candor-ts 0.5.0 → 0.5.2

package/AGENTS.md

@@ -9,6 +9,23 @@ chains by hand.
 > 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.
 
+> **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
+> build too old for the flag, read `candor.version` / `candor.spec` from an existing
+> `.candor/report*.json`, or `npm ls -g candor-ts`.
+>
+> **Staying current is your job, not candor's.** candor never phones home — it audits and denies the
+> 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
+> -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.
+
 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.

package/README.md

@@ -20,6 +20,8 @@ node scan.mjs <project-dir>                 # tsconfig.json honored; tests exclu
                                             #   <dir>/.candor/report.json + .callgraph.json
 node scan.mjs . --policy .candor/policy     # the §6.2 gate: exit 1 on violation, 2 if unreadable
 
+node scan.mjs --version                     # installed build + spec contract (offline), + upgrade line
+
 node query.mjs show     .candor/report db.save 1   # a function's effects (match ladder)
 node query.mjs where    .candor/report Net 1       # direct sources vs inheritors
 node query.mjs callers  .candor/report db.save 1   # the blast radius (transitive callers)
@@ -28,6 +30,8 @@ node query.mjs whatif   .candor/report db.save Net policy  # pre-edit gate verdi
 node query.mjs diff     .candor/report baseline 1  # per-function effect delta (exit 1 on a gain)
 ```
 
+**Staying current:** check your installed version and upgrade — [candor/AGENTS.md §2a](https://github.com/tombaldwin/candor/blob/main/AGENTS.md#2a-staying-current--check-the-version-upgrade). `npx -y candor-ts --version` prints the build, the spec, and the upgrade one-liner (offline; candor never phones home).
+
 Function names are module-qualified with `.` segments (`src.db.save`), so policy scopes read
 naturally:
 

package/package.json

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

package/scan.mjs

@@ -30,12 +30,29 @@ import { isTestPath, kappa, kappaKnows, commandHeadEffects, hostLiteral, tablesI
 
 const ENGINE_DIR = path.dirname(fileURLToPath(import.meta.url));
 
+// The single version + spec sources, read once. PKG_VERSION is the bare semver from package.json
+// (e.g. "0.5.0"); ENGINE_VERSION (below) prefixes it for the report envelope's `version` field, and
+// `--version` prints the bare form. SPEC_VERSION is the spec contract this build speaks — the SAME
+// literal stamped into the envelope's `spec` field, so the doc lines and the report can never drift.
+// Reused, never re-littered.
+const PKG_VERSION = JSON.parse(fs.readFileSync(path.join(ENGINE_DIR, "package.json"), "utf8")).version;
+const SPEC_VERSION = "0.5";
+
+// --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")) {
+  console.log(`candor-ts ${PKG_VERSION} (spec ${SPEC_VERSION})`);
+  console.log("upgrade: npm install -g candor-ts@latest");
+  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]";
+const usage = "usage: candor-ts <dir | file.ts | tsconfig.json> [--out <prefix>] [--policy <file>] [--allow-js] [--agents] [--version]";
 const argv = process.argv.slice(2);
 let target = null, outPrefix = null, policyPath = process.env.CANDOR_POLICY ?? null, allowJs = false, wantAgents = false;
 for (let i = 0; i < argv.length; i++) {
@@ -175,7 +192,7 @@ fs.mkdirSync(path.dirname(path.resolve(outPrefix)), { recursive: true });
 // 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 ENGINE_VERSION = `candor-ts-${PKG_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
@@ -319,6 +336,14 @@ function localName(node) {
   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()}`;
+  // GET/SET ACCESSORS are units too — a property read/assignment that resolves to one edges here, so
+  // an accessor body that does I/O classifies normally instead of being a SILENT-PURE hole (and its
+  // effect is no longer misattributed to the enclosing class's synthesized ctor, which `enclosing()`
+  // would otherwise pick as the nearest unit). get/set are DISTINCT units (a class may have both for
+  // one name): `Class.get raw` / `Class.set raw`, mirroring how the checker keeps them apart.
+  if ((ts.isGetAccessorDeclaration(node) || ts.isSetAccessorDeclaration(node))
+      && ts.isClassDeclaration(node.parent) && node.parent.name)
+    return `${node.parent.name.text}.${ts.isGetAccessorDeclaration(node) ? "get" : "set"} ${node.name.getText()}`;
   // `const f = (…) => …` / `const f = function (…) {…}` at any binding site — the dominant style in
   // real TS (rimraf's whole API is arrow consts; the first dogfood analyzed 0 of 50 files without
   // this). The VARIABLE name is the function's name; nodeName is ALSO set on the initializer so a
@@ -473,6 +498,23 @@ function realDecl(sym) {
   return sym.valueDeclaration ?? sym.declarations?.[0];
 }
 
+// Accessor resolution (the silent-pure-accessor fix): a property READ (`x.raw`) or property
+// ASSIGNMENT target (`x.path = v`) may resolve to a getter/setter whose body performs effects. We
+// resolve the property-name symbol to its declarations and look for an accessor of the matching
+// kind (get for a read, set for an assignment LHS). Returns { decl, local } where `local` is true
+// when the accessor's declaration lives in a project file (a UNIT we minted; edge to it). A resolved
+// accessor we CAN'T see (external/typed-only declaration) returns local:false so the caller follows
+// the existing Unknown/curated-κ posture — never silent-pure for a resolved-but-unseen accessor.
+function accessorAt(propNode, kind /* "get" | "set" */) {
+  const sym = checker.getSymbolAtLocation(propNode.name ?? propNode);
+  if (!sym) return null;
+  const want = kind === "get" ? ts.isGetAccessorDeclaration : ts.isSetAccessorDeclaration;
+  // A symbol is an accessor only if its declarations include an accessor of the wanted kind.
+  const decl = (sym.declarations ?? []).find((d) => want(d));
+  if (!decl) return null;
+  return { decl, local: projectFiles.has(path.resolve(decl.getSourceFile().fileName)) };
+}
+
 // nearest enclosing analyzed function (closures attribute to it — SEMANTICS §2)
 function enclosing(node) {
   for (let p = node; p; p = p.parent) {
@@ -749,6 +791,35 @@ function visitCalls(node) {
     const owner = enclosing(node);
     if (owner) fns.get(owner).direct.add("Env");
   }
+  // GET/SET ACCESSOR access (the silent-pure-accessor fix): a property read that resolves to a
+  // getter, or a property assignment whose target resolves to a setter, is effectively a call into
+  // the accessor body — model it as a call EDGE so the accessor's effects propagate (like a method
+  // call), never silently pure. A resolved-but-UNSEEN accessor (external declaration) reads Unknown,
+  // following the same posture as an unresolvable call (SPEC §4).
+  if (ts.isPropertyAccessExpression(node) || ts.isElementAccessExpression(node)) {
+    // Is this property access the TARGET of an assignment (`x.prop = v`)? If so it's a setter site;
+    // otherwise it's a read (getter) site. (`x.prop += v` is both a read and a write, but the read
+    // side is the produced value — model it as a setter target only when it is the bare LHS of `=`.)
+    const p = node.parent;
+    const isAssignTarget = p && ts.isBinaryExpression(p) && p.left === node
+      && p.operatorToken.kind === ts.SyntaxKind.EqualsToken;
+    const hit = isAssignTarget ? accessorAt(node, "set") : accessorAt(node, "get");
+    if (hit) {
+      const owner = enclosing(node);
+      if (owner) {
+        const rec = fns.get(owner);
+        const t = nodeName.get(hit.decl);
+        if (hit.local && t) {
+          rec.edges.add(t); // (EDGE) into the accessor unit — effects propagate
+        } else {
+          // resolved to an accessor whose body we can't see → Unknown, never silent-pure (SPEC §4)
+          rec.direct.add("Unknown");
+          const an = hit.decl.parent?.name?.getText?.() ?? "?";
+          rec.why.add(`accessor:${an}.${node.name?.getText?.() ?? node.argumentExpression?.getText?.() ?? "?"}`);
+        }
+      }
+    }
+  }
   ts.forEachChild(node, visitCalls);
 }
 for (const sf of sources) visitCalls(sf);
@@ -822,7 +893,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: ENGINE_VERSION, toolchain: `node-${process.versions.node}`, spec: "0.5" },
+const envelope = { candor: { version: ENGINE_VERSION, toolchain: `node-${process.versions.node}`, spec: SPEC_VERSION },
                    package: pkgName, functions };
 const cg = {};
 for (const [name, rec] of fns) cg[name] = [...rec.edges].sort();