@payconductor/houndsman 0.0.0-stage → 0.1.1

package/src/core/brief.ts

@@ -0,0 +1,185 @@
+/**
+ * Renderização do brief de um watchdog (biblioteca) — `defaultRenderBrief`.
+ *
+ * O procedimento (`PROCEDURE`) é compartilhado por todos os watchdogs; o que era
+ * protocolo específico vive nas regras do watchdog (`rules`).
+ */
+
+import {
+	type Rule,
+	SEVERITY_EMOJI,
+	severityRank,
+	type WatchdogDefinition,
+	type WatchdogRenderArgs,
+	type WatchdogRenderCandidate,
+	type WatchdogRenderContext,
+} from "./types";
+
+/**
+ * Procedimento de revisão — compartilhado por todos os watchdogs.
+ * Substitui o antigo protocolo genérico de 5 passos + o ponteiro `PROTOCOL_GLOB`.
+ */
+export const PROCEDURE: readonly string[] = [
+	"1. **FILTER** — descarte o que não for do seu domínio (ver *Prioridade de leitura* e *Não carregar*).",
+	"2. **READ HEAD** — leia os arquivos seletivamente (primeiras ~30 linhas). NUNCA o diff completo.",
+	"3. **GREP** — use as regras críticas/anti-padrões como heurística para localizar violações.",
+	"4. **DEEP-READ** — aprofunde apenas os arquivos com suspeita de violação.",
+	'5. **CONCLUDE** — grave o JSON no caminho de output, com `reviewedFiles` preenchido. Sem achados → `"findings": []` (arquivo obrigatório). Não escreva markdown livre.',
+];
+
+/** Bloco de contexto da PR, injetado no brief de cada watchdog. */
+export function renderBriefContext(context: WatchdogRenderContext): string[] {
+	const lines = ["## Contexto da PR", ""];
+	if (context.objective) lines.push(`**Objetivo:** ${context.objective}`);
+	if (context.motivation) lines.push(`**Motivação:** ${context.motivation}`);
+	const changeSummary = context.changeSummary ?? [];
+	if (changeSummary.length > 0) {
+		lines.push("", "**Resumo das alterações:**", "");
+		for (const item of changeSummary) lines.push(`- ${item}`);
+	}
+	lines.push("");
+	return lines;
+}
+
+/** Seção de candidatos pré-analisados (Jev) — o watchdog confirma ou refuta. */
+export function renderBriefCandidates(
+	candidates: readonly WatchdogRenderCandidate[],
+): string[] {
+	const lines = [
+		"## Candidatos pré-analisados (Jev) — confirme ou refute",
+		"",
+		"> Indícios automáticos com confiança calibrada. **NÃO** são achados:",
+		"> confirme (virando finding, com a `rule` abaixo) ou ignore se for falso positivo.",
+		"",
+	];
+	for (const candidate of candidates) {
+		lines.push(
+			`- [ ] \`${candidate.file}\` · **${candidate.severity}** · confiança ${candidate.confidence.toFixed(2)}`,
+			`  Regra: ${candidate.rule}`,
+		);
+	}
+	lines.push("");
+	return lines;
+}
+
+/** Linha de lista em code-span: `- \`valor\``. */
+function codeItem(value: string): string {
+	return `- \`${value}\``;
+}
+
+/** Linha de regra com emoji de severidade. */
+function ruleItem(rule: Rule): string {
+	return `- ${SEVERITY_EMOJI[rule.severity]} **${rule.severity}** — ${rule.text}`;
+}
+
+/** Seção opcional (`## <título>` + itens) — vazia se não houver itens. */
+function optionalList(title: string, items: readonly string[] | undefined): string[] {
+	if (!items || items.length === 0) return [];
+	return [`## ${title}`, "", ...items.map((item) => `- ${item}`), ""];
+}
+
+/** Lista de arquivos do domínio com status (e churn, quando disponível). */
+function fileItems(args: WatchdogRenderArgs): string[] {
+	return args.files.map((file) => {
+		const status = args.statuses[file]?.status ?? "modified";
+		const churn = args.churn?.[file];
+		const delta = churn ? `, +${churn.additions}/−${churn.deletions}` : "";
+		return `- \`${file}\` (${status}${delta})`;
+	});
+}
+
+/**
+ * Arquivos do domínio fora do orçamento (triage de PRs grandes): o watchdog NÃO
+ * deve lê-los, mas precisa registrá-los em `skipped` — cobertura honesta.
+ */
+function overflowSection(args: WatchdogRenderArgs): string[] {
+	const overflow = args.overflow ?? [];
+	if (overflow.length === 0) return [];
+	return [
+		"## Fora do orçamento (NÃO revisar)",
+		"",
+		`> ${overflow.length} arquivo(s) do seu domínio ficaram fora do orçamento`,
+		"> (menor churn). Não os leia: registre-os em `skipped` com o motivo",
+		'> "budget" para que a cobertura do relatório fique honesta.',
+		"",
+		...overflow.map(codeItem),
+		"",
+	];
+}
+
+/** Seção de deletados (breaking change) — só p/ watchdogs com `breakingChange`. */
+function deletedSection(args: WatchdogRenderArgs, def: WatchdogDefinition): string[] {
+	if (!def.breakingChange || args.deleted.length === 0) return [];
+	return [
+		"## Deletados — checar breaking change",
+		"",
+		...args.deleted.map(codeItem),
+		"",
+	];
+}
+
+/**
+ * Render padrão do brief de um watchdog (ordem estável).
+ * `def` é a definição do próprio watchdog (evita ciclo com o registry).
+ */
+export function defaultRenderBrief(
+	args: WatchdogRenderArgs,
+	def: WatchdogDefinition,
+): string[] {
+	const lines: string[] = [
+		`# Brief — ${def.name} (\`${def.id}\`)`,
+		"",
+		`**Branch:** ${args.branch}`,
+		`**Output obrigatório:** \`${args.outputPath}\``,
+		`**Schema do output:** \`${args.outputFormatPath}\``,
+		"",
+	];
+
+	if (def.description) lines.push("## Objetivo", "", def.description, "");
+	lines.push("## Escopo", "", def.scope, "");
+
+	if (args.context) lines.push(...renderBriefContext(args.context));
+
+	lines.push(...optionalList("Prioridade de leitura", def.reviewFocus));
+	lines.push(
+		"## Regras (por severidade)",
+		"",
+		...[...def.rules]
+			.sort((a, b) => severityRank(a.severity) - severityRank(b.severity))
+			.map(ruleItem),
+		"",
+	);
+	lines.push(
+		"## Docs de contexto (carregar sob demanda)",
+		"",
+		...args.docs.map(codeItem),
+		"",
+	);
+	lines.push(
+		`## Arquivos do seu domínio (${args.files.length})`,
+		"",
+		...fileItems(args),
+		"",
+	);
+
+	lines.push(...overflowSection(args));
+
+	if (args.candidates && args.candidates.length > 0) {
+		lines.push(...renderBriefCandidates(args.candidates));
+	}
+
+	lines.push(...deletedSection(args, def));
+	lines.push(...optionalList("Não carregar", def.exclude));
+	lines.push("## Procedimento", "", ...PROCEDURE);
+
+	return lines;
+}
+
+/**
+ * Renderiza o brief via hook custom (`def.renderBrief`) ou o padrão.
+ * Passa a própria definição para que o hook possa reutilizar o render padrão.
+ */
+export function renderBrief(def: WatchdogDefinition, args: WatchdogRenderArgs): string {
+	const render = def.renderBrief ?? defaultRenderBrief;
+	return render(args, def).join("\n");
+}

package/src/core/commands/context.ts

@@ -0,0 +1,39 @@
+/**
+ * Subcomando `context` — coleta o contexto da PR via `gh` (Passo 0).
+ *
+ * Biblioteca: grava os artefatos e devolve os dados; o CLI faz o log/exit.
+ */
+
+import { mkdirSync, writeFileSync } from "node:fs";
+import { type HoundsmanConfig, resolveArtifactDir } from "../config";
+import {
+	type ContextPaths,
+	collectPrContext,
+	contextPaths,
+	currentBranch,
+	type PrContextRaw,
+	renderContextBrief,
+} from "../pr-context";
+
+export type ContextRunResult = {
+	paths: ContextPaths;
+	context: PrContextRaw;
+};
+
+/** Coleta a PR atual e grava `context.json` + `context-brief.md`. */
+export function runContextCommand(
+	config: HoundsmanConfig,
+	opts: { branch?: string; dir?: string } = {},
+): ContextRunResult {
+	const branch = opts.branch ?? currentBranch();
+	const dir = opts.dir ?? resolveArtifactDir(config);
+	const paths = contextPaths(dir, branch);
+
+	mkdirSync(paths.dir, { recursive: true });
+
+	const context = collectPrContext(branch);
+	writeFileSync(paths.context, `${JSON.stringify(context, null, 2)}\n`);
+	writeFileSync(paths.brief, `${renderContextBrief(context, branch, paths)}\n`);
+
+	return { paths, context };
+}

package/src/core/commands/findings.ts

@@ -0,0 +1,390 @@
+/**
+ * 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` para interagir sem abrir o JSON à mão.
+ *
+ * Se o `state.json` não existir, é re-construído a partir de
+ * `findings/*.json` + `classification.json` (não exige `--finalize`).
+ */
+
+import { type HoundsmanConfig, resolveArtifactDir } from "../config";
+import {
+	applyFindingUpdate,
+	buildStateFromRunDir,
+	FINDING_DECISIONS,
+	FINDING_EXEC_STATES,
+	type FindingDecision,
+	type FindingExecState,
+	type FindingState,
+	type FindingsFilter,
+	type FindingsStateFile,
+	FindingsStateStore,
+	type FindingsSummary,
+	type FindingUpdate,
+	fileReader,
+	filterFindings,
+	runDir,
+	summarize,
+	syncState,
+} from "../findings-state";
+import { relFromRoot } from "../paths";
+import { currentBranch } from "../pr-context";
+import { SEVERITY_EMOJI, SEVERITY_ORDER, type Severity } from "../types";
+
+export type FindingsCommandResult = {
+	output: string;
+	exitCode: number;
+};
+
+const VALUE_FLAGS = new Set([
+	"--decision",
+	"--exec",
+	"--watchdog",
+	"--severity",
+	"--file",
+	"--branch",
+	"--dir",
+	"--limit",
+	"--comment",
+	"--by",
+]);
+
+type ParsedArgs = {
+	sub?: string;
+	positionals: string[];
+	values: Record<string, string>;
+	bools: Set<string>;
+};
+
+/** Parse simples: primeiro não-flag = sub; demais = positionais. */
+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.startsWith("--")) {
+			if (VALUE_FLAGS.has(arg)) {
+				const value = args[i + 1];
+				if (value !== undefined) parsed.values[arg] = value;
+				i++;
+			} else {
+				parsed.bools.add(arg);
+			}
+			continue;
+		}
+		if (!parsed.sub) parsed.sub = arg;
+		else parsed.positionals.push(arg);
+	}
+	return parsed;
+}
+
+/** Diretório da run + branch resolvida. */
+function resolveDir(
+	config: HoundsmanConfig,
+	parsed: ParsedArgs,
+): { dir: string; branch: string } {
+	return {
+		dir: parsed.values["--dir"] ?? resolveArtifactDir(config),
+		branch: parsed.values["--branch"] ?? currentBranch(),
+	};
+}
+
+/** 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) {
+		throw new Error(
+			`Nenhum estado de triagem para '${branch}'. Rode \`houndsman --finalize\` primeiro.`,
+		);
+	}
+	store.write(built);
+	return built;
+}
+
+// ---------------------------------------------------------------------------
+// Render
+// ---------------------------------------------------------------------------
+
+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");
+}
+
+// ---------------------------------------------------------------------------
+// Execução
+// ---------------------------------------------------------------------------
+
+function parseDecision(raw: string | undefined): FindingDecision | undefined {
+	if (!raw) return undefined;
+	if (!FINDING_DECISIONS.includes(raw as FindingDecision)) {
+		throw new Error(
+			`--decision inválido: '${raw}'. Use: ${FINDING_DECISIONS.join(", ")}.`,
+		);
+	}
+	return raw as FindingDecision;
+}
+
+function parseExec(raw: string | undefined): FindingExecState | undefined {
+	if (!raw) return undefined;
+	if (!FINDING_EXEC_STATES.includes(raw as FindingExecState)) {
+		throw new Error(
+			`--exec inválido: '${raw}'. Use: ${FINDING_EXEC_STATES.join(", ")}.`,
+		);
+	}
+	return raw as FindingExecState;
+}
+
+function filterFrom(parsed: ParsedArgs): FindingsFilter {
+	const severity = parsed.values["--severity"];
+	return {
+		decision: parseDecision(parsed.values["--decision"]),
+		execState: parseExec(parsed.values["--exec"]),
+		watchdog: parsed.values["--watchdog"],
+		severity: severity ? (severity as Severity) : undefined,
+		file: parsed.values["--file"],
+		includeAbsent: parsed.bools.has("--all"),
+	};
+}
+
+/** Aplica uma atualização a um finding e persiste. */
+function updateOne(
+	config: HoundsmanConfig,
+	parsed: ParsedArgs,
+	id: 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);
+	});
+	if (!updated) throw new Error(`Finding '${id}' não encontrado.`);
+	return updated;
+}
+
+/** Aplica a mesma atualização a vários ids (done/reset). */
+function updateMany(
+	config: HoundsmanConfig,
+	parsed: ParsedArgs,
+	ids: string[],
+	update: FindingUpdate,
+): FindingState[] {
+	const { dir, branch } = resolveDir(config, parsed);
+	const store = FindingsStateStore.at(dir, branch);
+	const updated: FindingState[] = [];
+	store.update((state) => {
+		for (const id of ids) {
+			const finding = state.findings[id];
+			if (!finding) continue;
+			updated.push(applyFindingUpdate(finding, 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,
+	args: string[],
+): FindingsCommandResult {
+	const parsed = parseArgs(args);
+	try {
+		return execute(config, parsed);
+	} catch (error) {
+		return {
+			output: error instanceof Error ? error.message : String(error),
+			exitCode: 1,
+		};
+	}
+}
+
+function execute(config: HoundsmanConfig, parsed: ParsedArgs): FindingsCommandResult {
+	switch (parsed.sub ?? "list") {
+		case "list": {
+			const state = loadState(config, parsed);
+			const filtered = filterFindings(state, filterFrom(parsed));
+			const limit = Number(parsed.values["--limit"]);
+			const findings =
+				Number.isFinite(limit) && limit > 0 ? filtered.slice(0, limit) : filtered;
+			return {
+				output: parsed.bools.has("--json")
+					? JSON.stringify(findings, null, 2)
+					: renderList(state, findings),
+				exitCode: 0,
+			};
+		}
+		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 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)
+					: renderList(state, [finding]),
+				exitCode: 0,
+			};
+		}
+		case "set": {
+			const id = parsed.positionals[0];
+			if (!id) 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);
+			return {
+				output: parsed.bools.has("--json")
+					? JSON.stringify(finding, null, 2)
+					: `Atualizado: \`${finding.id}\` → ${finding.decision}/${finding.execState}.`,
+				exitCode: 0,
+			};
+		}
+		case "done": {
+			const ids = requireIds(parsed, "done");
+			const updated = updateMany(config, parsed, ids, { execState: "done" });
+			return {
+				output: `Marcados como done: ${updated.map((f) => f.id).join(", ")}.`,
+				exitCode: 0,
+			};
+		}
+		case "reset": {
+			const ids = requireIds(parsed, "reset");
+			const updated = updateMany(config, parsed, ids, {
+				decision: "pending",
+				execState: "pending",
+				comment: "",
+			});
+			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 result = syncState(state, fileReader(process.cwd()));
+			store.write(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.`,
+						result.moved.length > 0
+							? `Movidos: ${result.moved.join(", ")}`
+							: "",
+						result.stale.length > 0
+							? `Stale: ${result.stale.join(", ")}`
+							: "",
+					]
+						.filter(Boolean)
+						.join("\n");
+			return { output, exitCode: 0 };
+		}
+		case "summary": {
+			const state = loadState(config, parsed);
+			const summary = summarize(state);
+			return {
+				output: parsed.bools.has("--json")
+					? JSON.stringify(summary, null, 2)
+					: renderSummary(state, summary),
+				exitCode: 0,
+			};
+		}
+		case "path": {
+			const { dir, branch } = resolveDir(config, parsed);
+			const path = FindingsStateStore.at(dir, branch).filePath;
+			return { output: relFromRoot(path), exitCode: 0 };
+		}
+		default:
+			return {
+				output: `Subcomando '${parsed.sub}' desconhecido. Use: list, show, set, done, reset, sync, summary, path.`,
+				exitCode: 1,
+			};
+	}
+}
+
+function updateFrom(parsed: ParsedArgs): FindingUpdate {
+	return {
+		decision: parseDecision(parsed.values["--decision"]),
+		execState: parseExec(parsed.values["--exec"]),
+		comment: parsed.values["--comment"],
+		by: parsed.values["--by"],
+	};
+}
+
+function hasUpdate(update: FindingUpdate): boolean {
+	return (
+		update.decision !== undefined ||
+		update.execState !== undefined ||
+		update.comment !== undefined
+	);
+}
+
+function requireIds(parsed: ParsedArgs, sub: string): string[] {
+	if (parsed.positionals.length === 0) {
+		throw new Error(`Informe ao menos um id: houndsman findings ${sub} <id...>`);
+	}
+	return parsed.positionals;
+}

package/src/core/commands/review.ts

@@ -0,0 +1,50 @@
+/**
+ * Subcomando default — parse de flags + prepare/finalize.
+ *
+ * Biblioteca: NÃO usa `process.argv`/`process.exit` (o CLI decide o exit code).
+ */
+
+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",
+]);
+
+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;
+}
+
+/** Converte argv (sem o subcomando) nas opções de prepare/finalize. */
+export function parseReviewArgs(
+	args: string[],
+	artifactDir: string = ARTIFACT_DIR,
+): ReviewOptions {
+	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);
+		}
+	}
+	return opts;
+}