dw-sdlc 0.21.0 → 0.21.1

package/dist/pr/read.js

@@ -1,18 +1,13 @@
 // The read the pr commands and recap make: gh as a child process, its auth, the pull request a command names,
-// its state from one GraphQL request with the compares that tell whether its head carries an earlier Review
-// and that size its changes, and beside them the default branch and the clock the decision reads.
-import { exec, TimedOut } from "../exec.js";
-import { behindOf, changedOf, changesOf, compareArgs, sameChanges } from "./delta.js";
+// its state from one GraphQL request and the Review's standing at its head from GitHub's compares, through
+// gh, and beside them the default branch and the clock the decision reads.
+import { CannotRun } from "../cannot-run.js";
+import { firstLine, need } from "../exec.js";
+import { behindOf, changedOf, changesOf, compareArgs } from "./delta.js";
 import { ReplyError } from "./reply.js";
+import { standingOf } from "./standing.js";
 import { awaitsReview, parseDefaultBranch, parsePr, parseView, QUERY } from "./state.js";
-/** What stops a pr command or recap before it answers: exit 2, the problem and its remedy on one line. */
-export class CannotRun extends Error {
-    remedy;
-    constructor(message, remedy) {
-        super(message);
-        this.remedy = remedy;
-    }
-}
+import { holds, renamedUpstream } from "./upstream.js";
 const REMEDIES = {
     missing: "install the GitHub CLI from https://cli.github.com",
     auth: "run gh auth login, or set GH_TOKEN",
@@ -31,39 +26,18 @@ export function namedProblem(number, repo) {
     }
     return undefined;
 }
-function firstLine(text) {
-    return text.trim().split("\n")[0] ?? "";
-}
 /** What gh said went wrong: the first line of its stderr, without its `gh: ` prefix or its `X` icon. */
 export function said(stderr) {
-    return firstLine(stderr).replace(/^(?:gh: |X )/, "");
+    return (firstLine(stderr) ?? "").replace(/^(?:gh: |X )/, "");
 }
 /** The problem `gh auth status` reports: its line marked `X` under the host, else its first line. */
 function authProblem(stderr) {
     const marked = stderr.split("\n").find((line) => line.trimStart().startsWith("X "));
-    return marked === undefined ? firstLine(stderr) : marked.trim().slice(2);
-}
-/** `gh args` as a child process; past its limit it stops the command as any other failed read does. */
-function reachGh(args) {
-    try {
-        return exec("gh", args);
-    }
-    catch (error) {
-        if (error instanceof TimedOut) {
-            throw new CannotRun(error.message, REMEDIES.read);
-        }
-        throw error;
-    }
+    return marked === undefined ? (firstLine(stderr) ?? "") : marked.trim().slice(2);
 }
+/** `gh args` as a child process; not on PATH, or past its limit, it stops the command as any failed read does. */
 export function gh(args) {
-    const result = reachGh(args);
-    if (result.error !== undefined) {
-        if ("code" in result.error && result.error.code === "ENOENT") {
-            throw new CannotRun("gh is not on PATH", REMEDIES.missing);
-        }
-        throw result.error;
-    }
-    return { status: result.status ?? 1, stdout: result.stdout, stderr: result.stderr };
+    return need("gh", args, { missing: REMEDIES.missing, stalled: REMEDIES.read });
 }
 /** What `parse` returns; a reply it cannot parse stops the command, naming the field. */
 function parseOrCannotRun(parse) {
@@ -89,7 +63,7 @@ function targetOf({ number, repo }, command) {
     const named = [...(number === undefined ? [] : [String(number)]), ...(repo === undefined ? [] : ["-R", repo])];
     const view = gh(["pr", "view", ...named, "--json", "url"]);
     if (view.status !== 0) {
-        throw new CannotRun(`gh pr view found no pull request: ${firstLine(view.stderr)}`, nameItRemedy(command));
+        throw new CannotRun(`gh pr view found no pull request: ${firstLine(view.stderr) ?? ""}`, nameItRemedy(command));
     }
     return parseOrCannotRun(() => parseView(view.stdout));
 }
@@ -101,41 +75,17 @@ function requireAuth() {
         throw new CannotRun(`gh auth status failed: ${authProblem(auth.stderr)}`, REMEDIES.auth);
     }
 }
-/**
- * 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) {
-    requireAuth();
-    return query(targetOf(named, command), sized);
-}
-/** The pull request `gh pr view` resolves for the head branch `branch`, else the current one; null when none. */
+/** The pull request `gh pr view` resolves for the head branch `branch`, else the current one, or what gh said of none. */
 function viewed(branch) {
     const view = gh(["pr", "view", ...(branch === undefined ? [] : [branch]), "--json", "url"]);
     if (view.status === 0) {
         return parseOrCannotRun(() => parseView(view.stdout));
     }
     if (said(view.stderr).startsWith("no pull requests found")) {
-        return null;
+        return { none: said(view.stderr) };
     }
     throw new CannotRun(`gh pr view failed: ${said(view.stderr)}`, REMEDIES.read);
 }
-/**
- * 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 function readBranch(sized, upstreamName) {
-    requireAuth();
-    const own = viewed(undefined);
-    if (own !== null) {
-        return { pr: query(own, sized), byUpstream: false };
-    }
-    if (upstreamName === undefined) {
-        return null;
-    }
-    const found = viewed(upstreamName);
-    return found === null ? null : { pr: query(found, sized), byUpstream: true };
-}
 /** The default branch of the repository gh resolves from the current directory. */
 export function defaultBranch() {
     const view = gh(["repo", "view", "--json", "defaultBranchRef"]);
@@ -156,125 +106,88 @@ export function now() {
     }
     return time;
 }
-/** The state of `pr` once more, after an action the script performed on it: the same pull request. */
-export function readAgain(pr, sized) {
-    return query(pr, sized);
+/** A commit as a reason names it: its first seven characters. */
+function short(commit) {
+    return commit.slice(0, 7);
 }
 /**
- * The compares this process has read, by repository and the two commits, so reads that share one ask gh
- * once: a compare of two commits never changes.
+ * The gh adapter on `target`. A compare of two commits never changes, so it asks gh for each once, for its
+ * own life; a compare gh refuses stops the command, naming it.
  */
-const COMPARES = new Map();
-/** For a test that runs the command in its own process: each case starts with no compare read. */
-export function forgetCompares() {
-    COMPARES.clear();
-}
-/** The reply of the compare from `from` to `commit`, read once per process; `what` names it when gh refuses it. */
-function compared(pr, from, commit, what) {
-    const key = `${pr.repo} ${from}...${commit}`;
-    const known = COMPARES.get(key);
-    if (known !== undefined) {
-        return known;
-    }
-    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);
-    }
-    COMPARES.set(key, reply.stdout);
-    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, with no read in its history, the newest commit force pushes left behind that a Review read. */
-function withRewritten(pr, rewritten) {
-    const [newest] = rewritten;
-    if (newest === undefined || pr.lastRead !== null || pr.open !== null) {
-        return pr;
-    }
-    return { ...pr, lastRead: { ...newest, baseOnly: true, baseMoved: true } };
-}
-/**
- * `pr` with its last read mark `open` when a merge of the base or a rebase came after it and no fix
- * shows: the own changes are as it read them, or a compare cannot show them whole (ADR 0023). The
- * compares run only when a Review awaits the head.
- */
-function withOpen(pr) {
-    const last = pr.lastRead;
-    if (last === null || last.clean || !last.baseMoved || pr.state !== "OPEN" || !awaitsReview(pr)) {
-        return pr;
-    }
-    const atRead = ownChanges(pr, last.commit);
-    const atHead = ownChanges(pr, pr.head);
-    if (atRead !== null && atHead !== null && !sameChanges(atRead, atHead)) {
-        return pr;
-    }
-    return { ...pr, lastRead: null, open: last.commit };
-}
-/**
- * `pr` and whether its head carries the success of the last commit a Review read: a clean read, only
- * the base's changes since it, and the same own changes at both. A read mark never carries. The
- * compares run only when a Review awaits the head.
- */
-function withCarried(pr) {
-    const last = pr.lastRead;
-    if (last === null || !last.clean || !last.baseOnly || pr.state !== "OPEN" || !awaitsReview(pr)) {
-        return { ...pr, carried: false };
-    }
-    return { ...pr, carried: sameChanges(ownChanges(pr, last.commit), ownChanges(pr, pr.head)) };
-}
-/**
- * The files whose own change differs between `from` and the head of `pr`, a rename under both names:
- * what a fix touched, without the files a merge of the base brought in. Null when a compare cannot show
- * the own changes whole.
- */
-function ownScope(pr, from) {
-    const before = ownChanges(pr, from);
-    const after = ownChanges(pr, pr.head);
-    if (before === null || after === null) {
-        return null;
-    }
-    const moved = [
-        ...after.filter((change) => !before.includes(change)),
-        ...before.filter((change) => !after.includes(change))
-    ];
-    const names = moved.flatMap((change) => {
-        const [path, , previous] = JSON.parse(change);
-        return previous === null ? [path] : [path, previous];
-    });
-    return [...new Set(names)].toSorted();
-}
-/**
- * `pr` and, when a Review awaits a head that carries none, its `scope` after a merge of the base or a
- * rebase, and when `sized`, the files the Review would read: the compare from the last commit a Review
- * read, else from the base, to the head, kept to the scope when there is one.
- */
-function withChanged(pr, sized) {
-    if (pr.carried || pr.state !== "OPEN" || !awaitsReview(pr)) {
-        return { ...pr, changed: null, scope: null };
-    }
-    const scope = pr.lastRead?.baseMoved === true ? ownScope(pr, pr.lastRead.commit) : null;
-    if (!sized) {
-        return { ...pr, changed: null, scope };
-    }
-    const from = pr.lastRead?.commit ?? pr.baseOid;
-    const reply = compared(pr, from, pr.head, `the compare of ${from.slice(0, 7)}...${pr.head.slice(0, 7)}`);
-    const changed = parseOrCannotRun(() => changedOf(reply));
-    if (scope === null || changed === "unsized") {
-        return { ...pr, changed, scope };
-    }
-    const within = changed.filter(({ path, previous }) => scope.includes(path) || (previous !== null && scope.includes(previous)));
-    return { ...pr, changed: within, scope };
-}
-/** The state of pull request `number` of `repo`, from one GraphQL request and the compares a Review needs. */
-function query({ repo, number }, sized) {
+function ghCompares(target) {
+    const replies = new Map();
+    const replyOf = (from, to, what) => {
+        const key = `${from}...${to}`;
+        const known = replies.get(key);
+        if (known !== undefined) {
+            return known;
+        }
+        const reply = gh(compareArgs(target.repo, from, to));
+        if (reply.status !== 0) {
+            throw new CannotRun(`${target.repo}#${target.number}: ${what}: ${said(reply.stderr)}`, REMEDIES.read);
+        }
+        replies.set(key, reply.stdout);
+        return reply.stdout;
+    };
+    return {
+        ownChanges: (base, commit) => parseOrCannotRun(() => changesOf(replyOf(base, commit, `the compare with ${short(commit)}`))),
+        changed: (from, head) => parseOrCannotRun(() => changedOf(replyOf(from, head, `the compare of ${short(from)}...${short(head)}`))),
+        behind: (base, head) => parseOrCannotRun(() => behindOf(replyOf(base, head, `the compare with ${short(base)}`)))
+    };
+}
+/** The pull request `named` from the one GraphQL request alone, without the compares the Review's standing reads. */
+export function pullRequestNamed(named, command) {
+    requireAuth();
+    const target = targetOf(named, command);
+    return parseOrCannotRun(() => parsePr(graphql(target), target.repo)).pr;
+}
+/** The reads of one command; with `sized`, as `pr.review: auto` needs, each sizes the changes a Review would read. */
+export function ghReads(sized) {
+    const adapters = new Map();
+    const comparesOn = (target) => {
+        const key = `${target.repo}#${target.number}`;
+        const adapter = adapters.get(key) ?? ghCompares(target);
+        adapters.set(key, adapter);
+        return adapter;
+    };
+    const query = (target) => {
+        const { pr, history } = parseOrCannotRun(() => parsePr(graphql(target), target.repo));
+        const awaits = pr.state === "OPEN" && awaitsReview(pr);
+        return { ...pr, ...standingOf(history, comparesOn(target), { awaits, sized }) };
+    };
+    return {
+        named: (named, command) => {
+            requireAuth();
+            return query(targetOf(named, command));
+        },
+        checkout: (root) => {
+            requireAuth();
+            const own = viewed(undefined);
+            if (!("none" in own)) {
+                return query(own);
+            }
+            const renamed = renamedUpstream(root);
+            if (renamed === undefined) {
+                return { problem: `gh pr view found no pull request: ${own.none}`, lacksHead: false };
+            }
+            const { branch, head, upstream } = renamed;
+            const named = `${upstream}, the name its upstream gives`;
+            const found = viewed(upstream);
+            if ("none" in found) {
+                return { problem: `gh pr view found no pull request for ${branch}, nor for ${named}`, lacksHead: false };
+            }
+            // A branch started from another tracks that branch until its first push: its pull request is not this one.
+            const pr = query(found);
+            return holds(pr, head)
+                ? pr
+                : { problem: `${pr.url}, found by ${named}, lacks HEAD ${short(head)}`, lacksHead: true };
+        },
+        again: query,
+        carriesBase: (before, after) => comparesOn(after).behind(before.baseOid, after.head) === 0
+    };
+}
+/** The reply of the one GraphQL request for pull request `number` of `repo`. */
+function graphql({ repo, number }) {
     const [owner = "", name = ""] = repo.split("/");
     const reply = gh([
         "api",
@@ -293,6 +206,5 @@ function query({ repo, number }, sized) {
         const remedy = problem.startsWith("Could not resolve to a") ? REMEDIES.target : REMEDIES.read;
         throw new CannotRun(`${repo}#${number}: ${problem}`, remedy);
     }
-    const { pr, rewritten } = parseOrCannotRun(() => parsePr(reply.stdout, repo));
-    return withChanged(withCarried(withOpen(withRewritten(pr, rewritten))), sized);
+    return reply.stdout;
 }

package/dist/pr/reply.js

@@ -1,11 +1,9 @@
 // The reply of a gh call read as JSON: each field checked as the type the reader asks for, and a
 // reply that fails names the field by its path.
+import { isObject } from "../json-text.js";
 /** A reply that is not the shape the query asks for; the message names the field. */
 export class ReplyError extends Error {
 }
-function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
 export function shown(value) {
     return value === undefined ? "missing" : JSON.stringify(value);
 }
@@ -18,7 +16,7 @@ export function rootOf(reply, what) {
     catch {
         throw new ReplyError(`${what} is not JSON`);
     }
-    if (!isRecord(json)) {
+    if (!isObject(json)) {
         throw new ReplyError(`${what} is not a JSON object`);
     }
     return { value: json, at: "" };
@@ -27,7 +25,7 @@ export function fieldOf(node, key) {
     return { value: node.value[key], at: node.at === "" ? key : `${node.at}.${key}` };
 }
 export function object(value, at) {
-    if (!isRecord(value)) {
+    if (!isObject(value)) {
         throw new ReplyError(`${at} is ${shown(value)}, not an object`);
     }
     return { value, at };

package/dist/pr/route.d.ts

@@ -1,5 +1,13 @@
 import type { ReviewDepth } from "../agentic-config.ts";
-import type { ChangedFile } from "./state.ts";
+/**
+ * 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 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">;
@@ -9,6 +17,6 @@ export type Routed = {
 };
 /**
  * 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.
+ * outside lockfiles the compare shows no patch for. With `findingsOpen` someone reads even lockfiles alone.
  */
-export declare function route(changed: ChangedFile[] | "unsized" | null): Routed;
+export declare function route(changed: ChangedFile[] | "unsized" | null, findingsOpen: boolean): Routed;

package/dist/pr/route.js

@@ -1,6 +1,6 @@
 // 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.
+// lockfiles alone are off while no Finding is open; 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",
@@ -33,14 +33,14 @@ function isWorkflow({ path, previous }) {
 }
 /**
  * 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.
+ * outside lockfiles the compare shows no patch for. With `findingsOpen` someone reads even lockfiles alone.
  */
-export function route(changed) {
+export function route(changed, findingsOpen) {
     if (changed === null || changed === "unsized") {
         return { depth: "full" };
     }
     const code = changed.filter((file) => !isLockfile(file.path));
-    if (changed.length > 0 && code.length === 0) {
+    if (!findingsOpen && changed.length > 0 && code.length === 0) {
         return { depth: "off", why: "lockfiles only" };
     }
     const lines = code.map((file) => file.lines);

package/dist/pr/standing.d.ts

@@ -0,0 +1,138 @@
+import type { PrReview, ReviewDepth } from "../agentic-config.ts";
+import { type ChangedFile } from "./route.ts";
+/** What a commit's review status says: a success, the read mark, a success posted under off, or none. */
+export type Posted = "clean" | "findings" | "off" | null;
+/** A commit of the history and the review status it carries; `merge` when it has more than one parent. */
+export type Commit = {
+    oid: string;
+    posted: Posted;
+    merge: boolean;
+};
+/**
+ * A commit a force push left behind and its review status; `forksAt` the index in the history of the
+ * commit its line was pushed on, as under an amend, -1 when its line holds none, as after a rebase.
+ */
+export type LeftBehind = {
+    oid: string;
+    posted: Posted;
+    forksAt: number;
+};
+/** What the standing is read from. */
+export type History = {
+    /** The pull request's last 100 commits, oldest first, the head last. */
+    commits: Commit[];
+    /** The commits the last force pushes left behind, newest push first, none of them among `commits`. */
+    leftBehind: LeftBehind[];
+    head: string;
+    /** The commit the base branch points at, the one the own changes are compared with. */
+    base: string;
+};
+/**
+ * A file's own change: its name, its status, its name before a rename, and the lines its patch adds and
+ * removes, in order, without the hunk headers and context a moved base shifts.
+ */
+export type OwnChange = {
+    path: string;
+    status: string;
+    previous: string | null;
+    lines: string[];
+};
+/** GitHub's compares as the standing asks them. A compare of two commits never changes: an adapter may keep it. */
+export type Compares = {
+    /** The pull request's own changes at `commit`, from `base`; null when the compare cannot show them whole. */
+    ownChanges: (base: string, commit: string) => OwnChange[] | null;
+    /** The files from `from` to `head` and their changed lines; `unsized` when the compare may hold some back. */
+    changed: (from: string, head: string) => ChangedFile[] | "unsized";
+};
+/**
+ * A commit a Review read, `clean` when it left a success there and not a read mark; `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 = {
+    commit: string;
+    clean: boolean;
+    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 no commit read holds one.
+ */
+export type ReadMarks = {
+    count: number;
+    since: string | null;
+};
+/** The Review's standing at the head, as the decision reads it and `pr ship --verbose` shows it. */
+export type Standing = {
+    /**
+     * A read mark force pushes left behind after every read of the history, else the last commit before the
+     * head a Review read, else a commit force pushes left behind that one read.
+     */
+    lastRead: LastRead | null;
+    /**
+     * A read mark whose Findings no later commit answers: the head's own, or one the commits since leave with
+     * no fix showing, merges of the base and rebases among them. Then `lastRead` is null and nothing carries
+     * (ADR 0023).
+     */
+    open: string | null;
+    /** The read marks posted since the last success, on the history and on the commits force pushes left behind. */
+    marks: ReadMarks;
+    /** Whether the head carries the success of `lastRead`, which two compares decide. */
+    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 or a rebase came after it:
+     * the files a fix touched, the base's own left out. Null with neither, or when a compare cannot show them.
+     */
+    scope: string[] | 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 declare function standingOf(history: History, compares: Compares, { awaits, sized }: {
+    awaits: boolean;
+    sized: boolean;
+}): Standing;
+/** Who set the depth: the dev's `--review` for this call, or `pr.review`, a depth or `auto`. */
+export type ReviewPolicy = {
+    depth: ReviewDepth;
+    source: "flag";
+} | {
+    depth: PrReview;
+    source: "config";
+};
+/** Where a Review depth comes from: the dev's word, `pr.review`, or the rules `pr.review: auto` routes by. */
+export type DepthSource = "flag" | "config" | "auto";
+/** A depth as the answer names it, and under off why no one reads the head. */
+export type Depth = {
+    depth: Exclude<ReviewDepth, "off">;
+    source: DepthSource;
+} | {
+    depth: "off";
+    source: DepthSource;
+    why: string;
+};
+/**
+ * The Review the head gets: the success of the read it carries; a Review at a depth that reads from `since`,
+ * kept to `paths`, over the read mark left `open`, where under off the script posts the success; or the park.
+ */
+export type ReviewCall = {
+    kind: "carry";
+    from: string;
+} | (Depth & {
+    kind: "review";
+    since: string | null;
+    paths: string[] | null;
+    open: string | null;
+}) | (ReadMarks & {
+    kind: "limit";
+});
+/** The Review the head gets at `standing` under `review`; the dev's word goes over a carry. */
+export declare function reviewCall(standing: Standing, review: ReviewPolicy): ReviewCall;