@williamthorsen/release-kit 10.9.0 → 12.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>;
@@ -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.

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/configFlagSchema.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The `--config` flag, shared by every subcommand that reads the config file.
+ *
+ * Spread into a subcommand's own schema rather than repeated, so that seven subcommands cannot drift to seven
+ * spellings of one flag.
+ */
+export declare const configFlagSchema: {
+    config: {
+        long: string;
+        type: "string";
+    };
+};

package/dist/esm/configFlagSchema.js

@@ -0,0 +1,3 @@
+export const configFlagSchema = {
+    config: { long: '--config', type: 'string' },
+};

package/dist/esm/createGithubReleaseCommand.js

@@ -1,19 +1,23 @@
 import { parseArgsOrExit, reportError } from '@williamthorsen/nmr-core';
 import { describeError } from '@williamthorsen/toolbelt.errors';
+import { configFlagSchema } from "./configFlagSchema.js";
 import { createGithubReleases } from "./createGithubRelease.js";
 import { formatPrivateSkip } from "./formatPrivateSkip.js";
+import { assertConfigUsable } from "./loadValidatedConfig.js";
 import { parseRequestedTags } from "./parseRequestedTags.js";
 import { resolveCommandTags } from "./resolveCommandTags.js";
 import { resolveReleaseNotesConfig } from "./resolveReleaseNotesConfig.js";
 const createGithubReleaseFlagSchema = {
+    ...configFlagSchema,
     dryRun: { long: '--dry-run', type: 'boolean' },
     tags: { long: '--tags', type: 'string' },
 };
 export async function createGithubReleaseCommand(argv, styles) {
     const parsed = parseArgsOrExit(argv, createGithubReleaseFlagSchema);
     const { dryRun } = parsed.flags;
+    await assertConfigUsable(styles.stderr, parsed.flags.config);
     const requestedTags = parseRequestedTags(parsed.flags.tags);
-    const resolvedTags = await resolveCommandTags(requestedTags);
+    const resolvedTags = resolveCommandTags(requestedTags);
     const publishableTags = resolvedTags.filter((resolvedTag) => resolvedTag.isPublishable);
     for (const resolvedTag of resolvedTags) {
         if (!resolvedTag.isPublishable) {
@@ -24,7 +28,7 @@ export async function createGithubReleaseCommand(argv, styles) {
         return;
     }
     const { changelogJsonOutputPath, sectionOrder } = await resolveReleaseNotesConfig(styles.stderr, {
-        strictLoad: true,
+        ...(parsed.flags.config !== undefined && { configPath: parsed.flags.config }),
     });
     let outcome;
     try {

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;