@payconductor/houndsman 0.2.0 → 0.4.0

package/src/core/defaults.ts

@@ -0,0 +1,20 @@
+/**
+ * Defaults do motor (biblioteca) — valores canônicos compartilhados.
+ *
+ * Vivem fora de `config.ts` para que `ProjectConfig` possa usá-los sem criar
+ * ciclo de importação com os adaptadores públicos.
+ */
+
+/** Documentos sempre incluídos nos briefs (default). */
+export const DEFAULT_ALWAYS_INCLUDE_DOCS: readonly string[] = ["AGENTS.md"];
+
+/**
+ * Teto default de arquivos por brief. Um PR grande (milhares de linhas) pode
+ * concentrar centenas de arquivos em um único domínio; o teto mantém o contexto
+ * do subagente limitado — o excedente vira "fora do orçamento" (cobertura
+ * honesta), nunca some silenciosamente.
+ */
+export const DEFAULT_MAX_FILES_PER_BRIEF = 40;
+
+/** Concorrência default das chamadas simultâneas ao Jev. */
+export const DEFAULT_JEV_CONCURRENCY = 5;

package/src/core/diff-source.ts

@@ -9,6 +9,7 @@
  * Jev) e por `classifyRange` (fallback standalone).
  */
 
+import { runGit } from "./git-runner";
 import type { ChurnMap, FileChurn } from "./types";
 
 export type DiffSource = {
@@ -26,19 +27,6 @@ export type CollectDiffOptions = {
 /** Teto default de caracteres por arquivo no patch (compartilhado com o git-revision). */
 export const DEFAULT_MAX_PER_FILE_CHARS = 8_000;
 
-/** Executa `git` com `core.quotepath=false` (paths literais) e devolve o stdout. */
-function runGit(args: string[]): string {
-	const result = Bun.spawnSync(["git", "-c", "core.quotepath=false", ...args], {
-		stdout: "pipe",
-		stderr: "pipe",
-	});
-	if (result.exitCode !== 0) {
-		const stderr = new TextDecoder().decode(result.stderr).trim();
-		throw new Error(`git ${args.join(" ")} falhou: ${stderr}`);
-	}
-	return new TextDecoder().decode(result.stdout);
-}
-
 /** Novo caminho do arquivo a partir do cabeçalho de um segmento do patch. */
 function extractPath(segment: string): string | undefined {
 	// Só o cabeçalho (antes do primeiro hunk) pode conter as linhas `---`/`+++` —

package/src/core/doc-discoverer.ts

@@ -6,28 +6,38 @@
  * (`project/doc-mappings.ts`) e chegam via `HoundsmanConfig`.
  */
 
-import { DEFAULT_ALWAYS_INCLUDE_DOCS, type HoundsmanConfig } from "./config";
+import type { HoundsmanConfig } from "./config";
+import { ProjectConfig } from "./project-config";
 
-/** Descobre docs relevantes com base nos paths + docs sempre incluídos. */
-export function discoverDocs(filePaths: string[], config: HoundsmanConfig): string[] {
-	const docs = new Set<string>();
+/** Descobre documentação relevante para um conjunto de arquivos alterados. */
+export class DocDiscoverer {
+	private readonly alwaysInclude: readonly string[];
+	private readonly mappings: readonly (readonly [RegExp, readonly string[]])[];
 
-	for (const doc of config.alwaysIncludeDocs ?? DEFAULT_ALWAYS_INCLUDE_DOCS) {
-		docs.add(doc);
+	constructor(config: HoundsmanConfig) {
+		const project = new ProjectConfig(config);
+		this.alwaysInclude = project.alwaysIncludeDocs;
+		this.mappings = project.docMappings;
 	}
 
-	for (const filePath of filePaths) {
-		const normalized = filePath.trim().toLowerCase();
-		if (!normalized) continue;
+	discover(filePaths: readonly string[]): string[] {
+		const docs = new Set<string>(this.alwaysInclude);
 
-		for (const [pattern, docPaths] of config.docMappings) {
-			if (pattern.test(normalized)) {
-				for (const docPath of docPaths) {
-					docs.add(docPath);
-				}
+		for (const filePath of filePaths) {
+			const normalized = filePath.trim().toLowerCase();
+			if (!normalized) continue;
+
+			for (const [pattern, docPaths] of this.mappings) {
+				if (!pattern.test(normalized)) continue;
+				for (const docPath of docPaths) docs.add(docPath);
 			}
 		}
+
+		return [...docs].sort();
 	}
+}
 
-	return [...docs].sort();
+/** Descobre docs relevantes com base nos paths + docs sempre incluídos. */
+export function discoverDocs(filePaths: string[], config: HoundsmanConfig): string[] {
+	return new DocDiscoverer(config).discover(filePaths);
 }

package/src/core/domain/budget.ts

@@ -0,0 +1,42 @@
+/**
+ * Orçamento por brief (domínio) — funções puras de triagem de PRs grandes.
+ *
+ * Separado de `file-classifier` para que `Classification` possa aplicar o
+ * orçamento sem depender do serviço de classificação.
+ */
+
+import type { ChurnMap } from "../types";
+
+/** 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) };
+}

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,65 @@
+/**
+ * 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 { 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). */
+export type EngineDeps = {
+	git?: GitRepository;
+	classifier?: FileClassifier;
+	verifier?: Verifier;
+	fixBatch?: FixBatchBuilder;
+	storage?: StorageProvider;
+	repo?: RepoIdentity;
+};
+
+/** Composition root do motor. */
+export class HoundsmanEngine {
+	readonly project: ProjectConfig;
+	readonly git: GitRepository;
+	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);
+		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();
+		this.storage = deps.storage ?? createStorage(raw);
+		this.repo = deps.repo ?? resolveRepoIdentity(this.git);
+	}
+
+	/** 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, 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-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 };
+	}
+}