@loomcli/loom 0.0.0 → 0.6.0

package/dist/helpers/release-files.js

@@ -0,0 +1,97 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseAllDocuments } from 'yaml';
+import { z } from 'zod';
+import { headingText, locateRelease, requireClosedBlocks } from './markdown.js';
+import { blankLine } from './release.js';
+import { git, readRegularFile, readRegularFileBytes } from './repository.js';
+function releaseInsertion(changelog, version) {
+    const { body, frontmatter, nodes, releases } = locateRelease(changelog, version);
+    requireClosedBlocks(body, 'CHANGELOG.md');
+    const headings = nodes.filter((node) => node.type === 'heading');
+    if (!headings.some((node) => node.depth === 1)) {
+        throw new Error('CHANGELOG.md requires a title.');
+    }
+    if (headings.some((node) => headingText(node).trim().toLowerCase() === 'unreleased' ||
+        headingText(node).trim().split(/\s/u)[0] === `v${version}`)) {
+        throw new Error('CHANGELOG.md already contains this version or an Unreleased section.');
+    }
+    const offset = releases[0]?.position?.start.offset;
+    const before = offset === undefined ? changelog : changelog.slice(0, frontmatter.length + offset);
+    const after = offset === undefined ? '' : changelog.slice(frontmatter.length + offset);
+    return { after, before: before + blankLine(before) };
+}
+/**
+ * The installed pnpm manifest's path. pnpm is an optional peer dependency, because only lockfile
+ * preparation runs it, so a missing one fails with a sentence instead of a resolve error.
+ */
+function pnpmManifestPath(resolve = (specifier) => import.meta.resolve(specifier)) {
+    try {
+        return fileURLToPath(resolve('pnpm/package.json'));
+    }
+    catch (error) {
+        throw new Error('Preparing pnpm-lock.yaml requires pnpm, an optional peer dependency of @loomcli/loom. Install pnpm 12.3.2 beside @loomcli/loom and run the command again.', { cause: error });
+    }
+}
+function updateLockfile(root) {
+    const lock = join(root, 'pnpm-lock.yaml');
+    if (existsSync(lock)) {
+        for (const document of parseAllDocuments(readRegularFile(root, 'pnpm-lock.yaml'))) {
+            if (document.errors.length > 0) {
+                throw new Error('pnpm-lock.yaml is invalid YAML.');
+            }
+            z.object({ lockfileVersion: z.union([z.string(), z.number()]) }).parse(document.toJS());
+        }
+    }
+    const manifestPath = pnpmManifestPath();
+    const manifestSource = readRegularFile(dirname(manifestPath), 'package.json');
+    const manifest = z
+        .object({ bin: z.object({ pnpm: z.string() }) })
+        .parse(JSON.parse(manifestSource));
+    const result = spawnSync(join(dirname(manifestPath), manifest.bin.pnpm), [
+        'install',
+        '--lockfile-only',
+        '--lockfile-dir',
+        '.',
+        '--offline',
+        '--ignore-scripts',
+        '--ignore-pnpmfile',
+        '--config.frozen-lockfile=false',
+    ], {
+        cwd: root,
+        encoding: 'utf8',
+        timeout: 60_000,
+    });
+    if (result.error) {
+        throw result.error;
+    }
+    if (result.status !== 0) {
+        throw new Error(`Lockfile preparation failed:\n${result.stdout}${result.stderr}`);
+    }
+    return readRegularFile(root, 'pnpm-lock.yaml');
+}
+function versionedManifest(source, version) {
+    const document = z.record(z.string(), z.unknown()).parse(JSON.parse(source));
+    return `${JSON.stringify({ ...document, version }, null, 2)}\n`;
+}
+export function prepareLockfile(root, release, ref) {
+    const stage = mkdtempSync(join(tmpdir(), 'loom-release-'));
+    try {
+        const paths = git(root, ref === undefined ? ['ls-files', '-z'] : ['ls-tree', '-r', '--name-only', '-z', ref]);
+        for (const path of paths.split('\0').filter(Boolean)) {
+            mkdirSync(dirname(join(stage, path)), { recursive: true });
+            writeFileSync(join(stage, path), readRegularFileBytes(root, path, ref));
+        }
+        for (const library of release.libraries) {
+            writeFileSync(join(stage, library.path), versionedManifest(library.source, release.version));
+        }
+        return updateLockfile(stage);
+    }
+    finally {
+        rmSync(stage, { force: true, recursive: true });
+    }
+}
+export { pnpmManifestPath, releaseInsertion, versionedManifest };

package/dist/helpers/release-plan.d.ts

@@ -0,0 +1,39 @@
+import { z } from 'zod';
+import type { HttpPolicy } from './http.js';
+export declare const planSchema: z.ZodObject<{
+    cutCommit: z.ZodString;
+    head: z.ZodString;
+    libraries: z.ZodTuple<[z.ZodObject<{
+        directory: z.ZodString;
+        name: z.ZodString;
+        published: z.ZodBoolean;
+    }, z.core.$strip>], z.ZodObject<{
+        directory: z.ZodString;
+        name: z.ZodString;
+        published: z.ZodBoolean;
+    }, z.core.$strip>>;
+    notes: z.ZodString;
+    provenanceCommit: z.ZodNullable<z.ZodString>;
+    publish: z.ZodBoolean;
+    record: z.ZodBoolean;
+    release: z.ZodObject<{
+        present: z.ZodBoolean;
+    }, z.core.$strip>;
+    tag: z.ZodObject<{
+        commit: z.ZodNullable<z.ZodString>;
+        present: z.ZodBoolean;
+    }, z.core.$strip>;
+    version: z.ZodString;
+}, z.core.$strip>;
+export type ReleasePlan = z.output<typeof planSchema>;
+export interface PlanRequest {
+    githubApi: string;
+    head: string;
+    policy: HttpPolicy;
+    registry: string;
+    repository: string;
+    root: string;
+    token: string | undefined;
+}
+export declare function planRelease(request: PlanRequest): Promise<ReleasePlan>;
+export declare function renderPlan(plan: ReleasePlan): string;

package/dist/helpers/release-plan.js

@@ -0,0 +1,221 @@
+import { z } from 'zod';
+import { isUploadedAsset, readRelease, readTagCommit } from './github.js';
+import { locateRelease } from './markdown.js';
+import { materialBaseline } from './material.js';
+import { readProvenance, readPublished, tarballName } from './registry.js';
+import { currentVersion, git, readLibraries, readRegularFile, requireFullHistory, } from './repository.js';
+const librarySchema = z.object({
+    directory: z.string().min(1),
+    name: z.string().min(1),
+    published: z.boolean(),
+});
+const releaseFactsSchema = z.object({ present: z.boolean() });
+const tagFactsSchema = z.object({ commit: z.string().nullable(), present: z.boolean() });
+// The manifests carry this version until the initial cut, and it is never published, tagged, or released.
+const unreleasedVersion = '0.0.0';
+// A heading, a rule, and raw HTML carry no notes, so a section built only from them says nothing.
+const decorations = new Set(['heading', 'html', 'thematicBreak']);
+// The notes are the body under the version's heading, up to the next release heading.
+function changelogSection(changelog, version) {
+    const { body, index, nodes, releases } = locateRelease(changelog, version);
+    const start = releases[index]?.position?.end.offset;
+    if (start === undefined) {
+        throw new Error(`CHANGELOG.md has no v${version} section.`);
+    }
+    const end = releases[index + 1]?.position?.start.offset ?? body.length;
+    const carries = nodes.some((node) => {
+        const offset = node.position?.start.offset;
+        return offset !== undefined && offset >= start && offset < end && !decorations.has(node.type);
+    });
+    if (!carries) {
+        throw new Error(`CHANGELOG.md: the v${version} section has no notes.`);
+    }
+    return body.slice(start, end).trim();
+}
+// A Release is complete once it carries every expected asset as a finished upload.
+// The exception: a Release that carries none of the expected assets but carries others was recorded by another process, and it is left alone.
+function releaseComplete(assets, expected) {
+    const carriesExpected = expected.some((name) => assets.some((asset) => asset.name === name));
+    if (!carriesExpected && assets.length > 0) {
+        return true;
+    }
+    return expected.every((name) => assets.some((asset) => asset.name === name && isUploadedAsset(asset)));
+}
+function abandon(version, reason) {
+    return new Error(`Version ${version} is absent from the registry and ${reason} Publication attests the head, so ${version} must be abandoned as unpublished and superseded by the next cut.`);
+}
+// Every participating library, named without a registry read, because the unreleased version is never published.
+function unreleasedLibraries(participants) {
+    const [first, ...others] = participants;
+    const libraries = [
+        { directory: first.directory, name: first.manifest.name, published: false },
+    ];
+    for (const other of others) {
+        libraries.push({ directory: other.directory, name: other.manifest.name, published: false });
+    }
+    return libraries;
+}
+// The registry facts of one participating library at the released version.
+async function describeLibrary(registry, participant, version) {
+    const name = participant.manifest.name;
+    const published = await readPublished(registry, name, version);
+    return { directory: participant.directory, name, published: published !== undefined };
+}
+// Every published library attests the same build commit, and that commit is where the tag belongs.
+async function publishedCommit(registry, libraries, version) {
+    let commit = undefined;
+    for (const library of libraries) {
+        const provenance = await readProvenance(registry, library.name, version);
+        if (provenance === undefined) {
+            return undefined;
+        }
+        if (commit !== undefined && provenance.commit !== commit) {
+            throw new Error(`${library.name}@${version} was published from ${provenance.commit}, but an earlier library names ${commit}.`);
+        }
+        commit = provenance.commit;
+    }
+    return commit;
+}
+// A tag anywhere other than the commit the version was published from fails the run, and recording never moves one.
+function requireTagAtPublication(tag, tagCommit, provenanceCommit, version) {
+    if (tagCommit === undefined) {
+        return;
+    }
+    if (provenanceCommit === null) {
+        throw new Error(`Tag ${tag} names ${tagCommit}, but the registry reports no provenance for ${version}, so the commit it was published from is unknown.`);
+    }
+    if (tagCommit !== provenanceCommit) {
+        throw new Error(`Tag ${tag} names ${tagCommit}, but ${version} was published from ${provenanceCommit}; recording never moves a tag.`);
+    }
+}
+// The paths whose bytes can reach a published library build.
+// Publication attests the head commit, so a change to any of them after the cut commit would attest bytes the cut did not produce.
+// Documentation and root Markdown are absent from this set and never refuse a publication.
+const sharedBuildInputs = [
+    'package.json',
+    'pnpm-lock.yaml',
+    'pnpm-workspace.yaml',
+    'scripts/clean.mjs',
+    'tsconfig.json',
+];
+export const planSchema = z
+    .object({
+    cutCommit: z.string().min(1),
+    head: z.string().min(1),
+    // A release participates with at least one library, and the record command reads the first one.
+    libraries: z.tuple([librarySchema], librarySchema),
+    notes: z.string(),
+    provenanceCommit: z.string().min(1).nullable(),
+    publish: z.boolean(),
+    record: z.boolean(),
+    release: releaseFactsSchema,
+    tag: tagFactsSchema,
+    version: z.string().min(1),
+})
+    // The notes are the body of the Release, so only the unreleased version plans without them.
+    .refine((plan) => plan.notes !== '' || plan.version === unreleasedVersion, {
+    error: 'A plan for a released version carries notes.',
+    path: ['notes'],
+});
+export async function planRelease(request) {
+    requireFullHistory(request.root);
+    const head = git(request.root, [
+        'rev-parse',
+        '--verify',
+        '--end-of-options',
+        `${request.head}^{commit}`,
+    ]).trim();
+    const participants = readLibraries(request.root, head);
+    const version = currentVersion(participants).text;
+    const cutCommit = materialBaseline(request.root, participants, version, head);
+    // The unreleased version has no registry record, no changelog section, and nothing to reconcile.
+    if (version === unreleasedVersion) {
+        return {
+            cutCommit,
+            head,
+            libraries: unreleasedLibraries(participants),
+            notes: '',
+            provenanceCommit: null,
+            publish: false,
+            record: false,
+            release: { present: false },
+            tag: { commit: null, present: false },
+            version,
+        };
+    }
+    const changelog = readRegularFile(request.root, 'CHANGELOG.md', head);
+    const notes = changelogSection(changelog, version);
+    const [participant, ...others] = participants;
+    const registry = { policy: request.policy, registry: request.registry };
+    const libraries = [
+        await describeLibrary(registry, participant, version),
+    ];
+    for (const other of others) {
+        libraries.push(await describeLibrary(registry, other, version));
+    }
+    const tag = `v${version}`;
+    const target = {
+        api: request.githubApi,
+        policy: request.policy,
+        repository: request.repository,
+        token: request.token,
+    };
+    const tagCommit = await readTagCommit(target, tag);
+    const release = await readRelease(target, tag);
+    const publish = libraries.some((library) => !library.published);
+    let provenanceCommit = null;
+    if (publish) {
+        const changed = git(request.root, [
+            'diff',
+            '--name-only',
+            '-z',
+            cutCommit,
+            head,
+            '--',
+            ...libraries.map((library) => library.directory),
+            ...sharedBuildInputs,
+        ])
+            .split('\0')
+            .filter(Boolean);
+        if (changed.length > 0) {
+            const paths = changed.join(', ');
+            throw abandon(version, `${paths} changed between the cut commit ${cutCommit} and the head ${head}.`);
+        }
+        if (tagCommit !== undefined && tagCommit !== head) {
+            throw abandon(version, `tag ${tag} already names ${tagCommit} instead of the head ${head}.`);
+        }
+    }
+    else {
+        provenanceCommit = (await publishedCommit(registry, libraries, version)) ?? null;
+        requireTagAtPublication(tag, tagCommit, provenanceCommit, version);
+    }
+    const expected = libraries.map((library) => tarballName(library.name, version));
+    return {
+        cutCommit,
+        head,
+        libraries,
+        notes,
+        provenanceCommit,
+        publish,
+        record: tagCommit === undefined ||
+            release === undefined ||
+            !releaseComplete(release.assets, expected),
+        release: { present: release !== undefined },
+        tag: { commit: tagCommit ?? null, present: tagCommit !== undefined },
+        version,
+    };
+}
+export function renderPlan(plan) {
+    const tag = `v${plan.version}`;
+    if (plan.version === unreleasedVersion) {
+        return `${plan.version} is the unreleased version at head ${plan.head}, so there is nothing to reconcile.\nPublish: no. Record: no.\n`;
+    }
+    const lines = [
+        `Plan ${tag} at head ${plan.head}, cut commit ${plan.cutCommit}.`,
+        ...plan.libraries.map((library) => `${library.name}: ${library.published ? 'published' : 'absent from the registry'}.`),
+        `Tag ${tag}: ${plan.tag.commit === null ? 'absent' : `present at ${plan.tag.commit}`}.`,
+        `Release ${tag}: ${plan.release.present ? 'present' : 'absent'}.`,
+        `Publish: ${plan.publish ? 'yes' : 'no'}. Record: ${plan.record ? 'yes' : 'no'}.`,
+    ];
+    return `${lines.join('\n')}\n`;
+}

package/dist/helpers/release-record.d.ts

@@ -0,0 +1,12 @@
+import type { RetryPolicy } from './http.js';
+import type { ReleasePlan } from './release-plan.js';
+export interface RecordRequest {
+    githubApi: string;
+    plan: ReleasePlan;
+    registry: string;
+    repository: string;
+    retry: RetryPolicy;
+    root: string;
+    token: string;
+}
+export declare function recordRelease(request: RecordRequest): Promise<string>;

package/dist/helpers/release-record.js

@@ -0,0 +1,99 @@
+import { createRelease, createTag, isUploadedAsset, readAssets, readRelease, readTagCommit, removeAsset, uploadAsset, } from './github.js';
+import { readBytes, until } from './http.js';
+import { readProvenance, readPublished, tarballName, verifyIntegrity } from './registry.js';
+import { git } from './repository.js';
+// The bytes, the build commit, and the asset name of one published library.
+async function readUpload(request, library, lines) {
+    const { plan, retry } = request;
+    const registry = { policy: retry, registry: request.registry };
+    const name = library.name;
+    const subject = `${name}@${plan.version}`;
+    const published = await until(retry, `${subject} on the registry`, async () => readPublished(registry, name, plan.version));
+    lines.push(`Read ${subject} from the registry.`);
+    const provenance = await until(retry, `the provenance of ${subject}`, async () => readProvenance(registry, name, plan.version));
+    const source = `git+https://github.com/${request.repository}@refs/heads/main`;
+    if (provenance.uri !== source) {
+        throw new Error(`${subject}: its provenance names ${provenance.uri}, which is not a build of ${source}.`);
+    }
+    const bytes = await until(retry, `the ${subject} tarball`, async () => readBytes(retry, published.tarball));
+    verifyIntegrity(subject, bytes, published.integrity);
+    lines.push(`Verified the ${subject} tarball against ${published.integrity}.`);
+    return { bytes, commit: provenance.commit, name: tarballName(name, plan.version), subject };
+}
+// Provenance attests a commit of this repository, and the checkout proves it is one this branch carries.
+function requireCommitInCheckout(root, commit, subject) {
+    const head = git(root, ['rev-parse', '--verify', '--end-of-options', 'HEAD^{commit}']).trim();
+    if (head === commit) {
+        return;
+    }
+    try {
+        git(root, ['merge-base', '--is-ancestor', commit, head]);
+    }
+    catch {
+        throw new Error(`${subject} was published from ${commit}, which is neither the head ${head} of the checkout nor an ancestor of it.`);
+    }
+}
+// Reconciles the tag, the Release, and its assets with the versions the registry already carries.
+// Every step reads before it writes, and the bytes are verified before the first write.
+export async function recordRelease(request) {
+    const { plan, retry } = request;
+    const version = plan.version;
+    const tag = `v${version}`;
+    const target = {
+        api: request.githubApi,
+        policy: retry,
+        repository: request.repository,
+        token: request.token,
+    };
+    const lines = [];
+    const first = await readUpload(request, plan.libraries[0], lines);
+    const uploads = [first];
+    for (const library of plan.libraries.slice(1)) {
+        const upload = await readUpload(request, library, lines);
+        if (upload.commit !== first.commit) {
+            throw new Error(`${upload.subject} was published from ${upload.commit}, but ${first.subject} was published from ${first.commit}.`);
+        }
+        uploads.push(upload);
+    }
+    const commit = first.commit;
+    requireCommitInCheckout(request.root, commit, tag);
+    const tagged = await readTagCommit(target, tag);
+    if (tagged === undefined) {
+        await createTag(target, tag, commit);
+        await until(retry, `the tag ${tag}`, async () => readTagCommit(target, tag));
+        lines.push(`Created the annotated tag ${tag} at ${commit}.`);
+    }
+    else if (tagged === commit) {
+        lines.push(`Reused the tag ${tag} at ${commit}.`);
+    }
+    else {
+        throw new Error(`Tag ${tag} names ${tagged}, but ${version} was published from ${commit}; recording never moves a tag.`);
+    }
+    const found = await readRelease(target, tag);
+    if (found === undefined) {
+        await createRelease(target, tag, plan.notes);
+    }
+    const release = found ?? (await until(retry, `the ${tag} Release`, async () => readRelease(target, tag)));
+    lines.push(found === undefined ? `Created the ${tag} Release.` : `Reused the ${tag} Release.`);
+    for (const upload of uploads) {
+        const assets = await readAssets(target, release.id);
+        const present = assets.find((asset) => asset.name === upload.name);
+        if (present !== undefined && isUploadedAsset(present)) {
+            lines.push(`Kept the ${upload.name} asset.`);
+        }
+        else {
+            if (present !== undefined) {
+                await removeAsset(target, present.id);
+                lines.push(`Deleted the unfinished ${upload.name} asset.`);
+            }
+            await uploadAsset(target, release.uploadUrl, upload.name, upload.bytes);
+            await until(retry, `the ${upload.name} asset`, async () => {
+                const uploaded = await readAssets(target, release.id);
+                return uploaded.find((asset) => asset.name === upload.name && isUploadedAsset(asset));
+            });
+            lines.push(`Uploaded the ${upload.name} asset.`);
+        }
+    }
+    lines.push(`Recorded ${tag}.`);
+    return `${lines.join('\n')}\n`;
+}

package/dist/helpers/release.d.ts

@@ -0,0 +1,48 @@
+export declare function releaseDate(input: string | undefined): string;
+export declare function prepareRelease(root: string, options: {
+    date: string;
+    initial: boolean;
+    since: string | undefined;
+    narrative: string | undefined;
+}, ref?: string): {
+    fragments: {
+        added: number;
+        body: string;
+        breaking: boolean;
+        name: string;
+    }[];
+    head: string;
+    libraries: [{
+        directory: string;
+        manifest: {
+            [x: string]: unknown;
+            dependencies?: Record<string, string> | undefined;
+            devDependencies?: Record<string, string> | undefined;
+            name: string;
+            optionalDependencies?: Record<string, string> | undefined;
+            peerDependencies?: Record<string, string> | undefined;
+            private?: boolean | undefined;
+            version: string;
+        };
+        path: string;
+        source: string;
+    }, ...{
+        directory: string;
+        manifest: {
+            [x: string]: unknown;
+            dependencies?: Record<string, string> | undefined;
+            devDependencies?: Record<string, string> | undefined;
+            name: string;
+            optionalDependencies?: Record<string, string> | undefined;
+            peerDependencies?: Record<string, string> | undefined;
+            private?: boolean | undefined;
+            version: string;
+        };
+        path: string;
+        source: string;
+    }[]];
+    section: string;
+    version: string;
+};
+export declare function requireReleaseNotes(release: ReturnType<typeof prepareRelease>): void;
+export declare function blankLine(text: string): "" | "\n" | "\n\n";

package/dist/helpers/release.js

@@ -0,0 +1,111 @@
+import { fromMarkdown } from 'mdast-util-from-markdown';
+import { readFragments } from './fragments.js';
+import { requireClosedBlocks } from './markdown.js';
+import { materialBaseline, unchangedLibraries } from './material.js';
+import { currentVersion, git, readLibraries, requireFullHistory } from './repository.js';
+function compareNames(left, right) {
+    if (left < right) {
+        return -1;
+    }
+    if (left > right) {
+        return 1;
+    }
+    return 0;
+}
+export function releaseDate(input) {
+    const date = input ?? new Date().toISOString().slice(0, 10);
+    if (!/^\d{4}-\d{2}-\d{2}$/u.test(date) ||
+        Number.isNaN(Date.parse(date)) ||
+        new Date(date).toISOString().slice(0, 10) !== date) {
+        throw new Error('Expected a calendar date: YYYY-MM-DD.');
+    }
+    return date;
+}
+export function prepareRelease(root, options, ref) {
+    requireFullHistory(root);
+    const head = ref ?? git(root, ['rev-parse', 'HEAD']).trim();
+    const fragments = readFragments(root, ref)
+        .map((fragment) => {
+        const added = git(root, [
+            'log',
+            '--first-parent',
+            '--diff-filter=A',
+            '-1',
+            '--format=%ct',
+            head,
+            '--',
+            `.changes/${fragment.name}`,
+        ]).trim();
+        if (!/^\d+$/u.test(added)) {
+            throw new Error(`.changes/${fragment.name}: commit the fragment before preparing a release.`);
+        }
+        return {
+            added: Number(added),
+            body: fragment.body,
+            breaking: fragment.breaking,
+            name: fragment.name,
+        };
+    })
+        .toSorted((left, right) => left.added - right.added || compareNames(left.name, right.name));
+    const libraries = readLibraries(root, ref);
+    const current = currentVersion(libraries);
+    if (options.initial && current.text !== '0.0.0') {
+        throw new Error('--initial requires library version 0.0.0.');
+    }
+    if (fragments.length === 0 && !options.initial) {
+        throw new Error('No fragments to release.');
+    }
+    const breaking = fragments.filter((fragment) => fragment.breaking);
+    const ordinary = fragments.filter((fragment) => !fragment.breaking);
+    let version = `0.${current.minor}.${current.patch + 1}`;
+    if (breaking.length > 0) {
+        version = `0.${current.minor + 1}.0`;
+    }
+    if (current.text === '0.0.0') {
+        version = '0.1.0';
+    }
+    let section = `## v${version} - ${options.date}\n\n`;
+    if (options.narrative !== undefined) {
+        requireClosedBlocks(options.narrative, 'Narrative');
+        if (!options.narrative.trim() ||
+            fromMarkdown(options.narrative).children.some((node) => node.type === 'heading' && node.depth <= 2)) {
+            throw new Error('Narrative must contain prose without level-one or level-two headings.');
+        }
+        section += options.narrative + blankLine(options.narrative);
+    }
+    for (const [heading, entries] of [
+        ['Breaking Changes', breaking],
+        ['Changes', ordinary],
+    ]) {
+        if (entries.length > 0) {
+            section += `### ${heading}\n\n`;
+            for (const entry of entries) {
+                section += entry.body + blankLine(entry.body);
+            }
+        }
+    }
+    const unchanged = current.text === '0.0.0'
+        ? []
+        : unchangedLibraries(root, libraries, options.since ?? materialBaseline(root, libraries, current.text, head), ref);
+    if (unchanged.length > 0) {
+        section += `No material changes: ${unchanged.join(', ')}.\n\n`;
+    }
+    return { fragments, head, libraries, section, version };
+}
+// A release must carry notes, because the release plan refuses a changelog section that says nothing.
+// Only an initial cut can reach that state: every other cut consumes at least one fragment.
+export function requireReleaseNotes(release) {
+    const body = release.section.slice(release.section.indexOf('\n') + 1);
+    if (body.trim() === '') {
+        throw new Error(`Release v${release.version} carries no entries, so it requires a narrative for its notes.`);
+    }
+}
+export function blankLine(text) {
+    if (text.endsWith('\n\n')) {
+        return '';
+    }
+    if (text.endsWith('\n')) {
+        return '\n';
+    }
+    return '\n\n';
+}