@williamthorsen/release-kit 14.1.0 → 14.2.0

package/dist/esm/validateConfig.js

@@ -9,12 +9,13 @@ export function validateConfig(raw) {
     if (!parseResult.success) {
         return {
             config: {},
-            errors: [...deprecationErrors, ...parseResult.error.issues.map(formatZodIssue)],
+            errors: [...deprecationErrors, ...parseResult.error.issues.flatMap((issue) => formatZodIssue(issue, cleaned))],
             warnings: [],
         };
     }
     const config = parseResult.data;
     const errors = [...deprecationErrors];
+    detectReleasesConflicts(config, errors);
     detectLegacyIdentityDuplicates(config, errors);
     detectRetiredPackageDuplicates(config, errors);
     detectRetiredVsLegacyCollisions(config, errors);
@@ -57,12 +58,31 @@ function preprocessDeprecatedKeys(raw) {
             return wsCopy;
         });
     }
+    if (isRecord(cleaned['releases'])) {
+        const releasesCopy = { ...cleaned['releases'] };
+        for (const [name, entry] of Object.entries(releasesCopy)) {
+            if (!isRecord(entry) || !Object.hasOwn(entry, 'paths'))
+                continue;
+            errors.push(`releases.${name}: 'paths' is not supported; a package's or a directory's commit window is its path, and a composite's is the union of its members' windows`);
+            const entryCopy = { ...entry };
+            delete entryCopy['paths'];
+            releasesCopy[name] = entryCopy;
+        }
+        cleaned['releases'] = releasesCopy;
+    }
     return { cleaned, deprecationErrors: errors };
 }
-function formatZodIssue(issue) {
+function formatZodIssue(issue, input) {
+    if (issue.code === 'invalid_union' && issue.path.length === 2 && issue.path[0] === 'releases') {
+        const branchIssues = issue.errors[selectReleaseEntryBranch(readAtPath(input, issue.path))];
+        if (branchIssues === undefined) {
+            return [`${renderPath(issue.path)}: ${RELEASE_ENTRY_SHAPES}`];
+        }
+        return branchIssues.flatMap((branchIssue) => formatZodIssue({ ...branchIssue, path: [...issue.path, ...branchIssue.path] }, input));
+    }
     const path = renderPath(issue.path);
     const message = customizeMessage(issue);
-    return path === '' ? message : `${path}: ${message}`;
+    return [path === '' ? message : `${path}: ${message}`];
 }
 function customizeMessage(issue) {
     if (issue.code === 'too_small' && issue.origin === 'string') {
@@ -70,6 +90,7 @@ function customizeMessage(issue) {
     }
     return issue.message;
 }
+const RELEASE_ENTRY_SHAPES = 'must be false, { path, tagPrefix?, legacyIdentities? }, or { includes, tagPrefix? }';
 function renderPath(path) {
     let rendered = '';
     for (const segment of path) {
@@ -86,16 +107,12 @@ function renderPath(path) {
     return rendered;
 }
 function detectLegacyIdentityDuplicates(config, errors) {
-    if (config.workspaces === undefined)
-        return;
-    for (const [wsIndex, workspace] of config.workspaces.entries()) {
-        if (workspace.legacyIdentities === undefined)
-            continue;
+    for (const { label, legacyIdentities } of listLegacyIdentityDeclarations(config)) {
         const seen = new Set();
-        for (const [entryIndex, identity] of workspace.legacyIdentities.entries()) {
+        for (const [entryIndex, identity] of legacyIdentities.entries()) {
             const key = `${identity.name}\0${identity.tagPrefix}`;
             if (seen.has(key)) {
-                errors.push(`workspaces[${wsIndex}].legacyIdentities[${entryIndex}]: duplicate identity (name='${identity.name}', tagPrefix='${identity.tagPrefix}')`);
+                errors.push(`${label}.legacyIdentities[${entryIndex}]: duplicate identity (name='${identity.name}', tagPrefix='${identity.tagPrefix}')`);
             }
             seen.add(key);
         }
@@ -114,22 +131,64 @@ function detectRetiredPackageDuplicates(config, errors) {
     }
 }
 function detectRetiredVsLegacyCollisions(config, errors) {
-    if (config.retiredPackages === undefined || config.workspaces === undefined)
+    if (config.retiredPackages === undefined)
         return;
-    const legacyPrefixToWorkspace = new Map();
-    for (const workspace of config.workspaces) {
-        if (workspace.legacyIdentities === undefined)
-            continue;
-        for (const identity of workspace.legacyIdentities) {
-            if (!legacyPrefixToWorkspace.has(identity.tagPrefix)) {
-                legacyPrefixToWorkspace.set(identity.tagPrefix, workspace.dir);
+    const legacyPrefixToOwner = new Map();
+    for (const { owner, legacyIdentities } of listLegacyIdentityDeclarations(config)) {
+        for (const identity of legacyIdentities) {
+            if (!legacyPrefixToOwner.has(identity.tagPrefix)) {
+                legacyPrefixToOwner.set(identity.tagPrefix, owner);
             }
         }
     }
     for (const [index, retired] of config.retiredPackages.entries()) {
-        const collidingDir = legacyPrefixToWorkspace.get(retired.tagPrefix);
-        if (collidingDir !== undefined) {
-            errors.push(`retiredPackages[${index}]: tagPrefix '${retired.tagPrefix}' collides with a declared legacyIdentities[].tagPrefix on workspace '${collidingDir}'`);
+        const collidingOwner = legacyPrefixToOwner.get(retired.tagPrefix);
+        if (collidingOwner !== undefined) {
+            errors.push(`retiredPackages[${index}]: tagPrefix '${retired.tagPrefix}' collides with a declared legacyIdentities[].tagPrefix on ${collidingOwner}`);
         }
     }
 }
+function detectReleasesConflicts(config, errors) {
+    if (config.releases === undefined)
+        return;
+    const legacyBlocks = [
+        ...(config.workspaces === undefined ? [] : ['workspaces']),
+        ...(config.project === undefined ? [] : ['project']),
+    ];
+    if (legacyBlocks.length === 0)
+        return;
+    errors.push(`releases cannot be combined with ${legacyBlocks.join(' or ')}; declare every target under releases, or remove releases`);
+}
+function listLegacyIdentityDeclarations(config) {
+    const fromWorkspaces = (config.workspaces ?? []).flatMap((workspace, index) => workspace.legacyIdentities === undefined
+        ? []
+        : [
+            {
+                label: `workspaces[${index}]`,
+                owner: `workspace '${workspace.dir}'`,
+                legacyIdentities: workspace.legacyIdentities,
+            },
+        ]);
+    const fromReleases = Object.entries(config.releases ?? {}).flatMap(([name, entry]) => entry === false || !('path' in entry) || entry.legacyIdentities === undefined
+        ? []
+        : [{ label: `releases.${name}`, owner: `release '${name}'`, legacyIdentities: entry.legacyIdentities }]);
+    return [...fromWorkspaces, ...fromReleases];
+}
+function readAtPath(input, path) {
+    let value = input;
+    for (const segment of path) {
+        if (!isRecord(value) || typeof segment === 'symbol')
+            return undefined;
+        value = value[String(segment)];
+    }
+    return value;
+}
+function selectReleaseEntryBranch(entry) {
+    if (!isRecord(entry))
+        return -1;
+    if (Object.hasOwn(entry, 'includes'))
+        return 2;
+    if (Object.hasOwn(entry, 'path'))
+        return 1;
+    return -1;
+}

package/dist/esm/validateOverridesCommand.d.ts

@@ -2,7 +2,7 @@ import { type OutputStyle, type StreamStyles } from '@williamthorsen/nmr-core';
 import { type ReleaseHistoryConfig } from './buildChangelogEntries.js';
 import { type ValidateAllChangelogOverridesInputs, type ValidateAllChangelogOverridesResult } from './changelogOverrides.js';
 import { type WorkspaceDiscovery } from './discoverWorkspaces.js';
-import { type GenerateChangelogOptions } from './generateChangelogs.js';
+import type { GenerateChangelogOptions } from './generateChangelogs.js';
 import { type LoadValidatedConfigResult } from './loadValidatedConfig.js';
 import type { ChangelogEntry } from './types.js';
 /**

package/dist/esm/validateOverridesCommand.js

@@ -3,9 +3,9 @@ import { describeError } from '@williamthorsen/toolbelt.errors';
 import { buildChangelogEntries } from "./buildChangelogEntries.js";
 import { resolveOverridePath, validateAllChangelogOverrides, } from "./changelogOverrides.js";
 import { describeEmptyWorkspace, discoverWorkspaces } from "./discoverWorkspaces.js";
-import { getAllTagPrefixes } from "./generateChangelogs.js";
-import { mergeMonorepoConfig, mergeSinglePackageConfig, readRootPackageVersion } from "./loadConfig.js";
 import { loadValidatedConfig } from "./loadValidatedConfig.js";
+import { describeHistoryWindow } from "./prepareTarget.js";
+import { isSinglePackageTargets, resolveReleaseTargets } from "./resolveReleaseTargets.js";
 const SYNTHETIC_VALIDATE_TAG = 'validate-only';
 export async function validateOverridesCommand(styles, configPath, dependencies = {}) {
     const discover = dependencies.discoverWorkspaces ?? discoverWorkspaces;
@@ -32,10 +32,7 @@ export async function validateOverridesCommand(styles, configPath, dependencies
     }
     let inputs;
     try {
-        inputs =
-            workspace.kind === 'single-package'
-                ? buildSinglePackageInputs(userConfig, buildEntries)
-                : buildMonorepoInputs(workspace.packageDirs, userConfig, buildEntries);
+        inputs = buildValidationInputs(resolveReleaseTargets(userConfig, workspace), buildEntries);
     }
     catch (error) {
         return { exitCode: 2, message: formatErrorLine(`Failed to resolve overrides scope: ${describeError(error)}`) };
@@ -89,30 +86,22 @@ function formatConfigProblem(problem) {
         ? formatErrorLine(`Failed to load config: ${problem.message}`)
         : `Invalid config:\n  - ${problem.errors.join('\n  - ')}`;
 }
-function buildSinglePackageInputs(userConfig, buildEntries) {
-    const config = mergeSinglePackageConfig(userConfig);
-    const items = flattenEntriesToItems(buildEntries(config, { tagPrefixes: [config.tagPrefix] }));
-    return {
-        project: { filePath: resolveOverridePath('.'), items },
-    };
-}
-function buildMonorepoInputs(discoveredPaths, userConfig, buildEntries) {
-    const rootPackage = readRootPackageVersion();
-    const config = mergeMonorepoConfig(discoveredPaths, userConfig, rootPackage);
-    const workspaces = config.workspaces.map((workspace) => {
-        const options = { tagPrefixes: getAllTagPrefixes(workspace), paths: workspace.paths, workspaceDir: workspace.dir };
-        return {
-            filePath: resolveOverridePath(workspace.workspacePath),
-            items: flattenEntriesToItems(buildEntries(config, options)),
-        };
-    });
-    const project = config.project;
+function buildValidationInputs({ targets, settings }, buildEntries) {
     const projectScope = {
         filePath: resolveOverridePath('.'),
     };
-    if (project !== undefined) {
-        const options = { tagPrefixes: [project.tagPrefix], paths: project.paths };
-        projectScope.items = flattenEntriesToItems(buildEntries(config, options));
+    const workspaces = [];
+    for (const target of targets) {
+        const items = flattenEntriesToItems(buildEntries(settings, describeHistoryWindow(target)));
+        if (target.kind === 'package' && target.isWorkspace) {
+            workspaces.push({ filePath: resolveOverridePath(target.packagePath), items });
+        }
+        else if (target.kind === 'directory' && target.directoryPath !== '.') {
+            workspaces.push({ filePath: resolveOverridePath(target.directoryPath), items });
+        }
+        else {
+            projectScope.items = items;
+        }
     }
-    return { project: projectScope, workspaces };
+    return isSinglePackageTargets(targets) ? { project: projectScope } : { project: projectScope, workspaces };
 }

package/docs/api.md

@@ -1,73 +1,40 @@
 # Programmatic API
 
-How to build a release config by hand with `deriveWorkspaceConfig()`, the script-based approach that predates the CLI, and the workspace records that `resolveReleaseTags` takes.
+The package exports two entries: `.`, which validates changelog override files, and `./config`, which types a config file. Every other module is internal, and the CLI is the supported way to release.
 
-## Using `deriveWorkspaceConfig()` for manual configuration
+## `./config`: typing a config file
 
-For a `MonorepoReleaseConfig` built manually (e.g., for the legacy script-based approach), the exported `deriveWorkspaceConfig()` helper creates a `WorkspaceConfig` from a workspace-relative path. It reads the workspace's `package.json` to derive the tag prefix from the package name:
+`defineConfig()` returns its argument unchanged, typed as a `ReleaseKitConfig`. The entry also exports the `ReleaseKitConfig`, `RepoLabelsConfig`, and `LabelSpec` types.
 
 ```typescript
-import { deriveWorkspaceConfig } from '@williamthorsen/release-kit';
+// .config/release-kit.config.ts
+import { defineConfig } from '@williamthorsen/release-kit/config';
 
-// packages/arrays/package.json contains `"name": "@scope/arrays"`
-deriveWorkspaceConfig('packages/arrays');
-// => {
-//   dir: 'arrays',
-//   name: '@scope/arrays',
-//   tagPrefix: 'arrays-v',
-//   workspacePath: 'packages/arrays',
-//   packageFiles: ['packages/arrays/package.json'],
-//   changelogPaths: ['packages/arrays'],
-//   paths: ['packages/arrays/**'],
-// }
-```
-
-`dir` is the basename of the workspace path and is the stable internal identifier used by `--only`, `WorkspaceOverride.dir`, and the dependency graph. `tagPrefix` is derived from the unscoped `package.json` `name` (with any leading `@scope/` stripped), so tags reflect the package identity rather than the directory layout. For example, a workspace at `packages/core` with `"name": "@williamthorsen/nmr-core"` produces `tagPrefix: 'nmr-core-v'`, yielding tags like `nmr-core-v1.3.0`.
-
-The workspace's `package.json` must declare a non-empty `name` field; `deriveWorkspaceConfig()` throws otherwise. If two workspaces produce the same `tagPrefix` (because their unscoped names collide), `mergeMonorepoConfig()` throws and names the colliding workspaces so that the developer can rename one.
-
-## Legacy script-based approach
-
-The CLI-driven approach is recommended for new setups. The script-based approach (using `runReleasePrepare` with a manually maintained config) is still supported for backward compatibility.
-
-```typescript
-// .github/scripts/release.config.ts
-import type { MonorepoReleaseConfig } from '@williamthorsen/release-kit';
-import { deriveWorkspaceConfig } from '@williamthorsen/release-kit';
-
-export const config: MonorepoReleaseConfig = {
-  workspaces: [deriveWorkspaceConfig('packages/arrays'), deriveWorkspaceConfig('packages/strings')],
+export default defineConfig({
   formatCommand: 'npx prettier --write',
-};
+});
 ```
 
-```typescript
-// .github/scripts/release-prepare.ts
-import { runReleasePrepare } from '@williamthorsen/release-kit';
-import { config } from './release.config.ts';
-
-runReleasePrepare(config);
-```
-
-The key difference: The script-based approach requires manually listing every workspace, while the CLI auto-discovers them from `pnpm-workspace.yaml`.
+The entry does not import any value, so a config load does not pull in the rest of the package. [Configuration](configuration.md) describes the fields.
 
-## `resolveReleaseTags` takes workspaces; `WorkspaceConfig` requires `workspacePath`
+## `.`: validating override files
 
-Tag resolution is now driven by workspace records rather than a caller-supplied directory map, so `resolveReleaseTags` can report both the workspace `dir` and its `workspacePath` for every resolved tag.
+`validateAllChangelogOverrides()` checks override files against the changelog items of their scopes, which the caller supplies, and returns every error and stale-key warning, each prefixed with the path of its file. `formatValidateOverridesResult()` turns that result into the exit code and message that `release-kit overrides validate` prints.
 
-- `resolveReleaseTags` signature changed from `(workspaceMap?: Map<string, string>)` to `(workspaces?: readonly WorkspaceConfig[])`.
-- `WorkspaceConfig` gained a required `workspacePath: string` field.
-
-Replace direct `Map`-based calls with `deriveWorkspaceConfig()`, which now populates `workspacePath`:
-
-```diff
--import { resolveReleaseTags } from '@williamthorsen/release-kit';
--
--const workspaceMap = new Map([['core', 'packages/core']]);
--resolveReleaseTags(workspaceMap);
-+import { deriveWorkspaceConfig, resolveReleaseTags } from '@williamthorsen/release-kit';
-+
-+resolveReleaseTags([deriveWorkspaceConfig('packages/core')]);
+```typescript
+import { formatValidateOverridesResult, validateAllChangelogOverrides } from '@williamthorsen/release-kit';
+
+const result = validateAllChangelogOverrides({
+  project: { filePath: '.meta/changelog-overrides.json' },
+  workspaces: [
+    {
+      filePath: 'packages/core/.meta/changelog-overrides.json',
+      items: [{ hash: '3f2a9c1e0b7d4a6f8e5c2b1a0d9e8f7a6b5c4d3e' }, { hash: '9b8a7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0b', entry: 2 }],
+    },
+  ],
+});
+
+const { exitCode, message } = formatValidateOverridesResult(result, 'plain');
 ```
 
-When constructing `WorkspaceConfig` objects directly, add `workspacePath` alongside the other required fields.
+An item is a commit hash, with `entry` set to the 1-based position of the change-record entry from which the item derives. A relative `filePath` resolves against the working directory. The exported types are `ValidateAllChangelogOverridesInputs`, `ChangelogOverrideScope`, `OverrideTargetItem`, `ValidateAllChangelogOverridesResult`, and `ValidateOverridesCommandResult`. [Editorial overrides](editorial-overrides.md) describes the file format and the tiers.

package/docs/changelogs.md

@@ -1,8 +1,8 @@
 # Changelogs
 
-What a published tarball includes, what each `.meta/changelog.json` item contains, which commits appear in a changelog, how a merge commit's change-record block becomes items, and how release notes are written into a README.
+What a published tarball includes, what each `.meta/changelog.json` item contains, how `CHANGELOG.md` archives older versions, which commits appear in a changelog, how a merge commit's change-record block becomes items, and how release notes are written into a README.
 
-npm doesn't include either `CHANGELOG.md` or `.meta/changelog.json` in a published tarball on its own. npm stopped including `CHANGELOG` automatically in npm 7, so a package that declares a `files` field publishes a changelog only when that field names `CHANGELOG.md` and `.meta/changelog.json`. release-kit's readyup kit reports a publishable workspace whose `files` field omits either.
+npm doesn't include either `CHANGELOG.md` or `.meta/changelog.json` in a published tarball on its own. npm stopped including `CHANGELOG` automatically in npm 7, so a package that declares a `files` field publishes a changelog only when that field names `CHANGELOG.md` and `.meta/changelog.json`. release-kit's readyup kit reports a publishable workspace whose `files` field omits either, and, when [`changelogMarkdown.keepVersions`](#archived-versions) is set, one whose `files` field omits `changelogs/`.
 
 ## `changelog.json` item schema
 
@@ -41,6 +41,26 @@ Three properties are worth knowing:
 
 The label match is exact: `migration:` and `**Migration:**` are not recognized.
 
+## Archived versions
+
+`changelogMarkdown.keepVersions` bounds `CHANGELOG.md`, which otherwise grows by one section per release. `.meta/changelog.json` is not affected: It contains every version whatever the option says.
+
+```typescript
+export default defineConfig({
+  changelogMarkdown: { keepVersions: 20 },
+});
+```
+
+With the option set, `prepare` writes each changelog as follows:
+
+- **`CHANGELOG.md`** contains the newest `keepVersions` sections, counting [hand-written sections](#existing-changelogmd-sections), and a paragraph below its header that links to each archive file.
+- **`changelogs/CHANGELOG-v{major}.md`**, beside `CHANGELOG.md`, contains every older section of that major version, newest first, under the same header and footer. `0.x` versions share `CHANGELOG-v0.md`, and a prerelease belongs to its major.
+- **An archive file that the render no longer produces**, after `keepVersions` is raised or the option is removed: `prepare` deletes it and renders its sections in `CHANGELOG.md` again. Every section is therefore in exactly one file.
+
+`prepare` regenerates the archive files on every release of the target, so an override applies to an archived version as it does to any other. A target that does not release keeps its unbounded `CHANGELOG.md` until its next release. The prepare report lists each archive file that it writes and each that it removes.
+
+A package that declares a `files` field publishes the archive files only when the field covers `changelogs/`; without them, the links from `CHANGELOG.md` do not resolve in the published package.
+
 ## Which commits appear in a changelog
 
 release-kit splits the history reachable from `HEAD` into one window per release tag that matches the scope's tag prefixes, restricted to commits that touch the scope's `paths`. The bump reads the same items: Its level is the highest that the unreleased window's items call for, so a commit that bumps is one that the changelog lists.
@@ -55,7 +75,7 @@ A commit whose last `change-record` block records entries yields its items from
 
 ### Existing `CHANGELOG.md` sections
 
-`prepare` also reads the `CHANGELOG.md` that it regenerates, so a version recorded only there, such as history written by hand before release-kit was adopted, survives. The first SemVer token in a `##` heading names the section's version: `## 1.2.0`, `## v1.2.0`, and `## [1.2.0] - 2024-01-01` all name 1.2.0, and so does `## Upgrading from 1.2.0`.
+`prepare` also reads the `CHANGELOG.md` that it regenerates, and its [archive files](#archived-versions), so a version recorded only there, such as history written by hand before release-kit was adopted, survives. The first SemVer token in a `##` heading names the section's version: `## 1.2.0`, `## v1.2.0`, and `## [1.2.0] - 2024-01-01` all name 1.2.0, and so does `## Upgrading from 1.2.0`.
 
 - **A version that neither the release windows nor `changelog.json` contain** keeps its section verbatim, placed among the rendered sections in version order.
 - **A version that either contains** is rendered from its entries, and its old text is discarded.
@@ -67,11 +87,11 @@ The header above the first section and the footer comment are regenerated. The p
 
 A workspace's window contains every commit that touches the workspace's paths. An item derived from a title is routed to every workspace whose window contains its commit. An item derived from a change-record entry is routed to a workspace in that window only when the entry's `scopes` route it there:
 
-- **A scope that names the workspace's `dir`** routes the item to that workspace. release-kit resolves each scope through [`scopeAliases`](configuration.md) before it compares the scope with the `dir`.
+- **A scope that names the workspace's target name**, which is its `dir` unless a [`releases`](configuration.md#releases) entry renames it, routes the item to that workspace. release-kit resolves each scope through [`scopeAliases`](configuration.md) before it compares the scope with the name.
 - **`*`, or an empty or absent `scopes`,** routes the item to every workspace in the window.
 - **`root`** doesn't name a workspace, so it routes the item nowhere and is not reported. A workspace whose `dir` is `root` is the exception: `root` then names that workspace.
 
-A scope narrows the window and never widens it: A scope that names a workspace whose window does not contain the commit doesn't route the item to any workspace, and `prepare` reports it (see [Reported diagnostics](#reported-diagnostics)). The project changelog and a single-package repo take every entry, whatever its scopes.
+A scope narrows the window and never widens it: A scope that names a workspace whose window does not contain the commit doesn't route the item to any workspace, and `prepare` reports it (see [Reported diagnostics](#reported-diagnostics)). A composite's changelog, such as the project changelog, and a single-package repo take every entry, whatever its scopes.
 
 A workspace's bump reads the items routed to it, so a breaking entry scoped to one workspace does not raise a major bump in another that the same commit touched. A workspace whose window has commits but lacks a routed item doesn't call for a release.
 
@@ -117,7 +137,7 @@ A commit is read from its title, as [Which commits appear in a changelog](#which
 - **A malformed block**, with the defect that stopped the read.
 - **An entry whose type is not declared**, with its position. It doesn't yield an item.
 - **An entry that violates its type's breaking policy**, as a policy violation at the entry's position. Its item is not marked breaking.
-- **An entry scope that doesn't name a workspace in its commit's window**, with the commit's hash, the entry's position, and the scope as the entry declares it. release-kit reports it under every workspace whose window contains the commit. A scope that names nothing, or a workspace whose window does not contain the commit, is reported; `*`, `root`, and a scope that names a workspace in the window are not. Under `--only`, a scope that names a configured workspace left out of the run is not reported either. A workspace excluded with `shouldExclude: true` is not a configured workspace, so a scope that names one is reported.
+- **An entry scope that doesn't name a workspace in its commit's window**, with the commit's hash, the entry's position, and the scope as the entry declares it. release-kit reports it under every workspace whose window contains the commit. A scope that names nothing, or a workspace whose window does not contain the commit, is reported; `*`, `root`, and a scope that names a workspace in the window are not. Under `--only`, a scope that names a configured workspace left out of the run is not reported either. A workspace excluded with `shouldExclude: true` or a `releases` entry of `false` is not a configured workspace, so a scope that names one is reported.
 
 The result that `prepare` returns includes these as `malformedBlocks`, `undeclaredEntryTypes`, `policyViolations` entries whose `surface` is `'entry'`, and `unroutedEntryScopes`, whether the target releases or is skipped. Because a block whose entries are all undeclared or excluded doesn't yield an item, the commit doesn't raise a bump.
 

package/docs/configuration.md

@@ -1,6 +1,6 @@
 # Configuration
 
-The fields of `.config/release-kit.config.ts`, how a workspace declares its prior identities or a retired package, the rule against colliding tag prefixes, the patterns that decide a bump, and the environment variable that sets the output style.
+The fields of `.config/release-kit.config.ts`, how the `releases` block names release targets, how a workspace declares its prior identities or a retired package, the rule against colliding tag prefixes, the patterns that decide a bump, and the environment variable that sets the output style.
 
 A minimal config file is in the [README](../README.md#configuration).
 
@@ -16,22 +16,84 @@ The two paths differ in what an absent file means. An absent default path means
 
 ## `ReleaseKitConfig` reference
 
-| Field              | Type                                        | Description                                                                                                                                                                                                                                               |
-| ------------------ | ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `workspaces`       | `WorkspaceOverride[]`                       | Override or exclude discovered workspaces (matched by `dir`)                                                                                                                                                                                              |
-| `formatCommand`    | `string`                                    | Shell command to run after changelog generation; modified file paths are appended as arguments                                                                                                                                                            |
-| `versionPatterns`  | `VersionPatterns`                           | Rules for which commit types trigger major/minor bumps                                                                                                                                                                                                    |
-| `scopeAliases`     | `Record<string, string>`                    | Maps shorthand scope names to canonical names in commit titles and in change-record entry `scopes`, which [route items to workspaces](changelogs.md#routing-to-workspaces). A renamed workspace directory needs an entry from its old name to its new one |
-| `workTypes`        | `Record<string, WorkTypeConfig>`            | Work type definitions, merged with defaults by key                                                                                                                                                                                                        |
-| `breakingPolicies` | `Record<string, 'forbidden' \| 'optional'>` | Per-type `!`-policy lookup. Defaults to `DEFAULT_BREAKING_POLICIES`. Replaces the default entirely when provided. Set to `{}` to disable enforcement                                                                                                      |
-| `retiredPackages`  | `RetiredPackage[]`                          | Packages that once lived in this repo but have been extracted or removed; suppresses undeclared-tag-prefix warnings                                                                                                                                       |
-| `project`          | `ProjectConfig`                             | Opt-in project-level release block. Declaring `project: {}` (even empty) enables a project-release stage in `prepare`                                                                                                                                     |
-| `repoLabels`       | `RepoLabelsConfig`                          | Declares the repository's label registry for `sync-labels`; see [Label configuration](labels.md#label-configuration)                                                                                                                                      |
-| `changelogJson`    | `ChangelogJsonConfig`                       | Controls `.meta/changelog.json`: `enabled` (default `true`), `outputPath` (default `'.meta/changelog.json'`), and `devOnlySections`; see [Custom work types](work-types.md#custom-work-types)                                                             |
-| `releaseNotes`     | `ReleaseNotesConfig`                        | `shouldInjectIntoReadme` (default `false`) injects release notes into each package's README while it publishes; see [Release-notes injection](changelogs.md#release-notes-injection)                                                                      |
+| Field               | Type                                        | Description                                                                                                                                                                                                                                                                              |
+| ------------------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `releases`          | `Record<string, ReleaseEntry>`              | Names, excludes, or composes release targets; see [`releases`](#releases). Can't be combined with `workspaces` or `project`                                                                                                                                                              |
+| `workspaces`        | `WorkspaceOverride[]`                       | Override or exclude discovered workspaces (matched by `dir`)                                                                                                                                                                                                                             |
+| `formatCommand`     | `string`                                    | Shell command to run after changelog generation; modified file paths are appended as arguments                                                                                                                                                                                           |
+| `versionPatterns`   | `VersionPatterns`                           | Rules for which commit types trigger major/minor bumps                                                                                                                                                                                                                                   |
+| `scopeAliases`      | `Record<string, string>`                    | Maps shorthand scope names to canonical names in commit titles and in change-record entry `scopes`, which [route items to workspaces](changelogs.md#routing-to-workspaces). A renamed workspace directory or [release target](#releases) needs an entry from its old name to its new one |
+| `workTypes`         | `Record<string, WorkTypeConfig>`            | Work type definitions, merged with defaults by key                                                                                                                                                                                                                                       |
+| `breakingPolicies`  | `Record<string, 'forbidden' \| 'optional'>` | Per-type `!`-policy lookup. Defaults to `DEFAULT_BREAKING_POLICIES`. Replaces the default entirely when provided. Set to `{}` to disable enforcement                                                                                                                                     |
+| `retiredPackages`   | `RetiredPackage[]`                          | Packages that once lived in this repo but have been extracted or removed; suppresses undeclared-tag-prefix warnings                                                                                                                                                                      |
+| `project`           | `ProjectConfig`                             | Opt-in project-level release block. Declaring `project: {}` (even empty) enables a project-release stage in `prepare`                                                                                                                                                                    |
+| `repoLabels`        | `RepoLabelsConfig`                          | Declares the repository's label registry for `sync-labels`; see [Label configuration](labels.md#label-configuration)                                                                                                                                                                     |
+| `changelogJson`     | `ChangelogJsonConfig`                       | Controls `.meta/changelog.json`: `enabled` (default `true`), `outputPath` (default `'.meta/changelog.json'`), and `devOnlySections`; see [Custom work types](work-types.md#custom-work-types)                                                                                            |
+| `changelogMarkdown` | `ChangelogMarkdownConfig`                   | `keepVersions` (an integer, at least 1) bounds `CHANGELOG.md` to that many of the newest versions and moves the rest into per-major archive files; omitted, `CHANGELOG.md` renders every version. See [Archived versions](changelogs.md#archived-versions)                               |
+| `releaseNotes`      | `ReleaseNotesConfig`                        | `shouldInjectIntoReadme` (default `false`) injects release notes into each package's README while it publishes; see [Release-notes injection](changelogs.md#release-notes-injection)                                                                                                     |
 
 All fields are optional.
 
+## `releases`
+
+`releases` maps each release target's name to its declaration. Every discovered workspace is a target, named by its directory, unless an entry excludes or renames it, so the block lists only what differs from the discovered set, along with any directory that releases without being a workspace.
+
+```typescript
+const config: ReleaseKitConfig = {
+  releases: {
+    core: { path: 'packages/nmr-core', legacyIdentities: [{ name: '@scope/core', tagPrefix: 'core-v' }] },
+    docs: { path: 'docs' },
+    scratch: false,
+    suite: { includes: ['nmr', 'core', 'docs'], tagPrefix: 'v' },
+  },
+};
+```
+
+An entry takes one of three shapes:
+
+- **`false`** excludes the discovered workspace that the entry's name names by its directory. An excluded workspace is treated as a `shouldExclude` one is: `prepare` never releases it, and `push`, `publish`, and `create-github-release` skip its tags with a warning.
+- **`{ path, tagPrefix?, legacyIdentities? }`** names the discovered workspace at `path`, a repo-relative directory. A `path` that isn't a discovered workspace declares a [directory target](#directory-targets) instead. `legacyIdentities` has the meaning that it has in [`WorkspaceOverride`](#workspaceoverride). `tagPrefix` applies only to a directory target: A workspace's prefix derives from its package name, and an entry that sets one for a workspace is an error.
+- **`{ includes, tagPrefix? }`** declares the composite, a release that rolls up the named package and directory targets. It is versioned by the root `package.json`, writes `./CHANGELOG.md`, and reads the commits of its members' windows. Its tag prefix defaults to `'v'`. A config declares at most one composite, because the root `package.json` holds one version. `includes` names targets by their names in this block, and it names at least one. Like a `project` release, the composite's changelog takes every entry in its window, whatever the entry's scopes.
+
+A target's name is its only identity. `--only` and `--set-version` select it by name, and a change-record entry routes to it when a scope names it. A target's name never reaches its tag prefix: A workspace's prefix stays `{unscoped package name}-v` whatever the entry calls it, and a directory's derives from its path. Renaming a workspace in `releases` therefore changes the scope that routes to it; add a [`scopeAliases`](#releasekitconfig-reference) entry from the old name to the new one, so that entries written before the rename still route to the target.
+
+`releases` can't be combined with `workspaces` or `project`, which declare the same targets, and a single-package repo rejects it. None of its entries accepts `paths`: A package's or a directory's commit window is its path, and a composite's is its members' windows. [Moving to `releases`](project-releases.md#moving-to-releases) maps each `workspaces` and `project` setting onto the block; both blocks keep working unchanged.
+
+### Directory targets
+
+A `{ path }` entry whose path isn't a discovered workspace declares a directory target: a Swift app, a Go binary, a container image, or a docs site that has a version, a changelog, and tags but isn't a JS package.
+
+- **Version file.** The directory's `package.json` when it has one, otherwise `version.json` in the directory. Either is a JSON file with a string `version` field, which `prepare` bumps. A directory without either is a config error that names the file to create, such as `{ "version": "0.0.0" }`.
+- **Commit window.** The directory. A commit can appear in several targets' changelogs when their windows overlap.
+- **Tag prefix.** The directory's basename followed by `-v`, such as `devopticon-v` for `apps/devopticon`, unless the entry sets `tagPrefix`. A basename that can't form a tag name, such as one containing a space, is an error that asks for `tagPrefix`.
+- **Changelog.** `CHANGELOG.md` in the directory. A change-record entry routes to the target when a scope names it, as it does to a workspace.
+- **Releases.** `--only` and `--set-version` take the target's name. A directory target never takes part in dependency propagation, and `publish` never publishes its tag. `push` pushes the tag, and `create-github-release` creates a GitHub Release for it from the directory's `.meta/changelog.json`.
+
+A path outside the repo, or one that isn't a directory, is an error.
+
+#### The repo root
+
+`{ path: '.' }` declares the repo root as a directory target, which is how a release states whole-repo coverage. Its window is the whole repo, its version file is the root `package.json`, its tag prefix is `v`, and its `CHANGELOG.md` takes every entry in its window, whatever the entry's scopes. A workspace added later is a target of its own and doesn't narrow the root target's window.
+
+The root target and a composite would both version the root `package.json`, so declaring both is an error.
+
+#### Worked example: an app that is the repo's deliverable
+
+`williamthorsen/devopticon` releases a SwiftPM app in `apps/devopticon`, keeps its version in the root `package.json`, and stamps it into the app bundle at build time. Its only workspace is a scaffold under `packages/`. A `project` block covered the whole repo only while the workspace union was empty, so adding a releasable package would have dropped the app and every root-level commit from the changelog. The root target states the coverage:
+
+```typescript
+export default defineConfig({
+  releases: {
+    devopticon: { path: '.' },
+    scaffold: false,
+  },
+});
+```
+
+`prepare` bumps the root `package.json`, writes `./CHANGELOG.md` from every commit since the last `v` tag, and tags `v{version}`. A package added under `packages/` later releases under its own `{name}-v` tags, and the root target still reads the whole repo.
+
+To version the app on its own instead, declare `app: { path: 'apps/devopticon' }` with an `apps/devopticon/version.json`; its window is then the app's directory, and its tags are `devopticon-v{version}`.
+
 ## `WorkspaceOverride`
 
 ```typescript
@@ -87,8 +149,9 @@ Validation rules:
 Tag prefixes from distinct owners must not be identical or be a strict prefix of one another. An owner is one of:
 
 - An active workspace, comprising its derived `tagPrefix` plus any declared `legacyIdentities[].tagPrefix`. Identities of the same workspace are one owner, so their prefixes are allowed to overlap (this represents the same package across renames).
+- A directory target, comprising its `tagPrefix` plus any declared `legacyIdentities[].tagPrefix`, as one owner.
 - A `retiredPackages[]` entry (one owner per entry).
-- The `project` block, when configured.
+- The `project` block or the `releases` composite, when configured.
 
 Because release-kit matches a tag to a prefix when the tag name is the prefix followed by a complete SemVer version, a strict-prefix overlap between distinct owners can match the wrong owner's tags. For example, a retired prefix of `pkg-` collides with a workspace prefix of `pkg-1.0.0-v`, since `pkg-1.0.0-v1.2.3` is `pkg-` followed by the pre-release version `1.0.0-v1.2.3`. The rule rejects every strict-prefix overlap, including one such as `v` and `vue-helpers-v`, whose shorter prefix can't match any tag of the longer one.
 
@@ -96,7 +159,7 @@ The rule is enforced at config load; the resulting error identifies both collidi
 
 ## `release-kit show-tag-prefixes`
 
-Prints a per-workspace table of derived tag prefixes, tag counts, and declared legacy prefixes. Also reports any release-shaped tag prefix in the repo that is neither a derived prefix nor declared via `legacyIdentities`, along with a copy-pasteable `workspaces: [...]` config snippet. The snippet uses a `TODO-fill-in-legacy-npm-name` placeholder for each identity's `name`; replace it with the package's prior npm name before pasting.
+Prints a per-workspace table of derived tag prefixes, tag counts, and declared legacy prefixes, with a row for each directory target. Also reports any release-shaped tag prefix in the repo that is neither a derived prefix nor declared via `legacyIdentities`, along with a copy-pasteable `workspaces: [...]` config snippet. The snippet uses a `TODO-fill-in-legacy-npm-name` placeholder for each identity's `name`; replace it with the package's prior npm name before pasting.
 
 Exits `0` when every workspace derives a prefix and the workspaces' prefixes don't collide; exits `1` on any derivation failure or collision. Undeclared candidates do not affect the exit code; the `legacy tag prefixes are declared` readyup check reports them as a warning.
 

package/docs/labels.md

@@ -36,11 +36,13 @@ The block declares the repository's label registry: the set of labels defined on
 
 The `common` preset defines a label for every work type in change-grammar's taxonomy, named by the type's `trackerLabel`, in addition to the labels in its bundled YAML file.
 
+The bundled file's `confidence:` family grades how advisable a recommendation is, for example one that a triage of spike findings turns into a ticket: `confidence:high` is clearly worth doing, `confidence:medium` is worth doing but arguable, and `confidence:low` is not worth a ticket now.
+
 Names match case-insensitively, as GitHub matches them: `Bug` in the `labels` record replaces a preset's `bug`, and `Bug: null` removes it. A label takes the spelling of the last layer to write it.
 
-`description` is optional throughout, in a preset as in the `labels` record, and `sync-labels init` generates none for a scope label. The generated file spells an absent description `''` because `github-label-sync` reads an omitted description as "leave the label's current one alone"; the empty form clears it.
+`description` is optional throughout, in a preset as in the `labels` record, and `sync-labels init` generates none for a scope label. The generated file spells an absent description `''` because `github-label-sync` reads an omitted description as "leave the label's current one alone"; the empty form clears it. Because a scope label without a description groups compactly in GitHub's label list, release-kit's readyup kit warns about each `scope:` label in the generated file that has one.
 
-Overlaps between layers are never errors; order resolves them, and the committed `.github/labels.yaml` diff shows any unexpected change at review. Two misstatements are config errors, because neither is visible in the output diff: a dangling `null`, which removes a name not defined by any preset, and `labels` keys that differ only in case, all but one of which the fold would discard.
+Overlaps between layers are never errors; order resolves them, and the committed `.github/labels.yaml` diff shows any unexpected change at review. Three misstatements are config errors, because none is visible in the output diff: a dangling `null`, which removes a name not defined by any preset; `labels` keys that differ only in case, all but one of which the fold would discard; and an alias that names a resolved label or repeats another alias, which would make the sync merge one label into another and delete it (see [Renaming a label](#renaming-a-label)).
 
 ### Retiring a label
 
@@ -56,6 +58,27 @@ The sync workflow archives a marked label rather than deleting it. An archived l
 
 The mark is set only in the `labels` record, not in a preset. To retire a preset's label, replace it with an entry that restates its color and adds the mark.
 
+### Renaming a label
+
+List a label's old names in `aliases` to rename it:
+
+```typescript
+labels: {
+  'scope:core': { color: '00ff96', aliases: ['scope:basic'] }, // rename `scope:basic` to `scope:core`
+},
+```
+
+The sync renames an existing label that an alias names, in place, rather than deleting it and creating a new one, so the label stays on the issues and pull requests that have it. The dry-run **Label diff** lists the rename. When the repository has both the old name and the new one, the sync adds the new label to every issue and pull request that has the old one, then deletes the old label. A label that an alias names is not reported as undeclared.
+
+`aliases` is set only in the `labels` record, not in a preset, and it takes at least one name. Names match case-insensitively. An alias must not name a label that the config resolves, including the label that declares it, and must not appear twice: Either would make the sync merge one declared label into another and delete it. To rename a preset's label, remove it with `null` and alias it from the new entry:
+
+```typescript
+labels: {
+  bug: null,
+  'type:bug': { color: 'd73a4a', aliases: ['bug'] },
+},
+```
+
 ### When labels are applied
 
 The scaffolded workflow declares three triggers: