@payconductor/houndsman 0.2.0 → 0.3.0

package/src/core/paths.ts

@@ -37,3 +37,12 @@ export const RUN_STATUS_FILE = "run.json";
 
 /** Relatório da verificação de findings, dentro da pasta da run (`<slug>/verify.md`). */
 export const VERIFY_FILE = "verify.md";
+
+/** Contexto bruto da PR (`gh pr view`), dentro da pasta da run. */
+export const CONTEXT_FILE = "context.json";
+
+/** Resumo do contexto gravado pelo subagente, dentro da pasta da run. */
+export const CONTEXT_SUMMARY_FILE = "context-summary.json";
+
+/** Brief do subagente que resume o contexto da PR. */
+export const CONTEXT_BRIEF_FILE = "context-brief.md";

package/src/core/pr-context.ts

@@ -14,16 +14,21 @@
  */
 
 import { existsSync, readFileSync } from "node:fs";
-import { join, relative } from "node:path";
 import {
-	type ContextSummary,
-	parseContextSummary,
-	sanitizeBranch,
-} from "./report-builder";
-
-export const CONTEXT_FILE = "context.json";
-export const CONTEXT_SUMMARY_FILE = "context-summary.json";
-export const CONTEXT_BRIEF_FILE = "context-brief.md";
+	CONTEXT_BRIEF_FILE,
+	CONTEXT_FILE,
+	CONTEXT_SUMMARY_FILE,
+	relFromRoot,
+} from "./paths";
+import type { ContextSummary } from "./report-builder";
+import { parseContextSummary } from "./report-builder";
+import { type ContextPaths, RunLayout } from "./run-layout";
+import { systemClock } from "./services/clock";
+import { defaultGhRunner, GhClient, type GhRunner } from "./services/gh-client";
+import { GitRepository } from "./services/git-repository";
+
+export { CONTEXT_BRIEF_FILE, CONTEXT_FILE, CONTEXT_SUMMARY_FILE };
+export type { ContextPaths };
 
 const GH_JSON_FIELDS =
 	"number,title,body,url,baseRefName,headRefName,author,commits,files";
@@ -54,55 +59,20 @@ export type PrContextRaw = {
 	stats?: { files: number; additions: number; deletions: number };
 };
 
-export type ContextPaths = {
-	dir: string;
-	context: string;
-	summary: string;
-	brief: string;
-};
-
 /** Caminhos dos artefatos de contexto para uma branch. */
 export function contextPaths(dir: string, branch: string): ContextPaths {
-	const dirPath = join(dir, sanitizeBranch(branch));
-	return {
-		dir: dirPath,
-		context: join(dirPath, CONTEXT_FILE),
-		summary: join(dirPath, CONTEXT_SUMMARY_FILE),
-		brief: join(dirPath, CONTEXT_BRIEF_FILE),
-	};
-}
-
-/** Caminho relativo à raiz, sempre com `/` (portável/legível). */
-function relFromRoot(absPath: string): string {
-	return relative(process.cwd(), absPath).replace(/\\/g, "/");
+	return new RunLayout(dir, branch).contextPaths;
 }
 
-/** Detecta a branch atual; encerra com erro se não houver. */
+/** Detecta a branch atual; lança se não houver (o CLI decide o exit). */
 export function currentBranch(): string {
-	const result = Bun.spawnSync(["git", "branch", "--show-current"], {
-		stdout: "pipe",
-		stderr: "pipe",
-	});
-	const branch = new TextDecoder().decode(result.stdout).trim();
+	const branch = new GitRepository().currentBranch();
 	if (!branch) {
-		console.error("Não foi possível detectar a branch. Use --branch <nome>.");
-		process.exit(1);
+		throw new Error("Não foi possível detectar a branch. Use --branch <nome>.");
 	}
 	return branch;
 }
 
-function runGh(args: string[]): { ok: boolean; stdout: string; stderr: string } {
-	const result = Bun.spawnSync(["gh", ...args], {
-		stdout: "pipe",
-		stderr: "pipe",
-	});
-	return {
-		ok: result.exitCode === 0,
-		stdout: new TextDecoder().decode(result.stdout).trim(),
-		stderr: new TextDecoder().decode(result.stderr).trim(),
-	};
-}
-
 type GhPrView = {
 	number?: number;
 	title?: string;
@@ -120,19 +90,23 @@ function unavailable(reason: ContextUnavailableReason, detail: string): PrContex
 		available: false,
 		reason,
 		detail,
-		collectedAt: new Date().toISOString(),
+		collectedAt: systemClock(),
 	};
 }
 
 /** Lê a PR da branch via `gh` e devolve o payload bruto (nunca lança). */
-export function collectPrContext(branch: string): PrContextRaw {
-	const collectedAt = new Date().toISOString();
+export function collectPrContext(
+	branch: string,
+	runner: GhRunner = defaultGhRunner,
+): PrContextRaw {
+	const collectedAt = systemClock();
+	const gh = new GhClient(runner);
 
-	if (!Bun.which("gh")) {
+	if (!gh.isAvailable()) {
 		return unavailable("gh-missing", "GitHub CLI (gh) não encontrado no PATH.");
 	}
 
-	const auth = runGh(["auth", "status"]);
+	const auth = gh.run(["auth", "status"]);
 	if (!auth.ok) {
 		return unavailable(
 			"gh-unauthenticated",
@@ -140,7 +114,7 @@ export function collectPrContext(branch: string): PrContextRaw {
 		);
 	}
 
-	const view = runGh(["pr", "view", branch, "--json", GH_JSON_FIELDS]);
+	const view = gh.run(["pr", "view", branch, "--json", GH_JSON_FIELDS]);
 	if (!view.ok) {
 		const noPr = /no pull requests? found|not found|could not find/i.test(
 			view.stderr,

package/src/core/project-config.ts

@@ -0,0 +1,57 @@
+/**
+ * Configuração do projeto (domínio) — resolve defaults e expõe o registry.
+ *
+ * Evita o "data clump" de passar `HoundsmanConfig` para dezenas de funções:
+ * quem precisa de `artifactDir`/orçamento/concorrência/watchdogs pede aqui.
+ * O contrato do consumidor (`houndsman.config.ts`) não muda.
+ */
+
+import type { HoundsmanConfig } from "./config";
+import {
+	DEFAULT_ALWAYS_INCLUDE_DOCS,
+	DEFAULT_JEV_CONCURRENCY,
+	DEFAULT_MAX_FILES_PER_BRIEF,
+} from "./defaults";
+import { ARTIFACT_DIR } from "./paths";
+import { WatchdogRegistry } from "./watchdog-registry";
+
+/** Configuração resolvida do projeto. */
+export class ProjectConfig<TId extends string = string> {
+	readonly raw: HoundsmanConfig<TId>;
+	readonly watchdogs: WatchdogRegistry<TId>;
+
+	constructor(raw: HoundsmanConfig<TId>) {
+		this.raw = raw;
+		this.watchdogs = new WatchdogRegistry(raw);
+	}
+
+	get projectName(): string {
+		return this.raw.projectName;
+	}
+
+	get artifactDir(): string {
+		return this.raw.artifactDir ?? ARTIFACT_DIR;
+	}
+
+	get maxFilesPerBrief(): number {
+		const value = this.raw.budgets?.maxFilesPerBrief;
+		return value !== undefined && value > 0 ? value : DEFAULT_MAX_FILES_PER_BRIEF;
+	}
+
+	get jevConcurrency(): number {
+		const value = this.raw.concurrency?.jev;
+		return value !== undefined && value > 0 ? value : DEFAULT_JEV_CONCURRENCY;
+	}
+
+	get alwaysIncludeDocs(): readonly string[] {
+		return this.raw.alwaysIncludeDocs ?? DEFAULT_ALWAYS_INCLUDE_DOCS;
+	}
+
+	get exclusions(): readonly RegExp[] {
+		return this.raw.exclusions;
+	}
+
+	get docMappings(): readonly (readonly [RegExp, readonly string[]])[] {
+		return this.raw.docMappings;
+	}
+}

package/src/core/renderers/batch-presenter.ts

@@ -0,0 +1,40 @@
+/**
+ * Apresentação do lote de correção (biblioteca) — markdown do `findings batch`.
+ */
+
+import type { FixBatchResult } from "../fix-batch";
+import { FindingsPresenter } from "./findings-presenter";
+
+/** Renderiza o grupo atual paginado + os outros grupos disponíveis. */
+export class BatchPresenter {
+	private readonly findings = new FindingsPresenter();
+
+	render(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(...this.findings.line(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} (${this.findings.severityBreakdown(group.bySeverity)})`,
+				);
+			}
+		}
+		lines.push(
+			"",
+			`fila: ${totals.queue} · retornados: ${totals.returned} · grupos: ${totals.groups}`,
+		);
+		return lines.join("\n");
+	}
+}

package/src/core/renderers/brief-renderer.ts

@@ -0,0 +1,23 @@
+/**
+ * Renderização de briefs (biblioteca) — superfície OO sobre `brief.ts`.
+ *
+ * O texto continua em `brief.ts` (funções puras); a classe existe para o
+ * pipeline injetar o renderer sem depender da implementação.
+ */
+
+import { renderBrief } from "../brief";
+import type { Watchdog } from "../domain/watchdog";
+import type { WatchdogDefinition, WatchdogRenderArgs } from "../types";
+
+/** Renderiza o brief de um watchdog (hook custom ou default). */
+export class BriefRenderer {
+	/** Render a partir de um `Watchdog` (domínio). */
+	render(watchdog: Watchdog, args: WatchdogRenderArgs): string {
+		return watchdog.renderBrief(args);
+	}
+
+	/** Render a partir da definição declarativa. */
+	renderDefinition(definition: WatchdogDefinition, args: WatchdogRenderArgs): string {
+		return renderBrief(definition, args);
+	}
+}

package/src/core/renderers/findings-presenter.ts

@@ -0,0 +1,74 @@
+/**
+ * Apresentação dos findings (biblioteca) — markdown/JSON do CLI.
+ *
+ * Separado do comando para que o mesmo texto possa ser reutilizado (CLI, UI,
+ * testes) sem arrastar o parse de flags.
+ */
+
+import {
+	FINDING_DECISIONS,
+	FINDING_EXEC_STATES,
+	type FindingDecision,
+	type FindingState,
+	type FindingsStateFile,
+	type FindingsSummary,
+} from "../findings-state";
+import { SEVERITY_EMOJI, SEVERITY_ORDER, type Severity } from "../types";
+
+/** Renderiza findings em markdown compacto (uso no agente). */
+export class FindingsPresenter {
+	/** Uma linha compacta por finding. */
+	line(finding: FindingState): string[] {
+		const emoji = SEVERITY_EMOJI[finding.severity];
+		const location = finding.line ? `${finding.file}:${finding.line}` : finding.file;
+		const flags = `${this.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;
+	}
+
+	/** Lista de findings com cabeçalho. */
+	list(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(...this.line(finding));
+		return lines.join("\n");
+	}
+
+	/** Resumo da triagem (decisões, execução e severidade). */
+	summary(state: FindingsStateFile, summary: FindingsSummary): string {
+		const decisions = FINDING_DECISIONS.map(
+			(decision) => `${decision} ${summary.byDecision[decision]}`,
+		).join(" · ");
+		const exec = FINDING_EXEC_STATES.map(
+			(stateName) => `${stateName} ${summary.byExecState[stateName]}`,
+		).join(" · ");
+		const severities = SEVERITY_ORDER.map(
+			(severity) => `${severity} ${summary.bySeverity[severity]}`,
+		).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`). */
+	severityBreakdown(bySeverity: Record<Severity, number>): string {
+		return SEVERITY_ORDER.filter((severity) => bySeverity[severity] > 0)
+			.map((severity) => `${SEVERITY_EMOJI[severity]}${bySeverity[severity]}`)
+			.join(" ");
+	}
+
+	private decisionLabel(decision: FindingDecision): string {
+		return decision;
+	}
+}

package/src/core/renderers/manifest-writer.ts

@@ -0,0 +1,112 @@
+/**
+ * Manifesto da run (biblioteca) — monta e grava o `manifest.json`.
+ *
+ * Concentra o resumo do que foi ativado (watchdogs, orçamento, churn, contexto,
+ * Jev e incremental), hoje espalhado em helpers do orquestrador.
+ */
+
+import { Classification } from "../domain/classification";
+import type { ClassificationResult } from "../file-classifier";
+import type { JevCandidatesFile } from "../jev";
+import { OUTPUT_FORMAT_PATH, relFromRoot } from "../paths";
+import { readContextSummary } from "../pr-context";
+import type { ProjectConfig } from "../project-config";
+import type { MergedFinding } from "../report-builder";
+import type { RunLayout } from "../run-layout";
+import { systemClock } from "../services/clock";
+import { ProjectFiles } from "../services/project-files";
+
+/** Opções do manifesto (subset do `ReviewOptions`). */
+export type ManifestOptions = {
+	base: string;
+	head: string;
+};
+
+/** Classificação enriquecida gravada pelo prepare (modo + incremental). */
+export type ManifestClassification = ClassificationResult & {
+	headSha?: string;
+	mode: "full" | "incremental";
+	reviewedFrom?: string;
+	carryover?: MergedFinding[];
+};
+
+/** Escreve o `manifest.json` de uma run. */
+export class ManifestWriter {
+	private readonly layout: RunLayout;
+	private readonly project: ProjectConfig;
+	private readonly options: ManifestOptions;
+
+	constructor(layout: RunLayout, project: ProjectConfig, options: ManifestOptions) {
+		this.layout = layout;
+		this.project = project;
+		this.options = options;
+	}
+
+	write(
+		classification: ManifestClassification,
+		activeIds: string[],
+		pending: string[],
+		jev: JevCandidatesFile,
+	): void {
+		const view = Classification.from(classification);
+		const maxFilesPerBrief = this.project.maxFilesPerBrief;
+		let filesOverBudget = 0;
+
+		const watchdogs = activeIds.map((id) => {
+			const selection = view.budgetFor(id, maxFilesPerBrief);
+			filesOverBudget += selection.overflow.length;
+			return {
+				id,
+				name: this.project.watchdogs.nameOf(id),
+				files: selection.selected,
+				overflow: selection.overflow.length,
+				brief: relFromRoot(this.layout.briefFile(id)),
+				findings: relFromRoot(this.layout.findingFile(id)),
+				status: pending.includes(id) ? "pending" : "done",
+			};
+		});
+
+		const summary = readContextSummary(this.layout.contextPaths.summary);
+		const manifest = {
+			branch: this.layout.branch,
+			slug: this.layout.slug,
+			base: this.options.base,
+			head: this.options.head,
+			headSha: classification.headSha,
+			generatedAt: systemClock(),
+			outputFormat: OUTPUT_FORMAT_PATH,
+			budget: { maxFilesPerBrief, filesOverBudget },
+			churn: view.churnTotals,
+			incremental:
+				classification.mode === "incremental"
+					? {
+							from: classification.reviewedFrom,
+							changedFiles: Object.keys(classification.files).length,
+							carried: classification.carryover?.length ?? 0,
+						}
+					: undefined,
+			watchdogs,
+			context: summary
+				? { summarized: true, source: summary.source ?? null }
+				: { summarized: false, source: null },
+			jev: jev.available
+				? {
+						available: true,
+						model: jev.model,
+						threshold: jev.threshold,
+						analyzedFiles: jev.analyzedFiles,
+						candidates: jev.candidates.length,
+						skipped: jev.skipped?.length ?? 0,
+					}
+				: { available: false, reason: jev.reason },
+			deleted: classification.deleted,
+			unclassified: classification.unclassified,
+			excludedCount: classification.excludedCount,
+		};
+
+		new ProjectFiles().write(
+			this.layout.manifestFile,
+			`${JSON.stringify(manifest, null, 2)}\n`,
+		);
+	}
+}

package/src/core/renderers/report-renderer.ts

@@ -0,0 +1,66 @@
+/**
+ * Renderização do relatório (biblioteca) — superfície OO sobre `report-builder`.
+ *
+ * O texto continua nas funções puras; a classe fixa o resolver de nomes e evita
+ * repetir a lista de argumentos no orquestrador.
+ */
+
+import type { JevCandidate } from "../jev";
+import {
+	type ContextSummary,
+	type DomainReport,
+	type MergedFinding,
+	renderDomainReport,
+	renderReport,
+	type WatchdogNameResolver,
+	type WatchdogReport,
+} from "../report-builder";
+
+/** Renderiza o relatório consolidado e os relatórios por domínio. */
+export class ReportRenderer {
+	private readonly nameOf: WatchdogNameResolver;
+
+	constructor(nameOf: WatchdogNameResolver) {
+		this.nameOf = nameOf;
+	}
+
+	/** Relatório consolidado (`review.md`). */
+	render(
+		branch: string,
+		reports: WatchdogReport[],
+		merged: MergedFinding[],
+		coverage: { classified?: Record<string, string[]> },
+		context?: ContextSummary | null,
+		candidates?: JevCandidate[],
+		domains: readonly DomainReport[] = [],
+	): string {
+		return renderReport(
+			branch,
+			reports,
+			merged,
+			coverage,
+			context,
+			candidates,
+			this.nameOf,
+			domains,
+		);
+	}
+
+	/** Relatório isolado de um watchdog (`review.<id>.md`). */
+	renderDomain(
+		branch: string,
+		report: WatchdogReport,
+		merged: MergedFinding[],
+		expectedFiles: number,
+		context?: ContextSummary | null,
+	): string {
+		return renderDomainReport(
+			branch,
+			report,
+			merged,
+			expectedFiles,
+			context,
+			this.nameOf,
+		);
+	}
+}

package/src/core/renderers/verify-presenter.ts

@@ -0,0 +1,50 @@
+/**
+ * Apresentação da verificação de findings (biblioteca) — markdown do `verify`.
+ */
+
+import type { FindingsStateFile } from "../findings-state";
+import type { VerifyEntry, VerifyStatus, VerifySummary } from "../verify";
+
+/** 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",
+};
+
+/** Metadados do Jev exibidos no cabeçalho. */
+export type VerifyMeta = { jevChecked: number; jevReason?: string };
+
+/** Renderiza a verificação: contagem por status + uma linha por finding. */
+export class VerifyPresenter {
+	render(
+		state: FindingsStateFile,
+		entries: VerifyEntry[],
+		summary: VerifySummary,
+		meta: VerifyMeta,
+	): 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");
+	}
+}

package/src/core/renderers/watchdog-presenter.ts

@@ -0,0 +1,100 @@
+/**
+ * Apresentação do contexto de um watchdog (biblioteca) — markdown/JSON.
+ */
+
+import type { WatchdogContext } from "../domain/watchdog";
+import {
+	type Rule,
+	SEVERITY_EMOJI,
+	severityRank,
+	type WatchdogDefinition,
+} from "../types";
+
+/** Opções de apresentação do watchdog. */
+export type WatchdogRenderOptions = {
+	/** Inclui as regras. */
+	withRules: boolean;
+	/** Saída JSON (default: markdown). */
+	json: boolean;
+};
+
+/** Renderiza o contexto de um watchdog. */
+export class WatchdogPresenter {
+	render(
+		context: WatchdogContext,
+		definition: WatchdogDefinition,
+		options: WatchdogRenderOptions,
+	): string {
+		return options.json
+			? this.serialize(context, definition, options.withRules)
+			: this.markdown(context, definition, options.withRules);
+	}
+
+	/** Payload serializável (regras incluídas apenas com `withRules`). */
+	private serialize(
+		context: WatchdogContext,
+		definition: WatchdogDefinition,
+		withRules: boolean,
+	): string {
+		const payload = withRules
+			? { ...context, rules: definition.rules }
+			: { ...context };
+		return JSON.stringify(payload, null, 2);
+	}
+
+	/** Lista de itens em bloco `## <título>` (vazio se não houver itens). */
+	private section(title: string, items: readonly string[] | undefined): string[] {
+		if (!items || items.length === 0) return [];
+		return [`## ${title}`, "", ...items.map((item) => `- ${item}`), ""];
+	}
+
+	/** Regras com emoji de severidade em bloco `## <título>`. */
+	private ruleSection(title: string, rules: readonly Rule[]): string[] {
+		return [
+			`## ${title}`,
+			"",
+			...rules.map(
+				(rule) =>
+					`- ${SEVERITY_EMOJI[rule.severity]} **${rule.severity}** — ${rule.text}`,
+			),
+			"",
+		];
+	}
+
+	/** Render markdown legível do contexto do watchdog. */
+	private markdown(
+		context: WatchdogContext,
+		definition: WatchdogDefinition,
+		withRules: boolean,
+	): string {
+		const lines: string[] = [
+			`# ${context.name} (\`${context.id}\`)`,
+			"",
+			`**Descrição:** ${context.description}`,
+			`**Escopo:** ${context.scope}`,
+			"",
+		];
+
+		lines.push(...this.section("Prioridade de leitura", context.reviewFocus));
+		lines.push(...this.section("Não carregar", context.exclude));
+		lines.push(
+			...this.section(
+				"Docs de contexto",
+				context.contextFiles.map((doc) => `\`${doc}\``),
+			),
+		);
+
+		if (withRules) {
+			lines.push(
+				...this.ruleSection(
+					"Regras",
+					[...definition.rules].sort(
+						(a, b) => severityRank(a.severity) - severityRank(b.severity),
+					),
+				),
+			);
+		}
+
+		return lines.join("\n").trimEnd();
+	}
+}