Luigit
repositories / dotfiles

dotfiles

bugabingas dorkfiles

owned by admin

pi/agent/skills/ast-grep/SKILL.md

Raw
Rendered preview

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.

^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 <regex> / --type <kind> 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

^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 <language>; add --debug-query=ast when needed.
  • Complex relational queries → consult current rule docs, 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

---
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 <regex>` / `--type <kind>` 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 <language>`; 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)