0080. Lint rules are coded warnings, set per project in duolith.yaml, run by duolith lint
- Status: Accepted (Mik, 17 Nov 2026)
- Date: 2026-11-14
- Decided by: Mik
- Planning item: WP4 (
duolith lintwith automatic fixes)
Context
The analyzer's diagnostics are errors: a page with one does not build. Much of what hurts an app's users or authors is not wrong enough to stop a build: a pressable view a keyboard cannot reach, a field with no label, a list without a key, state nothing uses, a utility another one overrides. These need a separate layer that advises, can be turned off where a project disagrees, and fixes what it safely can. The plan (WP4) names duolith lint with fixes; it does not say where a project sets the rules or how the codes look.
Decision
- A lint rule is a check with a stable warning code,
W0001toW0099, inspec/diagnostics/catalogue.yamlbeside the errors. Each entry addsrule:, the rule's name. Codes come in blocks: W0001-W0019 accessibility, W0020-W0039 performance, W0040-W0059 correctness, W0060-W0079 style. W0099 is not a rule: it is the code an editor reports a brokenduolith.yamlwith.duolith explainprints a rule's entry by code or by name (duolith explain list-without-key). - The first rules are press-without-role (W0001), field-without-label (W0002), low-contrast (W0003, WCAG 2.1 contrast of the theme's tokens in each colour scheme the app shows; it gives up rather than guess where a colour is set only sometimes or by a style block), nested-pressable (W0004), list-without-key (W0020), large-inline-literal (W0021), effect-writes-what-it-reads (W0022), unused-state (W0040), unused-prop (W0041), unreachable-otherwise (W0042), shadowed-name (W0043), conflicting-utilities (W0060) and hard-coded-colour (W0061). An image without a description is already an error (E0160), so it has no rule. A heading order rule waits for the language to have heading levels; today
role="heading"has none. - Rules run on files that analyse without errors, reading the syntax tree, the Screen IR and the theme.
crates/lintdepends onsyntaxandstyleas well asanalyzerfor that (tools/boundaries.yaml). - **
--fixapplies a fix only where it cannot change what the app does or shows**: removing an overridden utility, removing<otherwise>after<show when={true}>(its line, not what is between it and the show), removing an unused state declaration whose initialiser calls nothing and has noneworawait, a placeholder becoming a label, and a hex colour becoming its token where exactly one token has that value in the light scheme (the dark one, for a theme that is always dark). A view becoming a button changes the layout, since a button centres what it holds, so that fix is offered only in the editor, where the author sees the result, and never where a button would end up inside another pressable element. Where the fix needs a name or a judgement (a list's key, a moved literal, an unused prop, a colour several tokens share), there is only help text. - **A project sets rules in
duolith.yamlat its root**, underlint:, by name or code (written exactly as the catalogue writes them, as the schema checks), tooff,warning(the default) orerror. A file that cannot be read, is not UTF-8 or has a mistake in it is an error forduolith lint; a rule set by both its name and its code is a warning, and the later entry wins. The file followstheme.yaml's convention: YAML at the project root, described by a schema (spec/schemas/project.schema.json), every problem reported with its path and the closest correct name. It is a new file rather than a group intheme.yamlbecause lint levels are not design values, and the theme schema rejects unknown groups. - **
duolith lint [project]** checks that the project builds (reporting build errors asduolith builddoes), then lints every page, layout and component.--fixworks on a copy of the project: it applies the fixes, formats each fixed file that was formatted before (soduolith fmt --checkstill passes), builds the copy and lints it again, for at most ten passes. A pass that breaks the build is undone and its fixes tried one at a time; one that breaks the build is left out and named. The project's own files are written only once the copy builds.--jsonprints{ ok, fixed, notApplied, stoppedEarly, configWarnings, diagnostics }, each diagnostic with itsfixtitle or null and whether that fix needs review. It exits 1 on any finding at levelerror, and on warnings too with--deny-warnings, which CI uses.duolith builddoes not lint. - Editors show lint warnings through the language server: the compiler service's
checkPagetakes the text ofduolith.yamland returns each warning with its fix's edits, which become a quick fix. While a file has an error, its lint warnings are not shown. A brokenduolith.yamlis shown at the top of each page as W0099, and the rules run at their defaults until it is corrected.
Alternatives considered
| Option | Why not |
|---|---|
A lint: group in theme.yaml | Mixes rule levels into design values, and needs the theme schema and its loader (Styling) to change for an Analysis concern |
duolith.config.ts | Needs a script runtime at build time, as decision 0018 found for the theme |
Lint warnings from duolith build | Every build would repeat advice the author may have chosen to ignore; a separate command keeps the build's output to what must be fixed |
| Comments that turn a rule off for one line | Useful, but a second way to configure; left for later (post-v1) once real projects show the need |
| Exit 1 on any warning | Makes warning and error the same thing from the command line; --deny-warnings gives CI the strict form |
Consequences
- New rules take the next code in their group, a catalogue entry with
rule:, a name in the project schema (a test checks all three agree) and a test that fires and one that does not. - Every example except
examples/lint-showcasemust lint clean: a test incrates/cliand a CI step check it. The showcase trips every rule once, and the same test checks its warnings exactly. - Lint rule is in the glossary, approved by Mik on 17 Nov 2026.