candor-ts 0.5.19 → 0.5.21

package/package.json

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

package/scan.mjs

@@ -759,6 +759,34 @@ function resolveFnRefUnit(refNode, depth = 0) {
   return null;
 }
 
+// Unwrap a `<ref>.bind(…)` partial-application chain to the underlying function-reference RECEIVER.
+// `setTimeout(this.flush.bind(this), 0)` / `effFs.bind(null)` / `cb.bind(null,a).bind(null,b)` schedule the
+// BOUND function, but the argument node is a CallExpression (callee = PropertyAccessExpression `.bind`), so
+// the HOF-ref arm — which only edges identifier / property-access args — dropped it (silent-pure: the
+// cardinal sin). `.bind` is the third reflective-invoke member alongside `.call`/`.apply`. Given an arg
+// node, returns:
+//   { ref }     — it IS a `.bind` chain and the root receiver is a resolvable id/property-access ref
+//                 (recursing through chained `.bind().bind()`); the caller resolves it to its fn unit.
+//   { ref:null }— it IS a `.bind` chain but the root receiver is NOT a plain ref (`getCallback().bind(null)`,
+//                 a parenthesized/`any` holder) — still INVOKED by the HOF, so the caller discloses Unknown.
+//   null        — not a `.bind` call at all; the caller's id/property-access path handles it.
+// A `.bind` on a PURE fn resolves to a pure unit (no fabrication); the bind-unresolvable case never goes
+// silent-pure.
+function unwrapBind(node, depth = 0) {
+  if (!node || depth > 8) return null;
+  if (!ts.isCallExpression(node) || !ts.isPropertyAccessExpression(node.expression)) return null;
+  if (node.expression.name.text !== "bind") return null;
+  let recv = node.expression.expression;
+  while (ts.isParenthesizedExpression(recv)) recv = recv.expression;
+  // chained `.bind().bind()` — recurse only when the receiver is ITSELF a `.bind` call, else it's an
+  // arbitrary call (`getCallback().bind`) whose result we can't pin → unresolvable bind.
+  if (ts.isCallExpression(recv)) {
+    const inner = unwrapBind(recv, depth + 1);
+    return inner ?? { ref: null };
+  }
+  return { ref: (ts.isIdentifier(recv) || ts.isPropertyAccessExpression(recv)) ? recv : null };
+}
+
 // Accessor resolution (the silent-pure-accessor fix): a property READ (`x.raw`) or property
 // ASSIGNMENT target (`x.path = v`) may resolve to a getter/setter whose body performs effects. We
 // resolve the property-name symbol to its declarations and look for an accessor of the matching
@@ -934,6 +962,63 @@ function iterationTargets(expr, isAsync) {
 function edgeToTargets(rec, decls) {
   for (const d of decls) { const t = nodeName.get(d); if (t) rec.edges.add(t); }
 }
+// Does iterating `expr` FORCE an OPAQUE (caller-supplied) iterable? Forcing an iterable runs its
+// `[Symbol.iterator]`/`next` body, which — when the iterable is a PARAMETER / `any` / a bare type-
+// parameter — is caller-chosen code that can perform arbitrary I/O. This is epistemically identical to
+// invoking an opaque callback parameter (the `call:param` → Unknown posture, scan.mjs ~1145-1158): a
+// silent-pure verdict would be the cardinal sin. Mirror that decision exactly. Returns a `why` string
+// (→ record Unknown) or null. By design this fires ONLY for genuinely caller-supplied iterables; a
+// CONCRETE built-in (array/string/Map/Set: the value resolves to a concrete type, not a param) stays
+// PURE, and a LOCAL iterable/generator (a local call result, a local class instance) is handled by the
+// existing local-edge path (iterationTargets / the call machinery) — neither is flagged here.
+// Opaque iterable INTERFACE names: a value whose TYPE is literally one of these is caller-supplied
+// iterator code (its `next` body is unknowable). A CONCRETE built-in (Array/Set/Map/String) has its own
+// symbol (`Array`/…) and runs a built-in iterator (no user code) → NOT opaque; a LOCAL class implementing
+// Iterable is handled by the local-edge path. So we key on the type's SYMBOL NAME, NOT on "is a parameter"
+// (the earlier param-identity check fabricated Unknown when iterating a concrete-typed array PARAM — the
+// conformance `loop_elem` regression: `(items: T[]) => { for (const c of items) … }`).
+const OPAQUE_ITERABLE_TYPES = new Set([
+  "Iterable", "Iterator", "IterableIterator", "Generator",
+  "AsyncIterable", "AsyncIterator", "AsyncIterableIterator", "AsyncGenerator",
+]);
+function opaqueIterableWhy(expr) {
+  const t = checker.getTypeAtLocation(expr);
+  if (!t) return null;
+  // (a) `any` or a bare TYPE PARAMETER (`<T extends Iterable<…>>(x: T)`): the concrete iterable is
+  // indeterminate, so its iterator body is unknowable — never silently pure.
+  if (t.flags & ts.TypeFlags.Any) return "iterate:any";
+  if (t.flags & ts.TypeFlags.TypeParameter) return "iterate:typeparam";
+  // (b) the type IS an opaque iterable INTERFACE *and* the value is CALLER-SUPPLIED (a parameter / binding
+  // element): `collect(source: Iterable<T>)`, `nexts(it: Iterator<T>)`, `drain(g: Generator<T>)`. The
+  // caller chooses the concrete iterator (arbitrary I/O), identical to invoking an opaque callback. BOTH
+  // conditions are required: a LOCAL generator/iterable CALL result (`for (const x of gen())`) also has a
+  // Generator/IterableIterator type but is NOT a param → excluded, so the local-edge path edges its real
+  // effect (no spurious Unknown); a concrete Array/Set/Map/String PARAM has its own symbol (not in the
+  // set) → excluded → PURE (built-in iterator, no user code; the conformance `loop_elem` case).
+  const sym = t.getSymbol && t.getSymbol();
+  if (sym && OPAQUE_ITERABLE_TYPES.has(sym.name) && ts.isIdentifier(expr)) {
+    const d = realDecl(checker.getSymbolAtLocation(expr));
+    if (d && (ts.isParameter(d) || ts.isBindingElement(d))) {
+      const idx = ts.isParameter(d) && d.parent ? d.parent.parameters.indexOf(d) : -1;
+      return idx >= 0 ? `iterate:param#${idx}` : "iterate:param";
+    }
+  }
+  return null;
+}
+// Record an opaque-iterable force as Unknown on the enclosing fn, UNLESS iteration already resolved a
+// LOCAL desugar target (then the real effect is edged — no Unknown needed). `localResolved` = the
+// non-empty result of iterationTargets (a local `[Symbol.iterator]`/`next` unit was found).
+function noteOpaqueIteration(node, iterExpr, localResolved) {
+  if (localResolved) return;
+  const owner = enclosing(node);
+  if (!owner) return;
+  const why = opaqueIterableWhy(iterExpr);
+  if (!why) return;
+  const rec = fns.get(owner);
+  if (!rec) return;
+  rec.direct.add("Unknown");
+  rec.why.add(why);
+}
 
 // Callee names that INVOKE a function/method argument (so a fn-reference passed to one is reachable
 // through it). Array/iterable HOFs, the timer/microtask schedulers, and Promise continuations. A
@@ -1028,6 +1113,23 @@ function visitCalls(node) {
           : ts.isIdentifier(node.expression) ? node.expression.text : null;
         if (mod !== "<local>" && calleeName && HOF_INVOKERS.has(calleeName)) {
           for (const a of node.arguments ?? []) {
+            // A `<ref>.bind(…)` partial-application is a CallExpression (skipped by the id/property-access
+            // gate below) but the INVOKING HOF calls the bound fn → its effects are reachable. Unwrap the
+            // `.bind` chain to the root receiver and resolve it like a bare ref (`resolveFnRefUnit` follows
+            // local aliases too). A `.bind` whose receiver can't be pinned to a fn unit (`getCallback().bind`,
+            // a param/`any` holder) still INVOKES whatever it wraps — disclose Unknown, never silent-pure.
+            const bound = unwrapBind(a);
+            if (bound) {
+              const bref = bound.ref;
+              const d3 = bref && realDecl(checker.getSymbolAtLocation(bref));
+              const tb = (d3 && nodeName.get(d3)) || (bref && resolveFnRefUnit(bref));
+              if (tb) rec.edges.add(tb);
+              else {
+                rec.direct.add("Unknown");
+                rec.why.add(`bind:${(bref ?? a).getText().replace(/\s+/g, "").slice(0, 40)}`);
+              }
+              continue;
+            }
             if (!ts.isIdentifier(a) && !ts.isPropertyAccessExpression(a)) continue;
             const d2 = realDecl(checker.getSymbolAtLocation(a));
             const t = d2 && nodeName.get(d2);
@@ -1068,6 +1170,28 @@ function visitCalls(node) {
               rec.why.add(`call:${recvText.slice(0, 40)}.${m}`);
             }
           }
+          // EXPLICIT iterator force: `it.next()` / `it.return()` / `it.throw()` on an OPAQUE iterator
+          // (a parameter / `any` / type-parameter typed as the `Iterator`/`Generator` protocol) runs
+          // caller-supplied iterator code — epistemically identical to forcing a for-of over an opaque
+          // iterable, and to invoking an opaque callback. The method resolves to the non-local es-lib
+          // `Iterator.next` signature, so the desugar above never sees it and the call lands here pure.
+          // Disclose Unknown (cardinal-sin guard). Gated on the iterator-protocol type symbol so an
+          // unrelated `.next()` on some other opaque param is not flagged; a LOCAL iterator's `next`
+          // resolves `<local>` (edged below), never reaching this non-local arm.
+          if ((m === "next" || m === "return" || m === "throw")) {
+            const why = opaqueIterableWhy(recv);
+            const rt = checker.getTypeAtLocation(recv);
+            const sn = rt?.getSymbol?.()?.getName?.()
+              ?? (rt?.flags & ts.TypeFlags.TypeParameter ? checker.getBaseConstraintOfType(rt)?.getSymbol?.()?.getName?.() : undefined);
+            const ITER_PROTO = new Set([
+              "Iterator", "AsyncIterator", "Iterable", "AsyncIterable",
+              "IterableIterator", "AsyncIterableIterator", "Generator", "AsyncGenerator",
+            ]);
+            if (why && sn && ITER_PROTO.has(sn)) {
+              rec.direct.add("Unknown");
+              rec.why.add(why); // `iterate:param#i` / `iterate:any` / `iterate:typeparam`
+            }
+          }
         }
         if (mod === "<local>") {
           const targetName = nodeName.get(decl);
@@ -1557,7 +1681,14 @@ function visitCalls(node) {
       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));
+      if (owner) {
+        const targets = iterationTargets(iterExpr, iterAsync);
+        edgeToTargets(fns.get(owner), targets);
+        // Opaque-iterable honesty: a param/`any`/type-parameter iterable runs caller-supplied iterator
+        // code — disclose Unknown, mirroring the opaque-callback `call:param` posture (cardinal-sin
+        // guard). Skipped when iteration already resolved a LOCAL unit (real effect already edged).
+        noteOpaqueIteration(node, iterExpr, targets.length > 0);
+      }
     }
   }
   // `using r = expr` / `await using r = expr` (MED): the scope-exit guarantees `r[Symbol.dispose]()` /