[malept]

What this PR does / why we need it

Schemas can only silence a rule today with # eslint-disable comments, which tie them to ESLint after the linter changes. Other linters have also learned that suppressions need a named rule and a reason, and that stale ones should be reported.

Add suppression comments owned by devbase: # devbase-lint-disable-next-line, -disable-line, -disable and -enable, for Tier 2 and Tier 3 rules named by their bare devbase name.

• A disable directive names at least one rule and gives a reason, either inline after -- or as a # Why: comment block directly above a disable-next-line or disable directive.
• A directive that is malformed, names an unknown or unsuppressible rule, or has no reason suppresses nothing and is reported as invalid-suppression.
• A valid directive that suppresses nothing for a rule it names is reported as unused-suppression.
• Both diagnostics default to error, cannot be suppressed, and can be lowered or turned off in scripts/devbase.yaml.

# Why: Renaming this value breaks existing clients,
# so it keeps its legacy casing until the v3 schema.
# devbase-lint-disable-next-line naming-convention
enum Kind { Legacy }

no-hashtag-description skips devbase-lint- comments, as it does eslint ones. The eslint- directives keep working as before.

Jira ID

DT-5644

Notes for your reviewers

The lexer gives a multi-line block string the line it ends on, not the line it starts on. disable-next-line skips a description below the directive, because violations are reported on the name's line, so it finds the description's start line from the token's rune offset.

Rejected review findings and intentional non-goals

These were considered during design and deliberately left as they are. Do not raise them again unless the reasoning below no longer holds.

Rejected findings

• Explain why a directive is unused when a comment sits between it and the code. The directive then covers the comment line and suppresses nothing, but the diagnostic cannot tell why. It reports the fact, which fails safe.

Intentional behavior

• There is no blanket form. Every disable directive must name a rule, as several linters recommend and some enforce.
• A # Why: block does not work for disable-line or for a trailing directive. A block above the code would be read by no-hashtag-description as a description, so those forms take only an inline -- reason. Use disable-next-line for a long reason.
• Directives cannot be stacked. List the rules in one directive.
• The @graphql-eslint/ rule prefix is not accepted in native directives.
• A reason only has to be non-empty. There is no minimum length.
• Unused detection is per rule and covers native directives only. Unused eslint- directives are not reported.
• A schema with a Tier 1 error returns before suppression runs, so it produces no suppression diagnostics.
• Native directives are applied before eslint- ones, so a violation covered by both counts as used for the native directive.
• Expiry dates, rule-and-path ignores in scripts/devbase.yaml, and a way to list suppressed violations are out of scope.

[getoutreach-ci-2]

Link to code coverage report (posted by coverbot 🤖)