dw-sdlc 0.7.0 → 0.10.0

package/dist/pr/decide.d.ts

@@ -1,10 +1,31 @@
-import type { PrMerge } from "../agentic-config.ts";
-import type { PrState } from "./state.ts";
+import type { PrMerge, PrReview, ReviewDepth } from "../agentic-config.ts";
+import { type PrState, REVIEW } from "./state.ts";
+export { REVIEW };
 export type Status = "act" | "wait" | "park" | "done";
 export type Actor = "script" | "agent" | "dev";
-export type Action = "done" | "stop" | "wait" | "fix-conflicts" | "update-branch" | "fix-ci" | "address-review" | "review" | "unverified" | "ci-stuck" | "awaiting-reply" | "mark-ready" | "awaiting-approval" | "ready-to-merge" | "merge";
+export type Action = "done" | "stop" | "wait" | "fix-conflicts" | "update-branch" | "fix-ci" | "address-review" | "review" | "mark-reviewed" | "unverified" | "ci-stuck" | "awaiting-reply" | "mark-ready" | "awaiting-author" | "awaiting-approval" | "ready-to-merge" | "merge";
 /** The Actions the script performs itself, each one gh command. */
-export type ScriptAction = "update-branch" | "mark-ready" | "merge";
+export type ScriptAction = "update-branch" | "mark-ready" | "mark-reviewed" | "merge";
+/**
+ * Where a Review depth comes from: the dev's `--review` for this call, a depth `pr.review` sets, or the
+ * rules `pr.review: auto` routes it by.
+ */
+export type DepthSource = "flag" | "config" | "auto";
+/**
+ * What the decision reads beside the pull request: who merges it, how closely a Review reads it, the
+ * dev's word or `pr.review`, and the slash command a `full` Review runs.
+ */
+export type Policy = {
+    merge: PrMerge;
+    review: {
+        depth: ReviewDepth;
+        source: "flag";
+    } | {
+        depth: PrReview;
+        source: "config";
+    };
+    reviewCommand: string;
+};
 /** An Action the pull request needs beside the one its answer names, so one push can fix several. */
 export type Blocker = {
     action: Action;
@@ -20,17 +41,24 @@ export type Answer = Blocker & {
     recheckAfter?: number;
     blockers: Blocker[];
 };
+/** Its one state: a failure or a pending status would turn the pull request unstable. */
+export declare const REVIEW_STATE = "success";
 /** The words as one POSIX shell command line, each word that needs it single-quoted. */
 export declare function shellLine(words: string[]): string;
+/**
+ * The gh arguments that post the `dw-sdlc/review` success on the head, `description` saying how it was
+ * read. The path names the repository, so the call reads the same from any checkout.
+ */
+export declare function reviewStatusArgs(pr: PrState, description: string): string[];
 export declare function isScriptAction(action: Action): action is ScriptAction;
 /**
  * The gh arguments of a script Action, `-R` naming the repository when `named`. The update merges the
  * base in, never --rebase, which rewrites the branch on GitHub; the merge names the head it read.
  */
-export declare function hostArgs(pr: PrState, action: ScriptAction, named: boolean): string[];
+export declare function hostArgs(pr: PrState, action: ScriptAction, policy: Policy, named: boolean): string[];
 /** The command a script Action leaves the dev to run, from a checkout of the repository. */
-export declare function devCommand(pr: PrState, action: ScriptAction): string;
+export declare function devCommand(pr: PrState, action: ScriptAction, policy: Policy): string;
 /** The merge left to the dev, `reason` saying why it is theirs. */
-export declare function readyToMerge(pr: PrState, reason: string): Omit<Answer, "blockers">;
-/** The Action `pr` needs at `now`, milliseconds since the epoch, when `merge` says who merges it. */
-export declare function decide(pr: PrState, now: number, merge: PrMerge): Answer;
+export declare function readyToMerge(pr: PrState, policy: Policy, reason: string): Omit<Answer, "blockers">;
+/** The Action `pr` needs at `now`, milliseconds since the epoch, under `policy`. */
+export declare function decide(pr: PrState, now: number, policy: Policy): Answer;

package/dist/pr/decide.js

@@ -1,14 +1,17 @@
 // The decision of the Ship script: one ordered list of rows, and the first row whose `when` holds for
 // the pull request answers its Action at the time given; every later row that holds rides in its
 // blockers. The last rows say who merges what no row before them holds back.
+import { route } from "./route.js";
+import { awaitsReview, OFF_PREFIX, REVIEW } from "./state.js";
+export { REVIEW };
 /** How long a head may carry no check before it parks as unverified, from its commit. */
 const GRACE_SECONDS = 120;
 /** How long CI may stay pending before it parks as stuck, from the first start among the pending checks. */
 const BUDGET_MINUTES = 40;
 /** The prefix of the contexts the script posts itself, as `dw-sdlc/review`: never CI. */
 const OWN_PREFIX = "dw-sdlc/";
-/** The commit status a clean review of the head leaves on it. */
-const REVIEW = "dw-sdlc/review";
+/** Its one state: a failure or a pending status would turn the pull request unstable. */
+export const REVIEW_STATE = "success";
 /** The words as one POSIX shell command line, each word that needs it single-quoted. */
 export function shellLine(words) {
     return words.map((word) => (/^[\w./:=@%+,-]+$/.test(word) ? word : `'${word.replaceAll("'", `'\\''`)}'`)).join(" ");
@@ -33,10 +36,59 @@ function threads(pr, lastByViewer) {
 function listed({ id, path, line, author, body }) {
     return { id, path, line, author, body };
 }
+/**
+ * The gh arguments that post the `dw-sdlc/review` success on the head, `description` saying how it was
+ * read. The path names the repository, so the call reads the same from any checkout.
+ */
+export function reviewStatusArgs(pr, description) {
+    const fields = { state: REVIEW_STATE, context: REVIEW, target_url: pr.url, description };
+    const flags = Object.entries(fields).flatMap(([key, value]) => ["-f", `${key}=${value}`]);
+    return ["api", `repos/${pr.repo}/statuses/${pr.head}`, "--method", "POST", "--silent", ...flags];
+}
+/** Whether the dev named a depth for a head that would carry the status: their word beats the carry. */
+function flagOverCarry(pr, { review }) {
+    return pr.carried && review.source === "flag";
+}
+/** The reviewed commit whose success the head carries, if it does and the dev named no depth. */
+function carriedFrom(pr, policy) {
+    return pr.carried && !flagOverCarry(pr, policy) ? (pr.lastReviewed?.commit ?? null) : null;
+}
+/**
+ * The commit the Review reads from: the last reviewed one. Over a carry the dev's depth reads the whole
+ * diff, since the changes after that commit are only the base's.
+ */
+function sinceOf(pr, policy) {
+    return flagOverCarry(pr, policy) ? null : (pr.lastReviewed?.commit ?? null);
+}
+/** The depth a Review reads the head at: the dev's or the one `pr.review` sets, else the one the rules route. */
+function depthOf(pr, { review }) {
+    const { depth, source } = review;
+    if (depth === "off") {
+        return { depth, source, why: source === "flag" ? "--review off" : "pr.review" };
+    }
+    if (depth !== "auto") {
+        return { depth, source };
+    }
+    return { ...route(pr.changed), source: "auto" };
+}
+/** Why the head carries the success the script posts: the Review it carries, else why its depth is off. */
+function markedDescription(pr, policy) {
+    const carried = carriedFrom(pr, policy);
+    if (carried !== null) {
+        return `carried from ${carried.slice(0, 7)}`;
+    }
+    const depth = depthOf(pr, policy);
+    if (depth.depth !== "off") {
+        throw new Error(`the script marks ${pr.url} reviewed at ${depth.depth}, neither off nor a carry`);
+    }
+    return `${OFF_PREFIX} ${depth.why}`;
+}
+/** A script Action's gh arguments; `repo` is `-R` and the repository when the call names it, else empty. */
 const HOST = {
-    "update-branch": { verb: "update-branch", flags: () => [] },
-    "mark-ready": { verb: "ready", flags: () => [] },
-    merge: { verb: "merge", flags: (pr) => ["--squash", "--match-head-commit", pr.head] }
+    "update-branch": (pr, repo) => ["pr", "update-branch", String(pr.number), ...repo],
+    "mark-ready": (pr, repo) => ["pr", "ready", String(pr.number), ...repo],
+    "mark-reviewed": (pr, _, policy) => reviewStatusArgs(pr, markedDescription(pr, policy)),
+    merge: (pr, repo) => ["pr", "merge", String(pr.number), ...repo, "--squash", "--match-head-commit", pr.head]
 };
 export function isScriptAction(action) {
     return Object.hasOwn(HOST, action);
@@ -45,17 +97,16 @@ export function isScriptAction(action) {
  * The gh arguments of a script Action, `-R` naming the repository when `named`. The update merges the
  * base in, never --rebase, which rewrites the branch on GitHub; the merge names the head it read.
  */
-export function hostArgs(pr, action, named) {
-    const { verb, flags } = HOST[action];
-    return ["pr", verb, String(pr.number), ...(named ? ["-R", pr.repo] : []), ...flags(pr)];
+export function hostArgs(pr, action, policy, named) {
+    return HOST[action](pr, named ? ["-R", pr.repo] : [], policy);
 }
 /** The command a script Action leaves the dev to run, from a checkout of the repository. */
-export function devCommand(pr, action) {
-    return shellLine(["gh", ...hostArgs(pr, action, false)]);
+export function devCommand(pr, action, policy) {
+    return shellLine(["gh", ...hostArgs(pr, action, policy, false)]);
 }
 /** The merge left to the dev, `reason` saying why it is theirs. */
-export function readyToMerge(pr, reason) {
-    return { status: "park", action: "ready-to-merge", actor: "dev", reason, command: devCommand(pr, "merge") };
+export function readyToMerge(pr, policy, reason) {
+    return { status: "park", action: "ready-to-merge", actor: "dev", reason, command: devCommand(pr, "merge", policy) };
 }
 const ROWS = [
     {
@@ -125,24 +176,42 @@ const ROWS = [
         answer: () => ({ status: "act", action: "address-review", actor: "agent", reason: "changes requested" })
     },
     {
-        when: (pr) => !pr.checks.some((check) => check.name === REVIEW && check.bucket === "pass"),
-        answer: (pr) => ({
-            status: "act",
-            action: "review",
-            actor: "agent",
-            reason: `no ${REVIEW} success on ${pr.head.slice(0, 7)}`
-        })
+        // Another author's pull request needs no Review: the dev merges it. The script posts the success
+        // under off, and over a carry, which reads at no depth.
+        when: awaitsReview,
+        answer: (pr, _, policy) => {
+            const since = sinceOf(pr, policy);
+            const head = { status: "act", reason: `no ${REVIEW} success on ${pr.head.slice(0, 7)}` };
+            const after = since === null ? {} : { since };
+            if (carriedFrom(pr, policy) !== null) {
+                return { ...head, action: "mark-reviewed", actor: "script", details: after };
+            }
+            const { depth, source } = depthOf(pr, policy);
+            const byScript = depth === "off";
+            return {
+                ...head,
+                action: byScript ? "mark-reviewed" : "review",
+                actor: byScript ? "script" : "agent",
+                details: {
+                    depth,
+                    source,
+                    // The agent may raise a routed depth to full, so auto names the command at any depth.
+                    ...(depth === "full" || source === "auto" ? { reviewCommand: policy.reviewCommand } : {}),
+                    ...after
+                }
+            };
+        }
     },
     {
         when: (pr) => ciOf(pr).length === 0,
-        answer: (pr, now) => now - Date.parse(pr.headCommittedAt) <= GRACE_SECONDS * 1000
+        answer: (pr, now, policy) => now - Date.parse(pr.headCommittedAt) <= GRACE_SECONDS * 1000
             ? { status: "wait", action: "wait", actor: "script", reason: "unverified", recheckAfter: 15 }
             : {
                 status: "park",
                 action: "unverified",
                 actor: "dev",
                 reason: `no check reported on ${pr.head.slice(0, 7)} within ${GRACE_SECONDS} s of its commit`,
-                command: devCommand(pr, "merge")
+                command: devCommand(pr, "merge", policy)
             }
     },
     {
@@ -173,9 +242,18 @@ const ROWS = [
         })
     },
     {
-        when: (pr) => pr.draft,
+        when: (pr) => pr.draft && pr.viewerDidAuthor,
         answer: () => ({ status: "act", action: "mark-ready", actor: "script", reason: "still a draft" })
     },
+    {
+        when: (pr) => pr.draft && !pr.viewerDidAuthor,
+        answer: () => ({
+            status: "park",
+            action: "awaiting-author",
+            actor: "dev",
+            reason: "another author's draft: marking it ready is the author's"
+        })
+    },
     {
         when: (pr) => pr.reviewDecision === "REVIEW_REQUIRED",
         answer: () => ({
@@ -187,30 +265,33 @@ const ROWS = [
     },
     {
         when: (pr) => !pr.viewerDidAuthor,
-        answer: (pr) => readyToMerge(pr, "another author's pull request: the merge is the dev's"),
+        answer: (pr, _, policy) => readyToMerge(pr, policy, "another author's pull request: the merge is the dev's"),
         merging: true
     },
     {
-        when: (_, merge) => merge === "auto",
+        when: (_, { merge }) => merge === "auto",
         answer: () => ({ status: "act", action: "merge", actor: "script", reason: "green, reviewed and the viewer's own" }),
         merging: true
     },
     {
-        when: (_, merge) => merge === "ask",
-        answer: (pr) => readyToMerge(pr, "pr.merge is ask: the merge is the dev's"),
+        when: (_, { merge }) => merge === "ask",
+        answer: (pr, _, policy) => readyToMerge(pr, policy, "pr.merge is ask: the merge is the dev's"),
         merging: true
     }
 ];
 function blockerOf({ action, actor, reason, details }) {
     return { action, actor, reason, ...(details === undefined ? {} : { details }) };
 }
-/** The Action `pr` needs at `now`, milliseconds since the epoch, when `merge` says who merges it. */
-export function decide(pr, now, merge) {
-    const index = ROWS.findIndex((row) => row.when(pr, merge));
+/** The Action `pr` needs at `now`, milliseconds since the epoch, under `policy`. */
+export function decide(pr, now, policy) {
+    const index = ROWS.findIndex((row) => row.when(pr, policy));
     const row = ROWS[index];
     if (row === undefined) {
-        throw new Error(`no row of the decision matches ${pr.url} under pr.merge ${merge}`);
+        throw new Error(`no row of the decision matches ${pr.url} under pr.merge ${policy.merge}`);
     }
-    const later = row.alone === true ? [] : ROWS.slice(index + 1).filter((other) => !other.merging && other.when(pr, merge));
-    return { ...row.answer(pr, now), blockers: later.map((other) => blockerOf(other.answer(pr, now))) };
+    const later = row.alone === true ? [] : ROWS.slice(index + 1).filter((other) => !other.merging && other.when(pr, policy));
+    return {
+        ...row.answer(pr, now, policy),
+        blockers: later.map((other) => blockerOf(other.answer(pr, now, policy)))
+    };
 }

package/dist/pr/delta.d.ts

@@ -0,0 +1,11 @@
+import { type ChangedFile } from "./state.ts";
+/** The gh arguments of the compare from `from` to `commit`, the files on its one page. */
+export declare function compareArgs(repo: string, from: string, commit: string): string[];
+/** How many commits of the compare's base its head lacks: 0 when the head carries all of it. */
+export declare function behindOf(reply: string): number;
+/** The own changes a compare reply lists, file by file; null when it cannot show them whole. */
+export declare function changesOf(reply: string): string[] | null;
+/** The files a compare reply lists with their changed lines; `unsized` when it may hold some back. */
+export declare function changedOf(reply: string): ChangedFile[] | "unsized";
+/** Whether the own changes at the head are those at the reviewed commit; unknown changes never are. */
+export declare function sameChanges(then: string[] | null, now: string[] | null): boolean;

package/dist/pr/delta.js

@@ -0,0 +1,60 @@
+// GitHub's compare of two commits, read two ways: whether a head carries the Review of an earlier commit,
+// the pull request's own changes from the base the same at both, since a merge of the base in adds none
+// of its own; and the files a Review would read, with their changed lines, for `pr.review: auto`.
+import { fieldOf, integer, object, ReplyError, rootOf, shown, string } from "./state.js";
+/** GitHub's compare lists at most this many files; one that lists as many may hold back the rest. */
+const FILE_LIMIT = 300;
+/** The gh arguments of the compare from `from` to `commit`, the files on its one page. */
+export function compareArgs(repo, from, commit) {
+    return ["api", `repos/${repo}/compare/${from}...${commit}?per_page=1`];
+}
+/** The files a compare reply lists. */
+function filesOf(reply) {
+    const { value, at } = fieldOf(rootOf(reply, "the compare"), "files");
+    if (!Array.isArray(value)) {
+        throw new ReplyError(`${at} is ${shown(value)}, not a list`);
+    }
+    return value.map((item, index) => object(item, `${at}[${index}]`));
+}
+/** How many commits of the compare's base its head lacks: 0 when the head carries all of it. */
+export function behindOf(reply) {
+    return integer(rootOf(reply, "the compare"), "behind_by");
+}
+/** A field the compare may leave out, as a file's patch or its previous name. */
+function optional(file, key) {
+    return file.value[key] === undefined || file.value[key] === null ? null : string(file, key);
+}
+/**
+ * A file's own change: its status, its names and the lines its patch adds and removes, in order,
+ * without the hunk headers and context a moved base shifts; null when the compare shows no patch.
+ */
+function changeOf(file) {
+    const names = [string(file, "filename"), string(file, "status"), optional(file, "previous_filename")];
+    const patch = optional(file, "patch");
+    if (patch === null) {
+        return null;
+    }
+    return JSON.stringify([...names, patch.split("\n").filter((line) => /^[-+\\]/.test(line))]);
+}
+/** The own changes a compare reply lists, file by file; null when it cannot show them whole. */
+export function changesOf(reply) {
+    const changes = filesOf(reply).map(changeOf);
+    const whole = changes.filter((change) => change !== null);
+    return changes.length >= FILE_LIMIT || whole.length < changes.length ? null : whole;
+}
+/** The files a compare reply lists with their changed lines; `unsized` when it may hold some back. */
+export function changedOf(reply) {
+    const files = filesOf(reply).map((file) => ({
+        path: string(file, "filename"),
+        previous: optional(file, "previous_filename"),
+        lines: optional(file, "patch") === null ? null : integer(file, "additions") + integer(file, "deletions")
+    }));
+    return files.length >= FILE_LIMIT ? "unsized" : files;
+}
+/** Whether the own changes at the head are those at the reviewed commit; unknown changes never are. */
+export function sameChanges(then, now) {
+    if (then === null || now === null) {
+        return false;
+    }
+    return JSON.stringify(then.toSorted()) === JSON.stringify(now.toSorted());
+}

package/dist/pr/read.d.ts

@@ -18,7 +18,12 @@ export declare function gh(args: string[]): {
     stdout: string;
     stderr: string;
 };
-/** The state of the pull request `named`; `command`, as `pr ship`, names the call in a remedy. */
-export declare function read(named: Named, command: string): PrState;
+/**
+ * The state of the pull request `named`; `command`, as `pr ship`, names the call in a remedy. With
+ * `sized`, as `pr.review: auto` needs, the read sizes the changes a Review would read.
+ */
+export declare function read(named: Named, command: string, sized: boolean): PrState;
 /** The state of `pr` once more, after an action the script performed on it: the same pull request. */
-export declare function readAgain(pr: PrState): PrState;
+export declare function readAgain(pr: PrState, sized: boolean): PrState;
+/** Whether the head of `after` carries the base `before` read: the compare shows it behind by none. */
+export declare function carriesBase(before: PrState, after: PrState): boolean;

package/dist/pr/read.js

@@ -1,7 +1,9 @@
 // The read both pr commands make: gh as a child process, its auth on the host gh api reads from, the
-// pull request a command names, and that pull request's state from one GraphQL request.
+// pull request a command names, and that pull request's state from one GraphQL request, with the two
+// compares that tell whether its head carries an earlier Review and the one that sizes its changes.
 import { spawnSync } from "node:child_process";
-import { parsePr, parseView, QUERY, ReplyError } from "./state.js";
+import { behindOf, changedOf, changesOf, compareArgs, sameChanges } from "./delta.js";
+import { awaitsReview, parsePr, parseView, QUERY, ReplyError } from "./state.js";
 /** What stops a pr command before it answers: exit 2, the problem and its remedy on one line. */
 export class CannotRun extends Error {
     remedy;
@@ -74,22 +76,66 @@ function targetOf({ number, repo }, command) {
     }
     return parseOrCannotRun(() => parseView(view.stdout));
 }
-/** The state of the pull request `named`; `command`, as `pr ship`, names the call in a remedy. */
-export function read(named, command) {
+/**
+ * The state of the pull request `named`; `command`, as `pr ship`, names the call in a remedy. With
+ * `sized`, as `pr.review: auto` needs, the read sizes the changes a Review would read.
+ */
+export function read(named, command, sized) {
     // The host gh api reads from: an account on any other host has no say in this call.
     const host = process.env.GH_HOST?.trim() || "github.com";
     const auth = gh(["auth", "status", "--active", "--hostname", host]);
     if (auth.status !== 0) {
         throw new CannotRun(`gh auth status failed: ${authProblem(auth.stderr)}`, REMEDIES.auth);
     }
-    return query(targetOf(named, command));
+    return query(targetOf(named, command), sized);
 }
 /** The state of `pr` once more, after an action the script performed on it: the same pull request. */
-export function readAgain(pr) {
-    return query(pr);
+export function readAgain(pr, sized) {
+    return query(pr, sized);
 }
-/** The state of pull request `number` of `repo`, from one GraphQL request. */
-function query({ repo, number }) {
+/** The reply of the compare from `from` to `commit`; `what` names it when gh refuses it. */
+function compared(pr, from, commit, what) {
+    const reply = gh(compareArgs(pr.repo, from, commit));
+    if (reply.status !== 0) {
+        throw new CannotRun(`${pr.repo}#${pr.number}: ${what}: ${said(reply.stderr)}`, REMEDIES.read);
+    }
+    return reply.stdout;
+}
+/** Whether the head of `after` carries the base `before` read: the compare shows it behind by none. */
+export function carriesBase(before, after) {
+    const reply = compared(after, before.baseOid, after.head, `the compare with ${before.baseOid.slice(0, 7)}`);
+    return parseOrCannotRun(() => behindOf(reply)) === 0;
+}
+/** The own changes of `pr` at `commit`, from the compare with its base; null when it cannot show them whole. */
+function ownChanges(pr, commit) {
+    const reply = compared(pr, pr.baseOid, commit, `the compare with ${commit.slice(0, 7)}`);
+    return parseOrCannotRun(() => changesOf(reply));
+}
+/**
+ * `pr` and whether its head carries the last reviewed commit's status: only merges since it, and the
+ * same own changes at both. The compares run only when a Review awaits the head.
+ */
+function withCarried(pr) {
+    const last = pr.lastReviewed;
+    if (last === null || !last.mergesOnly || pr.state !== "OPEN" || !awaitsReview(pr)) {
+        return { ...pr, carried: false };
+    }
+    return { ...pr, carried: sameChanges(ownChanges(pr, last.commit), ownChanges(pr, pr.head)) };
+}
+/**
+ * `pr` and, when `sized` and a Review awaits a head that carries none, the files the Review would read:
+ * the compare from the last reviewed commit, else from the base, to the head.
+ */
+function withChanged(pr, sized) {
+    if (!sized || pr.carried || pr.state !== "OPEN" || !awaitsReview(pr)) {
+        return { ...pr, changed: null };
+    }
+    const from = pr.lastReviewed?.commit ?? pr.baseOid;
+    const reply = compared(pr, from, pr.head, `the compare of ${from.slice(0, 7)}...${pr.head.slice(0, 7)}`);
+    return { ...pr, changed: parseOrCannotRun(() => changedOf(reply)) };
+}
+/** The state of pull request `number` of `repo`, from one GraphQL request and the compares a Review needs. */
+function query({ repo, number }, sized) {
     const [owner = "", name = ""] = repo.split("/");
     const reply = gh([
         "api",
@@ -108,5 +154,5 @@ function query({ repo, number }) {
         const remedy = problem.startsWith("Could not resolve to a") ? REMEDIES.target : REMEDIES.read;
         throw new CannotRun(`${repo}#${number}: ${problem}`, remedy);
     }
-    return parseOrCannotRun(() => parsePr(reply.stdout, repo));
+    return withChanged(withCarried(parseOrCannotRun(() => parsePr(reply.stdout, repo))), sized);
 }

package/dist/pr/route.d.ts

@@ -0,0 +1,14 @@
+import type { ReviewDepth } from "../agentic-config.ts";
+import type { ChangedFile } from "./state.ts";
+/** A routed depth, and under off why no one reads the changes, as the status the script posts says. */
+export type Routed = {
+    depth: Exclude<ReviewDepth, "off">;
+} | {
+    depth: "off";
+    why: string;
+};
+/**
+ * The depth the rules route `changed` to. A change not read or not sized reads in full, as does a file
+ * outside lockfiles the compare shows no patch for.
+ */
+export declare function route(changed: ChangedFile[] | "unsized" | null): Routed;

package/dist/pr/route.js

@@ -0,0 +1,52 @@
+// The built-in rules `pr.review: auto` routes a Review depth by, from the files the Review would read:
+// lockfiles alone are off; a workflow file, more than 100 changed lines outside lockfiles, or a change
+// the compare cannot size is full; the rest is light. No config key moves them.
+/** The lockfiles a package manager writes, by file name in any directory. */
+const LOCKFILES = new Set([
+    "pnpm-lock.yaml",
+    "package-lock.json",
+    "npm-shrinkwrap.json",
+    "yarn.lock",
+    "bun.lock",
+    "bun.lockb",
+    "Gemfile.lock",
+    "Cargo.lock",
+    "poetry.lock",
+    "uv.lock",
+    "Pipfile.lock",
+    "composer.lock",
+    "go.sum",
+    "Podfile.lock",
+    "pubspec.lock",
+    "mix.lock",
+    "flake.lock"
+]);
+/** Where GitHub Actions reads its workflows: a change there runs with the repository's secrets. */
+const WORKFLOWS = ".github/workflows/";
+/** The most changed lines outside lockfiles a light Review reads. */
+const LINE_LIMIT = 100;
+function isLockfile(path) {
+    return LOCKFILES.has(path.slice(path.lastIndexOf("/") + 1));
+}
+function isWorkflow({ path, previous }) {
+    return [path, previous].some((name) => name?.startsWith(WORKFLOWS) === true);
+}
+/**
+ * The depth the rules route `changed` to. A change not read or not sized reads in full, as does a file
+ * outside lockfiles the compare shows no patch for.
+ */
+export function route(changed) {
+    if (changed === null || changed === "unsized") {
+        return { depth: "full" };
+    }
+    const code = changed.filter((file) => !isLockfile(file.path));
+    if (changed.length > 0 && code.length === 0) {
+        return { depth: "off", why: "lockfiles only" };
+    }
+    const lines = code.map((file) => file.lines);
+    if (changed.some(isWorkflow) || lines.includes(null)) {
+        return { depth: "full" };
+    }
+    const total = lines.reduce((sum, count) => sum + (count ?? 0), 0);
+    return { depth: total > LINE_LIMIT ? "full" : "light" };
+}

package/dist/pr/state.d.ts

@@ -1,4 +1,8 @@
-export declare const QUERY = "query($owner: String!, $name: String!, $number: Int!) {\n  repository(owner: $owner, name: $name) {\n    pullRequest(number: $number) {\n      url number state isDraft mergeable mergeStateStatus reviewDecision headRefOid headRefName baseRefName\n      viewerDidAuthor mergeCommit { oid }\n      reviewThreads(first: 100) { nodes { id isResolved isOutdated path line\n        comments(first: 1) { nodes { author { login } body } }\n        latest: comments(last: 1) { nodes { viewerDidAuthor } } } }\n      commits(last: 1) { nodes { commit { committedDate statusCheckRollup {\n        contexts(first: 50) { nodes {\n          ... on CheckRun { name status conclusion detailsUrl startedAt isRequired(pullRequestNumber: $number) }\n          ... on StatusContext { context state targetUrl createdAt isRequired(pullRequestNumber: $number) } } } } } } }\n    }\n  }\n}";
+/** The commit status a clean review of the head leaves on it. */
+export declare const REVIEW = "dw-sdlc/review";
+/** How the description of a success the script posts under off begins: no one read that head. */
+export declare const OFF_PREFIX = "off:";
+export declare const QUERY = "query($owner: String!, $name: String!, $number: Int!) {\n  repository(owner: $owner, name: $name) {\n    pullRequest(number: $number) {\n      url number state isDraft mergeable mergeStateStatus reviewDecision headRefOid headRefName baseRefName baseRefOid\n      viewerDidAuthor mergeCommit { oid }\n      reviewThreads(first: 100) { nodes { id isResolved isOutdated path line\n        comments(first: 1) { nodes { author { login } body } }\n        latest: comments(last: 1) { nodes { viewerDidAuthor } } } }\n      commits(last: 1) { nodes { commit { committedDate statusCheckRollup {\n        contexts(first: 50) { nodes {\n          ... on CheckRun { name status conclusion detailsUrl startedAt isRequired(pullRequestNumber: $number) }\n          ... on StatusContext { context state targetUrl createdAt isRequired(pullRequestNumber: $number) } } } } } } }\n      history: commits(last: 100) { nodes { commit { oid parents { totalCount } status { context(name: \"dw-sdlc/review\") { state description } } } } }\n    }\n  }\n}";
 export type Bucket = "pass" | "fail" | "pending" | "skipping";
 export type CiCheck = {
     name: string;
@@ -36,19 +40,61 @@ export type PrState = {
     headCommittedAt: string;
     branch: string;
     base: string;
+    /** The commit the base branch points at. */
+    baseOid: string;
     mergeCommit: string | null;
     checks: CiCheck[];
     /** The threads neither resolved nor outdated. */
     unresolvedThreads: Thread[];
+    /** The last commit before the head with a review success not posted under off, of the last 100. */
+    lastReviewed: LastReviewed | null;
+    /** Whether the head carries the success of `lastReviewed`: the read decides it from two compares. */
+    carried: boolean;
+    /**
+     * The files a Review would read, from `lastReviewed` or the base to the head, read only for `pr.review:
+     * auto` to route on: `unsized` when the compare cannot list them all, null when not read.
+     */
+    changed: ChangedFile[] | "unsized" | null;
+};
+/**
+ * A file a Review would read: its name, its name before a rename, and the lines it adds and removes,
+ * null when the compare shows no patch for it, as for a binary file.
+ */
+export type ChangedFile = {
+    path: string;
+    previous: string | null;
+    lines: number | null;
+};
+/** A reviewed commit, and whether every commit after it, the head included, is a merge. */
+export type LastReviewed = {
+    commit: string;
+    mergesOnly: boolean;
 };
 /** A reply that is not the shape the query asks for; the message names the field. */
 export declare class ReplyError extends Error {
 }
+/** A JSON object of the reply and the path that reached it, as `data.repository.pullRequest`. */
+export type Node = {
+    value: Record<string, unknown>;
+    at: string;
+};
+export declare function shown(value: unknown): string;
+/** The JSON object `reply` holds, the root its fields' paths start from; `what` names it in a problem. */
+export declare function rootOf(reply: string, what: string): Node;
+export declare function fieldOf(node: Node, key: string): {
+    value: unknown;
+    at: string;
+};
+export declare function object(value: unknown, at: string): Node;
+export declare function string(node: Node, key: string): string;
+export declare function integer(node: Node, key: string): number;
+/** The viewer's own pull request without a review success on its head: the one a Review reads. */
+export declare function awaitsReview(pr: Pick<PrState, "viewerDidAuthor" | "checks">): boolean;
 /** The repository and number of the pull request whose URL `gh pr view --json url` printed. */
 export declare function parseView(reply: string): {
     repo: string;
     number: number;
 };
 /** The state of the pull request in `reply`, the text `gh api graphql` printed for QUERY on `repo`. */
-export declare function parsePr(reply: string, repo: string): PrState;
+export declare function parsePr(reply: string, repo: string): Omit<PrState, "carried" | "changed">;
 export {};