test(@angular/cli): add CI validation for MCP example code

.github/workflows/pr.yml

@@ -59,6 +59,8 @@ jobs:
         uses: angular/dev-infra/github-actions/linting/licenses@5043638fd8529765b375831a4679b9013141b326
       - name: Check tooling setup
         run: pnpm check-tooling-setup
+      - name: Validate MCP Example Markdown
+        run: pnpm check-mcp-examples
       - name: Check commit message
         # Commit message validation is only done on pull requests as its too late to validate once
         # it has been merged.

docs/FIND_EXAMPLES_FORMAT.md

@@ -0,0 +1,75 @@
+# Angular CLI MCP Example Format Specification
+
+This document specifies the "knowledge packet" format for all markdown examples used by the `find_examples` MCP tool. The goal of this format is to provide a rich, structured, and unambiguous source of information for an AI model, enabling it to understand, apply, and generate code based on modern Angular best practices.
+
+The format is optimized for both keyword-based full-text search and modern semantic search via a vector database.
+
+## File Structure
+
+Each example must be a single `.md` file containing YAML front matter and a structured markdown body.
+
+### 1. YAML Front Matter
+
+The front matter provides machine-readable metadata about the example.
+
+- **`title`** (string, required): A clear, human-readable title for the example (e.g., `Signal Form with Cross-Field Validation`).
+- **`summary`** (string, required): A dense, one-sentence, factual description of what the code demonstrates. This field is the primary target for vector database embeddings.
+- **`keywords`** (string[], required): A list of keywords and concepts for full-text search. Include APIs, function names, and conceptual terms (e.g., `conditional rendering`).
+- **`required_packages`** (string[], optional): A list of NPM packages required for the example to work, excluding `@angular/core`. This is for dependencies that may not be installed (e.g., `@angular/forms`, `@angular/material`).
+- **`related_concepts`** (string[], optional): A list of other high-level concepts that are related to this example.
+- **`related_tools`** (string[], optional): A list of other MCP tools that are related to this example (e.g., `modernize`).
+- **`experimental`** (boolean, optional, default: `false`): When set to `true`, indicates that the example demonstrates an experimental or unstable API that may not be suitable for production use.
+
+### 2. Markdown Body
+
+The body provides human-readable and AI-parsable context. It must follow this exact structure and heading order.
+
+#### `## Purpose`
+
+- **Content:** A high-level, conceptual explanation of the "why" behind the pattern. It should answer: "What problem does this pattern solve in an application?"
+
+#### `## When to Use`
+
+- **Content:** A description of the specific scenarios where this pattern is the preferred best practice. If it supersedes an older pattern, that should be mentioned here (e.g., `@if` vs. `*ngIf`).
+
+#### `## Key Concepts`
+
+- **Content:** A bulleted list explaining the main APIs, functions, or decorators demonstrated in the code. Each item should be in the format: `- **`functionName()`:** A brief explanation.`
+
+#### `## Example Files`
+
+- **Content:** This section contains the code for the example, structured as a "file-set."
+- **Structure:**
+      - It must start with a brief, one-sentence description of the file-set.
+      - Each file within the set must be introduced with a `### filename.ext` heading.
+      - Each file heading must be followed by a one-sentence description of that file's role.
+      - Each file description must be followed by a fenced code block with the appropriate language identifier (e.g., `typescript`, `html`, `css`).
+- **Best Practice:** Examples should be self-contained and runnable, preferably using a `standalone` component.
+
+#### `## Usage Notes`
+
+- **Content:** A bulleted list of important details, nuances, or rules about the _internal implementation_ of the code in the `Example Files` section.
+
+#### `## How to Use This Example`
+
+- **Content:** A "recipe" that explains how to consume or integrate the example into a larger application. This section is critical for code generation.
+- **Structure:** It should contain one or more numbered subheadings (e.g., `### 1. Import the Component`) that provide step-by-step instructions, including code blocks.
+- **Flexibility:** The content of this section should be tailored to the type of entity being demonstrated (component, service, pipe, route configuration, etc.).
+- **Optional:** This section may not be needed for all examples
+
+## Search and Embedding Strategy
+
+This format is designed to be consumed by a sophisticated search system.
+
+### Keyword Search (FTS)
+
+The `keywords` field is the primary target for the full-text search engine. The content of the entire document is also indexed.
+
+### Vector Search (Semantic Search)
+
+For optimal RAG (Retrieval-Augmented Generation) performance, the document should be chunked before being embedded into a vector database.
+
+- **Chunking Strategy:**
+      1.  The `summary` field from the front matter should be treated as the primary, document-level chunk and receive its own embedding.
+      2.  Each major markdown section (`## Purpose`, `## When to Use`, `## Key Concepts`, `## Example Files`, `## Usage Notes`, `## How to Use This Example`) should be treated as a separate chunk and receive its own embedding.
+- **Metadata:** The full YAML front matter (`title`, `keywords`, `required_packages`, etc.) must be stored as metadata alongside every vector in the database. This allows for powerful post-retrieval filtering and provides the LLM with the full context after a chunk has been identified via semantic search.

package.json

@@ -26,6 +26,7 @@
     "public-api:update": "node goldens/public-api/manage.js accept",
     "ts-circular-deps": "pnpm -s ng-dev ts-circular-deps --config ./scripts/circular-deps-test.conf.mjs",
     "check-tooling-setup": "tsc --project .ng-dev/tsconfig.json",
+    "check-mcp-examples": "node tools/process_examples.mjs packages/angular/cli/lib/examples --mode validate-structure",
     "diff-release-package": "node --no-warnings=ExperimentalWarning --loader ts-node/esm/transpile-only scripts/diff-release-package.mts"
   },
   "repository": {
@@ -124,6 +125,7 @@
     "listr2": "9.0.3",
     "lodash": "^4.17.21",
     "magic-string": "0.30.19",
+    "marked": "^16.2.1",
     "npm": "^11.0.0",
     "prettier": "^3.0.0",
     "protractor": "~7.0.0",

tools/BUILD.bazel

@@ -34,8 +34,9 @@ js_binary(
 js_binary(
     name = "ng_example_db",
     data = [
-        "example_db_generator.js",
+        "process_examples.mjs",
+        "//:node_modules/marked",
         "//:node_modules/zod",
     ],
-    entry_point = "example_db_generator.js",
+    entry_point = "process_examples.mjs",
 )

tools/example-validation-harness/angular.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "./node_modules/@angular/cli/lib/config/schema.json",
+  "version": 1,
+  "newProjectRoot": "projects",
+  "projects": {
+    "validation-harness": {
+      "projectType": "application",
+      "root": "",
+      "sourceRoot": "src",
+      "prefix": "app",
+      "architect": {
+        "build": {
+          "builder": "@angular/build:application",
+          "options": {
+            "outputPath": "dist/validation-harness",
+            "index": "src/index.html",
+            "browser": "src/main.ts",
+            "polyfills": ["zone.js"],
+            "tsConfig": "tsconfig.app.json",
+            "assets": [],
+            "styles": [],
+            "scripts": []
+          }
+        }
+      }
+    }
+  }
+}

tools/example-validation-harness/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "example-validation-harness",
+  "version": "0.0.0",
+  "private": true,
+  "dependencies": {
+    "@angular/common": "^21.0.0-next",
+    "@angular/compiler": "^21.0.0-next",
+    "@angular/core": "^21.0.0-next",
+    "@angular/forms": "^21.0.0-next",
+    "@angular/platform-browser": "^21.0.0-next",
+    "rxjs": "~7.8.0",
+    "tslib": "^2.3.0",
+    "zone.js": "~0.15.0"
+  },
+  "devDependencies": {
+    "@angular/build": "^21.0.0-next",
+    "@angular/cli": "^21.0.0-next",
+    "@angular/compiler-cli": "^21.0.0-next",
+    "typescript": "~5.9.2"
+  }
+}

tools/example-validation-harness/src/app/app.ts

@@ -0,0 +1,16 @@
+/**
+ * @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 { Component } from '@angular/core';
+
+@Component({
+  selector: 'app-root',
+  imports: [],
+  template: '',
+})
+export class App {}

tools/example-validation-harness/src/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <title>ValidationHarness</title>
+  <base href="/">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <link rel="icon" type="image/x-icon" href="favicon.ico">
+</head>
+<body>
+  <app-root></app-root>
+</body>
+</html>

tools/example-validation-harness/src/main.ts

@@ -0,0 +1,12 @@
+/**
+ * @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 { bootstrapApplication } from '@angular/platform-browser';
+import { App } from './app/app';
+
+bootstrapApplication(App).catch((err) => console.error(err));

tools/example-validation-harness/tsconfig.app.json

@@ -0,0 +1,9 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./out-tsc/app",
+    "types": []
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["src/**/*.spec.ts"]
+}

tools/example-validation-harness/tsconfig.json

@@ -0,0 +1,29 @@
+{
+  "compileOnSave": false,
+  "compilerOptions": {
+    "strict": true,
+    "noImplicitOverride": true,
+    "noPropertyAccessFromIndexSignature": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "skipLibCheck": true,
+    "isolatedModules": true,
+    "experimentalDecorators": true,
+    "importHelpers": true,
+    "target": "ES2022",
+    "module": "preserve"
+  },
+  "angularCompilerOptions": {
+    "enableI18nLegacyMessageIdFormat": false,
+    "strictInjectionParameters": true,
+    "strictInputAccessModifiers": true,
+    "typeCheckHostBindings": true,
+    "strictTemplates": true
+  },
+  "files": [],
+  "references": [
+    {
+      "path": "./tsconfig.app.json"
+    }
+  ]
+}

tools/example_db_generator.bzl

@@ -8,5 +8,5 @@ def cli_example_db(name, srcs, path, out, data = []):
         tool = "//tools:ng_example_db",
         progress_message = "Generating code example database from %s" % path,
         mnemonic = "NgExampleSqliteDb",
-        args = [path, "$(rootpath %s)" % out],
+        args = ["--mode generate-db", "--output $(rootpath %s)" % out, path],
     )