basalt-ui 1.25.0 → 1.27.0

package/src/guard/check-source.test.ts

@@ -1,7 +1,7 @@
 /**
  * Unit tests for checkSource — the pure (text, relPath, cfg) → Finding[] core.
  *
- * Covers all 25 guard kinds. Co-located with the guard, excluded from tsc
+ * Covers all 27 guard kinds. Co-located with the guard, excluded from tsc
  * (tsconfig exclude: src/**\/*.test.ts), run via `bun test`.
  *
  * The walker/reporter half is covered by the integration test in
@@ -1916,15 +1916,16 @@ describe('severity', () => {
     expect(f.find((v) => v.kind === 'raw-spacing')?.severity).toBe('error')
   })
 
-  // The grace ledger. Five kinds landed warn-only in the round-4 guard minor; deleting an entry
-  // from GRACE_PERIOD_KINDS is the promotion, and it shows up here as an explicit diff.
+  // The grace ledger. These five kinds landed warn-only in the round-4 guard minor and sat there
+  // for five minors with nothing tracking the promise (D4) — GRACE_PERIOD_KINDS is now empty and
+  // the C16 version gate in grace.test.ts is what stops a future entry sitting unpromoted again.
   it.each([
     'theme-allow-unscoped',
     'surface-shadow-override',
     'css-raw-surface',
     'inline-font-size',
     'hidden-inline-style',
-  ])('%s is still in its grace minor (warn)', (kind) => {
+  ])('%s is promoted past its grace minor (error)', (kind) => {
     const cases: Record<string, [string, string]> = {
       'theme-allow-unscoped': ['const x = 1 // theme-allow', PATH],
       'surface-shadow-override': ['const s = { boxShadow: `0 0 0 2px ${VX.accent}` }', PATH],
@@ -1937,7 +1938,7 @@ describe('severity', () => {
     }
     const [src, path] = cases[kind] as [string, string]
     const hit = find(src, path).find((v) => v.kind === kind)
-    expect(hit?.severity).toBe('warn')
+    expect(hit?.severity).toBe('error')
   })
 
   it('ships every OTHER kind past its grace period', () => {
@@ -2139,9 +2140,9 @@ describe('theme-allow scoping', () => {
     expect(f).toHaveLength(0)
   })
 
-  it('ships theme-allow-unscoped as a warning, not a build failure', () => {
+  it('ships theme-allow-unscoped as an error (promoted, C16)', () => {
     const f = find(`const x = 1 // theme-allow`)
-    expect(f.every((v) => v.severity === 'warn')).toBe(true)
+    expect(f.every((v) => v.severity === 'error')).toBe(true)
   })
 
   // The annotation itself lives in a comment; a `theme-allow` in real code must not waive anything.
@@ -2370,9 +2371,9 @@ describe('surface-shadow-override', () => {
     expect(kinds(f)).not.toContain('surface-shadow-override')
   })
 
-  it('ships as a warning for its grace minor', () => {
+  it('is an error now that its grace minor has ended (promoted, C16)', () => {
     const f = find('const s = { boxShadow: `0 0 0 2px ${VX.accent}` }')
-    expect(f.find((v) => v.kind === 'surface-shadow-override')?.severity).toBe('warn')
+    expect(f.find((v) => v.kind === 'surface-shadow-override')?.severity).toBe('error')
   })
 })
 
@@ -2435,6 +2436,147 @@ describe('inline-font-size', () => {
   })
 })
 
+// ── 26. in-body-page-title (the text lane of law C8) ─────────────────────────
+
+describe('in-body-page-title', () => {
+  it('flags <Title order={1}> in the body', () => {
+    expect(kinds(find(`<Title order={1}>Analytics</Title>`))).toContain('in-body-page-title')
+  })
+
+  it('flags order={2} too', () => {
+    expect(kinds(find(`<Title order={2}>Analytics</Title>`))).toContain('in-body-page-title')
+  })
+
+  // The formatted default — the reason this kind is a bounded TAG scan and not a line regex.
+  it('flags a Title formatted across lines', () => {
+    const f = find(`<Title\n  order={1}\n  mb="sm"\n>\n  Analytics\n</Title>`)
+    expect(kinds(f)).toContain('in-body-page-title')
+  })
+
+  it('does NOT flag order={3} — a section heading', () => {
+    expect(kinds(find(`<Title order={3}>Sessions</Title>`))).not.toContain('in-body-page-title')
+  })
+
+  it('does NOT flag a Title with no order', () => {
+    expect(kinds(find(`<Title>Sessions</Title>`))).not.toContain('in-body-page-title')
+  })
+
+  it('does NOT flag anything under a content/ path segment', () => {
+    const f = find(`<Title order={1}>Doc</Title>`, 'src/content/Guide.tsx')
+    expect(kinds(f)).not.toContain('in-body-page-title')
+  })
+
+  // File-scoped and coarser than the plugin's node-level ancestry, on purpose: a document heading
+  // told to become a breadcrumb is the WRONG advice, so the text lane errs silent.
+  it('does NOT flag a file that renders Prose', () => {
+    const f = find(`<Prose>\n  <Title order={1}>Doc</Title>\n</Prose>`)
+    expect(kinds(f)).not.toContain('in-body-page-title')
+  })
+
+  it('honours a theme-allow', () => {
+    const f = find(
+      `// theme-allow in-body-page-title — a shell-less print view\n<Title order={1}>P</Title>`,
+    )
+    expect(kinds(f)).not.toContain('in-body-page-title')
+  })
+
+  // Promoted at 1.27.0 — its GRACE_PERIOD_KINDS entry is gone, and so is the plugin rule of the
+  // same id from PLUGIN_RULE_GRACE. One law, two lanes, one promotion.
+  it('lands error now that the grace entry is gone (C16)', () => {
+    const f = find(`<Title order={1}>Analytics</Title>`)
+    expect(f.find((x) => x.kind === 'in-body-page-title')?.severity).toBe('error')
+  })
+})
+
+// ── 27. raw-selection-control (the text lane of law C1) ──────────────────────
+
+describe('raw-selection-control', () => {
+  it.each(['SegmentedControl', 'Select', 'MultiSelect', 'NativeSelect', 'TagsInput', 'Chip.Group'])(
+    'flags a raw <%s>',
+    (tag) => {
+      expect(kinds(find(`<${tag} data={[]} />`))).toContain('raw-selection-control')
+    },
+  )
+
+  it('reports the tag it found, not the whole line', () => {
+    const f = find(`<Select data={[]} />`)
+    expect(f.find((x) => x.kind === 'raw-selection-control')?.token).toBe('<Select')
+  })
+
+  it.each(['SettingsRow', 'Modal', 'Drawer', 'Menu.Dropdown'])(
+    'does NOT flag one inside a %s window',
+    (host) => {
+      const f = find(`<${host}>\n  <Select data={[]} />\n</${host}>`)
+      expect(kinds(f)).not.toContain('raw-selection-control')
+    },
+  )
+
+  // The window is 12 lines; past it the approximation would start swallowing the NEXT row's control.
+  it('DOES flag one 20 lines below the host tag — the window is bounded', () => {
+    const f = find(`<Modal>\n${'  <Text>x</Text>\n'.repeat(20)}  <Select data={[]} />\n</Modal>`)
+    expect(kinds(f)).toContain('raw-selection-control')
+  })
+
+  it('does NOT flag anything in a file importing @mantine/form', () => {
+    const f = find(`import { useForm } from '@mantine/form'\n<Select data={[]} />`)
+    expect(kinds(f)).not.toContain('raw-selection-control')
+  })
+
+  it('does NOT flag the file that DEFINES a basalt control', () => {
+    const f = find(`export function ViewTabs() {\n  return <SegmentedControl data={[]} />\n}`)
+    expect(kinds(f)).not.toContain('raw-selection-control')
+  })
+
+  it('does NOT flag a bound basalt control', () => {
+    expect(kinds(find(`<SelectFilter field={f} label="Channel" />`))).not.toContain(
+      'raw-selection-control',
+    )
+  })
+
+  it('honours a theme-allow', () => {
+    const f = find(
+      `{/* theme-allow raw-selection-control — a one-off admin picker */}\n<Select data={[]} />`,
+    )
+    expect(kinds(f)).not.toContain('raw-selection-control')
+  })
+
+  // The CROSS-FILE exemption — the same basename convention the plugin's `control-outside-home`
+  // applies, so both lanes agree on the same file (one law, two lanes, one exemption). argo carried
+  // 9 of these: a control in a modal/form module whose `<Modal>` is rendered by the parent, which is
+  // outside the 12-line host window because the host tag is not in the file at all.
+  it.each([
+    'src/edit-session-modal.tsx',
+    'src/filters-drawer.tsx',
+    'src/column-popover.tsx',
+    'src/detail-panel.tsx',
+    'src/booking-form.tsx',
+  ])('does NOT flag %s — the overlay filename convention', (relPath) => {
+    expect(kinds(find(`<Select data={[]} />`, relPath))).not.toContain('raw-selection-control')
+  })
+
+  it('still flags a page module beside them', () => {
+    expect(kinds(find(`<Select data={[]} />`, 'src/bookings-page.tsx'))).toContain(
+      'raw-selection-control',
+    )
+  })
+
+  // Basename only, and it needs the leading subject: a `modal/` DIRECTORY holds the page pieces
+  // around the modals too, and a bare `modal.tsx` is a page module in every consumer that has one.
+  it.each(['src/modal/session.tsx', 'src/modal.tsx'])(
+    'is a subject-prefixed BASENAME convention, not %s',
+    (relPath) => {
+      expect(kinds(find(`<Select data={[]} />`, relPath))).toContain('raw-selection-control')
+    },
+  )
+
+  // Still warn at 1.27.0 — this kind and its AST twin `basalt/control-outside-home` are the C1 pair
+  // that moved to `promote: '1.28.0'` while the other wave-6 entries promoted.
+  it('lands warn while the grace entry stands (C16)', () => {
+    const f = find(`<Select data={[]} />`)
+    expect(f.find((x) => x.kind === 'raw-selection-control')?.severity).toBe('warn')
+  })
+})
+
 // ── 26. hidden-inline-style ──────────────────────────────────────────────────
 
 describe('hidden-inline-style', () => {
@@ -2475,12 +2617,12 @@ export const C = () => <div style={labelStyle} />`,
     expect(kinds(f)).not.toContain('hidden-inline-style')
   })
 
-  it('ships as a warning for its grace minor', () => {
+  it('is an error now that its grace minor has ended (promoted, C16)', () => {
     const f = find(
       `const wrapperStyle = { position: 'relative', width: '100%' }
 export const C = () => <div style={wrapperStyle} />`,
     )
-    expect(f.find((v) => v.kind === 'hidden-inline-style')?.severity).toBe('warn')
+    expect(f.find((v) => v.kind === 'hidden-inline-style')?.severity).toBe('error')
   })
 })
 
@@ -2638,7 +2780,7 @@ describe('markup files (index.html / *.webmanifest)', () => {
  * Round 9: `.astro` and `.vue` became scannable and fell through to the `ts` dialect, so `<!-- … -->`
  * was never stripped — a `theme-allow` written in an HTML comment waived nothing there, and a color
  * inside a commented-out block still reported. They resolve as `sfc` now: BOTH comment dialects,
- * and the full 25-kind set (not `MARKUP_KINDS` — an `.astro` template is JSX-shaped and a `.vue`
+ * and the full 27-kind set (not `MARKUP_KINDS` — an `.astro` template is JSX-shaped and a `.vue`
  * `<script setup>` is real TS).
  */
 describe('single-file components (.astro / .vue)', () => {
@@ -2770,11 +2912,15 @@ describe("profile: 'tokens-only'", () => {
     'css-raw-surface': false,
     'inline-font-size': false,
     'hidden-inline-style': true,
+    // The two wave-6 control kinds: `<Title>` is a Mantine component, and the remedy for either is
+    // a Mantine-rendered home (PageBar / WidgetHeader) or a basalt control over @mantine/core.
+    'in-body-page-title': true,
+    'raw-selection-control': true,
   }
 
   it('classifies every kind in the registry — the table is exhaustive', () => {
     expect(Object.keys(MANTINE_COUPLED).toSorted()).toEqual(Object.keys(GUARD_RULES).toSorted())
-    expect(Object.keys(MANTINE_COUPLED)).toHaveLength(25)
+    expect(Object.keys(MANTINE_COUPLED)).toHaveLength(27)
   })
 
   it('the disabled set is exactly the Mantine-coupled half — a complete partition', () => {

package/src/guard/grace.test.ts

@@ -0,0 +1,158 @@
+/**
+ * The C16 version gate (`docs/CONTROLS-SPEC.md` §1): a `GRACE_PERIOD_KINDS` entry fails the build
+ * once `package.json`'s version reaches its `promote`, and every entry must declare `since` before
+ * `promote`. This is the mechanism that replaces the honor system — deleting an entry used to be
+ * the ONLY enforcement of "warn for one minor", and nothing checked that anyone had (D4:
+ * `docs/archive/CONTROLS-SYNTHESIS.md`). Five kinds landed together in the round-4 guard minor and sat
+ * at `warn` for five minors before this test existed.
+ *
+ * `assertGraceLedger` is tested directly against synthetic entries below rather than only through
+ * the real ledger: every pre-existing entry promoted or moved to `PLUGIN_RULE_ADVISORY`'s guard-side
+ * sibling, and an `it.each` over the empty ledger that left behind ran zero assertions, which proved
+ * nothing about the gate actually firing. The ledger carries ONE wave-6 control kind at 1.27.0 —
+ * `raw-selection-control`, re-dated to `promote: '1.28.0'` with its AST twin
+ * `basalt/control-outside-home` (`in-body-page-title` promoted on schedule and its entry is gone) —
+ * and the real-ledger check below runs against it.
+ *
+ * This gate measures the version already PUBLISHED, so it can only go red after the release that
+ * shipped a due entry. `scripts/check-grace.ts` is the other end — `scripts/release.sh` runs it
+ * against the version the dry run computed, before the release is cut.
+ *
+ * Excluded from tsc (tsconfig exclude: src/**\/*.test.ts), run via `bun test`.
+ */
+import { describe, expect, it } from 'bun:test'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { GRACE_PERIOD_KINDS } from './index'
+
+const PACKAGE_JSON_PATH = resolve(import.meta.dirname, '..', '..', 'package.json')
+const CURRENT_VERSION = (JSON.parse(readFileSync(PACKAGE_JSON_PATH, 'utf8')) as { version: string })
+  .version
+
+type GraceEntry = { since: string; promote: string; why: string }
+
+/**
+ * Tiny local semver compare — no dependency. Assumes plain `x.y.z`, no pre-release identifiers
+ * (basalt-ui bans majors and ships no pre-releases). Returns negative when `a` sorts before `b`,
+ * positive when after, zero when equal. Compares each component numerically, not lexically, so
+ * `'1.9.0' < '1.10.0'` and `'1.3.0' < '1.26.0'` — a string compare would get both backwards.
+ */
+export function compareSemver(a: string, b: string): number {
+  const partsA = a.split('.').map(Number)
+  const partsB = b.split('.').map(Number)
+  for (let i = 0; i < 3; i++) {
+    const diff = (partsA[i] ?? 0) - (partsB[i] ?? 0)
+    if (diff !== 0) return diff > 0 ? 1 : -1
+  }
+  return 0
+}
+
+/**
+ * The C16 gate itself, extracted so it can be exercised against a synthetic ledger as well as the
+ * real one. Throws naming the first offending entry when either invariant breaks: `since` must
+ * precede `promote` for every entry, and no entry's `promote` may be `<=` the given `version`.
+ */
+export function assertGraceLedger(ledger: Record<string, GraceEntry>, version: string): void {
+  for (const [id, entry] of Object.entries(ledger)) {
+    if (compareSemver(entry.since, entry.promote) >= 0) {
+      throw new Error(
+        `${id}: \`since\` (${entry.since}) must be before \`promote\` (${entry.promote}).`,
+      )
+    }
+    if (compareSemver(version, entry.promote) >= 0) {
+      throw new Error(
+        `${id}: package.json is at ${version}, which has reached its promote version ` +
+          `${entry.promote} — promote to error or extend \`promote\` with a reason.`,
+      )
+    }
+  }
+}
+
+describe('compareSemver', () => {
+  it('orders multi-digit components numerically, not lexically', () => {
+    expect(compareSemver('1.9.0', '1.10.0')).toBeLessThan(0)
+    expect(compareSemver('1.10.0', '1.9.0')).toBeGreaterThan(0)
+    expect(compareSemver('1.3.0', '1.26.0')).toBeLessThan(0)
+    expect(compareSemver('1.26.0', '1.3.0')).toBeGreaterThan(0)
+  })
+
+  it('treats equal versions as equal', () => {
+    expect(compareSemver('1.25.0', '1.25.0')).toBe(0)
+  })
+})
+
+describe('assertGraceLedger', () => {
+  it('does not throw on a well-formed entry not yet due', () => {
+    const ledger = { 'fake-kind': { since: '1.0.0', promote: '2.0.0', why: 'synthetic' } }
+    expect(() => assertGraceLedger(ledger, '1.25.0')).not.toThrow()
+  })
+
+  it('throws once the given version reaches promote', () => {
+    const ledger = { 'fake-kind': { since: '1.0.0', promote: '1.25.0', why: 'synthetic' } }
+    expect(() => assertGraceLedger(ledger, '1.25.0')).toThrow(/fake-kind/)
+  })
+
+  it('throws once the given version is past promote', () => {
+    const ledger = { 'fake-kind': { since: '1.0.0', promote: '1.9.0', why: 'synthetic' } }
+    expect(() => assertGraceLedger(ledger, '1.10.0')).toThrow(/fake-kind/)
+  })
+
+  it('throws when since does not precede promote', () => {
+    const ledger = { 'fake-kind': { since: '1.5.0', promote: '1.5.0', why: 'synthetic' } }
+    expect(() => assertGraceLedger(ledger, '1.0.0')).toThrow(/since/)
+  })
+})
+
+describe('GRACE_PERIOD_KINDS — version gate (C16)', () => {
+  it('the real ledger passes the gate against the real package version', () => {
+    expect(() =>
+      assertGraceLedger(GRACE_PERIOD_KINDS as Record<string, GraceEntry>, CURRENT_VERSION),
+    ).not.toThrow()
+  })
+})
+
+// ── the release-time half: scripts/check-grace.ts ────────────────────────────
+// Exercised as a PROCESS, because that is how `scripts/release.sh` consumes it — the exit code is
+// the whole interface, and a script that printed the right words with status 0 would gate nothing.
+
+const CHECK_GRACE = resolve(import.meta.dirname, '..', '..', 'scripts', 'check-grace.ts')
+
+function runCheckGrace(...args: string[]): { code: number; stderr: string; stdout: string } {
+  const result = Bun.spawnSync(['bun', CHECK_GRACE, ...args])
+  return {
+    code: result.exitCode,
+    stderr: result.stderr.toString(),
+    stdout: result.stdout.toString(),
+  }
+}
+
+describe('scripts/check-grace.ts', () => {
+  it('passes for a version below every promote', () => {
+    const { code, stdout } = runCheckGrace('1.0.0')
+    expect([code, stdout.includes('clear of all')]).toEqual([0, true])
+  })
+
+  it('refuses a version that has reached a promote, naming the entries', () => {
+    const { code, stderr } = runCheckGrace('9.9.9')
+    expect(code).toBe(1)
+    expect(stderr).toContain('raw-selection-control')
+    expect(stderr).toContain('basalt/control-outside-home')
+  })
+
+  // 1.27.0 promoted five of the six wave-6 plugin rules and one of the two guard kinds; what is
+  // LEFT is the C1 pair (`raw-selection-control` + `basalt/control-outside-home`), re-dated to
+  // 1.28.0 against a measurement rather than a hunch — see either entry's `why`. So the release
+  // this file used to refuse now passes, and the refusal moved with the pair.
+  it('passes 1.27.0 — the five entries due there promoted', () => {
+    expect(runCheckGrace('1.27.0').code).toBe(0)
+  })
+
+  it('refuses the version the remaining C1 pair is due in (1.28.0)', () => {
+    expect(runCheckGrace('1.28.0').code).toBe(1)
+  })
+
+  it('exits 2 on a missing or malformed version rather than passing vacuously', () => {
+    expect(runCheckGrace().code).toBe(2)
+    expect(runCheckGrace('not-a-version').code).toBe(2)
+  })
+})