@payconductor/houndsman 0.7.0 → 0.10.0

package/src/core/technical-summary.ts

@@ -0,0 +1,398 @@
+/**
+ * Pontos técnicos estruturais do resumo final (`technical-summary.json`).
+ *
+ * Descrevem a arquitetura da mudança (módulos, contratos, implementações,
+ * dependências e impacto) — nunca os achados da revisão. A IA apenas refina a
+ * redação; sem ela, a heurística abaixo é o resultado final.
+ */
+
+import type { AstAnalysis, AstImpact, AstSymbol, AstSymbolKind } from "./ast/types";
+import type { ClassificationResult } from "./file-classifier";
+
+/** Destaque técnico exibido como um bullet do resumo. */
+export type TechnicalHighlight = {
+	/** Rótulo curto (ex.: "Contratos", "Implementações"). */
+	area: string;
+	/** Detalhe em uma linha, com paths/símbolos. */
+	detail: string;
+};
+
+/** Pontos técnicos de uma revisão. */
+export type TechnicalSummary = {
+	/** `ai` quando o texto veio do modelo; `deterministic` no fallback. */
+	source: "ai" | "deterministic";
+	/** Commit coberto — permite saber a que revisão o resumo se refere. */
+	headSha?: string;
+	/** Parágrafo curto de abertura (opcional). */
+	overview?: string;
+	highlights: TechnicalHighlight[];
+};
+
+/** Entrada mínima para montar os destaques. */
+export type TechnicalInput = {
+	classification: Pick<ClassificationResult, "files" | "churn">;
+	ast?: ReadonlyMap<string, AstAnalysis>;
+	impact?: AstImpact;
+	headSha?: string;
+};
+
+/** Entrada do payload enviado à IA (inclui contexto de negócio e domínios). */
+export type TechnicalPromptInput = TechnicalInput & {
+	branch: string;
+	context?: {
+		objective?: string;
+		motivation?: string;
+		changeSummary?: string[];
+	} | null;
+	domains?: readonly string[];
+};
+
+const MAX_HIGHLIGHTS = 6;
+const MAX_DETAIL = 240;
+
+/** Corta o texto em `max` caracteres, sinalizando com reticências. */
+function truncate(value: string, max: number): string {
+	const text = value.trim().replace(/\s+/g, " ");
+	return text.length <= max ? text : `${text.slice(0, max - 1).trimEnd()}…`;
+}
+
+/** Diretório do arquivo (`(raiz)` para paths sem pasta). */
+function moduleOf(path: string): string {
+	const slash = path.lastIndexOf("/");
+	return slash > 0 ? path.slice(0, slash) : "(raiz)";
+}
+
+/** `true` para pacotes externos (fora do projeto e de aliases locais). */
+function isExternal(source: string): boolean {
+	return (
+		!source.startsWith(".") &&
+		!source.startsWith("/") &&
+		!source.startsWith("#") &&
+		!source.startsWith("@/")
+	);
+}
+
+/** `true` para símbolos que representam contratos públicos. */
+function isContract(kind: AstSymbolKind): boolean {
+	return kind === "interface" || kind === "type" || kind === "enum";
+}
+
+type SymbolRef = { symbol: AstSymbol; file: string };
+
+/** Lista curta de símbolos com o arquivo de origem. */
+function symbolDetail(refs: SymbolRef[], max = 4): string {
+	const seen = new Set<string>();
+	const parts: string[] = [];
+	for (const ref of refs) {
+		const key = `${ref.file}|${ref.symbol.name}`;
+		if (seen.has(key)) continue;
+		seen.add(key);
+		parts.push(`\`${ref.symbol.name}\` (${ref.file})`);
+		if (parts.length === max) break;
+	}
+	const total = new Set(refs.map((ref) => `${ref.file}|${ref.symbol.name}`)).size;
+	return `${parts.join(", ")}${total > parts.length ? ` +${total - parts.length}` : ""}`;
+}
+
+type SignatureRef = {
+	name: string;
+	before: string;
+	after: string;
+	file: string;
+};
+
+/** Assinaturas alteradas, com o `antes → depois`. */
+function signatureDetail(changes: SignatureRef[], max = 3): string {
+	return changes
+		.slice(0, max)
+		.map(
+			(change) =>
+				`\`${change.name}\` (${truncate(change.before, 60)} → ${truncate(change.after, 60)})`,
+		)
+		.join(", ");
+}
+
+type ExportRef = {
+	name: string;
+	change: "added" | "removed";
+	file: string;
+};
+
+type PromptSymbolRef = { name: string; kind: string; file: string };
+
+/** Exports adicionados/removidos, com o arquivo. */
+function exportDetail(changes: ExportRef[], max = 4): string {
+	return changes
+		.slice(0, max)
+		.map((change) => `\`${change.name}\` (${change.change}, ${change.file})`)
+		.join(", ");
+}
+
+/** Agrupa paths por diretório, do maior para o menor grupo. */
+function groupByModule(paths: string[]): [string, number][] {
+	const counts = new Map<string, number>();
+	for (const path of paths) {
+		const dir = moduleOf(path);
+		counts.set(dir, (counts.get(dir) ?? 0) + 1);
+	}
+	return [...counts.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]));
+}
+
+/**
+ * Monta os destaques determinísticos. Prioriza símbolos do AST; sem fatos
+ * estruturais, agrupa os arquivos novos por diretório. Nunca lança.
+ */
+export function buildTechnicalSummary(input: TechnicalInput): TechnicalSummary {
+	const highlights: TechnicalHighlight[] = [];
+	const files = input.classification.files;
+	const added = Object.entries(files)
+		.filter(([, file]) => file.status === "added")
+		.map(([path]) => path);
+	const deleted = Object.entries(files)
+		.filter(([, file]) => file.status === "deleted")
+		.map(([path]) => path);
+
+	const contracts: SymbolRef[] = [];
+	const implementations: SymbolRef[] = [];
+	const functions: SymbolRef[] = [];
+	const signatures: SignatureRef[] = [];
+	const exportsChanged: ExportRef[] = [];
+	const imports = new Set<string>();
+
+	if (input.ast) {
+		for (const [file, analysis] of input.ast) {
+			const delta = analysis.delta;
+			if (!delta) continue;
+			for (const symbol of delta.addedSymbols) {
+				if (isContract(symbol.kind)) contracts.push({ symbol, file });
+				else if (symbol.kind === "class") implementations.push({ symbol, file });
+				else if (symbol.kind === "function") functions.push({ symbol, file });
+			}
+			for (const change of delta.changedSignatures) {
+				if (!change.exported) continue;
+				signatures.push({
+					name: change.name,
+					before: change.before,
+					after: change.after,
+					file,
+				});
+			}
+			for (const change of delta.changedExports) {
+				exportsChanged.push({
+					name: change.name,
+					change: change.change,
+					file,
+				});
+			}
+			for (const source of delta.addedImports) {
+				if (isExternal(source)) imports.add(source);
+			}
+		}
+	}
+
+	if (contracts.length > 0) {
+		highlights.push({ area: "Contratos", detail: symbolDetail(contracts) });
+	}
+	if (implementations.length > 0) {
+		highlights.push({
+			area: "Implementações",
+			detail: symbolDetail(implementations),
+		});
+	}
+	if (functions.length > 0 && contracts.length === 0 && implementations.length === 0) {
+		highlights.push({ area: "Funções", detail: symbolDetail(functions) });
+	}
+	if (signatures.length > 0) {
+		highlights.push({
+			area: "Assinaturas alteradas",
+			detail: signatureDetail(signatures),
+		});
+	}
+	if (exportsChanged.length > 0) {
+		highlights.push({
+			area: "Exports alterados",
+			detail: exportDetail(exportsChanged),
+		});
+	}
+	if (imports.size > 0) {
+		highlights.push({
+			area: "Novas dependências",
+			detail: [...imports]
+				.slice(0, 6)
+				.map((source) => `\`${source}\``)
+				.join(", "),
+		});
+	}
+
+	// Sem fatos do AST, a estrutura visível é o conjunto de diretórios novos.
+	if (highlights.length === 0) {
+		for (const [dir, count] of groupByModule(added).slice(0, 3)) {
+			highlights.push({
+				area: "Estrutura",
+				detail: `Novo diretório \`${dir}\` com ${count} arquivo(s).`,
+			});
+		}
+	}
+
+	if (deleted.length > 0 && highlights.length < MAX_HIGHLIGHTS) {
+		highlights.push({
+			area: "Remoções",
+			detail: `${deleted
+				.slice(0, 4)
+				.map((path) => `\`${path}\``)
+				.join(", ")}${deleted.length > 4 ? ` +${deleted.length - 4}` : ""}`,
+		});
+	}
+
+	if (
+		input.impact &&
+		input.impact.affectedFiles.length > 0 &&
+		highlights.length < MAX_HIGHLIGHTS
+	) {
+		const exported = input.impact.exportedChanges.length;
+		highlights.push({
+			area: "Impacto",
+			detail:
+				`${input.impact.affectedFiles.length} arquivo(s) importam os alterados` +
+				(exported > 0 ? `; ${exported} export(s) público(s) alterado(s)` : "") +
+				".",
+		});
+	}
+
+	return {
+		source: "deterministic",
+		headSha: input.headSha,
+		highlights: highlights.slice(0, MAX_HIGHLIGHTS).map((highlight) => ({
+			area: truncate(highlight.area, 80),
+			detail: truncate(highlight.detail, MAX_DETAIL),
+		})),
+	};
+}
+
+/** Payload compacto enviado ao modelo (nunca arquivos inteiros). */
+export function buildTechnicalPromptPayload(
+	input: TechnicalPromptInput,
+): Record<string, unknown> {
+	const files = Object.entries(input.classification.files)
+		.map(([path, file]) => ({
+			path,
+			status: file.status,
+			additions: input.classification.churn[path]?.additions ?? 0,
+			deletions: input.classification.churn[path]?.deletions ?? 0,
+		}))
+		.sort(
+			(a, b) =>
+				b.additions + b.deletions - (a.additions + a.deletions) ||
+				a.path.localeCompare(b.path),
+		)
+		.slice(0, 80);
+
+	const contracts: PromptSymbolRef[] = [];
+	const implementations: PromptSymbolRef[] = [];
+	const signatures: SignatureRef[] = [];
+	const exportsChanged: ExportRef[] = [];
+	const imports = new Set<string>();
+	const deletedFiles: string[] = [];
+
+	for (const [path, file] of Object.entries(input.classification.files)) {
+		if (file.status === "deleted") deletedFiles.push(path);
+	}
+
+	if (input.ast) {
+		for (const [file, analysis] of input.ast) {
+			const delta = analysis.delta;
+			if (!delta) continue;
+			for (const symbol of delta.addedSymbols) {
+				if (isContract(symbol.kind)) {
+					contracts.push({ name: symbol.name, kind: symbol.kind, file });
+				} else if (symbol.kind === "class") {
+					implementations.push({ name: symbol.name, kind: symbol.kind, file });
+				}
+			}
+			for (const change of delta.changedSignatures) {
+				if (change.exported) {
+					signatures.push({
+						name: change.name,
+						before: change.before,
+						after: change.after,
+						file,
+					});
+				}
+			}
+			for (const change of delta.changedExports) {
+				exportsChanged.push({
+					name: change.name,
+					change: change.change,
+					file,
+				});
+			}
+			for (const source of delta.addedImports) {
+				if (isExternal(source)) imports.add(source);
+			}
+		}
+	}
+
+	return {
+		branch: input.branch,
+		headSha: input.headSha,
+		business: input.context
+			? {
+					objective: input.context.objective,
+					motivation: input.context.motivation,
+					changeSummary: input.context.changeSummary,
+				}
+			: undefined,
+		domains: input.domains ?? [],
+		files,
+		structure: {
+			contracts: contracts.slice(0, 40),
+			implementations: implementations.slice(0, 40),
+			changedSignatures: signatures.slice(0, 20),
+			changedExports: exportsChanged.slice(0, 20),
+			addedImports: [...imports].slice(0, 20),
+			deletedFiles: deletedFiles.slice(0, 20),
+		},
+		impact: input.impact
+			? {
+					affectedFiles: input.impact.affectedFiles.length,
+					importers: Object.keys(input.impact.importers).length,
+					exportedChanges: input.impact.exportedChanges.length,
+				}
+			: undefined,
+	};
+}
+
+/** Valida/normaliza o `technical-summary.json`; null quando vazio/inválido. */
+export function parseTechnicalSummary(raw: unknown): TechnicalSummary | null {
+	if (typeof raw !== "object" || raw === null) return null;
+	const obj = raw as Record<string, unknown>;
+
+	const highlights: TechnicalHighlight[] = [];
+	if (Array.isArray(obj.highlights)) {
+		for (const item of obj.highlights) {
+			if (typeof item !== "object" || item === null) continue;
+			const entry = item as Record<string, unknown>;
+			const area = typeof entry.area === "string" ? entry.area.trim() : "";
+			const detail = typeof entry.detail === "string" ? entry.detail.trim() : "";
+			if (!area || !detail) continue;
+			highlights.push({
+				area: truncate(area, 80),
+				detail: truncate(detail, MAX_DETAIL),
+			});
+			if (highlights.length === MAX_HIGHLIGHTS) break;
+		}
+	}
+
+	const overview =
+		typeof obj.overview === "string" && obj.overview.trim().length > 0
+			? truncate(obj.overview, 600)
+			: undefined;
+	if (highlights.length === 0 && !overview) return null;
+
+	return {
+		source: obj.source === "deterministic" ? "deterministic" : "ai",
+		headSha: typeof obj.headSha === "string" ? obj.headSha : undefined,
+		overview,
+		highlights,
+	};
+}

package/src/core/types.ts

@@ -135,6 +135,8 @@ export type WatchdogRenderArgs = {
 	branch: string;
 	outputPath: string;
 	outputFormatPath: string;
+	/** Worktree onde a review roda (ausente = clone principal). */
+	worktree?: string;
 	docs: readonly string[];
 	context?: WatchdogRenderContext | null;
 	candidates?: readonly WatchdogRenderCandidate[];

package/src/harness/agent/agent-factory.ts

@@ -37,6 +37,7 @@ export class AgentFactory {
 			reporter: this.deps.reporter,
 			maxOutputTokens: config.maxOutputTokensFor(context.watchdog.id),
 			temperature: config.temperature,
+			providerOptions: config.providerOptions,
 			timeoutMs: config.timeoutMs,
 			ast: this.deps.ast,
 			readFile: this.deps.readFile,

package/src/harness/agent/review-agent.ts

@@ -8,7 +8,13 @@
 
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
-import { type AiUsage, addUsage, emptyUsage, type ModelProvider } from "../../core/ai";
+import {
+	type AiProviderOptions,
+	type AiUsage,
+	addUsage,
+	emptyUsage,
+	type ModelProvider,
+} from "../../core/ai";
 import type { AstService } from "../../core/ast/service";
 import type { WatchdogReport } from "../../core/report-builder";
 import type { Severity } from "../../core/types";
@@ -49,6 +55,7 @@ export type ReviewAgentDeps = {
 	reporter: AgentReporter;
 	maxOutputTokens: number;
 	temperature: number;
+	providerOptions?: AiProviderOptions;
 	timeoutMs: number;
 	ast: AstService;
 	readFile?: (path: string) => string | null;
@@ -338,6 +345,9 @@ export class ReviewAgent {
 			maxSteps,
 			maxOutputTokens: this.deps.maxOutputTokens,
 			temperature: this.deps.temperature,
+			...(this.deps.providerOptions
+				? { providerOptions: this.deps.providerOptions }
+				: {}),
 			signal: AbortSignal.timeout(this.deps.timeoutMs),
 		});
 		this.usage = addUsage(this.usage, response.usage);

package/src/harness/config/harness-config.ts

@@ -5,7 +5,7 @@
  * aplica apenas overrides de execução (`hunt --model`, `--max-calls`, etc.).
  */
 
-import type { AiProviderKind } from "../../core/config";
+import type { AiProviderKind, AiProviderOptions } from "../../core/config";
 import { ProjectConfig } from "../../core/project-config";
 
 /** Overrides de execução do harness. */
@@ -76,6 +76,11 @@ export class HarnessConfig {
 	get temperature(): number {
 		return this.project.aiTemperature;
 	}
+
+	/** Opções do AI SDK por provider (config do projeto, sem override de flag). */
+	get providerOptions(): AiProviderOptions | undefined {
+		return this.project.aiProviderOptions;
+	}
 }
 
 /** Inteiro positivo ou o default. */

package/src/harness/hunt/hunt-options.ts

@@ -24,6 +24,12 @@ export type HuntOptions = {
 	concurrency?: number;
 	provider?: AiProviderKind;
 	model?: string;
+	/** Número da PR (`--pr`) — o comando resolve/cria o worktree. */
+	pr?: number;
+	/** Worktree informado via flag (relativo ao cwd ou absoluto). */
+	worktree?: string;
+	/** Worktree resolvido (absoluto) para persistir na review. */
+	worktreePath?: string;
 };
 
 /** Defaults do hunt. */
@@ -54,6 +60,17 @@ export function parseHuntArgs(args: string[]): HuntOptions {
 	const model = parser.value("--model");
 	const maxCalls = parser.value("--max-calls");
 	const concurrency = parser.value("--concurrency");
+	const pr = parser.value("--pr");
+	const worktree = parser.value("--worktree");
+	if (pr) {
+		const number = Number.parseInt(pr, 10);
+		if (Number.isFinite(number) && number > 0) options.pr = number;
+		else throw new Error(`--pr inválido: '${pr}'.`);
+	}
+	if (worktree) options.worktree = worktree;
+	if (options.pr !== undefined && options.worktree !== undefined) {
+		throw new Error("Use --pr ou --worktree, não os dois.");
+	}
 	if (base) options.base = base;
 	if (head) options.head = head;
 	if (branch) options.branch = branch;

package/src/harness/hunt/hunt-session.ts

@@ -14,11 +14,9 @@ import {
 	type ModelProvider,
 } from "../../core/ai";
 import type { AstAnalysis } from "../../core/ast/types";
-import { collectDiff } from "../../core/diff-source";
 import type { HoundsmanEngine } from "../../core/engine/houndsman-engine";
 import type { RunClassification } from "../../core/engine/review-scope";
 import { parseEntries } from "../../core/file-classifier";
-import { runGit, tryGit } from "../../core/git-runner";
 import type { LoggerLike } from "../../core/logging";
 import type { PrepareResult } from "../../core/orchestrator";
 import { defaultOptions, type ReviewOptions } from "../../core/orchestrator";
@@ -67,6 +65,8 @@ export class HuntSession {
 			clean: options.clean,
 			noAi: true,
 			finalize: false,
+			pr: options.pr,
+			worktreePath: options.worktreePath,
 		};
 
 		const session = engine.session(reviewOptions);
@@ -137,7 +137,7 @@ export class HuntSession {
 			reporter,
 			config: this.deps.config,
 			ast: engine.ast,
-			readFile: defaultFileReader(fileRoot()),
+			readFile: defaultFileReader(engine.root),
 		});
 		const runner = new AgentRunner(factory);
 		const scheduler = new AgentScheduler(
@@ -265,11 +265,11 @@ export class HuntSession {
 		work: import("../../core/storage/work-area").ReviewWorkArea,
 	) {
 		const { engine, options } = this.deps;
-		const diff = collectDiff(options.base, options.head);
+		const diff = engine.git.collectDiff(options.base, options.head);
 		const entries = parseEntries(
-			runGit(["diff", `${options.base}...${options.head}`, "--name-status"]),
+			engine.git.diffNameStatus(options.base, options.head),
 		);
-		const baseRef = mergeBase(options.base, options.head) ?? options.base;
+		const baseRef = engine.git.mergeBase(options.base, options.head) ?? options.base;
 		const ast: Map<string, AstAnalysis> = options.noAst
 			? new Map()
 			: await engine.ast.analyze(entries, diff, baseRef);
@@ -283,7 +283,7 @@ export class HuntSession {
 			context,
 			ast,
 			impact,
-			repoRoot: process.cwd(),
+			repoRoot: engine.root,
 			diff,
 			branch: review.branch,
 			watchdog: options.watchdog,
@@ -357,16 +357,3 @@ function readContextSummary(
 		return null;
 	}
 }
-
-/** Merge-base best effort. */
-function mergeBase(base: string, head: string): string | null {
-	const result = tryGit(["merge-base", base, head]);
-	if (!result.ok) return null;
-	const sha = result.stdout.trim();
-	return sha.length > 0 ? sha : null;
-}
-
-/** Raiz do repositório para leitura das tools. */
-function fileRoot(): string {
-	return process.cwd();
-}

package/src/index.ts

@@ -49,6 +49,7 @@ export { runFindingsCommand, runVerifyCommand } from "./core/commands/findings";
 export { ProjectScaffolder } from "./core/commands/scaffold";
 export type {
 	AiProviderKind,
+	AiProviderOptions,
 	HoundsmanAi,
 	HoundsmanAiFeatures,
 	HoundsmanAst,
@@ -89,6 +90,14 @@ export { buildCarryover, mergeCarryover } from "./core/engine/carryover";
 export { HoundsmanEngine } from "./core/engine/houndsman-engine";
 export { ReviewScopeResolver } from "./core/engine/review-scope";
 export { ReviewSession } from "./core/engine/review-session";
+export type {
+	ResolvedWorkspace,
+	WorkspaceRequest,
+} from "./core/engine/review-workspace";
+export {
+	mainRootOf,
+	resolveReviewWorkspace,
+} from "./core/engine/review-workspace";
 export type { HoundsmanEnv } from "./core/env";
 export { ENV_NAMES, env, readEnv } from "./core/env";
 export {
@@ -171,8 +180,27 @@ export { FixBatchBuilder } from "./core/services/fix-batch-builder";
 export type { GhResult, GhRunner } from "./core/services/gh-client";
 export { GhClient } from "./core/services/gh-client";
 export { GitRepository } from "./core/services/git-repository";
+export type {
+	PrRefs,
+	PrResolveResult,
+	PullRequestInfo,
+} from "./core/services/pr-resolver";
+export { PrResolver } from "./core/services/pr-resolver";
 export { ProjectFiles } from "./core/services/project-files";
 export { Verifier } from "./core/services/verifier";
+export type {
+	EnsureWorktreeInput,
+	EnsureWorktreeResult,
+	RemoveWorktreeResult,
+	WorktreeEntry,
+	WorktreeManagerOptions,
+} from "./core/services/worktree-manager";
+export {
+	branchSlug,
+	parseWorktreeList,
+	repoSlug,
+	WorktreeManager,
+} from "./core/services/worktree-manager";
 export {
 	createMemoryStorage,
 	createStorage,
@@ -226,4 +254,9 @@ export {
 } from "./core/watchdog-registry";
 export type { ServerOptions } from "./server";
 export { createRequestHandler, HoundsmanServer, startServer } from "./server";
+export type {
+	DeleteRunResult,
+	RunDetail,
+	RunListItem,
+} from "./server/run-repository";
 export { RunRepository } from "./server/run-repository";