explainer-video 0.0.0-stage → 0.4.0

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

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+/* =============================================================================
+   rank.mjs — order each group's top-level candidates by the new code they cover,
+   and print every row with the evidence the agent reads to propose a series.
+
+   Usage:
+     node tools/rank.mjs --candidates out/<name>/candidates.json [--explain-top 10] [--explain-top-eval 5]
+
+   Writes ranking.json and ranking.md beside candidates.json. Per group
+   (prod, eval, dev) the order is greedy marginal coverage of that group's
+   own symbols, ties broken by more crossings. There is no cut line and no series:
+   each row carries its nearest higher-ranked row with their Jaccard overlap, how
+   many of its functions tests pin, which evals exercise it, and its config-
+   dependent dispatch points. A second table lists production modules that many
+   candidates share and many tests pin, since cross-cutting code has no entry point
+   of its own. The merged prod+eval order is evidence only. Dev rows are printed
+   and filtered by default.
+
+   Exit: 0 ok · 1 bad flags, unreadable candidates, or candidates.json inside the repo
+   ========================================================================== */
+import { readFileSync, writeFileSync, existsSync, realpathSync } from 'node:fs';
+import { join, resolve, dirname, sep, relative } from 'node:path';
+import { renderRanking, configDispatchPoints } from './ranking-md.mjs';
+
+const fail = (code, msg) => { console.error(`[rank] ${msg}`); process.exit(code); };
+
+/* ---------------- args ---------------- */
+const argv = process.argv.slice(2);
+const VALUED = new Set(['--candidates', '--explain-top', '--explain-top-eval']);
+const flags = new Map();
+for (let i = 0; i < argv.length; i++) {
+  if (VALUED.has(argv[i])) { if (argv[i + 1] == null) fail(1, `${argv[i]} needs a value`); flags.set(argv[i], argv[++i]); }
+  else fail(1, `unknown argument ${argv[i]}`);
+}
+if (!flags.has('--candidates')) fail(1, 'usage: rank.mjs --candidates out/<name>/candidates.json [--explain-top 10] [--explain-top-eval 5]');
+const count = (flag, d) => { const v = flags.has(flag) ? Number(flags.get(flag)) : d; if (!Number.isInteger(v) || v < 0) fail(1, `${flag} must be a whole number`); return v; };
+const params = { explainTop: count('--explain-top', 10), explainTopEval: count('--explain-top-eval', 5) };
+const CANDIDATES = resolve(flags.get('--candidates'));
+let r;
+try { r = JSON.parse(readFileSync(CANDIDATES, 'utf8')); } catch (e) { fail(1, `cannot read ${CANDIDATES}: ${e.message}`); }
+if (r.schema !== 1 || !r.candidates || !r.bySymbol) fail(1, `${CANDIDATES} is not a propose.mjs candidates file (schema 1)`);
+const OUT = dirname(CANDIDATES);
+if (r.root && existsSync(r.root)) { const root = realpathSync(r.root), o = realpathSync(OUT); if (o === root || o.startsWith(root + sep)) fail(1, `refusing to write inside the repo: ${OUT}`); }
+
+/* ---------------- rank ---------------- */
+const cands = Object.entries(r.candidates).map(([id, c]) => ({ id, ...c, own: new Set(c.ownIds) }));
+const topLevel = grp => cands.filter(c => c.group === grp && !c.continues);
+const pinnedBy = id => r.bySymbol[id]?.direct || [];
+const jaccard = (a, b) => { let i = 0; for (const x of a) if (b.has(x)) i++; return i / (a.size + b.size - i || 1); };
+const evalPool = topLevel('eval');
+const exercisesOf = c => c.exercises.map(x => x.to);
+
+// greedy marginal coverage: repeatedly take the candidate that adds the most not-yet-covered own symbols
+function rankPool(pool) {
+  const universe = new Set(pool.flatMap(c => [...c.own])), covered = new Set(), ranked = [], left = [...pool];
+  while (left.length) {
+    let best = null, bestGain = -1;
+    for (const c of left) { let gain = 0; for (const s of c.own) if (!covered.has(s)) gain++;
+      if (gain > bestGain || (gain === bestGain && c.crossings.length > best.crossings.length)) { best = c; bestGain = gain; } }
+    left.splice(left.indexOf(best), 1);
+    const newSyms = [...best.own].filter(s => !covered.has(s));
+    for (const s of best.own) covered.add(s);
+    let near = null, nj = -1;
+    for (const x of ranked) { const j = jaccard(best.own, x.c.own); if (j > nj) { nj = j; near = x; } }
+    const tests = new Set([...best.own].flatMap(pinnedBy)), testsNew = new Set(newSyms.flatMap(pinnedBy));
+    ranked.push({ c: best, gain: bestGain, cumulative: covered.size, nearest: near ? near.c.id : null, jaccard: near ? Number(nj.toFixed(2)) : null,
+      pinned: [...best.own].filter(s => pinnedBy(s).length).length, tests: tests.size, testsNew: testsNew.size,
+      cfg: configDispatchPoints(best.dispatch).length,
+      evals: evalPool.filter(e => e.usesProd.some(s => best.own.has(s)) || exercisesOf(e).some(s => best.own.has(s))).map(e => e.id) });
+  }
+  return { universe, ranked };
+}
+const pools = { prod: rankPool(topLevel('prod')), eval: rankPool(evalPool), dev: rankPool(topLevel('dev')) };
+const merged = rankPool([...topLevel('prod'), ...evalPool]);   // evidence only: where eval flows would land on one list
+
+// the first-ranked production row whose own code holds a symbol: which flow an eval exercises
+const prodRanked = pools.prod.ranked;
+const flowRank = id => { const i = prodRanked.findIndex(x => x.c.own.has(id)); return i === -1 ? null : i + 1; };
+const row = (x, i, universe) => ({
+  rank: i + 1, entry: x.c.id, group: x.c.group, kind: x.c.kind, method: x.c.method, path: x.c.path, key: x.c.key, file: x.c.file, line: x.c.line,
+  gain: x.gain, cumulative: x.cumulative, coverage: Number((x.cumulative / (universe.size || 1)).toFixed(3)),
+  own: x.c.own.size, folded: x.c.folded, modules: x.c.modules, crossings: x.c.crossings.length, nearest: x.nearest, jaccard: x.jaccard,
+  pinned: x.pinned, tests: x.tests, testsNew: x.testsNew, cfg: x.cfg, evals: x.evals,
+  ...(x.c.group !== 'prod' ? {
+    exercises: [...new Map(x.c.exercises.map(e => [e.to, { to: e.to, kind: e.kind, flowRank: flowRank(e.to) }])).values()],
+    usesProd: x.c.usesProd.map(id => ({ id, flowRank: flowRank(id) })) } : {}),
+});
+const ranked = Object.fromEntries(Object.entries(pools).map(([g, p]) => [g, p.ranked.map((x, i) => row(x, i, p.universe))]));
+
+// shared, heavily tested production code: a module whose functions appear in >= 3 top-level production candidates
+// and that >= 5 tests pin directly, listed with the first row that owns it
+const sym = r.symbols;
+const mods = new Map();
+prodRanked.forEach((x, i) => { for (const n of x.c.nodes) { const s = sym[n.id];
+  if (!s || s.group !== 'prod' || (s.kind !== 'function' && s.kind !== 'method')) continue;
+  const mod = mods.get(s.file) || mods.set(s.file, { cands: new Set(), fns: new Set(), tests: new Set() }).get(s.file);
+  mod.cands.add(i + 1); mod.fns.add(n.id); for (const t of pinnedBy(n.id)) mod.tests.add(t); } });
+const shared = [...mods].map(([file, x]) => ({ module: file, candidates: x.cands.size, firstOwner: Math.min(...x.cands),
+  firstOwnerEntry: prodRanked[Math.min(...x.cands) - 1].c.id, functions: x.fns.size, directTests: x.tests.size }))
+  .filter(x => x.candidates >= 3 && x.directTests >= 5)
+  .sort((a, b) => b.directTests - a.directTests || b.candidates - a.candidates || (a.module < b.module ? -1 : 1));
+
+const continuations = cands.filter(c => c.continues).map(c => ({ entry: c.id, group: c.group, kind: c.kind, method: c.method, path: c.path, key: c.key, parents: c.continues, own: c.own.size }));
+const ranking = {
+  schema: 1, tool: { name: 'rank.mjs' }, root: r.root, commit: r.commit, treeHash: r.treeHash, params,
+  totals: { topLevel: Object.fromEntries(Object.entries(pools).map(([g, p]) => [g, p.ranked.length])),
+    universe: Object.fromEntries(Object.entries(pools).map(([g, p]) => [g, p.universe.size])), continuations: continuations.length },
+  ranked,
+  merged: merged.ranked.map((x, i) => ({ rank: i + 1, entry: x.c.id, group: x.c.group, gain: x.gain })),
+  shared, continuations,
+};
+writeFileSync(join(OUT, 'ranking.json'), JSON.stringify(ranking, null, 1) + '\n');
+writeFileSync(join(OUT, 'ranking.md'), renderRanking(ranking, r));
+
+const t = ranking.totals;
+console.log(`[rank] top-level ${JSON.stringify(t.topLevel)} · universes ${JSON.stringify(t.universe)} · ${t.continuations} continuations · no cut line`);
+console.log(`[rank] merged prod+eval (evidence only): ${ranking.merged.slice(0, 5).map(x => `${x.rank}:${x.entry.split(':').pop()}[${x.group}]`).join(' ')}`);
+console.log(`[rank] shared heavily-tested production modules ${shared.length}${shared.length ? `, led by ${shared[0].module} (${shared[0].directTests} direct tests)` : ''}`);
+console.log(`[rank] wrote ${relative(process.cwd(), OUT) || '.'}/ranking.{json,md}`);

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

@@ -0,0 +1,76 @@
+/* ranking.md: every row of every group with its evidence columns, the shared heavily-tested table, every
+   continuation with its parent, the merged prod+eval order, and for the top rows of prod and eval their segments,
+   config-dependent dispatch points and config-guarded branches. No row is marked chosen: the agent proposes. */
+const short = id => id.endsWith(':<main>') ? id.split(':')[0].split('.').pop() + ':<main>' : id.split(':').pop();
+const table = (head, rows) => rows.length ? [`| ${head.join(' | ')} |`, `|${head.map(() => '---').join('|')}|`, ...rows.map(r => `| ${r.map(c => String(c ?? '').replace(/\|/g, '\\|')).join(' | ')} |`)].join('\n') : '_none_';
+const what = x => x.path ? [x.method, x.path].filter(Boolean).join(' ') : x.key || '';
+const pct = x => `${Math.round(100 * x)}%`;
+
+// a dispatch point whose targets depend on config: narrowed by a config read, picked by selectors, or a collaborator
+// with more than one concrete implementation; one per site and target set, however many times the walk passed it
+export const configDispatchPoints = dispatch => { const seen = new Set();
+  return dispatch.filter(d => d.config || d.selectors || (d.collaborator && d.after > 1)).filter(d => { const key = d.site + d.targets.join(); return !seen.has(key) && seen.add(key); }); };
+
+export function renderRanking(k, r) {
+  const out = [];
+  const t = k.totals;
+  out.push(`# Ranking: ${(k.root || '').split('/').pop()}`, '',
+    `- ${k.commit ? `commit \`${k.commit.slice(0, 7)}\` · ` : ''}tree ${(k.treeHash || '').slice(0, 19)}…`,
+    `- top-level candidates: prod ${t.topLevel.prod}, eval ${t.topLevel.eval}, dev ${t.topLevel.dev} · ${t.continuations} continuations · universes prod ${t.universe.prod}, eval ${t.universe.eval}, dev ${t.universe.dev} own symbols`,
+    `- walk: same-group fan-in >= ${r.params.fanin} with a subtree <= ${r.params.leafy} folds a helper · interface folding ${r.params.ifaceFold ? 'on' : 'off'}`, '',
+    'Each group is ordered by the new own code a row adds (`gain`), ties by more crossings. **There is no cut line and no series**: ' +
+    'new code is not important code. Read `nearest (J)` to judge "same flow" against "different flow", and the test, eval and config ' +
+    'columns for importance the order cannot see. Every high-ranked row needs a decision with a reason in `flows.json`.', '',
+    'Columns: `own` expanded symbols · `cross` crossings (queue, HTTP, spawn) · `pinned` own functions with a direct test link · ' +
+    '`tests` distinct tests pinning own code · `new` tests pinning only this row\'s new code · `cfg` config-dependent dispatch points · `evals` eval candidates exercising this row.', '');
+
+  const rows = (grp, xs) => table(['rank', 'gain', 'cum', 'kind', 'entry', 'route / key', 'own', 'cross', 'nearest (J)', 'pinned', 'tests', 'new', 'cfg', 'evals'],
+    xs.map(x => [x.rank, x.gain, pct(x.coverage), x.kind, `\`${short(x.entry)}\``, what(x), x.own, x.crossings,
+      x.nearest ? `#${xs.find(y => y.entry === x.nearest).rank} \`${short(x.nearest)}\` (${x.jaccard})` : '—', x.pinned, x.tests, x.testsNew, x.cfg,
+      grp === 'prod' ? x.evals.map(e => `\`${short(e)}\``).join(', ') : x.evals.length]));
+  const prodRank = new Map(k.ranked.prod.map(x => [x.entry, x.rank]));
+  const flow = f => f.flowRank ? ` (in #${f.flowRank})` : '';
+
+  out.push(`## prod: ${t.topLevel.prod} rows`, '', rows('prod', k.ranked.prod), '');
+  out.push(`## eval: ${t.topLevel.eval} rows`, '', 'Eval flows are ranked in their own group and never filtered: account for each high-ranked row (include, variant, or skip with a reason). ' +
+    'An eval walk folds the production code it calls into `uses-prod` leaves; its crossings into production are `exercises` links, not continuations.', '', rows('eval', k.ranked.eval), '');
+  const KIND_ORDER = ['http', 'queue', 'spawn'];
+  const byKind = xs => [...xs].sort((a, b) => KIND_ORDER.indexOf(a.kind) - KIND_ORDER.indexOf(b.kind));
+  out.push('### What each eval row exercises in production', '', 'A spawn link is a process the harness starts (a worker, a scheduler) and every consumer it serves.', '',
+    table(['rank', 'entry', 'exercises (crossings)', 'other uses-prod leaves'], k.ranked.eval.map(x => { const crossed = new Set(x.exercises.map(e => e.to));
+      return [x.rank, `\`${short(x.entry)}\``, byKind(x.exercises).map(e => `${e.kind} \`${short(e.to)}\`${flow(e)}`).join(', ') || '—',
+        x.usesProd.filter(u => !crossed.has(u.id)).map(u => `\`${short(u.id)}\`${flow(u)}`).join(', ') || '—']; })), '');
+  out.push(`## dev: ${t.topLevel.dev} rows (filtered by default)`, '', 'Migrations, dev routes, debug, verification and ops scripts: printed, not proposed. Promote a row in `flows.json` with a reason.', '',
+    rows('dev', k.ranked.dev), '');
+
+  out.push('## Shared, heavily tested production code', '',
+    'Production modules whose functions appear in at least 3 production rows and that at least 5 tests pin directly. Cross-cutting code (auth, retry, tokens) ' +
+    'has no entry point, so the order above counts it only inside the first row that reaches it.', '',
+    table(['module', 'in rows', 'first owner', 'functions', 'direct tests'], k.shared.map(x => [`\`${x.module}\``, x.candidates, `#${x.firstOwner} \`${short(x.firstOwnerEntry)}\``, x.functions, x.directTests])), '');
+
+  out.push('## Continuations', '', 'Entries reached through another candidate\'s same-group crossing. They are shown inside their parent, not ranked on their own.', '',
+    table(['entry', 'group', 'route / key', 'own', 'reached from'], k.continuations.map(c => [`\`${short(c.entry)}\``, c.group, what(c), c.own,
+      c.parents.map(p => `${prodRank.has(p) ? `#${prodRank.get(p)} ` : ''}\`${short(p)}\``).join(', ')])), '');
+
+  out.push('## Merged prod + eval order (evidence only)', '', 'Where eval flows would land on one list. Groups stay separate; this order decides nothing.', '',
+    table(['rank', 'entry', 'group', 'gain'], k.merged.map(x => [x.rank, `\`${short(x.entry)}\``, x.group, x.gain])), '');
+
+  const explain = (grp, n) => {
+    for (const x of k.ranked[grp].slice(0, n)) {
+      const c = r.candidates[x.entry];
+      out.push(`### ${grp} #${x.rank} \`${short(x.entry)}\`${what(x) ? ` — ${what(x)}` : ''}`, '',
+        `${c.file}${c.line ? `:${c.line}` : ''} · ${x.own} own, ${c.folded} folded, ${x.modules} modules, depth ${c.maxDepth} · ${c.testDoubles.length} test doubles refused`, '',
+        table(['segment root', 'reached from', 'via', 'own', 'folded'], c.segments.map(s => [`\`${short(s.root)}\``, s.from ? `\`${short(s.from)}\`` : '(entry)', s.kind || '', s.own, s.folded])), '');
+      const points = configDispatchPoints(c.dispatch);
+      if (points.length) out.push('Dispatch points:', '', table(['site', 'how', 'targets', 'config'], points.map(d => [`\`${d.site}\``, `${d.how} ${d.before}→${d.after}${d.narrowedBy ? ` by \`${short(d.narrowedBy)}\`` : ''}`,
+        d.targets.map(short).join(', '), d.config ? `${d.config.classification}: ${d.config.alternatives.map(a => `\`${short(a.cls)}\` when ${a.guards.join(' & ') || '(fallthrough)'}`).join('; ')}` : ''])), '');
+      const bseen = new Set();
+      const branches = c.branches.filter(b => { const key = `${b.from}|${b.to}|${b.line}`; return !bseen.has(key) && bseen.add(key); });
+      if (branches.length) out.push('Config-guarded branches:', '', table(['from', 'to', 'guard', 'line'], branches.map(b => [`\`${short(b.from)}\``, `\`${short(b.to)}\``, b.cfg.join(' & ') + (b.onFailure ? ` (on failure: ${b.onFailure})` : ''), b.line])), '');
+    }
+  };
+  out.push('## Top rows explained', '');
+  explain('prod', k.params.explainTop);
+  explain('eval', k.params.explainTopEval);
+  return out.join('\n');
+}

package/skills/explainer-video-from-codebase/tools/rules/c-handlers.mjs

@@ -0,0 +1,53 @@
+/* Rule pack: C and C++ string-to-handler tables. A table is
+   - a C array of rows, each a string and a function (`{ "add", cmd_add }`, `{ .name = "list", .run = cmd_list }`);
+   - a C++ map initialised with such pairs (`std::map<std::string, Handler> t = {{"add", cmd_add}, …}`), a lambda
+     value included (named `t["add"]`), or filled by assignments (`t["add"] = cmd_add;`, `this->t_["x"] = …`).
+   Each row is a `command` entry at its function, keyed by its string. A function that names the table and calls
+   through it — the row's function field of a C struct (`c->run(…)`, `commands[i].run(…)`), or a C++ map's value
+   (`t[name](…)`, `t.at(name)(…)`, `it->second(…)`) — is the dispatcher: a `dispatch` edge to every row's function,
+   one site, so a walk from the dispatcher folds them as alternatives and each command is its own flow. */
+import { addCEdge } from '../lang/c.mjs';
+
+export function handlerTables(cm, R) {
+  const entries = [], claimed = new Set(), tables = [];
+  // assignments to one map (`t["a"] = f; t["b"] = g;`) are one table
+  const byName = new Map();
+  for (const t of cm.tables) {
+    const name = t.name.replace(/^this->/, '');
+    const key = t.assigned ? `${t.module}#${name}` : t.var;
+    if (!byName.has(key)) { byName.set(key, { ...t, name, rows: [] }); tables.push(byName.get(key)); }
+    byName.get(key).rows.push(...t.rows);
+  }
+  for (const t of tables) {
+    const sc = { module: t.module, ns: t.ns || [] };
+    const k = !t.map && t.elemType ? R.classNamed(t.elemType, sc) : null;
+    const fieldAt = i => k ? cm.classes.get(k).fieldOrder[i] : null;
+    t.handlers = [];
+    for (const r of t.rows) {
+      const key = r.cells.find(x => x.str != null)?.str;
+      const fnCell = r.cells.find(x => x.fnId || (x.ref && R.funcNamed(x.ref, sc)));
+      if (key == null || !fnCell) continue;
+      const id = fnCell.fnId || R.funcNamed(fnCell.ref, sc);
+      t.field ||= fnCell.field || fieldAt(fnCell.i);
+      t.handlers.push({ key, id, line: r.line });
+      entries.push({ kind: 'command', key, id, file: t.file, line: r.line, rule: 'c.handler-table', table: t.name });
+    }
+  }
+  // the dispatcher: a function that names the table and calls through a row (C) or a map value (C++)
+  const links = [];
+  cm.rawCalls.forEach((c, i) => {
+    if (c.isNew || c.top) return;
+    const refs = cm.refs.get(c.from);
+    for (const t of tables) {
+      if (!t.handlers.length || !refs?.has(t.name)) continue;
+      const through = t.map ? (c.fnType === 'subscript_expression' || c.fnType === 'call_expression' || c.attr === 'second') : (c.attr && c.attr === t.field);
+      if (!through) continue;
+      claimed.add(i);
+      const site = `${c.from}@${c.line}:${t.name}`;
+      for (const h of t.handlers) addCEdge(cm, c.from, h.id, 'dispatch', c.line, { site, rule: 'c.handler-table', key: h.key,
+        evidence: `${c.file}:${c.line} calls the ${t.name} row for "${h.key}" (${t.file}:${h.line})` });
+      links.push({ from: c.from, table: t.name, file: c.file, line: c.line, handlers: t.handlers.length });
+    }
+  });
+  return { entries, claimed, tables: tables.filter(t => t.handlers.length).map(t => ({ name: t.name, file: t.file, line: t.line, rows: t.handlers.length, field: t.field || null })), dispatchers: links };
+}

package/skills/explainer-video-from-codebase/tools/rules/celery-taskiq.mjs

@@ -0,0 +1,48 @@
+/* Rule pack: Celery / Taskiq.
+   - consumers: `@<broker>.task(task_name=K)` / `@shared_task` -> a `queue-consumer` entry keyed K, or `scheduled`
+     when the decorator carries `schedule=`;
+   - producers: `.kiq()/.delay()/.apply_async()` on a consumer, `send_task("K")`, `AsyncKicker(task_name="K")` ->
+     a `queue` crossing to the consumer. A kicker whose name is not a literal makes its function a dispatcher, which
+     the registry pack uses. */
+import { addEdge } from '../lang/python.mjs';
+
+export function consumerEntry(py, d) {
+  if (!/(\.|^)(task|shared_task)$/.test(d.expr)) return null;
+  const s = py.symbols.get(d.id);
+  return { kind: d.kwNames.includes('schedule') ? 'scheduled' : 'queue-consumer', id: d.id,
+    key: d.kwArgs.task_name || d.kwArgs.name || d.strArgs[0] || s.name, line: d.line, file: s.file, rule: 'celery-taskiq.consumer' };
+}
+
+const literal = a => a && a.type === 'string' ? a.s : null;
+
+export function linkProducers(py, R, entries) {
+  const consumerByKey = new Map(entries.filter(e => e.kind === 'queue-consumer' || e.kind === 'scheduled').map(e => [e.key, e.id]));
+  const consumers = new Set(consumerByKey.values());
+  const kickers = [];
+  for (const c of py.rawCalls) {
+    if (c.attr === 'send_task' && literal(c.args[0]) != null) kickers.push({ fn: c.from, key: literal(c.args[0]), line: c.line });
+    if (/(^|\.)AsyncKicker$|(^|\.)kicker$/.test(c.expr)) {
+      const kw = c.args.find(a => a.kw === 'task_name');
+      const key = kw ? kw.s : literal(c.args[0]);
+      kickers.push({ fn: c.from, key, dynamic: key == null, line: c.line });
+    }
+  }
+  const links = [], dispatchers = new Set();
+  const sym = id => py.symbols.get(id);
+  const sameNameInBases = id => { const s = sym(id); return s?.cls ? R.mro(s.cls).slice(1).map(b => py.classes.get(b)?.methods.get(s.name)).filter(Boolean) : []; };
+  for (const k of kickers) {
+    if (k.key != null) { const consumer = consumerByKey.get(k.key);
+      if (consumer) { addEdge(py, k.fn, consumer, 'queue', k.line, { rule: 'taskiq.literal-key', evidence: `${sym(k.fn)?.file}:${k.line} kicks "${k.key}"` }); links.push({ fn: k.fn, key: k.key }); } }
+    else { dispatchers.add(k.fn); for (const m of sameNameInBases(k.fn)) dispatchers.add(m); }
+  }
+  // methods that call a dispatcher in the same class count as dispatchers too (enqueue_batch -> enqueue)
+  const rev = new Map();
+  for (const e of py.edges) if (!e.rule && /^(static|virtual|dispatch|ctor)$/.test(e.kind)) (rev.get(e.to) || rev.set(e.to, new Set()).get(e.to)).add(e.from);
+  for (const d of [...dispatchers]) for (const caller of rev.get(d) || []) if (sym(caller)?.cls && sym(caller)?.cls === sym(d)?.cls) dispatchers.add(caller);
+  for (const d of [...dispatchers]) for (const m of sameNameInBases(d)) dispatchers.add(m);
+  for (const c of py.rawCalls) if (c.attr && /^(kiq|delay|apply_async)$/.test(c.attr) && !c.obj.includes('(')) {
+    const r = R.resolveName(c.obj.split('.')[0], c);
+    if (r?.id && consumers.has(r.id)) { addEdge(py, c.from, r.id, 'queue', c.line, { rule: `taskiq.${c.attr}` }); links.push({ fn: c.from, direct: r.id }); }
+  }
+  return { links, dispatchers, consumerByKey };
+}

package/skills/explainer-video-from-codebase/tools/rules/click-typer.mjs

@@ -0,0 +1,6 @@
+/* Rule pack: click / typer. Only a command decorator makes a CLI entry; `@click.option` and friends decorate
+   the same function and must not make one entry each. */
+export function commandEntry(py, d, entries) {
+  if (!/(^|\.)command$|^app\.callback$/.test(d.expr) || entries.some(e => e.kind === 'cli' && e.id === d.id)) return null;
+  return { kind: 'cli', id: d.id, line: d.line, file: py.symbols.get(d.id).file, rule: 'click-typer.command' };
+}

package/skills/explainer-video-from-codebase/tools/rules/express.mjs

@@ -0,0 +1,72 @@
+/* Rule pack: Express. An app is `express()` (the default import of 'express' or its `require`); a router is
+   `express.Router()` or `Router()` from 'express' (a module-level variable, imported or not, a function's local, or a
+   parameter annotated `Router` / `Express` / `Application`). `<app|router>.<method>(path, ...handlers)` and
+   `<router>.route(path).<method>(...handlers)` make an `http` entry at the last handler; each handler before it is
+   middleware, linked from that handler (`framework`, express.middleware). `<app|router>.use([prefix,] router)` mounts
+   a router (a variable, a `require`, or a call of a function that returns one by name); the prefix is folded like a
+   route path (a const works). A route's path is every mount prefix up the chain, then its own; `:id` is written
+   `{id}`. A function handed to a registration is the router's to run, so it is never a call from the registering code. */
+import { addTsEdge, foldString } from '../lang/typescript.mjs';
+
+const METHOD = /^(get|post|put|patch|delete|del|all|options|head)$/;
+const EXPRESS = /^express(\.default)?(\.Router)?$|^express\.(Express|Application|Router)$/;
+
+export function expressRoutes(ts, R) {
+  const isExpress = (spec, sc) => { if (!spec) return false; const r = R.resolveExpr(spec.expr, sc); return !!(r?.ext && EXPRESS.test(r.ext)); };
+  // the router an expression names, as `<owner>#<name>`, or null
+  const routerOf = (name, c) => {
+    if (!/^[\w$]+$/.test(name)) return null;
+    if (c.types?.has(name)) return isExpress(c.types.get(name), c) ? `${c.from}#${name}` : null;
+    const r = R.resolveName(name, c);
+    return r?.var && isExpress(r.var, r.var) ? `${r.in}#${r.name}` : null;
+  };
+  const argRouter = (a, c) => {
+    if (a.name) return routerOf(a.name, c);
+    const req = /^require\(\s*["'`]([^"'`]+)["'`]\s*\)$/.exec(a.text);
+    if (req) { const mod = R.resolveModule(req[1], c.module); const r = mod && R.exportOf(mod, '*'); return r?.var && isExpress(r.var, r.var) ? `${r.in}#${r.name}` : null; }
+    const callee = a.type === 'call_expression' && /^([\w$]+(?:\.[\w$]+)*)\s*\(/.exec(a.text);
+    const fn = callee && R.resolveExpr(callee[1], c)?.id;
+    for (const ret of fn ? ts.returns.filter(x => x.fn === fn && x.kind === 'name') : []) { const r = routerOf(ret.name, { ...ret, from: fn }); if (r) return r; }
+    return null;
+  };
+  const handlerOf = (a, c) => {
+    if (a.fnId) return a.fnId;
+    if (a.name || a.member) { const r = R.resolveExpr(a.name || a.member, c); const s = r?.id && ts.symbols.get(r.id); return s && (s.kind === 'function' || s.kind === 'method') ? r.id : null; }
+    return null;
+  };
+  const pathOf = (a, c) => a?.ir ? foldString(ts, R, a.ir, c).s : null;
+  const mounts = new Map(), regs = [], claimed = new Set();
+  ts.rawCalls.forEach((c, i) => {
+    if (!c.attr) return;
+    const chained = c.routeChain || null;
+    const owner = chained ? routerOf(chained.owner, c) : c.obj ? routerOf(c.obj, c) : null;
+    if (!owner) return;
+    if (c.attr === 'use') {
+      const first = c.args[0] && !argRouter(c.args[0], c) ? pathOf(c.args[0], c) : null;
+      const prefix = first?.startsWith('/') ? first : '';
+      for (const a of c.args) { const child = argRouter(a, c); if (child && child !== owner && !mounts.has(child)) mounts.set(child, { parent: owner, prefix }); }
+      claimed.add(i);
+      return;
+    }
+    if (!METHOD.test(c.attr)) return;
+    const path = chained ? (chained.path ? foldString(ts, R, chained.path, c).s : null) : pathOf(c.args[0], c);
+    if (path == null || !path.startsWith('/') && path !== '*') return;
+    const handlers = (chained ? c.args : c.args.slice(1)).map(a => handlerOf(a, c)).filter(Boolean);
+    claimed.add(i);
+    if (!handlers.length) return;
+    regs.push({ owner, method: c.attr === 'all' ? '*' : c.attr === 'del' ? 'DELETE' : c.attr.toUpperCase(), path, handler: handlers.at(-1), middleware: handlers.slice(0, -1), file: c.file, line: c.line });
+  });
+  const fullPath = (owner, path, seen = new Set()) => {
+    let p = path;
+    for (let o = owner; mounts.has(o) && !seen.has(o); o = mounts.get(o).parent) { seen.add(o); p = `${mounts.get(o).prefix.replace(/\/$/, '')}${p.startsWith('/') ? '' : '/'}${p}`; }
+    p = p.replace(/\/{2,}/g, '/').replace(/:(\w+)\??/g, '{$1}');
+    return p.length > 1 ? p.replace(/\/$/, '') : p;
+  };
+  const routes = [];
+  for (const g of regs) {
+    const path = fullPath(g.owner, g.path);
+    routes.push({ kind: 'http', method: g.method, path, id: g.handler, file: g.file, line: g.line, rule: 'express' });
+    for (const mw of g.middleware) addTsEdge(ts, g.handler, mw, 'framework', g.line, { rule: 'express.middleware', evidence: `${g.file}:${g.line} ${g.method} ${path} runs ${ts.symbols.get(mw)?.name} first` });
+  }
+  return { routes, claimed, mounts: [...mounts].map(([child, m]) => ({ child, parent: m.parent, prefix: m.prefix })) };
+}

package/skills/explainer-video-from-codebase/tools/rules/fastapi.mjs

@@ -0,0 +1,99 @@
+/* Rule pack: FastAPI / Starlette.
+   - routes: `@<router>.get/post/…(path)` where <router> is an APIRouter or FastAPI app (a module-level variable,
+     imported or not, or a function's local or parameter, built by `APIRouter()` / `FastAPI()`, an in-repo subclass
+     of either, or a factory returning one) -> an `http` entry. Its path is every `include_router(r, prefix=)` up the include chain (at module level
+     or inside an app factory) + `APIRouter(prefix=)` + the decorator path;
+   - DI: `p: T = Depends(provider)` and `Alias = Annotated[T, Depends(provider)]` -> handler links to provider;
+     a parameter typed by such an alias is narrowed to whatever the provider returns. */
+import { addEdge } from '../lang/python.mjs';
+
+const simpleType = t => {
+  const s = t.replace(/^["']|["']$/g, '').replace(/\s*\|\s*None\b|\bNone\s*\|\s*/g, '').replace(/^Optional\[(.*)\]$/, '$1').trim();
+  return /^[A-Za-z_][\w.]*$/.test(s) ? s : null;
+};
+
+// before call resolution: aliases must be known for receivers typed by them
+export function registerAliases(py) {
+  for (const a of py.moduleAssigns) {
+    if (!a.sub || !/(^|\.)Annotated$/.test(a.sub.value)) continue;
+    const dep = a.sub.items.find(x => x.type === 'call' && /(^|\.)Depends$/.test(x.fn));
+    if (!dep || !a.sub.items[0]) continue;
+    const aid = `${a.module}:${a.name}`;
+    py.modules.get(a.module).defs.set(a.name, aid);
+    const provider = /^[\w.]+\(\s*([^,)]+)/.exec(dep.text)?.[1].trim() ?? null;
+    py.typeAliases.set(aid, { type: simpleType(a.sub.items[0].text), provider, line: a.line, module: a.module, imports: a.imports, locals: new Map() });
+  }
+}
+
+const ROUTER = /(^|\.)(APIRouter|FastAPI)$/;
+
+// a router's prefix as mounted: each include_router prefix up the chain, then its own APIRouter(prefix=)
+export function routePrefixes(py, R) {
+  const routerClass = id => R.mro(id).some(c => py.classes.get(c).baseExprs.some(b => ROUTER.test(b) || ROUTER.test(R.resolveExpr(b, py.classes.get(c))?.ext || '')));
+  const makesRouter = (expr, sc) => { if (!expr) return false; if (ROUTER.test(expr)) return true; const r = R.resolveExpr(expr, sc);
+    return !!(r?.ext && ROUTER.test(r.ext)) || !!(r?.id && (py.classes.has(r.id) ? routerClass(r.id) : R.factoryReturns(r.id).some(x => x.ext && ROUTER.test(x.ext)))); };
+  const routers = new Map();   // `module:name` (or `fn#name` for a local) -> own prefix
+  for (const a of py.moduleAssigns) if (a.fn && makesRouter(a.fn, a)) {
+    const kw = a.args.find(x => x.kw === 'prefix');
+    routers.set(`${a.module}:${a.name}`, kw?.s || '');
+  }
+  const moduleRouter = (name, sc, depth = 0) => {   // a module-level router named in scope, followed through imports
+    if (sc.locals?.has(name)) return null;
+    if (routers.has(`${sc.module}:${name}`)) return `${sc.module}:${name}`;
+    const t = sc.imports.get(name);
+    if (!t?.from || depth > 4) return null;
+    const mod = R.findModule(t.from, t.in), M = py.modules.get(mod);
+    return M ? moduleRouter(t.name, { imports: M.imports, module: mod }, depth + 1) : null;
+  };
+  const routerOf = (expr, sc, fn) => {   // `router`, `items.router`, an imported router, or a local / parameter
+    const parts = expr.split('.');
+    if (parts.length === 1) {
+      const spec = sc.types?.get(expr);
+      if (fn && spec?.expr && makesRouter(spec.expr, sc)) return `${fn}#${expr}`;
+      return moduleRouter(expr, sc);
+    }
+    const r = R.resolveName(parts[0], sc);
+    if (!r?.module) return null;
+    const id = `${[r.module, ...parts.slice(1, -1)].join('.')}:${parts.at(-1)}`;
+    return routers.has(id) ? id : null;
+  };
+  const includes = new Map();   // router -> { parent, prefix }, the first include_router of it
+  for (const c of py.rawCalls) if (c.attr === 'include_router' && c.args[0] && c.args[0].type !== 'keyword_argument') {
+    const parent = routerOf(c.obj, c, c.top ? null : c.from), child = routerOf(c.args[0].text, c, c.top ? null : c.from);
+    if (parent && child && !includes.has(child)) includes.set(child, { parent, prefix: c.args.find(x => x.kw === 'prefix')?.s || '' });
+  }
+  const mounted = (id, seen = new Set()) => { if (seen.has(id)) return ''; seen.add(id);
+    const inc = includes.get(id); return (inc ? mounted(inc.parent, seen) + inc.prefix : '') + (routers.get(id) || ''); };
+  // a decorator's route prefix, or null when its receiver is not a router (`@mock.patch(…)` is no route)
+  return d => { const id = routerOf(d.expr.slice(0, d.expr.lastIndexOf('.')), d, d.fn); return id ? mounted(id) : null; };
+}
+
+const HTTP = /\.(get|post|put|patch|delete|api_route|websocket)$/;
+export function routeEntry(py, d, prefixOf) {
+  if (!HTTP.test(d.expr)) return null;
+  const prefix = prefixOf(d);
+  if (prefix == null) return null;
+  const s = py.symbols.get(d.id);
+  return { kind: 'http', id: d.id, method: d.expr.split('.').pop().toUpperCase(), path: prefix + (d.strArgs[0] || ''),
+    line: d.line, file: s.file, rule: 'fastapi.route' };
+}
+
+export function linkDepends(py, R) {
+  const links = [];
+  const file = id => py.symbols.get(id)?.file;
+  for (const p of py.annotParams) {
+    const r = R.resolveExpr(p.annot, p); if (!r?.id || !py.typeAliases.has(r.id)) continue;
+    const a = py.typeAliases.get(r.id); const pr = a.provider ? R.resolveExpr(a.provider, a) : null;
+    if (!pr?.id) continue;
+    addEdge(py, p.fn, pr.id, 'framework', p.line, { rule: 'fastapi.Depends', evidence: `${file(p.fn)}:${p.line} ${p.param}: ${p.annot} = Annotated[${a.type}, Depends(${a.provider})] (${py.modules.get(a.module)?.file}:${a.line})` });
+    links.push({ fn: p.fn, provider: pr.id, param: p.param, via: p.annot });
+  }
+  for (const d of py.paramDefaults) {
+    if (!/(^|\.)Depends$/.test(d.call) || !d.a0) continue;
+    const r = R.resolveExpr(d.a0, d);
+    if (!r?.id) continue;
+    addEdge(py, d.fn, r.id, 'framework', d.line, { rule: 'fastapi.Depends', evidence: `${file(d.fn)}:${d.line} ${d.param}=Depends(${d.a0})` });
+    links.push({ fn: d.fn, provider: r.id, param: d.param });
+  }
+  return links;
+}