What You Refuse to Check Decides the Quality of a Linter

Description and use

Building a linter that avoids false positives is achieved by adding rules only when documentation explicitly states them, requiring source URLs, and using only error/warn severities.

Problem

Developers struggle to build linters that avoid false positives while still catching real issues, leading to loss of trust and CI failures.

Outcome

The linter achieves zero false positives on valid configurations, maintains high trust, and avoids CI removal.

Workflow

• 1. Define a rule only if the official documentation explicitly states it as an error, warning, or ignored case.
• 2. Require each finding to include a "because" field with a source URL.
• 3. Enforce the source URL requirement in tests; any finding without it fails the suite.
• 4. Avoid rules for ambiguous or undocumented features (unknown keys, model names, complex path patterns, non‑standard booleans).
• 5. Use only two severities: "error" for documented violations and "warn" for deprecated or future‑breaking cases.
• 6. Run tests with a deliberately valid configuration that includes edge cases; expect zero findings.
• 7. If any finding appears on the valid config, reconsider the rule or its implementation.

Evidence

One false positive is enough to get the tool thrown out

Source

Only check what the official documentation states outright — as an error, as skipped, or as ignored.

Source

A single finding from any of those means the design is wrong.

Source