ast-grep-refactor

Files (8)

• SKILL.md
• examples.md · references/
• fix-expand.md · references/
• rewrite.md · references/
• rewriter.md · references/
• rule-basics.md · references/
• transform.md · references/
• troubleshooting.md · references/

SKILL.md (first lines)

# ast-grep Refactor

Use ast-grep to refactor by AST, not by text. Keep rules small, test on samples, then scale to the codebase.

## Quick workflow

1. Inspect AST for the target pattern.
2. Write a rule that matches only what you intend.
3. Dry-run on small files and review diffs.
4. Apply at scale only after review or tests.
5. Format and run checks.

```bash
ast-grep run --pattern '...' --lang <language> --debug-query=ast path/to/file
ast-grep scan -r rule.yml path/to/file
ast-grep scan -r rule.yml --update-all path/glob/**
```

Review matches via `ast-grep scan` output, `--interactive`, or `git diff` before `--update-all`.

## Decide the rule shape

- Use `pattern` for simple rewrites with metavariables.
- Use `kind` plus relational rules (`inside`, `has`, `nthChild`) for structural or positional changes.
- Use `fix` string for direct replacement; use `FixConfig` when you must remove punctuation or neighbors.
- Use `transform` to change captured strings; use `rewriters` to rewrite different subnodes differently.

## Rule files

- Separate multiple rules with `---`.
- Keep rules focused and composable.
- For repeatable or risky changes, add rule tests and run `ast-grep test`.

## References

- Rule basics and selection: `references/rule-basics.md`
- Rewrite and `fix`: `references/rewrite.md`
- FixConfig expansion: `references/fix-expand.md`
- Transformations: `references/transform.md`
- Rewriters: `references/rewriter.md`
- Troubleshooting: `references/troubleshooting.md`
- Examples: `references/examples.md`

## When to skip ast-grep

- Very small, one-off edits where manual editing is faster.
- Pure text replacement where AST structure does not matter.
- Changes requiring type-aware or semantic analysis.

## Links

- [ast-grep](https://github.com/ast-grep/ast-grep)

From seruman/pi-things, MIT.

More from seruman/pi-things