explainer-video 0.0.0-stage → 0.4.0

package/skills/explainer-video-from-codebase/tools/lib/observe.mjs

@@ -0,0 +1,162 @@
+/* Map the Python collector's records onto a code map (design §3.17, Appendix A.7): which static edges fired, which
+   code ran under which test, and which calls ran with no static edge at all. It never removes or demotes an edge: the
+   result is an overlay beside the code map, which is not edited.
+
+   A record is (caller, callee, test, calls), each code unit as [file relative to the repo root, co_qualname]. Its id
+   is the code map's: `pkg.module:Class.method`, `…:outer.<locals>.inner`, `pkg.module:<module>` for module code. */
+
+const KINDS = ['static', 'ctor', 'virtual', 'dispatch', 'framework', 'queue', 'http'];
+const STATUS_RANK = { error: 4, failed: 3, xpassed: 2, passed: 1, xfailed: 0, skipped: 0 };
+
+const modOf = rel => rel.replace(/\.py$/, '').replace(/\/__init__$/, '').split('/').join('.');
+const idOf = ([rel, q]) => `${modOf(rel)}:${q}`;
+const byStr = (a, b) => a < b ? -1 : a > b ? 1 : 0;
+const pairKey = (a, b) => a + '|' + b;
+
+// a test's outcome from its phases: pytest's counting (a failed setup is an error, a failed teardown adds one); a
+// test with no call report was cut off mid-call (the time limit) and is an error
+function statusOf(rec) {
+  if (rec.call === 'error' || rec.setup === 'failed') return 'error';
+  if (rec.setup === 'skipped' || rec.call === 'skipped') return rec.xfail ? 'xfailed' : 'skipped';
+  if (rec.call === 'failed') return 'failed';
+  if (rec.call === 'xfailed' || rec.call === 'xpassed') return rec.call;
+  if (rec.call === 'passed') return rec.xfail ? 'xpassed' : 'passed';
+  return 'error';
+}
+
+function category(sym, grp, a, b) {
+  const n = b.split(/[.:]/).pop(), s = sym.get(b);
+  if (/^__\w+__$/.test(n) && n !== '__init__') return 'dunder';
+  if ((s.decos || []).some(d => /property|setter|cached_property/.test(d))) return 'property';
+  if ((s.decos || []).some(d => /validator|model_validator|field_validator|computed_field/.test(d))) return 'validator';
+  if (grp(a) === 'test' || grp(b) === 'test') return 'test-side';
+  if (n === '__init__') return 'init';
+  return 'other';
+}
+
+export function observe(m, dumps) {
+  const sym = new Map(m.symbols.map(s => [s.id, s]));
+  const grp = id => sym.get(id)?.group || '?';
+  const callable = id => sym.has(id) && sym.get(id).kind !== 'class' && sym.get(id).kind !== 'main';
+  const tests = m.tests || [];
+  const dotted = new Map(tests.map(t => [t.id.replace(':', '.'), t.id]));
+  const known = new Set(tests.map(t => t.id));
+  // a collector key (`tests/x.py::Class::test[param]`, `unittest::pkg.mod.Class.test`) -> the code map's test id
+  const testIdOf = key => {
+    if (key.startsWith('unittest::')) return dotted.get(key.slice('unittest::'.length)) || null;
+    const [path, ...rest] = key.split('::');
+    const id = `${modOf(path)}:${rest.join('.').replace(/\[.*\]$/, '')}`;
+    return known.has(id) ? id : null;
+  };
+  const nameOf = key => testIdOf(key) || key;
+
+  /* ---- merge every process's records ---- */
+  const pairs = new Map(), ranBy = new Map(), outcomes = new Map(), network = new Map(), collectErrors = new Map(), fixtureErrors = new Map();
+  let collected = null, records = 0, unmappedRecords = 0, bodies = 0;
+  const unmappedSample = new Set(), python = new Set();
+  for (const d of dumps) {
+    if (d.python) python.add(d.python);
+    if (d.collected != null) collected = Math.max(collected ?? 0, d.collected);
+    for (const e of d.collectErrors || []) collectErrors.set(e.nodeid, e);
+    for (const e of d.fixtureErrors || []) fixtureErrors.set(e.nodeid, e);
+    for (const [k, rec] of Object.entries(d.outcomes || {})) outcomes.set(k, { ...outcomes.get(k), ...rec });
+    for (const [k, v] of Object.entries(d.network || {})) network.set(k, [...new Set([...(network.get(k) || []), ...v])]);
+    for (const p of d.pairs || []) {
+      records++;
+      const to = idOf(p.to);
+      if (!callable(to)) {
+        if (p.to[1] === '<module>' || sym.get(to)?.kind === 'class') bodies++;
+        else { unmappedRecords++; if (unmappedSample.size < 8) unmappedSample.add(to); }
+        continue;
+      }
+      if (p.test != null) { const t = nameOf(p.test); (ranBy.get(t) || ranBy.set(t, { keys: new Set(), ran: new Set() }).get(t)).ran.add(to); ranBy.get(t).keys.add(p.test); }
+      if (!p.from) continue;
+      const from = idOf(p.from), k = pairKey(from, to);
+      const x = pairs.get(k) || pairs.set(k, { from, to, n: 0, tests: new Set() }).get(k);
+      x.n += p.n;
+      if (p.test != null) x.tests.add(nameOf(p.test));
+    }
+  }
+
+  /* ---- outcome, failures, tests the sandbox denied ---- */
+  const outcome = { collected: Math.max(collected ?? 0, outcomes.size), passed: 0, failed: 0, errors: collectErrors.size + fixtureErrors.size, skipped: 0, xfailed: 0, xpassed: 0 };
+  const statusBy = new Map(), failures = [], denied = [];
+  for (const [key, rec] of [...outcomes].sort(([a], [b]) => byStr(a, b))) {
+    const status = statusOf(rec), name = nameOf(key);
+    outcome[{ passed: 'passed', failed: 'failed', error: 'errors', skipped: 'skipped', xfailed: 'xfailed', xpassed: 'xpassed' }[status]]++;
+    if (rec.teardown === 'failed') outcome.errors++;
+    const prev = statusBy.get(name);
+    if (!prev || STATUS_RANK[status] > STATUS_RANK[prev]) statusBy.set(name, status);
+    if (status !== 'failed' && status !== 'error' && rec.teardown !== 'failed') continue;
+    const phase = rec.setup === 'failed' ? 'setup' : (status === 'failed' || status === 'error') ? 'call' : 'teardown';
+    failures.push({ test: testIdOf(key), nodeid: rec.nodeid || key, status, phase, message: rec.message || '' });
+    const net = network.get(key) || [];
+    if (net.length || rec.permission) denied.push({ test: testIdOf(key), nodeid: rec.nodeid || key, status, network: net, permission: !!rec.permission, message: rec.message || '' });
+  }
+  for (const e of [...collectErrors.values()].sort((a, b) => byStr(a.nodeid, b.nodeid)))
+    failures.push({ test: null, nodeid: e.nodeid, status: 'error', phase: 'collect', message: e.message || '' });
+  for (const e of [...fixtureErrors.values()].sort((a, b) => byStr(a.nodeid, b.nodeid))) {
+    failures.push({ test: null, nodeid: e.nodeid, status: 'error', phase: e.phase, message: e.message || '' });
+    const net = network.get(e.nodeid) || [];
+    if (net.length || e.permission) denied.push({ test: null, nodeid: e.nodeid, status: 'error', network: net, permission: !!e.permission, message: e.message || '' });
+  }
+
+  /* ---- static edges that fired ---- */
+  const uniq = [...new Map(m.edges.map(e => [e.from + '|' + e.to + '|' + e.kind, e])).values()];
+  const countable = uniq.filter(e => KINDS.includes(e.kind) && sym.has(e.from) && callable(e.to));
+  const fired = e => pairs.get(pairKey(e.from, e.to));
+  const tally = edges => { const byKind = {}; let observed = 0;
+    for (const e of edges) { const k = e.kind + (e.rule ? '/' + e.rule : ''); const b = byKind[k] || (byKind[k] = [0, 0]); b[1]++; if (fired(e)) { b[0]++; observed++; } }
+    return { observed, total: edges.length, byKind: Object.fromEntries(Object.entries(byKind).sort(([a], [b]) => byStr(a, b))) }; };
+  const edges = countable.filter(fired).map(e => { const p = fired(e);
+    return { from: e.from, to: e.to, kind: e.kind, ...(e.rule ? { rule: e.rule } : {}), ...(e.passedBy ? { passedBy: e.passedBy } : {}), n: p.n, tests: [...p.tests].sort(byStr) }; })
+    .sort((a, b) => byStr(a.from, b.from) || byStr(a.to, b.to) || byStr(a.kind, b.kind));
+
+  /* ---- per test: direct links that ran under their own test ---- */
+  const byTest = {};
+  let dObs = 0, dAll = 0, pObs = 0, pAll = 0, linkedTests = 0;
+  const testById = new Map(tests.map(t => [t.id, t]));
+  for (const name of [...new Set([...ranBy.keys(), ...statusBy.keys()])].sort(byStr)) {
+    const r = ranBy.get(name), ran = r?.ran || new Set(), t = testById.get(name);
+    const direct = t ? [...new Set(t.direct.map(d => d.to).filter(to => callable(to) && grp(to) !== 'test'))] : [];
+    const missing = r ? direct.filter(to => !ran.has(to)).sort(byStr) : [];
+    if (r && direct.length) { linkedTests++; dAll += direct.length; dObs += direct.length - missing.length;
+      const prod = direct.filter(to => grp(to) === 'prod'); pAll += prod.length; pObs += prod.filter(to => ran.has(to)).length; }
+    byTest[name] = { nodeids: [...(r?.keys || [])].sort(byStr), status: statusBy.get(name) || null, ran: [...ran].sort(byStr),
+      direct: { total: direct.length, observed: direct.length - missing.length, missing } };
+  }
+  let fixO = 0, fixN = 0;
+  for (const b of m.fixtureBindings || []) { const r = ranBy.get(b.fn); if (!r) continue; fixN++; if (r.ran.has(b.fixture)) fixO++; }
+
+  /* ---- calls that ran with no static edge of any kind ---- */
+  const anyEdge = new Set(m.edges.map(e => pairKey(e.from, e.to)));
+  const noStaticEdge = [...pairs.values()].filter(p => sym.has(p.from) && p.from !== p.to && !anyEdge.has(pairKey(p.from, p.to)))
+    .map(p => ({ from: p.from, to: p.to, n: p.n, tests: p.tests.size, category: category(sym, grp, p.from, p.to) }))
+    .sort((a, b) => byStr(a.from, b.from) || byStr(a.to, b.to));
+  const byCategory = {};
+  for (const x of noStaticEdge) byCategory[x.category] = (byCategory[x.category] || 0) + 1;
+  // the callback links (a callable handed to the code that runs it) the run confirmed
+  const callbacks = edges.filter(e => e.rule === 'py.callback').map(e => ({ from: e.from, to: e.to, passedBy: e.passedBy || null, tests: e.tests.length }));
+  const prodNoEdge = noStaticEdge.filter(x => x.category === 'other' && grp(x.from) === 'prod' && grp(x.to) === 'prod').length;
+
+  const fns = m.symbols.filter(s => s.kind === 'function' || s.kind === 'method');
+  const ranAnywhere = new Set([...ranBy.values()].flatMap(r => [...r.ran]).concat([...pairs.values()].map(p => p.to)));
+  const functionsRan = {};
+  for (const g of ['prod', 'eval', 'test', 'dev']) { const f = fns.filter(s => s.group === g); functionsRan[g] = { ran: f.filter(s => ranAnywhere.has(s.id)).length, total: f.length }; }
+
+  const summary = {
+    records, distinctPairs: pairs.size, functionsRan,
+    edges: { all: tally(countable), prodToProd: tally(countable.filter(e => grp(e.from) === 'prod' && grp(e.to) === 'prod')),
+      testToNonTest: tally(countable.filter(e => grp(e.from) === 'test' && grp(e.to) !== 'test')) },
+    directLinksPerTest: { tests: linkedTests, observed: dObs, total: dAll, prod: { observed: pObs, total: pAll } },
+    fixtureLinks: { observed: fixO, total: fixN },
+    noStaticEdge: { pairs: noStaticEdge.length, prodToProd: prodNoEdge, byCategory: Object.fromEntries(Object.entries(byCategory).sort(([a], [b]) => byStr(a, b))) },
+    callbacks: callbacks.length,
+    unmapped: { records: unmappedRecords, sample: [...unmappedSample].sort(byStr) }, moduleAndClassBodies: bodies,
+  };
+  return {
+    python: [...python].sort(byStr), outcome, failures, deniedBySandbox: denied, summary,
+    pairs: [...pairs.values()].map(p => ({ from: p.from, to: p.to, n: p.n, tests: p.tests.size })).sort((a, b) => byStr(a.from, b.from) || byStr(a.to, b.to)),
+    edges, noStaticEdge, callbacks, byTest,
+  };
+}

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

@@ -0,0 +1,28 @@
+/* Redact credential-shaped strings from what a traced test run printed, before trace.mjs writes it to trace.log, shows
+   its tail or keeps a failure message in trace.json: private-key blocks, AWS access key ids, bearer and basic auth
+   headers, well-known token formats, JWTs, a URL's password, and the value of any key=value or "key": "value" whose
+   key names a secret (password, secret, token, api key, credential, ...). The secret is replaced, its label kept. */
+export const REDACTED = '[REDACTED]';
+
+// a key that names a secret (`db_password`, `API_KEY`, `x-auth-token`), but not `author` or `tokenizer.py`
+const SECRET_KEY = String.raw`[A-Za-z0-9_-]*(?:passw(?:or)?d|pwd|secret|token|api[_-]?key|access[_-]?key|private[_-]?key|credentials?|authorization|auth(?![a-z]))[A-Za-z0-9_-]*`;
+
+const RULES = [
+  // a private key block, or its first line when the output was cut short
+  [/-----BEGIN ([A-Z0-9 ]*)PRIVATE KEY-----[\s\S]*?(?:-----END \1PRIVATE KEY-----|$(?![\s\S]))/g, `-----BEGIN $1PRIVATE KEY----- ${REDACTED}`],
+  [/(\b(?:Bearer|Basic|Token)\s+)[A-Za-z0-9._~+/=-]{8,}/gi, `$1${REDACTED}`],
+  [/(:\/\/[^\s:/@]+:)[^\s@/]+@/g, `$1${REDACTED}@`],
+  // "key": "value" and key: 'value'
+  [new RegExp(String.raw`(["']?\b${SECRET_KEY}["']?\s*[:=](?![:=])\s*)(["'])(?:(?!\2)[^\\\n]|\\.)+\2`, 'gi'), `$1$2${REDACTED}$2`],
+  // key=value, key: value (unquoted, to the end of the word)
+  [new RegExp(String.raw`(\b${SECRET_KEY}\s*[:=](?![:=])\s*)(?!["'\s]|\[REDACTED\]|(?:Bearer|Basic|Token)\s)[^\s,;&'"}\])]+`, 'gi'), `$1${REDACTED}`],
+  [/\b(?:AKIA|ASIA|ABIA|ACCA|AGPA|AIDA|AROA|ANPA)[0-9A-Z]{16}\b/g, REDACTED],
+  [/\b(?:gh[pousr]_[A-Za-z0-9]{30,}|github_pat_[A-Za-z0-9_]{30,}|glpat-[A-Za-z0-9_-]{20,}|xox[abposr]-[A-Za-z0-9-]{10,}|sk-[A-Za-z0-9_-]{20,}|AIza[0-9A-Za-z_-]{35}|npm_[A-Za-z0-9]{36})\b/g, REDACTED],
+  [/\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/g, REDACTED],
+];
+
+export function redactSecrets(text) {
+  let s = String(text ?? '');
+  for (const [re, by] of RULES) s = s.replace(re, by);
+  return s;
+}

package/skills/explainer-video-from-codebase/tools/lib/sandbox.mjs

@@ -0,0 +1,97 @@
+/* The OS sandboxes trace.mjs runs a repo's test command in (design §3.17, ADR-014). Each one denies all network (IP,
+   localhost and unix-socket connects), every write outside the scratch dir, and every read of the hidden paths (the
+   user's home folder and the original repo) except the read-only paths the run needs (the interpreter and its
+   virtualenv); the caller passes an empty environment.
+   - macos: sandbox-exec with trace/sandbox/macos-nonet.sb, plus the read rules built here for these paths;
+   - bwrap: bubblewrap through trace/sandbox/linux-bwrap.sh (namespaces, read-only /, the hidden paths replaced by
+     empty dirs, a seccomp filter on unix sockets).
+   There is no unsandboxed mode: where this platform's sandbox does not start, the caller refuses (exit 4). */
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync, realpathSync, mkdtempSync, rmSync, openSync, fstatSync, closeSync, readSync, constants } from 'node:fs';
+import { join, dirname, sep } from 'node:path';
+import { tmpdir, homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+const DIR = join(dirname(fileURLToPath(import.meta.url)), '..', 'trace', 'sandbox');
+export const MACOS_PROFILE = join(DIR, 'macos-nonet.sb');
+export const BWRAP_SCRIPT = join(DIR, 'linux-bwrap.sh');
+const SANDBOX_EXEC = '/usr/bin/sandbox-exec';
+export const SANDBOX_LABEL = { macos: 'macos-sandbox-exec:macos-nonet.sb', bwrap: 'linux-bwrap:linux-bwrap.sh' };
+const KIND_OF = { darwin: 'macos', linux: 'bwrap' };
+
+const strip = p => p.replace(/\/+$/, '') || '/';
+const inside = (p, dir) => p === dir || p.startsWith(dir === '/' ? '/' : dir + sep);
+const sbString = p => `"${p.replace(/[\\"]/g, c => '\\' + c)}"`;
+const ancestors = p => { const out = []; for (let d = dirname(p); d !== dirname(d); d = dirname(d)) out.push(d); return out; };
+
+// the read-only paths the sandbox may expose: never scratch or one of its parents (a read-only mount there would make
+// scratch read-only too), never a hidden path or one of its parents (that would expose all of it)
+export function exposable(p, { scratch, hidden }) {
+  if (!p || !existsSync(p)) return false;
+  const d = strip(p);
+  return !inside(strip(scratch), d) && !hidden.some(h => inside(strip(h), d));
+}
+
+// a file the sandboxed run wrote (or could have replaced), read from outside the sandbox: opened without following a
+// symlink and without waiting (a FIFO the run left there never blocks), and read only when the open file is a plain
+// file; null otherwise
+function withRunFile(p, read) {
+  let fd = null;
+  try { fd = openSync(p, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK); return fstatSync(fd).isFile() ? read(fd) : null; }
+  catch { return null; } finally { if (fd != null) closeSync(fd); }
+}
+export const readRunFile = p => withRunFile(p, fd => readFileSync(fd, 'utf8'));
+// its first n bytes (fewer when it is shorter), as a Buffer
+export const readRunHead = (p, n) => withRunFile(p, fd => { const b = Buffer.alloc(n); return b.subarray(0, readSync(fd, b, 0, n, 0)); });
+// the same, parsed as JSON: [value], or [] when it cannot be read or parsed
+export function readRunJson(p) {
+  const t = readRunFile(p); if (t == null) return [];
+  try { return [JSON.parse(t)]; } catch { return []; }
+}
+
+// the read rules the macOS profile gets for this run: nothing under a hidden path, except scratch and the read-only
+// paths, and the metadata (not the contents) of the hidden dirs above those, so a path to them still resolves
+function macosReadRules({ scratch, hidden, readOnly }) {
+  const allowed = [scratch, ...readOnly].map(strip);
+  const above = [...new Set(allowed.flatMap(ancestors).filter(a => hidden.some(h => inside(a, strip(h)))))].sort();
+  if (!hidden.length) return '';
+  return [
+    `(deny file-read* ${hidden.map(h => `(subpath ${sbString(strip(h))})`).join(' ')})`,
+    `(allow file-read* ${allowed.map(p => `(subpath ${sbString(p)})`).join(' ')})`,
+    ...(above.length ? [`(allow file-read-metadata ${above.map(a => `(literal ${sbString(a)})`).join(' ')})`] : []),
+  ].join('\n');
+}
+
+// the command line that runs argv inside the sandbox
+export function sandboxArgv(kind, { scratch, hidden = [homedir()], readOnly = [], argv }) {
+  const ro = readOnly.filter(p => exposable(p, { scratch, hidden })).map(strip);
+  if (kind === 'macos') {
+    const profile = `${readFileSync(MACOS_PROFILE, 'utf8')}\n; reads, for this run\n${macosReadRules({ scratch, hidden, readOnly: [...new Set(ro)] })}\n`;
+    return [SANDBOX_EXEC, '-p', profile, '-D', `SCRATCH=${scratch}`, ...argv];
+  }
+  // the script applies each list last line first: longest first, so a dir is mounted before the paths inside it
+  const deepestFirst = ps => [...new Set(ps)].sort((a, b) => b.length - a.length).join('\n');
+  return ['/bin/sh', BWRAP_SCRIPT, scratch, deepestFirst(hidden.filter(h => existsSync(h)).map(strip)), deepestFirst(ro), ...argv];
+}
+
+// can this platform's sandbox run here? A probe runs `true` inside it: sandbox-exec refuses inside another sandbox,
+// and bwrap fails where unprivileged user namespaces are off
+export function sandboxWorks(kind) {
+  if (kind === 'macos' && !existsSync(SANDBOX_EXEC)) return { ok: false, why: `${SANDBOX_EXEC} is missing` };
+  const scratch = realpathSync(mkdtempSync(join(tmpdir(), 'fmtrace-probe-')));
+  const [cmd, ...args] = sandboxArgv(kind, { scratch, argv: [kind === 'macos' ? '/usr/bin/true' : '/bin/true'] });
+  const r = spawnSync(cmd, args, { env: { PATH: '/usr/local/bin:/usr/bin:/bin' }, encoding: 'utf8', timeout: 20000 });
+  rmSync(scratch, { recursive: true, force: true });
+  if (r.status === 0) return { ok: true };
+  const why = (r.error?.message || r.stderr || `exit ${r.status}`).trim().split('\n').pop();
+  return { ok: false, why: kind === 'bwrap' && /ENOENT|not found/.test(why) ? 'bwrap is not installed' : `the ${kind} sandbox does not start here: ${why}` };
+}
+
+// this platform's sandbox, or why there is none: a platform without one and a sandbox that cannot start here are
+// refusals, never a fallback
+export function pickSandbox() {
+  const kind = KIND_OF[process.platform];
+  if (!kind) return { why: `no OS sandbox is supported on ${process.platform}` };
+  const w = sandboxWorks(kind);
+  return w.ok ? { kind } : { why: w.why };
+}

package/skills/explainer-video-from-codebase/tools/lib/test-links.mjs

@@ -0,0 +1,28 @@
+/* Direct test links, for every language whose test pack records tests, hooks bound as framework edges, and mock
+   targets (jest / vitest, go test, gtest / Catch2): every edge from a test's own side (its body, its hooks, test-side
+   helpers, reached through test-group edges) into non-test code is a direct link to its target, unless that test
+   mocks the target. A mock with a `scope: 'session'` applies to every test under its `covers` directory; one recorded
+   on `<file>:<module>` (hoisted) to every test in that file; any other to the tests whose side holds its `fn`. */
+const under = (dir, file) => !dir || file.startsWith(dir + '/');
+
+const FOLLOW = new Set(['static', 'ctor', 'framework', 'dispatch', 'queue', 'http', 'virtual']);
+export function directLinks(tests, mocks, edges, symbolOf) {
+  const out = new Map(); for (const e of edges) (out.get(e.from) || out.set(e.from, []).get(e.from)).push(e);
+  const G = id => symbolOf(id)?.group || (id.startsWith('ext:') ? 'ext' : 'prod');
+  const mocksIn = new Map(); for (const m of mocks) if (m.target && !m.scope) (mocksIn.get(m.fn) || mocksIn.set(m.fn, new Set()).get(m.fn)).add(m.target);
+  const session = mocks.filter(m => m.target && m.scope === 'session');
+  for (const t of tests) {
+    const side = new Set([t.id]), q = [t.id];
+    while (q.length) { const x = q.pop(); for (const e of out.get(x) || []) if (FOLLOW.has(e.kind) && G(e.to) === 'test' && !side.has(e.to)) { side.add(e.to); q.push(e.to); } }
+    const mocked = new Set(session.filter(m => under(m.covers, t.file)).map(m => m.target));
+    for (const s of [...side, `${t.file}:<module>`]) for (const m of mocksIn.get(s) || []) mocked.add(m);
+    const hooks = new Set([...side].filter(s => symbolOf(s)?.hook));
+    const links = new Map();
+    for (const s of side) for (const e of out.get(s) || []) {
+      if (!FOLLOW.has(e.kind) || G(e.to) === 'test' || e.to.startsWith('ext:') || mocked.has(e.to) || symbolOf(e.to)?.kind === 'class' || links.has(e.to)) continue;
+      links.set(e.to, { to: e.to, via: s === t.id ? 'body' : hooks.has(s) ? 'fixture' : 'helper', viaId: s, kind: e.kind, ...(e.rule ? { rule: e.rule } : {}), line: e.line, ...(e.recvClass ? { recvClass: e.recvClass } : {}) });
+    }
+    t.mocked = [...mocked].sort();
+    t.direct = [...links.values()];
+  }
+}

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

@@ -0,0 +1,129 @@
+/* A TOML reader for dependency manifests (pyproject.toml, Pipfile): tables, arrays of tables, dotted and quoted keys,
+   the four string forms with their escapes, arrays and inline tables, comments anywhere a comment may stand. Numbers,
+   booleans and dates are kept as their source text, since a dependency name is only ever a string or a key. A `]`
+   inside a string (`"uvicorn[standard]"`) is string content, never the end of an array. Throws on a malformed
+   document, the way tomllib does. */
+const BARE = /[A-Za-z0-9_-]+/y;
+const SCALAR = /\d{4}-\d{2}-\d{2}[ T]\d{2}:[^\s,\]}#]*|[^\s,\]}#]+/y;
+const ESC = { b: '\b', t: '\t', n: '\n', f: '\f', r: '\r', e: '\x1b', '"': '"', '\\': '\\' };
+const isTable = v => v !== null && typeof v === 'object' && !Array.isArray(v);
+const table = () => Object.create(null);
+
+export function parseToml(src) {
+  let i = 0;
+  const err = msg => { throw new Error(`TOML: ${msg} at line ${src.slice(0, i).split('\n').length}`); };
+  const ws = () => { while (src[i] === ' ' || src[i] === '\t') i++; };
+  const comment = () => { if (src[i] === '#') while (i < src.length && src[i] !== '\n') i++; };
+  const gap = () => { for (;;) { ws(); comment(); if (src[i] === '\n' || src[i] === '\r') i++; else return; } };   // blank lines and comments
+  const eol = () => { ws(); comment(); if (src[i] === '\r') i++; if (i < src.length && src[i] !== '\n') err('expected the end of the line'); i++; };
+
+  function str() {
+    const q = src[i], multi = src.startsWith(q.repeat(3), i);
+    i += multi ? 3 : 1;
+    if (multi && src[i] === '\n') i++; else if (multi && src.startsWith('\r\n', i)) i += 2;   // a newline right after """ is dropped
+    let out = '';
+    for (;;) {
+      if (i >= src.length) err('unterminated string');
+      const c = src[i];
+      if (!multi && c === q) { i++; return out; }
+      if (multi && src.startsWith(q.repeat(3), i)) { let n = 3; while (n < 5 && src[i + n] === q) n++; out += q.repeat(n - 3); i += n; return out; }
+      if (!multi && c === '\n') err('newline in a single-line string');
+      if (q === '"' && c === '\\') {
+        const e = src[i + 1];
+        if (multi && /[ \t\r\n]/.test(e)) {   // a line-ending backslash swallows the newline and the whitespace after it
+          let j = i + 1; while (src[j] === ' ' || src[j] === '\t') j++;
+          if (src[j] === '\r') j++;
+          if (src[j] !== '\n') err('invalid escape');
+          while (/[ \t\r\n]/.test(src[j] ?? '')) j++;
+          i = j; continue;
+        }
+        const hex = { x: 2, u: 4, U: 8 }[e];
+        if (hex) { const h = src.slice(i + 2, i + 2 + hex); if (!new RegExp(`^[0-9a-fA-F]{${hex}}$`).test(h)) err('invalid escape'); out += String.fromCodePoint(parseInt(h, 16)); i += 2 + hex; continue; }
+        if (!(e in ESC)) err('invalid escape');
+        out += ESC[e]; i += 2; continue;
+      }
+      out += c; i++;
+    }
+  }
+
+  function key() {
+    const parts = [];
+    for (;;) {
+      ws();
+      if (src[i] === '"' || src[i] === "'") { if (src.startsWith(src[i].repeat(3), i)) err('a key cannot be a multi-line string'); parts.push(str()); }
+      else { BARE.lastIndex = i; const m = BARE.exec(src); if (!m) err('expected a key'); parts.push(m[0]); i += m[0].length; }
+      ws();
+      if (src[i] !== '.') return parts;
+      i++;
+    }
+  }
+
+  // the table a path names, created on the way; an array of tables is entered at its last element
+  const tableAt = (obj, path) => {
+    for (const k of path) {
+      if (!(k in obj)) obj[k] = table();
+      const v = Array.isArray(obj[k]) ? obj[k][obj[k].length - 1] : obj[k];
+      if (!isTable(v)) err(`\`${k}\` is not a table`);
+      obj = v;
+    }
+    return obj;
+  };
+  const assign = (obj, path, v) => {
+    const t = tableAt(obj, path.slice(0, -1)), k = path[path.length - 1];
+    if (k in t) err(`duplicate key \`${k}\``);
+    t[k] = v;
+  };
+
+  function value() {
+    const c = src[i];
+    if (c === '"' || c === "'") return str();
+    if (c === '[') {
+      i++; const out = [];
+      for (;;) {
+        gap();
+        if (src[i] === ']') { i++; return out; }
+        out.push(value()); gap();
+        if (src[i] === ',') i++; else if (src[i] === ']') { i++; return out; } else err('expected `,` or `]`');
+      }
+    }
+    if (c === '{') {
+      i++; const out = table();
+      for (;;) {
+        gap();
+        if (src[i] === '}') { i++; return out; }
+        const k = key();
+        if (src[i] !== '=') err('expected `=`');
+        i++; ws(); assign(out, k, value()); gap();
+        if (src[i] === ',') i++; else if (src[i] === '}') { i++; return out; } else err('expected `,` or `}`');
+      }
+    }
+    SCALAR.lastIndex = i; const m = SCALAR.exec(src);
+    if (!m) err('expected a value');
+    i += m[0].length; return m[0];
+  }
+
+  const root = table();
+  let cur = root;
+  for (;;) {
+    gap();
+    if (i >= src.length) return root;
+    if (src[i] === '[') {
+      const many = src[i + 1] === '['; i += many ? 2 : 1;
+      const path = key();
+      if (src[i] !== ']' || (many && src[i + 1] !== ']')) err('expected `]`');
+      i += many ? 2 : 1;
+      if (!many) cur = tableAt(root, path);
+      else {
+        const parent = tableAt(root, path.slice(0, -1)), k = path[path.length - 1];
+        if (!(k in parent)) parent[k] = [];
+        if (!Array.isArray(parent[k])) err(`\`${k}\` is not an array of tables`);
+        parent[k].push(cur = table());
+      }
+    } else {
+      const path = key();
+      if (src[i] !== '=') err('expected `=`');
+      i++; ws(); assign(cur, path, value());
+    }
+    eol();
+  }
+}

package/skills/explainer-video-from-codebase/tools/lib/trace-c.mjs

@@ -0,0 +1,95 @@
+/* trace.mjs's C / C++ runner (design §3.14 C and C++ rows, §3.17): the repo's own `make` test target, built with
+   coverage and read with gcov, per test binary.
+   - accepted: `make test`, `make check` and `make -C <dir> test|check` (the make on PATH); no variables, no other
+     target, no other flag: the trace sets CC, CXX and SHELL itself;
+   - the run builds and runs the target once with `CC="cc --coverage"`, `CXX="c++ --coverage"` (a command-line
+     variable wins over the Makefile's own, and the flag reaches both compiling and linking) and SHELL set to
+     trace/c/fmtrace-sh, which runs each recipe line under the shell the Makefile's own top-level `SHELL =` names
+     (else /bin/sh), with the line's .SHELLFLAGS, and GCOV_PREFIX pointing at a dir of its own: the counters each
+     line's test binary writes land apart, and its exit status and output are kept beside them;
+   - each recipe line that wrote counters is one unit (`granularity: binary`); after the run, inside the same sandbox,
+     each counter file and the notes file the compiler wrote beside its object are copied into a fresh dir and read
+     there with `gcov -t` for the line counts of each source it covers. A test whose own lines ran in a unit belongs to
+     that unit (the first, if several), and its direct links are judged against that unit's coverage; its status
+     comes from GoogleTest's `[ RUN ]` / `[ OK ]` / `[ FAILED ]` lines or Unity's `file:line:test:PASS` lines, else from
+     its recipe line's exit status, only when every command of the line (lineHeads: one simple command, or each part of
+     an all-`&&` chain) is a native executable the build produced in the copy (ELF or Mach-O, isNativeExecutable), a
+     relative head read from the dir that line ran in (a sub-make's own, as fmtrace-sh records it): one such command
+     is passed on 0 and failed otherwise, an `&&` chain of them is passed on 0 and `unknown` otherwise.
+     Every other line is `unknown` either way: a script or a shell or interpreter at its head (`sh tests/run.sh`,
+     `./run.sh` starting with `#!`, `env`, `python`), a command that runs others (`find -exec`, `xargs`, `cd`, `time`),
+     `;`, `||`, `|`, a loop or a subshell. */
+import { posix } from 'node:path';
+
+/* -> { runner: 'make', dir, target } or null */
+export function recogniseMake(words) {
+  if (posix.basename(words[0]) !== 'make') return null;
+  let i = 1, dir = '';
+  if (words[i] === '-C' && words[i + 1] != null) { dir = words[i + 1]; i += 2; }
+  if (dir.startsWith('/') || dir.split('/').includes('..')) return null;
+  if (words.length !== i + 1 || !/^(test|check)$/.test(words[i])) return null;
+  return { runner: 'make', dir: dir.replace(/^\.\/?/, '').replace(/\/$/, ''), target: words[i] };
+}
+
+/* the shell a Makefile's own top-level `SHELL = …` names (its last such assignment), or null: one that needs make to
+   expand it (`$(shell which bash)`) is left to the default */
+export function makefileShell(text) {
+  let sh = null;
+  for (const m of text.matchAll(/^(?:(?:export|override)\s+)*SHELL\s*:{0,3}=[ \t]*(.*?)\s*(?:#.*)?$/gm)) sh = m[1];
+  return sh && !sh.includes('$') ? sh : null;
+}
+
+/* the head word of each command a recipe line runs, when the line is one simple command or simple commands joined by
+   `&&` (so its exit status is 0 only if each one's was); null for any other line (`;`, `||`, `|`, `&`, a newline, a
+   subshell or group, a command substitution). Quotes and redirections are read as a shell would; a quoted head word is
+   kept unreadable, so it names no file */
+export function lineHeads(cmd) {
+  const segs = ['']; let q = null;
+  for (let i = 0; i < cmd.length; i++) {
+    const c = cmd[i];
+    if (q === "'") { if (c === "'") q = null; segs[segs.length - 1] += '\0'; continue; }
+    if (c === '`' || (c === '$' && cmd[i + 1] === '(')) return null;
+    if (c === '\\') { i++; segs[segs.length - 1] += '\0'; continue; }
+    if (q === '"') { if (c === '"') q = null; segs[segs.length - 1] += '\0'; continue; }
+    if (c === "'" || c === '"') { q = c; segs[segs.length - 1] += '\0'; continue; }
+    if (c === '&' && cmd[i + 1] === '&') { segs.push(''); i++; continue; }
+    if (c === '>' || c === '<') { if (cmd[i + 1] === '&' || cmd[i + 1] === c) i++; segs[segs.length - 1] += ' '; continue; }
+    if (';|&(){}\n'.includes(c)) return null;
+    segs[segs.length - 1] += c;
+  }
+  if (q) return null;
+  const heads = segs.map(x => x.trim().split(/\s+/).find(w => !/^\w+=/.test(w)));
+  return heads.every(Boolean) ? heads : null;
+}
+
+// a native executable's first bytes: ELF, Mach-O (32 and 64 bit, either byte order) and a universal Mach-O
+const NATIVE_MAGIC = ['7f454c46', 'feedface', 'cefaedfe', 'feedfacf', 'cffaedfe', 'cafebabe'];
+export const isNativeExecutable = buf => !!buf && buf.length >= 4 && NATIVE_MAGIC.includes(buf.subarray(0, 4).toString('hex'));
+
+export const makeArgv = ({ make, dir, target, shell }) => [make, ...(dir ? ['-C', dir] : []), target, 'CC=cc --coverage', 'CXX=c++ --coverage', `SHELL=${shell}`];
+
+/* gcov -t text (one or more files) -> Map(source as compiled -> Map(line -> count)) */
+export function parseGcov(text) {
+  const out = new Map(); let cur = null;
+  for (const line of text.split('\n')) {
+    const m = /^\s*([^:]+):\s*(\d+):(.*)$/.exec(line);
+    if (!m) continue;
+    if (m[2] === '0') { const src = /^Source:(.*)$/.exec(m[3]); if (src) { cur = out.get(src[1]) || out.set(src[1], new Map()).get(src[1]); } continue; }
+    const c = m[1].trim();
+    if (!cur || c === '-') continue;
+    const n = /^[#=]+$/.test(c) ? 0 : parseInt(c.replace(/\*$/, ''), 10);
+    if (Number.isFinite(n)) cur.set(+m[2], Math.max(n, cur.get(+m[2]) || 0));
+  }
+  return out;
+}
+
+/* test outcomes a make run printed: GoogleTest and Unity lines -> Map(name -> status) */
+export function parseCTestOutput(text) {
+  const out = new Map();
+  for (const m of text.matchAll(/^\[\s+(OK|FAILED|SKIPPED)\s+\]\s+([\w/]+\.[\w/]+)(?: \(\d+ ms\))?\s*$/gm))
+    out.set(m[2], m[1] === 'OK' ? 'passed' : m[1] === 'FAILED' ? 'failed' : 'skipped');
+  for (const m of text.matchAll(/^[^\s:]+:\d+:(\w+):(PASS|FAIL|IGNORE)\b/gm)) out.set(m[1], m[2] === 'PASS' ? 'passed' : m[2] === 'FAIL' ? 'failed' : 'skipped');
+  return out;
+}
+
+export const C_NETWORK = /\b(connect|getaddrinfo|socket)\b[^\n]*\b(Operation not permitted|Permission denied|Connection refused|No route to host|failure)\b|\bconnect\(\)[^\n]*/g;