@bongos/core 1.21.175 → 1.21.176

package/scripts/bongos/copy-inventory.js

@@ -0,0 +1,571 @@
+#!/usr/bin/env node
+'use strict';
+//
+// scripts/bongos/copy-inventory.js — the COPY REGISTRY (R01 of goal 1000074, the
+// artist's loop; from idea 1000736).
+//
+// WHAT IT IS FOR. The owner's ABI brief gives the artist the project's TEXT: no
+// slop, story and ideology communicated, purpose and gravitas, re-text-writing.
+// None of that is exercisable today, because the copy is scattered across 23 hall
+// HTML files, 34 hall JS files, the status dashboard and a server-rendered landing
+// template. This command is the inventory that makes it findable — read-only: no
+// editing, no queue, no UI (those are R02/R03).
+//
+// DELIBERATELY IN THE gen-* FAMILY: pure-ish (fs only — no DB, no network, no
+// clock, no randomness), deterministic byte-for-byte on the same tree, emitting one
+// machine-readable registry and one human report. Same posture as gen-repo-map /
+// gen-api-docs: a command you run and commit.
+//
+// THE SURFACE MISMATCH, RECORDED RATHER THAN ASSUMED AWAY. The design contract
+// (modules/ui-design/docs/design-contract.md) says UI components live under
+// `src/ui/<surface>/`, and that a surface directory is the unit a design adapter
+// targets. This tree has no `src/ui/` at all (the adapters moved to
+// modules/ui-design/adapters/ in task 1003324) — the real UI is modules/hall-ui/public
+// and modules/status-ui/public.
+// So this tool maps REAL paths onto contract-shaped surface ids and reports the
+// mismatch in its own output. Do not "fix" that by pretending the contract layout
+// exists.
+//
+// EVERY ROW NAMES ITS RENDER PATH (`origin`), which is what makes the inventory
+// trustworthy: html-text, html-attr:<attr>, html-title, js-markup (text inside
+// markup a script builds), js-notice (toast/alert/confirm), js-text-assign
+// (.textContent/.innerText/.title). A string this tool cannot tie to one of those
+// paths is not listed at all — the first cut filtered "literals that look like
+// prose" and produced 2144 rows of mostly code, including `use strict` 34 times.
+//
+// Run:  node scripts/bongos/copy-inventory.js            (writes both artifacts)
+//       node scripts/bongos/copy-inventory.js --check     (exit 1 if artifacts stale)
+//       node scripts/bongos/copy-inventory.js --json      (registry to stdout, no write)
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { sameContent } = require('./gen-freshness'); // eol-insensitive freshness (CRLF checkouts)
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+// Repo-relative paths that end up INSIDE the checked-in artifacts are joined with
+// '/', never path.join: CI compares the committed bytes, so a Windows run baking
+// 'modules\hall-ui\public' in would rewrite ~1600 lines and never match again.
+// (fs still resolves forward slashes on Windows, so reads are unaffected.)
+const REGISTRY_REL = 'docs/copy-registry.json';
+const REPORT_REL = 'docs/copy-inventory.md';
+
+// The surfaces this tool knows how to read. `id` is the contract-shaped surface
+// name; `at` is where it REALLY lives. Adding a surface is a data edit — the point.
+const SURFACES = [
+  { id: 'builders-hall', kind: 'dir', at: 'modules/hall-ui/public', exts: ['.html', '.js'] },
+  { id: 'status-dashboard', kind: 'dir', at: 'modules/status-ui/public', exts: ['.html', '.js'] },
+  // THE LANDING SURFACE IS modules/public-landing/public/, NOT src/platform-server.js. The first
+  // cut pointed here at the server file, which only fs.readFileSync's these
+  // templates — so its JS patterns matched a handful of incidental literals and the
+  // page's ACTUAL copy (hero, meta/og text, every section) was silently absent
+  // while the registry reported a number. Caught by the grader on task 1003112.
+  { id: 'landing', kind: 'dir', at: 'modules/public-landing/public', exts: ['.html'] },
+];
+
+// Attributes whose value is COPY a person reads (not wiring). The matchers are
+// built ONCE — the first cut re-created all seven per markup literal.
+const COPY_ATTRS = ['title', 'aria-label', 'placeholder', 'alt', 'data-page-title', 'aria-description'];
+// The longest string the registry lists. A page tweak may rewrite a paragraph
+// past the old 400, and the applier then could not find its own words in the
+// registry it regenerates (task 1004768, the privacy page's round).
+const MAX_COPY_LEN = 2000;
+const COPY_ATTR_RES = COPY_ATTRS.map((attr) => ({ attr, re: new RegExp(`\\b${attr}\\s*=\\s*"([^"]{4,${MAX_COPY_LEN}})"`, 'gi') }));
+
+// What this tool knowingly does not see. Printed in the report — an inventory that
+// implies completeness it does not have is worse than a short one.
+const BLIND_SPOTS = [
+  'Landing-page transforms: `modules/public-landing/public/*.html` is scanned as authored, but the server rewrites it before a visitor sees it — `{{token}}` placeholders are filled from the branding pack, and `<!--apex-only:start--> … <!--apex-only:end-->` sections are STRIPPED on a child instance (src/platform-server.js `landingPage()`). So a row here may be copy that this instance never renders, and a rendered sentence may differ from its authored form.',
+  'Server-side messages: route failures (`res.fail` reasons), validation text and API error copy live in server JS and are not walked here. A person reads them, so widening to them is a deliberate later step, not an oversight to quietly fix.',
+  'Skill and playbook prose: `.claude/skills/**/SKILL.md` is read by agents and by builders and is arguably the largest body of project voice. Out of scope on purpose — it is not UI, and mixing it in would drown the UI signal.',
+  'Discord copy: outbound broadcast text is composed in `modules/discord/*.js` at send time. User-facing, but not part of any UI surface.',
+  'JS literals with no render path: a string is listed only when it can be tied to one — markup built in a script, a toast/alert/confirm argument, or a textContent/innerText/title assignment. Copy reaching the DOM by any other route (a helper that takes a message parameter, a string held in a config object) is invisible here, deliberately: the alternative is a queue where most rows are code.',
+  'Template literals containing a nested backtick: the literal scanner stops at the first closing backtick, so a nested template inside `${...}` truncates that one literal. Rare in this tree and cheap to spot (a row that ends mid-sentence); a real JS parser is the fix if it ever matters.',
+  'Runtime-composed strings: anything assembled from fragments or interpolated at render time is captured only as its literal parts. A sentence that exists only once the browser runs cannot be inventoried by reading the tree.',
+  'Generated pages: `docs/api-reference.md` and the OpenAPI surface are generated from route prose; that copy belongs to its generator, not to a designer.',
+  'The design-contract surface layout: `modules/ui-design/docs/design-contract.md` expects `src/ui/<surface>/`, which this tree does not use (there is no `src/ui/`; the adapters live in `modules/ui-design/adapters/`). Surface ids here are a MAPPING onto real paths, not evidence the contract layout exists.',
+];
+
+// A stable id survives the string MOVING: it hashes surface + normalized text,
+// never file or line. That is what lets a flag (R02) stay attached across
+// refactors — and two identical strings in one surface share an id, which is a
+// feature: they are one piece of copy shown twice.
+function stableId(surfaceId, text) {
+  const norm = text.replace(/\s+/g, ' ').trim();
+  return crypto.createHash('sha256').update(`${surfaceId} ${norm}`).digest('hex').slice(0, 12);
+}
+
+// Locale-independent string order — see the note on the entries sort below.
+function cmp(a, b) {
+  if (a === b) return 0;
+  return a < b ? -1 : 1;
+}
+
+// Line lookup without rescanning. The first cut counted newlines from offset 0 for
+// EVERY extracted string — O(n x matches) on the extractor's hottest loop (bounded
+// at ~62 files / ~1096 matches today, but needlessly quadratic-shaped; the grader
+// was right to flag it). One offset table per source, then a binary search.
+function lineIndex(source) {
+  const starts = [0];
+  for (let i = 0; i < source.length; i += 1) if (source[i] === '\n') starts.push(i + 1);
+  return starts;
+}
+
+function lineAt(starts, index) {
+  let lo = 0;
+  let hi = starts.length - 1;
+  while (lo < hi) {
+    const mid = (lo + hi + 1) >> 1;
+    if (starts[mid] <= index) lo = mid; else hi = mid - 1;
+  }
+  return lo + 1;
+}
+
+// Does this look like prose a person reads, rather than code that happens to be a
+// string? Conservative on purpose — a false positive costs an artist's attention.
+//
+// Measured with CRLF folded to LF: the length cap must give a multi-line run the
+// same verdict on a Windows checkout as on CI's, or the committed registry differs
+// by platform (task 1004545 — a 396-char run was 403 under CRLF and vanished).
+function looksLikeCopy(raw) {
+  const s = String(raw).replace(/\r\n/g, '\n').trim();
+  if (s.length < 4 || s.length > MAX_COPY_LEN) return false;
+  if (!/[A-Za-z]{2}/.test(s)) return false;               // needs actual letters
+  if (!/\s/.test(s) && !/[.!?]$/.test(s)) return false;   // one bare word is a token
+  if (/^[/.#]/.test(s)) return false;                     // paths, selectors
+  if (/^https?:/i.test(s)) return false;                  // urls
+  if (/^[a-z0-9-]+$/.test(s)) return false;               // css class / slug
+  if (/^[A-Z0-9_]+$/.test(s)) return false;               // CONSTANT_NAME
+  if (/=>|\$\{|function\s*\(/.test(s)) return false;      // code fragments
+  if (/^[\s\d.,:%$-]+$/.test(s)) return false;            // numbers and units
+  return true;
+}
+
+// THE SPAN: where a row's text physically SITS in the file, as [start, end)
+// character offsets. Every extractor below records one alongside the text.
+//
+// It is deliberately NOT part of the committed registry — buildRegistry drops it
+// (see the note there). A committed offset would go stale on the next edit to an
+// unrelated line of the same file, and the registry's whole point is an id that
+// survives movement. The span is a LIVE fact, recomputed from the tree by whoever
+// needs it: today that is scripts/bongos/copy-apply.js (R03 of goal 1000074), which
+// re-runs this extractor against the working tree and uses the span to replace
+// exactly the characters a string occupies and nothing else. Deriving it here,
+// beside the regex that captured the text, is what keeps the applier from owning
+// a second, drifting copy of these matching rules.
+//
+// The span covers the TRIMMED text — a row's `text` is whitespace-collapsed and
+// trimmed, so the indentation around a multi-line literal belongs to the file's
+// formatting, not to the copy, and an applier must leave it alone.
+function trimmedSpan(group, groupStart) {
+  const lead = group.length - group.replace(/^\s+/, '').length;
+  const trail = group.length - group.replace(/\s+$/, '').length;
+  return { start: groupStart + lead, end: groupStart + group.length - trail };
+}
+
+// Strip HTML comments and <script>/<style> bodies so their contents are not read
+// as page text. Replaced with spaces of equal length so every line number — and
+// every span copy-apply.js writes through — stays truthful.
+//
+// Comments are author notes, never something a visitor reads (task 1004545: a
+// header comment's literal `<a>` opened a fake text node). ONE alternation, not
+// three passes, so whichever construct opens first wins, as in a browser: a
+// `<style>` named inside a comment cannot swallow the page up to the real
+// `</style>`, and a `<!--` inside a script string cannot eat past `</script>`.
+//
+// A comment keeps its `<` and `>` and blanks only its inside: marker comments
+// (`<!--apex-only:start-->`, `<!--brand-if:…-->`) split a sentence into segments
+// the server shows or drops independently, so each segment must stay its own row
+// with its own stable id — blanking the whole comment would fuse them.
+function stripEmbedded(html) {
+  return html.replace(/<!--[\s\S]*?-->|<script\b[\s\S]*?<\/script>|<style\b[\s\S]*?<\/style>/gi, (m) => {
+    const blank = m.replace(/[^\r\n]/g, ' ');
+    return m.startsWith('<!--') ? `<${blank.slice(1, -1)}>` : blank;
+  });
+}
+
+function fromHtml({ source, rel }) {
+  const out = [];
+  const cleaned = stripEmbedded(source);
+  // stripEmbedded preserves every newline, so one offset table serves both strings.
+  const starts = lineIndex(cleaned);
+  let m;
+
+  // 1. text nodes: everything between a '>' and the next '<'.
+  const textRe = />([^<>]+)</g;
+  while ((m = textRe.exec(cleaned)) !== null) {
+    if (!looksLikeCopy(m[1])) continue;
+    // The captured group opens one character past the '>' that anchored the match.
+    out.push({ text: m[1].replace(/\s+/g, ' ').trim(), file: rel, line: lineAt(starts, m.index), origin: 'html-text', confidence: 'certain', ...trimmedSpan(m[1], m.index + 1) });
+  }
+
+  // 2. copy-bearing attributes.
+  for (const { attr, re } of COPY_ATTR_RES) {
+    re.lastIndex = 0;
+    while ((m = re.exec(cleaned)) !== null) {
+      if (!looksLikeCopy(m[1])) continue;
+      // Every COPY_ATTR_RE ends with the closing quote, so the group's last
+      // character sits exactly one before the match's end. DERIVED, never
+      // searched for — indexOf would land on an earlier copy of the same text.
+      const attrStart = m.index + m[0].length - 1 - m[1].length;
+      out.push({ text: m[1].replace(/\s+/g, ' ').trim(), file: rel, line: lineAt(starts, m.index), origin: `html-attr:${attr}`, confidence: 'certain', ...trimmedSpan(m[1], attrStart) });
+    }
+  }
+
+  // 3. <title> is the page's own name — always copy.
+  const titleRe = /<title>([^<]{2,200})<\/title>/gi;
+  while ((m = titleRe.exec(cleaned)) !== null) {
+    const titleStart = m.index + '<title>'.length;
+    out.push({ text: m[1].replace(/\s+/g, ' ').trim(), file: rel, line: lineAt(starts, m.index), origin: 'html-title', confidence: 'certain', ...trimmedSpan(m[1], titleStart) });
+  }
+  return out;
+}
+
+// JS copy is found by FOLLOWING RENDER PATHS, not by guessing at prose. The first
+// cut of this file filtered "literals that look like sentences" and produced 2144
+// rows of which most were code: `use strict` 34 times, CSS values, and fragments of
+// template literals sliced at their quotes. Precision beats recall for a queue an
+// artist actually reads, so this extractor only claims a string when it can name
+// HOW a person sees it:
+//
+//   • markup built in JS — any literal containing tags is parsed as HTML, so the
+//     TEXT inside it is captured (not the tags). Template interpolations become a
+//     `{…}` placeholder, which keeps a sentence readable while marking the hole.
+//   • toast() / alert() / confirm() arguments — shown verbatim to a person.
+//   • .textContent / .innerText / .title assignments — same.
+//
+// Everything else is skipped, and the report says so. A literal this tool cannot
+// tie to a render path is not evidence of copy.
+const PLACEHOLDER = '{…}';
+
+// Template literals + quoted strings. Template bodies may contain ${...}; the
+// no-nested-backtick limitation is real and recorded in BLIND_SPOTS.
+const JS_LITERALS = /`([^`]*)`|'((?:[^'\\\n]|\\.)*)'|"((?:[^"\\\n]|\\.)*)"/g;
+const UI_CALL = /\b(?:toast|alert|confirm)\s*\(\s*(?:`([^`]*)`|'((?:[^'\\\n]|\\.)*)'|"((?:[^"\\\n]|\\.)*)")/g;
+const TEXT_ASSIGN = /\.(?:textContent|innerText|title)\s*=\s*(?:`([^`]*)`|'((?:[^'\\\n]|\\.)*)'|"((?:[^"\\\n]|\\.)*)")/g;
+
+function unescapeLiteral(raw) {
+  return String(raw).replace(/\\(['"`\\])/g, '$1');
+}
+
+// Can offsets into this match's BODY be read as offsets into the file?
+//
+// A template literal (group 1) is used raw, so yes. A quoted literal is
+// `unescapeLiteral`d first, and that SHIFTS every character after a backslash —
+// so yes only when the unescape changed nothing. The alternative, an
+// escape-aware index map, would buy spans for a handful of quoted-markup rows
+// and add a second place for the escaping rules to be wrong. A row with no span
+// is refused BY NAME in copy-apply.js instead, which is the honest trade.
+function literalIsUnshifted(m) {
+  if (m[1] !== undefined) return true;
+  const raw = m[2] ?? m[3];
+  return raw === undefined ? false : unescapeLiteral(raw) === raw;
+}
+
+// Interpolations are replaced by a fixed-width PLACEHOLDER before matching, so a
+// position in the holed string is NOT a position in the source. This records the
+// literal runs between the holes so one can be converted back to the other —
+// which is what lets a markup row carry a source span (see `trimmedSpan`).
+//
+// The conversion is only ever asked for at a capture BOUNDARY, and every boundary
+// sits on a real character: a text node's group opens just past a '>' and closes
+// just before a '<', and neither can appear inside `{…}`. A boundary that lands
+// where a hole meets the next run resolves to the character after the closing
+// '}' of the interpolation, which is the right place to cut.
+function holeMap(body) {
+  const re = /\$\{[^{}]*\}/g;
+  const runs = [];
+  let withHoles = '';
+  let last = 0;
+  let m;
+  while ((m = re.exec(body)) !== null) {
+    const literal = body.slice(last, m.index);
+    runs.push({ holed: withHoles.length, raw: last, length: literal.length });
+    withHoles += literal + PLACEHOLDER;
+    last = m.index + m[0].length;
+  }
+  const tail = body.slice(last);
+  runs.push({ holed: withHoles.length, raw: last, length: tail.length });
+  return { withHoles: withHoles + tail, runs };
+}
+
+function holedToRaw(runs, at) {
+  for (const run of runs) {
+    if (at >= run.holed && at <= run.holed + run.length) return run.raw + (at - run.holed);
+  }
+  return null; // only reachable for a position strictly inside a placeholder
+}
+
+// A literal that carries markup: extract what a person reads out of it, each row
+// carrying [start, end) offsets into the RAW body it was found in.
+function copyFromMarkupLiteral(body) {
+  const { withHoles, runs } = holeMap(body);
+  const out = [];
+  const emit = (group, groupStart) => {
+    const t = group.replace(/\s+/g, ' ').trim();
+    if (t === PLACEHOLDER || !looksLikeCopy(t.replace(/\{…\}/g, 'x'))) return;
+    const span = trimmedSpan(group, groupStart);
+    const start = holedToRaw(runs, span.start);
+    const end = holedToRaw(runs, span.end);
+    // A span that cannot be mapped back is reported as text with no span rather
+    // than as a guess; the applier refuses such a row by name.
+    out.push(start === null || end === null ? { text: t } : { text: t, start, end });
+  };
+  let m;
+  const textRe = />([^<>]+)</g;
+  while ((m = textRe.exec(withHoles)) !== null) emit(m[1], m.index + 1);
+  for (const { re } of COPY_ATTR_RES) {
+    re.lastIndex = 0;
+    while ((m = re.exec(withHoles)) !== null) emit(m[1], m.index + m[0].length - 1 - m[1].length);
+  }
+  return out;
+}
+
+function fromJs({ source, rel }) {
+  const out = [];
+  const starts = lineIndex(source);
+  const seen = new Set(); // (text, line) — one row per string per site
+  const push = (text, index, origin, span = null) => {
+    const line = lineAt(starts, index);
+    const key = `${text}\u0000${line}\u0000${origin}`;
+    if (seen.has(key)) return;
+    seen.add(key);
+    out.push({ text, file: rel, line, origin, confidence: 'certain', ...(span || {}) });
+  };
+
+  let m;
+  // 1. markup built in JS.
+  JS_LITERALS.lastIndex = 0;
+  while ((m = JS_LITERALS.exec(source)) !== null) {
+    const body = m[1] ?? unescapeLiteral(m[2] ?? m[3] ?? '');
+    if (!body || !/<[a-zA-Z/]/.test(body) || !/>/.test(body)) continue;
+    // Each alternative opens with exactly one delimiter, so the body starts one
+    // character past the match.
+    const mapped = literalIsUnshifted(m);
+    for (const f of copyFromMarkupLiteral(body)) {
+      const span = mapped && f.start !== undefined
+        ? { start: m.index + 1 + f.start, end: m.index + 1 + f.end }
+        : null;
+      push(f.text, m.index, 'js-markup', span);
+    }
+  }
+  // 2. strings shown directly to a person. Both of these normalize the WHOLE
+  // literal into the row's text, so the span is the whole body: the delimiter
+  // closes the match, so the body ends one character before the match does.
+  const wholeLiteral = (re, origin) => {
+    re.lastIndex = 0;
+    while ((m = re.exec(source)) !== null) {
+      const rawBody = m[1] ?? m[2] ?? m[3] ?? '';
+      const body = (m[1] ?? unescapeLiteral(m[2] ?? m[3] ?? '')).replace(/\$\{[^{}]*\}/g, PLACEHOLDER).replace(/\s+/g, ' ').trim();
+      if (!body || !looksLikeCopy(body.replace(/\{…\}/g, 'x'))) continue;
+      const bodyStart = m.index + m[0].length - 1 - rawBody.length;
+      push(body, m.index, origin, literalIsUnshifted(m) ? trimmedSpan(rawBody, bodyStart) : null);
+    }
+  };
+  wholeLiteral(UI_CALL, 'js-notice');
+  wholeLiteral(TEXT_ASSIGN, 'js-text-assign');
+  return out;
+}
+
+function filesFor(surface, { fsImpl = fs } = {}) {
+  const abs = path.join(REPO_ROOT, surface.at);
+  if (surface.kind === 'file') return fsImpl.existsSync(abs) ? [surface.at] : [];
+  if (!fsImpl.existsSync(abs)) return [];
+  return fsImpl.readdirSync(abs)
+    .filter((n) => surface.exts.includes(path.extname(n)))
+    .sort()
+    .map((n) => `${surface.at}/${n}`);
+}
+
+function buildRegistry() {
+  const entries = [];
+  const surfaces = {};
+  for (const surface of SURFACES) {
+    const rels = filesFor(surface);
+    let count = 0;
+    for (const rel of rels) {
+      const source = fs.readFileSync(path.join(REPO_ROOT, rel), 'utf8');
+      const found = path.extname(rel) === '.html'
+        ? fromHtml({ source, rel })
+        : fromJs({ source, rel });
+      for (const f of found) {
+        // THE SPAN IS DROPPED HERE, DELIBERATELY. Every extractor records where a
+        // string physically sits (see `trimmedSpan`), and none of it is committed:
+        // an offset goes stale the moment anything above it in the file changes,
+        // so a registry carrying one would be wrong far more often than the id —
+        // which is designed to survive exactly that movement — ever is. The span
+        // is recomputed from the tree by the applier, at the moment it edits.
+        const { start, end, ...row } = f;
+        entries.push({ id: stableId(surface.id, f.text), surface: surface.id, ...row });
+        count += 1;
+      }
+    }
+    surfaces[surface.id] = { at: surface.at, files: rels.length, strings: count };
+  }
+
+  // Deterministic order, independent of walk order: surface, text, file, line.
+  // BYTE ORDER, NOT localeCompare: these artifacts are committed, and
+  // localeCompare's collation depends on the runtime's ICU data — a Node built with
+  // small-icu would reshuffle the file and every unrelated commit would carry the
+  // churn. `cmp` is boring on purpose.
+  entries.sort((a, b) => cmp(a.surface, b.surface)
+    || cmp(a.text, b.text)
+    || cmp(a.file, b.file)
+    || a.line - b.line);
+
+  // Duplicate copy is the cheapest of the three signals R02 wants, and needs no
+  // judgement: the same normalized text in one surface, shown in more than one place.
+  const byId = new Map();
+  for (const e of entries) {
+    if (!byId.has(e.id)) byId.set(e.id, []);
+    byId.get(e.id).push(e);
+  }
+  const duplicates = [...byId.entries()]
+    .filter(([, list]) => list.length > 1)
+    .map(([id, list]) => ({
+      id, surface: list[0].surface, text: list[0].text,
+      occurrences: list.length, at: list.map((e) => `${e.file}:${e.line}`),
+    }))
+    .sort((a, b) => b.occurrences - a.occurrences || cmp(a.text, b.text));
+
+  return {
+    schema: 1,
+    generator: 'scripts/bongos/copy-inventory.js',
+    goal: 1000074,
+    counts: {
+      strings: entries.length,
+      unique_ids: byId.size,
+      certain: entries.filter((e) => e.confidence === 'certain').length,
+      heuristic: entries.filter((e) => e.confidence === 'heuristic').length,
+      duplicate_ids: duplicates.length,
+    },
+    surfaces,
+    blind_spots: BLIND_SPOTS,
+    duplicates,
+    entries,
+  };
+}
+
+function renderReport(reg) {
+  const L = [];
+  const esc = (s) => s.replace(/\|/g, '\\|');
+  L.push('# Copy inventory — every string the product shows a person');
+  L.push('');
+  L.push('> **Generated** by `node scripts/bongos/copy-inventory.js` (R01 of goal 1000074, the artist\'s loop).');
+  L.push('> Deterministic on a given tree — regenerate and commit rather than hand-editing.');
+  L.push('> Machine-readable twin: [`copy-registry.json`](copy-registry.json).');
+  L.push('');
+  L.push(`**${reg.counts.strings} strings** across ${Object.keys(reg.surfaces).length} surfaces · `
+    + `${reg.counts.unique_ids} distinct pieces of copy · ${reg.counts.certain} certain, ${reg.counts.heuristic} heuristic · `
+    + `${reg.counts.duplicate_ids} shown in more than one place.`);
+  L.push('');
+  L.push('## Surfaces');
+  L.push('');
+  L.push('| surface | lives at | files | strings |');
+  L.push('|---|---|---|---|');
+  for (const [id, s] of Object.entries(reg.surfaces)) {
+    L.push(`| \`${id}\` | \`${s.at}\` | ${s.files} | ${s.strings} |`);
+  }
+  L.push('');
+  L.push('## Confidence, and why it is on every row');
+  L.push('');
+  L.push('`certain` copy comes from markup only a person reads: an HTML text node, a `<title>`, or a copy-bearing attribute. `heuristic` copy is a JavaScript string literal that passed a prose filter — this tool does not parse JS, so a filtered literal is evidence, not proof. Treat a heuristic row as a candidate an artist confirms, and do not quote the total as "the number of strings in the product".');
+  L.push('');
+  L.push('## What this cannot see');
+  L.push('');
+  for (const b of reg.blind_spots) L.push(`- ${b}`);
+  L.push('');
+  if (reg.duplicates.length) {
+    L.push('## The same words, shown twice');
+    L.push('');
+    L.push('Identical copy within one surface. Sometimes right (a repeated button), sometimes two screens that should share one string.');
+    L.push('');
+    L.push('| id | shown | text | where |');
+    L.push('|---|---|---|---|');
+    for (const d of reg.duplicates.slice(0, 40)) {
+      L.push(`| \`${d.id}\` | ${d.occurrences}x | ${esc(d.text).slice(0, 90)} | ${d.at.slice(0, 3).join(', ')} |`);
+    }
+    if (reg.duplicates.length > 40) L.push(`| … | | _${reg.duplicates.length - 40} more in the JSON registry_ | |`);
+    L.push('');
+  }
+  for (const [surfaceId] of Object.entries(reg.surfaces)) {
+    const rows = reg.entries.filter((e) => e.surface === surfaceId);
+    if (!rows.length) continue;
+    L.push(`## \`${surfaceId}\` — ${rows.length} strings`);
+    L.push('');
+    L.push('| id | conf | text | where |');
+    L.push('|---|---|---|---|');
+    for (const e of rows) {
+      L.push(`| \`${e.id}\` | ${e.confidence === 'certain' ? 'certain' : 'heur'} | ${esc(e.text).slice(0, 110)} | \`${e.file}:${e.line}\` |`);
+    }
+    L.push('');
+  }
+  L.push('---');
+  L.push('');
+  L.push('Ids are stable across moves: a string keeps its id when it changes file or line, and loses it when its TEXT changes — which is exactly when a flag against it should be re-examined.');
+  L.push('');
+  return L.join('\n');
+}
+
+// Is the artifact on disk still what the generator would write? Freshness is a
+// question about CONTENT, so CRLF-vs-LF is not a difference — the eol-blind compare
+// is gen-freshness.sameContent, shared with the other six generators, and its header
+// carries the full why (task 1003619 hit it here: a Windows checkout reads back the
+// CRLF git wrote, so a byte compare reported STALE forever on content that was
+// byte-identical in the index — a permanently red gate teaches builders to wave past
+// the one check that catches a REAL stale artifact). Only \r\n is folded, NOT a lone
+// \r, so a genuinely corrupt file cannot read as fresh.
+//
+// The one thing that is local, and the reason this wrapper exists rather than a bare
+// sameContent() at the call site: a MISSING file is stale by definition. sameContent
+// would coerce a null `have` to '' and call it fresh against an empty `want`.
+// Not used on the write path — generated files are still written with LF endings.
+// Pure + exported so the decision is unit-testable without writing to the committed
+// artifacts (same shape as shouldRefuseSessionClaim in modules/lifecycle/routes/claims.js).
+function matchesGenerated(have, want) {
+  if (have === null || have === undefined) return false;
+  return sameContent(have, want);
+}
+
+function write({ check = false } = {}) {
+  const reg = buildRegistry();
+  const json = `${JSON.stringify(reg, null, 2)}\n`;
+  const md = renderReport(reg);
+  const jsonPath = path.join(REPO_ROOT, REGISTRY_REL);
+  const mdPath = path.join(REPO_ROOT, REPORT_REL);
+  if (check) {
+    const stale = [];
+    for (const [p, want] of [[jsonPath, json], [mdPath, md]]) {
+      const have = fs.existsSync(p) ? fs.readFileSync(p, 'utf8') : null;
+      if (!matchesGenerated(have, want)) stale.push(path.relative(REPO_ROOT, p));
+    }
+    return { reg, stale };
+  }
+  fs.writeFileSync(jsonPath, json);
+  fs.writeFileSync(mdPath, md);
+  return { reg, written: [REGISTRY_REL, REPORT_REL] };
+}
+
+if (require.main === module) {
+  const args = process.argv.slice(2);
+  if (args.includes('--json')) {
+    process.stdout.write(`${JSON.stringify(buildRegistry(), null, 2)}\n`);
+  } else if (args.includes('--check')) {
+    const { stale } = write({ check: true });
+    if (stale.length) {
+      console.error(`copy-inventory: STALE — ${stale.join(', ')} do not match the tree. Run: node scripts/bongos/copy-inventory.js`);
+      process.exit(1);
+    }
+    console.log('copy-inventory: artifacts match the tree.');
+  } else {
+    const { reg, written } = write();
+    console.log(`copy-inventory: ${reg.counts.strings} strings (${reg.counts.certain} certain, ${reg.counts.heuristic} heuristic), `
+      + `${reg.counts.duplicate_ids} duplicated -> wrote ${written.join(', ')}`);
+  }
+}
+
+module.exports = {
+  SURFACES, COPY_ATTRS, BLIND_SPOTS, MAX_COPY_LEN, REGISTRY_REL, REPORT_REL,
+  cmp, stableId, looksLikeCopy, lineIndex, lineAt, stripEmbedded, fromHtml, fromJs, filesFor,
+  buildRegistry, renderReport, write, matchesGenerated,
+};