refactor(@angular-devkit/build-angular): convert build optimizer passes to babel plugins

The build optimizer passes that are still relevant for Ivy are now implemented as babel plugins.  Using babel has several advantages.  The `babel-loader` is already present within the build pipeline and many packages will already need to be processed by it.  The `babel-loader` also provides the necessary infrastructure to setup babel and link it to the Webpack build system.  This removes the need for the infrastructure code within the build optimizer loader and reduces the build optimizer to only a set of transformation plugins for babel to consume.  The babel plugin architecture also allows for less code to represent similar transformations and provides a variety of helper utilities which further reduces the amount code needed.
The passes are now implemented to be safer when transforming code.  Enum values which contain potential side effects are also no longer altered.  Enums are wrapped in less destructive manner which reduces the likelihood of incorrectly emitting the transformed enum. Class static fields which contain potential side effects are no longer wrapped in pure annotated IIFEs.  Known safe Angular static fields are also wrapped and Angular static fields which are not required in production code are also dropped.
The conversion of the passes not only reduces the amount of code to maintain but also provides a noticeable performance improvement.  Initial tests of a production build of AIO resulted in a ~10% total build time reduction.

Closes angular#12160

Author: clydin

package.json

@@ -83,6 +83,7 @@
     "@angular/service-worker": "12.0.3",
     "@babel/core": "7.14.3",
     "@babel/generator": "7.14.3",
+    "@babel/helper-annotate-as-pure": "7.12.13",
     "@babel/plugin-transform-runtime": "7.14.3",
     "@babel/preset-env": "7.14.4",
     "@babel/runtime": "7.14.0",
@@ -226,7 +227,7 @@
     "tree-kill": "1.2.2",
     "ts-api-guardian": "0.6.0",
     "ts-node": "^10.0.0",
-    "tslib": "^2.0.0",
+    "tslib": "2.2.0",
     "tslint": "^6.1.3",
     "typescript": "4.2.4",
     "verdaccio": "5.1.0",

packages/angular_devkit/build_angular/BUILD.bazel

@@ -109,6 +109,7 @@ ts_library(
         "@npm//@angular/localize",
         "@npm//@angular/service-worker",
         "@npm//@babel/core",
+        "@npm//@babel/helper-annotate-as-pure",
         "@npm//@babel/plugin-transform-runtime",
         "@npm//@babel/preset-env",
         "@npm//@babel/runtime",
@@ -184,6 +185,7 @@ ts_library(
         "@npm//terser-webpack-plugin",
         "@npm//text-table",
         "@npm//tree-kill",
+        "@npm//tslib",
         "@npm//tslint",
         "@npm//typescript",
         "@npm//webpack",
@@ -201,6 +203,7 @@ ts_library(
         include = [
             "plugins/**/*_spec.ts",
             "src/utils/**/*_spec.ts",
+            "src/babel/**/*_spec.ts",
             "src/angular-cli-files/**/*_spec.ts",
         ],
     ),
@@ -210,6 +213,7 @@ ts_library(
         ":build_angular",
         "//packages/angular_devkit/architect/testing",
         "//packages/angular_devkit/core",
+        "@npm//prettier",
         "@npm//typescript",
         "@npm//webpack",
     ],

packages/angular_devkit/build_angular/package.json

@@ -12,6 +12,7 @@
     "@angular-devkit/core": "0.0.0",
     "@babel/core": "7.14.3",
     "@babel/generator": "7.14.3",
+    "@babel/helper-annotate-as-pure": "7.12.13",
     "@babel/plugin-transform-async-to-generator": "7.13.0",
     "@babel/plugin-transform-runtime": "7.14.3",
     "@babel/preset-env": "7.14.4",
@@ -67,6 +68,7 @@
     "terser-webpack-plugin": "5.1.3",
     "text-table": "0.2.0",
     "tree-kill": "1.2.2",
+    "tslib": "2.2.0",
     "webpack": "5.38.1",
     "webpack-dev-middleware": "5.0.0",
     "webpack-dev-server": "3.11.2",

packages/angular_devkit/build_angular/src/babel/plugins/adjust-static-class-members.ts

@@ -0,0 +1,300 @@
+/**
+ * @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 { NodePath, PluginObj, PluginPass, types } from '@babel/core';
+import annotateAsPure from '@babel/helper-annotate-as-pure';
+
+/**
+ * The name of the Typescript decorator helper function created by the TypeScript compiler.
+ */
+const TSLIB_DECORATE_HELPER_NAME = '__decorate';
+
+/**
+ * The set of Angular static fields that should always be wrapped.
+ * These fields may appear to have side effects but are safe to remove if the associated class
+ * is otherwise unused within the output.
+ */
+const angularStaticsToWrap = new Set([
+  'ɵcmp',
+  'ɵdir',
+  'ɵfac',
+  'ɵinj',
+  'ɵmod',
+  'ɵpipe',
+  'ɵprov',
+  'INJECTOR_KEY',
+]);
+
+/**
+ * An object map of static fields and related value checks for discovery of Angular generated
+ * JIT related static fields.
+ */
+const angularStaticsToElide: Record<string, (path: NodePath<types.Expression>) => boolean> = {
+  'ctorParameters'(path) {
+    return path.isFunctionExpression() || path.isArrowFunctionExpression();
+  },
+  'decorators'(path) {
+    return path.isArrayExpression();
+  },
+  'propDecorators'(path) {
+    return path.isObjectExpression();
+  },
+};
+
+/**
+ * Provides one or more keywords that if found within the content of a source file indicate
+ * that this plugin should be used with a source file.
+ *
+ * @returns An a string iterable containing one or more keywords.
+ */
+export function getKeywords(): Iterable<string> {
+  return ['class'];
+}
+
+/**
+ * Analyze the sibling nodes of a class to determine if any downlevel elements should be
+ * wrapped in a pure annotated IIFE. Also determines if any elements have potential side
+ * effects.
+ *
+ * @param origin The starting NodePath location for analyzing siblings.
+ * @param classIdentifier The identifier node that represents the name of the class.
+ * @param allowWrappingDecorators Whether to allow decorators to be wrapped.
+ * @returns An object containing the results of the analysis.
+ */
+function analyzeClassSiblings(
+  origin: NodePath,
+  classIdentifier: types.Identifier,
+  allowWrappingDecorators: boolean,
+): { hasPotentialSideEffects: boolean; wrapStatementPaths: NodePath<types.Statement>[] } {
+  const wrapStatementPaths: NodePath<types.Statement>[] = [];
+  let hasPotentialSideEffects = false;
+  for (let i = 1; ; ++i) {
+    const nextStatement = origin.getSibling(+origin.key + i);
+    if (!nextStatement.isExpressionStatement()) {
+      break;
+    }
+
+    // Valid sibling statements for class declarations are only assignment expressions
+    // and TypeScript decorator helper call expressions
+    const nextExpression = nextStatement.get('expression');
+    if (nextExpression.isCallExpression()) {
+      if (
+        !types.isIdentifier(nextExpression.node.callee) ||
+        nextExpression.node.callee.name !== TSLIB_DECORATE_HELPER_NAME
+      ) {
+        break;
+      }
+
+      if (allowWrappingDecorators) {
+        wrapStatementPaths.push(nextStatement);
+      } else {
+        // Statement cannot be safely wrapped which makes wrapping the class unneeded.
+        // The statement will prevent even a wrapped class from being optimized away.
+        hasPotentialSideEffects = true;
+      }
+
+      continue;
+    } else if (!nextExpression.isAssignmentExpression()) {
+      break;
+    }
+
+    // Valid assignment expressions should be member access expressions using the class
+    // name as the object and an identifier as the property for static fields or only
+    // the class name for decorators.
+    const left = nextExpression.get('left');
+    if (left.isIdentifier()) {
+      if (
+        !left.scope.bindingIdentifierEquals(left.node.name, classIdentifier) ||
+        !types.isCallExpression(nextExpression.node.right) ||
+        !types.isIdentifier(nextExpression.node.right.callee) ||
+        nextExpression.node.right.callee.name !== TSLIB_DECORATE_HELPER_NAME
+      ) {
+        break;
+      }
+
+      if (allowWrappingDecorators) {
+        wrapStatementPaths.push(nextStatement);
+      } else {
+        // Statement cannot be safely wrapped which makes wrapping the class unneeded.
+        // The statement will prevent even a wrapped class from being optimized away.
+        hasPotentialSideEffects = true;
+      }
+
+      continue;
+    } else if (
+      !left.isMemberExpression() ||
+      !types.isIdentifier(left.node.object) ||
+      !left.scope.bindingIdentifierEquals(left.node.object.name, classIdentifier) ||
+      !types.isIdentifier(left.node.property)
+    ) {
+      break;
+    }
+
+    const propertyName = left.node.property.name;
+    const assignmentValue = nextExpression.get('right');
+    if (angularStaticsToElide[propertyName]?.(assignmentValue)) {
+      nextStatement.remove();
+      --i;
+    } else if (angularStaticsToWrap.has(propertyName) || assignmentValue.isPure()) {
+      wrapStatementPaths.push(nextStatement);
+    } else {
+      // Statement cannot be safely wrapped which makes wrapping the class unneeded.
+      // The statement will prevent even a wrapped class from being optimized away.
+      hasPotentialSideEffects = true;
+    }
+  }
+
+  return { hasPotentialSideEffects, wrapStatementPaths };
+}
+
+/**
+ * The set of classed already visited and analyzed during the plugin's execution.
+ * This is used to prevent adjusted classes from being repeatedly analyzed which can lead
+ * to an infinite loop.
+ */
+const visitedClasses = new WeakSet<types.Class>();
+
+/**
+ * A babel plugin factory function for adjusting classes; primarily with Angular metadata.
+ * The adjustments include wrapping classes with known safe or no side effects with pure
+ * annotations to support dead code removal of unused classes. Angular compiler generated
+ * metadata static fields not required in AOT mode are also elided to better support bundler-
+ * level treeshaking.
+ *
+ * @returns A babel plugin object instance.
+ */
+export default function (): PluginObj {
+  return {
+    visitor: {
+      ClassDeclaration(path: NodePath<types.ClassDeclaration>, state: PluginPass) {
+        const { node: classNode, parentPath } = path;
+        const { wrapDecorators } = state.opts as { wrapDecorators: boolean };
+
+        if (visitedClasses.has(classNode)) {
+          return;
+        }
+
+        // Analyze sibling statements for elements of the class that were downleveled
+        const hasExport =
+          parentPath.isExportNamedDeclaration() || parentPath.isExportDefaultDeclaration();
+        const origin = hasExport ? parentPath : path;
+        const { wrapStatementPaths, hasPotentialSideEffects } = analyzeClassSiblings(
+          origin,
+          classNode.id,
+          wrapDecorators,
+        );
+
+        visitedClasses.add(classNode);
+
+        if (hasPotentialSideEffects || wrapStatementPaths.length === 0) {
+          return;
+        }
+
+        const wrapStatementNodes: types.Statement[] = [];
+        for (const statementPath of wrapStatementPaths) {
+          wrapStatementNodes.push(statementPath.node);
+          statementPath.remove();
+        }
+
+        // Wrap class and safe static assignments in a pure annotated IIFE
+        const container = types.arrowFunctionExpression(
+          [],
+          types.blockStatement([
+            classNode,
+            ...wrapStatementNodes,
+            types.returnStatement(types.cloneNode(classNode.id)),
+          ]),
+        );
+        const replacementInitializer = types.callExpression(
+          types.parenthesizedExpression(container),
+          [],
+        );
+        annotateAsPure(replacementInitializer);
+
+        // Replace class with IIFE wrapped class
+        const declaration = types.variableDeclaration('let', [
+          types.variableDeclarator(types.cloneNode(classNode.id), replacementInitializer),
+        ]);
+        if (parentPath.isExportDefaultDeclaration()) {
+          // When converted to a variable declaration, the default export must be moved
+          // to a subsequent statement to prevent a JavaScript syntax error.
+          parentPath.replaceWithMultiple([
+            declaration,
+            types.exportNamedDeclaration(undefined, [
+              types.exportSpecifier(types.cloneNode(classNode.id), types.identifier('default')),
+            ]),
+          ]);
+        } else {
+          path.replaceWith(declaration);
+        }
+      },
+      ClassExpression(path: NodePath<types.ClassExpression>, state: PluginPass) {
+        const { node: classNode, parentPath } = path;
+        const { wrapDecorators } = state.opts as { wrapDecorators: boolean };
+
+        // Class expressions are used by TypeScript to represent downlevel class/constructor decorators.
+        // If not wrapping decorators, they do not need to be processed.
+        if (!wrapDecorators || visitedClasses.has(classNode)) {
+          return;
+        }
+
+        if (
+          !classNode.id ||
+          !parentPath.isVariableDeclarator() ||
+          !types.isIdentifier(parentPath.node.id) ||
+          parentPath.node.id.name !== classNode.id.name
+        ) {
+          return;
+        }
+
+        const origin = parentPath.parentPath;
+        if (!origin.isVariableDeclaration() || origin.node.declarations.length !== 1) {
+          return;
+        }
+
+        const { wrapStatementPaths, hasPotentialSideEffects } = analyzeClassSiblings(
+          origin,
+          parentPath.node.id,
+          wrapDecorators,
+        );
+
+        visitedClasses.add(classNode);
+
+        if (hasPotentialSideEffects || wrapStatementPaths.length === 0) {
+          return;
+        }
+
+        const wrapStatementNodes: types.Statement[] = [];
+        for (const statementPath of wrapStatementPaths) {
+          wrapStatementNodes.push(statementPath.node);
+          statementPath.remove();
+        }
+
+        // Wrap class and safe static assignments in a pure annotated IIFE
+        const container = types.arrowFunctionExpression(
+          [],
+          types.blockStatement([
+            types.variableDeclaration('let', [
+              types.variableDeclarator(types.cloneNode(classNode.id), classNode),
+            ]),
+            ...wrapStatementNodes,
+            types.returnStatement(types.cloneNode(classNode.id)),
+          ]),
+        );
+        const replacementInitializer = types.callExpression(
+          types.parenthesizedExpression(container),
+          [],
+        );
+        annotateAsPure(replacementInitializer);
+
+        // Add the wrapped class directly to the variable declaration
+        parentPath.get('init').replaceWith(replacementInitializer);
+      },
+    },
+  };
+}