feat(bazel/api-golden): allow for module types to be provided

* feat(bazel/api-golden): allow for module types to be provided

Currently the API golden bazel test rule will just add `@types/<..>`
modules to the TSConfig `types` section. This is unreliable and relies
on the Bazel NodeJS linker which does not work well on Windows.

This commit refactors the logic to rely on path mappings for type
resolution inside the API golden Bazel-based tests. This guarantees
a working rule on Windows and also supports scoped packages. Currently
scoped package types do not work, like `@types/babel__core` which is
actually mapping internally to `@babel/core`.

Our trick will be to use path mappings as mentioned before, manually
computing the scoped package types (like with `@babel/core`). Additionally
referenced types will still be loaded directly as part of the compilation
inputs to support global type definitions like `NodeJS.ProcessEnv`.

The solution is not 100% ideal but it's less breaky than how type resolution
works within `@bazel/typescript` currently.. The biggest issue is that we
assume for global types that the file is called `index.d.ts`. We can allow
this to be provided in the future though, if something comes up

Author: devversion

bazel/api-golden/BUILD.bazel

@@ -13,6 +13,7 @@ ts_library(
         "find_entry_points.ts",
         "index.ts",
         "index_npm_packages.ts",
+        "module_mappings.ts",
         "path-normalize.ts",
         "test_api_report.ts",
     ],

bazel/api-golden/index.bzl

@@ -5,43 +5,35 @@ nodejs_test_args = [
     # Needed so that node doesn't walk back to the source directory.
     # From there, the relative imports would point to .ts files.
     "--node_options=--preserve-symlinks",
-    # TODO(josephperrott): update dependency usages to no longer need bazel patch module resolver
-    # See: https://github.com/bazelbuild/rules_nodejs/wiki#--bazel_patch_module_resolver-now-defaults-to-false-2324
-    "--bazel_patch_module_resolver",
+    "--nobazel_run_linker",
 ]
 
 default_strip_export_pattern = "^ɵ(?!ɵdefineInjectable|ɵinject|ɵInjectableDef)"
 
-"""Escapes a Regular expression so that it can be passed as process argument."""
-
 def _escape_regex_for_arg(value):
+    """Escapes a Regular expression so that it can be passed as process argument."""
     return "\"%s\"" % value
 
-"""
-  Extracts type names from a list of NPM type targets.
+def extract_module_names_from_npm_targets(type_targets):
+    """Extracts the module names from a list of NPM targets.
 
-  For example: Consider the `@npm//@types/node` target. This function extracts `node`
-  from the label. This is needed so that the Node types can be wired up within a
-  TypeScript program using the `types` tsconfig option.
-"""
+    For example: Consider the `@npm//@types/node` target. This function extracts
+    `@types/node` from the label. This is needed so that the Node types can be
+    resolved from within the test runner through runfile resolution.
+    """
+    module_names = []
 
-def extract_type_names_from_labels(type_targets):
-    type_names = []
     for type_target in type_targets:
-        type_package = Label(type_target).package
+        type_label = Label(type_target)
+        type_package = type_label.package
 
-        if (type_package.startswith("@types/")):
-            type_names.append(type_package[len("@types/"):])
-        else:
-            fail("Expected type target to match the following format: " +
-                 "`@<npm_workspace>//@types/<name>`, but got: %s" % type_target)
+        if type_label.workspace_name != "npm":
+            fail("Expected type targets to be part of the `@npm` workspace." +
+                 "e.g. `@npm//@types/nodes`.")
 
-    return type_names
+        module_names.append(type_package)
 
-"""
-  Builds an API report for the specified entry-point and compares it against the
-  specified golden
-"""
+    return module_names
 
 def api_golden_test(
         name,
@@ -51,6 +43,18 @@ def api_golden_test(
         strip_export_pattern = default_strip_export_pattern,
         types = [],
         **kwargs):
+    """Builds an API report for the specified entry-point and compares it against the
+    specified golden
+
+    Args;
+      name: Name of the test target
+      golden: Manifest path to the golden file
+      entry_point: Manifest path to the type definition entry-point.
+      data: Runtime dependenices needed for the rule (e.g. transitive type definitions)
+      strip_export_pattern: An optional regular expression to filter out exports from the golden.
+      types: Optional list of type targets to make available in the API report generation.
+    """
+
     quoted_export_pattern = _escape_regex_for_arg(strip_export_pattern)
 
     kwargs["tags"] = kwargs.get("tags", []) + ["api_guard"]
@@ -73,7 +77,7 @@ def api_golden_test(
         data = test_data,
         entry_point = "//bazel/api-golden:index.ts",
         templated_args = nodejs_test_args + [golden, entry_point, "false", quoted_export_pattern] +
-                         extract_type_names_from_labels(types),
+                         extract_module_names_from_npm_targets(types),
         **kwargs
     )
 
@@ -83,15 +87,10 @@ def api_golden_test(
         data = test_data,
         entry_point = "//bazel/api-golden:index.ts",
         templated_args = nodejs_test_args + [golden, entry_point, "true", quoted_export_pattern] +
-                         extract_type_names_from_labels(types),
+                         extract_module_names_from_npm_targets(types),
         **kwargs
     )
 
-"""
-  Builds an API report for all entrypoints within the given NPM package and compares it
-  against goldens within the specified directory.
-"""
-
 def api_golden_test_npm_package(
         name,
         golden_dir,
@@ -100,6 +99,18 @@ def api_golden_test_npm_package(
         strip_export_pattern = default_strip_export_pattern,
         types = [],
         **kwargs):
+    """Builds an API report for all entry-points within the given NPM package and compares it
+      against goldens within the specified directory.
+
+    Args;
+      name: Name of the test target
+      golden_dir: Manifest path to the golden directory
+      npm_package: Manifest path to the NPM package.
+      data: Runtime dependenices needed for the rule (e.g. the tree artifact of the NPM package)
+      strip_export_pattern: An optional regular expression to filter out exports from the golden.
+      types: Optional list of type targets to make available in the API report generation.
+    """
+
     quoted_export_pattern = _escape_regex_for_arg(strip_export_pattern)
 
     kwargs["tags"] = kwargs.get("tags", []) + ["api_guard"]
@@ -109,7 +120,7 @@ def api_golden_test_npm_package(
         data = ["//bazel/api-golden"] + data + types,
         entry_point = "//bazel/api-golden:index_npm_packages.ts",
         templated_args = nodejs_test_args + [golden_dir, npm_package, "false", quoted_export_pattern] +
-                         extract_type_names_from_labels(types),
+                         extract_module_names_from_npm_targets(types),
         **kwargs
     )
 
@@ -119,6 +130,6 @@ def api_golden_test_npm_package(
         data = ["//bazel/api-golden"] + data + types,
         entry_point = "//bazel/api-golden:index_npm_packages.ts",
         templated_args = nodejs_test_args + [golden_dir, npm_package, "true", quoted_export_pattern] +
-                         extract_type_names_from_labels(types),
+                         extract_module_names_from_npm_targets(types),
         **kwargs
     )

bazel/api-golden/index.ts

@@ -6,9 +6,9 @@
  * found in the LICENSE file at https://angular.io/license
  */
 
-import {runfiles} from '@bazel/runfiles';
 import * as chalk from 'chalk';
 
+import {runfiles} from '@bazel/runfiles';
 import {testApiGolden} from './test_api_report';
 
 /**
@@ -20,14 +20,14 @@ async function main(
   entryPointFilePath: string,
   approveGolden: boolean,
   stripExportPattern: RegExp,
-  typeNames: string[],
+  typePackageNames: string[],
 ) {
   const {succeeded, apiReportChanged} = await testApiGolden(
     goldenFilePath,
     entryPointFilePath,
     approveGolden,
     stripExportPattern,
-    typeNames,
+    typePackageNames,
   );
 
   if (!succeeded && apiReportChanged) {
@@ -49,12 +49,16 @@ if (require.main === module) {
   const entryPointFilePath = runfiles.resolve(args[1]);
   const approveGolden = args[2] === 'true';
   const stripExportPattern = new RegExp(args[3]);
-  const typeNames = args.slice(4);
+  const typePackageNames = args.slice(4);
 
-  main(goldenFilePath, entryPointFilePath, approveGolden, stripExportPattern, typeNames).catch(
-    (e) => {
-      console.error(e);
-      process.exit(1);
-    },
-  );
+  main(
+    goldenFilePath,
+    entryPointFilePath,
+    approveGolden,
+    stripExportPattern,
+    typePackageNames,
+  ).catch((e) => {
+    console.error(e);
+    process.exit(1);
+  });
 }

bazel/api-golden/index_npm_packages.ts

@@ -33,7 +33,7 @@ async function main(
   npmPackageDir: string,
   approveGolden: boolean,
   stripExportPattern: RegExp,
-  typeNames: string[],
+  typePackageNames: string[],
 ) {
   const packageJsonPath = join(npmPackageDir, 'package.json');
   const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf8')) as PackageJson;
@@ -56,7 +56,7 @@ async function main(
       typesEntryPointPath,
       approveGolden,
       stripExportPattern,
-      typeNames,
+      typePackageNames,
       packageJsonPath,
       moduleName,
     );
@@ -90,9 +90,9 @@ if (require.main === module) {
   const npmPackageDir = runfiles.resolve(args[1]);
   const approveGolden = args[2] === 'true';
   const stripExportPattern = new RegExp(args[3]);
-  const typeNames = args.slice(4);
+  const typePackageNames = args.slice(4);
 
-  main(goldenDir, npmPackageDir, approveGolden, stripExportPattern, typeNames).catch((e) => {
+  main(goldenDir, npmPackageDir, approveGolden, stripExportPattern, typePackageNames).catch((e) => {
     console.error(e);
     process.exit(1);
   });

bazel/api-golden/module_mappings.ts

@@ -0,0 +1,87 @@
+/**
+ * @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 * as fs from 'fs';
+import * as path from 'path';
+
+import {runfiles} from '@bazel/runfiles';
+
+/** Regular expression that matches a scoped type package name. */
+const scopedTypesPackageRegex = /^@types\/([^_\/]+)__(.+)/;
+
+/**
+ * Resolves type modules and returns corresponding path mappings and a
+ * list of referenced files.
+ */
+export async function resolveTypePackages(typePackageNames: string[]): Promise<{
+  paths: Record<string, string[]>;
+  typeFiles: string[];
+}> {
+  const typeFiles = [];
+  const paths: Record<string, string[]> = {};
+
+  for (const typePackageName of typePackageNames) {
+    const moduleNames = getModuleNamesForTypePackage(typePackageName);
+    const {entryPointTypeFile, resolvedPackageDir} = await resolveTypeDeclarationOfPackage(
+      typePackageName,
+    );
+
+    typeFiles.push(entryPointTypeFile);
+
+    for (const moduleName of moduleNames) {
+      paths[moduleName] = [resolvedPackageDir];
+    }
+  }
+
+  return {paths, typeFiles};
+}
+
+/** Resolves the type declaration entry-point file of a given package. */
+async function resolveTypeDeclarationOfPackage(moduleName: string): Promise<{
+  entryPointTypeFile: string;
+  resolvedPackageDir: string;
+}> {
+  const pkgJsonPath = runfiles.resolve(`npm/node_modules/${moduleName}/package.json`);
+  const pkgJson = JSON.parse(await fs.promises.readFile(pkgJsonPath, 'utf8')) as {
+    types?: string;
+    typings?: string;
+  };
+  const typesRelativePath = pkgJson.types ?? pkgJson.typings;
+
+  if (typesRelativePath === undefined) {
+    throw new Error(`Unable to resolve type definition for "${moduleName}".`);
+  }
+
+  return {
+    entryPointTypeFile: path.join(path.dirname(pkgJsonPath), typesRelativePath),
+    resolvedPackageDir: path.dirname(pkgJsonPath),
+  };
+}
+
+/**
+ * Gets the module names for a given type package name.
+ *
+ * As an example, for `@types/babel__core` this returns both the `babel__core`
+ * and `@babel/core` module names.
+ */
+function getModuleNamesForTypePackage(name: string): string[] {
+  if (!name.startsWith('@types/')) {
+    return [name];
+  }
+
+  const moduleName = name.slice('@types/'.length);
+  const matches = name.match(scopedTypesPackageRegex);
+
+  if (matches === null) {
+    return [moduleName];
+  }
+
+  // Support potential alternative module names for scoped packages. e.g.
+  // the `@types/babel__core` package could also be for `@babel/core`.
+  return [moduleName, `@${matches[1]}/${matches[2]}`];
+}

bazel/api-golden/test/BUILD.bazel

@@ -8,6 +8,8 @@ api_golden_test(
     ],
     entry_point = "dev-infra/bazel/api-golden/test/fixtures/test_fixture.d.ts",
     golden = "dev-infra/bazel/api-golden/test/goldens/test_golden.md",
+    # API extractor type resolution is prone to non-sandbox errors, so we test Windows.
+    tags = ["windows"],
     types = ["@npm//@types/node"],
 )
 
@@ -19,6 +21,11 @@ api_golden_test_npm_package(
     ],
     golden_dir = "dev-infra/bazel/api-golden/test/goldens/test_package",
     npm_package = "dev-infra/bazel/api-golden/test/fixtures/test_package",
+    # API extractor type resolution is prone to non-sandbox errors, so we test Windows.
+    tags = ["windows"],
+    # API extractor needs to be able to resolve `@babel/core` due to an aliased namespace
+    # we expose as part of the `nested.d.ts` fake entry-point.
+    types = ["@npm//@types/babel__core"],
 )
 
 api_golden_test_npm_package(
@@ -29,4 +36,6 @@ api_golden_test_npm_package(
     ],
     golden_dir = "dev-infra/bazel/api-golden/test/goldens/pkg_no_exports_field",
     npm_package = "dev-infra/bazel/api-golden/test/fixtures/pkg_no_exports_field",
+    # API extractor type resolution is prone to non-sandbox errors, so we test Windows.
+    tags = ["windows"],
 )

bazel/api-golden/test/fixtures/test_package/testing/namespace-alias.ts

@@ -0,0 +1,6 @@
+import * as _babelNamespace from '@babel/core';
+
+// Alias namespace.
+import aliasNamespace = _babelNamespace.types;
+
+export import types = aliasNamespace;

bazel/api-golden/test/fixtures/test_package/testing/nested.d.ts

@@ -1 +1,7 @@
+import {types} from './namespace-alias';
+
+import aliased = types;
+export import reexposed = aliased;
+
+export declare function acceptVersion(v: aliased.ExistsTypeAnnotation): void;
 export declare const nestedFile = true;

bazel/api-golden/test/goldens/test_package/testing/nested/index.md

@@ -4,9 +4,16 @@
 
 ```ts
 
+import * as reexposed from '@babel/types';
+
+// @public (undocumented)
+export function acceptVersion(v: reexposed.ExistsTypeAnnotation): void;
+
 // @public (undocumented)
 export const nestedFile = true;
 
+export { reexposed }
+
 // (No @packageDocumentation comment for this package)
 
 ```