Merge pull request #1609 from intuit/hook-context

simplify hook APIs for easier future extensibility

docs/pages/docs/plugins/changelog-hooks.mdx

@@ -21,6 +21,10 @@ The hooks it provides allow you to customize everything about how the changelog
 This is where you hook into the changelog's hooks.
 See examples below.
 
+```ts
+auto.hooks.onCreateChangelog.tapPromise('Giphy', (changelog, { bump }) => {});
+```
+
 ## addToBody
 
 Add extra content to your changelogs.

docs/pages/docs/plugins/release-lifecycle-hooks.mdx

@@ -154,10 +154,10 @@ You must push the tags to github!
 This hooks is required for plugin that facilitate publishing.
 
 ```ts
-auto.hooks.publish.tapPromise("NPM", async (version: SEMVER) => {
+auto.hooks.publish.tapPromise("NPM", async ({ bump }) => {
   await execPromise("npm", [
     "version",
-    version,
+    bump,
     "-m",
     "Bump version to: %s [skip ci]",
   ]);
@@ -187,19 +187,26 @@ You can either return a string value of just the version or an object containing
 - `details` - The body of the details element
 
 ```ts
-auto.hooks.canary.tapPromise(this.name, async ({ bump, canaryIdentifier, dryRun, quiet }) => {
-  const lastRelease = await auto.git!.getLatestRelease();
-  const current = await auto.getCurrentVersion(lastRelease);
-  const nextVersion = inc(current, bump as ReleaseType);
-  const isScopedPackage = name.match(/@\S+\/\S+/);
-  const canaryVersion = `${nextVersion}-canary${canaryIdentifier}`;
-
-  await execPromise("npm", ["version", canaryVersion, "--no-git-tag-version"]);
-  await execPromise("npm", ["publish", "--tag", "canary"]);
-
-  auto.logger.verbose.info("Successfully published canary version");
-  return canaryVersion;
-});
+auto.hooks.canary.tapPromise(
+  this.name,
+  async ({ bump, canaryIdentifier, dryRun, quiet }) => {
+    const lastRelease = await auto.git!.getLatestRelease();
+    const current = await auto.getCurrentVersion(lastRelease);
+    const nextVersion = inc(current, bump as ReleaseType);
+    const isScopedPackage = name.match(/@\S+\/\S+/);
+    const canaryVersion = `${nextVersion}-canary${canaryIdentifier}`;
+
+    await execPromise("npm", [
+      "version",
+      canaryVersion,
+      "--no-git-tag-version",
+    ]);
+    await execPromise("npm", ["publish", "--tag", "canary"]);
+
+    auto.logger.verbose.info("Successfully published canary version");
+    return canaryVersion;
+  }
+);
 ```
 
 `canary` version should not produce any of the following:
@@ -230,7 +237,7 @@ import {
 
 auto.hooks.next.tapPromise(
   this.name,
-  async (preReleaseVersions, bump, { dryRun }) => {
+  async (preReleaseVersions, { bump, dryRun }) => {
     const branch = getCurrentBranch() || "";
     const lastRelease = await auto.git.getLatestRelease();
     const current =
@@ -328,18 +335,15 @@ _Other examples:_
 
 Ran after the `shipit` command has run.
 
-- `newVersion` - The new version that was release
-- `commits` - the commits in the release
 - `data`
+  - `newVersion` - The new version that was release
+  - `commits` - the commits in the release
   - `context` - The type of release that was created (`latest`, `next`, `canary`, or `old`)
 
 ```ts
-auto.hooks.afterShipIt.tap(
-  "MyPlugin",
-  async (newVersion, commits, { context }) => {
-    // do something
-  }
-);
+auto.hooks.afterShipIt.tap("MyPlugin", async ({ context }) => {
+  // do something
+});
 ```
 
 _Other examples:_

packages/core/src/auto.ts

@@ -125,6 +125,8 @@ interface BeforeShipitContext extends DryRunOption {
 }
 
 interface NextContext extends DryRunOption {
+  /** The bump to apply to the version */
+  bump: SEMVER;
   /** The commits in the next release */
   commits: IExtendedCommit[];
   /** The release notes for all the commits in the next release */
@@ -151,9 +153,11 @@ export interface IAutoHooks {
   /** Ran after the `shipit` command has run. */
   afterShipIt: AsyncParallelHook<
     [
-      string | undefined,
-      IExtendedCommit[],
       {
+        /** The version published in the shipit run */
+        newVersion: string | undefined;
+        /** The commits the version was published for */
+        commitsInRelease: IExtendedCommit[];
         /** The type of release made by shipit */
         context: ShipitContext;
       }
@@ -214,7 +218,15 @@ export interface IAutoHooks {
    * This is where you hook into the changelog's hooks.
    * This hook is exposed for convenience during `this.hooks.onCreateRelease` and at the root `this.hooks`
    */
-  onCreateChangelog: SyncHook<[Changelog, SEMVER | undefined]>;
+  onCreateChangelog: SyncHook<
+    [
+      Changelog,
+      {
+        /** The bump the changelog will make */
+        bump: SEMVER | undefined;
+      }
+    ]
+  >;
   /** Version the package. This is a good opportunity to `git tag` the release also.  */
   version: AsyncParallelHook<
     [
@@ -228,13 +240,20 @@ export interface IAutoHooks {
   /** Ran after the package has been versioned. */
   afterVersion: AsyncParallelHook<[DryRunOption]>;
   /** Publish the package to some package distributor. You must push the tags to github! */
-  publish: AsyncParallelHook<[SEMVER]>;
+  publish: AsyncParallelHook<
+    [
+      {
+        /** The semver bump that was applied in the version hook */
+        bump: SEMVER;
+      }
+    ]
+  >;
   /** Used to publish a canary release. In this hook you get the semver bump and the unique canary postfix ID. */
   canary: AsyncSeriesBailHook<
     [
       DryRunOption &
         QuietOption & {
-          /** The bump to apply to the version */
+          /** The bump being applied to the version */
           bump: SEMVER;
           /** The post-version identifier to add to the version */
           canaryIdentifier: string;
@@ -258,7 +277,7 @@ export interface IAutoHooks {
    * and an array of next versions that been released. If you make another
    * next release be sure to add it the the array.
    */
-  next: AsyncSeriesWaterfallHook<[string[], SEMVER, NextContext]>;
+  next: AsyncSeriesWaterfallHook<[string[], NextContext]>;
   /** Ran after the package has been published. */
   afterPublish: AsyncParallelHook<[]>;
   /** Ran after the package has been published. */
@@ -392,8 +411,8 @@ export default class Auto {
     this.hooks.onCreateRelease.tap("Link onCreateChangelog", (release) => {
       release.hooks.onCreateChangelog.tap(
         "Link onCreateChangelog",
-        (changelog, version) => {
-          this.hooks.onCreateChangelog.call(changelog, version);
+        (changelog, bump) => {
+          this.hooks.onCreateChangelog.call(changelog, { bump });
         }
       );
     });
@@ -1317,7 +1336,8 @@ export default class Auto {
     }
 
     this.logger.verbose.info(`Calling "next" hook with: ${bump}`);
-    const result = await this.hooks.next.promise([], bump, {
+    const result = await this.hooks.next.promise([], {
+      bump,
       commits,
       fullReleaseNotes,
       releaseNotes,
@@ -1484,7 +1504,9 @@ export default class Auto {
     }
 
     const { newVersion, commitsInRelease, context } = publishInfo;
-    await this.hooks.afterShipIt.promise(newVersion, commitsInRelease, {
+    await this.hooks.afterShipIt.promise({
+      newVersion,
+      commitsInRelease,
       context,
     });
   }
@@ -1584,7 +1606,7 @@ export default class Auto {
 
     if (!options.dryRun) {
       this.logger.verbose.info("Calling publish hook");
-      await this.hooks.publish.promise(bump);
+      await this.hooks.publish.promise({ bump });
       this.logger.verbose.info("Calling after publish hook");
       await this.hooks.afterPublish.promise();
     }

packages/core/src/utils/make-hooks.ts

@@ -20,7 +20,7 @@ export const makeHooks = (): IAutoHooks => ({
   beforeShipIt: new AsyncSeriesHook(["context"]),
   afterChangelog: new AsyncSeriesHook(["context"]),
   beforeCommitChangelog: new AsyncSeriesHook(["context"]),
-  afterShipIt: new AsyncParallelHook(["version", "commits", "context"]),
+  afterShipIt: new AsyncParallelHook(["context"]),
   makeRelease: new AsyncSeriesBailHook(["releaseInfo"]),
   afterRelease: new AsyncParallelHook(["releaseInfo"]),
   onCreateRelease: new SyncHook(["options"]),
@@ -35,7 +35,7 @@ export const makeHooks = (): IAutoHooks => ({
   publish: new AsyncParallelHook(["version"]),
   afterPublish: new AsyncParallelHook(),
   canary: new AsyncSeriesBailHook(["canaryContext"]),
-  next: new AsyncSeriesWaterfallHook(["preReleaseVersions", "bump", "context"]),
+  next: new AsyncSeriesWaterfallHook(["preReleaseVersions", "context"]),
 });
 
 /** Make the hooks for "Release" */

plugins/cocoapods/__tests__/cocoapods.test.ts

@@ -247,7 +247,7 @@ describe("Cocoapods Plugin", () => {
         prefixRelease,
       } as Auto.Auto);
 
-      await hook.publish.promise(Auto.SEMVER.patch);
+      await hook.publish.promise({ bump: Auto.SEMVER.patch });
 
       expect(exec).toBeCalledTimes(2);
       expect(exec).lastCalledWith("pod", ["trunk", "push", "./Test.podspec"]);
@@ -264,7 +264,7 @@ describe("Cocoapods Plugin", () => {
         prefixRelease,
       } as Auto.Auto);
 
-      await hook.publish.promise(Auto.SEMVER.patch);
+      await hook.publish.promise({ bump: Auto.SEMVER.patch });
 
       expect(exec).toBeCalledTimes(2);
       expect(exec).lastCalledWith("notpod", [
@@ -288,7 +288,7 @@ describe("Cocoapods Plugin", () => {
         prefixRelease,
       } as Auto.Auto);
 
-      await hook.publish.promise(Auto.SEMVER.patch);
+      await hook.publish.promise({ bump: Auto.SEMVER.patch });
 
       expect(exec).toBeCalledTimes(2);
       expect(exec).lastCalledWith("bundle", [
@@ -317,7 +317,7 @@ describe("Cocoapods Plugin", () => {
         prefixRelease,
       } as Auto.Auto);
 
-      await hook.publish.promise(Auto.SEMVER.patch);
+      await hook.publish.promise({ bump: Auto.SEMVER.patch });
 
       expect(exec).toBeCalledTimes(2);
       expect(exec).lastCalledWith("pod", [
@@ -347,7 +347,7 @@ describe("Cocoapods Plugin", () => {
         prefixRelease,
       } as Auto.Auto);
 
-      await hook.publish.promise(Auto.SEMVER.patch);
+      await hook.publish.promise({ bump: Auto.SEMVER.patch });
 
       expect(exec).toBeCalledTimes(5);
       expect(exec).toHaveBeenNthCalledWith(2, "pod", ["repo", "list"]);
@@ -391,7 +391,7 @@ describe("Cocoapods Plugin", () => {
         prefixRelease,
       } as Auto.Auto);
 
-      await hook.publish.promise(Auto.SEMVER.patch);
+      await hook.publish.promise({ bump: Auto.SEMVER.patch });
 
       expect(exec).toBeCalledTimes(5);
       expect(exec).toHaveBeenNthCalledWith(2, "pod", ["repo", "list"]);
@@ -454,7 +454,7 @@ trunk
         prefixRelease,
       } as Auto.Auto);
 
-      await hook.publish.promise(Auto.SEMVER.patch);
+      await hook.publish.promise({ bump: Auto.SEMVER.patch });
 
       expect(exec).toBeCalledTimes(6);
       expect(exec).toHaveBeenNthCalledWith(2, "pod", ["repo", "list"]);

plugins/crates/__tests__/crates.test.ts

@@ -226,7 +226,7 @@ describe("CratesPlugin", () => {
           remote: "origin",
           baseBranch: "master",
         } as Auto.Auto);
-        await hooks.publish.promise(Auto.SEMVER.patch);
+        await hooks.publish.promise({ bump: Auto.SEMVER.patch });
         expect(exec).toHaveBeenCalledWith("cargo", ["publish"]);
         expect(exec).toHaveBeenCalledWith("git", [
           "push",

plugins/docker/__tests__/docker.test.ts

@@ -165,7 +165,7 @@ describe("Docker Plugin", () => {
   describe("canary", () => {
     test("should do nothing without git", async () => {
       const hooks = setup();
-      await hooks.next.promise([], Auto.SEMVER.patch, {} as any);
+      await hooks.next.promise([], { bump: Auto.SEMVER.patch } as any);
       expect(exec).not.toHaveBeenCalled();
     });
 
@@ -223,7 +223,7 @@ describe("Docker Plugin", () => {
   describe("next", () => {
     test("should do nothing without git", async () => {
       const hooks = setup();
-      await hooks.next.promise([], Auto.SEMVER.patch, {} as any);
+      await hooks.next.promise([], { bump: Auto.SEMVER.patch } as any);
       expect(exec).not.toHaveBeenCalled();
     });
 
@@ -237,7 +237,7 @@ describe("Docker Plugin", () => {
         { registry, image: sourceImage }
       );
 
-      await hooks.next.promise([], Auto.SEMVER.patch, {} as any);
+      await hooks.next.promise([], { bump: Auto.SEMVER.patch } as any);
 
       expect(exec).toHaveBeenCalledWith("git", [
         "tag",
@@ -273,7 +273,8 @@ describe("Docker Plugin", () => {
       );
 
       expect(
-        await hooks.next.promise([], Auto.SEMVER.patch, {
+        await hooks.next.promise([], {
+          bump: Auto.SEMVER.patch,
           dryRun: true,
           quiet: true,
         } as any)
@@ -295,7 +296,7 @@ describe("Docker Plugin", () => {
       );
       await hooks.version.promise({ bump: Auto.SEMVER.patch });
 
-      await hooks.publish.promise(Auto.SEMVER.patch);
+      await hooks.publish.promise({ bump: Auto.SEMVER.patch });
       expect(exec).toHaveBeenCalledWith("docker", [
         "push",
         `${registry}:1.0.1`,
@@ -314,7 +315,7 @@ describe("Docker Plugin", () => {
       );
       await hooks.version.promise({ bump: Auto.SEMVER.patch });
 
-      await hooks.publish.promise(Auto.SEMVER.patch);
+      await hooks.publish.promise({ bump: Auto.SEMVER.patch });
       expect(exec).toHaveBeenCalledWith("docker", [
         "push",
         `${registry}:1.0.1`,

plugins/docker/src/index.ts

@@ -162,7 +162,7 @@ export default class DockerPlugin implements IPlugin {
 
     auto.hooks.next.tapPromise(
       this.name,
-      async (preReleaseVersions, bump, { dryRun }) => {
+      async (preReleaseVersions, { bump, dryRun }) => {
         if (!auto.git) {
           return preReleaseVersions;
         }

plugins/exec/__tests__/exec.test.ts

@@ -192,7 +192,7 @@ describe("Exec Plugin", () => {
       plugins.apply({ hooks } as Auto);
       hooks.onCreateChangelog.call(
         { hooks: changelogHooks } as any,
-        SEMVER.patch
+        { bump: SEMVER.patch }
       );
 
       expect(

plugins/first-time-contributor/__tests__/first-time-contributor.test.ts

@@ -13,8 +13,9 @@ const graphql = jest.fn();
 const exec = jest.fn();
 exec.mockReturnValue("");
 // @ts-ignore
-jest.mock("../../../packages/core/dist/utils/exec-promise", () => (...args: any[]) =>
-  exec(...args)
+jest.mock(
+  "../../../packages/core/dist/utils/exec-promise",
+  () => (...args: any[]) => exec(...args)
 );
 
 const setup = (
@@ -45,7 +46,7 @@ const setup = (
       hooks: changelogHooks,
       options: { baseUrl: "https://github.com" },
     } as Changelog,
-    Auto.SEMVER.patch
+    { bump: Auto.SEMVER.patch }
   );
 
   return changelogHooks;