@farming-labs/docs 0.2.62 → 0.2.64

package/dist/review-CLoHTywU.mjs

@@ -0,0 +1,673 @@
+import { Ht as PAGE_AGENT_CONTRACT_FIELDS, Jt as normalizePageAgentFrontmatter, Kt as getPageAgentFrontmatterIssues, T as DOCS_CONFIG_MAP_TOP_LEVEL_KEYS, bt as findDocsAudienceMdxIssues, in as getDocsMcpProtectedResourceMetadataRoutes, j as buildDocsConfigMap, k as buildDocsAgentDiscoverySpec, qt as hasStructuredPageAgentContract } from "./agent-DKKptIgy.mjs";
+import { c as DEFAULT_AGENT_SKILLS_INDEX_ROUTE, g as DEFAULT_API_CATALOG_ROUTE, h as DEFAULT_API_CATALOG_FORMAT, k as resolveDocsDiscoveryApiRoute, l as DEFAULT_AGENT_SKILLS_ROUTE_PATTERN, p as DEFAULT_AGENT_SKILL_FORMAT, s as DEFAULT_AGENT_SKILLS_INDEX_FORMAT } from "./standards-discovery-jkykaXq1.mjs";
+import { d as resolveAskAISearchRequestConfig } from "./search-B6V6qtiI.mjs";
+import { a as resolveDocsMetadataBaseUrl } from "./metadata-DWExHQnx.mjs";
+import { c as resolveDocsReviewConfig, o as ensureDocsReviewWorkflow, s as readDocsReviewConfigFromSource, t as runDocsGoldenTasks } from "./agent-evals-B7MIxuEX.mjs";
+import { createFilesystemDocsMcpSource, getDocsConfigSchema, resolveDocsMcpConfig } from "./mcp.mjs";
+import "./code-blocks-DnNVNK2M.mjs";
+import { _ as resolveDocsContentDir, g as resolveDocsConfigPath, h as readTopLevelStringProperty, s as loadDocsConfigModuleResultWithProjectEnv } from "./config-Wcdj-D0a.mjs";
+import { t as detectFramework } from "./utils-DpiIioYb.mjs";
+import { a as extractAgentBlocks, i as createAgentUsefulnessPagesFromMcp, n as analyzeAgentSurfaceDrift, r as analyzeAgentUsefulness, t as resolveGoldenEvaluationInput } from "./golden-evaluations-Dj-9Eo3v.mjs";
+import matter from "gray-matter";
+import { existsSync, lstatSync, readFileSync, readdirSync } from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import pc from "picocolors";
+
+//#region src/cli/review.ts
+const DOCS_FILE_PATTERN = /\.(?:md|mdx|svx)$/;
+const IGNORED_DIRS = new Set([
+	".git",
+	".next",
+	".nuxt",
+	".output",
+	".svelte-kit",
+	"coverage",
+	"dist",
+	"node_modules",
+	"out"
+]);
+function parseReviewArgs(argv) {
+	const parsed = {};
+	for (let index = 0; index < argv.length; index += 1) {
+		const arg = argv[index];
+		if (arg === "setup") {
+			parsed.setup = true;
+			continue;
+		}
+		if (arg === "--help" || arg === "-h") {
+			parsed.help = true;
+			continue;
+		}
+		if (arg === "--ci") {
+			parsed.ci = true;
+			continue;
+		}
+		if (arg === "--json") {
+			parsed.json = true;
+			continue;
+		}
+		if (arg === "--config" || arg === "--base" || arg === "--head" || arg === "--mode") {
+			const value = argv[index + 1];
+			if (!value || value.startsWith("--")) throw new Error(`Missing value for ${arg}.`);
+			if (arg === "--config") parsed.configPath = value;
+			if (arg === "--base") parsed.base = value;
+			if (arg === "--head") parsed.head = value;
+			if (arg === "--mode") parsed.mode = parseReviewCiMode(value);
+			index += 1;
+			continue;
+		}
+		if (arg === "--score-threshold") {
+			const value = argv[index + 1];
+			if (!value || value.startsWith("--")) throw new Error("Missing value for --score-threshold.");
+			parsed.scoreThreshold = Number.parseInt(value, 10);
+			index += 1;
+			continue;
+		}
+		if (arg.startsWith("--config=")) {
+			parsed.configPath = readInlineFlag(arg, "--config=");
+			continue;
+		}
+		if (arg.startsWith("--base=")) {
+			parsed.base = readInlineFlag(arg, "--base=");
+			continue;
+		}
+		if (arg.startsWith("--head=")) {
+			parsed.head = readInlineFlag(arg, "--head=");
+			continue;
+		}
+		if (arg.startsWith("--mode=")) {
+			parsed.mode = parseReviewCiMode(readInlineFlag(arg, "--mode="));
+			continue;
+		}
+		if (arg.startsWith("--score-threshold=")) {
+			parsed.scoreThreshold = Number.parseInt(readInlineFlag(arg, "--score-threshold="), 10);
+			continue;
+		}
+		throw new Error(`Unknown review flag: ${arg}.`);
+	}
+	return parsed;
+}
+async function runReview(options = {}) {
+	const rootDir = process.cwd();
+	const configPath = resolveDocsConfigPath(rootDir, options.configPath);
+	const configContent = readFileSync(configPath, "utf-8");
+	const configLoad = await loadDocsConfigModuleResultWithProjectEnv(rootDir, options.configPath);
+	const config = configLoad.status === "evaluated" ? configLoad.config : void 0;
+	const review = withReviewOptionOverrides(resolveDocsReviewConfig(config?.review ?? readDocsReviewConfigFromSource(configContent)), options.mode, options.scoreThreshold);
+	if (options.setup) {
+		const result = ensureDocsReviewWorkflow({
+			rootDir,
+			config,
+			configPath: path.relative(rootDir, configPath),
+			configContent,
+			log: (message) => console.log(pc.green(message))
+		});
+		if (result.status === "exists") console.log(pc.dim(`${result.relativePath} already exists.`));
+		if (result.status === "disabled") console.log(pc.yellow("Docs Review CI is disabled in docs.config."));
+		return;
+	}
+	if (!review.enabled) {
+		const report = {
+			status: "disabled",
+			score: null,
+			threshold: review.score.threshold,
+			mode: options.ci ? review.ci.mode : "local",
+			reviewedFiles: [],
+			changedFiles: [],
+			findings: []
+		};
+		if (options.json) console.log(JSON.stringify(report, null, 2));
+		else console.log(pc.yellow("Docs Review is disabled in docs.config."));
+		return report;
+	}
+	const entry = config?.entry ?? readTopLevelStringProperty(configContent, "entry") ?? "docs";
+	const contentDir = config?.contentDir ?? resolveDocsContentDir(rootDir, configContent, entry);
+	const pages = scanDocsPages(rootDir, contentDir, entry);
+	const changedFiles = getChangedFiles(rootDir, options);
+	const relevantFiles = selectReviewFiles({
+		changedFiles,
+		pages,
+		configPath: path.relative(rootDir, configPath),
+		rootDir,
+		contentDir
+	});
+	const mcpSource = createFilesystemDocsMcpSource({
+		rootDir,
+		entry,
+		contentDir,
+		siteTitle: typeof config?.nav?.title === "string" ? config.nav.title : "Documentation"
+	});
+	const corpusPages = await Promise.resolve(mcpSource.getPages());
+	const usefulness = analyzeAgentUsefulness({
+		rootDir,
+		pages: createAgentUsefulnessPagesFromMcp(rootDir, corpusPages),
+		projectFramework: detectFramework(rootDir) ?? void 0
+	});
+	const findings = collectReviewFindings({
+		rootDir,
+		entry,
+		pages,
+		files: relevantFiles,
+		review
+	});
+	const relevantSet = new Set(relevantFiles);
+	for (const issue of usefulness.findings) {
+		if (!relevantSet.has(issue.file)) continue;
+		pushFinding(findings, review, {
+			rule: issue.category === "command" ? "commandHealth" : issue.category === "related" ? "relatedCoverage" : "agentContext",
+			code: issue.code,
+			severity: issue.severity === "warning" ? "warn" : issue.severity === "error" ? "error" : "suggestion",
+			file: issue.file,
+			line: issue.line,
+			message: issue.message
+		});
+	}
+	const evaluationInput = config?.agent?.evaluations;
+	const evaluation = resolveGoldenEvaluationInput(evaluationInput);
+	const evaluationBaseUrl = config ? resolveDocsMetadataBaseUrl(config) : void 0;
+	const evaluationSiteTitle = typeof config?.nav?.title === "string" ? config.nav.title : void 0;
+	const evaluationMcp = resolveDocsMcpConfig(config?.mcp, { defaultName: evaluationSiteTitle });
+	const askAISearch = resolveAskAISearchRequestConfig({
+		search: config?.search,
+		useMcp: config?.ai?.useMcp,
+		mcpEndpoint: evaluationMcp.route,
+		mcpEnabled: evaluationMcp.enabled,
+		mcpSearchEnabled: evaluationMcp.tools.searchDocs,
+		requestUrl: evaluationBaseUrl
+	});
+	const evaluations = await runDocsGoldenTasks(corpusPages, evaluation.tasks, {
+		...evaluation.options,
+		search: config?.search,
+		askAISearch,
+		siteTitle: evaluationSiteTitle,
+		baseUrl: evaluationBaseUrl,
+		rootDir,
+		codeBlocksValidate: config?.codeBlocks?.validate
+	});
+	if (relevantFiles.length > 0 && evaluations.status === "unmeasured") pushFinding(findings, review, {
+		rule: "goldenTasks",
+		code: "golden-tasks-unmeasured",
+		severity: "warn",
+		file: toPosixPath(path.relative(rootDir, configPath)),
+		message: evaluationInput === false || typeof evaluationInput === "object" && evaluationInput.enabled === false ? "Golden agent tasks are disabled, so retrieval usefulness is unmeasured." : "No golden agent tasks are configured; retrieval, citations, version selection, executable examples, and token usage are unmeasured."
+	});
+	for (const task of evaluations.tasks.filter((task) => !task.passed)) pushFinding(findings, review, {
+		rule: "goldenTasks",
+		code: "golden-task-failed",
+		severity: "warn",
+		file: toPosixPath(path.relative(rootDir, configPath)),
+		message: `Golden task ${JSON.stringify(task.id)} scored ${task.score}/100: ${task.issues.join(" ")}`
+	});
+	if (configLoad.status === "static-fallback") pushFinding(findings, review, {
+		rule: "configConfidence",
+		code: "config-static-fallback",
+		severity: "warn",
+		file: toPosixPath(path.relative(rootDir, configPath)),
+		message: `docs.config could not be evaluated; review used partial static parsing. ${configLoad.error}`
+	});
+	else {
+		const evaluatedConfig = configLoad.config;
+		const searchEnabled = evaluatedConfig.search !== false && !(typeof evaluatedConfig.search === "object" && evaluatedConfig.search?.enabled === false);
+		const mcp = resolveDocsMcpConfig(evaluatedConfig.mcp, { defaultName: typeof evaluatedConfig.nav?.title === "string" ? evaluatedConfig.nav.title : void 0 });
+		const apiRoute = resolveDocsDiscoveryApiRoute(evaluatedConfig.cloud?.apiRoute);
+		const discovery = buildDocsAgentDiscoverySpec({
+			origin: "http://localhost",
+			entry,
+			apiRoute,
+			search: evaluatedConfig.search,
+			mcp
+		});
+		const configuredAgentReviewPaths = Object.values(buildDocsConfigMap(evaluatedConfig).pointers).map((pointer) => pointer.path).filter((optionPath) => optionPath === "agent" || optionPath.startsWith("agent.") || optionPath === "mcp" || optionPath.startsWith("mcp.") || optionPath === "review" || optionPath.startsWith("review."));
+		const expectedMcpProtectedResource = mcp.enabled && mcp.security?.authenticate && mcp.security.protectedResource ? {
+			metadataEndpoints: [...getDocsMcpProtectedResourceMetadataRoutes(mcp.route)],
+			authorizationServers: mcp.security.protectedResource.authorizationServers,
+			scopesSupported: mcp.security.protectedResource.scopesSupported,
+			requiredScopes: mcp.security.protectedResource.requiredScopes
+		} : null;
+		const drift = analyzeAgentSurfaceDrift({
+			configOptionPaths: [...new Set([...DOCS_CONFIG_MAP_TOP_LEVEL_KEYS, ...configuredAgentReviewPaths])],
+			schemaOptions: getDocsConfigSchema().options,
+			agentContractFields: PAGE_AGENT_CONTRACT_FIELDS,
+			discovery,
+			expected: {
+				entry,
+				search: {
+					enabled: searchEnabled,
+					endpoint: `${apiRoute}?query={query}`
+				},
+				mcp: {
+					enabled: mcp.enabled,
+					endpoint: mcp.route,
+					tools: mcp.tools,
+					protectedResource: expectedMcpProtectedResource
+				},
+				routes: {
+					"api.docs": apiRoute,
+					"api.config": `${apiRoute}?format=config`,
+					"api.apiCatalog": DEFAULT_API_CATALOG_ROUTE,
+					"api.apiCatalogQuery": `${apiRoute}?format=${DEFAULT_API_CATALOG_FORMAT}`,
+					"api.agentSkillsIndex": DEFAULT_AGENT_SKILLS_INDEX_ROUTE,
+					"apiCatalog.route": DEFAULT_API_CATALOG_ROUTE,
+					"apiCatalog.api": `${apiRoute}?format=${DEFAULT_API_CATALOG_FORMAT}`,
+					"config.endpoint": `${apiRoute}?format=config`,
+					"skills.discovery.index": DEFAULT_AGENT_SKILLS_INDEX_ROUTE,
+					"skills.discovery.artifact": DEFAULT_AGENT_SKILLS_ROUTE_PATTERN,
+					"skills.discovery.apiIndex": `${apiRoute}?format=${DEFAULT_AGENT_SKILLS_INDEX_FORMAT}`,
+					"skills.discovery.apiArtifact": `${apiRoute}?format=${DEFAULT_AGENT_SKILL_FORMAT}&name={name}`
+				}
+			}
+		});
+		for (const issue of drift) pushFinding(findings, review, {
+			rule: "agentSurfaceDrift",
+			code: issue.code,
+			severity: "error",
+			file: toPosixPath(path.relative(rootDir, configPath)),
+			message: issue.message
+		});
+	}
+	const score = calculateReviewScore(findings, review);
+	const mode = options.ci ? review.ci.mode : "local";
+	const report = {
+		status: "measured",
+		score,
+		threshold: review.score.threshold,
+		mode,
+		reviewedFiles: relevantFiles,
+		changedFiles,
+		findings,
+		usefulness: usefulness.metrics,
+		evaluations
+	};
+	if (options.json) console.log(JSON.stringify(report, null, 2));
+	else printReviewReport(report);
+	if (options.ci && review.ci.annotations) emitGitHubAnnotations(report.findings);
+	if (options.ci && review.ci.mode === "block" && (score < review.score.threshold || findings.some((finding) => finding.severity === "error"))) process.exitCode = 1;
+	return report;
+}
+function printReviewHelp() {
+	console.log(`
+${pc.bold("docs review")} — Review changed docs content for CI and agent-readiness.
+
+${pc.dim("Usage:")}
+  pnpm exec docs ${pc.cyan("review")} ${pc.dim("[--ci]")}
+  pnpm exec docs ${pc.cyan("review setup")}
+
+${pc.dim("Options:")}
+  ${pc.cyan("--ci")}                         Use docs.config review.ci behavior and GitHub annotations
+  ${pc.cyan("--json")}                       Print JSON report
+  ${pc.cyan("--config <path>")}              Use a custom docs config path
+  ${pc.cyan("--base <ref> --head <ref>")}    Review files changed between two git refs
+  ${pc.cyan("--mode <off|warn|block>")}      Override review.ci.mode
+  ${pc.cyan("--score-threshold <0-100>")}    Override review.score.threshold
+`);
+}
+function withReviewOptionOverrides(review, mode, scoreThreshold) {
+	return {
+		...review,
+		ci: mode ? {
+			...review.ci,
+			mode,
+			enabled: mode !== "off"
+		} : review.ci,
+		score: typeof scoreThreshold === "number" && Number.isFinite(scoreThreshold) ? {
+			...review.score,
+			threshold: Math.max(0, Math.min(100, Math.round(scoreThreshold)))
+		} : review.score
+	};
+}
+function collectReviewFindings(options) {
+	const findings = [];
+	const knownRoutes = /* @__PURE__ */ new Set();
+	const slugSources = /* @__PURE__ */ new Map();
+	for (const page of options.pages) {
+		knownRoutes.add(page.route);
+		knownRoutes.add(page.markdownRoute);
+		if (slugSources.has(page.route)) pushFinding(findings, options.review, {
+			rule: "duplicateSlugs",
+			severity: "error",
+			file: page.relativePath,
+			message: `Duplicate docs route ${page.route}; already used by ${slugSources.get(page.route)}.`
+		});
+		else slugSources.set(page.route, page.relativePath);
+	}
+	for (const file of options.files) {
+		if (!DOCS_FILE_PATTERN.test(file)) continue;
+		const absolutePath = path.join(options.rootDir, file);
+		if (!existsSync(absolutePath)) continue;
+		let source = "";
+		let parsed;
+		try {
+			source = readFileSync(absolutePath, "utf-8");
+			parsed = matter(source);
+		} catch (error) {
+			pushFinding(findings, options.review, {
+				rule: "invalidMdx",
+				severity: "error",
+				file,
+				message: `Could not read or parse this docs file: ${error instanceof Error ? error.message : String(error)}`
+			});
+			continue;
+		}
+		if (!file.endsWith("agent.md")) {
+			checkFrontmatter(findings, options.review, file, parsed.data);
+			checkAgentContext(findings, options.review, {
+				file,
+				source,
+				rootDir: options.rootDir,
+				agent: parsed.data.agent
+			});
+		}
+		checkBrokenLinks(findings, options.review, {
+			file,
+			source,
+			entry: options.entry,
+			knownRoutes
+		});
+		checkCodeFences(findings, options.review, {
+			file,
+			source
+		});
+	}
+	return findings;
+}
+function checkFrontmatter(findings, review, file, data) {
+	if (!data.title || typeof data.title !== "string") pushFinding(findings, review, {
+		rule: "frontmatter",
+		severity: "error",
+		file,
+		line: 1,
+		message: "Missing frontmatter title."
+	});
+	if (!data.description || typeof data.description !== "string") pushFinding(findings, review, {
+		rule: "frontmatter",
+		severity: "error",
+		file,
+		line: 1,
+		message: "Missing frontmatter description."
+	});
+}
+function checkBrokenLinks(findings, review, options) {
+	const linkPattern = /\[[^\]]+\]\(([^)]+)\)|href=["']([^"']+)["']/g;
+	let match;
+	while (match = linkPattern.exec(options.source)) {
+		if (match[1] && options.source[match.index - 1] === "!") continue;
+		const href = match[1] ?? match[2];
+		if (!href || !href.startsWith("/")) continue;
+		const normalized = normalizeInternalHref(href);
+		if (!normalized || !normalized.startsWith(`/${options.entry}`)) continue;
+		if (options.knownRoutes.has(normalized)) continue;
+		pushFinding(findings, review, {
+			rule: "brokenLinks",
+			severity: "error",
+			file: options.file,
+			line: lineForIndex(options.source, match.index),
+			message: `Internal docs link does not resolve: ${href}`
+		});
+	}
+}
+function checkCodeFences(findings, review, options) {
+	const fencePattern = /^```([^\n`]*)\n([\s\S]*?)^```/gm;
+	let match;
+	while (match = fencePattern.exec(options.source)) {
+		const info = match[1]?.trim() ?? "";
+		const code = match[2] ?? "";
+		const language = info.split(/\s+/)[0] ?? "";
+		if (!language || !isImplementationLanguage(language)) continue;
+		const hasTitle = /\btitle=/.test(info);
+		const hasPackageManager = /\bpackageManager=/.test(info);
+		const isRunnable = /\brunnable\b/.test(info);
+		const isConfigExample = /\bdefineDocs\s*\(|\bwithDocs\s*\(|\bdocs\.config\b/.test(code);
+		if (!hasTitle && (isRunnable || isConfigExample)) pushFinding(findings, review, {
+			rule: "codeFenceMetadata",
+			severity: "warn",
+			file: options.file,
+			line: lineForIndex(options.source, match.index),
+			message: "Code block is missing title metadata, e.g. title=\"docs.config.ts\"."
+		});
+		if (isRunnable && !hasPackageManager) pushFinding(findings, review, {
+			rule: "runnableMetadata",
+			severity: "warn",
+			file: options.file,
+			line: lineForIndex(options.source, match.index),
+			message: "Runnable code block is missing packageManager metadata."
+		});
+	}
+}
+function checkAgentContext(findings, review, options) {
+	for (const issue of findDocsAudienceMdxIssues(options.source)) pushFinding(findings, review, {
+		rule: "agentContext",
+		code: `audience-${issue.code}`,
+		severity: issue.code === "dynamic-only" ? "error" : "warn",
+		file: options.file,
+		line: lineForIndex(options.source, issue.index),
+		message: issue.message
+	});
+	for (const issue of getPageAgentFrontmatterIssues(options.agent)) pushFinding(findings, review, {
+		rule: "agentContext",
+		severity: "warn",
+		file: options.file,
+		line: 1,
+		message: `Invalid ${issue.path}: ${issue.message}${/[.!?]$/.test(issue.message) ? "" : "."}`
+	});
+	const agent = normalizePageAgentFrontmatter(options.agent);
+	if (hasStructuredPageAgentContract(agent)) {
+		const missing = [!agent?.task ? "task" : void 0, !agent?.outcome ? "outcome" : void 0].filter(Boolean).join(" and ");
+		if (missing) pushFinding(findings, review, {
+			rule: "agentContext",
+			severity: "suggestion",
+			file: options.file,
+			line: 1,
+			message: `Structured agent contract is missing ${missing}.`
+		});
+		if (agent?.commands?.length && !agent.verification?.length) pushFinding(findings, review, {
+			rule: "agentContext",
+			severity: "suggestion",
+			file: options.file,
+			line: 1,
+			message: "Structured agent contract defines commands without verification steps."
+		});
+		if (agent?.sideEffects?.length && !agent.rollback?.length) pushFinding(findings, review, {
+			rule: "agentContext",
+			severity: "suggestion",
+			file: options.file,
+			line: 1,
+			message: "Structured agent contract defines side effects without rollback guidance."
+		});
+		if (agent?.task && agent.outcome) return;
+	}
+	if (extractAgentBlocks(options.source, { sourcePath: options.file }).length > 0) return;
+	if (existsSync(path.join(path.dirname(path.join(options.rootDir, options.file)), "agent.md"))) return;
+	if (!/\b(install|configure|setup|implement|defineDocs|docs\.config|MCP|agent)\b/i.test(options.source)) return;
+	pushFinding(findings, review, {
+		rule: "agentContext",
+		severity: "suggestion",
+		file: options.file,
+		line: 1,
+		message: "Implementation-heavy docs page could use an <Agent> block, <Audience only=\"agent\"> block, or sibling agent.md."
+	});
+}
+function pushFinding(findings, review, finding) {
+	const configured = review.rules[finding.rule];
+	if (configured === "off") return;
+	findings.push({
+		...finding,
+		severity: configured === "error" || configured === "warn" ? configured : "suggestion"
+	});
+}
+function calculateReviewScore(findings, review) {
+	const penalty = findings.reduce((total, finding) => {
+		if (finding.severity === "error") return total + review.score.weights.error;
+		if (finding.severity === "warn") return total + review.score.weights.warn;
+		return total + review.score.weights.suggestion;
+	}, 0);
+	return Math.max(0, 100 - penalty);
+}
+function printReviewReport(report) {
+	const counts = countFindings(report.findings);
+	const modeLabel = report.mode === "local" ? "local" : report.mode;
+	console.log(pc.bold("Docs Review"));
+	console.log("");
+	console.log(`Score: ${scoreColor(report.score, report.threshold)} / 100`);
+	console.log(`Threshold: ${report.threshold}`);
+	console.log(`Mode: ${modeLabel}`);
+	console.log(`Changed files: ${report.changedFiles.length}`);
+	console.log(`Reviewed docs files: ${report.reviewedFiles.length}`);
+	console.log(`Findings: ${counts.error} error${counts.error === 1 ? "" : "s"}, ${counts.warn} warning${counts.warn === 1 ? "" : "s"}, ${counts.suggestion} suggestion${counts.suggestion === 1 ? "" : "s"}`);
+	if (report.usefulness) console.log(`Useful agent-only blocks: ${report.usefulness.agentBlocks.useful}/${report.usefulness.agentBlocks.total}; task-complete pages: ${report.usefulness.taskCompleteness.completePages}/${report.usefulness.actionablePages}`);
+	if (report.evaluations) console.log(`Golden tasks: ${report.evaluations.status === "unmeasured" ? "unmeasured" : `${report.evaluations.passedTaskCount}/${report.evaluations.taskCount} passed (${report.evaluations.score}/100)`}`);
+	if (report.reviewedFiles.length === 0 && report.findings.length === 0) {
+		console.log("");
+		console.log(pc.green("No docs changes detected. Skipping review."));
+		return;
+	}
+	if (report.reviewedFiles.length === 0) {
+		console.log("");
+		console.log(pc.yellow("No docs files changed; reporting project-wide findings."));
+	}
+	if (report.findings.length === 0) {
+		console.log("");
+		console.log(pc.green("No docs review findings."));
+		return;
+	}
+	console.log("");
+	for (const finding of report.findings) {
+		const label = finding.severity === "error" ? pc.red("ERROR") : finding.severity === "warn" ? pc.yellow("WARN") : pc.cyan("SUGGEST");
+		const location = `${finding.file}${finding.line ? `:${finding.line}` : ""}`;
+		console.log(`${label} ${pc.dim(location)} ${finding.message}`);
+	}
+}
+function emitGitHubAnnotations(findings) {
+	if (process.env.GITHUB_ACTIONS !== "true") return;
+	for (const finding of findings) {
+		const command = finding.severity === "error" ? "error" : finding.severity === "warn" ? "warning" : "notice";
+		const location = [`file=${escapeGitHubAnnotationValue(finding.file)}`, finding.line ? `line=${finding.line}` : void 0].filter(Boolean).join(",");
+		console.log(`::${command} ${location}::${escapeGitHubAnnotationValue(finding.message)}`);
+	}
+}
+function scoreColor(score, threshold) {
+	if (score < threshold) return pc.red(String(score));
+	if (score < Math.min(100, threshold + 10)) return pc.yellow(String(score));
+	return pc.green(String(score));
+}
+function countFindings(findings) {
+	return findings.reduce((counts, finding) => {
+		counts[finding.severity] += 1;
+		return counts;
+	}, {
+		error: 0,
+		warn: 0,
+		suggestion: 0
+	});
+}
+function selectReviewFiles(options) {
+	const pageFiles = new Set(options.pages.map((page) => page.relativePath));
+	const normalizedConfigPath = toPosixPath(options.configPath);
+	if (options.changedFiles.includes(normalizedConfigPath)) return Array.from(pageFiles).sort();
+	const selected = /* @__PURE__ */ new Set();
+	for (const changedFile of options.changedFiles.map(toPosixPath)) {
+		if (pageFiles.has(changedFile)) {
+			selected.add(changedFile);
+			continue;
+		}
+		if (!changedFile.endsWith("/agent.md") && changedFile !== "agent.md") continue;
+		const sibling = options.pages.find((page) => path.posix.dirname(page.relativePath) === path.posix.dirname(changedFile));
+		if (sibling) selected.add(sibling.relativePath);
+	}
+	return Array.from(selected).sort();
+}
+function getChangedFiles(rootDir, options) {
+	const ranges = [
+		options.base && options.head ? `${options.base}...${options.head}` : void 0,
+		process.env.GITHUB_BASE_REF ? `origin/${process.env.GITHUB_BASE_REF}...HEAD` : void 0,
+		"HEAD~1...HEAD",
+		void 0
+	].filter((range, index, allRanges) => range !== void 0 || index === allRanges.length - 1);
+	for (const range of ranges) try {
+		const args = [
+			"diff",
+			"--relative",
+			"--name-only",
+			"--diff-filter=ACMRTUXB"
+		];
+		if (range) args.push(range);
+		const files = execFileSync("git", args, {
+			cwd: rootDir,
+			encoding: "utf-8"
+		}).split(/\r?\n/).map((file) => file.trim()).filter(Boolean).map(toPosixPath);
+		if (files.length > 0 || range === void 0) return files;
+	} catch {}
+	return [];
+}
+function scanDocsPages(rootDir, contentDir, entry) {
+	const contentRoot = path.isAbsolute(contentDir) ? contentDir : path.join(rootDir, contentDir);
+	if (!existsSync(contentRoot)) return [];
+	return listFiles(contentRoot).filter((file) => DOCS_FILE_PATTERN.test(file) && path.basename(file) !== "agent.md").map((absolutePath) => {
+		const relativeToContent = toPosixPath(path.relative(contentRoot, absolutePath));
+		const relativePath = toPosixPath(path.relative(rootDir, absolutePath));
+		const slug = docsSlugFromFile(relativeToContent);
+		const route = normalizeRoute(`/${entry}${slug ? `/${slug}` : ""}`);
+		return {
+			relativePath,
+			absolutePath,
+			route,
+			markdownRoute: `${route}.md`
+		};
+	});
+}
+function listFiles(dir) {
+	const files = [];
+	for (const name of readdirSync(dir)) {
+		if (IGNORED_DIRS.has(name)) continue;
+		const fullPath = path.join(dir, name);
+		let stat;
+		try {
+			stat = lstatSync(fullPath);
+		} catch {
+			continue;
+		}
+		if (stat.isDirectory()) files.push(...listFiles(fullPath));
+		else if (stat.isFile()) files.push(fullPath);
+	}
+	return files;
+}
+function docsSlugFromFile(relativePath) {
+	const withoutExt = relativePath.replace(/\.(?:md|mdx|svx)$/, "");
+	if (withoutExt === "page" || withoutExt === "+page" || withoutExt === "index") return "";
+	if (withoutExt.endsWith("/page") || withoutExt.endsWith("/+page") || withoutExt.endsWith("/index")) return withoutExt.replace(/\/(?:\+?page|index)$/, "");
+	return withoutExt;
+}
+function normalizeInternalHref(href) {
+	const [withoutHash] = href.split("#");
+	const [withoutQuery] = withoutHash.split("?");
+	if (!withoutQuery || withoutQuery === "/") return "/";
+	return normalizeRoute(withoutQuery.replace(/\.md$/, ""));
+}
+function normalizeRoute(route) {
+	const normalized = `/${route}`.replace(/\/+/g, "/");
+	return normalized.length > 1 ? normalized.replace(/\/+$/, "") : normalized;
+}
+function isImplementationLanguage(language) {
+	return /^(?:bash|sh|shell|zsh|ts|tsx|js|jsx|json|mdx?)$/.test(language);
+}
+function lineForIndex(source, index) {
+	return source.slice(0, index).split(/\r?\n/).length;
+}
+function escapeGitHubAnnotationValue(value) {
+	return value.replaceAll("%", "%25").replaceAll("\r", "%0D").replaceAll("\n", "%0A");
+}
+function parseReviewCiMode(value) {
+	if (value === "off" || value === "warn" || value === "block") return value;
+	throw new Error(`Invalid review mode: ${value}. Expected off, warn, or block.`);
+}
+function readInlineFlag(arg, prefix) {
+	const value = arg.slice(prefix.length);
+	if (!value) throw new Error(`Missing value for ${prefix.replace(/=$/, "")}.`);
+	return value;
+}
+function toPosixPath(value) {
+	return value.replaceAll("\\", "/");
+}
+
+//#endregion
+export { parseReviewArgs, printReviewHelp, runReview };