dw-sdlc 0.7.0 → 0.9.0

package/dist/drift.d.ts

@@ -0,0 +1,17 @@
+import type { Gate } from "./agentic-config.ts";
+import type { Failure } from "./report.ts";
+import { type Status } from "./run-command.ts";
+/** What a Step answered, and one failure per file it created, changed or deleted. */
+export type Watched<T> = {
+    result: T;
+    failures: Failure[];
+};
+/** Steps run under watch, and what the watch found. */
+export type DriftWatch = {
+    /** Runs one Step by `run` between two records of the tree. */
+    step: <T>(command: string, run: () => Promise<T>) => Promise<Watched<T>>;
+    /** `fail` once a Step drifted, `error` once the tree could not be recorded, `pass` otherwise. */
+    status: () => Status;
+};
+/** A watch over the Steps of `gate` at `root`; under `gate.drift: "allow"` it only runs them. */
+export declare function watchDrift(root: string, gate: Gate): DriftWatch;

package/dist/drift.js

@@ -0,0 +1,68 @@
+// Drift: a file a Step creates, changes or deletes while the Gate runs. Before and after each Step the
+// Gate records the tree of every file git tracks or would track, never against HEAD, so an ignored
+// file never drifts and an edit made before the run sits in both records.
+import { stoppedBy } from "./run-command.js";
+import { git, workingTree } from "./working-tree.js";
+const REMEDIES = {
+    drift: "commit the change, or make the Step only read",
+    cannotWatch: 'run the Gate in a git checkout, or set gate.drift to "allow"'
+};
+/** What a letter of `git diff-tree --name-status` did to the file; T is a change of type, as a link to a file. */
+const CHANGES = { A: "created", D: "deleted", M: "changed", T: "changed" };
+/** One failure per file that differs between the trees `before` and `after`, naming `command`. */
+function drifted(root, command, before, after) {
+    if (before === after) {
+        return [];
+    }
+    const diff = git(root, ["diff-tree", "-r", "-z", "--no-renames", "--name-status", before, after]);
+    if ("error" in diff) {
+        return diff;
+    }
+    // NUL-terminated pairs: the letter, then the path, which may hold any byte but NUL.
+    return [...diff.out.matchAll(/([A-Z])\0([^\0]+)\0/g)].map(([, letter = "", file = ""]) => {
+        const message = `${JSON.stringify(command)} ${CHANGES[letter] ?? "changed"} it`;
+        return { file, rule: "drift", message, remedy: REMEDIES.drift };
+    });
+}
+/** A watch over the Steps of `gate` at `root`; under `gate.drift: "allow"` it only runs them. */
+export function watchDrift(root, gate) {
+    let status = "pass";
+    let watching = gate.drift !== "allow";
+    /** The tree after the last Step, the record before the next: nothing runs between two Steps. */
+    let last;
+    /** The one failure of a tree that cannot be recorded; the watch stops there. */
+    const cannotWatch = (command, error) => {
+        watching = false;
+        status = "error";
+        const message = `cannot watch ${JSON.stringify(command)}: ${error}`;
+        return [{ rule: "drift", message, remedy: REMEDIES.cannotWatch }];
+    };
+    const step = async (command, run) => {
+        if (!watching) {
+            return { result: await run(), failures: [] };
+        }
+        const before = last === undefined ? workingTree(root) : { tree: last };
+        const result = await run();
+        if ("error" in before) {
+            return { result, failures: cannotWatch(command, before.error) };
+        }
+        if (stoppedBy() !== undefined) {
+            // A signal cut the Step short and ends the Gate, so nothing is compared after it.
+            return { result, failures: [] };
+        }
+        const after = workingTree(root);
+        if ("error" in after) {
+            return { result, failures: cannotWatch(command, after.error) };
+        }
+        last = after.tree;
+        const found = drifted(root, command, before.tree, after.tree);
+        if ("error" in found) {
+            return { result, failures: cannotWatch(command, found.error) };
+        }
+        if (found.length > 0) {
+            status = "fail";
+        }
+        return { result, failures: found };
+    };
+    return { step, status: () => status };
+}

package/dist/gate-cache.d.ts

@@ -0,0 +1,13 @@
+import type { Gate } from "./agentic-config.ts";
+/** A checkout's fingerprint and the file its last green run is stamped in. */
+export type Fingerprint = {
+    key: string;
+    stampFile: string;
+};
+/** The fingerprint of the checkout at `root` judged by `gate`, or why it has none. */
+export declare function fingerprint(root: string, gate: Gate): Fingerprint | {
+    error: string;
+};
+/** Whether the last green run of this checkout was stamped with this fingerprint. */
+export declare function isGreen({ key, stampFile }: Fingerprint): boolean;
+export declare function stampGreen({ key, stampFile }: Fingerprint): void;

package/dist/gate-cache.js

@@ -0,0 +1,39 @@
+// The Gate's cache. A checkout's fingerprint is its working tree's content and the Gate that judges
+// it. A green run stamps it in the checkout's own git dir, so each worktree keeps its own stamp.
+import { createHash } from "node:crypto";
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { packageVersion } from "./package-version.js";
+import { workingTree } from "./working-tree.js";
+const STAMP_FILE = "dw-sdlc-gate.green";
+/** The fingerprint of the checkout at `root` judged by `gate`, or why it has none. */
+export function fingerprint(root, gate) {
+    const found = workingTree(root);
+    if ("error" in found) {
+        return found;
+    }
+    try {
+        const judge = createHash("sha256").update(JSON.stringify({ version: packageVersion(), gate }));
+        return { key: `${found.tree} ${judge.digest("hex")}`, stampFile: join(found.gitDir, STAMP_FILE) };
+    }
+    catch (error) {
+        return { error: error instanceof Error ? error.message : String(error) };
+    }
+}
+/** Whether the last green run of this checkout was stamped with this fingerprint. */
+export function isGreen({ key, stampFile }) {
+    try {
+        return readFileSync(stampFile, "utf8").trim() === key;
+    }
+    catch {
+        return false;
+    }
+}
+export function stampGreen({ key, stampFile }) {
+    try {
+        writeFileSync(stampFile, `${key}\n`);
+    }
+    catch {
+        // A stamp that cannot be written only means the next run does not skip.
+    }
+}

package/dist/git-env.d.ts

@@ -0,0 +1,2 @@
+/** This process's environment without the variables that tie git to one repository, as git lists them. */
+export declare function repositoryFreeEnv(): NodeJS.ProcessEnv;

package/dist/git-env.js

@@ -0,0 +1,10 @@
+// The environment a git command runs under to find its repository from its own directory, as a git
+// hook's GIT_DIR or GIT_INDEX_FILE would otherwise aim it at the hook's repository.
+import { spawnSync } from "node:child_process";
+let repositoryVars;
+/** This process's environment without the variables that tie git to one repository, as git lists them. */
+export function repositoryFreeEnv() {
+    repositoryVars ??= new Set((spawnSync("git", ["rev-parse", "--local-env-vars"], { encoding: "utf8" }).stdout ?? "").split("\n").filter(Boolean));
+    const vars = repositoryVars;
+    return Object.fromEntries(Object.entries(process.env).filter(([name]) => !vars.has(name)));
+}

package/dist/markdown.d.ts

@@ -25,6 +25,25 @@ export declare function codeSpans(text: string): string[];
 export declare function prose(text: string): string;
 /** Every link target in the prose of `text`, its angle brackets dropped, with its 1-based line. */
 export declare function links(text: string): Link[];
+/** A value of a frontmatter, with its 1-based line. */
+export type FrontmatterValue = {
+    value: string;
+    line: number;
+};
+/** A top-level key of a frontmatter: the value after its colon, and the items of the block list under it. */
+export type FrontmatterEntry = FrontmatterValue & {
+    items: FrontmatterValue[];
+};
+/**
+ * The top-level keys of the frontmatter `text` opens with, none when it opens with none. A key written
+ * twice is read where it first appears.
+ */
+export declare function frontmatter(text: string): Map<string, FrontmatterEntry>;
+/**
+ * The values a list key names: comma-separated after its colon, in `[…]` or not, or else its items. A comma
+ * inside a glob's `{…}` separates none, and an empty value is dropped.
+ */
+export declare function frontmatterList(key: FrontmatterEntry | undefined): FrontmatterValue[];
 /** The anchors of each markdown file read so far, by path. */
 export type Anchors = Map<string, Set<string>>;
 /** The anchors of the headings of `path` under `root`; none when it is not a file. */

package/dist/markdown.js

@@ -1,6 +1,6 @@
 // The parts of a markdown file the Checks read: its ATX headings with the anchors GitHub gives them,
-// the rows of a table under a heading, its links, and its prose with the code masked; and the anchors
-// of a file on disk. A line inside a fenced code block is never any of them.
+// the rows of a table under a heading, its links, its prose with the code masked and the keys of its
+// frontmatter; and the anchors of a file on disk. A line inside a fenced code block is never any of them.
 import { readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 /** A code fence at any indent, so one inside a list item counts. */
@@ -103,6 +103,50 @@ export function links(text) {
         return targets.map((target) => ({ target: target.replace(/^<(.*)>$/, "$1"), line: index + 1 }));
     });
 }
+/** A scalar as YAML reads it: the text between its quotes, or else the text before a ` #` comment. */
+function scalar(text) {
+    const quoted = /^\s*(["'])(.*?)\1\s*(#.*)?$/.exec(text);
+    return quoted?.[2] ?? text.replace(/(^|\s)#.*$/, "").trim();
+}
+/**
+ * The top-level keys of the frontmatter `text` opens with, none when it opens with none. A key written
+ * twice is read where it first appears.
+ */
+export function frontmatter(text) {
+    const keys = new Map();
+    const lines = text.split("\n");
+    if (lines[0]?.trim() !== "---") {
+        return keys;
+    }
+    let current;
+    for (let index = 1; index < lines.length && lines[index]?.trim() !== "---"; index++) {
+        const line = lines[index] ?? "";
+        const [, name, rest = ""] = /^([\w-]+):(.*)$/.exec(line) ?? [];
+        const item = /^\s*-(?:\s+(.*))?$/.exec(line);
+        if (name !== undefined) {
+            current = keys.has(name) ? undefined : { value: scalar(rest), line: index + 1, items: [] };
+            if (current !== undefined) {
+                keys.set(name, current);
+            }
+        }
+        else if (item !== null) {
+            current?.items.push({ value: scalar(item[1] ?? ""), line: index + 1 });
+        }
+    }
+    return keys;
+}
+/**
+ * The values a list key names: comma-separated after its colon, in `[…]` or not, or else its items. A comma
+ * inside a glob's `{…}` separates none, and an empty value is dropped.
+ */
+export function frontmatterList(key) {
+    if (key === undefined) {
+        return [];
+    }
+    const inline = key.value.replace(/^\[(.*)\]$/, "$1");
+    const values = inline === "" ? key.items : inline.split(/,(?![^{]*\})/).map((value) => ({ value: scalar(value), line: key.line }));
+    return values.filter(({ value }) => value !== "");
+}
 /** The anchors of the headings of `path` under `root`; none when it is not a file. */
 export function anchorsOf(root, path, cache) {
     let anchors = cache.get(path);

package/dist/package-version.d.ts

@@ -0,0 +1,2 @@
+/** This package's version; throws when its manifest names none. */
+export declare function packageVersion(): string;

package/dist/package-version.js

@@ -0,0 +1,13 @@
+// The version of this package, read from its own manifest: one directory above `src/` in the source
+// and above `dist/` in what npm installs.
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parseObject } from "./json-text.js";
+/** This package's version; throws when its manifest names none. */
+export function packageVersion() {
+    const manifest = parseObject(readFileSync(join(import.meta.dirname, "..", "package.json"), "utf8"));
+    if (typeof manifest?.version !== "string") {
+        throw new Error("dw-sdlc's package.json names no version");
+    }
+    return manifest.version;
+}

package/dist/pr/decide.d.ts

@@ -1,10 +1,24 @@
-import type { PrMerge } from "../agentic-config.ts";
+import type { PrMerge, PrReview } from "../agentic-config.ts";
 import type { PrState } from "./state.ts";
 export type Status = "act" | "wait" | "park" | "done";
 export type Actor = "script" | "agent" | "dev";
-export type Action = "done" | "stop" | "wait" | "fix-conflicts" | "update-branch" | "fix-ci" | "address-review" | "review" | "unverified" | "ci-stuck" | "awaiting-reply" | "mark-ready" | "awaiting-approval" | "ready-to-merge" | "merge";
+export type Action = "done" | "stop" | "wait" | "fix-conflicts" | "update-branch" | "fix-ci" | "address-review" | "review" | "mark-reviewed" | "unverified" | "ci-stuck" | "awaiting-reply" | "mark-ready" | "awaiting-author" | "awaiting-approval" | "ready-to-merge" | "merge";
 /** The Actions the script performs itself, each one gh command. */
-export type ScriptAction = "update-branch" | "mark-ready" | "merge";
+export type ScriptAction = "update-branch" | "mark-ready" | "mark-reviewed" | "merge";
+/** Where a Review depth comes from: the dev's `--review` for this call, or `pr.review`. */
+export type DepthSource = "flag" | "config";
+/**
+ * What the decision reads beside the pull request: who merges it, how closely a Review reads it, and
+ * the slash command a `full` Review runs.
+ */
+export type Policy = {
+    merge: PrMerge;
+    review: {
+        depth: PrReview;
+        source: DepthSource;
+    };
+    reviewCommand: string;
+};
 /** An Action the pull request needs beside the one its answer names, so one push can fix several. */
 export type Blocker = {
     action: Action;
@@ -20,17 +34,26 @@ export type Answer = Blocker & {
     recheckAfter?: number;
     blockers: Blocker[];
 };
+/** The commit status a clean review of the head leaves on it. */
+export declare const REVIEW = "dw-sdlc/review";
+/** Its one state: a failure or a pending status would turn the pull request unstable. */
+export declare const REVIEW_STATE = "success";
 /** The words as one POSIX shell command line, each word that needs it single-quoted. */
 export declare function shellLine(words: string[]): string;
+/**
+ * The gh arguments that post the `dw-sdlc/review` success on the head, `description` saying how it was
+ * read. The path names the repository, so the call reads the same from any checkout.
+ */
+export declare function reviewStatusArgs(pr: PrState, description: string): string[];
 export declare function isScriptAction(action: Action): action is ScriptAction;
 /**
  * The gh arguments of a script Action, `-R` naming the repository when `named`. The update merges the
  * base in, never --rebase, which rewrites the branch on GitHub; the merge names the head it read.
  */
-export declare function hostArgs(pr: PrState, action: ScriptAction, named: boolean): string[];
+export declare function hostArgs(pr: PrState, action: ScriptAction, policy: Policy, named: boolean): string[];
 /** The command a script Action leaves the dev to run, from a checkout of the repository. */
-export declare function devCommand(pr: PrState, action: ScriptAction): string;
+export declare function devCommand(pr: PrState, action: ScriptAction, policy: Policy): string;
 /** The merge left to the dev, `reason` saying why it is theirs. */
-export declare function readyToMerge(pr: PrState, reason: string): Omit<Answer, "blockers">;
-/** The Action `pr` needs at `now`, milliseconds since the epoch, when `merge` says who merges it. */
-export declare function decide(pr: PrState, now: number, merge: PrMerge): Answer;
+export declare function readyToMerge(pr: PrState, policy: Policy, reason: string): Omit<Answer, "blockers">;
+/** The Action `pr` needs at `now`, milliseconds since the epoch, under `policy`. */
+export declare function decide(pr: PrState, now: number, policy: Policy): Answer;

package/dist/pr/decide.js

@@ -8,7 +8,9 @@ const BUDGET_MINUTES = 40;
 /** The prefix of the contexts the script posts itself, as `dw-sdlc/review`: never CI. */
 const OWN_PREFIX = "dw-sdlc/";
 /** The commit status a clean review of the head leaves on it. */
-const REVIEW = "dw-sdlc/review";
+export const REVIEW = "dw-sdlc/review";
+/** Its one state: a failure or a pending status would turn the pull request unstable. */
+export const REVIEW_STATE = "success";
 /** The words as one POSIX shell command line, each word that needs it single-quoted. */
 export function shellLine(words) {
     return words.map((word) => (/^[\w./:=@%+,-]+$/.test(word) ? word : `'${word.replaceAll("'", `'\\''`)}'`)).join(" ");
@@ -33,10 +35,25 @@ function threads(pr, lastByViewer) {
 function listed({ id, path, line, author, body }) {
     return { id, path, line, author, body };
 }
+/**
+ * The gh arguments that post the `dw-sdlc/review` success on the head, `description` saying how it was
+ * read. The path names the repository, so the call reads the same from any checkout.
+ */
+export function reviewStatusArgs(pr, description) {
+    const fields = { state: REVIEW_STATE, context: REVIEW, target_url: pr.url, description };
+    const flags = Object.entries(fields).flatMap(([key, value]) => ["-f", `${key}=${value}`]);
+    return ["api", `repos/${pr.repo}/statuses/${pr.head}`, "--method", "POST", "--silent", ...flags];
+}
+/** Why a head no one reads carries the success: the dev's word or the config. */
+function offDescription(policy) {
+    return `off: ${policy.review.source === "flag" ? "--review off" : "pr.review"}`;
+}
+/** A script Action's gh arguments; `repo` is `-R` and the repository when the call names it, else empty. */
 const HOST = {
-    "update-branch": { verb: "update-branch", flags: () => [] },
-    "mark-ready": { verb: "ready", flags: () => [] },
-    merge: { verb: "merge", flags: (pr) => ["--squash", "--match-head-commit", pr.head] }
+    "update-branch": (pr, repo) => ["pr", "update-branch", String(pr.number), ...repo],
+    "mark-ready": (pr, repo) => ["pr", "ready", String(pr.number), ...repo],
+    "mark-reviewed": (pr, _, policy) => reviewStatusArgs(pr, offDescription(policy)),
+    merge: (pr, repo) => ["pr", "merge", String(pr.number), ...repo, "--squash", "--match-head-commit", pr.head]
 };
 export function isScriptAction(action) {
     return Object.hasOwn(HOST, action);
@@ -45,17 +62,16 @@ export function isScriptAction(action) {
  * The gh arguments of a script Action, `-R` naming the repository when `named`. The update merges the
  * base in, never --rebase, which rewrites the branch on GitHub; the merge names the head it read.
  */
-export function hostArgs(pr, action, named) {
-    const { verb, flags } = HOST[action];
-    return ["pr", verb, String(pr.number), ...(named ? ["-R", pr.repo] : []), ...flags(pr)];
+export function hostArgs(pr, action, policy, named) {
+    return HOST[action](pr, named ? ["-R", pr.repo] : [], policy);
 }
 /** The command a script Action leaves the dev to run, from a checkout of the repository. */
-export function devCommand(pr, action) {
-    return shellLine(["gh", ...hostArgs(pr, action, false)]);
+export function devCommand(pr, action, policy) {
+    return shellLine(["gh", ...hostArgs(pr, action, policy, false)]);
 }
 /** The merge left to the dev, `reason` saying why it is theirs. */
-export function readyToMerge(pr, reason) {
-    return { status: "park", action: "ready-to-merge", actor: "dev", reason, command: devCommand(pr, "merge") };
+export function readyToMerge(pr, policy, reason) {
+    return { status: "park", action: "ready-to-merge", actor: "dev", reason, command: devCommand(pr, "merge", policy) };
 }
 const ROWS = [
     {
@@ -125,24 +141,30 @@ const ROWS = [
         answer: () => ({ status: "act", action: "address-review", actor: "agent", reason: "changes requested" })
     },
     {
-        when: (pr) => !pr.checks.some((check) => check.name === REVIEW && check.bucket === "pass"),
-        answer: (pr) => ({
-            status: "act",
-            action: "review",
-            actor: "agent",
-            reason: `no ${REVIEW} success on ${pr.head.slice(0, 7)}`
-        })
+        // The dev merges another author's pull request, so it needs no Review. Under off no one reads
+        // the head: the script posts the success itself.
+        when: (pr) => pr.viewerDidAuthor && !pr.checks.some((check) => check.name === REVIEW && check.bucket === "pass"),
+        answer: (pr, _, { review, reviewCommand }) => {
+            const off = review.depth === "off";
+            return {
+                status: "act",
+                action: off ? "mark-reviewed" : "review",
+                actor: off ? "script" : "agent",
+                reason: `no ${REVIEW} success on ${pr.head.slice(0, 7)}`,
+                details: { ...review, ...(review.depth === "full" ? { reviewCommand } : {}) }
+            };
+        }
     },
     {
         when: (pr) => ciOf(pr).length === 0,
-        answer: (pr, now) => now - Date.parse(pr.headCommittedAt) <= GRACE_SECONDS * 1000
+        answer: (pr, now, policy) => now - Date.parse(pr.headCommittedAt) <= GRACE_SECONDS * 1000
             ? { status: "wait", action: "wait", actor: "script", reason: "unverified", recheckAfter: 15 }
             : {
                 status: "park",
                 action: "unverified",
                 actor: "dev",
                 reason: `no check reported on ${pr.head.slice(0, 7)} within ${GRACE_SECONDS} s of its commit`,
-                command: devCommand(pr, "merge")
+                command: devCommand(pr, "merge", policy)
             }
     },
     {
@@ -173,9 +195,18 @@ const ROWS = [
         })
     },
     {
-        when: (pr) => pr.draft,
+        when: (pr) => pr.draft && pr.viewerDidAuthor,
         answer: () => ({ status: "act", action: "mark-ready", actor: "script", reason: "still a draft" })
     },
+    {
+        when: (pr) => pr.draft && !pr.viewerDidAuthor,
+        answer: () => ({
+            status: "park",
+            action: "awaiting-author",
+            actor: "dev",
+            reason: "another author's draft: marking it ready is the author's"
+        })
+    },
     {
         when: (pr) => pr.reviewDecision === "REVIEW_REQUIRED",
         answer: () => ({
@@ -187,30 +218,33 @@ const ROWS = [
     },
     {
         when: (pr) => !pr.viewerDidAuthor,
-        answer: (pr) => readyToMerge(pr, "another author's pull request: the merge is the dev's"),
+        answer: (pr, _, policy) => readyToMerge(pr, policy, "another author's pull request: the merge is the dev's"),
         merging: true
     },
     {
-        when: (_, merge) => merge === "auto",
+        when: (_, { merge }) => merge === "auto",
         answer: () => ({ status: "act", action: "merge", actor: "script", reason: "green, reviewed and the viewer's own" }),
         merging: true
     },
     {
-        when: (_, merge) => merge === "ask",
-        answer: (pr) => readyToMerge(pr, "pr.merge is ask: the merge is the dev's"),
+        when: (_, { merge }) => merge === "ask",
+        answer: (pr, _, policy) => readyToMerge(pr, policy, "pr.merge is ask: the merge is the dev's"),
         merging: true
     }
 ];
 function blockerOf({ action, actor, reason, details }) {
     return { action, actor, reason, ...(details === undefined ? {} : { details }) };
 }
-/** The Action `pr` needs at `now`, milliseconds since the epoch, when `merge` says who merges it. */
-export function decide(pr, now, merge) {
-    const index = ROWS.findIndex((row) => row.when(pr, merge));
+/** The Action `pr` needs at `now`, milliseconds since the epoch, under `policy`. */
+export function decide(pr, now, policy) {
+    const index = ROWS.findIndex((row) => row.when(pr, policy));
     const row = ROWS[index];
     if (row === undefined) {
-        throw new Error(`no row of the decision matches ${pr.url} under pr.merge ${merge}`);
+        throw new Error(`no row of the decision matches ${pr.url} under pr.merge ${policy.merge}`);
     }
-    const later = row.alone === true ? [] : ROWS.slice(index + 1).filter((other) => !other.merging && other.when(pr, merge));
-    return { ...row.answer(pr, now), blockers: later.map((other) => blockerOf(other.answer(pr, now))) };
+    const later = row.alone === true ? [] : ROWS.slice(index + 1).filter((other) => !other.merging && other.when(pr, policy));
+    return {
+        ...row.answer(pr, now, policy),
+        blockers: later.map((other) => blockerOf(other.answer(pr, now, policy)))
+    };
 }

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>;