dw-sdlc 0.12.1 → 0.14.0

package/dist/pr/read.js

@@ -64,6 +64,10 @@ function parseOrCannotRun(parse) {
         throw error;
     }
 }
+/** The remedy for a pull request `command`, as `pr ship`, cannot find by itself: name it in full. */
+export function nameItRemedy(command) {
+    return `name it: dw-sdlc ${command} <n> -R owner/name`;
+}
 /** The pull request named in full, or the one `gh pr view` resolves from what is given. */
 function targetOf({ number, repo }, command) {
     if (number !== undefined && repo !== undefined) {
@@ -72,8 +76,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) {
-        const remedy = `name it: dw-sdlc ${command} <n> -R owner/name`;
-        throw new CannotRun(`gh pr view found no pull request: ${firstLine(view.stderr)}`, remedy);
+        throw new CannotRun(`gh pr view found no pull request: ${firstLine(view.stderr)}`, nameItRemedy(command));
     }
     return parseOrCannotRun(() => parseView(view.stdout));
 }
@@ -185,25 +188,26 @@ function ownChanges(pr, commit) {
     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.
+ * `pr` and whether its head carries the success of the last commit a Review read: a clean read, only
+ * merges 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.lastReviewed;
-    if (last === null || !last.mergesOnly || pr.state !== "OPEN" || !awaitsReview(pr)) {
+    const last = pr.lastRead;
+    if (last === null || !last.clean || !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.
+ * the compare from the last commit a Review read, 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 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)}`);
     return { ...pr, changed: parseOrCannotRun(() => changedOf(reply)) };
 }

package/dist/pr/state.d.ts

@@ -2,6 +2,14 @@
 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:";
+/**
+ * The read mark: the review status in this state and with this description says a Review read that
+ * head and left a Finding open.
+ */
+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 baseRefName baseRefOid\n      baseRef { target { oid } } 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 = {
@@ -51,12 +59,17 @@ export type PrState = {
     unresolvedThreads: Thread[];
     /** The oids of the pull request's last 100 commits, oldest first, the head last. */
     commits: string[];
-    /** 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. */
+    /**
+     * The last commit before the head a Review read, of the last 100: a review success not posted under
+     * off, or a read mark.
+     */
+    lastRead: LastRead | null;
+    /** The read marks since the last review success of any kind, of the last 100 commits. */
+    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 `lastReviewed` or the base to the head, read only for `pr.review:
+     * 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;
@@ -75,11 +88,24 @@ export type ChangedFile = {
     previous: string | null;
     lines: number | null;
 };
-/** A reviewed commit, and whether every commit after it, the head included, is a merge. */
-export type LastReviewed = {
+/**
+ * A commit a Review read; `clean` when that Review left a success on it, not a read mark; and whether
+ * every commit after it, the head included, is a merge.
+ */
+export type LastRead = {
     commit: string;
+    clean: boolean;
     mergesOnly: 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;
+};
 /** A reply that is not the shape the query asks for; the message names the field. */
 export declare class ReplyError extends Error {
 }

package/dist/pr/state.js

@@ -4,6 +4,14 @@
 export const REVIEW = "dw-sdlc/review";
 /** How the description of a success the script posts under off begins: no one read that head. */
 export const OFF_PREFIX = "off:";
+/**
+ * The read mark: the review status in this state and with this description says a Review read that
+ * head and left a Finding open.
+ */
+export const MARK_STATE = "failure";
+export 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 const ACCEPTED = "accepted by the dev, findings open";
 export const QUERY = `query($owner: String!, $name: String!, $number: Int!) {
   repository(owner: $owner, name: $name) {
     pullRequest(number: $number) {
@@ -191,26 +199,57 @@ function threadOf(thread) {
 export function awaitsReview(pr) {
     return pr.viewerDidAuthor && !pr.checks.some((check) => check.name === REVIEW && check.bucket === "pass");
 }
-/** A commit whose review success says someone read it: a status posted under off never does. */
-function isReviewed(commit) {
+/**
+ * What a commit's review status says: `clean` a success, `findings` the read mark, `off` a success
+ * posted under off, which says no one read the commit, null no status of the Review.
+ */
+function postedOn(commit) {
     const status = childOrNull(commit, "status");
     const context = status === null ? null : childOrNull(status, "context");
-    if (context === null || string(context, "state") !== "SUCCESS") {
-        return false;
+    if (context === null) {
+        return null;
+    }
+    const state = string(context, "state");
+    const description = stringOrNull(context, "description") ?? "";
+    if (state === "SUCCESS") {
+        return description.startsWith(OFF_PREFIX) ? "off" : "clean";
     }
-    return !(stringOrNull(context, "description") ?? "").startsWith(OFF_PREFIX);
+    return state === MARK_STATE.toUpperCase() && description === READ_MARK ? "findings" : null;
+}
+/** The pull request's last 100 commits, oldest first, each with the review status it carries. */
+function historyOf(pr) {
+    return nodes(pr, "history").map((node) => {
+        const commit = child(node, "commit");
+        return {
+            oid: string(commit, "oid"),
+            posted: postedOn(commit),
+            merge: integer(child(commit, "parents"), "totalCount") > 1
+        };
+    });
 }
-/** The last commit before `head` that `isReviewed` takes, the history oldest first. */
-function lastReviewedOf(pr, head) {
-    const commits = nodes(pr, "history").map((node) => child(node, "commit"));
-    const index = commits.findLastIndex((commit) => string(commit, "oid") !== head && isReviewed(commit));
-    const reviewed = commits[index];
-    if (reviewed === undefined) {
+/**
+ * The last commit before `head` a Review read, the history oldest first. A read mark with only merges
+ * after it is passed over: no fix answers its Findings yet, and a Review from it would read only the
+ * base's changes, so the Review reads from the read before it and finds them again.
+ */
+function lastReadOf(history, head) {
+    const commits = history.map(({ oid, posted, merge }) => ({
+        oid,
+        read: oid === head || posted === "off" ? null : posted,
+        merge
+    }));
+    const mergesOnlyAfter = (index) => commits.slice(index + 1).every(({ merge }) => merge);
+    const index = commits.findLastIndex(({ read }, at) => read === "clean" || (read === "findings" && !mergesOnlyAfter(at)));
+    const last = commits[index];
+    if (last === undefined) {
         return null;
     }
-    const after = commits.slice(index + 1);
-    const mergesOnly = after.every((commit) => integer(child(commit, "parents"), "totalCount") > 1);
-    return { commit: string(reviewed, "oid"), mergesOnly };
+    return { commit: last.oid, clean: last.read === "clean", mergesOnly: mergesOnlyAfter(index) };
+}
+function readMarksOf(history) {
+    const success = history.findLastIndex(({ posted }) => posted === "clean" || posted === "off");
+    const count = history.slice(success + 1).filter(({ posted }) => posted === "findings").length;
+    return { count, since: history[success]?.oid ?? null };
 }
 /** The repository and number of the pull request whose URL `gh pr view --json url` printed. */
 export function parseView(reply) {
@@ -233,6 +272,7 @@ export function parsePr(reply, repo) {
     const mergeCommit = childOrNull(pr, "mergeCommit");
     const head = string(pr, "headRefOid");
     const baseRef = childOrNull(pr, "baseRef");
+    const history = historyOf(pr);
     return {
         url: string(pr, "url"),
         repo,
@@ -253,7 +293,8 @@ export function parsePr(reply, repo) {
         unresolvedThreads: nodes(pr, "reviewThreads")
             .filter((thread) => !boolean(thread, "isResolved") && !boolean(thread, "isOutdated"))
             .map(threadOf),
-        commits: nodes(pr, "history").map((node) => string(child(node, "commit"), "oid")),
-        lastReviewed: lastReviewedOf(pr, head)
+        commits: history.map(({ oid }) => oid),
+        lastRead: lastReadOf(history, head),
+        marks: readMarksOf(history)
     };
 }

package/dist/pr/upstream.d.ts

@@ -0,0 +1,16 @@
+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;
+/** The checked-out branch at `root`, its head commit, and the other name its upstream gives. */
+export type RenamedUpstream = {
+    branch: string;
+    head: string;
+    upstream: string;
+};
+/** The checked-out branch whose upstream has another name; undefined on a detached HEAD or a branch with no commit. */
+export declare function renamedUpstream(root: string): RenamedUpstream | undefined;

package/dist/pr/upstream.js

@@ -0,0 +1,31 @@
+// 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";
+/**
+ * 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) {
+    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/")) {
+        return undefined;
+    }
+    const name = merge.slice("refs/heads/".length);
+    return name === branch ? undefined : name;
+}
+/** Whether `pr`'s commits hold `head`, so the head is on GitHub whatever became of the upstream. */
+export function holds(pr, head) {
+    return head !== null && pr.commits.includes(head);
+}
+/** The checked-out branch whose upstream has another name; undefined on a detached HEAD or a branch with no commit. */
+export function renamedUpstream(root) {
+    const branch = asked(root, ["symbolic-ref", "--quiet", "--short", "HEAD"]);
+    const head = asked(root, ["rev-parse", "--verify", "--quiet", "HEAD"]);
+    if (branch === undefined || head === undefined) {
+        return undefined;
+    }
+    const upstream = upstreamName(root, branch);
+    return upstream === undefined ? undefined : { branch, head, upstream };
+}

package/dist/run-command.d.ts

@@ -19,6 +19,6 @@ export type Ran = {
 export declare const TAIL_LINES = 50;
 /** Runs `body` with SIGINT and SIGTERM held, so a signal stops the command running and the Gate reports it. */
 export declare function holdingSignals<T>(body: () => Promise<T>): Promise<T>;
-/** The signal that stopped the run, once one has; no command starts after it. */
+/** The signal that stopped the run, once one has: one the Gate got or one that ended a command. */
 export declare function stoppedBy(): NodeJS.Signals | undefined;
 export declare function runCommand(command: string, root: string, output: Output): Promise<Ran>;

package/dist/run-command.js

@@ -13,6 +13,11 @@ const STOPPING = ["SIGINT", "SIGTERM"];
 let running;
 /** The first SIGINT or SIGTERM the Gate got; no command starts after it. */
 let received;
+/**
+ * The SIGINT or SIGTERM that ended a command; no command starts after it either. Ctrl-C reaches the
+ * command and the Gate together, and the command's exit can be seen before the Gate's own signal.
+ */
+let commandEndedBy;
 function release() {
     for (const signal of STOPPING) {
         process.off(signal, stop);
@@ -32,6 +37,8 @@ function stop(signal) {
 export async function holdingSignals(body) {
     running = undefined;
     received = undefined;
+    commandEndedBy = undefined;
+    release();
     for (const signal of STOPPING) {
         process.on(signal, stop);
     }
@@ -41,12 +48,16 @@ export async function holdingSignals(body) {
     finally {
         // One turn of the event loop hands a signal that landed after the last command to its handler.
         await new Promise((resolve) => setImmediate(resolve));
-        release();
+        // The Gate's own signal may still be on its way after a command it ended: the handlers stay, so
+        // that signal does not end the Gate before its report.
+        if (commandEndedBy === undefined || received !== undefined) {
+            release();
+        }
     }
 }
-/** The signal that stopped the run, once one has; no command starts after it. */
+/** The signal that stopped the run, once one has: one the Gate got or one that ended a command. */
 export function stoppedBy() {
-    return received;
+    return received ?? commandEndedBy;
 }
 /** Everything written to `fd`, read from its start: the command's writes moved the offset it shares to the end. */
 function written(fd) {
@@ -99,7 +110,12 @@ function run(command, root, stdio) {
                 done({ status: "error", exitCode: null, signal: null, detail: `could not start: ${error.message}` });
             }
         });
-        child.once("exit", (exitCode, signal) => done(answer(exitCode, signal)));
+        child.once("exit", (exitCode, signal) => {
+            if (signal !== null && STOPPING.includes(signal)) {
+                commandEndedBy ??= signal;
+            }
+            done(answer(exitCode, signal));
+        });
     });
 }
 export async function runCommand(command, root, output) {

package/dist/sweep-terminals.d.ts

@@ -0,0 +1,89 @@
+import { type Worker } from "./worker/herdr.ts";
+import { type LockVerdict } from "./worktree-lock.ts";
+/** A live terminal of another session, or the sweeping one's own, with the place herdr shows it at. */
+type Seen = {
+    address: string;
+    name: string;
+    folder: string;
+    place: string;
+};
+/** A Worker with the pid of the program `hc get` reports in its terminal, which a Claude Code lock names. */
+export type Located = Worker & {
+    pid: number | undefined;
+};
+export type Terminals = {
+    own: Seen | undefined;
+    workers: Located[];
+    others: Seen[];
+};
+/** What holds a worktree: the terminal of this session, another session's, or a Worker of this one. */
+export type Holder = {
+    role: "own";
+    terminal: Seen;
+} | {
+    role: "other";
+    terminal: Seen;
+} | {
+    role: "worker";
+    worker: Located;
+};
+/** The terminal to stop and remove, or only to remove once it has finished. */
+export type TerminalPlan = {
+    kind: "terminal";
+    name: string;
+    reason: string;
+    stop: boolean;
+    tree?: string;
+};
+/** The address of the terminal the Sweep runs in, or undefined outside herdr. */
+export declare function sweepingTerminal(): string | undefined;
+/**
+ * Reads herdr for the sweeping terminal `own`: its Workers, finished ones included, and the other live
+ * terminals. An `hc` that fails stops the Sweep, since a terminal it cannot see must not count as absent.
+ */
+export declare function readTerminals(own: string): Terminals;
+/** A Worker whose terminal is live but whose folder is gone, with no worktree of `roots` around it, could commit nothing more. */
+export declare function workerWithoutFolder({ workers }: Terminals, roots: string[]): Worker[];
+/** The terminals in the folder of each of `trees`; the main checkout `main` takes those not in a linked one. */
+export declare function holdersOf({ own, workers, others }: Terminals, main: string, trees: string[]): Map<string, Holder[]>;
+/** How the Sweep says a Worker that is working, blocked or yet to report is, or undefined for one that is done. */
+export declare function atWork({ status }: Worker): string | undefined;
+/** What the terminals in a worktree keep it for, or null when only Workers at the end of their turn are in it. */
+export declare function whyHeld(holders: Holder[]): {
+    reason: string;
+    command: string | null;
+} | null;
+/** The terminals of the Workers done in a worktree that goes, to stop and remove with it. */
+export declare function stopsOf(holders: Holder[], tree: string): TerminalPlan[];
+/** Stops, if `item` asks, and removes its terminal; the words of the `hc` that refused, or undefined when it is gone. */
+export declare function removeTerminal(item: {
+    name: string;
+    stop?: boolean;
+}): string | undefined;
+/** A Worker the Sweep keeps, with why. */
+export type KeptWorker = {
+    name: string;
+    reason: string;
+};
+/** The Workers no worktree of this Sweep decides: a finished one is removed, one whose folder is gone goes under the status rule. */
+export declare function outsideWorktrees(terminals: Terminals, roots: string[]): {
+    remove: TerminalPlan[];
+    keep: KeptWorker[];
+};
+/** The command that stops or removes the terminal of a planned terminal by hand. */
+export declare function byHand(item: {
+    name: string;
+    stop?: boolean;
+}): string;
+/** The Worker in `holders` whose program is the process a live lock names, when it may be stopped. */
+export declare function lockHolder(pid: number, holders: Holder[]): Located | undefined;
+/** The lock of the worktree at `path` read again once its Worker is stopped, given the program a moment to end. */
+export declare function lockAfterStop(root: string, path: string): LockVerdict;
+type KeptTerminal = {
+    name: string;
+    reason: string;
+    command: string | null;
+};
+/** The terminals in a worktree that stays which the Sweep lists as kept: Workers, and another session's terminals. */
+export declare function keptIn(holders: Holder[], tree: string): KeptTerminal[];
+export {};