@payconductor/houndsman 0.1.0 → 0.1.3

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;
@@ -23,6 +25,11 @@ export type Finding = {
 	message: string;
 	action: string;
 	evidence?: string;
+	/**
+	 * Commit em que o achado foi observado (interno). Preenchido nos carry-over
+	 * do review incremental — preserva a referência para a verificação (verify).
+	 */
+	foundAtSha?: string;
 };
 
 export type WatchdogReport = {
@@ -206,8 +213,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 +292,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 +427,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 +448,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 +458,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/run-status.ts

@@ -0,0 +1,123 @@
+/**
+ * Status do run (biblioteca) — persistido em `.houndsman/.runs/<slug>/run.json`.
+ *
+ * Diz à UI em que pé está uma run: `reviewing` (revisando) → `review_done`
+ * (revisão finalizada) → `fixing` (corrigindo) → `fix_done` (correção finalizada).
+ *
+ * Toda ação que muda o estado faz um **ping** no `updatedAt`, mantendo o arquivo
+ * "quente". Timeout é **display-only** (a UI compara `updatedAt` com o agora) —
+ * não é um status persistido.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type { FindingsStateFile } from "./findings-state";
+import { RUN_STATUS_FILE } from "./paths";
+import { sanitizeBranch } from "./report-builder";
+
+/** Estados de execução de uma run (persistidos). */
+export type RunStatus = "reviewing" | "review_done" | "fixing" | "fix_done";
+
+/** Valores canônicos de status (ordem de exibição/lifecycle). */
+export const RUN_STATUSES: readonly RunStatus[] = [
+	"reviewing",
+	"review_done",
+	"fixing",
+	"fix_done",
+];
+
+export const RUN_STATUS_VERSION = 1;
+
+/** Conteúdo do `run.json`. */
+export type RunStatusFile = {
+	version: 1;
+	slug: string;
+	branch: string;
+	status: RunStatus;
+	/** Início do ciclo de revisão atual (reiniciado a cada `prepare`). */
+	startedAt: string;
+	/** Última ação importante (ping). */
+	updatedAt: string;
+};
+
+/** Caminho do `run.json` dentro da pasta da run. */
+export function runStatusPath(runDir: string): string {
+	return join(runDir, RUN_STATUS_FILE);
+}
+
+/** Lê o `run.json` da run (null se ausente/inválido). */
+export function readRunStatus(runDir: string): RunStatusFile | null {
+	const path = runStatusPath(runDir);
+	if (!existsSync(path)) return null;
+	try {
+		return JSON.parse(readFileSync(path, "utf8")) as RunStatusFile;
+	} catch {
+		return null;
+	}
+}
+
+export type WriteRunStatusOptions = {
+	branch: string;
+	status: RunStatus;
+	/** Reinicia o `startedAt` — usado no início de uma nova revisão. */
+	resetStartedAt?: boolean;
+	now?: string;
+};
+
+/** Grava/atualiza o `run.json` (ping no `updatedAt`). */
+export function writeRunStatus(
+	runDir: string,
+	options: WriteRunStatusOptions,
+): RunStatusFile {
+	const now = options.now ?? new Date().toISOString();
+	const previous = readRunStatus(runDir);
+	const file: RunStatusFile = {
+		version: RUN_STATUS_VERSION,
+		slug: sanitizeBranch(options.branch),
+		branch: options.branch,
+		status: options.status,
+		startedAt: options.resetStartedAt ? now : (previous?.startedAt ?? now),
+		updatedAt: now,
+	};
+	mkdirSync(runDir, { recursive: true });
+	writeFileSync(runStatusPath(runDir), `${JSON.stringify(file, null, 2)}\n`);
+	return file;
+}
+
+/**
+ * Deriva o status após uma mudança nos findings (triagem/correção).
+ * `fixing` exige correção em andamento (`in_progress`) ou retomada de um fix;
+ * `fix_done` quando o fix começou e a fila (`execute` não `done`) esvaziou.
+ */
+export function statusAfterFindingsChange(
+	previous: RunStatus | null,
+	state: FindingsStateFile,
+): RunStatus {
+	const findings = Object.values(state.findings);
+	const active = findings.filter((finding) => finding.present);
+
+	if (active.some((finding) => finding.execState === "in_progress")) return "fixing";
+
+	const queueRemaining = active.some(
+		(finding) => finding.decision === "execute" && finding.execState !== "done",
+	);
+	const anyDone = active.some(
+		(finding) => finding.decision === "execute" && finding.execState === "done",
+	);
+	const fixStarted = previous === "fixing" || previous === "fix_done" || anyDone;
+	if (fixStarted) return queueRemaining ? "fixing" : "fix_done";
+
+	return previous ?? "review_done";
+}
+
+/** Ping: deriva o status da mudança nos findings e grava o `run.json`. */
+export function pingFindingsStatus(
+	runDir: string,
+	state: FindingsStateFile,
+): RunStatusFile {
+	const previous = readRunStatus(runDir)?.status ?? null;
+	return writeRunStatus(runDir, {
+		branch: state.branch,
+		status: statusAfterFindingsChange(previous, state),
+	});
+}

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;

package/src/core/verify.ts

@@ -0,0 +1,175 @@
+/**
+ * Verificação de findings (biblioteca) — "as violações foram resolvidas?".
+ *
+ * Checagem barata, **sem re-revisar a PR**:
+ *  - Tier 0 (local, grátis): reancora a âncora de conteúdo contra o working tree.
+ *  - Tier 1 (Jev, opcional): confirma/refuta os casos ambíguos (âncora sumida ou
+ *    inexistente) via LLM, sobre um diff focado do arquivo (`jev-verify.ts`).
+ *
+ * `verifyLocal` é puro (recebe o leitor de arquivos); o comando renderiza e, com
+ * `--apply`, persiste `resolved` → `execState: done`.
+ */
+
+import { reanchor } from "./finding-anchor";
+import {
+	applyFindingUpdate,
+	type FileReader,
+	type FindingState,
+	type FindingsFilter,
+	type FindingsStateFile,
+	filterFindings,
+} from "./findings-state";
+import type { Severity } from "./types";
+
+/** Resultado da verificação de um finding. */
+export type VerifyStatus = "resolved" | "persisting" | "uncertain" | "file-missing";
+
+/** Mecanismo que decidiu o status (reancoragem local ou LLM). */
+export type VerifyBasis = "anchor" | "jev";
+
+/** Valores canônicos de status (ordem de exibição). */
+export const VERIFY_STATUSES: readonly VerifyStatus[] = [
+	"resolved",
+	"persisting",
+	"uncertain",
+	"file-missing",
+];
+
+/** Um finding verificado. */
+export type VerifyEntry = {
+	id: string;
+	file: string;
+	rule: string;
+	severity: Severity;
+	message: string;
+	line: number | null;
+	status: VerifyStatus;
+	basis: VerifyBasis;
+	/** Confiança do Jev (0–1) quando `basis: "jev"`. */
+	confidence?: number;
+	detail?: string;
+	/** Ambíguo no tier local — candidato à confirmação do Jev. */
+	ambiguous: boolean;
+};
+
+/** Fila de verificação: presentes, excluindo `ignore` (descartados pelo usuário). */
+export function selectVerifiable(
+	state: FindingsStateFile,
+	filter: FindingsFilter = {},
+): FindingState[] {
+	return filterFindings(state, filter).filter(
+		(finding) => finding.decision !== "ignore",
+	);
+}
+
+/**
+ * Tier 0 — checagem local por conteúdo. Marca `ambiguous: true` quando a âncora
+ * sumiu (corrigida ou trecho reescrito) ou não existe; nesses casos o Jev pode
+ * confirmar. Âncora presente (`ok`/`moved`) ⇒ `persisting`, definitivo.
+ */
+export function verifyLocal(
+	findings: readonly FindingState[],
+	readFile: FileReader,
+): VerifyEntry[] {
+	return findings.map((finding) => {
+		const base = {
+			id: finding.id,
+			file: finding.file,
+			rule: finding.rule,
+			severity: finding.severity,
+			message: finding.message,
+			line: finding.line,
+		};
+		const content = readFile(finding.file);
+		if (content === null) {
+			return {
+				...base,
+				status: "file-missing" as const,
+				basis: "anchor" as const,
+				ambiguous: false,
+				detail: "arquivo ausente no working tree",
+			};
+		}
+		if (!finding.anchor) {
+			return {
+				...base,
+				status: "uncertain" as const,
+				basis: "anchor" as const,
+				ambiguous: true,
+				detail: "finding sem âncora de conteúdo",
+			};
+		}
+		const { status } = reanchor(content, finding.anchor, finding.line);
+		if (status === "stale") {
+			return {
+				...base,
+				status: "resolved" as const,
+				basis: "anchor" as const,
+				ambiguous: true,
+				detail: "âncora ausente (trecho corrigido?)",
+			};
+		}
+		return {
+			...base,
+			status: "persisting" as const,
+			basis: "anchor" as const,
+			ambiguous: false,
+			detail: status === "moved" ? "âncora deslocada" : undefined,
+		};
+	});
+}
+
+/**
+ * Tier 1 — aplica a confirmação do Jev aos casos ambíguos.
+ * `confidence[id] >= threshold` ⇒ a violação persiste; abaixo ⇒ resolvida.
+ * Ids sem resposta mantêm o provisório local (fail-open). Devolve o nº aplicado.
+ */
+export function applyJev(
+	entries: VerifyEntry[],
+	confidence: Map<string, number>,
+	threshold: number,
+): number {
+	let applied = 0;
+	for (const entry of entries) {
+		if (!entry.ambiguous) continue;
+		const value = confidence.get(entry.id);
+		if (value === undefined) continue;
+		entry.basis = "jev";
+		entry.confidence = value;
+		entry.status = value >= threshold ? "persisting" : "resolved";
+		applied++;
+	}
+	return applied;
+}
+
+export type VerifySummary = Record<VerifyStatus, number>;
+
+/** Contagem por status. */
+export function summarizeVerify(entries: readonly VerifyEntry[]): VerifySummary {
+	const summary = Object.fromEntries(
+		VERIFY_STATUSES.map((status) => [status, 0]),
+	) as VerifySummary;
+	for (const entry of entries) summary[entry.status]++;
+	return summary;
+}
+
+/**
+ * Persiste os `resolved` como `done` (acao `verify`). Devolve os ids alterados.
+ * Muta o estado em memória (o caller persiste).
+ */
+export function applyResolutions(
+	state: FindingsStateFile,
+	entries: readonly VerifyEntry[],
+	now: string = new Date().toISOString(),
+): string[] {
+	const changed: string[] = [];
+	for (const entry of entries) {
+		if (entry.status !== "resolved") continue;
+		const finding = state.findings[entry.id];
+		if (!finding || finding.execState === "done") continue;
+		applyFindingUpdate(finding, { execState: "done", by: "verify" }, now);
+		changed.push(finding.id);
+	}
+	if (changed.length > 0) state.updatedAt = now;
+	return changed;
+}

package/src/core/watchdog-registry.ts

@@ -1,8 +1,7 @@
 /**
  * Acesso tipado aos watchdogs de um `HoundsmanConfig` (biblioteca).
  *
- * Substitui o antigo barrel `registry/`. O motor não conhece ids concretos —
- * tudo chega via `config`.
+ * O motor não conhece ids concretos — tudo chega via `config`.
  */
 
 import type { HoundsmanConfig } from "./config";

package/src/index.ts

@@ -7,8 +7,22 @@
 
 export { assetPath, OUTPUT_FORMAT_FILE } from "./core/assets";
 export { defaultRenderBrief, PROCEDURE, renderBrief } from "./core/brief";
-export type { HoundsmanConfig, HoundsmanConfigInput } from "./core/config";
-export { DEFAULT_ALWAYS_INCLUDE_DOCS, defineHoundsmanConfig } from "./core/config";
+export type { FindingsCommandResult } from "./core/commands/findings";
+export { runFindingsCommand, runVerifyCommand } from "./core/commands/findings";
+export type {
+	HoundsmanBudgets,
+	HoundsmanConcurrency,
+	HoundsmanConfig,
+	HoundsmanConfigInput,
+} from "./core/config";
+export {
+	DEFAULT_ALWAYS_INCLUDE_DOCS,
+	DEFAULT_JEV_CONCURRENCY,
+	DEFAULT_MAX_FILES_PER_BRIEF,
+	defineHoundsmanConfig,
+	resolveJevConcurrency,
+	resolveMaxFilesPerBrief,
+} from "./core/config";
 export type { LoadedConfig } from "./core/config-loader";
 export {
 	CONFIG_FILE_CANDIDATES,
@@ -16,12 +30,67 @@ export {
 	resolveConfigPath,
 } from "./core/config-loader";
 export {
+	collectChurn,
+	collectDiff,
+	type DiffSource,
+	parseDiffIndex,
+	parseNumstat,
+} from "./core/diff-source";
+export {
+	churnOf,
 	classifyEntries,
 	classifyRange,
 	isExcludedPath,
 	matchWatchdogs,
 	parseEntries,
+	selectByBudget,
+	sortByRisk,
 } from "./core/file-classifier";
+export type {
+	AnchorLocation,
+	FindingAnchor,
+	ReanchorStatus,
+} from "./core/finding-anchor";
+export {
+	buildAnchor,
+	fingerprintOf,
+	hashKey,
+	locateAnchor,
+	normalizeLine,
+	reanchor,
+} from "./core/finding-anchor";
+export type {
+	BuildStateOptions,
+	FileReader,
+	FindingDecision,
+	FindingExecState,
+	FindingHistoryEntry,
+	FindingState,
+	FindingsFilter,
+	FindingsStateFile,
+	FindingsSummary,
+	FindingUpdate,
+	SyncResult,
+} from "./core/findings-state";
+export {
+	applyFindingUpdate,
+	buildStateFromFindings,
+	buildStateFromRunDir,
+	compareFindings,
+	emptyState,
+	FINDING_DECISIONS,
+	FINDING_EXEC_STATES,
+	FINDINGS_STATE_VERSION,
+	FindingsStateStore,
+	fileReader,
+	filterFindings,
+	newFindingId,
+	reorder,
+	runDir,
+	stateFile,
+	summarize,
+	syncState,
+} from "./core/findings-state";
 export {
 	ARTIFACT_DIR,
 	CORE_DIR,
@@ -29,10 +98,15 @@ export {
 	OUTPUT_FORMAT_PATH,
 	PROJECT_DIR,
 	relFromRoot,
+	STATE_FILE,
 } from "./core/paths";
 export { checkRegistry } from "./core/registry-check";
+export type { DomainReport } from "./core/report-builder";
+export { renderDomainReport } from "./core/report-builder";
 export type {
+	ChurnMap,
 	ClassifyRule,
+	FileChurn,
 	FileStatus,
 	FileStatusMap,
 	Rule,
@@ -54,3 +128,5 @@ export {
 	getWatchdog,
 	getWatchdogContext,
 } from "./core/watchdog-registry";
+export type { ServerOptions } from "./server";
+export { createRequestHandler, startServer } from "./server";

package/src/server/artifacts.ts

@@ -0,0 +1,67 @@
+/**
+ * Descoberta de runs e leitura segura de artefatos (servidor).
+ *
+ * Toda leitura é restrita à pasta da run — `readRunFile` barra path traversal.
+ */
+
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { isAbsolute, join, relative, resolve } from "node:path";
+
+/** Arquivos que marcam uma pasta como "run" do houndsman. */
+const RUN_MARKERS = [
+	"manifest.json",
+	"state.json",
+	"run.json",
+	"classification.json",
+	"review.md",
+] as const;
+
+/** Slugs (nomes de pasta) das runs sob o `artifactDir`. */
+export function listRunSlugs(artifactDir: string): string[] {
+	if (!existsSync(artifactDir)) return [];
+	try {
+		return readdirSync(artifactDir, { withFileTypes: true })
+			.filter((entry) => entry.isDirectory())
+			.map((entry) => entry.name)
+			.filter((slug) =>
+				RUN_MARKERS.some((marker) => existsSync(join(artifactDir, slug, marker))),
+			)
+			.sort();
+	} catch {
+		return [];
+	}
+}
+
+/** Diretório absoluto de uma run; null se o slug for inválido/inexistente. */
+export function runDirForSlug(artifactDir: string, slug: string): string | null {
+	if (!/^[a-zA-Z0-9._-]+$/.test(slug)) return null;
+	const dir = join(artifactDir, slug);
+	if (!existsSync(dir) || !statSync(dir).isDirectory()) return null;
+	return dir;
+}
+
+/** Lê um arquivo DENTRO da run; null se ausente ou fora do diretório. */
+export function readRunFile(runDir: string, name: string): string | null {
+	const root = resolve(runDir);
+	const target = resolve(root, name);
+	const rel = relative(root, target);
+	if (rel === "" || rel.startsWith("..") || isAbsolute(rel)) return null;
+	try {
+		return existsSync(target) && statSync(target).isFile()
+			? readFileSync(target, "utf8")
+			: null;
+	} catch {
+		return null;
+	}
+}
+
+/** Lê e faz parse de um JSON da run (null se ausente/inválido). */
+export function readRunJson<T>(runDir: string, name: string): T | null {
+	const raw = readRunFile(runDir, name);
+	if (raw === null) return null;
+	try {
+		return JSON.parse(raw) as T;
+	} catch {
+		return null;
+	}
+}