basalt-ui 1.20.0 → 1.22.0

package/src/cli/init-sync.test.ts

@@ -151,6 +151,8 @@ describe('doctor — CLI vs installed basalt-ui version', () => {
       'node_modules/basalt-ui/package.json',
       JSON.stringify({ name: 'basalt-ui', version: cliVersion }),
     )
+    // The `extends` above has to RESOLVE, not merely read correctly — see the oxlint-preset check.
+    writeFixture('node_modules/basalt-ui/configs/oxlint.json', '{}')
     const { code, log } = capture(() => doctor(dir))
     expect(code).toBe(0)
     expect(log).toContain('matches the installed basalt-ui')

package/src/cli/template-ledger.test.ts

@@ -116,7 +116,7 @@ describe('classify ledger: cross-version format-only drift vs a real edit', () =
     // older version token — this is what makes the scenario cross-version, not same-version.
     const olderBlock = currentBlock.replace(/basalt-ui/g, 'basalt')
     expect(olderBlock).not.toBe(currentBlock)
-    expect(olderBlock).toContain('bunx basalt sync')
+    expect(olderBlock).toContain('basalt sync')
 
     // What a PRE-1.0.2 CLI's writeUnit actually recorded at that sync: a RAW hash of the exact
     // bytes it wrote — the fix only normalizes hashes written by a CLI carrying it, so a genuine

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'
@@ -20,6 +20,7 @@ import {
   init,
   MANIFEST_PATH,
   normalizeColorFunctions,
+  sync,
   tokensCss,
 } from './index.ts'
 
@@ -68,6 +69,9 @@ function installBasalt(at = ''): void {
     join(at, 'node_modules/basalt-ui/package.json'),
     JSON.stringify({ name: 'basalt-ui', version: CLI_VERSION }),
   )
+  // The shipped preset itself — `doctor`'s oxlint-preset check resolves the `extends` target now,
+  // so an install without it is (correctly) a failure.
+  write(join(at, 'node_modules/basalt-ui/configs/oxlint.json'), '{}')
 }
 
 /** A repo where every framework-profile doctor check passes. */
@@ -538,6 +542,18 @@ describe('tokens:css — a committable artifact', () => {
     expect(css).toContain('rgba(255, 255, 255, 0.6)')
   })
 
+  it('emits no trailing-zero alpha — the last thing keeping the sheet out of a linter', () => {
+    // prettier rewrites `rgba(28, 25, 23, 0.10)` → `0.1`, so the two light shadow tokens failed
+    // `format/prettier` while `--fix` put the file straight into `tokens:css --check` drift. The
+    // consumer's eslint-ignore entry for it survived two releases.
+    const css = emit([])
+    expect(css).not.toMatch(/rgba\([^)]*\d\.\d*0\)/)
+    expect(css).toContain('rgba(28, 25, 23, 0.1)')
+    expect(normalizeColorFunctions('a: rgba(1, 2, 3, 0.10); b: rgba(1, 2, 3, 1.0);')).toBe(
+      'a: rgba(1, 2, 3, 0.1); b: rgba(1, 2, 3, 1);',
+    )
+  })
+
   it('changes no token VALUE — the body is buildPaletteCss modulo the formatting', () => {
     const body = emit([]).split('\n').slice(2).join('\n')
     expect(body).toBe(`${normalizeColorFunctions(buildPaletteCss())}\n`)
@@ -692,3 +708,338 @@ describe('fonts:css — the typeface half of the token layer', () => {
     expect(capture(() => fontsCss(['--out', 'fonts.css', '--check'], dir)).code).toBe(1)
   })
 })
+
+// ──────────────────────────────────────────────────────────────────────────────
+// Round 5: the same false-green class, one layer in — inside the checks that
+// were added to prevent it.
+// ──────────────────────────────────────────────────────────────────────────────
+
+describe('doctor — the oxlint-preset check resolves the path, not just the string', () => {
+  it('hard-fails when the extends entry names a path that does not exist', () => {
+    healthyFixture()
+    // Exactly the state a monorepo consumer upgrades into: a well-shaped root-relative entry, and
+    // basalt installed beside the package that depends on it. `bunx oxlint .` dies with NotFound
+    // here, and 1.20.0's own check printed ✓ in the same tree.
+    rmSync(join(dir, 'node_modules/basalt-ui/configs/oxlint.json'))
+    const { code, log } = capture(() => doctor(dir))
+    expect(code).toBe(1)
+    expect(log).toContain('does not exist')
+    expect(log).toContain('NotFound')
+    expect(log).not.toContain('✓ .oxlintrc.json extends')
+  })
+
+  it('names the RESOLVED install path as the remedy when the entry points somewhere else', () => {
+    write(
+      'package.json',
+      JSON.stringify({
+        name: 'root',
+        workspaces: ['packages/*'],
+        basalt: { roots: ['packages/web/src'] },
+      }),
+    )
+    write('packages/web/package.json', JSON.stringify({ name: 'web' }))
+    write('packages/web/src/app.tsx', 'export const App = () => null\n')
+    write(MANIFEST_PATH, JSON.stringify({ version: 1, files: {}, basaltVersion: CLI_VERSION }))
+    write('.oxlintrc.json', '{ "extends": ["./node_modules/basalt-ui/configs/oxlint.json"] }')
+    installBasalt('packages/web')
+    const { code, log } = capture(() => doctor(dir))
+    expect(code).toBe(1)
+    expect(log).toContain('packages/web/node_modules/basalt-ui/configs/oxlint.json')
+  })
+
+  it('passes — and quotes the entry — when the target really is there', () => {
+    healthyFixture()
+    const { code, log } = capture(() => doctor(dir))
+    expect(code).toBe(0)
+    expect(log).toContain('extends the shipped basalt-ui oxlint preset')
+  })
+})
+
+describe('doctor — the lefthook extends target, the seam that fails SILENTLY', () => {
+  it('hard-fails on a missing target: lefthook merges it to zero commands and exits 0', () => {
+    healthyFixture()
+    write('lefthook.yml', 'extends:\n  - node_modules/basalt-ui/configs/lefthook.yml\n')
+    const { code, log } = capture(() => doctor(dir))
+    expect(code).toBe(1)
+    expect(log).toContain('ZERO commands')
+  })
+
+  it('passes when the target resolves', () => {
+    healthyFixture()
+    write('node_modules/basalt-ui/configs/lefthook.yml', 'pre-commit:\n  commands: {}\n')
+    write('lefthook.yml', 'extends:\n  - node_modules/basalt-ui/configs/lefthook.yml\n')
+    const { code, log } = capture(() => doctor(dir))
+    expect(code).toBe(0)
+    expect(log).toContain('extends the shipped lefthook preset')
+  })
+
+  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('cannot tell a missing gate from one wired through an `include:`')
+  })
+
+  it('is not applicable when the repo runs no lefthook at all', () => {
+    healthyFixture()
+    const { code, log } = capture(() => doctor(dir))
+    expect(code).toBe(0)
+    expect(log).toContain('lefthook-preset: n/a')
+  })
+})
+
+describe('sync — basalt.roots is drift, and sync is the drift command', () => {
+  it('backfills the inferred roots when the key was never written', () => {
+    write('package.json', JSON.stringify({ name: 'fixture' }))
+    write('src/app.tsx', 'export const App = () => null\n')
+    capture(() => init(dir))
+    // Undo init's write to reproduce a repo scaffolded before roots existed, then upgrade.
+    write('package.json', JSON.stringify({ name: 'fixture' }))
+    const { log } = capture(() => sync({}, dir))
+    expect(log).toContain('"roots": ["src"]')
+    expect((readPkg()['basalt'] as { roots: string[] }).roots).toEqual(['src'])
+  })
+
+  it('never overwrites a declared roots — it names what the declaration does not cover', () => {
+    write(
+      'package.json',
+      JSON.stringify({
+        name: 'root',
+        workspaces: ['packages/*'],
+        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': '*' } }),
+    )
+    write('packages/web/src/app.tsx', 'export const App = () => null\n')
+    write(
+      'packages/api/package.json',
+      JSON.stringify({ name: 'api', dependencies: { 'basalt-ui': '*' } }),
+    )
+    write('packages/api/src/server.ts', 'export const server = null\n')
+    const { log } = capture(() => sync({}, dir))
+    expect((readPkg()['basalt'] as { roots: string[] }).roots).toEqual(['packages/web/src'])
+    expect(log).toContain('keeping your "basalt.roots"')
+    expect(log).toContain('packages/api/src')
+  })
+
+  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()
+    expect(log).toContain('"basalt.roots" is not set')
+  })
+
+  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))
+    expect(log).toContain('ZERO commands')
+  })
+})
+
+describe('init — the seeded lefthook.yml pins the guard to the local bin', () => {
+  it('renders a BASALT_BIN env override, the one key an extends target cannot eat', () => {
+    write('package.json', JSON.stringify({ name: 'fixture' }))
+    write('src/app.tsx', 'export const App = () => null\n')
+    installBasalt()
+    capture(() => init(dir))
+    const seeded = read('lefthook.yml')
+    expect(seeded).toContain('BASALT_BIN: node_modules/.bin/basalt-ui')
+    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

@@ -0,0 +1,211 @@
+/**
+ * `check-theme --audit-allows` — the accountability half of the escape hatch.
+ *
+ * 1.20.0 shipped `theme-allow-unscoped`, which reports a waiver that names no rule. It cannot see
+ * the other failure: a perfectly well-written waiver whose finding no longer exists. Two consumers
+ * found five of those by hand — editing the token out and re-running the guard — and that manual
+ * method is what this command automates, which is why every assertion below is about a VERDICT
+ * derived from re-running the scan, never from parsing the annotation's text.
+ *
+ * Run: bun test packages/basalt-ui/src/cli/waiver-audit.test.ts
+ */
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test'
+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 {
+  const abs = join(dir, relPath)
+  mkdirSync(resolve(abs, '..'), { recursive: true })
+  writeFileSync(abs, content, 'utf8')
+}
+
+function audit(): { code: number; log: string } {
+  const originalLog = console.log
+  const originalError = console.error
+  let log = ''
+  const sink = (...args: unknown[]) => {
+    log += `${args.join(' ')}\n`
+  }
+  console.log = sink
+  console.error = sink
+  try {
+    return { code: checkTheme(dir, ['--audit-allows']), log }
+  } finally {
+    console.log = originalLog
+    console.error = originalError
+  }
+}
+
+/** A repo whose only source file is the one under test. */
+function fixture(source: string, basalt: Record<string, unknown> = {}): void {
+  write('package.json', JSON.stringify({ name: 'fixture', basalt: { roots: ['src'], ...basalt } }))
+  write('src/app.tsx', source)
+}
+
+beforeEach(() => {
+  dir = mkdtempSync(resolve(tmpdir(), 'basalt-audit-'))
+})
+
+afterEach(() => {
+  rmSync(dir, { recursive: true, force: true })
+})
+
+describe('check-theme --audit-allows — theme-allow annotations', () => {
+  it('names what a live waiver still suppresses, and exits 0', () => {
+    fixture("export const c = '#ff0000' // theme-allow raw-hex — a deliberate brand literal\n")
+    const { code, log } = audit()
+    expect(log).toContain('suppresses raw-hex@1')
+    expect(code).toBe(0)
+  })
+
+  it('calls a waiver over a line with no finding DEAD, and exits 1', () => {
+    fixture('export const c = 1 // theme-allow raw-hex — nothing here fires any more\n')
+    const { code, log } = audit()
+    expect(log).toContain('SUPPRESSES NOTHING')
+    expect(code).toBe(1)
+  })
+
+  it('does not report prose that merely mentions the token', () => {
+    // The guard stopped treating a mid-comment mention as an annotation for exactly this reason;
+    // an audit that listed them as dead waivers would send someone editing documentation.
+    fixture('// Waive it with a `theme-allow raw-hex — why` comment.\nexport const c = 1\n')
+    const { code, log } = audit()
+    expect(log).toContain('annotations (0)')
+    expect(code).toBe(0)
+  })
+
+  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.
+    // 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('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()
+    expect(log).toContain('suppresses raw-hex@1')
+    expect(log).toContain('no rule id')
+    expect(log).toContain('1 unaccountable')
+  })
+})
+
+describe('check-theme --audit-allows — basalt.exemptRules', () => {
+  it('prints the reason from the object form, and says so when there is none', () => {
+    fixture("export const c = '#ff0000'\n", {
+      exemptRules: { 'raw-hex': { paths: ['src'], reason: 'a vendor asset basalt does not own' } },
+    })
+    const { log } = audit()
+    expect(log).toContain('a vendor asset basalt does not own')
+    expect(log).toContain('suppresses findings in src/app.tsx')
+
+    fixture("export const c = '#ff0000'\n", { exemptRules: { 'raw-hex': ['src'] } })
+    expect(audit().log).toContain('[no reason recorded]')
+  })
+
+  it('the object form really does exempt — the reason is accountability, not a second config', () => {
+    fixture("export const c = '#ff0000'\n", {
+      exemptRules: { 'raw-hex': { paths: ['src'], reason: 'a vendor asset basalt does not own' } },
+    })
+    expect(checkTheme(dir, [])).toBe(0)
+  })
+
+  it('reports a pattern that matches no scanned file as dead, and exits 1', () => {
+    // rollhook wrote a real, correct relative path, it matched nothing, and nothing said so — the
+    // finding kept failing the build with the config sitting right there looking like the answer.
+    fixture("export const c = '#ff0000'\n", { exemptRules: { 'raw-hex': ['does-not-exist'] } })
+    const { code, log } = audit()
+    expect(log).toContain('matches no scanned file')
+    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'])
+  })
+})