candor-ts 0.7.6 → 0.8.0

package/package.json

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

package/policy.mjs

@@ -56,10 +56,12 @@ export function parsePolicy(text) {
   return { deny, allow, forbid };
 }
 
-/** §6.2 scope match: by NAME SEGMENT over ".", last segment a prefix. */
+/** §6.2 scope match: by NAME SEGMENT, last segment a prefix.
+ * Segments split on BOTH "." and "::" — Rust/Java qualify with "::" while TS uses ".", and a shared
+ * policy must match across engines (a `Foo::bar` scope authored against Rust was inert in TS before). */
 export function scopeMatches(name, scope) {
-  const segs = name.split(".");
-  const parts = scope.split(".");
+  const segs = name.split(/[.:]+/).filter(Boolean);
+  const parts = scope.split(/[.:]+/).filter(Boolean);
   if (parts.length === 0 || parts.length > segs.length) return false;
   const last = parts[parts.length - 1], init = parts.slice(0, -1);
   outer: for (let i = 0; i + parts.length <= segs.length; i++) {
@@ -107,14 +109,19 @@ export function literalAllowed(effect, reached, values) {
  * transitive inferred; AS-EFF-008 allowlists over the transitive literal surfaces, the no-visible-
  * literal case flagged as uncertifiable; AS-EFF-009 forbid by reachability). One line per violation.
  */
+// Each violation is a STRUCTURED record { rule, fn, effects, detail } (candor-spec §3.3 ⟨0.8⟩): `effects`
+// is the specific denied/allowed effect set the violation concerns ([] for the 009 layer-flow, which has
+// no single effect); `detail` is the message BODY (no `[AS-EFF-00x]` prefix — the rule carries the code).
+// The console gate renders `[${rule}] ${detail}`; --gate-json emits the records verbatim.
 export function evaluatePolicy(pol, functions, callgraph, incomplete = new Map()) {
   const out = [];
   const surfaces = { Net: "hosts", Exec: "cmds", Fs: "paths", Db: "tables" };
+  const push = (rule, fn, effects, detail) => out.push({ rule, fn, effects, detail });
   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));
-      if (hits.length) out.push(`[AS-EFF-006] \`${f.fn}\` performs { ${hits.join(", ")} }, forbidden by policy: \`${r.raw}\``);
+      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) {
       if (r.scope && !scopeMatches(f.fn, r.scope)) continue;
@@ -125,14 +132,14 @@ export function evaluatePolicy(pol, functions, callgraph, incomplete = new Map()
       // invisible forbidden endpoint (the masking evasion). Matches candor-java 0.5.29 / candor-rust.
       const surfaceIncomplete = incomplete.get(f.fn)?.has(r.effect);
       if (reached.length === 0 || surfaceIncomplete) {
-        out.push(`[AS-EFF-008] \`${f.fn}\` performs ${r.effect} with no visible literal — the surface cannot be certified: \`${r.raw}\``);
+        push("AS-EFF-008", f.fn, [r.effect], `\`${f.fn}\` performs ${r.effect} with no visible literal — the surface cannot be certified: \`${r.raw}\``);
       } else {
         const bad = reached.filter((v) => !literalAllowed(r.effect, v, r.values));
-        if (bad.length) out.push(`[AS-EFF-008] \`${f.fn}\` reaches { ${bad.join(", ")} } outside the allowlist: \`${r.raw}\``);
+        if (bad.length) push("AS-EFF-008", f.fn, [r.effect], `\`${f.fn}\` reaches { ${bad.join(", ")} } outside the allowlist: \`${r.raw}\``);
       }
     }
   }
-  // AS-EFF-009: forbid A -> B by reachability over the callgraph.
+  // AS-EFF-009: forbid A -> B by reachability over the callgraph. No single effect → effects: [].
   for (const r of pol.forbid) {
     for (const fn of Object.keys(callgraph)) {
       if (!scopeMatches(fn, r.from)) continue;
@@ -146,7 +153,7 @@ export function evaluatePolicy(pol, functions, callgraph, incomplete = new Map()
           queue.push(c);
         }
       }
-      if (hit) out.push(`[AS-EFF-009] \`${fn}\` reaches into a forbidden layer (via \`${hit}\`), violating policy: \`${r.raw}\``);
+      if (hit) push("AS-EFF-009", fn, [], `\`${fn}\` reaches into a forbidden layer (via \`${hit}\`), violating policy: \`${r.raw}\``);
     }
   }
   return out;

package/query.mjs

@@ -37,7 +37,7 @@ const emit = (v) => console.log(JSON.stringify(v, null, 1));
 // 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.7";
+const SPEC_VERSION = "0.8";
 
 // The full subcommand catalogue — name + one-line description (derived from the per-subcommand
 // comments + the module-doc header). The single source for the --help list AND the no-arg/unknown
@@ -95,7 +95,15 @@ switch (cmd) {
     printAgents(); // shared with scan.mjs — one implementation, can't diverge within an install
     break;
   case "parsepolicy": {
-    emit(parsePolicy(fs.readFileSync(args[0], "utf8")));
+    // An unreadable/missing file is a clean exit-2 error, not an uncaught readFileSync stack trace.
+    let text;
+    try {
+      text = fs.readFileSync(args[0], "utf8");
+    } catch {
+      console.error(`candor: policy ${args[0] ?? "(no file given)"} could not be read`);
+      process.exit(2);
+    }
+    emit(parsePolicy(text));
     break;
   }
   case "show": {
@@ -234,8 +242,18 @@ switch (cmd) {
       for (const c of rev.get(n) ?? []) if (!affected.has(c)) { affected.add(c); queue.push(c); }
     }
     const violations = [];
-    if (maybePolicy && maybePolicy !== "0" && maybePolicy !== "1" && fs.existsSync(maybePolicy)) {
-      const pol = parsePolicy(fs.readFileSync(maybePolicy, "utf8"));
+    // A present policy arg (anything but the 0/1 verbosity sentinels) MUST exist and be readable —
+    // a typo'd path must be LOUD, not silently "no policy → ok:true, exit 0" (mirrors scan's --policy,
+    // which exits 2 on an unreadable file: a gate that can't read its policy can't certify anything).
+    if (maybePolicy && maybePolicy !== "0" && maybePolicy !== "1") {
+      let text;
+      try {
+        text = fs.readFileSync(maybePolicy, "utf8");
+      } catch {
+        console.error(`candor: policy ${maybePolicy} could not be read; whatif NOT evaluated against it`);
+        process.exit(2);
+      }
+      const pol = parsePolicy(text);
       for (const r of pol.deny) {
         if (r.effects.length && !r.effects.includes(eff)) continue; // pure ([]) forbids ANY effect
         for (const fn of affected)

package/scan.mjs

@@ -36,7 +36,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.7";
+const SPEC_VERSION = "0.8";
 
 // --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
@@ -52,13 +52,14 @@ if (process.argv.includes("--version") || process.argv.includes("-V")) {
 if (process.argv.includes("-h") || process.argv.includes("--help")) {
   console.log(`candor-ts ${PKG_VERSION} — TypeScript/JavaScript effect scanner (candor-spec ${SPEC_VERSION})
 
-USAGE: candor-ts <dir | file.ts | tsconfig.json> [--out <prefix>] [--json] [--policy <file>] [--allow-js] [--agents] [--version]
+USAGE: candor-ts <dir | file.ts | tsconfig.json> [--out <prefix>] [--json] [--policy <file>] [--gate-json <file>] [--allow-js] [--agents] [--version]
 
   <target>          a dir, a .ts file, or a tsconfig.json to scan
   --out <prefix>    write the report to <prefix>.json + <prefix>.callgraph.json
   --json            print the report as JSON to stdout (instead of writing files)
   --policy <file>   enforce a policy file (deny/pure/allow/forbid, candor-spec §6.2) — exit 1 on a
                     violation, 2 if unreadable; honours $CANDOR_POLICY when the flag is absent
+  --gate-json <f>   write the structured gate verdict { spec, ok, violations } as JSON (candor-spec §3.3)
   --allow-js        also scan plain JS/Node (.js/.mjs/.cjs), not just TypeScript
   --agents          print the agent contract for this build (AGENTS.md)
   -V, --version     print the build and spec version (offline)
@@ -73,21 +74,25 @@ See https://github.com/tombaldwin/candor`);
 // missing/flag-shaped value; an unknown flag fails; flags may precede the target. `--agents` is a
 // flag (a print-and-exit MODE) — it must NOT fire when it is the VALUE of --out/--policy, which the
 // value-consuming skip handles, nor produce a "lying unknown flag" error for a real flag given first.
-const usage = "usage: candor-ts <dir | file.ts | tsconfig.json> [--out <prefix>] [--json] [--policy <file>] [--allow-js] [--agents] [--version] [--help]";
+const usage = "usage: candor-ts <dir | file.ts | tsconfig.json> [--out <prefix>] [--json] [--policy <file>] [--gate-json <file>] [--allow-js] [--agents] [--version] [--help]";
 const argv = process.argv.slice(2);
-let target = null, outPrefix = null, policyPath = process.env.CANDOR_POLICY ?? null, allowJs = false, wantAgents = false, wantJson = false;
+let target = null, outPrefix = null, policyPath = process.env.CANDOR_POLICY ?? null, gateJsonPath = null, allowJs = false, wantAgents = false, wantJson = false;
 for (let i = 0; i < argv.length; i++) {
   const a = argv[i];
   if (a === "--agents") wantAgents = true;
   else if (a === "--json") wantJson = true;
   else if (a === "--allow-js") allowJs = true;
-  else if (a === "--out" || a === "--policy") {
+  else if (a === "--out" || a === "--policy" || a === "--gate-json") {
     const v = argv[i + 1];
     if (v === undefined || v.startsWith("--")) { console.error(`candor-ts: ${a} requires a value (${usage})`); process.exit(2); }
-    if (a === "--out") outPrefix = v; else policyPath = v;
+    if (a === "--out") outPrefix = v; else if (a === "--policy") policyPath = v; else gateJsonPath = v;
     i++;
   }
-  else if (a.startsWith("--")) { console.error(`candor-ts: unknown flag ${a} (${usage})`); process.exit(2); }
+  // Any leading-dash token that isn't a recognized flag is an unknown flag — NOT a positional target
+  // (SPEC §6.2/§7). `-h`/`-V`/`--help`/`--version` are print-and-exit modes consumed above, so by here
+  // a single-dash token (`-x`, the typo `-policy`) can only be a mistake; treating it as the scan
+  // target would silently scan the wrong thing.
+  else if (a.startsWith("-")) { console.error(`candor-ts: unknown flag ${a} (${usage})`); process.exit(2); }
   else if (target === null) target = a;
   else if (outPrefix === null) outPrefix = a; // legacy positional prefix
   else { console.error(`candor-ts: unexpected extra argument ${a} (${usage})`); process.exit(2); }
@@ -193,8 +198,8 @@ if (!wantJson) fs.mkdirSync(path.dirname(path.resolve(outPrefix)), { recursive:
       const deps = JSON.parse(fs.readFileSync(pkg, "utf8")).dependencies ?? {};
       if (Object.keys(deps).length > 0)
         console.error("candor-ts: WARNING — the target declares dependencies but has no node_modules; " +
-                      "imports will not resolve and most functions will read Unknown. " +
-                      "Run `npm install` in the target first.");
+                      "imports won't resolve, so calls into those packages read pure/invisible (not Unknown) " +
+                      "and effects through them are silently dropped. Run `npm install` in the target first.");
     } catch {}
   }
   // Prisma's client types are GENERATED — a project with the prisma dependency but no generated
@@ -2070,6 +2075,7 @@ if (unlistedSeen.size > 0) {
 }
 
 // ---- the standing §6.2 gate (--policy / CANDOR_POLICY) --------------------------------------------
+let gateViolations = [];
 if (policyPath) {
   let text;
   try {
@@ -2083,11 +2089,22 @@ if (policyPath) {
   // java/rust engines (not a report field) — passed to the gate so an incomplete surface fails closed.
   const incompleteMap = new Map();
   for (const [name, rec] of fns) if (rec.incomplete.size) incompleteMap.set(name, rec.incomplete);
-  const v = evaluatePolicy(parsePolicy(text), functions, cg, incompleteMap);
-  for (const line of v) console.log(line);
-  if (v.length) {
-    console.error(`candor-ts: ${v.length} policy violation(s)`);
-    process.exit(1);
-  }
-  console.error("candor-ts: policy ✓");
+  gateViolations = evaluatePolicy(parsePolicy(text), functions, cg, incompleteMap);
+  // In --json mode stdout is the §2 envelope and must stay pure JSON — route the gate's
+  // [AS-EFF-…] violation lines to stderr so a `candor-ts --json --policy … | jq` pipe never breaks.
+  const emitViolation = wantJson ? (l) => console.error(l) : (l) => console.log(l);
+  for (const x of gateViolations) emitViolation(`[${x.rule}] ${x.detail}`);
+}
+// --gate-json ⟨0.8⟩: the structured gate verdict { spec, ok, violations:[{rule,fn,effects,detail}] }, from
+// the SAME gateViolations that set the exit code (so it can't disagree). Written whenever the flag is set —
+// ok:true,[] when no gate is configured. Must precede the exit(1) below.
+if (gateJsonPath) {
+  const verdict = JSON.stringify({ spec: SPEC_VERSION, ok: gateViolations.length === 0, violations: gateViolations }, null, 1);
+  if (gateJsonPath === "-") console.log(verdict);
+  else writeAtomic(gateJsonPath, verdict + "\n");
+}
+if (policyPath && gateViolations.length) {
+  console.error(`candor-ts: ${gateViolations.length} policy violation(s)`);
+  process.exit(1);
 }
+if (policyPath) console.error("candor-ts: policy ✓");