@payconductor/houndsman 0.1.1 → 0.1.4

package/src/core/findings-state.ts

@@ -67,6 +67,13 @@ export type FindingHistoryEntry = {
 	by?: string;
 };
 
+/** Marco da revisão que originou o estado: commit revisado + quando. */
+export type FindingsReviewed = {
+	/** SHA do commit revisado (head do diff no `--finalize`). */
+	headSha: string;
+	at: string;
+};
+
 /** Um finding triável, com o estado das duas dimensões. */
 export type FindingState = {
 	id: string;
@@ -80,6 +87,8 @@ export type FindingState = {
 	action: string;
 	evidence?: string;
 	anchor: FindingAnchor | null;
+	/** Commit em que o achado foi observado (base do diff focado do verify). */
+	foundAtSha?: string;
 	/** Ocorrências idênticas colapsadas neste fingerprint (>1 = grupo). */
 	count: number;
 	/** Ainda presente no último relatório consolidado. */
@@ -94,16 +103,18 @@ export type FindingState = {
 
 /** Conteúdo do `state.json`. */
 export type FindingsStateFile = {
-	version: 1;
+	version: 2;
 	branch: string;
 	slug: string;
 	updatedAt: string;
 	/** Ids na ordem de exibição (estável). */
 	order: string[];
+	/** Commit revisado — habilita o review incremental e o verify por diff. */
+	reviewed?: FindingsReviewed;
 	findings: Record<string, FindingState>;
 };
 
-export const FINDINGS_STATE_VERSION = 1;
+export const FINDINGS_STATE_VERSION = 2;
 
 // ---------------------------------------------------------------------------
 // Caminhos
@@ -249,6 +260,10 @@ export type BuildStateOptions = {
 	branch: string;
 	readFile: FileReader;
 	previous?: FindingsStateFile | null;
+	/** Commit revisado — carimbado nos findings e no `reviewed` do estado. */
+	reviewed?: FindingsReviewed;
+	/** SHA usado para carimbar `foundAtSha` de findings novos/re-reportados. */
+	headSha?: string;
 	now?: string;
 };
 
@@ -320,6 +335,8 @@ export function buildStateFromFindings(
 			action: finding.action,
 			evidence: finding.evidence,
 			anchor,
+			// Carry-over preserva o `foundAtSha` original; novos/re-reportados usam o head atual.
+			foundAtSha: finding.foundAtSha ?? options.headSha ?? prev?.foundAtSha,
 			count: 1,
 			present: true,
 			decision: prev?.decision ?? "pending",
@@ -340,6 +357,7 @@ export function buildStateFromFindings(
 		slug: sanitizeBranch(options.branch),
 		updatedAt: now,
 		order: [],
+		reviewed: options.reviewed ?? previous?.reviewed,
 		findings: result,
 	};
 	reorder(state);

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-detector.ts

@@ -130,8 +130,8 @@ export class JevDetector {
 	}
 
 	/**
-	 * Diff para o `state`: reaproveita o injetado ou coleta **uma vez** (antes era
-	 * 1 `git diff` por arquivo). Tolerante a falha — o Jev é opcional/fail-open.
+	 * 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;

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

@@ -0,0 +1,178 @@
+/**
+ * Confirmação Jev dos findings ambíguos (tier 1 do `findings verify`).
+ *
+ * Por arquivo: monta um `state` pequeno (topo do arquivo + diff focado
+ * `foundAtSha..head`) e, numa única chamada, pergunta se cada violação ainda
+ * ocorre. **Falha-aberto** — sem chave/erro, nada é confirmado: o tier local
+ * decide. O custo é uma chamada por arquivo ambíguo, não uma revisão completa.
+ */
+
+import { diffPatch, readFileAt } from "../git-revision";
+import type { JevClient } from "./jev-client";
+import type { JevAnswer, JevQuestion } from "./jev-types";
+
+/** Caso ambíguo a confirmar com o Jev. */
+export type JevVerifyCase = {
+	id: string;
+	file: string;
+	rule: string;
+	/** Commit em que o achado foi observado (base do diff focado). */
+	foundAtSha?: string;
+};
+
+export type JevVerifyOptions = {
+	/** Commit atual (head) para o diff focado. */
+	headSha?: string;
+	/** Nº de arquivos avaliados em paralelo. */
+	concurrency?: number;
+};
+
+export type JevVerifyOutcome = {
+	/** id → confiança (0–1) de a violação ainda ocorrer. */
+	confidence: Map<string, number>;
+	checked: number;
+	skipped: number;
+	reason?: string;
+};
+
+/** Linhas iniciais do arquivo incluídas no `state` (contexto de imports). */
+const HEADER_LINES = 60;
+const MAX_STATE_CHARS = 8_000;
+const MAX_DIFF_CHARS = 4_000;
+const DEFAULT_CONCURRENCY = 5;
+
+/** Início do diff do grupo: o `foundAtSha` mais antigo informado. */
+function referenceOf(
+	group: readonly JevVerifyCase[],
+	headSha: string | undefined,
+): { from: string; to: string } | null {
+	const from = group.find((item) => item.foundAtSha)?.foundAtSha;
+	if (!from || !headSha || from === headSha) return null;
+	return { from, to: headSha };
+}
+
+/** Arquivo → casos daquele arquivo (uma chamada por arquivo). */
+function groupByFile(cases: readonly JevVerifyCase[]): Map<string, JevVerifyCase[]> {
+	const map = new Map<string, JevVerifyCase[]>();
+	for (const item of cases) {
+		const list = map.get(item.file);
+		if (list) list.push(item);
+		else map.set(item.file, [item]);
+	}
+	return map;
+}
+
+/** Executa `fn` sobre `items` com concorrência limitada (ordem irrelevante). */
+async function mapWithConcurrency<T>(
+	items: readonly T[],
+	limit: number,
+	fn: (item: T) => Promise<void>,
+): Promise<void> {
+	let cursor = 0;
+	const workers = Array.from({ length: Math.min(limit, items.length) }, async () => {
+		while (cursor < items.length) {
+			const current = items[cursor++];
+			await fn(current);
+		}
+	});
+	await Promise.all(workers);
+}
+
+/** Confirma com o Jev se as violações ambíguas ainda ocorrem. */
+export class JevVerifier {
+	private readonly client: JevClient;
+
+	/** Construtor que recebe o cliente (injeção). */
+	constructor(client: JevClient) {
+		this.client = client;
+	}
+
+	/** `true` se há chave configurada (sem chave o tier 1 é pulado). */
+	isConfigured(): boolean {
+		return this.client.isConfigured();
+	}
+
+	/** Avalia os casos ambíguos e devolve a confiança por id. */
+	async verify(
+		cases: readonly JevVerifyCase[],
+		options: JevVerifyOptions = {},
+	): Promise<JevVerifyOutcome> {
+		const confidence = new Map<string, number>();
+		if (cases.length === 0) return { confidence, checked: 0, skipped: 0 };
+		if (!this.client.isConfigured()) {
+			return {
+				confidence,
+				checked: 0,
+				skipped: cases.length,
+				reason: "TYPESAFE_API_KEY não configurada",
+			};
+		}
+
+		const groups = [...groupByFile(cases).values()];
+		const jobs = groups.filter((group) => referenceOf(group, options.headSha));
+		const withoutRef =
+			cases.length - jobs.reduce((sum, group) => sum + group.length, 0);
+		let skipped = withoutRef;
+
+		await mapWithConcurrency(
+			jobs,
+			options.concurrency ?? DEFAULT_CONCURRENCY,
+			async (group) => {
+				try {
+					const answers = await this.evaluateGroup(group, options.headSha);
+					for (const item of group) {
+						const answer = answers[item.id];
+						if (answer?.type === "noul") confidence.set(item.id, answer.noul);
+					}
+				} catch {
+					skipped += group.length;
+				}
+			},
+		);
+
+		return {
+			confidence,
+			checked: confidence.size,
+			skipped,
+			reason:
+				withoutRef > 0
+					? "sem commit de referência (foundAtSha) em algum arquivo"
+					: undefined,
+		};
+	}
+
+	/** Uma chamada por arquivo: `state` focado + uma pergunta por caso. */
+	private async evaluateGroup(
+		group: readonly JevVerifyCase[],
+		headSha: string | undefined,
+	): Promise<Record<string, JevAnswer>> {
+		const reference = referenceOf(group, headSha);
+		if (!reference) throw new Error("sem commit de referência para o diff focado.");
+
+		const file = group[0].file;
+		const patch =
+			diffPatch(`${reference.from}..${reference.to}`, [file]).get(file) ?? "";
+		const header = (readFileAt(reference.to, file) ?? "")
+			.split("\n")
+			.slice(0, HEADER_LINES)
+			.join("\n");
+
+		const parts = [`Arquivo: ${file}`];
+		if (header) parts.push("--- topo do arquivo ---", header);
+		if (patch) {
+			parts.push("--- diff desde a revisão ---", patch.slice(0, MAX_DIFF_CHARS));
+		}
+		const state = parts.join("\n").slice(0, MAX_STATE_CHARS);
+
+		const questions: Record<string, JevQuestion> = {};
+		for (const item of group) {
+			questions[item.id] = {
+				type: "noul",
+				instructions: `No estado fornecido, a violação a seguir ainda ocorre? "${item.rule}"`,
+			};
+		}
+
+		const response = await this.client.evaluate({ state, questions });
+		return response.answers;
+	}
+}