@williamthorsen/release-kit 14.0.0 → 14.2.0

package/.readyup/manifest.json

@@ -8,18 +8,23 @@
       "esbuildVersion": "0.28.2",
       "inputs": [
         {
-          "hash": "7a8522cd",
+          "hash": "a9f00459",
           "kind": "module",
           "path": "kits/default.ts"
         },
         {
-          "hash": "6eab98d1",
+          "hash": "14ecf16a",
           "kind": "inline",
           "path": "../package.json",
           "paths": [
             "version"
           ]
         },
+        {
+          "hash": "40404aa0",
+          "kind": "module",
+          "path": "../src/changelogArchive.ts"
+        },
         {
           "hash": "43bb0452",
           "kind": "module",
@@ -45,8 +50,8 @@
       "path": "kits/default.js",
       "readyupVersion": "0.40.0",
       "source": "kits/default.ts",
-      "sourceHash": "7a8522cd",
-      "targetHash": "4e21467f"
+      "sourceHash": "a9f00459",
+      "targetHash": "dada6894"
     },
     {
       "checklists": [
@@ -56,7 +61,7 @@
       "esbuildVersion": "0.28.2",
       "inputs": [
         {
-          "hash": "d9910d60",
+          "hash": "79c773cf",
           "kind": "module",
           "path": "kits/npm-auto-publish.ts"
         },
@@ -64,14 +69,24 @@
           "hash": "d360febf",
           "kind": "module",
           "path": "../src/init/hasProvenance.ts"
+        },
+        {
+          "hash": "3e39b9be",
+          "kind": "module",
+          "path": "../src/npmRegistry.ts"
+        },
+        {
+          "hash": "1424b343",
+          "kind": "module",
+          "path": "../src/typeGuards.ts"
         }
       ],
       "name": "npm-auto-publish",
       "path": "kits/npm-auto-publish.js",
       "readyupVersion": "0.40.0",
       "source": "kits/npm-auto-publish.ts",
-      "sourceHash": "d9910d60",
-      "targetHash": "2a6931b6"
+      "sourceHash": "79c773cf",
+      "targetHash": "38ddb04a"
     }
   ]
 }

package/CHANGELOG.md

@@ -2,6 +2,53 @@
 
 All notable changes to this project will be documented in this file.
 
+## 14.2.0 — 2026-10-12
+
+### 🎉 Features
+
+- Adds an optional `aliases` array to a `repoLabels.labels` entry, which `sync-labels` writes to `.github/labels.yaml` so that the sync renames each existing label named by an alias to the entry's name and keeps it on the issues and pull requests that have it. (#1015)
+- Makes `release-kit sync-labels` reject a config whose alias names a label that the config resolves or appears twice, because the sync would otherwise merge one declared label into another and delete it. (#1015)
+- Adds the `confidence:high` ("Clearly worth doing"), `confidence:medium` ("Worth doing, but arguable"), and `confidence:low` ("Not worth a ticket now") labels to the `common` preset of `release-kit sync-labels`, and documents in `docs/labels.md` that the family grades how advisable a recommendation is. (#1019)
+- Adds a warning to the `release-kit` readyup kit that names each `scope:` label in `.github/labels.yaml` with a non-empty description, archived labels included, because GitHub's label list groups scope labels compactly only when they have no description. (#1022)
+- Adds the `releases` block to `.config/release-kit.config.ts`, in which an entry renames a discovered workspace's release target, excludes the workspace with `false`, or declares a composite of named members that the root `package.json` versions, as an alternative to the `workspaces` and `project` blocks, which keep working unchanged. (#1028)
+- Lets `release-kit prepare --only` select a `releases` composite by its target name, and makes a narrowed run that leaves the composite out skip it with a warning that names it. (#1028)
+- Adds directory release targets to `release-kit`: A `releases` entry whose `path` is not a workspace now declares a target that `prepare` versions from the directory's `package.json` or `version.json`, whose `CHANGELOG.md` `prepare` writes, and whose tags `push` and `create-github-release` handle, while `publish` skips them because a directory does not have any package to publish to npm. (#1029)
+- Adds the repo-root target `{ path: '.' }`, which versions the root `package.json`, tags `v{version}`, and writes every commit in the repo to `./CHANGELOG.md`, replacing a `project` block whose window covered the whole repo only while every workspace was excluded. (#1029)
+- Adds the `changelogMarkdown.keepVersions` config option, which makes `prepare` write only the newest `keepVersions` sections to `CHANGELOG.md`, with links to `changelogs/CHANGELOG-v{major}.md` archive files that contain the older sections, and delete any archive file that is no longer needed after the option is raised or removed. (#1031)
+- Extends `prepare` to read hand-written sections from the `changelogs/` archive files as well as from `CHANGELOG.md`, so that an archived section written by hand is kept when the changelog is regenerated. (#1031)
+- Adds the warning "published packages ship the changelog archives" to the release-kit readyup kit, which reports each publishable package whose `files` field omits `changelogs/` while `keepVersions` is set, because the links in `CHANGELOG.md` to the archive files would otherwise be broken in the published package. (#1031)
+
+### 🐛 Bug fixes
+
+- Fixes the issue that the `npm-auto-publish` kit crashed without reporting any results in a repo whose `origin` remote is missing or does not point to GitHub, and makes its trusted-publisher and provenance checks name that cause and advise adding the remote. (#1018)
+- Fixes the issue that `release-kit prepare` accepted two workspaces whose directories share a name, which `--only` and the dependency graph use to identify a workspace, and makes `prepare` and `release-kit overrides validate` stop with an error that lists the path of each. (#1026)
+- Fixes the issue that `release-kit push` never pushed the project tag on HEAD, and failed with `HEAD does not have any release tags.` when the project tag was the only release tag. (#1027)
+- Fixes the issue that `release-kit create-github-release` did not create a GitHub Release for the project tag; a private workspace's tag is still skipped. (#1027)
+- Makes `release-kit publish` skip a project tag named by `--tags` with the warning `Skipping v0.13.0: a project tag is not an npm package.`, since the project does not have an npm package to publish. (#1027)
+
+### ♻️ Refactoring
+
+- Replaces `releasePrepare`, `releasePrepareMono`, and `releasePrepareProject` with `releasePrepareTargets`, which prepares a release from one list of package and project targets resolved from any config shape. (#1026)
+
+### 📚 Documentation
+
+- Rewrites `docs/api.md` to describe what the `.` and `./config` entries export, and drops its sections on `deriveWorkspaceConfig`, the script-based approach, and `resolveReleaseTags`, none of which the package exports. (#1026)
+- Documents in `docs/project-releases.md` the tag pattern that a scaffolded `create-github-release.yaml` needs in order to trigger on a project tag, because its default `'*-v[0-9]*.[0-9]*.[0-9]*'` filter does not match a `v<version>` tag. (#1027)
+
+## 14.1.0 — 2026-10-11
+
+### 🎉 Features
+
+- Stops `release-kit init` from scaffolding `publish.yaml` and `create-github-release.yaml` when every package is private, even with `--force`, and removes the provenance and trusted-publisher steps from the next steps that it prints. (#995)
+- Stops `release-kit update-templates` from re-creating a deleted `publish.yaml` or `create-github-release.yaml` when every package is private, while it still refreshes either workflow that exists. (#995)
+- Makes `release-kit prepare` refuse, before it writes any file and in a dry run too, to release a publishable package that npm does not list or that it cannot look up, and prints `npm publish --access public` as the fix for each unlisted package. (#996)
+
+### 🐛 Bug fixes
+
+- Fixes the issue that the `npm-auto-publish` kit's "published to npm" check reported a failed lookup, such as an unreachable registry or an authentication error, as an unpublished package and ignored `publishConfig.registry`. (#996)
+- Fixes the issue that release-kit's changelog generation treated a floating major tag such as `v1` as a release and added a spurious release to the history, by counting a tag only when the rest of its name after the prefix is a complete SemVer version such as `1.0.0` or `1.0.0-beta.1`. (#1000)
+- Fixes the issue that `release-kit show-tag-prefixes` counted every tag that starts with a workspace's prefix, including floating pointers such as `core-v1` and non-release tags such as `core-vnext`, rather than only the tags that release-kit counts as releases. (#1000)
+
 ## 14.0.0 — 2026-10-08
 
 ### 🎉 Features

package/README.md

@@ -7,15 +7,29 @@ Version-bumping and changelog-generation toolkit for release workflows.
 Provides a self-contained CLI that auto-discovers workspaces from `pnpm-workspace.yaml`, parses conventional commits, determines version bumps, updates `package.json` files, and generates changelogs from the same commit history that decides each bump (with optional [editorial overrides](docs/editorial-overrides.md)).
 
 <!-- section:release-notes -->
-## Release notes — v14.0.0 (2026-10-08)
+## Release notes — v14.2.0 (2026-10-12)
 
 ### 🎉 Features
 
-- 🚨 **Breaking:** Changes monorepo `--set-version` to take comma-separated `<workspace>@N.N.N` entries, which `prepare` accepts without `--only` and together with `--bump` and `--force`, and which release each named workspace's dependents. (#970)
+- Adds an optional `aliases` array to a `repoLabels.labels` entry, which `sync-labels` writes to `.github/labels.yaml` so that the sync renames each existing label named by an alias to the entry's name and keeps it on the issues and pull requests that have it. (#1015)
+- Makes `release-kit sync-labels` reject a config whose alias names a label that the config resolves or appears twice, because the sync would otherwise merge one declared label into another and delete it. (#1015)
+- Adds the `confidence:high` ("Clearly worth doing"), `confidence:medium` ("Worth doing, but arguable"), and `confidence:low` ("Not worth a ticket now") labels to the `common` preset of `release-kit sync-labels`, and documents in `docs/labels.md` that the family grades how advisable a recommendation is. (#1019)
+- Adds a warning to the `release-kit` readyup kit that names each `scope:` label in `.github/labels.yaml` with a non-empty description, archived labels included, because GitHub's label list groups scope labels compactly only when they have no description. (#1022)
+- Adds the `releases` block to `.config/release-kit.config.ts`, in which an entry renames a discovered workspace's release target, excludes the workspace with `false`, or declares a composite of named members that the root `package.json` versions, as an alternative to the `workspaces` and `project` blocks, which keep working unchanged. (#1028)
+- Lets `release-kit prepare --only` select a `releases` composite by its target name, and makes a narrowed run that leaves the composite out skip it with a warning that names it. (#1028)
+- Adds directory release targets to `release-kit`: A `releases` entry whose `path` is not a workspace now declares a target that `prepare` versions from the directory's `package.json` or `version.json`, whose `CHANGELOG.md` `prepare` writes, and whose tags `push` and `create-github-release` handle, while `publish` skips them because a directory does not have any package to publish to npm. (#1029)
+- Adds the repo-root target `{ path: '.' }`, which versions the root `package.json`, tags `v{version}`, and writes every commit in the repo to `./CHANGELOG.md`, replacing a `project` block whose window covered the whole repo only while every workspace was excluded. (#1029)
+- Adds the `changelogMarkdown.keepVersions` config option, which makes `prepare` write only the newest `keepVersions` sections to `CHANGELOG.md`, with links to `changelogs/CHANGELOG-v{major}.md` archive files that contain the older sections, and delete any archive file that is no longer needed after the option is raised or removed. (#1031)
+- Extends `prepare` to read hand-written sections from the `changelogs/` archive files as well as from `CHANGELOG.md`, so that an archived section written by hand is kept when the changelog is regenerated. (#1031)
+- Adds the warning "published packages ship the changelog archives" to the release-kit readyup kit, which reports each publishable package whose `files` field omits `changelogs/` while `keepVersions` is set, because the links in `CHANGELOG.md` to the archive files would otherwise be broken in the published package. (#1031)
 
 ### 🐛 Bug fixes
 
-- 🚨 **Breaking:** Fixes the issue that `release-kit prepare --only` left each dependent of the named workspaces published against the old version range of its dependency, by also releasing every transitive dependent: a dependent with commits of its own at its own bump, and one without at a propagated patch bump. (#970)
+- Fixes the issue that the `npm-auto-publish` kit crashed without reporting any results in a repo whose `origin` remote is missing or does not point to GitHub, and makes its trusted-publisher and provenance checks name that cause and advise adding the remote. (#1018)
+- Fixes the issue that `release-kit prepare` accepted two workspaces whose directories share a name, which `--only` and the dependency graph use to identify a workspace, and makes `prepare` and `release-kit overrides validate` stop with an error that lists the path of each. (#1026)
+- Fixes the issue that `release-kit push` never pushed the project tag on HEAD, and failed with `HEAD does not have any release tags.` when the project tag was the only release tag. (#1027)
+- Fixes the issue that `release-kit create-github-release` did not create a GitHub Release for the project tag; a private workspace's tag is still skipped. (#1027)
+- Makes `release-kit publish` skip a project tag named by `--tags` with the warning `Skipping v0.13.0: a project tag is not an npm package.`, since the project does not have an npm package to publish. (#1027)
 <!-- /section:release-notes -->
 
 ## Installation
@@ -172,4 +186,4 @@ rdy run --sources
 - [Work types and tiers](docs/work-types.md): Tiers, the `!` policy, markers, and custom work types
 - [Labels](docs/labels.md): `sync-labels`, label configuration, the workflow's triggers, and where the `label-map.json` schema is published
 - [Readiness checks](docs/readiness-checks.md): Both readyup kits, and how to run each
-- [Programmatic API](docs/api.md): `deriveWorkspaceConfig()`, the script-based approach, and `resolveReleaseTags`
+- [Programmatic API](docs/api.md): `defineConfig()` for typing a config file, and validating override files from code

package/dist/esm/assertReleasesOnNpm.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Throws when npm doesn't list, or can't confirm, a publishable package among the given workspaces.
+ *
+ * Each workspace path is repo-relative and is read from the current directory. A private package is not looked up,
+ * and an empty list doesn't call the registry at all.
+ */
+export declare function assertReleasesOnNpm(workspacePaths: readonly string[]): void;

package/dist/esm/assertReleasesOnNpm.js

@@ -0,0 +1,56 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { isPublishableManifest } from "./isPublishableManifest.js";
+import { lookUpNpmPackage } from "./npmRegistry.js";
+import { isRecord } from "./typeGuards.js";
+export function assertReleasesOnNpm(workspacePaths) {
+    const unpublished = [];
+    const unverifiable = [];
+    for (const workspacePath of workspacePaths) {
+        const candidate = buildNpmCandidate(workspacePath);
+        if (candidate === undefined) {
+            continue;
+        }
+        const lookup = lookUpNpmPackage(candidate.name, candidate.registry);
+        if (lookup.status === 'unpublished') {
+            unpublished.push(candidate);
+        }
+        else if (lookup.status === 'unverifiable') {
+            unverifiable.push({ candidate, detail: lookup.detail });
+        }
+    }
+    if (unpublished.length === 0 && unverifiable.length === 0) {
+        return;
+    }
+    throw new Error(describeRefusal(unpublished, unverifiable));
+}
+function buildNpmCandidate(workspacePath) {
+    const manifest = JSON.parse(readFileSync(join(workspacePath, 'package.json'), 'utf8'));
+    if (!isRecord(manifest) || !isPublishableManifest(manifest) || typeof manifest['name'] !== 'string') {
+        return undefined;
+    }
+    const publishConfig = manifest['publishConfig'];
+    const registry = isRecord(publishConfig) ? publishConfig['registry'] : undefined;
+    return {
+        name: manifest['name'],
+        workspacePath,
+        ...(typeof registry === 'string' && { registry }),
+    };
+}
+function describeRefusal(unpublished, unverifiable) {
+    const sections = ['Cannot prepare the release: npm must already have every package that the release publishes.'];
+    if (unpublished.length > 0) {
+        sections.push([
+            'Not on npm yet:',
+            ...unpublished.map(({ name, workspacePath }) => `  - ${name}: run "npm publish --access public" from ${workspacePath}`),
+            'Then register each one as a trusted publisher; "rdy run --from npm:@williamthorsen/release-kit npm-auto-publish" prints the command.',
+        ].join('\n'));
+    }
+    if (unverifiable.length > 0) {
+        sections.push([
+            'Could not confirm on npm:',
+            ...unverifiable.map(({ candidate, detail }) => `  - ${candidate.name}: ${detail}`),
+        ].join('\n'));
+    }
+    return sections.join('\n\n');
+}

package/dist/esm/assertTaggedBaseline.d.ts

@@ -1,4 +1,4 @@
-import type { ReleaseConfig } from './types.js';
+import type { ReleaseSettings } from './types.js';
 /** A release target whose history `prepare` has read, as the baseline check sees it. */
 export interface BaselineTarget {
     /** How the error names the target, such as `workspace 'core'`. */
@@ -26,4 +26,4 @@ export declare function assertTaggedBaseline(findings: ReadonlyArray<UntaggedBas
  * `changelog.json` files, and its previous tag is not that version under any of its prefixes. A first release has
  * none, because its changelogs do not record its version yet.
  */
-export declare function findUntaggedBaseline(target: BaselineTarget, config: Pick<ReleaseConfig, 'changelogJson'>): UntaggedBaseline | undefined;
+export declare function findUntaggedBaseline(target: BaselineTarget, config: Pick<ReleaseSettings, 'changelogJson'>): UntaggedBaseline | undefined;

package/dist/esm/attachChangelogDiagnostics.d.ts

@@ -1,4 +1,4 @@
 import type { ChangelogDiagnostics } from './buildChangelogEntries.js';
-import type { ReleasedWorkspaceResult } from './types.js';
+import type { ReleasedPackageResult } from './types.js';
 /** Attaches a history's diagnostics to a released or skipped result, omitting each empty list. */
-export declare function attachChangelogDiagnostics(result: Pick<ReleasedWorkspaceResult, 'malformedBlocks' | 'policyViolations' | 'undeclaredEntryTypes' | 'unroutedEntryScopes'>, diagnostics: ChangelogDiagnostics): void;
+export declare function attachChangelogDiagnostics(result: Pick<ReleasedPackageResult, 'malformedBlocks' | 'policyViolations' | 'undeclaredEntryTypes' | 'unroutedEntryScopes'>, diagnostics: ChangelogDiagnostics): void;

package/dist/esm/bin/release-kit.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { parseArgsOrExit, readPackageVersion, reportError } from '@williamthorsen/nmr-core';
+import { parseArgsOrExit, reportError, resolveSelfVersion } from '@williamthorsen/nmr-core';
 import { describeError } from '@williamthorsen/toolbelt.errors';
 import { commitCommand } from "../commitCommand.js";
 import { configFlagSchema } from "../configFlagSchema.js";
@@ -19,7 +19,7 @@ import { syncLabelsInitCommand } from "../sync-labels/initCommand.js";
 import { syncLabelsCommand } from "../sync-labels/syncCommand.js";
 import { tagCommand } from "../tagCommand.js";
 import { validateOverridesCommand } from "../validateOverridesCommand.js";
-const VERSION = readPackageVersion(import.meta.url);
+const VERSION = resolveSelfVersion(import.meta.url);
 function showUsage() {
     console.info(`
 Usage: release-kit <command> [options]
@@ -108,7 +108,8 @@ function showInitHelp() {
 Usage: release-kit init [options]
 
 Initialize release-kit in the current repository.
-By default, scaffolds only the GitHub Actions workflow files.
+By default, scaffolds only the GitHub Actions workflow files. When every
+package is private, skips publish.yaml and create-github-release.yaml.
 
 Options:
   --with-config   Also scaffold .config/release-kit.config.ts
@@ -124,7 +125,9 @@ Usage: release-kit update-templates [options]
 Update the GitHub Actions workflows that release-kit scaffolds to the templates
 of the installed version, showing what changed in each file. Creates a missing
 workflow that \`init\` would create, and refreshes sync-labels.yaml only when it
-exists. Keeps publish.yaml's provenance setting. Never touches config files.
+exists. When every package is private, refreshes publish.yaml and
+create-github-release.yaml only when they exist. Keeps publish.yaml's provenance
+setting. Never touches config files.
 
 Options:
   --dry-run       Preview changes without writing files
@@ -177,7 +180,8 @@ Usage: release-kit create-github-release [options]
 
 Create GitHub Releases from changelog.json for tags on HEAD. Private
 (package.json#private) workspaces are skipped with a warning, and the command
-doesn't create a Release for them.
+doesn't create a Release for them. A project tag gets a Release even when the
+root package is private.
 
 Options:
   --config <path>        Config file, relative to the current directory
@@ -241,7 +245,7 @@ Usage: release-kit publish [options]
 Publish packages that have release tags on HEAD. Operates only on workspaces whose
 package.json#private is absent or false. Without --tags, unpublishable workspaces are
 silently filtered out. With --tags, an unpublishable tag is skipped with a warning while
-any publishable tags are still published.
+any publishable tags are still published. A project tag is never published.
 
 Options:
   --config <path>        Config file, relative to the current directory

package/dist/esm/buildChangelogEntries.d.ts

@@ -1,6 +1,6 @@
 import { type RawCommit } from './enumerateReleaseWindows.js';
 import type { GenerateChangelogOptions } from './generateChangelogs.js';
-import type { ChangelogEntry, ChangelogSection, MalformedChangeRecordBlock, PolicyViolation, ReleaseConfig, ReleaseType, UndeclaredEntryType, UnroutedEntryScope } from './types.js';
+import type { ChangelogEntry, ChangelogSection, MalformedChangeRecordBlock, PolicyViolation, ReleaseSettings, ReleaseType, UndeclaredEntryType, UnroutedEntryScope } from './types.js';
 /**
  * Strips a section title down to its bare name.
  *
@@ -35,13 +35,13 @@ export interface ChangelogDiagnostics {
  * window decides: its commits, its bump, and its diagnostics.
  *
  * A commit whose last `change-record` block records entries yields one item per entry routed to
- * `options.workspaceDir`; any other commit is classified by its title through `classifyChangelogCommit`. A `release:`
+ * `options.scope`; any other commit is classified by its title through `classifyChangelogCommit`. A `release:`
  * or merge subject yields nothing either way. The read records diagnostics only for the unreleased window, since the
  * released windows were reported when they were prepared.
  */
 export declare function readReleaseHistory(config: ReleaseHistoryConfig, options: GenerateChangelogOptions): ReleaseHistory;
 /** The configuration that `readReleaseHistory` reads. */
-export type ReleaseHistoryConfig = Pick<ReleaseConfig, 'breakingPolicies' | 'changelogJson' | 'scopeAliases' | 'versionPatterns' | 'workTypes'>;
+export type ReleaseHistoryConfig = Pick<ReleaseSettings, 'breakingPolicies' | 'changelogJson' | 'scopeAliases' | 'versionPatterns' | 'workTypes'>;
 /** One read of a scope's release windows. */
 export interface ReleaseHistory {
     /** The newest matching tag that HEAD reaches; undefined when none does. */

package/dist/esm/buildChangelogEntries.js

@@ -32,8 +32,8 @@ export function readReleaseHistory(config, options) {
         const context = {
             breakingPolicies: config.breakingPolicies ?? DEFAULT_BREAKING_POLICIES,
             devOnlySections: new Set(config.changelogJson.devOnlySections.map(stripGroupDecorations)),
-            ...(options.workspaceDir !== undefined && {
-                routing: { workspaceDir: options.workspaceDir, scopeAliases: config.scopeAliases ?? {} },
+            ...(options.scope !== undefined && {
+                routing: { scope: options.scope, scopeAliases: config.scopeAliases ?? {} },
             }),
             versionPatterns: config.versionPatterns ?? DEFAULT_VERSION_PATTERNS,
             workTypes: config.workTypes ?? DEFAULT_WORK_TYPES,
@@ -170,7 +170,7 @@ function isRoutedTo(scopes, routing) {
     }
     return scopes.some((scope) => {
         const resolved = routing.scopeAliases[scope] ?? scope;
-        return resolved === '*' || resolved === routing.workspaceDir;
+        return resolved === '*' || resolved === routing.scope;
     });
 }
 function formatDate(timestamp) {

package/dist/esm/buildDependencyGraph.d.ts

@@ -1,25 +1,25 @@
-import type { WorkspaceConfig } from './types.js';
-/** Identities, current versions, and `workspace:` dependency edges of the workspaces' packages. */
+import type { PackageTarget } from './types.js';
+/** Identities, current versions, and `workspace:` dependency edges of the package targets. */
 export interface DependencyGraph {
-    /** Maps a package name to its workspace `dir`. */
+    /** Maps a package name to its target id, the workspace `dir`. */
     packageNameToDir: Map<string, string>;
-    /** Maps a workspace `dir` to its package name (inverse of `packageNameToDir`). */
+    /** Maps a target id (a workspace `dir`) to its package name (inverse of `packageNameToDir`). */
     dirToPackageName: Map<string, string>;
-    /** Maps a workspace `dir` to its current version; absent when its `package.json` doesn't have a string `version`. */
+    /** Maps a target id to its current version; absent when its `package.json` doesn't have a string `version`. */
     dirToVersion: Map<string, string>;
-    /** Maps a package name to the workspaces that depend on it. */
-    dependentsOf: Map<string, WorkspaceConfig[]>;
+    /** Maps a package name to the targets that depend on it. */
+    dependentsOf: Map<string, PackageTarget[]>;
     /**
-     * Maps a workspace `dir` to the `workspace:`-protocol package names that it declares in `dependencies` or
+     * Maps a target id to the `workspace:`-protocol package names that it declares in `dependencies` or
      * `peerDependencies` (the forward counterpart of `dependentsOf`).
      */
     dependenciesOf: Map<string, Set<string>>;
 }
 /**
- * Builds the dependency graph from the workspaces' `package.json` files.
+ * Builds the dependency graph from the package targets' `package.json` files.
  *
- * Reads each workspace's primary `package.json` (first entry in `packageFiles`) to discover
+ * Reads each target's primary `package.json` (first entry in `versionFiles`) to discover
  * `workspace:` references in `dependencies` and `peerDependencies`, and to record its current
  * version.
  */
-export declare function buildDependencyGraph(workspaces: readonly WorkspaceConfig[]): DependencyGraph;
+export declare function buildDependencyGraph(targets: readonly PackageTarget[]): DependencyGraph;

package/dist/esm/buildDependencyGraph.js

@@ -3,30 +3,30 @@ import { chainError } from '@williamthorsen/toolbelt.errors/candidate';
 function isPackageJsonSubset(value) {
     return typeof value === 'object' && value !== null;
 }
-export function buildDependencyGraph(workspaces) {
+export function buildDependencyGraph(targets) {
     const packageNameToDir = new Map();
     const dirToPackageName = new Map();
     const dirToVersion = new Map();
     const dependentsOf = new Map();
     const dependenciesOf = new Map();
-    const workspacePackages = new Map();
-    for (const workspace of workspaces) {
-        const primaryPackageFile = workspace.packageFiles[0];
+    const targetPackages = new Map();
+    for (const target of targets) {
+        const primaryPackageFile = target.versionFiles[0];
         if (primaryPackageFile === undefined) {
             continue;
         }
         const pkg = readPackageJsonSubset(primaryPackageFile);
-        workspacePackages.set(workspace, pkg);
+        targetPackages.set(target, pkg);
         if (typeof pkg.version === 'string') {
-            dirToVersion.set(workspace.dir, pkg.version);
+            dirToVersion.set(target.id, pkg.version);
         }
         if (pkg.name === undefined) {
             continue;
         }
-        packageNameToDir.set(pkg.name, workspace.dir);
-        dirToPackageName.set(workspace.dir, pkg.name);
+        packageNameToDir.set(pkg.name, target.id);
+        dirToPackageName.set(target.id, pkg.name);
     }
-    for (const [workspace, pkg] of workspacePackages) {
+    for (const [target, pkg] of targetPackages) {
         const allDeps = { ...pkg.dependencies, ...pkg.peerDependencies };
         for (const [depName, depVersion] of Object.entries(allDeps)) {
             if (typeof depVersion !== 'string' || !depVersion.startsWith('workspace:')) {
@@ -34,14 +34,14 @@ export function buildDependencyGraph(workspaces) {
             }
             const existing = dependentsOf.get(depName);
             if (existing === undefined) {
-                dependentsOf.set(depName, [workspace]);
+                dependentsOf.set(depName, [target]);
             }
             else {
-                existing.push(workspace);
+                existing.push(target);
             }
-            const forward = dependenciesOf.get(workspace.dir);
+            const forward = dependenciesOf.get(target.id);
             if (forward === undefined) {
-                dependenciesOf.set(workspace.dir, new Set([depName]));
+                dependenciesOf.set(target.id, new Set([depName]));
             }
             else {
                 forward.add(depName);

package/dist/esm/buildReleaseSummary.d.ts

@@ -1,6 +1,6 @@
 import type { PrepareResult } from './types.js';
 /**
- * Builds a release commit body from a prepare result: one section per released workspace or project that has commits,
- * the project last, each headed by its tag and listing its scope-stripped commit subjects.
+ * Builds a release commit body from a prepare result: one section per released target that has commits, in result
+ * order, each headed by its tag and listing its scope-stripped commit subjects.
  */
-export declare function buildReleaseSummary(result: Pick<PrepareResult, 'project' | 'workspaces'>): string;
+export declare function buildReleaseSummary(result: Pick<PrepareResult, 'targets'>): string;

package/dist/esm/buildReleaseSummary.js

@@ -1,27 +1,19 @@
 import { stripScope } from "./stripScope.js";
 export function buildReleaseSummary(result) {
     const sections = [];
-    for (const workspace of result.workspaces) {
-        if (workspace.status !== 'released') {
+    for (const target of result.targets) {
+        if (target.status !== 'released') {
             continue;
         }
-        const commits = workspace.commits;
+        const commits = target.commits;
         if (commits === undefined || commits.length === 0) {
             continue;
         }
-        const lines = [workspace.tag];
+        const lines = [target.tag];
         for (const commit of commits) {
             lines.push(`- ${stripScope(commit.subject)}`);
         }
         sections.push(lines.join('\n'));
     }
-    const project = result.project;
-    if (project !== undefined && project.status === 'released' && project.commits.length > 0) {
-        const lines = [project.tag];
-        for (const commit of project.commits) {
-            lines.push(`- ${stripScope(commit.subject)}`);
-        }
-        sections.push(lines.join('\n'));
-    }
     return sections.join('\n\n');
 }

package/dist/esm/changelogArchive.d.ts

@@ -0,0 +1,14 @@
+/** Directory, relative to a changelog directory, that contains the per-major archive files of its `CHANGELOG.md`. */
+export declare const CHANGELOG_ARCHIVE_DIRECTORY = "changelogs";
+/** An archive file that exists on disk. */
+export interface ChangelogArchivePath {
+    major: number;
+    path: string;
+}
+/** Returns the path, relative to the changelog directory, of the archive file for a major version. */
+export declare function describeArchivePath(major: number): string;
+/**
+ * Lists the archive files under the changelog directory, newest major first. A missing archive directory has none;
+ * files whose names do not match the archive pattern are ignored.
+ */
+export declare function listArchiveFiles(changelogDir: string): ChangelogArchivePath[];

package/dist/esm/changelogArchive.js

@@ -0,0 +1,21 @@
+import { existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+export const CHANGELOG_ARCHIVE_DIRECTORY = 'changelogs';
+export function describeArchivePath(major) {
+    return `${CHANGELOG_ARCHIVE_DIRECTORY}/CHANGELOG-v${major}.md`;
+}
+export function listArchiveFiles(changelogDir) {
+    const archiveDir = join(changelogDir, CHANGELOG_ARCHIVE_DIRECTORY);
+    if (!existsSync(archiveDir)) {
+        return [];
+    }
+    const archives = [];
+    for (const name of readdirSync(archiveDir)) {
+        const match = ARCHIVE_FILE_PATTERN.exec(name);
+        if (match?.[1] !== undefined) {
+            archives.push({ major: Number(match[1]), path: join(archiveDir, name) });
+        }
+    }
+    return archives.toSorted((a, b) => b.major - a.major);
+}
+const ARCHIVE_FILE_PATTERN = /^CHANGELOG-v(\d+)\.md$/;

package/dist/esm/changelogJsonFile.d.ts

@@ -1,6 +1,6 @@
-import type { ChangelogEntry, ReleaseConfig } from './types.js';
+import type { ChangelogEntry, ReleaseSettings } from './types.js';
 /** Resolves the path of the `changelog.json` file under a workspace's changelog directory. */
-export declare function resolveChangelogJsonPath(config: Pick<ReleaseConfig, 'changelogJson'>, changelogPath: string): string;
+export declare function resolveChangelogJsonPath(config: Pick<ReleaseSettings, 'changelogJson'>, changelogPath: string): string;
 /** Renders changelog entries as a `changelog.json` file's complete content, sorted newest-first. */
 export declare function renderChangelogJson(entries: ChangelogEntry[]): string;
 /**

package/dist/esm/changelogOverrides.d.ts

@@ -1,4 +1,4 @@
-import type { ChangelogEntry, ChangelogOverride, WorkspaceConfig } from './types.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. */
@@ -102,11 +102,11 @@ export interface OverrideContext {
     globalMatchedRootKeys: Set<string>;
 }
 /**
- * Loads and validates the override files of the root and every workspace, and bundles them with empty warning
- * aggregators. Throws if any file fails to load, so that a malformed checked-in override file stops `prepare` before
- * any workspace writes.
+ * 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(workspaces: WorkspaceConfig[]): OverrideContext;
+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;
@@ -164,12 +164,13 @@ export interface ValidateAllChangelogOverridesResult {
  */
 export declare function validateAllChangelogOverrides(inputs: ValidateAllChangelogOverridesInputs): ValidateAllChangelogOverridesResult;
 /**
- * Applies the composed root and workspace override map to a workspace's changelog entries, and records stale keys by
- * tier.
+ * 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 applyWorkspaceOverrides(newEntries: ChangelogEntry[], workspacePath: string, overrideContext: OverrideContext): ReturnType<typeof applyChangelogOverrides>;
+export declare function applyWorkspaceOverrides(newEntries: ChangelogEntry[], workspacePath: string | undefined, overrideContext: OverrideContext): ReturnType<typeof applyChangelogOverrides>;

package/dist/esm/changelogOverrides.js

@@ -336,11 +336,8 @@ export function composeOverrides(rootEntries, workspaceEntries) {
     }
     return composed;
 }
-export function createOverrideContext(workspaces) {
-    const result = loadOverridesForScopes({
-        project: '.',
-        workspaces: workspaces.map((workspace) => workspace.workspacePath),
-    });
+export function createOverrideContext(workspacePaths) {
+    const result = loadOverridesForScopes({ project: '.', workspaces: [...workspacePaths] });
     if (result.errors.length > 0) {
         throw new Error(`Failed to load changelog overrides:\n  - ${result.errors.join('\n  - ')}`);
     }
@@ -488,7 +485,7 @@ function formatRootStaleWarning(filePath, key) {
 }
 export function applyWorkspaceOverrides(newEntries, workspacePath, overrideContext) {
     const { project, perWorkspace, overrideWarnings, globalMatchedRootKeys } = overrideContext;
-    const workspaceOverrides = perWorkspace.get(workspacePath);
+    const workspaceOverrides = workspacePath === undefined ? undefined : perWorkspace.get(workspacePath);
     const composed = composeOverrides(project, workspaceOverrides);
     const applied = applyChangelogOverrides(newEntries, composed);
     if (applied.errors.length > 0) {

package/dist/esm/createGithubReleaseCommand.d.ts

@@ -4,6 +4,7 @@ import { type StreamStyles } from '@williamthorsen/nmr-core';
  * a comma-separated `--tags` subset, without publishing to npm.
  *
  * A private workspace's tag is skipped with a warning and doesn't get a Release; an all-private tag set is a clean
- * no-op. A relative `--config` resolves against `invocationDir`.
+ * no-op. A project tag gets a Release whatever the root `package.json#private` says. A relative `--config` resolves
+ * against `invocationDir`.
  */
 export declare function createGithubReleaseCommand(argv: string[], styles: StreamStyles, invocationDir: string): Promise<void>;