@williamthorsen/release-kit 14.1.0 → 14.2.1

package/dist/esm/types.d.ts

@@ -64,6 +64,14 @@ export interface ChangelogJsonConfig {
     outputPath: string;
     devOnlySections: string[];
 }
+/** Configuration for the rendered `CHANGELOG.md`. */
+export interface ChangelogMarkdownConfig {
+    /**
+     * How many of the newest versioned sections `CHANGELOG.md` keeps; older sections go to per-major archive files
+     * under `changelogs/`. When omitted, `CHANGELOG.md` keeps every section.
+     */
+    keepVersions?: number;
+}
 /**
  * Editorial override for changelog items, keyed in the override file by `<hash>` (every item of the commit) or
  * `<hash>:<n>` (the item derived from the commit's `n`th change-record entry), where the hash is lowercase hex
@@ -87,7 +95,10 @@ export type ChangelogOverridesFile = Record<string, ChangelogOverride>;
 export interface ReleaseNotesConfig {
     shouldInjectIntoReadme: boolean;
 }
-/** Project-release config after merging defaults: `ProjectConfig` with every field required. */
+/**
+ * The composite release after merging defaults, declared by a `project` block or by a `releases` composite entry.
+ * Both are versioned by the root `package.json`.
+ */
 export interface ResolvedProjectConfig {
     /**
      * Resolved commit window for the project release: the git pathspecs that select which commits
@@ -96,6 +107,10 @@ export interface ResolvedProjectConfig {
     paths: string[];
     /** Resolved tag prefix for project-level tags. */
     tagPrefix: string;
+    /** Name that selects the composite; `undefined` for a `project` block, whose composite cannot be selected. */
+    name?: string;
+    /** Target names of the member workspaces; `undefined` means every retained workspace, as a `project` block has. */
+    members?: string[];
 }
 /** Identifies a dependency whose version bump triggered a propagated release. */
 export interface PropagationSource {
@@ -167,22 +182,12 @@ export interface ChangelogPreservation {
     /** Headings of the sections that do not name any version, which the regenerated file does not contain. */
     droppedUnversionedHeadings: string[];
 }
-/**
- * Result of preparing a single workspace (package) for release when a release was produced. `releaseType` is absent
- * for `--set-version`.
- */
-export interface ReleasedWorkspaceResult {
-    status: 'released';
-    /** Workspace name; absent in single-package mode, present in monorepo mode. */
-    name?: string;
+/** Fields of every target result: what `prepare` read from the target's unreleased window. */
+interface TargetResultFields {
+    /** Id of the target that the result describes. */
+    targetId: string;
     previousTag?: string;
     commitCount: number;
-    /**
-     * Count of commits that yield at least one changelog item; `0` when the unreleased window does
-     * not contain any commits or when none does. Absent for `--set-version` and propagation-only
-     * workspaces. `bumpOverride`, not this count, signals that the user supplied `--bump=X`.
-     */
-    parsedCommitCount?: number;
     /** Commits that do not yield any changelog item and are not accounted for by any exclusion or diagnostic. */
     unparseableCommits?: Commit[];
     /** Policy violations of the unreleased window's titles and change-record entries; omitted when none. */
@@ -191,14 +196,17 @@ export interface ReleasedWorkspaceResult {
     malformedBlocks?: MalformedChangeRecordBlock[];
     /** Change-record entries of the unreleased window whose type is undeclared; omitted when none. */
     undeclaredEntryTypes?: UndeclaredEntryType[];
-    /** Change-record entry scopes of the unreleased window that route their entry nowhere; omitted when none. */
-    unroutedEntryScopes?: UnroutedEntryScope[];
-    releaseType?: ReleaseType;
+}
+/** Fields of every released target result: the version, tag, and files of the release. */
+interface ReleaseFields {
     currentVersion: string;
     newVersion: string;
     tag: string;
     bumpedFiles: string[];
+    /** The `CHANGELOG.md`, then any archive files that the release writes. */
     changelogFiles: string[];
+    /** Archive files of the `CHANGELOG.md` that the release removes; omitted when it removes none. */
+    removedChangelogFiles?: string[];
     /** Release-notes preview files; present only under `--with-release-notes`. */
     previewFiles?: string[];
     /**
@@ -206,134 +214,125 @@ export interface ReleasedWorkspaceResult {
      * any.
      */
     changelogPreservation?: ChangelogPreservation[];
-    /** Raw commits of the workspace's unreleased window. */
-    commits?: Commit[];
     /**
-     * Present when `--bump=X` was supplied and selected the release level for this workspace, which
-     * distinguishes a bump-override release from a `--force` fallback or a natural-bump release.
+     * Present when `--bump=X` was supplied and selected the release level, which distinguishes a bump-override release
+     * from a `--force` fallback or a natural-bump release.
      */
     bumpOverride?: ReleaseType;
-    /** Dependencies that triggered a propagated bump (present for propagated or mixed workspaces). */
+}
+/** Fields of every package target result. */
+interface PackageResultFields extends TargetResultFields {
+    kind: 'package';
+    /** Workspace `dir`; absent for the single-package root. */
+    name?: string;
+    /** Change-record entry scopes of the unreleased window that route their entry nowhere; omitted when none. */
+    unroutedEntryScopes?: UnroutedEntryScope[];
+}
+/** Result of a package target that releases. `releaseType` is absent for `--set-version`. */
+export interface ReleasedPackageResult extends PackageResultFields, ReleaseFields {
+    status: 'released';
+    /**
+     * Count of commits that yield at least one changelog item; `0` when the unreleased window does
+     * not contain any commits or when none does. Absent for `--set-version` and propagation-only
+     * releases. `bumpOverride`, not this count, signals that the user supplied `--bump=X`.
+     */
+    parsedCommitCount?: number;
+    releaseType?: ReleaseType;
+    /** Raw commits of the package's unreleased window. */
+    commits?: Commit[];
+    /** Dependencies that triggered a propagated bump (present for propagated or mixed releases). */
     propagatedFrom?: PropagationSource[];
-    /** Present when propagation alone set the bump, the workspace's own commits having called for none. */
+    /** Present when propagation alone set the bump, the package's own commits having called for none. */
     propagatedOnly?: true;
-    /** Present when this workspace was written via `--set-version`; the explicit version that was applied. */
+    /** Present when the package was written via `--set-version`; the explicit version that was applied. */
     setVersion?: string;
 }
-/**
- * Result of preparing a single workspace (package) for release when the release was skipped: the diagnostic fields
- * and a human-readable `skipReason`, without the release-only fields.
- */
-export interface SkippedWorkspaceResult {
+/** Result of a package target that skips: the diagnostic fields and a human-readable `skipReason`. */
+export interface SkippedPackageResult extends PackageResultFields {
     status: 'skipped';
-    /** Workspace name; absent in single-package mode, present in monorepo mode. */
-    name?: string;
-    previousTag?: string;
-    commitCount: number;
     /**
      * Count of commits that yield at least one changelog item; `0` when the unreleased window does not contain any
      * commits or when none does.
      */
     parsedCommitCount: number;
-    /** Commits that do not yield any changelog item and are not accounted for by any exclusion or diagnostic. */
-    unparseableCommits?: Commit[];
-    /** Policy violations of the unreleased window's titles and change-record entries; omitted when none. */
-    policyViolations?: PolicyViolation[];
-    /** Commits of the unreleased window whose `change-record` block could not be read; omitted when none. */
-    malformedBlocks?: MalformedChangeRecordBlock[];
-    /** Change-record entries of the unreleased window whose type is undeclared; omitted when none. */
-    undeclaredEntryTypes?: UndeclaredEntryType[];
+    skipReason: string;
+}
+/** Fields of every directory target result. */
+interface DirectoryResultFields extends TargetResultFields {
+    kind: 'directory';
+    /** Name of the directory target. */
+    name: string;
     /** Change-record entry scopes of the unreleased window that route their entry nowhere; omitted when none. */
     unroutedEntryScopes?: UnroutedEntryScope[];
-    skipReason: string;
 }
 /**
- * Result of preparing a single workspace (package) for release.
- *
- * Discriminated by `status`: `ReleasedWorkspaceResult` for produced releases,
- * `SkippedWorkspaceResult` for skips.
+ * Result of a directory target that releases. A directory never propagates; `releaseType` and `parsedCommitCount` are
+ * absent for `--set-version`.
  */
-export type WorkspacePrepareResult = ReleasedWorkspaceResult | SkippedWorkspaceResult;
+export interface ReleasedDirectoryResult extends DirectoryResultFields, ReleaseFields {
+    status: 'released';
+    /**
+     * Count of commits that yield at least one changelog item; `0` when the unreleased window does not contain any
+     * commits or when none does.
+     */
+    parsedCommitCount?: number;
+    releaseType?: ReleaseType;
+    /** Raw commits of the directory's unreleased window. */
+    commits: Commit[];
+    /** Present when the directory was written via `--set-version`; the explicit version that was applied. */
+    setVersion?: string;
+}
+/** Result of a directory target that skips: the diagnostic fields and a human-readable `skipReason`. */
+export interface SkippedDirectoryResult extends DirectoryResultFields {
+    status: 'skipped';
+    /**
+     * Count of commits that yield at least one changelog item; `0` when the unreleased window does not contain any
+     * commits or when none does.
+     */
+    parsedCommitCount: number;
+    skipReason: string;
+}
 /**
- * Result of preparing a project-level release when a release was produced.
- *
- * Mirrors `ReleasedWorkspaceResult` without the workspace-only fields. Project releases never propagate and never
- * use `--set-version`, so `releaseType`, `parsedCommitCount`, and `commits` are required.
+ * Result of a composite target that releases. A composite never propagates and never takes `--set-version`, so
+ * `releaseType`, `parsedCommitCount`, and `commits` are required.
  */
-export interface ReleasedProjectResult {
+export interface ReleasedCompositeResult extends TargetResultFields, ReleaseFields {
     status: 'released';
-    previousTag?: string;
-    commitCount: number;
+    kind: 'composite';
     /**
      * Count of commits that yield at least one changelog item; `0` when the unreleased window does
-     * not contain any commits or when none does. `bumpOverride`, not a zero count, signals that the
-     * user supplied `--bump=X`.
+     * not contain any commits or when none does.
      */
     parsedCommitCount: number;
-    /** Commits that do not yield any changelog item and are not accounted for by any exclusion or diagnostic. */
-    unparseableCommits?: Commit[];
-    /** Policy violations of the unreleased window's titles and change-record entries; omitted when none. */
-    policyViolations?: PolicyViolation[];
-    /** Commits of the unreleased window whose `change-record` block could not be read; omitted when none. */
-    malformedBlocks?: MalformedChangeRecordBlock[];
-    /** Change-record entries of the unreleased window whose type is undeclared; omitted when none. */
-    undeclaredEntryTypes?: UndeclaredEntryType[];
     releaseType: ReleaseType;
-    currentVersion: string;
-    newVersion: string;
-    tag: string;
-    bumpedFiles: string[];
-    changelogFiles: string[];
-    /** Release-notes preview files; present only under `--with-release-notes`. */
-    previewFiles?: string[];
-    /**
-     * Per `CHANGELOG.md`, the existing sections that were kept or dropped; omitted when `prepare` did not keep or drop
-     * any.
-     */
-    changelogPreservation?: ChangelogPreservation[];
-    /** Raw commits in the project's contributing-paths window since the last project tag. */
+    /** Raw commits of the composite's commit window since its last tag. */
     commits: Commit[];
-    /**
-     * Present when `--bump=X` was supplied and selected the release level for the project, which
-     * distinguishes a bump-override release from a `--force` fallback or a natural-bump release.
-     */
-    bumpOverride?: ReleaseType;
 }
-/**
- * Result of preparing a project-level release when the release was skipped: the diagnostic fields and a
- * human-readable `skipReason`, without the release-only fields.
- */
-export interface SkippedProjectResult {
+/** Result of a composite target that skips: the diagnostic fields and a human-readable `skipReason`. */
+export interface SkippedCompositeResult extends TargetResultFields {
     status: 'skipped';
-    previousTag?: string;
-    commitCount: number;
+    kind: 'composite';
     /**
      * Count of commits that yield at least one changelog item; `0` when the unreleased window does not contain any
      * commits or when none does.
      */
     parsedCommitCount: number;
-    /** Commits that do not yield any changelog item and are not accounted for by any exclusion or diagnostic. */
-    unparseableCommits?: Commit[];
-    /** Policy violations of the unreleased window's titles and change-record entries; omitted when none. */
-    policyViolations?: PolicyViolation[];
-    /** Commits of the unreleased window whose `change-record` block could not be read; omitted when none. */
-    malformedBlocks?: MalformedChangeRecordBlock[];
-    /** Change-record entries of the unreleased window whose type is undeclared; omitted when none. */
-    undeclaredEntryTypes?: UndeclaredEntryType[];
     skipReason: string;
 }
-/**
- * Result of preparing a project-level release.
- *
- * Discriminated by `status`: `ReleasedProjectResult` for produced releases,
- * `SkippedProjectResult` for skips. `PrepareResult.project === undefined` means either that
- * the config does not declare a `project` block or that `--only` narrowed the run, which skips
- * the stage before it can produce a result; `prepare` reports the skip as a run warning instead.
- */
-export type ProjectPrepareResult = ReleasedProjectResult | SkippedProjectResult;
-/** Aggregate result of the prepare workflow for both single-package and monorepo modes. */
+/** Result of preparing a package target, discriminated by `status`. */
+export type PackagePrepareResult = ReleasedPackageResult | SkippedPackageResult;
+/** Result of preparing a directory target, discriminated by `status`. */
+export type DirectoryPrepareResult = ReleasedDirectoryResult | SkippedDirectoryResult;
+/** Result of preparing a composite target, discriminated by `status`. */
+export type CompositePrepareResult = ReleasedCompositeResult | SkippedCompositeResult;
+/** Result of preparing one release target, discriminated by `kind` and by `status`. */
+export type TargetPrepareResult = PackagePrepareResult | DirectoryPrepareResult | CompositePrepareResult;
+/** Result of a target that releases, of any kind. */
+export type ReleasedTargetResult = ReleasedPackageResult | ReleasedDirectoryResult | ReleasedCompositeResult;
+/** Aggregate result of the prepare workflow over a run's targets. */
 export interface PrepareResult {
-    workspaces: WorkspacePrepareResult[];
+    /** One result per target that the run prepared: the package targets in config order, then the composites. */
+    targets: TargetPrepareResult[];
     tags: string[];
     formatCommand?: {
         command: string;
@@ -341,8 +340,6 @@ export interface PrepareResult {
     } | undefined;
     /** Warnings reported during preparation (e.g., circular dependency detection). */
     warnings?: string[] | undefined;
-    /** Result of the project-level release stage (present only when `config.project` is configured and the stage ran). */
-    project?: ProjectPrepareResult | undefined;
 }
 /** Configuration for a single work type used in commit categorization. */
 export interface WorkTypeConfig {
@@ -416,12 +413,54 @@ export declare const projectConfigSchema: z.ZodObject<{
 }, z.core.$strict>;
 /** Consumer-facing project-release config (`project` block). Empty object opts in to project releases. */
 export type ProjectConfig = z.infer<typeof projectConfigSchema>;
+/**
+ * Schema for a `releases` entry that names the target at `path`: the discovered workspace there, or otherwise the
+ * directory, whose `tagPrefix` defaults to its basename followed by `-v`.
+ */
+export declare const pathReleaseSchema: z.ZodObject<{
+    path: z.ZodString;
+    tagPrefix: z.ZodOptional<z.ZodString>;
+    legacyIdentities: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        tagPrefix: z.ZodString;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+/** A `releases` entry that names the discovered workspace or the directory at `path`. */
+export type PathRelease = z.infer<typeof pathReleaseSchema>;
+/** Schema for a `releases` entry that declares a composite of the named targets. */
+export declare const compositeReleaseSchema: z.ZodObject<{
+    includes: z.ZodArray<z.ZodString>;
+    tagPrefix: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/** A `releases` entry that declares a composite of the named targets, versioned by the root `package.json`. */
+export type CompositeRelease = z.infer<typeof compositeReleaseSchema>;
+/**
+ * Schema for one `releases` entry: `false` excludes the discovered workspace of that name, and the object shapes name
+ * a workspace or a directory, or declare the composite. `validateConfig` relies on this branch order to report a failed entry.
+ */
+export declare const releaseEntrySchema: z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodObject<{
+    path: z.ZodString;
+    tagPrefix: z.ZodOptional<z.ZodString>;
+    legacyIdentities: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        tagPrefix: z.ZodString;
+    }, z.core.$strict>>>;
+}, z.core.$strict>, z.ZodObject<{
+    includes: z.ZodArray<z.ZodString>;
+    tagPrefix: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>]>;
+/** One `releases` entry, keyed in the config by the target's name. */
+export type ReleaseEntry = z.infer<typeof releaseEntrySchema>;
 /** Schema for the optional `changelogJson` block (input shape, all fields optional). */
 export declare const changelogJsonInputSchema: z.ZodObject<{
     enabled: z.ZodOptional<z.ZodBoolean>;
     outputPath: z.ZodOptional<z.ZodString>;
     devOnlySections: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strict>;
+/** Schema for the optional `changelogMarkdown` block (input shape, all fields optional). */
+export declare const changelogMarkdownInputSchema: z.ZodObject<{
+    keepVersions: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
 /** Schema for the optional `releaseNotes` block (input shape, all fields optional). */
 export declare const releaseNotesInputSchema: z.ZodObject<{
     shouldInjectIntoReadme: z.ZodOptional<z.ZodBoolean>;
@@ -446,13 +485,15 @@ export declare const breakingPolicyValueSchema: z.ZodEnum<{
 export declare const labelSpecSchema: z.ZodObject<{
     color: z.ZodString;
     description: z.ZodOptional<z.ZodString>;
+    aliases: z.ZodOptional<z.ZodArray<z.ZodString>>;
     archived: z.ZodOptional<z.ZodLiteral<true>>;
 }, z.core.$strict>;
 /**
- * A label's color, optional description, and optional archived mark; the name is the record key in
+ * A label's color, optional description, optional aliases, and optional archived mark; the name is the record key in
  * `repoLabels.labels`. An omitted description resolves to empty, which the generated labels file declares explicitly
- * so that a sync clears whatever description the label has on the repo. `archived: true` retires the label: The sync
- * archives it, keeping it on the issues and pull requests that have it.
+ * so that a sync clears whatever description the label has on the repo. Each alias names an existing label that the
+ * sync renames to this one in place, keeping it on the issues and pull requests that have it. `archived: true` retires
+ * the label: The sync archives it, keeping it on the issues and pull requests that have it.
  */
 export type LabelSpec = z.infer<typeof labelSpecSchema>;
 /**
@@ -462,14 +503,16 @@ export type LabelSpec = z.infer<typeof labelSpecSchema>;
  * Resolution is an ordered fold with last-writer-wins: presets in `extends` order, then the `labels` record,
  * in which an entry adds a label, replaces one that an earlier layer defined, or removes it (`null`). Names match
  * case-insensitively, as GitHub matches them, and the replacing layer's spelling wins.
- * Two misstatements are resolve-time errors (`resolveLabels`), not schema errors: `labels` keys that differ only in
- * case, and a `null` naming a label not defined by any earlier layer.
+ * Three misstatements are resolve-time errors (`resolveLabels`), not schema errors: `labels` keys that differ only in
+ * case, a `null` naming a label not defined by any earlier layer, and an alias that names a resolved label or repeats
+ * another alias.
  */
 export declare const repoLabelsSchema: z.ZodObject<{
     extends: z.ZodOptional<z.ZodArray<z.ZodString>>;
     labels: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodObject<{
         color: z.ZodString;
         description: z.ZodOptional<z.ZodString>;
+        aliases: z.ZodOptional<z.ZodArray<z.ZodString>>;
         archived: z.ZodOptional<z.ZodLiteral<true>>;
     }, z.core.$strict>>>>;
 }, z.core.$strict>;
@@ -486,6 +529,9 @@ export declare const releaseKitConfigSchema: z.ZodObject<{
         outputPath: z.ZodOptional<z.ZodString>;
         devOnlySections: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>>;
+    changelogMarkdown: z.ZodOptional<z.ZodObject<{
+        keepVersions: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
     formatCommand: z.ZodOptional<z.ZodString>;
     project: z.ZodOptional<z.ZodObject<{
         paths: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -494,11 +540,23 @@ export declare const releaseKitConfigSchema: z.ZodObject<{
     releaseNotes: z.ZodOptional<z.ZodObject<{
         shouldInjectIntoReadme: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>>;
+    releases: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodObject<{
+        path: z.ZodString;
+        tagPrefix: z.ZodOptional<z.ZodString>;
+        legacyIdentities: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            tagPrefix: z.ZodString;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>, z.ZodObject<{
+        includes: z.ZodArray<z.ZodString>;
+        tagPrefix: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>]>>>;
     repoLabels: z.ZodOptional<z.ZodObject<{
         extends: z.ZodOptional<z.ZodArray<z.ZodString>>;
         labels: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodObject<{
             color: z.ZodString;
             description: z.ZodOptional<z.ZodString>;
+            aliases: z.ZodOptional<z.ZodArray<z.ZodString>>;
             archived: z.ZodOptional<z.ZodLiteral<true>>;
         }, z.core.$strict>>>>;
     }, z.core.$strict>>;
@@ -555,10 +613,26 @@ export interface ParsedCommit {
     /** Whether this is a breaking change. */
     breaking: boolean;
 }
+/** A directory that a `releases` entry declares as a release target, as config merging resolves it. */
+export interface DirectoryConfig {
+    /** Name of the release target, its `releases` entry key. */
+    name: string;
+    /** Repo-relative POSIX path of the directory; `.` for the repo root. */
+    path: string;
+    /** Repo-relative JSON file whose `version` field the release bumps: the directory's `package.json` or `version.json`. */
+    versionFile: string;
+    /** Git pathspecs of the commit window; `undefined` for the repo root, whose window is the whole repo. */
+    paths?: string[];
+    tagPrefix: string;
+    /** Prior identities, whose tag prefixes are searched alongside `tagPrefix`; `undefined` equals the empty array. */
+    legacyIdentities?: LegacyIdentity[];
+}
 /** Per-workspace configuration for monorepo releases. */
 export interface WorkspaceConfig {
-    /** The package directory name (e.g., 'arrays'). Used for display and `--only` matching. */
+    /** The package directory name (e.g., 'arrays'), which names the workspace's release target by default. */
     dir: string;
+    /** Name of the workspace's release target when a `releases` entry renames it; `undefined` means `dir`. */
+    targetName?: string;
     /** The full scoped npm name from `package.json` (e.g., `'@williamthorsen/nmr-core'`). */
     name: string;
     /** The git tag prefix for this workspace (e.g., 'nmr-core-v'), derived from the unscoped `package.json` name. */
@@ -572,8 +646,6 @@ export interface WorkspaceConfig {
     isPublishable: boolean;
     /** Paths to package.json files to bump. */
     packageFiles: string[];
-    /** Directories in which to generate changelogs. */
-    changelogPaths: string[];
     /** Glob patterns passed to `git log -- <paths>` for commit filtering. */
     paths: string[];
     /**
@@ -583,52 +655,8 @@ export interface WorkspaceConfig {
      */
     legacyIdentities?: LegacyIdentity[];
 }
-/** Configuration for a monorepo release workflow with multiple workspaces. */
-export interface MonorepoReleaseConfig {
-    /** Ordered list of workspace configurations. */
-    workspaces: WorkspaceConfig[];
-    /** Work type configurations shared across all workspaces. Defaults to `DEFAULT_WORK_TYPES`. */
-    workTypes?: Record<string, WorkTypeConfig>;
-    /** Version bump patterns. Defaults to `DEFAULT_VERSION_PATTERNS`. */
-    versionPatterns?: VersionPatterns;
-    /**
-     * Per-canonical-type breaking-policy lookup. Defaults to `DEFAULT_BREAKING_POLICIES`.
-     * When provided, replaces the default entirely.
-     * Pass `{}` to disable enforcement (parser falls back to `'optional'` for missing types).
-     */
-    breakingPolicies?: Record<string, BreakingPolicy>;
-    /**
-     * Shell command to run after all changelogs are generated (e.g., 'pnpm run fmt').
-     * Modified file paths (package.json files and CHANGELOGs) are appended as space-separated
-     * arguments. Paths are repo-relative; file paths containing spaces are not supported.
-     */
-    formatCommand?: string;
-    /**
-     * Maps scope shorthand names to their canonical names.
-     * When a commit uses `shorthand|type: description` or `type(shorthand): description`,
-     * the shorthand is resolved to the canonical scope name before the parsed commit is returned.
-     */
-    scopeAliases?: Record<string, string>;
-    /** Controls structured changelog JSON generation. */
-    changelogJson: ChangelogJsonConfig;
-    /** Controls release notes consumption (README injection). */
-    releaseNotes: ReleaseNotesConfig;
-    /**
-     * Project-level release config. Present when the config declares a `project` block, in which case
-     * `prepare` runs a project-release stage after the per-workspace loop.
-     */
-    project?: ResolvedProjectConfig;
-}
-/** Monorepo config as seen by the prepare workflow, which does not read release-notes configuration. */
-export type MonorepoPrepareConfig = Omit<MonorepoReleaseConfig, 'releaseNotes'>;
-/** Configuration for the release workflow. */
-export interface ReleaseConfig {
-    /** The git tag prefix used to identify version tags (e.g., 'v'). */
-    tagPrefix: string;
-    /** Paths to package.json files to bump. */
-    packageFiles: string[];
-    /** Paths to directories in which to generate changelogs. */
-    changelogPaths: string[];
+/** Release settings that every target of a run shares, as config merging resolves them. */
+export interface ReleaseSettings {
     /** Work type configurations. Defaults to `DEFAULT_WORK_TYPES`. */
     workTypes?: Record<string, WorkTypeConfig>;
     /** Version bump patterns. Defaults to `DEFAULT_VERSION_PATTERNS`. */
@@ -653,8 +681,64 @@ export interface ReleaseConfig {
     scopeAliases?: Record<string, string>;
     /** Controls structured changelog JSON generation. */
     changelogJson: ChangelogJsonConfig;
+    /** Bounds the rendered `CHANGELOG.md`; `undefined` renders every version. */
+    changelogMarkdown?: ChangelogMarkdownConfig;
     /** Controls release notes consumption (README injection). */
     releaseNotes: ReleaseNotesConfig;
 }
-/** Single-package config as seen by the prepare workflow, which does not read release-notes configuration. */
-export type PrepareConfig = Omit<ReleaseConfig, 'releaseNotes'>;
+/** Fields that every kind of release target declares. */
+interface ReleaseTargetBase {
+    /** Selects the target, as `--only` does; never a source of tag names. */
+    id: string;
+    /** Prefix of the target's version tags (e.g., `'nmr-core-v'`). */
+    tagPrefix: string;
+    /** Prior identities, whose tag prefixes are searched alongside `tagPrefix`; `undefined` equals the empty array. */
+    legacyIdentities?: LegacyIdentity[];
+    /** Repo-relative files whose `version` field the release bumps. */
+    versionFiles: string[];
+    /** Repo-relative directory that contains the target's `CHANGELOG.md` and changelog JSON. */
+    changelogDir: string;
+    /** Git pathspecs that bound the target's commit window; `undefined` reads the whole repo. */
+    paths?: string[];
+    /** Whether a release of the target publishes to a registry. */
+    isPublishable: boolean;
+}
+/** A releasable package: a workspace of a monorepo, or the root of a single-package repo. */
+export interface PackageTarget extends ReleaseTargetBase {
+    kind: 'package';
+    /** The npm name from `package.json`; undefined for the single-package root. */
+    packageName?: string;
+    /** Repo-relative path to the package root (e.g., `packages/core`, or `.` for the single-package root). */
+    packagePath: string;
+    /** Whether the target is a monorepo workspace, whose change-record entries route by scope to its `id`. */
+    isWorkspace: boolean;
+}
+/** A releasable directory that isn't a workspace, versioned by its `package.json` or `version.json`. */
+export interface DirectoryTarget extends ReleaseTargetBase {
+    kind: 'directory';
+    /** Repo-relative path to the directory; `.` for the repo root, whose window is the whole repo. */
+    directoryPath: string;
+}
+/** A release that rolls up other targets, such as the project release of a monorepo. */
+export interface CompositeTarget extends ReleaseTargetBase {
+    kind: 'composite';
+    /** Ids of the package and directory targets that the composite rolls up. */
+    members: string[];
+}
+/** One releasable thing, whatever shape of config declared it. */
+export type ReleaseTarget = PackageTarget | DirectoryTarget | CompositeTarget;
+/** Configuration for a monorepo release workflow with multiple workspaces. */
+export interface MonorepoReleaseConfig extends ReleaseSettings {
+    /** Ordered list of workspace configurations. */
+    workspaces: WorkspaceConfig[];
+    /** Discovered workspaces that the config excludes, which tag resolution still matches; `undefined` means none. */
+    excludedWorkspaces?: WorkspaceConfig[];
+    /** Directories that the `releases` block declares as targets, in config order; `undefined` means none. */
+    directories?: DirectoryConfig[];
+    /**
+     * Project-level release config. Present when the config declares a `project` block, in which case
+     * `prepare` runs a project-release stage after the per-workspace loop.
+     */
+    project?: ResolvedProjectConfig;
+}
+export {};

package/dist/esm/types.js

@@ -25,6 +25,20 @@ export const projectConfigSchema = z
     tagPrefix: z.string().min(1).optional(),
 })
     .strict();
+export const pathReleaseSchema = z
+    .object({
+    path: z.string().min(1),
+    tagPrefix: z.string().min(1).optional(),
+    legacyIdentities: z.array(legacyIdentitySchema).optional(),
+})
+    .strict();
+export const compositeReleaseSchema = z
+    .object({
+    includes: z.array(z.string().min(1)).min(1),
+    tagPrefix: z.string().min(1).optional(),
+})
+    .strict();
+export const releaseEntrySchema = z.union([z.literal(false), pathReleaseSchema, compositeReleaseSchema]);
 export const changelogJsonInputSchema = z
     .object({
     enabled: z.boolean().optional(),
@@ -32,6 +46,11 @@ export const changelogJsonInputSchema = z
     devOnlySections: z.array(z.string()).optional(),
 })
     .strict();
+export const changelogMarkdownInputSchema = z
+    .object({
+    keepVersions: z.number().int().min(1).optional(),
+})
+    .strict();
 export const releaseNotesInputSchema = z
     .object({
     shouldInjectIntoReadme: z.boolean().optional(),
@@ -55,6 +74,7 @@ export const labelSpecSchema = z
     .object({
     color: z.string().min(1),
     description: z.string().optional(),
+    aliases: z.array(z.string().min(1)).min(1).optional(),
     archived: z.literal(true).optional(),
 })
     .strict();
@@ -68,9 +88,11 @@ export const releaseKitConfigSchema = z
     .object({
     breakingPolicies: z.record(z.string(), breakingPolicyValueSchema).optional(),
     changelogJson: changelogJsonInputSchema.optional(),
+    changelogMarkdown: changelogMarkdownInputSchema.optional(),
     formatCommand: z.string().min(1).optional(),
     project: projectConfigSchema.optional(),
     releaseNotes: releaseNotesInputSchema.optional(),
+    releases: z.record(z.string().min(1), releaseEntrySchema).optional(),
     repoLabels: repoLabelsSchema.optional(),
     retiredPackages: z.array(retiredPackageSchema).optional(),
     scopeAliases: z.record(z.string(), z.string()).optional(),