candor-ts 0.4.0 → 0.4.2

package/AGENTS.md

@@ -9,15 +9,11 @@ the TypeScript-specific production + query surface.
 
 ## Produce a report
 
-Not yet on npm — run from a clone (needs node ≥ 20):
+On npm (needs node ≥ 20):
 
 ```sh
-git clone --depth 1 https://github.com/tombaldwin/candor-ts /tmp/candor-ts 2>/dev/null \
-  || (cd /tmp/candor-ts && git pull -q)
-( cd /tmp/candor-ts && npm install --no-fund --no-audit )
-
-node /tmp/candor-ts/scan.mjs <project-dir>     # tsconfig.json honored; tests/node_modules excluded
-node /tmp/candor-ts/scan.mjs <dir> --allow-js  # also analyze .js/.mjs sources (walks the tree)
+npx -y candor-ts <project-dir>          # tsconfig.json honored; tests/node_modules excluded
+npx -y candor-ts <dir> --allow-js       # also analyze .js/.mjs sources (walks the tree)
 ```
 
 This writes `<project-dir>/.candor/report.json` and `.candor/report.callgraph.json` (override
@@ -46,7 +42,7 @@ downgraded to `Unknown` rather than silently trusted (spec §2.1). Caveat: a typ
 ## Query it (same names/shapes as the Rust and JVM engines — candor-spec §3.1)
 
 ```sh
-Q() { node /tmp/candor-ts/query.mjs "$@"; }; P=".candor/report"   # a function — works in bash AND zsh
+Q() { npx -y candor-ts-query "$@"; }; P=".candor/report"   # a function — works in bash AND zsh
 Q show     $P <fn-query> 1          # a function's effects (+ hosts/tables when visible)
 Q where    $P <Effect>   1          # {effect, directly, inherited}
 Q callers  $P <fn-query> 1          # the BLAST RADIUS: {of, direct, transitive} — works for pure fns

package/PROVE-IT.md

@@ -36,9 +36,7 @@ enclosing function). Also note roughly how
 many file-reads/searches it took you.
 
 STEP 3 — Run candor-ts:
-  git clone --depth 1 https://github.com/tombaldwin/candor-ts /tmp/candor-ts
-  (cd /tmp/candor-ts && npm install --no-fund --no-audit)
-  node /tmp/candor-ts/scan.mjs .
+  npx -y candor-ts .
 It writes .candor/report.json (per-function transitive effects) and .candor/report.callgraph.json
 (every analyzed function's direct callees, pure ones included).
 

package/README.md

@@ -106,4 +106,4 @@ spec §7.13: generated effect chains through every encoded call form, any silent
 conformance-held. The npm classifier tier is
 deliberately curated and will keep growing case-by-case. Entry points (Nest/Next populations),
 `unknownWhy` origins, `reachable`, cross-package inheritance (`CANDOR_DEPS` + the spec §2 `hash`,
-version-trusted per §2.1), and `--allow-js` are all in. Not yet on npm — run from the clone.
+version-trusted per §2.1), and `--allow-js` are all in. On npm: `npx -y candor-ts <dir>`.

package/package.json

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

package/scan.mjs

@@ -22,8 +22,12 @@
 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.length === 0) {
@@ -83,6 +87,20 @@ if (stat.isFile() && /tsconfig.*\.json$/.test(path.basename(target))) {
   }
 }
 if (fileNames.length === 0) { console.error(`candor-ts: no TypeScript sources under ${target}`); process.exit(2); }
+// 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). 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) {
+  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`).
 let pkgName = path.basename(rootDir);
@@ -121,7 +139,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.0";
+const ENGINE_VERSION = "candor-ts-0.4.2";
 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
@@ -765,7 +783,7 @@ for (const [name, rec] of fns) {
 }
 // `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.0", toolchain: `node-${process.versions.node}`, spec: "0.4" },
+const envelope = { candor: { version: "candor-ts-0.4.2", toolchain: `node-${process.versions.node}`, spec: "0.4" },
                    package: pkgName, functions };
 fs.writeFileSync(`${outPrefix}.json`, JSON.stringify(envelope, null, 1));
 const cg = {};