@payconductor/houndsman 0.13.0 → 0.16.0

package/src/core/engine/review-context.ts

@@ -0,0 +1,51 @@
+/**
+ * Contexto de uma run (engine) — storage + review + staging + raiz operacional.
+ *
+ * É criado uma vez por `ReviewSession` e injetado nas pipelines. Não existe
+ * contexto ambiente: duas runs concorrentes no mesmo processo mantêm contextos
+ * isolados (um singleton mutável trocaria root/git/storage entre `await`s).
+ */
+
+import { GitRepository } from "../services/git-repository";
+import { ProjectFiles } from "../services/project-files";
+import type { ReviewRecord, StorageProvider } from "../storage/types";
+import { ReviewWorkArea } from "../storage/work-area";
+
+/** Workspace onde os arquivos da review são lidos. */
+export type ReviewWorkspaceContext = {
+	/** Raiz operacional (worktree ou clone principal). */
+	root?: string;
+	/** Raiz do clone principal (identidade/config). */
+	mainRoot?: string;
+	git?: GitRepository;
+};
+
+/** Contexto de uma run: storage + review + staging + raiz operacional. */
+export type ReviewContext = {
+	storage: StorageProvider;
+	review: ReviewRecord;
+	work: ReviewWorkArea;
+	root: string;
+	mainRoot: string;
+	git: GitRepository;
+	/** Leitor relativo à raiz operacional (evita repetir `fileReader(root)`). */
+	files: ProjectFiles;
+};
+
+/** Cria o contexto de uma review existente. */
+export function reviewContext(
+	storage: StorageProvider,
+	review: ReviewRecord,
+	workspace: ReviewWorkspaceContext = {},
+): ReviewContext {
+	const root = workspace.root ?? process.cwd();
+	return {
+		storage,
+		review,
+		work: new ReviewWorkArea(review),
+		root,
+		mainRoot: workspace.mainRoot ?? root,
+		git: workspace.git ?? new GitRepository(),
+		files: new ProjectFiles(root),
+	};
+}

package/src/core/engine/review-options.ts

@@ -0,0 +1,47 @@
+/**
+ * Opções de uma run (flags do CLI já resolvidas).
+ *
+ * Fica fora do `orchestrator` para as pipelines importarem o tipo sem ciclo.
+ */
+
+export type ReviewOptions = {
+	base: string;
+	head: string;
+	branch?: string;
+	/**
+	 * Rótulo da variante A/B. Cada variante vira uma run própria
+	 * (`repoKey`, `branch`, `variant`) — permite comparar sem apagar a anterior.
+	 */
+	variant?: string;
+	finalize: boolean;
+	failOnBlocking: boolean;
+	clean: boolean;
+	noJev: boolean;
+	/** Desativa a análise estrutural (AST) nesta run. */
+	noAst: boolean;
+	/** Força review completo (ignora o modo incremental). */
+	full: boolean;
+	/** Desativa as features de IA do fluxo normal. */
+	noAi: boolean;
+	/** PR de origem (resolvida via `--pr`). */
+	pr?: number;
+	/** Worktree informado via flag (`--worktree`). */
+	worktree?: string;
+	/** Worktree resolvido (absoluto; ausente = clone principal). */
+	worktreePath?: string;
+};
+
+/** Valores default das opções (o CLI sobrepõe com as flags). */
+export function defaultOptions(): ReviewOptions {
+	return {
+		base: "main",
+		head: "HEAD",
+		finalize: false,
+		failOnBlocking: false,
+		clean: false,
+		noJev: false,
+		noAst: false,
+		full: false,
+		noAi: false,
+	};
+}

package/src/core/engine/review-scope.ts

@@ -52,6 +52,11 @@ export type ReviewScope =
 			kind: "review";
 			classification: RunClassification;
 			diff: DiffSource;
+			/**
+			 * Patch `-U0` sem truncar (path → hunks). É o insumo dos briefs: cada
+			 * watchdog recebe os trechos alterados em vez de reler arquivos inteiros.
+			 */
+			patch: Map<string, string>;
 			reviewedFrom?: string;
 			/** Fatos/delta por arquivo alterado (quando o AST está habilitado). */
 			ast?: Map<string, AstAnalysis>;
@@ -144,6 +149,7 @@ export class ReviewScopeResolver {
 			return {
 				kind: "review",
 				diff,
+				patch: scopeDiff.byFile,
 				ast,
 				classification: {
 					...result,
@@ -192,7 +198,14 @@ export class ReviewScopeResolver {
 				ast,
 			}),
 		};
-		return { kind: "review", classification, diff, reviewedFrom: prevSha, ast };
+		return {
+			kind: "review",
+			classification,
+			diff,
+			patch: scopeDiff.byFile,
+			reviewedFrom: prevSha,
+			ast,
+		};
 	}
 
 	/**

package/src/core/engine/review-session.ts

@@ -20,7 +20,7 @@ import {
 	resolveBranch,
 	reviewContext,
 } from "../orchestrator";
-import { sanitizeBranch } from "../report-builder";
+import { reviewSlug } from "../report-builder";
 import { GitRepository } from "../services/git-repository";
 import type { RepoIdentity, StorageProvider } from "../storage/types";
 
@@ -48,12 +48,14 @@ export class ReviewSession {
 		this.branch = branch;
 		this.ast = ast;
 		this.ai = ai;
+		const variant = options.variant?.trim() || undefined;
 		const review = options.finalize
-			? storage.findReview(repo.key, branch)
+			? storage.findReview(repo.key, branch, variant)
 			: storage.getOrCreateReview({
 					repo,
 					branch,
-					slug: sanitizeBranch(branch),
+					variant,
+					slug: reviewSlug(branch, variant),
 					base: options.base,
 					head: options.head,
 					worktreePath: options.worktreePath,
@@ -61,7 +63,7 @@ export class ReviewSession {
 				});
 		if (!review) {
 			throw new Error(
-				`Nenhuma revisão para '${branch}'. Rode \`houndsman\` (preparar) primeiro.`,
+				`Nenhuma revisão para '${branch}'${variant ? ` (variante '${variant}')` : ""}. Rode \`houndsman\` (preparar) primeiro.`,
 			);
 		}
 		// Um prepare no clone principal invalida um worktree usado antes; o finalize
@@ -106,20 +108,16 @@ export class ReviewSession {
 
 	/** Passo 1 — preparar. */
 	prepare(onProgress?: PrepareProgress): Promise<PrepareResult> {
-		return prepare(
-			this.options,
-			this.branch,
-			this.config,
-			this.context,
-			this.ast,
-			this.ai,
+		return prepare(this.context, this.config, this.options, {
+			ast: this.ast,
+			ai: this.ai,
 			onProgress,
-		);
+		});
 	}
 
 	/** Passo 3 — finalizar. */
 	finalize(): FinalizeResult {
-		return finalize(this.options, this.branch, this.config, this.context);
+		return finalize(this.context, this.config, this.options);
 	}
 
 	/** Executa o passo escolhido em `--finalize`. */

package/src/core/engine/run-artifacts.ts

@@ -0,0 +1,196 @@
+/**
+ * Artefatos persistidos de uma run (engine) — leitura/escrita tipada.
+ *
+ * Concentra `classification`, `candidates`, `manifest`, resumos e contexto para
+ * que as pipelines não repitam `storage.readArtifact(...)`.
+ */
+
+import type { AstAnalysis, AstImpact } from "../ast/types";
+import { GENERAL_WATCHDOG_ID } from "../builtins";
+import { type BusinessSummary, parseBusinessSummary } from "../business-summary";
+import type { HoundsmanConfig } from "../config";
+import { type JevCandidatesFile, JevCandidatesStore, parseCandidates } from "../jev";
+import {
+	BUSINESS_BRIEF_FILE,
+	BUSINESS_SUMMARY_FILE,
+	TECHNICAL_SUMMARY_FILE,
+} from "../paths";
+import type {
+	ManifestAi,
+	ManifestAst,
+	ManifestBusiness,
+} from "../renderers/manifest-writer";
+import { type ContextSummary, parseContextSummary } from "../report-builder";
+import type { ReviewRecord, StorageProvider } from "../storage/types";
+import type { ReviewWorkArea } from "../storage/work-area";
+import {
+	buildTechnicalSummary,
+	parseTechnicalSummary,
+	type TechnicalSummary,
+} from "../technical-summary";
+import type { RunClassification } from "./review-scope";
+
+/** Acesso tipado aos artefatos de uma review. */
+export class RunArtifacts {
+	constructor(
+		private readonly storage: StorageProvider,
+		private readonly review: ReviewRecord,
+		private readonly work: ReviewWorkArea,
+	) {}
+
+	/** JSON persistido, ou `null` quando ausente/inválido. */
+	json<T>(name: string): T | null {
+		const artifact = this.storage.readArtifact(this.review.id, name);
+		if (!artifact) return null;
+		try {
+			return JSON.parse(artifact.content) as T;
+		} catch {
+			return null;
+		}
+	}
+
+	/** Reaproveita `ast`/`ai`/`business` do manifesto anterior. */
+	manifestExtras(): {
+		ast?: ManifestAst;
+		ai?: ManifestAi;
+		business?: ManifestBusiness;
+	} {
+		const artifact = this.storage.readArtifact(this.review.id, "manifest.json");
+		if (!artifact) return {};
+		try {
+			const parsed = JSON.parse(artifact.content) as {
+				ast?: ManifestAst;
+				ai?: ManifestAi;
+				business?: ManifestBusiness;
+			};
+			return {
+				ast: parsed.ast,
+				ai: parsed.ai,
+				business: parsed.business ?? undefined,
+			};
+		} catch {
+			return {};
+		}
+	}
+
+	/** Lê o `classification.json` persistido pelo prepare (lança se ausente). */
+	classification(): RunClassification {
+		const artifact = this.storage.readArtifact(this.review.id, "classification.json");
+		if (!artifact) {
+			throw new Error(
+				`Não encontrei a classificação da review. Rode \`bun run houndsman\` (preparar) primeiro.`,
+			);
+		}
+		return JSON.parse(artifact.content) as RunClassification;
+	}
+
+	/** Lê os candidatos Jev persistidos (unavailable se ausente/inválido). */
+	candidates(config: HoundsmanConfig): JevCandidatesFile {
+		const artifact = this.storage.readArtifact(this.review.id, "candidates.json");
+		if (!artifact) return JevCandidatesStore.unavailable("candidates.json ausente");
+		try {
+			return (
+				parseCandidates(JSON.parse(artifact.content), [
+					...config.watchdogIds,
+					GENERAL_WATCHDOG_ID,
+				]) ?? JevCandidatesStore.unavailable("candidates.json inválido")
+			);
+		} catch {
+			return JevCandidatesStore.unavailable("candidates.json inválido");
+		}
+	}
+
+	/** Resumo do contexto persistido (usado quando o staging já foi limpo). */
+	contextSummary(): ContextSummary | null {
+		const artifact = this.storage.readArtifact(
+			this.review.id,
+			"context-summary.json",
+		);
+		if (!artifact) return null;
+		try {
+			return parseContextSummary(JSON.parse(artifact.content));
+		} catch {
+			return null;
+		}
+	}
+
+	/** Modelo de intenção persistido pelo prepare/revisor; `null` quando ausente. */
+	businessSummary(): BusinessSummary | null {
+		const raw = this.json<unknown>(BUSINESS_SUMMARY_FILE);
+		return raw ? parseBusinessSummary(raw) : null;
+	}
+
+	/** Pontos técnicos persistidos pelo `prepare`; `null` quando ausentes. */
+	technicalSummary(): TechnicalSummary | null {
+		const raw = this.json<unknown>(TECHNICAL_SUMMARY_FILE);
+		return raw ? parseTechnicalSummary(raw) : null;
+	}
+
+	/** Fallback para runs antigas: reconstrói os destaques dos artefatos de AST. */
+	technicalFallback(classification: RunClassification): TechnicalSummary {
+		const ast = this.json<{ files?: Record<string, AstAnalysis> }>(
+			"ast-summary.json",
+		);
+		return buildTechnicalSummary({
+			classification,
+			ast: ast?.files ? new Map(Object.entries(ast.files)) : undefined,
+			impact: this.json<AstImpact>("ast-impact.json") ?? undefined,
+			headSha: classification.headSha,
+		});
+	}
+
+	/** Persiste o contexto da PR (bruto + resumo) como artefatos, quando existirem. */
+	persistContext(): void {
+		const raw = this.work.readContextRaw();
+		if (raw !== null) {
+			this.storage.writeArtifact(this.review.id, {
+				name: "context.json",
+				kind: "context",
+				content: raw,
+			});
+		}
+		const summary = this.work.readContextSummaryRaw();
+		if (summary !== null) {
+			this.storage.writeArtifact(this.review.id, {
+				name: "context-summary.json",
+				kind: "context-summary",
+				content: summary,
+			});
+		}
+		const brief = this.work.readContextBriefRaw();
+		if (brief !== null) {
+			this.storage.writeArtifact(this.review.id, {
+				name: "context-brief.md",
+				kind: "context-brief",
+				content: brief,
+			});
+		}
+	}
+
+	/**
+	 * Persiste o `business-summary.json` final: o revisor `general` pode ter
+	 * reescrito o modelo no staging durante a revisão.
+	 */
+	persistBusiness(): BusinessSummary | null {
+		const raw = this.work.readBusinessSummaryRaw();
+		if (raw === null) return this.businessSummary();
+		this.storage.writeArtifact(this.review.id, {
+			name: BUSINESS_SUMMARY_FILE,
+			kind: "business",
+			content: raw.endsWith("\n") ? raw : `${raw}\n`,
+		});
+		const brief = this.work.readBusinessBriefRaw();
+		if (brief !== null) {
+			this.storage.writeArtifact(this.review.id, {
+				name: BUSINESS_BRIEF_FILE,
+				kind: "business-brief",
+				content: brief.endsWith("\n") ? brief : `${brief}\n`,
+			});
+		}
+		try {
+			return parseBusinessSummary(JSON.parse(raw), "reviewer");
+		} catch {
+			return this.businessSummary();
+		}
+	}
+}

package/src/core/engine/run-format.ts

@@ -0,0 +1,4 @@
+/** SHA curto para logs (7 chars, como o git). */
+export function shortSha(sha: string): string {
+	return sha.slice(0, 7);
+}

package/src/core/findings-state.ts

@@ -18,9 +18,10 @@ import {
 	locateAnchor,
 	reanchor,
 } from "./finding-anchor";
-import { type MergedFinding, sanitizeBranch } from "./report-builder";
+import { type FindingBasis, type MergedFinding, sanitizeBranch } from "./report-builder";
 import { systemClock } from "./services/clock";
 import { type FileReader, ProjectFiles } from "./services/project-files";
+import { isImpactClass } from "./severity";
 import { SEVERITY_ORDER, type Severity, severityRank } from "./types";
 
 export type { FileReader };
@@ -101,6 +102,14 @@ export type FindingState = {
 	message: string;
 	action: string;
 	evidence?: string;
+	/** Gatilho concreto do gap (fora de regra). */
+	scenario?: string;
+	/** Consequência observável do gap. */
+	impact?: string;
+	/** Confiança do revisor (0–1). */
+	confidence?: number;
+	/** Origem do achado: regra, lógica ou domínio. */
+	basis?: FindingBasis;
 	anchor: FindingAnchor | null;
 	/** Commit em que o achado foi observado (base do diff focado do verify). */
 	foundAtSha?: string;
@@ -359,17 +368,28 @@ export function buildStateFromFindings(
 		const prev = previous
 			? Object.values(previous.findings).find((f) => f.fingerprint === fingerprint)
 			: undefined;
+		// Emergente sem `impactClass` (relatório legado) mantém a severidade já triada
+		// para o mesmo fingerprint: o código é o mesmo, então o valor não pode oscilar
+		// entre reviews. Regra e `impactClass` produzem valor determinístico e vencem.
+		const sticky =
+			(finding.basis ?? "rule") !== "rule" &&
+			!isImpactClass(finding.impactClass) &&
+			prev !== undefined;
 		const created: FindingState = {
 			id: prev?.id ?? newFindingId(),
 			fingerprint,
 			watchdogIds: [...finding.watchdogs],
 			rule: finding.rule,
-			severity: finding.severity,
+			severity: sticky && prev ? prev.severity : finding.severity,
 			file: finding.file,
 			line: anchor ? anchor.line : null,
 			message: finding.message,
 			action: finding.action,
 			evidence: finding.evidence,
+			scenario: finding.scenario,
+			impact: finding.impact,
+			confidence: finding.confidence,
+			basis: finding.basis,
 			anchor,
 			// Carry-over preserva o `foundAtSha` original; novos/re-reportados usam o head atual.
 			foundAtSha: finding.foundAtSha ?? options.headSha ?? prev?.foundAtSha,

package/src/core/github-review.ts

@@ -225,9 +225,10 @@ export function buildCommentBody(finding: FindingState): string {
 		`${SEVERITY_EMOJI[finding.severity]} **${finding.rule}** · _${finding.severity}_`,
 		"",
 		finding.message,
-		"",
-		`**Ação:** ${finding.action}`,
 	];
+	if (finding.scenario) lines.push("", `**Cenário:** ${finding.scenario}`);
+	if (finding.impact) lines.push("", `**Impacto:** ${finding.impact}`);
+	lines.push("", `**Ação:** ${finding.action}`);
 	if (finding.evidence) lines.push("", "```", finding.evidence, "```");
 	lines.push("", "_— houndsman_");
 	return lines.join("\n");
@@ -247,6 +248,8 @@ export function renderGeneralBody(findings: readonly FindingState[]): string {
 			`- ${SEVERITY_EMOJI[finding.severity]} **${finding.severity}** \`${location}\` — ${finding.rule}`,
 			`  ${finding.message}`,
 		);
+		if (finding.scenario) lines.push(`  **Cenário:** ${finding.scenario}`);
+		if (finding.impact) lines.push(`  **Impacto:** ${finding.impact}`);
 	}
 	return lines.join("\n");
 }