explainer-video 0.0.0-stage → 0.4.0

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

@@ -0,0 +1,173 @@
+/* Rule pack: Go HTTP routers — net/http, gin, echo, chi. A router is a value made by `http.NewServeMux()` (or the
+   `http` package's default mux), `gin.Default()` / `gin.New()`, `echo.New()`, `chi.NewRouter()` / `chi.NewMux()`; a
+   variable, a struct field or a parameter typed as one of their router types (`*http.ServeMux`, `*gin.Engine`,
+   `*gin.RouterGroup`, `*echo.Echo`, `*echo.Group`, `chi.Router`, `*chi.Mux`) is one too. A route registration makes
+   an `http` entry at its handler:
+   - net/http: `Handle` / `HandleFunc(pattern, h)`, the pattern's method and path (Go 1.22: "GET /items/{id}"),
+     else any method; `http.HandlerFunc(f)` is f, a value whose type has `ServeHTTP` is that method, and a call of an
+     in-repo function that wraps a handler (`logged(h)`) is h, the wrapper linked as middleware;
+   - gin: `GET/POST/…/Any/Handle(…, h...)`, the last handler is the route's, the ones before it its middleware;
+   - echo: `GET/POST/…/Any/Add(…, h, mw...)`, the first is the route's, the rest its middleware;
+   - chi: `Get/Post/…/Method/Handle/HandleFunc(…, h)`.
+   Prefixes compose: gin and echo `Group(prefix)`, chi `Route(prefix, func(r chi.Router) {…})`, `Group(func(r) {…})`
+   and `Mount(prefix, sub)`, net/http `Handle(prefix, http.StripPrefix(p, sub))` or `Handle(p, sub)`, and a router
+   handed to a function (`routes.Register(api)`) carries its prefix into that function's parameter. `:id` and `*rest`
+   (gin, echo), `{id:[0-9]+}` (chi) and `{rest...}` (net/http) are written `{id}`. A function handed to a
+   registration is the router's to run, never a call from the registering code. */
+import { addGoEdge, foldGo } from '../lang/go.mjs';
+
+const KIND = [
+  [/^net\/http\.(ServeMux|NewServeMux)$/, 'net-http'],
+  [/^github\.com\/gin-gonic\/gin\.(Engine|RouterGroup|IRouter|IRoutes|Default|New)$/, 'gin'],
+  [/^github\.com\/labstack\/echo(\/v\d+)?\.(Echo|Group|New)$/, 'echo'],
+  [/^github\.com\/go-chi\/chi(\/v\d+)?\.(Mux|Router|NewRouter|NewMux)$/, 'chi'],
+];
+const kindOfExt = ext => KIND.find(([re]) => re.test(ext || ''))?.[1] || null;
+const METHODS = {
+  'net-http': /^(Handle|HandleFunc)$/,
+  gin: /^(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS|Any|Handle)$/,
+  echo: /^(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS|CONNECT|TRACE|Any|Add)$/,
+  chi: /^(Get|Post|Put|Patch|Delete|Head|Options|Connect|Trace|Method|MethodFunc|Handle|HandleFunc)$/,
+};
+const VERB = { Get: 'GET', Post: 'POST', Put: 'PUT', Patch: 'PATCH', Delete: 'DELETE', Head: 'HEAD', Options: 'OPTIONS', Connect: 'CONNECT', Trace: 'TRACE' };
+
+export function goRoutes(go, R) {
+  const fold = (a, c) => a ? foldGo(R, a.ir, c) : null;
+  const extCallee = (ir, sc) => ir?.k === 'call' ? R.calleeOf(ir.fn, sc)?.ext || null : null;
+  // a router expression -> { key, kind } (the key names one router value); mounts records where a child hangs
+  const mounts = new Map(), kinds = new Map();
+  const root = (key, kind) => { kinds.set(key, kind); return { key, kind }; };
+  const mount = (child, parent, prefix) => { if (child && parent && child.key !== parent.key && !mounts.has(child.key)) mounts.set(child.key, { parent: parent.key, prefix }); };
+  function ownerOf(ir, c, depth = 0) {
+    if (!ir || depth > 6) return null;
+    if (ir.k === 'id') {
+      const r = R.resolveName(ir.name, c);
+      if (r?.ext === 'net/http') return root('net/http#DefaultServeMux', 'net-http');
+      const spec = r?.local || r?.var;
+      if (!spec) return null;
+      const key = r.local ? `${c.from}#${ir.name}` : `${spec.module}#${ir.name}`;
+      if (spec.t === 'annot') {
+        const k = kindOfExt(R.classOf(spec.type, spec.module || c.module)?.ext);
+        if (!k) return null;
+        if (spec.closureOf != null) {   // chi `Route(prefix, func(r chi.Router) {…})` / `Group(func(r) {…})`: a child of the call's router
+          const call = go.rawCalls[spec.closureOf], parent = call?.obj && ownerOf(call.obj, call, depth + 1);
+          const child = root(`${c.from}@${call?.line}#${ir.name}`, k);
+          if (parent) mount(child, parent, call.attr === 'Route' ? fold(call.args[0], call) : '');
+          return child;
+        }
+        const p = go.symbols.get(c.from)?.params?.indexOf(ir.name);
+        return root(p >= 0 ? `${c.from}#p${p}` : key, k);
+      }
+      if (spec.t !== 'expr') return null;
+      const sc = r.local ? c : { module: spec.module, from: `${spec.module}:<module>`, types: null, consts: null };
+      return named(key, valueOwner(spec.ir, sc, depth + 1));
+    }
+    if (ir.k === 'sel') {   // a struct field: `s.router`
+      const t = R.typeOf(ir, c), k = t && kindOfExt(R.classOf(t.t, t.module)?.ext);
+      if (!k) return null;
+      const o = R.typeOf(ir.obj, c), cls = o && R.classOf(o.t, o.module)?.cls;
+      return root(`${cls || c.from}.${ir.field}`, k);
+    }
+    if (ir.k === 'call') return named(`${c.from}@${c.line}`, valueOwner(ir, c, depth + 1));   // a chain: `r.Group("/v1").GET(…)`
+    return null;
+  }
+  // the router a key names, given what its value makes
+  const named = (key, v) => !v ? null : v.how === 'same' ? v.owner : v.how === 'new' ? root(key, v.kind) : (mount(root(key, v.parent.kind), v.parent, v.prefix), { key, kind: v.parent.kind });
+  // what a value expression makes: a new router, a group of an existing one, or an existing one
+  function valueOwner(ir, sc, depth) {
+    if (depth > 6) return null;
+    if (ir.k !== 'call') { const o = ownerOf(ir, sc, depth + 1); return o ? { how: 'same', owner: o } : null; }
+    const ext = extCallee(ir, sc), k = kindOfExt(ext);
+    if (k && /\.(NewServeMux|Default|New|NewRouter|NewMux)$/.test(ext)) return { how: 'new', kind: k };
+    if (ir.fn.k === 'sel' && ir.fn.field === 'With') { const o = ownerOf(ir.fn.obj, sc, depth + 1); return o ? { how: 'same', owner: o } : null; }   // chi `r.With(mw)`
+    if (ir.fn.k === 'sel' && /^(Group|Route)$/.test(ir.fn.field) && ir.args[0] && ir.args[0].k !== 'fn') {
+      const parent = ownerOf(ir.fn.obj, sc, depth + 1);
+      if (parent) return { how: 'group', parent, prefix: foldGo(R, ir.args[0], sc) };
+    }
+    // a function that builds and returns a router: `apiRouter()` is the router it returns
+    const fn = R.calleeOf(ir.fn, sc)?.id;
+    for (const ret of fn ? go.returns.filter(x => x.fn === fn && x.ir.k === 'id') : []) { const o = ownerOf(ret.ir, { ...ret, from: fn }, depth + 1); if (o) return { how: 'same', owner: o }; }
+    return null;
+  }
+  const fnOf = id => { const s = id && go.symbols.get(id); return s && (s.kind === 'function' || s.kind === 'method') && !(s.decos || []).includes('abstractmethod') ? id : null; };
+  // a handler argument -> { id, middleware: [ids] }
+  function handlerOf(a, c, depth = 0) {
+    if (!a || depth > 4) return null;
+    if (a.fnId) return { id: a.fnId, middleware: [] };
+    const ir = a.ir || a;
+    if (ir.k === 'id' || ir.k === 'sel') {
+      const t = R.calleeOf(ir, c); if (fnOf(t?.id)) return { id: t.id, middleware: [] };
+      const v = R.typeOf(ir, c), cls = v && R.classOf(v.t, v.module)?.cls, sh = cls && R.lookup(cls, 'ServeHTTP');
+      return sh ? { id: sh, middleware: [] } : null;
+    }
+    if (ir.k === 'lit') { const cls = R.classOf(ir.type, c.module)?.cls, sh = cls && R.lookup(cls, 'ServeHTTP'); return sh ? { id: sh, middleware: [] } : null; }
+    if (ir.k === 'call') {
+      const ext = extCallee(ir, c);
+      if (/^net\/http\.HandlerFunc$/.test(ext || '')) return handlerOf(ir.args[0], c, depth + 1);
+      const t = R.calleeOf(ir.fn, c), fn = fnOf(t?.id);
+      if (!fn) return null;
+      const inner = ir.args.map(x => handlerOf(x, c, depth + 1)).find(Boolean);
+      return inner ? { id: inner.id, middleware: [...inner.middleware, fn] } : { id: fn, middleware: [] };   // `s.handleX()` returns the handler it builds
+    }
+    return null;
+  }
+  const regs = [], claimed = new Set(), byTarget = new Map();
+  for (const c of go.rawCalls) if (c.target) (byTarget.get(c.target) || byTarget.set(c.target, []).get(c.target)).push(c);
+  // a router handed to a function carries its prefix into the parameter
+  for (const [fn, calls] of byTarget) {
+    const s = go.symbols.get(fn); if (!s?.paramTypes) continue;
+    s.paramTypes.forEach((t, p) => { if (!kindOfExt(R.classOf(t, s.file)?.ext)) return;
+      for (const c of calls) { const o = c.args[p] && ownerOf(c.args[p].ir, c); if (o) { mount({ key: `${fn}#p${p}` }, o, ''); break; } } });
+  }
+  go.rawCalls.forEach((c, i) => {
+    if (!c.attr || !c.obj) return;
+    const owner = ownerOf(c.obj, c);
+    if (!owner) return;
+    const k = owner.kind;
+    if (c.attr === 'Mount' && k === 'chi') { const sub = ownerOf(c.args[1]?.ir, c); if (sub) mount(sub, owner, fold(c.args[0], c)); claimed.add(i); return; }
+    if (k === 'net-http' && c.attr === 'Handle') {   // a sub-mux under a pattern, with or without StripPrefix
+      const a1 = c.args[1]?.ir;
+      const strip = a1?.k === 'call' && /^net\/http\.StripPrefix$/.test(extCallee(a1, c) || '') ? a1 : null;
+      const sub = ownerOf(strip ? strip.args[1] : a1, c);
+      if (sub) { mount(sub, owner, strip ? foldGo(R, strip.args[0], c) : ''); claimed.add(i); return; }
+    }
+    if (!METHODS[k]?.test(c.attr)) return;
+    let method, pathArg, hs;
+    if (k === 'net-http') {
+      const pat = fold(c.args[0], c);
+      const m = pat && /^(?:([A-Z]+)\s+)?(?:[\w.-]+)?(\/\S*)$/.exec(pat);
+      if (!m) return;
+      method = m[1] || '*'; pathArg = m[2]; hs = [c.args[1]];
+    } else if ((k === 'gin' && c.attr === 'Handle') || (k === 'echo' && c.attr === 'Add') || (k === 'chi' && /^Method(Func)?$/.test(c.attr))) {
+      method = fold(c.args[0], c); pathArg = fold(c.args[1], c); hs = c.args.slice(2);
+    } else {
+      method = c.attr === 'Any' || c.attr === 'Handle' || c.attr === 'HandleFunc' ? '*' : VERB[c.attr] || c.attr; pathArg = fold(c.args[0], c); hs = c.args.slice(1);
+    }
+    if (pathArg == null || (!pathArg.startsWith('/') && !(pathArg === '' && mounts.has(owner.key)))) return;
+    claimed.add(i);
+    // chi `r.With(mw...).Get(…)`: the With call's arguments are this route's middleware, handed to the router too
+    const withMw = [];
+    for (let o = c.obj; o?.k === 'call' && o.fn.k === 'sel' && o.fn.field === 'With'; o = o.fn.obj) {
+      withMw.push(...o.args.map(a => handlerOf(a, c)?.id).filter(Boolean));
+      const w = go.rawCalls.findIndex(x => x.attr === 'With' && x.line === c.line && x.from === c.from); if (w >= 0) claimed.add(w);
+    }
+    const found = hs.map(a => handlerOf(a, c)).filter(Boolean);
+    if (!found.length) return;
+    const main = k === 'echo' ? found[0] : found.at(-1);
+    const middleware = [...withMw, ...(k === 'echo' ? found.slice(1) : found.slice(0, -1)).map(h => h.id), ...main.middleware];
+    regs.push({ owner: owner.key, kind: k, method: method.toUpperCase(), path: pathArg, handler: main.id, middleware, 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); const pre = mounts.get(o).prefix || ''; p = `${pre.replace(/\/$/, '')}${p.startsWith('/') ? '' : '/'}${p}`; }
+    p = p.replace(/\/{2,}/g, '/').replace(/\{\$\}/g, '').replace(/[:*](\w+)/g, '{$1}').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: `go.${g.kind}` });
+    for (const mw of g.middleware) addGoEdge(go, g.handler, mw, 'framework', g.line, { rule: 'go.middleware', evidence: `${g.file}:${g.line} ${g.method} ${path} runs ${go.symbols.get(mw)?.name} around it` });
+  }
+  return { routes, claimed, mounts: [...mounts].map(([child, m]) => ({ child, parent: m.parent, prefix: m.prefix })) };
+}

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

@@ -0,0 +1,108 @@
+/* Rule pack: go test, in test-group (`_test.go`) files.
+   - tests: `func TestXxx(t *testing.T)` and `func FuzzXxx(f *testing.F)` (Xxx not starting with a lower-case letter),
+     the functions `go test` runs; assertion lines are `t.Error*` / `t.Fatal*` / `t.Fail*` calls, testify
+     `assert.*` / `require.*` calls (or an `assert.New(t)` value's) and a testify mock's `AssertExpectations` /
+     `AssertCalled`; a function literal's body (a subtest) belongs to its test;
+   - subtests: `t.Run("name", func(t *testing.T) {…})` names a subtest; in a table test,
+     `for _, tc := range cases { t.Run(tc.name, …) }`, the table's case count is recorded when `cases` is a composite
+     literal (`table: { cases, line }`);
+   - hooks: `TestMain(m *testing.M)` runs around every test of its directory's test binary (the pytest pack's autouse
+     fixture);
+   - mock targets: a test-group type the test side constructs (`&fakeStore{}`, `new(fakeStore)`, a testify
+     `mock.Mock` embedder, a gomock `NewMockX(ctrl)`) that implements a production interface replaces, in that test,
+     every production implementation of that interface's methods: the code it stands in for is not what the test
+     exercises;
+   - direct test links: every edge from a test's own side (its body, TestMain, test-side helpers) into non-test code,
+     minus whatever that test mocks. */
+import { posix } from 'node:path';
+import { addGoEdge } from '../lang/go.mjs';
+
+const TEST = /^(Test|Fuzz)([^a-z]|$)/;
+const ASSERT_ATTR = /^(Error|Errorf|Fatal|Fatalf|Fail|FailNow)$/;
+const TESTIFY = /^github\.com\/stretchr\/testify\/(assert|require)\.(?!New$)\w+$/;
+const MOCK_ASSERT = /^Assert(Expectations|Called|NotCalled|NumberOfCalls)$/;   // a testify mock.Mock's own checks
+const dirOf = f => posix.dirname(f) === '.' ? '' : posix.dirname(f);
+
+export function findGoTests(go, R) {
+  const isTestingT = (ir, c) => { const t = R.typeOf(ir, c), x = t && R.classOf(t.t, t.module)?.ext; return /^testing\.(T|B|F|TB)$/.test(x || ''); };
+  const isAssertions = (ir, c) => { const t = R.typeOf(ir, c), x = t && R.classOf(t.t, t.module)?.ext;
+    if (/^github\.com\/stretchr\/testify\/(assert|require)\.Assertions$/.test(x || '')) return true;
+    const spec = ir?.k === 'id' ? R.resolveName(ir.name, c)?.local : null;   // a := assert.New(t)
+    return spec?.t === 'expr' && spec.ir.k === 'call' && /\/(assert|require)\.New$/.test(R.calleeOf(spec.ir.fn, c)?.ext || ''); };
+  const asserts = new Map(), runs = new Map();
+  for (const c of go.rawCalls) {
+    const s = go.symbols.get(c.from);
+    if (s?.group !== 'test') continue;
+    const isAssert = (c.attr && ASSERT_ATTR.test(c.attr) && isTestingT(c.obj, c)) || TESTIFY.test(R.calleeOf(c.attr ? { k: 'sel', obj: c.obj, field: c.attr } : c.fn, c)?.ext || '')
+      || (c.attr && (isAssertions(c.obj, c) || MOCK_ASSERT.test(c.attr)));
+    if (isAssert) (asserts.get(c.from) || asserts.set(c.from, new Set()).get(c.from)).add(c.line);
+    if (c.attr === 'Run' && isTestingT(c.obj, c)) {
+      const title = c.args[0]?.ir.k === 'str' ? c.args[0].ir.v : null;
+      (runs.get(c.from) || runs.set(c.from, []).get(c.from)).push({ title, line: c.line, ...(title == null ? { name: c.args[0]?.text } : {}),
+        ...(c.range ? { table: { over: c.range.over, line: c.range.line, cases: c.range.cases } } : {}) });
+    }
+  }
+  const tests = [];
+  for (const s of go.symbols.values()) {
+    if (s.group !== 'test' || s.kind !== 'function' || !/_test\.go$/.test(s.file) || s.id.includes('<locals>') || !TEST.test(s.name) || s.name === 'TestMain') continue;
+    if (!/^testing\.(T|F)$/.test(R.classOf(s.paramTypes?.[0], s.file)?.ext || '')) continue;
+    const lines = [...(asserts.get(s.id) || [])].sort((a, b) => a - b);
+    s.asserts = lines.length; s.assertLines = lines;
+    const sub = runs.get(s.id) || [];
+    const table = sub.find(r => r.table)?.table;
+    tests.push({ id: s.id, file: s.file, line: s.start, end: s.end, asserts: lines.length, assertLines: lines,
+      ...(sub.length ? { subtests: sub.map(r => r.title ?? `<${r.name}>`) } : {}), ...(table ? { table } : {}) });
+  }
+  return tests;
+}
+
+export function findGoHooks(go, R) {
+  return [...go.symbols.values()].filter(s => s.group === 'test' && s.kind === 'function' && s.name === 'TestMain' && /_test\.go$/.test(s.file)
+    && /^testing\.M$/.test(R.classOf(s.paramTypes?.[0], s.file)?.ext || ''))
+    .map(s => { s.hook = 'TestMain'; return { id: s.id, name: 'TestMain', file: s.file, line: s.start, cls: null, autouse: true, scope: [], covers: dirOf(s.file) }; });
+}
+
+// TestMain runs around every test in its directory: both the package's and its external `_test` package's
+export function bindGoHooks(tests, hooks) {
+  const out = [];
+  for (const t of tests) for (const h of hooks) if (dirOf(t.file) === h.covers) out.push({ fn: t.id, param: null, fixture: h.id, autouse: true, rule: 'go.TestMain' });
+  return out;
+}
+
+export function goMockTargets(go, R, readText) {
+  const mocks = [];
+  const how = k => {
+    if (k.embeds.some(t => /testify\/mock\.Mock$/.test(R.classOf(t, k.module)?.ext || ''))) return 'testify.mock';
+    if (/Code generated by MockGen/.test(readText(k.file).slice(0, 400))) return 'gomock';
+    return 'go.fake';
+  };
+  const doubleOf = cls => { const k = go.classes.get(cls); return k && !k.iface && go.symbols.get(cls)?.group === 'test' ? k : null; };
+  const constructs = [];
+  for (const l of go.literals) if (l.cls && doubleOf(l.cls)) constructs.push({ from: l.from, cls: l.cls, line: l.line });
+  for (const c of go.rawCalls) {   // NewMockStore(ctrl), newFake(): a function whose declared result is a test double
+    const s = c.target && go.symbols.get(c.target), r = s?.results?.[0] && R.classOf(s.results[0], s.file)?.cls;
+    if (r && doubleOf(r)) constructs.push({ from: c.from, cls: r, line: c.line });
+  }
+  const seen = new Set();
+  for (const x of constructs) {
+    const k = doubleOf(x.cls);
+    for (const iface of k.implementsIds || []) {
+      if (go.symbols.get(iface)?.group === 'test') continue;
+      for (const n of go.classes.get(iface).methods.keys())
+        for (const impl of R.implementers.get(iface) || []) {
+          if (go.symbols.get(impl)?.group === 'test') continue;
+          const target = R.lookup(impl, n), key = `${x.from}\0${target}`;
+          if (!target || seen.has(key)) continue;
+          seen.add(key);
+          mocks.push({ fn: x.from, raw: `${k.name} (for ${go.symbols.get(iface).name}.${n})`, target, line: x.line, how: how(k) });
+        }
+    }
+  }
+  return mocks;
+}
+
+export function linkGoHooks(go, bindings) {
+  const s = id => go.symbols.get(id);
+  for (const b of bindings) addGoEdge(go, b.fn, b.fixture, 'framework', s(b.fn)?.start, { rule: 'go.test-main',
+    evidence: `${s(b.fn)?.file}: TestMain at ${s(b.fixture)?.file}:${s(b.fixture)?.start} runs around this test` });
+}

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

@@ -0,0 +1,57 @@
+/* Rule pack: gRPC (Go). A server registration `pb.Register<Svc>Server(s, impl)` makes an `rpc` entry at each method
+   of impl's type that serves the service: the methods of the `<Svc>Server` interface when the generated code is in
+   the repo (its `mustEmbed…` marker left out), else impl's exported methods that take a `context.Context` first. A
+   method impl only inherits from an embedded `Unimplemented<Svc>Server` is not served by it. The entry's path is the
+   gRPC method's HTTP/2 path, `/<package>.<Svc>/<Method>`, the package read from the generated `grpc.ServiceDesc`
+   (`ServiceName: "pkg.Svc"`), else `/<Svc>/<Method>`.
+   A client call is an `http` crossing to that method's handler: in generated client code, `cc.Invoke(ctx, method, …)`
+   / `cc.NewStream(ctx, desc, method)` whose method string (or the const naming it) is the path; else a call on a
+   value made by `pb.New<Svc>Client(conn)` from an external package, matched by service and method name. */
+import { addGoEdge, foldGo } from '../lang/go.mjs';
+
+export function grpcEntries(go, R) {
+  const entries = [];
+  const fullName = svc => go.serviceNames.find(s => s.iface === `${svc}Server`)?.name || go.serviceNames.find(s => s.name.split('.').pop() === svc)?.name || svc;
+  const ifaceOf = svc => [...go.classes.values()].find(k => k.iface && k.name === `${svc}Server`);
+  for (const c of go.rawCalls) {
+    const name = c.attr || (c.fn?.k === 'id' ? c.fn.name : null);
+    const m = name && /^Register(\w+)Server$/.exec(name);
+    if (!m || c.args.length < 2) continue;
+    const svc = m[1], t = R.typeOf(c.args[1].ir, c), impl = t && R.classOf(t.t, t.module)?.cls;
+    if (!impl) continue;
+    const iface = ifaceOf(svc);
+    const names = iface ? [...iface.methods.keys()].filter(n => !/^mustEmbed/.test(n))
+      : [...new Set(R.embedChain(impl).flatMap(k => [...go.classes.get(k).methods.keys()]))].filter(n => /^[A-Z]/.test(n) && /context\.Context/.test(go.symbols.get(R.lookup(impl, n))?.text.split('\n')[0] || ''));
+    const full = fullName(svc);
+    for (const n of names) {
+      const id = R.lookup(impl, n), s = id && go.symbols.get(id);
+      if (!s || /^Unimplemented/.test(go.symbols.get(s.cls)?.name || '') || (s.decos || []).includes('abstractmethod')) continue;
+      entries.push({ kind: 'rpc', path: `/${full}/${n}`, key: `${full}/${n}`, id, file: c.file, line: c.line, rule: 'grpc', service: full });
+    }
+  }
+  return entries;
+}
+
+export function linkGrpcClients(go, R, rpcEntries) {
+  const byPath = new Map(rpcEntries.map(e => [e.path, e])), links = [];
+  const link = (c, e, how) => { addGoEdge(go, c.from, e.id, 'http', c.line, { rule: 'grpc.client', evidence: `${c.file}:${c.line} ${how} ${e.path}` });
+    links.push({ from: c.from, file: c.file, line: c.line, path: e.path, handler: e.id }); };
+  for (const c of go.rawCalls) {
+    if (!c.attr) continue;
+    if (c.attr === 'Invoke' || c.attr === 'NewStream') {
+      const p = foldGo(R, c.args[c.attr === 'Invoke' ? 1 : 2]?.ir, c);
+      const e = byPath.get(p);
+      if (e) link(c, e, `invokes`);
+      continue;
+    }
+    // a client made by an external package's New<Svc>Client: matched by service and method name
+    let h = c.obj; if (h?.k !== 'id') continue;
+    const spec = R.resolveName(h.name, c)?.local;
+    const made = spec?.t === 'expr' && spec.ir.k === 'call' ? R.calleeOf(spec.ir.fn, c)?.ext : null;
+    const m = made && /\.New(\w+)Client$/.exec(made);
+    if (!m) continue;
+    const e = rpcEntries.find(x => x.key.split('/')[0].split('.').pop() === m[1] && x.key.endsWith(`/${c.attr}`));
+    if (e) link(c, e, `calls`);
+  }
+  return links;
+}

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

@@ -0,0 +1,97 @@
+/* Rule pack: C and C++ tests — GoogleTest, Catch2, and plain C test functions (Unity, cmocka, a hand-rolled runner) —
+   in test-group files.
+   - tests: gtest `TEST(Suite, Name)`, `TEST_F(Fixture, Name)`, `TEST_P`, `TYPED_TEST` (named `Suite.Name`); Catch2
+     `TEST_CASE("title", "[tags]")`, `SCENARIO`, `TEST_CASE_METHOD(Fixture, "title")`, its `SECTION("…")`s recorded
+     as subtests; a C function named `test_*`; assertion lines are `EXPECT_*` / `ASSERT_*` (gmock's `EXPECT_CALL`
+     included), `REQUIRE*` / `CHECK*`, Unity `TEST_ASSERT*`, cmocka `assert_*`, check's `ck_assert*` and `assert`;
+   - hooks: a TEST_F / TEST_CASE_METHOD fixture class's constructor, `SetUp` and `TearDown` run around each of its
+     tests (the pytest pack's autouse fixtures), as do a Unity file's `setUp` / `tearDown`; the test body is a member of
+     its fixture, so `cart_.add()` resolves through the fixture's fields;
+   - mock targets: a test-group class that derives from a production class — a gmock `MOCK_METHOD` mock or a
+     hand-written fake — and that the test side constructs replaces, in that test, every production implementation of
+     the methods it overrides in that hierarchy;
+   - direct test links (lib/test-links.mjs): every edge from a test's side into non-test code, minus its mocks. */
+import { addCEdge } from '../lang/c.mjs';
+
+const ASSERT = /^((EXPECT|ASSERT)_[A-Z0-9_]+|REQUIRE(_\w+)?|CHECK(_\w+)?|TEST_ASSERT\w*|assert|assert_\w+|ck_assert\w*|ASSERT|CU_ASSERT\w*)$/;
+
+export function findCTests(cm) {
+  const asserts = new Map(), sections = new Map();
+  for (const c of cm.rawCalls) {
+    const s = cm.symbols.get(c.from);
+    if (s?.group !== 'test' || c.attr || c.isNew) continue;
+    const name = c.fn?.k === 'id' ? c.fn.name.split('::').pop() : c.expr;
+    if (ASSERT.test(name)) (asserts.get(c.from) || asserts.set(c.from, new Set()).get(c.from)).add(c.line);
+    if (name === 'SECTION' || name === 'GIVEN' || name === 'WHEN' || name === 'THEN') (sections.get(c.from) || sections.set(c.from, []).get(c.from)).push(c.args[0]?.str ?? c.args[0]?.text);
+  }
+  const tests = [];
+  for (const s of cm.symbols.values()) {
+    if (s.group !== 'test' || s.kind !== 'function' || s.id.includes('<locals>')) continue;
+    if (!s.test && !/^test_\w+$/.test(s.name)) continue;
+    const lines = [...(asserts.get(s.id) || [])].sort((a, b) => a - b);
+    s.asserts = lines.length; s.assertLines = lines;
+    const sub = sections.get(s.id) || [];
+    tests.push({ id: s.id, file: s.file, line: s.start, end: s.end, asserts: lines.length, assertLines: lines, framework: s.macro ? (/TEST_CASE|SCENARIO/.test(s.macro) ? 'catch2' : 'gtest') : 'c',
+      ...(s.fixture ? { fixture: s.fixture } : {}), ...(sub.length ? { subtests: sub } : {}) });
+  }
+  return tests;
+}
+
+export function findCHooks(cm, R, tests) {
+  const hooks = new Map();
+  const add = (id, name, autouse = true) => { const s = cm.symbols.get(id); if (s && !hooks.has(id)) hooks.set(id, { id, name, file: s.file, line: s.start, cls: s.cls || null, autouse }); };
+  for (const t of tests) {
+    const s = cm.symbols.get(t.id);
+    if (t.fixture) { const k = R.classNamed(t.fixture, { module: s.module, ns: s.ns }); if (!k) continue;
+      for (const m of [R.ctorOf(k), R.lookup(k, 'SetUp'), R.lookup(k, 'TearDown')]) if (m) add(m, cm.symbols.get(m).name); }
+  }
+  for (const s of cm.symbols.values()) if (s.group === 'test' && s.kind === 'function' && /^(setUp|tearDown)$/.test(s.name)) add(s.id, s.name);
+  for (const h of hooks.values()) cm.symbols.get(h.id).hook = h.name.split('.').pop();   // a direct link through it is `via: fixture`
+  return [...hooks.values()];
+}
+
+export function bindCHooks(cm, R, tests, hooks) {
+  const out = [];
+  for (const t of tests) {
+    const s = cm.symbols.get(t.id);
+    const k = t.fixture ? R.classNamed(t.fixture, { module: s.module, ns: s.ns }) : null;
+    const chain = k ? new Set(R.mro(k)) : new Set();
+    for (const h of hooks) {
+      if (h.cls && chain.has(h.cls)) out.push({ fn: t.id, param: null, fixture: h.id, autouse: true, rule: 'gtest.fixture' });
+      else if (!h.cls && h.file === t.file && !t.fixture && t.framework === 'c') out.push({ fn: t.id, param: null, fixture: h.id, autouse: true, rule: 'unity.setUp' });
+    }
+  }
+  return out;
+}
+
+export function linkCHooks(cm, bindings) {
+  const s = id => cm.symbols.get(id);
+  for (const b of bindings) addCEdge(cm, b.fn, b.fixture, 'framework', s(b.fn)?.start, { rule: b.rule,
+    evidence: `${s(b.fn)?.file}: ${s(b.fixture)?.name} at ${s(b.fixture)?.file}:${s(b.fixture)?.start} runs around this test` });
+}
+
+export function cMockTargets(cm, R, hooks) {
+  const mocks = [], seen = new Set();
+  const isTest = id => cm.symbols.get(id)?.group === 'test';
+  // what the test side constructs: `MockPrices m;`, `new FakeDb`, make_unique<…>, and a fixture's fields (made with it)
+  const built = cm.rawCalls.filter(c => c.isNew && c.target).map(c => ({ from: c.from, cls: c.target, line: c.line }));
+  for (const h of hooks) if (h.cls) for (const k of R.mro(h.cls)) for (const [f, t] of cm.classes.get(k)?.fields || []) {
+    const d = t.k === 'name' ? R.classNamed(t.name, { module: cm.classes.get(k).module, ns: cm.classes.get(k).ns }) : null;
+    if (d) built.push({ from: h.id, cls: d, line: cm.classes.get(k).line, field: f });
+  }
+  for (const c of built) {
+    if (!isTest(c.cls) || !cm.classes.has(c.cls)) continue;
+    const k = cm.classes.get(c.cls);
+    const roots = R.mro(k.id).slice(1).filter(b => !isTest(b));
+    if (!roots.length) continue;
+    for (const m of k.methods.keys()) for (const r of roots) {
+      const impls = [R.lookup(r, m), ...R.overrides(r, m)].filter(x => x && !isTest(x) && !(cm.symbols.get(x).decos || []).includes('abstractmethod'));
+      for (const target of impls) {
+        const key = `${c.from}\0${target}`;
+        if (seen.has(key)) continue; seen.add(key);
+        mocks.push({ fn: c.from, raw: `${k.name} (for ${cm.symbols.get(r).name}.${m})`, target, line: c.line, how: k.mocked ? 'gmock' : 'cpp.fake' });
+      }
+    }
+  }
+  return mocks;
+}

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

@@ -0,0 +1,55 @@
+/* Rule pack: Haystack pipelines. A builder function (Pipeline() + add_component + connect) wires components;
+   `p.run()` on a builder's result calls each component's `run` in connect order. A component built by a
+   factory becomes `dispatch` links carrying the factory's branch guards; a library component is a named
+   external leaf. */
+import { addEdge } from '../lang/python.mjs';
+
+const literal = a => a && a.type === 'string' ? a.s : null;
+
+export function linkPipelines(py, R) {
+  const builders = new Map();
+  const sym = id => py.symbols.get(id);
+  for (const c of py.rawCalls) {
+    if (c.attr === 'add_component' && c.args.length >= 2) {
+      const b = builders.get(c.from) || builders.set(c.from, { fn: c.from, comps: new Map(), order: [] }).get(c.from);
+      const v = c.args[1];
+      const asTargets = (expr, sc) => { const r = R.resolveExpr(expr, sc);
+        if (r?.id && py.classes.has(r.id)) return [{ cls: r.id }];
+        if (r?.ext) return [{ ext: r.ext }];
+        if (r?.id && sym(r.id)?.kind === 'function') return R.factoryReturns(r.id).map(x => ({ ...x, factory: r.id }));
+        return []; };
+      const type = v.type === 'identifier' ? c.types?.get(v.text) : null;
+      const targets = v.type === 'call' ? asTargets(v.fn, c) : type ? asTargets(type.expr, c) : [];
+      b.comps.set(literal(c.args[0]), { targets, line: c.line });
+    }
+  }
+  for (const c of py.rawCalls) if (c.attr === 'connect' && c.args.length >= 2 && literal(c.args[0]) != null && literal(c.args[1]) != null) {
+    const b = builders.get(c.from); if (b) b.order.push([literal(c.args[0]).split('.')[0], literal(c.args[1]).split('.')[0], c.line]);
+  }
+  for (const b of builders.values()) {   // topological order from the connect pairs
+    const names = [...b.comps.keys()], indeg = new Map(names.map(n => [n, 0]));
+    for (const [, y] of b.order) indeg.set(y, (indeg.get(y) || 0) + 1);
+    const seq = [], q = names.filter(n => !indeg.get(n));
+    while (q.length) { const n = q.shift(); seq.push(n); for (const [x, y] of b.order) if (x === n) { indeg.set(y, indeg.get(y) - 1); if (!indeg.get(y)) q.push(y); } }
+    b.seq = seq.length === names.length ? seq : names;
+  }
+  const runs = [];
+  for (const c of py.rawCalls) if (c.attr === 'run' && c.types?.has(c.obj)) {
+    const spec = c.types.get(c.obj);
+    const r = spec.expr ? R.resolveExpr(spec.expr, c) : null;
+    const b = r?.id ? builders.get(r.id) : (spec.expr === 'Pipeline' ? builders.get(c.from) : null);
+    if (!b) continue;
+    b.seq.forEach((name, i) => {
+      const comp = b.comps.get(name);
+      const ev = `${sym(b.fn).file}:${comp.line} add_component("${name}") · connect order ${i + 1}/${b.seq.length}`;
+      const kind = comp.targets.length > 1 ? 'dispatch' : 'framework';
+      for (const t of comp.targets) {
+        const extra = { rule: 'haystack.pipeline', order: i, component: name, evidence: ev, selectors: t.guards?.map(g => (g.neg ? 'not ' : '') + g.text), narrowedBy: t.factory };
+        if (t.cls) { const run = R.lookup(t.cls, 'run'); if (run) addEdge(py, c.from, run, kind, c.line, extra); }
+        else if (t.ext) addEdge(py, c.from, `ext:${t.ext}.run`, kind, c.line, { ...extra, external: true });
+      }
+    });
+    runs.push({ caller: c.from, builder: b.fn, seq: b.seq, comps: Object.fromEntries([...b.comps].map(([n, v]) => [n, v.targets.map(t => t.cls || 'ext:' + t.ext)])) });
+  }
+  return runs;
+}

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

@@ -0,0 +1,100 @@
+/* Rule pack: jest / vitest (and node:test and mocha, which share the API) in test-group files.
+   - tests: `it(title, fn)` / `test(title, fn)` (and `.only`, `.skip`, `.each(...)`), named by their `describe` titles
+     and their own (`A > B > adds`); assertion lines are their `expect(…)` and `assert…(…)` calls;
+   - hooks: `beforeEach` / `beforeAll` / `afterEach` / `afterAll` bind to every test under their `describe` (the
+     pytest pack's autouse fixtures); a hook in a setup file (setupTests.*, jest.setup.*, vitest.setup.*, or a file a
+     jest / vitest config lists in setupFiles) binds to every test below that setup file's directory (a listed one:
+     below its config's directory);
+   - mock targets: `jest.mock('mod')` / `vi.mock('mod')` (and `doMock`) replace every export of the module the
+     string resolves to (from the test file, the way the module system would), or only the factory's keys when the
+     factory spreads the real module; they are hoisted, so they apply to the whole test file, and in a setup file to
+     every test in its scope (session-wide). `jest.spyOn(obj, 'm')` / `vi.spyOn` replaces `m` only when a
+     `.mockImplementation` / `.mockReturnValue` / `.mockResolvedValue` / `.mockRejectedValue` follows (a bare spy
+     calls through);
+   - direct test links (lib/test-links.mjs): every edge from a test's own side (its body, its hooks, test-side
+     helpers) into non-test code, minus whatever that test mocks. */
+import { posix } from 'node:path';
+import { addTsEdge } from '../lang/typescript.mjs';
+
+export const SETUP_FILE = /(^|\/)(setupTests|setup-tests|jest\.setup|vitest\.setup|test-setup)\.[cm]?[jt]sx?$/;
+const ASSERT = /^(expect|assert)$|^assert\.\w+$|^expect\.\w+$|^t\.assert\w*$/;
+
+// files a jest or vitest config names in setupFiles / setupFilesAfterEnv (`<rootDir>/x`, './x' or 'x', from the config's
+// dir) -> the directory whose tests they set up (the config's)
+export function configuredSetupFiles(configs) {
+  const out = new Map();
+  for (const { rel, text } of configs) {
+    const dir = posix.dirname(rel) === '.' ? '' : posix.dirname(rel);
+    for (const m of text.matchAll(/setupFiles(?:AfterEnv)?["']?\s*:\s*\[([^\]]*)\]/g))
+      for (const s of m[1].matchAll(/["'`]([^"'`]+)["'`]/g)) out.set(posix.normalize(posix.join(dir, s[1].replace(/^<rootDir>\/?/, ''))), dir);
+  }
+  return out;
+}
+// the directory a setup file's hooks and mocks cover: its config's, else its own
+const setupScope = (file, setupFiles) => setupFiles.has(file) ? setupFiles.get(file) : posix.dirname(file) === '.' ? '' : posix.dirname(file);
+const under = (dir, file) => !dir || file.startsWith(dir + '/');
+
+export function findTests(ts) {
+  const assertsOf = new Map();
+  for (const c of ts.rawCalls) if (ASSERT.test(c.expr) && ts.symbols.get(c.from)?.test) (assertsOf.get(c.from) || assertsOf.set(c.from, new Set()).get(c.from)).add(c.line);
+  return [...ts.symbols.values()].filter(s => s.test && s.group === 'test').map(s => {
+    const lines = [...(assertsOf.get(s.id) || [])].sort((a, b) => a - b);
+    s.asserts = lines.length; s.assertLines = lines;
+    return { id: s.id, file: s.file, line: s.start, end: s.end, asserts: lines.length, assertLines: lines, title: s.title, describe: s.describe };
+  });
+}
+
+export function findHooks(ts, setupFiles) {
+  return ts.testCalls.filter(t => t.kind === 'hook').map(h => {
+    const setup = SETUP_FILE.test(h.file) || setupFiles.has(h.file);
+    return { id: h.id, name: h.hook, file: h.file, line: h.line, cls: null, autouse: true, scope: h.describe, ...(setup ? { setup: true, covers: setupScope(h.file, setupFiles) } : {}) };
+  });
+}
+
+export function bindHooks(tests, hooks) {
+  const binds = (t, h) => h.setup ? under(h.covers, t.file) : h.file === t.file && h.scope.every((x, i) => t.describe[i] === x);
+  const out = [];
+  for (const t of tests) for (const h of hooks) if (binds(t, h)) out.push({ fn: t.id, param: null, fixture: h.id, autouse: true, rule: `${h.setup ? 'setup-file' : 'test'}.${h.name}` });
+  return out;
+}
+
+export function linkHooks(ts, bindings) {
+  const s = id => ts.symbols.get(id);
+  for (const b of bindings) addTsEdge(ts, b.fn, b.fixture, 'framework', s(b.fn)?.start, { rule: 'js.test-hook',
+    evidence: `${s(b.fn)?.file}: ${s(b.fixture)?.name} at ${s(b.fixture)?.file}:${s(b.fixture)?.start} runs around this test` });
+}
+
+export function mockTargets(ts, R, setupFiles) {
+  const exportsOf = (rel, seen = new Set()) => {
+    if (seen.has(rel)) return []; seen.add(rel);
+    const M = ts.modules.get(rel); if (!M) return [];
+    const names = [...M.exports.keys(), ...(M.defaultExport ? ['default'] : [])];
+    const ids = names.map(n => R.exportOf(rel, n)?.id).filter(Boolean);
+    for (const s of M.starExports) { const t = R.resolveModule(s, rel); if (t) ids.push(...exportsOf(t, seen)); }
+    // a mocked class has every method replaced
+    return [...new Set(ids.flatMap(id => ts.classes.has(id) ? [id, ...ts.classes.get(id).methods.values()] : [id]))];
+  };
+  const mocks = [];
+  for (const c of ts.mockCalls) {
+    const setup = SETUP_FILE.test(c.file) || setupFiles.has(c.file);
+    const where = setup ? { scope: 'session', conftest: c.file, covers: setupScope(c.file, setupFiles) } : {};
+    if (/(^|\.)(mock|doMock)$/.test(c.how) && c.spec != null) {
+      const mod = R.resolveModule(c.spec, c.file);
+      const fn = `${c.file}:<module>`;   // hoisted: the whole test file
+      if (!mod) { mocks.push({ fn, raw: c.spec, target: null, line: c.line, how: c.how, ...where }); continue; }
+      const targets = c.keys ? c.keys.map(k => R.exportOf(mod, k)?.id).filter(Boolean) : exportsOf(mod);
+      if (!targets.length) mocks.push({ fn, raw: c.spec, target: null, module: mod, line: c.line, how: c.how, ...where });
+      for (const t of targets) mocks.push({ fn, raw: c.spec, target: t, module: mod, line: c.line, how: c.how, ...(c.keys ? { partial: true } : {}), ...where });
+    } else if (/spyOn$/.test(c.how) && c.obj && c.prop && c.replaced) {
+      let target = null;
+      const obj = c.obj.replace(/\.prototype$/, '');
+      const r = /^[\w$.]+$/.test(obj) ? R.resolveExpr(obj, c) : null;
+      if (r?.module) target = R.exportOf(r.module, c.prop)?.id || null;
+      else if (r?.id && ts.classes.has(r.id)) target = R.lookup(r.id, c.prop);
+      else if (r?.obj) { const m = r.obj.get(c.prop); target = typeof m === 'string' ? m : null; }
+      else { const spec = c.types?.get(obj) || r?.var; const rc = spec ? R.receiverOf(spec, spec.module ? spec : c) : null; if (rc) target = R.lookup(rc.cls[0], c.prop); }
+      mocks.push({ fn: c.fn, raw: `${c.obj}.${c.prop}`, target, line: c.line, how: c.how, ...where });
+    }
+  }
+  return mocks;
+}