@payconductor/houndsman 0.3.0 → 0.5.0

package/src/core/commands/findings.ts

@@ -1,24 +1,18 @@
 /**
  * Subcomando `findings` — triagem dos findings da revisão (biblioteca).
  *
- * Lê/grava o `state.json` da run (`findings-state.ts`). Devolve o texto pronto
- * (markdown ou JSON) + exit code; o CLI decide o log/exit. O agente do usuário
- * usa `list`/`set`/`done` (e `batch` para lotes de correção) para interagir sem abrir o JSON à mão.
+ * Lê/grava o estado de triagem no storage (SQLite por default). Devolve o texto
+ * pronto (markdown ou JSON) + exit code; o CLI decide o log/exit. O agente do
+ * usuário usa `list`/`set`/`done` (e `batch` para lotes de correção) para
+ * interagir sem abrir o banco à mão.
  *
- * Se o `state.json` não existir, é re-construído a partir de
- * `findings/*.json` + `classification.json` (não exige `--finalize`).
+ * Ids aceitam prefixo único (exato primeiro) — útil porque o id curto convive
+ * com o UUID interno no banco.
  */
 
-import { writeFileSync } from "node:fs";
-import { join } from "node:path";
-import {
-	type HoundsmanConfig,
-	resolveArtifactDir,
-	resolveJevConcurrency,
-} from "../config";
+import { type HoundsmanConfig, resolveJevConcurrency } from "../config";
 import {
 	applyFindingUpdate,
-	buildStateFromRunDir,
 	FINDING_DECISIONS,
 	FINDING_EXEC_STATES,
 	type FindingDecision,
@@ -26,11 +20,11 @@ import {
 	type FindingState,
 	type FindingsFilter,
 	type FindingsStateFile,
-	FindingsStateStore,
 	type FindingUpdate,
 	fileReader,
 	filterFindings,
-	runDir,
+	reorder,
+	resolveFindingId,
 	summarize,
 	syncState,
 } from "../findings-state";
@@ -42,15 +36,19 @@ import {
 	type SubmitPreview,
 	type SubmitSelection,
 	submitFindings,
+	syncResolvedThreads,
 } from "../github-review";
-import { relFromRoot, VERIFY_FILE } from "../paths";
+import { VERIFY_FILE } from "../paths";
 import { currentBranch } from "../pr-context";
 import { BatchPresenter } from "../renderers/batch-presenter";
 import { FindingsPresenter } from "../renderers/findings-presenter";
 import { VerifyPresenter } from "../renderers/verify-presenter";
 import { pingFindingsStatus } from "../run-status";
+import { systemClock } from "../services/clock";
 import { FixBatchBuilder } from "../services/fix-batch-builder";
 import { Verifier } from "../services/verifier";
+import type { RepoIdentity, ReviewRecord, StorageProvider } from "../storage/types";
+import { ReviewWorkArea } from "../storage/work-area";
 import { SEVERITY_ORDER, type Severity } from "../types";
 
 export type FindingsCommandResult = {
@@ -65,7 +63,6 @@ const VALUE_FLAGS = new Set([
 	"--severity",
 	"--file",
 	"--branch",
-	"--dir",
 	"--limit",
 	"--comment",
 	"--by",
@@ -85,6 +82,11 @@ function parseArgs(args: string[]): ParsedArgs {
 	const parsed: ParsedArgs = { positionals: [], values: {}, bools: new Set() };
 	for (let i = 0; i < args.length; i++) {
 		const arg = args[i];
+		if (arg === "--dir") {
+			throw new Error(
+				"--dir foi removido; configure `storage` no houndsman.config.ts.",
+			);
+		}
 		if (arg.startsWith("--")) {
 			if (VALUE_FLAGS.has(arg)) {
 				const value = args[i + 1];
@@ -101,36 +103,63 @@ function parseArgs(args: string[]): ParsedArgs {
 	return parsed;
 }
 
-/** Diretório da run + branch resolvida. */
-function resolveDir(
-	config: HoundsmanConfig,
+/** Contexto de uma review (storage + registro + staging). */
+type CommandContext = {
+	storage: StorageProvider;
+	review: ReviewRecord;
+	work: ReviewWorkArea;
+};
+
+/** Resolve a review da branch atual (explícita ou via git). */
+function openContext(
+	storage: StorageProvider,
+	repo: RepoIdentity,
 	parsed: ParsedArgs,
-): { dir: string; branch: string } {
-	return {
-		dir: parsed.values["--dir"] ?? resolveArtifactDir(config),
-		branch: parsed.values["--branch"] ?? currentBranch(),
-	};
+): CommandContext {
+	const branch = parsed.values["--branch"] ?? currentBranch();
+	const review = storage.findReview(repo.key, branch);
+	if (!review) {
+		throw new Error(
+			`Nenhuma revisão para '${branch}'. Rode \`houndsman --finalize\` primeiro.`,
+		);
+	}
+	return { storage, review, work: new ReviewWorkArea(review) };
 }
 
-/** Lê o estado da run; reconstrói dos findings se ausente. Lança se impossível. */
-function loadState(config: HoundsmanConfig, parsed: ParsedArgs): FindingsStateFile {
-	const { dir, branch } = resolveDir(config, parsed);
-	const store = FindingsStateStore.at(dir, branch);
-	const existing = store.read();
-	if (existing) return existing;
-
-	const built = buildStateFromRunDir(
-		runDir(dir, branch),
-		branch,
-		fileReader(process.cwd()),
-	);
-	if (!built) {
+/** Lê o estado de triagem; lança se a review ainda não tem findings. */
+function loadState(ctx: CommandContext): FindingsStateFile {
+	const state = ctx.storage.readFindings(ctx.review.id);
+	if (!state) {
 		throw new Error(
-			`Nenhum estado de triagem para '${branch}'. Rode \`houndsman --finalize\` primeiro.`,
+			`Nenhum estado de triagem para '${ctx.review.branch}'. Rode \`houndsman --finalize\` primeiro.`,
 		);
 	}
-	store.write(built);
-	return built;
+	return state;
+}
+
+/** Lê-modifica-grava o estado, atualizando `updatedAt` e a ordem. */
+function mutateState(
+	ctx: CommandContext,
+	mutator: (state: FindingsStateFile) => void,
+): FindingsStateFile {
+	const state = loadState(ctx);
+	mutator(state);
+	state.updatedAt = systemClock();
+	reorder(state);
+	ctx.storage.writeFindings(ctx.review.id, state);
+	return state;
+}
+
+/** Resolve um id (exato ou prefixo único), lançando erro explicativo. */
+function requireFindingId(state: FindingsStateFile, input: string): string {
+	const resolution = resolveFindingId(state, input);
+	if (resolution.status === "found") return resolution.id;
+	if (resolution.status === "ambiguous") {
+		throw new Error(
+			`Id '${input}' ambíguo — candidatos: ${resolution.matches.join(", ")}.`,
+		);
+	}
+	throw new Error(`Finding '${input}' não encontrado.`);
 }
 
 // ---------------------------------------------------------------------------
@@ -181,64 +210,71 @@ function filterFrom(parsed: ParsedArgs): FindingsFilter {
 	};
 }
 
-/** Faz ping no `run.json` (status derivado do estado atual) após uma mutação. */
-function pingStatus(config: HoundsmanConfig, parsed: ParsedArgs): void {
-	const { dir, branch } = resolveDir(config, parsed);
-	const state = FindingsStateStore.at(dir, branch).read();
-	if (state) pingFindingsStatus(runDir(dir, branch), state);
+/** Faz ping no status da review (derivado do estado atual) após uma mutação. */
+function pingStatus(ctx: CommandContext, state: FindingsStateFile): void {
+	pingFindingsStatus(ctx.storage, ctx.review.id, state);
+}
+
+/**
+ * Resolve no GitHub as threads dos findings recém-resolvidos localmente.
+ * Fail-open (`gh` ausente/sem PR ⇒ só a mensagem). Devolve a linha para o
+ * output ou `null` quando não há vínculo remoto pendente.
+ */
+function syncThreadsOutput(ctx: CommandContext, ids: readonly string[]): string | null {
+	if (ids.length === 0) return null;
+	const state = loadState(ctx);
+	const outcome = syncResolvedThreads({ state, ids });
+	if (outcome.checked === 0) return null;
+	if (outcome.updated.length > 0) ctx.storage.writeFindings(ctx.review.id, state);
+	if (!outcome.available) {
+		return `GitHub: threads não sincronizadas (${outcome.reason}).`;
+	}
+	const failures =
+		outcome.failed.length > 0 ? `, ${outcome.failed.length} falha(s)` : "";
+	return `GitHub: ${outcome.resolved.length} thread(s) resolvida(s), ${outcome.skipped.length} já resolvida(s)/pulada(s)${failures}.`;
 }
 
 /** Aplica uma atualização a um finding e persiste. */
 function updateOne(
-	config: HoundsmanConfig,
-	parsed: ParsedArgs,
-	id: string,
+	ctx: CommandContext,
+	input: string,
 	update: FindingUpdate,
 ): FindingState {
-	const { dir, branch } = resolveDir(config, parsed);
-	const store = FindingsStateStore.at(dir, branch);
 	let updated: FindingState | undefined;
-	store.update((state) => {
-		const finding = state.findings[id];
-		if (!finding) return;
-		updated = applyFindingUpdate(finding, update);
+	mutateState(ctx, (state) => {
+		const id = requireFindingId(state, input);
+		updated = applyFindingUpdate(state.findings[id], update);
 	});
-	if (!updated) throw new Error(`Finding '${id}' não encontrado.`);
+	if (!updated) throw new Error(`Finding '${input}' não encontrado.`);
 	return updated;
 }
 
 /** Aplica a mesma atualização a vários ids (done/reset). */
 function updateMany(
-	config: HoundsmanConfig,
-	parsed: ParsedArgs,
-	ids: string[],
+	ctx: CommandContext,
+	inputs: string[],
 	update: FindingUpdate,
 ): FindingState[] {
-	const { dir, branch } = resolveDir(config, parsed);
-	const store = FindingsStateStore.at(dir, branch);
 	const updated: FindingState[] = [];
-	store.update((state) => {
+	mutateState(ctx, (state) => {
+		const ids = inputs.map((input) => requireFindingId(state, input));
 		for (const id of ids) {
-			const finding = state.findings[id];
-			if (!finding) continue;
-			updated.push(applyFindingUpdate(finding, update));
+			updated.push(applyFindingUpdate(state.findings[id], update));
 		}
 	});
-	const missing = ids.filter((id) => !updated.some((f) => f.id === id));
-	if (missing.length > 0) {
-		throw new Error(`Findings não encontrados: ${missing.join(", ")}.`);
-	}
 	return updated;
 }
 
 /** Executa um subcomando de `findings` e devolve o texto + exit code. */
 export function runFindingsCommand(
 	config: HoundsmanConfig,
+	storage: StorageProvider,
+	repo: RepoIdentity,
 	args: string[],
 ): FindingsCommandResult {
-	const parsed = parseArgs(args);
 	try {
-		return execute(config, parsed);
+		const parsed = parseArgs(args);
+		return execute(config, storage, repo, parsed);
 	} catch (error) {
 		return {
 			output: error instanceof Error ? error.message : String(error),
@@ -247,10 +283,16 @@ export function runFindingsCommand(
 	}
 }
 
-function execute(config: HoundsmanConfig, parsed: ParsedArgs): FindingsCommandResult {
+function execute(
+	_config: HoundsmanConfig,
+	storage: StorageProvider,
+	repo: RepoIdentity,
+	parsed: ParsedArgs,
+): FindingsCommandResult {
+	const ctx = openContext(storage, repo, parsed);
 	switch (parsed.sub ?? "list") {
 		case "list": {
-			const state = loadState(config, parsed);
+			const state = loadState(ctx);
 			const filtered = filterFindings(state, filterFrom(parsed));
 			const limit = Number(parsed.values["--limit"]);
 			const findings =
@@ -263,11 +305,11 @@ function execute(config: HoundsmanConfig, parsed: ParsedArgs): FindingsCommandRe
 			};
 		}
 		case "show": {
-			const state = loadState(config, parsed);
-			const id = parsed.positionals[0];
-			if (!id) throw new Error("Informe o id: houndsman findings show <id>");
+			const state = loadState(ctx);
+			const input = parsed.positionals[0];
+			if (!input) throw new Error("Informe o id: houndsman findings show <id>");
+			const id = requireFindingId(state, input);
 			const finding = state.findings[id];
-			if (!finding) throw new Error(`Finding '${id}' não encontrado.`);
 			return {
 				output: parsed.bools.has("--json")
 					? JSON.stringify(finding, null, 2)
@@ -276,56 +318,71 @@ function execute(config: HoundsmanConfig, parsed: ParsedArgs): FindingsCommandRe
 			};
 		}
 		case "set": {
-			const id = parsed.positionals[0];
-			if (!id) throw new Error("Informe o id: houndsman findings set <id> [flags]");
+			const input = parsed.positionals[0];
+			if (!input)
+				throw new Error("Informe o id: houndsman findings set <id> [flags]");
 			const update = updateFrom(parsed);
 			if (!hasUpdate(update)) {
 				throw new Error(
 					"Nada para atualizar (use --decision, --exec ou --comment).",
 				);
 			}
-			const finding = updateOne(config, parsed, id, update);
-			pingStatus(config, parsed);
+			const finding = updateOne(ctx, input, update);
+			pingStatus(ctx, loadState(ctx));
+			const threads =
+				update.execState === "done" ? syncThreadsOutput(ctx, [finding.id]) : null;
 			return {
 				output: parsed.bools.has("--json")
 					? JSON.stringify(finding, null, 2)
-					: `Atualizado: \`${finding.id}\` → ${finding.decision}/${finding.execState}.`,
+					: [
+							`Atualizado: \`${finding.id}\` → ${finding.decision}/${finding.execState}.`,
+							threads,
+						]
+							.filter(Boolean)
+							.join("\n"),
 				exitCode: 0,
 			};
 		}
 		case "done": {
 			const ids = requireIds(parsed, "done");
-			const updated = updateMany(config, parsed, ids, { execState: "done" });
-			pingStatus(config, parsed);
+			const updated = updateMany(ctx, ids, { execState: "done" });
+			pingStatus(ctx, loadState(ctx));
+			const threads = syncThreadsOutput(
+				ctx,
+				updated.map((finding) => finding.id),
+			);
 			return {
-				output: `Marcados como done: ${updated.map((f) => f.id).join(", ")}.`,
+				output: [
+					`Marcados como done: ${updated.map((f) => f.id).join(", ")}.`,
+					threads,
+				]
+					.filter(Boolean)
+					.join("\n"),
 				exitCode: 0,
 			};
 		}
 		case "reset": {
 			const ids = requireIds(parsed, "reset");
-			const updated = updateMany(config, parsed, ids, {
+			const updated = updateMany(ctx, ids, {
 				decision: "pending",
 				execState: "pending",
 				comment: "",
 			});
-			pingStatus(config, parsed);
+			pingStatus(ctx, loadState(ctx));
 			return {
 				output: `Triagem reiniciada: ${updated.map((f) => f.id).join(", ")}.`,
 				exitCode: 0,
 			};
 		}
 		case "sync": {
-			const { dir, branch } = resolveDir(config, parsed);
-			const store = FindingsStateStore.at(dir, branch);
-			const state = loadState(config, parsed);
+			const state = loadState(ctx);
 			const result = syncState(state, fileReader(process.cwd()));
-			store.write(state);
-			pingStatus(config, parsed);
+			ctx.storage.writeFindings(ctx.review.id, state);
+			pingStatus(ctx, state);
 			const output = parsed.bools.has("--json")
 				? JSON.stringify(result, null, 2)
 				: [
-						`Sync — ${branch}: ${result.ok} ok, ${result.moved.length} movido(s), ${result.stale.length} stale.`,
+						`Sync — ${ctx.review.branch}: ${result.ok} ok, ${result.moved.length} movido(s), ${result.stale.length} stale.`,
 						result.moved.length > 0
 							? `Movidos: ${result.moved.join(", ")}`
 							: "",
@@ -338,7 +395,7 @@ function execute(config: HoundsmanConfig, parsed: ParsedArgs): FindingsCommandRe
 			return { output, exitCode: 0 };
 		}
 		case "summary": {
-			const state = loadState(config, parsed);
+			const state = loadState(ctx);
 			const summary = summarize(state);
 			return {
 				output: parsed.bools.has("--json")
@@ -348,12 +405,13 @@ function execute(config: HoundsmanConfig, parsed: ParsedArgs): FindingsCommandRe
 			};
 		}
 		case "path": {
-			const { dir, branch } = resolveDir(config, parsed);
-			const path = FindingsStateStore.at(dir, branch).filePath;
-			return { output: relFromRoot(path), exitCode: 0 };
+			return {
+				output: ctx.storage.location(ctx.review.id),
+				exitCode: 0,
+			};
 		}
 		case "batch": {
-			const state = loadState(config, parsed);
+			const state = loadState(ctx);
 			const severity = parsed.values["--severity"];
 			const offset = Number(parsed.values["--offset"]);
 			const result = fixBatchBuilder.build(state, {
@@ -412,11 +470,13 @@ function requireIds(parsed: ParsedArgs, sub: string): string[] {
  */
 export async function runVerifyCommand(
 	config: HoundsmanConfig,
+	storage: StorageProvider,
+	repo: RepoIdentity,
 	args: string[],
 ): Promise<FindingsCommandResult> {
-	const parsed = parseArgs(args);
 	try {
-		return await executeVerify(config, parsed);
+		const parsed = parseArgs(args);
+		return await executeVerify(config, storage, repo, parsed);
 	} catch (error) {
 		return {
 			output: error instanceof Error ? error.message : String(error),
@@ -427,11 +487,12 @@ export async function runVerifyCommand(
 
 async function executeVerify(
 	config: HoundsmanConfig,
+	storage: StorageProvider,
+	repo: RepoIdentity,
 	parsed: ParsedArgs,
 ): Promise<FindingsCommandResult> {
-	const { dir, branch } = resolveDir(config, parsed);
-	const store = FindingsStateStore.at(dir, branch);
-	const state = loadState(config, parsed);
+	const ctx = openContext(storage, repo, parsed);
+	const state = loadState(ctx);
 
 	// Lazy: `../jev` (axios) só entra no caminho do verify.
 	const verifier = new Verifier();
@@ -471,23 +532,34 @@ async function executeVerify(
 	}
 
 	const summary = verifier.summarize(entries);
-	const reportPath = join(runDir(dir, branch), VERIFY_FILE);
-	writeFileSync(
-		reportPath,
-		`${presenters.verify.render(state, entries, summary, { jevChecked, jevReason })}\n`,
-	);
+	const location = ctx.storage.location(ctx.review.id);
+	ctx.storage.writeArtifact(ctx.review.id, {
+		name: VERIFY_FILE,
+		kind: "verify",
+		content: `${presenters.verify.render(state, entries, summary, { jevChecked, jevReason })}\n`,
+	});
 
 	let applied: string[] = [];
 	if (parsed.bools.has("--apply")) {
-		store.update((current) => {
-			applied = verifier.applyResolutions(current, entries);
+		const current = mutateState(ctx, (draft) => {
+			applied = verifier.applyResolutions(draft, entries);
 		});
-		pingStatus(config, parsed);
+		pingStatus(ctx, current);
 	}
 
+	// Resolvidos localmente ⇒ resolve as conversas correspondentes no PR.
+	const threads = syncThreadsOutput(ctx, applied);
+
 	const output = parsed.bools.has("--json")
 		? JSON.stringify(
-				{ branch, summary, jevChecked, jevReason, applied, entries },
+				{
+					branch: ctx.review.branch,
+					summary,
+					jevChecked,
+					jevReason,
+					applied,
+					entries,
+				},
 				null,
 				2,
 			)
@@ -497,10 +569,11 @@ async function executeVerify(
 					jevReason,
 				}),
 				"",
-				`Relatório: ${relFromRoot(reportPath)}`,
+				`Relatório: ${location} (${VERIFY_FILE})`,
 				parsed.bools.has("--apply")
 					? `Aplicados (done): ${applied.length > 0 ? applied.join(", ") : "—"}.`
 					: "",
+				threads,
 			]
 				.filter(Boolean)
 				.join("\n");
@@ -570,6 +643,21 @@ function renderSubmitOutcome(outcome: SubmitOutcome, json: boolean): string {
 		"",
 		`Enviados: ${outcome.posted.length} · Falhas: ${outcome.failed.length} · Pulados: ${outcome.skipped.length}`,
 	];
+	const review = outcome.review;
+	if (review?.id !== undefined) {
+		const target = review.url ? ` — ${review.url}` : "";
+		if (review.created) {
+			const status = review.finalized
+				? `finalizada (${review.event})`
+				: "criada, mas não finalizada";
+			lines.push(`Revisão #${review.id} ${status}${target}`);
+		} else {
+			lines.push(
+				`Comentários adicionados à revisão pendente #${review.id}${target}`,
+			);
+		}
+	}
+	if (review?.error) lines.push(`Revisão: ❌ ${review.error}`);
 	if (outcome.general) {
 		lines.push(
 			`Comentário geral: ${outcome.general.url ?? outcome.general.commentId} (${outcome.general.ids.length})`,
@@ -582,16 +670,19 @@ function renderSubmitOutcome(outcome: SubmitOutcome, json: boolean): string {
 }
 
 /**
- * Subcomando `findings submit` — envia os findings selecionados como comentários
- * na PR (via `gh`). `--dry-run` mostra a prévia sem postar. Assíncrono (gh).
+ * Subcomando `findings submit` — envia os findings selecionados numa revisão da
+ * PR (via `gh`): reaproveita a revisão pendente ou cria/finaliza uma nova.
+ * `--dry-run` mostra a prévia sem postar. Assíncrono (gh).
  */
 export async function runSubmitCommand(
 	config: HoundsmanConfig,
+	storage: StorageProvider,
+	repo: RepoIdentity,
 	args: string[],
 ): Promise<FindingsCommandResult> {
-	const parsed = parseArgs(args);
 	try {
-		return await executeSubmit(config, parsed);
+		const parsed = parseArgs(args);
+		return await executeSubmit(config, storage, repo, parsed);
 	} catch (error) {
 		return {
 			output: error instanceof Error ? error.message : String(error),
@@ -601,10 +692,13 @@ export async function runSubmitCommand(
 }
 
 async function executeSubmit(
-	config: HoundsmanConfig,
+	_config: HoundsmanConfig,
+	storage: StorageProvider,
+	repo: RepoIdentity,
 	parsed: ParsedArgs,
 ): Promise<FindingsCommandResult> {
-	const state = loadState(config, parsed);
+	const ctx = openContext(storage, repo, parsed);
+	const state = loadState(ctx);
 	const selection = submitSelection(parsed);
 	const target = resolvePrTarget(defaultGhRunner, state.branch);
 	const preview = buildSubmitPreview(state, target, selection);
@@ -621,14 +715,11 @@ async function executeSubmit(
 		runner: defaultGhRunner,
 		selection,
 	});
-	FindingsStateStore.at(
-		parsed.values["--dir"] ?? resolveArtifactDir(config),
-		state.branch,
-	).write(state);
-	pingStatus(config, parsed);
+	ctx.storage.writeFindings(ctx.review.id, state);
+	pingStatus(ctx, state);
 
 	return {
 		output: renderSubmitOutcome(outcome, json),
-		exitCode: outcome.failed.length > 0 ? 1 : 0,
+		exitCode: outcome.failed.length > 0 || Boolean(outcome.review?.error) ? 1 : 0,
 	};
 }

package/src/core/commands/review.ts

@@ -6,24 +6,23 @@
 
 import { ArgParser } from "../arg-parser";
 import { defaultOptions, type ReviewOptions } from "../orchestrator";
-import { ARTIFACT_DIR } from "../paths";
 
 /** Converte argv (sem o subcomando) nas opções de prepare/finalize. */
-export function parseReviewArgs(
-	args: string[],
-	artifactDir: string = ARTIFACT_DIR,
-): ReviewOptions {
+export function parseReviewArgs(args: string[]): ReviewOptions {
 	const parser = ArgParser.from(args);
-	const opts = defaultOptions(artifactDir);
+	if (parser.has("--dir")) {
+		throw new Error(
+			"--dir foi removido; configure `storage` no houndsman.config.ts.",
+		);
+	}
+	const opts = defaultOptions();
 
 	const base = parser.value("--base");
 	const head = parser.value("--head");
 	const branch = parser.value("--branch");
-	const dir = parser.value("--dir");
 	if (base) opts.base = base;
 	if (head) opts.head = head;
 	if (branch) opts.branch = branch;
-	if (dir) opts.dir = dir;
 
 	if (parser.has("--finalize") || parser.has("--report-only")) opts.finalize = true;
 	if (parser.has("--fail-on-blocking")) opts.failOnBlocking = true;