@wpelevator/wp-release 0.10.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"]
 ```
@@ -186,13 +186,27 @@ To release packages separately, for example with a release pull request for each
 
 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. GitHub Releases of versions with a pre-release part, like `1.0.0-rc.1`, are 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. 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:
+
+```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
 
@@ -493,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:
@@ -598,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-dependents.d.ts

@@ -0,0 +1,132 @@
+import type { ChangesetConfig, DependentsConfig } from './changeset-config.ts';
+import type { ChangedPackages, ConfiguredPackage } from './changeset-packages.ts';
+import type { Changeset, ChangesetPackage, ChangesetReleasePlan, PackageRelease } from './changesets.ts';
+import type { FileJournal } from './file-journal.ts';
+/**
+ * A declared dependency of a package on another configured package.
+ */
+export interface DependencySpec {
+    /** Absolute path of the manifest that declares the dependency. */
+    file: string;
+    /** Dependency name in the manifest, like the npm package name. */
+    name: string;
+    /** Declared spec, like ^1.2.0 or workspace:*. */
+    spec: string;
+}
+/**
+ * Add releases for dependents of packages that release, applying the
+ * configured dependents policy until the plan settles.
+ *
+ * @param releases Planned releases, mutated in place.
+ * @param packages Discovered packages.
+ * @param config   Repository release configuration.
+ */
+export declare function applyDependents(releases: PackageRelease[], packages: ConfiguredPackage[], config: ChangesetConfig): Promise<void>;
+/**
+ * Limit a release plan to some packages and the changesets that name them.
+ *
+ * @param  plan           Release plan of all pending changesets.
+ * @param  packages       Configured packages.
+ * @param  names          Packages to version.
+ * @param  config         Repository release configuration.
+ * @param  withDependents Whether the selection also releases the dependents of the selected sources.
+ * @return Release plan of the selected packages and their dependents.
+ * @throws {ValidationError} For unknown packages.
+ */
+export declare function selectReleasePlan(plan: ChangesetReleasePlan, packages: ConfiguredPackage[], names: string[], config: ChangesetConfig, withDependents?: boolean): Promise<ChangesetReleasePlan>;
+/**
+ * Drop bundle sources that aren't released by the selected plan.
+ *
+ * @param plan Selected release plan.
+ * @return Release plan with dependents bundling only its released sources.
+ */
+export declare function expandDependentsPlan(plan: ChangesetReleasePlan): ChangesetReleasePlan;
+/**
+ * Remove the derived dependent releases of a plan, keeping only the releases
+ * of packages that have their own changesets.
+ *
+ * @param plan Release plan of all pending changesets.
+ * @return Release plan without derived dependent releases.
+ */
+export declare function stripDependentsPlan(plan: ChangesetReleasePlan): ChangesetReleasePlan;
+/**
+ * Fail when a planned release bundles a source package that has pending
+ * changesets released by a later run, so that no dependent ships unreleased
+ * code under a changelog that cannot credit it.
+ *
+ * @param  plan     Planned releases.
+ * @param  fullPlan Release plan of all pending changesets.
+ * @param  packages Discovered packages.
+ * @param  config   Repository release configuration.
+ * @throws {ValidationError} If a source of a planned release stays pending.
+ */
+export declare function assertDependentsSourcesReleased(plan: ChangesetReleasePlan, fullPlan: ChangesetReleasePlan, packages: ConfiguredPackage[], config: ChangesetConfig): Promise<void>;
+/**
+ * Find the changed packages that need no changeset of their own, because the
+ * dependents policy releases them with their sources. A dependent releases
+ * with its sources, which the release pull request already announces when
+ * the changesets of the diff release one of them. Exempting its package
+ * manifest pin change keeps the check from demanding an entry for what
+ * versioning rewrites anyway; documentation and code changes still need
+ * their own changesets.
+ *
+ * @param changed          Changed packages and their files.
+ * @param changesetsInDiff Changesets added or changed by the diff.
+ * @param packages         Discovered packages.
+ * @param config           Repository release configuration.
+ * @return Names of the packages whose only changes are manifests of released dependents.
+ */
+export declare function findBundledPinChanges(changed: ChangedPackages, changesetsInDiff: Changeset[], packages: ConfiguredPackage[], config: ChangesetConfig): Promise<Set<string>>;
+/**
+ * Check whether a changeset names a package.
+ *
+ * @param changesets Changesets.
+ * @param name       Package name.
+ * @return Whether one of the changesets names the package.
+ */
+export declare function hasChangeset(changesets: Changeset[], name: string): boolean;
+/**
+ * Update how a dependent declares its dependency on a released source, with
+ * the configured hook or the built-in spec rewrite.
+ *
+ * @param input           Dependent, source, released version, policy and journal.
+ * @param input.dependent The released dependent package.
+ * @param input.source    Released source package that the dependent bundles.
+ * @param input.version   Released version of the source.
+ * @param input.rule      Dependents policy with its sections and dependency hooks.
+ * @param input.journal   File journal for rolling back.
+ */
+export declare function updateDependencyDeclaration(input: {
+    dependent: ChangesetPackage;
+    source: ChangesetPackage;
+    version: string;
+    rule?: DependentsConfig;
+    journal: FileJournal;
+}): Promise<void>;
+/**
+ * Update a dependency spec to the released version, keeping its shape, like
+ * the caret of ^0.9.0 or the x of 0.9.x.
+ *
+ * @param spec    Declared spec of the source.
+ * @param version Released version of the source.
+ * @return The updated spec, undefined when nothing has to change, like a wildcard or a workspace spec, or null when the spec can't be rewritten.
+ */
+export declare function updatedSpec(spec: string, version: string): string | null | undefined;
+/**
+ * Warn about declared pins of configured packages that don't resolve the
+ * current version of the package they name.
+ *
+ * @param config   Repository release configuration.
+ * @param packages Discovered packages.
+ * @return Warnings, one per package pair.
+ */
+export declare function collectPinDriftWarnings(config: ChangesetConfig, packages: ConfiguredPackage[]): Promise<string[]>;
+/**
+ * Check whether a spec points at the workspace copy of a package, by
+ * resolving the current version through its range or its workspace protocol.
+ *
+ * @param spec           Declared spec of the source.
+ * @param currentVersion Current version of the source package.
+ * @return Whether the spec is a dependency of the source.
+ */
+export declare function isDependencyOfSource(spec: string, currentVersion: string): boolean;