@rheged-studio/changelog-core 1.1.1

package/dist/commands/validate.js

@@ -0,0 +1,293 @@
+// Validates the individual dated changelog entries under `changelog/`.
+//
+// The single authored changelog validator (A-369): this is the only copy —
+// the root `validate:changelog` script and consumers both run it.
+//   - `version` is accepted (typed-when-present semver string).
+//   - `affected_packages` is accepted (typed-when-present string array) — owned
+//     by the merge-time set-affected-packages step on monorepo consumers.
+//   - the REQUIRED set is relaxed to title/created_at/category/breaking so that
+//     both backfilled historical entries (no branch/author/stats) and in-flight
+//     entries (no version/merged_at/pr/commit/stats until enriched) validate.
+//
+// The pure `validateEntry(name, raw)` returns an array of error strings (empty
+// means valid), so it's trivially unit-testable; main() walks the directory.
+// Zero-dep — Node built-ins + the package's frontmatter parser.
+import { isCliEntry } from "../lib/cli-entry.js";
+import { loadConfig } from "../lib/config.js";
+import { parseFrontmatter } from "../lib/frontmatter.js";
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { basename, join } from "node:path";
+import { argv } from "node:process";
+const FILENAME_RE = /^(\d{8})-(\d{6})-([a-z0-9-]+)\.md$/;
+const ISO_UTC_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/;
+// SemVer 2.0.0: prerelease and build identifiers are dot-separated and may
+// contain ASCII alphanumerics and hyphens (e.g. 1.2.3-rc-1, 1.2.3+build-45).
+const SEMVER_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+const SHA7_RE = /^[0-9a-f]{7}$/;
+const ISSUE_RE = /^[A-Z]+-\d+$/;
+const CATEGORIES = new Set([
+    "chore",
+    "docs",
+    "feature",
+    "fix",
+    "perf",
+    "refactor",
+]);
+const SECTION_RE = /^##\s+(Breaking|Added|Changed|Fixed)\b/m;
+const REQUIRED = ["title", "created_at", "category", "breaking"];
+/**
+ * True when a value is set to something meaningful (not null/undefined/"").
+ */
+function present(value) {
+    return value !== null && value !== undefined && value !== "";
+}
+function isInt(value) {
+    return typeof value === "number" && Number.isInteger(value);
+}
+function isNonNegInt(value) {
+    return isInt(value) && value >= 0;
+}
+function isStringArray(value) {
+    return (Array.isArray(value) && value.every((item) => typeof item === "string"));
+}
+function asIso(value) {
+    // The frontmatter parser only ever yields strings for timestamps, so a
+    // non-string is treated as absent.
+    return typeof value === "string" ? value : "";
+}
+/**
+ * Validate one entry. Returns an array of human-readable error strings.
+ */
+export function validateEntry(name, raw) {
+    const errors = [];
+    function fail(message) {
+        errors.push(`${name}: ${message}`);
+    }
+    if (!FILENAME_RE.test(name)) {
+        fail("filename must match YYYYMMDD-HHMMSS-<slug>.md (slug: [a-z0-9-]+)");
+        return errors;
+    }
+    let parsed;
+    try {
+        parsed = parseFrontmatter(raw);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        fail(`frontmatter unparseable: ${message}`);
+        return errors;
+    }
+    const fm = parsed.data ?? {};
+    const body = parsed.content ?? "";
+    for (const key of REQUIRED) {
+        if (!(key in fm)) {
+            fail(`missing required field: ${key}`);
+        }
+    }
+    if ("title" in fm &&
+        (typeof fm.title !== "string" || fm.title.trim() === "")) {
+        fail("title must be a non-empty string");
+    }
+    if ("release_note" in fm &&
+        fm.release_note !== null &&
+        typeof fm.release_note !== "string") {
+        fail("release_note must be a string or null when present");
+    }
+    if (present(fm.version) &&
+        (typeof fm.version !== "string" || !SEMVER_RE.test(fm.version))) {
+        fail(`version must be a semver string when set (got ${JSON.stringify(fm.version)})`);
+    }
+    if ("created_at" in fm && !ISO_UTC_RE.test(asIso(fm.created_at))) {
+        fail(`created_at must be ISO 8601 UTC with Z suffix (got ${JSON.stringify(fm.created_at)})`);
+    }
+    if (present(fm.merged_at) && !ISO_UTC_RE.test(asIso(fm.merged_at))) {
+        fail("merged_at must be ISO 8601 UTC with Z suffix when set");
+    }
+    if ("branch" in fm &&
+        (typeof fm.branch !== "string" || fm.branch.trim() === "")) {
+        fail("branch must be a non-empty string when present");
+    }
+    if (present(fm.pr) && !isInt(fm.pr)) {
+        fail("pr must be an integer when set");
+    }
+    if (present(fm.commit) && !SHA7_RE.test(String(fm.commit))) {
+        fail("commit must be a 7-char hex SHA when set");
+    }
+    if ("author" in fm &&
+        (typeof fm.author !== "string" || fm.author.trim() === "")) {
+        fail("author must be a non-empty string when present");
+    }
+    if ("co_authors" in fm && !isStringArray(fm.co_authors)) {
+        fail("co_authors must be an array of strings (use [] when none)");
+    }
+    if ("category" in fm && !CATEGORIES.has(String(fm.category))) {
+        fail(`category must be one of: ${[...CATEGORIES].join(", ")}`);
+    }
+    if ("breaking" in fm && typeof fm.breaking !== "boolean") {
+        fail("breaking must be a boolean");
+    }
+    if ("issues" in fm) {
+        if (isStringArray(fm.issues)) {
+            for (const id of fm.issues) {
+                if (!ISSUE_RE.test(id)) {
+                    fail(`issues entry ${JSON.stringify(id)} must match [A-Z]+-\\d+`);
+                }
+            }
+        }
+        else {
+            fail("issues must be an array of strings when present");
+        }
+    }
+    // affected_packages is owned by the merge-time set-affected-packages step on
+    // monorepo consumers. The author emits an empty array as a placeholder; the
+    // step overwrites it with the canonical list derived from the PR diff. Only
+    // enforce structure (string array) when present.
+    if ("affected_packages" in fm &&
+        fm.affected_packages !== null &&
+        !isStringArray(fm.affected_packages)) {
+        fail("affected_packages must be an array of strings (use [] when unpopulated)");
+    }
+    // PR stats live under stats: { files_changed, loc_added, loc_removed, commits }.
+    const statKeys = ["files_changed", "loc_added", "loc_removed", "commits"];
+    for (const key of statKeys) {
+        if (key in fm) {
+            fail(`${key} must be under stats, not top-level`);
+        }
+    }
+    // stats is optional (filled by enrichment), but must be a well-formed object
+    // with non-negative integer values when present.
+    if (present(fm.stats)) {
+        if (typeof fm.stats !== "object" || Array.isArray(fm.stats)) {
+            fail("stats must be an object");
+        }
+        else {
+            const stats = fm.stats;
+            for (const key of statKeys) {
+                if (key in stats && present(stats[key]) && !isNonNegInt(stats[key])) {
+                    fail(`stats.${key} must be a non-negative integer when set`);
+                }
+            }
+        }
+    }
+    // The schema requires "## Breaking" to be the FIRST body section when
+    // breaking: true — not merely present somewhere.
+    if (fm.breaking === true) {
+        const firstSection = body.match(/^##\s+([A-Za-z]+)\b/m)?.[1];
+        if (firstSection !== "Breaking") {
+            fail('breaking: true requires "## Breaking" as the first body section');
+        }
+    }
+    if (!SECTION_RE.test(body)) {
+        fail("body must contain at least one of: ## Breaking | ## Added | ## Changed | ## Fixed");
+    }
+    return errors;
+}
+const USAGE = `validate — validate the dated changelog/ entries against the contract
+
+Usage:
+  changelog-core validate            Validate every changelog/<ts>-<slug>.md entry
+  changelog-core validate --self-test  Run the built-in offline smoke test
+  changelog-core validate --help     Show this message (alias: -h)
+
+Exits 1 when an entry is invalid, 2 when the changelog directory is missing.`;
+// Offline smoke test: run the pure validateEntry over a known-good and a
+// known-bad entry. This is a light check that the exported logic is wired up,
+// with no filesystem or network access.
+function selfTest() {
+    const cases = [];
+    const goodName = "20260101-000000-a-1-sample.md";
+    const goodRaw = `---
+title: A sample entry
+created_at: '2026-01-01T00:00:00Z'
+category: feature
+breaking: false
+---
+
+## Added
+
+- Something.
+`;
+    cases.push({
+        name: "a well-formed entry produces no errors",
+        ok: validateEntry(goodName, goodRaw).length === 0,
+    });
+    cases.push({
+        name: "a bad filename is rejected",
+        ok: validateEntry("not-a-valid-name.md", goodRaw).length > 0,
+    });
+    const badCategory = goodRaw.replace("category: feature", "category: nope");
+    cases.push({
+        name: "an unknown category is rejected",
+        ok: validateEntry(goodName, badCategory).length > 0,
+    });
+    const missingSection = `---
+title: No body section
+created_at: '2026-01-01T00:00:00Z'
+category: docs
+breaking: false
+---
+
+Just prose, no heading.
+`;
+    cases.push({
+        name: "a body with no recognised section is rejected",
+        ok: validateEntry(goodName, missingSection).length > 0,
+    });
+    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);
+}
+function listEntries(directory) {
+    let stat;
+    try {
+        stat = statSync(directory);
+    }
+    catch {
+        console.error(`changelog directory not found: ${directory}`);
+        process.exit(2);
+    }
+    if (!stat.isDirectory()) {
+        console.error(`${directory} is not a directory`);
+        process.exit(2);
+    }
+    return readdirSync(directory)
+        .filter((name) => name.endsWith(".md") && name !== "README.md")
+        .map((name) => join(directory, name));
+}
+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 files = listEntries(loadConfig().changelogDir);
+    const errors = [];
+    for (const file of files) {
+        errors.push(...validateEntry(basename(file), readFileSync(file, "utf8")));
+    }
+    if (errors.length > 0) {
+        console.error(`Changelog validation failed with ${errors.length} error(s):\n`);
+        for (const message of errors) {
+            console.error(`  - ${message}`);
+        }
+        process.exit(1);
+    }
+    console.log(`Changelog validation passed (${files.length} entr${files.length === 1 ? "y" : "ies"} checked).`);
+}
+// Only run the filesystem pass when invoked as a CLI, not when imported (e.g.
+// by unit tests exercising validateEntry).
+if (isCliEntry(import.meta.filename)) {
+    main();
+}

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Public API for @acme-skunkworks/changelog-core.
+ *
+ * Library helpers and command pure functions — the CLI lives in `cli.ts`.
+ */
+export { frontmatterBranch, rewriteBody, splitFrontmatter, } from "./commands/add-links.js";
+export { backfillEntry, resolvePrNumber } from "./commands/backfill-commits.js";
+export { changelogEntryPattern, checkCompleteness, type CompletenessResult, hasChangelogEntry, isReleaseTriggering, } from "./commands/check-completeness.js";
+export { enrichEntry, readEnvironmentInput } from "./commands/enrich.js";
+export { finaliseEntry, makeResolver, type PrResolver, type ResolvedPr, } from "./commands/finalise.js";
+export { buildAffectedPackagesFrontmatter } from "./commands/set-affected-packages.js";
+export { validateEntry } from "./commands/validate.js";
+export { blank } from "./lib/blank.js";
+export { findEntryByBranch } from "./lib/changelog.js";
+export { isCliEntry } from "./lib/cli-entry.js";
+export { nonMergeCommitCount, realRunner, type Runner, } from "./lib/commit-count.js";
+export { type ChangelogConfig, loadConfig, parseConfig, resetConfigCache, } from "./lib/config.js";
+export { derivePackagesFromPaths, type DerivePackagesOptions, } from "./lib/derive-packages.js";
+export { enrichFrontmatter, type EnrichInput } from "./lib/enrich.js";
+export { type FrontmatterData, type FrontmatterValue, type ParsedFrontmatter, parseFrontmatter, stringifyFrontmatter, } from "./lib/frontmatter.js";
+export { readPackageVersion, stampVersion } from "./lib/stamp.js";
+export { buildIssueRe, escapeRegex } from "./lib/vendor/issue-keys.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,EACL,iBAAiB,EACjB,WAAW,EACX,gBAAgB,GACjB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AAChF,OAAO,EACL,qBAAqB,EACrB,iBAAiB,EACjB,KAAK,kBAAkB,EACvB,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EAAE,WAAW,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AACzE,OAAO,EACL,aAAa,EACb,YAAY,EACZ,KAAK,UAAU,EACf,KAAK,UAAU,GAChB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,gCAAgC,EAAE,MAAM,qCAAqC,CAAC;AACvF,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAIvD,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AACvC,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,EACL,mBAAmB,EACnB,UAAU,EACV,KAAK,MAAM,GACZ,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,KAAK,eAAe,EACpB,UAAU,EACV,WAAW,EACX,gBAAgB,GACjB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,uBAAuB,EACvB,KAAK,qBAAqB,GAC3B,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,iBAAiB,EAAE,KAAK,WAAW,EAAE,MAAM,iBAAiB,CAAC;AACtE,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,gBAAgB,EAChB,oBAAoB,GACrB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAClE,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC"}

package/dist/index.js

@@ -0,0 +1,24 @@
+/**
+ * Public API for @acme-skunkworks/changelog-core.
+ *
+ * Library helpers and command pure functions — the CLI lives in `cli.ts`.
+ */
+// --- commands (pure helpers) ------------------------------------------------
+export { frontmatterBranch, rewriteBody, splitFrontmatter, } from "./commands/add-links.js";
+export { backfillEntry, resolvePrNumber } from "./commands/backfill-commits.js";
+export { changelogEntryPattern, checkCompleteness, hasChangelogEntry, isReleaseTriggering, } from "./commands/check-completeness.js";
+export { enrichEntry, readEnvironmentInput } from "./commands/enrich.js";
+export { finaliseEntry, makeResolver, } from "./commands/finalise.js";
+export { buildAffectedPackagesFrontmatter } from "./commands/set-affected-packages.js";
+export { validateEntry } from "./commands/validate.js";
+// --- lib --------------------------------------------------------------------
+export { blank } from "./lib/blank.js";
+export { findEntryByBranch } from "./lib/changelog.js";
+export { isCliEntry } from "./lib/cli-entry.js";
+export { nonMergeCommitCount, realRunner, } from "./lib/commit-count.js";
+export { loadConfig, parseConfig, resetConfigCache, } from "./lib/config.js";
+export { derivePackagesFromPaths, } from "./lib/derive-packages.js";
+export { enrichFrontmatter } from "./lib/enrich.js";
+export { parseFrontmatter, stringifyFrontmatter, } from "./lib/frontmatter.js";
+export { readPackageVersion, stampVersion } from "./lib/stamp.js";
+export { buildIssueRe, escapeRegex } from "./lib/vendor/issue-keys.js";

package/dist/lib/blank.d.ts

@@ -0,0 +1,5 @@
+/**
+ * True when a value is unset (null/undefined/"").
+ */
+export declare function blank(value: unknown): boolean;
+//# sourceMappingURL=blank.d.ts.map

package/dist/lib/blank.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blank.d.ts","sourceRoot":"","sources":["../../src/lib/blank.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE7C"}

package/dist/lib/blank.js

@@ -0,0 +1,6 @@
+/**
+ * True when a value is unset (null/undefined/"").
+ */
+export function blank(value) {
+    return value === null || value === undefined || value === "";
+}

package/dist/lib/changelog.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Find the changelog entry whose frontmatter `branch:` equals `branch`.
+ * Returns the matching entry's path, or null if none matches.
+ */
+export declare function findEntryByBranch(branch: string, changelogDirectory?: string): null | string;
+//# sourceMappingURL=changelog.d.ts.map

package/dist/lib/changelog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"changelog.d.ts","sourceRoot":"","sources":["../../src/lib/changelog.ts"],"names":[],"mappings":"AAYA;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,EACd,kBAAkB,SAAwB,GACzC,IAAI,GAAG,MAAM,CAqCf"}

package/dist/lib/changelog.js

@@ -0,0 +1,47 @@
+// Shared helpers for locating changelog entries on disk.
+//
+// `findEntryByBranch` is the one entry-lookup rule the enrichment scripts share,
+// so the rule can't drift between callers — the same reasoning that produced
+// derive-packages.ts.
+import { parseFrontmatter } from "./frontmatter.js";
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+const DEFAULT_CHANGELOG_DIR = "changelog";
+/**
+ * Find the changelog entry whose frontmatter `branch:` equals `branch`.
+ * Returns the matching entry's path, or null if none matches.
+ */
+export function findEntryByBranch(branch, changelogDirectory = DEFAULT_CHANGELOG_DIR) {
+    let names;
+    try {
+        names = readdirSync(changelogDirectory);
+    }
+    catch (error) {
+        // A repo with no `changelog/` directory yet means "no entry found", not a
+        // crash — callers (e.g. set-affected-packages) already handle null.
+        const nodeError = error;
+        if (nodeError.code === "ENOENT") {
+            return null;
+        }
+        throw error;
+    }
+    const files = names
+        .filter((name) => name.endsWith(".md") && name !== "README.md")
+        .map((name) => join(changelogDirectory, name));
+    for (const entryPath of files) {
+        let data;
+        try {
+            ({ data } = parseFrontmatter(readFileSync(entryPath, "utf8")));
+        }
+        catch (error) {
+            // Rethrow with the offending file named — the raw parser error carries no
+            // filename, so a malformed entry anywhere in the corpus is hard to locate.
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`Failed to parse changelog frontmatter in ${entryPath}: ${message}`);
+        }
+        if (data?.branch === branch) {
+            return entryPath;
+        }
+    }
+    return null;
+}

package/dist/lib/cli-entry.d.ts

@@ -0,0 +1,10 @@
+/**
+ * True when the calling module is the process entry point — i.e. it was run as a
+ * CLI, not imported (e.g. by unit tests exercising its pure helpers).
+ *
+ * Pass the caller's `import.meta.filename`. Both sides are resolved with
+ * `realpathSync` so a symlinked entry point (macOS `/var`→`/private/var`, pnpm's
+ * store) isn't a false negative that skips `main()`.
+ */
+export declare function isCliEntry(moduleFilename: string): boolean;
+//# sourceMappingURL=cli-entry.d.ts.map

package/dist/lib/cli-entry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-entry.d.ts","sourceRoot":"","sources":["../../src/lib/cli-entry.ts"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAW1D"}

package/dist/lib/cli-entry.js

@@ -0,0 +1,22 @@
+import { realpathSync } from "node:fs";
+import { argv } from "node:process";
+/**
+ * True when the calling module is the process entry point — i.e. it was run as a
+ * CLI, not imported (e.g. by unit tests exercising its pure helpers).
+ *
+ * Pass the caller's `import.meta.filename`. Both sides are resolved with
+ * `realpathSync` so a symlinked entry point (macOS `/var`→`/private/var`, pnpm's
+ * store) isn't a false negative that skips `main()`.
+ */
+export function isCliEntry(moduleFilename) {
+    const entry = argv[1];
+    if (!entry) {
+        return false;
+    }
+    try {
+        return realpathSync(moduleFilename) === realpathSync(entry);
+    }
+    catch {
+        return false;
+    }
+}

package/dist/lib/commit-count.d.ts

@@ -0,0 +1,16 @@
+export type Runner = (cmd: string, args: readonly string[]) => string;
+/**
+ * Default Runner backed by `execFileSync` — shared by finalise and
+ * backfill-commits so the timeout / stdio options can't drift.
+ */
+export declare function realRunner(cmd: string, args: readonly string[]): string;
+/**
+ * Count a merged PR's commits, excluding merge commits (more than one parent).
+ * Returns the non-merge commit count as a string, or null when the response
+ * isn't an array. Throws (rather than returning null) if the gh output isn't
+ * valid JSON — a network/auth failure must surface to the caller, not be
+ * silently recorded as a count; both callers own that (finalise's resolver and
+ * backfill's main() each wrap the call).
+ */
+export declare function nonMergeCommitCount(run: Runner, prNumber: number | string): null | string;
+//# sourceMappingURL=commit-count.d.ts.map

package/dist/lib/commit-count.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commit-count.d.ts","sourceRoot":"","sources":["../../src/lib/commit-count.ts"],"names":[],"mappings":"AA0BA,MAAM,MAAM,MAAM,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,KAAK,MAAM,CAAC;AAEtE;;;GAGG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CASvE;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,GAAG,MAAM,GACxB,IAAI,GAAG,MAAM,CA2Bf"}

package/dist/lib/commit-count.js

@@ -0,0 +1,72 @@
+// Resolve a merged PR's commit count EXCLUDING merge commits, via the GitHub
+// REST commits endpoint. Shared by finalise (release-time enrichment) and
+// backfill-commits (the one-off backlog backfill) — A-560.
+//
+// Works for both squash and merge-commit trunk strategies (A-825):
+//
+// - **Squash:** the per-commit count is lost from local trunk history (the PR
+//   lands as a single-parent squash SHA), but the PR commits endpoint still
+//   returns the original branch commits post-merge, so the count stays
+//   recoverable.
+// - **Merge commits on trunk:** branch history is preserved on `main`; the same
+//   PR commits endpoint still yields the authored (non-merge) count. Excluding
+//   commits with more than one parent also drops the merge commit itself and
+//   any `main`-merge upkeep commits on the branch.
+//
+// In both cases the REST commit object's `parents` array is the reliable signal
+// (`gh pr view --json commits` omits parent data).
+//
+// Runner-injectable `(cmd, args) -> stdout`, mirroring finalise's makeResolver,
+// so it's unit-testable with a fake runner and never reaches the network in
+// tests. `gh api --paginate` substitutes `{owner}`/`{repo}` from the repo's
+// remote and merges the paged arrays, so PRs with more than one page of commits
+// still count correctly.
+import { execFileSync } from "node:child_process";
+/**
+ * Default Runner backed by `execFileSync` — shared by finalise and
+ * backfill-commits so the timeout / stdio options can't drift.
+ */
+export function realRunner(cmd, args) {
+    return execFileSync(cmd, args, {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "inherit"],
+        // Fail fast if gh/git stalls (network/auth). Enrichment is best-effort, so
+        // a timeout throws → callers' try/catch falls back rather than hanging the
+        // release until the whole job times out.
+        timeout: 30_000,
+    });
+}
+/**
+ * Count a merged PR's commits, excluding merge commits (more than one parent).
+ * Returns the non-merge commit count as a string, or null when the response
+ * isn't an array. Throws (rather than returning null) if the gh output isn't
+ * valid JSON — a network/auth failure must surface to the caller, not be
+ * silently recorded as a count; both callers own that (finalise's resolver and
+ * backfill's main() each wrap the call).
+ */
+export function nonMergeCommitCount(run, prNumber) {
+    const json = run("gh", [
+        "api",
+        "--paginate",
+        `repos/{owner}/{repo}/pulls/${prNumber}/commits`,
+    ]);
+    const commits = JSON.parse(json);
+    if (!Array.isArray(commits)) {
+        return null;
+    }
+    // Exclude only commits we can positively identify as merges (>1 parent). The
+    // REST commits endpoint always includes `parents`, so a missing/malformed
+    // `parents` is anomalous — treat it as 0 parents (a normal commit) so we err
+    // toward counting authored work rather than silently dropping it; a real merge
+    // always arrives with its two parents present.
+    const count = commits.filter((commit) => {
+        const parents = commit !== null &&
+            typeof commit === "object" &&
+            "parents" in commit &&
+            Array.isArray(commit.parents)
+            ? commit.parents
+            : [];
+        return parents.length <= 1;
+    }).length;
+    return String(count);
+}

package/dist/lib/config.d.ts

@@ -0,0 +1,25 @@
+export type ChangelogConfig = {
+    affectedPackages: boolean;
+    baseBranch: string;
+    changelogDir: string;
+    fallbackPackage: string;
+    issueKeys: string[];
+    linearWorkspaceSlug: string;
+    packageRoots: string[];
+};
+/**
+ * Validate a raw config JSON string and merge it over the structural defaults.
+ * Exported so the fail-loud contract is unit-testable without filesystem setup.
+ */
+export declare function parseConfig(raw: string, source?: string): ChangelogConfig;
+/**
+ * Load and cache the changelog config from the consumer cwd (or an explicit path).
+ */
+export declare function loadConfig(options?: {
+    configPath?: string;
+}): ChangelogConfig;
+/**
+ * Clear the cached config — for tests that swap config between cases.
+ */
+export declare function resetConfigCache(): void;
+//# sourceMappingURL=config.d.ts.map

package/dist/lib/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/lib/config.ts"],"names":[],"mappings":"AAuBA,MAAM,MAAM,eAAe,GAAG;IAC5B,gBAAgB,EAAE,OAAO,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB,CAAC;AAgCF;;;GAGG;AACH,wBAAgB,WAAW,CACzB,GAAG,EAAE,MAAM,EACX,MAAM,SAAgB,GACrB,eAAe,CAkEjB;AAqCD;;GAEG;AACH,wBAAgB,UAAU,CAAC,OAAO,CAAC,EAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,eAAe,CAsB7E;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,IAAI,CAEvC"}