diff --git a/apps/server/src/fork/reviewRules/lensComment.ts b/apps/server/src/fork/reviewRules/lensComment.ts index 0931983458621..8f246736b9011 100644 --- a/apps/server/src/fork/reviewRules/lensComment.ts +++ b/apps/server/src/fork/reviewRules/lensComment.ts @@ -128,7 +128,7 @@ export function lensKey(name: string): string { } /** The name has a letter or digit, is no `<...>` placeholder and is more than a round marker. */ -function namesALens(name: string): boolean { +export function namesALens(name: string): boolean { const key = lensKey(name); return ( new RegExp(ALNUM, "u").test(key) && diff --git a/apps/server/src/fork/reviewRules/lensStart.test.ts b/apps/server/src/fork/reviewRules/lensStart.test.ts new file mode 100644 index 0000000000000..04da03622eef9 --- /dev/null +++ b/apps/server/src/fork/reviewRules/lensStart.test.ts @@ -0,0 +1,1003 @@ +// @effect-diagnostics nodeBuiltinImport:off +// Fork: lens_start's plan, prompt, refusals and request ids (lensStart.ts). It replays the CI gate's own shared vectors +// (one source, never copied), so its plan and rounds cannot drift from what the gate requires; a vector it does not +// run fails the count checks below. +import * as NodeFS from "node:fs"; +import { effectiveReviewRules } from "@t3tools/contracts"; +import { assert, describe, it } from "@effect/vitest"; + +import { lensKey, lensScan } from "./lensComment.ts"; +import { + FALLBACK_REVIEW, + LENS_START_MAX_PRS, + confirmLensStart, + gateReads, + lensRequestId, + planLensStart, + startRounds, + type LensStartBase, + type LensStartInput, + type LensStartPlan, + type LensStartPost, + type LensStartPullRequest, +} from "./lensStart.ts"; +import { type ReviewBlock } from "./plan.ts"; +import { judgeRounds, roundMarker } from "./rounds.ts"; + +const V = JSON.parse( + NodeFS.readFileSync( + new URL("../../../../../fork-ci/actions/pr-queue/review.vectors.json", import.meta.url), + "utf8", + ), +); +const configs = V.configs as Record; +const basic = configs.basic!; +const ON = effectiveReviewRules({ preset: "recommended" }); +if (ON.preset !== "recommended") throw new Error("the recommended preset reads as off"); +const REPO = "owner/repo"; +const [A, B, C, D, E, F] = ["a", "b", "c", "d", "e", "f"].map((x) => x.repeat(40)) as [ + string, + string, + string, + string, + string, + string, +]; + +const report = (lens: string, sha: string): LensStartPost => ({ + body: `lens: ${lens} · reviewer: x · read at: ${sha}\nstate: fine\nblocker: none\nmajor: none`, + edited: false, + hidden: false, +}); +/** Every lens prompt of a config, read at the base. */ +const promptsOf = (review: ReviewBlock) => + Object.fromEntries(Object.values(review.lenses).map((l) => [l.prompt, `Look at ${l.prompt}.`])); + +const override = (sha: string): LensStartPost => ({ + body: `${V.override_prefix} ${sha}: a person looked`, + edited: false, + hidden: false, + override: sha, +}); + +function pull(number: number, over: Partial = {}): LensStartPullRequest { + return { + number, + state: "open", + head: A, + base: "main", + changes: [["M", "src/x.ts"]], + posts: [], + ...over, + }; +} + +/** One base: its review block (enforce: the path rules name the lenses), prompts and the gate's input. */ +const baseOf = ( + review: ReviewBlock | null, + requiredLenses: ReadonlyArray | null = [], + prompts: Record = review ? promptsOf(review) : {}, +): LensStartBase => ({ review, prompts, requiredLenses }); + +function input( + over: Partial & { + pullList?: LensStartPullRequest[]; + review?: ReviewBlock | null; + prompts?: Record; + required?: ReadonlyArray | null; + }, +) { + const { pullList = [pull(1)], review = basic, prompts, required = [], ...rest } = over; + return { + rules: ON, + repo: REPO, + bases: new Map([["main", baseOf(review, required, prompts)]]), + overridePrefix: V.override_prefix, + prs: pullList.map((p) => ({ number: p.number })), + pulls: new Map(pullList.map((p) => [p.number, p])), + ...rest, + } satisfies LensStartInput; +} + +/** + * The gate's lens verdict, written from its own code, not from lensStart.ts: head_check.decide's required lenses (the + * input; in enforce also the path lenses, as the shared case vector names them, and the approach lens from its + * round), lens.Review.lens_reads (each lens's newest entry; a newer override covers it) and head_check.verdict (every + * required key read, every entry one full sha, the head or the same change). + */ +function gatePasses( + review: ReviewBlock, + input: ReadonlyArray, + pathLenses: ReadonlyArray, + posts: ReadonlyArray, + head: string, + changeOf: (sha: string) => string = (sha) => sha, +): boolean { + const lensPosts = posts.flatMap((p, i) => (p.override === undefined ? [{ p, i }] : [])); + const newest = posts.findLastIndex((p) => p.override !== undefined); + const entries: Record = {}; + for (const { p, i } of lensPosts) { + for (const [key, [sha]] of Object.entries( + lensScan([{ ...p, where: `post ${i + 1}` }], V.override_prefix).entries, + )) { + entries[key] = { at: i, sha }; + } + } + const reads = Object.entries(entries).map(([key, { at, sha }]) => [ + key, + newest >= 0 && at < newest + ? posts[newest]!.override! + : sha && /^[0-9a-f]{40}$/u.test(sha) + ? sha + : null, + ]); + const required = new Set(input.map(lensKey)); + if (review.mode === "enforce") { + pathLenses.forEach((name) => required.add(lensKey(name))); + const history = lensScan( + lensPosts.map(({ p }) => p), + V.override_prefix, + ).history; + if (judgeRounds(review, history, {}, false, changeOf).approach) + required.add(lensKey(review.rounds.approach_lens)); + } + if (reads.length === 0) return required.size === 0; + if ([...required].some((key) => !(key in entries))) return false; + const shas = new Set(reads.map(([, sha]) => sha)); + const [sha] = shas; + return ( + shas.size === 1 && typeof sha === "string" && (sha === head || changeOf(sha) === changeOf(head)) + ); +} + +const lensesOf = (plan: ReturnType) => plan.starts.map((s) => s.lens); + +describe("lens_start on the shared vectors", () => { + it("every case: a first read starts each lens the gate requires, one child each, nothing more", () => { + let ran = 0; + for (const c of V.cases) { + const review = configs[c.config]!; + // Shadow: the gate requires only its input; T3 adds the path lenses (the trial shadow is for). + const shadow = review.mode === "shadow"; + const plan = planLensStart( + input({ + review, + required: shadow ? ["code"] : [], + pullList: [pull(7, { changes: c.changes })], + }), + ); + assert.deepStrictEqual(plan.refused, [], c.name); + const want = shadow && !c.lenses.includes("code") ? [...c.lenses, "code"] : c.lenses; + assert.deepStrictEqual(lensesOf(plan), want, c.name); + for (const s of plan.starts) + assert.deepStrictEqual(s.prs, [{ number: 7, head: A, round: 1 }]); + ran++; + } + assert.strictEqual(ran, V.cases.length); + assert.isAtLeast(ran, 28); + }); + + it("every round: a read of an already-read head is that round, a new head at most one more", () => { + const fresh = "0123456789abcdef0123456789abcdef01234567"; + let ran = 0; + for (const r of V.rounds) { + const review = configs[r.config]!; + const changes = r.changes as Record | undefined; + const changeOf = changes && ((sha: string) => changes[sha] ?? sha); + const history = r.history as Array<[string, string | null]>; + assert.notInclude( + history.map(([, sha]) => sha), + fresh, + ); + const last = history.findLast(([, sha]) => sha !== null)?.[1]; + if (last) + assert.strictEqual( + startRounds(review, history, last, changeOf).round, + r.expect.round, + r.name, + ); + const next = startRounds(review, history, fresh, changeOf).round; + const marked = history.some(([name]) => roundMarker(name) >= next); + assert.isTrue(next === r.expect.round + 1 || (marked && next === r.expect.round), r.name); + ran++; + } + assert.strictEqual(ran, V.rounds.length); + assert.isAtLeast(ran, 28); + }); + + it("every shared vector state: after the plan is carried out the gate passes, or a person must act", () => { + // States: each scan's posts, each round's history as reports, and mixed heads the vectors do not hold. + const states: Array<[string, LensStartPost[]]> = [ + ...V.scans.map( + (v: { + name: string; + posts: Array<{ body: string; edited?: boolean; hidden?: boolean }>; + }) => [ + `scan ${v.name}`, + v.posts.map((p) => ({ + body: p.body, + edited: p.edited ?? false, + hidden: p.hidden ?? false, + })), + ], + ), + ...V.rounds.map((r: { name: string; history: Array<[string, string | null]> }) => [ + `round ${r.name}`, + r.history.flatMap(([name, sha]) => (sha ? [report(name, sha)] : [])), + ]), + ["two lenses, one head each", [report("data-1", A), report("code", B)]], + ["a lens no longer required", [report("data-1", A), report("data-2", A)]], + ["an override covers an older read", [report("code", B), override(A)]], + [ + "an override covers a comment that reads nothing", + [ + { body: `Review done.\n${report("code", B).body}`, edited: false, hidden: false }, + override(A), + ], + ], + ["a read newer than an override", [override(A), report("code", B)]], + ]; + const sameChange = () => "one change"; + let plans = 0; + let carried = 0; + let mixed = 0; + let refusedByPerson = 0; + for (const c of V.cases) { + const review = configs[c.config]!; + const enforce = review.mode === "enforce"; + for (const required of enforce ? [[], ["code"]] : [["code"], ["code", "data-1"]]) { + for (const [name, posts] of states) { + for (const head of [A, F]) { + for (const changeOf of [undefined, sameChange]) { + const at = `${c.name} / ${name} / ${required.join(",")} / ${head.slice(0, 1)} / ${changeOf ? "same" : "own"}`; + const one = (list: LensStartPost[]) => + planLensStart( + input({ + review, + required, + pullList: [ + pull(7, { + head, + posts: list, + changes: c.changes, + ...(changeOf ? { changeOf } : {}), + }), + ], + }), + ); + const plan = one(posts); + plans++; + if (plan.refused.length > 0) { + assert.lengthOf(plan.refused, 1, at); + assert.include(plan.refused[0]!.reason, "a person", at); + assert.deepStrictEqual(plan.starts, [], at); + refusedByPerson++; + continue; + } + const after = [ + ...posts, + ...plan.starts.flatMap((s) => s.prs.map((r) => report(s.lens, r.head))), + ]; + if (plan.starts.length > 0) carried++; + if ( + new Set([...gateReads(posts, V.override_prefix).values()].map((r) => r.sha)).size > + 1 + ) + mixed++; + assert.isTrue(gatePasses(review, required, c.lenses, after, head, changeOf), at); + // Runs again: the carried-out plan starts nothing more. + assert.deepStrictEqual(one(after).starts, [], `${at}: again`); + } + } + } + } + } + assert.isAtLeast(plans, V.cases.length * (V.scans.length + V.rounds.length) * 8); + assert.isAtLeast(carried, 1000); + assert.isAtLeast(mixed, 100); + assert.isAtLeast(refusedByPerson, 100); + }); +}); + +describe("lens_start answers the state question", () => { + it("runs again: the same call twice is the same plan, the same ids, the same prompts", () => { + const make = () => + planLensStart( + input({ + pullList: [pull(1, { posts: [report("code", B)] }), pull(2, { head: C })], + }), + ); + const one = make(); + assert.deepStrictEqual(make(), one); + assert.deepStrictEqual( + planLensStart( + input({ pullList: [pull(2, { head: C }), pull(1, { posts: [report("code", B)] })] }), + ).starts.map((s) => s.requestId), + one.starts.map((s) => s.requestId), + ); + }); + + it("runs again after a lens reported: that lens is already read, the rest still start", () => { + const plan = planLensStart( + input({ + pullList: [ + pull(1, { changes: [["M", "src/storage/x.sql"]], posts: [report("data-1", A)] }), + ], + }), + ); + assert.deepStrictEqual(lensesOf(plan), ["data-2"]); + assert.deepStrictEqual(plan.alreadyRead, [{ pr: 1, lens: "data-1" }]); + }); + + it("a report that reads nothing (edited, or of another head) does not count as read", () => { + const edited = { ...report("code", A), edited: true }; + assert.deepStrictEqual( + lensesOf(planLensStart(input({ pullList: [pull(1, { posts: [edited] })] }))), + ["code"], + ); + assert.deepStrictEqual( + lensesOf(planLensStart(input({ pullList: [pull(1, { posts: [report("code", B)] })] }))), + ["code"], + ); + const short = report("code", A.slice(0, 7)); + assert.deepStrictEqual( + lensesOf(planLensStart(input({ pullList: [pull(1, { posts: [short] })] }))), + ["code"], + ); + }); + + it("a short read-at sha never counts as reading the head, even of the same change", () => { + const short = report("code", A.slice(0, 7)); + const plan = planLensStart( + input({ pullList: [pull(1, { posts: [short], changeOf: () => "same" })] }), + ); + assert.deepStrictEqual(lensesOf(plan), ["code"]); + }); + + it("a hidden report of this head is no earlier read in the prompt", () => { + const hidden = { ...report("code", A), hidden: true }; + const plan = planLensStart( + input({ pullList: [pull(1, { posts: [report("code", B), hidden] })] }), + ); + assert.include( + plan.starts[0]!.prompt, + `read it before at ${B}: check each earlier finding first, then the changes since ${B}.`, + ); + }); + + it("a read before a clean base merge still read the head when the change is the same", () => { + const plan = planLensStart( + input({ + pullList: [pull(1, { head: B, posts: [report("code", A)], changeOf: () => "same" })], + }), + ); + assert.deepStrictEqual(lensesOf(plan), []); + assert.deepStrictEqual(plan.alreadyRead, [{ pr: 1, lens: "code" }]); + }); + + it("the head moved since the plan: the child is refused, call again plans the new head", () => { + const plan = planLensStart(input({ pullList: [pull(1), pull(2, { head: B })] })); + assert.lengthOf(plan.starts, 1); + const moved = confirmLensStart( + plan, + new Map([ + [1, C], + [2, B], + ]), + ); + assert.deepStrictEqual(moved.starts, []); + assert.include(moved.refused.find((r) => r.pr === 1)!.reason, `moved from ${A} to ${C}`); + assert.isTrue(moved.refused.some((r) => r.pr === null && r.reason.includes("#1 #2"))); + const kept = confirmLensStart( + plan, + new Map([ + [1, A.toUpperCase()], + [2, B], + ]), + ); + assert.strictEqual(kept, plan); + const closed = confirmLensStart( + plan, + new Map([ + [1, null], + [2, B], + ]), + ); + assert.deepStrictEqual(closed.starts, []); + assert.include(closed.refused.find((r) => r.pr === 1)!.reason, "no longer open"); + const again = planLensStart(input({ pullList: [pull(1, { head: C }), pull(2, { head: B })] })); + assert.notStrictEqual(again.starts[0]!.requestId, plan.starts[0]!.requestId); + }); + + it("a moved head only stops the children that read it", () => { + const plan = planLensStart( + input({ + pullList: [ + pull(1, { changes: [["M", "src/storage/x.sql"]] }), + pull(2, { head: B, posts: [report("data-1", B)], changes: [["M", "src/storage/y.sql"]] }), + ], + }), + ); + // data-1 reads #1 only, data-2 reads both. + assert.deepStrictEqual( + plan.starts.map((s) => [s.lens, s.prs.map((r) => r.number)]), + [ + ["data-1", [1]], + ["data-2", [1, 2]], + ], + ); + const got = confirmLensStart( + plan, + new Map([ + [1, A], + [2, C], + ]), + ); + assert.deepStrictEqual(lensesOf(got), ["data-1"]); + }); + + it("the caller's head is not GitHub's: refused, no read of a head nobody asked for", () => { + const plan = planLensStart({ ...input({}), prs: [{ number: 1, head: B }] }); + assert.deepStrictEqual(plan.starts, []); + assert.include(plan.refused[0]!.reason, `its head is ${A}, not ${B}`); + assert.lengthOf( + planLensStart({ ...input({}), prs: [{ number: 1, head: A.toUpperCase() }] }).starts, + 1, + ); + }); + + it("old or empty settings: unset, empty, off, unreadable or a project's off all start nothing", () => { + for (const rules of [ + effectiveReviewRules(undefined), + effectiveReviewRules({ preset: "off" }), + effectiveReviewRules({ preset: "recommended", unreadable: { preset: "on" } }), + effectiveReviewRules({ preset: "recommended" }, { preset: "off" }), + ]) { + const plan = planLensStart(input({ rules })); + assert.deepStrictEqual(plan.starts, []); + assert.deepStrictEqual( + plan.refused.map((r) => r.pr), + [null], + ); + assert.include(plan.refused[0]!.reason, "review rules are off"); + } + }); + + it("a round already at the limit: the head read in round 4 still gets its missing lens; round 5 never starts", () => { + const four = [report("code", A), report("code", B), report("code", C), report("code", D)]; + const at = planLensStart( + input({ + pullList: [pull(1, { head: D, posts: four, changes: [["M", "src/storage/x.sql"]] })], + }), + ); + assert.deepStrictEqual(at.refused, []); + assert.deepStrictEqual(lensesOf(at), ["data-1", "data-2", "approach"]); + assert.isTrue(at.starts.every((s) => s.prs[0]!.round === 4)); + const over = planLensStart(input({ pullList: [pull(1, { head: E, posts: four })] })); + assert.deepStrictEqual(over.starts, []); + assert.include(over.refused[0]!.reason, "review round 5, past the cap of 4"); + const marked = planLensStart( + input({ pullList: [pull(1, { head: B, posts: [report("code r5", A)] })] }), + ); + assert.include(marked.refused[0]!.reason, "review round 5"); + }); + + it("a partial batch: a closed, merged or unknown pull request is refused, the rest start", () => { + const plan = planLensStart({ + ...input({ + pullList: [ + pull(1), + pull(2, { state: "closed", head: B }), + pull(3, { state: "merged", head: C }), + pull(5, { head: E }), + ], + }), + prs: [1, 2, 3, 4, 5].map((number) => ({ number })), + }); + assert.deepStrictEqual( + plan.starts.map((s) => s.prs.map((r) => r.number)), + [[1, 5]], + ); + assert.deepStrictEqual( + plan.refused.map((r) => r.pr), + [2, 3, 4], + ); + assert.include(plan.refused[0]!.reason, "closed"); + assert.include(plan.refused[2]!.reason, "no pull request #4"); + }); + + it("a batch child that reported some pull requests: again, only the missing ones get a new child", () => { + const first = planLensStart(input({ pullList: [pull(1), pull(2, { head: B })] })); + const later = planLensStart( + input({ pullList: [pull(1, { posts: [report("code", A)] }), pull(2, { head: B })] }), + ); + assert.deepStrictEqual( + later.starts.map((s) => s.prs.map((r) => r.number)), + [[2]], + ); + assert.notStrictEqual(later.starts[0]!.requestId, first.starts[0]!.requestId); + assert.strictEqual( + later.starts[0]!.requestId, + lensRequestId(REPO, "code", [{ number: 2, head: B }]), + ); + }); + + it("a person's override for the head: nothing starts, a new lens comment would end it", () => { + const plan = planLensStart(input({ pullList: [pull(1, { decided: true })] })); + assert.deepStrictEqual(plan.starts, []); + assert.include(plan.refused[0]!.reason, "override"); + }); +}); + +describe("lens_start's plan, prompt and refusals", () => { + it("no plan: changes it cannot read, a path no rule takes, or a prompt not read are refused, never too few lenses", () => { + const noCatchAll = { ...basic, rules: basic.rules.filter((r) => r.name !== "code") }; + for (const [over, words] of [ + [{ pullList: [pull(1, { changes: [["X", "a"]] })] }, "unknown change status"], + [{ review: noCatchAll, pullList: [pull(1)] }, "no rule matches"], + [{ prompts: {} }, "could not be read at the base"], + ] as const) { + const plan = planLensStart(input(over as never)); + assert.deepStrictEqual(plan.starts, []); + assert.include(plan.refused[0]!.reason, "no plan"); + assert.include(plan.refused[0]!.reason, words); + } + const own: ReviewBlock = { + ...basic, + lenses: { ...basic.lenses, "data-2": { prompt: ".github/lenses/data-2.md" } }, + }; + const one = { ...promptsOf(basic) }; + const storage = [["M", "src/storage/x.sql"]]; + const plan = planLensStart( + input({ review: own, prompts: one, pullList: [pull(1, { changes: storage })] }), + ); + assert.deepStrictEqual(plan.starts, []); + assert.include(plan.refused[0]!.reason, "data-2 (.github/lenses/data-2.md)"); + // A lens already read needs no prompt. + const read = planLensStart( + input({ + review: own, + prompts: one, + pullList: [pull(1, { changes: storage, posts: [report("data-2", A)] })], + }), + ); + assert.deepStrictEqual(lensesOf(read), ["data-1"]); + }); + + it("refuses a bad call whole", () => { + for (const [over, words] of [ + [{ repo: "not a repo" }, "not owner/name"], + [{ prs: [] }, "at least one"], + [{ prs: [{ number: 0 }] }, "not a pull request number"], + [ + { + prs: [ + { number: 1, head: A }, + { number: 1, head: B }, + ], + }, + "named twice", + ], + [ + { prs: Array.from({ length: LENS_START_MAX_PRS + 1 }, (_, i) => ({ number: i + 1 })) }, + `at most ${LENS_START_MAX_PRS}`, + ], + ] as const) { + const plan = planLensStart({ ...input({}), ...over }); + assert.deepStrictEqual(plan.starts, []); + assert.deepStrictEqual( + plan.refused.map((r) => r.pr), + [null], + ); + assert.include(plan.refused[0]!.reason, words); + } + assert.lengthOf(planLensStart({ ...input({}), prs: [{ number: 1 }, { number: 1 }] }).starts, 1); + assert.include( + planLensStart(input({ pullList: [pull(1, { head: "abc" })] })).refused[0]!.reason, + "not a full sha", + ); + }); + + it("from round 3 the approach lens joins, with its own runner", () => { + const plan = planLensStart( + input({ pullList: [pull(1, { head: C, posts: [report("code", A), report("code", B)] })] }), + ); + assert.deepStrictEqual(lensesOf(plan), ["code", "approach"]); + assert.deepStrictEqual( + plan.starts.map((s) => s.runner.model), + ["claude-opus-5-5", "claude-fable-5-2"], + ); + const two = planLensStart( + input({ pullList: [pull(1, { head: B, posts: [report("code", A)] })] }), + ); + assert.deepStrictEqual(lensesOf(two), ["code"]); + }); + + it("a runner set for a lens wins over the preset's", () => { + const rules = effectiveReviewRules({ + preset: "recommended", + lensRunners: { code: { driver: ON.runner.driver, model: "m", effort: "xhigh" } }, + }); + const plan = planLensStart(input({ rules })); + assert.deepStrictEqual(plan.starts[0]!.runner, { + driver: ON.runner.driver, + model: "m", + effort: "xhigh", + }); + }); + + it("a repo without a review block: the gate's required-lenses input names the lenses, critical paths not guessed", () => { + const named = ["code", "security"]; + const plan = planLensStart( + input({ + review: null, + required: named, + pullList: [pull(1, { changes: [["M", ".github/workflows/ci.yml"]] })], + }), + ); + assert.deepStrictEqual(plan.refused, []); + assert.deepStrictEqual(lensesOf(plan), named); + assert.include(plan.notes[0], "no `review` block"); + assert.include(plan.notes[0], "required-lenses input (code, security)"); + assert.include(plan.starts[0]!.prompt, "correctness"); + const late = planLensStart( + input({ + review: null, + required: named, + pullList: [ + pull(1, { + head: C, + posts: [ + report("code", A), + report("security", A), + report("code", B), + report("security", B), + ], + }), + ], + }), + ); + assert.deepStrictEqual(lensesOf(late), [...named, FALLBACK_REVIEW.rounds.approach_lens]); + assert.include(late.starts[2]!.prompt, "approach can reach a mergeable state"); + const over = [A, B, C, D].map((sha) => report("code", sha)); + assert.include( + planLensStart( + input({ review: null, required: ["code"], pullList: [pull(1, { head: E, posts: over })] }), + ).refused[0]!.reason, + "past the cap of 4", + ); + // Old or empty state: no block and no input fails every head at the gate; a person must name the lenses. + for (const required of [[], ["", " "]]) { + const none = planLensStart(input({ review: null, required })); + assert.deepStrictEqual(none.starts, []); + assert.include(none.refused[0]!.reason, "a person names the lenses"); + } + }); + + it("the prompt: read only, the lens text, the state question word for word, the report rules and earlier reads", () => { + const plan = planLensStart( + input({ pullList: [pull(4, { head: B, posts: [report("code", A)] })] }), + ); + const prompt = plan.starts[0]!.prompt; + assert.include(prompt, "Read only"); + assert.include(prompt, `Look at ${basic.lenses.code!.prompt}.`); + assert.include(prompt, ON.stateQuestion); + assert.include(prompt, "line starting `state:`"); + assert.include(prompt, "`blocker:`, `major:` or `minor:`"); + assert.include(prompt, `under ${ON.reportMaxChars} characters`); + assert.include(prompt, `#4 at head ${B}: review round 2.`); + assert.include( + prompt, + `read it before at ${A}: check each earlier finding first, then the changes since ${A}`, + ); + assert.include(prompt, "`lens_report`, for the head above"); + const custom = effectiveReviewRules({ + preset: "recommended", + stateQuestion: "What if it runs twice or finds old data?", + }); + assert.include( + planLensStart(input({ rules: custom })).starts[0]!.prompt, + "What if it runs twice or finds old data?", + ); + }); + + it("a batch: one child per lens reads every pull request needing it, one report per pull request with its head", () => { + const plan = planLensStart( + input({ + pullList: [ + pull(1), + pull(2, { head: B, changes: [["M", "src/storage/x.sql"]] }), + pull(3, { head: C, changes: [["M", "docs/a.md"]] }), + ], + }), + ); + assert.deepStrictEqual( + plan.starts.map((s) => [s.lens, s.prs.map((r) => r.number)]), + [ + ["code", [1]], + ["data-1", [2]], + ["data-2", [2]], + ], + ); + const both = planLensStart(input({ pullList: [pull(1), pull(2, { head: B })] })); + assert.lengthOf(both.starts, 1); + const child = both.starts[0]!; + assert.include(child.prompt, `#1 at head ${A}`); + assert.include(child.prompt, `#2 at head ${B}`); + assert.include(child.prompt, "one report per pull request"); + assert.strictEqual(child.title, "lens code #1 #2"); + assert.strictEqual(child.key, lensKey("code")); + }); + + it("request ids: the same lens and heads give the same id, in any order; each fits delegate_task", () => { + const two = [ + { number: 1, head: A }, + { number: 2, head: B }, + ]; + assert.strictEqual( + lensRequestId(REPO, "code", two), + lensRequestId(REPO, "code", two.toReversed()), + ); + assert.notStrictEqual( + lensRequestId(REPO, "code", two), + lensRequestId(REPO, "code", [two[0]!, { number: 2, head: C }]), + ); + assert.notStrictEqual(lensRequestId(REPO, "code", two), lensRequestId(REPO, "data-1", two)); + assert.notStrictEqual( + lensRequestId(REPO, "code", two), + lensRequestId("owner/other", "code", two), + ); + assert.strictEqual(lensRequestId(REPO, "code", [two[0]!]), `lens/${REPO}#1/${A}/code`); + assert.strictEqual( + lensRequestId(REPO, "code", [two[0]!], 2), + `lens/${REPO}#1/${A}/code/again-2`, + ); + const long = lensRequestId(`o/${"r".repeat(200)}`, "x".repeat(40), [two[0]!]); + assert.isAtMost(long.length, 256); + assert.notStrictEqual(long, lensRequestId(`o/${"r".repeat(200)}`, "y".repeat(40), [two[0]!])); + assert.strictEqual( + lensRequestId(REPO, "code review", [two[0]!]), + `lens/${REPO}#1/${A}/code%20review`, + ); + }); +}); + +describe("lens_start plans what the gate reads (fix round A+B)", () => { + const storage = [["M", "src/storage/x.sql"]]; + const carryOut = (posts: ReadonlyArray, plan: LensStartPlan) => [ + ...posts, + ...plan.starts.flatMap((s) => s.prs.map((r) => report(s.lens, r.head))), + ]; + + it("a base merge kept data-1's read: every lens reads the new head, not data-2 alone", () => { + // data-1 read A; the base merged in, head B is the same change, and now touches storage. + const posts = [report("data-1", A)]; + const same = () => "one change"; + const plan = planLensStart( + input({ pullList: [pull(1, { head: B, posts, changes: storage, changeOf: same })] }), + ); + assert.deepStrictEqual(lensesOf(plan), ["data-1", "data-2"]); + assert.deepStrictEqual(plan.alreadyRead, []); + assert.isTrue(gatePasses(basic, [], ["data-1", "data-2"], carryOut(posts, plan), B, same)); + // Stopped half-way: data-2 reported B, data-1 did not; again, only data-1 starts. + const half = [...posts, report("data-2", B)]; + const again = planLensStart( + input({ pullList: [pull(1, { head: B, posts: half, changes: storage, changeOf: same })] }), + ); + assert.deepStrictEqual(lensesOf(again), ["data-1"]); + assert.isTrue(gatePasses(basic, [], ["data-1", "data-2"], carryOut(half, again), B, same)); + }); + + it("a lens no longer required still names an old head: it reads the new head too", () => { + const posts = [report("data-1", A), report("data-2", A)]; + const plan = planLensStart(input({ pullList: [pull(1, { head: B, posts })] })); + assert.deepStrictEqual(lensesOf(plan), ["code", "data-1", "data-2"]); + assert.isTrue(plan.notes.some((n) => n.includes("data-1 is no longer required but read " + A))); + assert.isTrue(gatePasses(basic, [], ["code"], carryOut(posts, plan), B)); + // Runs again after it all reported: nothing more. + assert.deepStrictEqual( + lensesOf( + planLensStart(input({ pullList: [pull(1, { head: B, posts: carryOut(posts, plan) })] })), + ), + [], + ); + }); + + it("an entry lens_start cannot start again: refused, and a person is told the way out", () => { + const noHeader = { + body: `Looks fine.\n${report("code", A).body}`, + edited: false, + hidden: false, + }; + const stuck = planLensStart(input({ pullList: [pull(1, { posts: [noHeader] })] })); + assert.deepStrictEqual(stuck.starts, []); + assert.include(stuck.refused[0]!.reason, "a comment that reads nothing"); + assert.include(stuck.refused[0]!.reason, "a person writes a newer override comment"); + const unknown = planLensStart(input({ pullList: [pull(1, { posts: [report("perf", B)] })] })); + assert.deepStrictEqual(unknown.starts, []); + assert.include(unknown.refused[0]!.reason, `lens perf read ${B}`); + // A person's newer override for the head covers the comment: the required lens still starts. + const covered = [noHeader, override(A)]; + const after = planLensStart(input({ pullList: [pull(1, { posts: covered })] })); + assert.deepStrictEqual(lensesOf(after), ["code"]); + assert.isTrue(gatePasses(basic, [], ["code"], carryOut(covered, after), A)); + }); + + it("a newer override the gate counts is honoured: nothing starts again", () => { + const plan = planLensStart( + input({ pullList: [pull(1, { head: B, posts: [report("code", A), override(B)] })] }), + ); + assert.deepStrictEqual(lensesOf(plan), []); + assert.deepStrictEqual(plan.alreadyRead, [{ pr: 1, lens: "code" }]); + // An override of another head covers nothing for this head. + const other = planLensStart( + input({ pullList: [pull(1, { head: B, posts: [report("code", B), override(A)] })] }), + ); + assert.deepStrictEqual(lensesOf(other), ["code"]); + }); + + it("the required-lenses input joins the plan; a name only it knows reads with the built-in prompt", () => { + const plan = planLensStart(input({ required: ["Security", "code"] })); + assert.deepStrictEqual(lensesOf(plan), ["code", "Security"]); + assert.include(plan.starts[1]!.prompt, "correctness"); + assert.include(plan.notes[0], "names Security, which the config's lenses do not"); + // Shadow: the gate requires only the input; T3 still starts the path lenses. + const shadow = configs["two-critical"]!; + assert.strictEqual(shadow.mode, "shadow"); + const trial = planLensStart( + input({ review: shadow, required: ["code"], pullList: [pull(1, { changes: storage })] }), + ); + assert.deepStrictEqual(trial.refused, []); + assert.include(lensesOf(trial), "code"); + }); + + it("an input or mode the gate refuses: no lens is started, a person fixes it", () => { + const shadow = configs["two-critical"]!; + for (const [over, words] of [ + [{ review: shadow, required: [] }, "a person names the lenses"], + [{ required: null }, "required-lenses input at main was not read"], + [{ required: ["code", ""] }, "a person fixes the caller workflow"], + [{ required: ["r2"] }, "a person fixes the caller workflow"], + [{ review: { ...basic, mode: undefined } }, "a person fixes the config"], + [{ review: { ...basic, mode: "on" as never } }, "a person fixes the config"], + ] as const) { + const plan = planLensStart(input(over as never)); + assert.deepStrictEqual(plan.starts, [], words); + assert.include(plan.refused[0]!.reason, words); + } + }); + + it("each pull request of a batch is planned with its own base branch's rules", () => { + const pulls = [ + pull(1), + pull(2, { head: B, base: "release" }), + pull(3, { head: C, base: "dev" }), + ]; + const plan = planLensStart({ + ...input({ pullList: pulls }), + bases: new Map([ + ["main", baseOf(basic)], + ["release", baseOf(null, ["security"])], + ]), + }); + assert.deepStrictEqual( + plan.starts.map((s) => [s.lens, s.prs.map((r) => r.number)]), + [ + ["code", [1]], + ["security", [2]], + ], + ); + assert.deepStrictEqual(plan.refused, [ + { pr: 3, reason: "its base branch dev was not read: no lens is started rather than too few" }, + ]); + }); + + it("a lens child that ended without its read starts again with the next attempt; a running one is returned", () => { + const first = planLensStart(input({})); + const [child] = first.starts; + assert.strictEqual(child!.attempt, 1); + assert.deepStrictEqual(child!.replaces, []); + const earlier = (running: boolean, ...ids: string[]) => + ids.map((requestId) => ({ requestId, key: "code", prs: [{ number: 1, head: A }], running })); + const second = planLensStart(input({ children: earlier(false, child!.requestId) })); + assert.strictEqual(second.starts[0]!.attempt, 2); + assert.strictEqual(second.starts[0]!.requestId, `${child!.requestId}/again-2`); + assert.deepStrictEqual(second.starts[0]!.replaces, [child!.requestId]); + assert.isTrue( + second.notes.some((n) => n.includes("ended without the read") && n.includes("attempt 2")), + ); + const third = planLensStart( + input({ children: earlier(false, child!.requestId, second.starts[0]!.requestId) }), + ); + assert.strictEqual(third.starts[0]!.attempt, 3); + // A second call while the child still runs: that child, never a duplicate. + const busy = planLensStart(input({ children: earlier(true, child!.requestId) })); + assert.deepStrictEqual(busy.starts, []); + assert.deepStrictEqual(busy.running, [ + { requestId: child!.requestId, key: "code", prs: [{ number: 1, head: A }] }, + ]); + // A batch call overlapping it: only the other pull request gets a child. + const batch = planLensStart( + input({ + pullList: [pull(1), pull(2, { head: B })], + children: earlier(true, child!.requestId), + }), + ); + assert.deepStrictEqual( + batch.starts.map((s) => s.prs.map((r) => r.number)), + [[2]], + ); + assert.lengthOf(batch.running, 1); + // A child of an old head is no child of this one. + const moved = planLensStart( + input({ pullList: [pull(1, { head: B })], children: earlier(true, child!.requestId) }), + ); + assert.deepStrictEqual(lensesOf(moved), ["code"]); + }); + + it("heads and repo in any case: one pull request, one id", () => { + const twice = planLensStart({ + ...input({}), + prs: [ + { number: 1, head: A }, + { number: 1, head: A.toUpperCase() }, + ], + }); + assert.deepStrictEqual(twice.refused, []); + assert.lengthOf(twice.starts, 1); + assert.strictEqual( + planLensStart({ ...input({}), repo: "Owner/Repo" }).starts[0]!.requestId, + planLensStart(input({})).starts[0]!.requestId, + ); + const upper = planLensStart( + input({ pullList: [pull(1, { head: A.toUpperCase(), posts: [report("code", A)] })] }), + ); + assert.deepStrictEqual(lensesOf(upper), []); + }); + + it("the approach lens runs on the approach runner by its role, whatever the config names it", () => { + const own: ReviewBlock = { + ...basic, + lenses: { ...basic.lenses, "stuck-audit": { prompt: "stuck-audit.md" } }, + rounds: { ...basic.rounds, approach_lens: "stuck-audit" }, + }; + const posts = [report("code", A), report("code", B)]; + const plan = planLensStart(input({ review: own, pullList: [pull(1, { head: C, posts })] })); + assert.deepStrictEqual(lensesOf(plan), ["code", "stuck-audit"]); + assert.strictEqual(plan.starts[1]!.runner.model, "claude-fable-5-2"); + const rules = effectiveReviewRules({ + preset: "recommended", + lensRunners: { "stuck-audit": { driver: ON.runner.driver, model: "m", effort: "high" } }, + }); + const set = planLensStart( + input({ rules, review: own, pullList: [pull(1, { head: C, posts })] }), + ); + assert.strictEqual(set.starts[1]!.runner.model, "m"); + }); + + it("a person's override with a lens still missing says so", () => { + const plan = planLensStart(input({ pullList: [pull(1, { decided: true, changes: storage })] })); + assert.deepStrictEqual(plan.starts, []); + assert.include(plan.refused[0]!.reason, "still misses lens data-1, data-2"); + }); + + it("refusals: a lens with no entry, bad numbers, long and odd ids", () => { + const { "data-2": _gone, ...lenses } = basic.lenses; + const plan = planLensStart( + input({ review: { ...basic, lenses }, pullList: [pull(1, { changes: storage })] }), + ); + assert.include(plan.refused[0]!.reason, "data-2 (no entry in lenses)"); + for (const number of [1.5, Number.NaN, -1]) { + assert.include( + planLensStart({ ...input({}), prs: [{ number }] }).refused[0]!.reason, + "is not a pull request number", + ); + } + const many = Array.from({ length: 10 }, (_, i) => ({ number: i + 1, head: A })); + const long = lensRequestId(`o/${"r".repeat(240)}`, "code", many); + assert.isAtMost(long.length, 256); + assert.match(long, /^lens\/[0-9a-f]{64}$/u); + assert.notStrictEqual(lensRequestId(REPO, "\ud800", many), lensRequestId(REPO, "\ud801", many)); + assert.notStrictEqual(lensRequestId(REPO, "\ud800", many), lensRequestId(REPO, "�", many)); + }); +}); diff --git a/apps/server/src/fork/reviewRules/lensStart.ts b/apps/server/src/fork/reviewRules/lensStart.ts new file mode 100644 index 0000000000000..60d5eb261251f --- /dev/null +++ b/apps/server/src/fork/reviewRules/lensStart.ts @@ -0,0 +1,713 @@ +/** + * Fork: `lens_start` as pure logic: from what the caller read it plans the read-only lens children, or refuses; same + * input, same answer. It reads what the gate reads (head_check.decide, verdict, lens.Review.lens_reads), so when + * anything starts, every lens entry that does not name the head starts again there (the gate needs one head). + */ +// @effect-diagnostics-next-line nodeBuiltinImport:off -- the batch request id must be a deterministic digest. +import * as NodeCrypto from "node:crypto"; +import * as Schema from "effect/Schema"; + +import { type EffectiveReviewRules, type ReviewRunner, reviewLensRunner } from "@t3tools/contracts"; + +import { NO_HEADER, lensKey, lensScan, namesALens, type LensPost } from "./lensComment.ts"; +import { ReviewPlanError, planReview, type ReviewBlock, type ReviewPlan } from "./plan.ts"; +import { judgeRounds, type Rounds } from "./rounds.ts"; + +const isPlanError = Schema.is(ReviewPlanError); + +type OnRules = Extract; + +/** The most pull requests one call reads. */ +export const LENS_START_MAX_PRS = 10; +/** The longest request id `delegate_task` takes. */ +const REQUEST_ID_MAX = 256; +const SHA = /^[0-9a-f]{40}$/u; +const REPO = /^[A-Za-z0-9][A-Za-z0-9-]*\/[A-Za-z0-9._-]+$/u; +/** The preset's runner key for the approach lens's role (the "stuck in circles" audit). */ +const APPROACH_RUNNER = "approach"; + +const FALLBACK_APPROACH_LENS = "approach"; +const FALLBACK_PROMPT = "fallback:review"; +const FALLBACK_APPROACH_PROMPT = "fallback:approach"; +const FALLBACK_PROMPTS: Readonly> = { + [FALLBACK_PROMPT]: + "Review the whole change for correctness, data safety and security. Read the code the change " + + "touches and the code that calls it, not only the diff.", + [FALLBACK_APPROACH_PROMPT]: + "This pull request is in its third review round or later. Do not review line by line: judge " + + "whether its approach can reach a mergeable state, and name the simplest way that can.", +}; + +/** + * The rounds a repo without a `review` block is held to by T3 (the gate judges no rounds there): 3 / 4, and the + * approach lens from round 3. Its lenses are the gate's required-lenses input, each with the built-in prompt. + */ +export const FALLBACK_REVIEW: ReviewBlock = { + rules: [], + lenses: { [FALLBACK_APPROACH_LENS]: { prompt: FALLBACK_APPROACH_PROMPT } }, + rounds: { approach_at: 3, max: 4, approach_lens: FALLBACK_APPROACH_LENS }, + findings: true, + override_authors: [], +}; + +/** How a person clears an entry lens_start cannot start again (lens.py NO_HEADER_WAY_OUT, plus the override). */ +const NO_HEADER_WAY_OUT = + "delete that comment (hiding it is not enough), or edit it to start with `not a lens` and a colon and hold no " + + "lens header line and no sha on a line with a lens field, or"; + +/** One post in the gate's order: a lens comment of a counted author, or a valid override comment. */ +export interface LensStartPost extends LensPost { + /** + * The sha a valid override comment vouches for (lens.Review.override_sha: the override author association, never + * edited, not hidden), lower-case; absent on every other post. Any such override newer than a lens's entry covers + * it in the gate (lens_reads), a person's or not. + */ + readonly override?: string; +} + +/** One pull request as the caller read it from GitHub, its head first. */ +export interface LensStartPullRequest { + readonly number: number; + readonly state: "open" | "closed" | "merged"; + /** The head commit GitHub names now. */ + readonly head: string; + /** The branch it merges into: its rules plan it (`LensStartInput.bases`). */ + readonly base: string; + /** `git diff --name-status -M `, one [status, path] or [R|C, old, new] per line. */ + readonly changes: ReadonlyArray>; + /** The lens comments that count and the valid override comments, in the gate's order (lensComment.ts). */ + readonly posts: ReadonlyArray; + /** A person's override for this head is newer than every lens comment (the gate's `decided`). */ + readonly decided?: boolean; + /** What the pull request itself changes at a commit, so a read before a clean base merge still read the head. */ + readonly changeOf?: (sha: string) => string; +} + +/** What the gate reads at one base branch's tip. */ +export interface LensStartBase { + /** The `review` block of the config at the base; null: the config has none. */ + readonly review: ReviewBlock | null; + /** Each lens prompt file's text at the base, by its path in the config; a file not read is absent. */ + readonly prompts: Readonly>; + /** The gate caller's `required-lenses` input, one lens name per entry (blank ones skipped); null: not read. */ + readonly requiredLenses: ReadonlyArray | null; +} + +/** A lens child started earlier for this repo (T3b reads them by their `lens/` request ids). */ +export interface LensStartEarlierChild { + readonly requestId: string; + readonly key: string; + readonly prs: ReadonlyArray<{ readonly number: number; readonly head: string }>; + /** true: still running, so what it reads is returned, not started twice; false: it ended. */ + readonly running: boolean; +} + +export interface LensStartInput { + /** This project's effective review rules. */ + readonly rules: EffectiveReviewRules; + /** owner/name. */ + readonly repo: string; + /** What the gate reads at each base branch, by branch name. */ + readonly bases: ReadonlyMap; + readonly overridePrefix?: string; + /** The call: each pull request, and the head the caller expects it at, if it names one. */ + readonly prs: ReadonlyArray<{ readonly number: number; readonly head?: string }>; + /** What the caller read, by number; a pull request GitHub does not know is absent. */ + readonly pulls: ReadonlyMap; + /** The lens children started earlier; absent: none known. */ + readonly children?: ReadonlyArray; +} + +/** One pull request a child reads. `round` is the review round this read makes. */ +export interface LensStartRead { + readonly number: number; + readonly head: string; + readonly round: number; +} + +/** One read-only child to start through `delegate_task` (role `review`). */ +export interface LensStartChild { + /** The same lens on the same heads and attempt gives the same id: a second call returns the same task. */ + readonly requestId: string; + /** 1, or one more than the newest attempt whose child ended without the read (`replaces`). */ + readonly attempt: number; + /** The ids of earlier attempts that ended without the read; empty on a first attempt. */ + readonly replaces: ReadonlyArray; + /** The lens's name as the config (or the required-lenses input) writes it. */ + readonly lens: string; + readonly key: string; + readonly runner: ReviewRunner; + readonly title: string; + readonly prompt: string; + readonly prs: ReadonlyArray; +} + +export interface LensStartRefusal { + /** null: the whole call. */ + readonly pr: number | null; + readonly reason: string; +} + +export interface LensStartPlan { + readonly starts: ReadonlyArray; + /** Children still running that already read what this call needs: returned, never started twice. */ + readonly running: ReadonlyArray<{ + readonly requestId: string; + readonly key: string; + readonly prs: ReadonlyArray<{ readonly number: number; readonly head: string }>; + }>; + readonly refused: ReadonlyArray; + /** Required lenses the gate already counts as reading the head: not started again. */ + readonly alreadyRead: ReadonlyArray<{ readonly pr: number; readonly lens: string }>; + readonly notes: ReadonlyArray; +} + +const whole = (reason: string): LensStartPlan => ({ + starts: [], + running: [], + refused: [{ pr: null, reason }], + alreadyRead: [], + notes: [], +}); + +/** What the gate counts one lens entry as reading (lens.Review.lens_reads). */ +export interface GateRead { + /** The full sha it reads, or the newer override's; null: it reads nothing. */ + readonly sha: string | null; + /** The lens name of its newest header; null for a comment that reads nothing (a NO_HEADER entry). */ + readonly name: string | null; +} + +/** + * lens.Review.lens_reads on the posts: each lens key's newest entry, and what it reads. An override newer than an + * entry makes it read the override's sha; a NO_HEADER entry, an edited or hidden newest entry or a short sha reads + * nothing. + */ +export function gateReads( + posts: ReadonlyArray, + overridePrefix?: string, +): Map { + const entries = new Map(); + let newest: { at: number; sha: string } | null = null; + posts.forEach((post, i) => { + if (post.override !== undefined) { + if (SHA.test(post.override)) newest = { at: i, sha: post.override }; + return; + } + const one = lensScan([{ ...post, where: post.where ?? `post ${i + 1}` }], overridePrefix); + const name = one.history[0]?.[0] ?? null; + for (const [key, [sha]] of Object.entries(one.entries)) { + entries.set(key, { at: i, sha, name: key.startsWith(NO_HEADER) ? null : name }); + } + }); + const over = newest as { at: number; sha: string } | null; + const reads = new Map(); + for (const [key, { at, sha, name }] of entries) { + if (over !== null && at < over.at) reads.set(key, { sha: over.sha, name }); + else reads.set(key, { sha: sha !== null && SHA.test(sha) ? sha : null, name }); + } + return reads; +} + +/** + * The lens part of the gate's verdict (head_check.verdict): every required key has an entry, every entry reads one + * full sha, and that sha is the head or the same change. + */ +function gateReadsPass( + reads: ReadonlyMap, + required: Iterable, + head: string, + changeOf: (sha: string) => string = (sha) => sha, +): boolean { + const keys = [...required]; + if (reads.size === 0) return keys.length === 0; + if (keys.some((key) => !reads.has(key))) return false; + const shas = new Set([...reads.values()].map((r) => r.sha)); + if (shas.size !== 1) return false; + const [sha] = shas; + return sha !== null && sha !== undefined && (sha === head || changeOf(sha) === changeOf(head)); +} + +/** One lens a base knows how to start: its name, and its prompt (a config path, or a built-in one). */ +interface KnownLens { + readonly name: string; + readonly prompt: string; + readonly builtIn: boolean; + readonly approach: boolean; +} + +/** A required lens the config names but gives no `lenses` entry (the gate's parser refuses that config). */ +const NO_ENTRY: KnownLens = { name: "", prompt: "", builtIn: false, approach: false }; + +/** What one pull request needs: the lenses still to read its head, by key, or why it is refused. */ +type PullNeed = + | { readonly refused: string } + | { + readonly read: LensStartRead; + readonly need: ReadonlyArray; + readonly done: ReadonlyArray; + /** Each lens key's earlier reads, oldest first, each sha once. */ + readonly earlier: ReadonlyMap>; + readonly notes: ReadonlyArray; + }; + +function readPull( + rules: OnRules, + base: LensStartBase, + overridePrefix: string | undefined, + pull: LensStartPullRequest, +): PullNeed { + const head = pull.head.toLowerCase(); + if (pull.state !== "open") return { refused: `it is ${pull.state}: only an open one is read` }; + if (!SHA.test(head)) + return { refused: `its head ${JSON.stringify(pull.head)} is not a full sha` }; + // The gate's required-lenses input (head_check.required_names): one name per line, blank ones skipped. + if (base.requiredLenses === null) { + return { + refused: + `the gate's required-lenses input at ${pull.base} was not read: no lens is started rather than ` + + "too few", + }; + } + const named = new Map(); + for (const raw of base.requiredLenses) { + const name = raw.trim(); + if (name === "") continue; + if (!namesALens(name)) { + return { + refused: + `the gate's required-lenses input names no lens (${JSON.stringify(name)}), so the gate fails every ` + + "head: a person fixes the caller workflow", + }; + } + if (!named.has(lensKey(name))) named.set(lensKey(name), name); + } + const review = base.review; + if (review !== null && review.mode !== "shadow" && review.mode !== "enforce") { + return { + refused: + `the \`review\` block at ${pull.base} has mode ${JSON.stringify(review.mode ?? null)}, not shadow ` + + "or enforce, so the gate refuses its config: a person fixes the config", + }; + } + const enforce = review?.mode === "enforce"; + if (named.size === 0 && !enforce) { + return { + refused: + "the gate's required-lenses input names no lens and the config has no `review` block in mode " + + "enforce, so the gate fails every head: a person names the lenses in the caller workflow or the config", + }; + } + const block = review ?? FALLBACK_REVIEW; + let plan: ReviewPlan; + try { + plan = + review === null + ? { weight: "normal", lenses: [], hits: [], protected: [] } + : planReview(review, pull.changes, rules.configPath); + } catch (error) { + if (!isPlanError(error)) throw error; + return { refused: `no plan: ${error.reason}; no lens is started rather than too few` }; + } + const reads = gateReads(pull.posts, overridePrefix); + const { history } = lensScan( + pull.posts.flatMap((p) => (p.override === undefined ? [p] : [])), + overridePrefix, + ); + const rounds = startRounds(block, history, head, pull.changeOf); + // The lenses this base can start, by key: the config's, then the input's names (built-in prompt). + const approachKey = lensKey(block.rounds.approach_lens); + const known = new Map(); + for (const [name, { prompt }] of Object.entries(block.lenses)) { + const key = lensKey(name); + if (!known.has(key)) { + known.set(key, { + name, + prompt, + builtIn: review === null, + approach: key === approachKey, + }); + } + } + const notes: string[] = []; + const inputOnly: string[] = []; + for (const [key, name] of named) { + if (known.has(key)) continue; + known.set(key, { name, prompt: FALLBACK_PROMPT, builtIn: true, approach: key === approachKey }); + inputOnly.push(name); + } + if (review === null) { + notes.push( + `#${pull.number}: the config at ${pull.base} has no \`review\` block, so the gate requires only its ` + + `required-lenses input (${[...named.values()].join(", ")}), each read with a built-in prompt; T3 ` + + `holds it to rounds ${FALLBACK_REVIEW.rounds.approach_at} / ${FALLBACK_REVIEW.rounds.max}. T3 does ` + + "not guess critical paths: the repo's config names them", + ); + } else if (inputOnly.length > 0) { + notes.push( + `#${pull.number}: the gate's required-lenses input names ${inputOnly.join(", ")}, which the config's ` + + "lenses do not, so each is read with a built-in prompt", + ); + } + // What the gate requires (decide): the input, the path lenses in enforce; T3 adds the path lenses in shadow too + // (the trial the shadow mode is for) and the approach lens from its round. + const required = new Map(); + const add = (name: string) => { + const key = lensKey(name); + if (!required.has(key)) required.set(key, known.get(key)?.name ?? name); + }; + plan.lenses.forEach(add); + for (const name of named.values()) add(name); + if (pull.decided) { + // The gate requires no approach lens once a person decided (judgeRounds), but still every other one. + const missing = [...required].filter(([key]) => !reads.has(key)).map(([, name]) => name); + return { + refused: + "a person's override already lets this head through; no lens is started, because a new lens " + + "comment would be newer than the override and end it" + + (missing.length > 0 + ? `. The gate still misses lens ${missing.join(", ")}: an override adds no lens, so a person ` + + "decides how it is read" + : ""), + }; + } + if (rounds.approach) add(block.rounds.approach_lens); + const changeOf = pull.changeOf ?? ((sha: string) => sha); + const passes = gateReadsPass(reads, required.keys(), head, changeOf); + if (rounds.round > block.rounds.max) { + return { + refused: + `a read of this head would be review round ${rounds.round}, past the cap of ${block.rounds.max} ` + + "rounds: no more rounds; a person decides: close the pull request, or write an override comment", + }; + } + const done: string[] = []; + const need: Array = []; + if (passes) { + done.push(...required.values()); + } else { + // Something starts at the head, so every entry that does not name the head itself starts again too. + const stuck: string[] = []; + for (const [key, name] of required) { + if (reads.get(key)?.sha === head) done.push(name); + else need.push({ key, ...(known.get(key) ?? { ...NO_ENTRY, name }) }); + } + for (const [key, read] of reads) { + if (required.has(key) || read.sha === head) continue; + const lens = known.get(key); + const said = read.sha === null ? "reads nothing" : `read ${read.sha}`; + if (lens !== undefined) { + need.push({ key, ...lens }); + notes.push( + `#${pull.number}: lens ${lens.name} is no longer required but ${said}, not this head; the gate ` + + "needs every lens comment to name one head, so it reads the head again", + ); + } else if (read.name === null) { + stuck.push(`a comment that reads nothing (${key}): ${NO_HEADER_WAY_OUT}`); + } else { + stuck.push( + `lens ${read.name} ${said}, and neither the config nor the required-lenses input names it, so ` + + "lens_start has no prompt for it: post that lens again at this head, delete its comment, or", + ); + } + } + if (stuck.length > 0) { + return { + refused: + "the gate needs every lens comment to name one head, and lens_start cannot start every lens " + + `that does not: ${stuck.map((s) => `${s} a person writes a newer override comment for this head`).join("; ")}`, + }; + } + } + const earlier = new Map(); + for (const [name, sha] of history) { + // A read of this very head that does not count (edited or hidden) is no earlier round. + if (sha === null || sha === head) continue; + const list = earlier.get(lensKey(name)) ?? []; + if (!list.includes(sha)) list.push(sha); + earlier.set(lensKey(name), list); + } + return { read: { number: pull.number, head, round: rounds.round }, need, done, earlier, notes }; +} + +/** + * The rounds as a read of `head` would make them, counted as the gate counts them: the reads so far + * plus one of this head, which is one more round only if no lens read that change yet. + */ +export function startRounds( + review: ReviewBlock, + history: ReadonlyArray, + head: string, + changeOf?: (sha: string) => string, +): Rounds { + return judgeRounds(review, [...history, ["lens_start", head]], {}, false, changeOf); +} + +const digest = (text: string, n: number) => + NodeCrypto.createHash("sha256").update(text).digest("hex").slice(0, n); + +/** The lens key in an id: URI-encoded; a name with a lone surrogate gets a digest mark no encoding can make. */ +function idKey(key: string): string { + if (key.isWellFormed()) return encodeURIComponent(key); + return `${encodeURIComponent(key.toWellFormed())}%!${digest(JSON.stringify(key), 16)}`; +} + +/** + * The request id of one lens child: `lens/#//` for one pull request; for a + * batch, a digest of its sorted `@` lines. The repo and heads are read lower-case, as GitHub + * does. The same lens on the same heads gives the same id; a moved head or another set of pull requests + * gives a new one. `attempt` (2, 3, ...) starts a lens again after its child ended without a report. + */ +export function lensRequestId( + repo: string, + key: string, + reads: ReadonlyArray>, + attempt = 1, +): string { + const lens = idKey(key); + const again = attempt > 1 ? `/again-${attempt}` : ""; + const owner = repo.toLowerCase(); + const sorted = reads + .map((r) => ({ number: r.number, head: r.head.toLowerCase() })) + .toSorted((a, b) => a.number - b.number); + const id = + sorted.length === 1 + ? `lens/${owner}#${sorted[0]!.number}/${sorted[0]!.head}/${lens}${again}` + : `lens/${owner}/batch-${digest(sorted.map((r) => `${r.number}@${r.head}`).join("\n"), 24)}/${lens}${again}`; + return id.length <= REQUEST_ID_MAX ? id : `lens/${digest(id, 64)}`; +} + +/** Who runs a lens: its own runner by key; else the approach lens's role runner for the config's approach lens. */ +function lensRunner(rules: OnRules, key: string, approach: boolean): ReviewRunner { + if (Object.hasOwn(rules.lensRunners, key)) return reviewLensRunner(rules, key); + return approach ? reviewLensRunner(rules, APPROACH_RUNNER) : rules.runner; +} + +/** The prompt the server gives one lens child; the agent never builds it. */ +function lensPrompt( + rules: OnRules, + repo: string, + lens: string, + lensText: string, + reads: ReadonlyArray }>, +): string { + const batch = reads.length > 1; + const lines = [ + `You are the \`${lens}\` review lens for ${batch ? "these pull requests" : "pull request"} of ${repo}. ` + + "Read only: change no file, commit, push or comment by hand.", + "", + ...reads.map((r) => { + const said = `- #${r.number} at head ${r.head}: review round ${r.round}.`; + if (r.earlier.length === 0) return `${said} This lens has not read it before.`; + return ( + `${said} This lens read it before at ${r.earlier.join(", ")}: check each earlier finding ` + + `first, then the changes since ${r.earlier.at(-1)}.` + ); + }), + "", + "## What this lens looks at", + "", + lensText.trim(), + "", + "## The state question", + "", + rules.stateQuestion, + "Answer it in a line starting `state:`.", + "", + "## Your report", + "", + batch + ? "Post one report per pull request with `lens_report`, each for that pull request's head above. " + + "Never one report for several." + : "Post your report with `lens_report`, for the head above.", + "Write one line per finding, starting `blocker:`, `major:` or `minor:`; write `blocker: none` and " + + "`major: none` when there is none.", + `Keep each report under ${rules.reportMaxChars} characters.`, + "If a head is not the one above when you read it, report nothing for it and say so in your answer.", + ]; + return lines.join("\n"); +} + +/** + * The plan for one `lens_start` call. Each pull request is planned or refused on its own, with its own base's + * rules, so one closed pull request in a batch does not stop the others. + */ +export function planLensStart(input: LensStartInput): LensStartPlan { + const { rules } = input; + if (rules.preset === "off") { + return whole( + "review rules are off for this project (Settings: review rules); lens_start starts nothing", + ); + } + if (!REPO.test(input.repo)) return whole(`${JSON.stringify(input.repo)} is not owner/name`); + if (input.prs.length === 0) return whole("name at least one pull request"); + const refused: LensStartRefusal[] = []; + const asked = new Map(); + for (const { number, head } of input.prs) { + if (!Number.isSafeInteger(number) || number < 1) { + return whole(`${JSON.stringify(number)} is not a pull request number`); + } + const said = head?.toLowerCase(); + if (asked.has(number) && asked.get(number) !== said) { + return whole(`#${number} is named twice with different heads`); + } + asked.set(number, said); + } + if (asked.size > LENS_START_MAX_PRS) { + return whole(`at most ${LENS_START_MAX_PRS} pull requests per call, not ${asked.size}`); + } + const alreadyRead: Array<{ pr: number; lens: string }> = []; + const notes: string[] = []; + const groups = new Map< + string, + { + key: string; + lens: KnownLens; + text: string; + runner: ReviewRunner; + reads: Array }>; + } + >(); + const children = input.children ?? []; + const running = new Map(); + for (const [number, expected] of asked) { + const pull = input.pulls.get(number); + if (pull === undefined) { + refused.push({ pr: number, reason: `${input.repo} has no pull request #${number}` }); + continue; + } + if (expected !== undefined && expected !== pull.head.toLowerCase()) { + refused.push({ + pr: number, + reason: `its head is ${pull.head}, not ${expected}: read the pull request again`, + }); + continue; + } + const base = input.bases.get(pull.base); + if (base === undefined) { + refused.push({ + pr: number, + reason: `its base branch ${pull.base} was not read: no lens is started rather than too few`, + }); + continue; + } + const got = readPull(rules, base, input.overridePrefix, pull); + if ("refused" in got) { + refused.push({ pr: number, reason: got.refused }); + continue; + } + for (const lens of got.done) alreadyRead.push({ pr: number, lens }); + const prompts = (lens: KnownLens) => (lens.builtIn ? FALLBACK_PROMPTS : base.prompts); + const missing = got.need.filter((lens) => !Object.hasOwn(prompts(lens), lens.prompt)); + if (missing.length > 0) { + refused.push({ + pr: number, + reason: + "no plan: the prompt of lens " + + `${missing.map((l) => `${l.name} (${l.prompt || "no entry in lenses"})`).join(", ")} could not be ` + + "read at the base", + }); + continue; + } + notes.push(...got.notes); + for (const lens of got.need) { + // A child still running that reads this lens on this head is returned, never started twice. + const busy = children.find( + (c) => + c.running && + c.key === lens.key && + c.prs.some((r) => r.number === number && r.head.toLowerCase() === got.read.head), + ); + if (busy !== undefined) { + running.set(busy.requestId, busy); + continue; + } + const text = prompts(lens)[lens.prompt]!; + const runner = lensRunner(rules, lens.key, lens.approach); + const id = JSON.stringify([lens.key, lens.name, text, runner]); + const group = groups.get(id) ?? { key: lens.key, lens, text, runner, reads: [] }; + group.reads.push({ ...got.read, earlier: got.earlier.get(lens.key) ?? [] }); + groups.set(id, group); + } + } + const ended = new Set(children.filter((c) => !c.running).map((c) => c.requestId)); + const starts = [...groups.values()].map(({ key, lens, text, runner, reads }): LensStartChild => { + const prs = reads.map(({ number, head, round }) => ({ number, head, round })); + const which = prs.map((r) => `#${r.number}`).join(" "); + const replaces: string[] = []; + let attempt = 1; + for (;;) { + const id = lensRequestId(input.repo, key, prs, attempt); + if (!ended.has(id)) break; + replaces.push(id); + attempt++; + } + if (attempt > 1) { + notes.push( + `lens ${lens.name} for ${which}: the child ${replaces.at(-1)} ended without the read, so it ` + + `starts again as attempt ${attempt}`, + ); + } + return { + requestId: lensRequestId(input.repo, key, prs, attempt), + attempt, + replaces, + lens: lens.name, + key, + runner, + title: `lens ${lens.name} ${which}`, + prompt: lensPrompt(rules, input.repo, lens.name, text, reads), + prs, + }; + }); + return { + starts, + running: [...running.values()].map(({ requestId, key, prs }) => ({ requestId, key, prs })), + refused, + alreadyRead, + notes, + }; +} + +/** + * Just before the children start: the heads GitHub names now (null: the pull request is gone or no + * longer open). A child whose pull request moved or closed since the plan is refused whole, as its + * prompt names the old head; calling lens_start again plans the new head, and a child that started + * keeps its id, so it is returned, not started twice. + */ +export function confirmLensStart( + plan: LensStartPlan, + heads: ReadonlyMap, +): LensStartPlan { + const moved = new Map(); + for (const child of plan.starts) { + for (const r of child.prs) { + const now = heads.get(r.number); + if (now === undefined || now === null) { + moved.set(r.number, "it is no longer open since the plan; nothing is started for it"); + } else if (now.toLowerCase() !== r.head) { + moved.set( + r.number, + `its head moved from ${r.head} to ${now.toLowerCase()} since the plan: call lens_start again`, + ); + } + } + } + if (moved.size === 0) return plan; + return { + ...plan, + starts: plan.starts.filter((child) => child.prs.every((r) => !moved.has(r.number))), + refused: [ + ...plan.refused, + ...[...moved].map(([pr, reason]) => ({ pr, reason })), + ...plan.starts + .filter((c) => c.prs.some((r) => moved.has(r.number)) && c.prs.length > 1) + .map((c) => ({ + pr: null, + reason: + `lens ${c.lens} for ${c.prs.map((r) => `#${r.number}`).join(" ")} is not started: a pull ` + + "request of its batch moved; call lens_start again", + })), + ], + }; +} diff --git a/apps/server/src/fork/reviewRules/plan.ts b/apps/server/src/fork/reviewRules/plan.ts index aa10d657bcdd1..5b3942c5b7863 100644 --- a/apps/server/src/fork/reviewRules/plan.ts +++ b/apps/server/src/fork/reviewRules/plan.ts @@ -11,6 +11,8 @@ const WEIGHTS: ReadonlyArray = ["critical", "normal", "light"]; /** A `review` block of the repo's pr-queue config, as the gate's parser accepts it. */ export interface ReviewBlock { + /** shadow: the gate requires only its required-lenses input; enforce: the path rules' lenses join it. */ + readonly mode?: "shadow" | "enforce"; readonly rules: ReadonlyArray<{ readonly name: string; readonly weight: ReviewWeight;