basalt-ui 1.19.1 → 1.20.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,7 +10,13 @@
 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 {
+  checkSource,
+  DEFAULT_GUARD_CONFIG,
+  GENERATED_HEADER_LINE,
+  GUARD_RULES,
+  TOKENS_ONLY_DISABLED_KINDS,
+} from './index'
 import type { Finding, GuardKind } from './types'
 
 const PATH = 'src/Dashboard.tsx'
@@ -1004,14 +1010,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-…)', () => {
@@ -1599,6 +1610,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 +1691,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 +1729,567 @@ 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')
+  })
+})
+
+// ── 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')
+  })
+})