@payconductor/houndsman 0.2.0 → 0.4.0

package/src/core/renderers/watchdog-presenter.ts

@@ -0,0 +1,100 @@
+/**
+ * Apresentação do contexto de um watchdog (biblioteca) — markdown/JSON.
+ */
+
+import type { WatchdogContext } from "../domain/watchdog";
+import {
+	type Rule,
+	SEVERITY_EMOJI,
+	severityRank,
+	type WatchdogDefinition,
+} from "../types";
+
+/** Opções de apresentação do watchdog. */
+export type WatchdogRenderOptions = {
+	/** Inclui as regras. */
+	withRules: boolean;
+	/** Saída JSON (default: markdown). */
+	json: boolean;
+};
+
+/** Renderiza o contexto de um watchdog. */
+export class WatchdogPresenter {
+	render(
+		context: WatchdogContext,
+		definition: WatchdogDefinition,
+		options: WatchdogRenderOptions,
+	): string {
+		return options.json
+			? this.serialize(context, definition, options.withRules)
+			: this.markdown(context, definition, options.withRules);
+	}
+
+	/** Payload serializável (regras incluídas apenas com `withRules`). */
+	private serialize(
+		context: WatchdogContext,
+		definition: WatchdogDefinition,
+		withRules: boolean,
+	): string {
+		const payload = withRules
+			? { ...context, rules: definition.rules }
+			: { ...context };
+		return JSON.stringify(payload, null, 2);
+	}
+
+	/** Lista de itens em bloco `## <título>` (vazio se não houver itens). */
+	private 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>`. */
+	private 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. */
+	private markdown(
+		context: WatchdogContext,
+		definition: WatchdogDefinition,
+		withRules: boolean,
+	): string {
+		const lines: string[] = [
+			`# ${context.name} (\`${context.id}\`)`,
+			"",
+			`**Descrição:** ${context.description}`,
+			`**Escopo:** ${context.scope}`,
+			"",
+		];
+
+		lines.push(...this.section("Prioridade de leitura", context.reviewFocus));
+		lines.push(...this.section("Não carregar", context.exclude));
+		lines.push(
+			...this.section(
+				"Docs de contexto",
+				context.contextFiles.map((doc) => `\`${doc}\``),
+			),
+		);
+
+		if (withRules) {
+			lines.push(
+				...this.ruleSection(
+					"Regras",
+					[...definition.rules].sort(
+						(a, b) => severityRank(a.severity) - severityRank(b.severity),
+					),
+				),
+			);
+		}
+
+		return lines.join("\n").trimEnd();
+	}
+}

package/src/core/report-builder.ts

@@ -8,6 +8,7 @@
  */
 
 import type { JevCandidate } from "./jev";
+import { systemClock } from "./services/clock";
 import { SEVERITY_EMOJI, SEVERITY_ORDER, type Severity, severityRank } from "./types";
 
 /** Resolve o nome legível de um watchdog (default: identidade). */
@@ -106,24 +107,28 @@ function isFinding(value: unknown): value is Finding {
 }
 
 /** Valida e normaliza um relatório. Retorna null se inválido. */
-export function parseWatchdogReport(raw: unknown, source: string): WatchdogReport | null {
+export function parseWatchdogReport(
+	raw: unknown,
+	source: string,
+	onError: (message: string) => void = () => {},
+): WatchdogReport | null {
 	if (typeof raw !== "object" || raw === null) {
-		console.error(`[report-builder] ${source}: não é um objeto JSON`);
+		onError(`[report-builder] ${source}: não é um objeto JSON`);
 		return null;
 	}
 	const obj = raw as Record<string, unknown>;
 	if (typeof obj.watchdogId !== "string") {
-		console.error(`[report-builder] ${source}: campo 'watchdogId' ausente`);
+		onError(`[report-builder] ${source}: campo 'watchdogId' ausente`);
 		return null;
 	}
 	if (!Array.isArray(obj.findings)) {
-		console.error(`[report-builder] ${source}: campo 'findings' ausente`);
+		onError(`[report-builder] ${source}: campo 'findings' ausente`);
 		return null;
 	}
 
 	const findings = obj.findings.filter((f) => {
 		if (!isFinding(f)) {
-			console.error(`[report-builder] ${source}: finding inválido ignorado`);
+			onError(`[report-builder] ${source}: finding inválido ignorado`);
 			return false;
 		}
 		return true;
@@ -370,7 +375,7 @@ export function renderDomainReport(
 	context?: ContextSummary | null,
 	nameOf: WatchdogNameResolver = identityName,
 ): string {
-	const now = new Date().toISOString().slice(0, 10);
+	const now = systemClock().slice(0, 10);
 	const name = watchdogName(nameOf, report.watchdogId);
 	const lines: string[] = [
 		`# Review — ${name} (\`${report.watchdogId}\`) — ${branch}`,
@@ -429,7 +434,7 @@ export function renderReport(
 	nameOf: WatchdogNameResolver = identityName,
 	domains: readonly DomainReport[] = [],
 ): string {
-	const now = new Date().toISOString().slice(0, 10);
+	const now = systemClock().slice(0, 10);
 	const counts = {
 		blocking: merged.filter((f) => f.severity === "blocking").length,
 		attention: merged.filter((f) => f.severity === "attention").length,

package/src/core/run-layout.ts

@@ -0,0 +1,8 @@
+/**
+ * Removido: o layout de artefatos do projeto deu lugar ao staging global por
+ * review (`ReviewWorkArea` em `core/storage/work-area.ts`).
+ *
+ * Mantido apenas para não quebrar imports antigos de tipos.
+ */
+
+export type { ContextPaths } from "./storage/work-area";

package/src/core/run-status.ts

@@ -1,22 +1,20 @@
 /**
- * Status do run (biblioteca) — persistido em `.houndsman/.runs/<slug>/run.json`.
+ * Status do run (biblioteca) — colunas da review no storage.
  *
  * Diz à UI em que pé está uma run: `reviewing` (revisando) → `review_done`
  * (revisão finalizada) → `fixing` (corrigindo) → `fix_done` (correção finalizada).
  *
- * Toda ação que muda o estado faz um **ping** no `updatedAt`, mantendo o arquivo
- * "quente". Timeout é **display-only** (a UI compara `updatedAt` com o agora) —
- * não é um status persistido.
+ * Toda ação que muda o estado faz um **ping** no `updatedAt`. Timeout é
+ * **display-only** (a UI compara `updatedAt` com o agora) — não é um status
+ * persistido.
  */
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
 import type { FindingsStateFile } from "./findings-state";
-import { RUN_STATUS_FILE } from "./paths";
-import { sanitizeBranch } from "./report-builder";
+import { systemClock } from "./services/clock";
+import type { ReviewRecord, ReviewStatus, StorageProvider } from "./storage/types";
 
 /** Estados de execução de uma run (persistidos). */
-export type RunStatus = "reviewing" | "review_done" | "fixing" | "fix_done";
+export type RunStatus = ReviewStatus;
 
 /** Valores canônicos de status (ordem de exibição/lifecycle). */
 export const RUN_STATUSES: readonly RunStatus[] = [
@@ -26,62 +24,34 @@ export const RUN_STATUSES: readonly RunStatus[] = [
 	"fix_done",
 ];
 
-export const RUN_STATUS_VERSION = 1;
-
-/** Conteúdo do `run.json`. */
-export type RunStatusFile = {
-	version: 1;
-	slug: string;
-	branch: string;
-	status: RunStatus;
-	/** Início do ciclo de revisão atual (reiniciado a cada `prepare`). */
-	startedAt: string;
-	/** Última ação importante (ping). */
-	updatedAt: string;
-};
-
-/** Caminho do `run.json` dentro da pasta da run. */
-export function runStatusPath(runDir: string): string {
-	return join(runDir, RUN_STATUS_FILE);
-}
-
-/** Lê o `run.json` da run (null se ausente/inválido). */
-export function readRunStatus(runDir: string): RunStatusFile | null {
-	const path = runStatusPath(runDir);
-	if (!existsSync(path)) return null;
-	try {
-		return JSON.parse(readFileSync(path, "utf8")) as RunStatusFile;
-	} catch {
-		return null;
-	}
+/** Lê o status atual (null se a review não existir). */
+export function readRunStatus(
+	storage: StorageProvider,
+	reviewId: string,
+): ReviewRecord | null {
+	return storage.getReview(reviewId);
 }
 
 export type WriteRunStatusOptions = {
-	branch: string;
 	status: RunStatus;
 	/** Reinicia o `startedAt` — usado no início de uma nova revisão. */
 	resetStartedAt?: boolean;
 	now?: string;
 };
 
-/** Grava/atualiza o `run.json` (ping no `updatedAt`). */
+/** Grava/atualiza o status da review (ping no `updatedAt`). */
 export function writeRunStatus(
-	runDir: string,
+	storage: StorageProvider,
+	reviewId: string,
 	options: WriteRunStatusOptions,
-): RunStatusFile {
-	const now = options.now ?? new Date().toISOString();
-	const previous = readRunStatus(runDir);
-	const file: RunStatusFile = {
-		version: RUN_STATUS_VERSION,
-		slug: sanitizeBranch(options.branch),
-		branch: options.branch,
+): ReviewRecord {
+	const updated = storage.updateReview(reviewId, {
 		status: options.status,
-		startedAt: options.resetStartedAt ? now : (previous?.startedAt ?? now),
-		updatedAt: now,
-	};
-	mkdirSync(runDir, { recursive: true });
-	writeFileSync(runStatusPath(runDir), `${JSON.stringify(file, null, 2)}\n`);
-	return file;
+		resetStartedAt: options.resetStartedAt,
+		updatedAt: options.now ?? systemClock(),
+	});
+	if (!updated) throw new Error(`Review '${reviewId}' não encontrada.`);
+	return updated;
 }
 
 /**
@@ -110,14 +80,14 @@ export function statusAfterFindingsChange(
 	return previous ?? "review_done";
 }
 
-/** Ping: deriva o status da mudança nos findings e grava o `run.json`. */
+/** Ping: deriva o status da mudança nos findings e grava na review. */
 export function pingFindingsStatus(
-	runDir: string,
+	storage: StorageProvider,
+	reviewId: string,
 	state: FindingsStateFile,
-): RunStatusFile {
-	const previous = readRunStatus(runDir)?.status ?? null;
-	return writeRunStatus(runDir, {
-		branch: state.branch,
+): ReviewRecord {
+	const previous = storage.getReview(reviewId)?.status ?? null;
+	return writeRunStatus(storage, reviewId, {
 		status: statusAfterFindingsChange(previous, state),
 	});
 }

package/src/core/services/clock.ts

@@ -0,0 +1,12 @@
+/**
+ * Relógio injetável (biblioteca) — timestamps ISO 8601.
+ *
+ * Centraliza `new Date().toISOString()` para que o domínio não dependa do
+ * relógio do sistema e os testes possam congelar o tempo.
+ */
+
+/** Devolve um timestamp ISO 8601. */
+export type Clock = () => string;
+
+/** Relógio do sistema (default do motor). */
+export const systemClock: Clock = () => new Date().toISOString();

package/src/core/services/file-classifier.ts

@@ -0,0 +1,34 @@
+/**
+ * Serviço de classificação (biblioteca) — superfície OO sobre as funções puras.
+ *
+ * Mantém as funções exportadas (`classifyEntries`/`classifyRange`) para a API
+ * pública e os testes; a classe devolve `Classification` (domínio).
+ */
+
+import type { HoundsmanConfig } from "../config";
+import type { DiffSource } from "../diff-source";
+import { Classification } from "../domain/classification";
+import { classifyEntries, classifyRange, type parseEntries } from "../file-classifier";
+import type { ChurnMap } from "../types";
+
+/** Classificador de arquivos alterados por domínio de review. */
+export class FileClassifier {
+	private readonly config: HoundsmanConfig;
+
+	constructor(config: HoundsmanConfig) {
+		this.config = config;
+	}
+
+	/** Classifica entradas já parseadas (`git diff --name-status`). */
+	classify(
+		entries: ReturnType<typeof parseEntries>,
+		churn: ChurnMap = {},
+	): Classification {
+		return new Classification(classifyEntries(entries, this.config, churn));
+	}
+
+	/** Executa o diff e classifica os arquivos entre `base` e `head`. */
+	classifyRange(base: string, head: string, diff?: DiffSource): Classification {
+		return new Classification(classifyRange(base, head, this.config, diff));
+	}
+}

package/src/core/services/fix-batch-builder.ts

@@ -0,0 +1,13 @@
+/**
+ * Montagem do lote de correção (biblioteca) — superfície OO sobre `fix-batch`.
+ */
+
+import type { FindingsStateFile } from "../findings-state";
+import { buildFixBatch, type FixBatchOptions, type FixBatchResult } from "../fix-batch";
+
+/** Constrói o lote de correção a partir do estado de triagem. */
+export class FixBatchBuilder {
+	build(state: FindingsStateFile, options: FixBatchOptions = {}): FixBatchResult {
+		return buildFixBatch(state, options);
+	}
+}

package/src/core/services/gh-client.ts

@@ -0,0 +1,54 @@
+/**
+ * Cliente do GitHub CLI (`gh`) — biblioteca.
+ *
+ * Um único runner para todo o motor (`context` e `findings submit`). O `gh` é
+ * opcional e falha-aberto: o runner nunca lança, devolve o resultado cru.
+ */
+
+export type GhResult = { ok: boolean; code: number; stdout: string; stderr: string };
+
+/** Executa o `gh` e devolve o resultado cru (sem lançar). */
+export type GhRunner = (args: string[]) => GhResult;
+
+/** Runner padrão: `gh` a partir do cwd; ausência do binário → `ok:false`. */
+export const defaultGhRunner: GhRunner = (args) => {
+	try {
+		const result = Bun.spawnSync(["gh", ...args], {
+			stdout: "pipe",
+			stderr: "pipe",
+		});
+		const code = result.exitCode ?? 1;
+		return {
+			ok: code === 0,
+			code,
+			stdout: new TextDecoder().decode(result.stdout).trim(),
+			stderr: new TextDecoder().decode(result.stderr).trim(),
+		};
+	} catch (error) {
+		return {
+			ok: false,
+			code: 127,
+			stdout: "",
+			stderr: error instanceof Error ? error.message : String(error),
+		};
+	}
+};
+
+/** Superfície OO sobre o runner injetável. */
+export class GhClient {
+	private readonly runner: GhRunner;
+
+	constructor(runner: GhRunner = defaultGhRunner) {
+		this.runner = runner;
+	}
+
+	/** Executa `gh` e devolve o resultado cru. */
+	run(args: string[]): GhResult {
+		return this.runner(args);
+	}
+
+	/** `true` se o binário existe no PATH (independe de login). */
+	isAvailable(): boolean {
+		return Boolean(Bun.which("gh"));
+	}
+}

package/src/core/services/git-repository.ts

@@ -0,0 +1,139 @@
+/**
+ * Acesso ao repositório git (biblioteca) — superfície OO sobre `git-runner`.
+ *
+ * Centraliza resolução de refs, ancestralidade, leitura por commit e coleta de
+ * diffs. Nenhum path/id de consumidor aqui.
+ */
+
+import {
+	type CollectDiffOptions,
+	DEFAULT_MAX_PER_FILE_CHARS,
+	type DiffSource,
+	parseDiffIndex,
+	parseNumstat,
+} from "../diff-source";
+import {
+	defaultGitRunner,
+	type GitResult,
+	type GitRunner,
+	runGit,
+	tryGit,
+} from "../git-runner";
+import type { FileChurn } from "../types";
+
+/** Repositório git com runner injetável (testes). */
+export class GitRepository {
+	private readonly runner: GitRunner;
+
+	constructor(runner: GitRunner = defaultGitRunner) {
+		this.runner = runner;
+	}
+
+	/** Executa git e devolve stdout; lança em falha. */
+	run(args: string[]): string {
+		return runGit(args, this.runner);
+	}
+
+	/** Executa git sem lançar (sondagens). */
+	tryRun(args: string[]): GitResult {
+		return tryGit(args, this.runner);
+	}
+
+	/** SHA completo de uma ref. */
+	resolveSha(ref: string): string {
+		return this.run(["rev-parse", ref]).trim();
+	}
+
+	/** Branch atual; `null` se indisponível (sem git, detached ou erro). */
+	currentBranch(): string | null {
+		const result = this.tryRun(["branch", "--show-current"]);
+		if (!result.ok) return null;
+		const branch = result.stdout.trim();
+		return branch.length > 0 ? branch : null;
+	}
+
+	/** Raiz do repositório; `null` fora de um repo git. */
+	rootPath(): string | null {
+		const result = this.tryRun(["rev-parse", "--show-toplevel"]);
+		if (!result.ok) return null;
+		const root = result.stdout.trim();
+		return root.length > 0 ? root : null;
+	}
+
+	/** URL de um remote (default `origin`); `null` se ausente. */
+	remoteUrl(name = "origin"): string | null {
+		const result = this.tryRun(["remote", "get-url", name]);
+		if (!result.ok) return null;
+		const url = result.stdout.trim();
+		return url.length > 0 ? url : null;
+	}
+
+	/**
+	 * `true` se `ancestor` é ancestral de `descendant`. Qualquer outro desfecho
+	 * (ref desconhecida, exit ≠ 0) devolve `false` — cai no review completo.
+	 */
+	isAncestor(ancestor: string, descendant: string): boolean {
+		return this.tryRun(["merge-base", "--is-ancestor", ancestor, descendant]).ok;
+	}
+
+	/** Conteúdo de um arquivo num commit; `null` se ausente. */
+	readFileAt(sha: string, path: string): string | null {
+		const result = this.tryRun(["show", `${sha}:${path}`]);
+		return result.ok ? result.stdout : null;
+	}
+
+	/** `git diff base...head --name-status` cru. */
+	diffNameStatus(base: string, head: string): string {
+		return this.run(["diff", `${base}...${head}`, "--name-status"]);
+	}
+
+	/** Churn por arquivo de um intervalo (`--numstat -z`). */
+	diffNumstat(range: string): Map<string, FileChurn> {
+		return parseNumstat(this.run(["diff", "--numstat", "-z", range]));
+	}
+
+	/** Patch por arquivo de um intervalo, opcionalmente restrito a `paths`. */
+	diffPatch(
+		range: string,
+		paths?: readonly string[],
+		maxPerFileChars: number = DEFAULT_MAX_PER_FILE_CHARS,
+	): Map<string, string> {
+		const args = ["diff", range];
+		if (paths && paths.length > 0) args.push("--", ...paths);
+		return parseDiffIndex(this.run(args), maxPerFileChars);
+	}
+
+	/** Churn de `base...head` — 1 spawn. */
+	collectChurn(base: string, head: string): Map<string, FileChurn> {
+		return this.diffNumstat(`${base}...${head}`);
+	}
+
+	/** Patch + churn da PR (`base...head`) — 2 spawns fixos. */
+	collectDiff(
+		base: string,
+		head: string,
+		options: CollectDiffOptions = {},
+	): DiffSource {
+		const range = `${base}...${head}`;
+		return {
+			byFile: parseDiffIndex(
+				this.run(["diff", range]),
+				options.maxPerFileChars ?? DEFAULT_MAX_PER_FILE_CHARS,
+			),
+			churn: this.collectChurn(base, head),
+		};
+	}
+
+	/** Patch + churn de `from..to` — base do review incremental. */
+	collectDiffSince(
+		from: string,
+		to: string,
+		maxPerFileChars: number = DEFAULT_MAX_PER_FILE_CHARS,
+	): DiffSource {
+		const range = `${from}..${to}`;
+		return {
+			byFile: parseDiffIndex(this.run(["diff", range]), maxPerFileChars),
+			churn: this.diffNumstat(range),
+		};
+	}
+}

package/src/core/services/project-files.ts

@@ -0,0 +1,91 @@
+/**
+ * Acesso a arquivos do projeto (biblioteca) — I/O centralizado e injetável.
+ *
+ * Caminhos relativos são resolvidos contra o `cwd` do projeto; absolutos passam
+ * intactos. Operações que falham devolvem `null`/`false` em vez de lançar, para
+ * manter o comportamento fail-open do motor.
+ */
+
+import {
+	existsSync,
+	mkdirSync,
+	readFileSync,
+	renameSync,
+	rmSync,
+	writeFileSync,
+} from "node:fs";
+import { dirname, isAbsolute, join } from "node:path";
+
+/** Leitor de arquivos relativos à raiz do projeto (injetável nos testes). */
+export type FileReader = (relativePath: string) => string | null;
+
+/** Acesso ao filesystem resolvido a partir de um `cwd`. */
+export class ProjectFiles {
+	private readonly cwd: string;
+
+	constructor(cwd: string = process.cwd()) {
+		this.cwd = cwd;
+	}
+
+	/** Resolve um caminho (relativo → absoluto). */
+	resolve(path: string): string {
+		return isAbsolute(path) ? path : join(this.cwd, path);
+	}
+
+	/** Lê UTF-8; `null` se ausente/ilegível. */
+	read(path: string): string | null {
+		const full = this.resolve(path);
+		try {
+			return existsSync(full) ? readFileSync(full, "utf8") : null;
+		} catch {
+			return null;
+		}
+	}
+
+	/** Lê + parseia JSON; `null` se ausente/inválido. */
+	readJson<T>(path: string): T | null {
+		const raw = this.read(path);
+		if (raw === null) return null;
+		try {
+			return JSON.parse(raw) as T;
+		} catch {
+			return null;
+		}
+	}
+
+	/** Escreve UTF-8, criando o diretório pai. */
+	write(path: string, content: string): void {
+		const full = this.resolve(path);
+		mkdirSync(dirname(full), { recursive: true });
+		writeFileSync(full, content);
+	}
+
+	/** Escrita atômica (tmp + rename). */
+	writeAtomic(path: string, content: string): void {
+		const full = this.resolve(path);
+		mkdirSync(dirname(full), { recursive: true });
+		const tmp = `${full}.${process.pid}.tmp`;
+		writeFileSync(tmp, content);
+		renameSync(tmp, full);
+	}
+
+	/** Cria o diretório (recursivo). */
+	ensureDir(path: string): void {
+		mkdirSync(this.resolve(path), { recursive: true });
+	}
+
+	/** Remove um diretório (recursivo, best-effort). */
+	removeDir(path: string): void {
+		rmSync(this.resolve(path), { recursive: true, force: true });
+	}
+
+	/** `true` se o caminho existe. */
+	exists(path: string): boolean {
+		return existsSync(this.resolve(path));
+	}
+
+	/** Função de leitura ligada a este `cwd` (compatível com `FileReader`). */
+	reader(): FileReader {
+		return (relativePath: string) => this.read(relativePath);
+	}
+}