@payconductor/houndsman 0.12.0 → 0.13.0

package/src/tests/hunt-maki.test.ts

@@ -0,0 +1,467 @@
+/**
+ * Harness local — prompt, parser de saída, runner e política de retry.
+ *
+ * Testa o `core/hunt` sem processo real: o `MakiProcessRunner` é injetado.
+ * A execução via `Bun.spawn` é coberta em plataformas POSIX nos testes abaixo.
+ */
+
+import { afterEach, describe, expect, test } from "bun:test";
+import { chmodSync, existsSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { defineHoundsmanConfig } from "../core/config";
+import { type HuntEvent, HuntRunner } from "../core/hunt/hunt-runner";
+import { requireMakiModel, resolveMakiModel } from "../core/hunt/maki-model";
+import { renderHuntPrompt } from "../core/hunt/maki-prompt";
+import {
+	extractJsonObject,
+	MAKI_DISALLOWED_TOOLS,
+	makiArgs,
+	parseMakiOutput,
+	SpawnMakiRunner,
+} from "../core/hunt/maki-runner";
+import { ProjectConfig } from "../core/project-config";
+import type { ReviewRecord } from "../core/storage/types";
+import { ReviewWorkArea } from "../core/storage/work-area";
+import { defineWatchdog } from "../core/types";
+
+const config = defineHoundsmanConfig({
+	projectName: "Hunt Test",
+	watchdogs: {
+		alpha: defineWatchdog({
+			id: "alpha",
+			name: "Alpha",
+			description: "alpha",
+			scope: "src/alpha/**",
+			classify: [{ value: "^src/alpha/" }],
+			rules: [{ severity: "attention", text: "Evitar any." }],
+			contextFiles: [],
+		}),
+		beta: defineWatchdog({
+			id: "beta",
+			name: "Beta",
+			description: "beta",
+			scope: "src/beta/**",
+			classify: [{ value: "^src/beta/" }],
+			rules: [{ severity: "attention", text: "Evitar console.log." }],
+			contextFiles: [],
+		}),
+	},
+	exclusions: [],
+	docMappings: [],
+});
+
+const project = new ProjectConfig(config);
+
+/** Review fake (o staging só precisa de id/branch). */
+function fakeReview(root: string): ReviewRecord {
+	const now = "2026-01-01T00:00:00.000Z";
+	return {
+		id: "review-hunt",
+		repoKey: "repo",
+		repoRoot: root,
+		branch: "main",
+		slug: "main",
+		status: "reviewing",
+		createdAt: now,
+		updatedAt: now,
+	};
+}
+
+/** Staging temporário com briefs prontos. */
+function makeWork(ids: string[]): {
+	root: string;
+	work: ReviewWorkArea;
+	cleanup: () => void;
+} {
+	const root = mkdtempSync(join(tmpdir(), "houndsman-hunt-"));
+	const work = new ReviewWorkArea(fakeReview(root), root);
+	work.ensure();
+	for (const id of ids) work.writeBrief(id, `brief de ${id}`);
+	return { root, work, cleanup: () => rmSync(root, { recursive: true, force: true }) };
+}
+
+function reportJson(watchdogId: string, findings = 1): string {
+	return JSON.stringify({
+		watchdogId,
+		reviewedFiles: [`src/${watchdogId}/a.ts`],
+		skipped: [],
+		findings: Array.from({ length: findings }, (_, index) => ({
+			rule: "Evitar any",
+			severity: "attention",
+			file: `src/${watchdogId}/a.ts`,
+			line: index + 1,
+			message: "any detectado",
+			action: "tipar",
+		})),
+	});
+}
+
+describe("maki — contrato de execução", () => {
+	test("args são headless e negam escrita/bash/rede sem yolo/trust", () => {
+		const args = makiArgs("deepseek/deepseek-v4-pro");
+		expect(args).toEqual([
+			"-p",
+			"--output-format",
+			"json",
+			"--model",
+			"deepseek/deepseek-v4-pro",
+			"--disallowed-tools",
+			MAKI_DISALLOWED_TOOLS,
+		]);
+		expect(args).not.toContain("--yolo");
+		expect(args).not.toContain("--trust");
+		for (const tool of ["bash", "write", "edit", "task", "webfetch"]) {
+			expect(MAKI_DISALLOWED_TOOLS.split(",")).toContain(tool);
+		}
+	});
+
+	test("prompt inclui brief e proíbe escrita", () => {
+		const prompt = renderHuntPrompt({
+			projectName: "Proj",
+			watchdogId: "alpha",
+			brief: "# Brief alpha",
+		});
+		expect(prompt).toContain("# Brief alpha");
+		expect(prompt).toContain("não escreva arquivos");
+		expect(prompt).toContain('"watchdogId": "alpha"');
+	});
+
+	test("extrai JSON puro, cercado por markdown ou texto", () => {
+		const payload = { watchdogId: "alpha", findings: [] };
+		expect(extractJsonObject(JSON.stringify(payload))).toEqual(payload);
+		expect(
+			extractJsonObject(`\`\`\`json\n${JSON.stringify(payload)}\n\`\`\``),
+		).toEqual(payload);
+		expect(extractJsonObject(`Aqui está:\n${JSON.stringify(payload)}\nfim`)).toEqual(
+			payload,
+		);
+		expect(extractJsonObject("sem json")).toBeNull();
+	});
+
+	test("parseia o JSON do maki (linha única e multi-linha)", () => {
+		const single = '{"type":"result","result":"ok","session_id":"s1"}';
+		expect(parseMakiOutput(single)?.result).toBe("ok");
+
+		const pretty = JSON.stringify(
+			{ type: "result", result: "ok", total_cost_usd: 0.5 },
+			null,
+			2,
+		);
+		expect(parseMakiOutput(pretty)?.total_cost_usd).toBe(0.5);
+		expect(parseMakiOutput(`log\n${single}`)?.session_id).toBe("s1");
+		expect(parseMakiOutput("nada")).toBeNull();
+	});
+});
+
+describe("maki — modelo e credencial", () => {
+	const original = {
+		deepseek: process.env.HOUNDSMAN_DEEP_SEEK_API_KEY,
+		openai: process.env.HOUNDSMAN_OPENAI_API_KEY,
+	};
+
+	afterEach(() => {
+		if (original.deepseek === undefined)
+			delete process.env.HOUNDSMAN_DEEP_SEEK_API_KEY;
+		else process.env.HOUNDSMAN_DEEP_SEEK_API_KEY = original.deepseek;
+		if (original.openai === undefined) delete process.env.HOUNDSMAN_OPENAI_API_KEY;
+		else process.env.HOUNDSMAN_OPENAI_API_KEY = original.openai;
+	});
+
+	test("deriva deepseek/<model> e injeta DEEPSEEK_API_KEY", () => {
+		process.env.HOUNDSMAN_DEEP_SEEK_API_KEY = "sk-deepseek";
+		const model = requireMakiModel(project);
+		expect(model.spec).toBe("deepseek/deepseek-v4-pro");
+		expect(model.apiKeyEnv).toBe("DEEPSEEK_API_KEY");
+		expect(model.apiKey).toBe("sk-deepseek");
+	});
+
+	test("prefixo reconhecido troca provider e credencial", () => {
+		process.env.HOUNDSMAN_OPENAI_API_KEY = "sk-openai";
+		const model = resolveMakiModel(project, "openai/gpt-5");
+		expect(model.spec).toBe("openai/gpt-5");
+		expect(model.provider).toBe("openai");
+		expect(model.apiKeyEnv).toBe("OPENAI_API_KEY");
+		expect(model.apiKey).toBe("sk-openai");
+	});
+
+	test("sem chave, requireMakiModel falha com a env correta", () => {
+		delete process.env.HOUNDSMAN_DEEP_SEEK_API_KEY;
+		expect(() => requireMakiModel(project)).toThrow("HOUNDSMAN_DEEP_SEEK_API_KEY");
+	});
+});
+
+describe("HuntRunner", () => {
+	test("grava findings e agrega métricas", async () => {
+		const staging = makeWork(["alpha", "beta"]);
+		try {
+			const runner = new HuntRunner({
+				work: staging.work,
+				root: staging.root,
+				projectName: "Proj",
+				model: "deepseek/deepseek-v4-pro",
+				apiKeyEnv: "DEEPSEEK_API_KEY",
+				apiKey: "sk",
+				concurrency: 2,
+				timeoutMs: 10_000,
+				retries: 1,
+				runner: {
+					run: async (request) => {
+						const id = request.prompt.includes("brief de alpha")
+							? "alpha"
+							: "beta";
+						return {
+							ok: true,
+							text: reportJson(id),
+							metrics: {
+								durationMs: 10,
+								costUsd: 0.01,
+								sessionId: `s-${id}`,
+								numTurns: 2,
+								usage: {
+									totalTokens: 100,
+									inputTokens: 60,
+									outputTokens: 40,
+								},
+							},
+							stderr: "",
+							exitCode: 0,
+						};
+					},
+				},
+			});
+
+			const report = await runner.run(["alpha", "beta"]);
+			expect(report.totals.watchdogs).toBe(2);
+			expect(report.totals.done).toBe(2);
+			expect(report.totals.failed).toBe(0);
+			expect(report.totals.findings).toBe(2);
+			expect(report.totals.costUsd).toBeCloseTo(0.02);
+			expect(report.totals.totalTokens).toBe(200);
+			expect(staging.work.readFindings(["alpha", "beta"]).pending).toEqual([]);
+		} finally {
+			staging.cleanup();
+		}
+	});
+
+	test("repete uma vez quando a saída não tem JSON válido", async () => {
+		const staging = makeWork(["alpha"]);
+		try {
+			const prompts: string[] = [];
+			let calls = 0;
+			const runner = new HuntRunner({
+				work: staging.work,
+				root: staging.root,
+				projectName: "Proj",
+				model: "deepseek/deepseek-v4-pro",
+				apiKeyEnv: "DEEPSEEK_API_KEY",
+				apiKey: "sk",
+				concurrency: 1,
+				timeoutMs: 10_000,
+				retries: 1,
+				runner: {
+					run: async (request) => {
+						prompts.push(request.prompt);
+						calls++;
+						return calls === 1
+							? {
+									ok: true,
+									text: "não é json",
+									metrics: { durationMs: 5 },
+									stderr: "",
+									exitCode: 0,
+								}
+							: {
+									ok: true,
+									text: reportJson("alpha"),
+									metrics: { durationMs: 5 },
+									stderr: "",
+									exitCode: 0,
+								};
+					},
+				},
+			});
+
+			const report = await runner.run(["alpha"]);
+			expect(calls).toBe(2);
+			expect(report.watchdogs[0].attempts).toBe(2);
+			expect(report.watchdogs[0].status).toBe("done");
+			expect(prompts[1]).toContain("Correção obrigatória");
+		} finally {
+			staging.cleanup();
+		}
+	});
+
+	test("emite evento de retry antes da segunda tentativa", async () => {
+		const staging = makeWork(["alpha"]);
+		try {
+			const events: HuntEvent[] = [];
+			let calls = 0;
+			const runner = new HuntRunner({
+				work: staging.work,
+				root: staging.root,
+				projectName: "Proj",
+				model: "deepseek/deepseek-v4-pro",
+				apiKeyEnv: "DEEPSEEK_API_KEY",
+				apiKey: "sk",
+				concurrency: 1,
+				timeoutMs: 10_000,
+				retries: 1,
+				onEvent: (event) => events.push(event),
+				runner: {
+					run: async () => {
+						calls++;
+						return calls === 1
+							? {
+									ok: true,
+									text: "não é json",
+									metrics: { durationMs: 5 },
+									stderr: "",
+									exitCode: 0,
+								}
+							: {
+									ok: true,
+									text: reportJson("alpha"),
+									metrics: { durationMs: 5 },
+									stderr: "",
+									exitCode: 0,
+								};
+					},
+				},
+			});
+
+			await runner.run(["alpha"]);
+			const retry = events.find((event) => event.type === "retry");
+			expect(retry).toMatchObject({
+				type: "retry",
+				watchdogId: "alpha",
+				attempt: 1,
+				maxAttempts: 2,
+			});
+			expect(events.some((event) => event.type === "done")).toBe(true);
+		} finally {
+			staging.cleanup();
+		}
+	});
+
+	test("falha após os retries e não grava findings", async () => {
+		const staging = makeWork(["alpha"]);
+		try {
+			const runner = new HuntRunner({
+				work: staging.work,
+				root: staging.root,
+				projectName: "Proj",
+				model: "deepseek/deepseek-v4-pro",
+				apiKeyEnv: "DEEPSEEK_API_KEY",
+				apiKey: "sk",
+				concurrency: 1,
+				timeoutMs: 10_000,
+				retries: 1,
+				runner: {
+					run: async () => ({
+						ok: true,
+						text: "{}",
+						metrics: { durationMs: 1 },
+						stderr: "",
+						exitCode: 0,
+					}),
+				},
+			});
+
+			const report = await runner.run(["alpha"]);
+			expect(report.watchdogs[0].status).toBe("failed");
+			expect(report.watchdogs[0].error).toContain("watchdogId");
+			expect(existsSync(staging.work.findingFile("alpha"))).toBe(false);
+		} finally {
+			staging.cleanup();
+		}
+	});
+
+	test("watchdogId divergente é rejeitado", async () => {
+		const staging = makeWork(["alpha"]);
+		try {
+			const runner = new HuntRunner({
+				work: staging.work,
+				root: staging.root,
+				projectName: "Proj",
+				model: "deepseek/deepseek-v4-pro",
+				apiKeyEnv: "DEEPSEEK_API_KEY",
+				apiKey: "sk",
+				concurrency: 1,
+				timeoutMs: 10_000,
+				retries: 0,
+				runner: {
+					run: async () => ({
+						ok: true,
+						text: reportJson("beta"),
+						metrics: { durationMs: 1 },
+						stderr: "",
+						exitCode: 0,
+					}),
+				},
+			});
+
+			const report = await runner.run(["alpha"]);
+			expect(report.watchdogs[0].status).toBe("failed");
+			expect(report.watchdogs[0].error).toContain("não corresponde");
+		} finally {
+			staging.cleanup();
+		}
+	});
+});
+
+describe("SpawnMakiRunner (POSIX)", () => {
+	const dirs: string[] = [];
+
+	afterEach(() => {
+		for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true });
+	});
+
+	test.skipIf(process.platform === "win32")(
+		"lê o JSON do stdout e respeita o timeout",
+		async () => {
+			const dir = mkdtempSync(join(tmpdir(), "houndsman-maki-bin-"));
+			dirs.push(dir);
+			const binary = join(dir, "maki");
+			writeFileSync(
+				binary,
+				[
+					"#!/bin/sh",
+					"cat > /dev/null",
+					`printf '%s\\n' '{"type":"result","result":"{\\"findings\\":[]}","session_id":"s1","total_cost_usd":0.01,"usage":{"total_tokens":10}}'`,
+				].join("\n"),
+			);
+			chmodSync(binary, 0o755);
+
+			const runner = new SpawnMakiRunner(binary);
+			const result = await runner.run({
+				prompt: "brief",
+				cwd: dir,
+				model: "deepseek/deepseek-v4-pro",
+				apiKeyEnv: "DEEPSEEK_API_KEY",
+				apiKey: "sk",
+				timeoutMs: 5_000,
+			});
+			expect(result.ok).toBe(true);
+			if (result.ok) {
+				expect(result.text).toContain('"findings"');
+				expect(result.metrics.sessionId).toBe("s1");
+				expect(result.metrics.costUsd).toBe(0.01);
+			}
+
+			const slow = join(dir, "maki-slow");
+			writeFileSync(slow, "#!/bin/sh\nsleep 10\n");
+			chmodSync(slow, 0o755);
+			const timedOut = await new SpawnMakiRunner(slow).run({
+				prompt: "brief",
+				cwd: dir,
+				model: "deepseek/deepseek-v4-pro",
+				apiKeyEnv: "DEEPSEEK_API_KEY",
+				apiKey: "sk",
+				timeoutMs: 100,
+			});
+			expect(timedOut.ok).toBe(false);
+			if (!timedOut.ok) expect(timedOut.timedOut).toBe(true);
+		},
+	);
+});

package/src/tests/progress.test.ts

@@ -0,0 +1,117 @@
+/**
+ * Progresso do CLI — formatação, fases sequenciais e board concorrente.
+ *
+ * O board em TTY pinta um bloco com loader; fora de TTY mantém as linhas de
+ * início/fim e um heartbeat periódico.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { formatDuration, Logger, PhaseReporter, ProgressBoard } from "../core/logging";
+
+function memoryStream(): { stream: NodeJS.WritableStream; text: () => string } {
+	let content = "";
+	const stream = {
+		write(chunk: string) {
+			content += chunk;
+			return true;
+		},
+		isTTY: false,
+	} as unknown as NodeJS.WritableStream;
+	return { stream, text: () => content };
+}
+
+function loggerFor(tty: boolean): {
+	logger: Logger;
+	out: ReturnType<typeof memoryStream>;
+	err: ReturnType<typeof memoryStream>;
+} {
+	const out = memoryStream();
+	const err = memoryStream();
+	const logger = new Logger({
+		stdout: out.stream,
+		stderr: err.stream,
+		color: false,
+		isTTY: tty,
+	});
+	return { logger, out, err };
+}
+
+const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+
+describe("formatDuration", () => {
+	test("ms, segundos e minutos", () => {
+		expect(formatDuration(820)).toBe("820ms");
+		expect(formatDuration(3_400)).toBe("3.4s");
+		expect(formatDuration(42_000)).toBe("42s");
+		expect(formatDuration(125_000)).toBe("2m05s");
+	});
+});
+
+describe("PhaseReporter", () => {
+	test("em pipe imprime início e fim com a duração", () => {
+		const { logger, out } = loggerFor(false);
+		const reporter = new PhaseReporter(logger);
+		reporter.begin("diff", "Lendo o diff");
+		expect(out.text()).toContain("→ Lendo o diff");
+		reporter.end("diff", "Diff lido", 1_200);
+		expect(out.text()).toContain("✔ Diff lido (1.2s)");
+	});
+
+	test("fase sem início ainda reporta o fim", () => {
+		const { logger, out } = loggerFor(false);
+		new PhaseReporter(logger).end("ast", "AST analisada", 40);
+		expect(out.text()).toContain("AST analisada (40ms)");
+	});
+});
+
+describe("ProgressBoard", () => {
+	test("em pipe loga início/fim e não usa ANSI", () => {
+		const { logger, out, err } = loggerFor(false);
+		const board = new ProgressBoard({ logger, heartbeatMs: 10_000 });
+		board.start(2);
+		board.add("alpha", "revisando");
+		board.add("beta", "revisando");
+		board.succeed("alpha", "alpha — 2 finding(s) (12s)");
+		board.fail("beta", "beta falhou");
+		board.stop();
+		const text = out.text();
+		expect(text).toContain("alpha: revisando…");
+		expect(text).toContain("alpha — 2 finding(s) (12s)");
+		expect(err.text()).toContain("beta falhou");
+		expect(`${text}${err.text()}`).not.toContain("\u001b[");
+	});
+
+	test("em pipe emite heartbeat enquanto há tarefa em execução", async () => {
+		const { logger, out } = loggerFor(false);
+		const board = new ProgressBoard({ logger, heartbeatMs: 5 });
+		board.start(1);
+		board.add("alpha", "revisando");
+		await sleep(40);
+		board.stop();
+		expect(out.text()).toContain("1 tarefa(s) em execução: alpha");
+	});
+
+	test("em TTY pinta o bloco com loader e apaga ao concluir", () => {
+		const { logger, out } = loggerFor(true);
+		const board = new ProgressBoard({ logger, frameMs: 1_000 });
+		board.start(1);
+		board.add("alpha", "revisando");
+		const painted = out.text();
+		expect(painted).toContain("\u001b[2K");
+		expect(painted).toContain("alpha");
+		expect(painted).toContain("0/1 concluído(s)");
+		board.succeed("alpha", "alpha — 1 finding(s) (5s)");
+		board.stop();
+		expect(out.text()).toContain("✔ alpha — 1 finding(s) (5s)");
+	});
+
+	test("retry atualiza o detalhe sem derrubar o board", () => {
+		const { logger, out } = loggerFor(false);
+		const board = new ProgressBoard({ logger });
+		board.start(1);
+		board.add("alpha", "revisando");
+		board.retry("alpha", "tentativa 2/2", "alpha: repetindo (2/2)");
+		board.stop();
+		expect(out.text()).toContain("alpha: repetindo (2/2)");
+	});
+});

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

@@ -12,6 +12,7 @@ import { join } from "node:path";
 import { AstService } from "../core/ast/service";
 import { ReviewScopeResolver, type ScopeOptions } from "../core/engine/review-scope";
 import type { FindingState, FindingsStateFile } from "../core/findings-state";
+import type { PrepareProgressEvent } from "../core/orchestrator";
 import { defaultOptions, finalize, prepare, reviewContext } from "../core/orchestrator";
 import { resolveRepoIdentity } from "../core/storage/repo-identity";
 import { SQLiteStorageProvider } from "../core/storage/sqlite/sqlite-storage";
@@ -400,3 +401,64 @@ describe("prepare sem alterações", () => {
 		}
 	}, 30_000);
 });
+
+// ---------------------------------------------------------------------------
+// Progresso do prepare
+// ---------------------------------------------------------------------------
+
+describe("prepare — progresso", () => {
+	test("emite início/fim das etapas que realmente rodam", 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,
+				noAst: true,
+			};
+
+			const events: PrepareProgressEvent[] = [];
+			await prepare(
+				opts,
+				"main",
+				fakeHoundsmanConfig,
+				reviewContext(storage, record),
+				undefined,
+				undefined,
+				(event) => events.push(event),
+			);
+
+			const starts = events
+				.filter((event) => event.type === "start")
+				.map((event) => event.stage);
+			expect(starts).toEqual(["diff", "classify", "briefs", "manifest"]);
+			const done = events.filter((event) => event.type === "done");
+			expect(done.map((event) => event.stage)).toEqual(starts);
+			for (const event of done) {
+				if (event.type === "done") {
+					expect(event.durationMs).toBeGreaterThanOrEqual(0);
+				}
+			}
+		} finally {
+			storage?.close();
+			process.chdir(originalCwd);
+			if (originalHome === undefined) delete process.env.HOUNDSMAN_HOME;
+			else process.env.HOUNDSMAN_HOME = originalHome;
+			repo.cleanup();
+		}
+	}, 30_000);
+});