pi-ast-grep

name	pi-ast-grep
description	Use ast-grep as a default code-structure, structural-search, and structural-rewrite tool in Pi. Trigger when exploring code, reading large files, finding symbols/imports/calls/classes, doing AST-aware search, writing codemods, or using ast-grep outline/search/rewrite/scan.

Pi ast-grep

Use the ast-grep tools before falling back to broad file reads when structure matters.

Default moves

• Use ast_grep_outline before reading large source files or unfamiliar directories.
• Use ast_grep_search when rg would be noisy: function calls, imports, JSX tags, class declarations, AST kinds, nested syntax.
• Use ast_grep_rewrite for syntax-aware codemods. It defaults to preview diff; pass mode: "apply" when the rule is narrow and intentional.
• Use ast_grep_scan for reusable YAML rules, project sgconfig.yml, or codemod/lint checks. Use mode: "apply" for trusted rule fixes.
• Use ast_grep_test when creating or changing reusable YAML rules. Snapshot updates are explicit and should be reviewed like source edits.
• Use ast_grep_doctor if outline fails; the fleet package pins ast-grep 0.44.1.

Good patterns

• Start cheap: ast_grep_outline with view: "names" or view: "digest".
• Narrow before reading: add match, types, globs, or paths instead of dumping whole directories.
• For search/rewrite, prefer real code patterns like foo($$$ARGS) over vague regex when possible.
• Rewrite/apply is sharp, not forbidden: preview broad codemods, apply narrow codemods or trusted rule fixes, then inspect the returned diff and run checks.

Examples

• Need a map of a file: ast_grep_outline({ paths: ["src/file.ts"], view: "digest" })
• Need exported API shape: ast_grep_outline({ paths: ["src"], items: "exports", view: "names" })
• Need custom-language symbols: pass the project config or an outlineRules file; ast-grep 0.44.1 loads custom-language outline rules from config.
• Need machine-readable large outlines: use json: "stream"; 0.44.1 bounds the outline file queue and streams entries.
• Need function calls: ast_grep_search({ pattern: "Effect.gen($$$ARGS)", lang: "ts", paths: ["src"] })
• Need JSX components: ast_grep_search({ kind: "jsx_opening_element > identifier", lang: "tsx", paths: ["app"] })
• Need a codemod preview: ast_grep_rewrite({ pattern: "foo($A)", rewrite: "bar($A)", lang: "ts", paths: ["src"] })
• Need to apply it: ast_grep_rewrite({ pattern: "foo($A)", rewrite: "bar($A)", lang: "ts", paths: ["src"], mode: "apply" })
• Need to apply rule fixes: ast_grep_scan({ ruleFile: "rules/foo-to-bar.yml", paths: ["src"], mode: "apply" })
• Need to prove a rule: ast_grep_test({ testDirs: ["rule-tests"] })