@wpelevator/wp-release 0.8.0 → 0.10.0

package/README.md

@@ -14,7 +14,7 @@ Option names follow the existing community tools (10up WordPress.org actions, `w
 npm install --save-dev @wpelevator/wp-release
 ```
 
-Requires Node.js 22.12 or later. `deploy-svn` also needs the `svn` command line client.
+Requires Node.js 22.12 or later. `deploy-svn` also needs the `svn` command line client; the optional `--exclude-gitattributes` flag needs Git.
 
 The package is an ES module with TypeScript type definitions. CommonJS projects can load it with `require( '@wpelevator/wp-release' )`, which Node.js supports for ES modules without top-level `await` since 22.12.
 
@@ -29,6 +29,7 @@ npx wp-release --help
 | `wp-release zip [<source-dir>] [options]` | Create a ZIP archive with a `{slug}/` root folder, respecting `.distignore`. |
 | `wp-release checksums [<source-dir>] [options]` | Write the MD5 and SHA-256 hashes of every distributed file to a checksums manifest. |
 | `wp-release sign <file>... [options]` | Sign files with Ed25519, writing a detached `<file>.sig` next to each. |
+| `wp-release keygen` | Generate a base64 Ed25519 private seed and public key for signing and verification. |
 | `wp-release verify [<source-dir>] --checksums <file> [options]` | Check a plugin or theme directory, or a ZIP, against a checksums manifest. |
 | `wp-release version-check [<source-dir>] [options]` | Check that the `Version` header, readme `Stable tag`, PHP constants and git tag agree. |
 | `wp-release deploy-svn [<source-dir>] [options]` | Deploy a plugin to the WordPress.org plugin SVN repository. |
@@ -141,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 )`.
@@ -188,15 +229,16 @@ CLI JSON results use camelCase keys like `zipPath`, and GitHub Action outputs us
 
 ### File selection
 
-`zip`, `checksums` and `deploy-svn` select files the same way:
+`zip`, `checksums`, `deploy-svn` and `deploy-git` select files the same way:
 
 | Option | Description |
 |---|---|
 | `--distignore <file>` | Path to the ignore file. Defaults to `.distignore` in the source directory when present; an explicitly passed file must exist. |
 | `--no-distignore` | Don't read any ignore file. |
 | `--exclude <patterns>` | Extra gitignore-style patterns, comma-separated or repeated, like `--exclude build/,assets/*,images/**/*`. They're applied after the ignore file, so a `!` pattern can also re-include a file. |
+| `--exclude-gitattributes` | Also exclude paths marked `export-ignore` by Git attributes. This is opt-in and requires the source directory to be inside a Git repository. |
 
-Both use full gitignore syntax, including `!` negation. Version control metadata (`.git`, `.svn` and `.hg`, at any depth, including the `.git` files of worktrees and submodules) is always left out, also without an ignore file and when deploying from a ZIP, and no `!` pattern can re-include it. This keeps a repository's history out of ZIPs and SVN deploys when the source directory is the repository root. The comma-separated `--exclude` list works like `--exclude` in `wp i18n make-pot`. `deploy-svn --from-zip` ignores both options, since the ZIP is already filtered. Symbolic links that aren't excluded are an error, since ZIP archives and WordPress.org SVN don't support them.
+`.distignore` and `--exclude` use full gitignore syntax, including `!` negation. `--exclude-gitattributes` asks Git to evaluate `export-ignore` attributes, including nested `.gitattributes` files, then adds those paths to the exclusions. It is off by default, so releases don't unexpectedly depend on Git or change selection when a repository adds attributes. Git must be installed and the source directory must be inside a working tree; the flag is ignored by `deploy-svn --from-zip`, since the ZIP is already filtered. Version control metadata (`.git`, `.svn` and `.hg`, at any depth, including the `.git` files of worktrees and submodules) is always left out, also without an ignore file and when deploying from a ZIP, and no `!` pattern can re-include it. This keeps a repository's history out of ZIPs and deploys when the source directory is the repository root. The comma-separated `--exclude` list works like `--exclude` in `wp i18n make-pot`. Selected symbolic links are an error, since ZIP archives and WordPress.org SVN don't support them.
 
 ### Plugin and theme headers
 
@@ -304,7 +346,7 @@ WP_RELEASE_SIGNING_KEY=… wp-release sign my-plugin.1.2.0.zip my-plugin.1.2.0.c
 - `--verbose` prints the public key of the signing key, which `--json` also returns as `publicKey`. Pass it to `verify --public-key` and to the plugin that checks the signatures.
 - An existing `.sig` file isn't overwritten without `--force`.
 
-Generating a key pair isn't part of the package yet. With PHP: `php -r 'echo base64_encode( random_bytes( 32 ) );'` gives a seed, and the public key is printed by `sign --verbose`.
+Generate a key pair with `wp-release keygen`. It prints the private seed once as `WP_RELEASE_SIGNING_KEY=…` and the matching public key. Store the private seed securely; never commit it or put it in a workflow log. Don't run `keygen` in CI or with `--github-output`, since those outputs can expose the private seed. The public key can be distributed to verifiers.
 
 ### Version check
 
@@ -538,7 +580,7 @@ const { valid, changed, missing, extra } = await verifyChecksums( {
 } );
 ```
 
-`loadFileRules()` reads the ignore file and `--exclude` patterns into a gitignore matcher and `selectFiles()` lists the files it doesn't ignore. `compareChecksums()` compares two hash maps without reading any files, and `parseChecksums()` validates manifest JSON. `extractZip()` extracts a ZIP after the same checks as `deploy-svn --from-zip`.
+`loadFileRules()` reads the ignore file and `--exclude` patterns into a gitignore matcher, optionally adds Git `export-ignore` paths, and `selectFiles()` lists the files it doesn't ignore. `compareChecksums()` compares two hash maps without reading any files, and `parseChecksums()` validates manifest JSON. `extractZip()` extracts a ZIP after the same checks as `deploy-svn --from-zip`.
 
 ## Development
 
@@ -560,9 +602,9 @@ The `wpelevator-source` export condition points at `src/index.ts`. The tests and
 
 | Tool | What it does | How `wp-release` differs |
 |---|---|---|
-| [10up WordPress.org plugin deploy](https://github.com/10up/action-wordpress-plugin-deploy) and [readme/asset update](https://github.com/10up/action-wordpress-plugin-asset-update) actions | Two separate GitHub Actions configured through env vars. A deploy always syncs the build to `trunk/` and copies it to the tag; readme and asset updates need the second action. Assets come from `.wordpress-org` by default, and files are selected with `.distignore` or `.gitattributes`. Files are synced with `rsync`. | One `deploy-svn` command with independent write flags, so a release, a readme-only update and an assets-only update are the same command with different flags. Runs locally and in any CI, not only GitHub Actions, and syncs in Node.js without `rsync`. Checks that the `Version` header, readme `Stable tag` and SVN tag agree before writing, which the 10up actions don't. Assets are deployed only when `--assets-dir` is passed, instead of always syncing `.wordpress-org` when it exists, so a plugin's own `assets/` folder is never uploaded by accident. Adds `--exclude` for patterns without an ignore file and `--from-zip` to deploy the exact files of a ZIP. |
+| [10up WordPress.org plugin deploy](https://github.com/10up/action-wordpress-plugin-deploy) and [readme/asset update](https://github.com/10up/action-wordpress-plugin-asset-update) actions | Two separate GitHub Actions configured through env vars. A deploy always syncs the build to `trunk/` and copies it to the tag; readme and asset updates need the second action. Assets come from `.wordpress-org` by default, and files are selected with `.distignore` or `.gitattributes`. Files are synced with `rsync`. | One `deploy-svn` command with independent write flags, so a release, a readme-only update and an assets-only update are the same command with different flags. Runs locally and in any CI, not only GitHub Actions, and syncs in Node.js without `rsync`. Checks that the `Version` header, readme `Stable tag` and SVN tag agree before writing, which the 10up actions don't. Assets are deployed only when `--assets-dir` is passed, instead of always syncing `.wordpress-org` when it exists, so a plugin's own `assets/` folder is never uploaded by accident. Adds `--exclude` for patterns without an ignore file, opt-in Git `export-ignore` support and `--from-zip` to deploy the exact files of a ZIP. |
 | [`grunt-wp-deploy`](https://github.com/stephenharris/grunt-wp-deploy) | Grunt task with `deploy_trunk` and `deploy_tag` booleans, interactive password prompts and a `Stable tag` check. | No Grunt dependency and never interactive. `--readme-only` is a separate flag, where `grunt-wp-deploy` can only update trunk with the full build. Assets are independent of trunk writes. |
 | [codeinwp theme deploy](https://github.com/codeinwp/action-wordpress-theme-deploy) | Fork of the 10up plugin action that commits themes to the themes SVN repository. | Doesn't deploy themes. Theme releases are ZIP uploads on WordPress.org; `zip` builds the upload with the theme folder as the root. |
 | [`wp dist-archive`](https://github.com/wp-cli/dist-archive-command) | WP-CLI command that zips a project using `.distignore`, with `--plugin-dirname` and `--filename-format`. | Same `.distignore` file and `{name}.{version}` style filename format, but needs only Node.js instead of PHP and WP-CLI. `.distignore` is matched with full gitignore syntax, including `!` negation, and `--distignore` / `--exclude` let you point at another ignore file or add patterns on the command line. Builds are reproducible, and `--checksums` writes a manifest next to the ZIP. |
 | [`wp plugin verify-checksums`](https://developer.wordpress.org/cli/commands/plugin/verify-checksums/) | WP-CLI command that checks installed plugins against the WordPress.org checksums API. | Reads the same manifest format, but from a file, so it also works for plugins and themes that aren't hosted on WordPress.org and for build directories in CI. `checksums` writes the manifest that WordPress.org generates for its own plugins. |
-| [`wp-scripts plugin-zip`](https://github.com/WordPress/gutenberg/tree/trunk/packages/scripts#plugin-zip) | Zips files from `package.json` `files` or a fixed allowlist, named after the npm package, with `--root-folder` / `--no-root-folder`. | Reuses the root folder flags, selects files with `.distignore` instead of an allowlist, puts the version from the plugin headers in the filename and streams the archive instead of building it in memory. |
+| [`wp-scripts plugin-zip`](https://github.com/WordPress/gutenberg/tree/trunk/packages/scripts#plugin-zip) | Zips files from `package.json` `files` or a fixed allowlist, named after the npm package, with `--root-folder` / `--no-root-folder`. | Reuses the root folder flags, selects files with `.distignore` by default and can optionally honor Git `export-ignore` attributes, puts the version from the plugin headers in the filename and streams the archive instead of building it in memory. |

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[];
 }>;