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

package/dist/oxlint-jev/index.d.ts

@@ -0,0 +1,6 @@
+import { Plugin } from "@oxlint/plugins";
+
+//#region src/oxlint-jev/index.d.ts
+declare const plugin: Plugin;
+//#endregion
+export { plugin as default };

package/dist/oxlint-jev/index.js

@@ -0,0 +1,581 @@
+import { i as buildJevRequests, l as noul, n as spawnJevBridge, o as defaultJevCacheDirectory } from "./bridge-B4Sx95ZO.js";
+import path from "node:path";
+import { mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+//#region src/oxlint-jev/pass.ts
+/** The environment variable that turns spending on. */
+const JEV_MODE_ENV = "PATRONAGE_JEV_MODE";
+/**
+* The mode this run is in.
+*
+* Deliberately an environment variable rather than a rule option. The Oxlint
+* config that carries the questions is a checked-in file: a `mode: "live"` in
+* it would be one merge away from every runner with HQ credentials spending on
+* every invocation, including whichever tool picks the config up next. An
+* environment variable is set per invocation by whoever is paying, and it is
+* bounded by the same credentials — `live` without `HQ_INGEST_URL` and the
+* Cloudflare Access pair buys nothing, it reports that it could not ask. A
+* value that is neither mode is refused rather than rounded to the safe one,
+* because "I set it and nothing happened" is how an operator ends up believing
+* a run asked something it did not.
+*/
+const resolveJevMode = (env) => {
+	const raw = env[JEV_MODE_ENV]?.trim();
+	if (raw === void 0 || raw === "") return "record";
+	if (raw === "live" || raw === "record") return raw;
+	throw new Error(`jev: ${JEV_MODE_ENV} must be "record" or "live"; got "${raw}"`);
+};
+/** Where recorded request bodies are written. */
+const recordDirectoryFor = (cacheDirectory) => path.join(cacheDirectory, "record");
+const describe = (error) => error instanceof Error ? error.message : String(error);
+/** The filesystem's own short constant (`ENOTDIR`, `EACCES`), never a message. */
+const errnoOf = (error) => error?.code ?? "an unknown error";
+/**
+* Whether a canonical path is the canonical root or sits under it.
+*
+* Compared on canonical paths, so neither side can be a symlink, and with a
+* separator appended so `/repo-secrets` is not read as being inside `/repo`.
+*/
+const isInside = (canonicalRoot, canonicalPath) => canonicalPath === canonicalRoot || canonicalPath.startsWith(`${canonicalRoot}${path.sep}`);
+/**
+* The reference files for each question that matched in this file, read whole.
+*
+* Their content rides the request, so it is part of the request hash and
+* therefore part of the cache key: editing a reference re-asks the question
+* rather than returning yesterday's answer about yesterday's file. A reference
+* that cannot be read makes its question's matches unavailable — the question
+* was written to be read against that file, and answering it without the file
+* would be answering a different question.
+*
+* Every reference is canonicalized before it is opened, and one outside the
+* canonical repository root is refused unread. `resolveJevQuestions` rejects an
+* absolute path and a `..` that climbs out, but that check is lexical and
+* `readFileSync` follows symlinks: a repository-relative path whose last
+* component — or any parent directory — is a symlink out of the checkout would
+* otherwise be read and, in `live` mode, sent to HQ. The refusal names the
+* configured reference and never the path it resolved to, which is the value
+* that must not travel.
+*/
+const readReferences = (root, questions) => {
+	const sharedEntries = [];
+	const failed = /* @__PURE__ */ new Map();
+	const canonicalRoot = realpathSync(root);
+	for (const question of questions) {
+		const references = question.references ?? [];
+		if (references.length === 0) continue;
+		const contentEntries = [];
+		for (const reference of references) try {
+			const canonical = realpathSync(path.join(root, reference));
+			if (!isInside(canonicalRoot, canonical)) {
+				failed.set(question.id, `reference ${reference} resolves outside the repository; it was not read`);
+				break;
+			}
+			contentEntries.push([reference, readFileSync(canonical, "utf-8")]);
+		} catch (error) {
+			failed.set(question.id, `reference ${reference} could not be read: ${error.code ?? describe(error)}`);
+			break;
+		}
+		if (!failed.has(question.id)) sharedEntries.push([question.id, Object.fromEntries(contentEntries)]);
+	}
+	return {
+		failed,
+		shared: Object.fromEntries(sharedEntries)
+	};
+};
+/**
+* The state one match contributes. A `file` match adds nothing but its target:
+* the file's whole text is already the shared state, and sending it twice
+* would buy the same tokens again.
+*/
+const stateFor = (match) => match.question.target === "file" ? { target: "file" } : {
+	snippet: match.snippet,
+	target: match.question.target
+};
+const toJevFile = (filePath, source, references, matches) => {
+	const jevMatches = matches.map((match) => ({
+		key: match.key,
+		questions: { [match.key]: noul(match.question.question) },
+		state: stateFor(match)
+	}));
+	const shared = { source };
+	if (Object.keys(references).length > 0) shared.references = references;
+	return {
+		matches: jevMatches,
+		path: filePath,
+		shared
+	};
+};
+/**
+* Writes the exact bytes the live mode would send, one file per request, named
+* by the request hash so the same request always lands in the same place.
+* Pretty-printed, because the point of recording is that a reviewer reads it.
+*/
+const writeRecords = (directory, file, unavailable) => {
+	const recorded = /* @__PURE__ */ new Map();
+	const plan = buildJevRequests({ files: [file] });
+	for (const entry of plan.unavailable) unavailable.set(entry.key, entry.reason);
+	try {
+		mkdirSync(directory, { recursive: true });
+	} catch (error) {
+		for (const match of file.matches) unavailable.set(match.key, `the Jev request could not be recorded: creating ${directory} failed with ${errnoOf(error)}`);
+		return recorded;
+	}
+	for (const request of plan.requests) {
+		const target = path.join(directory, `${request.hash}.json`);
+		try {
+			writeFileSync(target, `${JSON.stringify({
+				body: request.body,
+				estimatedTokens: request.estimatedTokens,
+				matchKeys: request.matchKeys,
+				path: request.path,
+				requestHash: request.hash
+			}, null, 2)}\n`, "utf-8");
+		} catch (error) {
+			for (const key of request.matchKeys) unavailable.set(key, `the Jev request could not be recorded: writing ${target} failed with ${errnoOf(error)}`);
+			continue;
+		}
+		for (const key of request.matchKeys) recorded.set(key, target);
+	}
+	return recorded;
+};
+/**
+* Two matches sharing a key is a bug, not a configuration error.
+*
+* The key is an answer name and a dictionary key in the request body, so a
+* collision does not produce a smaller request — it produces a request that
+* silently asks about one of the colliding matches and answers all of them
+* from it. Nothing downstream can detect that, so it is refused here, where
+* both keys are still in hand.
+*/
+const assertDistinctKeys = (matches) => {
+	const seen = /* @__PURE__ */ new Set();
+	for (const match of matches) {
+		if (seen.has(match.key)) throw new Error(`jev: two matches share the key ${match.key}. A match key must identify one node; this is a bug in the plugin, not in the configuration.`);
+		seen.add(match.key);
+	}
+};
+/** Builds the request bodies and writes them; nothing is sent. */
+const recordPass = (cacheDirectory, file, asked) => {
+	const recorded = [];
+	const unavailable = [];
+	const notRecorded = /* @__PURE__ */ new Map();
+	const written = writeRecords(recordDirectoryFor(cacheDirectory), file, notRecorded);
+	for (const match of asked) {
+		const cause = notRecorded.get(match.key);
+		if (cause === void 0) recorded.push({
+			id: match.question.id,
+			loc: match.loc,
+			requestPath: written.get(match.key) ?? "",
+			textHash: match.question.textHash
+		});
+		else unavailable.push({
+			cause,
+			id: match.question.id,
+			loc: match.loc
+		});
+	}
+	return {
+		findings: [],
+		recorded,
+		unavailable
+	};
+};
+/** Sends the request through the bridge and reads the answers back. */
+const livePass = (bridge, cacheDirectory, file, asked) => {
+	const findings = [];
+	const unavailable = [];
+	const result = bridge({
+		cacheDirectory,
+		files: [file]
+	});
+	const modelByKey = /* @__PURE__ */ new Map();
+	for (const request of result.requests) for (const key of request.matchKeys) modelByKey.set(key, request.model ?? "unknown");
+	for (const match of asked) {
+		const answer = result.answersByMatchKey[match.key]?.[match.key];
+		if (answer === void 0 || answer.type !== "noul") {
+			unavailable.push({
+				cause: result.unavailableByMatchKey[match.key] ?? "the Jev run returned no answer and no reason for this match",
+				id: match.question.id,
+				loc: match.loc
+			});
+			continue;
+		}
+		if (answer.noul >= match.question.cutoff) findings.push({
+			cutoff: match.question.cutoff,
+			id: match.question.id,
+			loc: match.loc,
+			model: modelByKey.get(match.key) ?? "unknown",
+			question: match.question.question,
+			score: answer.noul,
+			textHash: match.question.textHash
+		});
+	}
+	return {
+		findings,
+		recorded: [],
+		unavailable
+	};
+};
+/**
+* Runs one file's matches: reads the references, builds the request, and
+* either records it or sends it.
+*/
+const runJevPass = ({ bridge = spawnJevBridge, cacheDirectory = defaultJevCacheDirectory(process.cwd()), filePath, matches, mode, root, source }) => {
+	const unavailable = [];
+	if (matches.length === 0) return {
+		findings: [],
+		recorded: [],
+		unavailable
+	};
+	const { failed, shared } = readReferences(root, [...new Map(matches.map((match) => [match.question.id, match.question])).values()]);
+	const asked = matches.filter((match) => !failed.has(match.question.id));
+	for (const match of matches) {
+		const cause = failed.get(match.question.id);
+		if (cause !== void 0) unavailable.push({
+			cause,
+			id: match.question.id,
+			loc: match.loc
+		});
+	}
+	if (asked.length === 0) return {
+		findings: [],
+		recorded: [],
+		unavailable
+	};
+	assertDistinctKeys(asked);
+	const file = toJevFile(filePath, source, shared, asked);
+	const run = mode === "record" ? recordPass(cacheDirectory, file, asked) : livePass(bridge, cacheDirectory, file, asked);
+	return {
+		...run,
+		unavailable: [...unavailable, ...run.unavailable]
+	};
+};
+//#endregion
+//#region src/oxlint-jev/questions.ts
+/**
+* What a Jev question is, and the one place a caller's configuration becomes
+* one.
+*
+* A question is **configuration, not code** (epic #1234): an id, an AST
+* target, the question text, a cutoff, and optionally a `contains` pattern and
+* a list of repository-relative reference files. There is no hook, no
+* check-as-code contract, and no escape to a callback — a case that code can
+* decide is an ordinary Oxlint rule, not a Jev question.
+*
+* Oxlint validates `context.options` against `JEV_ASK_OPTIONS_SCHEMA` before a
+* rule sees them, so the checks here are only the ones a JSON schema cannot
+* express: that ids are unique, that a `contains` pattern compiles, and that a
+* reference path stays inside the repository. Each of them throws, which
+* Oxlint turns into a plugin error and a non-zero exit — a malformed question
+* set is never quietly a smaller question set.
+*/
+/** The AST shapes a question can be asked about. */
+const JEV_TARGETS = [
+	"call",
+	"file",
+	"function",
+	"jsx"
+];
+/**
+* The option schema Oxlint enforces. `additionalProperties: false` is the
+* control that refuses the options this design deliberately does not have — a
+* `mode`, an `exceptions` list, a `ci` behavior, a match cap — instead of
+* ignoring them and leaving a consumer believing they took effect.
+*/
+const JEV_ASK_OPTIONS_SCHEMA = {
+	additionalProperties: false,
+	properties: { questions: {
+		items: {
+			additionalProperties: false,
+			properties: {
+				contains: {
+					minLength: 1,
+					type: "string"
+				},
+				cutoff: {
+					maximum: 1,
+					minimum: 0,
+					type: "number"
+				},
+				id: {
+					minLength: 1,
+					type: "string"
+				},
+				question: {
+					minLength: 1,
+					type: "string"
+				},
+				references: {
+					items: {
+						minLength: 1,
+						type: "string"
+					},
+					type: "array",
+					uniqueItems: true
+				},
+				target: { enum: [...JEV_TARGETS] }
+			},
+			required: [
+				"id",
+				"target",
+				"question",
+				"cutoff"
+			],
+			type: "object"
+		},
+		minItems: 1,
+		type: "array"
+	} },
+	required: ["questions"],
+	type: "object"
+};
+const fail = (detail) => {
+	throw new Error(`jev/ask: ${detail}`);
+};
+/** The short hash of a question's text that every finding carries. */
+const questionTextHash = (question) => createHash("sha256").update(question).digest("hex").slice(0, 8);
+/**
+* A reference must name a file inside the repository. An absolute path or one
+* that climbs out of the checkout would make the request depend on the machine
+* that ran the lint, and the request is the cache key — two machines would
+* disagree about what the same configuration asked.
+*/
+const checkReference = (id, reference) => {
+	if (path.isAbsolute(reference)) fail(`question "${id}" references an absolute path (${reference}); references are repository-relative`);
+	const normalized = path.normalize(reference);
+	if (normalized === ".." || normalized.startsWith(`..${path.sep}`)) fail(`question "${id}" references a path outside the repository (${reference})`);
+};
+/**
+* Turns the rule's options into the questions this file's pass will ask.
+*
+* Called once per file, so it stays cheap: the only work is compiling
+* `contains` and hashing the question text.
+*/
+const resolveJevQuestions = (raw) => {
+	if (raw === null || typeof raw !== "object") fail("the rule takes one options object with a `questions` array; configure it as `\"jev/ask\": [\"warn\", { \"questions\": [ … ] }]`");
+	const { questions } = raw;
+	if (!Array.isArray(questions) || questions.length === 0) fail("`questions` must list at least one question");
+	const seen = /* @__PURE__ */ new Set();
+	return questions.map((question) => {
+		if (seen.has(question.id)) fail(`question id "${question.id}" is used more than once`);
+		seen.add(question.id);
+		for (const reference of question.references ?? []) checkReference(question.id, reference);
+		let pattern;
+		if (question.contains !== void 0) try {
+			pattern = new RegExp(question.contains, "u");
+		} catch {
+			fail(`question "${question.id}" has a \`contains\` that is not a valid regular expression: ${question.contains}`);
+		}
+		return {
+			...question,
+			pattern,
+			textHash: questionTextHash(question.question)
+		};
+	});
+};
+//#endregion
+//#region src/oxlint-jev/targets.ts
+const TARGET_NODE_TYPES = {
+	call: ["CallExpression"],
+	file: ["Program"],
+	function: [
+		"ArrowFunctionExpression",
+		"FunctionDeclaration",
+		"FunctionExpression"
+	],
+	jsx: ["JSXElement"]
+};
+/** Every node type any target selects, so the visitor is registered once. */
+const ALL_TARGET_NODE_TYPES = [...new Set(JEV_TARGETS.flatMap((target) => TARGET_NODE_TYPES[target]))];
+/** Node type back to the target that selected it. */
+const TARGET_BY_NODE_TYPE = new Map(JEV_TARGETS.flatMap((target) => TARGET_NODE_TYPES[target].map((type) => [type, target])));
+/**
+* The fields in which an anonymous function inherits a name from its parent.
+* `const handler = () => …` reads as "handler", and sending only `() => …`
+* would ask Jev about a snippet with the one identifying word removed.
+*/
+const NAMED_PARENTS = {
+	MethodDefinition: (parent) => parent.value,
+	Property: (parent) => parent.value,
+	PropertyDefinition: (parent) => parent.value,
+	VariableDeclarator: (parent) => parent.init
+};
+const ANONYMOUS_FUNCTIONS = new Set(["ArrowFunctionExpression", "FunctionExpression"]);
+/**
+* The node whose text is sent for this match: the node itself, unless it is an
+* anonymous function sitting in a field that names it, in which case the
+* named parent is sent instead.
+*/
+const snippetNodeFor = (node) => {
+	const visited = node;
+	const { parent } = visited;
+	if (parent === null || parent === void 0) return node;
+	const namedField = NAMED_PARENTS[parent.type];
+	if (namedField === void 0 || !ANONYMOUS_FUNCTIONS.has(visited.type)) return node;
+	return namedField(parent) === node ? parent : node;
+};
+/**
+* The first line of `text`, as a location starting at `line`/`column`. A
+* function or a whole file spans far more than a reviewer wants underlined;
+* the signature line — or the file's first line — is what identifies it.
+*/
+const headOf = (text, line, column) => {
+	const newline = text.indexOf("\n");
+	return {
+		end: {
+			column: column + (newline === -1 ? text.length : newline),
+			line
+		},
+		start: {
+			column,
+			line
+		}
+	};
+};
+/** Where the diagnostic for one match lands. */
+const reportLocationFor = (target, node, ownText) => {
+	const visited = node;
+	if (target === "file") return headOf(ownText, 1, 0);
+	if (target === "function") return headOf(ownText, visited.loc.start.line, visited.loc.start.column);
+	if (target === "jsx") return (visited.openingElement ?? visited).loc;
+	return visited.loc;
+};
+//#endregion
+//#region src/oxlint-jev/index.ts
+let currentPass = null;
+/** The file `jev/unavailable` is enabled for, set at its `Program` handler. */
+let unavailableArmedFor = null;
+const passFor = (context) => currentPass !== null && currentPass.filename === context.filename ? currentPass : null;
+const resolvePass = (pass, context) => {
+	pass.result ??= runJevPass({
+		filePath: path.relative(process.cwd(), context.filename),
+		matches: pass.matches,
+		mode: resolveJevMode(process.env),
+		root: process.cwd(),
+		source: context.sourceCode.text
+	});
+	return pass.result;
+};
+/**
+* A match's key: the question's id and the selected node's full source range.
+*
+* The range, not the report location. The key is an answer name and a
+* dictionary key in the request body, so it has to identify one node — and a
+* report location does not. Every `CallExpression` in `a().b().c()` starts at
+* the same line and column, as does every call in `f()()`, so keying on the
+* start collapsed a whole chain onto one entry: the request asked about the
+* innermost call alone and its score was reported on every call in the chain,
+* with nothing saying work had been dropped. Start and end together are unique
+* per node, because two distinct nodes cannot span exactly the same text.
+*/
+const matchKeyFor = (id, node) => {
+	const [start, end] = node.range;
+	return `${id}@${start}-${end}`;
+};
+const askMeta = {
+	docs: { description: "Ask Jev a configured question about matched code, through HQ, and report the matches whose probability clears the question's cutoff." },
+	messages: {
+		finding: "[{{id}} {{hash}}] {{model}} answered {{score}} against a {{cutoff}} cutoff: {{question}}",
+		recorded: "[{{id}} {{hash}}] record mode: this would be asked. The request is in {{request}}."
+	},
+	schema: [JEV_ASK_OPTIONS_SCHEMA],
+	type: "problem"
+};
+const unavailableMeta = {
+	docs: { description: "Report a match Jev could not answer, naming the cause. Set it to `error`: an incomplete run must exit non-zero." },
+	messages: { unavailable: "[{{id}}] Jev could not answer: {{cause}}" },
+	schema: [],
+	type: "problem"
+};
+const createAsk = (context) => {
+	const collect = (nodeType, node) => {
+		const pass = currentPass;
+		const target = TARGET_BY_NODE_TYPE.get(nodeType);
+		if (pass === null || target === void 0) return;
+		for (const question of pass.questions) {
+			if (question.target !== target) continue;
+			const ownText = target === "file" ? context.sourceCode.text : context.sourceCode.getText(node);
+			const named = snippetNodeFor(node);
+			const snippet = named === node ? ownText : context.sourceCode.getText(named);
+			if (question.pattern !== void 0 && !question.pattern.test(snippet)) continue;
+			const loc = reportLocationFor(target, node, ownText);
+			pass.matches.push({
+				key: matchKeyFor(question.id, node),
+				loc,
+				question,
+				snippet
+			});
+		}
+	};
+	const visitors = {};
+	for (const nodeType of ALL_TARGET_NODE_TYPES) visitors[nodeType] = (node) => collect(nodeType, node);
+	visitors.Program = (node) => {
+		currentPass = {
+			filename: context.filename,
+			matches: [],
+			questions: resolveJevQuestions(context.options[0]),
+			result: void 0
+		};
+		collect("Program", node);
+	};
+	visitors["Program:exit"] = () => {
+		const pass = passFor(context);
+		if (pass === null) return;
+		const result = resolvePass(pass, context);
+		for (const finding of result.findings) context.report({
+			data: {
+				cutoff: finding.cutoff.toFixed(2),
+				hash: finding.textHash,
+				id: finding.id,
+				model: finding.model,
+				question: finding.question,
+				score: finding.score.toFixed(2)
+			},
+			loc: finding.loc,
+			messageId: "finding"
+		});
+		for (const record of result.recorded) context.report({
+			data: {
+				hash: record.textHash,
+				id: record.id,
+				request: record.requestPath
+			},
+			loc: record.loc,
+			messageId: "recorded"
+		});
+		if (result.unavailable.length > 0 && unavailableArmedFor !== context.filename) throw new Error(`jev/ask: ${result.unavailable.length} match(es) could not be answered and the jev/unavailable rule is not enabled, so nothing would report them. Enable it as an error in the Jev config. First cause: ${result.unavailable[0]?.cause ?? ""}`);
+	};
+	return visitors;
+};
+const createUnavailable = (context) => ({
+	Program: () => {
+		unavailableArmedFor = context.filename;
+	},
+	"Program:exit": () => {
+		const pass = passFor(context);
+		if (pass === null) return;
+		for (const entry of resolvePass(pass, context).unavailable) context.report({
+			data: {
+				cause: entry.cause,
+				id: entry.id
+			},
+			loc: entry.loc,
+			messageId: "unavailable"
+		});
+	}
+});
+const plugin = {
+	meta: { name: "jev" },
+	rules: {
+		ask: {
+			createOnce: createAsk,
+			meta: askMeta
+		},
+		unavailable: {
+			createOnce: createUnavailable,
+			meta: unavailableMeta
+		}
+	}
+};
+//#endregion
+export { plugin as default };

package/dist/oxlint-jev/worker.d.ts

@@ -0,0 +1 @@
+export { };

package/dist/oxlint-jev/worker.js

@@ -0,0 +1,49 @@
+import { a as resolveJevGateway, r as runJevFiles, s as openJevCache, t as allUnavailable } from "./bridge-B4Sx95ZO.js";
+import { readFileSync } from "node:fs";
+//#region src/oxlint-jev/worker.ts
+/**
+* The subprocess behind the synchronous bridge. It reads one
+* `JevBridgeRequest` from stdin, runs it through the shared Jev layer, and
+* prints the `JevRunResult` to stdout as JSON.
+*
+* It prints exactly one thing, always a result, even when it fails. A throw
+* escaping here would reach the plugin as a dead subprocess with no match keys
+* attached, and every match in the file would lose its own reason; instead
+* every throw becomes the same shape as every other Jev failure — each match
+* unavailable, named with its cause.
+*/
+const describe = (error) => error instanceof Error ? error.message : String(error);
+const readRequest = () => {
+	let parsed;
+	try {
+		parsed = JSON.parse(readFileSync(0, "utf-8"));
+	} catch {
+		throw new Error("the Jev worker could not read its request. The input is not reported: it can quote repository source.");
+	}
+	if (!Array.isArray(parsed.files)) throw new TypeError("the Jev worker was given no files to ask about");
+	return parsed;
+};
+const run = async (request) => {
+	const gateway = await resolveJevGateway({ env: process.env });
+	const cache = gateway.status === "ready" ? openJevCache({
+		directory: request.cacheDirectory,
+		endpoint: gateway.endpoint
+	}) : void 0;
+	return await runJevFiles({
+		...cache === void 0 ? {} : { cache },
+		files: request.files,
+		gateway
+	});
+};
+let files = [];
+let result;
+try {
+	const request = readRequest();
+	({files} = request);
+	result = await run(request);
+} catch (error) {
+	result = allUnavailable(files, describe(error));
+}
+process.stdout.write(JSON.stringify(result));
+//#endregion
+export {};