# ast-grep-skill

LLM-neutral skill for **AST-aware search and rewrite** across 25 languages. Wraps the [`ast-grep`](https://ast-grep.github.io/) (`sg`) CLI with offline pattern validation, the two-pass write trick, binary auto-resolution, and a per-OS installer.

Same shape as [`web-fetch`](https://github.com/code-yeongyu/web-fetch) and [`web-search`](https://github.com/code-yeongyu/web-search), packaged as a standalone skill that any Bash-capable agent (Claude Code, OpenCode, pi, hermes, openclaw) can load.

## Install

```bash
git clone https://github.com/code-yeongyu/ast-grep-skill ~/.agents/skills/ast-grep
bash ~/.agents/skills/ast-grep/install.sh        # installs the ast-grep binary
```

That is it. The wrapper script is single-file Python 3 stdlib; no `pip install` needed. The installer tries `brew` → `npm` → `cargo` → `pip` → `nix` → `mise` → GitHub release in priority order, picks the first that works, and falls back to a cached binary at `<skill>/bin/sg`.

### Symlink for active development

```bash
ln -s /path/to/your/clone ~/.agents/skills/ast-grep
```

### Other agents

- **Claude Code / OpenCode**: drop the directory under `~/.agents/skills/` (or `~/.config/opencode/skills/`) and the skill auto-registers via the `name` + `description` in `SKILL.md` frontmatter.
- **pi (`~/.senpi/agent`)**: not a `pi` extension — this is a skill. Pi consumes skills via `~/.agents/skills/` symlinks; the actual `pi-ast-grep` extension is at <https://github.com/code-yeongyu/pi-extensions>.
- **Direct CLI use**: `python3 ~/.agents/skills/ast-grep/scripts/ast_grep_helper.py <subcommand>`.

## Usage

```bash
# Search by AST pattern (the helper validates patterns offline first)
python3 scripts/ast_grep_helper.py search 'console.log($MSG)' --lang ts src/

# Rewrite (dry-run preview by default)
python3 scripts/ast_grep_helper.py replace 'console.log($MSG)' 'logger.info($MSG)' --lang ts src/

# Apply the rewrite (two-pass: preview JSON + then --update-all)
python3 scripts/ast_grep_helper.py replace 'console.log($MSG)' 'logger.info($MSG)' --lang ts src/ --apply

# Run YAML lint rules from sgconfig.yml
python3 scripts/ast_grep_helper.py scan src/

# Validate a pattern OFFLINE (no sg call, no filesystem)
python3 scripts/ast_grep_helper.py validate '\w+' --lang ts
# → exit 2: regex \w not supported. Use $VAR for identifiers.

# Doctor: check ast-grep binary availability
python3 scripts/ast_grep_helper.py doctor

# List 25 supported languages
python3 scripts/ast_grep_helper.py langs

# Install / re-install the ast-grep binary
python3 scripts/ast_grep_helper.py install
```

See [SKILL.md](./SKILL.md) for full agent-facing usage and the [`references/`](./references/) directory for deep dives.

## Project layout

```
ast-grep-skill/
├── SKILL.md                       agent-facing skill (loaded by Claude Code, OpenCode, pi, etc.)
├── README.md                      this file
├── LICENSE                        MIT
├── install.sh                     POSIX installer (macOS / Linux / WSL / Git Bash)
├── install.ps1                    Windows PowerShell installer
├── scripts/
│   └── ast_grep_helper.py         single-file Python 3 stdlib wrapper
├── references/
│   ├── install.md                 per-OS install methods + manual fallback
│   ├── patterns.md                meta-variables ($VAR, $$$) and pattern syntax
│   ├── pitfalls.md                regex anti-patterns + language-specific traps
│   ├── recipes.md                 copy-paste patterns by language (TS/JS/Py/Go/Rust/...)
│   ├── cli.md                     sg run / scan / test / new / lsp reference
│   ├── yaml-rules.md              YAML rule schema (atomic / relational / composite / transform / fix)
│   └── sgconfig.md                project configuration (ruleDirs, testConfigs, utilDirs)
├── tests/
│   ├── smoke.sh                   POSIX self-test
│   └── smoke.ps1                  PowerShell self-test (Windows CI)
└── .github/workflows/ci.yml       matrix CI: macos / ubuntu / windows × py 3.9-3.13
```

## What it does

1. **Wraps `sg`** with a single Python 3 stdlib script that works the same on macOS, Linux, Windows, WSL, Git Bash.
2. **Validates patterns offline** before calling `sg` — catches the regex-misuse class of mistakes (`\w`, `.*`, `|`, `[a-z]`) plus language-specific traps (Python trailing colons, JS/Go/Rust missing function bodies).
3. **Resolves the binary** through 6 candidate paths: cached → PATH (with Linux `setgroups` collision detection) → Homebrew. Falls through to a clear install hint with copy-paste commands.
4. **Runs the two-pass write trick** when applying rewrites — `sg run` silently ignores `--update-all` when `--json` is set, so `replace --apply` runs two invocations: pass 1 collects JSON matches, pass 2 mutates files.
5. **Ships per-OS installers** that try every reasonable package manager and fall back to a GitHub release tarball.
6. **Documents the failure modes** the model will hit (regex misuse, incomplete patterns, `--update-all` + `--json` trap, scope/type questions ast-grep can't answer) in `references/pitfalls.md`.

## What it does NOT do

- No type inference, scope analysis, or data flow. ast-grep is a structural matcher; for type-aware questions use TypeScript LSP, Pyright, Semgrep with type inference, or CodeQL.
- No multi-repo federation. Run the helper once per repo.
- No automatic `sgconfig.yml` discovery — it does what `sg scan` does (walk up from cwd looking for one).
- No JS/Python rewriter authoring environment — for that, write YAML rules and use `sg test` for snapshot testing (see [`references/yaml-rules.md`](./references/yaml-rules.md)).

## Limits

- 5-minute timeout per `sg` invocation (configurable in the helper).
- ast-grep itself supports 25 languages out-of-the-box. For anything else, use [`customLanguages`](./references/sgconfig.md#customlanguages-experimental) in `sgconfig.yml`.
- Pattern hint detection is heuristic; pass `--force` to skip validation when you know the pattern is correct.

## Requirements

- Python ≥ 3.9 (stdlib only — no pip install).
- `ast-grep` binary, installed via `install.sh` / `install.ps1` or one of:
  - `brew install ast-grep` (macOS / linuxbrew)
  - `npm install -g @ast-grep/cli` (any OS with Node)
  - `cargo install ast-grep --locked` (any OS with Rust)
  - `pip install ast-grep-cli` (any OS with Python)
  - `scoop install main/ast-grep` (Windows)

For older systems and Windows-specific setup, see [`references/install.md`](./references/install.md).

## Testing

```bash
bash tests/smoke.sh        # POSIX (macOS / Linux / WSL / Git Bash)
pwsh tests/smoke.ps1       # Windows (PowerShell 5.1+ or 7+)
```

CI runs the matrix on every push: `{macos-latest, ubuntu-latest, ubuntu-22.04, windows-latest}` × `{Python 3.9, 3.10, 3.11, 3.12, 3.13}` plus a syntax-floor check on Python 3.9 and 3.10.

## License

[MIT](./LICENSE).

## Acknowledgments

- [`omo` (oh-my-opencode)](https://github.com/code-yeongyu/oh-my-opencode) — `src/tools/ast-grep/` is the original tool implementation; this skill is a port of its pattern-hint detection and two-pass-write strategy.
- [`pi-extensions/pi-ast-grep`](https://github.com/code-yeongyu/pi-extensions) — sibling Node port; the helper's binary-resolution cascade is modelled on it.
- [ast-grep](https://github.com/ast-grep/ast-grep) — the CLI. All structural matching power comes from it.
- [Anthropic skills](https://docs.anthropic.com/en/docs/claude-code/skills) — the `SKILL.md` + `references/` packaging convention.