candor-ts 0.7.7 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "candor-ts",
-  "version": "0.7.7",
+  "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

@@ -109,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;
@@ -127,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;
@@ -148,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

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,18 +74,18 @@ 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++;
   }
   // Any leading-dash token that isn't a recognized flag is an unknown flag — NOT a positional target
@@ -2074,6 +2075,7 @@ if (unlistedSeen.size > 0) {
 }
 
 // ---- the standing §6.2 gate (--policy / CANDOR_POLICY) --------------------------------------------
+let gateViolations = [];
 if (policyPath) {
   let text;
   try {
@@ -2087,14 +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);
+  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 line of v) emitViolation(line);
-  if (v.length) {
-    console.error(`candor-ts: ${v.length} policy violation(s)`);
-    process.exit(1);
-  }
-  console.error("candor-ts: policy ✓");
+  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 ✓");