dw-sdlc 0.15.2 → 0.17.0

package/dist/recap-next.js

@@ -0,0 +1,105 @@
+// The candidates for the session after this one, as `dw-sdlc recap` reads them: the open issues an agent may
+// start, from one GraphQL request that also asks which issues the branch's pull request closes.
+import { isObject, parseObject } from "./json-text.js";
+import { CannotRun, gh, said } from "./pr/read.js";
+/** The label that marks an issue as ready for an agent to start. */
+export const READY_LABEL = "ready-for-agent";
+/** How many open issues the one read holds, oldest first, and how many issues the pull request closes. */
+const ISSUES_READ = 100;
+const CLOSING_READ = 25;
+const QUERY = `query Backlog($owner: String!, $name: String!, $number: Int!, $closing: Boolean!) {
+  repository(owner: $owner, name: $name) {
+    pullRequest(number: $number) @include(if: $closing) { closingIssuesReferences(first: ${CLOSING_READ}) { nodes { number } } }
+    issues(first: ${ISSUES_READ}, states: OPEN, labels: ["${READY_LABEL}"], orderBy: { field: CREATED_AT, direction: ASC }) {
+      nodes { number title url assignees { totalCount } issueDependenciesSummary { blockedBy } parent { number } }
+    }
+  }
+}`;
+const REMEDY = "check gh auth status and the network, then call again";
+function malformed(field) {
+    return new CannotRun(`the backlog reply does not parse: ${field}`, "gh answered a shape dw-sdlc does not read; report it with the output of gh --version");
+}
+function nodesOf(value, field) {
+    if (!isObject(value) || !Array.isArray(value.nodes)) {
+        throw malformed(field);
+    }
+    return value.nodes;
+}
+function numberOf(value, field) {
+    if (!isObject(value) || typeof value.number !== "number") {
+        throw malformed(field);
+    }
+    return value.number;
+}
+/** An issue node as a candidate, or null when it has an assignee or an open blocker. */
+function candidateOf(node) {
+    if (!isObject(node) || typeof node.title !== "string" || typeof node.url !== "string") {
+        throw malformed("issues.nodes");
+    }
+    const { assignees, issueDependenciesSummary: dependencies, parent } = node;
+    if (!isObject(assignees) || typeof assignees.totalCount !== "number") {
+        throw malformed("issues.nodes.assignees");
+    }
+    if (!isObject(dependencies) || typeof dependencies.blockedBy !== "number") {
+        throw malformed("issues.nodes.issueDependenciesSummary");
+    }
+    if (assignees.totalCount > 0 || dependencies.blockedBy > 0) {
+        return null;
+    }
+    const number = numberOf(node, "issues.nodes.number");
+    return { number, title: node.title, url: node.url, parent: parent === null ? null : numberOf(parent, "parent") };
+}
+function repositoryOf(stdout) {
+    const data = parseObject(stdout)?.data;
+    const repository = isObject(data) ? data.repository : undefined;
+    if (!isObject(repository)) {
+        throw malformed("data.repository");
+    }
+    return repository;
+}
+/**
+ * The open issues labelled ready-for-agent with no assignee and no open blocker, read from `repo`, or from the
+ * repository gh resolves when it is null. The open sub-issues of an issue pull request `pr` closes come
+ * first, then the rest, each part in issue order; the issues it closes are never candidates.
+ */
+function nextCandidates(pr) {
+    const [owner, name] = pr === null ? ["{owner}", "{repo}"] : pr.repo.split("/");
+    const reply = gh([
+        "api",
+        "graphql",
+        "-f",
+        `query=${QUERY}`,
+        "-F",
+        `owner=${owner ?? ""}`,
+        "-F",
+        `name=${name ?? ""}`,
+        "-F",
+        `number=${pr?.number ?? 0}`,
+        "-F",
+        `closing=${pr !== null}`
+    ]);
+    if (reply.status !== 0) {
+        throw new CannotRun(`gh could not read the backlog: ${said(reply.stderr)}`, REMEDY);
+    }
+    const repository = repositoryOf(reply.stdout);
+    const closes = new Set(pr === null
+        ? []
+        : nodesOf(isObject(repository.pullRequest) ? repository.pullRequest.closingIssuesReferences : undefined, "pullRequest").map((node) => numberOf(node, "closingIssuesReferences.nodes")));
+    const candidates = nodesOf(repository.issues, "issues")
+        .map(candidateOf)
+        .filter((candidate) => candidate !== null && !closes.has(candidate.number))
+        .toSorted((one, other) => one.number - other.number);
+    const underClosed = (candidate) => candidate.parent !== null && closes.has(candidate.parent);
+    return [...candidates.filter(underClosed), ...candidates.filter((candidate) => !underClosed(candidate))];
+}
+export function readNext(pr) {
+    try {
+        return { candidates: nextCandidates(pr) };
+    }
+    catch (error) {
+        if (error instanceof CannotRun) {
+            return { unread: error.message };
+        }
+        throw error;
+    }
+}

package/dist/report.d.ts

@@ -4,10 +4,16 @@ export type Failure = {
     rule: string;
     message: string;
     remedy: string;
+    /** What the repository owner wrote to try, printed as `hint: <text>` under the failure line. */
+    hint?: string;
+    /** The Disable directive a `disable-directives` failure names, as written. */
+    directive?: string;
 };
+/** `hint: <text>` where the failure carries a Hint, nothing otherwise. */
+export declare function hintLines({ hint }: Failure): string[];
 /** `file:line: rule: message — remedy`, without the location where the failure has none. */
 export declare function failureLine({ file, line, rule, message, remedy }: Failure): string;
 /** `::error file=…,line=…,title=<rule>::<message> — <remedy>`, an annotation on the file where there is one. */
 export declare function annotation({ file, line, rule, message, remedy }: Failure): string;
-/** The failure as JSON: every key present, null where it has no file or line. */
-export declare function failureJson({ file, line, rule, message, remedy }: Failure): Record<string, unknown>;
+/** The failure as JSON: every key present, null where it has no file or line, and `directive` where it names one. */
+export declare function failureJson({ file, line, rule, message, remedy, directive }: Failure): Record<string, unknown>;

package/dist/report.js

@@ -1,6 +1,10 @@
 // A failure of the Gate as every consumer reads it: one line naming the file and line where there is
 // one, the rule, what is wrong and the remedy; the same as a GitHub Actions workflow annotation; the
 // same as JSON.
+/** `hint: <text>` where the failure carries a Hint, nothing otherwise. */
+export function hintLines({ hint }) {
+    return hint === undefined ? [] : [`hint: ${hint}`];
+}
 /** `file:line: rule: message — remedy`, without the location where the failure has none. */
 export function failureLine({ file, line, rule, message, remedy }) {
     const where = file === undefined ? "" : `${file}${line === undefined ? "" : `:${line}`}: `;
@@ -23,7 +27,8 @@ export function annotation({ file, line, rule, message, remedy }) {
     ];
     return `::error ${properties.join(",")}::${escapeData(`${message} — ${remedy}`)}`;
 }
-/** The failure as JSON: every key present, null where it has no file or line. */
-export function failureJson({ file, line, rule, message, remedy }) {
-    return { file: file ?? null, line: line ?? null, rule, message, remedy };
+/** The failure as JSON: every key present, null where it has no file or line, and `directive` where it names one. */
+export function failureJson({ file, line, rule, message, remedy, directive }) {
+    const json = { file: file ?? null, line: line ?? null, rule, message, remedy };
+    return directive === undefined ? json : { ...json, directive };
 }

package/dist/worker/launch.d.ts

@@ -0,0 +1,31 @@
+/** hc names a terminal with 1-32 of a-z, 0-9, - and _. */
+export declare const NAME: RegExp;
+/** The most seconds a start looks for the new tab in the window, beside the read-back. */
+export declare const TAB_WAIT = 10;
+/** The id of the herdr space the terminal `id` sits in, if it sits in one. */
+export declare function spaceOf(id: string): string | undefined;
+export type Launch = {
+    name: string;
+    /** The `role` label of the new terminal. */
+    role: "worker" | "lead";
+    /** The herdr space of the caller, which the new terminal joins; none leaves the tab alone. */
+    space: string | undefined;
+    /** The folder it starts in. */
+    cwd: string;
+    /** The program and its arguments, its first message last. */
+    argv: string[];
+    /** The most seconds the read-back waits. */
+    wait: number;
+};
+export type Launched = {
+    address: string;
+    tab: "none" | "renamed" | "kept";
+    reason: string | undefined;
+};
+/**
+ * Runs `hc run` once for `launch`, outliving its caller, then names the tab and reads the terminal back side
+ * by side. It never sends the first message again; `reason` says why the session did not take it.
+ */
+export declare function launch(command: string, { name, role, space, cwd, argv, wait }: Launch): Promise<Launched>;
+/** The line that says a started session did not take its first message, and how to recover. */
+export declare function undelivered(command: string, name: string, address: string, reason: string, message: string): string;

package/dist/worker/launch.js

@@ -0,0 +1,100 @@
+// What `worker start` and `lead start` share: a session started in a herdr terminal of its own beside the
+// caller, its tab named, and the terminal read back until the session shows it took its first message.
+import { setTimeout as sleep } from "node:timers/promises";
+import { isObject } from "../json-text.js";
+import { describe, hcObject, Refusal } from "./herdr.js";
+import { nameTab } from "./tabs.js";
+/** hc names a terminal with 1-32 of a-z, 0-9, - and _. */
+export const NAME = /^[a-z0-9][a-z0-9_-]{0,31}$/;
+/** The most seconds a start looks for the new tab in the window, beside the read-back. */
+export const TAB_WAIT = 10;
+/** What a session reports once it has taken its first message. */
+const WORKING = new Set(["working", "blocked", "done"]);
+/** How long the read-back waits between two reads of the terminal. */
+const POLL_MS = 1000;
+/** The status a session reports, if it has reported one. */
+function reportedStatus(terminal) {
+    const { status } = terminal;
+    return isObject(status) && typeof status.state === "string" ? status.state : undefined;
+}
+/** Why the session, called `who`, can no longer take its first message, or undefined while it still may. */
+function failure(terminal, who) {
+    const { first_message: first, state } = terminal;
+    if (isObject(first) && first.sent === false) {
+        return typeof first.reason === "string" ? first.reason : "herdr gave no reason";
+    }
+    if (state !== "live") {
+        return "the terminal has finished";
+    }
+    return reportedStatus(terminal) === "error" ? `the ${who} reports its status as error` : undefined;
+}
+/** Reads the terminal until the session shows work, for up to `wait` seconds; why it did not, or undefined once it did. */
+async function delivery(address, wait, who) {
+    const deadline = Date.now() + wait * 1000;
+    for (;;) {
+        let terminal;
+        try {
+            terminal = hcObject(["get", address, "--json"]);
+        }
+        catch (error) {
+            if (!(error instanceof Refusal)) {
+                throw error;
+            }
+            // The session is running by now, so a failed read is a message not confirmed, never a start that did not happen.
+            return `the terminal could not be read back: ${describe(error)}`;
+        }
+        const failed = failure(terminal, who);
+        if (failed !== undefined) {
+            return failed;
+        }
+        if (WORKING.has(reportedStatus(terminal) ?? "")) {
+            return undefined;
+        }
+        if (Date.now() >= deadline) {
+            return `the ${who} showed no sign of work within ${wait} s`;
+        }
+        await sleep(POLL_MS);
+    }
+}
+/** The id of the herdr space the terminal `id` sits in, if it sits in one. */
+export function spaceOf(id) {
+    const { labels } = hcObject(["get", id, "--json"]);
+    const space = isObject(labels) ? labels["herdr.space"] : undefined;
+    return typeof space === "string" ? space : undefined;
+}
+/**
+ * Runs `hc run` once for `launch`, outliving its caller, then names the tab and reads the terminal back side
+ * by side. It never sends the first message again; `reason` says why the session did not take it.
+ */
+export async function launch(command, { name, role, space, cwd, argv, wait }) {
+    const { address } = hcObject([
+        "run",
+        "--bg",
+        "--json",
+        "--name",
+        name,
+        "--label",
+        `role=${role}`,
+        ...(space === undefined ? [] : ["--label", `herdr.space=${space}`]),
+        "--outlive-parent",
+        "--cwd",
+        cwd,
+        "--",
+        ...argv
+    ]);
+    if (typeof address !== "string") {
+        throw new Refusal("hc run answered no address for the terminal it started", "check hc ls before starting it again");
+    }
+    // Side by side, so the wait for the tab overlaps the wait for the session to start.
+    const naming = space === undefined ? Promise.resolve("none") : nameTab(address, name, Math.min(TAB_WAIT, wait));
+    const [named, reason] = await Promise.all([naming, delivery(address, wait, role === "lead" ? "Lead" : "Worker")]);
+    if (typeof named === "object") {
+        process.stderr.write(`dw-sdlc ${command}: warning: ${named.kept}\n`);
+    }
+    return { address, tab: typeof named === "object" ? "kept" : named, reason };
+}
+/** The line that says a started session did not take its first message, and how to recover. */
+export function undelivered(command, name, address, reason, message) {
+    return (`dw-sdlc ${command}: ${name} (${address}) started but its first message was not delivered: ${reason} — ` +
+        `run hc read ${address} to see why; do not send the ${message} again before you have read it\n`);
+}

package/dist/worker/origin.js

@@ -27,7 +27,8 @@ export function freshenOrigin(root, baseBranch) {
     const branch = defaultBranch(root, baseBranch);
     const args = ["-C", root, "fetch", "--quiet", "origin", ...(branch === undefined ? [] : [branch])];
     const fetched = `git fetch origin${branch === undefined ? "" : ` ${branch}`}`;
-    const stale = (why) => new Refusal(`${fetched} failed, so the Worker would begin from a stale base: ${why}`, "check the network and the access to origin, then start the Worker again");
+    const stale = (why) => new Refusal(`${fetched} failed, so the Worker would begin from a stale base: ${why}`, "check the network and the access to origin; when origin/HEAD names a branch the remote no longer has, " +
+        "run `git remote set-head origin --auto`; then start the Worker again");
     let result;
     try {
         result = exec("git", args, { env: repositoryFreeEnv(), limitMs: SLOW_LIMIT_MS });

package/package.json

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