@payconductor/houndsman 0.0.0-stage → 0.1.1

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();
+		}
+	});
+});

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

@@ -0,0 +1,274 @@
+import { describe, expect, test } from "bun:test";
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import {
+	applyFindingUpdate,
+	buildStateFromFindings,
+	emptyState,
+	FindingsStateStore,
+	fileReader,
+	filterFindings,
+	summarize,
+	syncState,
+} from "../core/findings-state";
+import type { MergedFinding } from "../core/report-builder";
+import type { Severity } from "../core/types";
+
+/** Projeto em disco temporário (limpo no fim). */
+function makeProject(files: Record<string, string>): {
+	cwd: string;
+	cleanup: () => void;
+} {
+	const cwd = mkdtempSync(join(tmpdir(), "houndsman-state-"));
+	for (const [rel, content] of Object.entries(files)) {
+		const full = join(cwd, rel);
+		mkdirSync(dirname(full), { recursive: true });
+		writeFileSync(full, content);
+	}
+	return { cwd, cleanup: () => rmSync(cwd, { recursive: true, force: true }) };
+}
+
+function merged(
+	partial: Partial<MergedFinding> & { file: string; rule: string },
+): MergedFinding {
+	return {
+		rule: partial.rule,
+		severity: (partial.severity ?? "attention") as Severity,
+		file: partial.file,
+		line: partial.line,
+		message: partial.message ?? "msg",
+		action: partial.action ?? "ação",
+		evidence: partial.evidence,
+		watchdogs: partial.watchdogs ?? ["alpha"],
+	};
+}
+
+const DUPLICATED = [
+	"function a() {",
+	'\tconsole.log("x");',
+	"}",
+	"function b() {",
+	'\tconsole.log("x");',
+	"}",
+].join("\n");
+
+const AFTER_FIX = [
+	"function a() {",
+	"}",
+	"function b() {",
+	'\tconsole.log("x");',
+	"}",
+].join("\n");
+
+describe("buildStateFromFindings", () => {
+	test("cria entradas pendentes com id e ancora a linha", () => {
+		const project = makeProject({ "src/f.ts": DUPLICATED });
+		try {
+			const findings = [
+				merged({ file: "src/f.ts", rule: "r", line: 2 }),
+				merged({ file: "src/f.ts", rule: "r", line: 5 }),
+			];
+			const state = buildStateFromFindings(findings, {
+				branch: "feature/x",
+				readFile: fileReader(project.cwd),
+			});
+
+			expect(state.slug).toBe("feature-x");
+			expect(Object.keys(state.findings)).toHaveLength(2);
+			// Os ids voltam para os findings (usados no relatório).
+			expect(findings[0].id).toBeTruthy();
+			expect(findings[0].id).not.toBe(findings[1].id);
+			for (const finding of Object.values(state.findings)) {
+				expect(finding.decision).toBe("pending");
+				expect(finding.execState).toBe("pending");
+				expect(finding.present).toBe(true);
+				expect(finding.line).toBeGreaterThan(0);
+			}
+		} finally {
+			project.cleanup();
+		}
+	});
+
+	test("preserva id e decisão entre execuções (casa por fingerprint)", () => {
+		const project = makeProject({ "src/f.ts": DUPLICATED });
+		try {
+			const reader = fileReader(project.cwd);
+			const first = buildStateFromFindings(
+				[merged({ file: "src/f.ts", rule: "r", line: 2 })],
+				{ branch: "main", readFile: reader },
+			);
+			const id = Object.keys(first.findings)[0];
+			applyFindingUpdate(first.findings[id], { decision: "ignore" });
+
+			const second = buildStateFromFindings(
+				[merged({ file: "src/f.ts", rule: "r", line: 2 })],
+				{ branch: "main", readFile: reader, previous: first },
+			);
+			expect(Object.keys(second.findings)).toEqual([id]);
+			expect(second.findings[id].decision).toBe("ignore");
+		} finally {
+			project.cleanup();
+		}
+	});
+
+	test("finding que sumiu fica ausente e vira done se era 'execute'", () => {
+		const project = makeProject({ "src/f.ts": DUPLICATED });
+		try {
+			const reader = fileReader(project.cwd);
+			const first = buildStateFromFindings(
+				[merged({ file: "src/f.ts", rule: "r", line: 2 })],
+				{ branch: "main", readFile: reader },
+			);
+			const id = Object.keys(first.findings)[0];
+			applyFindingUpdate(first.findings[id], { decision: "execute" });
+
+			const second = buildStateFromFindings([], {
+				branch: "main",
+				readFile: reader,
+				previous: first,
+			});
+			expect(second.findings[id].present).toBe(false);
+			expect(second.findings[id].execState).toBe("done");
+		} finally {
+			project.cleanup();
+		}
+	});
+
+	test("ocorrências idênticas (mesmo contexto) viram um grupo com count", () => {
+		const content = [
+			"const a = 1;",
+			'console.log("x");',
+			"const a = 1;",
+			'console.log("x");',
+			"const a = 1;",
+		].join("\n");
+		const project = makeProject({ "src/g.ts": content });
+		try {
+			const findings = [
+				merged({ file: "src/g.ts", rule: "r", line: 2 }),
+				merged({ file: "src/g.ts", rule: "r", line: 4 }),
+			];
+			const state = buildStateFromFindings(findings, {
+				branch: "main",
+				readFile: fileReader(project.cwd),
+			});
+			expect(Object.keys(state.findings)).toHaveLength(1);
+			const only = Object.values(state.findings)[0];
+			expect(only.count).toBe(2);
+			expect(findings[0].id).toBe(findings[1].id);
+		} finally {
+			project.cleanup();
+		}
+	});
+});
+
+describe("syncState", () => {
+	test("move a sobrevivente de linha e marca a removida como stale/done", () => {
+		const before = makeProject({ "src/f.ts": DUPLICATED });
+		const after = makeProject({ "src/f.ts": AFTER_FIX });
+		try {
+			const state = buildStateFromFindings(
+				[
+					merged({ file: "src/f.ts", rule: "r", line: 2 }),
+					merged({ file: "src/f.ts", rule: "r", line: 5 }),
+				],
+				{ branch: "main", readFile: fileReader(before.cwd) },
+			);
+			const ids = Object.keys(state.findings);
+			// A primeira ocorrência foi marcada para executar.
+			const firstId = ids[0];
+			applyFindingUpdate(state.findings[firstId], { decision: "execute" });
+
+			const result = syncState(state, fileReader(after.cwd));
+			expect(result.moved).toHaveLength(1);
+			expect(result.stale).toHaveLength(1);
+			expect(result.stale).toContain(firstId);
+			expect(state.findings[firstId].execState).toBe("done");
+
+			const survivor = state.findings[result.moved[0]];
+			expect(survivor.line).toBe(4);
+		} finally {
+			before.cleanup();
+			after.cleanup();
+		}
+	});
+});
+
+describe("filterFindings / summarize", () => {
+	test("filtra por decisão e severity, e resume as contagens", () => {
+		const project = makeProject({ "src/f.ts": DUPLICATED });
+		try {
+			const state = buildStateFromFindings(
+				[
+					merged({
+						file: "src/f.ts",
+						rule: "r",
+						line: 2,
+						severity: "blocking",
+					}),
+					merged({ file: "src/f.ts", rule: "r2", line: 5, severity: "nit" }),
+				],
+				{ branch: "main", readFile: fileReader(project.cwd) },
+			);
+			const ids = Object.keys(state.findings);
+			applyFindingUpdate(state.findings[ids[0]], { decision: "execute" });
+
+			expect(
+				filterFindings(state, { decision: "execute" }).map((f) => f.id),
+			).toEqual([ids[0]]);
+			expect(filterFindings(state, { severity: "nit" }).map((f) => f.id)).toEqual([
+				ids[1],
+			]);
+
+			const summary = summarize(state);
+			expect(summary.total).toBe(2);
+			expect(summary.byDecision.execute).toBe(1);
+			expect(summary.byDecision.pending).toBe(1);
+			expect(summary.bySeverity.blocking).toBe(1);
+		} finally {
+			project.cleanup();
+		}
+	});
+});
+
+describe("FindingsStateStore", () => {
+	test("grava e lê o state.json de forma atômica", () => {
+		const project = makeProject({ "src/f.ts": DUPLICATED });
+		const outDir = join(project.cwd, "artifacts");
+		try {
+			const store = FindingsStateStore.at(outDir, "feature/x");
+			const state = buildStateFromFindings(
+				[merged({ file: "src/f.ts", rule: "r", line: 2 })],
+				{ branch: "feature/x", readFile: fileReader(project.cwd) },
+			);
+			store.write(state);
+
+			expect(store.filePath).toBe(join(outDir, "feature-x", "state.json"));
+			expect(existsSync(store.filePath)).toBe(true);
+			const read = store.read();
+			expect(read?.slug).toBe("feature-x");
+			expect(Object.keys(read?.findings ?? {})).toHaveLength(1);
+		} finally {
+			project.cleanup();
+		}
+	});
+
+	test("read devolve null quando o arquivo não existe", () => {
+		const project = makeProject({});
+		try {
+			const store = FindingsStateStore.at(join(project.cwd, "artifacts"), "main");
+			expect(store.read()).toBeNull();
+			expect(store.update(() => {})).toBeTruthy();
+		} finally {
+			project.cleanup();
+		}
+	});
+
+	test("emptyState cria um estado vazio válido", () => {
+		const state = emptyState("feature/x");
+		expect(state.version).toBe(1);
+		expect(state.slug).toBe("feature-x");
+		expect(state.findings).toEqual({});
+	});
+});

package/src/tests/fixtures/fake-project.ts

@@ -0,0 +1,64 @@
+/**
+ * "Project fake" usado pela suíte de testes da lib.
+ *
+ * Os testes validam o MOTOR (`core/`), não as regras de um projeto real —
+ * por isso usam esta configuração fictícia em vez da config do projeto real.
+ */
+
+import { defineHoundsmanConfig, type HoundsmanConfig } from "../../core/config";
+import { defineWatchdog } from "../../core/types";
+
+/** Watchdog A — regra bloqueante com spec Jev + outras severidades. */
+export const alphaWatchdog = defineWatchdog({
+	id: "alpha",
+	name: "Alpha",
+	description: "Watchdog A do projeto fake.",
+	scope: "src/alpha/**",
+	classify: [{ value: "^src/alpha/" }],
+	rules: [
+		{ severity: "blocking", text: "Nunca usar `any`.", jev: { kind: "noul" } },
+		{ severity: "attention", text: "Validar entrada do usuário." },
+		{ severity: "suggestion", text: "Evitar console.log." },
+	],
+	contextFiles: ["README.md"],
+});
+
+/** Watchdog B — cobre testes e um padrão de nome de arquivo. */
+export const betaWatchdog = defineWatchdog({
+	id: "beta",
+	name: "Beta",
+	description: "Watchdog B do projeto fake.",
+	scope: "src/beta/**, arquivos de teste e o arquivo especial",
+	classify: [
+		{ value: "^src/beta/" },
+		{ value: "\\.test\\.ts$" },
+		{ value: "special\\.ts$" },
+	],
+	rules: [
+		{
+			severity: "blocking",
+			text: "Nunca commitar segredos.",
+			jev: { kind: "noul", instructions: "O estado contém segredo hardcoded?" },
+		},
+		{ severity: "attention", text: "Evitar código morto." },
+	],
+	contextFiles: ["README.md"],
+});
+
+export const FAKE_WATCHDOG_DEFINITIONS = {
+	alpha: alphaWatchdog,
+	beta: betaWatchdog,
+};
+
+export type FakeWatchdogId = keyof typeof FAKE_WATCHDOG_DEFINITIONS;
+
+/** Configuração completa do projeto fake. */
+export const fakeHoundsmanConfig: HoundsmanConfig<FakeWatchdogId> =
+	defineHoundsmanConfig<FakeWatchdogId>({
+		projectName: "Fake Project",
+		artifactDir: "tmp/fake-review",
+		watchdogs: FAKE_WATCHDOG_DEFINITIONS,
+		exclusions: [/^dist\//, /\.lock$/],
+		docMappings: [[/^src\//, ["README.md"]]],
+		alwaysIncludeDocs: ["README.md"],
+	});