build: migrate manual_api_docs to rules_js (#61181)

Migrates `manual_api_docs` to `rules_js`. Since compiler CLI is ESM
compiled but doesn't have extensions, we can either bundle or simply use
the dependency as type only. This is easier and sufficient for this
use-case.

PR Close #61181

tools/defaults2.bzl

@@ -1,7 +1,10 @@
+load("@aspect_rules_ts//ts:defs.bzl", _ts_config = "ts_config")
 load("@rules_angular//src/ng_project:index.bzl", _ng_project = "ng_project")
 load("//tools/bazel:module_name.bzl", "compute_module_name")
 load("//tools/bazel:ts_project_interop.bzl", _ts_project = "ts_project")
 
+ts_config = _ts_config
+
 def ts_project(
         name,
         source_map = True,

tools/manual_api_docs/BUILD.bazel

@@ -1,37 +1,46 @@
-load("//tools:defaults.bzl", "nodejs_binary", "ts_library")
+load("@aspect_rules_js//js:defs.bzl", "js_binary")
+load("//tools:defaults2.bzl", "ts_config", "ts_project")
 
 package(default_visibility = ["//visibility:public"])
 
-ts_library(
+ts_config(
+    name = "tsconfig_build",
+    src = "tsconfig.json",
+    deps = ["//tools:tsconfig_build"],
+)
+
+ts_project(
     name = "generate_element_api_json_lib",
-    srcs = ["generate_element_api_json.ts"],
+    srcs = ["generate_element_api_json.mts"],
+    tsconfig = ":tsconfig_build",
     deps = [
-        "//packages/compiler-cli",
-        "@npm//@types/node",
+        "//:node_modules/@types/node",
+        "//packages/compiler-cli/src/ngtsc/docs:docs_rjs",
     ],
 )
 
-nodejs_binary(
+js_binary(
     name = "generate_element_api_json",
     data = [
-        ":generate_element_api_json_lib",
+        ":generate_element_api_json_lib_rjs",
     ],
-    entry_point = ":generate_element_api_json.ts",
+    entry_point = ":generate_element_api_json.mjs",
 )
 
-ts_library(
+ts_project(
     name = "generate_block_api_json_lib",
-    srcs = ["generate_block_api_json.ts"],
+    srcs = ["generate_block_api_json.mts"],
+    tsconfig = ":tsconfig_build",
     deps = [
-        "//packages/compiler-cli",
-        "@npm//@types/node",
+        "//:node_modules/@types/node",
+        "//packages/compiler-cli/src/ngtsc/docs:docs_rjs",
     ],
 )
 
-nodejs_binary(
+js_binary(
     name = "generate_block_api_json",
     data = [
-        ":generate_block_api_json_lib",
+        ":generate_block_api_json_lib_rjs",
     ],
-    entry_point = ":generate_block_api_json.ts",
+    entry_point = ":generate_block_api_json.mjs",
 )

tools/manual_api_docs/generate_block_api_json.bzl

@@ -25,6 +25,11 @@ def _generate_block_api_json(ctx):
         executable = "_generate_block_api_json",
         outputs = [manifest],
         arguments = [args],
+        env = {
+            # Note: This rule access source files directly, without copying them over.
+            # Hence we don't need to change the working directory to the bazel-bin.
+            "BAZEL_BINDIR": ".",
+        },
     )
 
     # The return value describes what the rule is producing. In this case we need to specify

tools/manual_api_docs/generate_block_api_json.mts

@@ -6,13 +6,19 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 
-import {DocEntry, DocEntryWithSourceInfo, EntryType} from '@angular/compiler-cli';
+import type {
+  DocEntry,
+  DocEntryWithSourceInfo,
+  EntryType,
+} from '@angular/compiler-cli/src/ngtsc/docs';
 import {readFileSync, writeFileSync} from 'fs';
-import {basename} from 'path';
+import {basename, join} from 'path';
 
 function main() {
-  const [paramFilePath] = process.argv.slice(2);
-  const rawParamLines = readFileSync(paramFilePath, {encoding: 'utf8'}).split('\n');
+  const [paramFileExecPath] = process.argv.slice(2);
+  const paramFileAbsolutePath = join(process.env.JS_BINARY__EXECROOT!, paramFileExecPath);
+
+  const rawParamLines = readFileSync(paramFileAbsolutePath, {encoding: 'utf8'}).split('\n');
   const [srcs, outputFileExecRootRelativePath] = rawParamLines;
 
   const developerPreview = [{'name': 'developerPreview', 'comment': ''}];
@@ -25,7 +31,7 @@ function main() {
 
     return {
       name: `@${basename(sourceFilePath, '.md')}`,
-      entryType: EntryType.Block,
+      entryType: 'block' as EntryType.Block,
       description: filteredContent,
       rawComment: filteredContent,
       source: {

tools/manual_api_docs/generate_element_api_json.bzl

@@ -25,6 +25,11 @@ def _generate_element_api_json(ctx):
         executable = "_generate_element_api_json",
         outputs = [manifest],
         arguments = [args],
+        env = {
+            # Note: This rule access source files directly, without copying them over.
+            # Hence we don't need to change the working directory to the bazel-bin.
+            "BAZEL_BINDIR": ".",
+        },
     )
 
     # The return value describes what the rule is producing. In this case we need to specify

tools/manual_api_docs/generate_element_api_json.mts

@@ -6,13 +6,15 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 
-import {DocEntry, EntryType} from '@angular/compiler-cli';
+import type {DocEntry, EntryType} from '@angular/compiler-cli/src/ngtsc/docs';
 import {readFileSync, writeFileSync} from 'fs';
-import {basename} from 'path';
+import {basename, join} from 'path';
 
 function main() {
-  const [paramFilePath] = process.argv.slice(2);
-  const rawParamLines = readFileSync(paramFilePath, {encoding: 'utf8'}).split('\n');
+  const [paramFileExecPath] = process.argv.slice(2);
+  const paramFileAbsolutePath = join(process.env.JS_BINARY__EXECROOT!, paramFileExecPath);
+
+  const rawParamLines = readFileSync(paramFileAbsolutePath, {encoding: 'utf8'}).split('\n');
   const [srcs, outputFileExecRootRelativePath] = rawParamLines;
 
   const entries: DocEntry[] = srcs.split(',').map((sourceFilePath) => {
@@ -25,7 +27,7 @@ function main() {
         startLine: 0,
         endLine: 0,
       },
-      entryType: EntryType.Element,
+      entryType: 'element' as EntryType.Element,
       description: fileContent,
       rawComment: fileContent,
       jsdocTags: [],

tools/manual_api_docs/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    // Note: We use `bundler` here because compiler-cli is understood as ESM, but
+    // there are no explicit extensions. This is invalid. For our type-only usage this
+    // is fine.
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "paths": {
+      "@angular/compiler-cli/*": ["../../packages/compiler-cli/*"]
+    }
+  }
+}

tools/tsconfig.json

@@ -5,8 +5,8 @@
     "declaration": true,
     "esModuleInterop": true,
     "sourceMap": true,
-    "module": "CommonJS",
-    "moduleResolution": "node10",
+    "module": "NodeNext",
+    "moduleResolution": "nodenext",
     "types": ["node"]
   }
 }