feat(tools,www): drive www nav/locale/link/SEO truth from owned sources with fail-closed gates (#1159, B2.4)

- tools/check-www-links.ts + tools/lib/www-links.ts: built-output internal
  link/fragment gate over www/dist (every internal href/src resolves to a
  built file; every #fragment anchors; every sitemap.xml URL resolves) plus
  per-page SEO invariants (exactly one <title>, non-trivial meta
  description, og:title). Wired into the build task so the CI build gate
  fails on broken links. First run found and this change fixes real broken
  links: CHANGELOG.md's repository-relative links are now projected onto
  the canonical GitHub tree at the changelog route's render seam.
- tools/check-www-truth.ts: the remaining hand-maintained surfaces must
  mechanically agree with owned truth — _generated-nav.ts byte-identical
  regeneration of route meta + vite.config headerNav (read through the TS
  AST), headerNav hrefs resolve to scanned routes, bilingual locale
  availability (orphan/missing zh and byte-identical en/zh pairs fail), and
  the CURRENT roadmap entry names the package version tag.
- tools/check-content-examples.ts: ts/tsx guide examples importing
  @openelement/* type-check against the real framework sources (en/zh
  duplicates deduped); only documented snippet elision (consumer-project
  imports, elided app names, implicit any, the uninferred loader-data
  generic) is suppressed — framework-surface errors fail closed.
- AutoFlow policy: www:check-truth and content:examples-check registered
  (ci + release tiers); the build gate's triggers cover the link checker.

Version constants and release-state agreement were already pinned by
docs:check-version-anchors / release:truth:check; this composes with them
instead of duplicating. Scheduled external link checks stay deferred to
Beta.3 under #1156 (workflow cap 8 — no ninth workflow added).

Author: DevBot

deno.json

@@ -38,7 +38,7 @@
   "tasks": {
     "dev": "cd www && deno run --allow-read --allow-write --allow-net --allow-env --allow-ffi --allow-sys npm:vite --config vite.config.ts",
     "www:dev-smoke": "deno run --allow-net --allow-run tools/smoke-www-dev.ts",
-    "build": "deno task generate:ui-manifest && (cd www && deno run --config ../deno.json --allow-read --allow-write --allow-net --allow-env --allow-ffi --allow-sys --allow-run ../packages/adapter-vite/src/cli/build.ts) && deno task www:pagefind && deno task www:check-artifact-truth",
+    "build": "deno task generate:ui-manifest && (cd www && deno run --config ../deno.json --allow-read --allow-write --allow-net --allow-env --allow-ffi --allow-sys --allow-run ../packages/adapter-vite/src/cli/build.ts) && deno task www:pagefind && deno task www:check-artifact-truth && deno task www:check-links",
     "www:pagefind": "cd www && deno run --config ../deno.json --allow-read --allow-write --allow-run --allow-env --allow-net --allow-ffi --allow-sys build-pagefind.ts",
     "preview": "cd www && deno run --allow-read --allow-write --allow-net --allow-env --allow-ffi npm:vite preview --config vite.config.ts",
     "workflow:check": "deno run --allow-read --allow-run=git tools/check-project-workflow.ts && deno task v044:orchestration:check",
@@ -62,6 +62,9 @@
     "www:check-current-truth": "deno run --allow-read tools/check-docs-truth.ts --check=www",
     "www:check-theme-tokens": "deno run --allow-read tools/check-www-theme-tokens.ts",
     "www:check-artifact-truth": "deno run --allow-read tools/check-docs-truth.ts --check=www --artifacts",
+    "www:check-links": "deno run --allow-read tools/check-www-links.ts",
+    "www:check-truth": "deno run --allow-read --allow-env tools/check-www-truth.ts",
+    "content:examples-check": "deno run --allow-read --allow-write --allow-env tools/check-content-examples.ts",
     "package-surface:check": "deno run --allow-read --allow-env tools/check-package-surface.ts",
     "interface:snapshot": "deno run --allow-read --allow-env tools/check-public-interface-snapshot.ts",
     "interface:snapshot:write": "deno run --allow-read --allow-write --allow-env tools/check-public-interface-snapshot.ts --write",

tools/autoflow/policy.ts

@@ -208,6 +208,34 @@ const GATES: readonly GateDefinition[] = [
     tiers: ['ci', 'release'],
     triggers: [/^www\//, /^docs\//, /^tools\/project-constants\.ts$/],
   },
+  {
+    // #1159 (B2.4): hand-maintained www surfaces must mechanically agree with
+    // owned truth — generated nav freshness (byte-identical regeneration of
+    // route meta + headerNav), headerNav hrefs resolve to real routes,
+    // bilingual locale availability (no orphan/missing/duplicated-untranslated
+    // zh), and the CURRENT roadmap entry names the package version tag.
+    name: 'www:check-truth',
+    command: ['deno', 'task', 'www:check-truth'],
+    tiers: ['ci', 'release'],
+    triggers: [
+      /^www\/(content|app\/routes|app\/data\/_generated-nav\.ts|vite\.config\.ts)/,
+      /^tools\/(?:check-www-truth|project-constants)/,
+      /^deno\.json$/,
+    ],
+  },
+  {
+    // #1159 (B2.4): guide/architecture code examples that import
+    // @openelement/* must type-check against the real framework sources.
+    name: 'content:examples-check',
+    command: ['deno', 'task', 'content:examples-check'],
+    tiers: ['ci', 'release'],
+    triggers: [
+      /^www\/content\//,
+      /^packages\//,
+      /^tools\/check-content-examples/,
+      /^deno\.json$/,
+    ],
+  },
   {
     name: 'docs:check-version-anchors',
     command: ['deno', 'task', 'docs:check-version-anchors'],
@@ -364,7 +392,13 @@ const GATES: readonly GateDefinition[] = [
     name: 'build',
     command: ['deno', 'task', 'build'],
     tiers: ['ci', 'release'],
-    triggers: [/^(packages|www)\//, /^deno\.json$/],
+    // #1159: the build task ends with the built-output internal
+    // link/fragment + SEO gate (www:check-links), so checker edits rebuild.
+    triggers: [
+      /^(packages|www)\//,
+      /^deno\.json$/,
+      /^tools\/(?:check-www-links|lib\/www-links)/,
+    ],
   },
   {
     // Runs after build when both gates are selected. check-coverage keeps a

tools/check-content-examples.test.ts

@@ -0,0 +1,107 @@
+/** Content example type-check gate tests (#1159). */
+import { assert, assertEquals } from '@std/assert';
+import {
+  extractExamples,
+  suppressElidedDiagnostic,
+  typeCheckExamples,
+} from './check-content-examples.ts';
+import ts from 'typescript';
+
+Deno.test('extractExamples: only fenced ts/tsx blocks importing @openelement', () => {
+  const markdown = [
+    '```ts',
+    "import { signal } from '@openelement/element';",
+    'const count = signal(0);',
+    '```',
+    '```bash',
+    'deno task dev',
+    '```',
+    '```ts',
+    "import { defineConfig } from 'vite';",
+    '```',
+    '```tsx',
+    "import { OpenElement } from '@openelement/element';",
+    'export class X extends OpenElement {}',
+    '```',
+  ].join('\n');
+  const examples = extractExamples('guide/x.md', markdown);
+  assertEquals(examples.length, 2);
+  assertEquals(examples[0].lang, 'ts');
+  assertEquals(examples[1].lang, 'tsx');
+});
+
+Deno.test('typeCheckExamples: framework-surface errors fail closed (RED proof)', async () => {
+  const failures = await typeCheckExamples([
+    {
+      file: 'fixture.md',
+      index: 0,
+      lang: 'ts',
+      code: "import { noSuchExport } from '@openelement/element';\nconsole.log(noSuchExport);",
+    },
+  ]);
+  assertEquals(failures.length, 1);
+  assert(failures[0].message.includes('TS2305'), failures[0].message);
+});
+
+Deno.test('typeCheckExamples: unknown @openelement module fails closed', async () => {
+  const failures = await typeCheckExamples([
+    {
+      file: 'fixture.md',
+      index: 0,
+      lang: 'ts',
+      code: "import { x } from '@openelement/no-such-package';\nconsole.log(x);",
+    },
+  ]);
+  assertEquals(failures.length, 1);
+  assert(failures[0].message.includes('TS2307'), failures[0].message);
+});
+
+Deno.test('typeCheckExamples: elided consumer context is tolerated, real API checks apply', async () => {
+  const failures = await typeCheckExamples([
+    {
+      file: 'fixture.md',
+      index: 0,
+      lang: 'ts',
+      code: [
+        "import { signal } from '@openelement/element';",
+        "import GuestbookPage from '../components/page-guestbook.tsx'; // consumer file, elided",
+        'const count = signal(0);',
+        'count.value += 1;',
+        'console.log(GuestbookPage, missingAppHelper());',
+        '',
+      ].join('\n'),
+    },
+  ]);
+  assertEquals(failures, []);
+});
+
+Deno.test('suppressElidedDiagnostic: suppression boundary is exact', () => {
+  const make = (code: number, messageText: string): ts.Diagnostic => ({
+    file: undefined,
+    start: 0,
+    length: 0,
+    code,
+    messageText,
+    category: ts.DiagnosticCategory.Error,
+    source: undefined,
+  });
+  assertEquals(suppressElidedDiagnostic(make(2307, "Cannot find module 'vite'.")), true);
+  assertEquals(
+    suppressElidedDiagnostic(make(2307, "Cannot find module '@openelement/generated/blog-data'.")),
+    true,
+  );
+  assertEquals(
+    suppressElidedDiagnostic(make(2307, "Cannot find module '@openelement/element'.")),
+    false,
+  );
+  assertEquals(suppressElidedDiagnostic(make(2304, "Cannot find name 'listEntries'.")), true);
+  assertEquals(
+    suppressElidedDiagnostic(make(2339, "Property 'entries' does not exist on type '{}'.")),
+    true,
+  );
+  assertEquals(
+    suppressElidedDiagnostic(make(2339, "Property 'x' does not exist on type 'OpenElement'.")),
+    false,
+  );
+  assertEquals(suppressElidedDiagnostic(make(2345, 'Argument of type ...')), false);
+});

tools/check-content-examples.ts

@@ -0,0 +1,178 @@
+/**
+ * Content example type-check gate (#1159, B2.4): TypeScript/TSX fenced code
+ * blocks in the authored bilingual guides that import `@openelement/*` must
+ * type-check against the real v0.44 framework sources. zh duplicates of an
+ * en block are deduped by content. Fails closed with compiler diagnostics.
+ *
+ * Elision convention: guide snippets are written as consumer-project modules
+ * and legitimately omit application context. The harness therefore suppresses
+ * only the diagnostics that express that elision — unresolved non-framework
+ * module specifiers (TS2307 outside `@openelement/*`; the virtual
+ * `@openelement/generated/*` namespace is adapter-generated consumer code),
+ * undefined names from elided app code (TS2304), implicit-any (TS7006) and
+ * property access on the uninferred loader-data generic (TS2339 on `{}`).
+ * Everything on the framework surface — unknown `@openelement` modules or
+ * exports, argument/assignability errors against real APIs, syntax and JSX
+ * errors — fails the gate.
+ */
+import ts from 'typescript';
+import { walk } from '@std/fs/walk';
+import { readPackages } from './lib/package-graph.ts';
+
+export interface ExampleFailure {
+  file: string;
+  message: string;
+}
+
+export interface ContentExample {
+  /** First source document the block was found in. */
+  file: string;
+  index: number;
+  lang: string;
+  code: string;
+}
+
+const FENCE_PATTERN = /```(ts|tsx)\n([\s\S]*?)```/g;
+
+/** Extract unique ts/tsx fenced blocks that import @openelement packages. */
+export function extractExamples(file: string, markdown: string): ContentExample[] {
+  const examples: ContentExample[] = [];
+  for (const match of markdown.matchAll(FENCE_PATTERN)) {
+    const code = match[2];
+    if (!code.includes('@openelement/')) continue;
+    examples.push({ file, index: examples.length, lang: match[1], code });
+  }
+  return examples;
+}
+
+/** Build a paths map resolving workspace @openelement/* specifiers to files. */
+export async function workspacePaths(): Promise<Record<string, string[]>> {
+  const paths: Record<string, string[]> = {};
+  for (const pkg of await readPackages()) {
+    const entries = typeof pkg.exports === 'string'
+      ? { '.': pkg.exports }
+      : (pkg.exports ?? {}) as Record<string, string>;
+    for (const [key, target] of Object.entries(entries)) {
+      if (typeof target !== 'string') continue;
+      const specifier = key === '.' ? pkg.name : `${pkg.name}/${key.replace(/^\.\//, '')}`;
+      paths[specifier] = [`${pkg.dir}/${target.replace(/^\.\//, '')}`];
+    }
+  }
+  return paths;
+}
+
+/**
+ * Type-check the given example blocks against the real framework. Each block
+ * is compiled as its own module in one shared program so diagnostics carry
+ * the example's virtual file name.
+ */
+export async function typeCheckExamples(examples: ContentExample[]): Promise<ExampleFailure[]> {
+  if (examples.length === 0) return [];
+  // The temp dir must live inside the workspace so node_modules resolution
+  // (vite, preact, ...) walks up to the repo's dependencies.
+  const dir = await Deno.makeTempDir({ dir: '.tmp', prefix: 'content-examples-' });
+  try {
+    const files: string[] = [];
+    for (const [index, example] of examples.entries()) {
+      const name = `example-${index}.${example.lang}`;
+      await Deno.writeTextFile(`${dir}/${name}`, example.code);
+      files.push(`${dir}/${name}`);
+    }
+    const paths = await workspacePaths();
+    const options: ts.CompilerOptions = {
+      allowImportingTsExtensions: true,
+      experimentalDecorators: true,
+      jsx: ts.JsxEmit.ReactJSX,
+      jsxImportSource: '@openelement/element',
+      module: ts.ModuleKind.ESNext,
+      moduleResolution: ts.ModuleResolutionKind.Bundler,
+      noEmit: true,
+      skipLibCheck: true,
+      strict: true,
+      target: ts.ScriptTarget.ESNext,
+      baseUrl: Deno.cwd(),
+      paths,
+      // Doc snippets are teaching material, not shippable modules: unused
+      // locals and missing return-type annotations are not defects there.
+      noUnusedLocals: false,
+      noUnusedParameters: false,
+    };
+    const program = ts.createProgram(files, options);
+    const failures: ExampleFailure[] = [];
+    for (const [index, file] of files.entries()) {
+      const source = program.getSourceFile(file);
+      if (!source) {
+        failures.push({ file: examples[index].file, message: 'example failed to parse' });
+        continue;
+      }
+      const diagnostics = [
+        ...program.getSyntacticDiagnostics(source),
+        ...program.getSemanticDiagnostics(source),
+      ];
+      for (const diagnostic of diagnostics) {
+        if (suppressElidedDiagnostic(diagnostic)) continue;
+        const position = diagnostic.file?.getLineAndCharacterOfPosition(diagnostic.start ?? 0);
+        failures.push({
+          file: `${examples[index].file} (block ${examples[index].index + 1})`,
+          message: `TS${diagnostic.code} at line ${(position?.line ?? 0) + 1}: ${
+            ts.flattenDiagnosticMessageText(diagnostic.messageText, ' ')
+          }`,
+        });
+      }
+    }
+    return failures;
+  } finally {
+    await Deno.remove(dir, { recursive: true });
+  }
+}
+
+/**
+ * Elided-context suppression (see the module header): returns true only for
+ * diagnostics that express documented snippet elision, never framework-surface
+ * errors.
+ */
+export function suppressElidedDiagnostic(diagnostic: ts.Diagnostic): boolean {
+  const text = ts.flattenDiagnosticMessageText(diagnostic.messageText, ' ');
+  if (diagnostic.code === 2307) {
+    // Unresolved module: only framework modules are harness truth. The
+    // `@openelement/generated/*` namespace is adapter-emitted consumer code.
+    if (/Cannot find module '@openelement\/(?!generated\/)/.test(text)) return false;
+    return true;
+  }
+  // Undefined names from elided application code.
+  if (diagnostic.code === 2304) return true;
+  // Implicit-any in teaching snippets.
+  if (diagnostic.code === 7006) return true;
+  // Property access on the uninferred loader-data generic (`{}`).
+  if (diagnostic.code === 2339 && text.includes(`on type '{}'`)) return true;
+  return false;
+}
+
+export async function checkContentExamples(): Promise<ExampleFailure[]> {
+  const seen = new Set<string>();
+  const examples: ContentExample[] = [];
+  for (const dir of ['www/content/guide', 'www/content/architecture']) {
+    for await (const entry of walk(dir, { includeDirs: false, exts: ['.md'] })) {
+      const markdown = await Deno.readTextFile(entry.path);
+      for (const example of extractExamples(entry.path, markdown)) {
+        // en/zh translations carry identical code — check each block once.
+        if (seen.has(example.code)) continue;
+        seen.add(example.code);
+        examples.push(example);
+      }
+    }
+  }
+  return await typeCheckExamples(examples);
+}
+
+if (import.meta.main) {
+  const failures = await checkContentExamples();
+  if (failures.length > 0) {
+    console.error('Content example type-check failed:');
+    for (const failure of failures) {
+      console.error(`- ${failure.file}: ${failure.message}`);
+    }
+    Deno.exit(1);
+  }
+  console.log('Content example type-check passed.');
+}