Skip to content

Commit 465249c

Browse files
HerringtonDarkholmeHerringtonDarkholme
committed
doc: move severity / rule suppression to a standalone page
fix #634
1 parent 67c21b1 commit 465249c

File tree

3 files changed

+123
-21
lines changed

3 files changed

+123
-21
lines changed

‎website/.vitepress/config.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -90,6 +90,7 @@ export default defineConfig({
9090
{ text: 'Project Configuration', link: '/guide/project/project-config.html' },
9191
{ text: 'Lint Rule', link: '/guide/project/lint-rule.html' },
9292
{ text: 'Test Your Rule', link: '/guide/test-rule.html' },
93+
{ text: 'Error Report', link: '/guide/project/severity.html' },
9394
],
9495
},
9596
{ text: 'Rewrite Code', link: '/guide/rewrite-code.html', collapsed: true,

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

Lines changed: 4 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -125,7 +125,7 @@ An example will be like this. The meta variable `$GREET` will be replaced both i
125125
## Other Linting Fields
126126

127127
* `message` is a concise description when the issue is reported.
128-
* `severity` is the issue's severity.
128+
* `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.
130130

131131

@@ -158,32 +158,15 @@ Be sure to remove `./` to the beginning of your rules. ast-grep will not recogni
158158

159159
## Ignore Linting Error
160160

161-
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` above the line that triggers the issue.
162-
163-
The suppression comment has the following format:
161+
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:
164162

165163
```javascript
166164
// ast-grep-ignore
167165
// ast-grep-ignore: <rule-id>, <more-rule-id>
168166
```
169167

170-
* A comment with the content `ast-grep-ignore` will suppress the following line's diagnostic.
171-
* The magic word `ast-grep-ignore` alone will suppress _all_ kinds of diagnostics.
172-
* `ast-grep-ignore: <rule-id>` can turn off specific rules.
173-
* You can turn off multiple rules by providing a comma-separated list in the comment. e.g. `ast-grep-ignore: rule-1, rule-2`
174-
175-
See the [playground](https://ast-grep.github.io/playground.html#eyJtb2RlIjoiQ29uZmlnIiwibGFuZyI6ImphdmFzY3JpcHQiLCJxdWVyeSI6IiRDQUxMRVIgOj0gJmZvb3t9IiwicmV3cml0ZSI6IiIsImNvbmZpZyI6ImlkOiBuby1jb25zb2xlXG5sYW5ndWFnZTogSmF2YVNjcmlwdFxucnVsZTpcbiAgcGF0dGVybjogY29uc29sZS5sb2coJEEpIiwic291cmNlIjoiY29uc29sZS5sb2coJ2hlbGxvJykgIC8vIG1hdGNoXG4vLyBhc3QtZ3JlcC1pZ25vcmVcbmNvbnNvbGUubG9nKCdzdXBwcmVzc2VkJykgLy8gc3VwcHJlc3NlZFxuLy8gYXN0LWdyZXAtaWdub3JlOiBuby1jb25zb2xlXG5jb25zb2xlLmxvZygnc3VwcHJlc3NlZCcpIC8vIHN1cHByZXNzZWRcbi8vIGFzdC1ncmVwLWlnbm9yZTogb3RoZXItcnVsZVxuY29uc29sZS5sb2coJ3dvcmxkJykgLy8gbWF0Y2hcbiJ9) for example.
176-
177-
```javascript [1,7]
178-
console.log('hello') // match
179-
// ast-grep-ignore
180-
console.log('suppressed') // suppressed
181-
// ast-grep-ignore: no-console
182-
console.log('suppressed') // suppressed
183-
// ast-grep-ignore: other-rule
184-
console.log('world') // match
185-
```
186-
168+
The first comment will suppress the following line's diagnostic. The second comment will suppress one or more specific rules.
169+
There are more options to configure ast-grep's linting behavior, please see [severity](/guide/project/severity.html) for more deep dive.
187170

188171
## Test and Debug Rules
189172

‎website/guide/project/severity.md‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
# Handle Error Reports
2+
3+
## Severity Levels
4+
5+
ast-grep supports these severity levels for rules:
6+
7+
* `error`: The rule will report an error and fails a scan.
8+
* `warning`: The rule will report a warning.
9+
* `info`: The rule will report an informational message.
10+
* `hint`: The rule will report a hint. This is the default severity level.
11+
* `off`: The rule will disable the rule at all.
12+
13+
If an `error` rule is triggered, `ast-grep scan` will exit with a non-zero status code. This is useful for CI/CD pipelines to fail the build when a rule is violated.
14+
15+
You can configure the severity level of a rule in the rule file:
16+
17+
```yaml
18+
id: rule-id
19+
severity: error
20+
# ... more fields
21+
```
22+
23+
## Override Severity on CLI
24+
25+
You can override the severity level of a rule on the command line. This is useful when you want to change the severity level of a rule for a specific scan.
26+
27+
```bash
28+
ast-grep scan --error rule-id --warning other-rule-id
29+
```
30+
31+
You can use multiple `--error`, `--warning`, `--info`, `--hint`, and `--off` flags to override multiple rules.
32+
33+
34+
## Ignore Linting Error
35+
36+
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` above the line that triggers the issue, or on the same line.
37+
38+
The suppression comment has the following format, in JavaScript for example:
39+
40+
```javascript {1,7}
41+
console.log('hello') // match
42+
// ast-grep-ignore
43+
console.log('suppressed') // suppressed
44+
// ast-grep-ignore: no-console
45+
console.log('suppressed') // suppressed
46+
// ast-grep-ignore: other-rule
47+
console.log('world') // match
48+
49+
// Same line suppression
50+
console.log('suppressed') // ast-grep-ignore
51+
console.log('suppressed') // ast-grep-ignore: no-console
52+
```
53+
54+
See the [playground](https://ast-grep.github.io/playground.html#eyJtb2RlIjoiQ29uZmlnIiwibGFuZyI6ImphdmFzY3JpcHQiLCJxdWVyeSI6IiRDQUxMRVIgOj0gJmZvb3t9IiwicmV3cml0ZSI6IiIsImNvbmZpZyI6ImlkOiBuby1jb25zb2xlXG5sYW5ndWFnZTogSmF2YVNjcmlwdFxucnVsZTpcbiAgcGF0dGVybjogY29uc29sZS5sb2coJEEpIiwic291cmNlIjoiY29uc29sZS5sb2coJ2hlbGxvJykgIC8vIG1hdGNoXG4vLyBhc3QtZ3JlcC1pZ25vcmVcbmNvbnNvbGUubG9nKCdzdXBwcmVzc2VkJykgLy8gc3VwcHJlc3NlZFxuLy8gYXN0LWdyZXAtaWdub3JlOiBuby1jb25zb2xlXG5jb25zb2xlLmxvZygnc3VwcHJlc3NlZCcpIC8vIHN1cHByZXNzZWRcbi8vIGFzdC1ncmVwLWlnbm9yZTogb3RoZXItcnVsZVxuY29uc29sZS5sb2coJ3dvcmxkJykgLy8gbWF0Y2hcbiJ9) in action.
55+
56+
These are the rules for suppression comments:
57+
58+
* A comment with the content `ast-grep-ignore` will suppress the following line/the same line's diagnostic.
59+
* The magic word `ast-grep-ignore` alone will suppress _all_ kinds of diagnostics.
60+
* `ast-grep-ignore: <rule-id>` can turn off specific rules.
61+
* You can turn off multiple rules by providing a comma-separated list in the comment. e.g. `ast-grep-ignore: rule-1, rule-2`
62+
* Suppression comments will suppress the next line diagnostic if and only if there is no preceding ASTs on the same line.
63+
64+
65+
66+
## Report Unused Suppressions
67+
68+
ast-grep can report unused suppression comments in your codebase. This is useful to keep your codebase clean and to avoid suppressing issues that are no longer relevant. An example report will look like this:
69+
70+
```diff
71+
help[unused-suppression]: Unused 'ast-grep-ignore' directive.
72+
- // ast-grep-ignore
73+
+
74+
```
75+
76+
`unused-suppression` itself behaves like a `hint` rule with auto-fix.
77+
But it is enabled, by default, only **when all rules are enabled**.
78+
79+
More specifically, [these conditions](https://github.com/ast-grep/ast-grep/blob/553f5e5ac577b6d2e0904c423bb5dbd27804328b/crates/cli/src/scan.rs#L68-L73) must be met:
80+
81+
1. No rule is [disabled](/guide/project/severity.html#override-severity-on-cli) by the `--off` flag on the CLI. `severity: off` configured in the YAML rule file does not count.
82+
2. The CLI [`--rule`](/reference/cli/scan.html#r-rule-rule-file) flag is not used.
83+
3. The CLI [`--inline-rules`](/reference/cli/scan.html#inline-rules-rule-text) flag is not used.
84+
4. The CLI [`--filter`](/reference/cli/scan.html#filter-regex) flag is not used.
85+
86+
:::tip Unused suppression report only happens in `ast-grep scan`
87+
If a rule is skipped during a scan, it is possible to mistakenly report a suppression comment as unused.
88+
So running specific rules or disabling rules will not trigger the unused suppression report.
89+
:::
90+
91+
You can also override the severity level of the `unused-suppression` rule on the command line. This can change the default behavior or unused-suppression reporting.
92+
93+
```bash
94+
# treat unused directive as error, useful in CI/CD
95+
ast-grep scan --error unused-suppression
96+
# enable report even not all rules are enabled
97+
ast-grep --rule rule.yml scan --hint unused-suppression
98+
```
99+
100+
## Inspect Rule Severity
101+
102+
Finally, ast-grep provides a CLI flag [`--inspect`](/reference/cli/scan.html#inspect-granularity) to debug what rules are enabled and their severity levels. This is useful to understand the rule configuration and to debug why a rule is not triggered.
103+
104+
```bash
105+
ast-grep scan --inspect entity
106+
107+
```
108+
109+
Example standard error debugging output:
110+
```
111+
sg: entity|rule|no-dupe-class-members: finalSeverity=Error
112+
sg: entity|rule|no-new-symbol: finalSeverity=Error
113+
sg: entity|rule|no-cond-assign: finalSeverity=Warning
114+
sg: entity|rule|no-constant-condition: finalSeverity=Warning
115+
sg: entity|rule|no-dupe-keys: finalSeverity=Error
116+
sg: entity|rule|no-await-in-loop: finalSeverity=Warning
117+
118+
```

0 commit comments

Comments
 (0)