@rheged-studio/changelog-core 1.1.1

package/dist/commands/finalise.js

@@ -0,0 +1,249 @@
+// Release-time finalisation of changelog entries — in-repo via
+// `reusable-changelog-enrich.yml` mode `finalise` / `changelog-core finalise`
+// after release-please bumps package.json (A-801 retired the central orchestrator
+// finalise). Reads the just-bumped version from package.json.
+//
+// For every entry that isn't finalised yet (empty `version`):
+//   1. resolve its merged PR from the `branch` field via `gh` and enrich
+//      (merged_at / commit / pr / stats);
+//   2. stamp `version` with the just-bumped package.json version;
+//   3. rewrite bare Linear IDs to links.
+//
+// The pure `finaliseEntry(raw, version, resolvePr)` is unit-testable with a fake
+// resolver; main() wires the real `gh`/`git` resolver and walks the directory.
+//
+// Zero-dep: composes the package's own modules (lib/enrich, lib/stamp,
+// add-links) and the frontmatter parser — no gray-matter, no tsx — so it runs
+// under bare `node`. The Linear workspace/issue keys come from config.json via
+// add-links, not hardcoded constants.
+import { blank } from "../lib/blank.js";
+import { isCliEntry } from "../lib/cli-entry.js";
+import { nonMergeCommitCount, realRunner } from "../lib/commit-count.js";
+import { loadConfig } from "../lib/config.js";
+import { enrichFrontmatter } from "../lib/enrich.js";
+import { parseFrontmatter } from "../lib/frontmatter.js";
+import { readPackageVersion, stampVersion } from "../lib/stamp.js";
+import { rewriteBody, splitFrontmatter } from "./add-links.js";
+import { readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { argv } from "node:process";
+/**
+ * Finalise one entry's raw markdown for release. Returns the rewritten markdown,
+ * or null when nothing changed (already finalised).
+ */
+export function finaliseEntry(raw, version, resolvePr) {
+    const fm = parseFrontmatter(raw).data;
+    if (!blank(fm.version)) {
+        return null; // already shipped in a release
+    }
+    let next = raw;
+    const branch = typeof fm.branch === "string" ? fm.branch : "";
+    // Include blank(fm.stats) so a hand-authored entry that pre-fills
+    // merged_at/commit/pr but leaves stats blank still gets stats from the PR.
+    // Also treat a populated-but-commits-less stats block as enrichable: an entry
+    // finalised in the window between `stats` first existing (A-380) and
+    // `stats.commits` being added (A-560) has every other field set, so without
+    // the `stats.commits` check needsEnrich is false, enrich is skipped, the entry
+    // is version-stamped, and the later version short-circuit makes the missing
+    // `commits` un-backfillable through finalise forever (A-579).
+    const stats = typeof fm.stats === "object" &&
+        fm.stats !== null &&
+        !Array.isArray(fm.stats)
+        ? fm.stats
+        : null;
+    const needsEnrich = blank(fm.merged_at) ||
+        blank(fm.commit) ||
+        blank(fm.pr) ||
+        blank(fm.stats) ||
+        blank(stats?.commits);
+    if (branch && needsEnrich) {
+        const pr = resolvePr(branch);
+        if (pr) {
+            next = enrichFrontmatter(next, {
+                additions: pr.additions,
+                branch,
+                changedFiles: pr.changedFiles,
+                commits: pr.commits,
+                deletions: pr.deletions,
+                mergedAt: pr.mergedAt,
+                mergeSha: pr.mergeSha,
+                prNumber: pr.prNumber,
+            });
+        }
+    }
+    next = stampVersion(next, version) ?? next;
+    const { body, fm: fmText } = splitFrontmatter(next);
+    next = fmText + rewriteBody(body);
+    return next === raw ? null : next;
+}
+/**
+ * Build a PR resolver backed by `gh` (injectable runner for tests).
+ */
+export function makeResolver(run) {
+    function resolve(branch) {
+        const json = run("gh", [
+            "pr",
+            "list",
+            "--head",
+            branch,
+            "--state",
+            "merged",
+            "--limit",
+            "1",
+            "--json",
+            "number,mergedAt,additions,deletions,changedFiles,mergeCommit",
+        ]);
+        const list = JSON.parse(json);
+        if (!Array.isArray(list) || list.length === 0) {
+            return null;
+        }
+        const pr = list[0];
+        const mergeSha = pr.mergeCommit?.oid ?? "";
+        // Commit count is resolved separately (a second API call). Keep it
+        // independently best-effort: a failure here leaves commits null but must NOT
+        // discard the stats we already resolved, so it gets its own try/catch rather
+        // than riding the outer one (which would null the whole ResolvedPr).
+        let commits = null;
+        if (pr.number !== undefined && pr.number !== null) {
+            try {
+                commits = nonMergeCommitCount(run, pr.number);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                console.warn(`⚠️  Could not resolve commit count for PR #${pr.number}: ${message}`);
+            }
+        }
+        // Absent numeric fields stay null (not ""), so the enrich guard skips them
+        // rather than parsing "" into NaN.
+        return {
+            additions: pr.additions === undefined ? null : String(pr.additions),
+            changedFiles: pr.changedFiles === undefined ? null : String(pr.changedFiles),
+            commits,
+            deletions: pr.deletions === undefined ? null : String(pr.deletions),
+            mergedAt: pr.mergedAt ?? "",
+            mergeSha,
+            prNumber: String(pr.number ?? ""),
+        };
+    }
+    return (branch) => {
+        // Enrichment is best-effort metadata: a gh/git failure here must NOT abort
+        // the release-please release-PR build and block the release. On any error,
+        // warn and return null — the entry still gets version-stamped, just without
+        // PR metadata.
+        try {
+            return resolve(branch);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            console.warn(`⚠️  Could not resolve PR for branch ${branch}: ${message}`);
+            return null;
+        }
+    };
+}
+const USAGE = `finalise — release-time enrich + version-stamp the dated changelog/ entries
+
+In-repo via \`reusable-changelog-enrich.yml\` mode \`finalise\` / \`changelog-core finalise\`
+after release-please bumps package.json. Reads the just-bumped version, then for every
+un-finalised entry: resolves its merged PR via \`gh\` to enrich (merged_at/commit/pr/stats),
+stamps \`version\`, and rewrites bare Linear IDs to links. WRITES to changelog/ files.
+
+Usage:
+  changelog-core finalise            Finalise every un-finalised entry (writes; needs gh)
+  changelog-core finalise --self-test  Run the built-in offline smoke test
+  changelog-core finalise --help     Show this message (alias: -h)`;
+// Offline smoke-test resolver — a fixed fake PR, no gh/git.
+function fakeResolver() {
+    return {
+        additions: "10",
+        changedFiles: "2",
+        commits: "4",
+        deletions: "3",
+        mergedAt: "2026-01-02T00:00:00Z",
+        mergeSha: "abcdef1234567890",
+        prNumber: "42",
+    };
+}
+// Offline smoke test: exercise the pure finaliseEntry with a fake resolver — no
+// gh, no git, no real package.json, no filesystem writes.
+function selfTest() {
+    const cases = [];
+    const unfinalised = `---
+title: Sample
+created_at: '2026-01-01T00:00:00Z'
+merged_at:
+branch: a-1-sample
+pr:
+commit:
+version:
+category: feature
+breaking: false
+stats:
+  files_changed:
+  loc_added:
+  loc_removed:
+---
+
+## Added
+
+- A thing.
+`;
+    const finalised = finaliseEntry(unfinalised, "1.2.3", () => fakeResolver());
+    cases.push({
+        name: "an un-finalised entry is rewritten",
+        ok: typeof finalised === "string" && finalised !== unfinalised,
+    });
+    cases.push({
+        name: "the bumped version is stamped",
+        ok: typeof finalised === "string" && finalised.includes("version: 1.2.3"),
+    });
+    // An already-stamped entry is a no-op (returns null).
+    const alreadyDone = (finalised ?? unfinalised).replace(/\n$/, "\n");
+    cases.push({
+        name: "an already-finalised entry returns null (no rewrite)",
+        ok: finaliseEntry(alreadyDone, "1.2.3", () => fakeResolver()) === null,
+    });
+    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 config = loadConfig();
+    const version = readPackageVersion(readFileSync("package.json", "utf8"));
+    const resolvePr = makeResolver(realRunner);
+    const files = readdirSync(config.changelogDir)
+        .filter((name) => name.endsWith(".md") && name !== "README.md")
+        .map((name) => join(config.changelogDir, name));
+    let finalised = 0;
+    for (const file of files) {
+        const next = finaliseEntry(readFileSync(file, "utf8"), version, resolvePr);
+        if (next !== null) {
+            writeFileSync(file, next);
+            finalised++;
+            console.log(`finalised ${version}: ${file}`);
+        }
+    }
+    console.log(`Changelog finalisation complete. ${finalised} entr${finalised === 1 ? "y" : "ies"} finalised with ${version}.`);
+}
+// Only run the filesystem pass when invoked as a CLI, not when imported (e.g.
+// by unit tests exercising finaliseEntry/makeResolver).
+if (isCliEntry(import.meta.filename)) {
+    main();
+}

package/dist/commands/set-affected-packages.d.ts

@@ -0,0 +1,13 @@
+import type { FrontmatterData } from "../lib/frontmatter.js";
+/**
+ * Rebuild an entry's frontmatter with `affected_packages` set, in canonical
+ * field order (`affected_packages` immediately before `stats`).
+ *
+ * Guards against a destructive overwrite: if `data` is empty or lacks the
+ * expected `branch` key — which is what `parseFrontmatter` returns when the
+ * entry has no parseable frontmatter — throw rather than clobber the file with
+ * just `affected_packages`.
+ */
+export declare function buildAffectedPackagesFrontmatter(data: FrontmatterData, packages: string[]): FrontmatterData;
+export declare function main(): void;
+//# sourceMappingURL=set-affected-packages.d.ts.map

package/dist/commands/set-affected-packages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"set-affected-packages.d.ts","sourceRoot":"","sources":["../../src/commands/set-affected-packages.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAK7D;;;;;;;;GAQG;AACH,wBAAgB,gCAAgC,CAC9C,IAAI,EAAE,eAAe,EACrB,QAAQ,EAAE,MAAM,EAAE,GACjB,eAAe,CA6BjB;AAiGD,wBAAgB,IAAI,IAAI,IAAI,CA+E3B"}

package/dist/commands/set-affected-packages.js

@@ -0,0 +1,207 @@
+// Merge-time half of changelog enrichment.
+//
+// `affected_packages` is knowable before merge — it's just the set of workspace
+// packages the branch diff touches — so the changelog step computes it at write
+// time rather than waiting for a privileged post-merge step. This script reads
+// the branch diff against the base, maps it through the shared
+// `derivePackagesFromPaths` rule, and writes the result into the changelog entry
+// for the current branch.
+//
+// The post-merge-only fields (`merged_at`, `commit`, and authoritative `stats`)
+// are deliberately NOT touched here — they're owned by the release-orchestrator
+// and stay blank until it fills them.
+//
+// Env overrides (both optional):
+//   BASE_REF    — base to diff against (default: origin/<baseBranch> from config.json)
+//   BRANCH_NAME — entry lookup key (default: current branch via git)
+import { findEntryByBranch } from "../lib/changelog.js";
+import { isCliEntry } from "../lib/cli-entry.js";
+import { loadConfig } from "../lib/config.js";
+import { derivePackagesFromPaths } from "../lib/derive-packages.js";
+import { parseFrontmatter, stringifyFrontmatter } from "../lib/frontmatter.js";
+import { execFileSync } from "node:child_process";
+import { readFileSync, writeFileSync } from "node:fs";
+import { argv, env } from "node:process";
+/**
+ * Rebuild an entry's frontmatter with `affected_packages` set, in canonical
+ * field order (`affected_packages` immediately before `stats`).
+ *
+ * Guards against a destructive overwrite: if `data` is empty or lacks the
+ * expected `branch` key — which is what `parseFrontmatter` returns when the
+ * entry has no parseable frontmatter — throw rather than clobber the file with
+ * just `affected_packages`.
+ */
+export function buildAffectedPackagesFrontmatter(data, packages) {
+    if (!data || typeof data !== "object" || !("branch" in data)) {
+        throw new Error("Refusing to write affected_packages: entry frontmatter is empty or " +
+            "missing the `branch` key — parsing likely failed. Writing would " +
+            "overwrite the entry with only affected_packages.");
+    }
+    const fm = {};
+    for (const [key, value] of Object.entries(data)) {
+        if (key === "affected_packages") {
+            continue; // re-inserted in its canonical slot below
+        }
+        if (key === "stats") {
+            fm.affected_packages = packages;
+        }
+        fm[key] = value;
+    }
+    if (!("affected_packages" in fm)) {
+        // No `stats` key to anchor against; append (a missing `stats` is itself a
+        // contract violation the validator will flag).
+        fm.affected_packages = packages;
+    }
+    return fm;
+}
+function git(args) {
+    let out;
+    try {
+        out = execFileSync("git", args, { encoding: "utf8" });
+    }
+    catch (error) {
+        // Most likely cause when run standalone: BASE_REF isn't fetched. In a ship
+        // flow the base is fetched before this runs.
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`git ${args.join(" ")} failed: ${message}`);
+        process.exit(1);
+    }
+    return out.trim();
+}
+function currentBranch() {
+    const fromEnvironment = env.BRANCH_NAME?.trim();
+    if (fromEnvironment) {
+        return fromEnvironment;
+    }
+    return git(["rev-parse", "--abbrev-ref", "HEAD"]);
+}
+function changedPaths(base) {
+    // Three-dot: files changed on the branch since it diverged from base, so
+    // unrelated churn that landed on base meanwhile doesn't leak in.
+    const out = git(["diff", "--name-only", `${base}...HEAD`]);
+    return out ? out.split("\n") : [];
+}
+const USAGE = `set-affected-packages — write affected_packages into the current branch's changelog entry
+
+Monorepo-only (config.json affectedPackages: true; a no-op otherwise). Diffs the
+branch against the base, maps the changed paths through the shared package rule,
+and writes the derived list into the entry's frontmatter (canonical field order).
+
+Env overrides: BASE_REF (default origin/<baseBranch>), BRANCH_NAME (default git HEAD).
+
+Usage:
+  changelog-core set-affected-packages            Derive + write affected_packages (writes; needs git)
+  changelog-core set-affected-packages --check    Report what would change; write nothing (alias: --dry-run)
+  changelog-core set-affected-packages --self-test  Run the built-in offline smoke test
+  changelog-core set-affected-packages --help     Show this message (alias: -h)`;
+// Offline smoke test: exercise the pure buildAffectedPackagesFrontmatter — no
+// git, no filesystem.
+function selfTest() {
+    const cases = [];
+    const data = {
+        branch: "a-1-sample",
+        stats: { files_changed: null },
+        title: "Sample",
+    };
+    const rebuilt = buildAffectedPackagesFrontmatter(data, ["skills/changelog"]);
+    cases.push({
+        name: "affected_packages is set from the derived list",
+        ok: JSON.stringify(rebuilt.affected_packages) ===
+            JSON.stringify(["skills/changelog"]),
+    });
+    cases.push({
+        name: "affected_packages is inserted immediately before stats",
+        ok: Object.keys(rebuilt).indexOf("affected_packages") ===
+            Object.keys(rebuilt).indexOf("stats") - 1,
+    });
+    let guardThrew = false;
+    try {
+        buildAffectedPackagesFrontmatter({}, ["x"]);
+    }
+    catch {
+        guardThrew = true;
+    }
+    cases.push({
+        name: "refuses to write when frontmatter lacks the branch key",
+        ok: guardThrew,
+    });
+    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;
+    }
+    // --check (alias --dry-run): report what would change and write nothing.
+    // Exit 0 when already up to date, 1 when a rewrite is needed — prettier-style,
+    // so CI can gate on it.
+    const check = args.some((argument) => argument === "--check" || argument === "--dry-run");
+    const config = loadConfig();
+    // `affected_packages` is monorepo-only. Single-package repos leave
+    // `affectedPackages: false` (the default) so entries stay clean — the field
+    // is write-only and redundant there, and the validator treats it as
+    // optional-when-present. No-op in both normal and --check modes so CI never
+    // demands a rewrite. Genuine monorepos opt in via `affectedPackages: true`.
+    if (!config.affectedPackages) {
+        console.log("affectedPackages is off (config.json sets it false, or omits it and it " +
+            "defaults to false) — affected_packages not emitted. Nothing to set.");
+        process.exit(0);
+    }
+    const BASE_REF = env.BASE_REF?.trim() || `origin/${config.baseBranch}`;
+    const branch = currentBranch();
+    const file = findEntryByBranch(branch, config.changelogDir);
+    if (!file) {
+        console.log(`No changelog entry found for branch '${branch}'. Nothing to set.`);
+        process.exit(0);
+    }
+    const packages = derivePackagesFromPaths(changedPaths(BASE_REF), {
+        changelogDir: config.changelogDir,
+        fallbackPackage: config.fallbackPackage,
+        packageRoots: config.packageRoots,
+    });
+    const raw = readFileSync(file, "utf8");
+    const parsed = parseFrontmatter(raw);
+    // Always overwrite (not fill-only like the post-merge fields): re-running must
+    // re-derive affected_packages from the latest branch diff as commits are added.
+    //
+    // Rebuild in canonical field order via the guarded helper, which refuses to
+    // write when the parse yielded empty/branch-less data (a destructive overwrite).
+    const fm = buildAffectedPackagesFrontmatter(parsed.data, packages);
+    const next = stringifyFrontmatter(parsed.content, fm);
+    if (check) {
+        if (next === raw) {
+            console.log(`affected_packages already up to date on ${file}`);
+            console.log(`  affected_packages=${JSON.stringify(packages)}`);
+            process.exit(0);
+        }
+        console.log(`[check] would set affected_packages on ${file}`);
+        console.log(`  branch=${branch} base=${BASE_REF}`);
+        console.log(`  affected_packages=${JSON.stringify(packages)}`);
+        process.exit(1);
+    }
+    writeFileSync(file, next);
+    console.log(`Set affected_packages on ${file}`);
+    console.log(`  branch=${branch} base=${BASE_REF}`);
+    console.log(`  affected_packages=${JSON.stringify(packages)}`);
+}
+// Only run when invoked as a CLI, not when imported (e.g. by unit tests
+// exercising `buildAffectedPackagesFrontmatter`).
+if (isCliEntry(import.meta.filename)) {
+    main();
+}

package/dist/commands/validate.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Validate one entry. Returns an array of human-readable error strings.
+ */
+export declare function validateEntry(name: string, raw: string): string[];
+export declare function main(): void;
+//# sourceMappingURL=validate.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/commands/validate.ts"],"names":[],"mappings":"AAqEA;;GAEG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAkKjE;AA4FD,wBAAgB,IAAI,IAAI,IAAI,CAgC3B"}