@wpelevator/wp-release 0.10.0 → 0.11.0

package/dist/release-tags.js

@@ -0,0 +1,89 @@
+import { readChangelogSection, getLatestChangelogVersion, } from "./changelog.js";
+import { assertKnownPackages, toChangesetPackage, } from "./changeset-packages.js";
+import { ValidationError } from "./errors.js";
+import { compareVersions, isVersion } from "./versions.js";
+/**
+ * Pick the packages to tag.
+ *
+ * @param  packages Configured packages.
+ * @param  names    Packages passed with --package, empty for all.
+ * @param  version  Expected version passed with --version, if any.
+ * @return Selected packages in the configured order.
+ * @throws {ValidationError} For unknown packages, or an expected version without a single package.
+ */
+export function selectTagPackages(packages, names, version) {
+    if (undefined !== version && 1 !== names.length) {
+        throw new ValidationError('An expected version requires exactly one package.');
+    }
+    assertKnownPackages(packages, names);
+    return names.length
+        ? packages.filter((pkg) => names.includes(pkg.name))
+        : packages;
+}
+/**
+ * Get the version to tag. Packages versioned by their git tags have no
+ * version file, so the expected version is the version to tag, or else the
+ * latest CHANGELOG.md version.
+ *
+ * @param pkg      Configured package.
+ * @param expected Expected version from --version, if any.
+ * @return Version to tag.
+ */
+export async function getTagVersion(pkg, expected) {
+    if ('git-tag' !== pkg.versionConfig.from.kind) {
+        return pkg.currentVersion;
+    }
+    return (expected ??
+        (await getLatestChangelogVersion(pkg.directory, pkg.currentVersion)));
+}
+/**
+ * Find the tag of the newest release before a version.
+ *
+ * @param repository Repository with the tags.
+ * @param prefix     Tag prefix of the package, like `plugins/alpha/`.
+ * @param version    Version being released.
+ * @return Previous tag, or undefined for the first release.
+ */
+export async function getPreviousTag(repository, prefix, version) {
+    const tags = await repository.listTags(prefix);
+    return tags
+        .filter((tag) => tag.startsWith(prefix))
+        .map((tag) => ({ tag, version: tag.slice(prefix.length) }))
+        .filter((item) => isVersion(item.version) &&
+        compareVersions(item.version, version) < 0)
+        .sort((a, b) => compareVersions(b.version, a.version))[0]?.tag;
+}
+/**
+ * Build the release notes of a tag from its CHANGELOG.md section, or from the
+ * commits since the previous release without one, with the configured
+ * formatter.
+ *
+ * @param repository Repository with the release commits.
+ * @param config     Repository release configuration.
+ * @param pkg        Released package.
+ * @param release    Version, tag and previous tag of the release.
+ * @param end        Commit of the release: the tag, or HEAD before tagging.
+ * @return Release notes.
+ */
+export async function getReleaseNotes(repository, config, pkg, release, end) {
+    const changelog = await readChangelogSection(pkg.directory, release.version);
+    const commits = await repository.getDirectoryCommits(release.previousTag ? `${release.previousTag}..${end}` : end, pkg.directory);
+    const notes = changelog ||
+        commits
+            .map((commit) => `- ${commit.subject} (${commit.shortHash})`)
+            .join('\n');
+    if (!config.releaseNotes) {
+        return notes;
+    }
+    const formatted = await config.releaseNotes({
+        package: toChangesetPackage(pkg),
+        ...release,
+        changelog,
+        commits,
+        notes,
+    });
+    if ('string' !== typeof formatted) {
+        throw new ValidationError(`The releaseNotes formatter didn't return a string for package "${pkg.name}".`);
+    }
+    return formatted.trim();
+}

package/dist/tag-format.d.ts

@@ -0,0 +1,20 @@
+import type { ConfiguredPackage } 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 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;
+/**
+ * Format the tag prefix of a package before its name is known, for packages
+ * versioned by their git tags.
+ *
+ * @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.
+ */
+export declare function formatTemplatePrefix(pattern: string, packagePath: string, tagType?: string): string;

package/dist/tag-format.js

@@ -0,0 +1,51 @@
+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 version Released version, empty for the tag prefix of the package.
+ * @return Tag name.
+ */
+export function formatTag(format, pkg, version) {
+    const type = pkg.group.tagType ?? defaultTagType(pkg.path, pkg.type);
+    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('{version}', version);
+}
+/**
+ * Format the tag prefix of a package before its name is known, for packages
+ * versioned by their git tags.
+ *
+ * @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.
+ */
+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$/, '');
+}

package/dist/version-check.js

@@ -5,6 +5,7 @@ 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";
+import { escapeRegExp } from "./regexp.js";
 export const GIT_TAG_FORMAT = '{version}';
 const TAG_REF_PREFIX = 'refs/tags/';
 /**
@@ -66,9 +67,6 @@ export function getGitTagVersion(input) {
     const version = new RegExp(`^${pattern}$`).exec(tag)?.[1];
     return version ? normalizeTag(version) : null;
 }
-function escapeRegExp(text) {
-    return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
 /**
  * Find the values of a PHP constant set with define( 'NAME', '1.2.0' ) or
  * const NAME = '1.2.0'.

package/dist/version-files.d.ts

@@ -0,0 +1,36 @@
+import type { PackageVersionSource, PackageVersionTarget } from './changeset-config.ts';
+import type { ConfiguredPackage } 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.
+ * @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>;
+/**
+ * Write a version to a configured version target.
+ *
+ * @param  directory  Package directory.
+ * @param  descriptor Version target.
+ * @param  version    Version to write.
+ * @param  journal    File journal for rolling back.
+ * @throws {ValidationError} If the target file has no version to replace.
+ */
+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.
+ *
+ * @param  repository Repository, for versions stored as git tags.
+ * @param  pkg        Configured package.
+ * @param  expected   Expected version.
+ * @throws {ValidationError} For the first target with another version.
+ */
+export declare function verifyVersionTargets(repository: ReleaseRepository, pkg: ConfiguredPackage, expected: string): Promise<void>;

package/dist/version-files.js

@@ -0,0 +1,195 @@
+import { access, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+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 { findConstantValues } from "./version-check.js";
+import { compareVersions } 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.
+ * @return Current version.
+ * @throws {ValidationError} If the version is missing.
+ */
+export async function readVersion(repository, directory, descriptor, relativePath, tagType) {
+    if ('package-json' === descriptor.kind ||
+        'composer-json' === descriptor.kind) {
+        const manifest = await readJson(path.join(directory, descriptor.file));
+        const version = manifest[descriptor.field];
+        if ('string' === typeof version && version.trim()) {
+            return version;
+        }
+        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 versions = tags
+            .map((tag) => tag.match(/(?:^|\/|v)(\d+\.\d+\.\d+)$/)?.[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}.`);
+    }
+    if ('php-constant' === descriptor.kind) {
+        const file = path.join(directory, descriptor.file);
+        const contents = await readFile(file, 'utf8');
+        const versions = findConstantValues(contents, descriptor.constant);
+        if (versions[0]) {
+            return versions[0];
+        }
+        throw new ValidationError(`Missing PHP constant ${descriptor.constant} in ${file}.`);
+    }
+    const file = path.join(directory, await getVersionFile(directory, descriptor.kind, descriptor.file));
+    const contents = await readFile(file, 'utf8');
+    const label = 'wordpress-stable-tag' === descriptor.kind ? 'Stable tag' : 'Version';
+    const match = new RegExp(`^\\s*\\*?\\s*${label}:\\s*([^\\r\\n]+)`, 'im').exec(contents);
+    if (!match) {
+        throw new ValidationError(`Missing ${label} header in ${file}.`);
+    }
+    return match[1]?.trim() ?? '';
+}
+/**
+ * Write a version to a configured version target.
+ *
+ * @param  directory  Package directory.
+ * @param  descriptor Version target.
+ * @param  version    Version to write.
+ * @param  journal    File journal for rolling back.
+ * @throws {ValidationError} If the target file has no version to replace.
+ */
+export async function writeVersion(directory, descriptor, version, journal) {
+    if ('package-json' === descriptor.kind ||
+        'composer-json' === descriptor.kind) {
+        const file = path.join(directory, descriptor.file);
+        const contents = await readFile(file, 'utf8');
+        const manifest = JSON.parse(contents);
+        if ('composer-json' === descriptor.kind &&
+            descriptor.ifPresent &&
+            !Object.hasOwn(manifest, descriptor.field)) {
+            return;
+        }
+        manifest[descriptor.field] = version;
+        await journal.remember(file);
+        await writeFile(file, `${JSON.stringify(manifest, null, '\t')}\n`);
+        return;
+    }
+    if ('php-constant' === descriptor.kind) {
+        const file = path.join(directory, descriptor.file);
+        const contents = await readFile(file, 'utf8');
+        const constant = escapeRegExp(descriptor.constant);
+        const definePattern = new RegExp(`(\\bdefine\\s*\\(\\s*(['"])${constant}\\2\\s*,\\s*)(['"])(.*?)\\3`, 'g');
+        const declarationPattern = new RegExp(`(\\bconst\\s+${constant}\\s*=\\s*)(['"])(.*?)\\2`, 'g');
+        const updated = contents
+            .replace(definePattern, (_match, prefix, _nameQuote, quote) => `${prefix}${quote}${version}${quote}`)
+            .replace(declarationPattern, (_match, prefix, quote) => `${prefix}${quote}${version}${quote}`);
+        if (updated === contents) {
+            throw new ValidationError(`Missing PHP constant ${descriptor.constant} in ${file}.`);
+        }
+        await journal.remember(file);
+        await writeFile(file, updated);
+        return;
+    }
+    if ('wordpress-stable-tag' === descriptor.kind &&
+        descriptor.ifPresent &&
+        !(await versionFileExists(directory, descriptor.kind, descriptor.file))) {
+        return;
+    }
+    const file = path.join(directory, await getVersionFile(directory, descriptor.kind, descriptor.file));
+    const contents = await readFile(file, 'utf8');
+    const label = 'wordpress-stable-tag' === descriptor.kind ? 'Stable tag' : 'Version';
+    const expression = new RegExp(`(^\\s*\\*?\\s*${label}:\\s*)[^\\r\\n]+`, 'im');
+    if (!expression.test(contents)) {
+        throw new ValidationError(`Missing ${label} header in ${file}.`);
+    }
+    await journal.remember(file);
+    await writeFile(file, contents.replace(expression, `$1${version}`));
+}
+/**
+ * Check that every version target of a package has the expected version.
+ * Optional targets that are absent are skipped.
+ *
+ * @param  repository Repository, for versions stored as git tags.
+ * @param  pkg        Configured package.
+ * @param  expected   Expected version.
+ * @throws {ValidationError} For the first target with another version.
+ */
+export async function verifyVersionTargets(repository, pkg, expected) {
+    for (const target of pkg.versionConfig.to) {
+        let actual;
+        if ('composer-json' === target.kind &&
+            target.ifPresent &&
+            !Object.hasOwn(await readJson(path.join(pkg.directory, target.file)), target.field)) {
+            actual = undefined;
+        }
+        else if ('wordpress-stable-tag' === target.kind &&
+            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);
+        }
+        if (undefined !== actual && actual !== expected) {
+            throw new ValidationError(`Version mismatch for ${pkg.name}: expected ${expected}, found ${actual}.`);
+        }
+    }
+}
+async function getVersionFile(directory, kind, configuredFile) {
+    if (configuredFile) {
+        return configuredFile;
+    }
+    if ('wordpress-plugin-header' === kind) {
+        const file = await findMainPluginFile({ dir: directory });
+        if (file) {
+            return file;
+        }
+        throw new ValidationError(`Could not find a plugin header file in ${directory}.`);
+    }
+    if ('wordpress-stable-tag' === kind) {
+        for (const file of ['readme.txt', 'readme.md']) {
+            try {
+                await access(path.join(directory, file));
+                return file;
+            }
+            catch {
+                // Try the next WordPress readme filename.
+            }
+        }
+        throw new ValidationError(`Could not find readme.txt or readme.md in ${directory}.`);
+    }
+    return 'style.css';
+}
+async function versionFileExists(directory, kind, configuredFile) {
+    if (configuredFile) {
+        try {
+            await access(path.join(directory, configuredFile));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    if ('wordpress-stable-tag' === kind) {
+        const files = await Promise.all(['readme.txt', 'readme.md'].map(async (file) => {
+            try {
+                await access(path.join(directory, file));
+                return true;
+            }
+            catch {
+                return false;
+            }
+        }));
+        return files.some(Boolean);
+    }
+    return true;
+}

package/dist/versions.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Check whether a string is a SemVer version, like 1.2.0 or 1.2.0-rc.1.
+ *
+ * @param version Version.
+ * @return Whether the version is valid.
+ */
+export declare function isVersion(version: string): boolean;
+/**
+ * Check whether a version has a pre-release part, like 1.0.0-rc.1.
+ *
+ * @param version Version.
+ * @return Whether the version is a valid pre-release.
+ */
+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.
+ *
+ * @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;

package/dist/versions.js

@@ -0,0 +1,74 @@
+/**
+ * Stable or pre-release SemVer version without build metadata.
+ */
+const VERSION_PATTERN = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z.-]+))?$/;
+/**
+ * Check whether a string is a SemVer version, like 1.2.0 or 1.2.0-rc.1.
+ *
+ * @param version Version.
+ * @return Whether the version is valid.
+ */
+export function isVersion(version) {
+    return VERSION_PATTERN.test(version);
+}
+/**
+ * Check whether a version has a pre-release part, like 1.0.0-rc.1.
+ *
+ * @param version Version.
+ * @return Whether the version is a valid pre-release.
+ */
+export function isPrerelease(version) {
+    return Boolean(VERSION_PATTERN.exec(version)?.[4]);
+}
+/**
+ * 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.
+ *
+ * @param left  Version.
+ * @param right Version to compare with.
+ * @return Negative when left is lower, positive when higher, otherwise 0.
+ */
+export function compareVersions(left, right) {
+    const [leftCore = '', leftPre] = splitPrerelease(left);
+    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);
+    if (core || leftPre === rightPre) {
+        return core;
+    }
+    if (undefined === leftPre || undefined === rightPre) {
+        return undefined === leftPre ? 1 : -1;
+    }
+    return comparePrerelease(leftPre.split('.'), rightPre.split('.'));
+}
+function splitPrerelease(version) {
+    const index = version.indexOf('-');
+    return -1 === index
+        ? [version]
+        : [version.slice(0, index), version.slice(index + 1)];
+}
+function comparePrerelease(left, right) {
+    const [a, ...leftRest] = left;
+    const [b, ...rightRest] = right;
+    if (undefined === a || undefined === b) {
+        return (undefined === a ? 0 : 1) - (undefined === b ? 0 : 1);
+    }
+    const order = compareIdentifier(a, b);
+    return order || comparePrerelease(leftRest, rightRest);
+}
+function compareIdentifier(a, b) {
+    const aNumeric = /^\d+$/.test(a);
+    const bNumeric = /^\d+$/.test(b);
+    if (aNumeric && bNumeric) {
+        return Number(a) - Number(b);
+    }
+    if (aNumeric || bNumeric) {
+        return aNumeric ? -1 : 1;
+    }
+    return Number(a > b) - Number(a < b);
+}

package/package.json

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