@bongos/core 1.19.1055 → 1.19.1057

package/scripts/gds/ship-check.js

@@ -35,6 +35,8 @@ const STEPS = [
   { key: 'api-docs', label: 'docs/api/openapi.json + api-reference fresh', argv: ['scripts/gds/gen-api-docs.js', '--check'], fix: 'node scripts/gds/gen-api-docs.js' },
   { key: 'copy-registry', label: 'docs/copy-registry.json fresh', argv: ['scripts/gds/copy-inventory.js', '--check'], fix: 'node scripts/gds/copy-inventory.js', optional: true },
   { key: 'page-inventory', label: 'docs/page-inventory.json fresh (every page + its stable id)', argv: ['scripts/gds/page-inventory.js', '--check'], fix: 'node scripts/gds/page-inventory.js', optional: true },
+  // The page readings (task 1004315, ADR 0341 D3): files_hash only, no browser; the fix is the reader's own re-read.
+  { key: 'page-readings', label: 'docs/page-readings.json fresh (every page\'s reading matches its files)', argv: ['scripts/gds/page-reader.js', '--check'], fix: 'node scripts/gds/page-reader.js --stale', optional: true },
   { key: 'linkify', label: 'no bare #NNN task refs in committed markdown', argv: ['scripts/gds/linkify-refs.js', '--check'], fix: 'node scripts/gds/linkify-refs.js', optional: true },
   { key: 'skill-lint', label: 'SKILL.md frontmatter parses', argv: ['scripts/gds/skill-lint.js'], fix: 'fix the ✗ lines (description: >- block scalars)' },
   { key: 'render-fit', label: 'rendered text fit + sibling overlap on the pages this branch changed (advisory)', argv: ['scripts/gds/render-check.js'], fix: 'look at the shots it names; fix the element, or say in the ship notes why it is right', advisory: true, optional: true, skipWith: '--no-render', slow: true },

package/src/module-api.js

@@ -71,7 +71,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.1055'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.1057'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/page_reader.mjs

@@ -0,0 +1,200 @@
+// tests/page_reader.mjs — the page reader (BV2.TW04, task 1004315; ADR 0341 D3;
+// the Tweak Mode chain, goal 1000095).
+//
+// What these tests defend:
+//   1. NOTHING IS DROPPED. A visible string the copy registry cannot place is
+//      LISTED as unplaced, with a key and a section — the task's own done-when.
+//      Only a string that is nothing but the page's own data is left out, and
+//      the registry is always asked first, so a placed string is never mistaken
+//      for data.
+//   2. PLACEMENT. Exact text, a holed row's pattern, a segment of a holed row —
+//      a row in the page's own files first, never another page's html.
+//   3. SHARED. Shell text is marked shared, keeps its registry row when it has
+//      one, and is outside reading_hash.
+//   4. THE CONTRACT. docs/page-readings.json covers every inventory page, each
+//      line carries key/section/text/placement, keys run L0001.. in order, and
+//      both hashes are what the generator computes.
+//   5. FRESHNESS WITHOUT A BROWSER. --check compares files_hash, names the re-read
+//      command, and never loads the browser driver.
+//
+// DB-free, network-free, browser-free.
+// Run:  node --test tests/page_reader.mjs
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const reader = require(path.join(ROOT, 'scripts', 'gds', 'page-reader.js'));
+const shipCheck = require(path.join(ROOT, 'scripts', 'gds', 'ship-check.js'));
+
+const REGISTRY = {
+  entries: [
+    { id: 'aaa000000001', text: 'Welcome back', file: 'mods/pub/home.html', line: 10 },
+    { id: 'aaa000000002', text: '${…} of ${…} shipped this week', file: 'mods/pub/home.js', line: 40 },
+    { id: 'aaa000000003', text: 'Signed in as ${…}. Sign out', file: 'mods/pub/shell.js', line: 7 },
+    { id: 'aaa000000004', text: 'Welcome back', file: 'mods/pub/other.html', line: 3 },
+    { id: 'aaa000000005', text: 'Only on the other page', file: 'mods/pub/other.html', line: 5 },
+    { id: 'aaa000000006', text: 'Loaded late', file: 'mods/pub/late.js', line: 2 },
+    { id: 'aaa000000007', text: 'Studio — {{worldName}}', file: 'mods/pub/home.html', line: 1 },
+  ],
+};
+const PAGE = { id: 'builders:home', surface: 'builders', title: 'Home', files: ['mods/pub/home.html', 'mods/pub/shell.js', 'mods/pub/home.js'] };
+const matcher = reader.buildMatcher(REGISTRY);
+const place = (t) => reader.placeText(t, matcher, { files: PAGE.files, surfaceDir: 'mods/pub' });
+const fakeFs = { readFileSync: () => 'x' };
+const assemble = (captures, opts = {}) => reader.assembleReading(PAGE, captures, matcher, { surfaceDir: 'mods/pub', fsImpl: fakeFs, ...opts });
+
+test('an unplaced string is listed, not dropped', () => {
+  const r = assemble([{ state: 'default', strings: [
+    { text: 'Welcome back', section: 'Home', shared: null },
+    { text: 'A sentence no file in the registry holds', section: 'Home', shared: null },
+    { text: 'Welcome back', section: 'Later', shared: null },
+  ] }]);
+  const line = r.lines.find((l) => l.text === 'A sentence no file in the registry holds');
+  assert.ok(line, 'the unplaceable string is in the reading');
+  assert.equal(line.placement, 'unplaced');
+  assert.equal(line.section, 'Home');
+  assert.match(line.key, /^L\d{4}$/);
+  assert.equal(line.file, undefined, 'an unplaced line names no file');
+  assert.equal(r.counts.unplaced, 1);
+  assert.deepEqual(r.lines.map((l) => l.key), ['L0001', 'L0002', 'L0003'], 'keys run in page order');
+});
+
+test('an unplaced string that CONTAINS data keeps its words, with the data holed', () => {
+  const data = new Set(['Ada Lovelace', 'ready']);
+  const r = assemble([{ state: 'default', strings: [
+    { text: 'Good morning, Ada Lovelace', section: '', shared: null },
+    { text: 'Ada Lovelace', section: '', shared: null },
+    { text: '42', section: '', shared: null },
+  ] }], { dataValues: data });
+  assert.deepEqual(r.lines.map((l) => [l.text, l.placement]), [['Good morning, {…}', 'unplaced']]);
+  assert.equal(r.omitted.data, 1, 'the pure-data string is counted, and the number is not copy');
+});
+
+test('clock times and dates in an unplaced string are holed, so a re-read reads the same', () => {
+  assert.equal(reader.holeData('· since 10:43 PM', new Set()).text, '· since {…}');
+  assert.equal(reader.holeData('Filed Sep 10, 2026 · Blocking 2 tasks:', new Set()).text, 'Filed {…} · Blocking 2 tasks:');
+  assert.equal(reader.holeData('Jul 20, 2026', new Set()).data, true, 'a bare date is data');
+  assert.equal(reader.holeData('Licensed AGPL-3.0', new Set()).text, 'Licensed AGPL-3.0', 'a version number is left alone');
+});
+
+test('the registry is asked before the data: a placed string is never taken for data', () => {
+  const r = assemble([{ state: 'default', strings: [{ text: 'Welcome back', section: '', shared: null }] }], { dataValues: new Set(['Welcome back']) });
+  assert.equal(r.lines.length, 1);
+  assert.equal(r.lines[0].placement, 'placed');
+});
+
+test('placement: exact, pattern and segment; the page\'s own file wins; never another page\'s html', () => {
+  assert.deepEqual(place('Welcome back'), { file: 'mods/pub/home.html', line: 10, string_id: 'aaa000000001', text: 'Welcome back', how: 'exact' });
+  const pat = place('3 of 9 shipped this week');
+  assert.equal(pat.string_id, 'aaa000000002');
+  assert.equal(pat.text, '{…} of {…} shipped this week', 'a pattern-placed line reads as its row, with the registry\'s {…} holes');
+  assert.equal(place('shipped this week').string_id, 'aaa000000002', 'a literal segment of a holed row places');
+  assert.equal(place('Only on the other page'), null, 'a row in ANOTHER page\'s html does not place a string on this one');
+  assert.equal(place('Loaded late').file, 'mods/pub/late.js', 'a script elsewhere on the surface is the fallback');
+  assert.equal(place('Studio — Cloud Bongos').text, 'Studio — {{worldName}}', 'entities decode and a {{token}} is a hole');
+});
+
+test('shared text is marked shared, keeps its row, and stays out of reading_hash', () => {
+  const own = { text: 'Welcome back', section: 'Home', shared: null };
+  const a = assemble([{ state: 'default', strings: [{ text: 'Signed in as Ada. Sign out', section: '', shared: 'top bar' }, own] }]);
+  const top = a.lines[0];
+  assert.equal(top.placement, 'shared');
+  assert.equal(top.section, 'top bar');
+  assert.equal(top.string_id, 'aaa000000003');
+  const b = assemble([{ state: 'default', strings: [{ text: 'Something else entirely', section: '', shared: 'top bar' }, own] }]);
+  assert.equal(b.lines[0].placement, 'shared', 'an unplaceable shell string is still shared');
+  assert.equal(a.reading_hash, b.reading_hash, 'a changed shell line does not move the page\'s own hash');
+  const c = assemble([{ state: 'default', strings: [{ text: 'Welcome back', section: 'Elsewhere', shared: null }] }]);
+  assert.notEqual(a.reading_hash, c.reading_hash, 'a changed own line does');
+});
+
+test('other states add their lines where they sit, named, after the default state\'s', () => {
+  const r = assemble([
+    { state: 'closed', strings: [{ text: 'Welcome back', section: 'Home', shared: null }, { text: 'Loaded late', section: 'Home', shared: null }] },
+    { state: 'open', strings: [{ text: 'Welcome back', section: 'Home', shared: null }, { text: 'A panel only open shows', section: 'Home', shared: null }, { text: 'Loaded late', section: 'Home', shared: null }] },
+  ]);
+  assert.deepEqual(r.lines.map((l) => [l.text, l.state || null]), [['Welcome back', null], ['A panel only open shows', 'open'], ['Loaded late', null]]);
+  assert.deepEqual(r.states_read, ['closed', 'open']);
+});
+
+test('a string repeated in one section is one line with its occurrences', () => {
+  const r = assemble([{ state: 'default', strings: [1, 2, 3].map(() => ({ text: 'Welcome back', section: 'List', shared: null })) }]);
+  assert.equal(r.lines.length, 1);
+  assert.equal(r.lines[0].occurrences, 3);
+});
+
+test('files_hash folds CRLF, and moves when a file changes or disappears', () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'page-reader-'));
+  fs.writeFileSync(path.join(dir, 'a.html'), 'one\ntwo\n');
+  const lf = reader.filesHash(['a.html'], { root: dir });
+  fs.writeFileSync(path.join(dir, 'a.html'), 'one\r\ntwo\r\n');
+  assert.equal(reader.filesHash(['a.html'], { root: dir }), lf, 'a Windows checkout agrees with CI');
+  fs.writeFileSync(path.join(dir, 'a.html'), 'one\ntwo!\n');
+  assert.notEqual(reader.filesHash(['a.html'], { root: dir }), lf);
+  fs.rmSync(path.join(dir, 'a.html'));
+  assert.notEqual(reader.filesHash(['a.html'], { root: dir }), lf);
+});
+
+test('checkReadings names a missing reading, a changed page and an extra one', () => {
+  const inv = { pages: [{ id: 's:a', files: ['x'] }, { id: 's:b', files: ['y'] }] };
+  const f = { readFileSync: (p) => (p.endsWith('x') ? 'X' : 'Y') };
+  const good = reader.filesHash(['x'], { fsImpl: f });
+  const stale = reader.checkReadings(inv, { pages: [{ id: 's:a', files_hash: good }, { id: 's:gone', files_hash: 'z' }] }, { fsImpl: f });
+  assert.deepEqual(stale, [{ id: 's:b', why: 'no reading' }, { id: 's:gone', why: 'not in the inventory' }]);
+  assert.deepEqual(reader.checkReadings(inv, { pages: [{ id: 's:a', files_hash: 'old' }, { id: 's:b', files_hash: reader.filesHash(['y'], { fsImpl: f }) }] }, { fsImpl: f }), [{ id: 's:a', why: 'its files changed' }]);
+});
+
+test('the committed readings cover every inventory page, in the D3 shape', () => {
+  const inv = JSON.parse(fs.readFileSync(path.join(ROOT, reader.INVENTORY_REL), 'utf8'));
+  const doc = JSON.parse(fs.readFileSync(path.join(ROOT, reader.READINGS_REL), 'utf8'));
+  assert.deepEqual(doc.pages.map((p) => p.id), inv.pages.map((p) => p.id), 'one reading per inventory page, in inventory order');
+  let unplaced = 0;
+  for (const p of doc.pages) {
+    assert.ok(p.lines.length > 0, `${p.id} has lines`);
+    p.lines.forEach((l, i) => {
+      assert.equal(l.key, `L${String(i + 1).padStart(4, '0')}`, `${p.id} keys run in order`);
+      assert.ok(typeof l.section === 'string' && l.section, `${p.id} ${l.key} has a section`);
+      assert.ok(typeof l.text === 'string' && l.text, `${p.id} ${l.key} has text`);
+      assert.ok(reader.PLACEMENTS.includes(l.placement), `${p.id} ${l.key} placement`);
+      if (l.placement === 'placed') assert.ok(l.file && Number.isInteger(l.line) && /^[0-9a-f]{12}$/.test(l.string_id), `${p.id} ${l.key} names its registry row`);
+      if (l.placement === 'unplaced') { unplaced += 1; assert.equal(l.string_id, undefined); }
+    });
+    assert.equal(p.reading_hash, reader.readingHash(p.lines), `${p.id} reading_hash is over its lines`);
+    assert.equal(p.counts.lines, p.lines.length);
+  }
+  assert.ok(unplaced > 0, 'the real pages carry unplaced strings, and they are listed');
+  assert.deepEqual(reader.checkReadings(inv, doc), [], 'the committed readings match this tree (re-read: node scripts/gds/page-reader.js --stale)');
+});
+
+test('--check needs no browser and names the re-read command', () => {
+  // A preload that makes the browser driver unloadable: if --check ever reached
+  // for it, this run would fail.
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'page-reader-nobrowser-'));
+  const pre = path.join(dir, 'no-browser.cjs');
+  fs.writeFileSync(pre, "const M=require('module');const o=M._load;M._load=function(r,...a){if(/playwright|ui-design[\\\\/]kit/.test(r))throw new Error('browser reached: '+r);return o.call(this,r,...a);};\n");
+  const r = spawnSync(process.execPath, ['--require', pre, path.join(ROOT, 'scripts', 'gds', 'page-reader.js'), '--check'], { cwd: ROOT, encoding: 'utf8' });
+  assert.equal(r.status, 0, r.stderr || r.stdout);
+  assert.match(reader.REREAD_COMMAND, /page-reader\.js --stale/);
+  const src = fs.readFileSync(path.join(ROOT, 'scripts', 'gds', 'page-reader.js'), 'utf8');
+  assert.match(src, /Re-read them \(opens a browser\): \$\{REREAD_COMMAND\}/, 'a stale --check names the command');
+});
+
+test('ship-check runs the browser-free --check, and fitness does not render', () => {
+  const step = shipCheck.STEPS.find((s) => s.key === 'page-readings');
+  assert.ok(step, 'ship-check has a page-readings row');
+  assert.deepEqual(step.argv, ['scripts/gds/page-reader.js', '--check']);
+  assert.equal(step.fix, reader.REREAD_COMMAND);
+  const fitness = fs.readFileSync(path.join(ROOT, 'scripts', 'gds', 'fitness.js'), 'utf8');
+  assert.doesNotMatch(fitness, /page-reader/, 'fitness never runs the reader (a render is the builder\'s own command)');
+});
+
+test('a hall page with no states file is read once, at its own path', () => {
+  assert.deepEqual(reader.planRenders({ id: 'builders:x', surface: 'builders', path: '/x', states_files: [] }).map((p) => [p.state, p.url]), [['default', '/x']]);
+});