explainer-video 0.0.0-stage → 0.4.0

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

@@ -0,0 +1,102 @@
+/* Validated flows → videos (design §4.5): the cost model and the splitting rules, shared by flow-plan.mjs and by
+   apply-flows' estimate in the approval table. WPM and EXPANSION are measured on coursework (imported from its
+   model.mjs). FRAME, HOP_BASE, WPL, BRANCH and TEST are calibrated on one narrated pilot code video (CALIBRATION:
+   8 hops with 96 narrated lines spoken in 609 words, 2 taught branches in 135, 3 cited tests in 134, the frame in
+   154; 1032 words in all, 381.6 s of speech). BOUNDARY and OVERVIEW are still estimates: the pilot crossed no
+   boundary and made no overview.
+
+     words(video) = FRAME + Σ_hops (HOP_BASE + WPL × narrated(h)) + Σ_crossings BOUNDARY + Σ_taught branches BRANCH
+                  + min(MAX_TESTS, cited tests) × TEST
+     narrated(h)  = h.lines ? count(h.lines) : min(LINE_CAP, ceil(NARRATE × span lines))
+     minutes      = words / WPM × EXPANSION
+
+   Splitting: a hop with `break` starts a new video; hops pack greedily under the cap; on overflow the video splits at
+   its latest crossing, else at the overflowing hop (a hop is never split); flows and cores are never glued together;
+   a piece under the minimum merges with a neighbour of the same item when the two fit. One overview video opens
+   the series. */
+import { WPM, EXPANSION } from '../../../explainer-video-from-coursework/tools/model.mjs';
+
+// what the calibration was measured on, in counts (one pilot video, 18 segments, 0 pause prompts)
+export const CALIBRATION = { videos: 1, segments: 18, hops: 8, narratedLines: 96, hopWords: 609, branches: 2, branchWords: 135,
+  citedTests: 3, testWords: 134, frameWords: 154, crossings: 0, pausePrompts: 0, words: 1032, speechSeconds: 381.6 };
+
+export const MODEL = { wpm: WPM, expansion: EXPANSION, frame: 150, hopBase: 5, wpl: 6, lineCap: 22, narrate: 0.5, boundary: 60, branch: 70,
+  prompt: 12, test: 45, maxTests: 3, overview: 1000, calibrated: true, uncalibrated: ['boundary', 'overview'], basis: CALIBRATION };
+
+export const narratedLines = h => h.lines ? h.lines.reduce((a, [x, y]) => a + y - x + 1, 0) : Math.min(MODEL.lineCap, Math.ceil(MODEL.narrate * (h.end - h.start + 1)));
+const hopWords = h => MODEL.hopBase + MODEL.wpl * narratedLines(h);
+const seconds = words => Math.round((words / MODEL.wpm) * 60 * MODEL.expansion);
+export const section = h => `${h.file} :: ${h.name} @L${h.start}`;
+
+// the words of one video holding `hops` of an item whose taught branches sit on the hops listed in `teach`
+function cost(hops, teach) {
+  const at = new Set(hops.map(h => h.index));
+  const branches = teach.filter(t => at.has(t.hop)).length, cited = hops.reduce((a, h) => a + h.pinnedBy.length, 0);
+  const crossings = hops.filter(h => h.crossing).length;
+  const words = MODEL.frame + hops.reduce((a, h) => a + hopWords(h), 0) + crossings * MODEL.boundary + branches * MODEL.branch + Math.min(MODEL.maxTests, cited) * MODEL.test;
+  return { words, seconds: seconds(words), crossings, branches, cited: Math.min(MODEL.maxTests, cited) };
+}
+
+// one item's hops → pieces under the cap
+function split(item, capSec, minSec) {
+  const groups = [];
+  for (const h of item.hops) { if (!groups.length || (h.break && h.index !== item.hops[0].index)) groups.push([]); groups.at(-1).push(h); }
+  const pieces = [];
+  groups.forEach((g, gi) => {
+    let cur = [];
+    for (const h of g) {
+      if (cur.length && cost([...cur, h], item.teach).seconds > capSec) {
+        const k = cur.findLastIndex((x, i) => i > 0 && x.crossing);
+        if (k > 0) { pieces.push({ hops: cur.slice(0, k), group: gi }); cur = cur.slice(k); }
+        if (cur.length && cost([...cur, h], item.teach).seconds > capSec) { pieces.push({ hops: cur, group: gi }); cur = []; }
+      }
+      cur.push(h);
+    }
+    pieces.push({ hops: cur, group: gi });
+  });
+  for (let i = 0; i < pieces.length; i++) {
+    if (pieces.length < 2 || cost(pieces[i].hops, item.teach).seconds >= minSec) continue;
+    const fits = j => pieces[j] && pieces[j].group === pieces[i].group && cost([...pieces[Math.min(i, j)].hops, ...pieces[Math.max(i, j)].hops], item.teach).seconds <= capSec;
+    const j = fits(i - 1) ? i - 1 : fits(i + 1) ? i + 1 : null;
+    if (j == null) continue;
+    const [a, b] = [Math.min(i, j), Math.max(i, j)];
+    pieces.splice(a, 2, { hops: [...pieces[a].hops, ...pieces[b].hops], group: pieces[a].group });
+    i = a - 1;
+  }
+  return pieces;
+}
+
+export function planVideos(v, { maxMin = 25, minMin = 2.5 } = {}) {
+  const capSec = maxMin * 60, minSec = minMin * 60;
+  const items = new Map([...v.flows, ...v.cores].map(x => [x.id, x]));
+  const videos = [], coverage = [];
+  const overviewSec = seconds(MODEL.overview);
+  videos.push({ index: 1, title: 'Series overview', form: 'overview', group: 'overview', flowGroup: null, words: MODEL.overview, seconds: overviewSec, minutes: +(overviewSec / 60).toFixed(1),
+    formWhy: 'one system map per series: the processes, the stores, and every flow and core as a route through them', sources: [], artefacts: [],
+    evidence: { items: v.series.length },
+    sections: v.series.map(s => `${s.id} :: ${s.title}`),
+    sectionSpans: v.series.map(s => ({ id: `${s.id} :: ${s.title}`, src: 'flows.validated.json', title: s.title, item: s.id, kind: s.kind, why: s.why })) });
+  for (const s of v.series) {
+    const item = items.get(s.id), pieces = split(item, capSec, minSec);
+    pieces.forEach((p, i) => {
+      const c = cost(p.hops, item.teach), index = videos.length + 1;
+      for (const h of p.hops) coverage.push({ item: item.id, hop: h.index, symbol: h.symbol, section: section(h), video: index });
+      const at = new Set(p.hops.map(h => h.index));
+      videos.push({ index, title: pieces.length > 1 ? `${item.title} (part ${i + 1} of ${pieces.length})` : item.title, form: item.kind, group: item.id, flowGroup: item.group,
+        words: c.words, seconds: c.seconds, minutes: +(c.seconds / 60).toFixed(1), formWhy: s.why,
+        sources: [...new Set(p.hops.map(h => h.file))], artefacts: [...new Set(p.hops.flatMap(h => h.pinnedBy.map(t => t.file)))],
+        evidence: { hops: p.hops.length, crossings: c.crossings, branches: c.branches, citedTests: c.cited, part: `${i + 1}/${pieces.length}`, rank: item.rank || null },
+        teach: item.teach.filter(t => at.has(t.hop)),
+        sections: p.hops.map(section),
+        sectionSpans: p.hops.map(h => ({ id: section(h), src: h.file, title: h.name, line: h.start, endLine: h.end, symbol: h.symbol, sha256: h.sha256, item: item.id, hop: h.index,
+          lines: h.lines, narratedLines: narratedLines(h), crossing: h.crossing, uses: h.uses, exercises: h.exercises, pinnedBy: h.pinnedBy })) });
+    });
+  }
+  const assigned = new Set(coverage.map(c => `${c.item}#${c.hop}`));
+  const orphans = [...items.values()].flatMap(x => x.hops.filter(h => !assigned.has(`${x.id}#${h.index}`)).map(h => ({ item: x.id, hop: h.index, symbol: h.symbol })));
+  const capViolations = videos.filter(x => x.seconds > capSec).map(x => ({ index: x.index, minutes: x.minutes }));
+  const total = videos.reduce((a, x) => a + x.seconds, 0);
+  return { videos, coverage, orphans, capViolations,
+    totals: { videos: videos.length, seriesMinutes: +(total / 60).toFixed(1), longestVideoMin: Math.max(...videos.map(x => x.minutes)), capMinutes: maxMin,
+      hops: coverage.length, flows: v.flows.length, cores: v.cores.length } };
+}

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

@@ -0,0 +1,77 @@
+/* Every file lands in exactly one group: prod, test, eval or dev. Ordered rules, first match
+   wins; a user override (`--group 'glob=group'`) always wins over them. Path rules decide;
+   content signals only reclassify a file that fell through to prod (design rev3 §3.15). */
+
+export const GROUPS = ['prod', 'test', 'eval', 'dev'];
+
+export const PATH_RULES = [
+  { group: 'test', rule: 'test: a tests/, test/ or __tests__/ dir; test_*.py, *_test.py, conftest.py; *.test|spec.[cm][jt]s(x), setupTests / jest.setup / vitest.setup; *_test.go; test_*.c(c|pp), *_test.c(c|pp), *_unittest.cc',
+    re: /(^|\/)(tests?|__tests__)\/|(^|\/)(test_[^/]*|[^/]*_test|conftest)\.py$|\.(test|spec)\.[cm]?[jt]sx?$|(^|\/)(setupTests|setup-tests|jest\.setup|vitest\.setup|test-setup)\.[cm]?[jt]sx?$|_test\.go$|(^|\/)test_[^/]*\.(c|cc|cpp|cxx)$|[^/]_(test|unittest)\.(c|cc|cpp|cxx)$/ },
+  { group: 'dev', rule: 'dev (file name): debug_*.py, diagnose_*.py, *migration_controller*.py, dev.py; debug*.[jt]s, *.dev.[jt]s, build and test tool configs (jest/vitest/vite/webpack/… .config.[jt]s)',
+    re: /(^|\/)(debug|diagnose)_[^/]*\.py$|(^|\/)[^/]*migration_controller[^/]*\.py$|(^|\/)dev\.py$|(^|\/)debug[^/]*\.[cm]?[jt]sx?$|\.dev\.[cm]?[jt]sx?$|(^|\/)(jest|vitest|vite|webpack|rollup|babel|eslint|prettier|tailwind|postcss|playwright|cypress)\.config\.[cm]?[jt]s$/ },
+  { group: 'eval', rule: 'eval: an evals/, eval/, *_evals/, evals_*/, evaluation(s)/, benchmark(s)/ or bench/ dir',
+    re: /(^|\/)(evals?|[\w-]+_evals?|evals?_[\w-]+|evaluations?|benchmarks?|bench)\// },
+  { group: 'dev', rule: 'dev (dir): migrations/, alembic/, dev_setup/, dev/, scripts/, verification/, debug/',
+    re: /(^|\/)(migrations|alembic|dev_setup|dev|scripts|verification|debug)\// },
+];
+export const DEFAULT_RULE = 'prod: everything else';
+
+const TEST_IMPORT = /^\s*(import|from)\s+(pytest|unittest)\b/m;
+const TEST_DEF = /^\s*(async\s+)?def\s+test_\w*\s*\(|^\s*class\s+Test\w*\s*[(:]/m;
+const EVAL_IMPORT = /^\s*(import|from)\s+(ragas|deepeval|promptfoo|lm_eval|inspect_ai|mteb|beir|trulens\w*)\b|^\s*from\s+langsmith(\.\w+)*\s+import\s+[^\n]*\bevaluate\b/m;
+const TRAINING = /\bTrainer\(|\.backward\(\)|^\s*(import|from)\s+accelerate\b/m;
+const JS_TEST_IMPORT = /\bfrom\s+["'](vitest|@jest\/globals|node:test|mocha)["']|\brequire\(\s*["'](node:test|mocha|@jest\/globals)["']\s*\)/;
+const JS_TEST_DEF = /^\s*(describe|it|test)(\.\w+)*\s*\(/m;
+// design rev3 §3.15 (eval row, content signals): an eval-framework import puts a file in eval, in every language
+const JS_EVAL_IMPORT = /\bfrom\s+["'](promptfoo|evalite|autoevals|braintrust|langsmith\/evaluation)["']|\brequire\(\s*["'](promptfoo|autoevals|braintrust)["']\s*\)/;
+// a Go file only `go test` compiles is already a _test.go file; a generated or hand-written mock is a test double
+const GO_MOCK = /^\/\/ Code generated by MockGen\b|^\s*mock\.Mock\s*$/m;
+
+// a C / C++ file that includes a test framework and defines its tests
+const C_TEST_INCLUDE = /^\s*#\s*include\s*[<"](gtest\/gtest\.h|gmock\/gmock\.h|catch2\/[\w/]+\.hpp|catch\.hpp|unity\.h|cmocka\.h|check\.h|CUnit\/\w+\.h)[>"]/m;
+const C_TEST_DEF = /^\s*(TEST|TEST_F|TEST_P|TYPED_TEST|TEST_CASE|SCENARIO|TEST_CASE_METHOD)\s*\(|^\s*(RUN_TEST|cmocka_unit_test)\s*\(|\bMOCK_METHOD\d*\s*\(/m;
+
+export function contentRule(text, lang = 'python') {
+  if (lang === 'go') return GO_MOCK.test(text) ? { group: 'test', rule: 'content: a MockGen-generated or testify mock.Mock test double' } : null;
+  if (lang === 'c' || lang === 'cpp') return C_TEST_INCLUDE.test(text) && C_TEST_DEF.test(text) ? { group: 'test', rule: 'content: includes gtest/gmock/Catch2/Unity/cmocka/check and defines tests or mocks' } : null;
+  if (lang !== 'python') {
+    if (JS_TEST_IMPORT.test(text) && JS_TEST_DEF.test(text)) return { group: 'test', rule: 'content: imports vitest/jest/node:test/mocha and defines tests' };
+    if (JS_EVAL_IMPORT.test(text)) return { group: 'eval', rule: 'content: imports an eval framework' };
+    return null;
+  }
+  if (TEST_IMPORT.test(text) && TEST_DEF.test(text)) return { group: 'test', rule: 'content: imports pytest/unittest and defines tests' };
+  if (EVAL_IMPORT.test(text)) return { group: 'eval', rule: 'content: imports an eval framework' };
+  if (TRAINING.test(text)) return { group: 'eval', rule: 'content: training-loop markers' };
+  return null;
+}
+
+// `**` crosses directories, `*` and `?` do not; a pattern with no slash matches anywhere
+export function globToRegExp(glob) {
+  let re = '';
+  for (let i = 0; i < glob.length; i++) {
+    const c = glob[i];
+    if (c === '*' && glob[i + 1] === '*') { re += glob[i + 2] === '/' ? '(?:.*/)?' : '.*'; i += glob[i + 2] === '/' ? 2 : 1; }
+    else if (c === '*') re += '[^/]*';
+    else if (c === '?') re += '[^/]';
+    else re += c.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+  }
+  return new RegExp((glob.includes('/') ? '^' : '(^|/)') + re + '$');
+}
+
+export function parseOverrides(specs) {
+  return specs.map(spec => {
+    const i = spec.lastIndexOf('=');
+    const glob = spec.slice(0, i), group = spec.slice(i + 1);
+    if (i < 1 || !GROUPS.includes(group)) throw new Error(`--group '${spec}': expected 'glob=${GROUPS.join('|')}'`);
+    return { glob, group, re: globToRegExp(glob) };
+  });
+}
+
+export function classifyFile(rel, overrides, readText, lang = 'python') {
+  const o = overrides.find(x => x.re.test(rel));
+  if (o) return { group: o.group, rule: `override: ${o.glob}=${o.group}` };
+  const r = PATH_RULES.find(x => x.re.test(rel));
+  if (r) return { group: r.group, rule: r.rule };
+  const c = readText && contentRule(readText(), lang);
+  return c || { group: 'prod', rule: DEFAULT_RULE };
+}

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

@@ -0,0 +1,68 @@
+/* Map a coverage-based test run (Go's -coverprofile, gcov) onto a code map (design §3.14, §3.17). Coverage says which
+   lines ran, not who called them, so no edge is marked observed: a symbol ran when a counted line or block inside it
+   ran (the innermost symbol holding it), and a direct test link counts as observed when its target ran in the unit
+   its test ran in — the test itself (Go, one run per test) or its test binary (make, `binary`). Nothing is removed or
+   demoted: the result is an overlay beside the code map, which is not edited. */
+const byStr = (a, b) => a < b ? -1 : a > b ? 1 : 0;
+
+/* counts: Map(repo-relative file -> [{ start, end, count }]) -> Set(symbol id) */
+export function symbolsRan(m, counts) {
+  const inFile = new Map();
+  for (const s of m.symbols) if (s.kind !== 'class') (inFile.get(s.file) || inFile.set(s.file, []).get(s.file)).push(s);
+  const ran = new Set();
+  for (const [file, blocks] of counts) {
+    const syms = inFile.get(file); if (!syms) continue;
+    for (const b of blocks) {
+      if (!b.count) continue;
+      let best = null;
+      for (const s of syms) if (s.start <= b.start && b.start <= s.end && (!best || s.start > best.start || (s.start === best.start && s.end < best.end))) best = s;
+      if (best) ran.add(best.id);
+    }
+  }
+  return ran;
+}
+// gcov line counts per source -> the blocks symbolsRan reads
+export const linesToBlocks = lines => [...lines].map(([line, count]) => ({ start: line, end: line, count }));
+
+/* units: [{ key, tests: [test ids], ran: Set }], results: Map(test id -> { status, message, nodeid }), granularity:
+   'test' | 'binary', ownFile: which code-map files this runner measures */
+export function observeCoverage(m, { units, results, failures, denied, granularity, ownFile, notCollected = [], runtime = {} }) {
+  const sym = new Map(m.symbols.map(s => [s.id, s]));
+  const grp = id => sym.get(id)?.group || '?';
+  const unitOf = new Map(); for (const u of units) for (const t of u.tests) unitOf.set(t, u);
+  const outcome = { collected: 0, passed: 0, failed: 0, errors: 0, skipped: 0, xfailed: 0, xpassed: 0, unknown: 0, notRun: 0 };
+  for (const r of results.values()) { outcome.collected++; if (r.status === 'not run') outcome.notRun++; else if (outcome[r.status] != null) outcome[r.status]++; }
+  outcome.errors += failures.filter(f => f.status === 'error').length;
+  const byTest = {};
+  let dObs = 0, dAll = 0, pObs = 0, pAll = 0, linked = 0;
+  for (const t of (m.tests || []).filter(x => ownFile(x.file))) {
+    const r = results.get(t.id), u = unitOf.get(t.id);
+    if (!r) continue;
+    const direct = [...new Set(t.direct.map(d => d.to).filter(to => sym.has(to) && grp(to) !== 'test' && sym.get(to).kind !== 'class'))];
+    const ran = r.status === 'not run' ? null : u?.ran;
+    const missing = ran ? direct.filter(to => !ran.has(to)).sort(byStr) : direct;
+    if (ran && direct.length) { linked++; 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[t.id] = { file: t.file, nodeids: r.nodeid ? [r.nodeid] : [], status: r.status, unit: u?.key ?? null, direct: { total: direct.length, observed: direct.length - missing.length, missing } };
+  }
+  let fixO = 0, fixN = 0;
+  for (const b of m.fixtureBindings || []) { const r = results.get(b.fn), u = unitOf.get(b.fn); if (!r || r.status === 'not run' || !u) continue; fixN++; if (u.ran.has(b.fixture)) fixO++; }
+  const ranAnywhere = new Set(units.flatMap(u => [...u.ran]));
+  const fns = m.symbols.filter(s => (s.kind === 'function' || s.kind === 'method') && ownFile(s.file));
+  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 ran = {};
+  for (const u of [...units].sort((a, b) => byStr(a.key, b.key))) for (const id of u.ran) (ran[id] ||= []).push(u.key);
+  return {
+    runtime, granularity, outcome, notCollected, failures, deniedBySandbox: denied,
+    summary: {
+      functionsRan,
+      pairs: 'not recorded: coverage says which code ran under a test, not which function called which',
+      directLinksPerTest: { tests: linked, observed: dObs, total: dAll, prod: { observed: pObs, total: pAll }, granularity },
+      fixtureLinks: { observed: fixO, total: fixN },
+    },
+    ran: Object.fromEntries(Object.entries(ran).sort(([a], [b]) => byStr(a, b))),
+    byUnit: Object.fromEntries([...units].sort((a, b) => byStr(a.key, b.key)).map(u => [u.key, { tests: [...u.tests].sort(byStr), ran: [...u.ran].sort(byStr) }])),
+    byTest, pairs: [], edges: [], noStaticEdge: [], callbacks: [],
+  };
+}

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

@@ -0,0 +1,232 @@
+/* Map a JavaScript / TypeScript test run onto a code map (design §3.14 TS/JS row, §3.17). Each test file ran in its
+   own runner process under V8 precise coverage (NODE_V8_COVERAGE), so a function that ran there ran under that test
+   file: attribution is per test file, never per test. Coverage records which functions ran, not who called them, so no
+   edge is marked observed; a direct test link counts as observed when its target ran in its test's file. It never
+   removes or demotes an edge: the result is an overlay beside the code map, which is not edited.
+
+   A covered function is matched to a code-map symbol through the script's source map when there is one (Node's own,
+   or the inline map of a script jest or vitest compiled through node:vm, which trace/js/fmtrace-srcmap.cjs records);
+   else by its position when the script V8 ran is the file itself (plain JavaScript), or the file with something
+   appended (TypeScript with its types stripped in place, plus a sourceURL comment) and every named function sits on a
+   line of the file that names it; and otherwise by name when exactly one symbol of that file has it. A named function
+   that matches nothing is counted, never guessed; an anonymous one (a callback inside a symbol) has nothing of its own
+   to mark.
+   A file whose run ended cleanly but reported no test is listed as not collected (the runner's own config leaves it
+   out, or it defines none), with the code map's count of tests in it, never as an error; those tests never ran, so they
+   are left out of byTest and the direct-link share. */
+import { fileURLToPath } from 'node:url';
+
+const byStr = (a, b) => a < b ? -1 : a > b ? 1 : 0;
+const STATUS_RANK = { error: 4, failed: 3, passed: 1, skipped: 0 };
+
+/* ---------------- source maps (v3, `mappings` only) ---------------- */
+const B64 = Object.fromEntries([...'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/'].map((c, i) => [c, i]));
+export function decodeMappings(mappings) {
+  const lines = []; let src = 0, sLine = 0, sCol = 0;
+  for (const line of mappings.split(';')) {
+    const segs = []; let gCol = 0;
+    for (const seg of line.split(',')) {
+      if (!seg) continue;
+      const v = []; let shift = 0, val = 0;
+      for (const ch of seg) { const d = B64[ch]; if (d == null) break; val += (d & 31) << shift; if (d & 32) shift += 5; else { v.push(val & 1 ? -(val >>> 1) : val >>> 1); val = 0; shift = 0; } }
+      gCol += v[0];
+      if (v.length >= 4) { src += v[1]; sLine += v[2]; sCol += v[3]; segs.push([gCol, src, sLine, sCol]); }
+    }
+    lines.push(segs);
+  }
+  return lines;
+}
+// the generated line (0-based) an offset falls on, and that line's start offset
+function generatedLine(entry, offset) {
+  let line = 0, start = 0;
+  while (line < entry.lineLengths.length && start + entry.lineLengths[line] < offset) { start += entry.lineLengths[line] + 1; line++; }
+  return [line, start];
+}
+// a function that closes after every line the map covers is the runner's module wrapper (jest's `Object.<anonymous>`,
+// opened on the file's first line, closed after the inline map), no function of the file
+function wrapsMappedCode(entry, endOffset) {
+  if (!entry?.lineLengths || !entry.data?.mappings) return false;
+  const decoded = entry.decoded ||= decodeMappings(entry.data.mappings);
+  return generatedLine(entry, endOffset)[0] > decoded.findLastIndex(segs => segs.length);
+}
+// the original line (1-based) a generated offset maps to, through a source-map-cache entry
+function sourceMapLine(entry, offset) {
+  if (!entry?.lineLengths || !entry.data?.mappings) return null;
+  const [line, start] = generatedLine(entry, offset);
+  const segs = (entry.decoded ||= decodeMappings(entry.data.mappings))[line] || [];
+  const col = offset - start;
+  let best = null; for (const s of segs) { if (s[0] <= col) best = s; else break; }
+  best ||= segs[0];
+  return best ? best[2] + 1 : null;
+}
+
+const lineStarts = text => { const out = [0]; for (let i = 0; i < text.length; i++) if (text[i] === '\n') out.push(i + 1); return out; };
+const lineOf = (starts, off) => { let lo = 0, hi = starts.length - 1; while (lo < hi) { const mid = (lo + hi + 1) >> 1; if (starts[mid] <= off) lo = mid; else hi = mid - 1; } return lo + 1; };
+const nameMatches = (s, fn) => { const n = fn.replace(/^(get|set|async) /, ''); return n && (s.name === n || s.name.split('.').pop() === n || (s.kind === 'class' && s.name === n)); };
+
+// which code-map symbols ran in one process's coverage dump; `root` is the copy the run used
+export function functionsRan(m, dump, root, readFile) {
+  const ran = new Set(); let unmapped = 0, scripts = 0, anonymous = 0;
+  const syms = new Map();
+  for (const s of m.symbols) if (s.kind !== 'main' && /\.[cm]?[jt]sx?$/.test(s.file)) (syms.get(s.file) || syms.set(s.file, []).get(s.file)).push(s);
+  const ctorOf = new Map(m.symbols.filter(s => s.name === 'constructor' && s.cls).map(s => [s.cls, s.id]));
+  const smc = dump['source-map-cache'] || {};
+  for (const script of dump.result || []) {
+    let path; try { path = script.url.startsWith('file://') ? fileURLToPath(script.url) : script.url; } catch { continue; }
+    if (!path.startsWith(root + '/')) continue;
+    const rel = path.slice(root.length + 1), here = syms.get(rel);
+    if (!here) continue;
+    scripts++;
+    const text = readFile(rel);
+    const len = Math.max(0, ...script.functions.filter(f => f.ranges[0]?.startOffset === 0).map(f => f.ranges[0].endOffset));
+    const starts = text != null ? lineStarts(text) : null;
+    const fns = script.functions.filter(f => f.ranges[0] && !(f.ranges[0].startOffset === 0 && !f.functionName));
+    const lineText = off => text.slice(starts[lineOf(starts, off) - 1], starts[lineOf(starts, off)] ?? text.length);
+    const identical = text != null && (len === text.length || (len > text.length && fns.every(f => f.ranges[0].endOffset <= text.length)
+      && fns.filter(f => f.functionName).every(f => lineText(f.ranges[0].startOffset).includes(f.functionName.replace(/^(get|set|async) /, '')) || /constructor/.test(lineText(f.ranges[0].startOffset)))));
+    const sm = smc[script.url] || smc[path];
+    for (const f of fns) {
+      const r0 = f.ranges[0];
+      if (!r0.count || (sm && wrapsMappedCode(sm, r0.endOffset))) continue;
+      const line = sm ? sourceMapLine(sm, r0.startOffset) : identical ? lineOf(starts, r0.startOffset) : null;
+      let cand = line != null ? here.filter(s => s.start === line) : [];
+      if (cand.length > 1) cand = cand.filter(s => nameMatches(s, f.functionName));
+      if (!cand.length && f.functionName && !identical) { const named = here.filter(s => nameMatches(s, f.functionName)); if (named.length === 1) cand = named; }
+      // a class's constructor runs under the class's name; a class with none has nothing of its own to mark
+      cand = cand.map(s => s.kind === 'class' ? ctorOf.get(s.id) : s.id).filter(Boolean);
+      if (cand.length === 1) ran.add(cand[0]); else if (f.functionName) unmapped++; else anonymous++;
+    }
+  }
+  return { ran, unmapped, scripts, anonymous };
+}
+
+/* ---------------- outcomes ---------------- */
+const safeTitle = s => s.replace(/:/g, '-').replace(/\s+/g, ' ').trim();
+// a test-id pattern from a code-map test title: `%s`, `%i`, `$x`, `${x}` stand for what `.each` and templates fill in
+const titleRe = q => new RegExp('^' + q.replace(/[.*+?^${}()|[\]\\]/g, '\\$&').replace(/%[sdifjop#]|\\\$\\\{[^}]*\\\}|\\\$\w+/g, '.+?') + '$');
+
+// jest's --json and vitest's json reporter (the same shape): per test file, per assertion
+export function parseJestJson(json, root) {
+  const tests = [], suiteErrors = [];
+  for (const tr of json?.testResults || []) {
+    const file = tr.name?.startsWith(root + '/') ? tr.name.slice(root.length + 1) : tr.name;
+    const ars = tr.assertionResults || [];
+    for (const a of ars) tests.push({ file, titles: [...(a.ancestorTitles || []), a.title], status: a.status === 'passed' ? 'passed' : a.status === 'failed' ? 'failed' : 'skipped',
+      message: (a.failureMessages || []).join('\n') });
+    if ((tr.status === 'failed' && !ars.some(a => a.status === 'failed')) || (tr.message && !ars.length)) suiteErrors.push({ file, message: tr.message || tr.failureMessage || '' });
+  }
+  return { tests, suiteErrors };
+}
+
+// node --test's TAP: `# Subtest: T` opens a test at an indent, `ok N - T` / `not ok N - T` at that indent closes it, and
+// the YAML block under it says whether it was a suite and carries the error. A suite fails on its own only by a hook
+export function parseTap(text) {
+  const tests = [], suiteErrors = [], stack = [];
+  const lines = text.split('\n');
+  const unescape = t => t.replace(/\\(.)/g, '$1');
+  for (let i = 0; i < lines.length; i++) {
+    const l = lines[i], ind = l.match(/^ */)[0].length;
+    const sub = /^ *# Subtest: (.*)$/.exec(l);
+    if (sub) { stack.push({ ind, title: unescape(sub[1]) }); continue; }
+    const pt = /^ *(not )?ok \d+ - (.*?)(?: # (SKIP|TODO)\b.*)?$/.exec(l);
+    if (!pt) continue;
+    while (stack.length && stack.at(-1).ind > ind) stack.pop();
+    if (stack.at(-1)?.ind === ind) stack.pop();
+    const titles = [...stack.map(x => x.title), unescape(pt[2])];
+    const yaml = [];
+    if (lines[i + 1]?.trim() === '---') for (let j = i + 2; j < lines.length && lines[j].trim() !== '...'; j++) yaml.push(lines[j]);
+    const y = yaml.join('\n'), type = /^\s*type: '(\w+)'/m.exec(y)?.[1], failureType = /^\s*failureType: '(\w+)'/m.exec(y)?.[1];
+    const block = /^( *)error: \|-\n([\s\S]*?)(?=\n\1\w+:|(?![\s\S]))/m.exec(y);
+    const line = /^\s*error: (?:'(.*)'|"(.*)")$/m.exec(y), code = /^\s*code: '?(EPERM|EACCES|EROFS|ECONN\w+|ENOTFOUND|EAI_AGAIN|ENETUNREACH|EHOSTUNREACH)'?$/m.exec(y)?.[1];
+    const message = [...(block ? block[2] : line?.[1] ?? line?.[2] ?? '').split('\n'), ...(code && !(block?.[2] || line?.[0] || '').includes(code) ? [`code: ${code}`] : [])]
+      .map(x => x.trim()).filter(Boolean).join('\n');
+    if (type === 'suite') { if (pt[1] && failureType !== 'subtestsFailed') suiteErrors.push({ titles, message }); continue; }
+    tests.push({ titles, status: pt[3] ? 'skipped' : pt[1] ? 'failed' : 'passed', message });
+  }
+  return { tests, suiteErrors };
+}
+
+const NETWORK = /\b(ECONNREFUSED|ENOTFOUND|EAI_AGAIN|ENETUNREACH|EHOSTUNREACH)\b|connect E\w+|getaddrinfo E\w+|fetch failed/;
+const PERMISSION = /\b(EPERM|EACCES|EROFS)\b/;
+// the attempts a run recorded, else the target its error names (a process or worker the preload did not hook)
+const attempts = (run, message) => run.network.length ? run.network
+  : [...new Set([...message.matchAll(/\bconnect E\w+ (\S+?)(?=[\s,)]|$)|\bgetaddrinfo E\w+ (\S+?)(?=[\s,)]|$)/g)].map(x => x[1] ? `connect ${x[1]}` : `getaddrinfo ${x[2]}`))];
+
+/* runs: [{ file, outcomes: { tests, suiteErrors }, coverage: [dump], network: [attempt], timedOut, exitCode }] */
+export function observeV8(m, runs, { root, readFile, node }) {
+  const sym = new Map(m.symbols.map(s => [s.id, s]));
+  const grp = id => sym.get(id)?.group || '?';
+  const tests = (m.tests || []).filter(t => /\.[cm]?[jt]sx?$/.test(t.file));
+  const testsIn = new Map(); for (const t of tests) (testsIn.get(t.file) || testsIn.set(t.file, []).get(t.file)).push(t);
+  const ranIn = new Map(), statusBy = new Map(), nodeidsOf = new Map(), failures = [], denied = [], notCollected = [];
+  const outcome = { collected: 0, passed: 0, failed: 0, errors: 0, skipped: 0, xfailed: 0, xpassed: 0 };
+  let unmapped = 0, scripts = 0, anonymous = 0;
+  for (const run of runs) {
+    const ran = new Set();
+    for (const d of run.coverage) { const r = functionsRan(m, d, root, readFile); r.ran.forEach(x => ran.add(x)); unmapped += r.unmapped; scripts += r.scripts; anonymous += r.anonymous; }
+    ranIn.set(run.file, ran);
+    const known = testsIn.get(run.file) || [];
+    const idOf = titles => { const q = `${run.file}:${safeTitle(titles.map(safeTitle).join(' > '))}`;
+      return known.find(t => t.id === q)?.id || known.find(t => titleRe(t.id).test(q))?.id || null; };
+    const reported = run.outcomes.tests.filter(t => !t.file || t.file === run.file);
+    for (const t of reported) {
+      outcome.collected++;
+      outcome[{ passed: 'passed', failed: 'failed', skipped: 'skipped' }[t.status]]++;
+      const id = idOf(t.titles), nodeid = `${run.file}::${t.titles.join(' > ')}`, name = id || nodeid;
+      (nodeidsOf.get(name) || nodeidsOf.set(name, new Set()).get(name)).add(nodeid);
+      if (!statusBy.has(name) || STATUS_RANK[t.status] > STATUS_RANK[statusBy.get(name)]) statusBy.set(name, t.status);
+      if (t.status !== 'failed') continue;
+      failures.push({ test: id, nodeid, status: 'failed', phase: 'call', message: t.message });
+      const network = NETWORK.test(t.message) ? attempts(run, t.message) : [];
+      if (network.length || PERMISSION.test(t.message)) denied.push({ test: id, nodeid, status: 'failed', network, permission: !network.length && PERMISSION.test(t.message), message: t.message });
+    }
+    const errs = [...run.outcomes.suiteErrors];
+    if (!reported.length && !errs.length && run.exitCode === 0 && !run.timedOut) notCollected.push({ file: run.file, tests: known.length });
+    if (!reported.length && !errs.length && (run.exitCode !== 0 || run.timedOut)) errs.push({ message: run.timedOut ? 'cut off by the time limit' : `the runner exited ${run.exitCode} and reported no test` });
+    for (const e of errs) {
+      outcome.errors++;
+      const nodeid = e.titles ? `${run.file}::${e.titles.join(' > ')}` : run.file;
+      failures.push({ test: null, nodeid, status: 'error', phase: e.titles ? 'setup' : 'collect', message: e.message || '' });
+      const network = NETWORK.test(e.message || '') ? attempts(run, e.message || '') : [];
+      if (network.length || PERMISSION.test(e.message || '')) denied.push({ test: null, nodeid, status: 'error', network, permission: !network.length, message: e.message || '' });
+    }
+  }
+
+  /* ---- per test (by its file's run): direct links and hooks that ran ---- */
+  const byTest = {};
+  let dObs = 0, dAll = 0, pObs = 0, pAll = 0, linked = 0;
+  const uncollected = new Set(notCollected.map(n => n.file));
+  for (const t of tests) {
+    const ran = ranIn.get(t.file);
+    if ((!ran && !statusBy.has(t.id)) || uncollected.has(t.file)) continue;
+    const direct = [...new Set(t.direct.map(d => d.to).filter(to => sym.has(to) && grp(to) !== 'test' && sym.get(to).kind !== 'class'))];
+    const missing = ran ? direct.filter(to => !ran.has(to)).sort(byStr) : direct;
+    if (ran && direct.length) { linked++; 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[t.id] = { file: t.file, nodeids: [...(nodeidsOf.get(t.id) || [])].sort(byStr), status: statusBy.get(t.id) || null,
+      direct: { total: direct.length, observed: direct.length - missing.length, missing } };
+  }
+  for (const [name, status] of statusBy) if (!byTest[name]) byTest[name] = { file: name.split('::')[0], nodeids: [...nodeidsOf.get(name)].sort(byStr), status, direct: { total: 0, observed: 0, missing: [] } };
+  let fixO = 0, fixN = 0;
+  const testFile = new Map(tests.map(t => [t.id, t.file]));
+  for (const b of m.fixtureBindings || []) { const ran = ranIn.get(testFile.get(b.fn)); if (!ran) continue; fixN++; if (ran.has(b.fixture)) fixO++; }
+
+  const ranAnywhere = new Set([...ranIn.values()].flatMap(s => [...s]));
+  const fns = m.symbols.filter(s => (s.kind === 'function' || s.kind === 'method') && /\.[cm]?[jt]sx?$/.test(s.file));
+  const functionsRanBy = {};
+  for (const g of ['prod', 'eval', 'test', 'dev']) { const f = fns.filter(s => s.group === g); functionsRanBy[g] = { ran: f.filter(s => ranAnywhere.has(s.id)).length, total: f.length }; }
+  const ran = {};
+  for (const [file, set] of [...ranIn].sort(([a], [b]) => byStr(a, b))) for (const id of set) (ran[id] ||= []).push(file);
+  const byFile = Object.fromEntries([...ranIn].sort(([a], [b]) => byStr(a, b)).map(([file, set]) => [file, { ran: [...set].sort(byStr) }]));
+  return {
+    runtime: { node }, granularity: 'test-file', outcome, notCollected: notCollected.sort((a, b) => byStr(a.file, b.file)), failures, deniedBySandbox: denied,
+    summary: {
+      scripts, functionsRan: functionsRanBy, unmappedFunctions: unmapped, anonymousCallbacks: anonymous,
+      pairs: 'not recorded: V8 coverage says which functions ran in a test file, not which called which (an inspector-based tracer would be needed)',
+      directLinksPerTest: { tests: linked, observed: dObs, total: dAll, prod: { observed: pObs, total: pAll }, granularity: 'test-file' },
+      fixtureLinks: { observed: fixO, total: fixN },
+    },
+    ran: Object.fromEntries(Object.entries(ran).sort(([a], [b]) => byStr(a, b))), byFile, byTest,
+    pairs: [], edges: [], noStaticEdge: [], callbacks: [],
+  };
+}