Skip to main content

LINT.ANNOTATION_UNKNOWN_RULE — an annotation suppresses a rule that does not exist

  • Category: safety
  • Level: 0
  • Stability: stable
  • Suites: lint

A migration carries #[SqlensIgnore(rules: [...])], and one of the ids it names matches no rule of any driver. The annotation suppresses nothing.

Why this is worse than an ordinary typo​

The attribute takes a mandatory reason. That is deliberate — a suppression without one is a decision nobody can review. The cost is that a broken annotation looks exactly like a working one:

#[SqlensIgnore(
    rules: ['PG.L1.DROP_TABLE'],   // …now transpose two letters in the name
    reason: 'this table is a scratch table rebuilt by the seeder',
)]

The reason is thoughtful, and one transposed letter in the id is all it takes: the finding the annotation was meant to accept has been reported on every run since. Nothing said so, because an entry that matches nothing produces exactly what a matching entry produces once the code is fixed.

⚠️ The misspelled id is described rather than printed here on purpose. A page that spelled it out would be a page citing a rule this package does not ship — which a guard refuses, and rightly: every other id on these pages is a promise that something answers to it.

Why it does not fail the run​

Its config-file twin — the same mistake in sqlens.ignore — does refuse, and the difference is where the text lives.

An ignore list is edited by whoever runs the tool today, so a typo there is fresh and worth stopping for. An annotation sits in a migration that shipped years ago and will never be touched again. Refusing a run because a rule was renamed since would turn a project's history into a timer: the older the migration, the likelier it names something that no longer exists, and the fix would be editing files that have already run in production.

So this is reported and the run continues.

What to do about it​

Read the id the message names, then pick one:

  • Correct it, if the rule still exists under another spelling. The message names the closest real id when there is one.
  • Delete the annotation, if the rule it named is gone. The finding it accepted either no longer exists or is now unsuppressed and worth looking at.
  • Leave it, deliberately, if the migration is historical and you would rather not touch it. The notice will keep appearing, which is the honest state: something in the file claims to be doing work that it is not.

Not a rule, and it says so​

This is a runner notice: no rule produced it, and none could, because it describes the project's configuration rather than a statement. It carries an id, a message prefix and this documentation URL exactly like a rule's finding, because a reader should not have to know the difference to act on it.

Sources​

  • The #[SqlensIgnore] attribute and its mandatory reason.
  • RuleIdValidator, which answers the same question for the baseline and the ignore list — and refuses those, for the reason above.