@hugojosefson/cli 0.11.0 → 0.12.0

package/esm/src/features/changelog-feature.js

@@ -0,0 +1,155 @@
+/** Optional changelog lifecycle that preserves existing release history. */
+import { parseSemver } from "../release/semver.js";
+import { changelogHeadings, changelogLines, } from "../release/changelog-markdown.js";
+const id = "changelog";
+const path = "CHANGELOG.md";
+const subject = { kind: "file", identifier: path };
+export const changelogStarter = "# Changelog\n";
+const resolution = "Automatic repair is unsupported. Make CHANGELOG.md a readable regular file, preserving its history, then inspect it again.";
+async function inspect(context) {
+    const file = await context.files.observe(path);
+    if (file.kind !== "file" && file.kind !== "absent") {
+        throw new Error("CHANGELOG.md is not a readable regular file.");
+    }
+    return file;
+}
+async function detect(context) {
+    try {
+        const file = await inspect(context);
+        let observation = "CHANGELOG.md is absent. Enable --changelog to create it with # Changelog.";
+        if (file.kind === "file") {
+            const headings = changelogHeadings(file.content).filter((heading) => heading.level === 2);
+            const releaseText = headings.flatMap((heading, index) => parseSemver(heading.title)
+                ? [file.content.slice(heading.offset, headings[index + 1]?.offset)]
+                : []).join("\n");
+            const content = changelogLines(releaseText).map((line) => line.text).join("\n");
+            const flat = /^[-*] [a-z][a-z0-9-]*(?:\([\w./@ -]+\))?!?: .+/m.test(content);
+            const grouped = /^### (?:BREAKING CHANGE|Features|Fixes|Other)\r?$/m.test(content);
+            observation = flat
+                ? `CHANGELOG.md contains ${grouped ? "mixed flat and grouped" : "flat"} entries. Existing history is preserved. Optional migration preview: hj changelog migrate.`
+                : grouped
+                    ? "CHANGELOG.md contains grouped release sections. Existing history is preserved."
+                    : file.content === changelogStarter
+                        ? "CHANGELOG.md has an empty starter heading, ready for release entries."
+                        : "CHANGELOG.md exists with custom content. Existing history is preserved.";
+        }
+        return {
+            state: file.kind === "file" ? "enabled" : "disabled",
+            evidence: [{
+                    code: "changelog-observed",
+                    kind: id,
+                    subject,
+                    observation,
+                }],
+        };
+    }
+    catch {
+        const issue = {
+            code: "changelog-unreadable",
+            kind: id,
+            subject,
+            observation: "CHANGELOG.md could not be read as a regular file.",
+            resolution,
+        };
+        return { state: "ambiguous", evidence: [issue], issues: [issue] };
+    }
+}
+async function check(context, enabled) {
+    try {
+        const file = await inspect(context);
+        if ((enabled && file.kind === "file") || (!enabled && file.kind === "absent")) {
+            return {
+                result: "no-op",
+                warnings: [],
+                reason: enabled
+                    ? "Existing CHANGELOG.md is preserved."
+                    : "CHANGELOG.md is absent.",
+            };
+        }
+        if (!enabled && file.kind === "file" && file.content !== changelogStarter) {
+            return {
+                result: "blocked",
+                warnings: [],
+                blockers: [{
+                        code: "changelog-history",
+                        subjects: [subject],
+                        message: "CHANGELOG.md contains history or custom content; automatic deletion is unsupported.",
+                        resolution: "Keep the changelog enabled, or archive its contents and remove CHANGELOG.md manually after disabling dependent release publication.",
+                    }],
+            };
+        }
+        return {
+            result: "allowed",
+            warnings: [],
+            preconditions: [{
+                    kind: "file-digest",
+                    path,
+                    digest: file.kind === "file" ? file.digest : undefined,
+                }],
+        };
+    }
+    catch {
+        return {
+            result: "blocked",
+            warnings: [],
+            blockers: [{
+                    code: "changelog-unreadable",
+                    subjects: [subject],
+                    message: "CHANGELOG.md could not be read as a regular file.",
+                    resolution,
+                }],
+        };
+    }
+}
+async function plan(context, enabled, allowed) {
+    const file = await inspect(context);
+    const checked = await check(context, enabled);
+    if (checked.result !== "allowed") {
+        throw new Error("Changelog operation no longer matches its checked state.");
+    }
+    let changes;
+    if (enabled) {
+        changes = [{
+                kind: "write-file",
+                path,
+                content: changelogStarter,
+                expectedDigest: undefined,
+            }];
+    }
+    else {
+        if (file.kind !== "file") {
+            throw new Error("CHANGELOG.md disappeared during planning.");
+        }
+        changes = [{ kind: "remove-file", path, expectedDigest: file.digest }];
+    }
+    return {
+        featureId: id,
+        action: enabled ? "enable" : "disable",
+        summary: enabled
+            ? "Create CHANGELOG.md with # Changelog."
+            : "Remove the empty CHANGELOG.md starter.",
+        warnings: allowed.warnings,
+        preconditions: allowed.preconditions,
+        changes,
+        validations: [{
+                kind: "feature-redetection",
+                featureId: id,
+                expected: enabled ? "enabled" : "disabled",
+            }],
+    };
+}
+/** Presence, rather than a required style, defines a valid changelog. */
+export const changelogFeature = {
+    metadata: {
+        id,
+        name: "Changelog",
+        summary: "Keep release history, with optional migration from flat entries to grouped sections.",
+    },
+    dependencies: { requires: [] },
+    capabilities: { provides: [], requires: [] },
+    detect,
+    checkEnable: (context) => check(context, true),
+    checkDisable: (context) => check(context, false),
+    planEnable: (context, allowed) => plan(context, true, allowed),
+    planDisable: (context, allowed) => plan(context, false, allowed),
+};

package/esm/src/features/github-ci-artifacts.js

@@ -2,6 +2,8 @@
 import { legacyCiCheckCompatibility } from "./github-ci-legacy.js";
 import { workflowDenoVersion } from "./workflow-toolchain.js";
 import { hjPackageReference } from "./hj-package.js";
+import { githubCiRuntimeMatrix, githubCiRuntimeMatrixMarker, } from "./github-ci-runtime-matrix.js";
+import { denoCacheInputs } from "./github-workflow-cache.js";
 import { inspectArtifact } from "../artifacts/inspect-artifact.js";
 import { workflowCliArtifact } from "./workflow-cli.js";
 export const githubCiFeatureId = "github-ci";
@@ -18,6 +20,10 @@ on:
 permissions:
   contents: read
 
+concurrency:
+  group: hj-ci-\${{ github.workflow }}-pr-\${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
 jobs:
   check:
     runs-on: ubuntu-latest
@@ -28,7 +34,7 @@ jobs:
       - uses: denoland/setup-deno@22d081ff2d3a40755e97629de92e3bcbfa7cf2ed # v2.0.5
         with:
           deno-version: ${workflowDenoVersion}
-      - run: deno task all
+${denoCacheInputs}      - run: deno task all
   hj-release-commit-validation:
     runs-on: ubuntu-latest
     permissions:
@@ -41,7 +47,7 @@ jobs:
       - uses: denoland/setup-deno@22d081ff2d3a40755e97629de92e3bcbfa7cf2ed # v2.0.5
         with:
           deno-version: ${workflowDenoVersion}
-      - name: Validate release commits
+${denoCacheInputs}      - name: Validate release commits
         env:
           HJ_RELEASE_ROUTE: source-validation
           HJ_SOURCE_BASE_SHA: \${{ github.event.pull_request.base.sha }}
@@ -82,7 +88,7 @@ jobs:
       - uses: denoland/setup-deno@22d081ff2d3a40755e97629de92e3bcbfa7cf2ed # v2.0.5
         with:
           deno-version: ${workflowDenoVersion}
-      - name: Update dependencies
+${denoCacheInputs}      - name: Update dependencies
         env:
           GH_TOKEN: \${{ github.token }}
         run: |
@@ -117,6 +123,14 @@ jobs:
     }];
 /** Render the same exact CI variant for local adoption and remote protection. */
 export function renderGithubCiArtifact(artifact, context, observation) {
+    if (artifact.path === githubCiArtifacts[0].path &&
+        observation.kind === "file" &&
+        observation.content.split("\n").includes(githubCiRuntimeMatrixMarker.trimEnd())) {
+        artifact = {
+            ...artifact,
+            content: githubCiRuntimeMatrix(artifact.content),
+        };
+    }
     const migrated = artifact.path === githubCiArtifacts[0].path &&
         observation.kind === "file" &&
         observation.content.includes("# Retains the git-hj-init required test check.");

package/esm/src/features/github-ci-runtime-matrix.js

@@ -0,0 +1,50 @@
+/** @module Explicit managed CI variant for hj's shared runtime suite. */
+import { nativeNpmCacheStep } from "./github-workflow-cache.js";
+export const githubCiRuntimeMatrixMarker = "# hj-ci-runtime-matrix: deno-node-bun-v1\n";
+/** Retain shared setup and release validation while replacing the check job. */
+export function githubCiRuntimeMatrix(content) {
+    const start = content.indexOf("  check:\n");
+    const end = content.indexOf("  hj-release-commit-validation:\n", start);
+    const setup = content.slice(start, end).split("    steps:\n")[1]
+        .split("      - run: deno task all\n")[0];
+    const upload = (label) => `      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: runtime-report-${label}
+          path: .hj/test-results/${label}.json
+          include-hidden-files: true
+          if-no-files-found: error
+          retention-days: 1
+          overwrite: true
+`;
+    const jobs = `  deno:
+    runs-on: ubuntu-latest
+    steps:
+${setup}      - run: deno task ci-deno
+${upload("deno")}  native:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        runtime: [node24, node26, bun]
+    steps:
+${setup}${nativeNpmCacheStep}      - run: deno run --allow-all scripts/run-test-matrix.ts --runtime \${{ matrix.runtime }}
+${upload("\${{ matrix.runtime }}")}  check:
+    if: \${{ always() }}
+    needs: [deno, native]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Require successful checks and every runtime
+        env:
+          DENO_RESULT: \${{ needs.deno.result }}
+          NATIVE_RESULT: \${{ needs.native.result }}
+        run: test "$DENO_RESULT" = success && test "$NATIVE_RESULT" = success
+${setup}      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          pattern: runtime-report-*
+          path: .hj/test-results
+          merge-multiple: true
+      - name: Compare complete executed inventories
+        run: deno run --allow-read scripts/run-test-matrix.ts --compare-only
+`;
+    return (content.slice(0, start) + jobs + content.slice(end)).replace("name: CI\n", githubCiRuntimeMatrixMarker + "name: CI\n");
+}

package/esm/src/features/github-release-publish-artifacts.js

@@ -1,6 +1,7 @@
 /** @module Exact workflows owned by release-publication features. */
 import { workflowDenoVersion } from "./workflow-toolchain.js";
 import { hjPackageReference } from "./hj-package.js";
+import { denoCacheInputs, nativeNpmCacheStep, } from "./github-workflow-cache.js";
 import { inspectArtifact } from "../artifacts/inspect-artifact.js";
 import { workflowCliArtifact } from "./workflow-cli.js";
 import { publishGithubWorkflow, publishJsrWorkflow, publishNpmWorkflow, publishTagWorkflow, } from "../release/names.js";
@@ -48,7 +49,7 @@ jobs:
       - uses: ${deno}
         with:
           deno-version: ${workflowDenoVersion}
-      - name: Configure Git authentication
+${denoCacheInputs}${nativeNpmCacheStep}      - name: Configure Git authentication
         env:
           GH_TOKEN: \${{ github.token }}
         run: gh auth setup-git
@@ -59,7 +60,7 @@ jobs:
           HJ_RELEASE_TAG: \${{ inputs.tag }}
         run: >-
           deno run --no-lock
-          --allow-env=PATH,GITHUB_OUTPUT,GITHUB_STEP_SUMMARY,HJ_RELEASE_ROUTE,HJ_RELEASE_TAG,ESBUILD_BINARY_PATH,ESBUILD_WORKER_THREADS
+          --allow-env=PATH,GITHUB_REPOSITORY,GITHUB_OUTPUT,GITHUB_STEP_SUMMARY,HJ_RELEASE_ROUTE,HJ_RELEASE_TAG,ESBUILD_BINARY_PATH,ESBUILD_WORKER_THREADS
           --allow-read=.,/tmp/opencode
           --allow-write=deno.json,deno.jsonc,CHANGELOG.md,/tmp/opencode,"\${GITHUB_OUTPUT}","\${GITHUB_STEP_SUMMARY}"
           --allow-run=deno,git
@@ -83,7 +84,7 @@ jobs:
       - uses: ${deno}
         with:
           deno-version: ${workflowDenoVersion}
-      - name: Configure Git authentication
+${denoCacheInputs}      - name: Configure Git authentication
         env:
           GH_TOKEN: \${{ github.token }}
         run: gh auth setup-git
@@ -140,7 +141,7 @@ ${job === "jsr"
       - uses: ${deno}
         with:
           deno-version: ${workflowDenoVersion}
-${job === "npm"
+${denoCacheInputs}${job === "npm"
             ? `      - uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6
         with:
           node-version: "24"

package/esm/src/features/github-release-publish-feature.js

@@ -37,6 +37,10 @@ function releaseFeature(id, name, artifact, requires, options = {}) {
 }
 export const githubReleasePublishTagFeature = releaseFeature(githubReleasePublishTagFeatureId, "GitHub release tag publication", publishTagArtifact, [
     { featureId: "git", reason: "Release publication requires Git." },
+    {
+        featureId: "changelog",
+        reason: "Release publication records changes in CHANGELOG.md.",
+    },
     {
         featureId: "github-repo",
         reason: "Release publication requires GitHub.",

package/esm/src/features/github-workflow-cache.js

@@ -0,0 +1,18 @@
+/** @module Download caches shared by managed CI and release workflows. */
+import { workflowDenoVersion } from "./workflow-toolchain.js";
+// setup-deno adds OS, architecture and job; its fallback also shares across jobs.
+// Package version metadata is deliberately excluded from dependency cache keys.
+export const denoCacheInputs = `          cache: true
+          cache-hash: deno-${workflowDenoVersion}-\${{ hashFiles('**/deno.lock', 'toolchain.json') }}
+`;
+// Frozen npm ci still validates the locks and installs with scripts disabled.
+// Do not cache the build output or node_modules: test preparation clears them.
+export const nativeNpmCacheStep = `      - name: Cache native test npm downloads
+        if: hashFiles('scripts/test-build/dependencies/package-lock.json') != '' && hashFiles('scripts/test-build/tools/package-lock.json') != ''
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        with:
+          path: ~/.npm
+          key: native-test-npm-\${{ runner.os }}-\${{ runner.arch }}-\${{ hashFiles('scripts/test-build/dependencies/package-lock.json', 'scripts/test-build/tools/package-lock.json', 'toolchain.json') }}
+          restore-keys: |
+            native-test-npm-\${{ runner.os }}-\${{ runner.arch }}-
+`;

package/esm/src/features/workflow-deno.js

@@ -22,6 +22,6 @@ export function workflowDenoArtifact(artifact, context, observation) {
     const version = validateDenoVersion(selected);
     return {
         ...artifact,
-        content: artifact.content.replaceAll(`deno-version: ${workflowDenoVersion}\n`, `deno-version: ${version}\n`),
+        content: artifact.content.replaceAll(`deno-version: ${workflowDenoVersion}\n`, `deno-version: ${version}\n`).replaceAll(`cache-hash: deno-${workflowDenoVersion}-`, `cache-hash: deno-${version}-`),
     };
 }

package/esm/src/release/changelog-markdown.js

@@ -0,0 +1,41 @@
+export function changelogLines(text) {
+    const lines = [];
+    let offset = 0;
+    let comment = false;
+    let fence;
+    for (const line of text.split(/(?<=\n)/)) {
+        const value = line.replace(/\r?\n$/, "");
+        const marker = /^ {0,3}(`{3,}|~{3,})(.*)$/.exec(value);
+        if (fence) {
+            if (marker && marker[1][0] === fence.character &&
+                marker[1].length >= fence.length && !marker[2].trim())
+                fence = undefined;
+        }
+        else if (comment || value.replace(/(`+).*?\1/g, "").includes("<!--")) {
+            // Comments can contain example headings and fences; neither is structure.
+            const markers = value.replace(/(`+).*?\1/g, "").match(/<!--|-->/g) ?? [];
+            for (const token of markers) {
+                if (token === "<!--")
+                    comment = true;
+                else
+                    comment = false;
+            }
+        }
+        else if (marker) {
+            fence = { character: marker[1][0], length: marker[1].length };
+        }
+        else if (!/^ {4}|^\t/.test(value)) {
+            lines.push({ text: value, offset });
+        }
+        offset += line.length;
+    }
+    return lines;
+}
+export function changelogHeadings(text) {
+    return changelogLines(text).flatMap((line) => {
+        const heading = /^ {0,3}(#{1,6})[ \t]+(.+?)(?:[ \t]+#+)?[ \t]*$/.exec(line.text);
+        return heading
+            ? [{ title: heading[2], level: heading[1].length, offset: line.offset }]
+            : [];
+    });
+}

package/esm/src/release/changelog.js

@@ -1,7 +1,117 @@
 /** @module Immutable changelog release-section creation and insertion. */
+import { changelogHeadings } from "./changelog-markdown.js";
+import { CommitParser } from "conventional-commits-parser";
+import { writeChangelogString } from "conventional-changelog-writer";
+import { validateConventionalCommits } from "./conventional-commit.js";
+import { parseSemver } from "./semver.js";
+const sections = ["BREAKING CHANGE", "Features", "Fixes", "Other"];
+/** Validates the target used for commit and issue links. */
+export function changelogRepositoryUrl(repository) {
+    const parts = repository.split("/");
+    if (parts.length !== 2 ||
+        parts.some((part) => !/^[A-Za-z0-9_.-]+$/.test(part) || part === "." || part === ".."))
+        throw new TypeError("Changelog requires a GitHub owner/repository.");
+    return `https://github.com/${repository}`;
+}
+/** Groups validated full messages with the pinned Conventional Changelog libraries. */
+export async function createReleaseSection(version, commits, repository) {
+    const repositoryUrl = changelogRepositoryUrl(repository);
+    if (!parseSemver(version) || commits.length === 0 ||
+        commits.some((commit) => !/^[0-9a-f]{40}(?:[0-9a-f]{24})?$/.test(commit.hash))) {
+        throw new TypeError("Release section requires a version and full commit SHAs.");
+    }
+    const validated = validateConventionalCommits(commits.map((commit) => commit.message));
+    const parser = new CommitParser({
+        headerPattern: /^([a-z][a-z0-9-]*)(?:\(([\w./@ -]+)\))?!?: (.+)$/,
+        headerCorrespondence: ["type", "scope", "subject"],
+        noteKeywords: ["BREAKING CHANGE", "BREAKING-CHANGE"],
+    });
+    const parsed = commits.map((commit, index) => {
+        const data = parser.parse(commit.message);
+        const references = [
+            ...data.references,
+            ...data.notes.flatMap((note) => parser.parse(`fix: note\n\n${note.text}`).references),
+        ];
+        const refs = new Map();
+        for (const reference of references) {
+            if (!/^\d+$/.test(reference.issue))
+                continue;
+            const target = reference.repository
+                ? `${reference.owner ?? repository.split("/")[0]}/${reference.repository}`
+                : repository;
+            const label = `${reference.owner ? `${reference.owner}/` : ""}${reference.repository ?? ""}#${reference.issue}`;
+            refs.set(label, `${changelogRepositoryUrl(target)}/issues/${reference.issue}`);
+        }
+        const used = new Set();
+        const subject = linkReferences(data.subject ?? "", refs, used);
+        const notes = data.notes.map((note) => ({
+            ...note,
+            text: linkReferences(note.text, refs, used),
+        }));
+        const extraLinks = [...refs].flatMap(([label, url]) => {
+            if (used.has(url))
+                return [];
+            used.add(url);
+            return [`[${label}](${url})`];
+        });
+        return {
+            ...data,
+            hash: commit.hash,
+            scope: data.scope ?? "",
+            subject,
+            notes,
+            type: validated[index].breaking
+                ? "BREAKING CHANGE"
+                : data.type === "feat"
+                    ? "Features"
+                    : data.type === "fix"
+                        ? "Fixes"
+                        : "Other",
+            links: [
+                `[${commit.hash.slice(0, 7)}](${repositoryUrl}/commit/${commit.hash})`,
+                ...extraLinks,
+            ],
+        };
+    });
+    const text = await writeChangelogString(parsed, { version }, {
+        // Preserve full hashes, every commit type, and the supplied range order.
+        transform: (commit) => commit,
+        ignoreReverted: false,
+        generateOn: () => false,
+        groupBy: "type",
+        commitsSort: (a, b) => compare(a.scope, b.scope),
+        commitGroupsSort: (a, b) => sections.indexOf(a.title) - sections.indexOf(b.title),
+        template: (context) => {
+            let output = `## ${version}\n\n`;
+            for (const group of context.commitGroups ?? []) {
+                output += `### ${group.title}\n\n`;
+                let scope;
+                for (const commit of group.commits) {
+                    if (commit.scope !== scope) {
+                        if (scope !== undefined)
+                            output += "\n";
+                        scope = commit.scope;
+                        if (scope)
+                            output += `#### ${scope}\n\n`;
+                    }
+                    output += `- ${commit.subject} (${commit.links.join(", ")})\n`;
+                    for (const note of commit.notes) {
+                        output += `\n  ${note.text.replaceAll("\n", "\n  ")}\n`;
+                    }
+                }
+                output += "\n";
+            }
+            return output;
+        },
+    });
+    return `${text.trimEnd()}\n\n`;
+}
+function compare(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
 const heading = "# Changelog";
 /** Creates a deterministic release heading and list from validated commit subjects. */
-export function createReleaseSection(version, subjects) {
+export function createLegacyReleaseSection(version, subjects) {
     if (!version || subjects.some((subject) => !subject)) {
         throw new TypeError("Release section requires a version and non-empty subjects.");
     }
@@ -15,12 +125,22 @@ export function createChangelogInsertion(oldText, releaseSection) {
     if (!oldText) {
         return { offset: 0, text: `${heading}\n\n${releaseSection}` };
     }
-    if (!oldText.startsWith(heading) || !/^# Changelog(?:\r?\n|$)/.test(oldText)) {
-        throw new TypeError("Existing changelog must start with # Changelog.");
-    }
-    const section = /\n## [^\n]+(?:\r?\n|$)/.exec(oldText);
-    const offset = section ? section.index + 1 : oldText.length;
-    return { offset, text: releaseSection };
+    const allHeadings = changelogHeadings(oldText);
+    const headings = allHeadings.filter((item) => item.level === 2);
+    const section = headings.find((item) => parseSemver(item.title) || /^\[?unreleased\]?$/i.test(item.title)) ?? headings[0];
+    // Without release headings, insert just after a leading title. Never enter a code block.
+    const titleEnd = allHeadings[0]?.level === 1 && allHeadings[0]?.offset === 0
+        ? /^(?:[^\n]*\n)(?:[ \t]*\r?\n)*/.exec(oldText)?.[0].length ??
+            oldText.length
+        : 0;
+    const offset = section?.offset ?? titleEnd;
+    const prefix = oldText.slice(0, offset);
+    const separator = !prefix || prefix.endsWith("\n\n")
+        ? ""
+        : prefix.endsWith("\n")
+            ? "\n"
+            : "\n\n";
+    return { offset, text: separator + releaseSection };
 }
 /** Applies the recorded insertion and leaves every old byte outside it unchanged. */
 export function applyChangelogInsertion(oldText, insertion) {
@@ -31,3 +151,31 @@ export function applyChangelogInsertion(oldText, insertion) {
     return oldText.slice(0, insertion.offset) + insertion.text +
         oldText.slice(insertion.offset);
 }
+/** Leave existing Markdown links, code and URLs intact while linking plain references. */
+function linkReferences(text, references, used) {
+    return text.replace(/\[[^\]]*\]\([^)]*\)|`[^`]*`|https?:\/\/\S+|(?<![\w/])(?:[\w.-]+(?:\/[\w.-]+)?)?#\d+\b/g, (token) => {
+        const url = references.get(token);
+        if (!url) {
+            for (const target of references.values()) {
+                if (token.endsWith(`](${target})`))
+                    used.add(target);
+            }
+            return token;
+        }
+        used.add(url);
+        return `[${token}](${url})`;
+    });
+}
+/** The original insertion algorithm remains frozen for exact legacy recovery. */
+export function createLegacyChangelogInsertion(oldText, releaseSection) {
+    if (!oldText)
+        return { offset: 0, text: `${heading}\n\n${releaseSection}` };
+    if (!/^# Changelog(?:\r?\n|$)/.test(oldText)) {
+        throw new TypeError("Existing changelog must start with # Changelog.");
+    }
+    const section = /\n## [^\n]+(?:\r?\n|$)/.exec(oldText);
+    return {
+        offset: section ? section.index + 1 : oldText.length,
+        text: releaseSection,
+    };
+}

package/esm/src/release/format-changelog.js

@@ -0,0 +1,15 @@
+/** Format new changelog text without rewriting previous content. */
+import { createChangelogInsertion, } from "./changelog.js";
+import { runOrThrow } from "./release-process.js";
+export async function formatChangelogSection(process, section) {
+    return await runOrThrow(process, "deno", ["fmt", "--ext=md", "-"], {
+        stdin: section,
+    });
+}
+export async function formatChangelogInsertion(process, oldText, section) {
+    const formatted = await formatChangelogSection(process, section);
+    const insertion = createChangelogInsertion(oldText, `${formatted.trimEnd()}\n\n`);
+    return insertion.offset === oldText.length
+        ? { ...insertion, text: `${insertion.text.trimEnd()}\n` }
+        : insertion;
+}