basalt-ui 1.19.1 → 1.21.0

package/src/guard/check-source.test.ts

@@ -1,7 +1,7 @@
 /**
  * Unit tests for checkSource — the pure (text, relPath, cfg) → Finding[] core.
  *
- * Covers all 20 guard kinds. Co-located with the guard, excluded from tsc
+ * Covers all 25 guard kinds. Co-located with the guard, excluded from tsc
  * (tsconfig exclude: src/**\/*.test.ts), run via `bun test`.
  *
  * The walker/reporter half is covered by the integration test in
@@ -10,8 +10,17 @@
 import { describe, expect, it } from 'bun:test'
 import { pxRem } from '../tokens'
 import { SPACE_SCALE } from '../tokens/palette'
-import { checkSource, DEFAULT_GUARD_CONFIG } from './index'
-import type { Finding, GuardKind } from './types'
+import {
+  checkSource,
+  DEFAULT_GUARD_CONFIG,
+  GENERATED_HEADER_LINE,
+  guardKindRemedy,
+  guardWaiverHint,
+  GUARD_RULES,
+  TOKENS_ONLY_DISABLED_KINDS,
+  unmatchedExemptPatterns,
+} from './index'
+import type { Finding, GuardConfig, GuardKind } from './types'
 
 const PATH = 'src/Dashboard.tsx'
 const CHART_PATH = 'src/charts/kinds/Foo.tsx'
@@ -1004,14 +1013,19 @@ describe('raw-font-family', () => {
     expect(kinds(f)).toContain('raw-font-family')
   })
 
-  it('flags a fontFamily bound to a var(...) reference OUTSIDE the two allowed prefixes (the (b) bypass)', () => {
+  // A var() REFERENCE is not a literal, whichever custom property it names. The escape used to be
+  // restricted to `--basalt-font-*` / `--mantine-font-family-*`, which reported a framework-free
+  // consumer's `font-family: var(--font-sans)` as "a hardcoded fontFamily literal" and pointed the
+  // fix at the React-only `createBasaltTheme`. The single-entry-point invariant is doctrine for
+  // basalt's own theme layer; this regex cannot tell it apart from a consumer's own indirection.
+  it('does NOT flag a fontFamily bound to a var(...) reference outside basalt’s own prefixes', () => {
     const f = find(`fontFamily: 'var(--some-other-var)'`)
-    expect(kinds(f)).toContain('raw-font-family')
+    expect(kinds(f)).not.toContain('raw-font-family')
   })
 
-  it('flags a kebab-case font-family bound to a var(...) reference outside the allowed prefixes', () => {
-    const f = find(`font-family: var(--some-other-var);`)
-    expect(kinds(f)).toContain('raw-font-family')
+  it('does NOT flag a kebab-case font-family bound to a consumer var(...) reference', () => {
+    const f = find(`font-family: var(--font-sans);`)
+    expect(kinds(f)).not.toContain('raw-font-family')
   })
 
   it('does NOT flag a kebab-case font-family bound to var(--mantine-font-family-…)', () => {
@@ -1575,6 +1589,99 @@ describe('exemptRules', () => {
     expect(kinds(f)).toContain('inline-display')
   })
 
+  // ── Relative paths and globs ────────────────────────────────────────────────
+  //
+  // Only the bare-segment shape existed, and it is the one nobody guesses. rollhook wrote the
+  // obvious, correct `"public/site.webmanifest"`, matched nothing, got no diagnostic, and kept
+  // reporting — while `exemptRules` had just become the ONLY waiver route for a whole file class.
+
+  const HEX_MANIFEST = '{ "theme_color": "#27272a" }'
+  const exemptedAt = (relPath: string, patterns: string[]): GuardKind[] =>
+    kinds(
+      checkSource(HEX_MANIFEST, relPath, {
+        ...DEFAULT_GUARD_CONFIG,
+        exemptRules: { 'raw-hex': patterns },
+      }),
+    )
+
+  it('matches a real relative path to one file', () => {
+    expect(exemptedAt('public/site.webmanifest', ['public/site.webmanifest'])).not.toContain(
+      'raw-hex',
+    )
+  })
+
+  it('matches a relative directory prefix', () => {
+    expect(exemptedAt('public/icons/theme.json', ['public/icons'])).not.toContain('raw-hex')
+  })
+
+  it("normalizes a leading './' and a trailing '/'", () => {
+    expect(exemptedAt('public/site.webmanifest', ['./public/'])).not.toContain('raw-hex')
+  })
+
+  it('matches a glob, with `*` stopping at a slash', () => {
+    expect(exemptedAt('public/site.webmanifest', ['public/*.webmanifest'])).not.toContain('raw-hex')
+    expect(exemptedAt('public/nested/site.webmanifest', ['public/*.webmanifest'])).toContain(
+      'raw-hex',
+    )
+  })
+
+  it('matches a `**` glob across slashes', () => {
+    expect(exemptedAt('src/a/b/theme.json', ['src/**/theme.json'])).not.toContain('raw-hex')
+  })
+
+  it('matches a slash-free glob against the BASENAME, like a bare segment does', () => {
+    const f = checkSource(`.a { padding: 18px }`, 'src/features/Card.module.css', {
+      ...DEFAULT_GUARD_CONFIG,
+      exemptRules: { 'inline-spacing': ['*.module.css'] },
+    })
+    expect(kinds(f)).not.toContain('inline-spacing')
+  })
+
+  it('still fires at a path the path/glob does not match', () => {
+    expect(exemptedAt('public/other.webmanifest', ['public/site.webmanifest'])).toContain('raw-hex')
+  })
+
+  // The other half of the fix. An exemption is a CLAIM, and a claim that resolves to nothing reads
+  // as coverage in a config review while enforcing exactly as much as an empty object.
+  describe('unmatchedExemptPatterns', () => {
+    const scanned = ['src/App.tsx', 'public/site.webmanifest']
+
+    it('reports a pattern that matches no scanned file', () => {
+      const cfg = { ...DEFAULT_GUARD_CONFIG, exemptRules: { 'raw-hex': ['public/manifest.json'] } }
+      expect(unmatchedExemptPatterns(cfg, scanned)).toEqual([
+        { kind: 'raw-hex', pattern: 'public/manifest.json', reason: 'no-match' },
+      ])
+    })
+
+    it('says nothing about a pattern that DOES match', () => {
+      const cfg = {
+        ...DEFAULT_GUARD_CONFIG,
+        exemptRules: { 'raw-hex': ['public/site.webmanifest'] },
+      }
+      expect(unmatchedExemptPatterns(cfg, scanned)).toEqual([])
+    })
+
+    it("reports a typo'd KIND — an exemption for a rule that does not exist", () => {
+      const cfg = {
+        ...DEFAULT_GUARD_CONFIG,
+        exemptRules: { 'raw-hexx': ['src'] } as unknown as GuardConfig['exemptRules'],
+      }
+      expect(unmatchedExemptPatterns(cfg, scanned)).toEqual([
+        { kind: 'raw-hexx', pattern: 'src', reason: 'unknown-kind' },
+      ])
+    })
+
+    it('reports the exact shape rollhook wrote before the path matcher existed', () => {
+      const cfg = { ...DEFAULT_GUARD_CONFIG, exemptRules: { 'raw-hex': ['site.webmanifest'] } }
+      expect(unmatchedExemptPatterns(cfg, ['public/site.webmanifest'])).toEqual([])
+      expect(unmatchedExemptPatterns(cfg, ['src/App.tsx'])).toHaveLength(1)
+    })
+
+    it('is silent on an empty config', () => {
+      expect(unmatchedExemptPatterns(DEFAULT_GUARD_CONFIG, scanned)).toEqual([])
+    })
+  })
+
   it('does NOT suppress a different kind on the same line/path', () => {
     const f = checkSource(`const c = '#ff0000'; ${TEXT}`, 'src/agent/x.tsx', {
       ...DEFAULT_GUARD_CONFIG,
@@ -1599,6 +1706,59 @@ describe('exemptRules', () => {
     expect(kinds(f)).toContain('inline-display')
     expect(kinds(f)).toContain('raw-html-layout')
   })
+
+  // ── EXEMPT_RULE_ALIASES: a grace-minor WIDENING inherits its parent's exemption ───────────────
+  // A kind that exists only to widen an established one is the same rule to a consumer, so an
+  // exemption already written for the parent has to cover it — otherwise the widening arrives as
+  // noise in exactly the paths someone decided the rule does not apply to.
+
+  const HIDDEN =
+    "const s = { display: 'flex', padding: 18 }\nexport const D = () => <div style={s} />"
+  const SHADOW = 'const s = { boxShadow: `0 0 0 2px ${VX.accent}` }'
+  const CSS_SURFACE = '.card { border-radius: 12px; }'
+
+  it("hidden-inline-style inherits raw-html-layout's exemption", () => {
+    expect(kinds(find(HIDDEN, 'src/agent/x.tsx'))).toContain('hidden-inline-style')
+    const f = checkSource(HIDDEN, 'src/agent/x.tsx', {
+      ...DEFAULT_GUARD_CONFIG,
+      exemptRules: { 'raw-html-layout': ['agent'] },
+    })
+    expect(kinds(f)).not.toContain('hidden-inline-style')
+  })
+
+  it("surface-shadow-override and css-raw-surface inherit raw-surface's exemption", () => {
+    expect(kinds(find(SHADOW, 'src/agent/x.tsx'))).toContain('surface-shadow-override')
+    expect(kinds(find(CSS_SURFACE, 'src/agent/x.css'))).toContain('css-raw-surface')
+    const cfg = { ...DEFAULT_GUARD_CONFIG, exemptRules: { 'raw-surface': ['agent'] } }
+    expect(kinds(checkSource(SHADOW, 'src/agent/x.tsx', cfg))).not.toContain(
+      'surface-shadow-override',
+    )
+    expect(kinds(checkSource(CSS_SURFACE, 'src/agent/x.css', cfg))).not.toContain('css-raw-surface')
+  })
+
+  it('the inheritance is one-way — exempting the CHILD leaves the parent enforced', () => {
+    const f = checkSource(HIDDEN, 'src/agent/x.tsx', {
+      ...DEFAULT_GUARD_CONFIG,
+      exemptRules: { 'hidden-inline-style': ['agent'] },
+    })
+    expect(kinds(f)).not.toContain('hidden-inline-style')
+    expect(
+      kinds(
+        checkSource(TEXT, 'src/agent/x.tsx', {
+          ...DEFAULT_GUARD_CONFIG,
+          exemptRules: { 'hidden-inline-style': ['agent'] },
+        }),
+      ),
+    ).toContain('raw-html-layout')
+  })
+
+  it('an alias does not exempt a path the parent exemption never named', () => {
+    const f = checkSource(SHADOW, 'src/charts/x.tsx', {
+      ...DEFAULT_GUARD_CONFIG,
+      exemptRules: { 'raw-surface': ['agent'] },
+    })
+    expect(kinds(f)).toContain('surface-shadow-override')
+  })
 })
 
 // ── 20. severity ─────────────────────────────────────────────────────────────
@@ -1627,10 +1787,34 @@ describe('severity', () => {
     expect(f.find((v) => v.kind === 'raw-spacing')?.severity).toBe('error')
   })
 
-  it('ships no kind in its grace period today', () => {
-    // Every shipped kind is past its grace minor. This is a LEDGER, not a constraint: when a new
-    // kind lands warn-only, this expectation changes in the same commit, and changing it back is
-    // the promotion. A grace entry that outlives its minor shows up here as an unexplained diff.
+  // The grace ledger. Five kinds landed warn-only in the round-4 guard minor; deleting an entry
+  // from GRACE_PERIOD_KINDS is the promotion, and it shows up here as an explicit diff.
+  it.each([
+    'theme-allow-unscoped',
+    'surface-shadow-override',
+    'css-raw-surface',
+    'inline-font-size',
+    'hidden-inline-style',
+  ])('%s is still in its grace minor (warn)', (kind) => {
+    const cases: Record<string, [string, string]> = {
+      'theme-allow-unscoped': ['const x = 1 // theme-allow', PATH],
+      'surface-shadow-override': ['const s = { boxShadow: `0 0 0 2px ${VX.accent}` }', PATH],
+      'css-raw-surface': ['.a { border-radius: 6px; }', 'src/a.module.css'],
+      'inline-font-size': [`<div style={{ fontSize: 11 }} />`, PATH],
+      'hidden-inline-style': [
+        `const rowStyle = { display: 'flex', gap: 12 }\nexport const C = () => <div style={rowStyle} />`,
+        PATH,
+      ],
+    }
+    const [src, path] = cases[kind] as [string, string]
+    const hit = find(src, path).find((v) => v.kind === kind)
+    expect(hit?.severity).toBe('warn')
+  })
+
+  it('ships every OTHER kind past its grace period', () => {
+    // Not a constraint, a LEDGER: when a new kind lands warn-only, this expectation changes in the
+    // same commit, and changing it back is the promotion. A grace entry that outlives its minor
+    // shows up here as an unexplained diff.
     const cfg = DEFAULT_GUARD_CONFIG
     const everyKind = checkSource(
       `<Box p={${SPACE_SCALE.md}} radius={4} style={{ color: '#ff0000', gap: 3 }} />`,
@@ -1641,3 +1825,911 @@ describe('severity', () => {
     expect(everyKind.every((v) => v.severity === 'error')).toBe(true)
   })
 })
+
+// ── 21. theme-allow placement ────────────────────────────────────────────────
+
+describe('theme-allow placement', () => {
+  it('honours a standalone comment on the PRECEDING line (the JSX-legal form)', () => {
+    const f = find(
+      `export const C = () => (
+  {/* theme-allow raw-hex — brand asset, fixed by the vendor */}
+  <Box style={{ color: '#ff0000' }} />
+)`,
+    )
+    expect(kinds(f)).not.toContain('raw-hex')
+  })
+
+  // A TRAILING comment stays scoped to its own line: `const a = '#f00' // theme-allow` must not
+  // silently waive the next line as well.
+  it('does NOT let a trailing comment waive the line below it', () => {
+    const f = find(`const a = '#ff0000' // theme-allow raw-hex — vendor brand\nconst b = '#00ff00'`)
+    expect(f.filter((x) => x.kind === 'raw-hex')).toHaveLength(1)
+  })
+
+  // rb's defect: the shipped oxfmt reflows a long declaration and lands the comment on a different
+  // line than the value, so a same-line-only escape silently stops working. Verified against real
+  // oxfmt output — the hex ends up ABOVE the comment, which is why preceding-line support alone
+  // does not fix it and the walk goes backwards over the declaration.
+  it('reaches back over an oxfmt-reflowed CSS declaration', () => {
+    const f = find(
+      `.root {
+  background-color: var(
+    --mantine-color-body,
+    #232326
+  ); /* theme-allow raw-hex — Mantine body fallback for the pre-paint value */
+}`,
+      'src/styles.css',
+    )
+    expect(kinds(f)).not.toContain('raw-hex')
+  })
+
+  it('stops the backward walk at the previous declaration', () => {
+    const f = find(
+      `.root {
+  color: #112233;
+  background: var(
+    #232326
+  ); /* theme-allow raw-hex — fallback */
+}`,
+      'src/styles.css',
+    )
+    expect(f.filter((x) => x.kind === 'raw-hex')).toHaveLength(1)
+    expect(f.find((x) => x.kind === 'raw-hex')?.line).toBe(2)
+  })
+})
+
+// ── 22. theme-allow rule scoping + accountability ────────────────────────────
+
+describe('theme-allow scoping', () => {
+  it('a scoped annotation waives only the kind it names', () => {
+    const f = find(
+      `<Box p={${SPACE_SCALE.md}} style={{ color: '#ff0000' }} /> // theme-allow raw-hex — vendor brand`,
+    )
+    expect(kinds(f)).not.toContain('raw-hex')
+    expect(kinds(f)).toContain('raw-spacing')
+  })
+
+  it('a bare annotation still waives everything (back-compat) but is reported', () => {
+    const f = find(`<Box p={${SPACE_SCALE.md}} style={{ color: '#ff0000' }} /> // theme-allow`)
+    expect(kinds(f)).not.toContain('raw-hex')
+    expect(kinds(f)).not.toContain('raw-spacing')
+    expect(kinds(f)).toContain('theme-allow-unscoped')
+  })
+
+  it('reports a reason-less scoped annotation too', () => {
+    const f = find(`<Box style={{ color: '#ff0000' }} /> // theme-allow raw-hex`)
+    expect(kinds(f)).toContain('theme-allow-unscoped')
+  })
+
+  it('accepts the accountable form silently', () => {
+    const f = find(
+      `<Box style={{ color: '#ff0000' }} /> // theme-allow raw-hex — vendor brand asset`,
+    )
+    expect(f).toHaveLength(0)
+  })
+
+  it('accepts a basalt/-prefixed plugin rule id as accountable', () => {
+    const f = find(`const x = 1 // theme-allow basalt/hand-rolled-plot — multi-pane, not one plot`)
+    expect(f).toHaveLength(0)
+  })
+
+  // A prose reason is introduced with a separator — the shape every annotation in the wild
+  // already has (`theme-allow: …`, `theme-allow — …`). That is what keeps prose out of the rule-id
+  // slot without having to guess whether an unknown word is a reason or a typo.
+  it('reads a separated reason as a reason, not as rule ids', () => {
+    for (const annotation of ['theme-allow: legacy vendor asset', 'theme-allow — legacy vendor']) {
+      const f = find(`<Box style={{ color: '#ff0000' }} /> // ${annotation}`)
+      expect(kinds(f)).not.toContain('raw-hex')
+    }
+  })
+
+  // ── fail closed: a waiver that names a rule id must never widen into a blanket one ────────────
+
+  it('waives NOTHING when the named rule id is a typo', () => {
+    const f = find(
+      `<Box p={${SPACE_SCALE.md}} style={{ color: '#ff0000' }} /> // theme-allow raw-hexx — vendor brand`,
+    )
+    // The old parse consumed no id, fell through to the empty-`rules` branch, and read the whole
+    // thing as the LEGACY BLANKET form: one mistyped character silenced every kind on the line.
+    expect(kinds(f)).toContain('raw-hex')
+    expect(kinds(f)).toContain('raw-spacing')
+  })
+
+  it('names the unknown id rather than reporting it as "no rule id"', () => {
+    const f = find(`const c = '#ff0000' // theme-allow raw-hexx — vendor brand`)
+    const unscoped = f.find((v) => v.kind === 'theme-allow-unscoped')
+    expect(unscoped?.token).toContain("unknown rule id 'raw-hexx'")
+  })
+
+  it('a typo is never more permissive than the same annotation spelled correctly', () => {
+    const correct = find(`const c = '#ff0000' // theme-allow raw-hex — vendor brand`)
+    const typo = find(`const c = '#ff0000' // theme-allow raw-hexx — vendor brand`)
+    expect(typo.length).toBeGreaterThanOrEqual(correct.length)
+  })
+
+  it('still waives the ids it got right in a mixed list', () => {
+    const f = find(
+      `<Box p={${SPACE_SCALE.md}} style={{ color: '#ff0000' }} /> // theme-allow raw-hex, raw-spacingg — mixed`,
+    )
+    expect(kinds(f)).not.toContain('raw-hex')
+    expect(kinds(f)).toContain('raw-spacing')
+  })
+
+  it('says "not waived", not "waives nothing", when an id in the list DID resolve', () => {
+    const f = find(`const c = '#ff0000' // theme-allow raw-hex, raw-spacingg — mixed`)
+    const unscoped = f.find((v) => v.kind === 'theme-allow-unscoped')
+    expect(unscoped?.token).toBe("theme-allow (unknown rule id 'raw-spacingg' — not waived)")
+    // The claim has to match what the same run actually did: raw-hex IS waived here.
+    expect(kinds(f)).not.toContain('raw-hex')
+  })
+
+  // ── prose after a resolved id is prose, not a typo ────────────────────────────────────────────
+  //
+  // The id slot closes at the first space no comma opened. `theme-allow raw-surface sub-scale …`
+  // is one em-dash away from annotations this package itself ships (see ChartLegend), and reading
+  // `sub-scale` as an attempted id made a scoped, reasoned waiver report as unscoped.
+
+  it('reads an unknown word after a resolved id as the reason', () => {
+    const f = find(
+      'const s = { borderRadius: 3 } // theme-allow raw-surface sub-scale legend corner',
+    )
+    expect(f).toHaveLength(0)
+  })
+
+  it('still fails closed on a typo in the FIRST id slot, separator or not', () => {
+    for (const annotation of [
+      'theme-allow raw-hexx — vendor',
+      'theme-allow raw-hexx vendor asset',
+    ]) {
+      expect(kinds(find(`const c = '#ff0000' // ${annotation}`))).toContain('raw-hex')
+    }
+  })
+
+  // Documented break, not a regression: a reason with NO separator introducing it sits in the id
+  // slot, names no rule, and therefore waives nothing. Kept as a test so the behaviour is pinned
+  // rather than rediscovered — MIGRATING.md carries the consumer-facing half.
+  it('does not waive a reason written with no separator introducing it', () => {
+    const f = find(`const c = '#ff0000' // theme-allow legacy vendor asset`)
+    expect(f.find((v) => v.kind === 'raw-hex')?.severity).toBe('error')
+    expect(f.find((v) => v.kind === 'theme-allow-unscoped')?.token).toContain(
+      "unknown rule id 'legacy' — waives nothing",
+    )
+  })
+
+  // `in` walks the prototype chain, so `'constructor' in GUARD_RULES` was true and a reason
+  // starting with that word scoped the waiver to a rule that does not exist.
+  it('does not resolve an Object.prototype key as a rule id', () => {
+    const f = find(`const c = '#ff0000' // theme-allow constructor — inherited key, not a rule`)
+    expect(kinds(f)).toContain('raw-hex')
+  })
+
+  it('accepts an id belonging to a plugin rule that does not honour theme-allow', () => {
+    // Not a guard kind and not theme-allow-aware — but a REAL id, so it parses as accountable
+    // rather than being read as a typo (or, before, as a blanket waiver).
+    const f = find(`const x = 1 // theme-allow ai-sdk-major — intentional producer/consumer skew`)
+    expect(f).toHaveLength(0)
+  })
+
+  it('ships theme-allow-unscoped as a warning, not a build failure', () => {
+    const f = find(`const x = 1 // theme-allow`)
+    expect(f.every((v) => v.severity === 'warn')).toBe(true)
+  })
+
+  // The annotation itself lives in a comment; a `theme-allow` in real code must not waive anything.
+  it('ignores the token when it is not inside a comment', () => {
+    const f = find(`const label = 'theme-allow'\nconst c = '#ff0000'`)
+    expect(kinds(f)).toContain('raw-hex')
+  })
+})
+
+// ── 22b. theme-allow — the prefix rule and the two scopes, exhaustively ──────
+//
+// Three holes in one contract across two rounds, so this is a matrix rather than a case.
+
+describe('theme-allow — annotation vs prose (the prefix rule)', () => {
+  const HEX = `const c = '#ff0000'`
+
+  /** `comment` on its own line directly above a raw hex — the placement that waives the line below. */
+  function above(comment: string): GuardKind[] {
+    return kinds(find(`${comment}\n${HEX}`))
+  }
+
+  // ── ACCEPTED — every shape a consumer actually writes ──────────────────────
+
+  it.each([
+    '// theme-allow raw-hex — vendor brand',
+    '//theme-allow raw-hex — no space after the marker',
+    '  // theme-allow raw-hex — indented',
+    '/* theme-allow raw-hex — a block comment */',
+    '{/* theme-allow raw-hex — a JSX expression comment */}',
+    '/**\n * theme-allow raw-hex — a docblock gutter line\n */',
+    '// theme-allow',
+  ])('%s is an annotation and waives the line below', (comment) => {
+    expect([comment, above(comment).includes('raw-hex')]).toEqual([comment, false])
+  })
+
+  it('a trailing annotation waives its own line', () => {
+    expect(kinds(find(`${HEX} // theme-allow raw-hex — vendor brand`))).not.toContain('raw-hex')
+  })
+
+  // The reason wrapping to a second line — or a docblock's own `*/` — used to absorb the whole
+  // waiver, so the natural multi-line shape silently waived nothing. argo hit it three times in one
+  // upgrade, each time on a comment that looked correct.
+  it('a wrapped reason still reaches the code line under it', () => {
+    const f = find(
+      `// theme-allow raw-hex — the vendor brand hex, kept in sync with
+// the marketing site's own palette
+${HEX}`,
+    )
+    expect(kinds(f)).not.toContain('raw-hex')
+  })
+
+  it('a blank line ends the block — the waiver does not jump it', () => {
+    expect(
+      kinds(
+        find(`// theme-allow raw-hex — about something else
+
+${HEX}`),
+      ),
+    ).toContain('raw-hex')
+  })
+
+  it('a trailing annotation does NOT walk forward — it stays on its own line', () => {
+    expect(kinds(find(`const ok = 1 // theme-allow raw-hex — about this line\n${HEX}`))).toContain(
+      'raw-hex',
+    )
+  })
+
+  // ── REJECTED — prose that MENTIONS the token ──────────────────────────────
+
+  // The linewatch defect, and the one that made this a false NEGATIVE: a file documenting its own
+  // waivers disarmed itself. Every shape here is lifted from real consumer or basalt source.
+  it.each([
+    '// see the `theme-allow` contract for how exceptions are written',
+    '/* Since 1.20.0 a `theme-allow` that names a rule declares the file */',
+    '/**\n * A `theme-allow` with a reason declares the whole FILE wherever it is written.\n */',
+    '// each chart carries a theme-allow saying why',
+    '// documented at theme-allow raw-hex — this sentence is prose, not a waiver',
+  ])('%s is prose and waives nothing', (comment) => {
+    expect([comment, above(comment).includes('raw-hex')]).toEqual([comment, true])
+  })
+
+  // A kind name written in prose used to consume no id, fall through to `rules: []`, and read as
+  // the blanket form — so a sentence about the reporting rule switched every rule off.
+  it('a comment starting with the longer word `theme-allow-unscoped` is not an annotation', () => {
+    expect(above('// theme-allow-unscoped is what reports a bare waiver')).toContain('raw-hex')
+  })
+
+  it('the token inside a string literal is code, not an annotation', () => {
+    expect(kinds(find(`const doc = 'theme-allow raw-hex — x'\n${HEX}`))).toContain('raw-hex')
+  })
+
+  // Prose is not an annotation for REPORTING either — otherwise every sentence documenting the
+  // escape hatch becomes a theme-allow-unscoped finding (this package's own guard/types.ts).
+  it('prose mentioning the token is not reported as an unscoped waiver', () => {
+    expect(above('// see the `theme-allow` contract')).not.toContain('theme-allow-unscoped')
+  })
+})
+
+describe('theme-allow-file — whole-file scope', () => {
+  const SRC = [`const a = '#ff0000'`, `const b = '#00ff00'`, `const c = '#0000ff'`].join('\n')
+
+  it('waives every line in the file, not just the one below it', () => {
+    const f = find(`// theme-allow-file raw-hex — the vendor brand sheet\n${SRC}`)
+    expect(kinds(f)).not.toContain('raw-hex')
+  })
+
+  it('reaches BACKWARDS too — a declaration at the bottom covers the top', () => {
+    const f = find(`${SRC}\n// theme-allow-file raw-hex — the vendor brand sheet`)
+    expect(kinds(f)).not.toContain('raw-hex')
+  })
+
+  it('waives only the kinds it names', () => {
+    const f = find(
+      `// theme-allow-file raw-hex — vendor brand\n${SRC}\n<Box style={{ display: 'flex' }} />`,
+    )
+    expect(kinds(f)).not.toContain('raw-hex')
+    expect(kinds(f)).toContain('inline-display')
+  })
+
+  // File scope is the widest waiver in the contract, so it is the one that has to name what it
+  // waives. A bare `theme-allow-file` is `exemptRules` without the config review.
+  it('a BARE theme-allow-file waives nothing, and is reported as unscoped', () => {
+    const f = find(`// theme-allow-file — everything in here is bespoke\n${SRC}`)
+    expect(kinds(f)).toContain('raw-hex')
+    expect(kinds(f)).toContain('theme-allow-unscoped')
+  })
+
+  it("a theme-allow-file naming a typo'd id waives nothing", () => {
+    const f = find(`// theme-allow-file raw-hexx — vendor brand\n${SRC}`)
+    expect(kinds(f)).toContain('raw-hex')
+    expect(kinds(f)).toContain('theme-allow-unscoped')
+  })
+
+  it('an id-and-reason theme-allow-file is accountable — no unscoped finding', () => {
+    const f = find(`// theme-allow-file raw-hex — the vendor brand sheet\n${SRC}`)
+    expect(kinds(f)).not.toContain('theme-allow-unscoped')
+  })
+
+  // The complement, and the half 1.20.0 did not deliver: naming a rule AND giving a reason used to
+  // promote a waiver to the whole file in the oxlint plugin, so whole-file was the only expressible
+  // scope. The guard's plain `theme-allow` has always been line-scoped, and stays that way.
+  it('a plain theme-allow with an id and a reason stays line-scoped', () => {
+    const f = find(`// theme-allow raw-hex — vendor brand\n${SRC}`)
+    expect(kinds(f).filter((k) => k === 'raw-hex')).toHaveLength(2)
+  })
+})
+
+/** A two-hex manifest with `extra` (an annotation member, or nothing) inserted at the top. */
+const MANIFEST = (extra: string) =>
+  `{\n${extra}  "theme_color": "#27272a",\n  "background_color": "#27272a"\n}\n`
+
+describe('theme-allow in JSON — the "basalt:theme-allow" member', () => {
+  it('a webmanifest hex reports with no annotation — the 1.20.0 baseline', () => {
+    const f = checkSource(MANIFEST(''), 'public/site.webmanifest', DEFAULT_GUARD_CONFIG)
+    expect(kinds(f).filter((k) => k === 'raw-hex')).toHaveLength(2)
+  })
+
+  // JSON has no comments, so from 1.20.0 the whole file class was permanently unwaivable and the
+  // printed remedy prescribed a comment the file cannot carry. Both consumers that hit it fell back
+  // to a blanket `exemptRules` entry — the shape the release was spent retiring.
+  it('a "basalt:theme-allow-file" member declares the file', () => {
+    const f = checkSource(
+      MANIFEST('  "basalt:theme-allow-file": "raw-hex — a manifest cannot read a CSS variable",\n'),
+      'public/site.webmanifest',
+      DEFAULT_GUARD_CONFIG,
+    )
+    expect(kinds(f)).not.toContain('raw-hex')
+  })
+
+  it('a "basalt:theme-allow" member is line-scoped — its own line and the one below', () => {
+    const f = checkSource(
+      MANIFEST('  "basalt:theme-allow": "raw-hex — the theme color only",\n'),
+      'public/site.webmanifest',
+      DEFAULT_GUARD_CONFIG,
+    )
+    expect(kinds(f).filter((k) => k === 'raw-hex')).toHaveLength(1)
+  })
+
+  it('the member must name its ids — a bare one waives nothing', () => {
+    const f = checkSource(
+      MANIFEST('  "basalt:theme-allow-file": "everything in here is bespoke",\n'),
+      'public/site.webmanifest',
+      DEFAULT_GUARD_CONFIG,
+    )
+    expect(kinds(f)).toContain('raw-hex')
+  })
+
+  it('works in a plain .json too, not only a manifest', () => {
+    const f = checkSource(
+      MANIFEST('  "basalt:theme-allow-file": "raw-hex — vendor brand data",\n'),
+      'src/brand.json',
+      DEFAULT_GUARD_CONFIG,
+    )
+    expect(kinds(f)).not.toContain('raw-hex')
+  })
+
+  // The member is JSON-only: in TS that string is a value, and a value that could switch off a rule
+  // is the hole `stripComments` exists to close.
+  it('the same string in a TS file is code, not an annotation', () => {
+    const f = find(`const cfg = { "basalt:theme-allow-file": "raw-hex — x" }\nconst c = '#ff0000'`)
+    expect(kinds(f)).toContain('raw-hex')
+  })
+})
+
+// ── 23. surface-shadow-override ──────────────────────────────────────────────
+
+describe('surface-shadow-override', () => {
+  it('flags a token-composed shadow that REPLACES card depth', () => {
+    const f = find('const s = { boxShadow: `0 0 0 2px ${VX.accent}` }')
+    expect(kinds(f)).toContain('surface-shadow-override')
+  })
+
+  it('does NOT flag one that composes WITH card depth', () => {
+    const f = find('const s = { boxShadow: `${VX.shadowCard}, 0 0 0 2px ${VX.accent}` }')
+    expect(kinds(f)).not.toContain('surface-shadow-override')
+  })
+
+  it('does NOT flag a var(--vx-shadow-…) reference', () => {
+    const f = find(`const s = { boxShadow: 'var(--vx-shadow-card)' }`)
+    expect(kinds(f)).not.toContain('surface-shadow-override')
+  })
+
+  it('still reports a fully literal shadow as raw-surface, not the new kind', () => {
+    const f = find(`const s = { boxShadow: '0 1px 3px black' }`)
+    expect(kinds(f)).toContain('raw-surface')
+    expect(kinds(f)).not.toContain('surface-shadow-override')
+  })
+
+  it('ships as a warning for its grace minor', () => {
+    const f = find('const s = { boxShadow: `0 0 0 2px ${VX.accent}` }')
+    expect(f.find((v) => v.kind === 'surface-shadow-override')?.severity).toBe('warn')
+  })
+})
+
+// ── 24. css-raw-surface ──────────────────────────────────────────────────────
+
+describe('css-raw-surface', () => {
+  it('flags a kebab-case border-radius literal in CSS', () => {
+    const f = find('.a { border-radius: 4px; }', 'src/a.module.css')
+    expect(kinds(f)).toContain('css-raw-surface')
+  })
+
+  it('does NOT flag a var(--vx-radius-…) reference', () => {
+    const f = find('.a { border-radius: var(--vx-radius-card); }', 'src/a.module.css')
+    expect(kinds(f)).not.toContain('css-raw-surface')
+  })
+
+  it('does NOT flag a sub-scale micro-corner below the 4px floor', () => {
+    const f = find('.a { border-radius: 2px; }', 'src/a.module.css')
+    expect(kinds(f)).not.toContain('css-raw-surface')
+  })
+
+  it('does NOT flag the circle/pill shape values', () => {
+    const f = find('.a { border-radius: 50%; }\n.b { border-radius: 9999px; }', 'src/a.module.css')
+    expect(kinds(f)).not.toContain('css-raw-surface')
+  })
+
+  it('flags a literal box-shadow in CSS', () => {
+    const f = find('.a { box-shadow: 0 1px 3px rgba(0,0,0,0.2); }', 'src/a.module.css')
+    expect(kinds(f)).toContain('css-raw-surface')
+  })
+
+  it('never fires in TSX (the camelCase dialect is raw-surface’s)', () => {
+    const f = find(`<div style={{ borderRadius: 8 }} />`)
+    expect(kinds(f)).not.toContain('css-raw-surface')
+    expect(kinds(f)).toContain('raw-surface')
+  })
+})
+
+// ── 25. inline-font-size ─────────────────────────────────────────────────────
+
+describe('inline-font-size', () => {
+  it('flags a unitless inline fontSize (the check-theme-only CI gap)', () => {
+    const f = find(`<div style={{ padding: '6px 8px', fontSize: 11 }} />`)
+    expect(kinds(f)).toContain('inline-font-size')
+  })
+
+  it('flags a px font-size in CSS', () => {
+    const f = find('.a { font-size: 13px; }', 'src/a.module.css')
+    expect(kinds(f)).toContain('inline-font-size')
+  })
+
+  it('does NOT flag a token reference', () => {
+    const f = find(`<div style={{ fontSize: VX.text.sm }} />`)
+    expect(kinds(f)).not.toContain('inline-font-size')
+  })
+
+  it('does NOT flag a relative unit', () => {
+    const f = find('.a { font-size: 0.8rem; }', 'src/a.module.css')
+    expect(kinds(f)).not.toContain('inline-font-size')
+  })
+})
+
+// ── 26. hidden-inline-style ──────────────────────────────────────────────────
+
+describe('hidden-inline-style', () => {
+  it('flags a multi-line-formatted raw div the line scan cannot see', () => {
+    const f = find(
+      `export const C = () => (
+  <div
+    className="x"
+    style={{
+      display: 'flex',
+      padding: 12,
+    }}
+  />
+)`,
+    )
+    expect(kinds(f)).toContain('hidden-inline-style')
+  })
+
+  it('flags a hoisted style const passed by identifier', () => {
+    const f = find(
+      `const wrapperStyle = { position: 'relative', width: '100%' }
+export const C = () => <div className="x" style={wrapperStyle} />`,
+    )
+    expect(kinds(f)).toContain('hidden-inline-style')
+  })
+
+  it('does NOT double-report what raw-html-layout already owns', () => {
+    const f = find(`<div style={{ display: 'flex', padding: 12 }} />`)
+    expect(kinds(f)).toContain('raw-html-layout')
+    expect(kinds(f)).not.toContain('hidden-inline-style')
+  })
+
+  it('does NOT flag a hoisted const with no layout/surface property', () => {
+    const f = find(
+      `const labelStyle = { fontWeight: 500 }
+export const C = () => <div style={labelStyle} />`,
+    )
+    expect(kinds(f)).not.toContain('hidden-inline-style')
+  })
+
+  it('ships as a warning for its grace minor', () => {
+    const f = find(
+      `const wrapperStyle = { position: 'relative', width: '100%' }
+export const C = () => <div style={wrapperStyle} />`,
+    )
+    expect(f.find((v) => v.kind === 'hidden-inline-style')?.severity).toBe('warn')
+  })
+})
+
+// ── 27. raw-color-fn on computed colors ──────────────────────────────────────
+
+describe('raw-color-fn — computed values', () => {
+  it('does NOT flag a color function whose first channel is interpolated', () => {
+    const f = find('const swatch = `rgb(${px[0]}, ${px[1]}, ${px[2]})`')
+    expect(kinds(f)).not.toContain('raw-color-fn')
+  })
+
+  it('still flags a literal color with only a variable alpha', () => {
+    const f = find('const s = `rgba(0, 0, 0, ${opacity})`')
+    expect(kinds(f)).toContain('raw-color-fn')
+  })
+})
+
+// ── 28. generated-file marker ────────────────────────────────────────────────
+
+describe('@generated basalt-ui marker', () => {
+  const HEADER = `${GENERATED_HEADER_LINE}\n/* basalt-ui 1.20.0 — \`basalt-ui tokens:css --only core\` */\n`
+  const BODY = ':root {\n  --vx-fill-gray: #717176;\n  --vx-axis: rgba(255, 255, 255, 0.6);\n}\n'
+  const EMITTED = `${HEADER}${BODY}`
+
+  it('skips a file basalt itself emitted', () => {
+    expect(find(EMITTED, 'src/styles/basalt-tokens.css')).toHaveLength(0)
+  })
+
+  // ── the forgery half: the marker was a whole-file bypass anyone could hand-write ──────────────
+
+  it('ignores the marker entirely outside a .css file', () => {
+    const forged = `${HEADER}export const C = () => <div style={{ color: '#ff0000', padding: 18 }} />\n`
+    expect(kinds(find(forged, 'src/a.tsx'))).toContain('raw-hex')
+    expect(kinds(find(forged, 'src/a.tsx'))).toContain('inline-spacing')
+  })
+
+  it('does not exempt hand-written CSS wearing the header', () => {
+    const forged = `${HEADER}.btn { color: #ff0000; }\n`
+    expect(kinds(find(forged, 'src/a.css'))).toContain('raw-hex')
+  })
+
+  it('does not exempt a generated sheet with an ordinary rule smuggled onto the end', () => {
+    const smuggled = `${EMITTED}.btn { color: #ff0000; }\n`
+    expect(kinds(find(smuggled, 'src/tokens.css'))).toContain('raw-hex')
+  })
+
+  it('requires the provenance line, not just the marker', () => {
+    const bare = `${GENERATED_HEADER_LINE}\n${BODY}`
+    expect(kinds(find(bare, 'src/tokens.css'))).toContain('raw-hex')
+    const loose = `/* @generated basalt-ui */\n${BODY}`
+    expect(kinds(find(loose, 'src/tokens.css'))).toContain('raw-hex')
+  })
+
+  // ── the header WINDOW: exactly the two lines the emitter writes, and no more ──────────────────
+
+  it('honours the header only on lines 1-2', () => {
+    const onLineOne = `${HEADER}${BODY}`
+    expect(find(onLineOne, 'src/tokens.css')).toHaveLength(0)
+    // One blank line ahead of it is already outside the window — the boundary is exact, not "the
+    // first few lines", which is what let a marker be pasted in above unrelated content.
+    const shifted = `\n${HEADER}${BODY}`
+    expect(kinds(find(shifted, 'src/tokens.css'))).toContain('raw-hex')
+    const buried = `${'\n'.repeat(8)}${HEADER}${BODY}`
+    expect(kinds(find(buried, 'src/tokens.css'))).toContain('raw-hex')
+  })
+
+  // ── the second forgery round: the line-shape allowlist itself was forgeable ───────────────────
+  //
+  // Both of the first two were demonstrated against the real `checkSource`, and both were valid,
+  // browser-effective CSS bought a WHOLE-FILE exemption. Every case below must report — a passing
+  // `toHaveLength(0)` here would mean the hole is open again.
+
+  const forgeries: ReadonlyArray<readonly [string, string]> = [
+    // A `;` inside a custom-property value smuggled two ordinary declarations onto a line the
+    // allowlist read as "a basalt custom property".
+    [
+      'a semicolon inside a custom-property value',
+      `${HEADER}:root {\n  --vx-pad: 0; box-shadow: 0 0 0 1px #ff0000; border-radius: 11px;\n}\n`,
+    ],
+    // The comment branch was `\/\*.*` — it never required the comment to CLOSE, so anything after
+    // `*/` rode along.
+    ['a comment that never closes', `${HEADER}/* x */ .btn { color: #ff0000; }\n`],
+    // A comment reopened mid-line: closing and reopening keeps the line comment-SHAPED at both
+    // ends while the middle is a live declaration.
+    ['a comment reopened mid-line', `${HEADER}:root {\n  /* a */ color: #ff0000 /* b */\n}\n`],
+    // The first line of a multi-line declaration ends in `,`, which is also how a selector list
+    // continues — the depth check is what tells them apart.
+    [
+      'a multi-line declaration whose first line ends in a comma',
+      `${HEADER}.btn {\n  box-shadow: 0 0 0 1px #ff0000,\n    0 0 2px #00ff00;\n}\n`,
+    ],
+    // The at-rule branch permitted `;`, so a declaration could ride behind `@…;`.
+    ['a declaration behind an at-rule', `${HEADER}@media all; color: #ff0000;\n`],
+    // No trailing `;` anywhere, so nothing to split on.
+    ['a whole rule on one line with no semicolon', `${HEADER}.btn { color: #ff0000 }\n`],
+    [
+      'a rule reopened after a closing brace',
+      `${HEADER}:root {\n  --vx-a: #fff;\n} .btn { color: #ff0000; }\n`,
+    ],
+    ['a nested block', `${HEADER}:root {\n  .btn {\n    color: #ff0000;\n  }\n}\n`],
+  ]
+
+  for (const [what, source] of forgeries) {
+    it(`reports ${what}`, () => {
+      expect(find(source, 'src/tokens.css').length).toBeGreaterThan(0)
+    })
+  }
+
+  it('never skips a line carrying theme-allow, so a hidden waiver still reports', () => {
+    // Without this the annotation would waive the line below AND its own unscoped report, because
+    // a bare `/* theme-allow */` is comment-SHAPED and would otherwise be a skippable line.
+    const smuggled = `${HEADER}/* theme-allow */\n.btn { color: #ff0000; }\n`
+    expect(kinds(find(smuggled, 'src/tokens.css'))).toContain('theme-allow-unscoped')
+  })
+
+  it('exempts LINES, not the file — a smuggled rule reports without burying it in token values', () => {
+    const smuggled = `${EMITTED}.btn { color: #ff0000; }\n`
+    const f = find(smuggled, 'src/tokens.css')
+    expect(f.map((x) => x.line)).toEqual([7])
+    expect(kinds(f)).toEqual(['raw-hex'])
+  })
+})
+
+// ── 29. markup files ─────────────────────────────────────────────────────────
+
+describe('markup files (index.html / *.webmanifest)', () => {
+  it('flags raw hex in index.html', () => {
+    const f = find(`<meta name="theme-color" content="#EDEFF2" />`, 'index.html')
+    expect(kinds(f)).toContain('raw-hex')
+  })
+
+  it('flags raw hex in a webmanifest', () => {
+    const f = find(`{ "theme_color": "#242424" }`, 'public/site.webmanifest')
+    expect(kinds(f)).toContain('raw-hex')
+  })
+
+  it('does not apply the JSX/CSS-in-JS kinds there', () => {
+    const f = find(`<div style="padding: 18px"><input /></div>`, 'index.html')
+    expect(kinds(f)).not.toContain('raw-form-control')
+    expect(kinds(f)).not.toContain('inline-spacing')
+  })
+
+  it('honours a theme-allow inside an HTML comment', () => {
+    const f = find(
+      `<!-- theme-allow raw-hex — favicon mask color -->\n<meta content="#EDEFF2" />`,
+      'index.html',
+    )
+    expect(kinds(f)).not.toContain('raw-hex')
+  })
+})
+
+// ── 30. tokens-only profile ──────────────────────────────────────────────────
+
+describe("profile: 'tokens-only'", () => {
+  const TOKENS_ONLY = { ...DEFAULT_GUARD_CONFIG, profile: 'tokens-only' as const }
+
+  it('drops the kinds whose remedy is a Mantine component', () => {
+    const src = `<input /> // a Mantine-free consumer has no TextInput to reach for`
+    expect(kinds(checkSource(src, PATH, DEFAULT_GUARD_CONFIG))).toContain('raw-form-control')
+    expect(kinds(checkSource(src, PATH, TOKENS_ONLY))).not.toContain('raw-form-control')
+  })
+
+  it('keeps the color kinds — the token layer IS what they consume', () => {
+    const f = checkSource(`.a { color: #ff0000; }`, 'src/a.css', TOKENS_ONLY)
+    expect(kinds(f)).toContain('raw-hex')
+  })
+
+  /**
+   * Every kind, classified by hand: is its remedy a Mantine component, a Mantine prop, or the React
+   * theme factory? The exhaustive literal IS the test — the previous spot check of four kinds is
+   * how `hidden-inline-style` shipped ENABLED under the profile, telling a Mantine-free app to
+   * import Box/Flex in a message copied word for word from `raw-html-layout`, which is disabled.
+   * A new kind fails the first assertion until it is classified here.
+   */
+  const MANTINE_COUPLED: Record<GuardKind, boolean> = {
+    'raw-hex': false,
+    'raw-color-fn': false,
+    'localstorage-theme': true,
+    'off-identity-accent': true,
+    'mantine-shade-index': true,
+    'raw-spacing': true,
+    'raw-radius': true,
+    'raw-surface': false,
+    'card-with-border': true,
+    'off-system-surface-var': true,
+    'raw-html-layout': true,
+    'inline-spacing': true,
+    'inline-display': true,
+    'raw-visx-axis': true,
+    'raw-motion-value': true,
+    'unframed-chart': true,
+    'chart-missing-aria-label': true,
+    'raw-form-control': true,
+    'sub-16-input-font': true,
+    'raw-font-family': false,
+    'theme-allow-unscoped': false,
+    'surface-shadow-override': false,
+    'css-raw-surface': false,
+    'inline-font-size': false,
+    'hidden-inline-style': true,
+  }
+
+  it('classifies every kind in the registry — the table is exhaustive', () => {
+    expect(Object.keys(MANTINE_COUPLED).toSorted()).toEqual(Object.keys(GUARD_RULES).toSorted())
+    expect(Object.keys(MANTINE_COUPLED)).toHaveLength(25)
+  })
+
+  it('the disabled set is exactly the Mantine-coupled half — a complete partition', () => {
+    for (const [kind, coupled] of Object.entries(MANTINE_COUPLED) as [GuardKind, boolean][]) {
+      expect([kind, TOKENS_ONLY_DISABLED_KINDS.has(kind)]).toEqual([kind, coupled])
+    }
+    expect(TOKENS_ONLY_DISABLED_KINDS.size).toBe(
+      Object.values(MANTINE_COUPLED).filter(Boolean).length,
+    )
+  })
+
+  it('no surviving kind tells a Mantine-free app to reach for a Mantine component', () => {
+    const MANTINE_REMEDY =
+      /@mantine\/|\b(?:Box|Flex|Grid|Stack|Group|TextInput|NumberInput|Select|Textarea)\b/
+    for (const kind of Object.keys(GUARD_RULES) as GuardKind[]) {
+      if (TOKENS_ONLY_DISABLED_KINDS.has(kind)) continue
+      expect([kind, MANTINE_REMEDY.test(GUARD_RULES[kind].message)]).toEqual([kind, false])
+    }
+  })
+
+  it("hidden-inline-style is off — its remedy is raw-html-layout's, word for word", () => {
+    const src =
+      "const s = { display: 'flex', padding: 18 }\nexport const D = () => <div style={s} />"
+    expect(kinds(checkSource(src, PATH, DEFAULT_GUARD_CONFIG))).toContain('hidden-inline-style')
+    expect(kinds(checkSource(src, PATH, TOKENS_ONLY))).not.toContain('hidden-inline-style')
+  })
+})
+
+// ── 31. remedy + waiver hint — what a report actually PRINTS ─────────────────
+
+describe('guardKindRemedy', () => {
+  // `check-theme`'s `Fix:` epilogue read a hand-duplicated subset of these, and the subset was
+  // missing every kind added at 1.20.0. All five of those ship `warn` under grace, so the findings
+  // whose whole argument is "this looks correct and is not" arrived with no argument — only "add a
+  // `theme-allow`", which reads as advice to waive. Sourcing it from the registry retires the
+  // duplicate instead of extending it, and this test is what stops a new kind shipping without one.
+  it('gives every kind a remedy, prefixed with the kind id', () => {
+    for (const kind of Object.keys(GUARD_RULES) as GuardKind[]) {
+      const remedy = guardKindRemedy(kind)
+      expect([kind, remedy.startsWith(`${kind}: `)]).toEqual([kind, true])
+      expect([kind, remedy.length > kind.length + 20]).toEqual([kind, true])
+    }
+  })
+
+  it('covers the five 1.20.0 kinds that the duplicated table did not', () => {
+    for (const kind of [
+      'surface-shadow-override',
+      'css-raw-surface',
+      'inline-font-size',
+      'hidden-inline-style',
+      'theme-allow-unscoped',
+    ] as GuardKind[]) {
+      expect([kind, guardKindRemedy(kind)]).toEqual([kind, `${kind}: ${GUARD_RULES[kind].message}`])
+    }
+  })
+
+  // argo: the kind fires on a fixed dock replacing card depth, where the right answer is the
+  // overlay tier — and `SHADOW_KEEPS_CARD_DEPTH` accepts any `--vx-shadow-*`, so the message was
+  // narrower than the check and pointed away from the correct token.
+  it('surface-shadow-override names the overlay tier, not only the card one', () => {
+    expect(guardKindRemedy('surface-shadow-override')).toContain('--vx-shadow-overlay')
+  })
+})
+
+describe('guardWaiverHint', () => {
+  // The `Fix:` closer prescribed a `theme-allow` COMMENT for every file class, including the one
+  // 1.20.0 had just started scanning and which cannot hold a comment at all.
+  it('never prescribes a comment to a file that cannot carry one', () => {
+    for (const relPath of ['public/site.webmanifest', 'src/brand.json']) {
+      expect([relPath, /theme-allow[^-]/.test(guardWaiverHint(relPath))]).toEqual([relPath, false])
+      expect([relPath, guardWaiverHint(relPath)]).toEqual([
+        relPath,
+        expect.stringContaining('basalt:theme-allow-file'),
+      ])
+    }
+  })
+
+  // rollhook's sharper point: a manifest hex can never be RIGHT, because a manifest cannot
+  // reference a CSS variable — so the value is a hand-copy that drifts. Both consumers that hit it
+  // found a dead colour. The remedy is to stop hand-writing the file.
+  it('points a manifest at basaltAppPlugin first, and the annotation second', () => {
+    const hint = guardWaiverHint('public/site.webmanifest')
+    expect(hint).toContain('basaltAppPlugin')
+    expect(hint.indexOf('basaltAppPlugin')).toBeLessThan(hint.indexOf('basalt:theme-allow-file'))
+  })
+
+  it('prescribes the comment form everywhere a comment exists', () => {
+    for (const relPath of ['src/App.tsx', 'src/app.css', 'index.html']) {
+      expect([relPath, guardWaiverHint(relPath)]).toEqual([
+        relPath,
+        expect.stringContaining('theme-allow <rule-id>'),
+      ])
+    }
+  })
+
+  it('names both scopes, so the narrow one is the one a reader reaches for first', () => {
+    const hint = guardWaiverHint('src/App.tsx')
+    expect(hint.indexOf('theme-allow <rule-id>')).toBeLessThan(hint.indexOf('theme-allow-file'))
+  })
+
+  // Every hint has to name a mechanism that EXISTS — the defect it replaces was a hint that did
+  // not. These two assert the guard actually honours what each hint prescribes.
+  it('the JSON hint names a member the guard honours', () => {
+    const f = checkSource(
+      '{\n  "basalt:theme-allow-file": "raw-hex — a manifest cannot read a CSS variable",\n  "theme_color": "#27272a"\n}\n',
+      'public/site.webmanifest',
+      DEFAULT_GUARD_CONFIG,
+    )
+    expect(kinds(f)).not.toContain('raw-hex')
+  })
+
+  it('the comment hint names a form the guard honours', () => {
+    expect(kinds(find(`// theme-allow raw-hex — vendor brand\nconst c = '#ff0000'`))).not.toContain(
+      'raw-hex',
+    )
+    expect(
+      kinds(find(`// theme-allow-file raw-hex — vendor brand\nconst c = '#ff0000'`)),
+    ).not.toContain('raw-hex')
+  })
+})
+
+// ── 32. inline-spacing — a property bag that never reaches CSS ───────────────
+
+describe('inline-spacing — the style-object test', () => {
+  const inlineSpacing = (src: string): GuardKind[] =>
+    kinds(find(src)).filter((k) => k === 'inline-spacing')
+
+  // argo: `const FIT_BOUNDS_OPTIONS = { padding: 48, duration: 0 }` is a maplibre `fitBounds`
+  // viewport inset measured in MAP pixels. There is no Mantine token that could express it, and
+  // "use p/m/gap with xs..xl" is not a thing that can be done to it. The class recurs in any
+  // consumer wrapping a map or a canvas library — basalt's own shell carries one (a floating-ui
+  // `shift: { padding: 8 }`), which is how it stayed invisible.
+  it('does NOT flag a unitless number in a plain options bag', () => {
+    expect(inlineSpacing('const FIT_BOUNDS_OPTIONS = { padding: 48, duration: 0 }')).toEqual([])
+  })
+
+  it('does NOT flag a unitless number in a call argument', () => {
+    expect(inlineSpacing('map.fitBounds(bounds, { padding: 48 })')).toEqual([])
+  })
+
+  it('does NOT flag a nested non-style bag (floating-ui middleware)', () => {
+    expect(inlineSpacing('const M = { flip: false, shift: { padding: 8 } }')).toEqual([])
+  })
+
+  // Everything the kind was built for still reports.
+  it.each([
+    '<Box style={{ padding: 16 }} />',
+    '<Box\n  style={{\n    padding: 16,\n  }}\n/>',
+    '<Input styles={{ input: { paddingLeft: 12 } }} />',
+    'const wrapperStyle = { padding: 16 }',
+    'const s: CSSProperties = { marginTop: 12 }',
+  ])('still flags %s', (src) => {
+    expect([src, inlineSpacing(src)]).toEqual([src, ['inline-spacing']])
+  })
+
+  // The hoisted form the name alone does not give away — resolved from the `style={…}` use site,
+  // the same seam `hidden-inline-style` already walks.
+  it('flags a hoisted object the file hands to a style prop', () => {
+    expect(
+      inlineSpacing('const s = { padding: 16 }\nexport const D = () => <div style={s} />'),
+    ).toEqual(['inline-spacing'])
+  })
+
+  // A UNIT is evidence the number is CSS wherever it was written, so it never consults the context.
+  it.each([`const OPTS = { padding: '16px' }`, `const OPTS = { marginTop: '1.5rem' }`])(
+    '%s carries a unit and is flagged regardless of context',
+    (src) => {
+      expect([src, inlineSpacing(src)]).toEqual([src, ['inline-spacing']])
+    },
+  )
+
+  it('CSS is untouched by the test — there is no object context to consult', () => {
+    const f = checkSource('.a { padding: 18px }', 'src/Card.module.css', DEFAULT_GUARD_CONFIG)
+    expect(kinds(f)).toContain('inline-spacing')
+  })
+})