@wpelevator/wp-release 0.4.0 → 0.5.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.
 
@@ -35,18 +35,47 @@ npx wp-release --help
 
 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.
+
 ### 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 +88,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 +113,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 +129,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
@@ -134,7 +168,7 @@ wp-release verify wp-content/plugins/my-plugin --checksums my-plugin.1.2.0.check
 - Manifest paths outside the package folder (absolute or with `..`) are rejected.
 - `--zip <file|url>` checks the files of a ZIP instead of a directory. The ZIP can be a URL, such as the one that WordPress.org builds for a release, and its single root folder is found automatically (or set `--root-folder`). The ZIP is extracted to a temporary directory after the same safety checks as `deploy-svn --from-zip`.
 - The version in the manifest must match the `Version` header of the checked files, so that an older release with its own valid manifest can't pass as a newer one.
-- A manifest can't list itself. A copy of the manifest and of its `.sig` inside the checked files, at the root with the same names as the `--checksums` file or at the path of `--embedded`, is skipped when comparing files, but it must be identical to the `--checksums` file. See [Manifest inside the plugin](#manifest-inside-the-plugin).
+- A manifest can't list itself. A copy of the manifest and of its `.sig` inside the checked files, at the root with the same names as the `--checksums` file or at the path of `--embedded`, is skipped when comparing files, but it must be identical to the `--checksums` file and its `.sig`. A path that the manifest lists is never skipped, and a file that isn't a matching copy is reported as not in the checksums. See [Manifest inside the plugin](#manifest-inside-the-plugin).
 
 A checksums manifest proves only that the files match the manifest. With `--public-key <key>`, `verify` first checks `<checksums>.sig` against the base64 Ed25519 public key and fails with exit code `2` before comparing any file when the signature is missing or invalid, so that the manifest itself can be trusted. See [Sign](#sign).
 
@@ -158,12 +192,14 @@ wp-release deploy-svn build --trunk --svn-tag 1.2.0
     --checksums build/checksums.json --public-key "$PUBLIC_KEY"
   ```
 
-- The manifest can have any name and location, for example `--output build/includes/signatures/checksums.json`, and missing folders are created. Tell `verify` where the shipped copy is with `--embedded <path>`, like `--embedded includes/signatures/checksums.json`. The copy and its `.sig` are then skipped when comparing files, must exist, and must be identical to the `--checksums` file and its signature. Without `--embedded`, `verify` looks for the manifest name at the root and only checks it when it's there.
+- The manifest can have any name and location, for example `--output build/includes/signatures/checksums.json`, and missing folders are created. Tell `verify` where the shipped copy is with `--embedded <path>`, like `--embedded includes/signatures/checksums.json`. Both the `--checksums` file and its `.sig` must then exist, both copies must be shipped, and they're skipped when comparing files and must be identical to the originals. The manifest can't list the embedded path. Without `--embedded`, `verify` looks for the manifest name at the root, and skips a file only when it exists, the matching original exists and the manifest doesn't list it. Otherwise it's checked like any other file, so a listed file that has the name of the manifest can't be deleted unnoticed, and a shipped `.sig` without an original is reported as not in the checksums.
 
 The public key has to come from somewhere other than the plugin that it checks, because someone who can overwrite the plugin files can also replace a key and a signature inside them. A copy of the manifest also doesn't prevent a downgrade to an older release that was signed too, so the installing side has to enforce a minimum version.
 
 ### 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 +228,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 +278,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 +310,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/cli.js

@@ -5,8 +5,11 @@ import sign from "./commands/sign.js";
 import verify from "./commands/verify.js";
 import versionCheck from "./commands/version-check.js";
 import deploySvn from "./commands/deploy-svn.js";
-import { Logger } from "./logger.js";
-import { getBoolean } from "./commands/command.js";
+import { Logger, TextWriter } from "./logger.js";
+import { getBoolean, getString } from "./commands/command.js";
+import { ValidationError } from "./errors.js";
+import { GitHubActionsWriter } from "./github-actions-writer.js";
+import { logError } from "./report.js";
 export const EXIT_SUCCESS = 0;
 export const EXIT_FAILURE = 1;
 export const EXIT_INVALID = 2;
@@ -22,15 +25,19 @@ const globalArgs = {
     help: { type: 'boolean', short: 'h' },
     verbose: { type: 'boolean', short: 'v' },
     quiet: { type: 'boolean', short: 'q' },
+    'log-format': { type: 'string' },
     ci: { type: 'boolean' },
     json: { type: 'boolean' },
 };
 const globalOptions = `Global options:
-  -h, --help        Show help for the command
-  -v, --verbose     Print more output
-  -q, --quiet       Print errors only
-      --ci          Use GitHub Actions annotations (default when GITHUB_ACTIONS=true)
-      --json        Print the result as JSON`;
+  -h, --help               Show help for the command
+  -v, --verbose            Print more output
+  -q, --quiet              Print errors only
+      --log-format <name>  Log format: text, or github for GitHub Actions
+                           annotations and job summaries (default: github
+                           when GITHUB_ACTIONS=true, otherwise text)
+      --ci                 Same as --log-format github
+      --json               Print the result as JSON`;
 /**
  * Get the top-level help text listing all commands.
  *
@@ -92,6 +99,40 @@ function getErrorExitCode(error) {
     }
     return EXIT_FAILURE;
 }
+/**
+ * Log writers by log format name, each created for the CLI streams. The
+ * names match the writer classes: text is TextWriter and github is
+ * GitHubActionsWriter.
+ */
+const logFormats = {
+    text: (streams) => new TextWriter(streams),
+    github: (streams) => new GitHubActionsWriter(streams),
+};
+/**
+ * Create the log writer of the log format: --log-format, github with --ci, or
+ * github in GitHub Actions (GITHUB_ACTIONS=true) and text elsewhere. Only the
+ * CLI reads the environment, so the library itself stays CI-agnostic.
+ *
+ * @param  values  Parsed option values.
+ * @param  streams Output streams.
+ * @return Log writer.
+ * @throws {ValidationError} For an unknown log format, or --ci with another log format.
+ */
+function createLogWriter(values, streams) {
+    const ci = getBoolean(values, 'ci');
+    const detected = 'true' === process.env.GITHUB_ACTIONS || ci ? 'github' : 'text';
+    const logFormat = getString(values, 'log-format') ?? detected;
+    const create = Object.hasOwn(logFormats, logFormat)
+        ? logFormats[logFormat]
+        : undefined;
+    if (!create) {
+        throw new ValidationError(`Unknown log format "${logFormat}". Use ${Object.keys(logFormats).join(' or ')}.`);
+    }
+    if (ci && 'github' !== logFormat) {
+        throw new ValidationError(`--ci is the same as --log-format github and can't be combined with --log-format ${logFormat}.`);
+    }
+    return create(streams);
+}
 /**
  * Parse the arguments of a command and run it.
  *
@@ -107,7 +148,7 @@ function getErrorExitCode(error) {
  */
 async function runCommand(command, args, io) {
     const { stdout, stderr, cwd } = io;
-    let logger = new Logger({ stdout, stderr });
+    let logger = new Logger({ writer: new TextWriter({ stdout, stderr }) });
     try {
         const { values, positionals } = parseArgs({
             args,
@@ -115,11 +156,9 @@ async function runCommand(command, args, io) {
             allowPositionals: true,
         });
         logger = new Logger({
-            ci: getBoolean(values, 'ci'),
+            writer: createLogWriter(values, { stdout, stderr }),
             quiet: getBoolean(values, 'quiet') || getBoolean(values, 'json'),
             verbose: getBoolean(values, 'verbose'),
-            stdout,
-            stderr,
         });
         const { exitCode, result } = await command.run({
             values,
@@ -133,7 +172,7 @@ async function runCommand(command, args, io) {
         return exitCode;
     }
     catch (error) {
-        logger.error(error instanceof Error ? error.message : String(error));
+        logError(logger, error, `wp-release ${command.name}`);
         return getErrorExitCode(error);
     }
 }

package/dist/commands/checksums.js

@@ -3,6 +3,7 @@ import { CHECKSUMS_EXTENSION, createChecksums, writeChecksums, } from "../checks
 import { loadFileRules, resolveFileSelection } from "../file-selection.js";
 import { FILENAME_FORMAT, formatFilename } from "../filename.js";
 import { readPackageMeta } from "../package-meta.js";
+import { getChecksumsSummary } from "../summary.js";
 import { checkDirectory, fileSelectionArgs, getFileSelectionInput, getSourceDirArg, ignoreOwnFile, ignoreOwnSignature, resolveOutput, sourceDirArgs, } from "./args.js";
 import { getBoolean, getString } from "./command.js";
 export default {
@@ -71,6 +72,7 @@ matches the ZIP contents.`,
         await writeChecksums(checksumsPath, manifest, getBoolean(values, 'force'));
         logger.debug(`Hashed ${files} files in ${sourceDir}.`);
         logger.info(checksumsPath);
+        logger.summary((context) => getChecksumsSummary(context, { checksumsPath, files }));
         return { exitCode: 0, result: { checksumsPath, files } };
     },
 };

package/dist/commands/sign.js

@@ -1,6 +1,7 @@
 import { resolve } from 'node:path';
 import { stat } from 'node:fs/promises';
 import { ValidationError } from "../errors.js";
+import { getSignSummary } from "../summary.js";
 import { SIGNING_KEY_ENV, getPublicKey, parseSigningKey, writeSignature, } from "../signing.js";
 import { getBoolean } from "./command.js";
 export default {
@@ -50,6 +51,7 @@ that belongs to the signing key.`,
             logger.info(signaturePath);
             signatures.push(signaturePath);
         }
+        logger.summary((context) => getSignSummary(context, { signatures, publicKey }));
         return { exitCode: 0, result: { signatures, publicKey } };
     },
 };

package/dist/commands/verify.js

@@ -7,6 +7,8 @@ import { downloadFile, isUrl } from "../download.js";
 import { loadFileRules, parseExclude } from "../file-selection.js";
 import { ValidationError } from "../errors.js";
 import { readPackageMeta } from "../package-meta.js";
+import { logProblems } from "../report.js";
+import { getVerifySummary } from "../summary.js";
 import { extractZip, readZipEntries } from "../unzip.js";
 import { SIGNATURE_EXTENSION, parsePublicKey, verifyFileSignature, } from "../signing.js";
 import { checkDirectory, getSourceDirArg, ignoreOwnFile, ignoreOwnSignature, sourceDirArgs, } from "./args.js";
@@ -99,33 +101,20 @@ function getEmbeddedPath(checksumsPath, embedded) {
         (isAbsolute(embedded) ||
             embedded.includes('\\') ||
             path.startsWith('../') ||
-            '.' === path)) {
+            ['.', '..'].includes(path))) {
         throw new ValidationError(`--embedded must be a path inside the plugin with forward slashes, got "${embedded}".`);
     }
     return embedded || path.endsWith('.json') ? path : null;
 }
 /**
- * Compare the copies of the manifest and its signature inside the checked
- * directory with the given ones. A release that ships the manifest and its
- * signature with the plugin files must ship the same bytes that were
- * signed, otherwise a verifier on the site would check something else. The
- * copies are not part of the manifest, since a manifest can't list itself,
- * so they're skipped when comparing the files.
+ * Get the manifest and signature pairs to look for inside the checked files.
  *
- * Without an explicit path, the copies are expected at the root with the
- * name of the manifest, and are checked only when they exist. With an
- * explicit path they must exist.
- *
- * @param input               Directory, manifest and embedded path.
- * @param input.dir           Directory to check.
- * @param input.checksumsPath Manifest path.
- * @param input.embedded      Explicit path of the embedded manifest.
- * @return The copies that were found to differ or be missing, and their paths.
+ * @param checksumsPath Manifest path.
+ * @param path          Relative path of the embedded manifest, if any.
+ * @return Pairs of the originals and their copies.
  */
-async function checkEmbeddedCopies(input) {
-    const { dir, checksumsPath, embedded } = input;
-    const path = getEmbeddedPath(checksumsPath, embedded);
-    const pairs = path
+function getCopyPairs(checksumsPath, path) {
+    return path
         ? [
             { original: checksumsPath, copy: path },
             {
@@ -134,30 +123,124 @@ async function checkEmbeddedCopies(input) {
             },
         ]
         : [];
-    const results = await Promise.all(pairs.map(async ({ original, copy }) => {
-        const file = join(dir, copy);
-        const hasCopy = existsSync(file);
-        const hasOriginal = existsSync(original);
-        const isSame = !hasCopy ||
-            !hasOriginal ||
-            resolve(original) === resolve(file) ||
-            (await readFile(original)).equals(await readFile(file));
-        return {
-            copy,
-            missing: Boolean(embedded) && hasOriginal && !hasCopy,
-            differing: !isSame,
-        };
-    }));
+}
+/**
+ * Check that an explicit --embedded path can be verified: the manifest can't
+ * list its own copies, and the originals to compare with must exist.
+ *
+ * @param  pairs    Pairs of the originals and their copies.
+ * @param  manifest Checksums manifest.
+ * @throws {ValidationError} If a copy is listed or an original is missing.
+ */
+function checkExplicitPairs(pairs, manifest) {
+    pairs.forEach(({ original, copy }) => {
+        if (Object.hasOwn(manifest.files, copy)) {
+            throw new ValidationError(`The checksums list ${copy}, but a manifest can't list its own embedded copy.`);
+        }
+        if (!existsSync(original)) {
+            throw new ValidationError(`--embedded needs ${original} to compare ${copy} with, but it doesn't exist.`);
+        }
+    });
+}
+/**
+ * Check that two paths are the same file or have the same bytes.
+ *
+ * @param original Path of the original.
+ * @param file     Path of the copy.
+ * @return Whether the contents are identical.
+ */
+async function hasSameContents(original, file) {
+    return (resolve(original) === resolve(file) ||
+        (await readFile(original)).equals(await readFile(file)));
+}
+/**
+ * Compare the copies of the manifest and its signature inside the checked
+ * directory with the given ones. A release that ships the manifest and its
+ * signature with the plugin files must ship the same bytes that were
+ * signed, otherwise a verifier on the site would check something else. The
+ * copies are not part of the manifest, since a manifest can't list itself,
+ * so they're skipped when comparing the files.
+ *
+ * With an explicit path both originals and both copies must exist. Without
+ * one, the copies are expected at the root with the name of the manifest,
+ * and a file is treated as a copy only when it exists, the matching
+ * original exists and the manifest doesn't list it. Any other file is
+ * checked like the rest of the files.
+ *
+ * @param  input               Directory, manifest and embedded path.
+ * @param  input.dir           Directory to check.
+ * @param  input.manifest      Checksums manifest.
+ * @param  input.checksumsPath Manifest path.
+ * @param  input.embedded      Explicit path of the embedded manifest.
+ * @return The copies that were found to differ or be missing, and the paths of the existing copies.
+ * @throws {ValidationError} If an explicit path can't be verified.
+ */
+async function checkEmbeddedCopies(input) {
+    const { dir, manifest, checksumsPath, embedded } = input;
+    const pairs = getCopyPairs(checksumsPath, getEmbeddedPath(checksumsPath, embedded));
+    if (embedded) {
+        checkExplicitPairs(pairs, manifest);
+    }
+    const found = pairs.filter(({ original, copy }) => existsSync(join(dir, copy)) &&
+        (embedded ||
+            (existsSync(original) &&
+                !Object.hasOwn(manifest.files, copy))));
+    const results = await Promise.all(found.map(async ({ original, copy }) => ({
+        copy,
+        isSame: await hasSameContents(original, join(dir, copy)),
+    })));
     return {
-        paths: pairs.map(({ copy }) => copy),
+        paths: found.map(({ copy }) => copy),
         differing: results
-            .filter((result) => result.differing)
-            .map((result) => result.copy),
-        missing: results
-            .filter((result) => result.missing)
-            .map((result) => result.copy),
+            .filter(({ isSame }) => !isSame)
+            .map(({ copy }) => copy),
+        missing: embedded
+            ? pairs
+                .filter(({ copy }) => !existsSync(join(dir, copy)))
+                .map(({ copy }) => copy)
+            : [],
     };
 }
+/**
+ * Get the problems of a verify run. Changed files and files that aren't in
+ * the checksums are reported on the file. Missing files have no file to
+ * report on.
+ *
+ * @param dir                    Checked directory.
+ * @param result                 Differences between the files and the manifest.
+ * @param result.changed         Changed files.
+ * @param result.missing         Missing files.
+ * @param result.extra           Files that aren't in the checksums.
+ * @param result.versionMismatch Manifest and file versions when they differ.
+ * @return Problems.
+ */
+function getVerifyProblems(dir, result) {
+    const { changed, missing, extra, versionMismatch } = result;
+    return [
+        ...changed.map((file) => ({
+            message: `Changed: ${file}`,
+            file: join(dir, file),
+            title: 'Changed file',
+        })),
+        ...missing.map((file) => ({
+            message: `Missing: ${file}`,
+            title: 'Missing file',
+        })),
+        ...extra.map((file) => ({
+            message: `Not in the checksums: ${file}`,
+            file: join(dir, file),
+            title: 'File not in the checksums',
+        })),
+        ...(versionMismatch
+            ? [
+                {
+                    message: `The checksums are for version ${versionMismatch.manifest}, but the files are version ${versionMismatch.files}.`,
+                    title: 'Version mismatch',
+                },
+            ]
+            : []),
+    ];
+}
 /**
  * Compare the version in the manifest with the Version header of the
  * checked files, so that an older signed release can't pass as a newer one.
@@ -193,6 +276,7 @@ async function verifyTarget(input) {
     const { dir } = target;
     const copies = await checkEmbeddedCopies({
         dir,
+        manifest,
         checksumsPath,
         embedded,
     });
@@ -211,25 +295,32 @@ async function verifyTarget(input) {
         !copies.differing.length &&
         !copies.missing.length &&
         !versionMismatch;
-    changed.forEach((file) => logger.error(`Changed: ${file}`));
-    missing.forEach((file) => logger.error(`Missing: ${file}`));
-    extra.forEach((file) => logger.error(`Not in the checksums: ${file}`));
-    if (versionMismatch) {
-        logger.error(`The checksums are for version ${versionMismatch.manifest}, but the files are version ${versionMismatch.files}.`);
-    }
-    logger.info(`${matched.length} files match, ${changed.length} changed, ${missing.length} missing and ${extra.length} extra.`);
-    return {
-        exitCode: valid ? 0 : 2,
-        result: {
-            valid,
+    const counts = `${matched.length} files match, ${changed.length} changed, ${missing.length} missing and ${extra.length} extra.`;
+    if (valid) {
+        logger.summary((context) => getVerifySummary(context, {
             checksumsPath,
             matched: matched.length,
+        }));
+    }
+    else {
+        logProblems(logger, 'wp-release verify', getVerifyProblems(dir, {
             changed,
             missing,
             extra,
             versionMismatch,
-        },
+        }), counts);
+    }
+    logger.info(counts);
+    const result = {
+        valid,
+        checksumsPath,
+        matched: matched.length,
+        changed,
+        missing,
+        extra,
+        versionMismatch,
     };
+    return { exitCode: valid ? 0 : 2, result };
 }
 export default {
     name: 'verify',
@@ -248,11 +339,13 @@ Options:
   --root-folder <name>    Folder in the ZIP (default: the one folder that
                           every entry is in)
   --embedded <path>       Where the manifest and its .sig are shipped inside the
-                          files, like includes/checksums.json (default: the
-                          name of the --checksums file at the root, when it
-                          exists). They're skipped when comparing files and
-                          must be identical to the --checksums file and its
-                          .sig, and with this option they must exist
+                          files, like includes/checksums.json. Both the
+                          --checksums file and its .sig must exist, both
+                          copies must be shipped, and they must be identical
+                          to them. Without this option, a file with the name
+                          of the --checksums file at the root (and its .sig)
+                          is a copy only when it exists, the matching original
+                          exists and the manifest doesn't list it
   --public-key <key>      Base64 Ed25519 public key. Checks <checksums>.sig, as
                           written by "wp-release sign", before comparing any
                           file, and fails when it's missing or invalid
@@ -270,7 +363,9 @@ ignore file inside the checked directory can't hide added files. Use
 
 A manifest can't list itself. A copy of the manifest and of its .sig inside
 the checked files is therefore skipped, but it must be identical to the
---checksums file. See --embedded for where it's looked for.`,
+--checksums file. A path that the manifest lists is never skipped, and a
+file that isn't a matching copy is reported as extra. See --embedded for
+where the copies are looked for.`,
     options: {
         checksums: { type: 'string' },
         zip: { type: 'string' },

package/dist/commands/version-check.js

@@ -2,7 +2,9 @@ import { basename, resolve } from 'node:path';
 import { isTagRef } from "../deploy-options.js";
 import { ValidationError } from "../errors.js";
 import { readPackageMeta } from "../package-meta.js";
-import { GIT_TAG_FORMAT, findVersionMismatches } from "../version-check.js";
+import { GIT_TAG_FORMAT, findVersionMismatches, getVersionMismatchProblems, } from "../version-check.js";
+import { logProblems } from "../report.js";
+import { getVersionCheckSummary } from "../summary.js";
 import { checkDirectory, getSourceDirArg, sourceDirArgs } from "./args.js";
 import { getBoolean, getString, getStrings } from "./command.js";
 /**
@@ -68,9 +70,10 @@ no Stable tag, so it's only checked for plugins.`,
             constants: getStrings(values, 'constant'),
             stableTag: !getBoolean(values, 'no-stable-tag'),
         });
-        mismatches.forEach((mismatch) => logger.error(mismatch.message));
+        logProblems(logger, 'wp-release version-check', getVersionMismatchProblems(sourceDir, mismatches));
         if (!mismatches.length) {
             logger.info(`All versions match ${version}.`);
+            logger.summary(() => getVersionCheckSummary(version));
         }
         return {
             exitCode: mismatches.length ? 2 : 0,

package/dist/commands/zip.js

@@ -5,6 +5,7 @@ import { ValidationError } from "../errors.js";
 import { loadFileRules, resolveFileSelection, selectFiles, } from "../file-selection.js";
 import { FILENAME_FORMAT, formatFilename } from "../filename.js";
 import { readPackageMeta } from "../package-meta.js";
+import { getZipSummary } from "../summary.js";
 import { createZip } from "../zip.js";
 import { checkDirectory, fileSelectionArgs, getFileSelectionInput, getSourceDirArg, ignoreOwnFile, ignoreOwnSignature, resolveOutput, sourceDirArgs, } from "./args.js";
 import { getBoolean, getString } from "./command.js";
@@ -126,13 +127,12 @@ always give the same ZIP.`,
             await writeChecksums(checksumsPath, manifest, force);
             logger.info(checksumsPath);
         }
-        return {
-            exitCode: 0,
-            result: {
-                zipPath,
-                ...(checksumsPath ? { checksumsPath } : {}),
-                files: files.length,
-            },
+        const result = {
+            zipPath,
+            ...(checksumsPath ? { checksumsPath } : {}),
+            files: files.length,
         };
+        logger.summary((context) => getZipSummary(context, result));
+        return { exitCode: 0, result };
     },
 };