@payconductor/houndsman 0.1.3 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@payconductor/houndsman",
-	"version": "0.1.3",
+	"version": "0.2.0",
 	"description": "Orquestrador de revisão de Pull Requests: classifica o diff, despacha watchdogs especializados por domínio e consolida o relatório.",
 	"type": "module",
 	"license": "MIT",

package/src/cli/index.ts

@@ -7,11 +7,14 @@
  * cwd) e orquestra funções/classes de `core/`. Não importa nenhum caminho do
  * projeto consumidor estaticamente.
  *
+ * Cada comando carrega seus módulos por import dinâmico (lazy) — o startup não
+ * paga por `server`, Jev (axios) ou `orchestrator` que o comando não usa.
+ *
  * Comandos:
  *   (default)            Passo 1 — preparar (classificação + briefs + manifesto)
  *   --finalize           Passo 3 — consolidar os findings em review.md
  *   context              Passo 0 — coletar o contexto da PR via `gh`
- *   findings <sub>       Triagem/correção dos findings (list/set/done/sync/batch/verify/...)
+ *   findings <sub>       Triagem/correção dos findings (list/set/done/sync/batch/verify/submit/...)
  *   server               Sobe a UI local de triagem (Bun.serve)
  *   setup                Cria a configuração inicial do projeto (config + skills)
  *   update               Sincroniza os arquivos auto-gerados (.houndsman/core)
@@ -23,20 +26,9 @@
  *   `--config <path>` · `--clean` · `--full` · `--no-jev` · `--fail-on-blocking`.
  */
 
-import { runContextCommand } from "../core/commands/context";
-import { runFindingsCommand, runVerifyCommand } from "../core/commands/findings";
-import { parseReviewArgs } from "../core/commands/review";
-import { runSetupCommand } from "../core/commands/setup";
-import { runLibTests } from "../core/commands/test";
-import { runUpdateCommand } from "../core/commands/update";
-import { renderWatchdogContext } from "../core/commands/watchdog";
 import { type HoundsmanConfig, resolveArtifactDir } from "../core/config";
 import { loadConfig } from "../core/config-loader";
-import { JevClient } from "../core/jev";
-import { finalize, prepare, resolveBranch } from "../core/orchestrator";
 import { relFromRoot } from "../core/paths";
-import { checkRegistry } from "../core/registry-check";
-import { startServer } from "../server";
 
 const HELP = `Uso: houndsman [comando] [flags]
 
@@ -44,7 +36,7 @@ Comandos:
   (nenhum)            Prepara a revisão (classification + briefs + manifesto)
   --finalize          Consolida os findings em review.md
   context             Coleta o contexto da PR via gh (Passo 0)
-  findings <sub>      Triagem/correção dos findings (list · show · set · done · reset · sync · summary · batch · verify · path)
+  findings <sub>      Triagem/correção dos findings (list · show · set · done · reset · sync · summary · batch · verify · submit · path)
   server              Sobe a UI local de triagem (--port, --host, --open)
   setup               Cria a configuração inicial do projeto (config + skills)
   update              Sincroniza os arquivos auto-gerados (.houndsman/core)
@@ -77,7 +69,9 @@ Flags de findings:
   --offset <n>        Paginação dentro do grupo (batch)
   --include-done      Inclui já concluídos no batch
   --apply             (verify) Marca os resolvidos como done
-  --fail-on-persisting (verify) Exit 1 se algum blocking persistir`;
+  --fail-on-persisting (verify) Exit 1 se algum blocking persistir
+  --include-sent      (submit) Reenvia findings já enviados à PR
+  --dry-run           (submit) Só a prévia do envio, sem postar`;
 
 function readFlag(args: string[], flag: string): string | undefined {
 	const index = args.indexOf(flag);
@@ -85,7 +79,8 @@ function readFlag(args: string[], flag: string): string | undefined {
 }
 
 /** Passo 0 — contexto da PR via `gh`. */
-function runContext(config: HoundsmanConfig, args: string[]): void {
+async function runContext(config: HoundsmanConfig, args: string[]): Promise<void> {
+	const { runContextCommand } = await import("../core/commands/context");
 	const { paths, context } = runContextCommand(config, {
 		branch: readFlag(args, "--branch"),
 		dir: readFlag(args, "--dir"),
@@ -114,6 +109,7 @@ function runContext(config: HoundsmanConfig, args: string[]): void {
 
 /** Valida a configuração do projeto e o ambiente. */
 async function runDoctor(config: HoundsmanConfig): Promise<void> {
+	const { checkRegistry } = await import("../core/registry-check");
 	console.log("→ Validando configuração do projeto...");
 	const { problems, warnings, jevQuestions } = checkRegistry(config);
 
@@ -142,6 +138,7 @@ async function runDoctor(config: HoundsmanConfig): Promise<void> {
  * Fail-open — nunca altera o exit code (`doctor` é diagnóstico).
  */
 async function reportJevCredential(): Promise<void> {
+	const { JevClient } = await import("../core/jev");
 	const client = new JevClient();
 	if (!client.isConfigured()) {
 		console.log("  ⚠️  TYPESAFE_API_KEY (opcional — pré-análise Jev)");
@@ -158,7 +155,8 @@ async function reportJevCredential(): Promise<void> {
 }
 
 /** Contexto de um watchdog. */
-function runWatchdog(config: HoundsmanConfig, args: string[]): void {
+async function runWatchdog(config: HoundsmanConfig, args: string[]): Promise<void> {
+	const { renderWatchdogContext } = await import("../core/commands/watchdog");
 	const id = args.find((arg) => !arg.startsWith("-"));
 
 	if (!id || renderWatchdogContext(config, id) === null) {
@@ -185,11 +183,16 @@ function runWatchdog(config: HoundsmanConfig, args: string[]): void {
  * o JSON. O `verify` é assíncrono (consulta opcional ao Jev) — roteado à parte.
  */
 async function runFindings(config: HoundsmanConfig, args: string[]): Promise<void> {
+	const { runFindingsCommand, runSubmitCommand, runVerifyCommand } = await import(
+		"../core/commands/findings"
+	);
 	const sub = args.find((arg) => !arg.startsWith("-"));
 	const result =
 		sub === "verify"
 			? await runVerifyCommand(config, args)
-			: runFindingsCommand(config, args);
+			: sub === "submit"
+				? await runSubmitCommand(config, args)
+				: runFindingsCommand(config, args);
 	if (result.exitCode !== 0) {
 		console.error(result.output);
 		process.exit(result.exitCode);
@@ -213,7 +216,8 @@ function openBrowser(url: string): void {
 }
 
 /** Subcomando `server` — sobe a UI local de triagem. */
-function runServer(config: HoundsmanConfig, args: string[]): void {
+async function runServer(config: HoundsmanConfig, args: string[]): Promise<void> {
+	const { startServer } = await import("../server");
 	const port = Number(readFlag(args, "--port")) || 7331;
 	const host = readFlag(args, "--host") ?? "127.0.0.1";
 	const { url } = startServer({ config, port, host });
@@ -224,6 +228,9 @@ function runServer(config: HoundsmanConfig, args: string[]): void {
 
 /** Passo 1/3 — preparar ou finalizar. */
 async function runReview(config: HoundsmanConfig, args: string[]): Promise<void> {
+	const [{ parseReviewArgs }, { finalize, prepare, resolveBranch }] = await Promise.all(
+		[import("../core/commands/review"), import("../core/orchestrator")],
+	);
 	const opts = parseReviewArgs(args, resolveArtifactDir(config));
 	const branch = resolveBranch(opts);
 
@@ -246,13 +253,16 @@ export async function main(): Promise<void> {
 	const rest = command ? argv.slice(1) : argv;
 
 	if (command === "test") {
+		const { runLibTests } = await import("../core/commands/test");
 		process.exit(runLibTests());
 	}
 	if (command === "setup") {
+		const { runSetupCommand } = await import("../core/commands/setup");
 		await runSetupCommand({ cwd: process.cwd(), args: rest });
 		return;
 	}
 	if (command === "update") {
+		const { runUpdateCommand } = await import("../core/commands/update");
 		await runUpdateCommand({ cwd: process.cwd(), args: rest });
 		return;
 	}
@@ -268,20 +278,20 @@ export async function main(): Promise<void> {
 
 	switch (command) {
 		case "context":
-			runContext(config, rest);
+			await runContext(config, rest);
 			return;
 		case "doctor":
 		case "check":
 			await runDoctor(config);
 			return;
 		case "watchdog":
-			runWatchdog(config, rest);
+			await runWatchdog(config, rest);
 			return;
 		case "findings":
 			await runFindings(config, rest);
 			return;
 		case "server":
-			runServer(config, rest);
+			await runServer(config, rest);
 			return;
 		case undefined:
 			await runReview(config, rest);

package/src/core/commands/findings.ts

@@ -36,21 +36,22 @@ import {
 	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 { 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";
+// Tipos são apagados no transpile (custo zero). Os **valores** de `../verify` e de
+// `../jev` (axios) entram por import dinâmico — só o subcomando `verify` os usa.
+import type { VerifyEntry, VerifyStatus, VerifySummary } from "../verify";
 
 export type FindingsCommandResult = {
 	output: string;
@@ -543,6 +544,12 @@ async function executeVerify(
 	const store = FindingsStateStore.at(dir, branch);
 	const state = loadState(config, parsed);
 
+	// Lazy: `../verify` (leve) e `../jev` (axios) só entram no caminho do verify.
+	const [
+		{ selectVerifiable, verifyLocal, summarizeVerify, applyJev, applyResolutions },
+		{ JevCandidatesStore, JevClient, JevVerifier },
+	] = await Promise.all([import("../verify"), import("../jev")]);
+
 	const findings = selectVerifiable(state, filterFrom(parsed));
 	const entries = verifyLocal(findings, fileReader(process.cwd()));
 
@@ -616,3 +623,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/findings-state.ts

@@ -67,6 +67,22 @@ export type FindingHistoryEntry = {
 	by?: string;
 };
 
+/**
+ * Vínculo com o comentário remoto no GitHub (envio da revisão). Gravado pelo
+ * `findings submit` / UI — permite pular reenvios e abrir o comentário.
+ */
+export type GitHubLink = {
+	/** Id do comentário (review comment inline ou issue comment geral). */
+	commentId: number;
+	url?: string;
+	/** Origem do comentário remoto: linha, arquivo ou comentário geral. */
+	kind: "line" | "file" | "comment";
+	/** Número da PR de destino. */
+	pr: number;
+	/** Quando foi enviado (ISO). */
+	at: string;
+};
+
 /** Marco da revisão que originou o estado: commit revisado + quando. */
 export type FindingsReviewed = {
 	/** SHA do commit revisado (head do diff no `--finalize`). */
@@ -99,6 +115,8 @@ export type FindingState = {
 	createdAt: string;
 	updatedAt: string;
 	history: FindingHistoryEntry[];
+	/** Vínculo com o comentário remoto no GitHub (envio da revisão). */
+	github?: GitHubLink;
 };
 
 /** Conteúdo do `state.json`. */
@@ -345,6 +363,7 @@ export function buildStateFromFindings(
 			createdAt: prev?.createdAt ?? now,
 			updatedAt: now,
 			history: prev?.history ?? [],
+			github: prev?.github,
 		};
 		byFingerprint.set(fingerprint, created);
 		result[created.id] = created;