@payconductor/houndsman 0.1.0 → 0.1.1

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** (antes era
+	 * 1 `git diff` por arquivo). 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,

package/src/core/orchestrator.ts

@@ -17,9 +17,20 @@
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { join, relative } from "node:path";
 import { renderBrief } from "./brief";
-import type { HoundsmanConfig } from "./config";
+import {
+	type HoundsmanConfig,
+	resolveJevConcurrency,
+	resolveMaxFilesPerBrief,
+} from "./config";
+import { collectDiff, type DiffSource } from "./diff-source";
 import { discoverDocs } from "./doc-discoverer";
-import { type ClassificationResult, classifyRange } from "./file-classifier";
+import {
+	type BudgetSelection,
+	type ClassificationResult,
+	classifyRange,
+	selectByBudget,
+} from "./file-classifier";
+import { buildStateFromFindings, FindingsStateStore, fileReader } from "./findings-state";
 import {
 	type JevCandidate,
 	type JevCandidatesFile,
@@ -31,8 +42,10 @@ import { ARTIFACT_DIR, OUTPUT_FORMAT_PATH } from "./paths";
 import { contextPaths, currentBranch, readContextSummary } from "./pr-context";
 import {
 	type ContextSummary,
+	type DomainReport,
 	dedupeFindings,
 	parseWatchdogReport,
+	renderDomainReport,
 	renderReport,
 	sanitizeBranch,
 	type WatchdogReport,
@@ -150,6 +163,22 @@ function writeManifest(
 	jev: JevCandidatesFile,
 	config: HoundsmanConfig,
 ): void {
+	const maxFilesPerBrief = resolveMaxFilesPerBrief(config);
+	let filesOverBudget = 0;
+	const watchdogs = activeIds.map((id) => {
+		const selection = budgetFor(classification, id, maxFilesPerBrief);
+		filesOverBudget += selection.overflow.length;
+		return {
+			id,
+			name: findWatchdog(config, id)?.name ?? id,
+			files: selection.selected,
+			overflow: selection.overflow.length,
+			brief: relFromRoot(join(outDir, "briefs", `${id}.md`)),
+			findings: relFromRoot(join(outDir, "findings", `${id}.json`)),
+			status: pending.includes(id) ? "pending" : "done",
+		};
+	});
+
 	const manifest = {
 		branch,
 		slug: sanitizeBranch(branch),
@@ -157,14 +186,9 @@ function writeManifest(
 		head: opts.head,
 		generatedAt: new Date().toISOString(),
 		outputFormat: OUTPUT_FORMAT_PATH,
-		watchdogs: activeIds.map((id) => ({
-			id,
-			name: findWatchdog(config, id)?.name ?? id,
-			files: classification.watchdogs[id] ?? [],
-			brief: relFromRoot(join(outDir, "briefs", `${id}.md`)),
-			findings: relFromRoot(join(outDir, "findings", `${id}.json`)),
-			status: pending.includes(id) ? "pending" : "done",
-		})),
+		budget: { maxFilesPerBrief, filesOverBudget },
+		churn: churnTotals(classification),
+		watchdogs,
 		context: contextManifest(opts, branch),
 		jev: jev.available
 			? {
@@ -186,6 +210,37 @@ function writeManifest(
 	);
 }
 
+// ---------------------------------------------------------------------------
+// Orçamento (triage de PRs grandes)
+// ---------------------------------------------------------------------------
+
+/** Aplica o orçamento aos arquivos de um watchdog. */
+function budgetFor(
+	classification: ClassificationResult,
+	id: string,
+	maxFiles: number,
+): BudgetSelection {
+	return selectByBudget(
+		classification.watchdogs[id] ?? [],
+		classification.churn,
+		maxFiles,
+	);
+}
+
+/** Totais de churn do diff (métricas do manifesto). */
+function churnTotals(classification: ClassificationResult): {
+	additions: number;
+	deletions: number;
+} {
+	let additions = 0;
+	let deletions = 0;
+	for (const entry of Object.values(classification.churn ?? {})) {
+		additions += entry.additions;
+		deletions += entry.deletions;
+	}
+	return { additions, deletions };
+}
+
 // ---------------------------------------------------------------------------
 // Briefs
 // ---------------------------------------------------------------------------
@@ -200,14 +255,17 @@ function writeBriefs(
 	config: HoundsmanConfig,
 ): void {
 	const docs = discoverDocs(Object.keys(classification.files), config);
+	const maxFilesPerBrief = resolveMaxFilesPerBrief(config);
 	for (const id of activeIds) {
 		const def = findWatchdog(config, id);
 		if (!def) continue;
-		const files = classification.watchdogs[id] ?? [];
+		const { selected, overflow } = budgetFor(classification, id, maxFilesPerBrief);
 		const brief = renderBrief(def, {
 			watchdogId: id,
-			files,
+			files: selected,
 			statuses: classification.files,
+			churn: classification.churn,
+			overflow,
 			deleted: classification.deleted,
 			branch,
 			outputPath: relFromRoot(join(dirs.findingsDir, `${id}.json`)),
@@ -233,6 +291,7 @@ async function resolveCandidates(
 	classification: ClassificationResult,
 	dirs: Paths,
 	config: HoundsmanConfig,
+	diff: DiffSource,
 ): Promise<JevCandidatesFile> {
 	const store = new JevCandidatesStore(
 		join(dirs.outDir, "candidates.json"),
@@ -257,7 +316,10 @@ async function resolveCandidates(
 			client,
 			config.watchdogs as Record<string, WatchdogMeta>,
 		);
-		const result = await detector.detect(classification, opts.base, opts.head);
+		const result = await detector.detect(classification, opts.base, opts.head, {
+			diff,
+			concurrency: resolveJevConcurrency(config),
+		});
 		return save({
 			available: true,
 			model: result.model,
@@ -301,6 +363,22 @@ function printDiscovery(
 	}
 }
 
+/** Resumo do orçamento — só quando algum arquivo ficou de fora (PR grande). */
+function printBudget(
+	classification: ClassificationResult,
+	config: HoundsmanConfig,
+): void {
+	const maxFiles = resolveMaxFilesPerBrief(config);
+	let overflow = 0;
+	for (const id of Object.keys(classification.watchdogs)) {
+		overflow += budgetFor(classification, id, maxFiles).overflow.length;
+	}
+	if (overflow === 0) return;
+	console.log(
+		`Orçamento: ${maxFiles} arquivo(s)/brief — ${overflow} fora do orçamento (menor churn; registrar em skipped).`,
+	);
+}
+
 /** Passo 1 — descobre os arquivos e grava briefs + manifesto. */
 export async function prepare(
 	opts: ReviewOptions,
@@ -310,13 +388,15 @@ export async function prepare(
 ): Promise<void> {
 	prepareDirs(dirs, opts.clean);
 
-	const classification = classifyRange(opts.base, opts.head, config);
+	// Um único diff para toda a execução (churn + patch) — antes: 1 spawn por arquivo.
+	const diff = collectDiff(opts.base, opts.head);
+	const classification = classifyRange(opts.base, opts.head, config, diff);
 	writeFileSync(
 		join(dirs.outDir, "classification.json"),
 		`${JSON.stringify(classification, null, 2)}\n`,
 	);
 
-	const jev = await resolveCandidates(opts, classification, dirs, config);
+	const jev = await resolveCandidates(opts, classification, dirs, config, diff);
 
 	const activeIds = Object.keys(classification.watchdogs);
 	if (Object.keys(classification.files).length === 0) {
@@ -342,6 +422,7 @@ export async function prepare(
 		config,
 	);
 	printDiscovery(activeIds, classification, dirs.briefsDir);
+	printBudget(classification, config);
 	printJevSummary(jev);
 
 	if (context) {
@@ -369,7 +450,53 @@ function readClassification(classificationPath: string): ClassificationResult {
 			`Não encontrei ${relFromRoot(classificationPath)}. Rode \`bun run houndsman\` (preparar) primeiro.`,
 		);
 	}
-	return JSON.parse(readFileSync(classificationPath, "utf8"));
+	const parsed = JSON.parse(
+		readFileSync(classificationPath, "utf8"),
+	) as ClassificationResult;
+	// Compatível com classification.json gerado antes do churn existir.
+	parsed.churn ??= {};
+	return parsed;
+}
+
+/**
+ * Grava um `review.<watchdog>.md` por watchdog com achados e devolve o índice.
+ * Mantém o `review.md` consolidado navegável em PRs grandes (centenas de achados).
+ */
+function writeDomainReports(
+	outDir: string,
+	branch: string,
+	reports: WatchdogReport[],
+	classification: ClassificationResult,
+	context: ContextSummary | null,
+	nameOf: (id: string) => string,
+): DomainReport[] {
+	const domains: DomainReport[] = [];
+	for (const report of reports) {
+		const findings = dedupeFindings([report]);
+		if (findings.length === 0) continue;
+		const file = `review.${sanitizeBranch(report.watchdogId)}.md`;
+		const expected = classification.watchdogs[report.watchdogId] ?? [];
+		writeFileSync(
+			join(outDir, file),
+			`${renderDomainReport(
+				branch,
+				report,
+				findings,
+				expected.length,
+				context,
+				nameOf,
+			)}\n`,
+		);
+		domains.push({
+			id: report.watchdogId,
+			name: nameOf(report.watchdogId),
+			file,
+			findings: findings.length,
+			reviewedFiles: report.reviewedFiles.length,
+			expectedFiles: expected.length,
+		});
+	}
+	return domains;
 }
 
 export type FinalizeResult = {
@@ -416,7 +543,31 @@ export function finalize(
 	}
 
 	const merged = dedupeFindings(reports);
+
+	// Estado de triagem: preserva o que já existia (casando por fingerprint) e
+	// anexa o `id` de cada finding aos itens do relatório. A linha é cache —
+	// recalculada por `houndsman findings sync` após edições.
+	const store = FindingsStateStore.at(opts.dir, branch);
+	const state = buildStateFromFindings(merged, {
+		branch,
+		readFile: fileReader(process.cwd()),
+		previous: store.read(),
+	});
+	store.write(state);
+	console.log(
+		`Triagem: ${relFromRoot(store.filePath)} — ${Object.keys(state.findings).length} finding(s).`,
+	);
+
 	const context = readContextSummary(contextPaths(opts.dir, branch).summary);
+	const nameOf = (id: string): string => findWatchdog(config, id)?.name ?? id;
+	const domains = writeDomainReports(
+		dirs.outDir,
+		branch,
+		reports,
+		classification,
+		context,
+		nameOf,
+	);
 	const markdown = renderReport(
 		branch,
 		reports,
@@ -424,7 +575,8 @@ export function finalize(
 		{ classified: classification.watchdogs },
 		context,
 		jev.available ? jev.candidates : undefined,
-		(id) => findWatchdog(config, id)?.name ?? id,
+		nameOf,
+		domains,
 	);
 	const reportPath = join(dirs.outDir, "review.md");
 	writeFileSync(reportPath, `${markdown}\n`);

package/src/core/paths.ts

@@ -28,3 +28,6 @@ export const ARTIFACT_DIR = `${PROJECT_DIR}/.runs`;
 
 /** Schema de output dos watchdogs, citado nos briefs. */
 export const OUTPUT_FORMAT_PATH = `${CORE_SKILL_DIR}/${OUTPUT_FORMAT_FILE}`;
+
+/** Estado de triagem dos findings, dentro da pasta da run (`<slug>/state.json`). */
+export const STATE_FILE = "state.json";

package/src/core/registry-check.ts

@@ -127,6 +127,20 @@ function checkRulePolarity(config: HoundsmanConfig, warnings: string[]): void {
 	}
 }
 
+/** Aviso para orçamento/concorrência inválidos — o motor cai no default. */
+function checkBudgets(config: HoundsmanConfig, warnings: string[]): void {
+	const maxFiles = config.budgets?.maxFilesPerBrief;
+	if (maxFiles !== undefined && maxFiles <= 0) {
+		warnings.push(
+			`budgets.maxFilesPerBrief = ${maxFiles} — não-positivo; usando o default.`,
+		);
+	}
+	const jev = config.concurrency?.jev;
+	if (jev !== undefined && jev <= 0) {
+		warnings.push(`concurrency.jev = ${jev} — não-positivo; usando o default.`);
+	}
+}
+
 export function checkRegistry(config: HoundsmanConfig): {
 	problems: string[];
 	warnings: string[];
@@ -139,6 +153,7 @@ export function checkRegistry(config: HoundsmanConfig): {
 	checkClassification(config, problems);
 	checkRendering(config, problems);
 	checkRulePolarity(config, warnings);
+	checkBudgets(config, warnings);
 	const jevQuestions = checkJevSpecs(config, problems);
 
 	return { problems, warnings, jevQuestions };

package/src/core/report-builder.ts

@@ -16,6 +16,8 @@ export type WatchdogNameResolver = (watchdogId: string) => string;
 const identityName: WatchdogNameResolver = (id) => id;
 
 export type Finding = {
+	/** Id curto do finding (preenchido no `--finalize`; usado pela triagem). */
+	id?: string;
 	rule: string;
 	severity: Severity;
 	file: string;
@@ -206,8 +208,9 @@ function watchdogName(nameOf: WatchdogNameResolver, id: string): string {
 function renderFinding(finding: MergedFinding, nameOf: WatchdogNameResolver): string[] {
 	const location = finding.line ? `${finding.file}:${finding.line}` : finding.file;
 	const watchdogs = finding.watchdogs.map((r) => watchdogName(nameOf, r)).join(", ");
+	const id = finding.id ? ` · \`${finding.id}\`` : "";
 	const lines = [
-		`- **${finding.rule}** — \`${location}\` · _${watchdogs}_`,
+		`- **${finding.rule}** — \`${location}\` · _${watchdogs}_${id}`,
 		`  ${finding.message}`,
 		`  **Ação:** ${finding.action}`,
 	];
@@ -284,6 +287,112 @@ function renderConclusion(counts: Record<Severity, number>): string[] {
 	];
 }
 
+/**
+ * Agrupa os achados por arquivo (navegabilidade em PRs grandes) e renderiza cada
+ * bloco. O `merged` já vem ordenado por severidade/arquivo/linha.
+ */
+function renderFindingsByFile(
+	findings: readonly MergedFinding[],
+	nameOf: WatchdogNameResolver,
+): string[] {
+	const byFile = new Map<string, MergedFinding[]>();
+	for (const finding of findings) {
+		const list = byFile.get(finding.file);
+		if (list) list.push(finding);
+		else byFile.set(finding.file, [finding]);
+	}
+
+	const lines: string[] = [];
+	for (const [file, items] of byFile) {
+		lines.push(`### \`${file}\``, "");
+		for (const item of items) lines.push(...renderFinding(item, nameOf));
+	}
+	return lines;
+}
+
+/** Seções por severidade (❌ > ⚠️ > 💡 > 🔎), com achados agrupados por arquivo. */
+function renderFindingsSections(
+	merged: readonly MergedFinding[],
+	nameOf: WatchdogNameResolver,
+): string[] {
+	const lines: string[] = [];
+	for (const severity of SEVERITY_ORDER) {
+		const items = merged.filter((f) => f.severity === severity);
+		if (items.length === 0) continue;
+		lines.push(`## ${SEVERITY_EMOJI[severity]} ${severity}`, "");
+		lines.push(...renderFindingsByFile(items, nameOf));
+	}
+	return lines;
+}
+
+/** Relatório de domínio gravado à parte (um por watchdog com achados). */
+export type DomainReport = {
+	id: string;
+	name: string;
+	/** Nome do arquivo do relatório (relativo ao diretório de artefatos). */
+	file: string;
+	findings: number;
+	reviewedFiles: number;
+	expectedFiles: number;
+};
+
+/** Índice dos relatórios por domínio (seção do `review.md` consolidado). */
+function renderDomainIndex(domains: readonly DomainReport[]): string[] {
+	if (domains.length === 0) return [];
+	const lines = [
+		"## Relatórios por domínio",
+		"",
+		"| Watchdog | Achados | Revisados | Relatório |",
+		"|---|---|---|---|",
+	];
+	for (const domain of domains) {
+		lines.push(
+			`| ${domain.name} | ${domain.findings} | ${domain.reviewedFiles}/${domain.expectedFiles} | [\`${domain.file}\`](${domain.file}) |`,
+		);
+	}
+	lines.push("");
+	return lines;
+}
+
+/**
+ * Relatório isolado de um watchdog — mantém o `review.md` enxuto em PRs grandes.
+ */
+export function renderDomainReport(
+	branch: string,
+	report: WatchdogReport,
+	merged: MergedFinding[],
+	expectedFiles: number,
+	context?: ContextSummary | null,
+	nameOf: WatchdogNameResolver = identityName,
+): string {
+	const now = new Date().toISOString().slice(0, 10);
+	const name = watchdogName(nameOf, report.watchdogId);
+	const lines: string[] = [
+		`# Review — ${name} (\`${report.watchdogId}\`) — ${branch}`,
+		"",
+		`**Data:** ${now}`,
+		`**Arquivos revisados:** ${report.reviewedFiles.length}/${expectedFiles}`,
+		`**Achados:** ${merged.length}`,
+		"",
+	];
+
+	if (context?.available) lines.push(...renderContext(context));
+
+	lines.push(...renderFindingsSections(merged, nameOf));
+	if (merged.length === 0) lines.push("Nenhum achado. ✅", "");
+
+	if (report.skipped.length > 0) {
+		lines.push(
+			"## Não revisados",
+			"",
+			...report.skipped.map((item) => `- \`${item}\``),
+			"",
+		);
+	}
+
+	return lines.join("\n");
+}
+
 /** Seção de contexto da PR (Objetivo / Motivação / Resumo das alterações). */
 function renderContext(context: ContextSummary): string[] {
 	const lines = ["## Contexto da PR", ""];
@@ -313,6 +422,7 @@ export function renderReport(
 	context?: ContextSummary | null,
 	candidates?: JevCandidate[],
 	nameOf: WatchdogNameResolver = identityName,
+	domains: readonly DomainReport[] = [],
 ): string {
 	const now = new Date().toISOString().slice(0, 10);
 	const counts = {
@@ -333,14 +443,7 @@ export function renderReport(
 
 	if (context) lines.push(...renderContext(context));
 
-	for (const severity of SEVERITY_ORDER) {
-		const items = merged.filter((f) => f.severity === severity);
-		if (items.length === 0) continue;
-		lines.push(`## ${SEVERITY_EMOJI[severity]} ${severity}`, "");
-		for (const finding of items) {
-			lines.push(...renderFinding(finding, nameOf));
-		}
-	}
+	lines.push(...renderFindingsSections(merged, nameOf));
 
 	if (merged.length === 0) {
 		lines.push("Nenhum achado. ✅", "");
@@ -350,6 +453,7 @@ export function renderReport(
 		lines.push(...renderUnconfirmedCandidates(candidates, merged));
 	}
 
+	lines.push(...renderDomainIndex(domains));
 	lines.push(...renderCoverage(reports, coverage, nameOf));
 	lines.push(...renderConclusion(counts));
 

package/src/core/types.ts

@@ -79,6 +79,12 @@ export type FileStatus =
 /** Status por arquivo, conforme o `classification.json`. */
 export type FileStatusMap = Record<string, { status: FileStatus; oldPath?: string }>;
 
+/** Linhas adicionadas/removidas de um arquivo no diff (churn). */
+export type FileChurn = { additions: number; deletions: number };
+
+/** Churn por caminho de arquivo (chave = caminho novo). */
+export type ChurnMap = Record<string, FileChurn>;
+
 /** Contexto da PR injetado no brief (estrutural — sem dependência de runtime). */
 export type WatchdogRenderContext = {
 	objective?: string;
@@ -99,6 +105,10 @@ export type WatchdogRenderArgs = {
 	watchdogId: string;
 	files: readonly string[];
 	statuses: FileStatusMap;
+	/** Churn por arquivo — insumo para priorizar a leitura (PRs grandes). */
+	churn?: ChurnMap;
+	/** Arquivos do domínio fora do orçamento — NÃO revisar (registrar em `skipped`). */
+	overflow?: readonly string[];
 	deleted: readonly string[];
 	branch: string;
 	outputPath: string;