basalt-ui 1.22.0 → 1.23.1

package/src/cli/shipped-versions.test.ts

@@ -0,0 +1,83 @@
+/**
+ * No shipped artifact may name a basalt version npm never served.
+ *
+ * Three rounds running, the newest `MIGRATING.md` heading named a phantom — `1.20.1` (shipped as
+ * 1.21.0), then `1.21.1` (shipped as 1.22.0) — because the docs pass runs BEFORE semantic-release
+ * computes the number, so whatever is written is a guess. That would be a docs problem alone if it
+ * stayed in docs. It does not: `sync` copies `agent/rules/**` and `agent/skills/**` verbatim into
+ * every consumer, so "Since 1.21.1" is currently shipped, as fact, into seven repos.
+ *
+ * This is the gate that ends it, and it is mechanical rather than editorial: every basalt-shaped
+ * version literal in a file a consumer receives must appear as a release heading in CHANGELOG.md —
+ * the one file `semantic-release` writes AFTER the number exists. A guessed version fails here
+ * before it can ship.
+ *
+ * Deliberately NOT a ban on version literals: `agent/rules/**` is release-history prose and
+ * "widened at 1.21.0, promoted at 1.22.0" is exactly the sentence a consumer needs. What it may
+ * not do is name a release that does not exist.
+ *
+ * The complementary half — no version stamped into a file nothing ever rewrites — lives in
+ * `toolchain-wiring.test.ts` ("DESIGN.md carries no version").
+ *
+ * Run: bun test packages/basalt-ui/src/cli/shipped-versions.test.ts
+ */
+import { readdirSync, readFileSync, statSync } from 'node:fs'
+import { join, relative, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'bun:test'
+
+const PKG_ROOT = fileURLToPath(new URL('../../', import.meta.url))
+
+/** Every version CHANGELOG.md records, plus the one package.json currently declares. */
+const RELEASED = new Set<string>([
+  ...(
+    readFileSync(resolve(PKG_ROOT, 'CHANGELOG.md'), 'utf8').match(/^#+\s*\[?(\d+\.\d+\.\d+)/gm) ??
+    []
+  ).map((h) => h.replace(/^#+\s*\[?/, '')),
+  (JSON.parse(readFileSync(resolve(PKG_ROOT, 'package.json'), 'utf8')) as { version: string })
+    .version,
+])
+
+/**
+ * basalt's own version line is 0.x / 1.x, so a literal with any other major belongs to a peer
+ * (visx 4.0.0, motion 12.42.0, the fontsource 5.2.x trio) and is none of this gate's business. A
+ * `^`/`~`/`@`-prefixed literal is a dependency RANGE for the same reason — `vite-plugin-pwa
+ * (^1.3.0)` shares a major with basalt and is still not a claim about basalt.
+ */
+const BASALT_VERSION_LITERAL = /(^|[^-~^@\w.])([01]\.\d+\.\d+)(?![\w.])/g
+
+function versionsIn(content: string): string[] {
+  return [...content.matchAll(BASALT_VERSION_LITERAL)].map((m) => m[2] as string)
+}
+
+/** Every file under `dir`, recursively. */
+function filesUnder(dir: string): string[] {
+  return readdirSync(dir).flatMap((name) => {
+    const abs = join(dir, name)
+    return statSync(abs).isDirectory() ? filesUnder(abs) : [abs]
+  })
+}
+
+// Everything `init`/`sync` place in a consumer repo, plus the presets they `extends` into.
+const SHIPPED = [
+  ...filesUnder(resolve(PKG_ROOT, 'agent')),
+  resolve(PKG_ROOT, 'configs/check.yml'),
+  resolve(PKG_ROOT, 'configs/lefthook.yml'),
+]
+
+describe('shipped agent assets name only versions that exist', () => {
+  it.each(SHIPPED.map((abs) => [relative(PKG_ROOT, abs), abs] as const))(
+    '%s',
+    (_rel, abs: string) => {
+      const unreleased = [...new Set(versionsIn(readFileSync(abs, 'utf8')))].filter(
+        (v) => !RELEASED.has(v),
+      )
+      expect(unreleased).toEqual([])
+    },
+  )
+
+  it('reads a real changelog, so an empty RELEASED set can never make this vacuous', () => {
+    expect(RELEASED.size).toBeGreaterThan(20)
+    expect(RELEASED.has('1.21.1')).toBe(false)
+  })
+})

package/src/cli/tokens-css.test.ts

@@ -14,6 +14,7 @@ import { existsSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSy
 import { tmpdir } from 'node:os'
 import { join, resolve } from 'node:path'
 
+import { GENERATED_HEADER_LINE } from '../guard'
 import { buildPaletteCss } from '../tokens'
 import { normalizeColorFunctions, run, tokensCss } from './index'
 
@@ -118,3 +119,64 @@ describe('tokens:css', () => {
     expect(readdirSync(dir)).toEqual(['package.json'])
   })
 })
+
+/**
+ * `--check` gates the token VALUES, never the provenance line.
+ *
+ * Line 2 of the generated header carries the emitting version, and `--check` used to compare the
+ * whole file byte for byte — so every basalt-ui release forced a mandatory no-op commit in every
+ * consumer that commits a generated sheet: regenerate, one line moves, nothing else, ship it. That
+ * is the rot pattern removed from DESIGN.md this cycle, on a file whose gate is byte-equality.
+ */
+describe('tokens:css --check and the provenance line', () => {
+  /** Capture stdout/stderr so the check's own sentence can be asserted. */
+  function check(out: string): { code: number; log: string } {
+    const originalLog = console.log
+    const originalError = console.error
+    let log = ''
+    const sink = (...args: unknown[]) => {
+      log += `${args.join(' ')}\n`
+    }
+    console.log = sink
+    console.error = sink
+    try {
+      return { code: tokensCss(['--check', '--out', out], dir), log }
+    } finally {
+      console.log = originalLog
+      console.error = originalError
+    }
+  }
+
+  it('passes when only the emitting VERSION on line 2 differs', () => {
+    const emitted = emit([])
+    const lines = emitted.split('\n')
+    lines[1] = (lines[1] as string).replace(/basalt-ui [\d.]+/, 'basalt-ui 0.0.1')
+    writeFileSync(resolve(dir, 'out.css'), lines.join('\n'))
+
+    const { code, log } = check('out.css')
+    expect(code).toBe(0)
+    expect(log).toContain('is up to date')
+    expect(log).toContain('provenance line still names an older basalt-ui')
+  })
+
+  it('says nothing about provenance when the file is byte-identical', () => {
+    emit([])
+    const { code, log } = check('out.css')
+    expect(code).toBe(0)
+    expect(log).not.toContain('provenance line')
+  })
+
+  it('STILL fails when a token value actually moved', () => {
+    const emitted = emit([])
+    writeFileSync(resolve(dir, 'out.css'), emitted.replace('--vx-neutral', '--vx-neutrall'))
+    const { code, log } = check('out.css')
+    expect(code).toBe(1)
+    expect(log).toContain('differs from what')
+  })
+
+  it('the header itself is unchanged — the `@generated` exemption needs both lines verbatim', () => {
+    const lines = emit([]).split('\n')
+    expect(lines[0]).toBe(GENERATED_HEADER_LINE)
+    expect(lines[1]).toMatch(/^\/\* basalt-ui [\d.]+ — `basalt-ui tokens:css --out out\.css` \*\/$/)
+  })
+})

package/src/cli/toolchain-wiring.test.ts

@@ -344,7 +344,7 @@ describe('check-theme — finds the config a root-invoked hook cannot see', () =
   it('reports ambiguity rather than guessing when two packages carry a config', () => {
     ambiguousWorkspace()
     const { code, log } = capture(() => checkTheme(dir))
-    expect(log).toContain('2 workspace packages carry one')
+    expect(log).toContain('2 packages below it carry one')
     expect(log).toContain('BASALT_CWD')
     expect(code).toBe(1)
   })
@@ -363,7 +363,7 @@ describe('doctor — an ambiguous project is terminal, exactly as it is for chec
   it('short-circuits instead of running every check against the wrong root', () => {
     ambiguousWorkspace()
     const { code, log } = capture(() => doctor(dir))
-    expect(log).toContain('2 workspace packages carry one')
+    expect(log).toContain('2 packages below it carry one')
     expect(log).toContain('BASALT_CWD')
     expect(code).toBe(1)
     // The bug this pins shut: falling back to the invocation cwd ran the remaining checks against
@@ -381,7 +381,7 @@ describe('doctor — an ambiguous project is terminal, exactly as it is for chec
   it('still runs normally once BASALT_CWD picks a package', () => {
     ambiguousWorkspace()
     const { code, log } = capture(() => doctor(join(dir, 'apps/a')))
-    expect(log).not.toContain('workspace packages carry one')
+    expect(log).not.toContain('packages below it carry one')
     expect(code).toBe(1) // no install / no manifest there — but the checks RAN
     expect(log).toContain('guard-scan')
   })
@@ -945,7 +945,7 @@ describe('sync — a scaffold is init’s decision, never a drift refresh’s',
     ambiguousWorkspace()
     const { code, log } = capture(() => sync({}, dir))
     expect(code).toBe(1)
-    expect(log).toContain('2 workspace packages carry one')
+    expect(log).toContain('2 packages below it carry one')
     expect(log).toContain('BASALT_CWD')
   })
 
@@ -1043,3 +1043,170 @@ describe('doctor — exit status per outcome, not per printed string', () => {
     expect(capture(() => doctor(dir, ['--tokens-only', '--framework'])).code).toBe(1)
   })
 })
+
+// ── the project resolver, for a repo that declares no workspaces ───────────────────────────────
+//
+// linewatch keeps its whole basalt consumer in `web/` and declares no `workspaces` field anywhere.
+// Measured at its repo root, all three project-scoped commands got that wrong in a different way:
+// `check-theme` printed `✓ no off-palette colors` having scanned ZERO files, `doctor` inferred
+// `tokens-only` for a full Mantine consumer, and `sync` refused while naming `basalt-ui init` as
+// the remedy — the one command that WOULD have written a competing install at the root. The
+// workspace-declaration path already handled image-share's `apps/admin`; nothing handled this.
+
+/** linewatch's shape: no `workspaces` field, the whole consumer one directory down. */
+function undeclaredChild(child = 'web'): void {
+  write('package.json', JSON.stringify({ name: 'root' }))
+  write(`${child}/package.json`, JSON.stringify({ name: child, basalt: { roots: ['src'] } }))
+  write(`${child}/src/app.tsx`, "export const c = '#ff0000'\n")
+  write(join(child, MANIFEST_PATH), JSON.stringify({ version: 1, files: {} }))
+}
+
+describe('resolveProjectDir — a repo that declares no workspaces still has a layout', () => {
+  it('sync relocates into the undeclared child instead of refusing with init as the advice', () => {
+    undeclaredChild()
+    const { log } = capture(() => sync({ check: true }, dir))
+    expect(log).toContain('running in ./web, where it lives')
+    expect(log).not.toContain('basalt-ui init')
+  })
+
+  it('sync writes NOTHING at the root it was invoked from', () => {
+    undeclaredChild()
+    capture(() => sync({}, dir))
+    expect(readdirSync(dir).toSorted()).toEqual(['package.json', 'web'])
+    expect(readPkg()['basalt']).toBeUndefined()
+  })
+
+  it('check-theme scans the child rather than reporting green over zero files', () => {
+    undeclaredChild()
+    const { code, log } = capture(() => checkTheme(dir, []))
+    expect(log).toContain('running in ./web, where it lives')
+    expect(log).not.toContain('no off-palette colors')
+    expect(code).toBe(1)
+  })
+
+  it('doctor reports on the child, so it cannot infer tokens-only from the empty root', () => {
+    undeclaredChild()
+    const { log } = capture(() => doctor(dir, []))
+    expect(log).toContain(join(dir, 'web'))
+    expect(log).not.toContain('profile: tokens-only')
+  })
+
+  it('two undeclared children are ambiguous, named, and never guessed between', () => {
+    undeclaredChild('web')
+    undeclaredChild('admin')
+    const { code, log } = capture(() => sync({}, dir))
+    expect(code).toBe(1)
+    expect(log).toContain('2 packages below it carry one')
+    expect(log).toContain('./admin')
+    expect(log).toContain('./web')
+    expect(readdirSync(dir)).not.toContain('DESIGN.md')
+  })
+
+  it('a declared workspaces field still wins — the layout scan is a fallback, not a union', () => {
+    // `stray/` carries a basalt key but is not a workspace package. Treating both as candidates
+    // would turn a working single-candidate repo into an ambiguity error on upgrade.
+    write('package.json', JSON.stringify({ name: 'root', workspaces: ['apps/*'] }))
+    write('apps/web/package.json', JSON.stringify({ name: 'web', basalt: { roots: ['src'] } }))
+    write('apps/web/src/app.tsx', 'export const App = () => null\n')
+    write(join('apps/web', MANIFEST_PATH), JSON.stringify({ version: 1, files: {} }))
+    write('stray/package.json', JSON.stringify({ name: 'stray', basalt: { roots: ['src'] } }))
+    const { log } = capture(() => sync({ check: true }, dir))
+    expect(log).toContain('running in ./apps/web, where it lives')
+  })
+})
+
+// ── sync honours the profile doctor already reads ──────────────────────────────────────────────
+//
+// rollhook is tokens-only in both apps and declares it. `sync` told it to run `basalt-ui init` —
+// the exact advice `doctor`, in the same directory at the same version, exists to prevent — and
+// exited 1, which also put `sync --check` out of reach of the one CI drift gate every other
+// consumer runs.
+
+describe('sync — tokens-only is a pass, not a refusal', () => {
+  function tokensOnly(): void {
+    write(
+      'package.json',
+      JSON.stringify({ name: 'marketing', basalt: { roots: ['src'], profile: 'tokens-only' } }),
+    )
+    write('src/app.ts', 'export const c = 1\n')
+  }
+
+  it('reports n/a and exits 0, mirroring doctor’s manifest row', () => {
+    tokensOnly()
+    const { code, log } = capture(() => sync({}, dir))
+    expect(code).toBe(0)
+    expect(log).toContain('n/a — a tokens-only consumer has no scaffold to reconcile')
+    expect(log).not.toContain('basalt-ui init')
+  })
+
+  it('is wirable into CI: --check exits 0 instead of failing on a scaffold it must not have', () => {
+    tokensOnly()
+    expect(capture(() => sync({ check: true, flags: [] }, dir)).code).toBe(0)
+  })
+
+  it('writes nothing — no manifest, no DESIGN.md, no basalt.roots backfill', () => {
+    tokensOnly()
+    capture(() => sync({}, dir))
+    expect(readdirSync(dir).toSorted()).toEqual(['package.json', 'src'])
+  })
+
+  it('--framework forces the full profile back on', () => {
+    tokensOnly()
+    const { code, log } = capture(() => sync({ flags: ['--framework'] }, dir))
+    expect(code).toBe(1)
+    expect(log).toContain('refusing to scaffold')
+  })
+
+  it('contradictory profile flags exit 1, exactly as they do for check-theme and doctor', () => {
+    tokensOnly()
+    expect(capture(() => sync({ flags: ['--tokens-only', '--framework'] }, dir)).code).toBe(1)
+  })
+})
+
+// ── no shipped artifact carries a version number that goes stale ───────────────────────────────
+//
+// `DESIGN.md` is a seed: written once at init, then consumer-owned and never reconciled. Its
+// opener stamped `{{BASALT_VERSION}}`, so across the seven consumers the same line read 1.0.0,
+// 1.9.0, 1.21.0 and 1.22.0 under an identical 1.22.0 install — reported three rounds running as
+// four separate doc bugs. It was one bug: a version number in a file nothing ever rewrites.
+
+describe('DESIGN.md carries no version, and sync heals the ones already written', () => {
+  function seeded(): void {
+    write('package.json', JSON.stringify({ name: 'fixture', basalt: { roots: ['src'] } }))
+    write('src/app.tsx', 'export const App = () => null\n')
+    capture(() => init(dir))
+  }
+
+  it('a fresh scaffold stamps no version at all', () => {
+    seeded()
+    expect(read('DESIGN.md')).not.toMatch(/Managed by basalt-ui \(\d+\.\d+\.\d+\)/)
+    expect(read('DESIGN.md')).toContain('run `basalt-ui doctor` for the version')
+  })
+
+  it('sync rewrites a stale opener in place and leaves the rest of the file alone', () => {
+    seeded()
+    const consumerOwned = '\n## Series\n\nOurs: hrv, rhr.\n'
+    write('DESIGN.md', `# app — Design\n\n> Managed by basalt-ui (1.9.0). Thin.\n${consumerOwned}`)
+    capture(() => sync({}, dir))
+    expect(read('DESIGN.md')).toContain(
+      '> Managed by basalt-ui — run `basalt-ui doctor` for the version. Thin.',
+    )
+    expect(read('DESIGN.md')).toContain(consumerOwned)
+  })
+
+  it('--check writes nothing, including the heal', () => {
+    seeded()
+    const stale = '# app — Design\n\n> Managed by basalt-ui (1.9.0). Thin.\n'
+    write('DESIGN.md', stale)
+    capture(() => sync({ check: true }, dir))
+    expect(read('DESIGN.md')).toBe(stale)
+  })
+
+  it('leaves an opener the consumer already rewrote by hand untouched', () => {
+    seeded()
+    const owned = '# app — Design\n\n> Our own words entirely.\n'
+    write('DESIGN.md', owned)
+    capture(() => sync({}, dir))
+    expect(read('DESIGN.md')).toBe(owned)
+  })
+})

package/src/cli/waiver-audit.test.ts

@@ -104,11 +104,15 @@ describe('check-theme --audit-allows — theme-allow annotations', () => {
   })
 
   it('names the scope it audited, so "0 dead" is never read as "0 dead anywhere"', () => {
-    // The audit reads exactly what check-theme reads. A waiver in a file outside `basalt.roots` is
-    // invisible to it — not because it is fine, but because nothing scanned it.
+    // The audit reads exactly what check-theme reads, and that is WIDER than `basalt.roots` — two
+    // consumers reported a live `public/site.webmanifest` waiver under a scope line claiming
+    // files outside roots are not audited. The line has to name every class the scan reaches, or
+    // it is a second false statement in the sentence that exists to prevent one.
     fixture("export const c = '#ff0000' // theme-allow raw-hex — brand literal\n")
     const { log } = audit()
-    expect(log).toContain('Scope: the 1 file(s) check-theme scans under basalt.roots (src)')
+    expect(log).toContain('Scope: the 1 file(s) check-theme scans — everything under basalt.roots')
+    expect(log).toContain('sibling index.html and public/ tree')
+    expect(log).toContain('basalt.include')
   })
 
   it('marks an unaccountable waiver while still reporting what it covers', () => {