refactor(compiler-cli): Do extract symbols from private modules.

JeanMeche · JeanMeche · commit 70ea93da808c · 2024-08-31T20:12:55.000+02:00
Modules like `core/primitives` are considered private and their symbols shouldn't be exposed nor linked in the docs.
diff --git a/adev/shared-docs/pipeline/api-gen/extraction/extract_api_to_json.bzl b/adev/shared-docs/pipeline/api-gen/extraction/extract_api_to_json.bzl
@@ -16,6 +16,9 @@ def _extract_api_to_json(ctx):
     # 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)
 
@@ -77,6 +80,9 @@ extract_api_to_json = rule(
             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,
diff --git a/adev/shared-docs/pipeline/api-gen/extraction/index.ts b/adev/shared-docs/pipeline/api-gen/extraction/index.ts
@@ -17,13 +17,16 @@ function main() {
   const [
     moduleName,
     moduleLabel,
+    serializedPrivateModules,
     entryPointExecRootRelativePath,
     srcs,
     outputFilenameExecRootRelativePath,
     serializedPathMapWithExecRootRelativePaths,
     extraEntriesSrcs,
   ] = rawParamLines;
 
+  const privateModules = new Set(serializedPrivateModules.split(','));
+
   // The path map is a serialized JSON map of import path to index.ts file.
   // For example, {'@angular/core': 'path/to/some/index.ts'}
   const pathMap = JSON.parse(serializedPathMapWithExecRootRelativePaths) as Record<string, string>;
@@ -61,7 +64,7 @@ function main() {
       return result.concat(JSON.parse(readFileSync(path, {encoding: 'utf8'})) as DocEntry[]);
     }, []);
 
-  const apiDoc = program.getApiDocumentation(entryPointExecRootRelativePath);
+  const apiDoc = program.getApiDocumentation(entryPointExecRootRelativePath, privateModules);
   const extractedEntries = apiDoc.entries;
   const combinedEntries = extractedEntries.concat(extraEntries);
 
diff --git a/adev/shared-docs/pipeline/api-gen/generate_api_docs.bzl b/adev/shared-docs/pipeline/api-gen/generate_api_docs.bzl
@@ -1,7 +1,7 @@
 load("//adev/shared-docs/pipeline/api-gen/extraction:extract_api_to_json.bzl", "extract_api_to_json")
 load("//adev/shared-docs/pipeline/api-gen/rendering:render_api_to_html.bzl", "render_api_to_html")
 
-def generate_api_docs(name, module_name, entry_point, srcs, module_label = None, import_map = {}, extra_entries = []):
+def generate_api_docs(name, module_name, entry_point, srcs, private_modules = [""], module_label = None, import_map = {}, extra_entries = []):
     """Generates API documentation reference pages for the given sources."""
     json_outfile = name + "_api.json"
 
@@ -14,6 +14,7 @@ def generate_api_docs(name, module_name, entry_point, srcs, module_label = None,
         output_name = json_outfile,
         import_map = import_map,
         extra_entries = extra_entries,
+        private_modules = private_modules,
     )
 
     render_api_to_html(
diff --git a/packages/compiler-cli/src/ngtsc/core/src/compiler.ts b/packages/compiler-cli/src/ngtsc/core/src/compiler.ts
@@ -904,7 +904,10 @@ export class NgCompiler {
    *
    * @returns A map of symbols with their associated module, eg: ApplicationRef => @angular/core
    */
-  getApiDocumentation(entryPoint: string): {entries: DocEntry[]; symbols: Map<string, string>} {
+  getApiDocumentation(
+    entryPoint: string,
+    privateModules: Set<string>,
+  ): {entries: DocEntry[]; symbols: Map<string, string>} {
     const compilation = this.ensureAnalyzed();
     const checker = this.inputProgram.getTypeChecker();
     const docsExtractor = new DocsExtractor(checker, compilation.metaReader);
@@ -922,7 +925,7 @@ export class NgCompiler {
     // TODO: Technically the current directory is not the root dir.
     // Should probably be derived from the config.
     const rootDir = this.inputProgram.getCurrentDirectory();
-    return docsExtractor.extractAll(entryPointSourceFile, rootDir);
+    return docsExtractor.extractAll(entryPointSourceFile, rootDir, privateModules);
   }
 
   /**
diff --git a/packages/compiler-cli/src/ngtsc/docs/src/extractor.ts b/packages/compiler-cli/src/ngtsc/docs/src/extractor.ts
@@ -50,6 +50,7 @@ export class DocsExtractor {
   extractAll(
     sourceFile: ts.SourceFile,
     rootDir: string,
+    privateModules: Set<string>,
   ): {entries: DocEntry[]; symbols: Map<string, string>} {
     const entries: DocEntry[] = [];
     const symbols = new Map<string, string>();
@@ -77,8 +78,7 @@ export class DocsExtractor {
          */
         const importedSymbols = getImportedSymbols(realSourceFile);
         importedSymbols.forEach((moduleName, symbolName) => {
-          // TODO: we probably want to filter out symbols from private modules (like core/primitives)
-          if (symbolName.startsWith('ɵ')) {
+          if (symbolName.startsWith('ɵ') || privateModules.has(moduleName)) {
             return;
           }
 
diff --git a/packages/compiler-cli/src/ngtsc/program.ts b/packages/compiler-cli/src/ngtsc/program.ts
@@ -399,8 +399,11 @@ export class NgtscProgram implements api.Program {
    * @param entryPoint Path to the entry point for the package for which API
    *     docs should be extracted.
    */
-  getApiDocumentation(entryPoint: string): {entries: DocEntry[]; symbols: Map<string, string>} {
-    return this.compiler.getApiDocumentation(entryPoint);
+  getApiDocumentation(
+    entryPoint: string,
+    privateModules: Set<string>,
+  ): {entries: DocEntry[]; symbols: Map<string, string>} {
+    return this.compiler.getApiDocumentation(entryPoint, privateModules);
   }
 
   getEmittedSourceFiles(): Map<string, ts.SourceFile> {
diff --git a/packages/compiler-cli/test/ngtsc/env.ts b/packages/compiler-cli/test/ngtsc/env.ts
@@ -321,14 +321,14 @@ export class NgtscTestEnvironment {
     const {rootNames, options} = readNgcCommandLineAndConfiguration(this.commandLineArgs);
     const host = createCompilerHost({options});
     const program = createProgram({rootNames, host, options});
-    return (program as NgtscProgram).getApiDocumentation(entryPoint).entries;
+    return (program as NgtscProgram).getApiDocumentation(entryPoint, new Set()).entries;
   }
 
   driveDocsExtractionForSymbols(entryPoint: string): Map<string, string> {
     const {rootNames, options} = readNgcCommandLineAndConfiguration(this.commandLineArgs);
     const host = createCompilerHost({options});
     const program = createProgram({rootNames, host, options});
-    return (program as NgtscProgram).getApiDocumentation(entryPoint).symbols;
+    return (program as NgtscProgram).getApiDocumentation(entryPoint, new Set()).symbols;
   }
 
   driveXi18n(format: string, outputFileName: string, locale: string | null = null): void {
diff --git a/packages/core/BUILD.bazel b/packages/core/BUILD.bazel
@@ -140,6 +140,10 @@ generate_api_docs(
     ],
     entry_point = ":index.ts",
     module_name = "@angular/core",
+    private_modules = [
+        "core/primitives/signals",
+        "core/primitives/event-dispatch",
+    ],
 )
 
 genrule(
