@wpelevator/wp-release 0.9.0 → 0.11.0

package/dist/changeset-files.d.ts

@@ -0,0 +1,41 @@
+import type { Changeset, ChangesetBump } from './changesets.ts';
+import type { FileJournal } from './file-journal.ts';
+import type { ReleaseRepository } from './release-repository.ts';
+/**
+ * Read the pending changesets of a directory, skipping its README.
+ *
+ * @param directory Changeset directory.
+ * @return Changesets sorted by file name, empty without the directory.
+ */
+export declare function readChangesets(directory: string): Promise<Changeset[]>;
+/**
+ * Pick the changesets that were added or changed since a ref.
+ *
+ * @param repository Repository of the changesets.
+ * @param directory  Changeset directory.
+ * @param changesets Pending changesets.
+ * @param since      Base ref, like origin/main.
+ * @return Changesets of the diff.
+ */
+export declare function readChangesetsSince(repository: ReleaseRepository, directory: string, changesets: Changeset[], since: string): Promise<Changeset[]>;
+/**
+ * Create a Changesets-compatible Markdown file.
+ *
+ * @param  directory Changeset directory, created when missing.
+ * @param  packages  Bump of each package.
+ * @param  summary   Changelog summary.
+ * @param  name      File name without the extension, random by default.
+ * @return Created file path.
+ * @throws {ValidationError} If the file already exists.
+ */
+export declare function writeChangeset(directory: string, packages: Record<string, ChangesetBump>, summary: string, name?: string): Promise<string>;
+/**
+ * Remove an applied changeset, or only the applied packages from a changeset
+ * that names other packages too, so that their releases keep its summary.
+ *
+ * @param file      Changeset file.
+ * @param changeset Parsed changeset.
+ * @param applied   Versioned packages, or undefined when all were versioned.
+ * @param journal   File journal for rolling back.
+ */
+export declare function consumeChangeset(file: string, changeset: Changeset, applied: string[] | undefined, journal: FileJournal): Promise<void>;

package/dist/changeset-files.js

@@ -0,0 +1,100 @@
+import { randomUUID } from 'node:crypto';
+import { access, mkdir, readdir, readFile, rm, writeFile, } from 'node:fs/promises';
+import path from 'node:path';
+import { formatChangeset, parseChangeset } from "./changesets.js";
+import { ValidationError } from "./errors.js";
+/**
+ * Read the pending changesets of a directory, skipping its README.
+ *
+ * @param directory Changeset directory.
+ * @return Changesets sorted by file name, empty without the directory.
+ */
+export async function readChangesets(directory) {
+    let entries;
+    try {
+        entries = await readdir(directory);
+    }
+    catch (error) {
+        if ('ENOENT' === error.code) {
+            return [];
+        }
+        throw error;
+    }
+    return Promise.all(entries
+        .filter((name) => name.endsWith('.md') && !name.startsWith('README'))
+        .sort()
+        .map(async (name) => parseChangeset(await readFile(path.join(directory, name), 'utf8'), name)));
+}
+/**
+ * Pick the changesets that were added or changed since a ref.
+ *
+ * @param repository Repository of the changesets.
+ * @param directory  Changeset directory.
+ * @param changesets Pending changesets.
+ * @param since      Base ref, like origin/main.
+ * @return Changesets of the diff.
+ */
+export async function readChangesetsSince(repository, directory, changesets, since) {
+    const relativeDirectory = repository.relativePath(directory);
+    const changedFiles = new Set(await repository.getChangedFiles(since, {
+        directory,
+        diffFilter: 'ACMR',
+    }));
+    return changesets.filter((changeset) => changedFiles.has(path.posix.join(relativeDirectory, changeset.fileName)));
+}
+/**
+ * Create a Changesets-compatible Markdown file.
+ *
+ * @param  directory Changeset directory, created when missing.
+ * @param  packages  Bump of each package.
+ * @param  summary   Changelog summary.
+ * @param  name      File name without the extension, random by default.
+ * @return Created file path.
+ * @throws {ValidationError} If the file already exists.
+ */
+export async function writeChangeset(directory, packages, summary, name) {
+    await mkdir(directory, { recursive: true });
+    const fileName = `${name ?? randomUUID().slice(0, 8)}.md`;
+    const file = path.join(directory, fileName);
+    let exists = false;
+    try {
+        await access(file);
+        exists = true;
+    }
+    catch (error) {
+        if ('ENOENT' !== error.code) {
+            throw error;
+        }
+    }
+    if (exists) {
+        throw new ValidationError(`Changeset ${fileName} already exists.`);
+    }
+    const entries = Object.entries(packages)
+        .sort((a, b) => a[0].localeCompare(b[0]))
+        .map(([pkg, bump]) => `${JSON.stringify(pkg)}: ${bump}`)
+        .join('\n');
+    await writeFile(file, `---\n${entries}\n---\n\n${summary.trim()}\n`);
+    return file;
+}
+/**
+ * Remove an applied changeset, or only the applied packages from a changeset
+ * that names other packages too, so that their releases keep its summary.
+ *
+ * @param file      Changeset file.
+ * @param changeset Parsed changeset.
+ * @param applied   Versioned packages, or undefined when all were versioned.
+ * @param journal   File journal for rolling back.
+ */
+export async function consumeChangeset(file, changeset, applied, journal) {
+    const remaining = Object.entries(changeset.packages).filter(([name]) => undefined !== applied && !applied.includes(name));
+    await journal.remember(file);
+    if (remaining.length) {
+        await writeFile(file, formatChangeset({
+            packages: Object.fromEntries(remaining),
+            summary: changeset.summary,
+        }));
+    }
+    else {
+        await rm(file);
+    }
+}

package/dist/changeset-packages.d.ts

@@ -0,0 +1,59 @@
+import type { ChangesetConfig, ChangesetPackageGroup } from './changeset-config.ts';
+import type { ChangesetPackage } from './changesets.ts';
+import type { ReleaseRepository } from './release-repository.ts';
+/**
+ * A discovered package with the configuration of its package group.
+ */
+export interface ConfiguredPackage extends ChangesetPackage {
+    group: ChangesetPackageGroup;
+    versionConfig: ChangesetPackageGroup['version'];
+}
+export interface ChangedPackages {
+    /** Packages with changed files, in the configured order. */
+    packages: ConfiguredPackage[];
+    /** Changed files relative to the repository root, by package name. */
+    filesByPackage: Record<string, string[]>;
+}
+/**
+ * Find the packages of the configured package groups, with their current
+ * versions.
+ *
+ * @param  repository Repository the packages are in.
+ * @param  config     Repository release configuration.
+ * @return Packages in the configured order.
+ * @throws {ValidationError} For a glob without matches or a duplicate package name.
+ */
+export declare function discoverPackages(repository: ReleaseRepository, config: ChangesetConfig): Promise<ConfiguredPackage[]>;
+/**
+ * Fail for package names that aren't configured.
+ *
+ * @param  packages Discovered packages.
+ * @param  names    Package names to check.
+ * @throws {ValidationError} For the first unknown package.
+ */
+export declare function assertKnownPackages(packages: ChangesetPackage[], names: string[]): void;
+/**
+ * Find the packages with files changed between the merge base of a ref and
+ * HEAD.
+ *
+ * @param repository Repository the packages are in.
+ * @param packages   Discovered packages.
+ * @param since      Base ref, like origin/main.
+ * @return Changed packages and their changed files.
+ */
+export declare function getChangedPackages(repository: ReleaseRepository, packages: ConfiguredPackage[], since: string): Promise<ChangedPackages>;
+/**
+ * Remove the release configuration from a package passed to config callbacks.
+ *
+ * @param pkg Configured package.
+ * @return Package without its group configuration.
+ */
+export declare function toChangesetPackage(pkg: ConfiguredPackage): ChangesetPackage;
+/**
+ * Convert a package glob to a regular expression, where * and ? match within
+ * a path segment and ** matches any number of segments.
+ *
+ * @param glob Glob relative to the package root, like `plugins/*`.
+ * @return Anchored regular expression.
+ */
+export declare function globRegExp(glob: string): RegExp;

package/dist/changeset-packages.js

@@ -0,0 +1,186 @@
+import { readdir } from 'node:fs/promises';
+import path from 'node:path';
+import { ValidationError } from "./errors.js";
+import { readJson } from "./json-files.js";
+import { readVersion } from "./version-files.js";
+/** Directories that never contain configured packages. */
+const SKIPPED_DIRECTORIES = ['.git', 'node_modules', 'vendor', 'dist'];
+/**
+ * Find the packages of the configured package groups, with their current
+ * versions.
+ *
+ * @param  repository Repository the packages are in.
+ * @param  config     Repository release configuration.
+ * @return Packages in the configured order.
+ * @throws {ValidationError} For a glob without matches or a duplicate package name.
+ */
+export async function discoverPackages(repository, config) {
+    const root = path.resolve(repository.cwd, config.root ?? '.');
+    const packages = [];
+    const hasRecursiveGlob = config.packages.some((item) => item.glob.split('/').includes('**'));
+    const directories = await findDirectories(root, '', hasRecursiveGlob
+        ? Infinity
+        : Math.max(1, ...config.packages.map((item) => item.glob.split('/').length + 2)));
+    for (const group of config.packages) {
+        const matcher = globRegExp(group.glob);
+        const candidates = matcher.test('.')
+            ? ['.', ...directories]
+            : directories;
+        const matches = candidates
+            .filter((item) => matcher.test(item) &&
+            !(group.exclude ?? []).some((excluded) => globRegExp(excluded).test(item)))
+            .sort();
+        if (!matches.length) {
+            throw new ValidationError(`Package glob "${group.glob}" did not match any directories under ${root}.`);
+        }
+        for (const relativePath of matches) {
+            const directory = path.join(root, relativePath);
+            const name = await packageName(directory, relativePath, group.idFrom ?? 'path');
+            const currentVersion = await readVersion(repository, directory, group.version.from, relativePath, group.tagType);
+            if (packages.some((pkg) => pkg.name === name)) {
+                throw new ValidationError(`Package identifier "${name}" is configured more than once.`);
+            }
+            packages.push({
+                name,
+                directory,
+                path: relativePath,
+                type: packageType(group),
+                currentVersion,
+                group,
+                versionConfig: group.version,
+            });
+        }
+    }
+    return packages;
+}
+/**
+ * Fail for package names that aren't configured.
+ *
+ * @param  packages Discovered packages.
+ * @param  names    Package names to check.
+ * @throws {ValidationError} For the first unknown package.
+ */
+export function assertKnownPackages(packages, names) {
+    names.forEach((name) => {
+        if (!packages.some((pkg) => pkg.name === name)) {
+            throw new ValidationError(`Unknown package "${name}".`);
+        }
+    });
+}
+/**
+ * Find the packages with files changed between the merge base of a ref and
+ * HEAD.
+ *
+ * @param repository Repository the packages are in.
+ * @param packages   Discovered packages.
+ * @param since      Base ref, like origin/main.
+ * @return Changed packages and their changed files.
+ */
+export async function getChangedPackages(repository, packages, since) {
+    const changedFiles = await repository.getChangedFiles(since);
+    const filesByPackage = {};
+    const changed = packages.filter((pkg) => {
+        const packageFromRepo = repository.relativePath(pkg.directory);
+        // Every file belongs to a package at the repository root.
+        const matchingFiles = '' === packageFromRepo
+            ? changedFiles
+            : changedFiles.filter((file) => file === packageFromRepo ||
+                file.startsWith(`${packageFromRepo}/`));
+        if (matchingFiles.length) {
+            filesByPackage[pkg.name] = matchingFiles;
+        }
+        return matchingFiles.length > 0;
+    });
+    return { packages: changed, filesByPackage };
+}
+/**
+ * Remove the release configuration from a package passed to config callbacks.
+ *
+ * @param pkg Configured package.
+ * @return Package without its group configuration.
+ */
+export function toChangesetPackage(pkg) {
+    return {
+        name: pkg.name,
+        directory: pkg.directory,
+        path: pkg.path,
+        type: pkg.type,
+        currentVersion: pkg.currentVersion,
+    };
+}
+/**
+ * Convert a package glob to a regular expression, where * and ? match within
+ * a path segment and ** matches any number of segments.
+ *
+ * @param glob Glob relative to the package root, like `plugins/*`.
+ * @return Anchored regular expression.
+ */
+export function globRegExp(glob) {
+    const escaped = glob
+        .split('/')
+        .map((part) => {
+        if ('**' === part) {
+            return '.*';
+        }
+        return part
+            .replaceAll(/[.+^${}()|[\]\\]/g, '\\$&')
+            .replaceAll('*', '[^/]*')
+            .replaceAll('?', '[^/]');
+    })
+        .join('/');
+    return new RegExp(`^${escaped}$`);
+}
+async function findDirectories(root, prefix = '', maxDepth = 5) {
+    let entries;
+    try {
+        entries = await readdir(path.join(root, prefix), {
+            withFileTypes: true,
+        });
+    }
+    catch (error) {
+        if ('ENOENT' === error.code) {
+            return [];
+        }
+        throw error;
+    }
+    const directories = entries.filter((item) => item.isDirectory() && !SKIPPED_DIRECTORIES.includes(item.name));
+    if (prefix.split(path.sep).filter(Boolean).length >= maxDepth) {
+        return directories.map((item) => path.join(prefix, item.name));
+    }
+    const children = await Promise.all(directories.map((item) => findDirectories(root, path.join(prefix, item.name), maxDepth)));
+    return [
+        ...directories.map((item) => path.join(prefix, item.name)),
+        ...children.flat(),
+    ];
+}
+async function packageName(directory, relativePath, idFrom) {
+    if ('path' === idFrom) {
+        if ('.' === relativePath) {
+            return path.basename(directory);
+        }
+        return relativePath.split(path.sep).join('/');
+    }
+    const [file, field] = idFrom.split('#');
+    if (!file || !field) {
+        throw new ValidationError(`Invalid package identifier source "${idFrom}".`);
+    }
+    const manifest = await readJson(path.join(directory, file));
+    const name = manifest[field];
+    if ('string' !== typeof name || !name.trim()) {
+        throw new ValidationError(`Expected ${file}#${field} in ${directory}.`);
+    }
+    return name;
+}
+function packageType(group) {
+    const kind = group.version.from.kind;
+    if ('wordpress-plugin-header' === kind) {
+        return 'plugin';
+    }
+    if ('wordpress-theme-header' === kind) {
+        return 'theme';
+    }
+    if ('package-json' === kind) {
+        return 'npm';
+    }
+    return 'other';
+}

package/dist/changeset-release.d.ts

@@ -1,14 +1,31 @@
-import type { Changeset, ChangesetPackage, ChangesetReleasePlan, PackageRelease, VersionedRelease } from './changesets.ts';
+import type { Changeset, ChangesetBump, ChangesetPackage, ChangesetReleasePlan, PackageRelease, VersionedRelease } from './changesets.ts';
+import type { GitRunner } from './git.ts';
+import { ReleaseRepository } from './release-repository.ts';
 export interface ChangesetRepository {
     cwd: string;
     configFile?: string;
 }
-export interface ChangesetVersionInput extends ChangesetRepository {
+export interface ChangesetReleaseOptions extends ChangesetRepository {
+    /** Git runner, spawning git by default. */
+    git?: GitRunner;
+}
+export interface ChangesetAddOptions {
+    /** Bump of each package. */
+    packages: Record<string, ChangesetBump>;
+    /** Changelog summary. */
+    summary: string;
+    /** File name without the extension, random by default. */
+    name?: string;
+}
+export interface ChangesetVersionOptions {
     dryRun?: boolean;
     date?: string;
     /** Version only these packages, leaving the other changesets pending. */
     packages?: string[];
+    /** Whether the selected sources release their configured dependents; defaults to true. */
+    dependents?: boolean;
 }
+export type ChangesetVersionInput = ChangesetRepository & ChangesetVersionOptions;
 /** Versioned releases, the applied changesets and whether files were changed. */
 export interface VersionChangesetsResult {
     changesets: Changeset[];
@@ -16,22 +33,24 @@ export interface VersionChangesetsResult {
     date: string;
     changed: boolean;
 }
-export interface ChangesetTagInput extends ChangesetRepository {
+export interface ChangesetTagOptions {
     dryRun?: boolean;
     untagged?: boolean;
     push?: boolean;
-    githubRelease?: boolean;
     since?: string;
     /** Tag only these packages. */
     packages?: string[];
     /** Expected version of the single package in `packages`. */
     version?: string;
 }
+export type ChangesetTagInput = ChangesetRepository & ChangesetTagOptions;
 export interface ChangesetTagResult {
     tags: Array<{
         package: string;
         version: string;
         tag: string;
+        /** Release title, like `plugins/alpha@1.2.0`. */
+        title: string;
         previousTag?: string;
         prerelease: boolean;
         exists: boolean;
@@ -39,6 +58,136 @@ export interface ChangesetTagResult {
         notes: string;
     }>;
 }
+export interface ChangesetStatusOptions {
+    /** Base ref to diff against, origin/<baseBranch> by default. */
+    since?: string;
+}
+export interface ChangesetStatusResult {
+    changesets: Changeset[];
+    releases: PackageRelease[];
+    changedPackages: string[];
+    changedPackageFiles: Record<string, string[]>;
+    missingChangesets: string[];
+    warnings: string[];
+}
+/**
+ * Changeset releases of a repository: recording changesets, versioning the
+ * packages they name and tagging the releases.
+ *
+ * Each operation loads the configuration, discovers the packages and reads the
+ * pending changesets again, so that one instance can version and then tag.
+ * Git runs through the injected runner.
+ */
+export declare class ChangesetRelease {
+    readonly cwd: string;
+    readonly configFile: string | undefined;
+    readonly repository: ReleaseRepository;
+    /**
+     * @param options Repository root, config file and git runner.
+     */
+    constructor(options: ChangesetReleaseOptions);
+    /**
+     * Discover configured packages, pending changesets, and their proposed
+     * versions.
+     *
+     * @return A release plan; `undefined` when no config is present.
+     */
+    getPlan(): Promise<ChangesetReleasePlan | undefined>;
+    /**
+     * Discover the packages of the repository configuration.
+     *
+     * @return Packages in the configured order with their current versions.
+     * @throws {ValidationError} Without a config, or for an invalid one.
+     */
+    getPackages(): Promise<ChangesetPackage[]>;
+    /**
+     * Create a Changesets-compatible Markdown file.
+     *
+     * @param  options Packages, summary and file name.
+     * @return Created file path.
+     * @throws {ValidationError} For unknown packages or an existing file.
+     */
+    add(options: ChangesetAddOptions): Promise<string>;
+    /**
+     * Apply pending package versions and changelogs. A failed run restores
+     * every file it changed.
+     *
+     * @param  options Versioning options.
+     * @return Planned releases and whether files were changed.
+     * @throws {ValidationError} Without a config, or for an invalid plan.
+     */
+    version(options?: ChangesetVersionOptions): Promise<VersionChangesetsResult>;
+    /**
+     * Create missing release tags, optionally pushing them to the origin
+     * remote. Each tag comes with the title and notes of its release, for a
+     * workflow step to create the GitHub Release.
+     *
+     * @param  options Tag options.
+     * @return Per-package tags and release notes.
+     * @throws {ValidationError} For conflicting options, unknown packages or version mismatches.
+     */
+    tag(options?: ChangesetTagOptions): Promise<ChangesetTagResult>;
+    /**
+     * Check whether changed files belong to packages without a changeset.
+     *
+     * @param  options Base git ref.
+     * @return Changed packages and missing changeset identifiers.
+     * @throws {ValidationError} Without a config.
+     */
+    getStatus(options?: ChangesetStatusOptions): Promise<ChangesetStatusResult>;
+    /**
+     * Write the versions, dependency specs and changelogs of the releases and
+     * consume the applied changesets, restoring every changed file when a
+     * step fails.
+     *
+     * @param context  Release context.
+     * @param plan     Selected release plan.
+     * @param releases Releases with their changelog entries.
+     * @param date     Release date, as YYYY-MM-DD.
+     * @param applied  Versioned packages, or undefined when all were versioned.
+     */
+    private writeReleases;
+    /**
+     * Write the version, the dependency specs of bundled sources and the
+     * changelog of a release.
+     *
+     * @param context Release context.
+     * @param plan    Selected release plan.
+     * @param release Release with its changelog entries.
+     * @param date    Release date, as YYYY-MM-DD.
+     * @param journal File journal for rolling back.
+     */
+    private writeRelease;
+    /**
+     * Load the configuration, discover the packages and plan the releases of
+     * the pending changesets, including the releases of their dependents.
+     *
+     * @return Release context, undefined without a config.
+     * @throws {ValidationError} For an invalid config, plan or changeset.
+     */
+    private loadContext;
+    /**
+     * Load the release context of a repository that has to be configured.
+     *
+     * @return Release context.
+     * @throws {ValidationError} Without a config.
+     */
+    private requireContext;
+    /**
+     * Load the configuration of a repository that has to be configured.
+     *
+     * @return Repository release configuration.
+     * @throws {ValidationError} Without a config.
+     */
+    private requireConfig;
+    /**
+     * Get the directory of the changeset files.
+     *
+     * @param config Repository release configuration.
+     * @return Absolute directory path.
+     */
+    private getChangesetDirectory;
+}
 /**
  * Discover configured packages, pending changesets, and their proposed versions.
  *
@@ -60,11 +209,7 @@ export declare function getChangesetPackages(input: ChangesetRepository): Promis
  * @param input Repository, packages and summary.
  * @return Created file path.
  */
-export declare function addChangeset(input: ChangesetRepository & {
-    packages: Record<string, 'patch' | 'minor' | 'major'>;
-    summary: string;
-    name?: string;
-}): Promise<string>;
+export declare function addChangeset(input: ChangesetRepository & ChangesetAddOptions): Promise<string>;
 /**
  * Apply pending package versions and changelogs.
  *
@@ -85,12 +230,4 @@ export declare function tagChangesets(input: ChangesetTagInput): Promise<Changes
  * @param input Repository and base git ref.
  * @return Changed packages and missing changeset identifiers.
  */
-export declare function getChangesetStatus(input: ChangesetRepository & {
-    since?: string;
-}): Promise<{
-    changesets: Changeset[];
-    releases: PackageRelease[];
-    changedPackages: string[];
-    changedPackageFiles: Record<string, string[]>;
-    missingChangesets: string[];
-}>;
+export declare function getChangesetStatus(input: ChangesetRepository & ChangesetStatusOptions): Promise<ChangesetStatusResult>;