candor-ts 0.13.0 → 0.14.1

package/AGENTS.md

@@ -12,7 +12,7 @@ chains by hand.
 > **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 `<version>` (spec 0.13)."*
+> plainly which version they're on** — e.g. *"This project is on candor-ts `<version>` (spec 0.14)."*
 > 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`.
 >

package/README.md

@@ -184,7 +184,7 @@ pure-vs-Unknown ruling (PART 16) — the engines must answer identically, on eve
 | A call resolving to a *type* (function-typed field/param) → `Unknown`, never silent-pure | SPEC §4 |
 | Unmatched external calls contribute nothing (curated-classifier caveat) | SEMANTICS §8 C1 |
 | The literal surfaces `hosts`/`cmds`/`paths`/`tables`, literal-read only | SPEC §2 |
-| `{ candor: { version, toolchain, spec: "0.13" }, functions }` envelope; pure fns omitted | SPEC §2/§2.1 |
+| `{ candor: { version, toolchain, spec: "0.14" }, functions }` envelope; pure fns omitted | SPEC §2/§2.1 |
 | Call-graph sidecar with **every** analyzed function a key | SPEC §2.2 |
 | The gate: AS-EFF-006 / 008 / 009, loud on an unreadable policy | SPEC §6.2 |
 
@@ -202,7 +202,7 @@ read the Rust source".
 
 ## Status
 
-0.13.x, speaking candor-spec 0.13: the analysis core, the gate (`--policy` / `--gate-json` /
+0.14.x, speaking candor-spec 0.14: the analysis core, the gate (`--policy` / `--gate-json` /
 `.candor/config`), the full §3.1 query surface (including `containment`, `blindspots`, the
 `--include-unknown` dispatch frontier), the MCP server, the LSP server, and the watch loop are
 real, behaviorally tested (`npm test` — the behavioral suite across six harnesses), **soundness-fuzzed

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "candor-ts",
-  "version": "0.13.0",
-  "description": "candor for TypeScript — per-function side effects, transitively, with a policy gate (candor-spec 0.13)",
+  "version": "0.14.1",
+  "description": "candor for TypeScript — per-function side effects, transitively, with a policy gate (candor-spec 0.14)",
   "type": "module",
   "dependencies": {
     "@types/node": "^25.9.2",

package/query.mjs

@@ -94,7 +94,7 @@ function renderPathHuman(fns, cg, fnQ, eff) {
 // package.json; SPEC_VERSION is the spec contract this build speaks. Reused, never re-littered.
 const QUERY_DIR = path.dirname(fileURLToPath(import.meta.url));
 const PKG_VERSION = JSON.parse(fs.readFileSync(path.join(QUERY_DIR, "package.json"), "utf8")).version;
-const SPEC_VERSION = "0.13";
+const SPEC_VERSION = "0.14";
 
 // ---- the §3.3.1 canonical query grammar (⟨0.10⟩, additive over 0.9) --------------------------------
 // One shape for every verb: `<verb> <verb-args…> [--report <locator>] [--policy <file>] [--json]

package/scan.mjs

@@ -41,7 +41,7 @@ const ENGINE_DIR = path.dirname(fileURLToPath(import.meta.url));
 // literal stamped into the envelope's `spec` field, so the doc lines and the report can never drift.
 // Reused, never re-littered.
 const PKG_VERSION = JSON.parse(fs.readFileSync(path.join(ENGINE_DIR, "package.json"), "utf8")).version;
-const SPEC_VERSION = "0.13";
+const SPEC_VERSION = "0.14";
 
 // --version: a print-and-exit MODE, handled before the main arg walk so it never depends on a target.
 // Fully OFFLINE — candor never phones home. Staying current is the AGENT's job: read the installed
@@ -1091,9 +1091,57 @@ function enumerateGetters(owner, type) {
   }
 }
 
+// The synthesized `<module>` unit for a source file's TOP-LEVEL executable statements (spec §2
+// unitKind "initializer" — java's `<clinit>` twin). Top-level `await fetch(…)`, a bare
+// `readFileSync(…)`, an IIFE, `export const r = await fetch(…)` execute at MODULE-LOAD time and
+// belong to nothing named — without this unit their effects reached the SourceFile in `enclosing`,
+// resolved to `null`, and were DROPPED → a false "pure" verdict (the cardinal sin: ESM top-level
+// await / serverless handler files / side-effecting config modules scanned as functions: []). This
+// is the field-initializer `Class.constructor` synthesis (~scan.mjs:774) one level up: the module
+// body is the file's own initializer. Minted LAZILY — only when a top-level statement actually
+// attributes an effect/edge here — so a pure top-level never gains a unit (pure units are omitted).
+// The qual mirrors sibling top-level units (`moduleOf(sf).<module>`); the bare local is `<module>`.
+function moduleUnit(sf) {
+  const mod = moduleOf(sf);
+  const qual = `${mod}.<module>`;
+  let rec = fns.get(qual);
+  if (!rec) {
+    rec = { local: "<module>", direct: new Set(), edges: new Set(), hosts: new Set(), tables: new Set(),
+            cmds: new Set(), paths: new Set(), blind: new Set(), incomplete: new Set(), why: new Set(),
+            entry: false, unitKind: "initializer",
+            loc: `${path.relative(rootDir, sf.fileName)}:1:1` };
+    fns.set(qual, rec);
+  }
+  return qual;
+}
+// The synthesized static-initializer unit for a `class C { static { … } }` block (spec §2 unitKind
+// "initializer"). A static block runs at class-DEFINITION time, not instance construction — but its
+// body's effects otherwise walked up in `enclosing` to the ClassDeclaration, which maps to the
+// `C.constructor` unit, so a static-init effect was MISLABELED as the instance ctor (and carried no
+// unitKind). Mint it as its own unit, lazily, mirroring `moduleUnit`. (An anonymous class expression's
+// static block keys under `<anonymous>`; there is at most one static-init unit per class name.)
+function staticBlockUnit(node) {
+  const cls = node.parent;
+  const sf = node.getSourceFile();
+  const mod = moduleOf(sf);
+  const cname = (ts.isClassDeclaration(cls) || ts.isClassExpression(cls)) && cls.name ? cls.name.text : "<anonymous>";
+  const qual = `${mod}.${cname}.<static-init>`;
+  let rec = fns.get(qual);
+  if (!rec) {
+    rec = { local: "<static-init>", direct: new Set(), edges: new Set(), hosts: new Set(), tables: new Set(),
+            cmds: new Set(), paths: new Set(), blind: new Set(), incomplete: new Set(), why: new Set(),
+            entry: false, unitKind: "initializer",
+            loc: `${path.relative(rootDir, sf.fileName)}:${sf.getLineAndCharacterOfPosition(node.getStart()).line + 1}:1` };
+    fns.set(qual, rec);
+  }
+  return qual;
+}
 // nearest enclosing analyzed function (closures attribute to it — SEMANTICS §2)
 function enclosing(node) {
   for (let p = node; p; p = p.parent) {
+    // A `static { … }` block is its own initializer unit (class-definition time), NOT the instance ctor
+    // the ClassDeclaration maps to — intercept before the nodeName lookup would fold it into .constructor.
+    if (ts.isClassStaticBlockDeclaration(p)) return staticBlockUnit(p);
     // A call/effect lexically inside a DECORATOR (`@factory(arg)`) runs at class-DEFINITION time, NOT in
     // the decorated declaration's body. The parent chain of a decorator's expression is
     // CallExpression → Decorator → MethodDeclaration/ClassDeclaration/Parameter, so `enclosing` otherwise
@@ -1104,6 +1152,9 @@ function enclosing(node) {
     if (ts.isDecorator(p)) return null;
     const n = nodeName.get(p);
     if (n) return n;
+    // Reached the SourceFile with no named unit: a TOP-LEVEL executable statement. Attribute to the
+    // file's synthesized `<module>` initializer unit (minted lazily here) rather than dropping it.
+    if (ts.isSourceFile(p)) return moduleUnit(p);
   }
   return null;
 }
@@ -2236,7 +2287,10 @@ for (const [name, rec] of fns) {
   // them are NOT in `inferred`, so it is a LOWER BOUND when this is non-empty. Omitted when none.
   if (rec.blind.size) entry.invisible = [...rec.blind].sort();
   if (rec.entry) entry.entryPoint = true;
-  if (rec.isCjsExport) entry.unitKind = "export"; // spec 0.5 draft, informative — per-unit, not by name
+  // unitKind (spec §2, informative — per-unit, not by name): the synthesized `<module>` initializer
+  // carries its own kind (set at mint), a CJS export is tagged "export".
+  if (rec.unitKind) entry.unitKind = rec.unitKind;
+  else if (rec.isCjsExport) entry.unitKind = "export"; // spec 0.5 draft, informative — per-unit, not by name
   functions.push(entry);
 }
 // `package` names what this report COVERS — a consumer chaining it registers coverage even when