basalt-ui 1.27.0 → 1.28.0

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

@@ -1,215 +0,0 @@
-/**
- * `check-theme --audit-allows` — the accountability half of the escape hatch.
- *
- * 1.20.0 shipped `theme-allow-unscoped`, which reports a waiver that names no rule. It cannot see
- * the other failure: a perfectly well-written waiver whose finding no longer exists. Two consumers
- * found five of those by hand — editing the token out and re-running the guard — and that manual
- * method is what this command automates, which is why every assertion below is about a VERDICT
- * derived from re-running the scan, never from parsing the annotation's text.
- *
- * Run: bun test packages/basalt-ui/src/cli/waiver-audit.test.ts
- */
-import { afterEach, beforeEach, describe, expect, it } from 'bun:test'
-import {
-  existsSync,
-  mkdirSync,
-  mkdtempSync,
-  readdirSync,
-  rmSync,
-  symlinkSync,
-  writeFileSync,
-} from 'node:fs'
-import { tmpdir } from 'node:os'
-import { join, resolve } from 'node:path'
-import { fileURLToPath } from 'node:url'
-
-import { checkTheme } from './index.ts'
-
-const PKG_ROOT = fileURLToPath(new URL('../../', import.meta.url))
-
-let dir: string
-
-function write(relPath: string, content: string): void {
-  const abs = join(dir, relPath)
-  mkdirSync(resolve(abs, '..'), { recursive: true })
-  writeFileSync(abs, content, 'utf8')
-}
-
-function audit(): { 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: checkTheme(dir, ['--audit-allows']), log }
-  } finally {
-    console.log = originalLog
-    console.error = originalError
-  }
-}
-
-/** A repo whose only source file is the one under test. */
-function fixture(source: string, basalt: Record<string, unknown> = {}): void {
-  write('package.json', JSON.stringify({ name: 'fixture', basalt: { roots: ['src'], ...basalt } }))
-  write('src/app.tsx', source)
-}
-
-beforeEach(() => {
-  dir = mkdtempSync(resolve(tmpdir(), 'basalt-audit-'))
-})
-
-afterEach(() => {
-  rmSync(dir, { recursive: true, force: true })
-})
-
-describe('check-theme --audit-allows — theme-allow annotations', () => {
-  it('names what a live waiver still suppresses, and exits 0', () => {
-    fixture("export const c = '#ff0000' // theme-allow raw-hex — a deliberate brand literal\n")
-    const { code, log } = audit()
-    expect(log).toContain('suppresses raw-hex@1')
-    expect(code).toBe(0)
-  })
-
-  it('calls a waiver over a line with no finding DEAD, and exits 1', () => {
-    fixture('export const c = 1 // theme-allow raw-hex — nothing here fires any more\n')
-    const { code, log } = audit()
-    expect(log).toContain('SUPPRESSES NOTHING')
-    expect(code).toBe(1)
-  })
-
-  it('does not report prose that merely mentions the token', () => {
-    // The guard stopped treating a mid-comment mention as an annotation for exactly this reason;
-    // an audit that listed them as dead waivers would send someone editing documentation.
-    fixture('// Waive it with a `theme-allow raw-hex — why` comment.\nexport const c = 1\n')
-    const { code, log } = audit()
-    expect(log).toContain('annotations (0)')
-    expect(code).toBe(0)
-  })
-
-  it('says oxlint could not be run rather than calling a plugin-rule waiver dead', () => {
-    // `hand-rolled-plot` lives in the plugin, so `checkSource` can never see what it suppresses.
-    // With no oxlint reachable from the fixture the honest answer is "cannot judge" — reporting
-    // "delete it" here would be the command telling someone to remove a live waiver.
-    fixture(
-      '// theme-allow hand-rolled-plot — DualPanel is not a single cartesian plot\nexport const c = 1\n',
-    )
-    const { code, log } = audit()
-    expect(log).toContain('oxlint could not be run here')
-    expect(log).not.toContain('SUPPRESSES NOTHING')
-    expect(code).toBe(0)
-  })
-
-  it('names the scope it audited, so "0 dead" is never read as "0 dead anywhere"', () => {
-    // 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 — 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', () => {
-    fixture("export const c = '#ff0000' // theme-allow\n")
-    const { log } = audit()
-    expect(log).toContain('suppresses raw-hex@1')
-    expect(log).toContain('no rule id')
-    expect(log).toContain('1 unaccountable')
-  })
-})
-
-describe('check-theme --audit-allows — basalt.exemptRules', () => {
-  it('prints the reason from the object form, and says so when there is none', () => {
-    fixture("export const c = '#ff0000'\n", {
-      exemptRules: { 'raw-hex': { paths: ['src'], reason: 'a vendor asset basalt does not own' } },
-    })
-    const { log } = audit()
-    expect(log).toContain('a vendor asset basalt does not own')
-    expect(log).toContain('suppresses findings in src/app.tsx')
-
-    fixture("export const c = '#ff0000'\n", { exemptRules: { 'raw-hex': ['src'] } })
-    expect(audit().log).toContain('[no reason recorded]')
-  })
-
-  it('the object form really does exempt — the reason is accountability, not a second config', () => {
-    fixture("export const c = '#ff0000'\n", {
-      exemptRules: { 'raw-hex': { paths: ['src'], reason: 'a vendor asset basalt does not own' } },
-    })
-    expect(checkTheme(dir, [])).toBe(0)
-  })
-
-  it('reports a pattern that matches no scanned file as dead, and exits 1', () => {
-    // rollhook wrote a real, correct relative path, it matched nothing, and nothing said so — the
-    // finding kept failing the build with the config sitting right there looking like the answer.
-    fixture("export const c = '#ff0000'\n", { exemptRules: { 'raw-hex': ['does-not-exist'] } })
-    const { code, log } = audit()
-    expect(log).toContain('matches no scanned file')
-    expect(code).toBe(1)
-  })
-})
-
-// ── the oxlint half ───────────────────────────────────────────────────────────────────────────
-//
-// The `error`-severity design rules live in the oxlint plugin, not in `checkSource`. Until this,
-// the audit declined to judge them — 8 of 8 annotations in argo, 11 of 14 in linewatch — so the
-// exit-1 gate covered an empty set. These prove the method generalizes: neutralize the annotation,
-// re-run oxlint over that one file, and the findings that appear are what it covers.
-
-const REPO_ROOT = resolve(PKG_ROOT, '../..')
-const OXLINT_BIN = resolve(REPO_ROOT, 'node_modules/.bin/oxlint')
-
-/** Make oxlint reachable from the fixture and point it at the shipped preset (plugin included). */
-function withOxlint(): void {
-  mkdirSync(join(dir, 'node_modules/.bin'), { recursive: true })
-  symlinkSync(OXLINT_BIN, join(dir, 'node_modules/.bin/oxlint'))
-  write('.oxlintrc.json', JSON.stringify({ extends: [resolve(PKG_ROOT, 'configs/oxlint.json')] }))
-}
-
-describe.skipIf(!existsSync(OXLINT_BIN))('check-theme --audit-allows — oxlint plugin rules', () => {
-  it('proves a plugin-rule waiver LIVE, naming the rule and the line it covers', () => {
-    write('package.json', JSON.stringify({ name: 'fixture', basalt: { roots: ['src'] } }))
-    write(
-      'src/charts/plot.tsx',
-      "import { AxisLeftNumeric } from 'basalt-ui/charts'\n\n" +
-        '// theme-allow hand-rolled-plot — this pane is not a single cartesian plot\n' +
-        'export const Plot = () => <AxisLeftNumeric />\n',
-    )
-    withOxlint()
-    const { code, log } = audit()
-    expect(log).toContain('suppresses hand-rolled-plot@4 (oxlint)')
-    expect(code).toBe(0)
-  })
-
-  it('calls a plugin-rule waiver over nothing DEAD, and exits 1 — the gate now covers them', () => {
-    write('package.json', JSON.stringify({ name: 'fixture', basalt: { roots: ['src'] } }))
-    write(
-      'src/charts/plot.tsx',
-      '// theme-allow hand-rolled-plot — this pane is not a single cartesian plot\n' +
-        'export const Plot = () => null\n',
-    )
-    withOxlint()
-    const { code, log } = audit()
-    expect(log).toContain('SUPPRESSES NOTHING')
-    expect(log).toContain('re-running oxlint')
-    expect(code).toBe(1)
-  })
-
-  it('leaves no probe file behind — the neutralized copy is a temp file basalt owns', () => {
-    write('package.json', JSON.stringify({ name: 'fixture', basalt: { roots: ['src'] } }))
-    write(
-      'src/charts/plot.tsx',
-      "import { AxisLeftNumeric } from 'basalt-ui/charts'\n\n" +
-        '// theme-allow hand-rolled-plot — this pane is not a single cartesian plot\n' +
-        'export const Plot = () => <AxisLeftNumeric />\n',
-    )
-    withOxlint()
-    audit()
-    expect(readdirSync(join(dir, 'src/charts'))).toEqual(['plot.tsx'])
-  })
-})

package/src/content/article-actions.test.ts

@@ -1,78 +0,0 @@
-import { describe, expect, test } from 'bun:test'
-import { toArticleActions } from './article-actions'
-import type { Article } from './article-model'
-
-const ARTICLE: Article = {
-  slug: 'reading-dashboards',
-  title: 'Reading dashboards',
-  description: 'Why most internal dashboards fail the five-second glance test.',
-  category: 'guide',
-  tags: ['dashboards', 'ux'],
-}
-
-describe('toArticleActions', () => {
-  test('projects id/label/description/keywords', () => {
-    const [action] = toArticleActions([ARTICLE], {
-      onNavigate: () => {},
-      href: () => '/content',
-    })
-
-    expect(action?.id).toBe('article:/content')
-    expect(action?.label).toBe('Reading dashboards')
-    expect(action?.description).toBe(ARTICLE.description)
-    expect(action?.keywords).toBe(
-      'Reading dashboards Why most internal dashboards fail the five-second glance test. guide dashboards ux reading-dashboards',
-    )
-  })
-
-  test('lands tags and category in keywords', () => {
-    const [action] = toArticleActions([ARTICLE], {
-      onNavigate: () => {},
-      href: () => '/content',
-    })
-
-    expect(action?.keywords).toContain('guide')
-    expect(action?.keywords).toContain('dashboards')
-    expect(action?.keywords).toContain('ux')
-  })
-
-  test('onClick calls onNavigate with the href fn output', () => {
-    const navigated: string[] = []
-    const [action] = toArticleActions([ARTICLE], {
-      onNavigate: (href) => navigated.push(href),
-      href: (article) => `/articles/${article.slug}`,
-    })
-
-    // onClick's declared type takes a MouseEvent, but the implementation ignores it — call
-    // through a zero-arg view rather than fabricating a fake event.
-    const onClick = action?.onClick as (() => void) | undefined
-    onClick?.()
-    expect(navigated).toEqual(['/articles/reading-dashboards'])
-  })
-
-  test('omits group/rightSection when not passed', () => {
-    const [action] = toArticleActions([ARTICLE], {
-      onNavigate: () => {},
-      href: () => '/content',
-    })
-
-    expect(action).not.toHaveProperty('group')
-    expect(action).not.toHaveProperty('rightSection')
-  })
-
-  test('sets group/rightSection when passed', () => {
-    const [action] = toArticleActions([ARTICLE], {
-      onNavigate: () => {},
-      href: () => '/content',
-      group: 'Guides',
-      rightSection: 'badge',
-    })
-
-    expect(action?.group).toBe('Guides')
-    expect(action?.rightSection).toBe('badge')
-  })
-
-  test('empty input returns []', () => {
-    expect(toArticleActions([], { onNavigate: () => {}, href: () => '#' })).toEqual([])
-  })
-})

package/src/content/article-model.test.ts

@@ -1,119 +0,0 @@
-import { describe, expect, test } from 'bun:test'
-import { filterArticles, formatArticleDate, sortArticles } from './article-model'
-import type { Article } from './article-model'
-
-function article(overrides: Partial<Article>): Article {
-  return { slug: 'x', title: 'Untitled', ...overrides }
-}
-
-describe('sortArticles', () => {
-  test('date-desc orders newest first (the default)', () => {
-    const articles = [
-      article({ slug: 'a', date: '2026-01-01' }),
-      article({ slug: 'b', date: '2026-06-01' }),
-      article({ slug: 'c', date: '2026-03-01' }),
-    ]
-    expect(sortArticles(articles).map((a) => a.slug)).toEqual(['b', 'c', 'a'])
-  })
-
-  test('date-asc orders oldest first', () => {
-    const articles = [
-      article({ slug: 'a', date: '2026-01-01' }),
-      article({ slug: 'b', date: '2026-06-01' }),
-      article({ slug: 'c', date: '2026-03-01' }),
-    ]
-    expect(sortArticles(articles, 'date-asc').map((a) => a.slug)).toEqual(['a', 'c', 'b'])
-  })
-
-  test('title sorts locale-aware, pinned to en-US regardless of runtime default', () => {
-    const articles = [
-      article({ slug: 'a', title: 'Zebra' }),
-      article({ slug: 'b', title: 'apple' }),
-      article({ slug: 'c', title: 'Mango' }),
-    ]
-    expect(sortArticles(articles, 'title').map((a) => a.slug)).toEqual(['b', 'c', 'a'])
-  })
-
-  test('is stable on equal dates — input order preserved', () => {
-    const articles = [
-      article({ slug: 'a', date: '2026-01-01' }),
-      article({ slug: 'b', date: '2026-01-01' }),
-      article({ slug: 'c', date: '2026-01-01' }),
-    ]
-    expect(sortArticles(articles, 'date-desc').map((a) => a.slug)).toEqual(['a', 'b', 'c'])
-    expect(sortArticles(articles, 'date-asc').map((a) => a.slug)).toEqual(['a', 'b', 'c'])
-  })
-
-  test('articles without a date sort last, in both date orders', () => {
-    const articles = [
-      article({ slug: 'no-date' }),
-      article({ slug: 'newer', date: '2026-06-01' }),
-      article({ slug: 'older', date: '2026-01-01' }),
-    ]
-    expect(sortArticles(articles, 'date-desc').map((a) => a.slug)).toEqual([
-      'newer',
-      'older',
-      'no-date',
-    ])
-    expect(sortArticles(articles, 'date-asc').map((a) => a.slug)).toEqual([
-      'older',
-      'newer',
-      'no-date',
-    ])
-  })
-
-  test('does not mutate the input array', () => {
-    const articles = [
-      article({ slug: 'b', date: '2026-06-01' }),
-      article({ slug: 'a', date: '2026-01-01' }),
-    ]
-    const snapshot = [...articles]
-    sortArticles(articles, 'date-asc')
-    expect(articles).toEqual(snapshot)
-  })
-})
-
-describe('filterArticles', () => {
-  const articles = [
-    article({ slug: 'a', category: 'guide', tags: ['api', 'design'] }),
-    article({ slug: 'b', category: 'reference', tags: ['api'] }),
-    article({ slug: 'c', category: 'guide', tags: ['ux'] }),
-  ]
-
-  test('category is an exact match', () => {
-    expect(filterArticles(articles, { category: 'guide' }).map((a) => a.slug)).toEqual(['a', 'c'])
-  })
-
-  test('tags are ANY-OF (OR)', () => {
-    expect(filterArticles(articles, { tags: ['design', 'ux'] }).map((a) => a.slug)).toEqual([
-      'a',
-      'c',
-    ])
-  })
-
-  test('category AND tags — AND between axes, OR within tags', () => {
-    expect(
-      filterArticles(articles, { category: 'guide', tags: ['ux'] }).map((a) => a.slug),
-    ).toEqual(['c'])
-  })
-
-  test('an empty query returns the input unchanged', () => {
-    expect(filterArticles(articles, {})).toBe(articles)
-    expect(filterArticles(articles, { category: '', tags: [] })).toBe(articles)
-  })
-})
-
-describe('formatArticleDate', () => {
-  test('formats a known ISO date', () => {
-    expect(formatArticleDate('2026-07-16')).toBe('Jul 16, 2026')
-  })
-
-  test('returns invalid input unchanged, never throws', () => {
-    expect(formatArticleDate('not-a-date')).toBe('not-a-date')
-    expect(formatArticleDate('')).toBe('')
-  })
-
-  test('an explicit locale override changes the output', () => {
-    expect(formatArticleDate('2026-07-16', 'de-DE')).toBe('16. Juli 2026')
-  })
-})

package/src/content/block-split.test.ts

@@ -1,75 +0,0 @@
-import { describe, expect, test } from 'bun:test'
-import { blockSplit } from './block-split'
-
-describe('blockSplit', () => {
-  test('returns an empty array for an empty string', () => {
-    expect(blockSplit('')).toEqual([])
-  })
-
-  test('join invariant holds for arbitrary input', () => {
-    const input = `# Title
-
-Paragraph one.
-
-- item one
-- item two
-
-\`\`\`ts
-const x = 1
-
-const y = 2
-\`\`\`
-
-Trailing paragraph.
-`
-    expect(blockSplit(input).join('')).toBe(input)
-  })
-
-  test('splits simple paragraphs on blank-line boundaries', () => {
-    const input = 'First paragraph.\n\nSecond paragraph.\n'
-    const blocks = blockSplit(input)
-    expect(blocks).toEqual(['First paragraph.\n\n', 'Second paragraph.\n'])
-  })
-
-  test('keeps a fenced code block containing blank lines as one block', () => {
-    const input = '```ts\nconst x = 1\n\nconst y = 2\n```\n\nAfter.\n'
-    const blocks = blockSplit(input)
-    expect(blocks).toEqual(['```ts\nconst x = 1\n\nconst y = 2\n```\n\n', 'After.\n'])
-  })
-
-  test('an unterminated fence at EOF stays one block', () => {
-    const input = 'Intro.\n\n```ts\nconst x = 1\n\nstill inside'
-    const blocks = blockSplit(input)
-    expect(blocks).toEqual(['Intro.\n\n', '```ts\nconst x = 1\n\nstill inside'])
-  })
-
-  test('a tilde fence is not closed by a backtick run of the same length', () => {
-    const input = '~~~\ncode\n```\nstill inside\n~~~\n\nAfter.\n'
-    const blocks = blockSplit(input)
-    expect(blocks).toEqual(['~~~\ncode\n```\nstill inside\n~~~\n\n', 'After.\n'])
-  })
-
-  test('keeps blank-line-separated list items in one block', () => {
-    const input = '- item one\n\n- item two\n\n- item three\n\nNew paragraph.\n'
-    const blocks = blockSplit(input)
-    expect(blocks).toEqual(['- item one\n\n- item two\n\n- item three\n\n', 'New paragraph.\n'])
-  })
-
-  test('keeps an indented continuation line attached to its list item', () => {
-    const input = '- item one\n\n  continuation text\n\nNew paragraph.\n'
-    const blocks = blockSplit(input)
-    expect(blocks).toEqual(['- item one\n\n  continuation text\n\n', 'New paragraph.\n'])
-  })
-
-  test('keeps consecutive table lines together with no blank line to split on', () => {
-    const input = '| a | b |\n| - | - |\n| 1 | 2 |\n\nAfter.\n'
-    const blocks = blockSplit(input)
-    expect(blocks).toEqual(['| a | b |\n| - | - |\n| 1 | 2 |\n\n', 'After.\n'])
-  })
-
-  test('keeps consecutive blockquote lines together', () => {
-    const input = '> line one\n> line two\n\nAfter.\n'
-    const blocks = blockSplit(input)
-    expect(blocks).toEqual(['> line one\n> line two\n\n', 'After.\n'])
-  })
-})

package/src/content/heading-components.test.tsx

@@ -1,65 +0,0 @@
-/**
- * heading-components — the slug/anchor/foreign-id contract (docs/CONTENT-SPEC.md §2 decision 6 /
- * §7). `createHeadingComponents` builds one renderer per level against a shared `SlugTracker`; each
- * test below builds its OWN tracker so a slug-collision counter never leaks across cases.
- *
- * `createHeadingComponents` is not part of the public surface (not re-exported by `./index`), same
- * test idiom as `composeRehypePlugins` in `./markdown.test.tsx` — imported straight from the module.
- */
-import type { ComponentType, JSX } from 'react'
-import type { Components, ExtraProps } from 'react-markdown'
-import { MantineProvider } from '@mantine/core'
-import { render, screen } from '@testing-library/react'
-import { describe, expect, test } from 'bun:test'
-import { createHeadingComponents } from './heading-components'
-import { SlugTracker } from './slug'
-
-function renderHeading(ui: React.ReactElement) {
-  return render(<MantineProvider>{ui}</MantineProvider>)
-}
-
-type HeadingProps = JSX.IntrinsicElements['h2'] & ExtraProps
-
-/** Narrows `Components['h2']` (`ComponentType | keyof JSX.IntrinsicElements | undefined`) down to
- * the function component `createHeadingComponents` actually builds — no cast, a runtime check. */
-function h2Of(components: Partial<Components>): ComponentType<HeadingProps> {
-  const H2 = components.h2
-  if (typeof H2 !== 'function') throw new Error('expected createHeadingComponents to build h2')
-  return H2
-}
-
-describe('heading-components', () => {
-  test('an ordinary heading is slugged, gets an id, and gets the anchor affordance', () => {
-    const H2 = h2Of(createHeadingComponents(new SlugTracker()))
-    renderHeading(<H2>Introduction</H2>)
-
-    const heading = screen.getByRole('heading', { level: 2, name: 'Introduction' })
-    expect(heading.id).toBe('introduction')
-    expect(screen.getByLabelText('Copy link to section')).toBeDefined()
-  })
-
-  test('a heading arriving with an id keeps that id instead of the slugged one', () => {
-    const H2 = h2Of(createHeadingComponents(new SlugTracker()))
-    renderHeading(<H2 id="footnote-label">Footnotes</H2>)
-
-    // The slugger would produce 'footnotes' — the incoming id must win outright.
-    const heading = screen.getByRole('heading', { level: 2, name: 'Footnotes' })
-    expect(heading.id).toBe('footnote-label')
-  })
-
-  test('a heading arriving with a class keeps it', () => {
-    const H2 = h2Of(createHeadingComponents(new SlugTracker()))
-    renderHeading(<H2 className="sr-only">Footnotes</H2>)
-
-    const heading = screen.getByRole('heading', { level: 2, name: 'Footnotes' })
-    expect(heading.className).toBe('sr-only')
-  })
-
-  test('a heading that keeps its own id is not given the anchor affordance', () => {
-    const H2 = h2Of(createHeadingComponents(new SlugTracker()))
-    renderHeading(<H2 id="footnote-label">Footnotes</H2>)
-
-    screen.getByRole('heading', { level: 2, name: 'Footnotes' })
-    expect(screen.queryByLabelText('Copy link to section')).toBeNull()
-  })
-})