candor-ts 0.8.6 → 0.8.7

package/Cases.ts

@@ -0,0 +1,77 @@
+// The candor-spec conformance cases in TypeScript — paired by bare function name with the Rust and
+// Java fixtures; the expected effect sets are conformance/expected.json (the SAME oracle).
+import * as fsm from "node:fs";
+import * as netm from "node:net";
+import * as cp from "node:child_process";
+import * as cryptom from "node:crypto";
+import { DatabaseSync } from "node:sqlite";
+import * as winstonm from "winston";
+
+// --- one function per std-only effect ---
+export function fs_read(): void { try { fsm.readFileSync("/tmp/x"); } catch {} }
+export function net_connect(): void { try { netm.connect(1, "h"); } catch {} }
+export function exec_spawn(): void { try { cp.spawn("x"); } catch {} }
+// Exec-cliff refinement (spec §4 ⟨0.5⟩): a known literal head adds its effect; all engines must agree.
+export function exec_curl(): void { try { cp.spawn("curl"); } catch {} }
+// Exec-refinement reads the HEAD (argv[0]) only: a dynamic program with a literal ARGUMENT keeps the
+// bare cliff — "curl" in the args array must NOT fabricate Net (spec §4 ⟨0.5⟩: the head is argv[0]).
+export function exec_dyn_head(tool: string): void { try { cp.spawn(tool, ["curl"]); } catch {} }
+export function env_read(): void { void process.env.X; }
+export function clock_now(): void { void Date.now(); }
+// Rand: node:crypto's CSPRNG. candor-ts is syntactic (AST), so the builtin need not resolve at scan time.
+export function rand_gen(): void { void cryptom.randomBytes(16); }
+// Db: node:sqlite's DatabaseSync.exec is the store round-trip (named import — candor-ts tracks the symbol).
+export function db_query(): void { void new DatabaseSync(":memory:").exec("SELECT 1"); }
+export function log_msg(): void { winstonm.info("m"); }
+
+// --- purity (negative) ---
+export function pure_fn(): number { return 1 + 2; }
+
+// --- the Unknown trust contract: a function-valued field the engine cannot see through ---
+class Holder { cb: () => void = () => {}; }
+const h = new Holder();
+export function unknown_dyn(): void { const cb = h.cb; cb(); }
+
+// --- multi-effect union in one body ---
+export function combined(): void { try { fsm.readFileSync("/tmp/x"); netm.connect(1, "h"); } catch {} }
+
+// --- transitive propagation across a call ---
+export function transitive_leaf(): void { try { fsm.readFileSync("/tmp/x"); } catch {} }
+export function transitive_caller(): void { transitive_leaf(); }
+
+// --- an effect inside a closure attributes to the enclosing function (SEMANTICS §2) ---
+export function closure_effect(): void { const f = () => { try { fsm.readFileSync("/tmp/x"); } catch {} }; f(); }
+
+// --- Unknown propagates like an effect ---
+export function unknown_propagates(): void { unknown_dyn(); }
+
+// --- mixed: a concrete effect AND an Unknown in one transitive set ---
+export function mixed_unknown(): void { try { fsm.readFileSync("/tmp/x"); } catch {} unknown_dyn(); }
+
+// --- a 3-hop chain a -> b -> c(Net) ---
+export function hop_c(): void { try { netm.connect(1, "h"); } catch {} }
+export function hop_b(): void { hop_c(); }
+export function hop_a(): void { hop_b(); }
+
+// --- a caller unions the effects of two distinct callees ---
+export function union_b(): void { try { fsm.readFileSync("/tmp/x"); } catch {} }
+export function union_c(): void { try { netm.connect(1, "h"); } catch {} }
+export function union_a(): void { union_b(); union_c(); }
+
+// --- recursion: the fixpoint must terminate AND keep the effect ---
+export function recurse(n: number): void { if (n > 0) { void process.env.X; recurse(n - 1); } }
+
+// --- an effect in one branch only is still inferred (over-approximation) ---
+export function conditional(b: boolean): void { if (b) { try { cp.spawn("x"); } catch {} } }
+
+// --- transitive purity: a -> b -> c, all pure, stays pure (negative) ---
+export function pure_c(): number { return 3; }
+export function pure_b(): number { return pure_c(); }
+export function pure_a(): number { return pure_b(); }
+
+// --- a method call on a concrete LOCAL-type receiver propagates the method's effect ---
+export class Svc { act(): void { try { fsm.readFileSync("/tmp/x"); } catch {} } }
+export function method_call(s: Svc): void { s.act(); }
+
+// --- scheduler attribution: an effect inside a scheduled task attributes to the SCHEDULER ---
+export function sched(): void { setTimeout(() => { try { fsm.readFileSync("/tmp/x"); } catch {} }, 0); }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "candor-ts",
-  "version": "0.8.6",
-  "description": "candor for TypeScript \u2014 per-function side effects, transitively, with a policy gate (candor-spec 0.8)",
+  "version": "0.8.7",
+  "description": "candor for TypeScript — per-function side effects, transitively, with a policy gate (candor-spec 0.8)",
   "type": "module",
   "dependencies": {
     "@types/node": "^25.9.2",
@@ -40,6 +40,7 @@
     "node": ">=20"
   },
   "files": [
+    "Cases.ts",
     "scan.mjs",
     "query.mjs",
     "policy.mjs",

package/policy.mjs

@@ -120,7 +120,13 @@ export function evaluatePolicy(pol, functions, callgraph, incomplete = new Map()
   for (const f of functions) {
     for (const r of pol.deny) {
       if (r.scope && !scopeMatches(f.fn, r.scope)) continue;
-      const hits = r.effects.length === 0 ? f.inferred : f.inferred.filter((e) => r.effects.includes(e));
+      // `pure` (empty forbidden set) forbids every EFFECT — not `Unknown`, which is the §4 trust
+      // marker, not an effect (AS-EFF-003's concern; `deny Unknown <scope>` is the explicit knob).
+      // The reference engine (candor-java) and the rust deep engine exclude it identically; candor-ts
+      // wrongly counted an Unknown-only fn as a `pure` violation until 2026-07-09.
+      const hits = r.effects.length === 0
+        ? f.inferred.filter((e) => e !== "Unknown")
+        : f.inferred.filter((e) => r.effects.includes(e));
       if (hits.length) push("AS-EFF-006", f.fn, hits, `\`${f.fn}\` performs { ${hits.join(", ")} }, forbidden by policy: \`${r.raw}\``);
     }
     for (const r of pol.allow) {

package/scan.mjs

@@ -498,6 +498,27 @@ function moduleOf(sf) {
   const rel = path.relative(rootDir, path.resolve(sf.fileName)).replace(/\.[mc]?[tj]sx?$/, "");
   return rel.split(path.sep).join(".");
 }
+// Enclosing `namespace`/`module` blocks are NAME SEGMENTS (the family ruling: §6.2 scope segments
+// split on the same boundaries as the §3.1 query name ladder, and a namespace is a segment — rust
+// modules and swift enum-namespaces already qualify this way). A unit declared in
+// `export namespace app { … }` is `mod.app.fn`, so a layer policy authored against namespace layers
+// (`forbid app -> repo`, `deny Db app`) bites in TS instead of being silently inert. Returns the
+// dotted prefix ("app." / "a.b.") or "". Dotted (`namespace a.b`) and nested forms both contribute
+// each identifier segment; ambient string-named modules (`declare module "x"`) and `declare global`
+// augmentations contribute nothing (not lexical layers of THIS module).
+function namespacePrefixOf(node) {
+  const segs = [];
+  for (let p = node.parent; p && !ts.isSourceFile(p); p = p.parent) {
+    if (!ts.isModuleBlock(p)) continue;
+    // `namespace a.b { … }` nests ModuleDeclarations (a -> b -> block); walk the chain so every
+    // dotted segment lands, innermost-first up.
+    for (let d = p.parent; d && ts.isModuleDeclaration(d); d = ts.isModuleDeclaration(d.parent) ? d.parent : null) {
+      if (d.name && ts.isIdentifier(d.name) && !(d.flags & ts.NodeFlags.GlobalAugmentation))
+        segs.unshift(d.name.text);
+    }
+  }
+  return segs.length ? `${segs.join(".")}.` : "";
+}
 // Is `node` (a function-expression / method-declaration / arrow) the `get` or `set` member of an
 // accessor DESCRIPTOR object passed to `Object.defineProperty(target, key, desc)` /
 // `Object.defineProperties(target, { key: desc, … })` / `Object.create(proto, { key: desc, … })`?
@@ -698,7 +719,7 @@ for (const sf of sources) {
           }
         }
       }
-      const ctorQual = `${mod}.${node.name.text}.constructor`;
+      const ctorQual = `${mod}.${namespacePrefixOf(node)}${node.name.text}.constructor`;
       if (!fns.has(ctorQual)) {
         const { line, character } = sf.getLineAndCharacterOfPosition(node.getStart());
         fns.set(ctorQual, { local: `${node.name.text}.constructor`, direct: new Set(), edges: new Set(),
@@ -719,7 +740,11 @@ for (const sf of sources) {
       // shared entry — FABRICATING them onto a pure caller. `nodeName` is keyed by NODE identity, so a
       // per-node-unique key keeps resolution exact; only TOP-LEVEL units need the stable bare name a
       // consumer's hash-join targets (a function-scoped local is never an export, so nothing joins to it).
-      const qual = isFunctionScoped(node) ? `${mod}.${n}#${line + 1}:${character + 1}` : `${mod}.${n}`;
+      // Namespace segments go in the QUAL only; `local` (and so the §2 hash `pkg#local`) stays the
+      // bare name — a consumer's cross-package join resolves the callee's own name, never the
+      // producer's namespace nesting, so widening the hash would break report chaining.
+      const nsp = namespacePrefixOf(node);
+      const qual = isFunctionScoped(node) ? `${mod}.${nsp}${n}#${line + 1}:${character + 1}` : `${mod}.${nsp}${n}`;
       fns.set(qual, { local: n, 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, isCjsExport,
                       loc: `${path.relative(rootDir, sf.fileName)}:${line + 1}:${character + 1}` });
@@ -1486,7 +1511,7 @@ function visitCalls(node) {
                 // dispatch-frontier (callers --include-unknown) can resolve overrides against the
                 // hierarchy sidecar. Bare `decl.parent.name` would not match a reacher's declaringType.
                 const tn = decl.parent?.name
-                  ? `${moduleOf(decl.parent.getSourceFile())}.${decl.parent.name.getText()}`
+                  ? `${moduleOf(decl.parent.getSourceFile())}.${namespacePrefixOf(decl.parent)}${decl.parent.name.getText()}`
                   : "type";
                 const mn = decl.name?.getText?.() ?? "member";
                 rec.why.add(`dispatch:${tn}.${mn}`); // resolution landed on a type, not a body — canonical `dispatch:OWNER.member` (frontier-relevant)
@@ -2112,10 +2137,10 @@ for (const sf of sources) {
           let sym = checker.getSymbolAtLocation(t.expression);
           if (sym && sym.flags & ts.SymbolFlags.Alias) { try { sym = checker.getAliasedSymbol(sym); } catch { /* keep */ } }
           const d = (sym?.declarations ?? []).find((x) => ts.isClassDeclaration(x) || ts.isInterfaceDeclaration(x));
-          supers.push(d && d.name ? `${moduleOf(d.getSourceFile())}.${d.name.getText()}` : t.expression.getText());
+          supers.push(d && d.name ? `${moduleOf(d.getSourceFile())}.${namespacePrefixOf(d)}${d.name.getText()}` : t.expression.getText());
         }
       }
-      if (supers.length) hierarchy[`${mod}.${node.name.getText()}`] = supers;
+      if (supers.length) hierarchy[`${mod}.${namespacePrefixOf(node)}${node.name.getText()}`] = supers;
     }
     ts.forEachChild(node, walk);
   })(sf);

package/watch.mjs

@@ -121,6 +121,14 @@ async function main() {
   // NO .unref() — the interval is the ONLY thing keeping the process alive; unref'ing it made Node exit
   // ~0.6s after the startup scan, so the watcher did ONE scan and died while printing "Watching…" (the
   // whole feature was silently broken, and test-watch.mjs only tests the helpers, never the live loop).
+
+  // GRACEFUL stop: the documented quit is Ctrl-C, but the default SIGINT/SIGTERM handler TERMINATES —
+  // exit hooks never run, the stop reads as a signal death (no exit code) to a supervisor, and a child
+  // instrumented with NODE_V8_COVERAGE discards its coverage (the TESTING.md §6 flush rule — this made
+  // the live loop measure 0% while actually exercised). Handle both: announce, exit 0.
+  for (const sig of ["SIGINT", "SIGTERM"]) {
+    process.on(sig, () => { console.error(`candor-ts-watch: ${sig} — stopping`); process.exit(0); });
+  }
 }
 
 if (path.resolve(process.argv[1] || "") === path.resolve(fileURLToPath(import.meta.url))) main();