forgedock 1.27.0 → 1.28.0

package/bin/lean/refactor.test.mjs

@@ -0,0 +1,359 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// refactor:split lane step (forge#4211): bin/lean/refactor.mjs against real fixture repos and the real scripts.
+// The libcst cases resolve an interpreter like scripts/symbol-move.test.sh ($SYMBOL_MOVE_PYTHON, python3 with libcst,
+// `uv run --no-project --with libcst python`) and skip without one; SYMBOL_MOVE_REQUIRE_LIBCST=1 makes that a failure.
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { execFileSync, spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { tmpDir } from "../tests/_tmp.mjs";
+import { OUTCOME_CODES } from "../engine/outcome-codes.mjs";
+import { groupingPrompt, GROUPING_SYSTEM } from "./prompts.mjs";
+import { noToolFlags } from "./effects.mjs";
+import {
+  runSplitStep, defaultRun, compactIndex, slicePlan, parseSplitTarget, parseTestCmd, parseSplitPlan, parseGroupingReply,
+  renderChainIssue, renderSplitPrBody, SYMBOL_INDEX, SYMBOL_MOVE, REFACTOR_VERIFY, SPLIT_LABEL, SYMBOL_INDEX_MJS, SYMBOL_MOVE_TS,
+} from "./refactor.mjs";
+
+const GEN = fileURLToPath(new URL("../../scripts/fixtures/symbol-move/gen_big.py", import.meta.url));
+const TEST_CMD = "python3 -m unittest discover -s tests -t .";
+const ENV = { ...process.env, PYTHONDONTWRITEBYTECODE: "1" };
+
+function libcstPython() {
+  const ok = (argv) => spawnSync(argv[0], [...argv.slice(1), "-c", "import libcst"], { stdio: "ignore", env: ENV }).status === 0;
+  if (process.env.SYMBOL_MOVE_PYTHON) return process.env.SYMBOL_MOVE_PYTHON.trim().split(/\s+/);
+  if (ok(["python3"])) return ["python3"];
+  const uv = ["uv", "run", "--no-project", "--with", "libcst", "python"];
+  return ok(uv) ? uv : null;
+}
+const PY = libcstPython();
+const SKIP = PY ? false : "no python with libcst (set SYMBOL_MOVE_PYTHON)";
+if (!PY && process.env.SYMBOL_MOVE_REQUIRE_LIBCST === "1") throw new Error("libcst required (SYMBOL_MOVE_REQUIRE_LIBCST=1) but not available");
+
+const git = (dir, ...a) => execFileSync("git", ["-C", dir, "-c", "user.name=t", "-c", "user.email=t@example.invalid", ...a], { encoding: "utf8", env: ENV }).trim();
+/** A git repo holding the ~3k-line fixture module pkg/big.py and its unittest suite, committed and tagged `base`. */
+function fixtureRepo() {
+  const d = join(tmpDir("split-"), "repo");
+  mkdirSync(d, { recursive: true });
+  git(d, "init", "-q");
+  writeFileSync(join(d, ".gitignore"), "__pycache__/\n.forge-lean/\n");
+  execFileSync("python3", [GEN, d], { env: ENV });
+  git(d, "add", "-A"); git(d, "commit", "-qm", "base"); git(d, "tag", "base");
+  return d;
+}
+const gitFx = (d) => async (args) => git(d, ...args);
+const clean = (d) => git(d, "status", "--porcelain");
+const seq = (n, f) => Array.from({ length: n }, (_, i) => f(String(i).padStart(2, "0")));
+const FULL = {
+  consts: [...seq(90, (i) => `LIMIT_${i}`), "_SEPARATOR"],
+  helpers: [...seq(90, (i) => [`_scale_${i}`, `compute_${i}`]).flat(), "join_parts"],
+  aio: seq(30, (i) => `fetch_${i}`),
+  models: seq(30, (i) => `Item_${i}`),
+};
+const BODY = "`pkg/big.py` has 3000 lines.\n\n<!-- FORGE:MAINT:refactor:split:pkg/big.py -->\n";
+
+/** Records every grouping call; replies with `plan`. */
+function grouper(plan) {
+  const calls = [];
+  return { calls, fn: async (prompt, opts) => { calls.push({ prompt, opts }); return `Here is the plan:\n${JSON.stringify(plan)}`; } };
+}
+/** defaultRun, except that calls whose argv contains `script` are answered by `fake(args, cwd)`. */
+const intercept = (script, fake) => async (cmd, args, o) => (args.includes(script) ? fake(args, o.cwd) : defaultRun(cmd, args, o));
+
+describe("refactor:split parsers and planning (forge#4211)", () => {
+  it("target, test command and chain plan come from the issue body", () => {
+    assert.equal(parseSplitTarget(BODY), "pkg/big.py");
+    assert.equal(parseSplitTarget("**Target**: `src/a.py`"), "src/a.py");
+    assert.equal(parseSplitTarget("nothing"), null);
+    assert.equal(parseTestCmd("**Test command**: `pytest -q tests`", ["npm test"]), "pytest -q tests");
+    assert.equal(parseTestCmd("x", ["ruff check .", "pytest"]), "ruff check . && pytest");
+    assert.equal(parseTestCmd("x", []), null);
+    const c = renderChainIssue({ parent: 9, target: "pkg/big.py", packageName: "big_parts", rest: { models: ["Item_00"] }, testCmd: TEST_CMD });
+    assert.deepEqual(c.labels, ["maintenance", SPLIT_LABEL]);
+    assert.match(c.body, /<!-- FORGE:MAINT:refactor:split:pkg\/big.py -->/);
+    assert.deepEqual(parseSplitPlan(c.body), { target: "pkg/big.py", package: "big_parts", plan: { models: ["Item_00"] } });
+    assert.equal(parseSplitTarget(c.body), "pkg/big.py");
+    assert.equal(parseTestCmd(c.body, []), TEST_CMD);
+    assert.equal(parseSplitPlan("<!-- FORGE:SPLIT-PLAN -->\n```json\n{\"package\":\"bad name\",\"plan\":{}}\n```"), null);
+  });
+
+  it("the grouping reply must be one {module:[symbols]} object over known symbols, each once", () => {
+    const names = ["a", "b", "c"];
+    assert.deepEqual(parseGroupingReply('ok ```json\n{"m1":["a"],"m2":["b","c"]}\n```', names), { m1: ["a"], m2: ["b", "c"] });
+    assert.equal(parseGroupingReply('{"m1":["a","a"]}', names), null);
+    assert.equal(parseGroupingReply('{"m1":["zzz"]}', names), null);
+    assert.equal(parseGroupingReply('{"a":["b"]}', names), null, "module name colliding with a symbol");
+    assert.equal(parseGroupingReply('{"bad-name":["a"]}', names), null);
+    assert.equal(parseGroupingReply("no json", names), null);
+  });
+
+  it("R4: slicePlan keeps whole modules under maxLines, dependencies first, and returns the rest", () => {
+    const index = { symbols: [{ name: "A", kind: "const", lines: 10, public: true }, { name: "f", kind: "function", lines: 500, public: true }, { name: "g", kind: "function", lines: 600, public: true }],
+      edges: [{ from: "f", to: "A" }, { from: "g", to: "f" }] };
+    const plan = { late: ["g"], mid: ["f"], base: ["A"] };
+    assert.deepEqual(slicePlan(plan, index, 600), { now: { base: ["A"], mid: ["f"] }, rest: { late: ["g"] }, lines: 510 });
+    assert.deepEqual(slicePlan(plan, index, 5).now, { base: ["A"] }, "the first module is always taken");
+    assert.equal(slicePlan(plan, index, 5000).rest, null);
+  });
+
+  it("R2/R5: the grouping input is the compact index only; its size does not follow the file size", () => {
+    const d = tmpDir("split-size-");
+    const mk = (n) => ["X = 1", "", "def f():", ...Array.from({ length: n }, (_, i) => `    v${i} = X + ${i}  # padding line ${"x".repeat(40)}`), "    return X", "", "class K:", "    def m(self):", "        return f()", ""].join("\n");
+    writeFileSync(join(d, "small.py"), mk(5)); writeFileSync(join(d, "big.py"), mk(500));
+    const idx = (f) => JSON.parse(execFileSync("python3", [SYMBOL_INDEX, join(d, f)], { encoding: "utf8" }));
+    const [a, b] = [compactIndex(idx("small.py")), compactIndex(idx("big.py"))];
+    assert.deepEqual(a.symbols.map((s) => s.name), ["X", "f", "K"], "top-level symbols only (no K.m)");
+    assert.deepEqual(a.edges, ["K->f", "f->X"]);
+    for (const s of a.symbols) assert.deepEqual(Object.keys(s).sort(), ["kind", "lines", "name", "public"]);
+    const [pa, pb] = [groupingPrompt(a), groupingPrompt(b)];
+    assert.ok(readFileSync(join(d, "big.py"), "utf8").length > 50 * readFileSync(join(d, "small.py"), "utf8").length);
+    assert.ok(Math.abs(pb.length - pa.length) <= 2 * a.symbols.length, `prompt grew ${pa.length} -> ${pb.length}`);
+    assert.doesNotMatch(pb, /padding line/);
+    assert.match(GROUPING_SYSTEM, /no tools/);
+    assert.deepEqual(noToolFlags({ strictMcp: true }), ["--tools", ""]);
+    assert.ok(noToolFlags({}).includes("Read") && noToolFlags({}).includes("Grep") && noToolFlags({}).includes("Glob"));
+  });
+});
+
+describe("refactor:split step on a fixture repo (forge#4211)", () => {
+  it("R2: the ~3k-line module becomes a package plus shim with identical test results; the LLM sees the index only", { skip: SKIP }, async () => {
+    const d = fixtureRepo();
+    const src = readFileSync(join(d, "pkg/big.py"), "utf8");
+    assert.ok(src.split("\n").length >= 2500);
+    const g = grouper(FULL);
+    const r = await runSplitStep({ wt: d, base: "base", issue: 42, issueBody: BODY, precheckCommands: [TEST_CMD], runTmp: tmpDir("split-run-"), python: PY, git: gitFx(d), callGrouper: g.fn });
+    assert.equal(r.ok, true, r.reason);
+    assert.equal(r.package, "pkg.big_parts");
+    assert.deepEqual(Object.keys(r.modules).sort(), ["aio", "consts", "helpers", "models"]);
+    assert.equal(r.rest, null);
+    assert.equal(r.grouped, true);
+    assert.deepEqual(r.verify, { failures: [], ok: true });
+    for (const f of ["__init__", "consts", "helpers", "aio", "models"]) assert.ok(existsSync(join(d, `pkg/big_parts/${f}.py`)), f);
+    assert.equal(clean(d), "", "the move is committed");
+    assert.match(git(d, "log", "-1", "--format=%s"), /^refactor\(split\): move 4 module\(s\) of pkg\/big.py into pkg.big_parts \(#42\)$/);
+    const after = spawnSync("bash", ["-c", TEST_CMD], { cwd: d, encoding: "utf8", env: ENV });
+    assert.equal(after.status, 0);
+    assert.match(after.stderr, /OK \(skipped=1\)/);
+    // the grouping call: exactly one, an empty cwd, and no line of the module body in its prompt
+    assert.equal(g.calls.length, 1);
+    const { prompt, opts } = g.calls[0];
+    assert.deepEqual(readdirSync(opts.cwd), [], "grouping cwd is an empty scratch dir");
+    for (const line of src.split("\n").map((l) => l.trim()).filter((l) => l.length > 20)) assert.ok(!prompt.includes(line), `prompt leaks a body line: ${line}`);
+    assert.doesNotMatch(prompt, /"start"|"end"|import functools/);
+    assert.match(renderSplitPrBody({ issue: 42, ...r }), /Closes #42$/);
+  });
+
+  it("R4: a large split is a chain; each PR moves one package slice, the next applies the carried plan with --extend and no LLM call", { skip: SKIP }, async () => {
+    const d = fixtureRepo();
+    const g = grouper(FULL);
+    const r1 = await runSplitStep({ wt: d, base: "base", issue: 1, issueBody: BODY, precheckCommands: [TEST_CMD], runTmp: tmpDir("split-run-"), python: PY, git: gitFx(d), callGrouper: g.fn, maxLines: 1200 });
+    assert.equal(r1.ok, true, r1.reason);
+    assert.ok(r1.rest, "a remainder is carried");
+    assert.ok(r1.lines <= 1200 || Object.keys(r1.modules).length === 1);
+    git(d, "tag", "pr1");
+    const chain = renderChainIssue({ parent: 1, target: r1.target, packageName: r1.packageName, rest: r1.rest, testCmd: TEST_CMD });
+    const g2 = grouper({});
+    const r2 = await runSplitStep({ wt: d, base: "pr1", issue: 2, issueBody: chain.body, precheckCommands: [], runTmp: tmpDir("split-run-"), python: PY, git: gitFx(d), callGrouper: g2.fn, maxLines: 100000 });
+    assert.equal(r2.ok, true, r2.reason);
+    assert.equal(g2.calls.length, 0, "a chained step makes no grouping call");
+    assert.equal(r2.package, r1.package, "the same target package");
+    assert.deepEqual(Object.keys(r2.modules).sort(), Object.keys(r1.rest).sort());
+    assert.equal(r2.rest, null);
+    assert.equal(g.calls.length, 1, "one grouping call for the whole split");
+    assert.equal(spawnSync("bash", ["-c", TEST_CMD], { cwd: d, env: ENV }).status, 0);
+  });
+
+  for (const [kind, mutate] of [
+    ["logic-diff", (d) => { const p = join(d, "pkg/big.py"); writeFileSync(p, readFileSync(p, "utf8").replace('VERSION = "1.0"', 'VERSION = "2.0"')); }],
+    ["missing-symbol", (d) => { const p = join(d, "pkg/big.py"); const s = readFileSync(p, "utf8"); const m = /\ndef describe\(\)[^\n]*\n(?: {4}[^\n]*\n)+/.exec(s); writeFileSync(p, s.replace(m[0], "\n")); mkdirSync(join(d, "pkg/big_parts")); writeFileSync(join(d, "pkg/big_parts/__init__.py"), ""); writeFileSync(join(d, "pkg/big_parts/misc.py"), m[0].slice(1)); }],
+    ["new-cycle", (d) => { writeFileSync(join(d, "pkg/cyc_a.py"), "import pkg.cyc_b\n"); writeFileSync(join(d, "pkg/cyc_b.py"), "import pkg.cyc_a\n"); }],
+  ]) {
+    it(`R3: verification fails the lane on a ${kind} and resets the worktree`, async () => {
+      const d = fixtureRepo();
+      const run = async (cmd, args, o) => {
+        if (args.includes("-c") && args.includes("import libcst")) return { code: 0, stdout: "", stderr: "" };
+        if (args.includes(SYMBOL_MOVE)) { mutate(d); return { code: 0, stdout: JSON.stringify({ status: "ok", package: "pkg.big_parts", modules: { misc: ["describe"] } }), stderr: "" }; }
+        return defaultRun(cmd, args, o);
+      };
+      const r = await runSplitStep({ wt: d, base: "base", issue: 3, issueBody: BODY, precheckCommands: [TEST_CMD], runTmp: tmpDir("split-run-"), git: gitFx(d), run, callGrouper: grouper(FULL).fn });
+      assert.equal(r.ok, false);
+      assert.equal(r.code, OUTCOME_CODES.SPLIT_VERIFY_FAILED);
+      assert.match(r.reason, new RegExp(`- ${kind}`));
+      assert.equal(clean(d), "", "no partial edit survives");
+      assert.equal(git(d, "rev-parse", "HEAD"), git(d, "rev-parse", "base"));
+    });
+  }
+
+  it("R6: a target with no mover (Go) is refused as needs-human material before anything runs", async () => {
+    const d = fixtureRepo();
+    mkdirSync(join(d, "src")); writeFileSync(join(d, "src/big.go"), "package big\n");
+    git(d, "add", "-A"); git(d, "commit", "-qm", "go");
+    const calls = [];
+    const r = await runSplitStep({ wt: d, base: "base", issueBody: "<!-- FORGE:MAINT:refactor:split:src/big.go -->", precheckCommands: [TEST_CMD], git: gitFx(d),
+      run: async (...a) => { calls.push(a); return defaultRun(...a); }, callGrouper: grouper(FULL).fn });
+    assert.deepEqual(r, { ok: false, code: OUTCOME_CODES.SPLIT_UNSUPPORTED, reason: "no codemod tool for go: `src/big.go` (the refactor:split movers support Python and TypeScript)" });
+    assert.equal(calls.length, 0);
+    assert.equal(clean(d), "");
+  });
+
+  it("R6: no libcst (probe or mover refusal) is split.unsupported with the reason and no partial edit", async () => {
+    const d = fixtureRepo();
+    const g = grouper(FULL);
+    const r = await runSplitStep({ wt: d, base: "base", issueBody: BODY, precheckCommands: [TEST_CMD], git: gitFx(d), python: ["python3", "-I", "-S"], callGrouper: g.fn });
+    assert.equal(r.code, OUTCOME_CODES.SPLIT_UNSUPPORTED);
+    assert.match(r.reason, /libcst is not importable/);
+    assert.equal(g.calls.length, 0, "refused before the grouping call");
+    // the mover itself refusing for want of libcst (after baseline and grouping) also leaves nothing behind
+    const run = async (cmd, args, o) => {
+      if (args.includes("-c") && args.includes("import libcst")) return { code: 0, stdout: "", stderr: "" };
+      if (args.includes(SYMBOL_MOVE)) return defaultRun("python3", ["-I", "-S", ...args.slice(args.indexOf(SYMBOL_MOVE))], o);
+      return defaultRun(cmd, args, o);
+    };
+    const r2 = await runSplitStep({ wt: d, base: "base", issueBody: BODY, precheckCommands: [TEST_CMD], runTmp: tmpDir("split-run-"), git: gitFx(d), run, callGrouper: grouper(FULL).fn });
+    assert.equal(r2.code, OUTCOME_CODES.SPLIT_UNSUPPORTED);
+    assert.match(r2.reason, /no codemod tool: libcst/);
+    assert.equal(clean(d), "");
+    assert.equal(git(d, "rev-parse", "HEAD"), git(d, "rev-parse", "base"));
+  });
+
+  it("R4/R5: a chained plan passes --package and --extend to the mover and makes no grouping call", async () => {
+    const d = fixtureRepo();
+    const body = renderChainIssue({ parent: 1, target: "pkg/big.py", packageName: "big_parts", rest: { models: FULL.models }, testCmd: TEST_CMD }).body;
+    let moverArgs = null;
+    const mover = intercept(SYMBOL_MOVE, (args) => { moverArgs = args; return { code: 3, stdout: JSON.stringify({ status: "refused", reason: "moved symbol Item_00 needs 'compute_00'" }), stderr: "" }; });
+    const run = async (cmd, args, o) => (args.includes("-c") && args.includes("import libcst") ? { code: 0, stdout: "", stderr: "" } : mover(cmd, args, o));
+    const g = grouper(FULL);
+    const r = await runSplitStep({ wt: d, base: "base", issueBody: body, precheckCommands: [], runTmp: tmpDir("split-run-"), git: gitFx(d), run, python: ["python3"], callGrouper: g.fn });
+    assert.equal(g.calls.length, 0);
+    assert.ok(moverArgs.includes("--extend"));
+    assert.equal(moverArgs[moverArgs.indexOf("--package") + 1], "big_parts");
+    assert.equal(r.code, OUTCOME_CODES.SPLIT_PLAN_INVALID, "a plan the mover refuses (not for libcst) is plan_invalid");
+    assert.match(r.reason, /symbol-move refused: moved symbol Item_00/);
+    assert.equal(clean(d), "");
+  });
+
+  it("an unparseable grouping reply is split.plan_invalid with no edit", async () => {
+    const d = fixtureRepo();
+    const run = async (cmd, args, o) => (args.includes("-c") && args.includes("import libcst") ? { code: 0, stdout: "", stderr: "" } : defaultRun(cmd, args, o));
+    const r = await runSplitStep({ wt: d, base: "base", issueBody: BODY, precheckCommands: [TEST_CMD], runTmp: tmpDir("split-run-"), git: gitFx(d), run, callGrouper: async () => "I cannot do that" });
+    assert.equal(r.code, OUTCOME_CODES.SPLIT_PLAN_INVALID);
+    assert.equal(clean(d), "");
+  });
+
+  it("the scripts the step calls exist", () => {
+    for (const p of [SYMBOL_INDEX, SYMBOL_MOVE, REFACTOR_VERIFY, SYMBOL_INDEX_MJS, SYMBOL_MOVE_TS]) assert.ok(existsSync(p), p);
+  });
+});
+
+// ---- forge#4212: TypeScript targets go through scripts/symbol-move.mjs (ts-morph) ----
+// The end-to-end case needs SYMBOL_MOVE_TS_NODE_MODULES=<node_modules holding ts-morph> and skips without it.
+const TS_GEN = fileURLToPath(new URL("../../scripts/fixtures/symbol-move-ts/gen_big.mjs", import.meta.url));
+const TS_TEST_CMD = "env -u NODE_TEST_CONTEXT node --test test/big.test.ts"; // not a child of this node:test run
+const TS_BODY = "`src/big.ts` is a hotspot.\n\n<!-- FORGE:MAINT:refactor:split:src/big.ts -->\n";
+const TSM = process.env.SYMBOL_MOVE_TS_NODE_MODULES && existsSync(join(process.env.SYMBOL_MOVE_TS_NODE_MODULES, "ts-morph")) ? process.env.SYMBOL_MOVE_TS_NODE_MODULES : null;
+const TS_PLAN = {
+  consts: seq(20, (i) => `LIMIT_${i}`),
+  helpers: seq(20, (i) => [`_scale_${i}`, `compute_${i}`]).flat(),
+  models: [...seq(20, (i) => `Item_${i}`), ...seq(20, (i) => `Store_${i}`)],
+  aio: seq(20, (i) => `fetch_${i}`),
+};
+/** A git repo holding the TS fixture src/big.ts and its node:test suite, committed and tagged `base`. */
+function tsFixtureRepo() {
+  const d = join(tmpDir("split-ts-"), "repo");
+  mkdirSync(d, { recursive: true });
+  git(d, "init", "-q");
+  writeFileSync(join(d, ".gitignore"), "node_modules/\n.forge-lean/\n");
+  execFileSync(process.execPath, [TS_GEN, d], { env: ENV });
+  git(d, "add", "-A"); git(d, "commit", "-qm", "base"); git(d, "tag", "base");
+  return d;
+}
+
+describe("refactor:split TypeScript targets (forge#4212)", () => {
+  it("R3: ts-morph unavailable is split.unsupported `no codemod tool for ts`, before the grouping call, with no partial edit", async () => {
+    const d = tsFixtureRepo();
+    const g = grouper(TS_PLAN);
+    const home = tmpDir("split-ts-home-");
+    const r = await runSplitStep({ wt: d, base: "base", issueBody: TS_BODY, precheckCommands: [TS_TEST_CMD], runTmp: tmpDir("split-run-"), git: gitFx(d),
+      env: { NODE_PATH: "", HOME: home }, callGrouper: g.fn });
+    assert.equal(r.ok, false);
+    assert.equal(r.code, OUTCOME_CODES.SPLIT_UNSUPPORTED);
+    assert.match(r.reason, /^no codemod tool for ts: ts-morph is not resolvable/);
+    assert.equal(g.calls.length, 0, "refused before the grouping call");
+    assert.equal(clean(d), "");
+    assert.equal(git(d, "rev-parse", "HEAD"), git(d, "rev-parse", "base"));
+    assert.equal(existsSync(join(d, "src/big_parts")), false);
+  });
+
+  it("R1: a .ts target dispatches to node symbol-index.mjs and symbol-move.mjs; a ts-morph refusal from the mover resets the worktree", async () => {
+    const d = tsFixtureRepo();
+    const calls = [];
+    const index = { symbols: [{ name: "LIMIT_00", kind: "const", lines: 1, public: true }, { name: "compute_00", kind: "function", lines: 4, public: true }], edges: [], imports: [], cycles: [] };
+    const run = async (cmd, args, o) => {
+      calls.push({ cmd, args });
+      if (args.includes(SYMBOL_MOVE_TS) && args.includes("--probe")) return { code: 0, stdout: JSON.stringify({ status: "ok", tool: "ts-morph" }), stderr: "" };
+      if (args.includes(SYMBOL_INDEX_MJS)) return { code: 0, stdout: JSON.stringify(index), stderr: "" };
+      if (args.includes(REFACTOR_VERIFY)) return { code: 0, stdout: "{}", stderr: "" };
+      if (args.includes(SYMBOL_MOVE_TS)) {
+        writeFileSync(join(o.cwd, "src/partial.ts"), "export {};\n"); // whatever a mover leaves behind is reset
+        return { code: 3, stdout: JSON.stringify({ status: "refused", reason: "no codemod tool for ts: ts-morph is not resolvable from src" }), stderr: "" };
+      }
+      return defaultRun(cmd, args, o);
+    };
+    const r = await runSplitStep({ wt: d, base: "base", issueBody: TS_BODY, precheckCommands: [TS_TEST_CMD], runTmp: tmpDir("split-run-"), git: gitFx(d), run,
+      callGrouper: grouper({ consts: ["LIMIT_00"], helpers: ["compute_00"] }).fn });
+    assert.equal(r.code, OUTCOME_CODES.SPLIT_UNSUPPORTED);
+    assert.match(r.reason, /symbol-move refused: no codemod tool for ts/);
+    const idx = calls.find((c) => c.args.includes(SYMBOL_INDEX_MJS)), mv = calls.find((c) => c.args.includes(SYMBOL_MOVE_TS) && !c.args.includes("--probe"));
+    assert.equal(idx.cmd, process.execPath);
+    assert.deepEqual(idx.args, [SYMBOL_INDEX_MJS, "src/big.ts"]);
+    assert.equal(mv.cmd, process.execPath);
+    assert.deepEqual(mv.args.slice(0, 4), [SYMBOL_MOVE_TS, "--src", "src/big.ts", "--plan"]);
+    assert.ok(!calls.some((c) => c.args.includes(SYMBOL_INDEX) || c.args.includes(SYMBOL_MOVE) || c.args.includes("import libcst")), "no Python tool for a .ts target");
+    assert.equal(clean(d), "");
+    assert.equal(git(d, "rev-parse", "HEAD"), git(d, "rev-parse", "base"));
+  });
+
+  it("a plan the TS mover refuses is split.plan_invalid", async () => {
+    const d = tsFixtureRepo();
+    const run = async (cmd, args, o) => {
+      if (args.includes(SYMBOL_MOVE_TS)) return args.includes("--probe") ? { code: 0, stdout: "{}", stderr: "" } : { code: 3, stdout: JSON.stringify({ status: "refused", reason: "plan creates an import cycle: a -> b -> a" }), stderr: "" };
+      if (args.includes(SYMBOL_INDEX_MJS)) return { code: 0, stdout: JSON.stringify({ symbols: [{ name: "ping", kind: "function", lines: 3, public: true }, { name: "pong", kind: "function", lines: 3, public: true }], edges: [] }), stderr: "" };
+      if (args.includes(REFACTOR_VERIFY)) return { code: 0, stdout: "{}", stderr: "" };
+      return defaultRun(cmd, args, o);
+    };
+    const r = await runSplitStep({ wt: d, base: "base", issueBody: TS_BODY, precheckCommands: [TS_TEST_CMD], runTmp: tmpDir("split-run-"), git: gitFx(d), run, callGrouper: grouper({ a: ["ping"], b: ["pong"] }).fn });
+    assert.equal(r.code, OUTCOME_CODES.SPLIT_PLAN_INVALID);
+    assert.match(r.reason, /import cycle/);
+    assert.equal(clean(d), "");
+  });
+
+  it("R2: the TS module becomes modules plus a re-export barrel, refactor-verify ok, one grouping call", { skip: TSM ? false : "set SYMBOL_MOVE_TS_NODE_MODULES to a node_modules holding ts-morph" }, async () => {
+    const d = tsFixtureRepo();
+    const g = grouper(TS_PLAN);
+    const r = await runSplitStep({ wt: d, base: "base", issue: 7, issueBody: TS_BODY, precheckCommands: [TS_TEST_CMD], runTmp: tmpDir("split-run-"), git: gitFx(d),
+      env: { NODE_PATH: TSM }, callGrouper: g.fn });
+    assert.equal(r.ok, true, r.reason);
+    assert.equal(r.package, "src/big_parts");
+    assert.equal(r.packageName, "big_parts");
+    assert.equal(r.tool, "ts-morph");
+    assert.deepEqual(Object.keys(r.modules).sort(), ["aio", "consts", "helpers", "models"]);
+    assert.deepEqual(r.verify, { failures: [], ok: true });
+    assert.equal(g.calls.length, 1);
+    for (const m of ["consts", "helpers", "models", "aio"]) assert.ok(existsSync(join(d, `src/big_parts/${m}.ts`)), m);
+    assert.match(readFileSync(join(d, "src/big.ts"), "utf8"), /^export \{ .*\} from "\.\/big_parts\/helpers\.ts";$/m);
+    assert.equal(clean(d), "", "the move is committed");
+    assert.match(git(d, "log", "-1", "--format=%s"), /^refactor\(split\): move 4 module\(s\) of src\/big.ts into src\/big_parts \(#7\)$/);
+    const body = renderSplitPrBody({ issue: 7, ...r });
+    assert.match(body, /scripts\/symbol-move\.mjs` \(ts-morph\)/);
+    // a chained remainder carries the bare package name, which the TS mover takes as --package
+    assert.equal(parseSplitPlan(renderChainIssue({ parent: 7, target: r.target, packageName: r.packageName, rest: { more: ["x"] } }).body).package, "big_parts");
+  });
+
+  it("renderSplitPrBody names the mover by the target's language when the result carries no tool (a rerun)", () => {
+    assert.match(renderSplitPrBody({ issue: 1, target: "src/big.ts", package: null, modules: {}, verify: { ok: true }, rest: null, grouped: false }), /symbol-move\.mjs` \(ts-morph\)/);
+    assert.match(renderSplitPrBody({ issue: 1, target: "pkg/big.py", package: null, modules: {}, verify: { ok: true }, rest: null, grouped: false }), /symbol-move\.py` \(libcst\)/);
+  });
+});

package/bin/lean/render.mjs

@@ -95,7 +95,9 @@ export function renderContract(c, hash, { compact = false } = {}) {
   const disp = (r) => `${r.disposition}${r.tracked ? ` → ${r.tracked}` : ["defer", "post-deploy"].includes(r.disposition) ? " (filed after review accepts it)" : ""}${r.why ? ` (${escl(r.why)})` : ""}`;
   const req = c.requirements.map((r) => `| ${esc(r.id)} | ${esc(r.quote)} | ${esc(disp(r))} |`).join("\n");
   const del = (c.deliverables ?? []).map((d) => `| ${esc(d.id)} | \`${esc(d.path)}\` | ${esc(d.change)} | ${esc((d.requirements ?? []).join(", "))} |`).join("\n");
-  return `## Builder Contract (frozen \`${hash}\`)\n\n### Requirements\n| Id | From the issue | Disposition |\n| --- | --- | --- |\n${req}\n\n### Deliverables\n${del ? `| Id | Path | Change | Requirements |\n| --- | --- | --- | --- |\n${del}` : "None."}\n\n### Preserve\n${(c.preserve ?? []).map((p) => `- ${escl(p.id)}: ${escl(p.what)}`).join("\n") || "None."}\n\n### Validate\n${(c.validate ?? []).map((v) => `- ${escl(v.id)}: \`${escl(v.command).replace(/`/g, "'")}\``).join("\n") || NR}\n\n${json}`;
+  const dec = Array.isArray(c.decisions) && c.decisions.length // forge#4165: decision provenance
+    ? `\n\n### Decisions\n| Id | Choice | Justification | Source |\n| --- | --- | --- | --- |\n${c.decisions.map((k) => `| ${esc(k?.id)} | ${esc(k?.choice)} | ${esc(k?.justification)} | ${esc(k?.source)} |`).join("\n")}` : "";
+  return `## Builder Contract (frozen \`${hash}\`)\n\n### Requirements\n| Id | From the issue | Disposition |\n| --- | --- | --- |\n${req}\n\n### Deliverables\n${del ? `| Id | Path | Change | Requirements |\n| --- | --- | --- | --- |\n${del}` : "None."}\n\n### Preserve\n${(c.preserve ?? []).map((p) => `- ${escl(p.id)}: ${escl(p.what)}`).join("\n") || "None."}\n\n### Validate\n${(c.validate ?? []).map((v) => `- ${escl(v.id)}: \`${escl(v.command).replace(/`/g, "'")}\``).join("\n") || NR}${dec}\n\n${json}`;
 }
 /** {contract, hash, text} from a FORGE:CONTRACT comment body, or null. */
 export function parseContractComment(body) {
@@ -120,12 +122,12 @@ export function renderReview(rv, contract) {
 }
 
 /** FORGE:REVIEW in shadow mode: what the enforced gate would have done, without enforcing it. */
-export function renderShadowReview({ would, failures = [], review, contract, unfiled = [] }) {
+export function renderShadowReview({ would, failures = [], review, contract, degraded = null }) {
   const head = would === "conforms" ? "would PASS" : `would BLOCK (${escl(would)})`;
   const rows = review ? `\n\n${renderReview(review, contract).split("\n").slice(2).join("\n")}` : "";
   const fl = failures.length ? `\n\n**What the enforced gate would have flagged:**\n${failures.slice(0, 30).map((f) => `- \`${escl(f.code)}\`: ${escl(f.detail)}`).join("\n")}` : "";
-  const uf = unfiled.length ? `\n\n**Deferrals not filed in shadow mode:** ${unfiled.map((r) => `${escl(r.id)} (${escl(r.disposition)})`).join(", ")}` : "";
-  return `## Conformance Review (shadow mode: not enforced)\n**Gate verdict:** ${head}. Only a requirement found not implemented, or a regression, blocks in shadow mode.${fl}${uf}${rows}`;
+  const dg = degraded ? `\n\n**Review degraded:** the review stayed incomplete after the targeted re-ask; merged with label \`review-degraded\`, follow-up ${escl(degraded)}.` : "";
+  return `## Conformance Review (shadow mode: not enforced)\n**Gate verdict:** ${head}. In shadow mode a requirement not implemented (found by the review or the precheck), a regression, or a review without complete rows blocks; accepted deferrals are filed as follow-ups.${fl}${dg}${rows}`;
 }
 
 // ---- PR body ----
@@ -140,11 +142,28 @@ export function renderPrBody({ issue, investigation, contract, implementation, r
 }
 
 // ---- trajectory ----
+/**
+ * forge#4165: the merged change's structure delta as a compact table, or "" without one. `s` is the STRUCTURE_DELTA
+ * record built at merge: deps_added [{from,to,manifest}], new_edges [{from,to,file}], removed_edges [{from,to}],
+ * top_growth [{file,lines}], decisions [{id,source}].
+ */
+export function renderStructure(s) {
+  if (!s || typeof s !== "object") return "";
+  const list = (v, fn) => (Array.isArray(v) && v.length ? v.slice(0, 10).map(fn).join(", ") + (v.length > 10 ? `, +${v.length - 10} more` : "") : "none");
+  const rows = [
+    ["Package deps added", list(s.deps_added, (e) => `${e.from} → ${e.to}${e.manifest ? ` (${e.manifest})` : ""}`)],
+    ["Import edges added", list(s.new_edges, (e) => `${e.from} → ${e.to}${e.file ? ` (${e.file})` : ""}`)],
+    ["Import edges removed", list(s.removed_edges, (e) => `${e.from} → ${e.to}`)],
+    ["Top growth", list(s.top_growth, (g) => `${g.file} +${g.lines}`)],
+    ["Decision sources", list(s.decisions, (k) => `${k.id} ${k.source}`)],
+  ];
+  return `**Structure**\n| Delta | Value |\n| --- | --- |\n${rows.map(([k, v]) => `| ${k} | ${esc(v)} |`).join("\n")}\n\n`;
+}
 export function renderTrajectory(T) {
   const rows = [["Validate", T.validate], ["Plan", T.plan], ["Implement", T.implement], ...(T.verify ? [["Verify", T.verify]] : []), ["Review", T.review], ["PR", T.pr], ["Base Sync", T.baseSync ?? "not needed"], ["Merge", T.merge], ["Close", T.close]];
   const cellPair = (v) => {
     const [res, notes] = Array.isArray(v) ? v : [v, ""];
     return `${cell(res ?? "not reached")} | ${notes ? cell(notes) : "-"}`;
   };
-  return `## Pipeline Trajectory — #${T.issue}\n\n| Phase | Result | Notes |\n| --- | --- | --- |\n${rows.map(([p, v]) => `| ${p} | ${cellPair(v)} |`).join("\n")}\n\n**Decisions**\n${(T.decisions ?? []).length ? T.decisions.map((d) => `- ${line(d)}`).join("\n") : "- none"}\n\n**Anomalies**\n${(T.anomalies ?? []).length ? T.anomalies.map((d) => `- ${line(d)}`).join("\n") : "- none"}\n\n${T.usage ? `_${T.usage}_` : ""}`;
+  return `## Pipeline Trajectory — #${T.issue}\n\n| Phase | Result | Notes |\n| --- | --- | --- |\n${rows.map(([p, v]) => `| ${p} | ${cellPair(v)} |`).join("\n")}\n\n${renderStructure(T.structure)}**Decisions**\n${(T.decisions ?? []).length ? T.decisions.map((d) => `- ${line(d)}`).join("\n") : "- none"}\n\n**Anomalies**\n${(T.anomalies ?? []).length ? T.anomalies.map((d) => `- ${line(d)}`).join("\n") : "- none"}\n\n${T.usage ? `_${T.usage}_` : ""}`;
 }

package/bin/lean/review-trigger.mjs

@@ -0,0 +1,134 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * Deterministic review trigger (#4273, #4199 "Judge only on a risk trigger"). The conformance reviewer is needed when
+ * the diff touches a risk path, adds a package edge (#4159), changes an over-threshold file (#4195), or a deterministic
+ * gate failed or could not answer. Otherwise the review would be skipped. forge.yaml `review.trigger`: shadow (default:
+ * log REVIEW_TRIGGER, always review), enforce (skip the reviewer when not triggered), off (today's behaviour).
+ * Run directly, it reports per repo how many would-skip lanes the reviewer flagged as nonconforming.
+ */
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { matchesGlob } from "./verify.mjs";
+
+/** The engine run-log dir (same rule as bin/stats/local-source.mjs runsDir). */
+const runsDir = (env = process.env) => env.FORGE_RUNS_DIR || join(homedir(), ".forge", "runs");
+
+export const TRIGGER_MODES = Object.freeze(["shadow", "enforce", "off"]);
+
+/** Built-in risk words, matched against a path's word tokens (camelCase, "/", ".", "-", "_" split them). */
+export const DEFAULT_RISK_PATTERNS = Object.freeze({
+  auth: ["auth", "authn", "authz", "oauth", "login", "logout", "session", "sessions", "permission", "permissions", "rbac", "acl"],
+  payments: ["payment", "payments", "billing", "checkout", "stripe", "invoice", "invoices", "subscription", "subscriptions"],
+  security: ["security", "crypto", "secret", "secrets", "credential", "credentials", "token", "tokens"],
+  deletion: ["delete", "deletion", "purge", "gdpr", "erase"],
+  migrations: ["migration", "migrations", "migrate", "alembic"],
+});
+const RISK_WORDS = new Map(Object.entries(DEFAULT_RISK_PATTERNS).flatMap(([k, ws]) => ws.map((w) => [w, k])));
+
+/** Word tokens of a path: "src/AuthService/user_delete.ts" -> src, auth, service, user, delete, ts. */
+const tokens = (p) => String(p).replace(/([a-z0-9])([A-Z])/g, "$1 $2").toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
+
+/** The built-in risk class a path hits, or null. */
+export function riskClassOf(path) {
+  for (const t of tokens(path)) if (RISK_WORDS.has(t)) return RISK_WORDS.get(t);
+  return null;
+}
+
+/** forge.yaml review.risk_paths: a comma-separated string or a list -> trimmed non-empty globs. */
+export function parseRiskPaths(v) {
+  const xs = Array.isArray(v) ? v : typeof v === "string" ? v.split(",") : [];
+  return xs.map((x) => String(x ?? "").trim()).filter(Boolean);
+}
+
+/**
+ * {would_skip, reasons:[{code, detail}]} from facts only. Codes: risk_path, package_edge, hotspot, gate.failed,
+ * gate.ambiguous. `hotspots` null/undefined means the facts were unavailable (ambiguous); {enabled:false} is an answer.
+ * gates: {precheckFailures[], checkCommandsFailing, ciFellBack}. Reasons are sorted, so equal input gives equal output.
+ */
+export function computeTrigger({ files = [], riskPaths = [], structure = null, hotspots, gates = {}, contract = null } = {}) {
+  const reasons = [];
+  const add = (code, detail) => reasons.push({ code, detail });
+  const globs = parseRiskPaths(riskPaths);
+  for (const f of [...new Set(files.map(String))].sort()) {
+    const cls = riskClassOf(f);
+    if (cls) add("risk_path", `${f} (${cls})`);
+    else { const g = globs.find((x) => matchesGlob(f, x)); if (g) add("risk_path", `${f} (review.risk_paths ${g})`); }
+  }
+  for (const e of Array.isArray(structure?.package_edges_added) ? structure.package_edges_added : []) add("package_edge", `${e?.from} → ${e?.to}`);
+  if (hotspots == null) add("gate.ambiguous", "hotspot facts unavailable");
+  else if (hotspots.enabled !== false && Array.isArray(hotspots.files)) {
+    const changed = new Set(files.map(String));
+    for (const h of hotspots.files) if (h?.over === true && h.excluded !== true && changed.has(String(h.path))) add("hotspot", `${h.path} (${h.lines} lines)`);
+  }
+  const pre = Array.isArray(gates.precheckFailures) ? gates.precheckFailures : [];
+  for (const c of [...new Set(pre.map((f) => String(f?.code ?? f)))].sort()) add("gate.failed", `precheck ${c}`);
+  if (gates.checkCommandsFailing) add("gate.failed", "declared check commands still failing");
+  if (gates.ciFellBack) add("gate.failed", "CI verification unavailable (local fallback)");
+  const tracked = (contract?.requirements ?? []).filter((r) => r?.disposition === "defer" || r?.disposition === "post-deploy").map((r) => r.id);
+  if (tracked.length) add("gate.ambiguous", `contract defers ${tracked.sort().join(", ")} (only the reviewer judges deferrals)`);
+  reasons.sort((a, b) => a.code.localeCompare(b.code) || a.detail.localeCompare(b.detail));
+  return { would_skip: reasons.length === 0, reasons };
+}
+
+/**
+ * Per repo, over run logs (one event array per log; the slice from the last RUN_START counts): runs with a
+ * REVIEW_TRIGGER, would-skip runs (their last REVIEW_TRIGGER), how many of those the reviewer flagged nonconforming
+ * (a CONFORMANCE event with state "nonconforming"), and enforce skips.
+ */
+export function triggerReport(logs = []) {
+  const out = {};
+  for (const events of logs) {
+    if (!Array.isArray(events)) continue;
+    let s = -1;
+    events.forEach((e, i) => { if (e?.event === "RUN_START") s = i; });
+    if (s < 0) continue;
+    const ev = events.slice(s);
+    const trig = ev.filter((e) => e?.event === "REVIEW_TRIGGER");
+    if (!trig.length) continue;
+    const repo = typeof ev[0].repo === "string" && ev[0].repo ? ev[0].repo : "unknown";
+    const r = (out[repo] ??= { runs: 0, would_skip: 0, would_skip_flagged: 0, skipped: 0 });
+    r.runs++;
+    if (trig.some((e) => e.skipped === true)) r.skipped++;
+    if (trig.at(-1).would_skip !== true) continue;
+    r.would_skip++;
+    if (ev.some((e) => e?.event === "CONFORMANCE" && e.state === "nonconforming")) r.would_skip_flagged++;
+  }
+  return out;
+}
+
+function parseLog(text) {
+  const out = [];
+  for (const line of text.split("\n")) {
+    if (!line.trim()) continue;
+    try { const e = JSON.parse(line); if (e && typeof e === "object") out.push(e); } catch { /* truncated or corrupt line */ }
+  }
+  return out;
+}
+
+/** Every *.jsonl run log in `dir`; a missing dir is no runs. */
+export function readRunLogs(dir = runsDir()) {
+  if (!existsSync(dir)) return [];
+  const logs = [];
+  for (const f of readdirSync(dir).sort()) {
+    if (!f.endsWith(".jsonl")) continue;
+    try { logs.push(parseLog(readFileSync(join(dir, f), "utf8"))); } catch { /* unreadable log */ }
+  }
+  return logs;
+}
+
+export function formatReport(report) {
+  const rows = Object.entries(report).sort(([a], [b]) => a.localeCompare(b));
+  if (!rows.length) return "No REVIEW_TRIGGER runs found.";
+  return ["| Repo | Runs | Would skip | Would skip, reviewer flagged | Skipped (enforce) |", "| --- | --- | --- | --- | --- |",
+    ...rows.map(([repo, r]) => `| ${repo} | ${r.runs} | ${r.would_skip} | ${r.would_skip_flagged} | ${r.skipped} |`)].join("\n");
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  const argv = process.argv.slice(2);
+  const i = argv.indexOf("--dir");
+  const report = triggerReport(readRunLogs(i >= 0 && argv[i + 1] ? argv[i + 1] : runsDir()));
+  process.stdout.write((argv.includes("--json") ? JSON.stringify(report, null, 2) : formatReport(report)) + "\n");
+}