@payconductor/houndsman 0.13.0 → 0.16.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,256 @@
+/**
+ * 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");
+	});
+
+	test("expõe checklist, cobertura e custo das passadas extras do harness", () => {
+		const withHarness: ReviewSnapshot = {
+			...snapshot("B", []),
+			harness: {
+				checksExpected: 8,
+				checksVerified: 6,
+				checksGaps: 2,
+				reviewedFiles: 11,
+				skippedFiles: 3,
+				undeclaredFiles: 4,
+				businessScore: 20,
+				extraCostUsd: 0.035,
+				secondOpinionFindings: 2,
+			},
+		};
+		const markdown = renderComparison(buildComparison(a, withHarness));
+		expect(markdown).toContain("| Checklist verificado | — | 6/8 | — |");
+		expect(markdown).toContain("| Arquivos sem declaração | — | 4 | — |");
+		expect(markdown).toContain("| Modelo de intenção (score) | — | 20 | — |");
+		expect(markdown).toContain("| Passadas extras (custo) | — | $0.0350 | — |");
+		expect(markdown).toContain("| Segunda opinião (findings) | — | 2 | — |");
+	});
+});
+
+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/findings-state.test.ts

@@ -33,6 +33,7 @@ function merged(
 	partial: Partial<MergedFinding> & { file: string; rule: string },
 ): MergedFinding {
 	return {
+		...partial,
 		rule: partial.rule,
 		severity: (partial.severity ?? "attention") as Severity,
 		file: partial.file,
@@ -209,6 +210,87 @@ describe("buildStateFromFindings", () => {
 			project.cleanup();
 		}
 	});
+
+	test("emergente sem impactClass mantém a severidade já triada", () => {
+		const project = makeProject({ "src/f.ts": DUPLICATED });
+		try {
+			const reader = fileReader(project.cwd);
+			const base = {
+				file: "src/f.ts",
+				rule: "Lógica: gap",
+				line: 2,
+				message: "gap",
+				basis: "logic" as const,
+			};
+			const first = buildStateFromFindings(
+				[merged({ ...base, severity: "blocking", scenario: "s", evidence: "x" })],
+				{ branch: "main", readFile: reader },
+			);
+			const second = buildStateFromFindings(
+				[merged({ ...base, severity: "suggestion" })],
+				{ branch: "main", readFile: reader, previous: first },
+			);
+			expect(Object.values(second.findings)[0].severity).toBe("blocking");
+		} finally {
+			project.cleanup();
+		}
+	});
+
+	test("emergente com impactClass acompanha o valor derivado", () => {
+		const project = makeProject({ "src/f.ts": DUPLICATED });
+		try {
+			const reader = fileReader(project.cwd);
+			const base = {
+				file: "src/f.ts",
+				rule: "Domínio: gap",
+				line: 2,
+				message: "gap",
+				basis: "domain" as const,
+			};
+			const first = buildStateFromFindings(
+				[merged({ ...base, severity: "suggestion", impactClass: "degradation" })],
+				{ branch: "main", readFile: reader },
+			);
+			const second = buildStateFromFindings(
+				[
+					merged({
+						...base,
+						severity: "attention",
+						impactClass: "contract-drift",
+					}),
+				],
+				{ branch: "main", readFile: reader, previous: first },
+			);
+			expect(Object.values(second.findings)[0].severity).toBe("attention");
+		} finally {
+			project.cleanup();
+		}
+	});
+
+	test("finding de regra sempre acompanha a severidade nova (config manda)", () => {
+		const project = makeProject({ "src/f.ts": DUPLICATED });
+		try {
+			const reader = fileReader(project.cwd);
+			const base = {
+				file: "src/f.ts",
+				rule: "Nunca usar any",
+				line: 2,
+				message: "any",
+				basis: "rule" as const,
+			};
+			const first = buildStateFromFindings(
+				[merged({ ...base, severity: "blocking" })],
+				{ branch: "main", readFile: reader },
+			);
+			const second = buildStateFromFindings(
+				[merged({ ...base, severity: "attention" })],
+				{ branch: "main", readFile: reader, previous: first },
+			);
+			expect(Object.values(second.findings)[0].severity).toBe("attention");
+		} finally {
+			project.cleanup();
+		}
+	});
 });
 
 describe("syncState", () => {

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,
 		};
 	}
 }