@payconductor/houndsman 0.6.0 → 0.8.0

package/src/core/orchestrator.ts

@@ -16,13 +16,15 @@
  * review.<watchdog>.md, context e context-summary.
  */
 
-import { readFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
 import type { AiClient } from "./ai/ai-client";
 import { AiBriefEnricher } from "./ai/features/brief-enricher";
 import { AiClassifier } from "./ai/features/classifier";
 import { AiContextSummarizer } from "./ai/features/context-summarizer";
 import { AiPreAnalyzer } from "./ai/features/pre-analyzer";
 import type { BriefPlan } from "./ai/schemas";
+import { assetPath, OUTPUT_FORMAT_FILE } from "./assets";
 import type { AstService } from "./ast/service";
 import type { AstAnalysis, AstFileBrief, AstImpact } from "./ast/types";
 import {
@@ -39,7 +41,6 @@ import { ReviewScopeResolver, type RunClassification } from "./engine/review-sco
 import { ENV_NAMES } from "./env";
 import type { BudgetSelection, ClassificationResult } from "./file-classifier";
 import { buildStateFromFindings, fileReader } from "./findings-state";
-import { resolveSha } from "./git-revision";
 import { syncResolvedThreads } from "./github-review";
 import {
 	type JevCandidate,
@@ -56,7 +57,6 @@ import {
 	REVIEW_FILE,
 	REVIEW_RESUME_FILE,
 } from "./paths";
-import { currentBranch } from "./pr-context";
 import { ProjectConfig } from "./project-config";
 import { BriefRenderer } from "./renderers/brief-renderer";
 import {
@@ -76,6 +76,7 @@ import {
 } from "./report-builder";
 import { writeRunStatus } from "./run-status";
 import { systemClock } from "./services/clock";
+import { GitRepository } from "./services/git-repository";
 import type { ReviewRecord, StorageProvider } from "./storage/types";
 import { ReviewWorkArea } from "./storage/work-area";
 import type { WatchdogMeta } from "./types";
@@ -95,6 +96,12 @@ export type ReviewOptions = {
 	full: boolean;
 	/** Desativa as features de IA do fluxo normal (hunt não usa esta flag). */
 	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). */
@@ -112,19 +119,49 @@ export function defaultOptions(): ReviewOptions {
 	};
 }
 
-/** Contexto de uma run: storage + review + staging. */
+/** 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;
 };
 
 /** Cria o contexto de uma review existente. */
 export function reviewContext(
 	storage: StorageProvider,
 	review: ReviewRecord,
+	workspace: ReviewWorkspaceContext = {},
 ): ReviewContext {
-	return { storage, review, work: new ReviewWorkArea(review) };
+	const root = workspace.root ?? process.cwd();
+	return {
+		storage,
+		review,
+		work: new ReviewWorkArea(review),
+		root,
+		mainRoot: workspace.mainRoot ?? root,
+		git: workspace.git ?? new GitRepository(),
+	};
+}
+
+/**
+ * Schema do output: relativo à raiz da review quando a camada existe; no
+ * worktree sem camada, cai para o asset embarcado (caminho absoluto legível).
+ */
+function outputFormatPathFor(ctx: ReviewContext): string {
+	if (existsSync(join(ctx.root, OUTPUT_FORMAT_PATH))) return OUTPUT_FORMAT_PATH;
+	return ctx.review.worktreePath ? assetPath(OUTPUT_FORMAT_FILE) : OUTPUT_FORMAT_PATH;
 }
 
 // ---------------------------------------------------------------------------
@@ -225,7 +262,8 @@ function writeBriefs(
 			deleted: classification.deleted,
 			branch,
 			outputPath: work.findingFile(id),
-			outputFormatPath: OUTPUT_FORMAT_PATH,
+			outputFormatPath: outputFormatPathFor(ctx),
+			worktree: ctx.review.worktreePath,
 			docs,
 			context,
 			candidates: candidates.filter((c) => c.watchdogId === id),
@@ -277,7 +315,7 @@ async function resolveCandidates(
 				const def = findWatchdog(config, id);
 				if (!def) continue;
 				const inputs = files.slice(0, 5).flatMap((file) => {
-					const snippet = readSnippet(file);
+					const snippet = readSnippet(ctx.root, file);
 					return snippet ? [{ file, snippet }] : [];
 				});
 				candidates.push(
@@ -314,6 +352,7 @@ async function resolveCandidates(
 		const detector = new JevDetector(
 			client,
 			config.watchdogs as Record<string, WatchdogMeta>,
+			ctx.root,
 		);
 		const result = await detector.detect(classification, opts.base, opts.head, {
 			diff,
@@ -377,9 +416,10 @@ function budgetMessage(
 }
 
 /** Primeiras 80 linhas de um arquivo (pré-análise por IA; fail-open). */
-function readSnippet(file: string): string | null {
+function readSnippet(root: string, file: string): string | null {
 	try {
-		return readFileSync(file, "utf8").split("\n").slice(0, 80).join("\n");
+		const path = join(root, file);
+		return readFileSync(path, "utf8").split("\n").slice(0, 80).join("\n");
 	} catch {
 		return null;
 	}
@@ -507,12 +547,13 @@ export async function prepare(
 	ctx.storage.updateReview(ctx.review.id, { base: opts.base, head: opts.head });
 
 	// Marca o commit revisado e decide entre completo, incremental ou no-op.
-	const headSha = resolveSha(opts.head);
+	const headSha = ctx.git.resolveSha(opts.head);
 	const previous = ctx.storage.readFindings(ctx.review.id);
 	const scope = await new ReviewScopeResolver(
 		opts,
 		config,
 		opts.noAst ? undefined : ast,
+		ctx.git,
 	).resolve(previous, headSha);
 
 	// Mesmo commit já revisado: preserva artefatos e triagem, sem re-revisar.
@@ -937,7 +978,7 @@ export function finalize(
 	// (`reviewed.headSha`) habilita o review incremental e o diff focado do verify.
 	const state = buildStateFromFindings(merged, {
 		branch,
-		readFile: fileReader(process.cwd()),
+		readFile: fileReader(ctx.root),
 		previous: ctx.storage.readFindings(ctx.review.id),
 		reviewedPaths: new Set([
 			...reports.flatMap((report) => report.reviewedFiles),
@@ -1042,6 +1083,14 @@ export function finalize(
 }
 
 /** Resolve a branch (opção explícita ou a atual do git). */
-export function resolveBranch(opts: ReviewOptions): string {
-	return opts.branch ?? currentBranch();
+export function resolveBranch(
+	opts: ReviewOptions,
+	git: GitRepository = new GitRepository(),
+): string {
+	if (opts.branch) return opts.branch;
+	const branch = git.currentBranch();
+	if (!branch) {
+		throw new Error("Não foi possível detectar a branch. Use --branch <nome>.");
+	}
+	return branch;
 }

package/src/core/project-config.ts

@@ -13,6 +13,7 @@ import type {
 	HoundsmanAst,
 	HoundsmanConfig,
 	HoundsmanStorage,
+	HoundsmanWorktrees,
 } from "./config";
 import {
 	DEFAULT_AI_CONCURRENCY,
@@ -27,6 +28,7 @@ import {
 	DEFAULT_AST_MAX_IMPACT_FILES,
 	DEFAULT_JEV_CONCURRENCY,
 	DEFAULT_MAX_FILES_PER_BRIEF,
+	DEFAULT_WORKTREES_LOCATION,
 } from "./defaults";
 import { WatchdogRegistry } from "./watchdog-registry";
 
@@ -48,6 +50,16 @@ export class ProjectConfig<TId extends string = string> {
 		return this.raw.storage ?? {};
 	}
 
+	/** Config de worktrees (objeto vazio quando ausente). */
+	get worktrees(): HoundsmanWorktrees {
+		return this.raw.worktrees ?? {};
+	}
+
+	/** Localização dos worktrees resolvida (default: workspace). */
+	get worktreesLocation(): string {
+		return this.worktrees.location?.trim() || DEFAULT_WORKTREES_LOCATION;
+	}
+
 	/** Config do AST (objeto vazio quando ausente). */
 	get ast(): HoundsmanAst {
 		return this.raw.ast ?? {};

package/src/core/services/gh-client.ts

@@ -10,29 +10,45 @@ export type GhResult = { ok: boolean; code: number; stdout: string; stderr: stri
 /** Executa o `gh` e devolve o resultado cru (sem lançar). */
 export type GhRunner = (args: string[]) => GhResult;
 
-/** Runner padrão: `gh` a partir do cwd; ausência do binário → `ok:false`. */
-export const defaultGhRunner: GhRunner = (args) => {
-	try {
-		const result = Bun.spawnSync(["gh", ...args], {
-			stdout: "pipe",
-			stderr: "pipe",
-		});
-		const code = result.exitCode ?? 1;
-		return {
-			ok: code === 0,
-			code,
-			stdout: new TextDecoder().decode(result.stdout).trim(),
-			stderr: new TextDecoder().decode(result.stderr).trim(),
-		};
-	} catch (error) {
-		return {
-			ok: false,
-			code: 127,
-			stdout: "",
-			stderr: error instanceof Error ? error.message : String(error),
-		};
+/** Mensagem curta para um erro do `gh` (sem expor o stderr inteiro). */
+export function describeGhError(result: GhResult): string {
+	if (result.code === 127 || /not found|ENOENT/i.test(result.stderr)) {
+		return "gh não instalado.";
 	}
-};
+	const last = result.stderr.split("\n").filter(Boolean).pop() ?? "";
+	if (/auth|login|logged/i.test(last)) return `gh sem autenticação (${last}).`;
+	return last || `gh saiu com código ${result.code}.`;
+}
+
+/** Cria um runner do `gh` com diretório de trabalho fixo. */
+export function createGhRunner(cwd?: string): GhRunner {
+	return (args) => {
+		try {
+			const result = Bun.spawnSync(["gh", ...args], {
+				cwd,
+				stdout: "pipe",
+				stderr: "pipe",
+			});
+			const code = result.exitCode ?? 1;
+			return {
+				ok: code === 0,
+				code,
+				stdout: new TextDecoder().decode(result.stdout).trim(),
+				stderr: new TextDecoder().decode(result.stderr).trim(),
+			};
+		} catch (error) {
+			return {
+				ok: false,
+				code: 127,
+				stdout: "",
+				stderr: error instanceof Error ? error.message : String(error),
+			};
+		}
+	};
+}
+
+/** Runner padrão: `gh` a partir do cwd; ausência do binário → `ok:false`. */
+export const defaultGhRunner: GhRunner = createGhRunner();
 
 /** Superfície OO sobre o runner injetável. */
 export class GhClient {

package/src/core/services/git-repository.ts

@@ -75,6 +75,52 @@ export class GitRepository {
 	isAncestor(ancestor: string, descendant: string): boolean {
 		return this.tryRun(["merge-base", "--is-ancestor", ancestor, descendant]).ok;
 	}
+	/** SHA do merge-base entre duas refs; `null` quando não há ancestral comum. */
+	mergeBase(base: string, head: string): string | null {
+		const result = this.tryRun(["merge-base", base, head]);
+		const sha = result.ok ? result.stdout.trim() : "";
+		return sha.length > 0 ? sha : null;
+	}
+
+	/**
+	 * Diretório git comum (`.git`) em caminho absoluto. Em um worktree linkado
+	 * aponta para o `.git` do clone principal — é como descobrimos a raiz real.
+	 */
+	gitCommonDir(): string | null {
+		const result = this.tryRun([
+			"rev-parse",
+			"--path-format=absolute",
+			"--git-common-dir",
+		]);
+		const dir = result.ok ? result.stdout.trim() : "";
+		return dir.length > 0 ? dir : null;
+	}
+
+	/** Saída crua de `git worktree list --porcelain` (vazia em erro). */
+	worktreeListRaw(): string {
+		const result = this.tryRun(["worktree", "list", "--porcelain"]);
+		return result.ok ? result.stdout : "";
+	}
+
+	/** Cria um worktree detached apontando para `ref` (lança em falha). */
+	addWorktree(path: string, ref: string): string {
+		return this.run(["worktree", "add", "--detach", path, ref]);
+	}
+
+	/** Remove um worktree; nunca lança (devolve o resultado para o chamador). */
+	removeWorktree(path: string, force = false): GitResult {
+		return this.tryRun(["worktree", "remove", ...(force ? ["--force"] : []), path]);
+	}
+
+	/** Remove metadados de worktrees cujo diretório sumiu. */
+	pruneWorktrees(): GitResult {
+		return this.tryRun(["worktree", "prune"]);
+	}
+
+	/** `git fetch --no-tags <remote> <refspecs...>` (nunca lança). */
+	fetch(remote: string, refspecs: readonly string[]): GitResult {
+		return this.tryRun(["fetch", "--no-tags", remote, ...refspecs]);
+	}
 
 	/** Conteúdo de um arquivo num commit; `null` se ausente. */
 	readFileAt(sha: string, path: string): string | null {

package/src/core/services/pr-resolver.ts

@@ -0,0 +1,147 @@
+/**
+ * Resolução de uma PR para revisão (biblioteca).
+ *
+ * Usa `gh pr view` para descobrir head/base e garante os commits localmente.
+ * O head é buscado em `refs/pull/<n>/head`, que funciona também para forks;
+ * o base vem de `origin/<baseRefName>`. Fail-open na leitura, mas a revisão só
+ * começa quando as refs necessárias existem (erro explícito caso contrário).
+ */
+
+import { describeGhError, type GhRunner } from "./gh-client";
+import type { GitRepository } from "./git-repository";
+
+const PR_FIELDS =
+	"number,title,headRefName,baseRefName,headRefOid,isCrossRepository,url,isDraft";
+
+/** Dados mínimos de uma PR para montar o worktree. */
+export type PullRequestInfo = {
+	number: number;
+	title?: string;
+	headRefName: string;
+	baseRefName: string;
+	/** Commit exato do head no momento da consulta. */
+	headSha?: string;
+	isCrossRepository: boolean;
+	isDraft: boolean;
+	url?: string;
+};
+
+/** Resultado da consulta ao `gh`. */
+export type PrResolveResult =
+	| { ok: true; pr: PullRequestInfo }
+	| { ok: false; reason: "gh" | "invalid"; detail: string };
+
+/** Refs locais preparadas para o diff. */
+export type PrRefs = {
+	base: string;
+	head: string;
+	/** `true` quando o fetch trouxe algo novo. */
+	fetched: boolean;
+	/** Aviso (ex.: fetch parcial) para o CLI imprimir. */
+	warning?: string;
+};
+
+type GhPrView = {
+	number?: unknown;
+	title?: unknown;
+	headRefName?: unknown;
+	baseRefName?: unknown;
+	headRefOid?: unknown;
+	isCrossRepository?: unknown;
+	isDraft?: unknown;
+	url?: unknown;
+};
+
+/** Cliente de PR sobre um runner injetável. */
+export class PrResolver {
+	constructor(
+		private readonly runner: GhRunner,
+		private readonly git: GitRepository,
+	) {}
+
+	/** Consulta a PR no GitHub (nunca lança). */
+	resolve(number: number): PrResolveResult {
+		const result = this.runner(["pr", "view", String(number), "--json", PR_FIELDS]);
+		if (!result.ok) {
+			return { ok: false, reason: "gh", detail: describeGhError(result) };
+		}
+
+		let parsed: GhPrView;
+		try {
+			parsed = JSON.parse(result.stdout) as GhPrView;
+		} catch {
+			return {
+				ok: false,
+				reason: "invalid",
+				detail: "Resposta inválida do gh (JSON malformado).",
+			};
+		}
+
+		const headRefName =
+			typeof parsed.headRefName === "string" ? parsed.headRefName.trim() : "";
+		const baseRefName =
+			typeof parsed.baseRefName === "string" ? parsed.baseRefName.trim() : "";
+		const resolvedNumber = Number(parsed.number);
+		if (
+			!Number.isFinite(resolvedNumber) ||
+			resolvedNumber <= 0 ||
+			headRefName.length === 0 ||
+			baseRefName.length === 0
+		) {
+			return {
+				ok: false,
+				reason: "invalid",
+				detail: "gh não devolveu número/head/base da PR.",
+			};
+		}
+
+		return {
+			ok: true,
+			pr: {
+				number: resolvedNumber,
+				title: typeof parsed.title === "string" ? parsed.title : undefined,
+				headRefName,
+				baseRefName,
+				headSha:
+					typeof parsed.headRefOid === "string"
+						? parsed.headRefOid.trim()
+						: undefined,
+				isCrossRepository: Boolean(parsed.isCrossRepository),
+				isDraft: Boolean(parsed.isDraft),
+				url: typeof parsed.url === "string" ? parsed.url : undefined,
+			},
+		};
+	}
+
+	/**
+	 * Garante base/head da PR no repositório local.
+	 *
+	 * Prefere o SHA informado pelo `gh`; cai para `refs/houndsman/pr-<n>` quando
+	 * o objeto não existe localmente.
+	 */
+	prepareRefs(pr: PullRequestInfo): PrRefs {
+		const headRef = `refs/houndsman/pr-${pr.number}`;
+		const headFetch = this.git.fetch("origin", [
+			`+refs/pull/${pr.number}/head:${headRef}`,
+		]);
+		const baseFetch = this.git.fetch("origin", [pr.baseRefName]);
+
+		const originBase = `origin/${pr.baseRefName}`;
+		const hasOriginBase = this.git.tryRun(["rev-parse", "--verify", originBase]).ok;
+		const base = hasOriginBase ? originBase : pr.baseRefName;
+
+		const hasSha = pr.headSha
+			? this.git.tryRun(["cat-file", "-e", `${pr.headSha}^{commit}`]).ok
+			: false;
+		const head = hasSha && pr.headSha ? pr.headSha : headRef;
+
+		const warning =
+			!headFetch.ok && !hasSha
+				? `Não foi possível buscar o head da PR: ${headFetch.stderr.trim()}`
+				: !baseFetch.ok
+					? `Não foi possível atualizar ${pr.baseRefName}: ${baseFetch.stderr.trim()}`
+					: undefined;
+
+		return { base, head, fetched: headFetch.ok || baseFetch.ok, warning };
+	}
+}