candor-ts 0.8.3 → 0.8.5

package/lsp.mjs

@@ -7,6 +7,8 @@
  *     how many functions transitively call it (who is affected if it changes).
  *   • Diagnostics: the repo's architecture-policy verdict (the §6.2 gate, resolved from CANDOR_POLICY
  *     or the checked-in .candor/config — spec §3.4) as squiggles at each violating function's line.
+ *   • Hover: effect PROVENANCE — for each inherited effect, the `path` hop chain to the function that
+ *     performs it directly ("Net via mid → leaf (source)"), plus unknownWhy when the fn discloses opacity.
  *
  * The server is a pure CONSUMER of the spec report envelope + callgraph sidecar (any engine — JVM /
  * Rust / TS / Swift / agents; the same read layer as candor-mcp), and it never scans (the analyzer
@@ -29,7 +31,10 @@ import { fileURLToPath } from "node:url";
 import * as Q from "./query-core.mjs";
 import { discoverConfigPolicy, evaluatePolicy, parsePolicy } from "./policy.mjs";
 
-const VERSION = createRequire(import.meta.url)("./package.json").version;
+// Version: from the sibling package.json when running inside the npm package; a single-file BUNDLE of
+// this server (the IDE-plugin embedding) has no sibling package.json — fall back rather than crash.
+let VERSION = "bundled";
+try { VERSION = createRequire(import.meta.url)("./package.json").version; } catch { /* bundled */ }
 
 // ---- state (set at initialize) ---------------------------------------------------------------------
 let rootPath = null;
@@ -96,6 +101,43 @@ function codeLenses(docPath) {
   });
 }
 
+// ---- Hover: effect provenance at the cursor ----------------------------------------------------------
+// The entry ENCLOSING the hovered line: the report pins each fn at its declaration line, so the match is
+// the greatest entry line ≤ the cursor (functions are sequential in a file — a sound approximation that
+// needs no parser). For each inferred effect: direct → "performed here"; inherited → the §3.1 `path`
+// chain to the direct source. unknownWhy rides along when the fn introduces opacity.
+function hoverAt(docPath, line) {
+  const found = entriesInDoc(docPath);
+  if (!found || !found.length) return null;
+  const at = found.filter((x) => x.line <= line).sort((a, b) => b.line - a.line)[0];
+  if (!at) return null;
+  const { entry } = at;
+  const fns = Q.loadReport(reportPrefix);
+  const cg = Q.loadCallgraph(reportPrefix);
+  const lines = [`**${entry.fn}** — ⚡ { ${(entry.inferred || []).join(", ") || "pure"} }`];
+  for (const eff of entry.inferred || []) {
+    if (eff === "Unknown") continue;                          // covered by unknownWhy below
+    if ((entry.direct || []).includes(eff)) {
+      lines.push(`- **${eff}** — performed directly here`);
+      continue;
+    }
+    try {
+      const hops = (Q.path(fns, cg, entry.fn, eff)?.path || []).map((h) => h.fn.split(/[.:]+/).pop() + (h.source ? " (source)" : ""));
+      lines.push(hops.length > 1 ? `- **${eff}** — via ${hops.slice(1).join(" → ")}` : `- **${eff}** — inherited (source is cross-boundary or framework-synthesised)`);
+    } catch { lines.push(`- **${eff}** — inherited`); }
+  }
+  if (entry.unknownWhy?.length) lines.push(`- **Unknown** — ${entry.unknownWhy.join(", ")}`);
+  if (entry.invisible?.length) lines.push(`- _invisible_: ${entry.invisible.join(", ")} (unmodeled — the effect set is a lower bound)`);
+  try {
+    const c = Q.callers(cg, entry.fn);
+    lines.push(`\nBlast radius: **${(c?.transitive || []).length}** transitive caller(s)`);
+  } catch { /* no callgraph */ }
+  return {
+    contents: { kind: "markdown", value: lines.join("\n") },
+    range: { start: { line: at.line, character: 0 }, end: { line: at.line, character: 200 } },
+  };
+}
+
 // ---- Diagnostics (the live gate) ---------------------------------------------------------------------
 function activePolicy() {
   const env = process.env.CANDOR_POLICY;
@@ -151,6 +193,7 @@ function handle(msg) {
       capabilities: {
         textDocumentSync: { openClose: true, save: true, change: 0 },  // report-backed: buffer edits don't move the map
         codeLensProvider: { resolveProvider: false },
+        hoverProvider: true,
       },
       serverInfo: { name: "candor-lsp", version: VERSION },
     });
@@ -161,6 +204,10 @@ function handle(msg) {
   if (method === "textDocument/didChange") return;                    // see textDocumentSync: report-backed
   if (method === "textDocument/didClose")
     return send({ jsonrpc: "2.0", method: "textDocument/publishDiagnostics", params: { uri: params.textDocument.uri, diagnostics: [] } });
+  if (method === "textDocument/hover") {
+    try { return result(id, hoverAt(fileURLToPath(params.textDocument.uri), params.position?.line ?? 0)); }
+    catch { return result(id, null); }   // hover is best-effort — null, never a crash
+  }
   if (method === "textDocument/codeLens") {
     try { return result(id, codeLenses(fileURLToPath(params.textDocument.uri))); }
     catch { return result(id, []); }   // a non-file URI / unreadable report → no lenses, never a crash

package/mcp.mjs

@@ -162,12 +162,14 @@ const TOOLS = {
   candor_diff: {
     description: "The per-function effect delta versus a baseline report: gained (introduced vs inherited) and lost effects. 'What did this change do to the effect surface?'.",
     schema: { type: "object", properties: { baseline: { type: "string", description: "the baseline report prefix" }, ...reportArg }, required: ["baseline"] },
-    run: (a, p) => Q.diff(Q.loadReport(p), Q.loadReport(a.baseline)),
+    run: (a, p) => ({ baseline_version: Q.reportVersion(a.baseline) ?? "", engine_version: Q.reportVersion(p) ?? "",
+                      ...Q.diff(Q.loadReport(p), Q.loadReport(a.baseline)) }),
   },
   candor_gains: {
     description: "The supply-chain alarm: effects the surface GAINED versus a baseline (package-level + per-function) — 'did this dependency bump add Net/Exec somewhere?'.",
     schema: { type: "object", properties: { baseline: { type: "string", description: "the baseline report prefix" }, ...reportArg }, required: ["baseline"] },
-    run: (a, p) => Q.gains(Q.loadReport(p), Q.loadReport(a.baseline)),
+    run: (a, p) => ({ baseline_version: Q.reportVersion(a.baseline) ?? "", engine_version: Q.reportVersion(p) ?? "",
+                      ...Q.gains(Q.loadReport(p), Q.loadReport(a.baseline)) }),
   },
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "candor-ts",
-  "version": "0.8.3",
+  "version": "0.8.5",
   "description": "candor for TypeScript \u2014 per-function side effects, transitively, with a policy gate (candor-spec 0.8)",
   "type": "module",
   "dependencies": {

package/query-core.mjs

@@ -55,6 +55,21 @@ function normFns(parsed, source) {
   return out;
 }
 
+/** The producing engine build of the report(s) at a prefix (the §2.1 envelope `candor.version`) — null
+ *  when unreadable/absent (a legacy bare array has no provenance). Baselines are comparable only to
+ *  their own producing version (§2.1): diff/gains consumers disclose a mismatch (an engine swap makes
+ *  "gained" effects ambiguous — unmasking vs regression — the baseline-invalidation rule, AGENTS §2a). */
+export function reportVersion(prefix) {
+  const files = fs.existsSync(`${prefix}.json`) ? [`${prefix}.json`] : siblings(prefix, isReport);
+  for (const f of files) {
+    try {
+      const v = JSON.parse(fs.readFileSync(f, "utf8"))?.candor?.version;
+      if (v) return String(v);
+    } catch { /* unreadable sibling — keep looking */ }
+  }
+  return null;
+}
+
 export function loadReport(prefix) {
   if (fs.existsSync(`${prefix}.json`)) {
     // The PRIMARY report parse must DISCLOSE-and-tolerate like the sibling path — a bare JSON.parse here

package/query.mjs

@@ -30,7 +30,7 @@ import { impact as coreImpact, path as corePath, gains as coreGains,
          show as coreShow, blindspots as coreBlindspots,
          callers as coreCallers, callersFrontier, loadHierarchy,
          containment as coreContainment,
-         loadReport, loadCallgraph, matches } from "./query-core.mjs";
+         loadReport, loadCallgraph, matches , reportVersion } from "./query-core.mjs";
 const emit = (v) => console.log(JSON.stringify(v, null, 1));
 
 // ONE version + spec source, the SAME way scan.mjs reads them: PKG_VERSION is the bare semver from
@@ -180,8 +180,19 @@ switch (cmd) {
       if (gained.length || lost.length) changes.push({ fn, gained, lost });
     }
     changes.sort((a, b) => a.fn.localeCompare(b.fn));
-    emit({ changes });
-    process.exit(changes.some((c) => c.gained.length) ? 1 : 0);
+    // §2.1: a baseline is comparable only to its own producing build — disclose a mismatch (the gains
+    // may be the engine reclassifying after a coverage batch, not the code changing). Same note + JSON
+    // provenance fields as the Rust candor-query (cross-engine parity, item 10).
+    const engineV = reportVersion(curPrefix), baseV = reportVersion(basePrefix);
+    const versionMismatch = engineV && baseV && engineV !== baseV;
+    if (versionMismatch)
+      console.error(`candor-ts: ⚠ baseline @${baseV} ≠ engine @${engineV} — some changes may be the engine reclassifying, not your code. Treat an engine swap as baseline-invalidating: review, then regenerate the baseline.`);
+    emit({ baseline_version: baseV ?? "", engine_version: engineV ?? "", changes });
+    // diff DISCLOSES (the posture) — it is not a gate. Its gained-effect exit 1 is a convenience for
+    // same-build ratchet use; under a version mismatch that signal is BOGUS (unmasking, not regression),
+    // so exit 0 and let the ⚠ inform — never deliver the wave as a CI failure (review §2.1: guards fail
+    // closed, queries disclose).
+    process.exit(!versionMismatch && changes.some((c) => c.gained.length) ? 1 : 0);
     break; // unreachable (process.exit), but eslint can't prove it — defends against fallthrough
   }
   case "reachable": {
@@ -215,7 +226,10 @@ switch (cmd) {
     // the supply-chain alarm (SPEC §5.1): {gained:[Effect], byFunction:[{fn,effect}]} — what the
     // surface gained between two reports (base → cur), the cross-engine machine-readable form.
     const [curPrefix, basePrefix] = args;
-    emit(coreGains(loadReport(curPrefix), loadReport(basePrefix)));
+    const gv = reportVersion(curPrefix), gbv = reportVersion(basePrefix);
+    if (gv && gbv && gv !== gbv)
+      console.error(`candor-ts: ⚠ baseline @${gbv} ≠ engine @${gv} — a "gained capability" may be the engine reclassifying, not the dependency changing. Regenerate both reports with one build to compare releases.`);
+    emit({ baseline_version: gbv ?? "", engine_version: gv ?? "", ...coreGains(loadReport(curPrefix), loadReport(basePrefix)) });
     break;
   }
   case "path": {