lint-and-style-config

Lint & Style Config

Style is not taste; it is toolchain-enforced. dart format owns whitespace, the analyzer owns correctness, and a small set of silence-producing bug classes are promoted to build-failing errors. This skill governs the analysis_options.yaml itself and the mechanics that decide whether it actually does anything. Applies whenever you edit that file, add or silence a lint, or bump the SDK/ruleset.

Read the reference for the task at hand:

• references/rule-catalog.md — every promoted rule and its bug class, the deliberate downgrades, the contested public_member_api_docs call, and the complexity-limit table.
• references/config-mechanics.md — the include-pin trap, errors:-re-ranks vs linter:-enables, sealed-switch analyze-vs-compile, coverage mirroring, the riverpod_lint plugin, and suppression discipline.

Copy examples/analysis_options.yaml into the package root as the starting config. Run scripts/verify-include-pin.sh and scripts/lint-gates.sh before a PR.

Non-negotiable rules

1. dart format is the only whitespace authority. Never hand-format, never argue with it, never // dart format off except around a hand-laid table with a justifying comment. CI runs dart format --set-exit-if-changed ..
2. Build on very_good_analysis, pinned to the version-numbered include. Never the bare analysis_options.yaml — a pub upgrade must not silently change what counts as an error. VGA already sets strict-casts, strict-inference, strict-raw-types; do not restate them in a language: block (redundant config drifts and contradicts).
3. An info is a failure. CI runs dart analyze --fatal-infos --fatal-warnings. Unaddressed infos accumulate into noise that hides real issues.
4. Promote only silence-producing bug classes to error — dropped Futures, swallowed failure, dead-context-after-await, resource leaks, dynamic-boundary type holes, non-exhaustive enum switches, print. Not style preferences.
5. A promotion under errors: only works if the base ruleset already enables the rule. errors: re-ranks existing diagnostics; it cannot turn on an off rule. To enable a rule VGA omits, add it under linter: rules: first.
6. Never mix list and map form in linter: rules:. - rule items and rule: true entries in one block is a parse error — a broken analyzer, which is a green build. To disable a base rule, use errors: <rule>: ignore.
7. CI must build, not merely analyze. Sealed-switch exhaustiveness is a compile error, not a lint; an errors: override cannot be trusted to silence it, and any code path that reaches dart compile still fails there — an analyze-only gate can go green over code that will not build.
8. Exclude generated code, and mirror the exact globs in coverage filtering. Otherwise generated files dilute the coverage number until it is meaningless.
9. Suppressions are line-scoped only, with a same-line/above reason. Never // ignore_for_file: on a promoted rule; never any suppression on an architecture/import gate. Prefer fixing the code.
10. Never add custom_lint. riverpod_lint 3.x runs on the first-party plugin system; its diagnostics fire on a plain flutter analyze.