@wpelevator/wp-release 0.6.1 → 0.8.0

package/dist/commands/changeset-version.d.ts

@@ -6,6 +6,8 @@ export interface ChangesetVersionResult {
         bump: string;
         currentVersion: string;
         nextVersion: string;
+        /** Changelog entries of the release as a Markdown list. */
+        changelog: string;
     }>;
 }
 declare const _default: {
@@ -20,6 +22,10 @@ declare const _default: {
         readonly date: {
             readonly type: "string";
         };
+        readonly package: {
+            readonly type: "string";
+            readonly multiple: true;
+        };
     };
     run({ values, cwd, configFile, logger }: import("./command.ts").CommandContext): Promise<{
         exitCode: number;
@@ -31,6 +37,7 @@ declare const _default: {
                 bump: "patch" | "minor" | "major";
                 currentVersion: string;
                 nextVersion: string;
+                changelog: string;
             }[];
         };
     }>;

package/dist/commands/changeset-version.js

@@ -1,15 +1,19 @@
 import { versionChangesets } from "../changeset-release.js";
+import { getChangesetVersionSummary } from "../summary.js";
 import { parseChangesetVersionArgs, changesetVersionArgs, } from "./changeset-args.js";
 export default {
     name: 'changeset-version',
-    usage: 'changeset-version [--dry-run] [--date <YYYY-MM-DD>]',
+    usage: 'changeset-version [--dry-run] [--date <YYYY-MM-DD>] [--package <name>]',
     summary: 'Apply pending version bumps and changelog entries.',
     help: `Options:
   --dry-run              Print the release plan without writing files
   --date <YYYY-MM-DD>    Changelog date (default: today)
+  --package <name>       Version only this package (repeatable)
 
 Updates configured version files, prepends changelog entries and removes the
-applied changeset files.`,
+applied changeset files. With --package, a changeset that also names other
+packages keeps only their entries, so it still applies to their releases, and
+changesets without packages are left for a run without --package.`,
     options: changesetVersionArgs,
     async run({ values, cwd, configFile, logger }) {
         const args = parseChangesetVersionArgs(values);
@@ -22,6 +26,7 @@ applied changeset files.`,
         if (!result.releases.length) {
             logger.info('No pending package releases.');
         }
+        logger.summary(() => getChangesetVersionSummary(result.releases, args.dryRun));
         return {
             exitCode: 0,
             result: {
@@ -32,6 +37,7 @@ applied changeset files.`,
                     bump: item.bump,
                     currentVersion: item.currentVersion,
                     nextVersion: item.nextVersion,
+                    changelog: item.changelog,
                 })),
             },
         };

package/dist/commands/deploy-git.d.ts

@@ -0,0 +1,45 @@
+import type { GitDeployInput } from '../git-deploy.ts';
+import type { ParsedValues } from './command.ts';
+/**
+ * Map the parsed "deploy-git" arguments to resolveGitDeployOptions() input.
+ *
+ * @param values      Parsed CLI values.
+ * @param positionals Positional arguments.
+ * @param cwd         Working directory.
+ * @return Git deploy input.
+ */
+export declare function getGitDeployInputFromArgs(values: ParsedValues, positionals: string[], cwd: string): GitDeployInput;
+declare const _default: {
+    name: string;
+    usage: string;
+    summary: string;
+    help: string;
+    options: {
+        message: {
+            type: "string";
+        };
+        'dry-run': {
+            type: "boolean";
+        };
+        'git-url': {
+            type: "string";
+        };
+        branch: {
+            type: "string";
+        };
+        tag: {
+            type: "string";
+        };
+        'split-prefix': {
+            type: "string";
+        };
+        'source-ref': {
+            type: "string";
+        };
+    };
+    run({ values, positionals, cwd, logger }: import("./command.ts").CommandContext): Promise<{
+        exitCode: number;
+        result: import("../git-deploy.ts").GitDeployResult;
+    }>;
+};
+export default _default;

package/dist/commands/deploy-git.js

@@ -0,0 +1,81 @@
+import { GitDeploy, resolveGitDeployOptions } from "../git-deploy.js";
+import { fileSelectionArgs, getFileSelectionInput, getSourceDirArg, sourceDirArgs, } from "./args.js";
+import { getBoolean, getString } from "./command.js";
+/**
+ * Map the parsed "deploy-git" arguments to resolveGitDeployOptions() input.
+ *
+ * @param values      Parsed CLI values.
+ * @param positionals Positional arguments.
+ * @param cwd         Working directory.
+ * @return Git deploy input.
+ */
+export function getGitDeployInputFromArgs(values, positionals, cwd) {
+    return {
+        cwd,
+        sourceDir: getSourceDirArg(values, positionals),
+        gitUrl: getString(values, 'git-url'),
+        branch: getString(values, 'branch'),
+        tag: getString(values, 'tag'),
+        splitPrefix: getString(values, 'split-prefix'),
+        sourceRef: getString(values, 'source-ref'),
+        ...getFileSelectionInput(values),
+        message: getString(values, 'message'),
+        dryRun: getBoolean(values, 'dry-run'),
+    };
+}
+export default {
+    name: 'deploy-git',
+    usage: 'deploy-git [<source-dir>] --git-url <url> [options]',
+    summary: 'Deploy the files of a plugin, theme or package to a Git repository as a release commit.',
+    help: `Arguments:
+  <source-dir>            Directory with the files to release (default: .),
+                          also accepted as --source-dir <dir>
+
+Writes (none by default):
+  --branch <name>         Push the release to this branch, on top of its
+                          previous release
+  --tag <name>            Create this tag for the release, on top of --branch
+                          or the default branch of the repository
+
+Options:
+  --git-url <url>         Repository to deploy to
+  --split-prefix <dir>    Use the history of this directory of the source
+                          repository, from git subtree split, as the source
+                          history (default: the source commit)
+  --source-ref <ref>      Source commit (default: HEAD)
+  --distignore <file>     Ignore file (default: <source-dir>/.distignore when present)
+  --no-distignore         Don't read any ignore file
+  --exclude <patterns>    Extra gitignore-style patterns, comma-separated or repeated
+  --message <text>        Release commit message
+  --dry-run               Run everything except the push
+
+Each release is a commit with exactly the selected files, whose parents are
+the previous release and the source history. Pushes are never forced: the
+branch only moves forward, a release without changes isn't pushed again, an
+older build doesn't move a branch that has newer source history, a tag that
+already has the same files is reused, and a tag with other files
+fails with exit code 2 (delete it in the repository to release it again). The source directory must be inside a Git repository.
+Credentials come from git, like a token in the URL or an SSH key.
+
+Examples:
+  wp-release deploy-git build --git-url git@github.com:me/my-plugin-dist.git --branch main --tag 1.2.0
+      Release a build to a distribution repository and tag it
+  wp-release deploy-git packages/my-plugin --split-prefix packages/my-plugin --git-url … --branch main
+      Release a monorepo package with its own history`,
+    options: {
+        ...sourceDirArgs,
+        'git-url': { type: 'string' },
+        branch: { type: 'string' },
+        tag: { type: 'string' },
+        'split-prefix': { type: 'string' },
+        'source-ref': { type: 'string' },
+        ...fileSelectionArgs,
+        message: { type: 'string' },
+        'dry-run': { type: 'boolean' },
+    },
+    async run({ values, positionals, cwd, logger }) {
+        const options = resolveGitDeployOptions(getGitDeployInputFromArgs(values, positionals, cwd));
+        const result = await new GitDeploy(options, logger).run();
+        return { exitCode: 0, result };
+    },
+};

package/dist/git-deploy.d.ts

@@ -0,0 +1,218 @@
+import type { FileSelection } from './file-selection.ts';
+import type { GitRunner } from './git.ts';
+import { Logger } from './logger.ts';
+/**
+ * Git deploy options from the CLI or a library caller. Unset options fall
+ * back to the defaults in resolveGitDeployOptions().
+ */
+export interface GitDeployInput {
+    /** Directory that relative paths resolve against. */
+    cwd?: string;
+    /** Directory with the files to release, defaults to cwd. */
+    sourceDir?: string;
+    /** URL of the repository to release to. */
+    gitUrl?: string;
+    /** Branch to push the release to. */
+    branch?: string;
+    /** Tag to create for the release. */
+    tag?: string;
+    /** Use the history of this directory, relative to the source repository root, from git subtree split as the source history. */
+    splitPrefix?: string;
+    /** Source commit, defaults to HEAD. */
+    sourceRef?: string;
+    /** Ignore file path, or false to not read one. */
+    distignore?: string | false;
+    /** Extra gitignore-style patterns. */
+    exclude?: string | string[];
+    /** Commit message of the release. */
+    message?: string;
+    /** Run everything except the push. */
+    dryRun?: boolean;
+}
+/**
+ * Git deploy options with the defaults applied, from resolveGitDeployOptions().
+ */
+export interface GitDeployOptions extends FileSelection {
+    cwd: string;
+    sourceDir: string;
+    gitUrl: string;
+    branch: string | null;
+    tag: string | null;
+    splitPrefix: string | null;
+    sourceRef: string;
+    message: string | null;
+    dryRun: boolean;
+}
+export interface GitDeployResult {
+    /** Release commit, null when nothing was deployed. */
+    revision: string | null;
+    /** Previous release that the release builds on, null for the first one. */
+    previous: string | null;
+    /** Whether a new release commit was created, false when the files didn't change. */
+    created: boolean;
+    /** Whether the branch already has a release of newer source history, so it isn't moved. */
+    outdated: boolean;
+    /** Refs to write: the branch when the release changed it, and the tag when it doesn't point to the release yet. */
+    planned: string[];
+    /** Refs that were pushed, empty in a dry run. */
+    pushed: string[];
+    /** Number of released files. */
+    files: number;
+}
+/**
+ * Check a branch or tag name for the common mistakes before it's used in a
+ * refspec. It intentionally covers only the main rules of git
+ * check-ref-format, since git rejects any other invalid name when it pushes.
+ *
+ * @param name Branch or tag name.
+ * @return Whether the name can be used.
+ */
+export declare function isValidRefName(name: string): boolean;
+/**
+ * Apply the defaults to the Git deploy options and validate them.
+ *
+ * @param  input Git deploy input.
+ * @return Git deploy options.
+ * @throws {ValidationError} For a missing URL or an invalid branch or tag.
+ */
+export declare function resolveGitDeployOptions(input?: GitDeployInput): GitDeployOptions;
+/**
+ * Deploy the files of a plugin, theme or package to a Git repository, as a
+ * release commit with exactly the selected files. Its parents are the
+ * previous release in the repository and the source commit, or with
+ * splitPrefix the history of that directory from git subtree split, so the
+ * repository keeps the source history and `git log --first-parent` lists the
+ * releases. Pushes are never forced: a branch only moves forward, a release
+ * without changes isn't pushed again, and an existing tag is never replaced.
+ *
+ * Each step is a separate method so that wrappers can run and report them
+ * one by one; run() does all of them.
+ */
+export declare class GitDeploy {
+    readonly options: GitDeployOptions;
+    readonly logger: Logger;
+    readonly runner: GitRunner;
+    private repoRoot;
+    /**
+     * @param options Options from resolveGitDeployOptions().
+     * @param logger  Logger for the progress.
+     * @param runner  Git command runner, replaceable in tests.
+     */
+    constructor(options: GitDeployOptions, logger?: Logger, runner?: GitRunner);
+    /**
+     * Whether the options ask for any push.
+     *
+     * @return True with a branch or a tag.
+     */
+    hasWrites(): boolean;
+    /**
+     * Create the release commit and push it.
+     *
+     * @return Release, previous release and the pushed refs.
+     */
+    run(): Promise<GitDeployResult>;
+    /**
+     * Write the selected files to the object database of the source
+     * repository and create a tree of them, with a temporary index so that
+     * the working tree and the index of the repository are left alone.
+     *
+     * @return Tree hash and the number of files.
+     * @throws {ValidationError} When no files are selected, or a file name has a line break.
+     */
+    createTree(): Promise<{
+        tree: string;
+        files: number;
+    }>;
+    /**
+     * Fetch the previous release: the branch, or for a tag-only deploy the
+     * default branch of the repository.
+     *
+     * @return Commit hash, or null when the repository has no such branch yet.
+     */
+    fetchPrevious(): Promise<string | null>;
+    /**
+     * Fetch a ref of the repository.
+     *
+     * @param ref Branch or tag ref, or HEAD.
+     * @return Commit hash, with a tag peeled to its commit.
+     */
+    fetchCommit(ref: string): Promise<string>;
+    /**
+     * Get the release commit. When the files are the same as in the previous
+     * release, that release is reused. When the previous release on the
+     * branch already has newer source history, like when an older build runs
+     * again, the branch isn't moved: only a tag gets a new release commit.
+     *
+     * @param tree     Tree of the released files.
+     * @param previous Previous release, or null for the first one.
+     * @return Release commit, whether it was created and whether the source is outdated.
+     */
+    createRelease(tree: string, previous: string | null): Promise<{
+        revision: string;
+        created: boolean;
+        outdated: boolean;
+    }>;
+    /**
+     * Check whether a release was made from newer source history: the source
+     * history of the release, its last parent, already has the source as an
+     * older commit. The same source, a newer one, including a revert, and
+     * unrelated history aren't outdated. With splitPrefix, git subtree split
+     * creates the same commits for the same history, so the split of an older
+     * build is part of the split of a newer one.
+     *
+     * @param source   Source history from getSourceHistory().
+     * @param previous Previous release.
+     * @return Whether the source is older than the source of the release.
+     */
+    isOutdated(source: string, previous: string): Promise<boolean>;
+    /**
+     * Get the source history parent of a release: the source commit, or the
+     * history of splitPrefix from git subtree split.
+     *
+     * @return Commit hash.
+     */
+    getSourceHistory(): Promise<string>;
+    /**
+     * Check the tag in the repository before anything is pushed. Tags are
+     * never replaced, so a tag with other files is an error. A tag with the
+     * same files is the release, which makes running a tag release again a
+     * no-op, also when the release commit was created on top of an older
+     * branch tip. To release a tag again, delete it in the repository first.
+     *
+     * @param  tree Tree of the released files.
+     * @return Tagged commit when the tag has the same files, null without the tag.
+     * @throws {ValidationError} When the tag has other files.
+     */
+    checkTag(tree: string): Promise<string | null>;
+    /**
+     * Get the refs to push: the branch, when the release moves it and the
+     * source isn't outdated, and the tag, unless it already exists with these
+     * files.
+     *
+     * @param revision Release commit.
+     * @param previous Previous release.
+     * @param tagged   Commit of an existing tag with the same files, from checkTag().
+     * @param outdated Whether the branch has newer source history, from createRelease().
+     * @return Refs like refs/heads/main and refs/tags/1.2.0.
+     */
+    getRefsToPush(revision: string, previous: string | null, tagged?: string | null, outdated?: boolean): string[];
+    /**
+     * Push the release to the refs in one atomic push, never forced, so the
+     * branch only moves forward and a tag that was created in the meantime
+     * is never replaced. A dry run checks the push without writing.
+     *
+     * @param revision Release commit.
+     * @param refs     Refs from getRefsToPush().
+     * @return Pushed refs, empty in a dry run or without refs.
+     */
+    push(revision: string, refs: string[]): Promise<string[]>;
+    private getDefaultMessage;
+    private getRepoRoot;
+    /**
+     * Run git in the source repository.
+     *
+     * @param input Command input without the working directory.
+     * @return Trimmed standard output.
+     */
+    private git;
+}