@payconductor/houndsman 0.11.0 → 0.13.0

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

@@ -7,6 +7,7 @@
 
 import type { AstService } from "../ast/service";
 import type { AstAnalysis, AstFacts } from "../ast/types";
+import { buildChangedScope, type ChangedScope, type ScopeEntry } from "../changed-scope";
 import type { HoundsmanConfig } from "../config";
 import { churnToRecord, type DiffSource } from "../diff-source";
 import { type ClassificationResult, parseEntries } from "../file-classifier";
@@ -34,6 +35,8 @@ export type RunClassification = ClassificationResult & {
 	reviewedFrom?: string;
 	/** Findings preservados do review anterior (arquivos inalterados). */
 	carryover?: MergedFinding[];
+	/** Faixas revisáveis por arquivo (símbolos alterados; hunks como fallback). */
+	changedScope?: ChangedScope;
 };
 
 /** Resultado da resolução de escopo: revisar ou nada a fazer. */
@@ -54,23 +57,37 @@ export type ReviewScope =
 			ast?: Map<string, AstAnalysis>;
 	  };
 
+/** Etapas da resolução de escopo reportadas ao CLI (sem log no core). */
+export type ScopeStage = "diff" | "ast" | "classify";
+
+/** Evento de progresso de uma etapa do escopo. */
+export type ScopeProgressEvent =
+	| { type: "start"; stage: ScopeStage }
+	| { type: "done"; stage: ScopeStage; durationMs: number };
+
+/** Callback de progresso (falhas do callback são ignoradas). */
+export type ScopeProgress = (event: ScopeProgressEvent) => void;
+
 /** Decide entre review completo e incremental. */
 export class ReviewScopeResolver {
 	private readonly options: ScopeOptions;
 	private readonly classifier: FileClassifier;
 	private readonly ast?: AstService;
 	private readonly git: GitRepository;
+	private readonly onProgress?: ScopeProgress;
 
 	constructor(
 		options: ScopeOptions,
 		config: HoundsmanConfig,
 		ast?: AstService,
 		git: GitRepository = new GitRepository(),
+		onProgress?: ScopeProgress,
 	) {
 		this.options = options;
 		this.classifier = new FileClassifier(config);
 		this.ast = ast;
 		this.git = git;
+		this.onProgress = onProgress;
 	}
 
 	/**
@@ -97,48 +114,131 @@ export class ReviewScopeResolver {
 			!prevSha ||
 			!this.git.isAncestor(prevSha, headSha)
 		) {
-			const diff = this.git.collectDiff(this.options.base, this.options.head);
-			const entries = parseEntries(
-				this.git.diffNameStatus(this.options.base, this.options.head),
-			);
-			const baseRef =
-				this.git.mergeBase(this.options.base, this.options.head) ??
-				this.options.base;
-			const ast = this.ast
-				? await this.ast.analyze(entries, diff, baseRef)
+			const diffData = this.step("diff", () => {
+				const diff = this.git.collectDiff(this.options.base, this.options.head);
+				const entries = parseEntries(
+					this.git.diffNameStatus(this.options.base, this.options.head),
+				);
+				const baseRef =
+					this.git.mergeBase(this.options.base, this.options.head) ??
+					this.options.base;
+				// Patch `-U0` sem truncar: mais preciso para delta AST e escopo.
+				const scopeDiff = this.zeroContext(
+					`${this.options.base}...${this.options.head}`,
+					diff,
+				);
+				return { diff, entries, baseRef, scopeDiff };
+			});
+			const { diff, entries, baseRef, scopeDiff } = diffData;
+			const astService = this.ast;
+			const ast = astService
+				? await this.stepAsync("ast", () =>
+						astService.analyze(entries, scopeDiff, baseRef),
+					)
 				: undefined;
+			const result = this.step("classify", () =>
+				this.classifier
+					.classify(entries, churnToRecord(diff.churn), factsOf(ast))
+					.toJSON(),
+			);
 			return {
 				kind: "review",
 				diff,
 				ast,
 				classification: {
-					...this.classifier
-						.classify(entries, churnToRecord(diff.churn), factsOf(ast))
-						.toJSON(),
+					...result,
 					headSha,
 					mode: "full",
+					changedScope: buildChangedScope({
+						entries: scopeEntries(entries, result),
+						diff: scopeDiff,
+						ast,
+					}),
 				},
 			};
 		}
 
 		const range = `${prevSha}..${headSha}`;
-		const diff = this.git.collectDiffSince(prevSha, headSha);
-		const entries = parseEntries(this.git.run(["diff", range, "--name-status"]));
+		const diffData = this.step("diff", () => {
+			const diff = this.git.collectDiffSince(prevSha, headSha);
+			const entries = parseEntries(this.git.run(["diff", range, "--name-status"]));
+			const scopeDiff = this.zeroContext(range, diff);
+			return { diff, entries, scopeDiff };
+		});
+		const { diff, entries, scopeDiff } = diffData;
 		const changedPaths = new Set(entries.map((entry) => entry.path));
-		const ast = this.ast ? await this.ast.analyze(entries, diff, prevSha) : undefined;
-		const classification: RunClassification = {
-			...this.classifier
+		const astService = this.ast;
+		const ast = astService
+			? await this.stepAsync("ast", () =>
+					astService.analyze(entries, scopeDiff, prevSha),
+				)
+			: undefined;
+		const result = this.step("classify", () =>
+			this.classifier
 				.classify(entries, churnToRecord(diff.churn), factsOf(ast))
 				.toJSON(),
+		);
+		const classification: RunClassification = {
+			...result,
 			base: prevSha,
 			head: this.options.head,
 			headSha,
 			mode: "incremental",
 			reviewedFrom: prevSha,
 			carryover: buildCarryover(previous, changedPaths),
+			changedScope: buildChangedScope({
+				entries: scopeEntries(entries, result),
+				diff: scopeDiff,
+				ast,
+			}),
 		};
 		return { kind: "review", classification, diff, reviewedFrom: prevSha, ast };
 	}
+
+	/**
+	 * Executa uma etapa síncrona reportando início/fim. O callback de progresso
+	 * é diagnóstico: nunca derruba a resolução.
+	 */
+	private step<T>(stage: ScopeStage, run: () => T): T {
+		if (!this.onProgress) return run();
+		const started = Date.now();
+		this.report({ type: "start", stage });
+		try {
+			return run();
+		} finally {
+			this.report({ type: "done", stage, durationMs: Date.now() - started });
+		}
+	}
+
+	/** Versão assíncrona de `step`. */
+	private async stepAsync<T>(stage: ScopeStage, run: () => Promise<T> | T): Promise<T> {
+		if (!this.onProgress) return run();
+		const started = Date.now();
+		this.report({ type: "start", stage });
+		try {
+			return await run();
+		} finally {
+			this.report({ type: "done", stage, durationMs: Date.now() - started });
+		}
+	}
+
+	private report(event: ScopeProgressEvent): void {
+		try {
+			this.onProgress?.(event);
+		} catch {
+			// Progresso nunca derruba a revisão.
+		}
+	}
+
+	/** Patch `-U0` do intervalo; falha aberta cai no diff já coletado. */
+	private zeroContext(range: string, fallback: DiffSource): DiffSource {
+		try {
+			const byFile = this.git.patchZeroContext(range);
+			return byFile.size > 0 ? { byFile, churn: fallback.churn } : fallback;
+		} catch {
+			return fallback;
+		}
+	}
 }
 
 /** Fatos apenas dos arquivos presentes (deletados não classificam). */
@@ -152,3 +252,17 @@ function factsOf(
 	}
 	return facts;
 }
+
+/**
+ * Entradas revisáveis do `--name-status`: exclui arquivos do `exclusions` e
+ * deletados (não há código atual para ancorar finding).
+ */
+function scopeEntries(
+	entries: ReturnType<typeof parseEntries>,
+	result: ClassificationResult,
+): ScopeEntry[] {
+	const excluded = new Set(result.excluded);
+	return entries
+		.filter((entry) => entry.status !== "deleted" && !excluded.has(entry.path))
+		.map((entry) => ({ path: entry.path, status: entry.status }));
+}

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

@@ -11,6 +11,7 @@ import { createGitRunner } from "../git-runner";
 import {
 	type FinalizeResult,
 	finalize,
+	type PrepareProgress,
 	type PrepareResult,
 	prepare,
 	type ReviewContext,
@@ -104,7 +105,7 @@ export class ReviewSession {
 	}
 
 	/** Passo 1 — preparar. */
-	prepare(): Promise<PrepareResult> {
+	prepare(onProgress?: PrepareProgress): Promise<PrepareResult> {
 		return prepare(
 			this.options,
 			this.branch,
@@ -112,6 +113,7 @@ export class ReviewSession {
 			this.context,
 			this.ast,
 			this.ai,
+			onProgress,
 		);
 	}
 
@@ -121,7 +123,9 @@ export class ReviewSession {
 	}
 
 	/** Executa o passo escolhido em `--finalize`. */
-	run(): Promise<PrepareResult | FinalizeResult> {
-		return this.options.finalize ? Promise.resolve(this.finalize()) : this.prepare();
+	run(onProgress?: PrepareProgress): Promise<PrepareResult | FinalizeResult> {
+		return this.options.finalize
+			? Promise.resolve(this.finalize())
+			: this.prepare(onProgress);
 	}
 }

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

@@ -35,6 +35,8 @@ export type WorkspaceDeps = {
 	worktreesLocation?: string;
 	/** Override explícito da raiz de worktrees (testes). */
 	worktreesRoot?: string;
+	/** Passos longos (gh/worktree) reportados ao CLI; nunca lança. */
+	onProgress?: (message: string) => void;
 };
 
 /** Workspace resolvido para a revisão. */
@@ -85,6 +87,14 @@ export function resolveReviewWorkspace(
 	deps: WorkspaceDeps = {},
 ): ResolvedWorkspace {
 	const messages: string[] = [];
+	/** Progresso é diagnóstico: nunca derruba a resolução. */
+	const report = (message: string): void => {
+		try {
+			deps.onProgress?.(message);
+		} catch {
+			// Progresso nunca derruba a revisão.
+		}
+	};
 	const cwdGit = repoAt(request.cwd);
 	const cwdRoot = resolve(cwdGit.rootPath() ?? request.cwd);
 	const mainRoot = resolve(mainRootOf(cwdGit, cwdRoot));
@@ -108,6 +118,7 @@ export function resolveReviewWorkspace(
 		// A camada gerada não vem no checkout; sem ela os comandos no worktree
 		// não carregam a config (`../core/types`).
 		const explicitMainRoot = mainRootOf(git, repo.root);
+		report("Sincronizando a camada gerada no worktree…");
 		syncProjectLayer(explicitMainRoot, root);
 		return {
 			root,
@@ -129,6 +140,7 @@ export function resolveReviewWorkspace(
 			deps.ghRunner ?? createGhRunner(mainRoot),
 			mainGit,
 		);
+		report(`Consultando a PR #${request.pr} via gh…`);
 		const resolved = resolver.resolve(request.pr);
 		if (!resolved.ok) {
 			throw new Error(
@@ -136,6 +148,7 @@ export function resolveReviewWorkspace(
 			);
 		}
 		const { pr } = resolved;
+		report("Buscando as refs da PR…");
 		const refs = resolver.prepareRefs(pr);
 		if (refs.warning) messages.push(`GitHub: ${refs.warning}`);
 
@@ -146,6 +159,7 @@ export function resolveReviewWorkspace(
 				deps.worktreesRoot ??
 				resolveWorktreesRoot(deps.worktreesLocation, mainRoot),
 		});
+		report("Criando/reutilizando o worktree da PR…");
 		const worktree = manager.ensure({ branch: pr.headRefName, ref: refs.head });
 		const worktreePath = resolve(worktree.path);
 		messages.push(

package/src/core/env.ts

@@ -19,6 +19,8 @@ export const ENV_NAMES = {
 	deepSeekApiKey: "HOUNDSMAN_DEEP_SEEK_API_KEY",
 	openAiApiKey: "HOUNDSMAN_OPENAI_API_KEY",
 	anthropicApiKey: "HOUNDSMAN_ANTHROPIC_API_KEY",
+	makiPath: "HOUNDSMAN_MAKI_PATH",
+	makiVersion: "HOUNDSMAN_MAKI_VERSION",
 	home: "HOUNDSMAN_HOME",
 	localAppData: "LOCALAPPDATA",
 	xdgDataHome: "XDG_DATA_HOME",
@@ -33,6 +35,10 @@ export type HoundsmanEnv = {
 	deepSeekApiKey?: string;
 	openAiApiKey?: string;
 	anthropicApiKey?: string;
+	/** Caminho explícito do binário do maki (harness local `hunt`). */
+	makiPath?: string;
+	/** Versão do maki a instalar (default: a fixada pelo pacote). */
+	makiVersion?: string;
 	home?: string;
 	localAppData?: string;
 	xdgDataHome?: string;
@@ -54,6 +60,8 @@ export function readEnv(): HoundsmanEnv {
 		deepSeekApiKey: read(ENV_NAMES.deepSeekApiKey),
 		openAiApiKey: read(ENV_NAMES.openAiApiKey),
 		anthropicApiKey: read(ENV_NAMES.anthropicApiKey),
+		makiPath: read(ENV_NAMES.makiPath),
+		makiVersion: read(ENV_NAMES.makiVersion),
 		home: read(ENV_NAMES.home),
 		localAppData: read(ENV_NAMES.localAppData),
 		xdgDataHome: read(ENV_NAMES.xdgDataHome),
@@ -80,6 +88,12 @@ export const env = {
 	get anthropicApiKey(): string | undefined {
 		return read(ENV_NAMES.anthropicApiKey);
 	},
+	get makiPath(): string | undefined {
+		return read(ENV_NAMES.makiPath);
+	},
+	get makiVersion(): string | undefined {
+		return read(ENV_NAMES.makiVersion);
+	},
 	get home(): string | undefined {
 		return read(ENV_NAMES.home);
 	},

package/src/core/hunt/hunt-runner.ts

@@ -0,0 +1,328 @@
+/**
+ * Orquestração do harness local (`houndsman hunt`).
+ *
+ * Recebe os briefs já preparados e despacha um processo maki por watchdog. O
+ * watchdog devolve o JSON na resposta final; validamos com o mesmo parser do
+ * `--finalize` e gravamos em `findings/<id>.json`. Falhas são reportadas por
+ * watchdog — a política de finalizar ou não fica com o chamador (CLI).
+ */
+
+import { readFileSync } from "node:fs";
+import { parseWatchdogReport } from "../report-builder";
+import { systemClock } from "../services/clock";
+import type { ReviewWorkArea } from "../storage/work-area";
+import { renderHuntPrompt, renderRetrySuffix } from "./maki-prompt";
+import {
+	extractJsonObject,
+	type MakiProcessRunner,
+	type MakiRunMetrics,
+	type MakiUsage,
+} from "./maki-runner";
+import { mapPool } from "./pool";
+
+/** Evento de progresso (CLI loga; core não escreve saída). */
+export type HuntEvent =
+	| { type: "start"; watchdogId: string }
+	| {
+			type: "retry";
+			watchdogId: string;
+			attempt: number;
+			maxAttempts: number;
+			error: string;
+	  }
+	| {
+			type: "done";
+			watchdogId: string;
+			findings: number;
+			reviewedFiles: number;
+			attempts: number;
+			metrics: MakiRunMetrics;
+	  }
+	| {
+			type: "failed";
+			watchdogId: string;
+			error: string;
+			attempts: number;
+			metrics: MakiRunMetrics;
+	  };
+
+/** Resultado de um watchdog. */
+export type HuntWatchdogResult = {
+	watchdogId: string;
+	status: "done" | "failed";
+	findings: number;
+	reviewedFiles: number;
+	attempts: number;
+	durationMs: number;
+	sessionId?: string;
+	numTurns?: number;
+	costUsd?: number;
+	usage?: MakiUsage;
+	error?: string;
+};
+
+/** Agregados do relatório. */
+export type HuntTotals = {
+	watchdogs: number;
+	done: number;
+	failed: number;
+	findings: number;
+	costUsd: number;
+	inputTokens: number;
+	outputTokens: number;
+	totalTokens: number;
+};
+
+/** Relatório persistido como `hunt-report.json`. */
+export type HuntReport = {
+	version: 1;
+	engine: "maki";
+	model: string;
+	startedAt: string;
+	finishedAt: string;
+	durationMs: number;
+	watchdogs: HuntWatchdogResult[];
+	totals: HuntTotals;
+};
+
+/** Dependências do runner. */
+export type HuntRunnerOptions = {
+	/** Staging da review (briefs/findings). */
+	work: ReviewWorkArea;
+	/** Raiz de leitura dos arquivos da review. */
+	root: string;
+	projectName: string;
+	/** Spec `provider/model-id`. */
+	model: string;
+	apiKeyEnv: string;
+	apiKey: string;
+	concurrency: number;
+	timeoutMs: number;
+	retries: number;
+	runner: MakiProcessRunner;
+	onEvent?: (event: HuntEvent) => void;
+};
+
+/** Despacha os briefs via maki e devolve o relatório consolidado. */
+export class HuntRunner {
+	private readonly options: HuntRunnerOptions;
+
+	constructor(options: HuntRunnerOptions) {
+		this.options = options;
+	}
+
+	async run(activeIds: readonly string[]): Promise<HuntReport> {
+		const startedAt = systemClock();
+		const startedMs = Date.now();
+		const watchdogs = await mapPool(activeIds, this.options.concurrency, (id) =>
+			this.runOne(id),
+		);
+		const finishedAt = systemClock();
+		return {
+			version: 1,
+			engine: "maki",
+			model: this.options.model,
+			startedAt,
+			finishedAt,
+			durationMs: Date.now() - startedMs,
+			watchdogs,
+			totals: totalsOf(watchdogs),
+		};
+	}
+
+	private async runOne(watchdogId: string): Promise<HuntWatchdogResult> {
+		const briefPath = this.options.work.briefFile(watchdogId);
+		let brief: string;
+		try {
+			brief = readFileSync(briefPath, "utf8");
+		} catch {
+			const error = `Brief ausente: ${briefPath}`;
+			this.emit({
+				type: "failed",
+				watchdogId,
+				error,
+				attempts: 0,
+				metrics: { durationMs: 0 },
+			});
+			return failedResult(watchdogId, error, 0, { durationMs: 0 });
+		}
+
+		const basePrompt = renderHuntPrompt({
+			projectName: this.options.projectName,
+			watchdogId,
+			brief,
+		});
+
+		this.emit({ type: "start", watchdogId });
+		let attempts = 0;
+		let lastError = "";
+		const accumulated: MakiRunMetrics = { durationMs: 0 };
+
+		while (attempts <= this.options.retries) {
+			attempts++;
+			const prompt =
+				attempts === 1
+					? basePrompt
+					: `${basePrompt}\n${renderRetrySuffix(lastError)}`;
+			const result = await this.options.runner.run({
+				prompt,
+				cwd: this.options.root,
+				model: this.options.model,
+				apiKeyEnv: this.options.apiKeyEnv,
+				apiKey: this.options.apiKey,
+				timeoutMs: this.options.timeoutMs,
+			});
+			mergeMetrics(accumulated, result.metrics);
+
+			if (!result.ok) {
+				lastError = result.error;
+				this.emitRetry(watchdogId, attempts, lastError);
+				continue;
+			}
+
+			const raw = extractJsonObject(result.text);
+			if (raw === null) {
+				lastError = "a resposta final não contém um objeto JSON.";
+				this.emitRetry(watchdogId, attempts, lastError);
+				continue;
+			}
+
+			const warnings: string[] = [];
+			const report = parseWatchdogReport(raw, `maki:${watchdogId}`, (message) =>
+				warnings.push(message),
+			);
+			if (!report) {
+				lastError = warnings[0] ?? "JSON fora do schema do watchdog.";
+				this.emitRetry(watchdogId, attempts, lastError);
+				continue;
+			}
+			if (report.watchdogId !== watchdogId) {
+				lastError = `watchdogId '${report.watchdogId}' não corresponde a '${watchdogId}'.`;
+				this.emitRetry(watchdogId, attempts, lastError);
+				continue;
+			}
+
+			this.options.work.writeFinding(
+				watchdogId,
+				`${JSON.stringify(report, null, 2)}\n`,
+			);
+			const done: HuntWatchdogResult = {
+				watchdogId,
+				status: "done",
+				findings: report.findings.length,
+				reviewedFiles: report.reviewedFiles.length,
+				attempts,
+				durationMs: accumulated.durationMs,
+				sessionId: accumulated.sessionId,
+				numTurns: accumulated.numTurns,
+				costUsd: accumulated.costUsd,
+				usage: accumulated.usage,
+			};
+			this.emit({
+				type: "done",
+				watchdogId,
+				findings: done.findings,
+				reviewedFiles: done.reviewedFiles,
+				attempts,
+				metrics: accumulated,
+			});
+			return done;
+		}
+
+		const error = lastError || "falha desconhecida.";
+		this.emit({ type: "failed", watchdogId, error, attempts, metrics: accumulated });
+		return failedResult(watchdogId, error, attempts, accumulated);
+	}
+
+	private emit(event: HuntEvent): void {
+		try {
+			this.options.onEvent?.(event);
+		} catch {
+			// Progresso nunca derruba a revisão.
+		}
+	}
+
+	/** Avisa a próxima tentativa (só quando ainda há retry). */
+	private emitRetry(watchdogId: string, attempt: number, error: string): void {
+		if (attempt > this.options.retries) return;
+		this.emit({
+			type: "retry",
+			watchdogId,
+			attempt,
+			maxAttempts: this.options.retries + 1,
+			error,
+		});
+	}
+}
+
+/** Soma métricas de várias tentativas no acumulado. */
+function mergeMetrics(target: MakiRunMetrics, source: MakiRunMetrics): void {
+	target.durationMs += source.durationMs;
+	target.sessionId = source.sessionId ?? target.sessionId;
+	if (source.numTurns !== undefined) {
+		target.numTurns = (target.numTurns ?? 0) + source.numTurns;
+	}
+	if (source.costUsd !== undefined) {
+		target.costUsd = (target.costUsd ?? 0) + source.costUsd;
+	}
+	if (source.usage) {
+		target.usage = {
+			inputTokens:
+				(target.usage?.inputTokens ?? 0) + (source.usage.inputTokens ?? 0),
+			outputTokens:
+				(target.usage?.outputTokens ?? 0) + (source.usage.outputTokens ?? 0),
+			totalTokens:
+				(target.usage?.totalTokens ?? 0) + (source.usage.totalTokens ?? 0),
+			cacheReadInputTokens:
+				(target.usage?.cacheReadInputTokens ?? 0) +
+				(source.usage.cacheReadInputTokens ?? 0),
+		};
+	}
+}
+
+/** Resultado de falha de um watchdog. */
+function failedResult(
+	watchdogId: string,
+	error: string,
+	attempts: number,
+	metrics: MakiRunMetrics,
+): HuntWatchdogResult {
+	return {
+		watchdogId,
+		status: "failed",
+		findings: 0,
+		reviewedFiles: 0,
+		attempts,
+		durationMs: metrics.durationMs,
+		sessionId: metrics.sessionId,
+		numTurns: metrics.numTurns,
+		costUsd: metrics.costUsd,
+		usage: metrics.usage,
+		error,
+	};
+}
+
+/** Agrega os resultados por watchdog. */
+function totalsOf(watchdogs: readonly HuntWatchdogResult[]): HuntTotals {
+	const totals: HuntTotals = {
+		watchdogs: watchdogs.length,
+		done: 0,
+		failed: 0,
+		findings: 0,
+		costUsd: 0,
+		inputTokens: 0,
+		outputTokens: 0,
+		totalTokens: 0,
+	};
+	for (const watchdog of watchdogs) {
+		if (watchdog.status === "done") totals.done++;
+		else totals.failed++;
+		totals.findings += watchdog.findings;
+		totals.costUsd += watchdog.costUsd ?? 0;
+		totals.inputTokens += watchdog.usage?.inputTokens ?? 0;
+		totals.outputTokens += watchdog.usage?.outputTokens ?? 0;
+		totals.totalTokens += watchdog.usage?.totalTokens ?? 0;
+	}
+	totals.costUsd = Number(totals.costUsd.toFixed(6));
+	return totals;
+}