@williamthorsen/release-kit 14.2.2 → 14.2.3

package/dist/esm/changelogOverrides.d.ts

@@ -1,68 +1,39 @@
+import { applyChangelogOverrides } from './applyChangelogOverrides.js';
 import type { ChangelogEntry, ChangelogOverride } 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>;
-} | {
-    errors: string[];
-};
 /**
- * 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.
+ * Applies the composed root and workspace override map to a target's changelog entries, and records stale keys by
+ * tier. A target without a workspace override file, such as the project, passes `undefined` for `workspacePath` and
+ * applies the root tier alone.
+ *
+ * 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 loadChangelogOverrides(path: string): LoadChangelogOverridesResult;
+export declare function applyWorkspaceOverrides(newEntries: ChangelogEntry[], workspacePath: string | undefined, overrideContext: OverrideContext): ReturnType<typeof applyChangelogOverrides>;
 /**
- * Validates a parsed override record, returning the valid overrides and an error message for each problem.
+ * Composes root and workspace override maps into the effective map for one workspace, without mutating either.
  *
- * 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.
+ * 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 validateChangelogOverrides(raw: unknown): {
-    overrides: Map<string, ChangelogOverride>;
-    errors: string[];
-};
-/** 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;
+export declare function composeOverrides(rootEntries: Map<string, ChangelogOverride>, workspaceEntries: Map<string, ChangelogOverride> | undefined): Map<string, ChangelogOverride>;
 /**
- * Applies overrides to changelog entries, returning new entries without mutating the input.
- *
- * 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).
- *
- * 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 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.
- *
- * 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.
+ * Loads and validates the override files of the root and of every workspace at the given repo-relative paths, 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 applyChangelogOverrides(entries: ChangelogEntry[], overrides: Map<string, ChangelogOverride>): {
-    entries: ChangelogEntry[];
-    warnings: string[];
-    errors: string[];
-    matchedKeys: string[];
-};
+export declare function createOverrideContext(workspacePaths: readonly string[]): OverrideContext;
 /**
- * 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.
+ * 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 resolveOverridePath(scopeRoot: string): string;
+export declare function loadOverridesForScopes(scopes: {
+    project?: string;
+    workspaces?: string[];
+}): LoadOverridesForScopesResult;
 /** Result of {@link loadOverridesForScopes}: per-scope maps plus accumulated load/validation errors. */
 export interface LoadOverridesForScopesResult {
     /** Project-tier (root) overrides. Empty map when the project file is absent. */
@@ -72,23 +43,6 @@ export interface LoadOverridesForScopesResult {
     /** All load and validation errors across every requested scope, prefixed with the offending file path. */
     errors: string[];
 }
-/**
- * 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;
-/**
- * Composes root and workspace override maps into the effective map for one workspace, without mutating either.
- *
- * 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>;
 /**
  * The loaded per-scope override maps and the run's warning aggregators, shared by every apply of a prepare run.
  *
@@ -102,75 +56,7 @@ export interface OverrideContext {
     globalMatchedRootKeys: Set<string>;
 }
 /**
- * Loads and validates the override files of the root and of every workspace at the given repo-relative paths, 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(workspacePaths: readonly string[]): 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, used to load the file and to attribute findings. A relative path resolves against the
-     * process working directory.
-     */
-    filePath: 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 {
-    /**
-     * Project-tier scope (the override file at the repo root).
-     *
-     * 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 `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 the project file doesn't exist.
-     */
-    project?: {
-        filePath: string;
-        items?: readonly OverrideTargetItem[];
-    };
-    /** 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 path of the
- * file to which it pertains.
- */
-export interface ValidateAllChangelogOverridesResult {
-    errors: string[];
-    warnings: string[];
-}
-/**
- * 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.
- *
- * Every returned string is prefixed with the path of the override file to which it pertains.
- *
- * 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;
-/**
- * Applies the composed root and workspace override map to a target's changelog entries, and records stale keys by
- * tier. A target without a workspace override file, such as the project, passes `undefined` for `workspacePath` and
- * applies the root tier alone.
- *
- * 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.
+ * 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 applyWorkspaceOverrides(newEntries: ChangelogEntry[], workspacePath: string | undefined, overrideContext: OverrideContext): ReturnType<typeof applyChangelogOverrides>;
+export declare function resolveOverridePath(scopeRoot: string): string;