@farming-labs/docs 0.2.53 → 0.2.54

package/dist/agent-evals-BD17jOqL.mjs

@@ -0,0 +1,1166 @@
+import { a as normalizeAgentScopeValues, i as normalizeAgentLocale, n as agentVersionConstraintsOverlap, o as normalizeAgentVersion, r as normalizeAgentFramework, t as agentVersionConstraintMatches } from "./agent-scope-B8lptqCd.mjs";
+import { buildDocsMcpContext } from "./mcp.mjs";
+import { n as planCodeBlockTargets, r as resolveDocsCodeBlocksValidateConfig, t as extractCodeBlocksFromMarkdown } from "./code-blocks-C9awWzEQ.mjs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join, relative } from "node:path";
+import { createJiti } from "jiti";
+
+//#region src/review.ts
+const DEFAULT_DOCS_REVIEW_WORKFLOW_PATH = ".github/workflows/docs-review.yml";
+const DEFAULT_DOCS_REVIEW_REUSABLE_WORKFLOW_PATH = ".github/workflows/docs-review-reusable.yml";
+const DEFAULT_DOCS_REVIEW_REUSABLE_WORKFLOW = "farming-labs/docs/.github/workflows/docs-review-reusable.yml@main";
+const LOCAL_DOCS_REVIEW_REUSABLE_WORKFLOW = "./.github/workflows/docs-review-reusable.yml";
+const DEFAULT_DOCS_REVIEW_PNPM_VERSION = "10";
+const DEFAULT_DOCS_REVIEW_SCORE_THRESHOLD = 80;
+const DEFAULT_DOCS_REVIEW_CI_NAME = "docs-review";
+const DEFAULT_REVIEW_RULES = {
+	brokenLinks: "error",
+	frontmatter: "error",
+	duplicateSlugs: "error",
+	invalidMdx: "error",
+	configExamples: "warn",
+	codeFenceMetadata: "warn",
+	runnableMetadata: "warn",
+	agentContext: "warn",
+	commandHealth: "warn",
+	relatedCoverage: "suggestion",
+	configConfidence: "warn",
+	agentSurfaceDrift: "error",
+	goldenTasks: "warn"
+};
+const DEFAULT_REVIEW_WEIGHTS = {
+	error: 20,
+	warn: 8,
+	suggestion: 2
+};
+const REVIEW_SEVERITIES = new Set([
+	"off",
+	"suggestion",
+	"warn",
+	"error"
+]);
+const REVIEW_CI_MODES = new Set([
+	"off",
+	"warn",
+	"block"
+]);
+const FILE_EXTS = [
+	"tsx",
+	"ts",
+	"jsx",
+	"js"
+];
+function resolveDocsReviewConfig(review) {
+	if (review === false) return {
+		enabled: false,
+		ci: {
+			enabled: false,
+			name: DEFAULT_DOCS_REVIEW_CI_NAME,
+			mode: "off",
+			annotations: false,
+			comment: false
+		},
+		score: {
+			threshold: DEFAULT_DOCS_REVIEW_SCORE_THRESHOLD,
+			weights: DEFAULT_REVIEW_WEIGHTS
+		},
+		rules: DEFAULT_REVIEW_RULES
+	};
+	const objectConfig = review && typeof review === "object" ? review : {};
+	const ciConfig = objectConfig.ci;
+	const ciObject = ciConfig && typeof ciConfig === "object" ? ciConfig : {};
+	const configuredMode = ciObject.mode;
+	const mode = configuredMode && REVIEW_CI_MODES.has(configuredMode) ? configuredMode : "warn";
+	const enabled = objectConfig.enabled !== false;
+	const ciEnabled = enabled && ciConfig !== false && ciObject.enabled !== false && mode !== "off";
+	return {
+		enabled,
+		ci: {
+			enabled: ciEnabled,
+			name: normalizeCiName(ciObject.name),
+			mode: ciEnabled ? mode : "off",
+			annotations: ciObject.annotations !== false,
+			comment: ciObject.comment !== false
+		},
+		score: {
+			threshold: clampScoreThreshold(objectConfig.score?.threshold),
+			weights: {
+				error: normalizeWeight(objectConfig.score?.weights?.error, DEFAULT_REVIEW_WEIGHTS.error),
+				warn: normalizeWeight(objectConfig.score?.weights?.warn, DEFAULT_REVIEW_WEIGHTS.warn),
+				suggestion: normalizeWeight(objectConfig.score?.weights?.suggestion, DEFAULT_REVIEW_WEIGHTS.suggestion)
+			}
+		},
+		rules: {
+			...DEFAULT_REVIEW_RULES,
+			...normalizeRules(objectConfig.rules)
+		}
+	};
+}
+function buildDocsReviewWorkflow(options = {}) {
+	const packageManager = options.packageManager ?? "npm";
+	const ciName = normalizeCiName(options.ciName);
+	const projectDir = normalizeProjectDir(options.projectDir);
+	const configPath = options.configPath ?? "docs.config.ts";
+	const reusableWorkflow = options.reusableWorkflow ?? DEFAULT_DOCS_REVIEW_REUSABLE_WORKFLOW;
+	const filters = normalizePathFilters(options.pathFilters);
+	const workflowInputs = [
+		["check-name", ciName],
+		["config", configPath],
+		["working-directory", projectDir],
+		["package-manager", packageManager],
+		options.pnpmVersion ? ["pnpm-version", options.pnpmVersion] : void 0,
+		options.buildCommand ? ["build-command", options.buildCommand] : void 0,
+		options.reviewCommand ? ["review-command", options.reviewCommand] : void 0
+	].filter((input) => Boolean(input)).map(([key, value]) => `      ${key}: ${JSON.stringify(value)}`).join("\n");
+	return `# Generated by @farming-labs/docs. You can edit this file.
+name: Docs Review
+
+on:
+  pull_request:
+    paths:
+${filters.map((filter) => `      - ${JSON.stringify(filter)}`).join("\n")}
+
+permissions:
+  contents: read
+  checks: write
+  pull-requests: write
+
+jobs:
+  docs-review:
+    name: ${JSON.stringify(ciName)}
+    uses: ${reusableWorkflow}
+    with:
+${workflowInputs}
+    permissions:
+      contents: read
+      checks: write
+      pull-requests: write
+`;
+}
+function ensureDocsReviewWorkflow(options) {
+	const rootDir = options.rootDir;
+	const repoRoot = findGitRoot(rootDir) ?? rootDir;
+	const workflowRelativePath = options.workflowPath ?? DEFAULT_DOCS_REVIEW_WORKFLOW_PATH;
+	const workflowPath = isAbsolute(workflowRelativePath) ? workflowRelativePath : join(repoRoot, workflowRelativePath);
+	const resultRelativePath = toPosixPath(relative(repoRoot, workflowPath));
+	const review = resolveDocsReviewConfig(options.config?.review ?? readDocsReviewConfigFromSource(options.configContent ?? readConfig(rootDir)));
+	if (!review.enabled || !review.ci.enabled) return {
+		status: "disabled",
+		path: workflowPath,
+		relativePath: resultRelativePath
+	};
+	if (existsSync(workflowPath)) return {
+		status: "exists",
+		path: workflowPath,
+		relativePath: resultRelativePath
+	};
+	const configPath = options.configPath ?? findDocsConfigPath(rootDir);
+	const configContent = options.configContent ?? readConfig(rootDir, configPath);
+	const projectDir = toPosixPath(relative(repoRoot, rootDir)) || ".";
+	const packageManager = detectPackageManager(repoRoot);
+	const workflow = buildDocsReviewWorkflow({
+		packageManager,
+		ciName: review.ci.name,
+		reusableWorkflow: hasLocalDocsWorkspacePackage(repoRoot) ? LOCAL_DOCS_REVIEW_REUSABLE_WORKFLOW : DEFAULT_DOCS_REVIEW_REUSABLE_WORKFLOW,
+		pnpmVersion: detectPnpmVersionFallback(repoRoot, packageManager),
+		projectDir,
+		configPath,
+		buildCommand: detectLocalDocsCliBuildCommand(repoRoot, packageManager),
+		reviewCommand: detectLocalDocsCliReviewCommand(repoRoot, rootDir),
+		pathFilters: buildDocsReviewWorkflowPathFilters({
+			rootDir,
+			repoRoot,
+			config: options.config,
+			configPath,
+			configContent
+		})
+	});
+	mkdirSync(dirname(workflowPath), { recursive: true });
+	writeFileSync(workflowPath, workflow, "utf-8");
+	options.log?.(`[docs] Created ${resultRelativePath} for Docs Review CI.`);
+	return {
+		status: "created",
+		path: workflowPath,
+		relativePath: resultRelativePath
+	};
+}
+function readDocsReviewConfigFromSource(content) {
+	if (!content) return void 0;
+	const rootObject = extractRootObjectLiteral(content) ?? content;
+	const reviewCursor = findTopLevelPropertyValueIndex(rootObject, "review");
+	if (reviewCursor === void 0) return void 0;
+	if (rootObject.startsWith("true", reviewCursor)) return true;
+	if (rootObject.startsWith("false", reviewCursor)) return false;
+	if (rootObject[reviewCursor] !== "{") return void 0;
+	const reviewEnd = findMatchingObjectEnd(rootObject, reviewCursor);
+	if (reviewEnd === void 0) return void 0;
+	const reviewBlock = rootObject.slice(reviewCursor + 1, reviewEnd);
+	const scoreBlock = extractTopLevelObjectLiteral(reviewBlock, "score");
+	const ciCursor = findTopLevelPropertyValueIndex(reviewBlock, "ci");
+	const rulesBlock = extractTopLevelObjectLiteral(reviewBlock, "rules");
+	const ci = ciCursor === void 0 ? void 0 : reviewBlock.startsWith("true", ciCursor) ? true : reviewBlock.startsWith("false", ciCursor) ? false : reviewBlock[ciCursor] === "{" ? readReviewCiObject(reviewBlock, ciCursor) : void 0;
+	return {
+		enabled: readTopLevelBoolean(reviewBlock, "enabled"),
+		score: scoreBlock ? {
+			threshold: readTopLevelNumber(scoreBlock, "threshold"),
+			weights: readReviewWeights(scoreBlock)
+		} : void 0,
+		ci,
+		rules: rulesBlock ? readReviewRules(rulesBlock) : void 0
+	};
+}
+function buildDocsReviewWorkflowPathFilters(options) {
+	const repoRoot = options.repoRoot ?? findGitRoot(options.rootDir) ?? options.rootDir;
+	const configPath = options.configPath ?? findDocsConfigPath(options.rootDir);
+	const configContent = options.configContent ?? readConfig(options.rootDir, configPath);
+	const entry = options.config?.entry ?? readTopLevelString(configContent, "entry") ?? "docs";
+	const contentDir = options.config?.contentDir ?? readTopLevelString(configContent, "contentDir");
+	const projectDir = toPosixPath(relative(repoRoot, options.rootDir));
+	const projectPrefix = projectDir && projectDir !== "." ? `${projectDir}/` : "";
+	const candidates = [
+		prefixPath(projectPrefix, configPath),
+		prefixPath(projectPrefix, `${entry}/**`),
+		prefixPath(projectPrefix, `app/${entry}/**`),
+		prefixPath(projectPrefix, `src/app/${entry}/**`),
+		contentDir ? prefixPath(projectPrefix, `${trimSlashes(contentDir)}/**`) : void 0,
+		prefixPath(projectPrefix, "content/docs/**"),
+		prefixPath(projectPrefix, "src/content/docs/**"),
+		prefixPath(projectPrefix, "src/lib/docs.config.*"),
+		DEFAULT_DOCS_REVIEW_WORKFLOW_PATH,
+		DEFAULT_DOCS_REVIEW_REUSABLE_WORKFLOW_PATH
+	];
+	return Array.from(new Set(candidates.filter((candidate) => Boolean(candidate))));
+}
+function normalizeRules(rules) {
+	if (!rules) return {};
+	const knownRules = new Set(Object.keys(DEFAULT_REVIEW_RULES));
+	return Object.fromEntries(Object.entries(rules).filter((entry) => knownRules.has(entry[0]) && REVIEW_SEVERITIES.has(entry[1])));
+}
+function normalizeWeight(value, fallback) {
+	return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : fallback;
+}
+function normalizeCiName(value) {
+	return value?.trim() || DEFAULT_DOCS_REVIEW_CI_NAME;
+}
+function clampScoreThreshold(value) {
+	if (typeof value !== "number" || !Number.isFinite(value)) return DEFAULT_DOCS_REVIEW_SCORE_THRESHOLD;
+	return Math.min(100, Math.max(0, Math.round(value)));
+}
+function readReviewCiObject(source, cursor) {
+	const end = findMatchingObjectEnd(source, cursor);
+	if (end === void 0) return void 0;
+	const block = source.slice(cursor + 1, end);
+	const mode = readTopLevelString(block, "mode");
+	return {
+		enabled: readTopLevelBoolean(block, "enabled"),
+		name: readTopLevelString(block, "name"),
+		mode: mode && REVIEW_CI_MODES.has(mode) ? mode : void 0,
+		annotations: readTopLevelBoolean(block, "annotations"),
+		comment: readTopLevelBoolean(block, "comment")
+	};
+}
+function readReviewRules(block) {
+	const rules = {};
+	for (const key of Object.keys(DEFAULT_REVIEW_RULES)) {
+		const value = readTopLevelString(block, key);
+		if (value && REVIEW_SEVERITIES.has(value)) rules[key] = value;
+	}
+	return rules;
+}
+function readReviewWeights(block) {
+	const weightsBlock = extractTopLevelObjectLiteral(block, "weights");
+	if (!weightsBlock) return void 0;
+	return {
+		error: readTopLevelNumber(weightsBlock, "error"),
+		warn: readTopLevelNumber(weightsBlock, "warn"),
+		suggestion: readTopLevelNumber(weightsBlock, "suggestion")
+	};
+}
+function detectPackageManager(rootDir) {
+	if (existsSync(join(rootDir, "pnpm-lock.yaml"))) return "pnpm";
+	if (existsSync(join(rootDir, "yarn.lock"))) return "yarn";
+	if (existsSync(join(rootDir, "bun.lock")) || existsSync(join(rootDir, "bun.lockb"))) return "bun";
+	return "npm";
+}
+function detectLocalDocsCliBuildCommand(repoRoot, packageManager) {
+	if (!hasLocalDocsWorkspacePackage(repoRoot)) return void 0;
+	if (packageManager === "pnpm") return "pnpm --filter @farming-labs/docs run build";
+	if (packageManager === "yarn") return "yarn workspace @farming-labs/docs build";
+	if (packageManager === "bun") return "bun run --filter @farming-labs/docs build";
+	return "npm run build --workspace=@farming-labs/docs";
+}
+function detectPnpmVersionFallback(repoRoot, packageManager) {
+	if (packageManager !== "pnpm") return void 0;
+	try {
+		if (JSON.parse(readFileSync(join(repoRoot, "package.json"), "utf-8")).packageManager?.startsWith("pnpm@")) return void 0;
+	} catch {}
+	return DEFAULT_DOCS_REVIEW_PNPM_VERSION;
+}
+function detectLocalDocsCliReviewCommand(repoRoot, rootDir) {
+	if (!hasLocalDocsWorkspacePackage(repoRoot)) return void 0;
+	return `node ${shellQuote(toPosixPath(relative(rootDir, join(repoRoot, "packages", "docs", "dist", "cli", "index.mjs"))) || "./packages/docs/dist/cli/index.mjs")}`;
+}
+function hasLocalDocsWorkspacePackage(repoRoot) {
+	const packageJsonPath = join(repoRoot, "packages", "docs", "package.json");
+	if (!existsSync(packageJsonPath)) return false;
+	try {
+		const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
+		return packageJson.name === "@farming-labs/docs" && Boolean(packageJson.scripts?.build);
+	} catch {
+		return false;
+	}
+}
+function shellQuote(value) {
+	if (/^[A-Za-z0-9_./:-]+$/.test(value)) return value;
+	return `'${value.replaceAll("'", "'\\''")}'`;
+}
+function normalizeProjectDir(value) {
+	if (!value || value === "") return ".";
+	return toPosixPath(value).replace(/\/+$/, "") || ".";
+}
+function normalizePathFilters(filters) {
+	const normalized = (filters && filters.length > 0 ? filters : ["docs.config.*", "app/docs/**"]).map((filter) => toPosixPath(filter).replace(/^\.\/+/, "")).filter(Boolean);
+	return Array.from(new Set(normalized));
+}
+function findGitRoot(start) {
+	let current = start;
+	while (true) {
+		if (existsSync(join(current, ".git"))) return current;
+		const parent = dirname(current);
+		if (parent === current) return void 0;
+		current = parent;
+	}
+}
+function findDocsConfigPath(rootDir) {
+	for (const ext of FILE_EXTS) {
+		const path = `docs.config.${ext}`;
+		if (existsSync(join(rootDir, path))) return path;
+	}
+	return "docs.config.ts";
+}
+function readConfig(rootDir, configPath = findDocsConfigPath(rootDir)) {
+	const fullPath = join(rootDir, configPath);
+	if (!existsSync(fullPath)) return void 0;
+	try {
+		return readFileSync(fullPath, "utf-8");
+	} catch {
+		return;
+	}
+}
+function prefixPath(prefix, value) {
+	return `${prefix}${toPosixPath(value).replace(/^\.\/+/, "")}`;
+}
+function trimSlashes(value) {
+	return toPosixPath(value).replace(/^\/+|\/+$/g, "");
+}
+function toPosixPath(value) {
+	return value.replaceAll("\\", "/");
+}
+function extractRootObjectLiteral(content) {
+	const candidateIndexes = [content.search(/\bdefineDocs\s*\(/), content.search(/\bexport\s+default\b/)].filter((value) => value !== -1);
+	for (const startIndex of candidateIndexes) {
+		const braceStart = content.indexOf("{", startIndex);
+		if (braceStart === -1) continue;
+		const braceEnd = findMatchingObjectEnd(content, braceStart);
+		if (braceEnd !== void 0) return content.slice(braceStart + 1, braceEnd);
+	}
+}
+function extractTopLevelObjectLiteral(content, key) {
+	const cursor = findTopLevelPropertyValueIndex(content, key);
+	if (cursor === void 0 || content[cursor] !== "{") return void 0;
+	const end = findMatchingObjectEnd(content, cursor);
+	return end === void 0 ? void 0 : content.slice(cursor + 1, end);
+}
+function readTopLevelBoolean(content, key) {
+	const cursor = findTopLevelPropertyValueIndex(content, key);
+	if (cursor === void 0) return void 0;
+	if (content.startsWith("true", cursor)) return true;
+	if (content.startsWith("false", cursor)) return false;
+}
+function readTopLevelNumber(content, key) {
+	const cursor = findTopLevelPropertyValueIndex(content, key);
+	if (cursor === void 0) return void 0;
+	const match = content.slice(cursor).match(/^-?\d+(?:\.\d+)?/);
+	if (!match) return void 0;
+	const value = Number(match[0]);
+	return Number.isFinite(value) ? value : void 0;
+}
+function readTopLevelString(content, key) {
+	if (!content) return void 0;
+	const cursor = findTopLevelPropertyValueIndex(content, key);
+	if (cursor === void 0) return void 0;
+	const quote = content[cursor];
+	if (quote !== "\"" && quote !== "'") return void 0;
+	let value = "";
+	for (let index = cursor + 1; index < content.length; index += 1) {
+		const char = content[index];
+		if (char === "\\") {
+			const escaped = content[index + 1];
+			if (escaped) {
+				value += escaped;
+				index += 1;
+			}
+			continue;
+		}
+		if (char === quote) return value;
+		value += char;
+	}
+}
+function findTopLevelPropertyValueIndex(block, key) {
+	let objectDepth = 0;
+	let arrayDepth = 0;
+	let parenDepth = 0;
+	let inString = null;
+	let inLineComment = false;
+	let inBlockComment = false;
+	let escaped = false;
+	for (let index = 0; index < block.length; index += 1) {
+		const char = block[index];
+		const next = block[index + 1];
+		if (inLineComment) {
+			if (char === "\n") inLineComment = false;
+			continue;
+		}
+		if (inBlockComment) {
+			if (char === "*" && next === "/") {
+				inBlockComment = false;
+				index += 1;
+			}
+			continue;
+		}
+		if (inString) {
+			if (escaped) {
+				escaped = false;
+				continue;
+			}
+			if (char === "\\") {
+				escaped = true;
+				continue;
+			}
+			if (char === inString) inString = null;
+			continue;
+		}
+		if (char === "/" && next === "/") {
+			inLineComment = true;
+			index += 1;
+			continue;
+		}
+		if (char === "/" && next === "*") {
+			inBlockComment = true;
+			index += 1;
+			continue;
+		}
+		if (char === "\"" || char === "'" || char === "`") {
+			inString = char;
+			continue;
+		}
+		if (char === "{") {
+			objectDepth += 1;
+			continue;
+		}
+		if (char === "}") {
+			objectDepth = Math.max(0, objectDepth - 1);
+			continue;
+		}
+		if (char === "[") {
+			arrayDepth += 1;
+			continue;
+		}
+		if (char === "]") {
+			arrayDepth = Math.max(0, arrayDepth - 1);
+			continue;
+		}
+		if (char === "(") {
+			parenDepth += 1;
+			continue;
+		}
+		if (char === ")") {
+			parenDepth = Math.max(0, parenDepth - 1);
+			continue;
+		}
+		if (objectDepth !== 0 || arrayDepth !== 0 || parenDepth !== 0) continue;
+		if (!block.startsWith(key, index)) continue;
+		const before = block[index - 1] ?? "";
+		const after = block[index + key.length] ?? "";
+		if (/[A-Za-z0-9_$]/.test(before) || /[A-Za-z0-9_$]/.test(after)) continue;
+		let cursor = index + key.length;
+		while (/\s/.test(block[cursor] ?? "")) cursor += 1;
+		if (block[cursor] !== ":") continue;
+		cursor += 1;
+		while (/\s/.test(block[cursor] ?? "")) cursor += 1;
+		return cursor;
+	}
+}
+function findMatchingObjectEnd(block, start) {
+	let depth = 0;
+	let inString = null;
+	let inLineComment = false;
+	let inBlockComment = false;
+	let escaped = false;
+	for (let index = start; index < block.length; index += 1) {
+		const char = block[index];
+		const next = block[index + 1];
+		if (inLineComment) {
+			if (char === "\n") inLineComment = false;
+			continue;
+		}
+		if (inBlockComment) {
+			if (char === "*" && next === "/") {
+				inBlockComment = false;
+				index += 1;
+			}
+			continue;
+		}
+		if (inString) {
+			if (escaped) {
+				escaped = false;
+				continue;
+			}
+			if (char === "\\") {
+				escaped = true;
+				continue;
+			}
+			if (char === inString) inString = null;
+			continue;
+		}
+		if (char === "/" && next === "/") {
+			inLineComment = true;
+			index += 1;
+			continue;
+		}
+		if (char === "/" && next === "*") {
+			inBlockComment = true;
+			index += 1;
+			continue;
+		}
+		if (char === "\"" || char === "'" || char === "`") {
+			inString = char;
+			continue;
+		}
+		if (char === "{") {
+			depth += 1;
+			continue;
+		}
+		if (char !== "}") continue;
+		depth -= 1;
+		if (depth === 0) return index;
+	}
+}
+
+//#endregion
+//#region src/agent-evals.ts
+const DEFAULT_TOP_K = 5;
+const DEFAULT_TOKEN_BUDGET = 4e3;
+const CONTEXT_SEPARATOR = "\n\n---\n\n";
+const STATIC_CODE_PLAN_CONFIG = resolveDocsCodeBlocksValidateConfig(true);
+const STATIC_JITI = createJiti(import.meta.url, {
+	fsCache: false,
+	moduleCache: false
+});
+const EXECUTABLE_LANGUAGES = new Set([
+	"bash",
+	"curl",
+	"javascript",
+	"js",
+	"jsx",
+	"json",
+	"node",
+	"py",
+	"python",
+	"rb",
+	"ruby",
+	"sh",
+	"shell",
+	"ts",
+	"tsx",
+	"typescript",
+	"zsh"
+]);
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function normalizeRuntimeString(value, path, issues, required = false) {
+	if (value === void 0) {
+		if (required) issues.push(`${path} must be a non-empty string.`);
+		return;
+	}
+	if (typeof value !== "string" || !value.trim()) {
+		issues.push(`${path} must be a non-empty string.`);
+		return;
+	}
+	return value.trim();
+}
+function normalizeRuntimeStringList(value, path, issues, options = {}) {
+	if (value === void 0) {
+		if (options.required) issues.push(`${path} must be a non-empty string array.`);
+		return;
+	}
+	if (!Array.isArray(value)) {
+		issues.push(`${path} must be a string array.`);
+		return [];
+	}
+	const normalized = [];
+	let hasInvalidItem = false;
+	for (const item of value) {
+		if (typeof item !== "string" || !item.trim()) {
+			hasInvalidItem = true;
+			continue;
+		}
+		if (!normalized.includes(item.trim())) normalized.push(item.trim());
+	}
+	if (hasInvalidItem) issues.push(`${path} must contain only non-empty strings.`);
+	if (options.required && normalized.length === 0) issues.push(`${path} must contain at least one source.`);
+	return normalized;
+}
+function normalizeRuntimeNumber(value, path, issues, options = {}) {
+	if (value === void 0) return void 0;
+	if (typeof value !== "number" || !Number.isFinite(value) || options.integer && !Number.isInteger(value) || options.minimum !== void 0 && value < options.minimum || options.maximum !== void 0 && value > options.maximum) {
+		const range = options.minimum !== void 0 || options.maximum !== void 0 ? ` between ${options.minimum ?? "-Infinity"} and ${options.maximum ?? "Infinity"}` : "";
+		issues.push(`${path} must be a finite${options.integer ? " integer" : " number"}${range}.`);
+		return;
+	}
+	return value;
+}
+function normalizeRuntimeFilters(value, path, issues) {
+	if (value === void 0) return void 0;
+	if (!isRecord(value)) {
+		issues.push(`${path} must be an object.`);
+		return;
+	}
+	const framework = normalizeRuntimeString(value.framework, `${path}.framework`, issues);
+	const version = normalizeRuntimeString(value.version, `${path}.version`, issues);
+	const locale = normalizeRuntimeString(value.locale, `${path}.locale`, issues);
+	return framework || version || locale ? {
+		framework,
+		version,
+		locale
+	} : void 0;
+}
+function normalizeRuntimeExamples(value, path, issues) {
+	if (value === void 0) return void 0;
+	if (!Array.isArray(value)) {
+		issues.push(`${path} must be an array.`);
+		return [];
+	}
+	return value.flatMap((item, index) => {
+		const itemPath = `${path}[${index}]`;
+		if (!isRecord(item)) {
+			issues.push(`${itemPath} must be an object.`);
+			return [];
+		}
+		const source = normalizeRuntimeString(item.source, `${itemPath}.source`, issues);
+		const language = normalizeRuntimeString(item.language, `${itemPath}.language`, issues);
+		const framework = normalizeRuntimeString(item.framework, `${itemPath}.framework`, issues);
+		const packageManager = normalizeRuntimeString(item.packageManager, `${itemPath}.packageManager`, issues);
+		const title = normalizeRuntimeString(item.title, `${itemPath}.title`, issues);
+		const includes = normalizeRuntimeStringList(item.includes, `${itemPath}.includes`, issues);
+		let runnable;
+		if (item.runnable !== void 0) if (typeof item.runnable === "boolean") runnable = item.runnable;
+		else issues.push(`${itemPath}.runnable must be a boolean.`);
+		return [{
+			source,
+			language,
+			framework,
+			packageManager,
+			title,
+			runnable,
+			includes
+		}];
+	});
+}
+function normalizeGoldenTaskInput(value, index, initialIssues = []) {
+	const issues = [...initialIssues];
+	const path = `tasks[${index}]`;
+	const input = isRecord(value) ? value : {};
+	if (!isRecord(value)) issues.push(`${path} must be an object.`);
+	const id = normalizeRuntimeString(input.id, `${path}.id`, issues, true) ?? `invalid-task-${index + 1}`;
+	const query = normalizeRuntimeString(input.query, `${path}.query`, issues, true) ?? "";
+	const filters = normalizeRuntimeFilters(input.filters, `${path}.filters`, issues);
+	const tokenBudget = normalizeRuntimeNumber(input.tokenBudget, `${path}.tokenBudget`, issues, {
+		minimum: 1,
+		integer: true
+	});
+	const topK = normalizeRuntimeNumber(input.topK, `${path}.topK`, issues, {
+		minimum: 1,
+		integer: true
+	});
+	const expectPath = `${path}.expect`;
+	const expectation = isRecord(input.expect) ? input.expect : {};
+	if (!isRecord(input.expect)) issues.push(`${expectPath} must be an object.`);
+	const relevantSources = normalizeRuntimeStringList(expectation.relevantSources, `${expectPath}.relevantSources`, issues, { required: true }) ?? [];
+	const allowedSources = normalizeRuntimeStringList(expectation.allowedSources, `${expectPath}.allowedSources`, issues);
+	const forbiddenSources = normalizeRuntimeStringList(expectation.forbiddenSources, `${expectPath}.forbiddenSources`, issues);
+	const requiredCitations = normalizeRuntimeStringList(expectation.requiredCitations, `${expectPath}.requiredCitations`, issues);
+	const minRecallAtK = normalizeRuntimeNumber(expectation.minRecallAtK, `${expectPath}.minRecallAtK`, issues, {
+		minimum: 0,
+		maximum: 1
+	});
+	const maxFirstRelevantRank = normalizeRuntimeNumber(expectation.maxFirstRelevantRank, `${expectPath}.maxFirstRelevantRank`, issues, {
+		minimum: 1,
+		integer: true
+	});
+	const minUsefulByteRatio = normalizeRuntimeNumber(expectation.minUsefulByteRatio, `${expectPath}.minUsefulByteRatio`, issues, {
+		minimum: 0,
+		maximum: 1
+	});
+	const examples = normalizeRuntimeExamples(expectation.examples, `${expectPath}.examples`, issues);
+	const forbidden = forbiddenSources ?? [];
+	for (const [name, sources] of [
+		["relevantSources", relevantSources],
+		["allowedSources", allowedSources ?? []],
+		["requiredCitations", requiredCitations ?? []]
+	]) {
+		const overlaps = sources.filter((source) => forbidden.some((forbiddenSource) => sourceMatches(source, forbiddenSource) || sourceMatches(forbiddenSource, source)));
+		if (overlaps.length > 0) issues.push(`${expectPath}.${name} must not overlap ${expectPath}.forbiddenSources (${overlaps.join(", ")}).`);
+	}
+	return {
+		task: {
+			id,
+			query,
+			filters,
+			tokenBudget,
+			topK,
+			expect: {
+				relevantSources,
+				allowedSources,
+				forbiddenSources,
+				requiredCitations,
+				minRecallAtK,
+				maxFirstRelevantRank,
+				minUsefulByteRatio,
+				examples
+			}
+		},
+		issues
+	};
+}
+function round(value) {
+	return Math.round((value + Number.EPSILON) * 1e4) / 1e4;
+}
+function clamp(value, minimum, maximum) {
+	return Math.min(maximum, Math.max(minimum, value));
+}
+function normalizePositiveInteger(value, fallback, maximum) {
+	if (!Number.isFinite(value)) return fallback;
+	return clamp(Math.floor(value ?? fallback), 1, maximum);
+}
+function safeDecode(value) {
+	try {
+		return decodeURIComponent(value);
+	} catch {
+		return value;
+	}
+}
+function canonicalizeSource(value) {
+	let pathname;
+	let hash;
+	try {
+		const parsed = new URL(value, "https://docs.local");
+		pathname = parsed.pathname;
+		hash = parsed.hash;
+	} catch {
+		const [pathAndQuery = "/", fragment = ""] = value.split("#", 2);
+		pathname = pathAndQuery.split("?", 1)[0] || "/";
+		hash = fragment ? `#${fragment}` : "";
+	}
+	pathname = pathname.replace(/\/{2,}/gu, "/").replace(/\.md$/iu, "");
+	if (pathname !== "/") pathname = pathname.replace(/\/+$/gu, "");
+	if (!pathname.startsWith("/")) pathname = `/${pathname}`;
+	const normalizedHash = hash ? `#${safeDecode(hash.slice(1)).trim().replace(/^#+/u, "").toLowerCase()}` : "";
+	return `${pathname || "/"}${normalizedHash === "#" ? "" : normalizedHash}`;
+}
+function sourcePage(value) {
+	return canonicalizeSource(value).split("#", 1)[0] ?? "/";
+}
+function sourceMatches(actual, expected) {
+	const canonicalActual = canonicalizeSource(actual);
+	const canonicalExpected = canonicalizeSource(expected);
+	return canonicalExpected.includes("#") ? canonicalActual === canonicalExpected : sourcePage(canonicalActual) === sourcePage(canonicalExpected);
+}
+function uniqueCanonicalSources(values) {
+	return Array.from(new Set(values.map(canonicalizeSource)));
+}
+function valuesOverlap(left, right, matches) {
+	return left.some((leftValue) => right.some((rightValue) => matches(leftValue, rightValue)));
+}
+function getPageScope(page) {
+	const topFramework = normalizeAgentScopeValues(page.framework).map(normalizeAgentFramework);
+	const contractFramework = normalizeAgentScopeValues(page.agent?.appliesTo?.framework).map(normalizeAgentFramework);
+	const topVersion = normalizeAgentScopeValues(page.version).map(normalizeAgentVersion);
+	const contractVersion = normalizeAgentScopeValues(page.agent?.appliesTo?.version).map(normalizeAgentVersion);
+	const locale = normalizeAgentScopeValues(page.locale).map(normalizeAgentLocale);
+	return {
+		framework: Array.from(new Set([...topFramework, ...contractFramework])),
+		version: Array.from(new Set([...topVersion, ...contractVersion])),
+		locale,
+		frameworkAmbiguous: topFramework.length > 0 && contractFramework.length > 0 && !valuesOverlap(topFramework, contractFramework, (left, right) => left === right),
+		versionAmbiguous: topVersion.length > 0 && contractVersion.length > 0 && !valuesOverlap(topVersion, contractVersion, agentVersionConstraintsOverlap)
+	};
+}
+function compareCodePoints(left, right) {
+	if (left === right) return 0;
+	return left < right ? -1 : 1;
+}
+function toGoldenSources(sources, relevantSources) {
+	return sources.map((source, index) => ({
+		rank: index + 1,
+		url: canonicalizeSource(source.url),
+		title: source.section ?? source.title,
+		framework: source.framework,
+		version: source.version,
+		utf8Bytes: source.utf8Bytes,
+		relevant: relevantSources.some((expected) => sourceMatches(source.url, expected)),
+		truncated: source.truncated
+	}));
+}
+function toContextCandidates(sources, pagesByUrl) {
+	return sources.flatMap((source) => {
+		const page = pagesByUrl.get(sourcePage(source.pageUrl));
+		if (!page) return [];
+		return [{
+			page,
+			source: canonicalizeSource(source.url),
+			content: source.content,
+			scope: getPageScope(page)
+		}];
+	});
+}
+function extractRenderedCitations(context, sources) {
+	const actual = [];
+	const blockUtf8Bytes = [];
+	let cursor = 0;
+	let layoutIntegrity = true;
+	for (let index = 0; index < sources.length; index += 1) {
+		const attributableStart = cursor;
+		if (index > 0) {
+			if (!context.startsWith(CONTEXT_SEPARATOR, cursor)) {
+				layoutIntegrity = false;
+				break;
+			}
+			cursor += 7;
+		}
+		const contentMarker = `\n\n${sources[index].content}`;
+		const contentStart = context.indexOf(contentMarker, cursor);
+		if (contentStart < cursor) {
+			layoutIntegrity = false;
+			break;
+		}
+		const sourceLines = context.slice(cursor, contentStart).split(/\r?\n/u).map((line) => line.match(/^Source:\s+(.+)$/u)?.[1]?.trim()).filter((source) => Boolean(source));
+		if (sourceLines.length !== 1) layoutIntegrity = false;
+		actual.push(...sourceLines.map(canonicalizeSource));
+		cursor = contentStart + contentMarker.length;
+		blockUtf8Bytes.push(Buffer.byteLength(context.slice(attributableStart, cursor), "utf8"));
+	}
+	if (cursor !== context.length) layoutIntegrity = false;
+	return {
+		actual,
+		layoutIntegrity,
+		blockUtf8Bytes
+	};
+}
+function hasValidStaticSyntax(target) {
+	const language = target.language?.toLowerCase();
+	if (language === "json") try {
+		JSON.parse(target.code);
+		return true;
+	} catch {
+		return false;
+	}
+	if (language === "javascript" || language === "js" || language === "jsx" || language === "node" || language === "typescript" || language === "ts" || language === "tsx") try {
+		const typescript = language === "typescript" || language === "ts" || language === "tsx";
+		const jsx = language === "jsx" || language === "tsx";
+		const transformed = STATIC_JITI.transform({
+			source: target.code,
+			filename: `golden-example.${language === "typescript" ? "ts" : language}`,
+			ts: typescript,
+			jsx,
+			async: true
+		});
+		return !/\bexports\.__JITI_ERROR__\s*=/u.test(transformed);
+	} catch {
+		return false;
+	}
+	return true;
+}
+function isStaticExecutable(target, plan) {
+	const language = target.language?.toLowerCase();
+	if (!target.runnable || !language || !EXECUTABLE_LANGUAGES.has(language)) return false;
+	if (!plan || plan.action === "skip") return false;
+	if (!target.code.trim()) return false;
+	if (target.code.split("\n").some((line) => /^\s*(?:(?:\/\/|#)\s*)?\.\.\.\s*$/u.test(line))) return false;
+	return hasValidStaticSyntax(target);
+}
+async function collectRetrievedExamples(candidates) {
+	const examples = [];
+	for (const candidate of candidates) {
+		const targets = extractCodeBlocksFromMarkdown({
+			source: candidate.content,
+			filePath: candidate.page.sourcePath ?? candidate.page.slug,
+			relativePath: candidate.page.slug
+		});
+		for (const target of targets) examples.push({
+			source: candidate.source,
+			target
+		});
+	}
+	const plans = await planCodeBlockTargets(examples.map((example) => example.target), STATIC_CODE_PLAN_CONFIG);
+	return examples.map((example, index) => ({
+		...example,
+		executable: isStaticExecutable(example.target, plans[index])
+	}));
+}
+function normalizedEqual(left, right) {
+	return (left ?? "").trim().toLowerCase() === (right ?? "").trim().toLowerCase();
+}
+function exampleMatches(expected, actual) {
+	if (expected.source && !sourceMatches(actual.source, expected.source)) return false;
+	if (expected.language && !normalizedEqual(actual.target.language, expected.language)) return false;
+	if (expected.framework && !normalizedEqual(actual.target.framework, expected.framework)) return false;
+	if (expected.packageManager && !normalizedEqual(actual.target.packageManager, expected.packageManager)) return false;
+	if (expected.title && !normalizedEqual(actual.target.title, expected.title)) return false;
+	if (expected.includes?.some((fragment) => !actual.target.code.includes(fragment))) return false;
+	if (expected.runnable === false) return !actual.target.runnable;
+	return actual.executable;
+}
+async function evaluateExamples(expectedExamples, candidates) {
+	const actualExamples = await collectRetrievedExamples(candidates);
+	const claimed = /* @__PURE__ */ new Set();
+	const results = expectedExamples.map((expected) => {
+		const index = actualExamples.findIndex((example, candidateIndex) => !claimed.has(candidateIndex) && exampleMatches(expected, example));
+		if (index < 0) return {
+			expected,
+			executable: false,
+			passed: false
+		};
+		claimed.add(index);
+		const matched = actualExamples[index];
+		return {
+			expected,
+			matchedId: matched.target.id,
+			source: matched.source,
+			executable: matched.executable,
+			passed: true
+		};
+	});
+	const matched = results.filter((result) => result.passed).length;
+	return {
+		expected: expectedExamples.length,
+		matched,
+		executable: results.filter((result) => result.executable).length,
+		results,
+		passed: matched === expectedExamples.length
+	};
+}
+function buildRetrievalMetrics(task, sources, topK) {
+	const expected = uniqueCanonicalSources(task.expect.relevantSources);
+	const forbidden = uniqueCanonicalSources(task.expect.forbiddenSources ?? []);
+	const retrievedRelevant = expected.filter((source) => sources.some((actual) => sourceMatches(actual.url, source))).length;
+	const recallAtK = expected.length > 0 ? retrievedRelevant / expected.length : 0;
+	const firstRelevant = sources.find((source) => source.relevant)?.rank ?? null;
+	const forbiddenSources = sources.filter((source) => forbidden.some((forbiddenSource) => sourceMatches(source.url, forbiddenSource))).map((source) => source.url);
+	const minimumRecall = clamp(task.expect.minRecallAtK ?? 1, 0, 1);
+	const maximumRank = normalizePositiveInteger(task.expect.maxFirstRelevantRank, topK, topK);
+	return {
+		expectedRelevant: expected.length,
+		retrievedRelevant,
+		recallAtK: round(recallAtK),
+		firstRelevantRank: firstRelevant,
+		reciprocalRank: firstRelevant ? round(1 / firstRelevant) : 0,
+		forbiddenSources,
+		passed: expected.length > 0 && recallAtK >= minimumRecall && firstRelevant !== null && firstRelevant <= maximumRank && forbiddenSources.length === 0
+	};
+}
+function buildCitationMetrics(task, context, sources) {
+	const expected = uniqueCanonicalSources(task.expect.requiredCitations ?? task.expect.relevantSources);
+	const allowed = uniqueCanonicalSources([
+		...task.expect.relevantSources,
+		...task.expect.requiredCitations ?? [],
+		...task.expect.allowedSources ?? []
+	]);
+	const extracted = extractRenderedCitations(context, sources);
+	const actual = extracted.actual;
+	const sourceRecords = sources.map((source) => canonicalizeSource(source.url));
+	const missing = expected.filter((expectedSource) => !actual.some((actualSource) => sourceMatches(actualSource, expectedSource)));
+	const unexpected = actual.filter((actualSource) => !allowed.some((allowedSource) => sourceMatches(actualSource, allowedSource)));
+	const correct = actual.filter((actualSource) => allowed.some((allowedSource) => sourceMatches(actualSource, allowedSource))).length;
+	const matchedExpected = expected.filter((expectedSource) => actual.some((actualSource) => sourceMatches(actualSource, expectedSource))).length;
+	const precision = actual.length > 0 ? correct / actual.length : expected.length === 0 ? 1 : 0;
+	const recall = expected.length > 0 ? matchedExpected / expected.length : 1;
+	const integrity = extracted.layoutIntegrity && actual.length === sourceRecords.length && actual.every((source, index) => source === sourceRecords[index]);
+	return {
+		expected,
+		actual,
+		missing,
+		unexpected,
+		precision: round(precision),
+		recall: round(recall),
+		integrity,
+		passed: missing.length === 0 && unexpected.length === 0 && integrity
+	};
+}
+function buildSelectionMetrics(filters, candidates) {
+	const requestedFramework = filters?.framework;
+	const requestedVersion = filters?.version;
+	const framework = requestedFramework ? normalizeAgentFramework(requestedFramework) : void 0;
+	const firstFrameworkMatchRank = framework ? candidates.findIndex((candidate) => candidate.scope.framework.includes(framework)) + 1 || null : null;
+	const firstVersionMatchRank = requestedVersion ? candidates.findIndex((candidate) => candidate.scope.version.some((version) => agentVersionConstraintMatches(requestedVersion, version))) + 1 || null : null;
+	const conflictingSources = candidates.filter((candidate) => framework && candidate.scope.framework.length > 0 && !candidate.scope.framework.includes(framework) || requestedVersion && candidate.scope.version.length > 0 && !candidate.scope.version.some((version) => agentVersionConstraintMatches(requestedVersion, version))).map((candidate) => candidate.source);
+	const ambiguousSources = candidates.filter((candidate) => candidate.scope.frameworkAmbiguous || candidate.scope.versionAmbiguous || Boolean(framework && candidate.scope.framework.length === 0) || Boolean(requestedVersion && candidate.scope.version.length === 0)).map((candidate) => candidate.source);
+	return {
+		requestedFramework,
+		requestedVersion,
+		firstFrameworkMatchRank,
+		firstVersionMatchRank,
+		conflictingSources,
+		ambiguousSources,
+		passed: (!framework || firstFrameworkMatchRank !== null) && (!requestedVersion || firstVersionMatchRank !== null) && conflictingSources.length === 0 && ambiguousSources.length === 0
+	};
+}
+function buildUsageMetrics(task, tokenBudget, context, relevantSources) {
+	const usedUtf8Bytes = context.budget.usedUtf8Bytes;
+	const rendered = extractRenderedCitations(context.context, context.sources);
+	const usefulUtf8Bytes = context.sources.reduce((total, source, index) => relevantSources.some((expected) => sourceMatches(source.url, expected)) ? total + (rendered.blockUtf8Bytes[index] ?? 0) : total, 0);
+	const usefulByteRatio = usedUtf8Bytes > 0 ? usefulUtf8Bytes / usedUtf8Bytes : 0;
+	const minimumUsefulRatio = clamp(task.expect.minUsefulByteRatio ?? 0, 0, 1);
+	const withinBudget = usedUtf8Bytes <= tokenBudget;
+	return {
+		budgetUnit: "utf8-bytes",
+		tokenBudget,
+		usedUtf8Bytes,
+		remainingUtf8Bytes: context.budget.remainingUtf8Bytes,
+		estimatedTokens: Math.ceil(usedUtf8Bytes / 4),
+		conservativeTokenUpperBound: usedUtf8Bytes,
+		usefulUtf8Bytes,
+		usefulByteRatio: round(usefulByteRatio),
+		truncated: context.budget.truncated,
+		withinBudget,
+		passed: withinBudget && usefulByteRatio >= minimumUsefulRatio
+	};
+}
+function calculateTaskScore(report) {
+	const dimensions = [
+		{
+			weight: 30,
+			score: report.retrieval.forbiddenSources.length > 0 ? 0 : (report.retrieval.recallAtK + report.retrieval.reciprocalRank) / 2
+		},
+		{
+			weight: 25,
+			score: report.citations.integrity ? (report.citations.precision + report.citations.recall) / 2 : 0
+		},
+		...report.hasSelectionExpectation ? [{
+			weight: 20,
+			score: report.selection.passed ? 1 : 0
+		}] : [],
+		...report.hasExampleExpectation ? [{
+			weight: 15,
+			score: report.examples.expected > 0 ? report.examples.matched / report.examples.expected : 1
+		}] : [],
+		{
+			weight: 10,
+			score: report.usage.passed ? 1 : 0
+		}
+	];
+	const totalWeight = dimensions.reduce((sum, dimension) => sum + dimension.weight, 0);
+	return round(dimensions.reduce((sum, dimension) => sum + dimension.weight * dimension.score, 0) / totalWeight * 100);
+}
+async function evaluateTask(pages, task, configurationIssues = []) {
+	const topK = normalizePositiveInteger(task.topK, DEFAULT_TOP_K, 50);
+	const tokenBudget = normalizePositiveInteger(task.tokenBudget, DEFAULT_TOKEN_BUDGET, 1e6);
+	const relevantSources = uniqueCanonicalSources(task.expect.relevantSources);
+	const orderedPages = pages.slice().sort((left, right) => compareCodePoints(canonicalizeSource(left.url), canonicalizeSource(right.url)));
+	const pagesByUrl = new Map(orderedPages.map((page) => [sourcePage(page.url), page]));
+	const contextOptions = {
+		pages: orderedPages,
+		query: task.query,
+		framework: task.filters?.framework,
+		version: task.filters?.version,
+		locale: task.filters?.locale,
+		maxResults: topK
+	};
+	const [rankedContext, budgetedContext] = await Promise.all([buildDocsMcpContext({
+		...contextOptions,
+		tokenBudget: Number.MAX_SAFE_INTEGER
+	}), buildDocsMcpContext({
+		...contextOptions,
+		tokenBudget
+	})]);
+	const rankedSources = toGoldenSources(rankedContext.sources, relevantSources);
+	const budgetedSources = toGoldenSources(budgetedContext.sources, relevantSources);
+	const rankedCandidates = toContextCandidates(rankedContext.sources, pagesByUrl);
+	const budgetedCandidates = toContextCandidates(budgetedContext.sources, pagesByUrl);
+	const retrieval = buildRetrievalMetrics(task, rankedSources, topK);
+	const citations = buildCitationMetrics(task, budgetedContext.context, budgetedContext.sources);
+	const selection = buildSelectionMetrics(task.filters, rankedCandidates);
+	const examples = await evaluateExamples(task.expect.examples ?? [], budgetedCandidates);
+	const usage = buildUsageMetrics(task, tokenBudget, budgetedContext, relevantSources);
+	const issues = configurationIssues.map((issue) => `Invalid golden task configuration: ${issue}`);
+	if (relevantSources.length === 0) issues.push("No relevantSources are configured for this task.");
+	if (!retrieval.passed) issues.push("Retrieval did not satisfy the expected recall, rank, or exclusion rules.");
+	if (!citations.passed) issues.push("Rendered citations are missing, unexpected, or do not match source records.");
+	if (!selection.passed) issues.push("Retrieved context is ambiguous or does not explicitly match the requested framework/version.");
+	if (!examples.passed) issues.push("One or more expected runnable examples were not retrieved or are not executable.");
+	if (!usage.passed) issues.push("Context exceeded its budget or did not meet the configured useful-byte ratio.");
+	const passed = configurationIssues.length === 0 && relevantSources.length > 0 && retrieval.passed && citations.passed && selection.passed && examples.passed && usage.passed;
+	const calculatedScore = configurationIssues.length > 0 ? 0 : calculateTaskScore({
+		retrieval,
+		citations,
+		selection,
+		examples,
+		usage,
+		hasSelectionExpectation: Boolean(task.filters?.framework || task.filters?.version),
+		hasExampleExpectation: (task.expect.examples?.length ?? 0) > 0
+	});
+	const score = passed ? calculatedScore : Math.min(calculatedScore, 99);
+	return {
+		id: task.id,
+		query: task.query,
+		status: passed ? "passed" : "failed",
+		passed,
+		score,
+		context: budgetedContext.context,
+		sources: budgetedSources,
+		retrieval,
+		citations,
+		selection,
+		examples,
+		usage,
+		issues
+	};
+}
+/**
+* Run deterministic, offline golden-task evaluations against MCP-ready docs pages.
+* An empty task list is intentionally unmeasured so CI cannot turn absent coverage into a pass.
+*/
+async function runDocsGoldenTasks(pages, tasks) {
+	const runtimeTasks = tasks;
+	if (runtimeTasks === void 0 || Array.isArray(runtimeTasks) && runtimeTasks.length === 0) return {
+		status: "unmeasured",
+		passed: null,
+		score: null,
+		taskCount: 0,
+		passedTaskCount: 0,
+		failedTaskCount: 0,
+		tasks: []
+	};
+	const normalizedTasks = Array.isArray(runtimeTasks) ? runtimeTasks.map((task, index) => normalizeGoldenTaskInput(task, index)) : [normalizeGoldenTaskInput(runtimeTasks, 0, ["agent.evaluations.tasks must be an array."])];
+	const idCounts = normalizedTasks.reduce((counts, input) => {
+		counts.set(input.task.id, (counts.get(input.task.id) ?? 0) + 1);
+		return counts;
+	}, /* @__PURE__ */ new Map());
+	for (const input of normalizedTasks) if ((idCounts.get(input.task.id) ?? 0) > 1) input.issues.push(`task id ${JSON.stringify(input.task.id)} is duplicated.`);
+	const reports = await Promise.all(normalizedTasks.map(({ task, issues }) => evaluateTask(pages, task, issues)));
+	const passedTaskCount = reports.filter((task) => task.passed).length;
+	const failedTaskCount = reports.length - passedTaskCount;
+	return {
+		status: failedTaskCount === 0 ? "passed" : "failed",
+		passed: failedTaskCount === 0,
+		score: round(reports.reduce((sum, task) => sum + task.score, 0) / reports.length),
+		taskCount: reports.length,
+		passedTaskCount,
+		failedTaskCount,
+		tasks: reports
+	};
+}
+
+//#endregion
+export { buildDocsReviewWorkflowPathFilters as a, resolveDocsReviewConfig as c, buildDocsReviewWorkflow as i, DEFAULT_DOCS_REVIEW_SCORE_THRESHOLD as n, ensureDocsReviewWorkflow as o, DEFAULT_DOCS_REVIEW_WORKFLOW_PATH as r, readDocsReviewConfigFromSource as s, runDocsGoldenTasks as t };