@wpelevator/wp-release 0.9.0 → 0.10.0

package/README.md

@@ -142,6 +142,46 @@ 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 )`.

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.`);

package/dist/changeset-release.d.ts

@@ -8,6 +8,8 @@ export interface ChangesetVersionInput extends ChangesetRepository {
     date?: string;
     /** Version only these packages, leaving the other changesets pending. */
     packages?: string[];
+    /** Whether the selected sources release their configured dependents; defaults to true. */
+    dependents?: boolean;
 }
 /** Versioned releases, the applied changesets and whether files were changed. */
 export interface VersionChangesetsResult {
@@ -93,4 +95,5 @@ export declare function getChangesetStatus(input: ChangesetRepository & {
     changedPackages: string[];
     changedPackageFiles: Record<string, string[]>;
     missingChangesets: string[];
+    warnings: string[];
 }>;

package/dist/changeset-release.js

@@ -8,7 +8,11 @@ import { findMainPluginFile } from "./package-meta.js";
 import { findConstantValues } from "./version-check.js";
 import { formatChangelogList, formatChangeset, getChangesetBump, getNextVersion, parseChangeset, } from "./changesets.js";
 import { ValidationError } from "./errors.js";
+import semverSatisfies from 'semver/functions/satisfies.js';
+import validRange from 'semver/ranges/valid.js';
 const execFileAsync = promisify(execFile);
+/** npm dependency sections whose declared dependency re-releases the dependent. */
+const DEFAULT_SECTIONS = ['dependencies', 'optionalDependencies'];
 /**
  * Discover configured packages, pending changesets, and their proposed versions.
  *
@@ -71,8 +75,238 @@ async function getReleaseContext(input) {
             }
         });
     });
+    await applyDependents(releases, packages, config);
     return { config, packages, plan: { changesets, releases } };
 }
+/**
+ * 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.
+ */
+async function applyDependents(releases, packages, config) {
+    const rule = config.dependents;
+    if (!rule) {
+        return;
+    }
+    // Dependents may themselves be dependents of other sources, so expand until stable.
+    let grew = true;
+    while (grew) {
+        grew = false;
+        for (const source of [...releases]) {
+            for (const dependent of packages) {
+                if (await deriveDependentRelease(source, dependent, releases, rule)) {
+                    grew = true;
+                }
+            }
+        }
+    }
+}
+/**
+ * Plan the release of a package that bundles a source package, or add the
+ * source to the bundle list of its own pending release.
+ *
+ * @param source    Package release of the source.
+ * @param dependent Package that would bundle the source.
+ * @param releases  Planned releases, mutated in place.
+ * @param rule      Dependents policy.
+ * @return Whether a new dependent release was planned.
+ */
+async function deriveDependentRelease(source, dependent, releases, rule) {
+    if (dependent.name === source.package.name ||
+        isExcludedDependent(dependent, rule)) {
+        return false;
+    }
+    const specs = await findDependencySpecs(dependent, source.package, rule);
+    if (!specs.length || !dependentNeedsRelease(specs, source, rule)) {
+        return false;
+    }
+    const release = releases.find((item) => item.package.name === dependent.name);
+    if (release) {
+        const sources = release.sources ?? [];
+        if (!sources.includes(source.package.name)) {
+            // A dependent that releases for its own reasons still notes the bundle.
+            release.sources = [...sources, source.package.name];
+        }
+        return false;
+    }
+    const bump = rule.bump ?? 'patch';
+    releases.push({
+        package: dependent,
+        bump,
+        currentVersion: dependent.currentVersion,
+        nextVersion: getNextVersion(dependent.currentVersion, bump),
+        changesets: [],
+        sources: [source.package.name],
+    });
+    return true;
+}
+/**
+ * Find the specs through which a package declares a dependency on another.
+ *
+ * A spec is a dependency of the source that the current version resolves,
+ * like a range that covers it or a workspace spec, or one that the
+ * configured hook reports. A pin like an older version of the source
+ * selects a registry release instead, which keeps the local code out of
+ * the dependent's build.
+ *
+ * @param dependent Package potentially declaring the dependency.
+ * @param source    Released source package.
+ * @param rule      Dependents policy, with its dependency hook and sections.
+ * @return The declared specs, with their manifest files and package names.
+ */
+async function findDependencySpecs(dependent, source, rule) {
+    const sourceManifest = await readJsonSafe(path.join(source.directory, 'package.json'));
+    if ('string' !== typeof sourceManifest?.name) {
+        return rule?.dependency?.find
+            ? findDependencyHookSpecs(dependent, source, rule)
+            : [];
+    }
+    const identifier = sourceManifest.name;
+    const specs = [];
+    const parsed = await readJsonSafe(path.join(dependent.directory, 'package.json'));
+    for (const section of dependentsSections(rule)) {
+        const sectionSpecs = parsed?.[section];
+        const declared = 'object' === typeof sectionSpecs &&
+            null !== sectionSpecs &&
+            Object.hasOwn(sectionSpecs, identifier)
+            ? String(sectionSpecs[identifier])
+            : undefined;
+        if (undefined !== declared &&
+            isDependencyOfSource(declared, source.currentVersion)) {
+            specs.push({
+                file: path.join(dependent.directory, 'package.json'),
+                name: identifier,
+                spec: declared,
+            });
+        }
+    }
+    if (rule?.dependency?.find) {
+        specs.push(...(await findDependencyHookSpecs(dependent, source, rule)));
+    }
+    return specs;
+}
+/**
+ * Find the specs that the configured dependency hook reports.
+ *
+ * @param dependent Package potentially declaring the dependency.
+ * @param source    Released source package.
+ * @param rule      Dependents policy.
+ * @return The hook's specs, with absolute manifest paths and package names.
+ */
+async function findDependencyHookSpecs(dependent, source, rule) {
+    const found = await rule.dependency?.find?.({
+        package: dependent,
+        source,
+    });
+    return (found ?? []).map((entry) => ({
+        file: path.resolve(dependent.directory, entry.file),
+        name: entry.name,
+        spec: entry.spec,
+    }));
+}
+/**
+ * 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.
+ */
+function isDependencyOfSource(spec, currentVersion) {
+    if (spec.startsWith('workspace:')) {
+        return true;
+    }
+    const range = effectiveRange(spec, currentVersion);
+    return (validRange(range) !== null && semverSatisfies(currentVersion, range));
+}
+/**
+ * The dependency sections that a dependents policy scans.
+ *
+ * @param rule Dependents policy.
+ * @return Dependency section names.
+ */
+function dependentsSections(rule) {
+    return (rule?.sections ?? DEFAULT_SECTIONS);
+}
+/**
+ * Check whether a dependent has to release when its declared source releases.
+ *
+ * @param specs  Declared specs of the source in the dependent.
+ * @param source Released source package.
+ * @param rule   Dependents policy.
+ * @return Whether the dependent needs a release.
+ */
+function dependentNeedsRelease(specs, source, rule) {
+    if ('always' === rule.when) {
+        return true;
+    }
+    // Without a range that accepts the next version, like an exact pin, the
+    // dependent has to release and rewrite its specs.
+    return specs.some(({ spec }) => isOutOfRange(source.nextVersion, spec, source.currentVersion));
+}
+/**
+ * Check whether a version falls outside a declared range.
+ *
+ * @param nextVersion    Next version of the source package.
+ * @param spec           Declared spec of the source).
+ * @param currentVersion Current version of the source package.
+ * @return Whether the next version falls outside the range.
+ */
+function isOutOfRange(nextVersion, spec, currentVersion) {
+    const range = effectiveRange(spec, currentVersion);
+    if (validRange(range) === null) {
+        // Unrecognized ranges of dependencies like git URLs are left to the consumer.
+        return false;
+    }
+    return !semverSatisfies(nextVersion, range);
+}
+/**
+ * Resolve a dependency spec to the range it selects for an internal package.
+ *
+ * @param spec           Declared spec.
+ * @param currentVersion Current version of the source package.
+ * @return The effective semver range.
+ */
+function effectiveRange(spec, currentVersion) {
+    if (!spec.startsWith('workspace:')) {
+        return spec;
+    }
+    // Workspace specs resolve to the exact published version, and to a
+    // prefixed one with their operator.
+    const bare = spec.slice('workspace:'.length);
+    if ('*' === bare) {
+        return currentVersion;
+    }
+    if ('^' === bare || '~' === bare) {
+        return `${bare}${currentVersion}`;
+    }
+    return bare;
+}
+/**
+ * Check whether the dependents policy excludes a package.
+ *
+ * @param dependent Candidate dependent package.
+ * @param rule      Dependents policy.
+ * @return Whether the package is excluded from re-releases.
+ */
+function isExcludedDependent(dependent, rule) {
+    return (rule.exclude ?? []).some((pattern) => pattern === dependent.name ||
+        globRegExp(pattern).test(dependent.path));
+}
+async function readJsonSafe(file) {
+    try {
+        return JSON.parse(await readFile(file, 'utf8'));
+    }
+    catch (error) {
+        if ('ENOENT' !== error.code) {
+            throw error;
+        }
+        return undefined;
+    }
+}
 /**
  * Create a Changesets-compatible Markdown file.
  *
@@ -123,9 +357,21 @@ export async function versionChangesets(input) {
         throw new ValidationError('No wp-release config found. Add wp-release.config.js or pass --config <path>.');
     }
     const { config, packages } = context;
-    const releasePlan = input.packages
-        ? selectReleasePlan(context.plan, packages, input.packages)
-        : context.plan;
+    const withDependents = input.dependents ?? true;
+    let releasePlan = context.plan;
+    if (input.packages) {
+        releasePlan = expandDependentsPlan(await selectReleasePlan(context.plan, packages, input.packages, config, withDependents));
+    }
+    else if (!withDependents) {
+        releasePlan = stripDependentsPlan(context.plan);
+    }
+    // A dependent must not release while one of the packages it depends on has
+    // pending changesets that aren't released in the same run, or it would
+    // bundle unreleased code under a changelog that cannot credit it. The
+    // check only applies to repositories that adopted the dependents policy.
+    if (withDependents && config.dependents) {
+        await assertDependentsSourcesReleased(releasePlan, context.plan, packages, config);
+    }
     const date = input.date ?? new Date().toISOString().slice(0, 10);
     const changesetDirectory = path.resolve(input.cwd, config.changesets ?? '.changeset');
     const releases = await getVersionedReleases(input.cwd, config, releasePlan.releases, changesetDirectory);
@@ -140,6 +386,19 @@ export async function versionChangesets(input) {
                 for (const target of configured.versionConfig.to) {
                     await writeVersion(configured.directory, target, release.nextVersion, journal);
                 }
+                for (const sourceName of release.sources ?? []) {
+                    const source = releasePlan.releases.find((item) => item.package.name === sourceName);
+                    if (!source) {
+                        throw new ValidationError(`The dependent package "${release.package.name}" bundles unreleased package "${sourceName}".`);
+                    }
+                    await updateDependencyDeclaration({
+                        dependent: release.package,
+                        source: source.package,
+                        version: source.nextVersion,
+                        rule: config.dependents,
+                        journal,
+                    });
+                }
                 await verifyVersionTargets(input.cwd, configured, release.nextVersion);
                 await prependChangelog(configured.directory, release, date, config.readmeChangelog ?? false, config.changelogInsertAfter, journal);
             }
@@ -159,9 +418,183 @@ export async function versionChangesets(input) {
         changesets: releasePlan.changesets,
         releases,
         date,
-        changed: !input.dryRun && releasePlan.changesets.length > 0,
+        changed: !input.dryRun &&
+            (releasePlan.changesets.length > 0 ||
+                releasePlan.releases.length > 0),
     };
 }
+/**
+ * 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.
+ */
+function expandDependentsPlan(plan) {
+    const released = new Set(plan.releases.map((release) => release.package.name));
+    plan.releases.forEach((release) => {
+        if (release.sources) {
+            release.sources = release.sources.filter((name) => released.has(name));
+            if (!release.sources.length) {
+                delete release.sources;
+            }
+        }
+    });
+    return plan;
+}
+/**
+ * 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.
+ */
+function stripDependentsPlan(plan) {
+    return {
+        ...plan,
+        releases: plan.releases
+            .filter((release) => release.changesets.length > 0)
+            .map(({ sources, ...release }) => release),
+    };
+}
+/**
+ * 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.
+ */
+async function assertDependentsSourcesReleased(plan, fullPlan, packages, config) {
+    const releasing = new Set(plan.releases.map((release) => release.package.name));
+    const pending = new Set(fullPlan.releases.map((release) => release.package.name));
+    for (const release of plan.releases) {
+        // Dependencies built into the dependent, like bundled or vendored
+        // directories, stay out of the check, which only guards released
+        // packages that the dependent declares.
+        const names = await collectDependencyNames(release.package, packages, config);
+        for (const name of names) {
+            const blocked = pending.has(name) &&
+                !releasing.has(name) &&
+                name !== release.package.name;
+            if (blocked) {
+                throw new ValidationError(`Cannot release package "${release.package.name}" while its source "${name}" has pending changesets; release them together or pass --no-dependents.`);
+            }
+        }
+    }
+}
+/**
+ * Collect the names of the configured sources that a package declares, by the
+ * dependency sections of the policy, without resolving the specs against the
+ * versions. The changeset check uses this to see through a pin that the
+ * versioning will rewrite after the source releases.
+ *
+ * @param pkg      Planned package.
+ * @param packages Discovered packages.
+ * @param config   Repository release configuration.
+ * @return Release package names the package declares.
+ */
+async function collectDeclarationNames(pkg, packages, config) {
+    const names = [];
+    for (const source of packages) {
+        if (pkg.name !== source.name &&
+            (await findNpmSpecs(pkg, source, dependentsSections(config.dependents))).length > 0) {
+            names.push(source.name);
+        }
+    }
+    return names;
+}
+/**
+ * Collect the names of the configured sources that a package builds against,
+ * through specs that resolve the current version or point at the workspace.
+ *
+ * @param pkg      Planned package.
+ * @param packages Discovered packages.
+ * @param config   Repository release configuration.
+ * @return Release package names the package declares.
+ */
+async function collectDependencyNames(pkg, packages, config) {
+    const names = [];
+    for (const source of packages) {
+        if (pkg.name !== source.name &&
+            (await findDependencySpecs(pkg, source, config.dependents))
+                .length > 0) {
+            names.push(source.name);
+        }
+    }
+    return names;
+}
+/**
+ * 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.
+ */
+async function updateDependencyDeclaration(input) {
+    const { dependent, source, version, rule, journal } = input;
+    const specs = await findDependencySpecs(dependent, source, rule);
+    const update = rule?.dependency?.update;
+    if (update) {
+        await update({
+            package: dependent,
+            source,
+            version,
+            specs,
+            remember: (file) => rememberFile(journal, file),
+        });
+        return;
+    }
+    for (const { file, name, spec } of specs) {
+        const nextSpec = updatedSpec(spec, version);
+        if (null === nextSpec &&
+            isOutOfRange(version, spec, source.currentVersion)) {
+            throw new ValidationError(`Cannot rewrite the dependency spec "${spec}" of "${name}" in ${dependent.name}'s ${file}; declare a range or pin that versioning rewrites, like "^${version}".`);
+        }
+        const changed = undefined !== nextSpec && nextSpec !== spec;
+        if (changed) {
+            const contents = await readFile(file, 'utf8');
+            const declared = new RegExp(`"${escapeRegExp(name)}"\\s*:\\s*"${escapeRegExp(spec)}"`);
+            if (!declared.test(contents)) {
+                throw new ValidationError(`The dependency spec of "${name}" in ${dependent.name}'s ${file} doesn't match "${spec}"; rewrite it to "${nextSpec}".`);
+            }
+            await rememberFile(journal, file);
+            await writeFile(file, contents.replace(declared, `"${name}": "${nextSpec}"`));
+        }
+    }
+}
+/**
+ * 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.
+ */
+function updatedSpec(spec, version) {
+    if (spec.startsWith('workspace:')) {
+        // Workspace specs resolve to the local package, so the manifest
+        // keeps them instead of a published version.
+        return undefined;
+    }
+    const prefix = /^[=\^~]/.exec(spec)?.[0] ?? '';
+    const bare = spec.slice(prefix.length).trim();
+    const partial = /^(v?\d+(?:\.\d+)*)(\.x)?$/.exec(bare);
+    if (partial?.[1]) {
+        const depth = partial[1].split('.').length;
+        const stem = version.split('.').slice(0, depth).join('.');
+        // npm partials like 1.x pin the major, and 0.9 pins the major.minor.
+        return `${prefix}${stem}${partial[2] ?? ''}`;
+    }
+    // Wildcards and keyword specs like * or latest already accept the release.
+    return null;
+}
 /**
  * Format the changelog entries of each release, with the configured
  * formatter and the commit that added each changeset.
@@ -180,15 +613,47 @@ async function getVersionedReleases(cwd, config, releases, changesetDirectory) {
         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();
+}
 async function getChangelogEntry(config, pkg, changeset, getCommit) {
     const summary = changeset.summary.trim();
     if (!summary || !config.changelogEntry) {
@@ -226,24 +691,74 @@ async function getChangesetCommit(cwd, file) {
         .split('\x1f');
     return hash ? { hash, shortHash, subject } : undefined;
 }
+/**
+ * Add a package to the selected release plan when it bundles a selected source.
+ *
+ * @param source    Selected package release.
+ * @param dependent Package that would bundle the source.
+ * @param packages  Discovered packages.
+ * @param rule      Dependents policy.
+ * @param selected  Selected package names, mutated in place.
+ * @return Whether the package was selected.
+ */
+async function selectDependentRelease(source, dependent, packages, rule, selected) {
+    const skip = selected.has(dependent.name) ||
+        dependent.name === source.package.name ||
+        isExcludedDependent(dependent, rule);
+    if (skip) {
+        return false;
+    }
+    const specs = await findDependencySpecs(dependent, source.package, rule);
+    if (!specs.length || !dependentNeedsRelease(specs, source, rule)) {
+        return false;
+    }
+    selected.add(dependent.name);
+    return true;
+}
 /**
  * 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.
- * @return Release plan of the named packages.
+ * @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.
  */
-function selectReleasePlan(plan, packages, names) {
+async function selectReleasePlan(plan, packages, names, config, withDependents = true) {
     names.forEach((name) => {
         if (!packages.some((pkg) => pkg.name === name)) {
             throw new ValidationError(`Unknown package "${name}".`);
         }
     });
+    // Dependents that need a release close over the selected sources.
+    const selected = new Set(names);
+    let grew = true;
+    // Dependents may depend on other selected dependents, so expand until stable.
+    while (grew && withDependents && config.dependents) {
+        grew = false;
+        const selectedSources = plan.releases.filter((release) => selected.has(release.package.name));
+        for (const source of selectedSources) {
+            for (const dependent of packages) {
+                if (await selectDependentRelease(source, dependent, packages, config.dependents, selected)) {
+                    grew = true;
+                }
+            }
+        }
+    }
+    const selectedNames = [...selected];
     return {
-        releases: plan.releases.filter((release) => names.includes(release.package.name)),
-        changesets: plan.changesets.filter((changeset) => names.some((name) => Object.hasOwn(changeset.packages, name))),
+        releases: plan.releases.filter((release) => {
+            if (!selected.has(release.package.name)) {
+                return false;
+            }
+            // Explicitly selected dependents without their own changesets only
+            // release when their source releases in the same selection.
+            return (release.changesets.length > 0 ||
+                (release.sources ?? []).some((name) => selected.has(name)));
+        }),
+        changesets: plan.changesets.filter((changeset) => selectedNames.some((name) => Object.hasOwn(changeset.packages, name))),
     };
 }
 /**
@@ -510,6 +1025,8 @@ export async function getChangesetStatus(input) {
     }
     const { plan } = context;
     const { changesets, releases } = plan;
+    const config = context.config;
+    const { packages } = context;
     const since = input.since ??
         (context.config.baseBranch
             ? `origin/${context.config.baseBranch}`
@@ -522,17 +1039,102 @@ export async function getChangesetStatus(input) {
         ? await readChangesetsSince(input.cwd, context.config, changesets, since)
         : [];
     const hasEmptyChangeset = changesetsInDiff.some((changeset) => 0 === Object.keys(changeset.packages).length);
+    // A dependent releases with its sources, which the release pull request
+    // already announces when this pull request's changesets 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.
+    const bundled = new Set((await Promise.all(changedPackages
+        .filter((name) => !changesetsInDiff.some((item) => Object.hasOwn(item.packages, name)))
+        .map(async (name) => {
+        if (!config.dependents ||
+            !(changed.filesByPackage[name] ?? []).every((file) => path.basename(file) === 'package.json')) {
+            return undefined;
+        }
+        const configured = packages.find((pkg) => pkg.name === name);
+        if (!configured) {
+            return undefined;
+        }
+        const sources = await collectDeclarationNames(configured, packages, config);
+        return changesetsInDiff.some((item) => sources.some((source) => Object.hasOwn(item.packages, source)))
+            ? name
+            : undefined;
+    }))).filter((name) => undefined !== name));
     const missingChangesets = hasEmptyChangeset
         ? []
-        : changedPackages.filter((name) => !changesetsInDiff.some((item) => Object.hasOwn(item.packages, name)));
+        : changedPackages.filter((name) => !changesetsInDiff.some((item) => Object.hasOwn(item.packages, name)) && !bundled.has(name));
+    // A pin that doesn't resolve the local package selects a registry release
+    // instead, which the dependents policy won't re-release automatically.
+    const warnings = config.dependents
+        ? await collectPinDriftWarnings(context.config, context.packages)
+        : [];
     return {
         changesets,
         releases,
         changedPackages,
         changedPackageFiles: changed.filesByPackage,
         missingChangesets,
+        warnings,
     };
 }
+/**
+ * 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.
+ */
+async function collectPinDriftWarnings(config, packages) {
+    const warnings = [];
+    for (const dependent of packages) {
+        const others = packages.filter((source) => source.name !== dependent.name);
+        for (const source of others) {
+            const driftedPin = (await findNpmSpecs(dependent, source, config.dependents?.sections ?? DEFAULT_SECTIONS))
+                .filter(({ spec }) => !spec.startsWith('workspace:') &&
+                isOutOfRange(source.currentVersion, spec, source.currentVersion))
+                .at(0);
+            if (driftedPin) {
+                warnings.push(`"${dependent.name}" pins "${driftedPin.name}@${driftedPin.spec}", but the package is at ${source.currentVersion}; the dependents policy won't re-release it until the pin resolves the package.`);
+            }
+        }
+    }
+    return warnings;
+}
+/**
+ * Find the npm specs that a package declares for a source, without the
+ * dependency filtering of dependents links, for drift warnings.
+ *
+ * @param dependent Package potentially declaring the dependency.
+ * @param source    Package the dependency is declared of.
+ * @param sections  Dependency sections to scan.
+ * @return The declared specs.
+ */
+async function findNpmSpecs(dependent, source, sections) {
+    const sourceManifest = await readJsonSafe(path.join(source.directory, 'package.json'));
+    if ('string' !== typeof sourceManifest?.name) {
+        return [];
+    }
+    const identifier = sourceManifest.name;
+    const parsed = await readJsonSafe(path.join(dependent.directory, 'package.json'));
+    const specs = [];
+    for (const section of sections) {
+        const sectionSpecs = parsed?.[section];
+        const declared = 'object' === typeof sectionSpecs &&
+            null !== sectionSpecs &&
+            Object.hasOwn(sectionSpecs, identifier)
+            ? String(sectionSpecs[identifier])
+            : undefined;
+        if (undefined !== declared) {
+            specs.push({
+                file: path.join(dependent.directory, 'package.json'),
+                name: identifier,
+                spec: declared,
+            });
+        }
+    }
+    return specs;
+}
 async function requireConfig(input) {
     const loaded = await loadChangesetConfig(input);
     if (!loaded) {

package/dist/changesets.d.ts

@@ -31,6 +31,8 @@ export interface PackageRelease {
     currentVersion: string;
     nextVersion: string;
     changesets: Changeset[];
+    /** Names of released source packages that this dependent release bundles; absent for changeset-driven releases. */
+    sources?: string[];
 }
 /** A package release with its formatted changelog entries, once versioned. */
 export interface VersionedRelease extends PackageRelease {

package/dist/commands/changeset-args.d.ts

@@ -65,12 +65,17 @@ export declare const changesetVersionArgs: {
         readonly type: "string";
         readonly multiple: true;
     };
+    readonly 'no-dependents': {
+        readonly type: "boolean";
+    };
 };
 /** Parsed input for `changeset-version`. */
 export interface ChangesetVersionArgs {
     dryRun: boolean;
     date?: string;
     packages?: string[];
+    /** Whether the selected sources release their configured dependents; defaults to true. */
+    dependents: boolean;
 }
 /**
  * Validate and normalize a release date option.

package/dist/commands/changeset-args.js

@@ -75,6 +75,7 @@ export const changesetVersionArgs = {
     'dry-run': { type: 'boolean' },
     date: { type: 'string' },
     package: { type: 'string', multiple: true },
+    'no-dependents': { type: 'boolean' },
 };
 /**
  * Validate and normalize a release date option.
@@ -111,6 +112,7 @@ export function parseChangesetVersionArgs(values) {
     }
     return {
         dryRun: getBoolean(values, 'dry-run'),
+        dependents: !getBoolean(values, 'no-dependents'),
         ...(date ? { date } : {}),
         ...(packages.length ? { packages } : {}),
     };

package/dist/commands/changeset-status.d.ts

@@ -13,6 +13,7 @@ export interface ChangesetStatusResult {
     changedPackages: string[];
     changedPackageFiles: Record<string, string[]>;
     missingChangesets: string[];
+    warnings: string[];
 }
 declare const _default: {
     name: string;
@@ -37,6 +38,7 @@ declare const _default: {
             changedPackages: string[];
             changedPackageFiles: Record<string, string[]>;
             missingChangesets: string[];
+            warnings: string[];
         };
     }>;
 };

package/dist/commands/changeset-status.js

@@ -20,8 +20,11 @@ An empty changeset added since the comparison base counts as an explicit no-rele
         logger.summary(() => {
             const rows = result.changedPackages.map((name) => {
                 let status = 'no release requested';
-                if (result.releases.some((release) => release.package.name === name)) {
-                    status = 'changeset found';
+                const release = result.releases.find((item) => item.package.name === name);
+                if (release) {
+                    status = release.changesets.length
+                        ? 'changeset found'
+                        : 'releases with its sources';
                 }
                 if (result.missingChangesets.includes(name)) {
                     status = 'missing changeset';
@@ -49,6 +52,7 @@ An empty changeset added since the comparison base counts as an explicit no-rele
         else if (!result.releases.length) {
             logger.info('No pending package releases.');
         }
+        result.warnings.forEach((warning) => logger.warning(warning));
         return {
             exitCode: result.missingChangesets.length ? 2 : 0,
             result: {

package/dist/commands/changeset-version.d.ts

@@ -26,6 +26,9 @@ declare const _default: {
             readonly type: "string";
             readonly multiple: true;
         };
+        readonly 'no-dependents': {
+            readonly type: "boolean";
+        };
     };
     run({ values, cwd, configFile, logger }: import("./command.ts").CommandContext): Promise<{
         exitCode: number;

package/dist/commands/changeset-version.js

@@ -3,12 +3,13 @@ import { getChangesetVersionSummary } from "../summary.js";
 import { parseChangesetVersionArgs, changesetVersionArgs, } from "./changeset-args.js";
 export default {
     name: 'changeset-version',
-    usage: 'changeset-version [--dry-run] [--date <YYYY-MM-DD>] [--package <name>]',
+    usage: 'changeset-version [--dry-run] [--date <YYYY-MM-DD>] [--package <name>] [--no-dependents]',
     summary: 'Apply pending version bumps and changelog entries.',
     help: `Options:
   --dry-run              Print the release plan without writing files
   --date <YYYY-MM-DD>    Changelog date (default: today)
   --package <name>       Version only this package (repeatable)
+  --no-dependents        Leave the configured dependents of the selected sources out
 
 Updates configured version files, prepends changelog entries and removes the
 applied changeset files. With --package, a changeset that also names other

package/dist/index.d.ts

@@ -43,7 +43,7 @@ export type { ExtractZipInput, ZipEntryInfo, ZipEntryType } from './unzip.ts';
 export type { FindVersionMismatchesInput, GitTagInput, VersionCheckResult, VersionMismatch, } from './version-check.ts';
 export type { Changeset, ChangesetBump, ChangesetPackages, ChangesetConfig, ChangesetPackageType, ChangesetPackage, PackageRelease, VersionedRelease, ChangesetReleasePlan, } from './changesets.ts';
 export type { ChangesetRepository, ChangesetVersionInput, VersionChangesetsResult, ChangesetTagInput, ChangesetTagResult, } from './changeset-release.ts';
-export type { WpReleaseConfig, ChangesetPackageGroup, PackageVersionConfig, PackageVersionSource, PackageVersionTarget, PackageIdSource, NextVersionInput, ReleaseCommit, ReleaseNotesInput, ChangelogEntryInput, PackageJsonVersionOptions, ComposerJsonVersionOptions, WordPressVersionFileOptions, GitTagVersionOptions, PhpConstantVersionOptions, LoadChangesetConfigInput, } from './changeset-config.ts';
+export type { WpReleaseConfig, ChangesetPackageGroup, PackageVersionConfig, PackageVersionSource, PackageVersionTarget, PackageIdSource, NextVersionInput, ReleaseCommit, ReleaseNotesInput, ChangelogEntryInput, DependentsChangelogInput, DependentsConfig, PackageJsonVersionOptions, ComposerJsonVersionOptions, WordPressVersionFileOptions, GitTagVersionOptions, PhpConstantVersionOptions, LoadChangesetConfigInput, } from './changeset-config.ts';
 export type { SvnCheckoutInput, SvnCommandInput, SvnCommandOutput, SvnCommitInput, SvnCopyInput, SvnDepth, SvnOptions, SvnPathsInput, SvnPropsetInput, SvnRunner, SvnStatusEntry, SvnStatusType, SvnUpdateInput, } from './svn.ts';
 export type { SyncDirectoryInput, SyncResult } from './sync.ts';
 export type { SummaryContext } from './summary.ts';

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@wpelevator/wp-release",
-	"version": "0.9.0",
+	"version": "0.10.0",
 	"description": "Package, checksum, sign, verify and version-check WordPress plugins and themes, and deploy plugins to WordPress.org SVN",
 	"license": "MIT",
 	"repository": {
@@ -41,11 +41,13 @@
 	],
 	"dependencies": {
 		"ignore": "^7.0.12",
+		"semver": "^7.7.1",
 		"yauzl": "^3.4.0",
 		"yazl": "^3.3.1"
 	},
 	"devDependencies": {
 		"@types/node": "^22.20.5",
+		"@types/semver": "^7.8.0",
 		"@types/yauzl": "^3.4.0",
 		"@types/yazl": "^3.3.1",
 		"@wordpress/scripts": "^33.0",