@payconductor/houndsman 0.5.0 → 0.7.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,6 +36,7 @@ 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";
@@ -49,7 +59,11 @@ import {
 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 {
@@ -75,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). */
@@ -88,7 +106,9 @@ export function defaultOptions(): ReviewOptions {
 		failOnBlocking: false,
 		clean: false,
 		noJev: false,
+		noAst: false,
 		full: false,
+		noAi: false,
 	};
 }
 
@@ -149,6 +169,8 @@ function writeManifest(
 	activeIds: string[],
 	pending: string[],
 	jev: JevCandidatesFile,
+	ast?: ManifestAst,
+	ai?: ManifestAi,
 ): void {
 	new ManifestWriter(
 		ctx.storage,
@@ -156,7 +178,7 @@ function writeManifest(
 		ctx.work,
 		new ProjectConfig(config),
 		opts,
-	).write(classification, activeIds, pending, jev);
+	).write(classification, activeIds, pending, jev, ast, ai);
 }
 
 // ---------------------------------------------------------------------------
@@ -171,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);
@@ -180,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,
@@ -193,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);
@@ -219,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, {
@@ -229,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 {
@@ -304,15 +376,130 @@ 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();
@@ -322,7 +509,11 @@ export async function prepare(
 	// 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 = new ReviewScopeResolver(opts, config).resolve(previous, headSha);
+	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") {
@@ -349,13 +540,44 @@ export async function prepare(
 	});
 
 	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) {
@@ -380,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;
 
-	writeBriefs(activeIds, classification, ctx, branch, context, jev.candidates, config);
-	writeManifest(ctx, config, opts, classification, activeIds, activeIds, jev);
+	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,
+		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.");
@@ -399,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)}/).`,
@@ -439,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");
@@ -562,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(

package/src/core/project-config.ts

@@ -6,9 +6,25 @@
  * O contrato do consumidor (`houndsman.config.ts`) não muda.
  */
 
-import type { HoundsmanConfig, HoundsmanStorage } from "./config";
+import type {
+	AiProviderKind,
+	HoundsmanAi,
+	HoundsmanAiFeatures,
+	HoundsmanAst,
+	HoundsmanConfig,
+	HoundsmanStorage,
+} from "./config";
 import {
+	DEFAULT_AI_CONCURRENCY,
+	DEFAULT_AI_MAX_CALLS_PER_REVIEW,
+	DEFAULT_AI_MAX_OUTPUT_TOKENS,
+	DEFAULT_AI_MAX_STEPS,
+	DEFAULT_AI_MODEL,
+	DEFAULT_AI_PROVIDER,
+	DEFAULT_AI_TIMEOUT_MS,
 	DEFAULT_ALWAYS_INCLUDE_DOCS,
+	DEFAULT_AST_MAX_FILE_BYTES,
+	DEFAULT_AST_MAX_IMPACT_FILES,
 	DEFAULT_JEV_CONCURRENCY,
 	DEFAULT_MAX_FILES_PER_BRIEF,
 } from "./defaults";
@@ -32,6 +48,26 @@ export class ProjectConfig<TId extends string = string> {
 		return this.raw.storage ?? {};
 	}
 
+	/** Config do AST (objeto vazio quando ausente). */
+	get ast(): HoundsmanAst {
+		return this.raw.ast ?? {};
+	}
+
+	/** AST habilitado (default: ligado; falhas de grammar são fail-open). */
+	get astEnabled(): boolean {
+		return this.ast.enabled !== false;
+	}
+
+	get astMaxFileBytes(): number {
+		const value = this.ast.maxFileBytes;
+		return value !== undefined && value > 0 ? value : DEFAULT_AST_MAX_FILE_BYTES;
+	}
+
+	get astMaxImpactFiles(): number {
+		const value = this.ast.maxImpactFiles;
+		return value !== undefined && value >= 0 ? value : DEFAULT_AST_MAX_IMPACT_FILES;
+	}
+
 	get maxFilesPerBrief(): number {
 		const value = this.raw.budgets?.maxFilesPerBrief;
 		return value !== undefined && value > 0 ? value : DEFAULT_MAX_FILES_PER_BRIEF;
@@ -53,4 +89,90 @@ export class ProjectConfig<TId extends string = string> {
 	get docMappings(): readonly (readonly [RegExp, readonly string[]])[] {
 		return this.raw.docMappings;
 	}
+
+	/** Config de IA (objeto vazio quando ausente). */
+	get ai(): HoundsmanAi {
+		return this.raw.ai ?? {};
+	}
+
+	/** IA habilitada (default: ligada; sem chave é fail-open). */
+	get aiEnabled(): boolean {
+		return this.ai.enabled !== false;
+	}
+
+	get aiProvider(): AiProviderKind {
+		return this.ai.provider ?? DEFAULT_AI_PROVIDER;
+	}
+
+	get aiModel(): string {
+		const value = this.ai.model?.trim();
+		return value && value.length > 0 ? value : DEFAULT_AI_MODEL;
+	}
+
+	get aiConcurrency(): number {
+		return positive(this.ai.concurrency, DEFAULT_AI_CONCURRENCY);
+	}
+
+	get aiMaxSteps(): number {
+		return positive(this.ai.maxSteps, DEFAULT_AI_MAX_STEPS);
+	}
+
+	get aiMaxOutputTokens(): number {
+		return positive(this.ai.maxOutputTokens, DEFAULT_AI_MAX_OUTPUT_TOKENS);
+	}
+
+	get aiTemperature(): number {
+		const value = this.ai.temperature;
+		return typeof value === "number" && Number.isFinite(value) ? value : 0;
+	}
+
+	get aiTimeoutMs(): number {
+		return positive(this.ai.timeoutMs, DEFAULT_AI_TIMEOUT_MS);
+	}
+
+	get aiMaxCallsPerReview(): number {
+		return positive(this.ai.maxCallsPerReview, DEFAULT_AI_MAX_CALLS_PER_REVIEW);
+	}
+
+	/** Teto de tokens por review (0/ausente = sem teto). */
+	get aiMaxTokensPerReview(): number | undefined {
+		const value = this.ai.maxTokensPerReview;
+		return value !== undefined && value > 0 ? value : undefined;
+	}
+
+	/** Features resolvidas com defaults (`context`/`brief` ligadas). */
+	get aiFeatures(): Required<HoundsmanAiFeatures> {
+		const features = this.ai.features ?? {};
+		return {
+			context: features.context !== false,
+			brief: features.brief !== false,
+			classification: features.classification === true,
+			preAnalysis: features.preAnalysis === true,
+			verify: features.verify === true,
+		};
+	}
+
+	/** Modelo efetivo de um watchdog (override por watchdog ou global). */
+	aiModelFor(watchdogId: string): string {
+		const override = this.ai.watchdogs?.[watchdogId]?.model?.trim();
+		return override && override.length > 0 ? override : this.aiModel;
+	}
+
+	/** Passos efetivos de um watchdog (override por watchdog ou global). */
+	aiMaxStepsFor(watchdogId: string): number {
+		return positive(this.ai.watchdogs?.[watchdogId]?.maxSteps, this.aiMaxSteps);
+	}
+
+	/** Tokens de saída efetivos de um watchdog. */
+	aiMaxOutputTokensFor(watchdogId: string): number {
+		return positive(
+			this.ai.watchdogs?.[watchdogId]?.maxOutputTokens,
+			this.aiMaxOutputTokens,
+		);
+	}
+}
+
+/** Inteiro positivo ou o default. */
+function positive(value: number | undefined, fallback: number): number {
+	return value !== undefined && Number.isFinite(value) && value > 0 ? value : fallback;
 }