dw-sdlc 0.12.0 → 0.13.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));
 }
@@ -93,18 +96,33 @@ export function read(named, command, sized) {
     requireAuth();
     return query(targetOf(named, command), sized);
 }
-/** The state of the current branch's pull request, open or not, or null when gh finds none. */
-export function readBranch(sized) {
-    requireAuth();
-    const view = gh(["pr", "view", "--json", "url"]);
+/** The pull request `gh pr view` resolves for the head branch `branch`, else the current one; null when none. */
+function viewed(branch) {
+    const view = gh(["pr", "view", ...(branch === undefined ? [] : [branch]), "--json", "url"]);
     if (view.status === 0) {
-        return query(parseOrCannotRun(() => parseView(view.stdout)), sized);
+        return parseOrCannotRun(() => parseView(view.stdout));
     }
     if (said(view.stderr).startsWith("no pull requests found")) {
         return null;
     }
     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"]);
@@ -170,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/working-tree.d.ts

@@ -4,6 +4,8 @@ export declare function git(root: string, args: string[], index?: string): {
 } | {
     error: string;
 };
+/** `git <args>` at `root`, or undefined when it exits non-zero as a question answered no. */
+export declare function asked(root: string, args: string[]): string | undefined;
 /** The tree of the checkout at `root` and its git dir, or why it has none. */
 export declare function workingTree(root: string): {
     tree: string;

package/dist/working-tree.js

@@ -20,6 +20,11 @@ export function git(root, args, index) {
     const reason = result.error?.message ?? result.stderr.split("\n").find((line) => line.trim() !== "");
     return { error: `git ${args[0] ?? ""}: ${reason?.trim() ?? `exited ${result.status ?? "on a signal"}`}` };
 }
+/** `git <args>` at `root`, or undefined when it exits non-zero as a question answered no. */
+export function asked(root, args) {
+    const result = git(root, args);
+    return "out" in result ? result.out : undefined;
+}
 /**
  * The tree `git write-tree` hashes from a copy of the index after `git add -A` on it: the copy keeps the
  * stat cache, so only what changed is read again; identical content survives a commit, an amend or a

package/dist/worktree-lock.d.ts

@@ -0,0 +1,15 @@
+/** The process is gone: `held` is the reason to put back should the removal fail, `why` what the Sweep tells. */
+export type StaleLock = {
+    state: "stale";
+    held: string;
+    why: string;
+};
+export type LockVerdict = {
+    state: "none";
+} | StaleLock | {
+    state: "stays";
+    reason: string;
+    command: string | null;
+};
+/** What the lock of the worktree at `path`, held for `reason`, says about whether the Sweep may lift it. */
+export declare function lockVerdict(path: string, reason: string | undefined): LockVerdict;

package/dist/worktree-lock.js

@@ -0,0 +1,63 @@
+// What a worktree's lock means to a Sweep. Claude Code locks the worktree of a session with the reason
+// `claude session <name> (pid <N> start <time>)`, <time> as `ps -o lstart` writes it in UTC. Such a lock is
+// stale once no process N runs or N started at another time. Any other reason is the dev's to lift.
+import { spawnSync } from "node:child_process";
+import { shellLine } from "./pr/decide.js";
+const CLAUDE_LOCK = /^claude session .* \(pid (?<pid>\d{1,10}) start (?<start>.+)\)$/;
+const MAX_PID = 2 ** 31 - 1;
+const squeezed = (text) => text.trim().replace(/\s+/g, " ");
+/**
+ * Whether process `pid` runs and, if so, its start time as `ps` writes it in UTC and in local time, so a
+ * live lock is never taken for stale over a time zone.
+ */
+function runningOf(pid) {
+    try {
+        process.kill(pid, 0);
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ESRCH") {
+            return { at: "gone" };
+        }
+    }
+    const starts = [{ TZ: "UTC" }, {}]
+        .map((zone) => {
+        const env = { ...process.env, LC_ALL: "C", ...zone };
+        const result = spawnSync("ps", ["-o", "lstart=", "-p", String(pid)], { encoding: "utf8", env });
+        return result.status === 0 ? squeezed(result.stdout) : "";
+    })
+        .filter((start) => start !== "");
+    return starts.length === 0 ? { at: "unknown" } : { at: "running", starts };
+}
+/** What the lock of the worktree at `path`, held for `reason`, says about whether the Sweep may lift it. */
+export function lockVerdict(path, reason) {
+    if (reason === undefined) {
+        return { state: "none" };
+    }
+    const unlock = shellLine(["git", "worktree", "unlock", path]);
+    const { pid: pidText = "", start = "" } = CLAUDE_LOCK.exec(reason)?.groups ?? {};
+    const pid = Number(pidText);
+    if (pidText === "" || pid < 1 || pid > MAX_PID) {
+        const said = reason === "" ? "locked, with no reason given" : `locked: ${reason}`;
+        return { state: "stays", reason: said, command: unlock };
+    }
+    const now = runningOf(pid);
+    if (now.at === "gone") {
+        return { state: "stale", held: reason, why: `pid ${pid} is gone, no process runs under it` };
+    }
+    if (now.at === "unknown") {
+        return { state: "stays", reason: `locked: ${reason}; ps could not say whether pid ${pid} runs`, command: unlock };
+    }
+    if (!now.starts.includes(squeezed(start))) {
+        const started = now.starts[0] ?? "";
+        return {
+            state: "stale",
+            held: reason,
+            why: `pid ${pid} is gone, it now belongs to another process (started ${started} UTC)`
+        };
+    }
+    return {
+        state: "stays",
+        reason: `locked by a live Claude Code session: pid ${pid} is running (${reason})`,
+        command: null
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dw-sdlc",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "The Gate and the agentic config of a repository: the dw-sdlc bin with the Gate, the setup, the doctor, the config check, the Sync and setup of References, and the Ship script that drives a pull request to merged; the resolver of the config's layers, its JSON Schema and the validator that reads it.",
   "license": "MIT",
   "repository": {