candor-ts 0.5.23 → 0.5.28

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "candor-ts",
-  "version": "0.5.23",
+  "version": "0.5.28",
   "description": "candor for TypeScript — per-function side effects, transitively, with a policy gate (candor-spec 0.5)",
   "type": "module",
   "dependencies": {

package/query-core.mjs

@@ -26,7 +26,7 @@ function siblings(prefix, predicate) {
 // calibrated-coverage sidecar). Exported so `hasReport` (the MCP existence check) uses the SAME predicate
 // as the loader — else a prefix whose only sibling is `.encountered-*`/`.calibrated.json` passes the
 // existence check but loads ZERO functions → an authoritative-empty result (silent under-report; review find).
-export const isReport = (f) => !f.endsWith(".callgraph.json") && !f.includes(".encountered-") && !f.endsWith(".calibrated.json");
+export const isReport = (f) => !f.endsWith(".callgraph.json") && !f.endsWith(".hierarchy.json") && !f.includes(".encountered-") && !f.endsWith(".calibrated.json");
 
 // Defend the queries against a partial/old-engine/hand-edited report: the §2 required fields are
 // defaulted, and a WRONG-TYPE field is coerced — a non-array `inferred` (e.g. the string "Net") must
@@ -158,6 +158,65 @@ export function callers(cg, q) {
   return { of: targets, direct: [...direct].sort(), transitive: [...transitive].sort() };
 }
 
+// The bare method name / declaring type of a `mod.Class.member` qual (drop a `#line:col` function-scoped
+// suffix, then split on the last dot). Used by the dispatch-frontier to match a confirmed reacher against
+// a `dispatch:OWNER.member` owner.
+const stripPos = (s) => { const h = s.indexOf("#"); return h >= 0 ? s.slice(0, h) : s; };
+export function simpleMethod(fn) { const b = stripPos(fn); const i = b.lastIndexOf("."); return i >= 0 ? b.slice(i + 1) : b; }
+export function declaringType(fn) { const b = stripPos(fn); const i = b.lastIndexOf("."); return i >= 0 ? b.slice(0, i) : b; }
+
+// Load the type-hierarchy sidecar (`<prefix>.hierarchy.json`, 0.7), or {} if absent (→ the frontier
+// falls back to a simple-name match, which over-lists — the safe direction).
+export function loadHierarchy(prefix) {
+  const norm = (h) => (h && typeof h === "object" && !Array.isArray(h))
+    ? Object.fromEntries(Object.entries(h).map(([k, v]) => [k, Array.isArray(v) ? v : []])) : {};
+  if (fs.existsSync(`${prefix}.hierarchy.json`)) {
+    try { return norm(JSON.parse(fs.readFileSync(`${prefix}.hierarchy.json`, "utf8"))); } catch { return {}; }
+  }
+  const h = {};
+  for (const f of siblings(prefix, (x) => x.endsWith(".hierarchy.json"))) {
+    try { Object.assign(h, JSON.parse(fs.readFileSync(f, "utf8"))); } catch { /* tolerate */ }
+  }
+  return norm(h);
+}
+
+// Reflexive+transitive subtype test over the hierarchy sidecar.
+function isSubtypeOf(type, owner, hierarchy) {
+  if (type === owner) return true;
+  const seen = new Set(), stack = [type];
+  while (stack.length) {
+    for (const s of hierarchy[stack.pop()] ?? []) { if (s === owner) return true; if (!seen.has(s)) { seen.add(s); stack.push(s); } }
+  }
+  return false;
+}
+
+// callers + the unresolved-dispatch frontier (--include-unknown, SPEC §3.1/§4 0.7): the CONFIRMED set,
+// plus functions that reach `q` only through a `dispatch:OWNER.member` the engine declined to resolve —
+// disclosed iff a confirmed reacher is an override of OWNER.member (same method AND a subtype of OWNER
+// per the hierarchy; empty hierarchy → simple-name match, over-lists). Never asserted ("cannot confirm").
+export function callersFrontier(cg, fns, hierarchy, q) {
+  const base = callers(cg, q);
+  const confirmed = new Set([...base.of, ...base.transitive]);
+  const typesByMethod = new Map();
+  for (const r of confirmed) { const m = simpleMethod(r); (typesByMethod.get(m) ?? typesByMethod.set(m, []).get(m)).push(declaringType(r)); }
+  const hasHier = hierarchy && Object.keys(hierarchy).length > 0;
+  const possible = [];
+  for (const f of fns) {
+    if (confirmed.has(f.fn)) continue;
+    const hits = new Set();
+    for (const w of f.unknownWhy ?? []) {
+      if (!w.startsWith("dispatch:")) continue;
+      const key = w.slice("dispatch:".length), m = simpleMethod(key), owner = declaringType(key);
+      const types = typesByMethod.get(m);
+      if (!types) continue;
+      if (!hasHier || types.some((t) => isSubtypeOf(t, owner, hierarchy))) hits.add(m);
+    }
+    if (hits.size) possible.push({ fn: f.fn, viaDispatchOn: [...hits].sort().join(",") });
+  }
+  possible.sort((a, b) => a.fn.localeCompare(b.fn));
+  return { ...base, possibleViaUnknownDispatch: possible };
+}
+
 export function map(fns) {
   const mods = {};
   for (const e of fns) {
@@ -205,6 +264,32 @@ export function impact(fns, cg, q) {
   return { fn: tgt ?? q, affectedCount: affected.length, affected, entryPoints };
 }
 
+// blindspots (SPEC §3.1 ⟨0.6⟩): the Unknown SOURCES — fns whose OWN body has an unresolvable call (so
+// they carry `unknownWhy`), each ranked by its Unknown blast radius (the transitive callers that inherit
+// Unknown through it). The actionable inverse of a widely-propagated Unknown: a report can read mostly
+// Unknown from a handful of root causes — this names them, ranked, to declare/resolve/accept. Matches
+// candor-java/candor-query: { sources:[{fn,why,reaches,affected}], totalUnknown }.
+export function blindspots(fns, cg) {
+  const rev = reverseGraph(cg);
+  const totalUnknown = fns.filter((e) => (e.inferred ?? []).includes("Unknown")).length;
+  const sources = [];
+  for (const e of fns) {
+    const why = e.unknownWhy ?? [];
+    if (why.length === 0) continue; // a SOURCE carries its own unknownWhy; a purely-transitive Unknown does not
+    const reached = new Set();
+    const queue = [e.fn];
+    const seen = new Set([e.fn]);
+    while (queue.length) {
+      const n = queue.pop();
+      for (const c of rev.get(n) ?? []) if (!seen.has(c)) { seen.add(c); reached.add(c); queue.push(c); }
+    }
+    const affected = [...reached].sort();
+    sources.push({ fn: e.fn, why, reaches: affected.length, affected });
+  }
+  sources.sort((a, b) => b.reaches - a.reaches || a.fn.localeCompare(b.fn)); // most-smearing first, stable
+  return { sources, totalUnknown };
+}
+
 // path: the FORWARD provenance — a shortest BFS over the calls graph from `fn` to the nearest unit
 // that performs `eff` DIRECTLY (the source). Matches candor-query's {effect, fn, path:[{fn,loc,source}]}.
 export function path(fns, cg, fnQ, eff) {

package/query.mjs

@@ -25,7 +25,8 @@ import { printAgents } from "./contract.mjs";
 // a `matchTier` missing `#` (so the SAME query resolved differently between `impact` and `callers` on a
 // JVM `Type#method` report). Importing the shared functions removes all three divergences (review find).
 import { impact as coreImpact, path as corePath, gains as coreGains,
-         show as coreShow,
+         show as coreShow, blindspots as coreBlindspots,
+         callers as coreCallers, callersFrontier, loadHierarchy,
          loadReport, loadCallgraph, matches } from "./query-core.mjs";
 const emit = (v) => console.log(JSON.stringify(v, null, 1));
 
@@ -58,21 +59,14 @@ switch (cmd) {
     break;
   }
   case "callers": {
-    const [prefix, q] = args;
+    // --include-unknown ⟨0.7⟩ adds the unresolved-dispatch frontier (possibleViaUnknownDispatch); without
+    // it, the byte-for-byte {of,direct,transitive} shape is unchanged (cross-engine parity). Call the
+    // shared query-core so the CLI and MCP compute one truth (the prior inline copy had drifted before).
+    const includeUnknown = args.includes("--include-unknown");
+    const [prefix, q] = args.filter((a) => a !== "--include-unknown");
     const cg = loadCallgraph(prefix);
-    const names = Object.keys(cg);
-    const targets = matches(names, q);
-    const rev = new Map();
-    for (const [caller, callees] of Object.entries(cg))
-      for (const c of callees) (rev.get(c) ?? rev.set(c, []).get(c)).push(caller);
-    const direct = new Set(), transitive = new Set();
-    const queue = [...targets];
-    for (const t of targets) for (const c of rev.get(t) ?? []) direct.add(c);
-    while (queue.length) {
-      const n = queue.pop();
-      for (const c of rev.get(n) ?? []) if (!transitive.has(c) && !targets.includes(c)) { transitive.add(c); queue.push(c); }
-    }
-    emit({ of: targets, direct: [...direct].sort(), transitive: [...transitive].sort() });
+    if (includeUnknown) emit(callersFrontier(cg, loadReport(prefix), loadHierarchy(prefix), q));
+    else emit(coreCallers(cg, q));
     break;
   }
   case "map": {
@@ -127,6 +121,13 @@ switch (cmd) {
     emit(coreImpact(loadReport(prefix), loadCallgraph(prefix), q));
     break;
   }
+  case "blindspots": {
+    // the Unknown SOURCES, ranked by blast radius — the actionable inverse of a widely-propagated
+    // Unknown (SPEC §3.1 ⟨0.6⟩): { sources:[{fn,why,reaches,affected}], totalUnknown }.
+    const [prefix] = args;
+    emit(coreBlindspots(loadReport(prefix), loadCallgraph(prefix)));
+    break;
+  }
   case "gains": {
     // the supply-chain alarm (SPEC §5.1): {gained:[Effect], byFunction:[{fn,effect}]} — what the
     // surface gained between two reports (base → cur), the cross-engine machine-readable form.

package/scan.mjs

@@ -36,7 +36,7 @@ const ENGINE_DIR = path.dirname(fileURLToPath(import.meta.url));
 // literal stamped into the envelope's `spec` field, so the doc lines and the report can never drift.
 // Reused, never re-littered.
 const PKG_VERSION = JSON.parse(fs.readFileSync(path.join(ENGINE_DIR, "package.json"), "utf8")).version;
-const SPEC_VERSION = "0.5";
+const SPEC_VERSION = "0.7";
 
 // --version: a print-and-exit MODE, handled before the main arg walk so it never depends on a target.
 // Fully OFFLINE — candor never phones home. Staying current is the AGENT's job: read the installed
@@ -857,7 +857,7 @@ function recordAccessorHit(owner, hit, label) {
     rec.edges.add(t); // (EDGE) into the accessor unit — effects propagate
   } else {
     rec.direct.add("Unknown");
-    rec.why.add(`accessor:${label}`);
+    rec.why.add(`reflect:accessor:${label}`); // a defineProperty runtime accessor (descriptor get/set unseen) — metaprogramming, canonical `reflect:`
   }
 }
 
@@ -1051,8 +1051,8 @@ function opaqueIterableWhy(expr) {
   if (!t) return null;
   // (a) `any` or a bare TYPE PARAMETER (`<T extends Iterable<…>>(x: T)`): the concrete iterable is
   // indeterminate, so its iterator body is unknowable — never silently pure.
-  if (t.flags & ts.TypeFlags.Any) return "iterate:any";
-  if (t.flags & ts.TypeFlags.TypeParameter) return "iterate:typeparam";
+  if (t.flags & ts.TypeFlags.Any) return "callback:opaque-iterable:any";
+  if (t.flags & ts.TypeFlags.TypeParameter) return "callback:opaque-iterable:typeparam";
   // (b) the type IS an opaque iterable INTERFACE *and* the value is CALLER-SUPPLIED (a parameter / binding
   // element): `collect(source: Iterable<T>)`, `nexts(it: Iterator<T>)`, `drain(g: Generator<T>)`. The
   // caller chooses the concrete iterator (arbitrary I/O), identical to invoking an opaque callback. BOTH
@@ -1065,7 +1065,7 @@ function opaqueIterableWhy(expr) {
     const d = realDecl(checker.getSymbolAtLocation(expr));
     if (d && (ts.isParameter(d) || ts.isBindingElement(d))) {
       const idx = ts.isParameter(d) && d.parent ? d.parent.parameters.indexOf(d) : -1;
-      return idx >= 0 ? `iterate:param#${idx}` : "iterate:param";
+      return idx >= 0 ? `callback:opaque-iterable:param#${idx}` : "callback:opaque-iterable:param";
     }
   }
   return null;
@@ -1155,7 +1155,7 @@ function visitCalls(node) {
           } else {
             rec.direct.add("Unknown"); // unresolvable call → Unknown, never silent-pure (SPEC §4)
             const callee = (node.expression?.getText?.() ?? "?").replace(/\s+/g, "").slice(0, 60);
-            rec.why.add(`call:${callee}`); // an `any`-typed/indeterminate callee — named, so triage starts here
+            rec.why.add(`callback:${callee}`); // an `any`-typed/indeterminate callee (a function VALUE) — canonical `callback:`
           }
         }
       } else {
@@ -1191,7 +1191,7 @@ function visitCalls(node) {
               if (tb) rec.edges.add(tb);
               else {
                 rec.direct.add("Unknown");
-                rec.why.add(`bind:${(bref ?? a).getText().replace(/\s+/g, "").slice(0, 40)}`);
+                rec.why.add(`callback:bind:${(bref ?? a).getText().replace(/\s+/g, "").slice(0, 40)}`); // `.bind(...)` yields a function VALUE — canonical `callback:`
               }
               continue;
             }
@@ -1232,7 +1232,7 @@ function visitCalls(node) {
             // non-value receiver — a type, a literal — resolves to no decl and stays out, no fabrication.)
             else if (d2 && (ts.isVariableDeclaration(d2) || ts.isBindingElement(d2) || ts.isParameter(d2))) {
               rec.direct.add("Unknown");
-              rec.why.add(`call:${recvText.slice(0, 40)}.${m}`);
+              rec.why.add(`callback:${recvText.slice(0, 40)}.${m}`); // method on an indeterminate-valued receiver (no resolvable owner TYPE) — canonical `callback:`, not the frontier's `dispatch:OWNER.member`
             }
           }
           // EXPLICIT iterator force: `it.next()` / `it.return()` / `it.throw()` on an OPAQUE iterator
@@ -1254,7 +1254,7 @@ function visitCalls(node) {
             ]);
             if (why && sn && ITER_PROTO.has(sn)) {
               rec.direct.add("Unknown");
-              rec.why.add(why); // `iterate:param#i` / `iterate:any` / `iterate:typeparam`
+              rec.why.add(why); // `callback:opaque-iterable:param#i` / `:any` / `:typeparam` (opaque iteration ≈ opaque callback)
             }
           }
         }
@@ -1308,11 +1308,11 @@ function visitCalls(node) {
                   for (const ot of oTargets) rec.edges.add(ot);
                   if (!allResolved) {
                     rec.direct.add("Unknown");
-                    rec.why.add(`override:${decl.name?.getText?.() ?? "member"}`);
+                    rec.why.add(`dispatch:${decl.parent?.name ? `${moduleOf(decl.parent.getSourceFile())}.${decl.parent.name.getText()}` : "type"}.${decl.name?.getText?.() ?? "member"}`); // class-override dispatch — canonical `dispatch:QUALIFIED-OWNER.member`, frontier-relevant
                   }
                 } else {
                   rec.direct.add("Unknown"); // override family too wide to enumerate soundly
-                  rec.why.add(`override:${decl.name?.getText?.() ?? "member"}`);
+                  rec.why.add(`dispatch:${decl.parent?.name?.getText?.() ?? "type"}.${decl.name?.getText?.() ?? "member"}`); // class-override dispatch (overridable member, unresolved/too-wide family) — canonical `dispatch:OWNER.member`, frontier-relevant
                 }
               }
             }
@@ -1375,8 +1375,14 @@ function visitCalls(node) {
               }
               if (!edged) {
                 rec.direct.add("Unknown");
-                const tn = decl.parent?.name?.getText?.() ?? decl.name?.getText?.() ?? "type";
-                rec.why.add(`dispatch:${tn}`); // resolution landed on a type, not a body
+                // QUALIFIED owner (module.Type), matching the `mod.Class.member` fn quals so the
+                // dispatch-frontier (callers --include-unknown) can resolve overrides against the
+                // hierarchy sidecar. Bare `decl.parent.name` would not match a reacher's declaringType.
+                const tn = decl.parent?.name
+                  ? `${moduleOf(decl.parent.getSourceFile())}.${decl.parent.name.getText()}`
+                  : "type";
+                const mn = decl.name?.getText?.() ?? "member";
+                rec.why.add(`dispatch:${tn}.${mn}`); // resolution landed on a type, not a body — canonical `dispatch:OWNER.member` (frontier-relevant)
               }
             }
           }
@@ -1395,7 +1401,7 @@ function visitCalls(node) {
           // resolved to a benign es-lib member and read SILENT-PURE (a code-execution sink reported pure).
           if (name === "eval" && parent !== "Math" && parent !== "JSON") {
             rec.direct.add("Unknown");
-            rec.why.add("call:eval");
+            rec.why.add("reflect:eval"); // eval executes a runtime-supplied string — canonical `reflect:`
           }
           if ((parent === "DateConstructor" && name === "now") || (parent === "Performance" && name === "now"))
             rec.direct.add("Clock");
@@ -1711,7 +1717,7 @@ function visitCalls(node) {
         const kinds = (rsym && definePropDynamicKey.get(rsym)) || (rsym0 && definePropDynamicKey.get(rsym0));
         if (kinds && kinds.has(kind)) {
           const owner = enclosing(node);
-          if (owner) { fns.get(owner).direct.add("Unknown"); fns.get(owner).why.add(`defineProperty:dynamic-key`); }
+          if (owner) { fns.get(owner).direct.add("Unknown"); fns.get(owner).why.add(`reflect:defineProperty:dynamic-key`); } // dynamic-key descriptor install — metaprogramming, canonical `reflect:`
         }
       }
     };
@@ -1935,7 +1941,11 @@ for (const [name, rec] of fns) {
   if (inf.includes("Db") && rec.tables.size) entry.tables = [...rec.tables].sort();
   if (inf.includes("Exec") && rec.cmds.size) entry.cmds = [...rec.cmds].sort();
   if (inf.includes("Fs") && rec.paths.size) entry.paths = [...rec.paths].sort();
-  if (rec.direct.has("Unknown") && rec.why.size) entry.unknownWhy = [...rec.why].sort();
+  // ⟨0.6⟩ unknownWhy — REQUIRED on a DIRECT Unknown SOURCE (this fn's own body has the unresolvable call,
+  // so `rec.direct` carries Unknown), absent on a purely-transitive Unknown. The rich per-site reasons
+  // (rec.why: callback:/dispatch:/dynamic-key:) when recorded, else a generic fallback so a source is
+  // never left un-tagged — the source/transitive split the `blindspots` query needs (SPEC §3.1/§4).
+  if (rec.direct.has("Unknown")) entry.unknownWhy = rec.why.size ? [...rec.why].sort() : ["unresolved"];
   // HONESTY: the npm packages this fn transitively reaches that κ couldn't see through — effects through
   // them are NOT in `inferred`, so it is a LOWER BOUND when this is non-empty. Omitted when none.
   if (rec.blind.size) entry.invisible = [...rec.blind].sort();
@@ -1956,6 +1966,30 @@ for (const [name, rec] of fns) cg[name] = [...rec.edges].sort();
 const writeAtomic = (file, text) => { const tmp = `${file}.${process.pid}.tmp`; fs.writeFileSync(tmp, text); fs.renameSync(tmp, file); };
 writeAtomic(`${outPrefix}.json`, JSON.stringify(envelope, null, 1));
 writeAtomic(`${outPrefix}.callgraph.json`, JSON.stringify(cg, null, 1));
+// Type-hierarchy sidecar (SPEC §4 / 0.7): each project class/interface (qualified `mod.Name`, matching
+// the `mod.Class.member` fn quals) -> its qualified direct supertypes/interfaces. Compact (O(types)),
+// lets `callers --include-unknown` resolve whether a confirmed reacher is an override of a `dispatch:`
+// owner WITHOUT storing the dropped candidate edges (which would re-encode the flood bounded-CHA prevents).
+const hierarchy = {};
+for (const sf of sources) {
+  const mod = moduleOf(sf);
+  (function walk(node) {
+    if ((ts.isClassDeclaration(node) || ts.isInterfaceDeclaration(node)) && node.name) {
+      const supers = [];
+      for (const h of node.heritageClauses ?? []) {
+        for (const t of h.types ?? []) {
+          let sym = checker.getSymbolAtLocation(t.expression);
+          if (sym && sym.flags & ts.SymbolFlags.Alias) { try { sym = checker.getAliasedSymbol(sym); } catch { /* keep */ } }
+          const d = (sym?.declarations ?? []).find((x) => ts.isClassDeclaration(x) || ts.isInterfaceDeclaration(x));
+          supers.push(d && d.name ? `${moduleOf(d.getSourceFile())}.${d.name.getText()}` : t.expression.getText());
+        }
+      }
+      if (supers.length) hierarchy[`${mod}.${node.name.getText()}`] = supers;
+    }
+    ts.forEachChild(node, walk);
+  })(sf);
+}
+writeAtomic(`${outPrefix}.hierarchy.json`, JSON.stringify(hierarchy, null, 1));
 console.error(`candor-ts: wrote ${functions.length} effectful functions (${fns.size} analyzed, ${sources.length} files) to ${outPrefix}.json`);
 if (unlistedSeen.size > 0) {
   const top = [...unlistedSeen.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]));