dw-sdlc 0.6.0 → 0.9.0

package/dist/commands/gate.js

@@ -1,39 +1,67 @@
 // `dw-sdlc gate`: the Gate of a repository, from the `gate` key of its resolved agentic config. The
 // run and the report serve `dw-sdlc check` too, which judges one Check of it.
-import { spawnSync } from "node:child_process";
 import { parseArgs } from "node:util";
 import { repositoryRoot, resolveConfig } from "../agentic-config.js";
 import { CannotRun } from "../checks/check.js";
 import { CHECK_NAMES, enabledChecks, shippedCheck } from "../checks/index.js";
+import { watchDrift } from "../drift.js";
+import { fingerprint, isGreen, stampGreen } from "../gate-cache.js";
 import { annotation, failureJson, failureLine } from "../report.js";
+import { holdingSignals, runCommand, stoppedBy, TAIL_LINES } from "../run-command.js";
 export const summary = "run the Gate: the Steps of gate.steps in order, then every Check under gate.checks";
-const USAGE = `Usage: dw-sdlc gate [--json] [--root <dir>] [--update-baseline]
+const USAGE = `Usage: dw-sdlc gate [--json] [--verbose] [--root <dir>] [--update-baseline | --cache]
 
 Runs the Gate of the repository holding --root (default: the current directory): each Step of
-gate.steps in order from the repository root, its output passed through, stopping at the first that
-fails; then every Check under gate.checks, the run scripts and then the Checks the package ships,
-none stopping the next. Prints one line per failure: the file where there is one, the rule, the
-remedy; under GitHub Actions each line is also a workflow annotation. --json prints one document
-instead and sends the commands' own output to stderr.
+gate.steps in order from the repository root, stopping at the first that fails; then every Check
+under gate.checks, the run scripts and then the Checks the package ships, none stopping the next.
+
+Prints one line per Step with its time, one per Check, one per failure and a last line, green or
+failed. A failure line names the file where there is one, the rule and the remedy; under GitHub
+Actions it is also a workflow annotation. A Step or run script prints nothing of its own unless it
+does not pass: then its last ${TAIL_LINES} lines, both streams in the order written, under its own
+line. In a terminal a Step's line shows when it starts and takes its result when it ends.
+
+Each Step runs between two records of every file git tracks or would track: a file the Step created,
+changed or deleted is Drift, one failure per file, and the Steps after it still run. Ignored files
+and edits made before the run never drift, and a Step a signal stopped is not compared. gate.drift
+"allow" turns the watch off.
+
+SIGINT or SIGTERM sent while a command runs stops it and everything after it, and the report still
+prints: the stopped command's last lines, its failure line and the last line. A second signal, or one
+sent while the Checks the package ships run, ends the Gate at once.
+
+--verbose passes each command's output through as it runs instead, under a line naming the command,
+and keeps no tail. --json prints the document alone; each Step and Check in it carries tail, the last
+${TAIL_LINES} lines of a command that did not pass, null otherwise. With --verbose, under --json, the
+commands' output goes to stderr and every tail is null.
 
 --update-baseline then rewrites the baseline of each Ratchet, only when every Step and every other
-Check passed, and only tighter: a file now within its limit leaves it and no file joins. Where there
-is no baseline, it records one. The Ratchet is judged again on what it wrote.
+Check passed and no Step drifted, and only tighter: a file now within its limit leaves it and no
+file joins. Where there is no baseline, it records one. The Ratchet is judged again on what it wrote.
+
+--cache skips the run when the working tree and the Gate match the last green run in this checkout.
+Untracked files count and ignored files do not. Each worktree keeps its own stamp. A tree it cannot
+hash runs the whole Gate.
 
-Exit 0 when everything passes, 1 when a Step or a Check fails, 2 when the Gate cannot run: an
-invalid config layer, a Step or Check whose command the shell cannot find or execute, or a Check
-missing an input it reads.`;
+Exit 0 when everything passes, 1 when a Step or a Check fails or a Step drifts, 2 when the Gate
+cannot run: an invalid config layer, a Step or Check whose command the shell cannot find or execute,
+a Check missing an input it reads, or a tree it cannot record for Drift.`;
 const EXIT_CODES = { pass: 0, fail: 1, error: 2 };
-/** 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 SKIPPED = { status: "skipped", exitCode: null };
-/** One Check run by name says nothing before its result. */
-const QUIET = { write: () => true };
+const SKIPPED = { status: "skipped", exitCode: null, tail: null };
+const SILENT = { write: () => true };
+const STATUS_WORDS = {
+    pass: "pass",
+    fail: "failed",
+    error: "cannot run",
+    skipped: "skipped"
+};
 const REMEDIES = {
     invalidLayer: "fix the file; the Gate runs once every layer is valid",
-    failed: "fix what it printed above",
-    stepNotRunnable: "install the command or fix gate.steps in the agentic config",
-    checkNotRunnable: "install the command or fix gate.checks.run in the agentic config",
+    failed: "fix what it printed above; run it alone for the full output",
+    notRunnable: {
+        step: "install the command or fix gate.steps in the agentic config",
+        check: "install the command or fix gate.checks.run in the agentic config"
+    },
     checkStopped: "fix what stopped it, or report it to dw-sdlc"
 };
 function plural(count, noun) {
@@ -46,16 +74,20 @@ function parseCli(argv) {
             options: {
                 help: { type: "boolean", short: "h" },
                 json: { type: "boolean" },
+                verbose: { type: "boolean" },
                 root: { type: "string" },
-                "update-baseline": { type: "boolean" }
+                "update-baseline": { type: "boolean" },
+                cache: { type: "boolean" }
             }
         });
-        return {
-            help: values.help === true,
-            json: values.json === true,
-            root: values.root,
-            updateBaseline: values["update-baseline"] === true
-        };
+        const refresh = values["update-baseline"] === true;
+        const cache = values.cache === true;
+        if (refresh && cache) {
+            return { error: "--cache and --update-baseline do not combine: a refresh needs the Gate to run" };
+        }
+        const mode = refresh ? "update-baseline" : cache ? "cache" : "plain";
+        const flags = { help: values.help === true, json: values.json === true, verbose: values.verbose === true };
+        return { ...flags, root: values.root, mode };
     }
     catch (error) {
         return { error: error instanceof Error ? error.message : String(error) };
@@ -66,25 +98,64 @@ function configFailure({ file, path, message }) {
     return { file, rule: "config", message: where, remedy: REMEDIES.invalidLayer };
 }
 /**
- * Runs `command` through `sh -c` from `root`, stdin closed and stderr passed through; stdout too, or
- * onto stderr when `--json` keeps stdout for the document. `detail` says what went wrong, when it did.
+ * What follows a Step's or Check's name once it ran: pass, failed or cannot run, with a command's exit,
+ * a Step's time, and a captured tail indented under the line.
  */
-function runCommand(command, root, json) {
-    const result = spawnSync(command, { shell: true, cwd: root, stdio: ["ignore", json ? 2 : "inherit", "inherit"] });
-    if (result.error !== undefined) {
-        return { status: "error", exitCode: null, detail: `could not start: ${result.error.message}` };
+function outcomeText(kind, outcome) {
+    const isCommand = "seconds" in outcome;
+    const exit = isCommand && outcome.status !== "pass" ? howItEnded(outcome) : "";
+    const time = isCommand && kind === "step" ? ` (${Math.round(outcome.seconds)} s)` : "";
+    const head = `${STATUS_WORDS[outcome.status]}${exit}${time}`;
+    if (outcome.tail === null) {
+        return head;
+    }
+    if (outcome.tail.length === 0) {
+        return `${head}; it printed nothing`;
     }
-    if (result.status === 0) {
-        return { status: "pass", exitCode: 0 };
+    const tail = outcome.tail.map((line) => (line === "" ? "" : `  ${line}`));
+    return [`${head}; its last ${TAIL_LINES} lines:`, ...tail].join("\n");
+}
+/** How a command that did not pass ended: the signal that stopped it, or its exit code. */
+function howItEnded({ signal, exitCode }) {
+    if (signal !== null) {
+        return `, stopped by ${signal}`;
     }
-    if (result.status === null) {
-        return { status: "fail", exitCode: null, detail: `was stopped by ${result.signal ?? "a signal"}` };
+    return exitCode === null ? "" : `, exit ${exitCode}`;
+}
+function none() { }
+/** Whether a Step's line goes out before it runs, to take its result in place: only in a terminal. */
+function live(kind) {
+    return kind === "step" && process.stdout.isTTY;
+}
+/**
+ * Quiet, the Gate prints each result, a Step's name first when stdout is a terminal; `--verbose` names
+ * each command before its output; `--json` prints neither. One Check run by name prints only a tail.
+ */
+function progressOf(options, log) {
+    if ("only" in options) {
+        const end = (kind, subject, outcome) => {
+            if (!options.json && outcome.tail !== null) {
+                process.stdout.write(`${kind} ${subject} — ${outcomeText(kind, outcome)}\n`);
+            }
+        };
+        return { start: none, end };
     }
-    const notRunnable = NOT_RUNNABLE[result.status];
-    if (notRunnable !== undefined) {
-        return { status: "error", exitCode: result.status, detail: `${notRunnable} (exit ${result.status})` };
+    if (options.verbose) {
+        return { start: (kind, subject) => log.write(`gate: ${kind} ${subject}\n`), end: none };
     }
-    return { status: "fail", exitCode: result.status, detail: `exited ${result.status}` };
+    if (options.json) {
+        return { start: none, end: none };
+    }
+    return {
+        start: (kind, subject) => {
+            if (live(kind)) {
+                process.stdout.write(`gate: ${kind} ${subject}`);
+            }
+        },
+        end: (kind, subject, outcome) => {
+            process.stdout.write(`${live(kind) ? "" : `gate: ${kind} ${subject}`} — ${outcomeText(kind, outcome)}\n`);
+        }
+    };
 }
 /** What a Check that threw reports: the input it lacks, or what stopped it. */
 function erred(check, error) {
@@ -93,7 +164,7 @@ function erred(check, error) {
         : { message: `stopped: ${error instanceof Error ? error.message : String(error)}`, remedy: REMEDIES.checkStopped };
     return {
         check,
-        outcome: { status: "error", exitCode: EXIT_CODES.error },
+        outcome: { status: "error", exitCode: EXIT_CODES.error, tail: null },
         failures: [{ rule: check.name, ...finding }]
     };
 }
@@ -102,21 +173,22 @@ function runShipped(check, root) {
     try {
         const failures = check.run(root).map((finding) => ({ rule: check.name, ...finding }));
         const status = failures.length === 0 ? "pass" : "fail";
-        return { check, outcome: { status, exitCode: EXIT_CODES[status] }, failures };
+        return { check, outcome: { status, exitCode: EXIT_CODES[status], tail: null }, failures };
     }
     catch (error) {
         return erred(check, error);
     }
 }
 /**
- * Rewrites the baseline of each Ratchet while every Step, every run Check in `others` and every other
- * shipped Check passed, and judges the Ratchet again on what it wrote.
+ * Rewrites the baseline of each Ratchet while every Step, every run Check and the watch for Drift in
+ * `others` and every other shipped Check passed, and judges the Ratchet again on what it wrote.
+ * Returns a line on each.
  */
-function refreshBaselines(judged, others, root, log) {
+function refreshBaselines(judged, others, root) {
     if (!judged.some(({ check }) => check.baseline !== undefined)) {
-        log.write("gate: no Ratchet is turned on, so no baseline to refresh\n");
-        return;
+        return ["gate: no Ratchet is turned on, so no baseline to refresh"];
     }
+    const notes = [];
     for (const [index, { check }] of judged.entries()) {
         if (check.baseline === undefined) {
             continue;
@@ -124,22 +196,23 @@ function refreshBaselines(judged, others, root, log) {
         const { file, refresh } = check.baseline;
         const rest = [...others, ...judged.filter((_, at) => at !== index).map(({ outcome }) => outcome)];
         if (rest.some(({ status }) => status !== "pass")) {
-            log.write(`gate: baseline ${file} not refreshed — a Step or another Check did not pass\n`);
+            notes.push(`gate: baseline ${file} not refreshed — a Step or another Check did not pass`);
             continue;
         }
         try {
-            log.write(`gate: baseline ${file} ${refresh(root)}\n`);
+            notes.push(`gate: baseline ${file} ${refresh(root)}`);
             judged[index] = runShipped(check, root);
         }
         catch (error) {
             if (error instanceof CannotRun) {
-                log.write(`gate: baseline ${file} not refreshed — ${error.finding.message}; ${error.finding.remedy}\n`);
+                notes.push(`gate: baseline ${file} not refreshed — ${error.finding.message}; ${error.finding.remedy}`);
             }
             else {
                 judged[index] = erred(check, error);
             }
         }
     }
+    return notes;
 }
 function worst(outcomes) {
     const statuses = new Set(outcomes.map(({ status }) => status));
@@ -162,10 +235,13 @@ function select(gate, only) {
     }
     return { steps: [], run: scripts, shipped: shipped === undefined ? [] : [shipped] };
 }
-export function runGate(root, options) {
+export async function runGate(root, options) {
     const { json } = options;
     const only = "only" in options ? options.only : undefined;
-    const log = only !== undefined ? QUIET : json ? process.stderr : process.stdout;
+    const mode = "mode" in options ? options.mode : undefined;
+    const log = only !== undefined ? SILENT : json ? process.stderr : process.stdout;
+    const progress = progressOf(options, log);
+    const output = "verbose" in options && options.verbose ? (json ? "stderr" : "stdout") : "capture";
     const { config, problems } = resolveConfig(root);
     const gateCommand = config.gate.command ?? null;
     if (problems.length > 0) {
@@ -175,55 +251,94 @@ export function runGate(root, options) {
     if ("rule" in selected) {
         return { status: "error", command: gateCommand, steps: [], checks: [], failures: [selected] };
     }
+    let toStamp;
+    if (mode === "cache") {
+        const found = fingerprint(root, config.gate);
+        if ("error" in found) {
+            log.write(`gate: cannot fingerprint the tree, so the whole Gate runs — ${found.error}\n`);
+        }
+        else if (isGreen(found)) {
+            return { status: "pass", command: gateCommand, cached: true, steps: [], checks: [], failures: [] };
+        }
+        else {
+            toStamp = found;
+        }
+    }
     const failures = [];
-    /** Runs one Step or Check and records its failure under `rule`, if it has one. */
-    const runOne = (command, rule, notRunnable) => {
-        const { detail, ...outcome } = runCommand(command, root, json);
-        if (detail !== undefined) {
-            const remedy = outcome.status === "error" ? notRunnable : REMEDIES.failed;
-            failures.push({ rule, message: `${JSON.stringify(command)} ${detail}`, remedy });
+    const watch = watchDrift(root, config.gate);
+    /** Runs one Step or Check, prints its progress and records its failure under `rule`, if it has one. */
+    const runOne = async (kind, subject, command) => {
+        progress.start(kind, subject);
+        const ran = await runCommand(command, root, output);
+        progress.end(kind, subject, ran);
+        if (ran.detail !== undefined) {
+            const remedy = ran.status === "error" ? REMEDIES.notRunnable[kind] : REMEDIES.failed;
+            failures.push({
+                rule: kind === "step" ? "step" : subject,
+                message: `${JSON.stringify(command)} ${ran.detail}`,
+                remedy
+            });
         }
-        return outcome;
+        return { status: ran.status, exitCode: ran.exitCode, tail: ran.tail };
     };
-    const steps = [];
-    let stopped = false;
-    for (const step of selected.steps) {
-        if (stopped) {
-            steps.push({ command: step, ...SKIPPED });
-            continue;
+    // While commands run, SIGINT and SIGTERM stop the one running and every one after it, and the report
+    // still prints. The Checks the package ships run in this process, where a signal ends the Gate at once.
+    const commands = await holdingSignals(async () => {
+        let failedStep = false;
+        const halted = () => failedStep || stoppedBy() !== undefined;
+        const steps = [];
+        for (const step of selected.steps) {
+            const watched = halted() ? undefined : await watch.step(step, () => runOne("step", step, step));
+            failures.push(...(watched?.failures ?? []));
+            const outcome = watched?.result ?? SKIPPED;
+            steps.push({ command: step, ...outcome });
+            failedStep ||= outcome.status !== "pass";
         }
-        log.write(`gate: step ${step}\n`);
-        const outcome = runOne(step, "step", REMEDIES.stepNotRunnable);
-        steps.push({ command: step, ...outcome });
-        stopped = outcome.status !== "pass";
-    }
-    const checks = [];
-    for (const check of selected.run) {
-        if (stopped) {
-            checks.push({ ...check, ...SKIPPED });
-            continue;
+        const checks = [];
+        for (const check of selected.run) {
+            checks.push({ ...check, ...(halted() ? SKIPPED : await runOne("check", check.name, check.command)) });
         }
-        log.write(`gate: check ${check.name}\n`);
-        checks.push({ ...check, ...runOne(check.command, check.name, REMEDIES.checkNotRunnable) });
+        return { steps, checks, halted: halted() };
+    });
+    const { steps, checks } = commands;
+    const late = commands.halted ? undefined : stoppedBy();
+    if (late !== undefined) {
+        // It landed after the last command, which it could not stop: it ends the Gate as in the shipped Checks.
+        process.kill(process.pid, late);
     }
+    const stopped = commands.halted;
     const judged = selected.shipped.map((check) => {
         if (stopped) {
             return { check, outcome: SKIPPED, failures: [] };
         }
-        log.write(`gate: check ${check.name}\n`);
+        progress.start("check", check.name);
         return runShipped(check, root);
     });
-    if ("updateBaseline" in options && options.updateBaseline) {
-        refreshBaselines(judged, [...steps, ...checks], root, log);
-    }
+    const watchOutcome = { status: watch.status() };
+    const notes = mode === "update-baseline" ? refreshBaselines(judged, [...steps, ...checks, watchOutcome], root) : [];
+    // A Ratchet's result is printed after its refresh, which judges it again.
     for (const { check, outcome, failures: found } of judged) {
+        if (outcome.status !== "skipped") {
+            progress.end("check", check.name, outcome);
+        }
         failures.push(...found);
         checks.push({ name: check.name, command: null, ...outcome });
     }
-    return { status: worst([...steps, ...checks]), command: gateCommand, steps, checks, failures };
+    for (const note of notes) {
+        log.write(`${note}\n`);
+    }
+    const status = worst([...steps, ...checks, watchOutcome]);
+    // Stamped with the fingerprint taken before the run: a Gate that changed the tree runs again next time.
+    if (status === "pass" && toStamp !== undefined) {
+        stampGreen(toStamp);
+    }
+    return { status, command: gateCommand, steps, checks, failures };
 }
 /** The last line, after `label`: green with what ran, or failed or cannot run with how many failures. */
 function verdict(label, report) {
+    if (report.cached === true) {
+        return `${label}: green — cached, the tree matches the last green run`;
+    }
     if (report.status === "pass") {
         return `${label}: green — ${plural(report.steps.length, "step")}, ${plural(report.checks.length, "check")}`;
     }
@@ -250,7 +365,7 @@ export function printReport(report, json, label) {
     }
     return EXIT_CODES[report.status];
 }
-export function run(argv) {
+export async function run(argv) {
     const cli = parseCli(argv);
     if ("error" in cli) {
         process.stderr.write(`dw-sdlc gate: ${cli.error}\n\n${USAGE}\n`);
@@ -260,6 +375,7 @@ export function run(argv) {
         process.stdout.write(`${USAGE}\n`);
         return 0;
     }
-    const { json, updateBaseline } = cli;
-    return printReport(runGate(repositoryRoot(cli.root ?? process.cwd()), { json, updateBaseline }), json, "gate");
+    const { json, verbose, mode } = cli;
+    const report = await runGate(repositoryRoot(cli.root ?? process.cwd()), { json, verbose, mode });
+    return printReport(report, json, "gate");
 }

package/dist/commands/pr-reviewed.d.ts

@@ -0,0 +1,2 @@
+export declare const summary = "pin a clean review to the head it read, as a commit status";
+export declare function run(argv: string[]): number;

package/dist/commands/pr-reviewed.js

@@ -0,0 +1,92 @@
+// `dw-sdlc pr reviewed <n> --head <sha>`: pins a clean review to the head it read, as the commit status
+// `dw-sdlc/review` in state success, so a push after the review leaves the new head unreviewed.
+import { parseArgs } from "node:util";
+import { REVIEW, REVIEW_STATE, reviewStatusArgs } from "../pr/decide.js";
+import { CannotRun, gh, namedProblem, read, said } from "../pr/read.js";
+export const summary = "pin a clean review to the head it read, as a commit status";
+const USAGE = `Usage: dw-sdlc pr reviewed <n> [-R owner/name] --head <sha> [--json]
+
+Reads pull request <n> through gh, the read pr ship makes, and when its head is still <sha> posts
+the commit status dw-sdlc/review in state success on it, the pull request's URL as its target. When
+a push moved the head since the review, it posts nothing. One line, or one document with --json.
+Needs an authenticated gh.
+
+Exit 0 posted, 2 when it cannot run or the head moved.`;
+const DESCRIPTION = "a clean review of this head";
+function parseCli(argv) {
+    try {
+        const { values, positionals } = parseArgs({
+            args: argv,
+            allowPositionals: true,
+            options: {
+                help: { type: "boolean", short: "h" },
+                json: { type: "boolean" },
+                repo: { type: "string", short: "R" },
+                head: { type: "string" }
+            }
+        });
+        if (values.help === true) {
+            return "help";
+        }
+        const [number, ...more] = positionals;
+        const { repo, head } = values;
+        if (number === undefined) {
+            return { error: "name the pull request: dw-sdlc pr reviewed <n> --head <sha>" };
+        }
+        if (more.length > 0) {
+            return { error: `name one pull request, not ${positionals.length}` };
+        }
+        const problem = namedProblem(number, repo);
+        if (problem !== undefined) {
+            return { error: problem };
+        }
+        if (head === undefined) {
+            return { error: "name the head the review read: --head <sha>" };
+        }
+        if (!/^[0-9a-f]{40}$/.test(head)) {
+            return { error: `--head takes the full 40-character sha, not ${JSON.stringify(head)}` };
+        }
+        return { json: values.json === true, number: Number(number), repo, head };
+    }
+    catch (error) {
+        return { error: error instanceof Error ? error.message : String(error) };
+    }
+}
+/** Posts the review status on `head` once the read shows it is still the pull request's head. */
+function post({ number, repo, head }) {
+    const pr = read({ number, repo }, "pr reviewed");
+    if (pr.head !== head) {
+        throw new CannotRun(`${pr.repo}#${number}: the head is ${pr.head}, not ${head}: a push landed since the review`, "review the new head, then call again with its sha");
+    }
+    const posted = gh(reviewStatusArgs(pr, DESCRIPTION));
+    if (posted.status !== 0) {
+        throw new CannotRun(`${pr.repo}#${number}: posting ${REVIEW} failed: ${said(posted.stderr)}`, `check that gh's token may write commit statuses to ${pr.repo}, then call again`);
+    }
+}
+export function run(argv) {
+    const cli = parseCli(argv);
+    if (cli === "help") {
+        process.stdout.write(`${USAGE}\n`);
+        return 0;
+    }
+    if ("error" in cli) {
+        process.stderr.write(`dw-sdlc pr reviewed: ${cli.error}\n\n${USAGE}\n`);
+        return 2;
+    }
+    try {
+        post(cli);
+    }
+    catch (error) {
+        if (error instanceof CannotRun) {
+            process.stderr.write(`dw-sdlc pr reviewed: ${error.message} — ${error.remedy}\n`);
+            return 2;
+        }
+        throw error;
+    }
+    const { head } = cli;
+    const answer = cli.json
+        ? JSON.stringify({ head, context: REVIEW, state: REVIEW_STATE }, null, 2)
+        : `posted ${REVIEW} ${REVIEW_STATE} on ${head}`;
+    process.stdout.write(`${answer}\n`);
+    return 0;
+}

package/dist/commands/pr-ship.d.ts

@@ -0,0 +1,2 @@
+export declare const summary = "decide the Action one pull request needs next, as a line or JSON";
+export declare function run(argv: string[]): number;