candor-ts 0.17.0 → 0.18.0

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.17)."*
+> plainly which version they're on** — e.g. *"This project is on candor-ts `<version>` (spec 0.18)."*
 > 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.17" }, functions }` envelope; pure fns omitted | SPEC §2/§2.1 |
+| `{ candor: { version, toolchain, spec: "0.18" }, 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.17.x, speaking candor-spec 0.17: the analysis core, the gate (`--policy` / `--gate-json` /
+0.18.x, speaking candor-spec 0.18: 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.17.0",
-  "description": "candor for TypeScript — per-function side effects, transitively, with a policy gate (candor-spec 0.17)",
+  "version": "0.18.0",
+  "description": "candor for TypeScript — per-function side effects, transitively, with a policy gate (candor-spec 0.18)",
   "type": "module",
   "dependencies": {
     "@types/node": "^25.9.2",

package/query.mjs

@@ -44,6 +44,18 @@ const emit = (v) => console.log(JSON.stringify(v, null, 1));
 // The §6 effect vocabulary — used to reject a typo'd effect name in `where` (corpus-audit #3). Kept in step
 // with SPEC §6 / the umbrella's list; an unknown name PRESENT in a report (a spec extension) is still allowed.
 const KNOWN_EFFECTS = ["Net", "Fs", "Db", "Llm", "Exec", "Env", "Clock", "Ipc", "Log", "Rand", "Clipboard", "Unknown"];
+// Suggest the nearest known flag for a typo (longest shared prefix ≥3): `--polciy` → `--policy` (#2).
+function didYouMeanFlag(unknown) {
+  const known = ["--report", "--policy", "--json", "--text", "--strict", "--include-unknown"];
+  const u = unknown.replace(/^-+/, "").toLowerCase();
+  let best = null, bestLen = 2;
+  for (const k of known) {
+    const kn = k.replace(/^-+/, "");
+    let s = 0; while (s < u.length && s < kn.length && u[s] === kn[s]) s++;
+    if (s >= 3 && s > bestLen) { bestLen = s; best = k; }
+  }
+  return best ? ` — did you mean \`${best}\`?` : "";
+}
 
 // ---- #8 output mode: PROSE at a TTY, JSON when piped or `--json` — so interactive `candor where Db` reads
 // like candor-java/-rust instead of dumping raw JSON, while a pipe/redirect (never a TTY) still yields the
@@ -184,7 +196,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.17";
+const SPEC_VERSION = "0.18";
 
 // ---- 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]
@@ -272,14 +284,21 @@ function parseCanonical(rawArgs, { policy = false, strict = false, includeUnknow
       if (i + 1 >= rawArgs.length) { console.error("candor-ts: --report requires a <locator> value (a directory, a .json report path, or a prefix)"); process.exit(2); }
       reportLocator = rawArgs[++i]; continue;
     }
-    if (policy && a === "--policy") {
+    if (a === "--policy") { // consumed for EVERY verb (a valid candor flag); used only by policy verbs
       if (i + 1 >= rawArgs.length) { console.error("candor-ts: --policy requires a <file> value"); process.exit(2); }
-      policyFile = rawArgs[++i]; continue;
+      const v = rawArgs[++i]; if (policy) policyFile = v; continue;
     }
     if (a === "--json" || a === "--text" || a === "--human") { continue; } // output-mode flags (#8) — consumed by
                                                                             // wantJsonOut(rawArgs), never a positional
-    if (strict && a === "--strict") { wantStrict = true; continue; }
-    if (includeUnknown && a === "--include-unknown") { wantIncludeUnknown = true; continue; }
+    if (a === "--strict") { if (strict) wantStrict = true; continue; }                       // vocabulary — tolerated everywhere,
+    if (a === "--include-unknown") { if (includeUnknown) wantIncludeUnknown = true; continue; } // used only by the verb that reads it
+    if (a.startsWith("-") && a.length > 1) {
+      // An unrecognized flag is a TYPO, not a positional — reject it LOUD (exit 2), never silently swallow.
+      // A swallowed `--polciy` runs the query with NO policy and exits green: a CI author who typos --policy
+      // ships a gate that never fires (corpus re-audit cardinal sin — a loud error, never a silent guess).
+      console.error(`candor-ts-query: unknown flag '${a}'${didYouMeanFlag(a)}\n  known flags: --report, --policy, --json, --text, --strict, --include-unknown`);
+      process.exit(2);
+    }
     positionals.push(a);
   }
   // Deprecated trailing `0|1` JSON sentinel (Rust/TS legacy): if the LAST positional is a bare 0 or 1,
@@ -384,11 +403,11 @@ const SUBCOMMANDS = [
   ["impact", `<query> ${REPORT_TAIL}`, "blast radius of a function (backward dual of reachable)"],
   ["blindspots", REPORT_TAIL, "the Unknown sources, ranked by blast radius"],
   ["tour", `[<N>] ${REPORT_TAIL}`, "the N most surprising transitive reaches — the guided cold-repo poke (no re-scan)"],
-  ["gains", "<current> <baseline> [--json]", "the supply-chain alarm: what the surface gained between two reports"],
+  ["gains", "<current> <baseline> [--json] [--strict]", "the supply-chain alarm: what the surface gained between two reports (--strict: exit 1 on ANY gain)"],
   ["path", `<fn> <Effect> ${REPORT_TAIL}`, "a call path from a function to where an effect enters"],
   ["whatif", `<fn> <Effect> [--policy <file>] ${REPORT_TAIL}`, "the impact of giving a function an effect, vs a policy (exit 1 on a violation)"],
   ["fix", `<fn> <Effect> [--policy <file>] ${REPORT_TAIL}`, "the boundary fix: where the effect belongs + the hoist refactor"],
-  ["fix-gate", `[--policy <file>] ${REPORT_TAIL}`, "a fix for EVERY boundary crossing — the loop's block-message remedy"],
+  ["fix-gate", `[--policy <file>] [--strict] ${REPORT_TAIL}`, "a fix for EVERY boundary crossing — advisory (--strict: exit 1 while any remains)"],
   ["unverified", `[--policy <file>] [--strict] ${REPORT_TAIL}`, "pure/deny layers that PASS but are Unknown (not PROVABLY clean)"],
   ["agents", "", "print the agent contract for this build (AGENTS.md)"],
 ];
@@ -447,7 +466,9 @@ OPTIONS  (uniform across every engine)
   --json                    machine-readable JSON (the default when output is piped/redirected)
   --text, --human           human-readable prose (the default at a terminal)
   --include-unknown         callers: also list the unresolved-dispatch frontier
-  --strict                  unverified: exit 1 on an unverified hole (advisory otherwise)
+  --strict                  make an advisory verb a CI gate — exit 1 while a finding remains:
+                            unverified (an unverified-purity hole), fix-gate (a boundary
+                            crossing), gains (ANY gained effect). Advisory (exit 0) otherwise.
   -V, --version             print the installed version + upgrade line (offline)
   -h, --help                show this help
 
@@ -693,13 +714,33 @@ switch (cmd) {
       const out = { reaches: finds.map((f) => ({
         effect: f.effect, fn: f.func, hops: f.hops, loc: f.sourceLoc, score: f.score, source: f.source,
       })) };
+      // The MACHINE half of the mostly-Unknown disclosure (Fable-review finding E): a JSON consumer (the
+      // agent loop) got a bare `{"reaches":[]}` and read it as clean — the same false all-clear the text
+      // branch qualifies. ADDITIVE + present only when the ≥⅓-Unknown threshold trips (byte-identical
+      // otherwise). Keys sorted after `reaches` (reaches < unknown) to match Rust's serde output.
+      const teff = fns.filter((e) => (e.inferred ?? []).length > 0).length;
+      const tunk = fns.filter((e) => (e.inferred ?? []).includes("Unknown")).length;
+      if (teff > 0 && tunk * 3 >= teff) out.unknown = { count: tunk, total: teff };
       console.log(JSON.stringify(out));
       break;
     }
     if (finds.length === 0) {
       // Effectful-but-nothing-surprising vs genuinely-pure both land here; the honest line is the useful
-      // answer (never a manufactured surprise) — mirrors the scan-note fallback + the Rust engine.
-      console.log("candor: nothing hidden — every effect sits where its name says it should.");
+      // answer (never a manufactured surprise) — mirrors the scan-note fallback + the Rust engine. BUT never
+      // reassure "nothing hidden" over a meaningfully-Unknown graph (unresolved calls — missing tsconfig /
+      // imports): those Unknowns ARE the hidden part, their transitive effects unanalyzed (re-audit cardinal
+      // sin). Same ≥⅓-effectful-Unknown gate as the scan opener (surface.mjs emitSurface).
+      const teff = fns.filter((e) => (e.inferred ?? []).length > 0).length;
+      const tunk = fns.filter((e) => (e.inferred ?? []).includes("Unknown")).length;
+      if (teff > 0 && tunk * 3 >= teff) {
+        console.log(
+          `candor: no surprising reaches — but ${tunk} of ${teff} function(s) are Unknown `
+          + `(unresolved calls; their transitive effects are NOT analyzed). Run \`candor blindspots\`; `
+          + `a missing tsconfig.json or unresolvable imports are the usual cause.`,
+        );
+      } else {
+        console.log("candor: nothing hidden — every effect sits where its name says it should.");
+      }
       break;
     }
     console.log(`candor tour — the ${finds.length} most surprising reach${finds.length === 1 ? "" : "es"} in ${crateName}:`);
@@ -716,8 +757,13 @@ switch (cmd) {
     // surface gained between two reports (base → cur), the cross-engine machine-readable form.
     // §3.3.1: like diff, two positional locators <current> <baseline> (no discovery), each resolved by
     // the shared locator rule; --json accepted.
-    const { positionals } = parseCanonical(args, {});
-    if (positionals.length < 2) { console.error("usage: candor-ts-query gains <current> <baseline> [--json]"); process.exit(2); }
+    // gains has no `--policy` of its own: parseCanonical consumes `--policy` for every verb (a valid flag),
+    // which for gains would SILENTLY drop it and exit 0 — a CI author who reaches for `--policy` to gate a
+    // supply-chain diff ships a gate that never fires. Reject it loud and point at the real gate. `--strict`
+    // (below) fails on ANY gained effect; the effect-SPECIFIC gate is a `deny <E> gained` scan policy.
+    if (args.includes("--policy")) { console.error("candor-ts-query gains: unknown flag '--policy' — gains is a diff view; to FAIL CI on a newly-gained effect gate at scan time with a `deny <E> gained` policy (AS-EFF-005), or use `--strict` to fail on ANY gain\n  known flags: --json, --strict"); process.exit(2); }
+    const { positionals, strict } = parseCanonical(args, { strict: true });
+    if (positionals.length < 2) { console.error("usage: candor-ts-query gains <current> <baseline> [--json] [--strict]"); process.exit(2); }
     const [curPrefix, basePrefix] = positionals.map(locatorToPrefix);
     // BOTH locators must name real report files (the Rust engine's no-files check, named per side):
     // a typo'd prefix loaded [] with hardFail=false and emitted an authoritative EMPTY
@@ -736,10 +782,13 @@ switch (cmd) {
     // read as total), plus `coverageDelta` when the baseline names different blind packages. Both
     // OMITTED when nothing applies, so a coverage-free comparison is byte-identical to ⟨0.14⟩.
     // Shared with the MCP `candor_gains` tool (gainsCoverage — the parity rule).
+    const gainsResult = coreGains(loadReportOrDie(curPrefix), loadReportOrDie(basePrefix), loadCallgraph(basePrefix));
     put(args, { baseline_version: gbv ?? "", engine_version: gv ?? "",
-           ...coreGains(loadReportOrDie(curPrefix), loadReportOrDie(basePrefix), loadCallgraph(basePrefix)),
-           ...gainsCoverage(curPrefix, basePrefix) }, P.gains);
-    break;
+           ...gainsResult, ...gainsCoverage(curPrefix, basePrefix) }, P.gains);
+    // Advisory by default (exit 0 — gains is a diff view); `--strict` fails on ANY gained effect so a
+    // supply-chain CI job can require a bump introduce no new capability (mirrors `unverified --strict`).
+    process.exit(strict && (gainsResult.gained?.length ?? 0) > 0 ? 1 : 0);
+    break; // unreachable
   }
   case "path": {
     // BOTH a human default AND a --json form (like the Rust/Java engines). The surface opener suggests
@@ -818,15 +867,19 @@ switch (cmd) {
     // A remedy for EVERY deny/pure crossing — the shape the edit-time loop folds into its block message.
     // §3.3.1: `fix-gate [--policy <file>]`, report discovered / --report. DEPRECATED alias: the old
     // `fix-gate <prefix> <policy-file>` (leading report + positional policy).
-    const { prefix, policyFile } = resolveGateVerb(args);
+    // Advisory by default (exit 0 — the agent fix-loop reads the remedy and edits); `--strict` makes the
+    // exit follow `ok`, so CI can REQUIRE zero outstanding crossings (mirrors `unverified --strict`).
+    const { prefix, policyFile, strict } = resolveGateVerb(args, { strict: true });
     if (!policyFile) { console.error("candor: fix-gate requires a policy file (pass --policy <file>, or set CANDOR_POLICY / a .candor/config `policy` key)"); process.exit(2); }
     let ptext;
     try { ptext = fs.readFileSync(policyFile, "utf8"); }
     catch { console.error(`candor: policy ${policyFile} could not be read — no fix computed`); process.exit(2); }
     const cg = loadCallgraph(prefix);
     if (!cg || Object.keys(cg).length === 0) { console.error(`candor: no call-graph sidecar for '${prefix}' — fix-gate needs it (re-run: candor-ts <src> --out ${prefix})`); process.exit(2); }
-    emit(coreFixGate(cg, loadReportOrDie(prefix), parsePolicy(ptext), scopeMatches));
-    break;
+    const fgr = coreFixGate(cg, loadReportOrDie(prefix), parsePolicy(ptext), scopeMatches);
+    emit(fgr);
+    process.exit(strict && !fgr.ok ? 1 : 0);
+    break; // unreachable
   }
   case "unverified": {
     // PROVABLE-PURITY disclosure: pure/deny layers that PASS but contain Unknown (not provably clean). A

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.17";
+const SPEC_VERSION = "0.18";
 
 // --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

package/surface.mjs

@@ -215,8 +215,26 @@ export function bestFind(inferred, direct, calls, isTest = () => false) {
 // the sink (defaults to console.error). Mirrors surface.rs::emit exactly.
 export function emitSurface(inferred, direct, calls, loc, isTest = () => false, log = console.error) {
   const res = bestFind(inferred, direct, calls, isTest);
-  if (res === null) return; // zero effectful functions — emit nothing
-  if (res.winner === null) {
+  // A real SURPRISING reach is a genuine finding — show it (below), even amid Unknowns.
+  if (res !== null && res.winner !== null) { /* fall through to the surprising-reach message */ }
+  else {
+    // No surprising reach. But do NOT reassure "nothing hidden" over a meaningfully-UNKNOWN graph: those
+    // Unknowns (unresolved calls — e.g. a missing tsconfig.json, unresolvable imports) ARE the hidden part,
+    // and their transitive effects are unanalyzed. "nothing hidden" there is a false all-clear — the
+    // cardinal sin for a tool that sells transitive-reach detection (corpus re-audit). Qualify + point at
+    // blindspots. `bestFind` returns null for BOTH "no effectful fns" and "effectful-but-nothing-surprising
+    // (incl. all-Unknown)", so measure the Unknown fraction from `inferred` directly, not from `res`.
+    const total = [...inferred.values()].filter((s) => s.size > 0).length; // EFFECTFUL fns (pure units excluded)
+    const unknown = [...inferred.values()].filter((s) => s.has("Unknown")).length;
+    if (total > 0 && unknown * 3 >= total) { // ≥ ~1/3 of effectful functions Unknown → meaningfully unresolved
+      log(
+        `candor: no surprising reaches — but ${unknown} of ${total} function(s) are Unknown `
+        + `(unresolved calls; their transitive effects are NOT analyzed). Run \`candor blindspots\`; `
+        + `a missing tsconfig.json or unresolvable imports are the usual cause.`,
+      );
+      return;
+    }
+    if (res === null) return; // genuinely nothing effectful/surprising and few Unknowns — emit nothing
     log("candor: nothing hidden — every effect sits where its name says it should.");
     return;
   }