@copilotkit/aimock 1.42.0 → 1.43.0

package/dist/validate-cli.js

@@ -0,0 +1,924 @@
+import { entryToFixture, renderValidationRef, validateFixtures } from "./fixture-loader.js";
+import { Logger } from "./logger.js";
+import { readFileSync, readdirSync, realpathSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { format, parseArgs } from "node:util";
+
+//#region src/validate-cli.ts
+/**
+* `aimock validate` subcommand — offline fixture lint.
+*
+* Usage: `aimock validate [--strict] [--json] [--] <path> [more paths ...]`
+*
+* Each path is a fixture file or a directory; directories are walked
+* recursively for `*.json` in the same order `--fixtures <dir>` loads them.
+* For each file: read bytes, JSON-parse, require a top-level
+* `{ "fixtures": [...] }` envelope, convert the entries (surfacing the
+* per-entry conversion warnings the server logs), then run the
+* `validateFixtures` rules over that file's entries alone, so its findings
+* are attributed to it.
+*
+* `validateFixtures` is then run a SECOND time over the union of every
+* successfully-parsed file's entries, in load order. Its rules are not all
+* per-fixture: `duplicate userMessage` and the catch-all ordering check look
+* at the other fixtures in the array they are given. Run per file those two
+* cannot see across files, so the findings the union pass adds — a
+* `userMessage` duplicated in two files, a catch-all that is last in its own
+* file but not last overall — are the cross-file ones. They are reported
+* against the file that owns the fixture, with the other file named in the
+* message; findings the per-file pass already made are not repeated.
+*
+* How this compares to the server's `--validate-on-load`, in both directions:
+*  - Stricter: there an unreadable, unparseable or wrong-shape file is
+*    non-fatal — it warns on stderr, contributes zero fixtures, and startup
+*    continues as long as the run loaded at least one fixture from somewhere.
+*    Here every such file fails the run — with one deliberate exception, for
+*    parity: a `*.json` file the WALK turned up that parses but carries no
+*    top-level `fixtures` array is not a fixture file (this package's own
+*    `fixtures/` tree holds aimock config files alongside fixtures), and is
+*    passed over with a note, exactly as the loader passes over it. A file
+*    the caller NAMES is still validated, wrong shape and all. Two walk
+*    hazards the server does not
+*    survive are refused outright rather than mirrored: a `*.json` path that
+*    is not a regular file (a FIFO, a socket, a device) is a per-file error
+*    here, where the server's `readFileSync` blocks on it forever; and a
+*    directory symlink that points back at a directory already being walked
+*    is reported once as a cycle, where the server recurses through it until
+*    the kernel returns ELOOP (~32 levels deep) and loads those levels'
+*    fixtures over and over. One diagnostic here has no counterpart there at
+*    all: an entry whose `match` is a string, a number, a boolean or an array
+*    converts, on both sides, into an EMPTY match — a catch-all answering
+*    every request — and the server loads it without a word. That is a server
+*    bug, not a rule this lint may quietly invent an error for, so it is a
+*    `[warning]` (which `--strict` promotes to a failure) rather than an
+*    error, and the fixture still goes on to the rules exactly as the server
+*    would build it.
+*  - Equal: the `validateFixtures` rules themselves, because of the union
+*    pass above, and the zero-fixture rule — a run whose inputs yield no
+*    fixtures at all is an error here, matching the server's "No fixtures
+*    loaded and validation/strict mode is enabled — aborting." A single
+*    `{"fixtures": []}` file alongside files that do load fixtures is an
+*    error in neither place. Equal too in what the inputs expand to: a path
+*    named twice, and a directory reached both directly and through an
+*    acyclic symlink to it, are validated once per mention, exactly as the
+*    server loads one `--fixtures` source per mention — so the duplicate
+*    fixtures that produces are reported here as the server reports them,
+*    one finding per (fixture, rule), the same count the server logs.
+*
+* A path mentioned more than once in one run is therefore several DIFFERENT
+* loads that happen to share a name, and printing that bare name for each of
+* them made them indistinguishable: a warning read as if a fixture shadowed
+* itself. Each mention is numbered, and every rendering surface carries that
+* number — human lines and their summary, cross-file references, and a
+* `mention` field on each `--json` `files[]` entry. The `<path>[<n>]` suffix
+* is printed only for a path that IS mentioned more than once, because for
+* every other path the name alone already names one load; the `--json` field
+* is always present so a consumer never has to infer it.
+*  - Weaker: this is a static lint. It never starts a server, so it covers
+*    nothing about binding, remote `--fixtures <url>` sources (it reads local
+*    paths only), `--watch` reloads, or any runtime behaviour.
+*
+* Nothing the filesystem or a fixture entry can do is allowed to escape this
+* function: a malformed entry, an unreadable path, a stat failure or a symlink
+* cycle each becomes a per-file `[error]` in the report, and a crash inside
+* either `validateFixtures` pass becomes a file-level or run-level `[error]`,
+* so the run still emits a report (valid JSON under `--json`) and still exits
+* 1. Run-level errors print after the per-file output, and the "no fixtures
+* loaded" one is withheld when a file already reported why it loaded none.
+*
+* Prints human lines by default (`file: [error|warning] #i message`) or a
+* JSON document with `--json`. Everything that contributes to a non-zero exit
+* goes to stderr, so a CI log's stderr always shows the reason; `--json` keeps
+* stdout to the report alone and puts the reason on stderr. The two modes
+* report the same facts: a fatal file is one record that both the stdout
+* tally and `files[].errors` count, and `--json` emits a document for a usage
+* error too — stdout is never empty on a `--json` run, whatever failed it.
+* A path naming a remote source (`https://...`) is refused as unsupported
+* rather than read as a filename. Exit codes:
+* 0 = clean (warnings allowed unless `--strict`), 1 = everything that fails
+* the run — errors / unreadable / unparseable / wrong shape / unwalkable path
+* / no fixtures loaded at all, and a usage error (no paths or an unknown
+* option) too, because every other CLI surface in this package exits 1 on a
+* usage error and nothing here uses sysexits codes. `--help` is handled
+* separately and exits 0.
+*/
+const VALIDATE_HELP = `
+Usage: aimock validate [options] [--] <path> [more paths ...]
+
+Validate aimock fixture files offline. Each path is a fixture file or a
+directory of them (walked recursively for *.json, like --fixtures <dir>).
+Files are checked one at a time and then as one combined set, so the rules
+that span files -- a userMessage duplicated across two files, a catch-all
+that is not last overall -- are reported here as the server reports them.
+
+Where the server's --validate-on-load differs: there an unreadable,
+unparseable or wrong-shape file only warns and startup continues, while here
+every such file fails the run. The one exception, which matches the loader: a
+*.json file found by WALKING a directory that has no top-level "fixtures"
+array is not a fixture file (an aimock config, say) and is skipped with a
+note -- a file you name on the command line is still validated. As on the
+server, a run that loads no fixtures at all is an error. This is a static lint: it starts no server and reads
+local paths only (no remote --fixtures URL).
+
+A path given twice is validated twice, because the server loads one set of
+fixtures per --fixtures it is given; the duplicate fixtures that produces are
+reported as the server reports them, one finding per fixture and rule. Such a
+path is printed as <path>[<n>], numbering its mentions from 1, so each load
+and every reference to its fixtures names one of them (--json reports the
+number as "mention" on every file). A directory symlink pointing back at a
+directory already being walked is a symlink cycle and fails the run; one
+pointing anywhere else is followed, as the server follows it.
+
+Options:
+      --strict          Treat warnings as errors (exit 1 on warnings)
+      --json            Emit a JSON report instead of human lines
+  -h, --help            Show this help message
+      --                Stop option parsing; every later argument is a path
+                        (use this for a path that begins with "-")
+
+Exit codes:
+  0  all files valid (warnings allowed unless --strict)
+  1  anything that failed the run: validation errors; a malformed fixture
+     entry; an unreadable or unparseable file; a named path of the wrong
+     shape (a walked one is skipped instead); a path that
+     cannot be stat'd, read or walked (including a symlink cycle, or a
+     *.json path that is not a regular file); a directory holding no *.json;
+     no fixtures loaded from any input; --strict warnings; or a usage error
+     (no paths given, or an unknown option)
+`.trim();
+/** The indices a ref names, in a fixed order, for identity purposes. */
+function refIndices(ref) {
+	return ref.rule === "duplicate-user-message" ? [ref.shadows] : [ref.shadowsFrom, ref.shadowsThrough];
+}
+/**
+* A path argument that names a remote source rather than a local file: any
+* `scheme://` prefix, not just http(s), so `ftp://` and friends get the same
+* explanation instead of a filesystem error. A Windows drive letter ("C:\\x")
+* has no `//` and is not matched.
+*/
+const REMOTE_SOURCE = /^[a-z][a-z0-9+.-]*:\/\//i;
+/** Render an unknown thrown value as a one-line message. */
+function errText(err) {
+	return err instanceof Error ? err.message : String(err);
+}
+/**
+* Record why a file produced no report at all. A fatal is ONE fact, so it is
+* written once, here, into both shapes that report it: `fatal`, which names
+* the reason, and `errors`, which is what every tally — the human summary
+* line, the `--json` consumer counting `files[].errors` — actually counts.
+* Set on `fatal` alone, the two modes disagreed: stdout said "1 error(s)"
+* while the same run's JSON said `"errors": []`, so a CI script adding up the
+* JSON saw a clean run that had exited 1.
+*
+* The finding carries no `index`: a fatal is about the file, not an entry
+* (see `Finding.index`).
+*/
+function setFatal(report, message) {
+	report.fatal = message;
+	report.errors.push({ message });
+}
+/** A file that never got as far as a report, with its fatal already recorded. */
+function fatalReport(file, mention, message) {
+	const report = {
+		file,
+		mention,
+		fixtures: 0,
+		errors: [],
+		warnings: []
+	};
+	setFatal(report, message);
+	return report;
+}
+/**
+* Logger that routes `warn` AND `error` into caller-supplied sinks instead of
+* the console, so the per-entry conversion diagnostics `entryToFixture` emits
+* land in the report rather than being dropped on the floor — and, under
+* `--json`, never interleave with the JSON document on stdout/stderr.
+* Exported for tests only; it is not part of the package's public API.
+* `info`/`debug` are inert: they are already below this logger's "warn" level,
+* and silencing them explicitly keeps future call sites off stdout too.
+*/
+var CollectingLogger = class CollectingLogger extends Logger {
+	warnSink;
+	errorSink;
+	constructor(warnSink, errorSink) {
+		super("warn");
+		this.warnSink = warnSink;
+		this.errorSink = errorSink;
+	}
+	/**
+	* Serialise exactly as the sink this logger replaces does — byte for byte.
+	* `Logger` writes `console.warn("[aimock]", ...args)`, and console's
+	* formatting IS `util.format`, so the call it makes is
+	* `format("[aimock]", ...args)`: `"[aimock]"` is the FORMAT STRING and holds
+	* no specifiers, which is what makes a caller's own `%s`/`%d` inert and its
+	* arguments plain trailing values. Calling `format(...args)` instead
+	* promoted the caller's message into the format slot — so a message that
+	* happened to contain `%s` (a fixture path, say) swallowed the next
+	* argument — and dropped the `[aimock]` prefix, leaving the report and the
+	* server's own stderr disagreeing about the same diagnostic.
+	* `util.inspect` still renders object arguments readably, which is what
+	* `String(a)` could not do.
+	*/
+	static format(args) {
+		return format("[aimock]", ...args);
+	}
+	warn(...args) {
+		this.warnSink(CollectingLogger.format(args));
+	}
+	error(...args) {
+		this.errorSink(CollectingLogger.format(args));
+	}
+	info(...args) {}
+	debug(...args) {}
+};
+/**
+* Why a `*.json` file the WALK turned up is not a fixture file, or
+* `undefined` if it is one (or if the question cannot be answered cheaply).
+*
+* A directory is not a fixture directory: this package ships `fixtures/`
+* holding both fixture files and eight aimock CONFIG files — the six
+* `fixtures/examples/**\/*-config.json`, `full-suite.json`, and
+* `agui/agui-text-response.json`, whose AG-UI fixtures sit NESTED under
+* `agui` where `--fixtures` cannot see them — which is why the documented
+* `aimock validate ./fixtures/` exited 1 on the package's own tree. The
+* server has the same mixture to deal with and passes over it:
+* `loadFixtureFile` warns "Missing or invalid \"fixtures\" array", returns no
+* fixtures, and startup continues. This mirrors that skip, so a walked
+* directory reports on the fixture files in it and says what it passed over.
+*
+* Non-fixture means the file carries no top-level `fixtures` key at all (or
+* is an aimock config). A `fixtures` key that is present but not an array is
+* a MALFORMED fixture file and still fails the run, as the loader would refuse
+* it. The skip applies ONLY to files the walk discovered — a path the caller named explicitly is still validated, and a
+* wrong-shape file there still fails the run, because naming a file is
+* asking about that file.
+*
+* A file carrying an aimock config section (`configSections`) is named as
+* what it is rather than by what it lacks, because "not a fixture file" on
+* its own is read as "holds no fixtures" — false of `agui`-sectioned configs,
+* which hold AG-UI fixtures that `aimock --config`, not `--fixtures`, serves.
+*
+* Unreadable and unparseable are deliberately NOT skips. Returning
+* `undefined` for them hands the file to `validateOneFile`, which reports the
+* real read error or JSON syntax error — a defect in any `*.json` file, and
+* one no config file has an excuse for either.
+*/
+function nonFixtureSkipReason(file) {
+	let parsed;
+	try {
+		parsed = JSON.parse(readFileSync(file, "utf-8"));
+	} catch {
+		return;
+	}
+	const asConfig = aimockConfigDescription(parsed);
+	if (asConfig !== void 0) return `not a fixture file — ${asConfig}`;
+	if (typeof parsed === "object" && parsed !== null && "fixtures" in parsed) return void 0;
+	return "not a fixture file — no top-level \"fixtures\" key";
+}
+/**
+* The mock sections of `AimockConfig` (config-loader.ts). An object carrying
+* any of them is an aimock config file: `aimock --config <path>` starts a
+* server from it, while `--fixtures <path>` loads nothing from it.
+*/
+const CONFIG_SECTIONS = [
+	"llm",
+	"mcp",
+	"a2a",
+	"agui",
+	"vector",
+	"services"
+];
+/**
+* What a parsed-but-not-fixture-shaped JSON document IS, when it is an aimock
+* config file, or `undefined` when it is not one. Used by both the walk's skip
+* note and the fatal a NAMED file of that shape gets, so the two surfaces
+* describe the same file the same way. The sections found are listed, so an
+* `agui` config is never described as a file holding no fixtures — it holds
+* AG-UI ones, nested where the fixture loader does not look.
+*/
+function aimockConfigDescription(parsed) {
+	if (typeof parsed !== "object" || parsed === null) return void 0;
+	const doc = parsed;
+	const sections = CONFIG_SECTIONS.filter((key) => typeof doc[key] === "object" && doc[key]);
+	if (sections.length === 0) return void 0;
+	return `an aimock config file (${sections.join(", ")}), which "aimock --config" serves and "--fixtures" does not load`;
+}
+/**
+* Collect `*.json` files under `dirPath`, recursing into subdirectories.
+* Mirrors `loadFixturesFromDir`: within a directory the `*.json` files come
+* first in sorted order, then its subdirectories in sorted order, so the
+* reported order matches the server's load order, and the same stat-error
+* handling — a vanished entry (ENOENT) is skipped silently, every other
+* failure is surfaced. Unlike the loader, which only warns, each surfaced
+* failure becomes a `fatal` entry that fails the run, and it is emitted in
+* walk position (an unreadable subdirectory is reported where that
+* subdirectory was reached, not after every file in the tree) so the report
+* reads in encounter order. Entries that are neither directories nor
+* `*.json` files are ignored, as they are by the loader.
+*
+* `ancestors` holds the real paths of the directories this call is nested
+* inside. A directory whose real path is one of them closes a symlink cycle
+* and is reported instead of walked; the server has no such guard and
+* recurses through the cycle until the kernel returns ELOOP. A repeat visit
+* that is NOT an ancestor — `root/link -> root/sub` alongside `root/sub` — is
+* no cycle: it is walked again, because the server walks it again and loads
+* those fixtures twice.
+*
+* A `*.json` entry that is not a regular file (a FIFO, a socket, a device)
+* is a `fatal` entry rather than a target, because reading it is what the
+* containment promise above cannot keep: `readFileSync` on a FIFO with no
+* writer blocks forever, as it does on the server.
+*/
+function collectJsonFiles(dirPath, ancestors, out = []) {
+	let realPath;
+	try {
+		realPath = realpathSync(dirPath);
+	} catch (err) {
+		out.push({
+			file: dirPath,
+			fatal: `Could not resolve directory: ${errText(err)}`
+		});
+		return out;
+	}
+	if (ancestors.includes(realPath)) {
+		out.push({
+			file: dirPath,
+			fatal: `Symlink cycle detected: already walking ${realPath}`
+		});
+		return out;
+	}
+	let names;
+	try {
+		names = readdirSync(dirPath);
+	} catch (err) {
+		out.push({
+			file: dirPath,
+			fatal: `Could not read directory: ${errText(err)}`
+		});
+		return out;
+	}
+	const subdirs = [];
+	for (const name of [...names].sort()) {
+		const fullPath = join(dirPath, name);
+		let stats;
+		try {
+			stats = statSync(fullPath);
+		} catch (err) {
+			if (err.code !== "ENOENT") out.push({
+				file: fullPath,
+				fatal: `Could not stat: ${errText(err)}`
+			});
+			continue;
+		}
+		if (stats.isDirectory()) subdirs.push(name);
+		else if (!name.endsWith(".json")) continue;
+		else if (stats.isFile()) {
+			const skipped = nonFixtureSkipReason(fullPath);
+			out.push(skipped === void 0 ? { file: fullPath } : {
+				file: fullPath,
+				skipped
+			});
+		} else out.push({
+			file: fullPath,
+			fatal: "Not a regular file"
+		});
+	}
+	const chain = [...ancestors, realPath];
+	for (const sub of subdirs) collectJsonFiles(join(dirPath, sub), chain, out);
+	return out;
+}
+/** The entry shape the loader and the server both assume, quoted verbatim. */
+const ENTRY_SHAPE = "every entry needs { \"match\": { ... }, \"response\": { ... } }";
+/** Name a value the way a fixture author would read it back in their JSON. */
+function gotText(value) {
+	if (value === null) return "null";
+	if (value === void 0) return "absent";
+	if (Array.isArray(value)) return "an array";
+	return `a ${typeof value}`;
+}
+/**
+* Classify a raw entry's shape, or return `undefined` when nothing about it is
+* worth saying. Runs before `entryToFixture`, so every branch below is driven
+* by the entry itself rather than by whichever exception the conversion
+* happened to throw.
+*
+* A missing or non-object `response` is deliberately NOT classified here: the
+* conversion accepts it (`{ ...undefined }` is `{}`), the server accepts it,
+* and the `validateFixtures` rules already reject it by name — "response is
+* not a recognized type (must have content, toolCalls, ...)" — which is the
+* more actionable message of the two. Saying it here as well would report one
+* defect twice. It is still named alongside `match` when `match` is fatal,
+* because then the rules never run on the entry at all and an author fixing
+* `{}` would otherwise need one round trip per missing key.
+*/
+function classifyEntry(entry) {
+	if (entry === null || typeof entry !== "object" || Array.isArray(entry)) return {
+		severity: "error",
+		convertible: false,
+		why: `entry is ${gotText(entry)}, expected an object — ${ENTRY_SHAPE}`
+	};
+	const match = entry.match;
+	if (match === null || match === void 0) return {
+		severity: "error",
+		convertible: false,
+		why: `missing or non-object ${["match", "response"].filter((key) => {
+			const value = entry[key];
+			return value === null || typeof value !== "object" || Array.isArray(value);
+		}).map((k) => `"${k}"`).join(" and ")} — ${ENTRY_SHAPE}`
+	};
+	if (typeof match !== "object" || Array.isArray(match)) return {
+		severity: "warning",
+		convertible: true,
+		why: `"match" is ${gotText(match)}, not an object — every match field reads as undefined, so this entry is an empty match: a CATCH-ALL answering every request. The server loads it the same way, so this warns rather than errors; --strict fails on it. ${ENTRY_SHAPE}`
+	};
+}
+/**
+* The backstop for an entry `classifyEntry` passed and `entryToFixture` threw
+* on anyway (a `toolCalls: [null]`, say, which `normalizeResponse` walks).
+* Which entry it was is the actionable half, so that leads; the raw thrown
+* text follows as `detail`, which `--json` carries as its own field and the
+* human report prints on an indented continuation line. It used to say
+* `see "detail"`, naming a field only the `--json` report has — in human mode
+* that pointed at nothing at all.
+*/
+function unexpectedEntryFailure(index, err) {
+	return {
+		index,
+		message: `Invalid fixture entry #${index}: could not be converted to a fixture`,
+		detail: errText(err)
+	};
+}
+/**
+* Validate one fixture file into a report. Every failure mode — unreadable,
+* unparseable, wrong shape, or a single malformed entry — is recorded in the
+* returned report rather than thrown.
+*
+* The converted fixtures are handed back alongside the report, with
+* `indices[i]` giving the entry index `fixtures[i]` was converted from, so the
+* cross-file union pass can append them and map its findings back to a file
+* and an entry index.
+*/
+function validateOneFile(file, mention) {
+	const report = {
+		file,
+		mention,
+		fixtures: 0,
+		errors: [],
+		warnings: []
+	};
+	const fixtures = [];
+	const sourceIndex = [];
+	const runErrors = [];
+	const identities = [];
+	let raw;
+	try {
+		raw = readFileSync(file, "utf-8");
+	} catch (err) {
+		setFatal(report, `Could not read file: ${errText(err)}`);
+		return {
+			report,
+			fixtures,
+			indices: sourceIndex,
+			identities,
+			runErrors
+		};
+	}
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch (err) {
+		setFatal(report, `Invalid JSON: ${errText(err)}`);
+		return {
+			report,
+			fixtures,
+			indices: sourceIndex,
+			identities,
+			runErrors
+		};
+	}
+	if (typeof parsed !== "object" || parsed === null || !Array.isArray(parsed.fixtures)) {
+		const asConfig = aimockConfigDescription(parsed);
+		setFatal(report, asConfig === void 0 ? "Missing or invalid \"fixtures\" array (expected { \"fixtures\": [...] })" : `Missing or invalid "fixtures" array (expected { "fixtures": [...] }) — this is ${asConfig}`);
+		return {
+			report,
+			fixtures,
+			indices: sourceIndex,
+			identities,
+			runErrors
+		};
+	}
+	let entryIndex = 0;
+	const entryLogger = new CollectingLogger((message) => report.warnings.push({
+		index: entryIndex,
+		message
+	}), (message) => report.errors.push({
+		index: entryIndex,
+		message
+	}));
+	const entries = parsed.fixtures;
+	for (let index = 0; index < entries.length; index++) {
+		entryIndex = index;
+		const defect = classifyEntry(entries[index]);
+		if (defect !== void 0) {
+			const label = defect.severity === "error" ? "Invalid fixture entry" : "Fixture entry";
+			const finding = {
+				index,
+				message: `${label} #${index}: ${defect.why}`
+			};
+			if (!defect.convertible) {
+				report.errors.push(finding);
+				continue;
+			}
+			report.warnings.push(finding);
+		}
+		try {
+			fixtures.push(entryToFixture(entries[index], entryLogger));
+			sourceIndex.push(index);
+		} catch (err) {
+			report.errors.push(unexpectedEntryFailure(index, err));
+		}
+	}
+	report.fixtures = fixtures.length;
+	const unresolved = /* @__PURE__ */ new Set();
+	const toEntryIndex = (fixtureIndex) => {
+		const entry = sourceIndex[fixtureIndex];
+		if (entry !== void 0) return entry;
+		if (!unresolved.has(fixtureIndex)) {
+			unresolved.add(fixtureIndex);
+			runErrors.push(`finding for fixture index ${fixtureIndex}, which maps to no entry in this file`);
+		}
+		return fixtureIndex;
+	};
+	try {
+		for (const r of validateFixtures(fixtures)) {
+			const index = toEntryIndex(r.fixtureIndex);
+			const refs = r.ref === void 0 ? [] : refIndices(r.ref).map(toEntryIndex);
+			const finding = {
+				index,
+				message: r.ref === void 0 ? r.message : renderValidationRef(r.ref, (i) => String(toEntryIndex(i)))
+			};
+			identities.push({
+				severity: r.severity,
+				index,
+				kind: r.ref === void 0 ? `message:${r.message}` : r.ref.rule,
+				refs,
+				finding
+			});
+			if (r.severity === "error") report.errors.push(finding);
+			else report.warnings.push(finding);
+		}
+	} catch (err) {
+		report.errors.push({ message: `Validation failed for this file: ${errText(err)}` });
+	}
+	return {
+		report,
+		fixtures,
+		indices: sourceIndex,
+		identities,
+		runErrors
+	};
+}
+/**
+* `#<index> ` for a finding that belongs to one entry; empty for a file-level
+* finding, which names no entry (see Finding.index). Shared by the human lines
+* and the failure summary so a reader of either can locate the same entry.
+*/
+const findingAt = (f) => f.index === void 0 ? "" : `#${f.index} `;
+/**
+* One-line reason a run failed, for the stderr side of `--json` output.
+*
+* It NAMES the failure first — the file and the finding that caused the
+* non-zero exit — and only then totals what else failed, because the line is
+* often the single line a CI log shows. Leading with a fixed list of counts
+* put two zeros ("0 unreadable/invalid file(s), 0 file(s) with errors") in
+* front of every strict-warning failure, where the reader has to get past the
+* things that did NOT happen to reach the one that did. Counts that are zero
+* are omitted for the same reason, and a file whose fatal is already the lead
+* is counted as unreadable/invalid only, not a second time under "with
+* errors" — its fatal now rides in `errors` as well (see `setFatal`).
+*/
+function summarizeFailure(reports, strict, runErrors, name) {
+	const fatalFiles = reports.filter((r) => r.fatal !== void 0);
+	const erroredFiles = reports.filter((r) => r.fatal === void 0 && r.errors.length > 0);
+	const warnedFiles = reports.filter((r) => r.warnings.length > 0);
+	let lead;
+	if (fatalFiles[0] !== void 0) lead = `${name(fatalFiles[0])}: ${fatalFiles[0].fatal}`;
+	else if (erroredFiles[0] !== void 0) lead = `${name(erroredFiles[0])}: ${findingAt(erroredFiles[0].errors[0])}${erroredFiles[0].errors[0].message}`;
+	else if (runErrors[0] !== void 0) lead = runErrors[0];
+	else if (warnedFiles[0] !== void 0) lead = `${name(warnedFiles[0])}: ${findingAt(warnedFiles[0].warnings[0])}${warnedFiles[0].warnings[0].message} (--strict)`;
+	else lead = "the run failed";
+	const counts = [];
+	if (fatalFiles.length > 0) counts.push(`${fatalFiles.length} unreadable/invalid file(s)`);
+	if (erroredFiles.length > 0) counts.push(`${erroredFiles.length} file(s) with errors`);
+	if (runErrors.length > 0) counts.push(`${runErrors.length} run-level error(s)`);
+	if (strict && warnedFiles.length > 0) counts.push(`${warnedFiles.length} file(s) with warnings (--strict)`);
+	return `Error: fixture validation failed — ${lead} [${counts.join(", ")}].`;
+}
+function runValidateCli(deps = {}) {
+	const argv = deps.argv ?? process.argv.slice(2);
+	const log = deps.log ?? console.log.bind(console);
+	const logError = deps.logError ?? console.error.bind(console);
+	const exit = deps.exit ?? process.exit.bind(process);
+	/**
+	* Is `flag` present as an OPTION in argv — i.e. before the `--` terminator,
+	* after which every argument is a path? Needed because a usage error can be
+	* a `parseArgs` throw, which leaves no parsed `values` to consult, and the
+	* output mode still has to be honoured. `--flag=value` counts: these are all
+	* boolean options, so giving one a value IS the usage error being reported,
+	* and matching the bare token alone answered "no `--json` here" for the one
+	* argv that most obviously asked for JSON — leaving stdout empty.
+	*/
+	const flagInArgv = (flag) => {
+		for (const arg of argv) {
+			if (arg === "--") return false;
+			if (arg === flag || arg.startsWith(`${flag}=`)) return true;
+		}
+		return false;
+	};
+	/**
+	* A usage error, in whichever mode the argv asked for. `--json` promises
+	* "one document on stdout" (README), and a run that fails on its own argv is
+	* still a run: emitting nothing there handed a CI job parsing stdout an
+	* empty buffer — a JSON parse error standing in for a perfectly ordinary
+	* "no paths given". The document reports the usage error the same way a
+	* run-level error is reported, so one consumer shape reads both. The
+	* human-readable reason plus the help text stay on stderr in both modes, so
+	* `--json` stdout is still the document alone.
+	*/
+	const usageError = (message) => {
+		logError(`Error: ${message}\n\n${VALIDATE_HELP}`);
+		if (flagInArgv("--json")) log(JSON.stringify({
+			strict: flagInArgv("--strict"),
+			failed: true,
+			files: [],
+			run: {
+				fixtures: 0,
+				errors: [message]
+			}
+		}, null, 2));
+		exit(1);
+	};
+	let values;
+	let paths;
+	try {
+		const parsed = parseArgs({
+			args: argv,
+			options: {
+				strict: {
+					type: "boolean",
+					default: false
+				},
+				json: {
+					type: "boolean",
+					default: false
+				},
+				help: {
+					type: "boolean",
+					short: "h",
+					default: false
+				}
+			},
+			strict: true,
+			allowPositionals: true
+		});
+		values = parsed.values;
+		paths = parsed.positionals;
+	} catch (err) {
+		usageError(err instanceof Error ? err.message : String(err));
+		return;
+	}
+	if (values.help === true) {
+		log(values.json === true ? JSON.stringify({ help: VALIDATE_HELP }, null, 2) : VALIDATE_HELP);
+		exit(0);
+		return;
+	}
+	const strict = values.strict === true;
+	const json = values.json === true;
+	if (paths.length === 0) {
+		usageError("no fixture paths given.");
+		return;
+	}
+	const targets = [];
+	for (const path of paths) {
+		if (REMOTE_SOURCE.test(path)) {
+			targets.push({
+				file: path,
+				fatal: "Remote fixture source: this lint reads local paths only (the server's --fixtures accepts a URL; validate does not) — download the file and validate the local copy"
+			});
+			continue;
+		}
+		let stats;
+		try {
+			stats = statSync(path);
+		} catch (err) {
+			if (err.code === "ENOENT") targets.push({ file: path });
+			else targets.push({
+				file: path,
+				fatal: `Could not stat: ${errText(err)}`
+			});
+			continue;
+		}
+		if (!stats.isDirectory()) {
+			if (stats.isFile()) targets.push({ file: path });
+			else targets.push({
+				file: path,
+				fatal: "Not a regular file"
+			});
+			continue;
+		}
+		const entries = collectJsonFiles(path, []);
+		if (entries.length === 0) {
+			targets.push({
+				file: path,
+				fatal: "No .json fixture files found in directory"
+			});
+			continue;
+		}
+		targets.push(...entries);
+	}
+	const mentionKey = (file) => resolve(file);
+	const mentionCount = /* @__PURE__ */ new Map();
+	for (const target of targets) mentionCount.set(mentionKey(target.file), (mentionCount.get(mentionKey(target.file)) ?? 0) + 1);
+	const mentionsSoFar = /* @__PURE__ */ new Map();
+	const nextMention = (file) => {
+		const mention = (mentionsSoFar.get(mentionKey(file)) ?? 0) + 1;
+		mentionsSoFar.set(mentionKey(file), mention);
+		return mention;
+	};
+	/**
+	* How a file is NAMED in human output and in cross-file references. A path
+	* this run loads more than once gets its mention number, because the bare
+	* path names all of those loads at once: without it a second load's findings
+	* read as a file shadowing itself. A path loaded once is printed unadorned —
+	* there is nothing to tell it apart from, and "[1]" on every line of an
+	* ordinary run is noise. The `--json` report carries `mention` regardless.
+	*/
+	const displayName = (report) => (mentionCount.get(mentionKey(report.file)) ?? 1) > 1 ? `${report.file}[${report.mention}]` : report.file;
+	const reports = [];
+	const union = [];
+	const provenance = [];
+	const reportedBySite = /* @__PURE__ */ new Map();
+	const fileIds = /* @__PURE__ */ new Map();
+	const runErrors = [];
+	const siteKey = (fileId, index, severity, kind) => [
+		fileId,
+		index,
+		severity,
+		kind
+	].join("\0");
+	for (const target of targets) {
+		if (target.skipped !== void 0) {
+			reports.push({
+				file: target.file,
+				mention: nextMention(target.file),
+				fixtures: 0,
+				errors: [],
+				warnings: [],
+				skipped: target.skipped
+			});
+			continue;
+		}
+		if (target.fatal !== void 0) {
+			reports.push(fatalReport(target.file, nextMention(target.file), target.fatal));
+			continue;
+		}
+		let report;
+		let fixtures = [];
+		let indices = [];
+		let identities = [];
+		let fileRunErrors = [];
+		const mention = nextMention(target.file);
+		try {
+			({report, fixtures, indices, identities, runErrors: fileRunErrors} = validateOneFile(target.file, mention));
+		} catch (err) {
+			report = fatalReport(target.file, mention, `Validation failed: ${errText(err)}`);
+		}
+		reports.push(report);
+		runErrors.push(...fileRunErrors.map((e) => `${displayName(report)}: ${e}`));
+		const fileId = fileIds.size;
+		fileIds.set(report, fileId);
+		for (const identity of identities) {
+			const key = siteKey(fileId, identity.index, identity.severity, identity.kind);
+			const atSite = reportedBySite.get(key) ?? [];
+			atSite.push({
+				finding: identity.finding,
+				refs: identity.refs.map((ref) => `${fileId}:${ref}`)
+			});
+			reportedBySite.set(key, atSite);
+		}
+		for (let i = 0; i < fixtures.length; i++) {
+			const index = indices[i];
+			if (index === void 0) runErrors.push(`${displayName(report)}: converted fixture ${i} has no source entry index; cross-file findings against it are reported at its array position`);
+			union.push(fixtures[i]);
+			provenance.push({
+				report,
+				index: index ?? i
+			});
+		}
+	}
+	let noFixturesLoaded = false;
+	const causeAlreadyReported = reports.some((r) => r.fatal !== void 0 || r.errors.length > 0);
+	if (union.length === 0) {
+		if (!causeAlreadyReported) {
+			runErrors.push("No fixtures loaded from any input — the server aborts startup on this under --validate-on-load/--strict");
+			noFixturesLoaded = true;
+		}
+	} else {
+		const describe = (unionIndex) => {
+			const origin = provenance[unionIndex];
+			return origin === void 0 ? String(unionIndex) : `${displayName(origin.report)} #${origin.index}`;
+		};
+		const targetOf = (unionIndex) => {
+			const origin = provenance[unionIndex];
+			if (origin === void 0) return `union:${unionIndex}`;
+			const fileId = fileIds.get(origin.report);
+			return fileId === void 0 ? `union:${unionIndex}` : `${fileId}:${origin.index}`;
+		};
+		const renderCrossFile = (ref) => {
+			if (ref.rule === "duplicate-user-message") return `duplicate userMessage '${ref.userMessage}' — shadows fixture ${describe(ref.shadows)}`;
+			const head = "empty match acts as catch-all but is not the last fixture";
+			return ref.shadowsFrom === ref.shadowsThrough ? `${head} — shadows ${describe(ref.shadowsFrom)}` : `${head} — shadows every later fixture, from ${describe(ref.shadowsFrom)} through ${describe(ref.shadowsThrough)}`;
+		};
+		try {
+			for (const r of validateFixtures(union)) {
+				const origin = provenance[r.fixtureIndex];
+				if (origin === void 0) {
+					runErrors.push(`Cross-file finding for an unknown fixture index ${r.fixtureIndex}: ${r.message}`);
+					continue;
+				}
+				const fileId = fileIds.get(origin.report);
+				if (fileId === void 0) {
+					runErrors.push(`Cross-file finding for an unrecognised file: ${r.message}`);
+					continue;
+				}
+				const kind = r.ref === void 0 ? `message:${r.message}` : r.ref.rule;
+				const refTargets = r.ref === void 0 ? [] : refIndices(r.ref).map(targetOf);
+				const message = `cross-file: ${r.ref === void 0 ? r.message : renderCrossFile(r.ref)}`;
+				const already = reportedBySite.get(siteKey(fileId, origin.index, r.severity, kind))?.shift();
+				if (already !== void 0) {
+					if (!(already.refs.length === refTargets.length && already.refs.every((target, i) => target === refTargets[i]))) already.finding.message = message;
+					continue;
+				}
+				if (r.severity === "error") origin.report.errors.push({
+					index: origin.index,
+					message
+				});
+				else origin.report.warnings.push({
+					index: origin.index,
+					message
+				});
+			}
+		} catch (err) {
+			runErrors.push(`Cross-file validation failed: ${errText(err)}`);
+		}
+	}
+	const hasFatal = reports.some((r) => r.fatal !== void 0);
+	const hasErrors = reports.some((r) => r.errors.length > 0) || runErrors.length > 0;
+	const hasWarnings = reports.some((r) => r.warnings.length > 0);
+	const failed = hasFatal || hasErrors || strict && hasWarnings;
+	const logWarning = strict ? logError : log;
+	if (json) {
+		log(JSON.stringify({
+			strict,
+			failed,
+			files: reports,
+			run: {
+				fixtures: union.length,
+				errors: runErrors
+			}
+		}, null, 2));
+		if (failed) logError(summarizeFailure(reports, strict, runErrors, displayName));
+	} else {
+		const at = findingAt;
+		const emitDetail = (f, sink) => {
+			if (f.detail !== void 0) sink(`    ${f.detail}`);
+		};
+		for (const r of reports) {
+			const name = displayName(r);
+			if (r.skipped !== void 0) {
+				log(`${name}: skipped (${r.skipped})`);
+				continue;
+			}
+			for (const e of r.errors) {
+				logError(`${name}: [error] ${at(e)}${e.message}`);
+				emitDetail(e, logError);
+			}
+			for (const w of r.warnings) {
+				logWarning(`${name}: [warning] ${at(w)}${w.message}`);
+				emitDetail(w, logWarning);
+			}
+			if (r.errors.length === 0 && r.warnings.length === 0) if (r.fixtures === 0 && failed) {
+				const why = noFixturesLoaded ? "see the run-level error" : "the run failed elsewhere";
+				log(`${name}: ${r.fixtures} fixture(s), loaded nothing — ${why}`);
+			} else log(`${name}: OK (${r.fixtures} fixture(s))`);
+			else log(`${name}: ${r.fixtures} fixture(s), ${r.errors.length} error(s), ${r.warnings.length} warning(s)`);
+		}
+		for (const e of runErrors) logError(`[error] ${e}`);
+	}
+	exit(failed ? 1 : 0);
+}
+
+//#endregion
+export { runValidateCli };
+//# sourceMappingURL=validate-cli.js.map