@payconductor/houndsman 0.4.0 → 0.6.0

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;
 }

package/src/core/registry-check.ts

@@ -6,8 +6,10 @@
  */
 
 import type { HoundsmanConfig } from "./config";
+import { env } from "./env";
 import { JevQuestionFactory } from "./jev";
 import { renderReport, sanitizeBranch } from "./report-builder";
+import { hasExplicitPolarity } from "./rule-text";
 import type { WatchdogMeta } from "./types";
 
 /** `id` da definição bate com a chave; `description` não vazio. */
@@ -27,17 +29,56 @@ function checkDefinitions(config: HoundsmanConfig, problems: string[]): void {
 	}
 }
 
-/** Todo watchdog precisa declarar ao menos um arquivo em `classify`. */
+/** Todo watchdog precisa declarar ao menos um arquivo em `classify` (fallback isento). */
 function checkClassification(config: HoundsmanConfig, problems: string[]): void {
 	for (const id of config.watchdogIds) {
 		const def = config.watchdogs[id];
 		if (!def) continue;
+		if (def.fallback) continue;
 		if (!def.classify || def.classify.length === 0) {
 			problems.push(`Watchdog '${id}' não declara nenhum padrão em 'classify'`);
 		}
 	}
 }
 
+/** Fallback: no máximo um; `classify` é ignorado; precisa de regras. */
+function checkFallbacks(config: HoundsmanConfig, warnings: string[]): void {
+	const fallbacks = config.watchdogIds.filter(
+		(id) => config.watchdogs[id]?.fallback === true,
+	);
+	if (fallbacks.length > 1) {
+		warnings.push(
+			`Mais de um watchdog fallback (${fallbacks.join(", ")}); o primeiro declarado vence.`,
+		);
+	}
+	for (const id of fallbacks) {
+		const def = config.watchdogs[id];
+		if (!def) continue;
+		if (def.classify && def.classify.length > 0) {
+			warnings.push(`watchdogs['${id}'] é fallback — 'classify' é ignorado.`);
+		}
+		if (def.rules.length === 0) {
+			warnings.push(`Watchdog fallback '${id}' não declara nenhuma regra.`);
+		}
+	}
+}
+
+/** Findings emergentes exigem ao menos uma regra de lógica/domínio como piso. */
+function checkEmergent(config: HoundsmanConfig, warnings: string[]): void {
+	for (const id of config.watchdogIds) {
+		const def = config.watchdogs[id];
+		if (!def?.allowEmergentFindings) continue;
+		const hasGeneric = def.rules.some((rule) =>
+			/l[oó]gica|dom[ií]nio/i.test(rule.text),
+		);
+		if (!hasGeneric) {
+			warnings.push(
+				`watchdogs['${id}'].allowEmergentFindings sem regra de lógica/domínio — o piso fica implícito.`,
+			);
+		}
+	}
+}
+
 /** Smoke test dos helpers críticos de renderização. */
 function checkRendering(config: HoundsmanConfig, problems: string[]): void {
 	if (sanitizeBranch("feature/x") !== "feature-x") {
@@ -106,9 +147,6 @@ function checkJevSpecs(config: HoundsmanConfig, problems: string[]): number {
 	return generated;
 }
 
-/** Prefixos de polaridade aceitos no texto da regra (§ Convenções de escrita). */
-const POLARITY_PREFIX = /^(promover|evitar|não|nao|nunca)\b/i;
-
 /**
  * Aviso **não bloqueante** para regra sem polaridade explícita: o texto deve
  * começar com `Promover:` (DEVE acontecer) ou `Evitar:`/`Não`/`Nunca` (NÃO DEVE).
@@ -119,7 +157,7 @@ function checkRulePolarity(config: HoundsmanConfig, warnings: string[]): void {
 		if (!def) continue;
 		def.rules.forEach((rule, index) => {
 			const text = rule.text.trim();
-			if (!text || POLARITY_PREFIX.test(text)) return;
+			if (!text || hasExplicitPolarity(text)) return;
 			warnings.push(
 				`Regra sem polaridade explícita em ${id} (rule-${index}): ${rule.text}`,
 			);
@@ -169,7 +207,7 @@ function checkMetadataPrecision(config: HoundsmanConfig, warnings: string[]): vo
 			const items = def[field];
 			if (!items) continue;
 			items.forEach((item, index) => {
-				if (!POLARITY_PREFIX.test(item.trim())) return;
+				if (!hasExplicitPolarity(item)) return;
 				warnings.push(
 					`Texto de regra em ${id}.${field}[${index}] — a regra vive só em 'rules': ${item}`,
 				);
@@ -192,6 +230,106 @@ function checkBudgets(config: HoundsmanConfig, warnings: string[]): void {
 	}
 }
 
+/** Valida a configuração do AST (a disponibilidade das grammars é checada no doctor). */
+function checkAstConfig(
+	config: HoundsmanConfig,
+	problems: string[],
+	warnings: string[],
+): void {
+	const ast = config.ast;
+	if (!ast) return;
+
+	if (ast.maxFileBytes !== undefined && ast.maxFileBytes <= 0) {
+		warnings.push(
+			`ast.maxFileBytes = ${ast.maxFileBytes} — não-positivo; usando o default.`,
+		);
+	}
+	if (ast.maxImpactFiles !== undefined && ast.maxImpactFiles < 0) {
+		warnings.push(
+			`ast.maxImpactFiles = ${ast.maxImpactFiles} — negativo; impacto será desabilitado.`,
+		);
+	}
+	const valid = new Set(["typescript", "tsx", "javascript"]);
+	for (const [extension, language] of Object.entries(ast.languages ?? {})) {
+		if (!valid.has(language)) {
+			problems.push(
+				`ast.languages['${extension}'] = '${language}' (esperado typescript|tsx|javascript)`,
+			);
+		}
+	}
+	for (const [alias, target] of Object.entries(ast.aliases ?? {})) {
+		if (!alias.trim() || !target.trim()) {
+			warnings.push(`ast.aliases['${alias}'] vazio — alias ignorado.`);
+		}
+	}
+}
+
+/** Valida a configuração de IA (sem exigir chave — fail-open). */
+function checkAiConfig(
+	config: HoundsmanConfig,
+	problems: string[],
+	warnings: string[],
+): void {
+	const ai = config.ai;
+	if (!ai) return;
+
+	const validProviders = new Set(["deepseek", "openai", "anthropic"]);
+	if (ai.provider !== undefined && !validProviders.has(ai.provider)) {
+		problems.push(
+			`ai.provider = '${ai.provider}' (esperado deepseek|openai|anthropic)`,
+		);
+	}
+	if (ai.enabled !== false && ai.model !== undefined && !ai.model.trim()) {
+		warnings.push("ai.model vazio — usando o default.");
+	}
+	for (const key of [
+		"concurrency",
+		"maxSteps",
+		"maxOutputTokens",
+		"timeoutMs",
+	] as const) {
+		const value = ai[key];
+		if (value !== undefined && value <= 0) {
+			warnings.push(`ai.${key} = ${value} — não-positivo; usando o default.`);
+		}
+	}
+	if (ai.maxCallsPerReview !== undefined && ai.maxCallsPerReview <= 0) {
+		warnings.push(
+			`ai.maxCallsPerReview = ${ai.maxCallsPerReview} — não-positivo; usando o default.`,
+		);
+	}
+	if (ai.maxTokensPerReview !== undefined && ai.maxTokensPerReview < 0) {
+		warnings.push(
+			`ai.maxTokensPerReview = ${ai.maxTokensPerReview} — negativo; sem teto.`,
+		);
+	}
+	for (const [id, override] of Object.entries(ai.watchdogs ?? {})) {
+		if (!config.watchdogIds.includes(id)) {
+			warnings.push(`ai.watchdogs['${id}'] não corresponde a nenhum watchdog.`);
+		}
+		if (override.maxSteps !== undefined && override.maxSteps <= 0) {
+			warnings.push(
+				`ai.watchdogs['${id}'].maxSteps não-positivo — usando o default.`,
+			);
+		}
+	}
+
+	const provider = ai.provider ?? "deepseek";
+	if (validProviders.has(provider) && ai.enabled !== false) {
+		const credential =
+			provider === "deepseek"
+				? env.deepSeekApiKey
+				: provider === "openai"
+					? env.openAiApiKey
+					: env.anthropicApiKey;
+		if (!credential) {
+			warnings.push(
+				`ai.provider '${provider}' sem credencial — features de IA ficam fail-open.`,
+			);
+		}
+	}
+}
+
 export function checkRegistry(config: HoundsmanConfig): {
 	problems: string[];
 	warnings: string[];
@@ -202,11 +340,15 @@ export function checkRegistry(config: HoundsmanConfig): {
 
 	checkDefinitions(config, problems);
 	checkClassification(config, problems);
+	checkFallbacks(config, warnings);
+	checkEmergent(config, warnings);
 	checkRendering(config, problems);
 	checkRulePolarity(config, warnings);
 	checkRuleDuplication(config, warnings);
 	checkMetadataPrecision(config, warnings);
 	checkBudgets(config, warnings);
+	checkAstConfig(config, problems, warnings);
+	checkAiConfig(config, problems, warnings);
 	const jevQuestions = checkJevSpecs(config, problems);
 
 	return { problems, warnings, jevQuestions };

package/src/core/renderers/manifest-writer.ts

@@ -6,6 +6,7 @@
  * findings apontam para o staging da review.
  */
 
+import type { AiUsage } from "../ai/types";
 import { Classification } from "../domain/classification";
 import type { ClassificationResult } from "../file-classifier";
 import type { JevCandidatesFile } from "../jev";
@@ -22,6 +23,27 @@ export type ManifestOptions = {
 	head: string;
 };
 
+/** Resumo do AST no manifesto. */
+export type ManifestAst = {
+	enabled: boolean;
+	languages: string[];
+	files: number;
+	impact: {
+		affectedFiles: number;
+		importers: number;
+		exportedChanges: number;
+	};
+};
+
+/** Resumo da IA no manifesto (só quando a IA foi usada). */
+export type ManifestAi = {
+	enabled: boolean;
+	provider: string;
+	model: string;
+	briefPlans: number;
+	usage: AiUsage;
+};
+
 /** Classificação enriquecida gravada pelo prepare (modo + incremental). */
 export type ManifestClassification = ClassificationResult & {
 	headSha?: string;
@@ -57,6 +79,8 @@ export class ManifestWriter {
 		activeIds: string[],
 		pending: string[],
 		jev: JevCandidatesFile,
+		ast?: ManifestAst,
+		ai?: ManifestAi,
 	): void {
 		const view = Classification.from(classification);
 		const maxFilesPerBrief = this.project.maxFilesPerBrief;
@@ -65,9 +89,11 @@ export class ManifestWriter {
 		const watchdogs = activeIds.map((id) => {
 			const selection = view.budgetFor(id, maxFilesPerBrief);
 			filesOverBudget += selection.overflow.length;
+			const domain = this.project.watchdogs.find(id);
 			return {
 				id,
 				name: this.project.watchdogs.nameOf(id),
+				...(domain?.definition.fallback ? { fallback: true } : {}),
 				files: selection.selected,
 				overflow: selection.overflow.length,
 				brief: this.work.briefFile(id),
@@ -109,6 +135,13 @@ export class ManifestWriter {
 						skipped: jev.skipped?.length ?? 0,
 					}
 				: { available: false, reason: jev.reason },
+			ast: ast ?? {
+				enabled: false,
+				languages: [],
+				files: 0,
+				impact: { affectedFiles: 0, importers: 0, exportedChanges: 0 },
+			},
+			ai,
 			deleted: classification.deleted,
 			unclassified: classification.unclassified,
 			excludedCount: classification.excludedCount,

package/src/core/renderers/resume-renderer.ts

@@ -0,0 +1,151 @@
+/**
+ * Resumo final da revisão (`review-resume.md`).
+ *
+ * Artefato somente-leitura para humanos: não entra em briefs, não é lido pelos
+ * watchdogs e não participa de nenhuma etapa seguinte. Une o contexto de
+ * negócio da PR aos números técnicos diretos da revisão, com limite de
+ * `RESUME_MAX_CHARS`.
+ */
+
+import type {
+	ContextSummary,
+	MergedFinding,
+	WatchdogNameResolver,
+} from "../report-builder";
+import { systemClock } from "../services/clock";
+
+/** Teto de caracteres do artefato (inclui cabeçalho e quebras de linha). */
+export const RESUME_MAX_CHARS = 2500;
+
+/** Dados de classificação usados no resumo. */
+export type ResumeClassification = {
+	files: Record<string, { status: string }>;
+	watchdogs: Record<string, string[]>;
+};
+
+export type ReviewResumeInput = {
+	branch: string;
+	/** `YYYY-MM-DD`; default: data corrente do sistema. */
+	date?: string;
+	context?: ContextSummary | null;
+	classification: ResumeClassification;
+	findings: readonly MergedFinding[];
+	nameOf?: WatchdogNameResolver;
+};
+
+const identityName: WatchdogNameResolver = (id) => id;
+
+const STATUS_BY_SEVERITY: Record<"blocking" | "attention" | "clean", string> = {
+	blocking: "❌ Mudanças necessárias",
+	attention: "⚠️ Aprovado com ressalvas",
+	clean: "✅ Aprovado",
+};
+
+/** Corta o texto em `max` caracteres, sinalizando com reticências. */
+function truncate(value: string, max: number): string {
+	const text = value.trim().replace(/\s+/g, " ");
+	return text.length <= max ? text : `${text.slice(0, max - 1).trimEnd()}…`;
+}
+
+function plural(count: number, singular: string, plural: string): string {
+	return `${count} ${count === 1 ? singular : plural}`;
+}
+
+/** Resumo de negócio: contexto da PR; sem ele, o alcance da branch. */
+function businessSection(input: ReviewResumeInput): string[] {
+	const context = input.context;
+	const hasContext =
+		context?.available === true &&
+		Boolean(
+			context.objective ||
+				context.motivation ||
+				(context.changeSummary && context.changeSummary.length > 0),
+		);
+	const lines = ["## Resumo de negócio", ""];
+
+	if (!hasContext) {
+		const domainCount = Object.keys(input.classification.watchdogs).length;
+		lines.push(
+			`A branch \`${input.branch}\` altera ${plural(
+				Object.keys(input.classification.files).length,
+				"arquivo",
+				"arquivos",
+			)} em ${plural(domainCount, "domínio", "domínios")} de revisão.`,
+			"Sem resumo de contexto da PR disponível.",
+			"",
+		);
+		return lines;
+	}
+
+	if (context.objective) lines.push(context.objective, "");
+	if (context.motivation) lines.push(`**Por quê:** ${context.motivation}`, "");
+	if (context.changeSummary && context.changeSummary.length > 0) {
+		for (const item of context.changeSummary.slice(0, 4)) {
+			lines.push(`- ${truncate(item, 180)}`);
+		}
+		lines.push("");
+	}
+	return lines;
+}
+
+/** Achados que exigem ação, em formato direto (máximo 5). */
+function technicalSection(
+	findings: readonly MergedFinding[],
+	nameOf: WatchdogNameResolver,
+): string[] {
+	const relevant = findings
+		.filter(
+			(finding) =>
+				finding.severity === "blocking" || finding.severity === "attention",
+		)
+		.slice(0, 5);
+	const lines = ["## Pontos técnicos", ""];
+	if (relevant.length === 0) {
+		lines.push("- Nenhum bloqueio ou ponto de atenção.", "");
+		return lines;
+	}
+	for (const finding of relevant) {
+		const location = finding.line ? `${finding.file}:${finding.line}` : finding.file;
+		const watchdogs = finding.watchdogs.map((id) => nameOf(id)).join(", ");
+		lines.push(
+			`- \`${location}\` — ${truncate(finding.message, 130)}${watchdogs ? ` _(${watchdogs})_` : ""}`,
+		);
+	}
+	lines.push("");
+	return lines;
+}
+
+/** Garante o teto de caracteres cortando em uma quebra de linha. */
+function clamp(markdown: string, max: number): string {
+	if (markdown.length <= max) return markdown;
+	const head = markdown.slice(0, max - 2);
+	const cut = head.lastIndexOf("\n");
+	return `${(cut > 0 ? head.slice(0, cut) : head).trimEnd()}\n…`;
+}
+
+/**
+ * Renderiza o resumo final. Determinístico e sem chamadas externas: o texto
+ * nasce do contexto já disponível e dos findings consolidados.
+ */
+export function renderReviewResume(input: ReviewResumeInput): string {
+	const nameOf = input.nameOf ?? identityName;
+	const blockers = input.findings.filter((f) => f.severity === "blocking").length;
+	const attention = input.findings.filter((f) => f.severity === "attention").length;
+	const status =
+		blockers > 0
+			? STATUS_BY_SEVERITY.blocking
+			: attention > 0
+				? STATUS_BY_SEVERITY.attention
+				: STATUS_BY_SEVERITY.clean;
+
+	const lines = [
+		`# Resumo da revisão — ${input.branch}`,
+		"",
+		`**Data:** ${input.date ?? systemClock().slice(0, 10)} · **Status:** ${status}`,
+		"",
+		...businessSection(input),
+		...technicalSection(input.findings, nameOf),
+	];
+
+	return clamp(`${lines.join("\n").trimEnd()}\n`, RESUME_MAX_CHARS);
+}

package/src/core/report-builder.ts

@@ -294,6 +294,7 @@ function renderConclusion(counts: Record<Severity, number>): string[] {
 		"",
 		`**Status:** ${status}`,
 		`**Resumo:** ${counts.blocking} violações bloqueantes, ${counts.attention} pontos de atenção, ${counts.suggestion} sugestões e ${counts.nit} nits.`,
+		"",
 	];
 }
 
@@ -453,6 +454,12 @@ export function renderReport(
 
 	if (context) lines.push(...renderContext(context));
 
+	// Sumário primeiro: quem lê o review.md vê domínios, cobertura e conclusão
+	// antes dos pontos específicos.
+	lines.push(...renderDomainIndex(domains));
+	lines.push(...renderCoverage(reports, coverage, nameOf));
+	lines.push(...renderConclusion(counts));
+
 	lines.push(...renderFindingsSections(merged, nameOf));
 
 	if (merged.length === 0) {
@@ -463,9 +470,5 @@ export function renderReport(
 		lines.push(...renderUnconfirmedCandidates(candidates, merged));
 	}
 
-	lines.push(...renderDomainIndex(domains));
-	lines.push(...renderCoverage(reports, coverage, nameOf));
-	lines.push(...renderConclusion(counts));
-
 	return lines.join("\n");
 }