dw-sdlc 0.16.1 → 0.18.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/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/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/package.json

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