@payconductor/houndsman 0.5.0 → 0.7.0

package/src/tests/fixtures/fake-investigation.ts

@@ -0,0 +1,64 @@
+/**
+ * Fixtures de investigação/agente (sem rede, sem git).
+ */
+
+import { AstService } from "../../core/ast/service";
+import { Watchdog } from "../../core/domain/watchdog";
+import type { AgentContext } from "../../harness/agent/agent-context";
+import { SilentReporter } from "../../harness/agent/agent-reporter";
+import type { ReviewAgentDeps } from "../../harness/agent/review-agent";
+import { RuleAnalyzer } from "../../harness/investigation/rule-analyzer";
+import { BuiltinToolsModule } from "../../harness/tools/builtin";
+import { ToolRegistry } from "../../harness/tools/tool-registry";
+import type { FakeModelProvider } from "./fake-model-provider";
+import { fakeHoundsmanConfig } from "./fake-project";
+
+/** Contexto de agente para o watchdog `alpha`. */
+export function fakeAgentContext(overrides: Partial<AgentContext> = {}): AgentContext {
+	const watchdog = new Watchdog(fakeHoundsmanConfig.watchdogs.alpha);
+	const rules = new RuleAnalyzer().analyze(watchdog.rules);
+	return {
+		watchdog,
+		projectName: "Fake",
+		branch: "main",
+		files: ["src/alpha/a.ts"],
+		overflow: [],
+		deleted: [],
+		docs: [],
+		context: null,
+		ast: new Map(),
+		outputPath: "findings/alpha.json",
+		maxSteps: 4,
+		maxCalls: 8,
+		repoRoot: process.cwd(),
+		diff: { byFile: new Map(), churn: new Map() },
+		rules,
+		...overrides,
+	};
+}
+
+/** Registry com tools built-in. */
+export function builtinRegistry(): ToolRegistry {
+	const registry = new ToolRegistry();
+	registry.registerModule(new BuiltinToolsModule());
+	return registry;
+}
+
+/** Deps completas de um `ReviewAgent` com provider fake. */
+export function fakeAgentDeps(
+	provider: FakeModelProvider,
+	overrides: Partial<ReviewAgentDeps> = {},
+): ReviewAgentDeps {
+	const context = overrides.context ?? fakeAgentContext();
+	return {
+		context,
+		provider,
+		registry: builtinRegistry(),
+		reporter: new SilentReporter(),
+		maxOutputTokens: 512,
+		temperature: 0,
+		timeoutMs: 5_000,
+		ast: new AstService(fakeHoundsmanConfig),
+		...overrides,
+	};
+}

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

@@ -0,0 +1,48 @@
+/**
+ * Provider de modelo fake — suíte sem rede.
+ */
+
+import type { AiUsage, ModelProvider, ModelRequest, ModelResponse } from "../../core/ai";
+
+/** Uso padrão de uma chamada fake. */
+export function fakeUsage(calls = 1): AiUsage {
+	return {
+		inputTokens: 10 * calls,
+		outputTokens: 5 * calls,
+		totalTokens: 15 * calls,
+		calls,
+	};
+}
+
+/** Handler roteirizado: recebe o request e o índice da chamada. */
+export type FakeHandler = (
+	request: ModelRequest<unknown>,
+	index: number,
+) => unknown | Promise<unknown>;
+
+/** Provider roteirizado. */
+export class FakeModelProvider implements ModelProvider {
+	readonly name = "deepseek" as const;
+	readonly modelId: string;
+	readonly requests: ModelRequest<unknown>[] = [];
+	calls = 0;
+
+	constructor(
+		private readonly handler: FakeHandler,
+		modelId = "fake-model",
+	) {
+		this.modelId = modelId;
+	}
+
+	async generate<T>(request: ModelRequest<T>): Promise<ModelResponse<T>> {
+		this.requests.push(request as ModelRequest<unknown>);
+		const index = this.calls++;
+		const output = await this.handler(request as ModelRequest<unknown>, index);
+		return {
+			output: output as T,
+			usage: fakeUsage(),
+			steps: 1,
+			finishReason: "stop",
+		};
+	}
+}

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

@@ -294,6 +294,15 @@ describe("selectSubmitCandidates", () => {
 		expect(selectSubmitCandidates(state, { execStates: ["done"] })).toEqual([]);
 	});
 
+	test("filtra pela decisão (a executar vs ainda pendente)", () => {
+		const execute = selectSubmitCandidates(state, { decisions: ["execute"] });
+		expect(execute.map((c) => c.id)).toEqual(["a"]);
+		expect(execute[0].decision).toBe("execute");
+		expect(
+			selectSubmitCandidates(state, { decisions: ["pending"] }).map((c) => c.id),
+		).toEqual(["c"]);
+	});
+
 	test("marca sent/skip e respeita includeSent", () => {
 		const sent = stateWith([finding({ id: "a", commentId: 99 })]);
 		const [only] = selectSubmitCandidates(sent);

package/src/tests/harness-agent.test.ts

@@ -0,0 +1,122 @@
+/**
+ * ReviewAgent — máquina de estados com provider fake e tools reais.
+ */
+
+import { afterAll, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { SilentReporter } from "../harness/agent/agent-reporter";
+import { ReviewAgent } from "../harness/agent/review-agent";
+import { fakeAgentContext, fakeAgentDeps } from "./fixtures/fake-investigation";
+import { FakeModelProvider } from "./fixtures/fake-model-provider";
+
+const RULE = "Nunca usar `any`.";
+
+const dir = mkdtempSync(join(tmpdir(), "houndsman-agent-"));
+mkdirSync(join(dir, "src/alpha"), { recursive: true });
+writeFileSync(join(dir, "src/alpha/a.ts"), "const x: any = 1;\nconsole.log(x);\n");
+afterAll(() => rmSync(dir, { recursive: true, force: true }));
+
+/** Provider que investiga com `read_file_range` e devolve um draft. */
+function investigatingProvider(options: { withEvidence?: boolean } = {}) {
+	return new FakeModelProvider(async (request, index) => {
+		if (index === 0) return { hypotheses: ["uso de any"] };
+		if (index === 1) return { taskIds: ["rule-0"] };
+		const tool = request.tools?.read_file_range;
+		if (!tool) throw new Error("tool read_file_range ausente");
+		const raw = await tool.execute({
+			path: "src/alpha/a.ts",
+			startLine: 1,
+			endLine: 2,
+		});
+		const parsed = JSON.parse(raw) as {
+			evidence?: { id: string }[];
+		};
+		const evidenceId = parsed.evidence?.[0]?.id;
+		return {
+			findingDrafts: [
+				{
+					rule: RULE,
+					severity: "blocking",
+					file: "src/alpha/a.ts",
+					line: 1,
+					message: "Uso de any.",
+					action: "Tipar o valor.",
+					evidenceIds:
+						options.withEvidence === false || !evidenceId ? [] : [evidenceId],
+					confidence: 0.9,
+				},
+			],
+			coverage: [
+				{ rule: RULE, status: "checked" },
+				{ rule: "Validar entrada do usuário.", status: "not_applicable" },
+				{ rule: "Evitar console.log.", status: "checked" },
+			],
+		};
+	});
+}
+
+function buildAgent(provider: FakeModelProvider): {
+	agent: ReviewAgent;
+	reporter: SilentReporter;
+} {
+	const reporter = new SilentReporter();
+	const deps = fakeAgentDeps(provider, {
+		context: fakeAgentContext({ repoRoot: dir }),
+		reporter,
+	});
+	return { agent: new ReviewAgent(deps), reporter };
+}
+
+describe("ReviewAgent", () => {
+	test("ORIENT→PLAN→INVESTIGATE→VERIFY→CONCLUDE com evidência", async () => {
+		const { agent, reporter } = buildAgent(investigatingProvider());
+		const result = await agent.run();
+		expect(result.status).toBe("done");
+		expect(result.report?.findings).toHaveLength(1);
+		expect(result.report?.findings[0]?.evidence).toContain("src/alpha/a.ts");
+		expect(result.report?.reviewedFiles).toContain("src/alpha/a.ts");
+		const transitions = reporter.journal.transitions.map((item) => item.to);
+		expect(transitions).toEqual(["PLAN", "INVESTIGATE", "VERIFY", "CONCLUDE"]);
+		expect(result.state.coverage.size).toBe(3);
+	});
+
+	test("VERIFY é obrigatório: draft sem evidência é descartado", async () => {
+		const { agent } = buildAgent(investigatingProvider({ withEvidence: false }));
+		const result = await agent.run();
+		expect(result.status).toBe("done");
+		expect(result.report?.findings).toHaveLength(0);
+		const coverage = result.state.coverageOf(RULE);
+		expect(coverage?.status).toBe("checked");
+		expect(coverage?.reason).toContain("refutado");
+	});
+
+	test("toda regra termina com cobertura (mesmo sem o modelo cobrir)", async () => {
+		const provider = new FakeModelProvider((_request, index) => {
+			if (index === 0) return { hypotheses: [] };
+			if (index === 1) return { taskIds: [] };
+			return { findingDrafts: [], coverage: [] };
+		});
+		const { agent } = buildAgent(provider);
+		const result = await agent.run();
+		expect(result.state.coverage.size).toBe(3);
+		expect(
+			[...result.state.coverage.values()].every(
+				(item) => item.status === "skipped",
+			),
+		).toBe(true);
+	});
+
+	test("falha do provider vira status failed", async () => {
+		const provider = new FakeModelProvider((_request, index) => {
+			if (index === 0) throw new Error("boom");
+			if (index === 1) throw new Error("boom");
+			throw new Error("429 rate limit");
+		});
+		const { agent } = buildAgent(provider);
+		const result = await agent.run();
+		expect(result.status).toBe("failed");
+		expect(result.error).toContain("429");
+	});
+});

package/src/tests/harness-investigation.test.ts

@@ -0,0 +1,206 @@
+/**
+ * Investigação: planner, evidência, crítico e cobertura.
+ */
+
+import { afterAll, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { AgentState } from "../harness/investigation/agent-state";
+import { EvidenceVerifier } from "../harness/investigation/evidence-verifier";
+import { FindingCritic } from "../harness/investigation/finding-critic";
+import { InvestigationPlanner } from "../harness/investigation/investigation-planner";
+import { RuleAnalyzer } from "../harness/investigation/rule-analyzer";
+
+const RULE = "Nunca usar `any`.";
+const analyses = new RuleAnalyzer().analyze([
+	{ severity: "suggestion", text: "Evitar console.log." },
+	{ severity: "blocking", text: RULE },
+	{ severity: "attention", text: "Validar entrada do usuário." },
+]);
+
+const dir = mkdtempSync(join(tmpdir(), "houndsman-evidence-"));
+const file = join(dir, "a.ts");
+writeFileSync(file, "const x: any = 1;\nconsole.log(x);\n");
+afterAll(() => rmSync(dir, { recursive: true, force: true }));
+
+function verifier(): EvidenceVerifier {
+	return new EvidenceVerifier({
+		allowedFiles: ["a.ts"],
+		readFile: (path) =>
+			path === "a.ts" ? "const x: any = 1;\nconsole.log(x);\n" : null,
+	});
+}
+
+describe("InvestigationPlanner", () => {
+	test("prioriza por severidade e calcula estimativa", () => {
+		const plan = new InvestigationPlanner().plan(
+			{ watchdogId: "alpha", files: ["a.ts"], symbols: [] },
+			analyses,
+		);
+		expect(plan.tasks[0]?.rule).toBe(RULE);
+		expect(plan.tasks[0]?.severity).toBe("blocking");
+		expect(plan.totalFiles).toBe(1);
+		expect(plan.estimatedToolCalls).toBeGreaterThan(0);
+	});
+
+	test("filtra arquivos por hint de path", () => {
+		const [analysis] = new RuleAnalyzer().analyze([
+			{
+				severity: "attention",
+				text: "Evitar: query no banco em rota.",
+				hints: { paths: ["^src/alpha/"] },
+			},
+		]);
+		const plan = new InvestigationPlanner().plan(
+			{
+				watchdogId: "alpha",
+				files: ["src/alpha/a.ts", "src/beta/b.ts"],
+				symbols: [],
+			},
+			analysis ? [analysis] : [],
+		);
+		expect(plan.tasks[0]?.files).toEqual(["src/alpha/a.ts"]);
+	});
+});
+
+describe("EvidenceVerifier", () => {
+	test("aceita snippet na linha e reancora quando deslocado", () => {
+		const state = new AgentState();
+		const exact = state.addEvidence({
+			file: "a.ts",
+			startLine: 1,
+			endLine: 1,
+			snippet: "const x: any = 1;",
+			kind: "definition",
+			sourceTool: "t",
+			confidence: 0.9,
+		});
+		const moved = state.addEvidence({
+			file: "a.ts",
+			startLine: 9,
+			endLine: 9,
+			snippet: "console.log(x);",
+			kind: "reference",
+			sourceTool: "t",
+			confidence: 0.7,
+		});
+		expect(verifier().verify(exact).valid).toBe(true);
+		const verdict = verifier().verify(moved);
+		expect(verdict.valid).toBe(true);
+		expect(verdict.startLine).toBe(2);
+	});
+
+	test("rejeita arquivo fora do domínio e snippet inexistente", () => {
+		const state = new AgentState();
+		const outside = state.addEvidence({
+			file: "b.ts",
+			startLine: 1,
+			endLine: 1,
+			snippet: "x",
+			kind: "definition",
+			sourceTool: "t",
+			confidence: 1,
+		});
+		const missing = state.addEvidence({
+			file: "a.ts",
+			startLine: 1,
+			endLine: 1,
+			snippet: "não existe",
+			kind: "definition",
+			sourceTool: "t",
+			confidence: 1,
+		});
+		expect(verifier().verify(outside).valid).toBe(false);
+		expect(verifier().verify(missing).valid).toBe(false);
+	});
+
+	test("draft sem evidência válida é inválido", () => {
+		const state = new AgentState();
+		const evidence = state.addEvidence({
+			file: "a.ts",
+			startLine: 1,
+			endLine: 1,
+			snippet: "const x: any = 1;",
+			kind: "definition",
+			sourceTool: "t",
+			confidence: 0.9,
+		});
+		const draft = {
+			rule: RULE,
+			severity: "blocking" as const,
+			file: "a.ts",
+			line: 1,
+			message: "m",
+			action: "a",
+			evidenceIds: [evidence.id],
+			confidence: 0.9,
+		};
+		expect(verifier().verifyDraft(draft, state).valid).toBe(true);
+		expect(
+			verifier().verifyDraft({ ...draft, evidenceIds: ["nope"] }, state).valid,
+		).toBe(false);
+	});
+});
+
+describe("FindingCritic", () => {
+	const state = new AgentState();
+	const evidence = state.addEvidence({
+		file: "a.ts",
+		startLine: 1,
+		endLine: 1,
+		snippet: "const x: any = 1;",
+		kind: "definition",
+		sourceTool: "t",
+		confidence: 0.9,
+	});
+	const critic = new FindingCritic({
+		knownRules: new Set([RULE]),
+		verifier: verifier(),
+	});
+	const draft = {
+		rule: RULE,
+		severity: "blocking" as const,
+		file: "a.ts",
+		line: 1,
+		message: "m",
+		action: "a",
+		evidenceIds: [evidence.id],
+		confidence: 0.9,
+	};
+
+	test("keep com evidência e confiança", () => {
+		expect(critic.reviewOne(draft, state).verdict).toBe("keep");
+	});
+
+	test("drop sem evidência, sem regra ou confiança baixa", () => {
+		expect(critic.reviewOne({ ...draft, evidenceIds: [] }, state).verdict).toBe(
+			"drop",
+		);
+		expect(critic.reviewOne({ ...draft, rule: "inexistente" }, state).verdict).toBe(
+			"drop",
+		);
+		expect(critic.reviewOne({ ...draft, confidence: 0.2 }, state).verdict).toBe(
+			"drop",
+		);
+	});
+
+	test("downgrade quando a confiança não sustenta a severidade", () => {
+		expect(critic.reviewOne({ ...draft, confidence: 0.5 }, state).verdict).toBe(
+			"downgrade",
+		);
+	});
+});
+
+describe("AgentState", () => {
+	test("cobertura e hipóteses sem duplicar", () => {
+		const state = new AgentState();
+		state.addHypothesis("a");
+		state.addHypothesis("a");
+		expect(state.hypotheses).toEqual(["a"]);
+		state.setCoverage(RULE, "skipped", "motivo");
+		expect(state.isCovered(RULE)).toBe(true);
+		state.setCoverage(RULE, "checked");
+		expect(state.coverageOf(RULE)?.status).toBe("checked");
+	});
+});

package/src/tests/harness-tools.test.ts

@@ -0,0 +1,148 @@
+/**
+ * Tools do harness: path guard, limites, cache, budget e redaction.
+ */
+
+import { afterAll, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { AstService } from "../core/ast/service";
+import { Watchdog } from "../core/domain/watchdog";
+import { SilentReporter } from "../harness/agent/agent-reporter";
+import { AgentState } from "../harness/investigation/agent-state";
+import type { ToolContext } from "../harness/tools/agent-tool";
+import { BuiltinToolsModule } from "../harness/tools/builtin";
+import { PathGuard } from "../harness/tools/path-guard";
+import { redactSecrets } from "../harness/tools/secret-redactor";
+import { ToolCache } from "../harness/tools/tool-cache";
+import { ToolCallBudget } from "../harness/tools/tool-call-budget";
+import { ToolMiddleware } from "../harness/tools/tool-middleware";
+import { ToolRegistry } from "../harness/tools/tool-registry";
+import { EchoTool } from "./fixtures/fake-agent-tools";
+import { fakeAgentContext } from "./fixtures/fake-investigation";
+import { fakeHoundsmanConfig } from "./fixtures/fake-project";
+
+const dir = mkdtempSync(join(tmpdir(), "houndsman-tools-"));
+mkdirSync(join(dir, "src/alpha"), { recursive: true });
+writeFileSync(
+	join(dir, "src/alpha/a.ts"),
+	"const x: any = 1;\nconsole.log(x);\nconst y = 2;\n",
+);
+afterAll(() => rmSync(dir, { recursive: true, force: true }));
+
+function context(): ToolContext {
+	const state = new AgentState();
+	return {
+		repoRoot: dir,
+		watchdog: new Watchdog(fakeHoundsmanConfig.watchdogs.alpha),
+		diff: { byFile: new Map(), churn: new Map() },
+		ast: new AstService(fakeHoundsmanConfig),
+		state,
+		budget: new ToolCallBudget(20, 10),
+		cache: new ToolCache(),
+		logger: new SilentReporter(),
+		agent: fakeAgentContext({ repoRoot: dir }),
+		rules: new Map(),
+	};
+}
+
+describe("PathGuard", () => {
+	test("bloqueia traversal, .git e .env", () => {
+		const guard = new PathGuard(dir);
+		expect(() => guard.resolvePath("../segredo")).toThrow();
+		expect(() => guard.resolvePath(".git/config")).toThrow();
+		expect(() => guard.resolvePath(".env")).toThrow();
+	});
+
+	test("aceita caminho interno", () => {
+		const guard = new PathGuard(dir);
+		expect(guard.resolvePath("src/alpha/a.ts")).toContain("a.ts");
+	});
+});
+
+describe("read_file_range", () => {
+	test("devolve faixa numerada + evidência com id", async () => {
+		const registry = new ToolRegistry();
+		registry.registerModule(new BuiltinToolsModule());
+		const middleware = new ToolMiddleware();
+		const ctx = context();
+		const result = await registry.execute(
+			"read_file_range",
+			{ path: "src/alpha/a.ts", startLine: 1, endLine: 2 },
+			ctx,
+			middleware,
+		);
+		expect(result.ok).toBe(true);
+		const data = result.data as { content: string };
+		expect(data.content).toContain("1\tconst x: any = 1;");
+		expect(data.content).toContain("2\tconsole.log(x);");
+		expect(result.evidence?.[0]?.id).toBeTruthy();
+		expect(ctx.state.evidence.size).toBe(1);
+	});
+
+	test("caminho fora do repo vira erro estruturado", async () => {
+		const registry = new ToolRegistry();
+		registry.registerModule(new BuiltinToolsModule());
+		const result = await registry.execute(
+			"read_file_range",
+			{ path: "../x", startLine: 1, endLine: 2 },
+			context(),
+			new ToolMiddleware(),
+		);
+		expect(result.ok).toBe(false);
+		expect(result.error).toContain("fora do repositório");
+	});
+});
+
+describe("ToolRegistry / middleware", () => {
+	test("nome duplicado falha no registro", () => {
+		const registry = new ToolRegistry();
+		registry.registerTool(new EchoTool());
+		expect(() => registry.registerTool(new EchoTool())).toThrow();
+	});
+
+	test("resultado em cache não consome budget", async () => {
+		const registry = new ToolRegistry();
+		registry.registerTool(new EchoTool());
+		const middleware = new ToolMiddleware();
+		const ctx = context();
+		await registry.execute("echo", { value: "a" }, ctx, middleware);
+		expect(ctx.budget.total).toBe(1);
+		await registry.execute("echo", { value: "a" }, ctx, middleware);
+		expect(ctx.budget.total).toBe(1);
+		await registry.execute("echo", { value: "b" }, ctx, middleware);
+		expect(ctx.budget.total).toBe(2);
+	});
+
+	test("input inválido vira erro (Zod)", async () => {
+		const registry = new ToolRegistry();
+		registry.registerTool(new EchoTool());
+		const result = await registry.execute(
+			"echo",
+			{ value: 1 },
+			context(),
+			new ToolMiddleware(),
+		);
+		expect(result.ok).toBe(false);
+		expect(result.error).toContain("input inválido");
+	});
+
+	test("budget esgotado interrompe", async () => {
+		const registry = new ToolRegistry();
+		registry.registerTool(new EchoTool());
+		const ctx = context();
+		ctx.budget = new ToolCallBudget(1, 1);
+		const middleware = new ToolMiddleware();
+		await registry.execute("echo", { value: "a" }, ctx, middleware);
+		const second = await registry.execute("echo", { value: "b" }, ctx, middleware);
+		expect(second.ok).toBe(false);
+		expect(second.error).toContain("Orçamento");
+	});
+});
+
+describe("redaction", () => {
+	test("remove tokens e chaves", () => {
+		expect(redactSecrets("token sk-abcdefgh123")).toContain("[REDACTED]");
+		expect(redactSecrets("api_key = segredo")).toContain("[REDACTED]");
+	});
+});