tool-ast-grep-rules

📁 heyvhuang/ship-faster 📅 3 days ago

总安装量

周安装量

安装命令

npx skills add https://github.com/heyvhuang/ship-faster --skill tool-ast-grep-rules

Agent 安装分布

trae 1

cursor 1

kiro-cli 1

claude-code 1

antigravity 1

gemini-cli 1

Skill 文档

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

Element	Syntax	Example
Single node	`$VAR`	`console.log($MSG)`
Multiple nodes	`$$$ARGS`	`fn($$$ARGS)`
Same content	Use same name	`$A == $A`
Non-capturing	`$_VAR`	`$_FN($_FN)`

Core Rules Quick Reference

Type	Purpose	Example
`pattern`	Match code structure	`pattern: if ($COND) {}`
`kind`	Match AST node type	`kind: function_declaration`
`all`	Match ALL conditions	`all: [pattern: X, kind: Y]`
`any`	Match ANY condition	`any: [pattern: var $A, pattern: let $A]`
`not`	Exclude matches	`not: {pattern: safe_call()}`
`has`	Must have child	`has: {kind: return_statement}`
`inside`	Must be in ancestor	`inside: {kind: class_body}`

Detailed References

Complete syntax guide: See rule-syntax.md

Atomic rules (pattern, kind, regex, nthChild, range)
Composite rules (all, any, not, matches)
Relational rules (has, inside, follows, precedes)
Transform and fixConfig

Language-specific patterns: See common-patterns.md

JavaScript/TypeScript examples
Python examples
Go and Rust examples

Supported Languages

Bash, C, Cpp, CSharp, Css, Elixir, Go, Haskell, Hcl, Html, Java, JavaScript, Json, Kotlin, Lua, Nix, Php, Python, Ruby, Rust, Scala, Solidity, Swift, Tsx, TypeScript, Yaml

GitHub 仓库 ↗ ← 返回陌讯 Skills 聚合平台