@payconductor/houndsman 0.4.0 → 0.6.0

package/src/core/orchestrator.ts

@@ -16,6 +16,15 @@
  * review.<watchdog>.md, context e context-summary.
  */
 
+import { readFileSync } from "node:fs";
+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 type { AstService } from "./ast/service";
+import type { AstAnalysis, AstFileBrief, AstImpact } from "./ast/types";
 import {
 	type HoundsmanConfig,
 	resolveJevConcurrency,
@@ -27,9 +36,11 @@ import { Classification } from "./domain/classification";
 import { Watchdog } from "./domain/watchdog";
 import { mergeCarryover } from "./engine/carryover";
 import { ReviewScopeResolver, type RunClassification } from "./engine/review-scope";
+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,
 	type JevCandidatesFile,
@@ -39,12 +50,22 @@ import {
 	parseCandidates,
 	serializeCandidates,
 } from "./jev";
-import { displayPath, OUTPUT_FORMAT_PATH, REVIEW_FILE } from "./paths";
+import {
+	displayPath,
+	OUTPUT_FORMAT_PATH,
+	REVIEW_FILE,
+	REVIEW_RESUME_FILE,
+} from "./paths";
 import { currentBranch } from "./pr-context";
 import { ProjectConfig } from "./project-config";
 import { BriefRenderer } from "./renderers/brief-renderer";
-import { ManifestWriter } from "./renderers/manifest-writer";
+import {
+	type ManifestAi,
+	type ManifestAst,
+	ManifestWriter,
+} from "./renderers/manifest-writer";
 import { ReportRenderer } from "./renderers/report-renderer";
+import { renderReviewResume } from "./renderers/resume-renderer";
 import {
 	type ContextSummary,
 	type DomainReport,
@@ -68,8 +89,12 @@ export type ReviewOptions = {
 	failOnBlocking: boolean;
 	clean: boolean;
 	noJev: boolean;
+	/** Desativa a análise estrutural (AST) nesta run. */
+	noAst: boolean;
 	/** Força review completo (ignora o modo incremental). */
 	full: boolean;
+	/** Desativa as features de IA do fluxo normal (hunt não usa esta flag). */
+	noAi: boolean;
 };
 
 /** Valores default das opções (o CLI sobrepõe com as flags). */
@@ -81,7 +106,9 @@ export function defaultOptions(): ReviewOptions {
 		failOnBlocking: false,
 		clean: false,
 		noJev: false,
+		noAst: false,
 		full: false,
+		noAi: false,
 	};
 }
 
@@ -142,6 +169,8 @@ function writeManifest(
 	activeIds: string[],
 	pending: string[],
 	jev: JevCandidatesFile,
+	ast?: ManifestAst,
+	ai?: ManifestAi,
 ): void {
 	new ManifestWriter(
 		ctx.storage,
@@ -149,7 +178,7 @@ function writeManifest(
 		ctx.work,
 		new ProjectConfig(config),
 		opts,
-	).write(classification, activeIds, pending, jev);
+	).write(classification, activeIds, pending, jev, ast, ai);
 }
 
 // ---------------------------------------------------------------------------
@@ -164,6 +193,9 @@ function writeBriefs(
 	context: ContextSummary | null,
 	candidates: JevCandidate[],
 	config: HoundsmanConfig,
+	astAnalyses?: ReadonlyMap<string, AstAnalysis>,
+	astImpact?: AstImpact,
+	aiPlans?: ReadonlyMap<string, BriefPlan>,
 ): void {
 	const work = ctx.work;
 	const docs = discoverDocs(Object.keys(classification.files), config);
@@ -173,6 +205,17 @@ function writeBriefs(
 		const def = findWatchdog(config, id);
 		if (!def) continue;
 		const { selected, overflow } = budgetFor(classification, id, maxFilesPerBrief);
+		const astFiles: AstFileBrief[] = selected.flatMap((file) => {
+			const analysis = astAnalyses?.get(file);
+			if (!analysis?.delta) return [];
+			return [
+				{
+					file,
+					delta: analysis.delta,
+					importers: astImpact?.importers[file],
+				},
+			];
+		});
 		const brief = renderer.render(new Watchdog(def), {
 			watchdogId: id,
 			files: selected,
@@ -186,6 +229,8 @@ function writeBriefs(
 			docs,
 			context,
 			candidates: candidates.filter((c) => c.watchdogId === id),
+			ast: astFiles,
+			aiPlan: aiPlans?.get(id),
 		});
 		const content = `${brief}\n`;
 		work.writeBrief(id, content);
@@ -212,6 +257,7 @@ async function resolveCandidates(
 	ctx: ReviewContext,
 	config: HoundsmanConfig,
 	diff: DiffSource,
+	ai?: AiClient,
 ): Promise<JevCandidatesFile> {
 	const save = (data: JevCandidatesFile): JevCandidatesFile => {
 		ctx.storage.writeArtifact(ctx.review.id, {
@@ -222,13 +268,46 @@ async function resolveCandidates(
 		return data;
 	};
 
+	// Pré-análise por IA (opcional) tem precedência sobre o Jev.
+	if (ai && !opts.noAi) {
+		const analyzer = new AiPreAnalyzer(ai);
+		if (analyzer.enabled) {
+			const candidates: JevCandidate[] = [];
+			for (const [id, files] of Object.entries(classification.watchdogs)) {
+				const def = findWatchdog(config, id);
+				if (!def) continue;
+				const inputs = files.slice(0, 5).flatMap((file) => {
+					const snippet = readSnippet(file);
+					return snippet ? [{ file, snippet }] : [];
+				});
+				candidates.push(
+					...(await analyzer.analyze({
+						watchdogId: id,
+						name: def.name,
+						rules: def.rules,
+						files: inputs,
+					})),
+				);
+			}
+			return save({
+				available: true,
+				model: ai.modelId,
+				threshold: JevCandidatesStore.THRESHOLD,
+				analyzedFiles: Object.values(classification.watchdogs).flat().length,
+				candidates,
+			});
+		}
+	}
+
 	if (opts.noJev) {
 		return save(JevCandidatesStore.unavailable("desativado (--no-jev)"));
 	}
 
 	const client = new JevClient();
 	if (!client.isConfigured()) {
-		return save(JevCandidatesStore.unavailable("TYPESAFE_API_KEY não configurada"));
+		return save(
+			JevCandidatesStore.unavailable(`${ENV_NAMES.typeSafeApiKey} não configurada`),
+		);
 	}
 
 	try {
@@ -297,41 +376,208 @@ function budgetMessage(
 	];
 }
 
+/** Primeiras 80 linhas de um arquivo (pré-análise por IA; fail-open). */
+function readSnippet(file: string): string | null {
+	try {
+		return readFileSync(file, "utf8").split("\n").slice(0, 80).join("\n");
+	} catch {
+		return null;
+	}
+}
+
 /** Resultado do prepare — mensagens para o CLI imprimir. */
 export type PrepareResult = { messages: string[] };
 
+/**
+ * Classificação fallback por IA (opcional): atribui arquivos não classificados
+ * a watchdogs conhecidos. Fail-open — falha mantém `unclassified`.
+ */
+async function applyAiClassification(
+	classification: RunClassification,
+	config: HoundsmanConfig,
+	ai: AiClient | undefined,
+	opts: ReviewOptions,
+): Promise<void> {
+	if (!ai || opts.noAi || classification.unclassified.length === 0) return;
+	const classifier = new AiClassifier(ai);
+	if (!classifier.enabled) return;
+	const watchdogs = config.watchdogIds.flatMap((id) => {
+		const def = config.watchdogs[id];
+		return def ? [{ id, name: def.name, scope: def.scope }] : [];
+	});
+	const assignments = await classifier.classify(classification.unclassified, watchdogs);
+	if (assignments.size === 0) return;
+	for (const [file, id] of assignments) {
+		const list = classification.watchdogs[id] ?? [];
+		if (!list.includes(file)) list.push(file);
+		classification.watchdogs[id] = list;
+		classification.stats[id] = list.length;
+	}
+	classification.unclassified = classification.unclassified.filter(
+		(file) => !assignments.has(file),
+	);
+}
+
+/**
+ * Resumo do contexto da PR: usa o do subagente ou, na ausência, a IA
+ * (`AiContextSummarizer`). Grava o artefato e o staging.
+ */
+async function resolveContextSummary(
+	ctx: ReviewContext,
+	ai: AiClient | undefined,
+	opts: ReviewOptions,
+): Promise<ContextSummary | null> {
+	const existing = ctx.work.readContextSummary() ?? readPersistedContextSummary(ctx);
+	if (existing) return existing;
+	if (!ai || opts.noAi) return null;
+	const raw = ctx.work.readContextRaw();
+	if (!raw) return null;
+	const summary = await new AiContextSummarizer(ai).summarize(raw);
+	if (!summary) return null;
+	ctx.work.writeContextSummary(summary);
+	ctx.storage.writeArtifact(ctx.review.id, {
+		name: "context-summary.json",
+		kind: "context-summary",
+		content: `${JSON.stringify(summary, null, 2)}\n`,
+	});
+	return summary;
+}
+
+/**
+ * Planos de revisão por watchdog (uma chamada por brief, concorrência
+ * limitada). Sem IA/chave/feature, devolve mapa vazio e o brief fica igual.
+ */
+async function buildAiPlans(
+	activeIds: string[],
+	classification: ClassificationResult,
+	config: HoundsmanConfig,
+	context: ContextSummary | null,
+	astAnalyses: ReadonlyMap<string, AstAnalysis> | undefined,
+	astImpact: AstImpact | undefined,
+	ai: AiClient | undefined,
+	opts: ReviewOptions,
+): Promise<Map<string, BriefPlan>> {
+	const plans = new Map<string, BriefPlan>();
+	if (!ai || opts.noAi) return plans;
+	const enricher = new AiBriefEnricher(ai);
+	if (!enricher.enabled) return plans;
+
+	const docs = discoverDocs(Object.keys(classification.files), config);
+	const maxFilesPerBrief = resolveMaxFilesPerBrief(config);
+	const inputs = [];
+	for (const id of activeIds) {
+		const def = findWatchdog(config, id);
+		if (!def) continue;
+		const { selected } = budgetFor(classification, id, maxFilesPerBrief);
+		const astFiles: AstFileBrief[] = selected.flatMap((file) => {
+			const analysis = astAnalyses?.get(file);
+			if (!analysis?.delta) return [];
+			return [
+				{ file, delta: analysis.delta, importers: astImpact?.importers[file] },
+			];
+		});
+		inputs.push({
+			watchdogId: id,
+			name: def.name,
+			description: def.description,
+			scope: def.scope,
+			rules: def.rules,
+			files: selected,
+			churn: classification.churn,
+			context,
+			ast: astFiles,
+			docs,
+		});
+	}
+	return enricher.enrichAll(inputs);
+}
+
 /** Passo 1 — descobre os arquivos e grava briefs + manifesto. */
 export async function prepare(
 	opts: ReviewOptions,
 	branch: string,
 	config: HoundsmanConfig,
 	ctx: ReviewContext,
+	ast?: AstService,
+	ai?: AiClient,
 ): Promise<PrepareResult> {
 	const messages: string[] = [];
 	ctx.work.ensure();
 	if (opts.clean) ctx.work.cleanFindings();
 	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 previous = ctx.storage.readFindings(ctx.review.id);
+	const scope = await new ReviewScopeResolver(
+		opts,
+		config,
+		opts.noAst ? undefined : ast,
+	).resolve(previous, headSha);
+
+	// Mesmo commit já revisado: preserva artefatos e triagem, sem re-revisar.
+	if (scope.kind === "noop") {
+		const status = ctx.storage.getReview(ctx.review.id)?.status ?? null;
+		// Ciclo em andamento continua válido (os findings já despachados devem
+		// ser finalizados); fora isso, o relatório anterior é a resposta final.
+		const pendingCycle = status === "reviewing";
+		if (!pendingCycle) {
+			writeRunStatus(ctx.storage, ctx.review.id, { status: "review_done" });
+		}
+		messages.push(
+			`Nenhuma alteração desde a última revisão (${shortSha(scope.reviewedFrom)}).`,
+			pendingCycle
+				? "Nada novo a preparar — o ciclo em andamento continua; rode `--finalize` quando os findings estiverem gravados."
+				: "Nada a revisar — o relatório anterior foi mantido. Use `--full` para re-revisar.",
+		);
+		return { messages };
+	}
+
 	// Marca o run como "revisando" (reinicia o ciclo) — a UI mostra o status.
 	writeRunStatus(ctx.storage, ctx.review.id, {
 		status: "reviewing",
 		resetStartedAt: true,
 	});
 
-	// Marca o commit revisado e decide entre review completo e incremental.
-	const headSha = resolveSha(opts.head);
-	const previous = ctx.storage.readFindings(ctx.review.id);
-	const { classification, diff } = new ReviewScopeResolver(opts, config).resolve(
-		previous,
-		headSha,
-	);
+	const { classification, diff } = scope;
+	await applyAiClassification(classification, config, ai, opts);
 	ctx.storage.writeArtifact(ctx.review.id, {
 		name: "classification.json",
 		kind: "classification",
 		content: `${JSON.stringify(classification, null, 2)}\n`,
 	});
 
-	const jev = await resolveCandidates(opts, classification, ctx, config, diff);
+	const astAnalyses = scope.ast;
+	const astImpact = astAnalyses && ast ? await ast.impact(astAnalyses) : undefined;
+	if (astAnalyses && ast?.enabled) {
+		const summary = {
+			enabled: true,
+			files: Object.fromEntries(
+				[...astAnalyses].map(([path, analysis]) => [
+					path,
+					{
+						facts: analysis.facts,
+						delta: analysis.delta,
+						deleted: analysis.deleted,
+					},
+				]),
+			),
+		};
+		ctx.storage.writeArtifact(ctx.review.id, {
+			name: "ast-summary.json",
+			kind: "ast",
+			content: `${JSON.stringify(summary, null, 2)}\n`,
+		});
+		if (astImpact) {
+			ctx.storage.writeArtifact(ctx.review.id, {
+				name: "ast-impact.json",
+				kind: "ast-impact",
+				content: `${JSON.stringify(astImpact, null, 2)}\n`,
+			});
+		}
+	}
+
+	const jev = await resolveCandidates(opts, classification, ctx, config, diff, ai);
 
 	const activeIds = Object.keys(classification.watchdogs);
 	if (Object.keys(classification.files).length === 0) {
@@ -356,17 +602,103 @@ export async function prepare(
 		);
 	}
 
-	const context = ctx.work.readContextSummary() ?? readPersistedContextSummary(ctx);
 	persistContext(ctx);
+	const context = await resolveContextSummary(ctx, ai, opts);
+
+	const manifestAst: ManifestAst | undefined = astAnalyses
+		? {
+				enabled: ast?.enabled ?? false,
+				languages: [
+					...new Set(
+						[...astAnalyses.values()].map(
+							(analysis) => analysis.facts.language,
+						),
+					),
+				].sort(),
+				files: astAnalyses.size,
+				impact: {
+					affectedFiles: astImpact?.affectedFiles.length ?? 0,
+					importers: Object.keys(astImpact?.importers ?? {}).length,
+					exportedChanges: astImpact?.exportedChanges.length ?? 0,
+				},
+			}
+		: undefined;
+
+	const aiPlans = await buildAiPlans(
+		activeIds,
+		classification,
+		config,
+		context,
+		astAnalyses,
+		astImpact,
+		ai,
+		opts,
+	);
+	if (aiPlans.size > 0) {
+		ctx.storage.writeArtifact(ctx.review.id, {
+			name: "ai-briefs.json",
+			kind: "ai-brief",
+			content: `${JSON.stringify(
+				{ plans: Object.fromEntries(aiPlans) },
+				null,
+				2,
+			)}\n`,
+		});
+	}
+	const aiUsage = ai?.recorder.total;
+	const manifestAi: ManifestAi | undefined =
+		ai && !opts.noAi && (aiPlans.size > 0 || (aiUsage?.calls ?? 0) > 0)
+			? {
+					enabled: true,
+					provider: ai.projectConfig.aiProvider,
+					model: ai.modelId,
+					briefPlans: aiPlans.size,
+					usage: aiUsage ?? {
+						inputTokens: 0,
+						outputTokens: 0,
+						totalTokens: 0,
+						calls: 0,
+					},
+				}
+			: undefined;
 
-	writeBriefs(activeIds, classification, ctx, branch, context, jev.candidates, config);
-	writeManifest(ctx, config, opts, classification, activeIds, activeIds, jev);
+	writeBriefs(
+		activeIds,
+		classification,
+		ctx,
+		branch,
+		context,
+		jev.candidates,
+		config,
+		astAnalyses,
+		astImpact,
+		aiPlans,
+	);
+	writeManifest(
+		ctx,
+		config,
+		opts,
+		classification,
+		activeIds,
+		activeIds,
+		jev,
+		manifestAst,
+		manifestAi,
+	);
 
 	messages.push(
 		...discoveryMessages(activeIds, classification, ctx.work.briefsDir),
 		...budgetMessage(classification, config),
 		...jevSummary(jev),
 	);
+	if (astAnalyses) {
+		messages.push(
+			`AST: ${astAnalyses.size} arquivo(s) analisado(s), ` +
+				`${astImpact?.affectedFiles.length ?? 0} impactado(s).`,
+		);
+	} else {
+		messages.push("AST: desabilitado ou sem grammar compatível.");
+	}
 
 	if (context) {
 		messages.push("Contexto da PR resumido e injetado nos briefs.");
@@ -375,6 +707,17 @@ export async function prepare(
 			"Sem contexto da PR (rode `bun run houndsman context` antes, se houver PR).",
 		);
 	}
+	if (aiPlans.size > 0) {
+		messages.push(
+			`IA: plano de revisão em ${aiPlans.size} brief(s) (sugestão, não substitui regras).`,
+		);
+	}
+	if (aiUsage && aiUsage.calls > 0) {
+		messages.push(
+			`IA: ${aiUsage.calls} chamada(s), ${aiUsage.totalTokens} token(s).`,
+		);
+		ai?.recorder.write(ctx.storage, ctx.review.id);
+	}
 
 	messages.push(
 		`\nPróximo passo: despachar os sub-agentes (um por brief em ${displayPath(ctx.work.briefsDir)}/).`,
@@ -415,6 +758,24 @@ function persistContext(ctx: ReviewContext): void {
 // Passo 2 — finalizar
 // ---------------------------------------------------------------------------
 
+/** Reaproveita `ast`/`ai` do manifesto anterior (o finalize não os recalcula). */
+function readManifestExtras(ctx: ReviewContext): {
+	ast?: ManifestAst;
+	ai?: ManifestAi;
+} {
+	const artifact = ctx.storage.readArtifact(ctx.review.id, "manifest.json");
+	if (!artifact) return {};
+	try {
+		const parsed = JSON.parse(artifact.content) as {
+			ast?: ManifestAst;
+			ai?: ManifestAi;
+		};
+		return { ast: parsed.ast, ai: parsed.ai };
+	} catch {
+		return {};
+	}
+}
+
 /** Lê o `classification.json` persistido pelo prepare (lança se ausente). */
 function readClassification(ctx: ReviewContext): RunClassification {
 	const artifact = ctx.storage.readArtifact(ctx.review.id, "classification.json");
@@ -510,6 +871,27 @@ export function finalize(
 	config: HoundsmanConfig,
 	ctx: ReviewContext,
 ): FinalizeResult {
+	// `--finalize` só consolida um ciclo preparado (status `reviewing`). Sem esta
+	// guarda, um prepare no-op seguido de `--finalize` reescreveria o relatório
+	// anterior com a classificação antiga (perdendo os relatórios por domínio).
+	// O `ctx.review` é um snapshot: relê o status atual do storage.
+	const status = ctx.storage.getReview(ctx.review.id)?.status ?? null;
+	if (status !== "reviewing") {
+		const state = ctx.storage.readFindings(ctx.review.id);
+		const present = Object.values(state?.findings ?? {}).filter(
+			(finding) => finding.present,
+		);
+		return {
+			reportPath: ctx.storage.location(ctx.review.id),
+			blockers: present.filter((f) => f.severity === "blocking").length,
+			attention: present.filter((f) => f.severity === "attention").length,
+			messages: [
+				`Nada a finalizar: nenhum ciclo de revisão pendente (status: ${status ?? "sem status"}).`,
+				"Se nada mudou desde a última revisão, o relatório anterior foi mantido; use `--full` para re-revisar.",
+			],
+		};
+	}
+
 	const classification = readClassification(ctx);
 	const activeIds = Object.keys(classification.watchdogs);
 
@@ -517,7 +899,18 @@ export function finalize(
 	const { reports, pending, warnings } = ctx.work.readFindings(activeIds);
 	messages.push(...warnings);
 	const jev = readCandidates(ctx, config);
-	writeManifest(ctx, config, opts, classification, activeIds, pending, jev);
+	const extras = readManifestExtras(ctx);
+	writeManifest(
+		ctx,
+		config,
+		opts,
+		classification,
+		activeIds,
+		pending,
+		jev,
+		extras.ast,
+		extras.ai,
+	);
 
 	if (pending.length > 0) {
 		throw new Error(
@@ -546,12 +939,44 @@ export function finalize(
 		branch,
 		readFile: fileReader(process.cwd()),
 		previous: ctx.storage.readFindings(ctx.review.id),
+		reviewedPaths: new Set([
+			...reports.flatMap((report) => report.reviewedFiles),
+			// Arquivo deletado: o achado deixou de existir junto com ele.
+			...classification.deleted,
+		]),
 		now,
 		headSha: classification.headSha,
 		reviewed: classification.headSha
 			? { headSha: classification.headSha, at: now }
 			: undefined,
 	});
+
+	// Findings corrigidos entre revisões (ausentes + done) têm a conversa do PR
+	// resolvida automaticamente; as já resolvidas no GitHub são puladas. Só
+	// toca o `gh` quando há vínculo remoto pendente (fail-open).
+	const threadIds = Object.values(state.findings)
+		.filter(
+			(finding) =>
+				!finding.present &&
+				finding.execState === "done" &&
+				finding.github &&
+				finding.github.kind !== "comment" &&
+				!finding.github.resolvedAt,
+		)
+		.map((finding) => finding.id);
+	if (threadIds.length > 0) {
+		const sync = syncResolvedThreads({ state, ids: threadIds, now });
+		if (!sync.available) {
+			messages.push(`GitHub: threads não sincronizadas (${sync.reason}).`);
+		} else if (sync.checked > 0) {
+			const failures =
+				sync.failed.length > 0 ? `, ${sync.failed.length} falha(s)` : "";
+			messages.push(
+				`GitHub: ${sync.resolved.length} thread(s) resolvida(s), ${sync.skipped.length} já resolvida(s)/pulada(s)${failures}.`,
+			);
+		}
+	}
+
 	ctx.storage.writeFindings(ctx.review.id, state);
 	ctx.storage.updateReview(ctx.review.id, {
 		base: opts.base,
@@ -585,6 +1010,19 @@ export function finalize(
 		kind: "review",
 		content: `${incrementalNote(classification)}${markdown}\n`,
 	});
+	// Resumo final para leitura humana — não participa de nenhuma etapa seguinte.
+	ctx.storage.writeArtifact(ctx.review.id, {
+		name: REVIEW_RESUME_FILE,
+		kind: "resume",
+		content: renderReviewResume({
+			branch,
+			date: now.slice(0, 10),
+			context,
+			classification,
+			findings: merged,
+			nameOf,
+		}),
+	});
 
 	const location = ctx.storage.location(ctx.review.id);
 	messages.push(

package/src/core/paths.ts

@@ -52,3 +52,6 @@ export const VERIFY_FILE = "verify.md";
 
 /** Relatório consolidado da review (artefato `review.md`). */
 export const REVIEW_FILE = "review.md";
+
+/** Resumo final da review (artefato `review-resume.md`) — leitura humana apenas. */
+export const REVIEW_RESUME_FILE = "review-resume.md";