candor-ts 0.5.1 → 0.5.3

package/AGENTS.md

@@ -9,11 +9,22 @@ chains by hand.
 > the *installed* version — always prefer that over a vendored or fetched copy, which can describe
 > a different candor-ts than the one you are running.
 
+> **Already installed? Report the version and ask before upgrading — before you scan.** If this
+> project already has candor (a `.candor/` report directory, or `candor-ts` reachable via `npx`/a
+> global install), do this *first*: run `npx -y candor-ts --version` (offline) and **tell the user
+> plainly which version they're on** — e.g. *"This project is on candor-ts 0.5.1 (spec 0.5)."* On a
+> build too old for the flag, read `candor.version` / `candor.spec` from an existing
+> `.candor/report*.json`, or `npm ls -g candor-ts`.
+>
 > **Staying current is your job, not candor's.** candor never phones home — it audits and denies the
 > Net effect, so it will not reach the network to check itself. `candor-ts --version` prints the
 > installed build, the spec contract it speaks, and the upgrade line (`npm install -g
-> candor-ts@latest`) — fully offline. You have the network: read the installed version here, compare
-> it against npm, and upgrade if it is stale. Every command is offline.
+> candor-ts@latest`) — fully offline. **You** have the network: compare the installed version against
+> npm. If it's behind, **ask the user before upgrading** — e.g. *"candor-ts 0.5.2 is available
+> (you're on 0.5.1) — upgrade before I scan?"* — and run `npm install -g candor-ts@latest` (or `npx
+> -y candor-ts@latest`) only if they agree. Never upgrade silently: an analysis tool's version is
+> part of its result's provenance, so the user decides when it changes. If it's already current (or
+> the user declines), just proceed; if candor isn't installed at all, install it normally.
 
 The language-agnostic consumption contract is
 [candor-spec/AGENTS.md](https://github.com/tombaldwin/candor-spec/blob/main/AGENTS.md); this file is

package/package.json

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

package/scan.mjs

@@ -336,6 +336,14 @@ function localName(node) {
   if (ts.isFunctionDeclaration(node) && node.name) return node.name.text;
   if (ts.isMethodDeclaration(node) && ts.isClassDeclaration(node.parent) && node.parent.name)
     return `${node.parent.name.text}.${node.name.getText()}`;
+  // GET/SET ACCESSORS are units too — a property read/assignment that resolves to one edges here, so
+  // an accessor body that does I/O classifies normally instead of being a SILENT-PURE hole (and its
+  // effect is no longer misattributed to the enclosing class's synthesized ctor, which `enclosing()`
+  // would otherwise pick as the nearest unit). get/set are DISTINCT units (a class may have both for
+  // one name): `Class.get raw` / `Class.set raw`, mirroring how the checker keeps them apart.
+  if ((ts.isGetAccessorDeclaration(node) || ts.isSetAccessorDeclaration(node))
+      && ts.isClassDeclaration(node.parent) && node.parent.name)
+    return `${node.parent.name.text}.${ts.isGetAccessorDeclaration(node) ? "get" : "set"} ${node.name.getText()}`;
   // `const f = (…) => …` / `const f = function (…) {…}` at any binding site — the dominant style in
   // real TS (rimraf's whole API is arrow consts; the first dogfood analyzed 0 of 50 files without
   // this). The VARIABLE name is the function's name; nodeName is ALSO set on the initializer so a
@@ -490,6 +498,23 @@ function realDecl(sym) {
   return sym.valueDeclaration ?? sym.declarations?.[0];
 }
 
+// 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
+// kind (get for a read, set for an assignment LHS). Returns { decl, local } where `local` is true
+// 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);
+  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.
+  const decl = (sym.declarations ?? []).find((d) => want(d));
+  if (!decl) return null;
+  return { decl, local: projectFiles.has(path.resolve(decl.getSourceFile().fileName)) };
+}
+
 // nearest enclosing analyzed function (closures attribute to it — SEMANTICS §2)
 function enclosing(node) {
   for (let p = node; p; p = p.parent) {
@@ -517,6 +542,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)) {
@@ -766,6 +845,85 @@ function visitCalls(node) {
     const owner = enclosing(node);
     if (owner) fns.get(owner).direct.add("Env");
   }
+  // GET/SET ACCESSOR access (the silent-pure-accessor fix): a property read that resolves to a
+  // getter, or a property assignment whose target resolves to a setter, is effectively a call into
+  // the accessor body — model it as a call EDGE so the accessor's effects propagate (like a method
+  // 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 `=`.)
+    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 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?.() ?? "?"}`);
+        }
+      }
+    }
+  }
+  // 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);