Skip to content
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.

Commit fea7a4a

Browse files
committedMay 18, 2025··
doc: add docs about custom labels in rule config
fix #741
1 parent dc87f5f commit fea7a4a

File tree

2 files changed

+66
-4
lines changed

2 files changed

+66
-4
lines changed
 

‎website/guide/project/lint-rule.md

Lines changed: 44 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -127,7 +127,7 @@ An example will be like this. The meta variable `$GREET` will be replaced both i
127127
* `message` is a concise description when the issue is reported.
128128
* `severity` is the issue's severity. See more in [severity](/guide/project/severity.html).
129129
* `note` is a detailed message to elaborate the message and preferably to provide actionable fix to end users.
130-
130+
* `labels` is a dictionary of labels to customize error reporting's code highlighting.
131131

132132
### `files`/`ignores`
133133

@@ -146,16 +146,56 @@ ignores:
146146
- "tests/config/**"
147147
```
148148

149-
:::tip They work together!
150-
`ignores` and `files` can be used together.
151-
:::
149+
`ignores` and `files` can be used together. But `files` will take precedence over `ignores`.
152150

153151
:::warning Don't add `./`
154152

155153
Be sure to remove `./` to the beginning of your rules. ast-grep will not recognize the paths if you add `./`.
156154

157155
:::
158156

157+
## Customize Code Highlighting
158+
159+
ast-grep will report linting issues with highlighted code span called label. A label describes an underlined region of code associated with an issue. _By default, the matched target code and its surrounding code captured by [relational rules](/guide/rule-config/relational-rule.html)_.
160+
161+
ast-grep further allows you to customize the highlighting style with the configuration `labels` in the rule to provide more context to the developer. **`labels` is a dictionary of which the keys are the meta-variable name without `$` and the values ares label config objects.**
162+
163+
The label config object contains two fields: the required `style` and the optional `message`.
164+
* `style` specifies the category of the label. Available choices are `primary` and `secondary`.
165+
* `primary` describe the primary cause of an issue.
166+
* `secondary` provides additional context for a diagnostic.
167+
* `message` specifies the message to be displayed along with the label.
168+
169+
Note, a `label` meta-variable must have a corresponding AST node in the matched code because highlighting requires a range in the code for label. That is, the **label meta-variables must be defined in `rule` or `constraints`**. meta-variables in `transform` cannot be used in `labels` as they are not part of the matched AST node.
170+
171+
---
172+
173+
Let's see an example. Suppose we have a [rule](/playground.html#eyJtb2RlIjoiQ29uZmlnIiwibGFuZyI6ImphdmFzY3JpcHQiLCJxdWVyeSI6IiIsInJld3JpdGUiOiIiLCJzdHJpY3RuZXNzIjoic21hcnQiLCJzZWxlY3RvciI6IiIsImNvbmZpZyI6InJ1bGU6XG4gIHBhdHRlcm46XG4gICAgY29udGV4dDogJ2NsYXNzIEggeyAkTUVUSE9EKCkgeyAkJCQgfSB9J1xuICAgIHNlbGVjdG9yOiBtZXRob2RfZGVmaW5pdGlvblxuICBpbnNpZGU6XG4gICAgcGF0dGVybjogY2xhc3MgJENMQVNTIHsgJCQkIH1cbiAgICBzdG9wQnk6IGVuZCIsInNvdXJjZSI6ImNsYXNzIE5vdENvbXBvbmVudCB7XG4gICAgbmdPbkluaXQoKSB7fVxufSJ9) that matches method declaration in a class.
174+
175+
```yaml
176+
rule:
177+
pattern:
178+
context: 'class H { $METHOD() { $$$ } }'
179+
selector: method_definition
180+
inside:
181+
pattern: class $CLASS { $$$ }
182+
stopBy: end
183+
```
184+
Without label customization, ast-grep will highlight the method declaration (target), and the whole class declaration, captured by relational rule. We can customize the highlighting with `labels`:
185+
186+
```yaml
187+
labels:
188+
METHOD:
189+
style: primary
190+
message: the method name
191+
CLASS:
192+
style: secondary
193+
message: The class name
194+
```
195+
196+
Instead of highlighting the whole method declaration and class declaration, we are just highlighting the method name and class name. The `style` field specifies the highlighting style. The `message` field specifies the message to be displayed in the editor extension. See this post for a [demo](https://x.com/hd_nvim/status/1924120276939256154).
197+
198+
159199
## Ignore Linting Error
160200

161201
It is possible to ignore a single line of code in ast-grep's scanning. A developer can suppress ast-grep's error by adding `ast-grep-ignore` comment. For example, in JavaScript:

‎website/reference/yaml.md

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -204,6 +204,28 @@ Example:
204204
note: "Use a logger instead"
205205
```
206206

207+
### `labels`
208+
209+
* type: `HashMap<String, LabelConfig>`
210+
* required: false
211+
212+
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:
213+
* `style`: (required) the style of the label. Available choice: `primary`, `secondary`.
214+
* `message`: (optional) the message to be displayed in the editor extension.
215+
216+
Example:
217+
```yaml
218+
labels:
219+
ARG:
220+
style: primary
221+
message: "This is the argument"
222+
FUNC:
223+
style: secondary
224+
message: "This is the function"
225+
```
226+
227+
Please also see [label guide](/guide/project/lint-rule.html#customize-code-highlighting) for details.
228+
207229
## Globbing
208230

209231
### `files`

0 commit comments

Comments
 (0)
Please sign in to comment.