@payconductor/houndsman 0.1.4 → 0.3.0

package/src/core/domain/classification.ts

@@ -0,0 +1,94 @@
+/**
+ * Classificação (domínio) — arquivos alterados por domínio de review.
+ *
+ * Envolve o `ClassificationResult` produzido pelo classificador e concentra as
+ * consultas usadas pelo orquestrador (arquivos por watchdog, orçamento, churn).
+ */
+
+import type { ClassificationResult } from "../file-classifier";
+import type { ChurnMap } from "../types";
+import { type BudgetSelection, selectByBudget } from "./budget";
+
+/** Classificação de um diff por watchdog. */
+export class Classification {
+	private readonly data: ClassificationResult;
+
+	constructor(data: ClassificationResult) {
+		this.data = data;
+	}
+
+	static from(data: ClassificationResult): Classification {
+		return new Classification(data);
+	}
+
+	get watchdogs(): Record<string, string[]> {
+		return this.data.watchdogs;
+	}
+
+	get files(): ClassificationResult["files"] {
+		return this.data.files;
+	}
+
+	get churn(): ChurnMap {
+		return this.data.churn;
+	}
+
+	get unclassified(): string[] {
+		return this.data.unclassified;
+	}
+
+	get excluded(): string[] {
+		return this.data.excluded;
+	}
+
+	get deleted(): string[] {
+		return this.data.deleted;
+	}
+
+	get stats(): Record<string, number> {
+		return this.data.stats;
+	}
+
+	get excludedCount(): number {
+		return this.data.excludedCount;
+	}
+
+	get base(): string | undefined {
+		return this.data.base;
+	}
+
+	get head(): string | undefined {
+		return this.data.head;
+	}
+
+	/** Ids de watchdog ativados (com ao menos um arquivo). */
+	get activeIds(): string[] {
+		return Object.keys(this.data.watchdogs);
+	}
+
+	/** Arquivos de um watchdog (vazio quando não ativado). */
+	watchdogsFor(id: string): string[] {
+		return this.data.watchdogs[id] ?? [];
+	}
+
+	/** Aplica o orçamento aos arquivos de um watchdog. */
+	budgetFor(id: string, maxFiles: number): BudgetSelection {
+		return selectByBudget(this.watchdogsFor(id), this.data.churn, maxFiles);
+	}
+
+	/** Totais de churn do diff. */
+	get churnTotals(): { additions: number; deletions: number } {
+		let additions = 0;
+		let deletions = 0;
+		for (const entry of Object.values(this.data.churn ?? {})) {
+			additions += entry.additions;
+			deletions += entry.deletions;
+		}
+		return { additions, deletions };
+	}
+
+	/** Payload serializável (mesmo shape do `classification.json`). */
+	toJSON(): ClassificationResult {
+		return this.data;
+	}
+}

package/src/core/domain/diff.ts

@@ -0,0 +1,53 @@
+/**
+ * Diff (domínio) — patch por arquivo + churn, com consultas coesas.
+ *
+ * Envolve o `DiffSource` coletado uma única vez pelo motor; não executa git.
+ */
+
+import type { DiffSource } from "../diff-source";
+import type { FileChurn } from "../types";
+
+/** Diff coletado de um intervalo de commits. */
+export class Diff {
+	private readonly source: DiffSource;
+
+	constructor(source: DiffSource) {
+		this.source = source;
+	}
+
+	/** Diff vazio (sem patch nem churn). */
+	static empty(): Diff {
+		return new Diff({ byFile: new Map(), churn: new Map() });
+	}
+
+	/** Todos os caminhos presentes no patch ou no churn. */
+	get paths(): string[] {
+		return [...new Set([...this.source.byFile.keys(), ...this.source.churn.keys()])];
+	}
+
+	/** Patch (header + hunks) de um arquivo, se houver. */
+	patchFor(path: string): string | undefined {
+		return this.source.byFile.get(path);
+	}
+
+	/** Churn de um arquivo; zero quando ausente. */
+	churnOf(path: string): FileChurn {
+		return this.source.churn.get(path) ?? { additions: 0, deletions: 0 };
+	}
+
+	/** Totais de churn do diff. */
+	get totals(): { additions: number; deletions: number } {
+		let additions = 0;
+		let deletions = 0;
+		for (const entry of this.source.churn.values()) {
+			additions += entry.additions;
+			deletions += entry.deletions;
+		}
+		return { additions, deletions };
+	}
+
+	/** `DiffSource` subjacente (para as funções puras que ainda o recebem). */
+	toSource(): DiffSource {
+		return this.source;
+	}
+}

package/src/core/domain/watchdog.ts

@@ -0,0 +1,96 @@
+/**
+ * Watchdog (domínio) — envolve a definição declarativa do projeto.
+ *
+ * A configuração continua sendo um objeto plano (`WatchdogDefinition`); esta
+ * classe concentra o comportamento (casar arquivo, ordenar regras, contexto e
+ * render do brief) sem alterar o contrato do consumidor.
+ */
+
+import { renderBrief } from "../brief";
+import {
+	type ClassifyRule,
+	type Rule,
+	severityRank,
+	type WatchdogDefinition,
+	type WatchdogRenderArgs,
+} from "../types";
+
+/** Tipo assumido quando `type` é omitido. */
+const DEFAULT_CLASSIFY_TYPE: NonNullable<ClassifyRule["type"]> = "filename";
+
+/** `true` se o arquivo casa a entrada de classificação. */
+export 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);
+}
+
+/** Contexto "essencial" do watchdog — SEM regras (docs/UI/inspeção). */
+export type WatchdogContext = {
+	id: string;
+	name: string;
+	description: string;
+	scope: string;
+	reviewFocus?: readonly string[];
+	exclude?: readonly string[];
+	contextFiles: string[];
+};
+
+/** Comportamento de um watchdog do projeto. */
+export class Watchdog {
+	readonly definition: WatchdogDefinition;
+
+	constructor(definition: WatchdogDefinition) {
+		this.definition = definition;
+	}
+
+	get id(): string {
+		return this.definition.id;
+	}
+
+	get name(): string {
+		return this.definition.name;
+	}
+
+	get description(): string {
+		return this.definition.description;
+	}
+
+	get scope(): string {
+		return this.definition.scope;
+	}
+
+	/** Regras de classificação declaradas (vazio = não casa nenhum arquivo). */
+	get classify(): readonly ClassifyRule[] {
+		return this.definition.classify ?? [];
+	}
+
+	/** `true` se o arquivo é deste domínio. */
+	matches(filePath: string, content?: string): boolean {
+		return this.classify.some((rule) => matchesClassifyRule(filePath, rule, content));
+	}
+
+	/** Regras ordenadas por severidade (mais grave primeiro). */
+	get rules(): readonly Rule[] {
+		return [...this.definition.rules].sort(
+			(a, b) => severityRank(a.severity) - severityRank(b.severity),
+		);
+	}
+
+	/** Metadados sem as regras. */
+	context(): WatchdogContext {
+		const { id, name, description, scope, reviewFocus, exclude, contextFiles } =
+			this.definition;
+		return { id, name, description, scope, reviewFocus, exclude, contextFiles };
+	}
+
+	/** Render do brief (hook custom ou default). */
+	renderBrief(args: WatchdogRenderArgs): string {
+		return renderBrief(this.definition, args);
+	}
+}

package/src/core/engine/carryover.ts

@@ -0,0 +1,67 @@
+/**
+ * Carry-over do review incremental (engine) — findings de arquivos inalterados.
+ *
+ * Preserva o estado anterior sem re-revisar: o prepare carrega o carry-over e o
+ * finalize o mescla aos findings re-reportados.
+ */
+
+import type { FindingsStateFile } from "../findings-state";
+import type { MergedFinding } from "../report-builder";
+import { severityRank } from "../types";
+
+/** Chave de dedupe de finding: `(file, line, rule)`. */
+function findingKey(finding: Pick<MergedFinding, "file" | "line" | "rule">): string {
+	return `${finding.file}|${finding.line ?? ""}|${finding.rule}`;
+}
+
+/**
+ * Findings do review anterior em arquivos inalterados — carregados sem
+ * re-revisão (carry-over). Preserva o `foundAtSha` para o diff focado do verify.
+ */
+export 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 anteriores). */
+export 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;
+}

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