@williamthorsen/release-kit 11.0.0 → 12.0.0

package/dist/esm/buildChangelogEntries.js

@@ -1,145 +1,228 @@
 import { chainError } from '@williamthorsen/toolbelt.errors/candidate';
 import { extractVersion } from "./changelogJsonUtils.js";
-import { DEFAULT_BREAKING_POLICIES, DEFAULT_WORK_TYPES } from "./defaults.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 { COMMIT_PREPROCESSOR_PATTERNS, parseCommitMessage, PIPE_SCOPE_SOURCE } from "./parseCommitMessage.js";
-import { resolveCliffConfigPath } from "./resolveCliffConfigPath.js";
-import { runGitCliff } from "./runGitCliff.js";
+import { parseChangeRecordBlock, stripChangeRecordBlocks } from "./parseChangeRecordBlock.js";
+import { COMMIT_PREPROCESSOR_PATTERNS, evaluateBreakingPolicy, PIPE_SCOPE_SOURCE, resolveType, } from "./parseCommitMessage.js";
 import { stripEmojiPrefix } from "./stripEmojiPrefix.js";
-import { isRecord, isUnknownArray } from "./typeGuards.js";
-const HTML_COMMENT_PREFIX_PATTERN = /^<!--[^>]*-->/;
+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.replace(HTML_COMMENT_PREFIX_PATTERN, ''));
+    return stripEmojiPrefix(group);
 }
 export function buildChangelogEntries(config, tag, options) {
-    const resolvedConfigPath = resolveCliffConfigPath(config.cliffConfigPath, import.meta.url);
-    const cliffArgs = ['--context', '--tag', tag];
-    if (options?.tagPattern !== undefined) {
-        cliffArgs.push('--tag-pattern', options.tagPattern);
-    }
-    const includePaths = options?.includePaths ?? [];
-    for (const includePath of includePaths) {
-        cliffArgs.push('--include-path', includePath);
-    }
+    const history = readReleaseHistory(config, options);
+    return { entries: toChangelogEntries(history, tag), diagnostics: history.unreleased.diagnostics };
+}
+export function readReleaseHistory(config, options) {
     try {
-        const contextJson = runGitCliff(resolvedConfigPath, cliffArgs);
-        const releases = parseCliffContext(contextJson);
-        const devOnlySections = new Set(config.changelogJson.devOnlySections);
-        const workTypes = config.workTypes ?? DEFAULT_WORK_TYPES;
-        const breakingPolicies = config.breakingPolicies ?? DEFAULT_BREAKING_POLICIES;
-        return transformReleases(releases, devOnlySections, workTypes, breakingPolicies);
+        const windows = enumerateReleaseWindows({
+            ...(options.paths !== undefined && { paths: options.paths }),
+            tagPrefixes: options.tagPrefixes,
+            unreleasedTag: UNRELEASED_TAG,
+        });
+        const context = {
+            breakingPolicies: config.breakingPolicies ?? DEFAULT_BREAKING_POLICIES,
+            devOnlySections: new Set(config.changelogJson.devOnlySections.map(stripGroupDecorations)),
+            versionPatterns: config.versionPatterns ?? DEFAULT_VERSION_PATTERNS,
+            workTypes: config.workTypes ?? DEFAULT_WORK_TYPES,
+        };
+        return transformReleases(windows, context);
     }
     catch (error) {
-        throw chainError(`Failed to build changelog entries for tag ${tag}`, error);
+        throw chainError(`Failed to read the release history for ${options.tagPrefixes.join(', ')}`, error);
     }
 }
-function parseCliffContext(json) {
-    const parsed = JSON.parse(json);
-    if (!isUnknownArray(parsed)) {
-        throw new TypeError('Expected git-cliff --context output to be an array');
+export function toChangelogEntries(history, tag) {
+    const { unreleased } = history;
+    if (unreleased.sections.length === 0) {
+        return [...history.releasedEntries];
     }
-    return parsed.map(toCliffContextRelease);
+    return [
+        { version: extractVersion(tag), date: unreleased.date, sections: unreleased.sections },
+        ...history.releasedEntries,
+    ];
 }
-function toCliffContextRelease(value) {
-    if (!isRecord(value)) {
-        return {};
+function transformReleases(windows, context) {
+    const [unreleasedWindow, baselineWindow] = windows;
+    const diagnostics = { malformedBlocks: [], policyViolations: [], undeclaredEntryTypes: [] };
+    const signals = [];
+    const unparseable = [];
+    let parsedCommitCount = 0;
+    const sectionMap = new Map();
+    const unreleasedCommits = unreleasedWindow?.commits ?? [];
+    for (const commit of unreleasedCommits) {
+        const reading = readCommit(commit, context, diagnostics);
+        for (const derived of reading.items) {
+            appendItem(sectionMap, derived.header, derived.item);
+            signals.push(derived.signal);
+        }
+        if (reading.items.length > 0) {
+            parsedCommitCount += 1;
+        }
+        else if (reading.isUnparseable) {
+            unparseable.push(commit);
+        }
     }
-    const release = {};
-    if (typeof value['version'] === 'string') {
-        release.version = value['version'];
+    const releasedEntries = [];
+    for (const release of windows.slice(1)) {
+        const releaseSections = new Map();
+        for (const commit of release.commits) {
+            for (const derived of readCommit(commit, context, undefined).items) {
+                appendItem(releaseSections, derived.header, derived.item);
+            }
+        }
+        const sections = buildSections(releaseSections, context.devOnlySections);
+        if (sections.length > 0) {
+            releasedEntries.push({ version: extractVersion(release.version), date: formatDate(release.timestamp), sections });
+        }
     }
-    if (typeof value['timestamp'] === 'number') {
-        release.timestamp = value['timestamp'];
+    return {
+        previousTag: baselineWindow?.version,
+        releasedEntries,
+        unreleased: {
+            bump: determineBumpType(signals, context.workTypes, context.versionPatterns),
+            commits: unreleasedCommits.filter((commit) => !isReleaseSubject(commit.subject)).toReversed(),
+            date: formatDate(unreleasedWindow?.timestamp ?? Math.floor(Date.now() / 1_000)),
+            diagnostics,
+            parsedCommitCount,
+            sections: buildSections(sectionMap, context.devOnlySections),
+            unparseableCommits: unparseable.length > 0 ? unparseable.toReversed() : undefined,
+        },
+    };
+}
+function readCommit(commit, context, diagnostics) {
+    if (isNonChangeSubject(commit.subject)) {
+        return { items: [], isUnparseable: false };
     }
-    if (isUnknownArray(value['commits'])) {
-        release.commits = value['commits'].map(toCliffContextCommit);
+    const reading = parseChangeRecordBlock(commit.message);
+    if (reading.kind === 'malformed') {
+        diagnostics?.malformedBlocks.push({
+            commitHash: commit.hash,
+            commitSubject: commit.subject,
+            reason: reading.reason,
+        });
     }
-    return release;
-}
-function toCliffContextCommit(value) {
-    if (!isRecord(value)) {
-        return { message: '' };
+    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 commit = {
-        message: typeof value['message'] === 'string' ? value['message'] : '',
-    };
-    if (typeof value['group'] === 'string') {
-        commit.group = value['group'];
+    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' };
     }
-    if (typeof value['id'] === 'string') {
-        commit.id = value['id'];
+    const item = buildTitleItem(commit, classification.breaking);
+    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 commit;
+    return sections.toSorted((a, b) => canonicalSectionPriority(a.title) - canonicalSectionPriority(b.title));
 }
-function transformReleases(releases, devOnlySections, workTypes, breakingPolicies) {
-    const entries = [];
-    const devOnlyNormalised = new Set([...devOnlySections].map(stripGroupDecorations));
-    for (const release of releases) {
-        if (release.version === undefined) {
-            continue;
-        }
-        const version = extractVersion(release.version);
-        const date = release.timestamp !== undefined ? new Date(release.timestamp * 1_000).toISOString().slice(0, 10) : 'unreleased';
-        const sectionMap = new Map();
-        const commits = release.commits ?? [];
-        for (const commit of commits) {
-            const group = stripCommentPrefix(commit.group ?? 'Other');
-            const description = extractDescription(commit.message);
-            const body = extractBody(commit.message);
-            const breaking = isBreakingUnderPolicy(commit, workTypes, breakingPolicies);
-            let items = sectionMap.get(group);
-            if (items === undefined) {
-                items = [];
-                sectionMap.set(group, items);
-            }
-            const item = { description };
-            if (body !== undefined) {
-                item.body = body;
-            }
-            if (breaking) {
-                item.breaking = true;
-            }
-            const migration = extractMigration(body);
-            if (migration !== undefined) {
-                item.migration = migration;
-            }
-            if (commit.id !== undefined && commit.id !== '') {
-                item.hash = commit.id;
-            }
-            items.push(item);
-        }
-        const sections = [];
-        for (const [title, items] of sectionMap) {
-            if (items.length === 0) {
-                continue;
-            }
-            sections.push({
-                title,
-                audience: devOnlyNormalised.has(stripGroupDecorations(title)) ? 'dev' : 'all',
-                items,
-            });
-        }
-        sections.sort((a, b) => canonicalSectionPriority(a.title) - canonicalSectionPriority(b.title));
-        if (sections.length > 0) {
-            entries.push({ version, date, sections });
-        }
+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);
     }
-    return entries;
+    items.push(item);
 }
-function stripCommentPrefix(group) {
-    return group.replace(HTML_COMMENT_PREFIX_PATTERN, '');
+function buildEntryItem(commit, entry, position, prNumber, context, diagnostics) {
+    const { breakingPolicies, workTypes } = context;
+    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 isBreakingUnderPolicy(commit, workTypes, breakingPolicies) {
-    if (!subjectHasBreakingMarker(commit.message)) {
-        return false;
+function buildTitleItem(commit, isParsedBreaking) {
+    const body = extractBody(stripChangeRecordBlocks(commit.message));
+    const item = { description: extractDescription(commit.message) };
+    if (body !== undefined) {
+        item.body = body;
+    }
+    if (isParsedBreaking && subjectHasBreakingMarker(commit.message)) {
+        item.breaking = true;
+    }
+    const migration = extractMigration(body);
+    if (migration !== undefined) {
+        item.migration = migration;
     }
-    const parsed = parseCommitMessage(commit.message, commit.id ?? '', workTypes, undefined, { breakingPolicies });
-    return parsed?.breaking ?? true;
+    item.hash = commit.hash;
+    return item;
 }
 const SUBJECT_BREAKING_MARKER_PATTERN = new RegExp(String.raw `^(?:${PIPE_SCOPE_SOURCE}\|)?\w+(?:\([^)]+\))?!:`);
 function subjectHasBreakingMarker(message) {

package/dist/esm/buildReleaseSummary.js

@@ -11,7 +11,7 @@ export function buildReleaseSummary(result) {
         }
         const lines = [workspace.tag];
         for (const commit of commits) {
-            lines.push(`- ${stripScope(commit.message)}`);
+            lines.push(`- ${stripScope(commit.subject)}`);
         }
         sections.push(lines.join('\n'));
     }
@@ -19,7 +19,7 @@ export function buildReleaseSummary(result) {
     if (project !== undefined && project.status === 'released' && project.commits.length > 0) {
         const lines = [project.tag];
         for (const commit of project.commits) {
-            lines.push(`- ${stripScope(commit.message)}`);
+            lines.push(`- ${stripScope(commit.subject)}`);
         }
         sections.push(lines.join('\n'));
     }

package/dist/esm/changelogOverrides.d.ts

@@ -1,4 +1,8 @@
 import type { ChangelogEntry, ChangelogOverride, WorkspaceConfig } from './types.js';
+/** Known fields on a single override entry; presence of any other field is a validation error. */
+export declare const KNOWN_OVERRIDE_FIELDS: Set<string>;
+/** Form of an override key: a lowercase hex commit hash or prefix, optionally followed by `:<n>`, a 1-based entry position. */
+export declare const OVERRIDE_KEY_PATTERN: RegExp;
 /** Result of loading an override file: either parsed overrides or a list of structured errors. */
 export type LoadChangelogOverridesResult = {
     overrides: Map<string, ChangelogOverride>;
@@ -26,6 +30,11 @@ export declare function validateChangelogOverrides(raw: unknown): {
     overrides: Map<string, ChangelogOverride>;
     errors: string[];
 };
+/** Split a valid override key into its hash prefix and, for an ordinal key, its 1-based entry position. */
+export declare function parseOverrideKey(key: string): {
+    hashPrefix: string;
+    entry?: number;
+};
 /**
  * Format the standard "stale override key" warning. Callers compute the set of stale keys
  * (keys that didn't match anywhere) and use this helper to surface them uniformly. Centralized
@@ -35,12 +44,16 @@ export declare function formatStaleOverrideKeyWarning(key: string): string;
 /**
  * Apply overrides to a `ChangelogEntry[]`, returning a new array. Pure: no mutation, no I/O.
  *
- * Match algorithm: each override key is treated as a string-prefix against `ChangelogItem.hash`.
+ * Match algorithm: each key's hash prefix is matched against the distinct `ChangelogItem.hash` values.
  * - 0 matches → key is recorded as unmatched in this batch (no warning emitted here).
- * - 1 match → apply each present override field to the matched item, record key as matched.
+ * - 1 match → a bare key resolves to every item of that commit, and an ordinal key `<hash>:<n>` to the items whose
+ *   `entry` is `n`. A key that resolves to no item is unmatched, so an ordinal key on a title-derived item goes stale.
  * - 2+ matches → error (ambiguous prefix).
  *
- * `matchedKeys` lists the override keys that resolved to exactly one item in this batch.
+ * Two more conditions are errors, and the keys involved apply nowhere: a bare key that sets `description` or `body` on a
+ * commit with several items, and two keys that resolve to the same item.
+ *
+ * `matchedKeys` lists the override keys that resolved to at least one item without error in this batch.
  * Callers are responsible for computing stale-key warnings: in a monorepo run, an override
  * may target a commit that lives in another workspace, so the per-batch zero-match signal is
  * insufficient on its own. Single-package and monorepo orchestrators format warnings using
@@ -98,8 +111,8 @@ export declare function loadOverridesForScopes(scopes: {
  *
  * Byte-equal-key shadowing: when a workspace key string-equals a root key, the workspace
  * entry wins entirely (no field-level merge) and supplants the root entry in the result.
- * Different-prefix keys that happen to resolve to the same commit do NOT shadow here — they
- * fall through to the existing ambiguous-prefix error in {@link applyChangelogOverrides}.
+ * Non-identical keys that resolve to the same item do NOT shadow here: {@link applyChangelogOverrides}
+ * reports them as overlapping.
  *
  * Pure: never mutates inputs.
  */
@@ -127,12 +140,17 @@ export interface OverrideContext {
  * is a bug, and we want the prepare run to fail before any workspace begins writing.
  */
 export declare function createOverrideContext(workspaces: WorkspaceConfig[]): OverrideContext;
+/** A changelog item as override matching sees it. `entry` is absent for a title-derived item. */
+export interface OverrideTargetItem {
+    hash: string;
+    entry?: number;
+}
 /** Per-scope input to {@link validateAllChangelogOverrides}. */
 export interface ChangelogOverrideScope {
     /** Path to the override file (relative to the repo root). Used to load the file and to attribute findings. */
     filePath: string;
-    /** Commit hashes in this scope's history window. Each override key is matched against these. */
-    hashes: readonly string[];
+    /** Items in this scope's history window. Each override key is matched against these. */
+    items: readonly OverrideTargetItem[];
 }
 /** Inputs to {@link validateAllChangelogOverrides}. */
 export interface ValidateAllChangelogOverridesInputs {
@@ -141,16 +159,16 @@ export interface ValidateAllChangelogOverridesInputs {
      *
      * The file at `filePath` is loaded once and used in two ways:
      * - Its overrides are composed into every workspace's apply (root-tier overrides apply globally).
-     * - When `hashes` is provided, the project map is also applied directly to that hash universe
+     * - When `items` is provided, the project map is also applied directly to those items
      *   (project release in monorepo mode, or the package's history in single-package mode).
      *
      * Omit when no project file exists (rare — most repos have a root file even if empty).
      */
     project?: {
         filePath: string;
-        hashes?: readonly string[];
+        items?: readonly OverrideTargetItem[];
     };
-    /** Per-workspace scopes. Each workspace's file applies only to its own hash universe. */
+    /** Per-workspace scopes. Each workspace's file applies only to its own items. */
     workspaces?: readonly ChangelogOverrideScope[];
 }
 /** Result of {@link validateAllChangelogOverrides}: aggregated errors and warnings, each prefixed with the file path it pertains to. */
@@ -160,16 +178,16 @@ export interface ValidateAllChangelogOverridesResult {
 }
 /**
  * End-to-end health check across every override file and scope. Pure: takes already-collected
- * hash universes and returns aggregated findings. The CLI command and any other consumer
+ * item universes and returns aggregated findings. The CLI command and any other consumer
  * (programmatic library callers, future composite checks) wrap this with discovery and I/O.
  *
  * When invoked via the standard `validateOverridesCommand` entry point, each scope's
- * `hashes` is built by `buildChangelogEntries` — the same path `release-kit prepare` walks —
+ * `items` is built by `buildChangelogEntries` — the same path `release-kit prepare` walks —
  * so the match-set is byte-equal to what `prepare` would compute. The tier asymmetry is part
  * of that contract: workspace-tier keys are stale if they don't match in their own workspace;
  * root-tier keys are stale only if they don't match in any scope (no workspace AND not the
  * project release window). Library callers that construct `inputs` directly are responsible
- * for supplying the same hash universes if they want this guarantee.
+ * for supplying the same item universes if they want this guarantee.
  *
  * Every returned string is prefixed with the relative override-file path it pertains to so
  * consumers can locate the offending file without further structuring.