@wpelevator/wp-release 0.4.1 → 0.5.0

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

package/dist/version-check.js

@@ -4,6 +4,7 @@ import ignore from 'ignore';
 import { normalizeTag } from "./deploy-options.js";
 import { ValidationError } from "./errors.js";
 import { selectFiles } from "./file-selection.js";
+import { findFileHeaderLine, findReadmeHeaderLine, getLineNumber, readFileStart, } from "./package-meta.js";
 export const GIT_TAG_FORMAT = '{version}';
 const TAG_REF_PREFIX = 'refs/tags/';
 /**
@@ -11,6 +12,39 @@ const TAG_REF_PREFIX = 'refs/tags/';
  * dependencies with their own versions.
  */
 const CONSTANT_SEARCH_IGNORE = ['node_modules/', 'vendor/', '.*'];
+/**
+ * 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 function getVersionMismatchProblems(sourceDir, mismatches) {
+    return mismatches.map(({ message, file, line }) => ({
+        message,
+        file: file ? join(sourceDir, file) : null,
+        line,
+        title: 'Version mismatch',
+    }));
+}
+/**
+ * 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 class VersionMismatchError extends ValidationError {
+    name = 'VersionMismatchError';
+    /** Directory that the mismatch files are relative to. */
+    sourceDir;
+    /** Every mismatch. */
+    mismatches;
+    constructor(sourceDir, mismatches) {
+        super(mismatches.map(({ message }) => message).join('\n'), getVersionMismatchProblems(sourceDir, mismatches));
+        this.sourceDir = sourceDir;
+        this.mismatches = mismatches;
+    }
+}
 /**
  * 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
@@ -44,6 +78,17 @@ function escapeRegExp(text) {
  * @return Values in the order they appear.
  */
 export function findConstantValues(contents, name) {
+    return findConstantDefinitions(contents, name).map(({ value }) => value);
+}
+/**
+ * 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 function findConstantDefinitions(contents, name) {
     const quotedName = `(['"])${escapeRegExp(name)}\\1`;
     const patterns = [
         new RegExp(`\\bdefine\\s*\\(\\s*${quotedName}\\s*,\\s*(['"])(.*?)\\2\\s*[,)]`, 'g'),
@@ -52,7 +97,10 @@ export function findConstantValues(contents, name) {
     return patterns
         .flatMap((pattern) => [...contents.matchAll(pattern)])
         .sort((a, b) => (a.index ?? 0) - (b.index ?? 0))
-        .map((match) => match[3] ?? '');
+        .map((match) => ({
+        value: match[3] ?? '',
+        line: getLineNumber(contents, match.index ?? 0),
+    }));
 }
 /**
  * Compare a version with the expected one.
@@ -100,16 +148,17 @@ async function compareConstants(sourceDir, constants, expected) {
     })));
     return constants.flatMap((name) => {
         const source = `Constant ${name}`;
-        const definitions = sources.flatMap(({ file, contents }) => findConstantValues(contents, name).map((actual) => ({
+        const definitions = sources.flatMap(({ file, contents }) => findConstantDefinitions(contents, name).map(({ value, line }) => ({
             source,
             file,
-            actual,
+            line,
+            actual: value,
         })));
         if (definitions.length) {
             return definitions.map((definition) => compareVersion(definition, expected));
         }
         return [
-            compareVersion({ source, file: null, actual: null }, expected),
+            compareVersion({ source, file: null, line: null, actual: null }, expected),
         ];
     });
 }
@@ -127,11 +176,12 @@ function compareGitTag(input, expected) {
         return {
             source: 'Git tag',
             file: null,
+            line: null,
             actual: tag,
             message: `Git tag ${tag} doesn't match the format ${input.gitTagFormat}.`,
         };
     }
-    return compareVersion({ source: `Git tag ${tag}`, file: null, actual }, expected);
+    return compareVersion({ source: `Git tag ${tag}`, file: null, line: null, actual }, expected);
 }
 /**
  * Check that the Version header, readme Stable tag, PHP constants and git tag
@@ -152,6 +202,7 @@ export async function findVersionMismatches(input) {
                 {
                     source: 'Version header',
                     file: meta.mainFile,
+                    line: null,
                     actual: null,
                     message: `Version header is missing in ${meta.mainFile}.`,
                 },
@@ -164,12 +215,14 @@ export async function findVersionMismatches(input) {
         compareVersion({
             source: 'Version header',
             file: meta.mainFile,
+            line: findFileHeaderLine((await readFileStart(join(sourceDir, meta.mainFile))) ?? '', 'Version'),
             actual: meta.version,
         }, expected),
         checkStableTag && !readme
             ? {
                 source: 'Stable tag',
                 file: null,
+                line: null,
                 actual: null,
                 message: `Readme is missing, expected Stable tag ${expected}.`,
             }
@@ -178,6 +231,7 @@ export async function findVersionMismatches(input) {
             ? compareVersion({
                 source: 'Stable tag',
                 file: readme.file,
+                line: findReadmeHeaderLine(await readFile(join(sourceDir, readme.file), 'utf8'), 'Stable tag'),
                 actual: readme.headers['Stable tag'] ?? null,
             }, expected)
             : null,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@wpelevator/wp-release",
-	"version": "0.4.1",
+	"version": "0.5.0",
 	"description": "Package, checksum, sign, verify and version-check WordPress plugins and themes, and deploy plugins to WordPress.org SVN",
 	"license": "MIT",
 	"repository": {