@payconductor/houndsman 0.1.4 → 0.3.0

package/src/core/findings-state.ts

@@ -11,8 +11,8 @@
  */
 
 import { randomUUID } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
 import {
 	buildAnchor,
 	type FindingAnchor,
@@ -20,7 +20,6 @@ import {
 	locateAnchor,
 	reanchor,
 } from "./finding-anchor";
-import { STATE_FILE } from "./paths";
 import {
 	dedupeFindings,
 	type MergedFinding,
@@ -28,8 +27,13 @@ import {
 	sanitizeBranch,
 	type WatchdogReport,
 } from "./report-builder";
+import { RunLayout } from "./run-layout";
+import { systemClock } from "./services/clock";
+import { type FileReader, ProjectFiles } from "./services/project-files";
 import { SEVERITY_ORDER, type Severity, severityRank } from "./types";
 
+export type { FileReader };
+
 // ---------------------------------------------------------------------------
 // Tipos
 // ---------------------------------------------------------------------------
@@ -67,6 +71,22 @@ export type FindingHistoryEntry = {
 	by?: string;
 };
 
+/**
+ * Vínculo com o comentário remoto no GitHub (envio da revisão). Gravado pelo
+ * `findings submit` / UI — permite pular reenvios e abrir o comentário.
+ */
+export type GitHubLink = {
+	/** Id do comentário (review comment inline ou issue comment geral). */
+	commentId: number;
+	url?: string;
+	/** Origem do comentário remoto: linha, arquivo ou comentário geral. */
+	kind: "line" | "file" | "comment";
+	/** Número da PR de destino. */
+	pr: number;
+	/** Quando foi enviado (ISO). */
+	at: string;
+};
+
 /** Marco da revisão que originou o estado: commit revisado + quando. */
 export type FindingsReviewed = {
 	/** SHA do commit revisado (head do diff no `--finalize`). */
@@ -99,6 +119,8 @@ export type FindingState = {
 	createdAt: string;
 	updatedAt: string;
 	history: FindingHistoryEntry[];
+	/** Vínculo com o comentário remoto no GitHub (envio da revisão). */
+	github?: GitHubLink;
 };
 
 /** Conteúdo do `state.json`. */
@@ -122,27 +144,17 @@ export const FINDINGS_STATE_VERSION = 2;
 
 /** Diretório de artefatos da run (branch-slug). */
 export function runDir(artifactDir: string, branch: string): string {
-	return join(artifactDir, sanitizeBranch(branch));
+	return new RunLayout(artifactDir, branch).outDir;
 }
 
 /** Caminho do `state.json` da run. */
 export function stateFile(artifactDir: string, branch: string): string {
-	return join(runDir(artifactDir, branch), STATE_FILE);
+	return new RunLayout(artifactDir, branch).stateFile;
 }
 
-/** Leitor de arquivos relativos à raiz do projeto (injetável nos testes). */
-export type FileReader = (relativePath: string) => string | null;
-
 /** Leitor padrão a partir do cwd (null se ausente/ilegível). */
 export function fileReader(cwd: string): FileReader {
-	return (relativePath: string) => {
-		try {
-			const full = join(cwd, relativePath);
-			return existsSync(full) ? readFileSync(full, "utf8") : null;
-		} catch {
-			return null;
-		}
-	};
+	return new ProjectFiles(cwd).reader();
 }
 
 /** Id curto aleatório (hex) para um finding novo. */
@@ -156,7 +168,7 @@ export function emptyState(branch: string): FindingsStateFile {
 		version: FINDINGS_STATE_VERSION,
 		branch,
 		slug: sanitizeBranch(branch),
-		updatedAt: new Date().toISOString(),
+		updatedAt: systemClock(),
 		order: [],
 		findings: {},
 	};
@@ -279,7 +291,7 @@ export function buildStateFromFindings(
 	merged: readonly MergedFinding[],
 	options: BuildStateOptions,
 ): FindingsStateFile {
-	const now = options.now ?? new Date().toISOString();
+	const now = options.now ?? systemClock();
 	const previous = options.previous ?? null;
 
 	const result: Record<string, FindingState> = {};
@@ -345,6 +357,7 @@ export function buildStateFromFindings(
 			createdAt: prev?.createdAt ?? now,
 			updatedAt: now,
 			history: prev?.history ?? [],
+			github: prev?.github,
 		};
 		byFingerprint.set(fingerprint, created);
 		result[created.id] = created;
@@ -418,7 +431,7 @@ export type FindingUpdate = {
 export function applyFindingUpdate(
 	finding: FindingState,
 	update: FindingUpdate,
-	now: string = new Date().toISOString(),
+	now: string = systemClock(),
 ): FindingState {
 	if (update.decision && DECISION_SET.has(update.decision)) {
 		finding.decision = update.decision;
@@ -452,7 +465,7 @@ export type SyncResult = {
 export function syncState(
 	state: FindingsStateFile,
 	readFile: FileReader,
-	now: string = new Date().toISOString(),
+	now: string = systemClock(),
 ): SyncResult {
 	const moved: string[] = [];
 	const stale: string[] = [];
@@ -502,22 +515,165 @@ export function occurrenceCount(
 }
 
 // ---------------------------------------------------------------------------
-// Store (I/O atômico)
+// Domínio (classes)
+// ---------------------------------------------------------------------------
+
+/** Um finding triável, com comportamento sobre o DTO serializável. */
+export class Finding {
+	readonly state: FindingState;
+
+	constructor(state: FindingState) {
+		this.state = state;
+	}
+
+	static from(state: FindingState): Finding {
+		return new Finding(state);
+	}
+
+	get id(): string {
+		return this.state.id;
+	}
+
+	get file(): string {
+		return this.state.file;
+	}
+
+	get line(): number | null {
+		return this.state.line;
+	}
+
+	get severity(): Severity {
+		return this.state.severity;
+	}
+
+	get decision(): FindingDecision {
+		return this.state.decision;
+	}
+
+	get execState(): FindingExecState {
+		return this.state.execState;
+	}
+
+	get present(): boolean {
+		return this.state.present;
+	}
+
+	get isDone(): boolean {
+		return this.state.execState === "done";
+	}
+
+	/** Aplica uma atualização (com histórico) e devolve o próprio finding. */
+	apply(update: FindingUpdate, now: string = systemClock()): Finding {
+		applyFindingUpdate(this.state, update, now);
+		return this;
+	}
+
+	/** Payload serializável (mesmo shape do `state.json`). */
+	toJSON(): FindingState {
+		return this.state;
+	}
+}
+
+/** Coleção de triagem de uma run — superfície OO sobre o `state.json`. */
+export class FindingsState {
+	readonly file: FindingsStateFile;
+
+	constructor(file: FindingsStateFile) {
+		this.file = file;
+	}
+
+	static from(file: FindingsStateFile): FindingsState {
+		return new FindingsState(file);
+	}
+
+	static empty(branch: string): FindingsState {
+		return new FindingsState(emptyState(branch));
+	}
+
+	get branch(): string {
+		return this.file.branch;
+	}
+
+	get reviewed(): FindingsReviewed | undefined {
+		return this.file.reviewed;
+	}
+
+	/** Findings na ordem de exibição (`order`). */
+	list(): Finding[] {
+		return this.file.order
+			.map((id) => this.file.findings[id])
+			.filter((state): state is FindingState => Boolean(state))
+			.map((state) => Finding.from(state));
+	}
+
+	/** Busca por id. */
+	get(id: string): Finding | null {
+		const state = this.file.findings[id];
+		return state ? Finding.from(state) : null;
+	}
+
+	/** Todos os findings (ordem de inserção, sem o `order`). */
+	values(): Finding[] {
+		return Object.values(this.file.findings).map((state) => Finding.from(state));
+	}
+
+	/** Somente os presentes no último relatório. */
+	present(): Finding[] {
+		return this.values().filter((finding) => finding.present);
+	}
+
+	/** Filtra pela ordem canônica (presentes → severidade → arquivo → linha). */
+	filter(filter: FindingsFilter = {}): Finding[] {
+		return filterFindings(this.file, filter).map((state) => Finding.from(state));
+	}
+
+	/** Contagens por decisão, execução e severidade. */
+	summarize(): FindingsSummary {
+		return summarize(this.file);
+	}
+
+	/** Reordena os ids pela ordenação canônica. */
+	reorder(): void {
+		reorder(this.file);
+	}
+
+	/** Aplica uma atualização a um finding e devolve-o (null se ausente). */
+	apply(id: string, update: FindingUpdate, now?: string): Finding | null {
+		const state = this.file.findings[id];
+		if (!state) return null;
+		applyFindingUpdate(state, update, now);
+		return Finding.from(state);
+	}
+
+	/** Reancora os presentes contra os arquivos atuais. */
+	sync(readFile: FileReader, now?: string): SyncResult {
+		return syncState(this.file, readFile, now);
+	}
+
+	/** Payload serializável (mesmo shape do `state.json`). */
+	toJSON(): FindingsStateFile {
+		return this.file;
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Repository (I/O atômico)
 // ---------------------------------------------------------------------------
 
 /** Persistência do `state.json` — escrita atômica (tmp + rename). */
-export class FindingsStateStore {
+export class FindingsRepository {
 	private readonly path: string;
 	private readonly branch: string;
+	private readonly files = new ProjectFiles();
 
 	constructor(path: string, branch: string) {
 		this.path = path;
 		this.branch = branch;
 	}
 
-	/** Store para a run de uma branch. */
-	static at(artifactDir: string, branch: string): FindingsStateStore {
-		return new FindingsStateStore(stateFile(artifactDir, branch), branch);
+	/** Repository para a run de uma branch. */
+	static at(artifactDir: string, branch: string): FindingsRepository {
+		return new FindingsRepository(stateFile(artifactDir, branch), branch);
 	}
 
 	get filePath(): string {
@@ -526,31 +682,26 @@ export class FindingsStateStore {
 
 	/** Lê o estado; null se ausente/inválido. */
 	read(): FindingsStateFile | null {
-		if (!existsSync(this.path)) return null;
-		try {
-			const raw = JSON.parse(readFileSync(this.path, "utf8")) as FindingsStateFile;
-			if (raw?.version !== FINDINGS_STATE_VERSION || !raw.findings) return null;
-			return raw;
-		} catch {
-			return null;
-		}
+		const raw = this.files.readJson<FindingsStateFile>(this.path);
+		if (!raw || raw.version !== FINDINGS_STATE_VERSION || !raw.findings) return null;
+		return raw;
 	}
 
 	/** Grava o estado de forma atômica. */
 	write(state: FindingsStateFile): void {
-		mkdirSync(dirname(this.path), { recursive: true });
-		const tmp = `${this.path}.${process.pid}.tmp`;
-		writeFileSync(tmp, `${JSON.stringify(state, null, 2)}\n`);
-		renameSync(tmp, this.path);
+		this.files.writeAtomic(this.path, `${JSON.stringify(state, null, 2)}\n`);
 	}
 
 	/** Lê-modifica-grava; parte de um estado vazio se não existir. */
 	update(mutator: (state: FindingsStateFile) => void): FindingsStateFile {
 		const state = this.read() ?? emptyState(this.branch);
 		mutator(state);
-		state.updatedAt = new Date().toISOString();
+		state.updatedAt = systemClock();
 		reorder(state);
 		this.write(state);
 		return state;
 	}
 }
+
+/** Nome anterior do repository (compatibilidade da API pública). */
+export { FindingsRepository as FindingsStateStore };

package/src/core/git-revision.ts

@@ -11,31 +11,20 @@
  * (`parseEntries`) — não reimplementa leitura de diff.
  */
 
-import {
-	DEFAULT_MAX_PER_FILE_CHARS,
-	type DiffSource,
-	parseDiffIndex,
-	parseNumstat,
-} from "./diff-source";
+import { DEFAULT_MAX_PER_FILE_CHARS, type DiffSource } from "./diff-source";
 import { parseEntries } from "./file-classifier";
+import { runGit } from "./git-runner";
+import { GitRepository } from "./services/git-repository";
 import type { FileChurn } from "./types";
 
-/** Executa `git` (paths literais) e devolve o stdout; lança se falhar. */
-export 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);
-}
+export { runGit };
+
+/** Repositório padrão (runner real) usado pelos helpers funcionais. */
+const git = new GitRepository();
 
 /** SHA completo de uma ref (`git rev-parse`). Lança se a ref não resolver. */
 export function resolveSha(ref: string): string {
-	return runGit(["rev-parse", ref]).trim();
+	return git.resolveSha(ref);
 }
 
 /** SHA do commit atual (`HEAD`). */
@@ -50,31 +39,22 @@ export function currentHeadSha(): string {
  * comportamento seguro.
  */
 export function isAncestor(ancestor: string, descendant: string): boolean {
-	const result = Bun.spawnSync(
-		["git", "merge-base", "--is-ancestor", ancestor, descendant],
-		{ stdout: "ignore", stderr: "ignore" },
-	);
-	return result.exitCode === 0;
+	return git.isAncestor(ancestor, descendant);
 }
 
 /** Conteúdo de um arquivo num commit (`git show sha:path`); null se ausente. */
 export function readFileAt(sha: string, path: string): string | null {
-	const result = Bun.spawnSync(
-		["git", "-c", "core.quotepath=false", "show", `${sha}:${path}`],
-		{ stdout: "pipe", stderr: "ignore" },
-	);
-	if (result.exitCode !== 0) return null;
-	return new TextDecoder().decode(result.stdout);
+	return git.readFileAt(sha, path);
 }
 
 /** Arquivos alterados num intervalo (`git diff range --name-status`). */
 export function diffEntries(range: string): ReturnType<typeof parseEntries> {
-	return parseEntries(runGit(["diff", range, "--name-status"]));
+	return parseEntries(git.run(["diff", range, "--name-status"]));
 }
 
 /** Churn por arquivo de um intervalo (`git diff --numstat -z range`). */
 export function diffNumstat(range: string): Map<string, FileChurn> {
-	return parseNumstat(runGit(["diff", "--numstat", "-z", range]));
+	return git.diffNumstat(range);
 }
 
 /**
@@ -86,9 +66,7 @@ export function diffPatch(
 	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(runGit(args), maxPerFileChars);
+	return git.diffPatch(range, paths, maxPerFileChars);
 }
 
 /** Diff (patch + churn) de `from..to` — 2 spawns, base do review incremental. */
@@ -97,9 +75,5 @@ export function collectDiffSince(
 	to: string,
 	maxPerFileChars: number = DEFAULT_MAX_PER_FILE_CHARS,
 ): DiffSource {
-	const range = `${from}..${to}`;
-	return {
-		byFile: parseDiffIndex(runGit(["diff", range]), maxPerFileChars),
-		churn: diffNumstat(range),
-	};
+	return git.collectDiffSince(from, to, maxPerFileChars);
 }

package/src/core/git-runner.ts

@@ -0,0 +1,46 @@
+/**
+ * Execução do binário `git` (biblioteca) — única camada que fala com o processo.
+ *
+ * `core.quotepath=false` mantém paths literais (acentos/unicode). O runner é
+ * injetável nos testes; `GitRepository` é a superfície OO sobre estes helpers.
+ */
+
+/** Resultado cru de uma execução do git (nunca lança). */
+export type GitResult = {
+	ok: boolean;
+	code: number;
+	stdout: string;
+	stderr: string;
+};
+
+/** Executa `git` e devolve o resultado cru. Injetável nos testes. */
+export type GitRunner = (args: string[]) => GitResult;
+
+/** Runner padrão: `git -c core.quotepath=false <args>` a partir do cwd. */
+export const defaultGitRunner: GitRunner = (args) => {
+	const result = Bun.spawnSync(["git", "-c", "core.quotepath=false", ...args], {
+		stdout: "pipe",
+		stderr: "pipe",
+	});
+	const code = result.exitCode ?? 1;
+	return {
+		ok: code === 0,
+		code,
+		stdout: new TextDecoder().decode(result.stdout),
+		stderr: new TextDecoder().decode(result.stderr),
+	};
+};
+
+/** Executa e devolve o stdout; lança com o stderr quando o git falha. */
+export function runGit(args: string[], runner: GitRunner = defaultGitRunner): string {
+	const result = runner(args);
+	if (!result.ok) {
+		throw new Error(`git ${args.join(" ")} falhou: ${result.stderr.trim()}`);
+	}
+	return result.stdout;
+}
+
+/** Executa o git sem lançar (para sondagens como `merge-base`/`show`). */
+export function tryGit(args: string[], runner: GitRunner = defaultGitRunner): GitResult {
+	return runner(args);
+}