forgedock 1.30.0 → 1.32.0

package/bin/lean/context.test.mjs

@@ -2,7 +2,8 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 import { describe, it } from "node:test";
 import assert from "node:assert/strict";
-import { gatherContextFacts, compileContextPack, contextPackFor, contextPackCacheKey, linkStateStamp, LINK_STAMP_MAX, parseContextPackConfig, laneType, priorAttempts, issueSymbols, bodyLinks, parentOf, renderContextRecord, DEFAULT_CONTEXT_BYTES, noComments } from "./context.mjs";
+import { normaliseFacts, renderFactsRecord, FACTS_MARKER } from "./facts.mjs";
+import { gatherContextFacts, compileContextPack, contextPackFor, contextArm, contextPackCacheKey, linkStateStamp, LINK_STAMP_MAX, parseContextPackConfig, laneType, priorAttempts, issueSymbols, bodyLinks, parentOf, renderContextRecord, DEFAULT_CONTEXT_BYTES, noComments } from "./context.mjs";
 
 const REPO = "o/r";
 const BOT = { author_association: "NONE", user: { type: "Bot", login: "forge[bot]" } };
@@ -33,7 +34,7 @@ function fakes(o = {}) {
     101: [{ id: 2, body: "<!-- FORGE:DECISION -->\nKeep `compileContextPack` pure; I/O lives in gather.", ...BOT }],
     102: [],
     103: [{ id: 3, body: "<!-- FORGE:DECISION -->\nUnrelated decision about logging.", ...BOT }],
-    33: [{ id: 4, body: "<!-- FORGE:CONTRACT -->\nx", ...BOT }],
+    33: [{ id: 4, body: "<!-- FORGE:CONTRACT -->\nx", ...BOT }, ...(o.facts33 ?? [])],
   };
   const prs = { 101: { title: "feat: ranking", body: "Closes #33", head: "feat/issue-33-lean" }, 102: { title: "feat: speedup", body: "", head: "feat/issue-34-lean" }, 103: { title: "chore: logs", body: "", head: "x" } };
   const log = [
@@ -109,6 +110,21 @@ describe("context pack (forge#4275)", () => {
     assert.notEqual(contextPackCacheKey(50, "abc", cfg), contextPackCacheKey(51, "abc", cfg));
   });
 
+  it("#4432: the cache key and the prune prefix are repo-scoped, so another repo's pack for the same number survives", async () => {
+    const store = new Map();
+    const fs = { read: async (p) => { if (!store.has(p)) throw new Error("ENOENT"); return store.get(p); }, write: async (p, t) => { store.set(p, t); },
+      list: async () => [...store.keys()].map((p) => p.slice("/runs/".length)), rm: async (p) => { store.delete(p); } };
+    const cfg = parseContextPackConfig({});
+    const g = async () => gather(fakes());
+    assert.match(contextPackCacheKey(50, "abc", cfg, {}, "acme/one"), /^context-acme__one__50-abc-/);
+    assert.equal(contextPackCacheKey(50, "abc", cfg, {}), contextPackCacheKey(50, "abc", cfg), "no repo: today's key");
+    await contextPackFor({ cfg, issue: 50, repo: "acme/one", headSha: "abc", cacheDir: "/runs", fs, gather: g });
+    await contextPackFor({ cfg, issue: 50, repo: "acme/two", headSha: "def", cacheDir: "/runs", fs, gather: g });
+    assert.deepEqual([...store.keys()].map((k) => k.split("-").slice(0, 2).join("-")).sort(), ["/runs/context-acme__one__50", "/runs/context-acme__two__50"]);
+    const again = await contextPackFor({ cfg, issue: 50, repo: "acme/one", headSha: "abc", cacheDir: "/runs", fs, gather: g });
+    assert.equal(again.cached, true);
+  });
+
   it("drops whole items past the byte cap, falls back to one line for a parent body, counts truncation", async () => {
     const facts = await gather(fakes());
     const p = compileContextPack(facts, { budgetBytes: 130 });
@@ -121,7 +137,10 @@ describe("context pack (forge#4275)", () => {
     const f = fakes();
     const facts = await gather(f, { sources: ["graph", "facts"] });
     assert.equal(facts.ledger.length + facts.attempts.length, 0);
-    assert.ok(!f.calls.some((c) => c[1] === "log" || c[1] === "for-each-ref"), "a disabled source makes no calls");
+    assert.ok(!f.calls.some((c) => c[1] === "for-each-ref"), "a disabled source makes no calls");
+    const g = fakes();
+    await gather(g, { sources: ["graph"] });
+    assert.ok(!g.calls.some((c) => c[1] === "log" || c[1] === "for-each-ref"), "no ledger walk without the ledger or facts source (#4401)");
     const p = compileContextPack(facts, { sources: ["graph"] });
     assert.ok(p.text.includes("#40") && !p.text.includes("test-map"));
     assert.deepEqual(parseContextPackConfig({ sources: "ledger, bogus,graph" }).sources, ["graph", "ledger"]);
@@ -166,7 +185,9 @@ describe("context pack (forge#4275)", () => {
   });
 
   it("config, lane type and parsers", () => {
-    assert.deepEqual(parseContextPackConfig({}), { mode: "shadow", sources: ["graph", "attempts", "ledger", "facts"], budgetBytes: 6144, days: 30 });
+    assert.deepEqual(parseContextPackConfig({}), { mode: "shadow", sources: ["graph", "attempts", "pitfalls", "ledger", "facts"], budgetBytes: 6144, days: 30, pitfallLanes: 50 });
+    assert.equal(parseContextPackConfig({ pitfallLanes: 12 }).pitfallLanes, 12);
+    assert.equal(parseContextPackConfig({ pitfallLanes: -3 }).pitfallLanes, 50);
     assert.equal(parseContextPackConfig({ mode: "ON" }).mode, "on");
     assert.equal(parseContextPackConfig({ mode: "nope" }).mode, "shadow");
     assert.equal(laneType({ body: "x\n**Parent**: #3" }), "child");
@@ -183,7 +204,7 @@ describe("context pack (forge#4275)", () => {
     const p = compileContextPack(await gather(fakes()));
     const r = renderContextRecord(p, { mode: "shadow", laneType: "rerun" });
     assert.match(r, /^<details><summary>Context pack: \d+ item\(s\), \d+ bytes, 0 dropped \(mode shadow, lane rerun, hash [0-9a-f]{12}\)<\/summary>/);
-    assert.match(r, /Sources \(included\/found\): graph 5\/5, attempts 3\/3, ledger 3\/3, facts 1\/1/);
+    assert.match(r, /Sources \(included\/found\): graph 5\/5, attempts 3\/3, pitfalls 0\/0, ledger 3\/3, facts 1\/1/);
     assert.ok(r.includes(p.text));
   });
 });
@@ -334,5 +355,136 @@ describe("#4298 context-pack cache and shared names", () => {
     writeFileSync(`${d}/forge.yaml`, "engine:\n  context_pack: on\n");
     assert.deepEqual(readContextPack(d, (m) => warns.push(m)), { mode: "on" });
     assert.equal(warns.length, 1, "a valid mode does not warn");
+    writeFileSync(`${d}/forge.yaml`, "engine:\n  context_pack_pitfall_lanes: 20\n");
+    assert.deepEqual(readContextPack(d, (m) => warns.push(m)), { pitfallLanes: 20 }, "#4375: the pitfall aging window");
+  });
+
+  it("#4444: ab is a valid mode, and contextArm gives each issue a stable on|shadow arm", async () => {
+    const { readContextPack } = await import("../engine-cli.mjs");
+    const { tmpDir } = await import("../tests/_tmp.mjs");
+    const { writeFileSync } = await import("node:fs");
+    const d = tmpDir("ctxab-"), warns = [];
+    writeFileSync(`${d}/forge.yaml`, "engine:\n  context_pack: ab\n");
+    assert.deepEqual(readContextPack(d, (m) => warns.push(m)), { mode: "ab" });
+    assert.equal(warns.length, 0);
+    assert.equal(parseContextPackConfig({ mode: "AB" }).mode, "ab");
+    assert.equal(parseContextPackConfig({}).mode, "shadow", "the default stays shadow");
+    for (const mode of ["shadow", "on", "off"]) assert.deepEqual(contextArm({ mode, repo: "o/r", issue: 1 }), { mode, ab: false });
+    const arms = Array.from({ length: 40 }, (_, i) => contextArm({ mode: "ab", repo: "o/r", issue: i + 1 }));
+    assert.ok(arms.every((a) => a.ab && ["on", "shadow"].includes(a.mode)));
+    assert.ok(arms.some((a) => a.mode === "on") && arms.some((a) => a.mode === "shadow"), "both arms are populated");
+    assert.deepEqual(contextArm({ mode: "ab", repo: "O/R", issue: 7 }), contextArm({ mode: "ab", repo: "o/r", issue: 7 }), "stable per issue");
+  });
+});
+
+describe("#4375 recurring pitfalls in the context pack", () => {
+  const PITS = [
+    { sig: "precheck:aaaaaaaaaaaa", trigger: "precheck", lesson: "precheck: src/a.ts:12:5 error 'x' is defined but never used no-unused-vars", globs: ["src/*.ts"], count: 4, match: "files" },
+    { sig: "docs:bbbbbbbbbbbb", trigger: "docs", lesson: "docs: devdocs/modules/lean.md is stale for bin/lean/lean.mjs", globs: ["devdocs/modules/*.md"], count: 2, match: "repo" },
+  ];
+  const facts = (pitfalls) => gatherContextFacts({ io: { gh: async () => { throw new Error("no gh"); }, git: async () => "", exists: async () => false }, repo: REPO, issue: 50, iss: { number: 50, body: "plain" }, comments: [], cwd: "/wt", base: "origin/staging", sources: ["pitfalls"], pitfalls });
+
+  it("compiles the given pitfalls in order, inside the byte budget, and lists the kept signatures", async () => {
+    const p = compileContextPack(await facts(PITS));
+    assert.ok(p.text.includes("Recurring pitfalls in this repo (past rework):"), p.text);
+    const a = p.text.indexOf("[precheck]"), b = p.text.indexOf("[docs]");
+    assert.ok(a > 0 && b > a, p.text);
+    assert.ok(p.text.includes("(src/*.ts); seen 4×"));
+    assert.deepEqual(p.pitfalls, [{ sig: PITS[0].sig, match: "files" }, { sig: PITS[1].sig, match: "repo" }]);
+    assert.equal(p.sources.pitfalls, 2);
+    const small = compileContextPack(await facts(PITS), { budgetBytes: 200 });
+    assert.ok(small.bytes <= 200 && small.truncated >= 1, `${small.bytes} ${small.truncated}`);
+    assert.deepEqual(small.pitfalls, small.text.includes("[docs]") ? p.pitfalls : [p.pitfalls[0]]);
+    assert.equal(compileContextPack(await facts(PITS), { sources: ["graph"] }).pitfalls.length, 0, "source off: no pitfalls");
+  });
+
+  it("the posted FORGE:CONTEXT record never carries pitfall text, only the count", async () => {
+    const f = await gather(fakes());
+    const p = compileContextPack({ ...f, pitfalls: (await facts(PITS)).pitfalls });
+    assert.ok(p.text.includes("no-unused-vars"));
+    const r = renderContextRecord(p, { mode: "on", laneType: "first" });
+    for (const x of ["no-unused-vars", "Recurring pitfalls", "src/*.ts", "devdocs/modules/lean.md is stale"]) assert.ok(!r.includes(x), x);
+    assert.match(r, /pitfalls 2\/2/);
+    assert.ok(r.includes("Prior attempts at this issue:") && r.includes("Merged PRs on the same symbols"), "the other sections stay");
+  });
+
+  it("the cache key changes when the selected pitfall signatures change", () => {
+    const cfg = parseContextPackConfig({});
+    const k0 = contextPackCacheKey(50, "abc", cfg, { scope: "s", attempts: 0 });
+    assert.equal(contextPackCacheKey(50, "abc", cfg, { scope: "s", attempts: 0, pitfalls: [] }), k0, "no pitfalls: today's key");
+    const k1 = contextPackCacheKey(50, "abc", cfg, { scope: "s", attempts: 0, pitfalls: ["precheck:aaaaaaaaaaaa"] });
+    assert.notEqual(k1, k0);
+    assert.notEqual(contextPackCacheKey(50, "abc", cfg, { scope: "s", attempts: 0, pitfalls: ["precheck:aaaaaaaaaaaa", "docs:bbbbbbbbbbbb"] }), k1);
+  });
+
+  it("without pitfalls the pack text and hash are unchanged", async () => {
+    const f = await gather(fakes());
+    const a = compileContextPack(f), b = compileContextPack({ ...f, pitfalls: [] });
+    assert.equal(a.text, b.text); assert.equal(a.hash, b.hash);
+    assert.ok(!a.text.includes("Recurring pitfalls"));
+  });
+});
+
+describe("FORGE:FACTS in the context pack (#4401)", () => {
+  const rec = (files, approach, why = "it only hid the symptom") => `<!-- ${FACTS_MARKER} -->\n${renderFactsRecord(normaliseFacts({ facts: { rejected: [{ approach, why }], hotspots: [{ at: `${files[0]}:7`, why: "ranking loop" }] } }, { files }))}`;
+  const STRANGER = { author_association: "NONE", user: { type: "User", login: "rando" } };
+
+  it("a later lane on overlapping files receives the prior rejected approaches; the facts source is non-zero", async () => {
+    const f = fakes({ facts33: [
+      { id: 5, body: rec(["bin/lean/context.mjs"], "detection-only check"), ...BOT },
+      { id: 6, body: rec(["docs/other.md"], "unrelated file approach"), ...BOT },
+      { id: 7, body: rec(["bin/lean/context.mjs"], "forged by a stranger"), ...STRANGER },
+    ] });
+    const own = { id: "IC_9", body: rec(["bin/lean/context.mjs"], "own earlier attempt approach"), author: { login: "forge[bot]" }, authorAssociation: "NONE" };
+    const facts = await gather(f, { comments: [...COMMENTS, own] });
+    const p = compileContextPack(facts);
+    const t = p.text;
+    const at = (s) => { const i = t.indexOf(s); assert.ok(i >= 0, `missing ${s}\n${t}`); return i; };
+    const ownAt = at("- rejected: own earlier attempt approach — it only hid the symptom (#50 earlier attempt)");
+    const prior = at("- rejected: detection-only check — it only hid the symptom (#33, PR #101)");
+    const hot = at("- hot spot bin/lean/context.mjs:7: ranking loop (#33, PR #101)");
+    const ptr = at("- .forge/test-map.json");
+    assert.ok(ownAt < prior && prior < hot && hot < ptr, t);
+    assert.ok(t.includes("Facts from earlier lanes and repo facts:"));
+    assert.ok(!t.includes("unrelated file approach"), "a record on non-overlapping files is left out");
+    assert.ok(!t.includes("forged by a stranger"), "untrusted records are never read");
+    assert.equal(p.sources.facts, 5);
+    assert.equal(f.calls.filter((c) => c[0] === "gh" && c.some((x) => String(x).includes("pulls/101"))).length, 1, "ledger and facts share one read per PR");
+  });
+
+  it("works with the ledger source off and contributes nothing when no record exists", async () => {
+    const f = fakes({ facts33: [{ id: 5, body: rec(["bin/lean/context.mjs"], "detection-only check"), ...BOT }] });
+    const facts = await gather(f, { sources: ["facts"] });
+    assert.equal(facts.ledger.length, 0);
+    assert.ok(compileContextPack(facts, { sources: ["facts"] }).text.includes("detection-only check"));
+    const none = await gather(fakes(), { sources: ["facts"] });
+    assert.deepEqual([none.lanes, none.facts], [[], [".forge/test-map.json"]]);
+  });
+});
+
+describe("populated pack sources (#4400)", () => {
+  it("repo-fact files that exist only in the main checkout are listed; the worktree alone (the old lookup) lists none", async () => {
+    const io = (dir) => ({ ...fakes().io, exists: async (p) => p.startsWith(`${dir}/`) && (p.endsWith(".forge/repo-facts.json") || p.endsWith(".forge/test-map.json")) });
+    const inCheckout = await gather({ io: io("/main") }, { sources: ["facts"], checkout: "/main" });
+    assert.deepEqual(inCheckout.facts, [".forge/repo-facts.json", ".forge/test-map.json"]);
+    const worktreeOnly = await gather({ io: io("/main") }, { sources: ["facts"] });
+    assert.deepEqual(worktreeOnly.facts, []);
+    const both = await gather({ io: { ...fakes().io, exists: async (p) => p.endsWith(".forge/repo-facts.json") } }, { sources: ["facts"], checkout: "/main" });
+    assert.deepEqual(both.facts, [".forge/repo-facts.json"], "a file in both dirs is listed once");
+  });
+
+  it("an issue with a prior run, a ledger PR on its file and a FORGE:FACTS record has non-zero attempts, ledger and facts", async () => {
+    const rec = `<!-- ${FACTS_MARKER} -->\n${renderFactsRecord(normaliseFacts({ facts: { rejected: [{ approach: "retry only", why: "hid the race" }] } }, { files: ["bin/lean/context.mjs"] }))}`;
+    const f = fakes({ facts33: [{ id: 8, body: rec, ...BOT }] });
+    const p = compileContextPack(await gather(f, { checkout: "/main" }));
+    for (const s of ["attempts", "ledger", "facts"]) assert.ok(p.sources[s] > 0, `${s} is zero: ${JSON.stringify(p.sources)}`);
+  });
+});
+
+describe("#4467: priorAttempts reads App comments in gh issue view shape", () => {
+  const ghShape = (login) => ({ author: { login }, authorAssociation: "CONTRIBUTOR", body: "<!-- FORGE:NEEDS_HUMAN -->\nstuck" });
+  it("counts the App's NEEDS_HUMAN, not a stranger's", () => {
+    assert.equal(priorAttempts("", [ghShape("rapiercraft-forgedock")]), 1);
+    assert.equal(priorAttempts("", [ghShape("someone")]), 0);
   });
 });

package/bin/lean/decompose.mjs

@@ -0,0 +1,90 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * Decomposition gate (#4396): a builder `split-required` block is admitted only when its sub-issues touch disjoint
+ * areas (each declares `paths`) or the block's `size` estimate exceeds the large-lane budget; otherwise the issue stays
+ * one lane with an ordered checklist. Also the batch report's decomposed vs single-lane $/parent line. Pure: no I/O.
+ */
+
+/** The large-lane size budget: a split of overlapping parts is admitted only above it. */
+export const SPLIT_MIN_FILES = 25;
+export const SPLIT_MIN_LINES = 1500;
+
+const norm = (p) => String(p).trim().replace(/^(\.?\/+)+/, "").replace(/\/+$/, "");
+const overlaps = (a, b) => a === b || a.startsWith(`${b}/`) || b.startsWith(`${a}/`);
+const count = (v) => (typeof v === "number" && Number.isFinite(v) && v >= 0 ? v : null);
+
+/** The block's `size` as {files, lines} (null fields when not a finite non-negative number), or null when absent. */
+function sizeOf(block) {
+  const s = block?.size;
+  if (!s || typeof s !== "object" || Array.isArray(s)) return null;
+  const files = count(s.files), lines = count(s.lines);
+  return files == null && lines == null ? null : { files, lines };
+}
+
+/**
+ * @param {object} block result.json `block` of kind split-required (sub-issues already checked for title and body)
+ * @returns {{ok:true, rationale:{independent:boolean, oversize:boolean, overlaps:Array<[number,number,string,string]>, missing:number[], size:?{files:?number, lines:?number}}} | {ok:false, problem:string}}
+ */
+export function splitGate(block) {
+  const subs = Array.isArray(block?.subissues) ? block.subissues : [];
+  // `paths` or the #4385 `files` (the files each sub-issue edits): either declares the area a part touches.
+  const declared = (s) => [...(Array.isArray(s?.paths) ? s.paths : []), ...(Array.isArray(s?.files) ? s.files : [])];
+  const paths = subs.map((s) => [...new Set(declared(s).filter((p) => typeof p === "string" && norm(p)).map(norm))]);
+  const missing = paths.flatMap((p, i) => (p.length ? [] : [i]));
+  const found = [];
+  for (let i = 0; i < paths.length; i++) {
+    for (let j = i + 1; j < paths.length; j++) {
+      for (const a of paths[i]) for (const b of paths[j]) if (overlaps(a, b)) found.push([i, j, a, b]);
+    }
+  }
+  const independent = subs.length > 0 && !missing.length && !found.length;
+  const size = sizeOf(block);
+  const oversize = !!size && ((size.files ?? 0) > SPLIT_MIN_FILES || (size.lines ?? 0) > SPLIT_MIN_LINES);
+  if (independent || oversize) return { ok: true, rationale: { independent, oversize, overlaps: found, missing, size } };
+  const why = [];
+  if (missing.length) why.push(`sub-issue(s) ${missing.join(", ")} declare no "paths" or "files"`);
+  if (found.length) why.push(`the parts overlap (${found.slice(0, 5).map(([i, j, a, b]) => `${i}:${a} ~ ${j}:${b}`).join("; ")})`);
+  why.push(size ? `the size estimate (${size.files ?? "?"} files, ${size.lines ?? "?"} lines) is within the ${SPLIT_MIN_FILES}-file / ${SPLIT_MIN_LINES}-line budget` : "the block has no \"size\" estimate");
+  return { ok: false, problem: `the split is not justified: ${why.join("; ")}. Split only when every sub-issue lists "paths" (or "files") disjoint from the others, or when "size" exceeds ${SPLIT_MIN_FILES} files or ${SPLIT_MIN_LINES} lines. Otherwise keep one lane: write the contract as an ordered checklist, one requirement or deliverable per item, each with its own validate command` };
+}
+
+/** One line for the FORGE:DECOMPOSED comment and the decision log. */
+export function rationaleLine(r) {
+  if (!r) return "";
+  const ov = r.overlaps?.length ? ` (overlaps ${r.overlaps.slice(0, 3).map(([i, j, a, b]) => `${i}:${a} ~ ${j}:${b}`).join("; ")})` : r.missing?.length ? ` (no paths: ${r.missing.join(", ")})` : "";
+  const sz = r.size ? `${r.size.files ?? "?"} files, ${r.size.lines ?? "?"} lines` : "no estimate";
+  return `independent: ${r.independent ? "yes" : "no"}${ov}; size: ${sz} vs budget ${SPLIT_MIN_FILES} files / ${SPLIT_MIN_LINES} lines -> oversize ${r.oversize ? "yes" : "no"}`;
+}
+
+/**
+ * Batch-report line: cost per decomposed parent (its row plus its sub-issue rows, recursively) vs per single-lane
+ * parent (a merged row that is no row's sub-issue). Null when no row decomposed.
+ */
+export function formatDecompositionSummary(rows) {
+  const list = (rows ?? []).filter((r) => r && Number.isSafeInteger(r.issue));
+  const subsOf = (r) => (r?.outcome === "decomposed" && Array.isArray(r.subissues) ? r.subissues.filter((n) => Number.isSafeInteger(n) && n !== r.issue) : []);
+  const byIssue = new Map(list.map((r) => [r.issue, r]));
+  const isSub = new Set(list.flatMap(subsOf));
+  const parents = list.filter((r) => subsOf(r).length && !isSub.has(r.issue));
+  if (!list.some((r) => subsOf(r).length)) return null;
+  let lanes = 0, outside = 0;
+  const total = (r, seen) => {
+    let c = Number(r.cost_usd) || 0;
+    for (const n of subsOf(r)) {
+      if (seen.has(n)) continue;
+      seen.add(n);
+      const s = byIssue.get(n);
+      if (!s) { outside++; continue; }
+      lanes++;
+      c += total(s, seen);
+    }
+    return c;
+  };
+  const dCost = parents.reduce((a, r) => a + total(r, new Set([r.issue])), 0);
+  const single = list.filter((r) => r.outcome === "merged" && !isSub.has(r.issue));
+  const sCost = single.reduce((a, r) => a + (Number(r.cost_usd) || 0), 0);
+  const per = (c, n) => `$${(n ? c / n : 0).toFixed(2)}/parent`;
+  return `decomposition: ${parents.length} decomposed parent${parents.length === 1 ? "" : "s"} ${per(dCost, parents.length)} (${lanes} sub-lane${lanes === 1 ? "" : "s"}${outside ? `, ${outside} outside this batch` : ""}); `
+    + (single.length ? `${single.length} single-lane ${per(sCost, single.length)}` : "single-lane none");
+}

package/bin/lean/decompose.test.mjs

@@ -0,0 +1,105 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// #4396: decomposition gate (independence and size) and the batch report's decomposed vs single-lane $/parent line.
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { splitGate, rationaleLine, formatDecompositionSummary, SPLIT_MIN_FILES, SPLIT_MIN_LINES } from "./decompose.mjs";
+import { classifyBlock } from "./lean.mjs";
+import { orchestrate } from "./orchestrate.mjs";
+
+const sub = (paths) => ({ title: "t", body: "b", ...(paths ? { paths } : {}) });
+
+describe("splitGate (#4396)", () => {
+  it("admits parts with disjoint paths and records independent", () => {
+    const g = splitGate({ subissues: [sub(["src/a", "docs/a.md"]), sub(["./src/b/"]), sub(["src/ab"])] });
+    assert.equal(g.ok, true);
+    assert.deepEqual(g.rationale, { independent: true, oversize: false, overlaps: [], missing: [], size: null });
+  });
+
+  it("rejects overlapping parts (same file, or a file under another part's directory) within the size budget", () => {
+    for (const [a, b] of [["src/alerts", "src/alerts/routing.ts"], ["src/x.ts", "./src/x.ts"]]) {
+      const g = splitGate({ subissues: [sub([a]), sub([b])], size: { files: 3, lines: 200 } });
+      assert.equal(g.ok, false, `${a} ~ ${b}`);
+      assert.match(g.problem, /parts overlap/);
+      assert.match(g.problem, /ordered checklist/);
+      assert.match(g.problem, /within the 25-file \/ 1500-line budget/);
+    }
+  });
+
+  it("reads the #4385 per-sub-issue files as the declared area, alone or with paths", () => {
+    const f = (files, paths) => ({ title: "t", body: "b", files, ...(paths ? { paths } : {}) });
+    assert.equal(splitGate({ subissues: [f(["src/a.ts"]), f(["/src/b.ts"])] }).ok, true);
+    const g = splitGate({ subissues: [f(["src/a.ts"]), f(["src/b.ts"], ["src/a.ts"])] });
+    assert.equal(g.ok, false);
+    assert.match(g.problem, /0:src\/a\.ts ~ 1:src\/a\.ts/);
+  });
+
+  it("rejects a split whose parts declare no paths and that has no size estimate", () => {
+    const g = splitGate({ subissues: [sub(), sub(["src/b"])] });
+    assert.equal(g.ok, false);
+    assert.match(g.problem, /sub-issue\(s\) 0 declare no "paths"/);
+    assert.match(g.problem, /no "size" estimate/);
+  });
+
+  it("admits overlapping parts when the size estimate exceeds the budget (files or lines); ignores a non-numeric size", () => {
+    const parts = [sub(["src/a"]), sub(["src/a/x.ts"])];
+    assert.equal(splitGate({ subissues: parts, size: { files: SPLIT_MIN_FILES + 1 } }).rationale.oversize, true);
+    const g = splitGate({ subissues: parts, size: { lines: SPLIT_MIN_LINES + 1 } });
+    assert.deepEqual({ ok: g.ok, independent: g.rationale.independent, oversize: g.rationale.oversize }, { ok: true, independent: false, oversize: true });
+    assert.equal(splitGate({ subissues: parts, size: { files: SPLIT_MIN_FILES, lines: SPLIT_MIN_LINES } }).ok, false, "at the budget is not over it");
+    assert.equal(splitGate({ subissues: parts, size: { files: "99" } }).ok, false);
+  });
+
+  it("rationaleLine names independence, overlaps and size against the budget", () => {
+    const g = splitGate({ subissues: [sub(["src/a"]), sub(["src/a/x.ts"])], size: { files: 40, lines: 3000 } });
+    assert.equal(rationaleLine(g.rationale), "independent: no (overlaps 0:src/a ~ 1:src/a/x.ts); size: 40 files, 3000 lines vs budget 25 files / 1500 lines -> oversize yes");
+    assert.equal(rationaleLine(null), "");
+  });
+
+  it("classifyBlock turns an unjustified split into an untyped block and carries the rationale of an admitted one", () => {
+    const bad = classifyBlock({ block: { kind: "split-required", subissues: [sub(["src/a"]), sub(["src/a"])] } }, 7);
+    assert.equal(bad.kind, "untyped");
+    assert.match(bad.problem, /split is not justified/);
+    const ok = classifyBlock({ block: { kind: "split-required", subissues: [sub(["src/a"]), { ...sub(["src/b"]), depends_on: [0] }] } }, 7);
+    assert.equal(ok.kind, "split");
+    assert.equal(ok.rationale.independent, true);
+    assert.deepEqual(ok.subissues.map((s) => s.dependsOn), [[], [0]]);
+  });
+});
+
+describe("formatDecompositionSummary (#4396)", () => {
+  it("is null when no row decomposed", () => {
+    assert.equal(formatDecompositionSummary([{ issue: 1, outcome: "merged", cost_usd: 3 }]), null);
+    assert.equal(formatDecompositionSummary(undefined), null);
+    assert.equal(formatDecompositionSummary([{ issue: 1, outcome: "decomposed", subissues: [] }]), null);
+  });
+
+  it("sums a parent with its sub-lanes (recursively) and compares with merged single-lane parents", () => {
+    const rows = [
+      { issue: 1, outcome: "decomposed", cost_usd: 2, subissues: [11, 12, 13] },
+      { issue: 11, outcome: "merged", cost_usd: 4 },
+      { issue: 12, outcome: "decomposed", cost_usd: 1, subissues: [121] },
+      { issue: 121, outcome: "merged", cost_usd: 3 },
+      { issue: 2, outcome: "merged", cost_usd: 5 },
+      { issue: 3, outcome: "merged", cost_usd: 7 },
+      { issue: 4, outcome: "needs-human", cost_usd: 9 },
+    ];
+    assert.equal(formatDecompositionSummary(rows), "decomposition: 1 decomposed parent $10.00/parent (3 sub-lanes, 1 outside this batch); 2 single-lane $6.00/parent");
+  });
+
+  it("reports no single-lane parents as none and guards a cycle", () => {
+    const rows = [{ issue: 1, outcome: "decomposed", cost_usd: 1, subissues: [2] }, { issue: 2, outcome: "decomposed", cost_usd: 1, subissues: [1] }];
+    assert.match(formatDecompositionSummary([{ issue: 1, outcome: "decomposed", cost_usd: 2, subissues: [5] }]), /^decomposition: 1 decomposed parent \$2\.00\/parent \(0 sub-lanes, 1 outside this batch\); single-lane none$/);
+    assert.ok(formatDecompositionSummary(rows));
+  });
+
+  it("the batch row keeps the lane's subissues and decomposition, so the report links a parent to its sub-lanes", async () => {
+    const rationale = { independent: true, oversize: false, overlaps: [], missing: [], size: null };
+    const script = { 1: { terminalReason: "decomposed", cost_usd: 2, subissues: [8], decomposition: rationale }, 8: { terminalReason: "merged", cost_usd: 4 }, 2: { terminalReason: "merged", cost_usd: 1 } };
+    const rows = await orchestrate({ issues: [1, 2], parallel: 1, readBody: async () => "", runOne: async (n) => script[n] });
+    const r1 = rows.find((r) => r.issue === 1);
+    assert.deepEqual(r1.subissues, [8]);
+    assert.deepEqual(r1.decomposition, rationale);
+    assert.equal(formatDecompositionSummary(rows), "decomposition: 1 decomposed parent $6.00/parent (1 sub-lane); 1 single-lane $1.00/parent");
+  });
+});

package/bin/lean/depcache.mjs

@@ -80,7 +80,8 @@ export function makeDepCache({ root = depcacheRoot(), exec, fs = nodeFs, now = (
     return { npm_config_store_dir: store("pnpm-store"), npm_config_cache: store("npm-cache"), UV_CACHE_DIR: store("uv-cache"), UV_LINK_MODE: "hardlink",
       POETRY_CACHE_DIR: store("poetry-cache"), PIP_CACHE_DIR: store("pip-cache"), POETRY_VIRTUALENVS_IN_PROJECT: "true" };
   }
-  const run = (cmd, args, cwd) => exec(cmd, args, { cwd, env: env(), timeoutMs: installTimeoutMs });
+  /** Install/repair command; `laneEnv` (the lane's toolchain env, #4347) sits under the store env, so store keys win. */
+  const run = (cmd, args, cwd, laneEnv) => exec(cmd, args, { cwd, env: laneEnv ? { ...laneEnv, ...env() } : env(), timeoutMs: installTimeoutMs });
   const runtime = async (cmd) => { try { return String(await exec(cmd, ["--version"], { timeoutMs: 30000 })).trim(); } catch { return "unknown"; } };
 
   /** Tracked package.json files (workspace members), relative; root only when git cannot list them. */
@@ -190,7 +191,7 @@ export function makeDepCache({ root = depcacheRoot(), exec, fs = nodeFs, now = (
     }
   }
 
-  async function prepareOne(wt, keyRoot, d) {
+  async function prepareOne(wt, keyRoot, d, laneEnv) {
     const t0 = now();
     const done = (status, extra = {}) => ({ status, eco: d.eco, key: extra.key ?? null, ms: now() - t0, reason: extra.reason ?? null, ...(extra.published === undefined ? {} : { published: extra.published }) });
     if (d.skip) return done("skipped", { reason: d.skip });
@@ -209,7 +210,7 @@ export function makeDepCache({ root = depcacheRoot(), exec, fs = nodeFs, now = (
       const created = [];
       try {
         for (const t of man.trees ?? []) { created.push(t); linkTree(join(snap, t), join(wt, t), { from: man.prefix, to: wt, binDir: binDirFor(d) }); }
-        for (const [c, a] of cmds.repair ?? []) await run(c, a, wt);
+        for (const [c, a] of cmds.repair ?? []) await run(c, a, wt, laneEnv);
         try { fs.writeFileSync(join(snap, "last-used"), String(now())); } catch { /* best effort */ }
         return done("hit", { key });
       } catch (e) {
@@ -218,7 +219,7 @@ export function makeDepCache({ root = depcacheRoot(), exec, fs = nodeFs, now = (
       }
     };
     const install = async () => {
-      try { for (const [c, a] of cmds.install) await run(c, a, wt); } catch (e) {
+      try { for (const [c, a] of cmds.install) await run(c, a, wt, laneEnv); } catch (e) {
         rmTrees(wt, expected);
         return { failed: done("failed", { key, reason: `${e?.code === "ENOENT" ? "tool not found" : "install failed"}: ${msg(e)}` }) };
       }
@@ -240,8 +241,11 @@ export function makeDepCache({ root = depcacheRoot(), exec, fs = nodeFs, now = (
     return ins.failed ?? done("miss-installed", { key, published: false, reason: "cache lock busy" });
   }
 
-  /** Materialize or build node_modules/.venv for `wt`; one result per detected ecosystem. Never throws. */
-  async function prepare({ wt, repoKey } = {}) {
+  /**
+   * Materialize or build node_modules/.venv for `wt`; one result per detected ecosystem. Never throws.
+   * `env` (#4347): the lane's toolchain env (PATH with the pinned pm shims) for install/repair; absent means the host PATH.
+   */
+  async function prepare({ wt, repoKey, env: laneEnv } = {}) {
     if (disabled()) return [{ status: "skipped", eco: null, key: null, ms: 0, reason: "FORGE_DEPCACHE=0" }];
     let found;
     try { found = detect(fs, wt); } catch (e) { return [{ status: "failed", eco: null, key: null, ms: 0, reason: msg(e) }]; }
@@ -249,7 +253,7 @@ export function makeDepCache({ root = depcacheRoot(), exec, fs = nodeFs, now = (
     const keyRoot = join(root, safeSegment(repoKey ?? "repo"));
     const out = [];
     for (const d of found) {
-      try { out.push(await prepareOne(wt, keyRoot, d)); } catch (e) { out.push({ status: "failed", eco: d.eco, key: null, ms: 0, reason: msg(e) }); }
+      try { out.push(await prepareOne(wt, keyRoot, d, laneEnv && typeof laneEnv === "object" ? laneEnv : undefined)); } catch (e) { out.push({ status: "failed", eco: d.eco, key: null, ms: 0, reason: msg(e) }); }
     }
     return out;
   }

package/bin/lean/depcache.test.mjs

@@ -8,6 +8,7 @@ import { mkdirSync, writeFileSync, readFileSync, existsSync, statSync, lstatSync
 import { tmpDir } from "../tests/_tmp.mjs";
 import { join, dirname, relative } from "node:path";
 import { makeDepCache } from "./depcache.mjs";
+import { prepareToolchain } from "./toolchain.mjs";
 
 const scratch = () => tmpDir("fd-depcache-");
 const put = (p, text, mode) => { mkdirSync(dirname(p), { recursive: true }); writeFileSync(p, text, mode ? { mode } : undefined); };
@@ -81,6 +82,10 @@ function fakeExec({ failInstall = false, installDelayMs = 0 } = {}) {
       symlinkSync("../left-pad/cli.js", join(cwd, "node_modules/.bin/left-pad"));
       return "";
     }
+    if (cmd === "yarn") {
+      put(join(cwd, "node_modules/left-pad/index.js"), `// ${readFileSync(join(cwd, "yarn.lock"), "utf8").length}\n`);
+      return "";
+    }
     if (cmd === "uv" && args[0] === "venv") { put(join(cwd, ".venv/pyvenv.cfg"), "home = /usr/bin\nrelocatable = true\n"); return ""; }
     if (cmd === "uv" || cmd === "poetry") { venv(cwd, readFileSync(join(cwd, cmd === "uv" ? "uv.lock" : "poetry.lock"), "utf8")); return ""; }
     throw Object.assign(new Error(`spawn ${cmd} ENOENT`), { code: "ENOENT" });
@@ -296,3 +301,79 @@ describe("depcache (#4220): shared dependency installs keyed by lock hash", () =
     assert.ok(!existsSync(fresh));
   });
 });
+
+describe("depcache (#4347): installs and repairs run with the lane toolchain env", () => {
+  const PMS = new Set(["pnpm", "pnpx", "yarn", "npm", "npx"]);
+  /** A host with no global package manager: pm commands resolve only when PATH starts with the toolchain shim dir. */
+  const shimOnlyExec = (f, binDir) => {
+    const seen = [];
+    const exec = async (cmd, args, o = {}) => {
+      if (PMS.has(cmd)) {
+        seen.push({ cmd, args: [...args], env: o.env });
+        if (!String(o.env?.PATH ?? "").startsWith(binDir)) throw Object.assign(new Error(`spawn ${cmd} ENOENT`), { code: "ENOENT" });
+      }
+      return f.exec(cmd, args, o);
+    };
+    return { exec, seen };
+  };
+  /** The real toolchain step: corepack on the host PATH, no global pm; shims recorded, not written. */
+  const laneToolchain = async (wt, binDir) => {
+    const tc = await prepareToolchain({ dir: wt, binDir, basePath: "/host/bin", find: (n) => (n === "corepack" ? "/host/bin/corepack" : null),
+      writeShim: async () => {}, mkdirp: async () => {}, hostNode: () => "v22.1.0" });
+    assert.ok(tc.env, "a packageManager pin yields a toolchain env");
+    return tc.env;
+  };
+
+  it("#4347 a packageManager-pinned pnpm repo with no host pnpm installs and repairs through the lane toolchain env", async () => {
+    const base = scratch(), root = join(base, "cache"), binDir = join(base, "toolchain", "bin");
+    const f = fakeExec(), x = shimOnlyExec(f, binDir);
+    const cache = makeDepCache({ root, exec: x.exec, env: {}, pollMs: 5 });
+    const lane = (name) => { const wt = join(base, "wt", name); FIXTURES.pnpm(wt); put(join(wt, "package.json"), '{"name":"web","private":true,"packageManager":"pnpm@9.12.0"}'); return wt; };
+    const a = lane("a");
+    const env = await laneToolchain(a, binDir);
+    const [r1] = await cache.prepare({ wt: a, repoKey: "r", env });
+    assert.equal(r1.status, "miss-installed", r1.reason);
+    assert.ok(existsSync(join(a, "node_modules/lodash/index.js")));
+    const [r2] = await cache.prepare({ wt: lane("b"), repoKey: "r", env });
+    assert.equal(r2.status, "hit", r2.reason);
+    assert.deepEqual(x.seen.map((c) => [c.cmd, c.args.includes("--offline")]), [["pnpm", false], ["pnpm", true]], "install then repair");
+    for (const c of x.seen) {
+      assert.ok(c.env.PATH.startsWith(`${binDir}:`), "the shim dir leads PATH");
+      assert.equal(c.env.COREPACK_ENABLE_DOWNLOAD_PROMPT, "0");
+      assert.equal(c.env.npm_config_store_dir, join(root, "stores", "pnpm-store"), "the store env stays");
+    }
+    // Without the toolchain env (the toolchain step failed or wrote no shim) it is the host PATH, as before.
+    const [r3] = await makeDepCache({ root: join(base, "cache2"), exec: x.exec, env: {} }).prepare({ wt: lane("c"), repoKey: "r" });
+    assert.equal(r3.status, "failed");
+    assert.match(r3.reason, /tool not found: spawn pnpm ENOENT/);
+  });
+
+  it("#4347 a pinned yarn (node-modules linker) repo installs through the shim env", async () => {
+    const base = scratch(), binDir = join(base, "toolchain", "bin");
+    const x = shimOnlyExec(fakeExec(), binDir);
+    const wt = join(base, "wt", "y");
+    put(join(wt, "package.json"), '{"name":"app","packageManager":"yarn@4.5.0"}');
+    put(join(wt, "yarn.lock"), "__metadata:\n  version: 8\n");
+    put(join(wt, ".yarnrc.yml"), "nodeLinker: node-modules\n");
+    const env = await laneToolchain(wt, binDir);
+    const [r] = await makeDepCache({ root: join(base, "cache"), exec: x.exec, env: {} }).prepare({ wt, repoKey: "r", env });
+    assert.equal(r.status, "miss-installed", r.reason);
+    assert.deepEqual(x.seen.map((c) => [c.cmd, c.args]), [["yarn", ["install", "--immutable"]]]);
+    assert.ok(x.seen[0].env.PATH.startsWith(`${binDir}:`));
+  });
+
+  it("#4347 a plain npm repo without pins passes exactly the store env, as before; store keys win over the lane env", async () => {
+    const s = setup("npm");
+    const [r] = await s.cache.prepare({ wt: s.lane("plain"), repoKey: "r" });
+    assert.equal(r.status, "miss-installed", r.reason);
+    const inst = s.f.calls.filter((c) => c.cmd === "npm");
+    assert.equal(inst.length, 1);
+    const seen = [];
+    const cache = makeDepCache({ root: join(s.base, "cache2"), exec: async (cmd, args, o = {}) => { if (cmd === "npm") seen.push(o); return s.f.exec(cmd, args, o); }, env: {} });
+    await cache.prepare({ wt: s.lane("plain2"), repoKey: "r" });
+    assert.deepEqual(seen[0].env, cache.env(), "no lane env: only the store env");
+    await cache.prepare({ wt: s.lane("pinned"), repoKey: "r2", env: { PATH: "/shim:/host", npm_config_cache: "/lane/should-not-win" } });
+    assert.equal(seen[1].env.PATH, "/shim:/host");
+    assert.equal(seen[1].env.npm_config_cache, cache.env().npm_config_cache);
+  });
+});