@wpelevator/wp-release 0.12.0 → 0.14.0

package/dist/tag-format.js

@@ -1,51 +1,37 @@
-import path from 'node:path';
 /**
- * Format the tag of a package release.
+ * Tag format of the package releases, like plugins/alpha/1.2.0 in a
+ * monorepo, or 1.2.0 for a package at the repository root.
+ */
+export const DEFAULT_TAG_FORMAT = '{path}/{version}';
+/**
+ * Fill in a template of a package with {name}, {path} and {version}, like a
+ * deploy template. A package at the root of the repository has an empty
+ * {path}.
  *
- * @param format  Tag format with {name}, {slug}, {path}, {type} and {version}.
- * @param pkg     Configured package.
- * @param version Released version, empty for the tag prefix of the package.
- * @return Tag name.
+ * @param format  Template with {name}, {path} and {version}.
+ * @param pkg     Configured package, with or without a version.
+ * @param version Released version, empty when there's none.
+ * @return Formatted text.
  */
-export function formatTag(format, pkg, version) {
-    const type = pkg.group.tagType ?? defaultTagType(pkg.path, pkg.type);
+export function formatTemplate(format, pkg, version) {
     return format
         .replaceAll('{name}', pkg.name)
-        .replaceAll('{slug}', '.' === pkg.path
-        ? path.basename(pkg.directory)
-        : path.basename(pkg.path))
-        .replaceAll('{path}', pkg.path)
-        .replaceAll('{type}', type)
+        .replaceAll('{path}', '.' === pkg.path ? '' : pkg.path)
         .replaceAll('{version}', version);
 }
 /**
- * Format the tag prefix of a package before its name is known, for packages
- * versioned by their git tags.
+ * Format the tag of a package release, or its tag prefix without a version.
+ * Empty placeholders leave no repeated or leading slashes, so a package at
+ * the repository root gets 1.2.0 for {path}/{version}. A trailing slash is
+ * kept, since it separates the tag prefix from the version.
  *
- * @param pattern     Tag pattern of the version source.
- * @param packagePath Package path relative to the package root.
- * @param tagType     Configured {type} of the package tags.
- * @return Tag prefix.
+ * @param format  Tag format with {name}, {path} and {version}.
+ * @param pkg     Configured package, with or without a version.
+ * @param version Released version, empty for the tag prefix of the package.
+ * @return Tag name or prefix.
  */
-export function formatTemplatePrefix(pattern, packagePath, tagType) {
-    return pattern
-        .replaceAll('{path}', packagePath)
-        .replaceAll('{type}', tagType ?? defaultTagType(packagePath))
-        .replaceAll('{name}', packagePath.split('/').at(-1) ?? packagePath)
-        .replaceAll('{slug}', packagePath.split('/').at(-1) ?? packagePath)
-        .replaceAll('{version}', '');
-}
-function defaultTagType(packagePath, type) {
-    if ('.' === packagePath && type) {
-        return type;
-    }
-    const first = packagePath.split('/')[0] ?? 'package';
-    const irregular = {
-        actions: 'action',
-        plugins: 'plugin',
-        themes: 'theme',
-        php: 'php',
-        js: 'js',
-    };
-    return irregular[first] ?? first.replace(/s$/, '');
+export function formatTag(format, pkg, version) {
+    return formatTemplate(format, pkg, version)
+        .replace(/\/{2,}/g, '/')
+        .replace(/^\/+/, '');
 }

package/dist/version-files.d.ts

@@ -1,19 +1,18 @@
 import type { PackageVersionSource, PackageVersionTarget } from './changeset-config.ts';
-import type { ConfiguredPackage } from './changeset-packages.ts';
+import type { ConfiguredPackage, ConfiguredDeployPackage } from './changeset-packages.ts';
 import type { FileJournal } from './file-journal.ts';
 import type { ReleaseRepository } from './release-repository.ts';
 /**
  * Read the current version of a package from its configured source.
  *
- * @param  repository   Repository, for versions stored as git tags.
- * @param  directory    Package directory.
- * @param  descriptor   Version source.
- * @param  relativePath Package path relative to the package root.
- * @param  tagType      Configured {type} of the package tags.
+ * @param  repository Repository, for versions stored as git tags.
+ * @param  directory  Package directory.
+ * @param  descriptor Version source.
+ * @param  pkg        Package name and path, for the tags of a git-tag source.
  * @return Current version.
  * @throws {ValidationError} If the version is missing.
  */
-export declare function readVersion(repository: ReleaseRepository, directory: string, descriptor: PackageVersionSource, relativePath: string, tagType?: string): Promise<string>;
+export declare function readVersion(repository: ReleaseRepository, directory: string, descriptor: PackageVersionSource, pkg: Pick<ConfiguredDeployPackage, 'name' | 'path'>): Promise<string>;
 /**
  * Write a version to a configured version target.
  *
@@ -26,7 +25,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

@@ -4,21 +4,20 @@ import { ValidationError } from "./errors.js";
 import { readJson } from "./json-files.js";
 import { findMainPluginFile } from "./package-meta.js";
 import { escapeRegExp } from "./regexp.js";
-import { formatTemplatePrefix } from "./tag-format.js";
+import { DEFAULT_TAG_FORMAT, formatTag } 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.
  *
- * @param  repository   Repository, for versions stored as git tags.
- * @param  directory    Package directory.
- * @param  descriptor   Version source.
- * @param  relativePath Package path relative to the package root.
- * @param  tagType      Configured {type} of the package tags.
+ * @param  repository Repository, for versions stored as git tags.
+ * @param  directory  Package directory.
+ * @param  descriptor Version source.
+ * @param  pkg        Package name and path, for the tags of a git-tag source.
  * @return Current version.
  * @throws {ValidationError} If the version is missing.
  */
-export async function readVersion(repository, directory, descriptor, relativePath, tagType) {
+export async function readVersion(repository, directory, descriptor, pkg) {
     if ('package-json' === descriptor.kind ||
         'composer-json' === descriptor.kind) {
         const manifest = await readJson(path.join(directory, descriptor.file));
@@ -29,16 +28,16 @@ export async function readVersion(repository, directory, descriptor, relativePat
         throw new ValidationError(`Missing ${descriptor.file}#${descriptor.field} in ${directory}.`);
     }
     if ('git-tag' === descriptor.kind) {
-        const pattern = descriptor.pattern ?? '{path}/{version}';
-        const tags = await repository.listTags(formatTemplatePrefix(pattern, relativePath, tagType));
+        const pattern = descriptor.pattern ?? DEFAULT_TAG_FORMAT;
+        const tags = await repository.listTags(formatTag(pattern, pkg, ''));
         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]) {
             return versions[0];
         }
-        throw new ValidationError(`No git tag matches ${pattern} for ${relativePath}.`);
+        throw new ValidationError(`No git tag matches ${pattern} for ${pkg.path}.`);
     }
     if ('php-constant' === descriptor.kind) {
         const file = path.join(directory, descriptor.file);
@@ -99,9 +98,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 +118,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,12 +135,13 @@ 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 {
-            actual = await readVersion(repository, pkg.directory, target, pkg.path, pkg.group.tagType);
+            actual = await readVersion(repository, pkg.directory, target, pkg);
         }
         if (undefined !== actual && actual !== expected) {
             throw new ValidationError(`Version mismatch for ${pkg.name}: expected ${expected}, found ${actual}.`);

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.12.0",
+	"version": "0.14.0",
 	"description": "Package, checksum, sign, verify and version-check WordPress plugins and themes, and deploy plugins to WordPress.org SVN",
 	"license": "MIT",
 	"repository": {
@@ -58,7 +58,7 @@
 		"build": "tsc -p tsconfig.build.json",
 		"prepack": "npm run build",
 		"lint": "npm-run-all lint:*",
-		"lint:js": "wp-scripts lint-js src",
+		"lint:js": "wp-scripts lint-js",
 		"lint:types": "tsc -p tsconfig.json",
 		"format": "wp-scripts format src",
 		"test": "node --test --conditions=wpelevator-source"