@williamthorsen/release-kit 11.0.0 → 12.0.0

package/dist/esm/changelogOverrides.js

@@ -6,7 +6,9 @@ import { isRecord } from "./typeGuards.js";
 const OVERRIDES_FILENAME = '.meta/changelog-overrides.json';
 const VALID_AUDIENCE_VALUES = new Set(['all', 'dev', 'skip']);
 const V1_SUPPORTED_AUDIENCE_VALUES = new Set(['skip']);
-const KNOWN_OVERRIDE_FIELDS = new Set(['audience', 'description', 'body', 'breaking']);
+export const KNOWN_OVERRIDE_FIELDS = new Set(['audience', 'description', 'body', 'breaking']);
+export const OVERRIDE_KEY_PATTERN = /^[0-9a-f]+(:[1-9][0-9]*)?$/;
+const SCHEMA_KEY = '$schema';
 export function loadChangelogOverrides(path) {
     if (!existsSync(path)) {
         return { overrides: new Map() };
@@ -43,8 +45,14 @@ export function validateChangelogOverrides(raw) {
         return { overrides, errors };
     }
     for (const [key, rawEntry] of Object.entries(raw)) {
-        if (key === '') {
-            errors.push('Override file: empty-string key is not a valid commit hash');
+        if (key === SCHEMA_KEY) {
+            if (typeof rawEntry !== 'string') {
+                errors.push(`Override file: '${SCHEMA_KEY}' must be a string`);
+            }
+            continue;
+        }
+        if (!OVERRIDE_KEY_PATTERN.test(key)) {
+            errors.push(`overrides['${key}']: key must be a lowercase hex commit hash or prefix, optionally followed by ':<n>'`);
             continue;
         }
         const validated = validateSingleOverride(key, rawEntry, errors);
@@ -54,6 +62,13 @@ export function validateChangelogOverrides(raw) {
     }
     return { overrides, errors };
 }
+export function parseOverrideKey(key) {
+    const separatorIndex = key.indexOf(':');
+    if (separatorIndex === -1) {
+        return { hashPrefix: key };
+    }
+    return { hashPrefix: key.slice(0, separatorIndex), entry: Number(key.slice(separatorIndex + 1)) };
+}
 function validateSingleOverride(key, rawEntry, errors) {
     if (!isRecord(rawEntry)) {
         errors.push(`overrides['${key}']: must be an object`);
@@ -125,53 +140,27 @@ function validateAudience(key, value, errors) {
     return 'skip';
 }
 export function formatStaleOverrideKeyWarning(key) {
-    return `Override key '${key}' did not match any commit hash in the changelog (likely a stale reference)`;
+    return `Override key '${key}' did not match any item in the changelog (likely a stale reference)`;
 }
 export function applyChangelogOverrides(entries, overrides) {
     const warnings = [];
-    const errors = [];
-    const matchedKeys = [];
     if (overrides.size === 0) {
-        return { entries: entries.map(cloneEntry), warnings, errors, matchedKeys };
-    }
-    const allHashes = [];
-    for (const entry of entries) {
-        for (const section of entry.sections) {
-            for (const item of section.items) {
-                if (item.hash !== undefined) {
-                    allHashes.push(item.hash);
-                }
-            }
-        }
+        return { entries: entries.map(cloneEntry), warnings, errors: [], matchedKeys: [] };
     }
-    const keyToMatchedHashes = new Map();
-    for (const overrideKey of overrides.keys()) {
-        const matches = allHashes.filter((hash) => hash.startsWith(overrideKey));
-        if (matches.length === 0) {
-            continue;
-        }
-        if (matches.length > 1) {
-            errors.push(`Override key '${overrideKey}' is ambiguous: matches multiple commits (${matches.join(', ')}). ` +
-                'Use a longer prefix or the full commit hash.');
-            continue;
-        }
-        keyToMatchedHashes.set(overrideKey, matches);
-        matchedKeys.push(overrideKey);
-    }
-    const hashToOverride = new Map();
-    for (const [overrideKey, matchedHashes] of keyToMatchedHashes) {
+    const { errors, itemIdToKey } = resolveOverrideKeys(indexEntryPositions(entries), overrides);
+    const itemIdToOverride = new Map();
+    for (const [itemId, overrideKey] of itemIdToKey) {
         const override = overrides.get(overrideKey);
-        if (override === undefined)
-            continue;
-        for (const hash of matchedHashes) {
-            hashToOverride.set(hash, override);
+        if (override !== undefined) {
+            itemIdToOverride.set(itemId, override);
         }
     }
+    const matchedKeys = [...new Set(itemIdToKey.values())];
     const transformedEntries = [];
     for (const entry of entries) {
         const transformedSections = [];
         for (const section of entry.sections) {
-            const transformedItems = applyOverridesToItems(section.items, hashToOverride);
+            const transformedItems = applyOverridesToItems(section.items, itemIdToOverride);
             if (transformedItems.length === 0) {
                 continue;
             }
@@ -181,14 +170,93 @@ export function applyChangelogOverrides(entries, overrides) {
     }
     return { entries: transformedEntries, warnings, errors, matchedKeys };
 }
-function applyOverridesToItems(items, hashToOverride) {
+function resolveOverrideKeys(positionsByHash, overrides) {
+    const errors = [];
+    const failedKeys = new Set();
+    const itemIdToKey = new Map();
+    for (const [overrideKey, override] of overrides) {
+        const resolution = resolveOverrideKey(overrideKey, positionsByHash);
+        if (resolution.kind === 'ambiguous') {
+            errors.push(`Override key '${overrideKey}' is ambiguous: matches multiple commits (${resolution.hashes.join(', ')}). ` +
+                'Use a longer prefix or the full commit hash.');
+            continue;
+        }
+        if (resolution.kind === 'none') {
+            continue;
+        }
+        const { hash, positions } = resolution;
+        if (parseOverrideKey(overrideKey).entry === undefined && positions.length > 1) {
+            const fieldsSet = ['description', 'body'].filter((field) => override[field] !== undefined);
+            if (fieldsSet.length > 0) {
+                const ordinalKeys = positions.map((position) => `${overrideKey}:${position}`).join(', ');
+                errors.push(`Override key '${overrideKey}' sets ${fieldsSet.join(' and ')} on a commit with several items; use ${ordinalKeys}`);
+                continue;
+            }
+        }
+        for (const position of positions) {
+            const itemId = formatItemId(hash, position);
+            const claimingKey = itemIdToKey.get(itemId);
+            if (claimingKey === undefined) {
+                itemIdToKey.set(itemId, overrideKey);
+                continue;
+            }
+            const target = position === undefined ? `commit ${hash}` : `the item at ${hash}:${position}`;
+            errors.push(`Override keys '${claimingKey}' and '${overrideKey}' both match ${target}; keep one`);
+            failedKeys.add(claimingKey);
+            failedKeys.add(overrideKey);
+        }
+    }
+    for (const [itemId, overrideKey] of itemIdToKey) {
+        if (failedKeys.has(overrideKey)) {
+            itemIdToKey.delete(itemId);
+        }
+    }
+    return { errors, itemIdToKey };
+}
+function resolveOverrideKey(overrideKey, positionsByHash) {
+    const { hashPrefix, entry } = parseOverrideKey(overrideKey);
+    const hashes = positionsByHash
+        .keys()
+        .filter((hash) => hash.startsWith(hashPrefix))
+        .toArray();
+    const [hash] = hashes;
+    if (hash === undefined) {
+        return { kind: 'none' };
+    }
+    if (hashes.length > 1) {
+        return { kind: 'ambiguous', hashes };
+    }
+    const available = [...(positionsByHash.get(hash) ?? [])];
+    const positions = entry === undefined
+        ? available.toSorted((left, right) => (left ?? 0) - (right ?? 0))
+        : available.filter((position) => position === entry);
+    return positions.length === 0 ? { kind: 'none' } : { kind: 'items', hash, positions };
+}
+function indexEntryPositions(entries) {
+    return indexItemPositions(entries.flatMap((entry) => entry.sections.flatMap((section) => section.items)));
+}
+function indexItemPositions(items) {
+    const positionsByHash = new Map();
+    for (const item of items) {
+        if (item.hash === undefined)
+            continue;
+        const positions = positionsByHash.get(item.hash) ?? new Set();
+        positions.add(item.entry);
+        positionsByHash.set(item.hash, positions);
+    }
+    return positionsByHash;
+}
+function formatItemId(hash, entry) {
+    return entry === undefined ? hash : `${hash}:${entry}`;
+}
+function applyOverridesToItems(items, itemIdToOverride) {
     const result = [];
     for (const item of items) {
         if (item.hash === undefined) {
             result.push(cloneItem(item));
             continue;
         }
-        const override = hashToOverride.get(item.hash);
+        const override = itemIdToOverride.get(formatItemId(item.hash, item.entry));
         if (override === undefined) {
             result.push(cloneItem(item));
             continue;
@@ -207,6 +275,8 @@ function applyOverrideToItem(item, override) {
     }
     if (override.body !== undefined) {
         result.body = override.body;
+    }
+    if (override.body !== undefined && item.entry === undefined) {
         const migration = extractMigration(override.body);
         if (migration === undefined) {
             delete result.migration;
@@ -288,7 +358,7 @@ export function validateAllChangelogOverrides(inputs) {
     const projectMap = loadScopeMap(projectFilePath, errors);
     const workspaceMaps = (inputs.workspaces ?? []).map((scope) => ({
         filePath: scope.filePath,
-        hashes: scope.hashes,
+        items: scope.items,
         map: loadScopeMap(scope.filePath, errors),
     }));
     const globalMatchedRootKeys = new Set();
@@ -302,9 +372,9 @@ export function validateAllChangelogOverrides(inputs) {
             globalMatchedRootKeys,
         });
     }
-    const projectHashes = inputs.project?.hashes;
-    if (projectFilePath !== undefined && projectHashes !== undefined) {
-        processProjectScope({ projectFilePath, projectMap, projectHashes, errors, globalMatchedRootKeys });
+    const projectItems = inputs.project?.items;
+    if (projectFilePath !== undefined && projectItems !== undefined) {
+        processProjectScope({ projectFilePath, projectMap, projectItems, errors, globalMatchedRootKeys });
     }
     if (projectFilePath !== undefined) {
         collectRootStaleWarnings(projectFilePath, projectMap, globalMatchedRootKeys, warnings);
@@ -313,39 +383,49 @@ export function validateAllChangelogOverrides(inputs) {
 }
 function processWorkspaceScope(args) {
     const { workspace, projectFilePath, projectMap, errors, warnings, globalMatchedRootKeys } = args;
-    const { filePath, hashes, map } = workspace;
-    const workspaceApplied = applyChangelogOverrides(makeValidationEntries(hashes), map);
+    const { filePath, items, map } = workspace;
+    const validationEntries = makeValidationEntries(items);
+    const positionsByHash = indexItemPositions(items);
+    const workspaceApplied = applyChangelogOverrides(validationEntries, map);
     for (const message of workspaceApplied.errors) {
         errors.push(prefixWithFilePath(filePath, message));
     }
     if (projectFilePath !== undefined && projectMap.size > 0) {
         const projectMinusShadowed = filterShadowedKeys(projectMap, map);
-        const projectApplied = applyChangelogOverrides(makeValidationEntries(hashes), projectMinusShadowed);
+        const projectApplied = applyChangelogOverrides(validationEntries, projectMinusShadowed);
         for (const message of projectApplied.errors) {
             errors.push(prefixWithFilePath(projectFilePath, message));
         }
+        const perFileErrors = new Set([...workspaceApplied.errors, ...projectApplied.errors]);
+        const composedApplied = applyChangelogOverrides(validationEntries, composeOverrides(projectMap, map));
+        for (const message of composedApplied.errors) {
+            if (!perFileErrors.has(message)) {
+                errors.push(prefixWithFilePath(filePath, message));
+            }
+        }
     }
     for (const key of map.keys()) {
-        if (!hasAnyMatch(key, hashes)) {
+        if (!hasAnyMatch(key, positionsByHash)) {
             warnings.push(formatWorkspaceStaleWarning(filePath, key));
         }
     }
     for (const key of projectMap.keys()) {
         if (map.has(key))
             continue;
-        if (hasAnyMatch(key, hashes)) {
+        if (hasAnyMatch(key, positionsByHash)) {
             globalMatchedRootKeys.add(key);
         }
     }
 }
 function processProjectScope(args) {
-    const { projectFilePath, projectMap, projectHashes, errors, globalMatchedRootKeys } = args;
-    const applied = applyChangelogOverrides(makeValidationEntries(projectHashes), projectMap);
+    const { projectFilePath, projectMap, projectItems, errors, globalMatchedRootKeys } = args;
+    const applied = applyChangelogOverrides(makeValidationEntries(projectItems), projectMap);
     for (const message of applied.errors) {
         errors.push(prefixWithFilePath(projectFilePath, message));
     }
+    const positionsByHash = indexItemPositions(projectItems);
     for (const key of projectMap.keys()) {
-        if (hasAnyMatch(key, projectHashes)) {
+        if (hasAnyMatch(key, positionsByHash)) {
             globalMatchedRootKeys.add(key);
         }
     }
@@ -357,8 +437,8 @@ function collectRootStaleWarnings(projectFilePath, projectMap, globalMatchedRoot
         }
     }
 }
-function hasAnyMatch(key, hashes) {
-    return hashes.some((hash) => hash.startsWith(key));
+function hasAnyMatch(key, positionsByHash) {
+    return resolveOverrideKey(key, positionsByHash).kind !== 'none';
 }
 function filterShadowedKeys(projectMap, workspaceMap) {
     const result = new Map();
@@ -382,7 +462,7 @@ function loadScopeMap(filePath, errors) {
     }
     return result.overrides;
 }
-function makeValidationEntries(hashes) {
+function makeValidationEntries(items) {
     return [
         {
             version: '0.0.0',
@@ -391,7 +471,7 @@ function makeValidationEntries(hashes) {
                 {
                     title: 'Validation',
                     audience: 'all',
-                    items: hashes.map((hash) => ({ description: '', hash })),
+                    items: items.map((item) => ({ ...item, description: '' })),
                 },
             ],
         },
@@ -401,10 +481,10 @@ function prefixWithFilePath(filePath, message) {
     return `${filePath}: ${message}`;
 }
 function formatWorkspaceStaleWarning(filePath, key) {
-    return `${filePath}: Override key '${key}' did not match any commit in this workspace's history (likely a stale reference)`;
+    return `${filePath}: Override key '${key}' did not match any item in this workspace's history (likely a stale reference)`;
 }
 function formatRootStaleWarning(filePath, key) {
-    return `${filePath}: Override key '${key}' did not match any commit in any scope (likely a stale reference)`;
+    return `${filePath}: Override key '${key}' did not match any item in any scope (likely a stale reference)`;
 }
 export function applyWorkspaceOverrides(newEntries, workspacePath, overrideContext) {
     const { project, perWorkspace, overrideWarnings, globalMatchedRootKeys } = overrideContext;

package/dist/esm/classifyChangelogCommit.d.ts

@@ -0,0 +1,38 @@
+import { type ParseCommitMessageOptions } from './parseCommitMessage.js';
+import type { Commit, WorkTypeConfig } from './types.js';
+/**
+ * How a commit's title places it in a changelog: under a section header, excluded by design, or unreadable.
+ *
+ * `breaking` is the parser's flag under the breaking policies passed in, which a `BREAKING CHANGE:` footer can set.
+ */
+export type ChangelogClassification = {
+    kind: 'header';
+    header: string;
+    type: string;
+    breaking: boolean;
+} | {
+    kind: 'excluded';
+} | {
+    kind: 'unparseable';
+};
+/**
+ * Classifies a commit by its title.
+ *
+ * Four gates decide, in order: a `release:` or `Merge` subject is excluded; a subject carrying no ticket-ID prefix is
+ * unparseable; a type that `parseCommitMessage` cannot resolve against `workTypes` is unparseable; and a type that
+ * `workTypes` excludes from the changelog is excluded. A commit that passes all four takes the header its type declares.
+ *
+ * `options` reaches the parse, so a policy violation is reported for every ticketed commit whose type resolves,
+ * excluded types included.
+ *
+ * The header carries no order encoding. `buildChangelogEntries` sorts sections by canonical priority, so
+ * the position a section occupies comes from the taxonomy rather than from the header string.
+ */
+export declare function classifyChangelogCommit(commit: Pick<Commit, 'hash' | 'message'>, workTypes: Record<string, WorkTypeConfig>, options?: ParseCommitMessageOptions): ChangelogClassification;
+/**
+ * Reports whether a subject belongs to a commit that never reaches a changelog: a `release:` commit, which records
+ * version bumps, or a git merge commit, whose content the merged commits already report.
+ */
+export declare function isNonChangeSubject(subject: string): boolean;
+/** Reports whether a subject belongs to a `release:` commit, which records version bumps rather than a change. */
+export declare function isReleaseSubject(subject: string): boolean;

package/dist/esm/classifyChangelogCommit.js

@@ -0,0 +1,33 @@
+import { COMMIT_PREPROCESSOR_PATTERNS, parseCommitMessage, } from "./parseCommitMessage.js";
+const RELEASE_SUBJECT_PATTERN = /^release:/;
+const MERGE_SUBJECT_PATTERN = /^Merge/;
+export function classifyChangelogCommit(commit, workTypes, options) {
+    const subject = commit.message.split('\n', 1)[0] ?? '';
+    if (isNonChangeSubject(subject)) {
+        return { kind: 'excluded' };
+    }
+    if (!hasTicketPrefix(subject)) {
+        return { kind: 'unparseable' };
+    }
+    const parsed = parseCommitMessage(commit.message, commit.hash, workTypes, undefined, options);
+    if (parsed === undefined) {
+        return { kind: 'unparseable' };
+    }
+    const config = workTypes[parsed.type];
+    if (config === undefined) {
+        return { kind: 'unparseable' };
+    }
+    if (config.excludedFromChangelog === true) {
+        return { kind: 'excluded' };
+    }
+    return { kind: 'header', header: config.header, type: parsed.type, breaking: parsed.breaking };
+}
+export function isNonChangeSubject(subject) {
+    return isReleaseSubject(subject) || MERGE_SUBJECT_PATTERN.test(subject);
+}
+export function isReleaseSubject(subject) {
+    return RELEASE_SUBJECT_PATTERN.test(subject);
+}
+function hasTicketPrefix(subject) {
+    return COMMIT_PREPROCESSOR_PATTERNS.some((pattern) => pattern.test(subject));
+}

package/dist/esm/decideRelease.d.ts

@@ -1,23 +1,17 @@
-import { type PolicyViolationHandler } from './parseCommitMessage.js';
-import type { Commit, ReleaseType, VersionPatterns, WorkTypeConfig } from './types.js';
-/** Inputs to the unified release decision used by both pipelines. */
+import type { ReleaseType } from './types.js';
+/** Inputs to the release decision that every release path makes. */
 export interface DecideReleaseArgs {
-    commits: readonly Commit[];
+    /** The bump that the window's changelog items call for; undefined when they call for none. */
+    naturalBump: ReleaseType | undefined;
+    /** The number of commits in the window, which selects the skip reason. */
+    commitCount: number;
     /** True when `--force` was passed; treats absence of a natural bump as patch. Defaults to false. */
     force?: boolean | undefined;
     /** Explicit `--bump=X` override. When set, the level is X regardless of the natural bump. */
     bumpOverride: ReleaseType | undefined;
-    workTypes: Record<string, WorkTypeConfig>;
-    versionPatterns: VersionPatterns;
-    scopeAliases: Record<string, string> | undefined;
-    /** Per-canonical-type breaking-policy lookup. When provided, drives `!` policy enforcement in `parseCommitMessage`. */
-    breakingPolicies?: Record<string, 'forbidden' | 'optional' | 'required'>;
-    /** Receives policy-violation notifications from `parseCommitMessage`. */
-    onPolicyViolation?: PolicyViolationHandler;
     /**
-     * Skip wordings to use when no commits exist (`noCommits`) or when commits exist but
-     * none parse to a bump-worthy work type (`noBumpWorthy`). Both pipelines pass their
-     * own pre-rendered wordings (with `{name}` / `since` substitutions already applied).
+     * Skip wordings to use when no commits exist (`noCommits`) or when commits exist but none yields a changelog item
+     * (`noBumpWorthy`). Each path passes its own pre-rendered wordings.
      */
     skipReasons: {
         noCommits: string;
@@ -28,38 +22,18 @@ export interface DecideReleaseArgs {
 export type DecideReleaseResult = {
     outcome: 'release';
     releaseType: ReleaseType;
-    parsedCommitCount: number;
-    unparseableCommits: Commit[] | undefined;
 } | {
     outcome: 'skip';
     skipReason: string;
-    parsedCommitCount: number;
-    unparseableCommits: Commit[] | undefined;
 };
 /**
- * Apply the unified release-decision algorithm shared by both `releasePrepareProject`
- * and the per-workspace path in `releasePrepareMono`.
+ * Decides whether a window releases, and at which level.
  *
  * Algorithm:
  *   shouldRelease = naturalBump !== undefined OR force === true
  *   releaseLevel  = bumpOverride ?? naturalBump ?? 'patch'
  *
- * "natural bump" is the raw output of `determineBumpType` over the parsed commits — it
- * is `undefined` when no commits exist or when none of the parsed commits map to a
- * bump-worthy work type. Note that this differs from `determineBumpFromCommits`, which
- * applies a patch floor whenever any commits exist; the patch floor is intentionally
- * not applied here so that `--bump=X` and `--force` remain orthogonal (the floor is
- * applied only when `--force` is set, by virtue of the `naturalBump ?? 'patch'`
- * fallback in the release-level expression above).
- *
- * `parsedCommitCount` and `unparseableCommits` are returned in both branches so callers
- * can surface diagnostic data uniformly regardless of skip/release outcome.
- *
- * Scope: this is the canonical algorithm for the orthogonal-flag model in the
- * monorepo path (`releasePrepareProject` + per-workspace `determineDirectBumps`). The
- * single-package executor (`releasePrepare`) deliberately retains
- * `determineBumpFromCommits` and the legacy patch-floor semantics; `prepareCommand`
- * rejects `--force` without `--bump` in single-package mode to surface that gap. A
- * future ticket can unify the single-package path; see #313's external plan.
+ * A window without a natural bump releases only under `--force`, so `--bump=X` chooses a level without triggering a
+ * release, and `--force` triggers one without choosing a level.
  */
 export declare function decideRelease(args: DecideReleaseArgs): DecideReleaseResult;

package/dist/esm/decideRelease.js

@@ -1,30 +1,8 @@
-import { determineBumpType } from "./determineBumpType.js";
-import { parseCommitMessage, } from "./parseCommitMessage.js";
 export function decideRelease(args) {
-    const { commits, force = false, bumpOverride, workTypes, versionPatterns, scopeAliases, breakingPolicies, onPolicyViolation, skipReasons, } = args;
-    const parseOptions = {
-        ...(breakingPolicies !== undefined && { breakingPolicies }),
-        ...(onPolicyViolation !== undefined && { onPolicyViolation }),
-    };
-    const parsedCommits = [];
-    const unparseable = [];
-    for (const commit of commits) {
-        const parsed = parseCommitMessage(commit.message, commit.hash, workTypes, scopeAliases, parseOptions);
-        if (parsed === undefined) {
-            unparseable.push(commit);
-        }
-        else {
-            parsedCommits.push(parsed);
-        }
+    const { naturalBump, commitCount, force = false, bumpOverride, skipReasons } = args;
+    if (naturalBump === undefined && !force) {
+        const skipReason = commitCount === 0 ? skipReasons.noCommits : skipReasons.noBumpWorthy;
+        return { outcome: 'skip', skipReason };
     }
-    const parsedCommitCount = parsedCommits.length;
-    const unparseableCommits = unparseable.length > 0 ? unparseable : undefined;
-    const naturalBump = determineBumpType(parsedCommits, workTypes, versionPatterns);
-    const shouldRelease = naturalBump !== undefined || force;
-    if (!shouldRelease) {
-        const skipReason = commits.length === 0 ? skipReasons.noCommits : skipReasons.noBumpWorthy;
-        return { outcome: 'skip', skipReason, parsedCommitCount, unparseableCommits };
-    }
-    const releaseType = bumpOverride ?? naturalBump ?? 'patch';
-    return { outcome: 'release', releaseType, parsedCommitCount, unparseableCommits };
+    return { outcome: 'release', releaseType: bumpOverride ?? naturalBump ?? 'patch' };
 }

package/dist/esm/defaults.d.ts

@@ -6,7 +6,7 @@ export { WORK_TYPES_DATA } from './workTypesData.js';
  * Compose the rendered section heading for a work-type entry as `${emoji} ${label}`.
  *
  * Single-sourced here so callers (DEFAULT_WORK_TYPES derivation, devOnlySections
- * derivation, cliff-template drift comparison) cannot disagree on the composition rule.
+ * derivation) cannot disagree on the composition rule.
  */
 export declare function composeHeader(entry: {
     emoji: string;

package/dist/esm/defaults.js

@@ -13,6 +13,9 @@ function deriveDefaultWorkTypes() {
         if (entry.aliases.length > 0) {
             config.aliases = [...entry.aliases];
         }
+        if (entry.excludedFromChangelog === true) {
+            config.excludedFromChangelog = true;
+        }
         result[entry.key] = config;
     }
     return result;

package/dist/esm/determineBumpType.d.ts

@@ -1,14 +1,14 @@
-import type { ParsedCommit, ReleaseType, VersionPatterns, WorkTypeConfig } from './types.js';
+import type { ReleaseType, VersionPatterns, WorkTypeConfig } from './types.js';
+/** The part of a changelog item or parsed commit that decides its bump: its resolved work type and breaking flag. */
+export interface BumpSignal {
+    type: string;
+    breaking: boolean;
+}
 /**
- * Determines the overall bump type from a set of parsed commits.
+ * Determines the overall bump type from a set of changes, returning undefined when none has a known work type.
  *
- * Uses `versionPatterns` to decide which commit types trigger major/minor bumps.
- * The `'!'` sentinel in `versionPatterns.major` means "any breaking commit triggers major".
- * Any recognized commit type not listed in major or minor patterns defaults to patch.
- *
- * @param commits - The parsed commits to analyze.
- * @param workTypes - The work type configurations to verify recognized types.
- * @param versionPatterns - Rules for determining major and minor bumps.
- * @returns The determined release type, or undefined if no commits match a known work type.
+ * Uses `versionPatterns` to decide which types trigger major/minor bumps.
+ * The `'!'` sentinel in `versionPatterns.major` means "any breaking change triggers major".
+ * Any recognized type not listed in major or minor patterns defaults to patch.
  */
-export declare function determineBumpType(commits: readonly ParsedCommit[], workTypes: Record<string, WorkTypeConfig>, versionPatterns: VersionPatterns): ReleaseType | undefined;
+export declare function determineBumpType(changes: readonly BumpSignal[], workTypes: Record<string, WorkTypeConfig>, versionPatterns: VersionPatterns): ReleaseType | undefined;

package/dist/esm/determineBumpType.js

@@ -3,23 +3,22 @@ const RELEASE_PRIORITY = {
     minor: 2,
     patch: 1,
 };
-export function determineBumpType(commits, workTypes, versionPatterns) {
+export function determineBumpType(changes, workTypes, versionPatterns) {
     const knownTypes = new Set(Object.keys(workTypes));
     let highestPriority = 0;
     let result;
-    for (const commit of commits) {
-        if (commit.breaking && versionPatterns.major.includes('!')) {
+    for (const change of changes) {
+        if (change.breaking && versionPatterns.major.includes('!')) {
             return 'major';
         }
-        const commitType = commit.type;
-        if (!knownTypes.has(commitType)) {
+        if (!knownTypes.has(change.type)) {
             continue;
         }
         let bump;
-        if (versionPatterns.major.includes(commitType)) {
+        if (versionPatterns.major.includes(change.type)) {
             bump = 'major';
         }
-        else if (versionPatterns.minor.includes(commitType)) {
+        else if (versionPatterns.minor.includes(change.type)) {
             bump = 'minor';
         }
         else {

package/dist/esm/enumerateReleaseWindows.d.ts

@@ -0,0 +1,50 @@
+/** A commit as git records it, before any parsing or filtering. */
+export interface RawCommit {
+    /** The full 40-character hash, which `changelogOverrides` keys on. */
+    hash: string;
+    /** The first line, with a wrapped subject folded onto one line by git. */
+    subject: string;
+    /** The message after its first blank line, empty when the commit carries no body. */
+    body: string;
+    /** The raw commit message, subject and body together. */
+    message: string;
+}
+/** The commits one release contains, with the version and date under which they shipped. */
+export interface ReleaseWindow {
+    /** The tag name for a released window, the caller's unreleased-tag name for the newest one. */
+    version: string;
+    /** Unix seconds: the tag's creation date for a released window, the clock for the unreleased one. */
+    timestamp: number;
+    /** Oldest first. */
+    commits: RawCommit[];
+}
+/** Inputs for {@link enumerateReleaseWindows}. */
+export interface EnumerateReleaseWindowsOptions {
+    /** Git pathspecs restricting the enumeration to commits that touch them. */
+    paths?: readonly string[];
+    /** Tag prefixes to match as a union; a matching tag name continues with a digit. */
+    tagPrefixes: readonly string[];
+    /** The version that the unreleased window reports, such as the tag that the release being prepared will write. */
+    unreleasedTag: string;
+    /** Returns the current time in epoch milliseconds; dates the unreleased window. */
+    now?: () => number;
+}
+/**
+ * Splits the history reachable from HEAD into release windows, newest first.
+ *
+ * The newest window is always the unreleased one, empty when HEAD sits on a tag. Released
+ * windows follow in descending order, one per reachable tag matching a prefix. A tag that
+ * HEAD cannot reach is dropped.
+ *
+ * A commit belongs to the oldest matching tag that contains it, and to the unreleased window
+ * when no matching tag does. Containment is read from the ancestry graph rather than from a
+ * position in a linear walk, because a branch commit authored before a tag and merged after it
+ * is not in that tag's release.
+ *
+ * Three git invocations serve any number of tags: `git rev-list --topo-order --parents` for the
+ * ancestry graph, `git for-each-ref` for the tag names with their creation dates and target
+ * commits, and one path-filtered `git log` for the commits themselves.
+ *
+ * @throws If `tagPrefixes` is empty, or if any git invocation fails.
+ */
+export declare function enumerateReleaseWindows(options: EnumerateReleaseWindowsOptions): ReleaseWindow[];