Configuration Reference
ast-grep's rules are written in YAML files.
One YAML file can contain multiple rules, separated by ---
.
An ast-grep rule is a YAML object with the following keys:
Basic Information
id
- type:
String
- required: true
Unique, descriptive identifier, e.g., no-unused-variable
.
Example:
id: no-console-log
language
- type:
String
- required: true
Specify the language to parse and the file extension to include in matching.
Valid values are: C
, Cpp
, CSharp
, Css
, Go
, Html
, Java
, JavaScript
, Kotlin
, Lua
, Python
, Rust
, Scala
, Swift
, Thrift
, Tsx
, TypeScript
Example:
language: JavaScript
Finding
rule
- type:
Rule
- required: true
The object specify the method to find matching AST nodes. See details in rule object reference.
rule:
pattern: console.log($$$ARGS)
constraints
- type:
HashMap<String, Rule>
- required: false
Additional meta variables pattern to filter matches. The key is matched meta variable name without $
. The value is a rule object.
Note, constraints only applies to the single meta variable like $ARG
, not multiple meta variable like $$$ARGS
. So the key name must only refer to a single meta variable.
Example:
rule:
pattern: console.log($ARG)
constraints:
ARG:
kind: number
# pattern: $A + $B
# regex: '[a-zA-Z]+'
constraints
is applied after rule
ast-grep will first match the rule
while ignoring constraints
, and then apply constraints
to filter the matched nodes.
Constrained meta-variables usually do not work inside not
.
utils
- type:
HashMap<String, Rule>
- required: false
A dictionary of utility rules that can be used in matches
locally. The dictionary key is the utility rule id and the value is the rule object. See utility rule guide.
Example:
utils:
match-function:
any:
- kind: function
- kind: function_declaration
- kind: arrow_function
Patching
transform
- type:
HashMap<String, Transformation>
- required: false
A dictionary to manipulate meta-variables. The dictionary key is the new variable name. The dictionary value is a transformation object or transformation string that specifies how meta var is processed.
Please also see transformation reference for details.
Example:
transform:
NEW_VAR_NAME: # new variable name
replace: # transform operation
source: $ARGS
replace: '^.+'
by: ', '
# string style for ast-grep 0.38.3+
transform:
NEW_VAR_NAME: replace($ARGS, replace='^.+', by=', ')
fix
- type:
String
orFixConfig
- required: false
A pattern or a FixConfig
object to auto fix the issue. See details in fix object reference.
It can reference meta variables that appeared in the rule.
Example:
fix: logger.log($$$ARGS)
# you can also use empty string to delete match
fix: ""
rewriters
- type:
Array<Rewriter>
- required: false
A list of rewriter rules that can be used in rewrite
transformation.
A rewriter rule is similar to ordinary YAML rule, but it ony contains finding fields, patching fields and id
.
Please also see rewriter reference for details.
Example:
rewriters:
- id: stringify
rule: { pattern: "'' + $A" }
fix: "String($A)"
# you can also use these fields
# transform, utils, constraints
Linting
severity
- type:
String
- required: false
Specify the level of matched result. Available choice: hint
, info
, warning
, error
or off
.
When severity
is off
, ast-grep will disable the rule in scanning.
Example:
severity: warning
message
- type:
String
- required: false
Main message highlighting why this rule fired. It should be single line and concise, but specific enough to be understood without additional context.
It can reference meta-variables that appeared in the rule.
Example:
message: "console.log should not be used in production code"
note
- type:
String
- required: false
Additional notes to elaborate the message and provide potential fix to the issue.
note
can contains markdown syntax, but it cannot reference meta-variables.
Example:
note: "Use a logger instead"
labels
- type:
HashMap<String, LabelConfig>
- required: false
A dictionary of labels to customize highlighting. The dictionary key is the meta-variable name without $
, defined in rules
or constraints
. The value is a label config object containing the following fields:
style
: (required) the style of the label. Available choice:primary
,secondary
.message
: (optional) the message to be displayed in the editor extension.
Example:
labels:
ARG:
style: primary
message: "This is the argument"
FUNC:
style: secondary
message: "This is the function"
Please also see label guide for details.
Globbing
files
- type:
Array<String>
- required: false
Glob patterns to specify that the rule only applies to matching files. It is tested if ignores
does not exist or a file does not match any ignores
glob.
Example:
files:
- src/**/*.js
- src/**/*.ts
Don't add ./
Be sure to remove ./
to the beginning of your rules. ast-grep will not recognize the paths if you add ./
.
ignores
- type:
Array<String>
- required: false
Example:
ignores:
- test/**/*.js
- test/**/*.ts
Glob patterns that exclude rules from applying to files. A file is tested against ignores
list before matching files
.
A typical globing process works as follows:
- If
ignores
is configured, a file will be skipped if it matches any of the glob in the list(files
will not be tested). - If
files
is configured, a file will be included if and only if it matches one of the glob in the list. - If neither
ignores
/files
is configured, a file is included by default.
ignores
in YAML is different from --no-ignore
in CLI
ast-grep respects common ignore files like .gitignore
and hidden files by default. To disable this behavior, use --no-ignore
in CLI. ignores
is a rule-wise configuration that only filters files that are not ignored by the CLI.
Other
url
- type:
String
- required: false
Documentation link to this rule. It will be displayed in editor extension if supported.
Example:
url: 'https://ast-grep.github.io/catalog/python/#migrate-openai-sdk'
metadata
- type:
HashMap<String, String>
- required: false
Extra information for the rule. This section can include custom data for external program to consume. For example, CVE/OWASP information can be added here for security research.
ast-grep will output metadata
with matches in --json
mode if --include-metadata
is on.
Example:
metadata:
extraField: 'Extra information for other usages'
complexData:
key: value