@payconductor/houndsman 0.4.0 → 0.6.0

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");
 		});
 	});
 

package/src/tests/server.test.ts

@@ -87,6 +87,11 @@ function makeEnv(): {
 const get = (handler: (r: Request) => Promise<Response>, path: string) =>
 	handler(new Request(`http://localhost${path}`));
 
+/** Resposta OK do `gh` com um JSON. */
+function ghJson(payload: unknown) {
+	return { ok: true, code: 0, stderr: "", stdout: JSON.stringify(payload) };
+}
+
 describe("server API", () => {
 	test("GET /api/runs lista as runs com resumo", async () => {
 		const env = makeEnv();
@@ -231,27 +236,77 @@ describe("server API", () => {
 			const handler = createRequestHandler(env.config, {
 				storage: env.storage,
 				repo: env.repo,
-				ghRunner: (args) =>
-					args[0] === "pr"
-						? {
-								ok: true,
-								code: 0,
-								stderr: "",
-								stdout: JSON.stringify({
-									number: 12,
-									url: "https://github.com/acme/app/pull/12",
-									headRefOid: "deadbeef",
-								}),
-							}
-						: {
-								ok: true,
-								code: 0,
-								stderr: "",
-								stdout: JSON.stringify({
-									id: 501,
-									html_url: "https://x/501",
-								}),
-							},
+				ghRunner: (args) => {
+					if (args[0] === "pr") {
+						return ghJson({
+							number: 12,
+							url: "https://github.com/acme/app/pull/12",
+							headRefOid: "deadbeef",
+						});
+					}
+					if (args[1] === "graphql") {
+						const query = args.find((arg) => arg.startsWith("query=")) ?? "";
+						if (query.includes("states: [PENDING]")) {
+							return ghJson({
+								data: {
+									repository: {
+										pullRequest: {
+											id: "PR_1",
+											reviews: { nodes: [] },
+										},
+									},
+								},
+							});
+						}
+						if (query.includes("addPullRequestReview(input")) {
+							return ghJson({
+								data: {
+									addPullRequestReview: {
+										pullRequestReview: {
+											id: "REV_NEW",
+											databaseId: 11,
+											resourcePath:
+												"/acme/app/pull/12#pullrequestreview-11",
+										},
+									},
+								},
+							});
+						}
+						if (query.includes("addPullRequestReviewThread")) {
+							return ghJson({
+								data: {
+									addPullRequestReviewThread: {
+										thread: {
+											comments: {
+												nodes: [
+													{
+														databaseId: 501,
+														resourcePath:
+															"/acme/app/pull/12#discussion_r501",
+													},
+												],
+											},
+										},
+									},
+								},
+							});
+						}
+						if (query.includes("submitPullRequestReview")) {
+							return ghJson({
+								data: {
+									submitPullRequestReview: {
+										pullRequestReview: {
+											id: "REV_NEW",
+											databaseId: 11,
+											state: "CHANGES_REQUESTED",
+										},
+									},
+								},
+							});
+						}
+					}
+					return { ok: false, code: 404, stderr: "", stdout: "" };
+				},
 			});
 			const res = await handler(
 				new Request("http://localhost/api/runs/main/submit", {

package/src/tests/storage.test.ts

@@ -384,3 +384,66 @@ describe("resolveFindingId", () => {
 		});
 	});
 });
+
+describe("migração do schema SQLite", () => {
+	test("banco v1 ganha a coluna heartbeat_at sem perder reviews", () => {
+		const dir = mkdtempSync(join(tmpdir(), "houndsman-migrate-"));
+		const path = join(dir, "houndsman.db");
+		const legacy = new Database(path);
+		try {
+			legacy.exec(`
+				CREATE TABLE reviews (
+					id TEXT PRIMARY KEY,
+					repo_key TEXT NOT NULL,
+					repo_root TEXT NOT NULL,
+					repo_remote TEXT,
+					branch TEXT NOT NULL,
+					slug TEXT NOT NULL,
+					base TEXT,
+					head TEXT,
+					head_sha TEXT,
+					reviewed_sha TEXT,
+					reviewed_at TEXT,
+					status TEXT,
+					started_at TEXT,
+					created_at TEXT NOT NULL,
+					updated_at TEXT NOT NULL,
+					UNIQUE(repo_key, branch)
+				);
+				PRAGMA user_version = 1;
+			`);
+			legacy.run(
+				`INSERT INTO reviews
+					(id, repo_key, repo_root, branch, slug, status, created_at, updated_at)
+				 VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+				[
+					"11111111-1111-4111-8111-111111111111",
+					"path:/repo",
+					dir,
+					"feature/x",
+					"feature-x",
+					"reviewing",
+					"2026-01-01T00:00:00.000Z",
+					"2026-01-01T00:00:00.000Z",
+				],
+			);
+		} finally {
+			legacy.close();
+		}
+
+		const storage = new SQLiteStorageProvider(path);
+		try {
+			const review = storage.listReviews()[0];
+			expect(review?.heartbeatAt).toBeUndefined();
+			storage.updateReview(review.id, {
+				heartbeatAt: "2026-01-01T00:05:00.000Z",
+			});
+			expect(storage.getReview(review.id)?.heartbeatAt).toBe(
+				"2026-01-01T00:05:00.000Z",
+			);
+		} finally {
+			storage.close();
+			rmSync(dir, { recursive: true, force: true });
+		}
+	});
+});

package/src/tests/tool-contracts.test.ts

@@ -0,0 +1,82 @@
+/**
+ * Contract test das tools built-in: metadata, schema e erros estruturados.
+ */
+
+import { describe, expect, test } from "bun:test";
+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 { 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 { fakeAgentContext } from "./fixtures/fake-investigation";
+import { fakeHoundsmanConfig } from "./fixtures/fake-project";
+
+function registry(): ToolRegistry {
+	const value = new ToolRegistry();
+	value.registerModule(new BuiltinToolsModule());
+	return value;
+}
+
+function context(): ToolContext {
+	return {
+		repoRoot: process.cwd(),
+		watchdog: new Watchdog(fakeHoundsmanConfig.watchdogs.alpha),
+		diff: { byFile: new Map(), churn: new Map() },
+		ast: new AstService(fakeHoundsmanConfig),
+		state: new AgentState(),
+		budget: new ToolCallBudget(20, 10),
+		cache: new ToolCache(),
+		logger: new SilentReporter(),
+		agent: fakeAgentContext({ repoRoot: process.cwd() }),
+		rules: new Map(),
+	};
+}
+
+describe("contratos das tools", () => {
+	test("todas declaram metadata read-only e capabilities", () => {
+		for (const tool of registry().list()) {
+			expect(tool.metadata.name.length).toBeGreaterThan(0);
+			expect(tool.metadata.description.length).toBeGreaterThan(0);
+			expect(tool.metadata.readOnly).toBe(true);
+			expect(tool.metadata.capabilities.length).toBeGreaterThan(0);
+			expect(tool.metadata.cost).toBeGreaterThanOrEqual(1);
+		}
+	});
+
+	test("nenhuma tool devolve arquivo inteiro por padrão", () => {
+		// `read_file_range` exige faixa explícita.
+		const range = registry().get("read_file_range");
+		expect(range?.inputSchema.safeParse({ path: "a.ts" }).success).toBe(false);
+		// `file_outline` só devolve metadados (não tem parâmetro de corpo).
+		const outline = registry().get("file_outline");
+		expect(outline?.inputSchema.safeParse({ path: "a.ts" }).success).toBe(true);
+	});
+
+	test("tools de arquivo devolvem erro estruturado (não lançam)", async () => {
+		const middleware = new ToolMiddleware();
+		for (const [name, input] of [
+			["read_file_range", { path: "../x", startLine: 1, endLine: 2 }],
+			["file_outline", { path: "../x" }],
+			["imports_exports", { file: "../x" }],
+		] as const) {
+			const result = await registry().execute(name, input, context(), middleware);
+			expect(result.ok).toBe(false);
+			expect(typeof result.error).toBe("string");
+		}
+	});
+
+	test("rule_signals devolve erro quando a regra não existe", async () => {
+		const result = await registry().execute(
+			"rule_signals",
+			{ rule: "regra inexistente" },
+			context(),
+			new ToolMiddleware(),
+		);
+		expect(result.ok).toBe(false);
+	});
+});

package/src/tests/verify.test.ts

@@ -158,7 +158,7 @@ describe("JevVerifier", () => {
 		]);
 		expect(outcome.checked).toBe(0);
 		expect(outcome.skipped).toBe(1);
-		expect(outcome.reason).toContain("TYPESAFE_API_KEY");
+		expect(outcome.reason).toContain("HOUNDSMAN_TYPE_SAFE_API_KEY");
 	});
 
 	test("sem casos ⇒ vazio", async () => {

package/src/server/client/markdown.ts

@@ -1,153 +0,0 @@
-/**
- * Markdown mínimo do campo `action` (cliente).
- *
- * Suporta o suficiente para instruções curtas: parágrafos, quebras de linha,
- * listas, blockquote, blocos de código e formatação inline (`code`, **bold**,
- * *itálico*, links). Sem lib externa e sem HTML cru.
- */
-
-export type MarkdownBlock =
-	| { type: "paragraph"; text: string }
-	| { type: "list"; ordered: boolean; items: string[] }
-	| { type: "code"; language: string | null; code: string }
-	| { type: "quote"; text: string };
-
-export type InlineToken =
-	| { type: "text"; text: string }
-	| { type: "code"; text: string }
-	| { type: "strong"; text: string }
-	| { type: "em"; text: string }
-	| { type: "link"; text: string; url: string };
-
-const FENCE = /^\s*```(\S*)\s*$/;
-const BULLET = /^\s*[-*+]\s+(.*)$/;
-const ORDERED = /^\s*\d+\.\s+(.*)$/;
-const QUOTE = /^\s*>\s?(.*)$/;
-
-function isBlockStart(line: string): boolean {
-	return (
-		FENCE.test(line) || BULLET.test(line) || ORDERED.test(line) || QUOTE.test(line)
-	);
-}
-
-/** Divide o texto em blocos simples (sem aninhamento profundo). */
-export function parseMarkdown(text: string): MarkdownBlock[] {
-	const lines = text.replace(/\r\n?/g, "\n").split("\n");
-	const blocks: MarkdownBlock[] = [];
-	let index = 0;
-
-	while (index < lines.length) {
-		const line = lines[index];
-		if (line.trim().length === 0) {
-			index++;
-			continue;
-		}
-
-		const fence = FENCE.exec(line);
-		if (fence) {
-			const language = fence[1] || null;
-			const code: string[] = [];
-			index++;
-			while (index < lines.length && !FENCE.test(lines[index])) {
-				code.push(lines[index]);
-				index++;
-			}
-			if (index < lines.length) index++;
-			blocks.push({ type: "code", language, code: code.join("\n") });
-			continue;
-		}
-
-		if (BULLET.test(line)) {
-			const items: string[] = [];
-			while (index < lines.length) {
-				const item = BULLET.exec(lines[index]);
-				if (!item) break;
-				items.push(item[1]);
-				index++;
-			}
-			blocks.push({ type: "list", ordered: false, items });
-			continue;
-		}
-
-		if (ORDERED.test(line)) {
-			const items: string[] = [];
-			while (index < lines.length) {
-				const item = ORDERED.exec(lines[index]);
-				if (!item) break;
-				items.push(item[1]);
-				index++;
-			}
-			blocks.push({ type: "list", ordered: true, items });
-			continue;
-		}
-
-		if (QUOTE.test(line)) {
-			const quote: string[] = [];
-			while (index < lines.length) {
-				const item = QUOTE.exec(lines[index]);
-				if (!item) break;
-				quote.push(item[1]);
-				index++;
-			}
-			blocks.push({ type: "quote", text: quote.join("\n") });
-			continue;
-		}
-
-		const paragraph: string[] = [line];
-		index++;
-		while (
-			index < lines.length &&
-			lines[index].trim().length > 0 &&
-			!isBlockStart(lines[index])
-		) {
-			paragraph.push(lines[index]);
-			index++;
-		}
-		blocks.push({ type: "paragraph", text: paragraph.join("\n") });
-	}
-
-	return blocks;
-}
-
-/** Tokeniza formatação inline preservando o texto e a ordem dos marcadores. */
-export function parseInline(text: string): InlineToken[] {
-	const tokens: InlineToken[] = [];
-	// Ordem importa: code/bold antes de itálico; `_` exige fronteira de palavra.
-	const pattern =
-		/`[^`\n]+`|\*\*[^*\n]+\*\*|__[^_\n]+__|\*[^*\n]+\*|(?<![\w])_[^_\n]+_(?![\w])|\[[^\]\n]+\]\([^)\s]+\)/g;
-	let last = 0;
-	for (const match of text.matchAll(pattern)) {
-		const start = match.index ?? 0;
-		if (start > last) {
-			tokens.push({ type: "text", text: text.slice(last, start) });
-		}
-		const raw = match[0];
-		if (raw.startsWith("`")) {
-			tokens.push({ type: "code", text: raw.slice(1, -1) });
-		} else if (raw.startsWith("**") || raw.startsWith("__")) {
-			tokens.push({ type: "strong", text: raw.slice(2, -2) });
-		} else if (raw.startsWith("*") || raw.startsWith("_")) {
-			tokens.push({ type: "em", text: raw.slice(1, -1) });
-		} else {
-			const link = /^\[([^\]]+)\]\(([^)\s]+)\)$/.exec(raw);
-			if (link) {
-				tokens.push({ type: "link", text: link[1], url: link[2] });
-			} else {
-				tokens.push({ type: "text", text: raw });
-			}
-		}
-		last = start + raw.length;
-	}
-	if (last < text.length) {
-		tokens.push({ type: "text", text: text.slice(last) });
-	}
-	return tokens;
-}
-
-/** URL segura para links de markdown (evita `javascript:` e afins). */
-export function safeUrl(url: string): string | null {
-	const value = url.trim();
-	if (/^(https?:|mailto:)/i.test(value)) return value;
-	if (value.startsWith("/") && !value.startsWith("//")) return value;
-	return null;
-}