refactor: add experimental jest builder

For now this just runs ESBuild-er to build test code, Jest is not actually invoked yet.

This uses `glob` to find test files matching the given pattern. I went out of my way to limit `glob` functionality as much as possible in case we change the implementation later.

(cherry picked from commit 7fe6570)

Author: dgp1130

packages/angular/cli/BUILD.bazel

@@ -85,6 +85,7 @@ CLI_SCHEMA_DATA = [
     "//packages/angular_devkit/build_angular:src/builders/browser-esbuild/schema.json",
     "//packages/angular_devkit/build_angular:src/builders/dev-server/schema.json",
     "//packages/angular_devkit/build_angular:src/builders/extract-i18n/schema.json",
+    "//packages/angular_devkit/build_angular:src/builders/jest/schema.json",
     "//packages/angular_devkit/build_angular:src/builders/karma/schema.json",
     "//packages/angular_devkit/build_angular:src/builders/ng-packagr/schema.json",
     "//packages/angular_devkit/build_angular:src/builders/protractor/schema.json",

packages/angular/cli/lib/config/workspace-schema.json

@@ -360,6 +360,7 @@
                       "@angular-devkit/build-angular:dev-server",
                       "@angular-devkit/build-angular:extract-i18n",
                       "@angular-devkit/build-angular:karma",
+                      "@angular-devkit/build-angular:jest",
                       "@angular-devkit/build-angular:protractor",
                       "@angular-devkit/build-angular:server",
                       "@angular-devkit/build-angular:ng-packagr"
@@ -516,6 +517,28 @@
                 }
               }
             },
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "builder": {
+                  "const": "@angular-devkit/build-angular:jest"
+                },
+                "defaultConfiguration": {
+                  "type": "string",
+                  "description": "A default named configuration to use when a target configuration is not provided."
+                },
+                "options": {
+                  "$ref": "../../../../angular_devkit/build_angular/src/builders/jest/schema.json"
+                },
+                "configurations": {
+                  "type": "object",
+                  "additionalProperties": {
+                    "$ref": "../../../../angular_devkit/build_angular/src/builders/jest/schema.json"
+                  }
+                }
+              }
+            },
             {
               "type": "object",
               "additionalProperties": false,

packages/angular_devkit/build_angular/BUILD.bazel

@@ -38,6 +38,11 @@ ts_json_schema(
     src = "src/builders/extract-i18n/schema.json",
 )
 
+ts_json_schema(
+    name = "jest_schema",
+    src = "src/builders/jest/schema.json",
+)
+
 ts_json_schema(
     name = "karma_schema",
     src = "src/builders/karma/schema.json",
@@ -79,6 +84,7 @@ ts_library(
         "//packages/angular_devkit/build_angular:src/builders/browser/schema.ts",
         "//packages/angular_devkit/build_angular:src/builders/dev-server/schema.ts",
         "//packages/angular_devkit/build_angular:src/builders/extract-i18n/schema.ts",
+        "//packages/angular_devkit/build_angular:src/builders/jest/schema.ts",
         "//packages/angular_devkit/build_angular:src/builders/karma/schema.ts",
         "//packages/angular_devkit/build_angular:src/builders/ng-packagr/schema.ts",
         "//packages/angular_devkit/build_angular:src/builders/protractor/schema.ts",
@@ -267,7 +273,7 @@ ts_library(
             "src/**/tests/*.ts",
         ],
         exclude = [
-            "src/testing/**/*_spec.ts",
+            "src/**/*_spec.ts",
         ],
     ),
     data = glob(["test/**/*"]),
@@ -347,6 +353,12 @@ LARGE_SPECS = {
             "@npm//buffer",
         ],
     },
+    "jest": {
+        "extra_deps": [
+            "@npm//glob",
+            "@npm//@types/glob",
+        ],
+    },
 }
 
 [

packages/angular_devkit/build_angular/builders.json

@@ -26,6 +26,11 @@
       "schema": "./src/builders/extract-i18n/schema.json",
       "description": "Extract i18n strings from a browser application."
     },
+    "jest": {
+      "implementation": "./src/builders/jest",
+      "schema": "./src/builders/jest/schema.json",
+      "description": "Run unit tests using Jest."
+    },
     "karma": {
       "implementation": "./src/builders/karma",
       "schema": "./src/builders/karma/schema.json",

packages/angular_devkit/build_angular/src/builders/jest/index.ts

@@ -0,0 +1,66 @@
+/**
+ * @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 { BuilderContext, BuilderOutput, createBuilder } from '@angular-devkit/architect';
+import { buildEsbuildBrowserInternal } from '../browser-esbuild';
+import { BrowserEsbuildOptions } from '../browser-esbuild/options';
+import { OutputHashing } from '../browser-esbuild/schema';
+import { normalizeOptions } from './options';
+import { Schema as JestBuilderSchema } from './schema';
+import { findTestFiles } from './test-files';
+
+/** Main execution function for the Jest builder. */
+export default createBuilder(
+  async (schema: JestBuilderSchema, context: BuilderContext): Promise<BuilderOutput> => {
+    context.logger.warn(
+      'NOTE: The Jest builder is currently EXPERIMENTAL and not ready for production use.',
+    );
+
+    const options = normalizeOptions(schema);
+    const testFiles = await findTestFiles(options, context.workspaceRoot);
+    const testOut = 'dist/test-out'; // TODO(dgp1130): Hide in temp directory.
+
+    // Build all the test files.
+    return await build(context, {
+      entryPoints: testFiles,
+      tsConfig: options.tsConfig,
+      polyfills: options.polyfills,
+      outputPath: testOut,
+      aot: false,
+      index: null,
+      outputHashing: OutputHashing.None,
+      outExtension: 'mjs', // Force native ESM.
+      commonChunk: false,
+      optimization: false,
+      buildOptimizer: false,
+      sourceMap: {
+        scripts: true,
+        styles: false,
+        vendor: false,
+      },
+    });
+  },
+);
+
+async function build(
+  context: BuilderContext,
+  options: BrowserEsbuildOptions,
+): Promise<BuilderOutput> {
+  try {
+    for await (const _ of buildEsbuildBrowserInternal(options, context)) {
+      // Nothing to do for each event, just wait for the whole build.
+    }
+
+    return { success: true };
+  } catch (err) {
+    return {
+      success: false,
+      error: (err as Error).message,
+    };
+  }
+}

packages/angular_devkit/build_angular/src/builders/jest/options.ts

@@ -0,0 +1,34 @@
+/**
+ * @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 { Schema as JestBuilderSchema } from './schema';
+
+/**
+ * Options supported for the Jest builder. The schema is an approximate
+ * representation of the options type, but this is a more precise version.
+ */
+export type JestBuilderOptions = JestBuilderSchema & {
+  include: string[];
+  exclude: string[];
+};
+
+/**
+ * Normalizes input options validated by the schema to a more precise and useful
+ * options type in {@link JestBuilderOptions}.
+ */
+export function normalizeOptions(schema: JestBuilderSchema): JestBuilderOptions {
+  return {
+    // Options with default values can't actually be null, even if the types say so.
+    /* eslint-disable @typescript-eslint/no-non-null-assertion */
+    include: schema.include!,
+    exclude: schema.exclude!,
+    /* eslint-enable @typescript-eslint/no-non-null-assertion */
+
+    ...schema,
+  };
+}

packages/angular_devkit/build_angular/src/builders/jest/schema.json

@@ -0,0 +1,48 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema",
+  "title": "Jest browser schema for Build Facade.",
+  "description": "Jest target options",
+  "type": "object",
+  "properties": {
+    "include": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "default": ["**/*.spec.ts"],
+      "description": "Globs of files to include, relative to project root. \nThere are 2 special cases:\n - when a path to directory is provided, all spec files ending \".spec.@(ts|tsx)\" will be included\n - when a path to a file is provided, and a matching spec file exists it will be included instead."
+    },
+    "exclude": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "default": [],
+      "description": "Globs of files to exclude, relative to the project root."
+    },
+    "tsConfig": {
+      "type": "string",
+      "description": "The name of the TypeScript configuration file."
+    },
+    "polyfills": {
+      "description": "Polyfills to be included in the build.",
+      "oneOf": [
+        {
+          "type": "array",
+          "description": "A list of polyfills to include in the build. Can be a full path for a file, relative to the current workspace or module specifier. Example: 'zone.js'.",
+          "items": {
+            "type": "string",
+            "uniqueItems": true
+          },
+          "default": []
+        },
+        {
+          "type": "string",
+          "description": "The full path for the polyfills file, relative to the current workspace or a module specifier. Example: 'zone.js'."
+        }
+      ]
+    }
+  },
+  "additionalProperties": false,
+  "required": ["tsConfig"]
+}

packages/angular_devkit/build_angular/src/builders/jest/test-files.ts

@@ -0,0 +1,42 @@
+/**
+ * @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 { IOptions as GlobOptions, glob as globCb } from 'glob';
+import { promisify } from 'util';
+import { JestBuilderOptions } from './options';
+
+const globAsync = promisify(globCb);
+
+/**
+ * Finds all test files in the project.
+ *
+ * @param options The builder options describing where to find tests.
+ * @param workspaceRoot The path to the root directory of the workspace.
+ * @param glob A promisified implementation of the `glob` module. Only intended for
+ *     testing purposes.
+ * @returns A set of all test files in the project.
+ */
+export async function findTestFiles(
+  options: JestBuilderOptions,
+  workspaceRoot: string,
+  glob: typeof globAsync = globAsync,
+): Promise<Set<string>> {
+  const globOptions: GlobOptions = {
+    cwd: workspaceRoot,
+    ignore: ['node_modules/**'].concat(options.exclude),
+    strict: true, // Fail on an "unusual error" when reading the file system.
+    nobrace: true, // Do not expand `a{b,c}` to `ab,ac`.
+    noext: true, // Disable "extglob" patterns.
+    nodir: true, // Match only files, don't care about directories.
+  };
+
+  const included = await Promise.all(options.include.map((pattern) => glob(pattern, globOptions)));
+
+  // Flatten and deduplicate any files found in multiple include patterns.
+  return new Set(included.flat());
+}

packages/angular_devkit/build_angular/src/builders/jest/tests/options.ts

@@ -0,0 +1,16 @@
+/**
+ * @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 { JestBuilderOptions } from '../options';
+
+/** Default options to use for most tests. */
+export const BASE_OPTIONS = Object.freeze<JestBuilderOptions>({
+  include: ['**/*.spec.ts'],
+  exclude: [],
+  tsConfig: 'tsconfig.spec.json',
+});