@payconductor/houndsman 0.1.4 → 0.3.0

package/src/core/commands/findings.ts

@@ -27,7 +27,6 @@ import {
 	type FindingsFilter,
 	type FindingsStateFile,
 	FindingsStateStore,
-	type FindingsSummary,
 	type FindingUpdate,
 	fileReader,
 	filterFindings,
@@ -35,22 +34,24 @@ import {
 	summarize,
 	syncState,
 } from "../findings-state";
-import { buildFixBatch, type FixBatchResult } from "../fix-batch";
-import { JevCandidatesStore, JevClient, JevVerifier } from "../jev";
+import {
+	buildSubmitPreview,
+	defaultGhRunner,
+	resolvePrTarget,
+	type SubmitOutcome,
+	type SubmitPreview,
+	type SubmitSelection,
+	submitFindings,
+} from "../github-review";
 import { relFromRoot, 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 { SEVERITY_EMOJI, SEVERITY_ORDER, type Severity } from "../types";
-import {
-	applyJev,
-	applyResolutions,
-	selectVerifiable,
-	summarizeVerify,
-	type VerifyEntry,
-	type VerifyStatus,
-	type VerifySummary,
-	verifyLocal,
-} from "../verify";
+import { FixBatchBuilder } from "../services/fix-batch-builder";
+import { Verifier } from "../services/verifier";
+import { SEVERITY_ORDER, type Severity } from "../types";
 
 export type FindingsCommandResult = {
 	output: string;
@@ -133,90 +134,16 @@ function loadState(config: HoundsmanConfig, parsed: ParsedArgs): FindingsStateFi
 }
 
 // ---------------------------------------------------------------------------
-// Render
+// Apresentação
 // ---------------------------------------------------------------------------
 
-function decisionLabel(decision: FindingDecision): string {
-	return decision;
-}
-
-/** Uma linha compacta por finding (uso no agente). */
-function renderFindingLine(finding: FindingState): string[] {
-	const emoji = SEVERITY_EMOJI[finding.severity];
-	const location = finding.line ? `${finding.file}:${finding.line}` : finding.file;
-	const flags = `${decisionLabel(finding.decision)}/${finding.execState}`;
-	const count = finding.count > 1 ? ` ×${finding.count}` : "";
-	const lines = [
-		`- \`${finding.id}\` ${emoji} **${finding.severity}** \`${location}\` — ${finding.rule}${count}`,
-		`  ${finding.message}`,
-		`  _${flags}_ · watchdogs: ${finding.watchdogIds.join(", ") || "—"}`,
-	];
-	if (finding.comment) lines.push(`  **Comentário:** ${finding.comment}`);
-	return lines;
-}
-
-function renderList(state: FindingsStateFile, findings: FindingState[]): string {
-	if (findings.length === 0) return "Nenhum finding para o filtro informado.";
-	const lines = [`# Findings — ${state.branch} (${findings.length})`, ""];
-	for (const finding of findings) lines.push(...renderFindingLine(finding));
-	return lines.join("\n");
-}
-
-function renderSummary(state: FindingsStateFile, summary: FindingsSummary): string {
-	const decisions = FINDING_DECISIONS.map((d) => `${d} ${summary.byDecision[d]}`).join(
-		" · ",
-	);
-	const exec = FINDING_EXEC_STATES.map((e) => `${e} ${summary.byExecState[e]}`).join(
-		" · ",
-	);
-	const severities = SEVERITY_ORDER.map((s) => `${s} ${summary.bySeverity[s]}`).join(
-		" · ",
-	);
-	return [
-		`# Triagem — ${state.branch}`,
-		"",
-		`Total: ${summary.total} (presentes: ${summary.present})`,
-		`Decisões: ${decisions}`,
-		`Execução: ${exec}`,
-		`Severidade: ${severities}`,
-	].join("\n");
-}
-
-/** Mix de severidade compacto (ex.: `❌1 ⚠️2`). */
-function severityBreakdown(bySeverity: Record<Severity, number>): string {
-	return SEVERITY_ORDER.filter((severity) => bySeverity[severity] > 0)
-		.map((severity) => `${SEVERITY_EMOJI[severity]}${bySeverity[severity]}`)
-		.join(" ");
-}
+const presenters = {
+	findings: new FindingsPresenter(),
+	batch: new BatchPresenter(),
+	verify: new VerifyPresenter(),
+};
 
-/** Render do lote de correção: grupo atual paginado + outros grupos. */
-function renderBatch(result: FixBatchResult): string {
-	const { dimension, current, others, totals } = result;
-	if (totals.queue === 0) return "Nenhum finding pendente de correção.";
-
-	const lines = [
-		`# Lote de correção — agrupado por ${dimension} (${totals.groups} grupo(s))`,
-		"",
-		`## Grupo atual — ${current.key} (${current.total} finding(s), mostrando ${current.returned})`,
-	];
-	for (const finding of current.findings) lines.push(...renderFindingLine(finding));
-	if (current.remaining > 0) {
-		lines.push("", `_… +${current.remaining} neste grupo (use \`--offset\`)._`);
-	}
-	if (others.length > 0) {
-		lines.push("", "## Outros grupos disponíveis");
-		for (const group of others) {
-			lines.push(
-				`- ${group.key} — ${group.count} (${severityBreakdown(group.bySeverity)})`,
-			);
-		}
-	}
-	lines.push(
-		"",
-		`fila: ${totals.queue} · retornados: ${totals.returned} · grupos: ${totals.groups}`,
-	);
-	return lines.join("\n");
-}
+const fixBatchBuilder = new FixBatchBuilder();
 
 // ---------------------------------------------------------------------------
 // Execução
@@ -331,7 +258,7 @@ function execute(config: HoundsmanConfig, parsed: ParsedArgs): FindingsCommandRe
 			return {
 				output: parsed.bools.has("--json")
 					? JSON.stringify(findings, null, 2)
-					: renderList(state, findings),
+					: presenters.findings.list(state, findings),
 				exitCode: 0,
 			};
 		}
@@ -344,7 +271,7 @@ function execute(config: HoundsmanConfig, parsed: ParsedArgs): FindingsCommandRe
 			return {
 				output: parsed.bools.has("--json")
 					? JSON.stringify(finding, null, 2)
-					: renderList(state, [finding]),
+					: presenters.findings.list(state, [finding]),
 				exitCode: 0,
 			};
 		}
@@ -416,7 +343,7 @@ function execute(config: HoundsmanConfig, parsed: ParsedArgs): FindingsCommandRe
 			return {
 				output: parsed.bools.has("--json")
 					? JSON.stringify(summary, null, 2)
-					: renderSummary(state, summary),
+					: presenters.findings.summary(state, summary),
 				exitCode: 0,
 			};
 		}
@@ -429,7 +356,7 @@ function execute(config: HoundsmanConfig, parsed: ParsedArgs): FindingsCommandRe
 			const state = loadState(config, parsed);
 			const severity = parsed.values["--severity"];
 			const offset = Number(parsed.values["--offset"]);
-			const result = buildFixBatch(state, {
+			const result = fixBatchBuilder.build(state, {
 				severity: severity ? (severity as Severity) : undefined,
 				includeDone: parsed.bools.has("--include-done"),
 				offset: Number.isFinite(offset) ? offset : undefined,
@@ -438,7 +365,7 @@ function execute(config: HoundsmanConfig, parsed: ParsedArgs): FindingsCommandRe
 			return {
 				output: parsed.bools.has("--json")
 					? JSON.stringify(result, null, 2)
-					: renderBatch(result),
+					: presenters.batch.render(result),
 				exitCode: 0,
 			};
 		}
@@ -478,43 +405,6 @@ function requireIds(parsed: ParsedArgs, sub: string): string[] {
 // verify — as violações foram resolvidas? (sem re-revisar a PR)
 // ---------------------------------------------------------------------------
 
-/** Rótulo curto de cada status de verificação. */
-const VERIFY_LABEL: Record<VerifyStatus, string> = {
-	resolved: "✅ resolvido",
-	persisting: "❌ persiste",
-	uncertain: "⚠️ incerto",
-	"file-missing": "🗑️ arquivo ausente",
-};
-
-/** Render da verificação: contagem por status + uma linha por finding. */
-function renderVerify(
-	state: FindingsStateFile,
-	entries: VerifyEntry[],
-	summary: VerifySummary,
-	meta: { jevChecked: number; jevReason?: string },
-): string {
-	if (entries.length === 0) return "Nenhum finding para verificar.";
-	const lines = [
-		`# Verificação — ${state.branch} (${entries.length})`,
-		"",
-		`Resolvidos: ${summary.resolved} · Persistem: ${summary.persisting} · Incertos: ${summary.uncertain} · Arquivo ausente: ${summary["file-missing"]}`,
-	];
-	if (meta.jevChecked > 0) lines.push(`Confirmados por Jev: ${meta.jevChecked}.`);
-	else if (meta.jevReason) lines.push(`Jev: pulado (${meta.jevReason}).`);
-	lines.push("");
-	for (const entry of entries) {
-		const location = entry.line ? `${entry.file}:${entry.line}` : entry.file;
-		const via =
-			entry.basis === "jev" ? ` · Jev ${(entry.confidence ?? 0).toFixed(2)}` : "";
-		lines.push(
-			`- \`${entry.id}\` ${VERIFY_LABEL[entry.status]} — **${entry.severity}** \`${location}\` — ${entry.rule}${via}`,
-			`  ${entry.message}`,
-		);
-		if (entry.detail) lines.push(`  _${entry.detail}_`);
-	}
-	return lines.join("\n");
-}
-
 /**
  * Subcomando `findings verify` — checa se as violações foram resolvidas, sem
  * re-revisar a PR. Tier local (grátis) + confirmação Jev dos casos ambíguos
@@ -543,22 +433,26 @@ async function executeVerify(
 	const store = FindingsStateStore.at(dir, branch);
 	const state = loadState(config, parsed);
 
-	const findings = selectVerifiable(state, filterFrom(parsed));
-	const entries = verifyLocal(findings, fileReader(process.cwd()));
+	// Lazy: `../jev` (axios) só entra no caminho do verify.
+	const verifier = new Verifier();
+	const { JevCandidatesStore, JevClient, JevVerifier } = await import("../jev");
+
+	const findings = verifier.select(state, filterFrom(parsed));
+	const entries = verifier.verifyLocal(findings, fileReader(process.cwd()));
 
 	// Tier 1 — Jev só nos ambíguos (fail-open: sem chave/erro mantém o provisório).
 	let jevChecked = 0;
 	let jevReason: string | undefined;
 	const ambiguous = entries.filter((entry) => entry.ambiguous);
 	if (ambiguous.length > 0) {
-		const verifier = new JevVerifier(new JevClient());
+		const jevVerifier = new JevVerifier(new JevClient());
 		if (parsed.bools.has("--no-jev")) {
 			jevReason = "desativado (--no-jev)";
-		} else if (!verifier.isConfigured()) {
+		} else if (!jevVerifier.isConfigured()) {
 			jevReason = "TYPESAFE_API_KEY não configurada";
 		} else {
 			const byId = new Map(findings.map((finding) => [finding.id, finding]));
-			const outcome = await verifier.verify(
+			const outcome = await jevVerifier.verify(
 				ambiguous.map((entry) => ({
 					id: entry.id,
 					file: entry.file,
@@ -570,23 +464,23 @@ async function executeVerify(
 					concurrency: resolveJevConcurrency(config),
 				},
 			);
-			applyJev(entries, outcome.confidence, JevCandidatesStore.THRESHOLD);
+			verifier.applyJev(entries, outcome.confidence, JevCandidatesStore.THRESHOLD);
 			jevChecked = outcome.checked;
 			jevReason = outcome.reason;
 		}
 	}
 
-	const summary = summarizeVerify(entries);
+	const summary = verifier.summarize(entries);
 	const reportPath = join(runDir(dir, branch), VERIFY_FILE);
 	writeFileSync(
 		reportPath,
-		`${renderVerify(state, entries, summary, { jevChecked, jevReason })}\n`,
+		`${presenters.verify.render(state, entries, summary, { jevChecked, jevReason })}\n`,
 	);
 
 	let applied: string[] = [];
 	if (parsed.bools.has("--apply")) {
 		store.update((current) => {
-			applied = applyResolutions(current, entries);
+			applied = verifier.applyResolutions(current, entries);
 		});
 		pingStatus(config, parsed);
 	}
@@ -598,7 +492,10 @@ async function executeVerify(
 				2,
 			)
 		: [
-				renderVerify(state, entries, summary, { jevChecked, jevReason }),
+				presenters.verify.render(state, entries, summary, {
+					jevChecked,
+					jevReason,
+				}),
 				"",
 				`Relatório: ${relFromRoot(reportPath)}`,
 				parsed.bools.has("--apply")
@@ -616,3 +513,122 @@ async function executeVerify(
 
 	return { output, exitCode: failOnPersisting ? 1 : 0 };
 }
+
+// ---------------------------------------------------------------------------
+// Envio (findings submit)
+// ---------------------------------------------------------------------------
+
+/** Flag de lista `a,b,c` → itens não vazios. */
+function splitList(raw: string | undefined): string[] {
+	return (raw ?? "")
+		.split(",")
+		.map((value) => value.trim())
+		.filter(Boolean);
+}
+
+/** Seleção do envio a partir das flags (`--severity`, `--exec`, `--include-sent`). */
+function submitSelection(parsed: ParsedArgs): SubmitSelection {
+	const severities = splitList(parsed.values["--severity"]).filter(
+		(value): value is Severity =>
+			(SEVERITY_ORDER as readonly string[]).includes(value),
+	);
+	const execStates = splitList(parsed.values["--exec"]).filter(
+		(value): value is FindingExecState =>
+			(FINDING_EXEC_STATES as readonly string[]).includes(value),
+	);
+	return {
+		severities: severities.length > 0 ? severities : undefined,
+		execStates: execStates.length > 0 ? execStates : undefined,
+		includeSent: parsed.bools.has("--include-sent"),
+	};
+}
+
+/** Render da prévia do envio (markdown ou JSON). */
+function renderSubmitPreview(preview: SubmitPreview, json: boolean): string {
+	if (json) return JSON.stringify(preview, null, 2);
+	const totals = preview.totals;
+	if (!preview.available) {
+		return [
+			`PR indisponível para envio: ${preview.reason}`,
+			`Prévia local: ${totals.candidates} candidato(s) — ${totals.line} na linha · ${totals.file} no arquivo · ${totals.sent} já enviado(s).`,
+		].join("\n");
+	}
+	const lines = [
+		`# Envio da revisão — PR #${preview.target?.number} (${preview.target?.repo})`,
+		"",
+		`A enviar: ${totals.toSend} (${totals.line} na linha · ${totals.file} no arquivo) · já enviados: ${totals.sent}`,
+	];
+	if (totals.toSend === 0) lines.push("", "Nada a enviar.");
+	return lines.join("\n");
+}
+
+/** Render do resultado do envio (markdown ou JSON). */
+function renderSubmitOutcome(outcome: SubmitOutcome, json: boolean): string {
+	if (json) return JSON.stringify(outcome, null, 2);
+	const lines = [
+		"# Envio da revisão",
+		"",
+		`Enviados: ${outcome.posted.length} · Falhas: ${outcome.failed.length} · Pulados: ${outcome.skipped.length}`,
+	];
+	if (outcome.general) {
+		lines.push(
+			`Comentário geral: ${outcome.general.url ?? outcome.general.commentId} (${outcome.general.ids.length})`,
+		);
+	}
+	for (const failure of outcome.failed) {
+		lines.push(`- ❌ \`${failure.id}\`: ${failure.reason}`);
+	}
+	return lines.join("\n");
+}
+
+/**
+ * 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).
+ */
+export async function runSubmitCommand(
+	config: HoundsmanConfig,
+	args: string[],
+): Promise<FindingsCommandResult> {
+	const parsed = parseArgs(args);
+	try {
+		return await executeSubmit(config, parsed);
+	} catch (error) {
+		return {
+			output: error instanceof Error ? error.message : String(error),
+			exitCode: 1,
+		};
+	}
+}
+
+async function executeSubmit(
+	config: HoundsmanConfig,
+	parsed: ParsedArgs,
+): Promise<FindingsCommandResult> {
+	const state = loadState(config, parsed);
+	const selection = submitSelection(parsed);
+	const target = resolvePrTarget(defaultGhRunner, state.branch);
+	const preview = buildSubmitPreview(state, target, selection);
+	const json = parsed.bools.has("--json");
+
+	// Prévia explícita, ou alvo indisponível (fail-open) — nada a postar.
+	if (parsed.bools.has("--dry-run") || !target.ok) {
+		return { output: renderSubmitPreview(preview, json), exitCode: 0 };
+	}
+
+	const outcome = submitFindings({
+		state,
+		target: target.target,
+		runner: defaultGhRunner,
+		selection,
+	});
+	FindingsStateStore.at(
+		parsed.values["--dir"] ?? resolveArtifactDir(config),
+		state.branch,
+	).write(state);
+	pingStatus(config, parsed);
+
+	return {
+		output: renderSubmitOutcome(outcome, json),
+		exitCode: outcome.failed.length > 0 ? 1 : 0,
+	};
+}

package/src/core/commands/review.ts

@@ -4,49 +4,32 @@
  * Biblioteca: NÃO usa `process.argv`/`process.exit` (o CLI decide o exit code).
  */
 
+import { ArgParser } from "../arg-parser";
 import { defaultOptions, type ReviewOptions } from "../orchestrator";
 import { ARTIFACT_DIR } from "../paths";
 
-const VALUE_FLAGS = new Set(["--base", "--head", "--branch", "--dir"]);
-const BOOLEAN_FLAGS = new Set([
-	"--finalize",
-	"--report-only",
-	"--fail-on-blocking",
-	"--clean",
-	"--no-jev",
-	"--full",
-]);
-
-function applyValue(opts: ReviewOptions, flag: string, value: string | undefined): void {
-	if (!value) return;
-	if (flag === "--base") opts.base = value;
-	else if (flag === "--head") opts.head = value;
-	else if (flag === "--branch") opts.branch = value;
-	else if (flag === "--dir") opts.dir = value;
-}
-
-function applyBoolean(opts: ReviewOptions, flag: string): void {
-	if (flag === "--finalize" || flag === "--report-only") opts.finalize = true;
-	else if (flag === "--fail-on-blocking") opts.failOnBlocking = true;
-	else if (flag === "--clean") opts.clean = true;
-	else if (flag === "--no-jev") opts.noJev = true;
-	else if (flag === "--full") opts.full = true;
-}
-
 /** Converte argv (sem o subcomando) nas opções de prepare/finalize. */
 export function parseReviewArgs(
 	args: string[],
 	artifactDir: string = ARTIFACT_DIR,
 ): ReviewOptions {
+	const parser = ArgParser.from(args);
 	const opts = defaultOptions(artifactDir);
-	for (let i = 0; i < args.length; i++) {
-		const arg = args[i];
-		if (VALUE_FLAGS.has(arg)) {
-			applyValue(opts, arg, args[i + 1]);
-			i++;
-		} else if (BOOLEAN_FLAGS.has(arg)) {
-			applyBoolean(opts, arg);
-		}
-	}
+
+	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;
+	if (parser.has("--clean")) opts.clean = true;
+	if (parser.has("--no-jev")) opts.noJev = true;
+	if (parser.has("--full")) opts.full = true;
+
 	return opts;
 }