explainer-video 0.0.0-stage → 0.4.0

package/skills/explainer-video-from-codebase/tools/rules/js-http-client.mjs

@@ -0,0 +1,111 @@
+/* Rule pack: frontend and Node HTTP clients. `fetch(url, { method })` (the global, not an in-repo function of that
+   name), `axios.get/post/…(url)`, `axios(config)` / `axios.request(config)`, `ky.get/…(url)` and `ky(url, { method })`,
+   and instances made by `axios.create({ baseURL })` or `ky.create/extend({ prefixUrl })`, whose base is prefixed.
+   The URL is folded to a string (B15): string and template literals, `+`, and identifiers or object members that
+   name a const, here or imported; `process.env.X ?? '/api'` folds to its default; what cannot be known is `{}`.
+   Any scheme://host is dropped. The path is matched against every route the repo serves, in any language
+   (FastAPI, Express, Next.js): a placeholder matches a route parameter, and the route with the most literal
+   segments wins. A method that cannot be folded links only when every method the path serves leads to one handler;
+   otherwise the call stays unlinked, with why (`unlinked`). A URL whose leading base could not be folded is matched by its tail instead, only when one route
+   has that tail more literally than every other (`match: "suffix"`). A match is an `http` crossing from the caller to the route handler. */
+import { addTsEdge, foldString, constOf } from '../lang/typescript.mjs';
+
+const VERB = /^(get|post|put|patch|delete|head|options)$/;
+const segsOf = p => p.replace(/\?.*$/, '').split('/').filter(Boolean);
+const isParam = s => /^\{[^}]+\}$/.test(s);
+
+// does a route (its segments) answer a call path (its segments, `{}` where unknown)?
+const fits = (rs, cs) => rs.length === cs.length && rs.every((r, i) => isParam(r) ? cs[i] !== '' : r === cs[i]);
+const literal = rs => rs.filter(s => !isParam(s)).length;
+
+// the route `best` picks among those serving the method (`best` gives [] for none, [route], or the routes that tie);
+// when the method is unknown, the one handler every method the routes serve would pick, with no tie for any of them,
+// else { ambiguous: the routes it could be }
+function byMethod(routes, method, best) {
+  const serving = m => routes.filter(r => r.method === '*' || r.method === m);
+  if (method) { const c = best(serving(method)); return { route: c.length === 1 ? c[0] : null }; }
+  const picks = [...new Set(routes.map(r => r.method))].map(m => best(serving(m))), all = picks.flat();
+  if (picks.every(c => c.length <= 1) && new Set(all.map(r => r.id)).size <= 1) return { route: all[0] || null };
+  return { route: null, ambiguous: [...new Set(all.map(r => `${r.method} ${r.path}`))].sort() };
+}
+
+export function matchRoute(routes, method, path, { suffix = false } = {}) {
+  const cs = segsOf(path);
+  const result = (r, match) => r.route ? { route: r.route, match } : r.ambiguous ? { route: null, ambiguous: r.ambiguous } : null;
+  const exact = byMethod(routes, method, rs => rs.filter(r => fits(r.segs, cs)).sort((a, b) => literal(b.segs) - literal(a.segs)).slice(0, 1));
+  if (exact.route || exact.ambiguous || !suffix || !cs.some(s => s !== '{}')) return result(exact, 'exact');
+  // the tail match must be unambiguous: one route, or one with more literal segments in its tail than any other
+  const tailLit = r => literal(r.segs.slice(r.segs.length - cs.length));
+  const tailOf = rs => { const tail = rs.filter(r => r.segs.length > cs.length && fits(r.segs.slice(r.segs.length - cs.length), cs)).sort((a, b) => tailLit(b) - tailLit(a));
+    return tail.filter(r => tailLit(r) === tailLit(tail[0])); };
+  return result(byMethod(routes, method, tailOf), 'suffix');
+}
+
+export function routeTable(httpRoutes) {
+  return httpRoutes.map(e => ({ ...e, segs: segsOf(e.path.replace(/\{\*?(\w+)\.{0,3}\}/g, '{$1}')) }));
+}
+
+export function linkHttpCalls(ts, R, httpRoutes) {
+  const routes = routeTable(httpRoutes);
+  const calls = [];
+  const extOf = (name, sc) => /^[\w$]+$/.test(name) ? R.resolveName(name, sc)?.ext || null : null;
+  // an axios / ky instance: a variable made by axios.create({ baseURL }) or ky.create/extend({ prefixUrl })
+  const instanceOf = (name, c) => {
+    const spec = c.types?.get(name) || (() => { const r = R.resolveName(name, c); return r?.var ? r.var : null; })();
+    if (!spec || spec.t !== 'call') return null;
+    const m = /^([\w$]+)\.(create|extend)$/.exec(spec.expr);
+    const ext = m && extOf(m[1], spec.module ? spec : c);
+    if (!ext || !/^(axios|ky)$/.test(ext)) return null;
+    const cfg = spec.a0?.k === 'obj' ? spec.a0.pairs : {};
+    const baseIr = cfg.baseURL || cfg.prefixUrl || cfg.prefixURL;
+    const base = baseIr ? foldString(ts, R, baseIr, { module: spec.module || c.module, consts: spec.module === c.module ? c.consts : null }) : null;
+    return { client: ext, base };
+  };
+  // the method an options / config argument sets: GET when there is none or it sets none, null (any) when it cannot be known
+  const methodOf = (arg, sc) => {
+    if (!arg) return 'GET';
+    let o = arg, osc = sc;
+    if (arg.k === 'id') { const local = sc.consts?.get(arg.name), found = local ? null : constOf(ts, R, arg.name, sc.module);
+      o = local || found?.ir; if (found) osc = { module: found.module, consts: null }; }
+    if (o?.k !== 'obj') return null;
+    if (!o.pairs.method) return o.pairs['...'] ? null : 'GET';
+    const m = foldString(ts, R, o.pairs.method, osc).s;
+    return /^[a-z]+$/i.test(m) ? m.toUpperCase() : null;
+  };
+  for (const c of ts.rawCalls) {
+    if (c.jsx || c.isNew) continue;
+    let client = null, method = null, urlIr = null, base = null;
+    const a0 = c.args[0]?.ir, a1 = c.args[1]?.ir;
+    if (!c.attr && /^(fetch|window\.fetch|globalThis\.fetch)$/.test(c.expr) && !R.resolveName('fetch', c)?.id) { client = 'fetch'; urlIr = a0; method = methodOf(a1, c); }
+    else if (!c.attr && /^(axios|ky)$/.test(extOf(c.expr, c) || '')) {
+      client = extOf(c.expr, c);
+      if (a0?.k === 'obj') { urlIr = a0.pairs.url; method = methodOf(a0, c); } else { urlIr = a0; method = methodOf(a1, c); }
+    } else if (c.attr && c.obj && /^[\w$]+$/.test(c.obj)) {
+      const ext = extOf(c.obj, c), inst = ext ? null : instanceOf(c.obj, c);
+      const lib = /^(axios|ky)$/.test(ext || '') ? ext : inst?.client;
+      if (!lib) continue;
+      if (VERB.test(c.attr)) { client = lib; method = c.attr.toUpperCase(); urlIr = a0; }
+      else if (c.attr === 'request' && a0?.k === 'obj') { client = lib; method = methodOf(a0, c); urlIr = a0.pairs.url; }
+      else continue;
+      base = inst?.base || null;
+    } else continue;
+    if (!urlIr) continue;
+    const f = foldString(ts, R, urlIr, c);
+    let url = f.s.replace(/^[a-z][\w+.-]*:\/\/[^/]*/i, '');
+    let baseStr = base ? base.s.replace(/^[a-z][\w+.-]*:\/\/[^/]*/i, '') : '';
+    if (/^[a-z][\w+.-]*:\/\//i.test(f.s)) baseStr = '';   // an absolute URL ignores the instance's base
+    const unknownLead = url.startsWith('{}') || (!!base && baseStr.startsWith('{}'));
+    url = `${baseStr.replace(/^\{\}/, '').replace(/\/$/, '')}${baseStr && !url.startsWith('/') && !url.startsWith('{}') ? '/' : ''}${url.replace(/^\{\}/, '')}`;
+    if (!url.startsWith('/')) { if (!unknownLead) continue; url = '/' + url; }
+    const path = url.replace(/\?.*$/, '').replace(/#.*$/, '');
+    const m = matchRoute(routes, method, path, { suffix: unknownLead }), hit = m?.route ? m : null;
+    const folded = [...new Set([...f.acc.folded, ...(base?.acc.folded || [])])], env = [...new Set([...f.acc.env, ...(base?.acc.env || [])])];
+    const group = ts.modules.get(c.module)?.group;
+    calls.push({ from: c.from, file: c.file, line: c.line, client, method, url: path, handler: hit?.route.id || null, group,
+      ...(m?.ambiguous ? { unlinked: `the method is unknown and the path is served by ${m.ambiguous.join(', ')}` } : {}),
+      ...(hit && hit.match !== 'exact' ? { match: hit.match } : {}), ...(folded.length ? { folded } : {}), ...(env.length ? { env } : {}) });
+    if (hit) addTsEdge(ts, c.from, hit.route.id, 'http', c.line, { rule: 'js.http-client', group, evidence: `${c.file}:${c.line} ${method || '*'} ${path}${folded.length ? ` (folded ${folded.join(', ')})` : ''}${hit.match === 'suffix' ? ` (tail match: ${hit.route.method} ${hit.route.path})` : ''}`,
+      ...(hit.match !== 'exact' ? { match: hit.match } : {}) });
+  }
+  return calls;
+}

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

@@ -0,0 +1,53 @@
+/* Rule pack: Next.js, read from the file layout of an app that depends on `next` (a package.json naming it, or a
+   next.config file beside one). App Router: a `page.*` file under `app/` is a `ui-route` at its default export,
+   and a `route.*` file an `http` entry per exported GET/POST/PUT/PATCH/DELETE/HEAD/OPTIONS. Pages Router:
+   a file under `pages/api/` is an `http` entry (any method) at its default export, every other page a `ui-route`. Route groups
+   `(x)` and slots `@x` add no segment, `_x` folders are private; `[id]` is `:id` in a UI path and `{id}` in an
+   HTTP one; `[...x]` and `[[...x]]` catch the rest. `src/app` and `src/pages` count as well. */
+import { posix } from 'node:path';
+
+const HTTP_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS'];
+const SPECIAL_PAGE = /^_(app|document|error)$/;
+
+export function nextRoots(packageJsons, files) {
+  const roots = new Set();
+  for (const { dir, json } of packageJsons) if (json && ['dependencies', 'devDependencies', 'peerDependencies'].some(k => json[k]?.next)) roots.add(dir);
+  for (const f of files) if (/(^|\/)next\.config\.(js|mjs|cjs|ts|mts)$/.test(f)) roots.add(posix.dirname(f) === '.' ? '' : posix.dirname(f));
+  return [...roots].sort();
+}
+
+export function nextEntries(ts, R, roots) {
+  const entries = [];
+  const segs = (parts, http) => {
+    const out = [];
+    for (const s of parts) {
+      if (/^\(.*\)$/.test(s) || s.startsWith('@')) continue;
+      const m = /^\[\[?\.\.\.(\w+)\]\]?$/.exec(s) || /^\[(\w+)\]$/.exec(s);
+      out.push(m ? (s.includes('...') ? (http ? `{${m[1]}}` : '*') : http ? `{${m[1]}}` : `:${m[1]}`) : s);
+    }
+    return '/' + out.join('/');
+  };
+  for (const root of roots) {
+    const at = d => root ? `${root}/${d}` : d;
+    for (const [rel] of ts.modules) {
+      for (const base of [at('app'), at('src/app')]) {
+        if (!rel.startsWith(base + '/')) continue;
+        const parts = rel.slice(base.length + 1).split('/'), file = parts.pop(), name = file.replace(/\.[^.]+$/, '');
+        if (parts.some(p => p.startsWith('_'))) continue;
+        if (name === 'page') { const r = R.exportOf(rel, 'default'); if (r?.id) entries.push({ kind: 'ui-route', path: segs(parts, false), id: r.id, file: rel, line: ts.symbols.get(r.id)?.start, rule: 'nextjs.app' }); }
+        if (name === 'route') for (const m of HTTP_METHODS) { const r = R.exportOf(rel, m); if (r?.id) entries.push({ kind: 'http', method: m, path: segs(parts, true), id: r.id, file: rel, line: ts.symbols.get(r.id)?.start, rule: 'nextjs.route' }); }
+      }
+      for (const base of [at('pages'), at('src/pages')]) {
+        if (!rel.startsWith(base + '/')) continue;
+        const parts = rel.slice(base.length + 1).split('/'), file = parts.pop(), name = file.replace(/\.[^.]+$/, '');
+        if (SPECIAL_PAGE.test(name) || parts.some(p => p.startsWith('_'))) continue;
+        const all = name === 'index' ? parts : [...parts, name];
+        const r = R.exportOf(rel, 'default');
+        if (!r?.id) continue;
+        if (all[0] === 'api') entries.push({ kind: 'http', method: '*', path: segs(all, true), id: r.id, file: rel, line: ts.symbols.get(r.id)?.start, rule: 'nextjs.api' });
+        else entries.push({ kind: 'ui-route', path: segs(all, false), id: r.id, file: rel, line: ts.symbols.get(r.id)?.start, rule: 'nextjs.pages' });
+      }
+    }
+  }
+  return entries;
+}

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

@@ -0,0 +1,49 @@
+/* Rule pack: process spawn. `subprocess.Popen/run/call/check_*([...])` or `asyncio.create_subprocess_exec(...)`
+   with a literal argv (inline, or a local list) that names an in-repo app starts that app's entries: a `spawn`
+   crossing from the spawning function to them.
+     uvicorn mod:app            -> the entries defined in the app's module (its lifespan)
+     taskiq worker mod:broker   -> every queue consumer          celery -A mod worker -> every queue consumer
+     taskiq scheduler mod:x     -> every scheduled task          celery -A mod beat   -> every scheduled task
+     python -m pkg              -> pkg's `__main__` entry
+   The app module is looked up as the spawned process would find it from the spawning file: its directory, then each
+   parent, then as an absolute import from that file (the repo root, then the package roots). */
+import { dirname } from 'node:path';
+import { addEdge } from '../lang/python.mjs';
+
+const SUBPROCESS = /^(Popen|run|call|check_call|check_output)$/;
+// `subprocess.run(…)`, `asyncio.create_subprocess_exec(…)`, or the bare name imported from either module
+const isSpawn = c => c.attr ? (c.obj === 'subprocess' && SUBPROCESS.test(c.attr)) || (c.obj === 'asyncio' && c.attr === 'create_subprocess_exec')
+  : (c.imports.get(c.expr)?.from === 'subprocess' && SUBPROCESS.test(c.expr)) || (c.imports.get(c.expr)?.from === 'asyncio' && c.expr === 'create_subprocess_exec');
+
+function argvOf(py, c) {
+  const items = /create_subprocess_exec$/.test(c.expr) ? c.args.filter(a => a.type !== 'keyword_argument')
+    : c.args[0]?.items ?? (c.args[0]?.type === 'identifier' ? py.fnLists.get(c.from)?.[c.args[0].text] : null);
+  return items ? items.map(a => (a.type === 'string' ? a.s : null)) : null;
+}
+
+export function linkSpawns(py, R, entries) {
+  const spawns = [];
+  const appModule = spec => spec && spec.includes(':') ? spec.split(':')[0] : spec;
+  const near = (c, name) => { const dirs = dirname(c.file) === '.' ? [] : dirname(c.file).split('/');
+    return [...dirs.map((_, i) => [...dirs.slice(0, dirs.length - i), name].join('.')), R.findModule(name, c.module)].filter(Boolean); };
+  for (const c of py.rawCalls) {
+    if (!isSpawn(c)) continue;
+    const argv = argvOf(py, c);
+    if (!argv) continue;
+    const at = w => argv.indexOf(w);
+    let targets = [], what = null;
+    if (at('uvicorn') !== -1) { const spec = appModule(argv[at('uvicorn') + 1]); what = `uvicorn ${argv[at('uvicorn') + 1]}`;
+      const mod = spec && near(c, spec).find(m => py.modules.has(m));
+      targets = mod ? entries.filter(e => e.file && py.modules.get(mod).file === e.file) : []; }
+    else if (at('taskiq') !== -1 && argv[at('taskiq') + 1] === 'worker') { what = `taskiq worker ${argv[at('taskiq') + 2]}`; targets = entries.filter(e => e.kind === 'queue-consumer'); }
+    else if (at('taskiq') !== -1 && argv[at('taskiq') + 1] === 'scheduler') { what = `taskiq scheduler ${argv[at('taskiq') + 2]}`; targets = entries.filter(e => e.kind === 'scheduled'); }
+    else if (at('celery') !== -1) { const beat = argv.includes('beat'); what = `celery ${beat ? 'beat' : 'worker'}`; targets = entries.filter(e => e.kind === (beat ? 'scheduled' : 'queue-consumer')); }
+    else if (at('-m') !== -1 && argv[at('-m') + 1]) { what = `python -m ${argv[at('-m') + 1]}`;
+      const mod = near(c, argv[at('-m') + 1]).find(m => py.modules.has(`${m}.__main__`) || py.modules.has(m));
+      targets = mod ? entries.filter(e => e.kind === 'main' && (e.id === `${mod}.__main__:<main>` || e.id === `${mod}:<main>`)) : []; }
+    if (!what) continue;
+    spawns.push({ from: c.from, file: c.file, line: c.line, argv: what, targets: targets.map(e => e.id) });
+    for (const e of targets) addEdge(py, c.from, e.id, 'spawn', c.line, { rule: 'process-spawn', evidence: `${c.file}:${c.line} spawns ${what}` });
+  }
+  return spawns;
+}

package/skills/explainer-video-from-codebase/tools/rules/py-http-client.mjs

@@ -0,0 +1,26 @@
+/* Rule pack: Python HTTP clients (httpx / requests / aiohttp / a test client). `<client>.get/post/…(url)` where url
+   is a string or f-string literal, or a local bound to one: a leading `{base}` and any scheme://host are dropped,
+   then the path is matched against the mined route table. A match is an `http` crossing to the route handler. */
+import { addEdge } from '../lang/python.mjs';
+
+export const routeRe = e => new RegExp('^' + e.path.replace(/\{[^}]+\}/g, '[^/]+') + '$');
+
+export function linkHttpCalls(py, entries) {
+  const routes = entries.filter(e => e.kind === 'http').map(e => ({ e, re: routeRe(e) }));
+  const calls = [];
+  for (const c of py.rawCalls) {
+    const a0 = c.args[0];
+    if (!c.attr || !/^(get|post|put|patch|delete)$/.test(c.attr) || !a0) continue;
+    const lit = a0.type === 'string' ? a0.text : a0.type === 'identifier' ? py.fnAlias.get(c.from)?.[a0.text] : null;
+    if (!lit || !/^[rbfRBF]*["']/.test(lit)) continue;
+    const url = lit.replace(/^[rbfRBF]*("""|'''|"|')/, '').replace(/("""|'''|"|')$/, '').replace(/\{[^}]*\}/g, '{}').replace(/^\{\}/, '').replace(/^https?:\/\/[^/]+/, '');
+    if (!url.startsWith('/')) continue;
+    const path = url.replace(/\?.*$/, '').replace(/\{\}/g, 'X');
+    const method = c.attr.toUpperCase();
+    const hit = routes.find(r => r.e.method === method && r.re.test(path))?.e;
+    const group = py.modules.get(c.module)?.group;
+    calls.push({ from: c.from, file: c.file, line: c.line, method, url, handler: hit?.id || null, group });
+    if (hit) addEdge(py, c.from, hit.id, 'http', c.line, { rule: 'py.http-client', group, evidence: `${c.file}:${c.line} ${method} ${url}` });
+  }
+  return calls;
+}

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

@@ -0,0 +1,107 @@
+/* Rule pack: pytest (and unittest-style test classes, and unittest.mock targets).
+   - tests: `test*` at module level, or `test*` methods of a `Test*` / `TestCase` class, in a test-group file;
+   - fixtures: `@pytest.fixture` / `@pytest_asyncio.fixture`; a test-side parameter named like a visible fixture (its
+     class, its module, then conftest.py in its directory and each parent) is bound to it, `autouse=True` binds to
+     every test in scope, and the fixture's returned or yielded class types the parameter;
+   - mock targets: `patch("a.b.c")` (decorator, context manager, `mocker.patch`), `patch.object(X, "m")`,
+     `monkeypatch.setattr(…)`, resolved the way `patch` looks them up. A patch started in `pytest_configure`,
+     `pytest_sessionstart` or at conftest module level is session-wide: it applies to every test under that conftest;
+   - direct test links: every edge from a test's own side (its body, fixtures, helpers, test class) into non-test
+     code, minus whatever that test mocks. */
+import { dirname } from 'node:path';
+import { addEdge } from '../lang/python.mjs';
+
+const isConftest = f => /(^|\/)conftest\.py$/.test(f);
+const inScope = (conftest, file) => { const d = dirname(conftest); return d === '.' || file.startsWith(d + '/'); };
+const SESSION_HOOK = /:(pytest_configure|pytest_sessionstart|<module>)$/;
+
+export function findTests(py, R) {
+  const isTestClass = k => /^Test/.test(k.name) || R.mro(k.id).some(c => py.classes.get(c)?.baseExprs.some(b => /(^|\.)(Async)?TestCase$/.test(b)));
+  const tests = [];
+  for (const s of py.symbols.values()) {
+    if (s.group !== 'test' || (s.kind !== 'function' && s.kind !== 'method') || s.id.includes('<locals>') || s.id.includes('<main>') || !/^test/.test(s.name)) continue;
+    if (s.cls && !isTestClass(py.classes.get(s.cls))) continue;
+    tests.push({ id: s.id, file: s.file, line: s.start, end: s.end, asserts: s.asserts, assertLines: s.assertLines });
+  }
+  return tests;
+}
+
+export function findFixtures(py) {
+  return [...py.symbols.values()].filter(s => (s.kind === 'function' || s.kind === 'method') && s.decos.some(d => /(^|\.)fixture(\(|$)/.test(d)))
+    .map(s => ({ id: s.id, name: s.name, file: s.file, line: s.start, cls: s.cls || null, autouse: s.decos.some(d => /autouse\s*=\s*True/.test(d)) }));
+}
+
+// before call resolution: a bound parameter is typed by its fixture's returns
+export function bindFixtures(py, tests, fixtures) {
+  const bindings = [];
+  const typesOf = new Map(); for (const c of py.rawCalls) if (!typesOf.has(c.from)) typesOf.set(c.from, c.types);
+  const fixtureFor = (s, p) => {
+    const cands = fixtures.filter(f => f.name === p && f.id !== s.id);
+    return cands.find(f => f.cls && f.cls === s.cls) || cands.find(f => !f.cls && f.file === s.file)
+      || cands.filter(f => !f.cls && isConftest(f.file) && inScope(f.file, s.file)).sort((a, b) => b.file.length - a.file.length)[0] || null;
+  };
+  for (const s of py.symbols.values()) if (s.group === 'test' && s.params && (s.kind === 'function' || s.kind === 'method')) {
+    for (const p of s.params) { if (p === 'self' || p === 'cls') continue; const f = fixtureFor(s, p); if (!f) continue;
+      bindings.push({ fn: s.id, param: p, fixture: f.id });
+      const t = typesOf.get(s.id); if (t && !t.has(p)) t.set(p, { t: 'returns', fn: f.id }); }
+  }
+  for (const t of tests) for (const f of fixtures.filter(x => x.autouse))
+    if (f.file === t.file || (isConftest(f.file) && inScope(f.file, t.file))) bindings.push({ fn: t.id, param: null, fixture: f.id, autouse: true });
+  return bindings;
+}
+
+export function linkFixtures(py, bindings) {
+  const s = id => py.symbols.get(id);
+  for (const b of bindings) addEdge(py, b.fn, b.fixture, 'framework', s(b.fn)?.start, { rule: b.autouse ? 'pytest.fixture.autouse' : 'pytest.fixture',
+    evidence: `${s(b.fn)?.file}: parameter ${b.param ?? '(autouse)'} -> fixture ${b.fixture.split(':').pop()} (${s(b.fixture)?.file}:${s(b.fixture)?.start})` });
+}
+
+export function mockTargets(py, R) {
+  const resolveDotted = (raw, from) => { const parts = raw.split('.');
+    for (let i = parts.length - 1; i >= 1; i--) { const mod = R.findModule(parts.slice(0, i).join('.'), from); if (!py.modules.has(mod)) continue;
+      const rest = parts.slice(i), sc = { imports: py.modules.get(mod).imports, module: mod };
+      const r = R.resolveName(rest[0], sc);
+      if (rest.length === 1) return r?.id || null;
+      if (rest.length === 2 && r?.id && py.classes.has(r.id)) return R.lookup(r.id, rest[1]);
+      return null; }
+    return null; };
+  const fileOf = fn => py.symbols.get(fn)?.file || py.modules.get(fn.split(':')[0])?.file || '';
+  const scoped = m => { const file = fileOf(m.fn); return isConftest(file) && SESSION_HOOK.test(m.fn) ? { ...m, scope: 'session', conftest: file } : m; };
+  const mocks = [];
+  for (const d of py.decorated) if (/(^|\.)patch$/.test(d.expr) && d.strArgs[0] && /\./.test(d.strArgs[0]))
+    mocks.push({ fn: d.id, raw: d.strArgs[0], target: resolveDotted(d.strArgs[0], d.module), line: d.line, how: '@patch' });
+  for (const c of py.rawCalls) {
+    const a0 = c.args[0], s0 = a0?.type === 'string' ? a0.s : null, s1 = c.args[1]?.type === 'string' ? c.args[1].s : null;
+    if ((/(^|\.)patch$/.test(c.expr) || /(^|\.)monkeypatch\.setattr$/.test(c.expr)) && s0 && /\./.test(s0))
+      mocks.push(scoped({ fn: c.from, raw: s0, target: resolveDotted(s0, c.module), line: c.line, how: c.expr.split('.').pop() }));
+    else if ((/(^|\.)patch\.object$/.test(c.expr) || /(^|\.)monkeypatch\.setattr$/.test(c.expr)) && a0 && s1) {
+      let k = null; const r = R.resolveExpr(a0.text, c); if (r?.id && py.classes.has(r.id)) k = r.id;
+      else if (c.types?.has(a0.text)) { const rc = R.receiverOf(c.types.get(a0.text), c); if (rc) k = rc.cls[0]; }
+      mocks.push(scoped({ fn: c.from, raw: `${a0.text}.${s1}`, target: k ? R.lookup(k, s1) : null, line: c.line, how: 'patch.object' }));
+    }
+  }
+  return mocks;
+}
+
+const FOLLOW = new Set(['static', 'ctor', 'framework', 'dispatch', 'queue', 'http', 'virtual']);
+export function directLinks(py, tests, fixtures, mocks) {
+  const out = new Map(); for (const e of py.edges) (out.get(e.from) || out.set(e.from, []).get(e.from)).push(e);
+  const G = id => py.symbols.get(id)?.group || (id.startsWith('ext:') ? 'ext' : 'prod');
+  const fixtureIds = new Set(fixtures.map(f => f.id));
+  const mocksIn = new Map(); for (const m of mocks) if (m.target && !m.scope) (mocksIn.get(m.fn) || mocksIn.set(m.fn, new Set()).get(m.fn)).add(m.target);
+  const session = mocks.filter(m => m.target && m.scope === 'session');
+  for (const t of tests) {
+    const side = new Set([t.id]), q = [t.id];
+    while (q.length) { const x = q.pop(); for (const e of out.get(x) || []) if (FOLLOW.has(e.kind) && G(e.to) === 'test' && !side.has(e.to)) { side.add(e.to); q.push(e.to); } }
+    const tcls = py.symbols.get(t.id)?.cls; if (tcls) side.add(tcls);
+    const mocked = new Set(session.filter(m => inScope(m.conftest, t.file)).map(m => m.target));
+    for (const s of side) for (const m of mocksIn.get(s) || []) mocked.add(m);
+    const links = new Map();
+    for (const s of side) for (const e of out.get(s) || []) {
+      if (!FOLLOW.has(e.kind) || G(e.to) === 'test' || e.to.startsWith('ext:') || mocked.has(e.to) || py.symbols.get(e.to)?.kind === 'class' || links.has(e.to)) continue;
+      links.set(e.to, { to: e.to, via: s === t.id ? 'body' : fixtureIds.has(s) ? 'fixture' : 'helper', viaId: s, kind: e.kind, ...(e.rule ? { rule: e.rule } : {}), line: e.line, ...(e.recvClass ? { recvClass: e.recvClass } : {}) });
+    }
+    t.mocked = [...mocked].sort();
+    t.direct = [...links.values()];
+  }
+}

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

@@ -0,0 +1,17 @@
+/* Rule pack: React Router, both styles. Route objects in an array (`createBrowserRouter([...])`, `useRoutes`, or any
+   route table in a file that imports react-router) with `path` or `index` and an `element`, `Component`,
+   `component` or `lazy: () => import(…)`; and `<Route path element={<X/>}>` elements, nested `<Route>`s and
+   `children` arrays joining their parents' paths. Each one is a `ui-route` entry at the component it renders (a
+   `lazy(() => import('./X'))` component is that module's default export). */
+export function uiRoutes(ts, R) {
+  const entries = [];
+  for (const d of ts.routeDefs) {
+    let r = null;
+    if (d.lazy) { const mod = R.resolveModule(d.lazy, d.file); r = mod ? R.exportOf(mod, 'default') : null; }
+    else r = R.resolveExpr(d.comp, { module: d.file, locals: null });
+    const s = r?.id && ts.symbols.get(r.id);
+    if (!s || s.kind === 'main') continue;
+    entries.push({ kind: 'ui-route', path: d.path, id: r.id, file: d.file, line: d.line, rule: d.rule, ...(d.lazy ? { lazy: d.lazy } : {}) });
+  }
+  return entries;
+}

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

@@ -0,0 +1,31 @@
+/* Rule pack: registry dispatch. A `{TypeName: "key"}` table read by a dispatcher whose task name is dynamic routes
+   each message type to the consumer keyed "key". A function that constructs TypeName links to that consumer only
+   when it (or a caller up to 3 levels) reaches a dispatcher within 3 calls, i.e. the message really is enqueued.
+   The link carries the producer's group: a test that builds a job and reaches the (mocked) dispatcher is test
+   evidence ("this test enqueues X"), never a production crossing. */
+import { addEdge } from '../lang/python.mjs';
+
+export function linkRegistry(py, dispatchers, consumerByKey) {
+  const fwd = new Map(), rev = new Map();
+  for (const e of py.edges) if (!e.rule && /^(static|virtual|dispatch|ctor)$/.test(e.kind)) {
+    (fwd.get(e.from) || fwd.set(e.from, new Set()).get(e.from)).add(e.to);
+    (rev.get(e.to) || rev.set(e.to, new Set()).get(e.to)).add(e.from); }
+  const reaches = (start, targets, depth) => { let frontier = [start]; const seen = new Set(frontier);
+    for (let d = 0; d < depth; d++) { const nx = []; for (const x of frontier) for (const y of fwd.get(x) || []) { if (targets.has(y)) return true; if (!seen.has(y)) { seen.add(y); nx.push(y); } } frontier = nx; } return false; };
+  const ancestors = (f, depth) => { const out = new Set([f]); let fr = [f];
+    for (let d = 0; d < depth; d++) { const nx = []; for (const x of fr) for (const y of rev.get(x) || []) if (!out.has(y)) { out.add(y); nx.push(y); } fr = nx; } return out; };
+  const classByName = new Map([...py.classes.values()].filter(k => k.id === `${k.module}:${k.name}`).map(k => [k.name, k.id]));
+  const groupOf = id => py.symbols.get(id)?.group || py.modules.get(id.split(':')[0])?.group || 'prod';
+  const keys = [];
+  for (const p of py.dictPairs) {
+    const consumer = consumerByKey.get(p.value), cls = classByName.get(p.key);
+    if (!consumer || !cls) continue;
+    const all = [...new Set(py.edges.filter(e => e.kind === 'ctor' && e.to === cls).map(e => e.from))];
+    const kept = all.filter(f => [...ancestors(f, 3)].some(a => reaches(a, dispatchers, 3)));
+    keys.push({ key: p.value, messageType: cls, consumer, evidence: `${p.file}:${p.line}`, candidates: all.length, kept: kept.length,
+      dropped: all.filter(f => !kept.includes(f)) });
+    for (const f of kept) addEdge(py, f, consumer, 'queue', null, { rule: 'registry', group: groupOf(f),
+      evidence: `constructs ${p.key} and reaches a dispatcher; ${p.file}:${p.line} maps it to "${p.value}"` });
+  }
+  return keys;
+}

package/skills/explainer-video-from-codebase/tools/trace/c/fmtrace-sh

@@ -0,0 +1,14 @@
+#!/bin/sh
+# fmtrace-sh — trace.mjs's recipe shell for `make` (SHELL=<this>): each recipe line runs, with the .SHELLFLAGS make
+# hands it, under the shell the Makefile itself names ($FM_TRACE_SHELL, else /bin/sh), with the coverage counters it
+# writes routed below a dir of its own (GCOV_PREFIX), so each test binary a line runs is measured on its own. Beside
+# them: the line, the dir it runs in (a sub-make's own), its exit status and a copy of its output (stdout and stderr
+# still go out apart, so a $(shell …) reads only stdout). $FM_TRACE_UNITS/order lists the dirs in the order the lines
+# ran.
+u=$(mktemp -d "$FM_TRACE_UNITS/line-XXXXXX") || exit 70
+echo "$u" >> "$FM_TRACE_UNITS/order"
+for a in "$@"; do line=$a; done
+printf '%s' "$line" > "$u/command"
+pwd -P > "$u/cwd"
+{ { { GCOV_PREFIX=$u/gcda ${FM_TRACE_SHELL:-/bin/sh} "$@"; echo $? > "$u/status"; } | tee -a "$u/output"; } 2>&1 1>&3 | tee -a "$u/output" 1>&2; } 3>&1
+exit "$(cat "$u/status")"

package/skills/explainer-video-from-codebase/tools/trace/js/fmtrace-net.cjs

@@ -0,0 +1,33 @@
+// fmtrace-net.cjs — loaded with `node --require` into every Node process of a traced JavaScript / TypeScript test run.
+// It records each outbound connect and DNS lookup the run attempts (the sandbox denies them all), so a test that failed
+// for want of the network is listed as denied by the sandbox. It changes nothing the code sees: every call goes on to
+// the real function. Written as it happens to FM_TRACE_OUT (a worker thread its runner terminates never reaches its
+// exit), tagged with the test file this process ran (FM_TRACE_FILE).
+'use strict';
+const net = require('node:net');
+const dns = require('node:dns');
+const fs = require('node:fs');
+const path = require('node:path');
+const { threadId } = require('node:worker_threads');
+
+const out = process.env.FM_TRACE_OUT;
+const seen = new Set();
+const note = s => {
+  if (seen.has(s) || seen.size >= 50) return;
+  seen.add(s);
+  if (out) try { fs.writeFileSync(path.join(out, `net-${process.pid}-${threadId}-${String(seen.size).padStart(2, '0')}.json`), JSON.stringify({ file: process.env.FM_TRACE_FILE || null, attempts: [s] })); } catch {}
+};
+
+const connect = net.Socket.prototype.connect;
+net.Socket.prototype.connect = function (...args) {
+  try {
+    const o = Array.isArray(args[0]) ? args[0][0] : args[0];
+    if (o && typeof o === 'object') note(o.path ? `connect ${o.path}` : `connect ${o.host || 'localhost'}:${o.port}`);
+    else if (typeof o === 'string' && isNaN(Number(o))) note(`connect ${o}`);
+    else note(`connect ${typeof args[1] === 'string' ? args[1] : 'localhost'}:${o}`);
+  } catch {}
+  return connect.apply(this, args);
+};
+const lookup = dns.lookup;
+dns.lookup = function (host, ...rest) { note(`getaddrinfo ${host}`); return lookup.call(this, host, ...rest); };
+

package/skills/explainer-video-from-codebase/tools/trace/js/fmtrace-srcmap.cjs

@@ -0,0 +1,41 @@
+// fmtrace-srcmap.cjs — loaded with `node --require` into every Node process and worker thread of a traced JavaScript /
+// TypeScript test run. jest and vitest compile each file they transform through node:vm (jest: new vm.Script, vitest:
+// vm.runInThisContext) with an inline source map, and Node's coverage dump records no source map for those scripts.
+// So each one's map is recorded here, in the shape of Node's own source-map-cache entry (the compiled code's line
+// lengths and the map's `mappings`), keyed by the script's file. It changes nothing the code sees: every call goes on
+// to the real function with the same arguments. Written as it happens to FM_TRACE_OUT, tagged with the test file this
+// process ran (FM_TRACE_FILE).
+'use strict';
+const vm = require('node:vm');
+const fs = require('node:fs');
+const path = require('node:path');
+const { fileURLToPath } = require('node:url');
+const { threadId } = require('node:worker_threads');
+
+const out = process.env.FM_TRACE_OUT;
+const INLINE = /\/\/# sourceMappingURL=data:application\/json[^,\n]*;base64,([A-Za-z0-9+/=]+)/y;
+let n = 0;
+const note = (code, options) => {
+  try {
+    const file = typeof options === 'string' ? options : options?.filename;
+    if (!out || typeof code !== 'string' || typeof file !== 'string' || file.includes('/node_modules/')) return;
+    // the last inline map: the runner's own wrapper may close after it
+    const at = code.lastIndexOf('//# sourceMappingURL=data:application/json');
+    if (at < 0) return;
+    INLINE.lastIndex = at;
+    const b64 = INLINE.exec(code)?.[1];
+    if (!b64) return;
+    const { mappings } = JSON.parse(Buffer.from(b64, 'base64').toString('utf8'));
+    if (typeof mappings !== 'string') return;
+    const key = file.startsWith('file://') ? fileURLToPath(file) : file;
+    fs.writeFileSync(path.join(out, `srcmap-${process.pid}-${threadId}-${n++}.json`),
+      JSON.stringify({ file: process.env.FM_TRACE_FILE || null, url: key, lineLengths: code.split('\n').map(l => l.length), data: { mappings } }));
+  } catch {}
+};
+
+const RealScript = vm.Script;
+vm.Script = class Script extends RealScript { constructor(code, options) { note(code, options); super(code, options); } };
+for (const name of ['runInThisContext', 'runInContext', 'runInNewContext']) {
+  const real = vm[name], optionsAt = name === 'runInThisContext' ? 0 : 1;
+  vm[name] = function (code, ...rest) { note(code, rest[optionsAt]); return real.call(this, code, ...rest); };
+}

package/skills/explainer-video-from-codebase/tools/trace/python/fmtrace_plugin.py

@@ -0,0 +1,87 @@
+"""trace.mjs's pytest plugin: tells the collector which test is running, so a call made by a framework (a fixture, a DI
+provider, a route reached through a test client thread) is still attributed to the test it ran under; and records each
+test's outcome per phase, with whether the sandbox denied it (a permission error, or a hidden path not found). Loaded
+with PYTEST_PLUGINS=fmtrace_plugin.
+It records only the repo's own tests: those of the first pytest config in a process, in files inside the scratch copy.
+A pytest run inside a test (pytester, in process or in a child process, which inherits PYTEST_PLUGINS) runs tests
+from its own tmp dir, so it records no outcome and moves no current test; the collector still records its calls. An
+xdist worker runs the copy's tests, and records them."""
+import os
+
+import pytest
+import sitecustomize as fm
+
+_CONFIG = [None]
+
+
+def pytest_configure(config):
+    if _CONFIG[0] is None:
+        _CONFIG[0] = config
+
+
+def _path(node):
+    return os.path.realpath(str(getattr(node, "path", None) or node.fspath))
+
+
+def _in_copy(path, root):
+    return (path + os.sep).startswith(root)
+
+
+def _ours(config, node):
+    path = _path(node)
+    return config is _CONFIG[0] and any(_in_copy(path, r) for r in fm.ROOTS)
+
+
+def _key(item):
+    # the test's file relative to the repo root, then the rest of its node id: independent of pytest's rootdir. An
+    # item a plugin parents at the session (its path is the root) is `::<name>`
+    path = _path(item)
+    rel = next((path[len(r):] for r in fm.ROOTS if _in_copy(path, r)), "")
+    rest = item.nodeid.split("::", 1)[1] if "::" in item.nodeid else ""
+    return rel + "::" + rest
+
+
+def _last_line(longrepr):
+    crash = getattr(longrepr, "reprcrash", None)
+    lines = (crash.message if crash else str(longrepr or "")).strip().splitlines()
+    return lines[-1][:200] if lines else ""
+
+
+@pytest.hookimpl(hookwrapper=True)
+def pytest_runtest_protocol(item, nextitem):
+    if not _ours(item.config, item):
+        yield
+        return
+    fm.CURRENT[0] = _key(item)
+    fm.OUTCOMES.setdefault(fm.CURRENT[0], {"nodeid": item.nodeid})
+    yield
+    fm.CURRENT[0] = None
+
+
+@pytest.hookimpl(hookwrapper=True)
+def pytest_runtest_makereport(item, call):
+    outcome = yield
+    if not _ours(item.config, item):
+        return
+    rep = outcome.get_result()
+    rec = fm.OUTCOMES.setdefault(_key(item), {"nodeid": item.nodeid})
+    rec[rep.when] = rep.outcome
+    if getattr(rep, "wasxfail", None) is not None:
+        rec["xfail"] = True
+    if rep.failed:
+        rec.setdefault("message", _last_line(rep.longrepr))
+        if call.excinfo is not None and fm.denied(call.excinfo.value):
+            rec["permission"] = True
+
+
+@pytest.hookimpl(hookwrapper=True)
+def pytest_make_collect_report(collector):
+    outcome = yield
+    report = outcome.get_result()
+    if _ours(collector.config, collector) and report.failed:
+        fm.COLLECT_ERRORS.append({"nodeid": report.nodeid, "message": _last_line(report.longrepr)})
+
+
+def pytest_collection_finish(session):
+    if session.config is _CONFIG[0]:
+        fm.COLLECTED[0] = len([i for i in session.items if _ours(session.config, i)])