@payconductor/houndsman 0.5.0 → 0.6.0

package/src/core/ai/prompts/brief.ts

@@ -0,0 +1,87 @@
+/**
+ * Prompt do enriquecimento de brief (`AiBriefEnricher`).
+ *
+ * A saída é apenas um **plano sugerido** (foco, perguntas e riscos). Ela não
+ * pode criar regras nem achados.
+ */
+
+import type { AstFileBrief } from "../../ast/types";
+import type { ChurnMap, Rule, WatchdogRenderContext } from "../../types";
+import { buildSystem } from "./base";
+
+/** Entrada do prompt do brief. */
+export type BriefPromptInput = {
+	watchdogId: string;
+	name: string;
+	description: string;
+	scope: string;
+	rules: readonly Rule[];
+	files: readonly string[];
+	churn?: ChurnMap;
+	context?: WatchdogRenderContext | null;
+	ast?: readonly AstFileBrief[];
+	docs?: readonly string[];
+};
+
+/** Instruções de sistema do enriquecimento. */
+export function briefInstructions(): string {
+	return buildSystem(
+		"Você é um revisor sênior que prepara um plano de leitura para um watchdog (revisor) especializado.",
+		[
+			"As regras fornecidas são o PISO da revisão, não o teto.",
+			"Além delas, procure riscos de consistência lógica: nome/contrato vs comportamento (ex.: `fazA` que faz `fazB`), fluxos incompletos, estados inválidos, off-by-one e bordas.",
+			"Procure também riscos do domínio de negócio: transições de estado, idempotência, arredondamento, timezone, autorização e invariantes implícitas.",
+			"Sugira foco de leitura (até 5), perguntas de verificação (até 3), riscos (até 3), verificações de lógica (até 3) e de domínio (até 3).",
+			"Sugira verificações, nunca afirme violação; não crie regra nova nem invente arquivo, linha ou achado.",
+			"Se uma suspeita não couber em nenhuma regra, coloque-a em `logic`/`domain` como pergunta de verificação.",
+			"Não repita o texto literal das regras; o brief já as contém.",
+		],
+	);
+}
+
+/** Prompt do usuário com o contexto compactado do watchdog. */
+export function briefPrompt(input: BriefPromptInput): string {
+	const lines = [
+		`Watchdog: ${input.name} (${input.watchdogId})`,
+		`Escopo: ${input.scope}`,
+		`Objetivo: ${input.description}`,
+		"",
+		"## Regras",
+		...input.rules.map((rule) => `- [${rule.severity}] ${rule.text}`),
+		"",
+		`## Arquivos (${input.files.length})`,
+		...input.files.slice(0, 40).map((file) => {
+			const churn = input.churn?.[file];
+			return `- ${file}${churn ? ` (+${churn.additions}/−${churn.deletions})` : ""}`;
+		}),
+	];
+	if (input.context) {
+		lines.push("", "## Contexto da PR");
+		if (input.context.objective) lines.push(`Objetivo: ${input.context.objective}`);
+		if (input.context.motivation)
+			lines.push(`Motivação: ${input.context.motivation}`);
+		for (const item of input.context.changeSummary ?? []) lines.push(`- ${item}`);
+	}
+	if (input.ast && input.ast.length > 0) {
+		lines.push("", "## Estrutura (AST)");
+		for (const entry of input.ast) {
+			const delta = entry.delta;
+			lines.push(
+				`- ${entry.file}: +${delta.addedSymbols.length} −${delta.removedSymbols.length} ~${delta.modifiedSymbols.length} símbolo(s)`,
+			);
+		}
+	}
+	if (input.docs && input.docs.length > 0) {
+		lines.push("", "## Docs disponíveis", ...input.docs.map((doc) => `- ${doc}`));
+	}
+	lines.push(
+		"",
+		"## Revisão além das regras",
+		"As regras são o piso. Aponte verificações de consistência lógica e de domínio",
+		"que mereçam inspeção mesmo sem regra explícita (nome vs comportamento, estados,",
+		"transições, idempotência, bordas). Sugira verificações; não afirme violações.",
+		"",
+		"Produza o plano de revisão em JSON (focus, questions, risks, logic, domain).",
+	);
+	return lines.join("\n");
+}

package/src/core/ai/prompts/classification.ts

@@ -0,0 +1,36 @@
+/**
+ * Prompt da classificação fallback (`AiClassifier`).
+ */
+
+import { buildSystem } from "./base";
+
+/** Entrada do prompt de classificação. */
+export type ClassificationPromptInput = {
+	files: readonly string[];
+	watchdogs: readonly { id: string; name: string; scope: string }[];
+};
+
+/** Instruções de sistema. */
+export function classificationInstructions(): string {
+	return buildSystem(
+		"Você classifica arquivos alterados nos domínios (watchdogs) de uma revisão.",
+		[
+			"Atribua cada arquivo ao watchdog cujo escopo melhor corresponde.",
+			"Se nenhum watchdog servir, omita o arquivo.",
+			"Use apenas ids de watchdog fornecidos.",
+		],
+	);
+}
+
+/** Prompt do usuário. */
+export function classificationPrompt(input: ClassificationPromptInput): string {
+	return [
+		"## Watchdogs",
+		...input.watchdogs.map((w) => `- ${w.id}: ${w.name} — ${w.scope}`),
+		"",
+		"## Arquivos",
+		...input.files.slice(0, 100).map((file) => `- ${file}`),
+		"",
+		"Produza as atribuições em JSON.",
+	].join("\n");
+}

package/src/core/ai/prompts/context.ts

@@ -0,0 +1,29 @@
+/**
+ * Prompt do resumo de contexto da PR (`AiContextSummarizer`).
+ */
+
+import { buildSystem, clip } from "./base";
+
+/** Instruções de sistema do resumo. */
+export function contextInstructions(): string {
+	return buildSystem(
+		"Você resume o contexto de uma Pull Request para revisores técnicos.",
+		[
+			"Objetivo em uma frase (máx. 200 caracteres).",
+			"Motivação em uma frase (máx. 240 caracteres).",
+			"Resumo das alterações em até 4 bullets (máx. 160 caracteres cada).",
+			"Não invente informação ausente do contexto.",
+		],
+	);
+}
+
+/** Prompt do usuário com o contexto bruto da PR. */
+export function contextPrompt(raw: string): string {
+	return [
+		"Resuma o contexto da PR abaixo.",
+		"",
+		"```json",
+		clip(raw, 12_000),
+		"```",
+	].join("\n");
+}

package/src/core/ai/prompts/pre-analysis.ts

@@ -0,0 +1,49 @@
+/**
+ * Prompt da pré-análise por IA (`AiPreAnalyzer`).
+ *
+ * Candidatos não são achados: são indícios para o watchdog confirmar.
+ */
+
+import type { Rule } from "../../types";
+import { buildSystem } from "./base";
+
+/** Entrada do prompt. */
+export type PreAnalysisPromptInput = {
+	watchdogId: string;
+	name: string;
+	rules: readonly Rule[];
+	files: readonly { file: string; snippet: string }[];
+};
+
+/** Instruções de sistema. */
+export function preAnalysisInstructions(): string {
+	return buildSystem(
+		"Você faz uma pré-análise de possíveis violações de regras em um diff.",
+		[
+			"Produza candidatos apenas quando houver indício concreto.",
+			"Use o texto de uma das regras fornecidas.",
+			"Confiança calibrada entre 0 e 1; prefira valores baixos na dúvida.",
+			"Não invente arquivos.",
+		],
+	);
+}
+
+/** Prompt do usuário. */
+export function preAnalysisPrompt(input: PreAnalysisPromptInput): string {
+	return [
+		`Watchdog: ${input.name} (${input.watchdogId})`,
+		"",
+		"## Regras",
+		...input.rules.map((rule) => `- [${rule.severity}] ${rule.text}`),
+		"",
+		"## Arquivos e trechos",
+		...input.files.flatMap((item) => [
+			`### ${item.file}`,
+			"```",
+			item.snippet,
+			"```",
+		]),
+		"",
+		"Produza os candidatos em JSON.",
+	].join("\n");
+}

package/src/core/ai/prompts/verify.ts

@@ -0,0 +1,40 @@
+/**
+ * Prompt de confirmação de findings (`AiVerifier`).
+ */
+
+import { buildSystem } from "./base";
+
+/** Entrada do prompt. */
+export type VerifyPromptInput = {
+	findings: readonly {
+		id: string;
+		rule: string;
+		file: string;
+		line: number | null;
+		message: string;
+		snippets: string;
+	}[];
+};
+
+/** Instruções de sistema. */
+export function verifyInstructions(): string {
+	return buildSystem("Você confirma ou refuta achados de revisão de código.", [
+		"Para cada achado, decida se a violação persiste no código atual.",
+		"Baseie-se apenas no trecho fornecido.",
+		"Confiança calibrada entre 0 e 1.",
+		"Não invente ids.",
+	]);
+}
+
+/** Prompt do usuário. */
+export function verifyPrompt(input: VerifyPromptInput): string {
+	const blocks = input.findings.flatMap((finding) => [
+		`### ${finding.id} — ${finding.rule}`,
+		`Arquivo: ${finding.file}${finding.line ? `:${finding.line}` : ""}`,
+		`Achado: ${finding.message}`,
+		"```",
+		finding.snippets,
+		"```",
+	]);
+	return [...blocks, "", "Produza os vereditos em JSON."].join("\n");
+}

package/src/core/ai/schemas.ts

@@ -0,0 +1,110 @@
+/**
+ * Schemas Zod da camada de IA.
+ *
+ * Espelham os contratos existentes (`ContextSummary`, `WatchdogReport`) e os
+ * planos das features. Todo schema é fechado por validação: saída inválida do
+ * modelo vira falha fail-open, nunca dado corrompido.
+ */
+
+import { z } from "zod";
+
+export const SeveritySchema = z.enum(["blocking", "attention", "suggestion", "nit"]);
+
+/** Resumo da PR (`context-summary.json`). */
+export const ContextSummarySchema = z.object({
+	available: z.boolean(),
+	source: z
+		.object({
+			number: z.number().optional(),
+			title: z.string().optional(),
+			url: z.string().optional(),
+			base: z.string().optional(),
+			head: z.string().optional(),
+		})
+		.optional(),
+	objective: z.string().max(200).optional(),
+	motivation: z.string().max(240).optional(),
+	changeSummary: z.array(z.string().max(160)).max(4).optional(),
+});
+export type ContextSummaryPlan = z.infer<typeof ContextSummarySchema>;
+
+/** Plano de revisão sugerido por IA para um brief. */
+export const BriefPlanSchema = z.object({
+	focus: z.array(z.string()).max(5).default([]),
+	questions: z.array(z.string()).max(3).default([]),
+	risks: z.array(z.string()).max(3).default([]),
+	/** Verificações de consistência lógica (fora das regras explícitas). */
+	logic: z.array(z.string()).max(3).default([]),
+	/** Riscos do domínio de negócio (fora das regras explícitas). */
+	domain: z.array(z.string()).max(3).default([]),
+});
+export type BriefPlan = z.infer<typeof BriefPlanSchema>;
+
+/** Classificação de arquivos não classificados. */
+export const ClassificationSchema = z.object({
+	assignments: z
+		.array(
+			z.object({
+				file: z.string(),
+				watchdogId: z.string(),
+				confidence: z.number().min(0).max(1).optional(),
+			}),
+		)
+		.max(200)
+		.default([]),
+});
+export type AiClassification = z.infer<typeof ClassificationSchema>;
+
+/** Candidato de pré-análise (`JevCandidate`-like). */
+export const CandidateSchema = z.object({
+	candidates: z
+		.array(
+			z.object({
+				file: z.string(),
+				watchdogId: z.string(),
+				rule: z.string(),
+				severity: SeveritySchema,
+				confidence: z.number().min(0).max(1),
+				reason: z.string().optional(),
+			}),
+		)
+		.max(200)
+		.default([]),
+});
+export type AiCandidate = z.infer<typeof CandidateSchema>["candidates"][number];
+
+/** Relatório de um watchdog (espelha `OUTPUT-FORMAT.md`). */
+export const WatchdogReportSchema = z.object({
+	watchdogId: z.string(),
+	reviewedFiles: z.array(z.string()).default([]),
+	skipped: z.array(z.string()).default([]),
+	findings: z
+		.array(
+			z.object({
+				rule: z.string(),
+				severity: SeveritySchema,
+				file: z.string(),
+				line: z.number().int().positive().optional(),
+				message: z.string(),
+				action: z.string(),
+				evidence: z.string().optional(),
+			}),
+		)
+		.default([]),
+});
+export type AiWatchdogReport = z.infer<typeof WatchdogReportSchema>;
+
+/** Veredito de verificação (confirma/refuta um finding ambíguo). */
+export const VerifySchema = z.object({
+	verdicts: z
+		.array(
+			z.object({
+				id: z.string(),
+				persisting: z.boolean(),
+				confidence: z.number().min(0).max(1),
+				reason: z.string().optional(),
+			}),
+		)
+		.default([]),
+});
+export type AiVerdict = z.infer<typeof VerifySchema>["verdicts"][number];

package/src/core/ai/types.ts

@@ -0,0 +1,76 @@
+/**
+ * Contratos genéricos da camada de IA (biblioteca).
+ *
+ * `core/ai` não conhece o harness: expõe modelo, uso, tools e resultado. O
+ * harness nativo (`src/harness/`) consome estes contratos.
+ */
+
+import type { ZodType, ZodTypeAny } from "zod";
+import type { AiProviderKind } from "../config";
+
+/** Uso de tokens de uma chamada (ou acumulado de uma review). */
+export type AiUsage = {
+	inputTokens: number;
+	outputTokens: number;
+	totalTokens: number;
+	calls: number;
+};
+
+/** Uso zerado (novo objeto — nunca compartilhe para mutação). */
+export function emptyUsage(): AiUsage {
+	return { inputTokens: 0, outputTokens: 0, totalTokens: 0, calls: 0 };
+}
+
+/** Soma dois usos sem mutar os originais. */
+export function addUsage(a: AiUsage, b: AiUsage): AiUsage {
+	return {
+		inputTokens: a.inputTokens + b.inputTokens,
+		outputTokens: a.outputTokens + b.outputTokens,
+		totalTokens: a.totalTokens + b.totalTokens,
+		calls: a.calls + b.calls,
+	};
+}
+
+/** Tool exposta ao modelo (execução já vinculada a um contexto). */
+export type AiTool = {
+	name: string;
+	description: string;
+	inputSchema: ZodTypeAny;
+	execute(input: unknown): Promise<string>;
+};
+
+/** Pedido de geração de modelo (texto ou objeto estruturado). */
+export type ModelRequest<T> = {
+	/** Instruções de sistema. */
+	instructions?: string;
+	/** Prompt do usuário. */
+	prompt: string;
+	/** Tools disponíveis para o loop do modelo. */
+	tools?: Record<string, AiTool>;
+	/** Schema de saída (quando ausente, a saída é texto). */
+	outputSchema?: ZodType<T>;
+	maxSteps?: number;
+	maxOutputTokens?: number;
+	temperature?: number;
+	signal?: AbortSignal;
+};
+
+/** Resposta do modelo. */
+export type ModelResponse<T> = {
+	output: T;
+	usage: AiUsage;
+	steps: number;
+	finishReason: string;
+};
+
+/** Provider de modelo (adaptador do AI SDK ou fake nos testes). */
+export interface ModelProvider {
+	readonly name: AiProviderKind;
+	readonly modelId: string;
+	generate<T>(request: ModelRequest<T>): Promise<ModelResponse<T>>;
+}
+
+/** Resultado fail-open de uma chamada de IA. */
+export type AiResult<T> =
+	| { ok: true; output: T; usage: AiUsage; model: string }
+	| { ok: false; error: string; usage?: AiUsage };

package/src/core/ai/usage-budget.ts

@@ -0,0 +1,75 @@
+/**
+ * Orçamento de IA por review (chamadas e tokens).
+ *
+ * O budget é consultado antes de cada chamada e atualizado com o uso real. Ao
+ * estourar, o chamador decide parar (features do core) ou falhar (harness).
+ */
+
+import { AiBudgetError } from "./errors";
+import { type AiUsage, addUsage, emptyUsage } from "./types";
+
+/** Tetos do budget (ausente = sem teto). */
+export type AiBudgetLimits = {
+	maxCalls?: number;
+	maxTokens?: number;
+};
+
+/** Orçamento de uso acumulado. */
+export class AiUsageBudget {
+	private readonly limits: AiBudgetLimits;
+	private readonly total: AiUsage = emptyUsage();
+
+	constructor(limits: AiBudgetLimits = {}) {
+		this.limits = limits;
+	}
+
+	get usage(): AiUsage {
+		return { ...this.total };
+	}
+
+	get maxCalls(): number | undefined {
+		return this.limits.maxCalls;
+	}
+
+	/** `true` quando ainda há orçamento para outra chamada. */
+	get canCall(): boolean {
+		if (
+			this.limits.maxCalls !== undefined &&
+			this.total.calls >= this.limits.maxCalls
+		) {
+			return false;
+		}
+		if (
+			this.limits.maxTokens !== undefined &&
+			this.total.totalTokens >= this.limits.maxTokens
+		) {
+			return false;
+		}
+		return true;
+	}
+
+	/** Lança quando o orçamento acabou. */
+	assertCanCall(): void {
+		if (!this.canCall) throw new AiBudgetError(this.describeExhaustion());
+	}
+
+	/** Registra o uso de uma chamada concluída. */
+	record(usage: AiUsage): void {
+		const merged = addUsage(this.total, usage);
+		this.total.inputTokens = merged.inputTokens;
+		this.total.outputTokens = merged.outputTokens;
+		this.total.totalTokens = merged.totalTokens;
+		this.total.calls = merged.calls;
+	}
+
+	/** Motivo legível do esgotamento. */
+	private describeExhaustion(): string {
+		if (
+			this.limits.maxCalls !== undefined &&
+			this.total.calls >= this.limits.maxCalls
+		) {
+			return `Teto de ${this.limits.maxCalls} chamada(s) de IA por review atingido.`;
+		}
+		return `Teto de ${this.limits.maxTokens ?? 0} token(s) de IA por review atingido.`;
+	}
+}

package/src/core/ai/usage-recorder.ts

@@ -0,0 +1,79 @@
+/**
+ * Registro de uso de IA por review (`ai-usage.json`).
+ *
+ * Guarda uma entrada por chamada (feature, modelo, uso) e o total agregado.
+ * Nunca grava prompt, resposta ou segredo.
+ */
+
+import { systemClock } from "../services/clock";
+import type { StorageProvider } from "../storage/types";
+import { type AiUsage, addUsage, emptyUsage } from "./types";
+
+/** Entrada de uso de uma chamada. */
+export type AiUsageEntry = {
+	feature: string;
+	model: string;
+	at: string;
+	usage: AiUsage;
+};
+
+/** Formato persistido em `ai-usage.json`. */
+export type AiUsageFile = {
+	provider: string;
+	model: string;
+	total: AiUsage;
+	entries: AiUsageEntry[];
+};
+
+/** Acumulador de uso (em memória) com persistência opcional. */
+export class AiUsageRecorder {
+	private readonly entries: AiUsageEntry[] = [];
+	private readonly provider: string;
+	private readonly model: string;
+
+	constructor(provider = "unknown", model = "unknown") {
+		this.provider = provider;
+		this.model = model;
+	}
+
+	/** Registra uma chamada concluída. */
+	record(feature: string, model: string, usage: AiUsage): void {
+		this.entries.push({ feature, model, at: systemClock(), usage: { ...usage } });
+	}
+
+	/** Total agregado de todas as chamadas. */
+	get total(): AiUsage {
+		return this.entries.reduce(
+			(acc, entry) => addUsage(acc, entry.usage),
+			emptyUsage(),
+		);
+	}
+
+	/** Snapshot serializável. */
+	toJSON(): AiUsageFile {
+		return {
+			provider: this.provider,
+			model: this.model,
+			total: this.total,
+			entries: [...this.entries],
+		};
+	}
+
+	/** Serializa para o artefato. */
+	serialize(): string {
+		return `${JSON.stringify(this.toJSON(), null, 2)}\n`;
+	}
+
+	/** Persiste `ai-usage.json` no storage (fail-open). */
+	write(storage: StorageProvider, reviewId: string): void {
+		try {
+			storage.writeArtifact(reviewId, {
+				name: "ai-usage.json",
+				kind: "ai-usage",
+				content: this.serialize(),
+			});
+		} catch {
+			// Observer: nunca derruba a revisão.
+		}
+	}
+}

package/src/core/assets.ts

@@ -14,6 +14,17 @@ export const SKILL_DIR = join(import.meta.dir, "..", "skill");
 /** Diretório de assets de mídia do pacote (root `assets/` — logo etc.). */
 export const MEDIA_DIR = join(import.meta.dir, "..", "..", "assets");
 
+/** Diretório das grammars tree-sitter embarcadas (wasm). */
+export const GRAMMAR_DIR = join(MEDIA_DIR, "grammars");
+
+/** Runtime e grammars copiados para a camada do projeto pelo setup/update. */
+export const GRAMMAR_FILES = [
+	"web-tree-sitter.wasm",
+	"tree-sitter-typescript.wasm",
+	"tree-sitter-tsx.wasm",
+	"tree-sitter-javascript.wasm",
+] as const;
+
 /** Nome do arquivo de schema de output dos watchdogs. */
 export const OUTPUT_FORMAT_FILE = "OUTPUT-FORMAT.md";
 
@@ -29,3 +40,8 @@ export function assetPath(fileName: string): string {
 export function mediaPath(fileName: string): string {
 	return join(MEDIA_DIR, fileName);
 }
+
+/** Caminho absoluto de uma grammar wasm em `assets/grammars/`. */
+export function grammarPath(fileName: string): string {
+	return join(GRAMMAR_DIR, fileName);
+}