ast-grep

name: ast-grep description: Use ast-grep (`sg`) for Python and Zig structural code exploration, mechanical codemods, and rule maintenance in this repo. Use this when you need syntax-aware search/replace (instead of regex), to add/update ast-grep rules in `tools/ast-grep/`, or to verify rule behavior with `sg scan` and `sg test`. For Zig, use `sgconfig.local.yml` so the custom parser is loaded.

Prefer sg for structural exploration and mechanical rewrites in Python/Zig code.

Quick Start

Run policy checks: sg scan
Run rule tests + snapshots: sg test
Run full local check chain: just check
For Zig parsing/local Zig rules: add -c sgconfig.local.yml

Structural Exploration

Use sg run with -p for ad-hoc structural queries.

Python examples:

sg run -l python -p 'config.data.get($$$ARGS)' src tests
sg run -l python -p 'except Exception: pass' src tests

Zig examples (must use local config):

sg run -c sgconfig.local.yml -l zig -p '@intFromFloat(@round(_DT * 1000.0))' crimson-zig/src
sg run -c sgconfig.local.yml -l zig -p 'const _NAME = _TYPE{};' crimson-zig/src

Zig metavariables use _VAR style in patterns (for example _EXPR, _TYPE).

Mechanical Codemods

Start narrow (single directory or file set).
Prototype match/rewrite:

sg run -l python -p 'config.data.get($$$ARGS)' -r 'config.get($$$ARGS)' src

Apply intentionally:

Interactive: add -i
Apply all matches: add -U

Review git diff and rerun sg scan and sg test.

For Zig typed-empty-init codemods, reuse the existing recipe:

just zig-z004-fix

Repo Rule Layout

Main config: sgconfig.yml
Main rules: tools/ast-grep/rules/
Main tests: tools/ast-grep/tests/
Local config: sgconfig.local.yml
Local rules: tools/ast-grep/rules-local/
Local tests: tools/ast-grep/tests-local/
Shared utils: tools/ast-grep/utils/

Rules are YAML files with id, language, severity, message, path scope (files/ignores), and rule matcher. Keep id, rule filename, and test filename aligned.

Repo Test Layout

Each test file mirrors a rule ID and includes:

valid: examples that must not match
invalid: examples that must match

Snapshot files live in __snapshots__/ beside tests and are checked by sg test.

Useful commands:

# all configured tests
sg test

# one rule by id regex
sg test -f no-config-data-get

# include local Zig tests/rules config
sg test -c sgconfig.local.yml

# refresh all snapshots after intentional rule changes
sg test -U

Repo Policy Notes

From CONTRIBUTING.md:

Prefer ast-grep over regex-only edits for structural transforms.
For Zig, use sgconfig.local.yml to load the custom parser.
When mistakes repeat, encode them as rules/tests/snapshots.