@alis-build/harness-eval 0.1.0 → 0.1.2

package/dist/{loader-BCnFJ8rm.js → loader-DcI0KfRX.js}

@@ -6,11 +6,18 @@ import { z } from "zod";
 //#region src/config/paths.ts
 /**
 * Resolve relative paths in suite config against the suite file directory.
+*
+* YAML authors write paths relative to the suite file; this module absolutizes
+* them at load time so the runner and adapters receive filesystem-ready values.
+* Tilde-prefixed paths and inline JSON blobs (settings starting with `{`) are
+* left unchanged.
 */
+/** Resolve a single path relative to `suiteDir` unless already absolute or `~/`. */
 function resolvePath(value, suiteDir) {
 	if (isAbsolute(value) || value.startsWith("~/")) return value;
 	return join(suiteDir, value);
 }
+/** Resolve Claude Code-specific path fields within a config block. */
 function resolveClaudeCodePaths(block, suiteDir) {
 	const resolved = { ...block };
 	if (typeof resolved.mcpConfig === "string") resolved.mcpConfig = resolvePath(resolved.mcpConfig, suiteDir);
@@ -42,9 +49,16 @@ function resolveSuitePaths(suite, suiteFilePath) {
 	for (const cell of suite.matrix) cell.config = resolveConfigPaths(cell.config, suiteDir) ?? cell.config;
 	for (const testCase of suite.cases) testCase.config = resolveConfigPaths(testCase.config, suiteDir);
 }
+/** Parent directory of a suite or grading config file path. */
 function configFileDir(filePath) {
 	return filePath.includes("/") || filePath.includes("\\") ? filePath.replace(/[/\\][^/\\]+$/, "") : ".";
 }
+/**
+* Heuristically resolve env var values that look like relative file paths.
+*
+* Used for grading config where credential or config paths may be expressed
+* relative to the grading YAML location.
+*/
 function resolveEnvPaths(env, baseDir) {
 	const resolved = {};
 	for (const [key, value] of Object.entries(env)) if (value.startsWith("./") || value.startsWith("../") || value.includes("/") && !value.startsWith("http")) resolved[key] = resolvePath(value, baseDir);
@@ -68,7 +82,8 @@ function resolveGradingConfigPaths(config, configFilePath) {
 * zod schemas for the YAML on-disk shape.
 *
 * Config uses a nested layout: generic harness fields at the top level,
-* adapter-specific options under a named key (e.g. `claudeCode`).
+* adapter-specific options under a named key (e.g. `claudeCode`). Validated
+* raw shapes are transformed into runtime types by `src/config/transform.ts`.
 */
 /** Claude Code adapter-specific options (nested under `claudeCode`). */
 const ClaudeCodeConfigSchema = z.object({
@@ -136,6 +151,11 @@ const ReferenceToolCallSchema = z.object({
 	tool_name: z.string().min(1),
 	tool_input: z.unknown()
 });
+/** Reference trajectory in suite YAML — array of steps or object with mode + steps. */
+const ReferenceTrajectorySchema = z.union([z.array(ReferenceToolCallSchema), z.object({
+	tool_name_mode: z.enum(["harness", "bare"]).optional(),
+	steps: z.array(ReferenceToolCallSchema).min(1)
+})]);
 /** A test case. */
 const TestCaseSchema = z.object({
 	id: z.string().min(1),
@@ -143,7 +163,7 @@ const TestCaseSchema = z.object({
 	category: z.string().optional(),
 	notes: z.string().optional(),
 	expectations: z.array(z.string().min(1)).optional(),
-	reference_trajectory: z.array(ReferenceToolCallSchema).optional(),
+	reference_trajectory: ReferenceTrajectorySchema.optional(),
 	human_ratings: z.record(z.string(), z.number()).optional(),
 	assertions: z.array(z.unknown()).min(1),
 	repetitions: z.number().int().positive().optional(),
@@ -192,6 +212,7 @@ function transformSuiteDirectory(raw) {
 function transformTestCases(raw, pathPrefix) {
 	return raw.map((c, i) => transformTestCase(c, `${pathPrefix}[${i}]`));
 }
+/** Merge suite-level parts shared by single-file and directory transforms. */
 function transformSuiteParts(raw) {
 	return {
 		adapter: raw.adapter,
@@ -200,6 +221,21 @@ function transformSuiteParts(raw) {
 		cases: raw.cases.map((c, i) => transformTestCase(c, `cases[${i}]`))
 	};
 }
+/**
+* Normalize reference trajectory YAML into {@link ReferenceTrajectoryConfig}.
+*
+* Accepts a bare step array or `{ tool_name_mode?, steps }` object form.
+*/
+function normalizeReferenceTrajectory(raw, path) {
+	if (raw === void 0) return void 0;
+	if (Array.isArray(raw)) return { steps: raw };
+	if (!isPlainObject(raw) || !Array.isArray(raw.steps)) throw new ConfigError("reference_trajectory must be an array of tool calls or { tool_name_mode?, steps: [...] }", path);
+	return {
+		tool_name_mode: raw.tool_name_mode,
+		steps: raw.steps
+	};
+}
+/** Map raw matrix cell YAML to runtime {@link MatrixCell}. */
 function transformMatrixCell(raw) {
 	return {
 		label: raw.label,
@@ -207,6 +243,7 @@ function transformMatrixCell(raw) {
 		axes: raw.axes
 	};
 }
+/** Map one raw test case to runtime {@link TestCase}, transforming assertions. */
 function transformTestCase(raw, path) {
 	return {
 		id: raw.id,
@@ -214,7 +251,7 @@ function transformTestCase(raw, path) {
 		category: raw.category,
 		notes: raw.notes,
 		expectations: raw.expectations,
-		reference_trajectory: raw.reference_trajectory,
+		reference_trajectory: normalizeReferenceTrajectory(raw.reference_trajectory, `${path}.reference_trajectory`),
 		human_ratings: raw.human_ratings,
 		repetitions: raw.repetitions,
 		config: raw.config,
@@ -223,6 +260,17 @@ function transformTestCase(raw, path) {
 }
 /** Keys that may appear alongside an assertion-type key. Not assertion types themselves. */
 const SIBLING_KEYS = /* @__PURE__ */ new Set(["threshold"]);
+/**
+* Parse optional `threshold` sibling and delegate the assertion body to
+* {@link transformAssertion}.
+*
+* @throws {ConfigError} When the wrapper is not an object, threshold is out of
+*   `[0, 1]`, or the nested assertion fails validation.
+*
+* @example
+* transformThresholdedAssertion({ called: "Read", threshold: 0.9 }, "path")
+* // → { assertion: { type: "called", tool: "Read" }, threshold: 0.9 }
+*/
 function transformThresholdedAssertion(raw, path) {
 	if (!isPlainObject(raw)) throw new ConfigError(`expected object, got ${typeOf(raw)}`, path);
 	const threshold = raw.threshold;
@@ -240,6 +288,19 @@ function transformThresholdedAssertion(raw, path) {
 * Finds the single non-sibling key, dispatches to the per-type transformer.
 * Per-type transformers handle both verbose-object and shortcut-scalar input
 * shapes where applicable.
+*
+* @param raw - Single assertion object from parsed YAML (may include `threshold` sibling).
+* @param path - JSON-path-like location for error messages (e.g. `cases[0].assertions[1]`).
+* @returns Runtime {@link Assertion} tagged union.
+* @throws {ConfigError} When the object has no assertion key, multiple type keys, or an unknown type.
+*
+* @example
+* transformAssertion({ called: "Read" }, "cases[0].assertions[0]")
+* // → { type: "called", tool: "Read" }
+*
+* @example
+* transformAssertion({ called: { tool: "Read", times: ">= 2" } }, "path")
+* // → { type: "called", tool: "Read", times: ">= 2" }
 */
 function transformAssertion(raw, path) {
 	if (!isPlainObject(raw)) throw new ConfigError(`expected object, got ${typeOf(raw)}`, path);
@@ -271,6 +332,22 @@ function transformAssertion(raw, path) {
 		default: throw new ConfigError(`unknown assertion type: ${typeKey}`, path);
 	}
 }
+/**
+* Transform `called` YAML (scalar or `{tool, times?}`) to runtime assertion.
+*
+* @throws {ConfigError} When value is neither string nor object, tool is invalid,
+*   or `times` is not a valid cardinality string.
+*
+* @example
+* // Scalar shortcut
+* transformCalled("mcp__api__search_skills", "path")
+* // → { type: "called", tool: "mcp__api__search_skills" }
+*
+* @example
+* // Verbose form with cardinality
+* transformCalled({ tool: "Read", times: ">= 1" }, "path")
+* // → { type: "called", tool: "Read", times: ">= 1" }
+*/
 function transformCalled(value, path) {
 	if (typeof value === "string") return {
 		type: "called",
@@ -293,6 +370,14 @@ function transformCalled(value, path) {
 		times
 	};
 }
+/**
+* Transform `not_called` YAML (scalar or `{tool}`).
+*
+* @throws {ConfigError} When value is neither string nor object with a valid `tool`.
+*
+* @example
+* transformNotCalled("Bash", "path") // → { type: "not_called", tool: "Bash" }
+*/
 function transformNotCalled(value, path) {
 	if (typeof value === "string") return {
 		type: "not_called",
@@ -304,18 +389,45 @@ function transformNotCalled(value, path) {
 		tool: requireToolPattern(value.tool, `${path}.tool`)
 	};
 }
+/**
+* Transform `called_any_of` — bare tool list or `{tools: [...]}`.
+*
+* @throws {ConfigError} When the value is not an array or `{tools: [...]}` object.
+*
+* @example
+* transformCalledAnyOf(["Read", "Glob"], "path")
+* // → { type: "called_any_of", tools: ["Read", "Glob"] }
+*/
 function transformCalledAnyOf(value, path) {
 	return {
 		type: "called_any_of",
 		tools: requireToolPatternList(value, path)
 	};
 }
+/**
+* Transform `called_all_of` — bare tool list or `{tools: [...]}`.
+*
+* @throws {ConfigError} When the value is not an array or `{tools: [...]}` object.
+*
+* @example
+* transformCalledAllOf({ tools: ["Read", "Grep"] }, "path")
+* // → { type: "called_all_of", tools: ["Read", "Grep"] }
+*/
 function transformCalledAllOf(value, path) {
 	return {
 		type: "called_all_of",
 		tools: requireToolPatternList(value, path)
 	};
 }
+/**
+* Transform `called_before: {first, then}` ordering assertion.
+*
+* @throws {ConfigError} When value is not an object or `first`/`then` are invalid patterns.
+*
+* @example
+* transformCalledBefore({ first: "SearchSkills", then: "LoadSkill" }, "path")
+* // → { type: "called_before", first: "SearchSkills", then: "LoadSkill" }
+*/
 function transformCalledBefore(value, path) {
 	if (!isPlainObject(value)) throw new ConfigError(`expected object with {first, then}, got ${typeOf(value)}`, path);
 	return {
@@ -324,6 +436,19 @@ function transformCalledBefore(value, path) {
 		then: requireToolPattern(value.then, `${path}.then`)
 	};
 }
+/**
+* Transform `sequence` — tool list with optional `strict` flag.
+*
+* @throws {ConfigError} When value is neither a pattern array nor `{tools, strict?}` object.
+*
+* @example
+* // Bare array (non-strict by default)
+* transformSequence(["Read", "Edit"], "path")
+*
+* @example
+* // Explicit strict ordering
+* transformSequence({ tools: ["Read", "Edit"], strict: true }, "path")
+*/
 function transformSequence(value, path) {
 	if (Array.isArray(value)) return {
 		type: "sequence",
@@ -336,6 +461,19 @@ function transformSequence(value, path) {
 		strict: value.strict === void 0 ? void 0 : requireBool(value.strict, `${path}.strict`)
 	};
 }
+/**
+* Transform `called_with: {tool, args}` with predicate validation on args.
+*
+* @throws {ConfigError} When `tool` or `args` is missing/invalid, or `args` fails
+*   {@link validatePredicate}.
+*
+* @example
+* transformCalledWith(
+*   { tool: "Read", args: { path: { contains: "README" } } },
+*   "path",
+* )
+* // → { type: "called_with", tool: "Read", args: { path: { contains: "README" } } }
+*/
 function transformCalledWith(value, path) {
 	if (!isPlainObject(value)) throw new ConfigError(`expected object with {tool, args}, got ${typeOf(value)}`, path);
 	const tool = requireToolPattern(value.tool, `${path}.tool`);
@@ -347,10 +485,32 @@ function transformCalledWith(value, path) {
 		args: value.args
 	};
 }
+/**
+* Transform `responded_without_tool_calls` — accepts true or empty object.
+*
+* @throws {ConfigError} When value is neither `true`, null, nor an empty object.
+*
+* @example
+* transformRespondedWithoutToolCalls(true, "path")
+* // → { type: "responded_without_tool_calls" }
+*/
 function transformRespondedWithoutToolCalls(value, path) {
 	if (value === true || value === null || isPlainObject(value) && Object.keys(value).length === 0) return { type: "responded_without_tool_calls" };
 	throw new ConfigError(`expected true or empty object, got ${JSON.stringify(value)}`, path);
 }
+/**
+* Transform budget assertions (`iterations_within`, `cost_within_usd`, `duration_within_ms`).
+*
+* @throws {ConfigError} When `max` is missing, non-positive, or not a number.
+*
+* @example
+* transformScalarMax(5, "path", "iterations_within")
+* // → { type: "iterations_within", max: 5 }
+*
+* @example
+* transformScalarMax({ max: 2.5 }, "path", "cost_within_usd")
+* // → { type: "cost_within_usd", max: 2.5 }
+*/
 function transformScalarMax(value, path, type) {
 	let max;
 	if (typeof value === "number") max = value;
@@ -362,6 +522,15 @@ function transformScalarMax(value, path, type) {
 		max
 	};
 }
+/**
+* Transform `finished_with` — stop reason string, list, or `{reasons}`.
+*
+* @throws {ConfigError} When value is not a string, string array, or `{reasons}` object.
+*
+* @example
+* transformFinishedWith("end_turn", "path")
+* // → { type: "finished_with", reasons: "end_turn" }
+*/
 function transformFinishedWith(value, path) {
 	if (typeof value === "string") return {
 		type: "finished_with",
@@ -384,6 +553,15 @@ function transformFinishedWith(value, path) {
 	}
 	throw new ConfigError(`expected string, string[], or {reasons: ...}, got ${JSON.stringify(value)}`, path);
 }
+/**
+* Transform `response_contains` / `response_not_contains` scalar or `{text}`.
+*
+* @throws {ConfigError} When value is neither a string nor `{text: string}`.
+*
+* @example
+* transformResponseText("done", "path", "response_contains")
+* // → { type: "response_contains", text: "done" }
+*/
 function transformResponseText(value, path, type) {
 	if (typeof value === "string") return {
 		type,
@@ -395,6 +573,15 @@ function transformResponseText(value, path, type) {
 	};
 	throw new ConfigError(`expected string or {text: string}, got ${JSON.stringify(value)}`, path);
 }
+/**
+* Transform `response_matches: {pattern, flags?}`.
+*
+* @throws {ConfigError} When `pattern` is missing or not a string.
+*
+* @example
+* transformResponseMatches({ pattern: "error\\d+", flags: "i" }, "path")
+* // → { type: "response_matches", pattern: "error\\d+", flags: "i" }
+*/
 function transformResponseMatches(value, path) {
 	if (!isPlainObject(value)) throw new ConfigError(`expected object with {pattern, flags?}, got ${typeOf(value)}`, path);
 	return {
@@ -403,24 +590,57 @@ function transformResponseMatches(value, path) {
 		flags: value.flags === void 0 ? void 0 : requireString(value.flags, `${path}.flags`)
 	};
 }
+/**
+* Transform compound `all_of` assertion list.
+*
+* @throws {ConfigError} When value is not an array or `{assertions: [...]}`.
+*
+* @example
+* transformAllOf([{ called: "Read" }, { not_called: "Bash" }], "path")
+*/
 function transformAllOf(value, path) {
 	return {
 		type: "all_of",
 		assertions: transformCompoundList(value, path)
 	};
 }
+/**
+* Transform compound `any_of` assertion list.
+*
+* @throws {ConfigError} When value is not an array or `{assertions: [...]}`.
+*
+* @example
+* transformAnyOf({ assertions: [{ called: "Read" }, { called: "Glob" }] }, "path")
+*/
 function transformAnyOf(value, path) {
 	return {
 		type: "any_of",
 		assertions: transformCompoundList(value, path)
 	};
 }
+/**
+* Transform compound `not` — single nested assertion, no threshold.
+*
+* The inner assertion uses the same single-key YAML shape as top-level
+* assertions; thresholds apply only at the outer {@link transformThresholdedAssertion} level.
+*
+* @throws {ConfigError} Propagates from nested {@link transformAssertion}.
+*
+* @example
+* transformNot({ called: "Bash" }, "path")
+* // → { type: "not", assertion: { type: "called", tool: "Bash" } }
+*/
 function transformNot(value, path) {
 	return {
 		type: "not",
 		assertion: transformAssertion(value, path)
 	};
 }
+/**
+* Parse compound assertion list from array or `{assertions: [...]}`.
+*
+* @throws {ConfigError} When value is neither form.
+*/
 function transformCompoundList(value, path) {
 	const list = Array.isArray(value) ? value : isPlainObject(value) && Array.isArray(value.assertions) ? value.assertions : null;
 	if (list === null) throw new ConfigError(`expected array or {assertions: [...]}, got ${JSON.stringify(value)}`, path);
@@ -452,6 +672,9 @@ const COMPOUND_OPS = /* @__PURE__ */ new Set([
 *   - single-key object whose key is a leaf op (e.g. `{contains: "x"}`)
 *   - single-key compound (`{any_of: [...]}`, `{all_of: [...]}`, `{not: ...}`)
 *   - multi-key object (descend into fields; each value is a sub-predicate)
+*
+* @throws {ConfigError} When a compound op has a non-array value or a leaf op
+*   has the wrong value type (e.g. non-string `contains`).
 */
 function validatePredicate(raw, path) {
 	if (!isPlainObject(raw)) return;
@@ -474,6 +697,12 @@ function validatePredicate(raw, path) {
 	}
 	for (const [field, sub] of Object.entries(raw)) validatePredicate(sub, `${path}.${field}`);
 }
+/**
+* Validate a leaf predicate operator's value shape at config load time.
+*
+* @throws {ConfigError} When the operator's value has the wrong type or `regex`
+*   is not a valid JavaScript regular expression.
+*/
 function validateLeafOperator(op, value, path) {
 	switch (op) {
 		case "equals": return;
@@ -501,27 +730,33 @@ function validateLeafOperator(op, value, path) {
 		default: return;
 	}
 }
+/** Require a tool pattern string or `{ pattern }` object. */
 function requireToolPattern(value, path) {
 	if (typeof value === "string") return value;
 	if (isPlainObject(value) && typeof value.pattern === "string") return { pattern: value.pattern };
 	throw new ConfigError(`expected string or {pattern: string}, got ${JSON.stringify(value)}`, path);
 }
+/** Require a bare tool pattern array or `{ tools: [...] }` wrapper. */
 function requireToolPatternList(value, path) {
 	const list = Array.isArray(value) ? value : isPlainObject(value) && Array.isArray(value.tools) ? value.tools : null;
 	if (list === null) throw new ConfigError(`expected array of tool patterns or {tools: [...]}, got ${JSON.stringify(value)}`, path);
 	return list.map((v, i) => requireToolPattern(v, `${path}[${i}]`));
 }
+/** Require a string value at `path` or throw {@link ConfigError}. */
 function requireString(value, path) {
 	if (typeof value === "string") return value;
 	throw new ConfigError(`expected string, got ${typeOf(value)}`, path);
 }
+/** Require a boolean value at `path` or throw {@link ConfigError}. */
 function requireBool(value, path) {
 	if (typeof value === "boolean") return value;
 	throw new ConfigError(`expected boolean, got ${typeOf(value)}`, path);
 }
+/** True for non-null, non-array objects (YAML mapping nodes). */
 function isPlainObject(x) {
 	return typeof x === "object" && x !== null && !Array.isArray(x);
 }
+/** Human-readable type name for config error messages. */
 function typeOf(x) {
 	if (x === null) return "null";
 	if (Array.isArray(x)) return "array";
@@ -531,6 +766,9 @@ function typeOf(x) {
 //#region src/config/grading-schema.ts
 /**
 * Zod schema for standalone grading YAML (`grading.yaml`).
+*
+* The top-level `judge` block reuses {@link ConfigPartialSchema} fields plus
+* grader-specific concurrency and system-instruction overrides.
 */
 /** Top-level `judge` block — mirrors harness config fields plus grader concurrency. */
 const JudgeConfigSchema = ConfigPartialSchema.extend({
@@ -544,7 +782,11 @@ const GradingConfigSchema = z.object({ judge: JudgeConfigSchema });
 //#region src/config/grading-loader.ts
 /**
 * Load standalone grading YAML for `harness-eval grade`.
+*
+* Grading config defines the judge subprocess (model, concurrency, Claude Code
+* flags) separately from the suite under test.
 */
+/** Load grading YAML from disk and resolve relative paths. */
 async function loadGradingConfig(filePath) {
 	const absolutePath = resolve(filePath);
 	let content;
@@ -555,6 +797,11 @@ async function loadGradingConfig(filePath) {
 	}
 	return parseGradingConfig(content, absolutePath);
 }
+/**
+* Parse grading YAML from a string.
+*
+* @param sourcePath Optional path for error messages and path resolution.
+*/
 function parseGradingConfig(yamlContent, sourcePath) {
 	let raw;
 	try {
@@ -568,6 +815,7 @@ function parseGradingConfig(yamlContent, sourcePath) {
 	if (sourcePath) resolveGradingConfigPaths(config, sourcePath);
 	return config;
 }
+/** Format a zod validation error with optional source file prefix. */
 function formatZodError$1(err, sourcePath) {
 	return err.issues.map((issue) => {
 		const path = issue.path.length > 0 ? issue.path.join(".") : "(root)";
@@ -578,6 +826,19 @@ function formatZodError$1(err, sourcePath) {
 //#region src/config/loader.ts
 /**
 * Load a `TestSuite` from a YAML file, directory, or string.
+*
+* Supports two on-disk layouts:
+*   - Single file: `suite.yaml` with inline `cases`.
+*   - Directory: `suite.yaml` plus optional `cases/*.yaml` fragments merged
+*     in lexicographic path order.
+*
+* Relative paths in config (MCP config, plugin dirs, etc.) are resolved
+* against the suite file directory after load.
+*/
+/**
+* Load a suite from a file path or directory path.
+*
+* @throws {@link ConfigError} when the path is unreadable or validation fails.
 */
 async function loadSuite(filePath) {
 	const absolutePath = resolve(filePath);
@@ -590,6 +851,7 @@ async function loadSuite(filePath) {
 	if (info.isDirectory()) return loadSuiteDirectory(absolutePath);
 	return loadSuiteFile(absolutePath);
 }
+/** Load and parse a single-file suite (not a directory layout). */
 async function loadSuiteFile(absolutePath) {
 	let content;
 	try {
@@ -599,6 +861,12 @@ async function loadSuiteFile(absolutePath) {
 	}
 	return parseSuite(content, absolutePath);
 }
+/**
+* Load a directory suite: `suite.yaml` plus optional `cases/` YAML files.
+*
+* Cases from `suite.yaml` sort before external case files; within each file,
+* array order is preserved.
+*/
 async function loadSuiteDirectory(dir) {
 	const suiteYamlPath = join(dir, "suite.yaml");
 	let content;
@@ -638,6 +906,11 @@ async function loadSuiteDirectory(dir) {
 	resolveSuitePaths(suite, suiteYamlPath);
 	return suite;
 }
+/**
+* Parse suite YAML from a string (single-file layout with inline cases).
+*
+* @param sourcePath Optional path for error messages and relative path resolution.
+*/
 function parseSuite(yamlContent, sourcePath) {
 	let raw;
 	try {
@@ -651,6 +924,7 @@ function parseSuite(yamlContent, sourcePath) {
 	if (sourcePath) resolveSuitePaths(suite, resolve(sourcePath));
 	return suite;
 }
+/** Parse `suite.yaml` for directory layout (cases may be omitted). */
 function parseSuiteDirectory(yamlContent, sourcePath) {
 	let raw;
 	try {
@@ -672,6 +946,11 @@ function parseCasesFile(yamlContent, sourcePath) {
 	}
 	return transformTestCases(extractRawCases(raw, sourcePath), sourcePath ?? "cases");
 }
+/**
+* Normalize raw YAML into a list of {@link RawTestCase} objects.
+*
+* Accepts a single case, an array, or `{ cases: [...] }`.
+*/
 function extractRawCases(raw, sourcePath) {
 	if (Array.isArray(raw)) return raw.map((item, index) => validateRawCase(item, sourcePath, index));
 	if (raw && typeof raw === "object") {
@@ -681,11 +960,18 @@ function extractRawCases(raw, sourcePath) {
 	}
 	throw new ConfigError("expected a case object, array of cases, or { cases: [...] }", sourcePath);
 }
+/** Validate one raw case object against {@link TestCaseSchema}. */
 function validateRawCase(raw, sourcePath, index) {
 	const validated = TestCaseSchema.safeParse(raw);
 	if (!validated.success) throw new ConfigError(`validation failed:\n${formatZodError(validated.error, sourcePath)}`, sourcePath);
 	return validated.data;
 }
+/**
+* Recursively collect `.yaml` / `.yml` files under `casesDir`.
+*
+* Returns an empty list when the directory does not exist — external cases
+* are optional in directory layout.
+*/
 async function collectCaseYamlFiles(casesDir) {
 	const files = [];
 	async function walk(dir) {
@@ -705,6 +991,7 @@ async function collectCaseYamlFiles(casesDir) {
 	await walk(casesDir);
 	return files.sort();
 }
+/** Format a zod validation error with optional source file prefix. */
 function formatZodError(err, sourcePath) {
 	return err.issues.map((issue) => {
 		const path = issue.path.length > 0 ? issue.path.join(".") : "(root)";
@@ -714,4 +1001,4 @@ function formatZodError(err, sourcePath) {
 //#endregion
 export { parseGradingConfig as a, loadGradingConfig as i, parseCasesFile as n, ConfigError as o, parseSuite as r, loadSuite as t };
 
-//# sourceMappingURL=loader-BCnFJ8rm.js.map
+//# sourceMappingURL=loader-DcI0KfRX.js.map