build: simplify api-golden rule and make it rules_js compatible

Simplifies the api-golden rule by removing the single file mode, and
using synthethic npm packages here.

In addition, this commit makes the rule compatible with `rules_js`, by
providing another `_rjs.bzl` file, that will eventually take over the
legacy exports that currently call into the `rjs` variant! (so in
practice this rule is alrady using rjs and can work with `rules_nodejs`
as an interop layer)

Author: devversion

.prettierignore

@@ -25,3 +25,5 @@ github-actions/unified-status-check/main.js
 .github/local-actions/changelog/main.js
 
 bazel/map-size-tracking/test/size-golden.json
+
+bazel/pnpm-lock.yaml

bazel/api-golden/BUILD.bazel

@@ -1,4 +1,4 @@
-load("//bazel:defaults.bzl", "ts_library")
+load("@aspect_rules_ts//ts:defs.bzl", "ts_project")
 
 package(default_visibility = ["//visibility:public"])
 
@@ -7,25 +7,21 @@ exports_files([
     "index_npm_packages.ts",
 ])
 
-ts_library(
+ts_project(
     name = "api-golden",
     srcs = [
         "find_entry_points.ts",
-        "index.ts",
         "index_npm_packages.ts",
         "module_mappings.ts",
         "patch-host.ts",
         "path-normalize.ts",
         "test_api_report.ts",
     ],
-    # A tsconfig needs to be specified as otherwise `ts_library` will look for the config
-    # in `//:package.json` and this breaks when the BUILD file is copied to `@npm//`.
-    tsconfig = "//:tsconfig.json",
+    tsconfig = "//bazel:tsconfig",
     deps = [
-        "@npm//@bazel/runfiles",
-        "@npm//@microsoft/api-extractor",
-        "@npm//@types/node",
-        "@npm//typescript",
+        "//bazel:node_modules/@microsoft/api-extractor",
+        "//bazel:node_modules/@types/node",
+        "//bazel:node_modules/typescript",
     ],
 )
 

bazel/api-golden/find_entry_points.ts

@@ -9,7 +9,7 @@
 import {dirname, join, relative} from 'path';
 import {lstatSync, readFileSync, readdirSync} from 'fs';
 
-import {PackageJson} from './index_npm_packages';
+import {PackageJson} from './index_npm_packages.js';
 
 /** Interface describing a resolved NPM package entry point. */
 export interface PackageEntryPoint {

bazel/api-golden/index.bzl

@@ -1,5 +1,6 @@
-load("//bazel:extract_types.bzl", "extract_types")
-load("@build_bazel_rules_nodejs//:index.bzl", "nodejs_binary", "nodejs_test")
+load("@bazel_skylib//rules:write_file.bzl", "write_file")
+load("@build_bazel_rules_nodejs//:index.bzl", "pkg_npm")
+load("//bazel/api-golden:index_rjs.bzl", _rjs_api_golden_test_npm_package = "api_golden_test_npm_package")
 
 nodejs_test_args = [
     # Needed so that node doesn't walk back to the source directory.
@@ -10,18 +11,8 @@ nodejs_test_args = [
 
 default_strip_export_pattern = "^ɵ(?!ɵdefineInjectable|ɵinject|ɵInjectableDef)"
 
-def _escape_regex_for_arg(value):
-    """Escapes a Regular expression so that it can be passed as process argument."""
-    return "\"%s\"" % value
-
 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
-    `@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 = []
+    types = {}
 
     for type_target in type_targets:
         type_label = Label(type_target)
@@ -31,9 +22,9 @@ def extract_module_names_from_npm_targets(type_targets):
             fail("Expected type targets to be part of the `@npm` workspace." +
                  "e.g. `@npm//@types/nodes`.")
 
-        module_names.append(type_package)
+        types[type_target] = type_package
 
-    return module_names
+    return types
 
 def api_golden_test(
         name,
@@ -43,52 +34,33 @@ 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"]
+    write_file(
+        name = "%s_synthetic_package_json" % name,
+        out = "package.json",
+        content = [json.encode({
+            "name": name,
+            "exports": {
+                ".": {
+                    "types": entry_point,
+                },
+            },
+        })],
+    )
 
-    # For API golden tests not running against a NPM package, we extract all transitive
-    # declarations of the specified `data` targets. This is necessary because API extractor
-    # needs to resolve other targets that have been linked by the Bazel NodeJS rules. The
-    # linker by default only provides access to JavaScript sources, but the API extractor is
-    # specifically concerned with type definitions that we can extract manually here.
-    extract_types(
-        name = "%s_data_typings" % name,
+    pkg_npm(
+        name = "%s_synthetic_package" % name,
+        deps = data + ["%s_synthetic_package_json" % name],
         testonly = True,
-        deps = data,
     )
 
-    test_data = ["//bazel/api-golden", "//:package.json", ":%s_data_typings" % name] + \
-                data + types
-
-    nodejs_test(
+    _rjs_api_golden_test_npm_package(
+        no_copy_to_bin = types,
         name = name,
-        data = test_data,
-        entry_point = "//bazel/api-golden:index.ts",
-        templated_args = nodejs_test_args + [golden, entry_point, "false", quoted_export_pattern] +
-                         extract_module_names_from_npm_targets(types),
-        **kwargs
-    )
-
-    nodejs_binary(
-        name = name + ".accept",
-        testonly = True,
-        data = test_data,
-        entry_point = "//bazel/api-golden:index.ts",
-        templated_args = nodejs_test_args + [golden, entry_point, "true", quoted_export_pattern] +
-                         extract_module_names_from_npm_targets(types),
+        golden_dir = fixup_path_for_rules_js(golden),
+        data = [":%s_synthetic_package" % name] + data,
+        npm_package = "%s/%s_synthetic_package" % (native.package_name(), name),
+        strip_export_pattern = strip_export_pattern,
+        types = extract_module_names_from_npm_targets(types),
         **kwargs
     )
 
@@ -100,37 +72,17 @@ 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"]
-
-    nodejs_test(
+    _rjs_api_golden_test_npm_package(
         name = name,
-        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_module_names_from_npm_targets(types),
+        no_copy_to_bin = types,
+        golden_dir = fixup_path_for_rules_js(golden_dir),
+        npm_package = fixup_path_for_rules_js(npm_package),
+        data = data,
+        strip_export_pattern = strip_export_pattern,
+        types = extract_module_names_from_npm_targets(types),
         **kwargs
     )
 
-    nodejs_binary(
-        name = name + ".accept",
-        testonly = True,
-        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_module_names_from_npm_targets(types),
-        **kwargs
-    )
+def fixup_path_for_rules_js(p):
+    segs = p.split("/")
+    return "/".join(segs[1:])

bazel/api-golden/index.ts

@@ -6,12 +6,12 @@
  * found in the LICENSE file at https://angular.io/license
  */
 
-import {findEntryPointsWithinNpmPackage} from './find_entry_points';
-import {join} from 'path';
-import {normalizePathToPosix} from './path-normalize';
+import {findEntryPointsWithinNpmPackage} from './find_entry_points.js';
+import * as path from 'path';
+import {normalizePathToPosix} from './path-normalize.js';
 import {readFileSync} from 'fs';
-import {runfiles} from '@bazel/runfiles';
-import {testApiGolden} from './test_api_report';
+import {testApiGolden} from './test_api_report.js';
+import * as fs from 'fs';
 
 /** Interface describing contents of a `package.json`. */
 export interface PackageJson {
@@ -37,7 +37,7 @@ async function main(
   // guaranteed to be ESM-only and supports the `mts` extension.
   const chalk = {red: (v: string) => v, yellow: (v: string) => v};
 
-  const packageJsonPath = join(npmPackageDir, 'package.json');
+  const packageJsonPath = path.join(npmPackageDir, 'package.json');
   const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf8')) as PackageJson;
   const entryPoints = findEntryPointsWithinNpmPackage(npmPackageDir, packageJson);
   const outdatedGoldens: string[] = [];
@@ -49,26 +49,34 @@ async function main(
     // entry-point we maintain a separate golden file. These golden files are
     // based on the name of the defining NodeJS exports subpath in the NPM package,
     // See: https://api-extractor.com/pages/overview/demo_api_report/.
-    const goldenName = join(subpath, 'index.api.md');
-    const goldenFilePath = join(goldenDir, goldenName);
-    const moduleName = normalizePathToPosix(join(packageJson.name, subpath));
+    const goldenName = path.join(subpath, 'index.api.md');
+    const goldenFilePath = path.join(goldenDir, goldenName);
+    const moduleName = normalizePathToPosix(path.join(packageJson.name, subpath));
 
-    const {succeeded, apiReportChanged} = await testApiGolden(
-      goldenFilePath,
+    const expected = fs.readFileSync(goldenFilePath, 'utf8');
+    const actual = await testApiGolden(
       typesEntryPointPath,
-      approveGolden,
       stripExportPattern,
       typePackageNames,
       packageJsonPath,
       moduleName,
     );
 
+    if (actual === null) {
+      console.error(`Could not generate API golden for subpath: "${subpath}". See errors above.`);
+      process.exit(1);
+    }
+
     // Keep track of outdated goldens.
-    if (!succeeded && apiReportChanged) {
-      outdatedGoldens.push(goldenName);
+    if (actual !== expected) {
+      if (approveGolden) {
+        fs.writeFileSync(goldenFilePath, actual, 'utf8');
+      } else {
+        outdatedGoldens.push(goldenName);
+      }
     }
 
-    allTestsSucceeding = allTestsSucceeding && succeeded;
+    allTestsSucceeding = allTestsSucceeding && actual === expected;
   }
 
   if (outdatedGoldens.length) {
@@ -89,12 +97,17 @@ async function main(
 // Invoke main.
 (() => {
   const args = process.argv.slice(2);
-  const goldenDir = runfiles.resolve(args[0]);
-  const npmPackageDir = runfiles.resolve(args[1]);
+  let goldenDir = path.resolve(args[0]);
+  const npmPackageDir = path.resolve(args[1]);
   const approveGolden = args[2] === 'true';
   const stripExportPattern = new RegExp(args[3]);
   const typePackageNames = args.slice(4);
 
+  // For approving, point to the real directory outside of the bazel-out.
+  if (approveGolden) {
+    goldenDir = path.join(process.env.BUILD_WORKSPACE_DIRECTORY!, args[0]);
+  }
+
   main(goldenDir, npmPackageDir, approveGolden, stripExportPattern, typePackageNames).catch((e) => {
     console.error(e);
     process.exit(1);