@wpelevator/wp-release 0.4.1 → 0.6.0

package/dist/changesets.d.ts

@@ -0,0 +1,72 @@
+export type { ChangesetConfig } from './changeset-config.ts';
+export declare const CHANGESET_BUMPS: readonly ["patch", "minor", "major"];
+export type ChangesetBump = (typeof CHANGESET_BUMPS)[number];
+export type ChangesetPackages = Record<string, ChangesetBump>;
+/** A parsed Changesets-compatible Markdown file. */
+export interface Changeset {
+    /** File name relative to .changeset/, including the .md extension. */
+    fileName: string;
+    /** Package names and their requested version bumps; empty for a no-release changeset. */
+    packages: ChangesetPackages;
+    /** Customer-facing release note. */
+    summary: string;
+}
+export type ChangesetPackageType = 'plugin' | 'theme' | 'npm' | 'other';
+/** A package discovered from repository configuration and its version files. */
+export interface ChangesetPackage {
+    /** Changeset-facing identifier (package.json name or configured path id). */
+    name: string;
+    /** Absolute package directory. */
+    directory: string;
+    /** Package path relative to the configured root. */
+    path: string;
+    type: ChangesetPackageType;
+    /** Version read from the package's authoritative version source. */
+    currentVersion: string;
+}
+/** One package's proposed release in a release plan. */
+export interface PackageRelease {
+    package: ChangesetPackage;
+    bump: ChangesetBump;
+    currentVersion: string;
+    nextVersion: string;
+    changesets: Changeset[];
+}
+/** Deterministic release plan assembled from pending changesets. */
+export interface ChangesetReleasePlan {
+    changesets: Changeset[];
+    releases: PackageRelease[];
+}
+/**
+ * Parse the supported subset of Changesets' Markdown format.
+ *
+ * @param  contents Markdown contents.
+ * @param  fileName File name relative to .changeset/.
+ * @return Parsed changeset.
+ * @throws {ValidationError} If the frontmatter or package bumps are invalid.
+ */
+export declare function parseChangeset(contents: string, fileName?: string): Changeset;
+/**
+ * Serialize a changeset using the standard Markdown frontmatter format.
+ *
+ * @param changeset Parsed changeset values.
+ * @return Markdown contents with a trailing newline.
+ */
+export declare function formatChangeset(changeset: Omit<Changeset, 'fileName'>): string;
+/**
+ * Return the strongest bump requested for a package across changesets.
+ *
+ * @param changesets  Pending changesets.
+ * @param packageName Package identifier.
+ * @return Highest bump, or undefined when no changeset mentions the package.
+ */
+export declare function getChangesetBump(changesets: Changeset[], packageName: string): ChangesetBump | undefined;
+/**
+ * Calculate the next stable semantic version using literal SemVer bump rules.
+ *
+ * @param  currentVersion Current package version.
+ * @param  bump           Requested bump.
+ * @return Next version.
+ * @throws {ValidationError} If currentVersion is not a stable x.y.z version.
+ */
+export declare function getNextVersion(currentVersion: string, bump: ChangesetBump): string;

package/dist/changesets.js

@@ -0,0 +1,103 @@
+import { ValidationError } from "./errors.js";
+export const CHANGESET_BUMPS = ['patch', 'minor', 'major'];
+const BUMP_RANK = {
+    patch: 0,
+    minor: 1,
+    major: 2,
+};
+/**
+ * Parse the supported subset of Changesets' Markdown format.
+ *
+ * @param  contents Markdown contents.
+ * @param  fileName File name relative to .changeset/.
+ * @return Parsed changeset.
+ * @throws {ValidationError} If the frontmatter or package bumps are invalid.
+ */
+export function parseChangeset(contents, fileName = 'changeset.md') {
+    const lines = contents.replace(/^\uFEFF/, '').split(/\r?\n/);
+    if ('---' !== lines[0]) {
+        throw new ValidationError(`Changeset ${fileName} must start with YAML frontmatter (---).`);
+    }
+    const closingLine = lines.indexOf('---', 1);
+    if (-1 === closingLine) {
+        throw new ValidationError(`Changeset ${fileName} is missing the closing frontmatter delimiter.`);
+    }
+    const packages = {};
+    const frontmatter = lines.slice(1, closingLine);
+    frontmatter.forEach((line, index) => {
+        if (line.trim()) {
+            const match = /^\s*(?:"((?:[^"\\]|\\.)+)"|'([^']+)'|([^:#]+))\s*:\s*(patch|minor|major)\s*$/.exec(line);
+            if (!match) {
+                throw new ValidationError(`Invalid package bump on line ${index + 2} of changeset ${fileName}.`);
+            }
+            const name = (match[1] ?? match[2] ?? match[3] ?? '')
+                .replaceAll('\\"', '"')
+                .trim();
+            if (!name) {
+                throw new ValidationError(`Package name is empty on line ${index + 2} of changeset ${fileName}.`);
+            }
+            if (Object.hasOwn(packages, name)) {
+                throw new ValidationError(`Package "${name}" appears more than once in changeset ${fileName}.`);
+            }
+            packages[name] = match[4];
+        }
+    });
+    return {
+        fileName,
+        packages,
+        summary: lines
+            .slice(closingLine + 1)
+            .join('\n')
+            .trim(),
+    };
+}
+/**
+ * Serialize a changeset using the standard Markdown frontmatter format.
+ *
+ * @param changeset Parsed changeset values.
+ * @return Markdown contents with a trailing newline.
+ */
+export function formatChangeset(changeset) {
+    const entries = Object.entries(changeset.packages).sort((a, b) => a[0].localeCompare(b[0]));
+    const frontmatter = entries
+        .map(([name, bump]) => `${JSON.stringify(name)}: ${bump}`)
+        .join('\n');
+    return `---\n${frontmatter}\n---\n\n${changeset.summary.trim()}\n`;
+}
+/**
+ * Return the strongest bump requested for a package across changesets.
+ *
+ * @param changesets  Pending changesets.
+ * @param packageName Package identifier.
+ * @return Highest bump, or undefined when no changeset mentions the package.
+ */
+export function getChangesetBump(changesets, packageName) {
+    const bumps = changesets
+        .map((changeset) => changeset.packages[packageName])
+        .filter((bump) => Boolean(bump));
+    return bumps.sort((a, b) => BUMP_RANK[b] - BUMP_RANK[a])[0];
+}
+/**
+ * Calculate the next stable semantic version using literal SemVer bump rules.
+ *
+ * @param  currentVersion Current package version.
+ * @param  bump           Requested bump.
+ * @return Next version.
+ * @throws {ValidationError} If currentVersion is not a stable x.y.z version.
+ */
+export function getNextVersion(currentVersion, bump) {
+    if (!CHANGESET_BUMPS.includes(bump)) {
+        throw new ValidationError(`Invalid bump "${bump}"; expected patch, minor or major.`);
+    }
+    const match = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/.exec(currentVersion);
+    if (!match) {
+        throw new ValidationError(`Cannot bump "${currentVersion}": expected a stable semantic version in x.y.z format.`);
+    }
+    if ('major' === bump) {
+        return `${Number(match[1]) + 1}.0.0`;
+    }
+    if ('minor' === bump) {
+        return `${match[1]}.${Number(match[2]) + 1}.0`;
+    }
+    return `${match[1]}.${match[2]}.${Number(match[3]) + 1}`;
+}

package/dist/cli.d.ts

@@ -1,6 +1,7 @@
 import type { ChecksumsResult } from './commands/checksums.ts';
 import type { SignResult } from './commands/sign.ts';
 import type { ZipResult } from './commands/zip.ts';
+import type { ChangesetVersionResult } from './commands/changeset-version.ts';
 import { Logger } from './logger.ts';
 import type { OutputStream } from './logger.ts';
 import type { Command, CommandOutcome } from './commands/command.ts';
@@ -43,23 +44,29 @@ export interface CommandResults {
     zip: ZipResult;
     checksums: ChecksumsResult;
     sign: SignResult;
+    'changeset-add': import('./commands/changeset-add.ts').ChangesetAddResult;
+    'changeset-status': import('./commands/changeset-status.ts').ChangesetStatusResult;
+    'changeset-version': ChangesetVersionResult;
+    'changeset-tag': import('./changeset-release.ts').ChangesetTagResult;
 }
 /**
  * Run a command by name with the given arguments, for wrappers like the
  * GitHub Actions that need the result and the thrown errors instead of an
  * exit code.
  *
- * @param  name           Command name, such as zip.
- * @param  args           Arguments after the command name.
- * @param  context        Working directory and logger.
- * @param  context.cwd    Working directory that relative paths resolve against.
- * @param  context.logger Logger for the command output.
+ * @param  name               Command name, such as zip.
+ * @param  args               Arguments after the command name.
+ * @param  context            Working directory and logger.
+ * @param  context.cwd        Working directory that relative paths resolve against.
+ * @param  context.configFile Explicit config file path, when supplied by a wrapper.
+ * @param  context.logger     Logger for the command output.
  * @return Exit code and result of the command.
  * @throws {Error} If the command is unknown, the arguments are invalid or the command fails.
  */
 export declare function execute<Name extends keyof CommandResults>(name: Name, args: string[], context: {
     cwd: string;
     logger: Logger;
+    configFile?: string;
 }): Promise<CommandOutcome<CommandResults[Name]>>;
 /**
  * Run the CLI.

package/dist/cli.js

@@ -5,8 +5,15 @@ 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";
+import changesetAdd from "./commands/changeset-add.js";
+import changesetStatus from "./commands/changeset-status.js";
+import changesetVersion from "./commands/changeset-version.js";
+import changesetTag from "./commands/changeset-tag.js";
 export const EXIT_SUCCESS = 0;
 export const EXIT_FAILURE = 1;
 export const EXIT_INVALID = 2;
@@ -17,20 +24,30 @@ export const commands = [
     verify,
     versionCheck,
     deploySvn,
+    changesetAdd,
+    changesetStatus,
+    changesetVersion,
+    changesetTag,
 ];
 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' },
+    config: { type: 'string' },
 };
 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
+      --config <path>      Path to a JavaScript release config file`;
 /**
  * Get the top-level help text listing all commands.
  *
@@ -92,6 +109,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,24 +158,27 @@ 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,
             options: { ...globalArgs, ...command.options },
             allowPositionals: true,
         });
+        const configFile = getString(values, 'config');
+        if ('' === configFile?.trim()) {
+            throw new ValidationError('--config <path> must not be empty.');
+        }
         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,
             positionals,
             cwd,
+            ...(configFile ? { configFile } : {}),
             logger,
         });
         if (getBoolean(values, 'json')) {
@@ -133,7 +187,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);
     }
 }
@@ -142,11 +196,12 @@ async function runCommand(command, args, io) {
  * GitHub Actions that need the result and the thrown errors instead of an
  * exit code.
  *
- * @param  name           Command name, such as zip.
- * @param  args           Arguments after the command name.
- * @param  context        Working directory and logger.
- * @param  context.cwd    Working directory that relative paths resolve against.
- * @param  context.logger Logger for the command output.
+ * @param  name               Command name, such as zip.
+ * @param  args               Arguments after the command name.
+ * @param  context            Working directory and logger.
+ * @param  context.cwd        Working directory that relative paths resolve against.
+ * @param  context.configFile Explicit config file path, when supplied by a wrapper.
+ * @param  context.logger     Logger for the command output.
  * @return Exit code and result of the command.
  * @throws {Error} If the command is unknown, the arguments are invalid or the command fails.
  */
@@ -157,14 +212,19 @@ export async function execute(name, args, context) {
     }
     const { values, positionals } = parseArgs({
         args,
-        options: command.options,
+        options: { ...globalArgs, ...command.options },
         allowPositionals: true,
     });
+    const configFile = getString(values, 'config') ?? context.configFile;
+    if ('' === configFile?.trim()) {
+        throw new ValidationError('--config <path> must not be empty.');
+    }
     // The command table is keyed by name, so the result matches CommandResults.
     return command.run({
         values,
         positionals,
         ...context,
+        ...(configFile ? { configFile } : {}),
     });
 }
 /**

package/dist/commands/changeset-add.d.ts

@@ -0,0 +1,37 @@
+export interface ChangesetAddResult {
+    file: string;
+    packages: Record<string, string>;
+}
+declare const _default: {
+    name: string;
+    usage: string;
+    summary: string;
+    help: string;
+    options: {
+        readonly package: {
+            readonly type: "string";
+            readonly multiple: true;
+        };
+        readonly bump: {
+            readonly type: "string";
+            readonly multiple: true;
+        };
+        readonly summary: {
+            readonly type: "string";
+        };
+        readonly empty: {
+            readonly type: "boolean";
+        };
+        readonly name: {
+            readonly type: "string";
+        };
+    };
+    run({ values, cwd, configFile, logger }: import("./command.ts").CommandContext): Promise<{
+        exitCode: number;
+        result: {
+            file: string;
+            packages: import("../changesets.ts").ChangesetPackages;
+        };
+    }>;
+};
+export default _default;

package/dist/commands/changeset-add.js

@@ -0,0 +1,35 @@
+import { addChangeset } from "../changeset-release.js";
+import { parseChangesetAddArgs, changesetAddArgs } from "./changeset-args.js";
+export default {
+    name: 'changeset-add',
+    usage: 'changeset-add (--empty | --package <name> --bump <bump> ...) [options]',
+    summary: 'Add a package release note for the next release PR.',
+    help: `Options:
+  --package <name>       Package identifier (repeatable)
+  --bump <bump>          patch, minor or major (repeatable, in package order)
+  --summary <text>       Customer-facing release note
+  --empty                Record that this change does not need a release
+  --name <name>          Changeset filename (default: random identifier)
+
+Use --package and --bump pairs for package releases, or --empty for changes
+that should pass the status check without producing a release.`,
+    options: changesetAddArgs,
+    async run({ values, cwd, configFile, logger }) {
+        const input = parseChangesetAddArgs(values);
+        const file = await addChangeset({
+            cwd,
+            ...(configFile ? { configFile } : {}),
+            packages: input.packages,
+            summary: input.summary,
+            ...(input.name ? { name: input.name } : {}),
+        });
+        logger.info(`Created ${file}.`);
+        return {
+            exitCode: 0,
+            result: {
+                file,
+                packages: input.packages,
+            },
+        };
+    },
+};

package/dist/commands/changeset-args.d.ts

@@ -0,0 +1,114 @@
+import type { ChangesetPackages } from '../changesets.ts';
+import type { ParsedValues } from './command.ts';
+/** Parsed input for `changeset-add`. */
+export interface ChangesetAddArgs {
+    packages: ChangesetPackages;
+    summary: string;
+    empty: boolean;
+    name?: string;
+}
+/** Parse-args options for `changeset-add`. */
+export declare const changesetAddArgs: {
+    readonly package: {
+        readonly type: "string";
+        readonly multiple: true;
+    };
+    readonly bump: {
+        readonly type: "string";
+        readonly multiple: true;
+    };
+    readonly summary: {
+        readonly type: "string";
+    };
+    readonly empty: {
+        readonly type: "boolean";
+    };
+    readonly name: {
+        readonly type: "string";
+    };
+};
+/**
+ * Parse and validate the `changeset-add` options.
+ *
+ * @param  values Parsed CLI options.
+ * @return Normalized changeset input.
+ * @throws {ValidationError} If required options are missing or conflicting.
+ */
+export declare function parseChangesetAddArgs(values: ParsedValues): ChangesetAddArgs;
+/** Parse-args options for `changeset-status`. */
+export declare const changesetStatusArgs: {
+    readonly since: {
+        readonly type: "string";
+    };
+};
+/** Parsed input for `changeset-status`. */
+export interface ChangesetStatusArgs {
+    since?: string;
+}
+/**
+ * Parse the `changeset-status` options.
+ *
+ * @param  values Parsed CLI options.
+ * @return Normalized status input.
+ * @throws {ValidationError} If --since is empty.
+ */
+export declare function parseChangesetStatusArgs(values: ParsedValues): ChangesetStatusArgs;
+/** Parse-args options for `changeset-version`. */
+export declare const changesetVersionArgs: {
+    readonly 'dry-run': {
+        readonly type: "boolean";
+    };
+    readonly date: {
+        readonly type: "string";
+    };
+};
+/** Parsed input for `changeset-version`. */
+export interface ChangesetVersionArgs {
+    dryRun: boolean;
+    date?: string;
+}
+/**
+ * Validate and normalize a release date option.
+ *
+ * @param  value Value from --date.
+ * @return A validated ISO date or undefined.
+ * @throws {ValidationError} If the date is not a real YYYY-MM-DD date.
+ */
+export declare function parseChangesetDate(value: string | undefined): string | undefined;
+/**
+ * Parse the `changeset-version` options.
+ *
+ * @param  values Parsed CLI options.
+ * @return Normalized versioning input.
+ * @throws {ValidationError} If --date is invalid.
+ */
+export declare function parseChangesetVersionArgs(values: ParsedValues): ChangesetVersionArgs;
+/** Parse-args options for `changeset-tag`. */
+export declare const changesetTagArgs: {
+    readonly push: {
+        readonly type: "boolean";
+    };
+    readonly 'dry-run': {
+        readonly type: "boolean";
+    };
+    readonly 'github-release': {
+        readonly type: "boolean";
+    };
+    readonly since: {
+        readonly type: "string";
+    };
+};
+/** Parsed input for `changeset-tag`. */
+export interface ChangesetTagArgs {
+    push: boolean;
+    dryRun: boolean;
+    githubRelease: boolean;
+    since?: string;
+}
+/**
+ * Parse the `changeset-tag` options.
+ *
+ * @param values Parsed CLI options.
+ * @return Normalized tag input.
+ */
+export declare function parseChangesetTagArgs(values: ParsedValues): ChangesetTagArgs;