candor-ts 0.4.4 → 0.4.6

package/contract.mjs

@@ -0,0 +1,13 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+// The agent contract for THE INSTALLED VERSION — AGENTS.md ships in the npm tarball, so the doc and
+// engine cannot drift (the spec §2.1 version-trust rule applied to documentation). ONE implementation
+// used by both scan.mjs and query.mjs, so `--agents` output can never diverge within an install.
+export function printAgents() {
+  const dir = path.dirname(fileURLToPath(import.meta.url)); // the package root (where AGENTS.md ships)
+  const semver = JSON.parse(fs.readFileSync(path.join(dir, "package.json"), "utf8")).version;
+  console.log(`<!-- candor-ts ${semver} · the agent contract for this installed version -->`);
+  process.stdout.write(fs.readFileSync(path.join(dir, "AGENTS.md"), "utf8"));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "candor-ts",
-  "version": "0.4.4",
+  "version": "0.4.6",
   "description": "candor for TypeScript — per-function side effects, transitively, with a policy gate (candor-spec 0.4)",
   "type": "module",
   "dependencies": {
@@ -35,6 +35,7 @@
     "scan.mjs",
     "query.mjs",
     "policy.mjs",
+    "contract.mjs",
     "README.md",
     "AGENTS.md",
     "PROVE-IT.md",

package/query.mjs

@@ -19,6 +19,7 @@
 import fs from "node:fs";
 
 import { parsePolicy, scopeMatches } from "./policy.mjs";
+import { printAgents } from "./contract.mjs";
 
 // ---- the §3.1 match ladder: exact > segment-suffix > substring ------------------------------------
 function matchTier(name, q) {
@@ -44,16 +45,9 @@ 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"));
+  case "agents":
+    printAgents(); // shared with scan.mjs — one implementation, can't diverge within an install
     break;
-  }
   case "parsepolicy": {
     emit(parsePolicy(fs.readFileSync(args[0], "utf8")));
     break;

package/scan.mjs

@@ -25,6 +25,7 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { createRequire } from "node:module";
 import { parsePolicy, evaluatePolicy } from "./policy.mjs";
+import { printAgents } from "./contract.mjs";
 
 const ENGINE_DIR = path.dirname(fileURLToPath(import.meta.url));
 
@@ -51,14 +52,7 @@ for (let i = 0; i < argv.length; i++) {
   else if (outPrefix === null) outPrefix = a; // legacy positional prefix
   else { console.error(`candor-ts: unexpected extra argument ${a} (${usage})`); process.exit(2); }
 }
-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 (wantAgents) { printAgents(); process.exit(0); }
 if (target === null) { console.error(usage); process.exit(2); }
 
 // ---- project discovery (a dir, a single file, or a tsconfig) --------------------------------------
@@ -311,6 +305,21 @@ function firstStringLiteral(node) {
   }
   return null;
 }
+// Refine the Exec cliff (spec §4 ⟨0.5⟩): the effects a literal, statically-known subprocess head
+// implies, matched by basename. ADDED to a caller that already carries Exec (a subprocess is still
+// spawned — Exec is never dropped); an unrecognised head returns [] and keeps the bare cliff (never
+// guess). A candor engine reads Fs/Env only — spec §7 item 12 (the analyzer self-boundary) guarantees
+// it, so that case is spec-supplied. Only UNAMBIGUOUS single-effect tools belong here: a multi-modal
+// head (git status local vs git push Net; rsync local vs remote; make/npm run project code) would
+// fabricate the effect for its common case. The reference engines share this table verbatim.
+function commandHeadEffects(cmd) {
+  const base = cmd.trim().split(/\s+/)[0].split(/[/\\]/).pop();
+  if (["curl", "wget", "http", "ssh", "scp"].includes(base)) return ["Net"];
+  if (["psql", "mysql", "sqlite3", "mongosh", "redis-cli"].includes(base)) return ["Db"];
+  if (["candor", "candor-run.sh", "candor-scan", "candor-query", "candor-java",
+       "candor-classify", "candor-report", "cargo-candor"].includes(base)) return ["Env", "Fs"];
+  return [];
+}
 // host[:port] from an address/URL literal; non-address strings yield nothing (never fabricate).
 function hostLiteral(s) {
   const m = s.match(/^[a-z][a-z0-9+.-]*:\/\/([^/]+)/i);   // scheme://host[:port]/…
@@ -689,7 +698,11 @@ function visitCalls(node) {
           }
           if (eff === "Exec") {
             const lit = firstStringLiteral(node);
-            if (lit) rec.cmds.add(lit.trim().split(/\s+/)[0]); // the program of a command line
+            if (lit) {
+              rec.cmds.add(lit.trim().split(/\s+/)[0]); // the program of a command line
+              // a known literal head refines the cliff (curl→Net, candor→Fs/Env); Exec stays
+              for (const e of commandHeadEffects(lit)) rec.direct.add(e);
+            }
           }
           if (eff === "Fs") {
             const lit = firstStringLiteral(node);