@wpelevator/wp-release 0.12.0 → 0.14.0

package/dist/package-deploy.js

@@ -0,0 +1,323 @@
+import { realpath } from 'node:fs/promises';
+import path from 'node:path';
+import { loadChangesetConfig, toTargetList } from "./changeset-config.js";
+import { discoverDeployPackages, discoverConfiguredPackages, findPackage, } from "./changeset-packages.js";
+import { ValidationError } from "./errors.js";
+import { parseRepositoryUrl, redactUrls } from "./git.js";
+import { ReleaseRepository } from "./release-repository.js";
+import { DEFAULT_TAG_FORMAT, formatTag, formatTemplate } from "./tag-format.js";
+import { isPrerelease, isVersion } from "./versions.js";
+/**
+ * Get the Git deploys of the configured packages that a ref releases: every
+ * Git target of the package of a release tag that releases tags, or of every
+ * package with a Git target that releases the branch.
+ *
+ * @param  options Repository, ref and package selection.
+ * @return Deploys in the configured package and target order.
+ * @throws {ValidationError} Without a config, or for an invalid one or an unknown package.
+ */
+export async function getGitDeploys(options) {
+    const { config, releases, root } = await loadDeployContext(options);
+    const deploys = await Promise.all(releases.map(async (release) => {
+        const targets = toTargetList(release.package.group.deploy?.git);
+        const resolved = await Promise.all(targets
+            .filter((target) => isGitTargetReleased(target, release))
+            .map((target) => getGitDeploy(target, release, config, root, options)));
+        return resolved.filter((deploy) => undefined !== deploy);
+    }));
+    return deploys.flat();
+}
+/**
+ * Get the WordPress.org SVN deploys of the configured package that a release
+ * tag releases. A stable release syncs trunk/, the tag and the assets, and a
+ * pre-release only creates its tag. Branches aren't deployed to SVN.
+ *
+ * @param  options Repository, ref and package selection.
+ * @return Deploys in the configured target order.
+ * @throws {ValidationError} Without a config, or for an invalid one or an unknown package.
+ */
+export async function getSvnDeploys(options) {
+    const { config, releases } = await loadDeployContext(options);
+    const deploys = await Promise.all(releases
+        .filter((release) => release.version)
+        .map(async (release) => {
+        const targets = toTargetList(release.package.group.deploy?.svn);
+        const resolved = await Promise.all(targets.map((target) => getSvnDeploy(target, release, config, options)));
+        return resolved.filter((deploy) => undefined !== deploy);
+    }));
+    return deploys.flat();
+}
+/**
+ * Get the packages with deploy targets and the files that their deploys
+ * ship, for example to build a ZIP with the same files.
+ *
+ * @param  options            Repository root and config file.
+ * @param  options.cwd        Repository root with the wp-release config.
+ * @param  options.configFile Config file, instead of the conventional one at the root.
+ * @return Packages in the configured order.
+ * @throws {ValidationError} Without a config, or for an invalid one.
+ */
+export async function getDeployPackages(options) {
+    const config = await requireConfig(options);
+    const packages = await discoverDeployPackages(new ReleaseRepository({ cwd: options.cwd }), config);
+    return packages.map((pkg) => ({
+        ...toDeployPackage(pkg),
+        files: getFileSelection(pkg, config),
+    }));
+}
+/**
+ * Get a configured package with the files that its releases ship, from the
+ * files config of its package group, which its deploys use too, for example
+ * to build its ZIP with the same files. Any package of the config works, with
+ * or without a version or deploy targets.
+ *
+ * @param  options            Repository root, config file and package.
+ * @param  options.cwd        Repository root with the wp-release config.
+ * @param  options.configFile Config file, instead of the conventional one at the root.
+ * @param  options.package    Package identifier or path under the configured root.
+ * @return The package and its file selection.
+ * @throws {ValidationError} Without a config, for an invalid one or an unknown package.
+ */
+export async function getPackageFiles(options) {
+    const config = await requireConfig(options);
+    const pkg = findPackage(await discoverConfiguredPackages(new ReleaseRepository({ cwd: options.cwd }), config), options.package);
+    if (!pkg) {
+        throw new ValidationError(`Unknown package "${options.package}".`);
+    }
+    return {
+        ...toDeployPackage(pkg),
+        files: getFileSelection(pkg, config),
+    };
+}
+async function requireConfig(options) {
+    const loaded = await loadChangesetConfig({
+        cwd: options.cwd,
+        ...(options.configFile ? { configFile: options.configFile } : {}),
+        ...(options.tagFormat ? { tagFormat: options.tagFormat } : {}),
+    });
+    if (!loaded) {
+        throw new ValidationError('No wp-release config found. Add wp-release.config.js or pass --config <path>.');
+    }
+    return loaded.config;
+}
+async function loadDeployContext(options) {
+    const config = await requireConfig(options);
+    const repository = new ReleaseRepository({
+        cwd: options.cwd,
+        runner: options.git,
+    });
+    const packages = selectPackages(await discoverDeployPackages(repository, config), options.packages ?? []);
+    const root = await repository.run(['rev-parse', '--show-toplevel']);
+    const revision = await repository.run(['rev-parse', 'HEAD^{commit}']);
+    return {
+        config,
+        releases: getReleases(packages, config, options.ref).map((release) => ({ ...release, revision: revision.trim() })),
+        root: root.trim(),
+    };
+}
+function selectPackages(packages, identifiers) {
+    const selected = identifiers.map((identifier) => {
+        const pkg = findPackage(packages, identifier);
+        if (!pkg) {
+            throw new ValidationError(`Unknown package "${identifier}", or it has no deploy targets.`);
+        }
+        return pkg;
+    });
+    return identifiers.length
+        ? packages.filter((pkg) => selected.includes(pkg))
+        : packages;
+}
+/**
+ * Resolve the releases of a ref: the package of a release tag, or every
+ * package for a branch.
+ *
+ * @param packages Packages with deploy targets.
+ * @param config   Repository release configuration.
+ * @param ref      Ref to deploy.
+ * @return Releases.
+ */
+function getReleases(packages, config, ref) {
+    const tagFormat = config.tagFormat ?? DEFAULT_TAG_FORMAT;
+    const tag = ref.startsWith('refs/tags/')
+        ? ref.slice('refs/tags/'.length)
+        : ref;
+    const tagged = ref.startsWith('refs/heads/')
+        ? []
+        : packages.flatMap((pkg) => getTaggedVersion(pkg, tagFormat, tag));
+    const branch = ref.replace(/^refs\/heads\//, '');
+    return ref.startsWith('refs/tags/') || tagged.length
+        ? tagged
+        : packages.map((pkg) => ({ package: pkg, branch }));
+}
+function getTaggedVersion(pkg, tagFormat, tag) {
+    const prefix = formatTag(tagFormat, pkg, '');
+    const version = tag.startsWith(prefix) ? tag.slice(prefix.length) : '';
+    return pkg.group.version && isVersion(version)
+        ? [{ package: pkg, version }]
+        : [];
+}
+function isGitTargetReleased(target, release) {
+    const branches = target.branches ?? true;
+    const branchReleased = Array.isArray(branches)
+        ? branches.includes(release.branch ?? '')
+        : branches;
+    return release.version ? false !== target.tag : branchReleased;
+}
+async function getGitDeploy(target, release, config, root, options) {
+    const pkg = release.package;
+    const tag = release.version
+        ? formatTag(target.tag || '{version}', pkg, release.version)
+        : undefined;
+    const ref = tag ?? release.branch ?? '';
+    const repository = await resolveTemplate(target.repository, release, ref);
+    const message = target.message
+        ? await resolveTemplate(target.message, release, ref)
+        : '';
+    // Git reports the real path of the root, so compare it with the real path
+    // of the package, like on macOS where the temporary directory is a link.
+    const splitPrefix = false === target.history
+        ? ''
+        : path
+            .relative(root, await realpath(pkg.directory))
+            .split(path.sep)
+            .join('/');
+    const location = repository ? parseRepositoryUrl(repository) : undefined;
+    return repository
+        ? {
+            package: toDeployPackage(pkg),
+            release: toRelease(release),
+            target: redactUrls(repository),
+            targetRef: ref,
+            ...(location
+                ? { targetHost: location.host, targetPath: location.path }
+                : {}),
+            label: `${pkg.name} to ${redactUrls(repository)} ${ref}`,
+            input: {
+                cwd: options.cwd,
+                sourceDir: pkg.directory,
+                gitUrl: repository,
+                ...(release.branch ? { branch: release.branch } : {}),
+                ...(tag ? { tag } : {}),
+                ...(splitPrefix ? { splitPrefix } : {}),
+                ...(message ? { message } : {}),
+                ...getFileSelection(pkg, config),
+                dryRun: Boolean(options.dryRun),
+            },
+        }
+        : undefined;
+}
+async function getSvnDeploy(target, release, config, options) {
+    const pkg = release.package;
+    const version = release.version ?? '';
+    const stable = !isPrerelease(version);
+    // The WordPress.org slug is the name of the package directory by default.
+    const slug = target.slug
+        ? await resolveTemplate(target.slug, release, version)
+        : path.basename(pkg.directory);
+    const message = target.message
+        ? await resolveTemplate(target.message, release, version)
+        : '';
+    return slug
+        ? {
+            package: toDeployPackage(pkg),
+            release: toRelease(release),
+            target: `WordPress.org ${slug}`,
+            targetRef: version,
+            label: `${pkg.name} to WordPress.org ${slug} ${version}`,
+            input: {
+                cwd: options.cwd,
+                sourceDir: pkg.directory,
+                slug,
+                version,
+                svnTag: version,
+                trunk: stable,
+                ...(stable && target.assetsDir
+                    ? {
+                        assetsDir: path.join(pkg.directory, target.assetsDir),
+                    }
+                    : {}),
+                ...(target.readme ? { readme: target.readme } : {}),
+                ...(target.url ? { svnUrl: target.url } : {}),
+                ...(message ? { message } : {}),
+                ...getFileSelection(pkg, config),
+                dryRun: Boolean(options.dryRun),
+            },
+        }
+        : undefined;
+}
+/**
+ * Resolve a template with the package and release placeholders, or call the
+ * callback with the package and its release.
+ *
+ * @param template Template or callback.
+ * @param release  Release of the package.
+ * @param ref      Tag or branch that the deploy writes in the target.
+ * @return Resolved value, empty for a skipped target or the default message.
+ */
+async function resolveTemplate(template, release, ref) {
+    const value = 'function' === typeof template
+        ? await template({
+            package: toDeployPackage(release.package),
+            ...toRelease(release),
+            ref,
+            revision: release.revision,
+        })
+        : formatTemplate(template, release.package, release.version ?? '')
+            .replaceAll('{branch}', release.branch ?? '')
+            .replaceAll('{ref}', ref)
+            .replaceAll('{revision}', release.revision);
+    return value?.trim() ?? '';
+}
+function getFileSelection(pkg, config) {
+    const shared = config.files ?? {};
+    const files = pkg.group.files ?? {};
+    const setting = undefined === files.distignore ? shared.distignore : files.distignore;
+    const distignore = 'string' === typeof setting
+        ? path.join(pkg.directory, setting)
+        : setting;
+    const exclude = [...(shared.exclude ?? []), ...(files.exclude ?? [])];
+    return {
+        ...(undefined === distignore ? {} : { distignore }),
+        ...(exclude.length ? { exclude } : {}),
+    };
+}
+function toDeployPackage(pkg) {
+    return {
+        name: pkg.name,
+        directory: pkg.directory,
+        path: pkg.path,
+        type: pkg.type,
+    };
+}
+function toRelease(release) {
+    return {
+        ...(release.version ? { version: release.version } : {}),
+        ...(release.branch ? { branch: release.branch } : {}),
+    };
+}
+/**
+ * Group deploys by package, for a preview of what a ref deploys or a CI
+ * matrix with a job for each package.
+ *
+ * @param deploys Deploys from getGitDeploys() or getSvnDeploys().
+ * @return One item for each package, in the deploy order.
+ */
+export function getDeployPlan(deploys) {
+    const names = [
+        ...new Set(deploys.map((item) => item.package.name)),
+    ];
+    return names.map((name) => {
+        const items = deploys.filter((item) => item.package.name === name);
+        return {
+            package: name,
+            ...items[0]?.release,
+            targets: items.map((item) => ({
+                target: item.target,
+                ref: item.targetRef,
+                ...(item.targetHost
+                    ? { host: item.targetHost, path: item.targetPath }
+                    : {}),
+            })),
+        };
+    });
+}

package/dist/package-zip.d.ts

@@ -0,0 +1,52 @@
+import type { PackageType } from './checksums.ts';
+import type { FileSelection } from './file-selection.ts';
+export interface ZipPackageInput {
+    /** Directory to archive. */
+    sourceDir: string;
+    /** File selection from resolveFileSelection(). */
+    selection: FileSelection;
+    /** Archive path. */
+    zipPath: string;
+    /** Folder inside the archive, or null for the root. */
+    rootFolder: string | null;
+    /** Plugin or theme slug, for the checksums manifest. */
+    slug: string;
+    /** Version for the checksums manifest. */
+    version?: string | null;
+    /** Package type for the checksums manifest. */
+    type?: PackageType;
+    /** Also write the checksums manifest next to the archive. */
+    checksums?: boolean;
+    /** Overwrite existing output files. */
+    force?: boolean;
+}
+/** Result of zipPackage(). */
+export interface ZipPackageResult {
+    /** Absolute path of the ZIP. */
+    zipPath: string;
+    /** Absolute path of the checksums manifest, set with checksums. */
+    checksumsPath?: string;
+    /** Number of archived files. */
+    files: number;
+}
+/**
+ * Get the checksums manifest path next to an archive, with .checksums.json
+ * instead of .zip.
+ *
+ * @param zipPath Archive path.
+ * @return Manifest path.
+ */
+export declare function getChecksumsPath(zipPath: string): string;
+/**
+ * Write a ZIP of the selected files of a plugin, theme or package, and
+ * optionally the checksums manifest of the same files next to it. The zip
+ * command, with a directory or a configured package release, and the
+ * snapshot builds of a monorepo all use it, so that every ZIP of a package
+ * selects its files the same way. Output files inside the source directory,
+ * and their signatures, are never archived.
+ *
+ * @param  input Files, archive path and manifest options.
+ * @return Paths of the written files and the number of archived files.
+ * @throws {ValidationError} Without selected files, or when an output file exists without force.
+ */
+export declare function zipPackage(input: ZipPackageInput): Promise<ZipPackageResult>;

package/dist/package-zip.js

@@ -0,0 +1,78 @@
+import { existsSync } from 'node:fs';
+import { CHECKSUMS_EXTENSION, createChecksums, writeChecksums, } from "./checksums.js";
+import { ValidationError } from "./errors.js";
+import { ignoreOwnFile, ignoreOwnSignature, loadFileRules, selectFiles, } from "./file-selection.js";
+import { createZip } from "./zip.js";
+const ZIP_EXTENSION = '.zip';
+/**
+ * Get the checksums manifest path next to an archive, with .checksums.json
+ * instead of .zip.
+ *
+ * @param zipPath Archive path.
+ * @return Manifest path.
+ */
+export function getChecksumsPath(zipPath) {
+    const name = zipPath.endsWith(ZIP_EXTENSION)
+        ? zipPath.slice(0, -ZIP_EXTENSION.length)
+        : zipPath;
+    return name + CHECKSUMS_EXTENSION;
+}
+/**
+ * Fail before writing anything when an output file exists.
+ *
+ * @param  paths Output paths.
+ * @param  force Whether existing files are overwritten.
+ * @throws {ValidationError} If a file exists and force isn't set.
+ */
+function checkOverwrite(paths, force) {
+    const existing = paths.filter((path) => !force && existsSync(path));
+    if (existing.length) {
+        throw new ValidationError(`${existing.join(' and ')} already exists, pass --force to overwrite it.`);
+    }
+}
+/**
+ * Write a ZIP of the selected files of a plugin, theme or package, and
+ * optionally the checksums manifest of the same files next to it. The zip
+ * command, with a directory or a configured package release, and the
+ * snapshot builds of a monorepo all use it, so that every ZIP of a package
+ * selects its files the same way. Output files inside the source directory,
+ * and their signatures, are never archived.
+ *
+ * @param  input Files, archive path and manifest options.
+ * @return Paths of the written files and the number of archived files.
+ * @throws {ValidationError} Without selected files, or when an output file exists without force.
+ */
+export async function zipPackage(input) {
+    const { sourceDir, zipPath, force = false } = input;
+    const checksumsPath = input.checksums ? getChecksumsPath(zipPath) : null;
+    const outputs = [zipPath, checksumsPath].filter((path) => null !== path);
+    const rules = await loadFileRules(input.selection);
+    outputs.forEach((path) => ignoreOwnSignature(ignoreOwnFile(rules, sourceDir, path), sourceDir, path));
+    const files = await selectFiles(sourceDir, rules);
+    if (!files.length) {
+        throw new ValidationError(`No files to archive in ${sourceDir}.`);
+    }
+    checkOverwrite(outputs, force);
+    await createZip({
+        sourceDir,
+        files,
+        zipPath,
+        rootFolder: input.rootFolder,
+        force,
+    });
+    if (checksumsPath) {
+        const manifest = await createChecksums({
+            sourceDir,
+            rules,
+            slug: input.slug,
+            version: input.version ?? null,
+            type: input.type,
+        });
+        await writeChecksums(checksumsPath, manifest, force);
+    }
+    return {
+        zipPath,
+        ...(checksumsPath ? { checksumsPath } : {}),
+        files: files.length,
+    };
+}

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
@@ -64,11 +66,12 @@ export declare class ReleaseRepository {
      */
     createTag(tag: string): Promise<void>;
     /**
-     * Push a tag to the origin remote.
+     * Push a tag to a remote.
      *
-     * @param tag Tag name.
+     * @param tag    Tag name.
+     * @param remote Remote name.
      */
-    pushTag(tag: string): Promise<void>;
+    pushTag(tag: string, remote: string): Promise<void>;
     /**
      * Find the commit that added a file.
      *
@@ -85,13 +88,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

@@ -78,12 +78,13 @@ export class ReleaseRepository {
         await this.run(['tag', tag]);
     }
     /**
-     * Push a tag to the origin remote.
+     * Push a tag to a remote.
      *
-     * @param tag Tag name.
+     * @param tag    Tag name.
+     * @param remote Remote name.
      */
-    async pushTag(tag) {
-        await this.run(['push', 'origin', tag]);
+    async pushTag(tag, remote) {
+        await this.run(['push', remote, tag]);
     }
     /**
      * Find the commit that added a file.
@@ -115,25 +116,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;
 }