candor-ts 0.28.0 → 0.28.2

package/README.md

@@ -210,7 +210,7 @@ read the Rust source".
 
 ## Status
 
-0.19.x, speaking candor-spec 0.28: the analysis core, the gate (`--policy` / `--gate-json` /
+0.28.0, speaking candor-spec 0.28: the analysis core, the gate (`--policy` / `--gate-json` /
 `.candor/config`), the full §3.1 query surface (including `containment`, `blindspots`, the
 `--include-unknown` dispatch frontier, and ⟨0.24⟩ `gate --report` — the gate applied to an EXISTING
 report, byte-equivalent to `scan --policy`'s verdict), the MCP server, the LSP server, and the watch loop are

package/contract.mjs

@@ -21,7 +21,34 @@ export function printAgents() {
   // and drains on the way out, scan.mjs exits. THE SIBLING ROUTE AGAIN — sharing the PRINTER does not
   // share the EXIT, and the divergence lived in the caller the shared function was meant to protect.
   // Fixing it here rather than in scan.mjs is deliberate: the next caller inherits the fix.
+  //
+  // Two failure modes the first version of this did not handle, both specific to a PIPE, which is the
+  // case it exists for:
+  //   EPIPE  — the reader stopped early (`| head -n5`, `| grep -m1`, a consumer that closed). The old
+  //            console.log path exited 0 silently; a bare writeSync raises, and a print-and-exit mode
+  //            answering a contract request with a Node stack trace and exit 1 is a worse regression
+  //            than the truncation this replaced. Swallowed — the reader left, that is not our error.
+  //   EAGAIN — once stdout has been initialised, libuv puts the pipe in non-blocking mode and writeSync
+  //            THROWS rather than short-writing as soon as the payload exceeds the 64 KiB pipe buffer.
+  //            The contract is 24 KiB today, so this is latent, not live — and it would come back as
+  //            exactly the truncation-plus-noise this function was written to remove. Retry with a
+  //            small backoff (Atomics.wait is the only synchronous sleep available here).
   let off = 0;
   const buf = Buffer.from(out, "utf8");
-  while (off < buf.length) off += fs.writeSync(1, buf, off, buf.length - off); // a short write is legal
+  const idle = new Int32Array(new SharedArrayBuffer(4));
+  try {
+    while (off < buf.length) {
+      try { off += fs.writeSync(1, buf, off, buf.length - off); }   // a short write is legal
+      catch (e) { if (e.code !== "EAGAIN") throw e; Atomics.wait(idle, 0, 0, 1); }
+    }
+  } catch (e) {
+    if (e.code !== "EPIPE") throw e;
+    // SWALLOWED, BUT NOT SILENT. Exiting non-zero would make `--agents | head` a failure, which it is
+    // not. But a truncated contract with exit 0 and an empty stderr is verbatim the defect this function
+    // was rewritten to remove ("an agent piping candor-ts --agents into its context silently read a
+    // third of its own instructions") — so the reader-left case has to be STATED. stderr may be closed
+    // too; that write is best-effort by construction.
+    try { fs.writeSync(2, `candor-ts: --agents output was cut short at ${off} of ${buf.length} bytes `
+                        + `— the reader closed the pipe. This contract is INCOMPLETE.\n`); } catch { /* nothing left to tell */ }
+  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "candor-ts",
-  "version": "0.28.0",
+  "version": "0.28.2",
   "description": "candor for TypeScript \u2014 per-function side effects, transitively, with a policy gate (candor-spec 0.28)",
   "type": "module",
   "dependencies": {
@@ -20,7 +20,7 @@
   },
   "scripts": {
     "lint": "eslint *.mjs",
-    "test": "npm run lint && node --test test-unit.mjs && node test.mjs && node test-mcp.mjs && node test-lsp.mjs && node test-watch.mjs && npm run test:probe && npm run test:fuzz",
+    "test": "npm run lint && node --test test-unit.mjs && node test.mjs --parallel && node test-mcp.mjs && node test-lsp.mjs && node test-watch.mjs && npm run test:probe && npm run test:fuzz",
     "test:unit": "node --test test-unit.mjs",
     "test:probe": "node fabrication_probe.mjs",
     "test:fuzz": "node fuzz.mjs",

package/scan.mjs

@@ -2829,11 +2829,13 @@ for (const sf of sources) {
                       endLine: sf.getLineAndCharacterOfPosition(node.getEnd()).line + 1 });
       nodeName.set(node, qual);
       // Record a unit minted for a declaration with NO BODY, for the §3 disclosure pass below (see it
-      // for the argument). MIRROR `fns.set`'s last-write-wins EXACTLY — `.delete` on the bodied write is
-      // load-bearing, not tidiness: an overload set is N body-less signatures followed by the
-      // implementation under the SAME qual, so a plain `.add` would mark every real overloaded function
-      // in the project unanalysable and charge its callers Unknown. That is the over-charge half of the
-      // fix, and it is pinned by a fixture (`over`/`callsOver`, still `Fs` after this pass).
+      // for the argument). The `.delete` mirrors `fns.set`'s last-write-wins for the MODULE-LEVEL
+      // overload set (N body-less signatures then the implementation, all under one qual) — but it is
+      // NOT sufficient on its own, and assuming it was is how this fix shipped an over-charge: a
+      // FUNCTION-SCOPED unit gets `#line:col` appended to its qual, so each signature holds a distinct
+      // key, the implementation's delete never reaches them, and every signature was charged
+      // `Unknown[native:…]` over code that is fully visible. The disclosure pass below therefore asks
+      // the SYMBOL — which every overload in a set shares, at any scope — and that is the real guard.
       {
         const hasBodySlot = ts.isFunctionDeclaration(node) || ts.isMethodDeclaration(node)
           || ts.isConstructorDeclaration(node) || ts.isGetAccessorDeclaration(node)
@@ -5440,10 +5442,57 @@ function resolveDepEntryKey(pkg, subpath) {
 // zod's `ZodType._parse` one — excluding them takes zod's delta to +0 and hono's from +18 to +9, and
 // every one of the nine that remain is a true positive (`Deno.mkdir`/`writeFile` are Fs, `Deno.
 // upgradeWebSocket` and `FetcherLike.fetch` are Net, all declared in local `.d.ts` shims with no body).
+// Does a LOCAL body answer this declaration? Climbs `classOverrides` TRANSITIVELY: that index records
+// DIRECT-subclass overrides only, so `Base (abstract) → Mid (abstract) → Impl (bodied)` resolved to
+// `Mid.hook` — no body — and charged `Base.hook` Unknown even though `Impl.hook` is the sole concrete
+// implementation and fully analyzed. The two-level fixture could not see it, which is also why the
+// measured corpus deltas characterise one-level hierarchies only.
+// DIRECT overrides only — the transitive climb was REVERTED, and the reason is worth keeping. Climbing
+// removed the base member's Unknown for `Base → Mid (re-declares abstract) → Impl`, but the dispatch-site
+// fan-out (see `classOverrides` at the call site) is still ONE level, so nothing then carried Impl's
+// effect caller-ward: the caller vanished from the report entirely, which under SPEC §2 rule 3 is a
+// positive purity claim. `deny Unknown` AND `deny Fs` both passed over a real Fs. The Unknown was
+// COMPENSATING for the non-transitive fan-out, and the climb deleted the compensation without supplying
+// the thing it compensated for. Over-charging that shape is the survivable direction; under-reporting it
+// is not. The real fix is to build `classOverrides` transitively once, as `classDescendants` already is —
+// filed, not attempted here under a shipped-regression clock.
 const answeredByLocalBody = (node) => (classOverrides.get(node) ?? []).some((om) => !!om.body);
+// The IMPLEMENTATION of the overload set this body-less signature belongs to, if we analyzed it.
+// Keyed on the SYMBOL, not the unit name: every overload shares one symbol at any scope, where the
+// qual does not (a function-scoped unit carries a `#line:col` suffix to keep sibling scopes apart).
+// `!!d.body` ALONE IS NOT "is an implementation" — a ts.ModuleDeclaration has a `.body` too (its
+// ModuleBlock), so `declare function f(); declare namespace f {}` — the UMD/ambient shape of jQuery,
+// lodash, moment, chalk — matched the namespace as f's implementation, dropped the Unknown, and
+// reported the caller PURE. That is the axios cardinal sin reopened BY the pass that closed it, and it
+// shipped in 0.28.1. The kind guard is the fix: only a declaration form that can carry a FUNCTION body
+// can be an overload implementation.
+const canCarryABody = (d) => ts.isFunctionDeclaration(d) || ts.isMethodDeclaration(d)
+  || ts.isConstructorDeclaration(d) || ts.isGetAccessorDeclaration(d) || ts.isSetAccessorDeclaration(d);
+const overloadImplOf = (node) => {
+  const sym = node.name ? checker.getSymbolAtLocation(node.name) : undefined;
+  return (sym?.declarations ?? []).find((d) => d !== node && canCarryABody(d) && !!d.body);
+};
 for (const [qual, meta] of bodylessDecls) {
   const rec = fns.get(qual);
   if (!rec || answeredByLocalBody(meta.node)) continue;
+  // An overload SIGNATURE with a local implementation is not unanswerable — but neither is it empty,
+  // and skipping it silently was this fix's first mistake in the other direction. At MODULE level every
+  // overload shares one qual, so a call resolving to the signature lands on the implementation's unit
+  // by construction. FUNCTION-SCOPED, the quals differ, the checker resolves the call to the SIGNATURE,
+  // and the caller reached an empty unit and read PURE — a silent under-report that predates this pass
+  // (`outer` calling a nested overloaded `inner` that writes a file was pure before any of this). Edge
+  // the signature to the implementation and the existing fixpoint carries the real effect through.
+  // The `continue` must depend on an EDGE BEING FORMED, not merely on finding a declaration. `nodeName`
+  // is minted only for units in `projectFiles`, while the symbol's declarations span the whole program —
+  // a `/// <reference>` pull-in, a file outside the tsconfig `include`, a `declare module` augmentation.
+  // Skipping on a target we could not resolve drops the charge AND forms no edge: the disclosure pass
+  // failing OPEN. Fall through to the Unknown instead, which is what "we could not follow this" means.
+  const implDecl = overloadImplOf(meta.node);
+  const target = implDecl ? nodeName.get(implDecl) : undefined;
+  if (target) {
+    if (target !== qual) rec.edges.add(target);
+    continue;
+  }
   rec.direct.add("Unknown");
   // §4's dividing line, same as everywhere else in this file. An `abstract` member IS an unresolved
   // DISPATCH — owner type and member are both nameable, which is what `dispatch:` reserves itself for,