@payconductor/houndsman 0.2.0 → 0.3.0

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,108 @@
+/**
+ * Layout de uma run (biblioteca) — único ponto que conhece os nomes/estrutura
+ * dos artefatos em `.houndsman/.runs/<slug>/`.
+ *
+ * Evita o "data clump" de `(dir, branch)`/`(outDir, branch)` espalhado pelo
+ * motor: quem precisa de um caminho pede ao layout.
+ */
+
+import { join } from "node:path";
+import {
+	CONTEXT_BRIEF_FILE,
+	CONTEXT_FILE,
+	CONTEXT_SUMMARY_FILE,
+	RUN_STATUS_FILE,
+	STATE_FILE,
+	VERIFY_FILE,
+} from "./paths";
+import { sanitizeBranch } from "./report-builder";
+
+/** Caminhos dos artefatos de contexto da PR. */
+export type ContextPaths = {
+	dir: string;
+	context: string;
+	summary: string;
+	brief: string;
+};
+
+/** Diretório e caminhos de uma run (branch-slug). */
+export class RunLayout {
+	readonly artifactDir: string;
+	readonly branch: string;
+
+	constructor(artifactDir: string, branch: string) {
+		this.artifactDir = artifactDir;
+		this.branch = branch;
+	}
+
+	get slug(): string {
+		return sanitizeBranch(this.branch);
+	}
+
+	get outDir(): string {
+		return join(this.artifactDir, this.slug);
+	}
+
+	get briefsDir(): string {
+		return join(this.outDir, "briefs");
+	}
+
+	get findingsDir(): string {
+		return join(this.outDir, "findings");
+	}
+
+	/** Caminho de um arquivo dentro da pasta da run. */
+	file(name: string): string {
+		return join(this.outDir, name);
+	}
+
+	briefFile(id: string): string {
+		return join(this.briefsDir, `${id}.md`);
+	}
+
+	findingFile(id: string): string {
+		return join(this.findingsDir, `${id}.json`);
+	}
+
+	get classificationFile(): string {
+		return this.file("classification.json");
+	}
+
+	get manifestFile(): string {
+		return this.file("manifest.json");
+	}
+
+	get candidatesFile(): string {
+		return this.file("candidates.json");
+	}
+
+	get reviewFile(): string {
+		return this.file("review.md");
+	}
+
+	get stateFile(): string {
+		return this.file(STATE_FILE);
+	}
+
+	get runStatusFile(): string {
+		return this.file(RUN_STATUS_FILE);
+	}
+
+	get verifyFile(): string {
+		return this.file(VERIFY_FILE);
+	}
+
+	/** Relatório isolado de um watchdog (`review.<id>.md`). */
+	domainReportFile(id: string): string {
+		return this.file(`review.${sanitizeBranch(id)}.md`);
+	}
+
+	get contextPaths(): ContextPaths {
+		return {
+			dir: this.outDir,
+			context: this.file(CONTEXT_FILE),
+			summary: this.file(CONTEXT_SUMMARY_FILE),
+			brief: this.file(CONTEXT_BRIEF_FILE),
+		};
+	}
+}

package/src/core/run-status.ts

@@ -9,11 +9,12 @@
  * 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 { ProjectFiles } from "./services/project-files";
 
 /** Estados de execução de uma run (persistidos). */
 export type RunStatus = "reviewing" | "review_done" | "fixing" | "fix_done";
@@ -47,13 +48,7 @@ export function runStatusPath(runDir: string): string {
 
 /** 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;
-	}
+	return new ProjectFiles().readJson<RunStatusFile>(runStatusPath(runDir));
 }
 
 export type WriteRunStatusOptions = {
@@ -69,7 +64,8 @@ export function writeRunStatus(
 	runDir: string,
 	options: WriteRunStatusOptions,
 ): RunStatusFile {
-	const now = options.now ?? new Date().toISOString();
+	const files = new ProjectFiles();
+	const now = options.now ?? systemClock();
 	const previous = readRunStatus(runDir);
 	const file: RunStatusFile = {
 		version: RUN_STATUS_VERSION,
@@ -79,8 +75,7 @@ export function writeRunStatus(
 		startedAt: options.resetStartedAt ? now : (previous?.startedAt ?? now),
 		updatedAt: now,
 	};
-	mkdirSync(runDir, { recursive: true });
-	writeFileSync(runStatusPath(runDir), `${JSON.stringify(file, null, 2)}\n`);
+	files.write(runStatusPath(runDir), `${JSON.stringify(file, null, 2)}\n`);
 	return file;
 }
 

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,123 @@
+/**
+ * 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;
+	}
+
+	/**
+	 * `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,79 @@
+/**
+ * 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, 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 });
+	}
+
+	/** `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);
+	}
+}

package/src/core/services/verifier.ts

@@ -0,0 +1,58 @@
+/**
+ * Verificação de findings (biblioteca) — superfície OO sobre `verify.ts`.
+ *
+ * O tier local (âncora de conteúdo) e o tier Jev continuam em funções puras; a
+ * classe concentra a sequência usada pelo comando `findings verify`.
+ */
+
+import type {
+	FileReader,
+	FindingState,
+	FindingsFilter,
+	FindingsStateFile,
+} from "../findings-state";
+import {
+	applyJev,
+	applyResolutions,
+	selectVerifiable,
+	summarizeVerify,
+	type VerifyEntry,
+	type VerifySummary,
+	verifyLocal,
+} from "../verify";
+
+/** Encadeia seleção, tier local, confirmação Jev e persistência. */
+export class Verifier {
+	/** Fila de verificação (presentes, sem `ignore`). */
+	select(state: FindingsStateFile, filter: FindingsFilter = {}): FindingState[] {
+		return selectVerifiable(state, filter);
+	}
+
+	/** Tier 0 — checagem local por reancoragem de conteúdo. */
+	verifyLocal(findings: readonly FindingState[], readFile: FileReader): VerifyEntry[] {
+		return verifyLocal(findings, readFile);
+	}
+
+	/** Tier 1 — aplica a confirmação do Jev aos casos ambíguos. */
+	applyJev(
+		entries: VerifyEntry[],
+		confidence: Map<string, number>,
+		threshold: number,
+	): number {
+		return applyJev(entries, confidence, threshold);
+	}
+
+	/** Contagem por status. */
+	summarize(entries: readonly VerifyEntry[]): VerifySummary {
+		return summarizeVerify(entries);
+	}
+
+	/** Persiste os `resolved` como `done`. */
+	applyResolutions(
+		state: FindingsStateFile,
+		entries: readonly VerifyEntry[],
+		now?: string,
+	): string[] {
+		return applyResolutions(state, entries, now);
+	}
+}

package/src/core/verify.ts

@@ -19,6 +19,7 @@ import {
 	type FindingsStateFile,
 	filterFindings,
 } from "./findings-state";
+import { systemClock } from "./services/clock";
 import type { Severity } from "./types";
 
 /** Resultado da verificação de um finding. */
@@ -160,7 +161,7 @@ export function summarizeVerify(entries: readonly VerifyEntry[]): VerifySummary
 export function applyResolutions(
 	state: FindingsStateFile,
 	entries: readonly VerifyEntry[],
-	now: string = new Date().toISOString(),
+	now: string = systemClock(),
 ): string[] {
 	const changed: string[] = [];
 	for (const entry of entries) {