@farming-labs/docs 0.1.119 → 0.1.120

package/dist/review-BHFhvl2F.mjs

@@ -0,0 +1,475 @@
+import { a as ensureDocsReviewWorkflow, o as readDocsReviewConfigFromSource, s as resolveDocsReviewConfig } from "./review-_5fnI667.mjs";
+import { d as readTopLevelStringProperty, f as resolveDocsConfigPath, i as loadDocsConfigModule, p as resolveDocsContentDir } from "./config-BHRL4R2v.mjs";
+import matter from "gray-matter";
+import { existsSync, lstatSync, readFileSync, readdirSync } from "node:fs";
+import path from "node:path";
+import pc from "picocolors";
+import { execFileSync } from "node:child_process";
+
+//#region src/cli/review.ts
+const DOCS_FILE_PATTERN = /\.(?:md|mdx)$/;
+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 config = (await loadDocsConfigModule(rootDir, options.configPath))?.config;
+	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 = {
+			score: 100,
+			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 findings = collectReviewFindings({
+		rootDir,
+		entry,
+		pages,
+		files: relevantFiles,
+		review
+	});
+	const score = calculateReviewScore(findings, review);
+	const mode = options.ci ? review.ci.mode : "local";
+	const report = {
+		score,
+		threshold: review.score.threshold,
+		mode,
+		reviewedFiles: relevantFiles,
+		changedFiles,
+		findings
+	};
+	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
+			});
+		}
+		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) {
+	if (options.source.includes("<Agent>") || options.source.includes("</Agent>")) 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 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.reviewedFiles.length === 0) {
+		console.log("");
+		console.log(pc.green("No docs changes detected. Skipping review."));
+		return;
+	}
+	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();
+	return options.changedFiles.map(toPosixPath).filter((file) => pageFiles.has(file)).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)).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)$/, "");
+	if (withoutExt === "page" || withoutExt === "index") return "";
+	if (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 };