candor-ts 0.5.12 → 0.5.14

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.12",
+  "version": "0.5.14",
   "description": "candor for TypeScript — per-function side effects, transitively, with a policy gate (candor-spec 0.5)",
   "type": "module",
   "dependencies": {

package/policy.mjs

@@ -14,7 +14,11 @@ const ASCII_WS = /[ \t\n\v\f\r]+/;
 const ASCII_WS_TRIM = /^[ \t\n\v\f\r]+|[ \t\n\v\f\r]+$/g;
 export function parsePolicy(text) {
   const deny = [], allow = [], forbid = [];
-  for (const rawLine of text.split("\n")) {
+  // Split LINES on \n / \r\n / bare \r — the three forms Java's Files.readAllLines (the reference parser)
+  // breaks on. Splitting on \n ONLY let a classic-Mac (bare-\r) file collapse to one line: \r is also an
+  // in-line ASCII-ws token separator (below), so every rule after the first was glued into the first rule's
+  // tokens and dropped — a gateless-green divergence (sweep [16]/[17]). \v/\f stay in-line separators.
+  for (const rawLine of text.replace(/\r\n/g, "\n").replace(/\r/g, "\n").split("\n")) {
     const line = rawLine.split("#")[0].replace(ASCII_WS_TRIM, "");
     if (!line) continue;
     const t = line.split(ASCII_WS);
@@ -103,7 +107,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 +120,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-core.mjs

@@ -39,7 +39,14 @@ export const KAPPA_RULES = [
   // FABRICATED Net — the cardinal sin — purely from this classification, with no local Net edge). Only
   // these three named validators are freed; every genuine verb (connect/createConnection/createServer…)
   // stays Net (the matcher excludes ONLY new + the three validators, nothing else).
-  [/^(node:)?(net|dgram|tls|http2?|https)$/, /^(?!(new|isIP|isIPv4|isIPv6)$)/, "Net"],
+  // ALSO exempt the pure CONFIG/METADATA members the whole-module rule fabricated Net on (sweep [9], the
+  // cardinal sin — none touch a socket/fd/syscall): tls.getCiphers/createSecureContext/checkServerIdentity
+  // (cipher-list + cert helpers), http.validateHeaderName/validateHeaderValue (string validators, like
+  // isIP), and a Socket/Server's setKeepAlive/setNoDelay/ref/unref/address (TCP-option + bound-address
+  // metadata — no I/O). Every genuine verb still classifies; only these proven-pure names are freed.
+  [/^(node:)?(net|dgram|tls|http2?|https)$/,
+   /^(?!(new|isIP|isIPv4|isIPv6|getCiphers|createSecureContext|checkServerIdentity|validateHeaderName|validateHeaderValue|setKeepAlive|setNoDelay|ref|unref|address)$)/,
+   "Net"],
   // node:dns — name resolution is NETWORK I/O (lookup/lookupService hit the OS resolver; resolve*/
   // reverse query DNS servers directly). Was unclassified, so a `dns.resolve(...)` read silently pure.
   // Same construction-and-pure-accessor carve-out as the net cluster: `new dns.Resolver()` ("new") is

package/scan.mjs

@@ -305,6 +305,25 @@ function firstStringLiteral(node) {
   return null;
 }
 
+// Is this property/element access a SETTER target reached through a destructuring assignment —
+// `({ k: x.prop } = src)` or `[x.prop] = arr` (sweep [32])? Walk up through PropertyAssignment /
+// Object|ArrayLiteral wrappers to the enclosing `=`; it is a target only when the wrapping literal is the
+// LHS (`.left`) of the assignment. A property access on the RHS (`src = { k: x.prop }`) walks to a literal
+// that is `.right`, so it stays a getter READ — no false setter attribution.
+function isDestructuringAssignTarget(node) {
+  let cur = node, parent = node.parent;
+  while (parent) {
+    if (ts.isPropertyAssignment(parent) && parent.initializer === cur) { cur = parent; parent = parent.parent; continue; }
+    if (ts.isShorthandPropertyAssignment(parent)) return false; // `{prop}` has no access node to attribute
+    if (ts.isSpreadAssignment(parent) || ts.isSpreadElement(parent)) { cur = parent; parent = parent.parent; continue; }
+    if (ts.isObjectLiteralExpression(parent) || ts.isArrayLiteralExpression(parent)) { cur = parent; parent = parent.parent; continue; }
+    if (ts.isBinaryExpression(parent) && parent.operatorToken.kind === ts.SyntaxKind.EqualsToken)
+      return parent.left === cur;
+    return false;
+  }
+  return false;
+}
+
 // The literal PROGRAM head a subprocess call NAMES — argv[0] specifically, never a later argument.
 // Unlike firstStringLiteral (the first literal ANYWHERE in the args), this refuses to refine when
 // the program (arg0) is a runtime value but a trailing arg is a literal whose basename hits the head
@@ -464,7 +483,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 +494,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)
@@ -754,8 +773,22 @@ function visitCalls(node) {
           // `new ExternalClass()` with an implicit ctor: same posture as an explicit external ctor
           // the classifier doesn't know — OPAQUE (contributes nothing), not Unknown. Consistency:
           // whether a library declares its ctor must not change the verdict.
-          else if (cd && ts.isClassDeclaration(cd) && !projectFiles.has(path.resolve(cd.getSourceFile().fileName)))
+          else if (cd && ts.isClassDeclaration(cd) && !projectFiles.has(path.resolve(cd.getSourceFile().fileName))) {
             externalClass = true;
+            // …but the construction DOES reach the class's package — disclose it as `invisible` (sweep
+            // [13]) so the pure verdict is qualified, exactly like an unmodeled METHOD call below. Without
+            // this, `new Pool()` from an unmodeled pkg read plain pure with no disclosure, no κ-ledger.
+            const cfile = cd.getSourceFile().fileName;
+            const cmod = declModule(cd);
+            const cpkg = cmod.startsWith("@types/") ? cmod.slice("@types/".length) : cmod;
+            const cdeclared = packageManifestEffects(cfile);
+            if (cdeclared !== null) { for (const e of cdeclared) rec.direct.add(e); }
+            else if (!cmod.startsWith("<") && !kappaKnows(cpkg) && !depCoveredPkgs.has(cpkg)
+                && /node_modules\//.test(cfile) && !/node_modules\/(@types\/node|typescript)\//.test(cfile)) {
+              unlistedSeen.set(cpkg, (unlistedSeen.get(cpkg) ?? 0) + 1);
+              rec.blind.add(cpkg);
+            }
+          }
         }
         if (!edged && !externalClass) {
           rec.direct.add("Unknown"); // unresolvable call → Unknown, never silent-pure (SPEC §4)
@@ -980,6 +1013,25 @@ 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 on
+          // a connected socket). `post/put/patch/delete/head/options` cover the axios/got/undici tier whose
+          // URL is the call arg (sweep [18]); `dgram.send(buf,port,host)` is added module-aware below (UDP
+          // has no connect, so send carries the destination — sweep [12]).
+          const NET_ESTABLISHING = new Set(["request", "get", "post", "put", "patch", "delete", "head",
+            "options", "connect", "createConnection", "fetch"]);
+          // Fs/Exec USE-verbs whose LOCATOR was fixed earlier, not an arg of THIS call — so a missing literal
+          // here is the legitimate split-construct/use shape, never the masking signal (the establishing-
+          // allowlist discipline, generalized from Net to all 4 effects; sweep [11]). Fs: the fd/FileHandle
+          // ops (fd came from open()); the path-taking fs.* fns are establishing. Exec: ChildProcess methods
+          // (the command was fixed at spawn); the spawn fns are establishing.
+          const FS_USE_VERBS = new Set(["write", "writeSync", "read", "readSync", "close", "closeSync",
+            "fsync", "fsyncSync", "fdatasync", "fdatasyncSync", "ftruncate", "ftruncateSync", "fchmod",
+            "fchmodSync", "fchown", "fchownSync", "futimes", "futimesSync", "fstat", "fstatSync"]);
+          const EXEC_USE_VERBS = new Set(["kill", "send", "disconnect", "ref", "unref"]);
+          const netEstablishing = (member) =>
+            CONNECTING_CTORS.has(ctorClassName) || NET_ESTABLISHING.has(member)
+            || (/^(node:)?dgram$/.test(mod) && member === "send");
           const ctorClassName = ts.isNewExpression(node)
             ? (ts.isConstructorDeclaration(decl) ? decl.parent?.name?.getText?.()
                : (decl.name ? decl.name.getText() : ""))
@@ -1005,9 +1057,18 @@ 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 — NEVER use-calls
+            // (write/end/non-dgram 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 (netEstablishing(member))
+              rec.incomplete.add("Net");
           }
           if (eff === "Db") {
             const lit = firstStringLiteral(node);
+            const before = rec.tables.size;
             for (const t of lit ? tablesInSql(lit) : []) rec.tables.add(t);
             // ORM route: `this.userRepository.find(…)` — the receiver's `Repository<UserEntity>`
             // type argument names the entity; its `@Entity("user")` decorator names the table.
@@ -1019,6 +1080,11 @@ function visitCalls(node) {
                 if (tbl) rec.tables.add(tbl);
               }
             }
+            // masking: a Db call that surfaced NO table (no SQL literal, no entity-typed receiver) reaches a
+            // runtime/invisible table — a benign sibling query's literal table must not mask it. The entity
+            // route above is NOT a literal so it still counts as visible (a captured table); only a fully
+            // invisible query marks incomplete. `new` (a connection ctor) carries no table — skip it.
+            if (rec.tables.size === before && member !== "new") rec.incomplete.add("Db");
           }
           if (eff === "Exec") {
             const lit = firstStringLiteral(node);
@@ -1028,10 +1094,18 @@ function visitCalls(node) {
             // names no static program, so its trailing literal must not fabricate Net (spec §4).
             const head = programHeadLiteral(node);
             if (head) for (const e of commandHeadEffects(head)) rec.direct.add(e);
+            // masking (sweep [11]): an Exec call whose program head is NOT a static literal (runtime
+            // command) leaves the command invisible. Establishing = the spawn fns; ChildProcess use-verbs
+            // (kill/send/disconnect/ref/unref) carry no command and are excluded.
+            else if (!EXEC_USE_VERBS.has(member)) rec.incomplete.add("Exec");
           }
           if (eff === "Fs") {
             const lit = firstStringLiteral(node);
-            if (lit && /[/\\]|^[.~]/.test(lit)) rec.paths.add(lit); // path-shaped literals only
+            const pathCaptured = lit && /[/\\]|^[.~]/.test(lit); // path-shaped literals only
+            if (pathCaptured) rec.paths.add(lit);
+            // masking (sweep [11]): a path-taking fs.* call whose path is NOT a captured literal (runtime
+            // path) leaves it invisible. fd/FileHandle USE-verbs (fd came from a prior open()) are excluded.
+            else if (!FS_USE_VERBS.has(member)) rec.incomplete.add("Fs");
           }
           // CANDOR_DEPS: an unclassified call into a package with a loaded sibling report inherits
           // that function's recorded transitive effects (+ literal surfaces) by `hash`.
@@ -1079,6 +1153,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);
             }
           }
         }
@@ -1115,8 +1194,19 @@ function visitCalls(node) {
     const callee = node.expression;
     const ctext = callee.getText().replace(/\s+/g, "");
     let geff = null;
-    if (ctext === "process.hrtime" || ctext === "process.hrtime.bigint") geff = "Clock";
-    else if (ctext === "process.send") geff = "Ipc";
+    // `process.*` is matched by exact text, so a project's OWN `const process = {…}` shadow would
+    // fabricate Clock/Ipc on a pure local method (sweep [31]) — guard it like the `fetch` arm: resolve the
+    // ROOT `process` identifier and fire only when it is NOT a project-local declaration (i.e. the global).
+    const processIsGlobal = () => {
+      if (!ts.isPropertyAccessExpression(callee)) return false;
+      let root = callee.expression;
+      while (ts.isPropertyAccessExpression(root)) root = root.expression; // process.hrtime.bigint → process
+      if (!ts.isIdentifier(root) || root.text !== "process") return false;
+      return !(checker.getSymbolAtLocation(root)?.declarations ?? [])
+        .some((d) => projectFiles.has(path.resolve(d.getSourceFile().fileName)));
+    };
+    if ((ctext === "process.hrtime" || ctext === "process.hrtime.bigint") && processIsGlobal()) geff = "Clock";
+    else if (ctext === "process.send" && processIsGlobal()) geff = "Ipc";
     else if (ts.isIdentifier(callee) && callee.text === "fetch"
              && !(checker.getSymbolAtLocation(callee)?.declarations ?? [])
                   .some((d) => projectFiles.has(path.resolve(d.getSourceFile().fileName))))
@@ -1145,21 +1235,28 @@ function visitCalls(node) {
   // call), never silently pure. A resolved-but-UNSEEN accessor (external declaration) reads Unknown,
   // following the same posture as an unresolvable call (SPEC §4).
   if (ts.isPropertyAccessExpression(node) || ts.isElementAccessExpression(node)) {
-    // Is this property access the TARGET of an assignment (`x.prop = v`)? If so it's a setter site;
-    // otherwise it's a read (getter) site. (`x.prop += v` is both a read and a write, but the read
-    // side is the produced value — model it as a setter target only when it is the bare LHS of `=`.)
+    // Is this property access an assignment TARGET? A simple `x.prop = v` invokes the SETTER only. A
+    // COMPOUND/LOGICAL assignment (`+=`,`-=`,`??=`,`||=`,`&&=`,…) reads the current value AND writes — both
+    // the getter and the setter run (sweep [10]; pre-fix only a bare `=` was a setter site, so an effectful
+    // setter under `+=`/`??=` read PURE). A DESTRUCTURING-assignment target (`({k: x.prop} = src)` /
+    // `[x.prop] = arr`) is also a setter site, invisible to the simple-LHS test (sweep [32]).
     const p = node.parent;
-    const isAssignTarget = p && ts.isBinaryExpression(p) && p.left === node
-      && p.operatorToken.kind === ts.SyntaxKind.EqualsToken;
-    const hit = isAssignTarget ? accessorAt(node, "set") : accessorAt(node, "get");
-    if (hit) {
+    const isBinAssign = p && ts.isBinaryExpression(p) && p.left === node;
+    const simpleAssign = isBinAssign && p.operatorToken.kind === ts.SyntaxKind.EqualsToken;
+    const compoundAssign = isBinAssign && !simpleAssign
+      && p.operatorToken.kind >= ts.SyntaxKind.FirstAssignment && p.operatorToken.kind <= ts.SyntaxKind.LastAssignment;
+    const recordKind = (kind) => {
+      const hit = accessorAt(node, kind);
+      if (!hit) return;
       const owner = enclosing(node);
-      if (owner) {
-        const an = hit.decl.parent?.name?.getText?.() ?? "?";
-        const pn = node.name?.getText?.() ?? node.argumentExpression?.getText?.() ?? "?";
-        recordAccessorHit(owner, hit, `${an}.${pn}`);
-      }
-    }
+      if (!owner) return;
+      const an = hit.decl.parent?.name?.getText?.() ?? "?";
+      const pn = node.name?.getText?.() ?? node.argumentExpression?.getText?.() ?? "?";
+      recordAccessorHit(owner, hit, `${an}.${pn}`);
+    };
+    if (simpleAssign || isDestructuringAssignTarget(node)) recordKind("set");
+    else if (compoundAssign) { recordKind("get"); recordKind("set"); }
+    else recordKind("get");
   }
   // OBJECT-DESTRUCTURING getter read (`const { prop } = obj`): each bound property is a READ that may
   // resolve to a getter whose body does I/O — the binding-pattern analog of `obj.prop`, invisible to
@@ -1271,7 +1368,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;
@@ -1286,7 +1383,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,
@@ -1303,6 +1402,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);
@@ -1339,7 +1441,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)`);