tools-ast-grep

ast-grep

ast-grep matches code by its syntax tree, so a pattern survives reformatting, whitespace, and comments that defeat grep. It is the cheapest way to answer "does this pattern exist where it shouldn't?" with a precise file:line list.

Evidence dimension: structural. Output is a concrete evidence ref per match.

When to use

Use when a finding hypothesis is a structural code pattern: "domain code imports the ORM directly," "routes are declared outside the router module," "this framework type leaks past the boundary," or "a module exports too much surface." ast-grep confirms presence/absence with line-anchored hits. Use it before claiming a boundary is bypassed — a claim about a pattern needs the matched lines.

Commands

Run from the repo root. -l sets language; -p is an inline pattern; --json gives machine-readable hits for counting.

# Imports of a specific package (TS/JS)
ast-grep -l ts -p 'import $$$ from "typeorm"'

# Direct DB access leaking into a layer (scope with a path)
ast-grep -l ts -p 'createConnection($$$)' src/domain

# Exported symbols (surface-area survey)
ast-grep -l ts -p 'export $$$'

# Route declarations outside the router (framework leak)
ast-grep -l ts -p 'app.$METHOD($PATH, $$$)'

# Framework type used past the boundary (Python example)
ast-grep -l python -p 'Request' src/core

# Count hits without dumping every match
ast-grep -l go -p 'sql.Open($$$)' --json | jq length

For reusable, named rules (relational metavariable constraints, inside, not), put them in a YAML rule file and run ast-grep scan -r rule.yml. See references/rules.md for the rule patterns this review relies on.

Evidence output

Record:

• dimension: structural.
• source: ast-grep command, language, pattern/rule file, searched scope, and version when parser behavior is in doubt.
• facts: matched file:line refs or confirmed zero-match scope.
• limits: parse errors, unsupported language, regex fallback, or lack of semantic reachability.