dw-sdlc 0.6.0 → 0.9.0

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/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,7 +1,7 @@
 {
   "name": "dw-sdlc",
-  "version": "0.6.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, and the Sync and setup of References; the resolver of the config's layers, its JSON Schema and the validator that reads it.",
+  "version": "0.9.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": {
     "type": "git",

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