Handle Error Reports

Severity Levels

ast-grep supports these severity levels for rules:

• error: The rule will report an error and fails a scan.
• warning: The rule will report a warning.
• info: The rule will report an informational message.
• hint: The rule will report a hint. This is the default severity level.
• off: The rule will disable the rule at all.

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.

You can configure the severity level of a rule in the rule file:

id: rule-id
severity: error
# ... more fields

Override Severity on CLI

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.

ast-grep scan --error rule-id --warning other-rule-id

You can use multiple --error, --warning, --info, --hint, and --off flags to override multiple rules.

Ignore Linting Error

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.

The suppression comment has the following format, in JavaScript for example:

console.log('hello')  // match
// ast-grep-ignore
console.log('suppressed') // suppressed
// ast-grep-ignore: no-console
console.log('suppressed') // suppressed
// ast-grep-ignore: other-rule
console.log('world') // match

// Same line suppression
console.log('suppressed') // ast-grep-ignore
console.log('suppressed') // ast-grep-ignore: no-console

See the playground in action.

These are the rules for suppression comments:

• A comment with the content ast-grep-ignore will suppress the following line/the same line's diagnostic.
• The magic word ast-grep-ignore alone will suppress all kinds of diagnostics.
• ast-grep-ignore: <rule-id> can turn off specific rules.
• You can turn off multiple rules by providing a comma-separated list in the comment. e.g. ast-grep-ignore: rule-1, rule-2
• Suppression comments will suppress the next line diagnostic if and only if there is no preceding ASTs on the same line.

Report Unused Suppressions

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:

help[unused-suppression]: Unused 'ast-grep-ignore' directive.
- // ast-grep-ignore
+

unused-suppression itself behaves like a hint rule with auto-fix. But it is enabled, by default, only when all rules are enabled.

More specifically, these conditions must be met:

1. No rule is disabled by the --off flag on the CLI. severity: off configured in the YAML rule file does not count.
2. The CLI --rule flag is not used.
3. The CLI --inline-rules flag is not used.
4. The CLI --filter flag is not used.

Unused suppression report only happens in ast-grep scan

If a rule is skipped during a scan, it is possible to mistakenly report a suppression comment as unused. So running specific rules or disabling rules will not trigger the unused suppression report.

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.

# treat unused directive as error, useful in CI/CD
ast-grep scan --error unused-suppression
# enable report even not all rules are enabled
ast-grep --rule rule.yml scan --hint unused-suppression

Inspect Rule Severity

Finally, ast-grep provides a CLI flag --inspect 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.

ast-grep scan --inspect entity

Example standard error debugging output:

sg: entity|rule|no-dupe-class-members: finalSeverity=Error
sg: entity|rule|no-new-symbol: finalSeverity=Error
sg: entity|rule|no-cond-assign: finalSeverity=Warning
sg: entity|rule|no-constant-condition: finalSeverity=Warning
sg: entity|rule|no-dupe-keys: finalSeverity=Error
sg: entity|rule|no-await-in-loop: finalSeverity=Warning