@farming-labs/docs 0.1.48 → 0.1.49

package/dist/cli/index.mjs

@@ -89,7 +89,7 @@ async function main() {
 		printAgentCompactHelp();
 		process.exit(1);
 	} else if (parsedCommand.command === "doctor") {
-		const { parseDoctorArgs, printDoctorHelp, runDoctor } = await import("../doctor-Jm7T0qYS.mjs");
+		const { parseDoctorArgs, printDoctorHelp, runDoctor } = await import("../doctor-D0UYKEFN.mjs");
 		const doctorOptions = parseDoctorArgs(args.slice(1));
 		if (doctorOptions.help) {
 			printDoctorHelp();
@@ -129,7 +129,7 @@ ${pc.dim("Usage:")}
 ${pc.dim("Commands:")}
   ${pc.cyan("init")}     Scaffold docs in your project (default)
   ${pc.cyan("agent")}    Agent utilities (${pc.dim("compact")} to generate sibling agent.md files)
-  ${pc.cyan("doctor")}   Inspect and score agent-readiness for the current docs app
+  ${pc.cyan("doctor")}   Inspect and score agent or reader-facing docs quality
   ${pc.cyan("mcp")}      Run the built-in docs MCP server over stdio
   ${pc.cyan("search")}   Search utilities (${pc.dim("sync")} for external indexes)
   ${pc.cyan("upgrade")}  Upgrade @farming-labs/* packages to latest (auto-detect or use --framework)
@@ -162,7 +162,11 @@ ${pc.dim("Options for agent compact:")}
 ${pc.dim("Options for doctor:")}
   ${pc.cyan("doctor")}                              Score the current docs app for agent-readiness
   ${pc.cyan("doctor --agent")}                      Same as ${pc.cyan("doctor")}; explicit agent scoring mode
+  ${pc.cyan("doctor --site")}                       Score the current docs app for reader-facing docs quality
+  ${pc.cyan("doctor --human")}                      Alias for ${pc.cyan("doctor --site")}
   ${pc.cyan("doctor agent")}                        Subcommand alias for agent scoring
+  ${pc.cyan("doctor site")}                         Subcommand alias for reader-facing scoring
+  ${pc.cyan("doctor human")}                        Legacy alias for reader-facing scoring
   ${pc.cyan("--config <path>")}                     Use a custom docs config path instead of ${pc.dim("docs.config.ts[x]")}
 
 ${pc.dim("Options for search sync:")}

package/dist/{doctor-Jm7T0qYS.mjs → doctor-D0UYKEFN.mjs}

@@ -41,7 +41,11 @@ function parseDoctorArgs(argv) {
 			continue;
 		}
 		if (arg === "--agent" || arg === "agent") {
-			parsed.agent = true;
+			parsed.mode = "agent";
+			continue;
+		}
+		if (arg === "--human" || arg === "human" || arg === "--site" || arg === "site") {
+			parsed.mode = "human";
 			continue;
 		}
 		if (arg.startsWith("--config=")) {
@@ -59,7 +63,7 @@ function parseDoctorArgs(argv) {
 		}
 		throw new Error(`Unknown doctor flag or subcommand: ${arg}.`);
 	}
-	if (!parsed.help && parsed.agent !== true) parsed.agent = true;
+	if (!parsed.help && !parsed.mode) parsed.mode = "agent";
 	return parsed;
 }
 function printDoctorHelp() {
@@ -69,10 +73,14 @@ ${pc.bold("@farming-labs/docs doctor")}
 ${pc.dim("Usage:")}
   pnpm exec docs doctor
   pnpm exec docs doctor --agent
+  pnpm exec docs doctor --site
   pnpm exec docs doctor agent
+  pnpm exec docs doctor site
 
 ${pc.dim("Options:")}
   ${pc.cyan("--agent")}            Score agent-readiness for the current docs app (default)
+  ${pc.cyan("--site")}             Score reader-facing docs quality for the current docs app
+  ${pc.cyan("--human")}            Alias for ${pc.cyan("--site")}
   ${pc.cyan("--config <path>")}    Use a custom docs config path instead of ${pc.dim("docs.config.ts[x]")}
   ${pc.cyan("-h, --help")}         Show this help message
 `);
@@ -174,6 +182,46 @@ function resolveAgentFeedbackEnabled(config, content) {
 	if (nestedAgentBlock) return readBooleanProperty(nestedAgentBlock, "enabled") ?? true;
 	return readBooleanProperty(feedbackBlock, "agent") ?? false;
 }
+function resolveHumanFeedbackEnabled(config, content) {
+	const feedback = config?.feedback;
+	if (typeof feedback === "boolean") return feedback;
+	if (feedback && typeof feedback === "object") return feedback.enabled ?? true;
+	const topLevelBoolean = readTopLevelBooleanProperty(content, "feedback");
+	if (typeof topLevelBoolean === "boolean") return topLevelBoolean;
+	const feedbackBlock = extractNestedObjectLiteral(content, ["feedback"]);
+	if (!feedbackBlock) return false;
+	return readBooleanProperty(feedbackBlock, "enabled") ?? true;
+}
+function resolveLastUpdatedEnabled(config, content) {
+	const current = config?.lastUpdated;
+	if (typeof current === "boolean") return current;
+	if (current && typeof current === "object") return current.enabled ?? true;
+	const topLevelBoolean = readTopLevelBooleanProperty(content, "lastUpdated");
+	if (typeof topLevelBoolean === "boolean") return topLevelBoolean;
+	const block = extractNestedObjectLiteral(content, ["lastUpdated"]);
+	if (!block) return true;
+	return readBooleanProperty(block, "enabled") ?? true;
+}
+function hasGithubIntegration(config, content) {
+	if (typeof config?.github === "string") return config.github.trim().length > 0;
+	if (config?.github && typeof config.github === "object") return typeof config.github.url === "string" && config.github.url.trim().length > 0;
+	const topLevelString = readTopLevelStringProperty(content, "github");
+	if (typeof topLevelString === "string" && topLevelString.trim().length > 0) return true;
+	const githubBlock = extractNestedObjectLiteral(content, ["github"]);
+	if (!githubBlock) return false;
+	const urlMatch = githubBlock.match(/\burl\s*:\s*["'`]([^"'`]+)["'`]/);
+	return typeof urlMatch?.[1] === "string" && urlMatch[1].trim().length > 0;
+}
+function hasReadingTimeSurface(config, content) {
+	const current = config?.readingTime;
+	if (current === true) return true;
+	if (current && typeof current === "object") return current.enabled !== false;
+	const topLevelBoolean = readTopLevelBooleanProperty(content, "readingTime");
+	if (typeof topLevelBoolean === "boolean") return topLevelBoolean;
+	const block = extractNestedObjectLiteral(content, ["readingTime"]);
+	if (!block) return false;
+	return readBooleanProperty(block, "enabled") ?? true;
+}
 function hasAgentCompactDefaults(config, content) {
 	if (config?.agent?.compact) return true;
 	return extractNestedObjectLiteral(content, ["agent", "compact"]) !== void 0;
@@ -332,12 +380,84 @@ function metadataScore(descriptionCoverage, relatedCoverage) {
 		score: 0
 	};
 }
-function gradeForScore(score) {
+function descriptionScore(descriptionCoverage) {
+	if (descriptionCoverage >= 90) return {
+		status: "pass",
+		score: 15
+	};
+	if (descriptionCoverage >= 75) return {
+		status: "pass",
+		score: 12
+	};
+	if (descriptionCoverage >= 50) return {
+		status: "warn",
+		score: 8
+	};
+	if (descriptionCoverage > 0) return {
+		status: "warn",
+		score: 4
+	};
+	return {
+		status: "warn",
+		score: 0
+	};
+}
+function structureScore(structureCoverage) {
+	if (structureCoverage >= 90) return {
+		status: "pass",
+		score: 15
+	};
+	if (structureCoverage >= 75) return {
+		status: "pass",
+		score: 12
+	};
+	if (structureCoverage >= 50) return {
+		status: "warn",
+		score: 8
+	};
+	if (structureCoverage > 0) return {
+		status: "warn",
+		score: 4
+	};
+	return {
+		status: "warn",
+		score: 0
+	};
+}
+function navigationScore(navigationCoverage) {
+	if (navigationCoverage >= 100) return {
+		status: "pass",
+		score: 15
+	};
+	if (navigationCoverage >= 80) return {
+		status: "pass",
+		score: 12
+	};
+	if (navigationCoverage >= 50) return {
+		status: "warn",
+		score: 8
+	};
+	if (navigationCoverage > 0) return {
+		status: "warn",
+		score: 4
+	};
+	return {
+		status: "fail",
+		score: 0
+	};
+}
+function gradeForAgentScore(score) {
 	if (score >= 90) return "Agent-optimized";
 	if (score >= 75) return "Agent-ready";
 	if (score >= 60) return "Promising";
 	return "Needs work";
 }
+function gradeForHumanScore(score) {
+	if (score >= 90) return "Human-optimized";
+	if (score >= 75) return "Reader-ready";
+	if (score >= 60) return "Promising";
+	return "Needs work";
+}
 function formatStatus(status) {
 	if (status === "pass") return pc.green("PASS");
 	if (status === "warn") return pc.yellow("WARN");
@@ -367,6 +487,47 @@ function buildMetadataCoverage(pages) {
 		relatedCoverage: totalPages === 0 ? 0 : Math.round(relatedPages / totalPages * 100)
 	};
 }
+function countNavigationPages(node) {
+	const urls = /* @__PURE__ */ new Set();
+	const visit = (current) => {
+		if (current.type === "page" && typeof current.url === "string") urls.add(current.url);
+		if (current.index && typeof current.index === "object") {
+			const indexNode = current.index;
+			if (typeof indexNode.url === "string") urls.add(indexNode.url);
+		}
+		const children = Array.isArray(current.children) ? current.children : [];
+		for (const child of children) {
+			if (!child || typeof child !== "object") continue;
+			visit(child);
+		}
+	};
+	visit(node);
+	return urls.size;
+}
+function estimateWordCount(content) {
+	return content.match(/\b[\p{L}\p{N}][\p{L}\p{N}'’-]*\b/gu)?.length ?? 0;
+}
+function hasSectionHeadings(content) {
+	return /^###{0,1}\s+/m.test(content);
+}
+function buildHumanCoverage(pages, navigationPages) {
+	const totalPages = pages.length;
+	const describedPages = pages.filter((page) => typeof page.description === "string" && page.description.trim().length > 0).length;
+	const longPages = pages.filter((page) => estimateWordCount(page.rawContent ?? "") >= 120).length;
+	const structuredLongPages = pages.filter((page) => {
+		const content = page.rawContent ?? "";
+		return estimateWordCount(content) >= 120 && hasSectionHeadings(content);
+	}).length;
+	return {
+		totalPages,
+		describedPages,
+		descriptionCoverage: totalPages === 0 ? 0 : Math.round(describedPages / totalPages * 100),
+		longPages,
+		structuredLongPages,
+		structureCoverage: longPages === 0 ? 100 : Math.round(structuredLongPages / longPages * 100),
+		navigationPages
+	};
+}
 async function loadDocsConfigModuleWithProjectEnv(rootDir, explicitPath) {
 	const env = loadProjectEnv(rootDir);
 	const injectedKeys = Object.entries(env).filter(([key]) => process.env[key] === void 0).map(([key, value]) => {
@@ -405,7 +566,7 @@ async function inspectAgentReadiness(options = {}) {
 			framework,
 			score: 0,
 			maxScore: 100,
-			grade: gradeForScore(0),
+			grade: gradeForAgentScore(0),
 			checks,
 			coverage: {
 				totalPages: 0,
@@ -472,7 +633,88 @@ async function inspectAgentReadiness(options = {}) {
 		contentDir,
 		score,
 		maxScore,
-		grade: gradeForScore(score),
+		grade: gradeForAgentScore(score),
+		checks,
+		coverage,
+		recommendations: checks.map((check) => check.recommendation).filter((recommendation) => Boolean(recommendation)).slice(0, 3)
+	};
+}
+async function inspectHumanReadiness(options = {}) {
+	const rootDir = process.cwd();
+	const files = listProjectFiles(rootDir);
+	const framework = detectFramework(rootDir) ?? detectFrameworkFromFiles(files) ?? "unknown";
+	const configCheckMax = 10;
+	let configPath;
+	try {
+		configPath = resolveDocsConfigPath(rootDir, options.configPath);
+	} catch (error) {
+		const checks = [makeCheck("config", "Docs config", "fail", 0, configCheckMax, error instanceof Error ? error.message : String(error), "Add docs.config.ts[x] or pass --config so the doctor can inspect the docs app.")];
+		return {
+			mode: "human",
+			framework,
+			score: 0,
+			maxScore: 100,
+			grade: gradeForHumanScore(0),
+			checks,
+			coverage: {
+				totalPages: 0,
+				describedPages: 0,
+				descriptionCoverage: 0,
+				longPages: 0,
+				structuredLongPages: 0,
+				structureCoverage: 0,
+				navigationPages: 0
+			},
+			recommendations: checks.map((check) => check.recommendation).filter(Boolean)
+		};
+	}
+	const configContent = readFileSync(configPath, "utf-8");
+	const loadedConfig = await loadDocsConfigModuleWithProjectEnv(rootDir, options.configPath);
+	const config = loadedConfig?.config;
+	const entry = config?.entry ?? readTopLevelStringProperty(configContent, "entry") ?? "docs";
+	const contentDir = config?.contentDir ?? resolveDocsContentDir(rootDir, configContent, entry);
+	const ordering = config?.ordering === "alphabetical" || config?.ordering === "numeric" || Array.isArray(config?.ordering) ? config.ordering : void 0;
+	const siteTitle = typeof config?.nav?.title === "string" ? config.nav.title : readNavTitle(configContent) ?? "Documentation";
+	const searchEnabled = resolveFeatureEnabled(config, configContent, "search");
+	const humanFeedbackEnabled = resolveHumanFeedbackEnabled(config, configContent);
+	const lastUpdatedEnabled = resolveLastUpdatedEnabled(config, configContent);
+	const githubEnabled = hasGithubIntegration(config, configContent);
+	const readingTimeEnabled = hasReadingTimeSurface(config, configContent);
+	const source = createFilesystemDocsMcpSource({
+		rootDir,
+		entry,
+		contentDir,
+		siteTitle,
+		ordering
+	});
+	const coverage = buildHumanCoverage(await Promise.resolve(source.getPages()), countNavigationPages(await Promise.resolve(source.getNavigation())));
+	const descriptionResult = descriptionScore(coverage.descriptionCoverage);
+	const structureResult = structureScore(coverage.structureCoverage);
+	const navigationCoverage = coverage.totalPages === 0 ? 0 : Math.min(100, Math.round(coverage.navigationPages / coverage.totalPages * 100));
+	const navigationResult = navigationScore(navigationCoverage);
+	const checks = [];
+	checks.push(makeCheck("config", "Docs config", "pass", 10, 10, loadedConfig ? `Resolved ${path.relative(rootDir, loadedConfig.path).replace(/\\/g, "/")} and evaluated the config module.` : `Resolved ${path.relative(rootDir, configPath).replace(/\\/g, "/")} using static parsing fallback.`));
+	const contentDirAbs = path.resolve(rootDir, contentDir);
+	checks.push(coverage.totalPages > 0 ? makeCheck("content", "Docs content", "pass", 15, 15, `Found ${coverage.totalPages} docs page${coverage.totalPages === 1 ? "" : "s"} in ${path.relative(rootDir, contentDirAbs).replace(/\\/g, "/")}.`) : makeCheck("content", "Docs content", "fail", 0, 15, `No folder-based docs pages were found in ${path.relative(rootDir, contentDirAbs).replace(/\\/g, "/")}.`, "Add index/page MDX files under the configured contentDir so the human docs site has pages to render."));
+	checks.push(makeCheck("navigation", "Navigation coverage", navigationResult.status, navigationResult.score, 15, coverage.totalPages > 0 ? `The generated docs navigation exposes ${coverage.navigationPages}/${coverage.totalPages} page entries (${navigationCoverage}% coverage).` : "No docs pages were available to score navigation coverage.", navigationCoverage >= 100 ? void 0 : "Make sure every important docs page is reachable from the generated navigation tree and not stranded outside the main docs flow."));
+	checks.push(makeCheck("descriptions", "Page descriptions", descriptionResult.status, descriptionResult.score, 15, coverage.totalPages > 0 ? `${coverage.describedPages}/${coverage.totalPages} pages include a description (${coverage.descriptionCoverage}% coverage).` : "No docs pages were available to score descriptions.", coverage.descriptionCoverage >= 75 ? void 0 : "Add frontmatter descriptions to more pages so readers get better search snippets, summaries, and page introductions."));
+	checks.push(makeCheck("structure", "Page structure", structureResult.status, structureResult.score, 15, coverage.longPages > 0 ? `${coverage.structuredLongPages}/${coverage.longPages} longer pages include section headings (${coverage.structureCoverage}% coverage).` : "No longer docs pages required section-heading checks.", coverage.structureCoverage >= 75 ? void 0 : "Break longer pages into clearer sections with H2/H3 headings so readers can scan and navigate without hitting a wall of text."));
+	checks.push(searchEnabled ? makeCheck("search", "Search surface", "pass", 10, 10, "Search is enabled for the docs site.") : makeCheck("search", "Search surface", "warn", 0, 10, "Search is disabled in docs config.", "Enable search so readers can jump directly to the right page instead of relying only on sidebar browsing."));
+	const trustScore = (githubEnabled ? 5 : 0) + (lastUpdatedEnabled ? 5 : 0);
+	checks.push(makeCheck("trust", "Trust signals", trustScore === 10 ? "pass" : "warn", trustScore, 10, githubEnabled && lastUpdatedEnabled ? "Edit links and last-updated metadata are configured." : githubEnabled ? "Edit links are configured, but last-updated metadata is not enabled." : lastUpdatedEnabled ? "Last-updated metadata is enabled, but edit links are not configured." : "Edit links and last-updated metadata are not configured.", trustScore === 10 ? void 0 : "Configure GitHub edit links and/or lastUpdated so readers can trust freshness and find the source of truth faster."));
+	checks.push(humanFeedbackEnabled ? makeCheck("feedback", "Reader feedback", "pass", 5, 5, "Built-in page feedback is enabled for the docs site.") : makeCheck("feedback", "Reader feedback", "warn", 0, 5, "Built-in page feedback is not enabled.", "Enable feedback if you want readers to leave quick page-level quality signals without opening an issue."));
+	checks.push(readingTimeEnabled ? makeCheck("reading-time", "Reading-time cues", "pass", 5, 5, "Reading time is configured for the docs site.") : makeCheck("reading-time", "Reading-time cues", "warn", 0, 5, "Reading time is not enabled.", "Enable readingTime if you want readers to get a quick effort estimate before they dive into longer pages."));
+	const score = checks.reduce((total, check) => total + check.score, 0);
+	const maxScore = checks.reduce((total, check) => total + check.maxScore, 0);
+	return {
+		mode: "human",
+		framework,
+		configPath: path.relative(rootDir, configPath).replace(/\\/g, "/"),
+		entry,
+		contentDir,
+		score,
+		maxScore,
+		grade: gradeForHumanScore(score),
 		checks,
 		coverage,
 		recommendations: checks.map((check) => check.recommendation).filter((recommendation) => Boolean(recommendation)).slice(0, 3)
@@ -497,7 +739,29 @@ function printAgentDoctorReport(report) {
 	console.log();
 	console.log(pc.dim(`Expected public surfaces: ${DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE}, ${DEFAULT_AGENT_SPEC_WELL_KNOWN_ROUTE}, ${DEFAULT_LLMS_TXT_ROUTE}, ${DEFAULT_LLMS_FULL_TXT_ROUTE}, ${DEFAULT_SKILL_MD_ROUTE}, ${DEFAULT_MCP_PUBLIC_ROUTE}`));
 }
+function printHumanDoctorReport(report) {
+	console.log(`${pc.bold("@farming-labs/docs doctor")} ${pc.dim("—")} ${pc.bold("site")}`);
+	console.log();
+	console.log(`${pc.bold("Score:")} ${pc.cyan(`${report.score}/${report.maxScore}`)} ${pc.dim(`(${report.grade})`)}`);
+	console.log(`${pc.bold("Framework:")} ${report.framework} ${pc.dim("•")} ${pc.bold("Entry:")} ${report.entry ?? "docs"} ${pc.dim("•")} ${pc.bold("Content:")} ${report.contentDir ?? "-"}`);
+	console.log(`${pc.bold("Described pages:")} ${report.coverage.describedPages}/${report.coverage.totalPages} pages ${pc.dim(`(${report.coverage.descriptionCoverage}%)`)}`);
+	console.log();
+	for (const check of report.checks) {
+		console.log(`${formatStatus(check.status)} ${check.title} ${pc.dim(`(${check.score}/${check.maxScore})`)}`);
+		console.log(`  ${check.detail}`);
+	}
+	if (report.recommendations.length > 0) {
+		console.log();
+		console.log(pc.bold("Next steps"));
+		for (const recommendation of report.recommendations) console.log(`- ${recommendation}`);
+	}
+}
 async function runDoctor(options = {}) {
+	if (options.mode === "human") {
+		const report = await inspectHumanReadiness(options);
+		printHumanDoctorReport(report);
+		return report;
+	}
 	const report = await inspectAgentReadiness(options);
 	printAgentDoctorReport(report);
 	return report;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farming-labs/docs",
-  "version": "0.1.48",
+  "version": "0.1.49",
   "description": "Modern, flexible MDX-based docs framework — core types, config, and CLI",
   "keywords": [
     "docs",