@rheged-studio/changelog-core 1.1.1

package/dist/lib/config.js

@@ -0,0 +1,156 @@
+// Load the consumer's changelog config.json (issue-ID prefixes, Linear workspace
+// slug, base branch, changelog directory, monorepo package mapping).
+//
+// Resolved from the consumer cwd (or an explicit path) — NOT relative to this
+// package's install location. Order:
+//   1. options.configPath
+//   2. process.env.CHANGELOG_CONFIG
+//   3. <cwd>/.claude/skills/changelog/config.json
+//   4. <cwd>/.agents/skills/changelog/config.json
+//   5. <cwd>/config.json (committed repo-root config — stopgap until agent-skills
+//      #122 / Linear follow-up makes skill config.json reliably available in CI)
+//
+// Zero-deps: a plain JSON read. Identity values (`issueKeys`,
+// `linearWorkspaceSlug`) have NO default — a foreign repo that silently inherited
+// ACME's keys/slug would emit wrong issue links and detection, so a missing
+// config or a missing identity key FAILS LOUDLY. Structural conventions
+// (`baseBranch`, `changelogDir`, `packageRoots`, `fallbackPackage`) keep generic,
+// non-ACME defaults a consumer can override; a present-but-mistyped one also fails
+// loudly rather than surfacing as a non-actionable crash downstream.
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+// Generic, non-ACME structural defaults. Applied only when the key is absent;
+// every one is overridable in config.json. Mirrored in derive-packages.ts so
+// that function can run standalone — keep the two in sync.
+const DEFAULTS = {
+    // `affected_packages` only earns its keep in a genuine monorepo. Default it
+    // off so single-package repos get clean entries; monorepo consumers (and
+    // initialise-skills, when it detects a workspace config) flip it on.
+    affectedPackages: false,
+    baseBranch: "main",
+    changelogDir: "changelog",
+    fallbackPackage: "infrastructure",
+    packageRoots: ["apps", "packages", "services"],
+};
+let cached;
+function fail(message, source) {
+    throw new Error(`changelog config: ${message} Set it in ${source} (commit a root config.json, or run initialise-skills for the skill-local copy).`);
+}
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every(isNonEmptyString);
+}
+/**
+ * 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 function parseConfig(raw, source = "config.json") {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`Invalid JSON in ${source}: ${message}`);
+        throw error;
+    }
+    // JSON.parse can return null/array/primitive; the field checks below would then
+    // throw a raw TypeError instead of the actionable config error this surfaces.
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        fail("config.json must contain a JSON object.", source);
+    }
+    const record = parsed;
+    // Required identity values — no default; fail loudly so a consuming repo can't
+    // silently ship ACME's issue keys or workspace slug.
+    if (!Array.isArray(record.issueKeys) ||
+        record.issueKeys.length === 0 ||
+        !record.issueKeys.every(isNonEmptyString)) {
+        fail("`issueKeys` must be a non-empty array of strings.", source);
+    }
+    if (!isNonEmptyString(record.linearWorkspaceSlug)) {
+        fail("`linearWorkspaceSlug` must be a non-empty string.", source);
+    }
+    // Structural keys are optional, but a present value of the wrong type would
+    // otherwise crash later (e.g. `packageRoots.map`) with a non-actionable error.
+    if ("baseBranch" in record && !isNonEmptyString(record.baseBranch)) {
+        fail("`baseBranch`, when set, must be a non-empty string.", source);
+    }
+    if ("changelogDir" in record && !isNonEmptyString(record.changelogDir)) {
+        fail("`changelogDir`, when set, must be a non-empty string.", source);
+    }
+    if ("packageRoots" in record && !isStringArray(record.packageRoots)) {
+        fail("`packageRoots`, when set, must be an array of strings.", source);
+    }
+    if ("fallbackPackage" in record &&
+        !isNonEmptyString(record.fallbackPackage)) {
+        fail("`fallbackPackage`, when set, must be a non-empty string.", source);
+    }
+    if ("affectedPackages" in record &&
+        typeof record.affectedPackages !== "boolean") {
+        fail("`affectedPackages`, when set, must be a boolean.", source);
+    }
+    return {
+        ...DEFAULTS,
+        ...record,
+        issueKeys: record.issueKeys,
+        linearWorkspaceSlug: record.linearWorkspaceSlug,
+    };
+}
+function resolveConfigPath(options) {
+    if (options?.configPath) {
+        return options.configPath;
+    }
+    const fromEnvironment = process.env.CHANGELOG_CONFIG?.trim();
+    if (fromEnvironment) {
+        return fromEnvironment;
+    }
+    const cwd = process.cwd();
+    const claudePath = join(cwd, ".claude/skills/changelog/config.json");
+    if (existsSync(claudePath)) {
+        return claudePath;
+    }
+    const agentsPath = join(cwd, ".agents/skills/changelog/config.json");
+    if (existsSync(agentsPath)) {
+        return agentsPath;
+    }
+    // Last resort: committed repo-root config.json. Skill-local config.json is
+    // gitignored under the agent-skills generated-config model, so CI / fresh
+    // clones need a tracked path until that gap is fixed (A-812).
+    const rootPath = join(cwd, "config.json");
+    if (existsSync(rootPath)) {
+        return rootPath;
+    }
+    return fail("config.json not found.", `${claudePath}, ${agentsPath}, or ${rootPath}`);
+}
+/**
+ * Load and cache the changelog config from the consumer cwd (or an explicit path).
+ */
+export function loadConfig(options) {
+    // An explicit path always reloads; otherwise return the cached value so
+    // repeated callers (and the CLI's env-based --config) share one parse.
+    if (cached !== undefined && options?.configPath === undefined) {
+        return cached;
+    }
+    const configPath = resolveConfigPath(options);
+    let raw;
+    try {
+        raw = readFileSync(configPath, "utf8");
+    }
+    catch (error) {
+        const nodeError = error;
+        if (nodeError.code === "ENOENT") {
+            fail("config.json not found.", configPath);
+        }
+        throw error;
+    }
+    cached = parseConfig(raw, configPath);
+    return cached;
+}
+/**
+ * Clear the cached config — for tests that swap config between cases.
+ */
+export function resetConfigCache() {
+    cached = undefined;
+}

package/dist/lib/derive-packages.d.ts

@@ -0,0 +1,10 @@
+export type DerivePackagesOptions = {
+    changelogDir?: string;
+    fallbackPackage?: string;
+    packageRoots?: string[];
+};
+/**
+ * Map changed repo-relative paths to sorted, de-duplicated package names.
+ */
+export declare function derivePackagesFromPaths(paths: string[], options?: DerivePackagesOptions): string[];
+//# sourceMappingURL=derive-packages.d.ts.map

package/dist/lib/derive-packages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"derive-packages.d.ts","sourceRoot":"","sources":["../../src/lib/derive-packages.ts"],"names":[],"mappings":"AAoBA,MAAM,MAAM,qBAAqB,GAAG;IAClC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB,CAAC;AAEF;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,MAAM,EAAE,EACf,OAAO,GAAE,qBAA0B,GAClC,MAAM,EAAE,CA+BV"}

package/dist/lib/derive-packages.js

@@ -0,0 +1,42 @@
+// Map a set of changed repo-relative paths to the workspace packages they touch.
+//
+// Used by the merge-time path (set-affected-packages, computed from the branch
+// diff). Kept as one implementation so the `affected_packages` value can't drift
+// if a post-merge counterpart reuses the same rule.
+//
+// The rule (a conventional monorepo path→package mapping, all config-driven):
+//   <root>/<x>/...    -> <x>   for each root in `packageRoots`
+//   everything else   -> `fallbackPackage`
+// The changelog directory itself is skipped — it's touched by every entry and
+// would otherwise pin `fallbackPackage` onto every package list.
+import { escapeRegex } from "./vendor/issue-keys.js";
+// Mirror config.ts's DEFAULTS so this function works standalone (e.g. in unit
+// tests) without loading config; keep the two in sync if the defaults change.
+const DEFAULT_PACKAGE_ROOTS = ["apps", "packages", "services"];
+const DEFAULT_FALLBACK_PACKAGE = "infrastructure";
+const DEFAULT_CHANGELOG_DIR = "changelog";
+/**
+ * Map changed repo-relative paths to sorted, de-duplicated package names.
+ */
+export function derivePackagesFromPaths(paths, options = {}) {
+    const { changelogDir: changelogDirectory = DEFAULT_CHANGELOG_DIR, fallbackPackage = DEFAULT_FALLBACK_PACKAGE, packageRoots = DEFAULT_PACKAGE_ROOTS, } = options;
+    // `<root>/<x>/` → captures `<x>`, for any configured root.
+    const rootRe = packageRoots.length > 0
+        ? new RegExp(`^(?:${packageRoots.map(escapeRegex).join("|")})/([^/]+)/`)
+        : null;
+    // Normalise a trailing slash so `changelogDir: "changelog/"` still skips.
+    const skipPrefix = `${changelogDirectory.replace(/\/+$/, "")}/`;
+    const out = new Set();
+    for (const changedPath of paths) {
+        const path = changedPath.trim();
+        if (!path) {
+            continue;
+        }
+        if (path.startsWith(skipPrefix)) {
+            continue;
+        }
+        const match = rootRe ? rootRe.exec(path) : null;
+        out.add(match ? match[1] : fallbackPackage);
+    }
+    return [...out].toSorted();
+}

package/dist/lib/enrich.d.ts

@@ -0,0 +1,29 @@
+export type EnrichInput = {
+    additions?: null | string;
+    /**
+     * Feature branch name — the stable lookup key.
+     */
+    branch: string;
+    changedFiles?: null | string;
+    /**
+     * Non-merge commit count as a string, or null.
+     */
+    commits?: null | string;
+    deletions?: null | string;
+    /**
+     * PR merged_at timestamp (ISO 8601 UTC).
+     */
+    mergedAt: string;
+    /**
+     * Merge commit SHA (full or short); only the first 7 chars are stored.
+     */
+    mergeSha: string;
+    prNumber?: null | string;
+};
+/**
+ * Apply enrichment to a single entry's raw markdown and return the rewritten
+ * markdown. Fill-once for merged_at/commit/pr; authoritative overwrite for
+ * stats. created_at is never touched.
+ */
+export declare function enrichFrontmatter(raw: string, input: EnrichInput): string;
+//# sourceMappingURL=enrich.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"enrich.d.ts","sourceRoot":"","sources":["../../src/lib/enrich.ts"],"names":[],"mappings":"AAYA,MAAM,MAAM,WAAW,GAAG;IACxB,SAAS,CAAC,EAAE,IAAI,GAAG,MAAM,CAAC;IAC1B;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,IAAI,GAAG,MAAM,CAAC;IAC7B;;OAEG;IACH,OAAO,CAAC,EAAE,IAAI,GAAG,MAAM,CAAC;IACxB,SAAS,CAAC,EAAE,IAAI,GAAG,MAAM,CAAC;IAC1B;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,IAAI,GAAG,MAAM,CAAC;CAC1B,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,GAAG,MAAM,CAkDzE"}

package/dist/lib/enrich.js

@@ -0,0 +1,54 @@
+// Pure enrichment of a changelog entry's frontmatter — fills the fields that
+// are only knowable once the PR has merged (merged_at / commit / pr) plus
+// authoritative stats. `version` is filled separately by lib/stamp.
+// created_at is never touched.
+//
+// This is a library module (no CLI): the release-time orchestrator finalise
+// composes it with the PR data it resolves from `gh`. Kept pure so it's
+// trivially unit-testable. Zero-dep — uses the package's frontmatter parser.
+import { blank } from "./blank.js";
+import { parseFrontmatter, stringifyFrontmatter } from "./frontmatter.js";
+/**
+ * Apply enrichment to a single entry's raw markdown and return the rewritten
+ * markdown. Fill-once for merged_at/commit/pr; authoritative overwrite for
+ * stats. created_at is never touched.
+ */
+export function enrichFrontmatter(raw, input) {
+    const parsed = parseFrontmatter(raw);
+    const fm = { ...parsed.data };
+    if (!fm.created_at) {
+        throw new Error("entry has no created_at; refusing to enrich");
+    }
+    const shortSha = input.mergeSha.slice(0, 7);
+    if (blank(fm.merged_at)) {
+        fm.merged_at = input.mergedAt;
+    }
+    if (blank(fm.commit)) {
+        fm.commit = shortSha;
+    }
+    if (blank(fm.pr) && input.prNumber) {
+        fm.pr = Number.parseInt(input.prNumber, 10);
+    }
+    // Authoritative overwrites from the GH API, always under stats: { ... }.
+    const stats = typeof fm.stats === "object" &&
+        fm.stats !== null &&
+        !Array.isArray(fm.stats)
+        ? { ...fm.stats }
+        : {};
+    // Guard with blank() (not just null/undefined): an empty string would slip
+    // through and Number.parseInt("", 10) is NaN, which the validator rejects.
+    if (!blank(input.additions)) {
+        stats.loc_added = Number.parseInt(input.additions, 10);
+    }
+    if (!blank(input.deletions)) {
+        stats.loc_removed = Number.parseInt(input.deletions, 10);
+    }
+    if (!blank(input.changedFiles)) {
+        stats.files_changed = Number.parseInt(input.changedFiles, 10);
+    }
+    if (!blank(input.commits)) {
+        stats.commits = Number.parseInt(input.commits, 10);
+    }
+    fm.stats = stats;
+    return stringifyFrontmatter(parsed.content, fm);
+}

package/dist/lib/frontmatter.d.ts

@@ -0,0 +1,11 @@
+export type FrontmatterValue = boolean | FrontmatterValue[] | null | number | string | {
+    [key: string]: FrontmatterValue;
+};
+export type FrontmatterData = Record<string, FrontmatterValue>;
+export type ParsedFrontmatter = {
+    content: string;
+    data: FrontmatterData;
+};
+export declare function parseFrontmatter(raw: string): ParsedFrontmatter;
+export declare function stringifyFrontmatter(content: string, data: FrontmatterData): string;
+//# sourceMappingURL=frontmatter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"frontmatter.d.ts","sourceRoot":"","sources":["../../src/lib/frontmatter.ts"],"names":[],"mappings":"AAkBA,MAAM,MAAM,gBAAgB,GACxB,OAAO,GACP,gBAAgB,EAAE,GAClB,IAAI,GACJ,MAAM,GACN,MAAM,GACN;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,gBAAgB,CAAA;CAAE,CAAC;AAExC,MAAM,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;AAE/D,MAAM,MAAM,iBAAiB,GAAG;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,eAAe,CAAC;CACvB,CAAC;AA0PF,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,iBAAiB,CAU/D;AA+ID,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,eAAe,GACpB,MAAM,CAOR"}

package/dist/lib/frontmatter.js

@@ -0,0 +1,355 @@
+// Zero-deps YAML-frontmatter parser/serialiser for the changelog corpus.
+//
+// Carries no third-party npm import so it can be lifted wholesale into this
+// package. It is NOT a general YAML implementation — it handles exactly the
+// subset the changelog frontmatter uses:
+//
+//   - plain / single- / double-quoted string scalars
+//   - integers, booleans, the `null` literal, and bare `key:` (-> null)
+//   - one folded/literal block scalar (`>-` `>` `|` `|-`) for `release_note`
+//   - inline arrays (`[]`, `["a", b]`) and block arrays (`- item`)
+//   - one level of nested mapping (`stats:`)
+//
+// API mirrors gray-matter's so call sites change minimally:
+//   parseFrontmatter(raw)            -> { data, content }
+//   stringifyFrontmatter(content, d) -> "---\n<yaml>\n---\n<content>"
+const FENCE = "---";
+// --- parsing ---------------------------------------------------------------
+function indentOf(line) {
+    return line.length - line.trimStart().length;
+}
+// Parse a scalar token (the text after `key:` or an array item).
+function parseScalar(token) {
+    const text = token.trim();
+    if (text === "" || text === "null" || text === "~") {
+        return null;
+    }
+    if (text === "true") {
+        return true;
+    }
+    if (text === "false") {
+        return false;
+    }
+    if (/^-?\d+$/.test(text)) {
+        return Number.parseInt(text, 10);
+    }
+    if (text.startsWith("'") && text.endsWith("'") && text.length >= 2) {
+        return text.slice(1, -1).replaceAll("''", "'");
+    }
+    if (text.startsWith('"') && text.endsWith('"') && text.length >= 2) {
+        // Unescape in a single left-to-right pass so an escaped backslash (`\\`)
+        // can't have its trailing char re-consumed by a later rule (e.g. `\\n`
+        // must become `\n`, not a newline).
+        return text
+            .slice(1, -1)
+            .replaceAll(/\\(.)/g, (_, char) => (char === "n" ? "\n" : char));
+    }
+    return text;
+}
+// Split an inline-array body on top-level commas only — commas inside single-
+// or double-quoted strings are preserved (e.g. `"Smith, Jr. <a@b>"` stays one
+// item). Mirrors parseScalar's quoting: `''` is an escaped quote inside single
+// quotes, `\` escapes inside double quotes.
+function splitInlineItems(inner) {
+    const items = [];
+    let current = "";
+    let quote = null;
+    for (let index = 0; index < inner.length; index++) {
+        const ch = inner[index];
+        if (quote === '"') {
+            current += ch;
+            if (ch === "\\" && index + 1 < inner.length) {
+                current += inner[++index];
+            }
+            else if (ch === '"') {
+                quote = null;
+            }
+        }
+        else if (quote === "'") {
+            current += ch;
+            if (ch === "'") {
+                if (inner[index + 1] === "'") {
+                    current += inner[++index];
+                }
+                else {
+                    quote = null;
+                }
+            }
+        }
+        else if (ch === '"' || ch === "'") {
+            quote = ch;
+            current += ch;
+        }
+        else if (ch === ",") {
+            items.push(current);
+            current = "";
+        }
+        else {
+            current += ch;
+        }
+    }
+    // A non-null `quote` here means the closing quote was never seen — the array
+    // body ended mid-string. Pushing `current` would fold the dangling opening
+    // quote into the parsed value; fail loudly instead.
+    if (quote !== null) {
+        throw new Error(`Unterminated quoted item in inline array: ${inner}`);
+    }
+    items.push(current);
+    return items;
+}
+// Parse an inline array body (the text between the surrounding brackets).
+function parseInlineArray(body) {
+    const inner = body.trim();
+    if (inner === "") {
+        return [];
+    }
+    return splitInlineItems(inner).map((item) => parseScalar(item));
+}
+// Collect an indented block following a `key:` / block-scalar header, returning
+// the consumed lines (those more indented than `parentIndent`) and the next index.
+function collectBlock(lines, start, parentIndent) {
+    const block = [];
+    let index = start;
+    while (index < lines.length) {
+        const line = lines[index];
+        if (line.trim() === "") {
+            block.push(line);
+            index++;
+            continue;
+        }
+        if (indentOf(line) <= parentIndent) {
+            break;
+        }
+        block.push(line);
+        index++;
+    }
+    // Drop trailing blank lines that belong to the gap before the next key.
+    while (block.length > 0 && block.at(-1).trim() === "") {
+        block.pop();
+    }
+    return { block, next: index };
+}
+// Fold/keep a block scalar per its indicator (`>` folds newlines to spaces,
+// `|` keeps them; a trailing `-` strips the final newline, which we always do
+// here since the corpus only ever uses `>-`).
+function parseBlockScalar(indicator, block) {
+    // An empty block — or one whose lines are all whitespace — has no content to
+    // dedent. `Math.min(...[])` is `Infinity`, which would slice every line down
+    // to "" and silently collapse the block, so treat both cases as empty.
+    const nonBlank = block.filter((line) => line.trim() !== "");
+    if (nonBlank.length === 0) {
+        return "";
+    }
+    const minIndent = Math.min(...nonBlank.map((line) => indentOf(line)));
+    const dedented = block.map((line) => line.slice(minIndent));
+    const folded = indicator.startsWith(">");
+    return folded
+        ? dedented.join(" ").replaceAll(/\s+/g, " ").trim()
+        : dedented.join("\n");
+}
+function parseMapping(lines, startIndent) {
+    const data = {};
+    let index = 0;
+    while (index < lines.length) {
+        const line = lines[index];
+        if (line.trim() === "") {
+            index++;
+            continue;
+        }
+        const colon = line.indexOf(":");
+        if (colon === -1) {
+            // No `:` means malformed input (or a mis-routed block-array item). Fail
+            // loudly: silently slicing on colon === -1 mangles the key/value and
+            // produces a confusing downstream validation error instead.
+            throw new Error(`Invalid frontmatter line (expected "key: value"): ${line}`);
+        }
+        const key = line.slice(indentOf(line), colon).trim();
+        const rest = line.slice(colon + 1).trim();
+        index++;
+        if (rest === "" ||
+            rest === ">" ||
+            rest === ">-" ||
+            rest === "|" ||
+            rest === "|-") {
+            const { block, next } = collectBlock(lines, index, startIndent);
+            index = next;
+            if (rest === "") {
+                // Could be a block array, a nested mapping, or a bare null.
+                if (block.length === 0) {
+                    data[key] = null;
+                }
+                else {
+                    // Decide array-vs-mapping from the first *non-blank* line: collectBlock
+                    // preserves a blank line between `key:` and the first `- item`, so
+                    // keying off `block[0]` would misroute such a block into parseMapping()
+                    // and throw on the `- item` lines.
+                    const firstContent = block.find((blockLine) => blockLine.trim() !== "");
+                    if (firstContent?.trimStart().startsWith("- ") ||
+                        firstContent?.trim() === "-") {
+                        // Drop interior blank lines before mapping: a block array with blank
+                        // lines between items would otherwise yield spurious `null` entries
+                        // (each blank line parses as the empty scalar -> `null`).
+                        data[key] = block
+                            .filter((blockLine) => blockLine.trim() !== "")
+                            .map((blockLine) => parseScalar(blockLine.trimStart().replace(/^-\s?/, "")));
+                    }
+                    else {
+                        const childIndent = indentOf(firstContent ?? block[0]);
+                        data[key] = parseMapping(block, childIndent);
+                    }
+                }
+            }
+            else {
+                data[key] = parseBlockScalar(rest, block);
+            }
+            continue;
+        }
+        if (rest.startsWith("[") && rest.endsWith("]")) {
+            data[key] = parseInlineArray(rest.slice(1, -1));
+            continue;
+        }
+        // Inline empty mapping. The serialiser emits `{}` for an empty object (the
+        // symmetric counterpart of `[]` for an empty array); a non-empty mapping is
+        // always written in block form, so `{}` is the only inline object to parse.
+        // Without this, `stats: {}` would fall through to parseScalar and parse back
+        // as the literal string "{}", silently corrupting an empty stats object.
+        if (rest === "{}") {
+            data[key] = {};
+            continue;
+        }
+        data[key] = parseScalar(rest);
+    }
+    return data;
+}
+// Matches a leading `---` fence, the frontmatter body (group 1, non-greedy up to
+// the first closing fence on its own line), the closing fence, and its trailing
+// newline. `content` is the exact remainder, so the markdown body is preserved
+// byte-for-byte and round-trips are idempotent — only the frontmatter is rewritten.
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---[ \t]*\r?\n?/;
+export function parseFrontmatter(raw) {
+    const text = raw.startsWith("\uFEFF") ? raw.slice(1) : raw;
+    const match = FRONTMATTER_RE.exec(text);
+    if (!match) {
+        return { content: text, data: {} };
+    }
+    const fmLines = match[1].split("\n");
+    const content = text.slice(match[0].length);
+    return { content, data: parseMapping(fmLines, 0) };
+}
+// --- serialising -----------------------------------------------------------
+const INDICATORS = new Set([
+    "!",
+    '"',
+    "#",
+    "%",
+    "&",
+    "'",
+    "*",
+    ",",
+    "-",
+    ":",
+    ">",
+    "?",
+    "@",
+    "[",
+    "]",
+    "`",
+    "{",
+    "|",
+    "}",
+]);
+function reparsesAsNonString(string_) {
+    // True when an unquoted emit of this string would parse back as something
+    // other than a string (bool/int/null) or as a date-shaped token worth quoting.
+    if (string_ === "" ||
+        string_ === "null" ||
+        string_ === "~" ||
+        string_ === "true" ||
+        string_ === "false") {
+        return true;
+    }
+    if (/^-?\d+$/.test(string_)) {
+        return true;
+    }
+    return /^\d{4}-\d{2}-\d{2}/.test(string_);
+}
+function needsQuoting(string_) {
+    if (string_.length === 0) {
+        return true;
+    }
+    if (string_ !== string_.trim()) {
+        return true;
+    }
+    if (INDICATORS.has(string_[0]) || string_.startsWith("- ")) {
+        return true;
+    }
+    if (string_.includes(": ") ||
+        string_.includes(" #") ||
+        string_.includes("\n")) {
+        return true;
+    }
+    return reparsesAsNonString(string_);
+}
+function serialiseString(string_) {
+    if (!needsQuoting(string_)) {
+        return string_;
+    }
+    // Prefer double quotes (Prettier's YAML default) so enrich/finalise rewrites
+    // don't turn authored `created_at: "…"` into single-quoted scalars that fail
+    // consumer `prettier --check` (A-1308).
+    const escaped = string_
+        .replaceAll("\\", "\\\\")
+        .replaceAll('"', '\\"')
+        .replaceAll("\n", "\\n");
+    return `"${escaped}"`;
+}
+function serialiseScalar(value) {
+    if (value === null || value === undefined) {
+        return "";
+    }
+    if (typeof value === "boolean") {
+        return value ? "true" : "false";
+    }
+    if (typeof value === "number") {
+        return String(value);
+    }
+    return serialiseString(String(value));
+}
+function serialiseValue(key, value, lines) {
+    if (Array.isArray(value)) {
+        if (value.length === 0) {
+            lines.push(`${key}: []`);
+            return;
+        }
+        lines.push(`${key}:`);
+        for (const item of value) {
+            lines.push(`  - ${serialiseScalar(item)}`);
+        }
+        return;
+    }
+    if (value !== null && typeof value === "object") {
+        const childEntries = Object.entries(value);
+        // Emit `{}` for an empty mapping so it round-trips as an object, mirroring
+        // `[]` for an empty array. A bare `key:` would re-parse as null, silently
+        // turning an empty `stats: {}` into `stats: null`.
+        if (childEntries.length === 0) {
+            lines.push(`${key}: {}`);
+            return;
+        }
+        lines.push(`${key}:`);
+        for (const [childKey, childValue] of childEntries) {
+            const child = serialiseScalar(childValue);
+            lines.push(child === "" ? `  ${childKey}:` : `  ${childKey}: ${child}`);
+        }
+        return;
+    }
+    const emitted = serialiseScalar(value);
+    lines.push(emitted === "" ? `${key}:` : `${key}: ${emitted}`);
+}
+export function stringifyFrontmatter(content, data) {
+    const lines = [];
+    for (const [key, value] of Object.entries(data)) {
+        serialiseValue(key, value, lines);
+    }
+    return `${FENCE}\n${lines.join("\n")}\n${FENCE}\n${content}`;
+}