@bongos/core 1.19.396 → 1.19.397

package/tests/ui_design_kit.mjs

@@ -0,0 +1,217 @@
+// tests/ui_design_kit.mjs — the ui-design kit (task 1003320, ADR 0197): the platform
+// floors are a pinned contract; a states/probes file has a shape the kit refuses to
+// guess at; the pure audit names what a bad render did; the mock checker keeps the
+// platform's rules apart from an instance's taste bans; the instance's own pack
+// clears the floor; every CLI exits with its documented code on a bad input; and the
+// stub serves a surface through the doorway's real transforms. DB-free and
+// browser-free — the renders themselves are the recipe's job, not CI's.
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+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';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const KIT = path.join(ROOT, 'modules', 'ui-design', 'kit');
+const lib = require(path.join(KIT, 'lib.js'));
+const mock = require(path.join(KIT, 'check-mock.js'));
+const contrast = require(path.join(KIT, 'contrast.js'));
+
+const run = (file, args, env = {}) => spawnSync(process.execPath, [path.join(KIT, file), ...args], { encoding: 'utf8', env: { ...process.env, ...env }, timeout: 60000 });
+const tmp = (name, text) => { const p = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'ui-kit-test-')), name); fs.writeFileSync(p, text); return p; };
+const readJson = (rel) => JSON.parse(fs.readFileSync(path.join(ROOT, rel), 'utf8'));
+
+// ── the contract ──────────────────────────────────────────────────────────────
+test('the platform floors are a pinned list — a floor cannot vanish quietly', () => {
+  assert.deepEqual([...lib.FLOORS], ['console-errors', 'failed-requests', 'horizontal-overflow', 'one-header-main-h1', 'controls-24px', 'top-bar-80px', 'reduced-motion']);
+  assert.deepEqual(lib.EXIT, { CLEAN: 0, PROBLEMS: 1, USAGE: 2, NO_BROWSER: 3 });
+  assert.deepEqual(Object.keys(lib.SIZES), ['320', '390', '1440']);
+});
+
+test('the shipped states files validate and sit beside the page they name', () => {
+  for (const rel of ['public-landing/projects.states.json', 'public-landing/index.states.json', 'modules/hall-ui/public/ranks.states.json']) {
+    const json = readJson(rel);
+    const v = lib.validateStatesFile(json);
+    assert.deepEqual(v.errors, [], `${rel}: ${v.errors.join('; ')}`);
+    assert.equal(path.basename(rel), `${lib.pageName(json.page)}.states.json`, `${rel} is named for its page`);
+  }
+});
+
+test('the shipped probes files validate', () => {
+  for (const rel of ['public-landing/projects.probes.json', 'public-landing/index.probes.json']) {
+    const v = lib.validateProbesFile(readJson(rel));
+    assert.deepEqual(v.errors, [], `${rel}: ${v.errors.join('; ')}`);
+  }
+});
+
+test('a states file that breaks the contract is refused with the reason named', () => {
+  assert.equal(lib.validateStatesFile(null).ok, false);
+  const v = lib.validateStatesFile({});
+  assert.ok(v.errors.some((e) => e.startsWith('page: required')));
+  assert.ok(v.errors.some((e) => e.startsWith('states: required')));
+  const bad = lib.validateStatesFile({ page: '/x', states: { 'Bad Name': { actions: [['teleport', '#a']], expect: { glow: true } }, ok: { auth: 'yes' } } });
+  assert.ok(bad.errors.some((e) => /kebab-case/.test(e)));
+  assert.ok(bad.errors.some((e) => /unknown action "teleport"/.test(e)));
+  assert.ok(bad.errors.some((e) => /unknown expectation/.test(e) && /glow/.test(e)));
+  assert.ok(bad.errors.some((e) => /states\.ok\.auth/.test(e)));
+  const stub = lib.validateStatesFile({ page: '/x', stub: { prefix: 'builders' }, states: { a: {} } });
+  assert.ok(stub.errors.some((e) => /stub\.prefix/.test(e)));
+});
+
+test('a probes file needs a name and an expectation per probe, and cannot continue from nothing', () => {
+  const v = lib.validateProbesFile({ page: '/x', probes: [{ continue: true, steps: [] }, { name: 'n', steps: [['wait', 1]] }] });
+  assert.ok(v.errors.some((e) => /probes\[0\]\.name: required/.test(e)));
+  assert.ok(v.errors.some((e) => /probes\[0\]\.continue: the first probe/.test(e)));
+  assert.ok(v.errors.some((e) => /probes\[1\]\.expect: required/.test(e)));
+  assert.ok(lib.validateProbesFile({ page: '/x', probes: [{ name: 'n', steps: [], expect: { dialog: false } }] }).ok);
+});
+
+// ── the pure audit ────────────────────────────────────────────────────────────
+const clean = () => ({ scrollWidth: 1440, clientWidth: 1440, mode: 'dark', headers: 1, mains: 1, h1s: 1, smallControls: [], bar: { h: 64, top: 0 }, expanded: [], dialog: false, running: 0, activeId: '', activeText: '', sel: {} });
+
+test('auditFloors names each floor a render breaks, and says nothing about a clean one', () => {
+  assert.deepEqual(lib.auditFloors(clean(), { width: 1440, mode: 'dark' }), []);
+  const p = lib.auditFloors({ ...clean(), scrollWidth: 1500, h1s: 3, smallControls: ['a.x "Docs" 40x17'], bar: { h: 96 }, mode: 'light' }, { width: 1440, mode: 'dark' });
+  assert.ok(p.some((x) => x.startsWith('horizontal-overflow')));
+  assert.ok(p.some((x) => x.startsWith('one-header-main-h1') && /h1 3/.test(x)));
+  assert.ok(p.some((x) => x.startsWith('controls-24px') && /40x17/.test(x)));
+  assert.ok(p.some((x) => x.startsWith('top-bar-80px') && /96px/.test(x)));
+  assert.ok(p.some((x) => /data-mode "light" under a dark scheme/.test(x)));
+  assert.deepEqual(lib.auditFloors({ ...clean(), mode: null }, { mode: 'dark' }), [], 'a page that sets no data-mode is not held to one');
+});
+
+test('expectProblems compares every expectation the vocabulary allows', () => {
+  const facts = { ...clean(), expanded: ['projTrig'], dialog: true, sel: { '#a': true, '#b': false }, activeId: 'x', activeText: 'Sky', param: { view: 'mine' }, attr: ['dark'], text: ['Table'], href: ['/docs'], count: [3], checked: false, value: ['demo'], hasClass: [true] };
+  assert.deepEqual(lib.expectProblems(facts, { expanded: true, dialog: true, visible: ['#a'], hidden: ['#b'], open: '#a', closed: '#b', activeId: 'x', activeText: 'Sky', expandedIds: ['projTrig'], param: { view: 'mine' }, attr: [['html', 'data-mode', 'dark']], text: [['h1', 'Table']], href: [['a', '/docs']], count: [['li', 3]], value: [['#q', 'demo']], hasClass: [['#w', 'is-open']] }), []);
+  const p = lib.expectProblems(facts, { expanded: false, dialog: false, visible: ['#b'], hidden: ['#a'], activeText: 'Table', param: { view: null }, count: [['li', 5]], checked: '#c', hasClass: [['#w', 'is-open', false]], noOverflow: true });
+  for (const needle of ['expected no expanded trigger', 'expected no visible dialog', 'expected visible: #b', 'expected hidden: #a', 'active text "Sky", expected "Table"', '?view=mine, expected null', '3 × li, expected 5', '#c is not checked', 'still has class "is-open"']) {
+    assert.ok(p.some((x) => x.includes(needle)), `missing: ${needle} in ${p.join(' | ')}`);
+  }
+});
+
+test('reducedMotionProblems: a running animation or a rAF loop is a floor break', () => {
+  assert.deepEqual(lib.reducedMotionProblems({ running: [], frames: 1 }), []);
+  const p = lib.reducedMotionProblems({ running: ['breath'], frames: 40 });
+  assert.equal(p.length, 2);
+  assert.match(p[0], /breath/); assert.match(p[1], /requestAnimationFrame loop/);
+});
+
+test('the page argument survives Git Bash path conversion of a bare slash', () => {
+  assert.equal(lib.normalizePageArg('C:/Program Files/Git/'), '/');
+  assert.equal(lib.normalizePageArg('/projects'), '/projects');
+  assert.equal(lib.pageName('/'), 'index'); assert.equal(lib.pageName('/builders/ranks'), 'ranks'); assert.equal(lib.pageName('/projects?view=mine'), 'projects');
+});
+
+// ── the mock checker: platform rules vs the instance's taste ──────────────────
+const GOOD_MOCK = `<!doctype html><html><head><style>
+body{--pad:8px;color:var(--ink);background:var(--bg)}
+:root[data-mode="dark"] body{--pad:9px}
+@media (prefers-color-scheme: dark){:root:not([data-mode="light"]) body{--pad:9px}}
+.a{transition:opacity 200ms}
+</style></head><body><!-- THESIS: a mock that says what it claims, so the reviewer can check the render against the words -->
+<a class="skip" href="#main">Skip</a><header><button aria-expanded="false" aria-controls="m">Menu</button></header>
+<main id="main"><h1>Title</h1><p>Plain copy.</p><div id="m" hidden></div></main>
+<script>const state = new URLSearchParams(location.search).get('state');</script></body></html>`;
+const fails = (results) => results.filter((r) => r[0] === 'FAIL').map((r) => r[1]);
+
+test('checkMock: a mock inside the contract passes every platform rule', () => {
+  assert.deepEqual(fails(mock.checkMock(GOOD_MOCK)), []);
+});
+
+test('checkMock: the platform rules catch a page :root, a literal colour, a pinned pack colour, JS motion', () => {
+  const f1 = fails(mock.checkMock(GOOD_MOCK.replace('<style>', '<style>:root{--x:1}')));
+  assert.ok(f1.some((r) => r.startsWith('no page-local :root')), f1.join(' | '));
+  const f2 = fails(mock.checkMock(GOOD_MOCK.replace('color:var(--ink)', 'color:#ff0000')));
+  assert.ok(f2.some((r) => r.startsWith('no literal hex colour')), f2.join(' | '));
+  const f3 = fails(mock.checkMock(GOOD_MOCK.replace('color:var(--ink)', 'color:#fb9569'), { packColors: { accent: '#fb9569' } }));
+  assert.ok(f3.some((r) => r.startsWith('no pack colour pinned')), f3.join(' | '));
+  const f4 = fails(mock.checkMock(GOOD_MOCK.replace('<script>', '<script>requestAnimationFrame(() => {});')));
+  assert.ok(f4.some((r) => r.startsWith('no motion in JavaScript')), f4.join(' | '));
+  const f5 = fails(mock.checkMock(GOOD_MOCK.replace(':root[data-mode="dark"] body{--pad:9px}', ':root[data-mode="dark"] body{--pad:10px}')));
+  assert.ok(f5.some((r) => r.startsWith('every dark rule written twice')), f5.join(' | '));
+});
+
+test('checkMock: a taste ban applies only when the instance declared it', () => {
+  const dashed = GOOD_MOCK.replace('Plain copy.', 'Plain — copy.');
+  const withBan = mock.checkMock(dashed, { bans: new Set(['em-dash']) });
+  assert.ok(fails(withBan).some((r) => r.startsWith('taste: no em/en dash')));
+  const withoutBan = mock.checkMock(dashed, { bans: new Set() });
+  assert.deepEqual(fails(withoutBan), []);
+  assert.ok(!withoutBan.some((r) => r[1].startsWith('taste:')), 'no taste rule is even evaluated without a ban');
+});
+
+test('readDesignBans reads the Don\'t section — the live DESIGN.md declares the five, an empty file none', () => {
+  const live = mock.readDesignBans(fs.readFileSync(path.join(ROOT, 'DESIGN.md'), 'utf8'));
+  for (const k of ['em-dash', 'emoji', 'gradient-text', 'text-glow', 'box-shadow']) assert.ok(live.has(k), `live DESIGN.md bans ${k}`);
+  assert.equal(mock.readDesignBans('').size, 0);
+  assert.deepEqual([...mock.readDesignBans("## Do's and Don'ts\n\n### Do\n- Do use an em dash.\n\n### Don't\n- Don't use emoji.\n\n## Next\n")], ['emoji'], 'only the Don\'t section counts');
+});
+
+// ── the pack ──────────────────────────────────────────────────────────────────
+test('the neutral pack clears the text floor on its own grounds (both pack shapes)', () => {
+  const filePack = readJson('config/branding.neutral.json');
+  const rows = contrast.packContrast(filePack);
+  const onGrounds = rows.filter((r) => r.bg === 'bg' || r.bg === 'bgCard');
+  assert.ok(onGrounds.length >= 6);
+  for (const r of onGrounds) assert.equal(r.ok, true, `${r.fg} on ${r.bg}: ${r.ratio} (need ${r.need})`);
+  const clientShape = { theme: filePack.theme.ui };
+  assert.deepEqual(contrast.packContrast(clientShape), rows, 'clientBranding() flattens theme.ui onto theme; same answer');
+});
+
+test('the WCAG maths: black on white is 21:1, alpha composites before it is measured', () => {
+  assert.equal(+lib.contrastRatio(lib.parseColor('#000'), lib.parseColor('#ffffff')).toFixed(1), 21);
+  const half = lib.composite(lib.parseColor('rgba(0,0,0,0.5)'), lib.parseColor('#fff'));
+  assert.ok(Math.abs(half[0] - 127.5) < 0.01);
+  assert.equal(lib.parseColor('nope'), null);
+});
+
+// ── the CLIs: exit codes are the contract a caller can script against ───────────
+test('render.js: usage and a broken states file exit 2 with the reason, before any browser', () => {
+  const noArgs = run('render.js', []);
+  assert.equal(noArgs.status, lib.EXIT.USAGE); assert.match(noArgs.stderr, /--page/);
+  const missing = run('render.js', ['--states', path.join(os.tmpdir(), 'no-such.states.json')]);
+  assert.equal(missing.status, lib.EXIT.USAGE); assert.match(missing.stderr, /not found/);
+  const bad = run('render.js', ['--states', tmp('x.states.json', JSON.stringify({ page: 'projects', states: { a: { actions: [['fly']] } } }))]);
+  assert.equal(bad.status, lib.EXIT.USAGE);
+  assert.match(bad.stderr, /page: required/); assert.match(bad.stderr, /unknown action "fly"/);
+  const noSidecar = run('render.js', ['--page', '/nowhere']);
+  assert.equal(noSidecar.status, lib.EXIT.USAGE); assert.match(noSidecar.stderr, /no states file beside the surface/);
+});
+
+test('probe.js and check-mock.js: the same discipline', () => {
+  const bad = run('probe.js', ['--probes', tmp('x.probes.json', JSON.stringify({ page: '/', probes: [{ name: 'n', steps: [] }] }))]);
+  assert.equal(bad.status, lib.EXIT.USAGE); assert.match(bad.stderr, /expect: required/);
+  assert.equal(run('check-mock.js', []).status, lib.EXIT.USAGE);
+  const failing = run('check-mock.js', ['--file', tmp('m.html', GOOD_MOCK.replace('<style>', '<style>:root{--x:1}')), '--no-taste']);
+  assert.equal(failing.status, lib.EXIT.PROBLEMS); assert.match(failing.stdout, /FAIL no page-local :root/);
+  const passing = run('check-mock.js', ['--file', tmp('m.html', GOOD_MOCK), '--no-taste']);
+  assert.equal(passing.status, lib.EXIT.CLEAN, passing.stdout); assert.match(passing.stdout, /ALL RULES PASS/);
+});
+
+test('serve.js refuses a surface that does not resolve, and serves one through the doorway transforms', async () => {
+  const bad = run('serve.js', [], { SURFACE: 'no-such-surface', STUB_PORT: '0' });
+  assert.equal(bad.status, lib.EXIT.USAGE); assert.match(bad.stderr, /neither a directory/);
+  for (const auth of [false, true]) {
+    const s = await lib.startStub({ surface: 'public-landing', auth });
+    try {
+      const html = await (await fetch(s.base + '/')).text();
+      assert.ok(html.includes('window.__BRANDING__'), 'the pack is injected');
+      assert.ok(/:root\s*\{/.test(html), 'the theme :root is spliced');
+      assert.ok(/\?v=[0-9a-f]{8}/.test(html), 'assets are content-stamped');
+      const me = await fetch(s.base + '/api/bongos/me');
+      assert.equal(me.status, auth ? 200 : 401);
+      if (auth) { const body = await me.json(); assert.ok(body.builder && body.builder.github_login, 'the real { builder } shape'); assert.match(body.builder.avatar_url, /^http:\/\/127\.0\.0\.1:\d+\/__kit\/avatar\.svg$/); }
+      assert.equal((await fetch(s.base + '/api/gds/public/progress')).status, 200, 'the public feed answers from a fixture');
+      assert.equal((await fetch(s.base + '/api/gds/nope')).status, 404);
+    } finally { s.stop(); }
+  }
+  const child = await lib.startStub({ surface: 'public-landing', child: true });
+  try {
+    const html = await (await fetch(child.base + '/')).text();
+    assert.equal((html.match(/<!--apex-only:start-->/g) || []).length, 0, 'the child shape strips the apex-only regions');
+  } finally { child.stop(); }
+});