geneseed 3.1.1 → 3.1.2

package/js/inspect/checks-build.mjs

@@ -0,0 +1,231 @@
+/**
+ * The checks over what the BUILD produced — rendered bytes, themes, colours, links.
+ *
+ * Every export here answers with an array of problem strings, empty when it finds nothing.
+ * That shape is the whole contract: `doctorCollect` in `doctor.mjs` concatenates them and
+ * a clean run is byte-identical whichever check is missing, which is why each one is gated
+ * by a PLANTED FAULT in `tests/unit/harness.test.mjs` rather than by a comparison.
+ */
+import path from 'node:path';
+import { stripCapabilityLinks } from '../build/emit-common.mjs';
+import { STRUCTURE, renderAll } from '../build/render.mjs';
+import { CONFIG, makeCfg } from '../build/source.mjs';
+import { hostCatalogsNatively, resolvePath } from '../hosts/hosts.mjs';
+import { EMIT_HOST_SCOPE, footprintOfDir, themeFiles } from '../hosts/installs.mjs';
+import { isVendoredPath } from '../hosts/native.mjs';
+import { PALETTE_ROLES, colorThemeFiles } from '../hosts/opencode.mjs';
+import { readText, withDiscardableStderr } from '../lib/fs.mjs';
+import { parseJson, formatRepr } from '../lib/json.mjs';
+import {
+  ABS_LINK_RE, LINK_RE, TOKEN_RE, has, isDir, isFile, rglob, stemOf, stripCode, within,
+} from './scan.mjs';
+import { existsSync, readFileSync } from 'node:fs';
+
+// --------------------------------------------------------------------------------------
+// the checks
+// --------------------------------------------------------------------------------------
+
+/**
+ * `_harness_build._link_problems` — dead links AND non-hermetic ones.
+ *
+ * Hermeticity is what lets a bundle be copied or subtree-split into any repo; a link that
+ * escapes `out` breaks it silently. The two are separate messages because they have separate
+ * causes, and a target that merely does not exist is the DEAD one — the absolute check runs
+ * first and returns, so `~/x.md` never reaches the filesystem at all.
+ */
+export function linkProblems(md, text, out, rel) {
+  const problems = [];
+  for (const m of stripCode(text).matchAll(LINK_RE)) {
+    const link = m[1];
+    const raw = link.split('#')[0].trim();
+    if (!raw) continue;
+    if (ABS_LINK_RE.test(raw)) {
+      problems.push(`non-hermetic absolute link '${link}' in ${rel}`);
+      continue;
+    }
+    // `(md.parent / raw).resolve()` — `resolvePath`, not `path.resolve`, because Python's
+    // canonicalises the symlinks in the part that exists and this comparison is against an
+    // `out` that went through the same call.
+    const target = resolvePath(path.join(path.dirname(md), raw));
+    if (!existsSync(target)) problems.push(`dead link '${link}' in ${rel}`);
+    else if (!within(target, out)) {
+      problems.push(`non-hermetic link '${link}' escapes the bundle in ${rel}`);
+    }
+  }
+  return problems;
+}
+
+/**
+ * `_harness_build._check_build` — scan one rendered tree for unresolved tokens and bad links.
+ *
+ * `isVendored` decides which relative shape counts as a vendored folder, and the two callers
+ * pass different ones ON PURPOSE: a `files`/opencode-global bundle nests skills at
+ * `skills/<name>/…` and a per-repo native layer one level deeper at `.claude/skills/<name>/…`.
+ * Vendored folders are verbatim upstream docs carrying their own license, and their internal
+ * cross-links point at the upstream project's own files, so they are exempt.
+ *
+ * `rel` is `str(Path)`, i.e. the platform's separator, because that is what the Python prints
+ * — every emit-scan cell in the acceptance matrix names a backslash on Windows.
+ */
+export function checkBuild(themeName, out, isVendored = isVendoredPath) {
+  const outAbs = resolvePath(out);
+  const problems = [];
+  for (const md of rglob(outAbs)) {
+    if (!md.endsWith('.md') || !isFile(md)) continue;
+    const rel = path.relative(outAbs, md);
+    if (isVendored(rel)) continue;
+    const text = readText(md);
+    // `set(TOKEN_RE.findall(text))` — Python iterates the set in ITS order, and the whole
+    // list is sorted by `_doctor_collect` before printing, so only uniqueness travels.
+    for (const tok of new Set(text.match(TOKEN_RE) ?? [])) {
+      problems.push(`[${themeName}] unresolved token ${tok} in ${rel}`);
+    }
+    for (const p of linkProblems(md, text, outAbs, rel)) problems.push(`[${themeName}] ${p}`);
+  }
+  return problems;
+}
+
+/**
+ * `_harness_build._theme_parity_problems` — every theme defines the same VOICE keys.
+ *
+ * A token present in one theme map and missing from another renders as a raw `{{TOKEN}}`
+ * only in the files that use it and only under that theme, so a plain build can miss it
+ * entirely. The maps are compared directly, in every mode, whatever `--theme` scoped the rest
+ * of the run to.
+ */
+export function themeParityProblems() {
+  const themes = new Map();
+  for (const p of themeFiles()) {
+    let doc;
+    try { doc = JSON.parse(readText(p)); } catch (e) {
+      return [`[themes] ${path.basename(p)} unreadable: ${e.message}`];
+    }
+    themes.set(stemOf(p), doc);
+  }
+  if (themes.size < 2) return [];
+  const allKeys = new Set();
+  for (const t of themes.values()) for (const k of Object.keys(t)) allKeys.add(k);
+  const problems = [];
+  for (const [name, t] of themes) {
+    for (const k of [...allKeys].filter((x) => !has(t, x)).sort()) {
+      problems.push(`[themes] '${name}' missing key {${k}} (defined in another theme)`);
+    }
+  }
+  return problems;
+}
+
+/** `_harness_build._HEX_RE`. Anchored at BOTH ends, so `#12345` and `#1122334` both fail. */
+const HEX_RE = /^#[0-9a-fA-F]{6}$/;
+
+/**
+ * `_harness_build._color_theme_problems` — every curated colour theme carries the full
+ * palette, in 6-digit hex. Voice-theme parity, for colours.
+ *
+ * TWO OF ITS THREE ARMS ARE UNREACHABLE FROM ANY CELL, and it is doctor's own ordering that
+ * makes them so: the opencode-global emit reads the same files (`writeColorThemes` ->
+ * `palette[role]`) and runs BEFORE this check, so a palette that is missing a role, or
+ * missing entirely, kills the emit rather than reaching here. The consumer is stricter than
+ * the gate. Only the third arm — a value present and not `#rrggbb` — passes the emit through
+ * to be reported.
+ */
+export function colorThemeProblems() {
+  const problems = [];
+  for (const p of colorThemeFiles(makeCfg())) {
+    let spec;
+    try { spec = JSON.parse(readText(p)); } catch (e) {
+      problems.push(`[colors] ${path.basename(p)} unreadable: ${e.message}`);
+      continue;
+    }
+    const pal = spec.palette;
+    if (pal === null || typeof pal !== 'object' || Array.isArray(pal)) {
+      problems.push(`[colors] ${path.basename(p)} has no 'palette' object`);
+      continue;
+    }
+    for (const role of [...PALETTE_ROLES].filter((r) => !has(pal, r)).sort()) {
+      problems.push(`[colors] '${stemOf(p)}' palette missing role '${role}'`);
+    }
+    for (const [role, val] of Object.entries(pal)) {
+      if (!(typeof val === 'string' && HEX_RE.test(val))) {
+        problems.push(`[colors] '${stemOf(p)}' role '${role}' is not #rrggbb hex: ${formatRepr(val)}`);
+      }
+    }
+  }
+  return problems;
+}
+
+/**
+ * `_harness_build._rendered_problems` — a committed bundle must match a fresh render of
+ * `src/` for its OWN recorded theme, emit and footprint.
+ *
+ * Doctor's temp builds never touch the committed bundle, so drift there is invisible to
+ * every other check. All three values are read back off the bundle's own markers rather than
+ * assumed, and each for the same reason: assuming one reports every file as drifted the
+ * moment that default moves, which is a diagnosis about this function rather than about the
+ * bundle. The emit marker is the one that took longest to learn — a host that catalogues
+ * capabilities to the model itself gets AGENT.md's tables collapsed to a pointer, and the
+ * OpenCode emits additionally strip the per-row spec links, so rendering the portable shape
+ * and comparing it against an OpenCode bundle reports AGENT.md stale on EVERY run with no
+ * rebuild able to clear it.
+ *
+ * Host-state files (context.json, MEMORY.md, the markers) are created once and never
+ * rendered, so they are not in the render set and are correctly ignored. Notebook files
+ * except its `.gitignore` are seed-once and agent-owned after the first build, so they are
+ * compared only for EXISTENCE.
+ */
+export function renderedProblems(bundle) {
+  if (!isDir(bundle)) return [];
+  const cfg = makeCfg();
+  const marker = path.join(bundle, '.geneseed-theme');
+  let themeName;
+  if (existsSync(marker)) themeName = readText(marker).trim();
+  else if (existsSync(CONFIG)) themeName = parseJson(readText(CONFIG))?.theme ?? 'neutral';
+  else themeName = 'neutral';
+  let emit;
+  try { emit = readText(path.join(bundle, '.geneseed-emit')).trim(); } catch { emit = ''; }
+  const host = (EMIT_HOST_SCOPE.get(emit) ?? ['', ''])[0];
+  let items;
+  try {
+    // THE FIRST CALLER IN THE PORT THAT CATCHES A REFUSAL, and that is why the stderr is
+    // buffered. `sys.exit(msg)` attaches the message to the EXCEPTION and the interpreter
+    // prints it on the way out, so a Python caller that catches SystemExit sees no output at
+    // all; this port's convention is to write at the raise site (`loadTheme`, and its
+    // docblock says why), which is identical for every caller that lets the throw propagate
+    // and wrong for exactly this one. Buffered and replayed on success, so a WARN the render
+    // legitimately emits still reaches the user, and discarded with the refusal it belongs to.
+    ({ items } = withDiscardableStderr(() => renderAll(cfg, themeName, {
+      footprint: footprintOfDir(bundle), nativeCatalog: hostCatalogsNatively(host),
+    })));
+  } catch (e) {
+    // `except SystemExit` — `effectiveTheme` refuses an unknown theme, and the driver's
+    // marker for a deliberate refusal is the `exitCode` this port already uses everywhere.
+    if (e && e.exitCode !== undefined) {
+      return [`[rendered] cannot render theme '${themeName}' for ${path.basename(bundle)}/`];
+    }
+    throw e;
+  }
+  const problems = [];
+  const nbDirname = STRUCTURE.DIR_NOTEBOOK ?? 'notebook';
+  for (const { rel: outRel, text: rendered, src } of items) {
+    const dest = path.join(bundle, outRel);
+    const parts = outRel.split('/');
+    const name = path.basename(bundle);
+    if (!existsSync(dest)) {
+      problems.push(`[rendered] ${name}/${outRel} missing — rebuild the bundle`);
+    } else if (parts[0] === nbDirname && parts[parts.length - 1] !== '.gitignore') {
+      continue;   // seed-once, agent-owned: a rewrite is not drift
+    } else if (rendered !== null) {
+      // The OpenCode emits de-link AGENT.md's per-row table entries after rendering, so the
+      // bundle on disk legitimately differs from `renderAll`'s output for this one file.
+      const text = host === 'opencode' && outRel === 'AGENT.md'
+        ? stripCapabilityLinks(cfg, rendered) : rendered;
+      if (readText(dest) !== text) {
+        problems.push(`[rendered] ${name}/${outRel} stale (differs from a fresh render) `
+          + '— rebuild');
+      }
+    } else if (!readFileSync(dest).equals(readFileSync(src))) {
+      problems.push(`[rendered] ${name}/${outRel} stale — rebuild`);
+    }
+  }
+  return problems;
+}
+

package/js/inspect/checks-repo.mjs

@@ -0,0 +1,308 @@
+/**
+ * The checks over the REPO's own records — the registry, committed secrets, the hook shim
+ * and the vendored-skill pins.
+ *
+ * Same contract as `checks-build.mjs`: an array of problem strings, empty when clean, one
+ * planted fault per check in the gate. This is the group that reads what the repo SAYS about
+ * itself and compares it against what is on disk.
+ */
+import path from 'node:path';
+import { PLUGIN_SRC, ROOT, SRC, THEMES, WORKFLOW_SRC } from '../build/source.mjs';
+import { VENDORED_SKILL_DIRS } from '../hosts/native.mjs';
+import { hookShimPath, shimDeadPaths } from '../hosts/settings.mjs';
+import { readText } from '../lib/fs.mjs';
+import { formatRepr, formatValue } from '../lib/json.mjs';
+import { splitLines } from '../lib/udiff.mjs';
+import { ENTITY_STATUSES } from './inventory.mjs';
+import { isDir, isFile, rglob, srcStems } from './scan.mjs';
+import { readFileSync } from 'node:fs';
+
+/**
+ * `_harness_build._registry_keys` — every entity the registry must describe.
+ *
+ * The flat agent and skill specs plus the vendored skill FOLDERS, which have no flat spec and
+ * are still shipped capabilities. Keyed `<folder>/<stem>`, the shape doctor already prints.
+ */
+function registryKeys() {
+  const keys = new Set();
+  for (const s of srcStems('agents')) keys.add(`agents/${s}`);
+  for (const s of srcStems('skills')) keys.add(`skills/${s}`);
+  for (const d of VENDORED_SKILL_DIRS) keys.add(`skills/${d}`);
+  return keys;
+}
+
+const SEMVER_RE = /^\d+\.\d+\.\d+$/;
+const ISO_DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+
+// `ENTITY_STATUSES`, `LAW_CLASSES`, `LAW_CLASS` and `SKILL_CLASS` moved to
+// `js/inspect/inventory.mjs` in P6c — see the import above. They crossed HERE in P5g because
+// doctor's authoring gates are what validate them, and they belong where Python keeps
+// them (`_harness_tui`) now that the catalog reads them too. The gates below are
+// unchanged, which is what licensed the move: a copy would have stopped being the
+// value under test the first time one of them was edited.
+
+/**
+ * `_harness_build._registry_problems` — `registry.json` describes exactly what `src/`
+ * provides, with well-formed fields.
+ *
+ * Two-way, like every anti-drift gate here: a new spec with no row and a row whose spec is
+ * gone are both errors. Without the second half a shipped skill would show no lifecycle
+ * status in the TUI and web catalogs while doctor stayed green. `last_verified` may be empty
+ * — nothing writes it yet — but when set it must be a date.
+ */
+export function registryProblems() {
+  let doc;
+  const file = path.join(ROOT, 'registry.json');
+  let raw;
+  try { raw = readText(file); } catch (e) {
+    return [`[authoring] registry.json unreadable: ${e.message}`];
+  }
+  try { doc = JSON.parse(raw); } catch (e) {
+    return [`[authoring] registry.json is not valid JSON: ${e.message}`];
+  }
+  const entities = doc && typeof doc === 'object' && !Array.isArray(doc) ? doc.entities : null;
+  if (entities === null || typeof entities !== 'object' || Array.isArray(entities)) {
+    return ["[authoring] registry.json has no 'entities' object"];
+  }
+  const expected = registryKeys();
+  const present = new Set(Object.keys(entities));
+  const problems = [...expected].filter((k) => !present.has(k)).sort()
+    .map((key) => `[authoring] ${key} has no row in registry.json`);
+  problems.push(...[...present].filter((k) => !expected.has(k)).sort()
+    .map((key) => `[authoring] registry.json lists '${key}' but no such entity exists`));
+  for (const key of [...expected].filter((k) => present.has(k)).sort()) {
+    const row = entities[key];
+    if (row === null || typeof row !== 'object' || Array.isArray(row)) {
+      problems.push(`[authoring] registry.json['${key}'] is not an object`);
+      continue;
+    }
+    // `row.get(...)` is None for an absent key, and `!r` renders that as `None`; a bare JS
+    // lookup is `undefined`, which `formatRepr` would not recognise as one.
+    if (!ENTITY_STATUSES.includes(row.status)) {
+      problems.push(`[authoring] registry.json['${key}'].status ${formatRepr(row.status ?? null)} `
+        + `is not one of ${formatRepr(ENTITY_STATUSES)}`);
+    }
+    if (!SEMVER_RE.test(formatValue(row.version ?? ''))) {
+      problems.push(`[authoring] registry.json['${key}'].version `
+        + `${formatRepr(row.version ?? null)} is not a semver (N.N.N)`);
+    }
+    if (!formatValue(row.owner ?? '').trim()) {
+      problems.push(`[authoring] registry.json['${key}'] has no owner`);
+    }
+    for (const field of ['added', 'last_verified']) {
+      const value = formatValue(row[field] ?? '');
+      if (value && !ISO_DATE_RE.test(value)) {
+        problems.push(`[authoring] registry.json['${key}'].${field} ${formatRepr(value)} is `
+          + 'not an ISO date (YYYY-MM-DD) or empty');
+      }
+    }
+  }
+  return problems;
+}
+
+/**
+ * `_harness_build._SECRET_PATTERNS` — credential shapes, by the prefix each issuer stamps,
+ * plus the generic assignment. Deliberately narrow: a gate that cries wolf gets disabled.
+ *
+ * `(?i)` becomes the `i` flag on the last one only, which is where the Python puts it.
+ */
+const SECRET_PATTERNS = [
+  ['Anthropic API key', /sk-ant-[A-Za-z0-9_-]{20,}/],
+  ['OpenAI-style API key', /\bsk-[A-Za-z0-9]{32,}/],
+  ['GitHub token', /\bgh[pousr]_[A-Za-z0-9]{36}\b/],
+  ['AWS access key id', /\bAKIA[0-9A-Z]{16}\b/],
+  ['Slack token', /\bxox[abprs]-[A-Za-z0-9-]{10,}/],
+  ['private key block', /-----BEGIN [A-Z ]*PRIVATE KEY-----/],
+  ['assigned credential',
+    /\b(password|passwd|secret|api[_-]?key|access[_-]?token)\s*[:=]\s*["'][^"'\s]{8,}["']/i],
+];
+
+/**
+ * `_harness_build._secret_problems` — no credential may ship.
+ *
+ * Sweeps the four trees `sourceFingerprint()` hashes, which is exactly the material that ends
+ * up inside a user's bundle. Reports file:line and the KIND only — echoing the matched text
+ * would republish the secret into every CI log.
+ */
+export function secretProblems() {
+  const problems = [];
+  for (const root of [SRC, THEMES, PLUGIN_SRC, WORKFLOW_SRC]) {
+    if (!isDir(root)) continue;
+    for (const p of rglob(root)) {
+      if (!isFile(p) || p.split(path.sep).includes('__pycache__')) continue;
+      // `except (OSError, UnicodeDecodeError): continue` — binary or unreadable, nothing to
+      // scan. `readText` would substitute U+FFFD where Python RAISES, so the strict decode is
+      // the check rather than a catch, and the newline folding `Path.read_text` does has to
+      // be applied by hand afterwards for the LINE NUMBERS to agree.
+      let raw;
+      try { raw = readFileSync(p); } catch { continue; }
+      let s;
+      try { s = new TextDecoder('utf-8', { fatal: true }).decode(raw); } catch { continue; }
+      s = s.replaceAll('\r\n', '\n').replaceAll('\r', '\n');
+      // `path.relative` returns a `..`-prefixed path where `relative_to` RAISES; the fallback
+      // is the Python's, for a tree outside the repo (a test tmpdir).
+      const r = path.relative(ROOT, p);
+      const rel = (r.startsWith('..') || path.isAbsolute(r) ? p : r)
+        .split(path.sep).join('/');
+      // `str.splitlines()`, not `split('\n')`: it also breaks on VT, FF, NEL and the two
+      // Unicode separators, and the line NUMBER is printed.
+      splitLines(s).forEach((line, i) => {
+        for (const [label, pattern] of SECRET_PATTERNS) {
+          if (pattern.test(line)) {
+            problems.push(`[authoring] possible ${label} in ${rel}:${i + 1} — a `
+              + 'credential must never be committed');
+          }
+        }
+      });
+    }
+  }
+  return problems;
+}
+
+/**
+ * `_harness_build._shim_problems` — the hook shim exists and points at something real.
+ *
+ * This gate exists because the shim DISARMED an accidental safety net. When the emitted hook
+ * command still carried the checkout path, moving the checkout made that command
+ * non-canonical and the next emit's prune-and-rewire repaired every install by itself. Now
+ * the config is invariant under a move and the stale path lives in the shim body, which no
+ * other gate reads (the build scan only walks `*.md`). Without this a moved checkout leaves
+ * every gate silently dead: the hooks still fire, the shim still runs, and the interpreter
+ * reports "no such file" into a channel nobody reads.
+ *
+ * An ABSENT shim is not a problem: a source checkout that has never emitted has no reason to
+ * own one.
+ */
+export function shimProblems() {
+  const p = hookShimPath();
+  if (!isFile(p)) return [];
+  let body;
+  try { body = readText(p); } catch (e) {
+    return [`[shim] ${p} exists but cannot be read (${e.message}) — hooks may be dead`];
+  }
+  // The body is machine-generated and quotes the two baked paths — plus, on POSIX, the argv
+  // placeholder `"$@"`, which is not a path. `shimDeadPaths` is the single owner of that rule;
+  // `hookPrefix` is its other reader, and the two must not drift.
+  return shimDeadPaths(body).map(
+    (m) => `[shim] ${p} pointed at ${m}, which does not exist — every hook in every `
+      + "install was dead (the checkout most likely moved). This run's own "
+      + 'emit has refreshed it; no further action needed.',
+  );
+}
+
+const HEX40_RE = /^[0-9a-f]{40}$/;
+/** Refs that move under the pin — re-copying months later changes the shipped skill. */
+const MOVING_REFS = new Set(['main', 'master', 'develop', 'dev', 'head', 'latest', 'trunk']);
+
+/**
+ * `_harness_build._vendor_pin_problems` — every vendored skill folder records where it came
+ * from, under which license, and at WHICH immutable commit.
+ *
+ * First-party folders that merely ride the vendored mechanism for their multi-file layout
+ * declare that instead (`**Upstream:** this …`) and are exempt from the pin: there is no
+ * upstream to drift against.
+ */
+export function vendorPinProblems() {
+  const problems = [];
+  for (const name of VENDORED_SKILL_DIRS) {
+    const folder = path.join(SRC, 'skills', name);
+    if (!isDir(folder)) {
+      problems.push(`[authoring] VENDORED_SKILL_DIRS lists '${name}' but `
+        + `src/skills/${name}/ does not exist`);
+      continue;
+    }
+    let text;
+    try { text = readText(path.join(folder, 'VENDOR.md')); } catch {
+      problems.push(`[authoring] skills/${name}/ has no VENDOR.md — its upstream, `
+        + 'pinned commit and license are unrecorded');
+      continue;
+    }
+    if (!/\*\*License:\*\*/.test(text)) {
+      problems.push(`[authoring] skills/${name}/VENDOR.md records no '**License:**'`);
+    }
+    const upstream = /\*\*Upstream:\*\*\s*(\S+)/.exec(text);
+    if (!upstream) {
+      problems.push(`[authoring] skills/${name}/VENDOR.md declares no '**Upstream:**'`);
+      continue;
+    }
+    if (upstream[1].toLowerCase().startsWith('this')) continue;  // first-party
+    const pin = /\*\*Commit:\*\*\s*(\S+)/.exec(text);
+    if (!pin) {
+      problems.push(`[authoring] skills/${name}/VENDOR.md has no '**Commit:**' pin`);
+    } else if (MOVING_REFS.has(pin[1].toLowerCase())) {
+      problems.push(`[authoring] skills/${name}/VENDOR.md pins '${pin[1]}', a `
+        + 'moving branch — record the commit sha instead');
+    } else if (!HEX40_RE.test(pin[1].toLowerCase())) {
+      problems.push(`[authoring] skills/${name}/VENDOR.md pin '${pin[1]}' is not `
+        + 'a 40-character commit sha');
+    }
+  }
+  return problems;
+}
+
+
+/**
+ * `js/README.md` describes every module under `js/`, and only modules that exist.
+ *
+ * THE MAP IS THE ONLY THING IN THIS REPO THAT ANSWERS "WHERE DOES X LIVE?", and a map is worse
+ * than no map once it is wrong: a reader who cannot find a module knows they are lost, and a
+ * reader sent to the wrong file does not. Nothing else notices — the map is prose, it compiles
+ * to nothing, and every suite here stays green while it rots.
+ *
+ * It went in when `js/` reached 56 modules across seven folders, most of them named within the
+ * previous week by splits that moved code between files without moving any behaviour. That is
+ * exactly the change a map cannot survive unattended.
+ *
+ * TWO-SIDED, like the partitions elsewhere in this tree: a module with no row is unfindable, and
+ * a row naming a module that does not exist sends a reader to an ENOENT. Both are reported.
+ * The scan reads the fenced table cells rather than the prose, so a module merely MENTIONED in a
+ * paragraph does not count as documented.
+ */
+export function moduleMapProblems() {
+  const problems = [];
+  const mapPath = path.join(String(ROOT), 'js', 'README.md');
+  let text;
+  try {
+    text = readText(mapPath);
+  } catch {
+    return ['[authoring] js/README.md is missing — it is the module map, and js/inspect/'
+      + 'checks-repo.mjs asserts it describes every module under js/'];
+  }
+
+  // A row is `| `name.mjs` | … |`. Reading the CODE SPAN and not the whole line keeps a module
+  // named in a "Before editing" paragraph from counting as a row.
+  const documented = new Set(
+    [...text.matchAll(/^\|\s*`([a-z0-9-]+\.mjs)`\s*\|/gm)].map((m) => m[1]),
+  );
+
+  const onDisk = new Set();
+  const jsDir = path.join(String(ROOT), 'js');
+  for (const rel of rglob(jsDir)) {
+    if (!rel.endsWith('.mjs')) continue;
+    // One level down only: `js/<domain>/<module>.mjs` is the shape the map is drawn in.
+    // Separators are normalised first: `path.relative` answers with the PLATFORM's, so a split
+    // that only knew `/` finds ONE part on Windows and therefore zero modules — which is what
+    // the vacuity guard below caught the first time this ran.
+    const parts = path.relative(jsDir, rel).replaceAll('\\', '/').split('/');
+    if (parts.length === 2) onDisk.add(parts[1]);
+  }
+
+  if (onDisk.size < 30) {
+    return [`[authoring] the module scan found only ${onDisk.size} modules under js/ — the walk `
+      + 'has gone stale and this check is no longer reading the tree it claims to read'];
+  }
+
+  for (const mod of [...onDisk].sort()) {
+    if (!documented.has(mod)) {
+      problems.push(`[authoring] js/${mod} has no row in js/README.md — a module the map does not `
+        + 'name is a module nobody can find');
+    }
+  }
+  for (const mod of [...documented].sort()) {
+    if (!onDisk.has(mod)) {
+      problems.push(`[authoring] js/README.md has a row for ${mod}, which does not exist — the map `
+        + 'sends a reader to a file that is not there');
+    }
+  }
+  return problems;
+}