basalt-ui 1.27.0 → 1.28.0

package/src/cli/template-ledger.test.ts

@@ -1,219 +0,0 @@
-/**
- * Regression tests for the `classify()` ledger widening (see `./index.ts`'s `normalizeForLedger` +
- * `writeUnit` + `classify`).
- *
- * `writeUnit` now records a NORMALIZED hash in the manifest (instead of a raw one) for every sync
- * it performs, going forward — that closes the false-positive gap for any consumer whose manifest
- * entry was written by a CLI carrying this fix. But a manifest entry written by an OLDER
- * (pre-1.0.2) CLI holds a RAW hash — `classify`'s legacy path (`sha256(current) === manifestHash`)
- * exists to keep matching that raw entry directly, and it is faithfully exercised below by seeding
- * the manifest with a genuine `sha256(olderBlock)`, not `sha256(normalizeForLedger(olderBlock))`.
- *
- * Two scenarios collide differently against that raw legacy entry:
- *  - reformat ONLY (template body unchanged since the entry was written) → the same-version
- *    fallback (`normalizeForLedger(current) === normalizeForLedger(desired)`) still catches it,
- *    independent of the manifest hash → `unchanged`, healed silently, no `--force` — and the
- *    healing sync rewrites the manifest with the NORMALIZED hash, closing the gap for good for
- *    that consumer.
- *  - reformat AND a cross-version word change (the CLI bin rename baked into the block's own
- *    prose) together → NONE of `classify`'s three paths match a raw legacy hash → `drifted`, a
- *    real transitional gap that needs one `--force` to heal. See the comment above the legacy-hash
- *    path in `classify` (`./index.ts`) for the documented tradeoff.
- *
- * Also proves the two pre-existing same-version guarantees still hold:
- *  2. a real word-level edit at the SAME version → still `drifted` → skipped without `--force`.
- *  3. reformatting + a real edit together → still `drifted`.
- */
-import { afterEach, beforeEach, describe, expect, it } from 'bun:test'
-import { createHash } from 'node:crypto'
-import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
-import { tmpdir } from 'node:os'
-import { join, resolve } from 'node:path'
-
-import { init, MANIFEST_PATH, normalizeForLedger, sync } from './index.ts'
-
-function sha256(text: string): string {
-  return createHash('sha256').update(text, 'utf8').digest('hex')
-}
-
-let dir: string
-
-function read(relPath: string): string {
-  return readFileSync(join(dir, relPath), 'utf8')
-}
-
-function write(relPath: string, content: string): void {
-  writeFileSync(join(dir, relPath), content, 'utf8')
-}
-
-/** Captures both console.log and console.error — sync() reports drift on either depending on flags. */
-function capture(fn: () => number): { code: number; log: string } {
-  const originalLog = console.log
-  const originalError = console.error
-  let log = ''
-  console.log = (...args: unknown[]) => {
-    log += `${args.join(' ')}\n`
-  }
-  console.error = (...args: unknown[]) => {
-    log += `${args.join(' ')}\n`
-  }
-  try {
-    return { code: fn(), log }
-  } finally {
-    console.log = originalLog
-    console.error = originalError
-  }
-}
-
-function silenced<T>(fn: () => T): T {
-  const originalLog = console.log
-  const originalError = console.error
-  console.log = () => {}
-  console.error = () => {}
-  try {
-    return fn()
-  } finally {
-    console.log = originalLog
-    console.error = originalError
-  }
-}
-
-/**
- * The exact argo repro: lefthook's oxfmt inserted an EXTRA blank line after
- * `<!-- basalt:begin … -->` and another before `<!-- basalt:end -->` (a 35-line template rendered
- * as 37 lines post-oxfmt) — a pure formatting delta, zero word changes. Inserted unconditionally
- * (not just when absent) so the fixture reproduces the delta regardless of how many blank lines the
- * live template already ships around its markers.
- */
-function simulateOxfmtReformat(host: string): string {
-  const beginLineEnd = host.indexOf('\n', host.indexOf('<!-- basalt:begin')) + 1
-  const endMarkerStart = host.indexOf('<!-- basalt:end -->')
-  return (
-    host.slice(0, beginLineEnd) +
-    '\n' +
-    host.slice(beginLineEnd, endMarkerStart) +
-    '\n' +
-    host.slice(endMarkerStart)
-  )
-}
-
-beforeEach(() => {
-  dir = mkdtempSync(resolve(tmpdir(), 'basalt-ledger-'))
-  writeFileSync(join(dir, 'package.json'), JSON.stringify({ name: 'fixture' }))
-  silenced(() => init(dir))
-})
-
-afterEach(() => {
-  rmSync(dir, { recursive: true, force: true })
-})
-
-describe('classify ledger: cross-version format-only drift vs a real edit', () => {
-  it('a raw legacy manifest hash + reformat + a cross-version word change classifies drifted — the documented transitional gap, healed by one --force', () => {
-    const currentBlock = read('CLAUDE.md').trimEnd() // == today's desired (v1.0.1-shaped) block
-    expect(currentBlock).toContain('basalt-ui')
-
-    // Simulate the v1.0.0 body: genuinely different WORDS (the pre-rename bin name), not just an
-    // older version token — this is what makes the scenario cross-version, not same-version.
-    const olderBlock = currentBlock.replace(/basalt-ui/g, 'basalt')
-    expect(olderBlock).not.toBe(currentBlock)
-    expect(olderBlock).toContain('basalt sync')
-
-    // What a PRE-1.0.2 CLI's writeUnit actually recorded at that sync: a RAW hash of the exact
-    // bytes it wrote — the fix only normalizes hashes written by a CLI carrying it, so a genuine
-    // legacy manifest entry looks like this, not `sha256(normalizeForLedger(olderBlock))`.
-    const manifestHash = sha256(olderBlock)
-    write(
-      MANIFEST_PATH,
-      JSON.stringify(
-        { version: 1, basaltVersion: '1.0.0', files: { 'CLAUDE.md': manifestHash } },
-        null,
-        2,
-      ),
-    )
-
-    // What actually sits on disk: the older body, reformatted by the consumer's own lefthook
-    // oxfmt AFTER that older sync — the real argo repro shape.
-    const onDisk = simulateOxfmtReformat(olderBlock)
-    expect(onDisk).not.toBe(olderBlock)
-    write('CLAUDE.md', `${onDisk}\n`)
-
-    const { code, log } = capture(() => sync({}, dir))
-    expect(code).toBe(0)
-    // NOT healed — none of classify's three paths match a raw legacy hash once the words have
-    // also changed cross-version. This is the residual transitional gap documented on `classify`.
-    expect(read('CLAUDE.md')).toBe(`${onDisk}\n`)
-    expect(log).toContain('locally edited')
-
-    expect(silenced(() => sync({ check: true }, dir))).toBe(1)
-
-    // One --force heals it straight to the CURRENT (v1.0.1-shaped) rendering.
-    silenced(() => sync({ force: true }, dir))
-    expect(read('CLAUDE.md').trimEnd()).toBe(currentBlock)
-  })
-
-  it('a raw legacy manifest hash + reformat only (no word change) still classifies unchanged via the same-version fallback, heals without --force, and the manifest is rewritten with the normalized hash', () => {
-    const currentBlock = read('CLAUDE.md').trimEnd() // == today's desired block; body unchanged
-
-    // What a PRE-1.0.2 CLI's writeUnit recorded for THIS SAME body: a raw hash, not normalized.
-    const manifestHash = sha256(currentBlock)
-    write(
-      MANIFEST_PATH,
-      JSON.stringify(
-        { version: 1, basaltVersion: '1.0.0', files: { 'CLAUDE.md': manifestHash } },
-        null,
-        2,
-      ),
-    )
-
-    // What sits on disk: the SAME body, reformatted by the consumer's own lefthook oxfmt — no
-    // template-body change since the manifest entry was written.
-    const onDisk = simulateOxfmtReformat(currentBlock)
-    expect(onDisk).not.toBe(currentBlock)
-    write('CLAUDE.md', `${onDisk}\n`)
-
-    const { code, log } = capture(() => sync({}, dir))
-    expect(code).toBe(0)
-    // Healed straight to the current rendering, no --force needed: the same-version fallback
-    // (`normalizeForLedger(current) === normalizeForLedger(desired)`) matches regardless of what
-    // the manifest hash says.
-    expect(read('CLAUDE.md').trimEnd()).toBe(currentBlock)
-    expect(log).not.toContain('locally edited')
-
-    // The gap is now closed for good for this consumer: the healing sync rewrote the manifest
-    // entry with the NORMALIZED hash (writeUnit's form), not the raw legacy one.
-    const manifest = JSON.parse(read(MANIFEST_PATH)) as { files: Record<string, string> }
-    expect(manifest.files['CLAUDE.md']).toBe(sha256(normalizeForLedger(currentBlock)))
-
-    expect(silenced(() => sync({ check: true }, dir))).toBe(0)
-  })
-
-  it('a genuine word-level edit inside the block classifies drifted and is skipped without --force', () => {
-    const original = read('CLAUDE.md')
-    const edited = original.replace('React 19', 'React 18 (pinned by our team)')
-    expect(edited).not.toBe(original)
-    write('CLAUDE.md', edited)
-
-    const { code, log } = capture(() => sync({}, dir))
-    expect(code).toBe(0)
-    // Untouched — a real edit is never silently overwritten.
-    expect(read('CLAUDE.md')).toBe(edited)
-    expect(log).toContain('locally edited')
-
-    expect(silenced(() => sync({ check: true }, dir))).toBe(1)
-
-    silenced(() => sync({ force: true }, dir))
-    expect(read('CLAUDE.md')).toBe(original)
-  })
-
-  it('reformatting AND a real edit together still classifies drifted (whitespace normalization never masks word changes)', () => {
-    const original = read('CLAUDE.md')
-    const reformattedAndEdited = simulateOxfmtReformat(original).replace(
-      'React 19',
-      'React 18 (pinned by our team)',
-    )
-    write('CLAUDE.md', reformattedAndEdited)
-
-    expect(silenced(() => sync({ check: true }, dir))).toBe(1)
-    expect(read('CLAUDE.md')).toBe(reformattedAndEdited)
-  })
-})

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

@@ -1,249 +0,0 @@
-/**
- * `basalt-ui tokens:css` — the install-free path to the token system.
- *
- * The contract these tests hold is that the command holds no emission logic of its own: the token
- * VALUES it prints must be exactly what `buildPaletteCss` returns for the same options, or a
- * consumer who ran `bunx basalt-ui tokens:css` and one who imported `basalt-ui/tokens` would be
- * looking at two different design systems. What the command DOES add is file framing for an
- * artifact a consumer commits — the `@generated` header, a trailing newline, `rgba()` spacing —
- * which `body()` below strips before every comparison. See `./toolchain-wiring.test.ts` for the
- * framing's own tests.
- */
-import { afterEach, beforeEach, describe, expect, it } from 'bun:test'
-import { existsSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs'
-import { tmpdir } from 'node:os'
-import { join, resolve } from 'node:path'
-
-import { DEFAULT_GUARD_CONFIG, GENERATED_HEADER_LINE, checkSource } from '../guard'
-import { buildPaletteCss } from '../tokens'
-import { normalizeColorFunctions, run, tokensCss } from './index'
-
-const FIXTURE = join(import.meta.dir, '..', '..', 'tests', 'fixtures', 'palette-default.css')
-
-let dir: string
-
-beforeEach(() => {
-  dir = mkdtempSync(resolve(tmpdir(), 'basalt-tokens-css-'))
-  writeFileSync(resolve(dir, 'package.json'), JSON.stringify({ name: 'fixture' }))
-})
-
-afterEach(() => {
-  rmSync(dir, { recursive: true, force: true })
-})
-
-/** Run the command with `--out`, returning the written file — stdout is awkward to capture here. */
-function emit(flags: string[], out = 'out.css'): string {
-  const code = tokensCss([...flags, '--out', out], dir)
-  expect(code).toBe(0)
-  return readFileSync(resolve(dir, out), 'utf8')
-}
-
-/** The emitted file minus the two-line generated header and the trailing newline. */
-function body(flags: string[], out = 'out.css'): string {
-  return emit(flags, out).split('\n').slice(2).join('\n').replace(/\n$/, '')
-}
-
-/** What `buildPaletteCss` returns, in the CLI's commit-safe formatting. */
-function expected(opts: Parameters<typeof buildPaletteCss>[0]): string {
-  return normalizeColorFunctions(buildPaletteCss(opts))
-}
-
-describe('tokens:css', () => {
-  it('with no flags emits the shipped default, byte for byte under the header', () => {
-    expect(body([])).toBe(normalizeColorFunctions(readFileSync(FIXTURE, 'utf8')))
-  })
-
-  it('forwards the selector flags to buildPaletteCss and adds nothing of its own', () => {
-    const flags = ['--selector-attribute', 'data-theme', '--default-scheme', 'light']
-    expect(body(flags)).toBe(
-      expected({ scheme: { attribute: 'data-theme' }, defaultScheme: 'light' }),
-    )
-  })
-
-  it('forwards the scheme VALUES and the media fallback', () => {
-    const flags = ['--dark-value', 'night', '--light-value', 'day', '--media-fallback']
-    expect(body(flags)).toBe(
-      expected({ scheme: { darkValue: 'night', lightValue: 'day' }, mediaFallback: true }),
-    )
-  })
-
-  it('forwards --only core', () => {
-    expect(body(['--only', 'core'])).toBe(expected({ only: 'core' }))
-  })
-
-  it('rejects an unknown --only instead of silently emitting everything', () => {
-    expect(tokensCss(['--only', 'spacing', '--out', 'out.css'], dir)).toBe(1)
-    expect(existsSync(resolve(dir, 'out.css'))).toBe(false)
-  })
-
-  it('creates the parent directory of --out', () => {
-    const css = emit([], 'nested/deep/tokens.css')
-    expect(css).toContain(':root {')
-  })
-
-  it('rejects an unknown --default-scheme instead of silently defaulting', () => {
-    const code = tokensCss(['--default-scheme', 'sepia', '--out', 'out.css'], dir)
-    expect(code).toBe(1)
-    expect(existsSync(resolve(dir, 'out.css'))).toBe(false)
-  })
-
-  it('--no-legacy-aliases drops every deprecated camelCase spelling while the canonical kebab names still resolve', () => {
-    const css = emit(['--no-legacy-aliases'])
-    expect(css).not.toContain('--vx-accentFill')
-    expect(css).not.toContain('--vx-tooltipBg')
-    expect(css).not.toContain('--vx-fillHover-')
-    expect(css).not.toContain('--vx-goodSoft')
-    expect(css).not.toContain('Deprecated camelCase aliases')
-    expect(css).toContain('--vx-accent-fill:')
-    expect(css).toContain('--vx-tooltip-bg:')
-    expect(css).toContain('--vx-fill-hover-')
-    expect(css).toContain('--vx-good-soft:')
-  })
-
-  it('--no-legacy-aliases output is byte-identical to buildPaletteCss({ legacyAliases: false }) — the CLI holds no emission logic of its own', () => {
-    expect(body(['--no-legacy-aliases'])).toBe(expected({ legacyAliases: false }))
-  })
-
-  it('`--help` short-circuits before the command runs — no file written', () => {
-    const originalLog = console.log
-    let log = ''
-    console.log = (...args: unknown[]) => {
-      log += `${args.join(' ')}\n`
-    }
-    try {
-      expect(run(['tokens:css', '--out', 'out.css', '--help'], dir)).toBe(0)
-    } finally {
-      console.log = originalLog
-    }
-    expect(log).toContain('Usage: basalt')
-    expect(readdirSync(dir)).toEqual(['package.json'])
-  })
-})
-
-/**
- * `--check` gates the token VALUES and the provenance INVOCATION — only the version token is free.
- *
- * 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. 1.23.1 fixed that by blanking the whole of line 2 —
- * which is also the line carrying the exact invocation line 1 tells the reader to regenerate with.
- * rollhook's header was rewritten from `--only core --no-legacy-aliases` to `--only all
- * --with-legacy-aliases` and `--check` passed clean.
- *
- * Three-way contract, one test each below: a version-only change passes, a line-2 flag change
- * fails, a token drift fails.
- */
-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')
-    // Parsed, not asserted: the old sentence claimed "an older basalt-ui" without ever reading
-    // the token, so `0.0.1-nonsense` got the same claim. Both versions are named now.
-    expect(log).toContain('names basalt-ui 0.0.1, an older release than the')
-  })
-
-  it('calls a NEWER on-disk version newer — the old sentence said "older" either way', () => {
-    const lines = emit([]).split('\n')
-    lines[1] = (lines[1] as string).replace(/basalt-ui [\d.]+ —/, 'basalt-ui 999.0.0 —')
-    writeFileSync(resolve(dir, 'out.css'), lines.join('\n'))
-
-    const { code, log } = check('out.css')
-    expect(code).toBe(0)
-    expect(log).toContain('names basalt-ui 999.0.0, a newer release than the')
-    expect(log).not.toContain('an older release')
-  })
-
-  it('calls a same-triple prerelease merely different rather than ordering it', () => {
-    const lines = emit([]).split('\n')
-    const current = /basalt-ui (\d+\.\d+\.\d+)/.exec(lines[1] as string)?.[1] as string
-    lines[1] = (lines[1] as string).replace(`basalt-ui ${current} —`, `basalt-ui ${current}-rc.1 —`)
-    writeFileSync(resolve(dir, 'out.css'), lines.join('\n'))
-
-    const { code, log } = check('out.css')
-    expect(code).toBe(0)
-    expect(log).toContain(`names basalt-ui ${current}-rc.1, a different release than the`)
-  })
-
-  it('FAILS when line 2 names different flags — the invocation line 1 points at is gated', () => {
-    const emitted = emit([])
-    const lines = emitted.split('\n')
-    lines[1] = (lines[1] as string).replace(
-      '`basalt-ui tokens:css --out out.css`',
-      '`basalt-ui tokens:css --only all --with-legacy-aliases --out out.css`',
-    )
-    writeFileSync(resolve(dir, 'out.css'), lines.join('\n'))
-
-    const { code, log } = check('out.css')
-    expect(code).toBe(1)
-    expect(log).toContain('provenance line does not match the command that produced this content')
-    expect(log).toContain('--only all --with-legacy-aliases')
-  })
-
-  it('FAILS when the provenance line is deleted outright — a blank line is not a free pass', () => {
-    const lines = emit([]).split('\n')
-    lines[1] = ''
-    writeFileSync(resolve(dir, 'out.css'), lines.join('\n'))
-
-    expect(check('out.css').code).toBe(1)
-  })
-
-  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('STILL fails on token drift even when the version token ALSO differs', () => {
-    const lines = emit([]).replace('--vx-neutral', '--vx-neutrall').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'))
-    expect(check('out.css').code).toBe(1)
-  })
-
-  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` \*\/$/)
-  })
-
-  it('the emitted header is still guard-exempt — checkSource reports nothing in it', () => {
-    // The exemption requires line 1 verbatim AND line 2 parsing as the provenance line. `--check`
-    // now reads line 2 too, so the two shapes have to keep agreeing; this is the assertion that
-    // notices if the emitter drifts to satisfy the gate.
-    const emitted = emit([])
-    expect(checkSource(emitted, 'src/tokens.css', DEFAULT_GUARD_CONFIG)).toEqual([])
-  })
-})