Validate the complete documentation graph

Compose catalog validation with canonical page, local link, semantic-code link, and heading-fragment checks across every compiler-owned reference page. Snapshot the ordered graph and verify exact page parity through native LSP, packaged desktop and browser workers, and the VS Code web host.

Author: CryZe

TODO.md

@@ -47,10 +47,6 @@ VS Code opens the index beside a script, supports search, breadcrumbs, links,
 and compiler-derived semantic code. Keep that working base and finish the
 missing graph rather than rebuilding the viewer.
 
-- [ ] Cover the documentation graph and reference contract with catalog
-  validation, link checking, deterministic snapshots, native/bundled-server
-  parity, and VS Code desktop/web integration tests. Missing documentation or
-  broken related-symbol and migration links should fail the repository check.
 - [ ] Finish semantic code in generated reference pages. Signatures now use
   catalog identities for syntax coloring and navigation, and examples can use
   rustdoc-style hidden `# ` fixture lines so the compiler can map exact

docs/COMPILER.md

@@ -1165,6 +1165,15 @@ only that one command in language-server Markdown, and the command opens the
 exact page beside the script; other command URIs remain inert. Standard-library
 and language go-to-definition responses use the same URI directly.
 
+[`src/documentation/validation.rs`](../src/documentation/validation.rs) checks
+the complete rendered graph rather than a hand-picked set of pages. It composes
+the three catalog validators, requires complete and unique index metadata,
+renders every indexed page, resolves Markdown and semantic-code HTML links
+relative to their virtual document, and verifies heading fragments. A stable
+fingerprint snapshots the ordered reference index. Native LSP tests compare all
+pages with this model, while packaged desktop and browser worker tests exercise
+the same page endpoint through the compiled adapter.
+
 ## VS Code client
 
 [`editors/vscode`](../editors/vscode) is a thin TypeScript extension around the

docs/ROADMAP_ARCHIVE.md

@@ -1,5 +1,19 @@
 # SplitScript roadmap
 
+## 2026-08-17: validated documentation graph across compiler products
+
+- Added one compiler-owned validation pass over all 413 reference
+  pages. It composes language, migration, and standard-library catalog
+  validation with canonical page identity, complete metadata, relative link,
+  semantic-code HTML link, and heading-fragment checks.
+- Added a deterministic reference-index snapshot so an accidental symbol,
+  hierarchy, title, signature, or summary change fails repository verification
+  and requires an intentional expectation update.
+- Compared every native LSP page with the direct documentation model and added
+  exact-page checks through both packaged desktop and browser language-server
+  workers. The VS Code web-host acceptance test now verifies that catalog hover
+  opens the requested symbol page beside the script.
+
 ## 2026-08-17: documentation links in ordinary editor workflows
 
 - Added exact compiler-owned documentation identities to catalog-backed hover

editors/vscode/test/webHost.ts

@@ -24,6 +24,33 @@ export async function run(): Promise<void> {
     await vscode.commands.executeCommand('splitscript.restartLanguageServer');
     await hoverAt(script, hoverPosition);
 
+    const printPosition = document.positionAt(document.getText().indexOf('print') + 1);
+    const printHovers = await hoverAt(script, printPosition);
+    const printMarkdown = printHovers.flatMap(hover => hover.contents)
+        .filter(
+            (content): content is vscode.MarkdownString =>
+                content instanceof vscode.MarkdownString,
+        )
+        .map(content => content.value)
+        .join('\n');
+    assert(
+        printMarkdown.includes(
+            'command:splitscript.openDocumentation?%5B%22%2Fstdlib%2Ffunctions%2Fprint.md%22%5D',
+        ),
+        'catalog hover does not link to its exact compiler-owned documentation page',
+    );
+    await vscode.commands.executeCommand(
+        'splitscript.openDocumentation',
+        '/stdlib/functions/print.md',
+    );
+    const printDocumentation = await vscode.workspace.openTextDocument(
+        vscode.Uri.parse('splitscript-docs:/stdlib/functions/print.md'),
+    );
+    assert(
+        printDocumentation.getText().includes('# print'),
+        'the documentation command did not open the requested symbol page',
+    );
+
     await vscode.commands.executeCommand('splitscript.openDocumentation');
     await waitFor(
         async () => (vscode.window.tabGroups.all.length >= 2 ? true : undefined),
@@ -98,14 +125,17 @@ export async function run(): Promise<void> {
     }
 }
 
-async function hoverAt(uri: vscode.Uri, position: vscode.Position): Promise<void> {
-    await waitFor(async () => {
+async function hoverAt(
+    uri: vscode.Uri,
+    position: vscode.Position,
+): Promise<readonly vscode.Hover[]> {
+    return waitFor(async () => {
         const hovers = await vscode.commands.executeCommand<readonly vscode.Hover[]>(
             'vscode.executeHoverProvider',
             uri,
             position,
         );
-        return hovers !== undefined && hovers.length > 0 ? true : undefined;
+        return hovers !== undefined && hovers.length > 0 ? hovers : undefined;
     }, 'the browser language server returned no hover');
 }
 

src/documentation.rs

@@ -4,6 +4,7 @@ mod bundled;
 mod code;
 mod entry;
 mod reference;
+mod validation;
 
 pub use entry::{DocumentedParameter, StandardLibraryDocumentation};
 pub(crate) use reference::migration_topic_uri;

src/documentation/reference.rs

@@ -69,6 +69,14 @@ pub struct DocumentationReference {
 }
 
 impl DocumentationReference {
+    /// Validates catalogs and every rendered page in the documentation graph.
+    ///
+    /// This checks the same graph consumed by native tools and editor clients,
+    /// including canonical page identities, local links, and heading anchors.
+    pub fn validate(&self) -> Vec<String> {
+        super::validation::validate(self, &self.library)
+    }
+
     /// Returns the stable virtual page for a language-catalog item.
     pub fn language_item_uri(&self, item: LanguageItemId) -> String {
         language_item_uri(item)
@@ -806,7 +814,7 @@ impl DocumentationReference {
         }
         DocumentationPage {
             uri: uri.to_owned(),
-            title: "SplitScript language".to_owned(),
+            title: "Language".to_owned(),
             markdown,
         }
     }
@@ -872,7 +880,7 @@ impl DocumentationReference {
         }
         DocumentationPage {
             uri: uri.to_owned(),
-            title: "Migrate to SplitScript".to_owned(),
+            title: "Migration".to_owned(),
             markdown,
         }
     }