feat(tools,www): typed Content Graph with deterministic generate + fail-closed CI gate (#1157, B2.4)

Define the normalized entry/source-location/locale/reference/fingerprint
schemas (tools/lib/content-graph.ts) and the five Beta.2 adapters
(tools/lib/content-graph-adapters.ts): Markdown collections via the
adapter-vite collection loader, public API data from the PACKAGE_SURFACE.md
machine blocks, compiler metadata from the @openelement/ui generated
manifest, the roadmap timeline via the repo's TypeScript AST tooling, and
release truth from docs/release.

The generator (tools/generate-content-graph.ts) writes
www/app/data/_generated-content-graph.json deterministically (sorted
entries/alternates/references/keys; sha256 fingerprints) and --check is the
CI drift gate registered in the AutoFlow policy. Validation fails closed on
duplicate ids, broken entry/route references and false locale alternates
(orphan locales, asymmetric pairs, byte-identical 'translations').

Deterministic queries for doc routes, locale availability, search records
and per-route SEO metadata are exposed for the #1159 consumers.

Author: DevBot

deno.json

@@ -97,6 +97,8 @@
     "generate:ui-tokens:check": "deno run --allow-read tools/generate-ui-token-module.ts --check",
     "generate:ui-manifest": "deno task generate:ui-tokens && deno run --allow-read --allow-write --allow-env tools/generate-ui-manifest.ts",
     "generate:www-content-data": "deno run --allow-read --allow-write tools/generate-www-content-data.ts",
+    "generate:content-graph": "deno run --allow-read --allow-write --allow-env tools/generate-content-graph.ts",
+    "content-graph:check": "deno run --allow-read --allow-env tools/generate-content-graph.ts --check",
     "test:coverage": "deno test --coverage=.coverage --allow-read --allow-write --allow-env --allow-net --allow-run --allow-ffi --allow-sys && deno coverage .coverage --html && deno coverage .coverage --lcov > .coverage/lcov.info",
     "test:watch": "deno test --allow-read --allow-write --allow-env --allow-net --allow-run --watch",
     "test:e2e": "deno run -A npm:@playwright/test@1.59.1 test --config www/e2e/playwright.config.ts --project=chromium",

tools/autoflow/policy.ts

@@ -208,6 +208,28 @@ const GATES: readonly GateDefinition[] = [
     tiers: ['ci', 'release'],
     triggers: [/^www\//, /^docs\//, /^tools\/project-constants\.ts$/],
   },
+  {
+    // #1157 (B2.4): typed Content Graph drift gate — the committed
+    // _generated-content-graph.json must be a byte-identical regeneration of
+    // the owned Markdown/API/compiler-metadata/roadmap/release sources, and
+    // the graph must validate (duplicate ids, broken references and false
+    // locale alternates fail closed inside the generator).
+    name: 'content-graph:check',
+    command: ['deno', 'task', 'content-graph:check'],
+    tiers: ['ci', 'release'],
+    triggers: [
+      /^www\/content\//,
+      /^www\/content-collections\.ts$/,
+      /^www\/app\/routes\//,
+      /^www\/app\/data\/_generated-content-graph\.json$/,
+      /^docs\/current\/PACKAGE_SURFACE\.md$/,
+      /^docs\/roadmap\/ROADMAP\.md$/,
+      /^docs\/release\//,
+      /^packages\/ui\/src\/generated-manifest\.json$/,
+      /^tools\/(?:lib\/content-graph|generate-content-graph|check-package-surface)/,
+      /^deno\.json$/,
+    ],
+  },
   {
     name: 'docs:check-version-anchors',
     command: ['deno', 'task', 'docs:check-version-anchors'],

tools/check-package-surface.ts

@@ -53,7 +53,7 @@ function normalizeExports(exports: unknown): Record<string, string> {
   );
 }
 
-interface SurfaceMapEntry {
+export interface SurfaceMapEntry {
   supported: string[];
   internal: string[];
 }
@@ -62,7 +62,7 @@ function isStringArray(value: unknown): value is string[] {
   return Array.isArray(value) && value.every((item) => typeof item === 'string');
 }
 
-function extractSurfaceMap(doc: string): Record<string, SurfaceMapEntry> | null {
+export function extractSurfaceMap(doc: string): Record<string, SurfaceMapEntry> | null {
   const BEGIN = '<!-- package-surface-map';
   const begin = doc.indexOf(BEGIN);
   if (begin === -1) return null;

tools/generate-content-graph.ts

@@ -0,0 +1,55 @@
+/**
+ * Typed Content Graph generator (#1157, B2.4).
+ *
+ * Default mode builds the graph from the owned sources (Markdown collections,
+ * PACKAGE_SURFACE.md API blocks, the @openelement/ui compiler manifest, the
+ * roadmap route timeline and release truth) and writes
+ * www/app/data/_generated-content-graph.json. `--check` regenerates and
+ * requires byte-identical output — the CI drift gate.
+ *
+ * Validation fails closed on duplicate ids, broken entry/route references
+ * and false locale alternates, in both modes.
+ */
+import { buildContentGraph, scanPublicRoutes, SITE_LOCALES } from './lib/content-graph-adapters.ts';
+import { serializeContentGraph, validateContentGraph } from './lib/content-graph.ts';
+
+export const CONTENT_GRAPH_ARTIFACT = 'www/app/data/_generated-content-graph.json';
+
+export async function generateContentGraphJson(): Promise<string> {
+  const graph = await buildContentGraph();
+  const routes = await scanPublicRoutes();
+  const failures = validateContentGraph(graph, { routes, locales: SITE_LOCALES });
+  if (failures.length > 0) {
+    console.error('Content graph validation failed:');
+    for (const failure of failures) {
+      console.error(`- ${failure.file}: ${failure.message}`);
+    }
+    throw new Error(`content graph invalid: ${failures.length} failure(s)`);
+  }
+  return serializeContentGraph(graph);
+}
+
+if (import.meta.main) {
+  const check = Deno.args.includes('--check');
+  const json = await generateContentGraphJson();
+  if (check) {
+    let existing: string;
+    try {
+      existing = await Deno.readTextFile(CONTENT_GRAPH_ARTIFACT);
+    } catch {
+      console.error(`${CONTENT_GRAPH_ARTIFACT} is missing; run deno task generate:content-graph`);
+      Deno.exit(1);
+    }
+    if (existing !== json) {
+      console.error(
+        `${CONTENT_GRAPH_ARTIFACT} is stale; run deno task generate:content-graph and commit the result`,
+      );
+      Deno.exit(1);
+    }
+    console.log(`Content graph check passed (${CONTENT_GRAPH_ARTIFACT} is byte-identical).`);
+  } else {
+    await Deno.writeTextFile(CONTENT_GRAPH_ARTIFACT, json);
+    const entries = (json.match(/"id":/g) ?? []).length;
+    console.log(`Wrote ${entries} entries to ${CONTENT_GRAPH_ARTIFACT}`);
+  }
+}

tools/lib/content-graph-adapters.test.ts

@@ -0,0 +1,83 @@
+/** Content Graph adapter + generator integration tests (#1157). */
+import { assert, assertEquals } from '@std/assert';
+import {
+  extractMarkdownReferences,
+  extractRoadmapTimeline,
+  scanPublicRoutes,
+} from './content-graph-adapters.ts';
+import { generateContentGraphJson } from '../generate-content-graph.ts';
+import type { ContentGraph } from './content-graph.ts';
+
+Deno.test('extractMarkdownReferences: classifies internal links, skips external and fragments', () => {
+  const content = [
+    'See [the guide](/guide/getting-started) and [localized](/zh/guide/api#x).',
+    'Relative [peer](./other.md) and [translation](other.zh.md) plus [anchor](#top).',
+    'External [site](https://example.com/docs) and [mail](mailto:a@b.c) are skipped.',
+    '[ref]: /architecture/islands',
+  ].join('\n');
+  const references = extractMarkdownReferences(
+    content,
+    (target) =>
+      target.startsWith('/')
+        ? { kind: 'route', target }
+        : { kind: 'entry', target: `article:guide/${target.replace(/\.mdx?$/, '')}` },
+  );
+  assertEquals(references, [
+    { kind: 'route', target: '/guide/getting-started', line: 1 },
+    { kind: 'route', target: '/zh/guide/api', line: 1 },
+    { kind: 'entry', target: 'article:guide/./other', line: 2 },
+    { kind: 'entry', target: 'article:guide/other.zh', line: 2 },
+    { kind: 'route', target: '/architecture/islands', line: 4 },
+  ]);
+});
+
+Deno.test('extractRoadmapTimeline: reads the bilingual timeline through the TS AST', () => {
+  const source = `
+const entries: Record<'en' | 'zh', TimelineEntry[]> = {
+  en: [
+    { version: 'v0.44.0-beta.1', theme: 'qualification', copy: 'English copy.', state: 'next', stamp: 'CURRENT', status: 'prerelease' },
+  ],
+  zh: [
+    { version: 'v0.44.0-beta.1', theme: '限定', copy: '中文文案。', state: 'next', stamp: 'CURRENT', status: 'prerelease' },
+  ],
+};
+`;
+  const timeline = extractRoadmapTimeline(source);
+  assertEquals(Object.keys(timeline).sort(), ['en', 'zh']);
+  assertEquals(timeline.en.length, 1);
+  assertEquals(timeline.en[0].version, 'v0.44.0-beta.1');
+  assertEquals(timeline.en[0].stamp, 'CURRENT');
+  assertEquals(timeline.zh[0].copy, '中文文案。');
+  assertEquals(timeline.en[0].line > 0, true);
+});
+
+Deno.test('scanPublicRoutes: discovers the real www route universe', async () => {
+  const routes = await scanPublicRoutes();
+  for (const expected of ['/guide/getting-started', '/roadmap', '/apilist', '/changelog']) {
+    assert(routes.includes(expected), `missing route ${expected}`);
+  }
+  assert(routes.every((route) => !route.includes(':')), 'dynamic segments must be excluded');
+});
+
+Deno.test('generateContentGraphJson: real repo sources produce a valid deterministic graph', async () => {
+  const first = await generateContentGraphJson();
+  const second = await generateContentGraphJson();
+  assertEquals(first, second);
+
+  const graph = JSON.parse(first) as ContentGraph;
+  const ids = new Set(graph.entries.map((entry) => entry.id));
+  // Every adapter contributes: markdown, public API data, compiler metadata,
+  // roadmap and release truth.
+  assert(ids.has('article:guide/getting-started:en'), 'markdown adapter missing');
+  assert(ids.has('api:@openelement/element'), 'api adapter missing');
+  assert(ids.has('element:open-dialog'), 'compiler metadata adapter missing');
+  assert(ids.has('roadmap:en:0'), 'roadmap adapter missing');
+  assert(ids.has('release:state'), 'release adapter missing');
+
+  // Locale pairs are symmetric and translated.
+  const en = graph.entries.find((entry) => entry.id === 'article:guide/getting-started:en');
+  const zh = graph.entries.find((entry) => entry.id === 'article:guide/getting-started:zh');
+  assert(en && zh, 'guide locale pair missing');
+  assertEquals(en.alternates, [{ locale: 'zh', id: 'article:guide/getting-started:zh' }]);
+  assertEquals(zh.alternates, [{ locale: 'en', id: 'article:guide/getting-started:en' }]);
+});