@payconductor/houndsman 0.5.0 → 0.6.0

package/src/tests/ast.test.ts

@@ -0,0 +1,335 @@
+/**
+ * Testes do subsistema AST (project-agnóstico).
+ *
+ * Cobrem extração de fatos, delta por hunk, impacto (resolução de imports),
+ * classificação estrutural e o bloco injetado no brief. Nenhuma chamada de rede.
+ */
+
+import { 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 { computeDelta, parseHunks } from "../core/ast/diff";
+import { resolveImport } from "../core/ast/impact";
+import { AstParser } from "../core/ast/parser";
+import { AstService } from "../core/ast/service";
+import type { AstFacts } from "../core/ast/types";
+import { renderBrief } from "../core/brief";
+import { defineHoundsmanConfig } from "../core/config";
+import { collectDiff } from "../core/diff-source";
+import { matchWatchdogs, parseEntries } from "../core/file-classifier";
+import { runGit } from "../core/git-runner";
+import { GitRepository } from "../core/services/git-repository";
+import { defineWatchdog } from "../core/types";
+
+const parser = new AstParser();
+
+const TS_SOURCE = `import { db } from "./db";
+import type { Order } from "./types";
+
+export class OrderService {
+	constructor(private readonly database: Db) {}
+
+	async create(input: Input): Promise<Order> {
+		return db.insert(input);
+	}
+}
+
+export function helper(value: string): number {
+	return value.length;
+}
+
+export const handler = async (request: Request) => {
+	return helper(request.url);
+};
+
+@Controller("/orders")
+export class OrdersController {
+	@Get(":id")
+	get(): string {
+		return "ok";
+	}
+}
+`;
+
+async function factsOf(source: string): Promise<AstFacts> {
+	const facts = await parser.parseSource("typescript", source);
+	if (!facts) throw new Error("parse falhou");
+	return facts;
+}
+
+describe("AstParser / extractFacts", () => {
+	test("extrai símbolos, exports, imports e decorators", async () => {
+		const facts = await factsOf(TS_SOURCE);
+		const names = facts.symbols.map((symbol) => symbol.name);
+
+		expect(names).toContain("OrderService");
+		expect(names).toContain("OrderService.create");
+		expect(names).toContain("helper");
+		expect(names).toContain("handler");
+		expect(facts.imports.map((item) => item.source)).toEqual(["./db", "./types"]);
+		expect(facts.imports[1]?.typeOnly).toBe(true);
+		expect(facts.exports.map((item) => item.name)).toEqual(
+			expect.arrayContaining([
+				"OrderService",
+				"helper",
+				"handler",
+				"OrdersController",
+			]),
+		);
+		expect(facts.decorators).toEqual(["Controller", "Get"]);
+		expect(facts.hasSyntaxErrors).toBe(false);
+	});
+
+	test("não quebra com sintaxe inválida (fatos parciais)", async () => {
+		const facts = await factsOf("export function broken( {");
+		expect(facts).not.toBeNull();
+		expect(facts.hasSyntaxErrors).toBe(true);
+	});
+
+	test("não extrai variáveis aninhadas como símbolos de topo", async () => {
+		const facts = await factsOf(
+			"export const handler = () => { const inner = 1; return inner; };\n",
+		);
+		const names = facts.symbols.map((symbol) => symbol.name);
+		expect(names).toContain("handler");
+		expect(names).not.toContain("inner");
+	});
+
+	test("linguagem não suportada devolve null", async () => {
+		expect(await parser.parseFile("README.md", "# titulo")).toBeNull();
+	});
+});
+
+describe("computeDelta / parseHunks", () => {
+	test("parseHunks extrai linhas novas", () => {
+		const patch = [
+			"@@ -1,3 +1,4 @@",
+			" export function a() {",
+			"-  return 1;",
+			"+  const x = 1;",
+			"+  return x;",
+			" }",
+		].join("\n");
+		expect(parseHunks(patch)[0]?.addedLines).toEqual([2, 3]);
+	});
+
+	test("detecta símbolos adicionados/removidos e assinatura alterada", async () => {
+		const before = await factsOf(
+			"export function a(value: string): void {}\nexport const b = 1;\n",
+		);
+		const after = await factsOf(
+			"export function a(value: number, extra: boolean): void {}\nexport function c() {}\n",
+		);
+		const patch = [
+			"@@ -1,2 +1,2 @@",
+			"-export function a(value: string): void {}",
+			"+export function a(value: number, extra: boolean): void {}",
+			"-export const b = 1;",
+			"+export function c() {}",
+		].join("\n");
+
+		const delta = computeDelta(before, after, patch);
+		expect(delta.addedSymbols.map((symbol) => symbol.name)).toContain("c");
+		expect(delta.removedSymbols.map((symbol) => symbol.name)).toContain("b");
+		expect(delta.changedSignatures.map((item) => item.name)).toContain("a");
+		expect(delta.modifiedSymbols.map((symbol) => symbol.name)).toContain("a");
+	});
+
+	test("marca como export a mudança via `export { ... }`", async () => {
+		const before = await factsOf(
+			"function a(value: string): void {}\nexport { a };\n",
+		);
+		const after = await factsOf(
+			"function a(value: number): void {}\nexport { a };\n",
+		);
+		const delta = computeDelta(
+			before,
+			after,
+			"@@ -1,2 +1,2 @@\n-function a(value: string): void {}\n+function a(value: number): void {}\n export { a };",
+		);
+		expect(delta.changedSignatures[0]?.exported).toBe(true);
+	});
+});
+
+describe("resolveImport", () => {
+	const aliases = { "@/*": "src/*" };
+	const existing = new Set([
+		"src/db.ts",
+		"src/orders/index.ts",
+		"src/utils/helpers.tsx",
+	]);
+
+	test("resolve relativo com extensão implícita", () => {
+		expect(
+			resolveImport("src/a.ts", "./db", aliases, (path) => existing.has(path)),
+		).toBe("src/db.ts");
+	});
+
+	test("resolve alias e index", () => {
+		expect(
+			resolveImport("src/a.ts", "@/orders", aliases, (path) => existing.has(path)),
+		).toBe("src/orders/index.ts");
+	});
+
+	test("ignora pacote externo", () => {
+		expect(
+			resolveImport("src/a.ts", "react", aliases, (path) => existing.has(path)),
+		).toBeNull();
+	});
+});
+
+describe("classificação estrutural", () => {
+	test("casa regras por símbolo, import, export e decorator", async () => {
+		const facts = await factsOf(TS_SOURCE);
+		const watchdog = defineWatchdog({
+			id: "auth",
+			name: "Auth",
+			description: "Regras de autenticação.",
+			scope: "src/**",
+			classify: [
+				{ type: "decorator", value: "^Controller$" },
+				{ type: "import", value: "^\\./db$" },
+				{ type: "symbol", value: "OrderService" },
+				{ type: "export", value: "^OrdersController$" },
+			],
+			rules: [{ severity: "attention", text: "Promover: validar entrada." }],
+			contextFiles: ["AGENTS.md"],
+		});
+
+		expect(
+			matchWatchdogs(
+				"src/orders.ts",
+				{ auth: watchdog },
+				["auth"],
+				undefined,
+				facts,
+			),
+		).toEqual(["auth"]);
+	});
+
+	test("sem fatos AST, regras estruturais não casam", () => {
+		const watchdog = defineWatchdog({
+			id: "auth",
+			name: "Auth",
+			description: "Regras de autenticação.",
+			scope: "src/**",
+			classify: [{ type: "decorator", value: "^Controller$" }],
+			rules: [{ severity: "attention", text: "Promover: validar entrada." }],
+			contextFiles: ["AGENTS.md"],
+		});
+		expect(matchWatchdogs("src/orders.ts", { auth: watchdog }, ["auth"])).toEqual([]);
+	});
+});
+
+describe("brief", () => {
+	test("injeta a seção de estrutura com delta e impacto", async () => {
+		const before = await factsOf("export function a(value: string): void {}\n");
+		const after = await factsOf(
+			"export function a(value: number): void {}\nexport const b = 1;\n",
+		);
+		const delta = computeDelta(
+			before,
+			after,
+			"@@ -1 +1,2 @@\n-export function a(value: string): void {}\n+export function a(value: number): void {}\n+export const b = 1;",
+		);
+		const watchdog = defineWatchdog({
+			id: "alpha",
+			name: "Alpha",
+			description: "Watchdog de teste.",
+			scope: "src/**",
+			classify: [{ value: "^src/" }],
+			rules: [{ severity: "attention", text: "Promover: algo." }],
+			contextFiles: ["AGENTS.md"],
+		});
+
+		const brief = renderBrief(watchdog, {
+			watchdogId: "alpha",
+			files: ["src/a.ts"],
+			statuses: { "src/a.ts": { status: "modified" } },
+			deleted: [],
+			branch: "main",
+			outputPath: "/tmp/a.json",
+			outputFormatPath: "/tmp/OUTPUT-FORMAT.md",
+			docs: [],
+			ast: [{ file: "src/a.ts", delta, importers: ["src/b.ts"] }],
+		});
+
+		expect(brief).toContain("## Estrutura (AST)");
+		expect(brief).toContain("assinatura `a`");
+		expect(brief).toContain("impacto: `src/b.ts`");
+	});
+});
+
+describe("AstService (integração)", () => {
+	test("analisa delta e descobre importadores via git grep", async () => {
+		const cwd = mkdtempSync(join(tmpdir(), "houndsman-ast-"));
+		const originalCwd = process.cwd();
+		const git = (args: string[]): string => runGit(args);
+
+		try {
+			process.chdir(cwd);
+			git(["init"]);
+			git(["config", "user.email", "test@example.com"]);
+			git(["config", "user.name", "Test"]);
+			git(["config", "commit.gpgsign", "false"]);
+			mkdirSync("src", { recursive: true });
+			writeFileSync(
+				"src/db.ts",
+				"export function connect(url: string): string { return url; }\n",
+			);
+			writeFileSync(
+				"src/orders.ts",
+				'import { connect } from "./db";\nexport function load(): string { return connect("x"); }\n',
+			);
+			git(["add", "."]);
+			git(["commit", "-m", "base"]);
+
+			writeFileSync(
+				"src/db.ts",
+				"export function connect(url: string, timeout: number): string { return url; }\n",
+			);
+			git(["add", "."]);
+			git(["commit", "-m", "change"]);
+
+			const config = defineHoundsmanConfig({
+				projectName: "AST",
+				watchdogs: {
+					alpha: defineWatchdog({
+						id: "alpha",
+						name: "Alpha",
+						description: "Teste.",
+						scope: "src/**",
+						classify: [{ value: "^src/" }],
+						rules: [{ severity: "attention", text: "Promover: algo." }],
+						contextFiles: ["AGENTS.md"],
+					}),
+				},
+				exclusions: [],
+				docMappings: [],
+				ast: { aliases: {} },
+			});
+
+			const diff = collectDiff("HEAD~1", "HEAD");
+			const entries = parseEntries(git(["diff", "HEAD~1...HEAD", "--name-status"]));
+			const service = new AstService(config, new GitRepository());
+			const analyses = await service.analyze(entries, diff, "HEAD~1");
+
+			const changed = analyses.get("src/db.ts");
+			expect(changed?.delta?.changedSignatures[0]?.name).toBe("connect");
+			expect(changed?.delta?.changedSignatures[0]?.exported).toBe(true);
+
+			const impact = await service.impact(analyses);
+			expect(impact.importers["src/db.ts"]).toEqual(["src/orders.ts"]);
+			expect(impact.affectedFiles).toEqual(["src/orders.ts"]);
+			expect(impact.exportedChanges).toContainEqual({
+				file: "src/db.ts",
+				symbol: "connect",
+				change: "signature",
+			});
+		} finally {
+			process.chdir(originalCwd);
+			rmSync(cwd, { recursive: true, force: true });
+		}
+	}, 30_000);
+});

package/src/tests/env.test.ts

@@ -0,0 +1,69 @@
+/**
+ * Testes do ambiente tipado (`core/env.ts`).
+ *
+ * Nenhum valor secreto é impresso; os testes apenas exercitam leitura,
+ * normalização e restauração das variáveis.
+ */
+
+import { afterEach, describe, expect, test } from "bun:test";
+import { ENV_NAMES, env, readEnv } from "../core/env";
+
+const original = {
+	typeSafe: process.env[ENV_NAMES.typeSafeApiKey],
+	deepSeek: process.env[ENV_NAMES.deepSeekApiKey],
+	home: process.env[ENV_NAMES.home],
+	localAppData: process.env[ENV_NAMES.localAppData],
+	xdgDataHome: process.env[ENV_NAMES.xdgDataHome],
+};
+
+afterEach(() => {
+	restore(ENV_NAMES.typeSafeApiKey, original.typeSafe);
+	restore(ENV_NAMES.deepSeekApiKey, original.deepSeek);
+	restore(ENV_NAMES.home, original.home);
+	restore(ENV_NAMES.localAppData, original.localAppData);
+	restore(ENV_NAMES.xdgDataHome, original.xdgDataHome);
+});
+
+function restore(name: string, value: string | undefined): void {
+	if (value === undefined) delete process.env[name];
+	else process.env[name] = value;
+}
+
+describe("env", () => {
+	test("lê as chaves canônicas, apara espaços e trata vazio como ausente", () => {
+		process.env[ENV_NAMES.typeSafeApiKey] = "  key-1  ";
+		process.env[ENV_NAMES.deepSeekApiKey] = "";
+		process.env[ENV_NAMES.home] = "  /tmp/houndsman  ";
+
+		const snapshot = readEnv();
+		expect(snapshot.typeSafeApiKey).toBe("key-1");
+		expect(snapshot.deepSeekApiKey).toBeUndefined();
+		expect(snapshot.home).toBe("/tmp/houndsman");
+	});
+
+	test("getters refletem alterações em runtime", () => {
+		process.env[ENV_NAMES.deepSeekApiKey] = "ds-1";
+		expect(env.deepSeekApiKey).toBe("ds-1");
+		process.env[ENV_NAMES.deepSeekApiKey] = "ds-2";
+		expect(env.deepSeekApiKey).toBe("ds-2");
+	});
+
+	test("variável ausente vira undefined", () => {
+		delete process.env[ENV_NAMES.typeSafeApiKey];
+		expect(env.typeSafeApiKey).toBeUndefined();
+	});
+
+	test("chaves de integração usam o prefixo HOUNDSMAN_", () => {
+		const native = new Set([
+			"LOCALAPPDATA",
+			"XDG_DATA_HOME",
+			"NO_COLOR",
+			"TERM",
+			"CI",
+		]);
+		for (const name of Object.values(ENV_NAMES)) {
+			if (native.has(name)) continue;
+			expect(name.startsWith("HOUNDSMAN_")).toBe(true);
+		}
+	});
+});

package/src/tests/fallback.test.ts

@@ -0,0 +1,172 @@
+/**
+ * Fallback de classificação e findings emergentes (lógica/domínio).
+ */
+
+import { describe, expect, test } from "bun:test";
+import { defineHoundsmanConfig } from "../core/config";
+import { classifyEntries } from "../core/file-classifier";
+import { checkRegistry } from "../core/registry-check";
+import { defineWatchdog } from "../core/types";
+import { AgentState } from "../harness/investigation/agent-state";
+import { EvidenceVerifier } from "../harness/investigation/evidence-verifier";
+import { FindingCritic } from "../harness/investigation/finding-critic";
+import { FindingValidator } from "../harness/validation/finding-validator";
+
+const alpha = defineWatchdog({
+	id: "alpha",
+	name: "Alpha",
+	description: "Domínio alpha.",
+	scope: "src/alpha/**",
+	classify: [{ value: "^src/alpha/" }],
+	rules: [{ severity: "blocking", text: "Nunca usar any." }],
+	contextFiles: [],
+});
+
+const fallback = defineWatchdog({
+	id: "default",
+	name: "Padrões gerais",
+	description: "Fallback de lógica/domínio.",
+	scope: "arquivos sem dono",
+	fallback: true,
+	allowEmergentFindings: true,
+	rules: [
+		{
+			severity: "attention",
+			text: "Promover: a lógica do domínio respeita as invariantes.",
+		},
+	],
+	contextFiles: [],
+});
+
+const config = defineHoundsmanConfig({
+	projectName: "Fallback",
+	watchdogs: { alpha, default: fallback },
+	exclusions: [],
+	docMappings: [],
+});
+
+describe("classificação com fallback", () => {
+	test("arquivo sem dono vai para o fallback; com dono fica no domínio", () => {
+		const result = classifyEntries(
+			[
+				{ path: "src/alpha/a.ts", status: "modified" },
+				{ path: "src/other/b.ts", status: "modified" },
+			],
+			config,
+			{},
+		);
+		expect(result.watchdogs.alpha).toEqual(["src/alpha/a.ts"]);
+		expect(result.watchdogs.default).toEqual(["src/other/b.ts"]);
+		expect(result.unclassified).toEqual([]);
+	});
+
+	test("múltiplos fallbacks geram warning (primeiro vence)", () => {
+		const second = defineWatchdog({
+			...fallback,
+			id: "default2",
+		});
+		const duplicated = defineHoundsmanConfig({
+			...config,
+			watchdogs: { ...config.watchdogs, default2: second },
+		});
+		const result = classifyEntries(
+			[{ path: "src/other/b.ts", status: "modified" }],
+			duplicated,
+			{},
+		);
+		expect(result.watchdogs.default).toEqual(["src/other/b.ts"]);
+		expect(result.watchdogs.default2).toBeUndefined();
+		const { warnings } = checkRegistry(duplicated);
+		expect(
+			warnings.some((item) => item.includes("Mais de um watchdog fallback")),
+		).toBe(true);
+	});
+});
+
+describe("findings emergentes", () => {
+	const file = "a.ts";
+	const content = "const x = 1;\n";
+	const state = new AgentState();
+	const evidence = state.addEvidence({
+		file,
+		startLine: 1,
+		endLine: 1,
+		snippet: content.trim(),
+		kind: "definition",
+		sourceTool: "test",
+		confidence: 0.9,
+	});
+	const draft = {
+		rule: "Lógica: a função fazA na verdade fazB",
+		severity: "blocking" as const,
+		file,
+		line: 1,
+		message: "comportamento diverge do nome",
+		action: "renomear ou corrigir",
+		evidenceIds: [evidence.id],
+		confidence: 0.9,
+	};
+	const verifier = new EvidenceVerifier({
+		allowedFiles: [file],
+		readFile: (path) => (path === file ? content : null),
+	});
+
+	test("crítico aceita e limita a severidade quando habilitado", () => {
+		const critic = new FindingCritic({
+			knownRules: new Set([fallback.rules[0]?.text ?? ""]),
+			verifier,
+			allowEmergentFindings: true,
+		});
+		const decision = critic.reviewOne(draft, state);
+		expect(decision.verdict).toBe("keep");
+		expect(decision.draft.severity).toBe("attention");
+	});
+
+	test("crítico descarta quando o opt-in está desligado", () => {
+		const critic = new FindingCritic({
+			knownRules: new Set([fallback.rules[0]?.text ?? ""]),
+			verifier,
+		});
+		const decision = critic.reviewOne(draft, state);
+		expect(decision.verdict).toBe("drop");
+		expect(decision.reason).toContain("desabilitado");
+	});
+
+	test("validador espelha a mesma regra", () => {
+		const report = {
+			watchdogId: "default",
+			reviewedFiles: [file],
+			skipped: [],
+			findings: [draft],
+		};
+		const allowed = new FindingValidator({
+			watchdogId: "default",
+			knownRules: new Set([fallback.rules[0]?.text ?? ""]),
+			allowedFiles: new Set([file]),
+			overflow: new Set(),
+			readFile: (path) => (path === file ? content : null),
+			allowEmergentFindings: true,
+		}).validate(report);
+		expect(allowed.report.findings[0]?.severity).toBe("attention");
+		expect(allowed.dropped).toHaveLength(0);
+
+		const denied = new FindingValidator({
+			watchdogId: "default",
+			knownRules: new Set([fallback.rules[0]?.text ?? ""]),
+			allowedFiles: new Set([file]),
+			overflow: new Set(),
+			readFile: (path) => (path === file ? content : null),
+		}).validate(report);
+		expect(denied.report.findings).toHaveLength(0);
+	});
+
+	test("finding emergente sem descrição é descartado", () => {
+		const critic = new FindingCritic({
+			knownRules: new Set([fallback.rules[0]?.text ?? ""]),
+			verifier,
+			allowEmergentFindings: true,
+		});
+		const decision = critic.reviewOne({ ...draft, rule: "Lógica:" }, state);
+		expect(decision.verdict).toBe("drop");
+	});
+});

package/src/tests/fixtures/fake-agent-tools.ts

@@ -0,0 +1,69 @@
+/**
+ * Tools fake para a suíte do harness.
+ */
+
+import { z } from "zod";
+import type {
+	AgentTool,
+	ToolContext,
+	ToolMetadata,
+	ToolResult,
+} from "../../harness/tools/agent-tool";
+
+/** Tool de eco (testa registry/middleware). */
+export class EchoTool implements AgentTool<{ value: string }, { value: string }> {
+	readonly metadata: ToolMetadata = {
+		name: "echo",
+		description: "Devolve o valor recebido.",
+		category: "context",
+		capabilities: ["read"],
+		readOnly: true,
+		cost: 1,
+		cacheTtlMs: 60_000,
+	};
+
+	readonly inputSchema = z.object({ value: z.string() });
+
+	async execute(
+		input: { value: string },
+		_context: ToolContext,
+	): Promise<ToolResult<{ value: string }>> {
+		return { ok: true, data: { value: input.value } };
+	}
+}
+
+/** Tool que produz evidência para o estado. */
+export class EvidenceTool implements AgentTool<{ file: string }, unknown> {
+	readonly metadata: ToolMetadata = {
+		name: "evidence",
+		description: "Produz uma evidência fake.",
+		category: "evidence",
+		capabilities: ["read"],
+		readOnly: true,
+		cost: 1,
+	};
+
+	readonly inputSchema = z.object({ file: z.string() });
+
+	async execute(
+		input: { file: string },
+		_context: ToolContext,
+	): Promise<ToolResult<unknown>> {
+		return {
+			ok: true,
+			data: { file: input.file },
+			evidence: [
+				{
+					id: "",
+					file: input.file,
+					startLine: 1,
+					endLine: 1,
+					snippet: "const x: any = 1;",
+					kind: "definition",
+					sourceTool: "evidence",
+					confidence: 0.9,
+				},
+			],
+		};
+	}
+}