add-a-linter

name	add-a-linter
description	Add a new linter to vigiles's cross-referencing engine as one cohesive, type-enforced unit — a LinterAdapter in the LINTERS registry, with the conformance test enforcing docs + site parity so no site is forgotten
disable-model-invocation	true
argument-hint	<linter name, e.g. "biome" or "checkov">

Add a linter to vigiles's cross-referencing engine (the enforce("eslint/...") moat). This is a contributor task, not a third-party extension point: the LINTERS registry is a Record<BuiltinLinter, LinterAdapter> — a closed set baked into core — so a linter is added by editing vigiles itself, and the type system + the conformance test make the parity un-forgettable.

The whole reason this skill exists: a linter used to be smeared across ~7 scattered sites (existence check, config checker, CLI-tool map, suggestion enumerator, generate-types discoverer, docs, site) with nothing enforcing that you touched all of them — miss one and it failed silently. Now tsc fails if the registry entry is missing, and src/core/linter-contract.test.ts fails if the docs table or the marketing site drifts. Follow the steps; let the gates catch what you forget. See research/linter-adapter-architecture.md.

The one invariant

A linter is one LinterAdapter in one registry. Everything else — existence, config-enabled, suggestions, type-gen, docs, site — is a field or a method on that adapter, cross-checked by the conformance test. You never again hunt for "the other place this linter is registered."

Steps

Work in this order — each step's gate tells you the next is needed.

1. Name it (the single source). Add the lowercase name to BUILTIN_LINTERS in src/core/spec.ts. BuiltinLinter derives from this array, so the moment you save, tsc fails on LINTERS in linters.ts with "property <name> is missing" — that error is your to-do list.

2. Pick the existence-check kind (LinterCapabilities.existenceCheck in src/core/linter-adapter.ts) — this decides which helper builds the adapter:

   • node-api — the rule set is resolved from an installed npm package (eslint, stylelint). Use nodeApiAdapter(name, resolver, configEnabled, discover).
   • cli — a real command asks the tool whether a rule exists (ruff, clippy, pylint, rubocop, detekt, ktlint, checkstyle, golangci-lint). Use cliAdapter(name, cliTool, checkExists, configEnabled, discover, enumerate?).
   • filesystem — presence in a project file counts, no tool (cedar). Write a literal adapter (see cedar in linters.ts).
   • format-only — only the reference shape is validated, no tool exists to list rules (ktlint's catalog is unlistable). Still a cli adapter, just omit the enumerate arg; the existence check is the qualified-shape rule.

3. Implement the discoverer discover<Name>Rules(basePath): DiscoveredRules | null in linters.ts — reads the project's real linter config and returns its enabled rules for generate-types (fail open: return null, never flag every rule, when you can't enumerate). If it's a cli linter, also write its <name>CheckExists existence probe (throws when the rule is unknown) and, for a real config-enabled read, its <name>ConfigEnabled checker — plain named functions the adapter references directly in the LINTERS registry (there is no separate map to touch). Parse structured config with a real parser (js-yaml / @iarna/toml / the shared markdown-it helper), never a hand-rolled regex — see the parse-structured-input-with-a-real-parser rule; detekt's parseDetektConfig (js-yaml) is the model.

4. Register it in LINTERS (linters.ts) via the matching helper. tsc goes green here — the registry is now complete.

5. Document it — docs/linter-support.md: add a row to the ## Supported Linters table AND a ## <Linter> section (config conventions, rule-prefix, any capability caveat like "format-only" or "whitelist-only"). The conformance test set-matches the table against the registry, so a missing row fails CI.

6. The site updates itself — the vigiles.sh chip strip (Wedge.tsx) DERIVES from BUILTIN_LINTERS, so a new linter appears automatically; there's no array to edit. Optionally add a display label to LINTER_LABELS in Wedge.tsx if it needs special casing (e.g. ESLint, RuboCop); with no entry it renders under its lowercase name. The conformance test guards that the derivation stays in place (a revert to a hand-typed list fails CI).

7. If it's a cli linter, make CI actually run it — no silent skips. The real-binary tests are describe.skipIf(!hasBinary("<tool>")) in src/core/linters.test.ts; a binary absent from CI means those tests skip silently (a hidden gap — the no-silent-skips rule). Install the tool in the test job of .github/workflows/ci.yml (pin a version via a job env, cache it) AND add it to the command -v sanity loop so a missing binary fails the build instead of skipping. Then write the two complementary tests: a real-binary test (describe.skipIf(!hasBinary)) and a missing-binary honest-error test (it.skipIf(hasBinary)) — one always runs, the pair is loud either way.

8. Add the parity test data. The conformance loop in src/core/linter-contract.test.ts is generic (it iterates the registry), so it covers the new linter automatically — but add a targeted config-parse/discover unit test in linters.test.ts for the new linter's own parser, and a per-linter capability assertion if it has an unusual variance (e.g. format-only, alwaysEnabled).

The gates that make this safe

Run npm test (or at least npx vitest run src/core/linter-contract.test.ts src/core/linters.test.ts + tsc --noEmit). You are done only when:

• tsc is clean — the registry entry exists (completeness).
• linter-contract.test.ts is green — key === name, every capability flag matches its method's presence, existenceCheck === "cli" ⟺ cliTool present, and the registry keys set-match BUILTIN_LINTERS and docs/linter-support.md and the site chip list (docs + site parity).
• The new linter's config-parse unit test passes with no binary, and its real-binary test runs in CI (installed + sanity-gated), not skipped.