dw-sdlc 0.21.0 → 0.21.1

package/dist/pr/standing.js

@@ -0,0 +1,181 @@
+// The Review's standing at a pull request's head: what the Reviews before it read, from the review status
+// each commit carries and the commits force pushes left behind; what the head carries of them; what the
+// next Review reads, through a port onto GitHub's compares; and so the Review the head gets.
+import { route } from "./route.js";
+/**
+ * How many Reviews that each left a Finding open, with no success between them, the script lets run: the
+ * next call parks the pull request for the dev. A constant, like the depth rules, so no repository turns
+ * the loop back on.
+ */
+const REVIEW_LIMIT = 3;
+/** A change as a key, equal exactly when the two changes are. */
+function keyOf({ path, status, previous, lines }) {
+    return JSON.stringify([path, status, previous, lines]);
+}
+/** Whether the own changes at the head are those at the reviewed commit; unknown changes never are. */
+function sameChanges(then, now) {
+    if (then === null || now === null) {
+        return false;
+    }
+    return JSON.stringify(then.map(keyOf).toSorted()) === JSON.stringify(now.map(keyOf).toSorted());
+}
+/**
+ * The files whose own change differs between `before` and `after`, a rename under both names; null when a
+ * compare cannot show either whole.
+ */
+function movedFiles(before, after) {
+    if (before === null || after === null) {
+        return null;
+    }
+    const was = new Set(before.map(keyOf));
+    const is = new Set(after.map(keyOf));
+    const moved = [
+        ...after.filter((change) => !was.has(keyOf(change))),
+        ...before.filter((change) => !is.has(keyOf(change)))
+    ];
+    const names = moved.flatMap(({ path, previous }) => (previous === null ? [path] : [path, previous]));
+    return [...new Set(names)].toSorted();
+}
+/**
+ * The last commit before the head a Review read, a success under off passed over, or `open`: a read mark
+ * on the head, or one with only merges after it. No fix answers its Findings, so no read stands in.
+ */
+function lastReadOf({ commits, head }) {
+    if (commits.some(({ oid, posted }) => oid === head && posted === "findings")) {
+        return { lastRead: null, open: head };
+    }
+    const index = commits.findLastIndex(({ oid, posted }) => oid !== head && (posted === "clean" || posted === "findings"));
+    const last = commits[index];
+    if (last === undefined) {
+        return { lastRead: null, open: null };
+    }
+    const after = commits.slice(index + 1);
+    const baseOnly = after.every(({ merge }) => merge);
+    if (last.posted === "findings" && baseOnly) {
+        return { lastRead: null, open: last.oid };
+    }
+    const baseMoved = after.some(({ merge }) => merge);
+    return { lastRead: { commit: last.oid, clean: last.posted === "clean", baseOnly, baseMoved }, open: null };
+}
+/** The newest commit force pushes left behind that a Review read: a rebase moved the base under it. */
+function leftBehindRead({ leftBehind }) {
+    const read = leftBehind.find(({ posted }) => posted === "clean" || posted === "findings");
+    return read === undefined
+        ? null
+        : { commit: read.oid, clean: read.posted === "clean", baseOnly: true, baseMoved: true };
+}
+/**
+ * A read mark a force push left behind and posted after every read of the history: the Review the head
+ * needs reads from it, not from the history's last read, whose clean status no longer stands.
+ */
+function leftBehindMark(history) {
+    const newest = inPostedOrder(history).findLast(({ posted }) => posted === "clean" || posted === "findings");
+    if (newest?.posted !== "findings" || history.commits.some(({ oid }) => oid === newest.oid)) {
+        return null;
+    }
+    return { commit: newest.oid, clean: false, baseOnly: true, baseMoved: true };
+}
+/**
+ * The read mark `read` left open, no fix showing after it (ADR 0023): no change since it after the branch's
+ * own commits alone, else the same own changes at both commits or a compare that cannot show them whole.
+ * Null for any other read.
+ */
+function openAt(read, { changed }, own, head) {
+    if (read === null || read.clean) {
+        return null;
+    }
+    if (!read.baseMoved) {
+        const since = changed(read.commit, head);
+        return since !== "unsized" && since.length === 0 ? read.commit : null;
+    }
+    const atRead = own(read.commit);
+    const atHead = own(head);
+    return atRead !== null && atHead !== null && !sameChanges(atRead, atHead) ? null : read.commit;
+}
+/** Whether a commit carries a review success of any kind. */
+function isSuccess({ posted }) {
+    return posted === "clean" || posted === "off";
+}
+/** How many of `marked` carry a read mark. */
+function findings(marked) {
+    return marked.filter(({ posted }) => posted === "findings").length;
+}
+/**
+ * The commits in the order their review statuses were posted: each line a force push left behind just
+ * after the commit of the history it was pushed on, older pushes first, and a line that holds none of
+ * the history before all of it.
+ */
+function inPostedOrder({ commits, leftBehind }) {
+    const oldestFirst = leftBehind.toReversed();
+    const pushedOn = (index) => oldestFirst.filter(({ forksAt }) => forksAt === index);
+    return [...pushedOn(-1), ...commits.flatMap((commit, index) => [commit, ...pushedOn(index)])];
+}
+/** The read marks posted after the last success, of the history and of the commits force pushes left behind. */
+function readMarksOf(history) {
+    const posted = inPostedOrder(history);
+    const success = posted.findLastIndex(isSuccess);
+    return { count: findings(posted.slice(success + 1)), since: posted[success]?.oid ?? null };
+}
+/**
+ * The standing at the head of `history`. The compares run only when a Review `awaits` the head, and the
+ * files that Review would read are read only when `sized`, as `pr.review: auto` routes on them.
+ */
+export function standingOf(history, compares, { awaits, sized }) {
+    const marks = readMarksOf(history);
+    const inHistory = lastReadOf(history);
+    const read = inHistory.open === null ? (leftBehindMark(history) ?? inHistory.lastRead ?? leftBehindRead(history)) : null;
+    if (!awaits) {
+        return { lastRead: read, open: inHistory.open, marks, carried: false, changed: null, scope: null };
+    }
+    const { head, base } = history;
+    const own = (commit) => compares.ownChanges(base, commit);
+    const open = inHistory.open ?? openAt(read, compares, own, head);
+    const lastRead = open === null ? read : null;
+    const reads = { lastRead, open, marks };
+    // A clean read carries over the base's changes alone.
+    const carried = lastRead !== null && lastRead.clean && lastRead.baseOnly && sameChanges(own(lastRead.commit), own(head));
+    if (carried) {
+        return { ...reads, carried, changed: null, scope: null };
+    }
+    const scope = lastRead?.baseMoved === true ? movedFiles(own(lastRead.commit), own(head)) : null;
+    if (!sized) {
+        return { ...reads, carried, changed: null, scope };
+    }
+    const changed = compares.changed(lastRead?.commit ?? base, head);
+    if (scope === null || changed === "unsized") {
+        return { ...reads, carried, changed, scope };
+    }
+    const within = changed.filter(({ path, previous }) => scope.includes(path) || (previous !== null && scope.includes(previous)));
+    return { ...reads, carried, changed: within, scope };
+}
+/** Whether a Finding stands: a read mark since the last success, as the last read, or left open (ADR 0016). */
+function findingsOpen({ marks, lastRead, open }) {
+    return marks.count > 0 || lastRead?.clean === false || open !== null;
+}
+/** The depth the head is read at: the dev's or the one `pr.review` sets, else the one the rules route. */
+function depthOf({ depth, source }, standing) {
+    if (depth === "off") {
+        return { depth, source, why: source === "flag" ? "--review off" : "pr.review" };
+    }
+    if (depth !== "auto") {
+        return { depth, source };
+    }
+    return { ...route(standing.changed, findingsOpen(standing)), source: "auto" };
+}
+/** The Review the head gets at `standing` under `review`; the dev's word goes over a carry. */
+export function reviewCall(standing, review) {
+    const { lastRead, open, marks, carried, scope } = standing;
+    const flagged = review.source === "flag";
+    if (carried && lastRead !== null && !flagged) {
+        return { kind: "carry", from: lastRead.commit };
+    }
+    const depth = depthOf(review, standing);
+    // The dev's own depth buys one Review past the limit, and only one: the flag rides on every
+    // later call. Their --review off posts past it: no one reads, by their word.
+    const limit = flagged ? REVIEW_LIMIT + 1 : REVIEW_LIMIT;
+    if (!(flagged && depth.depth === "off") && marks.count >= limit) {
+        return { ...marks, kind: "limit" };
+    }
+    // Over a carry the dev's depth reads the whole diff: the changes after the read are only the base's.
+    return { ...depth, kind: "review", since: carried ? null : (lastRead?.commit ?? null), paths: scope, open };
+}

package/dist/pr/state.d.ts

@@ -1,3 +1,4 @@
+import type { History, Standing } from "./standing.ts";
 /** 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. */
@@ -10,7 +11,7 @@ export declare const MARK_STATE = "failure";
 export declare const READ_MARK = "read, findings open";
 /** How the description of the success the dev's `--accept` posts reads: the head, taken with its Findings open. */
 export declare const ACCEPTED = "accepted by the dev, findings open";
-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 headRef { name } isCrossRepository baseRefName\n      baseRefOid baseRef { target { oid } } viewerDidAuthor mergeCommit { oid }\n      ready: timelineItems(last: 1, itemTypes: [READY_FOR_REVIEW_EVENT]) { nodes { ... on ReadyForReviewEvent { createdAt } } }\n      latestReviews(first: 100) { nodes { state author { login } commit { oid } } }\n      reviewThreads(first: 100) { pageInfo { hasNextPage } 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) { pageInfo { hasNextPage } 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      rewritten: timelineItems(last: 20, itemTypes: [HEAD_REF_FORCE_PUSHED_EVENT]) { nodes { ... on HeadRefForcePushedEvent {\n        beforeCommit { oid history(first: 20) { nodes { oid parents(first: 1) { nodes { oid } }\n          status { context(name: \"dw-sdlc/review\") { state description } } } } } } } }\n    }\n  }\n}";
+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 headRef { name } isCrossRepository baseRefName\n      baseRefOid baseRef { target { oid } } viewerDidAuthor mergeCommit { oid }\n      ready: timelineItems(last: 1, itemTypes: [READY_FOR_REVIEW_EVENT]) { nodes { ... on ReadyForReviewEvent { createdAt } } }\n      latestReviews(first: 100) { nodes { state author { login } commit { oid } } }\n      reviewThreads(first: 100) { pageInfo { hasNextPage } 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) { pageInfo { hasNextPage } nodes {\n          ... on CheckRun { name status conclusion detailsUrl startedAt isRequired(pullRequestNumber: $number) }\n          ... on StatusContext { context state targetUrl createdAt isRequired(pullRequestNumber: $number) } } } }\n        status { context(name: \"dw-sdlc/review\") { 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      rewritten: timelineItems(last: 20, itemTypes: [HEAD_REF_FORCE_PUSHED_EVENT]) { nodes { ... on HeadRefForcePushedEvent {\n        beforeCommit { oid history(first: 20) { nodes { oid parents(first: 1) { nodes { oid } }\n          status { context(name: \"dw-sdlc/review\") { state description } } } } } } } }\n    }\n  }\n}";
 export type Bucket = "pass" | "fail" | "pending" | "skipping";
 export type CiCheck = {
     name: string;
@@ -38,7 +39,8 @@ export type ChangeRequest = {
     reviewer: string;
     answered: boolean;
 };
-export type PrState = {
+/** The pull request as the reply holds it, before the Review's standing is read. */
+export type PullRequest = {
     url: string;
     repo: string;
     number: number;
@@ -74,67 +76,9 @@ export type PrState = {
     cutOff: string[];
     /** The oids of the pull request's last 100 commits, oldest first, the head last. */
     commits: string[];
-    /**
-     * The last commit before the head a Review read, of the last 100: a review success not posted under
-     * off, or a read mark. With none there, a commit force pushes left behind that a Review read.
-     */
-    lastRead: LastRead | null;
-    /**
-     * A read mark whose Findings no later commit answers: the head's own, or one a merge of the base or a
-     * rebase came after with no fix showing. Then `lastRead` is null, the Review reads the whole pull
-     * request, and nothing carries (ADR 0023).
-     */
-    open: string | null;
-    /**
-     * The read marks since the last review success of any kind, of the last 100 commits, then, when they
-     * hold no success, of the commits force pushes left behind.
-     */
-    marks: ReadMarks;
-    /** Whether the head carries the success of `lastRead`: the read decides it from two compares. */
-    carried: boolean;
-    /**
-     * The files a Review would read, from `lastRead` 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;
-    /**
-     * The files whose own change moved since `lastRead`, when a merge of the base came after it: the files
-     * a fix touched, the base's own left out. Null with no such merge, or when a compare cannot show them.
-     */
-    scope: string[] | 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 commit a Review read; `clean` when that Review left a success on it, not a read mark. */
-export type Read = {
-    commit: string;
-    clean: boolean;
-};
-/**
- * A commit a Review read; `baseOnly` when every change after it is the base's, the head included: only
- * merges of the base, or a rebase past no other read; `baseMoved` when a merge of the base or a rebase
- * came after it.
- */
-export type LastRead = Read & {
-    baseOnly: boolean;
-    baseMoved: boolean;
-};
-/**
- * The Reviews that left a Finding open since the last review success, a success under off and the dev's
- * acceptance included: `count` their read marks, the head's own among them, and `since` that success's
- * commit, null when none of the last 100 holds one.
- */
-export type ReadMarks = {
-    count: number;
-    since: string | null;
 };
+/** The pull request and the Review's standing at its head. */
+export type PrState = PullRequest & Standing;
 /** 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. */
@@ -144,15 +88,12 @@ export declare function parseView(reply: string): {
 };
 /** The default branch of the repository whose `gh repo view --json defaultBranchRef` printed `reply`. */
 export declare function parseDefaultBranch(reply: string): string;
-/** The state as the reply holds it, before the compares decide what the head carries and a Review reads. */
-export type Parsed = Omit<PrState, "carried" | "changed" | "scope">;
 /**
- * The state of the pull request in `reply`, the text `gh api graphql` printed for QUERY on `repo`, and
- * `rewritten`: the commits the last 20 force pushes left behind that a Review read, newest first, none the
- * history still holds, where a Review's read stands once a rebase rewrote every commit it read.
+ * The pull request in `reply`, the text `gh api graphql` printed for QUERY on `repo`, and the history the
+ * Review's standing at its head is read from.
  */
 export declare function parsePr(reply: string, repo: string): {
-    pr: Parsed;
-    rewritten: Read[];
+    pr: PullRequest;
+    history: History;
 };
 export {};

package/dist/pr/state.js

@@ -1,5 +1,6 @@
 // One pull request as the Ship script reads it: the one GraphQL query, and its reply parsed into the
-// state the decision reads. Every field the state needs is checked; a reply that fails names the field.
+// state the decision reads, the review history the Review's standing is read from beside it. Every field
+// the state needs is checked; a reply that fails names the field.
 import { boolean, child, childOrNull, firstNode, hasMore, integer, integerOrNull, nodes, oneOf, ReplyError, rootOf, string, stringOrNull, time, timeOrNull } from "./reply.js";
 /** The commit status a clean review of the head leaves on it. */
 export const REVIEW = "dw-sdlc/review";
@@ -35,7 +36,8 @@ export const QUERY = `query($owner: String!, $name: String!, $number: Int!) {
       commits(last: 1) { nodes { commit { committedDate statusCheckRollup {
         contexts(first: ${CHECKS_READ}) { pageInfo { hasNextPage } nodes {
           ... on CheckRun { name status conclusion detailsUrl startedAt isRequired(pullRequestNumber: $number) }
-          ... on StatusContext { context state targetUrl createdAt isRequired(pullRequestNumber: $number) } } } } } } }
+          ... on StatusContext { context state targetUrl createdAt isRequired(pullRequestNumber: $number) } } } }
+        status { context(name: "${REVIEW}") { context state targetUrl createdAt isRequired(pullRequestNumber: $number) } } } } }
       history: commits(last: 100) { nodes { commit { oid parents { totalCount } status { context(name: "${REVIEW}") { state description } } } } }
       rewritten: timelineItems(last: ${FORCE_PUSHES_READ}, itemTypes: [HEAD_REF_FORCE_PUSHED_EVENT]) { nodes { ... on HeadRefForcePushedEvent {
         beforeCommit { oid history(first: ${LEFT_BEHIND_READ}) { nodes { oid parents(first: 1) { nodes { oid } }
@@ -89,6 +91,23 @@ function checkOf(context, repo) {
     }
     throw new ReplyError(`${context.at} is neither a CheckRun nor a StatusContext`);
 }
+/**
+ * The head's checks as the rollup lists them. With more past its first 50, the review status is read by
+ * its name too, so whether the head is reviewed never hangs on where the rollup lists it.
+ */
+function checksOf(commit, repo) {
+    const rollup = childOrNull(commit, "statusCheckRollup");
+    if (rollup === null) {
+        return [];
+    }
+    const listed = nodes(rollup, "contexts").map((context) => checkOf(context, repo));
+    if (!hasMore(rollup, "contexts") || listed.some(({ name }) => name === REVIEW)) {
+        return listed;
+    }
+    const status = childOrNull(commit, "status");
+    const review = status === null ? null : childOrNull(status, "context");
+    return review === null ? listed : [...listed, checkOf(review, repo)];
+}
 /** A thread by its opening comment; a deleted account's comment has no author and reads as GitHub's ghost. */
 function threadOf(thread) {
     const first = firstNode(thread, "comments");
@@ -134,34 +153,6 @@ function historyOf(pr) {
         };
     });
 }
-/**
- * The last commit before `head` a Review read, the history oldest first, or `open`: a read mark on the
- * head, or with only merges after it. No fix answers its Findings, so no read stands in (ADR 0023).
- */
-function lastReadOf(history, head) {
-    if (history.some(({ oid, posted }) => oid === head && posted === "findings")) {
-        return { lastRead: null, open: head };
-    }
-    const index = history.findLastIndex(({ oid, posted }) => oid !== head && (posted === "clean" || posted === "findings"));
-    const last = history[index];
-    if (last === undefined) {
-        return { lastRead: null, open: null };
-    }
-    const after = history.slice(index + 1);
-    const baseOnly = after.every(({ merge }) => merge);
-    if (last.posted === "findings" && baseOnly) {
-        return { lastRead: null, open: last.oid };
-    }
-    return {
-        lastRead: {
-            commit: last.oid,
-            clean: last.posted === "clean",
-            baseOnly,
-            baseMoved: after.some(({ merge }) => merge)
-        },
-        open: null
-    };
-}
 /**
  * The commits a force push left behind: the head, then down its first parents within the history the
  * read holds of it. A merge's first parent is the branch, so the walk stays off the base's side.
@@ -179,29 +170,27 @@ function lineOf(left) {
 }
 /**
  * The commits the force pushes left behind, newest push first, each once and none the history still
- * holds: a line stops where it meets the history, as under an amend, or a newer push's line.
+ * holds: a line stops where it meets the history, as under an amend, or a newer push's line, and forks
+ * where the commit it meets does.
  */
-function forcePushedOf(pr, history) {
-    const seen = new Set(history.map(({ oid }) => oid));
+function leftBehindOf(pr, history) {
+    const forks = new Map(history.map(({ oid }, index) => [oid, index]));
     const left = [];
     for (const event of nodes(pr, "rewritten").toReversed()) {
         const head = childOrNull(event, "beforeCommit");
-        for (const commit of head === null ? [] : lineOf(head)) {
-            if (seen.has(commit.oid)) {
-                break;
-            }
-            seen.add(commit.oid);
-            left.push(commit);
+        const line = head === null ? [] : lineOf(head);
+        const met = line.findIndex(({ oid }) => forks.has(oid));
+        const meets = line[met];
+        const forksAt = meets === undefined ? -1 : (forks.get(meets.oid) ?? -1);
+        for (const commit of meets === undefined ? line : line.slice(0, met)) {
+            forks.set(commit.oid, forksAt);
+            left.push({ ...commit, forksAt });
         }
     }
     return left;
 }
-/** The commits of `forcePushed` a Review read; a success under off says no one read its commit. */
-function rewrittenOf(forcePushed) {
-    return forcePushed.flatMap(({ oid, posted }) => posted === "clean" || posted === "findings" ? [{ commit: oid, clean: posted === "clean" }] : []);
-}
 /**
- * Whether a non-merge commit follows `commit` in the history, oldest first, as `lastReadOf` judges a read
+ * Whether a non-merge commit follows `commit` in the history, oldest first, as the standing judges a read
  * mark. A commit outside the history, after a force-push or past the last 100, is not answered.
  */
 function answeredAfter(history, commit) {
@@ -221,23 +210,6 @@ function changeRequestsOf(pr, history) {
         };
     });
 }
-/**
- * The read marks since the last success, the history's first; with no success there, the marks on the
- * commits force pushes left behind go on the count, newest first, up to the first success among them.
- */
-function readMarksOf(history, forcePushed) {
-    const isSuccess = ({ posted }) => posted === "clean" || posted === "off";
-    const findings = (commits) => commits.filter(({ posted }) => posted === "findings").length;
-    const success = history.findLastIndex(isSuccess);
-    const count = findings(history.slice(success + 1));
-    const lastSuccess = history[success];
-    if (lastSuccess !== undefined) {
-        return { count, since: lastSuccess.oid };
-    }
-    const pushedSuccess = forcePushed.findIndex(isSuccess);
-    const sincePushed = pushedSuccess < 0 ? forcePushed : forcePushed.slice(0, pushedSuccess);
-    return { count: count + findings(sincePushed), since: forcePushed[pushedSuccess]?.oid ?? null };
-}
 /** The repository and number of the pull request whose URL `gh pr view --json url` printed. */
 export function parseView(reply) {
     const url = string(rootOf(reply, "the reply of gh pr view"), "url");
@@ -252,9 +224,8 @@ export function parseDefaultBranch(reply) {
     return string(child(rootOf(reply, "the reply of gh repo view"), "defaultBranchRef"), "name");
 }
 /**
- * The state of the pull request in `reply`, the text `gh api graphql` printed for QUERY on `repo`, and
- * `rewritten`: the commits the last 20 force pushes left behind that a Review read, newest first, none the
- * history still holds, where a Review's read stands once a rebase rewrote every commit it read.
+ * The pull request in `reply`, the text `gh api graphql` printed for QUERY on `repo`, and the history the
+ * Review's standing at its head is read from.
  */
 export function parsePr(reply, repo) {
     const pr = child(child(child(rootOf(reply, "the reply"), "data"), "repository"), "pullRequest");
@@ -263,9 +234,9 @@ export function parsePr(reply, repo) {
     const mergeCommit = childOrNull(pr, "mergeCommit");
     const head = string(pr, "headRefOid");
     const baseRef = childOrNull(pr, "baseRef");
-    const history = historyOf(pr);
+    const commits = historyOf(pr);
     const [ready] = nodes(pr, "ready");
-    const state = {
+    const parsed = {
         url: string(pr, "url"),
         repo,
         number: integer(pr, "number"),
@@ -284,18 +255,17 @@ export function parsePr(reply, repo) {
         base: string(pr, "baseRefName"),
         baseOid: baseRef === null ? string(pr, "baseRefOid") : string(child(baseRef, "target"), "oid"),
         mergeCommit: mergeCommit === null ? null : string(mergeCommit, "oid"),
-        checks: rollup === null ? [] : nodes(rollup, "contexts").map((context) => checkOf(context, repo)),
+        checks: checksOf(commit, repo),
         unresolvedThreads: nodes(pr, "reviewThreads")
             .filter((thread) => !boolean(thread, "isResolved") && !boolean(thread, "isOutdated"))
             .map(threadOf),
-        changeRequests: changeRequestsOf(pr, history),
+        changeRequests: changeRequestsOf(pr, commits),
         cutOff: [
             ...(rollup !== null && hasMore(rollup, "contexts") ? [`the first ${CHECKS_READ} checks`] : []),
             ...(hasMore(pr, "reviewThreads") ? [`the first ${THREADS_READ} threads`] : [])
         ],
-        commits: history.map(({ oid }) => oid),
-        ...lastReadOf(history, head)
+        commits: commits.map(({ oid }) => oid)
     };
-    const forcePushed = forcePushedOf(pr, history);
-    return { pr: { ...state, marks: readMarksOf(history, forcePushed) }, rewritten: rewrittenOf(forcePushed) };
+    const history = { commits, leftBehind: leftBehindOf(pr, commits), head, base: parsed.baseOid };
+    return { pr: parsed, history };
 }

package/dist/pr/upstream.d.ts

@@ -1,11 +1,6 @@
 import type { PrState } from "./state.ts";
-/**
- * The remote branch name `branch` tracks, when it differs from `branch`. Read from the config, so it holds
- * after the remote deleted the branch.
- */
-export declare function upstreamName(root: string, branch: string): string | undefined;
 /** Whether `pr`'s commits hold `head`, so the head is on GitHub whatever became of the upstream. */
-export declare function holds(pr: PrState, head: string | null): boolean;
+export declare function holds(pr: Pick<PrState, "commits">, head: string | null): boolean;
 /** The checked-out branch at `root`, its head commit, and the other name its upstream gives. */
 export type RenamedUpstream = {
     branch: string;

package/dist/pr/upstream.js

@@ -1,12 +1,12 @@
 // A branch's upstream, read from git, for a branch pushed under another name: gh resolves
 // its pull request neither through `@{push}` nor by the local name, so `pr ship` and recap ask by the name
 // the upstream gives, and take that pull request only when its commits hold the local head.
-import { asked } from "../working-tree.js";
+import { asked } from "../git.js";
 /**
  * The remote branch name `branch` tracks, when it differs from `branch`. Read from the config, so it holds
  * after the remote deleted the branch.
  */
-export function upstreamName(root, branch) {
+function upstreamName(root, branch) {
     const remote = asked(root, ["config", "--get", `branch.${branch}.remote`]);
     const merge = asked(root, ["config", "--get", `branch.${branch}.merge`]);
     if (remote === undefined || remote === "." || merge === undefined || !merge.startsWith("refs/heads/")) {

package/dist/primitives-diff.js

@@ -4,7 +4,7 @@
 import { resolveConfig } from "./agentic-config.js";
 import { parseCatalogue, primitivesNaming } from "./catalogue.js";
 import { catalogueFile } from "./checks/primitives.js";
-import { asked, git } from "./working-tree.js";
+import { asked, git } from "./git.js";
 const CLASSES = ["removes", "adds", "extends"];
 const REMEDIES = {
     missing: "create it, or point gate.checks.primitives.file at the catalogue",

package/dist/recap-next.js

@@ -1,7 +1,8 @@
 // The candidates for the session after this one, as `dw-sdlc recap` reads them: the open issues an agent may
 // start, from one GraphQL request that also asks which issues the branch's pull request closes.
-import { isObject, parseObject } from "./json-text.js";
-import { CannotRun, gh, said } from "./pr/read.js";
+import { CannotRun } from "./cannot-run.js";
+import { gh, said } from "./pr/read.js";
+import { child, childOrNull, integer, nodes, ReplyError, rootOf, string } from "./pr/reply.js";
 /** The label that marks an issue as ready for an agent to start. */
 export const READY_LABEL = "ready-for-agent";
 /** How many open issues the one read holds, oldest first, and how many issues the pull request closes. */
@@ -16,46 +17,33 @@ const QUERY = `query Backlog($owner: String!, $name: String!, $number: Int!, $cl
   }
 }`;
 const REMEDY = "check gh auth status and the network, then call again";
-function malformed(field) {
-    return new CannotRun(`the backlog reply does not parse: ${field}`, "gh answered a shape dw-sdlc does not read; report it with the output of gh --version");
-}
-function nodesOf(value, field) {
-    if (!isObject(value) || !Array.isArray(value.nodes)) {
-        throw malformed(field);
-    }
-    return value.nodes;
-}
-function numberOf(value, field) {
-    if (!isObject(value) || typeof value.number !== "number") {
-        throw malformed(field);
-    }
-    return value.number;
-}
+const UNREAD_SHAPE = "gh answered a shape dw-sdlc does not read; report it with the output of gh --version";
 /** An issue node as a candidate, or null when it has an assignee or an open blocker. */
 function candidateOf(node) {
-    if (!isObject(node) || typeof node.title !== "string" || typeof node.url !== "string") {
-        throw malformed("issues.nodes");
-    }
-    const { assignees, issueDependenciesSummary: dependencies, parent } = node;
-    if (!isObject(assignees) || typeof assignees.totalCount !== "number") {
-        throw malformed("issues.nodes.assignees");
-    }
-    if (!isObject(dependencies) || typeof dependencies.blockedBy !== "number") {
-        throw malformed("issues.nodes.issueDependenciesSummary");
-    }
-    if (assignees.totalCount > 0 || dependencies.blockedBy > 0) {
+    const title = string(node, "title");
+    const url = string(node, "url");
+    const assignees = integer(child(node, "assignees"), "totalCount");
+    const blockedBy = integer(child(node, "issueDependenciesSummary"), "blockedBy");
+    if (assignees > 0 || blockedBy > 0) {
         return null;
     }
-    const number = numberOf(node, "issues.nodes.number");
-    return { number, title: node.title, url: node.url, parent: parent === null ? null : numberOf(parent, "parent") };
+    const parent = childOrNull(node, "parent");
+    return { number: integer(node, "number"), title, url, parent: parent === null ? null : integer(parent, "number") };
 }
-function repositoryOf(stdout) {
-    const data = parseObject(stdout)?.data;
-    const repository = isObject(data) ? data.repository : undefined;
-    if (!isObject(repository)) {
-        throw malformed("data.repository");
-    }
-    return repository;
+/**
+ * The candidates the backlog `reply` holds, the sub-issues of an issue the pull request closes first, each
+ * part in issue order. The issues it closes are read only when the query asked for them, `closing`.
+ */
+function candidatesIn(reply, closing) {
+    const repository = child(child(rootOf(reply, "the backlog reply"), "data"), "repository");
+    const closed = closing ? nodes(child(repository, "pullRequest"), "closingIssuesReferences") : [];
+    const closes = new Set(closed.map((node) => integer(node, "number")));
+    const candidates = nodes(repository, "issues")
+        .map(candidateOf)
+        .filter((candidate) => candidate !== null && !closes.has(candidate.number))
+        .toSorted((one, other) => one.number - other.number);
+    const underClosed = (candidate) => candidate.parent !== null && closes.has(candidate.parent);
+    return [...candidates.filter(underClosed), ...candidates.filter((candidate) => !underClosed(candidate))];
 }
 /**
  * The open issues labelled ready-for-agent with no assignee and no open blocker, read from `repo`, or from the
@@ -81,16 +69,15 @@ function nextCandidates(pr) {
     if (reply.status !== 0) {
         throw new CannotRun(`gh could not read the backlog: ${said(reply.stderr)}`, REMEDY);
     }
-    const repository = repositoryOf(reply.stdout);
-    const closes = new Set(pr === null
-        ? []
-        : nodesOf(isObject(repository.pullRequest) ? repository.pullRequest.closingIssuesReferences : undefined, "pullRequest").map((node) => numberOf(node, "closingIssuesReferences.nodes")));
-    const candidates = nodesOf(repository.issues, "issues")
-        .map(candidateOf)
-        .filter((candidate) => candidate !== null && !closes.has(candidate.number))
-        .toSorted((one, other) => one.number - other.number);
-    const underClosed = (candidate) => candidate.parent !== null && closes.has(candidate.parent);
-    return [...candidates.filter(underClosed), ...candidates.filter((candidate) => !underClosed(candidate))];
+    try {
+        return candidatesIn(reply.stdout, pr !== null);
+    }
+    catch (error) {
+        if (error instanceof ReplyError) {
+            throw new CannotRun(`the backlog reply does not parse: ${error.message}`, UNREAD_SHAPE);
+        }
+        throw error;
+    }
 }
 export function readNext(pr) {
     try {

package/dist/recap-primitives.js

@@ -3,8 +3,8 @@
 // the default branch and a repository with no catalogue roll up to none.
 import { resolveConfig } from "./agentic-config.js";
 import { catalogueFile } from "./checks/primitives.js";
+import { asked } from "./git.js";
 import { primitivesDiff } from "./primitives-diff.js";
-import { asked } from "./working-tree.js";
 /** `defaultOf` names the default branch and is asked only once the repository has a catalogue and `branch` is no base. */
 export function rollup(root, branch, defaultOf) {
     const { guardrails, gate } = resolveConfig(root).config;