candor-ts 0.5.21 → 0.5.23

package/package.json

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

package/scan-core.mjs

@@ -66,11 +66,60 @@ export const KAPPA_RULES = [
   [/^(node:)?sqlite$/, null, "Db"],
   // the curated npm tier
   [/^(axios|got|node-fetch|undici|ws|socket\.io(-client)?|nodemailer)$/, null, "Net"],
+  // gaxios is the axios-like HTTP client under googleapis (request/get/post/put/patch/delete/head do
+  // the network; it has no notable pure surface, but be VERB-precise like the rest of the Net tier so a
+  // future config accessor can't fabricate). `createAPIRequest` is googleapis-common's transport entry
+  // (every googleapis service method funnels through it → the real network). The deeper `googleapis`
+  // service chains (`calendar.events.insert()`) resolve their verb into the `googleapis` package, but
+  // those verbs are GENERIC (insert/list/get/update) and shared with pure builders — modeling them by
+  // name would fabricate; the actual network is the gaxios/createAPIRequest transport, modeled here, so
+  // a googleapis call that reaches the wire does so through a modeled unit when its source is scanned.
+  [/^gaxios$/, /^(request|get|post|put|patch|delete|head)$/, "Net"],
+  [/^googleapis-common$/, /^createAPIRequest$/, "Net"],
+  // google-auth-library mints/refreshes OAuth tokens and verifies ID tokens over the network. The
+  // verb surface only (the GoogleAuth/OAuth2Client/JWT constructors are config — inert until a verb).
+  [/^google-auth-library$/,
+   /^(request|getClient|getAccessToken|getRequestHeaders|authorize|refreshAccessToken|refreshToken|getTokenInfo|verifyIdToken|fetchIdToken|getCredentials|getProjectId|getSignedJwt)$/,
+   "Net"],
+  // stripe: methods land on a `new Stripe()` instance's resource chains
+  // (`stripe.customers.create()`, `stripe.checkout.sessions.create()`, `charges.*`, `paymentIntents.*`).
+  // A chained member call resolves its verb's DECLARATION into the `stripe` package (declModule keys on
+  // the source file, not the chain depth — verified), so keying on stripe's resource VERBS catches the
+  // deep chains. VERB-precise: the I/O verbs only (the SDK's resources share these); pure helpers
+  // (toString/JSON) and inert `new Stripe()` construction stay pure.
+  [/^stripe$/,
+   /^(create|retrieve|update|list|listLineItems|listPaymentMethods|del|delete|cancel|capture|confirm|expire|finalizeInvoice|pay|sendInvoice|markUncollectible|voidInvoice|refund|reverse|verify|search|approve|decline|attach|detach|deactivate)$/,
+   "Net"],
+  // error/telemetry SaaS — the capture/flush verbs ship the payload over the network. init/config are
+  // inert. @sentry/* re-exports captureException etc. from @sentry/core/@sentry/browser, so a consumer's
+  // import may resolve into any @sentry sub-package — match the whole scope, verb-precise.
+  [/^@sentry\/[^/]+$/,
+   /^(captureException|captureMessage|captureEvent|captureCheckIn|flush|close)$/, "Net"],
+  // posthog-node: capture/identify/group enqueue then flush over HTTP; flush/shutdown/captureImmediate
+  // and the feature-flag fetches (isFeatureEnabled/getFeatureFlag*) hit the API. Verb-precise; the
+  // `new PostHog()` ctor is inert (config).
+  [/^posthog-node$/,
+   /^(capture|captureImmediate|identify|identifyImmediate|alias|groupIdentify|flush|shutdown|isFeatureEnabled|getFeatureFlag|getFeatureFlagPayload|getAllFlags|getAllFlagsAndPayloads|getRemoteConfigPayload|reloadFeatureFlags)$/,
+   "Net"],
   [/^(pg|mysql2?|mongodb|ioredis|redis|sqlite3|better-sqlite3|knex)$/, null, "Db"],
+  // bull/bullmq are Redis-backed job queues — the queue/worker/job ops issue Redis commands (Db). Their
+  // surface is almost entirely I/O, but be VERB-precise (the I/O ops) so inert event-wiring
+  // (`queue.on(...)`) and `new Queue()`/`new Worker()` construction (which only opens a lazy connection)
+  // don't fabricate. The connection IS Redis — Db, consistent with the ioredis/redis classification.
+  [/^(bull|bullmq)$/,
+   /^(add|addBulk|getJob|getJobs|getJobCounts|getJobCountByTypes|getWaiting|getActive|getCompleted|getFailed|getDelayed|getWaitingChildren|getRepeatableJobs|removeRepeatable|removeRepeatableByKey|getMetrics|count|pause|resume|isPaused|drain|clean|obliterate|empty|close|remove|retry|retryJobs|promote|moveToCompleted|moveToFailed|updateData|updateProgress|process|waitUntilReady|getState|getDependencies|getChildrenValues)$/,
+   "Db"],
   [/^(execa|cross-spawn|shelljs)$/, null, "Exec"],
+  // the `open` package spawns the OS handler (xdg-open/open/start) — Exec. Default export `open(target)`
+  // resolves to member `open` (its declared fn name — verified); `openApp` likewise. The `apps` const is
+  // pure (a property read, never a call).
+  [/^open$/, /^(open|openApp)$/, "Exec"],
   [/^(fs-extra|graceful-fs|rimraf|glob|chokidar)$/, null, "Fs"],
   [/^dotenv$/, null, "Env"],
   [/^(winston|pino|bunyan|npmlog)$/, null, "Log"],
+  // nest-winston wraps winston; the injected logger's level verbs are the Log boundary (the
+  // WinstonModule.createLogger/forRoot config is inert).
+  [/^nest-winston$/, /^(log|info|warn|error|debug|verbose|silly|http)$/, "Log"],
   // entropy: node:crypto's random surface + the password-hashing libs (salted -> Rand). Found by
   // the CTA dogfood on a Nest app: argon2.hash came out SILENTLY PURE (the curated-kappa caveat
   // landing on exactly the call a security review cares about).
@@ -78,6 +127,14 @@ export const KAPPA_RULES = [
   // were silently pure inside the covered `crypto` module (the κ-coverage floor can't tell an unmodeled
   // entropy draw from a pure unmodeled member; the fix is to MODEL the member, not drop coverage).
   [/^(node:)?crypto$/, /^(random|getRandomValues|generateKey|generatePrime)/, "Rand"],
+  // uuid: the random-based generators draw from the CSPRNG (v4) / clock+MAC+random (v1) / random (v6/v7).
+  // v3 (MD5) and v5 (SHA-1) are DETERMINISTIC namespace hashes — same input, same UUID — so they are
+  // PURE and excluded. parse/stringify/validate/version/NIL/MAX are pure too (not matched).
+  [/^uuid$/, /^(v1|v4|v6|v7)$/, "Rand"],
+  // nanoid: nanoid()/customRandom() draw from crypto.getRandomValues; customAlphabet() returns a
+  // generator that does the same. `nanoid/non-secure` uses Math.random — still Rand. The `urlAlphabet`
+  // const is pure (a property read). Sound over-approximation: the factory call is the resolvable site.
+  [/^nanoid(\/non-secure)?$/, /^(nanoid|customAlphabet|customRandom)$/, "Rand"],
   // node:os identity reads — userInfo (the OS user record) and hostname (the machine name) are
   // environment/host reads (Env), like System.getenv's host-identity cousins. The rest of node:os
   // (platform/arch/cpus/totalmem/…) is inert host introspection, left pure.

package/scan.mjs

@@ -962,6 +962,71 @@ function iterationTargets(expr, isAsync) {
 function edgeToTargets(rec, decls) {
   for (const d of decls) { const t = nodeName.get(d); if (t) rec.edges.add(t); }
 }
+
+// ---- implicit VALUE-COERCION desugaring (the silent-pure holes where the JS coercion protocol calls a
+// user method the AST walk never visits) ----------------------------------------------------------
+// JS coerces an object to a primitive by INVOKING a method on it: `a + b`/`` `${x}` ``/`String(x)` call
+// `toString` (or `[Symbol.toPrimitive]`); `x + 1`/`-x`/`+x`/relational call `valueOf` (or
+// `[Symbol.toPrimitive]`); `JSON.stringify(x)` calls `toJSON`. None of these surface as a
+// CallExpression on the user method, so an effectful `toString`/`valueOf`/`toJSON`/`[Symbol.toPrimitive]`
+// reached this way read SILENT-PURE (the cardinal sin). We model the desugar EXACTLY as the spec demands:
+// resolve the operand's type's coercion member via the checker and edge to it ONLY when it is a LOCAL
+// unit. A built-in/external member (lib.es `Object.prototype.toString`, a stdlib `toJSON`) resolves
+// non-local → no edge → stays pure (the precision invariant); a PURE local member edges to a pure unit
+// (contributes nothing). NEVER a fabricated edge: a non-object operand, or a type with no such member,
+// resolves to nothing.
+
+// Resolve coercion members of `expr`'s type to their LOCAL decls. `names` is the ordered set of plain
+// member names to try; `withPrimitive` also consults the well-known `[Symbol.toPrimitive]` (which JS
+// prefers over toString/valueOf when present). A union operand is widened to its constituents so a
+// `A | B` value edges to whichever side declares a LOCAL coercion member. Returns LOCAL member decls.
+function coercionTargets(expr, names, withPrimitive) {
+  const t = checker.getTypeAtLocation(expr);
+  if (!t) return [];
+  // Widen unions/intersections so each branch's coercion member is considered (a `Foo | string` operand
+  // can be a Foo at runtime → its local toString runs). A primitive/literal constituent has no LOCAL
+  // member and contributes nothing.
+  const parts = t.isUnionOrIntersection?.() ? t.types : [t];
+  const out = [];
+  for (const part of parts) {
+    if (!part || !part.getProperty) continue;
+    if (withPrimitive) {
+      const pd = declOfSym(wellKnownSymbolMember(part, ["__@toPrimitive"]));
+      if (pd && declIsLocal(pd) && !out.includes(pd)) out.push(pd);
+    }
+    for (const n of names) {
+      const md = declOfSym(part.getProperty(n));
+      // A METHOD (or function-valued property) member — not a getter/data field of an unrelated shape.
+      if (md && declIsLocal(md)
+          && (ts.isMethodDeclaration(md) || ts.isMethodSignature(md)
+              || ts.isPropertyDeclaration(md) || ts.isPropertyAssignment(md)
+              || ts.isFunctionDeclaration(md) || ts.isFunctionExpression(md) || ts.isArrowFunction(md))
+          && !out.includes(md))
+        out.push(md);
+    }
+  }
+  return out;
+}
+// True when `expr`'s type is an OBJECT type that could carry a coercion method (so `a + b` may trigger
+// one). A pure primitive operand (string/number/boolean/bigint/null/undefined) never invokes
+// toString/valueOf in `+` (string+string concatenates, number+number adds — no method call), so we skip
+// it: edging there would be at best inert and the type-narrowing keeps `coercionTargets` from widening a
+// huge `string | Foo` into spurious work. An object/union-containing-object is a candidate.
+function mayCoerceObject(expr) {
+  const t = checker.getTypeAtLocation(expr);
+  if (!t) return false;
+  const parts = t.isUnionOrIntersection?.() ? t.types : [t];
+  const PRIM = ts.TypeFlags.StringLike | ts.TypeFlags.NumberLike | ts.TypeFlags.BigIntLike
+    | ts.TypeFlags.BooleanLike | ts.TypeFlags.Null | ts.TypeFlags.Undefined | ts.TypeFlags.VoidLike
+    | ts.TypeFlags.ESSymbolLike;
+  for (const part of parts) {
+    if (!part) continue;
+    if (part.flags & PRIM) continue;           // a pure primitive branch never coerces via a method
+    if (part.flags & ts.TypeFlags.Object) return true;
+    if (part.isUnionOrIntersection?.()) return true; // nested — let coercionTargets sort it out
+  }
+  return false;
+}
 // 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
@@ -1388,9 +1453,25 @@ function visitCalls(node) {
                : (decl.name ? decl.name.getText() : ""))
             : "";
           const isConstruction = ts.isConstructorDeclaration(decl) || ts.isNewExpression(node);
+          // The κ member token. A named decl (function/method declaration) carries its own name; but a
+          // VALUE-BINDING export — `export const v4 = (...) => ...` (the shape REAL uuid v9+/nanoid ship,
+          // and the `type v4 = v4Buffer & v4String` callable type-alias of @types/uuid v8) resolves to an
+          // ANONYMOUS arrow/function-type whose `decl.name` is empty, so κ saw `""` and the package's
+          // entropy/net verb read silent-pure (verified against installed uuid/nanoid). Fall back to the
+          // BINDING name: an arrow/fn-expr's parent VariableDeclaration / PropertyAssignment / property,
+          // or a callable type-alias's TypeAliasDeclaration. Precision no-op where the old path already
+          // had a name (this only fills a former `""`); never synthesizes a name for `new`.
+          const bindingName = (d) => {
+            const p = d.parent;
+            if (!p) return "";
+            if ((ts.isVariableDeclaration(p) || ts.isPropertyDeclaration(p) || ts.isPropertyAssignment(p)
+                 || ts.isPropertySignature(p) || ts.isBindingElement(p) || ts.isTypeAliasDeclaration(p))
+                && p.name && ts.isIdentifier(p.name)) return p.name.getText();
+            return "";
+          };
           const member = isConstruction
             ? (CONNECTING_CTORS.has(ctorClassName) ? ctorClassName : "new")
-            : (decl.name ? decl.name.getText() : "");
+            : (decl.name ? decl.name.getText() : bindingName(decl));
           let eff = kappa(mod, member); // (CLASSIFY)
           // process.stdout/stderr/stdin are typed `tty.WriteStream`, which EXTENDS `net.Socket`, so a
           // `.write()`/`.end()` on them resolves to `net.Socket.write` and the whole-module Net rule
@@ -1708,6 +1789,72 @@ function visitCalls(node) {
       }
     }
   }
+  // IMPLICIT VALUE-COERCION desugaring (HIGH): the JS coercion protocol invokes a user method the AST
+  // walk never visits as a CallExpression. Resolve the operand's type's coercion member and edge to it
+  // when LOCAL (a built-in/external member resolves non-local → no edge → stays pure). NEVER fabricate.
+  {
+    const owner = enclosing(node);
+    const recOf = () => owner && fns.get(owner);
+    // 1+2. BINARY operators. `+` with an OBJECT operand triggers toString/valueOf (string+string,
+    // number+number have no coercion method — stay pure, gated by mayCoerceObject). Arithmetic
+    // (`-`/`*`/`/`/`%`/`**`) and relational (`<`/`>`/`<=`/`>=`) coerce to a NUMBER → valueOf (then
+    // toString). `[Symbol.toPrimitive]` is preferred by JS over both — always consulted.
+    if (ts.isBinaryExpression(node) && owner) {
+      const op = node.operatorToken.kind;
+      const K = ts.SyntaxKind;
+      const ARITH = new Set([K.MinusToken, K.AsteriskToken, K.SlashToken, K.PercentToken,
+        K.AsteriskAsteriskToken, K.LessThanToken, K.GreaterThanToken, K.LessThanEqualsToken,
+        K.GreaterThanEqualsToken, K.AmpersandToken, K.BarToken, K.CaretToken,
+        K.LessThanLessThanToken, K.GreaterThanGreaterThanToken, K.GreaterThanGreaterThanGreaterThanToken]);
+      const COMPOUND_ARITH = new Set([K.MinusEqualsToken, K.AsteriskEqualsToken, K.SlashEqualsToken,
+        K.PercentEqualsToken, K.AsteriskAsteriskEqualsToken]);
+      if (op === K.PlusToken || op === K.PlusEqualsToken) {
+        // string concat / `+` arithmetic: an OBJECT operand is coerced via toString OR valueOf (the
+        // order depends on the hint, but EITHER may run — edge to both when local). string+string and
+        // number+number have only primitive operands → mayCoerceObject false → no edge (pure).
+        for (const operand of [node.left, node.right]) {
+          if (mayCoerceObject(operand))
+            edgeToTargets(recOf(), coercionTargets(operand, ["valueOf", "toString"], true));
+        }
+      } else if (ARITH.has(op) || COMPOUND_ARITH.has(op)) {
+        for (const operand of [node.left, node.right]) {
+          if (mayCoerceObject(operand))
+            edgeToTargets(recOf(), coercionTargets(operand, ["valueOf", "toString"], true));
+        }
+      }
+    }
+    // 2. UNARY arithmetic `-x` / `+x` / `~x` coerces the operand to a number → valueOf (then toString /
+    // [Symbol.toPrimitive]). (`!x` is boolean coercion — no method call; excluded.)
+    if (ts.isPrefixUnaryExpression(node) && owner
+        && (node.operator === ts.SyntaxKind.MinusToken || node.operator === ts.SyntaxKind.PlusToken
+            || node.operator === ts.SyntaxKind.TildeToken)
+        && mayCoerceObject(node.operand)) {
+      edgeToTargets(recOf(), coercionTargets(node.operand, ["valueOf", "toString"], true));
+    }
+    // 1. TEMPLATE expression `` `${x}` ``: each interpolated substitution is string-coerced → toString
+    // (then [Symbol.toPrimitive]/valueOf). (A TaggedTemplate is handled separately below — the tag fn
+    // receives the raw substitution values, no per-sub coercion, so we exclude tagged templates here.)
+    if (ts.isTemplateExpression(node) && owner && !ts.isTaggedTemplateExpression(node.parent)) {
+      for (const span of node.templateSpans)
+        if (mayCoerceObject(span.expression))
+          edgeToTargets(recOf(), coercionTargets(span.expression, ["toString", "valueOf"], true));
+    }
+    // 1+4. CALL forms `String(x)` (→ toString) and `JSON.stringify(x)` (→ toJSON). These resolve to the
+    // es-lib `StringConstructor`/`JSON.stringify` signature (not the user method), so the CallExpression
+    // walk above never follows the coercion. Edge to the argument's LOCAL toString / toJSON.
+    if (ts.isCallExpression(node) && owner && node.arguments?.[0]) {
+      const callee = node.expression.getText().replace(/\s+/g, "");
+      const arg0 = node.arguments[0];
+      if (callee === "String" && ts.isIdentifier(node.expression) && mayCoerceObject(arg0))
+        edgeToTargets(recOf(), coercionTargets(arg0, ["toString", "valueOf"], true));
+      // `"" + x` is covered by the binary arm; `String(x)` is the explicit conversion form.
+      else if (callee === "JSON.stringify")
+        // toJSON is consulted regardless of operand shape (JSON.stringify checks for it on any value);
+        // a plain object with no LOCAL toJSON resolves to nothing → pure (no fabrication). NO Symbol-
+        // toPrimitive here — JSON.stringify uses toJSON only, not the primitive-coercion protocol.
+        edgeToTargets(recOf(), coercionTargets(arg0, ["toJSON"], false));
+    }
+  }
   // 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