basalt-ui 1.25.0 → 1.26.0

package/src/charts/sparklines/BarSparkline.tsx

@@ -7,14 +7,49 @@ type BarSparklineProps = {
   width: number
   height: number
   color?: string
+  /**
+   * Gap between two bars, in px. `1` is the shipped look; `2` at ~10 bars reads as a discrete series
+   * rather than a histogram, which is the KPI-card treatment.
+   *
+   * @default 1
+   */
+  barGap?: number
+  /**
+   * Bar corner radius, in px. `0` is the shipped look.
+   *
+   * @default 0
+   */
+  barRadius?: number
+  /**
+   * Paints the LAST bar in `emphasisColor` at full opacity — "this is where the series ends", the
+   * one reading a trend beside a KPI value is actually for. Off by default: a chart that means
+   * something by its final point must say so.
+   *
+   * @default false
+   */
+  emphasizeLast?: boolean
+  /** The emphasised bar's fill. @default `VX.accent` */
+  emphasisColor?: string
   /** Accessible text alternative, applied as `aria-label` (+ `role="img"`) on the `<svg>`. */
   ariaLabel?: string
 }
 
 /** Quiet inline bar trend — defaults to `VX.faint`, matching the sparkline family's restrained
- * identity (docs/DESIGN-SPEC.md §5). */
-export function BarSparkline({ data, width, height, color, ariaLabel }: BarSparklineProps) {
+ * identity (docs/DESIGN-SPEC.md §5). Every geometry option below defaults to the shipped look, so
+ * an existing call site renders byte-identically. */
+export function BarSparkline({
+  data,
+  width,
+  height,
+  color,
+  barGap = 1,
+  barRadius = 0,
+  emphasizeLast = false,
+  emphasisColor,
+  ariaLabel,
+}: BarSparklineProps) {
   const fillColor = color ?? VX.faint
+  const lastColor = emphasisColor ?? VX.accent
   const a11yProps = ariaLabel !== undefined ? { role: 'img' as const, 'aria-label': ariaLabel } : {}
 
   const yScale = useMemo(() => {
@@ -25,12 +60,14 @@ export function BarSparkline({ data, width, height, color, ariaLabel }: BarSpark
   if (!data.length) return <svg width={width} height={height} {...a11yProps} />
 
   const step = width / data.length
-  const barWidth = Math.max(step - 1, 1)
+  const barWidth = Math.max(step - barGap, 1)
+  const lastIndex = data.length - 1
 
   return (
     <svg width={width} height={height} {...a11yProps}>
       {data.map((v, i) => {
         const bh = Math.max(yScale(Math.max(v, 0)), 0)
+        const isLast = emphasizeLast && i === lastIndex
         return (
           <rect
             key={i}
@@ -38,8 +75,9 @@ export function BarSparkline({ data, width, height, color, ariaLabel }: BarSpark
             y={height - bh}
             width={barWidth}
             height={bh}
-            fill={fillColor}
-            fillOpacity={0.75}
+            {...(barRadius > 0 && { rx: barRadius })}
+            fill={isLast ? lastColor : fillColor}
+            fillOpacity={isLast ? 1 : 0.75}
           />
         )
       })}

package/src/cli/check-coverage.test.ts

@@ -0,0 +1,297 @@
+/**
+ * `basalt-ui check-coverage` — the 11 assertions (SURFACES consistency + the agent-layer line
+ * budgets), and the generated `<!-- basalt:coverage -->` header each rule file carries
+ * (docs/CONTROLS-SPEC.md §7).
+ *
+ * The block exists because a rule file's own claim about what enforces it was prose, and prose
+ * drifted: a doc could name a guard kind and stay silent about the oxlint rule doing the real work,
+ * or claim coverage for a law nothing checks (D8). Generating it from SURFACES makes the claim a
+ * projection of the registry, and `--check` makes a stale claim a build failure.
+ *
+ * The pure half (`coverageFor` / `coverageBlock` / `applyCoverageBlock`) is tested directly; the fs
+ * half runs against a TEMP package root, never the real `agent/rules/**` — a test that wrote into
+ * the shipped rules would make `--write` untestable afterwards.
+ */
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test'
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { resolve } from 'node:path'
+
+import { GUARD_RULES } from '../guard/index'
+import { RULE_NAMES, SURFACES } from '../surfaces'
+import {
+  COVERAGE_BLOCK_CLOSE,
+  COVERAGE_BLOCK_OPEN,
+  applyCoverageBlock,
+  checkCoverage,
+  coverageBlock,
+  coverageFor,
+  readCoverageBlock,
+  reconcileCoverageBlocks,
+} from './index'
+
+const FRONTMATTER = `---\nsource: basalt-ui\ndescription: d\npaths:\n  - 'src/**'\n---\n`
+
+let dir: string
+
+beforeEach(() => {
+  dir = mkdtempSync(resolve(tmpdir(), 'basalt-check-coverage-'))
+  mkdirSync(resolve(dir, 'agent/rules'), { recursive: true })
+})
+
+afterEach(() => {
+  rmSync(dir, { recursive: true, force: true })
+})
+
+/** Writes one rule file into the temp package root and returns its path. */
+function writeRuleFile(rule: string, body: string): string {
+  const path = resolve(dir, `agent/rules/basalt-${rule}.md`)
+  writeFileSync(path, body)
+  return path
+}
+
+// ── the 11 assertions ────────────────────────────────────────────────────────
+
+describe('checkCoverage', () => {
+  it('passes against the live registry', () => {
+    expect(checkCoverage()).toBe(0)
+  })
+
+  it('rejects --write and --check together rather than picking one', () => {
+    expect(checkCoverage(['--write', '--check'])).toBe(1)
+  })
+
+  it('holds every shipped agent-layer file inside its budget, and the rules inside the total', () => {
+    // Assertion 10, read off the real layer rather than a fixture: the budgets ARE the doctrine, so
+    // the interesting failure is a shipped rule growing past one, not a synthetic file doing it.
+    const pkgRoot = resolve(import.meta.dir, '../..')
+    const lines = (rel: string) =>
+      readFileSync(resolve(pkgRoot, rel), 'utf8').split('\n').length - 1
+    const total = RULE_NAMES.reduce((sum, rule) => sum + lines(`agent/rules/basalt-${rule}.md`), 0)
+    expect(total).toBeLessThanOrEqual(1050)
+    expect(RULE_NAMES.length).toBe(6)
+    for (const skill of ['basalt-app', 'basalt-design', 'basalt-charts']) {
+      expect(lines(`agent/skills/${skill}/SKILL.md`)).toBeLessThanOrEqual(100)
+    }
+    expect(lines('agent/templates/CLAUDE-block.md.tpl')).toBeLessThanOrEqual(40)
+    expect(lines('agent/templates/DESIGN.md.tpl')).toBeLessThanOrEqual(45)
+  })
+})
+
+// ── coverageFor — the projection ─────────────────────────────────────────────
+
+describe('coverageFor', () => {
+  // `rule` is many-to-one: `data` covers ./data, ./data/table and ./data/virtual, `mantine` covers
+  // `.` and ./connectivity. Reading one surface would understate the rule's coverage.
+  it('unions every surface carrying the rule', () => {
+    const mantine = coverageFor('mantine')
+    expect(mantine.pluginRules).toContain('hand-rolled-shell')
+    expect(mantine.guardKinds).toContain('raw-form-control')
+  })
+
+  it('names the control rules under the controls rule', () => {
+    expect(coverageFor('controls').pluginRules).toEqual([
+      'control-outside-home',
+      'control-size-literal',
+      'hand-rolled-filter',
+      'responsive-twin',
+    ])
+  })
+
+  it('carries the advisory laws verbatim, in spec order', () => {
+    const { advisoryLaws } = coverageFor('controls')
+    expect(advisoryLaws.length).toBe(4)
+    expect(advisoryLaws[0]).toContain('C1 as a cross-file law')
+  })
+
+  it('dedupes a kind two surfaces share', () => {
+    const { guardKinds } = coverageFor('charts')
+    expect(guardKinds.filter((k) => k === 'raw-hex')).toHaveLength(1)
+  })
+
+  it('unions the plugin rules of every surface sharing one rule name', () => {
+    // `batteries` is eight surfaces (query, forms, notifications, commands, data ×3, agent ×2,
+    // content, #app); only the agent pair carries plugin rules, and the header must name them.
+    const { guardKinds, pluginRules } = coverageFor('batteries')
+    expect(guardKinds).toEqual([])
+    expect(pluginRules).toEqual(['agent-no-raw-usechat', 'agent-resume-guard', 'ai-sdk-major'])
+  })
+
+  it('leaves no rule with nothing on either lane', () => {
+    // The 13→6 merge folded the eight `guardKinds: []` rules into one file, so every remaining rule
+    // is backed by something — a header saying otherwise would be a rule with no reason to ship.
+    for (const rule of RULE_NAMES) {
+      const { guardKinds, pluginRules } = coverageFor(rule)
+      expect([rule, guardKinds.length + pluginRules.length > 0]).toEqual([rule, true])
+    }
+  })
+})
+
+// ── coverageBlock — what the file actually carries ───────────────────────────
+
+describe('coverageBlock', () => {
+  it('is HTML comments only, so it renders as nothing', () => {
+    for (const rule of RULE_NAMES) {
+      for (const line of coverageBlock(rule).split('\n')) {
+        expect([rule, line.startsWith('<!--') && line.endsWith('-->')]).toEqual([rule, true])
+      }
+    }
+  })
+
+  it('opens and closes with the delimiters', () => {
+    const block = coverageBlock('controls')
+    expect(block.startsWith(COVERAGE_BLOCK_OPEN)).toBe(true)
+    expect(block.endsWith(COVERAGE_BLOCK_CLOSE)).toBe(true)
+  })
+
+  it('names both lanes, prefixing the oxlint ids', () => {
+    const block = coverageBlock('controls')
+    expect(block).toContain('oxlint rules — basalt/control-outside-home')
+    expect(block).toContain('guard kinds — raw-selection-control')
+  })
+
+  // The empty lane still prints — `none` is a claim someone can check, an omitted section is not.
+  it('prints `none` for a lane with nothing on it', () => {
+    expect(coverageBlock('batteries')).toContain('guard kinds — none')
+  })
+
+  // A block that simply omitted the section would read as "nothing to declare" whether or not
+  // anyone had looked. `—` is a claim someone can check.
+  it('prints `not guarded: —` when a rule declares no advisory law', () => {
+    expect(coverageBlock('tokens')).toContain('<!-- not guarded: — -->')
+  })
+
+  it('prints one line per advisory law, so a diff points at the claim', () => {
+    const lines = coverageBlock('controls')
+      .split('\n')
+      .filter((l) => l.includes('not guarded'))
+    expect(lines).toHaveLength(4)
+  })
+
+  it('is stable — the same registry emits the same bytes', () => {
+    expect(coverageBlock('charts')).toBe(coverageBlock('charts'))
+  })
+})
+
+// ── applyCoverageBlock / readCoverageBlock ──────────────────────────────────
+
+describe('applyCoverageBlock', () => {
+  const block = coverageBlock('controls')
+
+  it('inserts below the YAML frontmatter — the paths: header stays first', () => {
+    const out = applyCoverageBlock(`${FRONTMATTER}\n# Title\n`, block)
+    expect(out.startsWith(FRONTMATTER)).toBe(true)
+    expect(out).toContain(block)
+    expect(out.indexOf(block)).toBeLessThan(out.indexOf('# Title'))
+  })
+
+  it('replaces an existing block instead of stacking a second one', () => {
+    const stale = `${COVERAGE_BLOCK_OPEN}\n<!-- backed by: nothing -->\n${COVERAGE_BLOCK_CLOSE}`
+    const out = applyCoverageBlock(`${FRONTMATTER}\n${stale}\n\n# Title\n`, block)
+    expect(out).toContain(block)
+    expect(out).not.toContain('backed by: nothing')
+    expect(out.split(COVERAGE_BLOCK_OPEN)).toHaveLength(2)
+  })
+
+  it('is idempotent', () => {
+    const once = applyCoverageBlock(`${FRONTMATTER}\n# T\n`, block)
+    expect(applyCoverageBlock(once, block)).toBe(once)
+  })
+
+  it('prepends when there is no frontmatter', () => {
+    expect(applyCoverageBlock('# T\n', block).startsWith(block)).toBe(true)
+  })
+
+  it('readCoverageBlock returns null for a file with no block', () => {
+    expect(readCoverageBlock(`${FRONTMATTER}\n# T\n`)).toBeNull()
+  })
+})
+
+// ── reconcileCoverageBlocks — --write / --check ─────────────────────────────
+
+describe('reconcileCoverageBlocks', () => {
+  /** Every rule file the temp root needs, so only the block state under test varies. */
+  function seedRuleFiles(body: (rule: string) => string): void {
+    for (const rule of RULE_NAMES) writeRuleFile(rule, body(rule))
+  }
+
+  it('--write inserts a block into every rule file', () => {
+    seedRuleFiles(() => `${FRONTMATTER}\n# T\n`)
+    const { failures, notes } = reconcileCoverageBlocks(dir, 'write')
+    expect(failures).toEqual([])
+    expect(notes).toHaveLength(RULE_NAMES.length)
+    const text = readFileSync(resolve(dir, 'agent/rules/basalt-controls.md'), 'utf8')
+    expect(text).toContain(coverageBlock('controls'))
+  })
+
+  it('--write is idempotent — a second run reports unchanged and rewrites nothing', () => {
+    seedRuleFiles(() => `${FRONTMATTER}\n# T\n`)
+    reconcileCoverageBlocks(dir, 'write')
+    const before = readFileSync(resolve(dir, 'agent/rules/basalt-controls.md'), 'utf8')
+    const { notes } = reconcileCoverageBlocks(dir, 'write')
+    expect(notes.every((n) => n.endsWith('unchanged'))).toBe(true)
+    expect(readFileSync(resolve(dir, 'agent/rules/basalt-controls.md'), 'utf8')).toBe(before)
+  })
+
+  it('--check passes once the blocks are written', () => {
+    seedRuleFiles(() => `${FRONTMATTER}\n# T\n`)
+    reconcileCoverageBlocks(dir, 'write')
+    expect(reconcileCoverageBlocks(dir, 'check').failures).toEqual([])
+  })
+
+  // The wave-6 requirement: the blocks are inserted by the agent-layer wave, and a gate that failed
+  // before they exist would have to land disabled — which is how a gate stays disabled.
+  it('--check REPORTS a file with no block yet, and does not fail it', () => {
+    seedRuleFiles(() => `${FRONTMATTER}\n# T\n`)
+    const { failures, notes } = reconcileCoverageBlocks(dir, 'check')
+    expect(failures).toEqual([])
+    expect(notes).toHaveLength(RULE_NAMES.length)
+    expect(notes[0]).toContain('no <!-- basalt:coverage --> block yet')
+  })
+
+  it('--check FAILS a block that disagrees with SURFACES', () => {
+    seedRuleFiles(() => `${FRONTMATTER}\n# T\n`)
+    reconcileCoverageBlocks(dir, 'write')
+    const path = resolve(dir, 'agent/rules/basalt-controls.md')
+    writeFileSync(path, readFileSync(path, 'utf8').replace('basalt/hand-rolled-filter', 'basalt/x'))
+    const { failures } = reconcileCoverageBlocks(dir, 'check')
+    expect(failures).toHaveLength(1)
+    expect(failures[0]).toContain('basalt-controls.md')
+  })
+
+  it('skips a missing rule file — assertion 2 already reports that', () => {
+    expect(reconcileCoverageBlocks(dir, 'check')).toEqual({ failures: [], notes: [] })
+  })
+})
+
+// ── the registry itself ─────────────────────────────────────────────────────
+
+describe('SURFACES.pluginRules', () => {
+  it('is required on every doctrine surface — [] is legal, absent is not', () => {
+    for (const [key, spec] of Object.entries(SURFACES)) {
+      if (spec.kind !== 'doctrine') continue
+      expect([key, Array.isArray(spec.pluginRules)]).toEqual([key, true])
+    }
+  })
+})
+
+describe('SURFACES.guardKinds — assertion 11', () => {
+  // The twin of assertion 9 for the text lane. Two wave-6 kinds shipped on no surface at all, so
+  // `basalt-controls.md` printed "guard kinds — none" while the guard was scanning for
+  // `raw-selection-control` — a generated header claiming less coverage than exists is D8 in the
+  // other direction, and it cannot be hand-corrected.
+  it('places every GUARD_RULES kind on at least one doctrine surface', () => {
+    const surfaced = new Set<string>()
+    for (const spec of Object.values(SURFACES)) {
+      if (spec.kind !== 'doctrine') continue
+      for (const kind of spec.guardKinds) surfaced.add(kind)
+    }
+    const orphans = Object.keys(GUARD_RULES).filter((kind) => !surfaced.has(kind))
+    expect(orphans).toEqual([])
+  })
+
+  it('names the two wave-6 control kinds on the surfaces whose headers must claim them', () => {
+    expect(coverageFor('controls').guardKinds).toContain('raw-selection-control')
+    expect(coverageFor('mantine').guardKinds).toContain('in-body-page-title')
+  })
+})

package/src/cli/check-theme.test.ts

@@ -84,7 +84,7 @@ describe('check-theme raw-surface', () => {
 
   it('does NOT flag a line carrying a theme-allow comment', () => {
     fixture(
-      `export const C = () => <div style={{ borderRadius: 8 }} /> // theme-allow: legacy widget\n`,
+      `export const C = () => <div style={{ borderRadius: 8 }} /> // theme-allow raw-surface — legacy widget\n`,
     )
     const { code, err } = run()
     expect(code).toBe(0)
@@ -110,10 +110,11 @@ describe('check-theme raw-surface', () => {
   })
 
   it('does NOT flag a var(--…) boxShadow token (regression)', () => {
-    fixture(`export const C = () => <div style={{ boxShadow: 'var(--mantine-shadow-sm)' }} />\n`)
+    fixture(`export const C = () => <div style={{ boxShadow: 'var(--vx-shadow-card)' }} />\n`)
     const { code, err } = run()
     expect(code).toBe(0)
     expect(err).not.toContain('raw-surface')
+    expect(err).not.toContain('surface-shadow-override')
   })
 
   it('does NOT flag a Mantine radius="md" prop (not inline surface styling)', () => {
@@ -216,7 +217,7 @@ describe('check-theme off-system-surface-var', () => {
 
   it('does NOT flag a line carrying a theme-allow comment', () => {
     fixture(
-      `export const C = () => <Box bg="var(--mantine-color-gray-3)" /> // theme-allow: legacy\n`,
+      `export const C = () => <Box bg="var(--mantine-color-gray-3)" /> // theme-allow off-system-surface-var — legacy\n`,
     )
     const { code, err } = run()
     expect(code).toBe(0)
@@ -266,7 +267,9 @@ describe('check-theme raw-html-layout', () => {
   })
 
   it('does NOT flag a line carrying a theme-allow comment', () => {
-    fixture(`export const C = () => <div style={{ display: 'flex' }} /> // theme-allow\n`)
+    fixture(
+      `export const C = () => <div style={{ display: 'flex' }} /> // theme-allow raw-html-layout inline-display — legacy\n`,
+    )
     const { code, err } = run()
     expect(code).toBe(0)
     expect(err).not.toContain('raw-html-layout')
@@ -377,7 +380,7 @@ describe('check-theme raw-visx-axis', () => {
   it('does NOT flag a chart-path <AxisLeft> carrying a theme-allow comment', () => {
     fixtureAt(
       'charts/kinds/Foo.tsx',
-      `export const Foo = () => <AxisLeft scale={s} /> // theme-allow: bespoke dual-panel\n`,
+      `export const Foo = () => <AxisLeft scale={s} /> // theme-allow raw-visx-axis — bespoke dual-panel\n`,
     )
     const { code, err } = run()
     expect(code).toBe(0)
@@ -490,7 +493,7 @@ describe('check-theme unframed-chart', () => {
   it('does NOT flag a line carrying a theme-allow comment', () => {
     fixtureAt(
       'charts/kinds/Foo.tsx',
-      `export const Foo = () => <ChartLegend items={[{ key: 'a', label: 'A' }]} /> // theme-allow: bespoke legend\n`,
+      `export const Foo = () => <ChartLegend items={[{ key: 'a', label: 'A' }]} /> // theme-allow unframed-chart — bespoke legend\n`,
     )
     const { code, err } = run()
     expect(code).toBe(0)
@@ -538,7 +541,9 @@ describe('check-theme raw-form-control', () => {
   })
 
   it('does NOT flag a line carrying a theme-allow comment', () => {
-    fixture(`export const C = () => <input type="text" /> // theme-allow: legacy widget\n`)
+    fixture(
+      `export const C = () => <input type="text" /> // theme-allow raw-form-control — legacy widget\n`,
+    )
     const { code, err } = run()
     expect(code).toBe(0)
     expect(err).not.toContain('raw-form-control')
@@ -563,34 +568,46 @@ describe('check-theme sub-16-input-font', () => {
     expect(err).toContain('sub-16-input-font')
   })
 
-  it('does NOT flag a fontSize below 16 on a <Text> (not a form control)', () => {
+  it('does NOT flag sub-16-input-font on a <Text> (not a form control)', () => {
+    // The literal itself is still a raw font-size, so `inline-font-size` (an independent kind,
+    // no `sub16InputFont` gate) reports it — only `sub-16-input-font`'s form-control scoping is
+    // under test here.
     fixture(`export const C = () => <Text style={{ fontSize: 12 }}>caption</Text>\n`)
     const { code, err } = run()
-    expect(code).toBe(0)
+    expect(code).toBe(1)
     expect(err).not.toContain('sub-16-input-font')
+    expect(err).toContain('inline-font-size')
   })
 
-  it('does NOT flag a fontSize below 16 on a <span> (not a form control)', () => {
+  it('does NOT flag sub-16-input-font on a <span> (not a form control)', () => {
+    // Same as the <Text> case above: `inline-font-size` fires independently of the form-control
+    // scoping this test verifies for `sub-16-input-font`.
     fixture(`export const C = () => <span style={{ fontSize: 11 }}>micro</span>\n`)
     const { code, err } = run()
-    expect(code).toBe(0)
+    expect(code).toBe(1)
     expect(err).not.toContain('sub-16-input-font')
+    expect(err).toContain('inline-font-size')
   })
 
   it('respects the sub16InputFont:false config knob', () => {
+    // `inline-font-size` has no config knob and fires on any raw literal regardless — only
+    // `sub-16-input-font` itself is under test here.
     fixture(`export const C = () => <input style={{ fontSize: 12 }} />\n`, {
       roots: ['src'],
       rawFormControl: false,
       sub16InputFont: false,
     })
     const { code, err } = run()
-    expect(code).toBe(0)
+    expect(code).toBe(1)
     expect(err).not.toContain('sub-16-input-font')
+    expect(err).toContain('inline-font-size')
   })
 
   it('does NOT flag a line carrying a theme-allow comment', () => {
+    // Names both kinds the literal can trip: sub-16-input-font (scoped by rawFormControl above)
+    // and inline-font-size (ungated, fires on the literal regardless of element).
     fixture(
-      `export const C = () => <input style={{ fontSize: 12 }} /> // theme-allow: legacy widget\n`,
+      `export const C = () => <input style={{ fontSize: 12 }} /> // theme-allow sub-16-input-font inline-font-size — legacy widget\n`,
       { roots: ['src'], rawFormControl: false },
     )
     const { code, err } = run()
@@ -646,11 +663,18 @@ describe('check-theme scans .css', () => {
   })
 
   it('does NOT false-positive a JSX-shaped rule on genuine CSS', () => {
-    fixtureAt('theme/controls.module.css', '.foo {\n  display: flex;\n  border-radius: 8px;\n}\n')
+    // `border-radius: 8px` is a genuine, unrelated `css-raw-surface` violation (a raw literal
+    // with no `--vx-radius-*` token) — the point of this test is that the JSX-shaped rules
+    // (`inline-display`, `raw-html-layout`) do not also fire on plain CSS syntax.
+    fixtureAt(
+      'theme/controls.module.css',
+      '.foo {\n  display: flex;\n  border-radius: var(--vx-radius-card);\n}\n',
+    )
     const { code, err } = run()
     expect(code).toBe(0)
     expect(err).not.toContain('inline-display')
     expect(err).not.toContain('raw-html-layout')
+    expect(err).not.toContain('css-raw-surface')
   })
 })