dw-sdlc 0.16.1 → 0.18.0

package/dist/checks/skill-sections.js

@@ -0,0 +1,163 @@
+// `skill-sections`: each README section a skill copies, a part, matches its source. A part sits between
+// `<!-- README.md#<anchor> -->` and `<!-- /README.md#<anchor> -->` and repeats only a section a Primitive's
+// docs name. `dw-sdlc check skill-sections --write` writes each part from its section.
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join, posix } from "node:path";
+import { resolveConfig } from "../agentic-config.js";
+import { readCatalogue } from "../catalogue.js";
+import { headings, openFence, prose } from "../markdown.js";
+import { CannotRun } from "./check.js";
+import { catalogueFile } from "./primitives.js";
+import { matching, treeFiles } from "./tree.js";
+/** Either marker of a part: `/` before `README.md` closes it. */
+const MARKER = /<!-- (\/?)README\.md#(\S+) -->/g;
+const WRITE = "dw-sdlc check skill-sections --write";
+const REMEDIES = {
+    stale: `edit the README, not the part, then run ${WRITE}`,
+    readme: "write the README, or drop the part",
+    section: "point it at a heading the README has",
+    unpaired: "open a part with <!-- README.md#<anchor> --> and close it with <!-- /README.md#<anchor> -->, each on its own line",
+    missing: "create it, or point gate.checks.primitives.file at the catalogue",
+    invalid: "fix what dw-sdlc check primitives names",
+    fence: "close the fence"
+};
+/** The markers outside code in `text`, in order. */
+function markers(text) {
+    return Array.from(prose(text).matchAll(MARKER), (match) => ({
+        close: match[1] === "/",
+        anchor: match[2] ?? "",
+        start: match.index,
+        end: match.index + match[0].length
+    }));
+}
+/** The README a skill file copies from: the one beside the `skills` directory it is in, else beside it. */
+function readmeOf(path) {
+    const directories = path.split("/").slice(0, -1);
+    const at = directories.lastIndexOf("skills");
+    const unit = at === -1 ? directories : directories.slice(0, at);
+    return posix.join(...unit, "README.md");
+}
+/** The section under the heading with `anchor`, up to the next heading of its level or above, its end trimmed. */
+function sectionOf(markdown, anchor) {
+    const all = headings(markdown);
+    const start = all.find((heading) => heading.anchor === anchor);
+    if (start === undefined) {
+        return undefined;
+    }
+    const end = all.find((heading) => heading.line > start.line && heading.level <= start.level);
+    return markdown
+        .split("\n")
+        .slice(start.line - 1, end === undefined ? undefined : end.line - 1)
+        .join("\n")
+        .trimEnd();
+}
+function lineAt(text, offset) {
+    return text.slice(0, offset).split("\n").length;
+}
+function readmeText(root, path, sources) {
+    if (!sources.readmes.has(path)) {
+        const full = join(root, path);
+        sources.readmes.set(path, existsSync(full) ? readFileSync(full, "utf8") : undefined);
+    }
+    return sources.readmes.get(path);
+}
+function render(root, path, sources) {
+    const text = readFileSync(join(root, path), "utf8");
+    const readme = readmeOf(path);
+    const found = markers(text);
+    const findings = [];
+    const pieces = [];
+    let copied = 0;
+    let rewritten = 0;
+    for (let index = 0, open = found[0]; open !== undefined; open = found[++index]) {
+        const close = found[index + 1];
+        const line = lineAt(text, open.start);
+        const fail = (message, remedy) => findings.push({ file: path, line, message, remedy });
+        if (open.close || close === undefined || !close.close || close.anchor !== open.anchor) {
+            const marker = `README.md#${open.anchor}`;
+            const message = open.close
+                ? `the closing marker of ${marker} has no opening marker`
+                : `the opening marker of ${marker} has no closing marker`;
+            fail(message, REMEDIES.unpaired);
+            continue;
+        }
+        index++;
+        const part = `the part from README.md#${open.anchor}`;
+        const source = readmeText(root, readme, sources);
+        const section = source === undefined ? undefined : sectionOf(source, open.anchor);
+        if (!sources.listed().has(`${readme}#${open.anchor}`)) {
+            const remedy = `name ${readme}#${open.anchor} in a Primitive's docs, or point the part at a section they name`;
+            fail(`${part} copies a section no Primitive's docs name`, remedy);
+        }
+        else if (source === undefined) {
+            fail(`${part} reads ${readme}, which does not exist`, REMEDIES.readme);
+        }
+        else if (section === undefined) {
+            fail(`${part} names no heading of ${readme}`, REMEDIES.section);
+        }
+        else if (text.slice(open.end, close.start) !== `\n\n${section}\n\n`) {
+            fail(`${part} differs from that section of ${readme}`, REMEDIES.stale);
+            pieces.push(text.slice(copied, open.end), `\n\n${section}\n\n`);
+            copied = close.start;
+            rewritten++;
+        }
+    }
+    const fence = openFence(text);
+    const hidden = fence === undefined ? "" : text.split("\n").slice(fence).join("\n");
+    if (fence !== undefined && hidden.search(MARKER) !== -1) {
+        const message = "a code fence opens here and never closes, so the markers after it are not read";
+        findings.push({ file: path, line: fence, message, remedy: REMEDIES.fence });
+    }
+    pieces.push(text.slice(copied));
+    return { text: pieces.join(""), findings, rewritten };
+}
+/** The docs entries the catalogue names, each read from the root; the catalogue is read on the first call. */
+function listedDocs(root) {
+    let listed;
+    return () => {
+        if (listed === undefined) {
+            const file = catalogueFile(resolveConfig(root).config.gate.checks);
+            const read = readCatalogue(root, file);
+            if (read.state === "missing") {
+                throw new CannotRun({
+                    file,
+                    message: "the catalogue does not exist, and a skill holds a part",
+                    remedy: REMEDIES.missing
+                });
+            }
+            if (read.state === "invalid") {
+                throw new CannotRun({
+                    file,
+                    message: "the catalogue is not valid, and a skill holds a part",
+                    remedy: REMEDIES.invalid
+                });
+            }
+            listed = new Set(read.catalogue.primitives.flatMap(({ docs }) => docs).map((entry) => posix.join(".", entry)));
+        }
+        return listed;
+    };
+}
+function renderAll(root, { files }) {
+    const sources = { listed: listedDocs(root), readmes: new Map() };
+    return matching(root, treeFiles(root), files).map((path) => ({ path, rendered: render(root, path, sources) }));
+}
+function plural(count, noun) {
+    return `${count} ${noun}${count === 1 ? "" : "s"}`;
+}
+function write(root, options) {
+    const changed = renderAll(root, options).filter(({ rendered }) => rendered.rewritten > 0);
+    for (const { path, rendered } of changed) {
+        writeFileSync(join(root, path), rendered.text);
+    }
+    if (changed.length === 0) {
+        return "every part matches its section, so nothing was written";
+    }
+    const parts = changed.reduce((sum, { rendered }) => sum + rendered.rewritten, 0);
+    return `wrote ${plural(parts, "part")} in ${plural(changed.length, "file")}`;
+}
+export const skillSections = {
+    name: "skill-sections",
+    defaults: { files: ["**/skills/**/*.md"] },
+    run: (root, options) => renderAll(root, options).flatMap(({ rendered }) => rendered.findings),
+    write
+};

package/dist/commands/check.js

@@ -1,11 +1,12 @@
 // `dw-sdlc check <name>`: one Check of the Gate by its name, without the Steps and the other Checks.
 import { parseArgs } from "node:util";
-import { repositoryRoot } from "../agentic-config.js";
-import { CHECK_NAMES } from "../checks/index.js";
+import { repositoryRoot, resolveConfig } from "../agentic-config.js";
+import { CannotRun } from "../checks/check.js";
+import { CHECK_NAMES, shippedCheck } from "../checks/index.js";
 import { TAIL_LINES } from "../run-command.js";
 import { printReport, runGate } from "./gate.js";
 export const summary = "run one Check of the Gate by its name, without the Steps and the other Checks";
-const USAGE = `Usage: dw-sdlc check <name> [--json] [--root <dir>]
+const USAGE = `Usage: dw-sdlc check <name> [--json] [--write] [--root <dir>]
 
 Runs the Check named <name> in the Gate of the repository holding --root (default: the current
 directory): a script under gate.checks.run, or a Check the package ships, one of
@@ -15,6 +16,10 @@ false or leaves it out. No Step runs. A run script prints nothing of its own unl
 pass: then its last ${TAIL_LINES} lines, both streams in the order written. Prints one line per failure,
 as the Gate does; --json prints the Gate's document alone, with no Step.
 
+--write first writes what the Check derives from its sources, then judges the tree it wrote, and
+prints a line on what it wrote, to stderr under --json. Only a Check that derives files takes it:
+skill-sections writes each part of a skill from its README section.
+
 A Ratchet's baseline is refreshed by dw-sdlc gate --update-baseline, which needs every other Check to
 pass.
 
@@ -29,18 +34,50 @@ function parseCli(argv) {
             options: {
                 help: { type: "boolean", short: "h" },
                 json: { type: "boolean" },
+                write: { type: "boolean" },
                 root: { type: "string" }
             }
         });
         if (positionals.length > 1) {
             return { error: `one Check at a time, not ${positionals.map((name) => JSON.stringify(name)).join(" and ")}` };
         }
-        return { help: values.help === true, json: values.json === true, root: values.root, name: positionals[0] };
+        const flags = { help: values.help === true, json: values.json === true, write: values.write === true };
+        return { ...flags, root: values.root, name: positionals[0] };
     }
     catch (error) {
         return { error: error instanceof Error ? error.message : String(error) };
     }
 }
+/**
+ * Writes what the shipped Check `name` derives, on the setting the config gives it, and prints what it
+ * wrote; why it cannot when it takes no --write. An invalid config or a missing input writes nothing,
+ * and the run after it reports why.
+ */
+function writeDerived(root, name, json) {
+    const { config, problems } = resolveConfig(root);
+    if (problems.length > 0) {
+        return undefined;
+    }
+    const shipped = shippedCheck(name, config.gate.checks[name]);
+    if (shipped === undefined && !config.gate.checks.run.some((check) => check.name === name)) {
+        // No Check of that name: the run after it says so, with the names there are.
+        return undefined;
+    }
+    const write = shipped?.write;
+    if (write === undefined) {
+        return `${JSON.stringify(name)} takes no --write: it derives no file`;
+    }
+    try {
+        const out = json ? process.stderr : process.stdout;
+        out.write(`check ${name}: ${write(root)}\n`);
+    }
+    catch (error) {
+        if (!(error instanceof CannotRun)) {
+            throw error;
+        }
+    }
+    return undefined;
+}
 export async function run(argv) {
     const cli = parseCli(argv);
     if ("error" in cli) {
@@ -56,6 +93,14 @@ export async function run(argv) {
         return 2;
     }
     const { json, name } = cli;
-    const report = await runGate(repositoryRoot(cli.root ?? process.cwd()), { json, only: name });
+    const root = repositoryRoot(cli.root ?? process.cwd());
+    if (cli.write) {
+        const refused = writeDerived(root, name, json);
+        if (refused !== undefined) {
+            process.stderr.write(`dw-sdlc check: ${refused}\n`);
+            return 2;
+        }
+    }
+    const report = await runGate(root, { json, only: name });
     return printReport(report, json, `check ${name}`);
 }

package/dist/commands/gate.d.ts

@@ -6,13 +6,16 @@ type Outcome = {
     exitCode: number | null;
     tail: string[] | null;
 };
+/** `hint` is what the Step carries to try when it fails, null where it has none. */
 type StepReport = Outcome & {
     command: string;
+    hint: string | null;
 };
-/** A Check the package ships runs in this process: it has no command. */
+/** A Check the package ships runs in this process: it has no command and no hint. */
 type CheckReport = Outcome & {
     name: string;
     command: string | null;
+    hint: string | null;
 };
 type GateReport = {
     status: Status;

package/dist/commands/gate.js

@@ -1,12 +1,12 @@
 // `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 { parseArgs } from "node:util";
-import { repositoryRoot, resolveConfig } from "../agentic-config.js";
+import { repositoryRoot, resolveConfig, stepCommand, stepHint } 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 { annotation, failureJson, failureLine, hintLines } 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] [--verbose] [--root <dir>] [--update-baseline | --cache]
@@ -21,6 +21,9 @@ Actions it is also a workflow annotation. A Step or run script prints nothing of
 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.
 
+A Step written as { "command", "hint" }, and a run script with a hint, prints "hint: <text>" under its
+failure line when it does not pass; a passing one prints nothing more.
+
 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
@@ -33,7 +36,7 @@ second signal, or one sent while the Checks the package ships run, ends the Gate
 
 --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
+${TAIL_LINES} lines of a command that did not pass, null otherwise, and hint, null where there is none. 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
@@ -268,7 +271,7 @@ export async function runGate(root, options) {
     const failures = [];
     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) => {
+    const runOne = async (kind, subject, command, hint) => {
         progress.start(kind, subject);
         const ran = await runCommand(command, root, output);
         progress.end(kind, subject, ran);
@@ -277,7 +280,8 @@ export async function runGate(root, options) {
             failures.push({
                 rule: kind === "step" ? "step" : subject,
                 message: `${JSON.stringify(command)} ${ran.detail}`,
-                remedy
+                remedy,
+                ...(hint === null ? {} : { hint })
             });
         }
         return { status: ran.status, exitCode: ran.exitCode, tail: ran.tail };
@@ -289,15 +293,19 @@ export async function runGate(root, options) {
         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));
+            const command = stepCommand(step);
+            const hint = stepHint(step);
+            const watched = halted() ? undefined : await watch.step(command, () => runOne("step", command, command, hint));
             failures.push(...(watched?.failures ?? []));
             const outcome = watched?.result ?? SKIPPED;
-            steps.push({ command: step, ...outcome });
+            steps.push({ command, hint, ...outcome });
             failedStep ||= outcome.status !== "pass";
         }
         const checks = [];
         for (const check of selected.run) {
-            checks.push({ ...check, ...(halted() ? SKIPPED : await runOne("check", check.name, check.command)) });
+            const hint = check.hint ?? null;
+            const outcome = halted() ? SKIPPED : await runOne("check", check.name, check.command, hint);
+            checks.push({ name: check.name, command: check.command, hint, ...outcome });
         }
         return { steps, checks, halted: halted() };
     });
@@ -323,7 +331,7 @@ export async function runGate(root, options) {
             progress.end("check", check.name, outcome);
         }
         failures.push(...found);
-        checks.push({ name: check.name, command: null, ...outcome });
+        checks.push({ name: check.name, command: null, hint: null, ...outcome });
     }
     for (const note of notes) {
         log.write(`${note}\n`);
@@ -361,7 +369,11 @@ export function printReport(report, json, label) {
         }
     }
     else {
-        const lines = report.failures.flatMap((failure) => actions ? [failureLine(failure), annotation(failure)] : [failureLine(failure)]);
+        const lines = report.failures.flatMap((failure) => [
+            failureLine(failure),
+            ...(actions ? [annotation(failure)] : []),
+            ...hintLines(failure)
+        ]);
         process.stdout.write(`${[...lines, verdict(label, report)].join("\n")}\n`);
     }
     return EXIT_CODES[report.status];

package/dist/commands/primitives.d.ts

@@ -1,2 +1,2 @@
-export declare const summary = "name the Primitives that own each path, with their summaries and documents";
+export declare const summary = "name the Primitives that own each path, or that a change removes, adds or extends";
 export declare function run(argv: string[]): number;

package/dist/commands/primitives.js

@@ -1,21 +1,32 @@
-// `dw-sdlc primitives --paths <files>`: for each path, the Primitives of the catalogue that name it,
-// with their summaries and the documents to read, or that none does.
+// `dw-sdlc primitives`: with `--paths <files>`, for each path the Primitives of the catalogue that name
+// it, with their summaries and the documents to read, or that none does; with `--diff <base>`, the
+// Primitives a change removes, adds or extends.
 import { existsSync, realpathSync } from "node:fs";
 import { basename, dirname, join, relative, resolve } from "node:path";
 import { parseArgs } from "node:util";
 import { repositoryRoot, resolveConfig } from "../agentic-config.js";
 import { primitivesNaming, readCatalogue } from "../catalogue.js";
 import { catalogueFile } from "../checks/primitives.js";
-export const summary = "name the Primitives that own each path, with their summaries and documents";
+import { blockOf, primitivesDiff } from "../primitives-diff.js";
+export const summary = "name the Primitives that own each path, or that a change removes, adds or extends";
 const USAGE = `Usage: dw-sdlc primitives --paths <file>... [--json] [--root <dir>]
+       dw-sdlc primitives --diff <base> [--json] [--root <dir>]
 
-Prints, for each path, the Primitives of the catalogue whose code names it, the file itself or the
-nearest directory above it: the id, the name, the summary and the documents to read; or that no
+--paths prints, for each path, the Primitives of the catalogue whose code names it, the file itself or
+the nearest directory above it: the id, the name, the summary and the documents to read; or that no
 Primitive names it. A path is read from the current directory. The catalogue is the one the
 primitives Check reads, in the repository holding --root (default: the current directory). --json
 prints one document instead.
 
-Exit 0 with an answer for every path, 2 when there is no catalogue to read or it is not one.`;
+--diff prints the Primitives the committed change from the merge-base of <base> and HEAD to HEAD
+removes (an id gone from the catalogue), adds (a new id) and extends (a changed file in the code of a
+Primitive that was there): a markdown block between <!-- primitives:start --> and <!-- primitives:end -->
+for a pull request body, which a later run replaces. --json prints instead, per Primitive, its id, name,
+class, file count, summary and docs, each doc with whether the change touches its file, and the count of
+changed files outside every Primitive. It takes no --paths.
+
+Exit 0 with an answer, 2 when there is no catalogue to read or it is not one, and for --diff when <base>
+does not resolve.`;
 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"
@@ -29,6 +40,7 @@ function parseCli(argv) {
                 help: { type: "boolean", short: "h" },
                 json: { type: "boolean" },
                 paths: { type: "boolean" },
+                diff: { type: "string" },
                 root: { type: "string" }
             }
         });
@@ -36,10 +48,17 @@ function parseCli(argv) {
             help: values.help === true,
             json: values.json === true,
             paths: values.paths === true,
+            diff: values.diff,
             files: positionals,
             root: values.root
         };
-        return cli.help || cli.paths ? cli : { error: "name the paths with --paths" };
+        if (cli.help) {
+            return cli;
+        }
+        if (cli.diff !== undefined && (cli.paths || cli.files.length > 0)) {
+            return { error: "--diff and --paths exclude each other — ask one question at a time" };
+        }
+        return cli.paths || cli.diff !== undefined ? cli : { error: "name the paths with --paths, or a base with --diff" };
     }
     catch (error) {
         return { error: error instanceof Error ? error.message : String(error) };
@@ -68,6 +87,15 @@ function plain(path, primitives) {
         `  read: ${docs.join(", ")}`
     ]);
 }
+function runDiff(root, base, json) {
+    const answer = primitivesDiff(root, base);
+    if ("problems" in answer) {
+        process.stderr.write(answer.problems.map((problem) => `dw-sdlc primitives: ${problem}\n`).join(""));
+        return 2;
+    }
+    process.stdout.write(json ? `${JSON.stringify(answer, null, 2)}\n` : `${blockOf(answer)}\n`);
+    return 0;
+}
 export function run(argv) {
     const cli = parseCli(argv);
     if ("error" in cli) {
@@ -79,6 +107,9 @@ export function run(argv) {
         return 0;
     }
     const root = repositoryRoot(cli.root ?? process.cwd());
+    if (cli.diff !== undefined) {
+        return runDiff(root, cli.diff, cli.json);
+    }
     const file = catalogueFile(resolveConfig(root).config.gate.checks);
     const read = readCatalogue(root, file);
     if (read.state !== "valid") {

package/dist/commands/recap.js

@@ -8,6 +8,7 @@ import { decide, declaredPolicy, labelOf, lineOf } from "../pr/decide.js";
 import { CannotRun, defaultBranch, now, readBranch } from "../pr/read.js";
 import { holds, upstreamName } from "../pr/upstream.js";
 import { READY_LABEL, readNext } from "../recap-next.js";
+import { rollup } from "../recap-primitives.js";
 import { isLive, Refusal, workersOf, workingFolders } from "../worker/herdr.js";
 import { asked, git } from "../working-tree.js";
 export const summary = "the facts a Recap rests on, whether the session can be closed and what could come next";
@@ -32,6 +33,10 @@ A pull request closed without merging merges nothing, and a detached HEAD names
 commit counts as pushed only on a remote branch, and the command asks the remote which branches still
 stand. A branch force-pushed since the last fetch can still read as holding it, so fetch first to be exact.
 
+Beside the facts it lists the Primitives the session's branch changed, as primitives --diff classes them
+from its merge-base with origin/<default>: ids and classes, none on the default branch or in a repository
+with no catalogue. A catalogue it cannot read lists none, with a warning.
+
 A linked worktree is a reason beside the verdict, never against it: the session cannot remove the
 directory it runs in.
 
@@ -192,11 +197,11 @@ function orphanedOf(root, read, shipped, held) {
  * The commits on top of the base that no pull request holds. A branch the config protects takes changes
  * through pull requests rather than making one, and so does the default branch: neither needs one.
  */
-function aheadOf(root, branch, shipped) {
+function aheadOf(root, branch, baseOf) {
     if (resolveConfig(root).config.guardrails.protectedBranches.includes(branch)) {
         return null;
     }
-    const base = shipped?.pr.base ?? defaultBranch();
+    const base = baseOf();
     if (branch === base) {
         return null;
     }
@@ -285,7 +290,11 @@ function nextLine(next) {
     const named = next.candidates.map(({ number, parent }) => `#${number}${parent === null ? "" : ` (sub-issue of #${parent})`}`);
     return named.length === 0 ? "none" : named.join(", ");
 }
-function linesOf(local, { shipped, askedGh, workers, next }, line) {
+function primitivesLine(primitives) {
+    const named = primitives.map(({ id, class: kind }) => `${kind} ${id}`);
+    return named.length === 0 ? [] : [`primitives: ${named.join(", ")}`];
+}
+function linesOf(local, { shipped, askedGh, workers, next }, primitives, line) {
     const none = askedGh ? "none" : "gh not asked";
     return [
         `branch: ${local.branch ?? "detached HEAD"}`,
@@ -295,6 +304,7 @@ function linesOf(local, { shipped, askedGh, workers, next }, line) {
         `worktree: ${local.worktree.linked ? `linked at ${local.worktree.path}` : "main checkout"}`,
         `workers: ${workersLine(workers)}`,
         `next: ${nextLine(next)}`,
+        ...primitivesLine(primitives),
         line
     ].join("\n");
 }
@@ -328,7 +338,9 @@ function report(json) {
     const local = standing(root, read, shipped, held);
     // An open pull request can still take the head, and a commit-less repository has nothing to merge.
     const nothingToMerge = held || shipped?.pr.state === "OPEN" || head === null;
-    const ahead = asksGh && !nothingToMerge ? aheadOf(root, branch, shipped) : null;
+    let named;
+    const baseOf = () => (named ??= shipped?.pr.base ?? defaultBranch());
+    const ahead = asksGh && !nothingToMerge ? aheadOf(root, branch, baseOf) : null;
     const facts = {
         shipped,
         ahead,
@@ -340,14 +352,18 @@ function report(json) {
     if (facts.next !== null && "unread" in facts.next) {
         process.stderr.write(`dw-sdlc recap: warning: the backlog was not read: ${facts.next.unread}\n`);
     }
+    const rolled = asksGh ? rollup(root, branch, defaultBranch) : { primitives: [] };
+    if ("unread" in rolled) {
+        process.stderr.write(`dw-sdlc recap: warning: the Primitives were not read: ${rolled.unread}\n`);
+    }
     const next = facts.next !== null && "candidates" in facts.next ? facts.next.candidates : null;
     const close = closeOf(reasonsOf(local, facts));
     const pullRequest = shipped === null
         ? null
         : { url: shipped.pr.url, number: shipped.pr.number, state: shipped.pr.state, ...shipped.answer };
     const output = json
-        ? JSON.stringify({ ...local, askedGh: asksGh, pullRequest, workers: facts.workers, close, next }, null, 2)
-        : linesOf(local, facts, close.line);
+        ? JSON.stringify({ ...local, askedGh: asksGh, pullRequest, workers: facts.workers, primitives: rolled.primitives, close, next }, null, 2)
+        : linesOf(local, facts, rolled.primitives, close.line);
     process.stdout.write(`${output}\n`);
     return close.verdict === "yes" ? 0 : 1;
 }

package/dist/markdown.d.ts

@@ -12,6 +12,8 @@ export type Link = {
     target: string;
     line: number;
 };
+/** The 1-based line of the code fence `text` leaves open at its end; none when every fence closes. */
+export declare function openFence(text: string): number | undefined;
 /** Every ATX heading in `text`, a repeated anchor numbered `-1`, `-2` as GitHub numbers it. */
 export declare function headings(text: string): Heading[];
 /**

package/dist/markdown.js

@@ -13,15 +13,24 @@ function scan(text) {
         const marker = FENCE.exec(line)?.[1];
         if (fence === undefined && marker !== undefined) {
             fence = marker;
-            return { text: line, line: index + 1, fenced: true };
+            return { text: line, line: index + 1, fenced: true, edge: "open" };
         }
         if (fence !== undefined && marker !== undefined && marker[0] === fence[0] && marker.length >= fence.length) {
             fence = undefined;
-            return { text: line, line: index + 1, fenced: true };
+            return { text: line, line: index + 1, fenced: true, edge: "close" };
         }
         return { text: line, line: index + 1, fenced: fence !== undefined };
     });
 }
+/** The 1-based line of the code fence `text` leaves open at its end; none when every fence closes. */
+export function openFence(text) {
+    const lines = scan(text);
+    const last = lines.at(-1);
+    if (last === undefined || !last.fenced || last.edge === "close") {
+        return undefined;
+    }
+    return lines.findLast(({ edge }) => edge === "open")?.line;
+}
 /**
  * GitHub's anchor for a heading: its text as rendered, lowercased, every character but a letter, a
  * digit, a space, `-` and `_` dropped, each space a hyphen.

package/dist/primitives-diff.d.ts

@@ -0,0 +1,31 @@
+export type PrimitiveClass = "removes" | "adds" | "extends";
+export type Change = {
+    id: string;
+    name: string;
+    class: PrimitiveClass;
+    /** The changed files the Primitive owns. */
+    files: number;
+    summary: string;
+    /** Each `docs` entry, and whether the diff changes its file, whatever its anchor. */
+    docs: {
+        entry: string;
+        touched: boolean;
+    }[];
+};
+export type PrimitivesDiff = {
+    base: string;
+    primitives: Change[];
+    outside: number;
+};
+/** Why a diff cannot be answered: each problem with its remedy. */
+export type Refusal = {
+    problems: string[];
+};
+/**
+ * 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 declare function primitivesDiff(root: string, base: string): PrimitivesDiff | Refusal;
+/** The markdown block between its markers, which a later run replaces whole. */
+export declare function blockOf({ primitives, outside }: PrimitivesDiff): string;