@payconductor/houndsman 0.4.0 → 0.6.0

package/src/tests/__snapshots__/baseline.test.ts.snap

@@ -88,23 +88,6 @@ exports[`baseline — relatório renderReport consolidado 1`] = `
 - Faz A
 - Remove B
 
-## ❌ blocking
-
-### \`src/alpha/a.ts\`
-
-- **Nunca usar \`any\`.** — \`src/alpha/a.ts:1\` · _Alpha_ · \`id-alpha\`
-  any detectado
-  **Ação:** tipar
-  **Evidência:** \`export const a: any = 1;\`
-
-## ⚠️ attention
-
-### \`src/alpha/b.ts\`
-
-- **Promover: validar a entrada.** — \`src/alpha/b.ts:2\` · _Alpha, Beta_ · \`id-beta\`
-  sem validação
-  **Ação:** adicionar schema
-
 ## Relatórios por domínio
 
 | Watchdog | Achados | Revisados | Relatório |
@@ -121,7 +104,25 @@ exports[`baseline — relatório renderReport consolidado 1`] = `
 ## Conclusão
 
 **Status:** ❌ Mudanças Necessárias
-**Resumo:** 1 violações bloqueantes, 1 pontos de atenção, 0 sugestões e 0 nits."
+**Resumo:** 1 violações bloqueantes, 1 pontos de atenção, 0 sugestões e 0 nits.
+
+## ❌ blocking
+
+### \`src/alpha/a.ts\`
+
+- **Nunca usar \`any\`.** — \`src/alpha/a.ts:1\` · _Alpha_ · \`id-alpha\`
+  any detectado
+  **Ação:** tipar
+  **Evidência:** \`export const a: any = 1;\`
+
+## ⚠️ attention
+
+### \`src/alpha/b.ts\`
+
+- **Promover: validar a entrada.** — \`src/alpha/b.ts:2\` · _Alpha, Beta_ · \`id-beta\`
+  sem validação
+  **Ação:** adicionar schema
+"
 `;
 
 exports[`baseline — relatório renderDomainReport isolado 1`] = `
@@ -171,6 +172,10 @@ exports[`baseline — camada gerada setup gera os mesmos arquivos e conteúdos 1
   ".agents/skills/houndsman/SKILL.md",
   ".claude/skills/houndsman/SKILL.md",
   ".houndsman/.gitignore",
+  ".houndsman/core/grammars/tree-sitter-javascript.wasm",
+  ".houndsman/core/grammars/tree-sitter-tsx.wasm",
+  ".houndsman/core/grammars/tree-sitter-typescript.wasm",
+  ".houndsman/core/grammars/web-tree-sitter.wasm",
   ".houndsman/core/skill/AUDIT-PROTOCOL.md",
   ".houndsman/core/skill/OUTPUT-FORMAT.md",
   ".houndsman/core/skill/README.md",
@@ -183,6 +188,7 @@ exports[`baseline — camada gerada setup gera os mesmos arquivos e conteúdos 1
   ".houndsman/core/types.ts",
   ".houndsman/doc-mappings.ts",
   ".houndsman/exclusions.ts",
+  ".houndsman/watchdogs/default.ts",
   ".houndsman/watchdogs/example.ts",
   ".houndsman/watchdogs/index.ts",
   "houndsman.config.ts",
@@ -329,11 +335,21 @@ export type Rule = {
 	severity: Severity;
 	text: string;
 	jev?: JevRuleSpec;
+	hints?: RuleHints;
+};
+
+/** Sinais opcionais de uma regra (símbolos, imports, decorators, paths, checks). */
+export type RuleHints = {
+	symbols?: string[];
+	imports?: string[];
+	decorators?: string[];
+	paths?: string[];
+	checks?: string[];
 };
 
 /** Como o watchdog casa um arquivo alterado. \`value\` é sempre regex. */
 export type ClassifyRule = {
-	type?: "filename" | "content";
+	type?: "filename" | "content" | "symbol" | "import" | "export" | "decorator";
 	value: string;
 };
 
@@ -350,6 +366,10 @@ export type WatchdogDefinition = WatchdogMeta & {
 	id: string;
 	description: string;
 	breakingChange?: boolean;
+	/** Só assume arquivos que nenhum outro watchdog casou. */
+	fallback?: boolean;
+	/** Permite findings emergentes (Lógica:/Domínio:) fora das regras. */
+	allowEmergentFindings?: boolean;
 	reviewFocus?: readonly string[];
 	exclude?: readonly string[];
 };
@@ -388,6 +408,54 @@ export type HoundsmanStorage = {
 	path?: string;
 };
 
+/** Linguagens suportadas pelo AST na primeira fase. */
+export type AstLanguage = "typescript" | "tsx" | "javascript";
+
+/** Configuração do AST determinístico (classificação estrutural, brief e impacto). */
+export type HoundsmanAst = {
+	enabled?: boolean;
+	maxFileBytes?: number;
+	maxImpactFiles?: number;
+	languages?: Record<string, AstLanguage>;
+	aliases?: Record<string, string>;
+};
+
+/** Providers suportados pela camada de IA. */
+export type AiProviderKind = "deepseek" | "openai" | "anthropic";
+
+/** Features de IA do fluxo normal (todas fail-open). */
+export type HoundsmanAiFeatures = {
+	context?: boolean;
+	brief?: boolean;
+	classification?: boolean;
+	preAnalysis?: boolean;
+	verify?: boolean;
+};
+
+/** Overrides de IA por watchdog. */
+export type HoundsmanAiWatchdog = {
+	model?: string;
+	maxSteps?: number;
+	maxOutputTokens?: number;
+};
+
+/** Configuração da camada de IA (briefs, contexto, classificação e hunt nativo). */
+export type HoundsmanAi = {
+	enabled?: boolean;
+	provider?: AiProviderKind;
+	model?: string;
+	baseURL?: string;
+	concurrency?: number;
+	maxSteps?: number;
+	maxOutputTokens?: number;
+	temperature?: number;
+	timeoutMs?: number;
+	maxCallsPerReview?: number;
+	maxTokensPerReview?: number;
+	features?: HoundsmanAiFeatures;
+	watchdogs?: Record<string, HoundsmanAiWatchdog>;
+};
+
 /** Contrato de configuração do motor. */
 export type HoundsmanConfig<TId extends string = string> = {
 	projectName: string;
@@ -399,6 +467,8 @@ export type HoundsmanConfig<TId extends string = string> = {
 	alwaysIncludeDocs?: readonly string[];
 	budgets?: HoundsmanBudgets;
 	concurrency?: HoundsmanConcurrency;
+	ast?: HoundsmanAst;
+	ai?: HoundsmanAi;
 };
 
 /** Helper de autoria (identidade) — apenas tipagem. */
@@ -418,9 +488,10 @@ export function defineHoundsmanConfig<TId extends string>(
 "/**
  * Mapeamento de padrões nos paths → documentação relevante.
  * Consumido pelo motor via \`HoundsmanConfig.docMappings\`.
- */\`core/\` é regenerado por \`houndsman update\`.
-# Runs, findings e artefatos vivem no storage global (fora do projeto).
-core
+ *
+ * Exemplo: [/^src\\//, ["README.md"]]
+ */
+export const DOC_MAPPINGS: readonly (readonly [RegExp, readonly string[]])[] = [];
 "
 ,
   ".houndsman/exclusions.ts": 
@@ -443,7 +514,8 @@ export function isExcluded(filePath: string): boolean {
 
 /**
  * Watchdog de exemplo — substitua pelas regras reais do projeto.
- * Um watchdog declara seus arquivos via \`classify\` (regex de path ou conteúdo).
+ * Um watchdog declara seus arquivos via \`classify\` (regex de path, conteúdo ou
+ * fatos AST: \`symbol\`/\`import\`/\`export\`/\`decorator\`).
  * O texto de cada regra começa com a polaridade: \`Promover:\` (DEVE acontecer)
  * ou \`Evitar:\`/\`Não\`/\`Nunca\` (NÃO DEVE acontecer).
  */
@@ -451,8 +523,8 @@ export const exampleWatchdog = defineWatchdog({
 	id: "example",
 	name: "Exemplo",
 	description: "Watchdog de exemplo — descreva o propósito em uma frase.",
-	scope: "Todo o repositório (ajuste o escopo)",
-	classify: [{ value: "^src/" }],
+	scope: "src/example/** (ajuste o escopo)",
+	classify: [{ value: "^src/example/" }],
 	rules: [
 		{
 			severity: "attention",
@@ -469,13 +541,15 @@ export const exampleWatchdog = defineWatchdog({
 "
 ,
   ".houndsman/watchdogs/index.ts": 
-"import { exampleWatchdog } from "./example";
+"import { defaultWatchdog } from "./default";
+import { exampleWatchdog } from "./example";
 
 /**
  * Definições dos watchdogs — as chaves definem o union \`WatchdogId\`.
  * Adicionar um watchdog = criar \`<id>.ts\` e registrá-lo aqui.
  */
 export const WATCHDOG_DEFINITIONS = {
+	default: defaultWatchdog,
 	example: exampleWatchdog,
 };
 
@@ -516,7 +590,7 @@ exports[`baseline — camada gerada setup gera os mesmos arquivos e conteúdos 3
   },
   {
     "file": ".houndsman/core/skill/OUTPUT-FORMAT.md",
-    "sha256": "06aedccd5688aaa8",
+    "sha256": "94ea2b8def871784",
   },
   {
     "file": ".houndsman/core/skill/README.md",
@@ -524,11 +598,11 @@ exports[`baseline — camada gerada setup gera os mesmos arquivos e conteúdos 3
   },
   {
     "file": ".houndsman/core/skill/SETUP.md",
-    "sha256": "7ce23b97d9609ac2",
+    "sha256": "b74af7e1979bf1b4",
   },
   {
     "file": ".houndsman/core/skill/example-review.md",
-    "sha256": "a2627e99ac5caead",
+    "sha256": "d9e75054cc9811dc",
   },
   {
     "file": ".houndsman/core/skill/fix.md",
@@ -536,7 +610,7 @@ exports[`baseline — camada gerada setup gera os mesmos arquivos e conteúdos 3
   },
   {
     "file": ".houndsman/core/skill/hunt.md",
-    "sha256": "c47a24c6c36c1c03",
+    "sha256": "b55507d62d3c1fcd",
   },
   {
     "file": ".houndsman/core/skill/train.md",
@@ -544,7 +618,7 @@ exports[`baseline — camada gerada setup gera os mesmos arquivos e conteúdos 3
   },
   {
     "file": ".houndsman/core/skill/verify.md",
-    "sha256": "7ae6e1ca8bf0a868",
+    "sha256": "780f4b078daa104b",
   },
 ]
 `;
@@ -554,6 +628,7 @@ exports[`baseline — artefatos de prepare/finalize gera classification, brief,
 Briefs: <cwd>/.home/work/<uuid>/briefs/
 Deletado (breaking change): src/alpha/old.ts
 Jev: pulado (desativado (--no-jev)).
+AST: desabilitado ou sem grammar compatível.
 Sem contexto da PR (rode \`bun run houndsman context\` antes, se houver PR).
 
 Próximo passo: despachar os sub-agentes (um por brief em <cwd>/.home/work/<uuid>/briefs/).
@@ -602,8 +677,6 @@ exports[`baseline — artefatos de prepare/finalize gera classification, brief,
     "alpha": 2
   },
   "excludedCount": 0,
-  "base": "<sha>",
-  "head": "HEAD",
   "headSha": "<sha>",
   "mode": "full"
 }
@@ -649,6 +722,16 @@ exports[`baseline — artefatos de prepare/finalize gera classification, brief,
     "available": false,
     "reason": "desativado (--no-jev)"
   },
+  "ast": {
+    "enabled": false,
+    "languages": [],
+    "files": 0,
+    "impact": {
+      "affectedFiles": 0,
+      "importers": 0,
+      "exportedChanges": 0
+    }
+  },
   "deleted": [
     "src/alpha/old.ts"
   ],
@@ -713,15 +796,6 @@ exports[`baseline — artefatos de prepare/finalize gera classification, brief,
 **Watchdogs ativos:** alpha
 **Achados:** 1 bloqueantes · 0 atenção · 0 sugestões · 0 nits
 
-## ❌ blocking
-
-### \`src/alpha/a.ts\`
-
-- **Nunca usar \`any\`.** — \`src/alpha/a.ts:1\` · _Alpha_ · \`<id>\`
-  any detectado
-  **Ação:** tipar
-  **Evidência:** \`export const a: any = 1;\`
-
 ## Relatórios por domínio
 
 | Watchdog | Achados | Revisados | Relatório |
@@ -738,6 +812,16 @@ exports[`baseline — artefatos de prepare/finalize gera classification, brief,
 
 **Status:** ❌ Mudanças Necessárias
 **Resumo:** 1 violações bloqueantes, 0 pontos de atenção, 0 sugestões e 0 nits.
+
+## ❌ blocking
+
+### \`src/alpha/a.ts\`
+
+- **Nunca usar \`any\`.** — \`src/alpha/a.ts:1\` · _Alpha_ · \`<id>\`
+  any detectado
+  **Ação:** tipar
+  **Evidência:** \`export const a: any = 1;\`
+
 "
 `;
 

package/src/tests/ai-core.test.ts

@@ -0,0 +1,120 @@
+/**
+ * Fundação de IA: cliente fail-open, budget, provider fake e config.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { z } from "zod";
+import { AiClient, AiUsageBudget, AiUsageRecorder } from "../core/ai";
+import { defineHoundsmanConfig } from "../core/config";
+import { DEFAULT_AI_MODEL } from "../core/defaults";
+import { ProjectConfig } from "../core/project-config";
+import { checkRegistry } from "../core/registry-check";
+import { FakeModelProvider } from "./fixtures/fake-model-provider";
+import { fakeHoundsmanConfig } from "./fixtures/fake-project";
+
+const project = new ProjectConfig(fakeHoundsmanConfig);
+
+describe("config de IA", () => {
+	test("modelo default do DeepSeek é 4.1 flash", () => {
+		expect(DEFAULT_AI_MODEL).toBe("deepseek-v4.1-flash");
+		expect(project.aiModel).toBe("deepseek-v4.1-flash");
+	});
+});
+
+describe("AiClient", () => {
+	test("sem provider/chave → indisponível e fail-open", async () => {
+		const client = new AiClient({ project, provider: null });
+		expect(client.available).toBe(false);
+		const result = await client.generateObject("x", {
+			prompt: "oi",
+			outputSchema: z.object({ ok: z.boolean() }),
+		});
+		expect(result.ok).toBe(false);
+	});
+
+	test("provider fake devolve saída, uso e registra no recorder", async () => {
+		const provider = new FakeModelProvider(() => ({ ok: true }));
+		const client = new AiClient({ project, provider });
+		expect(client.available).toBe(true);
+		const result = await client.generateObject("context", {
+			prompt: "oi",
+			outputSchema: z.object({ ok: z.boolean() }),
+		});
+		expect(result.ok).toBe(true);
+		if (result.ok) expect(result.output.ok).toBe(true);
+		expect(client.recorder.total.calls).toBe(1);
+		expect(provider.calls).toBe(1);
+	});
+
+	test("budget estourado vira fail-open sem chamar o provider", async () => {
+		const provider = new FakeModelProvider(() => ({ ok: true }));
+		const client = new AiClient({
+			project,
+			provider,
+			budget: new AiUsageBudget({ maxCalls: 0 }),
+		});
+		const result = await client.generateObject("x", {
+			prompt: "oi",
+			outputSchema: z.object({ ok: z.boolean() }),
+		});
+		expect(result.ok).toBe(false);
+		expect(provider.calls).toBe(0);
+	});
+	describe("validateCredential", () => {
+		test("ok, inválida e ausente", async () => {
+			const okClient = new AiClient({
+				project,
+				provider: new FakeModelProvider(() => "OK"),
+			});
+			expect((await okClient.validateCredential()).kind).toBe("ok");
+
+			const invalid = new AiClient({
+				project,
+				provider: new FakeModelProvider(() => {
+					throw new Error("401 invalid api key");
+				}),
+			});
+			expect((await invalid.validateCredential()).kind).toBe("invalid");
+
+			const missing = new AiClient({ project, provider: null });
+			expect((await missing.validateCredential()).kind).toBe("missing");
+		});
+	});
+});
+
+describe("AiUsageBudget / AiUsageRecorder", () => {
+	test("acumula uso e bloqueia no teto", () => {
+		const budget = new AiUsageBudget({ maxCalls: 2 });
+		budget.record({ inputTokens: 1, outputTokens: 1, totalTokens: 2, calls: 1 });
+		budget.record({ inputTokens: 1, outputTokens: 1, totalTokens: 2, calls: 1 });
+		expect(budget.canCall).toBe(false);
+		expect(() => budget.assertCanCall()).toThrow();
+	});
+
+	test("recorder serializa total e entradas", () => {
+		const recorder = new AiUsageRecorder("deepseek", "fake");
+		recorder.record("brief", "fake", {
+			inputTokens: 10,
+			outputTokens: 5,
+			totalTokens: 15,
+			calls: 1,
+		});
+		const data = recorder.toJSON();
+		expect(data.total.calls).toBe(1);
+		expect(data.total.totalTokens).toBe(15);
+		expect(data.entries[0]?.feature).toBe("brief");
+		expect(recorder.serialize()).toContain('"calls": 1');
+	});
+});
+
+describe("checkRegistry (IA)", () => {
+	test("provider inválido é problema; budgets inválidos são aviso", () => {
+		const config = defineHoundsmanConfig({
+			...fakeHoundsmanConfig,
+			ai: { provider: "nope" as never, concurrency: 0 },
+		});
+		const { problems, warnings } = checkRegistry(config);
+		expect(problems.some((item) => item.includes("ai.provider"))).toBe(true);
+		expect(warnings.some((item) => item.includes("ai.concurrency"))).toBe(true);
+	});
+});

package/src/tests/ai-features.test.ts

@@ -0,0 +1,183 @@
+/**
+ * Features de IA do fluxo normal (brief, contexto, classificação, verify).
+ */
+
+import { describe, expect, test } from "bun:test";
+import { AiClient } from "../core/ai";
+import { AiBriefEnricher } from "../core/ai/features/brief-enricher";
+import { AiClassifier } from "../core/ai/features/classifier";
+import { AiContextSummarizer } from "../core/ai/features/context-summarizer";
+import { AiPreAnalyzer } from "../core/ai/features/pre-analyzer";
+import { AiVerifier } from "../core/ai/features/verifier";
+import { briefInstructions, briefPrompt } from "../core/ai/prompts/brief";
+import { renderBrief } from "../core/brief";
+import { ProjectConfig } from "../core/project-config";
+import { FakeModelProvider } from "./fixtures/fake-model-provider";
+import { fakeHoundsmanConfig } from "./fixtures/fake-project";
+
+const project = new ProjectConfig(fakeHoundsmanConfig);
+const alpha = fakeHoundsmanConfig.watchdogs.alpha;
+
+describe("AiBriefEnricher", () => {
+	test("devolve o plano do modelo", async () => {
+		const provider = new FakeModelProvider(() => ({
+			focus: ["checar any"],
+			questions: ["há any?"],
+			risks: ["tipagem fraca"],
+		}));
+		const enricher = new AiBriefEnricher(new AiClient({ project, provider }));
+		const plan = await enricher.enrich({
+			watchdogId: "alpha",
+			name: "Alpha",
+			description: "x",
+			scope: "src/alpha",
+			rules: alpha.rules,
+			files: ["src/alpha/a.ts"],
+		});
+		expect(plan?.focus[0]).toBe("checar any");
+	});
+
+	test("sem IA → null (brief inalterado)", async () => {
+		const enricher = new AiBriefEnricher(new AiClient({ project, provider: null }));
+		expect(enricher.enabled).toBe(false);
+		expect(
+			await enricher.enrich({
+				watchdogId: "alpha",
+				name: "Alpha",
+				description: "x",
+				scope: "src/alpha",
+				rules: alpha.rules,
+				files: [],
+			}),
+		).toBeNull();
+	});
+
+	test("brief com aiPlan ganha a seção de sugestão", () => {
+		const args = {
+			watchdogId: "alpha",
+			files: ["src/alpha/a.ts"],
+			statuses: { "src/alpha/a.ts": { status: "modified" as const } },
+			deleted: [],
+			branch: "main",
+			outputPath: "findings/alpha.json",
+			outputFormatPath: "OUTPUT-FORMAT.md",
+			docs: [],
+			aiPlan: {
+				focus: ["foco"],
+				questions: ["pergunta"],
+				risks: ["risco"],
+				logic: [],
+				domain: [],
+			},
+		};
+		const markdown = renderBrief(alpha, args);
+		expect(markdown).toContain("## Plano de revisão (IA)");
+		expect(markdown).toContain("foco");
+	});
+
+	test("brief sem aiPlan é byte-idêntico ao render sem a seção", () => {
+		const base = {
+			watchdogId: "alpha",
+			files: ["src/alpha/a.ts"],
+			statuses: { "src/alpha/a.ts": { status: "modified" as const } },
+			deleted: [],
+			branch: "main",
+			outputPath: "findings/alpha.json",
+			outputFormatPath: "OUTPUT-FORMAT.md",
+			docs: [],
+		};
+		expect(renderBrief(alpha, base)).not.toContain("Plano de revisão (IA)");
+	});
+
+	test("prompt e render incluem lógica e domínio", () => {
+		expect(briefInstructions()).toContain("PISO");
+		const prompt = briefPrompt({
+			watchdogId: "alpha",
+			name: "Alpha",
+			description: "x",
+			scope: "src/alpha",
+			rules: alpha.rules,
+			files: ["src/alpha/a.ts"],
+		});
+		expect(prompt).toContain("Revisão além das regras");
+		const markdown = renderBrief(alpha, {
+			watchdogId: "alpha",
+			files: ["src/alpha/a.ts"],
+			statuses: { "src/alpha/a.ts": { status: "modified" as const } },
+			deleted: [],
+			branch: "main",
+			outputPath: "findings/alpha.json",
+			outputFormatPath: "OUTPUT-FORMAT.md",
+			docs: [],
+			aiPlan: {
+				focus: [],
+				questions: [],
+				risks: [],
+				logic: ["nome vs comportamento"],
+				domain: ["transição de estado"],
+			},
+		});
+		expect(markdown).toContain("Consistência lógica");
+		expect(markdown).toContain("Domínio de negócio");
+	});
+});
+
+describe("AiContextSummarizer", () => {
+	test("resume contexto bruto", async () => {
+		const provider = new FakeModelProvider(() => ({
+			available: true,
+			objective: "Entregar Y",
+			changeSummary: ["Faz X"],
+		}));
+		const summarizer = new AiContextSummarizer(new AiClient({ project, provider }));
+		const summary = await summarizer.summarize('{"title":"PR"}');
+		expect(summary?.objective).toBe("Entregar Y");
+	});
+});
+
+describe("AiClassifier", () => {
+	test("filtra ids e arquivos desconhecidos", async () => {
+		const provider = new FakeModelProvider(() => ({
+			assignments: [
+				{ file: "a.ts", watchdogId: "alpha" },
+				{ file: "a.ts", watchdogId: "nope" },
+				{ file: "b.ts", watchdogId: "alpha" },
+			],
+		}));
+		const classifier = new AiClassifier(new AiClient({ project, provider }));
+		// Feature desligada por default no fake config.
+		expect(classifier.enabled).toBe(false);
+		expect(
+			await classifier.classify(["a.ts"], [{ id: "alpha", name: "A", scope: "x" }]),
+		).toEqual(new Map());
+	});
+});
+
+describe("AiVerifier", () => {
+	test("devolve confiança apenas para ids conhecidos", async () => {
+		const provider = new FakeModelProvider(() => ({
+			verdicts: [
+				{ id: "f1", persisting: true, confidence: 0.9 },
+				{ id: "nope", persisting: false, confidence: 0 },
+			],
+		}));
+		const verifier = new AiVerifier(new AiClient({ project, provider }));
+		expect(verifier.enabled).toBe(false);
+	});
+});
+
+describe("AiPreAnalyzer", () => {
+	test("sem a feature ligada não gera candidatos", async () => {
+		const provider = new FakeModelProvider(() => ({ candidates: [] }));
+		const analyzer = new AiPreAnalyzer(new AiClient({ project, provider }));
+		expect(analyzer.enabled).toBe(false);
+		expect(
+			await analyzer.analyze({
+				watchdogId: "alpha",
+				name: "Alpha",
+				rules: alpha.rules,
+				files: [{ file: "a.ts", snippet: "x" }],
+			}),
+		).toEqual([]);
+	});
+});