candor-ts 0.5.4 → 0.5.6

package/mcp.mjs

@@ -45,6 +45,20 @@ function resolvePrefix(args) {
   if (!hasReport(p)) throw new Error(`no report at \`${p}\` (.json or .<crate>.scan.json) — run a candor scan first`);
   return p;
 }
+// Truncate a caller-supplied value echoed back in an error (a multi-MB `fn` would otherwise be reflected
+// verbatim — token/memory amplification over the agent transport, the opposite of the list-cap thrift).
+const clip = (s, n = 120) => { s = String(s); return s.length > n ? s.slice(0, n) + "…" : s; };
+// Read a caller-supplied policy file CONFINED to the report's directory tree. The MCP surface is
+// report-query-only (spec §7.12); an arbitrary `policy` path (/etc/passwd, ~/.aws/credentials) whose
+// parsed deny-rule scopes are reflected back in violations[].rule is an arbitrary-file-read exfiltration
+// channel — tie the policy to the project it gates.
+function confinedPolicyRead(policyPath, prefix) {
+  const root = nodePath.resolve(nodePath.dirname(prefix));
+  const abs = nodePath.resolve(policyPath);
+  if (abs !== root && !abs.startsWith(root + nodePath.sep))
+    throw new Error(`policy must be within the report's directory (${root}) — refusing to read \`${clip(policyPath)}\``);
+  return fs.readFileSync(abs, "utf8");
+}
 
 // ---- the tools: name -> {description, schema, run} ------------------------------------------------
 const reportArg = { report: { type: "string", description: "report prefix (optional; defaults to $CANDOR_REPORT)" } };
@@ -110,9 +124,9 @@ const TOOLS = {
     description: "Hypothetically add `effect` to `fn` and report the blast radius; with `policy`, also the deny-rule violations it would cause. Pre-edit gate check.",
     schema: { type: "object", properties: { fn: { type: "string" }, effect: { type: "string" }, policy: { type: "string", description: "path to a CANDOR_POLICY file (optional)" }, ...reportArg }, required: ["fn", "effect"] },
     run: (a, p) => {
-      const pol = a.policy && fs.existsSync(a.policy) ? parsePolicy(fs.readFileSync(a.policy, "utf8")) : null;
+      const pol = a.policy && fs.existsSync(a.policy) ? parsePolicy(confinedPolicyRead(a.policy, p)) : null;
       const r = Q.whatif(Q.loadCallgraph(p), a.fn, a.effect, pol, scopeMatches);
-      if (r === null) throw new Error(`no function matching \`${a.fn}\` in the call graph`);
+      if (r === null) throw new Error(`no function matching \`${clip(a.fn)}\` in the call graph`);
       return r;
     },
   },
@@ -156,7 +170,7 @@ function handle(msg) {
       if (args.fn !== undefined) {
         const names = [...new Set([...Object.keys(Q.loadCallgraph(prefix)), ...Q.loadReport(prefix).map((e) => e.fn)])];
         if (Q.matches(names, args.fn).length === 0)
-          return result(id, { content: [{ type: "text", text: `candor: no function matching \`${args.fn}\` in this report` }], isError: true });
+          return result(id, { content: [{ type: "text", text: `candor: no function matching \`${clip(args.fn)}\` in this report` }], isError: true });
       }
       const out = t.run(args, prefix);
       // Minified, not pretty-printed: the consumer is an AGENT (it parses the JSON), so the indentation

package/package.json

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

package/scan-core.mjs

@@ -40,6 +40,14 @@ export const KAPPA_RULES = [
   // 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"],
+  // 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
+  // inert, and the SERVER-CONFIG accessors getServers/setServers/get|setDefaultResultOrder touch no
+  // network (in-process config) — classifying them Net would FABRICATE the cardinal sin. Every genuine
+  // resolver verb (lookup/resolve4/resolveMx/reverse/…) stays Net. Covers node:dns/promises too.
+  [/^(node:)?dns(\/promises)?$/,
+   /^(?!(new|getServers|setServers|getDefaultResultOrder|setDefaultResultOrder)$)/, "Net"],
   [/^(node:)?child_process$/, null, "Exec"],
   [/^(node:)?sqlite$/, null, "Db"],
   // the curated npm tier

package/scan.mjs

@@ -323,6 +323,32 @@ const nodeName = new WeakMap();  // declaration node -> qualified name
 const entityTables = new Map();    // ClassDeclaration node -> table name
 const interfaceImpls = new Map();  // InterfaceDeclaration node -> implementing ClassDeclarations (CHA universe)
 const classOverrides = new Map();  // base-method MemberDeclaration node -> overriding subclass member nodes (class-CHA)
+// Resolve `extends X` to X's LOCAL ClassDeclaration (through an import alias), or null. Module-level
+// so both the class-CHA INDEX (below) and the dispatch site's RECEIVER-SUBTREE scoping share one
+// definition of the local inheritance edge.
+function localBaseClassOf(cls) {
+  for (const h of cls.heritageClauses ?? []) {
+    if (h.token !== ts.SyntaxKind.ExtendsKeyword) continue;
+    const t = h.types?.[0];
+    if (!t) continue;
+    let sym = checker.getSymbolAtLocation(t.expression);
+    if (sym && sym.flags & ts.SymbolFlags.Alias) { try { sym = checker.getAliasedSymbol(sym); } catch { /* keep */ } }
+    const bd = (sym?.declarations ?? []).find((d) => ts.isClassDeclaration(d));
+    if (bd && projectFiles.has(path.resolve(bd.getSourceFile().fileName))) return bd;
+  }
+  return null;
+}
+// Is `cls` in the subtree rooted at `root` (i.e. cls === root, or cls transitively `extends` root
+// through LOCAL classes)? Used to scope a base-member override fan-out to the RECEIVER's static type
+// — a sibling subclass's override lives OUTSIDE this subtree and must not contaminate the verdict.
+function classInSubtree(cls, root) {
+  let cur = cls, guard = 0;
+  while (cur && guard++ < 64) {
+    if (cur === root) return true;
+    cur = localBaseClassOf(cur);
+  }
+  return false;
+}
 function moduleOf(sf) {
   const rel = path.relative(rootDir, path.resolve(sf.fileName)).replace(/\.[mc]?[tj]sx?$/, "");
   return rel.split(path.sep).join(".");
@@ -467,19 +493,7 @@ for (const sf of sources) {
 {
   const memberName = (m) => (ts.isMethodDeclaration(m) || ts.isGetAccessorDeclaration(m)
     || ts.isSetAccessorDeclaration(m) || ts.isPropertyDeclaration(m)) && m.name?.getText?.();
-  // Resolve `extends X` to X's LOCAL ClassDeclaration (through an import alias), or null.
-  const baseClassOf = (cls) => {
-    for (const h of cls.heritageClauses ?? []) {
-      if (h.token !== ts.SyntaxKind.ExtendsKeyword) continue;
-      const t = h.types?.[0];
-      if (!t) continue;
-      let sym = checker.getSymbolAtLocation(t.expression);
-      if (sym && sym.flags & ts.SymbolFlags.Alias) { try { sym = checker.getAliasedSymbol(sym); } catch { /* keep */ } }
-      const bd = (sym?.declarations ?? []).find((d) => ts.isClassDeclaration(d));
-      if (bd && projectFiles.has(path.resolve(bd.getSourceFile().fileName))) return bd;
-    }
-    return null;
-  };
+  const baseClassOf = localBaseClassOf;
   for (const sf of sources) {
     (function scan(node) {
       if (ts.isClassDeclaration(node)) {
@@ -563,8 +577,10 @@ function realDecl(sym) {
 // when the accessor's declaration lives in a project file (a UNIT we minted; edge to it). A resolved
 // accessor we CAN'T see (external/typed-only declaration) returns local:false so the caller follows
 // the existing Unknown/curated-κ posture — never silent-pure for a resolved-but-unseen accessor.
-function accessorAt(propNode, kind /* "get" | "set" */) {
-  const sym = checker.getSymbolAtLocation(propNode.name ?? propNode);
+// A property SYMBOL → its accessor declaration of the wanted kind (or null). `local` is true when that
+// declaration lives in a project file (a unit we minted; edge to it). Shared by every property-read
+// shape: dot access, element access, and object destructuring.
+function accessorFromSym(sym, kind /* "get" | "set" */) {
   if (!sym) return null;
   const want = kind === "get" ? ts.isGetAccessorDeclaration : ts.isSetAccessorDeclaration;
   // A symbol is an accessor only if its declarations include an accessor of the wanted kind.
@@ -572,6 +588,34 @@ function accessorAt(propNode, kind /* "get" | "set" */) {
   if (!decl) return null;
   return { decl, local: projectFiles.has(path.resolve(decl.getSourceFile().fileName)) };
 }
+function accessorAt(propNode, kind /* "get" | "set" */) {
+  let sym;
+  if (ts.isElementAccessExpression(propNode)) {
+    // `c["prop"]` carries no `.name`; resolve the LITERAL key as a property on the receiver's type.
+    // A dynamic key (`c[k]`) can't be pinned to one property — leave it unresolved (the existing
+    // dynamic-access posture stands; resolving it would guess, never fabricate here).
+    const arg = propNode.argumentExpression;
+    sym = arg && ts.isStringLiteralLike(arg)
+      ? checker.getTypeAtLocation(propNode.expression)?.getProperty?.(arg.text)
+      : null;
+  } else {
+    sym = checker.getSymbolAtLocation(propNode.name ?? propNode);
+  }
+  return accessorFromSym(sym, kind);
+}
+// Record a resolved accessor HIT (read or write) as an edge from `owner`: into the accessor UNIT when
+// it's a local declaration we minted; otherwise Unknown (a resolved-but-unseen accessor body — never
+// silent-pure, SPEC §4). `label` tags the §-why disclosure.
+function recordAccessorHit(owner, hit, label) {
+  const rec = fns.get(owner);
+  const t = nodeName.get(hit.decl);
+  if (hit.local && t) {
+    rec.edges.add(t); // (EDGE) into the accessor unit — effects propagate
+  } else {
+    rec.direct.add("Unknown");
+    rec.why.add(`accessor:${label}`);
+  }
+}
 
 // nearest enclosing analyzed function (closures attribute to it — SEMANTICS §2)
 function enclosing(node) {
@@ -697,24 +741,48 @@ function visitCalls(node) {
             // receiver already resolved to the leaf (`new Dog()` -> Dog.speak, no overrides) so this is
             // inert there — no double-count. A base method NO subclass overrides has no entry: today's
             // behavior (just the base) is preserved exactly.
-            const overrides = classOverrides.get(decl);
-            if (overrides && overrides.length > 0) {
-              if (overrides.length <= 12) {
-                let allResolved = true;
-                const oTargets = [];
-                for (const om of overrides) {
-                  const ot = nodeName.get(om);
-                  if (ot) oTargets.push(ot);
-                  else allResolved = false;
-                }
-                for (const ot of oTargets) rec.edges.add(ot);
-                if (!allResolved) {
-                  rec.direct.add("Unknown");
+            const allOverrides = classOverrides.get(decl);
+            if (allOverrides && allOverrides.length > 0) {
+              // PRECISION: scope the fan-out to the RECEIVER's static-type subtree. A base-member
+              // dispatch on a receiver statically typed as subclass `Cat` can only ever bind to a
+              // `Cat`-subtree body — a SIBLING `Dog.speak` override is type-impossible on this path,
+              // so propagating its effect over-reports on an unreachable receiver (fabrication-
+              // adjacent). When we can pin the receiver's static class (a property/element access
+              // whose receiver-expression type is a LOCAL class), keep only overrides whose owning
+              // class lies in that class's subtree; `viaBase(a: Animal)` keeps Dog (Dog ∈ Animal-
+              // subtree, the soundness edge), `noOverride(c: Cat)` drops Dog (Dog ∉ Cat-subtree) and
+              // stays pure. SOUNDNESS-PRESERVING FALLBACK: if the receiver's static class can't be
+              // pinned to a LOCAL class (no property access, a union/interface/`any` receiver, an
+              // external/unresolved type), we do NOT narrow — the full override set is kept, exactly
+              // the pre-precision behavior, so we never silently drop an effect we can't rule out.
+              let overrides = allOverrides;
+              const recvExpr = (ts.isPropertyAccessExpression(node.expression)
+                || ts.isElementAccessExpression(node.expression)) ? node.expression.expression : null;
+              if (recvExpr) {
+                const rt = checker.getTypeAtLocation(recvExpr);
+                const rootClass = (rt?.symbol?.declarations ?? []).find((d) =>
+                  ts.isClassDeclaration(d) && projectFiles.has(path.resolve(d.getSourceFile().fileName)));
+                if (rootClass) overrides = allOverrides.filter((om) =>
+                  ts.isClassDeclaration(om.parent) && classInSubtree(om.parent, rootClass));
+              }
+              if (overrides.length > 0) {
+                if (overrides.length <= 12) {
+                  let allResolved = true;
+                  const oTargets = [];
+                  for (const om of overrides) {
+                    const ot = nodeName.get(om);
+                    if (ot) oTargets.push(ot);
+                    else allResolved = false;
+                  }
+                  for (const ot of oTargets) rec.edges.add(ot);
+                  if (!allResolved) {
+                    rec.direct.add("Unknown");
+                    rec.why.add(`override:${decl.name?.getText?.() ?? "member"}`);
+                  }
+                } else {
+                  rec.direct.add("Unknown"); // override family too wide to enumerate soundly
                   rec.why.add(`override:${decl.name?.getText?.() ?? "member"}`);
                 }
-              } else {
-                rec.direct.add("Unknown"); // override family too wide to enumerate soundly
-                rec.why.add(`override:${decl.name?.getText?.() ?? "member"}`);
               }
             }
             // record what each argument position received (callback-flow, see callbackArgs)
@@ -949,16 +1017,30 @@ function visitCalls(node) {
     if (hit) {
       const owner = enclosing(node);
       if (owner) {
-        const rec = fns.get(owner);
-        const t = nodeName.get(hit.decl);
-        if (hit.local && t) {
-          rec.edges.add(t); // (EDGE) into the accessor unit — effects propagate
-        } else {
-          // resolved to an accessor whose body we can't see → Unknown, never silent-pure (SPEC §4)
-          rec.direct.add("Unknown");
-          const an = hit.decl.parent?.name?.getText?.() ?? "?";
-          rec.why.add(`accessor:${an}.${node.name?.getText?.() ?? node.argumentExpression?.getText?.() ?? "?"}`);
-        }
+        const an = hit.decl.parent?.name?.getText?.() ?? "?";
+        const pn = node.name?.getText?.() ?? node.argumentExpression?.getText?.() ?? "?";
+        recordAccessorHit(owner, hit, `${an}.${pn}`);
+      }
+    }
+  }
+  // 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
+  // the property-access arm above because there is no PropertyAccess/ElementAccess node. (ARRAY
+  // destructuring is ITERATION, handled below; object destructuring copies named own/inherited props,
+  // invoking each getter.) Resolve every bound key as a property on the initializer's type; a rest
+  // element / computed key can't be pinned to one accessor, so it's skipped (no fabrication).
+  if (ts.isVariableDeclaration(node) && ts.isObjectBindingPattern(node.name) && node.initializer) {
+    const owner = enclosing(node);
+    if (owner) {
+      const recvType = checker.getTypeAtLocation(node.initializer);
+      for (const el of node.name.elements) {
+        if (el.dotDotDotToken) continue; // `...rest` collects the remaining props, not one getter
+        const key = el.propertyName ?? el.name; // `{prop}` shorthand, or `{prop: alias}`
+        const keyName = ts.isIdentifier(key) ? key.text
+          : ts.isStringLiteralLike(key) ? key.text : null;
+        if (keyName === null) continue; // computed key (`{[k]: v}`) — unresolvable to one property
+        const hit = accessorFromSym(recvType?.getProperty?.(keyName), "get");
+        if (hit) recordAccessorHit(owner, hit, keyName);
       }
     }
   }