Skip to content

refactor(guards, rules, ansi_c): split the parsers, decisions pinned and unchanged - #61

Merged
blockmandev merged 4 commits into
mainfrom
refactor/shell-rules-parsers
Oct 23, 2026
Merged

blockmandev merged 4 commits into
mainfrom
refactor/shell-rules-parsers

Conversation

@blockmandev

Copy link
Copy Markdown
Member

Answers the code-auditor findings on the three parsers that decide what an agent's shell command may do: guards::shell (protected-path lexer), permissions::rules (allow/ask/deny splitter), ansi_c ($'…' decoder).

Two commits

  1. tests: pin … decisions before refactor (green on the original code). It adds src/parser_pins.rs and three pinned_tests modules, with recordings in tests/pinned/:
    • 267 curated command lines: every input of the modules' own tests, plus quotes, $'…', escapes, heredocs, redirects with and without spaces, ; && | &, subshells, backticks, $(…), comments, unicode, empty and unterminated input, and nesting past both depth limits. Each one is recorded in full.
    • 4050 generated pairs of 45 fragments, joined with a space and without one. These are recorded as one FNV-1a digest per first fragment.
    • What gets recorded for each line. Shell: the write targets, plus the tokens, heredoc bodies and substitutions of both $' readings. Rules: the segments (text, opacity, peeled forms), words, the unquoted line, and the verdicts of two rule sets. ansi_c: 1048 decodes, each with its decoded text and end index.
  2. refactor: no decision changes. The recordings and every existing test pass unchanged, and the pinned test files are pure renames (100% similarity).
    • guards/shell/{mod,lex,program}.rs:
      • lex now loops over Lexer::step, which calls one method per construct.
      • Lexer::substitution is split into delimiters, substitution_end, skipped and past_quoted_span.
      • collect_reading is split into pipeline, redirect and heredoc helpers.
    • permissions/rules/{mod,rule,path,split,peel,set}.rs:
      • The public API is re-exported from mod.rs, so no caller changes.
      • split_reading now drives a Splitter state machine, and substitution is split into backtick and ParenScan bracket scans.
      • The existing tests moved verbatim into rules/tests/{mod,commands,paths,layers}.rs.
    • ansi_c::decode hands each escape to escape, hex or named.
    • Each new submodule has a few focused unit tests (13 added).

Measured

  • Every file is ≤ 565 lines, and the longest function is 57 lines.
  • The auditor's static check reports no complexity or length violation in the touched files.
  • Fan-out:
    • shell went from 140 to 72 / 62 / 39.
    • rules went from 281 to at most 78 per file.
    • rules_tests went from 59 to at most 35.
    • ansi_c.rs stays a single 235-line, single-purpose file, so its fan-out (27 → 32) was not contorted for a name count.
  • Local gate on Windows: cargo fmt --check, cargo clippy --all-targets -- -D warnings and cargo test are green. The lib suite went from 2258 on main to 2274: 3 pinned tests and 13 unit tests added, none removed.

…ore refactor

Records what the three parsers that decide what an agent's shell command may
do make of a broad corpus, computed by the current code, so restructuring them
cannot change a decision unnoticed:

- guards::shell: write targets, and the lexer's tokens, heredoc bodies and
  substitutions under both readings of `$'`
- permissions::rules: segments (text, opacity, peeled forms), words, unquoted
  line, and the verdicts of two rule sets
- ansi_c: decoded text and end index of every body, at four start offsets

Corpus: 267 curated command lines (every input of the modules' own tests,
plus quotes, `$'...'`, escapes, heredocs, redirects with and without spaces,
operators, subshells, substitutions, comments, unicode, empty, unterminated,
and nesting past the depth limits) recorded in full, and 4050 generated
pairs of 45 fragments recorded as FNV-1a digests per group; 1048 ansi_c
readings. Recordings in tests/pinned/, compared line by line.
…and unchanged

Behaviour-preserving: the pinned recordings from the previous commit (made on
the original code) and every existing test pass unchanged.

- guards::shell -> shell/{mod,lex,program}.rs. `lex` is a loop over
  `Lexer::step`, which dispatches to one method per construct (quotes,
  escapes, `$`, pipes, `&`, redirects, heredocs); `Lexer::substitution` is
  split into delimiters / substitution_end / skipped / past_quoted_span;
  `collect_reading` into pipeline_targets / redirect_targets /
  heredoc_targets / every_word.
- permissions::rules -> rules/{mod,rule,path,split,peel,set}.rs, public API
  re-exported from mod.rs so no caller changes. `split_reading` drives a
  `Splitter` with one method per quote state and construct; `substitution`
  is split into backtick and bracket scans (`ParenScan`). The existing tests
  moved verbatim into rules/tests/{mod,commands,paths,layers}.rs.
- ansi_c `decode` delegates each escape to escape / hex / named.
- Each new submodule gets focused unit tests of its own (13 added).

Every file is under 1000 lines, the longest function is 57 lines, and the
auditor's static check reports no complexity or length violation in them.
…ions

Closes two gaps in the pinned corpus. Every new recording was made on the
original code (be10301, in a temporary worktree), passed there, and is
brought over byte-identical; it passes unchanged on the refactor.

- Nesting (parser_pins::nesting, 43 cases, read by both the guard and the
  rules): quoted `bash -c "…"`, `sh -c '…'`, `eval '…'`, `$(…)`, heredocs
  fed to `sh`, and mixtures, at depths 1/5/7/8/9/10/12/16 with writes at the
  innermost level, so the readers really recurse into and past MAX_DEPTH.
  Recorded as size and digest of the input, targets (count, digest, whether
  the innermost writes are among them) or parts and verdicts in full.
- Rule sets (rules::pinned_set_tests, 319 lines): Rule::parse with and
  without a home (39 rules), the tools 12 rules name, 16 path patterns over
  28 paths, normalise (36), domain rules over 18 URLs, a project's ignored
  allow list, deny_everything, the deny/ask/allow order across the managed,
  user and project layers in both add orders (162), and an Allowlist.
  Inputs are lower case without drive letters in matched paths, so the
  recording holds on every platform.
- parser_pins gets unit tests of its own: the quoting of each nesting level,
  the case list, and the platform-stable digest and escape.
The split moved the pipeline walk out of collect_reading into
pipeline_targets (mod.rs:110), but program_of's doc still named
collect_reading. Found by the independent review of #61; comment only.
@blockmandev
blockmandev merged commit fedb944 into main Oct 23, 2026
12 checks passed
@blockmandev
blockmandev deleted the refactor/shell-rules-parsers branch November 15, 2026 20:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant