@payconductor/houndsman 0.3.0 → 0.4.0

package/src/core/engine/houndsman-engine.ts

@@ -13,6 +13,9 @@ import { FileClassifier } from "../services/file-classifier";
 import { FixBatchBuilder } from "../services/fix-batch-builder";
 import { GitRepository } from "../services/git-repository";
 import { Verifier } from "../services/verifier";
+import { createStorage } from "../storage/factory";
+import { resolveRepoIdentity } from "../storage/repo-identity";
+import type { RepoIdentity, StorageProvider } from "../storage/types";
 import { ReviewSession } from "./review-session";
 
 /** Colaboradores injetáveis (testes/CLI). */
@@ -21,6 +24,8 @@ export type EngineDeps = {
 	classifier?: FileClassifier;
 	verifier?: Verifier;
 	fixBatch?: FixBatchBuilder;
+	storage?: StorageProvider;
+	repo?: RepoIdentity;
 };
 
 /** Composition root do motor. */
@@ -30,6 +35,8 @@ export class HoundsmanEngine {
 	readonly classifier: FileClassifier;
 	readonly verifier: Verifier;
 	readonly fixBatch: FixBatchBuilder;
+	readonly storage: StorageProvider;
+	readonly repo: RepoIdentity;
 
 	constructor(raw: HoundsmanConfig, deps: EngineDeps = {}) {
 		this.project = new ProjectConfig(raw);
@@ -37,6 +44,8 @@ export class HoundsmanEngine {
 		this.classifier = deps.classifier ?? new FileClassifier(raw);
 		this.verifier = deps.verifier ?? new Verifier();
 		this.fixBatch = deps.fixBatch ?? new FixBatchBuilder();
+		this.storage = deps.storage ?? createStorage(raw);
+		this.repo = deps.repo ?? resolveRepoIdentity(this.git);
 	}
 
 	/** Configuração crua (contrato do consumidor). */
@@ -46,6 +55,11 @@ export class HoundsmanEngine {
 
 	/** Abre uma sessão de revisão (prepare/finalize). */
 	session(options: ReviewOptions): ReviewSession {
-		return ReviewSession.from(this.config, options);
+		return ReviewSession.from(this.config, options, this.storage, this.repo);
+	}
+
+	/** Libera o provider (fecha o SQLite e faz checkpoint do WAL). */
+	close(): void {
+		this.storage.close();
 	}
 }

package/src/core/engine/review-session.ts

@@ -1,5 +1,5 @@
 /**
- * Sessão de uma run (engine) — amarra opções, branch e layout.
+ * Sessão de uma run (engine) — amarra opções, branch, storage e staging.
  *
  * É o ponto de entrada do `prepare`/`finalize` para o CLI e para o engine.
  */
@@ -10,38 +10,66 @@ import {
 	finalize,
 	type PrepareResult,
 	prepare,
+	type ReviewContext,
 	type ReviewOptions,
 	resolveBranch,
+	reviewContext,
 } from "../orchestrator";
-import { RunLayout } from "../run-layout";
+import { sanitizeBranch } from "../report-builder";
+import type { RepoIdentity, StorageProvider } from "../storage/types";
 
 /** Uma revisão em andamento (prepare ou finalize). */
 export class ReviewSession {
 	readonly config: HoundsmanConfig;
 	readonly options: ReviewOptions;
 	readonly branch: string;
-	readonly layout: RunLayout;
+	readonly context: ReviewContext;
 
-	constructor(config: HoundsmanConfig, options: ReviewOptions, branch: string) {
+	constructor(
+		config: HoundsmanConfig,
+		options: ReviewOptions,
+		branch: string,
+		storage: StorageProvider,
+		repo: RepoIdentity,
+	) {
 		this.config = config;
 		this.options = options;
 		this.branch = branch;
-		this.layout = new RunLayout(options.dir, branch);
+		const review = options.finalize
+			? storage.findReview(repo.key, branch)
+			: storage.getOrCreateReview({
+					repo,
+					branch,
+					slug: sanitizeBranch(branch),
+					base: options.base,
+					head: options.head,
+				});
+		if (!review) {
+			throw new Error(
+				`Nenhuma revisão para '${branch}'. Rode \`houndsman\` (preparar) primeiro.`,
+			);
+		}
+		this.context = reviewContext(storage, review);
 	}
 
 	/** Resolve a branch (opção explícita ou a atual do git). */
-	static from(config: HoundsmanConfig, options: ReviewOptions): ReviewSession {
-		return new ReviewSession(config, options, resolveBranch(options));
+	static from(
+		config: HoundsmanConfig,
+		options: ReviewOptions,
+		storage: StorageProvider,
+		repo: RepoIdentity,
+	): ReviewSession {
+		return new ReviewSession(config, options, resolveBranch(options), storage, repo);
 	}
 
 	/** Passo 1 — preparar. */
 	prepare(): Promise<PrepareResult> {
-		return prepare(this.options, this.branch, this.config, this.layout);
+		return prepare(this.options, this.branch, this.config, this.context);
 	}
 
 	/** Passo 3 — finalizar. */
 	finalize(): FinalizeResult {
-		return finalize(this.options, this.branch, this.config, this.layout);
+		return finalize(this.options, this.branch, this.config, this.context);
 	}
 
 	/** Executa o passo escolhido em `--finalize`. */

package/src/core/findings-state.ts

@@ -1,18 +1,16 @@
 /**
  * Estado de triagem dos findings (biblioteca).
  *
- * Persistido em `.houndsman/.runs/<slug>/state.json` (local — coberto pelo
- * `.gitignore` gerado, que ignora `.runs/`). Cada finding tem um `id` curto e um
- * `fingerprint` de conteúdo: nas re-execuções do `--finalize` o estado é
- * preservado casando por fingerprint.
+ * O dump (`state.json`) é um detalhe do provider de arquivos; no SQLite o
+ * estado é reconstruído de `findings` + `finding_history`. Cada finding tem um
+ * `id` curto e um `fingerprint` de conteúdo: nas re-execuções do `--finalize`
+ * o estado é preservado casando por fingerprint.
  *
  * A `line` é cache — `syncState` a recalcula após edições (auto-fix) e marca
  * `stale` quando a âncora some.
  */
 
 import { randomUUID } from "node:crypto";
-import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
 import {
 	buildAnchor,
 	type FindingAnchor,
@@ -20,14 +18,7 @@ import {
 	locateAnchor,
 	reanchor,
 } from "./finding-anchor";
-import {
-	dedupeFindings,
-	type MergedFinding,
-	parseWatchdogReport,
-	sanitizeBranch,
-	type WatchdogReport,
-} from "./report-builder";
-import { RunLayout } from "./run-layout";
+import { type MergedFinding, sanitizeBranch } from "./report-builder";
 import { systemClock } from "./services/clock";
 import { type FileReader, ProjectFiles } from "./services/project-files";
 import { SEVERITY_ORDER, type Severity, severityRank } from "./types";
@@ -142,16 +133,6 @@ export const FINDINGS_STATE_VERSION = 2;
 // Caminhos
 // ---------------------------------------------------------------------------
 
-/** Diretório de artefatos da run (branch-slug). */
-export function runDir(artifactDir: string, branch: string): string {
-	return new RunLayout(artifactDir, branch).outDir;
-}
-
-/** Caminho do `state.json` da run. */
-export function stateFile(artifactDir: string, branch: string): string {
-	return new RunLayout(artifactDir, branch).stateFile;
-}
-
 /** Leitor padrão a partir do cwd (null se ausente/ilegível). */
 export function fileReader(cwd: string): FileReader {
 	return new ProjectFiles(cwd).reader();
@@ -264,6 +245,32 @@ export function filterFindings(
 		.sort(compareFindings);
 }
 
+/** Resultado da resolução de um id (completo ou prefixo único). */
+export type FindingIdResolution =
+	| { status: "found"; id: string }
+	| { status: "ambiguous"; matches: string[] }
+	| { status: "missing" };
+
+/**
+ * Resolve um id de finding: exato primeiro, depois prefixo único.
+ * Ambíguo devolve os candidatos para a mensagem de erro.
+ */
+export function resolveFindingId(
+	state: FindingsStateFile,
+	input: string,
+): FindingIdResolution {
+	const needle = input.trim();
+	if (needle.length === 0) return { status: "missing" };
+	if (state.findings[needle]) return { status: "found", id: needle };
+
+	const matches = Object.keys(state.findings).filter((id) =>
+		id.toLowerCase().startsWith(needle.toLowerCase()),
+	);
+	if (matches.length === 1) return { status: "found", id: matches[0] };
+	if (matches.length > 1) return { status: "ambiguous", matches };
+	return { status: "missing" };
+}
+
 // ---------------------------------------------------------------------------
 // Construção (finalize)
 // ---------------------------------------------------------------------------
@@ -377,47 +384,6 @@ export function buildStateFromFindings(
 	return state;
 }
 
-/**
- * Reconstrói o estado a partir dos artefatos da run (`classification.json` +
- * `findings/<id>.json`), sem exigir `--finalize`. Devolve null se não houver
- * findings gravados.
- */
-export function buildStateFromRunDir(
-	outDir: string,
-	branch: string,
-	readFile: FileReader,
-): FindingsStateFile | null {
-	const classificationPath = join(outDir, "classification.json");
-	if (!existsSync(classificationPath)) return null;
-
-	let activeIds: string[] = [];
-	try {
-		const classification = JSON.parse(readFileSync(classificationPath, "utf8")) as {
-			watchdogs?: Record<string, string[]>;
-		};
-		activeIds = Object.keys(classification.watchdogs ?? {});
-	} catch {
-		return null;
-	}
-
-	const reports: WatchdogReport[] = [];
-	for (const id of activeIds) {
-		const path = join(outDir, "findings", `${id}.json`);
-		if (!existsSync(path)) continue;
-		try {
-			const report = parseWatchdogReport(
-				JSON.parse(readFileSync(path, "utf8")),
-				path,
-			);
-			if (report) reports.push(report);
-		} catch {
-			// Ignora findings ilegíveis — reconstrução best-effort.
-		}
-	}
-	if (reports.length === 0) return null;
-
-	return buildStateFromFindings(dedupeFindings(reports), { branch, readFile });
-}
 // ---------------------------------------------------------------------------
 
 export type FindingUpdate = {
@@ -574,7 +540,7 @@ export class Finding {
 	}
 }
 
-/** Coleção de triagem de uma run — superfície OO sobre o `state.json`. */
+/** Coleção de triagem de uma run — superfície OO sobre o dump persistido. */
 export class FindingsState {
 	readonly file: FindingsStateFile;
 
@@ -671,11 +637,6 @@ export class FindingsRepository {
 		this.branch = branch;
 	}
 
-	/** Repository para a run de uma branch. */
-	static at(artifactDir: string, branch: string): FindingsRepository {
-		return new FindingsRepository(stateFile(artifactDir, branch), branch);
-	}
-
 	get filePath(): string {
 		return this.path;
 	}

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

@@ -36,6 +36,50 @@ export type JevCandidatesFile = {
 
 const SEVERITY_SET = new Set<string>(SEVERITY_ORDER);
 
+/** Serializa o artefato `candidates.json` (sempre com quebra de linha final). */
+export function serializeCandidates(data: JevCandidatesFile): string {
+	return `${JSON.stringify(data, null, 2)}\n`;
+}
+
+/** Valida/parseia o JSON bruto do artefato; null se inválido. */
+export function parseCandidates(
+	raw: unknown,
+	validIds: readonly string[] = [],
+): JevCandidatesFile | null {
+	if (typeof raw !== "object" || raw === null) return null;
+	const value = raw as Record<string, unknown>;
+	const idSet = validIds.length > 0 ? new Set(validIds) : null;
+	const isCandidate = (entry: unknown): entry is JevCandidate => {
+		if (typeof entry !== "object" || entry === null) return false;
+		const c = entry as Record<string, unknown>;
+		return (
+			typeof c.watchdogId === "string" &&
+			(idSet === null || idSet.has(c.watchdogId)) &&
+			typeof c.rule === "string" &&
+			typeof c.severity === "string" &&
+			SEVERITY_SET.has(c.severity) &&
+			typeof c.file === "string" &&
+			typeof c.confidence === "number" &&
+			typeof c.questionKey === "string"
+		);
+	};
+	const candidates = Array.isArray(value.candidates)
+		? value.candidates.filter(isCandidate)
+		: [];
+	return {
+		available: value.available === true,
+		reason: typeof value.reason === "string" ? value.reason : undefined,
+		model: typeof value.model === "string" ? value.model : undefined,
+		threshold: typeof value.threshold === "number" ? value.threshold : undefined,
+		analyzedFiles:
+			typeof value.analyzedFiles === "number" ? value.analyzedFiles : undefined,
+		candidates,
+		skipped: Array.isArray(value.skipped)
+			? (value.skipped as JevSkippedFile[])
+			: undefined,
+	};
+}
+
 /** Persistência do artefato `candidates.json` para um diretório de review. */
 export class JevCandidatesStore {
 	/** Limiar padrão de confiança (`noul`) para virar candidato. */
@@ -57,49 +101,19 @@ export class JevCandidatesStore {
 
 	/** Grava o `candidates.json` (sempre com candidatos válidos apenas). */
 	write(data: JevCandidatesFile): void {
-		writeFileSync(this.filePath, `${JSON.stringify(data, null, 2)}\n`);
+		writeFileSync(this.filePath, serializeCandidates(data));
 	}
 
 	/** Lê o `candidates.json`; null se ausente/inválido. */
 	read(): JevCandidatesFile | null {
 		if (!existsSync(this.filePath)) return null;
 		try {
-			const raw = JSON.parse(readFileSync(this.filePath, "utf8")) as Record<
-				string,
-				unknown
-			>;
-			const candidates = Array.isArray(raw.candidates)
-				? raw.candidates.filter((c) => this.isCandidate(c))
-				: [];
-			return {
-				available: raw.available === true,
-				reason: typeof raw.reason === "string" ? raw.reason : undefined,
-				model: typeof raw.model === "string" ? raw.model : undefined,
-				threshold: typeof raw.threshold === "number" ? raw.threshold : undefined,
-				analyzedFiles:
-					typeof raw.analyzedFiles === "number" ? raw.analyzedFiles : undefined,
-				candidates,
-				skipped: Array.isArray(raw.skipped)
-					? (raw.skipped as JevSkippedFile[])
-					: undefined,
-			};
+			return parseCandidates(
+				JSON.parse(readFileSync(this.filePath, "utf8")),
+				this.watchdogIdSet ? [...this.watchdogIdSet] : [],
+			);
 		} catch {
 			return null;
 		}
 	}
-
-	private isCandidate(value: unknown): value is JevCandidate {
-		if (typeof value !== "object" || value === null) return false;
-		const c = value as Record<string, unknown>;
-		return (
-			typeof c.watchdogId === "string" &&
-			(this.watchdogIdSet === null || this.watchdogIdSet.has(c.watchdogId)) &&
-			typeof c.rule === "string" &&
-			typeof c.severity === "string" &&
-			SEVERITY_SET.has(c.severity) &&
-			typeof c.file === "string" &&
-			typeof c.confidence === "number" &&
-			typeof c.questionKey === "string"
-		);
-	}
 }