@williamthorsen/release-kit 11.0.0 → 13.0.0

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>;
@@ -6,55 +10,47 @@ export type LoadChangelogOverridesResult = {
     errors: string[];
 };
 /**
- * Load and validate the editorial overrides file at `path`.
- *
- * - Missing file resolves to an empty map (no-op default; matches "absent file → unchanged behavior").
- * - Malformed JSON, wrong top-level shape, or any per-entry validation failure surfaces as
- *   structured errors. Callers decide how to surface them.
- *
- * Returns either `{ overrides: Map }` on success or `{ errors: string[] }` on failure. Pure
- * except for the single file read; performs no other I/O.
+ * Loads and validates the editorial overrides file at `path`. A missing file yields an empty map; an unreadable file,
+ * malformed JSON, a wrong top-level shape, or any per-entry validation failure yields errors.
  */
 export declare function loadChangelogOverrides(path: string): LoadChangelogOverridesResult;
 /**
- * Validate a parsed override record. Returns the parsed `Map` along with any error messages.
+ * Validates a parsed override record, returning the valid overrides and an error message for each problem.
  *
- * Each error names the offending key (e.g. `overrides['abc']: 'audience' must be one of …`)
- * so the consumer can locate it in their override file.
+ * Each error names the offending key (e.g. `overrides['abc']: 'audience' must be one of …`) so that the user can find
+ * it in the override file.
  */
 export declare function validateChangelogOverrides(raw: unknown): {
     overrides: Map<string, ChangelogOverride>;
     errors: string[];
 };
-/**
- * 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
- * so single-package and monorepo flows produce identical warning text.
- */
+/** Splits 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;
+};
+/** Formats the warning for an override key that did not match any item in the changelog. */
 export declare function formatStaleOverrideKeyWarning(key: string): string;
 /**
- * Apply overrides to a `ChangelogEntry[]`, returning a new array. Pure: no mutation, no I/O.
+ * Applies overrides to changelog entries, returning new entries without mutating the input.
  *
- * Match algorithm: each override key is treated as a string-prefix against `ChangelogItem.hash`.
- * - 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.
- * - 2+ matches → error (ambiguous prefix).
+ * Each key's hash prefix is matched against the distinct `ChangelogItem.hash` values:
+ * - No match: The key is unmatched in this batch, and this function doesn't emit a warning.
+ * - One 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 doesn't resolve to any item is unmatched, so an ordinal key on a title-derived item
+ *   goes stale.
+ * - Several matches: an error (ambiguous prefix).
  *
- * `matchedKeys` lists the override keys that resolved to exactly one item 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
- * `formatStaleOverrideKeyWarning` after aggregating `matchedKeys` across all apply calls.
+ * 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.
  *
- * v1 audience semantics:
- * - `'skip'` removes the matched item from its containing section. Empty sections are pruned.
- *   Versions with zero sections still appear (matches existing "empty workspace" behavior).
- * - `'all'` and `'dev'` are validated out before reaching the applier.
+ * `matchedKeys` lists the keys that resolved to at least one item without error. The caller computes stale-key
+ * warnings, because in a monorepo a key may target a commit in another workspace: A key unmatched in one batch is not
+ * necessarily stale.
  *
- * Items without a `hash` (synthetic propagation entries) are never matched and pass through.
- *
- * The function does not throw; warnings/errors accumulate and are returned alongside the
- * transformed entries so the caller decides whether to abort or log-and-continue.
+ * An override whose audience is `'skip'` removes its item, and a section left empty is dropped; an entry left without
+ * sections is kept. An item without a `hash`, such as a synthetic propagation item, passes through unmatched. Errors
+ * are returned rather than thrown, and the caller decides whether to abort.
  */
 export declare function applyChangelogOverrides(entries: ChangelogEntry[], overrides: Map<string, ChangelogOverride>): {
     entries: ChangelogEntry[];
@@ -63,10 +59,8 @@ export declare function applyChangelogOverrides(entries: ChangelogEntry[], overr
     matchedKeys: string[];
 };
 /**
- * Resolve the conventional override-file path for a given scope root.
- *
- * `scopeRoot` is the directory at which a scope's other artifacts live (e.g., `'.'` for the
- * project, `'packages/foo'` for a workspace). The returned path is repo-relative.
+ * Resolves the conventional override-file path for a scope root: the directory in which a scope's other artifacts live
+ * (e.g., `'.'` for the project, `'packages/foo'` for a workspace). The returned path is repo-relative.
  */
 export declare function resolveOverridePath(scopeRoot: string): string;
 /** Result of {@link loadOverridesForScopes}: per-scope maps plus accumulated load/validation errors. */
@@ -79,40 +73,27 @@ export interface LoadOverridesForScopesResult {
     errors: string[];
 }
 /**
- * Load and validate every requested override file in one pass.
- *
- * Iterates the configured scope roots, calls {@link loadChangelogOverrides} for each, and
- * aggregates errors across all files (rather than throwing on the first failure) so a
- * consumer who edits multiple files at once sees every problem in one report. Missing files
- * resolve to empty maps — matches the existing single-file behavior.
- *
- * The caller is expected to surface a combined error when `errors.length > 0` and abort the
- * release before any workspace begins writing.
+ * Loads and validates the override file of every requested scope, collecting the errors of all files rather than
+ * stopping at the first, so that a user who edits several files sees every problem in one report. A missing file
+ * yields an empty map.
  */
 export declare function loadOverridesForScopes(scopes: {
     project?: string;
     workspaces?: string[];
 }): LoadOverridesForScopesResult;
 /**
- * Compose root and workspace override maps into a single effective map for one workspace.
+ * Composes root and workspace override maps into the effective map for one workspace, without mutating either.
  *
- * 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}.
- *
- * Pure: never mutates inputs.
+ * A workspace key identical to a root key replaces the root entry entirely, without a field-level merge. Distinct keys
+ * that resolve to the same item do not shadow each other here: {@link applyChangelogOverrides} reports them as
+ * overlapping.
  */
 export declare function composeOverrides(rootEntries: Map<string, ChangelogOverride>, workspaceEntries: Map<string, ChangelogOverride> | undefined): Map<string, ChangelogOverride>;
 /**
- * Shared override-application context threaded through the per-workspace and project apply
- * sites. Bundles the loaded per-scope maps with the run-scoped warning aggregators so each
- * call site can both consume the maps it needs and report into the same warning channel.
+ * The loaded per-scope override maps and the run's warning aggregators, shared by every apply of a prepare run.
  *
- * `globalMatchedRootKeys` tracks ROOT keys matched in any apply call. Workspace-sourced
- * matched keys are not added here — they're tracked locally per workspace because their
- * stale-key semantics are local (a workspace key that doesn't match in its own workspace is
- * unambiguously stale and is warned immediately, not aggregated to end-of-run).
+ * `globalMatchedRootKeys` contains the root keys matched in any apply. Workspace keys are not added: A workspace key
+ * that matches nothing in its own workspace is stale, and it is warned about at once rather than at the end of the run.
  */
 export interface OverrideContext {
     project: Map<string, ChangelogOverride>;
@@ -121,18 +102,25 @@ export interface OverrideContext {
     globalMatchedRootKeys: Set<string>;
 }
 /**
- * Load all per-scope override files (root + every workspace) in one upfront pass, validate
- * them, and bundle the results with run-scoped warning aggregators. Aborts the release with
- * a clear error when any file is malformed — checked-in editorial config that does not parse
- * is a bug, and we want the prepare run to fail before any workspace begins writing.
+ * Loads and validates the override files of the root and every workspace, and bundles them with empty warning
+ * aggregators. Throws if any file fails to load, so that a malformed checked-in override file stops `prepare` before
+ * any workspace writes.
  */
 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. */
+    /**
+     * Path to the override file, used to load the file and to attribute findings. A relative path resolves against the
+     * process working directory.
+     */
     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,56 +129,47 @@ 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).
+     * Omit when the project file doesn't exist.
      */
     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. */
+/**
+ * Result of {@link validateAllChangelogOverrides}: aggregated errors and warnings, each prefixed with the path of the
+ * file to which it pertains.
+ */
 export interface ValidateAllChangelogOverridesResult {
     errors: string[];
     warnings: string[];
 }
 /**
- * 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
- * (programmatic library callers, future composite checks) wrap this with discovery and I/O.
+ * Validates every override file against the items of its scopes and returns the aggregated findings. It reads the
+ * override files but doesn't collect any items: The caller supplies each scope's items.
+ *
+ * Items built by `buildChangelogEntries`, as `release-kit prepare` builds them, yield the matches that `prepare`
+ * computes, tier asymmetry included: A workspace-tier key is stale when it matches nothing in its own workspace, and a
+ * root-tier key only when it matches nothing in any scope, the project release window included.
  *
- * When invoked via the standard `validateOverridesCommand` entry point, each scope's
- * `hashes` 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.
+ * Every returned string is prefixed with the path of the override file to which it pertains.
  *
- * Every returned string is prefixed with the relative override-file path it pertains to so
- * consumers can locate the offending file without further structuring.
+ * A relative `filePath`, in any scope, resolves against the process working directory, not against the repo root.
+ * A caller running from elsewhere passes absolute paths or changes directory first.
  */
 export declare function validateAllChangelogOverrides(inputs: ValidateAllChangelogOverridesInputs): ValidateAllChangelogOverridesResult;
 /**
- * Apply the composed (root + workspace) override map to a workspace's changelog entries and
- * report stale-key warnings tier-by-tier.
- *
- * The composed map is applied in a single {@link applyChangelogOverrides} call. Matched keys
- * are demultiplexed by source via `Map.has` lookups on the original (uncomposed) maps so the
- * stale-key semantics stay tier-aware:
- *
- * - Workspace-sourced keys (those present in the per-workspace map, regardless of whether
- *   the root map also has the same byte-equal key) that did NOT match are unambiguously
- *   stale in their own apply context — push an immediate stale warning naming the key.
- * - Root-sourced matched keys (present in root, absent from this workspace's map) are added
- *   to `globalMatchedRootKeys` so the orchestrator's end-of-run loop can dedupe across
- *   batches and warn only on root keys that matched nowhere.
+ * Applies the composed root and workspace override map to a workspace's changelog entries, and records stale keys by
+ * tier.
  *
- * Throws when any apply call surfaces an error (e.g. ambiguous prefix). Returns the applied
- * result so the caller can consume `applied.entries` for downstream rendering.
+ * A workspace key that matched nothing, whether or not the root map has the same key, is stale, and it is warned about
+ * at once. The function adds each root key that matched without being shadowed to `globalMatchedRootKeys`, from which
+ * the caller warns, at the end of the run, about the root keys that matched nowhere. Throws if applying reports any
+ * error, such as an ambiguous prefix.
  */
 export declare function applyWorkspaceOverrides(newEntries: ChangelogEntry[], workspacePath: string, overrideContext: OverrideContext): ReturnType<typeof applyChangelogOverrides>;

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,36 @@
+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 without a 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 that its type
+ * declares.
+ *
+ * The function passes `options` to the parse, so a policy violation is reported for every ticketed commit whose type
+ * resolves, excluded types included.
+ */
+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 is never included in 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;