@patronage/software-factory 1.0.0-alpha.34 → 1.0.0-alpha.36

package/dist/oxlint-jev/bridge-B4Sx95ZO.js

@@ -0,0 +1,1007 @@
+import path from "node:path";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { z } from "zod";
+import { noul } from "@typesafe-ai/sdk";
+import { spawnSync } from "node:child_process";
+import { readFile, stat } from "node:fs/promises";
+import { setTimeout as setTimeout$1 } from "node:timers/promises";
+import os from "node:os";
+//#region src/jev/schema.ts
+const noulAnswerSchema = z.object({
+	noul: z.number().min(0).max(1),
+	type: z.literal("noul")
+});
+const choiceAnswerSchema = z.object({
+	choice: z.string(),
+	confidence: z.number(),
+	probabilities: z.record(z.string(), z.number()),
+	type: z.literal("choice")
+});
+const scoreAnswerSchema = z.object({
+	confidence: z.number(),
+	probabilities: z.record(z.string(), z.number()),
+	score: z.number(),
+	type: z.literal("score")
+});
+/**
+* One answer, discriminated exactly as Jev discriminates it.
+*
+* Every member is a *stripping* object: an unknown key inside one answer is
+* dropped, not an error. Erroring would let a single surprising field sink a
+* whole response, and keeping it would put an upstream-named field into a
+* record. Dropping is the only behavior that is both safe and non-destructive.
+*/
+const jevAnswerSchema = z.discriminatedUnion("type", [
+	noulAnswerSchema,
+	choiceAnswerSchema,
+	scoreAnswerSchema
+]);
+/** Token counters, copied field by field. Never a passthrough object. */
+const usageSchema = z.object({
+	input_tokens: z.number().optional(),
+	output_tokens: z.number().optional()
+});
+/**
+* Jev's response body. Unknown keys are stripped at every level: nothing
+* upstream names may end up on a record simply because it was present.
+*/
+const jevResponseSchema = z.object({
+	answers: z.record(z.string(), jevAnswerSchema),
+	model: z.string().min(1),
+	usage: usageSchema.optional()
+});
+/** A model id is a short token. Anything longer or stranger is prose. */
+const MODEL_ID_SHAPE = /^[A-Za-z0-9][\w.-]{0,63}$/u;
+/** What a report says when HQ names its model in something other than an id. */
+const UNKNOWN_MODEL = "unknown";
+/**
+* The one way an upstream body becomes a value this package will carry.
+*
+* It returns `undefined` rather than throwing, because a thrown validation
+* error carries the rejected data in its own message — the exact thing that
+* must not travel. Every field is copied explicitly: a passthrough object, a
+* spread, or a `z.infer` handed straight to a record would all reintroduce
+* "whatever HQ sent" as "whatever we publish".
+*/
+const parseJevResponse = (payload) => {
+	const parsed = jevResponseSchema.safeParse(payload);
+	if (!parsed.success) return;
+	const { answers, model, usage } = parsed.data;
+	const counters = {};
+	if (typeof usage?.input_tokens === "number") counters.input_tokens = usage.input_tokens;
+	if (typeof usage?.output_tokens === "number") counters.output_tokens = usage.output_tokens;
+	return {
+		answers,
+		model: MODEL_ID_SHAPE.test(model) ? model : UNKNOWN_MODEL,
+		...usage === void 0 ? {} : { usage: counters }
+	};
+};
+/**
+* Projects one answer onto the question that asked for it.
+*
+* Two jobs, and the second is why this lives here rather than in a caller.
+* Type agreement keeps a well-formed answer of the wrong kind from throwing
+* later, deeper, and taking a whole report with it. And the only free text an
+* answer can carry — a `choice` label — is accepted solely when it is a label
+* this package itself wrote into the question. Probability keys are rebuilt
+* from the question's own labels or rubric levels for the same reason, so an
+* upstream-invented key cannot ride along.
+*/
+const projectAnswer = (question, answer) => {
+	if (answer.type !== question.type) return { reason: `asked ${question.type}, answered ${answer.type}` };
+	if (answer.type === "noul") return { answer: {
+		noul: answer.noul,
+		type: "noul"
+	} };
+	const keep = (keys) => Object.fromEntries(keys.map((key) => [key, answer.probabilities[key]]).filter(([, value]) => typeof value === "number"));
+	if (answer.type === "choice") {
+		const labels = Object.keys(question.criteria);
+		if (!labels.includes(answer.choice)) return { reason: "answered with a label the question did not offer" };
+		return { answer: {
+			choice: answer.choice,
+			confidence: answer.confidence,
+			probabilities: keep(labels),
+			type: "choice"
+		} };
+	}
+	const levels = question.criteria.map((_, index) => String(index));
+	return { answer: {
+		confidence: answer.confidence,
+		probabilities: keep(levels),
+		score: answer.score,
+		type: "score"
+	} };
+};
+//#endregion
+//#region src/jev/cache.ts
+/**
+* The request-hash cache: the same request bytes against the same endpoint
+* answer from disk instead of from HQ.
+*
+* The key is the endpoint plus the exact serialized request, and nothing else.
+* That is the whole design: a changed snippet, a reworded question, a
+* different reference file and a different HQ all move the bytes, so they all
+* move the key. There is no key schema to keep in step with the request
+* builder, and no way to grow one that forgets a field.
+*
+* It lives under `node_modules/.cache`, which is disposable by convention and
+* already ignored everywhere — a Jev answer is a session diagnostic (ADR
+* 0034), not a build input and not evidence.
+*
+* An entry that exists but cannot be used — unreadable, not JSON, not Jev's
+* response shape — is an error, not a miss, and so is a write that fails. Only
+* `ENOENT` means "nothing is stored". Repairing any of the others silently and
+* calling HQ anyway would be a second behavior for one failure, and a paid
+* one; the run names the entry and its cause, and the operator removes it.
+*/
+/** A cache entry that could not be used, or could not be written. */
+var JevCacheError = class extends Error {
+	path;
+	constructor(entryPath, detail) {
+		super(`the Jev cache entry ${entryPath} could not be used: ${detail}. Remove it and run again.`);
+		this.name = "JevCacheError";
+		this.path = entryPath;
+	}
+};
+/**
+* The filesystem's own error code, which is a short constant it names
+* (`EISDIR`, `EACCES`), not a message that could quote anything.
+*/
+const errnoOf = (error) => error?.code ?? "an unknown error";
+/** Where a repository's Jev answers are kept. */
+const defaultJevCacheDirectory = (cwd) => path.join(cwd, "node_modules", ".cache", "patronage-jev");
+/**
+* Opens the cache, creating its directory now so a directory that cannot be
+* written fails here — at the one place that names it — rather than midway
+* through a run as an unexplained request failure.
+*/
+const openJevCache = ({ directory = defaultJevCacheDirectory(process.cwd()), endpoint }) => {
+	mkdirSync(directory, { recursive: true });
+	const keyFor = (serialized) => createHash("sha256").update(`${endpoint}\0${serialized}`).digest("hex");
+	const entryPathFor = (serialized) => path.join(directory, `${keyFor(serialized)}.json`);
+	return {
+		keyFor,
+		read: (serialized) => {
+			const entryPath = entryPathFor(serialized);
+			let text;
+			try {
+				text = readFileSync(entryPath, "utf-8");
+			} catch (error) {
+				if (errnoOf(error) === "ENOENT") return;
+				throw new JevCacheError(entryPath, `reading it failed with ${errnoOf(error)}`);
+			}
+			let payload;
+			try {
+				payload = JSON.parse(text);
+			} catch {
+				throw new JevCacheError(entryPath, "it is not JSON");
+			}
+			const parsed = parseJevResponse(payload);
+			if (parsed === void 0) throw new JevCacheError(entryPath, "it is not Jev's response shape");
+			return parsed;
+		},
+		write: (serialized, response) => {
+			const entryPath = entryPathFor(serialized);
+			try {
+				writeFileSync(entryPath, JSON.stringify(response), "utf-8");
+			} catch (error) {
+				throw new JevCacheError(entryPath, `writing it failed with ${errnoOf(error)}`);
+			}
+		}
+	};
+};
+//#endregion
+//#region src/hq-access.ts
+const CF_ACCESS_CLIENT_ID_ENV = "CF-Access-Client-Id";
+const CF_ACCESS_CLIENT_SECRET_ENV = "CF-Access-Client-Secret";
+/**
+* True in a hosted runner, where secret-manager resolution must not be
+* tried (#312). Lives here — a dependency-free leaf both
+* `hq-ingest-preflight.ts` and `hq-credentials.ts` already import from for
+* the env var names above — so neither of those two needs to import the
+* other for it; that import, either direction, would close a cycle (#394).
+*/
+const isHostedRunner = (env) => env.CI === "true" || env.CI === "1" || env.GITHUB_ACTIONS === "true";
+/**
+* Builds a credential-bearing HQ request that cannot follow redirects. Access
+* credentials must never leave the origin selected by the caller.
+*/
+const buildCloudflareAccessRequestInit = (token, init) => ({
+	...init,
+	headers: {
+		...init.headers,
+		[CF_ACCESS_CLIENT_ID_ENV]: token.clientId,
+		[CF_ACCESS_CLIENT_SECRET_ENV]: token.clientSecret
+	},
+	redirect: "error"
+});
+//#endregion
+//#region src/hq-credentials.ts
+/**
+* Resolving the HQ Access credentials, and saying *why* when that fails.
+*
+* A deliberate command (`psf hq:flush`, and doctor's remote checks in #394) is
+* the one place allowed to ask the secret manager for the HQ Access token. It
+* used to keep a value-or-nothing answer, so a missing binary, a sandbox that
+* cannot reach the keychain, and a mistyped reference all collapsed into one
+* generic "credentials are unavailable" line. A sandboxed lane read that as
+* environmental noise while every one of its proofs stayed spooled.
+*
+* Two boundaries hold everywhere in this module:
+*
+* - **Classification comes from the failure mode, never from resolver output.**
+*   No stderr is captured and no resolver text is retained or rendered: a
+*   secret manager's diagnostics can quote the material it was asked for.
+*   Exit status, spawn error code, and signal are the whole evidence base.
+* - **Trusted-local only.** Hosted runners never invoke a secret manager
+*   (#312); references stay inert there and the failure says so.
+*/
+/** Ceiling for one secret-manager probe; expiry means unresolved, never a hang. */
+const SECRET_PROBE_TIMEOUT_MS = 1e4;
+/** The operator's resolution path: `op-fast` first, official `op` as fallback. */
+const SECRET_RESOLVER_BINARIES = ["op-fast", "op"];
+const spawnFailure = (error) => {
+	const code = error?.code;
+	if (code === "ENOENT") return "resolver-missing";
+	if (code === "EACCES" || code === "EPERM") return "resolver-blocked";
+	return "resolver-timeout";
+};
+const probe = (binary, reference, capture) => {
+	const result = spawnSync(binary, ["read", reference], {
+		encoding: "utf-8",
+		stdio: [
+			"ignore",
+			capture ? "pipe" : "ignore",
+			"ignore"
+		],
+		timeout: SECRET_PROBE_TIMEOUT_MS
+	});
+	if (result.error) return { status: spawnFailure(result.error) };
+	if (result.signal) return { status: "resolver-timeout" };
+	if (result.status !== 0) return { status: "resolver-refused" };
+	if (!capture) return {
+		status: "resolved",
+		value: ""
+	};
+	const value = result.stdout.trim();
+	return value === "" ? { status: "resolver-refused" } : {
+		status: "resolved",
+		value
+	};
+};
+/**
+* `op-fast` first, official `op` as the fallback, matching `doctor
+* --preflight`'s resolvability probe. The reported failure is the first
+* *informative* one: a machine without `op-fast` that has `op` installed and
+* denied must report the denial, not the missing binary.
+*/
+const resolveThrough = (reference, capture) => {
+	let failure = "resolver-missing";
+	for (const binary of SECRET_RESOLVER_BINARIES) {
+		const outcome = probe(binary, reference, capture);
+		if (outcome.status === "resolved") return outcome;
+		if (failure === "resolver-missing") failure = outcome.status;
+	}
+	return { status: failure };
+};
+const defaultSecretReferenceResolver = (reference) => resolveThrough(reference, true);
+/**
+* Environment first (the #312 emit-time path), then the operator's configured
+* references. The first reference that fails ends the resolution: a second
+* probe would add nothing but another chance to hang.
+*/
+const resolveHqCredentials = ({ env, references, resolve = defaultSecretReferenceResolver }) => {
+	const clientId = env[CF_ACCESS_CLIENT_ID_ENV];
+	const clientSecret = env[CF_ACCESS_CLIENT_SECRET_ENV];
+	if (clientId && clientSecret) return {
+		credentials: {
+			clientId,
+			clientSecret
+		},
+		source: "environment",
+		status: "resolved"
+	};
+	if (!references) return {
+		failure: "no-reference",
+		status: "unresolved"
+	};
+	if (isHostedRunner(env)) return {
+		failure: "hosted-runner",
+		status: "unresolved"
+	};
+	const resolvedId = resolve(references.clientIdRef);
+	if (resolvedId.status !== "resolved") return {
+		failure: resolvedId.status,
+		reference: references.clientIdRef,
+		status: "unresolved"
+	};
+	const resolvedSecret = resolve(references.clientSecretRef);
+	if (resolvedSecret.status !== "resolved") return {
+		failure: resolvedSecret.status,
+		reference: references.clientSecretRef,
+		status: "unresolved"
+	};
+	return {
+		credentials: {
+			clientId: resolvedId.value,
+			clientSecret: resolvedSecret.value
+		},
+		source: "references",
+		status: "resolved"
+	};
+};
+//#endregion
+//#region src/user-config.ts
+const FACTORY_USER_CONFIG_SCHEMA_VERSION = 2;
+const githubAppConfigSchema = z.object({
+	appId: z.union([z.string().min(1), z.number().int().positive()]),
+	installationId: z.number().int().positive().optional(),
+	privateKeyPath: z.string().min(1)
+});
+const hqAllowedOriginSchema = z.string().url().refine((value) => {
+	try {
+		const url = new URL(value);
+		return url.protocol === "https:" && url.username === "" && url.password === "" && value === url.origin;
+	} catch {
+		return false;
+	}
+}, "Must be an HTTPS origin without credentials, path, query, or fragment");
+const hqIngestCredentialReferencesSchema = z.object({
+	clientIdRef: z.string().min(1),
+	clientSecretRef: z.string().min(1)
+});
+const factoryUserConfigSchema = z.object({
+	githubApp: githubAppConfigSchema.optional(),
+	hqAllowedOrigins: z.array(hqAllowedOriginSchema).describe("Operator-controlled exact HTTPS origins authorized to receive HQ credential-bearing requests; an absent or empty list authorizes none.").optional(),
+	hqIngestCredentials: hqIngestCredentialReferencesSchema.describe("Operator-controlled secret-manager references for the HQ ingest Cloudflare Access service token. References only — the factory never reads, prints, exports, or caches the values.").optional(),
+	schemaVersion: z.literal(FACTORY_USER_CONFIG_SCHEMA_VERSION)
+});
+function defaultUserConfigPath(env = process.env) {
+	const configHome = env.XDG_CONFIG_HOME !== void 0 && env.XDG_CONFIG_HOME !== "" ? env.XDG_CONFIG_HOME : path.join(env.HOME !== void 0 && env.HOME !== "" ? env.HOME : os.homedir(), ".config");
+	return path.join(configHome, "patronage-factory", "config.json");
+}
+//#endregion
+//#region src/hq-origin-policy.ts
+/**
+* Where the HQ Access service token may be sent, decided once.
+*
+* A request that carries the token goes only to an HTTPS origin with no
+* embedded credentials that the operator listed, exactly, in
+* `hqAllowedOrigins` in the operator user config. Committed repository data
+* and the environment can name an origin; only the operator can authorize one
+* (ADR 0015). HQ ingest and the Jev client both call this module, so the two
+* cannot drift apart: one protocol rule, one reader, one parser.
+*
+* The reader is bounded. A config path that is a FIFO, a huge file, or a disk
+* that hangs answers "no origin is authorized" within the caller's deadline
+* instead of holding a gate or a lint run open.
+*/
+/** Largest operator config or profile file the HQ readers will open. */
+const MAX_HQ_CONFIG_BYTES = 1024 * 1024;
+const remainingMs = (deadline) => Math.max(0, deadline - performance.now());
+const settleWithin = async (operation, budgetMs) => {
+	const settleOperation = async () => {
+		try {
+			return {
+				status: "fulfilled",
+				value: await operation
+			};
+		} catch (error) {
+			return {
+				error,
+				status: "rejected"
+			};
+		}
+	};
+	const timeoutAbort = new AbortController();
+	const settleTimeout = async () => {
+		try {
+			await setTimeout$1(Math.max(0, budgetMs), void 0, { signal: timeoutAbort.signal });
+		} catch {}
+		return { status: "timed-out" };
+	};
+	const result = await Promise.race([settleOperation(), settleTimeout()]);
+	timeoutAbort.abort();
+	return result;
+};
+const readBoundedTextFile = async (filePath, deadline, maxBytes = MAX_HQ_CONFIG_BYTES) => {
+	const metadata = await settleWithin(stat(filePath), remainingMs(deadline));
+	if (metadata.status !== "fulfilled" || !metadata.value.isFile() || metadata.value.size > maxBytes) return;
+	const budget = remainingMs(deadline);
+	if (budget <= 0) return;
+	const abort = new AbortController();
+	const abortTimer = setTimeout(() => abort.abort(), budget);
+	const contents = await settleWithin(readFile(filePath, {
+		encoding: "utf-8",
+		signal: abort.signal
+	}), budget);
+	clearTimeout(abortTimer);
+	if (contents.status !== "fulfilled" || Buffer.byteLength(contents.value, "utf-8") > maxBytes) return;
+	return contents.value;
+};
+/**
+* The protocol rule: an `https:` URL with no username and no password. There
+* is no `http:` exception, loopback included. The caller composes its own path
+* onto the returned URL's `origin`.
+*/
+const validatedHqOrigin = (value) => {
+	try {
+		const endpoint = new URL(value);
+		if (endpoint.protocol !== "https:" || endpoint.username !== "" || endpoint.password !== "") return;
+		return endpoint;
+	} catch {
+		return;
+	}
+};
+/**
+* The operator's `hqAllowedOrigins`, from the text of the operator user
+* config. A file that is not JSON or not a valid user config authorizes
+* nothing: the list is empty, never partly read.
+*/
+const hqAllowedOriginsFromConfigText = (text) => {
+	try {
+		const parsed = factoryUserConfigSchema.safeParse(JSON.parse(text));
+		return parsed.success ? parsed.data.hqAllowedOrigins ?? [] : [];
+	} catch {
+		return [];
+	}
+};
+/**
+* The operator's `hqAllowedOrigins`, read from the operator user config within
+* `deadline` (a `performance.now()` time). A missing, unreadable, oversized or
+* invalid file, or one that does not answer in time, authorizes nothing.
+*/
+const loadHqAllowedOrigins = async (env, deadline) => {
+	let configPath;
+	try {
+		configPath = defaultUserConfigPath(env);
+	} catch {
+		return [];
+	}
+	const contents = await readBoundedTextFile(configPath, deadline);
+	return contents === void 0 ? [] : hqAllowedOriginsFromConfigText(contents);
+};
+/**
+* The matching rule: the URL's origin must equal one listed origin exactly.
+* No prefix, wildcard, or host-only match.
+*/
+const isHqOriginAuthorized = (allowedOrigins, endpoint) => allowedOrigins.includes(endpoint.origin);
+//#endregion
+//#region src/jev/client.ts
+/**
+* The one Jev gateway: HQ (ADR 0033).
+*
+* There is no fallback provider and no direct mode "for local dev". This
+* module knows Jev's request schema and how to reach HQ; it does not know
+* Cloudflare, TypeSafe, accounts, or model versions. HQ names the model and
+* returns the one that actually ran.
+*
+* `HQ_INGEST_URL` names the origin (#259). The origin is authorized before
+* anything else happens, by the same code HQ ingest uses
+* (`hq-origin-policy.ts`, ADR 0015): it must be an `https:` origin with no
+* embedded credentials, listed exactly in the operator's `hqAllowedOrigins`.
+* Only then are credentials read: `resolveHqCredentials` reads the hyphenated
+* `CF-Access-Client-Id` / `CF-Access-Client-Secret` pair, and
+* `buildCloudflareAccessRequestInit` attaches them to a request that refuses
+* redirects so the credentials cannot leave the authorized origin.
+*
+* Credentials are read from the environment only. A diagnostic must not reach
+* into the operator's secret manager: `hq:flush` is the deliberate command
+* allowed to do that, and a session that has already loaded the pair for a
+* factory command has it here too. So `resolveHqCredentials` is called with no
+* references, and the remedy this module prints is the one that actually
+* applies — load the variables — never "record references in the user config",
+* which would do nothing for this command.
+*/
+/** The environment variable that carries HQ's origin, same as ingest. */
+const HQ_ORIGIN_ENV = "HQ_INGEST_URL";
+/** HQ's Jev boundary, composed onto the origin. */
+const JEV_ROUTE_PATH = "/api/jev";
+/** Per-attempt ceiling. A 32k-token packet is a slow request, not a hung one. */
+const JEV_REQUEST_TIMEOUT_MS = 6e4;
+/**
+* Ceiling for reading the operator user config. A config path that hangs
+* authorizes nothing rather than holding the run open.
+*/
+const ORIGIN_POLICY_READ_MS = 5e3;
+/**
+* An upstream refusal, carried with the code HQ passed through rather than
+* flattened into prose. `max_tokens_exceeded` is the one a caller acts on: it
+* means the packet was too large despite the local budget.
+*/
+var JevRequestError = class extends Error {
+	code;
+	httpStatus;
+	constructor(httpStatus, code, message) {
+		super(message);
+		this.name = "JevRequestError";
+		this.code = code;
+		this.httpStatus = httpStatus;
+	}
+};
+/**
+* A code is a short machine token. Anything else in that field is prose the
+* upstream chose, and prose is exactly what must not travel into a report.
+*/
+const CODE_SHAPE = /^[a-z0-9_.-]{1,64}$/iu;
+/** Reads the upstream error code out of whatever shape the body arrived in. */
+const rawErrorCode = (body) => {
+	if (body === null || typeof body !== "object") return;
+	const record = body;
+	if (typeof record.code === "string") return record.code;
+	if (typeof record.error === "string") return record.error;
+	if (record.error !== null && typeof record.error === "object") {
+		const nested = record.error.code;
+		return typeof nested === "string" ? nested : void 0;
+	}
+};
+/**
+* The only thing kept from a refusal body.
+*
+* An upstream 400 routinely quotes the state it rejected, and this state is
+* repository source. That message used to be copied into the request record and
+* into every affected case's reasons, so an ordinary run without
+* `--include-evidence` could print source back out. Status and a code-shaped
+* token are enough to act on — `max_tokens_exceeded` is the one a caller does
+* anything about — and a field that is not code-shaped is dropped rather than
+* trimmed, because a truncated leak is still a leak.
+*/
+const errorCode = (body) => {
+	const raw = rawErrorCode(body);
+	return raw !== void 0 && CODE_SHAPE.test(raw) ? raw : void 0;
+};
+/**
+* How to name a rejected origin without repeating it.
+*
+* Every `unavailable` reason reaches `statusReason`, each case's `reasons`, and
+* both the JSON and Markdown renderings — none of which is redacted anywhere.
+* An `HQ_INGEST_URL` carrying userinfo is exactly the value that must not be
+* echoed, and it is exactly the value being rejected, so the diagnostic is
+* limited to scheme and host. A value that does not parse is not quoted at all:
+* there is no structure to trim it down to.
+*/
+const describeOrigin = (origin) => {
+	const parsed = URL.parse(origin);
+	return parsed === null ? "(not a URL; the value is withheld because it could not be parsed to strip credentials)" : `${parsed.protocol}//${parsed.host}`;
+};
+/**
+* HQ's Jev endpoint for a configured origin, or `undefined` when the value
+* breaks HQ ingest's protocol rule (`validatedHqOrigin`: `https:` only, no
+* embedded credentials, no `http:` exception).
+*
+* The path is composed onto the URL's *origin*, which is what both existing HQ
+* readers do and what makes the documented misconfiguration harmless: the
+* operator who sets `HQ_INGEST_URL` to the profile's `/api/ingest` endpoint
+* instead of the origin (#259) still reaches `/api/jev`, not
+* `/api/ingest/api/jev`.
+*/
+const jevEndpointFor = (origin) => {
+	const parsed = validatedHqOrigin(origin);
+	return parsed === void 0 ? void 0 : new URL(JEV_ROUTE_PATH, parsed.origin).href;
+};
+/**
+* Whether an upstream token is this request's own credential handed back.
+*
+* Narrow on purpose. A model id and an error code are opaque tokens HQ names,
+* so they cannot be pattern-matched for secrets in general, and general secret
+* scanning is not wanted here: HQ already holds both the credential and the
+* source, so a hostile HQ is outside the threat model. What *is* cheap and
+* exact is the comparison this function makes — the credential values are in
+* scope at the one place a response is read, so a field that echoes one back
+* can be recognized by equality rather than by guesswork.
+*/
+const reflectsCredential = (value, token) => value.includes(token.clientId) || value.includes(token.clientSecret);
+/**
+* The whole exchange, and the only place an upstream body is touched.
+*
+* Fetching, reading the body, parsing it, and validating it all happen inside
+* one boundary with one outer catch, because the leak this shape prevents kept
+* coming back by a different route each time: first the refusal body, then the
+* transport message, then the body stream, then a schema issue. Each of those
+* is a distinct throw site, and patching them one at a time is a losing game.
+*
+* The rule is therefore structural, not per-site: **everything that leaves here
+* is a `JevRequestError` whose message is a fixed string, plus an HTTP status,
+* plus a code-shaped token.** Nothing derived from an upstream value —
+* `error.message`, `error.cause`, response text, or a validation issue — is
+* ever read into a message. A throw this function does not recognize becomes
+* one fixed sentence rather than being inspected.
+*/
+const exchange = async (input) => {
+	const init = buildCloudflareAccessRequestInit(input.token, {
+		body: input.serializedBody,
+		headers: { "content-type": "application/json" },
+		method: "POST",
+		signal: AbortSignal.timeout(JEV_REQUEST_TIMEOUT_MS)
+	});
+	try {
+		let response;
+		try {
+			response = await input.fetchImpl(input.endpoint, init);
+		} catch (error) {
+			const timedOut = error instanceof Error && error.name === "TimeoutError";
+			throw new JevRequestError(0, timedOut ? "timeout" : "unreachable", timedOut ? `HQ Jev at ${input.endpoint} did not answer within ${JEV_REQUEST_TIMEOUT_MS}ms.` : `HQ Jev at ${input.endpoint} could not be reached. Redirects are refused to protect Cloudflare Access credentials.`);
+		}
+		const text = await response.text();
+		let payload;
+		try {
+			payload = JSON.parse(text);
+		} catch {
+			payload = void 0;
+		}
+		if (!response.ok) {
+			const reported = errorCode(payload);
+			const code = reported !== void 0 && reflectsCredential(reported, input.token) ? void 0 : reported;
+			throw new JevRequestError(response.status, code, `HQ Jev refused the request with HTTP ${response.status}${code === void 0 ? "" : ` (${code})`}. The response body is not reported: an upstream validation error can quote the state it rejected, which is repository source.`);
+		}
+		const parsed = parseJevResponse(payload);
+		const body = parsed !== void 0 && reflectsCredential(parsed.model, input.token) ? {
+			...parsed,
+			model: UNKNOWN_MODEL
+		} : parsed;
+		if (body === void 0) throw new JevRequestError(response.status, "malformed_response", "HQ Jev returned a body that is not Jev's response shape. The body is not reported.");
+		return body;
+	} catch (error) {
+		if (error instanceof JevRequestError) throw error;
+		throw new JevRequestError(0, "exchange_failed", "The HQ Jev exchange failed before a response could be read. No upstream text is reported: it can quote the request.");
+	}
+};
+/**
+* The whole remedy, in one sentence. The variable names are literally
+* hyphenated, so a plain `export` does not set them.
+*/
+const MISSING_CREDENTIALS_REASON = `no HQ credentials: ${CF_ACCESS_CLIENT_ID_ENV} and ${CF_ACCESS_CLIENT_SECRET_ENV} are not both in the environment. The names are literally hyphenated, so a plain \`export\` does not set them — prefix the command: \`env '${CF_ACCESS_CLIENT_ID_ENV}=…' '${CF_ACCESS_CLIENT_SECRET_ENV}=…' <the command> …\`.`;
+/** Where the operator config was looked for, for a message that names it. */
+const operatorConfigLocation = (env) => {
+	try {
+		return ` (${defaultUserConfigPath(env)})`;
+	} catch {
+		return "";
+	}
+};
+/**
+* Why an origin is not authorized. An empty list and an unlisted origin are
+* different remedies, so they are different sentences. A config that is
+* missing, unreadable or invalid reads as an empty list, exactly as it does
+* for HQ ingest.
+*/
+const unauthorizedOriginReason = (allowedOrigins, origin, env) => allowedOrigins.length === 0 ? `no HQ origin is authorized: the operator user config${operatorConfigLocation(env)} has no hqAllowedOrigins, or it is missing or cannot be read. List ${origin} there, as HQ ingest requires, before Jev sends credentials or source to it.` : `HQ origin ${origin} is not authorized by hqAllowedOrigins in the operator user config${operatorConfigLocation(env)}. List the exact origin there, as HQ ingest requires, before Jev sends credentials or source to it.`;
+/**
+* Resolves the gateway, or says why there isn't one. Every `unavailable`
+* reason is an operator-facing sentence naming a remedy that applies to this
+* command, and none of them can carry a credential: nothing here reads a
+* resolved value into a message.
+*
+* The order is the policy. The origin is checked against HQ ingest's protocol
+* rule and the operator's `hqAllowedOrigins` first, and only an authorized
+* origin gets as far as reading credentials. An unauthorized origin never sees
+* a request.
+*/
+const resolveJevGateway = async ({ env, fetchImpl = fetch }) => {
+	const origin = env[HQ_ORIGIN_ENV]?.trim();
+	if (!origin) return {
+		reason: `no HQ origin: ${HQ_ORIGIN_ENV} is unset. It wants the origin, for example https://hq.patronage.com.`,
+		status: "unavailable"
+	};
+	const endpoint = jevEndpointFor(origin);
+	if (endpoint === void 0) return {
+		reason: `${HQ_ORIGIN_ENV} must be an https origin without embedded credentials, as HQ ingest requires: ${describeOrigin(origin)}`,
+		status: "unavailable"
+	};
+	const endpointUrl = new URL(endpoint);
+	const allowedOrigins = await loadHqAllowedOrigins(env, performance.now() + ORIGIN_POLICY_READ_MS);
+	if (!isHqOriginAuthorized(allowedOrigins, endpointUrl)) return {
+		reason: unauthorizedOriginReason(allowedOrigins, endpointUrl.origin, env),
+		status: "unavailable"
+	};
+	const resolution = resolveHqCredentials({ env });
+	if (resolution.status !== "resolved") return {
+		reason: MISSING_CREDENTIALS_REASON,
+		status: "unavailable"
+	};
+	return {
+		endpoint,
+		evaluate: (serializedBody) => exchange({
+			endpoint,
+			fetchImpl,
+			serializedBody,
+			token: resolution.credentials
+		}),
+		status: "ready"
+	};
+};
+//#endregion
+//#region src/jev/request.ts
+/**
+* The per-request ceiling, in tokens. Jev's context is the constraint this
+* bounds; 32k is the size the epic designed to, and the headroom below covers
+* the estimator's error rather than pretending it has none.
+*/
+const JEV_REQUEST_TOKEN_BUDGET = 32e3;
+/** Fraction of the budget a request may fill. The rest absorbs estimator error. */
+const BUDGET_HEADROOM = .9;
+/** JSON punctuation the per-part sizes do not account for. */
+const ENVELOPE_OVERHEAD_BYTES = 128;
+const BYTES_PER_TOKEN = 4;
+/**
+* Tokens from bytes, at the conventional four-bytes-per-token ratio.
+*
+* A real tokenizer would be a heavy dependency and a second thing to keep in
+* step with whatever model HQ routes to — and the factory holds no model
+* vocabulary by design (ADR 0033). An over-estimate costs an extra split; the
+* headroom above covers an under-estimate. It is a budget, not a measurement.
+*/
+const tokensFor = (bytes) => Math.ceil(bytes / BYTES_PER_TOKEN);
+/**
+* JSON with object keys in sorted order, so the same logical request always
+* serializes to the same bytes — and therefore the same hash, and therefore
+* the same cache entry. Two runs that assembled their state in a different
+* order must not look like two different requests.
+*/
+const stableStringify = (value) => JSON.stringify(value, (_key, nested) => {
+	if (nested === null || typeof nested !== "object" || Array.isArray(nested)) return nested;
+	const source = nested;
+	return Object.fromEntries(Object.keys(source).toSorted().map((key) => [key, source[key]]));
+});
+const byteSize = (value) => Buffer.byteLength(stableStringify(value), "utf-8");
+/** What one match adds to a request: its state entry plus its questions. */
+const matchCost = (match) => byteSize({ [match.key]: match.state }) + byteSize(match.questions);
+/** What a request costs before any match is in it. */
+const baseCost = (file) => ENVELOPE_OVERHEAD_BYTES + byteSize({ path: file.path }) + byteSize({ file: file.shared });
+const buildBody = (file, matches) => {
+	const matchStates = Object.fromEntries(matches.map((match) => [match.key, match.state]));
+	return {
+		questions: Object.fromEntries(matches.flatMap((match) => Object.entries(match.questions))),
+		state: {
+			file: file.shared,
+			matches: matchStates,
+			path: file.path
+		}
+	};
+};
+const toRequest = (file, matches) => {
+	const body = buildBody(file, matches);
+	const serialized = stableStringify(body);
+	return {
+		body,
+		estimatedTokens: tokensFor(Buffer.byteLength(serialized, "utf-8")),
+		hash: createHash("sha256").update(serialized).digest("hex"),
+		matchKeys: matches.map((match) => match.key),
+		path: file.path,
+		serialized
+	};
+};
+/**
+* Turns files into the requests that will be sent, plus the matches that
+* cannot be sent and why. Pure: it performs no I/O and decides nothing about
+* transport.
+*/
+const buildJevRequests = ({ budgetTokens = JEV_REQUEST_TOKEN_BUDGET, files }) => {
+	const ceiling = Math.floor(budgetTokens * BUDGET_HEADROOM);
+	const ceilingBytes = ceiling * BYTES_PER_TOKEN;
+	const requests = [];
+	const unavailable = [];
+	for (const file of files) {
+		const base = baseCost(file);
+		let open = [];
+		let openBytes = base;
+		const flush = () => {
+			if (open.length > 0) {
+				requests.push(toRequest(file, open));
+				open = [];
+				openBytes = base;
+			}
+		};
+		for (const match of file.matches) {
+			const cost = matchCost(match);
+			if (openBytes + cost <= ceilingBytes) {
+				open.push(match);
+				openBytes += cost;
+				continue;
+			}
+			flush();
+			if (openBytes + cost <= ceilingBytes) {
+				open.push(match);
+				openBytes += cost;
+				continue;
+			}
+			unavailable.push({
+				key: match.key,
+				reason: `this match does not fit one Jev request: ${file.path} plus this match is estimated at ${tokensFor(base + cost)} tokens against a ${ceiling}-token ceiling`
+			});
+		}
+		flush();
+	}
+	return {
+		requests,
+		unavailable
+	};
+};
+//#endregion
+//#region src/jev/run.ts
+const describe = (error) => error instanceof Error ? error.message : String(error);
+/**
+* Matches one match's answers to the questions it asked.
+*
+* `projectAnswer` does the work: it rebuilds each answer from the question
+* that asked for it, so an answer of the wrong kind, a `choice` label nobody
+* offered, and an upstream-invented probability key are each refused or
+* dropped rather than carried. A refusal costs one match — it becomes
+* unavailable with a reason — instead of throwing later, deeper, and taking a
+* whole report's correctly answered siblings with it.
+*/
+const routeAnswers = (questions, answers) => {
+	const routed = /* @__PURE__ */ new Map();
+	const missing = [];
+	const mismatched = [];
+	for (const [name, question] of Object.entries(questions)) {
+		const answer = answers[name];
+		if (answer === void 0) {
+			missing.push(name);
+			continue;
+		}
+		const projected = projectAnswer(question, answer);
+		if (projected.reason === void 0) routed.set(name, projected.answer);
+		else mismatched.push(`${name} (${projected.reason})`);
+	}
+	if (missing.length > 0) return { reason: `Jev answered the request but omitted ${missing.join(", ")}` };
+	if (mismatched.length > 0) return { reason: `answer type mismatch: ${mismatched.join(", ")}` };
+	return { answers: Object.fromEntries(routed) };
+};
+const completionOf = (answered, unanswered) => {
+	if (unanswered === 0) return "complete";
+	return answered === 0 ? "unavailable" : "partial";
+};
+/** Counters copied one by one, never the parsed object: this record is printed. */
+const copyUsage = (usage) => {
+	const copied = {};
+	if (typeof usage.input_tokens === "number") copied.input_tokens = usage.input_tokens;
+	if (typeof usage.output_tokens === "number") copied.output_tokens = usage.output_tokens;
+	return copied;
+};
+/**
+* One request's answer, from the cache when the exact bytes are already
+* answered and from HQ otherwise. A live answer is stored on the way back, so
+* the next identical request costs nothing.
+*/
+const answerFor = async (gateway, cache, serialized) => {
+	const stored = cache?.read(serialized);
+	if (stored !== void 0) return {
+		cached: true,
+		response: stored
+	};
+	const response = await gateway.evaluate(serialized);
+	cache?.write(serialized, response);
+	return {
+		cached: false,
+		response
+	};
+};
+/** Writes what HQ reported about the call itself onto the request's record. */
+const recordResponse = (record, response, models) => {
+	record.model = response.model;
+	if (response.usage !== void 0) record.usage = copyUsage(response.usage);
+	if (!models.includes(response.model)) models.push(response.model);
+};
+/**
+* Builds the requests, sends the ones the cache does not already answer, and
+* routes answers back to the matches that asked for them.
+*
+* Requests go one at a time. Bounded load is the point: a repository-wide run
+* would otherwise open dozens of concurrent 32k-token requests against one HQ
+* route for a diagnostic nothing is waiting on.
+*/
+const runJevFiles = async ({ budgetTokens, cache, files, gateway }) => {
+	const plan = buildJevRequests({
+		...budgetTokens === void 0 ? {} : { budgetTokens },
+		files
+	});
+	const questionsByMatch = /* @__PURE__ */ new Map();
+	for (const file of files) for (const match of file.matches) questionsByMatch.set(match.key, match.questions);
+	const answers = /* @__PURE__ */ new Map();
+	const unavailable = /* @__PURE__ */ new Map();
+	const requests = [];
+	const models = [];
+	for (const { key, reason } of plan.unavailable) unavailable.set(key, reason);
+	if (gateway.status !== "ready") {
+		for (const request of plan.requests) for (const key of request.matchKeys) unavailable.set(key, gateway.reason);
+		return {
+			answersByMatchKey: {},
+			completion: completionOf(0, unavailable.size),
+			elapsedMs: 0,
+			models,
+			requests,
+			unavailableByMatchKey: Object.fromEntries(unavailable)
+		};
+	}
+	const runStarted = Date.now();
+	for (const request of plan.requests) {
+		const record = {
+			cached: false,
+			elapsedMs: 0,
+			estimatedTokens: request.estimatedTokens,
+			matchKeys: request.matchKeys,
+			path: request.path,
+			requestHash: request.hash
+		};
+		const started = Date.now();
+		try {
+			const { cached, response } = await answerFor(gateway, cache, request.serialized);
+			record.cached = cached;
+			recordResponse(record, response, models);
+			for (const matchKey of request.matchKeys) {
+				const routed = routeAnswers(questionsByMatch.get(matchKey) ?? {}, response.answers);
+				if (routed.reason === void 0) answers.set(matchKey, routed.answers);
+				else unavailable.set(matchKey, routed.reason);
+			}
+		} catch (error) {
+			record.error = describe(error);
+			if (error instanceof JevRequestError && error.code !== void 0) record.errorCode = error.code;
+			for (const matchKey of request.matchKeys) unavailable.set(matchKey, record.error);
+		}
+		record.elapsedMs = Date.now() - started;
+		requests.push(record);
+	}
+	return {
+		answersByMatchKey: Object.fromEntries(answers),
+		completion: completionOf(answers.size, unavailable.size),
+		elapsedMs: Date.now() - runStarted,
+		models,
+		requests,
+		unavailableByMatchKey: Object.fromEntries(unavailable)
+	};
+};
+//#endregion
+//#region src/oxlint-jev/bridge.ts
+/**
+* A result in which nothing was answered, for the failures that happen outside
+* the subprocess's own reporting — it could not start, it died, or what it
+* printed was not a result.
+*/
+const allUnavailable = (files, reason) => ({
+	answersByMatchKey: {},
+	completion: "unavailable",
+	elapsedMs: 0,
+	models: [],
+	requests: [],
+	unavailableByMatchKey: Object.fromEntries(files.flatMap((file) => file.matches.map((match) => [match.key, reason])))
+});
+/**
+* `worker.ts` in a source checkout, `worker.js` in the published package. The
+* extension is read from this module's own path, so the source layout and the
+* built one stay in step without a build-time constant. The build keeps the
+* two files side by side in `dist/oxlint-jev/` for the same reason.
+*/
+const workerPath = () => path.join(import.meta.dirname, `worker${path.extname(import.meta.filename)}`);
+/** Room for a whole file's requests and answers. The 1 MiB default is not. */
+const MAX_OUTPUT_BYTES = 64 * 1024 * 1024;
+/**
+* Runs one file's requests in a subprocess and returns what happened.
+*
+* Nothing the subprocess wrote is read into a reason. Its stderr can carry a
+* stack that quotes the request, and the request is repository source
+* (`src/jev/client.ts` holds the same rule for upstream bodies), so a failure
+* this function cannot parse becomes one fixed sentence plus the exit status.
+*/
+const spawnJevBridge = ({ cacheDirectory, files }) => {
+	const child = spawnSync(process.execPath, [workerPath()], {
+		encoding: "utf-8",
+		input: JSON.stringify({
+			cacheDirectory,
+			files
+		}),
+		maxBuffer: MAX_OUTPUT_BYTES
+	});
+	if (child.error !== void 0 || child.status !== 0) {
+		const code = child.error?.code;
+		return allUnavailable(files, `the Jev worker exited with status ${String(child.status)}, signal ${String(child.signal)}${code === void 0 ? "" : `, spawn error ${code}`}. Its output is not reported: it can quote the request, which is repository source.`);
+	}
+	try {
+		return JSON.parse(child.stdout);
+	} catch {
+		return allUnavailable(files, "the Jev worker did not print a result. Its output is not reported: it can quote the request, which is repository source.");
+	}
+};
+//#endregion
+export { resolveJevGateway as a, UNKNOWN_MODEL as c, buildJevRequests as i, noul as l, spawnJevBridge as n, defaultJevCacheDirectory as o, runJevFiles as r, openJevCache as s, allUnavailable as t };