candor-ts 0.4.2 → 0.4.4

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.2",
+  "version": "0.4.4",
   "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

@@ -29,19 +29,37 @@ import { parsePolicy, evaluatePolicy } from "./policy.mjs";
 const ENGINE_DIR = path.dirname(fileURLToPath(import.meta.url));
 
 // ---- 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]";
 const argv = process.argv.slice(2);
-if (argv.length === 0) {
-  console.error("usage: node scan.mjs <dir | file.ts | tsconfig.json> [--out <prefix>] [--policy <file>]");
-  process.exit(2);
+let target = null, outPrefix = null, policyPath = process.env.CANDOR_POLICY ?? null, allowJs = false, wantAgents = false;
+for (let i = 0; i < argv.length; i++) {
+  const a = argv[i];
+  if (a === "--agents") wantAgents = true;
+  else if (a === "--allow-js") allowJs = true;
+  else if (a === "--out" || a === "--policy") {
+    const v = argv[i + 1];
+    if (v === undefined || v.startsWith("--")) { console.error(`candor-ts: ${a} requires a value (${usage})`); process.exit(2); }
+    if (a === "--out") outPrefix = v; else policyPath = v;
+    i++;
+  }
+  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); }
 }
-const target = argv[0];
-let outPrefix = null, policyPath = process.env.CANDOR_POLICY ?? null, allowJs = false;
-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
+if (wantAgents) {
+  // 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 (target === null) { console.error(usage); process.exit(2); }
 
 // ---- project discovery (a dir, a single file, or a tsconfig) --------------------------------------
 function isTestPath(p) {
@@ -54,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); }
@@ -139,7 +180,10 @@ 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.2";
+// ONE version source: package.json. A second hardcoded literal (the envelope's, the --agents
+// banner's) that drifted from this would make the engine distrust its OWN reports at the §2.1
+// staleness check (`d.candor?.version !== ENGINE_VERSION`), silently downgrading every chained dep.
+const ENGINE_VERSION = `candor-ts-${JSON.parse(fs.readFileSync(path.join(ENGINE_DIR, "package.json"), "utf8")).version}`;
 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
@@ -336,7 +380,13 @@ function moduleOf(sf) {
   const rel = path.relative(rootDir, path.resolve(sf.fileName)).replace(/\.[mc]?[tj]sx?$/, "");
   return rel.split(path.sep).join(".");
 }
+// `_lastCjs` is set by markCjs when localName() returns a CJS export-surface name, read right after
+// the call to tag THAT unit (spec 0.5 draft unitKind: "export"). Keyed to the unit, not a project-
+// wide name set — a same-named ordinary TS function in another file must NOT be mislabeled.
+let _lastCjs = false;
+const markCjs = (v) => { if (v) _lastCjs = true; return v; };
 function localName(node) {
+  _lastCjs = false;
   if (ts.isFunctionDeclaration(node) && node.name) return node.name.text;
   if (ts.isMethodDeclaration(node) && ts.isClassDeclaration(node.parent) && node.parent.name)
     return `${node.parent.name.text}.${node.name.getText()}`;
@@ -371,10 +421,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;
@@ -382,7 +432,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;
@@ -434,11 +484,12 @@ for (const sf of sources) {
       nodeName.set(node, ctorQual);
     }
     const n = localName(node);
+    const isCjsExport = _lastCjs; // captured immediately: localName set it for THIS node only
     if (n) {
       const qual = `${mod}.${n}`;
       const { line, character } = sf.getLineAndCharacterOfPosition(node.getStart());
       fns.set(qual, { local: n, direct: new Set(), edges: new Set(), hosts: new Set(), tables: new Set(),
-                      cmds: new Set(), paths: new Set(), why: new Set(), entry: false,
+                      cmds: new Set(), paths: new Set(), why: new Set(), entry: false, isCjsExport,
                       loc: `${path.relative(rootDir, sf.fileName)}:${line + 1}:${character + 1}` });
       nodeName.set(node, qual);
       if ((ts.isVariableDeclaration(node) || ts.isPropertyDeclaration(node)) && node.initializer)
@@ -779,11 +830,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 (rec.isCjsExport) entry.unitKind = "export"; // spec 0.5 draft, informative — per-unit, not by name
   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.2", toolchain: `node-${process.versions.node}`, spec: "0.4" },
+const envelope = { candor: { version: ENGINE_VERSION, toolchain: `node-${process.versions.node}`, spec: "0.4" },
                    package: pkgName, functions };
 fs.writeFileSync(`${outPrefix}.json`, JSON.stringify(envelope, null, 1));
 const cg = {};