@payconductor/houndsman 0.6.0 → 0.8.0

package/src/core/defaults.ts

@@ -19,6 +19,13 @@ export const DEFAULT_MAX_FILES_PER_BRIEF = 40;
 /** Concorrência default das chamadas simultâneas ao Jev. */
 export const DEFAULT_JEV_CONCURRENCY = 5;
 
+/**
+ * Localização default dos worktrees: dentro do workspace aberto no editor.
+ * Mantém leitura/execução dentro da pasta do projeto — agentes com permissão
+ * escopada ao workspace não pedem autorização a cada acesso.
+ */
+export const DEFAULT_WORKTREES_LOCATION = "workspace";
+
 /** Teto default de bytes por arquivo no AST (evita bundles/minificados). */
 export const DEFAULT_AST_MAX_FILE_BYTES = 512_000;
 
@@ -29,7 +36,7 @@ export const DEFAULT_AST_MAX_IMPACT_FILES = 200;
 export const DEFAULT_AI_PROVIDER = "deepseek" as const;
 
 /** Modelo default da camada de IA. */
-export const DEFAULT_AI_MODEL = "deepseek-v4.1-flash";
+export const DEFAULT_AI_MODEL = "deepseek-v4-pro";
 
 /** Concorrência default das chamadas de IA. */
 export const DEFAULT_AI_CONCURRENCY = 2;

package/src/core/engine/houndsman-engine.ts

@@ -6,9 +6,11 @@
  * de instanciar/importar tudo diretamente.
  */
 
+import { resolve } from "node:path";
 import { AiClient } from "../ai/ai-client";
 import { AstService } from "../ast/service";
 import type { HoundsmanConfig } from "../config";
+import { createGitRunner } from "../git-runner";
 import type { ReviewOptions } from "../orchestrator";
 import { ProjectConfig } from "../project-config";
 import { FileClassifier } from "../services/file-classifier";
@@ -19,9 +21,14 @@ import { createStorage } from "../storage/factory";
 import { resolveRepoIdentity } from "../storage/repo-identity";
 import type { RepoIdentity, StorageProvider } from "../storage/types";
 import { ReviewSession } from "./review-session";
+import { mainRootOf } from "./review-workspace";
 
 /** Colaboradores injetáveis (testes/CLI). */
 export type EngineDeps = {
+	/** Raiz operacional (worktree ou clone principal). */
+	root?: string;
+	/** Raiz do clone principal (identidade/config). */
+	mainRoot?: string;
 	git?: GitRepository;
 	classifier?: FileClassifier;
 	verifier?: Verifier;
@@ -35,6 +42,10 @@ export type EngineDeps = {
 /** Composition root do motor. */
 export class HoundsmanEngine {
 	readonly project: ProjectConfig;
+	/** Onde os arquivos da revisão são lidos (worktree ou clone principal). */
+	readonly root: string;
+	/** Clone principal (identidade estável + camada/config). */
+	readonly mainRoot: string;
 	readonly git: GitRepository;
 	readonly classifier: FileClassifier;
 	readonly verifier: Verifier;
@@ -46,16 +57,27 @@ export class HoundsmanEngine {
 
 	constructor(raw: HoundsmanConfig, deps: EngineDeps = {}) {
 		this.project = new ProjectConfig(raw);
-		this.git = deps.git ?? new GitRepository();
+		this.root = resolve(deps.root ?? process.cwd());
+		this.git = deps.git ?? new GitRepository(createGitRunner(this.root));
+		this.mainRoot = resolve(
+			deps.mainRoot ?? mainRootOf(this.git, this.repoRootFallback()),
+		);
 		this.classifier = deps.classifier ?? new FileClassifier(raw);
 		this.verifier = deps.verifier ?? new Verifier();
 		this.fixBatch = deps.fixBatch ?? new FixBatchBuilder();
 		this.storage = deps.storage ?? createStorage(raw);
-		this.repo = deps.repo ?? resolveRepoIdentity(this.git);
-		this.ast = deps.ast ?? new AstService(raw, this.git);
+		this.repo =
+			deps.repo ??
+			resolveRepoIdentity(new GitRepository(createGitRunner(this.mainRoot)));
+		this.ast = deps.ast ?? new AstService(raw, this.git, this.root);
 		this.ai = deps.ai ?? new AiClient({ project: this.project });
 	}
 
+	/** Raiz do clone principal a partir do git atual (fallback: `root`). */
+	private repoRootFallback(): string {
+		return this.git.rootPath() ?? this.root;
+	}
+
 	/** Configuração crua (contrato do consumidor). */
 	get config(): HoundsmanConfig {
 		return this.project.raw;
@@ -70,6 +92,7 @@ export class HoundsmanEngine {
 			this.repo,
 			this.ast,
 			this.ai,
+			{ root: this.root, mainRoot: this.mainRoot, git: this.git },
 		);
 	}
 

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

@@ -8,13 +8,12 @@
 import type { AstService } from "../ast/service";
 import type { AstAnalysis, AstFacts } from "../ast/types";
 import type { HoundsmanConfig } from "../config";
-import { churnToRecord, collectDiff, type DiffSource } from "../diff-source";
+import { churnToRecord, type DiffSource } from "../diff-source";
 import { type ClassificationResult, parseEntries } from "../file-classifier";
 import type { FindingsStateFile } from "../findings-state";
-import { collectDiffSince, diffEntries, isAncestor } from "../git-revision";
-import { runGit, tryGit } from "../git-runner";
 import type { MergedFinding } from "../report-builder";
 import { FileClassifier } from "../services/file-classifier";
+import { GitRepository } from "../services/git-repository";
 import { buildCarryover } from "./carryover";
 
 /** Opções que afetam o escopo (subset do `ReviewOptions`). */
@@ -60,11 +59,18 @@ export class ReviewScopeResolver {
 	private readonly options: ScopeOptions;
 	private readonly classifier: FileClassifier;
 	private readonly ast?: AstService;
+	private readonly git: GitRepository;
 
-	constructor(options: ScopeOptions, config: HoundsmanConfig, ast?: AstService) {
+	constructor(
+		options: ScopeOptions,
+		config: HoundsmanConfig,
+		ast?: AstService,
+		git: GitRepository = new GitRepository(),
+	) {
 		this.options = options;
 		this.classifier = new FileClassifier(config);
 		this.ast = ast;
+		this.git = git;
 	}
 
 	/**
@@ -89,18 +95,15 @@ export class ReviewScopeResolver {
 			this.options.full ||
 			this.options.clean ||
 			!prevSha ||
-			!isAncestor(prevSha, headSha)
+			!this.git.isAncestor(prevSha, headSha)
 		) {
-			const diff = collectDiff(this.options.base, this.options.head);
+			const diff = this.git.collectDiff(this.options.base, this.options.head);
 			const entries = parseEntries(
-				runGit([
-					"diff",
-					`${this.options.base}...${this.options.head}`,
-					"--name-status",
-				]),
+				this.git.diffNameStatus(this.options.base, this.options.head),
 			);
 			const baseRef =
-				mergeBase(this.options.base, this.options.head) ?? this.options.base;
+				this.git.mergeBase(this.options.base, this.options.head) ??
+				this.options.base;
 			const ast = this.ast
 				? await this.ast.analyze(entries, diff, baseRef)
 				: undefined;
@@ -119,8 +122,8 @@ export class ReviewScopeResolver {
 		}
 
 		const range = `${prevSha}..${headSha}`;
-		const diff = collectDiffSince(prevSha, headSha);
-		const entries = diffEntries(range);
+		const diff = this.git.collectDiffSince(prevSha, headSha);
+		const entries = parseEntries(this.git.run(["diff", range, "--name-status"]));
 		const changedPaths = new Set(entries.map((entry) => entry.path));
 		const ast = this.ast ? await this.ast.analyze(entries, diff, prevSha) : undefined;
 		const classification: RunClassification = {
@@ -149,11 +152,3 @@ function factsOf(
 	}
 	return facts;
 }
-
-/** SHA do merge-base entre base e head (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;
-}

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

@@ -7,6 +7,7 @@
 import type { AiClient } from "../ai/ai-client";
 import type { AstService } from "../ast/service";
 import type { HoundsmanConfig } from "../config";
+import { createGitRunner } from "../git-runner";
 import {
 	type FinalizeResult,
 	finalize,
@@ -14,10 +15,12 @@ import {
 	prepare,
 	type ReviewContext,
 	type ReviewOptions,
+	type ReviewWorkspaceContext,
 	resolveBranch,
 	reviewContext,
 } from "../orchestrator";
 import { sanitizeBranch } from "../report-builder";
+import { GitRepository } from "../services/git-repository";
 import type { RepoIdentity, StorageProvider } from "../storage/types";
 
 /** Uma revisão em andamento (prepare ou finalize). */
@@ -37,6 +40,7 @@ export class ReviewSession {
 		repo: RepoIdentity,
 		ast?: AstService,
 		ai?: AiClient,
+		workspace?: ReviewWorkspaceContext,
 	) {
 		this.config = config;
 		this.options = options;
@@ -51,13 +55,30 @@ export class ReviewSession {
 					slug: sanitizeBranch(branch),
 					base: options.base,
 					head: options.head,
+					worktreePath: options.worktreePath,
+					prNumber: options.pr,
 				});
 		if (!review) {
 			throw new Error(
 				`Nenhuma revisão para '${branch}'. Rode \`houndsman\` (preparar) primeiro.`,
 			);
 		}
-		this.context = reviewContext(storage, review);
+		// Um prepare no clone principal invalida um worktree usado antes; o finalize
+		// não mexe (pode ser rodado de outro lugar depois do prepare no worktree).
+		const current =
+			!options.finalize && !options.worktreePath && review.worktreePath
+				? (storage.updateReview(review.id, { resetWorkspace: true }) ?? review)
+				: review;
+		// Finalize sem flag explícita reusa o worktree gravado no prepare.
+		const effective =
+			options.finalize && !options.worktreePath && current.worktreePath
+				? {
+						root: current.worktreePath,
+						mainRoot: workspace?.mainRoot,
+						git: new GitRepository(createGitRunner(current.worktreePath)),
+					}
+				: workspace;
+		this.context = reviewContext(storage, current, effective);
 	}
 
 	/** Resolve a branch (opção explícita ou a atual do git). */
@@ -68,15 +89,17 @@ export class ReviewSession {
 		repo: RepoIdentity,
 		ast?: AstService,
 		ai?: AiClient,
+		workspace?: ReviewWorkspaceContext,
 	): ReviewSession {
 		return new ReviewSession(
 			config,
 			options,
-			resolveBranch(options),
+			resolveBranch(options, workspace?.git),
 			storage,
 			repo,
 			ast,
 			ai,
+			workspace,
 		);
 	}
 

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

@@ -0,0 +1,204 @@
+/**
+ * Resolução do workspace de uma revisão (engine).
+ *
+ * Decide onde a revisão roda: clone principal, worktree explícito (`--worktree`)
+ * ou worktree criado/reusado para uma PR (`--pr`). Devolve a raiz operacional,
+ * a raiz do clone principal (identidade/config) e as refs do diff.
+ */
+
+import { basename, dirname, resolve } from "node:path";
+import { createGitRunner } from "../git-runner";
+import { createGhRunner, type GhRunner } from "../services/gh-client";
+import { GitRepository } from "../services/git-repository";
+import { PrResolver } from "../services/pr-resolver";
+import { WorktreeManager } from "../services/worktree-manager";
+import { resolveWorktreesRoot } from "../storage/paths";
+import { resolveRepoIdentity } from "../storage/repo-identity";
+import type { RepoIdentity } from "../storage/types";
+
+/** Pedido de resolução (flags do CLI). */
+export type WorkspaceRequest = {
+	cwd: string;
+	base: string;
+	head: string;
+	branch?: string;
+	/** Número da PR (`--pr`). */
+	pr?: number;
+	/** Worktree já existente (`--worktree`). */
+	worktree?: string;
+};
+
+/** Dependências injetáveis (testes). */
+export type WorkspaceDeps = {
+	ghRunner?: GhRunner;
+	/** `config.worktrees.location` (default: `workspace`). */
+	worktreesLocation?: string;
+	/** Override explícito da raiz de worktrees (testes). */
+	worktreesRoot?: string;
+};
+
+/** Workspace resolvido para a revisão. */
+export type ResolvedWorkspace = {
+	/** Onde os arquivos e o git da revisão são lidos. */
+	root: string;
+	/** Clone principal (identidade estável + camada/config). */
+	mainRoot: string;
+	repo: RepoIdentity;
+	git: GitRepository;
+	branch: string;
+	base: string;
+	head: string;
+	prNumber?: number;
+	worktreePath?: string;
+	/** Avisos para o CLI (fetch parcial, reuso etc.). */
+	messages: string[];
+};
+
+/**
+ * Raiz do clone principal a partir de um worktree linkado.
+ * `--git-common-dir` aponta para `<main>/.git`; qualquer outro formato usa `fallback`.
+ */
+export function mainRootOf(git: GitRepository, fallback: string): string {
+	const common = git.gitCommonDir();
+	if (!common) return fallback;
+	const normalized = common.replace(/[\\/]+$/, "");
+	return basename(normalized).toLowerCase() === ".git" ? dirname(normalized) : fallback;
+}
+
+/** Cria um repositório git enraizado em `root`. */
+function repoAt(root: string): GitRepository {
+	return new GitRepository(createGitRunner(root));
+}
+
+/** Compara paths levando em conta o filesystem (Windows é case-insensitive). */
+function samePath(a: string, b: string): boolean {
+	const norm = (path: string): string => {
+		const absolute = resolve(path).replace(/[\\/]+$/, "");
+		return process.platform === "win32" ? absolute.toLowerCase() : absolute;
+	};
+	return norm(a) === norm(b);
+}
+
+/** Resolve o workspace efetivo da revisão. */
+export function resolveReviewWorkspace(
+	request: WorkspaceRequest,
+	deps: WorkspaceDeps = {},
+): ResolvedWorkspace {
+	const messages: string[] = [];
+	const cwdGit = repoAt(request.cwd);
+	const cwdRoot = resolve(cwdGit.rootPath() ?? request.cwd);
+	const mainRoot = resolve(mainRootOf(cwdGit, cwdRoot));
+	const mainGit = repoAt(mainRoot);
+
+	// Worktree explícito: a revisão roda onde o usuário mandou.
+	if (request.worktree) {
+		const path = resolve(request.cwd, request.worktree);
+		const git = repoAt(path);
+		const root = git.rootPath();
+		if (!root) {
+			throw new Error(`'${path}' não é um worktree/repositório git válido.`);
+		}
+		const repo = resolveRepoIdentity(git, root);
+		const branch = request.branch ?? git.currentBranch();
+		if (!branch) {
+			throw new Error(
+				`Worktree '${root}' está em detached HEAD. Informe --branch <nome>.`,
+			);
+		}
+		return {
+			root,
+			mainRoot: mainRootOf(git, repo.root),
+			repo,
+			git,
+			branch,
+			base: request.base,
+			head: request.head,
+			worktreePath: root,
+			messages,
+		};
+	}
+
+	// PR: cria/reusa o worktree detached no commit da PR.
+	if (request.pr !== undefined) {
+		const repo = resolveRepoIdentity(mainGit, mainRoot);
+		const resolver = new PrResolver(
+			deps.ghRunner ?? createGhRunner(mainRoot),
+			mainGit,
+		);
+		const resolved = resolver.resolve(request.pr);
+		if (!resolved.ok) {
+			throw new Error(
+				`Não foi possível resolver a PR #${request.pr}: ${resolved.detail}`,
+			);
+		}
+		const { pr } = resolved;
+		const refs = resolver.prepareRefs(pr);
+		if (refs.warning) messages.push(`GitHub: ${refs.warning}`);
+
+		const manager = new WorktreeManager(mainGit, {
+			repoKey: repo.key,
+			repoRoot: mainRoot,
+			baseDir:
+				deps.worktreesRoot ??
+				resolveWorktreesRoot(deps.worktreesLocation, mainRoot),
+		});
+		const worktree = manager.ensure({ branch: pr.headRefName, ref: refs.head });
+		const worktreePath = resolve(worktree.path);
+		messages.push(
+			`Worktree ${worktree.created ? "criado" : "reutilizado"}: ${worktreePath}`,
+			`PR #${pr.number} — ${pr.headRefName} → ${pr.baseRefName} @ ${refs.head.slice(0, 7)}.`,
+		);
+
+		return {
+			root: worktreePath,
+			mainRoot,
+			repo,
+			git: repoAt(worktreePath),
+			branch: pr.headRefName,
+			base: refs.base,
+			head: refs.head,
+			prNumber: pr.number,
+			worktreePath,
+			messages,
+		};
+	}
+
+	// Já estamos dentro de um worktree: ele é a raiz operacional.
+	const repo = resolveRepoIdentity(mainGit, mainRoot);
+	if (!samePath(cwdRoot, mainRoot)) {
+		const branch = request.branch ?? cwdGit.currentBranch();
+		if (!branch) {
+			throw new Error(
+				`Worktree '${cwdRoot}' está em detached HEAD. Informe --branch <nome>.`,
+			);
+		}
+		messages.push(`Usando o worktree atual: ${cwdRoot}`);
+		return {
+			root: cwdRoot,
+			mainRoot,
+			repo,
+			git: cwdGit,
+			branch,
+			base: request.base,
+			head: request.head,
+			worktreePath: cwdRoot,
+			messages,
+		};
+	}
+
+	// Clone principal.
+	const branch = request.branch ?? mainGit.currentBranch();
+	if (!branch) {
+		throw new Error("Não foi possível detectar a branch. Use --branch <nome>.");
+	}
+	return {
+		root: mainRoot,
+		mainRoot,
+		repo,
+		git: mainGit,
+		branch,
+		base: request.base,
+		head: request.head,
+		messages,
+	};
+}

package/src/core/git-runner.ts

@@ -16,20 +16,32 @@ export type GitResult = {
 /** Executa `git` e devolve o resultado cru. Injetável nos testes. */
 export type GitRunner = (args: string[]) => GitResult;
 
-/** Runner padrão: `git -c core.quotepath=false <args>` a partir do cwd. */
-export const defaultGitRunner: GitRunner = (args) => {
-	const result = Bun.spawnSync(["git", "-c", "core.quotepath=false", ...args], {
-		stdout: "pipe",
-		stderr: "pipe",
-	});
-	const code = result.exitCode ?? 1;
-	return {
-		ok: code === 0,
-		code,
-		stdout: new TextDecoder().decode(result.stdout),
-		stderr: new TextDecoder().decode(result.stderr),
+/**
+ * Cria um runner do git com diretório de trabalho fixo.
+ *
+ * O servidor roda a partir da raiz do repositório, mas o checkout pode ser
+ * disparado de outra sessão — o `cwd` garante que os comandos atinjam o repo
+ * certo. Sem `cwd`, herda o diretório do processo (default).
+ */
+export function createGitRunner(cwd?: string): GitRunner {
+	return (args) => {
+		const result = Bun.spawnSync(["git", "-c", "core.quotepath=false", ...args], {
+			cwd,
+			stdout: "pipe",
+			stderr: "pipe",
+		});
+		const code = result.exitCode ?? 1;
+		return {
+			ok: code === 0,
+			code,
+			stdout: new TextDecoder().decode(result.stdout),
+			stderr: new TextDecoder().decode(result.stderr),
+		};
 	};
-};
+}
+
+/** Runner padrão: `git -c core.quotepath=false <args>` a partir do cwd. */
+export const defaultGitRunner: GitRunner = createGitRunner();
 
 /** Executa e devolve o stdout; lança com o stderr quando o git falha. */
 export function runGit(args: string[], runner: GitRunner = defaultGitRunner): string {

package/src/core/github-review.ts

@@ -24,7 +24,12 @@ import {
 	type FindingsStateFile,
 } from "./findings-state";
 import { systemClock } from "./services/clock";
-import { defaultGhRunner, type GhResult, type GhRunner } from "./services/gh-client";
+import {
+	defaultGhRunner,
+	describeGhError,
+	type GhResult,
+	type GhRunner,
+} from "./services/gh-client";
 import { SEVERITY_EMOJI, SEVERITY_ORDER, type Severity } from "./types";
 
 export { type GhResult, type GhRunner, defaultGhRunner };
@@ -54,12 +59,7 @@ function repoFromUrl(url: string | undefined): string | null {
 
 /** Mensagem curta para um erro do `gh`. */
 function shortError(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}.`;
+	return describeGhError(result);
 }
 
 /**
@@ -118,6 +118,8 @@ export type SubmitCandidate = {
 	file: string;
 	line: number | null;
 	severity: Severity;
+	/** Decisão da triagem (`execute` = "a executar"/fila de correção). */
+	decision: FindingDecision;
 	execState: FindingExecState;
 	rule: string;
 	message: string;
@@ -159,6 +161,7 @@ export function selectSubmitCandidates(
 				file: finding.file,
 				line: finding.line,
 				severity: finding.severity,
+				decision: finding.decision,
 				execState: finding.execState,
 				rule: finding.rule,
 				message: finding.message,

package/src/core/jev/jev-detector.ts

@@ -9,6 +9,7 @@
  */
 
 import { readFileSync } from "node:fs";
+import { join } from "node:path";
 import { collectDiff, type DiffSource } from "../diff-source";
 import type { ClassificationResult } from "../file-classifier";
 import type { WatchdogMeta } from "../types";
@@ -47,11 +48,18 @@ export class JevDetector {
 
 	private readonly client: JevClient;
 	private readonly questions: JevQuestionFactory;
+	/** Raiz dos arquivos (worktree ou clone principal). */
+	private readonly root: string;
 
 	/** Construtor que recebe o cliente e o registry de watchdogs (injeção). */
-	constructor(client: JevClient, registry: Record<string, WatchdogMeta>) {
+	constructor(
+		client: JevClient,
+		registry: Record<string, WatchdogMeta>,
+		root: string = process.cwd(),
+	) {
 		this.client = client;
 		this.questions = new JevQuestionFactory(registry);
+		this.root = root;
 	}
 
 	/** Roda a pré-análise e devolve os candidatos (ordenados por confiança desc). */
@@ -157,7 +165,7 @@ export class JevDetector {
 
 	private readHeader(filePath: string): string {
 		try {
-			return readFileSync(filePath, "utf8")
+			return readFileSync(join(this.root, filePath), "utf8")
 				.split("\n")
 				.slice(0, JevDetector.HEADER_LINES)
 				.join("\n");