ast-grep-rules

An opinionated set of ast-grep rules for Rust, TypeScript, Svelte, HTML, Python, Go, Pi extensions, and OpenCode plugins.

The rules catch API design problems, weak error handling, deprecated Svelte patterns, and code clutter. Pre-commit users can choose rules by language or run the whole set.

Install prek (recommended for faster installs and runs) or pre-commit. Both use the same .pre-commit-config.yaml.

Choose all to run every rule:

repos:
  - repo: https://github.com/joshuadavidthomas/ast-grep-rules
    rev: main
    hooks:
      - id: all

Set rev to a release tag when you want a fixed version. To select rule groups instead, list only the hooks the project needs:

repos:
  - repo: https://github.com/joshuadavidthomas/ast-grep-rules
    rev: main
    hooks:
      - id: pi
      - id: opencode

Language hooks include the shared checks for that language because shared rule IDs carry the same language prefix. For example, rust includes rust-no-code-barricade. Pi and OpenCode use product prefixes so each plugin ecosystem can run only its own rules.

With prek, install the Git hook and prepare its environment up front:

prek install --prepare-hooks
prek run all --all-files

The equivalent pre-commit commands are:

pre-commit install --install-hooks
pre-commit run all --all-files

Preparing the hook downloads an isolated Node.js environment, ast-grep, and the Svelte parser. Later runs reuse that environment. The project does not need Node.js or an sgconfig.yml.

Both tools scan tracked files. Add a new file to version control before expecting --all-files to include it. Rules with warning severity print findings without failing the hook; error rules fail it.

Pass ast-grep's --off option once for each rule:

repos:
  - repo: https://github.com/joshuadavidthomas/ast-grep-rules
    rev: main
    hooks:
      - id: rust
        args:
          - --off=rust-no-single-field-struct
          - --off=rust-no-visible-bool-argument

Install the tagged Git package in a project that uses Node.js 22, 24, or 26:

npm install --save-dev "github:joshuadavidthomas/ast-grep-rules#v0.6.0"
npx ast-grep-rules .

The command uses its packaged rules and configuration. Pass any ast-grep scan options after the command.

Install a maintained Node.js release (22, 24, or 26) and just, then install the pinned ast-grep CLI and Svelte parser:

npm install

Scan a project:

just scan /path/to/project

just scan also reports blanket suppressions and stale suppression comments. To run the rule tests:

just test

Install uv only if you need to audit the GitHub Actions workflows with Zizmor:

just lint

All rules link to their definitions. Most definitions include a note with exceptions and replacement advice.

The wrapper registers tree-sitter-svelte as an ast-grep custom language, so Svelte rules can match component and template nodes such as {#if} and {#each} blocks. It injects every <script> body as TypeScript so script rules also work with plain and lang="ts" blocks.

The parser installs without a compiler on glibc Linux x64, macOS x64 and arm64, and Windows x64. Linux arm64 and Windows arm64 or 32-bit x86 build the parser from source and need Python plus a native compiler. The pinned ast-grep CLI does not support other targets such as musl Linux.

1. Add the rule under rules/<prefix>-<rule-id>.yml.
2. Add valid and invalid examples under tests/<prefix>-<rule-id>-test.yml.
3. Run just test.
4. If the expected findings changed, run just test --update-all and review the snapshots in tests/__snapshots__/.
5. Add or update the rule in the reference above.

Use common- for files that contain rules for several languages and a language prefix such as rust- for files tied to one language. Start every rule ID with its language, such as rust-no-deny-warnings. Keep rule IDs stable, descriptive, and kebab-cased.

• rules/ contains the rule definitions.
• tests/ contains valid and invalid examples, generated snapshots, and a real .svelte scan test.
• sgconfig.yml defines the rules, tests, custom Svelte language, and script injection.
• bin/ast-grep-rules.mjs resolves the native parser, renders the config paths, and runs the pinned ast-grep CLI.
• .agents/skills/ast-grep/ contains the local agent guide for writing and debugging rules.

ast-grep-rules is licensed under the MIT license. See LICENSE for details.