@payconductor/houndsman 0.13.0 → 0.14.0

package/src/core/compare.ts

@@ -0,0 +1,243 @@
+/**
+ * Comparação A/B de duas revisões da mesma branch (funções puras).
+ *
+ * O objetivo é responder "o que mudou entre as duas execuções?" sem tentar
+ * eleger um vencedor: conta achados por severidade, cobertura, tempo e tokens,
+ * e lista o que apareceu/sumiu entre A e B.
+ */
+
+import { SEVERITY_ORDER, type Severity } from "./types";
+
+/** Finding normalizado para a comparação. */
+export type ComparisonFinding = {
+	fingerprint: string;
+	rule: string;
+	severity: Severity;
+	file: string;
+	line?: number;
+	message: string;
+	watchdogs: readonly string[];
+};
+
+/** Snapshot de uma execução (uma das pontas do A/B). */
+export type ReviewSnapshot = {
+	/** Rótulo exibido (`A`, `B` ou a variante). */
+	label: string;
+	slug: string;
+	branch: string;
+	variant?: string;
+	headSha?: string;
+	model?: string;
+	/** Achados presentes no último relatório. */
+	findings: readonly ComparisonFinding[];
+	bySeverity: Record<Severity, number>;
+	coverage: { watchdogs: number; files: number; overflow: number };
+	/** Duração do ciclo (`startedAt` → `reviewedAt`), quando medida. */
+	durationMs?: number;
+	/** Duração do prepare (`prepare-report.json`). */
+	prepareMs?: number;
+	/** Duração do harness maki (`hunt-report.json`). */
+	huntMs?: number;
+	tokens?: number;
+	costUsd?: number;
+};
+
+/** Resultado da comparação. */
+export type ReviewComparison = {
+	branch: string;
+	headSha?: string;
+	a: ReviewSnapshot;
+	b: ReviewSnapshot;
+	onlyA: readonly ComparisonFinding[];
+	onlyB: readonly ComparisonFinding[];
+	common: readonly { a: ComparisonFinding; b: ComparisonFinding }[];
+	severityChanged: readonly { a: ComparisonFinding; b: ComparisonFinding }[];
+};
+
+/** Conta os achados por severidade. */
+export function countBySeverity(
+	findings: readonly ComparisonFinding[],
+): Record<Severity, number> {
+	const counts: Record<Severity, number> = {
+		blocking: 0,
+		attention: 0,
+		suggestion: 0,
+		nit: 0,
+	};
+	for (const finding of findings) counts[finding.severity]++;
+	return counts;
+}
+
+/** Compara dois snapshots (ordem estável por severidade e caminho). */
+export function buildComparison(a: ReviewSnapshot, b: ReviewSnapshot): ReviewComparison {
+	const aByKey = new Map(a.findings.map((finding) => [finding.fingerprint, finding]));
+	const bByKey = new Map(b.findings.map((finding) => [finding.fingerprint, finding]));
+	const onlyA = a.findings.filter((finding) => !bByKey.has(finding.fingerprint));
+	const onlyB = b.findings.filter((finding) => !aByKey.has(finding.fingerprint));
+	const common: { a: ComparisonFinding; b: ComparisonFinding }[] = [];
+	const severityChanged: { a: ComparisonFinding; b: ComparisonFinding }[] = [];
+
+	for (const finding of a.findings) {
+		const other = bByKey.get(finding.fingerprint);
+		if (!other) continue;
+		common.push({ a: finding, b: other });
+		if (finding.severity !== other.severity) {
+			severityChanged.push({ a: finding, b: other });
+		}
+	}
+
+	const sortFindings = (items: ComparisonFinding[]): ComparisonFinding[] =>
+		[...items].sort(
+			(x, y) =>
+				SEVERITY_ORDER.indexOf(x.severity) - SEVERITY_ORDER.indexOf(y.severity) ||
+				x.file.localeCompare(y.file) ||
+				(x.line ?? 0) - (y.line ?? 0) ||
+				x.rule.localeCompare(y.rule),
+		);
+
+	return {
+		branch: a.branch,
+		headSha: a.headSha ?? b.headSha,
+		a,
+		b,
+		onlyA: sortFindings(onlyA),
+		onlyB: sortFindings(onlyB),
+		common,
+		severityChanged: severityChanged.sort(
+			(x, y) =>
+				SEVERITY_ORDER.indexOf(x.a.severity) -
+					SEVERITY_ORDER.indexOf(y.a.severity) ||
+				x.a.file.localeCompare(y.a.file),
+		),
+	};
+}
+
+/** Duração legível (`820ms`, `12.3s`, `2m05s`). */
+function formatMs(ms: number | undefined): string {
+	if (ms === undefined || !Number.isFinite(ms)) return "—";
+	const safe = Math.max(0, Math.round(ms));
+	if (safe < 1_000) return `${safe}ms`;
+	const seconds = safe / 1_000;
+	if (seconds < 60) return `${seconds.toFixed(1)}s`;
+	const minutes = Math.floor(seconds / 60);
+	return `${minutes}m${String(Math.round(seconds % 60)).padStart(2, "0")}s`;
+}
+
+function formatDelta(
+	a: number | undefined,
+	b: number | undefined,
+	format: (value: number) => string,
+): string {
+	if (a === undefined || b === undefined) return "—";
+	const delta = b - a;
+	return `${delta > 0 ? "+" : ""}${format(delta)}`;
+}
+
+/** Linha da tabela de métricas. */
+function metricRow(label: string, a: string, b: string, delta = "—"): string {
+	return `| ${label} | ${a} | ${b} | ${delta} |`;
+}
+
+/** Lista compacta de um conjunto de achados. */
+function findingList(title: string, findings: readonly ComparisonFinding[]): string[] {
+	if (findings.length === 0) return [`## ${title}`, "", "_Nenhum._", ""];
+	const shown = findings.slice(0, 20);
+	const lines = [`## ${title} (${findings.length})`, ""];
+	for (const finding of shown) {
+		const line = finding.line !== undefined ? `:${finding.line}` : "";
+		lines.push(
+			`- **${finding.severity}** · \`${finding.file}${line}\` — ${finding.message}`,
+		);
+	}
+	if (findings.length > shown.length) {
+		lines.push(`- … +${findings.length - shown.length} achado(s)`);
+	}
+	lines.push("");
+	return lines;
+}
+
+/** Renderiza a comparação em Markdown (artefato e stdout). */
+export function renderComparison(comparison: ReviewComparison): string {
+	const { a, b } = comparison;
+	const severityDelta = SEVERITY_ORDER.map((severity) =>
+		metricRow(
+			severity,
+			String(a.bySeverity[severity]),
+			String(b.bySeverity[severity]),
+			formatDelta(a.bySeverity[severity], b.bySeverity[severity], (value) =>
+				String(value),
+			),
+		),
+	);
+	const totalA = a.findings.length;
+	const totalB = b.findings.length;
+	const lines = [
+		`# Comparação A/B — \`${comparison.branch}\``,
+		"",
+		`**A:** ${labelOf(a)} · **B:** ${labelOf(b)}`,
+		...(comparison.headSha
+			? [`**Commit:** \`${comparison.headSha.slice(0, 7)}\``]
+			: []),
+		"",
+		"> Compara o que apareceu/sumiu entre as execuções. Não é veredito: confirme",
+		"> cada achado novo no código antes de considerá-lo ganho ou perda.",
+		"",
+		"## Métricas",
+		"",
+		`| Métrica | A | B | Δ |`,
+		`| --- | --- | --- | --- |`,
+		metricRow(
+			"Findings (presentes)",
+			String(totalA),
+			String(totalB),
+			formatDelta(totalA, totalB, (value) => String(value)),
+		),
+		...severityDelta,
+		metricRow(
+			"Cobertura (arquivos)",
+			String(a.coverage.files),
+			String(b.coverage.files),
+		),
+		metricRow(
+			"Watchdogs",
+			String(a.coverage.watchdogs),
+			String(b.coverage.watchdogs),
+		),
+		metricRow("Duração total", formatMs(a.durationMs), formatMs(b.durationMs)),
+		metricRow("Prepare", formatMs(a.prepareMs), formatMs(b.prepareMs)),
+		metricRow("Harness", formatMs(a.huntMs), formatMs(b.huntMs)),
+		metricRow(
+			"Tokens",
+			a.tokens !== undefined ? String(a.tokens) : "—",
+			b.tokens !== undefined ? String(b.tokens) : "—",
+		),
+		metricRow(
+			"Custo",
+			a.costUsd !== undefined ? `$${a.costUsd.toFixed(4)}` : "—",
+			b.costUsd !== undefined ? `$${b.costUsd.toFixed(4)}` : "—",
+		),
+		"",
+		...findingList("Só em B (novos)", comparison.onlyB),
+		...findingList("Só em A (não apareceram em B)", comparison.onlyA),
+	];
+	if (comparison.severityChanged.length > 0) {
+		lines.push(`## Severidade mudou (${comparison.severityChanged.length})`, "");
+		for (const item of comparison.severityChanged.slice(0, 20)) {
+			lines.push(
+				`- \`${item.a.file}\` — ${item.a.rule}: **${item.a.severity} → ${item.b.severity}**`,
+			);
+		}
+		lines.push("");
+	}
+	return `${lines.join("\n").trimEnd()}\n`;
+}
+
+/** JSON estável da comparação (artefato para automação). */
+export function comparisonToJson(comparison: ReviewComparison): string {
+	return `${JSON.stringify(comparison, null, 2)}\n`;
+}
+
+function labelOf(snapshot: ReviewSnapshot): string {
+	const variant = snapshot.variant ? ` (variante \`${snapshot.variant}\`)` : "";
+	return `\`${snapshot.slug}\`${variant} · ${snapshot.findings.length} finding(s)`;
+}

package/src/core/concurrency.ts

@@ -0,0 +1,30 @@
+/**
+ * Pool de concorrência mínimo (biblioteca).
+ *
+ * Mantém no máximo `limit` promessas ativas e preserva a ordem dos resultados.
+ * Não trata erros: o chamador decide se cada item falha isoladamente.
+ */
+
+/** Executa `mapper` para cada item com concorrência limitada. */
+export async function mapPool<T, R>(
+	items: readonly T[],
+	limit: number,
+	mapper: (item: T, index: number) => Promise<R>,
+): Promise<R[]> {
+	const results = new Array<R>(items.length);
+	if (items.length === 0) return results;
+
+	let next = 0;
+	const workers = Array.from(
+		{ length: Math.max(1, Math.min(limit, items.length)) },
+		async () => {
+			while (true) {
+				const index = next++;
+				if (index >= items.length) return;
+				results[index] = await mapper(items[index], index);
+			}
+		},
+	);
+	await Promise.all(workers);
+	return results;
+}

package/src/core/config.ts

@@ -72,6 +72,8 @@ export type AiProviderOptions = Record<string, Record<string, unknown>>;
 export type HoundsmanAiFeatures = {
 	/** Resume o contexto da PR (`context-summary`) quando o subagente não gerou. */
 	context?: boolean;
+	/** Reconstrói a intenção da PR (`business-summary`) antes dos watchdogs. */
+	business?: boolean;
 	/** Enriquece os briefs com um plano de revisão sugerido. */
 	brief?: boolean;
 	/** Gera os pontos técnicos estruturais do resumo final. */
@@ -99,7 +101,7 @@ export type HoundsmanAi = {
 	model?: string;
 	/** Base URL customizada do provider. */
 	baseURL?: string;
-	/** Chamadas simultâneas (default: 2). */
+	/** Chamadas simultâneas (default: 4). */
 	concurrency?: number;
 	/** Opções do AI SDK por provider (repassadas sem interpretação). */
 	providerOptions?: AiProviderOptions;
@@ -130,7 +132,7 @@ export type HoundsmanWorktrees = {
  * Harness local da capability `hunt` (`houndsman hunt`) — opcional.
  *
  * Sem esta config, o comando usa defaults seguros: modelo derivado de `ai`,
- * 4 processos simultâneos e timeout de 15 min por watchdog. A skill
+ * 8 processos simultâneos (uma onda) e timeout de 15 min por watchdog. A skill
  * `/houndsman hunt` (harness externo) não depende deste bloco.
  */
 export type HoundsmanHunt = {
@@ -138,7 +140,7 @@ export type HoundsmanHunt = {
 	enabled?: boolean;
 	/** Modelo no formato do maki (`provider/model-id`). Default: derivado de `ai`. */
 	model?: string;
-	/** Processos maki simultâneos (default: 4). */
+	/** Processos maki simultâneos (default: 8). */
 	concurrency?: number;
 	/** Timeout por watchdog em ms (default: 900_000). */
 	timeoutMs?: number;
@@ -162,6 +164,27 @@ export type HoundsmanStorage = {
 	path?: string;
 };
 
+/**
+ * Regra de prioridade por caminho (ordenada; a primeira que casar vence).
+ *
+ * O risco do arquivo é `min(churn, maxRiskFromChurn) + bonus`. O `bonus` promove
+ * caminhos críticos (em linhas de churn equivalentes) e o `maxRiskFromChurn`
+ * satura o superchurn de caminhos de baixa criticidade: um frontend que
+ * reformatou 2.000 linhas não escala além do teto, mas um ajuste pequeno no
+ * mesmo caminho mantém o peso natural.
+ */
+export type HoundsmanPriority = {
+	/** Padrão sobre o caminho relativo (ex.: `/^server\\/src\\/db\\//`). */
+	pattern: RegExp;
+	/** Peso em linhas de churn equivalentes (≥ 0; default: 0). */
+	bonus?: number;
+	/**
+	 * Teto do churn considerado no risco (em linhas equivalentes). Acima dele os
+	 * arquivos do caminho empatam e só o `bonus` diferencia. Default: sem teto.
+	 */
+	maxRiskFromChurn?: number;
+};
+
 /**
  * Configuração completa do motor de revisão para um projeto.
  *
@@ -185,6 +208,11 @@ export type HoundsmanConfig<TId extends string = string> = {
 	exclusions: readonly RegExp[];
 	/** Mapeamentos path → documentação relevante. */
 	docMappings: readonly (readonly [RegExp, readonly string[]])[];
+	/**
+	 * Prioridade por caminho (opcional). Ordena arquivos no orçamento, no rateio
+	 * do diff e no recorte do `general` — a primeira regra que casar vence.
+	 */
+	priorities?: readonly HoundsmanPriority[];
 	/** Docs sempre incluídos nos briefs (default: `DEFAULT_ALWAYS_INCLUDE_DOCS`). */
 	alwaysIncludeDocs?: readonly string[];
 	/** Limites de triage para PRs grandes (default: `DEFAULT_MAX_FILES_PER_BRIEF`). */

package/src/core/defaults.ts

@@ -38,8 +38,13 @@ export const DEFAULT_AI_PROVIDER = "deepseek" as const;
 /** Modelo default da camada de IA. */
 export const DEFAULT_AI_MODEL = "deepseek-v4-pro";
 
-/** Concorrência default das chamadas de IA. */
-export const DEFAULT_AI_CONCURRENCY = 2;
+/**
+ * Concorrência default das chamadas de IA do prepare.
+ *
+ * Vale principalmente para os planos de brief (1 chamada por watchdog): com 4,
+ * 8 watchdogs fecham em 2 rodadas em vez de 4.
+ */
+export const DEFAULT_AI_CONCURRENCY = 4;
 
 /** Timeout default de uma chamada de modelo (ms). */
 export const DEFAULT_AI_TIMEOUT_MS = 120_000;
@@ -47,12 +52,53 @@ export const DEFAULT_AI_TIMEOUT_MS = 120_000;
 /** Teto default de chamadas de IA por review. */
 export const DEFAULT_AI_MAX_CALLS_PER_REVIEW = 40;
 
-/** Processos maki simultâneos no harness local (`houndsman hunt`). */
-export const DEFAULT_HUNT_CONCURRENCY = 4;
+/**
+ * Processos maki simultâneos no harness local (`houndsman hunt`).
+ *
+ * 8 = uma onda para os watchdogs usuais (domínios + `general`), em vez de 2.
+ */
+export const DEFAULT_HUNT_CONCURRENCY = 8;
 
 /** Timeout default de um watchdog no harness local (15 min). */
 export const DEFAULT_HUNT_TIMEOUT_MS = 900_000;
 
+/**
+ * Trechos alterados injetados no brief (watchdog de domínio).
+ *
+ * Substituem a leitura do arquivo inteiro: o subagente começa pelo diff e só
+ * abre o arquivo para contexto adjacente. O orçamento é distribuído entre os
+ * arquivos (metade em partes iguais, o resto por churn) — antes, os primeiros
+ * arquivos consumiam o teto e o subagente lia os demais à mão.
+ */
+export const DEFAULT_BRIEF_SNIPPET_CHARS = 24_000;
+export const DEFAULT_BRIEF_SNIPPET_CHARS_PER_FILE = 4_000;
+
+/** Mesmos limites para o revisor de fluxo (`general`), que vê todos os arquivos. */
+export const GENERAL_BRIEF_SNIPPET_CHARS = 32_000;
+export const GENERAL_BRIEF_SNIPPET_CHARS_PER_FILE = 5_000;
+
+/** Fração do teto dividida igualmente entre os arquivos (o resto vai por churn). */
+export const BRIEF_SNIPPET_FLOOR_RATIO = 0.5;
+
+/** Piso de chars por arquivo no rateio igual (evita trechos inúteis). */
+export const BRIEF_SNIPPET_MIN_PER_FILE = 120;
+
+/**
+ * A partir daqui o `general` revisa por **fluxo** em vez de amostrar arquivos.
+ *
+ * Em PRs grandes, 40 arquivos com ~800 chars cada viram amostragem: melhor ver
+ * os arquivos que participam dos fluxos do modelo de intenção (com diff de
+ * verdade) e declarar o resto em `skipped`.
+ */
+export const GENERAL_FLOW_MIN_FILES = 40;
+export const GENERAL_FLOW_MIN_LINES = 2_000;
+
+/** Arquivos do recorte de fluxo do `general`. */
+export const GENERAL_FLOW_MAX_FILES = 15;
+
+/** Diff por arquivo no recorte de fluxo — profundidade em vez de cobertura. */
+export const GENERAL_FLOW_SNIPPET_CHARS_PER_FILE = 2_000;
+
 /** Retentativas default quando a saída do watchdog é inválida. */
 export const DEFAULT_HUNT_RETRIES = 1;
 

package/src/core/domain/budget.ts

@@ -5,6 +5,7 @@
  * orçamento sem depender do serviço de classificação.
  */
 
+import type { HoundsmanPriority } from "../config";
 import type { ChurnMap } from "../types";
 
 /** Churn total (adições + remoções) de um arquivo; 0 quando ausente. */
@@ -13,10 +14,66 @@ export function churnOf(filePath: string, churn: ChurnMap | undefined): number {
 	return entry ? entry.additions + entry.deletions : 0;
 }
 
-/** Ordena os arquivos por risco (churn desc; empate pelo caminho). */
-export function sortByRisk(files: readonly string[], churn?: ChurnMap): string[] {
+/** Regra de prioridade do caminho (a primeira que casar vence). */
+export function priorityFor(
+	filePath: string,
+	priorities: readonly HoundsmanPriority[] | undefined,
+): HoundsmanPriority | undefined {
+	for (const rule of priorities ?? []) {
+		// Regex global mantém `lastIndex` entre chamadas — zera para não pular match.
+		if (rule.pattern.global) rule.pattern.lastIndex = 0;
+		if (rule.pattern.test(filePath)) return rule;
+	}
+	return undefined;
+}
+
+/** Bônus da regra (linhas de churn equivalentes; ausente/inválido = 0). */
+function bonusOf(rule: HoundsmanPriority | undefined): number {
+	const bonus = rule?.bonus;
+	return bonus !== undefined && Number.isFinite(bonus) ? Math.max(0, bonus) : 0;
+}
+
+/** Bônus de prioridade do caminho (primeira regra que casar vence). */
+export function priorityBonus(
+	filePath: string,
+	priorities: readonly HoundsmanPriority[] | undefined,
+): number {
+	return bonusOf(priorityFor(filePath, priorities));
+}
+
+/** Teto de churn da regra (ausente/inválido = sem teto). */
+function churnLimitOf(rule: HoundsmanPriority | undefined): number {
+	const limit = rule?.maxRiskFromChurn;
+	return limit !== undefined && Number.isFinite(limit) && limit > 0
+		? limit
+		: Number.POSITIVE_INFINITY;
+}
+
+/**
+ * Risco do arquivo: `min(churn, maxRiskFromChurn) + bonus`.
+ *
+ * O teto existe para superchurn de caminho de baixa criticidade (frontend que
+ * reformatou uma tabela inteira) não competir com churn real de caminho crítico;
+ * abaixo do teto, o peso do caminho é o churn natural.
+ */
+export function riskOf(
+	filePath: string,
+	churn: ChurnMap | undefined,
+	priorities?: readonly HoundsmanPriority[],
+): number {
+	const rule = priorityFor(filePath, priorities);
+	const churnRisk = Math.min(churnOf(filePath, churn), churnLimitOf(rule));
+	return churnRisk + bonusOf(rule);
+}
+
+/** Ordena os arquivos por risco (churn + prioridade; empate pelo caminho). */
+export function sortByRisk(
+	files: readonly string[],
+	churn?: ChurnMap,
+	priorities?: readonly HoundsmanPriority[],
+): string[] {
 	return [...files].sort((a, b) => {
-		const delta = churnOf(b, churn) - churnOf(a, churn);
+		const delta = riskOf(b, churn, priorities) - riskOf(a, churn, priorities);
 		return delta !== 0 ? delta : a.localeCompare(b);
 	});
 }
@@ -33,8 +90,9 @@ export function selectByBudget(
 	files: readonly string[],
 	churn: ChurnMap | undefined,
 	maxFiles: number,
+	priorities?: readonly HoundsmanPriority[],
 ): BudgetSelection {
-	const ordered = sortByRisk(files, churn);
+	const ordered = sortByRisk(files, churn, priorities);
 	if (!Number.isFinite(maxFiles) || maxFiles <= 0 || ordered.length <= maxFiles) {
 		return { selected: ordered, overflow: [] };
 	}

package/src/core/domain/classification.ts

@@ -5,6 +5,7 @@
  * consultas usadas pelo orquestrador (arquivos por watchdog, orçamento, churn).
  */
 
+import type { HoundsmanPriority } from "../config";
 import type { ClassificationResult } from "../file-classifier";
 import type { ChurnMap } from "../types";
 import { type BudgetSelection, selectByBudget } from "./budget";
@@ -72,8 +73,17 @@ export class Classification {
 	}
 
 	/** Aplica o orçamento aos arquivos de um watchdog. */
-	budgetFor(id: string, maxFiles: number): BudgetSelection {
-		return selectByBudget(this.watchdogsFor(id), this.data.churn, maxFiles);
+	budgetFor(
+		id: string,
+		maxFiles: number,
+		priorities?: readonly HoundsmanPriority[],
+	): BudgetSelection {
+		return selectByBudget(
+			this.watchdogsFor(id),
+			this.data.churn,
+			maxFiles,
+			priorities,
+		);
 	}
 
 	/** Totais de churn do diff. */

package/src/core/engine/carryover.ts

@@ -34,6 +34,10 @@ export function buildCarryover(
 			message: finding.message,
 			action: finding.action,
 			evidence: finding.evidence,
+			scenario: finding.scenario,
+			impact: finding.impact,
+			confidence: finding.confidence,
+			basis: finding.basis,
 			foundAtSha: finding.foundAtSha,
 			watchdogs: [...finding.watchdogIds],
 		}));