docs(docs-infra): Throw build error on invalid guide links

The list of valid links is generated from navigation data configuration in the ADEV app.
Redirections are knowingly exclude so we stop referencing them.

Author: JeanMeche

adev/BUILD.bazel

@@ -25,6 +25,19 @@ APPLICATION_FILES = [
     "//adev/src/assets:context",
     "//adev/src/content/examples:embeddable",
     "tailwind.config.js",
+
+    # For the routes that are generated at build time
+    "//adev/src/assets:docs_api_manifest",
+    "//adev/scripts/routes:generate_route",
+    "//adev/src/app/routing/navigation-entries",
+    "//adev/src/app/routing/navigation-entries:navigation_types",
+    "//adev/src/content/reference/errors:route-nav-items",
+    "//adev/src/content/reference/extended-diagnostics:route-nav-items",
+    "//adev/src/content/tutorials/deferrable-views",
+    "//adev/src/content/tutorials/first-app",
+    "//adev/src/content/tutorials/learn-angular",
+    "//adev/src/content/tutorials/signal-forms",
+    "//adev/src/content/tutorials/signals",
 ] + glob(
     ["src/**/*"],
     exclude = ["src/**/*.spec.ts"],

adev/scripts/routes/BUILD.bazel

@@ -0,0 +1,52 @@
+load("@aspect_rules_ts//ts:defs.bzl", "ts_project")
+load("//adev/shared-docs:defaults.bzl", "js_binary", "js_run_binary")
+
+package(default_visibility = ["//adev:__subpackages__"])
+
+ts_project(
+    name = "generate_routes_lib",
+    srcs = [
+        "generate-routes.mts",
+    ],
+    data = [
+        "//adev/src/assets:docs_api_manifest",
+        "//adev/src/content/tutorials/deferrable-views",
+        "//adev/src/content/tutorials/first-app",
+        "//adev/src/content/tutorials/learn-angular",
+        "//adev/src/content/tutorials/signal-forms",
+        "//adev/src/content/tutorials/signals",
+    ],
+    tsconfig = {
+        "compilerOptions": {
+            "target": "ES2022",
+            "moduleResolution": "node",
+            "types": ["node"],
+            "rootDir": ".",
+            "skipLibCheck": True,
+        },
+    },
+    deps = [
+        "//adev:node_modules/@angular/docs",
+        "//adev:node_modules/@types/node",
+        "//adev/src/app/routing/navigation-entries",
+        "//adev/src/content/reference/errors:route-nav-items",
+        "//adev/src/content/reference/extended-diagnostics:route-nav-items",
+    ],
+)
+
+js_binary(
+    name = "generate_route",
+    data = [
+        "generate-routes.mjs",
+        ":generate_routes_lib",
+        "//adev/src/content:guide_files",
+    ],
+    entry_point = ":generate-routes.mjs",
+)
+
+js_run_binary(
+    name = "run_generate_route",
+    outs = ["defined-routes.json"],
+    chdir = package_name(),
+    tool = ":generate_route",
+)

adev/scripts/routes/generate-routes.mts

@@ -0,0 +1,82 @@
+/*!
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.dev/license
+ */
+
+import {ALL_ITEMS} from '../../src/app/routing/navigation-entries';
+import {NavigationItem} from '@angular/docs';
+import {writeFileSync, readFileSync} from 'fs';
+import {join, resolve} from 'path';
+
+const outputFile = 'defined-routes.json';
+const contentRoot = resolve(process.cwd(), '../../src/content');
+
+/**
+ * The scripts generates a list of all defined routes in the guides section and stores them
+ * in a JSON file. This file then used by other bazel targets to know which routes are valid.
+ */
+
+function extractRoutes(items: NavigationItem[]): string[] {
+  const routes: string[] = [];
+  for (const item of items) {
+    if (item.path && !item.path.startsWith('http')) {
+      routes.push(item.path);
+      if (item.contentPath) {
+        const content = readFileSync(join(contentRoot, `${item.contentPath}.md`), {
+          encoding: 'utf-8',
+        });
+        const headings = extractHeadings(content);
+        routes.push(
+          ...headings.map(
+            (heading) => `${item.path}#${heading.toLowerCase().replace(/\s+/g, '-')}`,
+          ),
+        );
+      }
+    }
+    if (item.children) {
+      routes.push(...extractRoutes(item.children));
+    }
+  }
+  return routes;
+}
+
+function extractHeadings(content: string): string[] {
+  const headings = content
+    .split('\n')
+    // Top level heading (H1) are used for the page title only
+    // and yes, headings can have leading spaces
+    .filter((line) => line.trim().startsWith('##'))
+    .map((line) => line.replace(/^#+\s*/, '').trim());
+
+  const stepRegex = /<docs-step[^>]*title="([^"]*)"/g;
+  let match;
+  while ((match = stepRegex.exec(content)) !== null) {
+    headings.push(match[1]);
+  }
+
+  return headings.map((heading: string) => getIdFromHeading(heading));
+}
+
+function main() {
+  const allRoutes: string[] = [];
+
+  allRoutes.push(...extractRoutes(ALL_ITEMS));
+
+  const uniqueRoutes = Array.from(new Set(allRoutes.filter((r) => !!r)));
+
+  console.warn('Generated routes:', JSON.stringify(uniqueRoutes, null, 2));
+  writeFileSync(outputFile, JSON.stringify(uniqueRoutes, null, 2));
+}
+
+main();
+
+// TODO: refactor so this function is shared with the generation pipeline (adev/shared-docs/pipeline/shared/marked/transformations/heading.mts)
+function getIdFromHeading(heading: string): string {
+  return heading
+    .toLowerCase()
+    .replace(/\s|\//g, '-') // replace spaces and slashes with dashes
+    .replace(/[^\p{L}\d\-]/gu, ''); // only keep letters, digits & dashes
+}

adev/shared-docs/index.bzl

@@ -5,9 +5,15 @@ load("//adev/shared-docs/pipeline:_previews.bzl", _generate_previews = "generate
 load("//adev/shared-docs/pipeline:_stackblitz.bzl", _generate_stackblitz = "generate_stackblitz")
 load("//adev/shared-docs/pipeline:_tutorial.bzl", _generate_tutorial = "generate_tutorial")
 
-generate_guides = _generate_guides
 generate_stackblitz = _generate_stackblitz
 generate_previews = _generate_previews
 generate_playground = _generate_playground
 generate_tutorial = _generate_tutorial
 generate_nav_items = _generate_nav_items
+
+def generate_guides(**kwargs):
+    _generate_guides(
+        api_manifest = "//adev/src/assets:docs_api_manifest",
+        defined_routes = "//adev/scripts/routes:defined-routes.json",
+        **kwargs
+    )

adev/shared-docs/pipeline/_guides.bzl

@@ -22,6 +22,11 @@ def _generate_guides(ctx):
     else:
         args.add("")
 
+    if ctx.attr.defined_routes:
+        args.add(ctx.file.defined_routes.path)
+    else:
+        args.add("")
+
     # Determine the set of html output files. For each input markdown file, produce an html
     # file with the same name (replacing the markdown extension with `.html`).
     html_outputs = []
@@ -39,6 +44,8 @@ def _generate_guides(ctx):
     inputs = ctx.files.srcs + ctx.files.data
     if ctx.attr.api_manifest:
         inputs.append(ctx.file.api_manifest)
+    if ctx.attr.defined_routes:
+        inputs.append(ctx.file.defined_routes)
 
     if (ctx.attr.mermaid_blocks):
         ctx.actions.run(
@@ -85,6 +92,10 @@ generate_guides = rule(
             doc = """A file containing API entries to be used in the markdown.""",
             allow_single_file = True,
         ),
+        "defined_routes": attr.label(
+            doc = """List of defined routes.""",
+            allow_single_file = [".json"],
+        ),
         "mermaid_blocks": attr.bool(
             doc = """Whether to transform mermaid blocks.""",
             default = False,

adev/shared-docs/pipeline/api-gen/rendering/transforms/jsdoc-transforms.mts

@@ -109,6 +109,7 @@ function getHtmlForJsDocText(text: string): string {
   const parsed = parseMarkdown(mdToParse, {
     apiEntries: getSymbolsAsApiEntries(),
     highlighter: getHighlighterInstance(),
+    definedRoutes: [],
   });
   return addApiLinksToHtml(parsed);
 }

adev/shared-docs/pipeline/guides/index.mts

@@ -8,8 +8,8 @@
 
 import {readFile, writeFile} from 'fs/promises';
 import path from 'path';
-import {initHighlighter} from '../shared/shiki.mjs';
 import {parseMarkdownAsync} from '../shared/marked/parse.mjs';
+import {initHighlighter} from '../shared/shiki.mjs';
 import {hasUnknownAnchors} from './helpers.mjs';
 
 type ApiManifest = ApiManifestPackage[];
@@ -21,33 +21,45 @@ interface ApiManifestPackage {
 async function main() {
   const [paramFilePath] = process.argv.slice(2);
   const rawParamLines = (await readFile(paramFilePath, {encoding: 'utf8'})).split('\n');
-  const [srcs, outputFilenameExecRootRelativePath, apiManifestPath] = rawParamLines;
+  const [srcs, outputFilenameExecRootRelativePath, apiManifestPath, definedRoutesAsStr] =
+    rawParamLines;
 
   // The highlighter needs to be setup asynchronously
   // so we're doing it at the start of the pipeline
   const highlighter = await initHighlighter();
 
+  let apiManifest: ApiManifest = [];
+  if (!apiManifestPath) {
+    throw new Error(
+      'No API manifest path provided to the markdown parser. Check the failing generate_guides target.',
+    );
+  }
+
+  const apiManifestStr = await readFile(apiManifestPath, {encoding: 'utf8'});
+  apiManifest = JSON.parse(apiManifestStr);
+
+  let definedRoutes: string[] = [];
+  if (!definedRoutesAsStr) {
+    throw new Error(
+      'No defined routes path provided to the markdown parser. Check the failing generate_guides target.',
+    );
+  }
+
+  const definedGuideRoutes = await readFile(definedRoutesAsStr, {encoding: 'utf8'});
+  definedRoutes = JSON.parse(definedGuideRoutes) as string[];
+
   await Promise.all(
     srcs.split(',').map(async (filePath) => {
       if (!filePath.endsWith('.md')) {
         throw new Error(`Input file "${filePath}" does not end in a ".md" file extension.`);
       }
 
-      let apiManifest: ApiManifest = [];
-      if (apiManifestPath) {
-        try {
-          const apiManifestStr = await readFile(apiManifestPath, {encoding: 'utf8'});
-          apiManifest = JSON.parse(apiManifestStr);
-        } catch (error) {
-          console.warn('Failed to load API entries:', error);
-        }
-      }
-
       const markdownContent = await readFile(filePath, {encoding: 'utf8'});
       const htmlOutputContent = await parseMarkdownAsync(markdownContent, {
         markdownFilePath: filePath,
         apiEntries: mapManifestToEntries(apiManifest),
         highlighter,
+        definedRoutes,
       });
 
       // The expected file name structure is the [name of the file].md.html.

adev/shared-docs/pipeline/shared/marked/extensions/docs-pill/docs-pill.mts

@@ -8,6 +8,7 @@
 
 import {Token, Tokens, RendererThis, TokenizerThis} from 'marked';
 import {anchorTarget, isExternalLink} from '../../helpers.mjs';
+import {AdevDocsRenderer} from '../../renderer.mjs';
 
 interface DocsPillToken extends Tokens.Generic {
   type: 'docs-pill';
@@ -59,6 +60,14 @@ export const docsPillExtension = {
   renderer(this: RendererThis, token: DocsPillToken) {
     const downloadAttr = token.download ? ` download="${token.download}"` : '';
     const targetAttr = token.target ? ` target="${token.target}"` : anchorTarget(token.href);
+    const renderer = this.parser.renderer as AdevDocsRenderer;
+
+    if (!renderer.isKnownRoute(token.href)) {
+      throw new Error(
+        `Link target "${token.href}" is invalid in <docs-pill> in ${renderer.context.markdownFilePath} does not exist in the defined guide routes.`,
+      );
+    }
+
     return `
     <a class="docs-pill" href="${token.href}"${targetAttr}${downloadAttr}>
       ${this.parser.parseInline(token.tokens)}${