@williamthorsen/release-kit 14.0.0 → 14.2.0

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
 
@@ -52,10 +54,31 @@ labels: {
 },
 ```
 
-The sync workflow archives a marked label rather than deleting it. An archived label stays on the issues and pull requests that have it, but it cannot be added to new ones and does not appear in the label picker. Removing the mark unarchives the label on the next sync. Removing the entry instead deletes the label, as the sync deletes every label that `.github/labels.yaml` does not declare, and the label disappears from every issue and pull request that had it.
+The sync workflow archives a marked label rather than deleting it. An archived label stays on the issues and pull requests that have it, but it cannot be added to new ones and does not appear in the label picker. Removing the mark unarchives the label on the next sync. Removing the entry leaves the label in place: The sync does not delete a label that `.github/labels.yaml` does not declare, and it reports each such label as a warning. To delete a label, run `gh label delete <name>`; the label disappears from every issue and pull request that had it.
 
 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:
@@ -68,15 +91,17 @@ The scaffolded workflow declares three triggers:
 
 Applying on merge closes the window in which a regenerated `.github/labels.yaml` remains unapplied. In that window, a later manual dispatch would apply an unreviewed label set.
 
-The `check` job runs the same sync in dry-run. Its **Label diff** log group lists every create, edit, rename, and deletion that the sync would perform, including deletions of labels that the file does not declare: the destructive edits that a diff of `.github/labels.yaml` alone cannot show, because a label created by hand or by another workflow is absent from the file both before and after. Read that log; the check reports success whether or not the diff is destructive, so a green check is not evidence that nothing will be deleted.
+The `check` job runs the same sync in dry-run. Its **Label diff** log group lists every create, edit, and rename that the sync would perform.
 
 Its **Archive state** log group lists each label that the sync would archive or unarchive. Archiving runs after the rest of the sync, so a label that the file both adds and marks is created and then archived.
 
+Both jobs end with an **Undeclared labels** log group, and they report each repository label that the file does not declare as a warning annotation, which appears on the run and on the pull request's check. A label created by hand, for example to put it on the ticket that will declare it, therefore survives every sync until the file declares it or someone deletes it.
+
 The two jobs are split because a job's permissions are fixed when the run is created and cannot vary by trigger. The split keeps a write-scoped token out of pull-request runs.
 
 The push trigger filters on the path alone; the `sync` job compares `github.ref_name` against the repository's default branch. The workflow therefore doesn't need a per-repo edit, whatever that branch is named, and a push touching `.github/labels.yaml` on any other branch produces a run whose jobs all skip.
 
-Manual dispatch is not a preview. It matches the `sync` job, so it applies the labels, deletions included; only the pull-request path runs in dry-run.
+Manual dispatch is not a preview. It matches the `sync` job, so it applies the labels; only the pull-request path runs in dry-run.
 
 ### Dry-run checks on fork pull requests
 

package/docs/project-releases.md

@@ -1,6 +1,6 @@
 # Project releases
 
-How to add a project-level release to a monorepo, what the `project` block accepts, and how that release interacts with `prepare`'s flags.
+How to add a project-level release to a monorepo, what the `project` block accepts, how that release interacts with `prepare`'s flags, and how to declare it as a `releases` composite instead.
 
 Some monorepos release a single combined deliverable, such as a Chrome extension, a CLI binary, or a packaged desktop app, for which the per-workspace tags and changelogs alone do not describe what the user actually receives. Declare the optional `project` block to add a project-level release stage that runs alongside the per-workspace pipeline.
 
@@ -69,6 +69,46 @@ CLI flag interactions:
 - `--bump=major|minor|patch` propagates to the project release as a level chooser. It does not trigger a release on its own when the window doesn't have any commits or any bump-worthy commits.
 - `--force` runs the project release even when the history since the last project tag doesn't have any commits or any bump-worthy commits. Defaults to patch when `--bump` is not given; combine with `--bump=X` to release at a different level.
 - `--only` narrows the run to the named workspaces and their dependents and skips the project release, which is reported as a warning. The project release rolls up every contributing workspace, and `--only` changes which workspaces those are, so rolling up a narrowed set would release a project version covering work that the run excluded. Run a full `prepare` (without `--only`) to include the project release.
-- `--set-version` is rejected with an error when `project` is configured. `--set-version` sets individual workspaces' versions, but a project release rolls up every contributing workspace; the two semantics don't compose. To use `--set-version`, run on a config without a `project` block.
+- `--set-version` is rejected with an error when `project` or a `releases` composite is configured. `--set-version` sets individual workspaces' versions, but a project release rolls up every contributing workspace; the two semantics don't compose. To use `--set-version`, run on a config without a `project` block.
+
+A `releases` composite has a name, so `--only` can select it: `--only suite` prepares the composite alone, from its own window, and `--only nmr,suite` prepares `nmr`, its dependents, and the composite. A run narrowed by `--only` that doesn't name the composite skips it with a warning.
 
 How `--bump` and `--force` combine for every target is in [Releasing](releasing.md#release-kit-prepare).
+
+## Moving to `releases`
+
+The [`releases`](configuration.md#releases) block declares the same targets by name, and every setting of the `workspaces` and `project` blocks has a counterpart in it, except `project.paths`. A config uses one surface or the other; tag prefixes are unchanged either way.
+
+| Legacy setting                                    | `releases` entry                                      |
+| ------------------------------------------------- | ----------------------------------------------------- |
+| `workspaces: [{ dir: 'x', shouldExclude: true }]` | `x: false`                                            |
+| `workspaces: [{ dir: 'x', legacyIdentities }]`    | `x: { path: 'packages/x', legacyIdentities }`         |
+| `project: {}`                                     | `<name>: { includes: [...every retained workspace] }` |
+| `project: { tagPrefix: 'app-v' }`                 | `<name>: { includes: [...], tagPrefix: 'app-v' }`     |
+| `project: { paths }`                              | No counterpart; keep the `project` block              |
+
+Unlike a `project` block, a composite releases only its listed members' commits, and it has a name that `--only` can select. A workspace left out of `includes` still releases on its own.
+
+A `project` block whose window covers the whole repo only because every workspace is excluded maps to the [repo-root target](configuration.md#the-repo-root), `<name>: { path: '.' }`, together with a `false` entry for each excluded workspace. The root target reads the whole repo by declaration, so a workspace added later doesn't narrow it.
+
+## Publishing and GitHub Releases
+
+`push`, `publish`, and `create-github-release` resolve the project tag on HEAD through the `tagPrefix` of the `project` block or the `releases` composite, alongside the workspace tags:
+
+- `release-kit push` pushes the project tag with the release commit, including when the project tag is the only release tag on HEAD.
+- `release-kit publish` never publishes the project tag, because the project does not have an npm package. When `--tags` names it, `publish` warns `Skipping v0.13.0: a project tag is not an npm package.` and publishes nothing for it.
+- `release-kit create-github-release` creates a GitHub Release for the project tag from `./.meta/changelog.json`, whatever the root `package.json#private` says. A private workspace's tag is still skipped, as [Publishing](publishing.md#publishability-filter) describes.
+
+The `create-github-release.yaml` workflow that `release-kit init` scaffolds for a monorepo triggers only on `'*-v[0-9]*.[0-9]*.[0-9]*'`, which requires a literal `-v` and does not match a `v<version>` project tag. Add the project pattern to its tag filter:
+
+```yaml
+on:
+  push:
+    tags:
+      - '*-v[0-9]*.[0-9]*.[0-9]*'
+      - 'v[0-9]*.[0-9]*.[0-9]*'
+```
+
+A GitHub tag filter matches from the start of the tag, so `'v[0-9]*.[0-9]*.[0-9]*'` does not match a workspace tag such as `core-v1.0.0`. A custom `tagPrefix` needs its own pattern, such as `'app-v[0-9]*.[0-9]*.[0-9]*'` for `tagPrefix: 'app-v'`. `publish.yaml` does not need the project pattern, because `publish` skips the project tag.
+
+When every workspace sets `private: true`, `init` does not create `create-github-release.yaml` (see [Releasing](releasing.md)). A project-release repo of that shape adds the workflow itself.

package/docs/publishing.md

@@ -8,14 +8,14 @@ Publishes packages that have release tags on HEAD. The publish workflow's reusab
 
 ### Publishability filter
 
-`publish` and `create-github-release` operate only on workspaces whose `package.json#private` is absent or `false`. A workspace marked `private: true` is "versioned but not published": It can still be tagged by `release-kit tag` and get a `CHANGELOG.md` entry, but it is skipped by both `release-kit publish` (no registry publish) and `release-kit create-github-release` (no GitHub Release). `private: true` alone excludes a workspace from publish and announce; it doesn't require any extra release config. Other commands ignore this filter and operate on private workspaces unchanged.
+`publish` and `create-github-release` operate only on workspaces whose `package.json#private` is absent or `false`. A workspace marked `private: true` is "versioned but not published": It can still be tagged by `release-kit tag` and get a `CHANGELOG.md` entry, but it is skipped by both `release-kit publish` (no registry publish) and `release-kit create-github-release` (no GitHub Release). `private: true` alone excludes a workspace from publish and announce; it doesn't require any extra release config. Other commands ignore this filter and operate on private workspaces unchanged. A project tag is the exception: `publish` never publishes it, and `create-github-release` creates a Release for it whatever the root `package.json#private` says (see [Project releases](project-releases.md#publishing-and-github-releases)).
 
 An unpublishable tag is always skipped cleanly, never fatal. For `release-kit publish`, whether the skip is announced depends on how the tag was resolved:
 
 - **Without `--tags`** (implicit resolution): Unpublishable tags on HEAD are silently filtered. The pre-publish listing shows only the publishable subset. If the filter empties the set, `release-kit publish` prints `Nothing to publish.` and exits 0.
 - **With `--tags`** (explicit naming): Each named tag pointing at an unpublishable workspace is skipped with a warning, and any publishable tags named in the same command are still published.
 
-`release-kit create-github-release` skips unpublishable workspaces with a warning regardless of `--tags`; an all-private tag set is a clean no-op.
+`release-kit create-github-release` skips unpublishable workspaces with a warning regardless of `--tags`; an all-private tag set is a clean no-op. A project tag is not skipped.
 
 Example warning when an explicit tag is unpublishable:
 
@@ -25,6 +25,6 @@ Skipping basic-v1.0.0 (packages/basic): package.json#private is true.
 
 ## `release-kit create-github-release`
 
-Creates GitHub Releases from `changelog.json` for tags on HEAD. Independent of `npm publish`: Invoking this command creates Releases for publishable packages whether or not they were published to a registry. Private workspaces are skipped (see [Publishability filter](#publishability-filter)).
+Creates GitHub Releases from `changelog.json` for tags on HEAD. Independent of `npm publish`: Invoking this command creates Releases for publishable packages whether or not they were published to a registry. Private workspaces are skipped, and a project tag gets a Release (see [Publishability filter](#publishability-filter)).
 
 When `--tags` is omitted, every release tag pointing at HEAD is processed. The CLI requires the `gh` CLI on `PATH` and `contents: write` permission. The bundled `create-github-release.reusable.yaml` GitHub Actions workflow runs this command in CI.

package/docs/releasing.md

@@ -15,13 +15,15 @@ Scaffolded files:
 - `.github/workflows/release.yaml`: Workflow that delegates to a reusable release workflow
 - `.config/release-kit.config.ts`: Starter config with commented-out customization examples (with `--with-config`)
 
+When every workspace, or the single package, sets `private: true`, `init` skips `create-github-release.yaml` and `publish.yaml`, `--force` included, and reports each skip: `publish` and `create-github-release` skip private packages, so neither workflow would do anything. A repo with a `project` block is the exception: `create-github-release` still creates a Release for its project tag, so that repo adds `create-github-release.yaml` itself (see [Project releases](project-releases.md#publishing-and-github-releases)). Its next steps then leave out the provenance and trusted-publisher steps.
+
 ## `release-kit update-templates`
 
 Updates the scaffolded workflows to the templates of the installed release-kit version, and prints what changed in each file. Run it after upgrading release-kit; `--dry-run` previews the changes without writing them.
 
 The workflows are managed files: release-kit renders them, and a change made by hand is overwritten on the next update. The config files are the repository's own, and the command never reads or writes them.
 
-- It creates a missing workflow that `init` would create.
+- It creates a missing workflow that `init` would create. In a repo whose packages are all private, `init` does not create `create-github-release.yaml` or `publish.yaml`, so the command does not create either one when it is missing and reports the skip; it still refreshes either one that exists.
 - It refreshes `.github/workflows/sync-labels.yaml` only when the file exists, because `sync-labels init` scaffolds it on request.
 - It keeps `publish.yaml`'s provenance setting: When the file does not set `provenance: true`, as in a private repository, the updated file does not either.
 
@@ -29,7 +31,7 @@ The workflows are managed files: release-kit renders them, and a change made by
 
 Runs release preparation with automatic workspace discovery.
 
-`--only` names the workspaces from which the release starts, by package directory name (e.g., `arrays`, `release-kit`). The run also releases every workspace that depends on one of them, directly or transitively: A dependent with commits of its own releases at its own bump, and one without releases at a propagated patch bump, so that it publishes against the new version. Workspaces outside that set are left out of the run.
+`--only` names the release targets from which the release starts, by target name: a workspace's directory name (e.g., `arrays`, `release-kit`) unless a [`releases`](configuration.md#releases) entry renames it, or a `releases` composite's name. A named composite releases from its own window, whether or not the run includes its members; a run narrowed by `--only` skips every composite that it doesn't name. The run also releases every workspace that depends on one of them, directly or transitively: A dependent with commits of its own releases at its own bump, and one without releases at a propagated patch bump, so that it publishes against the new version. Workspaces outside that set are left out of the run.
 
 `prepare` reads each target's history once and builds the changelog items of its unreleased commits. The bump is the highest level that those items call for, under [`versionPatterns`](configuration.md#versionpatterns), so the bump and the changelog describe the same release: A `feat` entry in a [change-record block](changelogs.md#change-record-blocks) bumps minor under a `docs:` title, and a breaking item bumps major.
 
@@ -57,6 +59,10 @@ release-kit prepare --force --bump=minor
 release-kit prepare --bump=minor
 ```
 
+### Packages that npm doesn't have yet
+
+Before it writes any file, and in a dry run as well, `prepare` asks npm about each publishable package that the release includes, querying the registry that the package's `publishConfig.registry` names when it sets one. OIDC trusted publishing can't publish a package's first version, so `prepare` refuses to release a package that npm doesn't list, and names each one with its fix: Run `npm publish --access public` from the package's directory once, then register the package as a trusted publisher. The `npm-auto-publish` [readiness kit](readiness-checks.md) prints the `npm trust` command. `prepare` also refuses when it can't look a package up, such as when the registry is unreachable, and reports npm's error for that package.
+
 ### Previewing release notes with `--with-release-notes`
 
 `--with-release-notes` writes two versioned files per workspace after each workspace's `changelog.json` is produced:
@@ -82,7 +88,7 @@ docs/*.v*.md
 
 The `--set-version` flag is a first-class escape hatch for the cases in which the derived bump produces the wrong version, most notably when promoting a pre-1.0 package to 1.0.0. Pre-1.0 packages collapse a `feat!` breaking change to a minor bump (matching semantic-release's `initialMajor: false` and release-please's `bump-minor-pre-major`), so a deliberate promotion to 1.0.0 must be requested explicitly.
 
-In a single-package repo, the value is the version: `--set-version 1.0.0`. In a monorepo, it names the workspace with each version, as comma-separated `<workspace>@N.N.N` entries: `--set-version arrays@1.0.0,strings@2.0.0`. Each named workspace releases at its version whether or not it has commits, and starts the release like a workspace named by `--only`.
+In a single-package repo, the value is the version: `--set-version 1.0.0`. In a monorepo, it names the workspace or [directory target](configuration.md#directory-targets) with each version, as comma-separated `<name>@N.N.N` entries: `--set-version arrays@1.0.0,strings@2.0.0`. Each named target releases at its version whether or not it has commits, and starts the release like a target named by `--only`.
 
 The flag validates that:
 
@@ -120,12 +126,14 @@ The `init` command scaffolds a release workflow at `.github/workflows/release.ya
 
 | Input   | Type    | Description                                                                                                                                     |
 | ------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
-| `only`  | string  | Workspaces to release, with their dependents (comma-separated, leave empty for all)                                                             |
+| `only`  | string  | Release targets to release, with their dependents (comma-separated, leave empty for all)                                                        |
 | `bump`  | choice  | Bump type: `auto` (default, detects it from commits), `patch`, `minor`, or `major`                                                              |
 | `force` | boolean | Release even when the window doesn't have any commits or any bump-worthy commits (defaults to patch; combine with `bump` for a different level) |
 
 For repos that need a self-contained workflow instead of the reusable one, the scaffolded file can be expanded. The key steps are: checkout with full history (`fetch-depth: 0`), run `release-kit prepare` with optional `--only`, `--bump`, and `--force` flags, check for changes, read tags from `tmp/.release-tags`, then commit, tag, and push.
 
+The reusable `release`, `create-github-release`, and `sync-labels` workflows run on `ubuntu-latest` unless the repository's `CI_RUNS_ON` variable names another runner; `publish` always runs on `ubuntu-latest`. See [Runner selection](https://github.com/williamthorsen/node-monorepo-tools/blob/main/.github/workflows/README.md#runner-selection).
+
 ### Triggering a release
 
 ```sh

package/docs/work-types.md

@@ -51,7 +51,7 @@ Each work-type has a `breakingPolicy` value:
 
 A `BREAKING CHANGE:` body footer on a `forbidden`-policy type triggers the same warning path as the prefix `!` does: A type that cannot be breaking is parsed as non-breaking whichever surface has the signal. The warning is all that a footer triggers; it doesn't raise a bump (see [`🚨 **Breaking:**` bullet marker](#-breaking-bullet-marker)).
 
-The release-prepare orchestrators (`releasePrepare`, `releasePrepareMono`, `releasePrepareProject`) apply `DEFAULT_BREAKING_POLICIES` automatically. Violations in the titles and change-record entries of each workspace's or project's unreleased window are collected onto the corresponding result's `policyViolations` field, on a skipped result as on a released one, and rendered under the section in the prepare report:
+The release-prepare orchestrator (`releasePrepareTargets`) applies `DEFAULT_BREAKING_POLICIES` automatically. Violations in the titles and change-record entries of each workspace's or project's unreleased window are collected onto the corresponding result's `policyViolations` field, on a skipped result as on a released one, and rendered under the section in the prepare report:
 
 ```
 arrays

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williamthorsen/release-kit",
-  "version": "14.0.0",
+  "version": "14.2.0",
   "description": "Version-bumping and changelog-generation toolkit for release workflows",
   "keywords": [
     "changelog",
@@ -51,8 +51,8 @@
   ],
   "dependencies": {
     "@williamthorsen/change-grammar": "0.2.0",
-    "@williamthorsen/nmr-core": "0.13.2",
-    "@williamthorsen/toolbelt.errors": "0.8.2",
+    "@williamthorsen/nmr-core": "0.13.3",
+    "@williamthorsen/toolbelt.errors": "0.8.3",
     "json-stringify-pretty-compact": "4.0.0",
     "semver": "7.8.5",
     "yaml": "2.9.1",
@@ -60,9 +60,9 @@
   },
   "devDependencies": {
     "@types/semver": "7.8.0",
-    "@williamthorsen/toolbelt.filesystem": "0.9.2",
-    "@williamthorsen/toolbelt.testing": "0.6.2",
-    "@williamthorsen/toolbelt.vitest": "0.10.2",
+    "@williamthorsen/toolbelt.filesystem": "0.9.3",
+    "@williamthorsen/toolbelt.testing": "0.6.3",
+    "@williamthorsen/toolbelt.vitest": "0.10.3",
     "actionlint": "2.0.6",
     "esbuild": "0.28.2",
     "readyup": "0.40.0",

package/presets/labels/common.yaml

@@ -53,6 +53,17 @@
 - name: 'value:questionable'
   color: c5def5
 
+# Confidence
+- name: 'confidence:high'
+  color: 0b7285
+  description: Clearly worth doing
+- name: 'confidence:medium'
+  color: 3bc9db
+  description: Worth doing, but arguable
+- name: 'confidence:low'
+  color: 99e9f2
+  description: Not worth a ticket now
+
 # Triage
 - name: duplicate
   color: cfd3d7

package/dist/esm/releasePrepare.d.ts

@@ -1,36 +0,0 @@
-import type { ReleasePlan } from './releasePlan.js';
-import type { PrepareConfig, ReleaseType } from './types.js';
-/** Options for the release preparation workflow. */
-export interface ReleasePrepareOptions {
-    /**
-     * Release even when the range since the last tag doesn't contain any commits or any bump-worthy commits.
-     * Orthogonal to `bumpOverride`: When `bumpOverride` is not given, the release falls back to `patch`.
-     */
-    force?: boolean;
-    /** Level of the release, in place of the level that the changelog items call for; it doesn't trigger a release. */
-    bumpOverride?: ReleaseType;
-    /**
-     * Explicit target version (canonical `N.N.N`) that bypasses commit-derived bump logic and takes precedence over
-     * `bumpOverride` and `force`.
-     */
-    setVersion?: string;
-    /**
-     * If true, plan per-workspace release-notes previews under `{workspacePath}/docs/`
-     * (`README.v{version}.md` and `RELEASE_NOTES.v{version}.md`) from each workspace's
-     * changelog entries. Requires `config.changelogJson.enabled`; when disabled,
-     * the planner records a warning on the plan and doesn't plan any previews.
-     */
-    withReleaseNotes?: boolean;
-}
-/**
- * Orchestrates the release preparation workflow for a single package.
- *
- * 1. Reads the release history once, and stops when the current version is recorded but untagged.
- * 2. Decides the release from the history's bump, `--force`, and `--bump` (or takes `--set-version`).
- * 3. Plans the bump of every configured `package.json` version field.
- * 4. Plans the changelogs from the same history, and the release-notes previews when requested.
- * 5. Renders the optional format command.
- *
- * Returns the plan without writing any file.
- */
-export declare function releasePrepare(config: PrepareConfig, options: ReleasePrepareOptions): ReleasePlan;

package/dist/esm/releasePrepare.js

@@ -1,230 +0,0 @@
-import { join as joinPath } from 'node:path';
-import { assertTaggedBaseline, findUntaggedBaseline } from "./assertTaggedBaseline.js";
-import { attachChangelogDiagnostics } from "./attachChangelogDiagnostics.js";
-import { readReleaseHistory, toReleaseEntries } from "./buildChangelogEntries.js";
-import { buildReleaseSummary } from "./buildReleaseSummary.js";
-import { mergeChangelogEntriesWithDisk, renderChangelogJson, resolveChangelogJsonPath } from "./changelogJsonFile.js";
-import { applyChangelogOverrides, formatStaleOverrideKeyWarning, loadOverridesForScopes, } from "./changelogOverrides.js";
-import { decideRelease } from "./decideRelease.js";
-import { deriveSectionOrder } from "./deriveReleaseNotesConfig.js";
-import { hasPrettierConfig } from "./hasPrettierConfig.js";
-import { resolveWorkTypes } from "./loadConfig.js";
-import { planReleaseNotesPreviews } from "./planReleaseNotesPreviews.js";
-import { planVersionBump, planVersionSet } from "./planVersionBump.js";
-import { planPreservedSections } from "./readChangelogSections.js";
-import { renderChangelogMarkdown } from "./renderChangelogMarkdown.js";
-export function releasePrepare(config, options) {
-    const { bumpOverride, force, setVersion, withReleaseNotes } = options;
-    const writes = [];
-    const overridesResult = loadOverridesForScopes({ project: '.' });
-    if (overridesResult.errors.length > 0) {
-        throw new Error(`Failed to load changelog overrides:\n  - ${overridesResult.errors.join('\n  - ')}`);
-    }
-    const overrides = overridesResult.project;
-    const history = readReleaseHistory(config, { tagPrefixes: [config.tagPrefix] });
-    assertTaggedBaseline([
-        findUntaggedBaseline({
-            label: 'package',
-            packageFiles: config.packageFiles,
-            changelogPaths: config.changelogPaths,
-            tagPrefixes: [config.tagPrefix],
-            previousTag: history.previousTag,
-        }, config),
-    ]);
-    const { commits } = history.unreleased;
-    const tag = history.previousTag;
-    const since = tag === undefined ? '(no previous release found)' : `since ${tag}`;
-    let releaseType;
-    let bump;
-    if (setVersion === undefined) {
-        const decision = decideRelease({
-            naturalBump: history.unreleased.bump,
-            commitCount: commits.length,
-            force,
-            bumpOverride,
-            skipReasons: {
-                noCommits: `No commits ${since}. Pass --force to release at patch. Skipping.`,
-                noBumpWorthy: `No bump-worthy commits ${since}. Pass --force to release at patch (or --force --bump=X for a different level). Skipping.`,
-            },
-        });
-        if (decision.outcome === 'skip') {
-            const skipped = buildSkippedSinglePackage(history, decision.skipReason);
-            return {
-                workspaces: [skipped],
-                tags: [],
-                writes: [],
-                summary: '',
-                formatCommand: undefined,
-            };
-        }
-        releaseType = decision.releaseType;
-        bump = planVersionBump(config.packageFiles, releaseType);
-    }
-    else {
-        bump = planVersionSet(config.packageFiles, setVersion);
-    }
-    writes.push(...bump.writes);
-    const newTag = `${config.tagPrefix}${bump.newVersion}`;
-    const planWarnings = [];
-    const changelogs = planSinglePackageChangelogs({
-        config,
-        history,
-        newTag,
-        overrides,
-        overrideWarnings: planWarnings,
-    });
-    const { changelogFiles, changelogJsonFiles, changelogPreservation } = changelogs;
-    const previewWrites = planSinglePackagePreviews(withReleaseNotes === true, config, newTag, changelogs.entries, planWarnings);
-    writes.push(...changelogs.writes, ...previewWrites);
-    const formatCommandStr = config.formatCommand ?? (hasPrettierConfig() ? 'npx prettier --write' : undefined);
-    let formatCommand;
-    if (formatCommandStr !== undefined) {
-        const modifiedFiles = [
-            ...config.packageFiles,
-            ...config.changelogPaths.map((changelogPath) => joinPath(changelogPath, 'CHANGELOG.md')),
-            ...changelogJsonFiles,
-        ];
-        formatCommand = { command: `${formatCommandStr} ${modifiedFiles.join(' ')}`, files: modifiedFiles };
-    }
-    const released = buildReleasedSinglePackage({
-        history,
-        bump,
-        newTag,
-        changelogFiles,
-        changelogPreservation,
-        releaseType,
-        bumpOverride: setVersion === undefined ? bumpOverride : undefined,
-        setVersion,
-        previewFiles: previewWrites.map((write) => write.path),
-    });
-    const plan = {
-        workspaces: [released],
-        tags: [newTag],
-        writes,
-        summary: buildReleaseSummary({ workspaces: [released] }),
-        formatCommand,
-    };
-    if (planWarnings.length > 0) {
-        plan.warnings = planWarnings;
-    }
-    return plan;
-}
-function buildSkippedSinglePackage(history, skipReason) {
-    const { unreleased } = history;
-    const skipped = {
-        status: 'skipped',
-        commitCount: unreleased.commits.length,
-        parsedCommitCount: unreleased.parsedCommitCount,
-        skipReason,
-    };
-    if (history.previousTag !== undefined) {
-        skipped.previousTag = history.previousTag;
-    }
-    if (unreleased.unparseableCommits !== undefined) {
-        skipped.unparseableCommits = unreleased.unparseableCommits;
-    }
-    attachChangelogDiagnostics(skipped, unreleased.diagnostics);
-    return skipped;
-}
-function buildReleasedSinglePackage(args) {
-    const { history, bump, newTag, changelogFiles, releaseType, bumpOverride, setVersion } = args;
-    const { commits, diagnostics, parsedCommitCount, unparseableCommits } = history.unreleased;
-    const released = {
-        status: 'released',
-        commitCount: commits.length,
-        currentVersion: bump.currentVersion,
-        newVersion: bump.newVersion,
-        tag: newTag,
-        bumpedFiles: bump.writes.map((write) => write.path),
-        changelogFiles,
-        commits,
-    };
-    if (history.previousTag !== undefined) {
-        released.previousTag = history.previousTag;
-    }
-    if (releaseType !== undefined) {
-        released.releaseType = releaseType;
-        released.parsedCommitCount = parsedCommitCount;
-        if (unparseableCommits !== undefined) {
-            released.unparseableCommits = unparseableCommits;
-        }
-    }
-    if (bumpOverride !== undefined) {
-        released.bumpOverride = bumpOverride;
-    }
-    attachChangelogDiagnostics(released, diagnostics);
-    if (setVersion !== undefined) {
-        released.setVersion = setVersion;
-    }
-    if (args.previewFiles.length > 0) {
-        released.previewFiles = args.previewFiles;
-    }
-    if (args.changelogPreservation.length > 0) {
-        released.changelogPreservation = args.changelogPreservation;
-    }
-    return released;
-}
-function planSinglePackageChangelogs(args) {
-    const { config, history, newTag, overrides, overrideWarnings } = args;
-    const today = new Date().toISOString().slice(0, 10);
-    const builtEntries = toReleaseEntries(history, newTag, today);
-    const applied = applyChangelogOverrides(builtEntries, overrides);
-    if (applied.errors.length > 0) {
-        throw new Error(`Changelog override application failed:\n  - ${applied.errors.join('\n  - ')}`);
-    }
-    overrideWarnings.push(...applied.warnings);
-    const matchedSet = new Set(applied.matchedKeys);
-    for (const overrideKey of overrides.keys()) {
-        if (!matchedSet.has(overrideKey)) {
-            overrideWarnings.push(formatStaleOverrideKeyWarning(overrideKey));
-        }
-    }
-    const sectionOrder = deriveSectionOrder(resolveWorkTypes(config.workTypes));
-    const changelogFiles = [];
-    const changelogJsonFiles = [];
-    const changelogPreservation = [];
-    const writes = [];
-    let firstMergedEntries = [];
-    for (const changelogPath of config.changelogPaths) {
-        const jsonPath = resolveChangelogJsonPath(config, changelogPath);
-        const mergedEntries = mergeChangelogEntriesWithDisk(jsonPath, applied.entries);
-        if (changelogFiles.length === 0) {
-            firstMergedEntries = mergedEntries;
-        }
-        if (config.changelogJson.enabled) {
-            writes.push({ path: jsonPath, content: renderChangelogJson(mergedEntries) });
-            changelogJsonFiles.push(jsonPath);
-        }
-        const changelogFile = joinPath(changelogPath, 'CHANGELOG.md');
-        const preserved = planPreservedSections(changelogFile, mergedEntries);
-        writes.push({
-            path: changelogFile,
-            content: renderChangelogMarkdown(mergedEntries, { sectionOrder, preservedSections: preserved.sections }),
-        });
-        changelogFiles.push(changelogFile);
-        if (preserved.preservation !== undefined) {
-            changelogPreservation.push(preserved.preservation);
-        }
-    }
-    return { changelogFiles, changelogJsonFiles, changelogPreservation, entries: firstMergedEntries, writes };
-}
-function planSinglePackagePreviews(withReleaseNotes, config, newTag, entries, warnings) {
-    if (!withReleaseNotes) {
-        return [];
-    }
-    if (!config.changelogJson.enabled) {
-        warnings.push('--with-release-notes requires changelogJson.enabled; skipping preview generation');
-        return [];
-    }
-    if (config.changelogPaths.length === 0) {
-        return [];
-    }
-    const previews = planReleaseNotesPreviews({
-        workspacePath: '.',
-        tag: newTag,
-        entries,
-        sectionOrder: deriveSectionOrder(resolveWorkTypes(config.workTypes)),
-    });
-    warnings.push(...previews.warnings);
-    return previews.writes;
-}

package/dist/esm/releasePrepareMono.d.ts

@@ -1,29 +0,0 @@
-import type { ReleasePlan } from './releasePlan.js';
-import type { ReleasePrepareOptions } from './releasePrepare.js';
-import type { MonorepoPrepareConfig } from './types.js';
-/** Options for monorepo release preparation. */
-export interface MonorepoPrepareOptions extends Omit<ReleasePrepareOptions, 'setVersion'> {
-    /**
-     * Workspace `dir`s from which the release starts; the run plans them and their transitive dependents. Present only
-     * for a narrowed run, which skips the project release: The project tier rolls up every contributing workspace, and
-     * the narrowing has changed which workspaces those are.
-     */
-    only?: readonly string[];
-    /**
-     * Explicit target versions (canonical `N.N.N`), keyed by workspace `dir`. Each named workspace starts the release
-     * and releases at its version, which takes precedence over `bumpOverride` and `force`.
-     */
-    setVersions?: ReadonlyMap<string, string>;
-}
-/**
- * Orchestrates release preparation for a monorepo with multiple workspaces.
- *
- * Phase 0: Selects the planned workspaces: those from which the release starts and their transitive dependents.
- * Phase 1: Determines direct bumps from commits for each workspace.
- * Phase 2: Propagates bumps to dependents.
- * Phase 2b: Sorts the full release set topologically.
- * Phase 3: Plans bumps and changelogs in dependency order.
- * Phase 3b: Plans the project release.
- * Phase 4: Renders the format command.
- */
-export declare function releasePrepareMono(fullConfig: MonorepoPrepareConfig, options: MonorepoPrepareOptions): ReleasePlan;