docs: Restructure example build rules (angular#60778)

Restructures the examples build rules so that all examples are exposed
through a single file group in adev/src/content/examples.

Also adds a separate filegroup in the same location for just the
embeddable examples and adds it to the APPLICATION_FILES for the docs
app.

This uncovered the fact that some of our examples have broken
non-compiling code. I've excluded these ones from being embeddable for
now, until the breakages can be addressed

PR Close angular#60778

Author: mmalerba

adev/BUILD.bazel

@@ -23,7 +23,9 @@ APPLICATION_FILES = [
     exclude = [
         "src/**/*.spec.ts",
     ],
-)
+) + [
+    "//adev/src/content/examples:embeddable",
+]
 
 TEST_FILES = APPLICATION_FILES + [
     "karma.conf.js",
@@ -40,7 +42,6 @@ APPLICATION_ASSETS = [
     "//adev/src/assets/icons",
     "//adev/src/assets:api",
     "//adev/src/assets:content",
-    "//adev/src/content/examples/accessibility:example",
 ]
 
 APPLICATION_DEPS = [

adev/shared-docs/pipeline/_previews.bzl

@@ -1,6 +1,6 @@
 load("@build_bazel_rules_nodejs//:providers.bzl", "run_node")
 
-def _generate_previews(ctx):
+def _generate_previews_impl(ctx):
     """Implementation of the previews generator rule"""
 
     # File declaration of the generated ts file
@@ -13,16 +13,16 @@ def _generate_previews(ctx):
     args.add(ctx.attr.example_srcs.label.package)
 
     # Path to the preview map template.
-    args.add(ctx.file.template_src)
+    args.add(ctx.file._template_src)
 
     # Path to the ts output file to write to.
     args.add(ts_output.path)
 
-    ctx.runfiles(files = ctx.files.template_src)
+    ctx.runfiles(files = ctx.files._template_src)
 
     run_node(
         ctx = ctx,
-        inputs = depset(ctx.files.example_srcs + ctx.files.template_src),
+        inputs = depset(ctx.files.example_srcs + ctx.files._template_src),
         executable = "_generate_previews",
         outputs = [ts_output],
         arguments = [args],
@@ -34,15 +34,15 @@ def _generate_previews(ctx):
 
 generate_previews = rule(
     # Point to the starlark function that will execute for this rule.
-    implementation = _generate_previews,
+    implementation = _generate_previews_impl,
     doc = """Rule that generates a map of example previews to their component""",
 
     # The attributes that can be set to this rule.
     attrs = {
         "example_srcs": attr.label(
             doc = """Files used for the previews map generation.""",
         ),
-        "template_src": attr.label(
+        "_template_src": attr.label(
             doc = """The previews map template file to base the generated file on.""",
             default = Label("//adev/shared-docs/pipeline/examples/previews:template"),
             allow_single_file = True,

adev/shared-docs/pipeline/examples/previews/BUILD.bazel

@@ -12,6 +12,7 @@ ts_library(
     ],
     deps = [
         "@npm//@types/node",
+        "@npm//tinyglobby",
         "@npm//typescript",
     ],
 )

adev/shared-docs/pipeline/examples/previews/index.ts

@@ -9,12 +9,11 @@
 import * as fs from 'fs';
 import {readFile, writeFile} from 'fs/promises';
 import {join, relative} from 'path';
+import {glob} from 'tinyglobby';
 import ts from 'typescript';
 
 const [examplesDir, templateFilePath, outputFilePath] = process.argv.slice(2);
 
-const TYPESCRIPT_EXTENSION = '.ts';
-const SKIP_FILES_WITH_EXTENSIONS = ['.e2e-spec.ts', '.spec.ts', '.po.ts'];
 const EXAMPLES_PATH = `../../content/examples`;
 
 interface File {
@@ -29,10 +28,38 @@ interface AnalyzedFiles {
 
 main();
 
+/**
+ * Creates a map of example path to dynamic component import for loading embedded examples.
+ *
+ * For example, given the following inputs:
+ * examplesDir: 'adev/src/content/examples',
+ * templateFilePath: 'adev/shared-docs/pipeline/examples/previews/previews.template',
+ * outputFilePath: 'bazel-out/k8-fastbuild/bin/adev/src/assets/previews/previews.ts'
+ *
+ * The script will generate a mapping of all example components under adev/src/content/examples and
+ * fill them into the given template file, writing the result to the output file.
+ *
+ * It will replace the placeholder text `${previewsComponents}` in the template with mappings like:
+ * ['adev/src/content/examples/accessibility/src/app/app.component.ts']:
+ *   () => import('../../content/examples/accessibility/src/app/app.component').then(c => c.AppComponent),
+ * ['adev/src/content/examples/accessibility/src/app/progress-bar.component.ts']:
+ *   () => import('../../content/examples/accessibility/src/app/progress-bar.component').then(c => c.ExampleProgressbarComponent),
+ * ...
+ */
 async function main() {
-  const files = await retrieveAllTypescriptFiles(
-    examplesDir,
-    (path) => !SKIP_FILES_WITH_EXTENSIONS.some((extensionToSkip) => path.endsWith(extensionToSkip)),
+  const files = await glob(join(examplesDir, '**/*.ts'), {
+    ignore: ['**/*.e2e-spec.ts', '**/*.spec.ts', '**/*.po.ts'],
+  }).then((paths) =>
+    Promise.all(
+      paths.map((path) =>
+        readFile(path, {encoding: 'utf-8'}).then((fileContent) => {
+          return {
+            path: relative(examplesDir, path),
+            content: fileContent,
+          };
+        }),
+      ),
+    ),
   );
 
   const filesWithComponent = files
@@ -47,43 +74,6 @@ async function main() {
   await writeFile(outputFilePath, previewsComponentMap);
 }
 
-/** Recursively search the provided directory for all typescript files and asynchronously load them. */
-function retrieveAllTypescriptFiles(
-  baseDir: string,
-  predicateFn: (path: string) => boolean,
-): Promise<File[]> {
-  const typescriptFiles: Promise<File>[] = [];
-
-  const checkFilesInDirectory = (dir: string) => {
-    const files = fs.readdirSync(dir, {withFileTypes: true});
-    for (const file of files) {
-      const fullPathToFile = join(dir, file.name);
-      const relativeFilePath = relative(baseDir, fullPathToFile);
-
-      if (
-        file.isFile() &&
-        file.name.endsWith(TYPESCRIPT_EXTENSION) &&
-        predicateFn(relativeFilePath)
-      ) {
-        typescriptFiles.push(
-          readFile(fullPathToFile, {encoding: 'utf-8'}).then((fileContent) => {
-            return {
-              path: relativeFilePath,
-              content: fileContent,
-            };
-          }),
-        );
-      } else if (file.isDirectory()) {
-        checkFilesInDirectory(fullPathToFile);
-      }
-    }
-  };
-
-  checkFilesInDirectory(baseDir);
-
-  return Promise.all(typescriptFiles);
-}
-
 /** Returns list of the `Standalone` @Component class names for given file */
 function analyzeFile(file: File): string[] {
   const componentClassNames: string[] = [];

adev/src/assets/previews/BUILD.bazel

@@ -2,6 +2,6 @@ load("//adev/shared-docs:index.bzl", "generate_previews")
 
 generate_previews(
     name = "previews",
-    example_srcs = "//adev/src/content/examples",
+    example_srcs = "//adev/src/content/examples:embeddable",
     visibility = ["//visibility:public"],
 )

adev/src/content/best-practices/BUILD.bazel

@@ -7,70 +7,7 @@ generate_guides(
     ]),
     data = [
         "//adev/src/assets/images:components.svg",
-        "//adev/src/content/examples/accessibility:src/app/app.component.html",
-        "//adev/src/content/examples/accessibility:src/app/app.component.ts",
-        "//adev/src/content/examples/accessibility:src/app/progress-bar.component.ts",
-        "//adev/src/content/examples/dependency-injection:src/app/tree-shaking/service.ts",
-        "//adev/src/content/examples/styleguide:src/01-01/app/app.component.ts",
-        "//adev/src/content/examples/styleguide:src/01-01/app/app.module.ts",
-        "//adev/src/content/examples/styleguide:src/01-01/app/heroes/hero.component.avoid.ts",
-        "//adev/src/content/examples/styleguide:src/01-01/app/heroes/heroes.component.ts",
-        "//adev/src/content/examples/styleguide:src/01-01/app/heroes/shared/hero.model.ts",
-        "//adev/src/content/examples/styleguide:src/01-01/app/heroes/shared/hero.service.ts",
-        "//adev/src/content/examples/styleguide:src/01-01/app/heroes/shared/mock-heroes.ts",
-        "//adev/src/content/examples/styleguide:src/01-01/main.ts",
-        "//adev/src/content/examples/styleguide:src/02-05/main.ts",
-        "//adev/src/content/examples/styleguide:src/02-07/app/heroes/hero.component.avoid.ts",
-        "//adev/src/content/examples/styleguide:src/02-07/app/heroes/hero.component.ts",
-        "//adev/src/content/examples/styleguide:src/02-07/app/users/users.component.avoid.ts",
-        "//adev/src/content/examples/styleguide:src/02-07/app/users/users.component.ts",
-        "//adev/src/content/examples/styleguide:src/02-08/app/shared/validate.directive.avoid.ts",
-        "//adev/src/content/examples/styleguide:src/02-08/app/shared/validate.directive.ts",
-        "//adev/src/content/examples/styleguide:src/04-08/app/app.module.ts",
-        "//adev/src/content/examples/styleguide:src/04-10/app/heroes/heroes.component.html",
-        "//adev/src/content/examples/styleguide:src/04-10/app/heroes/heroes.component.ts",
-        "//adev/src/content/examples/styleguide:src/04-10/app/shared/filter-text/filter-text.component.ts",
-        "//adev/src/content/examples/styleguide:src/04-10/app/shared/filter-text/filter-text.service.ts",
-        "//adev/src/content/examples/styleguide:src/04-10/app/shared/init-caps.pipe.ts",
-        "//adev/src/content/examples/styleguide:src/04-10/app/shared/shared.module.ts",
-        "//adev/src/content/examples/styleguide:src/05-02/app/app.component.html",
-        "//adev/src/content/examples/styleguide:src/05-02/app/heroes/shared/hero-button/hero-button.component.avoid.ts",
-        "//adev/src/content/examples/styleguide:src/05-02/app/heroes/shared/hero-button/hero-button.component.ts",
-        "//adev/src/content/examples/styleguide:src/05-03/app/app.component.avoid.html",
-        "//adev/src/content/examples/styleguide:src/05-03/app/app.component.html",
-        "//adev/src/content/examples/styleguide:src/05-03/app/heroes/shared/hero-button/hero-button.component.avoid.ts",
-        "//adev/src/content/examples/styleguide:src/05-03/app/heroes/shared/hero-button/hero-button.component.ts",
-        "//adev/src/content/examples/styleguide:src/05-04/app/heroes/heroes.component.avoid.ts",
-        "//adev/src/content/examples/styleguide:src/05-04/app/heroes/heroes.component.css",
-        "//adev/src/content/examples/styleguide:src/05-04/app/heroes/heroes.component.html",
-        "//adev/src/content/examples/styleguide:src/05-04/app/heroes/heroes.component.ts",
-        "//adev/src/content/examples/styleguide:src/05-12/app/heroes/shared/hero-button/hero-button.component.avoid.ts",
-        "//adev/src/content/examples/styleguide:src/05-12/app/heroes/shared/hero-button/hero-button.component.ts",
-        "//adev/src/content/examples/styleguide:src/05-13/app/app.component.avoid.html",
-        "//adev/src/content/examples/styleguide:src/05-13/app/app.component.html",
-        "//adev/src/content/examples/styleguide:src/05-13/app/heroes/shared/hero-button/hero-button.component.avoid.ts",
-        "//adev/src/content/examples/styleguide:src/05-13/app/heroes/shared/hero-button/hero-button.component.ts",
-        "//adev/src/content/examples/styleguide:src/05-13/app/heroes/shared/hero-highlight.directive.ts",
-        "//adev/src/content/examples/styleguide:src/05-15/app/heroes/hero-list/hero-list.component.avoid.ts",
-        "//adev/src/content/examples/styleguide:src/05-15/app/heroes/hero-list/hero-list.component.ts",
-        "//adev/src/content/examples/styleguide:src/05-16/app/app.component.avoid.html",
-        "//adev/src/content/examples/styleguide:src/05-16/app/app.component.html",
-        "//adev/src/content/examples/styleguide:src/05-16/app/heroes/hero.component.avoid.ts",
-        "//adev/src/content/examples/styleguide:src/05-16/app/heroes/hero.component.ts",
-        "//adev/src/content/examples/styleguide:src/05-17/app/heroes/hero-list/hero-list.component.avoid.ts",
-        "//adev/src/content/examples/styleguide:src/05-17/app/heroes/hero-list/hero-list.component.ts",
-        "//adev/src/content/examples/styleguide:src/05-18/app/heroes/hero/hero.component.avoid.ts",
-        "//adev/src/content/examples/styleguide:src/05-18/app/heroes/hero/hero.component.optional.ts",
-        "//adev/src/content/examples/styleguide:src/05-18/app/heroes/hero/hero.component.ts",
-        "//adev/src/content/examples/styleguide:src/06-01/app/app.component.html",
-        "//adev/src/content/examples/styleguide:src/06-01/app/shared/highlight.directive.ts",
-        "//adev/src/content/examples/styleguide:src/06-03/app/shared/validator.directive.ts",
-        "//adev/src/content/examples/styleguide:src/06-03/app/shared/validator2.directive.ts",
-        "//adev/src/content/examples/styleguide:src/07-01/app/heroes/shared/hero.service.ts",
-        "//adev/src/content/examples/styleguide:src/07-04/app/heroes/shared/hero-arena.service.avoid.ts",
-        "//adev/src/content/examples/styleguide:src/07-04/app/heroes/shared/hero-arena.service.ts",
-        "//adev/src/content/examples/styleguide:src/09-01/app/heroes/shared/hero-button/hero-button.component.avoid.ts",
-        "//adev/src/content/examples/styleguide:src/09-01/app/heroes/shared/hero-button/hero-button.component.ts",
+        "//adev/src/content/examples",
     ],
     visibility = ["//adev:__subpackages__"],
 )

adev/src/content/ecosystem/service-workers/BUILD.bazel

@@ -6,10 +6,7 @@ generate_guides(
         "*.md",
     ]),
     data = [
-        "//adev/src/content/examples/service-worker-getting-started:src/app/check-for-update.service.ts",
-        "//adev/src/content/examples/service-worker-getting-started:src/app/handle-unrecoverable-state.service.ts",
-        "//adev/src/content/examples/service-worker-getting-started:src/app/log-update.service.ts",
-        "//adev/src/content/examples/service-worker-getting-started:src/app/prompt-update.service.ts",
+        "//adev/src/content/examples",
     ],
     visibility = ["//adev:__subpackages__"],
 )

adev/src/content/examples/BUILD.bazel

@@ -1,7 +1,27 @@
+# All example files.
 filegroup(
     name = "examples",
-    srcs = [
-        "//adev/src/content/examples/accessibility:ts_files",
-    ],
+    srcs = glob(["**"]),
+    visibility = ["//visibility:public"],
+)
+
+# Example files that can be embedded as preview components.
+filegroup(
+    name = "embeddable",
+    srcs = glob(
+        ["*/src/app/**"],
+        exclude = [
+            "testing/**",  # Can't embed test code
+            "i18n/**",  # @angular/localize/init not available in docs app
+            "elements/**",  # @angular/elements not available in docs app
+            "service-worker-getting-started/**",  # @angular/service-worker not available in docs app
+            # TODO: The following examples have broken code that does not compile, fix them and remove them from this list.
+            "ssr/**",
+            "resolution-modifiers/**",
+            "reactive-forms/**",
+            "form-validation/**",
+            "dependency-injection/**",
+        ],
+    ),
     visibility = ["//visibility:public"],
 )