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

package/query.mjs

@@ -94,7 +94,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.15";
+const SPEC_VERSION = "0.16";
 
 // ---- 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]
@@ -307,7 +307,7 @@ const SUBCOMMANDS = [
 const usage = () => {
   const w = Math.max(...SUBCOMMANDS.map(([n, a]) => `${n} ${a}`.trimEnd().length));
   const lines = SUBCOMMANDS.map(([n, a, d]) => `  ${`${n} ${a}`.trimEnd().padEnd(w)}  ${d}`);
-  lines.push(`  ${"-V, --version".padEnd(w)}  print the build and spec version (offline)`);
+  lines.push(`  ${"-V, --version".padEnd(w)}  print the installed version + upgrade line (offline)`);
   lines.push(`  ${"-h, --help".padEnd(w)}  show this help`);
   return `USAGE: candor-ts-query <command> [args]\n\n${lines.join("\n")}`;
 };
@@ -321,12 +321,54 @@ if (process.argv.includes("--version") || process.argv.includes("-V")) {
 }
 
 // -h / --help: a print-and-exit MODE, handled before the switch (so `-h`'s single dash is never
-// mistaken for a command). Banner + USAGE + the full described subcommand list + the github footer.
+// mistaken for a command). House-style page: identity + model paragraph + COMMON/ALL ACTIONS
+// (the action names derived from SUBCOMMANDS, so the list can never go stale) + OPTIONS + footer.
+// The exit-2 error path keeps the denser fully-described usage() above.
 if (process.argv.includes("-h") || process.argv.includes("--help")) {
-  console.log(`candor-ts-query ${PKG_VERSION} — read-only queries over a candor report (candor-spec ${SPEC_VERSION})
+  const names = SUBCOMMANDS.map(([n]) => n);
+  const allActions = [names.slice(0, 9), names.slice(9)].map((row) => `  ${row.join("  ")}`).join("\n");
+  console.log(`candor-ts-query — read-only queries over a candor report.
 
-${usage()}
+Answers come from the report candor-ts wrote — discovered by walking up from the
+cwd to a .candor/ dir (CANDOR_REPORT overrides; --report pins a locator). No
+re-scan, no network. Every engine speaks the same grammar, so these actions and
+flags match the rest of the family.
 
+USAGE
+  candor-ts-query <action> [args] [options]
+
+COMMON ACTIONS
+  where <Effect>            the functions that perform an effect
+  path <fn> <Effect>        the call path by which a function reaches an effect
+  callers <fn>              who calls a function, direct and transitive
+  tour [N]                  the N most surprising transitive reaches (default 10)
+  blindspots                the Unknown sources worth resolving, ranked by reach
+  gains <current> <base>    what a new version newly reaches (the supply-chain diff)
+  fix <fn> <Effect>         the boundary hoist that would clear a violation
+
+ALL ACTIONS
+${allActions}
+
+OPTIONS  (uniform across every engine)
+  --report <locator>        use this report instead of discovering .candor/
+  --policy <file>           evaluate a policy — exit 1 on a violation (whatif, fix, fix-gate,
+                            unverified; CANDOR_POLICY / a .candor/config \`policy\` key when absent)
+  --json                    machine-readable output
+  --include-unknown         callers: also list the unresolved-dispatch frontier
+  --strict                  unverified: exit 1 on an unverified hole (advisory otherwise)
+  -V, --version             print the installed version + upgrade line (offline)
+  -h, --help                show this help
+
+  diff and gains take two positional report locators: <current> <baseline>. Run
+  candor-ts-query with no action for the full per-action argument list.
+
+EXAMPLES
+  candor-ts-query where Db
+  candor-ts-query path app.orders.render Net
+  candor-ts-query gains new/.candor/report.json old/.candor/report.json
+  candor-ts-query fix-gate --policy candor.policy
+
+Docs: candor.poly.io   ·   Verify an install: candor doctor
 See https://github.com/tombaldwin/candor`);
   process.exit(0);
 }
@@ -354,6 +396,9 @@ switch (cmd) {
     // written; the paths silently vanished) and dropped Exec `cmds` entirely. Call the shared show so
     // the CLI and the MCP `candor_show` are one implementation that cannot diverge again.
     const { prefix, args: [q] } = resolveReportVerb(args, 1);
+    // A missing/empty <query> is a LOUD usage error (exit 2, like candor-java) — never a silently-empty
+    // `[]` at exit 0, which reads as an authoritative "no such function" over a question never asked.
+    if (!q) { console.error("usage: candor-ts-query show <query> [--report <locator>] [--json]"); process.exit(2); }
     emit(coreShow(loadReportOrDie(prefix), q));
     break;
   }
@@ -362,6 +407,9 @@ switch (cmd) {
     // Hand-copies of core functions in this file have drifted three times (show, callers, diff); the
     // fix each time was the same: delegate, keep query.mjs as arg-parsing + emit + exit codes only.
     const { prefix, args: [eff] } = resolveReportVerb(args, 1);
+    // A missing/empty <Effect> is a LOUD usage error (exit 2, like candor-java's missing-arg path) —
+    // never an authoritative-empty {directly:[],inherited:[]} at exit 0 (a false all-clear shape).
+    if (!eff) { console.error("usage: candor-ts-query where <Effect> [--report <locator>] [--json]"); process.exit(2); }
     emit(coreWhere(loadReportOrDie(prefix), eff));
     break;
   }
@@ -370,6 +418,9 @@ switch (cmd) {
     // it, the byte-for-byte {of,direct,transitive} shape is unchanged (cross-engine parity). Call the
     // shared query-core so the CLI and MCP compute one truth (the prior inline copy had drifted before).
     const { prefix, args: [q], includeUnknown } = resolveReportVerb(args, 1, { includeUnknown: true });
+    // A missing/empty <query> is a LOUD usage error (exit 2, like candor-java) — never an empty
+    // {of:[],direct:[],transitive:[]} at exit 0 (reads as "nothing reaches it" for a fn never named).
+    if (!q) { console.error("usage: candor-ts-query callers <query> [--include-unknown] [--report <locator>] [--json]"); process.exit(2); }
     const cg = loadCallgraph(prefix);
     if (includeUnknown) emit(callersFrontier(cg, loadReportOrDie(prefix), loadHierarchy(prefix), q));
     else emit(coreCallers(cg, q));
@@ -465,6 +516,9 @@ switch (cmd) {
     // blast radius (backward dual of reachable) — reuses the shared query-core, the same logic the
     // MCP server serves. SPEC §3.1: {fn, affectedCount, affected, entryPoints:[{fn,inferred}]}.
     const { prefix, args: [q] } = resolveReportVerb(args, 1);
+    // A missing/empty <query> is a LOUD usage error (exit 2, like candor-java) — never an
+    // affectedCount:0 blast radius at exit 0 for a function that was never named.
+    if (!q) { console.error("usage: candor-ts-query impact <query> [--report <locator>] [--json]"); process.exit(2); }
     emit(coreImpact(loadReportOrDie(prefix), loadCallgraph(prefix), q));
     break;
   }
@@ -587,6 +641,10 @@ switch (cmd) {
     // pinned JSON shape. parseCanonical otherwise swallows --json, so detect it explicitly (as `tour` does).
     const wantJson = args.includes("--json");
     const { prefix, args: [fn, eff] } = resolveReportVerb(args, 2);
+    // BOTH positionals are required (`path <fn> <Effect>`) — a missing/empty one is a LOUD usage error
+    // (exit 2, like candor-java). Before this gate, one arg slid through as `<fn> undefined` and printed
+    // "does not perform undefined" at exit 0 — a false all-clear over a question that was never posed.
+    if (!fn || !eff) { console.error("usage: candor-ts-query path <fn> <Effect> [--report <locator>] [--json]"); process.exit(2); }
     const fns = loadReportOrDie(prefix);
     const cg = loadCallgraph(prefix);
     if (wantJson) emit(corePath(fns, cg, fn, eff));           // conformance PART 5 shape — UNCHANGED

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.15";
+const SPEC_VERSION = "0.16";
 
 // --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
@@ -55,25 +55,45 @@ if (process.argv.includes("--version") || process.argv.includes("-V")) {
 // -h / --help: a print-and-exit MODE (like --version), handled before the arg walk so `-h` (a single
 // dash) is never mistaken for the scan target by the positional fallthrough below.
 if (process.argv.includes("-h") || process.argv.includes("--help")) {
-  console.log(`candor-ts ${PKG_VERSION} — TypeScript/JavaScript effect scanner (candor-spec ${SPEC_VERSION})
+  console.log(`candor-ts — the TypeScript/JavaScript effect analyzer.
 
-USAGE: candor-ts <dir | file.ts | tsconfig.json> [--out <prefix>] [--json] [--policy <file>] [--gate-json <file>] [--allow-js] [--agents] [--version]
+Reads TS/JS source through the TypeScript compiler API — no build needed. Calls
+are resolved through the checker; a call that cannot be resolved reads Unknown,
+never silently pure. The report lands in .candor/, where candor-ts-query and the
+umbrella \`candor\` CLI discover it.
 
-  <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)
-  -h, --help        show this help
+USAGE
+  candor-ts <dir | file.ts | tsconfig.json> [flags]
 
-CANDOR_BASELINE=<report.json> (or a .candor/config \`baseline\` key) runs the AS-EFF-005 regression
-guard against a saved same-build report: exit 1 when an existing function gained an effect, exit 2
-on an unparseable or different-build baseline (never evaluated), a stderr note when absent.
+  The target is a project directory, a single .ts file, or a tsconfig.json.
 
+OPTIONS
+  --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) — exit 1 on a
+                            violation, 2 if unreadable
+  --gate-json <file>        write the structured gate verdict { spec, ok, violations } as JSON
+  --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 installed version + upgrade line (offline)
+  -h, --help                show this help
+
+ENVIRONMENT / CONFIG
+  CANDOR_POLICY=<file>           the policy when --policy is absent (a .candor/config
+                                 \`policy\` key works too)
+  CANDOR_BASELINE=<report.json>  (or a .candor/config \`baseline\` key) runs the AS-EFF-005
+                                 regression guard against a saved same-build report: exit 1
+                                 when an existing function gained an effect, exit 2 on an
+                                 unparseable or different-build baseline (never evaluated),
+                                 a stderr note when absent
+
+EXAMPLES
+  candor-ts .
+  candor-ts src --allow-js
+  candor-ts . --policy candor.policy --gate-json gate.json
+  candor-ts-query where Db          query the report this scan wrote
+
+Docs: candor.poly.io   ·   Verify an install: candor doctor
 See https://github.com/tombaldwin/candor`);
   process.exit(0);
 }
@@ -2616,6 +2636,20 @@ let gateViolations = [];
 //  · Valid + same build → per-fn compare: an EXISTING fn gaining an effect is an [AS-EFF-005]
 //    violation (exit 1, joins --gate-json); a fn absent from the baseline is NEW code, reviewed as
 //    such, not a regression. Baselines omit pure fns (spec §2), so absent-prior means no prior claim.
+//
+// ⟨0.16⟩ Callgraph-aware existence (SPEC §7 item 5). Reports OMIT pure functions, so a fn that
+// shipped PURE and now performs an effect is absent from the baseline report and reads as exempt "new
+// code" — the sharpest supply-chain shape escaping the guard. Fix: key existence on the baseline
+// CALLGRAPH sidecar (<baseline>.callgraph.json, §2.2 — it lists every project fn INCLUDING pure
+// leaves), exactly as `gains`'s `origin` existence test does (query-core.mjs `gains`: a fn is
+// "existing" if it is a baseline-callgraph node — a caller key or a callee):
+//  · sidecar PRESENT + loaded → a fn that is a baseline-callgraph node has baseline effect set ∅
+//    (pure → omitted from the report) and any effect now is a GAIN violation. pure→effectful is caught.
+//    A fn in NEITHER report nor callgraph genuinely did not exist → stays exempt "new".
+//  · sidecar ABSENT → degrade to report-only existence (pre-⟨0.16⟩: a formerly-pure fn reads as new;
+//    still catches an already-effectful fn WIDENING). One stderr note that the guard is weaker.
+//  · sidecar PRESENT-but-CORRUPT → fail closed (exit 2), like a corrupt baseline: a broken sidecar
+//    must not silently NARROW the guard back to report-only.
 if (baselinePath !== null) {
   const shownB = baselinePath === "" ? "(configured empty)" : baselinePath;
   if (baselinePath !== "" && !fs.existsSync(baselinePath)) {
@@ -2647,14 +2681,66 @@ if (baselinePath !== null) {
     for (const e of arr) {
       if (e && typeof e.fn === "string" && e.fn) base.set(e.fn, new Set(Array.isArray(e.inferred) ? e.inferred : []));
     }
+    // ⟨0.16⟩ Load the baseline callgraph sidecar next to the baseline report. The sidecar for a
+    // report at <stem>.json is <stem>.callgraph.json (scan.mjs writes exactly this pair). Three states:
+    //   loaded  — a parsed object → its node set (every key + every callee) keys existence, mirroring
+    //             the `gains` origin test (query-core.mjs). A baseline-callgraph node whose baseline
+    //             effects are ∅ (pure → omitted from the report) that now performs an effect is a GAIN.
+    //   absent  — no sidecar file → degrade to report-only existence + one stderr note (guard weaker).
+    //   corrupt — file present but not parseable / not a plain object → fail closed (exit 2). A broken
+    //             sidecar must not silently narrow the guard (SPEC §7 item 5).
+    // shownB may be "(configured empty)"; the real path is baselinePath here (non-null, exists).
+    const sidecarPath = baselinePath.replace(/\.json$/i, "") + ".callgraph.json";
+    let cgNodes = null;                                     // null = sidecar absent (report-only degrade)
+    if (fs.existsSync(sidecarPath)) {
+      let baseCg = null;
+      try { baseCg = JSON.parse(fs.readFileSync(sidecarPath, "utf8")); } catch { baseCg = undefined; }
+      // A non-object parse (null / array / number) is a corrupt sidecar: it cannot list nodes, and
+      // treating it as "absent" would silently narrow the guard — fail closed like a corrupt baseline.
+      if (baseCg === undefined || baseCg === null || typeof baseCg !== "object" || Array.isArray(baseCg)) {
+        console.error(`candor-ts: the baseline callgraph ${sidecarPath} is present but could not be parsed `
+          + `(corrupt/truncated?) — failing (exit 2); a broken sidecar must not silently narrow the guard to `
+          + `report-only. Regenerate the baseline with this build.`);
+        process.exit(2);
+      }
+      // The node set = every caller key + every callee (a pure leaf appears only as a callee), exactly
+      // as `gains` computes cgNodes. Non-array edge values are tolerated (skipped), matching loadCallgraph.
+      cgNodes = new Set(Object.entries(baseCg).flatMap(([k, vs]) => [k, ...(Array.isArray(vs) ? vs : [])]));
+    } else {
+      console.error(`candor-ts: no baseline callgraph sidecar at ${sidecarPath} — the AS-EFF-005 guard is `
+        + `WEAKER: existence falls back to the report, which omits pure functions, so a formerly-PURE fn `
+        + `turning effectful reads as new code and is NOT caught (only an already-effectful fn widening is). `
+        + `Regenerate the baseline with --out so the .callgraph.json is written alongside it.`);
+    }
+    const unknownOnly = [];   // ⟨0.16⟩ advisory: fns that gained ONLY Unknown vs the baseline
     for (const name of [...inferred.keys()].sort()) {
       const prior = base.get(name);
-      if (prior === undefined) continue;                    // new function — not a regression
-      const gained = [...inferred.get(name)].filter((x) => !prior.has(x)).sort();
-      if (gained.length) {
-        gateViolations.push({ rule: "AS-EFF-005", fn: name, effects: gained,
-          detail: `\`${name}\` gained effect { ${gained.join(", ")} } not present in the baseline` });
-      }
+      // ⟨0.16⟩ Existence ladder: in the baseline REPORT → its recorded inferred set is the prior;
+      // else a baseline-callgraph NODE (sidecar present) → it existed and was pure, so prior = ∅ (any
+      // effect now is a gain); else genuinely absent → new code, exempt. Without the sidecar (cgNodes
+      // null) only the report path decides, the pre-⟨0.16⟩ semantics.
+      const priorSet = prior !== undefined ? prior
+        : (cgNodes !== null && cgNodes.has(name)) ? new Set()   // baseline-pure node → ∅ prior
+        : null;                                                 // new function — not a regression
+      if (priorSet === null) continue;
+      const gained = [...inferred.get(name)].filter((x) => !priorSet.has(x)).sort();
+      if (!gained.length) continue;
+      // ⟨0.16⟩ the ratchet fires only on gaining a REAL boundary effect. An Unknown-ONLY gain is
+      // the §4 trust marker, not an effect (`pure` policies exclude it), and on version bumps it is
+      // dominated by resolution noise — DISCLOSE it (advisory), never fail the gate on it. Mirrors the
+      // reference engine (candor-scan gate.rs check_baseline).
+      const real = gained.filter((x) => x !== "Unknown");
+      if (!real.length) { unknownOnly.push(name); continue; }
+      gateViolations.push({ rule: "AS-EFF-005", fn: name, effects: real,
+        detail: `\`${name}\` gained effect { ${real.join(", ")} } not present in the baseline` });
+    }
+    if (unknownOnly.length) {
+      unknownOnly.sort();
+      const shown = unknownOnly.slice(0, 3).join(", ");
+      const more = unknownOnly.length > 3 ? ` (+${unknownOnly.length - 3} more)` : "";
+      console.error(`candor-ts: note — ${unknownOnly.length} function(s) gained an unresolved call `
+        + `(Unknown) vs the baseline but no real effect — advisory, NOT a regression (Unknown is the §4 `
+        + `trust marker, dominated by resolution noise on version bumps): ${shown}${more}`);
     }
   }
 }
@@ -2721,6 +2807,10 @@ if (gateJsonPath) {
 // gateViolations is non-empty only when a gate surface (policy / baseline) was active and fired.
 if (gateViolations.length) {
   console.error(`candor-ts: ${gateViolations.length} policy violation(s)`);
+  // FAILURE-only pointer at the engine's own remedy verb (append-only, same stream as the summary; a
+  // zero-violation run is byte-identical — the exit code, violation lines and summary text are pinned
+  // by the conformance suite and stay untouched).
+  console.error("→ candor-ts-query fix-gate names the remedy for each");
   process.exit(1);
 }
 if (policyPath !== null) console.error("candor-ts: policy ✓");