dw-sdlc 0.17.0 → 0.19.0

package/dist/primitives-diff.js

@@ -0,0 +1,123 @@
+// The Primitives a change removes, adds or extends, decided from the paths it changes and the catalogue
+// at both ends of `base...HEAD`: nothing is judged. `dw-sdlc primitives --diff` prints it and `recap`
+// rolls it up for the session's branch.
+import { resolveConfig } from "./agentic-config.js";
+import { parseCatalogue, primitivesNaming } from "./catalogue.js";
+import { catalogueFile } from "./checks/primitives.js";
+import { asked, git } from "./working-tree.js";
+const CLASSES = ["removes", "adds", "extends"];
+const REMEDIES = {
+    missing: "create it, or point gate.checks.primitives.file at the catalogue",
+    invalid: "fix the catalogue; dw-sdlc gate names each problem under the primitives Check",
+    base: "fetch it, or name a ref that exists",
+    git: "check the repository with git status"
+};
+function refuse(problem, remedy) {
+    return { problems: [`${problem} — ${remedy}`] };
+}
+/** The catalogue `file` holds at `rev`, `missing` when `rev` has no such file. */
+function readAt(root, rev, file) {
+    if (asked(root, ["cat-file", "-e", `${rev}:${file}`]) === undefined) {
+        return { state: "missing" };
+    }
+    const shown = git(root, ["show", `${rev}:${file}`]);
+    return "error" in shown ? { state: "invalid", problems: [shown.error] } : parseCatalogue(shown.out);
+}
+/** The merge-base of `base` and `HEAD`, and the files `base...HEAD` changes: a deleted one and both ends of a rename too. */
+function changeSince(root, base) {
+    const resolved = asked(root, ["rev-parse", "--verify", "--quiet", `${base}^{commit}`]);
+    if (resolved === undefined) {
+        return refuse(`the base ${JSON.stringify(base)} does not resolve to a commit`, REMEDIES.base);
+    }
+    const mergeBase = asked(root, ["merge-base", resolved, "HEAD"]);
+    if (mergeBase === undefined) {
+        return refuse(`the base ${JSON.stringify(base)} shares no history with HEAD`, REMEDIES.base);
+    }
+    const diff = git(root, ["diff", "--name-only", "-z", "--no-renames", mergeBase, "HEAD"]);
+    if ("error" in diff) {
+        return refuse(diff.error, REMEDIES.git);
+    }
+    return { mergeBase, files: diff.out.split("\0").filter((path) => path !== "") };
+}
+/** How many of `files` the Primitive `id` owns in any of `catalogues`. */
+function owned(catalogues, files, id) {
+    return files.filter((file) => catalogues.some((catalogue) => primitivesNaming(catalogue, file).some((primitive) => primitive.id === id))).length;
+}
+function describe(primitive, kind, files, changed) {
+    const docs = primitive.docs.map((entry) => ({ entry, touched: changed.has(entry.split("#")[0] ?? entry) }));
+    return { id: primitive.id, name: primitive.name, class: kind, files, summary: primitive.summary, docs };
+}
+/**
+ * The Primitives `base...HEAD` removes, adds and extends. The catalogue's path comes from the config of
+ * the checkout; the catalogue is read at `HEAD` and at the merge-base, from the commits and not the tree.
+ * A file's owners are the nearest entries of the catalogue it is read against, as `--paths` answers.
+ */
+export function primitivesDiff(root, base) {
+    const file = catalogueFile(resolveConfig(root).config.gate.checks);
+    const head = readAt(root, "HEAD", file);
+    if (head.state === "missing") {
+        return refuse(`${file}: the catalogue does not exist at HEAD`, REMEDIES.missing);
+    }
+    if (head.state === "invalid") {
+        return { problems: head.problems.map((problem) => `${file}: ${problem} — ${REMEDIES.invalid}`) };
+    }
+    const since = changeSince(root, base);
+    if ("problems" in since) {
+        return since;
+    }
+    const { mergeBase, files } = since;
+    const before = readAt(root, mergeBase, file);
+    if (before.state === "invalid") {
+        const at = `${file} at ${JSON.stringify(base)}`;
+        return { problems: before.problems.map((problem) => `${at}: ${problem} — ${REMEDIES.invalid}`) };
+    }
+    const atBase = before.state === "valid" ? before.catalogue : { version: 1, groups: [], primitives: [] };
+    const atHead = head.catalogue;
+    const changed = new Set(files);
+    const inBase = new Set(atBase.primitives.map(({ id }) => id));
+    const inHead = new Set(atHead.primitives.map(({ id }) => id));
+    const changes = [
+        ...atBase.primitives
+            .filter(({ id }) => !inHead.has(id))
+            .map((primitive) => describe(primitive, "removes", owned([atBase], files, primitive.id), changed)),
+        ...atHead.primitives.flatMap((primitive) => {
+            const kind = inBase.has(primitive.id) ? "extends" : "adds";
+            const count = owned(kind === "adds" ? [atHead] : [atBase, atHead], files, primitive.id);
+            return kind === "adds" || count > 0 ? [describe(primitive, kind, count, changed)] : [];
+        })
+    ];
+    const outside = files.filter((path) => primitivesNaming(atHead, path).length + primitivesNaming(atBase, path).length === 0);
+    const rank = ({ class: kind }) => CLASSES.indexOf(kind);
+    changes.sort((a, b) => rank(a) - rank(b) || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+    return { base, primitives: changes, outside: outside.length };
+}
+function plural(howMany, word) {
+    return `${howMany} ${word}${howMany === 1 ? "" : "s"}`;
+}
+function cell(text) {
+    return text.replaceAll("|", "\\|");
+}
+/** The markdown block between its markers, which a later run replaces whole. */
+export function blockOf({ primitives, outside }) {
+    const start = "<!-- primitives:start -->";
+    const end = "<!-- primitives:end -->";
+    if (primitives.length === 0) {
+        return [start, "No Primitive changes.", end].join("\n");
+    }
+    const counts = CLASSES.map((kind) => ({ kind, howMany: primitives.filter((change) => change.class === kind).length }));
+    const clauses = counts
+        .filter(({ howMany }) => howMany > 0)
+        .map(({ kind, howMany }, position) => position === 0
+        ? `${kind[0]?.toUpperCase()}${kind.slice(1)} ${plural(howMany, "Primitive")}`
+        : `${kind} ${howMany}`);
+    const rows = primitives.map((change) => `| \`${cell(change.id)}\` (${cell(change.name)}) | ${change.class} | ${change.files} |`);
+    return [
+        start,
+        `**${clauses.join(", ")}.** ${plural(outside, "file")} outside the catalogue.`,
+        "",
+        "| Primitive | Class | Files |",
+        "| --- | --- | --- |",
+        ...rows,
+        end
+    ].join("\n");
+}

package/dist/recap-primitives.d.ts

@@ -0,0 +1,12 @@
+import { type PrimitiveClass } from "./primitives-diff.ts";
+export type Rolled = {
+    id: string;
+    class: PrimitiveClass;
+};
+/** What the rollup read: the Primitives, and why it could not read them when it could not. */
+export type Rollup = {
+    primitives: Rolled[];
+    unread?: string;
+};
+/** `defaultOf` names the default branch and is asked only once the repository has a catalogue and `branch` is no base. */
+export declare function rollup(root: string, branch: string, defaultOf: () => string): Rollup;

package/dist/recap-primitives.js

@@ -0,0 +1,26 @@
+// The Primitives a session's branch changed, for `dw-sdlc recap`: the rollup of `primitives --diff` from
+// the branch's merge-base with `origin/<default>`, ids and classes only. A branch the config protects,
+// the default branch and a repository with no catalogue roll up to none.
+import { resolveConfig } from "./agentic-config.js";
+import { catalogueFile } from "./checks/primitives.js";
+import { primitivesDiff } from "./primitives-diff.js";
+import { asked } from "./working-tree.js";
+/** `defaultOf` names the default branch and is asked only once the repository has a catalogue and `branch` is no base. */
+export function rollup(root, branch, defaultOf) {
+    const { guardrails, gate } = resolveConfig(root).config;
+    if (guardrails.protectedBranches.includes(branch)) {
+        return { primitives: [] };
+    }
+    if (asked(root, ["cat-file", "-e", `HEAD:${catalogueFile(gate.checks)}`]) === undefined) {
+        return { primitives: [] };
+    }
+    const base = defaultOf();
+    if (branch === base) {
+        return { primitives: [] };
+    }
+    const answer = primitivesDiff(root, `origin/${base}`);
+    if ("problems" in answer) {
+        return { primitives: [], unread: answer.problems.join("; ") };
+    }
+    return { primitives: answer.primitives.map(({ id, class: kind }) => ({ id, class: kind })) };
+}

package/dist/run-command.js

@@ -46,8 +46,10 @@ export async function holdingSignals(body) {
         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));
+        // libuv takes a signal at once but hands it to its handler only when the loop next polls, and a
+        // handler released before that poll loses it. The last command's exit is read in a poll and the
+        // first immediate runs right after it, so the second waits for one more poll.
+        await new Promise((resolve) => setImmediate(() => setImmediate(resolve)));
         // The Gate's own signal may still be on its way after a command it ended: the handlers stay, so
         // that signal does not end the Gate before its report.
         if (commandEndedBy === undefined || received !== undefined) {

package/dist/sweep-trees.d.ts

@@ -1,5 +1,7 @@
 /** `git <args>` at `root`, or a stop naming its problem. */
 export declare function must(root: string, args: string[]): string;
+/** The local branches of the repository at `root`. */
+export declare function branchesOf(root: string): string[];
 export type Tree = {
     path: string;
     head: string;
@@ -15,3 +17,11 @@ export declare function dirtyFiles(path: string): string[] | {
 };
 /** The operation paused in the worktree at `path`: its git dir holds the state git resumes it from. */
 export declare function pausedOperation(path: string): string | undefined;
+/** The dev's way off `branch`, checked out in the main checkout at `root`: null until it is Landed and nothing there could be lost. */
+export declare function switchOff(root: string, base: {
+    name: string;
+    ref: string;
+}, branch: string): {
+    reason: string;
+    command: string;
+} | null;

package/dist/sweep-trees.js

@@ -1,9 +1,11 @@
-// What a Sweep reads of a repository's linked worktrees: where each lies, what it has checked out, its lock,
-// the files that hold it and the operation paused in it.
+// What a Sweep reads of a repository's branches and worktrees: where each worktree lies, what it has checked
+// out, its lock, the files that hold it and the operation paused in it, and the way off the main checkout's.
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { exec } from "./exec.js";
 import { repositoryFreeEnv } from "./git-env.js";
+import { isLanded } from "./landed.js";
+import { shellLine } from "./pr/decide.js";
 import { CannotRun } from "./pr/read.js";
 import { asked, git } from "./working-tree.js";
 /** `git <args>` at `root`, or a stop naming its problem. */
@@ -14,6 +16,12 @@ export function must(root, args) {
     }
     return result.out;
 }
+/** The local branches of the repository at `root`. */
+export function branchesOf(root) {
+    return must(root, ["for-each-ref", "--format=%(refname:lstrip=2)", "refs/heads"])
+        .split("\n")
+        .filter((name) => name !== "");
+}
 /** Every worktree of the repository, the main checkout first. */
 export function worktreesOf(root) {
     const trees = [];
@@ -70,3 +78,15 @@ export function pausedOperation(path) {
     const dir = asked(path, ["rev-parse", "--absolute-git-dir"]);
     return dir === undefined ? undefined : OPERATIONS.find(([file]) => existsSync(join(dir, file)))?.[1];
 }
+/** The dev's way off `branch`, checked out in the main checkout at `root`: null until it is Landed and nothing there could be lost. */
+export function switchOff(root, base, branch) {
+    const files = dirtyFiles(root);
+    if ("error" in files ||
+        files.length > 0 ||
+        pausedOperation(root) !== undefined ||
+        !isLanded(root, base.ref, branch)) {
+        return null;
+    }
+    const command = `${shellLine(["git", "switch", base.name])} && ${shellLine(["git", "pull", "--rebase"])}`;
+    return { reason: `checked out in the main checkout at ${root}, Landed on origin/${base.name}`, command };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dw-sdlc",
-  "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.",
+  "version": "0.19.0",
+  "description": "The Gate and the agentic config behind the sdlc Claude Code plugin: a bin with the Gate and its Checks, the setup, the doctor, the Sync of References, the Ship script that drives a pull request to merged, the Sweep, and Lead and Worker sessions in herdr; the resolver of a repository's .ai/agentic.config.json layers and its JSON Schema.",
   "license": "MIT",
   "repository": {
     "type": "git",