@payconductor/houndsman 0.1.3 → 0.2.0

package/src/skill/train.md

@@ -72,10 +72,29 @@ Toda regra (nova ou alterada) deve passar por **todos** os itens:
      direta da afirmação). Aí o prefixo lidera o sentido dominante e o outro entra como oração
      subordinada — nunca como segundo juízo coordenado.
 9. **Escopo coerente** — a regra pertence ao domínio do watchdog.
-10. **Sem duplicata** — nenhuma regra repetida literalmente no mesmo watchdog.
+10. **Sem duplicata** — nenhuma regra repetida (texto normalizado) no mesmo watchdog.
+11. **Lugar único** — a regra vive **apenas** em `rules`. Nunca repita o texto (nem o anti-padrão)
+    em `reviewFocus`, `contextFiles`, `scope`, `description` ou `exclude`.
 
 > O `houndsman doctor` emite um **aviso** (não bloqueante) para regra sem polaridade explícita
-> (`Promover:`, `Evitar:`, `Não` ou `Nunca`).
+> (`Promover:`, `Evitar:`, `Não` ou `Nunca`), para regra duplicada e para texto de regra que
+> vazou para `reviewFocus`/`contextFiles`/`exclude`.
+
+### Onde cada coisa vive (não duplique a regra)
+
+Cada informação tem o seu campo — não espelhe a regra em vários lugares:
+
+| O que você quer expressar | Campo | Observação |
+|---|---|---|
+| A **regra** (o que DEVE/NÃO DEVE acontecer) | `rules[]` | Único lugar da regra: `{ severity, text, jev? }`. |
+| **Quais arquivos** o watchdog cobre | `classify` | Regex de path (ou de conteúdo). |
+| **Que arquivos** olhar primeiro | `reviewFocus` | **Paths/áreas** do código — não texto de regra. |
+| **Que docs** consultar | `contextFiles` | Caminhos de **documentação** — não regra nem código. |
+| O que **nunca** carregar | `exclude` | Paths a ignorar. |
+| O **território** em prosa | `scope` / `description` | Contexto do domínio, não regra. |
+
+> A regra aparece **uma única vez** no arquivo — em `rules`. Repeti-la em
+> `reviewFocus`/`contextFiles`/`scope`/`description`/`exclude` só cria ruído no brief do subagente.
 
 ---
 
@@ -166,7 +185,9 @@ verificáveis por leitura local. Candidatos não confirmados pelo watchdog **nã
      `Evitar:`/`Não`/`Nunca` (NÃO DEVE), conforme as Convenções de escrita.
    - Regra que mistura afirmação e negação (dois sentidos) → dividir em **duas entradas** (*Unipolar*, item 8).
    - `jev` (opcional): `{ kind: "noul" }`, com `instructions` e/ou `criteria` — ver seção acima.
-   - Ajustar `scope` / `description` / `reviewFocus` / `exclude` / `contextFiles` se necessário.
+   - **A regra vai só em `rules`** — não a repita em `reviewFocus`/`contextFiles`/`scope`/
+     `description`/`exclude`. Só toque nesses campos se o **domínio/paths** mudou (ver
+     *Onde cada coisa vive*), nunca para reafirmar a regra.
    - Se a regra muda para outro domínio (paths), ajustar o `classify` do watchdog.
 5. **Watchdog novo?** criar `.houndsman/watchdogs/<id>.ts` e registrar em `.houndsman/watchdogs/index.ts` (o id é derivado das chaves).
 6. **Atualizar `src/skill/hunt.md`/`README.md`** se escopo/regra visível mudou (no motor).
@@ -226,16 +247,14 @@ todos os itens — em especial: **geral/reutilizável** (não regra de negócio
 
 ```bash
 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                   # tipagem (no repo da lib)
 ```
 
+> `bun run houndsman test`, `bun run ci:fix` e `bun run ci` são comandos para **manter a lib** do
+> houndsman (repo do pacote) — não para quem só usa o houndsman no projeto.
+
 Checklist final:
 
 - [ ] `bun run houndsman doctor` → sem problemas reportados.
-- [ ] `bun run houndsman test` → **0 fail**.
-- [ ] `ci:fix` + `ci` → exit 0 (warnings pré-existentes não contam).
 - [ ] `WATCHDOG_DEFINITIONS[<id>].id` bate com a chave e `description` não vazio.
 - [ ] `src/skill/hunt.md` continua consistente com os watchdogs do projeto.
 - [ ] Toda regra nova/alterada tem **evidência** registrada no PR/relatório
@@ -244,6 +263,8 @@ Checklist final:
 - [ ] Brief de amostra não contém regra removida (dry-run abaixo).
 - [ ] Toda regra passa nas convenções de escrita (geral/reutilizável, sem jargão abreviado,
       sem qualificador vago, com polaridade explícita e **unipolar**) — conferir via grep.
+- [ ] O texto de cada regra aparece **exatamente uma vez** no arquivo (só em `rules`) — nada em
+      `reviewFocus`/`contextFiles`/`scope`/`description`/`exclude`.
 
 ```bash
 # Dry-run: gerar briefs e conferir ausência de regras removidas

package/src/tests/baseline.test.ts

@@ -0,0 +1,493 @@
+/**
+ * Baseline de comportamento (Fase 0 do refactor OO).
+ *
+ * Congela a saída observável do motor — briefs, relatórios, camada gerada e
+ * artefatos de `prepare`/`finalize` — para provar que o refactor não muda
+ * comportamento. Qualquer divergência nesses snapshots é uma regressão.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { createHash } from "node:crypto";
+import {
+	mkdirSync,
+	mkdtempSync,
+	readFileSync,
+	readdirSync,
+	rmSync,
+	statSync,
+	writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join, relative } from "node:path";
+import { renderBrief } from "../core/brief";
+import {
+	createScaffoldContext,
+	syncGeneratedFiles,
+	writeUserLayer,
+} from "../core/commands/scaffold";
+import { defineHoundsmanConfig } from "../core/config";
+import { defaultOptions, finalize, prepare } from "../core/orchestrator";
+import {
+	type MergedFinding,
+	renderDomainReport,
+	renderReport,
+	type WatchdogReport,
+} from "../core/report-builder";
+import { defineWatchdog } from "../core/types";
+import * as facade from "../index";
+
+// ---------------------------------------------------------------------------
+// Config baseline (projeto fake, 1 watchdog para artefatos determinísticos)
+// ---------------------------------------------------------------------------
+
+const baselineWatchdog = defineWatchdog({
+	id: "alpha",
+	name: "Alpha",
+	description: "Watchdog baseline.",
+	scope: "src/alpha/**",
+	classify: [{ value: "^src/alpha/" }],
+	rules: [
+		{ severity: "blocking", text: "Nunca usar `any`." },
+		{ severity: "attention", text: "Promover: validar a entrada." },
+	],
+	contextFiles: ["README.md"],
+	breakingChange: true,
+});
+
+const baselineConfig = defineHoundsmanConfig({
+	projectName: "Baseline",
+	artifactDir: ".houndsman/.runs",
+	watchdogs: { alpha: baselineWatchdog },
+	exclusions: [/^dist\//],
+	docMappings: [[/^src\//, ["README.md"]]],
+	alwaysIncludeDocs: ["README.md"],
+});
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Substitui valores voláteis (ids, timestamps, SHAs) por marcadores estáveis. */
+function normalizeArtifacts(text: string): string {
+	return text
+		.replace(
+			/"(createdAt|updatedAt|generatedAt|startedAt|at)": "[^"]*"/g,
+			'"$1": "<timestamp>"',
+		)
+		.replace(/"\d{4}-\d{2}-\d{2}T[^"]*"/g, '"<timestamp>"')
+		.replace(/\b[0-9a-f]{40}\b/g, "<sha>")
+		.replace(/\b[0-9a-f]{16}\b/g, "<fingerprint>")
+		.replace(/\b[0-9a-f]{10}\b/g, "<id>")
+		.replace(/\d{4}-\d{2}-\d{2}/g, "<date>");
+}
+
+/** Lista recursiva de arquivos (caminhos relativos, ordenados). */
+function listFiles(root: string): string[] {
+	const files: string[] = [];
+	const walk = (dir: string): void => {
+		for (const name of readdirSync(dir)) {
+			const full = join(dir, name);
+			if (statSync(full).isDirectory()) walk(full);
+			else files.push(relative(root, full).replace(/\\/g, "/"));
+		}
+	};
+	walk(root);
+	return files.sort();
+}
+
+/** Executa git no diretório e devolve stdout (lança em falha). */
+function git(cwd: string, args: string[]): string {
+	const result = Bun.spawnSync(["git", ...args], {
+		cwd,
+		stdout: "pipe",
+		stderr: "pipe",
+	});
+	if (result.exitCode !== 0) {
+		throw new Error(`git ${args.join(" ")}: ${result.stderr.toString()}`);
+	}
+	return result.stdout.toString();
+}
+
+/** Captura o stdout de `fn` (o baseline inclui a saída textual do CLI). */
+async function captureStdout(fn: () => Promise<void>): Promise<string> {
+	const original = console.log;
+	const lines: string[] = [];
+	console.log = (...args: unknown[]) => {
+		lines.push(args.map(String).join(" "));
+	};
+	try {
+		await fn();
+	} finally {
+		console.log = original;
+	}
+	return lines.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// Brief
+// ---------------------------------------------------------------------------
+
+describe("baseline — brief", () => {
+	test("defaultRenderBrief (contexto, churn, overflow, candidatos e deletados)", () => {
+		const brief = renderBrief(baselineWatchdog, {
+			watchdogId: "alpha",
+			files: ["src/alpha/a.ts", "src/alpha/b.ts"],
+			statuses: {
+				"src/alpha/a.ts": { status: "modified" },
+				"src/alpha/b.ts": { status: "added" },
+			},
+			churn: {
+				"src/alpha/a.ts": { additions: 3, deletions: 1 },
+				"src/alpha/b.ts": { additions: 2, deletions: 0 },
+			},
+			overflow: ["src/alpha/c.ts"],
+			deleted: ["src/alpha/old.ts"],
+			branch: "feature/x",
+			outputPath: ".houndsman/.runs/feature-x/findings/alpha.json",
+			outputFormatPath: ".houndsman/core/skill/OUTPUT-FORMAT.md",
+			docs: ["AGENTS.md", "README.md"],
+			context: {
+				objective: "Entregar X",
+				motivation: "Reduzir Y",
+				changeSummary: ["Faz A", "Remove B"],
+			},
+			candidates: [
+				{
+					file: "src/alpha/a.ts",
+					severity: "blocking",
+					confidence: 0.82,
+					rule: "Nunca usar `any`.",
+				},
+			],
+		});
+
+		expect(brief).toMatchSnapshot();
+	});
+});
+
+// ---------------------------------------------------------------------------
+// Relatório
+// ---------------------------------------------------------------------------
+
+const reports: WatchdogReport[] = [
+	{
+		watchdogId: "alpha",
+		reviewedFiles: ["src/alpha/a.ts", "src/alpha/b.ts"],
+		skipped: ["src/alpha/c.ts"],
+		findings: [
+			{
+				rule: "Nunca usar `any`.",
+				severity: "blocking",
+				file: "src/alpha/a.ts",
+				line: 1,
+				message: "any detectado",
+				action: "tipar",
+				evidence: "export const a: any = 1;",
+				id: "id-alpha",
+			},
+			{
+				rule: "Promover: validar a entrada.",
+				severity: "attention",
+				file: "src/alpha/b.ts",
+				line: 2,
+				message: "sem validação",
+				action: "adicionar schema",
+				id: "id-beta",
+			},
+		],
+	},
+	{
+		watchdogId: "beta",
+		reviewedFiles: ["src/beta/x.test.ts"],
+		skipped: [],
+		findings: [],
+	},
+];
+
+const merged: MergedFinding[] = [
+	{ ...reports[0].findings[0], watchdogs: ["alpha"] },
+	{ ...reports[0].findings[1], watchdogs: ["alpha", "beta"] },
+];
+
+const reportContext = {
+	available: true,
+	source: {
+		number: 42,
+		title: "Entrega X",
+		url: "https://example.test/pull/42",
+		head: "feature/x",
+		base: "main",
+	},
+	objective: "Entregar X",
+	motivation: "Reduzir Y",
+	changeSummary: ["Faz A", "Remove B"],
+};
+
+describe("baseline — relatório", () => {
+	test("renderReport consolidado", () => {
+		const md = renderReport(
+			"feature/x",
+			reports,
+			merged,
+			{ classified: { alpha: ["src/alpha/a.ts", "src/alpha/b.ts"], beta: [] } },
+			reportContext,
+			[
+				{
+					watchdogId: "alpha",
+					rule: "Nunca usar `any`.",
+					severity: "blocking",
+					file: "src/alpha/a.ts",
+					confidence: 0.82,
+					questionKey: "alpha::rule-0",
+				},
+			],
+			(id) => (id === "alpha" ? "Alpha" : "Beta"),
+			[
+				{
+					id: "alpha",
+					name: "Alpha",
+					file: "review.alpha.md",
+					findings: 2,
+					reviewedFiles: 2,
+					expectedFiles: 2,
+				},
+			],
+		);
+
+		expect(md).toMatchSnapshot();
+	});
+
+	test("renderDomainReport isolado", () => {
+		const md = renderDomainReport(
+			"feature/x",
+			reports[0],
+			merged,
+			2,
+			reportContext,
+			(id) => (id === "alpha" ? "Alpha" : "Beta"),
+		);
+
+		expect(md).toMatchSnapshot();
+	});
+});
+
+// ---------------------------------------------------------------------------
+// Camada gerada pelo setup/update
+// ---------------------------------------------------------------------------
+
+/** Arquivos-template cujo conteúdo precisa permanecer idêntico. */
+const TEMPLATE_FILES = [
+	"houndsman.config.ts",
+	".houndsman/core/types.ts",
+	".houndsman/watchdogs/example.ts",
+	".houndsman/watchdogs/index.ts",
+	".houndsman/exclusions.ts",
+	".houndsman/doc-mappings.ts",
+	".houndsman/.gitignore",
+	".agents/skills/houndsman/SKILL.md",
+	".claude/skills/houndsman/SKILL.md",
+];
+
+describe("baseline — camada gerada", () => {
+	test("setup gera os mesmos arquivos e conteúdos", () => {
+		const cwd = mkdtempSync(join(tmpdir(), "houndsman-baseline-scaffold-"));
+		try {
+			const ctx = createScaffoldContext(cwd, ["--name", "acme"], false);
+			writeUserLayer(ctx);
+			syncGeneratedFiles(ctx);
+
+			const files = listFiles(cwd);
+			expect(files).toMatchSnapshot();
+
+			const contents = Object.fromEntries(
+				TEMPLATE_FILES.map((file) => [file, readFileSync(join(cwd, file), "utf8")]),
+			);
+			expect(contents).toMatchSnapshot();
+
+			// Assets copiados (skill docs): hash estável, sem colar o markdown inteiro.
+			const skillDocs = files
+				.filter((file) => file.startsWith(".houndsman/core/skill/"))
+				.map((file) => ({
+					file,
+					sha256: createHash("sha256")
+						.update(readFileSync(join(cwd, file), "utf8"))
+						.digest("hex")
+						.slice(0, 16),
+				}));
+			expect(skillDocs).toMatchSnapshot();
+		} finally {
+			rmSync(cwd, { recursive: true, force: true });
+		}
+	});
+});
+
+// ---------------------------------------------------------------------------
+// prepare → findings → finalize (end-to-end em repo git temporário)
+// ---------------------------------------------------------------------------
+
+describe("baseline — artefatos de prepare/finalize", () => {
+	test("gera classification, brief, manifest, review e state", async () => {
+		const cwd = mkdtempSync(join(tmpdir(), "houndsman-baseline-run-"));
+		const originalCwd = process.cwd();
+
+		try {
+			git(cwd, ["init", "-b", "main"]);
+			git(cwd, ["config", "user.email", "baseline@example.test"]);
+			git(cwd, ["config", "user.name", "Baseline"]);
+			mkdirSync(join(cwd, "src", "alpha"), { recursive: true });
+			writeFileSync(join(cwd, "src", "alpha", "a.ts"), "export const a = 1;\n");
+			writeFileSync(join(cwd, "src", "alpha", "old.ts"), "export const old = 1;\n");
+			writeFileSync(join(cwd, "README.md"), "# Baseline\n");
+			git(cwd, ["add", "."]);
+			git(cwd, ["commit", "-m", "initial"]);
+			const base = git(cwd, ["rev-parse", "HEAD"]).trim();
+
+			writeFileSync(
+				join(cwd, "src", "alpha", "a.ts"),
+				"export const a: any = 1;\nexport const b = 2;\n",
+			);
+			writeFileSync(join(cwd, "src", "alpha", "b.ts"), "export const b = 3;\n");
+			rmSync(join(cwd, "src", "alpha", "old.ts"));
+			git(cwd, ["add", "-A"]);
+			git(cwd, ["commit", "-m", "change"]);
+
+			const opts = {
+				...defaultOptions(".houndsman/.runs"),
+				base,
+				head: "HEAD",
+				noJev: true,
+			};
+
+			process.chdir(cwd);
+
+			const prepareOutput = await captureStdout(async () => {
+				await prepare(opts, "main", baselineConfig);
+			});
+			expect(normalizeArtifacts(prepareOutput)).toMatchSnapshot();
+
+			const runDir = join(cwd, ".houndsman", ".runs", "main");
+			for (const file of ["classification.json", "manifest.json", "briefs/alpha.md"]) {
+				expect(
+					normalizeArtifacts(readFileSync(join(runDir, file), "utf8")),
+				).toMatchSnapshot(file);
+			}
+
+			writeFileSync(
+				join(runDir, "findings", "alpha.json"),
+				`${JSON.stringify(
+					{
+						watchdogId: "alpha",
+						reviewedFiles: ["src/alpha/a.ts", "src/alpha/b.ts"],
+						skipped: [],
+						findings: [
+							{
+								rule: "Nunca usar `any`.",
+								severity: "blocking",
+								file: "src/alpha/a.ts",
+								line: 1,
+								message: "any detectado",
+								action: "tipar",
+								evidence: "export const a: any = 1;",
+							},
+						],
+					},
+					null,
+					2,
+				)}\n`,
+			);
+
+			const finalizeOutput = await captureStdout(async () => {
+				finalize(opts, "main", baselineConfig);
+			});
+			expect(normalizeArtifacts(finalizeOutput)).toMatchSnapshot();
+
+			for (const file of [
+				"review.md",
+				"review.alpha.md",
+				"state.json",
+				"run.json",
+			]) {
+				expect(
+					normalizeArtifacts(readFileSync(join(runDir, file), "utf8")),
+				).toMatchSnapshot(file);
+			}
+		} finally {
+			process.chdir(originalCwd);
+			rmSync(cwd, { recursive: true, force: true });
+		}
+	});
+});
+
+// ---------------------------------------------------------------------------
+// Contrato da API pública (facade src/index.ts)
+// ---------------------------------------------------------------------------
+
+/** Símbolos que consumidores importam de `@payconductor/houndsman`. */
+const REQUIRED_EXPORTS = [
+	"PROCEDURE",
+	"SEVERITY_EMOJI",
+	"SEVERITY_ORDER",
+	"FINDING_DECISIONS",
+	"FINDING_EXEC_STATES",
+	"FINDINGS_STATE_VERSION",
+	"FindingsStateStore",
+	"applyFindingUpdate",
+	"assetPath",
+	"buildAnchor",
+	"buildStateFromFindings",
+	"buildStateFromRunDir",
+	"checkRegistry",
+	"churnOf",
+	"classifyEntries",
+	"classifyRange",
+	"collectChurn",
+	"collectDiff",
+	"compareFindings",
+	"createRequestHandler",
+	"defaultRenderBrief",
+	"defineHoundsmanConfig",
+	"defineWatchdog",
+	"emptyState",
+	"fileReader",
+	"filterFindings",
+	"findWatchdog",
+	"fingerprintOf",
+	"getWatchdog",
+	"getWatchdogContext",
+	"hashKey",
+	"isExcludedPath",
+	"loadConfig",
+	"locateAnchor",
+	"matchWatchdogs",
+	"newFindingId",
+	"normalizeLine",
+	"parseDiffIndex",
+	"parseEntries",
+	"parseNumstat",
+	"reanchor",
+	"relFromRoot",
+	"renderBrief",
+	"renderDomainReport",
+	"reorder",
+	"resolveConfigPath",
+	"resolveJevConcurrency",
+	"resolveMaxFilesPerBrief",
+	"runDir",
+	"runFindingsCommand",
+	"runVerifyCommand",
+	"selectByBudget",
+	"severityRank",
+	"sortByRisk",
+	"startServer",
+	"stateFile",
+	"summarize",
+	"syncState",
+] as const;
+
+describe("baseline — API pública", () => {
+	test("a facade mantém todos os símbolos exportados", () => {
+		for (const name of REQUIRED_EXPORTS) {
+			expect(facade).toHaveProperty(name);
+		}
+	});
+});