@wpelevator/wp-release 0.4.0 → 0.5.0

package/dist/report.d.ts

@@ -0,0 +1,22 @@
+import type { Problem } from './errors.ts';
+import type { Logger } from './logger.ts';
+/**
+ * Log each problem as an error on its file and line, and list them in the
+ * summary of the run.
+ *
+ * @param logger      Logger.
+ * @param title       What failed, like the command name, for the summary.
+ * @param problems    Problems.
+ * @param description Text above the problems in the summary, if any.
+ */
+export declare function logProblems(logger: Logger, title: string, problems: Problem[], description?: string): void;
+/**
+ * Log an error thrown while running a command, and add it to the summary of
+ * the run. A ValidationError with problems is logged problem by problem, so
+ * that each one is reported on its own file and line.
+ *
+ * @param logger Logger.
+ * @param error  Thrown error.
+ * @param title  What failed, like the command name, for the summary.
+ */
+export declare function logError(logger: Logger, error: unknown, title?: string): void;

package/dist/report.js

@@ -0,0 +1,35 @@
+import { ValidationError } from "./errors.js";
+import { getErrorSummary, getProblemsSummary } from "./summary.js";
+/**
+ * Log each problem as an error on its file and line, and list them in the
+ * summary of the run.
+ *
+ * @param logger      Logger.
+ * @param title       What failed, like the command name, for the summary.
+ * @param problems    Problems.
+ * @param description Text above the problems in the summary, if any.
+ */
+export function logProblems(logger, title, problems, description = '') {
+    problems.forEach(({ message, ...annotation }) => logger.error(message, annotation));
+    logger.summary((context) => getProblemsSummary(context, title, problems, description));
+}
+/**
+ * Log an error thrown while running a command, and add it to the summary of
+ * the run. A ValidationError with problems is logged problem by problem, so
+ * that each one is reported on its own file and line.
+ *
+ * @param logger Logger.
+ * @param error  Thrown error.
+ * @param title  What failed, like the command name, for the summary.
+ */
+export function logError(logger, error, title = 'wp-release') {
+    const message = error instanceof Error ? error.message : String(error);
+    const problems = error instanceof ValidationError ? error.problems : [];
+    if (problems.length) {
+        logProblems(logger, title, problems);
+    }
+    else {
+        logger.error(message);
+        logger.summary(() => getErrorSummary(title, message));
+    }
+}

package/dist/summary.d.ts

@@ -0,0 +1,141 @@
+import type { ChecksumsResult } from './commands/checksums.ts';
+import type { SignResult } from './commands/sign.ts';
+import type { ZipResult } from './commands/zip.ts';
+import type { DeployOptions } from './deploy-options.ts';
+import type { SvnStatusEntry } from './svn.ts';
+import type { Problem } from './errors.ts';
+/**
+ * SVN host of the WordPress.org plugin repositories.
+ */
+export declare const WPORG_SVN_HOST = "https://plugins.svn.wordpress.org/";
+/**
+ * Number of files or SVN changes listed in a summary before the rest are
+ * counted.
+ */
+export declare const SUMMARY_LIST_LIMIT = 100;
+/**
+ * Where summary file paths are relative to.
+ */
+export interface SummaryContext {
+    /** Directory that file paths are shown relative to. */
+    workspace: string;
+}
+export interface DeploySummaryInput {
+    /** Resolved deploy options. */
+    options: DeployOptions;
+    /** Whether a commit was made. */
+    committed: boolean;
+    /** Revision of the commit. */
+    revision: number | null;
+    /** Deployed version. */
+    version: string | null;
+    /** Changed paths in the working copy. */
+    changes: SvnStatusEntry[];
+}
+/**
+ * Get the path of a file relative to the workspace.
+ *
+ * @param workspace Workspace directory.
+ * @param file      File path, absolute or relative to the working directory.
+ * @return Path with forward slashes, or null when it's outside the workspace.
+ */
+export declare function getWorkspacePath(workspace: string, file: string): string | null;
+/**
+ * Format text as inline code, with a fence that is longer than any backticks
+ * in the text.
+ *
+ * @param text Text.
+ * @return Markdown code span.
+ */
+export declare function formatCode(text: string): string;
+/**
+ * Format a Markdown table.
+ *
+ * @param header Column titles.
+ * @param rows   Cells of each row, already formatted as Markdown.
+ * @return Markdown table.
+ */
+export declare function formatTable(header: string[], rows: string[][]): string;
+/**
+ * Format a file path as code, relative to the workspace when it's inside it.
+ * Files aren't linked, since build directories and release files usually
+ * aren't in the repository.
+ *
+ * @param context Workspace directory.
+ * @param file    File path.
+ * @param line    Line in the file, if known.
+ * @return Markdown code.
+ */
+export declare function formatFile(context: SummaryContext, file: string, line?: number | null): string;
+/**
+ * Get the summary of a ZIP.
+ *
+ * @param context Workspace directory.
+ * @param result  ZIP and manifest paths and the number of files.
+ * @return Markdown summary.
+ */
+export declare function getZipSummary(context: SummaryContext, result: ZipResult): string;
+/**
+ * Get the summary of a checksums manifest.
+ *
+ * @param context Workspace directory.
+ * @param result  Manifest path and the number of hashed files.
+ * @return Markdown summary.
+ */
+export declare function getChecksumsSummary(context: SummaryContext, result: ChecksumsResult): string;
+/**
+ * Get the summary of signed files.
+ *
+ * @param context Workspace directory.
+ * @param result  Signature paths and the public key.
+ * @return Markdown summary.
+ */
+export declare function getSignSummary(context: SummaryContext, result: SignResult): string;
+/**
+ * Get the summary of a verify run where every file matches. Failed runs are
+ * summarized with their problems instead.
+ *
+ * @param context              Workspace directory.
+ * @param result               Verify result.
+ * @param result.checksumsPath Checksums manifest path.
+ * @param result.matched       Number of matching files.
+ * @return Markdown summary.
+ */
+export declare function getVerifySummary(context: SummaryContext, result: {
+    checksumsPath: string;
+    matched: number;
+}): string;
+/**
+ * Get the summary of a version check without mismatches.
+ *
+ * @param version Version that all sources match.
+ * @return Markdown summary.
+ */
+export declare function getVersionCheckSummary(version: string | null): string;
+/**
+ * Get the summary of failed checks, with the file and line of each problem.
+ * Problems after the list limit are counted instead of listed.
+ *
+ * @param context     Workspace directory.
+ * @param title       What failed, like the command name.
+ * @param problems    Problems.
+ * @param description Text above the problems, if any.
+ * @return Markdown summary.
+ */
+export declare function getProblemsSummary(context: SummaryContext, title: string, problems: Problem[], description?: string): string;
+/**
+ * Get the summary of a failed run.
+ *
+ * @param title   What failed, like the command name.
+ * @param message Error message.
+ * @return Markdown summary.
+ */
+export declare function getErrorSummary(title: string, message: string): string;
+/**
+ * Get the summary of a deploy, with the written paths, the commit and the
+ * SVN changes.
+ *
+ * @param input Deploy options and result.
+ * @return Markdown summary.
+ */
+export declare function getDeploySummary(input: DeploySummaryInput): string;

package/dist/summary.js

@@ -0,0 +1,287 @@
+import { isAbsolute, relative, resolve, sep } from 'node:path';
+import { normalizeTag } from "./deploy-options.js";
+/**
+ * SVN host of the WordPress.org plugin repositories.
+ */
+export const WPORG_SVN_HOST = 'https://plugins.svn.wordpress.org/';
+/**
+ * Number of files or SVN changes listed in a summary before the rest are
+ * counted.
+ */
+export const SUMMARY_LIST_LIMIT = 100;
+/**
+ * Get the path of a file relative to the workspace.
+ *
+ * @param workspace Workspace directory.
+ * @param file      File path, absolute or relative to the working directory.
+ * @return Path with forward slashes, or null when it's outside the workspace.
+ */
+export function getWorkspacePath(workspace, file) {
+    const path = relative(workspace, resolve(file));
+    const inWorkspace = '' !== path && !path.startsWith('..') && !isAbsolute(path);
+    return inWorkspace ? path.split(sep).join('/') : null;
+}
+/**
+ * Format text as inline code, with a fence that is longer than any backticks
+ * in the text.
+ *
+ * @param text Text.
+ * @return Markdown code span.
+ */
+export function formatCode(text) {
+    const longest = Math.max(0, ...[...text.matchAll(/`+/g)].map(([ticks]) => ticks.length));
+    const fence = '`'.repeat(longest + 1);
+    const padding = longest ? ' ' : '';
+    return `${fence}${padding}${text}${padding}${fence}`;
+}
+/**
+ * Format a Markdown table.
+ *
+ * @param header Column titles.
+ * @param rows   Cells of each row, already formatted as Markdown.
+ * @return Markdown table.
+ */
+export function formatTable(header, rows) {
+    const formatRow = (cells) => `| ${cells
+        .map((cell) => cell.replaceAll('|', '\\|').replace(/\r?\n/g, ' '))
+        .join(' | ')} |`;
+    return [
+        formatRow(header),
+        formatRow(header.map(() => '---')),
+        ...rows.map(formatRow),
+    ].join('\n');
+}
+/**
+ * Format a file path as code, relative to the workspace when it's inside it.
+ * Files aren't linked, since build directories and release files usually
+ * aren't in the repository.
+ *
+ * @param context Workspace directory.
+ * @param file    File path.
+ * @param line    Line in the file, if known.
+ * @return Markdown code.
+ */
+export function formatFile(context, file, line) {
+    const path = getWorkspacePath(context.workspace, file) ?? file;
+    return formatCode(`${path}${line ? `:${line}` : ''}`);
+}
+/**
+ * Format a list, counting the items after the limit instead of listing them.
+ *
+ * @param items Items, already formatted as Markdown.
+ * @return Markdown list.
+ */
+function formatList(items) {
+    const listed = items.slice(0, SUMMARY_LIST_LIMIT);
+    const more = items.length - listed.length;
+    return [
+        ...listed.map((item) => `- ${item}`),
+        ...(more ? [`- … and ${more} more`] : []),
+    ].join('\n');
+}
+/**
+ * Wrap content in a collapsed section.
+ *
+ * @param title   Section title.
+ * @param content Markdown content.
+ * @return Markdown with a details element.
+ */
+function formatDetails(title, content) {
+    return `<details><summary>${title}</summary>\n\n${content}\n\n</details>`;
+}
+/**
+ * Join summary blocks into one summary.
+ *
+ * @param blocks Markdown blocks, empty ones are left out.
+ * @return Markdown with a line break at the end.
+ */
+function joinBlocks(blocks) {
+    return `${blocks.filter(Boolean).join('\n\n')}\n`;
+}
+/**
+ * Get the summary of a ZIP.
+ *
+ * @param context Workspace directory.
+ * @param result  ZIP and manifest paths and the number of files.
+ * @return Markdown summary.
+ */
+export function getZipSummary(context, result) {
+    return joinBlocks([
+        '### ZIP',
+        formatList([
+            `**ZIP:** ${formatFile(context, result.zipPath)}, ${result.files} files`,
+            ...(result.checksumsPath
+                ? [
+                    `**Checksums:** ${formatFile(context, result.checksumsPath)}`,
+                ]
+                : []),
+        ]),
+    ]);
+}
+/**
+ * Get the summary of a checksums manifest.
+ *
+ * @param context Workspace directory.
+ * @param result  Manifest path and the number of hashed files.
+ * @return Markdown summary.
+ */
+export function getChecksumsSummary(context, result) {
+    return joinBlocks([
+        '### Checksums',
+        formatList([
+            `**Manifest:** ${formatFile(context, result.checksumsPath)}, ${result.files} files`,
+        ]),
+    ]);
+}
+/**
+ * Get the summary of signed files.
+ *
+ * @param context Workspace directory.
+ * @param result  Signature paths and the public key.
+ * @return Markdown summary.
+ */
+export function getSignSummary(context, result) {
+    return joinBlocks([
+        '### Signatures',
+        formatList(result.signatures.map((path) => formatFile(context, path))),
+        `Public key: ${formatCode(result.publicKey)}`,
+    ]);
+}
+/**
+ * Get the summary of a verify run where every file matches. Failed runs are
+ * summarized with their problems instead.
+ *
+ * @param context              Workspace directory.
+ * @param result               Verify result.
+ * @param result.checksumsPath Checksums manifest path.
+ * @param result.matched       Number of matching files.
+ * @return Markdown summary.
+ */
+export function getVerifySummary(context, result) {
+    return joinBlocks([
+        '### Verify',
+        `All ${result.matched} files match ${formatFile(context, result.checksumsPath)}.`,
+    ]);
+}
+/**
+ * Get the summary of a version check without mismatches.
+ *
+ * @param version Version that all sources match.
+ * @return Markdown summary.
+ */
+export function getVersionCheckSummary(version) {
+    return joinBlocks([
+        '### Version check',
+        `All versions match ${formatCode(version ?? '')}.`,
+    ]);
+}
+/**
+ * Get the summary of failed checks, with the file and line of each problem.
+ * Problems after the list limit are counted instead of listed.
+ *
+ * @param context     Workspace directory.
+ * @param title       What failed, like the command name.
+ * @param problems    Problems.
+ * @param description Text above the problems, if any.
+ * @return Markdown summary.
+ */
+export function getProblemsSummary(context, title, problems, description = '') {
+    const more = problems.length - SUMMARY_LIST_LIMIT;
+    return joinBlocks([
+        `### ${title} failed`,
+        description,
+        formatTable(['Problem', 'Location'], problems
+            .slice(0, SUMMARY_LIST_LIMIT)
+            .map(({ message, file, line }) => [
+            message,
+            file ? formatFile(context, file, line) : '',
+        ])),
+        more > 0 && `… and ${more} more`,
+    ]);
+}
+/**
+ * Get the summary of a failed run.
+ *
+ * @param title   What failed, like the command name.
+ * @param message Error message.
+ * @return Markdown summary.
+ */
+export function getErrorSummary(title, message) {
+    return joinBlocks([
+        `### ${title} failed`,
+        message
+            .split(/\r?\n/)
+            .map((line) => `> ${line}`)
+            .join('\n'),
+    ]);
+}
+/**
+ * Get the paths that a deploy writes to.
+ *
+ * @param options Resolved deploy options.
+ * @return SVN paths.
+ */
+function getDeployWrites(options) {
+    const { trunk, readmeOnly, svnTag, assets, assetsDir, readme } = options;
+    return [
+        trunk && 'trunk/',
+        readmeOnly && `trunk/${readme}`,
+        svnTag && `tags/${normalizeTag(svnTag)}/`,
+        assets && assetsDir && 'assets/',
+    ].filter((path) => Boolean(path));
+}
+/**
+ * Describe the result of a deploy commit.
+ *
+ * @param input Deploy options and result.
+ * @return Markdown text.
+ */
+function describeDeployResult(input) {
+    const { options, committed, revision, changes } = input;
+    const isWporg = options.svnUrl.startsWith(WPORG_SVN_HOST);
+    const revisionLabel = `r${revision}`;
+    const revisionLink = isWporg
+        ? `[${revisionLabel}](https://plugins.trac.wordpress.org/changeset/${revision})`
+        : revisionLabel;
+    const uncommitted = changes.length
+        ? `Dry run, ${changes.length} changes were not committed.`
+        : 'No changes to commit.';
+    return committed
+        ? `Committed ${revisionLink} with ${changes.length} changes.`
+        : uncommitted;
+}
+/**
+ * Get the summary of a deploy, with the written paths, the commit and the
+ * SVN changes.
+ *
+ * @param input Deploy options and result.
+ * @return Markdown summary.
+ */
+export function getDeploySummary(input) {
+    const { options, version, changes } = input;
+    const isWporg = options.svnUrl.startsWith(WPORG_SVN_HOST);
+    const plugin = isWporg
+        ? `[${options.slug}](https://wordpress.org/plugins/${options.slug}/)`
+        : formatCode(options.slug);
+    return joinBlocks([
+        isWporg ? '### Deploy to WordPress.org' : '### Deploy to SVN',
+        formatList([
+            `**Plugin:** ${plugin}`,
+            ...(version ? [`**Version:** ${formatCode(version)}`] : []),
+            `**Writes:** ${getDeployWrites(options)
+                .map(formatCode)
+                .join(', ')}`,
+            `**Result:** ${describeDeployResult(input)}`,
+        ]),
+        changes.length > 0 &&
+            formatDetails(`SVN changes (${changes.length})`, formatTable(['Status', 'Path'], changes
+                .slice(0, SUMMARY_LIST_LIMIT)
+                .map(({ status, path }) => [
+                status,
+                formatCode(path),
+            ])) +
+                (changes.length > SUMMARY_LIST_LIMIT
+                    ? `\n\n… and ${changes.length - SUMMARY_LIST_LIMIT} more`
+                    : '')),
+    ]);
+}

package/dist/svn-deploy.d.ts

@@ -78,7 +78,8 @@ export declare class SvnDeploy {
      * pre-release tag doesn't change the stable tag. Readme-only updates need
      * the readme.
      *
-     * @throws {ValidationError} When the files or versions don't match.
+     * @throws {ValidationError} When the files don't match.
+     * @throws {VersionMismatchError} When the versions don't match.
      */
     checkVersions(): Promise<void>;
     /**

package/dist/svn-deploy.js

@@ -10,8 +10,9 @@ import { loadFileRules, selectFiles } from "./file-selection.js";
 import { readPackageMeta } from "./package-meta.js";
 import { Svn } from "./svn.js";
 import { copyFileIfChanged, syncDirectory } from "./sync.js";
+import { getDeploySummary } from "./summary.js";
 import { extractZip } from "./unzip.js";
-import { findVersionMismatches } from "./version-check.js";
+import { VersionMismatchError, findVersionMismatches, } from "./version-check.js";
 /**
  * MIME types of the plugin directory asset formats. svn guesses binary
  * types, but WordPress.org serves assets with the svn:mime-type property,
@@ -102,7 +103,8 @@ export class SvnDeploy {
      * pre-release tag doesn't change the stable tag. Readme-only updates need
      * the readme.
      *
-     * @throws {ValidationError} When the files or versions don't match.
+     * @throws {ValidationError} When the files don't match.
+     * @throws {VersionMismatchError} When the versions don't match.
      */
     async checkVersions() {
         const { trunk, readmeOnly, svnTag, slug, readme } = this.options;
@@ -122,9 +124,7 @@ export class SvnDeploy {
                 });
                 this.version = version;
                 if (mismatches.length) {
-                    throw new ValidationError(mismatches
-                        .map(({ message }) => message)
-                        .join('\n'));
+                    throw new VersionMismatchError(sourceDir, mismatches);
                 }
                 this.logger.info(`Deploying version ${version}.`);
             }
@@ -379,7 +379,9 @@ export class SvnDeploy {
                 await this.checkVersions();
                 await this.checkout();
                 await this.sync();
-                return await this.commit();
+                const result = await this.commit();
+                this.logger.summary(() => getDeploySummary({ options: this.options, ...result }));
+                return result;
             }
             finally {
                 await this.cleanup();

package/dist/version-check.d.ts

@@ -1,3 +1,5 @@
+import { ValidationError } from './errors.ts';
+import type { Problem } from './errors.ts';
 import type { PackageMeta } from './package-meta.ts';
 export declare const GIT_TAG_FORMAT = "{version}";
 /**
@@ -6,8 +8,10 @@ export declare const GIT_TAG_FORMAT = "{version}";
 export interface VersionMismatch {
     /** Where the version comes from, like "Stable tag" or "Git tag". */
     source: string;
-    /** File that holds the version, if any. */
+    /** File that holds the version, relative to the source directory, if any. */
     file: string | null;
+    /** Line of the version in the file, starting at 1, if known. */
+    line: number | null;
     /** Version found, or null when it's missing. */
     actual: string | null;
     /** Human-readable description. */
@@ -45,6 +49,28 @@ export interface VersionCheckResult {
     /** Every mismatch, empty when all versions agree. */
     mismatches: VersionMismatch[];
 }
+/**
+ * Get the problems of version mismatches, with their files relative to the
+ * working directory instead of the plugin directory.
+ *
+ * @param sourceDir  Directory that the mismatch files are relative to.
+ * @param mismatches Mismatches from findVersionMismatches().
+ * @return Problems.
+ */
+export declare function getVersionMismatchProblems(sourceDir: string, mismatches: VersionMismatch[]): Problem[];
+/**
+ * Versions that don't agree, thrown by a deploy before anything is written.
+ * The message lists every mismatch, and the problems have their files and
+ * lines.
+ */
+export declare class VersionMismatchError extends ValidationError {
+    name: string;
+    /** Directory that the mismatch files are relative to. */
+    readonly sourceDir: string;
+    /** Every mismatch. */
+    readonly mismatches: VersionMismatch[];
+    constructor(sourceDir: string, mismatches: VersionMismatch[]);
+}
 /**
  * Get the version from a git tag with a format like v{version} or
  * {slug}-{version}. A leading "v" is stripped from the version, like for
@@ -64,6 +90,18 @@ export declare function getGitTagVersion(input: GitTagInput): string | null;
  * @return Values in the order they appear.
  */
 export declare function findConstantValues(contents: string, name: string): string[];
+/**
+ * Find the definitions of a PHP constant set with define( 'NAME', '1.2.0' )
+ * or const NAME = '1.2.0'.
+ *
+ * @param contents PHP code.
+ * @param name     Constant name.
+ * @return Values and their line numbers, in the order they appear.
+ */
+export declare function findConstantDefinitions(contents: string, name: string): Array<{
+    value: string;
+    line: number;
+}>;
 /**
  * Check that the Version header, readme Stable tag, PHP constants and git tag
  * of a plugin or theme agree, and report every one that doesn't. Themes have