explainer-video 0.0.0-stage → 0.4.0

package/skills/explainer-video-from-codebase/tools/codemap-md.mjs

@@ -0,0 +1,116 @@
+/* codemap.md: the human-readable code map. Every group, every entry, every rule link with its evidence, the test
+   inventory with its session-wide and autouse mocks, config facts and profiles, and the self-check. Pytest
+   fixture links are listed per fixture (each individual link is in codemap.json). */
+const short = id => id.split(':').pop();
+const loc = (file, line) => line ? `${file}:${line}` : file;
+const table = (head, rows) => rows.length ? [`| ${head.join(' | ')} |`, `|${head.map(() => '---').join('|')}|`, ...rows.map(r => `| ${r.map(c => String(c ?? '').replace(/\|/g, '\\|')).join(' | ')} |`)].join('\n') : '_none_';
+
+export function renderCodemap(m) {
+  const G = ['prod', 'eval', 'dev', 'test'];
+  const sym = new Map(m.symbols.map(s => [s.id, s]));
+  const fileOf = id => sym.get(id)?.file || id.split(':')[0];
+  const out = [];
+  const ts = m.testSummary, sc = m.selfCheck;
+  out.push(`# Code map: ${m.root.split('/').pop()}`, '',
+    `- root: \`${m.root}\`${m.commit ? ` at \`${m.commit.slice(0, 7)}\`` : ''} · tree ${m.treeHash.slice(0, 19)}…`,
+    `- tools: ${Object.entries(m.tool.versions).map(([k, v]) => `${k}@${v}`).join(', ')}`,
+    `- ${m.files.length} files: ${m.languages.python.files} Python (${m.languages.python.parseErrors} with syntax errors)` +
+      (m.languages.typescript ? `, ${m.languages.typescript.files} TypeScript (${m.languages.typescript.parseErrors} with syntax errors), ${m.languages.javascript.files} JavaScript (${m.languages.javascript.parseErrors} with syntax errors)` : '') +
+      [['go', 'Go'], ['c', 'C'], ['cpp', 'C++']].filter(([k]) => m.languages[k]).map(([k, n]) => `, ${m.languages[k].files} ${n} (${m.languages[k].parseErrors} with syntax errors)`).join('') +
+      `, ${m.unsupported.files} not mined yet ${JSON.stringify(m.unsupported.byExt)}`,
+    `- ${m.symbols.length} symbols · ${m.edges.length} edges · ${m.entries.length} entries · ${ts.tests} tests`, '');
+
+  out.push('## Self-check', '',
+    `- **${sc.ok ? 'ok' : 'FAILED'}**: ${sc.defsExtracted} of ${sc.defNodes} parsed definitions extracted (${sc.defLinesRaw} \`def\`/\`class\` lines by regex) · ${sc.defScopes} distinct definitions, ${sc.symbols} symbols`,
+    `- calls: ${sc.calls.resolved} resolved · unresolved by origin ${JSON.stringify(sc.unresolvedByOrigin)} · in-repo miss rate ${(sc.inRepoMissRate * 100).toFixed(1)}%`,
+    `- Python package roots below the repo root: ${sc.packageRoots.length ? sc.packageRoots.map(r => `\`${r}/\``).join(', ') : 'none'}`,
+    ...(sc.ambiguousImports.length ? [`- **${sc.ambiguousImports.reduce((n, x) => n + x.calls, 0)} calls are not linked: their import names a module several package roots claim and none holds the importing file**: ` +
+      sc.ambiguousImports.map(x => `\`${x.name}\` ${x.calls} (${x.roots.map(r => `\`${r}/\``).join(', ')})`).join(', ')] : []),
+    ...(sc.crossRootImports.length ? [`- ${sc.crossRootImports.reduce((n, x) => n + x.calls, 0)} calls resolve through a package root that does not hold the importing file (right only if that root is on its sys.path): ` +
+      sc.crossRootImports.map(x => `\`${x.name}\` → \`${x.root}/\` ${x.calls}`).join(', ')] : []),
+    ...(sc.externalLikeRepoDirs.calls ? [`- **${sc.externalLikeRepoDirs.calls} calls (${(sc.externalLikeRepoDirs.rate * 100).toFixed(1)}%) go to imports resolved as external although an in-repo directory with no \`__init__.py\` has their name**: ` +
+      sc.externalLikeRepoDirs.names.map(x => `\`${x.name}\` ${x.calls} (${x.dirs.map(d => `\`${d}/\``).join(', ')})`).join(', ') + ' — if these are in-repo namespace packages, these calls are not linked'] : []),
+    ...(sc.typescript ? [`- TypeScript / JavaScript: ${sc.typescript.defsExtracted} of ${sc.typescript.defNodes} parsed definitions extracted · ${sc.typescript.symbols} symbols · calls: ${sc.typescript.calls.resolved} resolved · unresolved by origin ${JSON.stringify(sc.typescript.unresolvedByOrigin)} · in-repo miss rate ${(sc.typescript.inRepoMissRate * 100).toFixed(1)}%`,
+      ...(sc.typescript.unresolvedImports.length ? [`- **${sc.typescript.unresolvedImports.length} relative imports name no file in the repo** (their calls are not linked): ` +
+        sc.typescript.unresolvedImports.slice(0, 20).map(x => `\`${x.spec}\` in \`${x.from}\``).join(', ') + (sc.typescript.unresolvedImports.length > 20 ? ', …' : '')] : [])] : []),
+    ...(sc.go ? [`- Go: ${sc.go.defsExtracted} of ${sc.go.defNodes} parsed definitions extracted · ${sc.go.symbols} symbols · modules ${sc.go.modules.map(x => `\`${x.module}\` (${x.dir}/)`).join(', ') || 'none (imports of in-repo packages cannot be told from dependencies)'} · calls: ${sc.go.calls.resolved} resolved · unresolved by origin ${JSON.stringify(sc.go.unresolvedByOrigin)} · in-repo miss rate ${(sc.go.inRepoMissRate * 100).toFixed(1)}%`] : []),
+    ...(sc.c ? [`- C / C++: ${sc.c.defsExtracted} of ${sc.c.defNodes} parsed definitions extracted · ${sc.c.symbols} symbols · calls: ${sc.c.calls.resolved} resolved · unresolved by origin ${JSON.stringify(sc.c.unresolvedByOrigin)} (an ALL_CAPS macro counts as builtin) · in-repo miss rate ${(sc.c.inRepoMissRate * 100).toFixed(1)}%`,
+      ...(sc.c.unresolvedIncludes.length ? [`- ${sc.c.unresolvedIncludes.length} quoted includes name no repo file (a vendored or generated header): ` +
+        sc.c.unresolvedIncludes.slice(0, 20).map(x => `\`${x.include}\` in \`${x.from}\``).join(', ') + (sc.c.unresolvedIncludes.length > 20 ? ', …' : '')] : [])] : []),
+    `- files with syntax errors: ${(m.files.filter(f => f.parseError).map(f => f.path)).length ? m.files.filter(f => f.parseError).map(f => `\`${f.path}\``).join(', ') : 'none'}`,
+    ...(sc.dependencyFilesNotParsed.length ? [`- **dependency files that are not valid TOML, their names read line by line**: ${sc.dependencyFilesNotParsed.map(f => `\`${f}\``).join(', ')}`] : []), '');
+
+  out.push('## Groups', '', 'Rules, first match wins (a `--group` override wins over all of them):', '', ...m.groups.rules.map((r, i) => `${i + 1}. ${r}`), '',
+    m.groups.overrides.length ? `Overrides: ${m.groups.overrides.map(o => `\`${o}\``).join(', ')}` : 'Overrides: none', '',
+    table(['group', 'files', 'symbols', 'entries'], G.map(g => [g, m.groups.files[g], m.groups.symbols[g], m.groups.entries[g]])), '');
+  const testEntries = m.entries.filter(e => e.group === 'test');
+  if (testEntries.length) out.push('**Entries in the test group** (test-group entries are not flows; if this is a script, override its group):', '',
+    ...testEntries.map(e => `- \`${e.id}\` (${loc(e.file, e.line)}) — e.g. \`--group '${e.file}=dev'\``), '');
+  out.push('### Every file and the rule that placed it', '', table(['file', 'group', 'rule'], m.files.map(f => [`\`${f.path}\``, f.group, f.rule + (f.unsupported ? ' · not mined yet' : '') + (f.parseError ? ' · syntax error' : '')])), '');
+
+  out.push('## Entries', '');
+  for (const g of G) {
+    const es = m.entries.filter(e => e.group === g);
+    out.push(`### ${g} (${es.length})`, '', table(['kind', 'entry', 'route / key / via', 'where', 'rule'],
+      es.map(e => [e.kind, `\`${short(e.id)}\``, e.path ? [e.method, e.path].filter(Boolean).join(' ') + (e.alsoAt ? ` (also ${e.alsoAt.join(', ')})` : '') : e.key || e.via || '', loc(e.file, e.line), e.rule || 'python'])), '');
+  }
+
+  out.push('## Rule links', '');
+  const ruleEdges = m.edges.filter(e => e.rule && !/^pytest\.fixture/.test(e.rule));
+  const byRule = new Map(); for (const e of ruleEdges) (byRule.get(e.rule) || byRule.set(e.rule, []).get(e.rule)).push(e);
+  for (const [rule, es] of [...byRule].sort()) {
+    out.push(`### ${rule} (${es.length})`, '', table(['from', 'to', 'kind', 'groups', 'evidence'],
+      es.map(e => [`\`${short(e.from)}\``, `\`${short(e.to)}\``, e.kind, e.groups ? e.groups.join('→') : e.group || '', e.evidence || loc(fileOf(e.from), e.line)])), '');
+  }
+  const reg = m.rules.registry;
+  if (reg.length) out.push('### registry tables', '', table(['key', 'message type', 'consumer', 'evidence', 'constructors', 'linked'],
+    reg.map(r => [r.key, `\`${short(r.messageType)}\``, `\`${short(r.consumer)}\``, r.evidence, r.candidates, r.kept])), '');
+  const unlinked = m.rules.pyHttp.filter(h => !h.handler);
+  if (m.rules.pyHttp.length) out.push(`### HTTP client calls with no matching route (${unlinked.length} of ${m.rules.pyHttp.length})`, '',
+    table(['from', 'call', 'where'], unlinked.map(h => [`\`${short(h.from)}\``, `${h.method} ${h.url}`, loc(h.file, h.line)])), '');
+  const jsUnlinked = (m.rules.jsHttp || []).filter(h => !h.handler);
+  if (m.rules.jsHttp?.length) out.push(`### TypeScript / JavaScript HTTP client calls (${m.rules.jsHttp.length - jsUnlinked.length} of ${m.rules.jsHttp.length} linked)`, '',
+    'A URL is folded from literals and consts (`folded`); one whose leading base could not be folded is linked only when exactly one route has its tail (`tail match`).', '',
+    table(['from', 'client', 'call', 'route handler', 'how', 'where'], m.rules.jsHttp.map(h => [`\`${short(h.from)}\``, h.client, `${h.method || '*'} ${h.url}`, h.handler ? `\`${short(h.handler)}\`` : h.unlinked ? `**not linked**: ${h.unlinked}` : '**no matching route**',
+      [h.folded ? `folded ${h.folded.join(', ')}` : '', h.env ? `env ${h.env.join(', ')}` : '', h.match === 'suffix' ? 'tail match' : ''].filter(Boolean).join(' · '), loc(h.file, h.line)])), '');
+  if (m.rules.routeAliases?.length) out.push('### Handlers a second route also reaches', '', table(['route', 'handler', 'where'],
+    m.rules.routeAliases.map(r => [`${r.method} ${r.path}`, `\`${short(r.id)}\``, loc(r.file, r.line)])), '');
+  const onFailure = m.edges.filter(e => e.onFailure);
+  out.push(`### Calls on failure paths (${onFailure.length})`, '', 'Calls inside an `except` clause run only when the guarded code raised.', '',
+    table(['from', 'to', 'on failure', 'where'], onFailure.map(e => [`\`${short(e.from)}\``, `\`${short(e.to)}\``, e.onFailure, loc(fileOf(e.from), e.line)])), '');
+  out.push('### Frameworks imported without a rule pack', '', m.frameworksWithoutPack.length
+    ? m.frameworksWithoutPack.map(f => `- \`${f.name}\`${f.lang ? ` (${f.lang})` : ''} (first seen in \`${f.firstSeen}\`): its wiring is not linked; declare links where a flow needs them`).join('\n') : '_none_', '');
+
+  out.push('## Tests', '',
+    `${ts.tests} tests (${ts.asserting} with at least one assertion) · ${ts.fixtures} fixtures (${ts.autouse} autouse) · ${ts.fixtureLinks} fixture links · ` +
+    `${ts.mocks} mock targets (${ts.mocksResolved} resolved in the repo, ${ts.sessionMocks} session-wide) · ` +
+    `**${ts.prodFunctionsWithDirectLink} of ${ts.prodFunctions} production functions have a direct test link**`, '');
+  const session = m.mocks.filter(x => x.scope === 'session');
+  const autouse = new Set(m.fixtures.filter(f => f.autouse).map(f => f.id));
+  const autouseMocks = m.mocks.filter(x => autouse.has(x.fn));
+  out.push('### Mocks every test in scope runs under', '', 'No test is evidence for what these replace; narration must not call it "tested".', '',
+    table(['mock', 'replaces', 'set up in', 'applies to'], [
+      ...session.map(x => [x.how, `\`${x.target ? short(x.target) : x.raw}\``, loc(fileOf(x.fn), x.line) + ` (\`${short(x.fn)}\`)`, x.covers != null ? `every test under \`${x.covers || '.'}/\` (session-wide, set up in \`${x.conftest}\`)` : `every test under \`${x.conftest}\` (session-wide)`]),
+      ...autouseMocks.map(x => [x.how, `\`${x.target ? short(x.target) : x.raw}\``, loc(fileOf(x.fn), x.line) + ` (\`${short(x.fn)}\`)`, 'every test in scope (autouse fixture)'])]), '');
+  const binds = new Map(); for (const b of m.fixtureBindings) binds.set(b.fixture, (binds.get(b.fixture) || 0) + 1);
+  out.push('### Fixtures', '', table(['fixture', 'where', 'autouse', 'bound by'], m.fixtures.map(f => [`\`${short(f.id)}\``, loc(f.file, f.line), f.autouse ? 'yes' : '', binds.get(f.id) || 0])), '');
+  const perFile = new Map(); for (const t of m.tests) { const x = perFile.get(t.file) || perFile.set(t.file, { n: 0, direct: 0 }).get(t.file); x.n++; x.direct += t.direct.length; }
+  out.push('### Tests per file', '', table(['file', 'tests', 'direct links'], [...perFile].map(([f, x]) => [`\`${f}\``, x.n, x.direct])), '');
+
+  out.push('## Config', '', `${m.config.settingsFields.length} settings fields · ${m.config.settingsProps.length} settings properties · ${m.config.kv.length} config facts in ${m.config.files.length} git-tracked files · ${m.config.untracked} untracked config files not read`, '',
+    ...m.config.notGitWorkTree.map(d => `**Config not read from \`${d}\`: not a git work tree, so no config file can be proven tracked.**`), ...(m.config.notGitWorkTree.length ? [''] : []),
+    'A value is kept only for a key a dispatch guard reads; a secret-looking key or value is shown as `set (redacted)`.', '',
+    table(['config file', 'group', 'reader', 'facts'], m.config.files.map(f => [`\`${f.path}\``, f.group, f.reader, f.facts])), '',
+    ...(m.config.envReads ? ['### Environment variables and flags the code reads', '', 'TypeScript / JavaScript `process.env` and `import.meta.env`, Go `os.Getenv` / `os.LookupEnv` and `flag.*` (key `-name`), C `getenv`. A default is the literal after `??` or `||`, or a flag\'s default; a secret-looking one is shown as `set (redacted)`.', '',
+      table(['variable', 'via', 'default', 'where', 'group'], m.config.envReads.map(r => [r.key, r.via, r.default ?? '', loc(r.file, r.line), r.group])), ''] : []),
+    '### Profiles', '', table(['profile', 'group', 'keys a guard reads'], m.config.profiles.map(p => [p.name, p.group, p.keys.join(', ')])), '',
+    '### Config-selected dispatch', '');
+  for (const s of m.config.sites) {
+    out.push(`- \`${s.factory}\` (${s.group}) → **${s.classification}**`);
+    for (const a of s.alternatives) out.push(`  - \`${short(a.cls)}\`${a.group && a.group !== s.group ? ` (${a.group} group)` : ''} when ${a.guards.join(' & ') || '(fallthrough)'} · ${Object.entries(a.sel).map(([k, v]) => `${k.split('/').pop()}=${v}`).join(' ')}`);
+    for (const v of s.inRepoValues) out.push(`  - reads settings.${v.setting} (env ${v.env}, default ${v.default}) set in: ${v.files.join(', ') || 'no in-repo file'}`);
+    if (s.params.length) out.push(`  - runtime inputs: ${s.params.join(', ')}`);
+  }
+  out.push('');
+  return out.join('\n');
+}

package/skills/explainer-video-from-codebase/tools/config/dotenv.mjs

@@ -0,0 +1,13 @@
+/* Config facts from `.env`-style files: `KEY=value`, `export KEY=value`, trailing `# comment` dropped. */
+export const matches = rel => /(^|\/)(\.env(\.[\w-]+)?|[\w.-]+\.env(\.example)?|sample\.env)$/.test(rel);
+
+export function readFacts(text) {
+  const out = [];
+  text.split('\n').forEach((ln, i) => {
+    const m = ln.match(/^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/);
+    if (!m) return;
+    const value = m[2].replace(/\s+#.*$/, '').replace(/^["']|["']$/g, '').trim();
+    if (value !== '') out.push({ key: m[1], value, line: i + 1 });
+  });
+  return out;
+}

package/skills/explainer-video-from-codebase/tools/config/json.mjs

@@ -0,0 +1,14 @@
+/* Config facts from JSON, line by line: `"key": value` pairs (leaf scalars; objects and arrays are skipped).
+   package.json, lockfiles and tsconfig are tooling, not configuration of the code. */
+export const matches = rel => /\.json$/.test(rel) && !/(^|\/)(package(-lock)?\.json|tsconfig[\w.-]*\.json)$/.test(rel);
+
+export function readFacts(text) {
+  const out = [];
+  text.split('\n').forEach((ln, i) => {
+    const m = ln.match(/^\s*"([A-Za-z][A-Za-z0-9_.-]*)"\s*:\s*(.*?)\s*,?\s*$/);
+    if (!m || /^[[{]/.test(m[2])) return;
+    const value = m[2].replace(/^"|"$/g, '').trim();
+    if (value !== '') out.push({ key: m[1], value, line: i + 1 });
+  });
+  return out;
+}

package/skills/explainer-video-from-codebase/tools/config/redact.mjs

@@ -0,0 +1,16 @@
+/* What the code map may show of a config value. A secret-looking key (…KEY, TOKEN, SECRET, PASSWORD, AUTH, …) or a
+   credential-shaped value (a URL with a password, a private key block, a JWT, a provider token, a long random
+   string) is shown only as set. */
+export const REDACTED = 'set (redacted)';
+const SECRET_KEY = /KEY|TOKEN|SECRET|PASS(WORD|WD|PHRASE)?|PWD|CREDENTIAL|PRIVATE|AUTH|CERT|SIGNATURE|SALT|COOKIE|SESSION|DSN/i;
+const CREDENTIAL = [
+  /^[a-z][\w+.-]*:\/\/[^/\s:@]*:[^/\s@]+@/i,          // scheme://user:password@host
+  /-----BEGIN [A-Z ]*PRIVATE KEY/,
+  /^eyJ[\w-]+\.[\w-]+\./,                              // JWT
+  /^(sk|pk|rk)[-_]\w[\w-]{15,}$/, /^(gh[pousr]|github_pat)_\w{20,}$/, /^xox[abposr]-/, /^AKIA[0-9A-Z]{16}$/, /^AIza[\w-]{30,}$/,
+  /^Bearer\s+\S/i,
+  /^[0-9a-f]{32,}$/i,
+  /^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)[A-Za-z0-9+/=_-]{32,}$/,
+];
+export const shownValue = (key, value) =>
+  value == null ? value : SECRET_KEY.test(key || '') || CREDENTIAL.some(re => re.test(String(value))) ? REDACTED : value;

package/skills/explainer-video-from-codebase/tools/config/toml-lite.mjs

@@ -0,0 +1,13 @@
+/* Config facts from TOML, line by line: `key = value` leaves (tables are not tracked; keys are leaf names). */
+export const matches = rel => /\.toml$/.test(rel);
+
+export function readFacts(text) {
+  const out = [];
+  text.split('\n').forEach((ln, i) => {
+    const m = ln.match(/^\s*["']?([A-Za-z][A-Za-z0-9_.-]*)["']?\s*=\s*(.*)$/);
+    if (!m) return;
+    const value = m[2].replace(/\s+#.*$/, '').replace(/^["']|["']$/g, '').trim();
+    if (value !== '') out.push({ key: m[1], value, line: i + 1 });
+  });
+  return out;
+}

package/skills/explainer-video-from-codebase/tools/config/yaml-lite.mjs

@@ -0,0 +1,18 @@
+/* Config facts from YAML (incl. Helm values and k8s manifests), line by line: `key: value` leaves, and the
+   container-env shape `- name: KEY` followed by `value: v`, which sets KEY. Block scalars (`|`, `>`) are skipped. */
+export const matches = rel => /\.ya?ml$/.test(rel);
+
+export function readFacts(text) {
+  const out = [];
+  let envName = null;
+  text.split('\n').forEach((ln, i) => {
+    const m = ln.match(/^\s*(?:-\s*)?["']?([A-Za-z][A-Za-z0-9_.-]*)["']?\s*:\s*(.*)$/);
+    if (!m) return;
+    const value = m[2].replace(/\s+#.*$/, '').replace(/^["']|["'],?$/g, '').trim();
+    if (m[1] === 'name' && /^\s*-\s*name\s*:/.test(ln)) envName = value;
+    else if (m[1] === 'value' && envName) { if (value !== '') out.push({ key: envName, value, line: i + 1 }); envName = null; return; }
+    if (value === '' || value === '|' || value === '>' || /^[|>][-+]?$/.test(value)) return;
+    out.push({ key: m[1], value, line: i + 1 });
+  });
+  return out;
+}

package/skills/explainer-video-from-codebase/tools/excerpt-check.mjs

@@ -0,0 +1,186 @@
+#!/usr/bin/env node
+/* =============================================================================
+   excerpt-check.mjs — prove every code panel of a code video shows the repo as
+   mined, and that the narration is the reading time (design §4.5 C6).
+
+   Usage:
+     node tools/excerpt-check.mjs --work out/<name>/<NN> --repo <root> --script out/<name>/scripts/NN-*.json
+
+   Reads the video's code scenes (manifest.json's `code` segments), lines.json
+   (stage 4b) and the video's script. Two checks:
+
+   DRIFT (exit 2) — every panel carries the `source` excerpt.mjs wrote, and is
+     byte-identical to the file as mined: the working tree's file when its sha256
+     is the mined one, else the file at the mined commit (`git show`), else the
+     file changed and the panel cannot be trusted. Every numbered line equals that
+     line of the file, inside the span, in order; the span's sha256 still matches;
+     every unnumbered line is an elision marker ("⋯ N lines") standing for exactly
+     the gap it sits in, and no line of the span is hidden without one; at most 22
+     lines are shown.
+
+   FOCUS (exit 3) — every shown, non-blank line is inside a focus window that is
+     synced to the narration: the focus act names `narration` (a line index of
+     the segment in lines.json, or [from, to]) and starts at that line's onset
+     and ends between its end and the next line's onset (scene time, ±0.06 s, as
+     resolve-beats measures). Only a pause segment (one whose script segment
+     carries `pause`) may show lines outside a focus window; there are at most 3,
+     each with a badge. A code scene names its segment (`segment: <key>`): its
+     acts are timed from that segment's window, and the code host plays a scene
+     that names none on the whole video's clock, where every window after the
+     first would be missed.
+
+   Exit: 0 ok · 1 bad flags, no manifest, no scenes, no lines.json or no script · 2 drift · 3 a shown line
+         outside every narration-synced focus window, or a pause rule broken
+   ========================================================================== */
+import { readFileSync, existsSync } from 'node:fs';
+import { join, resolve, basename } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { createHash } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { MAX_PAUSES } from '../../explainer-video-from-coursework/tools/model.mjs';
+
+const fail = (code, msg) => { console.error(`[excerpt-check] ${msg}`); process.exit(code); };
+
+/* ---------------- args ---------------- */
+const argv = process.argv.slice(2);
+const VALUED = new Set(['--work', '--repo', '--script']);
+const flags = new Map();
+for (let i = 0; i < argv.length; i++) {
+  if (VALUED.has(argv[i])) { if (argv[i + 1] == null) fail(1, `${argv[i]} needs a value`); flags.set(argv[i], argv[++i]); }
+  else fail(1, `unknown argument ${argv[i]}`);
+}
+if (!flags.has('--work') || !flags.has('--repo') || !flags.has('--script')) fail(1, 'usage: excerpt-check.mjs --work out/<name>/<NN> --repo <root> --script out/<name>/scripts/NN-*.json');
+const WORK = resolve(flags.get('--work')), REPO = resolve(flags.get('--repo'));
+const MAX_LINES = 22, TOL = 0.06;
+const MARKER = /^\s*⋯ (\d+) lines?$/;
+const sha = t => createHash('sha256').update(t).digest('hex');
+const readJson = (f, what) => { try { return JSON.parse(readFileSync(f, 'utf8')); } catch (e) { fail(1, `cannot read ${what} ${f}: ${e.message}`); } };
+
+/* ---------------- the code scenes ---------------- */
+const scenesDir = join(WORK, 'scenes');
+if (!existsSync(scenesDir)) fail(1, `no scenes/ in ${WORK}: author the scenes first (stage 5)`);
+// a scene is read by executing it with a stubbed `window`, as resolve-beats and the scene host do
+async function sceneConfig(file) {
+  const prev = global.window;
+  global.window = {};
+  try { await import(pathToFileURL(file).href + '?v=' + Date.now()); return global.window.SCENE_CONFIG || null; }
+  catch (e) { fail(1, `${basename(file)} threw: ${e.message}`); }
+  finally { global.window = prev; }
+}
+const manifestPath = join(WORK, 'manifest.json');
+if (!existsSync(manifestPath)) fail(1, `no manifest.json in ${WORK}: write it with the scenes (stage 5); its code segments are the panels checked`);
+const man = readJson(manifestPath, 'the manifest');
+const isCode = host => host === 'code' || /scene-code\.html$/.test((man.hosts || {})[host] || '');
+const segs = Object.entries(man.segments || {}).filter(([, s]) => isCode(s.host)).map(([key, s]) => ({ key, file: join(scenesDir, `${s.scene}.js`) }));
+const scenes = [];
+for (const s of segs) {
+  if (!existsSync(s.file)) fail(1, `segment ${s.key}: scene ${s.file} does not exist`);
+  const cfg = await sceneConfig(s.file);
+  if (cfg && Array.isArray(cfg.panels)) scenes.push({ ...s, cfg });
+}
+if (!scenes.length) fail(1, `no code scenes in ${WORK}`);
+const linesPath = join(WORK, 'lines.json');
+if (!existsSync(linesPath)) fail(1, `no lines.json in ${WORK}: run align.mjs first (stage 4b); focus windows are checked against the measured narration`);
+const segLines = readJson(linesPath, 'lines.json').segments || {};
+const script = readJson(resolve(flags.get('--script')), 'the script');
+
+/* ---------------- the file a panel was cut from, as mined ---------------- */
+const fileCache = new Map();
+function minedFile(src) {
+  const key = `${src.file}\0${src.fileSha256}\0${src.commit}`;
+  if (fileCache.has(key)) return fileCache.get(key);
+  let got = null;
+  const path = join(REPO, src.file);
+  if (existsSync(path)) { const t = readFileSync(path, 'utf8'); if (sha(t) === src.fileSha256) got = { text: t, from: 'working tree' }; }
+  if (!got && src.commit) {
+    const r = spawnSync('git', ['-C', REPO, 'show', `${src.commit}:./${src.file}`], { encoding: 'utf8', maxBuffer: 1 << 28 });
+    if (r.status === 0 && sha(r.stdout) === src.fileSha256) got = { text: r.stdout, from: `commit ${src.commit.slice(0, 12)}` };
+  }
+  fileCache.set(key, got);
+  return got;
+}
+
+/* ---------------- checks ---------------- */
+const drift = [], focus = [], report = [];
+const pauseSegs = new Set((script.segments || []).filter(s => s.pause != null).map(s => s.key));
+
+for (const { key, cfg } of scenes) {
+  const acts = cfg.acts || [];
+  const L = segLines[key];
+  const isPause = pauseSegs.has(key);
+  const hasBadge = acts.some(a => a.op === 'pause');
+  if (isPause && !hasBadge) focus.push(`${key}: a pause segment shows no pause badge (add a \`pause\` act over the spoken prompt)`);
+  if (!isPause && hasBadge) focus.push(`${key}: a pause badge on a segment whose narration does not ask for a pause`);
+  if (cfg.segment !== key) focus.push(`${key}: the scene ${cfg.segment == null ? 'names no segment' : `names segment "${cfg.segment}"`} (set \`segment: "${key}"\`): its acts are timed from this segment's window, and the code host plays them on that window only when the scene names it`);
+
+  // the focus windows synced to this segment's narration; an unsynced one covers nothing
+  const synced = new Map();   // panel id -> Set of 1-based panel lines
+  for (const a of acts.filter(x => x.op === 'focus')) {
+    const at = `${key}: focus on ${a.panel} at ${a.from}–${a.to}s`;
+    const n = a.narration;
+    const [f, t] = Array.isArray(n) ? n : [n, n];
+    if (!Number.isInteger(f) || !Number.isInteger(t) || t < f) { focus.push(`${at} names no narration line (\`narration: <line>\` or \`[from, to]\` in lines.json)`); continue; }
+    if (typeof a.from !== 'number' || typeof a.to !== 'number') { focus.push(`${at} needs numeric from and to (scene seconds)`); continue; }
+    if (!L) { focus.push(`${at}: lines.json has no segment ${key} (re-run align.mjs)`); continue; }
+    if (f < 0 || t >= L.lines.length) { focus.push(`${at}: narration lines ${f}…${t} do not exist (segment has ${L.lines.length})`); continue; }
+    const lead = L.lead ?? 0, start = L.lines[f].start + lead, end = L.lines[t].end + lead;
+    const next = t + 1 < L.lines.length ? L.lines[t + 1].start + lead : (cfg.total ?? end);
+    if (Math.abs(a.from - start) > TOL) { focus.push(`${at} starts ${(a.from - start).toFixed(2)}s off narration line ${f}'s onset (${start.toFixed(3)}s)`); continue; }
+    if (a.to < end - TOL || a.to > Math.max(end, next) + TOL) { focus.push(`${at} must end between narration line ${t}'s end (${end.toFixed(3)}s) and the next line's onset (${next.toFixed(3)}s)`); continue; }
+    const set = synced.get(a.panel) || synced.set(a.panel, new Set()).get(a.panel);
+    for (const i of a.lines || []) set.add(i);
+  }
+
+  for (const p of cfg.panels) {
+    const at = `${key}/${p.id}`;
+    const src = p.source;
+    if (!src || !src.file || !src.fileSha256 || !src.sha256 || !Number.isInteger(src.start) || !Number.isInteger(src.end)) {
+      drift.push(`${at}: no excerpt source — every code panel of a code video is generated by excerpt.mjs, never typed`); continue;
+    }
+    const lines = p.lines || [], nums = p.numbers || [];
+    if (nums.length !== lines.length) { drift.push(`${at}: numbers[] has ${nums.length} entries for ${lines.length} lines`); continue; }
+    const mined = minedFile(src);
+    if (!mined) { drift.push(`${at}: ${src.file} is not the file excerpt.mjs read (sha256 ${src.fileSha256.slice(0, 12)}…) in the working tree${src.commit ? ` or at commit ${src.commit.slice(0, 12)}` : ''}: re-mine and re-excerpt`); continue; }
+    const file = mined.text.split('\n');
+    if (sha(file.slice(src.start - 1, src.end).join('\n')) !== src.sha256) { drift.push(`${at}: the span ${src.file}:${src.start}-${src.end} no longer matches its sha256`); continue; }
+    const elided = new Map((p.elided || []).map(e => [e.at, e]));
+    let prev = src.start - 1, bad = 0;
+    const visible = nums.filter(n => n != null).length;
+    if (visible > MAX_LINES) drift.push(`${at}: ${visible} lines shown, over the ${MAX_LINES}-line cap`);
+    // the gap an elision marker stands for runs to the next numbered line, or the span's end
+    const nextNum = i => { for (let j = i + 1; j < nums.length; j++) if (nums[j] != null) return nums[j]; return src.end + 1; };
+    lines.forEach((ln, i) => {
+      const n = nums[i];
+      if (n == null) {
+        const e = elided.get(i), mk = MARKER.exec(ln);
+        const from = prev + 1, to = nextNum(i) - 1;
+        if (!e || !mk || e.from !== from || e.to !== to || Number(mk[1]) !== to - from + 1) {
+          drift.push(`${at} line ${i + 1}: "${ln}" is unnumbered but not the elision marker for lines ${from}-${to}`); bad++;
+        }
+        prev = to;
+        return;
+      }
+      if (!Number.isInteger(n) || n <= prev || n < src.start || n > src.end) { drift.push(`${at} line ${i + 1}: number ${n} is out of order or outside ${src.file}:${src.start}-${src.end}`); bad++; prev = Math.max(prev, Number(n) || prev); return; }
+      if (n !== prev + 1) { drift.push(`${at}: ${src.file}:${prev + 1}-${n - 1} hidden without an elision marker`); bad++; }
+      if (ln !== file[n - 1]) { drift.push(`${at}: ${src.file}:${n} differs from the file (${JSON.stringify(ln)} vs ${JSON.stringify(file[n - 1])})`); bad++; }
+      prev = n;
+    });
+    if (prev < src.end) { drift.push(`${at}: ${src.file}:${prev + 1}-${src.end} hidden without an elision marker`); bad++; }
+
+    // narration is the reading time: every shown line in a narration-synced focus window, except in a pause segment
+    const covered = synced.get(p.id) || new Set();
+    const unread = lines.map((ln, i) => ({ ln, i, n: nums[i] })).filter(x => x.n != null && x.ln.trim() && !covered.has(x.i + 1));
+    if (unread.length && !isPause) focus.push(`${at}: ${unread.length} shown line(s) outside every narration-synced focus window: ${src.file}:${unread.map(x => x.n).join(',')}`);
+    report.push(`  ${bad ? '✗' : '✓'} ${at.padEnd(24)} ${src.test ? `test ${src.test.split(':').pop()}` : src.symbol || src.file} · ${visible} lines · ${mined.from}${isPause ? ' · pause segment' : ''}${unread.length ? ` · ${unread.length} unfocused` : ''}`);
+  }
+}
+for (const k of pauseSegs) if (!scenes.some(s => s.key === k)) focus.push(`${k}: a pause segment shows no pause badge (only a code scene with panels shows one; host it there)`);
+if (pauseSegs.size > MAX_PAUSES) focus.push(`${pauseSegs.size} pause segments (max ${MAX_PAUSES}): a video that asks for that much silent reading must be split`);
+
+console.log(`\nexcerpt-check ${WORK}`);
+console.log(`  ${scenes.length} code scene(s) · ${scenes.reduce((a, s) => a + s.cfg.panels.length, 0)} panel(s) · ${pauseSegs.size} pause segment(s)`);
+report.forEach(r => console.log(r));
+if (drift.length) { console.log(`\n  ✗ ${drift.length} drift problem(s):`); drift.forEach(d => console.log(`     - ${d}`)); }
+if (focus.length) { console.log(`\n  ✗ ${focus.length} focus problem(s):`); focus.forEach(d => console.log(`     - ${d}`)); }
+if (!drift.length && !focus.length) console.log('\n  ✓ every panel is the mined code, and every shown line is narrated');
+process.exitCode = drift.length ? 2 : focus.length ? 3 : 0;

package/skills/explainer-video-from-codebase/tools/excerpt.mjs

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+/* =============================================================================
+   excerpt.mjs — one code panel for a scene, cut from the repo as it was mined.
+
+   Usage:
+     node tools/excerpt.mjs --codemap out/<name>/codemap.json --symbol <id> [--lines a-b,…]
+     node tools/excerpt.mjs --codemap out/<name>/codemap.json --symbol <id> --test <test id> [--lines a-b,…]
+
+   Prints a panel fragment for scene-code.js (design §4.6):
+     { file, lang, lines[], numbers[], elided[], source }
+   `lines` are the file's lines, byte for byte; `numbers` their real line numbers.
+   Narration is the reading time, so only narrated lines are shown: `--lines`
+   ("54-65,70", inside the symbol's span) picks them, and every unshown run inside
+   the span collapses into one elision marker ("⋯ 4 lines"), whose number is null
+   and whose index is in `elided` ({at, from, to}). A run of blank lines is shown,
+   not elided. Without `--lines` the whole span is shown.
+
+   With --test, the panel is the test's side of a "pinned by" pair: the test's
+   def line (its name, which the narration says), the line where it calls the hop
+   (its direct link) and its assertion lines, elided between. The test must link
+   to --symbol directly and must not mock it.
+
+   `source` {file, symbol | test, start, end, sha256, fileSha256, commit} is what
+   excerpt-check.mjs verifies the panel against: `sha256` is the shown span's
+   (for a symbol, the code map's own), `fileSha256` the file's when mined.
+
+   Exit: 0 ok · 1 bad flags or unreadable code map · 2 symbol or test missing, a
+         line outside the span, a test that does not pin the symbol, the file
+         changed since it was mined, or more than 22 shown lines
+   ========================================================================== */
+import { readFileSync, existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { createHash } from 'node:crypto';
+
+const fail = (code, msg) => { console.error(`[excerpt] ${msg}`); process.exit(code); };
+
+/* ---------------- args ---------------- */
+const argv = process.argv.slice(2);
+const VALUED = new Set(['--codemap', '--symbol', '--lines', '--test']);
+const flags = new Map();
+for (let i = 0; i < argv.length; i++) {
+  if (VALUED.has(argv[i])) { if (argv[i + 1] == null) fail(1, `${argv[i]} needs a value`); flags.set(argv[i], argv[++i]); }
+  else fail(1, `unknown argument ${argv[i]}`);
+}
+if (!flags.has('--codemap') || !flags.has('--symbol')) fail(1, 'usage: excerpt.mjs --codemap out/<name>/codemap.json --symbol <id> [--lines a-b,…] [--test <test id>]');
+const MAX = 22;
+let m;
+try { m = JSON.parse(readFileSync(resolve(flags.get('--codemap')), 'utf8')); } catch (e) { fail(1, `cannot read the code map: ${e.message}`); }
+if (m?.schema !== 1 || !Array.isArray(m.symbols)) fail(1, 'not a mine.mjs code map (schema 1)');
+
+const sha = t => createHash('sha256').update(t).digest('hex');
+const symId = flags.get('--symbol'), testId = flags.get('--test');
+const sym = m.symbols.find(s => s.id === symId);
+if (!sym) fail(2, `no symbol ${symId} in the code map`);
+
+/* ---------------- what span, which file ---------------- */
+let span, shown, test = null;
+if (testId) {
+  test = (m.tests || []).find(t => t.id === testId);
+  if (!test) fail(2, `no test ${testId} in the code map`);
+  if (test.mocked.includes(symId)) fail(2, `test ${testId} mocks ${symId}: a test that replaces a hop cannot pin it`);
+  const link = test.direct.find(l => l.to === symId);
+  if (!link) fail(2, `test ${testId} has no direct link to ${symId}: only a direct, unmocked link may be shown as pinning it`);
+  span = { file: test.file, start: test.line, end: test.end };
+  // its name, the call line when it is in the test's own body (a fixture or helper calls from elsewhere), the assertions
+  const call = link.line >= test.line && link.line <= test.end ? [link.line] : [];
+  if (!call.length && !test.assertLines.length) fail(2, `test ${testId} has neither a call line nor an assertion line inside its body to show`);
+  shown = [...new Set([test.line, ...call, ...test.assertLines])].sort((a, b) => a - b);
+} else span = { file: sym.file, start: sym.start, end: sym.end };
+
+const file = (m.files || []).find(f => f.path === span.file);
+const path = join(m.root, span.file);
+if (!file || !existsSync(path)) fail(2, `${span.file} is not in the mined repo at ${m.root}`);
+const text = readFileSync(path, 'utf8');
+if (sha(text) !== file.sha256) fail(2, `${span.file} changed since it was mined: re-mine before excerpting, so the panel shows the code the flow was built from`);
+const all = text.split('\n');
+const spanSha = sha(all.slice(span.start - 1, span.end).join('\n'));
+if (!test && spanSha !== sym.sha256) fail(2, `${symId}'s span no longer matches the code map: re-mine`);
+
+if (flags.has('--lines')) {
+  shown = [];
+  for (const part of flags.get('--lines').split(',')) {
+    const r = /^\s*(\d+)(?:\s*-\s*(\d+))?\s*$/.exec(part);
+    if (!r) fail(1, `--lines takes ranges like "54-65,70", not "${part}"`);
+    const a = Number(r[1]), b = Number(r[2] ?? r[1]);
+    if (b < a || a < span.start || b > span.end) fail(2, `lines ${a}-${b} are outside ${testId || symId} (lines ${span.start}-${span.end} of ${span.file})`);
+    for (let n = a; n <= b; n++) shown.push(n);
+  }
+  shown = [...new Set(shown)].sort((a, b) => a - b);
+} else if (!test) shown = Array.from({ length: span.end - span.start + 1 }, (_, i) => span.start + i);
+
+/* ---------------- lines, numbers, elision markers ---------------- */
+const blank = n => !all[n - 1].trim();
+const lines = [], numbers = [], elided = [];
+const gap = (from, to) => {
+  if (from > to) return;
+  const hidden = Array.from({ length: to - from + 1 }, (_, i) => from + i);
+  if (hidden.every(blank)) { for (const n of hidden) { lines.push(all[n - 1]); numbers.push(n); } return; }
+  // the marker sits at the hidden block's outer indent: its least-indented non-blank line
+  const indent = hidden.filter(n => !blank(n)).map(n => /^\s*/.exec(all[n - 1])[0]).reduce((a, b) => (b.length < a.length ? b : a));
+  elided.push({ at: lines.length, from, to });
+  lines.push(`${indent}⋯ ${to - from + 1} line${to === from ? '' : 's'}`);
+  numbers.push(null);
+};
+let prev = span.start - 1;
+for (const n of shown) { gap(prev + 1, n - 1); lines.push(all[n - 1]); numbers.push(n); prev = n; }
+gap(prev + 1, span.end);
+const visible = numbers.filter(n => n != null).length;
+if (visible > MAX) fail(2, `${visible} lines shown, over the ${MAX}-line cap: narrow them with --lines (only narrated lines belong on screen), or split the hop`);
+
+const panel = {
+  file: span.file, lang: file.lang, lines, numbers, elided,
+  source: { file: span.file, ...(test ? { test: test.id, pins: symId, via: test.direct.find(l => l.to === symId).via } : { symbol: symId }),
+    start: span.start, end: span.end, sha256: spanSha, fileSha256: file.sha256, commit: m.commit },
+};
+console.log(JSON.stringify(panel, null, 2));