candor-ts 0.5.23 → 0.5.25

package/package.json

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

package/query-core.mjs

@@ -205,6 +205,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,7 @@ 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,
          loadReport, loadCallgraph, matches } from "./query-core.mjs";
 const emit = (v) => console.log(JSON.stringify(v, null, 1));
 
@@ -127,6 +127,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.6";
 
 // --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
@@ -1935,7 +1935,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();