feat(when): expose shell.loop_kind for matching commands inside shell loops

[fohte]

Purpose

• Polling loops of the form until cmd; do sleep N; done should be deniable from a when clause, but runok currently exposes no way to tell that a sleep runs inside a loop, so a rule cannot distinguish a polling sleep from a standalone one
  • Even when a deterministic alternative exists (gh pr checks --watch, kubectl wait, ...), the only rule that can block the polling form today is a blanket deny on sleep N, which also blocks the legitimate standalone sleep calls that have to keep working

Approach

• Stamp every extracted sub-command with the kind of shell loop that immediately encloses it, and expose that value to CEL as shell.loop_kind
  • Values: "while", "until", "for", or "" when the command is not inside any loop
  • Nested loops surface the nearest enclosing kind (sleep in for x in a b; do until y; do sleep 1; done; done reports "until")
  • Subshells do not reset the kind (sleep in (while x; do sleep 1; done) still reports "while")
  • Substitutions that evaluate once before the loop body keep loop_kind = "", whether bare or quoted (for i in $(cmd); do ...; done and for i in "$(cmd)"; do ...; done both report "" for cmd)
• Example usage:

  rules:
    - deny: 'sleep *'
      when: 'shell.loop_kind in ["while", "until"]'
      message: 'Polling loops are fragile. Use --watch / wait flags or a native polling command instead.'
    - allow: 'sleep *'

Design decisions

CEL surface shape

Decision	Design	Pros	Cons
Chosen	shell.loop_kind: string, with "" as the loop-outside sentinel	Matches the existing flat-map style of pipe.stdin etc.; in [...] works without has() gating	Users have to learn that "" means "outside any loop"
Rejected	Pair a shell.in_loop: bool field with the string	in_loop reads naturally for the common case	Redundant with loop_kind != ""; adds a field without enabling anything new
Rejected	Make loop_kind nullable and check it with has(shell.loop_kind)	Lets users rely on CEL's built-in absence check	Diverges from the existing flat-map contexts (pipe.*, redirects[].*) that already use sentinel values rather than nullability

Loop kind for value-list substitutions

Decision	Design	Pros	Cons
Chosen	cmd in for i in $(cmd); do ...; done reports loop_kind = ""	Matches bash evaluation order (the value list runs once before the loop body); bare $(cmd) and quoted "$(cmd)" agree	Users who want to treat a value-list substitution as "loop-internal" need a different way to express that
Rejected	Bare $(cmd) reports loop_kind = "for", quoted "$(cmd)" reports ""	Picks up the substitutions that appear as direct AST children of the for-statement	Behaviour splits across quoting, which is confusing for rule authors writing semantically identical commands

[codecov]

Codecov Report

❌ Patch coverage is 90.52632% with 9 lines in your changes missing coverage. Please review.
✅ Project coverage is 89.05%. Comparing base (9dd0e7d) to head (5f7ced5).

Files with missing lines	Patch %	Lines
src/rules/command_parser.rs	89.28%	6 Missing ⚠️
src/rules/rule_engine.rs	90.47%	2 Missing ⚠️
src/adapter/mod.rs	91.66%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #345      +/-   ##
==========================================
- Coverage   89.07%   89.05%   -0.02%     
==========================================
  Files          53       53              
  Lines       12657    12731      +74     
==========================================
+ Hits        11274    11338      +64     
- Misses       1383     1393      +10     

Flag	Coverage Δ
Linux	88.88% <90.52%> (-0.01%)	⬇️
macOS	90.19% <90.52%> (-0.01%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[gemini-code-assist]

Code Review

This pull request introduces a new shell.loop_kind CEL variable to detect shell loops (while, until, for) within when clauses. This feature allows users to distinguish between polling loops and standalone commands, enabling more granular rule enforcement, such as denying sleep inside a loop while permitting it elsewhere. The implementation includes updates to the command parser, rule engine, and expression evaluator to propagate and expose this context, supported by comprehensive documentation and new integration tests. The reviewer correctly identified that the TODO(pr-link) placeholder in the release notes must be resolved before merging.