--- name: ast-grep description: "Use for compact code outlines, declarations, imports/exports, direct members, or syntax-aware pattern searches with ast-grep; not plain literal text search." compatibility: "Requires ast-grep CLI; outline support varies by installed version." --- # ast-grep Inspect syntax on demand; no index, LSP, rewrites, or semantic call-graph claims. ## Before querying - Prefer normal text search for exact strings, comments, documentation, or filenames. - Check `ast-grep --version` and the needed subcommand's `--help`; installed help wins over newer web docs. - Missing binary/subcommand → report unavailable capability; use text search or source reads, without installing or upgrading. - Scope to candidate files/subdirectory first; retain default ignore/symlink boundaries. Narrow noisy output before expanding scope; label truncated results as partial. ## Outline first Run from the target project's working directory; let ast-grep discover its project configuration normally. ```nu ^ast-grep outline --items structure --view names src/ ^ast-grep outline --items structure --view expanded src/client.ts ^ast-grep outline --items imports --view signatures src/client.ts ^ast-grep outline --items exports --view signatures src/ ``` - Directory defaults show exports only; explicitly choose `structure` when internal declarations matter. - `--match ` / `--type ` filter top-level items, not members. To locate a method, expand its containing declaration or use structural search. - Open only relevant source ranges after locating declarations. Outlines describe extracted syntax, not every possible construct or runtime dependency. ## Structural search ```nu ^ast-grep run --lang ts --pattern 'console.log($$$ARGS)' --color never src/ ``` - Single-quote patterns to preserve dollar signs. `$NAME` matches one named AST node; `$$$ARGS` matches zero or more nodes. Call-shaped patterns exclude comment/string lookalikes and tolerate formatting changes. - Match syntax in its actual grammar; do not treat patterns as regex or identifier matches as resolved references. - Unexpected zero hits → check scope, language, argument count, and pattern shape. Test a minimal known-positive snippet through `--stdin --lang `; add `--debug-query=ast` when needed. - Complex relational queries → consult current [rule docs](https://ast-grep.github.io/guide/rule-config/relational-rule.html), rather than guessing traversal boundaries. - Stay read-only: no `--rewrite`, `--update-all`, or interactive edits under this skill. ## Report evidence - Report each declaration or match with file:line evidence; prefer compact text, using `--json=compact` only for structured processing. JSON positions are zero-based; add one when presenting human line numbers. - Inspect exit status and stderr: `run` uses 1 for no matches; `outline` can succeed with no selected entries. Read/config/parser failures are not evidence of absence, even with exit 0. In Nushell, inspect expected nonzero results with `^ast-grep ... | complete | to json` so `stdout`, `stderr`, and `exit_code` remain visible. Run error probes separately instead of hiding nested records or chaining commands that may stop early. - State scope and limitations; never promote syntactic imports or same-named calls into verified dependencies/callers. ## Sources - [Outline CLI](https://ast-grep.github.io/reference/cli/outline.html) - [Search CLI](https://ast-grep.github.io/reference/cli/run.html) - [Pattern syntax](https://ast-grep.github.io/guide/pattern-syntax.html)