@payconductor/houndsman 0.1.4 → 0.3.0

package/src/tests/baseline.test.ts

@@ -0,0 +1,513 @@
+/**
+ * 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,
+	readdirSync,
+	readFileSync,
+	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();
+}
+
+// ---------------------------------------------------------------------------
+// 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(normalizeArtifacts(md)).toMatchSnapshot();
+	});
+
+	test("renderDomainReport isolado", () => {
+		const md = renderDomainReport(
+			"feature/x",
+			reports[0],
+			merged,
+			2,
+			reportContext,
+			(id) => (id === "alpha" ? "Alpha" : "Beta"),
+		);
+
+		expect(normalizeArtifacts(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"]);
+			// Evita assinatura de commit (ex.: 1Password) no repo temporário.
+			git(cwd, ["config", "commit.gpgsign", "false"]);
+			git(cwd, ["config", "tag.gpgsign", "false"]);
+			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 prepared = await prepare(opts, "main", baselineConfig);
+			expect(normalizeArtifacts(prepared.messages.join("\n"))).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 finalized = finalize(opts, "main", baselineConfig);
+			expect(normalizeArtifacts(finalized.messages.join("\n"))).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 });
+		}
+	}, 30_000);
+});
+
+// ---------------------------------------------------------------------------
+// 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",
+	"FindingsRepository",
+	"FindingsState",
+	"Finding",
+	"Classification",
+	"Diff",
+	"DocDiscoverer",
+	"FileClassifier",
+	"GhClient",
+	"GitRepository",
+	"ProjectConfig",
+	"ProjectFiles",
+	"RunLayout",
+	"Watchdog",
+	"WatchdogRegistry",
+	"systemClock",
+	"HoundsmanServer",
+	"HoundsmanEngine",
+	"ReviewSession",
+	"ReviewScopeResolver",
+	"buildCarryover",
+	"mergeCarryover",
+	"RunRepository",
+	"ArgParser",
+	"ProjectScaffolder",
+	"FixBatchBuilder",
+	"Verifier",
+	"BriefRenderer",
+	"ReportRenderer",
+	"ManifestWriter",
+	"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);
+		}
+	});
+});

package/src/tests/cli.test.ts

@@ -0,0 +1,167 @@
+/**
+ * Smoke test do CLI (`src/cli/index.ts`).
+ *
+ * O `main()` carrega cada comando por **import dinâmico** — este teste invoca o
+ * CLI como processo (num projeto mínimo em disco) para garantir que os caminhos
+ * lazy resolvem em runtime. É a única cobertura end-to-end do binário.
+ */
+
+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";
+
+/** Caminho do executável do CLI (TS, rodado pelo Bun). */
+const CLI = join(import.meta.dir, "..", "cli", "index.ts");
+
+/** Config mínima, como objeto literal (o `loadConfig` deriva `watchdogIds`). */
+const CONFIG = `export default {
+	projectName: "Smoke",
+	watchdogs: {
+		alpha: {
+			id: "alpha",
+			name: "Alpha",
+			description: "Watchdog de smoke.",
+			scope: "src/**",
+			classify: [{ value: "^src/" }],
+			rules: [{ severity: "attention", text: "Evitar any." }],
+			contextFiles: [],
+		},
+	},
+	exclusions: [],
+	docMappings: [],
+};
+`;
+
+type Project = { cwd: string; artifacts: string; cleanup: () => void };
+
+/** Projeto temporário: config + uma run com um finding. */
+function makeProject(): Project {
+	const cwd = mkdtempSync(join(tmpdir(), "houndsman-cli-"));
+	const artifacts = join(cwd, ".houndsman", ".runs");
+	const runDir = join(artifacts, "main");
+	mkdirSync(join(runDir, "findings"), { recursive: true });
+	writeFileSync(join(cwd, "houndsman.config.ts"), CONFIG);
+	writeFileSync(
+		join(runDir, "classification.json"),
+		JSON.stringify({ watchdogs: { alpha: ["src/a.ts"] } }),
+	);
+	writeFileSync(
+		join(runDir, "findings", "alpha.json"),
+		JSON.stringify({
+			watchdogId: "alpha",
+			reviewedFiles: ["src/a.ts"],
+			skipped: [],
+			findings: [
+				{
+					rule: "Evitar any",
+					severity: "attention",
+					file: "src/a.ts",
+					line: 1,
+					message: "any detectado",
+					action: "tipar",
+				},
+			],
+		}),
+	);
+	return {
+		cwd,
+		artifacts,
+		cleanup: () => rmSync(cwd, { recursive: true, force: true }),
+	};
+}
+
+type CliResult = { code: number; stdout: string; stderr: string };
+
+/** Invoca o CLI como processo, no cwd informado. */
+function runCli(cwd: string, args: string[]): CliResult {
+	const proc = Bun.spawnSync(["bun", CLI, ...args], {
+		cwd,
+		stdout: "pipe",
+		stderr: "pipe",
+	});
+	return {
+		code: proc.exitCode ?? -1,
+		stdout: proc.stdout.toString(),
+		stderr: proc.stderr.toString(),
+	};
+}
+
+describe("cli smoke — imports dinâmicos", () => {
+	test("help imprime o uso (sem carregar config)", () => {
+		const result = runCli(process.cwd(), ["help"]);
+		expect(result.code).toBe(0);
+		expect(result.stdout).toContain("Uso: houndsman");
+	});
+
+	test("watchdog <id> devolve o contexto (import lazy de commands/watchdog)", () => {
+		const project = makeProject();
+		try {
+			const result = runCli(project.cwd, ["watchdog", "alpha", "--json"]);
+			expect(result.code).toBe(0);
+			expect(JSON.parse(result.stdout).id).toBe("alpha");
+		} finally {
+			project.cleanup();
+		}
+	});
+
+	test("findings summary devolve a triagem (import lazy de commands/findings)", () => {
+		const project = makeProject();
+		try {
+			const result = runCli(project.cwd, [
+				"findings",
+				"summary",
+				"--json",
+				"--dir",
+				project.artifacts,
+				"--branch",
+				"main",
+			]);
+			expect(result.code).toBe(0);
+			expect(JSON.parse(result.stdout).total).toBe(1);
+		} finally {
+			project.cleanup();
+		}
+	});
+
+	test("findings submit --dry-run devolve a prévia (fail-open sem gh)", () => {
+		const project = makeProject();
+		try {
+			const result = runCli(project.cwd, [
+				"findings",
+				"submit",
+				"--dry-run",
+				"--json",
+				"--dir",
+				project.artifacts,
+				"--branch",
+				"main",
+			]);
+			expect(result.code).toBe(0);
+			expect(JSON.parse(result.stdout).totals.candidates).toBe(1);
+		} finally {
+			project.cleanup();
+		}
+	});
+
+	test("doctor valida a config (import lazy de registry-check)", () => {
+		const project = makeProject();
+		try {
+			const result = runCli(project.cwd, ["doctor"]);
+			expect(result.code).toBe(0);
+			expect(result.stdout).toContain("Validando");
+		} finally {
+			project.cleanup();
+		}
+	});
+
+	test("context é fail-open sem PR (import lazy de commands/context)", () => {
+		const project = makeProject();
+		try {
+			const result = runCli(project.cwd, ["context", "--branch", "main"]);
+			expect(result.code).toBe(0);
+		} finally {
+			project.cleanup();
+		}
+	});
+});