@payconductor/houndsman 0.2.0 → 0.3.0

package/src/core/commands/update.ts

@@ -13,18 +13,18 @@ export type UpdateOptions = {
 	args: string[];
 };
 
-/** Sincroniza os arquivos auto-gerados da camada de projeto. */
-export async function runUpdateCommand(options: UpdateOptions): Promise<void> {
+/** Sincroniza os arquivos auto-gerados da camada de projeto. Devolve mensagens. */
+export async function runUpdateCommand(options: UpdateOptions): Promise<string[]> {
 	const ctx = createScaffoldContext(options.cwd, options.args, false);
-
-	console.log(`→ Sincronizando arquivos auto-gerados em ${ctx.cwd}`);
+	const messages = [`→ Sincronizando arquivos auto-gerados em ${ctx.cwd}`];
 
 	syncGeneratedFiles(ctx);
 
-	for (const path of ctx.generated) console.log(`  ~ ${path} (auto)`);
+	for (const path of ctx.generated) messages.push(`  ~ ${path} (auto)`);
 
-	console.log("\nArquivos do usuário não foram tocados:");
-	console.log(
+	messages.push(
+		"\nArquivos do usuário não foram tocados:",
 		"  .houndsman/watchdogs/ · exclusions.ts · doc-mappings.ts · houndsman.config.ts",
 	);
+	return messages;
 }

package/src/core/commands/watchdog.ts

@@ -6,12 +6,7 @@
  */
 
 import type { HoundsmanConfig } from "../config";
-import {
-	type Rule,
-	SEVERITY_EMOJI,
-	severityRank,
-	type WatchdogDefinition,
-} from "../types";
+import { WatchdogPresenter } from "../renderers/watchdog-presenter";
 import { findWatchdog, getWatchdogContext } from "../watchdog-registry";
 
 export type WatchdogContextOptions = {
@@ -21,7 +16,7 @@ export type WatchdogContextOptions = {
 	json?: boolean;
 };
 
-type WatchdogContext = ReturnType<typeof getWatchdogContext>;
+const presenter = new WatchdogPresenter();
 
 /** Renderiza o contexto de um watchdog (markdown ou JSON). `null` se o id não existe. */
 export function renderWatchdogContext(
@@ -29,77 +24,10 @@ export function renderWatchdogContext(
 	id: string,
 	opts: WatchdogContextOptions = {},
 ): string | null {
-	const def = findWatchdog(config, id);
-	if (!def) return null;
-	const ctx = getWatchdogContext(config, def.id);
-	const withRules = opts.withRules ?? false;
-	return opts.json
-		? serializeWatchdogContext(ctx, def, withRules)
-		: renderWatchdogMarkdown(ctx, def, withRules);
-}
-
-/** Payload serializável (regras incluídas apenas com `withRules`). */
-function serializeWatchdogContext(
-	ctx: WatchdogContext,
-	def: WatchdogDefinition,
-	withRules: boolean,
-): string {
-	const payload = withRules ? { ...ctx, rules: def.rules } : { ...ctx };
-	return JSON.stringify(payload, null, 2);
-}
-
-/** Lista de itens em bloco `## <título>` (vazio se não houver itens). */
-function section(title: string, items: readonly string[] | undefined): string[] {
-	if (!items || items.length === 0) return [];
-	return [`## ${title}`, "", ...items.map((item) => `- ${item}`), ""];
-}
-
-/** Regras com emoji de severidade em bloco `## <título>`. */
-function ruleSection(title: string, rules: readonly Rule[]): string[] {
-	return [
-		`## ${title}`,
-		"",
-		...rules.map(
-			(rule) =>
-				`- ${SEVERITY_EMOJI[rule.severity]} **${rule.severity}** — ${rule.text}`,
-		),
-		"",
-	];
-}
-
-/** Render markdown legível do contexto do watchdog. */
-function renderWatchdogMarkdown(
-	ctx: WatchdogContext,
-	def: WatchdogDefinition,
-	withRules: boolean,
-): string {
-	const lines: string[] = [
-		`# ${ctx.name} (\`${ctx.id}\`)`,
-		"",
-		`**Descrição:** ${ctx.description}`,
-		`**Escopo:** ${ctx.scope}`,
-		"",
-	];
-
-	lines.push(...section("Prioridade de leitura", ctx.reviewFocus));
-	lines.push(...section("Não carregar", ctx.exclude));
-	lines.push(
-		...section(
-			"Docs de contexto",
-			ctx.contextFiles.map((doc) => `\`${doc}\``),
-		),
-	);
-
-	if (withRules) {
-		lines.push(
-			...ruleSection(
-				"Regras",
-				[...def.rules].sort(
-					(a, b) => severityRank(a.severity) - severityRank(b.severity),
-				),
-			),
-		);
-	}
-
-	return lines.join("\n").trimEnd();
+	const definition = findWatchdog(config, id);
+	if (!definition) return null;
+	return presenter.render(getWatchdogContext(config, definition.id), definition, {
+		withRules: opts.withRules ?? false,
+		json: opts.json ?? false,
+	});
 }

package/src/core/config.ts

@@ -6,22 +6,14 @@
  * (camada `houndsman/`) — único ponto de troca ao portar para outro repositório.
  */
 
-import { ARTIFACT_DIR } from "./paths";
+import { ProjectConfig } from "./project-config";
 import type { WatchdogDefinition } from "./types";
 
-/** 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;
+export {
+	DEFAULT_ALWAYS_INCLUDE_DOCS,
+	DEFAULT_JEV_CONCURRENCY,
+	DEFAULT_MAX_FILES_PER_BRIEF,
+} from "./defaults";
 
 /** Limites de triage para PRs grandes. */
 export type HoundsmanBudgets = {
@@ -82,7 +74,7 @@ export function defineHoundsmanConfig<TId extends string>(
 
 /** Diretório dos artefatos — o valor do projeto ou o default da camada. */
 export function resolveArtifactDir(config: HoundsmanConfig): string {
-	return config.artifactDir ?? ARTIFACT_DIR;
+	return new ProjectConfig(config).artifactDir;
 }
 
 /**
@@ -90,12 +82,10 @@ export function resolveArtifactDir(config: HoundsmanConfig): string {
  * mantém o contexto do subagente limitado em PRs grandes.
  */
 export function resolveMaxFilesPerBrief(config: HoundsmanConfig): number {
-	const value = config.budgets?.maxFilesPerBrief;
-	return value !== undefined && value > 0 ? value : DEFAULT_MAX_FILES_PER_BRIEF;
+	return new ProjectConfig(config).maxFilesPerBrief;
 }
 
 /** Concorrência das chamadas Jev (valor ausente/não-positivo cai no default). */
 export function resolveJevConcurrency(config: HoundsmanConfig): number {
-	const value = config.concurrency?.jev;
-	return value !== undefined && value > 0 ? value : DEFAULT_JEV_CONCURRENCY;
+	return new ProjectConfig(config).jevConcurrency;
 }

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;
+}