candor-ts 0.5.2 → 0.5.4

package/package.json

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

package/scan.mjs

@@ -322,6 +322,7 @@ const nodeName = new WeakMap();  // declaration node -> qualified name
 // `@Entity()` (naming-strategy-dependent) contributes nothing — never a guess.
 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)
 function moduleOf(sf) {
   const rel = path.relative(rootDir, path.resolve(sf.fileName)).replace(/\.[mc]?[tj]sx?$/, "");
   return rel.split(path.sep).join(".");
@@ -453,6 +454,63 @@ for (const sf of sources) {
   })(sf);
 }
 
+// Class-CHA universe (the override half of the Rust engine's local-trait / bounded-CHA move): a
+// method call on a BASE-class-typed receiver resolves statically to the base method, but a SUBCLASS
+// may override it with an effectful body — `class Dog extends Animal { speak(){ fs.readFileSync() } }`.
+// Without fanning out to the override, `a.speak()` on an `Animal`-typed `a` comes back concrete-PURE
+// (a silent-pure soundness hole, strictly worse than Unknown). We index, for every LOCAL base-class
+// member, the overriding members in its LOCAL subclasses (walking the full `extends` chain so a
+// grand-subclass override is attributed to the right ancestor declaration). The dispatch site (below)
+// edges to the base PLUS these overrides, bounded by the same ≤12 family limit the interface path
+// uses, with the same allResolved honesty gate. Local subclasses only (an external base/override
+// surface stays OPAQUE, never fabricated). Mirrors interfaceImpls' merged-decl posture.
+{
+  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;
+  };
+  for (const sf of sources) {
+    (function scan(node) {
+      if (ts.isClassDeclaration(node)) {
+        for (const m of node.members ?? []) {
+          const name = memberName(m);
+          if (!name) continue;
+          // Walk the base chain; register this subclass member as an override of the NEAREST
+          // ancestor member of the same name (one edge per (name) — TS forbids two declarations of
+          // one accessor-kind/method on a class, so the first match up the chain is the override
+          // target). Stop after the first ancestor declares the name: that is the unit a base-typed
+          // dispatch lands on; higher ancestors are reached transitively via their own override edges.
+          let base = baseClassOf(node), guard = 0;
+          while (base && guard++ < 64) {
+            const ancestor = (base.members ?? []).find((x) => memberName(x) === name
+              && (ts.isMethodDeclaration(x) === ts.isMethodDeclaration(m))
+              && (ts.isGetAccessorDeclaration(x) === ts.isGetAccessorDeclaration(m))
+              && (ts.isSetAccessorDeclaration(x) === ts.isSetAccessorDeclaration(m)));
+            if (ancestor) {
+              if (!classOverrides.has(ancestor)) classOverrides.set(ancestor, []);
+              classOverrides.get(ancestor).push(m);
+              break;
+            }
+            base = baseClassOf(base);
+          }
+        }
+      }
+      ts.forEachChild(node, scan);
+    })(sf);
+  }
+}
+
 // callback-flow bookkeeping (the Rust engine's callback_named move, ported): for every call that
 // edges to a LOCAL unit, record what each argument position received — a NAMED local unit (a
 // resolvable callback target), or an opaque value (an inline closure stays attributed to the
@@ -542,6 +600,60 @@ function rootsAtStdStream(expr) {
   }
 }
 
+// ---- the implicit/desugared-call surface (the silent-pure holes the AST walk misses) -------------
+// CLASSIFIER §1 says resolve, don't pattern-match — but the walk only sees CallExpression/
+// NewExpression (+ accessor access). Effects reached through a DESUGARED call (a `for-of` lowering to
+// `it[Symbol.iterator]().next()`, a `using` to `r[Symbol.dispose]()`, a tagged template to `tag(...)`)
+// were invisible: reported concrete-PURE (omitted), not even Unknown. We model the desugaring exactly
+// as the spec demands — resolve the implicit target via the compiler API and edge to it when LOCAL.
+// A resolved-but-unseen target follows the existing external/κ posture (OPAQUE + ledger), and a
+// BUILT-IN iterator/disposer (es-lib/@types/node — a plain array's iterator, a stdlib disposable)
+// resolves to a non-local declaration and edges nothing, so it correctly stays pure.
+
+// The member symbol for a WELL-KNOWN symbol (`Symbol.iterator`, `Symbol.dispose`, …) on a type. The
+// checker mangles these to an escaped name `__@iterator@<globalId>`; match by the `__@<name>@` prefix
+// (the trailing id is the unique Symbol's identity, not part of the name). `prefixes` is tried in
+// order so a sync site prefers the sync method and an async site its async twin (falling back to sync).
+function wellKnownSymbolMember(type, prefixes) {
+  if (!type || !type.getProperties) return null;
+  for (const p of type.getProperties()) {
+    const n = p.getName();
+    for (const pre of prefixes) if (n === pre || n.startsWith(pre + "@")) return p;
+  }
+  return null;
+}
+function declOfSym(sym) { return sym && (sym.valueDeclaration ?? sym.declarations?.[0]); }
+const declIsLocal = (decl) => decl && projectFiles.has(path.resolve(decl.getSourceFile().fileName));
+
+// The LOCAL units an ITERATION over `expr` implicitly calls: the iterable's `[Symbol.iterator]` (or
+// `[Symbol.asyncIterator]` for `for await`) method AND the produced iterator's `next()`. The generator
+// case rolls `next`'s body into the iterator-method unit (lexical attribution), and the self-iterator
+// case (`[Symbol.iterator]() { return this }` + a separate effectful `next()`) needs the `next` edge —
+// so we edge to BOTH whenever each is a LOCAL unit. A built-in iterable (plain array/string/Map: the
+// es-lib/@types iterator) resolves non-local → no edge → stays pure (the precision invariant).
+function iterationTargets(expr, isAsync) {
+  const t = checker.getTypeAtLocation(expr);
+  const iterPrefixes = isAsync ? ["__@asyncIterator", "__@iterator"] : ["__@iterator"];
+  const iterDecl = declOfSym(wellKnownSymbolMember(t, iterPrefixes));
+  if (!iterDecl) return [];
+  const out = [];
+  if (declIsLocal(iterDecl)) out.push(iterDecl);
+  // the iterator's next(): the return type of the [Symbol.iterator] method
+  try {
+    const sig = checker.getSignatureFromDeclaration(iterDecl);
+    const ret = sig && checker.getReturnTypeOfSignature(sig);
+    const nextDecl = declOfSym(ret && ret.getProperties().find((p) => p.getName() === "next"));
+    if (nextDecl && declIsLocal(nextDecl) && !out.includes(nextDecl)) out.push(nextDecl);
+  } catch { /* unresolved iterator shape — the iterator-method edge already covers the common case */ }
+  return out;
+}
+// Edge `rec` to each LOCAL desugared target that is a minted unit. Local-only by design: an external
+// iterable/disposer is OPAQUE (the curated-κ caveat — same as an unmatched external call), never a
+// fabricated edge; the existing call machinery + κ ledger already cover any EXPLICIT calls into it.
+function edgeToTargets(rec, decls) {
+  for (const d of decls) { const t = nodeName.get(d); if (t) rec.edges.add(t); }
+}
+
 // ---- pass 2: per call site, the (CLASSIFY)/(EDGE)/(UNKNOWN) resolution of SEMANTICS §4 ------------
 function visitCalls(node) {
   if (ts.isCallExpression(node) || ts.isNewExpression(node)) {
@@ -575,6 +687,36 @@ function visitCalls(node) {
           const targetName = nodeName.get(decl);
           if (targetName) {
             rec.edges.add(targetName); // (EDGE) — cross-FILE edges resolve the same way
+            // Class-CHA fan-out: resolution landed on a base-class member that LOCAL subclasses
+            // override. A base-typed receiver (`a: Animal`, or a branch-merged `Animal|Dog`) could be
+            // any subclass at runtime, so the override bodies' effects must propagate — else the caller
+            // reads concrete-PURE while a `Dog.speak` does I/O (the silent-pure base-dispatch hole). We
+            // edge to the overrides too, bounded by the same ≤12 family limit the interface path uses,
+            // with the same honesty gate: if any override isn't a resolvable unit (not minted), or the
+            // family is too large, fall to Unknown rather than silently dropping it. A monomorphic
+            // 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");
+                  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)
             (node.arguments ?? []).forEach((a, i) => {
               const slot = (callbackArgs.get(targetName) ?? callbackArgs.set(targetName, new Map()).get(targetName));
@@ -820,6 +962,56 @@ function visitCalls(node) {
       }
     }
   }
+  // ITERATION desugaring (HIGH): `for (const x of bag)`, `for await (…)`, `[...bag]`, `const [a]=bag`,
+  // `Array.from(bag)` all lower to `bag[Symbol.iterator]().next()`. Edge the enclosing fn to the
+  // iterable's local `[Symbol.iterator]`/`[Symbol.asyncIterator]` method (and the produced iterator's
+  // local `next`). A built-in iterable (array/string/Map) resolves non-local → no edge → stays pure.
+  {
+    let iterExpr = null, iterAsync = false;
+    if (ts.isForOfStatement(node)) { iterExpr = node.expression; iterAsync = !!node.awaitModifier; }
+    else if (ts.isSpreadElement(node)) iterExpr = node.expression; // [...bag] / f(...bag)
+    else if (ts.isSpreadAssignment(node)) iterExpr = node.expression; // {...bag} — object spread is NOT
+    // iteration (it copies own enumerable props, no [Symbol.iterator]); wellKnownSymbolMember simply
+    // finds none and edges nothing. Listed for clarity; the resolution self-guards.
+    else if (ts.isVariableDeclaration(node) && ts.isArrayBindingPattern(node.name) && node.initializer)
+      iterExpr = node.initializer; // const [a] = bag
+    else if (ts.isCallExpression(node) && node.arguments?.[0]
+             && node.expression.getText() === "Array.from")
+      iterExpr = node.arguments[0]; // Array.from(bag) — the iterable form (arg0 is iterated)
+    if (iterExpr) {
+      const owner = enclosing(node);
+      if (owner) edgeToTargets(fns.get(owner), iterationTargets(iterExpr, iterAsync));
+    }
+  }
+  // `using r = expr` / `await using r = expr` (MED): the scope-exit guarantees `r[Symbol.dispose]()` /
+  // `r[Symbol.asyncDispose]()`. Edge the enclosing fn to the resolved LOCAL dispose method.
+  if (ts.isVariableStatement(node)) {
+    const fl = node.declarationList.flags;
+    const isUsing = (fl & ts.NodeFlags.Using) || (fl & ts.NodeFlags.AwaitUsing);
+    if (isUsing) {
+      const isAwait = !!(fl & ts.NodeFlags.AwaitUsing);
+      const prefixes = isAwait ? ["__@asyncDispose", "__@dispose"] : ["__@dispose"];
+      const owner = enclosing(node);
+      for (const d of node.declarationList.declarations) {
+        if (!d.initializer || !owner) continue;
+        const t = checker.getTypeAtLocation(d.initializer);
+        const disposeDecl = declOfSym(wellKnownSymbolMember(t, prefixes));
+        if (disposeDecl && declIsLocal(disposeDecl)) edgeToTargets(fns.get(owner), [disposeDecl]);
+      }
+    }
+  }
+  // TAGGED TEMPLATE (LOW): `` tag`…` `` calls `tag(strings, ...subs)`. getResolvedSignature resolves
+  // the TaggedTemplateExpression to the tag fn cleanly — a node form the CallExpression walk never
+  // visits. Edge to the tag when LOCAL; a built-in/external tag (`String.raw`) resolves non-local and
+  // edges nothing (pure), matching the external-call posture.
+  if (ts.isTaggedTemplateExpression(node)) {
+    const owner = enclosing(node);
+    if (owner) {
+      const sig = checker.getResolvedSignature(node);
+      const decl = sig && sig.declaration;
+      if (decl && declIsLocal(decl)) edgeToTargets(fns.get(owner), [decl]);
+    }
+  }
   ts.forEachChild(node, visitCalls);
 }
 for (const sf of sources) visitCalls(sf);