candor-ts 0.5.22 → 0.5.25

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "candor-ts",
-  "version": "0.5.22",
+  "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-core.mjs

@@ -66,11 +66,60 @@ export const KAPPA_RULES = [
   [/^(node:)?sqlite$/, null, "Db"],
   // the curated npm tier
   [/^(axios|got|node-fetch|undici|ws|socket\.io(-client)?|nodemailer)$/, null, "Net"],
+  // gaxios is the axios-like HTTP client under googleapis (request/get/post/put/patch/delete/head do
+  // the network; it has no notable pure surface, but be VERB-precise like the rest of the Net tier so a
+  // future config accessor can't fabricate). `createAPIRequest` is googleapis-common's transport entry
+  // (every googleapis service method funnels through it → the real network). The deeper `googleapis`
+  // service chains (`calendar.events.insert()`) resolve their verb into the `googleapis` package, but
+  // those verbs are GENERIC (insert/list/get/update) and shared with pure builders — modeling them by
+  // name would fabricate; the actual network is the gaxios/createAPIRequest transport, modeled here, so
+  // a googleapis call that reaches the wire does so through a modeled unit when its source is scanned.
+  [/^gaxios$/, /^(request|get|post|put|patch|delete|head)$/, "Net"],
+  [/^googleapis-common$/, /^createAPIRequest$/, "Net"],
+  // google-auth-library mints/refreshes OAuth tokens and verifies ID tokens over the network. The
+  // verb surface only (the GoogleAuth/OAuth2Client/JWT constructors are config — inert until a verb).
+  [/^google-auth-library$/,
+   /^(request|getClient|getAccessToken|getRequestHeaders|authorize|refreshAccessToken|refreshToken|getTokenInfo|verifyIdToken|fetchIdToken|getCredentials|getProjectId|getSignedJwt)$/,
+   "Net"],
+  // stripe: methods land on a `new Stripe()` instance's resource chains
+  // (`stripe.customers.create()`, `stripe.checkout.sessions.create()`, `charges.*`, `paymentIntents.*`).
+  // A chained member call resolves its verb's DECLARATION into the `stripe` package (declModule keys on
+  // the source file, not the chain depth — verified), so keying on stripe's resource VERBS catches the
+  // deep chains. VERB-precise: the I/O verbs only (the SDK's resources share these); pure helpers
+  // (toString/JSON) and inert `new Stripe()` construction stay pure.
+  [/^stripe$/,
+   /^(create|retrieve|update|list|listLineItems|listPaymentMethods|del|delete|cancel|capture|confirm|expire|finalizeInvoice|pay|sendInvoice|markUncollectible|voidInvoice|refund|reverse|verify|search|approve|decline|attach|detach|deactivate)$/,
+   "Net"],
+  // error/telemetry SaaS — the capture/flush verbs ship the payload over the network. init/config are
+  // inert. @sentry/* re-exports captureException etc. from @sentry/core/@sentry/browser, so a consumer's
+  // import may resolve into any @sentry sub-package — match the whole scope, verb-precise.
+  [/^@sentry\/[^/]+$/,
+   /^(captureException|captureMessage|captureEvent|captureCheckIn|flush|close)$/, "Net"],
+  // posthog-node: capture/identify/group enqueue then flush over HTTP; flush/shutdown/captureImmediate
+  // and the feature-flag fetches (isFeatureEnabled/getFeatureFlag*) hit the API. Verb-precise; the
+  // `new PostHog()` ctor is inert (config).
+  [/^posthog-node$/,
+   /^(capture|captureImmediate|identify|identifyImmediate|alias|groupIdentify|flush|shutdown|isFeatureEnabled|getFeatureFlag|getFeatureFlagPayload|getAllFlags|getAllFlagsAndPayloads|getRemoteConfigPayload|reloadFeatureFlags)$/,
+   "Net"],
   [/^(pg|mysql2?|mongodb|ioredis|redis|sqlite3|better-sqlite3|knex)$/, null, "Db"],
+  // bull/bullmq are Redis-backed job queues — the queue/worker/job ops issue Redis commands (Db). Their
+  // surface is almost entirely I/O, but be VERB-precise (the I/O ops) so inert event-wiring
+  // (`queue.on(...)`) and `new Queue()`/`new Worker()` construction (which only opens a lazy connection)
+  // don't fabricate. The connection IS Redis — Db, consistent with the ioredis/redis classification.
+  [/^(bull|bullmq)$/,
+   /^(add|addBulk|getJob|getJobs|getJobCounts|getJobCountByTypes|getWaiting|getActive|getCompleted|getFailed|getDelayed|getWaitingChildren|getRepeatableJobs|removeRepeatable|removeRepeatableByKey|getMetrics|count|pause|resume|isPaused|drain|clean|obliterate|empty|close|remove|retry|retryJobs|promote|moveToCompleted|moveToFailed|updateData|updateProgress|process|waitUntilReady|getState|getDependencies|getChildrenValues)$/,
+   "Db"],
   [/^(execa|cross-spawn|shelljs)$/, null, "Exec"],
+  // the `open` package spawns the OS handler (xdg-open/open/start) — Exec. Default export `open(target)`
+  // resolves to member `open` (its declared fn name — verified); `openApp` likewise. The `apps` const is
+  // pure (a property read, never a call).
+  [/^open$/, /^(open|openApp)$/, "Exec"],
   [/^(fs-extra|graceful-fs|rimraf|glob|chokidar)$/, null, "Fs"],
   [/^dotenv$/, null, "Env"],
   [/^(winston|pino|bunyan|npmlog)$/, null, "Log"],
+  // nest-winston wraps winston; the injected logger's level verbs are the Log boundary (the
+  // WinstonModule.createLogger/forRoot config is inert).
+  [/^nest-winston$/, /^(log|info|warn|error|debug|verbose|silly|http)$/, "Log"],
   // entropy: node:crypto's random surface + the password-hashing libs (salted -> Rand). Found by
   // the CTA dogfood on a Nest app: argon2.hash came out SILENTLY PURE (the curated-kappa caveat
   // landing on exactly the call a security review cares about).
@@ -78,6 +127,14 @@ export const KAPPA_RULES = [
   // were silently pure inside the covered `crypto` module (the κ-coverage floor can't tell an unmodeled
   // entropy draw from a pure unmodeled member; the fix is to MODEL the member, not drop coverage).
   [/^(node:)?crypto$/, /^(random|getRandomValues|generateKey|generatePrime)/, "Rand"],
+  // uuid: the random-based generators draw from the CSPRNG (v4) / clock+MAC+random (v1) / random (v6/v7).
+  // v3 (MD5) and v5 (SHA-1) are DETERMINISTIC namespace hashes — same input, same UUID — so they are
+  // PURE and excluded. parse/stringify/validate/version/NIL/MAX are pure too (not matched).
+  [/^uuid$/, /^(v1|v4|v6|v7)$/, "Rand"],
+  // nanoid: nanoid()/customRandom() draw from crypto.getRandomValues; customAlphabet() returns a
+  // generator that does the same. `nanoid/non-secure` uses Math.random — still Rand. The `urlAlphabet`
+  // const is pure (a property read). Sound over-approximation: the factory call is the resolvable site.
+  [/^nanoid(\/non-secure)?$/, /^(nanoid|customAlphabet|customRandom)$/, "Rand"],
   // node:os identity reads — userInfo (the OS user record) and hostname (the machine name) are
   // environment/host reads (Env), like System.getenv's host-identity cousins. The rest of node:os
   // (platform/arch/cpus/totalmem/…) is inert host introspection, left pure.

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
@@ -1453,9 +1453,25 @@ function visitCalls(node) {
                : (decl.name ? decl.name.getText() : ""))
             : "";
           const isConstruction = ts.isConstructorDeclaration(decl) || ts.isNewExpression(node);
+          // The κ member token. A named decl (function/method declaration) carries its own name; but a
+          // VALUE-BINDING export — `export const v4 = (...) => ...` (the shape REAL uuid v9+/nanoid ship,
+          // and the `type v4 = v4Buffer & v4String` callable type-alias of @types/uuid v8) resolves to an
+          // ANONYMOUS arrow/function-type whose `decl.name` is empty, so κ saw `""` and the package's
+          // entropy/net verb read silent-pure (verified against installed uuid/nanoid). Fall back to the
+          // BINDING name: an arrow/fn-expr's parent VariableDeclaration / PropertyAssignment / property,
+          // or a callable type-alias's TypeAliasDeclaration. Precision no-op where the old path already
+          // had a name (this only fills a former `""`); never synthesizes a name for `new`.
+          const bindingName = (d) => {
+            const p = d.parent;
+            if (!p) return "";
+            if ((ts.isVariableDeclaration(p) || ts.isPropertyDeclaration(p) || ts.isPropertyAssignment(p)
+                 || ts.isPropertySignature(p) || ts.isBindingElement(p) || ts.isTypeAliasDeclaration(p))
+                && p.name && ts.isIdentifier(p.name)) return p.name.getText();
+            return "";
+          };
           const member = isConstruction
             ? (CONNECTING_CTORS.has(ctorClassName) ? ctorClassName : "new")
-            : (decl.name ? decl.name.getText() : "");
+            : (decl.name ? decl.name.getText() : bindingName(decl));
           let eff = kappa(mod, member); // (CLASSIFY)
           // process.stdout/stderr/stdin are typed `tty.WriteStream`, which EXTENDS `net.Socket`, so a
           // `.write()`/`.end()` on them resolves to `net.Socket.write` and the whole-module Net rule
@@ -1919,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();