feat: prefer-scale-token (#91), and three reliability fixes from the 1.5.0 review

[sergioazoc]

Closes #91, plus the three reliability findings the 1.5.0 review left documented and unfixed — one of which 1.5.0 itself made worse.

prefer-scale-token (#91)

A new rule that reports a hardcoded value numerically equal to something the design system already names, and suggests the name. It fills a gap the other three arbitrary→named rules structurally cannot, because each keys on something this case does not satisfy:

Rule	Fires on	Keyed on
no-unnecessary-arbitrary-value	w-[100%] → w-full	byte-identical CSS
enforce-canonical	what canonicalizeCandidates proposes	the same, since #78
prefer-theme-tokens	bg-(--primary) → bg-primary	the NAME of a variable
prefer-scale-token	p-[10px] → p-2.5	numeric equality

p-2.5 compiles to calc(var(--spacing) * 2.5) and p-[10px] to 10px: same length, different text.

Report-only, and it will stay that way. No fixable — the token reaches its value through var(), so a :root override or a different rootFontSize makes the equivalence false. Autofixing that is the bug #78 fixed. The message says so.

Correcting the issue's premise

w-[140px] → w-35 was never reported, before or after #78: canonicalizeCandidates doesn't propose it, because 35 isn't one of the steps Tailwind enumerates. What #78 silenced were the enumerated ones (p-[10px] → p-2.5, gap-[4px] → gap-1, h-[2rem] → h-8) plus the theme tokens (rounded-[0.5rem] → rounded-lg). Both are covered now, including the reporter's example — Tailwind compiles w-35, so it counts.

Two families, both derived

--spacing comes from the theme; the prefixes that read it are found by asking what <prefix>-1 compiles to; named tokens come from the emitted CSS plus the theme values. No namespace table exists to drift, and two things fall out of the derivation rather than being special-cased:

• text-[14px] → text-sm is NOT reported. text-sm also sets line-height, so it isn't the same declaration. Requiring one declaration drops the whole family on its own.
• Colour tokens aren't candidates — a colour can't match a literal numerically. ~7 000 of the ~7 200 pure-var() classes gone, 253 comparable ones left, +8.5 KB on the cache artifact.

The granularity is derived, not chosen

Tailwind compiles any number (w-8.425 is valid), so every length is N spacing units for some N — reporting all of them would be no-arbitrary-value with extra steps. Every step Tailwind's own scale enumerates is a multiple of 0.5, and the precompute computes that from the steps themselves. w-[140px] → w-35 passes; w-[33.7px] → w-8.425 doesn't. step only ever makes it finer.

Three reliability fixes

• The declaration service degraded in silence. It swallowed its own failures, which was defensible when no-conflicting-classes was the only caller. Since fix: derive the remaining nine rules from the generated CSS #95 no-unknown-classes asks it about VALIDITY, and there silence sends the rule back to the tolerant heuristic: a dead worker quietly reinstated the false negatives the service exists to remove, on a run that stayed green. It throws now, and each caller takes a posture that already existed — the two DS-dependent rules surface designSystemUnavailable, no-dark-without-light (which may never emit it) degrades and logs under debug. A transient worker failure now fails those two rules instead of weakening them quietly.
• prefer-theme-tokens proposed a colour-changing rewrite when the theme lived in an @import. definesVar is the guard that stops it, and it scanned only the entry CSS — so the normal shadcn/ui layout made :root { --primary: … } read as undefined. Reproduced with a fixture, then fixed.
• Two caches over one artifact could produce a false conflict. Lint-time interning appended to the artifact's own array while each cache kept its own text→id map, so one value could get two ids — and conflicts are decided by comparing ids. Ids are local now.

Testing

• Every fix has a test that fails on the old code — verified by reverting each one, not assumed.
• prefer-scale-token: 33 cases, and the valid half is the important one (the boundary, byte-identical hand-offs, text-[14px], variable references, bare numbers).
• The coexistence matrix goes from three rules to four: for each input, exactly one rule fires.
• The derived data is pinned in precomputed-snapshot.test.ts, so a Tailwind release that changes the granularity or the token set shows up as a failure rather than silently moving the rule.
• 1661 tests green, plus lint, format, typecheck, and both builds. Precompute cost of the new probe measured at 15 ms (+0.7%).

Found while reviewing my own diff

p-[10] compiles to padding: 10 — no unit, not a length — and the rule treated the bare number as px, so it suggested p-2.5 (padding: 10px). A change of meaning dressed as a change of spelling, which matters even without an autofix because editors apply suggestions on a click. Values now carry whether they had a unit.

Also fixes a doc error the same misconception produced: the rule index claimed no-unnecessary-arbitrary-value handles w-[200px] → w-50. It can't — getNamedEquivalent('w-[200px]') is null — and that example now points at the rule that does.

Version bumped to 1.6.0: new rule (off by default, no presets exist), plus the behaviour change above.