@wpelevator/wp-release 0.9.0 → 0.11.0

package/README.md

@@ -97,7 +97,7 @@ flowchart TD
 	J -->|Yes| K["Workflow opens or updates the release pull request"]
 	K --> L["Review and merge the release pull request"]
 	L --> M["changeset-tag creates tags for packages changed by that release"]
-	M --> N["GitHub Releases are created from changelog entries"]
+	M --> N["A workflow step creates GitHub Releases from the tag notes"]
 	N --> O["Tag-triggered publish and split workflows run"]
 	J -->|No| P["No package versions or release tags are created"]
 ```
@@ -142,17 +142,71 @@ changelogEntry: async ( { changeset, commit } ) => {
 },
 ```
 
+Configure `dependents` to re-release packages that bundle a package when it releases. The dependents come from what the packages declare: a package is a dependent of a source when the spec that it declares in its npm `dependencies` or `optionalDependencies` (or the sections that the policy adds) resolves the current version of the source or points at the workspace, and it re-releases when the next version of the source falls outside the declared range, or always with `when: 'always'`. A pin to an older version selects a registry release instead and `changeset-status` warns about the drift until the pin resolves the package again. Versioning a dependent rewrites its declared specs of the source to the released version, keeping their range prefixes, so an exact pin matches the released workspace again and the built bundle matches the changelog. Wildcards and unpinned ranges accept the release without one, like the `devDependencies` of a package. The derived dependents appear in `changeset-status`, `changeset-version` and `changeset-tag` like any other release, and a dependent that releases for its own reasons keeps its own bump and appends the bundle note:
+
+```js
+dependents: {
+	bump: 'patch', // Default
+	exclude: [ 'actions/wp-release-sign' ], // Package paths under root, or globs over them
+},
+```
+
+Excluded packages still release with their own changesets and stay out of the automatic re-releases.
+
+The bundle changelog entry defaults to `Bundle <source> <version>.` and is formatted with `dependents.changelog( { package, source } )`:
+
+```js
+dependents: {
+	changelog: ( { source } ) => `Bundle ${ source.package.name } ${ source.version }.`,
+},
+```
+
+`dependents.sections` lists the npm dependency sections that declare a source, defaulting to `dependencies` and `optionalDependencies`; add `devDependencies` for dependencies that end up in the dependent's build, or `peerDependencies` to scan them.
+
+The `dependents.dependency` hooks extend the built-in npm scan instead of replacing it, so that both work behind the same range rule and rewrite:
+
+```js
+dependents: {
+	dependency: {
+		// Specs that declare the source outside package.json, like a Composer
+		// require in a vendor-isolated directory.
+		find: async ( { package: dependent, source } ) => {
+			return [ { file: 'vendor-isolated/composer.json', name: '…', spec: '^0.3' } ];
+		},
+		// Update the declaration to the released version. Call `remember( file )`
+		// before writing a file, so failed versioning rolls it back.
+		update: async ( { package: dependent, source, specs, version, remember } ) => { /* … */ },
+	},
+},
+```
+
+After versioning, run `npm install --package-lock-only` so that the root lockfile resolves the rewritten pins to the workspace links again; the `Prepare Release` workflow (`prepare-release.yml` in this monorepo) does it with its release pull request.
+
 To release packages separately, for example with a release pull request for each, pass `--package <name>`, repeatable, to version only those packages. A changeset that also names other packages keeps only their entries and its summary, so it still applies to their releases with the same bump. Changesets without packages are left for a run without `--package`.
 
 The `changeset-version` result lists each release with its `package`, `bump`, `currentVersion`, `nextVersion` and `changelog` entries, a Markdown list like the one added to `CHANGELOG.md`. Use it to name and describe the release pull request in a repository script, or call `versionChangesets()` from the library and format the entries of each release with `formatChangelogEntries( release.changesets )`.
 
-After merging the release PR, `changeset-tag --since <merge-commit>^1 --push` pushes tags only for packages changed by that release. It pushes one tag at a time because GitHub doesn't trigger workflows for a push of more than three tags. Add `--github-release` to create missing GitHub Releases; it requires `--push`. For initial adoption, preview all missing tags with `changeset-tag --dry-run` (without `--since`), then push if needed. To release each package with a separate workflow instead, `changeset-tag --since <merge-commit>^1 --untagged --github-output` lists the releases that don't have a tag yet, without creating any. Tag pushes need Git write credentials; GitHub Releases need authenticated `gh`.
+After merging the release PR, `changeset-tag --since <merge-commit>^1 --push` pushes tags only for packages changed by that release. It pushes one tag at a time because GitHub doesn't trigger workflows for a push of more than three tags. wp-release doesn't create GitHub Releases: with `--json` or `--github-output`, each entry of `tags` has the `tag`, a `title` like `plugins/alpha@1.2.0`, the release `notes` and a `prerelease` flag, for a workflow step like [`softprops/action-gh-release`](https://github.com/softprops/action-gh-release) to create the release (see the example below). For initial adoption, preview all missing tags with `changeset-tag --dry-run` (without `--since`), then push if needed. To release each package with a separate workflow instead, `changeset-tag --since <merge-commit>^1 --untagged --github-output` lists the releases that don't have a tag yet, without creating any. Tag pushes need Git write credentials.
+
+To release a single package, for example from a manual workflow, pass `--package <name>`, repeatable, and with one package `--version <version>` to fail unless the package is at that version. Packages versioned by git tags have no version file, so for them `--version` is the version to tag. Before a tag is created, every `version.to` target must match the version, so a plugin `Version` header that disagrees with its readme `Stable tag` blocks the tag. Versions with a pre-release part, like `1.0.0-rc.1`, have `prerelease` set, so their GitHub Releases can be marked as pre-releases:
 
-To release a single package, for example from a manual workflow, pass `--package <name>`, repeatable, and with one package `--version <version>` to fail unless the package is at that version. Packages versioned by git tags have no version file, so for them `--version` is the version to tag. Before a tag is created, every `version.to` target must match the version, so a plugin `Version` header that disagrees with its readme `Stable tag` blocks the tag. GitHub Releases of versions with a pre-release part, like `1.0.0-rc.1`, are marked as pre-releases.
+```yaml
+- name: Tag a release
+  id: tag
+  run: npx wp-release changeset-tag --package "$PACKAGE" --version "$VERSION" --push --github-output
+
+# Creates the GitHub Release, or updates it on a rerun.
+- uses: softprops/action-gh-release@v3
+  with:
+    tag_name: ${{ fromJSON( steps.tag.outputs.result ).tags[0].tag }}
+    name: ${{ fromJSON( steps.tag.outputs.result ).tags[0].title }}
+    body: ${{ fromJSON( steps.tag.outputs.result ).tags[0].notes }}
+    prerelease: ${{ fromJSON( steps.tag.outputs.result ).tags[0].prerelease }}
+```
 
 The release notes are the version's `CHANGELOG.md` section, or without one the commits that changed the package since its previous tag, the highest version below the released one. Configure `releaseNotes( { package, version, tag, previousTag, changelog, commits, notes } )` to format them, for example to add links; `notes` is the default text and `commits` lists `{ hash, shortHash, subject }`, newest first. `changeset-tag --package <name> --dry-run` prints them without creating the tag.
 
-For local development, run the TypeScript source with `npm run wp-release -- <command>` (for example, `npm run wp-release -- changeset-status --since origin/main`). GitHub workflows use the same CLI for versioning and tagging. `SUBTREE_DEPLOY_TOKEN` lets them update the release PR, push tags, and create GitHub Releases.
+For local development, run the TypeScript source with `npm run wp-release -- <command>` (for example, `npm run wp-release -- changeset-status --since origin/main`). GitHub workflows use the same CLI for versioning and tagging. `SUBTREE_DEPLOY_TOKEN` lets them update the release PR and push tags, and the `Tag Release` workflow passes it to `softprops/action-gh-release` to create the GitHub Releases.
 
 ### Naming convention
 
@@ -453,6 +507,20 @@ const { revision, created, pushed } = await new GitDeploy(
 
 `resolveGitDeployOptions()` throws a `ValidationError` without a repository URL or with an invalid branch or tag. `GitDeploy` exposes `createTree()`, `fetchPrevious()`, `createRelease()`, `isOutdated()`, `checkTag()`, `getRefsToPush()` and `push()` separately, like `SvnDeploy`, and takes a git command runner from `createGitRunner()` as a dependency. The result has `outdated` when the branch wasn't moved for older source history, the refs to write in `planned` and the refs that were pushed in `pushed`, which is empty in a dry run. `redactUrls()` hides the credentials in URLs.
 
+Changeset releases:
+
+```js
+import { ChangesetRelease } from '@wpelevator/wp-release';
+
+const release = new ChangesetRelease( { cwd: process.cwd() } );
+
+const { missingChangesets } = await release.getStatus( { since: 'origin/main' } );
+const { releases } = await release.version( { dryRun: true } );
+const { tags } = await release.tag( { dryRun: true } );
+```
+
+`ChangesetRelease` runs the `changeset-*` commands: `add()`, `getStatus()`, `version()` and `tag()`, plus `getPlan()` and `getPackages()`. Each call reads the configuration, packages and pending changesets again, so one instance can version and then tag. It takes a git runner from `createGitRunner()` as `git`, so that tests can replace it. The functions `addChangeset()`, `getChangesetStatus()`, `versionChangesets()`, `tagChangesets()`, `getChangesetReleasePlan()` and `getChangesetPackages()` do the same with the default runners, in one call.
+
 ### Logging
 
 `Logger` filters messages by level and passes them to a writer, like the transports of other Node.js loggers. The writer decides how messages look:
@@ -558,6 +626,35 @@ npm run lint --workspace @wpelevator/wp-release
 
 The `wpelevator-source` export condition points at `src/index.ts`. The tests and the `wp-release-deploy-svn` action build use it to work with the source instead of a `dist/` build. It's not set by other tools, so the published package always resolves to `dist/`.
 
+### Architecture
+
+The package uses ES modules as its unit of encapsulation, like most Node.js CLI tools: a module exports a few functions and keeps its helpers private, so there's no class to wrap them in. A class is used only when it holds state across steps or binds dependencies, so that callers and tests can replace them:
+
+- **Workflows with steps** are classes, so that their steps share state and dependencies on the instance: `SvnDeploy` shares the temporary working copy across `prepare()`, `checkout()`, `sync()` and `commit()`, `GitDeploy` binds the options and the git runner to its steps, and `ChangesetRelease` binds the repository and the runners to `add()`, `version()` and `tag()`.
+- **External commands** run through injectable runners: `createSvnRunner()` and `createGitRunner()` return functions that spawn the binary without a shell. The classes take a runner as an option and create the default one when it's missing, so tests pass a fake runner, or one that wraps the real runner and records some commands, instead of putting fake binaries on the `PATH`. The `Svn` and `ReleaseRepository` classes wrap a runner with the commands of their domain.
+- **Domain logic** is plain functions that take their dependencies as arguments, like `discoverPackages( repository, config )`, so that each one can be tested on its own.
+- **Commands** in `src/commands/` parse the CLI options and call the library, and `cli.ts` handles the global options, logging and exit codes. Errors carry their exit code, like `ValidationError` with `2`.
+- Constructors only store their options. Work starts in a method call.
+
+The changeset release modules, from the entry point down:
+
+| Module | Responsibility |
+|---|---|
+| `changeset-release.ts` | `ChangesetRelease`, which plans releases and runs `add()`, `getStatus()`, `version()` and `tag()`, and the function form of each operation. |
+| `changeset-config.ts` | Loading and validating `wp-release.config.js`, and the version source and target helpers. |
+| `changeset-packages.ts` | Discovering the packages of the configured globs and finding the changed ones. |
+| `changeset-files.ts` | Reading, writing and consuming changeset files. |
+| `changeset-dependents.ts` | The dependents policy: which packages re-release with their sources, and rewriting their dependency specs. |
+| `changesets.ts` | Parsing and formatting changesets, and the release types. |
+| `version-files.ts` | Reading and writing versions in manifests, headers, readmes and PHP constants. |
+| `changelog.ts` | Changelog entries, and the `CHANGELOG.md` and readme changelog sections. |
+| `release-tags.ts` | Choosing the version and previous tag of a release, and building its release notes. |
+| `tag-format.ts` | Formatting tag names from the tag format. |
+| `release-repository.ts` | `ReleaseRepository`, the git commands of a release: tags, commits and changed files. |
+| `github.ts` | Finding the pull request of a commit with the GitHub CLI, for changelog formatters. |
+| `file-journal.ts` | `FileJournal`, which restores every file a failed `changeset-version` run changed. |
+| `versions.ts` | Version checks and SemVer precedence. |
+
 ## Comparison with existing tools
 
 | Tool | What it does | How `wp-release` differs |

package/dist/changelog.d.ts

@@ -0,0 +1,45 @@
+import type { ChangesetConfig } from './changeset-config.ts';
+import type { PackageRelease, VersionedRelease } from './changesets.ts';
+import type { FileJournal } from './file-journal.ts';
+import type { ReleaseRepository } from './release-repository.ts';
+/**
+ * Format the changelog entries of each release, with the configured
+ * formatter and the commit that added each changeset.
+ *
+ * @param repository         Repository, for the commit of each changeset.
+ * @param config             Repository release configuration.
+ * @param releases           Package releases.
+ * @param changesetDirectory Directory of the changeset files.
+ * @return Releases with their changelog entries.
+ */
+export declare function getVersionedReleases(repository: ReleaseRepository, config: ChangesetConfig, releases: PackageRelease[], changesetDirectory: string): Promise<VersionedRelease[]>;
+/**
+ * Add the changelog section of a release to the CHANGELOG.md of the package,
+ * and with readmeChangelog to the changelog of its plugin readme. A release
+ * that already has a section is left as it is.
+ *
+ * @param  directory            Package directory.
+ * @param  release              Versioned release.
+ * @param  date                 Release date, as YYYY-MM-DD.
+ * @param  readmeChangelog      Whether to update the plugin readme too.
+ * @param  changelogInsertAfter Marker to insert the section after, if configured.
+ * @param  journal              File journal for rolling back.
+ * @throws {ValidationError} If the configured marker isn't found.
+ */
+export declare function prependChangelog(directory: string, release: VersionedRelease, date: string, readmeChangelog: boolean, changelogInsertAfter: string | undefined, journal: FileJournal): Promise<void>;
+/**
+ * Read the CHANGELOG.md section of a version, without its heading.
+ *
+ * @param directory Package directory.
+ * @param version   Released version.
+ * @return Section contents, empty without a section.
+ */
+export declare function readChangelogSection(directory: string, version: string): Promise<string>;
+/**
+ * Read the newest stable version with a CHANGELOG.md section.
+ *
+ * @param directory Package directory.
+ * @param fallback  Version to return without a changelog or a version section.
+ * @return Latest changelog version.
+ */
+export declare function getLatestChangelogVersion(directory: string, fallback: string): Promise<string>;

package/dist/changelog.js

@@ -0,0 +1,246 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { formatChangelogList } from "./changesets.js";
+import { ValidationError } from "./errors.js";
+import { escapeRegExp } from "./regexp.js";
+/**
+ * Format the changelog entries of each release, with the configured
+ * formatter and the commit that added each changeset.
+ *
+ * @param repository         Repository, for the commit of each changeset.
+ * @param config             Repository release configuration.
+ * @param releases           Package releases.
+ * @param changesetDirectory Directory of the changeset files.
+ * @return Releases with their changelog entries.
+ */
+export async function getVersionedReleases(repository, config, releases, changesetDirectory) {
+    const commits = new Map();
+    const getCommit = (changeset) => {
+        const cached = commits.get(changeset.fileName) ??
+            repository.getAddedCommit(path.join(changesetDirectory, changeset.fileName));
+        commits.set(changeset.fileName, cached);
+        return cached;
+    };
+    const releasesByName = new Map(releases.map((release) => [release.package.name, release]));
+    return Promise.all(releases.map(async (release) => {
+        const entries = [];
+        // Format one at a time, so that formatters calling an API aren't rate limited.
+        for (const changeset of release.changesets) {
+            entries.push(await getChangelogEntry(config, release.package, changeset, getCommit));
+        }
+        for (const sourceName of release.sources ?? []) {
+            const source = releasesByName.get(sourceName);
+            if (!source) {
+                throw new ValidationError(`The dependent package "${release.package.name}" bundles unreleased package "${sourceName}".`);
+            }
+            entries.push(await getDependentsChangelogEntry(config, release.package, source));
+        }
+        return { ...release, changelog: formatChangelogList(entries) };
+    }));
+}
+/**
+ * Format the bundle changelog entry of a dependent release.
+ *
+ * @param config Repository release configuration.
+ * @param pkg    Dependent package being re-released.
+ * @param source Released source package bundled by the dependent.
+ * @return Changelog entry.
+ */
+async function getDependentsChangelogEntry(config, pkg, source) {
+    if (!config.dependents?.changelog) {
+        return `Bundle ${source.package.name.split('/').pop()} ${source.nextVersion}.`;
+    }
+    const entry = await config.dependents.changelog({
+        package: pkg,
+        source: {
+            package: source.package,
+            version: source.nextVersion,
+        },
+    });
+    if ('string' !== typeof entry) {
+        throw new ValidationError(`The dependents changelog formatter didn't return a string for package "${pkg.name}".`);
+    }
+    return entry.trim();
+}
+/**
+ * Format the changelog entry of a changeset with the configured formatter.
+ *
+ * @param config    Repository release configuration.
+ * @param pkg       Released package.
+ * @param changeset Changeset of the release.
+ * @param getCommit Get the commit that added a changeset.
+ * @return Changelog entry, the plain summary without a formatter.
+ */
+async function getChangelogEntry(config, pkg, changeset, getCommit) {
+    const summary = changeset.summary.trim();
+    if (!summary || !config.changelogEntry) {
+        return summary;
+    }
+    const commit = await getCommit(changeset);
+    const entry = await config.changelogEntry({
+        package: pkg,
+        changeset,
+        ...(commit ? { commit } : {}),
+    });
+    if ('string' !== typeof entry) {
+        throw new ValidationError(`The changelogEntry formatter didn't return a string for changeset ${changeset.fileName}.`);
+    }
+    return entry.trim();
+}
+/**
+ * Add the changelog section of a release to the CHANGELOG.md of the package,
+ * and with readmeChangelog to the changelog of its plugin readme. A release
+ * that already has a section is left as it is.
+ *
+ * @param  directory            Package directory.
+ * @param  release              Versioned release.
+ * @param  date                 Release date, as YYYY-MM-DD.
+ * @param  readmeChangelog      Whether to update the plugin readme too.
+ * @param  changelogInsertAfter Marker to insert the section after, if configured.
+ * @param  journal              File journal for rolling back.
+ * @throws {ValidationError} If the configured marker isn't found.
+ */
+export async function prependChangelog(directory, release, date, readmeChangelog, changelogInsertAfter, journal) {
+    const summaries = release.changesets
+        .map((item) => item.summary.trim())
+        .filter(Boolean);
+    const section = `## ${release.nextVersion} (${date})\n\n${release.changelog}\n\n`;
+    const changelog = path.join(directory, 'CHANGELOG.md');
+    let previous = '';
+    try {
+        previous = await readFile(changelog, 'utf8');
+    }
+    catch (error) {
+        if ('ENOENT' !== error.code) {
+            throw error;
+        }
+    }
+    const releaseHeading = new RegExp(`^## ${escapeRegExp(release.nextVersion)} \\(`, 'm');
+    if (!releaseHeading.test(previous)) {
+        await journal.remember(changelog);
+        if (undefined !== changelogInsertAfter) {
+            await writeFile(changelog, insertAfterMarker(previous, changelogInsertAfter, section, changelog));
+        }
+        else {
+            const versionHeading = /^##[ \t]+v?\d+(?:\.\d+){1,2}(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?(?:[ \t]+.*)?$/m.exec(previous);
+            const heading = /^#[ \t]+[^\r\n]+[ \t]*$/m.exec(previous);
+            const insertion = versionHeading ?? heading;
+            if (insertion) {
+                const before = previous
+                    .slice(0, insertion.index)
+                    .replace(/(?:\r?\n)*$/, '');
+                const after = previous.slice(insertion.index);
+                const prefix = before ? `${before}\n\n` : '';
+                await writeFile(changelog, `${prefix}${section}${after}`);
+            }
+            else {
+                await writeFile(changelog, `${section}${previous}`);
+            }
+        }
+    }
+    if (readmeChangelog) {
+        const readme = ['readme.txt', 'readme.md'].map((name) => path.join(directory, name));
+        let readmeUpdated = false;
+        let readmeFound = false;
+        let readmeMarkerFound = false;
+        let readmeAlreadyVersioned = false;
+        for (const file of readme) {
+            try {
+                const contents = await readFile(file, 'utf8');
+                readmeFound = true;
+                const defaultHeading = undefined === changelogInsertAfter
+                    ? /^==\s*Changelog\s*==\s*$/im.exec(contents)?.[0]
+                    : undefined;
+                const insertionMarker = changelogInsertAfter ?? defaultHeading;
+                readmeMarkerFound ||=
+                    undefined !== insertionMarker &&
+                        contents.includes(insertionMarker);
+                const alreadyVersioned = new RegExp(`^=\\s*${escapeRegExp(release.nextVersion)}\\s*=$`, 'm').test(contents);
+                readmeAlreadyVersioned ||= alreadyVersioned;
+                if (insertionMarker &&
+                    !alreadyVersioned &&
+                    !readmeUpdated &&
+                    contents.includes(insertionMarker)) {
+                    const readmeSection = `\n\n= ${release.nextVersion} =\n\n${summaries
+                        .map((item) => `* ${item.replaceAll(/\r?\n/g, '\n  ')}`)
+                        .join('\n')}\n\n`;
+                    await journal.remember(file);
+                    await writeFile(file, insertAfterMarker(contents, insertionMarker, readmeSection.trimStart(), file));
+                    readmeUpdated = true;
+                }
+            }
+            catch (error) {
+                if ('ENOENT' !== error.code) {
+                    throw error;
+                }
+            }
+        }
+        if (changelogInsertAfter &&
+            readmeFound &&
+            !readmeMarkerFound &&
+            !readmeAlreadyVersioned) {
+            throw new ValidationError(`Changelog insertion marker "${changelogInsertAfter}" was not found in a plugin readme in ${directory}.`);
+        }
+    }
+}
+/**
+ * Read the CHANGELOG.md section of a version, without its heading.
+ *
+ * @param directory Package directory.
+ * @param version   Released version.
+ * @return Section contents, empty without a section.
+ */
+export async function readChangelogSection(directory, version) {
+    let contents = '';
+    try {
+        contents = await readFile(path.join(directory, 'CHANGELOG.md'), 'utf8');
+    }
+    catch (error) {
+        if ('ENOENT' !== error.code) {
+            throw error;
+        }
+    }
+    const lines = contents.split(/\r?\n/);
+    const headingIndex = lines.findIndex((line) => new RegExp(`^##\\s+${escapeRegExp(version)}(?:\\s|$)`).test(line));
+    if (-1 === headingIndex) {
+        return '';
+    }
+    const followingHeading = lines.findIndex((line, index) => index > headingIndex && /^##\s/.test(line));
+    const end = -1 === followingHeading ? lines.length : followingHeading;
+    return lines
+        .slice(headingIndex + 1, end)
+        .join('\n')
+        .trim();
+}
+/**
+ * Read the newest stable version with a CHANGELOG.md section.
+ *
+ * @param directory Package directory.
+ * @param fallback  Version to return without a changelog or a version section.
+ * @return Latest changelog version.
+ */
+export async function getLatestChangelogVersion(directory, fallback) {
+    try {
+        const contents = await readFile(path.join(directory, 'CHANGELOG.md'), 'utf8');
+        const match = /^##\s+(\d+\.\d+\.\d+)(?:\s|$)/m.exec(contents);
+        return match?.[1] ?? fallback;
+    }
+    catch (error) {
+        if ('ENOENT' === error.code) {
+            return fallback;
+        }
+        throw error;
+    }
+}
+function insertAfterMarker(contents, marker, section, file) {
+    const index = contents.indexOf(marker);
+    if (-1 === index) {
+        throw new ValidationError(`Changelog insertion marker "${marker}" was not found in ${file}.`);
+    }
+    const markerEnd = index + marker.length;
+    const after = contents
+        .slice(markerEnd)
+        .replace(/^(?:[ \t]*\r?\n)+/, '');
+    const lineEnding = contents.includes('\r\n') ? '\r\n' : '\n';
+    return `${contents.slice(0, markerEnd)}${lineEnding}${lineEnding}${section.replaceAll('\n', lineEnding)}${after}`;
+}

package/dist/changeset-config.d.ts

@@ -69,6 +69,79 @@ export interface ChangesetPackageGroup {
     /** Version source and files to update for every discovered package. */
     version: PackageVersionConfig;
 }
+/** Inputs supplied to a dependents changelog formatter. */
+export interface DependentsChangelogInput {
+    /** The dependent package being re-released. */
+    package: ChangesetPackage;
+    /** The released source package that the dependent bundles. */
+    source: {
+        package: ChangesetPackage;
+        /** Version of the source release. */
+        version: string;
+    };
+}
+/** Inputs supplied to a dependents dependency finder. */
+export interface DependentsFindInput {
+    /** The dependent package. */
+    package: ChangesetPackage;
+    /** The source package. */
+    source: ChangesetPackage;
+}
+/** A dependency of a source that a package declares outside package.json. */
+export interface DependentsSpec {
+    /** Manifest file that declares the dependency, relative to the dependent package. */
+    file: string;
+    /** Identifier that holds the spec, like a Composer package name. */
+    name: string;
+    /** Declared spec of the source. */
+    spec: string;
+}
+/** Inputs supplied to a dependents dependency update. */
+export interface DependentsUpdateInput {
+    /** The dependent package whose declaration gets updated. */
+    package: ChangesetPackage;
+    /** The released source package. */
+    source: ChangesetPackage;
+    /** Released version of the source. */
+    version: string;
+    /** The specs to update, with their manifest files and identifiers. */
+    specs: DependentsSpec[];
+    /** Snapshot a file before writing it, so that failed versioning rolls it back. */
+    remember: (file: string) => Promise<void>;
+}
+/** How packages find and update their dependency of a source. */
+export interface DependentsDependencyOptions {
+    /** Specs of the source that a package declares outside package.json, added to the built-in npm scan, so that the range rule and the rewrite apply to them the same way. */
+    find?: (input: DependentsFindInput) => Promise<DependentsSpec[]>;
+    /** Update a package's declared dependency of a released source to the released version; defaults to rewriting the found specs, keeping their range prefixes. Call `remember()` with every file path before writing it. */
+    update?: (input: DependentsUpdateInput) => Promise<void>;
+}
+/** npm dependency section that the dependents of a policy scan. */
+export type DependentsSection = 'dependencies' | 'optionalDependencies' | 'peerDependencies' | 'devDependencies';
+/**
+ * Packages that bundle another configured package, re-released whenever that
+ * source releases, so that their shipped build includes the new version. The
+ * dependents come from the dependencies that each package declares, like the
+ * npm packages depending on another through package.json: a package is a
+ * dependent of a source when its declared spec resolves the source's current
+ * version or points at the workspace, and it releases when the next version
+ * of the source falls outside its declared range, or always with
+ * `when: 'always'`.
+ */
+export interface DependentsConfig {
+    /** Bump applied to dependents that release without their own changeset; defaults to patch. */
+    bump?: 'patch' | 'minor' | 'major';
+    /** Package paths, identifiers or globs never re-released as dependents; they still release with their own changesets. */
+    exclude?: string[];
+    /** Whether dependents release only when the next source version falls outside their declared ranges, or always; defaults to out-of-range. */
+    when?: 'out-of-range' | 'always';
+    /** npm dependency sections scanned for sources; defaults to dependencies and optionalDependencies, with devDependencies for dependencies that get bundled into the dependent's build. */
+    sections?: DependentsSection[];
+    /** Overrides of the built-in npm lookup and spec rewrite, for dependencies that other manifests declare. */
+    dependency?: DependentsDependencyOptions;
+    /** Changelog entry added to the dependent, for example a bundle note; defaults to "Bundle <source> <version>." */
+    changelog?: (input: DependentsChangelogInput) => string | Promise<string>;
+}
 /** JavaScript configuration for changeset-aware releases. */
 export interface ChangesetConfig {
     /** Branch receiving ordinary changes. */
@@ -91,6 +164,8 @@ export interface ChangesetConfig {
     releaseNotes?: (input: ReleaseNotesInput) => string | Promise<string>;
     /** Format the CHANGELOG.md entry of a changeset, for example to credit its pull request. */
     changelogEntry?: (input: ChangelogEntryInput) => string | Promise<string>;
+    /** Groups of packages re-released whenever one of their source packages releases. */
+    dependents?: DependentsConfig;
 }
 /** Inputs supplied to a custom next-version strategy. */
 export interface NextVersionInput {

package/dist/changeset-config.js

@@ -198,6 +198,54 @@ function validateChangesetConfig(config, configFile) {
         'function' !== typeof candidate.changelogEntry) {
         throw new ValidationError(`wp-release config ${configFile}.changelogEntry must be a function.`);
     }
+    if (undefined !== candidate.dependents &&
+        ('object' !== typeof candidate.dependents ||
+            Array.isArray(candidate.dependents) ||
+            null === candidate.dependents)) {
+        throw new ValidationError(`wp-release config ${configFile}.dependents must be an object.`);
+    }
+    const dependentsOptions = candidate.dependents;
+    if (undefined !== dependentsOptions?.bump &&
+        !['patch', 'minor', 'major'].includes(dependentsOptions.bump)) {
+        throw new ValidationError(`wp-release config ${configFile}.dependents.bump must be patch, minor or major.`);
+    }
+    if (undefined !== dependentsOptions?.exclude &&
+        (!Array.isArray(dependentsOptions.exclude) ||
+            !dependentsOptions.exclude.length ||
+            dependentsOptions.exclude.some((item) => 'string' !== typeof item || !item.trim()))) {
+        throw new ValidationError(`wp-release config ${configFile}.dependents.exclude must be an array of non-empty strings.`);
+    }
+    if (undefined !== dependentsOptions?.when &&
+        !['out-of-range', 'always'].includes(dependentsOptions.when)) {
+        throw new ValidationError(`wp-release config ${configFile}.dependents.when must be out-of-range or always.`);
+    }
+    if (undefined !== dependentsOptions?.sections &&
+        (!Array.isArray(dependentsOptions.sections) ||
+            !dependentsOptions.sections.length ||
+            dependentsOptions.sections.some((section) => ![
+                'dependencies',
+                'optionalDependencies',
+                'peerDependencies',
+                'devDependencies',
+            ].includes(section)))) {
+        throw new ValidationError(`wp-release config ${configFile}.dependents.sections must be a list of dependencies, optionalDependencies, peerDependencies or devDependencies.`);
+    }
+    if (undefined !== dependentsOptions?.changelog &&
+        'function' !== typeof dependentsOptions.changelog) {
+        throw new ValidationError(`wp-release config ${configFile}.dependents.changelog must be a function.`);
+    }
+    if (undefined !== dependentsOptions?.dependency) {
+        if ('object' !== typeof dependentsOptions.dependency ||
+            null === dependentsOptions.dependency) {
+            throw new ValidationError(`wp-release config ${configFile}.dependents.dependency must be an object.`);
+        }
+        ['find', 'update'].forEach((key) => {
+            if (undefined !== dependentsOptions.dependency[key] &&
+                'function' !== typeof dependentsOptions.dependency[key]) {
+                throw new ValidationError(`wp-release config ${configFile}.dependents.dependency.${key} must be a function.`);
+            }
+        });
+    }
     if (undefined !== candidate.releaseNotes &&
         'function' !== typeof candidate.releaseNotes) {
         throw new ValidationError(`wp-release config ${configFile}.releaseNotes must be a function.`);