@wpelevator/wp-release 0.11.0 → 0.13.0

package/dist/release-repository.d.ts

@@ -11,6 +11,8 @@ export interface ChangedFilesOptions {
     directory?: string;
     /** Value of --diff-filter, like ACMR for files that still exist. */
     diffFilter?: string;
+    /** Whether to include the uncommitted and untracked files of the working tree. */
+    uncommitted?: boolean;
 }
 /**
  * The git queries and writes of a changeset release: tags, the commits of a
@@ -85,13 +87,23 @@ export declare class ReleaseRepository {
      */
     getDirectoryCommits(revision: string, directory: string): Promise<ReleaseCommit[]>;
     /**
-     * List the files changed between the merge base of a ref and HEAD.
+     * List the files changed between the merge base of a ref and HEAD, or the
+     * working tree with the uncommitted option, which adds untracked files.
      *
      * @param since   Base ref, like origin/main.
-     * @param options Directory and diff filter.
+     * @param options Directory, diff filter and uncommitted files.
      * @return Changed files relative to the repository root.
      */
     getChangedFiles(since: string, options?: ChangedFilesOptions): Promise<string[]>;
+    /**
+     * Read a file as of the merge base of a ref and HEAD, the side that
+     * getChangedFiles() diffs against.
+     *
+     * @param since Base ref, like origin/main.
+     * @param file  Absolute or relative file path.
+     * @return File contents, or undefined when the file doesn't exist there.
+     */
+    readFileAtMergeBase(since: string, file: string): Promise<string | undefined>;
     /**
      * Run git log and parse the commits.
      *

package/dist/release-repository.js

@@ -115,25 +115,64 @@ export class ReleaseRepository {
         ]);
     }
     /**
-     * List the files changed between the merge base of a ref and HEAD.
+     * List the files changed between the merge base of a ref and HEAD, or the
+     * working tree with the uncommitted option, which adds untracked files.
      *
      * @param since   Base ref, like origin/main.
-     * @param options Directory and diff filter.
+     * @param options Directory, diff filter and uncommitted files.
      * @return Changed files relative to the repository root.
      */
     async getChangedFiles(since, options = {}) {
+        const pathspec = options.directory
+            ? ['--', this.relativePath(options.directory)]
+            : [];
+        const range = options.uncommitted
+            ? (await this.run(['merge-base', since, 'HEAD'])).trim()
+            : `${since}...HEAD`;
         const output = await this.run([
             'diff',
             '--name-only',
             ...(options.diffFilter
                 ? [`--diff-filter=${options.diffFilter}`]
                 : []),
-            `${since}...HEAD`,
-            ...(options.directory
-                ? ['--', this.relativePath(options.directory)]
-                : []),
+            range,
+            ...pathspec,
         ]);
-        return output.trim().split(/\r?\n/).filter(Boolean);
+        const untracked = options.uncommitted
+            ? await this.run([
+                'ls-files',
+                '--others',
+                '--exclude-standard',
+                '--full-name',
+                ...pathspec,
+            ])
+            : '';
+        const files = `${output}\n${untracked}`
+            .split(/\r?\n/)
+            .filter(Boolean);
+        return [...new Set(files)];
+    }
+    /**
+     * Read a file as of the merge base of a ref and HEAD, the side that
+     * getChangedFiles() diffs against.
+     *
+     * @param since Base ref, like origin/main.
+     * @param file  Absolute or relative file path.
+     * @return File contents, or undefined when the file doesn't exist there.
+     */
+    async readFileAtMergeBase(since, file) {
+        const base = (await this.run(['merge-base', since, 'HEAD'])).trim();
+        const relative = this.relativePath(file);
+        const listed = await this.run([
+            'ls-tree',
+            '--name-only',
+            base,
+            '--',
+            relative,
+        ]);
+        return '' === listed.trim()
+            ? undefined
+            : this.run(['show', `${base}:${relative}`]);
     }
     /**
      * Run git log and parse the commits.

package/dist/release-tags.d.ts

@@ -33,7 +33,9 @@ export declare function selectTagPackages(packages: ConfiguredPackage[], names:
  */
 export declare function getTagVersion(pkg: ConfiguredPackage, expected?: string): Promise<string>;
 /**
- * Find the tag of the newest release before a version.
+ * Find the tag of the newest release before a version. A stable release
+ * skips the pre-releases before it, so that it compares with the previous
+ * stable release.
  *
  * @param repository Repository with the tags.
  * @param prefix     Tag prefix of the package, like `plugins/alpha/`.

package/dist/release-tags.js

@@ -1,7 +1,7 @@
 import { readChangelogSection, getLatestChangelogVersion, } from "./changelog.js";
 import { assertKnownPackages, toChangesetPackage, } from "./changeset-packages.js";
 import { ValidationError } from "./errors.js";
-import { compareVersions, isVersion } from "./versions.js";
+import { compareVersions, isPrerelease, isVersion } from "./versions.js";
 /**
  * Pick the packages to tag.
  *
@@ -37,7 +37,9 @@ export async function getTagVersion(pkg, expected) {
         (await getLatestChangelogVersion(pkg.directory, pkg.currentVersion)));
 }
 /**
- * Find the tag of the newest release before a version.
+ * Find the tag of the newest release before a version. A stable release
+ * skips the pre-releases before it, so that it compares with the previous
+ * stable release.
  *
  * @param repository Repository with the tags.
  * @param prefix     Tag prefix of the package, like `plugins/alpha/`.
@@ -50,6 +52,7 @@ export async function getPreviousTag(repository, prefix, version) {
         .filter((tag) => tag.startsWith(prefix))
         .map((tag) => ({ tag, version: tag.slice(prefix.length) }))
         .filter((item) => isVersion(item.version) &&
+        (isPrerelease(version) || !isPrerelease(item.version)) &&
         compareVersions(item.version, version) < 0)
         .sort((a, b) => compareVersions(b.version, a.version))[0]?.tag;
 }

package/dist/tag-format.d.ts

@@ -1,13 +1,13 @@
-import type { ConfiguredPackage } from './changeset-packages.ts';
+import type { ConfiguredDeployPackage } from './changeset-packages.ts';
 /**
  * Format the tag of a package release.
  *
  * @param format  Tag format with {name}, {slug}, {path}, {type} and {version}.
- * @param pkg     Configured package.
+ * @param pkg     Configured package, with or without a version.
  * @param version Released version, empty for the tag prefix of the package.
  * @return Tag name.
  */
-export declare function formatTag(format: string, pkg: ConfiguredPackage, version: string): string;
+export declare function formatTag(format: string, pkg: ConfiguredDeployPackage, version: string): string;
 /**
  * Format the tag prefix of a package before its name is known, for packages
  * versioned by their git tags.

package/dist/tag-format.js

@@ -3,7 +3,7 @@ import path from 'node:path';
  * Format the tag of a package release.
  *
  * @param format  Tag format with {name}, {slug}, {path}, {type} and {version}.
- * @param pkg     Configured package.
+ * @param pkg     Configured package, with or without a version.
  * @param version Released version, empty for the tag prefix of the package.
  * @return Tag name.
  */

package/dist/version-files.d.ts

@@ -26,7 +26,8 @@ export declare function readVersion(repository: ReleaseRepository, directory: st
 export declare function writeVersion(directory: string, descriptor: PackageVersionTarget, version: string, journal: FileJournal): Promise<void>;
 /**
  * Check that every version target of a package has the expected version.
- * Optional targets that are absent are skipped.
+ * Optional targets that are absent are skipped, and so is the readme Stable
+ * tag of a pre-release.
  *
  * @param  repository Repository, for versions stored as git tags.
  * @param  pkg        Configured package.

package/dist/version-files.js

@@ -6,7 +6,7 @@ import { findMainPluginFile } from "./package-meta.js";
 import { escapeRegExp } from "./regexp.js";
 import { formatTemplatePrefix } from "./tag-format.js";
 import { findConstantValues } from "./version-check.js";
-import { compareVersions } from "./versions.js";
+import { compareVersions, isPrerelease } from "./versions.js";
 /**
  * Read the current version of a package from its configured source.
  *
@@ -32,7 +32,7 @@ export async function readVersion(repository, directory, descriptor, relativePat
         const pattern = descriptor.pattern ?? '{path}/{version}';
         const tags = await repository.listTags(formatTemplatePrefix(pattern, relativePath, tagType));
         const versions = tags
-            .map((tag) => tag.match(/(?:^|\/|v)(\d+\.\d+\.\d+)$/)?.[1])
+            .map((tag) => tag.match(/(?:^|\/|v)(\d+(?:\.\d+){1,3})$/)?.[1])
             .filter((item) => Boolean(item));
         versions.sort((a, b) => compareVersions(b, a));
         if (versions[0]) {
@@ -99,9 +99,12 @@ export async function writeVersion(directory, descriptor, version, journal) {
         await writeFile(file, updated);
         return;
     }
+    // The readme Stable tag keeps the last stable version for a pre-release,
+    // since WordPress.org offers the stable tag to every site.
     if ('wordpress-stable-tag' === descriptor.kind &&
-        descriptor.ifPresent &&
-        !(await versionFileExists(directory, descriptor.kind, descriptor.file))) {
+        (isPrerelease(version) ||
+            (descriptor.ifPresent &&
+                !(await versionFileExists(directory, descriptor.kind, descriptor.file))))) {
         return;
     }
     const file = path.join(directory, await getVersionFile(directory, descriptor.kind, descriptor.file));
@@ -116,7 +119,8 @@ export async function writeVersion(directory, descriptor, version, journal) {
 }
 /**
  * Check that every version target of a package has the expected version.
- * Optional targets that are absent are skipped.
+ * Optional targets that are absent are skipped, and so is the readme Stable
+ * tag of a pre-release.
  *
  * @param  repository Repository, for versions stored as git tags.
  * @param  pkg        Configured package.
@@ -132,8 +136,9 @@ export async function verifyVersionTargets(repository, pkg, expected) {
             actual = undefined;
         }
         else if ('wordpress-stable-tag' === target.kind &&
-            target.ifPresent &&
-            !(await versionFileExists(pkg.directory, target.kind, target.file))) {
+            (isPrerelease(expected) ||
+                (target.ifPresent &&
+                    !(await versionFileExists(pkg.directory, target.kind, target.file))))) {
             actual = undefined;
         }
         else {

package/dist/versions.d.ts

@@ -1,5 +1,5 @@
 /**
- * Check whether a string is a SemVer version, like 1.2.0 or 1.2.0-rc.1.
+ * Check whether a string is a version, like 1.2.0, 1.2.0-rc.1, 2.1 or 1.2.3.4.
  *
  * @param version Version.
  * @return Whether the version is valid.
@@ -15,11 +15,36 @@ export declare function isPrerelease(version: string): boolean;
 /**
  * Compare two versions with SemVer precedence, where a pre-release like
  * 1.0.0-rc.1 comes before 1.0.0. Unlike the semver package, it doesn't throw
- * for versions outside SemVer, like the 1.2 of a custom nextVersion
- * strategy: missing parts count as 0.
+ * for versions outside SemVer, like 1.2 or 1.2.3.4: every part is compared,
+ * and missing parts count as 0.
  *
  * @param left  Version.
  * @param right Version to compare with.
  * @return Negative when left is lower, positive when higher, otherwise 0.
  */
 export declare function compareVersions(left: string, right: string): number;
+/**
+ * Get the pre-release version of a stable release version, like 1.3.0-rc.1
+ * for 1.3.0. A pre-release with a number, like rc.2, is used as is. Without a
+ * number, like rc, the number is one above the highest existing pre-release
+ * of that identifier and stable version, so the first one is rc.1.
+ *
+ * @param  stable     Stable version of the release, like 1.3.0.
+ * @param  prerelease Pre-release identifier with an optional number, like rc or rc.2.
+ * @param  existing   Existing versions of the package, like those of its tags.
+ * @return Pre-release version.
+ * @throws {ValidationError} For an invalid input, or a version that exists.
+ */
+export declare function getPrereleaseVersion(stable: string, prerelease: string, existing: string[]): string;
+/**
+ * Get the snapshot version of a stable release version, like
+ * 1.3.0-pr-251.20261012183000 for 1.3.0: the identifier and the UTC time,
+ * which keeps every snapshot unique and sorts them by time.
+ *
+ * @param  stable Stable version of the release, like 1.3.0.
+ * @param  id     Snapshot identifier, like pr-251.
+ * @param  time   Time of the snapshot.
+ * @return Snapshot version.
+ * @throws {ValidationError} For an invalid identifier or a version that isn't stable.
+ */
+export declare function getSnapshotVersion(stable: string, id: string, time: Date): string;

package/dist/versions.js

@@ -1,9 +1,20 @@
+import { ValidationError } from "./errors.js";
 /**
- * Stable or pre-release SemVer version without build metadata.
+ * Stable or pre-release version without build metadata: SemVer x.y.z, or the
+ * x.y and x.y.z.w versions common in WordPress plugins.
  */
-const VERSION_PATTERN = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z.-]+))?$/;
+const VERSION_PATTERN = /^(?:0|[1-9]\d*)(?:\.(?:0|[1-9]\d*)){1,3}(?:-([0-9A-Za-z.-]+))?$/;
 /**
- * Check whether a string is a SemVer version, like 1.2.0 or 1.2.0-rc.1.
+ * Pre-release input: an identifier with an optional number, like rc or rc.1.
+ */
+const PRERELEASE_INPUT_PATTERN = /^([A-Za-z][0-9A-Za-z-]*)(?:\.(0|[1-9]\d*))?$/;
+/**
+ * Snapshot identifier: dot-separated SemVer pre-release identifiers that start
+ * with a letter, like pr-251 or pr-251.g1a2b3c4.
+ */
+const SNAPSHOT_ID_PATTERN = /^[A-Za-z][0-9A-Za-z-]*(?:\.(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*))*$/;
+/**
+ * Check whether a string is a version, like 1.2.0, 1.2.0-rc.1, 2.1 or 1.2.3.4.
  *
  * @param version Version.
  * @return Whether the version is valid.
@@ -18,13 +29,13 @@ export function isVersion(version) {
  * @return Whether the version is a valid pre-release.
  */
 export function isPrerelease(version) {
-    return Boolean(VERSION_PATTERN.exec(version)?.[4]);
+    return Boolean(VERSION_PATTERN.exec(version)?.[1]);
 }
 /**
  * Compare two versions with SemVer precedence, where a pre-release like
  * 1.0.0-rc.1 comes before 1.0.0. Unlike the semver package, it doesn't throw
- * for versions outside SemVer, like the 1.2 of a custom nextVersion
- * strategy: missing parts count as 0.
+ * for versions outside SemVer, like 1.2 or 1.2.3.4: every part is compared,
+ * and missing parts count as 0.
  *
  * @param left  Version.
  * @param right Version to compare with.
@@ -35,9 +46,7 @@ export function compareVersions(left, right) {
     const [rightCore = '', rightPre] = splitPrerelease(right);
     const a = leftCore.split('.').map(Number);
     const b = rightCore.split('.').map(Number);
-    const core = (a[0] ?? 0) - (b[0] ?? 0) ||
-        (a[1] ?? 0) - (b[1] ?? 0) ||
-        (a[2] ?? 0) - (b[2] ?? 0);
+    const core = compareParts(a, b);
     if (core || leftPre === rightPre) {
         return core;
     }
@@ -46,6 +55,14 @@ export function compareVersions(left, right) {
     }
     return comparePrerelease(leftPre.split('.'), rightPre.split('.'));
 }
+function compareParts(left, right) {
+    const [a, ...leftRest] = left;
+    const [b, ...rightRest] = right;
+    if (undefined === a && undefined === b) {
+        return 0;
+    }
+    return (a ?? 0) - (b ?? 0) || compareParts(leftRest, rightRest);
+}
 function splitPrerelease(version) {
     const index = version.indexOf('-');
     return -1 === index
@@ -72,3 +89,61 @@ function compareIdentifier(a, b) {
     }
     return Number(a > b) - Number(a < b);
 }
+/**
+ * Get the pre-release version of a stable release version, like 1.3.0-rc.1
+ * for 1.3.0. A pre-release with a number, like rc.2, is used as is. Without a
+ * number, like rc, the number is one above the highest existing pre-release
+ * of that identifier and stable version, so the first one is rc.1.
+ *
+ * @param  stable     Stable version of the release, like 1.3.0.
+ * @param  prerelease Pre-release identifier with an optional number, like rc or rc.2.
+ * @param  existing   Existing versions of the package, like those of its tags.
+ * @return Pre-release version.
+ * @throws {ValidationError} For an invalid input, or a version that exists.
+ */
+export function getPrereleaseVersion(stable, prerelease, existing) {
+    const match = PRERELEASE_INPUT_PATTERN.exec(prerelease);
+    if (!match) {
+        throw new ValidationError(`Invalid pre-release "${prerelease}"; expected an identifier with an optional number, like rc or rc.1.`);
+    }
+    if (!isVersion(stable) || isPrerelease(stable)) {
+        throw new ValidationError(`Cannot release "${stable}" as a pre-release: expected a stable version.`);
+    }
+    const identifier = match[1] ?? '';
+    const version = match[2]
+        ? `${stable}-${prerelease}`
+        : `${stable}-${identifier}.${getNextPrereleaseNumber(`${stable}-${identifier}.`, existing)}`;
+    if (existing.includes(version)) {
+        throw new ValidationError(`Version ${version} already exists; pass a pre-release without a number to release the next one.`);
+    }
+    return version;
+}
+function getNextPrereleaseNumber(prefix, existing) {
+    const numbers = existing
+        .filter((version) => version.startsWith(prefix))
+        .map((version) => version.slice(prefix.length))
+        .filter((number) => /^\d+$/.test(number))
+        .map(Number);
+    return Math.max(0, ...numbers) + 1;
+}
+/**
+ * Get the snapshot version of a stable release version, like
+ * 1.3.0-pr-251.20261012183000 for 1.3.0: the identifier and the UTC time,
+ * which keeps every snapshot unique and sorts them by time.
+ *
+ * @param  stable Stable version of the release, like 1.3.0.
+ * @param  id     Snapshot identifier, like pr-251.
+ * @param  time   Time of the snapshot.
+ * @return Snapshot version.
+ * @throws {ValidationError} For an invalid identifier or a version that isn't stable.
+ */
+export function getSnapshotVersion(stable, id, time) {
+    if (!SNAPSHOT_ID_PATTERN.test(id)) {
+        throw new ValidationError(`Invalid snapshot "${id}"; expected SemVer pre-release identifiers that start with a letter, like pr-251.`);
+    }
+    if (!isVersion(stable) || isPrerelease(stable)) {
+        throw new ValidationError(`Cannot release "${stable}" as a snapshot: expected a stable version.`);
+    }
+    const timestamp = time.toISOString().replace(/\D/g, '').slice(0, 14);
+    return `${stable}-${id}.${timestamp}`;
+}

package/package.json

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

package/dist/github.d.ts

@@ -1,24 +0,0 @@
-/**
- * A GitHub pull request of a commit.
- */
-export interface GitHubPullRequest {
-    number: number;
-    url: string;
-    /** GitHub handle of the pull request author, without the @. */
-    author: string;
-}
-export interface GetGitHubPullRequestInput {
-    /** Directory of the repository, whose GitHub remote `gh` uses. */
-    cwd: string;
-    /** Commit hash. */
-    commit: string;
-}
-/**
- * Find the pull request that merged a commit, with the authenticated `gh`
- * command line client.
- *
- * @param  input Repository directory and commit.
- * @return The first pull request of the commit, or undefined without one.
- * @throws {ValidationError} If `gh` fails, like without authentication.
- */
-export declare function getGitHubPullRequest(input: GetGitHubPullRequestInput): Promise<GitHubPullRequest | undefined>;

package/dist/github.js

@@ -1,30 +0,0 @@
-import { execFile } from 'node:child_process';
-import { promisify } from 'node:util';
-import { ValidationError } from "./errors.js";
-const execFileAsync = promisify(execFile);
-/**
- * Find the pull request that merged a commit, with the authenticated `gh`
- * command line client.
- *
- * @param  input Repository directory and commit.
- * @return The first pull request of the commit, or undefined without one.
- * @throws {ValidationError} If `gh` fails, like without authentication.
- */
-export async function getGitHubPullRequest(input) {
-    let stdout;
-    try {
-        ({ stdout } = await execFileAsync('gh', ['api', `repos/{owner}/{repo}/commits/${input.commit}/pulls`], { cwd: input.cwd }));
-    }
-    catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        throw new ValidationError(`Could not find the pull request of commit ${input.commit}: ${message}`);
-    }
-    const [pullRequest] = JSON.parse(stdout);
-    return pullRequest
-        ? {
-            number: pullRequest.number,
-            url: pullRequest.html_url,
-            author: pullRequest.user?.login ?? '',
-        }
-        : undefined;
-}