review-guards

/review-guards — turn review rules into guards

Goal: a review rule stated once should never depend on a reviewer's memory again. Mechanical rules become ast-grep guards (exit code decides); everything else becomes written guidance reviewers receive automatically.

1. Triage each rule

If a rule can't name a concrete AST shape, it is not an ast-grep rule.

2. Project setup (once)

sgconfig.yml          # ruleDirs: [.ast-grep/rules], testConfigs: [{testDir: .ast-grep/tests}]
.ast-grep/rules/      # one YAML per rule
.ast-grep/tests/      # one test per rule: valid + invalid snippets

Requires ast-grep on PATH (brew package, already in chezmoi packages).

3. Write each rule TDD-style

1. Write the test FIRST: .ast-grep/tests/<id>-test.yml with valid: (must not match) and invalid: (must match) snippets — the invalid one is the exact code from the review finding that motivated the rule.
2. Write .ast-grep/rules/<id>.yml: id, language, severity: error, message (say WHY, not just what), rule: (pattern/kind/inside…).
3. ast-grep test --skip-snapshot-tests — must print Running N tests with your test INCLUDED and pass. Pitfall: a test whose rule id does not exist is silently skipped (0 passed, exit 0) — the count is the proof the test ran. A wrong rule fails loudly (non-zero exit). Optionally pin snapshots with ast-grep test -U and drop the flag afterwards.
4. ast-grep scan on the repo: every existing hit is either fixed now or the rule's scope is narrowed — never ship a guard the codebase already violates.