dw-sdlc 0.21.0 → 0.21.1

package/dist/pr/decide.d.ts

@@ -1,4 +1,5 @@
-import type { PrMerge, PrReview, ResolvedConfig, ReviewDepth } from "../agentic-config.ts";
+import type { PrMerge, ResolvedConfig } from "../agentic-config.ts";
+import { type ReviewPolicy } from "./standing.ts";
 import { type PrState, REVIEW } from "./state.ts";
 export { REVIEW };
 export type Status = "act" | "wait" | "park" | "done";
@@ -6,24 +7,13 @@ export type Actor = "script" | "agent" | "dev";
 export type Action = "done" | "stop" | "wait" | "fix-conflicts" | "update-branch" | "fix-ci" | "address-review" | "review" | "review-limit" | "mark-reviewed" | "unverified" | "ci-stuck" | "awaiting-reply" | "awaiting-review" | "mark-ready" | "awaiting-author" | "awaiting-approval" | "partial-read" | "ready-to-merge" | "merge";
 /** The Actions the script performs itself, each one gh command. */
 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";
-    };
+    review: ReviewPolicy;
     reviewCommand: string;
 };
 /** The policy a repository's `pr` key declares; a flag for one call goes over it. */
@@ -48,14 +38,12 @@ export type Answer = Blocker & {
  * head the fix then leaves behind. 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 `dw-sdlc/review` on the head, a success unless `state` says otherwise,
  * `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, state?: string): string[];
+export declare function reviewStatusArgs(pr: Pick<PrState, "url" | "repo" | "head">, description: string, state?: 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

package/dist/pr/decide.js

@@ -1,23 +1,18 @@
 // 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 { shellLine } from "../shell-line.js";
+import { reviewCall } from "./standing.js";
 import { awaitsReview, OFF_PREFIX, REVIEW } from "./state.js";
 export { REVIEW };
 /** The policy a repository's `pr` key declares; a flag for one call goes over it. */
 export function declaredPolicy({ merge, review, reviewCommand }) {
     return { merge, review: { depth: review, source: "config" }, reviewCommand };
 }
-/** How long a head may carry no check before it parks as unverified, from its commit. */
+/** How long a head may carry no check before it parks as unverified, from when its CI could start. */
 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;
-/**
- * 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;
 /** The prefix of the contexts the script posts itself, as `dw-sdlc/review`: never CI. */
 const OWN_PREFIX = "dw-sdlc/";
 /**
@@ -25,9 +20,9 @@ const OWN_PREFIX = "dw-sdlc/";
  * head the fix then leaves behind. 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(" ");
+/** When the head's CI could start: its commit, or its ready when it left draft later, since a draft runs nothing. */
+function ciStartOf(pr) {
+    return Math.max(Date.parse(pr.headCommittedAt), Date.parse(pr.readyAt ?? pr.headCommittedAt));
 }
 function ciOf(pr) {
     return pr.checks.filter((check) => !check.name.startsWith(OWN_PREFIX));
@@ -73,48 +68,19 @@ export function reviewStatusArgs(pr, description, state = REVIEW_STATE) {
     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.lastRead?.commit ?? null) : null;
-}
-/**
- * The commit the Review reads from: the last one a Review read, clean or not, so the Review after a fix
- * reads the fix. 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.lastRead?.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 call = reviewCall(pr, policy.review);
+    if (call.kind === "carry") {
+        return `carried from ${call.from.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`);
+    if (call.kind !== "review" || call.depth !== "off") {
+        throw new Error(`the script marks ${pr.url} reviewed, neither off nor a carry`);
     }
-    return `${OFF_PREFIX} ${depth.why}`;
+    return `${OFF_PREFIX} ${call.why}`;
 }
 /** The park at the limit: the dev accepts the head as it stands, or names a depth for one more Review. */
-function reviewLimit(pr) {
-    const { count, since } = pr.marks;
+function reviewLimit(pr, { count, since }) {
     const from = since === null ? "the start of the pull request" : `the success on ${since.slice(0, 7)}`;
     return {
         status: "park",
@@ -124,6 +90,36 @@ function reviewLimit(pr) {
         command: shellLine(["dw-sdlc", "pr", "reviewed", String(pr.number), "-R", pr.repo, "--head", pr.head, "--accept"])
     };
 }
+/**
+ * The Review a head that awaits one gets: the script posts the success of a carry or under off, the agent
+ * reviews at the depth, else it parks at the limit. Auto names the command at any depth, since the agent
+ * may raise a routed one to full.
+ */
+function reviewAnswer(pr, policy) {
+    const head = { status: "act", reason: `no ${REVIEW} success on ${pr.head.slice(0, 7)}` };
+    const call = reviewCall(pr, policy.review);
+    if (call.kind === "carry") {
+        return { ...head, action: "mark-reviewed", actor: "script", details: { since: call.from } };
+    }
+    if (call.kind === "limit") {
+        return reviewLimit(pr, call);
+    }
+    const { depth, source, since, paths, open } = call;
+    const byScript = depth === "off";
+    return {
+        ...head,
+        action: byScript ? "mark-reviewed" : "review",
+        actor: byScript ? "script" : "agent",
+        details: {
+            depth,
+            source,
+            ...(depth === "full" || source === "auto" ? { reviewCommand: policy.reviewCommand } : {}),
+            ...(since === null ? {} : { since }),
+            ...(paths === null ? {} : { paths }),
+            ...(open === null ? {} : { open })
+        }
+    };
+}
 /** A script Action's gh arguments; `repo` is `-R` and the repository when the call names it, else empty. */
 const HOST = {
     "update-branch": (pr, repo) => ["pr", "update-branch", String(pr.number), ...repo],
@@ -221,53 +217,22 @@ const ROWS = [
         answer: () => ({ status: "act", action: "address-review", actor: "agent", reason: "changes requested" })
     },
     {
-        // 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.
+        // Another author's pull request needs no Review: the dev merges it.
         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);
-            // The dev's own depth buys one Review past the limit, and only one: the flag rides on every
-            // later call. A Review under off needs none.
-            const limit = source === "flag" ? REVIEW_LIMIT + 1 : REVIEW_LIMIT;
-            if (depth !== "off" && pr.marks.count >= limit) {
-                return reviewLimit(pr);
-            }
-            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,
-                    ...(pr.scope === null ? {} : { paths: pr.scope }),
-                    ...(pr.open === null ? {} : { open: pr.open })
-                }
-            };
-        }
+        answer: (pr, _, policy) => reviewAnswer(pr, policy)
     },
     {
         // A head whose every check was skipped, or that has none, has run nothing. A draft's runs skip or
         // never start until `ready` starts the run, so a draft is no case of it: `mark-ready` is its row.
         when: (pr) => !pr.draft && (ciOf(pr).length === 0 || ciOf(pr).every((check) => check.bucket === "skipping")),
-        answer: (pr, now, policy) => now - Math.max(Date.parse(pr.headCommittedAt), Date.parse(pr.readyAt ?? pr.headCommittedAt)) <=
-            GRACE_SECONDS * 1000
+        answer: (pr, now, policy) => now - ciStartOf(pr) <= GRACE_SECONDS * 1000
             ? { status: "wait", action: "wait", actor: "script", reason: "unverified", recheckAfter: 15 }
             : {
                 status: "park",
                 action: "unverified",
                 actor: "dev",
                 reason: ciOf(pr).length === 0
-                    ? `no check reported on ${pr.head.slice(0, 7)} within ${GRACE_SECONDS} s of its commit`
+                    ? `no check reported on ${pr.head.slice(0, 7)} within ${GRACE_SECONDS} s of its commit or its ready`
                     : `every check on ${pr.head.slice(0, 7)} was skipped, ${GRACE_SECONDS} s after its commit or its ready`,
                 command: devCommand(pr, "merge", policy)
             }
@@ -276,8 +241,7 @@ const ROWS = [
         when: (pr) => pendingOf(pr).length > 0,
         answer: (pr, now) => {
             const pending = pendingOf(pr);
-            // A check queued and not yet started counts from the head's commit.
-            const start = Math.min(...pending.map((check) => Date.parse(check.startedAt ?? pr.headCommittedAt)));
+            const start = Math.min(...pending.map((check) => (check.startedAt === null ? ciStartOf(pr) : Date.parse(check.startedAt))));
             const minutes = Math.floor((now - start) / 60_000);
             return now - start <= BUDGET_MINUTES * 60_000
                 ? { status: "wait", action: "wait", actor: "script", reason: "ci-pending", recheckAfter: 60 }

package/dist/pr/delta.d.ts

@@ -1,11 +1,10 @@
-import type { ChangedFile } from "./state.ts";
+import type { ChangedFile } from "./route.ts";
+import type { OwnChange } from "./standing.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;
+export declare function changesOf(reply: string): OwnChange[] | 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

@@ -1,6 +1,6 @@
-// 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`.
+// GitHub's compare of two commits as gh prints it, read three ways: the pull request's own changes at a
+// commit, from the base; the files a Review would read, with their changed lines, for `pr.review: auto`;
+// and how far a head is behind a base, which says whether an update merged it in.
 import { fieldOf, integer, object, ReplyError, rootOf, shown, string } from "./reply.js";
 /** GitHub's compare lists at most this many files; one that lists as many may hold back the rest. */
 const FILE_LIMIT = 300;
@@ -24,17 +24,15 @@ export function behindOf(reply) {
 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.
- */
+/** A file's own change; null when the compare shows no patch for it. */
 function changeOf(file) {
-    const names = [string(file, "filename"), string(file, "status"), optional(file, "previous_filename")];
+    const path = string(file, "filename");
+    const status = string(file, "status");
+    const previous = 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))]);
+    return patch === null
+        ? null
+        : { path, status, previous, lines: 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) {
@@ -51,10 +49,3 @@ export function changedOf(reply) {
     }));
     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

@@ -1,9 +1,5 @@
-import { type PrState } from "./state.ts";
-/** What stops a pr command or recap before it answers: exit 2, the problem and its remedy on one line. */
-export declare class CannotRun extends Error {
-    remedy: string;
-    constructor(message: string, remedy: string);
-}
+import { type Called } from "../exec.ts";
+import { type PrState, type PullRequest } from "./state.ts";
 /** The pull request a command line names; what it leaves out, `gh pr view` resolves. */
 export type Named = {
     number: number | undefined;
@@ -13,33 +9,34 @@ export type Named = {
 export declare function namedProblem(number: string | undefined, repo: string | undefined): string | undefined;
 /** What gh said went wrong: the first line of its stderr, without its `gh: ` prefix or its `X` icon. */
 export declare function said(stderr: string): string;
-export declare function gh(args: string[]): {
-    status: number;
-    stdout: string;
-    stderr: string;
-};
+/** `gh args` as a child process; not on PATH, or past its limit, it stops the command as any failed read does. */
+export declare function gh(args: string[]): Called;
 /** The remedy for a pull request `command`, as `pr ship`, cannot find by itself: name it in full. */
 export declare function nameItRemedy(command: string): string;
-/**
- * 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 current branch's pull request, open or not, or null. gh tries `@{push}`, else the local name, which
- * misses a branch pushed under another name; then `upstreamName` is asked, and `byUpstream` says so.
- */
-export declare function readBranch(sized: boolean, upstreamName: string | undefined): {
-    pr: PrState;
-    byUpstream: boolean;
-} | null;
+/** Why this checkout names no pull request to read; `lacksHead` when the one its upstream's name finds lacks HEAD. */
+export type NoPr = {
+    problem: string;
+    lacksHead: boolean;
+};
 /** The default branch of the repository gh resolves from the current directory. */
 export declare function defaultBranch(): string;
 /** The time the decision reads: DW_SDLC_NOW, an ISO 8601 time a test sets, else the system clock. */
 export declare function now(): number;
-/** The state of `pr` once more, after an action the script performed on it: the same pull request. */
-export declare function readAgain(pr: PrState, sized: boolean): PrState;
-/** For a test that runs the command in its own process: each case starts with no compare read. */
-export declare function forgetCompares(): void;
-/** 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;
+/** The pull request `named` from the one GraphQL request alone, without the compares the Review's standing reads. */
+export declare function pullRequestNamed(named: Named, command: string): PullRequest;
+/** The reads of pull requests one command makes through gh, each one's compares kept for the reads' life. */
+export type Reads = {
+    /** The state of the pull request `named`; `command`, as `pr ship`, names the call in a remedy. */
+    named: (named: Named, command: string) => PrState;
+    /**
+     * The pull request of the branch checked out at `root`, open or not. gh tries `@{push}`, else the local
+     * name, which misses a branch pushed under another name: then it asks by the name the upstream gives.
+     */
+    checkout: (root: string) => PrState | NoPr;
+    /** The state of `pr` once more, after an action the script performed on it. */
+    again: (pr: PrState) => PrState;
+    /** Whether the head of `after` carries the base `before` read: the compare shows it behind by none. */
+    carriesBase: (before: PrState, after: PrState) => boolean;
+};
+/** The reads of one command; with `sized`, as `pr.review: auto` needs, each sizes the changes a Review would read. */
+export declare function ghReads(sized: boolean): Reads;