@farming-labs/docs 0.2.60 → 0.2.62

package/dist/review-NC-sOdXn.mjs

@@ -1,665 +0,0 @@
-import { Jt as DEFAULT_AGENT_SKILLS_ROUTE_PATTERN, Kt as DEFAULT_AGENT_SKILLS_INDEX_FORMAT, M as buildDocsAgentDiscoverySpec, O as DOCS_CONFIG_MAP_TOP_LEVEL_KEYS, P as buildDocsConfigMap, Qt as DEFAULT_API_CATALOG_ROUTE, Xt as DEFAULT_AGENT_SKILL_FORMAT, Zt as DEFAULT_API_CATALOG_FORMAT, _n as hasStructuredPageAgentContract, an as resolveDocsDiscoveryApiRoute, fn as PAGE_AGENT_CONTRACT_FIELDS, gn as getPageAgentFrontmatterIssues, qt as DEFAULT_AGENT_SKILLS_INDEX_ROUTE, vn as normalizePageAgentFrontmatter, wt as findDocsAudienceMdxIssues } from "./agent-BFqyqEnC.mjs";
-import { d as resolveAskAISearchRequestConfig } from "./search-D57JXQLj.mjs";
-import { a as resolveDocsMetadataBaseUrl } from "./metadata-BDuewuzq.mjs";
-import { c as resolveDocsReviewConfig, o as ensureDocsReviewWorkflow, s as readDocsReviewConfigFromSource, t as runDocsGoldenTasks } from "./agent-evals-kJs2Y9xR.mjs";
-import { createFilesystemDocsMcpSource, getDocsConfigSchema, resolveDocsMcpConfig } from "./mcp.mjs";
-import "./code-blocks-qe0T8-xe.mjs";
-import { a as loadDocsConfigModuleResultWithProjectEnv, h as resolveDocsContentDir, m as resolveDocsConfigPath, p as readTopLevelStringProperty } from "./config-DASewQ0x.mjs";
-import { t as detectFramework } from "./utils-6UCLxv4B.mjs";
-import { a as extractAgentBlocks, i as createAgentUsefulnessPagesFromMcp, n as analyzeAgentSurfaceDrift, r as analyzeAgentUsefulness, t as resolveGoldenEvaluationInput } from "./golden-evaluations-BN9u2wxw.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 === "review" || optionPath.startsWith("review."));
-		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
-				},
-				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 };