Rule Cheat Sheet

This cheat sheet provides a concise overview of ast-grep's rule object configuration, covering Atomic, Relational, and Composite rules, along with notes on Utility rules. It's designed as a handy reference for common usage.

Atomic Rules Cheat Sheet

These are your precision tools, matching individual AST nodes based on their inherent properties.

⚛️ Atomic Rules
pattern: console.log($ARG)	🧩 Match a node by code structure. e.g. console.log call with a single $ARG
pattern: context: '{ key: value }' selector: pair	🧩 To parse ambiguous patterns, use context and specify selector AST to search.
kind: if_statement	🏷️ Match an AST node by its kind name
regex: ^regex.+$	🔍 Matches node text content against a Rust regular expression
nthChild: 1	🔢 Find a node by its 1-based index among its named siblings
nthChild: position: 2 reverse: true ofRule: { kind: argument_list }	🔢 Advanced positional control: position, reverse (count from end), or filter siblings using ofRule
range: start: { line: 0, column: 0 } end: { line: 0, column: 13 }	🎯 Matches a node based on its character span: 0-based, inclusive start, exclusive end

Relational Rules Cheat Sheet

These powerful rules define how nodes relate to each other structurally. Think of them as your AST GPS!

🔗 Relational Rules
inside: kind: function_declaration	🏠 Target node must appear inside its parent/ancestor node matching the sub-rule
has: kind: method_definition	🌳 Target node must have a child/descendant node matching the sub-rule
has: kind: statement_block field: body	🌳 field makes has/inside match nodes by their semantic role
precedes: pattern: function $FUNC() { $$ }	◀️ Target node must appear before another node matching the sub-rule
follows: pattern: let x = 10;	▶️ Target node must appear after another node matching the sub-rule.
inside: kind: function_declaration stopBy: end	🏠 stopBy makes relational rules search all the way to the end, not just immediate neighbors.

Composite Rules Cheat Sheet

Combine multiple rules using Boolean logic. Crucially, these operations apply to a single target node!

🧠 Composite Rules
all: - pattern: const $VAR = $VALUE - has: { kind: string_literal }	✅ Node must satisfy ALL the rules in the list.
any: - pattern: let $X = $Y - pattern: const $X = $Y	🧡 Node must satisfy AT LEAST ONE of the rules in the list.
not: pattern: console.log($$)	🚫 Node must NOT satisfy the specified sub-rule.
matches: is-function-call	🔄 Matches the node if that utility rule matches it. Your gateway to modularity!

Utility Rules Cheat Sheet

Define reusable rule definitions to cut down on duplication and build complex, maintainable rule sets.

📦 Utility Rules
rules: - id: find-my-pattern rule: matches: my-local-check utils: my-local-check: kind: identifier regex: '^my'	🏡 Defined within the utils field of your current config file. Only accessible within that file.
# In utils/my-global-check.yml id: my-global-check language: javascript rule: kind: variable_declarator has: kind: number_literal	🌍 Defined in separate YAML files in global utilsDirs folders, accessible across your entire project.