candor-ts 0.7.2 → 0.7.6

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.2",
+  "version": "0.7.6",
   "description": "candor for TypeScript — per-function side effects, transitively, with a policy gate (candor-spec 0.5)",
   "type": "module",
   "dependencies": {

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":
@@ -191,6 +248,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-core.mjs

@@ -63,6 +63,13 @@ export const KAPPA_RULES = [
   [/^(node:)?worker_threads$/, /^(postMessage|receiveMessageOnPort)$/, "Ipc"],
   // node:cluster — `fork()` spawns a worker PROCESS and wires its IPC channel.
   [/^(node:)?cluster$/, /^fork$/, "Ipc"],
+  // node:vm executes a runtime-supplied code STRING in-process — `runInThisContext`/`runInContext`/
+  // `runInNewContext`/`compileFunction`, and the same verbs on a `new vm.Script(code)`. Like `eval`,
+  // the effects are whatever the code does (opaque) → genuinely Unknown (NOT Exec: no subprocess).
+  // Was unmodeled inside the κ-covered @types/node, so `vm.runInThisContext(code)` read SILENT-PURE
+  // (a code-execution sink reported pure — found by real-world corpus testing). The why is attached at
+  // the classify site (the only κ rule that resolves to the Unknown trust-marker, SPEC §4).
+  [/^(node:)?vm$/, /^(runInThisContext|runInContext|runInNewContext|compileFunction)$/, "Unknown"],
   [/^(node:)?sqlite$/, null, "Db"],
   // the curated npm tier
   [/^(axios|got|node-fetch|undici|ws|socket\.io(-client)?|nodemailer)$/, null, "Net"],

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];
@@ -152,13 +174,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).
@@ -251,7 +274,17 @@ function declModule(decl) {
   if (m) return m[1];
   if (/typescript\/lib\/lib\..*\.d\.ts$/.test(f)) return "<es-lib>";
   m = f.match(/node_modules\/(@[^/]+\/[^/]+|[^/]+)\//);
-  if (m) return m[1];
+  if (m) {
+    // `@types/X` (DefinitelyTyped) provides types for the RUNTIME package X — map it to X so the curated κ
+    // tier (keyed by the runtime name: pg/ws/…) fires. Without this a package typed via @types resolved to
+    // "@types/pg", the `pg`→Db rule never matched, and the resolved-but-unmodeled external decl read
+    // SILENT-PURE — `pool.query()` in a real TS Postgres app (which MUST have @types/pg installed to use
+    // pg) reported pure (found by a node_modules corpus run). Scoped runtime pkgs use the `__` convention:
+    // `@types/babel__core` → `@babel/core`.
+    const tm = m[1].match(/^@types\/(.+)$/);
+    if (tm) return tm[1].includes("__") ? "@" + tm[1].replace("__", "/") : tm[1];
+    return m[1];
+  }
   return f;
 }
 
@@ -1489,7 +1522,13 @@ function visitCalls(node) {
           if (eff && (ts.isPropertyAccessExpression(node.expression) || ts.isElementAccessExpression(node.expression))
               && rootsAtStdStream(node.expression.expression))
             eff = null;
-          if (eff) rec.direct.add(eff);
+          if (eff) {
+            rec.direct.add(eff);
+            // a κ rule that resolves to the Unknown trust-marker (node:vm code execution) is a direct
+            // Unknown SOURCE — SPEC §4 requires a why on it, like eval's `reflect:eval`. (The rest of
+            // the κ table is concrete effects, which carry no why.)
+            if (eff === "Unknown") rec.why.add(`reflect:${mod.replace(/^node:/, "")}.${member}`);
+          }
           // the literal surfaces, read only at a CLASSIFIED call (SPEC §2)
           if (eff === "Net") {
             const lit = firstStringLiteral(node);
@@ -1658,6 +1697,19 @@ function visitCalls(node) {
       const owner = enclosing(node);
       if (owner) fns.get(owner).direct.add(geff);
     }
+    // dynamic `require(<non-literal>)` — the CJS twin of `import(m)` (which already discloses Unknown):
+    // it loads an arbitrary module and runs its top-level code, so the effects are opaque → Unknown. A
+    // LITERAL `require('fs')` is a static, resolvable load (pure until a member call), so ONLY a
+    // non-literal arg is the escape. Gated like `fetch`: a bare `require` whose symbol is NOT a project
+    // declaration (a project's own `function require()` shadow never fabricates). Under-disclose Unknown,
+    // never a concrete effect. (Found by real-world corpus testing; sibling of the node:vm fix.)
+    if (ts.isIdentifier(callee) && callee.text === "require"
+        && node.arguments?.length === 1 && !ts.isStringLiteralLike(node.arguments[0])
+        && !(checker.getSymbolAtLocation(callee)?.declarations ?? [])
+             .some((d) => projectFiles.has(path.resolve(d.getSourceFile().fileName)))) {
+      const owner = enclosing(node);
+      if (owner) { fns.get(owner).direct.add("Unknown"); fns.get(owner).why.add("reflect:require"); }
+    }
     // Object.assign(target, ...sources) copies each SOURCE's own enumerable props → invokes their
     // getters (the object-spread twin). Enumerate the sources' local getters.
     if (callee.getText().replace(/\s+/g, "") === "Object.assign") {
@@ -1964,8 +2016,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:`
@@ -1989,8 +2046,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(", ");