tool-ast-grep-rules

ast-grep Rule Crafter

ast-grep uses tree-sitter to parse code into AST, enabling precise pattern matching. Rules are defined in YAML for linting, searching, and rewriting code.

Quick Start

id: no-console-log
language: JavaScript
rule:
  pattern: console.log($$$ARGS)
fix: logger.log($$$ARGS)
message: Replace console.log with logger

Project Configuration

Project-level scanning requires an sgconfig.yml configuration file:

# sgconfig.yml (project root)
ruleDirs:
  - rules          # Rule directory, recursively loads all .yml files

Typical project structure:

my-project/
├── sgconfig.yml
├── rules/
│   ├── no-console.yml
│   └── custom/
│       └── team-rules.yml
└── src/

Running project scan:

ast-grep scan              # Automatically finds sgconfig.yml
ast-grep scan --config path/to/sgconfig.yml  # Specify config

Note: ast-grep scan command requires sgconfig.yml, while ast-grep run -p can be used standalone.

Rule Workflow

Lint Rule (Common)

Check only without fixing, used for CI/editor hints:

# rules/no-console-log.yml
id: no-console-log
language: JavaScript
severity: warning
message: Avoid console.log in production code
rule:
  pattern: console.log($$$ARGS)

Verify:

ast-grep scan -r rules/no-console-log.yml src/

Rewrite Rule (Optional)

Add fix when auto-fix is needed:

id: no-console-log
language: JavaScript
severity: warning
message: Replace console.log with logger
rule:
  pattern: console.log($$$ARGS)
fix: logger.log($$$ARGS)

Apply fix:

ast-grep scan -r rules/no-console-log.yml --update-all src/

Development Workflow

- [ ] 1. Explore pattern with CLI: ast-grep -p 'pattern' src/
- [ ] 2. Create rule file (.yml)
- [ ] 3. Verify: ast-grep scan -r rule.yml src/
- [ ] 4. If false positives → add constraints → re-verify

Debug AST structure:

ast-grep -p 'console.log($ARG)' --debug-query ast

Essential Syntax