@pnpm/releasing.versioning 1100.1.0

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# @pnpm/releasing.versioning
+
+## 1100.1.0
+
+### Minor Changes
+
+- Added `versioning.epics` to `pnpm-workspace.yaml`. An epic ties a group of member packages to a lead package, constraining every member's major version to a band derived from the lead's major: while the lead is on major `M`, members live in `M*100 … M*100+99`. Members move independently inside the band (patch, minor, and a `major` intent that stays in-band); a bump that would carry a member past the band ceiling is rejected until the lead advances its own major. When a release plan takes the lead to a new stable major, every member re-bases to the band floor in the same plan. Membership is matched with pnpm's package selectors — name globs, `./`-prefixed directory globs, and `!`-prefixed negations.
+
+- Added native workspace release management [#12952](https://github.com/pnpm/pnpm/issues/12952): the new `pnpm change` command records change intents as changesets-compatible `.changeset/*.md` files (`pnpm change status` shows the pending release plan), and the bare `pnpm version -r` consumes them — bumping versions across the workspace with dependent propagation through `workspace:` ranges, fixed groups, a `maxBump` cap, `--filter` narrowing, and `--dry-run` — writing changelogs, and recording consumed intents in a committed ledger that keeps cherry-picks and merge-backs between release branches safe. Packages can be moved onto per-package release lanes with the new `pnpm lane <name> --filter <pkg>` command and back with `pnpm lane main --filter <pkg>` (`pnpm lane` shows the membership), releasing `X.Y.Z-lane.N` prereleases from the same runs that release stable versions of the packages on the main lane. Configuration lives under the new `versioning` key of `pnpm-workspace.yaml` (`fixed`, `ignore`, `maxBump`, `lanes`, `changelog`). When two workspace projects publish the same name, intent files, `versioning.lanes`, and `versioning.fixed`/`ignore` may reference a project by its workspace-relative directory path (e.g. `"./pnpm/npm/pnpm"`) — the one additive extension to the changesets format, applied automatically by `pnpm change`.
+
+  Release changelogs default to `registry` storage (`versioning.changelog.storage`): no `CHANGELOG.md` is committed. Each release's section is composed at publish time and packed into the published tarball on top of the previously published version's changelog, and the consumed change intents are garbage-collected by a later `pnpm version -r` only once the registry confirms the version is published with its section. Set `versioning.changelog.storage: repository` to keep committed `CHANGELOG.md` files instead.
+
+### Patch Changes
+
+- Updated dependencies:
+  - @pnpm/types@1101.4.0
+  - @pnpm/workspace.project-manifest-reader@1100.0.15

package/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2015-2016 Rico Sta. Cruz and other contributors
+Copyright (c) 2016-2026 Zoltan Kochan and other contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,24 @@
+# @pnpm/releasing.versioning
+
+> Native workspace release management: change intents, release-plan assembly, and changelog writing
+
+[![npm version](https://img.shields.io/npm/v/@pnpm/releasing.versioning.svg)](https://npmx.dev/package/@pnpm/releasing.versioning)
+
+Implements the engine behind `pnpm change` and the bare `pnpm version -r`:
+reading and writing changesets-compatible change-intent files from
+`.changeset/*.md`, assembling a release plan (direct bumps, dependent
+propagation through materialized `workspace:` ranges, fixed groups,
+per-package release lanes), and applying it (manifest version updates,
+changelog composition, the consumed-intents ledger, and intent-file cleanup).
+
+See the [native monorepo versioning RFC](https://github.com/pnpm/rfcs/pull/18).
+
+## Installation
+
+```sh
+pnpm add @pnpm/releasing.versioning
+```
+
+## License
+
+MIT

package/lib/applyReleasePlan.d.ts

@@ -0,0 +1,35 @@
+import type { VersioningChangelogStorage, VersioningSettings } from '@pnpm/types';
+import { type ReleasePlan, type WorkspaceProject } from './assembleReleasePlan.js';
+import type { ChangeIntent } from './intents.js';
+/**
+ * Registry storage is the default: no CHANGELOG.md is committed; a release's
+ * section is parked (see {@link writePendingChangelog}) and packed into the
+ * published tarball. `repository` opts back into committed changelogs.
+ */
+export declare function changelogStorage(versioning?: VersioningSettings): VersioningChangelogStorage;
+export interface ApplyReleasePlanOptions {
+    workspaceDir: string;
+    projects: WorkspaceProject[];
+    /**
+     * All intent files currently in the workspace, used to decide which files
+     * are fully consumed after this run and can be deleted.
+     */
+    allIntents: ChangeIntent[];
+    versioning?: VersioningSettings;
+    /**
+     * In `registry` changelog storage, the gate that lets a ledgered release's
+     * intents be garbage-collected: it must resolve `true` only once the
+     * registry has published `${name}@${version}` and that tarball's
+     * CHANGELOG.md already contains `section`. Without it, registry-mode
+     * releases keep their intents (the repository is still their only prose).
+     * Ignored in `repository` storage, where the committed changelog already
+     * holds the prose and the ledger alone gates deletion.
+     */
+    verifyPublished?: (name: string, version: string, section: string) => Promise<boolean>;
+}
+export interface AppliedRelease {
+    name: string;
+    currentVersion: string;
+    newVersion: string;
+}
+export declare function applyReleasePlan(plan: ReleasePlan, opts: ApplyReleasePlanOptions): Promise<AppliedRelease[]>;

package/lib/applyReleasePlan.js

@@ -0,0 +1,115 @@
+import fs from 'node:fs/promises';
+import { readProjectManifest } from '@pnpm/workspace.project-manifest-reader';
+import { indexProjectRefs } from './assembleReleasePlan.js';
+import { composeChangelogSection, prependChangelogSection } from './changelog.js';
+import { appendToLedger, buildConsumptionIndex } from './ledger.js';
+import { listPendingChangelogs, readPendingChangelog, removePendingChangelog, writePendingChangelog } from './pendingChangelog.js';
+/**
+ * Registry storage is the default: no CHANGELOG.md is committed; a release's
+ * section is parked (see {@link writePendingChangelog}) and packed into the
+ * published tarball. `repository` opts back into committed changelogs.
+ */
+export function changelogStorage(versioning) {
+    return versioning?.changelog?.storage ?? 'registry';
+}
+export async function applyReleasePlan(plan, opts) {
+    const storage = changelogStorage(opts.versioning);
+    const applied = await Promise.all(plan.releases.map(async (release) => {
+        const { manifest, writeProjectManifest } = await readProjectManifest(release.rootDir);
+        manifest.version = release.newVersion;
+        await writeProjectManifest(manifest);
+        return {
+            name: release.name,
+            currentVersion: release.currentVersion,
+            newVersion: release.newVersion,
+        };
+    }));
+    // In `repository` storage the section is committed to CHANGELOG.md now. In
+    // `registry` storage nothing is committed to the package; the section is
+    // parked until publish, when it is packed into the tarball.
+    await Promise.all(plan.releases.map(async (release) => {
+        const section = composeChangelogSection(release);
+        if (storage === 'repository') {
+            await prependChangelogSection(release.rootDir, release.name, section);
+        }
+        else {
+            await writePendingChangelog(opts.workspaceDir, release.name, release.newVersion, section);
+        }
+    }));
+    const newEntries = {};
+    for (const release of plan.releases) {
+        if (release.intents.length === 0)
+            continue;
+        newEntries[`${release.name}@${release.newVersion}`] = {
+            dir: release.dir,
+            intents: release.intents.map((intent) => intent.id).sort(),
+        };
+    }
+    const ledger = await appendToLedger(opts.workspaceDir, newEntries);
+    // An intent file is deletable once every project it names has a consumed
+    // ledger entry for it, with one exemption: while a project is still on a
+    // lane, entries against prerelease versions alone keep the file alive — its
+    // prose is still needed to compose the stable changelog section at
+    // graduation. Declined (`none`) entries demand no release and never block
+    // deletion. References here were already validated by the plan assembly,
+    // so an unresolvable one just keeps its file around.
+    //
+    // In `registry` storage the ledger alone does not authorize deletion: the
+    // repository is the only copy of the prose until the release is published,
+    // so an entry counts as consumed only once the registry confirms its version
+    // carries the composed section.
+    const refs = indexProjectRefs(opts.projects, opts.workspaceDir);
+    const consumedLedger = storage === 'repository'
+        ? ledger
+        : await confirmPublished(ledger, opts);
+    const consumptionOf = buildConsumptionIndex(consumedLedger, refs.nameToDirs);
+    const laneDirs = new Set();
+    for (const ref of Object.keys(opts.versioning?.lanes ?? {})) {
+        for (const dir of refs.refToDirs(ref)) {
+            laneDirs.add(dir);
+        }
+    }
+    const deletable = opts.allIntents.filter((intent) => Object.entries(intent.releases).every(([ref, bumpType]) => {
+        if (bumpType === 'none')
+            return true;
+        const dirs = refs.refToDirs(ref);
+        if (dirs.length !== 1)
+            return false;
+        const consumption = consumptionOf(dirs[0]);
+        return consumption.allIds.has(intent.id) &&
+            !(laneDirs.has(dirs[0]) && consumption.prereleaseOnlyIds.has(intent.id));
+    }));
+    await Promise.all(deletable.map(async (intent) => fs.rm(intent.filePath)));
+    return applied;
+}
+/**
+ * Confirms the parked sections whose releases the registry reports published
+ * with that section, deletes those section files (their prose now lives in the
+ * published tarball), and returns the subset of `ledger` those confirmations
+ * cover — the consumed ledger that gates intent deletion. Driven by the parked
+ * files rather than the ledger, so a dependency-propagated release (which has a
+ * section but no consumed intents, hence no ledger entry) still gets its
+ * section collected. Every parked file belongs to an as-yet-unpublished
+ * release, so the confirmation cost is bounded by the release backlog, not by
+ * history.
+ */
+async function confirmPublished(ledger, opts) {
+    const { verifyPublished } = opts;
+    const confirmed = Object.create(null);
+    if (verifyPublished == null)
+        return confirmed;
+    const pending = await listPendingChangelogs(opts.workspaceDir);
+    await Promise.all(pending.map(async ({ name, version }) => {
+        const section = await readPendingChangelog(opts.workspaceDir, name, version);
+        if (section == null)
+            return;
+        if (!(await verifyPublished(name, version, section)))
+            return;
+        const key = `${name}@${version}`;
+        if (ledger[key] != null)
+            confirmed[key] = ledger[key];
+        await removePendingChangelog(opts.workspaceDir, name, version);
+    }));
+    return confirmed;
+}
+//# sourceMappingURL=applyReleasePlan.js.map

package/lib/assembleReleasePlan.d.ts

@@ -0,0 +1,91 @@
+import type { ProjectManifest, VersioningSettings } from '@pnpm/types';
+import type { ChangeIntent, ReleaseBumpType } from './intents.js';
+import { type Ledger } from './ledger.js';
+export interface WorkspaceProject {
+    rootDir: string;
+    manifest: ProjectManifest;
+}
+export type ReleaseCause = 'intent' | 'dependencies' | 'fixed' | 'epic';
+export interface DependencyUpdate {
+    name: string;
+    newVersion: string;
+}
+export interface PlannedRelease {
+    name: string;
+    /** Workspace-relative project directory — the engine's unit of identity. */
+    dir: string;
+    rootDir: string;
+    currentVersion: string;
+    newVersion: string;
+    bumpType: ReleaseBumpType;
+    /**
+     * The intent files this release consumes for this package: the pending ones,
+     * plus — when the release graduates the package off a lane — the
+     * ones the ledger recorded against the lane's prerelease versions.
+     */
+    intents: ChangeIntent[];
+    dependencyUpdates: DependencyUpdate[];
+    causes: ReleaseCause[];
+}
+export interface ReleasePlan {
+    releases: PlannedRelease[];
+}
+export interface AssembleReleasePlanOptions {
+    workspaceDir: string;
+    projects: WorkspaceProject[];
+    intents: ChangeIntent[];
+    ledger: Ledger;
+    versioning?: VersioningSettings;
+    /**
+     * Workspace-relative directories of the projects selected with --filter.
+     * The plan is narrowed to the selected packages' portion of the pending
+     * work, expanded with their fixed-group companions and range-invalidated
+     * dependents.
+     */
+    filter?: Set<string>;
+    /**
+     * When set, every planned release gets the version `0.0.0-<suffix>` instead
+     * of the computed one, matching snapshot releases.
+     */
+    snapshotSuffix?: string;
+    /**
+     * Enforce that every internal production dependency uses the `workspace:`
+     * protocol — a prerequisite for actually releasing. The release path
+     * (`pnpm version -r`) sets this; read-only callers (`pnpm change status`)
+     * leave it off so a diagnostic never fails on an unmigrated dependency.
+     */
+    enforceWorkspaceProtocol?: boolean;
+}
+/**
+ * Whether a package reference is a workspace-relative directory path rather
+ * than a package name — the additive extension to the changesets format,
+ * needed only when workspace projects share a published name.
+ */
+export declare function isDirRef(ref: string): boolean;
+/**
+ * Resolves package references — bare names, or `./`-prefixed
+ * workspace-relative directories — against the workspace. Names are aliases:
+ * one that matches several projects cannot identify any of them and callers
+ * must treat it as an error, never a silent pick.
+ */
+export interface ProjectRefIndex {
+    /** The directories a reference resolves to: `[]` unknown, 2+ ambiguous. */
+    refToDirs: (ref: string) => string[];
+    nameToDirs: (name: string) => string[];
+}
+export declare function indexProjectRefs(projects: ReadonlyArray<{
+    rootDir: string;
+    manifest: {
+        name?: string;
+    };
+}>, workspaceDir: string): ProjectRefIndex;
+/** The workspace-relative directory of a project, in canonical spelling. */
+export declare function toProjectDir(workspaceDir: string, rootDir: string): string;
+export declare function assembleReleasePlan(opts: AssembleReleasePlanOptions): ReleasePlan;
+/**
+ * The range that pnpm materializes for a workspace: spec at pack time, given
+ * the dependency's version at the dependent's previous release. Dependent
+ * propagation republishes the dependent whenever the dependency's new version
+ * falls outside this range.
+ */
+export declare function materializeWorkspaceRange(spec: string, depCurrentVersion: string): string | null;