@payconductor/houndsman 0.13.0 → 0.14.0

package/src/core/commands/compare.ts

@@ -0,0 +1,233 @@
+/**
+ * Comando `compare` (biblioteca) — compara duas runs da mesma branch.
+ *
+ * Resolve o par por slug (como na URL da UI) ou por `(branch, variante)`, lê os
+ * artefatos de cada review e grava `compare-<a>--<b>.md|.json` na run B.
+ */
+
+import {
+	buildComparison,
+	type ComparisonFinding,
+	comparisonToJson,
+	countBySeverity,
+	type ReviewSnapshot,
+	renderComparison,
+} from "../compare";
+import { currentBranch } from "../pr-context";
+import type { RepoIdentity, ReviewRecord, StorageProvider } from "../storage/types";
+import type { Severity } from "../types";
+
+/** Seleção do par A/B. */
+export type CompareOptions = {
+	/** Slugs prontos (como exibidos na UI). */
+	slugA?: string;
+	slugB?: string;
+	/** Identidade alternativa: branch + rótulos de variante. */
+	branch?: string;
+	variantA?: string;
+	variantB?: string;
+};
+
+/** Resultado do comando. */
+export type CompareResult = {
+	markdown: string;
+	json: string;
+	a: ReviewRecord;
+	b: ReviewRecord;
+	artifacts: { markdown: string; json: string };
+};
+
+type ManifestShape = {
+	watchdogs?: { files?: string[]; overflow?: number }[];
+	ai?: { model?: string };
+};
+
+type ReportShape = { durationMs?: number };
+type HuntShape = {
+	model?: string;
+	durationMs?: number;
+	totals?: { totalTokens?: number; costUsd?: number };
+};
+type AiUsageShape = { total?: { totalTokens?: number } };
+
+/** Resolve a run pelo slug dentro do repositório. */
+function bySlug(
+	storage: StorageProvider,
+	repo: RepoIdentity,
+	slug: string,
+): ReviewRecord {
+	const review = storage
+		.listReviews(repo.key)
+		.find((candidate) => candidate.slug === slug);
+	if (!review) throw new Error(`Nenhuma run com slug '${slug}' neste repositório.`);
+	return review;
+}
+
+/** Resolve o par A/B (slug ou branch + variantes). */
+export function resolveComparePair(
+	storage: StorageProvider,
+	repo: RepoIdentity,
+	options: CompareOptions,
+): [ReviewRecord, ReviewRecord] {
+	if (options.slugA && options.slugB) {
+		return [
+			bySlug(storage, repo, options.slugA),
+			bySlug(storage, repo, options.slugB),
+		];
+	}
+	const branch = options.branch ?? currentBranch();
+	const variantB = options.variantB?.trim();
+	if (!variantB) {
+		throw new Error(
+			"Informe --b <variante> (ou passe dois slugs: `houndsman compare <a> <b>`).",
+		);
+	}
+	const a = storage.findReview(repo.key, branch, options.variantA);
+	const b = storage.findReview(repo.key, branch, variantB);
+	if (!a) {
+		throw new Error(
+			`Nenhuma revisão para '${branch}'${options.variantA ? ` (variante '${options.variantA}')` : ""}.`,
+		);
+	}
+	if (!b) throw new Error(`Nenhuma revisão para '${branch}' (variante '${variantB}').`);
+	return [a, b];
+}
+
+function readJson<T>(storage: StorageProvider, reviewId: string, name: string): T | null {
+	const artifact = storage.readArtifact(reviewId, name);
+	if (!artifact) return null;
+	try {
+		return JSON.parse(artifact.content) as T;
+	} catch {
+		return null;
+	}
+}
+
+/** Extrai o snapshot comparável de uma run. */
+function snapshotOf(
+	storage: StorageProvider,
+	review: ReviewRecord,
+	label: string,
+): ReviewSnapshot {
+	const state = storage.readFindings(review.id);
+	const findings: ComparisonFinding[] = Object.values(state?.findings ?? {})
+		.filter((finding) => finding.present)
+		.map((finding) => ({
+			fingerprint: finding.fingerprint,
+			rule: finding.rule,
+			severity: finding.severity,
+			file: finding.file,
+			line: finding.line ?? undefined,
+			message: finding.message,
+			watchdogs: finding.watchdogIds,
+		}));
+
+	const manifest = readJson<ManifestShape>(storage, review.id, "manifest.json");
+	const prepare = readJson<ReportShape>(storage, review.id, "prepare-report.json");
+	const hunt = readJson<HuntShape>(storage, review.id, "hunt-report.json");
+	const aiUsage = readJson<AiUsageShape>(storage, review.id, "ai-usage.json");
+
+	const started = review.startedAt ? Date.parse(review.startedAt) : Number.NaN;
+	const reviewed = review.reviewedAt ? Date.parse(review.reviewedAt) : Number.NaN;
+	const durationMs =
+		Number.isFinite(started) && Number.isFinite(reviewed) && reviewed >= started
+			? reviewed - started
+			: undefined;
+
+	const watchdogs = manifest?.watchdogs ?? [];
+	// Domínios se sobrepõem: conta arquivos únicos, não "slots" por watchdog.
+	const files = new Set<string>();
+	for (const watchdog of watchdogs) {
+		for (const file of watchdog.files ?? []) files.add(file);
+	}
+	return {
+		label,
+		slug: review.slug,
+		branch: review.branch,
+		variant: review.variant,
+		headSha: review.headSha ?? review.reviewedSha,
+		model: hunt?.model ?? manifest?.ai?.model,
+		findings,
+		bySeverity: countBySeverity(findings),
+		coverage: {
+			watchdogs: watchdogs.length,
+			files: files.size,
+			overflow: watchdogs.reduce(
+				(total, watchdog) => total + (watchdog.overflow ?? 0),
+				0,
+			),
+		},
+		durationMs,
+		prepareMs: prepare?.durationMs,
+		huntMs: hunt?.durationMs,
+		tokens: hunt?.totals?.totalTokens ?? aiUsage?.total?.totalTokens,
+		costUsd: hunt?.totals?.costUsd,
+	};
+}
+
+/** Executa a comparação e persiste o relatório na run B. */
+export function runCompare(
+	storage: StorageProvider,
+	repo: RepoIdentity,
+	options: CompareOptions,
+): CompareResult {
+	const [a, b] = resolveComparePair(storage, repo, options);
+	const comparison = buildComparison(
+		snapshotOf(storage, a, "A"),
+		snapshotOf(storage, b, "B"),
+	);
+	const markdown = renderComparison(comparison);
+	const json = comparisonToJson(comparison);
+	const base = `compare-${a.slug}--${b.slug}`;
+	storage.writeArtifact(b.id, {
+		name: `${base}.md`,
+		kind: "compare",
+		content: markdown,
+	});
+	storage.writeArtifact(b.id, {
+		name: `${base}.json`,
+		kind: "compare",
+		content: json,
+	});
+	return {
+		markdown,
+		json,
+		a,
+		b,
+		artifacts: { markdown: `${base}.md`, json: `${base}.json` },
+	};
+}
+
+/** Linha da listagem de variantes da branch. */
+export type CompareListItem = {
+	slug: string;
+	branch: string;
+	variant?: string;
+	status: ReviewRecord["status"];
+	findings: number;
+	bySeverity: Record<Severity, number>;
+	updatedAt: string;
+};
+
+/** Lista as runs do repositório (filtra por branch quando informado). */
+export function listRunsForCompare(
+	storage: StorageProvider,
+	repo: RepoIdentity,
+	branch?: string,
+): CompareListItem[] {
+	return storage
+		.listReviews(repo.key)
+		.filter((review) => !branch || review.branch === branch)
+		.map((review) => {
+			const snapshot = snapshotOf(storage, review, review.variant ?? "principal");
+			return {
+				slug: review.slug,
+				branch: review.branch,
+				variant: review.variant,
+				status: review.status,
+				findings: snapshot.findings.length,
+				bySeverity: snapshot.bySeverity,
+				updatedAt: review.updatedAt,
+			};
+		});
+}

package/src/core/commands/context.ts

@@ -12,7 +12,7 @@ import {
 	type PrContextRaw,
 	renderContextBrief,
 } from "../pr-context";
-import { sanitizeBranch } from "../report-builder";
+import { reviewSlug } from "../report-builder";
 import type { RepoIdentity, StorageProvider } from "../storage/types";
 import { type ContextPaths, ReviewWorkArea } from "../storage/work-area";
 
@@ -28,6 +28,8 @@ export function runContextCommand(
 	repo: RepoIdentity,
 	opts: {
 		branch?: string;
+		/** Variante A/B da run (ausente = principal). */
+		variant?: string;
 		/** Worktree onde a review roda (persistido na review). */
 		worktreePath?: string;
 		/** PR de origem (persistida na review). */
@@ -35,10 +37,12 @@ export function runContextCommand(
 	} = {},
 ): ContextRunResult {
 	const branch = opts.branch ?? currentBranch();
+	const variant = opts.variant?.trim() || undefined;
 	const review = storage.getOrCreateReview({
 		repo,
 		branch,
-		slug: sanitizeBranch(branch),
+		variant,
+		slug: reviewSlug(branch, variant),
 		worktreePath: opts.worktreePath,
 		prNumber: opts.prNumber,
 	});

package/src/core/commands/findings.ts

@@ -14,6 +14,7 @@ import { existsSync } from "node:fs";
 import { AiClient } from "../ai/ai-client";
 import { AiVerifier } from "../ai/features/verifier";
 import { type HoundsmanConfig, resolveJevConcurrency } from "../config";
+import { type ReviewContext, reviewContext } from "../engine/review-context";
 import { ENV_NAMES } from "../env";
 import {
 	applyFindingUpdate,
@@ -25,7 +26,6 @@ import {
 	type FindingsFilter,
 	type FindingsStateFile,
 	type FindingUpdate,
-	fileReader,
 	filterFindings,
 	reorder,
 	resolveFindingId,
@@ -51,9 +51,9 @@ import { VerifyPresenter } from "../renderers/verify-presenter";
 import { pingFindingsStatus } from "../run-status";
 import { systemClock } from "../services/clock";
 import { FixBatchBuilder } from "../services/fix-batch-builder";
+import type { GitRepository } from "../services/git-repository";
 import { Verifier } from "../services/verifier";
-import type { RepoIdentity, ReviewRecord, StorageProvider } from "../storage/types";
-import { ReviewWorkArea } from "../storage/work-area";
+import type { RepoIdentity, StorageProvider } from "../storage/types";
 import { SEVERITY_ORDER, type Severity } from "../types";
 
 export type FindingsCommandResult = {
@@ -68,6 +68,7 @@ const VALUE_FLAGS = new Set([
 	"--severity",
 	"--file",
 	"--branch",
+	"--variant",
 	"--limit",
 	"--comment",
 	"--by",
@@ -108,13 +109,11 @@ function parseArgs(args: string[]): ParsedArgs {
 	return parsed;
 }
 
-/** Contexto de uma review (storage + registro + staging + raiz). */
-type CommandContext = {
-	storage: StorageProvider;
-	review: ReviewRecord;
-	work: ReviewWorkArea;
-	/** Worktree da review quando existir; senão, a raiz do repositório. */
-	root: string;
+/** Opções de resolução do contexto (o CLI passa root/git do engine). */
+export type FindingsContextOptions = {
+	/** Raiz operacional (default: cwd de quem chamou). */
+	root?: string;
+	git?: GitRepository;
 };
 
 /** Resolve a review da branch atual (explícita ou via git). */
@@ -122,22 +121,25 @@ function openContext(
 	storage: StorageProvider,
 	repo: RepoIdentity,
 	parsed: ParsedArgs,
-): CommandContext {
+	options: FindingsContextOptions = {},
+): ReviewContext {
 	const branch = parsed.values["--branch"] ?? currentBranch();
-	const review = storage.findReview(repo.key, branch);
+	const variant = parsed.values["--variant"]?.trim() || undefined;
+	const review = storage.findReview(repo.key, branch, variant);
 	if (!review) {
 		throw new Error(
-			`Nenhuma revisão para '${branch}'. Rode \`houndsman --finalize\` primeiro.`,
+			`Nenhuma revisão para '${branch}'${variant ? ` (variante '${variant}')` : ""}. Rode \`houndsman --finalize\` primeiro.`,
 		);
 	}
 	const worktree = review.worktreePath;
 	// Sem worktree, mantém a raiz onde o comando foi invocado (comportamento histórico).
-	const root = worktree && existsSync(worktree) ? worktree : process.cwd();
-	return { storage, review, work: new ReviewWorkArea(review), root };
+	const root =
+		worktree && existsSync(worktree) ? worktree : (options.root ?? process.cwd());
+	return reviewContext(storage, review, { root, git: options.git });
 }
 
 /** Lê o estado de triagem; lança se a review ainda não tem findings. */
-function loadState(ctx: CommandContext): FindingsStateFile {
+function loadState(ctx: ReviewContext): FindingsStateFile {
 	const state = ctx.storage.readFindings(ctx.review.id);
 	if (!state) {
 		throw new Error(
@@ -149,7 +151,7 @@ function loadState(ctx: CommandContext): FindingsStateFile {
 
 /** Lê-modifica-grava o estado, atualizando `updatedAt` e a ordem. */
 function mutateState(
-	ctx: CommandContext,
+	ctx: ReviewContext,
 	mutator: (state: FindingsStateFile) => void,
 ): FindingsStateFile {
 	const state = loadState(ctx);
@@ -221,7 +223,7 @@ function filterFrom(parsed: ParsedArgs): FindingsFilter {
 }
 
 /** Faz ping no status da review (derivado do estado atual) após uma mutação. */
-function pingStatus(ctx: CommandContext, state: FindingsStateFile): void {
+function pingStatus(ctx: ReviewContext, state: FindingsStateFile): void {
 	pingFindingsStatus(ctx.storage, ctx.review.id, state);
 }
 
@@ -230,7 +232,7 @@ function pingStatus(ctx: CommandContext, state: FindingsStateFile): void {
  * 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 {
+function syncThreadsOutput(ctx: ReviewContext, ids: readonly string[]): string | null {
 	if (ids.length === 0) return null;
 	const state = loadState(ctx);
 	const outcome = syncResolvedThreads({ state, ids });
@@ -246,7 +248,7 @@ function syncThreadsOutput(ctx: CommandContext, ids: readonly string[]): string
 
 /** Aplica uma atualização a um finding e persiste. */
 function updateOne(
-	ctx: CommandContext,
+	ctx: ReviewContext,
 	input: string,
 	update: FindingUpdate,
 ): FindingState {
@@ -261,7 +263,7 @@ function updateOne(
 
 /** Aplica a mesma atualização a vários ids (done/reset). */
 function updateMany(
-	ctx: CommandContext,
+	ctx: ReviewContext,
 	inputs: string[],
 	update: FindingUpdate,
 ): FindingState[] {
@@ -281,10 +283,11 @@ export function runFindingsCommand(
 	storage: StorageProvider,
 	repo: RepoIdentity,
 	args: string[],
+	options: FindingsContextOptions = {},
 ): FindingsCommandResult {
 	try {
 		const parsed = parseArgs(args);
-		return execute(config, storage, repo, parsed);
+		return execute(config, storage, repo, parsed, options);
 	} catch (error) {
 		return {
 			output: error instanceof Error ? error.message : String(error),
@@ -298,8 +301,9 @@ function execute(
 	storage: StorageProvider,
 	repo: RepoIdentity,
 	parsed: ParsedArgs,
+	options: FindingsContextOptions,
 ): FindingsCommandResult {
-	const ctx = openContext(storage, repo, parsed);
+	const ctx = openContext(storage, repo, parsed, options);
 	switch (parsed.sub ?? "list") {
 		case "list": {
 			const state = loadState(ctx);
@@ -386,7 +390,7 @@ function execute(
 		}
 		case "sync": {
 			const state = loadState(ctx);
-			const result = syncState(state, fileReader(ctx.root));
+			const result = syncState(state, ctx.files.reader());
 			ctx.storage.writeFindings(ctx.review.id, state);
 			pingStatus(ctx, state);
 			const output = parsed.bools.has("--json")
@@ -483,10 +487,11 @@ export async function runVerifyCommand(
 	storage: StorageProvider,
 	repo: RepoIdentity,
 	args: string[],
+	options: FindingsContextOptions = {},
 ): Promise<FindingsCommandResult> {
 	try {
 		const parsed = parseArgs(args);
-		return await executeVerify(config, storage, repo, parsed);
+		return await executeVerify(config, storage, repo, parsed, options);
 	} catch (error) {
 		return {
 			output: error instanceof Error ? error.message : String(error),
@@ -514,8 +519,9 @@ async function executeVerify(
 	storage: StorageProvider,
 	repo: RepoIdentity,
 	parsed: ParsedArgs,
+	options: FindingsContextOptions,
 ): Promise<FindingsCommandResult> {
-	const ctx = openContext(storage, repo, parsed);
+	const ctx = openContext(storage, repo, parsed, options);
 	const state = loadState(ctx);
 
 	// Lazy: `../jev` (axios) só entra no caminho do verify.
@@ -523,7 +529,7 @@ async function executeVerify(
 	const { JevCandidatesStore, JevClient, JevVerifier } = await import("../jev");
 
 	const findings = verifier.select(state, filterFrom(parsed));
-	const entries = verifier.verifyLocal(findings, fileReader(ctx.root));
+	const entries = verifier.verifyLocal(findings, ctx.files.reader());
 
 	// Tier 1 — Jev só nos ambíguos (fail-open: sem chave/erro mantém o provisório).
 	let jevChecked = 0;
@@ -571,7 +577,7 @@ async function executeVerify(
 		} else if (!aiVerifier.enabled) {
 			aiReason = "feature ai.features.verify desligada";
 		} else {
-			const readFile = fileReader(ctx.root);
+			const readFile = ctx.files.reader();
 			const byId = new Map(findings.map((finding) => [finding.id, finding]));
 			const confidence = await aiVerifier.verify({
 				findings: stillAmbiguous.map((entry) => ({
@@ -748,10 +754,11 @@ export async function runSubmitCommand(
 	storage: StorageProvider,
 	repo: RepoIdentity,
 	args: string[],
+	options: FindingsContextOptions = {},
 ): Promise<FindingsCommandResult> {
 	try {
 		const parsed = parseArgs(args);
-		return await executeSubmit(config, storage, repo, parsed);
+		return await executeSubmit(config, storage, repo, parsed, options);
 	} catch (error) {
 		return {
 			output: error instanceof Error ? error.message : String(error),
@@ -765,8 +772,9 @@ async function executeSubmit(
 	storage: StorageProvider,
 	repo: RepoIdentity,
 	parsed: ParsedArgs,
+	options: FindingsContextOptions,
 ): Promise<FindingsCommandResult> {
-	const ctx = openContext(storage, repo, parsed);
+	const ctx = openContext(storage, repo, parsed, options);
 	const state = loadState(ctx);
 	const selection = submitSelection(parsed);
 	const target = resolvePrTarget(defaultGhRunner, state.branch);

package/src/core/commands/review.ts

@@ -22,10 +22,16 @@ export function parseReviewArgs(args: string[]): ReviewOptions {
 	const branch = parser.value("--branch");
 	const pr = parser.value("--pr");
 	const worktree = parser.value("--worktree");
+	const variant = parser.value("--variant");
 	if (base) opts.base = base;
 	if (head) opts.head = head;
 	if (branch) opts.branch = branch;
 	if (worktree) opts.worktree = worktree;
+	if (variant !== undefined) {
+		const label = variant.trim();
+		if (!label) throw new Error("--variant não pode ser vazio.");
+		opts.variant = label;
+	}
 	if (pr) {
 		const number = Number.parseInt(pr, 10);
 		if (!Number.isFinite(number) || number <= 0) {

package/src/core/commands/scaffold.ts

@@ -98,6 +98,15 @@ export const houndsmanConfig = {
 	watchdogs: WATCHDOG_DEFINITIONS,
 	exclusions: EXCLUSION_PATTERNS,
 	docMappings: DOC_MAPPINGS,
+	// Prioridade por caminho (opcional): "linhas de churn equivalentes".
+	// \`bonus\` promove caminho crítico; \`maxRiskFromChurn\` satura o superchurn de
+	// caminho de baixa criticidade (risco = min(churn, teto) + bonus).
+	// A primeira regra que casar vence; sem regra, o risco é o churn puro.
+	// priorities: [
+	//   { pattern: /^src\\/(db|repositories)\\//, bonus: 300 },
+	//   { pattern: /^src\\/(services|domain)\\//, bonus: 200 },
+	//   { pattern: /^src\\/(components|styles)\\//, maxRiskFromChurn: 120 },
+	// ],
 } satisfies HoundsmanConfig;
 
 export default houndsmanConfig;
@@ -215,6 +224,7 @@ export type AiProviderOptions = Record<string, Record<string, unknown>>;
 /** Features de IA do fluxo normal (todas fail-open). */
 export type HoundsmanAiFeatures = {
 	context?: boolean;
+	business?: boolean;
 	brief?: boolean;
 	technical?: boolean;
 	classification?: boolean;
@@ -252,6 +262,18 @@ export type HoundsmanHunt = {
 	binaryPath?: string;
 };
 
+/**
+ * Prioridade por caminho.
+ *
+ * \`bonus\` promove (linhas de churn equivalentes) e \`maxRiskFromChurn\` satura o
+ * superchurn de caminhos de baixa criticidade.
+ */
+export type HoundsmanPriority = {
+	pattern: RegExp;
+	bonus?: number;
+	maxRiskFromChurn?: number;
+};
+
 /** Contrato de configuração do motor. */
 export type HoundsmanConfig<TId extends string = string> = {
 	projectName: string;
@@ -260,6 +282,8 @@ export type HoundsmanConfig<TId extends string = string> = {
 	watchdogs: Record<TId, WatchdogDefinition>;
 	exclusions: readonly RegExp[];
 	docMappings: readonly (readonly [RegExp, readonly string[]])[];
+	/** Prioridade por caminho (opcional; a primeira regra que casar vence). */
+	priorities?: readonly HoundsmanPriority[];
 	alwaysIncludeDocs?: readonly string[];
 	budgets?: HoundsmanBudgets;
 	concurrency?: HoundsmanConcurrency;
@@ -365,6 +389,9 @@ import { exampleWatchdog } from "./example";
 /**
  * Definições dos watchdogs — as chaves definem o union \`WatchdogId\`.
  * Adicionar um watchdog = criar \`<id>.ts\` e registrá-lo aqui.
+ *
+ * NÃO declare um watchdog com id \`general\`: ele é reservado pelo motor
+ * (revisor de fluxo obrigatório) e é injetado em todo ciclo.
  */
 export const WATCHDOG_DEFINITIONS = {
 	default: defaultWatchdog,

package/src/core/commands/status.ts

@@ -33,11 +33,14 @@ function findReview(
 	storage: StorageProvider,
 	repo: RepoIdentity,
 	branch?: string,
+	variant?: string,
 ): ReviewRecord {
 	const target = branch ?? currentBranch();
-	const review = storage.findReview(repo.key, target);
+	const review = storage.findReview(repo.key, target, variant);
 	if (!review) {
-		throw new Error(`Nenhuma revisão para '${target}'.`);
+		throw new Error(
+			`Nenhuma revisão para '${target}'${variant ? ` (variante '${variant}')` : ""}.`,
+		);
 	}
 	return review;
 }
@@ -47,8 +50,9 @@ export function readStatus(
 	storage: StorageProvider,
 	repo: RepoIdentity,
 	branch?: string,
+	variant?: string,
 ): StatusResult {
-	return toResult(findReview(storage, repo, branch));
+	return toResult(findReview(storage, repo, branch, variant));
 }
 
 /** Renova o heartbeat de uma execução ativa (`reviewing`/`fixing`). */
@@ -56,8 +60,9 @@ export function pingStatus(
 	storage: StorageProvider,
 	repo: RepoIdentity,
 	branch?: string,
+	variant?: string,
 	now?: string,
 ): StatusResult {
-	const review = findReview(storage, repo, branch);
+	const review = findReview(storage, repo, branch, variant);
 	return toResult(touchRunStatus(storage, review.id, now));
 }