@wpelevator/wp-release 0.4.1 → 0.6.0

package/README.md

@@ -1,10 +1,10 @@
 # WP Release
 
-Package, checksum, verify and version-check WordPress plugins and themes, and deploy plugins to the WordPress.org plugin SVN repository. Usable as a CLI, as a library, and through the [`wp-release-deploy-svn`](../../actions/wp-release-deploy-svn) GitHub Action.
+Package, checksum, verify and version-check WordPress plugins and themes, and deploy plugins to the WordPress.org plugin SVN repository. Usable as a CLI, as a library, and through the [`wp-release-zip`](https://github.com/wpelevator/wp-release-zip), [`wp-release-checksums`](https://github.com/wpelevator/wp-release-checksums), [`wp-release-sign`](https://github.com/wpelevator/wp-release-sign) and [`wp-release-deploy-svn`](https://github.com/wpelevator/wp-release-deploy-svn) GitHub Actions.
 
 Themes are released by uploading a ZIP on WordPress.org, so `deploy-svn` is for plugins only; use `zip` to build the theme upload.
 
-**Status:** first release (0.x). All commands are implemented and tested against local SVN repositories, but `deploy-svn` hasn't been used for a WordPress.org deploy yet, so try it with `--dry-run` first. Signatures are tested against libsodium, but haven't been used for a real release yet.
+**Status:** first release (0.x). Signatures are tested against libsodium, but haven't been used for a real release yet.
 
 Option names follow the existing community tools (10up WordPress.org actions, `wp dist-archive`, `wp-scripts plugin-zip`, `grunt-wp-deploy`) so that migrating needs few or no renames. See [Comparison with existing tools](#comparison-with-existing-tools) for the differences.
 
@@ -32,21 +32,117 @@ npx wp-release --help
 | `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. |
+| `wp-release changeset-add [options]` | Record the release impact of a pull request. |
+| `wp-release changeset-status [options]` | List pending releases and check changed packages for changesets. |
+| `wp-release changeset-version [options]` | Apply version bumps and changelog entries. |
+| `wp-release changeset-tag [options]` | Create missing package release tags. |
 
 Run `npx wp-release <command> --help` for the options of each command. Every command reads the plugin or theme directory from the first argument or `--source-dir`, defaulting to the current directory, and prints its result as JSON with `--json`.
 
+### GitHub Actions annotations and job summaries
+
+With the `github` log format, the CLI uses current GitHub Actions features to report problems where you look for them, instead of only in the log. `--log-format <name>` picks how the CLI logs, separately from the result that `--json` prints:
+
+| Log format | Output |
+|---|---|
+| `text` | Plain text. The default outside GitHub Actions. |
+| `github` | GitHub Actions annotations and job summaries. The default when `GITHUB_ACTIONS=true`. `--ci` is a shorthand for it. |
+
+Pass `--log-format text` for plain text in GitHub Actions. The GitHub Actions always use the `github` log format. Only the CLI checks `GITHUB_ACTIONS`: the library classes don't read the environment, and choose the format by the [writer](#logging) they get.
+
+Errors, warnings and notices are printed as [workflow commands](https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-commands), so they show up as annotations on the run and on the files of a pull request:
+
+- `version-check` and `deploy-svn` annotate each version mismatch on the file and line of the version: the `Version` header, the readme `Stable tag` or the PHP constant.
+- `verify` annotates each changed file and each file that isn't in the checksums.
+
+Each command also adds a section to the [job summary](https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-commands#adding-a-job-summary) of the run, when `GITHUB_STEP_SUMMARY` is set:
+
+| Command | Summary |
+|---|---|
+| `deploy-svn` | Plugin, linked to its WordPress.org page, version, written SVN paths, the commit linked to its WordPress.org changeset (or the dry run or no-op result), and the SVN changes in a collapsed table. |
+| `zip` | ZIP, number of files and checksums manifest. |
+| `checksums` | Manifest and number of files. |
+| `sign` | Signature files and the public key. |
+| `verify` | That all files match, or the counts and a table of the changed, missing and extra files. |
+| `version-check` | The matching version, or a table of the mismatches with their files and lines. |
+
+A failed command adds its error to the summary, or a table of its problems with their files and lines, listing up to 100 and counting the rest. The Markdown of the summaries isn't part of the library API. File paths are relative to `GITHUB_WORKSPACE`, or the current directory without it. Files outside it, like those of an extracted ZIP, get an annotation without a file. Multi-line messages stay one annotation.
+
+Use global `--config <path>` to select a config; relative paths resolve from the current directory. Otherwise, Changesets commands discover `wp-release.config.js`, `.mjs` or `.cjs` there.
+
+### Changesets support (experimental)
+
+Changesets support is experimental. It reads Changesets-style Markdown and loads JavaScript configs with descriptors for npm and Composer manifests, plugin and theme headers, readme Stable tags, PHP constants, and Git tags. Use ESM (`export default`) or CommonJS (`module.exports`); TypeScript configs are not supported. Frontmatter accepts `package-name: patch|minor|major` entries; advanced YAML and prerelease mode are unsupported.
+
+Typical release flow, from a feature pull request to the publish workflows triggered by release tags:
+
+```mermaid
+flowchart TD
+	A["Contributor changes a plugin or package"] --> B{"Does this change need a release?"}
+	B -->|Yes| C["Add a changeset with package, bump, and release note"]
+	B -->|No| D["Add an empty changeset"]
+	C --> E["Open or update the feature pull request"]
+	D --> E
+	E --> F["changeset-status checks changed packages and PR changesets"]
+	F -->|Missing a changeset| G["Add the missing changeset"]
+	G --> E
+	F -->|Pass| H["Merge the feature pull request to main"]
+	H --> I["changeset-version updates configured version files and changelogs"]
+	I --> J{"Are there package releases to review?"}
+	J -->|Yes| K["Workflow opens or updates the Version Packages pull request"]
+	K --> L["Review and merge the Version Packages pull request"]
+	L --> M["changeset-tag creates tags for packages changed by that release"]
+	M --> N["GitHub Releases are created from changelog entries"]
+	N --> O["Tag-triggered publish and split workflows run"]
+	J -->|No| P["No package versions or release tags are created"]
+```
+
+An empty changeset marks a feature PR as no-release. The version workflow consumes it without changing versions, and a release PR containing only its deletion produces no tags.
+
+```js
+import { composerJsonVersion, defineConfig, gitTagVersion, packageJsonVersion, wordpressPluginVersion, wordpressStableTag } from '@wpelevator/wp-release';
+
+export default defineConfig( {
+	baseBranch: 'main',
+	changesets: '.changeset',
+	readmeChangelog: true,
+	changelogInsertAfter: '<!-- changelog -->',
+	root: 'packages',
+	tagFormat: '{path}/{version}',
+	packages: [
+		{ glob: 'js/*', idFrom: 'package.json#name', version: { from: packageJsonVersion(), to: [ packageJsonVersion() ] } },
+		{ glob: 'plugins/*', idFrom: 'package.json#name', version: { from: wordpressPluginVersion(), to: [ wordpressPluginVersion(), wordpressStableTag( { ifPresent: true } ), composerJsonVersion( { ifPresent: true } ) ] } },
+		{ glob: 'php/*', idFrom: 'composer.json#name', version: { from: gitTagVersion( { pattern: '{path}/{version}' } ), to: [] } },
+	],
+} );
+```
+
+`version.from` selects the current version; `version.to` lists release targets. Package globs support `*`, `?` and `**`; `{path}` in tag templates is relative to `root`. Templates also accept `{type}`, `{name}` and `{slug}`, while `tagType` customizes the type label. Use `phpConstantVersion( { file, constant } )` to sync a PHP constant.
+
+The default strategy requires stable `x.y.z` versions. Configure `nextVersion( { package, bump, currentVersion, changesets } )` for other formats; changeset bumps remain `patch`, `minor` or `major`, and prerelease syntax is unsupported.
+
+Without `--since`, `changeset-status` compares against `origin/<baseBranch>`; fetch that ref or pass `--since` when using a fork or different upstream. `loadChangesetConfig()` discovers a conventional config at the repository root, unless `--config <path>` selects one explicitly.
+
+Add release notes in a feature PR with `npx wp-release changeset-add --package @vendor/plugin --bump patch --summary "Fix the checkout validation."`. Repeat package and bump flags for multiple packages, or use `--empty` when no release is needed. In CI, `changeset-status --since origin/main` requires a changeset added by the PR; changesets already on the base do not count, while an empty PR changeset records an explicit no-release decision. Missing-change annotations identify an affected file.
+
+On the release branch, preview with `changeset-version --dry-run`, then run `changeset-version` to update version targets and changelogs. By default, new Markdown entries go before the first version heading; `changelogInsertAfter` sets a literal insertion marker for `CHANGELOG.md` and, with `readmeChangelog`, the plugin readme. Put the marker in both files; a missing marker is an error. Without a marker, plugin readmes use the `== Changelog ==` heading. Failed updates are rolled back for safe retries.
+
+After merging the release PR, `changeset-tag --since <merge-commit>^1 --push` pushes tags only for packages changed by that release. 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. Tag pushes need Git write credentials; GitHub Releases need authenticated `gh`.
+
+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 Version Packages PR, push tags, and create GitHub Releases.
+
 ### Naming convention
 
 `@wpelevator/wp-release` is the suite of release tools and `wp-release` is its CLI. "Release" is the whole workflow; each command is one operation in it. Commands are flat: a single word or dashed words like `version-check` and `deploy-svn`, without command groups or aliases. Each GitHub Action is named `wp-release-` followed by the command name, so the CLI command and the `uses:` name always match:
 
 | Capability | CLI command | GitHub Action |
 |---|---|---|
-| Build a ZIP | `wp-release zip` | [`wpelevator/wp-release-zip`](../../actions/wp-release-zip) |
-| Create a checksums manifest | `wp-release checksums` | [`wpelevator/wp-release-checksums`](../../actions/wp-release-checksums) |
-| Sign files | `wp-release sign` | [`wpelevator/wp-release-sign`](../../actions/wp-release-sign) |
+| Build a ZIP | `wp-release zip` | [`wpelevator/wp-release-zip`](https://github.com/wpelevator/wp-release-zip) |
+| Create a checksums manifest | `wp-release checksums` | [`wpelevator/wp-release-checksums`](https://github.com/wpelevator/wp-release-checksums) |
+| Sign files | `wp-release sign` | [`wpelevator/wp-release-sign`](https://github.com/wpelevator/wp-release-sign) |
 | Verify files against a manifest | `wp-release verify` | |
 | Check that the versions agree | `wp-release version-check` | |
-| Deploy to WordPress.org SVN | `wp-release deploy-svn` | [`wpelevator/wp-release-deploy-svn`](../../actions/wp-release-deploy-svn) |
+| Deploy to WordPress.org SVN | `wp-release deploy-svn` | [`wpelevator/wp-release-deploy-svn`](https://github.com/wpelevator/wp-release-deploy-svn) |
 
 Each concept has one name, written in the syntax of each interface:
 
@@ -59,6 +155,7 @@ Each concept has one name, written in the syntax of each interface:
 | SVN tag to create | `--svn-tag <version>` | `svn-tag` | `svnTag` | Tag written by `deploy-svn`, distinct from a git tag. |
 | SVN repository | `--svn-url <url>` | `svn-url` | `svnUrl` | Deploy destination. |
 | SVN credentials | `--svn-username <name>`, `SVN_USERNAME` and `SVN_PASSWORD` env vars | `svn-username`, `svn-password` | `svnUsername`, `svnPassword` | Needed only to commit. There's no password flag, since it would show in the process list; the action inputs and library options fall back to the env vars. |
+| Log format | `--log-format <text\|github>`, `--ci` for `github` | always `github` | `writer: new TextWriter()` or `new GitHubActionsWriter()` | How the log is printed: plain text, or GitHub Actions annotations and job summaries. Each name matches the start of its writer class. |
 | Assets sync | `--no-assets` to skip | `assets: false` to skip | `assets` | Booleans are positive in the library and the action; `--no-assets` is only the CLI negation, never `noAssets` or a `no-assets` input. |
 
 CLI JSON results use camelCase keys like `zipPath`, and GitHub Action outputs use kebab-case like `zip-path`. Library classes are named after the capability (`SvnDeploy`, `Svn`) without repeating "release".
@@ -83,6 +180,8 @@ The commands read the same headers as WordPress. The main plugin file is the top
 
 ### ZIP
 
+The [`wp-release-zip`](https://github.com/wpelevator/wp-release-zip) GitHub Action runs this command.
+
 `zip` writes `{slug}.{version}.zip` to the current directory, or to `--output <file>`, with the selected files in a `{slug}/` root folder:
 
 ```bash
@@ -97,6 +196,8 @@ wp-release zip dist --slug my-plugin --checksums
 
 ### Checksums
 
+The [`wp-release-checksums`](https://github.com/wpelevator/wp-release-checksums) GitHub Action runs this command.
+
 `checksums` writes a manifest with the MD5 and SHA-256 hash of every selected file, in the format of the WordPress.org plugin checksums API (`https://downloads.wordpress.org/plugin-checksums/{slug}/{version}.json`). Paths are relative to the plugin or theme folder, sorted, and use forward slashes:
 
 ```json
@@ -164,6 +265,8 @@ The public key has to come from somewhere other than the plugin that it checks,
 
 ### Sign
 
+The [`wp-release-sign`](https://github.com/wpelevator/wp-release-sign) GitHub Action runs this command.
+
 `sign` writes a detached signature next to each file, `<file>.sig`, so that downloads and installed copies can be trusted. Sign both the ZIP and the checksums manifest: the ZIP signature covers installs and updates, and the manifest signature covers the contents after unpacking and copies that weren't built by you.
 
 ```bash
@@ -192,6 +295,8 @@ wp-release version-check --constant MY_PLUGIN_VERSION --git-tag v1.2.0
 
 ### Deploy to SVN
 
+The [`wp-release-deploy-svn`](https://github.com/wpelevator/wp-release-deploy-svn) GitHub Action runs this command.
+
 `deploy-svn` syncs a plugin to the WordPress.org plugin SVN repository. Each SVN write is a separate flag and nothing is written unless requested. All writes go into one commit.
 
 | Flag | Default | Writes |
@@ -240,6 +345,7 @@ Validation:
 - `--version` defaults to `--svn-tag`, then the `Version` header of the deployed files; when `--version` and `--svn-tag` are both set they must match.
 - Pre-release versions like `1.0.0-rc.1` can be tagged, but syncing one to `trunk/` warns, since trunk is for the development version.
 - `--trunk` without `--svn-tag` works but warns, because trunk then differs from the stable tag that WordPress.org serves downloads from.
+- A version mismatch throws a `VersionMismatchError`, a `ValidationError` with the `mismatches` and a problem for each, with its file and line. See [Logging](#logging).
 
 ### Exit codes
 
@@ -271,6 +377,30 @@ const { committed, revision, version, changes } = await new SvnDeploy(
 
 `resolveDeployOptions()` applies the defaults and throws a `ValidationError` (with `exitCode` `2`) for invalid combinations. `SvnDeploy` exposes each step (`prepare()`, `checkVersions()`, `checkout()`, `sync()`, `commit()` and `cleanup()`) separately so CI wrappers can run and report them one by one; `run()` runs all of them, or nothing when there's nothing to write. `getPlan()` lists the planned SVN changes. The `Svn` class wraps the svn command line, and takes the command runner as a dependency so that tests can replace it.
 
+### 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:
+
+- `TextWriter` prints plain text to `stdout` and `stderr`. It's the default.
+- `GitHubActionsWriter` prints [workflow commands](#github-actions-annotations-and-job-summaries), so that notices, warnings and errors with a file are annotations, and appends summaries to `GITHUB_STEP_SUMMARY`. It's the CLI's `github` log format, and the GitHub Actions pass it to their logger. Its `workspace` and `summaryPath` options default to `GITHUB_WORKSPACE` and `GITHUB_STEP_SUMMARY`.
+
+```js
+import { GitHubActionsWriter, Logger, logError } from '@wpelevator/wp-release';
+
+const logger = new Logger( { writer: new GitHubActionsWriter(), verbose: true } );
+
+logger.error( 'Version header is 1.2.0, expected 1.3.0.', {
+	file: 'my-plugin.php',
+	line: 4,
+	title: 'Version mismatch',
+} );
+logger.summary( ( { workspace } ) => `### Checked ${ workspace }` );
+```
+
+A writer implements `LogWriter` with `write()`, `startGroup()`, `endGroup()` and `summary()`, so other CI systems can have their own format. `summary()` takes a function that builds the Markdown, which only writers with a summary call.
+
+A `ValidationError` can list `problems`, each with a `message` and an optional `file`, `line` and `title`. `logError( logger, error, title )` logs each problem as an error on its file and line and lists them in the summary under the title, or logs the message when there are none. `VersionMismatchError` and `version-check` report the version mismatches this way.
+
 ZIP files and metadata:
 
 ```js

package/dist/changeset-config.d.ts

@@ -0,0 +1,189 @@
+import type { Changeset, ChangesetBump, ChangesetPackage } from './changesets.ts';
+export type PackageVersionSource = {
+    kind: 'package-json';
+    file: string;
+    field: 'version';
+} | {
+    kind: 'composer-json';
+    file: string;
+    field: 'version';
+} | {
+    kind: 'wordpress-plugin-header';
+    file?: string;
+} | {
+    kind: 'wordpress-theme-header';
+    file?: string;
+} | {
+    kind: 'wordpress-stable-tag';
+    file?: string;
+    ifPresent?: boolean;
+} | {
+    kind: 'php-constant';
+    file: string;
+    constant: string;
+} | {
+    kind: 'git-tag';
+    pattern?: string;
+};
+export type PackageVersionTarget = {
+    kind: 'package-json';
+    file: string;
+    field: 'version';
+} | {
+    kind: 'composer-json';
+    file: string;
+    field: 'version';
+    ifPresent: boolean;
+} | {
+    kind: 'wordpress-plugin-header';
+    file?: string;
+} | {
+    kind: 'wordpress-theme-header';
+    file?: string;
+} | {
+    kind: 'wordpress-stable-tag';
+    file?: string;
+    ifPresent?: boolean;
+} | {
+    kind: 'php-constant';
+    file: string;
+    constant: string;
+};
+export interface PackageVersionConfig {
+    /** File or tag that provides the package's current version. */
+    from: PackageVersionSource;
+    /** All version locations that should receive the next version. */
+    to: PackageVersionTarget[];
+}
+export type PackageIdSource = 'package.json#name' | 'composer.json#name' | 'path';
+/** One directory pattern that describes packages sharing release behavior. */
+export interface ChangesetPackageGroup {
+    /** Package directories to discover, relative to the configured package root. */
+    glob: string;
+    /** Package paths excluded from this group, relative to root. */
+    exclude?: string[];
+    /** Optional type used by the {type} tag template. */
+    tagType?: string;
+    /** Manifest field used as the changeset name; defaults to `path`. */
+    idFrom?: PackageIdSource;
+    /** Version source and files to update for every discovered package. */
+    version: PackageVersionConfig;
+}
+/** JavaScript configuration for changeset-aware releases. */
+export interface ChangesetConfig {
+    /** Branch receiving ordinary changes. */
+    baseBranch?: string;
+    /** Directory containing Markdown changesets, relative to the repository root. */
+    changesets?: string;
+    /** Package groups to discover and release. */
+    packages: ChangesetPackageGroup[];
+    /** Git tag template supporting {name}, {slug}, {path}, {type} and {version}. */
+    tagFormat?: string;
+    /** Directory against which package paths in tag formats are calculated. */
+    root?: string;
+    /** Whether plugin readme changelogs are updated with CHANGELOG.md. */
+    readmeChangelog?: boolean;
+    /** Insert generated changelog entries after this literal marker. */
+    changelogInsertAfter?: string;
+    /** Calculate a package's next version instead of using stable SemVer bumps. */
+    nextVersion?: (input: NextVersionInput) => string;
+}
+/** Inputs supplied to a custom next-version strategy. */
+export interface NextVersionInput {
+    package: ChangesetPackage;
+    bump: ChangesetBump;
+    currentVersion: string;
+    changesets: Changeset[];
+}
+export type WpReleaseConfig = ChangesetConfig;
+export interface PackageJsonVersionOptions {
+    file?: string;
+}
+export interface ComposerJsonVersionOptions {
+    file?: string;
+    /** Skip this target when the `version` property is absent instead of adding it. */
+    ifPresent?: boolean;
+}
+export interface WordPressVersionFileOptions {
+    file?: string;
+    /** Skip a missing target file instead of failing. */
+    ifPresent?: boolean;
+}
+export interface GitTagVersionOptions {
+    pattern?: string;
+}
+export interface PhpConstantVersionOptions {
+    file: string;
+    constant: string;
+}
+/**
+ * Return a package.json version descriptor for use as a source or target.
+ *
+ * @param options Version manifest path.
+ * @return Package version descriptor.
+ */
+export declare function packageJsonVersion(options?: PackageJsonVersionOptions): PackageVersionSource & PackageVersionTarget;
+/**
+ * Return a Composer version descriptor for use as a source or target.
+ *
+ * @param options Composer manifest path and missing-field behavior.
+ * @return Package version descriptor.
+ */
+export declare function composerJsonVersion(options?: ComposerJsonVersionOptions): PackageVersionSource & PackageVersionTarget;
+/**
+ * Return a WordPress plugin header version descriptor.
+ *
+ * @param options Optional plugin main file path.
+ * @return Package version descriptor.
+ */
+export declare function wordpressPluginVersion(options?: WordPressVersionFileOptions): PackageVersionSource & PackageVersionTarget;
+/**
+ * Return a WordPress theme style.css version descriptor.
+ *
+ * @param options Optional theme stylesheet path.
+ * @return Package version descriptor.
+ */
+export declare function wordpressThemeVersion(options?: WordPressVersionFileOptions): PackageVersionSource & PackageVersionTarget;
+/**
+ * Return a WordPress readme Stable tag version descriptor.
+ *
+ * @param options Optional readme path.
+ * @return Package version descriptor.
+ */
+export declare function wordpressStableTag(options?: WordPressVersionFileOptions): PackageVersionSource & PackageVersionTarget;
+/**
+ * Return a git tag version descriptor for packages without a version file.
+ *
+ * @param options Optional tag pattern.
+ * @return Package version descriptor.
+ */
+export declare function gitTagVersion(options?: GitTagVersionOptions): PackageVersionSource;
+/**
+ * Return a PHP constant descriptor for use as a version source or target.
+ *
+ * @param options PHP file and constant name.
+ * @return Package version descriptor.
+ */
+export declare function phpConstantVersion(options: PhpConstantVersionOptions): PackageVersionSource & PackageVersionTarget;
+/**
+ * Add type checking to a JavaScript wp-release configuration.
+ *
+ * @param config Repository release configuration.
+ * @return The same configuration object.
+ */
+export declare function defineConfig(config: ChangesetConfig): ChangesetConfig;
+export interface LoadChangesetConfigInput {
+    cwd?: string;
+    configFile?: string;
+}
+/**
+ * Load and validate the repository's JavaScript wp-release configuration.
+ *
+ * @param  input Working directory and optional explicit config path.
+ * @return Loaded configuration and its absolute file path, or undefined when absent.
+ * @throws {ValidationError} If the module cannot be loaded or its shape is invalid.
+ */
+export declare function loadChangesetConfig(input?: LoadChangesetConfigInput): Promise<{
+    config: ChangesetConfig;
+    file: string;
+} | undefined>;