docs: generate adev-compatible api json

package.json

@@ -46,7 +46,7 @@
     "integration-tests": "bazel test --test_tag_filters=-linker-integration-test --build_tests_only -- //integration/...",
     "test-linker-aot": "bazel test --partial_compilation --test_tag_filters=partial-compilation-integration,-firefox --build_tests_only -- //integration/... //src/...",
     "test-linker-jit": "bazel test --partial_compilation --test_tag_filters=partial-compilation-integration,-firefox --build_tests_only --//tools:force_partial_jit_compilation=True  -- //integration/... //src/...",
-    "check-tooling-setup": "pnpm tsc --project tools/tsconfig.json --noEmit && pnpm tsc --project scripts/tsconfig.json --noEmit && pnpm tsc --project .ng-dev/tsconfig.json --noEmit",
+    "check-tooling-setup": "pnpm tsc --project tools/tsconfig.json --noEmit && pnpm tsc --project tools/adev-api-extraction/tsconfig.json --noEmit && pnpm tsc --project scripts/tsconfig.json --noEmit && pnpm tsc --project .ng-dev/tsconfig.json --noEmit",
     "tsc": "node ./node_modules/typescript/bin/tsc",
     "ci-push-deploy-docs-app": "node --no-warnings=ExperimentalWarning --loader ts-node/esm/transpile-only scripts/docs-deploy/deploy-ci-push.mts",
     "ci-docs-monitor-test": "node --no-warnings=ExperimentalWarning --loader ts-node/esm/transpile-only scripts/docs-deploy/monitoring/ci-test.mts",

src/cdk/BUILD.bazel

@@ -3,6 +3,7 @@ load("//tools:defaults.bzl", "ng_package", "sass_library")
 load("//tools:defaults2.bzl", "ts_project")
 load("//tools/bazel:legacy_target.bzl", "get_legacy_label")
 load("@npm2//:defs.bzl", "npm_link_all_packages")
+load("@aspect_bazel_lib//lib:copy_to_directory.bzl", "copy_to_directory")
 
 package(default_visibility = ["//visibility:public"])
 
@@ -77,3 +78,16 @@ filegroup(
     # which contain a slash are not in the top-level and do not have an overview.
     srcs = ["//src/cdk/%s:overview" % ep for ep in CDK_ENTRYPOINTS if not "/" in ep],
 )
+
+copy_to_directory(
+    name = "adev_json_apis",
+    srcs = [
+        "//src/cdk/testing:json_api",
+        "//src/cdk/testing/protractor:json_api",
+        "//src/cdk/testing/selenium-webdriver:json_api",
+        "//src/cdk/testing/testbed:json_api",
+    ],
+    replace_prefixes = {
+        "**/": "",
+    },
+)

src/cdk/testing/BUILD.bazel

@@ -2,6 +2,7 @@ load("//src/e2e-app:test_suite.bzl", "e2e_test_suite")
 load("//tools:defaults.bzl", "markdown_to_html", "ng_web_test_suite")
 load("//src/cdk/testing/tests:webdriver-test.bzl", "webdriver_test")
 load("//tools:defaults2.bzl", "ts_project")
+load("//tools/adev-api-extraction:extract_api_to_json.bzl", "extract_api_to_json")
 
 package(default_visibility = ["//visibility:public"])
 
@@ -48,3 +49,14 @@ webdriver_test(
         "//src/cdk/testing/tests:webdriver_test_sources",
     ],
 )
+
+extract_api_to_json(
+    name = "json_api",
+    srcs = [
+        ":source-files",
+    ],
+    entry_point = ":index.ts",
+    module_name = "@angular/cdk/testing",
+    output_name = "cdk_testing.json",
+    private_modules = [""],
+)

src/cdk/testing/protractor/BUILD.bazel

@@ -1,4 +1,5 @@
 load("//tools:defaults2.bzl", "ts_project")
+load("//tools/adev-api-extraction:extract_api_to_json.bzl", "extract_api_to_json")
 
 package(default_visibility = ["//visibility:public"])
 
@@ -20,3 +21,14 @@ filegroup(
     name = "source-files",
     srcs = glob(["**/*.ts"]),
 )
+
+extract_api_to_json(
+    name = "json_api",
+    srcs = [
+        ":source-files",
+    ],
+    entry_point = ":index.ts",
+    module_name = "@angular/cdk/testing/protractor",
+    output_name = "cdk_testing_protractor.json",
+    private_modules = [""],
+)

src/cdk/testing/selenium-webdriver/BUILD.bazel

@@ -1,4 +1,5 @@
 load("//tools:defaults2.bzl", "ts_project")
+load("//tools/adev-api-extraction:extract_api_to_json.bzl", "extract_api_to_json")
 
 package(default_visibility = ["//visibility:public"])
 
@@ -19,3 +20,14 @@ filegroup(
     name = "source-files",
     srcs = glob(["**/*.ts"]),
 )
+
+extract_api_to_json(
+    name = "json_api",
+    srcs = [
+        ":source-files",
+    ],
+    entry_point = ":index.ts",
+    module_name = "@angular/cdk//selenium-webdriver",
+    output_name = "cdk_testing_selenium_webdriver.json",
+    private_modules = [""],
+)

src/cdk/testing/testbed/BUILD.bazel

@@ -1,5 +1,6 @@
 load("//tools:defaults2.bzl", "ts_project")
 load("//tools:defaults.bzl", "ng_web_test_suite")
+load("//tools/adev-api-extraction:extract_api_to_json.bzl", "extract_api_to_json")
 
 package(default_visibility = ["//visibility:public"])
 
@@ -36,3 +37,14 @@ ng_web_test_suite(
     name = "unit_tests",
     deps = [":unit_test_sources"],
 )
+
+extract_api_to_json(
+    name = "json_api",
+    srcs = [
+        ":source-files",
+    ],
+    entry_point = ":index.ts",
+    module_name = "@angular/cdk/testing/testbed",
+    output_name = "cdk_testing_testbed.json",
+    private_modules = [""],
+)

tools/adev-api-extraction/BUILD.bazel

@@ -0,0 +1,70 @@
+load("@build_bazel_rules_nodejs//:index.bzl", "nodejs_binary")
+load("@aspect_rules_esbuild//esbuild:defs.bzl", "esbuild")
+load("//tools:defaults2.bzl", "ts_project")
+load("@aspect_rules_ts//ts:defs.bzl", rules_js_tsconfig = "ts_config")
+
+package(default_visibility = ["//visibility:public"])
+
+esbuild(
+    name = "bin",
+    bundle = True,
+    entry_point = ":index.ts",
+    external = [
+        "typescript",
+    ],
+    format = "esm",
+    output = "bin.mjs",
+    platform = "node",
+    target = "es2022",
+    deps = [
+        ":extract_api_to_json_lib",
+        "//:node_modules/@angular/compiler-cli",
+    ],
+)
+
+ts_project(
+    name = "extract_api_to_json_lib",
+    srcs = glob(
+        ["**/*.ts"],
+        exclude = [
+            "**/*.spec.ts",
+        ],
+    ),
+    resolve_json_module = True,
+    tsconfig = ":tsconfig",
+    deps = [
+        "//:node_modules/@angular/compiler",
+        "//:node_modules/@angular/compiler-cli",
+        "//:node_modules/@bazel/runfiles",
+        "//:node_modules/@types/node",
+        "//:node_modules/typescript",
+    ],
+)
+
+# Action binary for the api_gen bazel rule.
+nodejs_binary(
+    name = "extract_api_to_json",
+    data = [
+        ":bin",
+        "//:node_modules/typescript",
+    ],
+    entry_point = "bin.mjs",
+    # Note: Using the linker here as we need it for ESM. The linker is not
+    # super reliably when running concurrently on Windows- but we have existing
+    # actions using the linker. An alternative would be to:
+    #   - bundle the Angular compiler into a CommonJS bundle
+    #   - use the patched resolution- but also patch the ESM imports (similar to how FW does it).
+    visibility = ["//visibility:public"],
+)
+
+# Expose the sources in the dev-infra NPM package.
+filegroup(
+    name = "files",
+    srcs = glob(["**/*"]),
+)
+
+rules_js_tsconfig(
+    name = "tsconfig",
+    src = "tsconfig.json",
+    deps = ["//:node_modules/@types/node"],
+)

tools/adev-api-extraction/README.md

@@ -0,0 +1,3 @@
+Copied from https://github.com/angular/angular/tree/main/adev/shared-docs/pipeline/api-gen/extraction
+
+TODO: share this script between angular/angular & angular/components

tools/adev-api-extraction/extract_api_to_json.bzl

@@ -0,0 +1,109 @@
+load("@build_bazel_rules_nodejs//:providers.bzl", "run_node")
+
+def _extract_api_to_json(ctx):
+    """Implementation of the extract_api_to_json rule"""
+
+    # Define arguments that will be passed to the underlying nodejs program.
+    args = ctx.actions.args()
+
+    # Use a param file because we may have a large number of inputs.
+    args.set_param_file_format("multiline")
+    args.use_param_file("%s", use_always = True)
+
+    # Pass the module_name for the extracted APIs. This will be something like "@angular/core".
+    args.add(ctx.attr.module_name)
+
+    # Pass the module_label for the extracted APIs, This is something like core for "@angular/core".
+    args.add(ctx.attr.module_label)
+
+    # Pass the set of private modules that should not be included in the API reference.
+    args.add_joined(ctx.attr.private_modules, join_with = ",")
+
+    # Pass the entry_point for from which to extract public symbols.
+    args.add(ctx.file.entry_point)
+
+    # Pass the set of source files from which API reference data will be extracted.
+    args.add_joined(ctx.files.srcs, join_with = ",")
+
+    # Pass the name of the output JSON file.
+    json_output = ctx.outputs.output_name
+    args.add(json_output.path)
+
+    # Pass the import path map
+    # TODO: consider module_mappings_aspect to deal with path mappings instead of manually
+    # specifying them
+    # https://github.com/bazelbuild/rules_nodejs/blob/5.x/internal/linker/link_node_modules.bzl#L236
+    path_map = {}
+    for target, path in ctx.attr.import_map.items():
+        files = target.files.to_list()
+        if len(files) != 1:
+            fail("Expected a single file in import_map target %s" % target.label)
+        path_map[path] = files[0].path
+    args.add(json.encode(path_map))
+
+    # Pass the set of (optional) extra entries
+    args.add_joined(ctx.files.extra_entries, join_with = ",")
+
+    # Define an action that runs the nodejs_binary executable. This is
+    # the main thing that this rule does.
+    run_node(
+        ctx = ctx,
+        inputs = depset(ctx.files.srcs + ctx.files.extra_entries),
+        executable = "_extract_api_to_json",
+        outputs = [json_output],
+        arguments = [args],
+    )
+
+    # The return value describes what the rule is producing. In this case we need to specify
+    # the "DefaultInfo" with the output JSON files.
+    return [DefaultInfo(files = depset([json_output]))]
+
+extract_api_to_json = rule(
+    # Point to the starlark function that will execute for this rule.
+    implementation = _extract_api_to_json,
+    doc = """Rule that extracts Angular API reference information from TypeScript
+             sources and write it to a JSON file""",
+
+    # The attributes that can be set to this rule.
+    attrs = {
+        "srcs": attr.label_list(
+            doc = """The source files for this rule. This must include one or more
+                    TypeScript files.""",
+            allow_empty = False,
+            allow_files = True,
+        ),
+        "output_name": attr.output(
+            doc = """Name of the JSON output file.""",
+        ),
+        "entry_point": attr.label(
+            doc = """Source file entry-point from which to extract public symbols""",
+            mandatory = True,
+            allow_single_file = True,
+        ),
+        "private_modules": attr.string_list(
+            doc = """List of private modules that should not be included in the API symbol linking""",
+        ),
+        "import_map": attr.label_keyed_string_dict(
+            doc = """Map of import path to the index.ts file for that import""",
+            allow_files = True,
+        ),
+        "module_name": attr.string(
+            doc = """JS Module name to be used for the extracted symbols""",
+            mandatory = True,
+        ),
+        "module_label": attr.string(
+            doc = """Module label to be used for the extracted symbols. To be used as display name, for example in API docs""",
+        ),
+        "extra_entries": attr.label_list(
+            doc = """JSON files that contain extra entries to append to the final collection.""",
+            allow_files = True,
+        ),
+
+        # The executable for this rule (private).
+        "_extract_api_to_json": attr.label(
+            default = Label("//tools/adev-api-extraction:extract_api_to_json"),
+            executable = True,
+            cfg = "exec",
+        ),
+    },
+)