@rheged-studio/changelog-core 1.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Rob Easthope
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,92 @@
+# @acme-skunkworks/changelog-core
+
+Shared **changelog contract** and dual-runtime **CLI** for Rheged Studio —
+validate, enrich, and finalise dated `changelog/` entries from CI **and** local
+dev. One package replaces the triplicated skill `.mjs` + per-repo
+`infrastructure/scripts` copies.
+
+Zero runtime dependencies (Node built-ins only). Node 22+.
+
+## Install
+
+```bash
+pnpm add -D @acme-skunkworks/changelog-core
+```
+
+## Config
+
+Commands resolve config from the **consumer repo** (not the package install
+path), in order:
+
+1. `--config <path>` (CLI)
+2. `CHANGELOG_CONFIG` env
+3. `.claude/skills/changelog/config.json`
+4. `.agents/skills/changelog/config.json`
+5. `config.json` (committed repo-root — stopgap while skill `config.json` stays
+   gitignored; see [A-812](https://linear.app/rheged-studio/issue/A-812))
+
+Required identity keys: `issueKeys`, `linearWorkspaceSlug`. Structural keys
+(`baseBranch`, `changelogDir`, `packageRoots`, `fallbackPackage`,
+`affectedPackages`) have safe defaults.
+
+## CLI
+
+```bash
+npx changelog-core [--config <path>] <subcommand> [args…]
+npx changelog-core --version
+```
+
+| Subcommand              | Purpose                                                           |
+| ----------------------- | ----------------------------------------------------------------- |
+| `validate`              | Schema-check every dated entry under `changelog/`                 |
+| `enrich`                | Fill post-merge fields for one entry (env-driven; deploy targets) |
+| `finalise`              | Release-time enrich + version stamp (npm targets)                 |
+| `set-affected-packages` | Write `affected_packages` from the branch diff (monorepos)        |
+| `add-links`             | Rewrite bare Linear IDs in bodies to links                        |
+| `backfill-commits`      | One-off backfill of `stats.commits`                               |
+| `check-completeness`    | Gate a release-triggering PR title on a changelog entry           |
+
+Local scripts in this repo:
+
+```bash
+pnpm validate:changelog
+pnpm changelog:enrich
+pnpm changelog:finalise
+```
+
+## Contract
+
+The frontmatter schema and field-ownership rules live in
+[`changelog-contract.md`](changelog-contract.md) (also importable as
+`@acme-skunkworks/changelog-core/contract`).
+
+`merge_strategy` is **not** part of the contract (A-802). Existing entries that
+still carry the key validate fine — unknown keys are ignored.
+
+## Library
+
+```ts
+import {
+  validateEntry,
+  enrichFrontmatter,
+  parseFrontmatter,
+  loadConfig,
+} from "@acme-skunkworks/changelog-core";
+```
+
+See `src/index.ts` for the full public surface (frontmatter, config, enrich,
+stamp, derive-packages, completeness helpers, …).
+
+## Development
+
+```bash
+pnpm install
+pnpm run build
+pnpm test
+pnpm lint
+pnpm tsc
+```
+
+## Licence
+
+MIT

package/changelog-contract.md

@@ -0,0 +1,129 @@
+# Changelog entry contract
+
+The full frontmatter schema and field-ownership rules the changelog tooling
+enforces. The `validate` command is the executable form of this contract.
+
+## Frontmatter schema
+
+Preserve this field order. When `affectedPackages: true`, emit
+`affected_packages: []` as a placeholder — enrichment fills it in place.
+Single-package repos omit the field entirely.
+
+```yaml
+---
+title: "Concise summary"
+release_note: "One-sentence user-facing summary"
+created_at: "2026-04-26T13:24:00Z"
+merged_at:
+branch: "<current-branch>"
+pr:
+commit:
+author: "you@example.com"
+co_authors: []
+category: feature
+breaking: false
+issues: ["A-123"]
+affected_packages: []
+stats:
+  files_changed:
+  loc_added:
+  loc_removed:
+  commits:
+---
+```
+
+## Required fields
+
+`validate` requires exactly four fields: `title`, `created_at`, `category`, and
+`breaking`. Every other field — including `branch`, `author`, `co_authors`, and
+`stats` — is validated **by type when present** but may be omitted or left as a
+blank placeholder until enrichment.
+
+## Field types and rules
+
+| Field                                                 | Rule                                                                                                                                                                 |
+| ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `title`                                               | Non-empty string.                                                                                                                                                    |
+| `release_note`                                        | String or `null`/blank when present.                                                                                                                                 |
+| `created_at`                                          | ISO 8601 UTC with `Z` suffix, quoted. **Set once; never overwritten.**                                                                                               |
+| `merged_at`                                           | ISO 8601 UTC with `Z` suffix when set; blank until release.                                                                                                          |
+| `branch`                                              | Non-empty string — the stable lookup key for enrichment.                                                                                                             |
+| `pr`                                                  | Integer when set; blank until post-merge enrichment resolves it from the merged PR.                                                                                  |
+| `commit`                                              | 7-char hex SHA when set; blank until merge.                                                                                                                          |
+| `author`                                              | Non-empty string (an email).                                                                                                                                         |
+| `co_authors`                                          | Array of strings (`[]` when none).                                                                                                                                   |
+| `category`                                            | One of `feature`, `fix`, `chore`, `docs`, `refactor`, `perf`.                                                                                                        |
+| `breaking`                                            | Boolean. If `true`, the body MUST contain a `## Breaking` section.                                                                                                   |
+| `issues`                                              | Array of strings, each matching `[A-Z]+-\d+` (a one-or-more-letter team key, e.g. `A-123`).                                                                          |
+| `affected_packages`                                   | Array of strings (`[]` when unpopulated). Monorepo-gated — emitted only when `affectedPackages: true` in `config.json`; absent (and clean) for single-package repos. |
+| `stats.{files_changed,loc_added,loc_removed,commits}` | Non-negative integers when set; blank until release. `commits` counts the PR's branch commits **excluding merge commits**, filled by post-merge enrichment.          |
+
+The filename must match `YYYYMMDD-HHMMSS-<slug>.md` (slug `[a-z0-9-]+`), and the
+body must contain at least one of `## Breaking` / `## Added` / `## Changed` /
+`## Fixed`.
+
+## Field ownership boundaries
+
+Three owners, never overlapping:
+
+1. **The author (the changelog skill / ship flow).** `title`, `release_note`,
+   `category`, `breaking`, `issues`, `co_authors`, `author`. Re-derived on every
+   run.
+2. **The enrichment scripts (deterministic, pre-merge).** `affected_packages` —
+   when `affectedPackages: true`, `set-affected-packages` always overwrites it
+   from the latest branch diff, so it tracks added commits; when `false` (the
+   single-package default) the field is never emitted and the script is a no-op.
+   `add-links` rewrites bare issue IDs in the body to Linear links.
+3. **The release-orchestrator (post-merge, privileged).** `merged_at`, `commit`,
+   `pr`, and authoritative `stats`, plus the published `version` where a consumer
+   adds one. Emit these as blank placeholders; never hand-edit them — so an
+   in-flight PR never shows numbers that drift as commits land. `pr` is resolved
+   from the merged PR by the entry's `branch:` (the same branch-resolution
+   finalise/enrich use for the other post-merge fields) — the ship flow never
+   writes it. npm targets fill these at release time (`finalise`); deploy
+   targets, never checked out during the release flow, fill them afterwards from
+   the enrichment cron (`enrich`, minus `version` and `commits` — the cron
+   passes no commit count, so `stats.commits` is left to the release-time path).
+
+`branch` is set by the author at create time and is the stable lookup key for
+enrichment.
+
+`created_at` is **sacred**: set once at create time, preserved verbatim on every
+update. The release step refuses to finalise an entry without it.
+
+## Body structure
+
+```markdown
+## Breaking <!-- only when breaking: true -->
+
+- Description and migration steps
+
+## Added
+
+- Description
+
+## Changed
+
+- ...
+
+## Fixed
+
+- ...
+```
+
+Only include `Added` / `Changed` / `Fixed` headings that have entries.
+
+## Notes for adopters
+
+- **Single-package repos** leave `affectedPackages: false` (the `config.json`
+  default), which omits `affected_packages` and makes `set-affected-packages` a
+  no-op — there is only one package, so the field is write-only noise. The
+  validator treats `affected_packages` as optional-when-present, so leaving it out
+  is fine. As shipped, `validate` requires only `title`, `created_at`,
+  `category`, and `breaking`; `branch`, `author`, `co_authors`, and `stats` are
+  validated by type when present but are not required.
+- **Adding a `version` field.** A single-versioned package may add `version` to
+  record the release each entry shipped in; that is owned by the release step,
+  alongside the other post-merge fields.
+- The `issueKeys`, `linearWorkspaceSlug`, and `baseBranch` knobs in `config.json`
+  are the only repo-specific inputs; everything else in the contract is generic.

package/config.json

@@ -0,0 +1,9 @@
+{
+  "issueKeys": ["A"],
+  "linearWorkspaceSlug": "rheged-studio",
+  "baseBranch": "main",
+  "changelogDir": "changelog",
+  "packageRoots": ["apps", "packages", "services"],
+  "fallbackPackage": "infrastructure",
+  "affectedPackages": false
+}

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+// Bin entry for @acme-skunkworks/changelog-core — parse the subcommand and
+// dispatch to the matching command main. Global `--config <path>` (before or
+// after the subcommand) is mapped to CHANGELOG_CONFIG so loadConfig() picks it
+// up without each command re-parsing the flag.
+import { main as addLinksMain } from "./commands/add-links.js";
+import { main as backfillCommitsMain } from "./commands/backfill-commits.js";
+import { main as checkCompletenessMain } from "./commands/check-completeness.js";
+import { main as enrichMain } from "./commands/enrich.js";
+import { main as finaliseMain } from "./commands/finalise.js";
+import { main as setAffectedPackagesMain } from "./commands/set-affected-packages.js";
+import { main as validateMain } from "./commands/validate.js";
+import { createRequire } from "node:module";
+import { argv, exit } from "node:process";
+const { version: PACKAGE_VERSION } = createRequire(import.meta.url)("../package.json");
+const SUBCOMMANDS = [
+    "validate",
+    "enrich",
+    "finalise",
+    "set-affected-packages",
+    "add-links",
+    "backfill-commits",
+    "check-completeness",
+];
+const DISPATCH = {
+    "add-links": addLinksMain,
+    "backfill-commits": backfillCommitsMain,
+    "check-completeness": checkCompletenessMain,
+    enrich: enrichMain,
+    finalise: finaliseMain,
+    "set-affected-packages": setAffectedPackagesMain,
+    validate: validateMain,
+};
+const USAGE = `changelog-core — dated changelog tooling (validate, enrich, finalise, …)
+
+Usage:
+  changelog-core [--config <path>] <subcommand> [args…]
+
+Subcommands:
+  validate                 Validate dated changelog/ entries against the contract
+  enrich                   Fill post-merge fields of one entry (env-driven)
+  finalise                 Release-time enrich + version-stamp
+  set-affected-packages    Write affected_packages from the branch diff
+  add-links                Rewrite bare Linear IDs in bodies to links
+  backfill-commits         One-off backfill of stats.commits
+  check-completeness       Gate a release-triggering PR on a changelog entry
+
+Global options:
+  --config <path>          Path to config.json (also via CHANGELOG_CONFIG)
+  --help, -h               Show this message
+  --version, -V            Print the package version`;
+function extractConfig(args) {
+    const rest = [];
+    let configPath;
+    for (let index = 0; index < args.length; index++) {
+        const argument = args[index];
+        if (argument === "--config") {
+            const next = args[++index];
+            if (!next || next.startsWith("-")) {
+                console.error("changelog-core: --config requires a path argument");
+                exit(2);
+            }
+            configPath = next;
+        }
+        else if (argument.startsWith("--config=")) {
+            const value = argument.slice("--config=".length);
+            if (!value) {
+                console.error("changelog-core: --config requires a path argument");
+                exit(2);
+            }
+            configPath = value;
+        }
+        else {
+            rest.push(argument);
+        }
+    }
+    return { configPath, rest };
+}
+function isSubcommand(value) {
+    return SUBCOMMANDS.includes(value);
+}
+function main() {
+    const { configPath, rest } = extractConfig(argv.slice(2));
+    if (rest.length === 0 || rest[0] === "--help" || rest[0] === "-h") {
+        console.log(USAGE);
+        return;
+    }
+    if (rest[0] === "--version" || rest[0] === "-V") {
+        console.log(PACKAGE_VERSION);
+        return;
+    }
+    const subcommand = rest[0];
+    if (!isSubcommand(subcommand)) {
+        console.error(`changelog-core: unknown subcommand '${subcommand}'\n`);
+        console.error(USAGE);
+        exit(2);
+    }
+    if (configPath) {
+        process.env.CHANGELOG_CONFIG = configPath;
+    }
+    // Leave the subcommand (and any remaining flags) on argv so command mains that
+    // scan argv.slice(2) for --help / --self-test / --check still see them. The
+    // subcommand name itself is ignored by those scanners.
+    DISPATCH[subcommand]();
+}
+main();

package/dist/commands/add-links.d.ts

@@ -0,0 +1,8 @@
+export declare function rewriteBody(body: string): string;
+export declare function splitFrontmatter(raw: string): {
+    body: string;
+    fm: string;
+};
+export declare function frontmatterBranch(raw: string): null | string;
+export declare function main(): void;
+//# sourceMappingURL=add-links.d.ts.map

package/dist/commands/add-links.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"add-links.d.ts","sourceRoot":"","sources":["../../src/commands/add-links.ts"],"names":[],"mappings":"AA6BA,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CA8ChD;AAED,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAU1E;AAKD,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAS5D;AAmHD,wBAAgB,IAAI,IAAI,IAAI,CA6E3B"}

package/dist/commands/add-links.js

@@ -0,0 +1,258 @@
+import { isCliEntry } from "../lib/cli-entry.js";
+import { loadConfig } from "../lib/config.js";
+import { buildIssueRe } from "../lib/vendor/issue-keys.js";
+import { spawnSync } from "node:child_process";
+import { readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { argv } from "node:process";
+const FENCE_RE = /```[\s\S]*?```/g;
+const INLINE_CODE_RE = /`[^`]*`/g;
+const ALREADY_LINKED_RE = /\[[^\]]*\]\([^)]*\)/g;
+// Reference-link definition lines — `[A-123]: <url>`, plus any indented
+// continuation lines. The label here is the definition's key, not prose, so
+// masking it stops `ISSUE_RE` rewriting it into `[[A-123](url)]: <url>` and
+// breaking the reference. CommonMark allows up to three leading spaces before
+// the label (four or more would be an indented code block), so allow `{0,3}`.
+// Must run before `REFERENCE_LINKED_RE` so a definition is never partially
+// consumed as an in-text label.
+const REFERENCE_DEFINITION_RE = /^ {0,3}\[[^\]]+\]:[^\n]*(?:\n[ \t][^\n]*)*/gm;
+// Reference-style links — `[text][ref]` and the collapsed `[text][]` — also
+// already point at a definition, so mask them too. Without this, `ISSUE_RE`
+// rewrites inside the label (`[A-1][1]` -> `[[A-1](url)][1]`) and re-runs
+// compound the corruption.
+const REFERENCE_LINKED_RE = /\[[^\]]*\]\[[^\]]*\]/g;
+function buildUrl(workspace, id) {
+    return `https://linear.app/${workspace}/issue/${id}`;
+}
+export function rewriteBody(body) {
+    // Lazy config load so `--config` / CHANGELOG_CONFIG set by the CLI dispatcher
+    // (or tests via resetConfigCache) take effect before the first rewrite.
+    const { issueKeys: teamKeys, linearWorkspaceSlug: workspace } = loadConfig();
+    const issueRe = buildIssueRe(teamKeys);
+    if (!issueRe) {
+        return body;
+    }
+    // Mask fenced/inline code and existing links so issue-like text inside them
+    // isn't linkified. Tokens are delimited with NUL bytes, which cannot occur in
+    // a UTF-8 text file, so a token can never collide with real prose on restore
+    // (the previous bare `FENCE0`/`INLINE1`/`LINK2` tokens could).
+    const masks = [];
+    function mask(match) {
+        masks.push(match);
+        return `\u0000CR_MASK_${masks.length - 1}\u0000`;
+    }
+    const masked = body
+        .replaceAll(FENCE_RE, mask)
+        .replaceAll(INLINE_CODE_RE, mask)
+        .replaceAll(ALREADY_LINKED_RE, mask)
+        .replaceAll(REFERENCE_DEFINITION_RE, mask)
+        .replaceAll(REFERENCE_LINKED_RE, mask)
+        .replace(issueRe, (id) => `[${id}](${buildUrl(workspace, id)})`);
+    // Unmask is reentrant. Masks can nest: inline code inside a Markdown link —
+    // `` [`code`](url) `` — has the inner inline-code span masked first, then the
+    // whole `[<token>](url)` masked again, so the outer mask's stored value still
+    // contains the inner token. A single replace pass restores the outer token but
+    // leaves that inner `\0…\0` token embedded, so literal NUL bytes survive into
+    // the file (the entry becomes a binary blob). Restore to a fixed point instead.
+    // Each token is stored before any token that embeds it, so every pass strictly
+    // reduces the highest remaining index and the loop terminates.
+    let unmasked = masked;
+    let previous;
+    do {
+        previous = unmasked;
+        unmasked = unmasked.replaceAll(/\0CR_MASK_(\d+)\0/g, (_, index) => masks[Number(index)]);
+    } while (unmasked !== previous);
+    return unmasked;
+}
+export function splitFrontmatter(raw) {
+    // Match the opening/closing `---` fences with either LF or CRLF endings so a
+    // file authored on Windows isn't treated as having no frontmatter (which
+    // would let `rewriteBody` rewrite the frontmatter region too).
+    const match = raw.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n/);
+    if (!match) {
+        return { body: raw, fm: "" };
+    }
+    return { body: raw.slice(match[0].length), fm: match[0] };
+}
+// The `branch:` value from a changelog entry's frontmatter (quotes stripped), or
+// `null` when the entry has no frontmatter or no `branch:` field. Used to scope
+// the default write pass to the entry(ies) authored on the current branch.
+export function frontmatterBranch(raw) {
+    const { fm } = splitFrontmatter(raw);
+    const match = fm.match(/^branch:(.*)$/m);
+    if (!match) {
+        return null;
+    }
+    const value = match[1].trim().replaceAll(/^['"]|['"]$/g, "");
+    return value || null;
+}
+// The current git branch, or `null` when git is unavailable or HEAD is detached
+// — callers fall back to the full-directory sweep in that case.
+function currentGitBranch() {
+    try {
+        const result = spawnSync("git", ["rev-parse", "--abbrev-ref", "HEAD"], {
+            encoding: "utf8",
+        });
+        if (result.status !== 0) {
+            return null;
+        }
+        const branch = result.stdout.trim();
+        return branch && branch !== "HEAD" ? branch : null;
+    }
+    catch {
+        return null;
+    }
+}
+const USAGE = `add-links — rewrite bare Linear issue IDs in changelog bodies to Linear URLs
+
+Usage:
+  changelog-core add-links                 Linkify the current branch's entry/entries (writes)
+  changelog-core add-links --all           Linkify every changelog/<ts>-<slug>.md body (writes)
+  changelog-core add-links --check         Report which files would change across ALL entries; write nothing
+  changelog-core add-links --dry-run       Alias for --check
+  changelog-core add-links --self-test     Run the built-in offline smoke test
+  changelog-core add-links --help          Show this message (alias: -h)
+
+By default the write pass is scoped to the entry(ies) whose \`branch:\` frontmatter
+matches the current git branch, so authoring a new entry never rewrites unrelated,
+already-merged entries (A-603). Use --all for the historical full-directory sweep.
+When git is unavailable the default falls back to the full sweep.
+
+--check always scans every entry (it's a completeness gate) and exits 1 when a
+rewrite is needed, 0 when nothing would change.`;
+// Offline smoke test for the pure rewriteBody: linkify a sample body and check
+// the masking rules (fenced/inline code and existing links are left alone).
+function selfTest() {
+    const cases = [];
+    // Masking invariants hold whatever the config: an already-linked ID and an
+    // inline-code ID must survive a rewrite untouched.
+    const alreadyLinked = "See [A-1](https://example.test/A-1) for context.";
+    cases.push({
+        name: "an already-linked issue ID is left untouched",
+        ok: rewriteBody(alreadyLinked) === alreadyLinked,
+    });
+    const inlineCode = "The token `A-1` is code, not a link.";
+    cases.push({
+        name: "an issue ID inside inline code is not linkified",
+        ok: rewriteBody(inlineCode) === inlineCode,
+    });
+    const fenced = "```\nA-1 in a fence\n```";
+    cases.push({
+        name: "an issue ID inside a code fence is not linkified",
+        ok: rewriteBody(fenced) === fenced,
+    });
+    // Inline code nested inside a Markdown link masks twice (inner span, then the
+    // whole link). The reentrant unmask must restore both so no NUL token survives.
+    const codeInLink = "See [`A-1`](https://example.test/A-1) for the helper.";
+    const codeInLinkOut = rewriteBody(codeInLink);
+    cases.push({
+        name: "inline code nested inside a link round-trips with no NUL bytes",
+        ok: codeInLinkOut === codeInLink && !codeInLinkOut.includes("\u0000"),
+    });
+    // When the host config has issue keys, a bare ID for the first key linkifies.
+    // Wrap loadConfig so --self-test still passes in a fresh consumer cwd with no
+    // config.json yet (masking cases above already ran).
+    try {
+        const { issueKeys: teamKeys, linearWorkspaceSlug: workspace } = loadConfig();
+        const issueRe = buildIssueRe(teamKeys);
+        if (issueRe && teamKeys.length > 0) {
+            const key = teamKeys[0];
+            const id = `${key}-123`;
+            const before = `Closes ${id}.`;
+            const after = rewriteBody(before);
+            cases.push({
+                name: `a bare ${id} is rewritten to a Linear link`,
+                ok: after === `Closes [${id}](${buildUrl(workspace, id)}).`,
+            });
+        }
+        else {
+            cases.push({
+                name: "no issue keys configured — rewriteBody is a no-op",
+                ok: rewriteBody("Closes A-1.") === "Closes A-1.",
+            });
+        }
+    }
+    catch {
+        cases.push({
+            name: "no config available — masking cases already covered",
+            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;
+    }
+    // --check (alias --dry-run): report which files would be rewritten and write
+    // nothing. Exit 0 when nothing would change, 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 all = args.includes("--all");
+    const { changelogDir } = loadConfig();
+    let stat;
+    try {
+        stat = statSync(changelogDir);
+    }
+    catch {
+        console.error(`changelog directory not found: ${changelogDir}`);
+        process.exit(2);
+    }
+    if (!stat.isDirectory()) {
+        console.error(`${changelogDir} is not a directory`);
+        process.exit(2);
+    }
+    let files = readdirSync(changelogDir)
+        .filter((name) => name.endsWith(".md") && name !== "README.md")
+        .map((name) => join(changelogDir, name));
+    // Default write pass: scope to the entry(ies) authored on the current branch
+    // (matched by `branch:` frontmatter), so linkifying a new entry never churns
+    // unrelated, already-merged entries (A-603). `--all` and `--check` keep the
+    // full-directory scan; a non-git context (no branch) also falls back to it.
+    if (!all && !check) {
+        const branch = currentGitBranch();
+        if (branch) {
+            files = files.filter((file) => frontmatterBranch(readFileSync(file, "utf8")) === branch);
+        }
+    }
+    let touched = 0;
+    for (const file of files) {
+        const raw = readFileSync(file, "utf8");
+        const { body, fm } = splitFrontmatter(raw);
+        const next = rewriteBody(body);
+        if (next !== body) {
+            if (!check) {
+                writeFileSync(file, fm + next);
+            }
+            touched++;
+            console.log(check ? `[check] would rewrite: ${file}` : `rewrote: ${file}`);
+        }
+    }
+    if (check) {
+        console.log(`[check] Linear link rewriting: ${touched} file(s) would be updated.`);
+        process.exit(touched > 0 ? 1 : 0);
+    }
+    console.log(`Linear link rewriting complete. ${touched} file(s) updated.`);
+}
+// Only run the filesystem pass when invoked as a CLI, not when imported (e.g.
+// by unit tests exercising `rewriteBody`).
+if (isCliEntry(import.meta.filename)) {
+    main();
+}

package/dist/commands/backfill-commits.d.ts

@@ -0,0 +1,19 @@
+import type { Runner } from "../lib/commit-count.js";
+import type { FrontmatterData } from "../lib/frontmatter.js";
+/**
+ * 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 declare function resolvePrNumber(run: Runner, fm: FrontmatterData): null | number;
+/**
+ * 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 declare function backfillEntry(raw: string, run: Runner): null | string;
+export declare function main(): void;
+//# sourceMappingURL=backfill-commits.d.ts.map

package/dist/commands/backfill-commits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backfill-commits.d.ts","sourceRoot":"","sources":["../../src/commands/backfill-commits.ts"],"names":[],"mappings":"AA8BA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAGrD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAK7D;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,MAAM,EACX,EAAE,EAAE,eAAe,GAClB,IAAI,GAAG,MAAM,CA8Bf;AAsGD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAyBrE;AAaD,wBAAgB,IAAI,IAAI,IAAI,CA+C3B"}