feat(res-to-affine): tree-sitter AST walker for side-effect-import (Phase 2b, Refs #57)

[hyperpolymath]

Summary

Lands the first AST-based detection pass on top of the Phase-2a grammar build pipeline (#321). New module tools/res-to-affine/walker.ml shells out to the vendored tree-sitter CLI, parses its default s-expression output (with embedded [row, col] byte ranges), and walks the AST to find the side-effect-import anti-pattern structurally rather than via the column-0-anchored regex Phase 1 uses.

Detection upgrade vs. Phase 1

The walker flags let _ = Mod.value only when the binding sits at module top level — direct child of source_file, or direct child of a block that is the body of a module_declaration. The Phase-1 regex matches any column-0 occurrence of the same shape.

On the existing sample.res fixture the walker reports 1 finding (the intended top-level let _ = Pixi.Sound.register on line 8); the scanner reports the same 1 plus the same shape nested inside function bodies. The regex pattern that #319 band-aided with column-0 anchoring is eliminated structurally by the walker.

$ dune exec tools/res-to-affine/main.exe -- \
    --engine=scanner tools/res-to-affine/test/fixtures/sample.res \
    | grep -E "^//\s+- "
//   - [side-effect-import] line 8: ...
//   - [raw-js] line 11: ...
//   - [mutable-global] line 15: ...
//   - [untyped-exception] line 19: ...
//   - [untyped-exception] line 22: ...
//   - [untyped-exception] line 28: ...

$ dune exec tools/res-to-affine/main.exe -- \
    --engine=walker tools/res-to-affine/test/fixtures/sample.res \
    | grep -E "^//\s+- "
//   - [side-effect-import] line 8: ...

(Walker covers only side-effect-import in 2b — the other three anti-patterns are scanner-only until 2c.)

CLI

• --engine={scanner,walker} — default scanner, preserves Phase-1 behaviour.
• --grammar-dir DIR — override walker's parser location (default: tools/vendor/tree-sitter-rescript, matches install.sh output).
• On any walker error (grammar missing, tree-sitter not on PATH, s-exp parse failure), the binary prints a one-line reason to stderr and falls back to the scanner — never bails for walker problems.

Walker design

• Subprocess to tree-sitter, not in-process FFI. The migration assistant runs once per file; subprocess overhead is negligible against the actual parse cost. Sidesteps OCaml↔C bindings entirely.
• Hand-rolled s-exp parser (~150 LOC) handles the tree-sitter default output format: paren-delimited nodes with [row, col] byte ranges and optional field: prefixes per child.
• stderr suppression. tree-sitter 0.26+ emits a benign "You have not configured any parser directories!" warning on every invocation regardless of how the parser is resolved (we use the cd grammar_dir trick, not its config file). The walker redirects stderr to /dev/null; errors that matter still surface via the exit code.
• Stable public surface: Walker.scan : grammar_dir:string -> path:string -> source:string -> Scanner.finding list. Phase 2c extends rather than re-architects.

Tests

test/test_walker.ml adds two end-to-end tests under a new res-to-affine-walker alcotest run. Both auto-skip if tree-sitter is missing or the vendored grammar hasn't been built, so dune runtest on a fresh clone (no bootstrap) still passes.

Repo-root discovery walks up from the test cwd looking for dune-project — necessary because the dune sandbox hides the source-tree tools/vendor/ from naive relative-path math.

CI

• The existing build job now installs tree-sitter-cli (npm, fast — pre-built binary, ~5 s) and runs install.sh before dune runtest, so the walker tests actually execute rather than auto-skip.
• The migration-assistant job added in feat(res-to-affine): land tree-sitter grammar build pipeline (Phase 2a, Refs #57) #321 stays — it remains the dedicated first-signal job for grammar-pin drift, independent of the OCaml build.

What is NOT in this PR

• raw-js, untyped-exception, mutable-global walker ports → Phase 2c.
• inline lambda callback record, oversized function (the two anti-patterns deferred from Phase 1 entirely) → Phase 2c.
• Switching --engine=walker to default → Phase 2c, after the four anti-patterns reach parity.

Stack

#321 (Phase 2a) → this PR (Phase 2b) → Phase 2c

Base is main per the orphan-trap guidance, so the diff is cumulative until #321 lands, then this rebases.

Test plan

• CI green — the build job now runs walker tests; the migration-assistant job still validates the grammar build.
• Local: just install-grammar && dune runtest tools/res-to-affine/ reports both walker tests [OK] (verified).
• Local: --engine=walker on sample.res produces exactly the line-8 side-effect-import finding (verified).

🤖 Generated with Claude Code