basalt-ui 1.19.1 → 1.21.0

package/configs/oxlint-plugin.test.ts

@@ -11,6 +11,9 @@ import { afterEach, beforeEach, describe, expect, it } from 'bun:test'
 import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { dirname, resolve } from 'node:path'
+// eslint-disable-next-line -- the plugin is plain JS; the ledger + id set are named exports beside it
+import basaltPlugin, { KNOWN_RULE_IDS, PLUGIN_RULE_GRACE } from './oxlint-plugin.js'
+import { GUARD_RULES } from '../src/guard/index.ts'
 
 const PLUGIN_PATH = resolve(import.meta.dirname, 'oxlint-plugin.js')
 const OXLINT_BIN = resolve(import.meta.dirname, '..', '..', '..', 'node_modules', '.bin', 'oxlint')
@@ -30,6 +33,8 @@ beforeEach(() => {
         'basalt/chart-in-raw-surface': 'error',
         'basalt/hand-rolled-plot': 'error',
         'basalt/chart-legend-literal': 'error',
+        'basalt/shadow-basalt-export': 'error',
+        'basalt/hand-rolled-shell': 'error',
         'basalt/visx-boundary': 'error',
         'basalt/visx-tooltip': 'error',
         'basalt/token-layer-boundary': 'error',
@@ -46,7 +51,10 @@ afterEach(() => {
 })
 
 /** Writes `source` as the sole fixture file and runs oxlint against the temp fixture repo. */
-function run(source: string, filename = 'fixture.tsx'): { code: number; rules: Set<string> } {
+function run(
+  source: string,
+  filename = 'fixture.tsx',
+): { code: number; rules: Set<string>; output: string } {
   const filePath = resolve(dir, filename)
   mkdirSync(dirname(filePath), { recursive: true })
   writeFileSync(filePath, source)
@@ -55,7 +63,7 @@ function run(source: string, filename = 'fixture.tsx'): { code: number; rules: S
   const rules = new Set(
     [...output.matchAll(/\(basalt\/([\w-]+)\)/g)].map((match) => match[1] as string),
   )
-  return { code: result.exitCode ?? 0, rules }
+  return { code: result.exitCode ?? 0, rules, output }
 }
 
 // ── no-raw-font-size ─────────────────────────────────────────────────────────
@@ -355,28 +363,40 @@ describe('basalt/agent-no-raw-usechat', () => {
 
 describe('basalt/ai-sdk-major', () => {
   it("flags when the nearest package.json declares a different ai major (5 vs basalt's 7)", () => {
-    writeFileSync(resolve(dir, 'package.json'), JSON.stringify({ dependencies: { ai: '5.0.196' } }))
+    writeFileSync(
+      resolve(dir, 'package.json'),
+      JSON.stringify({ dependencies: { 'basalt-ui': '^1.19.1', ai: '5.0.196' } }),
+    )
     const { code, rules } = run(`import { streamText } from 'ai'\n`, 'lib.ts')
     expect(code).toBe(1)
     expect(rules).toContain('ai-sdk-major')
   })
 
   it('does NOT flag when the nearest package.json declares the same major (^7.0.18)', () => {
-    writeFileSync(resolve(dir, 'package.json'), JSON.stringify({ dependencies: { ai: '^7.0.18' } }))
+    writeFileSync(
+      resolve(dir, 'package.json'),
+      JSON.stringify({ dependencies: { 'basalt-ui': '^1.19.1', ai: '^7.0.18' } }),
+    )
     const { code, rules } = run(`import { streamText } from 'ai'\n`, 'lib.ts')
     expect(code).toBe(0)
     expect(rules).not.toContain('ai-sdk-major')
   })
 
   it('does NOT flag when there is no ai in the nearest package.json', () => {
-    writeFileSync(resolve(dir, 'package.json'), JSON.stringify({ dependencies: {} }))
+    writeFileSync(
+      resolve(dir, 'package.json'),
+      JSON.stringify({ dependencies: { 'basalt-ui': '^1.19.1' } }),
+    )
     const { code, rules } = run(`import { streamText } from 'ai'\n`, 'lib.ts')
     expect(code).toBe(0)
     expect(rules).not.toContain('ai-sdk-major')
   })
 
   it('does NOT flag an unrelated import even with a skewed nearest package.json', () => {
-    writeFileSync(resolve(dir, 'package.json'), JSON.stringify({ dependencies: { ai: '5.0.196' } }))
+    writeFileSync(
+      resolve(dir, 'package.json'),
+      JSON.stringify({ dependencies: { 'basalt-ui': '^1.19.1', ai: '5.0.196' } }),
+    )
     const { code, rules } = run(`import { useState } from 'react'\n`, 'lib.ts')
     expect(code).toBe(0)
     expect(rules).not.toContain('ai-sdk-major')
@@ -385,14 +405,20 @@ describe('basalt/ai-sdk-major', () => {
   // The matcher covers TWO forms (source === 'ai' OR source.startsWith('@ai-sdk/')) — every
   // fixture above only exercises the bare 'ai' specifier; this pins the scoped-package half.
   it("flags a scoped '@ai-sdk/*' import when the nearest package.json declares a different ai major", () => {
-    writeFileSync(resolve(dir, 'package.json'), JSON.stringify({ dependencies: { ai: '5.0.196' } }))
+    writeFileSync(
+      resolve(dir, 'package.json'),
+      JSON.stringify({ dependencies: { 'basalt-ui': '^1.19.1', ai: '5.0.196' } }),
+    )
     const { code, rules } = run(`import { openai } from '@ai-sdk/openai'\n`, 'lib.ts')
     expect(code).toBe(1)
     expect(rules).toContain('ai-sdk-major')
   })
 
   it("does NOT flag a scoped '@ai-sdk/*' import when the nearest package.json declares the same major", () => {
-    writeFileSync(resolve(dir, 'package.json'), JSON.stringify({ dependencies: { ai: '^7.0.18' } }))
+    writeFileSync(
+      resolve(dir, 'package.json'),
+      JSON.stringify({ dependencies: { 'basalt-ui': '^1.19.1', ai: '^7.0.18' } }),
+    )
     const { code, rules } = run(`import { openai } from '@ai-sdk/openai'\n`, 'lib.ts')
     expect(code).toBe(0)
     expect(rules).not.toContain('ai-sdk-major')
@@ -402,7 +428,10 @@ describe('basalt/ai-sdk-major', () => {
   // token as its two agent-chat siblings above — not `theme-allow`. A skewed producer/consumer
   // import that is genuinely intentional (see doctor's `aiMajorSkewReason`) can mark the line.
   it('does NOT flag an import marked basalt-agent-allow, even with a skewed nearest package.json', () => {
-    writeFileSync(resolve(dir, 'package.json'), JSON.stringify({ dependencies: { ai: '5.0.196' } }))
+    writeFileSync(
+      resolve(dir, 'package.json'),
+      JSON.stringify({ dependencies: { 'basalt-ui': '^1.19.1', ai: '5.0.196' } }),
+    )
     const { code, rules } = run(
       `// basalt-agent-allow\nimport { streamText } from 'ai'\n`,
       'lib.ts',
@@ -412,11 +441,67 @@ describe('basalt/ai-sdk-major', () => {
   })
 
   it('STILL flags an import marked only theme-allow (wrong escape token)', () => {
-    writeFileSync(resolve(dir, 'package.json'), JSON.stringify({ dependencies: { ai: '5.0.196' } }))
+    writeFileSync(
+      resolve(dir, 'package.json'),
+      JSON.stringify({ dependencies: { 'basalt-ui': '^1.19.1', ai: '5.0.196' } }),
+    )
     const { code, rules } = run(`// theme-allow\nimport { streamText } from 'ai'\n`, 'lib.ts')
     expect(code).toBe(1)
     expect(rules).toContain('ai-sdk-major')
   })
+
+  // The scoping fix: a workspace package with no basalt-ui dependency is not a basalt consumer, so
+  // its `ai` pin is none of this rule's business. rb's `apps/api` took 3 errors for exactly this,
+  // while `doctor` — which scopes the same concern by workspace — reported green.
+  it('does NOT flag a package that does not depend on basalt-ui at all', () => {
+    writeFileSync(resolve(dir, 'package.json'), JSON.stringify({ dependencies: { ai: '5.0.196' } }))
+    const { code, rules } = run(`import { streamText } from 'ai'\n`, 'lib.ts')
+    expect(code).toBe(0)
+    expect(rules).not.toContain('ai-sdk-major')
+  })
+
+  it('does NOT flag a file outside a declared basalt.roots', () => {
+    writeFileSync(
+      resolve(dir, 'package.json'),
+      JSON.stringify({ basalt: { roots: ['web/src'] }, dependencies: { ai: '5.0.196' } }),
+    )
+    const { code, rules } = run(`import { streamText } from 'ai'\n`, 'api/src/llm.ts')
+    expect(code).toBe(0)
+    expect(rules).not.toContain('ai-sdk-major')
+  })
+
+  // The ORDERING half of the scoping fix, and the layout `init` produces for a monorepo: one
+  // manifest carrying BOTH the workspace-root CLI devDependency and `basalt.roots` naming the app.
+  // Dep-first returned in-scope on that root before `roots` was ever read, so rb's `apps/api` — no
+  // basalt dependency, deliberately on a different `ai` major, explicitly outside the roots — kept
+  // taking 3 errors and kept its `.oxlintrc.json` override.
+  it('reads basalt.roots BEFORE the basalt-ui dependency in the same manifest', () => {
+    writeFileSync(
+      resolve(dir, 'package.json'),
+      JSON.stringify({
+        basalt: { roots: ['apps/web/src'] },
+        devDependencies: { 'basalt-ui': '^1.20.0' },
+        dependencies: { ai: '5.0.196' },
+      }),
+    )
+    const outside = run(`import { streamText } from 'ai'\n`, 'apps/api/src/llm.ts')
+    expect(outside.code).toBe(0)
+    expect(outside.rules).not.toContain('ai-sdk-major')
+
+    // …and the declared root itself is still in scope, so the reorder narrows nothing it shouldn't.
+    const inside = run(`import { streamText } from 'ai'\n`, 'apps/web/src/llm.ts')
+    expect(inside.rules).toContain('ai-sdk-major')
+  })
+
+  it('DOES flag a file inside a declared basalt.roots', () => {
+    writeFileSync(
+      resolve(dir, 'package.json'),
+      JSON.stringify({ basalt: { roots: ['web/src'] }, dependencies: { ai: '5.0.196' } }),
+    )
+    const { code, rules } = run(`import { streamText } from 'ai'\n`, 'web/src/llm.ts')
+    expect(code).toBe(1)
+    expect(rules).toContain('ai-sdk-major')
+  })
 })
 
 // ── raw-scroll-container — promotion (off → warn → error shipped) ───────────
@@ -500,11 +585,13 @@ describe('basalt/hand-rolled-plot', () => {
     expect(rules).not.toContain('hand-rolled-plot')
   })
 
-  it('reports ONCE per file — declaring the exception is a file-level decision', () => {
+  // `theme-allow-file` is the written declaration about the file, and it covers every assembly node
+  // in it — the DualPanel shape.
+  it('a theme-allow-file declaration covers the whole file', () => {
     const { code, rules } = run(
       `${CHARTS_IMPORT}export const C = () => (
   <svg>
-    {/* theme-allow: multi-pane shape, not a single cartesian plot */}
+    {/* theme-allow-file basalt/hand-rolled-plot: multi-pane shape, not a single cartesian plot */}
     <AxisLeftNumeric scale={a} />
     <HoverOverlay width={1} height={1} />
     <Crosshair x={0} top={0} bottom={1} />
@@ -515,6 +602,54 @@ describe('basalt/hand-rolled-plot', () => {
     expect(rules).not.toContain('hand-rolled-plot')
   })
 
+  // The other half of the 1.20.0 fix. Naming the rule AND giving a reason used to promote the
+  // waiver to the whole file, which made whole-file the ONLY expressible scope: the shape the rule's
+  // own message asks for was the shape that granted immunity. It is now what it reads as — one node.
+  it('a named-with-a-reason theme-allow waives its own node ONLY, not the file', () => {
+    const { code, rules } = run(
+      `${CHARTS_IMPORT}export const C = () => (
+  <svg>
+    {/* theme-allow basalt/hand-rolled-plot — this one axis is drawn against a second scale */}
+    <AxisLeftNumeric scale={a} />
+    <HoverOverlay width={1} height={1} />
+  </svg>
+)\n`,
+    )
+    expect(code).toBe(1)
+    expect(rules).toContain('hand-rolled-plot')
+  })
+
+  // The linewatch defect: a BARE comment used to buy the whole file permanent immunity, because
+  // only the first node was reported and the waiver was tested there. It now waives its own node
+  // and nothing else, so everything added to the file afterwards is still reported.
+  it('a bare theme-allow waives only the node it sits above, not the file', () => {
+    const { code, rules } = run(
+      `${CHARTS_IMPORT}export const C = () => (
+  <svg>
+    {/* theme-allow */}
+    <AxisLeftNumeric scale={a} />
+    <HoverOverlay width={1} height={1} />
+  </svg>
+)\n`,
+    )
+    expect(code).toBe(1)
+    expect(rules).toContain('hand-rolled-plot')
+  })
+
+  // A comment written about something else must not double as a licence to hand-assemble a plot.
+  it('a theme-allow scoped to a DIFFERENT rule does not waive this one', () => {
+    const { code, rules } = run(
+      `${CHARTS_IMPORT}export const C = () => (
+  <svg>
+    {/* theme-allow raw-hex — the swatch below is a measured pixel */}
+    <AxisLeftNumeric scale={a} />
+  </svg>
+)\n`,
+    )
+    expect(code).toBe(1)
+    expect(rules).toContain('hand-rolled-plot')
+  })
+
   it('does NOT flag a same-named component that is NOT a basalt chart primitive', () => {
     const { code, rules } = run(
       `import { Crosshair } from './my-own-widgets'
@@ -524,25 +659,152 @@ export const C = () => <svg><Crosshair x={0} /></svg>\n`,
     expect(rules).not.toContain('hand-rolled-plot')
   })
 
+  // `code` is 1 in both of these and that is correct: a CONSUMER file declaring `CartesianChart`
+  // shadows a basalt export, which `shadow-basalt-export` now sees since it reads the charts barrel
+  // too. The assertion under test is that `hand-rolled-plot` stays silent — a rule saying "compose
+  // X" cannot fire inside X.
   it('does NOT flag the module that DEFINES CartesianChart (function form)', () => {
-    const { code, rules } = run(
+    const { rules } = run(
       `import { AxisBottomDate } from '../primitives/Axes'
 export function CartesianChart() {
   return <svg><AxisBottomDate scale={s} top={0} tickValues={[]} /></svg>
 }\n`,
     )
-    expect(code).toBe(0)
     expect(rules).not.toContain('hand-rolled-plot')
   })
 
   it('does NOT flag the module that DEFINES CartesianChart (const form)', () => {
-    const { code, rules } = run(
+    const { rules } = run(
       `import { AxisBottomDate } from '../primitives/Axes'
 export const CartesianChart = () => <svg><AxisBottomDate scale={s} top={0} tickValues={[]} /></svg>\n`,
+    )
+    expect(rules).not.toContain('hand-rolled-plot')
+  })
+})
+
+// ── theme-allow grammar — the accepted and rejected shapes, exhaustively ─────
+//
+// Two rounds produced three holes in this one contract, so it gets a matrix rather than a case.
+// `hand-rolled-plot` is the vehicle: it is the only rule with BOTH scopes, so one fixture shape
+// exercises the node waiver, the file declaration and the prefix rule at once.
+
+describe('theme-allow grammar', () => {
+  /** Two assembly nodes, with `annotation` placed as a comment-only line above the first. */
+  function twoNodes(annotation: string): { code: number; rules: Set<string> } {
+    return run(
+      `${CHARTS_IMPORT}export const C = () => (
+  <svg>
+    ${annotation}
+    <AxisLeftNumeric scale={a} />
+    <HoverOverlay width={1} height={1} />
+  </svg>
+)\n`,
+    )
+  }
+
+  const waivesFirstNodeOnly = (annotation: string) => {
+    const { rules } = twoNodes(annotation)
+    expect([annotation, rules.has('hand-rolled-plot')]).toEqual([annotation, true])
+  }
+  const waivesWholeFile = (annotation: string) => {
+    const { rules } = twoNodes(annotation)
+    expect([annotation, rules.has('hand-rolled-plot')]).toEqual([annotation, false])
+  }
+
+  // ── ACCEPTED as a NODE waiver (the second node still reports) ──────────────
+
+  it.each([
+    '{/* theme-allow */}',
+    '{/* theme-allow hand-rolled-plot */}',
+    '{/* theme-allow hand-rolled-plot — a reason */}',
+    '{/* theme-allow basalt/hand-rolled-plot: a reason */}',
+    '{/* theme-allow hand-rolled-plot, raw-hex — two ids */}',
+    '{/*theme-allow hand-rolled-plot — no space after the opener*/}',
+  ])('%s waives its own node and leaves the rest policed', waivesFirstNodeOnly)
+
+  // ── ACCEPTED as a FILE declaration (nothing in the file reports) ───────────
+
+  it.each([
+    '{/* theme-allow-file hand-rolled-plot — a reason */}',
+    '{/* theme-allow-file basalt/hand-rolled-plot: a reason */}',
+    '{/* theme-allow-file hand-rolled-plot */}',
+    '{/* theme-allow-file hand-rolled-plot, chart-legend-literal — two ids */}',
+  ])('%s declares the whole file', waivesWholeFile)
+
+  it('a theme-allow-file inside a docblock, detached from any node, declares the file', () => {
+    const { code, rules } = run(
+      `${CHARTS_IMPORT}/**
+ * A two-pane shape.
+ *
+ * theme-allow-file hand-rolled-plot — two panes over one x scale is not a single plot
+ */
+export const C = () => (
+  <svg>
+    <AxisLeftNumeric scale={a} />
+    <HoverOverlay width={1} height={1} />
+  </svg>
+)\n`,
     )
     expect(code).toBe(0)
     expect(rules).not.toContain('hand-rolled-plot')
   })
+
+  // ── REJECTED — prose that merely MENTIONS the token (the linewatch defect) ─
+
+  // The whole class: a file documenting its own waivers used to disarm itself. Every one of these
+  // parsed as the bare blanket form under the old `indexOf('theme-allow')` and silenced the node
+  // below it. All four are shapes taken from real consumer source.
+  it.each([
+    '{/* Since 1.20.0 a `theme-allow` that names a rule is a file declaration */}',
+    '{/* see the theme-allow contract for how this file is waived */}',
+    '{/* `theme-allow` with a reason declares the whole FILE wherever it is written */}',
+    '{/* each with a theme-allow saying why */}',
+  ])('%s is prose, not an annotation — it waives nothing', (annotation) => {
+    const { code, rules } = twoNodes(annotation)
+    expect([annotation, code]).toEqual([annotation, 1])
+    expect([annotation, rules.has('hand-rolled-plot')]).toEqual([annotation, true])
+  })
+
+  it('a prose docblock line mentioning theme-allow-file does not declare the file', () => {
+    const { rules } = twoNodes(
+      '{/* the shape to write here is a theme-allow-file hand-rolled-plot — see the docs */}',
+    )
+    expect(rules).toContain('hand-rolled-plot')
+  })
+
+  // ── REJECTED — a longer word that merely STARTS with the token ─────────────
+
+  // `theme-allow-unscoped` is a KIND NAME, written in prose constantly. It used to consume no id,
+  // fall through to the empty-`rules` branch, and read as a blanket waiver.
+  it('a comment starting with the kind name `theme-allow-unscoped` is not an annotation', () => {
+    const { rules } = twoNodes('{/* theme-allow-unscoped is what reports a bare waiver */}')
+    expect(rules).toContain('hand-rolled-plot')
+  })
+
+  // ── REJECTED — a bare file declaration, and a typo'd id ────────────────────
+
+  it('a BARE theme-allow-file waives nothing — file scope must name its ids', () => {
+    const { code, rules } = twoNodes('{/* theme-allow-file — everything in here is bespoke */}')
+    expect(code).toBe(1)
+    expect(rules).toContain('hand-rolled-plot')
+  })
+
+  it("a theme-allow-file naming a typo'd id waives nothing", () => {
+    const { rules } = twoNodes('{/* theme-allow-file hand-rolled-plott — a reason */}')
+    expect(rules).toContain('hand-rolled-plot')
+  })
+
+  it('a theme-allow-file scoped to a DIFFERENT rule does not waive this one', () => {
+    const { rules } = twoNodes('{/* theme-allow-file raw-hex — the swatch is a measured pixel */}')
+    expect(rules).toContain('hand-rolled-plot')
+  })
+
+  // ── REJECTED — the token inside a string literal, not a comment ────────────
+
+  it('the token inside a string literal is code, not an annotation', () => {
+    const { rules } = twoNodes("{'theme-allow hand-rolled-plot — a reason'}")
+    expect(rules).toContain('hand-rolled-plot')
+  })
 })
 
 // ── chart-legend-literal ─────────────────────────────────────────────────────
@@ -583,3 +845,320 @@ describe('basalt/chart-legend-literal', () => {
     expect(rules).not.toContain('chart-legend-literal')
   })
 })
+
+// ── shadow-basalt-export ─────────────────────────────────────────────────────
+
+describe('basalt/shadow-basalt-export', () => {
+  it('flags a local component that collides with a basalt-ui root export', () => {
+    const { code, rules } = run(`export function EmptyState() { return null }\n`)
+    expect(code).toBe(1)
+    expect(rules).toContain('shadow-basalt-export')
+  })
+
+  it('flags the arrow/const form too (rb shipped a local StatCard)', () => {
+    const { code, rules } = run(`const StatCard = () => null\nexport default StatCard\n`)
+    expect(code).toBe(1)
+    expect(rules).toContain('shadow-basalt-export')
+  })
+
+  it('does NOT flag a name basalt does not export', () => {
+    const { code, rules } = run(`export function ExerciseSummaryCard() { return null }\n`)
+    expect(code).toBe(0)
+    expect(rules).not.toContain('shadow-basalt-export')
+  })
+
+  // The rule read ONLY the root barrel, and `./charts` is deliberately not re-exported from it —
+  // so a consumer whose forks all live in the chart layer, which is the layer forks actually live
+  // in, could never trip it. Correctly silent, for the wrong reason.
+  it('sees the charts layer, not just the root barrel', () => {
+    const { code, rules } = run(`export function ChartCard() { return null }\n`)
+    expect(code).toBe(1)
+    expect(rules).toContain('shadow-basalt-export')
+  })
+
+  it('sees the content layer too', () => {
+    const { rules } = run(`export function ReadingProgress() { return null }\n`)
+    expect(rules).toContain('shadow-basalt-export')
+  })
+
+  // …but a barrel is not only basalt's own names. `./charts` re-exports `Bar`, `Line`, `Pie`,
+  // `AreaClosed` … straight from `@visx/shape`, and a local `Bar` is not a fork of anything basalt
+  // wrote. The playground's own demo tripped on it the moment the rule started reading that barrel.
+  it('does NOT flag a name the barrel merely re-exports from a third party', () => {
+    const { code, rules } = run(`export function Bar() { return null }\n`)
+    expect(code).toBe(0)
+    expect(rules).not.toContain('shadow-basalt-export')
+  })
+
+  // A NAME collision is the whole of the signal, so renaming defeats the rule in one keystroke —
+  // linewatch's forks are `Cell` and `Box`, rb's is `Stat`, and all three are invisible here. That
+  // limit cannot be closed without intent analysis, so the rule STATES it rather than implying
+  // coverage it does not have.
+  it('a renamed fork is invisible, and the message says so rather than implying coverage', () => {
+    expect(run(`export function Stat() { return null }\n`).rules).not.toContain(
+      'shadow-basalt-export',
+    )
+    const { output } = run(`export function EmptyState() { return null }\n`)
+    expect(output).toContain('tripwire, not coverage')
+    expect(output).toContain('Silence here is not evidence')
+  })
+
+  // The export list is derived from the real barrel, so a TYPE export must not create a collision:
+  // a local `StatCardProps` is an ordinary thing for a consumer to declare.
+  it('does NOT flag a name that basalt exports only as a type', () => {
+    const { code, rules } = run(`export type StatCardProps = { label: string }\n`, 'types.ts')
+    expect(code).toBe(0)
+    expect(rules).not.toContain('shadow-basalt-export')
+  })
+
+  it('is waivable with a scoped theme-allow', () => {
+    const { code, rules } = run(
+      `// theme-allow basalt/shadow-basalt-export — domain-specific, unrelated to the shipped one\nexport function EmptyState() { return null }\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('shadow-basalt-export')
+  })
+})
+
+// ── hand-rolled-shell ────────────────────────────────────────────────────────
+
+describe('basalt/hand-rolled-shell', () => {
+  it('flags a hand-assembled Mantine AppShell', () => {
+    const { code, rules } = run(
+      `import { AppShell, Burger } from '@mantine/core'
+export const Shell = () => (
+  <AppShell>
+    <AppShell.Header><Burger opened={false} /></AppShell.Header>
+    <AppShell.Navbar>nav</AppShell.Navbar>
+  </AppShell>
+)\n`,
+    )
+    expect(code).toBe(1)
+    expect(rules).toContain('hand-rolled-shell')
+  })
+
+  it('does NOT flag a file that renders BasaltShell', () => {
+    const { code, rules } = run(
+      `import { AppShell } from '@mantine/core'
+import { BasaltShell } from 'basalt-ui'
+export const Shell = () => <BasaltShell sections={[]}><AppShell.Main>x</AppShell.Main></BasaltShell>\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('hand-rolled-shell')
+  })
+
+  // Exempt by DECLARATION, not by path — a rule saying "compose X" cannot fire inside X. (The
+  // fixture also trips `shadow-basalt-export`, which is correct for a consumer file and irrelevant
+  // here, so this asserts the rule set rather than the exit code.)
+  it('does NOT flag the module that DEFINES BasaltShell', () => {
+    const { rules } = run(
+      `import { AppShell } from '@mantine/core'
+export function BasaltShell() { return <AppShell.Navbar>nav</AppShell.Navbar> }\n`,
+    )
+    expect(rules).not.toContain('hand-rolled-shell')
+  })
+
+  it("does NOT flag a consumer's own AppShell-named component with no @mantine import", () => {
+    const { code, rules } = run(
+      `import { AppShell } from './my-layout'
+export const C = () => <AppShell.Navbar>nav</AppShell.Navbar>\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('hand-rolled-shell')
+  })
+
+  it('does NOT flag a standalone Mantine NavLink (deliberately not a trigger)', () => {
+    const { code, rules } = run(
+      `import { NavLink } from '@mantine/core'
+export const C = () => <NavLink label="Settings" />\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('hand-rolled-shell')
+  })
+})
+
+// ── grace ledger ↔ shipped preset ────────────────────────────────────────────
+
+describe('PLUGIN_RULE_GRACE', () => {
+  const shipped = JSON.parse(readFileSync(resolve(import.meta.dirname, 'oxlint.json'), 'utf8')) as {
+    rules: Record<string, unknown>
+  }
+  const graceIds = Object.keys(PLUGIN_RULE_GRACE)
+  const shippedBasaltIds = Object.keys(shipped.rules).filter((id) => id.startsWith('basalt/'))
+
+  // The mechanism whose ABSENCE let three rules sit at `warn` for up to twelve minors with nothing
+  // tracking them. Deleting a ledger entry IS the promotion, and this test makes flipping the
+  // shipped level part of the same commit.
+  it('every ledger entry is warn in the shipped preset', () => {
+    for (const id of graceIds) expect(shipped.rules[`basalt/${id}`]).toBe('warn')
+  })
+
+  it('every shipped rule NOT in the ledger is error', () => {
+    for (const id of shippedBasaltIds) {
+      if (graceIds.includes(id.slice('basalt/'.length))) continue
+      expect([id, shipped.rules[id]]).toEqual([id, 'error'])
+    }
+  })
+
+  it('every ledger entry carries a written promotion note', () => {
+    for (const id of graceIds) {
+      expect((PLUGIN_RULE_GRACE as Record<string, string>)[id]?.length ?? 0).toBeGreaterThan(40)
+    }
+  })
+})
+
+// ── chart-legend-literal: the .map() half ────────────────────────────────────
+
+describe('basalt/chart-legend-literal — derived-from-series', () => {
+  const IMPORT = `import { ChartLegend } from 'basalt-ui/charts'\n`
+
+  // Deriving from *an* array is not deriving from *the* series: every field of a
+  // `refLines.map(...)` / `PACE_ZONES.map(...)` legend is authored at the call site, and the list
+  // can keep naming a band the plot no longer draws exactly like a `[...]` literal can.
+  it('flags a .map() over a non-series array', () => {
+    const { code, rules } = run(
+      `${IMPORT}export const C = () => <ChartLegend items={refLines.map((r) => ({ key: r.k, label: r.l }))} />\n`,
+    )
+    expect(code).toBe(1)
+    expect(rules).toContain('chart-legend-literal')
+  })
+
+  it('does NOT flag a .map() over the series', () => {
+    const { code, rules } = run(
+      `${IMPORT}export const C = () => <ChartLegend items={series.map((s) => ({ key: s.key }))} />\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('chart-legend-literal')
+  })
+
+  it('does NOT flag a .map() over a derived series binding', () => {
+    const { code, rules } = run(
+      `${IMPORT}export const C = () => <ChartLegend items={visibleSeries.map((s) => ({ key: s.key }))} />\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('chart-legend-literal')
+  })
+
+  it('does NOT flag deriveLegend(series)', () => {
+    const { code, rules } = run(
+      `${IMPORT}export const C = () => <ChartLegend items={deriveLegend(series)} />\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('chart-legend-literal')
+  })
+})
+
+// ── no-raw-font-size: style-context scoping ──────────────────────────────────
+
+describe('basalt/no-raw-font-size — style context', () => {
+  it('flags a fontSize inside a style attribute', () => {
+    const { code, rules } = run(`export const C = () => <div style={{ fontSize: 11 }} />\n`)
+    expect(code).toBe(1)
+    expect(rules).toContain('no-raw-font-size')
+  })
+
+  it('flags a fontSize inside a Mantine styles per-part object', () => {
+    const { code, rules } = run(
+      `export const C = () => <TextInput styles={{ input: { fontSize: 12 } }} />\n`,
+    )
+    expect(code).toBe(1)
+    expect(rules).toContain('no-raw-font-size')
+  })
+
+  it('flags a fontSize in a CSSProperties-annotated const', () => {
+    const { code, rules } = run(
+      `import type { CSSProperties } from 'react'\nconst rowLook: CSSProperties = { fontSize: 11 }\nexport { rowLook }\n`,
+      'look.ts',
+    )
+    expect(code).toBe(1)
+    expect(rules).toContain('no-raw-font-size')
+  })
+
+  // The obsidian false positive: a `fontSize` key in a plain data object, in a package with no
+  // React and no Mantine, where "route it through VX.text.*" is advice about another domain.
+  it('does NOT flag a fontSize key in a plain data object', () => {
+    const { code, rules } = run(
+      `export const iconizeData = { settings: { fontSize: 16 }, Inbox: 'LiInbox' }\n`,
+      'data.ts',
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('no-raw-font-size')
+  })
+
+  it('does NOT run in a test file at all', () => {
+    const { code, rules } = run(
+      `export const C = () => <div style={{ fontSize: 11 }} />\n`,
+      'nav-config.test.tsx',
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('no-raw-font-size')
+  })
+})
+
+// ── KNOWN_RULE_IDS — the hand-maintained list a typo'd theme-allow is measured against ──────────
+
+describe('KNOWN_RULE_IDS', () => {
+  // Forgetting an entry is not cosmetic: an id this set does not know is treated as a typo, so the
+  // annotation naming it waives nothing. Before the fail-closed fix it was worse — an unknown id
+  // fell through to the empty-`rules` branch and became a BLANKET waiver, which is how a
+  // hand-maintained duplicate turned a missing entry into a hole in the guard.
+  it('contains every rule the plugin actually exports', () => {
+    for (const id of Object.keys(basaltPlugin.rules)) {
+      expect([id, KNOWN_RULE_IDS.has(id)]).toEqual([id, true])
+    }
+  })
+
+  it('contains every guard kind', () => {
+    for (const kind of Object.keys(GUARD_RULES)) {
+      expect([kind, KNOWN_RULE_IDS.has(kind)]).toEqual([kind, true])
+    }
+  })
+
+  it('contains nothing else — it is exactly the union of the two registries', () => {
+    const expected = [...Object.keys(basaltPlugin.rules), ...Object.keys(GUARD_RULES)].toSorted()
+    expect([...KNOWN_RULE_IDS].toSorted()).toEqual(expected)
+  })
+})
+
+// ── theme-allow fails closed on a typo ─────────────────────────────────────────────────────────
+
+describe('theme-allow with an unrecognized rule id', () => {
+  it('waives nothing rather than escalating to a blanket suppression', () => {
+    // `no-raw-font-size` would be waived by a bare `theme-allow`. A typo'd id must not do that.
+    const { code, rules } = run(
+      `export const C = () => <Text fz={10} /> // theme-allow no-raw-font-sizee — legacy\n`,
+    )
+    expect(code).toBe(1)
+    expect(rules).toContain('no-raw-font-size')
+  })
+
+  it('a correctly spelled id still waives', () => {
+    const { code, rules } = run(
+      `export const C = () => <Text fz={10} /> // theme-allow no-raw-font-size — legacy\n`,
+    )
+    expect(rules).not.toContain('no-raw-font-size')
+    expect(code).toBe(0)
+  })
+
+  it('a bare theme-allow still waives everything', () => {
+    const { rules } = run(`export const C = () => <Text fz={10} /> // theme-allow\n`)
+    expect(rules).not.toContain('no-raw-font-size')
+  })
+
+  it('does not resolve an Object.prototype key as a rule id', () => {
+    const { code, rules } = run(
+      `export const C = () => <Text fz={10} /> // theme-allow constructor — inherited key\n`,
+    )
+    expect(code).toBe(1)
+    expect(rules).toContain('no-raw-font-size')
+  })
+
+  // The id slot closes at the first space no comma opened — mirrors `parseAllowAnnotation`.
+  it('reads an unknown word after a resolved id as the reason, not as a second id', () => {
+    const { code, rules } = run(
+      `export const C = () => <Text fz={10} /> // theme-allow no-raw-font-size sub-scale micro label\n`,
+    )
+    expect(rules).not.toContain('no-raw-font-size')
+    expect(code).toBe(0)
+  })
+})