candor-ts 0.5.11 → 0.5.13

package/AGENTS.md

@@ -144,7 +144,10 @@ curated-κ caveat cuts the other way:** a call into an npm package κ doesn't kn
 NOTHING — invisible, not `Unknown`. The scan's receipt now DISCLOSES these by name (`κ doesn't
 know N packages…`), so the blind spots are per-scan evidence, not a doc footnote: never conclude
 "no effect" through a package that line names (the documented weaker edge of the
-never-silently-pure promise, same as every candor engine's curated classifier). An uncurated
+never-silently-pure promise, same as every candor engine's curated classifier). Each function ALSO
+carries an `invisible` list — the κ-unknown packages it (transitively) reaches — so `inferred` is
+never an unqualified claim PER FUNCTION: `inferred: []` with a non-empty `invisible` means "pure as
+far as candor could see, but it could not see through these" (a LOWER bound), not "pure". An uncurated
 dependency can opt out of that blind spot by declaring `"candorEffects": ["Net", …]` in its
 `package.json` (the §5.1 effect manifest, read declared-not-verified) — its calls then classify to
 the declared set instead of contributing nothing.

package/package.json

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

package/policy.mjs

@@ -103,7 +103,7 @@ export function literalAllowed(effect, reached, values) {
  * transitive inferred; AS-EFF-008 allowlists over the transitive literal surfaces, the no-visible-
  * literal case flagged as uncertifiable; AS-EFF-009 forbid by reachability). One line per violation.
  */
-export function evaluatePolicy(pol, functions, callgraph) {
+export function evaluatePolicy(pol, functions, callgraph, incomplete = new Map()) {
   const out = [];
   const surfaces = { Net: "hosts", Exec: "cmds", Fs: "paths", Db: "tables" };
   for (const f of functions) {
@@ -116,7 +116,11 @@ export function evaluatePolicy(pol, functions, callgraph) {
       if (r.scope && !scopeMatches(f.fn, r.scope)) continue;
       if (!f.inferred.includes(r.effect)) continue;
       const reached = f[surfaces[r.effect]] ?? [];
-      if (reached.length === 0) {
+      // An INCOMPLETE surface (a structurally-invisible reach — a host-establishing call with a runtime/
+      // invisible host) can't be certified even with visible hosts, else a benign literal masks the
+      // invisible forbidden endpoint (the masking evasion). Matches candor-java 0.5.29 / candor-rust.
+      const surfaceIncomplete = incomplete.get(f.fn)?.has(r.effect);
+      if (reached.length === 0 || surfaceIncomplete) {
         out.push(`[AS-EFF-008] \`${f.fn}\` performs ${r.effect} with no visible literal — the surface cannot be certified: \`${r.raw}\``);
       } else {
         const bad = reached.filter((v) => !literalAllowed(r.effect, v, r.values));

package/scan.mjs

@@ -464,7 +464,7 @@ for (const sf of sources) {
         const { line, character } = sf.getLineAndCharacterOfPosition(node.getStart());
         fns.set(ctorQual, { local: `${node.name.text}.constructor`, direct: new Set(), edges: new Set(),
                             hosts: new Set(), tables: new Set(), cmds: new Set(), paths: new Set(),
-                            why: new Set(), entry: false,
+                            blind: new Set(), incomplete: new Set(), why: new Set(), entry: false,
                             loc: `${path.relative(rootDir, sf.fileName)}:${line + 1}:${character + 1}` });
       }
       nodeName.set(node, ctorQual);
@@ -475,7 +475,7 @@ for (const sf of sources) {
       const qual = `${mod}.${n}`;
       const { line, character } = sf.getLineAndCharacterOfPosition(node.getStart());
       fns.set(qual, { local: n, direct: new Set(), edges: new Set(), hosts: new Set(), tables: new Set(),
-                      cmds: new Set(), paths: new Set(), why: new Set(), entry: false, isCjsExport,
+                      cmds: new Set(), paths: new Set(), blind: new Set(), incomplete: new Set(), why: new Set(), entry: false, isCjsExport,
                       loc: `${path.relative(rootDir, sf.fileName)}:${line + 1}:${character + 1}` });
       nodeName.set(node, qual);
       if ((ts.isVariableDeclaration(node) || ts.isPropertyDeclaration(node)) && node.initializer)
@@ -788,6 +788,27 @@ function visitCalls(node) {
             if (t) rec.edges.add(t);
           }
         }
+        // `fn.call(thisArg, …)` / `fn.apply(thisArg, args)` INVOKE the receiver function reference, and
+        // `Reflect.apply(fn, …)` / `Reflect.construct(Ctor, …)` invoke their FIRST ARGUMENT. The resolved
+        // signature lands on the es-lib `CallableFunction.call/apply` / `Reflect.apply` member, so the
+        // function actually invoked (the receiver, or arg0) was never followed → the caller read
+        // silent-pure (HIGH: a common reflective-invoke shape). Edge to the referenced unit, mirroring the
+        // HOF-ref arm: a pure ref edges to a pure unit (no fabrication); a non-fn receiver/arg resolves to
+        // no minted unit (`nodeName` miss) and adds nothing; an unresolvable ref stays opaque/Unknown.
+        if (ts.isPropertyAccessExpression(node.expression)) {
+          const m = node.expression.name.text;
+          const recv = node.expression.expression;
+          const recvText = recv.getText().replace(/\s+/g, "");
+          let invokedRef = null;
+          if ((m === "call" || m === "apply") && recvText !== "Reflect") invokedRef = recv;
+          else if (recvText === "Reflect" && (m === "apply" || m === "construct"))
+            invokedRef = (node.arguments ?? [])[0] ?? null;
+          if (invokedRef && (ts.isIdentifier(invokedRef) || ts.isPropertyAccessExpression(invokedRef))) {
+            const d2 = realDecl(checker.getSymbolAtLocation(invokedRef));
+            const t = d2 && nodeName.get(d2);
+            if (t) rec.edges.add(t);
+          }
+        }
         if (mod === "<local>") {
           const targetName = nodeName.get(decl);
           if (targetName) {
@@ -933,6 +954,19 @@ function visitCalls(node) {
           if (ts.isNewExpression(node) && (node.arguments ?? []).length === 0
               && checker.getTypeAtLocation(node.expression)?.symbol?.name === "DateConstructor")
             rec.direct.add("Clock");
+          // Browser/runtime NETWORK globals declared in lib.dom — no importable module for the κ table to
+          // key on, so they read SILENT-PURE. `XMLHttpRequest.send`/`.open` issue the HTTP request; the
+          // `EventSource`/`WebSocket` constructors open a connection on construction. Net. (Found by a
+          // Net-deep sweep. The npm `ws` package is already κ-covered; this is the bare browser global.)
+          if (parent === "XMLHttpRequest" && (name === "send" || name === "open")) rec.direct.add("Net");
+          // `new EventSource(url)` / `new WebSocket(url)`: the constructor is declared on an anonymous
+          // `declare var` object type (symbol `__type`, no usable parent name), but reaching the es-lib
+          // branch already proves the ctor resolved to lib.dom (not a project class shadowing the name),
+          // so the constructed identifier is the real browser global.
+          if (ts.isNewExpression(node)) {
+            const ctorName = node.expression.getText();
+            if (ctorName === "EventSource" || ctorName === "WebSocket") rec.direct.add("Net");
+          }
         } else {
           // The member token κ matches: the resolved declaration's name, EXCEPT a `new X()` call,
           // whose declaration is a Constructor (empty name) — synthesize "new" so a rule can exempt
@@ -946,6 +980,9 @@ function visitCalls(node) {
           // needs no entry here. Inert ctors (Agent/Server/Socket/TLSSocket/Http2Server*/message shells)
           // still synthesize "new" and stay pure.
           const CONNECTING_CTORS = new Set(["ClientRequest"]);
+          // Host-ESTABLISHING Net call names (the masking-fix allowlist): a Net call by one of these whose
+          // host is not a captured literal leaves the host invisible. Excludes use-verbs (write/end/send).
+          const NET_ESTABLISHING = new Set(["request", "get", "connect", "createConnection", "fetch"]);
           const ctorClassName = ts.isNewExpression(node)
             ? (ts.isConstructorDeclaration(decl) ? decl.parent?.name?.getText?.()
                : (decl.name ? decl.name.getText() : ""))
@@ -971,6 +1008,14 @@ function visitCalls(node) {
             const lit = firstStringLiteral(node);
             const h = lit && hostLiteral(lit);
             if (h) rec.hosts.add(h);
+            // MASKING fix: a host-ESTABLISHING Net call whose host is NOT a captured literal (runtime URL, or
+            // built elsewhere) leaves the host invisible to the gate → mark the surface incomplete so a
+            // benign literal can't mask it. ALLOWLIST of establishing forms only (request/get/connect/
+            // createConnection/fetch + the connecting ctor) — NEVER use-calls (write/end/send), which would
+            // false-positive on `socket.connect("h").write(data)` (the host is captured at connect). Under-
+            // catches an unlisted establishing verb (safe direction); never over-flags a use-call.
+            else if (NET_ESTABLISHING.has(member) || CONNECTING_CTORS.has(ctorClassName))
+              rec.incomplete.add("Net");
           }
           if (eff === "Db") {
             const lit = firstStringLiteral(node);
@@ -1045,6 +1090,11 @@ function visitCalls(node) {
             } else if (!kappaKnows(pkg) && !depCoveredPkgs.has(pkg)
                 && /node_modules\//.test(file) && !/node_modules\/(@types\/node|typescript)\//.test(file)) {
               unlistedSeen.set(pkg, (unlistedSeen.get(pkg) ?? 0) + 1);
+              // Per-fn HONESTY: this fn calls into a genuinely-blind package (κ-unknown, not dep-covered).
+              // Recorded per fn, propagated transitively, emitted as `invisible` — so `inferred` is never an
+              // unqualified completeness claim. This branch already IS the global-blind condition, so no
+              // post-filter is needed (κ either knows a package or it doesn't).
+              rec.blind.add(pkg);
             }
           }
         }
@@ -1087,6 +1137,11 @@ function visitCalls(node) {
              && !(checker.getSymbolAtLocation(callee)?.declarations ?? [])
                   .some((d) => projectFiles.has(path.resolve(d.getSourceFile().fileName))))
       geff = "Net";
+    // the fully-qualified global fetch — `globalThis.fetch`/`window.fetch`/`self.fetch` — is a
+    // PropertyAccess callee the bare-identifier guard above misses, so it read silent-pure. Mirror the
+    // `eval` global-qualifier handling (a runtime global a project would not shadow).
+    else if (ctext === "globalThis.fetch" || ctext === "window.fetch" || ctext === "self.fetch")
+      geff = "Net";
     if (geff) {
       const owner = enclosing(node);
       if (owner) fns.get(owner).direct.add(geff);
@@ -1232,7 +1287,7 @@ while (changed) {
         if (!mine.has(e)) { mine.add(e); changed = true; }
   }
 }
-for (const m of ["hosts", "tables", "cmds", "paths"]) {
+for (const m of ["hosts", "tables", "cmds", "paths", "blind", "incomplete"]) {
   let moved = true;
   while (moved) {
     moved = false;
@@ -1247,7 +1302,9 @@ for (const m of ["hosts", "tables", "cmds", "paths"]) {
 const functions = [];
 for (const [name, rec] of fns) {
   const inf = [...inferred.get(name)].sort();
-  if (inf.length === 0 && !rec.entry) continue; // entry points stay visible even when pure
+  // entry points stay visible even when pure; a BLIND fn stays too, so the honesty disclosure survives
+  // on exactly the `inferred: []` fns that need it.
+  if (inf.length === 0 && !rec.entry && rec.blind.size === 0) continue;
   const entry = {
     fn: name,
     loc: rec.loc,
@@ -1264,6 +1321,9 @@ for (const [name, rec] of fns) {
   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();
+  // 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();
   if (rec.entry) entry.entryPoint = true;
   if (rec.isCjsExport) entry.unitKind = "export"; // spec 0.5 draft, informative — per-unit, not by name
   functions.push(entry);
@@ -1300,7 +1360,11 @@ if (policyPath) {
     console.error(`candor-ts: policy ${policyPath} could not be read; gate NOT enforced`);
     process.exit(2);
   }
-  const v = evaluatePolicy(parsePolicy(text), functions, cg);
+  // The masking-incompleteness map (fn -> effects whose surface is incomplete), kept INTERNAL like the
+  // java/rust engines (not a report field) — passed to the gate so an incomplete surface fails closed.
+  const incompleteMap = new Map();
+  for (const [name, rec] of fns) if (rec.incomplete.size) incompleteMap.set(name, rec.incomplete);
+  const v = evaluatePolicy(parsePolicy(text), functions, cg, incompleteMap);
   for (const line of v) console.log(line);
   if (v.length) {
     console.error(`candor-ts: ${v.length} policy violation(s)`);