candor-ts 0.4.1 → 0.4.3

package/AGENTS.md

@@ -3,7 +3,13 @@
 You are working in a TypeScript project. **candor-ts** tells you, for every function, which side
 effects it can reach — network, filesystem, database, subprocess, env, clock — *including effects
 inherited transitively through any chain of calls across files*. Use it instead of tracing call
-chains by hand. The language-agnostic consumption contract is
+chains by hand.
+
+> **This document ships inside the package.** `npx -y candor-ts --agents` prints the contract for
+> the *installed* version — always prefer that over a vendored or fetched copy, which can describe
+> a different candor-ts than the one you are running.
+
+The language-agnostic consumption contract is
 [candor-spec/AGENTS.md](https://github.com/tombaldwin/candor-spec/blob/main/AGENTS.md); this file is
 the TypeScript-specific production + query surface.
 
@@ -32,6 +38,9 @@ pure functions are omitted** — a function present in the callgraph sidecar but
 `.functions[]` is pure (as far as the engine resolved). In *neither* file = never analyzed
 (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.
+
 **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
 report inherits that function's recorded transitive effects and literal surfaces, joined by the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "candor-ts",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "candor for TypeScript — per-function side effects, transitively, with a policy gate (candor-spec 0.4)",
   "type": "module",
   "dependencies": {

package/query.mjs

@@ -43,6 +43,17 @@ const emit = (v) => console.log(JSON.stringify(v, null, 1));
 
 const [, , cmd, ...args] = process.argv;
 switch (cmd) {
+  case "--agents":
+  case "agents": {
+    // The agent contract for THE INSTALLED VERSION — ships in the npm tarball, cannot drift.
+    const { dirname: qDirname, join: qJoin } = await import("node:path");
+    const { fileURLToPath: qFile } = await import("node:url");
+    const dir = qDirname(qFile(import.meta.url));
+    const semver = JSON.parse(fs.readFileSync(qJoin(dir, "package.json"), "utf8")).version;
+    console.log(`<!-- candor-ts ${semver} · the agent contract for this installed version -->`);
+    process.stdout.write(fs.readFileSync(qJoin(dir, "AGENTS.md"), "utf8"));
+    break;
+  }
   case "parsepolicy": {
     emit(parsePolicy(fs.readFileSync(args[0], "utf8")));
     break;

package/scan.mjs

@@ -23,14 +23,23 @@ import ts from "typescript";
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { createRequire } from "node:module";
 import { parsePolicy, evaluatePolicy } from "./policy.mjs";
 
 const ENGINE_DIR = path.dirname(fileURLToPath(import.meta.url));
 
 // ---- args ----------------------------------------------------------------------------------------
 const argv = process.argv.slice(2);
+if (argv.includes("--agents")) {
+  // The agent contract for THE INSTALLED VERSION — AGENTS.md ships in the npm tarball, so doc
+  // and engine cannot drift (the spec §2.1 version-trust rule applied to documentation).
+  const semver = JSON.parse(fs.readFileSync(path.join(ENGINE_DIR, "package.json"), "utf8")).version;
+  console.log(`<!-- candor-ts ${semver} · the agent contract for this installed version -->`);
+  process.stdout.write(fs.readFileSync(path.join(ENGINE_DIR, "AGENTS.md"), "utf8"));
+  process.exit(0);
+}
 if (argv.length === 0) {
-  console.error("usage: node scan.mjs <dir | file.ts | tsconfig.json> [--out <prefix>] [--policy <file>]");
+  console.error("usage: node scan.mjs <dir | file.ts | tsconfig.json> [--out <prefix>] [--policy <file>] [--agents]");
   process.exit(2);
 }
 const target = argv[0];
@@ -39,7 +48,17 @@ for (let i = 1; i < argv.length; i++) {
   if (argv[i] === "--out") outPrefix = argv[++i];
   else if (argv[i] === "--policy") policyPath = argv[++i];
   else if (argv[i] === "--allow-js") allowJs = true;
-  else if (!argv[i].startsWith("--") && !outPrefix) outPrefix = argv[i]; // legacy positional prefix
+  else if (argv[i].startsWith("--")) {
+    // An unknown flag must FAIL, not be silently ignored: a typo'd --policy drops the gate; an
+    // agent following a newer doc against an older binary deserves a loud "upgrade me" signal.
+    console.error(`candor-ts: unknown flag ${argv[i]} (usage: candor-ts <dir> [--out <prefix>] [--policy <file>] [--allow-js] [--agents])`);
+    process.exit(2);
+  }
+  else if (!outPrefix) outPrefix = argv[i]; // legacy positional prefix
+}
+if (target.startsWith("--")) {
+  console.error(`candor-ts: unknown flag ${target} (see usage)`);
+  process.exit(2);
 }
 
 // ---- project discovery (a dir, a single file, or a tsconfig) --------------------------------------
@@ -53,11 +72,34 @@ let rootDir, fileNames, compilerOptions = {
   types: ["node"],
   strict: true,
 };
+// The scanner CLASSIFIES through the builtin typings, so `node` always rides in `types` — a
+// project's `types: []` (legitimate for its own build) would blind the effect analysis itself.
+function withNodeTypes(options) {
+  const t = options.types && options.types.length ? options.types : [];
+  return { ...options, types: [...new Set([...t, "node"])] };
+}
+
 function fromTsconfig(cfgPath, baseDir) {
   const cfg = ts.readConfigFile(cfgPath, ts.sys.readFile);
   const parsed = ts.parseJsonConfigFileContent(cfg.config ?? {}, ts.sys, baseDir);
-  compilerOptions = { ...parsed.options, types: parsed.options.types ?? ["node"] };
-  return parsed.fileNames.filter((f) => !isTestPath(path.relative(baseDir, f)));
+  compilerOptions = withNodeTypes(parsed.options);
+  let names = parsed.fileNames;
+  // SOLUTION-STYLE configs (`files: [], references: [...]` — hono, most monorepo roots) list no
+  // sources themselves; follow the references one level and union their file lists (skipping
+  // test/bench configs by the same path rule). Found by the published-package probe: hono read
+  // "no TypeScript sources".
+  if (names.length === 0 && (parsed.projectReferences ?? []).length > 0) {
+    for (const ref of parsed.projectReferences) {
+      const refPath = ts.resolveProjectReferencePath(ref);
+      if (!fs.existsSync(refPath) || isTestPath(path.relative(baseDir, refPath))) continue;
+      const sub = ts.readConfigFile(refPath, ts.sys.readFile);
+      const subParsed = ts.parseJsonConfigFileContent(sub.config ?? {}, ts.sys, path.dirname(refPath));
+      if (names.length === 0) compilerOptions = withNodeTypes(subParsed.options);
+      names = names.concat(subParsed.fileNames);
+    }
+    names = [...new Set(names)];
+  }
+  return names.filter((f) => !isTestPath(path.relative(baseDir, f)));
 }
 const stat = fs.existsSync(target) ? fs.statSync(target) : null;
 if (!stat) { console.error(`candor-ts: no such path: ${target}`); process.exit(2); }
@@ -89,12 +131,16 @@ if (fileNames.length === 0) { console.error(`candor-ts: no TypeScript sources un
 // Builtin typings FALLBACK: the engine ships @types/node as its own dependency, so a target that
 // hasn't installed it still resolves node:fs/node:net/… (found by the first npx-distribution
 // probe: a bare fixture read Unknown for fs.readFileSync because nothing supplied the builtin
-// types). The TARGET's own @types win when present.
+// types). Resolved via the module system, NOT a fixed relative path — npm HOISTS dependencies, so
+// in an npx/install tree @types/node sits BESIDE candor-ts, not inside it (the second probe's
+// catch). The TARGET's own @types win when present.
 if (!compilerOptions.typeRoots) {
-  compilerOptions.typeRoots = [
-    path.join(rootDir, "node_modules", "@types"),
-    path.join(ENGINE_DIR, "node_modules", "@types"),
-  ];
+  const roots = [path.join(rootDir, "node_modules", "@types")];
+  try {
+    const req = createRequire(path.join(ENGINE_DIR, "scan.mjs"));
+    roots.push(path.dirname(path.dirname(req.resolve("@types/node/package.json"))));
+  } catch {}
+  compilerOptions.typeRoots = roots;
 }
 if (!outPrefix) outPrefix = path.join(rootDir, ".candor", "report");
 // The scanned package's name — the first half of the cross-package join key (SPEC §2 `hash`).
@@ -134,7 +180,7 @@ fs.mkdirSync(path.dirname(path.resolve(outPrefix)), { recursive: true });
 // scan and a .d.ts resolution). Version-aware trust (§2.1): a report from a DIFFERENT engine
 // version is downgraded to Unknown rather than silently trusted. Duplicate hashes (two same-named
 // exports in one package) UNION — a sound over-approximation, documented.
-const ENGINE_VERSION = "candor-ts-0.4.1";
+const ENGINE_VERSION = "candor-ts-0.4.3";
 const crossDeps = new Map(); // hash -> {inferred:Set, hosts:[], cmds:[], paths:[], tables:[]}
 // Packages a loaded sibling report COVERS — exempt from the κ ledger even when a call joins no
 // entry (reports omit pure functions: the silence is the purity claim, SPEC §2 rule 3 — the
@@ -331,6 +377,8 @@ function moduleOf(sf) {
   const rel = path.relative(rootDir, path.resolve(sf.fileName)).replace(/\.[mc]?[tj]sx?$/, "");
   return rel.split(path.sep).join(".");
 }
+const cjsLocal = new Set(); // CJS export-surface units (spec 0.5 draft unitKind: "export")
+const markCjs = (v) => { if (v) cjsLocal.add(v); return v; };
 function localName(node) {
   if (ts.isFunctionDeclaration(node) && node.name) return node.name.text;
   if (ts.isMethodDeclaration(node) && ts.isClassDeclaration(node.parent) && node.parent.name)
@@ -366,10 +414,10 @@ function localName(node) {
     if (ts.isBinaryExpression(p) && p.operatorToken.kind === ts.SyntaxKind.EqualsToken && p.right === node) {
       const lhs = p.left.getText().replace(/\s+/g, "");
       if (lhs === "module.exports")
-        return (ts.isFunctionExpression(node) && node.name?.text)
-          || path.basename(node.getSourceFile().fileName).replace(/\.[mc]?jsx?$/, "");
+        return markCjs((ts.isFunctionExpression(node) && node.name?.text)
+          || path.basename(node.getSourceFile().fileName).replace(/\.[mc]?jsx?$/, ""));
       const m = lhs.match(/^(?:module\.)?exports\.([A-Za-z_$][\w$]*)$/);
-      if (m) return m[1];
+      if (m) return markCjs(m[1]);
     }
     if (ts.isPropertyAssignment(p) && p.initializer === node && ts.isObjectLiteralExpression(p.parent)) {
       const g = p.parent.parent;
@@ -377,7 +425,7 @@ function localName(node) {
           && g.right === p.parent && g.left.getText().replace(/\s+/g, "") === "module.exports")
         // .text, not getText(): a string-literal key keeps its quotes under getText, minting a
         // hash like pkg#"sign" the consumer's pkg#sign join can never hit (/code-review).
-        return p.name.text ?? p.name.getText();
+        return markCjs(p.name.text ?? p.name.getText());
     }
   }
   return null;
@@ -774,11 +822,12 @@ for (const [name, rec] of fns) {
   if (inf.includes("Fs") && rec.paths.size) entry.paths = [...rec.paths].sort();
   if (rec.direct.has("Unknown") && rec.why.size) entry.unknownWhy = [...rec.why].sort();
   if (rec.entry) entry.entryPoint = true;
+  if (cjsLocal.has(rec.local)) entry.unitKind = "export"; // spec 0.5 draft, informative
   functions.push(entry);
 }
 // `package` names what this report COVERS — a consumer chaining it registers coverage even when
 // `functions` is empty (an all-pure package's report is its purity claim, SPEC §2 rule 3).
-const envelope = { candor: { version: "candor-ts-0.4.1", toolchain: `node-${process.versions.node}`, spec: "0.4" },
+const envelope = { candor: { version: "candor-ts-0.4.3", toolchain: `node-${process.versions.node}`, spec: "0.4" },
                    package: pkgName, functions };
 fs.writeFileSync(`${outPrefix}.json`, JSON.stringify(envelope, null, 1));
 const cg = {};