feat(ng-dev/release): support for custom release pre-checks to be provided

This commit introduces a new config option that can be defined to
configure custom release pre-checks that will run before releasing,
and after the release output has been built.

This allows for pre-release checks and post-build checks. Useful for
e.g. validating release output, checking the migration collection,
checking the peer dependency ranges etc.

Author: devversion

ng-dev/BUILD.bazel

@@ -30,6 +30,7 @@ ts_library(
         "//ng-dev/pullapprove",
         "//ng-dev/release",
         "//ng-dev/release/config",
+        "//ng-dev/release/precheck",
         "//ng-dev/release/publish",
         "//ng-dev/release/versioning",
         "//ng-dev/ts-circular-dependencies",

ng-dev/cli.ts

@@ -9,23 +9,16 @@
 import * as yargs from 'yargs';
 
 import {buildCaretakerParser} from './caretaker/cli';
+import {buildCiParser} from './ci/cli';
 import {buildCommitMessageParser} from './commit-message/cli';
 import {buildFormatParser} from './format/cli';
+import {buildMiscParser} from './misc/cli';
 import {buildNgbotParser} from './ngbot/cli';
 import {buildPrParser} from './pr/cli';
 import {buildPullapproveParser} from './pullapprove/cli';
 import {buildReleaseParser} from './release/cli';
 import {tsCircularDependenciesBuilder} from './ts-circular-dependencies/index';
 import {captureLogOutputForCommand} from './utils/console';
-import {buildMiscParser} from './misc/cli';
-import {buildCiParser} from './ci/cli';
-import {ReleaseAction} from './index';
-
-// Expose the `ReleaseAction` constructor globally so that the COMP repo
-// can hook into it and setup staging/post-building release checks.
-// TODO: Remove once https://github.com/angular/dev-infra/issues/402 is resolved.
-// or if we have code-splitting w/ ESM enabled for the ng-dev bundling.
-(global as any).ReleaseAction = ReleaseAction;
 
 yargs
   .scriptName('ng-dev')

ng-dev/index.ts

@@ -18,6 +18,10 @@ export * from './release/config';
 // respect to Angular's branching/versioning and release process.
 export * from './release/versioning';
 
+// Exposes the release precheck command utilities. These should be available
+// as they are needed for authoring pre-release custom checks.
+export {ReleasePrecheckError} from './release/precheck';
+
 // Exposes console utils that can be used by consumers to e.g. add messages
 // to the dev-infra log which is stored on failures.
 export * from './utils/console';
@@ -27,11 +31,3 @@ export * from './utils/console';
 export * from './utils/git/authenticated-git-client';
 export * from './utils/git/git-client';
 export * from './utils/git/github';
-
-// Additional exports for adding custom release pre-staging, post-build checks.
-// TODO: Remove once https://github.com/angular/dev-infra/issues/402 is resolved.
-export {ReleaseAction} from './release/publish/actions';
-export {
-  FatalReleaseActionError,
-  UserAbortedReleaseActionError,
-} from './release/publish/actions-error';

ng-dev/release/BUILD.bazel

@@ -10,6 +10,7 @@ ts_library(
         "//ng-dev/release/build",
         "//ng-dev/release/info",
         "//ng-dev/release/notes",
+        "//ng-dev/release/precheck",
         "//ng-dev/release/publish",
         "//ng-dev/release/set-dist-tag",
         "//ng-dev/release/stamping",

ng-dev/release/cli.ts

@@ -10,6 +10,7 @@ import * as yargs from 'yargs';
 import {ReleaseBuildCommandModule} from './build/cli';
 import {ReleaseInfoCommandModule} from './info/cli';
 import {ReleaseNotesCommandModule} from './notes/cli';
+import {ReleasePrecheckCommandModule} from './precheck/cli';
 import {ReleasePublishCommandModule} from './publish/cli';
 import {ReleaseSetDistTagCommand} from './set-dist-tag/cli';
 import {BuildEnvStampCommand} from './stamping/cli';
@@ -23,6 +24,7 @@ export function buildReleaseParser(localYargs: yargs.Argv) {
     .command(ReleasePublishCommandModule)
     .command(ReleaseBuildCommandModule)
     .command(ReleaseInfoCommandModule)
+    .command(ReleasePrecheckCommandModule)
     .command(ReleaseSetDistTagCommand)
     .command(BuildEnvStampCommand)
     .command(ReleaseNotesCommandModule);

ng-dev/release/config/index.ts

@@ -52,6 +52,17 @@ export interface ReleaseConfig {
   releasePrLabels?: string[];
   /** Configuration for creating release notes during publishing. */
   releaseNotes?: ReleaseNotesConfig;
+  /**
+   * Optional function that can be provided to run checks for a version before
+   * it can be released.
+   *
+   * If provided, the release can occur when the promise resolves. Upon rejection,
+   * the release will abort the release and print the `ReleasePrecheckError` error.
+   */
+  prereleaseCheck?: (
+    newVersion: SemVer,
+    builtPackagesWithInfo: BuiltPackageWithInfo[],
+  ) => Promise<void>;
 }
 
 /**

ng-dev/release/precheck/BUILD.bazel

@@ -0,0 +1,40 @@
+load("//tools:defaults.bzl", "jasmine_node_test", "ts_library")
+
+ts_library(
+    name = "precheck",
+    srcs = glob(
+        [
+            "**/*.ts",
+        ],
+        exclude = ["*.spec.ts"],
+    ),
+    visibility = ["//ng-dev:__subpackages__"],
+    deps = [
+        "//ng-dev/release/config",
+        "//ng-dev/utils",
+        "@npm//@types/node",
+        "@npm//@types/semver",
+        "@npm//@types/yargs",
+        "@npm//semver",
+    ],
+)
+
+ts_library(
+    name = "test_lib",
+    testonly = True,
+    srcs = glob([
+        "*.spec.ts",
+    ]),
+    deps = [
+        ":precheck",
+        "//ng-dev/release/config",
+        "//ng-dev/utils",
+        "@npm//@types/semver",
+        "@npm//semver",
+    ],
+)
+
+jasmine_node_test(
+    name = "test",
+    specs = [":test_lib"],
+)

ng-dev/release/precheck/cli.ts

@@ -0,0 +1,75 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+// ---- **IMPORTANT** ----
+// This command is part of our external commands invoked by the release publish
+// command. Before making changes, keep in mind that more recent `ng-dev` versions
+// can still invoke this command.
+// ------------------------
+
+import * as semver from 'semver';
+import {CommandModule} from 'yargs';
+
+import {assertPassingReleasePrechecks} from './index';
+import {getConfig} from '../../utils/config';
+import {readBufferFromStdinUntilClosed} from '../../utils/read-stdin-until-closed';
+import {assertValidReleaseConfig, BuiltPackageWithInfo} from '../config/index';
+import {error, red} from '../../utils/console';
+
+/**
+ * Type describing the JSON stdin input of this command. The release tool will
+ * deliver this information through `stdin` because command line arguments are
+ * less reliable and have max-length limits.
+ *
+ * @important When changing this, make sure the release action
+ *   invocation is updated as well.
+ */
+export interface ReleasePrecheckJsonStdin {
+  /** Package output that has been built and can be checked. */
+  builtPackagesWithInfo: BuiltPackageWithInfo[];
+  /** New version that is intended to be released. */
+  newVersion: string;
+}
+
+async function handler() {
+  // Note: Stdin input is buffered until we start reading from it. This allows us to
+  // asynchronously start reading the `stdin` input. With the default `readableFlowing`
+  // value of `null`, data is buffered. See: https://nodejs.org/api/stream.html#three-states.
+  const stdin = await readBufferFromStdinUntilClosed();
+  const config = getConfig();
+  assertValidReleaseConfig(config);
+
+  // Parse the JSON metadata read from `stdin`.
+  const {builtPackagesWithInfo, newVersion: newVersionRaw} = JSON.parse(
+    stdin.toString('utf8'),
+  ) as ReleasePrecheckJsonStdin;
+
+  if (!Array.isArray(builtPackagesWithInfo)) {
+    error(red(`  ✘   Release pre-checks failed. Invalid list of built packages was provided.`));
+    process.exitCode = 1;
+    return;
+  }
+
+  const newVersion = semver.parse(newVersionRaw);
+  if (newVersion === null) {
+    error(red(`  ✘   Release pre-checks failed. Invalid new version was provided.`));
+    process.exitCode = 1;
+    return;
+  }
+
+  if (!(await assertPassingReleasePrechecks(config.release, newVersion, builtPackagesWithInfo))) {
+    process.exitCode = 1;
+  }
+}
+
+/** CLI command module for running checks before releasing. */
+export const ReleasePrecheckCommandModule: CommandModule<{}, {}> = {
+  handler,
+  command: 'precheck',
+  describe: false,
+};

ng-dev/release/precheck/index.ts

@@ -0,0 +1,65 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+import {debug} from 'console';
+import {SemVer} from 'semver';
+import {error, green, info, red, warn, yellow} from '../../utils/console';
+import {BuiltPackageWithInfo, ReleaseConfig} from '../config';
+
+/**
+ * Error class that can be used to report precheck failures. Messaging with
+ * respect to the pre-check error is required to be handled manually.
+ */
+export class ReleasePrecheckError extends Error {}
+
+/**
+ * Runs the release prechecks and checks whether they are passing for the
+ * specified release config, intended new version and built release packages.
+ *
+ * @returns A boolean that indicates whether the prechecks are passing or not.
+ */
+export async function assertPassingReleasePrechecks(
+  config: ReleaseConfig,
+  newVersion: SemVer,
+  builtPackagesWithInfo: BuiltPackageWithInfo[],
+): Promise<boolean> {
+  if (config.prereleaseCheck === undefined) {
+    warn(yellow('  ⚠   Skipping release pre-checks. No checks configured.'));
+    return true;
+  }
+
+  // The user-defined release precheck function is supposed to throw errors upon unmet
+  // checks. We catch this here and print a better message and determine the status.
+  try {
+    await config.prereleaseCheck(newVersion, builtPackagesWithInfo);
+    info(green('  ✓   Release pre-checks passing.'));
+    return true;
+  } catch (e) {
+    if (isReleasePrecheckError(e)) {
+      // Note: Error messaging is expected to be handled manually.
+      debug(e.message);
+      error(red(`  ✘   Release pre-checks failed. Please check the output above.`));
+    } else {
+      error(red(e), '\n');
+      error(red(`  ✘   Release pre-checks errored with unexpected runtime error.`));
+    }
+
+    return false;
+  }
+}
+
+/**
+ * Gets whether the given value is a `ReleasePrecheckError`. This helper exists
+ * because `instanceof` checks would not work due to us not using code-splitting.
+ *
+ * TODO(devversion): Remove this when we expose the same code we use in the CLI,
+ *   using ESBuild code-splitting.
+ */
+function isReleasePrecheckError(value: unknown): value is ReleasePrecheckError {
+  return (value as Partial<Object>).constructor?.name === 'ReleasePrecheckError';
+}