@rheged-studio/changelog-core 1.1.1

package/dist/commands/backfill-commits.js

@@ -0,0 +1,236 @@
+// One-off backfill of `stats.commits` across the dated changelog backlog (A-560).
+//
+// The `commits` stat joins the existing post-merge stats rail (files_changed /
+// loc_added / loc_removed), but those were only ever filled going forward by the
+// release-time enrichment. This walks the existing `changelog/*.md` entries and
+// stamps `stats.commits` for each one whose merged PR can be resolved, so the
+// backlog carries the same field as new entries will.
+//
+// Deliberately narrow: it sets ONLY `stats.commits` and touches no other field —
+// unlike `finalise`, which also stamps `version` (owned by release-please) and
+// the other post-merge fields. Running finalise to backfill would mis-stamp the
+// not-yet-finalised entries; this stays in its lane.
+//
+// Idempotent: re-running is a no-op once `stats.commits` matches the resolved
+// count. Best-effort per entry — a gh/network failure on one entry warns and
+// skips it rather than aborting the run.
+//
+// The new line is spliced into the raw `stats:` block textually rather than via
+// a parse → re-serialise round-trip. Re-serialising would re-canonicalise the
+// whole frontmatter (quote styles, inline-vs-block arrays) on older,
+// differently-formatted entries — a noisy diff that buries the one line that
+// actually changed. Textual insertion keeps each entry's diff to a single added
+// line. (Release-time enrichment can re-serialise freely because it only runs on
+// freshly-authored, already-canonical entries.)
+//
+// Zero-dep: composes the package's own lib modules and the frontmatter parser,
+// so it runs under bare `node`.
+import { isCliEntry } from "../lib/cli-entry.js";
+import { nonMergeCommitCount, realRunner } from "../lib/commit-count.js";
+import { loadConfig } from "../lib/config.js";
+import { parseFrontmatter } from "../lib/frontmatter.js";
+import { readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { argv } from "node:process";
+/**
+ * Resolve the merged PR number for an entry: prefer the recorded `pr` field,
+ * else look it up from the `branch`. Returns the number, or null when there's no
+ * resolvable merged PR (e.g. an entry whose PR never merged or predates GitHub).
+ * Throws (rather than returning null) if the gh output isn't valid JSON —
+ * main()'s per-entry try/catch owns that, so a malformed response skips the
+ * entry loudly instead of being mistaken for "no PR".
+ */
+export function resolvePrNumber(run, fm) {
+    if (typeof fm.pr === "number") {
+        return fm.pr;
+    }
+    const branch = typeof fm.branch === "string" ? fm.branch : "";
+    if (!branch) {
+        return null;
+    }
+    const list = JSON.parse(run("gh", [
+        "pr",
+        "list",
+        "--head",
+        branch,
+        "--state",
+        "merged",
+        "--limit",
+        "1",
+        "--json",
+        "number",
+    ]));
+    if (!Array.isArray(list) || list.length === 0) {
+        return null;
+    }
+    const first = list[0];
+    return first.number ?? null;
+}
+/**
+ * Splice a `commits: <n>` line into an entry's raw `stats:` block — replacing an
+ * existing `commits:` line, else appending after the block's last child. When the
+ * entry omits `stats` entirely (the contract allows it), synthesise a minimal
+ * `stats:` block carrying just the commits count. Leaves every other byte of the
+ * entry untouched.
+ */
+function setStatsCommits(raw, commits) {
+    const lines = raw.split("\n");
+    if (lines[0]?.trim() !== "---") {
+        throw new Error("entry has no frontmatter fence");
+    }
+    let fmEnd = -1;
+    for (let index = 1; index < lines.length; index++) {
+        if (lines[index].trim() === "---") {
+            fmEnd = index;
+            break;
+        }
+    }
+    if (fmEnd === -1) {
+        throw new Error("unterminated frontmatter");
+    }
+    let statsIndex = -1;
+    let inlineEmptyStats = false;
+    for (let index = 1; index < fmEnd; index++) {
+        const line = lines[index];
+        if (/^stats:\s*$/.test(line)) {
+            statsIndex = index;
+            break;
+        }
+        // Serialiser can emit `stats: {}` when the mapping has no children; treat
+        // that as an empty block to expand rather than synthesising a second key.
+        if (/^stats:\s*\{\}\s*$/.test(line)) {
+            statsIndex = index;
+            inlineEmptyStats = true;
+            break;
+        }
+    }
+    if (statsIndex === -1) {
+        // The contract lets an entry omit `stats` entirely (A-613). Rather than
+        // throwing, synthesise a minimal block carrying just the commits count,
+        // appended as the last frontmatter field (its canonical position) so no
+        // existing line shifts. The other stats children stay absent — this script
+        // sets only stats.commits.
+        lines.splice(fmEnd, 0, "stats:", `  commits: ${commits}`);
+        return lines.join("\n");
+    }
+    if (inlineEmptyStats) {
+        lines[statsIndex] = "stats:";
+        lines.splice(statsIndex + 1, 0, `  commits: ${commits}`);
+        return lines.join("\n");
+    }
+    // Walk the indented children of the stats block. The first dedented (or
+    // closing-fence) line ends it. Track the last child to append after, any
+    // existing commits line to replace in place, and the child indent so an
+    // inserted line nests under stats: at the same depth (don't hard-code two
+    // spaces — a 4-space block would otherwise be mis-nested; A-581).
+    let lastChild = statsIndex;
+    let commitsIndex = -1;
+    let childIndent = null;
+    for (let index = statsIndex + 1; index < fmEnd; index++) {
+        const line = lines[index];
+        if (line.trim() === "") {
+            continue;
+        }
+        const indentMatch = /^(\s+)/.exec(line);
+        if (!indentMatch) {
+            break;
+        }
+        if (childIndent === null) {
+            childIndent = indentMatch[1];
+        }
+        lastChild = index;
+        if (/^\s+commits:/.test(line)) {
+            commitsIndex = index;
+        }
+    }
+    // Fall back to two spaces only when the stats block has no children to mirror.
+    const indent = childIndent ?? "  ";
+    const newLine = `${indent}commits: ${commits}`;
+    if (commitsIndex === -1) {
+        lines.splice(lastChild + 1, 0, newLine);
+    }
+    else {
+        lines[commitsIndex] = newLine;
+    }
+    return lines.join("\n");
+}
+/**
+ * Pure backfill of a single entry's raw markdown. Returns the rewritten markdown
+ * with `stats.commits` set, or null when nothing changed (unresolvable PR, or
+ * the count already matches).
+ */
+export function backfillEntry(raw, run) {
+    const { data } = parseFrontmatter(raw);
+    const prNumber = resolvePrNumber(run, data);
+    if (prNumber === null) {
+        return null;
+    }
+    const count = nonMergeCommitCount(run, prNumber);
+    if (count === null) {
+        return null;
+    }
+    const commits = Number.parseInt(count, 10);
+    const existing = typeof data.stats === "object" &&
+        data.stats !== null &&
+        !Array.isArray(data.stats)
+        ? data.stats.commits
+        : undefined;
+    if (existing === commits) {
+        return null; // already backfilled with the same count
+    }
+    return setStatsCommits(raw, commits);
+}
+const USAGE = `backfill-commits — one-off backfill of stats.commits across the changelog backlog
+
+Walks the dated changelog/ entries and stamps stats.commits for each one whose
+merged PR resolves (via gh). Sets ONLY stats.commits; idempotent; best-effort per
+entry. WRITES to changelog/ files unless --dry-run.
+
+Usage:
+  changelog-core backfill-commits            Backfill every resolvable entry (writes; needs gh)
+  changelog-core backfill-commits --dry-run  Report what would change without writing
+  changelog-core backfill-commits --help     Show this message (alias: -h)`;
+export function main() {
+    const args = argv.slice(2);
+    if (args.includes("--help") || args.includes("-h")) {
+        console.log(USAGE);
+        return;
+    }
+    const dryRun = args.includes("--dry-run");
+    const config = loadConfig();
+    const run = realRunner;
+    const files = readdirSync(config.changelogDir)
+        .filter((name) => name.endsWith(".md") && name !== "README.md")
+        .map((name) => join(config.changelogDir, name));
+    let changed = 0;
+    let skipped = 0;
+    for (const file of files) {
+        let next = null;
+        try {
+            next = backfillEntry(readFileSync(file, "utf8"), run);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            console.warn(`⚠️  Skipped ${file}: ${message}`);
+            skipped++;
+            continue;
+        }
+        if (next === null) {
+            continue;
+        }
+        if (dryRun) {
+            console.log(`would backfill: ${file}`);
+        }
+        else {
+            writeFileSync(file, next);
+            console.log(`backfilled: ${file}`);
+        }
+        changed++;
+    }
+    console.log(`\n${dryRun ? "Would backfill" : "Backfilled"} ${changed} entr${changed === 1 ? "y" : "ies"}${skipped ? `, skipped ${skipped} on error` : ""}.`);
+}
+// Only run the filesystem pass when invoked as a CLI, not when imported by
+// tests.
+if (isCliEntry(import.meta.filename)) {
+    main();
+}

package/dist/commands/check-completeness.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Build the path regex for dated entries under a configured changelog directory.
+ */
+export declare function changelogEntryPattern(changelogDirectory: string): RegExp;
+export declare function isReleaseTriggering(prTitle: string): boolean;
+export declare function hasChangelogEntry(changedFiles: string[], changelogDirectory?: string): boolean;
+export type CompletenessResult = {
+    ok: boolean;
+    reason: string;
+};
+export declare function checkCompleteness(prTitle: string, changedFiles: string[], changelogDirectory?: string): CompletenessResult;
+export declare function main(): void;
+//# sourceMappingURL=check-completeness.d.ts.map

package/dist/commands/check-completeness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"check-completeness.d.ts","sourceRoot":"","sources":["../../src/commands/check-completeness.ts"],"names":[],"mappings":"AA6BA;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,kBAAkB,EAAE,MAAM,GAAG,MAAM,CAGxE;AAMD,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAG5D;AAED,wBAAgB,iBAAiB,CAC/B,YAAY,EAAE,MAAM,EAAE,EACtB,kBAAkB,GAAE,MAA8B,GACjD,OAAO,CAKT;AAED,MAAM,MAAM,kBAAkB,GAAG;IAC/B,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,EAAE,EACtB,kBAAkB,GAAE,MAA8B,GACjD,kBAAkB,CAmBpB;AAyFD,wBAAgB,IAAI,IAAI,IAAI,CAgC3B"}

package/dist/commands/check-completeness.js

@@ -0,0 +1,164 @@
+// Changelog-completeness gate (A-380). A release-triggering PR title
+// (`feat`/`fix`/breaking) MUST carry a dated changelog entry. This restores
+// the coupling Changesets gave for free — no changeset → no release — now that
+// release-please infers the bump from the Conventional-Commit PR title rather
+// than an explicit file.
+//
+// "Release-triggering" mirrors release-please's default node bump table:
+// `feat` (minor), `fix`/`perf`/`revert` (patch), and a `!` breaking marker
+// (major) cut a release; `docs`/`chore`/`ci`/`refactor`/`test`/`build`/`style`
+// do not.
+//
+// Inputs (env, set by the workflow):
+//   PR_TITLE — the pull request title (github.event.pull_request.title)
+//   BASE_REF — the base branch name (github.base_ref); defaults to "main"
+// Reads changed files from `git diff --name-only origin/<BASE_REF>...HEAD`.
+// Pure functions live exported for vitest.
+//
+// Zero-dep: Node built-ins only — no tsx, so CI runs it under bare `node`.
+import { isCliEntry } from "../lib/cli-entry.js";
+import { loadConfig } from "../lib/config.js";
+import { escapeRegex } from "../lib/vendor/issue-keys.js";
+import { execFileSync } from "node:child_process";
+import { argv } from "node:process";
+const RELEASE_TRIGGERING_TYPE = /^(feat|fix|perf|revert)(\([^)]+\))?:/;
+const BREAKING_SUBJECT = /^[a-z]+(\([^)]+\))?!:/;
+const DEFAULT_CHANGELOG_DIR = "changelog";
+/**
+ * Build the path regex for dated entries under a configured changelog directory.
+ */
+export function changelogEntryPattern(changelogDirectory) {
+    const directory = changelogDirectory.replace(/\/+$/, "");
+    return new RegExp(`^${escapeRegex(directory)}/.+\\.md$`);
+}
+function normalisedChangelogDirectory(changelogDirectory) {
+    return changelogDirectory.replace(/\/+$/, "");
+}
+export function isReleaseTriggering(prTitle) {
+    const title = prTitle.trim();
+    return BREAKING_SUBJECT.test(title) || RELEASE_TRIGGERING_TYPE.test(title);
+}
+export function hasChangelogEntry(changedFiles, changelogDirectory = DEFAULT_CHANGELOG_DIR) {
+    const directory = normalisedChangelogDirectory(changelogDirectory);
+    const pattern = changelogEntryPattern(directory);
+    const readme = `${directory}/README.md`;
+    return changedFiles.some((file) => pattern.test(file) && file !== readme);
+}
+export function checkCompleteness(prTitle, changedFiles, changelogDirectory = DEFAULT_CHANGELOG_DIR) {
+    if (!isReleaseTriggering(prTitle)) {
+        return {
+            ok: true,
+            reason: `PR title "${prTitle}" is not release-triggering — no changelog entry required.`,
+        };
+    }
+    if (hasChangelogEntry(changedFiles, changelogDirectory)) {
+        return {
+            ok: true,
+            reason: `Release-triggering PR title with a ${normalisedChangelogDirectory(changelogDirectory)}/ entry present.`,
+        };
+    }
+    return {
+        ok: false,
+        reason: `PR title "${prTitle}" triggers a release (feat/fix/breaking) but no ${normalisedChangelogDirectory(changelogDirectory)}/*.md entry is present in the diff vs the base branch. Run /send-it (or add a dated changelog entry) so the release carries notes.`,
+    };
+}
+function readChangedFiles(baseRef) {
+    // execFileSync (argv array, no shell) rather than execSync — consistent with
+    // finalise and keeps `baseRef` (from env) out of a shell string.
+    const out = execFileSync("git", ["diff", "--name-only", `origin/${baseRef}...HEAD`], { encoding: "utf8" });
+    return out
+        .split("\n")
+        .map((line) => line.trim())
+        .filter(Boolean);
+}
+const USAGE = `check-completeness — gate a release-triggering PR on a dated changelog entry
+
+Reads PR_TITLE and BASE_REF (default "main") from the environment and the changed
+files from \`git diff --name-only origin/<BASE_REF>...HEAD\`. A feat/fix/breaking
+PR title with no dated entry under the configured changelogDir fails the gate
+(exit 1).
+
+Usage:
+  PR_TITLE=… changelog-core check-completeness   Run the gate
+  changelog-core check-completeness --self-test   Run the built-in offline smoke test
+  changelog-core check-completeness --help        Show this message (alias: -h)`;
+// Offline smoke test: exercise the pure checkCompleteness / isReleaseTriggering
+// over representative inputs — no env, no git.
+function selfTest() {
+    const cases = [
+        {
+            name: "feat: title is release-triggering",
+            ok: isReleaseTriggering("feat: add a thing") === true,
+        },
+        {
+            name: "docs: title is not release-triggering",
+            ok: isReleaseTriggering("docs: tidy the readme") === false,
+        },
+        {
+            name: "breaking ! marker is release-triggering",
+            ok: isReleaseTriggering("feat(api)!: drop the old endpoint") === true,
+        },
+        {
+            name: "feat with a changelog entry passes the gate",
+            ok: checkCompleteness("feat: x", ["changelog/20260101-000000-a-1-x.md"])
+                .ok === true,
+        },
+        {
+            name: "feat with no changelog entry fails the gate",
+            ok: checkCompleteness("feat: x", ["skills/changelog/SKILL.md"]).ok ===
+                false,
+        },
+        {
+            name: "changelog/README.md does not satisfy the gate",
+            ok: checkCompleteness("fix: y", ["changelog/README.md"]).ok === false,
+        },
+        {
+            name: "custom changelogDir is honoured",
+            ok: checkCompleteness("feat: x", ["changelogs/20260101-000000-a-1-x.md"], "changelogs").ok === true,
+        },
+        {
+            name: "non-release-triggering title passes with no entry",
+            ok: checkCompleteness("chore: z", []).ok === true,
+        },
+    ];
+    let failed = 0;
+    for (const { name, ok } of cases) {
+        if (ok) {
+            console.log(`  ok    ${name}`);
+        }
+        else {
+            failed += 1;
+            console.log(`  FAIL  ${name}`);
+        }
+    }
+    console.log(`\n${cases.length - failed}/${cases.length} passed`);
+    process.exit(failed === 0 ? 0 : 1);
+}
+export function main() {
+    const args = argv.slice(2);
+    if (args.includes("--help") || args.includes("-h")) {
+        console.log(USAGE);
+        return;
+    }
+    if (args.includes("--self-test")) {
+        selfTest();
+        return;
+    }
+    const prTitle = process.env.PR_TITLE ?? "";
+    const baseRef = process.env.BASE_REF || "main";
+    if (!prTitle) {
+        console.error("PR_TITLE is not set — cannot run the changelog-completeness gate.");
+        process.exit(1);
+    }
+    const { changelogDir: changelogDirectory } = loadConfig();
+    const result = checkCompleteness(prTitle, readChangedFiles(baseRef), changelogDirectory);
+    console.log(result.reason);
+    if (!result.ok) {
+        process.exit(1);
+    }
+}
+// Only run when invoked as a CLI, not when imported (e.g. by unit tests
+// exercising the pure functions).
+if (isCliEntry(import.meta.filename)) {
+    main();
+}

package/dist/commands/enrich.d.ts

@@ -0,0 +1,17 @@
+import type { EnrichInput } from "../lib/enrich.js";
+/**
+ * Map the orchestrator's env-var interface into an EnrichInput. Absent or empty
+ * vars become null so enrichFrontmatter's `blank()` guards fire — and so
+ * `Number.parseInt` is never handed `""` (which is NaN, and the validator rejects
+ * it).
+ */
+export declare function readEnvironmentInput(environment: Record<string, string | undefined>): EnrichInput;
+/**
+ * Enrich one entry's raw markdown, returning the rewritten string — or null when
+ * enrichment changes nothing (an already-filled entry, since enrichFrontmatter's
+ * fill-once guards make a re-run a no-op). Lets callers detect no-ops without
+ * diffing frontmatter.
+ */
+export declare function enrichEntry(raw: string, input: EnrichInput): null | string;
+export declare function main(): void;
+//# sourceMappingURL=enrich.d.ts.map

package/dist/commands/enrich.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enrich.d.ts","sourceRoot":"","sources":["../../src/commands/enrich.ts"],"names":[],"mappings":"AAgCA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAKpD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GAC9C,WAAW,CAeb;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,GAAG,IAAI,GAAG,MAAM,CAG1E;AA0ED,wBAAgB,IAAI,IAAI,IAAI,CAuE3B"}

package/dist/commands/enrich.js

@@ -0,0 +1,194 @@
+// Post-merge enrichment of a single changelog entry — the DEPLOY-TARGET entry
+// point the release orchestrator's `enrich-changelogs.yml` cron invokes on a
+// checked-out target, one run per discovered entry.
+//
+// Deploy targets are never checked out during the release flow, so — unlike npm
+// targets, which enrich at release time via `finalise` — their entries can only
+// be filled afterwards, from the cron. This is the writer that cron had no
+// implementation for: it reads the per-PR data from the env-var interface below,
+// finds the entry by its `branch:` field, fills the post-merge fields, and writes
+// back.
+//
+// Env-var interface (all supplied by enrich-changelogs.yml):
+//   BRANCH_NAME     the entry's branch — the lookup key       (required)
+//   MERGED_AT       PR merged_at (ISO 8601 UTC)               (required)
+//   MERGE_SHA       merge commit SHA (only first 7 stored)    (required)
+//   PR_NUMBER       merged PR number                          (optional)
+//   ADDITIONS       lines added   -> stats.loc_added          (optional)
+//   DELETIONS       lines removed -> stats.loc_removed        (optional)
+//   CHANGED_FILES   files changed -> stats.files_changed      (optional)
+// The cron passes no commit count, so `stats.commits` is left to the release-time
+// path; the pure transform needs no `GH_TOKEN` (the cron empties it).
+//
+// Thin re-serialising wrapper: it delegates the actual field logic to
+// `lib/enrich#enrichFrontmatter`, which re-serialises the frontmatter. Enrichment
+// is fill-once via enrichFrontmatter's guards, so re-runs are idempotent.
+//
+// Zero-dep: composes the package's own lib modules, so it runs under bare `node`.
+import { findEntryByBranch } from "../lib/changelog.js";
+import { isCliEntry } from "../lib/cli-entry.js";
+import { loadConfig } from "../lib/config.js";
+import { enrichFrontmatter } from "../lib/enrich.js";
+import { parseFrontmatter } from "../lib/frontmatter.js";
+import { readFileSync, writeFileSync } from "node:fs";
+import { argv, env, exit } from "node:process";
+/**
+ * Map the orchestrator's env-var interface into an EnrichInput. Absent or empty
+ * vars become null so enrichFrontmatter's `blank()` guards fire — and so
+ * `Number.parseInt` is never handed `""` (which is NaN, and the validator rejects
+ * it).
+ */
+export function readEnvironmentInput(environment) {
+    function read(name) {
+        const value = environment[name];
+        return value === undefined || value === "" ? null : value;
+    }
+    return {
+        additions: read("ADDITIONS"),
+        branch: read("BRANCH_NAME") ?? "",
+        changedFiles: read("CHANGED_FILES"),
+        deletions: read("DELETIONS"),
+        mergedAt: read("MERGED_AT") ?? "",
+        mergeSha: read("MERGE_SHA") ?? "",
+        prNumber: read("PR_NUMBER"),
+    };
+}
+/**
+ * Enrich one entry's raw markdown, returning the rewritten string — or null when
+ * enrichment changes nothing (an already-filled entry, since enrichFrontmatter's
+ * fill-once guards make a re-run a no-op). Lets callers detect no-ops without
+ * diffing frontmatter.
+ */
+export function enrichEntry(raw, input) {
+    const next = enrichFrontmatter(raw, input);
+    return next === raw ? null : next;
+}
+const USAGE = `enrich — fill the post-merge fields of one changelog entry
+
+The deploy-target post-merge enricher: reads a merged PR's data from env vars,
+finds the entry by its branch, fills merged_at / commit / pr / stats via the
+shared enrich lib, and writes back. Fill-once and idempotent.
+
+Env vars: BRANCH_NAME, MERGED_AT, MERGE_SHA (required); PR_NUMBER, ADDITIONS,
+DELETIONS, CHANGED_FILES (optional).
+
+Usage:
+  changelog-core enrich             Enrich the entry for $BRANCH_NAME (writes)
+  changelog-core enrich --check     Exit 1 if the entry still needs enriching
+  changelog-core enrich --dry-run   Report what would change without writing
+  changelog-core enrich --self-test Offline smoke test of the pure logic
+  changelog-core enrich --help      Show this message (alias: -h)`;
+function assert(condition, message) {
+    if (!condition) {
+        throw new Error(message);
+    }
+}
+/**
+ * Offline smoke test of the pure logic — no filesystem, no network. Enriches an
+ * in-memory placeholder and asserts the fields land and a re-run is a no-op.
+ */
+function selfTest() {
+    const entry = [
+        "---",
+        'title: "Fix a thing"',
+        'created_at: "2026-05-23T14:55:37Z"',
+        'branch: "a-1-fix-a-thing"',
+        "merged_at:",
+        "pr:",
+        "commit:",
+        "category: fix",
+        "breaking: false",
+        "---",
+        "",
+        "## Fixed",
+        "",
+        "- A thing",
+        "",
+    ].join("\n");
+    const input = {
+        additions: "10",
+        branch: "a-1-fix-a-thing",
+        changedFiles: "3",
+        deletions: "2",
+        mergedAt: "2026-05-24T09:00:00Z",
+        mergeSha: "abc1234def5678",
+        prNumber: "7",
+    };
+    const out = enrichEntry(entry, input);
+    assert(out !== null, "expected enrichment to change the placeholder entry");
+    const { data } = parseFrontmatter(out);
+    assert(data.merged_at === "2026-05-24T09:00:00Z", "merged_at not filled");
+    assert(data.commit === "abc1234", "commit not filled to 7 chars");
+    assert(data.pr === 7, "blank pr must be resolved from prNumber");
+    assert(typeof data.stats === "object" &&
+        data.stats !== null &&
+        !Array.isArray(data.stats) &&
+        data.stats.loc_added === 10 &&
+        data.stats.loc_removed === 2 &&
+        data.stats.files_changed === 3, "stats not overwritten authoritatively");
+    assert(enrichEntry(out, input) === null, "re-run should be a no-op");
+}
+export function main() {
+    const args = argv.slice(2);
+    if (args.includes("--help") || args.includes("-h")) {
+        console.log(USAGE);
+        return;
+    }
+    if (args.includes("--self-test")) {
+        try {
+            selfTest();
+            console.log("✓ enrich self-test passed");
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            console.error(`✗ enrich self-test failed: ${message}`);
+            exit(1);
+        }
+        return;
+    }
+    const check = args.includes("--check");
+    const dryRun = args.includes("--dry-run");
+    const input = readEnvironmentInput(env);
+    // The cron always supplies these three; without them there is nothing to look
+    // up or fill, so this is a misinvocation rather than a no-op.
+    if (!input.branch || !input.mergedAt || !input.mergeSha) {
+        console.error("enrich: BRANCH_NAME, MERGED_AT and MERGE_SHA are required.\n");
+        console.error(USAGE);
+        exit(2);
+    }
+    const path = findEntryByBranch(input.branch, loadConfig().changelogDir);
+    if (path === null) {
+        // Discovery upstream may race with the entry's own merge; a missing entry is
+        // not the writer's failure to own — warn and succeed.
+        console.warn(`enrich: no entry for branch '${input.branch}' — nothing to enrich.`);
+        return;
+    }
+    let next = null;
+    try {
+        next = enrichEntry(readFileSync(path, "utf8"), input);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`enrich: ${path}: ${message}`);
+        exit(1);
+    }
+    if (next === null) {
+        console.log(`already enriched: ${path}`);
+        return;
+    }
+    if (check) {
+        // Completeness gate: the entry still needs enriching.
+        console.log(`would enrich: ${path}`);
+        exit(1);
+    }
+    if (dryRun) {
+        console.log(`would enrich: ${path}`);
+        return;
+    }
+    writeFileSync(path, next);
+    console.log(`enriched: ${path}`);
+}
+// Only run the filesystem pass when invoked as a CLI, not when imported by tests.
+if (isCliEntry(import.meta.filename)) {
+    main();
+}

package/dist/commands/finalise.d.ts

@@ -0,0 +1,25 @@
+import type { Runner } from "../lib/commit-count.js";
+export type ResolvedPr = {
+    additions: null | string;
+    changedFiles: null | string;
+    commits: null | string;
+    deletions: null | string;
+    mergedAt: string;
+    mergeSha: string;
+    prNumber: string;
+};
+/**
+ * Resolve the merged PR for a branch, or null when none is found.
+ */
+export type PrResolver = (branch: string) => null | ResolvedPr;
+/**
+ * Finalise one entry's raw markdown for release. Returns the rewritten markdown,
+ * or null when nothing changed (already finalised).
+ */
+export declare function finaliseEntry(raw: string, version: string, resolvePr: PrResolver): null | string;
+/**
+ * Build a PR resolver backed by `gh` (injectable runner for tests).
+ */
+export declare function makeResolver(run: Runner): PrResolver;
+export declare function main(): void;
+//# sourceMappingURL=finalise.d.ts.map

package/dist/commands/finalise.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"finalise.d.ts","sourceRoot":"","sources":["../../src/commands/finalise.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAUrD,MAAM,MAAM,UAAU,GAAG;IACvB,SAAS,EAAE,IAAI,GAAG,MAAM,CAAC;IACzB,YAAY,EAAE,IAAI,GAAG,MAAM,CAAC;IAC5B,OAAO,EAAE,IAAI,GAAG,MAAM,CAAC;IACvB,SAAS,EAAE,IAAI,GAAG,MAAM,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,GAAG,UAAU,CAAC;AAE/D;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,UAAU,GACpB,IAAI,GAAG,MAAM,CAmDf;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAwEpD;AAmFD,wBAAgB,IAAI,IAAI,IAAI,CAiC3B"}