@farming-labs/docs 0.2.120 → 0.2.122

package/dist/{golden-evaluations-CLUViycJ.mjs → agent-usefulness.mjs}

@@ -1,6 +1,7 @@
-import { _ as hasStructuredPageAgentContract, v as normalizePageAgentFrontmatter } from "./markdown-sections-9Oxr33b-.mjs";
-import { Dn as resolveDocsAudienceMdxContent, Fn as normalizeAgentVersion, Mn as normalizeAgentFramework, Tn as findDocsAudienceMdxTags, jn as agentVersionConstraintsOverlap } from "./agent-DkAidqtV.mjs";
-import { t as extractCodeBlocksFromMarkdown } from "./code-blocks-GYdvS3BH.mjs";
+import { hasStructuredPageAgentContract, normalizePageAgentFrontmatter } from "./agent-contract.mjs";
+import { agentVersionConstraintsOverlap, normalizeAgentFramework, normalizeAgentVersion } from "./agent-scope.mjs";
+import { findDocsAudienceMdxTags, resolveDocsAudienceMdxContent } from "./audience.mjs";
+import { extractCodeBlocksFromMarkdown } from "./code-blocks.mjs";
 import { isMap, isScalar, isSeq, parseDocument } from "yaml";
 import { existsSync, lstatSync, readFileSync, readdirSync } from "node:fs";
 import path from "node:path";
@@ -1656,290 +1657,4 @@ function clampRatio(value) {
 }
 
 //#endregion
-//#region src/agent-surface-drift.ts
-function isRecord(value) {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function normalizeDotPath(value) {
-	const segments = value.trim().replace(/\[\d+\]/gu, "[]").replace(/^\/+|\/+$/g, "").replaceAll("/", ".").split(".").map((segment) => segment.trim()).filter(Boolean);
-	const normalized = [];
-	for (const segment of segments) {
-		if (/^\d+$/u.test(segment) && normalized.length > 0) {
-			normalized[normalized.length - 1] = `${normalized.at(-1)}[]`;
-			continue;
-		}
-		normalized.push(segment);
-	}
-	return normalized.join(".");
-}
-function collectSchemaPaths(options) {
-	const paths = /* @__PURE__ */ new Set();
-	const visited = /* @__PURE__ */ new Set();
-	const visit = (option) => {
-		if (visited.has(option)) return;
-		visited.add(option);
-		const optionPath = normalizeDotPath(option.path);
-		if (optionPath) paths.add(optionPath);
-		for (const child of option.children ?? []) visit(child);
-	};
-	for (const option of options) visit(option);
-	return paths;
-}
-function schemaCoversConfigPath(schemaPaths, configPath) {
-	if (schemaPaths.has(configPath)) return true;
-	if (configPath.endsWith("[]") && schemaPaths.has(configPath.slice(0, -2))) return true;
-	for (const schemaPath of schemaPaths) {
-		if (!schemaPath.endsWith(".*")) continue;
-		const prefix = schemaPath.slice(0, -1);
-		if (configPath.startsWith(prefix) && configPath.length > prefix.length) return true;
-	}
-	return false;
-}
-function readPath(root, dotPath) {
-	const normalized = normalizeDotPath(dotPath);
-	if (!normalized) return {
-		present: true,
-		value: root
-	};
-	let current = root;
-	for (const segment of normalized.split(".")) {
-		if (!isRecord(current) || !Object.prototype.hasOwnProperty.call(current, segment)) return {
-			present: false,
-			value: void 0
-		};
-		current = current[segment];
-	}
-	return {
-		present: true,
-		value: current
-	};
-}
-function stableJsonValue(value) {
-	if (Array.isArray(value)) return value.map(stableJsonValue);
-	if (!isRecord(value)) return value;
-	return Object.fromEntries(Object.keys(value).sort().map((key) => [key, stableJsonValue(value[key])]));
-}
-function displayValue(value, present = true) {
-	if (!present || value === void 0) return "<missing>";
-	if (typeof value === "string") return JSON.stringify(value);
-	if (typeof value === "number" || typeof value === "boolean" || value === null) return String(value);
-	try {
-		return JSON.stringify(stableJsonValue(value));
-	} catch {
-		return "<unserializable>";
-	}
-}
-function valuesMatch(actual, expected) {
-	if (!actual.present) return false;
-	if (Object.is(actual.value, expected)) return true;
-	if ((Array.isArray(actual.value) || isRecord(actual.value)) && (Array.isArray(expected) || isRecord(expected))) return displayValue(actual.value) === displayValue(expected);
-	return false;
-}
-function mismatchIssue(code, path, expected, actual, label) {
-	const expectedDisplay = displayValue(expected);
-	const actualDisplay = displayValue(actual.value, actual.present);
-	return {
-		code,
-		path,
-		expected: expectedDisplay,
-		actual: actualDisplay,
-		message: `${label} is ${actualDisplay}; expected ${expectedDisplay}.`
-	};
-}
-function compareExpectedValue(issues, discovery, code, path, expected, label) {
-	const actual = readPath(discovery, path);
-	if (!valuesMatch(actual, expected)) issues.push(mismatchIssue(code, path, expected, actual, label));
-}
-/**
-* Compare independently resolved docs values with the public agent discovery and
-* config-schema surfaces. The helper is intentionally pure so doctor, review,
-* and golden evaluations can use the same deterministic drift rules.
-*/
-function analyzeAgentSurfaceDrift(options) {
-	const issues = [];
-	const schemaPaths = collectSchemaPaths(options.schemaOptions);
-	const configPaths = Array.from(new Set(options.configOptionPaths.map(normalizeDotPath).filter(Boolean))).sort();
-	for (const configPath of configPaths) {
-		if (schemaCoversConfigPath(schemaPaths, configPath)) continue;
-		issues.push({
-			code: "config-schema-omission",
-			path: configPath,
-			expected: "documented schema option",
-			actual: "<missing>",
-			message: `Config option ${JSON.stringify(configPath)} is present but missing from the published config schema.`
-		});
-	}
-	const canonicalFields = Array.from(new Set(options.agentContractFields.map((field) => field.trim()).filter(Boolean))).sort();
-	const discoveredFieldsValue = readPath(options.discovery, "agentContract.fields");
-	const discoveredFields = isRecord(discoveredFieldsValue.value) ? Object.keys(discoveredFieldsValue.value).sort() : [];
-	const canonicalFieldSet = new Set(canonicalFields);
-	const discoveredFieldSet = new Set(discoveredFields);
-	for (const field of canonicalFields) {
-		if (discoveredFieldSet.has(field)) continue;
-		const issuePath = `agentContract.fields.${field}`;
-		issues.push({
-			code: "agent-contract-field-missing",
-			path: issuePath,
-			expected: "canonical field",
-			actual: "<missing>",
-			message: `Discovery agent contract is missing canonical field ${JSON.stringify(field)}.`
-		});
-	}
-	for (const field of discoveredFields) {
-		if (canonicalFieldSet.has(field)) continue;
-		const issuePath = `agentContract.fields.${field}`;
-		issues.push({
-			code: "agent-contract-field-unexpected",
-			path: issuePath,
-			expected: "<absent>",
-			actual: "declared field",
-			message: `Discovery agent contract advertises non-canonical field ${JSON.stringify(field)}.`
-		});
-	}
-	compareExpectedValue(issues, options.discovery, "entry-mismatch", "site.entry", options.expected.entry, "Discovery site.entry");
-	compareExpectedValue(issues, options.discovery, "search-enabled-mismatch", "search.enabled", options.expected.search.enabled, "Discovery search.enabled");
-	compareExpectedValue(issues, options.discovery, "search-capability-mismatch", "capabilities.search", options.expected.search.enabled, "Discovery capabilities.search");
-	compareExpectedValue(issues, options.discovery, "search-route-mismatch", "search.endpoint", options.expected.search.endpoint, "Discovery search.endpoint");
-	const expectedAgentSearchEndpoint = options.expected.search.endpoint === null ? null : `${options.expected.search.endpoint}${options.expected.search.endpoint.includes("?") ? "&" : "?"}audience=agent`;
-	compareExpectedValue(issues, options.discovery, "search-audience-mismatch", "search.agentEndpoint", expectedAgentSearchEndpoint, "Discovery search.agentEndpoint");
-	compareExpectedValue(issues, options.discovery, "search-audience-mismatch", "search.audienceParam", "audience", "Discovery search.audienceParam");
-	compareExpectedValue(issues, options.discovery, "search-audience-mismatch", "search.defaultAudience", "human", "Discovery search.defaultAudience");
-	compareExpectedValue(issues, options.discovery, "search-audience-mismatch", "search.supportedAudiences", ["human", "agent"], "Discovery search.supportedAudiences");
-	const expectedStructuredAgentSearchEndpoint = expectedAgentSearchEndpoint === null ? null : `${expectedAgentSearchEndpoint}&response=structured`;
-	const expectedSearchFacetsEndpoint = expectedAgentSearchEndpoint === null ? null : expectedAgentSearchEndpoint.replace("query={query}&audience=agent", "audience=agent&response=facets");
-	const expectedExplainedAgentSearchEndpoint = expectedStructuredAgentSearchEndpoint === null ? null : `${expectedStructuredAgentSearchEndpoint}&explain=true`;
-	for (const [path, expected] of [
-		["search.structuredAgentEndpoint", expectedStructuredAgentSearchEndpoint],
-		["search.explainedAgentEndpoint", expectedExplainedAgentSearchEndpoint],
-		["search.facetsEndpoint", expectedSearchFacetsEndpoint],
-		["search.responseParam", "response"],
-		["search.structuredResponseValue", "structured"],
-		["search.facetsResponseValue", "facets"],
-		["search.responseFormat", "docs-search.v1"],
-		["search.explainParam", "explain"],
-		["search.explainValue", "true"],
-		["search.explanationField", "explanation"],
-		["search.explanationFormat", "docs-search-explanation.v1"],
-		["search.facetsResponseFormat", "docs-search-facets.v1"],
-		["search.filterParams", {
-			framework: "framework",
-			version: "version",
-			package: "package",
-			tags: "tags"
-		}],
-		["search.repeatedFilterParams", [
-			"framework",
-			"version",
-			"package",
-			"tags"
-		]],
-		["search.warningsField", "warnings"],
-		["search.facetParam", "facet"],
-		["search.limitParam", "limit"],
-		["search.cursorParam", "cursor"],
-		["search.nextCursorField", "nextCursor"],
-		["search.hasMoreField", "hasMore"],
-		["search.totalField", "total"]
-	]) compareExpectedValue(issues, options.discovery, "search-scope-mismatch", path, expected, `Discovery ${path}`);
-	compareExpectedValue(issues, options.discovery, "mcp-enabled-mismatch", "mcp.enabled", options.expected.mcp.enabled, "Discovery mcp.enabled");
-	compareExpectedValue(issues, options.discovery, "mcp-capability-mismatch", "capabilities.mcp", options.expected.mcp.enabled, "Discovery capabilities.mcp");
-	compareExpectedValue(issues, options.discovery, "mcp-route-mismatch", "mcp.endpoint", options.expected.mcp.endpoint, "Discovery mcp.endpoint");
-	if (options.expected.mcp.protectedResource !== void 0) {
-		const expectedProtectedResource = options.expected.mcp.protectedResource;
-		const discoveredProtectedResource = readPath(options.discovery, "mcp.protectedResource");
-		if (expectedProtectedResource === null) {
-			if (discoveredProtectedResource.present) issues.push(mismatchIssue("mcp-protected-resource-mismatch", "mcp.protectedResource", void 0, discoveredProtectedResource, "Discovery mcp.protectedResource"));
-		} else for (const field of [
-			"metadataEndpoints",
-			"authorizationServers",
-			"scopesSupported",
-			"requiredScopes"
-		]) compareExpectedValue(issues, options.discovery, "mcp-protected-resource-mismatch", `mcp.protectedResource.${field}`, expectedProtectedResource[field], `Discovery mcp.protectedResource.${field}`);
-	}
-	const expectedToolNames = Object.keys(options.expected.mcp.tools).sort();
-	const expectedToolSet = new Set(expectedToolNames);
-	const discoveredToolsValue = readPath(options.discovery, "mcp.tools");
-	const discoveredTools = isRecord(discoveredToolsValue.value) ? discoveredToolsValue.value : {};
-	for (const toolName of expectedToolNames) {
-		const expected = options.expected.mcp.tools[toolName];
-		const path = `mcp.tools.${toolName}`;
-		const actual = Object.prototype.hasOwnProperty.call(discoveredTools, toolName) ? {
-			present: true,
-			value: discoveredTools[toolName]
-		} : {
-			present: false,
-			value: void 0
-		};
-		if (!valuesMatch(actual, expected)) issues.push(mismatchIssue("mcp-tool-mismatch", path, expected, actual, `Discovery ${path}`));
-	}
-	for (const toolName of Object.keys(discoveredTools).sort()) {
-		if (expectedToolSet.has(toolName)) continue;
-		const path = `mcp.tools.${toolName}`;
-		issues.push({
-			code: "mcp-tool-unexpected",
-			path,
-			expected: "<absent>",
-			actual: displayValue(discoveredTools[toolName]),
-			message: `Discovery MCP tools advertise unexpected tool flag ${JSON.stringify(toolName)}.`
-		});
-	}
-	for (const routePath of Object.keys(options.expected.routes).sort()) {
-		const expected = options.expected.routes[routePath];
-		compareExpectedValue(issues, options.discovery, "route-mismatch", routePath, expected, `Discovery ${routePath}`);
-	}
-	return issues.sort((left, right) => left.path.localeCompare(right.path) || left.code.localeCompare(right.code) || left.message.localeCompare(right.message));
-}
-
-//#endregion
-//#region src/cli/golden-evaluations.ts
-function isPlainRecord(value) {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-/** Normalize the runtime docs.config evaluation shape shared by doctor and review. */
-function resolveGoldenEvaluationInput(evaluationInput) {
-	if (evaluationInput === void 0 || typeof evaluationInput === "boolean") return {
-		tasks: void 0,
-		options: {}
-	};
-	if (!isPlainRecord(evaluationInput)) return {
-		tasks: { evaluationConfig: evaluationInput },
-		options: {}
-	};
-	const options = {
-		surface: evaluationInput.surface,
-		allowNetwork: evaluationInput.allowNetwork,
-		searchTimeoutMs: evaluationInput.searchTimeoutMs,
-		answer: evaluationInput.answer
-	};
-	if (evaluationInput.enabled === false) return {
-		tasks: void 0,
-		options
-	};
-	if ("enabled" in evaluationInput && typeof evaluationInput.enabled !== "boolean") return {
-		tasks: evaluationInput,
-		options
-	};
-	if (!("tasks" in evaluationInput)) return {
-		tasks: void 0,
-		options
-	};
-	const runtimeTasks = evaluationInput.tasks;
-	if (!Array.isArray(runtimeTasks)) return {
-		tasks: runtimeTasks,
-		options
-	};
-	return {
-		tasks: runtimeTasks.map((task) => {
-			if (!isPlainRecord(task)) return task;
-			return {
-				...task,
-				tokenBudget: task.tokenBudget ?? evaluationInput.tokenBudget,
-				topK: task.topK ?? evaluationInput.topK
-			};
-		}),
-		options
-	};
-}
-
-//#endregion
-export { extractAgentBlocks as a, createAgentUsefulnessPagesFromMcp as i, analyzeAgentSurfaceDrift as n, analyzeAgentUsefulness as r, resolveGoldenEvaluationInput as t };
+export { analyzeAgentUsefulness, createAgentUsefulnessPagesFromMcp, extractAgentBlocks };