@wpelevator/wp-release 0.7.0 → 0.8.0

package/README.md

@@ -131,6 +131,16 @@ Add release notes in a feature PR with `npx wp-release changeset-add --package @
 
 On the release branch, preview with `changeset-version --dry-run`, then run `changeset-version` to update version targets and changelogs. By default, new Markdown entries go before the first version heading; `changelogInsertAfter` sets a literal insertion marker for `CHANGELOG.md` and, with `readmeChangelog`, the plugin readme. Put the marker in both files; a missing marker is an error. Without a marker, plugin readmes use the `== Changelog ==` heading. Failed updates are rolled back for safe retries.
 
+Configure `changelogEntry( { package, changeset, commit } )` to format the changelog entry of each changeset, where `commit` is the `{ hash, shortHash, subject }` of the commit that added the changeset file, if it's committed. The formatted entries go into `CHANGELOG.md`, the `changelog` of each release in the `changeset-version` result, and so the release notes; plugin readmes keep the plain summaries. `getGitHubPullRequest( { cwd, commit } )` finds the `{ number, url, author }` of the pull request that merged a commit with the authenticated `gh` CLI, for example to credit it:
+
+```js
+changelogEntry: async ( { changeset, commit } ) => {
+	const pullRequest = commit && ( await getGitHubPullRequest( { cwd: import.meta.dirname, commit: commit.hash } ) );
+
+	return pullRequest ? `${ changeset.summary } (#${ pullRequest.number } by @${ pullRequest.author })` : changeset.summary;
+},
+```
+
 To release packages separately, for example with a release pull request for each, pass `--package <name>`, repeatable, to version only those packages. A changeset that also names other packages keeps only their entries and its summary, so it still applies to their releases with the same bump. Changesets without packages are left for a run without `--package`.
 
 The `changeset-version` result lists each release with its `package`, `bump`, `currentVersion`, `nextVersion` and `changelog` entries, a Markdown list like the one added to `CHANGELOG.md`. Use it to name and describe the release pull request in a repository script, or call `versionChangesets()` from the library and format the entries of each release with `formatChangelogEntries( release.changesets )`.

package/dist/changeset-config.d.ts

@@ -89,6 +89,8 @@ export interface ChangesetConfig {
     nextVersion?: (input: NextVersionInput) => string;
     /** Format the release notes of a tag, for example to add links. */
     releaseNotes?: (input: ReleaseNotesInput) => string | Promise<string>;
+    /** Format the CHANGELOG.md entry of a changeset, for example to credit its pull request. */
+    changelogEntry?: (input: ChangelogEntryInput) => string | Promise<string>;
 }
 /** Inputs supplied to a custom next-version strategy. */
 export interface NextVersionInput {
@@ -117,6 +119,13 @@ export interface ReleaseNotesInput {
     /** The default release notes: the changelog section, or the commit list without one. */
     notes: string;
 }
+/** Inputs supplied to a custom changelog entry formatter. */
+export interface ChangelogEntryInput {
+    package: ChangesetPackage;
+    changeset: Changeset;
+    /** Commit that added the changeset file, unless it isn't committed yet. */
+    commit?: ReleaseCommit;
+}
 export type WpReleaseConfig = ChangesetConfig;
 export interface PackageJsonVersionOptions {
     file?: string;

package/dist/changeset-config.js

@@ -194,6 +194,10 @@ function validateChangesetConfig(config, configFile) {
         'function' !== typeof candidate.nextVersion) {
         throw new ValidationError(`wp-release config ${configFile}.nextVersion must be a function.`);
     }
+    if (undefined !== candidate.changelogEntry &&
+        'function' !== typeof candidate.changelogEntry) {
+        throw new ValidationError(`wp-release config ${configFile}.changelogEntry must be a function.`);
+    }
     if (undefined !== candidate.releaseNotes &&
         'function' !== typeof candidate.releaseNotes) {
         throw new ValidationError(`wp-release config ${configFile}.releaseNotes must be a function.`);

package/dist/changeset-release.d.ts

@@ -1,4 +1,4 @@
-import type { Changeset, ChangesetPackage, ChangesetReleasePlan, PackageRelease } from './changesets.ts';
+import type { Changeset, ChangesetPackage, ChangesetReleasePlan, PackageRelease, VersionedRelease } from './changesets.ts';
 export interface ChangesetRepository {
     cwd: string;
     configFile?: string;
@@ -9,6 +9,13 @@ export interface ChangesetVersionInput extends ChangesetRepository {
     /** Version only these packages, leaving the other changesets pending. */
     packages?: string[];
 }
+/** Versioned releases, the applied changesets and whether files were changed. */
+export interface VersionChangesetsResult {
+    changesets: Changeset[];
+    releases: VersionedRelease[];
+    date: string;
+    changed: boolean;
+}
 export interface ChangesetTagInput extends ChangesetRepository {
     dryRun?: boolean;
     untagged?: boolean;
@@ -64,10 +71,7 @@ export declare function addChangeset(input: ChangesetRepository & {
  * @param input Repository and versioning options.
  * @return Planned releases and whether files were changed.
  */
-export declare function versionChangesets(input: ChangesetVersionInput): Promise<ChangesetReleasePlan & {
-    date: string;
-    changed: boolean;
-}>;
+export declare function versionChangesets(input: ChangesetVersionInput): Promise<VersionChangesetsResult>;
 /**
  * Create missing release tags, optionally pushing them to the configured remote.
  *

package/dist/changeset-release.js

@@ -6,7 +6,7 @@ import { promisify } from 'node:util';
 import { loadChangesetConfig } from "./changeset-config.js";
 import { findMainPluginFile } from "./package-meta.js";
 import { findConstantValues } from "./version-check.js";
-import { formatChangelogEntries, formatChangeset, getChangesetBump, getNextVersion, parseChangeset, } from "./changesets.js";
+import { formatChangelogList, formatChangeset, getChangesetBump, getNextVersion, parseChangeset, } from "./changesets.js";
 import { ValidationError } from "./errors.js";
 const execFileAsync = promisify(execFile);
 /**
@@ -127,10 +127,12 @@ export async function versionChangesets(input) {
         ? selectReleasePlan(context.plan, packages, input.packages)
         : context.plan;
     const date = input.date ?? new Date().toISOString().slice(0, 10);
+    const changesetDirectory = path.resolve(input.cwd, config.changesets ?? '.changeset');
+    const releases = await getVersionedReleases(input.cwd, config, releasePlan.releases, changesetDirectory);
     if (!input.dryRun) {
         const journal = new Map();
         try {
-            for (const release of releasePlan.releases) {
+            for (const release of releases) {
                 const configured = packages.find((pkg) => pkg.name === release.package.name);
                 if (!configured) {
                     throw new ValidationError(`Unknown package "${release.package.name}".`);
@@ -141,7 +143,6 @@ export async function versionChangesets(input) {
                 await verifyVersionTargets(input.cwd, configured, release.nextVersion);
                 await prependChangelog(configured.directory, release, date, config.readmeChangelog ?? false, config.changelogInsertAfter, journal);
             }
-            const changesetDirectory = path.resolve(input.cwd, config.changesets ?? '.changeset');
             for (const changeset of releasePlan.changesets) {
                 await consumeChangeset(path.join(changesetDirectory, changeset.fileName), changeset, input.packages, journal);
             }
@@ -155,11 +156,76 @@ export async function versionChangesets(input) {
         }
     }
     return {
-        ...releasePlan,
+        changesets: releasePlan.changesets,
+        releases,
         date,
         changed: !input.dryRun && releasePlan.changesets.length > 0,
     };
 }
+/**
+ * Format the changelog entries of each release, with the configured
+ * formatter and the commit that added each changeset.
+ *
+ * @param cwd                Repository root.
+ * @param config             Repository release configuration.
+ * @param releases           Package releases.
+ * @param changesetDirectory Directory of the changeset files.
+ * @return Releases with their changelog entries.
+ */
+async function getVersionedReleases(cwd, config, releases, changesetDirectory) {
+    const commits = new Map();
+    const getCommit = (changeset) => {
+        const cached = commits.get(changeset.fileName) ??
+            getChangesetCommit(cwd, path.join(changesetDirectory, changeset.fileName));
+        commits.set(changeset.fileName, cached);
+        return cached;
+    };
+    return Promise.all(releases.map(async (release) => {
+        const entries = [];
+        // Format one at a time, so that formatters calling an API aren't rate limited.
+        for (const changeset of release.changesets) {
+            entries.push(await getChangelogEntry(config, release.package, changeset, getCommit));
+        }
+        return { ...release, changelog: formatChangelogList(entries) };
+    }));
+}
+async function getChangelogEntry(config, pkg, changeset, getCommit) {
+    const summary = changeset.summary.trim();
+    if (!summary || !config.changelogEntry) {
+        return summary;
+    }
+    const commit = await getCommit(changeset);
+    const entry = await config.changelogEntry({
+        package: pkg,
+        changeset,
+        ...(commit ? { commit } : {}),
+    });
+    if ('string' !== typeof entry) {
+        throw new ValidationError(`The changelogEntry formatter didn't return a string for changeset ${changeset.fileName}.`);
+    }
+    return entry.trim();
+}
+/**
+ * Find the commit that added a changeset file.
+ *
+ * @param cwd  Repository root.
+ * @param file Changeset file.
+ * @return Commit, or undefined when the file isn't committed.
+ */
+async function getChangesetCommit(cwd, file) {
+    const output = await git(cwd, [
+        'log',
+        '--diff-filter=A',
+        '--format=%H%x1f%h%x1f%s',
+        '-1',
+        '--',
+        path.relative(cwd, file).split(path.sep).join('/'),
+    ]);
+    const [hash, shortHash = '', subject = ''] = output
+        .trim()
+        .split('\x1f');
+    return hash ? { hash, shortHash, subject } : undefined;
+}
 /**
  * Limit a release plan to some packages and the changesets that name them.
  *
@@ -749,7 +815,7 @@ async function prependChangelog(directory, release, date, readmeChangelog, chang
     const summaries = release.changesets
         .map((item) => item.summary.trim())
         .filter(Boolean);
-    const section = `## ${release.nextVersion} (${date})\n\n${formatChangelogEntries(release.changesets)}\n\n`;
+    const section = `## ${release.nextVersion} (${date})\n\n${release.changelog}\n\n`;
     const changelog = path.join(directory, 'CHANGELOG.md');
     let previous = '';
     try {

package/dist/changesets.d.ts

@@ -32,6 +32,11 @@ export interface PackageRelease {
     nextVersion: string;
     changesets: Changeset[];
 }
+/** A package release with its formatted changelog entries, once versioned. */
+export interface VersionedRelease extends PackageRelease {
+    /** Changelog entries as a Markdown list, as added to CHANGELOG.md. */
+    changelog: string;
+}
 /** Deterministic release plan assembled from pending changesets. */
 export interface ChangesetReleasePlan {
     changesets: Changeset[];
@@ -60,6 +65,13 @@ export declare function formatChangeset(changeset: Omit<Changeset, 'fileName'>):
  * @return Markdown list, empty without summaries.
  */
 export declare function formatChangelogEntries(changesets: Changeset[]): string;
+/**
+ * Format changelog entries as a Markdown list, indenting their extra lines.
+ *
+ * @param entries Changelog entries; empty ones are left out.
+ * @return Markdown list, empty without entries.
+ */
+export declare function formatChangelogList(entries: string[]): string;
 /**
  * Return the strongest bump requested for a package across changesets.
  *

package/dist/changesets.js

@@ -71,8 +71,16 @@ export function formatChangeset(changeset) {
  * @return Markdown list, empty without summaries.
  */
 export function formatChangelogEntries(changesets) {
-    return changesets
-        .map((item) => item.summary.trim())
+    return formatChangelogList(changesets.map((item) => item.summary.trim()));
+}
+/**
+ * Format changelog entries as a Markdown list, indenting their extra lines.
+ *
+ * @param entries Changelog entries; empty ones are left out.
+ * @return Markdown list, empty without entries.
+ */
+export function formatChangelogList(entries) {
+    return entries
         .filter(Boolean)
         .map((item) => `- ${item.replaceAll(/\r?\n/g, '\n  ')}`)
         .join('\n');

package/dist/commands/changeset-version.js

@@ -1,5 +1,4 @@
 import { versionChangesets } from "../changeset-release.js";
-import { formatChangelogEntries } from "../changesets.js";
 import { getChangesetVersionSummary } from "../summary.js";
 import { parseChangesetVersionArgs, changesetVersionArgs, } from "./changeset-args.js";
 export default {
@@ -38,7 +37,7 @@ changesets without packages are left for a run without --package.`,
                     bump: item.bump,
                     currentVersion: item.currentVersion,
                     nextVersion: item.nextVersion,
-                    changelog: formatChangelogEntries(item.changesets),
+                    changelog: item.changelog,
                 })),
             },
         };

package/dist/github.d.ts

@@ -0,0 +1,24 @@
+/**
+ * A GitHub pull request of a commit.
+ */
+export interface GitHubPullRequest {
+    number: number;
+    url: string;
+    /** GitHub handle of the pull request author, without the @. */
+    author: string;
+}
+export interface GetGitHubPullRequestInput {
+    /** Directory of the repository, whose GitHub remote `gh` uses. */
+    cwd: string;
+    /** Commit hash. */
+    commit: string;
+}
+/**
+ * Find the pull request that merged a commit, with the authenticated `gh`
+ * command line client.
+ *
+ * @param  input Repository directory and commit.
+ * @return The first pull request of the commit, or undefined without one.
+ * @throws {ValidationError} If `gh` fails, like without authentication.
+ */
+export declare function getGitHubPullRequest(input: GetGitHubPullRequestInput): Promise<GitHubPullRequest | undefined>;

package/dist/github.js

@@ -0,0 +1,30 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { ValidationError } from "./errors.js";
+const execFileAsync = promisify(execFile);
+/**
+ * Find the pull request that merged a commit, with the authenticated `gh`
+ * command line client.
+ *
+ * @param  input Repository directory and commit.
+ * @return The first pull request of the commit, or undefined without one.
+ * @throws {ValidationError} If `gh` fails, like without authentication.
+ */
+export async function getGitHubPullRequest(input) {
+    let stdout;
+    try {
+        ({ stdout } = await execFileAsync('gh', ['api', `repos/{owner}/{repo}/commits/${input.commit}/pulls`], { cwd: input.cwd }));
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new ValidationError(`Could not find the pull request of commit ${input.commit}: ${message}`);
+    }
+    const [pullRequest] = JSON.parse(stdout);
+    return pullRequest
+        ? {
+            number: pullRequest.number,
+            url: pullRequest.html_url,
+            author: pullRequest.user?.login ?? '',
+        }
+        : undefined;
+}

package/dist/index.d.ts

@@ -14,7 +14,7 @@ export { ZIP_MTIME, ZIP_FILE_MODE, createZip } from './zip.ts';
 export { isUrl, downloadFile } from './download.ts';
 export { readZipEntries, getZipEntryErrors, extractZip } from './unzip.ts';
 export { GIT_TAG_FORMAT, VersionMismatchError, getGitTagVersion, findConstantValues, findConstantDefinitions, findVersionMismatches, getVersionMismatchProblems, } from './version-check.ts';
-export { CHANGESET_BUMPS, parseChangeset, formatChangeset, formatChangelogEntries, getChangesetBump, getNextVersion, } from './changesets.ts';
+export { CHANGESET_BUMPS, parseChangeset, formatChangeset, formatChangelogEntries, formatChangelogList, getChangesetBump, getNextVersion, } from './changesets.ts';
 export { addChangeset, getChangesetPackages, getChangesetReleasePlan, getChangesetStatus, versionChangesets, tagChangesets, } from './changeset-release.ts';
 export { defineConfig, packageJsonVersion, composerJsonVersion, wordpressPluginVersion, wordpressThemeVersion, wordpressStableTag, gitTagVersion, phpConstantVersion, loadChangesetConfig, } from './changeset-config.ts';
 export { Svn, SvnError, createSvnRunner, parseStatus, toSvnPath, } from './svn.ts';
@@ -40,12 +40,14 @@ export type { FindMainPluginFileInput, HeaderValues, PackageMeta, ParseFileHeade
 export type { CreateZipInput } from './zip.ts';
 export type { ExtractZipInput, ZipEntryInfo, ZipEntryType } from './unzip.ts';
 export type { FindVersionMismatchesInput, GitTagInput, VersionCheckResult, VersionMismatch, } from './version-check.ts';
-export type { Changeset, ChangesetBump, ChangesetPackages, ChangesetConfig, ChangesetPackageType, ChangesetPackage, PackageRelease, ChangesetReleasePlan, } from './changesets.ts';
-export type { ChangesetRepository, ChangesetVersionInput, ChangesetTagInput, ChangesetTagResult, } from './changeset-release.ts';
-export type { WpReleaseConfig, ChangesetPackageGroup, PackageVersionConfig, PackageVersionSource, PackageVersionTarget, PackageIdSource, NextVersionInput, ReleaseCommit, ReleaseNotesInput, PackageJsonVersionOptions, ComposerJsonVersionOptions, WordPressVersionFileOptions, GitTagVersionOptions, PhpConstantVersionOptions, LoadChangesetConfigInput, } from './changeset-config.ts';
+export type { Changeset, ChangesetBump, ChangesetPackages, ChangesetConfig, ChangesetPackageType, ChangesetPackage, PackageRelease, VersionedRelease, ChangesetReleasePlan, } from './changesets.ts';
+export type { ChangesetRepository, ChangesetVersionInput, VersionChangesetsResult, ChangesetTagInput, ChangesetTagResult, } from './changeset-release.ts';
+export type { WpReleaseConfig, ChangesetPackageGroup, PackageVersionConfig, PackageVersionSource, PackageVersionTarget, PackageIdSource, NextVersionInput, ReleaseCommit, ReleaseNotesInput, ChangelogEntryInput, PackageJsonVersionOptions, ComposerJsonVersionOptions, WordPressVersionFileOptions, GitTagVersionOptions, PhpConstantVersionOptions, LoadChangesetConfigInput, } from './changeset-config.ts';
 export type { SvnCheckoutInput, SvnCommandInput, SvnCommandOutput, SvnCommitInput, SvnCopyInput, SvnDepth, SvnOptions, SvnPathsInput, SvnPropsetInput, SvnRunner, SvnStatusEntry, SvnStatusType, SvnUpdateInput, } from './svn.ts';
 export type { SyncDirectoryInput, SyncResult } from './sync.ts';
 export type { SummaryContext } from './summary.ts';
+export { getGitHubPullRequest } from './github.ts';
+export type { GitHubPullRequest, GetGitHubPullRequestInput } from './github.ts';
 export type { CheckoutPath, DeployResult } from './svn-deploy.ts';
 export type { GitCommandInput, GitCommandOutput, GitRunner } from './git.ts';
 export type { GitDeployInput, GitDeployOptions, GitDeployResult, } from './git-deploy.ts';

package/dist/index.js

@@ -14,7 +14,7 @@ export { ZIP_MTIME, ZIP_FILE_MODE, createZip } from "./zip.js";
 export { isUrl, downloadFile } from "./download.js";
 export { readZipEntries, getZipEntryErrors, extractZip } from "./unzip.js";
 export { GIT_TAG_FORMAT, VersionMismatchError, getGitTagVersion, findConstantValues, findConstantDefinitions, findVersionMismatches, getVersionMismatchProblems, } from "./version-check.js";
-export { CHANGESET_BUMPS, parseChangeset, formatChangeset, formatChangelogEntries, getChangesetBump, getNextVersion, } from "./changesets.js";
+export { CHANGESET_BUMPS, parseChangeset, formatChangeset, formatChangelogEntries, formatChangelogList, getChangesetBump, getNextVersion, } from "./changesets.js";
 export { addChangeset, getChangesetPackages, getChangesetReleasePlan, getChangesetStatus, versionChangesets, tagChangesets, } from "./changeset-release.js";
 export { defineConfig, packageJsonVersion, composerJsonVersion, wordpressPluginVersion, wordpressThemeVersion, wordpressStableTag, gitTagVersion, phpConstantVersion, loadChangesetConfig, } from "./changeset-config.js";
 export { Svn, SvnError, createSvnRunner, parseStatus, toSvnPath, } from "./svn.js";
@@ -23,3 +23,4 @@ export { ASSET_MIME_TYPES, SvnDeploy } from "./svn-deploy.js";
 export { GitError, createGitRunner, redactUrls } from "./git.js";
 export { GitDeploy, isValidRefName, resolveGitDeployOptions, } from "./git-deploy.js";
 export { getGitDeployInputFromArgs } from "./commands/deploy-git.js";
+export { getGitHubPullRequest } from "./github.js";

package/package.json

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