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

Rule kind	Destination
Structural / mechanical ("no console.log outside logger", "every handler calls auth middleware", "no raw SQL in controllers")	ast-grep rule
Type-aware or flow-sensitive	existing linter / tsc config — do NOT emulate a type checker with patterns
Qualitative (naming taste, architecture judgement)	REVIEW_GUIDELINES.md in repo root — the /review extension and review subagents pick it up

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.