basalt-ui 1.19.1 → 1.21.0

package/configs/oxlint-plugin.js

@@ -9,10 +9,13 @@
  * `./oxlint-plugin.js` — a consumer `extends`-ing that preset inherits `jsPlugins` too, and the
  * path resolves relative to the preset file, not the consumer's own config.
  *
- * The four design-guard rules below support the same `theme-allow` escape as `src/guard`: skip a
- * reported node if a line comment containing `theme-allow` sits on the node's own line or the line
- * immediately above it. The three boundary rules deliberately do NOT — see their own comment for
- * why.
+ * The design-guard rules below support the same `theme-allow` escape as `src/guard`, and the same
+ * two-scope grammar: `theme-allow [<id>…] [— <why>]` at the START of a comment on the reported
+ * node's own line or the line above skips THAT node; `theme-allow-file <id>… — <why>` anywhere in
+ * the file skips every node of the named rules in it. Both halves are load-bearing — see
+ * {@link parseThemeAllows} for why the prefix matters and {@link hasFileDeclaration} for why file
+ * scope has to be spelled. The three boundary rules deliberately honour neither — see their own
+ * comment for why.
  *
  * ── The two agent-chat guard rules (`agent-resume-guard` / `agent-no-raw-usechat`) + `ai-sdk-major` ──
  * These are also correctness/architecture boundaries, not design guidance, so they do NOT honour
@@ -77,18 +80,218 @@ import { fileURLToPath } from 'node:url'
 
 // ── Shared helpers ──────────────────────────────────────────────────────────────────────────────
 
-/** True when a `theme-allow` line comment sits on `node`'s own source line or the line above it. */
-function hasThemeAllow(context, node) {
+/**
+ * Rule ids a `theme-allow` may name — this plugin's own rules plus `src/guard`'s kinds. Duplicated
+ * by hand for the same reason `majorOf` is: this file loads standalone out of a consumer's
+ * node_modules and must not import from the package.
+ *
+ * Exported, and `oxlint-plugin.test.ts` asserts it is EXACTLY the plugin's own rule ids plus
+ * `GUARD_RULES`'s keys. Forgetting an entry here is not a cosmetic omission — an id this set does
+ * not know is treated as a typo, so the annotation naming it waives nothing (see
+ * {@link parseThemeAllow}); before the fail-closed change it was worse still, silently widening to
+ * a blanket waiver.
+ */
+export const KNOWN_RULE_IDS = new Set([
+  // this plugin
+  'no-raw-font-size',
+  'raw-size-literal',
+  'card-inset',
+  'chart-in-raw-surface',
+  'hand-rolled-plot',
+  'chart-legend-literal',
+  'hand-rolled-shell',
+  'shadow-basalt-export',
+  'raw-scroll-container',
+  'visx-boundary',
+  'visx-tooltip',
+  'token-layer-boundary',
+  // These three honour `basalt-agent-allow`, never `theme-allow` — but they are real ids, so an
+  // annotation naming one must parse as a (useless) scoped annotation rather than as prose.
+  'agent-resume-guard',
+  'agent-no-raw-usechat',
+  'ai-sdk-major',
+  // src/guard kinds
+  'raw-hex',
+  'raw-color-fn',
+  'localstorage-theme',
+  'off-identity-accent',
+  'mantine-shade-index',
+  'raw-spacing',
+  'raw-radius',
+  'raw-surface',
+  'card-with-border',
+  'off-system-surface-var',
+  'raw-html-layout',
+  'inline-spacing',
+  'inline-display',
+  'raw-visx-axis',
+  'raw-motion-value',
+  'unframed-chart',
+  'chart-missing-aria-label',
+  'raw-form-control',
+  'sub-16-input-font',
+  'raw-font-family',
+  'theme-allow-unscoped',
+  'surface-shadow-override',
+  'css-raw-surface',
+  'inline-font-size',
+  'hidden-inline-style',
+])
+
+const ALLOW_RULE_TOKEN = /^(?:basalt\/)?([a-z][a-z0-9-]*)(?=$|[\s,:—–])/
+const ALLOW_REASON_SEPARATOR = /^(?:—|–|-{1,2}|:)\s*/
+/** Shortest string accepted as a written reason — enough to exclude a stray separator. */
+const MIN_ALLOW_REASON_LENGTH = 4
+
+/**
+ * The annotation token, with its optional `-file` suffix.
+ *
+ * `(?![\w-])` keeps the two forms apart AND stops a longer word from parsing as the bare form:
+ * `theme-allow-unscoped` — the KIND NAME, written in prose constantly — used to consume no id, fall
+ * through to `rules: []` and read as a blanket waiver.
+ */
+const ALLOW_TOKEN = /theme-allow(-file)?(?![\w-])/
+
+/**
+ * Everything permitted between the start of a line INSIDE the comment and the token.
+ *
+ * The annotation has to START its comment (or a line of one — the `*` is a block-comment gutter).
+ * Without this the parser did a bare `indexOf('theme-allow')`, so a comment that merely MENTIONED
+ * the token in prose parsed as the blanket form and switched every rule off on the node below it.
+ * linewatch documented its own waivers in a docblock and thereby disarmed the file: a false
+ * NEGATIVE, and worse than the whole-file hole 1.20.0 closed. `src/guard`'s `ANNOTATION_PREFIX` is
+ * the same test against raw source text (which still carries its `//` / `/*` opener; a comment
+ * NODE's `value` does not, hence the two spellings).
+ */
+const ALLOW_LINE_PREFIX = /^\s*\*?\s*$/
+
+/** Parse the text following the token — ids, then the reason. See {@link parseThemeAllows}. */
+function parseAllowBody(rest, scope) {
+  let remainder = rest.replace(/^[\s,]+/, '')
+  const rules = []
+  const unknownRules = []
+  let inIdSlot = true
+  for (;;) {
+    const token = ALLOW_RULE_TOKEN.exec(remainder)
+    if (token === null) break
+    if (!KNOWN_RULE_IDS.has(token[1])) {
+      if (inIdSlot) unknownRules.push(token[1])
+      break
+    }
+    rules.push(token[1])
+    const after = remainder.slice(token[0].length)
+    remainder = after.replace(/^[\s,]+/, '')
+    inIdSlot = /^\s*,/.test(after)
+  }
+  const reason = remainder.replace(ALLOW_REASON_SEPARATOR, '').trim()
+  return { rules, unknownRules, hasReason: reason.length >= MIN_ALLOW_REASON_LENGTH, scope }
+}
+
+/**
+ * Every annotation one comment carries. A docblock can hold more than one, so this returns a list.
+ *
+ * The grammar, and it is the same one `src/guard` parses:
+ *
+ * ```text
+ * theme-allow                             → this node, EVERY rule (the legacy bare form)
+ * theme-allow <id>[, <id>…] [— <why>]     → this node, those rules
+ * theme-allow-file <id>[, <id>…] — <why>  → the WHOLE FILE, those rules
+ * ```
+ *
+ * `{ rules: [], unknownRules: [] }` is the bare form; a non-empty `rules` scopes the exception to
+ * exactly those ids. A word that occupies the id slot but names no known rule lands in
+ * `unknownRules` and FAILS CLOSED — the annotation then waives only the ids it got right, never
+ * everything. `theme-allow raw-hexx — reason` used to consume no id, fall through to the
+ * empty-`rules` branch and be read as the blanket form, so one mistyped character escalated a
+ * scoped waiver into a whole-line one, i.e. weaker than before the scoping existed.
+ *
+ * A prose reason is therefore introduced with a separator (`—`, `–`, `-`, `:`), which is how every
+ * annotation in the wild already writes it.
+ *
+ * The id slot closes at the first space that no comma opened: the first word is always a claimed
+ * id (that is where a typo lands), but after a resolved id only a `,` keeps the list open, so
+ * `theme-allow raw-surface sub-scale legend corner` reads `sub-scale` as prose rather than as a
+ * typo. See the guard's copy for the full reasoning.
+ */
+function parseThemeAllows(commentValue) {
+  const out = []
+  for (const rawLine of commentValue.split('\n')) {
+    const token = ALLOW_TOKEN.exec(rawLine)
+    if (token === null) continue
+    if (!ALLOW_LINE_PREFIX.test(rawLine.slice(0, token.index))) continue
+    const rest = rawLine.slice(token.index + token[0].length)
+    out.push(parseAllowBody(rest, token[1] === undefined ? 'line' : 'file'))
+  }
+  return out
+}
+
+/**
+ * Does one annotation cover `ruleId`?
+ *
+ * Only a BARE **node** annotation covers every rule. A bare `theme-allow-file` covers nothing: the
+ * blanket form is tolerable on one line, where a reader sees what it sits on; over a whole file it
+ * is a config exemption without the config review, so the widest waiver in the contract is the one
+ * that has to name what it waives.
+ */
+function allowCovers(allow, ruleId) {
+  if (allow.rules.includes(ruleId)) return true
+  if (allow.scope === 'file') return false
+  return allow.rules.length === 0 && allow.unknownRules.length === 0
+}
+
+function allComments(context) {
   const sourceCode = context.sourceCode ?? context.getSourceCode?.()
-  const comments = sourceCode?.getAllComments?.() ?? []
+  return sourceCode?.getAllComments?.() ?? []
+}
+
+/**
+ * True when a NODE-scoped `theme-allow` covering `ruleId` sits on `node`'s own source line or the
+ * line above — or when the file carries a `theme-allow-file` declaration for it.
+ *
+ * The `ruleId` argument is what stops one exemption from being a blanket one: a `theme-allow
+ * raw-hex — …` written for a color no longer silently switches off `card-inset` on the same line.
+ * An annotation that reached for an id and missed covers only the ids it got right.
+ */
+function hasThemeAllow(context, node, ruleId) {
+  if (hasFileDeclaration(context, ruleId)) return true
   const nodeLine = node.loc.start.line
-  return comments.some(
-    (comment) =>
-      comment.value.includes('theme-allow') &&
-      (comment.loc.end.line === nodeLine || comment.loc.end.line === nodeLine - 1),
+  return allComments(context).some((comment) => {
+    if (comment.loc.end.line !== nodeLine && comment.loc.end.line !== nodeLine - 1) return false
+    return parseThemeAllows(comment.value).some(
+      (allow) => allow.scope === 'line' && allowCovers(allow, ruleId),
+    )
+  })
+}
+
+/**
+ * True when the FILE carries a written declaration for `ruleId` — a `theme-allow-file` naming it,
+ * anywhere in the file.
+ *
+ * File scope has to be SPELLED, and that is the second half of the 1.20.0 fix rather than a new
+ * idea. The first half landed: `hand-rolled-plot` stopped granting a whole file permanent immunity
+ * off any comment that happened to sit on its first assembly node, and now reports every node. The
+ * second half did not, because the promotion rule was "names a rule AND gives a reason" — which is
+ * exactly what the rule's own message asks a consumer to write, and what `theme-allow-unscoped`
+ * reports them for omitting. So there was one legal annotation shape and it was whole-file:
+ * `hasFileDeclaration` still returned early for every node, forever. linewatch ended up with one
+ * whole-file declaration per chart file — the thing 1.20.0 set out to eliminate — because per-node
+ * scoping was not expressible. Now it is: `theme-allow` is the node, `theme-allow-file` is the file.
+ */
+function hasFileDeclaration(context, ruleId) {
+  return allComments(context).some((comment) =>
+    parseThemeAllows(comment.value).some(
+      (allow) => allow.scope === 'file' && allow.rules.includes(ruleId),
+    ),
   )
 }
 
+/** Test/spec files — design guidance does not apply to a fixture. Mirrors `src/cli`'s own SKIP. */
+const TEST_FILE = /\.(?:test|spec)\.[cm]?[jt]sx?$|(?:^|[\\/])__tests__[\\/]/
+
+function isTestFile(context) {
+  return TEST_FILE.test(getFilename(context))
+}
+
 /**
  * True when a `basalt-agent-allow` line comment sits on `node`'s own source line or the line above
  * it. A copy of `hasThemeAllow` with a different needle — deliberately NOT the same token, so a
@@ -146,6 +349,50 @@ const NO_RAW_FONT_SIZE_MESSAGE =
   'Raw font-size literal — route through VX.text.* (numbers) or --vx-text-* (CSS); em/relative ' +
   'ratios are allowed. (basalt/no-raw-font-size)'
 
+/** JSX attributes whose value IS a style object — the only object literals this rule reaches into. */
+const STYLE_ATTRS = new Set(['style', 'styles', 'sx'])
+/** A binding or key whose name says the object is styling — `wrapperStyle`, `styles`, `rowStyles`. */
+const STYLE_NAME = /styles?$/i
+/** How far up the tree the style-context walk goes before giving up. */
+const STYLE_CONTEXT_MAX_DEPTH = 12
+
+/**
+ * Is this object property part of a STYLE object?
+ *
+ * `fontSize` is not a reserved word. The rule used to report every object property spelled that
+ * way, which fired on an Obsidian `data.json` fixture — `{ settings: { fontSize: 16 } }` inside a
+ * string, in a package with no React and no Mantine — where the "route it through VX.text.*" advice
+ * is not merely unhelpful, it is about a different domain. Requiring a style context (a
+ * `style`/`styles`/`sx` JSX attribute, a `…Style(s)` binding or key, or a `CSSProperties`
+ * annotation) keeps every shape that is really styling and drops the ones that never reach CSS.
+ */
+function isInStyleContext(context, node) {
+  const sourceCode = context.sourceCode ?? context.getSourceCode?.()
+  let current = node.parent
+  for (let depth = 0; current !== undefined && current !== null; depth++) {
+    if (depth > STYLE_CONTEXT_MAX_DEPTH) return false
+    if (current.type === 'JSXAttribute') return STYLE_ATTRS.has(current.name?.name)
+    if (current.type === 'Property') {
+      const key = current.key
+      const name = key?.type === 'Identifier' ? key.name : key?.value
+      if (typeof name === 'string' && STYLE_NAME.test(name)) return true
+    }
+    if (current.type === 'VariableDeclarator') {
+      const id = current.id
+      if (typeof id?.name === 'string' && STYLE_NAME.test(id.name)) return true
+      const annotation = id?.typeAnnotation
+      return (
+        annotation !== undefined &&
+        annotation !== null &&
+        (sourceCode?.getText?.(annotation) ?? '').includes('CSSProperties')
+      )
+    }
+    if (current.type === 'FunctionDeclaration' || current.type === 'Program') return false
+    current = current.parent
+  }
+  return false
+}
+
 const noRawFontSize = {
   meta: {
     type: 'suggestion',
@@ -155,7 +402,7 @@ const noRawFontSize = {
     schema: [],
   },
   create(context) {
-    if (getFilename(context).includes('/src/tokens/')) return {}
+    if (getFilename(context).includes('/src/tokens/') || isTestFile(context)) return {}
 
     return {
       JSXAttribute(node) {
@@ -163,7 +410,7 @@ const noRawFontSize = {
         if (name !== 'fz' && name !== 'fontSize') return
         const value = unwrapExpressionContainer(node.value)
         if (!isNumericLiteral(value)) return
-        if (hasThemeAllow(context, node)) return
+        if (hasThemeAllow(context, node, 'no-raw-font-size')) return
         context.report({ node, message: NO_RAW_FONT_SIZE_MESSAGE })
       },
       Property(node) {
@@ -173,7 +420,8 @@ const noRawFontSize = {
           (key.type === 'Literal' && key.value === 'fontSize')
         if (!isFontSizeKey) return
         if (!isNumericLiteral(node.value)) return
-        if (hasThemeAllow(context, node)) return
+        if (!isInStyleContext(context, node)) return
+        if (hasThemeAllow(context, node, 'no-raw-font-size')) return
         context.report({ node, message: NO_RAW_FONT_SIZE_MESSAGE })
       },
     }
@@ -225,7 +473,7 @@ const rawSizeLiteral = {
         if (typeof name !== 'string' || !SIZE_ATTRS.has(name)) return
         const value = unwrapExpressionContainer(node.value)
         if (!isCssLengthString(value)) return
-        if (hasThemeAllow(context, node)) return
+        if (hasThemeAllow(context, node, 'raw-size-literal')) return
         context.report({ node, message: RAW_SIZE_LITERAL_MESSAGE })
       },
     }
@@ -276,7 +524,7 @@ const cardInset = {
           const isRadius = attrName === 'radius'
 
           if (!isOffPadding && !isOffPy && !isOffPx && !isRadius) continue
-          if (hasThemeAllow(context, attr)) continue
+          if (hasThemeAllow(context, attr, 'card-inset')) continue
           context.report({ node: attr, message: CARD_INSET_MESSAGE })
         }
       },
@@ -350,7 +598,7 @@ const chartInRawSurface = {
         if (!CARD_TAGS.has(tagName)) return
         const hasChartDescendant = node.children.some((child) => subtreeHasChart(child))
         if (!hasChartDescendant) return
-        if (hasThemeAllow(context, node)) return
+        if (hasThemeAllow(context, node, 'chart-in-raw-surface')) return
         context.report({ node, message: CHART_IN_RAW_SURFACE_MESSAGE })
       },
     }
@@ -396,7 +644,7 @@ const rawScrollContainer = {
           key.type === 'Identifier' ? key.name : key.type === 'Literal' ? key.value : undefined
         if (typeof keyName !== 'string' || !OVERFLOW_KEYS.has(keyName)) return
         if (!isStringLiteral(node.value) || !SCROLLING_VALUES.has(node.value.value)) return
-        if (hasThemeAllow(context, node)) return
+        if (hasThemeAllow(context, node, 'raw-scroll-container')) return
         context.report({ node, message: RAW_SCROLL_CONTAINER_MESSAGE })
       },
     }
@@ -760,6 +1008,61 @@ function nearestAiMajor(startDir) {
   return result
 }
 
+// One parsed manifest per path — the scope walk below re-reads the same ancestors for every file.
+const packageJsonCache = new Map()
+
+function readPackageJson(pkgPath) {
+  if (packageJsonCache.has(pkgPath)) return packageJsonCache.get(pkgPath)
+  let pkg = null
+  try {
+    pkg = JSON.parse(readFileSync(pkgPath, 'utf8'))
+  } catch {
+    pkg = null
+  }
+  packageJsonCache.set(pkgPath, pkg)
+  return pkg
+}
+
+/**
+ * Is this file inside a package that actually consumes basalt-ui?
+ *
+ * Without this the rule compared EVERY package's `ai` major against basalt's own peer major, and
+ * fired three errors in an rb workspace package (`apps/api`) that has no basalt-ui dependency, is
+ * outside `basalt.roots`, and pins `ai@6` deliberately. `doctor`'s `ai-major-parity` scopes the same
+ * concern correctly — two shipped enforcement surfaces disagreeing about one fact leaves a consumer
+ * unable to tell which is right, which is worse than either being wrong.
+ *
+ * In scope when an ancestor package.json either depends on `basalt-ui`, or declares `basalt.roots`
+ * that the file sits under. A declared `basalt.roots` that the file is NOT under is a positive
+ * statement that this code is not basalt's — the walk stops there rather than continuing up to a
+ * workspace root that happens to carry the dependency.
+ *
+ * **`roots` is consulted BEFORE the dependency, within one manifest**, and that ordering is the
+ * whole fix. `init` produces exactly the layout that breaks the other way round: a monorepo ROOT
+ * carrying `basalt-ui` as the devDependency the CLI is run from, AND `basalt.roots: ["apps/web/
+ * src"]` naming where the app actually is. 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 declared roots — took three errors and needed a permanent override. The
+ * more specific statement wins: `roots` says WHERE, the dependency only says whether.
+ */
+function isBasaltScopedFile(filename) {
+  let dir = dirname(filename)
+  for (;;) {
+    const pkg = readPackageJson(resolvePath(dir, 'package.json'))
+    if (pkg !== null) {
+      const roots = pkg.basalt?.roots
+      if (Array.isArray(roots) && roots.length > 0) {
+        return roots.some((root) => filename.startsWith(`${resolvePath(dir, root)}/`))
+      }
+      const deps = { ...pkg.dependencies, ...pkg.devDependencies, ...pkg.peerDependencies }
+      if (deps['basalt-ui'] !== undefined) return true
+    }
+    const parent = dirname(dir)
+    if (parent === dir) return false
+    dir = parent
+  }
+}
+
 function aiSdkMajorMessage(consumerMajor) {
   return (
     `This file's nearest package.json declares ai@${consumerMajor}, but basalt-ui declares the ` +
@@ -792,6 +1095,7 @@ const aiSdkMajor = {
 
         const filename = getFilename(context)
         if (filename.length === 0) return
+        if (!isBasaltScopedFile(filename)) return
         const consumerMajor = nearestAiMajor(dirname(filename))
         if (consumerMajor === null) return // no `ai` in the nearest package.json — nothing to compare
         if (consumerMajor === BASALT_AI_MAJOR) return
@@ -818,6 +1122,19 @@ const PLOT_ASSEMBLY_TAGS = new Set([
   'Crosshair',
 ])
 
+/**
+ * KNOWN LIMIT, deliberately not closed: a chart drawn out of DOM instead of the chart layer is
+ * structurally invisible here.
+ *
+ * argo has two — a 3×3 Mantine `SimpleGrid` matrix and absolutely-positioned `Box` bullet bars —
+ * that import only `ChartCard` and `VX`, render no basalt primitive, and therefore cannot trip any
+ * tag-name check. The candidate widenings all fail on false positives in a rule that SHIPS to
+ * consumers: adding `ChartTooltipFloat`/`useChartSize` to this set flags `Donut` and `Heatmap`,
+ * which compose them legitimately; "renders `ChartCard` and a raw `<svg>`" flags an inline icon in
+ * a card header. Detecting "this Box grid is a chart" needs intent, not syntax. Naming the gap here
+ * is the honest answer — a noisy rule gets switched off, and then it guards nothing at all.
+ */
+
 /**
  * Composing this means the file is USING the chart system rather than re-implementing it.
  * `ChartFrame` deliberately does NOT count: composing the frame directly and then hand-assembling
@@ -847,7 +1164,9 @@ const HAND_ROLLED_PLOT_MESSAGE =
   'owns the measured margins, both y scales, the axes, grid, shared cursor, crosshair and ' +
   'tooltip. Hand-assembling them is how two charts stop matching. Compose CartesianChart and ' +
   'render only marks. A genuinely non-single-plot shape (multi-pane, radial, matrix) composes ' +
-  'ChartFrame instead — add a theme-allow comment to declare that. (basalt/hand-rolled-plot)'
+  'ChartFrame instead — declare that with `theme-allow-file hand-rolled-plot — <why>` anywhere in ' +
+  'the file. To waive just THIS node and stay policed on the rest, write `theme-allow ' +
+  'hand-rolled-plot — <why>` on its own line above it. (basalt/hand-rolled-plot)'
 
 const handRolledPlot = {
   meta: {
@@ -859,6 +1178,7 @@ const handRolledPlot = {
     schema: [],
   },
   create(context) {
+    if (isTestFile(context)) return {}
     // File-scoped, not node-scoped: the verdict depends on whether a plot OWNER appears anywhere
     // in the file, which is only known once the whole file has been walked.
     const assemblyNodes = []
@@ -891,16 +1211,26 @@ const handRolledPlot = {
       },
       'Program:exit'() {
         if (ownsPlot || definesOwner) return
-        // Only the FIRST site is reported, and the whole check is FILE-scoped rather than
-        // component-scoped. Both are deliberate. File scope is forced by the shape of the correct
-        // pattern: `<CartesianChart>{() => <AxisLeftNumeric …/>}</CartesianChart>` puts the axis
-        // inside a render-prop arrow, a different function from the component that owns the chart
-        // — component scope would flag the canonical usage. One report because declaring an
-        // exception is a decision about the FILE ("this shape isn't a single cartesian plot"), so
-        // one `theme-allow` settles it instead of one comment per axis and overlay.
-        const [first] = assemblyNodes.filter((node) => chartImports.has(node.name?.name))
-        if (first === undefined || hasThemeAllow(context, first)) return
-        context.report({ node: first, message: HAND_ROLLED_PLOT_MESSAGE })
+        // The CHECK stays file-scoped — forced by the shape of the correct pattern:
+        // `<CartesianChart>{() => <AxisLeftNumeric …/>}</CartesianChart>` puts the axis inside a
+        // render-prop arrow, a different function from the component that owns the chart, so
+        // component scope would flag the canonical usage.
+        //
+        // The SUPPRESSION no longer is. Reporting only the first node and testing the waiver there
+        // meant one comment — any comment, about anything — bought a whole file permanent immunity:
+        // every axis, overlay and crosshair added to that file afterwards went unreported forever
+        // (linewatch: three files, one 604 lines). Now every assembly node is reported and waived on
+        // its own, EXCEPT when the file carries a written declaration — a `theme-allow` that names
+        // `basalt/hand-rolled-plot` and gives a reason. That is the shape a genuinely non-single-plot
+        // kind already uses (`DualPanel`), and it is the difference between a line waiver and a
+        // decision about the file.
+        const nodes = assemblyNodes.filter((node) => chartImports.has(node.name?.name))
+        if (nodes.length === 0) return
+        if (hasFileDeclaration(context, 'hand-rolled-plot')) return
+        for (const node of nodes) {
+          if (hasThemeAllow(context, node, 'hand-rolled-plot')) continue
+          context.report({ node, message: HAND_ROLLED_PLOT_MESSAGE })
+        }
       },
     }
   },
@@ -914,6 +1244,40 @@ const CHART_LEGEND_LITERAL_MESSAGE =
   'is a second source of truth that silently goes stale: it keeps naming a series after the plot ' +
   'stops drawing it. (basalt/chart-legend-literal)'
 
+/**
+ * Does this expression derive from the chart's own `series`?
+ *
+ * The contract is derivation from `series` — not derivation from *an* array. `items={refLines.map(
+ * (r) => ({ key, label, color, shape }))}` and `items={PACE_ZONES.map(…)}` are hand-authored
+ * legends by any reading: every field is written at the call site, and the list can name a band the
+ * plot no longer draws exactly like a `[...]` literal can. Walks the base of a member/call chain so
+ * `visibleSeries.filter(…).map(…)` and `deriveLegend(series)` both read as derived.
+ */
+function derivesFromSeries(node, depth = 0) {
+  if (node === null || node === undefined || depth > 8) return false
+  if (node.type === 'Identifier') return /series$/i.test(node.name ?? '')
+  if (node.type === 'MemberExpression') {
+    return derivesFromSeries(node.object, depth + 1) || derivesFromSeries(node.property, depth + 1)
+  }
+  if (node.type === 'CallExpression') {
+    if (node.callee?.type === 'Identifier' && node.callee.name === 'deriveLegend') return true
+    return (
+      derivesFromSeries(node.callee, depth + 1) ||
+      (node.arguments ?? []).some((arg) => derivesFromSeries(arg, depth + 1))
+    )
+  }
+  return false
+}
+
+/** `X.map(…)` — the derivation-shaped form that is only derivation when `X` is the series. */
+function isMapCall(node) {
+  return (
+    node?.type === 'CallExpression' &&
+    node.callee?.type === 'MemberExpression' &&
+    node.callee.property?.name === 'map'
+  )
+}
+
 const chartLegendLiteral = {
   meta: {
     type: 'suggestion',
@@ -921,6 +1285,7 @@ const chartLegendLiteral = {
     schema: [],
   },
   create(context) {
+    if (isTestFile(context)) return {}
     const chartImports = new Set()
 
     return {
@@ -933,6 +1298,14 @@ const chartLegendLiteral = {
           (attr) => attr.type === 'JSXAttribute' && attr.name?.name === 'items',
         )
         const expression = items?.value?.expression
+        // The `.map()` half — a list built by mapping over something that is NOT the series. See
+        // `derivesFromSeries`. Reported under the same id as the array-literal half because it is
+        // the same defect (a second source of truth for the legend), just written as a call.
+        if (isMapCall(expression) && !derivesFromSeries(expression.callee?.object)) {
+          if (hasThemeAllow(context, node, 'chart-legend-literal')) return
+          context.report({ node, message: CHART_LEGEND_LITERAL_MESSAGE })
+          return
+        }
         if (expression?.type !== 'ArrayExpression') return
         // Only a list that is ENTIRELY object literals is a hand-authored legend. An array that
         // spreads or calls something (`[...deriveLegend(series), note]`) is derived-and-extended,
@@ -946,13 +1319,241 @@ const chartLegendLiteral = {
           expression.elements.length > 0 &&
           expression.elements.every((el) => el?.type === 'ObjectExpression')
         if (!allObjectLiterals) return
-        if (hasThemeAllow(context, node)) return
+        if (hasThemeAllow(context, node, 'chart-legend-literal')) return
         context.report({ node, message: CHART_LEGEND_LITERAL_MESSAGE })
       },
     }
   },
 }
 
+// ── Rule 14 — shadow-basalt-export ───────────────────────────────────────────────────────────────
+
+/** The package root — one directory above `configs/`, repo-locally AND inside node_modules. */
+const PACKAGE_ROOT = resolvePath(PLUGIN_DIR, '..')
+
+/**
+ * A component-shaped name: starts uppercase and carries a lowercase letter, which excludes the
+ * SCREAMING_CASE constants and the two-letter token namespaces in the same barrel.
+ */
+const COMPONENT_NAME = /^[A-Z][A-Za-z0-9]*[a-z][A-Za-z0-9]*$/
+
+/**
+ * The barrels a consumer can import a component FROM. The root one is not the whole surface: a
+ * chart-layer fork (`ChartFrame`, `CartesianChart`, `ChartCard`, …) collided with nothing, because
+ * `./charts` is deliberately NOT re-exported from `.` — so a consumer whose forks all live in the
+ * chart layer, which is the layer forks actually live in, could never trip the rule. It was
+ * correctly silent there for the wrong reason.
+ *
+ * Enumerated rather than globbed: `dist/**\/index.d.ts` would also sweep internal directory
+ * barrels that are not published subpaths, and a name that is not importable is not a fork of
+ * anything. Keep this in step with the `exports` map in package.json.
+ */
+const BASALT_BARRELS = [
+  ['index.d.ts'],
+  ['charts', 'index.d.ts'],
+  ['content', 'index.d.ts'],
+  ['data', 'index.d.ts'],
+  ['forms', 'index.d.ts'],
+  ['agent', 'index.d.ts'],
+  ['commands', 'index.d.ts'],
+  ['notifications', 'index.d.ts'],
+  ['connectivity', 'index.d.ts'],
+]
+
+/**
+ * Every component-shaped VALUE export of basalt's published barrels, read once at module load from
+ * the real `.d.ts` files — not a hand-maintained list that would go stale the first time an export
+ * was renamed. `type` specifiers are skipped: a local `StatCardProps` is a normal thing to write, a
+ * local `StatCard` is not.
+ *
+ * Empty (rule silent) when `dist` is unreadable, exactly like `BASALT_AI_MAJOR` — a lint run must
+ * not depend on a build having happened.
+ */
+const BASALT_EXPORTS = (() => {
+  const names = new Set()
+  for (const segments of BASALT_BARRELS) {
+    let text
+    try {
+      text = readFileSync(resolvePath(PACKAGE_ROOT, 'dist', ...segments), 'utf8')
+    } catch {
+      continue
+    }
+    for (const block of text.matchAll(/export\s*\{([^}]*)\}(?:\s*from\s*['"]([^'"]*)['"])?/g)) {
+      // A pass-through re-export of a THIRD-PARTY name is not a basalt composite. `./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 this rule started reading the charts barrel. Relative sources only.
+      const source = block[2]
+      if (source !== undefined && !source.startsWith('.')) continue
+      for (const raw of block[1].split(',')) {
+        const part = raw.trim()
+        if (part === '' || part.startsWith('type ')) continue
+        const name = (part.split(/\s+as\s+/).pop() ?? '').trim()
+        if (COMPONENT_NAME.test(name)) names.add(name)
+      }
+    }
+  }
+  return names
+})()
+
+function shadowBasaltExportMessage(name) {
+  return (
+    `Local component '${name}' collides with the basalt-ui export of the same name — import it ` +
+    "from 'basalt-ui' instead of re-rolling it. This is the one signal a forked composite emits: " +
+    'the palette guard can never see it, because a fork written by a token-fluent author uses ' +
+    'exactly the right tokens and passes every other check. A NAME collision is the whole of the ' +
+    'signal, so this is a tripwire, not coverage: rename the fork and the rule goes quiet ' +
+    "(linewatch's forks are `Cell` and `Box`, rb's is `Stat`). Silence here is not evidence that " +
+    'nothing is forked. (basalt/shadow-basalt-export)'
+  )
+}
+
+/**
+ * Flags a local declaration whose name collides with a live basalt export.
+ *
+ * The cheapest possible detector for the whole absorption class: argo shipped its own `EmptyState`
+ * (a full duplicate of the shipped one) and rb a local `StatCard`, and both passed `check-theme`,
+ * `oxlint` and `doctor` clean — off-palette code fails, a forked component that uses the correct
+ * tokens does not. `warn`, not `error`: a name collision is evidence, not proof, and a consumer
+ * with a genuinely different `Composer` should be told once, not blocked.
+ */
+const shadowBasaltExport = {
+  meta: {
+    type: 'suggestion',
+    docs: { description: 'Warn on a local component whose name collides with a basalt-ui export.' },
+    schema: [],
+  },
+  create(context) {
+    const filename = getFilename(context)
+    // basalt's own source DEFINES these names; a consumer's does not.
+    if (BASALT_EXPORTS.size === 0 || filename.startsWith(`${PACKAGE_ROOT}/`)) return {}
+    if (isTestFile(context)) return {}
+
+    const report = (node, name) => {
+      if (typeof name !== 'string' || !BASALT_EXPORTS.has(name)) return
+      if (hasThemeAllow(context, node, 'shadow-basalt-export')) return
+      context.report({ node, message: shadowBasaltExportMessage(name) })
+    }
+
+    return {
+      FunctionDeclaration(node) {
+        report(node, node.id?.name)
+      },
+      VariableDeclarator(node) {
+        report(node, node.id?.name)
+      },
+      ClassDeclaration(node) {
+        report(node, node.id?.name)
+      },
+    }
+  },
+}
+
+// ── Rule 15 — hand-rolled-shell ──────────────────────────────────────────────────────────────────
+
+/** Mantine parts that only ever appear when someone is assembling an application shell by hand. */
+// `NavLink` is deliberately NOT here: Mantine's NavLink is a legitimate standalone list row, and a
+// rule that fires on one inside a settings page would be switched off within a day. `Burger` and the
+// `AppShell.*` parts have no use outside assembling a shell.
+const SHELL_ASSEMBLY_TAGS = new Set(['Burger'])
+const SHELL_ASSEMBLY_MEMBER_OBJECT = 'AppShell'
+
+const HAND_ROLLED_SHELL_MESSAGE =
+  'Application shell assembled by hand — AppShell parts / Burger / NavLink in a file that does not ' +
+  'render BasaltShell. The shell is the framework: BasaltShell owns the sidebar, the mobile tab ' +
+  'bar and its More sheet, breadcrumbs, the page header and the collapse state, all driven by ONE ' +
+  'typed nav definition (defineNav + useNav). A hand-rolled AppShell + burger drawer is the exact ' +
+  'layer the 1.19 nav contract replaces, and no palette guard can see it — it uses the right ' +
+  'tokens. Declare a deliberate exception with `theme-allow-file hand-rolled-shell — <why>`. ' +
+  '(basalt/hand-rolled-shell)'
+
+/**
+ * The `hand-rolled-plot` shape, one layer up. rb shipped 266 lines of `AppShell` + `NavLink` +
+ * `Burger` + `useDisclosure` mobile drawer and every gate passed it green.
+ *
+ * File-scoped and reported once: which shell a file uses is one decision, so one comment settles
+ * it. The module that DEFINES `BasaltShell` is exempt by declaration, not by path — a rule saying
+ * "compose X" cannot fire inside X.
+ */
+const handRolledShell = {
+  meta: {
+    type: 'suggestion',
+    docs: { description: 'Disallow assembling an app shell by hand instead of using BasaltShell.' },
+    schema: [],
+  },
+  create(context) {
+    if (isTestFile(context)) return {}
+
+    const assemblyNodes = []
+    let mantineImported = false
+    let ownsShell = false
+
+    const notesOwnerDefinition = (name) => {
+      if (name === 'BasaltShell') ownsShell = true
+    }
+
+    return {
+      ImportDeclaration(node) {
+        if ((node.source?.value ?? '').startsWith('@mantine/')) mantineImported = true
+      },
+      FunctionDeclaration(node) {
+        notesOwnerDefinition(node.id?.name)
+      },
+      VariableDeclarator(node) {
+        notesOwnerDefinition(node.id?.name)
+      },
+      JSXOpeningElement(node) {
+        const name = node.name
+        if (name?.type === 'JSXMemberExpression') {
+          if (name.object?.name === SHELL_ASSEMBLY_MEMBER_OBJECT) assemblyNodes.push(node)
+          return
+        }
+        if (name?.name === 'BasaltShell') ownsShell = true
+        else if (SHELL_ASSEMBLY_TAGS.has(name?.name)) assemblyNodes.push(node)
+      },
+      'Program:exit'() {
+        if (ownsShell || !mantineImported) return
+        const [first] = assemblyNodes
+        if (first === undefined) return
+        if (hasThemeAllow(context, first, 'hand-rolled-shell')) return
+        if (hasFileDeclaration(context, 'hand-rolled-shell')) return
+        context.report({ node: first, message: HAND_ROLLED_SHELL_MESSAGE })
+      },
+    }
+  },
+}
+
+// ── Grace ledger ────────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Plugin rules still inside their grace minor — `warn` in the shipped consumer preset, `error`
+ * repo-locally, with the promotion note as the value. This is the plugin's counterpart to
+ * `src/guard`'s `GRACE_PERIOD_KINDS`, and it exists because its ABSENCE is what let three rules sit
+ * at `warn` for up to twelve minors with nothing tracking them: `configs/oxlint.json` is generated
+ * and its top-level keys are fixed by oxlint's own parser, so the ledger cannot live there.
+ *
+ * `oxlint-plugin.test.ts` asserts the two agree in both directions — a rule listed here must be
+ * `warn` in the shipped preset, and one absent from here must be `error`. Deleting an entry IS the
+ * promotion, and the test makes the config change mandatory in the same commit.
+ */
+export const PLUGIN_RULE_GRACE = {
+  'hand-rolled-plot':
+    'widened AGAIN in the round-5 guard minor (file scope must now be spelled `theme-allow-file`, ' +
+    'so the named-with-a-reason shape every consumer wrote at 1.20.0 is a NODE waiver and the ' +
+    'remaining assembly nodes report) — grace restarts with the widening, per the "a rule the ' +
+    'current minor widens does not promote in that minor" doctrine. Promote one minor after ' +
+    'consumers have moved their file declarations to `theme-allow-file`.',
+  'chart-legend-literal':
+    'widened in the round-4 guard minor (a `.map()` over a non-series array now counts) — promote ' +
+    'to error one minor later, for the same reason as hand-rolled-plot above.',
+  'shadow-basalt-export':
+    'new in the round-4 guard minor, widened in round-5 (reads every published barrel, not just ' +
+    'the root one, so a chart-layer fork is visible) — promote to error one minor later, if ever. ' +
+    'A name collision is strong evidence and not proof, and renaming defeats it outright, so this ' +
+    'may be a permanent warn.',
+  'hand-rolled-shell': 'new in the round-4 guard minor — promote to error one minor later.',
+}
+
 // ── Plugin export ───────────────────────────────────────────────────────────────────────────────
 
 export default {
@@ -964,6 +1565,8 @@ export default {
     'chart-in-raw-surface': chartInRawSurface,
     'hand-rolled-plot': handRolledPlot,
     'chart-legend-literal': chartLegendLiteral,
+    'shadow-basalt-export': shadowBasaltExport,
+    'hand-rolled-shell': handRolledShell,
     'raw-scroll-container': rawScrollContainer,
     'visx-boundary': visxBoundary,
     'visx-tooltip': visxTooltip,