@f5-sales-demo/xcsh 22.3.3 → 22.4.0

package/src/internal-urls/build-info.generated.ts

@@ -17,17 +17,17 @@ export interface BuildInfo {
 }
 
 export const BUILD_INFO: BuildInfo = {
-	"version": "22.3.3",
-	"commit": "82917afa08ee15956c363dacfb1c0f4511c74d3e",
-	"shortCommit": "82917af",
+	"version": "22.4.0",
+	"commit": "d4a6bd5c3d91616121cb5fb195c0dd0c2feb5bf7",
+	"shortCommit": "d4a6bd5",
 	"branch": "main",
-	"tag": "v22.3.3",
-	"commitDate": "2026-09-28T13:54:02Z",
-	"buildDate": "2026-09-28T14:30:23.798Z",
+	"tag": "v22.4.0",
+	"commitDate": "2026-09-29T03:06:46Z",
+	"buildDate": "2026-09-29T03:44:37.730Z",
 	"dirty": true,
 	"prNumber": "",
 	"repoUrl": "https://github.com/f5-sales-demo/xcsh",
 	"repoSlug": "f5-sales-demo/xcsh",
-	"commitUrl": "https://github.com/f5-sales-demo/xcsh/commit/82917afa08ee15956c363dacfb1c0f4511c74d3e",
-	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v22.3.3"
+	"commitUrl": "https://github.com/f5-sales-demo/xcsh/commit/d4a6bd5c3d91616121cb5fb195c0dd0c2feb5bf7",
+	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v22.4.0"
 };

package/src/internal-urls/documentation-metadata.ts

@@ -0,0 +1,271 @@
+import { createHash } from "node:crypto";
+import type { DocumentationSource } from "./documentation-resolve";
+
+export const DOCUMENTATION_CONTENT_TYPES = [
+	"product_overview",
+	"solution_overview",
+	"concept",
+	"how_to",
+	"reference",
+	"knowledge_article",
+] as const;
+export type DocumentationContentType = (typeof DOCUMENTATION_CONTENT_TYPES)[number];
+
+export const DOCUMENTATION_TASK_TYPES = ["concept", "configure", "troubleshoot", "support", "reference"] as const;
+export type DocumentationTaskType = (typeof DOCUMENTATION_TASK_TYPES)[number];
+
+export const DOCUMENTATION_LIFECYCLES = ["current", "deprecated", "superseded"] as const;
+export type DocumentationLifecycle = (typeof DOCUMENTATION_LIFECYCLES)[number];
+
+export interface DocumentationRelatedDocument {
+	readonly relation: DocumentationTaskType;
+	readonly title: string;
+	readonly canonicalUrl: string;
+	readonly source: DocumentationSource;
+	readonly stablePath: string;
+}
+
+export interface DocumentationMetadata {
+	readonly metadataSchema: 1;
+	readonly product: string | null;
+	readonly contentType: DocumentationContentType;
+	readonly taskType: DocumentationTaskType;
+	readonly canonicalUrl: string;
+	readonly lastUpdated: string | null;
+	readonly language: string;
+	readonly aliases: readonly string[];
+	readonly lifecycle: DocumentationLifecycle;
+	readonly replacementUrl: string | null;
+	readonly relatedDocuments: readonly DocumentationRelatedDocument[];
+}
+
+export interface DocumentationPassage {
+	readonly anchor: string;
+	readonly heading: string;
+	readonly markdown: string;
+	readonly ordinal: number;
+}
+
+export interface DocumentationGraphNode {
+	readonly source: DocumentationSource;
+	readonly stablePath: string;
+	readonly title: string;
+	readonly metadata: DocumentationMetadata;
+}
+
+const CONTENT_TYPE_SET = new Set<string>(DOCUMENTATION_CONTENT_TYPES);
+const TASK_TYPE_SET = new Set<string>(DOCUMENTATION_TASK_TYPES);
+const LIFECYCLE_SET = new Set<string>(DOCUMENTATION_LIFECYCLES);
+const LANGUAGE = /^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$/;
+const PRODUCT = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const DATE = /^\d{4}-\d{2}-\d{2}$/;
+const SAFE_PATH = /^[A-Za-z0-9._~-]+(?:\/[A-Za-z0-9._~-]+)*$/;
+const SOURCE_SET = new Set<DocumentationSource>(["docs-cloud-f5-com", "my-f5-com", "www-f5-com"]);
+
+function record(value: unknown, field: string): Record<string, unknown> {
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${field} must be an object`);
+	return value as Record<string, unknown>;
+}
+
+function nonEmpty(value: unknown, field: string): string {
+	if (typeof value !== "string" || !value.trim()) throw new Error(`${field} must be a non-empty string`);
+	return value;
+}
+
+function nullableDate(value: unknown, field: string): string | null {
+	if (value === null) return null;
+	const result = nonEmpty(value, field);
+	const parsed = new Date(`${result}T00:00:00Z`);
+	if (
+		result.length !== 10 ||
+		!DATE.test(result) ||
+		Number.isNaN(parsed.valueOf()) ||
+		parsed.toISOString().slice(0, 10) !== result
+	)
+		throw new Error(`${field} is invalid`);
+	return result;
+}
+
+function sortedStrings(value: unknown, field: string): readonly string[] {
+	if (!Array.isArray(value) || value.some(item => typeof item !== "string" || !item.trim())) {
+		throw new Error(`${field} must contain non-empty strings`);
+	}
+	const result = value as string[];
+	const expected = [...new Set(result)].sort((left, right) =>
+		compareText(left.toLocaleLowerCase("en-US"), right.toLocaleLowerCase("en-US")),
+	);
+	if (JSON.stringify(result) !== JSON.stringify(expected)) throw new Error(`${field} must be sorted and deduplicated`);
+	return result;
+}
+
+function compareText(left: string, right: string): number {
+	return left < right ? -1 : left > right ? 1 : 0;
+}
+
+export function parseDocumentationMetadata(
+	value: Record<string, unknown>,
+	validateUrl: (value: unknown, source: DocumentationSource | undefined, field: string) => string,
+	source: DocumentationSource,
+	field: string,
+): DocumentationMetadata {
+	if (value.metadata_schema !== 1) throw new Error(`${field}.metadata_schema must be 1`);
+	const product = value.product;
+	if (product !== null && (typeof product !== "string" || !PRODUCT.test(product))) {
+		throw new Error(`${field}.product must be a stable slug or null`);
+	}
+	const contentType = nonEmpty(value.content_type, `${field}.content_type`);
+	if (!CONTENT_TYPE_SET.has(contentType)) throw new Error(`${field}.content_type is invalid`);
+	const taskType = nonEmpty(value.task_type, `${field}.task_type`);
+	if (!TASK_TYPE_SET.has(taskType)) throw new Error(`${field}.task_type is invalid`);
+	const canonicalUrl = validateUrl(value.canonical_url, source, `${field}.canonical_url`);
+	const lastUpdated = nullableDate(value.last_updated, `${field}.last_updated`);
+	const language = nonEmpty(value.language, `${field}.language`);
+	if (!LANGUAGE.test(language)) throw new Error(`${field}.language is invalid`);
+	const aliases = sortedStrings(value.aliases, `${field}.aliases`);
+	const lifecycle = nonEmpty(value.lifecycle, `${field}.lifecycle`);
+	if (!LIFECYCLE_SET.has(lifecycle)) throw new Error(`${field}.lifecycle is invalid`);
+	const replacementUrl =
+		value.replacement_url === null ? null : validateUrl(value.replacement_url, undefined, `${field}.replacement_url`);
+	if ((lifecycle === "superseded") !== (replacementUrl !== null)) {
+		throw new Error(`${field}.replacement_url must exist only for superseded documents`);
+	}
+	if (!Array.isArray(value.related_documents)) throw new Error(`${field}.related_documents must be a list`);
+	const relatedDocuments = value.related_documents.map((item, position) => {
+		const relation = record(item, `${field}.related_documents[${position}]`);
+		const relationType = nonEmpty(relation.relation, `${field}.related_documents[${position}].relation`);
+		if (!TASK_TYPE_SET.has(relationType))
+			throw new Error(`${field}.related_documents[${position}].relation is invalid`);
+		const relatedSource = nonEmpty(
+			relation.source_id,
+			`${field}.related_documents[${position}].source_id`,
+		) as DocumentationSource;
+		if (!SOURCE_SET.has(relatedSource))
+			throw new Error(`${field}.related_documents[${position}].source_id is invalid`);
+		const stablePath = nonEmpty(relation.stable_path, `${field}.related_documents[${position}].stable_path`);
+		if (!SAFE_PATH.test(stablePath))
+			throw new Error(`${field}.related_documents[${position}].stable_path is invalid`);
+		return {
+			relation: relationType as DocumentationTaskType,
+			title: nonEmpty(relation.title, `${field}.related_documents[${position}].title`),
+			canonicalUrl: validateUrl(
+				relation.canonical_url,
+				relatedSource,
+				`${field}.related_documents[${position}].canonical_url`,
+			),
+			source: relatedSource,
+			stablePath,
+		};
+	});
+	const relatedOrder = [...relatedDocuments].sort(
+		(left, right) =>
+			compareText(left.relation, right.relation) ||
+			compareText(left.title.toLocaleLowerCase("en-US"), right.title.toLocaleLowerCase("en-US")) ||
+			compareText(left.canonicalUrl, right.canonicalUrl) ||
+			compareText(left.source, right.source) ||
+			compareText(left.stablePath, right.stablePath),
+	);
+	if (JSON.stringify(relatedDocuments) !== JSON.stringify(relatedOrder)) {
+		throw new Error(`${field}.related_documents must be sorted`);
+	}
+	if (new Set(relatedDocuments.map(item => item.canonicalUrl)).size !== relatedDocuments.length) {
+		throw new Error(`${field}.related_documents must be deduplicated`);
+	}
+	return {
+		metadataSchema: 1,
+		product: product as string | null,
+		contentType: contentType as DocumentationContentType,
+		taskType: taskType as DocumentationTaskType,
+		canonicalUrl,
+		lastUpdated,
+		language,
+		aliases,
+		lifecycle: lifecycle as DocumentationLifecycle,
+		replacementUrl,
+		relatedDocuments,
+	};
+}
+
+export function githubHeadingAnchor(heading: string, occurrences: Map<string, number>): string {
+	const base = heading
+		.trim()
+		.toLocaleLowerCase("en-US")
+		.replace(/<[^>]*>/g, "")
+		.replace(/[^\p{L}\p{N}\p{M}\s_-]/gu, "")
+		.replace(/\s/g, "-");
+	const normalized = base || "section";
+	const count = occurrences.get(normalized) ?? 0;
+	occurrences.set(normalized, count + 1);
+	return count === 0 ? normalized : `${normalized}-${count}`;
+}
+
+export function splitHeadingPassages(body: string): readonly DocumentationPassage[] {
+	const lines = body.replaceAll("\r\n", "\n").replaceAll("\r", "\n").split("\n");
+	const headings: Array<{ line: number; heading: string; anchor: string }> = [];
+	const occurrences = new Map<string, number>();
+	let fence: string | undefined;
+	for (const [line, value] of lines.entries()) {
+		const fenceMatch = /^\s*(`{3,}|~{3,})/.exec(value);
+		if (fenceMatch) {
+			const marker = fenceMatch[1]![0]!;
+			if (!fence) fence = marker;
+			else if (fence === marker) fence = undefined;
+			continue;
+		}
+		if (fence) continue;
+		const match = /^(#{1,3})\s+(.+?)\s*#*\s*$/.exec(value);
+		if (!match) continue;
+		const heading = match[2]!.trim();
+		headings.push({ line, heading, anchor: githubHeadingAnchor(heading, occurrences) });
+	}
+	if (headings.length === 0)
+		return [{ anchor: "document", heading: "Document", markdown: `${body.trim()}\n`, ordinal: 0 }];
+	return headings.map((heading, ordinal) => {
+		const start = heading.line;
+		const end = headings[ordinal + 1]?.line ?? lines.length;
+		return {
+			anchor: heading.anchor,
+			heading: heading.heading,
+			markdown: `${lines.slice(start, end).join("\n").trim()}\n`,
+			ordinal,
+		};
+	});
+}
+
+export function passageHash(documentHash: string, anchor: string, markdown: string): string {
+	return createHash("sha256").update(`${documentHash}\0${anchor}\0${markdown}`).digest("hex");
+}
+
+export function validateDocumentationGraph(documents: readonly DocumentationGraphNode[]): void {
+	const canonicalGroups = new Map<string, DocumentationGraphNode[]>();
+	for (const document of documents) {
+		canonicalGroups.set(document.metadata.canonicalUrl, [
+			...(canonicalGroups.get(document.metadata.canonicalUrl) ?? []),
+			document,
+		]);
+	}
+	const uniqueTargets = new Map(
+		[...canonicalGroups]
+			.filter(([, matches]) => matches.length === 1)
+			.map(([url, matches]) => [url, matches[0]!] as const),
+	);
+	for (const document of documents) {
+		if (document.metadata.replacementUrl !== null && !uniqueTargets.has(document.metadata.replacementUrl)) {
+			throw new Error(`replacement target is missing or ambiguous: ${document.metadata.replacementUrl}`);
+		}
+		for (const related of document.metadata.relatedDocuments) {
+			const target = uniqueTargets.get(related.canonicalUrl);
+			if (!target) throw new Error(`related target is missing or ambiguous: ${related.canonicalUrl}`);
+			if (
+				target.source !== related.source ||
+				target.stablePath !== related.stablePath ||
+				target.title !== related.title ||
+				target.metadata.taskType !== related.relation
+			) {
+				throw new Error(`related target metadata mismatch: ${related.canonicalUrl}`);
+			}
+			if (related.canonicalUrl === document.metadata.canonicalUrl) {
+				throw new Error(`related target cannot reference itself: ${related.canonicalUrl}`);
+			}
+		}
+	}
+}

package/src/internal-urls/documentation-repository.ts

@@ -6,14 +6,15 @@ import os from "node:os";
 import path from "node:path";
 import { gunzipSync } from "node:zlib";
 import { createStore } from "@tobilu/qmd";
-import {
-	DOCUMENTATION_SOURCES,
-	type DocumentationAsset,
-	type DocumentationDocument,
-	type DocumentationRepository,
-	type DocumentationSearchResult,
-	type DocumentationSource,
+import type {
+	DocumentationAsset,
+	DocumentationDocument,
+	DocumentationRepository,
+	DocumentationSearchFilters,
+	DocumentationSearchResult,
+	DocumentationSource,
 } from "./documentation-resolve";
+import { DOCUMENTATION_SOURCES } from "./documentation-resolve";
 import { extractVerifiedDocumentationAsset, type VerifiedDocumentationAsset } from "./documentation-snapshot";
 
 interface EmbeddedDocumentationAssetMetadata {
@@ -67,6 +68,24 @@ interface DocumentRow {
 	readonly title: string;
 	readonly original_url: string;
 	readonly markdown: string;
+	readonly canonical_url: string;
+	readonly last_updated: string | null;
+	readonly product: string | null;
+	readonly content_type: DocumentationSearchResult["contentType"];
+	readonly task_type: DocumentationSearchResult["taskType"];
+	readonly language: string;
+	readonly lifecycle: DocumentationSearchResult["lifecycle"];
+	readonly replacement_url: string | null;
+	readonly aliases_json: string;
+	readonly related_documents_json: string;
+}
+
+interface PassageRow extends DocumentRow {
+	readonly anchor: string;
+	readonly heading: string;
+	readonly passage_markdown: string;
+	readonly ordinal: number;
+	readonly score: number;
 }
 
 interface AssetRow {
@@ -219,6 +238,7 @@ function verifyDatabase(database: Database, assets: EmbeddedDocumentationAssets)
 		asset_count: String(assets.assetCount),
 		document_count: String(assets.documentCount),
 		fingerprint: assets.fingerprint,
+		index_schema: "2",
 		release_tag: assets.releaseTag,
 		source_commit: assets.sourceCommit,
 	};
@@ -234,14 +254,6 @@ function verifyDatabase(database: Database, assets: EmbeddedDocumentationAssets)
 	}
 }
 
-function stablePathFromResult(displayPath: string, source: DocumentationSource): string | null {
-	const prefix = `${source}/`;
-	const suffix = "/index.md";
-	if (!displayPath.startsWith(prefix) || !displayPath.endsWith(suffix)) return null;
-	const stablePath = displayPath.slice(prefix.length, -suffix.length);
-	return stablePath || null;
-}
-
 function boundedSnippet(markdown: string, query: string): string {
 	const body = markdown
 		.replace(/^---\n.*?\n---\n?/s, "")
@@ -264,6 +276,122 @@ function lexicalDocumentationQuery(query: string): string {
 	return query.replace(/^\s*(?:what|who)\s+(?:is|are)\s+/i, "").trim() || query;
 }
 
+function ftsPhrase(value: string): string {
+	return value
+		.normalize("NFKC")
+		.replace(/[^\p{L}\p{N}_-]+/gu, " ")
+		.replace(/-/g, " ")
+		.trim()
+		.replace(/\s+/g, " ");
+}
+
+function aliasGroups(database: Database): readonly (readonly string[])[] {
+	const rows = database
+		.query("SELECT product, alias FROM documentation_aliases ORDER BY product, alias")
+		.all() as Array<{
+		product: string;
+		alias: string;
+	}>;
+	const groups = new Map<string, string[]>();
+	for (const row of rows) groups.set(row.product, [...(groups.get(row.product) ?? []), row.alias]);
+	return [...groups.values()].sort(
+		(left, right) => Math.max(...right.map(value => value.length)) - Math.max(...left.map(value => value.length)),
+	);
+}
+
+function escapedFtsQuery(database: Database, query: string): string {
+	let remaining = lexicalDocumentationQuery(query);
+	const expansions: string[] = [];
+	for (const aliases of aliasGroups(database)) {
+		const matched = [...aliases]
+			.sort((left, right) => right.length - left.length)
+			.find(alias =>
+				new RegExp(
+					`(^|[^\\p{L}\\p{N}])${alias.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}([^\\p{L}\\p{N}]|$)`,
+					"iu",
+				).test(remaining),
+			);
+		if (!matched) continue;
+		remaining = remaining.replace(new RegExp(matched.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "iu"), " ");
+		expansions.push(`(${aliases.map(alias => `"${ftsPhrase(alias)}"`).join(" OR ")})`);
+	}
+	const terms =
+		remaining
+			.match(/[\p{L}\p{N}_-]+/gu)
+			?.map(term => ftsPhrase(term))
+			.filter(Boolean) ?? [];
+	return [...expansions, ...terms.map(term => `"${term}"*`)].join(" AND ");
+}
+
+function searchRows(
+	database: Database,
+	query: string,
+	source: DocumentationSource | undefined,
+	filters: DocumentationSearchFilters,
+): PassageRow[] {
+	const clauses = ["documents_fts MATCH ?", "d.active = 1"];
+	const parameters: Array<string | null> = [escapedFtsQuery(database, query)];
+	const add = (column: string, value: string | undefined): void => {
+		if (value === undefined) return;
+		clauses.push(`${column} = ?`);
+		parameters.push(value);
+	};
+	add("dd.source", source);
+	add("dd.product", filters.product);
+	add("dd.content_type", filters.contentType);
+	add("dd.task_type", filters.taskType);
+	add("dd.language", filters.language);
+	add("dd.lifecycle", filters.lifecycle);
+	if (!parameters[0]) return [];
+	return database
+		.query(`WITH scored AS (
+			SELECT dd.*, p.anchor, p.heading, p.markdown AS passage_markdown, p.ordinal,
+				ABS(bm25(documents_fts, 1.5, 4.0, 1.0)) /
+				(1.0 + ABS(bm25(documents_fts, 1.5, 4.0, 1.0))) *
+				CASE dd.lifecycle WHEN 'deprecated' THEN 0.85 WHEN 'superseded' THEN 0.65 ELSE 1.0 END AS score
+			FROM documents_fts
+			JOIN documents d ON d.id = documents_fts.rowid
+			JOIN documentation_passages p ON p.source = d.collection AND p.qmd_path = d.path
+			JOIN documentation_documents dd ON dd.source = p.source AND dd.stable_path = p.stable_path
+			WHERE ${clauses.join(" AND ")}
+		), ranked AS (
+			SELECT *, ROW_NUMBER() OVER (
+				PARTITION BY source, stable_path ORDER BY score DESC, ordinal ASC
+			) AS page_rank FROM scored
+		)
+		SELECT * FROM ranked WHERE page_rank = 1`)
+		.all(...parameters) as PassageRow[];
+}
+
+function diversifySources(
+	results: readonly PassageRow[],
+	preferredSource: DocumentationSource | undefined,
+	limit: number,
+): PassageRow[] {
+	const selected: PassageRow[] = [];
+	const seen = new Set<string>();
+	const sourceOrder = preferredSource
+		? [preferredSource, ...DOCUMENTATION_SOURCES.filter(source => source !== preferredSource)]
+		: [...DOCUMENTATION_SOURCES].sort((left, right) => {
+				const leftScore = results.find(result => result.source === left)?.score ?? -1;
+				const rightScore = results.find(result => result.source === right)?.score ?? -1;
+				return rightScore - leftScore || left.localeCompare(right);
+			});
+	for (const source of sourceOrder) {
+		const result = results.find(candidate => candidate.source === source);
+		if (!result) continue;
+		selected.push(result);
+		seen.add(`${result.source}\0${result.stable_path}`);
+	}
+	for (const result of results) {
+		const key = `${result.source}\0${result.stable_path}`;
+		if (seen.has(key)) continue;
+		selected.push(result);
+		seen.add(key);
+	}
+	return selected.slice(0, limit);
+}
+
 const SUPPORT_QUERY = /\b(?:troubleshoot|support|knowledge[- ]base|error|failure|issue|K[0-9]{6,})\b/i;
 const CONFIGURATION_QUERY = /\b(?:configure|configuration|set\s*up|procedure|instructions?|how\s+(?:do|can|to))\b/i;
 const CONCEPTUAL_QUERY = /\b(?:what\s+(?:is|are)|overview|product|solution|capabilities|benefits)\b/i;
@@ -313,58 +441,67 @@ export function createEmbeddedDocumentationRepository(
 		prime: async () => {
 			await state();
 		},
-		search: async (query, source, limit): Promise<readonly DocumentationSearchResult[]> => {
+		search: async (query, source, limit, filters = {}): Promise<readonly DocumentationSearchResult[]> => {
 			const current = await state();
-			const lexicalQuery = lexicalDocumentationQuery(query);
 			const preferredSource = source ? undefined : preferredDocumentationSource(query);
-			const results = source
-				? await current.store.searchLex(lexicalQuery, { limit, collection: source })
-				: (
-						await Promise.all(
-							DOCUMENTATION_SOURCES.map(collection =>
-								current.store.searchLex(lexicalQuery, { limit, collection }),
-							),
-						)
-					).flat();
+			const results = searchRows(current.database, query, source, filters);
 			results.sort((left, right) => {
-				const sourceOrder =
-					Number(right.collectionName === preferredSource) - Number(left.collectionName === preferredSource);
+				const sourceOrder = Number(right.source === preferredSource) - Number(left.source === preferredSource);
 				return (
 					sourceOrder ||
 					right.score - left.score ||
-					left.collectionName.localeCompare(right.collectionName) ||
-					left.displayPath.localeCompare(right.displayPath)
+					left.source.localeCompare(right.source) ||
+					left.stable_path.localeCompare(right.stable_path)
 				);
 			});
-			const rows: DocumentationSearchResult[] = [];
-			const lookup = current.database.query(
-				"SELECT source, stable_path, title, original_url, markdown FROM documentation_documents WHERE source = ? AND stable_path = ?",
-			);
-			for (const result of results) {
-				const resultSource = result.collectionName as DocumentationSource;
-				const stablePath = stablePathFromResult(result.displayPath, resultSource);
-				if (!stablePath) continue;
-				const row = lookup.get(resultSource, stablePath) as DocumentRow | null;
-				if (!row) continue;
-				rows.push({
-					title: row.title,
-					source: row.source,
-					originalUrl: row.original_url,
-					stablePath: row.stable_path,
-					snippet: boundedSnippet(row.markdown, query),
-					score: result.score,
-				});
-			}
-			return rows.slice(0, limit);
+			const selected = source ? results.slice(0, limit) : diversifySources(results, preferredSource, limit);
+			return selected.map(row => ({
+				title: row.title,
+				source: row.source,
+				originalUrl: row.original_url,
+				stablePath: row.stable_path,
+				snippet: boundedSnippet(row.passage_markdown, query),
+				score: Number(row.score.toFixed(12)),
+				anchor: row.anchor,
+				heading: row.heading,
+				canonicalUrl: row.canonical_url,
+				lastUpdated: row.last_updated,
+				product: row.product,
+				contentType: row.content_type,
+				taskType: row.task_type,
+				language: row.language,
+				lifecycle: row.lifecycle,
+				replacementUrl: row.replacement_url,
+				aliases: JSON.parse(row.aliases_json),
+				relatedDocuments: JSON.parse(row.related_documents_json),
+			}));
 		},
-		readDocument: async (source, stablePath): Promise<DocumentationDocument | null> => {
+		readDocument: async (source, stablePath, anchor): Promise<DocumentationDocument | null> => {
 			const current = await state();
 			const row = current.database
 				.query(
-					"SELECT title, original_url, markdown FROM documentation_documents WHERE source = ? AND stable_path = ?",
+					"SELECT title, original_url, markdown, lifecycle, replacement_url FROM documentation_documents WHERE source = ? AND stable_path = ?",
 				)
-				.get(source, stablePath) as Pick<DocumentRow, "title" | "original_url" | "markdown"> | null;
-			return row ? { markdown: row.markdown, title: row.title, originalUrl: row.original_url } : null;
+				.get(source, stablePath) as Pick<
+				DocumentRow,
+				"title" | "original_url" | "markdown" | "lifecycle" | "replacement_url"
+			> | null;
+			if (!row) return null;
+			let markdown = row.markdown;
+			if (anchor) {
+				const passage = current.database
+					.query("SELECT markdown FROM documentation_passages WHERE source = ? AND stable_path = ? AND anchor = ?")
+					.get(source, stablePath, anchor) as { markdown: string } | null;
+				if (!passage) return null;
+				markdown = passage.markdown;
+			}
+			return {
+				markdown,
+				title: row.title,
+				originalUrl: row.original_url,
+				lifecycle: row.lifecycle,
+				replacementUrl: row.replacement_url,
+			};
 		},
 		readAsset: async (source, stablePath, filename): Promise<DocumentationAsset | null> => {
 			const current = await state();