@payconductor/houndsman 0.4.0 → 0.5.0

package/src/tests/review-resume.test.ts

@@ -0,0 +1,101 @@
+/**
+ * Resumo final (`review-resume.md`) — conteúdo de negócio + pontos técnicos,
+ * determinístico e limitado a `RESUME_MAX_CHARS`.
+ */
+
+import { describe, expect, test } from "bun:test";
+import {
+	RESUME_MAX_CHARS,
+	type ResumeClassification,
+	renderReviewResume,
+} from "../core/renderers/resume-renderer";
+import type { MergedFinding } from "../core/report-builder";
+
+function finding(overrides: Partial<MergedFinding> = {}): MergedFinding {
+	return {
+		rule: "regra",
+		severity: "suggestion",
+		file: "src/a.ts",
+		line: 1,
+		message: "mensagem",
+		action: "ação",
+		watchdogs: ["alpha"],
+		...overrides,
+	};
+}
+
+const classification: ResumeClassification = {
+	files: {
+		"src/a.ts": { status: "modified" },
+		"src/b.ts": { status: "added" },
+	},
+	watchdogs: { alpha: ["src/a.ts"], beta: ["src/b.ts"] },
+};
+
+describe("renderReviewResume", () => {
+	test("une contexto de negócio e pontos técnicos", () => {
+		const md = renderReviewResume({
+			branch: "feat/x",
+			date: "2026-10-17",
+			context: {
+				available: true,
+				objective: "Entregar a feature X.",
+				motivation: "Reduzir o esforço manual.",
+				changeSummary: ["Novo fluxo de cadastro.", "Ajuste no relatório."],
+			},
+			classification,
+			findings: [
+				finding({ severity: "blocking", message: "quebra o cadastro" }),
+				finding({ severity: "attention", file: "src/b.ts", line: undefined }),
+			],
+			nameOf: (id) => id.toUpperCase(),
+		});
+
+		expect(md).toContain("# Resumo da revisão — feat/x");
+		expect(md).toContain("**Data:** 2026-10-17");
+		expect(md).toContain("❌ Mudanças necessárias");
+		expect(md).toContain("Entregar a feature X.");
+		expect(md).toContain("**Por quê:** Reduzir o esforço manual.");
+		expect(md).toContain("- Novo fluxo de cadastro.");
+		expect(md).not.toContain("## Números");
+		expect(md).toContain("`src/a.ts:1` — quebra o cadastro _(ALPHA)_");
+		expect(md).toContain("`src/b.ts` — mensagem _(ALPHA)_");
+		expect(md.length).toBeLessThanOrEqual(RESUME_MAX_CHARS);
+	});
+
+	test("sem contexto da PR, cai no alcance da branch", () => {
+		const md = renderReviewResume({
+			branch: "main",
+			classification,
+			findings: [],
+		});
+
+		expect(md).toContain("Sem resumo de contexto da PR disponível.");
+		expect(md).toContain("✅ Aprovado");
+		expect(md).toContain("- Nenhum bloqueio ou ponto de atenção.");
+	});
+
+	test("respeita o teto de caracteres", () => {
+		const findings = Array.from({ length: 40 }, (_, index) =>
+			finding({
+				severity: index % 2 === 0 ? "blocking" : "attention",
+				file: `src/very/long/path/file-${index}.ts`,
+				message: "x".repeat(300),
+			}),
+		);
+		const md = renderReviewResume({
+			branch: "main",
+			context: {
+				available: true,
+				objective: "o".repeat(1000),
+				motivation: "m".repeat(1000),
+				changeSummary: ["a".repeat(200), "b".repeat(200)],
+			},
+			classification,
+			findings,
+		});
+
+		expect(md.length).toBeLessThanOrEqual(RESUME_MAX_CHARS);
+		expect(md.endsWith("…")).toBe(true);
+	});
+});

package/src/tests/review-scope.test.ts

@@ -0,0 +1,302 @@
+/**
+ * Escopo do review: completo × incremental × no-op.
+ *
+ * Congela a decisão que evita re-revisar a PR inteira: mesmo commit revisado
+ * vira no-op (sem `--full`/`--clean`), delta vira incremental com carry-over.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { ReviewScopeResolver, type ScopeOptions } from "../core/engine/review-scope";
+import type { FindingState, FindingsStateFile } from "../core/findings-state";
+import { defaultOptions, finalize, prepare, reviewContext } from "../core/orchestrator";
+import { resolveRepoIdentity } from "../core/storage/repo-identity";
+import { SQLiteStorageProvider } from "../core/storage/sqlite/sqlite-storage";
+import { fakeHoundsmanConfig } from "./fixtures/fake-project";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function findingState(overrides: Partial<FindingState> = {}): FindingState {
+	return {
+		id: "abcdef1234",
+		fingerprint: "0123456789abcdef",
+		watchdogIds: ["alpha"],
+		rule: "regra",
+		severity: "blocking",
+		file: "src/alpha/keep.ts",
+		line: 1,
+		message: "mensagem",
+		action: "ação",
+		anchor: null,
+		count: 1,
+		present: true,
+		decision: "pending",
+		execState: "pending",
+		createdAt: "2026-01-01T00:00:00.000Z",
+		updatedAt: "2026-01-01T00:00:00.000Z",
+		history: [],
+		...overrides,
+	};
+}
+
+function stateWith(
+	reviewedSha: string,
+	findings: Record<string, FindingState> = {},
+): FindingsStateFile {
+	return {
+		version: 2,
+		branch: "main",
+		slug: "main",
+		updatedAt: "2026-01-01T00:00:00.000Z",
+		order: Object.keys(findings),
+		reviewed: { headSha: reviewedSha, at: "2026-01-01T00:00:00.000Z" },
+		findings,
+	};
+}
+
+function options(overrides: Partial<ScopeOptions> = {}): ScopeOptions {
+	return { base: "main", head: "HEAD", full: false, clean: false, ...overrides };
+}
+
+function git(cwd: string, args: string[]): string {
+	const result = Bun.spawnSync(["git", ...args], {
+		cwd,
+		stdout: "pipe",
+		stderr: "pipe",
+	});
+	if (result.exitCode !== 0) {
+		throw new Error(`git ${args.join(" ")}: ${result.stderr.toString()}`);
+	}
+	return result.stdout.toString();
+}
+
+type Repo = { cwd: string; base: string; head: string; cleanup: () => void };
+
+/** Repositório temporário: `base` → `head` altera `src/alpha/a.ts`. */
+function makeRepo(): Repo {
+	const cwd = mkdtempSync(join(tmpdir(), "houndsman-scope-"));
+	git(cwd, ["init", "-b", "main"]);
+	git(cwd, ["config", "user.email", "scope@example.test"]);
+	git(cwd, ["config", "user.name", "Scope"]);
+	git(cwd, ["config", "commit.gpgsign", "false"]);
+	git(cwd, ["config", "tag.gpgsign", "false"]);
+
+	mkdirSync(join(cwd, "src", "alpha"), { recursive: true });
+	writeFileSync(join(cwd, "src", "alpha", "a.ts"), "export const a = 1;\n");
+	writeFileSync(join(cwd, "src", "alpha", "keep.ts"), "export const keep = 1;\n");
+	writeFileSync(join(cwd, "README.md"), "# Fake\n");
+	git(cwd, ["add", "."]);
+	git(cwd, ["commit", "-m", "initial"]);
+	const base = git(cwd, ["rev-parse", "HEAD"]).trim();
+
+	writeFileSync(join(cwd, "src", "alpha", "a.ts"), "export const a = 2;\n");
+	git(cwd, ["add", "-A"]);
+	git(cwd, ["commit", "-m", "change"]);
+	const head = git(cwd, ["rev-parse", "HEAD"]).trim();
+
+	return {
+		cwd,
+		base,
+		head,
+		cleanup: () => rmSync(cwd, { recursive: true, force: true }),
+	};
+}
+
+// ---------------------------------------------------------------------------
+// Decisão de escopo
+// ---------------------------------------------------------------------------
+
+describe("ReviewScopeResolver", () => {
+	test("mesmo commit revisado vira no-op (sem tocar no git)", () => {
+		const sha = "a".repeat(40);
+		const scope = new ReviewScopeResolver(options(), fakeHoundsmanConfig).resolve(
+			stateWith(sha),
+			sha,
+		);
+
+		expect(scope.kind).toBe("noop");
+		if (scope.kind !== "noop") throw new Error("esperava noop");
+		expect(scope.reviewedFrom).toBe(sha);
+		expect(scope.headSha).toBe(sha);
+	});
+
+	test("`--full` re-revisa o mesmo commit", () => {
+		const repo = makeRepo();
+		const originalCwd = process.cwd();
+		try {
+			process.chdir(repo.cwd);
+			const scope = new ReviewScopeResolver(
+				options({ base: repo.base, full: true }),
+				fakeHoundsmanConfig,
+			).resolve(stateWith(repo.head), repo.head);
+
+			expect(scope.kind).toBe("review");
+			if (scope.kind !== "review") throw new Error("esperava review");
+			expect(scope.classification.mode).toBe("full");
+			expect(scope.classification.headSha).toBe(repo.head);
+		} finally {
+			process.chdir(originalCwd);
+			repo.cleanup();
+		}
+	});
+
+	test("delta revisa só os arquivos alterados e carrega o resto", () => {
+		const repo = makeRepo();
+		const originalCwd = process.cwd();
+		try {
+			process.chdir(repo.cwd);
+			const previous = stateWith(repo.base, {
+				abcdef1234: findingState({ file: "src/alpha/keep.ts" }),
+				fedcba4321: findingState({ file: "src/alpha/a.ts" }),
+			});
+			const scope = new ReviewScopeResolver(
+				options({ base: repo.base }),
+				fakeHoundsmanConfig,
+			).resolve(previous, repo.head);
+
+			expect(scope.kind).toBe("review");
+			if (scope.kind !== "review") throw new Error("esperava review");
+			expect(scope.classification.mode).toBe("incremental");
+			expect(scope.classification.reviewedFrom).toBe(repo.base);
+			expect(Object.keys(scope.classification.files)).toEqual(["src/alpha/a.ts"]);
+			expect(scope.classification.carryover?.map((f) => f.file)).toEqual([
+				"src/alpha/keep.ts",
+			]);
+		} finally {
+			process.chdir(originalCwd);
+			repo.cleanup();
+		}
+	});
+
+	test("histórico reescrito (HEAD sem ancestrais comuns) cai no completo", () => {
+		const repo = makeRepo();
+		const originalCwd = process.cwd();
+		try {
+			process.chdir(repo.cwd);
+			// `repo.head` não é ancestral de `repo.base` → revisão completa.
+			const scope = new ReviewScopeResolver(
+				options({ base: repo.base }),
+				fakeHoundsmanConfig,
+			).resolve(stateWith(repo.head), repo.base);
+
+			expect(scope.kind).toBe("review");
+			if (scope.kind !== "review") throw new Error("esperava review");
+			expect(scope.classification.mode).toBe("full");
+		} finally {
+			process.chdir(originalCwd);
+			repo.cleanup();
+		}
+	});
+});
+
+// ---------------------------------------------------------------------------
+// Integração: prepare/finalize no mesmo commit
+// ---------------------------------------------------------------------------
+
+describe("prepare/finalize — mesmo commit", () => {
+	test("no-op preserva relatório e não gera briefs", async () => {
+		const repo = makeRepo();
+		const originalCwd = process.cwd();
+		const originalHome = process.env.HOUNDSMAN_HOME;
+		let storage: SQLiteStorageProvider | null = null;
+
+		try {
+			process.env.HOUNDSMAN_HOME = join(repo.cwd, ".home");
+			process.chdir(repo.cwd);
+
+			storage = new SQLiteStorageProvider(join(repo.cwd, "houndsman.db"));
+			const record = storage.getOrCreateReview({
+				repo: resolveRepoIdentity(),
+				branch: "main",
+				slug: "main",
+			});
+			const opts = {
+				...defaultOptions(),
+				base: repo.base,
+				head: "HEAD",
+				noJev: true,
+			};
+
+			let ctx = reviewContext(storage, record);
+			await prepare(opts, "main", fakeHoundsmanConfig, ctx);
+			expect(storage.getReview(record.id)?.status).toBe("reviewing");
+
+			writeFileSync(
+				ctx.work.findingFile("alpha"),
+				`${JSON.stringify(
+					{
+						watchdogId: "alpha",
+						reviewedFiles: ["src/alpha/a.ts"],
+						skipped: [],
+						findings: [
+							{
+								rule: "regra",
+								severity: "blocking",
+								file: "src/alpha/a.ts",
+								line: 1,
+								message: "achado",
+								action: "corrigir",
+							},
+						],
+					},
+					null,
+					2,
+				)}\n`,
+			);
+			finalize(opts, "main", fakeHoundsmanConfig, ctx);
+
+			const classificationBefore = storage.readArtifact(
+				record.id,
+				"classification.json",
+			)?.content;
+			const reportBefore = storage.readArtifact(record.id, "review.md")?.content;
+			const findingsBefore = JSON.stringify(
+				storage.readFindings(record.id)?.findings,
+			);
+			const reviewedBefore = storage.getReview(record.id)?.reviewedSha;
+			expect(classificationBefore).toBeTruthy();
+			expect(reportBefore).toContain("src/alpha/a.ts");
+
+			// Mesmo commit: prepare vira no-op e nada é reescrito.
+			ctx = reviewContext(storage, storage.getReview(record.id) ?? record);
+			const again = await prepare(opts, "main", fakeHoundsmanConfig, ctx);
+			expect(again.messages.join("\n")).toContain(
+				"Nenhuma alteração desde a última revisão",
+			);
+			expect(storage.readArtifact(record.id, "classification.json")?.content).toBe(
+				classificationBefore,
+			);
+			expect(storage.readArtifact(record.id, "review.md")?.content).toBe(
+				reportBefore,
+			);
+			expect(storage.getReview(record.id)?.status).toBe("review_done");
+			expect(existsSync(ctx.work.briefFile("alpha"))).toBe(false);
+
+			// Finalize sem ciclo preparado: no-op (não degrada o relatório).
+			const finalizedAgain = finalize(
+				opts,
+				"main",
+				fakeHoundsmanConfig,
+				reviewContext(storage, storage.getReview(record.id) ?? record),
+			);
+			expect(finalizedAgain.messages.join("\n")).toContain("Nada a finalizar");
+			expect(storage.readArtifact(record.id, "review.md")?.content).toBe(
+				reportBefore,
+			);
+			expect(JSON.stringify(storage.readFindings(record.id)?.findings)).toBe(
+				findingsBefore,
+			);
+			expect(storage.getReview(record.id)?.reviewedSha).toBe(reviewedBefore);
+		} finally {
+			storage?.close();
+			process.chdir(originalCwd);
+			if (originalHome === undefined) delete process.env.HOUNDSMAN_HOME;
+			else process.env.HOUNDSMAN_HOME = originalHome;
+			repo.cleanup();
+		}
+	}, 30_000);
+});

package/src/tests/review-scripts.test.ts

@@ -673,6 +673,79 @@ describe("report-builder", () => {
 		expect(md).toContain("review.alpha.md");
 	});
 
+	test("renderReport coloca o sumário antes dos achados", () => {
+		const md = renderReport(
+			"main",
+			[{ watchdogId: "alpha", reviewedFiles: ["a.ts"], skipped: [], findings: [] }],
+			[
+				{
+					rule: "R1",
+					severity: "blocking" as const,
+					file: "a.ts",
+					line: 1,
+					message: "m",
+					action: "a",
+					watchdogs: ["alpha"],
+				},
+			],
+			{ classified: { alpha: ["a.ts"] } },
+			null,
+			undefined,
+			undefined,
+			[
+				{
+					id: "alpha",
+					name: "Alpha",
+					file: "review.alpha.md",
+					findings: 1,
+					reviewedFiles: 1,
+					expectedFiles: 1,
+				},
+			],
+		);
+		const sections = [
+			"## Relatórios por domínio",
+			"## Cobertura",
+			"## Conclusão",
+			"## ❌ blocking",
+		].map((section) => md.indexOf(section));
+		expect(sections.every((index) => index >= 0)).toBe(true);
+		expect([...sections].sort((a, b) => a - b)).toEqual(sections);
+	});
+
+	test("renderReport anexa candidatos Jev depois dos achados", () => {
+		const md = renderReport(
+			"main",
+			[{ watchdogId: "alpha", reviewedFiles: [], skipped: [], findings: [] }],
+			[
+				{
+					rule: "R1",
+					severity: "blocking" as const,
+					file: "a.ts",
+					line: 1,
+					message: "m",
+					action: "a",
+					watchdogs: ["alpha"],
+				},
+			],
+			{},
+			null,
+			[
+				{
+					watchdogId: "alpha",
+					rule: "R2",
+					severity: "attention",
+					file: "b.ts",
+					confidence: 0.6,
+					questionKey: "q",
+				},
+			],
+		);
+		expect(md.indexOf("## ❌ blocking")).toBeLessThan(
+			md.indexOf("## 🔎 Candidatos não verificados"),
+		);
+	});
+
 	test("renderDomainReport mostra cobertura e não revisados", () => {
 		const md = renderDomainReport(
 			"main",

package/src/tests/run-status-view.test.ts

@@ -0,0 +1,94 @@
+/**
+ * View do status na sidebar — timeout só vale quando há heartbeat de execução.
+ * `updatedAt` (triagem/sync) não deve simular uma revisão em andamento.
+ */
+
+import { describe, expect, test } from "bun:test";
+import {
+	describeRunStatus,
+	REVIEW_TIMEOUT_MS,
+	STATUS_TIMEOUT_MS,
+} from "../server/client/utils/constants";
+import type { RunSummary, Summary } from "../server/client/utils/types";
+
+const summary: Summary = {
+	total: 0,
+	present: 0,
+	byDecision: { pending: 0, execute: 0, ignore: 0 },
+	byExecState: { pending: 0, in_progress: 0, done: 0, stale: 0 },
+	bySeverity: { blocking: 0, attention: 0, suggestion: 0, nit: 0 },
+};
+
+const NOW = Date.parse("2026-10-17T12:00:00.000Z");
+const iso = (offsetMs: number): string => new Date(NOW + offsetMs).toISOString();
+
+function run(overrides: Partial<RunSummary>): RunSummary {
+	return {
+		slug: "feature-x",
+		branch: "feature/x",
+		summary,
+		...overrides,
+	};
+}
+
+describe("describeRunStatus", () => {
+	test("heartbeat recente mantém o status de execução", () => {
+		expect(
+			describeRunStatus(
+				run({ status: "reviewing", heartbeatAt: iso(-60_000) }),
+				NOW,
+			),
+		).toEqual({ kind: "reviewing", label: "Revisando", timeout: false });
+	});
+
+	test("heartbeat antigo vira timeout", () => {
+		expect(
+			describeRunStatus(
+				run({
+					status: "reviewing",
+					heartbeatAt: iso(-REVIEW_TIMEOUT_MS - 1_000),
+				}),
+				NOW,
+			),
+		).toEqual({ kind: "timeout", label: "Timeout na revisão", timeout: true });
+	});
+
+	test("updatedAt recente não mascara heartbeat antigo", () => {
+		expect(
+			describeRunStatus(
+				run({
+					status: "reviewing",
+					updatedAt: iso(-1_000),
+					heartbeatAt: iso(-REVIEW_TIMEOUT_MS - 1_000),
+				}),
+				NOW,
+			)?.timeout,
+		).toBe(true);
+	});
+
+	test("sem heartbeat não inventa revisão em andamento", () => {
+		expect(
+			describeRunStatus(run({ status: "reviewing", updatedAt: iso(-1_000) }), NOW),
+		).toBeNull();
+	});
+
+	test("status terminal aparece normalmente sem heartbeat", () => {
+		expect(describeRunStatus(run({ status: "review_done" }), NOW)).toEqual({
+			kind: "review_done",
+			label: "Revisão pronta",
+			timeout: false,
+		});
+	});
+
+	test("correção também usa heartbeat para timeout", () => {
+		expect(
+			describeRunStatus(
+				run({
+					status: "fixing",
+					heartbeatAt: iso(-STATUS_TIMEOUT_MS - 1_000),
+				}),
+				NOW,
+			),
+		).toEqual({ kind: "timeout", label: "Timeout na correção", timeout: true });
+	});
+});

package/src/tests/run-status.test.ts

@@ -7,6 +7,7 @@ import {
 	pingFindingsStatus,
 	readRunStatus,
 	statusAfterFindingsChange,
+	touchRunStatus,
 	writeRunStatus,
 } from "../core/run-status";
 import { buildRepoIdentity } from "../core/storage/repo-identity";
@@ -78,6 +79,7 @@ describe("run-status — storage", () => {
 			expect(first?.status).toBe("reviewing");
 			expect(first?.slug).toBe("feature-x");
 			expect(first?.startedAt).toBe("2026-01-01T00:00:00.000Z");
+			expect(first?.heartbeatAt).toBe("2026-01-01T00:00:00.000Z");
 
 			writeRunStatus(storage, reviewId, {
 				status: "review_done",
@@ -86,6 +88,7 @@ describe("run-status — storage", () => {
 			const second = readRunStatus(storage, reviewId);
 			expect(second?.status).toBe("review_done");
 			expect(second?.startedAt).toBe("2026-01-01T00:00:00.000Z");
+			expect(second?.heartbeatAt).toBeUndefined();
 			expect(second?.updatedAt).toBe("2026-01-01T00:10:00.000Z");
 
 			writeRunStatus(storage, reviewId, {
@@ -96,6 +99,56 @@ describe("run-status — storage", () => {
 			expect(readRunStatus(storage, reviewId)?.startedAt).toBe(
 				"2026-01-01T00:20:00.000Z",
 			);
+			expect(readRunStatus(storage, reviewId)?.heartbeatAt).toBe(
+				"2026-01-01T00:20:00.000Z",
+			);
+		});
+	});
+
+	test("touch renova o heartbeat apenas em execução ativa", () => {
+		withStorage((storage, reviewId) => {
+			writeRunStatus(storage, reviewId, {
+				status: "reviewing",
+				resetStartedAt: true,
+				now: "2026-01-01T00:00:00.000Z",
+			});
+			touchRunStatus(storage, reviewId, "2026-01-01T00:05:00.000Z");
+			expect(readRunStatus(storage, reviewId)?.heartbeatAt).toBe(
+				"2026-01-01T00:05:00.000Z",
+			);
+
+			writeRunStatus(storage, reviewId, {
+				status: "review_done",
+				now: "2026-01-01T00:10:00.000Z",
+			});
+			touchRunStatus(storage, reviewId, "2026-01-01T00:15:00.000Z");
+			expect(readRunStatus(storage, reviewId)?.heartbeatAt).toBeUndefined();
+		});
+	});
+
+	test("triagem em reviewing não renova o heartbeat; fix em andamento sim", () => {
+		withStorage((storage, reviewId) => {
+			writeRunStatus(storage, reviewId, {
+				status: "reviewing",
+				resetStartedAt: true,
+				now: "2026-01-01T00:00:00.000Z",
+			});
+
+			// Triagem (decision/comment) mantém reviewing — não é execução.
+			pingFindingsStatus(storage, reviewId, stateOf([]));
+			expect(readRunStatus(storage, reviewId)?.heartbeatAt).toBe(
+				"2026-01-01T00:00:00.000Z",
+			);
+
+			// Correção em andamento renova o heartbeat.
+			pingFindingsStatus(
+				storage,
+				reviewId,
+				stateOf([findingState({ execState: "in_progress" })]),
+			);
+			const fixed = readRunStatus(storage, reviewId);
+			expect(fixed?.status).toBe("fixing");
+			expect(fixed?.heartbeatAt).not.toBe("2026-01-01T00:00:00.000Z");
 		});
 	});