dw-sdlc 0.7.0 → 0.10.0

package/dist/pr/state.js

@@ -1,9 +1,13 @@
 // One pull request as the Ship script reads it: the one GraphQL query, and its reply parsed into the
 // state the decision reads. Every field the state needs is checked; a reply that fails names the field.
+/** The commit status a clean review of the head leaves on it. */
+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:";
 export const QUERY = `query($owner: String!, $name: String!, $number: Int!) {
   repository(owner: $owner, name: $name) {
     pullRequest(number: $number) {
-      url number state isDraft mergeable mergeStateStatus reviewDecision headRefOid headRefName baseRefName
+      url number state isDraft mergeable mergeStateStatus reviewDecision headRefOid headRefName baseRefName baseRefOid
       viewerDidAuthor mergeCommit { oid }
       reviewThreads(first: 100) { nodes { id isResolved isOutdated path line
         comments(first: 1) { nodes { author { login } body } }
@@ -12,6 +16,7 @@ export const QUERY = `query($owner: String!, $name: String!, $number: Int!) {
         contexts(first: 50) { nodes {
           ... on CheckRun { name status conclusion detailsUrl startedAt isRequired(pullRequestNumber: $number) }
           ... on StatusContext { context state targetUrl createdAt isRequired(pullRequestNumber: $number) } } } } } } }
+      history: commits(last: 100) { nodes { commit { oid parents { totalCount } status { context(name: "${REVIEW}") { state description } } } } }
     }
   }
 }`;
@@ -24,11 +29,11 @@ export class ReplyError extends Error {
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-function shown(value) {
+export function shown(value) {
     return value === undefined ? "missing" : JSON.stringify(value);
 }
 /** The JSON object `reply` holds, the root its fields' paths start from; `what` names it in a problem. */
-function rootOf(reply, what) {
+export function rootOf(reply, what) {
     let json;
     try {
         json = JSON.parse(reply);
@@ -41,10 +46,10 @@ function rootOf(reply, what) {
     }
     return { value: json, at: "" };
 }
-function fieldOf(node, key) {
+export function fieldOf(node, key) {
     return { value: node.value[key], at: node.at === "" ? key : `${node.at}.${key}` };
 }
-function object(value, at) {
+export function object(value, at) {
     if (!isRecord(value)) {
         throw new ReplyError(`${at} is ${shown(value)}, not an object`);
     }
@@ -58,7 +63,7 @@ function childOrNull(node, key) {
     const { value, at } = fieldOf(node, key);
     return value === null ? null : object(value, at);
 }
-function string(node, key) {
+export function string(node, key) {
     const { value, at } = fieldOf(node, key);
     if (typeof value !== "string") {
         throw new ReplyError(`${at} is ${shown(value)}, not a string`);
@@ -75,7 +80,7 @@ function boolean(node, key) {
     }
     return value;
 }
-function integer(node, key) {
+export function integer(node, key) {
     const { value, at } = fieldOf(node, key);
     if (typeof value !== "number" || !Number.isInteger(value)) {
         throw new ReplyError(`${at} is ${shown(value)}, not an integer`);
@@ -182,6 +187,31 @@ function threadOf(thread) {
         lastByViewer: boolean(firstNode(thread, "latest"), "viewerDidAuthor")
     };
 }
+/** The viewer's own pull request without a review success on its head: the one a Review reads. */
+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) {
+    const status = childOrNull(commit, "status");
+    const context = status === null ? null : childOrNull(status, "context");
+    if (context === null || string(context, "state") !== "SUCCESS") {
+        return false;
+    }
+    return !(stringOrNull(context, "description") ?? "").startsWith(OFF_PREFIX);
+}
+/** 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) {
+        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 };
+}
 /** The repository and number of the pull request whose URL `gh pr view --json url` printed. */
 export function parseView(reply) {
     const url = string(rootOf(reply, "the reply of gh pr view"), "url");
@@ -197,6 +227,7 @@ export function parsePr(reply, repo) {
     const commit = child(firstNode(pr, "commits"), "commit");
     const rollup = childOrNull(commit, "statusCheckRollup");
     const mergeCommit = childOrNull(pr, "mergeCommit");
+    const head = string(pr, "headRefOid");
     return {
         url: string(pr, "url"),
         repo,
@@ -207,14 +238,16 @@ export function parsePr(reply, repo) {
         mergeStateStatus: string(pr, "mergeStateStatus"),
         reviewDecision: pr.value.reviewDecision === null ? null : oneOf(pr, "reviewDecision", REVIEW_DECISIONS),
         viewerDidAuthor: boolean(pr, "viewerDidAuthor"),
-        head: string(pr, "headRefOid"),
+        head,
         headCommittedAt: time(commit, "committedDate"),
         branch: string(pr, "headRefName"),
         base: string(pr, "baseRefName"),
+        baseOid: string(pr, "baseRefOid"),
         mergeCommit: mergeCommit === null ? null : string(mergeCommit, "oid"),
         checks: rollup === null ? [] : nodes(rollup, "contexts").map((context) => checkOf(context, repo)),
         unresolvedThreads: nodes(pr, "reviewThreads")
             .filter((thread) => !boolean(thread, "isResolved") && !boolean(thread, "isOutdated"))
-            .map(threadOf)
+            .map(threadOf),
+        lastReviewed: lastReviewedOf(pr, head)
     };
 }

package/dist/router-block.d.ts

@@ -1,5 +1,8 @@
 import type { Reference } from "./references-key.ts";
-/** The block the file gives: one row per Reference in the file's order, or one line when it has none. */
+/**
+ * The block the file gives: one row per Reference in the file's order, or one line when it has none,
+ * with a blank line inside each marker and each `when` trimmed, as oxfmt leaves it.
+ */
 export declare function renderBlock(references: Reference[]): string;
 /**
  * The Router's text with `block` in place of the one between its markers: as it is when the two say

package/dist/router-block.js

@@ -6,16 +6,40 @@ const END = "<!-- references:end -->";
 const START_LINE = /^<!-- references:start\b.*-->\s*$/;
 const END_LINE = /^<!-- references:end -->\s*$/;
 const NONE = "No Reference is declared yet: `/sdlc-references-add <repository>` adds one.";
-/** The block the file gives: one row per Reference in the file's order, or one line when it has none. */
+const GRAPHEMES = new Intl.Segmenter("en", { granularity: "grapheme" });
+/** An emoji drawn as one, or a character of the East Asian wide and fullwidth ranges. */
+const WIDE = /[\p{Emoji_Presentation}\u{FE0F}\u{1100}-\u{115F}\u{2329}\u{232A}\u{2E80}-\u{303E}\u{3040}-\u{A4CF}\u{AC00}-\u{D7A3}\u{F900}-\u{FAFF}\u{FE10}-\u{FE19}\u{FE30}-\u{FE6F}\u{FF00}-\u{FF60}\u{FFE0}-\u{FFE6}\u{20000}-\u{2FFFD}\u{30000}-\u{3FFFD}]/u;
+/**
+ * A cell's width in columns, close to oxfmt's: two for a wide grapheme, one for any other. It matches
+ * oxfmt on Latin text, CJK, Hangul and emoji; a script with combining signs, such as Devanagari, or a
+ * rarer wide character comes out off, and the formatter pads that table again.
+ */
+function width(cell) {
+    let columns = 0;
+    for (const { segment } of GRAPHEMES.segment(cell)) {
+        columns += WIDE.test(segment) ? 2 : 1;
+    }
+    return columns;
+}
+function tableLine(cells) {
+    return `| ${cells.join(" | ")} |`;
+}
+/** A Markdown table, each column padded to its widest cell and three at the least. */
+function table(header, body) {
+    const rows = [header, ...body];
+    const widths = header.map((_, column) => Math.max(3, ...rows.map((row) => width(row[column] ?? ""))));
+    const paddedLine = (row) => tableLine(row.map((cell, column) => cell + " ".repeat((widths[column] ?? 0) - width(cell))));
+    return [paddedLine(header), tableLine(widths.map((count) => "-".repeat(count))), ...body.map(paddedLine)];
+}
+/**
+ * The block the file gives: one row per Reference in the file's order, or one line when it has none,
+ * with a blank line inside each marker and each `when` trimmed, as oxfmt leaves it.
+ */
 export function renderBlock(references) {
     const body = references.length === 0
         ? [NONE]
-        : [
-            "| dir | reach for it when |",
-            "| --- | --- |",
-            ...references.map((reference) => `| \`${reference.dir}\` | ${reference.when.replaceAll("|", "\\|")} |`)
-        ];
-    return `${[START, ...body, END].join("\n")}\n`;
+        : table(["dir", "reach for it when"], references.map((reference) => [`\`${reference.dir}\``, reference.when.trim().replaceAll("|", "\\|")]));
+    return `${[START, "", ...body, "", END].join("\n")}\n`;
 }
 /** A table's delimiter row, dashes of any count. */
 const DELIMITER = /^\|(?:\s*-+\s*\|)+$/;

package/dist/run-command.d.ts

@@ -0,0 +1,24 @@
+export type Status = "pass" | "fail" | "error";
+/**
+ * Where a command's output goes: `capture` keeps its last lines when it does not pass; `stdout` and
+ * `stderr` pass it through as it is written, onto stderr when `--json` keeps stdout for the document.
+ */
+export type Output = "capture" | "stdout" | "stderr";
+export type Ran = {
+    status: Status;
+    /** Null when it never started or a signal stopped it. */
+    exitCode: number | null;
+    /** The signal that stopped it: one the Gate got while it ran, or one that ended it. */
+    signal: NodeJS.Signals | null;
+    seconds: number;
+    /** What went wrong, as `exited 3`; absent on a pass. */
+    detail?: string;
+    /** Its last `TAIL_LINES` lines, both streams in the order written, when captured and not passing. */
+    tail: string[] | null;
+};
+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. */
+export declare function stoppedBy(): NodeJS.Signals | undefined;
+export declare function runCommand(command: string, root: string, output: Output): Promise<Ran>;

package/dist/run-command.js

@@ -0,0 +1,121 @@
+// How the Gate runs one command, a Step or a `gate.checks.run` script: through `sh -c` from the
+// repository root, stdin closed, its output captured or passed through, and what it answered; and
+// how SIGINT and SIGTERM stop the command running and every command after it.
+import { spawn } from "node:child_process";
+import { closeSync, fstatSync, mkdtempSync, openSync, readSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+export const TAIL_LINES = 50;
+/** What the shell answers for a command it cannot find, and for one it cannot execute. */
+const NOT_RUNNABLE = { 127: "was not found", 126: "could not be executed" };
+const STOPPING = ["SIGINT", "SIGTERM"];
+/** The command running, which a signal the Gate gets is passed on to. */
+let running;
+/** The first SIGINT or SIGTERM the Gate got; no command starts after it. */
+let received;
+function release() {
+    for (const signal of STOPPING) {
+        process.off(signal, stop);
+    }
+}
+function stop(signal) {
+    if (received !== undefined) {
+        // A second signal ends the Gate at once, as it would with no handler: the command ignored the first.
+        release();
+        process.kill(process.pid, signal);
+        return;
+    }
+    received = signal;
+    running?.kill(signal);
+}
+/** Runs `body` with SIGINT and SIGTERM held, so a signal stops the command running and the Gate reports it. */
+export async function holdingSignals(body) {
+    running = undefined;
+    received = undefined;
+    for (const signal of STOPPING) {
+        process.on(signal, stop);
+    }
+    try {
+        return await 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 signal that stopped the run, once one has; no command starts after it. */
+export function stoppedBy() {
+    return received;
+}
+/** Everything written to `fd`, read from its start: the command's writes moved the offset it shares to the end. */
+function written(fd) {
+    const buffer = Buffer.alloc(fstatSync(fd).size);
+    let filled = 0;
+    while (filled < buffer.length) {
+        const read = readSync(fd, buffer, filled, buffer.length - filled, filled);
+        if (read === 0) {
+            break;
+        }
+        filled += read;
+    }
+    return buffer.toString("utf8", 0, filled);
+}
+/** The last lines of `text`; a line a lone `\r` rewrote keeps the last text written over it, as a terminal shows it. */
+function lastLines(text) {
+    const all = text.split(/\r?\n/);
+    if (all.at(-1) === "") {
+        all.pop();
+    }
+    return all.slice(-TAIL_LINES).map((line) => line.split("\r").findLast((part) => part !== "") ?? "");
+}
+/** What the command's exit says; a signal the Gate got while it ran stops it, however it then exited. */
+function answer(exitCode, ended) {
+    const signal = received ?? ended;
+    if (signal !== null) {
+        return { status: "fail", exitCode, signal, detail: `was stopped by ${signal}` };
+    }
+    if (exitCode === 0) {
+        return { status: "pass", exitCode, signal };
+    }
+    const notRunnable = exitCode === null ? undefined : NOT_RUNNABLE[exitCode];
+    if (notRunnable !== undefined) {
+        return { status: "error", exitCode, signal, detail: `${notRunnable} (exit ${exitCode})` };
+    }
+    return { status: "fail", exitCode, signal, detail: `exited ${exitCode}` };
+}
+function run(command, root, stdio) {
+    const started = performance.now();
+    return new Promise((resolve) => {
+        const done = (answered) => {
+            running = undefined;
+            resolve({ ...answered, seconds: (performance.now() - started) / 1000 });
+        };
+        const child = spawn(command, { shell: true, cwd: root, stdio });
+        running = child;
+        // A signal that cannot be delivered is an error too; only a child with no pid never started.
+        child.on("error", (error) => {
+            if (child.pid === undefined) {
+                done({ status: "error", exitCode: null, signal: null, detail: `could not start: ${error.message}` });
+            }
+        });
+        child.once("exit", (exitCode, signal) => done(answer(exitCode, signal)));
+    });
+}
+export async function runCommand(command, root, output) {
+    if (output !== "capture") {
+        return { ...(await run(command, root, ["ignore", output === "stderr" ? 2 : "inherit", "inherit"])), tail: null };
+    }
+    // Both streams share one open file, so its lines keep the order the command wrote them in. The file
+    // leaves the disk before the command starts, so no run, an interrupted one included, leaves it behind.
+    const scratch = mkdtempSync(join(tmpdir(), "dw-sdlc-run-"));
+    const fd = openSync(join(scratch, "output"), "w+");
+    rmSync(scratch, { recursive: true, force: true });
+    try {
+        const ran = await run(command, root, ["ignore", fd, fd]);
+        return { ...ran, tail: ran.status === "pass" ? null : lastLines(written(fd)) };
+    }
+    finally {
+        closeSync(fd);
+    }
+}

package/dist/setup-gate.js

@@ -1,28 +1,19 @@
 // What `dw-sdlc setup` changes to adopt the Gate, in files the repository commits: the `dw-sdlc`
 // devDependency in package.json, pinned to the version that runs the setup, and the `gate` key of the
 // committed config. Each answers with the file's next text, or why the file stays as it is.
-import { readFileSync } from "node:fs";
-import { join } from "node:path";
 import { CHECK_NAMES } from "./checks/index.js";
 import { appendKey, isObject, parseObject, render } from "./json-text.js";
+import { packageVersion } from "./package-version.js";
 const PACKAGE = "dw-sdlc";
 /**
  * The Checks a new `gate` key turns on: each judges a tree as it is, the agent map aside, which the
- * setup never writes and the first Gate names. The rest read an input a repository adds first, a
- * catalogue, a records directory, docs a glob matches or a Ratchet's baseline, so they start `false`.
+ * setup never writes and the first Gate names. The rest read an input a repository adds first, so they
+ * start `false`.
  */
 const ON_BY_DEFAULT = new Set(["agents-map", "markdown-refs", "temporal-language", "comment-budget"]);
 /** Where a committed config the setup creates points `$schema`: the schema the pinned package installs. */
 const SCHEMA = `../node_modules/${PACKAGE}/config/agentic.config.schema.json`;
 const NOT_AN_OBJECT = "is not a JSON object; fix it by hand first";
-/** This package's version, the one a pin names, so the plugin and the repository run the same code. */
-function packageVersion() {
-    const manifest = parseObject(readFileSync(join(import.meta.dirname, "..", "package.json"), "utf8"));
-    if (typeof manifest?.version !== "string") {
-        throw new Error(`${PACKAGE}'s package.json names no version`);
-    }
-    return manifest.version;
-}
 /** `a`, `a and b`, `a, b and c`. */
 function list(items) {
     return items.length < 2 ? items.join("") : `${items.slice(0, -1).join(", ")} and ${items.at(-1)}`;

package/dist/setup-worker.d.ts

@@ -0,0 +1,11 @@
+import { type JsonObject } from "./json-text.ts";
+/** The `worker` block a local file holds, carried through on every run, `--force` included. */
+export declare function keptWorker(existing: unknown): JsonObject | undefined;
+/**
+ * The `worker` block to write: the one the file holds, with `command` added when it has none and `cswap`
+ * is on PATH. A command already there, whatever it holds, stays; without `cswap` nothing is added.
+ */
+export declare function pinnedWorker(kept: JsonObject | undefined, pathVariable: string | undefined): {
+    worker: JsonObject | undefined;
+    detail?: string;
+};

package/dist/setup-worker.js

@@ -0,0 +1,37 @@
+// The `worker` block of the machine's local layer: the command a Worker starts with, which the setup
+// writes once when `cswap` is on PATH so no prompt ever carries it.
+import { accessSync, constants, statSync } from "node:fs";
+import { delimiter, join } from "node:path";
+import { isObject } from "./json-text.js";
+/** The command that starts a Worker on the account `cswap` maps to the repository, prompts bypassed. */
+const CSWAP_WORKER_COMMAND = "cswap run -- --dangerously-skip-permissions";
+/** Whether an executable file `name` sits in a directory of `pathVariable`, a PATH as the shell reads it. */
+function onPath(name, pathVariable) {
+    return (pathVariable ?? "").split(delimiter).some((dir) => {
+        if (dir === "") {
+            return false;
+        }
+        try {
+            const file = join(dir, name);
+            accessSync(file, constants.X_OK);
+            return statSync(file).isFile();
+        }
+        catch {
+            return false;
+        }
+    });
+}
+/** The `worker` block a local file holds, carried through on every run, `--force` included. */
+export function keptWorker(existing) {
+    return isObject(existing) && isObject(existing.worker) ? existing.worker : undefined;
+}
+/**
+ * The `worker` block to write: the one the file holds, with `command` added when it has none and `cswap`
+ * is on PATH. A command already there, whatever it holds, stays; without `cswap` nothing is added.
+ */
+export function pinnedWorker(kept, pathVariable) {
+    if ((kept !== undefined && "command" in kept) || !onPath("cswap", pathVariable)) {
+        return { worker: kept };
+    }
+    return { worker: { ...kept, command: CSWAP_WORKER_COMMAND }, detail: `worker.command: ${CSWAP_WORKER_COMMAND}` };
+}

package/dist/working-tree.d.ts

@@ -0,0 +1,13 @@
+/** `git <args>` in the repository at `root`, on `index` when given. */
+export declare function git(root: string, args: string[], index?: string): {
+    out: string;
+} | {
+    error: string;
+};
+/** The tree of the checkout at `root` and its git dir, or why it has none. */
+export declare function workingTree(root: string): {
+    tree: string;
+    gitDir: string;
+} | {
+    error: string;
+};

package/dist/working-tree.js

@@ -0,0 +1,60 @@
+// A checkout's working tree as git would commit it: the tree of every file git tracks or would track,
+// hashed on a copy of the index. The Gate's cache fingerprints it and the watch for Drift records it.
+import { spawnSync } from "node:child_process";
+import { copyFileSync, existsSync, mkdtempSync, rmSync, statSync, utimesSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { repositoryFreeEnv } from "./git-env.js";
+/** `git <args>` in the repository at `root`, on `index` when given. */
+export function git(root, args, index) {
+    const env = repositoryFreeEnv();
+    const result = spawnSync("git", ["-C", root, ...args], {
+        encoding: "utf8",
+        env: index === undefined ? env : { ...env, GIT_INDEX_FILE: index },
+        // A Step that writes thousands of files makes a diff-tree past the default 1 MiB.
+        maxBuffer: 64 * 1024 * 1024
+    });
+    if (result.status === 0) {
+        return { out: result.stdout.trim() };
+    }
+    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"}`}` };
+}
+/**
+ * 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
+ * rebase, and a new untracked file changes it while an ignored one does not.
+ */
+function treeOf(root, gitDir) {
+    const scratch = mkdtempSync(join(tmpdir(), "dw-sdlc-gate-"));
+    const index = join(scratch, "index");
+    const real = join(gitDir, "index");
+    try {
+        if (existsSync(real)) {
+            // git trusts a cached stat only when the index is newer than the file, so the copy takes the mtime
+            // the real one had before it was read: a newer one would hide an edit made in that same second.
+            const { atime, mtime } = statSync(real);
+            copyFileSync(real, index);
+            utimesSync(index, atime, mtime);
+        }
+        const added = git(root, ["add", "-A"], index);
+        return "error" in added ? added : git(root, ["write-tree"], index);
+    }
+    finally {
+        rmSync(scratch, { recursive: true, force: true });
+    }
+}
+/** The tree of the checkout at `root` and its git dir, or why it has none. */
+export function workingTree(root) {
+    try {
+        const gitDir = git(root, ["rev-parse", "--absolute-git-dir"]);
+        if ("error" in gitDir) {
+            return gitDir;
+        }
+        const tree = treeOf(root, gitDir.out);
+        return "error" in tree ? tree : { tree: tree.out, gitDir: gitDir.out };
+    }
+    catch (error) {
+        return { error: error instanceof Error ? error.message : String(error) };
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dw-sdlc",
-  "version": "0.7.0",
+  "version": "0.10.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": {

package/templates/router.md

@@ -16,6 +16,7 @@ skips. Before you research, open the clones whose `when` matches the task.
 <!-- references:start — written from .ai/references.json by the setup; edit the file -->
 
 No Reference is declared yet: `/sdlc-references-add <repository>` adds one.
+
 <!-- references:end -->
 
 ## Rules