explainer-video 0.0.0-stage → 0.4.0

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

@@ -0,0 +1,101 @@
+/* trace.mjs's Go runner (design §3.14 Go row, §3.17): `go test`, recognised with the flags that only choose and run
+   tests, run once per test under `-coverprofile` so what ran is attributed to that test.
+   - accepted: `go test [flags] [packages]` and `go -C <dir> test …` (the go on PATH, or a path to one); packages are
+     `.`, `./dir` or `./dir/...` inside the module; flags: -run, -skip, -short, -v, -count, -tags, -timeout, -failfast,
+     -p, -parallel, -cpu (a value given as -flag=v or -flag v);
+   - refused: any flag the trace sets itself or that runs another program or writes elsewhere (-json, -cover*,
+     -coverprofile, -exec, -toolexec, -o, -c, -cpuprofile, -memprofile, -trace, -fuzz, -race, -vet, -modfile, -overlay);
+   - the module is the one `-C` names, else the repo root's go.mod, else the code map's one Go module;
+   - each code-map TestXxx / FuzzXxx in a selected package runs alone (`-run ^TestXxx$`, intersected with a -run the
+     command gave) with `-json -count=1 -coverprofile -coverpkg=./...`: the profile marks the module's non-test code
+     that ran under that test. go test does not instrument _test.go files, so test-side code (helpers, fakes,
+     TestMain) is never observed. */
+import { posix } from 'node:path';
+
+const VALUE = new Set(['-run', '-skip', '-count', '-tags', '-timeout', '-p', '-parallel', '-cpu']);
+const BOOL = new Set(['-short', '-v', '-failfast']);
+
+/* -> { runner: 'go-test', dir, flags, packages, run } or null */
+export function recogniseGo(words) {
+  if (!/^go$/.test(posix.basename(words[0]))) return null;
+  let i = 1, dir = '';
+  if (words[i] === '-C' && words[i + 1] != null) { dir = words[i + 1]; i += 2; }
+  else if (/^-C=/.test(words[i] || '')) { dir = words[i].slice(3); i++; }
+  if (words[i] !== 'test') return null;
+  if (dir.startsWith('/') || dir.split('/').includes('..')) return null;
+  const flags = [], packages = []; let run = null;
+  for (let j = i + 1; j < words.length; j++) {
+    const w = words[j];
+    if (!w.startsWith('-')) { if (w.startsWith('/') || w.split('/').includes('..') || !/^\.(\/|$)/.test(w)) return null; packages.push(w); continue; }
+    const [f, v] = w.includes('=') ? [w.slice(0, w.indexOf('=')), w.slice(w.indexOf('=') + 1)] : [w, null];
+    const flag = f.replace(/^--/, '-');
+    if (BOOL.has(flag)) { if (v != null && !/^(true|false)$/.test(v)) return null; flags.push(w); continue; }
+    if (!VALUE.has(flag)) return null;
+    const val = v ?? words[++j];
+    if (val == null) return null;
+    if (flag === '-run') run = val; else flags.push(`${flag}=${val}`);
+  }
+  return { runner: 'go-test', dir: dir.replace(/^\.\/?/, '').replace(/\/$/, ''), flags, packages: packages.length ? packages : ['.'], run };
+}
+
+// does a package pattern (relative to the module dir) select a package dir (relative to the module dir, '' = root)?
+const selects = (pat, dir) => { const p = pat.replace(/^\.\/?/, '').replace(/\/$/, '');
+  if (p === '...') return true;
+  if (p.endsWith('/...')) { const base = p.slice(0, -4); return dir === base || dir.startsWith(base + '/'); }
+  return dir === p; };
+
+/* the module dir the run uses (repo-relative, '' = root), or { why } */
+export function goModuleDir(m, cmd, hasRootGoMod) {
+  const mods = m.selfCheck?.go?.modules || [];
+  if (cmd.dir) return mods.some(x => (x.dir === '.' ? '' : x.dir) === cmd.dir) ? { dir: cmd.dir } : { why: `-C ${cmd.dir}: no go.mod there in the code map` };
+  if (hasRootGoMod) return { dir: '' };
+  if (mods.length === 1) return { dir: mods[0].dir === '.' ? '' : mods[0].dir };
+  return { why: mods.length ? `the repo holds ${mods.length} Go modules (${mods.map(x => x.dir).join(', ')}): name one with go -C <dir> test` : 'no go.mod in the code map' };
+}
+
+/* the code map's tests the command runs: [{ id, name, pkgDir (module-relative) }]; a test in a module nested inside
+   this one is that module's, which go test skips */
+export function goTestsToRun(m, cmd, modDir) {
+  let re = null; if (cmd.run) { try { re = new RegExp(cmd.run); } catch { re = null; } }
+  const nested = (m.selfCheck?.go?.modules || []).map(x => x.dir === '.' ? '' : x.dir).filter(d => d !== modDir && (!modDir || d.startsWith(modDir + '/')));
+  return (m.tests || []).filter(t => t.file.endsWith('_test.go') && !nested.some(d => t.file.startsWith(d + '/'))).map(t => {
+    const rel = modDir ? (t.file.startsWith(modDir + '/') ? t.file.slice(modDir.length + 1) : null) : t.file;
+    return rel == null ? null : { id: t.id, name: t.id.split(':').pop(), file: t.file, pkgDir: posix.dirname(rel) === '.' ? '' : posix.dirname(rel) };
+  }).filter(t => t && cmd.packages.some(p => selects(p, t.pkgDir)) && (!re || re.test(t.name)));
+}
+
+export const goTestArgv = ({ go, flags, name, profile, pkgDir }) =>
+  [go, 'test', '-json', '-count=1', `-run=^${name}$`, `-coverprofile=${profile}`, '-coverpkg=./...', ...flags, pkgDir ? `./${pkgDir}` : '.'];
+
+/* `go test -json` events -> { tests: [{ name, status, message }], buildErrors: [text] } (top-level tests only; a
+   subtest's failure fails its parent) */
+export function parseGoTestJson(text) {
+  const status = new Map(), out = new Map(), pkgOut = [];
+  let pkgFailed = false;
+  for (const line of text.split('\n')) {
+    if (!line.startsWith('{')) { if (line.trim()) pkgOut.push(line + '\n'); continue; }
+    let e; try { e = JSON.parse(line); } catch { continue; }
+    const top = e.Test ? e.Test.split('/')[0] : null;
+    if (e.Action === 'output') { if (top) out.set(top, (out.get(top) || '') + e.Output); else pkgOut.push(e.Output); continue; }
+    if (e.Test && !e.Test.includes('/') && /^(pass|fail|skip)$/.test(e.Action)) status.set(e.Test, e.Action === 'pass' ? 'passed' : e.Action === 'fail' ? 'failed' : 'skipped');
+    if (!e.Test && e.Action === 'fail') pkgFailed = true;
+  }
+  const tests = [...status].map(([name, s]) => ({ name, status: s, message: (out.get(name) || '').trim() }));
+  return { tests, buildErrors: pkgFailed && !tests.length ? [pkgOut.join('').trim()] : [] };
+}
+
+/* a coverprofile -> Map(repo-relative file -> [{ start, end, count }]); `importDir` maps an import path to a repo dir */
+export function parseCoverProfile(text, importDir) {
+  const out = new Map();
+  for (const line of text.split('\n')) {
+    const m = /^(.+\.go):(\d+)\.\d+,(\d+)\.\d+ \d+ (\d+)$/.exec(line.trim());
+    if (!m) continue;
+    const slash = m[1].lastIndexOf('/'), dir = importDir(m[1].slice(0, slash));
+    if (dir == null) continue;
+    const file = (dir ? `${dir}/` : '') + m[1].slice(slash + 1);
+    (out.get(file) || out.set(file, []).get(file)).push({ start: +m[2], end: +m[3], count: +m[4] });
+  }
+  return out;
+}
+
+export const GO_NETWORK = /\bdial (tcp|udp|unix)\S*[^\n]*|\bsocket: operation not permitted|\blookup \S+[^\n]*(no such host|operation not permitted|server misbehaving)/g;

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

@@ -0,0 +1,136 @@
+/* trace.mjs's JavaScript / TypeScript runners (design §3.14, §3.17): which test commands are recognised, which test
+   files each one runs, and the command line that runs one file under V8 precise coverage with a machine-readable
+   report. Only the repo's own installed runner is ever run (its node_modules/.bin); nothing is installed. jest and vitest
+   run from the package that holds the runner: the repo root, else the one package below it (a package.json beside a
+   node_modules/.bin holding the runner, such as frontend/) that holds the code map's test files; test files and the
+   paths given are read relative to it, as the runner run there reads them.
+   - `node --test [--test-* flags] [paths]`: the TAP reporter on stdout;
+   - `npx jest [args]`, `jest [args]`, `node_modules/.bin/jest [args]`: --json --outputFile, --runInBand, no watchman;
+   - `npx vitest [run] [args]`, `vitest …`: --reporter=json --outputFile, run mode, the threads pool (a forked worker is
+     killed before it can write its coverage; worker threads write theirs).
+   A split value of a jest or vitest flag that takes one (`-t adds`, `--config vitest.config.ts`) is joined to it;
+   every other flag is boolean, so a word after it is a test path or filter. A positional selects test files as the
+   runner does: a path or directory for node, a case-insensitive regex over the path for jest (as is a
+   --testPathPattern value, which is not passed on: --runTestsByPath ignores it), a case-insensitive substring of it
+   for vitest. jest and vitest run with --passWithNoTests, so a file the repo's own config does not collect exits 0
+   instead of failing. */
+import { existsSync, readFileSync, readdirSync, lstatSync, realpathSync } from 'node:fs';
+import { join, basename, relative, sep } from 'node:path';
+
+const NODE_FLAG = /^--(test-name-pattern|test-skip-pattern|test-timeout|test-concurrency)=.+$|^--test-only$|^--experimental-(strip|transform)-types$|^--experimental-test-module-mocks$|^--no-experimental-strip-types$/;
+// flags the trace sets itself, or that would never end or report elsewhere
+const OWN_FLAGS = /^--(watch|watchAll|ui|coverage|shard|outputFile|json|reporter|pool|threads|runInBand|watchman|ci|browser|api|inspect)(\b|=|$)/;
+// each runner's flags that take a value
+const VALUE_FLAGS = {
+  jest: new Set(['-t', '--testNamePattern', '-c', '--config', '--testPathPattern', '--testPathPatterns', '--testPathIgnorePatterns', '--rootDir', '--roots',
+    '--selectProjects', '--projects', '--testEnvironment', '--env', '-w', '--maxWorkers', '--testTimeout', '--testMatch', '--testRegex', '--seed', '--reporters']),
+  vitest: new Set(['-t', '--testNamePattern', '-c', '--config', '-r', '--root', '--dir', '--project', '--environment', '--testTimeout', '--maxWorkers',
+    '--minWorkers', '--mode', '--exclude', '--retry', '--bail']),
+};
+
+/* -> { runner, args } or null. `words` is the command split like a shell would */
+export function recogniseJs(words) {
+  const head = basename(words[0]);
+  if (/^node(\d+)?$/.test(head) && words[1] === '--test') {
+    const args = words.slice(2);
+    return args.every(a => !a.startsWith('-') || NODE_FLAG.test(a)) ? { runner: 'node-test', args } : null;
+  }
+  let tool = null, args = [];
+  if (head === 'npx' && /^(jest|vitest)$/.test(words[1] || '')) { tool = words[1]; args = words.slice(2); }
+  else if (/^(jest|vitest)$/.test(head) && (!words[0].includes('/') || /(^|\/)node_modules\/\.bin\/(jest|vitest)$/.test(words[0]))) { tool = head; args = words.slice(1); }
+  if (!tool) return null;
+  if (tool === 'vitest') { if (/^(watch|dev|bench|init|list|serve)$/.test(args[0] || '')) return null; if (args[0] === 'run') args = args.slice(1); }
+  const joined = [];
+  for (let i = 0; i < args.length; i++) joined.push(VALUE_FLAGS[tool].has(args[i]) && args[i + 1] != null ? `${args[i]}=${args[++i]}` : args[i]);
+  if (joined.some(a => OWN_FLAGS.test(a))) return null;
+  return { runner: tool, args: joined };
+}
+
+// each runner's own default test-file pattern, applied to the code map's test files
+const PATTERNS = {
+  'node-test': f => /\.test\.[cm]?[jt]s$|[-_.]test\.[cm]?[jt]s$|(^|\/)test-[^/]*\.[cm]?[jt]s$|(^|\/)test\.[cm]?[jt]s$|(^|\/)test\/.*\.[cm]?[jt]s$/.test(f),
+  jest: f => /(^|\/)__tests__\/.*\.[jt]sx?$|\.(test|spec)\.[jt]sx?$/.test(f),
+  vitest: f => /\.(test|spec)\.[cm]?[jt]sx?$/.test(f),
+};
+// which files a positional selects, as each runner reads it
+const SELECTS = {
+  'node-test': p => f => f === p || f.startsWith(p + '/'),
+  jest: p => { let re; try { re = new RegExp(p, 'i'); } catch { return () => false; } return f => re.test(f); },
+  vitest: p => f => f.toLowerCase().includes(p.toLowerCase()),
+};
+// what an argument selects test files by: a positional, or jest's --testPathPattern(s) (which --runTestsByPath ignores)
+const selectorOf = (runner, a) => !a.startsWith('-') ? a : runner === 'jest' && /^--testPathPatterns?=/.test(a) ? a.slice(a.indexOf('=') + 1) : null;
+// -> the repo-relative test files the command runs, from the package `pkg` ('' for the repo root)
+export function jsTestFiles(m, runner, args, pkg = '') {
+  const selects = args.map(a => selectorOf(runner, a)).filter(p => p != null).map(p => SELECTS[runner](p.replace(/^\.\//, '').replace(/\/$/, '')));
+  const files = [...new Set((m.tests || []).filter(t => /\.[cm]?[jt]sx?$/.test(t.file)).map(t => t.file))].sort();
+  const inPkg = f => pkg ? (f.startsWith(pkg + '/') ? f.slice(pkg.length + 1) : null) : f;
+  return files.filter(f => { const p = inPkg(f); return p != null && PATTERNS[runner](p) && (!selects.length || selects.some(sel => sel(p))); });
+}
+export const passThrough = (runner, args) => args.filter(a => selectorOf(runner, a) == null);
+
+// the runner's entry in the repo's node_modules: a node script (run with node) or a shell shim (run as is)
+export function runnerBin(root, runner) {
+  const bin = join(root, 'node_modules', '.bin', runner);
+  if (!existsSync(bin)) return null;
+  const real = realpathSync(bin);
+  const head = readFileSync(real, 'utf8').slice(0, 200);
+  return { rel: `node_modules/.bin/${runner}`, node: /\.[cm]?js$/.test(real) || /^#!.*\bnode\b/.test(head) };
+}
+
+// the package jest or vitest runs from: { dir, bin } (dir '' for the repo root), or { why } when none can be chosen
+export function runnerPackage(root, m, runner) {
+  if (runnerBin(root, runner)) return { dir: '', bin: runnerBin(root, runner) };
+  const pkgs = nodeModulesDirs(root).map(d => d.slice(0, -'/node_modules'.length)).filter(d => d && existsSync(join(root, d, 'package.json')) && runnerBin(join(root, d), runner));
+  if (!pkgs.length) return { why: `${runner} is not installed in the repo (no node_modules/.bin/${runner} at its root or beside a package.json below it)` };
+  const owners = pkgs.filter(d => jsTestFiles(m, runner, [], d).length);
+  if (owners.length > 1) return { why: `${runner} is installed in ${owners.length} packages that hold test files (${owners.join(', ')}), and one command runs from one of them` };
+  const dir = owners[0] ?? (pkgs.length === 1 ? pkgs[0] : null);
+  return dir == null ? { why: `${runner} is installed in ${pkgs.join(', ')}, none of which holds a test file` } : { dir, bin: runnerBin(join(root, dir), runner) };
+}
+
+// node_modules dirs under the repo (not inside another one), to link into the copy and expose read-only
+export function nodeModulesDirs(root, max = 4) {
+  const out = [];
+  (function walk(rel, depth) {
+    let names; try { names = readdirSync(join(root, rel)); } catch { return; }
+    for (const name of names) {
+      if (name === '.git') continue;
+      const r = rel ? `${rel}/${name}` : name;
+      let st; try { st = lstatSync(join(root, r)); } catch { continue; }
+      if (!st.isDirectory()) continue;
+      if (name === 'node_modules') out.push(r);
+      else if (depth < max && !name.startsWith('.')) walk(r, depth + 1);
+    }
+  })('', 0);
+  return out.sort();
+}
+
+// the links that put one of those node_modules dirs into the copy: each entry (a scope's entries one by one) to the
+// repo's own, except a workspace package (a symlink into the repo, outside every node_modules dir) to its counterpart
+// in the copy, since the sandbox hides the repo. vite's caches (which it writes into on every run) are left out, so the
+// run makes its own in the copy. -> [{ rel, copy }], copy null for the repo's own entry
+const VITE_CACHES = new Set(['.vite', '.vite-temp', '.vitest']);
+export function nodeModulesLinks(root, dir, dirs) {
+  const out = [];
+  (function each(rel) {
+    for (const name of readdirSync(join(root, rel)).sort()) {
+      if (rel === dir && VITE_CACHES.has(name)) continue;
+      const r = `${rel}/${name}`;
+      let st; try { st = lstatSync(join(root, r)); } catch { continue; }
+      if (name.startsWith('@') && st.isDirectory()) { each(r); continue; }
+      let real = null; if (st.isSymbolicLink()) try { real = realpathSync(join(root, r)); } catch {}
+      const workspace = real && real.startsWith(root + sep) && !dirs.some(d => real.startsWith(join(root, d) + sep));
+      out.push({ rel: r, copy: workspace ? relative(root, real) : null });
+    }
+  })(dir);
+  return out;
+}
+
+// one file's command line, and where its report lands (null: stdout)
+export function fileArgv({ runner, node, bin, flags, file, report }) {
+  const tool = bin ? (bin.node ? [node, bin.rel] : [bin.rel]) : null;
+  if (runner === 'node-test') return [node, ...flags, '--test', '--test-reporter=tap', file];
+  if (runner === 'jest') return [...tool, ...flags, '--ci', '--watchman=false', '--runInBand', '--passWithNoTests', '--json', `--outputFile=${report}`, '--runTestsByPath', file];
+  return [...tool, 'run', ...flags, '--passWithNoTests', '--reporter=json', `--outputFile=${report}`, '--pool=threads', file];
+}

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

@@ -0,0 +1,19 @@
+/* Load the vendored tree-sitter runtime and grammars. File names come from MANIFEST.json
+   (written by scripts/sync-tree-sitter.mjs), never from node_modules, so the tools run
+   from a git clone with no `npm install` and from any cwd. */
+import { readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const VENDOR = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'vendor', 'tree-sitter');
+
+export async function loadGrammars(langs) {
+  const manifest = JSON.parse(readFileSync(join(VENDOR, 'MANIFEST.json'), 'utf8'));
+  const { Parser, Language } = await import(pathToFileURL(join(VENDOR, manifest.runtime.js)).href);
+  await Parser.init();
+  const grammars = {};
+  for (const lang of langs) grammars[lang] = await Language.load(join(VENDOR, manifest.grammars[lang].file));
+  const versions = { [manifest.runtime.package]: manifest.runtime.version,
+    ...Object.fromEntries(langs.map(l => [manifest.grammars[l].package, manifest.grammars[l].version])) };
+  return { Parser, grammars, versions };
+}

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

@@ -0,0 +1,138 @@
+/* The candidate walk over a code map: from one symbol, down and back through the call graph, with the
+   receiver class carried so self-calls resolve per receiver. Group rules (design §3.7, §3.15):
+   - a non-test walk never enters test-group code: test doubles are counted and skipped;
+   - a production walk expands any non-test code it reaches, labelling other groups' nodes (`crossGroup`);
+   - an eval or dev walk folds every production symbol into a `uses-prod` leaf;
+   - helper folding counts callers from the symbol's own group only, never through test code.
+   A `py.callback` link (the callee runs a callable a caller handed it) is followed only from the caller that
+   handed it over, so a walk that reached the callee some other way never picks up another caller's callable. */
+
+export const FOLLOW = new Set(['static', 'ctor', 'framework', 'dispatch', 'queue', 'http', 'spawn', 'virtual']);
+export const CROSSING = new Set(['queue', 'http', 'spawn']);
+const DATA_BASES = /(^|\.)(BaseModel|BaseSettings|Exception|Error|Enum|StrEnum|IntEnum|TypedDict|NamedTuple|JSONResponse|Response)$/;
+const isCallback = e => e.rule === 'py.callback';
+
+export function indexCodemap(m, { fanin = 6, leafy = 5, ifaceFold = true } = {}) {
+  const sym = new Map(m.symbols.map(s => [s.id, s]));
+  const cls = new Map(m.classes.map(k => [k.id, k]));
+  const G = id => sym.get(id)?.group || (id.startsWith('ext:') ? 'ext' : 'prod');
+  const moduleOf = id => sym.get(id)?.module || (id.startsWith('ext:') ? 'ext' : id.split(':')[0]);
+  const declCls = id => sym.get(id)?.cls || null;
+  const isAbstract = id => (sym.get(id)?.decos || []).some(d => /abstractmethod/.test(d));
+  const subclasses = new Map();
+  for (const k of cls.values()) for (const b of k.bases) (subclasses.get(b) || subclasses.set(b, []).get(b)).push(k.id);
+  const mro = (id, seen = new Set()) => seen.has(id) ? [] : (seen.add(id), [id, ...(cls.get(id)?.bases || []).flatMap(b => mro(b, seen))]);
+  const lookup = (k, name) => { for (const c of mro(k)) { const x = cls.get(c)?.methods[name]; if (x) return x; } return null; };
+  const overridesOf = (k, name, acc = []) => { for (const s of subclasses.get(k) || []) { const x = cls.get(s).methods[name]; if (x) acc.push(x); overridesOf(s, name, acc); } return acc; };
+  const isData = (k, seen = new Set()) => { if (seen.has(k)) return false; seen.add(k); const c = cls.get(k); if (!c) return false;
+    if (c.decos?.some(d => /dataclass/.test(d)) || c.baseExprs.some(b => DATA_BASES.test(b))) return true; return c.bases.some(b => isData(b, seen)); };
+  const entryIds = new Set(m.entries.map(e => e.id));
+  const altFactories = new Set(Object.entries(m.factories || {}).filter(([f, v]) => new Set(v.map(x => x.cls || x.ext)).size > 1 && !entryIds.has(f)).map(([f]) => f));
+  const siteOf = new Map((m.config?.sites || []).map(s => [s.factory, s]));
+
+  const out = new Map(), handedBy = new Map();
+  for (const e of m.edges) {
+    if (isCallback(e)) (handedBy.get(e.passedBy) || handedBy.set(e.passedBy, []).get(e.passedBy)).push(e);
+    else (out.get(e.from) || out.set(e.from, []).get(e.from)).push(e);
+  }
+  const visible = (grp, id) => grp === 'test' || G(id) !== 'test';
+  const crossTargets = new Set(m.edges.filter(e => CROSSING.has(e.kind)).map(e => e.to));
+
+  // fan-in (same-group callers; a production caller also counts for a library target) and subtree size
+  const callers = new Map();
+  for (const e of m.edges) if (FOLLOW.has(e.kind) && e.kind !== 'virtual' && !isCallback(e) && (G(e.from) === G(e.to) || (G(e.to) === 'ext' && G(e.from) === 'prod')))
+    (callers.get(e.to) || callers.set(e.to, new Set()).get(e.to)).add(e.from);
+  const subtree = new Map();
+  const subtreeSize = start => {
+    if (subtree.has(start)) return subtree.get(start);
+    const grp = G(start), seen = new Set([start]), q = [start];
+    while (q.length) { const x = q.pop(); for (const e of out.get(x) || []) if (FOLLOW.has(e.kind) && visible(grp, e.to) && !seen.has(e.to)) { seen.add(e.to); q.push(e.to); } }
+    const n = [...seen].filter(x => !x.startsWith('ext:')).length - 1;
+    subtree.set(start, n);
+    return n;
+  };
+  const isHelper = id => !entryIds.has(id) && !crossTargets.has(id) && sym.get(id)?.kind !== 'class' &&
+    (callers.get(id)?.size || 0) >= fanin && subtreeSize(id) <= leafy;
+
+  /* walk from `start` as group `grp`. `stopAtCrossing` leaves queue/http/spawn targets unexpanded (segments,
+     test reach); `stop` are symbols left unexpanded as `mocked` (what a test replaces); `ctx0` the receiver class */
+  function expand(start, { grp = G(start.id), stopAtCrossing = false, stop = null, ctx0 } = {}) {
+    const nodes = new Map(), order = [], dispatch = [], constructs = new Set(), crossings = [], branches = [], folded = new Set(), seenSite = new Set();
+    const testDoubles = new Set(), usesProd = new Set(), crossGroup = new Set();
+    const leafOf = kind => ifaceFold ? kind : null;
+    const visit = (id, ctx, depth, via, parent, leaf) => {
+      if (!visible(grp, id)) { testDoubles.add(id); return; }
+      const key = id + '|' + (ctx || '');
+      if (nodes.has(key)) return;
+      const node = { id, ctx, depth, via, parent, folded: false };
+      nodes.set(key, node); order.push(node);
+      if (leaf) { node.folded = leaf; folded.add(id); return; }
+      if (stop && stop.has(id)) { node.folded = 'mocked'; folded.add(id); return; }
+      if (depth > 0 && grp !== 'prod' && G(id) === 'prod') { node.folded = 'uses-prod'; folded.add(id); usesProd.add(id); return; }
+      if (depth > 0 && isHelper(id)) { node.folded = 'helper'; folded.add(id); return; }
+      if (id.startsWith('ext:')) return;
+      if (G(id) !== grp) crossGroup.add(id);
+      const edges = out.get(id) || [];
+      const sites = new Map();
+      for (const e of edges) if (e.self || (e.site && (e.kind === 'dispatch' || e.kind === 'virtual'))) (sites.get(e.site) || sites.set(e.site, []).get(e.site)).push(e);
+      for (const e of edges) {
+        if (!FOLLOW.has(e.kind)) continue;
+        if (!visible(grp, e.to)) { testDoubles.add(e.to); continue; }
+        if (e.cfg) branches.push({ from: id, to: e.to, cfg: e.cfg, line: e.line, onFailure: e.onFailure });
+        if (e.kind === 'ctor') {
+          const k = cls.has(e.to) ? e.to : declCls(e.to);
+          if (cls.has(e.to)) { if (isData(e.to)) constructs.add(e.to); continue; }
+          if (isData(k)) continue;
+          visit(e.to, k, depth + 1, 'ctor', id, altFactories.has(id) ? leafOf('alternative') : null);
+          continue;
+        }
+        if (e.self) {
+          if (seenSite.has(e.site + key)) continue;
+          seenSite.add(e.site + key);
+          const all = sites.get(e.site).map(x => x.to).filter(t => visible(grp, t));
+          let targets, how;
+          if (ctx) { const t = lookup(ctx, e.self); targets = [...new Set([t, ...overridesOf(ctx, e.self)].filter(Boolean))].filter(t => visible(grp, t)); how = 'receiver'; }
+          else { targets = all; how = 'cha'; }
+          if (all.length > 1 || targets.length > 1) dispatch.push({ site: e.site, attr: e.self, how, before: all.length, after: targets.length, ctx, targets });
+          for (const t of targets) visit(t, ctx, depth + 1, targets.length > 1 ? 'virtual' : 'static', id);
+          continue;
+        }
+        if (e.kind === 'virtual' || e.kind === 'dispatch') {
+          if (e.site && seenSite.has(e.site + key + e.kind)) continue;
+          if (e.site) seenSite.add(e.site + key + e.kind);
+          const alts = (e.site ? (sites.get(e.site) || [e]).filter(x => x.kind === e.kind || x.kind === 'static') : [e]).filter(x => visible(grp, x.to));
+          if (e.kind === 'dispatch' && e.rule === 'haystack.pipeline') {
+            const comp = edges.filter(x => x.rule === 'haystack.pipeline' && x.component === e.component);
+            dispatch.push({ site: `${id}@${e.line}:${e.component}`, attr: e.component, how: 'factory', before: comp.length, after: comp.length, targets: comp.map(x => x.to),
+              selectors: comp.map(x => x.selectors), narrowedBy: e.narrowedBy, config: configOf(e.narrowedBy) });
+            for (const x of comp) visit(x.to, declCls(x.to), depth + 1, 'framework', id);
+            continue;
+          }
+          const concrete = alts.filter(x => !isAbstract(x.to));
+          dispatch.push({ site: e.site, attr: e.site?.split(':').pop(), how: e.kind === 'dispatch' ? 'factory' : 'cha', before: alts.length, after: concrete.length,
+            targets: alts.map(x => x.to), narrowedBy: e.narrowedBy, config: configOf(e.narrowedBy), collaborator: true });
+          for (const x of alts) visit(x.to, declCls(x.to), depth + 1, e.kind, id, isAbstract(x.to) ? leafOf('interface') : concrete.length > 1 ? leafOf('alternative') : null);
+          continue;
+        }
+        if (CROSSING.has(e.kind)) {
+          if (!crossings.some(x => x.from === id && x.to === e.to && x.kind === e.kind)) crossings.push({ from: id, to: e.to, kind: e.kind, evidence: e.evidence, intoGroup: G(e.to) });
+          if (!stopAtCrossing) visit(e.to, null, depth + 1, e.kind, id);
+          continue;
+        }
+        if (e.kind === 'framework') { visit(e.to, declCls(e.to), depth + 1, 'framework', id); continue; }
+        visit(e.to, e.recvClass || (e.passCtx ? ctx : null), depth + 1, 'static', id);
+      }
+      // callables this symbol handed to a callee: they run inside that callee, so they hang under it
+      for (const e of handedBy.get(id) || []) if (visible(grp, e.to)) visit(e.to, declCls(e.to) ? ctx : null, depth + 2, 'callback', e.from);
+    };
+    visit(start.id, ctx0 !== undefined ? ctx0 : start.kind === 'ui-route' ? null : declCls(start.id), 0, 'entry', null);
+    const ids = new Set(order.map(n => n.id));
+    const own = new Set([...ids].filter(i => !folded.has(i) && !i.startsWith('ext:')));
+    return { order, ids, own, folded, constructs, crossings, branches, dispatch, testDoubles, usesProd, crossGroup,
+      modules: new Set([...own].map(moduleOf)), maxDepth: Math.max(...order.map(n => n.depth)) };
+  }
+  const configOf = factory => { const s = factory && siteOf.get(factory);
+    return s ? { classification: s.classification, alternatives: s.alternatives.map(a => ({ cls: a.cls, group: a.group, guards: a.guards })) } : undefined; };
+
+  return { sym, G, moduleOf, declCls, out, entryIds, isHelper, expand };
+}