@payconductor/houndsman 0.1.0 → 0.1.3

package/src/core/orchestrator.ts

@@ -17,9 +17,27 @@
 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 { churnToRecord, collectDiff, type DiffSource } from "./diff-source";
 import { discoverDocs } from "./doc-discoverer";
-import { type ClassificationResult, classifyRange } from "./file-classifier";
+import {
+	type BudgetSelection,
+	type ClassificationResult,
+	classifyEntries,
+	classifyRange,
+	selectByBudget,
+} from "./file-classifier";
+import {
+	buildStateFromFindings,
+	type FindingsStateFile,
+	FindingsStateStore,
+	fileReader,
+} from "./findings-state";
+import { collectDiffSince, diffEntries, isAncestor, resolveSha } from "./git-revision";
 import {
 	type JevCandidate,
 	type JevCandidatesFile,
@@ -31,13 +49,17 @@ import { ARTIFACT_DIR, OUTPUT_FORMAT_PATH } from "./paths";
 import { contextPaths, currentBranch, readContextSummary } from "./pr-context";
 import {
 	type ContextSummary,
+	type DomainReport,
 	dedupeFindings,
+	type MergedFinding,
 	parseWatchdogReport,
+	renderDomainReport,
 	renderReport,
 	sanitizeBranch,
 	type WatchdogReport,
 } from "./report-builder";
-import type { WatchdogMeta } from "./types";
+import { writeRunStatus } from "./run-status";
+import { severityRank, type WatchdogMeta } from "./types";
 import { findWatchdog } from "./watchdog-registry";
 
 export type ReviewOptions = {
@@ -49,6 +71,8 @@ export type ReviewOptions = {
 	failOnBlocking: boolean;
 	clean: boolean;
 	noJev: boolean;
+	/** Força review completo (ignora o modo incremental). */
+	full: boolean;
 };
 
 /** Valores default das opções (o CLI sobrepõe com as flags). */
@@ -61,6 +85,7 @@ export function defaultOptions(artifactDir: string = ARTIFACT_DIR): ReviewOption
 		failOnBlocking: false,
 		clean: false,
 		noJev: false,
+		full: false,
 	};
 }
 
@@ -96,6 +121,142 @@ function prepareDirs(dirs: Paths, clean: boolean): void {
 	}
 }
 
+// ---------------------------------------------------------------------------
+// Escopo da revisão (completo vs incremental)
+// ---------------------------------------------------------------------------
+
+/** Classificação enriquecida gravada no `classification.json` (modo + revisão + carry-over). */
+type RunClassification = ClassificationResult & {
+	/** Commit revisado (head do diff). */
+	headSha?: string;
+	/** Modo do prepare: completo ou incremental (delta desde a última revisão). */
+	mode: "full" | "incremental";
+	/** Commit da última revisão (só no incremental). */
+	reviewedFrom?: string;
+	/** Findings preservados do review anterior (arquivos inalterados). */
+	carryover?: MergedFinding[];
+};
+
+/** SHA curto para logs (7 chars, como o git). */
+function shortSha(sha: string): string {
+	return sha.slice(0, 7);
+}
+
+/** Chave de dedupe de finding: `(file, line, rule)` — igual ao `dedupeFindings`. */
+function findingKey(finding: Pick<MergedFinding, "file" | "line" | "rule">): string {
+	return `${finding.file}|${finding.line ?? ""}|${finding.rule}`;
+}
+
+/** Aviso no topo do `review.md` quando a revisão foi incremental (senão vazio). */
+function incrementalNote(classification: RunClassification): string {
+	if (classification.mode !== "incremental" || !classification.reviewedFrom) return "";
+	const carried = classification.carryover?.length ?? 0;
+	return (
+		`> **Revisão incremental** — desde \`${shortSha(classification.reviewedFrom)}\`; ` +
+		`${Object.keys(classification.files).length} arquivo(s) alterado(s), ` +
+		`${carried} finding(s) carregado(s) do review anterior.\n\n`
+	);
+}
+
+/**
+ * Findings do review anterior em arquivos inalterados — carregados sem
+ * re-revisão (carry-over). Preserva o `foundAtSha` para o diff focado do verify.
+ */
+function buildCarryover(
+	previous: FindingsStateFile | null,
+	changedPaths: Set<string>,
+): MergedFinding[] {
+	if (!previous) return [];
+	return Object.values(previous.findings)
+		.filter((finding) => finding.present && !changedPaths.has(finding.file))
+		.map((finding) => ({
+			id: finding.id,
+			rule: finding.rule,
+			severity: finding.severity,
+			file: finding.file,
+			line: finding.line ?? undefined,
+			message: finding.message,
+			action: finding.action,
+			evidence: finding.evidence,
+			foundAtSha: finding.foundAtSha,
+			watchdogs: [...finding.watchdogIds],
+		}));
+}
+
+/** Une os findings re-reportados com os carry-over (preserva ids do estado anterior). */
+function mergeCarryover(
+	merged: MergedFinding[],
+	carryover: readonly MergedFinding[],
+): MergedFinding[] {
+	const byKey = new Map(merged.map((finding) => [findingKey(finding), finding]));
+	for (const carried of carryover) {
+		const existing = byKey.get(findingKey(carried));
+		if (existing) {
+			for (const watchdog of carried.watchdogs) {
+				if (!existing.watchdogs.includes(watchdog))
+					existing.watchdogs.push(watchdog);
+			}
+			continue;
+		}
+		byKey.set(findingKey(carried), carried);
+		merged.push(carried);
+	}
+	merged.sort((a, b) => {
+		const bySeverity = severityRank(a.severity) - severityRank(b.severity);
+		if (bySeverity !== 0) return bySeverity;
+		if (a.file !== b.file) return a.file.localeCompare(b.file);
+		return (a.line ?? 0) - (b.line ?? 0);
+	});
+	return merged;
+}
+
+/**
+ * Decide entre review completo e incremental. Incremental só quando há um
+ * `reviewed.headSha` anterior, o `HEAD` atual o sucede (sem rebase) e não veio
+ * `--full`/`--clean`. Reconstrói só o delta `prevSha..headSha` e carrega os
+ * findings de arquivos inalterados do estado anterior.
+ */
+function resolveReviewScope(
+	opts: ReviewOptions,
+	previous: FindingsStateFile | null,
+	headSha: string,
+	config: HoundsmanConfig,
+): { classification: RunClassification; diff: DiffSource; reviewedFrom?: string } {
+	const prevSha = previous?.reviewed?.headSha;
+	if (
+		opts.full ||
+		opts.clean ||
+		!prevSha ||
+		prevSha === headSha ||
+		!isAncestor(prevSha, headSha)
+	) {
+		const diff = collectDiff(opts.base, opts.head);
+		return {
+			diff,
+			classification: {
+				...classifyRange(opts.base, opts.head, config, diff),
+				headSha,
+				mode: "full",
+			},
+		};
+	}
+
+	const range = `${prevSha}..${headSha}`;
+	const diff = collectDiffSince(prevSha, headSha);
+	const entries = diffEntries(range);
+	const changedPaths = new Set(entries.map((entry) => entry.path));
+	const classification: RunClassification = {
+		...classifyEntries(entries, config, churnToRecord(diff.churn)),
+		base: prevSha,
+		head: opts.head,
+		headSha,
+		mode: "incremental",
+		reviewedFrom: prevSha,
+		carryover: buildCarryover(previous, changedPaths),
+	};
+	return { classification, diff, reviewedFrom: prevSha };
+}
+
 // ---------------------------------------------------------------------------
 // Findings
 // ---------------------------------------------------------------------------
@@ -144,27 +305,47 @@ function writeManifest(
 	outDir: string,
 	opts: ReviewOptions,
 	branch: string,
-	classification: ClassificationResult,
+	classification: RunClassification,
 	activeIds: string[],
 	pending: string[],
 	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),
 		base: opts.base,
 		head: opts.head,
+		headSha: classification.headSha,
 		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),
+		incremental:
+			classification.mode === "incremental"
+				? {
+						from: classification.reviewedFrom,
+						changedFiles: Object.keys(classification.files).length,
+						carried: classification.carryover?.length ?? 0,
+					}
+				: undefined,
+		watchdogs,
 		context: contextManifest(opts, branch),
 		jev: jev.available
 			? {
@@ -186,6 +367,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 +412,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 +448,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 +473,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 +520,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,23 +545,40 @@ export async function prepare(
 ): Promise<void> {
 	prepareDirs(dirs, opts.clean);
 
-	const classification = classifyRange(opts.base, opts.head, config);
+	// Marca o run como "revisando" (reinicia o ciclo) — a UI mostra o status.
+	writeRunStatus(dirs.outDir, { branch, status: "reviewing", resetStartedAt: true });
+
+	// Marca o commit revisado e decide entre review completo e incremental.
+	const headSha = resolveSha(opts.head);
+	const previous = FindingsStateStore.at(opts.dir, branch).read();
+	const { classification, diff } = resolveReviewScope(opts, previous, headSha, config);
 	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) {
-		console.log(`Nenhuma alteração entre ${opts.base}...${opts.head}.`);
+		writeRunStatus(dirs.outDir, { branch, status: "review_done" });
+		console.log(
+			classification.mode === "incremental"
+				? `Nenhuma alteração desde a última revisão (${shortSha(classification.reviewedFrom ?? "")}).`
+				: `Nenhuma alteração entre ${opts.base}...${opts.head}.`,
+		);
 		return;
 	}
 	if (activeIds.length === 0) {
+		writeRunStatus(dirs.outDir, { branch, status: "review_done" });
 		console.log("Nenhum arquivo revisável (tudo excluído, deletado ou irrelevante).");
 		return;
 	}
+	if (classification.mode === "incremental") {
+		console.log(
+			`Modo incremental: ${Object.keys(classification.files).length} arquivo(s) alterado(s) desde ${shortSha(classification.reviewedFrom ?? "")}; ${classification.carryover?.length ?? 0} finding(s) carregado(s) do review anterior.`,
+		);
+	}
 
 	const context = readContextSummary(contextPaths(opts.dir, branch).summary);
 
@@ -342,6 +594,7 @@ export async function prepare(
 		config,
 	);
 	printDiscovery(activeIds, classification, dirs.briefsDir);
+	printBudget(classification, config);
 	printJevSummary(jev);
 
 	if (context) {
@@ -363,13 +616,57 @@ export async function prepare(
 // ---------------------------------------------------------------------------
 
 /** Lê o classification.json gravado pelo passo de preparação (lança se ausente). */
-function readClassification(classificationPath: string): ClassificationResult {
+function readClassification(classificationPath: string): RunClassification {
 	if (!existsSync(classificationPath)) {
 		throw new Error(
 			`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 RunClassification;
+	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 = {
@@ -415,8 +712,49 @@ export function finalize(
 		);
 	}
 
-	const merged = dedupeFindings(reports);
+	const now = new Date().toISOString();
+	// Findings re-reportados neste ciclo + carry-over (arquivos inalterados).
+	const merged = mergeCarryover(
+		dedupeFindings(reports),
+		classification.carryover ?? [],
+	);
+	if (classification.mode === "incremental") {
+		console.log(
+			`Carry-over: ${classification.carryover?.length ?? 0} finding(s) preservado(s) de ${shortSha(classification.reviewedFrom ?? "")}.`,
+		);
+	}
+
+	// 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. O commit revisado
+	// (`reviewed.headSha`) habilita o review incremental e o diff focado do verify.
+	const store = FindingsStateStore.at(opts.dir, branch);
+	const state = buildStateFromFindings(merged, {
+		branch,
+		readFile: fileReader(process.cwd()),
+		previous: store.read(),
+		now,
+		headSha: classification.headSha,
+		reviewed: classification.headSha
+			? { headSha: classification.headSha, at: now }
+			: undefined,
+	});
+	store.write(state);
+	console.log(
+		`Triagem: ${relFromRoot(store.filePath)} — ${Object.keys(state.findings).length} finding(s).`,
+	);
+	writeRunStatus(dirs.outDir, { branch, status: "review_done" });
+
 	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,10 +762,11 @@ 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`);
+	writeFileSync(reportPath, `${incrementalNote(classification)}${markdown}\n`);
 
 	const blockers = merged.filter((f) => f.severity === "blocking").length;
 	const attention = merged.filter((f) => f.severity === "attention").length;

package/src/core/paths.ts

@@ -28,3 +28,12 @@ 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";
+
+/** Status da run (revisão/correção), dentro da pasta da run (`<slug>/run.json`). */
+export const RUN_STATUS_FILE = "run.json";
+
+/** Relatório da verificação de findings, dentro da pasta da run (`<slug>/verify.md`). */
+export const VERIFY_FILE = "verify.md";

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 };