@williamthorsen/release-kit 14.2.2 → 14.2.3

package/dist/esm/buildChangelogEntries.js

@@ -1,23 +1,15 @@
 import { chainError } from '@williamthorsen/toolbelt.errors/candidate';
+import { buildEntryItem, buildTitleItem, } from "./buildChangelogItem.js";
 import { buildEmptyReleaseEntry } from "./buildEmptyReleaseEntry.js";
 import { extractVersion } from "./changelogJsonUtils.js";
 import { classifyChangelogCommit, isNonChangeSubject, isReleaseSubject } from "./classifyChangelogCommit.js";
 import { DEFAULT_BREAKING_POLICIES, DEFAULT_VERSION_PATTERNS, DEFAULT_WORK_TYPES } from "./defaults.js";
 import { determineBumpType } from "./determineBumpType.js";
 import { enumerateReleaseWindows } from "./enumerateReleaseWindows.js";
-import { extractMigration } from "./extractMigration.js";
-import { parseChangeRecordBlock, stripChangeRecordBlocks } from "./parseChangeRecordBlock.js";
-import { evaluateBreakingPolicy, parseSubject, resolveType } from "./parseCommitMessage.js";
+import { parseChangeRecordBlock } from "./parseChangeRecordBlock.js";
 import { stripEmojiPrefix } from "./stripEmojiPrefix.js";
 const UNRELEASED_TAG = 'unreleased';
 const CANONICAL_SECTION_ORDER = new Map(Object.values(DEFAULT_WORK_TYPES).map((config, index) => [stripGroupDecorations(config.header), index]));
-function canonicalSectionPriority(title) {
-    const index = CANONICAL_SECTION_ORDER.get(stripGroupDecorations(title));
-    return index ?? Infinity;
-}
-export function stripGroupDecorations(group) {
-    return stripEmojiPrefix(group);
-}
 export function buildChangelogEntries(config, tag, options) {
     const history = readReleaseHistory(config, options);
     return { entries: toChangelogEntries(history, tag), diagnostics: history.unreleased.diagnostics };
@@ -44,6 +36,9 @@ export function readReleaseHistory(config, options) {
         throw chainError(`Failed to read the release history for ${options.tagPrefixes.join(', ')}`, error);
     }
 }
+export function stripGroupDecorations(group) {
+    return stripEmojiPrefix(group);
+}
 export function toChangelogEntries(history, tag) {
     const { unreleased } = history;
     if (unreleased.sections.length === 0) {
@@ -60,6 +55,72 @@ export function toReleaseEntries(history, tag, today) {
     }
     return toChangelogEntries(history, tag);
 }
+function appendItem(sectionMap, header, item) {
+    let items = sectionMap.get(header);
+    if (items === undefined) {
+        items = [];
+        sectionMap.set(header, items);
+    }
+    items.push(item);
+}
+function buildSections(sectionMap, devOnlySections) {
+    const sections = [];
+    for (const [title, items] of sectionMap) {
+        sections.push({
+            title,
+            audience: devOnlySections.has(stripGroupDecorations(title)) ? 'dev' : 'all',
+            items,
+        });
+    }
+    return sections.toSorted((a, b) => canonicalSectionPriority(a.title) - canonicalSectionPriority(b.title));
+}
+function canonicalSectionPriority(title) {
+    const index = CANONICAL_SECTION_ORDER.get(stripGroupDecorations(title));
+    return index ?? Infinity;
+}
+function formatDate(timestamp) {
+    return new Date(timestamp * 1_000).toISOString().slice(0, 10);
+}
+function readCommit(commit, context, diagnostics) {
+    if (isNonChangeSubject(commit.subject)) {
+        return { items: [], isUnparseable: false };
+    }
+    const reading = parseChangeRecordBlock(commit.message);
+    if (reading.kind === 'malformed') {
+        diagnostics?.malformedBlocks.push({
+            commitHash: commit.hash,
+            commitSubject: commit.subject,
+            reason: reading.reason,
+        });
+    }
+    if (reading.kind === 'read' && reading.entries.length > 0) {
+        const items = reading.entries.flatMap((entry, entryIndex) => buildEntryItem(commit, entry, entryIndex + 1, reading.prNumber, context, diagnostics) ?? []);
+        return { items, isUnparseable: false };
+    }
+    const classification = classifyChangelogCommit(commit, context.workTypes, {
+        breakingPolicies: context.breakingPolicies,
+        ...(diagnostics !== undefined && {
+            onPolicyViolation: (violating, type, surface) => {
+                diagnostics.policyViolations.push({
+                    commitHash: violating.hash,
+                    commitSubject: violating.subject,
+                    type,
+                    surface,
+                });
+            },
+        }),
+    });
+    if (classification.kind !== 'header') {
+        return { items: [], isUnparseable: classification.kind === 'unparseable' && reading.kind !== 'malformed' };
+    }
+    const item = buildTitleItem(commit, classification.breaking, context.workTypes);
+    return {
+        items: [
+            { header: classification.header, item, signal: { type: classification.type, breaking: item.breaking === true } },
+        ],
+        isUnparseable: false,
+    };
+}
 function transformReleases(windows, context) {
     const [unreleasedWindow, baselineWindow] = windows;
     const diagnostics = {
@@ -113,181 +174,3 @@ function transformReleases(windows, context) {
         },
     };
 }
-function readCommit(commit, context, diagnostics) {
-    if (isNonChangeSubject(commit.subject)) {
-        return { items: [], isUnparseable: false };
-    }
-    const reading = parseChangeRecordBlock(commit.message);
-    if (reading.kind === 'malformed') {
-        diagnostics?.malformedBlocks.push({
-            commitHash: commit.hash,
-            commitSubject: commit.subject,
-            reason: reading.reason,
-        });
-    }
-    if (reading.kind === 'read' && reading.entries.length > 0) {
-        const items = reading.entries.flatMap((entry, entryIndex) => buildEntryItem(commit, entry, entryIndex + 1, reading.prNumber, context, diagnostics) ?? []);
-        return { items, isUnparseable: false };
-    }
-    const classification = classifyChangelogCommit(commit, context.workTypes, {
-        breakingPolicies: context.breakingPolicies,
-        ...(diagnostics !== undefined && {
-            onPolicyViolation: (violating, type, surface) => {
-                diagnostics.policyViolations.push({
-                    commitHash: violating.hash,
-                    commitSubject: violating.subject,
-                    type,
-                    surface,
-                });
-            },
-        }),
-    });
-    if (classification.kind !== 'header') {
-        return { items: [], isUnparseable: classification.kind === 'unparseable' && reading.kind !== 'malformed' };
-    }
-    const item = buildTitleItem(commit, classification.breaking, context.workTypes);
-    return {
-        items: [
-            { header: classification.header, item, signal: { type: classification.type, breaking: item.breaking === true } },
-        ],
-        isUnparseable: false,
-    };
-}
-function buildSections(sectionMap, devOnlySections) {
-    const sections = [];
-    for (const [title, items] of sectionMap) {
-        sections.push({
-            title,
-            audience: devOnlySections.has(stripGroupDecorations(title)) ? 'dev' : 'all',
-            items,
-        });
-    }
-    return sections.toSorted((a, b) => canonicalSectionPriority(a.title) - canonicalSectionPriority(b.title));
-}
-function isRoutedTo(scopes, routing) {
-    if (scopes.length === 0) {
-        return true;
-    }
-    return scopes.some((scope) => {
-        const resolved = routing.scopeAliases[scope] ?? scope;
-        return resolved === '*' || resolved === routing.scope;
-    });
-}
-function formatDate(timestamp) {
-    return new Date(timestamp * 1_000).toISOString().slice(0, 10);
-}
-function appendItem(sectionMap, header, item) {
-    let items = sectionMap.get(header);
-    if (items === undefined) {
-        items = [];
-        sectionMap.set(header, items);
-    }
-    items.push(item);
-}
-function buildEntryItem(commit, entry, position, prNumber, context, diagnostics) {
-    const { breakingPolicies, routing, workTypes } = context;
-    if (routing !== undefined && !isRoutedTo(entry.scopes, routing)) {
-        return undefined;
-    }
-    const type = resolveType(entry.type, workTypes);
-    if (type === undefined) {
-        diagnostics?.undeclaredEntryTypes.push({
-            commitHash: commit.hash,
-            commitSubject: commit.subject,
-            entryPosition: position,
-            type: entry.type,
-        });
-        return undefined;
-    }
-    const config = workTypes[type];
-    if (config === undefined || config.excludedFromChangelog === true) {
-        return undefined;
-    }
-    const breaking = evaluateBreakingPolicy({
-        commit: { message: commit.message, subject: commit.subject, hash: commit.hash },
-        resolvedType: type,
-        hasPrefixBreaking: entry.breaking,
-        hasFooterBreaking: false,
-        policy: breakingPolicies[type] ?? 'optional',
-        prefixSurface: 'entry',
-        onPolicyViolation: diagnostics === undefined
-            ? undefined
-            : (violating, violatedType, surface) => {
-                diagnostics.policyViolations.push({
-                    commitHash: violating.hash,
-                    commitSubject: violating.subject,
-                    type: violatedType,
-                    surface,
-                    entryPosition: position,
-                });
-            },
-    });
-    const item = {
-        description: prNumber === undefined ? entry.text : `${entry.text} (#${prNumber})`,
-    };
-    if (breaking) {
-        item.breaking = true;
-    }
-    if (entry.migration !== undefined) {
-        item.migration = entry.migration;
-    }
-    item.hash = commit.hash;
-    item.entry = position;
-    return { header: config.header, item, signal: { type, breaking } };
-}
-function buildTitleItem(commit, isParsedBreaking, workTypes) {
-    const body = extractBody(stripChangeRecordBlocks(commit.message));
-    const item = { description: extractDescription(commit.message) };
-    if (body !== undefined) {
-        item.body = body;
-    }
-    if (isParsedBreaking && subjectHasBreakingMarker(commit.message, workTypes)) {
-        item.breaking = true;
-    }
-    const migration = extractMigration(body);
-    if (migration !== undefined) {
-        item.migration = migration;
-    }
-    item.hash = commit.hash;
-    return item;
-}
-function subjectHasBreakingMarker(message, workTypes) {
-    return parseSubject(message.split('\n', 1)[0] ?? '', workTypes)?.breaking === true;
-}
-function extractDescription(message) {
-    const firstLine = message.split('\n', 1)[0] ?? message;
-    const afterColon = firstLine.split(': ').slice(1).join(': ');
-    return afterColon.charAt(0).toUpperCase() + afterColon.slice(1);
-}
-const TRAILER_PATTERNS = [
-    /^Change:/i,
-    /^Signed-off-by:/i,
-    /^Co-authored-by:/i,
-    /^(Closes|Fixes|Resolves)\s+#\d+\s*$/i,
-    /^https?:\/\/\S+\/pull\/\d+\/?\s*$/,
-];
-function extractBody(message) {
-    const lines = message.split('\n').slice(1);
-    let start = 0;
-    while (start < lines.length && (lines[start] ?? '').trim() === '') {
-        start += 1;
-    }
-    let end = lines.length;
-    while (end > start) {
-        const line = lines[end - 1] ?? '';
-        const trimmed = line.trim();
-        if (trimmed === '') {
-            end -= 1;
-            continue;
-        }
-        if (TRAILER_PATTERNS.some((pattern) => pattern.test(trimmed))) {
-            end -= 1;
-            continue;
-        }
-        break;
-    }
-    if (end <= start) {
-        return undefined;
-    }
-    return lines.slice(start, end).join('\n').trim();
-}

package/dist/esm/buildChangelogItem.d.ts

@@ -0,0 +1,56 @@
+import type { BumpSignal } from './determineBumpType.js';
+import type { RawCommit } from './enumerateReleaseWindows.js';
+import { type ChangeRecordEntry } from './parseChangeRecordBlock.js';
+import type { ChangelogItem, MalformedChangeRecordBlock, PolicyViolation, ReleaseSettings, UndeclaredEntryType, UnroutedEntryScope, VersionPatterns, WorkTypeConfig } from './types.js';
+/**
+ * Builds the item that one change-record entry yields, with the section header that its type declares.
+ *
+ * Returns `undefined` for an entry whose scopes route it away from the workspace being read, for one whose type is
+ * undeclared, which is recorded as a diagnostic, and for one whose type is excluded from the changelog. An entry
+ * whose `breaking` violates its type's policy is recorded as a policy violation and yields an item that is not
+ * breaking.
+ */
+export declare function buildEntryItem(commit: RawCommit, entry: ChangeRecordEntry, position: number, prNumber: number | undefined, context: ReadContext, diagnostics: ChangelogDiagnostics | undefined): DerivedItem | undefined;
+/**
+ * Builds the item that a commit without a usable change-record block yields from its title and body. The body leaves
+ * out any block, which records data rather than prose.
+ *
+ * `isParsedBreaking` is the parser's policy-evaluated flag. The item is breaking only when the subject also has a
+ * prefix `!`, because the parse also counts a `BREAKING CHANGE:` footer on an `optional`-policy type, which the
+ * changelog ignores.
+ */
+export declare function buildTitleItem(commit: RawCommit, isParsedBreaking: boolean, workTypes: Record<string, WorkTypeConfig>): ChangelogItem;
+/** What reading the unreleased window reports beyond its items. */
+export interface ChangelogDiagnostics {
+    malformedBlocks: MalformedChangeRecordBlock[];
+    /** Breaking-policy violations of the window's titles and change-record entries. */
+    policyViolations: PolicyViolation[];
+    undeclaredEntryTypes: UndeclaredEntryType[];
+    /**
+     * Entry scopes that don't route to any workspace. A read leaves it empty: Only a pass over every workspace can fill
+     * it.
+     */
+    unroutedEntryScopes: UnroutedEntryScope[];
+}
+/** An item with the section header under which it is filed and the signal that it contributes to the bump. */
+export interface DerivedItem {
+    header: string;
+    item: ChangelogItem;
+    signal: BumpSignal;
+}
+/** What every window's read shares. */
+export interface ReadContext {
+    breakingPolicies: NonNullable<ReleaseSettings['breakingPolicies']>;
+    /** Dev-only section titles, stripped of decorations. */
+    devOnlySections: ReadonlySet<string>;
+    /** The workspace to which entries are routed; undefined for a read that takes every entry. */
+    routing?: EntryRouting;
+    versionPatterns: VersionPatterns;
+    workTypes: NonNullable<ReleaseSettings['workTypes']>;
+}
+/** The scope of the workspace to which a read routes change-record entries, and the aliases that resolve scopes. */
+interface EntryRouting {
+    scope: string;
+    scopeAliases: Readonly<Record<string, string>>;
+}
+export {};

package/dist/esm/buildChangelogItem.js

@@ -0,0 +1,119 @@
+import { extractMigration } from "./extractMigration.js";
+import { stripChangeRecordBlocks } from "./parseChangeRecordBlock.js";
+import { evaluateBreakingPolicy, parseSubject, resolveType } from "./parseCommitMessage.js";
+const TRAILER_PATTERNS = [
+    /^Change:/i,
+    /^Signed-off-by:/i,
+    /^Co-authored-by:/i,
+    /^(Closes|Fixes|Resolves)\s+#\d+\s*$/i,
+    /^https?:\/\/\S+\/pull\/\d+\/?\s*$/,
+];
+export function buildEntryItem(commit, entry, position, prNumber, context, diagnostics) {
+    const { breakingPolicies, routing, workTypes } = context;
+    if (routing !== undefined && !isRoutedTo(entry.scopes, routing)) {
+        return undefined;
+    }
+    const type = resolveType(entry.type, workTypes);
+    if (type === undefined) {
+        diagnostics?.undeclaredEntryTypes.push({
+            commitHash: commit.hash,
+            commitSubject: commit.subject,
+            entryPosition: position,
+            type: entry.type,
+        });
+        return undefined;
+    }
+    const config = workTypes[type];
+    if (config === undefined || config.excludedFromChangelog === true) {
+        return undefined;
+    }
+    const breaking = evaluateBreakingPolicy({
+        commit: { message: commit.message, subject: commit.subject, hash: commit.hash },
+        resolvedType: type,
+        hasPrefixBreaking: entry.breaking,
+        hasFooterBreaking: false,
+        policy: breakingPolicies[type] ?? 'optional',
+        prefixSurface: 'entry',
+        onPolicyViolation: diagnostics === undefined
+            ? undefined
+            : (violating, violatedType, surface) => {
+                diagnostics.policyViolations.push({
+                    commitHash: violating.hash,
+                    commitSubject: violating.subject,
+                    type: violatedType,
+                    surface,
+                    entryPosition: position,
+                });
+            },
+    });
+    const item = {
+        description: prNumber === undefined ? entry.text : `${entry.text} (#${prNumber})`,
+    };
+    if (breaking) {
+        item.breaking = true;
+    }
+    if (entry.migration !== undefined) {
+        item.migration = entry.migration;
+    }
+    item.hash = commit.hash;
+    item.entry = position;
+    return { header: config.header, item, signal: { type, breaking } };
+}
+export function buildTitleItem(commit, isParsedBreaking, workTypes) {
+    const body = extractBody(stripChangeRecordBlocks(commit.message));
+    const item = { description: extractDescription(commit.message) };
+    if (body !== undefined) {
+        item.body = body;
+    }
+    if (isParsedBreaking && subjectHasBreakingMarker(commit.message, workTypes)) {
+        item.breaking = true;
+    }
+    const migration = extractMigration(body);
+    if (migration !== undefined) {
+        item.migration = migration;
+    }
+    item.hash = commit.hash;
+    return item;
+}
+function extractBody(message) {
+    const lines = message.split('\n').slice(1);
+    let start = 0;
+    while (start < lines.length && (lines[start] ?? '').trim() === '') {
+        start += 1;
+    }
+    let end = lines.length;
+    while (end > start) {
+        const line = lines[end - 1] ?? '';
+        const trimmed = line.trim();
+        if (trimmed === '') {
+            end -= 1;
+            continue;
+        }
+        if (TRAILER_PATTERNS.some((pattern) => pattern.test(trimmed))) {
+            end -= 1;
+            continue;
+        }
+        break;
+    }
+    if (end <= start) {
+        return undefined;
+    }
+    return lines.slice(start, end).join('\n').trim();
+}
+function extractDescription(message) {
+    const firstLine = message.split('\n', 1)[0] ?? message;
+    const afterColon = firstLine.split(': ').slice(1).join(': ');
+    return afterColon.charAt(0).toUpperCase() + afterColon.slice(1);
+}
+function isRoutedTo(scopes, routing) {
+    if (scopes.length === 0) {
+        return true;
+    }
+    return scopes.some((scope) => {
+        const resolved = routing.scopeAliases[scope] ?? scope;
+        return resolved === '*' || resolved === routing.scope;
+    });
+}
+function subjectHasBreakingMarker(message, workTypes) {
+    return parseSubject(message.split('\n', 1)[0] ?? '', workTypes)?.breaking === true;
+}

package/dist/esm/buildReleasedResult.d.ts

@@ -0,0 +1,20 @@
+import type { ReleaseHistory } from './buildChangelogEntries.js';
+import type { ChangelogEntry, PropagationSource, ReleasedCompositeResult, ReleasedTargetResult, ReleaseTarget, ReleaseType } from './types.js';
+/** The release level that a target takes, whether its own commits or a dependency's bump decided it. */
+export interface TargetRelease {
+    releaseType: ReleaseType;
+    /** Dependencies whose bumps this release records; present for a propagated or mixed release. */
+    propagatedFrom?: PropagationSource[];
+}
+/** The fields of a direct release decision that a released result records; undefined for a propagated release. */
+interface ReleaseDecisionFields {
+    bumpOverride: ReleaseType | undefined;
+    setVersion: string | undefined;
+}
+/** The fields that a released result of either kind takes from the plan. */
+type ReleaseResultFields = Omit<ReleasedCompositeResult, 'commits' | 'kind' | 'parsedCommitCount' | 'releaseType' | 'status'>;
+/** Builds the one synthetic entry of a release that propagation alone set, under the dependencies header. */
+export declare function buildPropagationEntries(target: ReleaseTarget, release: TargetRelease, newVersion: string, today: string, dependenciesHeader: string): ChangelogEntry[];
+/** Builds the released result of a target from the plan's fields, by the target's kind. */
+export declare function buildReleasedResult(target: ReleaseTarget, fields: ReleaseResultFields, release: TargetRelease, decision: ReleaseDecisionFields | undefined, history: ReleaseHistory): ReleasedTargetResult;
+export {};

package/dist/esm/buildReleasedResult.js

@@ -0,0 +1,78 @@
+import { attachChangelogDiagnostics } from "./attachChangelogDiagnostics.js";
+import { buildSyntheticChangelogEntry } from "./buildSyntheticChangelogEntry.js";
+export function buildPropagationEntries(target, release, newVersion, today, dependenciesHeader) {
+    if (release.propagatedFrom === undefined) {
+        throw new Error(`Workspace '${target.id}' has neither a direct release nor a propagation source`);
+    }
+    return [buildSyntheticChangelogEntry(release.propagatedFrom, newVersion, today, dependenciesHeader)];
+}
+export function buildReleasedResult(target, fields, release, decision, history) {
+    switch (target.kind) {
+        case 'package':
+            return buildReleasedPackage(target, fields, release, decision, history);
+        case 'directory':
+            return buildReleasedDirectory(target, fields, release, decision, history);
+        case 'composite':
+            return buildReleasedComposite(fields, release, decision, history);
+    }
+}
+function buildReleasedComposite(fields, release, decision, history) {
+    const { unreleased } = history;
+    const result = {
+        ...fields,
+        status: 'released',
+        kind: 'composite',
+        parsedCommitCount: unreleased.parsedCommitCount,
+        releaseType: release.releaseType,
+        commits: unreleased.commits,
+        ...(unreleased.unparseableCommits !== undefined && { unparseableCommits: unreleased.unparseableCommits }),
+        ...(decision?.bumpOverride !== undefined && { bumpOverride: decision.bumpOverride }),
+    };
+    attachChangelogDiagnostics(result, unreleased.diagnostics);
+    return result;
+}
+function buildReleasedDirectory(target, fields, release, decision, history) {
+    const { unreleased } = history;
+    const setVersion = decision?.setVersion;
+    const result = {
+        ...fields,
+        status: 'released',
+        kind: 'directory',
+        name: target.id,
+        commits: unreleased.commits,
+        ...(setVersion === undefined && {
+            releaseType: release.releaseType,
+            parsedCommitCount: unreleased.parsedCommitCount,
+        }),
+        ...(decision?.bumpOverride !== undefined && { bumpOverride: decision.bumpOverride }),
+        ...(setVersion !== undefined && { setVersion }),
+    };
+    if (setVersion === undefined && unreleased.unparseableCommits !== undefined) {
+        result.unparseableCommits = unreleased.unparseableCommits;
+    }
+    attachChangelogDiagnostics(result, unreleased.diagnostics);
+    return result;
+}
+function buildReleasedPackage(target, fields, release, decision, history) {
+    const { unreleased } = history;
+    const setVersion = decision?.setVersion;
+    const hasParseCounts = decision !== undefined && setVersion === undefined;
+    const result = {
+        ...fields,
+        status: 'released',
+        kind: 'package',
+        commits: unreleased.commits,
+        ...(target.isWorkspace && { name: target.id }),
+        ...(setVersion === undefined && { releaseType: release.releaseType }),
+        ...(hasParseCounts && { parsedCommitCount: unreleased.parsedCommitCount }),
+        ...(decision === undefined && { propagatedOnly: true }),
+        ...(release.propagatedFrom !== undefined && { propagatedFrom: release.propagatedFrom }),
+        ...(decision?.bumpOverride !== undefined && { bumpOverride: decision.bumpOverride }),
+        ...(setVersion !== undefined && { setVersion }),
+    };
+    if (setVersion === undefined && unreleased.unparseableCommits !== undefined) {
+        result.unparseableCommits = unreleased.unparseableCommits;
+    }
+    attachChangelogDiagnostics(result, unreleased.diagnostics);
+    return result;
+}

package/dist/esm/changelogJsonUtils.d.ts

@@ -4,7 +4,7 @@ import type { ChangelogEntry } from './types.js';
  *
  * Checks the entry's top level only: `sections` must be an array, and its contents pass through unvalidated.
  * `.meta/changelog.json` is written by release-kit and read tolerantly; strict validation applies to the
- * human-authored `.meta/changelog-overrides.json`, in `changelogOverrides.ts`.
+ * human-authored `.meta/changelog-overrides.json`, in `loadChangelogOverrides.ts`.
  */
 export declare function isChangelogEntry(value: unknown): value is ChangelogEntry;
 /** Extracts the version from a tag: the text from its first `N.N.N` onward, or the whole tag when it contains none. */