feat(ng-dev): expose entry-point with code-splitting for runtime consumers (#430)

We recently moved all `dependencies` that we bundle into the ng-dev CLI
to the `devDependencies`. This is expected but breaks consumers deeply
importing from `ng-dev` files that do not benefit from the bundling.

We should remove all these deep files and just expose public entry-points
with code splitting. This fixes the dependency issue and also allows us
to limit access to deep code. We would rather want to expose necessary
utilities explicitly, _knowing_ that they are used in consumer projects.

PR Close #430

Author: devversion

BUILD.bazel

@@ -35,8 +35,8 @@ pkg_npm(
     ],
     substitutions = NPM_PACKAGE_SUBSTITUTIONS,
     deps = [
-        "//ng-dev",
-        "//ng-dev:lib",
+        "//ng-dev:bundles",
+        "//ng-dev:types",
         "//tslint-rules:lib",
     ],
 )

ng-dev/BUILD.bazel

@@ -1,4 +1,5 @@
 load("//tools:defaults.bzl", "esbuild", "ts_library")
+load("//bazel:extract_types.bzl", "extract_types")
 
 NG_DEV_EXTERNALS = [
     # `ts-node` is optional for users who write their configurations in TypeScript.
@@ -12,6 +13,7 @@ ts_library(
     name = "ng-dev",
     srcs = [
         "cli.ts",
+        "index.ts",
     ],
     visibility = [
         "//:npm",
@@ -25,55 +27,39 @@ ts_library(
         "//ng-dev/misc",
         "//ng-dev/ngbot",
         "//ng-dev/pr",
+        "//ng-dev/pr/config",
         "//ng-dev/pullapprove",
         "//ng-dev/release",
+        "//ng-dev/release/config",
+        "//ng-dev/release/publish",
+        "//ng-dev/release/versioning",
         "//ng-dev/ts-circular-dependencies",
         "//ng-dev/utils",
         "@npm//@types/yargs",
         "@npm//yargs",
     ],
 )
 
-esbuild(
-    name = "cli-bundle",
-    entry_point = "cli.ts",
-    external = NG_DEV_EXTERNALS,
-    output = "cli-bundle.js",
-    deps = [
-        ":ng-dev",
-    ],
+extract_types(
+    name = "types",
+    visibility = ["//:npm"],
+    deps = [":ng-dev"],
 )
 
 esbuild(
-    name = "build-worker-bundle",
-    entry_point = "//ng-dev/release/build:build-worker.ts",
+    name = "bundles",
+    entry_points = [
+        "cli.ts",
+        "index.ts",
+        # These additional entry-points need to be generated since the `ng-dev` tool tries
+        # to launch these files/scripts dynamically (through e.g. `spawn` or `fork`).
+        "//ng-dev/release/build:build-worker.ts",
+        "//ng-dev/pr/merge:strategies/commit-message-filter.ts",
+    ],
     external = NG_DEV_EXTERNALS,
-    # Note: Needs to be named `build-worker.js` as this is the external path
-    # the release build command resolves the script from.
-    output = "build-worker.js",
+    splitting = True,
+    visibility = ["//:npm"],
     deps = [
-        "//ng-dev/release/build",
-    ],
-)
-
-genrule(
-    name = "commit-message-filter",
-    srcs = ["//ng-dev/pr/merge:strategies/commit-message-filter.js"],
-    # Note: Needs to be named `commit-message-filter.js` as this is the name
-    # the autosquash merge strategy expects the external file to be named.
-    outs = ["commit-message-filter.js"],
-    cmd = """cp $< $@""",
-)
-
-filegroup(
-    name = "lib",
-    srcs = [
-        ":cli-bundle",
-        # The bundle of `ng-dev` relies on the following files to be available next to the `ng-dev`
-        # bundle. This is necessary because the CLI resolves these files using relative paths and
-        # requires these to be external, compared to bundling those up.
-        ":build-worker-bundle",
-        ":commit-message-filter",
+        ":ng-dev",
     ],
-    visibility = ["//:npm"],
 )

ng-dev/index.ts

@@ -0,0 +1,31 @@
+/**
+ * @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
+ */
+
+// Exposes config types, helpers for the individual commands.
+export * from './utils/config';
+export * from './caretaker/config';
+export * from './commit-message/config';
+export * from './format/config';
+export * from './pr/config';
+export * from './release/config';
+
+// Exposes versioning utilities which are useful for building scripts with
+// respect to Angular's branching/versioning and release process.
+export * from './release/versioning';
+
+// 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';
+
+// Additional exports for adding custom release pre-staging, post-build checks.
+// TODO: Remove this once we have a public API for release hooks/checks
+export {ReleaseAction} from './release/publish/actions';
+export {
+  FatalReleaseActionError,
+  UserAbortedReleaseActionError,
+} from './release/publish/actions-error';

ng-dev/pr/merge/BUILD.bazel

@@ -1,7 +1,7 @@
 load("//tools:defaults.bzl", "jasmine_node_test", "ts_library")
 
 exports_files([
-    "strategies/commit-message-filter.js",
+    "strategies/commit-message-filter.ts",
 ])
 
 ts_library(

ng-dev/pr/merge/strategies/autosquash-merge.ts

@@ -6,14 +6,10 @@
  * found in the LICENSE file at https://angular.io/license
  */
 
-import {join} from 'path';
 import {PullRequestFailure} from '../../common/validation/failures';
 import {PullRequest} from '../pull-request';
 import {MergeStrategy, TEMP_PR_HEAD_BRANCH} from './strategy';
 
-/** Path to the commit message filter script. Git expects this paths to use forward slashes. */
-const MSG_FILTER_SCRIPT = join(__dirname, './commit-message-filter.js').replace(/\\/g, '/');
-
 /**
  * Merge strategy that does not use the Github API for merging. Instead, it fetches
  * all target branches and the PR locally. The PR is then cherry-picked with autosquash
@@ -80,7 +76,7 @@ export class AutosquashMergeStrategy extends MergeStrategy {
       'filter-branch',
       '-f',
       '--msg-filter',
-      `${MSG_FILTER_SCRIPT} ${prNumber}`,
+      `${getCommitMessageFilterScriptPath()} ${prNumber}`,
       revisionRange,
     ]);
 
@@ -122,3 +118,12 @@ export class AutosquashMergeStrategy extends MergeStrategy {
     return null;
   }
 }
+
+/** Gets the absolute file path to the commit-message filter script. */
+function getCommitMessageFilterScriptPath(): string {
+  // We resolve the script using module resolution as in the package output
+  // the worker might be bundled but exposed through a subpath export mapping.
+  return require.resolve(
+    '@angular/dev-infra-private/ng-dev/pr/merge/strategies/commit-message-filter',
+  );
+}

ng-dev/pr/merge/strategies/commit-message-filter.js renamed to ng-dev/pr/merge/strategies/commit-message-filter.ts

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+
 /**
  * @license
  * Copyright Google LLC All Rights Reserved.
@@ -34,7 +35,7 @@ if (require.main === module) {
   });
 }
 
-function rewriteCommitMessage(message, prNumber) {
+function rewriteCommitMessage(message: string, prNumber: string) {
   const lines = message.split(/\n/);
   // Add the pull request number to the commit message title. This matches what
   // Github does when PRs are merged on the web through the `Squash and Merge` button.

ng-dev/release/build/index.ts

@@ -18,7 +18,7 @@ import {BuiltPackage} from '../config/index';
  */
 export async function buildReleaseOutput(): Promise<BuiltPackage[] | null> {
   return new Promise((resolve) => {
-    const buildProcess = fork(require.resolve('./build-worker'), {
+    const buildProcess = fork(getBuildWorkerScriptPath(), {
       // The stdio option is set to redirect any "stdout" output directly to the "stderr" file
       // descriptor. An additional "ipc" file descriptor is created to support communication with
       // the build process. https://nodejs.org/api/child_process.html#child_process_options_stdio.
@@ -34,3 +34,10 @@ export async function buildReleaseOutput(): Promise<BuiltPackage[] | null> {
     buildProcess.on('exit', () => resolve(builtPackages));
   });
 }
+
+/** Gets the absolute file path to the build worker script. */
+function getBuildWorkerScriptPath(): string {
+  // We resolve the worker script using module resolution as in the package output
+  // the worker might be bundled but exposed through a subpath export mapping.
+  return require.resolve('@angular/dev-infra-private/ng-dev/release/build/build-worker');
+}

package.json

@@ -10,6 +10,14 @@
     "ng-dev": "ts-node --transpile-only ./ng-dev/cli.ts",
     "update-generated-files": "ts-node --transpile-only ./tools/update-generated-files.ts"
   },
+  "exports": {
+    "./ng-dev/*": {
+      "default": "./ng-dev/bundles/*"
+    },
+    "./*": {
+      "default": "./'"
+    }
+  },
   "packageManager": "yarn@3.2.0",
   "dependencies": {
     "@angular-devkit/build-angular": "14.0.0-next.3",