candor-ts 0.8.9 → 0.8.10

package/AGENTS.md

@@ -97,6 +97,8 @@ Q map      $P 1                     # {module: {effects, functions}}
 Q containment $P [baseline-prefix]  # §6.1 boundary-effect dispersion; with a baseline = AS-EFF-010 ratchet (exit 1 on a leak)
 Q blindspots $P                     # the Unknown SOURCES (fns with unknownWhy), ranked by Unknown blast radius
 Q whatif   $P <fn> <Effect> [policy]  # pre-edit gate verdict (exit 1 if it would violate)
+Q fix      $P <fn> <Effect> <policy>  # the boundary FIX: where the effect belongs + the hoist refactor
+Q fix-gate $P <policy>              # a fix for EVERY crossing — the loop's block-message remedy
 Q diff     $P <baseline-prefix> 1   # per-function effect delta (exit 1 on a gained effect)
 Q gains    $P <baseline-prefix>     # supply-chain alarm: {gained, byFunction} — effects a surface grew
 Q reachable $P 1                    # what the app DOES at runtime: effects over the entry points
@@ -105,13 +107,14 @@ Q parsepolicy <policy-file>         # the canonical §6.2 parse (what the gate w
 
 And as an MCP server, so an agent pulls these as tools instead of shelling out:
 `CANDOR_REPORT=$P npx -y candor-ts-mcp` (tools `candor_impact`/`candor_reachable`/`candor_where`/…,
-plus `candor_gate`/`candor_whatif` — a given-but-unreadable `policy` is a loud tool error, never a
-clean verdict). `npx -y candor-ts-watch <dir>` keeps the report fresh as you edit (and reports the
-edit-delta); `candor-lsp` serves the same report as CodeLens/hover/diagnostics in any LSP editor,
-plus the pre-edit whatif as a code action (`candor: what if <fn> performed <E>?` → the
-`candor.whatif` command: the query-core whatif's verdict + blast radius as a showMessage and a
-transient diagnostic, cleared on the file's next open/save — plain LSP, so helix/neovim/VS
-Code/JetBrains-via-LSP4IJ all get it without client code).
+plus `candor_gate`/`candor_whatif`/`candor_fix` — a given-but-unreadable `policy` is a loud tool
+error, never a clean verdict). `npx -y candor-ts-watch <dir>` keeps the report fresh as you edit (and
+reports the edit-delta); `candor-lsp` serves the same report as CodeLens/hover/diagnostics in any LSP
+editor, plus two code actions (plain LSP — helix/neovim/VS Code/JetBrains-via-LSP4IJ all get them
+without client code): the pre-edit whatif (`candor: what if <fn> performed <E>?` → the `candor.whatif`
+command) and, when the cursor sits in a function that actually violates the policy, the boundary FIX
+(`candor fix: hoist <E> out of <fn>` → the `candor.fix` command: where the effect belongs + the hoist
+refactor, as a showMessage and a transient diagnostic, cleared on the file's next open/save).
 CAVEAT — the MCP/LSP gate verdicts are computed FROM THE REPORT: the engine's own `--policy` /
 `--gate-json` run additionally fails an allow rule whose literal surface is incomplete (a masked
 endpoint — internal state, not a report field), so treat a report-side green as advisory and the

package/lsp.mjs

@@ -219,6 +219,7 @@ function showMessage(type, message) { send({ jsonrpc: "2.0", method: "window/sho
 // BOUNDARY effect (Q.CONTAINED — ambient effects gate nothing) the fn does not already carry. The action
 // carries a plain `command` (no client-side resolve, no edit) so it works in any LSP client verbatim.
 const WHATIF_COMMAND = "candor.whatif";
+const FIX_COMMAND = "candor.fix";
 function codeActions(docPath, uri, range) {
   const at = enclosingEntry(docPath, range?.start?.line ?? 0);
   if (!at) return [];                                  // a fn the report doesn't know → no actions, never an error
@@ -235,6 +236,30 @@ function codeActions(docPath, uri, range) {
       },
     });
   }
+  // The REMEDIAL companion (integrations/FIX-SPEC.md): for each BOUNDARY effect the fn ALREADY performs that
+  // the active policy FORBIDS here, offer the FIX — where the effect belongs + the hoist. Only real crossings
+  // are offered (Q.fix returns `crossing:false` otherwise), so this is empty unless the cursor sits in a
+  // function that actually violates the boundary. Same policy source as the diagnostics + the whatif action.
+  const policyText = activePolicy();
+  if (policyText !== null && hasReport(reportPrefix)) {
+    const pol = parsePolicy(policyText);
+    const cg = Q.loadCallgraph(reportPrefix);
+    const fns = Q.loadReport(reportPrefix);
+    for (const eff of Q.CONTAINED) {
+      if (!have.has(eff)) continue;
+      const r = Q.fix(cg, fns, at.entry.fn, eff, pol, scopeMatches);
+      if (r && r.crossing) {
+        out.push({
+          title: `candor fix: hoist ${eff} out of ${at.entry.fn}`,
+          command: {
+            title: `candor fix: hoist ${eff} out of ${at.entry.fn}`,
+            command: FIX_COMMAND,
+            arguments: [{ fn: at.entry.fn, effect: eff, uri, line: at.line }],
+          },
+        });
+      }
+    }
+  }
   return out;
 }
 
@@ -290,6 +315,56 @@ function runWhatif(a) {
   return r;   // the raw whatif result rides back as the executeCommand result (a thick client can render it)
 }
 
+// The candor.fix command: the SAME query-core `fix` the CLI (`query.mjs fix`) and MCP (`candor_fix`) run —
+// the boundary remedy (where the effect belongs + the hoist refactor), against the live policy (same source
+// as the diagnostics). Re-read per call (the freshness contract). Malformed args → logMessage + null.
+function runFix(a) {
+  if (!a || typeof a !== "object" || typeof a.fn !== "string" || typeof a.effect !== "string") {
+    logMessage(`candor-lsp: ${FIX_COMMAND} called with malformed arguments (expected [{ fn, effect, uri?, line? }]) — ignored`);
+    return null;
+  }
+  if (!hasReport(reportPrefix)) {
+    showMessage(2, "candor: no report found — scan first (candor-ts <dir> --out .candor/report)");
+    return null;
+  }
+  const policyText = activePolicy();
+  if (policyText === null) {
+    showMessage(2, "candor: no policy discovered — a fix is defined relative to a boundary; set CANDOR_POLICY or check one into .candor/config");
+    return null;
+  }
+  const r = Q.fix(Q.loadCallgraph(reportPrefix), Q.loadReport(reportPrefix), a.fn, a.effect,
+                  parsePolicy(policyText), scopeMatches);
+  if (r === null) {
+    showMessage(2, `candor: no function matching \`${a.fn}\` in the call graph — the report may be stale`);
+    return null;
+  }
+  if (!r.crossing) {
+    showMessage(3, `candor: \`${a.fn}\` — ${a.effect} isn't forbidden here; no boundary fix needed`);
+    return r;
+  }
+  const verdict = r.cleanHoist
+    ? `candor fix: hoist ${a.effect} to ${r.hoistTo.join(", ")} — the ${r.deniedSpan.length} ${r.layer || "(root)"} function(s) then stay pure (or relax the boundary: ${r.policyAlternative})`
+    : `candor fix: no clean hoist for ${a.effect} — introduce a port, or relax the boundary: ${r.policyAlternative}`;
+  showMessage(2, verdict);
+  if (typeof a.uri === "string" && Number.isInteger(a.line)) {   // the plan, pinned at the fn's line
+    const lines = [`candor fix — hoist ${a.effect} out of the ${r.layer || "(root)"} boundary`];
+    lines.push(`site: ${r.site.join(", ") || "(cross-module or Unknown source)"}`);
+    if (r.cleanHoist) {
+      lines.push(`hoist ${a.effect} to: ${r.hoistTo.join(", ")}`);
+      lines.push(`then pure (thread the value): ${r.deniedSpan.join(", ")}`);
+    } else {
+      lines.push("no clean hoist — introduce a port (inject the effect from an allowed layer), or relax the boundary");
+    }
+    lines.push(`policy alternative: ${r.policyAlternative}`);
+    transient.set(a.uri, [{
+      range: { start: { line: a.line, character: 0 }, end: { line: a.line, character: 200 } },
+      severity: 3, source: "candor", code: "fix", message: lines.join("\n"),
+    }]);
+    publishDiagnostics(a.uri);
+  }
+  return r;   // the raw remedy rides back as the executeCommand result (a thick client can render it)
+}
+
 // ---- the LSP method surface ---------------------------------------------------------------------------
 function handle(msg) {
   const { id, method, params } = msg;
@@ -307,7 +382,7 @@ function handle(msg) {
         codeLensProvider: { resolveProvider: false },
         hoverProvider: true,
         codeActionProvider: { resolveProvider: false },                // actions carry their command inline
-        executeCommandProvider: { commands: [WHATIF_COMMAND] },
+        executeCommandProvider: { commands: [WHATIF_COMMAND, FIX_COMMAND] },
       },
       serverInfo: { name: "candor-lsp", version: VERSION },
     });
@@ -334,12 +409,14 @@ function handle(msg) {
     catch { return result(id, []); }   // unknown fn / non-file URI / unreadable report → no actions, never an error
   }
   if (method === "workspace/executeCommand") {
-    if (params?.command !== WHATIF_COMMAND) {
-      logMessage(`candor-lsp: unknown command \`${params?.command}\` — this server provides only ${WHATIF_COMMAND}`);
+    const handlers = { [WHATIF_COMMAND]: runWhatif, [FIX_COMMAND]: runFix };
+    const run = handlers[params?.command];
+    if (!run) {
+      logMessage(`candor-lsp: unknown command \`${params?.command}\` — this server provides ${WHATIF_COMMAND} and ${FIX_COMMAND}`);
       return result(id, null);
     }
-    try { return result(id, runWhatif(params?.arguments?.[0])); }
-    catch (e) { logMessage(`candor-lsp: ${WHATIF_COMMAND} failed: ${e.message}`); return result(id, null); }
+    try { return result(id, run(params?.arguments?.[0])); }
+    catch (e) { logMessage(`candor-lsp: ${params?.command} failed: ${e.message}`); return result(id, null); }
   }
   if (method === "shutdown") return result(id, null);
   if (method === "exit") process.exit(0);

package/mcp.mjs

@@ -178,6 +178,24 @@ const TOOLS = {
       return r;
     },
   },
+  candor_fix: {
+    description: "THE BOUNDARY FIX: when `fn` performs `effect` in a layer the policy forbids (a violation candor_whatif/candor_gate reports), compute the architectural REMEDY — not just 'the domain can't do Net', but WHERE the effect belongs and the refactor to put it there: the direct call site to hoist, the forbidden-layer functions that become pure and thread the value as a parameter, and the nearest allowed-layer caller to perform the effect ({ crossing, site, deniedSpan, hoistTo, policyAlternative }). The remedial inverse of candor_whatif. Call this INSTEAD OF guessing a fix (adding `allow` to the domain, moving the I/O one call up, threading a handle the wrong way). Advisory: it names the structure, you write the code; the gate re-scan verifies. Uses `policy` if given, else the repo's checked-in .candor/config policy (spec §3.4).",
+    schema: { type: "object", properties: { fn: { type: "string" }, effect: { type: "string" }, policy: { type: "string", description: "path to a §6.2 policy file (optional; defaults to the repo's .candor/config `policy`)" }, ...reportArg }, required: ["fn", "effect"] },
+    run: (a, p) => {
+      // The fix is defined relative to a boundary — a policy is required. Given → confined fail-closed read;
+      // else the repo's checked-in policy (same resolution as candor_gate), so it works zero-config.
+      let text;
+      if (a.policy) text = confinedPolicyRead(a.policy, p);
+      else {
+        const cfg = configPolicy(p);
+        if (!cfg) throw new Error("no policy: pass `policy`, or check one into the repo's .candor/config (spec §3.4) — the fix is defined relative to the boundary it crosses");
+        text = confinedPolicyRead(cfg.policyPath, p, cfg.repoRoot);
+      }
+      const r = Q.fix(Q.loadCallgraph(p), Q.loadReport(p), a.fn, a.effect, parsePolicy(text), scopeMatches);
+      if (r === null) throw new Error(`no function matching \`${clip(a.fn)}\` in the call graph`);
+      return r;
+    },
+  },
   candor_gate: {
     description: "The policy verdict over this report: { ok, violations:[{rule, fn, effects, detail}] } — 'would this repo pass its architecture gate?'. Uses `policy` if given, else the repo's checked-in .candor/config policy (spec §3.4). Computed from the report — the engine's own --gate-json run is the authoritative CI form: it additionally fails an allow rule whose literal surface is INCOMPLETE (a masked/invisible endpoint), which is not a report field, so a green here can still be red in CI.",
     schema: { type: "object", properties: { policy: { type: "string", description: "path to a §6.2 policy file (optional; defaults to the repo's .candor/config `policy`)" }, ...reportArg }, required: [] },

package/package.json

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

package/query-core.mjs

@@ -486,3 +486,103 @@ export function whatif(cg, target, eff, policyParsed, scopeMatches) {
   }
   return { of: targets, effect: eff, affected: [...affected].sort(), violations, ok: violations.length === 0 };
 }
+
+// deniedLayer: the deny/`pure` scope (the "layer") forbidding `eff` at `fn`, or null if allowed there.
+// Mirrors the gate's AS-EFF-006 predicate (candor-java/candor-query): a `deny` fires when it names the
+// effect; a `pure` rule (empty effects) forbids every real effect but not Unknown.
+function deniedLayer(fn, eff, policyParsed, scopeMatches) {
+  for (const r of policyParsed.deny) {
+    const denies = r.effects.length === 0 ? eff !== "Unknown" : r.effects.includes(eff);
+    if (denies && (!r.scope || scopeMatches(fn, r.scope))) return r.scope ?? "";
+  }
+  return null;
+}
+
+// The site-anchored cut (integrations/FIX-SPEC.md), shared by fix + fixGate — the byte-for-byte port of
+// candor-query / candor-java's computeRemedy. Forward-BFS to the direct site(s), then climb UP through the
+// denied layer so the pure span is the same whichever inheriting function triggered it (root-independent);
+// the allowed-layer callers where the climb stops are the hoist frontier.
+function computeRemedy(start, eff, layer, cg, rev, byName, policyParsed, scopeMatches) {
+  const sites = new Set();
+  const fseen = new Set([start]);
+  const fq = [start];
+  while (fq.length) {
+    const cur = fq.shift();
+    const fe = byName.get(cur);
+    if (fe && (fe.direct ?? []).includes(eff)) sites.add(cur);
+    for (const c of cg[cur] ?? []) {
+      const ce = byName.get(c);
+      if (ce && (ce.inferred ?? []).includes(eff) && !fseen.has(c)) { fseen.add(c); fq.push(c); }
+    }
+  }
+  const anchors = sites.size ? [...sites] : [start];
+  const deniedSpan = new Set();
+  const hoistTo = new Set();
+  const up = [];
+  for (const a of anchors) {
+    if (deniedLayer(a, eff, policyParsed, scopeMatches) !== null) deniedSpan.add(a);
+    up.push(a);
+  }
+  while (up.length) {
+    const cur = up.shift();
+    for (const caller of rev.get(cur) ?? []) {
+      const ce = byName.get(caller);
+      if (ce && !(ce.inferred ?? []).includes(eff)) continue; // doesn't route the effect
+      if (deniedLayer(caller, eff, policyParsed, scopeMatches) !== null) {
+        if (!deniedSpan.has(caller)) { deniedSpan.add(caller); up.push(caller); }
+      } else {
+        hoistTo.add(caller);
+      }
+    }
+  }
+  return {
+    fn: start, effect: eff, layer,
+    cleanHoist: hoistTo.size > 0,
+    site: [...sites].sort(),
+    deniedSpan: [...deniedSpan].sort(),
+    hoistTo: [...hoistTo].sort(),
+    policyAlternative: layer ? `allow ${eff} ${layer}` : `allow ${eff}`,
+  };
+}
+
+// fix: the boundary remedy for ONE function (the remedial inverse of whatif). Returns null if the function
+// isn't in the graph; `{ crossing:false, reason }` if it performs the effect but no policy forbids it there
+// (or it doesn't perform it) — a no-op the caller reports plainly; else the full remedy (`crossing:true`).
+export function fix(cg, fns, target, eff, policyParsed, scopeMatches) {
+  const names = new Set(Object.keys(cg));
+  for (const e of fns) names.add(e.fn);
+  const m = matches([...names], target);
+  if (m.length === 0) return null;
+  const byName = indexFns(fns);
+  // prefer a match that actually performs the effect, so a bare leaf resolves to the violating function
+  const start = m.find((n) => (byName.get(n)?.inferred ?? []).includes(eff)) ?? m[0];
+  const se = byName.get(start);
+  if (!se || !(se.inferred ?? []).includes(eff))
+    return { fn: start, effect: eff, crossing: false, reason: "does-not-perform" };
+  const layer = deniedLayer(start, eff, policyParsed, scopeMatches);
+  if (layer === null)
+    return { fn: start, effect: eff, crossing: false, reason: "not-forbidden" };
+  const rev = reverseGraph(cg);
+  return { crossing: true, ...computeRemedy(start, eff, layer, cg, rev, byName, policyParsed, scopeMatches) };
+}
+
+// fixGate: a remedy for EVERY deny/`pure` (AS-EFF-006) crossing in the report, collapsing the inheritors of
+// one root cause to a single plan (keyed by effect|layer|site|hoist). Returns { ok, remedies } — the shape
+// the edit-time loop folds into its block message.
+export function fixGate(cg, fns, policyParsed, scopeMatches) {
+  const byName = indexFns(fns);
+  const rev = reverseGraph(cg);
+  const plans = new Map();
+  for (const e of fns) {
+    for (const eff of (e.inferred ?? [])) {
+      const layer = deniedLayer(e.fn, eff, policyParsed, scopeMatches);
+      if (layer !== null) {
+        const p = computeRemedy(e.fn, eff, layer, cg, rev, byName, policyParsed, scopeMatches);
+        const key = `${p.effect}|${p.layer}|${p.site}|${p.hoistTo}`;
+        if (!plans.has(key)) plans.set(key, p);
+      }
+    }
+  }
+  const remedies = [...plans.values()];
+  return { ok: remedies.length === 0, remedies };
+}

package/query.mjs

@@ -31,6 +31,7 @@ import { impact as coreImpact, path as corePath, gains as coreGains,
          callers as coreCallers, callersFrontier, loadHierarchy,
          containment as coreContainment, diff as coreDiff,
          where as coreWhere, map as coreMap, whatif as coreWhatif,
+         fix as coreFix, fixGate as coreFixGate,
          loadReport, loadCallgraph, reportVersion } from "./query-core.mjs";
 const emit = (v) => console.log(JSON.stringify(v, null, 1));
 
@@ -57,6 +58,8 @@ const SUBCOMMANDS = [
   ["gains", "<cur-prefix> <base-prefix>", "the supply-chain alarm: what the surface gained between two reports"],
   ["path", "<prefix> <fn> <Effect>", "a call path from a function to where an effect enters"],
   ["whatif", "<prefix> <fn> <Effect> [policy-file] [0|1]", "the impact of giving a function an effect, vs a policy (exit 1 on a violation)"],
+  ["fix", "<prefix> <fn> <Effect> <policy-file>", "the boundary fix: where the effect belongs + the hoist refactor"],
+  ["fix-gate", "<prefix> <policy-file>", "a fix for EVERY boundary crossing — the loop's block-message remedy"],
   ["agents", "", "print the agent contract for this build (AGENTS.md)"],
 ];
 
@@ -250,6 +253,31 @@ switch (cmd) {
     process.exit(r.violations.length ? 1 : 0);
     break; // unreachable (process.exit), but eslint can't prove it — defends against fallthrough
   }
+  case "fix": {
+    // THE BOUNDARY FIX (integrations/FIX-SPEC.md): where a forbidden effect belongs + the hoist refactor.
+    // The remedial inverse of whatif. A policy is REQUIRED and must be readable (the fix is defined relative
+    // to the boundary the edit crossed) — a typo'd path fails LOUD, never a silently-empty "no crossing".
+    const [prefix, target, eff, policyFile] = args;
+    if (!target || !eff) { console.error("usage: candor-ts-query fix <prefix> <fn> <Effect> <policy-file>"); process.exit(2); }
+    if (!policyFile) { console.error("candor: fix requires a policy file — the fix is the refactor that restores the boundary the edit crossed"); process.exit(2); }
+    let ptext;
+    try { ptext = fs.readFileSync(policyFile, "utf8"); }
+    catch { console.error(`candor: policy ${policyFile} could not be read — no fix computed`); process.exit(2); }
+    const r = coreFix(loadCallgraph(prefix), loadReport(prefix), target, eff, parsePolicy(ptext), scopeMatches);
+    if (r === null) { console.error(`candor: no function matching \`${target}\` in the call graph`); process.exit(2); }
+    emit(r);
+    break;
+  }
+  case "fix-gate": {
+    // A remedy for EVERY deny/pure crossing — the shape the edit-time loop folds into its block message.
+    const [prefix, policyFile] = args;
+    if (!policyFile) { console.error("candor: fix-gate requires a policy file"); process.exit(2); }
+    let ptext;
+    try { ptext = fs.readFileSync(policyFile, "utf8"); }
+    catch { console.error(`candor: policy ${policyFile} could not be read — no fix computed`); process.exit(2); }
+    emit(coreFixGate(loadCallgraph(prefix), loadReport(prefix), parsePolicy(ptext), scopeMatches));
+    break;
+  }
   default:
     // no command (cmd === undefined) or an unknown one: the FULL usage, not the stale 6-item list.
     if (cmd !== undefined) console.error(`candor-ts-query: unknown command '${cmd}'`);