@payconductor/houndsman 0.2.0 → 0.3.0

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

@@ -0,0 +1,51 @@
+/**
+ * Engine do houndsman (composition root).
+ *
+ * Injeta a configuração do projeto e os colaboradores compartilhados (git,
+ * classificador, verifier, lote). Comandos e pipelines pedem ao engine em vez
+ * de instanciar/importar tudo diretamente.
+ */
+
+import type { HoundsmanConfig } from "../config";
+import type { ReviewOptions } from "../orchestrator";
+import { ProjectConfig } from "../project-config";
+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 { ReviewSession } from "./review-session";
+
+/** Colaboradores injetáveis (testes/CLI). */
+export type EngineDeps = {
+	git?: GitRepository;
+	classifier?: FileClassifier;
+	verifier?: Verifier;
+	fixBatch?: FixBatchBuilder;
+};
+
+/** Composition root do motor. */
+export class HoundsmanEngine {
+	readonly project: ProjectConfig;
+	readonly git: GitRepository;
+	readonly classifier: FileClassifier;
+	readonly verifier: Verifier;
+	readonly fixBatch: FixBatchBuilder;
+
+	constructor(raw: HoundsmanConfig, deps: EngineDeps = {}) {
+		this.project = new ProjectConfig(raw);
+		this.git = deps.git ?? new GitRepository();
+		this.classifier = deps.classifier ?? new FileClassifier(raw);
+		this.verifier = deps.verifier ?? new Verifier();
+		this.fixBatch = deps.fixBatch ?? new FixBatchBuilder();
+	}
+
+	/** Configuração crua (contrato do consumidor). */
+	get config(): HoundsmanConfig {
+		return this.project.raw;
+	}
+
+	/** Abre uma sessão de revisão (prepare/finalize). */
+	session(options: ReviewOptions): ReviewSession {
+		return ReviewSession.from(this.config, options);
+	}
+}

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

@@ -0,0 +1,95 @@
+/**
+ * Escopo da revisão (engine) — completo vs incremental.
+ *
+ * Decide se reconstrói o diff inteiro ou só o delta `prevSha..headSha` e
+ * carrega os findings de arquivos inalterados (carry-over).
+ */
+
+import type { HoundsmanConfig } from "../config";
+import { churnToRecord, collectDiff, type DiffSource } from "../diff-source";
+import type { ClassificationResult } from "../file-classifier";
+import type { FindingsStateFile } from "../findings-state";
+import { collectDiffSince, diffEntries, isAncestor } from "../git-revision";
+import type { MergedFinding } from "../report-builder";
+import { FileClassifier } from "../services/file-classifier";
+import { buildCarryover } from "./carryover";
+
+/** Opções que afetam o escopo (subset do `ReviewOptions`). */
+export type ScopeOptions = {
+	base: string;
+	head: string;
+	full: boolean;
+	clean: boolean;
+};
+
+/** Classificação enriquecida gravada no `classification.json`. */
+export type RunClassification = ClassificationResult & {
+	/** Commit revisado (head do diff). */
+	headSha?: string;
+	/** Modo do prepare: completo ou incremental. */
+	mode: "full" | "incremental";
+	/** Commit da última revisão (só no incremental). */
+	reviewedFrom?: string;
+	/** Findings preservados do review anterior (arquivos inalterados). */
+	carryover?: MergedFinding[];
+};
+
+/** Resultado da resolução de escopo. */
+export type ReviewScope = {
+	classification: RunClassification;
+	diff: DiffSource;
+	reviewedFrom?: string;
+};
+
+/** Decide entre review completo e incremental. */
+export class ReviewScopeResolver {
+	private readonly options: ScopeOptions;
+	private readonly classifier: FileClassifier;
+
+	constructor(options: ScopeOptions, config: HoundsmanConfig) {
+		this.options = options;
+		this.classifier = new FileClassifier(config);
+	}
+
+	/**
+	 * Incremental só quando há um `reviewed.headSha` anterior, o `HEAD` atual o
+	 * sucede (sem rebase) e não veio `--full`/`--clean`.
+	 */
+	resolve(previous: FindingsStateFile | null, headSha: string): ReviewScope {
+		const prevSha = previous?.reviewed?.headSha;
+		if (
+			this.options.full ||
+			this.options.clean ||
+			!prevSha ||
+			prevSha === headSha ||
+			!isAncestor(prevSha, headSha)
+		) {
+			const diff = collectDiff(this.options.base, this.options.head);
+			return {
+				diff,
+				classification: {
+					...this.classifier
+						.classifyRange(this.options.base, this.options.head, diff)
+						.toJSON(),
+					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 = {
+			...this.classifier.classify(entries, churnToRecord(diff.churn)).toJSON(),
+			base: prevSha,
+			head: this.options.head,
+			headSha,
+			mode: "incremental",
+			reviewedFrom: prevSha,
+			carryover: buildCarryover(previous, changedPaths),
+		};
+		return { classification, diff, reviewedFrom: prevSha };
+	}
+}

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

@@ -0,0 +1,51 @@
+/**
+ * Sessão de uma run (engine) — amarra opções, branch e layout.
+ *
+ * É o ponto de entrada do `prepare`/`finalize` para o CLI e para o engine.
+ */
+
+import type { HoundsmanConfig } from "../config";
+import {
+	type FinalizeResult,
+	finalize,
+	type PrepareResult,
+	prepare,
+	type ReviewOptions,
+	resolveBranch,
+} from "../orchestrator";
+import { RunLayout } from "../run-layout";
+
+/** Uma revisão em andamento (prepare ou finalize). */
+export class ReviewSession {
+	readonly config: HoundsmanConfig;
+	readonly options: ReviewOptions;
+	readonly branch: string;
+	readonly layout: RunLayout;
+
+	constructor(config: HoundsmanConfig, options: ReviewOptions, branch: string) {
+		this.config = config;
+		this.options = options;
+		this.branch = branch;
+		this.layout = new RunLayout(options.dir, branch);
+	}
+
+	/** 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));
+	}
+
+	/** Passo 1 — preparar. */
+	prepare(): Promise<PrepareResult> {
+		return prepare(this.options, this.branch, this.config, this.layout);
+	}
+
+	/** Passo 3 — finalizar. */
+	finalize(): FinalizeResult {
+		return finalize(this.options, this.branch, this.config, this.layout);
+	}
+
+	/** Executa o passo escolhido em `--finalize`. */
+	run(): Promise<PrepareResult | FinalizeResult> {
+		return this.options.finalize ? Promise.resolve(this.finalize()) : this.prepare();
+	}
+}

package/src/core/file-classifier.ts

@@ -8,7 +8,9 @@
 import { readFileSync } from "node:fs";
 import type { HoundsmanConfig } from "./config";
 import { churnToRecord, collectChurn, type DiffSource } from "./diff-source";
-import type { ChurnMap, ClassifyRule, WatchdogDefinition } from "./types";
+import { matchesClassifyRule } from "./domain/watchdog";
+import { runGit } from "./git-runner";
+import type { ChurnMap, WatchdogDefinition } from "./types";
 
 type FileStatus = "added" | "modified" | "deleted" | "renamed" | "copied" | "unknown";
 
@@ -42,9 +44,6 @@ export type ClassificationResult = {
 // Matchers genéricos (reutilizados pelo projeto)
 // ---------------------------------------------------------------------------
 
-/** Tipo de classificação assumido quando `type` é omitido. */
-const DEFAULT_CLASSIFY_TYPE: NonNullable<ClassifyRule["type"]> = "filename";
-
 /** `true` se há entradas de conteúdo (as únicas que exigem ler o arquivo). */
 function hasContentRules<TId extends string>(
 	watchdogs: Record<TId, WatchdogDefinition>,
@@ -64,18 +63,6 @@ function readFileContent(filePath: string): string | undefined {
 	}
 }
 
-/** `true` se o arquivo casa a entrada de classificação. */
-function matchesClassifyRule(
-	filePath: string,
-	rule: ClassifyRule,
-	content: string | undefined,
-): boolean {
-	if ((rule.type ?? DEFAULT_CLASSIFY_TYPE) === "content") {
-		return content !== undefined && new RegExp(rule.value).test(content);
-	}
-	return new RegExp(rule.value).test(filePath);
-}
-
 /** Watchdogs que declaram o arquivo (união dos `classify`). */
 export function matchWatchdogs<TId extends string>(
 	filePath: string,
@@ -101,22 +88,6 @@ export function isExcludedPath(filePath: string, patterns: readonly RegExp[]): b
 	return patterns.some((pattern) => pattern.test(filePath));
 }
 
-// ---------------------------------------------------------------------------
-// Execução do git diff
-// ---------------------------------------------------------------------------
-
-function runGitDiff(base: string, head: string): string {
-	const result = Bun.spawnSync(["git", "diff", `${base}...${head}`, "--name-status"], {
-		stdout: "pipe",
-		stderr: "pipe",
-	});
-	if (result.exitCode !== 0) {
-		const stderr = new TextDecoder().decode(result.stderr).trim();
-		throw new Error(`git diff falhou (base='${base}', head='${head}'): ${stderr}`);
-	}
-	return new TextDecoder().decode(result.stdout);
-}
-
 // ---------------------------------------------------------------------------
 // Parsing de `git diff --name-status`
 // ---------------------------------------------------------------------------
@@ -248,7 +219,7 @@ export function classifyRange<TId extends string>(
 	config: HoundsmanConfig<TId>,
 	diff?: DiffSource,
 ): ClassificationResult {
-	const entries = parseEntries(runGitDiff(base, head));
+	const entries = parseEntries(runGit(["diff", `${base}...${head}`, "--name-status"]));
 	const churn = diff?.churn ?? collectChurn(base, head);
 	const result = classifyEntries(entries, config, churnToRecord(churn));
 	result.base = base;
@@ -257,39 +228,12 @@ export function classifyRange<TId extends string>(
 }
 
 // ---------------------------------------------------------------------------
-// Triage (PRs grandes)
+// Triage (PRs grandes) — reexportado do domínio
 // ---------------------------------------------------------------------------
 
-/** Churn total (adições + remoções) de um arquivo; 0 quando ausente. */
-export function churnOf(filePath: string, churn: ChurnMap | undefined): number {
-	const entry = churn?.[filePath];
-	return entry ? entry.additions + entry.deletions : 0;
-}
-
-/** Ordena os arquivos por risco (churn desc; empate pelo caminho). */
-export function sortByRisk(files: readonly string[], churn?: ChurnMap): string[] {
-	return [...files].sort((a, b) => {
-		const delta = churnOf(b, churn) - churnOf(a, churn);
-		return delta !== 0 ? delta : a.localeCompare(b);
-	});
-}
-
-/** Resultado da aplicação do orçamento: o que revisar e o que ficou de fora. */
-export type BudgetSelection = { selected: string[]; overflow: string[] };
-
-/**
- * Aplica o orçamento por brief: mantém os `maxFiles` de maior risco e devolve o
- * restante em `overflow` (nunca descarta silenciosamente). `maxFiles` não-positivo
- * ou não-finito desativa o orçamento.
- */
-export function selectByBudget(
-	files: readonly string[],
-	churn: ChurnMap | undefined,
-	maxFiles: number,
-): BudgetSelection {
-	const ordered = sortByRisk(files, churn);
-	if (!Number.isFinite(maxFiles) || maxFiles <= 0 || ordered.length <= maxFiles) {
-		return { selected: ordered, overflow: [] };
-	}
-	return { selected: ordered.slice(0, maxFiles), overflow: ordered.slice(maxFiles) };
-}
+export {
+	type BudgetSelection,
+	churnOf,
+	selectByBudget,
+	sortByRisk,
+} from "./domain/budget";

package/src/core/findings-state.ts

@@ -11,8 +11,8 @@
  */
 
 import { randomUUID } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
 import {
 	buildAnchor,
 	type FindingAnchor,
@@ -20,7 +20,6 @@ import {
 	locateAnchor,
 	reanchor,
 } from "./finding-anchor";
-import { STATE_FILE } from "./paths";
 import {
 	dedupeFindings,
 	type MergedFinding,
@@ -28,8 +27,13 @@ import {
 	sanitizeBranch,
 	type WatchdogReport,
 } from "./report-builder";
+import { RunLayout } from "./run-layout";
+import { systemClock } from "./services/clock";
+import { type FileReader, ProjectFiles } from "./services/project-files";
 import { SEVERITY_ORDER, type Severity, severityRank } from "./types";
 
+export type { FileReader };
+
 // ---------------------------------------------------------------------------
 // Tipos
 // ---------------------------------------------------------------------------
@@ -140,27 +144,17 @@ export const FINDINGS_STATE_VERSION = 2;
 
 /** Diretório de artefatos da run (branch-slug). */
 export function runDir(artifactDir: string, branch: string): string {
-	return join(artifactDir, sanitizeBranch(branch));
+	return new RunLayout(artifactDir, branch).outDir;
 }
 
 /** Caminho do `state.json` da run. */
 export function stateFile(artifactDir: string, branch: string): string {
-	return join(runDir(artifactDir, branch), STATE_FILE);
+	return new RunLayout(artifactDir, branch).stateFile;
 }
 
-/** Leitor de arquivos relativos à raiz do projeto (injetável nos testes). */
-export type FileReader = (relativePath: string) => string | null;
-
 /** Leitor padrão a partir do cwd (null se ausente/ilegível). */
 export function fileReader(cwd: string): FileReader {
-	return (relativePath: string) => {
-		try {
-			const full = join(cwd, relativePath);
-			return existsSync(full) ? readFileSync(full, "utf8") : null;
-		} catch {
-			return null;
-		}
-	};
+	return new ProjectFiles(cwd).reader();
 }
 
 /** Id curto aleatório (hex) para um finding novo. */
@@ -174,7 +168,7 @@ export function emptyState(branch: string): FindingsStateFile {
 		version: FINDINGS_STATE_VERSION,
 		branch,
 		slug: sanitizeBranch(branch),
-		updatedAt: new Date().toISOString(),
+		updatedAt: systemClock(),
 		order: [],
 		findings: {},
 	};
@@ -297,7 +291,7 @@ export function buildStateFromFindings(
 	merged: readonly MergedFinding[],
 	options: BuildStateOptions,
 ): FindingsStateFile {
-	const now = options.now ?? new Date().toISOString();
+	const now = options.now ?? systemClock();
 	const previous = options.previous ?? null;
 
 	const result: Record<string, FindingState> = {};
@@ -437,7 +431,7 @@ export type FindingUpdate = {
 export function applyFindingUpdate(
 	finding: FindingState,
 	update: FindingUpdate,
-	now: string = new Date().toISOString(),
+	now: string = systemClock(),
 ): FindingState {
 	if (update.decision && DECISION_SET.has(update.decision)) {
 		finding.decision = update.decision;
@@ -471,7 +465,7 @@ export type SyncResult = {
 export function syncState(
 	state: FindingsStateFile,
 	readFile: FileReader,
-	now: string = new Date().toISOString(),
+	now: string = systemClock(),
 ): SyncResult {
 	const moved: string[] = [];
 	const stale: string[] = [];
@@ -521,22 +515,165 @@ export function occurrenceCount(
 }
 
 // ---------------------------------------------------------------------------
-// Store (I/O atômico)
+// Domínio (classes)
+// ---------------------------------------------------------------------------
+
+/** Um finding triável, com comportamento sobre o DTO serializável. */
+export class Finding {
+	readonly state: FindingState;
+
+	constructor(state: FindingState) {
+		this.state = state;
+	}
+
+	static from(state: FindingState): Finding {
+		return new Finding(state);
+	}
+
+	get id(): string {
+		return this.state.id;
+	}
+
+	get file(): string {
+		return this.state.file;
+	}
+
+	get line(): number | null {
+		return this.state.line;
+	}
+
+	get severity(): Severity {
+		return this.state.severity;
+	}
+
+	get decision(): FindingDecision {
+		return this.state.decision;
+	}
+
+	get execState(): FindingExecState {
+		return this.state.execState;
+	}
+
+	get present(): boolean {
+		return this.state.present;
+	}
+
+	get isDone(): boolean {
+		return this.state.execState === "done";
+	}
+
+	/** Aplica uma atualização (com histórico) e devolve o próprio finding. */
+	apply(update: FindingUpdate, now: string = systemClock()): Finding {
+		applyFindingUpdate(this.state, update, now);
+		return this;
+	}
+
+	/** Payload serializável (mesmo shape do `state.json`). */
+	toJSON(): FindingState {
+		return this.state;
+	}
+}
+
+/** Coleção de triagem de uma run — superfície OO sobre o `state.json`. */
+export class FindingsState {
+	readonly file: FindingsStateFile;
+
+	constructor(file: FindingsStateFile) {
+		this.file = file;
+	}
+
+	static from(file: FindingsStateFile): FindingsState {
+		return new FindingsState(file);
+	}
+
+	static empty(branch: string): FindingsState {
+		return new FindingsState(emptyState(branch));
+	}
+
+	get branch(): string {
+		return this.file.branch;
+	}
+
+	get reviewed(): FindingsReviewed | undefined {
+		return this.file.reviewed;
+	}
+
+	/** Findings na ordem de exibição (`order`). */
+	list(): Finding[] {
+		return this.file.order
+			.map((id) => this.file.findings[id])
+			.filter((state): state is FindingState => Boolean(state))
+			.map((state) => Finding.from(state));
+	}
+
+	/** Busca por id. */
+	get(id: string): Finding | null {
+		const state = this.file.findings[id];
+		return state ? Finding.from(state) : null;
+	}
+
+	/** Todos os findings (ordem de inserção, sem o `order`). */
+	values(): Finding[] {
+		return Object.values(this.file.findings).map((state) => Finding.from(state));
+	}
+
+	/** Somente os presentes no último relatório. */
+	present(): Finding[] {
+		return this.values().filter((finding) => finding.present);
+	}
+
+	/** Filtra pela ordem canônica (presentes → severidade → arquivo → linha). */
+	filter(filter: FindingsFilter = {}): Finding[] {
+		return filterFindings(this.file, filter).map((state) => Finding.from(state));
+	}
+
+	/** Contagens por decisão, execução e severidade. */
+	summarize(): FindingsSummary {
+		return summarize(this.file);
+	}
+
+	/** Reordena os ids pela ordenação canônica. */
+	reorder(): void {
+		reorder(this.file);
+	}
+
+	/** Aplica uma atualização a um finding e devolve-o (null se ausente). */
+	apply(id: string, update: FindingUpdate, now?: string): Finding | null {
+		const state = this.file.findings[id];
+		if (!state) return null;
+		applyFindingUpdate(state, update, now);
+		return Finding.from(state);
+	}
+
+	/** Reancora os presentes contra os arquivos atuais. */
+	sync(readFile: FileReader, now?: string): SyncResult {
+		return syncState(this.file, readFile, now);
+	}
+
+	/** Payload serializável (mesmo shape do `state.json`). */
+	toJSON(): FindingsStateFile {
+		return this.file;
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Repository (I/O atômico)
 // ---------------------------------------------------------------------------
 
 /** Persistência do `state.json` — escrita atômica (tmp + rename). */
-export class FindingsStateStore {
+export class FindingsRepository {
 	private readonly path: string;
 	private readonly branch: string;
+	private readonly files = new ProjectFiles();
 
 	constructor(path: string, branch: string) {
 		this.path = path;
 		this.branch = branch;
 	}
 
-	/** Store para a run de uma branch. */
-	static at(artifactDir: string, branch: string): FindingsStateStore {
-		return new FindingsStateStore(stateFile(artifactDir, 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 {
@@ -545,31 +682,26 @@ export class FindingsStateStore {
 
 	/** Lê o estado; null se ausente/inválido. */
 	read(): FindingsStateFile | null {
-		if (!existsSync(this.path)) return null;
-		try {
-			const raw = JSON.parse(readFileSync(this.path, "utf8")) as FindingsStateFile;
-			if (raw?.version !== FINDINGS_STATE_VERSION || !raw.findings) return null;
-			return raw;
-		} catch {
-			return null;
-		}
+		const raw = this.files.readJson<FindingsStateFile>(this.path);
+		if (!raw || raw.version !== FINDINGS_STATE_VERSION || !raw.findings) return null;
+		return raw;
 	}
 
 	/** Grava o estado de forma atômica. */
 	write(state: FindingsStateFile): void {
-		mkdirSync(dirname(this.path), { recursive: true });
-		const tmp = `${this.path}.${process.pid}.tmp`;
-		writeFileSync(tmp, `${JSON.stringify(state, null, 2)}\n`);
-		renameSync(tmp, this.path);
+		this.files.writeAtomic(this.path, `${JSON.stringify(state, null, 2)}\n`);
 	}
 
 	/** Lê-modifica-grava; parte de um estado vazio se não existir. */
 	update(mutator: (state: FindingsStateFile) => void): FindingsStateFile {
 		const state = this.read() ?? emptyState(this.branch);
 		mutator(state);
-		state.updatedAt = new Date().toISOString();
+		state.updatedAt = systemClock();
 		reorder(state);
 		this.write(state);
 		return state;
 	}
 }
+
+/** Nome anterior do repository (compatibilidade da API pública). */
+export { FindingsRepository as FindingsStateStore };