@payconductor/houndsman 0.1.0 → 0.1.3

package/src/core/fix-batch.ts

@@ -0,0 +1,236 @@
+/**
+ * Montagem do **lote de correção** dos findings (biblioteca).
+ *
+ * O `findings batch` precisa entregar, com o mínimo de decisão da LLM, a "melhor
+ * unidade de trabalho" para corrigir achados: um grupo coeso (arquivo, regra ou
+ * watchdog) já paginado, mais a lista dos outros grupos disponíveis.
+ *
+ * A escolha do agrupamento é **determinística** — não vem do consumidor. Para a
+ * fila atual (findings `decision: execute` ainda não concluídos):
+ *
+ *   1. Candidatas, em ordem de prioridade: `file` → `rule` → `watchdog`.
+ *   2. "Elegível" = média de itens por grupo ≥ 2 (há coesão real).
+ *   3. Vence a elegível com **menos grupos** (escopo mais coeso); empate mantém
+ *      a prioridade. Sem elegíveis (tudo singleton), cai em `file`.
+ *
+ * Assim o lote se adapta à run: poucos arquivos → corrige arquivo a arquivo;
+ * uma regra espalhada por muitos arquivos → corrige regra a regra; muitos
+ * arquivos/regras → agrupa por watchdog.
+ */
+
+import {
+	compareFindings,
+	type FindingState,
+	type FindingsStateFile,
+	filterFindings,
+} from "./findings-state";
+import { SEVERITY_ORDER, type Severity, severityRank } from "./types";
+
+/** Eixos possíveis de agrupamento do lote (ordem = prioridade de desempate). */
+export type GroupingDimension = "file" | "rule" | "watchdog";
+
+const GROUPING_DIMENSIONS: readonly GroupingDimension[] = ["file", "rule", "watchdog"];
+
+/** Tamanho de página padrão dentro do grupo atual. */
+export const FIX_BATCH_PAGE_SIZE = 8;
+
+const DIMENSION_PREFIX = /^(file|rule|watchdog):/;
+
+export type FixBatchOptions = {
+	/** Severidade alvo; ausente = todas. */
+	severity?: Severity;
+	/** Inclui achados já concluídos (default: só os pendentes). */
+	includeDone?: boolean;
+	/** Deslocamento dentro do grupo atual (default 0). */
+	offset?: number;
+	/** Chave do grupo alvo (default: o primeiro grupo). */
+	group?: string;
+	/** Tamanho da página dentro do grupo atual (default `FIX_BATCH_PAGE_SIZE`). */
+	pageSize?: number;
+};
+
+/** Referência a um grupo na lista dos "outros grupos". */
+export type FixBatchGroupRef = {
+	key: string;
+	label: string;
+	count: number;
+	bySeverity: Record<Severity, number>;
+};
+
+export type FixBatchCurrent = {
+	key: string;
+	label: string;
+	findings: FindingState[];
+	total: number;
+	offset: number;
+	returned: number;
+	/** Restantes no grupo atual após a página. */
+	remaining: number;
+};
+
+export type FixBatchResult = {
+	dimension: GroupingDimension;
+	current: FixBatchCurrent;
+	others: FixBatchGroupRef[];
+	totals: {
+		/** Itens na fila de correção. */
+		queue: number;
+		/** Total de grupos. */
+		groups: number;
+		/** Itens retornados na página do grupo atual. */
+		returned: number;
+	};
+};
+
+/**
+ * Fila de correção: findings `decision: execute`, presentes, excluindo `done`
+ * (salvo `includeDone`). Ordenados por severidade/arquivo/linha.
+ */
+export function fixQueue(
+	state: FindingsStateFile,
+	options: FixBatchOptions = {},
+): FindingState[] {
+	const filtered = filterFindings(state, {
+		decision: "execute",
+		severity: options.severity,
+	});
+	return options.includeDone
+		? filtered
+		: filtered.filter((finding) => finding.execState !== "done");
+}
+
+/** Escolhe a dimensão de agrupamento com melhor coesão para a fila. */
+export function chooseGrouping(findings: FindingState[]): GroupingDimension {
+	let best: { dimension: GroupingDimension; groups: number } | undefined;
+	for (const dimension of GROUPING_DIMENSIONS) {
+		const groups = groupFindings(findings, dimension).size;
+		if (groups === 0) continue;
+		if (findings.length / groups < 2) continue;
+		if (!best || groups < best.groups) best = { dimension, groups };
+	}
+	return best?.dimension ?? "file";
+}
+
+/** Agrupa os findings pela dimensão informada (chaves prefixadas pela dimensão). */
+export function groupFindings(
+	findings: readonly FindingState[],
+	dimension: GroupingDimension,
+): Map<string, FindingState[]> {
+	const groups = new Map<string, FindingState[]>();
+	for (const finding of findings) {
+		const key = groupKey(finding, dimension);
+		const list = groups.get(key);
+		if (list) list.push(finding);
+		else groups.set(key, [finding]);
+	}
+	return groups;
+}
+
+function groupKey(finding: FindingState, dimension: GroupingDimension): string {
+	if (dimension === "file") return `file:${finding.file}`;
+	if (dimension === "rule") return `rule:${finding.rule}`;
+	return `watchdog:${finding.watchdogIds[0] ?? "—"}`;
+}
+
+function labelOf(key: string): string {
+	return key.replace(DIMENSION_PREFIX, "");
+}
+
+function countBySeverity(findings: readonly FindingState[]): Record<Severity, number> {
+	const counts = Object.fromEntries(SEVERITY_ORDER.map((s) => [s, 0])) as Record<
+		Severity,
+		number
+	>;
+	for (const finding of findings) counts[finding.severity]++;
+	return counts;
+}
+
+function groupSeverityRank(findings: readonly FindingState[]): number {
+	let rank = Number.POSITIVE_INFINITY;
+	for (const finding of findings) rank = Math.min(rank, severityRank(finding.severity));
+	return rank;
+}
+
+/** Ordena os grupos: severidade mais grave primeiro → tamanho desc → chave. */
+function compareGroups(
+	a: readonly [string, FindingState[]],
+	b: readonly [string, FindingState[]],
+): number {
+	const bySeverity = groupSeverityRank(a[1]) - groupSeverityRank(b[1]);
+	if (bySeverity !== 0) return bySeverity;
+	if (a[1].length !== b[1].length) return b[1].length - a[1].length;
+	return a[0].localeCompare(b[0]);
+}
+
+/**
+ * Monta o lote de correção: escolhe o agrupamento, seleciona o grupo atual
+ * (primeiro, ou o `group` informado) paginado, e lista os demais grupos.
+ * Lança se o `group` informado não existir.
+ */
+export function buildFixBatch(
+	state: FindingsStateFile,
+	options: FixBatchOptions = {},
+): FixBatchResult {
+	const queue = fixQueue(state, options);
+	const dimension = chooseGrouping(queue);
+	const ordered = [...groupFindings(queue, dimension).entries()].sort(compareGroups);
+
+	if (ordered.length === 0) {
+		return {
+			dimension,
+			current: {
+				key: "",
+				label: "",
+				findings: [],
+				total: 0,
+				offset: 0,
+				returned: 0,
+				remaining: 0,
+			},
+			others: [],
+			totals: { queue: 0, groups: 0, returned: 0 },
+		};
+	}
+
+	if (options.group !== undefined && !ordered.some(([key]) => key === options.group)) {
+		const available = ordered.map(([key]) => key);
+		const preview = available.slice(0, 5).join(", ");
+		throw new Error(
+			`Grupo '${options.group}' não encontrado. Disponíveis: ${preview}${
+				available.length > 5 ? ", …" : ""
+			}.`,
+		);
+	}
+
+	const [key, members] = (
+		options.group ? ordered.find(([k]) => k === options.group) : ordered[0]
+	) as [string, FindingState[]];
+	const sorted = [...members].sort(compareFindings);
+	const offset = Math.max(0, options.offset ?? 0);
+	const pageSize = Math.max(1, options.pageSize ?? FIX_BATCH_PAGE_SIZE);
+	const page = sorted.slice(offset, offset + pageSize);
+
+	const others = ordered
+		.filter(([otherKey]) => otherKey !== key)
+		.map(([otherKey, otherMembers]) => ({
+			key: otherKey,
+			label: labelOf(otherKey),
+			count: otherMembers.length,
+			bySeverity: countBySeverity(otherMembers),
+		}));
+
+	return {
+		dimension,
+		current: {
+			key,
+			label: labelOf(key),
+			findings: page,
+			total: sorted.length,
+			offset,
+			returned: page.length,
+			remaining: Math.max(0, sorted.length - (offset + page.length)),
+		},
+		others,
+		totals: { queue: queue.length, groups: ordered.length, returned: page.length },
+	};
+}

package/src/core/git-revision.ts

@@ -0,0 +1,105 @@
+/**
+ * Operações de revisão do git (biblioteca).
+ *
+ * Resolução de refs, ancestralidade, leitura de arquivo por commit e diffs por
+ * intervalo (`from..to`) — a base do **review incremental** e da **verificação
+ * de findings**, que comparam contra um commit fixado (ex.: o `headSha` da
+ * última revisão) em vez do working tree.
+ *
+ * Genérico: nenhum path/id de consumidor aqui. Reusa os parsers de diff de
+ * `diff-source.ts` (`parseDiffIndex`/`parseNumstat`) e de `file-classifier.ts`
+ * (`parseEntries`) — não reimplementa leitura de diff.
+ */
+
+import {
+	DEFAULT_MAX_PER_FILE_CHARS,
+	type DiffSource,
+	parseDiffIndex,
+	parseNumstat,
+} from "./diff-source";
+import { parseEntries } from "./file-classifier";
+import type { FileChurn } from "./types";
+
+/** Executa `git` (paths literais) e devolve o stdout; lança se falhar. */
+export function runGit(args: string[]): string {
+	const result = Bun.spawnSync(["git", "-c", "core.quotepath=false", ...args], {
+		stdout: "pipe",
+		stderr: "pipe",
+	});
+	if (result.exitCode !== 0) {
+		const stderr = new TextDecoder().decode(result.stderr).trim();
+		throw new Error(`git ${args.join(" ")} falhou: ${stderr}`);
+	}
+	return new TextDecoder().decode(result.stdout);
+}
+
+/** SHA completo de uma ref (`git rev-parse`). Lança se a ref não resolver. */
+export function resolveSha(ref: string): string {
+	return runGit(["rev-parse", ref]).trim();
+}
+
+/** SHA do commit atual (`HEAD`). */
+export function currentHeadSha(): string {
+	return resolveSha("HEAD");
+}
+
+/**
+ * `true` se `ancestor` é ancestral de `descendant` — histórico linear/sem
+ * rebase, condição para o review incremental. Qualquer outro desfecho (ref
+ * desconhecida, exit ≠ 0) devolve `false`: cai no review completo, que é o
+ * comportamento seguro.
+ */
+export function isAncestor(ancestor: string, descendant: string): boolean {
+	const result = Bun.spawnSync(
+		["git", "merge-base", "--is-ancestor", ancestor, descendant],
+		{ stdout: "ignore", stderr: "ignore" },
+	);
+	return result.exitCode === 0;
+}
+
+/** Conteúdo de um arquivo num commit (`git show sha:path`); null se ausente. */
+export function readFileAt(sha: string, path: string): string | null {
+	const result = Bun.spawnSync(
+		["git", "-c", "core.quotepath=false", "show", `${sha}:${path}`],
+		{ stdout: "pipe", stderr: "ignore" },
+	);
+	if (result.exitCode !== 0) return null;
+	return new TextDecoder().decode(result.stdout);
+}
+
+/** Arquivos alterados num intervalo (`git diff range --name-status`). */
+export function diffEntries(range: string): ReturnType<typeof parseEntries> {
+	return parseEntries(runGit(["diff", range, "--name-status"]));
+}
+
+/** Churn por arquivo de um intervalo (`git diff --numstat -z range`). */
+export function diffNumstat(range: string): Map<string, FileChurn> {
+	return parseNumstat(runGit(["diff", "--numstat", "-z", range]));
+}
+
+/**
+ * Patch por arquivo de um intervalo, opcionalmente restrito a `paths`.
+ * `maxPerFileChars` trunca cada arquivo (default: mesmo teto do `collectDiff`).
+ */
+export function diffPatch(
+	range: string,
+	paths?: readonly string[],
+	maxPerFileChars: number = DEFAULT_MAX_PER_FILE_CHARS,
+): Map<string, string> {
+	const args = ["diff", range];
+	if (paths && paths.length > 0) args.push("--", ...paths);
+	return parseDiffIndex(runGit(args), maxPerFileChars);
+}
+
+/** Diff (patch + churn) de `from..to` — 2 spawns, base do review incremental. */
+export function collectDiffSince(
+	from: string,
+	to: string,
+	maxPerFileChars: number = DEFAULT_MAX_PER_FILE_CHARS,
+): DiffSource {
+	const range = `${from}..${to}`;
+	return {
+		byFile: parseDiffIndex(runGit(["diff", range]), maxPerFileChars),
+		churn: diffNumstat(range),
+	};
+}

package/src/core/jev/index.ts

@@ -10,3 +10,4 @@ export * from "./jev-client";
 export * from "./jev-detector";
 export * from "./jev-questions";
 export * from "./jev-types";
+export * from "./jev-verify";

package/src/core/jev/jev-client.ts

@@ -17,16 +17,27 @@ import type { JevEvaluateRequest, JevEvaluateResponse } from "./jev-types";
 const DEFAULT_BASE_URL = "https://api.typesafe.ai";
 const DEFAULT_MODEL = "jev-latest";
 const DEFAULT_TIMEOUT_MS = 20_000;
-/** Caminho fixo do endpoint System One. */
+/** Timeout da verificação de credencial do `doctor` (mais curto que o de review). */
+const DEFAULT_PING_TIMEOUT_MS = 10_000;
+/** Caminho fixo do endpoinft System One. */
 const JEV_PATH = "/v1/systemone";
 
 export class JevError extends Error {
-	constructor(message: string) {
+	/** Status HTTP da resposta, quando houver (indefinido em falha de rede). */
+	readonly status?: number;
+
+	constructor(message: string, status?: number) {
 		super(message);
 		this.name = "JevError";
+		this.status = status;
 	}
 }
 
+/** Resultado da verificação de credencial (`doctor`) — não lança, devolve dados. */
+export type JevCredentialCheck =
+	| { ok: true; model: string }
+	| { ok: false; kind: "invalid" | "unreachable"; detail: string };
+
 export type JevClientOptions = {
 	/** Chave de API (default: `process.env.TYPESAFE_API_KEY`). */
 	apiKey?: string;
@@ -78,22 +89,72 @@ export class JevClient {
 			);
 			return data;
 		} catch (error) {
-			throw new JevError(JevClient.describeError(error));
+			const { message, status } = JevClient.parseError(error);
+			throw new JevError(message, status);
+		}
+	}
+
+	/**
+	 * Verifica a credencial com uma chamada mínima (usada pelo `doctor`).
+	 *
+	 * Não lança: devolve o resultado tipado para o chamador decidir (fail-open).
+	 * 2xx → válida; 401/403 → inválida; demais → indeterminada (rede/timeout).
+	 */
+	async validateCredential(): Promise<JevCredentialCheck> {
+		if (!this.apiKey) {
+			return {
+				ok: false,
+				kind: "unreachable",
+				detail: "TYPESAFE_API_KEY não configurada.",
+			};
+		}
+		const request: JevEvaluateRequest = {
+			state: "Ping de verificação de credencial do houndsman.",
+			questions: {
+				ping: {
+					type: "noul",
+					instructions: 'A seguinte afirmação é verdadeira? "Este é um ping."',
+				},
+			},
+		};
+		try {
+			const { data } = await this.http.post<JevEvaluateResponse>(
+				JEV_PATH,
+				{ ...request, model: this.model },
+				{
+					headers: { Authorization: `Bearer ${this.apiKey}` },
+					timeout: DEFAULT_PING_TIMEOUT_MS,
+				},
+			);
+			return { ok: true, model: data.model ?? this.model };
+		} catch (error) {
+			const { message, status } = JevClient.parseError(error);
+			const kind = status === 401 || status === 403 ? "invalid" : "unreachable";
+			return { ok: false, kind, detail: message };
 		}
 	}
 
-	/** Normaliza o erro do axios em mensagem legível (sem expor o payload bruto). */
-	private static describeError(error: unknown): string {
+	/** Normaliza o erro do axios em `{ message, status }` (sem expor o payload bruto). */
+	private static parseError(error: unknown): {
+		message: string;
+		status?: number;
+	} {
 		if (isAxiosError(error)) {
 			const status = error.response?.status;
+			const responseData = error.response?.data;
 			const detail =
-				typeof error.response?.data === "string"
-					? error.response.data
-					: error.response?.data
-						? JSON.stringify(error.response.data)
+				typeof responseData === "string"
+					? responseData
+					: responseData
+						? responseData?.detail?.message || JSON.stringify(responseData)
 						: error.message;
-			return status ? `HTTP ${status}: ${detail}` : detail;
+			return {
+				message: status ? `HTTP ${status}: ${detail}` : detail,
+				status,
+			};
 		}
-		return error instanceof Error ? error.message : String(error);
+		return {
+			message: error instanceof Error ? error.message : String(error),
+		};
 	}
 }

package/src/core/jev/jev-detector.ts

@@ -9,6 +9,7 @@
  */
 
 import { readFileSync } from "node:fs";
+import { collectDiff, type DiffSource } from "../diff-source";
 import type { ClassificationResult } from "../file-classifier";
 import type { WatchdogMeta } from "../types";
 import {
@@ -25,6 +26,8 @@ export type DetectOptions = {
 	threshold?: number;
 	/** Nº de arquivos avaliados em paralelo. */
 	concurrency?: number;
+	/** Diff já coletado (evita novo `git diff`); ausente → coleta aqui. */
+	diff?: DiffSource;
 };
 
 export type DetectResult = {
@@ -60,6 +63,7 @@ export class JevDetector {
 	): Promise<DetectResult> {
 		const threshold = options.threshold ?? JevCandidatesStore.THRESHOLD;
 		const concurrency = options.concurrency ?? JevDetector.DEFAULT_CONCURRENCY;
+		const diff = this.resolveDiff(base, head, options.diff);
 
 		const jobs = this.buildJobs(classification);
 		const questionByKey = new Map<string, DerivedQuestion>();
@@ -76,7 +80,7 @@ export class JevDetector {
 			for (const dq of job.questions) questions[dq.key] = dq.question;
 
 			const status = classification.files[job.file]?.status ?? "modified";
-			const state = this.buildState(job.file, status, base, head);
+			const state = this.buildState(job.file, status, diff);
 
 			try {
 				const response = await this.client.evaluate({ state, questions });
@@ -125,15 +129,24 @@ export class JevDetector {
 			.filter((job) => job.questions.length > 0);
 	}
 
+	/**
+	 * Diff para o `state`: reaproveita o injetado ou coleta **uma vez**. Tolerante
+	 * a falha — o Jev é opcional/fail-open.
+	 */
+	private resolveDiff(base: string, head: string, provided?: DiffSource): DiffSource {
+		if (provided) return provided;
+		try {
+			return collectDiff(base, head);
+		} catch {
+			return { byFile: new Map<string, string>(), churn: new Map() };
+		}
+	}
+
 	/** Monta o `state` de um arquivo: cabeçalho + hunk do diff, com cap de tamanho. */
-	private buildState(
-		filePath: string,
-		status: string,
-		base: string,
-		head: string,
-	): string {
+	private buildState(filePath: string, status: string, diff: DiffSource): string {
 		const header = this.readHeader(filePath);
-		const hunk = this.readHunk(base, head, filePath);
+		const hunk =
+			diff.byFile.get(filePath)?.slice(0, JevDetector.MAX_DIFF_CHARS) ?? "";
 		const parts = [`Arquivo: ${filePath} (${status})`];
 		if (header) {
 			parts.push("--- topo do arquivo (imports/declarações) ---", header);
@@ -153,17 +166,6 @@ export class JevDetector {
 		}
 	}
 
-	private readHunk(base: string, head: string, filePath: string): string {
-		const result = Bun.spawnSync(
-			["git", "diff", `${base}...${head}`, "--", filePath],
-			{ stdout: "pipe", stderr: "pipe" },
-		);
-		if (result.exitCode !== 0) return "";
-		return new TextDecoder()
-			.decode(result.stdout)
-			.slice(0, JevDetector.MAX_DIFF_CHARS);
-	}
-
 	/** Arquivo → watchdogs que o cobrem. */
 	private static mapFilesToWatchdogs(
 		classification: ClassificationResult,