basalt-ui 1.27.0 → 1.29.0

package/configs/oxlint-plugin.test.ts

@@ -14,9 +14,11 @@ 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, {
   CTL_THEME_TAGS,
+  DEPRECATED_EXPORTS,
   KNOWN_RULE_IDS,
   PLUGIN_RULE_ADVISORY,
   PLUGIN_RULE_GRACE,
+  RETIRED_RULE_IDS,
 } from './oxlint-plugin.js'
 import { CTL_THEME } from '../src/theme/ctl-theme'
 import { GUARD_RULES, PLUGIN_RULE_IDS } from '../src/guard/index.ts'
@@ -35,7 +37,13 @@ beforeEach(() => {
       plugins: [],
       jsPlugins: [PLUGIN_PATH],
       rules: {
+        'basalt/provider-above-router': 'error',
+        'basalt/query-dual-import': 'error',
+        'basalt/query-fn-unwrap': 'error',
+        'basalt/deprecated-export': 'error',
+        'basalt/forms-field-key': 'error',
         'basalt/no-raw-font-size': 'error',
+        'basalt/raw-size-literal': 'error',
         'basalt/card-inset': 'error',
         'basalt/chart-in-raw-surface': 'error',
         'basalt/hand-rolled-plot': 'error',
@@ -45,6 +53,7 @@ beforeEach(() => {
         'basalt/raw-scroll-container': 'error',
         'basalt/hand-rolled-filter': 'error',
         'basalt/control-outside-home': 'error',
+        'basalt/bound-control-outside-home': 'error',
         'basalt/control-size-literal': 'error',
         'basalt/page-bar-budget': 'error',
         'basalt/in-body-page-title': 'error',
@@ -111,6 +120,76 @@ describe('basalt/no-raw-font-size', () => {
     expect(code).toBe(0)
     expect(rules).not.toContain('no-raw-font-size')
   })
+
+  // F25: symmetric with raw-size-literal's own test-file skip below — the doctrine is about
+  // shipped UI, not fixtures.
+  it('does NOT flag a numeric fz inside a *.test.tsx file', () => {
+    const { code, rules } = run(`export const C = () => <Text fz={10}>a</Text>\n`, 'lib.test.tsx')
+    expect(code).toBe(0)
+    expect(rules).not.toContain('no-raw-font-size')
+  })
+})
+
+// ── raw-size-literal ─────────────────────────────────────────────────────────
+
+describe('basalt/raw-size-literal', () => {
+  it('flags a CSS-length string on size', () => {
+    const { code, rules } = run(`export const C = () => <ThemeIcon size="2rem" />\n`)
+    expect(code).toBe(1)
+    expect(rules).toContain('raw-size-literal')
+  })
+
+  it('flags a CSS-length string on fz', () => {
+    const { code, rules } = run(`export const C = () => <Text fz="0.8rem">a</Text>\n`)
+    expect(code).toBe(1)
+    expect(rules).toContain('raw-size-literal')
+  })
+
+  it('does NOT flag a scale token on size', () => {
+    const { code, rules } = run(`export const C = () => <ThemeIcon size="md" />\n`)
+    expect(code).toBe(0)
+    expect(rules).not.toContain('raw-size-literal')
+  })
+
+  it('does NOT flag a numeric size (the documented icon-dimension idiom)', () => {
+    const { code, rules } = run(`export const C = () => <ThemeIcon size={32} />\n`)
+    expect(code).toBe(0)
+    expect(rules).not.toContain('raw-size-literal')
+  })
+
+  it('does NOT flag with a same-line theme-allow comment', () => {
+    const { code, rules } = run(
+      `export const C = () => <Text fz="0.8rem" /* theme-allow: legacy */>a</Text>\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('raw-size-literal')
+  })
+
+  // F25: was the asymmetric half — no-raw-font-size already skipped test files, this rule did not.
+  it('does NOT flag a CSS-length string inside a *.test.tsx file', () => {
+    const { code, rules } = run(
+      `export const C = () => <Text fz="0.8rem">a</Text>\n`,
+      'lib.test.tsx',
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('raw-size-literal')
+  })
+
+  // A3: the /src/tokens/ exemption used to be a bare path-substring check, then a check gated on
+  // `isBasaltScopedFile` — but that predicate tests "does the nearest package.json depend on
+  // basalt-ui", not "is this file basalt's own", so a CONSUMER package that merely depends on
+  // basalt-ui could still put raw literals under its own `src/tokens/` and silence the rule. The
+  // exemption is deleted outright rather than re-gated on package identity: both rules only ever
+  // visit JSX, and basalt's real `src/tokens/**` is pure `.ts` data with none, so no gate was ever
+  // load-bearing there. A `src/tokens/` path — basalt's own or a consumer's — now always fires.
+  it('DOES flag a CSS-length string inside a src/tokens/ file (no path exemption)', () => {
+    const { code, rules } = run(
+      `export const C = () => <ThemeIcon size="2rem" />\n`,
+      'src/tokens/palette.tsx',
+    )
+    expect(code).toBe(1)
+    expect(rules).toContain('raw-size-literal')
+  })
 })
 
 // ── card-inset ───────────────────────────────────────────────────────────────
@@ -1296,6 +1375,30 @@ describe('PLUGIN_RULE_GRACE', () => {
   it('passes the C16 gate against the real ledger and package version', () => {
     expect(() => assertGraceLedger(Object.fromEntries(graceEntries), pkgVersion)).not.toThrow()
   })
+
+  // F27: a grace entry is written for a rule that lands in the NEXT release, so its `since` can sit
+  // one minor ahead of `package.json`'s current version (`bound-control-outside-home` at 1.28.0
+  // while the published version still reads 1.27.0, exactly like `control-outside-home` before it).
+  // What this catches is a `since` that is malformed or planted further out than that — a value
+  // static analysis has no way to verify is "the version this actually ships in", so the bound this
+  // test enforces is the one thing that IS checkable: well-formed semver, no more than one minor
+  // past what is currently published.
+  it("every grace entry's since is valid semver, at most one minor past the published version", () => {
+    const SEMVER = /^\d+\.\d+\.\d+$/
+    const [major, minor] = pkgVersion.split('.').map(Number)
+    const nextMinorCeiling = `${major}.${minor + 1}.0`
+    for (const [id, entry] of graceEntries) {
+      if (!SEMVER.test(entry.since)) {
+        throw new Error(`${id}: \`since\` (${entry.since}) is not valid semver.`)
+      }
+      if (compareSemver(entry.since, nextMinorCeiling) > 0) {
+        throw new Error(
+          `${id}: \`since\` (${entry.since}) is more than one minor past the published version ` +
+            `${pkgVersion}.`,
+        )
+      }
+    }
+  })
 })
 
 // ── chart-legend-literal: the .map() half ────────────────────────────────────
@@ -1408,9 +1511,15 @@ describe('KNOWN_RULE_IDS', () => {
   // Deduped, because ONE id is deliberately in both registries: `in-body-page-title` is a plugin
   // rule AND a guard kind (law C8 has an AST half and a text half), so one `theme-allow
   // in-body-page-title — <why>` waives both lanes rather than needing a different word per lane.
-  it('contains nothing else — it is exactly the union of the two registries', () => {
+  // `RETIRED_RULE_IDS` adds a third component: an id that used to be a guard kind or a plugin
+  // rule, is in neither live registry, and must still parse as a (dead) waiver rather than a typo.
+  it('contains nothing else — it is exactly the union of the two registries plus retired ids', () => {
     const expected = [
-      ...new Set([...Object.keys(basaltPlugin.rules), ...Object.keys(GUARD_RULES)]),
+      ...new Set([
+        ...Object.keys(basaltPlugin.rules),
+        ...Object.keys(GUARD_RULES),
+        ...RETIRED_RULE_IDS,
+      ]),
     ].toSorted()
     expect([...KNOWN_RULE_IDS].toSorted()).toEqual(expected)
   })
@@ -1428,6 +1537,15 @@ describe('KNOWN_RULE_IDS', () => {
       expect([id, PLUGIN_RULE_IDS.has(id) || Object.hasOwn(GUARD_RULES, id)]).toEqual([id, true])
     }
   })
+
+  // A retired id has to be classifiable too, on both sides — `RETIRED_RULE_IDS` is this plugin's
+  // copy, `PLUGIN_RULE_IDS` (src/guard) is the guard's. Drift between them would mean
+  // `--audit-allows` classifies a retired id one way from `check-theme` and another from oxlint.
+  it('every retired id is in the guard’s PLUGIN_RULE_IDS too', () => {
+    for (const id of RETIRED_RULE_IDS) {
+      expect([id, PLUGIN_RULE_IDS.has(id)]).toEqual([id, true])
+    }
+  })
 })
 
 // ── theme-allow fails closed on a typo ─────────────────────────────────────────────────────────
@@ -1681,6 +1799,28 @@ describe('basalt/control-outside-home', () => {
     },
   )
 
+  // FormRow/FormGroup (`basalt-ui/forms`) are law C1's third home written for a `<form>` rather
+  // than a settings page — the same non-home treatment SettingsRow gets, via the same
+  // CONTROL_HOST_TAGS ancestry walk.
+  it.each(['FormRow', 'FormGroup'])(
+    'does NOT flag a raw Select nested inside a %s imported from basalt-ui/forms',
+    (host) => {
+      const { code, rules } = run(
+        `import { ${host} } from 'basalt-ui/forms'\n${MANTINE_IMPORT}` +
+          `export const C = () => <${host} label="L"><Select data={[]} /></${host}>\n`,
+      )
+      expect(code).toBe(0)
+      expect(rules).not.toContain('control-outside-home')
+    },
+  )
+
+  it('still flags a bare Select in a page body with no FormRow/FormGroup around it', () => {
+    const { rules } = run(
+      `${MANTINE_IMPORT}export const C = () => <div><Select data={[]} /></div>\n`,
+    )
+    expect(rules).toContain('control-outside-home')
+  })
+
   it('does NOT flag one under a member-expression non-home (Menu.Dropdown)', () => {
     const { rules } = run(
       `${MANTINE_IMPORT}export const C = () => <Menu.Dropdown><Select data={[]} /></Menu.Dropdown>\n`,
@@ -1708,6 +1848,58 @@ describe('basalt/control-outside-home', () => {
     expect(rules).not.toContain('control-outside-home')
   })
 
+  /**
+   * The exemption's SECOND half. `CONTROL_OWNER_NAMES` carries generic names (`PanelRow`,
+   * `EnumFilter`, `SliderControl`), so a bare-name match let one local helper switch this rule —
+   * and `bound-control-outside-home` and `responsive-twin` with it — off for a whole consumer file.
+   * A file that imports `basalt-ui*` is CONSUMING basalt; basalt's own control sources import each
+   * other relatively and never name the package.
+   */
+  it('DOES flag a file that declares its own PanelRow but imports basalt-ui', () => {
+    const { rules } = run(
+      `import { Section } from 'basalt-ui'\n${MANTINE_IMPORT}` +
+        `function PanelRow({ children }) {\n  return <div>{children}</div>\n}\n` +
+        `export const C = () => (\n  <Section title="x">\n    <Select value={v} onChange={set} data={[]} />\n  </Section>\n)\n`,
+    )
+    expect(rules).toContain('control-outside-home')
+  })
+
+  /**
+   * The basalt SUBTREE homes, which this rule did not know: `bound-control-outside-home` has read
+   * `FilterSet` / `PageAside` / `PanelRow` as homes since it shipped, so a `<Select>` inside a
+   * `<PageAside><PanelRow>` reported while the bound control beside it did not — two rules
+   * answering one question two ways.
+   */
+  it('does NOT flag one inside a PageAside > PanelRow subtree', () => {
+    const { code, rules } = run(
+      `import { PageAside } from 'basalt-ui'\nimport { PanelRow } from 'basalt-ui/controls'\n${MANTINE_IMPORT}` +
+        `export const C = () => (\n  <PageAside title="Filters">\n    <PanelRow label="Scale">\n      <Select data={[]} />\n    </PanelRow>\n  </PageAside>\n)\n`,
+      'src/scale-page.tsx',
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('control-outside-home')
+  })
+
+  it('does NOT flag one inside a FilterSet subtree', () => {
+    const { rules } = run(
+      `import { FilterSet } from 'basalt-ui/controls'\n${MANTINE_IMPORT}` +
+        `export const C = () => (\n  <FilterSet>\n    <Select data={[]} />\n  </FilterSet>\n)\n`,
+      'src/scale-page.tsx',
+    )
+    expect(rules).not.toContain('control-outside-home')
+  })
+
+  // Provenance, the test `SLOT_OWNER_TAGS` already applies: a consumer's own `PanelRow` is a layout
+  // helper, not a basalt home, so it exempts nothing.
+  it("still flags one inside a consumer's OWN PanelRow", () => {
+    const { rules } = run(
+      `import { PanelRow } from './panel-row'\n${MANTINE_IMPORT}` +
+        `export const C = () => (\n  <PanelRow label="Scale">\n    <Select data={[]} />\n  </PanelRow>\n)\n`,
+      'src/scale-page.tsx',
+    )
+    expect(rules).toContain('control-outside-home')
+  })
+
   it('flags an ALIASED Mantine import with no home', () => {
     const { code, rules } = run(
       `import { Select as MantineSelect } from '@mantine/core'\n` +
@@ -1770,6 +1962,252 @@ describe('basalt/control-outside-home', () => {
       const { rules } = run(SOURCE, 'src/modal.tsx')
       expect(rules).toContain('control-outside-home')
     })
+
+    // The SECOND dialect: a repo mandating `PascalCase.tsx` for component files (basalt's own root
+    // CLAUDE.md included) can never write `foo-panel.tsx`, so the kebab form alone exempted nothing
+    // there — which is how the CBBI panel collected four warns for a `<PageAside>` in its parent.
+    it.each(['src/EditSessionModal.tsx', 'src/FiltersDrawer.tsx', 'src/CbbiPanel.tsx'])(
+      'does NOT flag %s — the PascalCase dialect of the same convention',
+      (filename) => {
+        const { code, rules } = run(SOURCE, filename)
+        expect(code).toBe(0)
+        expect(rules).not.toContain('control-outside-home')
+      },
+    )
+
+    /**
+     * The trade, stated as a test rather than only as prose: a `FooPanel.tsx` that renders NO page
+     * bar is exempt WHOLE-FILE, so a control that genuinely belongs in a bar goes unreported there.
+     * Measured before keeping it — across argo, linewatch, image-share, rb and image-gen the
+     * PascalCase dialect matches 9 files, all in image-gen, and NONE of them renders a `<PageBar>`
+     * or sits under a `routes/` directory. Nine overlay bodies, zero pages, so the dialect stays
+     * whole-file rather than growing a "does it render a page bar" predicate (CONTROLS-SPEC §6).
+     */
+    it('exempts a FooPanel.tsx that renders no page bar — the measured trade', () => {
+      const { code, rules } = run(SOURCE, 'src/components/refine/CropPanel.tsx')
+      expect(code).toBe(0)
+      expect(rules).not.toContain('control-outside-home')
+    })
+
+    it('needs the leading subject in the PascalCase dialect too', () => {
+      const { rules } = run(SOURCE, 'src/Panel.tsx')
+      expect(rules).toContain('control-outside-home')
+    })
+
+    it('is CASE-sensitive — foopanel.tsx is neither dialect', () => {
+      const { rules } = run(SOURCE, 'src/foopanel.tsx')
+      expect(rules).toContain('control-outside-home')
+    })
+  })
+})
+
+/**
+ * Ledger G5 (`docs/ASIDE-SPEC.md` §2) — the basalt half of law C1. Mirrors the
+ * `control-outside-home` block above case for case, because the two rules answer the same question
+ * about a different tag set: that one matches raw Mantine, this one matches a bound basalt control.
+ */
+describe('basalt/bound-control-outside-home', () => {
+  const CONTROLS_IMPORT = `import { FilterSet, PanelRow, SelectFilter, SliderControl } from 'basalt-ui/controls'\n`
+  const ASIDE_IMPORT = `import { PageAside, PageBar, Section } from 'basalt-ui'\n`
+
+  it("flags a bound control in a Section's BODY — the stray pill G5 named", () => {
+    const { code, rules } = run(
+      `${ASIDE_IMPORT}${CONTROLS_IMPORT}export const C = () => (\n  <Section title="Composition">\n    <SelectFilter field={f} />\n  </Section>\n)\n`,
+    )
+    expect(code).toBe(1)
+    expect(rules).toContain('bound-control-outside-home')
+  })
+
+  it('flags one in a bare page Stack', () => {
+    const { rules } = run(
+      `import { Stack } from '@mantine/core'\n${CONTROLS_IMPORT}` +
+        `export const C = () => (\n  <Stack>\n    <SelectFilter field={f} />\n  </Stack>\n)\n`,
+    )
+    expect(rules).toContain('bound-control-outside-home')
+  })
+
+  it('does NOT flag one in a PageBar filters slot', () => {
+    const { code, rules } = run(
+      `${ASIDE_IMPORT}${CONTROLS_IMPORT}export const C = () => <PageBar filters={<SelectFilter field={f} />} />\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('bound-control-outside-home')
+  })
+
+  it('does NOT flag one inside a FilterSet subtree', () => {
+    const { code, rules } = run(
+      `${CONTROLS_IMPORT}export const C = () => (\n  <FilterSet>\n    <SelectFilter field={f} />\n  </FilterSet>\n)\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('bound-control-outside-home')
+  })
+
+  // The aside is a shell REGION whose body IS a home — it scopes its children to the `panel`
+  // surface, where the same control renders as a row rather than a pill (docs/ASIDE-SPEC.md §3).
+  it('does NOT flag one inside a PageAside subtree, Section and all', () => {
+    const { code, rules } = run(
+      `${ASIDE_IMPORT}${CONTROLS_IMPORT}export const C = () => (\n  <PageAside title="Filters">\n    <Section title="Origin">\n      <SelectFilter field={f} />\n    </Section>\n  </PageAside>\n)\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('bound-control-outside-home')
+  })
+
+  it("does NOT flag one as a PanelRow's `end` — the attribute hangs off PanelRow itself", () => {
+    const { code, rules } = run(
+      `${CONTROLS_IMPORT}export const C = () => <PanelRow label="Weight" end={<SelectFilter field={f} />} />\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('bound-control-outside-home')
+  })
+
+  it("does NOT flag one in a PanelRow's children — the row IS the home", () => {
+    const { rules } = run(
+      `${CONTROLS_IMPORT}export const C = () => (\n  <PanelRow label="Origin">\n    <SelectFilter field={f} />\n  </PanelRow>\n)\n`,
+    )
+    expect(rules).not.toContain('bound-control-outside-home')
+  })
+
+  it('does NOT flag one inside an overlay host (Modal)', () => {
+    const { rules } = run(
+      `import { Modal } from '@mantine/core'\n${CONTROLS_IMPORT}` +
+        `export const C = () => (\n  <Modal opened>\n    <SelectFilter field={f} />\n  </Modal>\n)\n`,
+    )
+    expect(rules).not.toContain('bound-control-outside-home')
+  })
+
+  // FormRow/FormGroup are the same declared non-home as SettingsRow — shared CONTROL_HOST_TAGS walk.
+  it.each(['FormRow', 'FormGroup'])('does NOT flag one inside a %s', (host) => {
+    const { code, rules } = run(
+      `import { ${host} } from 'basalt-ui/forms'\n${CONTROLS_IMPORT}` +
+        `export const C = () => <${host} label="L"><SelectFilter field={f} /></${host}>\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('bound-control-outside-home')
+  })
+
+  it.each(['src/cbbi-panel.tsx', 'src/CbbiPanel.tsx'])(
+    'does NOT flag %s — a panel body whose host lives in the parent, in either dialect',
+    (filename) => {
+      const { code, rules } = run(
+        `${CONTROLS_IMPORT}export const C = () => <div><SelectFilter field={f} /></div>\n`,
+        filename,
+      )
+      expect(code).toBe(0)
+      expect(rules).not.toContain('bound-control-outside-home')
+    },
+  )
+
+  // Both dialects need the leading SUBJECT, and neither is case-insensitive — `foopanel.tsx` is a
+  // page module spelled without a separator, not a declaration.
+  it.each(['src/foopanel.tsx', 'src/Panel.tsx'])('still flags %s', (filename) => {
+    const { rules } = run(
+      `${CONTROLS_IMPORT}export const C = () => <div><SelectFilter field={f} /></div>\n`,
+      filename,
+    )
+    expect(rules).toContain('bound-control-outside-home')
+  })
+
+  it('honors a scoped theme-allow', () => {
+    const { rules } = run(
+      `${CONTROLS_IMPORT}export const C = () => (\n  <div>\n    {/* theme-allow bound-control-outside-home — a one-off embedded picker */}\n    <SelectFilter field={f} />\n  </div>\n)\n`,
+    )
+    expect(rules).not.toContain('bound-control-outside-home')
+  })
+
+  it('honors a theme-allow-file declaration', () => {
+    const { rules } = run(
+      `// theme-allow-file bound-control-outside-home — a legacy page, migrating next sprint\n` +
+        `${CONTROLS_IMPORT}export const C = () => <div><SelectFilter field={f} /></div>\n`,
+    )
+    expect(rules).not.toContain('bound-control-outside-home')
+  })
+
+  // Provenance, the same test the raw-filter rules apply the other way round: a consumer's own
+  // `SelectFilter` is not basalt's, and basalt has no claim over where it is written.
+  it('does NOT flag a locally-defined SelectFilter', () => {
+    const { code, rules } = run(
+      `import { SelectFilter } from './my-filters'\n` +
+        `export const C = () => <div><SelectFilter field={f} /></div>\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('bound-control-outside-home')
+  })
+
+  it('flags an ALIASED basalt import with no home', () => {
+    const { rules } = run(
+      `import { SelectFilter as Picker } from 'basalt-ui/controls'\n` +
+        `export const C = () => <div><Picker field={f} /></div>\n`,
+    )
+    expect(rules).toContain('bound-control-outside-home')
+  })
+
+  /**
+   * The owner exemption needs the file to import NOTHING from `basalt-ui*` — see
+   * `control-outside-home`'s copy for why. For THIS rule that makes the exemption reachable only
+   * inside basalt's own `src/`, which is exactly where it is meant to apply: provenance already
+   * requires a basalt import (or a relative one inside that tree), so a consumer file can never be
+   * both the owner and a place this rule could fire.
+   */
+  it('DOES flag a consumer file that declares its own PanelRow', () => {
+    const { rules } = run(
+      `${CONTROLS_IMPORT}function PanelRow({ children }) {\n  return <div>{children}</div>\n}\n` +
+        `export const C = () => <div><SelectFilter field={f} /></div>\n`,
+    )
+    expect(rules).toContain('bound-control-outside-home')
+  })
+
+  // Provenance on the HOME too, the same test `control-outside-home` applies: a consumer's own
+  // `PanelRow` is a layout helper, not the aside's row primitive.
+  it("still flags one inside a consumer's OWN PanelRow", () => {
+    const { rules } = run(
+      `import { SelectFilter } from 'basalt-ui/controls'\nimport { PanelRow } from './panel-row'\n` +
+        `export const C = () => (\n  <PanelRow label="Scale">\n    <SelectFilter field={f} />\n  </PanelRow>\n)\n`,
+    )
+    expect(rules).toContain('bound-control-outside-home')
+  })
+
+  /**
+   * `SliderControl` is NOT policed: it renders its own `PanelRow` and has no pill form at all
+   * (`docs/ASIDE-SPEC.md` §3), so "this renders as a stray pill" is false for it and a `Section`
+   * body is a legitimate place to write one. The plugin has no per-tag home set, so the honest fix
+   * is dropping it from the policed set rather than giving it a private exemption.
+   */
+  it('does NOT flag a SliderControl in a Section body — it has no pill form', () => {
+    const { code, rules } = run(
+      `${ASIDE_IMPORT}${CONTROLS_IMPORT}export const C = () => (\n  <Section title="Weights">\n    <SliderControl field={f} label="Pi" />\n  </Section>\n)\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('bound-control-outside-home')
+  })
+
+  it('resolves a hoisted binding handed to a slot, like its siblings do', () => {
+    const { rules } = run(
+      `${ASIDE_IMPORT}${CONTROLS_IMPORT}const pills = <SelectFilter field={f} />\n` +
+        `export const C = () => <PageBar filters={pills} />\n`,
+    )
+    expect(rules).not.toContain('bound-control-outside-home')
+  })
+
+  /**
+   * …and one handed to a subtree home as its CHILDREN, which the ancestry walk cannot see: at the
+   * `const` there is no `PageAside` above the node at all. The same `Program:exit` deferral the
+   * slot lane uses, over the home's `{expr}` children instead of its attributes.
+   */
+  it('resolves a hoisted binding rendered as a PageAside CHILD', () => {
+    const { code, rules } = run(
+      `${ASIDE_IMPORT}${CONTROLS_IMPORT}const rows = <SelectFilter field={f} />\n` +
+        `export const C = () => <PageAside title="Filters">{rows}</PageAside>\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('bound-control-outside-home')
+  })
+
+  it('still flags the same hoisted binding under a bare Stack', () => {
+    const { rules } = run(
+      `import { Stack } from '@mantine/core'\n${CONTROLS_IMPORT}const rows = <SelectFilter field={f} />\n` +
+        `export const C = () => <Stack>{rows}</Stack>\n`,
+    )
+    expect(rules).toContain('bound-control-outside-home')
   })
 })
 
@@ -2159,6 +2597,17 @@ describe('basalt/responsive-twin', () => {
     expect(rules).not.toContain('responsive-twin')
   })
 
+  // The owner exemption's second half, the same predicate its two siblings apply: a consumer file
+  // that names a helper `PanelRow` and imports basalt is consuming basalt, not defining a control.
+  it('DOES flag a file that declares its own PanelRow but imports basalt-ui', () => {
+    const { rules } = run(
+      `import { Section } from 'basalt-ui'\n` +
+        `function PanelRow({ children }) {\n  return <div>{children}</div>\n}\n` +
+        `export const C = () => (\n  <div>\n    <SegmentedControl visibleFrom="sm" data={[]} />\n    <SegmentedControl hiddenFrom="sm" data={[]} />\n  </div>\n)\n`,
+    )
+    expect(rules).toContain('responsive-twin')
+  })
+
   it('honors a scoped theme-allow', () => {
     const { rules } = run(
       `export const C = () => (\n  <div>\n    <SegmentedControl visibleFrom="sm" data={[]} />\n    {/* theme-allow responsive-twin — two genuinely different data sets */}\n    <SegmentedControl hiddenFrom="sm" data={[]} />\n  </div>\n)\n`,
@@ -2507,6 +2956,7 @@ describe('PLUGIN_RULE_ID_LIST ↔ the plugin', () => {
 
   it('gives ./controls the control-tier rules', () => {
     expect([...SURFACES['./controls'].pluginRules].toSorted()).toEqual([
+      'bound-control-outside-home',
       'control-outside-home',
       'control-size-literal',
       'hand-rolled-filter',
@@ -2514,3 +2964,453 @@ describe('PLUGIN_RULE_ID_LIST ↔ the plugin', () => {
     ])
   })
 })
+
+// ── provider-above-router (F5) ───────────────────────────────────────────────
+
+describe('basalt/provider-above-router', () => {
+  const IMPORTS =
+    `import { BasaltProvider } from 'basalt-ui'\n` +
+    `import { RouterProvider } from '@tanstack/react-router'\n`
+
+  it('flags a BasaltProvider rendered inside a RouterProvider', () => {
+    const { code, rules } = run(
+      `${IMPORTS}export const App = () => (\n` +
+        `  <RouterProvider router={r}>\n    <BasaltProvider>{null}</BasaltProvider>\n` +
+        `  </RouterProvider>\n)\n`,
+    )
+    expect(code).toBe(1)
+    expect(rules).toContain('provider-above-router')
+  })
+
+  it('does NOT flag the correct order — provider above router', () => {
+    const { code, rules } = run(
+      `${IMPORTS}export const App = () => (\n` +
+        `  <BasaltProvider>\n    <RouterProvider router={r} />\n  </BasaltProvider>\n)\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('provider-above-router')
+  })
+
+  // Provenance both ways: the tag names alone are not the finding.
+  it("does NOT flag a consumer's own BasaltProvider (no basalt import)", () => {
+    const { code, rules } = run(
+      `import { RouterProvider } from '@tanstack/react-router'\n` +
+        `import { BasaltProvider } from './my-provider'\n` +
+        `export const App = () => (\n  <RouterProvider router={r}>\n` +
+        `    <BasaltProvider>{null}</BasaltProvider>\n  </RouterProvider>\n)\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('provider-above-router')
+  })
+
+  it('does NOT flag a RouterProvider that is not TanStack s', () => {
+    const { code, rules } = run(
+      `import { BasaltProvider } from 'basalt-ui'\n` +
+        `import { RouterProvider } from 'other-router'\n` +
+        `export const App = () => (\n  <RouterProvider router={r}>\n` +
+        `    <BasaltProvider>{null}</BasaltProvider>\n  </RouterProvider>\n)\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('provider-above-router')
+  })
+
+  // The alias is why the ancestry is read by BINDING and not by written tag name.
+  it('flags through an aliased RouterProvider import', () => {
+    const { code, rules } = run(
+      `import { BasaltProvider } from 'basalt-ui'\n` +
+        `import { RouterProvider as Router } from '@tanstack/react-router'\n` +
+        `export const App = () => (\n  <Router router={r}>\n` +
+        `    <BasaltProvider>{null}</BasaltProvider>\n  </Router>\n)\n`,
+    )
+    expect(code).toBe(1)
+    expect(rules).toContain('provider-above-router')
+  })
+
+  it('honours a theme-allow naming the rule', () => {
+    const { code, rules } = run(
+      `${IMPORTS}export const App = () => (\n  <RouterProvider router={r}>\n` +
+        `    {/* theme-allow provider-above-router — legacy bootstrap, ported next minor */}\n` +
+        `    <BasaltProvider>{null}</BasaltProvider>\n  </RouterProvider>\n)\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('provider-above-router')
+  })
+
+  // The documented limit of the heuristic — stated in the rule's own JSDoc, pinned here so a
+  // future widening has to move this test rather than discover the gap.
+  it('does NOT see a cross-file composition (static JSX ancestry only)', () => {
+    const { code, rules } = run(
+      `import { BasaltProvider } from 'basalt-ui'\n` +
+        `import { Routes } from './routes'\n` +
+        `export const App = () => (\n  <Routes>\n    <BasaltProvider>{null}</BasaltProvider>\n` +
+        `  </Routes>\n)\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('provider-above-router')
+  })
+})
+
+// ── query-dual-import (F5) ───────────────────────────────────────────────────
+
+describe('basalt/query-dual-import', () => {
+  it('flags a file importing from both @tanstack/react-query and basalt-ui/query', () => {
+    const { code, rules, output } = run(
+      `import { useQuery } from '@tanstack/react-query'\n` +
+        `import { unwrap } from 'basalt-ui/query'\n` +
+        `export const useThing = () => useQuery({ queryKey: ['t'], queryFn: () => unwrap(get()) })\n`,
+    )
+    expect(code).toBe(1)
+    expect(rules).toContain('query-dual-import')
+    expect(output).toContain('Dual query import')
+  })
+
+  // The softer half — the one that actually catches the drift, and why the rule is `warn`.
+  it('flags a raw @tanstack/react-query import beside a basalt root import', () => {
+    const { code, rules, output } = run(
+      `import { useQuery } from '@tanstack/react-query'\n` +
+        `import { QueryState } from 'basalt-ui'\n` +
+        `export const useThing = () => useQuery({ queryKey: ['t'], queryFn: get })\n`,
+    )
+    expect(code).toBe(1)
+    expect(rules).toContain('query-dual-import')
+    expect(output).toContain('Raw @tanstack/react-query import')
+  })
+
+  it('does NOT flag basalt-ui/query on its own', () => {
+    const { code, rules } = run(
+      `import { useQuery, unwrap } from 'basalt-ui/query'\n` +
+        `export const useThing = () => useQuery({ queryKey: ['t'], queryFn: () => unwrap(get()) })\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('query-dual-import')
+  })
+
+  // `import type` is erased at compile time — there is no runtime import to route through the
+  // seam, and typing against the library's own result type is what `QueryStateLike` documents as
+  // legitimate. Same skip `agent-no-raw-usechat` and `ai-sdk-major` take.
+  it('does NOT flag a type-only @tanstack/react-query import beside basalt-ui/query', () => {
+    const { code, rules } = run(
+      `import type { UseQueryResult } from '@tanstack/react-query'\n` +
+        `import { unwrap } from 'basalt-ui/query'\n` +
+        `export const pick = (q: UseQueryResult<number>) => unwrap(q.data)\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('query-dual-import')
+  })
+
+  it('does NOT flag @tanstack/react-query in a file with no basalt import', () => {
+    const { code, rules } = run(
+      `import { useQuery } from '@tanstack/react-query'\n` +
+        `export const useThing = () => useQuery({ queryKey: ['t'], queryFn: get })\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('query-dual-import')
+  })
+
+  // The devtools package is a different package, not a subpath.
+  it('does NOT flag @tanstack/react-query-devtools', () => {
+    const { code, rules } = run(
+      `import { ReactQueryDevtools } from '@tanstack/react-query-devtools'\n` +
+        `import { unwrap } from 'basalt-ui/query'\n` +
+        `export const D = () => <ReactQueryDevtools />\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('query-dual-import')
+  })
+
+  it('honours a theme-allow naming the rule', () => {
+    const { code, rules } = run(
+      `// theme-allow query-dual-import — the persister API has no basalt re-export yet\n` +
+        `import { useQuery } from '@tanstack/react-query'\n` +
+        `import { unwrap } from 'basalt-ui/query'\n` +
+        `export const useThing = () => useQuery({ queryKey: ['t'], queryFn: () => unwrap(g()) })\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('query-dual-import')
+  })
+})
+
+// ── query-fn-unwrap (F5) ─────────────────────────────────────────────────────
+
+describe('basalt/query-fn-unwrap', () => {
+  const IMPORT = `import { unwrap } from 'basalt-ui/query'\n`
+
+  it('flags a queryFn that fetches with no unwrap', () => {
+    const { code, rules } = run(
+      `${IMPORT}export const o = { queryKey: ['t'], queryFn: () => fetch('/api/t') }\n`,
+    )
+    expect(code).toBe(1)
+    expect(rules).toContain('query-fn-unwrap')
+  })
+
+  it('flags the async .json() form', () => {
+    const { code, rules } = run(
+      `${IMPORT}export const o = {\n  queryKey: ['t'],\n` +
+        `  queryFn: async () => (await fetch('/api/t')).json(),\n}\n`,
+    )
+    expect(code).toBe(1)
+    expect(rules).toContain('query-fn-unwrap')
+  })
+
+  it('does NOT flag a queryFn that wraps the call', () => {
+    const { code, rules } = run(
+      `${IMPORT}export const o = { queryKey: ['t'], queryFn: () => unwrap(fetch('/api/t')) }\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('query-fn-unwrap')
+  })
+
+  it('does NOT flag a queryFn with no fetch in it', () => {
+    const { code, rules } = run(
+      `${IMPORT}export const o = { queryKey: ['t'], queryFn: () => client.t.get() }\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('query-fn-unwrap')
+  })
+
+  // The scope gate: with no basalt-ui/query import this is an opinion about `fetch`, which basalt
+  // does not have.
+  it('does NOT flag a file that never imports basalt-ui/query', () => {
+    const { code, rules } = run(
+      `export const o = { queryKey: ['t'], queryFn: () => fetch('/api/t') }\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('query-fn-unwrap')
+  })
+
+  // The documented blind spot — a reference, not a function literal. Pinned so a widening moves it.
+  it('does NOT see a queryFn passed as a reference', () => {
+    const { code, rules } = run(
+      `${IMPORT}const load = () => fetch('/api/t')\n` +
+        `export const o = { queryKey: ['t'], queryFn: load }\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('query-fn-unwrap')
+  })
+
+  it('honours a theme-allow naming the rule', () => {
+    const { code, rules } = run(
+      `${IMPORT}export const o = {\n  queryKey: ['t'],\n` +
+        `  // theme-allow query-fn-unwrap — raw Response is the point, this reads a blob\n` +
+        `  queryFn: () => fetch('/api/t'),\n}\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('query-fn-unwrap')
+  })
+})
+
+// ── deprecated-export (B4) ───────────────────────────────────────────────────
+
+// deprecated-export's behaviour tests were removed with the last ledger row in 1.29.0; the
+// ledger-shape and barrel-scan assertions below keep the mechanism honest until the next row.
+
+// ── forms-field-key ──────────────────────────────────────────────────────────
+
+describe('basalt/forms-field-key', () => {
+  const FORMS = `import { inputProps } from 'basalt-ui/forms'\n`
+
+  it('flags a spread inputProps() with no sibling key', () => {
+    const { code, rules, output } = run(
+      `${FORMS}export const C = () => <TextInput {...inputProps(form, 'email')} />\n`,
+    )
+    expect(code).toBe(1)
+    expect(rules).toContain('forms-field-key')
+    expect(output).toContain('no sibling `key`')
+  })
+
+  it('does NOT flag the documented two-call idiom', () => {
+    const { code, rules } = run(
+      `import { fieldKey, inputProps } from 'basalt-ui/forms'\n` +
+        `export const C = () => <TextInput key={fieldKey(form, 'e')} {...inputProps(form, 'e')} />\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('forms-field-key')
+  })
+
+  // An `inputProps` a consumer wrote themselves is not basalt's — the same provenance gate the
+  // control and chart rules take, one lane over.
+  it('does NOT flag a same-named helper imported from somewhere else', () => {
+    const { code, rules } = run(
+      `import { inputProps } from './my-helpers'\n` +
+        `export const C = () => <TextInput {...inputProps(form, 'email')} />\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('forms-field-key')
+  })
+
+  it('resolves an aliased import — `inputProps as f` is still inputProps', () => {
+    const { code, rules } = run(
+      `import { inputProps as f } from 'basalt-ui/forms'\n` +
+        `export const C = () => <TextInput {...f(form, 'email')} />\n`,
+    )
+    expect(code).toBe(1)
+    expect(rules).toContain('forms-field-key')
+  })
+
+  // The second message: `field` still RETURNS `key`, so it is reported whether or not the element
+  // carries one — the remedy is the rename, never an added attribute.
+  it('flags a spread field() even when the element already has a key', () => {
+    const { code, rules, output } = run(
+      `import { field } from 'basalt-ui/forms'\n` +
+        `export const C = () => <TextInput key="e" {...field(form, 'email')} />\n`,
+    )
+    expect(code).toBe(1)
+    expect(rules).toContain('forms-field-key')
+    expect(output).toContain('@deprecated 1.27 alias')
+  })
+
+  it('honours a theme-allow naming the rule', () => {
+    const { code, rules } = run(
+      `${FORMS}export const C = () => (\n` +
+        `  // theme-allow forms-field-key — this input is remounted by its parent\n` +
+        `  <TextInput {...inputProps(form, 'email')} />\n)\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('forms-field-key')
+  })
+
+  // The autofix has to produce COMPILING code: an inserted `fieldKey(…)` with no import is a worse
+  // outcome than the missing key it replaced.
+  it('autofixes the key in, with the same arguments, and adds fieldKey to the import once', () => {
+    const source =
+      `${FORMS}export const C = () => (\n` +
+      `  <form>\n` +
+      `    <TextInput {...inputProps(form, 'email')} label="Email" />\n` +
+      `    <TextInput {...inputProps(form, 'name')} />\n` +
+      `  </form>\n)\n`
+    writeFileSync(resolve(dir, 'fixture.tsx'), source)
+    Bun.spawnSync([OXLINT_BIN, '-c', '.oxlintrc.json', '--fix', 'fixture.tsx'], { cwd: dir })
+    const fixed = readFileSync(resolve(dir, 'fixture.tsx'), 'utf8')
+    expect(fixed).toContain(`import { inputProps, fieldKey } from 'basalt-ui/forms'`)
+    expect(fixed).toContain(`key={fieldKey(form, 'email')} {...inputProps(form, 'email')}`)
+    expect(fixed).toContain(`key={fieldKey(form, 'name')} {...inputProps(form, 'name')}`)
+    // Once, not twice: two overlapping edits to one import declaration would drop one of them.
+    expect(fixed.match(/fieldKey,|, fieldKey/g)).toHaveLength(1)
+  })
+
+  it('does not re-add fieldKey when it is already imported', () => {
+    const source =
+      `import { fieldKey, inputProps } from 'basalt-ui/forms'\n` +
+      `export const C = () => <TextInput {...inputProps(form, 'email')} />\n`
+    writeFileSync(resolve(dir, 'fixture.tsx'), source)
+    Bun.spawnSync([OXLINT_BIN, '-c', '.oxlintrc.json', '--fix', 'fixture.tsx'], { cwd: dir })
+    const fixed = readFileSync(resolve(dir, 'fixture.tsx'), 'utf8')
+    expect(fixed).toContain(`import { fieldKey, inputProps } from 'basalt-ui/forms'`)
+    expect(fixed).toContain(`key={fieldKey(form, 'email')}`)
+  })
+})
+
+// ── the deprecation ledger (B4) ──────────────────────────────────────────────
+
+describe('DEPRECATED_EXPORTS', () => {
+  const pkgVersion = (
+    JSON.parse(readFileSync(resolve(import.meta.dirname, '..', 'package.json'), 'utf8')) as {
+      version: string
+    }
+  ).version
+
+  it('carries a replacement and a removeIn at least one minor out on every row', () => {
+    const [major, minor] = pkgVersion.split('.').map(Number)
+    const floor = `${major}.${(minor as number) + 1}.0`
+    for (const row of DEPRECATED_EXPORTS) {
+      expect([row.name, row.replacement.length > 0]).toEqual([row.name, true])
+      expect([row.name, /^\d+\.\d+\.\d+$/.test(row.removeIn)]).toEqual([row.name, true])
+      expect([row.name, compareSemver(row.removeIn, floor) >= 0]).toEqual([row.name, true])
+    }
+  })
+
+  it('names a real published subpath on every row', () => {
+    const exports = Object.keys(
+      (
+        JSON.parse(readFileSync(resolve(import.meta.dirname, '..', 'package.json'), 'utf8')) as {
+          exports: Record<string, unknown>
+        }
+      ).exports,
+    )
+    for (const row of DEPRECATED_EXPORTS) {
+      const subpath = row.subpath === 'basalt-ui' ? '.' : row.subpath.replace('basalt-ui', '.')
+      expect([row.subpath, exports.includes(subpath)]).toEqual([row.subpath, true])
+    }
+  })
+
+  /**
+   * The barrel half of the lifecycle: a JSDoc `@deprecated` on a published barrel with no ledger
+   * row is an export nothing nudges anyone off. Deliberately scoped to `src/**' + '/index.ts(x)` —
+   * the files a consumer's import resolves through. To add one: write the `@deprecated` JSDoc, add
+   * the `DEPRECATED_EXPORTS` row, add the `MIGRATING.md` row.
+   */
+  it('has a row for every @deprecated JSDoc tag on a published barrel', () => {
+    const barrels = [
+      ...new Bun.Glob('src/**/index.{ts,tsx}').scanSync({
+        cwd: resolve(import.meta.dirname, '..'),
+        absolute: true,
+      }),
+    ]
+    const names = new Set(DEPRECATED_EXPORTS.map((row) => row.prop ?? row.name))
+    for (const file of barrels) {
+      const lines = readFileSync(file, 'utf8').split('\n')
+      for (const [index, line] of lines.entries()) {
+        if (!/^\s*\*\s*@deprecated\b/.test(line)) continue
+        const declared = lines
+          .slice(index, index + 12)
+          .map((l) => /^\s*(?:readonly\s+)?([A-Za-z_$][\w$]*)\??\s*[:(]/.exec(l)?.[1])
+          .find((name) => name !== undefined)
+        expect([file, declared, declared !== undefined && names.has(declared)]).toEqual([
+          file,
+          declared,
+          true,
+        ])
+      }
+    }
+  })
+})
+
+// ── the `Ships:` claim above each rule (F26) ─────────────────────────────────
+
+/**
+ * F26 was a rule's own doc comment claiming a level it did not ship at, with nothing able to catch
+ * it: the C16 ledger is asserted against the preset, and a COMMENT is outside the ledger. So the
+ * claim is now one normalised line — `// Ships: <level>` directly above each rule's `const` — and
+ * this is the assertion that makes it as checkable as the ledger it restates.
+ */
+describe('the `Ships:` line above each rule', () => {
+  const source = readFileSync(resolve(import.meta.dirname, 'oxlint-plugin.js'), 'utf8')
+  const lines = source.split('\n')
+  const shipped = JSON.parse(readFileSync(resolve(import.meta.dirname, 'oxlint.json'), 'utf8')) as {
+    rules: Record<string, unknown>
+  }
+  // The registry block maps rule id → the `const` implementing it.
+  const registry = [
+    ...source.slice(source.indexOf('export default {')).matchAll(/^ {4}'([\w-]+)': (\w+),$/gm),
+  ].map(([, id, binding]) => ({ id: id as string, binding: binding as string }))
+
+  it('covers every registered rule', () => {
+    expect(registry.map((r) => r.id).toSorted()).toEqual(Object.keys(basaltPlugin.rules).toSorted())
+  })
+
+  for (const { id, binding } of registry) {
+    it(`${id}: the claim matches oxlint.json`, () => {
+      const at = lines.indexOf(`const ${binding} = {`)
+      expect([id, at]).not.toEqual([id, -1])
+      const claim = /^\/\/ Ships: (.+)$/.exec(lines[at - 1] as string)?.[1]
+      const level = shipped.rules[`basalt/${id}`]
+      if (level === undefined) {
+        expect([id, claim]).toEqual([id, 'repo-local only'])
+        return
+      }
+      if (Object.hasOwn(PLUGIN_RULE_GRACE, id)) {
+        const { promote } = PLUGIN_RULE_GRACE[id] as GraceEntry
+        expect([id, claim]).toEqual([id, `warn (grace → ${promote})`])
+        expect([id, level]).toEqual([id, 'warn'])
+        return
+      }
+      if (Object.hasOwn(PLUGIN_RULE_ADVISORY, id)) {
+        expect([id, claim]).toEqual([id, 'warn (advisory)'])
+        expect([id, level]).toEqual([id, 'warn'])
+        return
+      }
+      expect([id, claim]).toEqual([id, 'error'])
+      expect([id, level]).toEqual([id, 'error'])
+    })
+  }
+})