pi-lens-ast-grep

AST-Grep Code Search

Use ast_grep_search and ast_grep_replace for semantic code search/replace. ast-grep understands code structure, not just text.

These tools (plus ast_grep_outline, lsp_navigation) are registered but inactive by default on hosts that support pi's dynamic tooling. If a call to one of them isn't recognized, activate it first: pi_lens_activate_tools tools=["ast_grep_search", "ast_grep_replace"].

On hosts that aggregate pi-lens behind a single lens tool, the ast_grep_* tools and pi_lens_activate_tools may not be registered at all. There, fall back to the ast-grep CLI (alias sg) — patterns, metavariables, and YAML rules are identical:

# search (≈ ast_grep_search)
ast-grep run -p 'fetchMetrics($$$ARGS)' -l ts src/

# rewrite (≈ ast_grep_replace; -U applies all)
ast-grep run -p 'var $X' -r 'let $X' -l js src/ -U

# full YAML rule (≈ the rule: parameter)
ast-grep scan --rule my-rule.yml src/

Structural-intent parameters map to YAML constraints: insideKind → inside: { kind: ..., stopBy: end }, hasKind/hasDescendantKind → has: { kind: ... }, follows → follows: { pattern: ... }, precedes → precedes: { pattern: ... }.

When to Use

• Function calls, imports, class methods (structured code)
• Safe replacements across files
• Use LSP first for: definitions/references/types — then scope ast-grep to files discovered by LSP
• Use grep for: partial string patterns, comments, URLs, or after one simplified ast-grep retry still returns zero matches

Golden Rules

1. Be specific — fetchMetrics($ARGS) not fetchMetrics
2. Scope it — always specify paths to relevant files
3. Retry once on zero matches — simplify the pattern, same paths, then fall back to grep
4. Dry-run first — apply: false before apply: true
5. Valid code only — function $NAME($$$) { $$$ } not function $NAME(
6. Avoid selector unless expert — narrows to AST node kind; does not extract metavariables
7. Metavariables don't work inside strings — from "$PATH" matches literal "$PATH", not a wildcard