basalt-ui 1.21.0 → 1.22.0

package/src/cli/toolchain-wiring.test.ts

@@ -7,7 +7,7 @@
  * false-greens shut. The unit under test is always "does the tool TELL you", not "does it work".
  */
 import { afterEach, beforeEach, describe, expect, it } from 'bun:test'
-import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
@@ -773,12 +773,30 @@ describe('doctor — the lefthook extends target, the seam that fails SILENTLY',
     expect(log).toContain('extends the shipped lefthook preset')
   })
 
-  it('warns (never fails) on a lefthook.yml that wires its own hooks instead', () => {
+  it('passes a repo that spells the gate out instead of extending — the check is the GATE', () => {
+    // linewatch's root lefthook.yml runs all three jobs with `root: 'web/'`, because `extends`
+    // merges commands WITHOUT their working directory: the preset's `bunx oxlint` would run at the
+    // repo root where there is no .oxlintrc.json. Testing for the extends STRING warned at a
+    // correctly-wired repo and prescribed a change that would have broken it.
+    healthyFixture()
+    write(
+      'lefthook.yml',
+      "pre-commit:\n  commands:\n    theme-guard:\n      root: 'web/'\n" +
+        '      run: bunx basalt-ui check-theme\n',
+    )
+    const { code, log } = capture(() => doctor(dir))
+    expect(code).toBe(0)
+    expect(log).toContain('a pre-commit command runs check-theme directly — the gate exists')
+  })
+
+  it('is advisory, never confident, when neither the text nor `lefthook dump` settles it', () => {
+    // A check that is confidently wrong is worse than one that admits its limit: an `include:` or a
+    // remote config carries commands this reader never sees.
     healthyFixture()
     write('lefthook.yml', 'pre-commit:\n  commands:\n    mine:\n      run: echo hi\n')
     const { code, log } = capture(() => doctor(dir))
     expect(code).toBe(0)
-    expect(log).toContain('does not extend the shipped lefthook preset')
+    expect(log).toContain('cannot tell a missing gate from one wired through an `include:`')
   })
 
   it('is not applicable when the repo runs no lefthook at all', () => {
@@ -810,6 +828,7 @@ describe('sync — basalt.roots is drift, and sync is the drift command', () =>
         basalt: { roots: ['packages/web/src'] },
       }),
     )
+    write(MANIFEST_PATH, JSON.stringify({ version: 1, files: {} }))
     write(
       'packages/web/package.json',
       JSON.stringify({ name: 'web', dependencies: { 'basalt-ui': '*' } }),
@@ -828,6 +847,7 @@ describe('sync — basalt.roots is drift, and sync is the drift command', () =>
 
   it('--check writes nothing, but still says the key is missing', () => {
     write('package.json', JSON.stringify({ name: 'fixture' }))
+    write(MANIFEST_PATH, JSON.stringify({ version: 1, files: {} }))
     write('src/app.tsx', 'export const App = () => null\n')
     const { log } = capture(() => sync({ check: true }, dir))
     expect(readPkg()['basalt']).toBeUndefined()
@@ -836,6 +856,7 @@ describe('sync — basalt.roots is drift, and sync is the drift command', () =>
 
   it('reports a lefthook extends target that no longer resolves', () => {
     write('package.json', JSON.stringify({ name: 'fixture', basalt: { roots: ['src'] } }))
+    write(MANIFEST_PATH, JSON.stringify({ version: 1, files: {} }))
     write('src/app.tsx', 'export const App = () => null\n')
     write('lefthook.yml', 'extends:\n  - node_modules/basalt-ui/configs/lefthook.yml\n')
     const { log } = capture(() => sync({}, dir))
@@ -854,3 +875,171 @@ describe('init — the seeded lefthook.yml pins the guard to the local bin', ()
     expect(seeded).toContain('extends:')
   })
 })
+
+// ── sync must never silently behave as init ───────────────────────────────────────────────────
+//
+// Found independently in argo and rb. Run from `apps/dashboard` — the package that actually
+// depends on basalt-ui — `sync` printed `0 updated, 20 recreated`, wrote a second `basalt` key into
+// that package.json, and scaffolded a complete competing install (`.basalt/`, `.oxlintrc.json`,
+// `.oxfmtrc.json`, `DESIGN.md`, 13 rules, 3 skills, and in rb's case a `src/routes/__root.tsx`
+// into an app that hand-writes its router) beside the real one at the repo root. Nothing warned.
+// Both consumers reverted it by hand. `check-theme` and `doctor` already relocate; `sync` — the one
+// command that WRITES — did not.
+
+/** A workspace whose basalt install lives at the ROOT, with an app package below it. */
+function installAtRoot(): void {
+  write(
+    'package.json',
+    JSON.stringify({
+      name: 'root',
+      workspaces: ['apps/*'],
+      basalt: { roots: ['apps/dashboard/src'] },
+    }),
+  )
+  write(MANIFEST_PATH, JSON.stringify({ version: 1, files: {}, basaltVersion: CLI_VERSION }))
+  write(
+    'apps/dashboard/package.json',
+    JSON.stringify({ name: 'dashboard', dependencies: { 'basalt-ui': '*' } }),
+  )
+  write('apps/dashboard/src/app.tsx', 'export const App = () => null\n')
+}
+
+describe('sync — a scaffold is init’s decision, never a drift refresh’s', () => {
+  it('refuses from a workspace sub-package and points at the install it found above', () => {
+    installAtRoot()
+    const { code, log } = capture(() => sync({}, join(dir, 'apps/dashboard')))
+    expect(code).toBe(1)
+    expect(log).toContain('refusing to scaffold')
+    expect(log).toContain("This repo's install is at ../..")
+  })
+
+  it('writes NOTHING when it refuses — not the files, and not the second basalt key', () => {
+    installAtRoot()
+    capture(() => sync({}, join(dir, 'apps/dashboard')))
+    // The `basalt.roots` backfill is half the damage: a second config site means check-theme
+    // silently scans a different tree depending on which directory it was invoked from.
+    expect(JSON.parse(read('apps/dashboard/package.json'))['basalt']).toBeUndefined()
+    expect(readdirSync(join(dir, 'apps/dashboard')).toSorted()).toEqual(['package.json', 'src'])
+  })
+
+  it('refuses in a repo that was never a consumer, and names init as the command that is', () => {
+    write('package.json', JSON.stringify({ name: 'fixture' }))
+    const { code, log } = capture(() => sync({}, dir))
+    expect(code).toBe(1)
+    expect(log).toContain('No manifest exists at any ancestor either')
+    expect(log).toContain('basalt-ui init')
+  })
+
+  it('relocates to the single workspace package carrying the install, exactly as doctor does', () => {
+    write('package.json', JSON.stringify({ name: 'root', workspaces: ['apps/*'] }))
+    write('apps/web/package.json', JSON.stringify({ name: 'web', basalt: { roots: ['src'] } }))
+    write('apps/web/src/app.tsx', 'export const App = () => null\n')
+    write(join('apps/web', MANIFEST_PATH), JSON.stringify({ version: 1, files: {} }))
+    const { code, log } = capture(() => sync({ check: true }, dir))
+    expect(log).toContain('running in ./apps/web, where it lives')
+    // --check on an unsynced package is legitimately stale; what matters is WHERE it looked.
+    expect(code).toBe(1)
+  })
+
+  it('short-circuits on an ambiguous workspace instead of picking one to scaffold', () => {
+    ambiguousWorkspace()
+    const { code, log } = capture(() => sync({}, dir))
+    expect(code).toBe(1)
+    expect(log).toContain('2 workspace packages carry one')
+    expect(log).toContain('BASALT_CWD')
+  })
+
+  it('says created, not recreated, for a file the ledger never recorded', () => {
+    // `0 updated, 20 recreated` described a scaffold as a refresh. "Recreated" means the ledger
+    // placed it once and it went missing; a file basalt never wrote here is CREATED.
+    write('package.json', JSON.stringify({ name: 'fixture', basalt: { roots: ['src'] } }))
+    write('src/app.tsx', 'export const App = () => null\n')
+    write(MANIFEST_PATH, JSON.stringify({ version: 1, files: {} }))
+    const { log } = capture(() => sync({}, dir))
+    expect(log).toMatch(/0 updated, \d+ created, 0 recreated/)
+  })
+
+  it('says recreated for a managed file the ledger recorded and someone deleted', () => {
+    write('package.json', JSON.stringify({ name: 'fixture', basalt: { roots: ['src'] } }))
+    write('src/app.tsx', 'export const App = () => null\n')
+    capture(() => init(dir))
+    const placed = '.claude/rules/basalt-tokens.md'
+    rmSync(join(dir, placed))
+    const { log } = capture(() => sync({}, dir))
+    expect(log).toContain('1 recreated')
+  })
+})
+
+// ── doctor's exit status, pinned per outcome ──────────────────────────────────────────────────
+//
+// argo reported two hard failures exiting 0. It does not reproduce (see the report), but the gap
+// that let 1.20.0 ship a SKIPPED-exits-0 bug was that the tests asserted printed TEXT and never the
+// status. These assert the status for every outcome, including the combinations.
+
+describe('doctor — exit status per outcome, not per printed string', () => {
+  it('pass-only exits 0 and is the only state that may print "All checks passed"', () => {
+    healthyFixture()
+    const { code, log } = capture(() => doctor(dir))
+    expect([code, log.includes('All checks passed')]).toEqual([0, true])
+  })
+
+  it('warn-only exits 0 — a warning is a schedule, not a build break', () => {
+    healthyFixture()
+    write(
+      'node_modules/basalt-ui/package.json',
+      JSON.stringify({ name: 'basalt-ui', version: '0.4.2' }),
+    )
+    const { code, log } = capture(() => doctor(dir))
+    expect(log).toContain('warning(s)')
+    expect(log).not.toContain('hard failure')
+    expect(log).not.toContain('All checks passed')
+    expect(code).toBe(0)
+  })
+
+  it('one hard failure exits 1', () => {
+    healthyFixture()
+    rmSync(join(dir, '.oxlintrc.json'))
+    const { code, log } = capture(() => doctor(dir))
+    expect(log).toContain('1 hard failure(s)')
+    expect(code).toBe(1)
+  })
+
+  it('TWO hard failures exit 1 — the shape argo reported as exiting 0', () => {
+    // argo's exact pair: no manifest and no .oxlintrc.json, in a Mantine repo (so the profile
+    // stays `framework` and both checks are real rather than n/a).
+    healthyFixture()
+    write(
+      'package.json',
+      JSON.stringify({
+        name: 'fixture',
+        dependencies: { '@mantine/core': '^9.3.0' },
+        basalt: { roots: ['src'] },
+      }),
+    )
+    rmSync(join(dir, '.oxlintrc.json'))
+    rmSync(join(dir, MANIFEST_PATH))
+    const { code, log } = capture(() => doctor(dir))
+    expect(log).toContain('2 hard failure(s)')
+    expect(code).toBe(1)
+  })
+
+  it('a SKIPPED check exits 1 on its own, with no failure and no warning', () => {
+    write('package.json', JSON.stringify({ name: 'fixture', basalt: { roots: ['src'] } }))
+    write('src/app.tsx', 'export const App = () => null\n')
+    write('.oxlintrc.json', '{ "extends": ["./node_modules/basalt-ui/configs/oxlint.json"] }')
+    write(MANIFEST_PATH, JSON.stringify({ version: 1, files: {}, basaltVersion: CLI_VERSION }))
+    const { code, log } = capture(() => doctor(dir))
+    expect(log).toContain('SKIPPED')
+    expect(code).toBe(1)
+  })
+
+  it('an ambiguous project exits 1 before any check runs', () => {
+    ambiguousWorkspace()
+    expect(capture(() => doctor(dir)).code).toBe(1)
+  })
+
+  it('contradictory profile flags exit 1', () => {
+    healthyFixture()
+    expect(capture(() => doctor(dir, ['--tokens-only', '--framework'])).code).toBe(1)
+  })
+})

package/src/cli/waiver-audit.test.ts

@@ -10,12 +10,23 @@
  * Run: bun test packages/basalt-ui/src/cli/waiver-audit.test.ts
  */
 import { afterEach, beforeEach, describe, expect, it } from 'bun:test'
-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readdirSync,
+  rmSync,
+  symlinkSync,
+  writeFileSync,
+} from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
 
 import { checkTheme } from './index.ts'
 
+const PKG_ROOT = fileURLToPath(new URL('../../', import.meta.url))
+
 let dir: string
 
 function write(relPath: string, content: string): void {
@@ -79,18 +90,27 @@ describe('check-theme --audit-allows — theme-allow annotations', () => {
     expect(code).toBe(0)
   })
 
-  it('refuses to judge a waiver scoped to an oxlint plugin rule instead of calling it dead', () => {
+  it('says oxlint could not be run rather than calling a plugin-rule waiver dead', () => {
     // `hand-rolled-plot` lives in the plugin, so `checkSource` can never see what it suppresses.
-    // Reporting "delete it" here would be the command telling someone to remove a live waiver.
+    // With no oxlint reachable from the fixture the honest answer is "cannot judge" — reporting
+    // "delete it" here would be the command telling someone to remove a live waiver.
     fixture(
       '// theme-allow hand-rolled-plot — DualPanel is not a single cartesian plot\nexport const c = 1\n',
     )
     const { code, log } = audit()
-    expect(log).toContain('not a check-theme kind')
+    expect(log).toContain('oxlint could not be run here')
     expect(log).not.toContain('SUPPRESSES NOTHING')
     expect(code).toBe(0)
   })
 
+  it('names the scope it audited, so "0 dead" is never read as "0 dead anywhere"', () => {
+    // The audit reads exactly what check-theme reads. A waiver in a file outside `basalt.roots` is
+    // invisible to it — not because it is fine, but because nothing scanned it.
+    fixture("export const c = '#ff0000' // theme-allow raw-hex — brand literal\n")
+    const { log } = audit()
+    expect(log).toContain('Scope: the 1 file(s) check-theme scans under basalt.roots (src)')
+  })
+
   it('marks an unaccountable waiver while still reporting what it covers', () => {
     fixture("export const c = '#ff0000' // theme-allow\n")
     const { log } = audit()
@@ -129,3 +149,63 @@ describe('check-theme --audit-allows — basalt.exemptRules', () => {
     expect(code).toBe(1)
   })
 })
+
+// ── the oxlint half ───────────────────────────────────────────────────────────────────────────
+//
+// The `error`-severity design rules live in the oxlint plugin, not in `checkSource`. Until this,
+// the audit declined to judge them — 8 of 8 annotations in argo, 11 of 14 in linewatch — so the
+// exit-1 gate covered an empty set. These prove the method generalizes: neutralize the annotation,
+// re-run oxlint over that one file, and the findings that appear are what it covers.
+
+const REPO_ROOT = resolve(PKG_ROOT, '../..')
+const OXLINT_BIN = resolve(REPO_ROOT, 'node_modules/.bin/oxlint')
+
+/** Make oxlint reachable from the fixture and point it at the shipped preset (plugin included). */
+function withOxlint(): void {
+  mkdirSync(join(dir, 'node_modules/.bin'), { recursive: true })
+  symlinkSync(OXLINT_BIN, join(dir, 'node_modules/.bin/oxlint'))
+  write('.oxlintrc.json', JSON.stringify({ extends: [resolve(PKG_ROOT, 'configs/oxlint.json')] }))
+}
+
+describe.skipIf(!existsSync(OXLINT_BIN))('check-theme --audit-allows — oxlint plugin rules', () => {
+  it('proves a plugin-rule waiver LIVE, naming the rule and the line it covers', () => {
+    write('package.json', JSON.stringify({ name: 'fixture', basalt: { roots: ['src'] } }))
+    write(
+      'src/charts/plot.tsx',
+      "import { AxisLeftNumeric } from 'basalt-ui/charts'\n\n" +
+        '// theme-allow hand-rolled-plot — this pane is not a single cartesian plot\n' +
+        'export const Plot = () => <AxisLeftNumeric />\n',
+    )
+    withOxlint()
+    const { code, log } = audit()
+    expect(log).toContain('suppresses hand-rolled-plot@4 (oxlint)')
+    expect(code).toBe(0)
+  })
+
+  it('calls a plugin-rule waiver over nothing DEAD, and exits 1 — the gate now covers them', () => {
+    write('package.json', JSON.stringify({ name: 'fixture', basalt: { roots: ['src'] } }))
+    write(
+      'src/charts/plot.tsx',
+      '// theme-allow hand-rolled-plot — this pane is not a single cartesian plot\n' +
+        'export const Plot = () => null\n',
+    )
+    withOxlint()
+    const { code, log } = audit()
+    expect(log).toContain('SUPPRESSES NOTHING')
+    expect(log).toContain('re-running oxlint')
+    expect(code).toBe(1)
+  })
+
+  it('leaves no probe file behind — the neutralized copy is a temp file basalt owns', () => {
+    write('package.json', JSON.stringify({ name: 'fixture', basalt: { roots: ['src'] } }))
+    write(
+      'src/charts/plot.tsx',
+      "import { AxisLeftNumeric } from 'basalt-ui/charts'\n\n" +
+        '// theme-allow hand-rolled-plot — this pane is not a single cartesian plot\n' +
+        'export const Plot = () => <AxisLeftNumeric />\n',
+    )
+    withOxlint()
+    audit()
+    expect(readdirSync(join(dir, 'src/charts'))).toEqual(['plot.tsx'])
+  })
+})

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

@@ -13,10 +13,14 @@ import { SPACE_SCALE } from '../tokens/palette'
 import {
   checkSource,
   DEFAULT_GUARD_CONFIG,
+  findAllowAnnotations,
   GENERATED_HEADER_LINE,
   guardKindRemedy,
   guardWaiverHint,
   GUARD_RULES,
+  neutralizeAllowAnnotation,
+  NEUTRALIZED_ALLOW_TOKEN,
+  PLUGIN_RULE_IDS,
   TOKENS_ONLY_DISABLED_KINDS,
   unmatchedExemptPatterns,
 } from './index'
@@ -2733,3 +2737,196 @@ describe('inline-spacing — the style-object test', () => {
     expect(kinds(f)).toContain('inline-spacing')
   })
 })
+
+// ── theme-allow comment shapes ───────────────────────────────────────────────────────────────────
+
+/**
+ * The prefix contract, pinned per comment shape.
+ *
+ * Three holes have been found in this rule in three rounds — two false positives and one false
+ * NEGATIVE (a docblock documenting a file's waivers disarmed the file). So every shape a consumer
+ * actually writes gets a fixture, and the oxlint plugin's copy is pinned identically in
+ * `configs/oxlint-plugin.test.ts`: the two halves of one contract must agree on what an annotation
+ * IS, and may differ only on which rules each can judge.
+ */
+describe('theme-allow comment shapes', () => {
+  const REASON = 'deliberate legacy value'
+  const waives = (relPath: string, src: string): boolean =>
+    checkSource(src, relPath, DEFAULT_GUARD_CONFIG).filter((f) => f.kind === 'raw-hex').length === 0
+
+  it.each([
+    ['own line //', PATH, `// theme-allow raw-hex — ${REASON}\nconst a = '#f00'\n`],
+    [
+      'indented //',
+      PATH,
+      `function f() {\n  // theme-allow raw-hex — ${REASON}\n  const a = '#f00'\n}\n`,
+    ],
+    ['trailing //', PATH, `const a = '#f00' // theme-allow raw-hex — ${REASON}\n`],
+    ['trailing block', PATH, `const a = '#f00' /* theme-allow raw-hex — ${REASON} */\n`],
+    [
+      'JSX expression comment',
+      PATH,
+      `export const C = () => (\n  <div>\n    {/* theme-allow raw-hex — ${REASON} */}\n    <span style={{ color: '#f00' }} />\n  </div>\n)\n`,
+    ],
+    [
+      'JSX expression comment, token on its own wrapped line',
+      PATH,
+      `export const C = () => (\n  <div>\n    {/*\n      theme-allow raw-hex — ${REASON} */}\n    <span style={{ color: '#f00' }} />\n  </div>\n)\n`,
+    ],
+    ['block gutter *', PATH, `/**\n * theme-allow raw-hex — ${REASON}\n */\nconst a = '#f00'\n`],
+    ['docblock opener /**', PATH, `/** theme-allow raw-hex — ${REASON} */\nconst a = '#f00'\n`],
+    ['css trailing', 'src/a.css', `a { color: #f00; /* theme-allow raw-hex — ${REASON} */ }\n`],
+    [
+      'css reflowed onto continuation lines',
+      'src/a.css',
+      `a {\n  color: var(\n    --x,\n    #f00\n  ); /* theme-allow raw-hex — ${REASON} */\n}\n`,
+    ],
+    [
+      'html comment',
+      'index.html',
+      `<!-- theme-allow raw-hex — ${REASON} -->\n<b style="color: #f00"></b>\n`,
+    ],
+    [
+      'html trailing comment',
+      'index.html',
+      `<b style="color: #f00"></b> <!-- theme-allow raw-hex — ${REASON} -->\n`,
+    ],
+    [
+      'JSON member form',
+      'public/site.webmanifest',
+      `{\n  "basalt:theme-allow-file": "raw-hex — ${REASON}",\n  "theme_color": "#f00"\n}\n`,
+    ],
+  ])('%s waives', (_name, relPath, src) => {
+    expect(waives(relPath as string, src as string)).toBe(true)
+  })
+
+  // The false negative the prefix rule closed: a sentence that MENTIONS the token is not one.
+  it.each([
+    [
+      'mid-sentence in a line comment',
+      `// we normally write a theme-allow raw-hex here\nconst a = '#f00'\n`,
+    ],
+    [
+      'mid-sentence in a docblock',
+      `/**\n * Each value below is escaped with a theme-allow raw-hex annotation.\n */\nconst a = '#f00'\n`,
+    ],
+    ['inside a string literal', `const doc = 'theme-allow raw-hex'\nconst a = '#f00'\n`],
+  ])('%s does NOT waive', (_name, src) => {
+    expect(waives(PATH, src as string)).toBe(false)
+  })
+
+  // The narrowness of the `*/}` exception: a `}` that is REAL code keeps its trailing
+  // classification, so the annotation does not reach the statement below it.
+  it('a trailing annotation on a real closing brace stays on its own line', () => {
+    const src = `function f() {\n  const a = 1\n} // theme-allow raw-hex — ${REASON}\nconst b = '#0f0'\n`
+    expect(
+      checkSource(src, PATH, DEFAULT_GUARD_CONFIG)
+        .filter((f) => f.kind === 'raw-hex')
+        .map((f) => f.line),
+    ).toEqual([4])
+  })
+
+  // A trailing annotation is scoped to its OWN line — otherwise `const a = '#f00' // theme-allow`
+  // would silently waive the statement below it too.
+  it('a trailing annotation does not reach the line below', () => {
+    const src = `const a = '#f00' // theme-allow raw-hex — ${REASON}\nconst b = '#0f0'\n`
+    expect(
+      checkSource(src, PATH, DEFAULT_GUARD_CONFIG).filter((f) => f.kind === 'raw-hex'),
+    ).toHaveLength(1)
+  })
+})
+
+// ── findAllowAnnotations / neutralizeAllowAnnotation ─────────────────────────────────────────────
+
+describe('findAllowAnnotations', () => {
+  const cfg = DEFAULT_GUARD_CONFIG
+
+  it('classifies each named id by whose reach it falls in', () => {
+    const src = [
+      `// theme-allow raw-hex — a guard kind`,
+      `const a = '#f00'`,
+      `// theme-allow hand-rolled-plot — a plugin rule, outside checkSource's reach`,
+      `const b = 1`,
+      `// theme-allow raw-hexx — a typo`,
+      `const c = 2`,
+      `// theme-allow`,
+      `const d = 3`,
+    ].join('\n')
+    const sites = findAllowAnnotations(src, PATH, cfg)
+
+    expect(sites.map((s) => s.line)).toEqual([1, 3, 5, 7])
+    expect(sites[0]).toMatchObject({ guardKinds: ['raw-hex'], pluginRules: [], bare: false })
+    expect(sites[1]).toMatchObject({ guardKinds: [], pluginRules: ['hand-rolled-plot'] })
+    expect(sites[2]).toMatchObject({ rules: [], unknownRules: ['raw-hexx'], bare: false })
+    expect(sites[3]).toMatchObject({ bare: true, hasReason: false })
+  })
+
+  it('records the file-declaration form once, at the line it is written on', () => {
+    const src = `// theme-allow-file raw-hex — the whole palette fixture\nconst a = '#f00'\n`
+    expect(findAllowAnnotations(src, PATH, cfg)).toMatchObject([
+      { line: 1, scope: 'file', guardKinds: ['raw-hex'] },
+    ])
+  })
+
+  it('carries the source line verbatim, and finds nothing in a file with no annotation', () => {
+    expect(findAllowAnnotations(`const a = '#f00'\n`, PATH, cfg)).toEqual([])
+    expect(
+      findAllowAnnotations(`  // theme-allow raw-hex — why not\nconst a = 1\n`, PATH, cfg)[0]?.text,
+    ).toBe('  // theme-allow raw-hex — why not')
+  })
+
+  // It shares `collectAllowAnnotations` with `checkSource`, so it cannot list a line the scan does
+  // not honour — the mirrored regex `--audit-allows` carried was already one alternation behind.
+  it('agrees with checkSource about what is prose and what is an annotation', () => {
+    expect(
+      findAllowAnnotations(`// a theme-allow raw-hex goes here\nconst a = 1\n`, PATH, cfg),
+    ).toEqual([])
+    expect(
+      findAllowAnnotations(`/** theme-allow raw-hex — deliberate */\nconst a = 1\n`, PATH, cfg),
+    ).toHaveLength(1)
+  })
+
+  it('finds the JSON member form in a manifest', () => {
+    const src = `{\n  "basalt:theme-allow-file": "raw-hex — brand color"\n}\n`
+    expect(findAllowAnnotations(src, 'public/site.webmanifest', cfg)).toMatchObject([
+      { line: 2, scope: 'file', guardKinds: ['raw-hex'] },
+    ])
+  })
+})
+
+describe('neutralizeAllowAnnotation', () => {
+  const cfg = DEFAULT_GUARD_CONFIG
+
+  it('neutralizes ONE annotation and reveals exactly what it suppressed', () => {
+    const src = [
+      `const a = '#f00' // theme-allow raw-hex — first`,
+      `const b = '#0f0' // theme-allow raw-hex — second`,
+    ].join('\n')
+    expect(checkSource(src, PATH, cfg).filter((f) => f.kind === 'raw-hex')).toEqual([])
+
+    const probe = neutralizeAllowAnnotation(src, 1, cfg)
+    expect(probe).toContain(NEUTRALIZED_ALLOW_TOKEN)
+    expect(
+      checkSource(probe, PATH, cfg)
+        .filter((f) => f.kind === 'raw-hex')
+        .map((f) => f.line),
+    ).toEqual([1])
+  })
+
+  it('leaves a line with no token, and an out-of-range line, untouched', () => {
+    const src = `const a = 1\nconst b = 2\n`
+    expect(neutralizeAllowAnnotation(src, 1, cfg)).toBe(src)
+    expect(neutralizeAllowAnnotation(src, 99, cfg)).toBe(src)
+  })
+
+  it('the neutralized token shares no substring with the annotation it replaces', () => {
+    expect(NEUTRALIZED_ALLOW_TOKEN).not.toContain(cfg.allowComment)
+    expect(NEUTRALIZED_ALLOW_TOKEN.includes('theme-allow')).toBe(false)
+  })
+})
+
+describe('PLUGIN_RULE_IDS', () => {
+  it('names no guard kind — the two registries are disjoint by construction', () => {
+    for (const id of PLUGIN_RULE_IDS) expect(Object.hasOwn(GUARD_RULES, id)).toBe(false)
+  })
+})