@farming-labs/docs 0.2.57 → 0.2.58

package/dist/{reading-time-W_Id2ayC.mjs → reading-time-EaVom2cl.mjs}

@@ -1,4 +1,4 @@
-import { S as DEFAULT_MCP_WELL_KNOWN_ROUTE, Xt as normalizePageAgentFrontmatter, Yt as hasStructuredPageAgentContract, c as DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE, f as DEFAULT_DOCS_CONFIG_ROUTE, h as DEFAULT_LLMS_FULL_TXT_ROUTE, i as DEFAULT_AGENT_FEEDBACK_ROUTE, jt as DEFAULT_SITEMAP_XML_ROUTE, kt as DEFAULT_SITEMAP_MD_ROUTE, m as DEFAULT_DOCS_DIAGNOSTICS_ROUTE, t as DEFAULT_AGENTS_MD_ROUTE, v as DEFAULT_LLMS_TXT_ROUTE, w as DEFAULT_SKILL_MD_ROUTE } from "./agent-CxDzPqtl.mjs";
+import { S as DEFAULT_MCP_WELL_KNOWN_ROUTE, c as DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE, f as DEFAULT_DOCS_CONFIG_ROUTE, h as DEFAULT_LLMS_FULL_TXT_ROUTE, i as DEFAULT_AGENT_FEEDBACK_ROUTE, jt as DEFAULT_SITEMAP_XML_ROUTE, kt as DEFAULT_SITEMAP_MD_ROUTE, m as DEFAULT_DOCS_DIAGNOSTICS_ROUTE, t as DEFAULT_AGENTS_MD_ROUTE, v as DEFAULT_LLMS_TXT_ROUTE, w as DEFAULT_SKILL_MD_ROUTE } from "./agent-CxDzPqtl.mjs";
 import { n as DEFAULT_ROBOTS_TXT_ROUTE } from "./robots-DRpoiYAV.mjs";
 import matter from "gray-matter";
 
@@ -393,238 +393,6 @@ async function runDocsAgentConformance(options) {
 	};
 }
 
-//#endregion
-//#region src/metadata.ts
-/**
-* Resolve page title using metadata titleTemplate.
-* %s is replaced with page title.
-*/
-function resolveTitle(pageTitle, metadata) {
-	return (metadata?.titleTemplate ?? "%s").replace("%s", pageTitle);
-}
-/**
-* Resolve OG image URL for a page.
-* Prefers page.openGraph.images[0], then page.ogImage, then config endpoint/default.
-*/
-function resolveOGImage(page, ogConfig, baseUrl) {
-	if (page.openGraph?.images?.length) return resolveImageUrl(page.openGraph.images[0].url, baseUrl);
-	if (!ogConfig?.enabled) return void 0;
-	if (page.ogImage) return resolveImageUrl(page.ogImage, baseUrl);
-	if (ogConfig.type === "dynamic" && ogConfig.endpoint) return `${baseUrl ?? ""}${ogConfig.endpoint}`;
-	return ogConfig.defaultImage;
-}
-function resolveImageUrl(url, baseUrl) {
-	if (url.startsWith("/") || url.startsWith("http")) return url;
-	const base = baseUrl ?? "";
-	return `${base}${base.length > 0 && !base.endsWith("/") ? "/" : ""}${url}`;
-}
-/**
-* Build the Open Graph metadata object for a page.
-* When the page has openGraph in frontmatter, uses it (with title/description filled from page if omitted).
-* Otherwise uses ogImage or config (dynamic endpoint / defaultImage).
-*/
-function buildPageOpenGraph(page, ogConfig, baseUrl) {
-	if (page.openGraph) {
-		const images = page.openGraph.images?.length ? page.openGraph.images.map((img) => ({
-			url: resolveImageUrl(img.url, baseUrl),
-			width: img.width ?? 1200,
-			height: img.height ?? 630
-		})) : void 0;
-		return {
-			title: page.openGraph.title ?? page.title,
-			description: page.openGraph.description ?? page.description,
-			...images && { images }
-		};
-	}
-	const url = resolveOGImage(page, ogConfig, baseUrl);
-	if (!url) return void 0;
-	return {
-		title: page.title,
-		...page.description && { description: page.description },
-		images: [{
-			url,
-			width: 1200,
-			height: 630
-		}]
-	};
-}
-/**
-* Build the Twitter card metadata object for a page.
-* When the page has twitter in frontmatter, uses it.
-* Otherwise builds from ogImage or config (dynamic endpoint).
-*/
-function buildPageTwitter(page, ogConfig, baseUrl) {
-	if (page.twitter) {
-		const images = page.twitter.images?.length ? page.twitter.images.map((url) => resolveImageUrl(url, baseUrl)) : void 0;
-		return {
-			...page.twitter.card && { card: page.twitter.card },
-			...page.twitter.title !== void 0 && { title: page.twitter.title },
-			...page.twitter.description !== void 0 && { description: page.twitter.description },
-			...images && { images }
-		};
-	}
-	const url = resolveOGImage(page, ogConfig, baseUrl);
-	if (!url) return void 0;
-	return {
-		card: "summary_large_image",
-		title: page.title,
-		...page.description && { description: page.description },
-		images: [url]
-	};
-}
-function normalizeBaseUrl(value) {
-	if (!value) return void 0;
-	try {
-		return new URL(value).toString().replace(/\/+$/, "");
-	} catch {
-		return;
-	}
-}
-function absolutizeUrl(url, baseUrl) {
-	const base = normalizeBaseUrl(baseUrl);
-	if (!base) return url;
-	try {
-		return new URL(url, `${base}/`).toString();
-	} catch {
-		return url;
-	}
-}
-function titleFromSegment(segment) {
-	return segment.replace(/\.[a-z0-9]+$/i, "").replace(/[-_]+/g, " ").replace(/\b\w/g, (char) => char.toUpperCase());
-}
-function normalizeRoutePath(url) {
-	try {
-		return new URL(url, "https://farming-labs.local").pathname.replace(/\/+$/, "") || "/";
-	} catch {
-		return `/${url.replace(/^\/+/, "")}`.replace(/\/+$/, "") || "/";
-	}
-}
-function buildDefaultBreadcrumbs(input) {
-	const routePath = normalizeRoutePath(input.url);
-	const entry = (input.entry ?? "docs").replace(/^\/+|\/+$/g, "") || "docs";
-	const segments = routePath.split("/").filter(Boolean);
-	const entryParts = entry.split("/").filter(Boolean);
-	const contentSegments = segments.slice(0, entryParts.length).join("/") === entryParts.join("/") ? segments.slice(entryParts.length) : segments;
-	const breadcrumbs = [{
-		name: titleFromSegment(entryParts[entryParts.length - 1] ?? "Docs"),
-		url: `/${entry}`
-	}];
-	let current = `/${entry}`;
-	contentSegments.forEach((segment, index) => {
-		current = `${current}/${segment}`.replace(/\/+/g, "/");
-		breadcrumbs.push({
-			name: index === contentSegments.length - 1 ? input.title : titleFromSegment(segment),
-			url: current
-		});
-	});
-	return breadcrumbs;
-}
-function normalizeDateModified(value) {
-	if (!value) return void 0;
-	const date = new Date(value);
-	return Number.isNaN(date.getTime()) ? value : date.toISOString();
-}
-function buildAgentContractHowTo(value, fallback) {
-	const agent = normalizePageAgentFrontmatter(value);
-	if (!agent || !hasStructuredPageAgentContract(agent)) return void 0;
-	const steps = [];
-	for (const command of agent.commands ?? []) {
-		const run = typeof command === "string" ? command : command.run;
-		const description = typeof command === "string" ? void 0 : command.description;
-		const cwd = typeof command === "string" ? void 0 : command.cwd;
-		steps.push({
-			"@type": "HowToStep",
-			position: steps.length + 1,
-			name: description ?? "Run command",
-			text: cwd ? `${run} (from ${cwd})` : run
-		});
-	}
-	for (const verification of agent.verification ?? []) {
-		const description = typeof verification === "string" ? verification : verification.description ?? "Verify the result";
-		const details = typeof verification === "string" ? verification : [verification.run, verification.expect ? `Expected: ${verification.expect}` : void 0].filter(Boolean).join(". ");
-		steps.push({
-			"@type": "HowToStep",
-			position: steps.length + 1,
-			name: description,
-			text: details || description
-		});
-	}
-	const supplies = [...(agent.prerequisites ?? []).map((name) => ({
-		"@type": "HowToSupply",
-		name
-	})), ...(agent.files ?? []).map((name) => ({
-		"@type": "HowToSupply",
-		name
-	}))];
-	const about = Object.entries(agent.appliesTo ?? {}).flatMap(([kind, values]) => (typeof values === "string" ? [values] : values ?? []).map((name) => ({
-		"@type": "Thing",
-		name: `${kind}: ${name}`
-	})));
-	return {
-		"@type": "HowTo",
-		name: agent.task ?? fallback.title,
-		...agent.outcome ?? fallback.description ? { description: agent.outcome ?? fallback.description } : {},
-		...about.length > 0 ? { about } : {},
-		...supplies.length > 0 ? { supply: supplies } : {},
-		...steps.length > 0 ? { step: steps } : {}
-	};
-}
-/**
-* Resolve the public docs site URL from existing agent-facing config.
-*
-* The framework intentionally reuses `sitemap.baseUrl`, `llmsTxt.baseUrl`,
-* `robots.baseUrl`, or `ai.docsUrl` instead of requiring another setting.
-*/
-function resolveDocsMetadataBaseUrl(config) {
-	return [
-		typeof config.sitemap === "object" ? config.sitemap.baseUrl : void 0,
-		typeof config.llmsTxt === "object" ? config.llmsTxt.baseUrl : void 0,
-		typeof config.robots === "object" ? config.robots.baseUrl : void 0,
-		config.ai?.docsUrl
-	].map((value) => normalizeBaseUrl(value)).find((value) => Boolean(value));
-}
-/**
-* Build Schema.org JSON-LD for a docs page.
-*
-* The shape follows Vercel's agent readability guidance: a `TechArticle`
-* with title, description, canonical URL, freshness, and breadcrumbs.
-*/
-function buildDocsPageStructuredData(input) {
-	const breadcrumbs = input.breadcrumbs?.length ? input.breadcrumbs : buildDefaultBreadcrumbs(input);
-	const result = {
-		"@context": "https://schema.org",
-		"@type": "TechArticle",
-		headline: input.title,
-		name: input.title,
-		url: absolutizeUrl(input.url, input.baseUrl),
-		mainEntityOfPage: {
-			"@type": "WebPage",
-			"@id": absolutizeUrl(input.url, input.baseUrl)
-		},
-		breadcrumb: {
-			"@type": "BreadcrumbList",
-			itemListElement: breadcrumbs.map((item, index) => ({
-				"@type": "ListItem",
-				position: index + 1,
-				name: item.name,
-				item: absolutizeUrl(item.url, input.baseUrl)
-			}))
-		}
-	};
-	if (input.description) result.description = input.description;
-	const agentContract = buildAgentContractHowTo(input.agent, input);
-	if (agentContract) result.mainEntity = agentContract;
-	const dateModified = normalizeDateModified(input.dateModified);
-	if (dateModified) result.dateModified = dateModified;
-	return result;
-}
-/**
-* Serialize Schema.org JSON-LD for safe insertion into a `<script>` tag.
-*/
-function renderDocsPageStructuredDataJson(input) {
-	return JSON.stringify(buildDocsPageStructuredData(input)).replace(/</g, "\\u003c");
-}
-
 //#endregion
 //#region src/reading-time.ts
 function hasExplicitReadingTime(frontmatter) {
@@ -681,4 +449,4 @@ function resolveReadingTimeFromSource(source, wordsPerMinute, options) {
 }
 
 //#endregion
-export { extendTheme as _, resolveReadingTimeOptions as a, defineDocs as b, buildPageTwitter as c, resolveOGImage as d, resolveTitle as f, createTheme as g, runDocsAgentConformance as h, resolveReadingTimeFromSource as i, renderDocsPageStructuredDataJson as l, createDocsAgentContractCases as m, resolvePageReadingTime as n, buildDocsPageStructuredData as o, DOCS_AGENT_CONTRACT_VERSION as p, resolveReadingTimeFromContent as r, buildPageOpenGraph as s, estimateReadingTimeMinutes as t, resolveDocsMetadataBaseUrl as u, deepMerge as v, resolveChangelogConfig as y };
+export { resolveReadingTimeOptions as a, runDocsAgentConformance as c, deepMerge as d, resolveChangelogConfig as f, resolveReadingTimeFromSource as i, createTheme as l, resolvePageReadingTime as n, DOCS_AGENT_CONTRACT_VERSION as o, defineDocs as p, resolveReadingTimeFromContent as r, createDocsAgentContractCases as s, estimateReadingTimeMinutes as t, extendTheme as u };

package/dist/{review-DZ81wm7h.mjs → review-BEgX7ey7.mjs}

@@ -1,11 +1,12 @@
 import { Jt as getPageAgentFrontmatterIssues, M as buildDocsAgentDiscoverySpec, O as DOCS_CONFIG_MAP_TOP_LEVEL_KEYS, P as buildDocsConfigMap, St as findDocsAudienceMdxIssues, Wt as PAGE_AGENT_CONTRACT_FIELDS, Xt as normalizePageAgentFrontmatter, Yt as hasStructuredPageAgentContract, f as DEFAULT_DOCS_CONFIG_ROUTE, u as DEFAULT_DOCS_API_ROUTE } from "./agent-CxDzPqtl.mjs";
-import "./search-OHp36znm.mjs";
-import { c as resolveDocsReviewConfig, o as ensureDocsReviewWorkflow, s as readDocsReviewConfigFromSource, t as runDocsGoldenTasks } from "./agent-evals-BD17jOqL.mjs";
+import { d as resolveAskAISearchRequestConfig } from "./search-Bo9ubPVO.mjs";
+import { a as resolveDocsMetadataBaseUrl } from "./metadata-3ljRN9MM.mjs";
+import { c as resolveDocsReviewConfig, o as ensureDocsReviewWorkflow, s as readDocsReviewConfigFromSource, t as runDocsGoldenTasks } from "./agent-evals-BW0vEc-F.mjs";
 import { createFilesystemDocsMcpSource, getDocsConfigSchema, resolveDocsMcpConfig } from "./mcp.mjs";
-import "./code-blocks-C9awWzEQ.mjs";
-import { a as loadDocsConfigModuleResultWithProjectEnv, h as resolveDocsContentDir, m as resolveDocsConfigPath, p as readTopLevelStringProperty } from "./config-DZbZiYEa.mjs";
-import { t as detectFramework } from "./utils-DBCCkkJS.mjs";
-import { i as extractAgentBlocks, n as analyzeAgentUsefulness, r as createAgentUsefulnessPagesFromMcp, t as analyzeAgentSurfaceDrift } from "./agent-surface-drift-rGFS38Ak.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-BiUg5Xe_.mjs";
 import matter from "gray-matter";
 import { existsSync, lstatSync, readFileSync, readdirSync } from "node:fs";
 import path from "node:path";
@@ -25,26 +26,6 @@ const IGNORED_DIRS = new Set([
 	"node_modules",
 	"out"
 ]);
-function isPlainRecord(value) {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function resolveGoldenEvaluationTasks(evaluationInput) {
-	if (evaluationInput === void 0 || typeof evaluationInput === "boolean") return void 0;
-	if (!isPlainRecord(evaluationInput)) return { evaluationConfig: evaluationInput };
-	if (evaluationInput.enabled === false) return void 0;
-	if ("enabled" in evaluationInput && typeof evaluationInput.enabled !== "boolean") return evaluationInput;
-	if (!("tasks" in evaluationInput)) return void 0;
-	const runtimeTasks = evaluationInput.tasks;
-	if (!Array.isArray(runtimeTasks)) return runtimeTasks;
-	return runtimeTasks.map((task) => {
-		if (!isPlainRecord(task)) return task;
-		return {
-			...task,
-			tokenBudget: task.tokenBudget ?? evaluationInput.tokenBudget,
-			topK: task.topK ?? evaluationInput.topK
-		};
-	});
-}
 function parseReviewArgs(argv) {
 	const parsed = {};
 	for (let index = 0; index < argv.length; index += 1) {
@@ -182,7 +163,27 @@ async function runReview(options = {}) {
 		});
 	}
 	const evaluationInput = config?.agent?.evaluations;
-	const evaluations = await runDocsGoldenTasks(corpusPages, resolveGoldenEvaluationTasks(evaluationInput));
+	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",

package/dist/{robots-mSc98PMp.mjs → robots-CFlsfYdA.mjs}

@@ -1,7 +1,7 @@
 import "./agent-CxDzPqtl.mjs";
 import { c as renderDocsRobotsGeneratedBlock, f as upsertDocsRobotsGeneratedBlock, i as DOCS_ROBOTS_GENERATED_BLOCK_START, r as DOCS_ROBOTS_GENERATED_BLOCK_END, u as resolveDocsRobotsConfig } from "./robots-DRpoiYAV.mjs";
-import { d as readStringProperty, i as loadDocsConfigModule, m as resolveDocsConfigPath, p as readTopLevelStringProperty, s as readBooleanProperty, t as extractNestedObjectLiteral } from "./config-DZbZiYEa.mjs";
-import { t as detectFramework } from "./utils-DBCCkkJS.mjs";
+import { d as readStringProperty, i as loadDocsConfigModule, m as resolveDocsConfigPath, p as readTopLevelStringProperty, s as readBooleanProperty, t as extractNestedObjectLiteral } from "./config-DASewQ0x.mjs";
+import { t as detectFramework } from "./utils-6UCLxv4B.mjs";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import pc from "picocolors";

package/dist/{search-9uEaC23e.d.mts → search-BblemZl4.d.mts}

@@ -1,4 +1,4 @@
-import { $t as McpDocsSearchConfig, An as TypesenseDocsSearchConfig, At as DocsSearchDocument, D as DocsAnalyticsEventInput, Dt as DocsSearchAdapterFactory, E as DocsAnalyticsEvent, Ft as DocsSearchSourcePage, It as DocsSitemapConfig, L as DocsAskAIMcpConfig, Nt as DocsSearchResult, Ot as DocsSearchChunkingConfig, S as DocsAgentTraceEventInput, T as DocsAnalyticsConfig, Tt as DocsSearchAdapter, an as OpenDocsTarget, bn as ResolvedDocsRelatedLink, f as CustomDocsSearchConfig, ht as DocsObservabilityEventInput, kt as DocsSearchConfig, mt as DocsObservabilityEvent, nn as OpenDocsProvider, pt as DocsObservabilityConfig, r as AlgoliaDocsSearchConfig } from "./types-R-DN23yw.mjs";
+import { An as ResolvedDocsRelatedLink, Bn as TypesenseDocsSearchConfig, Bt as DocsSearchDocument, Ct as DocsObservabilityConfig, F as DocsAnalyticsConfig, Ft as DocsSearchAdapter, Gt as DocsSearchSourcePage, I as DocsAnalyticsEvent, Kt as DocsSitemapConfig, L as DocsAnalyticsEventInput, Lt as DocsSearchAdapterFactory, M as DocsAgentTraceEventInput, Rt as DocsSearchChunkingConfig, Tt as DocsObservabilityEventInput, Ut as DocsSearchResult, f as CustomDocsSearchConfig, fn as OpenDocsProvider, hn as OpenDocsTarget, ln as McpDocsSearchConfig, q as DocsAskAIMcpConfig, r as AlgoliaDocsSearchConfig, wt as DocsObservabilityEvent, zt as DocsSearchConfig } from "./types-C1nPRXqo.mjs";
 
 //#region src/analytics.d.ts
 declare const DOCS_AGENT_TRACE_EVENT_TYPES: readonly ["run.start", "run.end", "run.error", "user.input", "prompt.build", "retrieval.query", "retrieval.result", "retrieval.error", "model.call", "model.response", "model.stream", "model.error", "tool.call", "tool.result", "tool.error", "retry", "timeout", "error", "agent.final"];
@@ -198,6 +198,11 @@ interface DocsAskAIContextResult extends DocsSearchResult {
 }
 interface DocsAskAIContext {
   context: string;
+  /** Structured production context blocks; avoids reparsing markdown horizontal rules. */
+  blocks: Array<{
+    text: string;
+    result: DocsAskAIContextResult;
+  }>;
   results: DocsAskAIContextResult[];
   searchResults: DocsSearchResult[];
   packageHints: DocsAskAIPackageHints;
@@ -230,8 +235,22 @@ declare function performDocsSearch(options: {
   audience?: DocsContentAudience;
   locale?: string;
   pathname?: string;
-  siteTitle?: string;
+  siteTitle?: string; /** Canonical docs URL used to distinguish same-site absolute hits from foreign MCP results. */
+  baseUrl?: string;
   limit?: number;
+  /**
+   * Controls provider failures. Runtime search keeps the resilient `fallback` default;
+   * diagnostics can request `throw` so a broken configured provider cannot be scored as
+   * successful simple search.
+   */
+  failureMode?: "fallback" | "throw";
+  /**
+   * Whether non-simple provider hits are supplemented with exact/local simple results.
+   * Runtime search defaults to true; provider diagnostics can disable supplementation.
+   */
+  supplementExternalResults?: boolean; /** Fail closed on absolute provider hits when no canonical docs origin is available. */
+  strictExternalOrigins?: boolean; /** Optional cancellation signal forwarded to adapters and their managed requests. */
+  signal?: AbortSignal;
 }): Promise<DocsSearchResult[]>;
 declare function buildDocsAskAIContext(options: {
   pages: DocsSearchSourcePage[];
@@ -243,7 +262,10 @@ declare function buildDocsAskAIContext(options: {
   baseUrl?: string;
   limit?: number;
   maxContextChars?: number;
-  maxResultChars?: number;
+  maxResultChars?: number; /** See `performDocsSearch.failureMode`. Defaults to resilient runtime fallback. */
+  searchFailureMode?: "fallback" | "throw"; /** See `performDocsSearch.strictExternalOrigins`. */
+  strictExternalOrigins?: boolean; /** Optional cancellation signal forwarded to the configured search provider. */
+  signal?: AbortSignal;
 }): Promise<DocsAskAIContext>;
 declare function createCustomSearchAdapter(adapter: DocsSearchAdapter | DocsSearchAdapterFactory): CustomDocsSearchConfig;
 //#endregion