You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: website/guide/project/lint-rule.md
+44-4Lines changed: 44 additions & 4 deletions
Original file line number
Diff line number
Diff line change
@@ -127,7 +127,7 @@ An example will be like this. The meta variable `$GREET` will be replaced both i
127
127
* `message` is a concise description when the issue is reported.
128
128
* `severity` is the issue's severity. See more in [severity](/guide/project/severity.html).
129
129
* `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.
131
131
132
132
### `files`/`ignores`
133
133
@@ -146,16 +146,56 @@ ignores:
146
146
- "tests/config/**"
147
147
```
148
148
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`.
152
150
153
151
:::warning Don't add `./`
154
152
155
153
Be sure to remove `./` to the beginning of your rules. ast-grep will not recognize the paths if you add `./`.
156
154
157
155
:::
158
156
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
+
159
199
## Ignore Linting Error
160
200
161
201
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:
Copy file name to clipboardExpand all lines: website/reference/yaml.md
+22Lines changed: 22 additions & 0 deletions
Original file line number
Diff line number
Diff line change
@@ -204,6 +204,28 @@ Example:
204
204
note: "Use a logger instead"
205
205
```
206
206
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.
0 commit comments