@wpelevator/wp-release 0.4.1 → 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
@@ -164,6 +198,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 +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";
@@ -199,6 +201,46 @@ async function checkEmbeddedCopies(input) {
             : [],
     };
 }
+/**
+ * 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.
@@ -253,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',

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 };
     },
 };

package/dist/errors.d.ts

@@ -1,9 +1,27 @@
+/**
+ * One failed check, with the file and line it's about when there is one.
+ */
+export interface Problem {
+    /** Description of the problem. */
+    message: string;
+    /** File the problem is in, absolute or relative to the working directory. */
+    file?: string | null;
+    /** Line in the file, starting at 1. */
+    line?: number | null;
+    /** Short title of the kind of problem, like "Version mismatch". */
+    title?: string;
+}
 /**
  * Invalid options or failed release checks, reported with exit code 2.
+ * Failed checks can list their problems, so that each one is reported on its
+ * own file and line.
  */
 export declare class ValidationError extends Error {
     name: string;
     exitCode: number;
+    /** Each failed check, empty when the message is all there is. */
+    readonly problems: Problem[];
+    constructor(message: string, problems?: Problem[]);
 }
 /**
  * Missing SVN credentials or a failed login or permission check, reported

package/dist/errors.js

@@ -1,9 +1,17 @@
 /**
  * Invalid options or failed release checks, reported with exit code 2.
+ * Failed checks can list their problems, so that each one is reported on its
+ * own file and line.
  */
 export class ValidationError extends Error {
     name = 'ValidationError';
     exitCode = 2;
+    /** Each failed check, empty when the message is all there is. */
+    problems;
+    constructor(message, problems = []) {
+        super(message);
+        this.problems = problems;
+    }
 }
 /**
  * Missing SVN credentials or a failed login or permission check, reported

package/dist/github-actions-writer.d.ts

@@ -0,0 +1,52 @@
+import type { Annotation, LogEntry, LogWriter, OutputStream, SummaryBuilder } from './logger.ts';
+export interface GitHubActionsWriterOptions {
+    /** Stream for regular output. */
+    stdout?: OutputStream;
+    /** Stream for warnings and errors. */
+    stderr?: OutputStream;
+    /**
+     * Directory that annotation and summary paths are relative to, defaults
+     * to GITHUB_WORKSPACE or the working directory.
+     */
+    workspace?: string;
+    /**
+     * File that summaries are appended to, defaults to GITHUB_STEP_SUMMARY.
+     * Null turns summaries off.
+     */
+    summaryPath?: string | null;
+}
+/**
+ * Writer that prints GitHub Actions workflow commands, so that notices,
+ * warnings and errors are annotations on the run and on the files they're
+ * about, and appends summaries to the job summary.
+ */
+export declare class GitHubActionsWriter implements LogWriter {
+    readonly stdout: OutputStream;
+    readonly stderr: OutputStream;
+    readonly workspace: string;
+    readonly summaryPath: string | null;
+    constructor({ stdout, stderr, workspace, summaryPath, }?: GitHubActionsWriterOptions);
+    write({ level, message, annotation }: LogEntry): void;
+    startGroup(title: string): void;
+    endGroup(): void;
+    summary(build: SummaryBuilder): void;
+    /**
+     * Format a workflow command like
+     * "::error file=my-plugin.php,line=3,title=Version mismatch::message".
+     *
+     * @param name       Command name.
+     * @param message    Message.
+     * @param annotation File, line and title of the annotation.
+     * @return Workflow command with a line break.
+     */
+    formatCommand(name: string, message: string, annotation?: Annotation): string;
+    /**
+     * Get the path of an annotation file relative to the workspace. GitHub
+     * only links files of the repository, so files outside the workspace,
+     * like an extracted ZIP in a temporary directory, get no file.
+     *
+     * @param file File path, absolute or relative to the working directory.
+     * @return Path with forward slashes, or null when it's outside the workspace.
+     */
+    getAnnotationFile(file?: string | null): string | null;
+}

package/dist/github-actions-writer.js

@@ -0,0 +1,94 @@
+import { appendFileSync } from 'node:fs';
+import { getWorkspacePath } from "./summary.js";
+/**
+ * Escape the message of a workflow command, so that a multi-line message
+ * stays one annotation.
+ *
+ * @param text Message.
+ * @return Escaped message.
+ */
+function escapeData(text) {
+    return text
+        .replaceAll('%', '%25')
+        .replaceAll('\r', '%0D')
+        .replaceAll('\n', '%0A');
+}
+/**
+ * Escape a workflow command property like a file path or title.
+ *
+ * @param text Property value.
+ * @return Escaped value.
+ */
+function escapeProperty(text) {
+    return escapeData(text).replaceAll(':', '%3A').replaceAll(',', '%2C');
+}
+/**
+ * Writer that prints GitHub Actions workflow commands, so that notices,
+ * warnings and errors are annotations on the run and on the files they're
+ * about, and appends summaries to the job summary.
+ */
+export class GitHubActionsWriter {
+    stdout;
+    stderr;
+    workspace;
+    summaryPath;
+    constructor({ stdout = process.stdout, stderr = process.stderr, workspace = process.env.GITHUB_WORKSPACE || process.cwd(), summaryPath = process.env.GITHUB_STEP_SUMMARY || null, } = {}) {
+        this.stdout = stdout;
+        this.stderr = stderr;
+        this.workspace = workspace;
+        this.summaryPath = summaryPath;
+    }
+    write({ level, message, annotation }) {
+        const stream = 'warning' === level || 'error' === level
+            ? this.stderr
+            : this.stdout;
+        stream.write('info' === level
+            ? `${message}\n`
+            : this.formatCommand(level, message, annotation));
+    }
+    startGroup(title) {
+        this.stdout.write(`::group::${escapeData(title)}\n`);
+    }
+    endGroup() {
+        this.stdout.write('::endgroup::\n');
+    }
+    summary(build) {
+        if (this.summaryPath) {
+            // A blank line keeps the Markdown of separate summaries apart.
+            appendFileSync(this.summaryPath, `${build({ workspace: this.workspace }).trimEnd()}\n\n`);
+        }
+    }
+    /**
+     * Format a workflow command like
+     * "::error file=my-plugin.php,line=3,title=Version mismatch::message".
+     *
+     * @param name       Command name.
+     * @param message    Message.
+     * @param annotation File, line and title of the annotation.
+     * @return Workflow command with a line break.
+     */
+    formatCommand(name, message, annotation = {}) {
+        const file = this.getAnnotationFile(annotation.file);
+        const properties = [
+            file ? `file=${escapeProperty(file)}` : '',
+            file && annotation.line ? `line=${annotation.line}` : '',
+            annotation.title
+                ? `title=${escapeProperty(annotation.title)}`
+                : '',
+        ]
+            .filter(Boolean)
+            .join(',');
+        return `::${name}${properties ? ` ${properties}` : ''}::${escapeData(message)}\n`;
+    }
+    /**
+     * Get the path of an annotation file relative to the workspace. GitHub
+     * only links files of the repository, so files outside the workspace,
+     * like an extracted ZIP in a temporary directory, get no file.
+     *
+     * @param file File path, absolute or relative to the working directory.
+     * @return Path with forward slashes, or null when it's outside the workspace.
+     */
+    getAnnotationFile(file) {
+        return file ? getWorkspacePath(this.workspace, file) : null;
+    }
+}