@payconductor/houndsman 0.1.0 → 0.1.1

package/src/core/commands/findings.ts

@@ -0,0 +1,390 @@
+/**
+ * Subcomando `findings` — triagem dos findings da revisão (biblioteca).
+ *
+ * Lê/grava o `state.json` da run (`findings-state.ts`). Devolve o texto pronto
+ * (markdown ou JSON) + exit code; o CLI decide o log/exit. O agente do usuário
+ * usa `list`/`set`/`done` para interagir sem abrir o JSON à mão.
+ *
+ * Se o `state.json` não existir, é re-construído a partir de
+ * `findings/*.json` + `classification.json` (não exige `--finalize`).
+ */
+
+import { type HoundsmanConfig, resolveArtifactDir } from "../config";
+import {
+	applyFindingUpdate,
+	buildStateFromRunDir,
+	FINDING_DECISIONS,
+	FINDING_EXEC_STATES,
+	type FindingDecision,
+	type FindingExecState,
+	type FindingState,
+	type FindingsFilter,
+	type FindingsStateFile,
+	FindingsStateStore,
+	type FindingsSummary,
+	type FindingUpdate,
+	fileReader,
+	filterFindings,
+	runDir,
+	summarize,
+	syncState,
+} from "../findings-state";
+import { relFromRoot } from "../paths";
+import { currentBranch } from "../pr-context";
+import { SEVERITY_EMOJI, SEVERITY_ORDER, type Severity } from "../types";
+
+export type FindingsCommandResult = {
+	output: string;
+	exitCode: number;
+};
+
+const VALUE_FLAGS = new Set([
+	"--decision",
+	"--exec",
+	"--watchdog",
+	"--severity",
+	"--file",
+	"--branch",
+	"--dir",
+	"--limit",
+	"--comment",
+	"--by",
+]);
+
+type ParsedArgs = {
+	sub?: string;
+	positionals: string[];
+	values: Record<string, string>;
+	bools: Set<string>;
+};
+
+/** Parse simples: primeiro não-flag = sub; demais = positionais. */
+function parseArgs(args: string[]): ParsedArgs {
+	const parsed: ParsedArgs = { positionals: [], values: {}, bools: new Set() };
+	for (let i = 0; i < args.length; i++) {
+		const arg = args[i];
+		if (arg.startsWith("--")) {
+			if (VALUE_FLAGS.has(arg)) {
+				const value = args[i + 1];
+				if (value !== undefined) parsed.values[arg] = value;
+				i++;
+			} else {
+				parsed.bools.add(arg);
+			}
+			continue;
+		}
+		if (!parsed.sub) parsed.sub = arg;
+		else parsed.positionals.push(arg);
+	}
+	return parsed;
+}
+
+/** Diretório da run + branch resolvida. */
+function resolveDir(
+	config: HoundsmanConfig,
+	parsed: ParsedArgs,
+): { dir: string; branch: string } {
+	return {
+		dir: parsed.values["--dir"] ?? resolveArtifactDir(config),
+		branch: parsed.values["--branch"] ?? currentBranch(),
+	};
+}
+
+/** Lê o estado da run; reconstrói dos findings se ausente. Lança se impossível. */
+function loadState(config: HoundsmanConfig, parsed: ParsedArgs): FindingsStateFile {
+	const { dir, branch } = resolveDir(config, parsed);
+	const store = FindingsStateStore.at(dir, branch);
+	const existing = store.read();
+	if (existing) return existing;
+
+	const built = buildStateFromRunDir(
+		runDir(dir, branch),
+		branch,
+		fileReader(process.cwd()),
+	);
+	if (!built) {
+		throw new Error(
+			`Nenhum estado de triagem para '${branch}'. Rode \`houndsman --finalize\` primeiro.`,
+		);
+	}
+	store.write(built);
+	return built;
+}
+
+// ---------------------------------------------------------------------------
+// Render
+// ---------------------------------------------------------------------------
+
+function decisionLabel(decision: FindingDecision): string {
+	return decision;
+}
+
+/** Uma linha compacta por finding (uso no agente). */
+function renderFindingLine(finding: FindingState): string[] {
+	const emoji = SEVERITY_EMOJI[finding.severity];
+	const location = finding.line ? `${finding.file}:${finding.line}` : finding.file;
+	const flags = `${decisionLabel(finding.decision)}/${finding.execState}`;
+	const count = finding.count > 1 ? ` ×${finding.count}` : "";
+	const lines = [
+		`- \`${finding.id}\` ${emoji} **${finding.severity}** \`${location}\` — ${finding.rule}${count}`,
+		`  ${finding.message}`,
+		`  _${flags}_ · watchdogs: ${finding.watchdogIds.join(", ") || "—"}`,
+	];
+	if (finding.comment) lines.push(`  **Comentário:** ${finding.comment}`);
+	return lines;
+}
+
+function renderList(state: FindingsStateFile, findings: FindingState[]): string {
+	if (findings.length === 0) return "Nenhum finding para o filtro informado.";
+	const lines = [`# Findings — ${state.branch} (${findings.length})`, ""];
+	for (const finding of findings) lines.push(...renderFindingLine(finding));
+	return lines.join("\n");
+}
+
+function renderSummary(state: FindingsStateFile, summary: FindingsSummary): string {
+	const decisions = FINDING_DECISIONS.map((d) => `${d} ${summary.byDecision[d]}`).join(
+		" · ",
+	);
+	const exec = FINDING_EXEC_STATES.map((e) => `${e} ${summary.byExecState[e]}`).join(
+		" · ",
+	);
+	const severities = SEVERITY_ORDER.map((s) => `${s} ${summary.bySeverity[s]}`).join(
+		" · ",
+	);
+	return [
+		`# Triagem — ${state.branch}`,
+		"",
+		`Total: ${summary.total} (presentes: ${summary.present})`,
+		`Decisões: ${decisions}`,
+		`Execução: ${exec}`,
+		`Severidade: ${severities}`,
+	].join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// Execução
+// ---------------------------------------------------------------------------
+
+function parseDecision(raw: string | undefined): FindingDecision | undefined {
+	if (!raw) return undefined;
+	if (!FINDING_DECISIONS.includes(raw as FindingDecision)) {
+		throw new Error(
+			`--decision inválido: '${raw}'. Use: ${FINDING_DECISIONS.join(", ")}.`,
+		);
+	}
+	return raw as FindingDecision;
+}
+
+function parseExec(raw: string | undefined): FindingExecState | undefined {
+	if (!raw) return undefined;
+	if (!FINDING_EXEC_STATES.includes(raw as FindingExecState)) {
+		throw new Error(
+			`--exec inválido: '${raw}'. Use: ${FINDING_EXEC_STATES.join(", ")}.`,
+		);
+	}
+	return raw as FindingExecState;
+}
+
+function filterFrom(parsed: ParsedArgs): FindingsFilter {
+	const severity = parsed.values["--severity"];
+	return {
+		decision: parseDecision(parsed.values["--decision"]),
+		execState: parseExec(parsed.values["--exec"]),
+		watchdog: parsed.values["--watchdog"],
+		severity: severity ? (severity as Severity) : undefined,
+		file: parsed.values["--file"],
+		includeAbsent: parsed.bools.has("--all"),
+	};
+}
+
+/** Aplica uma atualização a um finding e persiste. */
+function updateOne(
+	config: HoundsmanConfig,
+	parsed: ParsedArgs,
+	id: string,
+	update: FindingUpdate,
+): FindingState {
+	const { dir, branch } = resolveDir(config, parsed);
+	const store = FindingsStateStore.at(dir, branch);
+	let updated: FindingState | undefined;
+	store.update((state) => {
+		const finding = state.findings[id];
+		if (!finding) return;
+		updated = applyFindingUpdate(finding, update);
+	});
+	if (!updated) throw new Error(`Finding '${id}' não encontrado.`);
+	return updated;
+}
+
+/** Aplica a mesma atualização a vários ids (done/reset). */
+function updateMany(
+	config: HoundsmanConfig,
+	parsed: ParsedArgs,
+	ids: string[],
+	update: FindingUpdate,
+): FindingState[] {
+	const { dir, branch } = resolveDir(config, parsed);
+	const store = FindingsStateStore.at(dir, branch);
+	const updated: FindingState[] = [];
+	store.update((state) => {
+		for (const id of ids) {
+			const finding = state.findings[id];
+			if (!finding) continue;
+			updated.push(applyFindingUpdate(finding, update));
+		}
+	});
+	const missing = ids.filter((id) => !updated.some((f) => f.id === id));
+	if (missing.length > 0) {
+		throw new Error(`Findings não encontrados: ${missing.join(", ")}.`);
+	}
+	return updated;
+}
+
+/** Executa um subcomando de `findings` e devolve o texto + exit code. */
+export function runFindingsCommand(
+	config: HoundsmanConfig,
+	args: string[],
+): FindingsCommandResult {
+	const parsed = parseArgs(args);
+	try {
+		return execute(config, parsed);
+	} catch (error) {
+		return {
+			output: error instanceof Error ? error.message : String(error),
+			exitCode: 1,
+		};
+	}
+}
+
+function execute(config: HoundsmanConfig, parsed: ParsedArgs): FindingsCommandResult {
+	switch (parsed.sub ?? "list") {
+		case "list": {
+			const state = loadState(config, parsed);
+			const filtered = filterFindings(state, filterFrom(parsed));
+			const limit = Number(parsed.values["--limit"]);
+			const findings =
+				Number.isFinite(limit) && limit > 0 ? filtered.slice(0, limit) : filtered;
+			return {
+				output: parsed.bools.has("--json")
+					? JSON.stringify(findings, null, 2)
+					: renderList(state, findings),
+				exitCode: 0,
+			};
+		}
+		case "show": {
+			const state = loadState(config, parsed);
+			const id = parsed.positionals[0];
+			if (!id) throw new Error("Informe o id: houndsman findings show <id>");
+			const finding = state.findings[id];
+			if (!finding) throw new Error(`Finding '${id}' não encontrado.`);
+			return {
+				output: parsed.bools.has("--json")
+					? JSON.stringify(finding, null, 2)
+					: renderList(state, [finding]),
+				exitCode: 0,
+			};
+		}
+		case "set": {
+			const id = parsed.positionals[0];
+			if (!id) throw new Error("Informe o id: houndsman findings set <id> [flags]");
+			const update = updateFrom(parsed);
+			if (!hasUpdate(update)) {
+				throw new Error(
+					"Nada para atualizar (use --decision, --exec ou --comment).",
+				);
+			}
+			const finding = updateOne(config, parsed, id, update);
+			return {
+				output: parsed.bools.has("--json")
+					? JSON.stringify(finding, null, 2)
+					: `Atualizado: \`${finding.id}\` → ${finding.decision}/${finding.execState}.`,
+				exitCode: 0,
+			};
+		}
+		case "done": {
+			const ids = requireIds(parsed, "done");
+			const updated = updateMany(config, parsed, ids, { execState: "done" });
+			return {
+				output: `Marcados como done: ${updated.map((f) => f.id).join(", ")}.`,
+				exitCode: 0,
+			};
+		}
+		case "reset": {
+			const ids = requireIds(parsed, "reset");
+			const updated = updateMany(config, parsed, ids, {
+				decision: "pending",
+				execState: "pending",
+				comment: "",
+			});
+			return {
+				output: `Triagem reiniciada: ${updated.map((f) => f.id).join(", ")}.`,
+				exitCode: 0,
+			};
+		}
+		case "sync": {
+			const { dir, branch } = resolveDir(config, parsed);
+			const store = FindingsStateStore.at(dir, branch);
+			const state = loadState(config, parsed);
+			const result = syncState(state, fileReader(process.cwd()));
+			store.write(state);
+			const output = parsed.bools.has("--json")
+				? JSON.stringify(result, null, 2)
+				: [
+						`Sync — ${branch}: ${result.ok} ok, ${result.moved.length} movido(s), ${result.stale.length} stale.`,
+						result.moved.length > 0
+							? `Movidos: ${result.moved.join(", ")}`
+							: "",
+						result.stale.length > 0
+							? `Stale: ${result.stale.join(", ")}`
+							: "",
+					]
+						.filter(Boolean)
+						.join("\n");
+			return { output, exitCode: 0 };
+		}
+		case "summary": {
+			const state = loadState(config, parsed);
+			const summary = summarize(state);
+			return {
+				output: parsed.bools.has("--json")
+					? JSON.stringify(summary, null, 2)
+					: renderSummary(state, summary),
+				exitCode: 0,
+			};
+		}
+		case "path": {
+			const { dir, branch } = resolveDir(config, parsed);
+			const path = FindingsStateStore.at(dir, branch).filePath;
+			return { output: relFromRoot(path), exitCode: 0 };
+		}
+		default:
+			return {
+				output: `Subcomando '${parsed.sub}' desconhecido. Use: list, show, set, done, reset, sync, summary, path.`,
+				exitCode: 1,
+			};
+	}
+}
+
+function updateFrom(parsed: ParsedArgs): FindingUpdate {
+	return {
+		decision: parseDecision(parsed.values["--decision"]),
+		execState: parseExec(parsed.values["--exec"]),
+		comment: parsed.values["--comment"],
+		by: parsed.values["--by"],
+	};
+}
+
+function hasUpdate(update: FindingUpdate): boolean {
+	return (
+		update.decision !== undefined ||
+		update.execState !== undefined ||
+		update.comment !== undefined
+	);
+}
+
+function requireIds(parsed: ParsedArgs, sub: string): string[] {
+	if (parsed.positionals.length === 0) {
+		throw new Error(`Informe ao menos um id: houndsman findings ${sub} <id...>`);
+	}
+	return parsed.positionals;
+}

package/src/core/commands/scaffold.ts

@@ -164,6 +164,24 @@ export type FileStatus =
 
 export type FileStatusMap = Record<string, { status: FileStatus; oldPath?: string }>;
 
+/** Linhas adicionadas/removidas de um arquivo no diff (churn). */
+export type FileChurn = { additions: number; deletions: number };
+
+/** Churn por caminho de arquivo. */
+export type ChurnMap = Record<string, FileChurn>;
+
+/** Limites de triage para PRs grandes. */
+export type HoundsmanBudgets = {
+	/** Máx. de arquivos por brief (default: 40). Excedente vai para "fora do orçamento". */
+	maxFilesPerBrief?: number;
+};
+
+/** Concorrência das fases paralelas internas. */
+export type HoundsmanConcurrency = {
+	/** Chamadas Jev simultâneas (default: 5). */
+	jev?: number;
+};
+
 /** Contrato de configuração do motor. */
 export type HoundsmanConfig<TId extends string = string> = {
 	projectName: string;
@@ -173,6 +191,8 @@ export type HoundsmanConfig<TId extends string = string> = {
 	exclusions: readonly RegExp[];
 	docMappings: readonly (readonly [RegExp, readonly string[]])[];
 	alwaysIncludeDocs?: readonly string[];
+	budgets?: HoundsmanBudgets;
+	concurrency?: HoundsmanConcurrency;
 };
 
 /** Helper de autoria (identidade) — apenas tipagem. */

package/src/core/config.ts

@@ -12,6 +12,29 @@ import type { WatchdogDefinition } from "./types";
 /** Documentos sempre incluídos nos briefs (default). */
 export const DEFAULT_ALWAYS_INCLUDE_DOCS: readonly string[] = ["AGENTS.md"];
 
+/**
+ * Teto default de arquivos por brief. Um PR grande (milhares de linhas) pode
+ * concentrar centenas de arquivos em um único domínio; o teto mantém o contexto
+ * do subagente limitado — o excedente vira "fora do orçamento" (cobertura
+ * honesta), nunca some silenciosamente.
+ */
+export const DEFAULT_MAX_FILES_PER_BRIEF = 40;
+
+/** Concorrência default das chamadas simultâneas ao Jev. */
+export const DEFAULT_JEV_CONCURRENCY = 5;
+
+/** Limites de triage para PRs grandes. */
+export type HoundsmanBudgets = {
+	/** Máx. de arquivos por brief (default: 40). Excedente vai para "fora do orçamento". */
+	maxFilesPerBrief?: number;
+};
+
+/** Concorrência das fases paralelas internas. */
+export type HoundsmanConcurrency = {
+	/** Chamadas Jev simultâneas (default: 5). */
+	jev?: number;
+};
+
 /**
  * Configuração completa do motor de revisão para um projeto.
  *
@@ -35,6 +58,10 @@ export type HoundsmanConfig<TId extends string = string> = {
 	docMappings: readonly (readonly [RegExp, readonly string[]])[];
 	/** Docs sempre incluídos nos briefs (default: `DEFAULT_ALWAYS_INCLUDE_DOCS`). */
 	alwaysIncludeDocs?: readonly string[];
+	/** Limites de triage para PRs grandes (default: `DEFAULT_MAX_FILES_PER_BRIEF`). */
+	budgets?: HoundsmanBudgets;
+	/** Concorrência das fases paralelas internas. */
+	concurrency?: HoundsmanConcurrency;
 };
 
 /** Entrada de `defineHoundsmanConfig` — `watchdogIds` é derivado, não informado. */
@@ -57,3 +84,18 @@ export function defineHoundsmanConfig<TId extends string>(
 export function resolveArtifactDir(config: HoundsmanConfig): string {
 	return config.artifactDir ?? ARTIFACT_DIR;
 }
+
+/**
+ * Teto de arquivos por brief. Valor ausente/não-positivo cai no default —
+ * mantém o contexto do subagente limitado em PRs grandes.
+ */
+export function resolveMaxFilesPerBrief(config: HoundsmanConfig): number {
+	const value = config.budgets?.maxFilesPerBrief;
+	return value !== undefined && value > 0 ? value : DEFAULT_MAX_FILES_PER_BRIEF;
+}
+
+/** Concorrência das chamadas Jev (valor ausente/não-positivo cai no default). */
+export function resolveJevConcurrency(config: HoundsmanConfig): number {
+	const value = config.concurrency?.jev;
+	return value !== undefined && value > 0 ? value : DEFAULT_JEV_CONCURRENCY;
+}

package/src/core/diff-source.ts

@@ -0,0 +1,140 @@
+/**
+ * Coleta do diff em um único passo (biblioteca).
+ *
+ * Roda `git diff base...head` **uma vez** (patch) e `--numstat` **uma vez**
+ * (churn), fatiando o patch por arquivo em memória. Substitui os N spawns de
+ * `git diff -- <arquivo>` (antes feitos por arquivo, no `jev-detector`): o custo
+ * deixa de crescer com o número de arquivos da PR.
+ *
+ * Usado por `orchestrator.prepare` (churn para a classificação + patch para o
+ * Jev) e por `classifyRange` (fallback standalone).
+ */
+
+import type { ChurnMap, FileChurn } from "./types";
+
+export type DiffSource = {
+	/** path → patch do arquivo (header + hunks), truncado por `maxPerFileChars`. */
+	byFile: Map<string, string>;
+	/** path (novo) → linhas adicionadas/removidas. */
+	churn: Map<string, FileChurn>;
+};
+
+export type CollectDiffOptions = {
+	/** Teto de caracteres por arquivo no patch (default: 8_000). */
+	maxPerFileChars?: number;
+};
+
+const DEFAULT_MAX_PER_FILE_CHARS = 8_000;
+
+/** Executa `git` com `core.quotepath=false` (paths literais) e devolve o stdout. */
+function runGit(args: string[]): string {
+	const result = Bun.spawnSync(["git", "-c", "core.quotepath=false", ...args], {
+		stdout: "pipe",
+		stderr: "pipe",
+	});
+	if (result.exitCode !== 0) {
+		const stderr = new TextDecoder().decode(result.stderr).trim();
+		throw new Error(`git ${args.join(" ")} falhou: ${stderr}`);
+	}
+	return new TextDecoder().decode(result.stdout);
+}
+
+/** Novo caminho do arquivo a partir do cabeçalho de um segmento do patch. */
+function extractPath(segment: string): string | undefined {
+	// Só o cabeçalho (antes do primeiro hunk) pode conter as linhas `---`/`+++` —
+	// assim uma linha de conteúdo como `+++ b/x` não é confundida com o header.
+	const hunkAt = segment.indexOf("\n@@");
+	const header = hunkAt >= 0 ? segment.slice(0, hunkAt) : segment;
+	const lines = header.split("\n");
+
+	for (const line of lines) {
+		if (line.startsWith("+++ b/")) return line.slice(6);
+	}
+	for (const line of lines) {
+		// Deletados têm `+++ /dev/null`; o caminho antigo é a melhor referência.
+		if (line.startsWith("--- a/")) return line.slice(6);
+	}
+
+	// Fallback (ex.: binário, sem `---`/`+++`): `a/<old> b/<new>`.
+	const firstLine = lines[0] ?? "";
+	const marker = firstLine.lastIndexOf(" b/");
+	return marker >= 0 ? firstLine.slice(marker + 3) : undefined;
+}
+
+/** Fatia um patch unificado por arquivo (`diff --git`). */
+export function parseDiffIndex(
+	patch: string,
+	maxPerFileChars = Number.POSITIVE_INFINITY,
+): Map<string, string> {
+	const map = new Map<string, string>();
+	for (const segment of patch.split(/^diff --git /m)) {
+		if (!segment.trim()) continue;
+		const path = extractPath(segment);
+		if (!path) continue;
+		const text = `diff --git ${segment}`;
+		map.set(
+			path,
+			text.length > maxPerFileChars ? text.slice(0, maxPerFileChars) : text,
+		);
+	}
+	return map;
+}
+
+/** Contagem do `--numstat` (`-` em binários) → número. */
+function toCount(value: string): number {
+	const parsed = Number.parseInt(value, 10);
+	return Number.isNaN(parsed) ? 0 : parsed;
+}
+
+/** Fatia `git diff --numstat -z` em path → churn (trata renames/cópias/bins). */
+export function parseNumstat(raw: string): Map<string, FileChurn> {
+	const map = new Map<string, FileChurn>();
+	const tokens = raw.split("\0");
+
+	for (let i = 0; i < tokens.length; i++) {
+		const token = tokens[i];
+		if (!token) continue;
+		const fields = token.split("\t");
+		if (fields.length < 3) continue;
+
+		let path = fields[2];
+		if (path === "") {
+			// Renomeado/copiado: os dois caminhos seguem como tokens próprios.
+			path = tokens[i + 2] ?? "";
+			i += 2;
+		}
+		if (!path) continue;
+
+		map.set(path, { additions: toCount(fields[0]), deletions: toCount(fields[1]) });
+	}
+	return map;
+}
+
+/** Churn por arquivo (`git diff --numstat -z`) — 1 spawn. */
+export function collectChurn(base: string, head: string): Map<string, FileChurn> {
+	return parseNumstat(runGit(["diff", "--numstat", "-z", `${base}...${head}`]));
+}
+
+/**
+ * Patch + churn em uma passada: 2 spawns fixos, independentes do nº de arquivos.
+ */
+export function collectDiff(
+	base: string,
+	head: string,
+	options: CollectDiffOptions = {},
+): DiffSource {
+	const range = `${base}...${head}`;
+	const patch = runGit(["diff", range]);
+	return {
+		byFile: parseDiffIndex(
+			patch,
+			options.maxPerFileChars ?? DEFAULT_MAX_PER_FILE_CHARS,
+		),
+		churn: collectChurn(base, head),
+	};
+}
+
+/** Converte o Map de churn em Record (para o `classification.json`). */
+export function churnToRecord(churn: Map<string, FileChurn>): ChurnMap {
+	return Object.fromEntries(churn);
+}