@wpelevator/wp-release 0.0.0-stage → 0.1.1

package/dist/unzip.js

@@ -0,0 +1,121 @@
+import { createWriteStream } from 'node:fs';
+import { mkdir } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { pipeline } from 'node:stream/promises';
+import yauzl from 'yauzl';
+import { ValidationError } from "./errors.js";
+/**
+ * File type of a symbolic link in the upper bits of a Unix mode (S_IFLNK).
+ */
+const SYMLINK_FILE_TYPE = 0o12;
+/**
+ * Open an archive with yauzl and call a callback for every entry, one at a
+ * time.
+ *
+ * @param zipPath Archive path.
+ * @param onEntry Callback for each entry, awaited before reading the next.
+ */
+async function readEntries(zipPath, onEntry) {
+    const zip = await new Promise((resolve, reject) => yauzl.open(zipPath, { lazyEntries: true, autoClose: false }, (error, file) => (error ? reject(error) : resolve(file)))).catch((error) => {
+        throw new ValidationError(`${zipPath} isn't a valid ZIP file: ${error.message}`);
+    });
+    try {
+        await new Promise((resolve, reject) => {
+            zip.on('entry', (entry) => onEntry(entry, zip).then(() => zip.readEntry(), reject));
+            zip.on('end', resolve);
+            zip.on('error', (error) => reject(new ValidationError(`Can't read ${zipPath}: ${error.message}`)));
+            zip.readEntry();
+        });
+    }
+    finally {
+        zip.close();
+    }
+}
+/**
+ * Get the type of an archive entry. Directories end with a slash, and
+ * symbolic links have the link file type in the Unix mode.
+ *
+ * @param entry Archive entry.
+ * @return Entry type.
+ */
+function getEntryType(entry) {
+    // The Unix mode is in the upper 16 bits, and the file type above its lower 12 bits.
+    const mode = Math.floor(entry.externalFileAttributes / 0x10000);
+    if (SYMLINK_FILE_TYPE === Math.floor(mode / 0o10000) % 0o20) {
+        return 'symlink';
+    }
+    return entry.fileName.endsWith('/') ? 'directory' : 'file';
+}
+/**
+ * List the entries of an archive without extracting it.
+ *
+ * @param zipPath Archive path.
+ * @return Entries in archive order.
+ */
+export async function readZipEntries(zipPath) {
+    const entries = [];
+    await readEntries(zipPath, async (entry) => {
+        entries.push({ path: entry.fileName, type: getEntryType(entry) });
+    });
+    return entries;
+}
+/**
+ * Collect the problems that make an archive unsafe or unexpected to extract:
+ * absolute paths, ".." segments, backslashes, symbolic links and entries
+ * outside the root folder.
+ *
+ * @param entries    Entries from readZipEntries().
+ * @param rootFolder Root folder that every entry must be in, or null.
+ * @return Error messages, empty when the archive can be extracted.
+ */
+export function getZipEntryErrors(entries, rootFolder = null) {
+    const errors = entries.map(({ path, type }) => {
+        if (path.startsWith('/') || /^[a-zA-Z]:/.test(path)) {
+            return `${path} is an absolute path.`;
+        }
+        const segments = path.split('/');
+        if (path.includes('\\') || segments.includes('..')) {
+            return `${path} is outside the archive root.`;
+        }
+        if ('symlink' === type) {
+            return `${path} is a symbolic link, which isn't supported.`;
+        }
+        if (rootFolder && segments[0] !== rootFolder) {
+            return `${path} isn't in the ${rootFolder}/ root folder.`;
+        }
+        return null;
+    });
+    return errors.filter((error) => null !== error);
+}
+/**
+ * Extract an archive after checking every entry with getZipEntryErrors(),
+ * so that nothing is written outside the target directory. The root folder,
+ * when set, is stripped from the paths.
+ *
+ * @param  input Archive, target directory and root folder.
+ * @return Extracted file paths relative to the target directory, sorted.
+ * @throws {ValidationError} If the archive has unsafe or unexpected entries.
+ */
+export async function extractZip(input) {
+    const { zipPath, targetDir, rootFolder = null } = input;
+    const errors = getZipEntryErrors(await readZipEntries(zipPath), rootFolder);
+    const files = [];
+    if (errors.length) {
+        throw new ValidationError(`Can't extract ${zipPath}:\n${errors.join('\n')}`);
+    }
+    await readEntries(zipPath, async (entry, zip) => {
+        const path = rootFolder
+            ? entry.fileName.split('/').slice(1).join('/')
+            : entry.fileName;
+        if (path && 'file' === getEntryType(entry)) {
+            const target = join(targetDir, path);
+            await mkdir(dirname(target), { recursive: true });
+            await pipeline(await openReadStream(zip, entry), createWriteStream(target, { flags: 'wx' }));
+            files.push(path);
+        }
+    });
+    return files.sort();
+}
+function openReadStream(zip, entry) {
+    return new Promise((resolve, reject) => zip.openReadStream(entry, (error, stream) => error ? reject(error) : resolve(stream)));
+}

package/dist/version-check.d.ts

@@ -0,0 +1,75 @@
+import type { PackageMeta } from './package-meta.ts';
+export declare const GIT_TAG_FORMAT = "{version}";
+/**
+ * A version that differs from the expected one, or a version that is missing.
+ */
+export interface VersionMismatch {
+    /** Where the version comes from, like "Stable tag" or "Git tag". */
+    source: string;
+    /** File that holds the version, if any. */
+    file: string | null;
+    /** Version found, or null when it's missing. */
+    actual: string | null;
+    /** Human-readable description. */
+    message: string;
+}
+export interface FindVersionMismatchesInput {
+    /** Plugin or theme directory. */
+    sourceDir: string;
+    /** Metadata from readPackageMeta(). */
+    meta: PackageMeta;
+    /** Plugin or theme slug, for {slug} in the git tag format. */
+    slug: string;
+    /** Expected version, defaults to the Version header. */
+    version?: string | null;
+    /** Git tag name or ref like refs/tags/v1.2.0, not compared when empty. */
+    gitTag?: string | null;
+    /** Git tag format with {version} and {slug}, defaults to {version}. */
+    gitTagFormat?: string;
+    /** PHP constants that must be set to the version. */
+    constants?: string[];
+    /** Compare the readme Stable tag of plugins, defaults to true. */
+    stableTag?: boolean;
+}
+export interface GitTagInput {
+    /** Git tag name or ref like refs/tags/v1.2.0. */
+    gitTag?: string;
+    /** Git tag format with {version} and {slug}, defaults to {version}. */
+    gitTagFormat?: string;
+    /** Plugin or theme slug. */
+    slug: string;
+}
+export interface VersionCheckResult {
+    /** Expected version, or null when it's unknown. */
+    version: string | null;
+    /** Every mismatch, empty when all versions agree. */
+    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
+ * deploys, so v1.2.0 matches the default {version} format.
+ *
+ * @param  input Tag, format and slug.
+ * @return Version, or null when the tag doesn't match the format.
+ * @throws {ValidationError} If the format has no {version}.
+ */
+export declare function getGitTagVersion(input: GitTagInput): string | null;
+/**
+ * Find the values 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 in the order they appear.
+ */
+export declare function findConstantValues(contents: string, name: string): string[];
+/**
+ * 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
+ * no Stable tag, so it's only compared for plugins.
+ *
+ * @param input Package metadata and the versions to compare.
+ * @return Expected version and the mismatches.
+ */
+export declare function findVersionMismatches(input: FindVersionMismatchesInput): Promise<VersionCheckResult>;

package/dist/version-check.js

@@ -0,0 +1,193 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import ignore from 'ignore';
+import { normalizeTag } from "./deploy-options.js";
+import { ValidationError } from "./errors.js";
+import { selectFiles } from "./file-selection.js";
+export const GIT_TAG_FORMAT = '{version}';
+const TAG_REF_PREFIX = 'refs/tags/';
+/**
+ * Directories that aren't searched for PHP constants, since they hold
+ * dependencies with their own versions.
+ */
+const CONSTANT_SEARCH_IGNORE = ['node_modules/', 'vendor/', '.*'];
+/**
+ * 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
+ * deploys, so v1.2.0 matches the default {version} format.
+ *
+ * @param  input Tag, format and slug.
+ * @return Version, or null when the tag doesn't match the format.
+ * @throws {ValidationError} If the format has no {version}.
+ */
+export function getGitTagVersion(input) {
+    const { gitTag = '', gitTagFormat = GIT_TAG_FORMAT, slug } = input;
+    const tag = (gitTag ?? '').replace(TAG_REF_PREFIX, '');
+    if (!gitTagFormat.includes('{version}')) {
+        throw new ValidationError(`The git tag format "${gitTagFormat}" needs a {version} placeholder.`);
+    }
+    const pattern = escapeRegExp(gitTagFormat)
+        .replaceAll('\\{slug\\}', escapeRegExp(slug))
+        .replace('\\{version\\}', '(.+)');
+    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'.
+ *
+ * @param contents PHP code.
+ * @param name     Constant name.
+ * @return Values in the order they appear.
+ */
+export function findConstantValues(contents, name) {
+    const quotedName = `(['"])${escapeRegExp(name)}\\1`;
+    const patterns = [
+        new RegExp(`\\bdefine\\s*\\(\\s*${quotedName}\\s*,\\s*(['"])(.*?)\\2\\s*[,)]`, 'g'),
+        new RegExp(`\\bconst\\s+()${escapeRegExp(name)}\\s*=\\s*(['"])(.*?)\\2\\s*;`, 'g'),
+    ];
+    return patterns
+        .flatMap((pattern) => [...contents.matchAll(pattern)])
+        .sort((a, b) => (a.index ?? 0) - (b.index ?? 0))
+        .map((match) => match[3] ?? '');
+}
+/**
+ * Compare a version with the expected one.
+ *
+ * @param mismatch Mismatch details without the message.
+ * @param expected Expected version.
+ * @return The mismatch, or null when the version matches.
+ */
+function compareVersion(mismatch, expected) {
+    const { source, file, actual } = mismatch;
+    const location = file ? ` in ${file}` : '';
+    if (null === actual) {
+        return {
+            ...mismatch,
+            message: `${source} is missing${location}, expected ${expected}.`,
+        };
+    }
+    if (actual !== expected) {
+        return {
+            ...mismatch,
+            message: `${source}${location} is ${actual}, expected ${expected}.`,
+        };
+    }
+    return null;
+}
+/**
+ * Compare the PHP constants with the expected version. Every PHP file except
+ * dependencies is searched, so that constants defined outside the main
+ * plugin file are found too.
+ *
+ * @param sourceDir Plugin or theme directory.
+ * @param constants Constant names.
+ * @param expected  Expected version.
+ * @return Mismatches, including a missing entry for each constant that isn't defined.
+ */
+async function compareConstants(sourceDir, constants, expected) {
+    const files = constants.length
+        ? await selectFiles(sourceDir, ignore().add(CONSTANT_SEARCH_IGNORE))
+        : [];
+    const sources = await Promise.all(files
+        .filter((file) => file.endsWith('.php'))
+        .map(async (file) => ({
+        file,
+        contents: await readFile(join(sourceDir, file), 'utf8'),
+    })));
+    return constants.flatMap((name) => {
+        const source = `Constant ${name}`;
+        const definitions = sources.flatMap(({ file, contents }) => findConstantValues(contents, name).map((actual) => ({
+            source,
+            file,
+            actual,
+        })));
+        if (definitions.length) {
+            return definitions.map((definition) => compareVersion(definition, expected));
+        }
+        return [
+            compareVersion({ source, file: null, actual: null }, expected),
+        ];
+    });
+}
+/**
+ * Compare the version in a git tag with the expected version.
+ *
+ * @param input    Tag, format and slug.
+ * @param expected Expected version.
+ * @return The mismatch, or null when the tag matches.
+ */
+function compareGitTag(input, expected) {
+    const tag = input.gitTag.replace(TAG_REF_PREFIX, '');
+    const actual = getGitTagVersion(input);
+    if (null === actual) {
+        return {
+            source: 'Git tag',
+            file: null,
+            actual: tag,
+            message: `Git tag ${tag} doesn't match the format ${input.gitTagFormat}.`,
+        };
+    }
+    return compareVersion({ source: `Git tag ${tag}`, file: null, actual }, expected);
+}
+/**
+ * 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
+ * no Stable tag, so it's only compared for plugins.
+ *
+ * @param input Package metadata and the versions to compare.
+ * @return Expected version and the mismatches.
+ */
+export async function findVersionMismatches(input) {
+    const { sourceDir, meta, slug, gitTag = null, gitTagFormat = GIT_TAG_FORMAT, constants = [], stableTag = true, } = input;
+    const version = input.version ? normalizeTag(input.version) : null;
+    const expected = version ?? meta.version;
+    if (!expected) {
+        return {
+            version: null,
+            mismatches: [
+                {
+                    source: 'Version header',
+                    file: meta.mainFile,
+                    actual: null,
+                    message: `Version header is missing in ${meta.mainFile}.`,
+                },
+            ],
+        };
+    }
+    const readme = meta.readme;
+    const checkStableTag = stableTag && 'plugin' === meta.type;
+    const mismatches = [
+        compareVersion({
+            source: 'Version header',
+            file: meta.mainFile,
+            actual: meta.version,
+        }, expected),
+        checkStableTag && !readme
+            ? {
+                source: 'Stable tag',
+                file: null,
+                actual: null,
+                message: `Readme is missing, expected Stable tag ${expected}.`,
+            }
+            : null,
+        checkStableTag && readme
+            ? compareVersion({
+                source: 'Stable tag',
+                file: readme.file,
+                actual: readme.headers['Stable tag'] ?? null,
+            }, expected)
+            : null,
+        ...(await compareConstants(sourceDir, constants, expected)),
+        gitTag
+            ? compareGitTag({ gitTag, gitTagFormat, slug }, expected)
+            : null,
+    ];
+    return {
+        version: expected,
+        mismatches: mismatches.filter((mismatch) => null !== mismatch),
+    };
+}

package/dist/zip.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Modification time of every archive entry, so that the same files always
+ * give the same archive. It's local midnight on the first day that ZIP
+ * timestamps support, since ZIP stores local time without a time zone.
+ */
+export declare const ZIP_MTIME: Date;
+/**
+ * File mode of every archive entry, so that the archive doesn't depend on
+ * the umask or file system of the machine that builds it.
+ */
+export declare const ZIP_FILE_MODE = 33188;
+export interface CreateZipInput {
+    /** Directory with the files. */
+    sourceDir: string;
+    /** Relative file paths with forward slashes, from selectFiles(). */
+    files: string[];
+    /** Archive path. */
+    zipPath: string;
+    /** Folder to put the files in inside the archive, or null for the root. */
+    rootFolder?: string | null;
+    /** Overwrite an existing archive. */
+    force?: boolean;
+}
+/**
+ * Write a ZIP archive of files, streaming each file into the archive. The
+ * entries are sorted and use a fixed timestamp and file mode, so that the
+ * same files always give the same archive.
+ *
+ * @param  input Files, archive path and root folder.
+ * @throws {ValidationError} If the archive exists and force isn't set.
+ */
+export declare function createZip(input: CreateZipInput): Promise<void>;

package/dist/zip.js

@@ -0,0 +1,53 @@
+import { createWriteStream } from 'node:fs';
+import { rm } from 'node:fs/promises';
+import { join, posix } from 'node:path';
+import { pipeline } from 'node:stream/promises';
+import yazl from 'yazl';
+import { ValidationError } from "./errors.js";
+import { isErrorCode } from "./file-selection.js";
+/**
+ * Modification time of every archive entry, so that the same files always
+ * give the same archive. It's local midnight on the first day that ZIP
+ * timestamps support, since ZIP stores local time without a time zone.
+ */
+export const ZIP_MTIME = new Date(1980, 0, 1);
+/**
+ * File mode of every archive entry, so that the archive doesn't depend on
+ * the umask or file system of the machine that builds it.
+ */
+export const ZIP_FILE_MODE = 0o100644;
+/**
+ * Write a ZIP archive of files, streaming each file into the archive. The
+ * entries are sorted and use a fixed timestamp and file mode, so that the
+ * same files always give the same archive.
+ *
+ * @param  input Files, archive path and root folder.
+ * @throws {ValidationError} If the archive exists and force isn't set.
+ */
+export async function createZip(input) {
+    const { sourceDir, files, zipPath, rootFolder = null, force = false, } = input;
+    if (rootFolder && !isValidRootFolder(rootFolder)) {
+        throw new ValidationError(`Invalid root folder "${rootFolder}", use a single folder name.`);
+    }
+    const zip = new yazl.ZipFile();
+    const output = createWriteStream(zipPath, { flags: force ? 'w' : 'wx' });
+    [...files].sort().forEach((file) => zip.addFile(join(sourceDir, file), rootFolder ? posix.join(rootFolder, file) : file, {
+        mtime: ZIP_MTIME,
+        mode: ZIP_FILE_MODE,
+        forceDosTimestamp: true,
+    }));
+    zip.end();
+    try {
+        await pipeline(zip.outputStream, output);
+    }
+    catch (error) {
+        if (isErrorCode(error, 'EEXIST')) {
+            throw new ValidationError(`${zipPath} already exists, pass --force to overwrite it.`);
+        }
+        await rm(zipPath, { force: true });
+        throw error;
+    }
+}
+function isValidRootFolder(name) {
+    return !/[\\/]/.test(name) && '.' !== name && '..' !== name;
+}

package/package.json

@@ -1,6 +1,62 @@
 {
-  "name": "@wpelevator/wp-release",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@wpelevator/wp-release",
+	"version": "0.1.1",
+	"description": "Package, checksum, verify and version-check WordPress plugins and themes, and deploy plugins to WordPress.org SVN",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/wpelevator/basement.git",
+		"directory": "packages/js/wp-release"
+	},
+	"type": "module",
+	"bin": {
+		"wp-release": "dist/bin/wp-release.js"
+	},
+	"exports": {
+		".": {
+			"wpelevator-source": "./src/index.ts",
+			"types": "./dist/index.d.ts",
+			"default": "./dist/index.js"
+		}
+	},
+	"files": [
+		"dist"
+	],
+	"publishConfig": {
+		"access": "public"
+	},
+	"engines": {
+		"node": ">=22.12"
+	},
+	"keywords": [
+		"wordpress",
+		"plugin",
+		"theme",
+		"release",
+		"deploy",
+		"svn",
+		"zip"
+	],
+	"dependencies": {
+		"ignore": "^7.0.12",
+		"yauzl": "^3.4.0",
+		"yazl": "^3.3.1"
+	},
+	"devDependencies": {
+		"@types/node": "^22.20.5",
+		"@types/yauzl": "^3.4.0",
+		"@types/yazl": "^3.3.1",
+		"@wordpress/scripts": "^33.0",
+		"npm-run-all2": "^9.0",
+		"typescript": "^6.0.3"
+	},
+	"scripts": {
+		"build": "tsc -p tsconfig.build.json",
+		"prepack": "npm run build",
+		"lint": "npm-run-all lint:*",
+		"lint:js": "wp-scripts lint-js src",
+		"lint:types": "tsc -p tsconfig.json",
+		"format": "wp-scripts format src",
+		"test": "node --test --conditions=wpelevator-source"
+	}
+}