@payconductor/houndsman 0.1.0 → 0.1.1

package/src/skill/houndsman-update.md

@@ -225,7 +225,7 @@ todos os itens — em especial: **geral/reutilizável** (não regra de negócio
 ## Verificação (obrigatória)
 
 ```bash
-bun run houndsman doctor     # config sem drift + ambiente
+bun run houndsman doctor     # config sem drift + ambiente + credencial Jev
 bun run houndsman test       # suíte da lib (project-agnóstica)
 bun run ci:fix               # formatação/imports/lint (no repo da lib)
 bun run ci:check             # tipagem (no repo da lib)

package/src/skill/houndsman.md

@@ -79,16 +79,31 @@ Gera em `.houndsman/.runs/<branch-slug>/`:
 
 | Artefato | Conteúdo |
 |---|---|
-| `classification.json` | Watchdogs ativados por arquivo + status (A/M/D/R) |
+| `classification.json` | Watchdogs ativados por arquivo + status (A/M/D/R) + churn |
 | `candidates.json` | Indícios da pré-análise Jev (regra + arquivo + confiança) |
-| `briefs/<watchdog>.md` | Instruções prontas para cada subagente |
-| `manifest.json` | Resumo: watchdogs, arquivos, deletados, status, contexto, Jev |
+| `briefs/<watchdog>.md` | Instruções prontas para cada subagente (arquivos por risco) |
+| `manifest.json` | Resumo: watchdogs, arquivos, deletados, status, contexto, Jev, orçamento |
 
 **Excluídos automaticamente:** lock files, `dist/`, `build/`, `.env*`, imagens, source
 maps (padrões do projeto em `.houndsman/exclusions.ts`).
 **Deletados:** não entram como conteúdo; vão para o brief de watchdogs com
 `breakingChange` como candidatos a **breaking change**.
 
+### Orçamento por brief (PRs grandes)
+
+O motor coleta o diff **uma única vez** (`git diff` + `git diff --numstat`) e classifica
+com **churn** (linhas adicionadas/removidas) por arquivo — o custo não cresce com o nº de
+arquivos da PR. Cada brief recebe no máximo `budgets.maxFilesPerBrief` arquivos (default 40),
+**priorizados pelo maior churn**:
+
+- O excedente vai para a seção **Fora do orçamento (NÃO revisar)** do brief e o watchdog deve
+  registrá-lo em `skipped` — a tabela de **Cobertura** mostra o que ficou de fora (nunca some
+  silenciosamente).
+- Isso mantém o contexto do subagente limitado mesmo num PR de 10k linhas com centenas de
+  arquivos num único domínio.
+- Ajuste em `houndsman.config.ts`: `budgets: { maxFilesPerBrief: 60 }` e
+  `concurrency: { jev: 8 }`. Valores não-positivos caem no default (o `doctor` avisa).
+
 ### Pré-análise Jev (Passo 1.5, opcional)
 
 Se `TYPESAFE_API_KEY` estiver definida, cada arquivo é avaliado pelo modelo **Jev** contra
@@ -96,14 +111,15 @@ as regras atômicas dos watchdogs. Respostas acima do limiar viram **candidatos*
 `candidates.json` e entram no brief como *warm start* — o subagente **confirma ou refuta**.
 
 - **Não é achado**: candidatos não bloqueiam.
-- **Falha-aberto**: sem chave / erro / timeout → `available:false`; a revisão segue idêntica.
+- **Opcional**: sem chave / erro / timeout → `available:false`; a revisão segue idêntica.
 - Desativar: `houndsman --no-jev`.
 
 ---
 
 ## Passo 2 — Revisar (skill despacha os subagentes)
 
-Um subagente por brief, todos no mesmo bloco de tool calls. O prompt é o próprio brief:
+Um subagente por brief. Despache em **ondas** (ex.: até 8 subagentes por bloco de tool
+calls) — evita estourar limites de taxa quando há muitos watchdogs. O prompt é o próprio brief:
 
 ```
 Leia e execute o brief: .houndsman/.runs/<branch-slug>/briefs/<watchdog-id>.md
@@ -111,7 +127,8 @@ Você é o watchdog <watchdog-id> do {{projectName}}.
 ```
 
 Cada subagente grava `findings/<watchdog-id>.json` (schema `.houndsman/core/skill/OUTPUT-FORMAT.md`).
-Sem achados → `"findings": []` (arquivo obrigatório).
+Sem achados → `"findings": []` (arquivo obrigatório). Arquivos na seção **Fora do orçamento**
+não são lidos: registre-os em `skipped`.
 
 **NUNCA enviar:** `git diff` completo · histórico de commits · arquivos de outros domínios ·
 `AGENTS.md` completo (já está no contexto global).
@@ -130,6 +147,50 @@ Falha com mensagem clara se faltar algum `findings/<watchdog>.json`. Quando todo
 3. Agrupa por severidade: ❌ blocking > ⚠️ attention > 💡 suggestion > 🔎 nit
 4. Grava `.houndsman/.runs/<branch-slug>/review.md` + tabela de cobertura
 5. Anexa os candidatos Jev não confirmados em `🔎 Candidatos não verificados` (não bloqueiam)
+6. Agrupa os achados **por arquivo** dentro de cada severidade (navegabilidade em PRs grandes)
+7. Grava um `review.<watchdog>.md` por watchdog com achados e indexa no `review.md`
+   (**Relatórios por domínio**) — mantém o relatório consolidado enxuto
+8. Grava `.houndsman/.runs/<branch-slug>/state.json` — a **triagem**: um `id` curto e um
+   `fingerprint` de conteúdo por finding (Passo 4), preservados entre execuções
+
+> Compatível com `classification.json` antigo: se faltar o churn, o orçamento não é aplicado.
+
+---
+
+## Passo 4 — Triagem (opcional)
+
+Cada finding recebe um `id` curto e um `fingerprint` de **conteúdo** no `--finalize`,
+gravados em `.houndsman/.runs/<branch-slug>/state.json`. A triagem é feita pela UI ou
+pelo agente — sem editar o JSON à mão. Duas dimensões independentes:
+
+- **decision:** `pending` · `execute` · `ignore` (+ `comment` opcional).
+- **execState:** `pending` · `in_progress` · `done` · `stale`.
+
+### UI local
+
+```bash
+houndsman server --open
+```
+
+Abre a UI (Bun.serve + Preact): lista as runs, triar os findings por severidade, comentar,
+marcar como feito e ler os artefatos (`manifest.json`, `classification.json`, `review.md`).
+Bind em `127.0.0.1` (ferramenta local, sem auth).
+
+### Auto-fix pelo agente
+
+```bash
+houndsman findings list --decision execute --json   # pendentes marcados p/ corrigir
+# ... o agente aplica as correções ...
+houndsman findings sync                             # reancora por conteúdo
+houndsman findings done <id>                        # confirma os concluídos
+```
+
+> **A linha não é a identidade.** O auto-fix desloca linhas; o motor reancora cada finding
+> pelo **conteúdo** (trecho + contexto) e não perde itens que se movem. Se a âncora some
+> (o trecho foi corrigido), o finding vira `done` automaticamente quando a decisão era
+> `execute`, ou `stale` caso contrário.
+> Ocorrências byte-idênticas (mesmo trecho E mesmo contexto) compartilham o id — são
+> tratadas como um grupo (`×N`); limitação conhecida.
 
 ---
 
@@ -150,10 +211,17 @@ Falha com mensagem clara se faltar algum `findings/<watchdog>.json`. Quando todo
 - ...
 
 ## ❌ blocking
-- **<regra>** — `arquivo:linha` · _<watchdogs>_
+### `src/routes/order-route.ts`
+- **<regra>** — `src/routes/order-route.ts:5` · _<watchdogs>_
   <mensagem>
   **Ação:** <ação>
 
+## 🔎 Candidatos não verificados (Jev)   ← se houver
+
+## Relatórios por domínio
+| Watchdog | Achados | Revisados | Relatório |
+|---|---|---|---|
+
 ## Cobertura
 | Watchdog | Arquivos revisados | Findings |
 |---|---|---|
@@ -175,7 +243,9 @@ git diff --name-status (base...head)
         ↓
 [2] N subagentes em paralelo   ──►  findings/<watchdog>.json
         ↓
-[3] houndsman --finalize       ──►  review.md
+[3] houndsman --finalize       ──►  review.md + state.json
+        ↓
+[4] triagem (UI ou agente)     ──►  state.json (decision/execState)
 ```
 
 ---
@@ -197,9 +267,11 @@ Se a branch não for informada, detecta com `git branch --show-current`. Base do
 | `houndsman` | Passo 1 — preparar (briefs + manifesto) |
 | `houndsman --finalize` | Passo 3 — gerar o relatório |
 | `houndsman watchdog <id>` | Contexto de um watchdog (`--json`, `--rules`) |
+| `houndsman findings <sub>` | Triagem dos findings (list/show/set/done/reset/sync/summary/path) |
+| `houndsman server` | UI local de triagem + leitura de artefatos (`--port`, `--host`, `--open`) |
 | `houndsman setup` | Cria a configuração inicial do projeto |
 | `houndsman update` | Sincroniza os arquivos auto-gerados (`.houndsman/core`) |
-| `houndsman doctor` | Valida a configuração e o ambiente (anti-drift) |
+| `houndsman doctor` | Valida a configuração, o ambiente e a credencial Jev |
 | `houndsman test` | Suíte de testes da lib |
 
 ---
@@ -208,6 +280,7 @@ Se a branch não for informada, detecta com `git branch --show-current`. Base do
 
 - ❌ Enviar git diff completo para qualquer watchdog
 - ❌ Ativar watchdogs sem arquivos no seu domínio
+- ❌ Revisar arquivos marcados como **Fora do orçamento** (registre-os em `skipped`)
 - ❌ Carregar documentação que o watchdog não precisa
 - ❌ Revisar arquivos gerados (lock files, builds, migrations)
 - ❌ Escrever markdown livre em vez do JSON de `OUTPUT-FORMAT.md`
@@ -225,7 +298,7 @@ Se a branch não for informada, detecta com `git branch --show-current`. Base do
 > skill **`houndsman-update`** (`src/skill/houndsman-update.md`).
 > Regra de ouro: só é regra o que o projeto **aplica hoje** — prove com evidência no código
 > (regra negativa com 0 ocorrências = seguida → **manter**).
-> Após qualquer alteração, rodar `houndsman doctor` (anti-drift) + `houndsman test` + `ci:fix` + `ci:check`.
+> Após qualquer alteração, rodar `houndsman doctor` + `houndsman test` + `ci:fix` + `ci:check`.
 
 ---
 
@@ -237,3 +310,7 @@ Se a branch não for informada, detecta com `git branch --show-current`. Base do
 | Médio (5k linhas) | 4-7 | ~1-2 min |
 | Grande (50k linhas) | 7-10 | ~3-5 min |
 | Enorme (300k linhas) | 10-15 | ~5-8 min |
+
+> O custo de coleta é **constante** (2 execuções de `git`), independente do nº de arquivos.
+> Em PRs muito grandes, o limitante é o nº de subagentes (ondas) e o orçamento por brief —
+> não o diff. Ajuste `budgets.maxFilesPerBrief` para revisar mais/menos arquivos por domínio.

package/src/tests/findings-anchor.test.ts

@@ -0,0 +1,120 @@
+import { describe, expect, test } from "bun:test";
+import {
+	buildAnchor,
+	fingerprintOf,
+	locateAnchor,
+	normalizeLine,
+	reanchor,
+} from "../core/finding-anchor";
+
+const DUPLICATED = [
+	"function a() {",
+	'\tconsole.log("x");',
+	"}",
+	"function b() {",
+	'\tconsole.log("x");',
+	"}",
+].join("\n");
+
+// Após um "auto-fix" que remove o PRIMEIRO console.log.
+const AFTER_FIX = [
+	"function a() {",
+	"}",
+	"function b() {",
+	'\tconsole.log("x");',
+	"}",
+].join("\n");
+
+describe("finding-anchor", () => {
+	test("normalizeLine colapsa espaços e apara as pontas", () => {
+		expect(normalizeLine('  \t console.log( "x" );  ')).toBe('console.log( "x" );');
+		expect(normalizeLine("   ")).toBe("");
+	});
+
+	test("buildAnchor usa a linha quando válida", () => {
+		const anchor = buildAnchor(DUPLICATED, 2);
+		expect(anchor).not.toBeNull();
+		expect(anchor?.snippet).toBe('console.log("x");');
+		expect(anchor?.contextBefore).toBe("function a() {");
+		expect(anchor?.contextAfter).toBe("}");
+		expect(anchor?.line).toBe(2);
+	});
+
+	test("buildAnchor cai na evidence quando a linha é inválida", () => {
+		const anchor = buildAnchor(DUPLICATED, 999, 'console.log("x");');
+		expect(anchor?.line).toBe(2);
+	});
+
+	test("buildAnchor devolve null sem linha válida nem evidence localizável", () => {
+		expect(buildAnchor(DUPLICATED, 999, "inexistente")).toBeNull();
+	});
+
+	test("locateAnchor encontra a linha e conta as ocorrências", () => {
+		const anchor = buildAnchor(DUPLICATED, 2);
+		const located = locateAnchor(DUPLICATED, anchor);
+		expect(located.line).toBe(2);
+		expect(located.occurrences).toBe(1);
+	});
+
+	test("fingerprint é estável e distingue contexto", () => {
+		const a1 = buildAnchor(DUPLICATED, 2);
+		const a2 = buildAnchor(DUPLICATED, 5);
+
+		// Mesmo arquivo + regra + âncora → mesmo fingerprint.
+		expect(fingerprintOf("f.ts", "rule", a1)).toBe(
+			fingerprintOf("f.ts", "rule", buildAnchor(DUPLICATED, 2)),
+		);
+		// Snippet idêntico mas contexto diferente → fingerprints diferentes.
+		expect(fingerprintOf("f.ts", "rule", a1)).not.toBe(
+			fingerprintOf("f.ts", "rule", a2),
+		);
+		// Regra diferente muda o fingerprint.
+		expect(fingerprintOf("f.ts", "outra", a1)).not.toBe(
+			fingerprintOf("f.ts", "rule", a1),
+		);
+	});
+
+	test("fingerprint sem âncora usa o fallback", () => {
+		expect(fingerprintOf("f.ts", "rule", null, "mensagem")).toBe(
+			fingerprintOf("f.ts", "rule", null, "mensagem"),
+		);
+		expect(fingerprintOf("f.ts", "rule", null, "a")).not.toBe(
+			fingerprintOf("f.ts", "rule", null, "b"),
+		);
+	});
+
+	test("reanchor: ok, moved e stale", () => {
+		const anchor = buildAnchor(DUPLICATED, 5);
+		expect(reanchor(DUPLICATED, anchor, 5).status).toBe("ok");
+
+		const moved = reanchor(AFTER_FIX, anchor, 5);
+		expect(moved.status).toBe("moved");
+		expect(moved.line).toBe(4);
+
+		const removed = buildAnchor(DUPLICATED, 2);
+		expect(reanchor(AFTER_FIX, removed, 2).status).toBe("stale");
+	});
+
+	test("duas ocorrências iguais não se perdem quando o fix remove a primeira", () => {
+		const first = buildAnchor(DUPLICATED, 2);
+		const second = buildAnchor(DUPLICATED, 5);
+
+		// A âncora removida vira stale; a sobrevivente apenas desloca de linha.
+		expect(reanchor(AFTER_FIX, first, 2).status).toBe("stale");
+		const survivor = reanchor(AFTER_FIX, second, 5);
+		expect(survivor.status).toBe("moved");
+		expect(survivor.line).toBe(4);
+	});
+
+	test("ocorrências byte-idênticas compartilham o fingerprint (grupo)", () => {
+		// Mesmo snippet E mesmo contexto (sem vizinhos) → mesmo fingerprint.
+		const content = "x\ny\nx\ny";
+		const a1 = buildAnchor(content, 1);
+		const a2 = buildAnchor(content, 3);
+		// contextBefore ausente em ambos (linha 1 vs 3 tem 'y' antes → difere), então
+		// forçamos âncoras sem contexto para simular colisão real.
+		const bare = a1 && { ...a1, contextBefore: undefined, contextAfter: undefined };
+		const bare2 = a2 && { ...a2, contextBefore: undefined, contextAfter: undefined };
+		expect(fingerprintOf("f.ts", "r", bare)).toBe(fingerprintOf("f.ts", "r", bare2));
+	});
+});

package/src/tests/findings-commands.test.ts

@@ -0,0 +1,226 @@
+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 { runFindingsCommand } from "../core/commands/findings";
+import { fakeHoundsmanConfig } from "./fixtures/fake-project";
+
+/** Run fake em disco: classification.json + findings/alpha.json. */
+function makeRun(findings: unknown[]): { dir: string; cleanup: () => void } {
+	const dir = mkdtempSync(join(tmpdir(), "houndsman-findings-"));
+	const outDir = join(dir, "main");
+	mkdirSync(join(outDir, "findings"), { recursive: true });
+	writeFileSync(
+		join(outDir, "classification.json"),
+		JSON.stringify({ watchdogs: { alpha: ["src/alpha/f.ts"] } }),
+	);
+	writeFileSync(
+		join(outDir, "findings", "alpha.json"),
+		JSON.stringify({
+			watchdogId: "alpha",
+			reviewedFiles: ["src/alpha/f.ts"],
+			skipped: [],
+			findings,
+		}),
+	);
+	return { dir, cleanup: () => rmSync(dir, { recursive: true, force: true }) };
+}
+
+const ONE_FINDING = [
+	{
+		rule: "Nunca usar any",
+		severity: "blocking",
+		file: "src/alpha/f.ts",
+		line: 2,
+		message: "any detectado",
+		action: "tipar",
+	},
+];
+
+function run(args: string[]) {
+	return runFindingsCommand(fakeHoundsmanConfig, args);
+}
+
+describe("findings command", () => {
+	test("list reconstrói o estado a partir dos artefatos", () => {
+		const run0 = makeRun(ONE_FINDING);
+		try {
+			const result = run(["list", "--dir", run0.dir, "--branch", "main", "--json"]);
+			expect(result.exitCode).toBe(0);
+			const parsed = JSON.parse(result.output);
+			expect(parsed).toHaveLength(1);
+			expect(parsed[0].decision).toBe("pending");
+			expect(parsed[0].id).toBeTruthy();
+			expect(parsed[0].severity).toBe("blocking");
+		} finally {
+			run0.cleanup();
+		}
+	});
+
+	test("set atualiza decisão + comentário e persiste", () => {
+		const run0 = makeRun(ONE_FINDING);
+		try {
+			const list = JSON.parse(
+				run(["list", "--dir", run0.dir, "--branch", "main", "--json"]).output,
+			);
+			const id = list[0].id;
+
+			const set = run([
+				"set",
+				id,
+				"--decision",
+				"execute",
+				"--comment",
+				"trocar por unknown",
+				"--dir",
+				run0.dir,
+				"--branch",
+				"main",
+			]);
+			expect(set.exitCode).toBe(0);
+
+			const after = JSON.parse(
+				run(["list", "--dir", run0.dir, "--branch", "main", "--json"]).output,
+			);
+			expect(after[0].decision).toBe("execute");
+			expect(after[0].comment).toBe("trocar por unknown");
+			expect(after[0].history.length).toBeGreaterThan(0);
+		} finally {
+			run0.cleanup();
+		}
+	});
+
+	test("done marca execState como done", () => {
+		const run0 = makeRun(ONE_FINDING);
+		try {
+			const id = JSON.parse(
+				run(["list", "--dir", run0.dir, "--branch", "main", "--json"]).output,
+			)[0].id;
+			expect(
+				run(["done", id, "--dir", run0.dir, "--branch", "main"]).exitCode,
+			).toBe(0);
+			const after = JSON.parse(
+				run(["list", "--dir", run0.dir, "--branch", "main", "--json"]).output,
+			);
+			expect(after[0].execState).toBe("done");
+		} finally {
+			run0.cleanup();
+		}
+	});
+
+	test("filtra por decisão e resume contagens", () => {
+		const run0 = makeRun(ONE_FINDING);
+		try {
+			const id = JSON.parse(
+				run(["list", "--dir", run0.dir, "--branch", "main", "--json"]).output,
+			)[0].id;
+			run([
+				"set",
+				id,
+				"--decision",
+				"ignore",
+				"--dir",
+				run0.dir,
+				"--branch",
+				"main",
+			]);
+
+			const pending = JSON.parse(
+				run([
+					"list",
+					"--decision",
+					"pending",
+					"--dir",
+					run0.dir,
+					"--branch",
+					"main",
+					"--json",
+				]).output,
+			);
+			expect(pending).toHaveLength(0);
+
+			const summary = JSON.parse(
+				run(["summary", "--dir", run0.dir, "--branch", "main", "--json"]).output,
+			);
+			expect(summary.total).toBe(1);
+			expect(summary.byDecision.ignore).toBe(1);
+		} finally {
+			run0.cleanup();
+		}
+	});
+
+	test("sync marca como stale quando o arquivo não está disponível", () => {
+		const run0 = makeRun(ONE_FINDING);
+		try {
+			const result = JSON.parse(
+				run(["sync", "--dir", run0.dir, "--branch", "main", "--json"]).output,
+			);
+			expect(result.stale).toHaveLength(1);
+		} finally {
+			run0.cleanup();
+		}
+	});
+
+	test("erros claros: decisão inválida, id inexistente, run ausente", () => {
+		const run0 = makeRun(ONE_FINDING);
+		try {
+			const bad = run([
+				"set",
+				"inexistente",
+				"--decision",
+				"xpto",
+				"--dir",
+				run0.dir,
+				"--branch",
+				"main",
+			]);
+			expect(bad.exitCode).toBe(1);
+			expect(bad.output).toContain("--decision inválido");
+
+			const missing = run([
+				"show",
+				"nao-existe",
+				"--dir",
+				run0.dir,
+				"--branch",
+				"main",
+			]);
+			expect(missing.exitCode).toBe(1);
+			expect(missing.output).toContain("não encontrado");
+
+			const empty = mkdtempSync(join(tmpdir(), "houndsman-empty-"));
+			try {
+				const absent = run(["list", "--dir", empty, "--branch", "main"]);
+				expect(absent.exitCode).toBe(1);
+				expect(absent.output).toContain("--finalize");
+			} finally {
+				rmSync(empty, { recursive: true, force: true });
+			}
+		} finally {
+			run0.cleanup();
+		}
+	});
+
+	test("path devolve o caminho do state.json", () => {
+		const run0 = makeRun(ONE_FINDING);
+		try {
+			run(["list", "--dir", run0.dir, "--branch", "main"]);
+			const result = run(["path", "--dir", run0.dir, "--branch", "main"]);
+			expect(result.exitCode).toBe(0);
+			expect(result.output.replace(/\\/g, "/")).toContain("main/state.json");
+		} finally {
+			run0.cleanup();
+		}
+	});
+
+	test("sub desconhecido devolve erro", () => {
+		const run0 = makeRun(ONE_FINDING);
+		try {
+			const result = run(["xpto", "--dir", run0.dir, "--branch", "main"]);
+			expect(result.exitCode).toBe(1);
+			expect(result.output).toContain("desconhecido");
+		} finally {
+			run0.cleanup();
+		}
+	});
+});