@payconductor/houndsman 0.13.0 → 0.14.0

package/src/tests/business-summary.test.ts

@@ -0,0 +1,258 @@
+/**
+ * Modelo de intenção (`business-summary.json`) e política de severidade dos
+ * findings de lógica/domínio.
+ */
+
+import { describe, expect, test } from "bun:test";
+import type { AstAnalysis } from "../core/ast/types";
+import { defaultRenderBrief } from "../core/brief";
+import { GENERAL_WATCHDOG_ID, generalWatchdog } from "../core/builtins";
+import {
+	buildBusinessBrief,
+	buildBusinessSummary,
+	parseBusinessSummary,
+} from "../core/business-summary";
+import { normalizeFinding } from "../core/report-builder";
+import { findWatchdog } from "../core/watchdog-registry";
+import { fakeHoundsmanConfig } from "./fixtures/fake-project";
+
+const facts: AstAnalysis["facts"] = {
+	language: "typescript",
+	symbols: [],
+	imports: [],
+	exports: [],
+	decorators: [],
+	hasSyntaxErrors: false,
+};
+
+const delta = {
+	addedSymbols: [
+		{
+			name: "Contrato",
+			kind: "interface" as const,
+			exported: true,
+			startLine: 1,
+			endLine: 3,
+		},
+		{
+			name: "executar",
+			kind: "function" as const,
+			exported: true,
+			startLine: 5,
+			endLine: 9,
+		},
+	],
+	removedSymbols: [],
+	modifiedSymbols: [],
+	changedSignatures: [],
+	addedImports: [],
+	removedImports: [],
+	changedExports: [],
+};
+
+const classification = {
+	files: {
+		"src/alpha/a.ts": { status: "modified" as const },
+		"src/beta/b.ts": { status: "modified" as const },
+		"src/alpha/old.ts": { status: "deleted" as const },
+	},
+	churn: {
+		"src/alpha/a.ts": { additions: 10, deletions: 2 },
+		"src/beta/b.ts": { additions: 1, deletions: 0 },
+	},
+	watchdogs: {
+		alpha: ["src/alpha/a.ts"],
+		beta: ["src/beta/b.ts"],
+		[GENERAL_WATCHDOG_ID]: ["src/alpha/a.ts", "src/beta/b.ts"],
+	},
+};
+
+const domains = [
+	{ id: "alpha", name: "Alpha" },
+	{ id: "beta", name: "Beta" },
+	{ id: GENERAL_WATCHDOG_ID, name: "Lógica e domínio (fluxo)" },
+];
+
+describe("buildBusinessSummary", () => {
+	test("deriva fluxos por domínio (sem o general) e contratos do AST", () => {
+		const summary = buildBusinessSummary({
+			classification,
+			domains,
+			ast: new Map([["src/alpha/a.ts", { facts, delta }]]),
+			headSha: "abc123",
+			context: { objective: "Entregar o split" },
+		});
+
+		expect(summary.source).toBe("deterministic");
+		expect(summary.intent).toBe("Entregar o split");
+		expect(summary.headSha).toBe("abc123");
+		expect(summary.flows.map((flow) => flow.name)).toEqual(["Alpha", "Beta"]);
+		expect(summary.flows[0]?.files).toEqual(["src/alpha/a.ts"]);
+		expect(summary.flows[0]?.expected).toContain("Contrato");
+		expect(summary.contracts).toEqual([
+			{
+				name: "Contrato",
+				sides: ["src/alpha/a.ts"],
+				expectation:
+					"Declaração `interface` nova — verificar se todos os lados do contrato a honram.",
+			},
+		]);
+	});
+
+	test("sem contexto e sem AST, mantém o esqueleto vazio (nunca inventa)", () => {
+		const summary = buildBusinessSummary({ classification, domains });
+		expect(summary.intent).toBeUndefined();
+		expect(summary.contracts).toEqual([]);
+		expect(summary.invariants).toEqual([]);
+		expect(summary.flows).toHaveLength(2);
+	});
+});
+
+describe("parseBusinessSummary", () => {
+	test("normaliza listas e preserva a fonte", () => {
+		const summary = parseBusinessSummary(
+			{
+				source: "reviewer",
+				intent: "  Entregar Y  ",
+				flows: [{ name: "Renovação", trigger: "job", files: ["src/a.ts"] }],
+				invariants: ["split sempre presente"],
+				contracts: [{ name: "AutomaticPix", sides: ["asaas", "processor"] }],
+				states: [{ name: "authorization", transitions: ["ativa → cancelada"] }],
+			},
+			"deterministic",
+		);
+		expect(summary?.source).toBe("reviewer");
+		expect(summary?.intent).toBe("Entregar Y");
+		expect(summary?.flows[0]?.name).toBe("Renovação");
+		expect(summary?.invariants).toEqual(["split sempre presente"]);
+	});
+
+	test("rejeita documento sem conteúdo útil", () => {
+		expect(parseBusinessSummary({})).toBeNull();
+		expect(parseBusinessSummary(null)).toBeNull();
+		expect(parseBusinessSummary({ flows: [{ name: "" }] })).toBeNull();
+	});
+
+	test("corta itens acima do limite e ignora entradas inválidas", () => {
+		const summary = parseBusinessSummary({
+			intent: "x",
+			flows: [
+				{ name: "ok" },
+				{ name: "" },
+				{ name: "outro", files: ["a", 1, "b"] },
+			],
+		});
+		expect(summary?.flows.map((flow) => flow.name)).toEqual(["ok", "outro"]);
+		expect(summary?.flows[1]?.files).toEqual(["a", "b"]);
+	});
+});
+
+describe("buildBusinessBrief", () => {
+	test("aponta o output e inclui o schema e o modelo determinístico", () => {
+		const summary = buildBusinessSummary({ classification, domains });
+		const brief = buildBusinessBrief({
+			projectName: "Fake",
+			branch: "main",
+			headSha: "abc123",
+			outputPath: "/tmp/work/review/business-summary.json",
+			business: summary,
+			files: [
+				{
+					path: "src/alpha/a.ts",
+					status: "modified",
+					ranges: [{ start: 3, end: 9 }],
+					symbols: ["Contrato"],
+				},
+			],
+			docs: ["AGENTS.md"],
+			context: { objective: "Entregar o split" },
+		});
+		expect(brief).toContain("/tmp/work/review/business-summary.json");
+		expect(brief).toContain('"invariants"');
+		expect(brief).toContain("Modelo determinístico");
+		expect(brief).toContain("src/alpha/a.ts");
+		expect(brief).toContain("AGENTS.md");
+		expect(brief).toContain('source: "reviewer"');
+	});
+});
+
+describe("política de severidade (lógica/domínio)", () => {
+	const base = {
+		file: "src/alpha/a.ts",
+		line: 3,
+		message: "gap",
+		action: "corrigir",
+	};
+
+	test("blocking sem cenário+evidência vira attention", () => {
+		const warnings: string[] = [];
+		const finding = normalizeFinding(
+			{
+				...base,
+				rule: "Domínio: renovação perde o split",
+				severity: "blocking",
+			},
+			(message) => warnings.push(message),
+		);
+		expect(finding.basis).toBe("domain");
+		expect(finding.severity).toBe("attention");
+		expect(warnings).toHaveLength(1);
+	});
+
+	test("com cenário e evidência, blocking é preservado", () => {
+		const finding = normalizeFinding({
+			...base,
+			rule: "Lógica: subscription sem authorize",
+			severity: "blocking",
+			scenario: "renovação de assinatura Pix",
+			evidence: "this.sendAutomaticPixPayment(data)",
+		});
+		expect(finding.basis).toBe("logic");
+		expect(finding.severity).toBe("blocking");
+	});
+
+	test("regra explícita mantém a severidade declarada", () => {
+		const finding = normalizeFinding({
+			...base,
+			rule: "Nunca usar `any`.",
+			severity: "blocking",
+		});
+		expect(finding.basis).toBe("rule");
+		expect(finding.severity).toBe("blocking");
+	});
+});
+
+describe("watchdog general", () => {
+	test("resolvido como built-in mesmo sem config", () => {
+		const definition = findWatchdog(fakeHoundsmanConfig, GENERAL_WATCHDOG_ID);
+		expect(definition?.name).toContain("Lógica");
+		expect(definition?.allowEmergentFindings).toBe(true);
+		expect(definition?.fallback).toBe(false);
+	});
+
+	test("brief inclui intenção, diff e obrigação de output", () => {
+		const summary = buildBusinessSummary({ classification, domains });
+		const markdown = defaultRenderBrief(
+			{
+				watchdogId: GENERAL_WATCHDOG_ID,
+				files: ["src/alpha/a.ts"],
+				statuses: { "src/alpha/a.ts": { status: "modified" as const } },
+				deleted: [],
+				branch: "main",
+				outputPath: "/tmp/findings/general.json",
+				outputFormatPath: "OUTPUT-FORMAT.md",
+				docs: [],
+				business: summary,
+				businessSummaryPath: "/tmp/business-summary.json",
+				snippets: [{ file: "src/alpha/a.ts", snippet: "@@ -1 +1 @@\n-a\n+b" }],
+				flowReview: true,
+			},
+			generalWatchdog,
+		).join("\n");
+		expect(markdown).toContain("## Modelo de intenção (negócio)");
+		expect(markdown).toContain("## Trechos alterados (diff)");
+		expect(markdown).toContain("## Obrigação de output (fluxo)");
+		expect(markdown).toContain("/tmp/business-summary.json");
+		expect(markdown).toContain("scenario");
+	});
+});

package/src/tests/compare.test.ts

@@ -0,0 +1,233 @@
+/**
+ * Comparação A/B e identidade das variantes.
+ *
+ * Cobre o slug da run (URL/backend de arquivos), o diff de findings entre dois
+ * snapshots e o parse de `--variant` no comando default.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { runCompare } from "../core/commands/compare";
+import { parseReviewArgs } from "../core/commands/review";
+import {
+	buildComparison,
+	type ComparisonFinding,
+	countBySeverity,
+	type ReviewSnapshot,
+	renderComparison,
+} from "../core/compare";
+import type { FindingsStateFile } from "../core/findings-state";
+import { reviewSlug, sanitizeVariant } from "../core/report-builder";
+import { buildRepoIdentity } from "../core/storage/repo-identity";
+import { SQLiteStorageProvider } from "../core/storage/sqlite/sqlite-storage";
+
+function finding(
+	fingerprint: string,
+	partial: Partial<ComparisonFinding> = {},
+): ComparisonFinding {
+	return {
+		fingerprint,
+		rule: "regra",
+		severity: "attention",
+		file: "src/a.ts",
+		line: 10,
+		message: "mensagem",
+		watchdogs: ["alpha"],
+		...partial,
+	};
+}
+
+function snapshot(
+	label: string,
+	findings: ComparisonFinding[],
+	variant?: string,
+): ReviewSnapshot {
+	return {
+		label,
+		slug: reviewSlug("feature/x", variant),
+		branch: "feature/x",
+		variant,
+		headSha: "deadbeef",
+		findings,
+		bySeverity: countBySeverity(findings),
+		coverage: { watchdogs: 2, files: 3, overflow: 0 },
+		durationMs: 60_000,
+	};
+}
+
+describe("reviewSlug / sanitizeVariant", () => {
+	test("run principal usa o slug da branch", () => {
+		expect(reviewSlug("feature/add-webhook")).toBe("feature-add-webhook");
+		expect(reviewSlug("feature/x", "   ")).toBe("feature-x");
+	});
+
+	test("variante ganha sufixo legível + hash estável", () => {
+		const baseline = reviewSlug("feature/x", "Baseline A");
+		const optimized = reviewSlug("feature/x", "Baseline B");
+		expect(baseline).toStartWith("feature-x--baseline-a-");
+		expect(baseline).toBe(reviewSlug("feature/x", "Baseline A"));
+		expect(baseline).not.toBe(optimized);
+		expect(sanitizeVariant("  A/B  ")).toBe("a-b");
+	});
+});
+
+describe("buildComparison", () => {
+	const a = snapshot("A", [
+		finding("f1", { severity: "attention", file: "src/a.ts" }),
+		finding("f2", { severity: "suggestion", file: "src/b.ts", line: 2 }),
+	]);
+	const b = snapshot(
+		"B",
+		[
+			finding("f1", { severity: "blocking", file: "src/a.ts" }),
+			finding("f3", { severity: "blocking", file: "src/c.ts", line: 5 }),
+		],
+		"otimizado",
+	);
+
+	test("separa novos, sumidos e mudança de severidade", () => {
+		const comparison = buildComparison(a, b);
+		expect(comparison.onlyB.map((item) => item.fingerprint)).toEqual(["f3"]);
+		expect(comparison.onlyA.map((item) => item.fingerprint)).toEqual(["f2"]);
+		expect(comparison.common).toHaveLength(1);
+		expect(comparison.severityChanged).toHaveLength(1);
+		expect(comparison.severityChanged[0].a.severity).toBe("attention");
+		expect(comparison.severityChanged[0].b.severity).toBe("blocking");
+	});
+
+	test("conta por severidade", () => {
+		expect(a.bySeverity).toEqual({
+			blocking: 0,
+			attention: 1,
+			suggestion: 1,
+			nit: 0,
+		});
+		expect(b.bySeverity).toEqual({
+			blocking: 2,
+			attention: 0,
+			suggestion: 0,
+			nit: 0,
+		});
+	});
+
+	test("renderiza a tabela e as listas", () => {
+		const markdown = renderComparison(buildComparison(a, b));
+		expect(markdown).toContain("# Comparação A/B — `feature/x`");
+		expect(markdown).toContain("| Findings (presentes) | 2 | 2 | 0 |");
+		expect(markdown).toContain("## Só em B (novos) (1)");
+		expect(markdown).toContain("## Só em A (não apareceram em B) (1)");
+		expect(markdown).toContain("## Severidade mudou (1)");
+		expect(markdown).toContain("## Só em B");
+	});
+});
+
+describe("--variant", () => {
+	test("é lido pelo parse do comando default", () => {
+		const options = parseReviewArgs([
+			"--branch",
+			"feature/x",
+			"--variant",
+			" baseline ",
+		]);
+		expect(options.variant).toBe("baseline");
+	});
+
+	describe("runCompare", () => {
+		test("lê as duas runs e grava o relatório na run B", () => {
+			const dir = mkdtempSync(join(tmpdir(), "houndsman-compare-"));
+			const storage = new SQLiteStorageProvider(join(dir, "houndsman.db"));
+			try {
+				const repo = buildRepoIdentity(null, dir);
+				const main = storage.getOrCreateReview({
+					repo,
+					branch: "feature/x",
+					slug: "feature-x",
+				});
+				const variant = storage.getOrCreateReview({
+					repo,
+					branch: "feature/x",
+					variant: "otimizado",
+					slug: "feature-x--otimizado-1a2b3c",
+				});
+				const state = (
+					findings: FindingsStateFile["findings"],
+				): FindingsStateFile => ({
+					version: 2,
+					branch: "feature/x",
+					slug: "feature-x",
+					updatedAt: "2026-01-01T00:00:00.000Z",
+					order: Object.keys(findings),
+					findings,
+				});
+				const baseFinding = {
+					id: "ab12cd34ef",
+					fingerprint: "fp-1",
+					watchdogIds: ["alpha"],
+					rule: "regra",
+					severity: "attention" as const,
+					file: "src/a.ts",
+					line: 10,
+					message: "mensagem",
+					action: "ação",
+					anchor: null,
+					count: 1,
+					present: true,
+					decision: "pending" as const,
+					execState: "pending" as const,
+					createdAt: "2026-01-01T00:00:00.000Z",
+					updatedAt: "2026-01-01T00:00:00.000Z",
+					history: [],
+				};
+				storage.writeFindings(main.id, state({ ab12cd34ef: baseFinding }));
+				storage.writeFindings(
+					variant.id,
+					state({
+						ab12cd34ef: baseFinding,
+						ff00aa11bb: {
+							...baseFinding,
+							id: "ff00aa11bb",
+							fingerprint: "fp-2",
+							rule: "outra",
+						},
+					}),
+				);
+				storage.writeArtifact(main.id, {
+					name: "manifest.json",
+					kind: "manifest",
+					content: JSON.stringify({
+						watchdogs: [{ files: ["src/a.ts"], overflow: 0 }],
+					}),
+				});
+				storage.writeArtifact(variant.id, {
+					name: "prepare-report.json",
+					kind: "prepare",
+					content: JSON.stringify({ durationMs: 1_000, stages: [] }),
+				});
+
+				const result = runCompare(storage, repo, {
+					branch: "feature/x",
+					variantB: "otimizado",
+				});
+				expect(result.b.id).toBe(variant.id);
+				expect(result.markdown).toContain("Só em B (novos) (1)");
+				expect(
+					storage.readArtifact(variant.id, result.artifacts.markdown)?.kind,
+				).toBe("compare");
+				expect(
+					storage.readArtifact(variant.id, result.artifacts.json)?.content,
+				).toContain("onlyB");
+			} finally {
+				storage.close();
+				rmSync(dir, { recursive: true, force: true });
+			}
+		});
+	});
+
+	test("vazio é rejeitado", () => {
+		expect(() => parseReviewArgs(["--variant", "  "])).toThrow(
+			"--variant não pode ser vazio",
+		);
+	});
+});

package/src/tests/fixtures/fake-model-provider.ts

@@ -30,6 +30,7 @@ export class FakeModelProvider implements ModelProvider {
 	constructor(
 		private readonly handler: FakeHandler,
 		modelId = "fake-model",
+		private readonly finishReason = "stop",
 	) {
 		this.modelId = modelId;
 	}
@@ -41,7 +42,7 @@ export class FakeModelProvider implements ModelProvider {
 		return {
 			output: output as T,
 			usage: fakeUsage(),
-			finishReason: "stop",
+			finishReason: this.finishReason,
 		};
 	}
 }

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

@@ -244,6 +244,64 @@ describe("HuntRunner", () => {
 		}
 	});
 
+	test("pré-passe de intenção grava o modelo antes dos watchdogs", async () => {
+		const staging = makeWork(["alpha"]);
+		staging.work.writeBusinessBrief("# Brief de intenção");
+		try {
+			let intentCalls = 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: 0,
+				runner: {
+					run: async (request) => {
+						if (request.prompt.includes("passo de intenção")) {
+							intentCalls++;
+							return {
+								ok: true,
+								text: JSON.stringify({
+									intent: "Entregar o split",
+									flows: [
+										{ name: "Renovação", files: ["src/alpha/a.ts"] },
+									],
+									invariants: ["split sempre presente"],
+									contracts: [],
+									states: [],
+								}),
+								metrics: { durationMs: 5 },
+								stderr: "",
+								exitCode: 0,
+							};
+						}
+						return {
+							ok: true,
+							text: reportJson("alpha"),
+							metrics: { durationMs: 5 },
+							stderr: "",
+							exitCode: 0,
+						};
+					},
+				},
+			});
+
+			const report = await runner.run(["alpha"]);
+			expect(intentCalls).toBe(1);
+			expect(report.business).toBe("reviewer");
+			const summary = staging.work.readBusinessSummary();
+			expect(summary?.source).toBe("reviewer");
+			expect(summary?.intent).toBe("Entregar o split");
+			expect(summary?.invariants).toEqual(["split sempre presente"]);
+		} finally {
+			staging.cleanup();
+		}
+	});
+
 	test("repete uma vez quando a saída não tem JSON válido", async () => {
 		const staging = makeWork(["alpha"]);
 		try {

package/src/tests/markdown.test.ts

@@ -116,11 +116,11 @@ describe("parseInline", () => {
 	});
 
 	test("destaca caminhos de arquivo no texto corrido", () => {
-		expect(parseInline("veja src/foo/bar.ts e review.md")).toEqual([
+		expect(parseInline("veja src/foo/bar.ts e manifest.json")).toEqual([
 			{ type: "text", text: "veja " },
 			{ type: "path", text: "src/foo/bar.ts" },
 			{ type: "text", text: " e " },
-			{ type: "path", text: "review.md" },
+			{ type: "path", text: "manifest.json" },
 		]);
 	});
 });
@@ -128,7 +128,7 @@ describe("parseInline", () => {
 describe("isFilePath", () => {
 	test("reconhece arquivos e caminhos, sem confundir texto comum", () => {
 		expect(isFilePath("src/foo/bar.ts")).toBe(true);
-		expect(isFilePath("review.md")).toBe(true);
+		expect(isFilePath("manifest.json")).toBe(true);
 		expect(isFilePath("./scripts/ci.sh")).toBe(true);
 		expect(isFilePath("M/D")).toBe(false);
 		expect(isFilePath("duas palavras.ts")).toBe(false);

package/src/tests/progress.test.ts

@@ -6,7 +6,13 @@
  */
 
 import { describe, expect, test } from "bun:test";
-import { formatDuration, Logger, PhaseReporter, ProgressBoard } from "../core/logging";
+import {
+	formatDuration,
+	Logger,
+	ParallelPhaseReporter,
+	PhaseReporter,
+	ProgressBoard,
+} from "../core/logging";
 
 function memoryStream(): { stream: NodeJS.WritableStream; text: () => string } {
 	let content = "";
@@ -64,6 +70,28 @@ describe("PhaseReporter", () => {
 	});
 });
 
+describe("ParallelPhaseReporter", () => {
+	test("em pipe aceita fases concorrentes e loga cada uma", () => {
+		const { logger, out } = loggerFor(false);
+		const reporter = new ParallelPhaseReporter(logger);
+		reporter.begin("context", "Resumindo o contexto");
+		reporter.begin("business", "Reconstruindo a intenção");
+		reporter.end("context", "Contexto resumido", 50);
+		reporter.end("business", "Intenção reconstruída", 80);
+		reporter.stop();
+		const text = out.text();
+		expect(text).toContain("→ Resumindo o contexto");
+		expect(text).toContain("→ Reconstruindo a intenção");
+		expect(text).toContain("✔ Contexto resumido (50ms)");
+		expect(text).toContain("✔ Intenção reconstruída (80ms)");
+	});
+
+	test("stop sem fases ativas não lança", () => {
+		const { logger } = loggerFor(false);
+		expect(() => new ParallelPhaseReporter(logger).stop()).not.toThrow();
+	});
+});
+
 describe("ProgressBoard", () => {
 	test("em pipe loga início/fim e não usa ANSI", () => {
 		const { logger, out, err } = loggerFor(false);