candor-ts 0.7.5 → 0.7.7

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 0.5.1 (spec 0.5)."* On a
+> plainly which version they're on** — e.g. *"This project is on candor-ts 0.7.1 (spec 0.7)."* 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`.
 >
@@ -20,8 +20,8 @@ chains by hand.
 > Net effect, so it will not reach the network to check itself. `candor-ts --version` prints the
 > installed build, the spec contract it speaks, and the upgrade line (`npm install -g
 > candor-ts@latest`) — fully offline. **You** have the network: compare the installed version against
-> npm. If it's behind, **ask the user before upgrading** — e.g. *"candor-ts 0.5.2 is available
-> (you're on 0.5.1) — upgrade before I scan?"* — and run `npm install -g candor-ts@latest` (or `npx
+> npm. If it's behind, **ask the user before upgrading** — e.g. *"candor-ts 0.7.2 is available
+> (you're on 0.7.1) — upgrade before I scan?"* — and run `npm install -g candor-ts@latest` (or `npx
 > -y candor-ts@latest`) only if they agree. Never upgrade silently: an analysis tool's version is
 > part of its result's provenance, so the user decides when it changes. If it's already current (or
 > the user declines), just proceed; if candor isn't installed at all, install it normally.
@@ -56,7 +56,7 @@ pure functions are omitted** — a function present in the callgraph sidecar but
 (a test file? an unexported arrow inside an object literal?) — conclude nothing.
 
 A dist-CJS export unit (a `module.exports` surface scanned with `--allow-js`) carries
-`unitKind: "export"` (spec 0.5 draft, informative); ordinary functions omit the field.
+`unitKind: "export"` (spec 0.7, informative); ordinary functions omit the field.
 
 **Multi-package (monorepos / private deps):** point `CANDOR_DEPS` at the dependencies' reports
 (a path list, or a directory of `*.json`); an unclassified call into a package with a loaded

package/package.json

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

package/query.mjs

@@ -17,6 +17,8 @@
  *   node query.mjs whatif   <prefix> <fn> <Effect> [policy-file] [0|1]
  */
 import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
 
 import { parsePolicy, scopeMatches } from "./policy.mjs";
 import { printAgents } from "./contract.mjs";
@@ -31,6 +33,61 @@ import { impact as coreImpact, path as corePath, gains as coreGains,
          loadReport, loadCallgraph, matches } from "./query-core.mjs";
 const emit = (v) => console.log(JSON.stringify(v, null, 1));
 
+// ONE version + spec source, the SAME way scan.mjs reads them: PKG_VERSION is the bare semver from
+// 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";
+
+// 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
+// usage, so the two can never drift back to a stale hand-list again.
+const SUBCOMMANDS = [
+  ["parsepolicy", "<file>", "parse a policy file (candor-spec §6.2) and print it as JSON"],
+  ["show", "<prefix> <query> [0|1]", "the effect record(s) for a function — direct, inferred, surfaces"],
+  ["where", "<prefix> <Effect> [0|1]", "functions with an effect, split into directly / inherited"],
+  ["callers", "<prefix> <query> [0|1]", "who reaches a function: {of, direct, transitive} (--include-unknown)"],
+  ["map", "<prefix> [0|1]", "per-module effect rollup: {effects, functions} by module"],
+  ["containment", "<prefix> [baseline-prefix]", "§6.1 boundary-effect dispersion; with a baseline, the leak ratchet (exit 1)"],
+  ["diff", "<cur-prefix> <base-prefix>", "per-function effect delta vs a baseline: {changes:[{fn,gained,lost}]} (exit 1 on a gain)"],
+  ["reachable", "<prefix>", "effects unioned over the entry points: what the app DOES at runtime"],
+  ["impact", "<prefix> <query>", "blast radius of a function (backward dual of reachable)"],
+  ["blindspots", "<prefix>", "the Unknown sources, ranked by blast radius"],
+  ["gains", "<cur-prefix> <base-prefix>", "the supply-chain alarm: what the surface gained between two reports"],
+  ["path", "<prefix> <fn> <Effect>", "a call path from a function to where an effect enters"],
+  ["whatif", "<prefix> <fn> <Effect> [policy-file] [0|1]", "the impact of giving a function an effect, vs a policy (exit 1 on a violation)"],
+  ["agents", "", "print the agent contract for this build (AGENTS.md)"],
+];
+
+// The full usage block — every real subcommand, replacing the stale hand-list. Printed to stderr on
+// the no-arg / unknown-command path (exit 2) and reused in --help (stdout, exit 0).
+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(`  ${"-h, --help".padEnd(w)}  show this help`);
+  return `USAGE: candor-ts-query <command> [args]\n\n${lines.join("\n")}`;
+};
+
+// --version / -V: a print-and-exit MODE, handled before the switch so it never depends on a command.
+// Fully OFFLINE — candor never phones home. Staying current is the AGENT's job.
+if (process.argv.includes("--version") || process.argv.includes("-V")) {
+  console.log(`candor-ts-query ${PKG_VERSION} (spec ${SPEC_VERSION})`);
+  console.log("upgrade: npm install -g candor-ts@latest");
+  process.exit(0);
+}
+
+// -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.
+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})
+
+${usage()}
+
+See https://github.com/tombaldwin/candor`);
+  process.exit(0);
+}
+
 const [, , cmd, ...args] = process.argv;
 switch (cmd) {
   case "--agents":
@@ -38,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": {
@@ -177,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)
@@ -191,6 +266,8 @@ switch (cmd) {
     break; // unreachable (process.exit), but eslint can't prove it — defends against fallthrough
   }
   default:
-    console.error("usage: node query.mjs <parsepolicy|show|where|callers|map|whatif> …");
+    // no command (cmd === undefined) or an unknown one: the FULL usage, not the stale 6-item list.
+    if (cmd !== undefined) console.error(`candor-ts-query: unknown command '${cmd}'`);
+    console.error(usage());
     process.exit(2);
 }

package/scan.mjs

@@ -41,23 +41,45 @@ const SPEC_VERSION = "0.7";
 // --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
 // build + upgrade line here, then (the agent has the network) compare against npm and upgrade.
-if (process.argv.includes("--version")) {
+if (process.argv.includes("--version") || process.argv.includes("-V")) {
   console.log(`candor-ts ${PKG_VERSION} (spec ${SPEC_VERSION})`);
   console.log("upgrade: npm install -g candor-ts@latest");
   process.exit(0);
 }
 
+// -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})
+
+USAGE: candor-ts <dir | file.ts | tsconfig.json> [--out <prefix>] [--json] [--policy <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
+  --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
+
+See https://github.com/tombaldwin/candor`);
+  process.exit(0);
+}
+
 // ---- args ----------------------------------------------------------------------------------------
 // ONE pass: the first non-flag is the target; value-taking flags consume the next arg and FAIL on a
 // 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>] [--policy <file>] [--allow-js] [--agents] [--version]";
+const usage = "usage: candor-ts <dir | file.ts | tsconfig.json> [--out <prefix>] [--json] [--policy <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;
+let target = null, outPrefix = null, policyPath = process.env.CANDOR_POLICY ?? 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") {
     const v = argv[i + 1];
@@ -65,7 +87,11 @@ for (let i = 0; i < argv.length; i++) {
     if (a === "--out") outPrefix = v; else policyPath = 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); }
@@ -152,13 +178,14 @@ if (!compilerOptions.typeRoots) {
   compilerOptions.typeRoots = roots;
 }
 if (!outPrefix) outPrefix = path.join(rootDir, ".candor", "report");
+// --json prints the report to stdout and writes NOTHING, so skip creating the (otherwise default) .candor/ dir.
 // The scanned package's name — the first half of the cross-package join key (SPEC §2 `hash`).
 let pkgName = path.basename(rootDir);
 try {
   const pj = JSON.parse(fs.readFileSync(path.join(rootDir, "package.json"), "utf8"));
   if (pj.name) pkgName = pj.name;
 } catch {}
-fs.mkdirSync(path.dirname(path.resolve(outPrefix)), { recursive: true });
+if (!wantJson) fs.mkdirSync(path.dirname(path.resolve(outPrefix)), { recursive: true });
 
 // A target with declared dependencies but no node_modules resolves almost nothing — the scan
 // would "succeed" with a near-total-Unknown report a fresh user could ship (CTA-dogfood finding).
@@ -170,8 +197,8 @@ fs.mkdirSync(path.dirname(path.resolve(outPrefix)), { recursive: true });
       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
@@ -1993,8 +2020,13 @@ for (const [name, rec] of fns) cg[name] = [...rec.edges].sort();
 // half-written report. An in-place writeFileSync leaves a truncation window where JSON.parse throws;
 // rename(2) is atomic within a filesystem, so a reader sees either the old report or the new one whole.
 const writeAtomic = (file, text) => { const tmp = `${file}.${process.pid}.tmp`; fs.writeFileSync(tmp, text); fs.renameSync(tmp, file); };
-writeAtomic(`${outPrefix}.json`, JSON.stringify(envelope, null, 1));
-writeAtomic(`${outPrefix}.callgraph.json`, JSON.stringify(cg, null, 1));
+// --json: print the §2 envelope to STDOUT instead of writing the report files (matches candor-scan/Rust).
+if (wantJson) {
+  console.log(JSON.stringify(envelope, null, 1));
+} else {
+  writeAtomic(`${outPrefix}.json`, JSON.stringify(envelope, null, 1));
+  writeAtomic(`${outPrefix}.callgraph.json`, JSON.stringify(cg, null, 1));
+}
 // Type-hierarchy sidecar (SPEC §4 / 0.7): each project class/interface (qualified `mod.Name`, matching
 // the `mod.Class.member` fn quals) -> its qualified direct supertypes/interfaces. Compact (O(types)),
 // lets `callers --include-unknown` resolve whether a confirmed reacher is an override of a `dispatch:`
@@ -2018,8 +2050,21 @@ for (const sf of sources) {
     ts.forEachChild(node, walk);
   })(sf);
 }
-writeAtomic(`${outPrefix}.hierarchy.json`, JSON.stringify(hierarchy, null, 1));
-console.error(`candor-ts: wrote ${functions.length} effectful functions (${fns.size} analyzed, ${sources.length} files) to ${outPrefix}.json`);
+if (!wantJson) {
+  writeAtomic(`${outPrefix}.hierarchy.json`, JSON.stringify(hierarchy, null, 1));
+  console.error(`candor-ts: wrote ${functions.length} effectful functions (${fns.size} analyzed, ${sources.length} files) to ${outPrefix}.json`);
+}
+{
+  // Effect breakdown — make the result visible at a glance, not just a count + a file path.
+  const counts = {};
+  for (const e of functions) for (const x of e.inferred) counts[x] = (counts[x] || 0) + 1;
+  const breakdown = ["Net", "Fs", "Db", "Exec", "Ipc", "Env", "Clipboard", "Clock", "Log", "Rand"]
+    .filter((k) => counts[k]).map((k) => `${k} ${counts[k]}`).join(" · ");
+  const unknown = counts.Unknown || 0;
+  if (breakdown || unknown) {
+    console.error(`  ${breakdown}${unknown ? `${breakdown ? "   ·   " : ""}Unknown ${unknown} (disclosed)` : ""}`);
+  }
+}
 if (unlistedSeen.size > 0) {
   const top = [...unlistedSeen.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]));
   const shown = top.slice(0, 8).map(([p, n]) => `${p} (${n} call${n === 1 ? "" : "s"})`).join(", ");
@@ -2043,7 +2088,10 @@ if (policyPath) {
   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);
+  // 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);