eko24ive/pi-config/pi-ast-grep

pi-ast-grep workflow

Use these tools to avoid reading huge files when a structural query can find the relevant code.

Prefer AST tools over grep-like tools when the user asks for code shape: calls to a function, imports from a module, declarations, classes, methods, control blocks, exports, or JSX-like elements. Use an available plain-text alternative for literal strings, comments, logs, config keys, prose, or when you cannot form a syntax-shaped query.

Preferred flow:

ast_outline / ast_change_index -> ast_search / ast_scan -> ast_fetch -> edit

For vague exploration, first locate candidate files if needed, then switch to ast_outline / ast_search once the target is structural.

Tool roles

• ast_outline: compact structure map for files/scoped paths; use before reading large source files when symbols matter.
• ast_search: structural search using ast-grep patterns or node kinds; prefer over text grep for calls/imports/declarations/classes/methods/blocks.
• ast_scan: native ast-grep YAML rule/config scanning from rule, inlineRules, explicit config, or cwd sgconfig.yml discovery.
• ast_fetch: bounded raw code for result ids or explicit file/range targets; include: ["ancestors"] adds a concise best-effort outline chain when available.
• ast_change_index: local/staged/branch changed-code index grouped by files/symbols where possible; use it to choose what to inspect, not to read patch diffs.
• ast_diff_file: bounded git diff for exactly one concrete file; use only after choosing a specific file. It rejects directories, globs, and project-root paths.
• ast_rewrite: structural rewrite; dry-run first, apply only with expectedMatches.

Pattern examples

Calls:

foo($$$ARGS)
readFileSync($$$ARGS)

Imports:

import { $NAME } from "$MOD"
import $NAME from "$MOD"

Functions/classes:

function $NAME($$$PARAMS) { $$$BODY }
class $NAME { $$$BODY }

Blocks:

if ($COND) { $$$BODY }
try { $$$BODY } catch ($ERR) { $$$HANDLER }

Use selector and strictness only as pattern modifiers, not with kind. Example: pattern: "foo($$$ARGS)", selector: "call_expression", strictness: "ast" to keep a call-shaped match focused.

Use beforeLines / afterLines for compact one-sided context in ast_search; use ast_fetch when editable code is needed.

JSX-like syntax is just syntax, not a React-specific workflow. Use only when the target language/files support it.

Language support

Language support depends on the local ast-grep installed for the session.

The extension normalizes common aliases and infers common file extensions when a single file language is clear. Explicit language is still useful for directory searches, ambiguous extensions, mixed-language paths, and parse errors.

Unknown or unsupported file types are passed through to ast-grep; zero-match results and failures should be treated cautiously because they can mean a language/inference problem rather than true absence.

Fallback rules

• Unknown file type: ast-grep sees it; use an available alternative or targeted read if results look suspicious.
• Pattern parse error: simplify the pattern and specify language.
• Zero matches: do not assume absence; check language, path/globs, inference, and whether this is actually text search.
• Stale id: re-run the source ast tool or pass explicit file/range to ast_fetch.
• Large changed-code result: narrow ast_change_index with paths, symbolKinds, maxFiles, or maxItems; do not switch to broad git diff or raise limits to read the whole patch.
• Large result: use nextCursor for ast_search/ast_scan/ast_outline result pagination, or narrow paths/globs/query. Cursor calls may include only paging/output params and return fresh fetchable ids. Cursors do not recover output truncated by maxBytes.

Safe rewrite workflow

1. Run ast_search first if unsure about match shape.
2. Run ast_rewrite with apply: false.
3. Inspect the diff.
4. Apply only with exact expectedMatches.
5. Validate with tests/typecheck/formatting as appropriate.

Never assume ast_rewrite is type-aware. It is syntax-aware only.