@bongos/core 1.19.458 → 1.19.459

package/tests/ui_design_styles.mjs

@@ -0,0 +1,218 @@
+// tests/ui_design_styles.mjs — the ui-design module's style library (task 1003323, ADR 0219)
+// is a pinned contract, not a folder of ideas: every style dir carries a pack (exactly the
+// fifteen), a DESIGN.md whose frontmatter holds the same thirteen value for value, and a
+// specimen mock that passes the platform's rules under its own colours; the chrome world
+// entry IS the neutral pack; every pack clears the pack floor; the three served sheets
+// (world.css, cosmos.css, the hall's style.css) clear AA under every alternate in both modes
+// (their own suites run once per pack through UI_DESIGN_PACK, and a bad pack is proven to
+// fail them); the stub serves a page under a style with the look's fifteen spliced in and the
+// instance's identity untouched; the CLIs refuse an unknown style; and the doors (the styles
+// README, the module CLAUDE.md, /design) name every look. DB-free; the one browser-free stub
+// round-trip is the same the kit test already makes.
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { listStyles, resolveStyle, styleBrandingFile, packColors, startStub, STYLES_DIR, EXIT } from '../modules/ui-design/kit/lib.js';
+import { packContrast, PACK_PAIRS } from '../modules/ui-design/kit/contrast.js';
+import { checkMock, readDesignBans } from '../modules/ui-design/kit/check-mock.js';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const KIT = path.join(ROOT, 'modules', 'ui-design', 'kit');
+const read = (p) => fs.readFileSync(p, 'utf8').replace(/\r\n/g, '\n');
+const readJson = (p) => JSON.parse(fs.readFileSync(p, 'utf8'));
+const neutralUi = readJson(path.join(ROOT, 'config', 'branding.neutral.json')).theme.ui;
+const THIRTEEN = Object.keys(neutralUi.colors).sort();
+const camelToKebab = (k) => k.replace(/[A-Z]/g, (c) => '-' + c.toLowerCase());
+const styles = listStyles().map((name) => resolveStyle(name));
+const alternates = styles.filter((s) => s.name !== 'chrome-world');
+// a child `node --test` must not inherit NODE_TEST_CONTEXT, or it reports to this runner's
+// channel instead of its own stdout (an empty stdout and exit 0: a silent pass)
+const childEnv = (extra = {}) => { const e = { ...process.env, ...extra }; delete e.NODE_TEST_CONTEXT; return e; };
+const run = (file, args, env = {}) => spawnSync(process.execPath, [path.join(KIT, file), ...args], { encoding: 'utf8', env: childEnv(env), timeout: 60000 });
+
+// The `colors:` block of a DESIGN.md frontmatter → { 'bg': '#…', … } (quoted scalars only;
+// comments and the nested keys of other blocks are skipped).
+function frontmatterColors(md) {
+  const fm = md.match(/^---\n([\s\S]*?)\n---\n/);
+  assert.ok(fm, 'DESIGN.md opens with a frontmatter block');
+  const lines = fm[1].split('\n');
+  const start = lines.findIndex((l) => /^colors:\s*$/.test(l));
+  assert.ok(start >= 0, 'the frontmatter carries a colors: block');
+  const out = {};
+  for (const line of lines.slice(start + 1)) {
+    if (/^[a-z]/.test(line)) break;
+    const m = line.match(/^\s+([a-z][a-z0-9-]*):\s*"([^"]*)"/);
+    if (m) out[m[1]] = m[2];
+  }
+  return out;
+}
+
+// ── the catalogue ─────────────────────────────────────────────────────────────
+test('the catalogue: the chrome world plus at least two alternates, each dir carrying pack.json, DESIGN.md and mock.html', () => {
+  assert.ok(styles.some((s) => s.name === 'chrome-world'), 'the chrome world is the first entry');
+  assert.ok(alternates.length >= 2, `at least two alternates (found ${alternates.map((s) => s.name).join(', ') || 'none'})`);
+  for (const s of styles) {
+    for (const f of ['pack.json', 'DESIGN.md', 'mock.html']) assert.ok(fs.existsSync(path.join(s.dir, f)), `${s.name}: ${f}`);
+    assert.equal(s.name, path.basename(s.dir), `${s.name}: pack.json names its own dir`);
+    assert.match(s.name, /^[a-z0-9][a-z0-9-]*$/, `${s.name}: kebab-case`);
+  }
+});
+
+test('a pack is exactly the fifteen: the thirteen colour keys of the neutral pack, the two font stacks and a links line, with a title, a summary and an origin', () => {
+  for (const s of styles) {
+    const ui = s.pack.theme && s.pack.theme.ui;
+    assert.ok(ui && ui.colors && ui.fonts, `${s.name}: theme.ui.colors + theme.ui.fonts`);
+    assert.deepEqual(Object.keys(ui.colors).sort(), THIRTEEN, `${s.name}: exactly the thirteen`);
+    for (const [k, v] of Object.entries(ui.colors)) assert.match(v, /^#[0-9a-f]{6}$/i, `${s.name}: ${k} is a plain hex (the sheets do hex maths on the contract tier)`);
+    assert.ok(typeof ui.fonts.display === 'string' && ui.fonts.display && typeof ui.fonts.body === 'string' && ui.fonts.body, `${s.name}: both font stacks`);
+    assert.ok(Array.isArray(ui.fonts.links) && ui.fonts.links.length && ui.fonts.links.every((l) => /^https:\/\//.test(l)), `${s.name}: fonts.links carries the face stylesheet(s)`);
+    assert.deepEqual(Object.keys(ui).sort(), ['colors', 'fonts'], `${s.name}: a look sets the fifteen and nothing else (favicon and backdrop stay the instance's)`);
+    for (const k of ['title', 'summary', 'origin']) assert.ok(typeof s.pack[k] === 'string' && s.pack[k].length > 8, `${s.name}: ${k}`);
+  }
+});
+
+test('the chrome world pack IS the neutral pack, and every alternate is a different look', () => {
+  const chrome = styles.find((s) => s.name === 'chrome-world');
+  assert.deepEqual(chrome.pack.theme.ui.colors, neutralUi.colors, 'chrome-world colours = config/branding.neutral.json theme.ui.colors');
+  assert.equal(chrome.pack.theme.ui.fonts.display, neutralUi.fonts.display);
+  assert.equal(chrome.pack.theme.ui.fonts.body, neutralUi.fonts.body);
+  assert.deepEqual(chrome.pack.theme.ui.fonts.links, neutralUi.fonts.links);
+  for (const s of alternates) {
+    assert.notEqual(s.pack.theme.ui.colors.accent.toLowerCase(), neutralUi.colors.accent.toLowerCase(), `${s.name}: a look has its own accent`);
+    assert.notEqual(s.pack.theme.ui.fonts.display, neutralUi.fonts.display, `${s.name}: a look has its own display face`);
+  }
+});
+
+test('every DESIGN.md frontmatter carries its pack\'s thirteen, value for value, and its prose names the look\'s adoption path', () => {
+  for (const s of styles) {
+    const md = read(path.join(s.dir, 'DESIGN.md'));
+    const colors = frontmatterColors(md);
+    for (const [k, v] of Object.entries(s.pack.theme.ui.colors)) {
+      assert.equal((colors[camelToKebab(k)] || '').toLowerCase(), v.toLowerCase(), `${s.name}: DESIGN.md ${camelToKebab(k)} = pack ${k}`);
+    }
+    assert.match(md, /config\/branding\.json/, `${s.name}: DESIGN.md says how an instance adopts the look`);
+  }
+});
+
+// ── the floors ────────────────────────────────────────────────────────────────
+test('every pack clears the pack floor: every ink on every ground at 4.5:1', () => {
+  for (const s of styles) {
+    const rows = packContrast(s.pack);
+    assert.equal(rows.length, PACK_PAIRS.length);
+    for (const r of rows) assert.equal(r.ok, true, `${s.name}: ${r.fg} on ${r.bg} = ${r.ratio} (need ${r.need})`);
+  }
+});
+
+test('every mock passes the platform rules under its own colours and its own DESIGN.md bans, is stamped by the transform, and declares no colour of its own', () => {
+  for (const s of styles) {
+    const html = read(path.join(s.dir, 'mock.html'));
+    const bans = readDesignBans(read(path.join(s.dir, 'DESIGN.md')));
+    const results = checkMock(html, { bans, packColors: packColors(s.pack) });
+    const fails = results.filter((r) => r[0] === 'FAIL').map((r) => `${r[1]} (${r[2]})`);
+    assert.deepEqual(fails, [], `${s.name}: mock.html`);
+    assert.ok(results.some((r) => r[1].startsWith('every dark rule written twice') && r[0] === 'PASS'), `${s.name}: the mock carries a dark tier, written twice`);
+    assert.ok(html.includes('{{productName}}'), `${s.name}: the mock carries the identity token the transform stamps`);
+    assert.ok(bans.has('em-dash') && bans.has('emoji'), `${s.name}: the look's DESIGN.md declares the copy bans`);
+  }
+});
+
+test('the world, hub and hall sheets clear AA under every alternate in both modes: the three token suites run once per pack', () => {
+  // relative, forward-slash paths: `node --test <path>` reads its positionals as globs, and a
+  // Windows absolute path matches nothing (zero tests, exit 0 — a silent pass)
+  const suites = ['tests/world_tokens.mjs', 'tests/cosmos_token_contrast.mjs', 'tests/hall_tokens.mjs'];
+  for (const s of alternates) {
+    const r = spawnSync(process.execPath, ['--test', '--test-reporter=tap', ...suites], { cwd: ROOT, encoding: 'utf8', env: childEnv({ UI_DESIGN_PACK: s.file }), timeout: 120000 });
+    assert.match(r.stdout, /# tests [1-9]/, `${s.name}: the suites actually ran`);
+    const fails = (r.stdout.match(/^not ok .*$/gm) || []).join('\n');
+    assert.equal(r.status, 0, `${s.name}: a sheet fails under this pack\n${fails}\n${(r.stdout.split('\n').filter((l) => /^\s+(\+|-|\*|actual|expected|error|message)/.test(l) || /:1 \(need|vs pack| = \d/.test(l)).slice(0, 30).join('\n'))}`);
+    assert.match(r.stdout, /# pass \d+/);
+  }
+});
+
+test('UI_DESIGN_PACK is honoured, not decorative: a pack that thins ink-faint fails the same suites', () => {
+  const bad = structuredClone(readJson(path.join(STYLES_DIR, 'expedition', 'pack.json')));
+  bad.theme.ui.colors.inkFaint = '#c8c6bd';
+  const file = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'ui-style-bad-')), 'pack.json');
+  fs.writeFileSync(file, JSON.stringify(bad));
+  const r = spawnSync(process.execPath, ['--test', '--test-reporter=tap', 'tests/world_tokens.mjs'], { cwd: ROOT, encoding: 'utf8', env: childEnv({ UI_DESIGN_PACK: file }), timeout: 60000 });
+  assert.match(r.stdout, /# tests [1-9]/, 'the suite actually ran');
+  assert.notEqual(r.status, 0, 'a thinned ink-faint must fail the world suite under the env var');
+  assert.match(r.stdout, /ink-faint on the page ground/, 'the failing pair is named');
+  const drift = spawnSync(process.execPath, ['--test', '--test-reporter=tap', 'tests/world_tokens.mjs'], { cwd: ROOT, encoding: 'utf8', env: childEnv({ UI_DESIGN_PACK: path.join(STYLES_DIR, 'expedition', 'pack.json') }), timeout: 60000 });
+  assert.match(drift.stdout, /^ok .*do not drift/m, 'the drift test keeps measuring the sheet against the NEUTRAL pack under an alternate');
+  fs.rmSync(path.dirname(file), { recursive: true, force: true });
+});
+
+// ── the picker ────────────────────────────────────────────────────────────────
+test('resolveStyle: by name, by pack.json path, and nothing else; styleBrandingFile lays the look over the instance and keeps its identity', () => {
+  const byName = resolveStyle('expedition');
+  assert.equal(byName.name, 'expedition');
+  assert.equal(resolveStyle(byName.file).name, 'expedition', 'a pack.json path resolves too');
+  assert.equal(resolveStyle('no-such-look'), null);
+  assert.equal(resolveStyle('../kit/lib.js'), null, 'a path that is not a pack.json does not resolve');
+  assert.equal(resolveStyle(''), null);
+  const merged = readJson(styleBrandingFile(byName));
+  assert.equal(merged.theme.ui.colors.accent, '#ffd214', 'the look\'s fifteen');
+  assert.equal(merged.theme.ui.fonts.display, byName.pack.theme.ui.fonts.display);
+  assert.equal(merged.identity, undefined, 'a neutral checkout has no instance pack: only theme is written, so identity resolves from the neutral starter');
+  // a pack.json loaded by path names itself: the temp file the transform reads takes a slug, never the name
+  const hostile = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'ui-style-name-')), 'pack.json');
+  fs.writeFileSync(hostile, JSON.stringify({ ...byName.pack, name: '../../escape' }));
+  const written = styleBrandingFile(resolveStyle(hostile));
+  assert.equal(path.dirname(written), path.join(os.tmpdir(), 'ui-design-kit', 'styles'), "the merged pack is written inside the kit's temp dir whatever the pack calls itself");
+  assert.match(path.basename(written), /^[A-Za-z0-9_-]+\.branding\.json$/);
+  fs.rmSync(path.dirname(hostile), { recursive: true, force: true });
+});
+
+test('the stub serves a real surface and a specimen under a style: the spliced :root carries the look\'s fifteen, the instance\'s name is stamped, the feeds still answer', async () => {
+  const s = await startStub({ surface: 'public-landing', style: 'grove' });
+  try {
+    const html = await (await fetch(s.base + '/')).text();
+    assert.ok(html.includes('--accent:#e3c39c;'), 'the grove\'s accent is in the spliced :root');
+    assert.ok(html.includes('--font-display:"Nunito"'), 'the grove\'s display face');
+    assert.ok(html.includes('family=Nunito'), 'the look\'s font link is injected');
+    assert.ok(html.includes('window.__BRANDING__'), 'the pack is injected');
+    assert.ok(!html.includes('#fb9569'), 'the neutral accent does not leak into the served page');
+    assert.equal((await fetch(s.base + '/api/gds/public/progress')).status, 200);
+  } finally { s.stop(); }
+  const spec = await startStub({ surface: 'modules/ui-design/styles/expedition', style: 'expedition' });
+  try {
+    const html = await (await fetch(spec.base + '/mock')).text();
+    assert.ok(html.includes('--accent:#ffd214;'), 'the specimen is served under its own pack');
+    assert.ok(!html.includes('{{productName}}'), 'the identity token is stamped by the real transform');
+    assert.match(html, /<title>[^<]*the expedition, on a sheet<\/title>/);
+  } finally { spec.stop(); }
+});
+
+test('the CLIs refuse an unknown style with the catalogue named, before any browser; contrast --pack <name> measures a look', () => {
+  const bad = run('serve.js', [], { STYLE: 'no-such-look', STUB_PORT: '0' });
+  assert.equal(bad.status, EXIT.USAGE); assert.match(bad.stderr, /neither a style/); assert.match(bad.stderr, /chrome-world, expedition, grove/);
+  const render = run('render.js', ['--page', '/', '--style', 'no-such-look']);
+  assert.equal(render.status, EXIT.USAGE); assert.match(render.stderr, /--style "no-such-look" is not a style/);
+  const probe = run('probe.js', ['--page', '/projects', '--style', 'no-such-look']);
+  assert.equal(probe.status, EXIT.USAGE); assert.match(probe.stderr, /--style "no-such-look" is not a style/);
+  const c = run('contrast.js', ['--pack', 'expedition']);
+  assert.equal(c.status, EXIT.CLEAN, c.stdout + c.stderr); assert.match(c.stdout, /the expedition pack/); assert.match(c.stdout, /PACK CLEAN/);
+  const cBad = run('contrast.js', ['--pack', 'no-such-look']);
+  assert.equal(cBad.status, EXIT.USAGE); assert.match(cBad.stderr, /not a style/);
+  const mock = run('check-mock.js', ['--file', path.join(STYLES_DIR, 'grove', 'mock.html'), '--pack', 'grove']);
+  assert.equal(mock.status, EXIT.CLEAN, mock.stdout); assert.match(mock.stdout, /ALL RULES PASS/);
+});
+
+// ── the doors ─────────────────────────────────────────────────────────────────
+test('the styles README, the module CLAUDE.md and /design name every look', () => {
+  const readme = read(path.join(STYLES_DIR, 'README.md'));
+  const claude = read(path.join(ROOT, 'modules', 'ui-design', 'CLAUDE.md'));
+  const design = read(path.join(ROOT, '.claude', 'skills', 'design', 'SKILL.md'));
+  for (const s of styles) {
+    assert.ok(readme.includes(`\`${s.name}\``), `styles/README.md rosters ${s.name}`);
+    assert.ok(claude.includes(`\`${s.name}\``), `modules/ui-design/CLAUDE.md names ${s.name}`);
+    assert.ok(design.split('\n').some((l) => l.includes(`\`${s.name}\``)), `/design names ${s.name} on a line`);
+  }
+  assert.match(design, /STYLE=/, '/design says how to render under a look');
+  assert.match(readme, /GDS_BRANDING_FILE/, 'the README names the knob the picker rides');
+});

package/tests/world_tokens.mjs

@@ -93,9 +93,15 @@ const darkMedia = declarations(blockAfter(':root:not([data-mode="light"]) {'));
 // pack emits the PACK wins and world.css's own value never renders. Measuring
 // world.css alone would measure a page nobody sees. The dark blocks are (0,2,0)
 // and win back.
-const packUi = JSON.parse(
+// UI_DESIGN_PACK=<pack.json> measures the sheet under a look from the style library
+// (tests/ui_design_styles.mjs runs this file once per pack, task 1003323); the DRIFT test
+// below always compares the sheet against the neutral pack, which is what it must equal.
+const neutralUi = JSON.parse(
   fs.readFileSync(path.join(ROOT, 'config', 'branding.neutral.json'), 'utf8'),
 ).theme.ui;
+const packUi = process.env.UI_DESIGN_PACK
+  ? JSON.parse(fs.readFileSync(path.resolve(process.env.UI_DESIGN_PACK), 'utf8')).theme.ui
+  : neutralUi;
 
 // mirrors COLOR_VARS in src/bongos/serve-internal.js
 const camelToVar = (k) => '--' + k.replace(/[A-Z]/g, (c) => '-' + c.toLowerCase());
@@ -173,7 +179,8 @@ test('world.css defaults do not drift from the branding pack', () => {
   // page reads correctly standalone (opened as a file, with no server) only while
   // the two agree. This is the fifteen: thirteen colours plus the two faces.
   const drift = [];
-  const expected = { ...PACK, '--font-display': packUi.fonts.display, '--font-body': packUi.fonts.body };
+  const NEUTRAL = Object.fromEntries(Object.entries(neutralUi.colors).map(([k, v]) => [camelToVar(k), v]));
+  const expected = { ...NEUTRAL, '--font-display': neutralUi.fonts.display, '--font-body': neutralUi.fonts.body };
   for (const [name, packValue] of Object.entries(expected)) {
     const cssValue = contractTier[name];
     if (cssValue === undefined) {