basalt-ui 1.21.0 → 1.23.0

package/src/cli/shipped-versions.test.ts

@@ -0,0 +1,83 @@
+/**
+ * No shipped artifact may name a basalt version npm never served.
+ *
+ * Three rounds running, the newest `MIGRATING.md` heading named a phantom — `1.20.1` (shipped as
+ * 1.21.0), then `1.21.1` (shipped as 1.22.0) — because the docs pass runs BEFORE semantic-release
+ * computes the number, so whatever is written is a guess. That would be a docs problem alone if it
+ * stayed in docs. It does not: `sync` copies `agent/rules/**` and `agent/skills/**` verbatim into
+ * every consumer, so "Since 1.21.1" is currently shipped, as fact, into seven repos.
+ *
+ * This is the gate that ends it, and it is mechanical rather than editorial: every basalt-shaped
+ * version literal in a file a consumer receives must appear as a release heading in CHANGELOG.md —
+ * the one file `semantic-release` writes AFTER the number exists. A guessed version fails here
+ * before it can ship.
+ *
+ * Deliberately NOT a ban on version literals: `agent/rules/**` is release-history prose and
+ * "widened at 1.21.0, promoted at 1.22.0" is exactly the sentence a consumer needs. What it may
+ * not do is name a release that does not exist.
+ *
+ * The complementary half — no version stamped into a file nothing ever rewrites — lives in
+ * `toolchain-wiring.test.ts` ("DESIGN.md carries no version").
+ *
+ * Run: bun test packages/basalt-ui/src/cli/shipped-versions.test.ts
+ */
+import { readdirSync, readFileSync, statSync } from 'node:fs'
+import { join, relative, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'bun:test'
+
+const PKG_ROOT = fileURLToPath(new URL('../../', import.meta.url))
+
+/** Every version CHANGELOG.md records, plus the one package.json currently declares. */
+const RELEASED = new Set<string>([
+  ...(
+    readFileSync(resolve(PKG_ROOT, 'CHANGELOG.md'), 'utf8').match(/^#+\s*\[?(\d+\.\d+\.\d+)/gm) ??
+    []
+  ).map((h) => h.replace(/^#+\s*\[?/, '')),
+  (JSON.parse(readFileSync(resolve(PKG_ROOT, 'package.json'), 'utf8')) as { version: string })
+    .version,
+])
+
+/**
+ * basalt's own version line is 0.x / 1.x, so a literal with any other major belongs to a peer
+ * (visx 4.0.0, motion 12.42.0, the fontsource 5.2.x trio) and is none of this gate's business. A
+ * `^`/`~`/`@`-prefixed literal is a dependency RANGE for the same reason — `vite-plugin-pwa
+ * (^1.3.0)` shares a major with basalt and is still not a claim about basalt.
+ */
+const BASALT_VERSION_LITERAL = /(^|[^-~^@\w.])([01]\.\d+\.\d+)(?![\w.])/g
+
+function versionsIn(content: string): string[] {
+  return [...content.matchAll(BASALT_VERSION_LITERAL)].map((m) => m[2] as string)
+}
+
+/** Every file under `dir`, recursively. */
+function filesUnder(dir: string): string[] {
+  return readdirSync(dir).flatMap((name) => {
+    const abs = join(dir, name)
+    return statSync(abs).isDirectory() ? filesUnder(abs) : [abs]
+  })
+}
+
+// Everything `init`/`sync` place in a consumer repo, plus the presets they `extends` into.
+const SHIPPED = [
+  ...filesUnder(resolve(PKG_ROOT, 'agent')),
+  resolve(PKG_ROOT, 'configs/check.yml'),
+  resolve(PKG_ROOT, 'configs/lefthook.yml'),
+]
+
+describe('shipped agent assets name only versions that exist', () => {
+  it.each(SHIPPED.map((abs) => [relative(PKG_ROOT, abs), abs] as const))(
+    '%s',
+    (_rel, abs: string) => {
+      const unreleased = [...new Set(versionsIn(readFileSync(abs, 'utf8')))].filter(
+        (v) => !RELEASED.has(v),
+      )
+      expect(unreleased).toEqual([])
+    },
+  )
+
+  it('reads a real changelog, so an empty RELEASED set can never make this vacuous', () => {
+    expect(RELEASED.size).toBeGreaterThan(20)
+    expect(RELEASED.has('1.21.1')).toBe(false)
+  })
+})

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'
@@ -344,7 +344,7 @@ describe('check-theme — finds the config a root-invoked hook cannot see', () =
   it('reports ambiguity rather than guessing when two packages carry a config', () => {
     ambiguousWorkspace()
     const { code, log } = capture(() => checkTheme(dir))
-    expect(log).toContain('2 workspace packages carry one')
+    expect(log).toContain('2 packages below it carry one')
     expect(log).toContain('BASALT_CWD')
     expect(code).toBe(1)
   })
@@ -363,7 +363,7 @@ describe('doctor — an ambiguous project is terminal, exactly as it is for chec
   it('short-circuits instead of running every check against the wrong root', () => {
     ambiguousWorkspace()
     const { code, log } = capture(() => doctor(dir))
-    expect(log).toContain('2 workspace packages carry one')
+    expect(log).toContain('2 packages below it carry one')
     expect(log).toContain('BASALT_CWD')
     expect(code).toBe(1)
     // The bug this pins shut: falling back to the invocation cwd ran the remaining checks against
@@ -381,7 +381,7 @@ describe('doctor — an ambiguous project is terminal, exactly as it is for chec
   it('still runs normally once BASALT_CWD picks a package', () => {
     ambiguousWorkspace()
     const { code, log } = capture(() => doctor(join(dir, 'apps/a')))
-    expect(log).not.toContain('workspace packages carry one')
+    expect(log).not.toContain('packages below it carry one')
     expect(code).toBe(1) // no install / no manifest there — but the checks RAN
     expect(log).toContain('guard-scan')
   })
@@ -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,338 @@ 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 packages below it 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)
+  })
+})
+
+// ── the project resolver, for a repo that declares no workspaces ───────────────────────────────
+//
+// linewatch keeps its whole basalt consumer in `web/` and declares no `workspaces` field anywhere.
+// Measured at its repo root, all three project-scoped commands got that wrong in a different way:
+// `check-theme` printed `✓ no off-palette colors` having scanned ZERO files, `doctor` inferred
+// `tokens-only` for a full Mantine consumer, and `sync` refused while naming `basalt-ui init` as
+// the remedy — the one command that WOULD have written a competing install at the root. The
+// workspace-declaration path already handled image-share's `apps/admin`; nothing handled this.
+
+/** linewatch's shape: no `workspaces` field, the whole consumer one directory down. */
+function undeclaredChild(child = 'web'): void {
+  write('package.json', JSON.stringify({ name: 'root' }))
+  write(`${child}/package.json`, JSON.stringify({ name: child, basalt: { roots: ['src'] } }))
+  write(`${child}/src/app.tsx`, "export const c = '#ff0000'\n")
+  write(join(child, MANIFEST_PATH), JSON.stringify({ version: 1, files: {} }))
+}
+
+describe('resolveProjectDir — a repo that declares no workspaces still has a layout', () => {
+  it('sync relocates into the undeclared child instead of refusing with init as the advice', () => {
+    undeclaredChild()
+    const { log } = capture(() => sync({ check: true }, dir))
+    expect(log).toContain('running in ./web, where it lives')
+    expect(log).not.toContain('basalt-ui init')
+  })
+
+  it('sync writes NOTHING at the root it was invoked from', () => {
+    undeclaredChild()
+    capture(() => sync({}, dir))
+    expect(readdirSync(dir).toSorted()).toEqual(['package.json', 'web'])
+    expect(readPkg()['basalt']).toBeUndefined()
+  })
+
+  it('check-theme scans the child rather than reporting green over zero files', () => {
+    undeclaredChild()
+    const { code, log } = capture(() => checkTheme(dir, []))
+    expect(log).toContain('running in ./web, where it lives')
+    expect(log).not.toContain('no off-palette colors')
+    expect(code).toBe(1)
+  })
+
+  it('doctor reports on the child, so it cannot infer tokens-only from the empty root', () => {
+    undeclaredChild()
+    const { log } = capture(() => doctor(dir, []))
+    expect(log).toContain(join(dir, 'web'))
+    expect(log).not.toContain('profile: tokens-only')
+  })
+
+  it('two undeclared children are ambiguous, named, and never guessed between', () => {
+    undeclaredChild('web')
+    undeclaredChild('admin')
+    const { code, log } = capture(() => sync({}, dir))
+    expect(code).toBe(1)
+    expect(log).toContain('2 packages below it carry one')
+    expect(log).toContain('./admin')
+    expect(log).toContain('./web')
+    expect(readdirSync(dir)).not.toContain('DESIGN.md')
+  })
+
+  it('a declared workspaces field still wins — the layout scan is a fallback, not a union', () => {
+    // `stray/` carries a basalt key but is not a workspace package. Treating both as candidates
+    // would turn a working single-candidate repo into an ambiguity error on upgrade.
+    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: {} }))
+    write('stray/package.json', JSON.stringify({ name: 'stray', basalt: { roots: ['src'] } }))
+    const { log } = capture(() => sync({ check: true }, dir))
+    expect(log).toContain('running in ./apps/web, where it lives')
+  })
+})
+
+// ── sync honours the profile doctor already reads ──────────────────────────────────────────────
+//
+// rollhook is tokens-only in both apps and declares it. `sync` told it to run `basalt-ui init` —
+// the exact advice `doctor`, in the same directory at the same version, exists to prevent — and
+// exited 1, which also put `sync --check` out of reach of the one CI drift gate every other
+// consumer runs.
+
+describe('sync — tokens-only is a pass, not a refusal', () => {
+  function tokensOnly(): void {
+    write(
+      'package.json',
+      JSON.stringify({ name: 'marketing', basalt: { roots: ['src'], profile: 'tokens-only' } }),
+    )
+    write('src/app.ts', 'export const c = 1\n')
+  }
+
+  it('reports n/a and exits 0, mirroring doctor’s manifest row', () => {
+    tokensOnly()
+    const { code, log } = capture(() => sync({}, dir))
+    expect(code).toBe(0)
+    expect(log).toContain('n/a — a tokens-only consumer has no scaffold to reconcile')
+    expect(log).not.toContain('basalt-ui init')
+  })
+
+  it('is wirable into CI: --check exits 0 instead of failing on a scaffold it must not have', () => {
+    tokensOnly()
+    expect(capture(() => sync({ check: true, flags: [] }, dir)).code).toBe(0)
+  })
+
+  it('writes nothing — no manifest, no DESIGN.md, no basalt.roots backfill', () => {
+    tokensOnly()
+    capture(() => sync({}, dir))
+    expect(readdirSync(dir).toSorted()).toEqual(['package.json', 'src'])
+  })
+
+  it('--framework forces the full profile back on', () => {
+    tokensOnly()
+    const { code, log } = capture(() => sync({ flags: ['--framework'] }, dir))
+    expect(code).toBe(1)
+    expect(log).toContain('refusing to scaffold')
+  })
+
+  it('contradictory profile flags exit 1, exactly as they do for check-theme and doctor', () => {
+    tokensOnly()
+    expect(capture(() => sync({ flags: ['--tokens-only', '--framework'] }, dir)).code).toBe(1)
+  })
+})
+
+// ── no shipped artifact carries a version number that goes stale ───────────────────────────────
+//
+// `DESIGN.md` is a seed: written once at init, then consumer-owned and never reconciled. Its
+// opener stamped `{{BASALT_VERSION}}`, so across the seven consumers the same line read 1.0.0,
+// 1.9.0, 1.21.0 and 1.22.0 under an identical 1.22.0 install — reported three rounds running as
+// four separate doc bugs. It was one bug: a version number in a file nothing ever rewrites.
+
+describe('DESIGN.md carries no version, and sync heals the ones already written', () => {
+  function seeded(): void {
+    write('package.json', JSON.stringify({ name: 'fixture', basalt: { roots: ['src'] } }))
+    write('src/app.tsx', 'export const App = () => null\n')
+    capture(() => init(dir))
+  }
+
+  it('a fresh scaffold stamps no version at all', () => {
+    seeded()
+    expect(read('DESIGN.md')).not.toMatch(/Managed by basalt-ui \(\d+\.\d+\.\d+\)/)
+    expect(read('DESIGN.md')).toContain('run `basalt-ui doctor` for the version')
+  })
+
+  it('sync rewrites a stale opener in place and leaves the rest of the file alone', () => {
+    seeded()
+    const consumerOwned = '\n## Series\n\nOurs: hrv, rhr.\n'
+    write('DESIGN.md', `# app — Design\n\n> Managed by basalt-ui (1.9.0). Thin.\n${consumerOwned}`)
+    capture(() => sync({}, dir))
+    expect(read('DESIGN.md')).toContain(
+      '> Managed by basalt-ui — run `basalt-ui doctor` for the version. Thin.',
+    )
+    expect(read('DESIGN.md')).toContain(consumerOwned)
+  })
+
+  it('--check writes nothing, including the heal', () => {
+    seeded()
+    const stale = '# app — Design\n\n> Managed by basalt-ui (1.9.0). Thin.\n'
+    write('DESIGN.md', stale)
+    capture(() => sync({ check: true }, dir))
+    expect(read('DESIGN.md')).toBe(stale)
+  })
+
+  it('leaves an opener the consumer already rewrote by hand untouched', () => {
+    seeded()
+    const owned = '# app — Design\n\n> Our own words entirely.\n'
+    write('DESIGN.md', owned)
+    capture(() => sync({}, dir))
+    expect(read('DESIGN.md')).toBe(owned)
+  })
+})

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,31 @@ 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, and that is WIDER than `basalt.roots` — two
+    // consumers reported a live `public/site.webmanifest` waiver under a scope line claiming
+    // files outside roots are not audited. The line has to name every class the scan reaches, or
+    // it is a second false statement in the sentence that exists to prevent one.
+    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 — everything under basalt.roots')
+    expect(log).toContain('sibling index.html and public/ tree')
+    expect(log).toContain('basalt.include')
+  })
+
   it('marks an unaccountable waiver while still reporting what it covers', () => {
     fixture("export const c = '#ff0000' // theme-allow\n")
     const { log } = audit()
@@ -129,3 +153,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'])
+  })
+})