@payconductor/houndsman 0.5.0 → 0.7.0

package/src/harness/hunt/review-planner.ts

@@ -0,0 +1,98 @@
+/**
+ * Planejador da review nativa — monta um `AgentContext` por watchdog ativo.
+ *
+ * Lê a classificação já preparada (prepare) e aplica o orçamento por brief.
+ * Nada aqui chama IA.
+ */
+
+import type { AstAnalysis, AstImpact } from "../../core/ast/types";
+import type { HoundsmanConfig } from "../../core/config";
+import type { DiffSource } from "../../core/diff-source";
+import { discoverDocs } from "../../core/doc-discoverer";
+import { selectByBudget } from "../../core/domain/budget";
+import type { RunClassification } from "../../core/engine/review-scope";
+import type { ProjectConfig } from "../../core/project-config";
+import type { ContextSummary } from "../../core/report-builder";
+import type { ChurnMap } from "../../core/types";
+import type { AgentContext } from "../agent/agent-context";
+import { RuleAnalyzer } from "../investigation/rule-analyzer";
+
+/** Entrada do planejador. */
+export type ReviewPlannerInput = {
+	config: HoundsmanConfig;
+	project: ProjectConfig;
+	classification: RunClassification;
+	context: ContextSummary | null;
+	ast: ReadonlyMap<string, AstAnalysis>;
+	impact?: AstImpact;
+	repoRoot: string;
+	diff: DiffSource;
+	/** Branch alvo da review (prompt do agente). */
+	branch: string;
+	/** Filtra um único watchdog (`--watchdog`). */
+	watchdog?: string;
+	maxCalls: number;
+};
+
+/** Um watchdog planejado. */
+export type PlannedWatchdog = {
+	context: AgentContext;
+	files: string[];
+	overflow: string[];
+};
+
+/** Planeja os agentes da review. */
+export class ReviewPlanner {
+	private readonly input: ReviewPlannerInput;
+
+	constructor(input: ReviewPlannerInput) {
+		this.input = input;
+	}
+
+	/** Watchdogs ativos (filtrados) com contexto pronto. */
+	plan(): PlannedWatchdog[] {
+		const { config, project, classification, watchdog } = this.input;
+		const ids = Object.keys(classification.watchdogs).filter(
+			(id) => !watchdog || id === watchdog,
+		);
+		const docs = discoverDocs(Object.keys(classification.files), config);
+		const maxFiles = project.maxFilesPerBrief;
+		const analyzer = new RuleAnalyzer();
+		const planned: PlannedWatchdog[] = [];
+
+		for (const id of ids) {
+			const domain = project.watchdogs.find(id);
+			if (!domain) continue;
+			const churn: ChurnMap = classification.churn;
+			const { selected, overflow } = selectByBudget(
+				classification.watchdogs[id] ?? [],
+				churn,
+				maxFiles,
+			);
+			const rules = analyzer.analyze(domain.rules);
+			planned.push({
+				files: selected,
+				overflow,
+				context: {
+					watchdog: domain,
+					projectName: project.projectName,
+					branch: this.input.branch,
+					files: selected,
+					overflow,
+					deleted: classification.deleted,
+					docs,
+					context: this.input.context,
+					ast: this.input.ast,
+					impact: this.input.impact,
+					outputPath: "",
+					maxSteps: project.aiMaxStepsFor(id),
+					maxCalls: this.input.maxCalls,
+					repoRoot: this.input.repoRoot,
+					diff: this.input.diff,
+					rules,
+				},
+			});
+		}
+		return planned;
+	}
+}

package/src/harness/index.ts

@@ -0,0 +1,36 @@
+/**
+ * Barrel do harness nativo.
+ *
+ * Atenção: `src/skill/` é o harness **externo** (markdown). Este é o runtime de
+ * agentes do próprio houndsman.
+ */
+
+export type { AgentContext } from "./agent/agent-context";
+export { AgentFactory } from "./agent/agent-factory";
+export type { AgentReporter } from "./agent/agent-reporter";
+export { LoggerReporter, SilentReporter } from "./agent/agent-reporter";
+export type { AgentResult } from "./agent/agent-result";
+export { AgentRunner } from "./agent/agent-runner";
+export { AgentScheduler } from "./agent/agent-scheduler";
+export { ReviewAgent } from "./agent/review-agent";
+export { HarnessConfig, type HarnessOverrides } from "./config/harness-config";
+export { HuntHarness } from "./hunt/hunt-harness";
+export { defaultHuntOptions, type HuntOptions, parseHuntArgs } from "./hunt/hunt-options";
+export type { HuntResult } from "./hunt/hunt-result";
+export { AgentState } from "./investigation/agent-state";
+export type {
+	CriticDecision,
+	Evidence,
+	FindingDraft,
+	RuleCoverage,
+} from "./investigation/evidence";
+export { EvidenceVerifier } from "./investigation/evidence-verifier";
+export { FindingCritic } from "./investigation/finding-critic";
+export { InvestigationPlanner } from "./investigation/investigation-planner";
+export { ReviewJournal } from "./investigation/review-journal";
+export { type RuleAnalysis, RuleAnalyzer } from "./investigation/rule-analyzer";
+export type { AgentTool, ToolContext, ToolResult } from "./tools/agent-tool";
+export { type AgentStateName, ToolPolicy } from "./tools/tool-policy";
+export { ToolRegistry } from "./tools/tool-registry";
+export { Toolbox } from "./tools/toolbox";
+export { FindingValidator } from "./validation/finding-validator";

package/src/harness/investigation/agent-state.ts

@@ -0,0 +1,134 @@
+/**
+ * Estado de um agente de investigação.
+ *
+ * Acumula tarefas, hipóteses, evidências, cobertura de regras, drafts e custo.
+ * É a única fonte de verdade que o verificador/crítico consultam.
+ */
+
+import {
+	type Evidence,
+	type EvidenceKind,
+	evidenceId,
+	type FindingDraft,
+	type RuleCoverage,
+	type RuleCoverageStatus,
+} from "./evidence";
+import type { InvestigationTask } from "./investigation-task";
+
+/** Entrada para registrar uma evidência. */
+export type EvidenceInput = Omit<Evidence, "id"> & { id?: string };
+
+/** Estado mutável de um agente. */
+export class AgentState {
+	readonly tasks: InvestigationTask[] = [];
+	readonly hypotheses: string[] = [];
+	readonly evidence = new Map<string, Evidence>();
+	readonly coverage = new Map<string, RuleCoverage>();
+	readonly drafts: FindingDraft[] = [];
+	readonly toolCalls = new Map<string, number>();
+	private sequence = 0;
+
+	/** Registra as tarefas do plano. */
+	setTasks(tasks: InvestigationTask[]): void {
+		this.tasks.push(...tasks);
+	}
+
+	/** Tarefas por status. */
+	tasksByStatus(status: InvestigationTask["status"]): InvestigationTask[] {
+		return this.tasks.filter((task) => task.status === status);
+	}
+
+	/** Marca uma tarefa como concluída. */
+	completeTask(id: string, reason?: string): void {
+		const task = this.tasks.find((item) => item.id === id);
+		if (!task) return;
+		task.status = "done";
+		if (reason) task.reason = reason;
+	}
+
+	/** Marca uma tarefa como pulada (com motivo). */
+	skipTask(id: string, reason: string): void {
+		const task = this.tasks.find((item) => item.id === id);
+		if (!task) return;
+		task.status = "skipped";
+		task.reason = reason;
+	}
+
+	/** Adiciona uma hipótese (sem duplicar). */
+	addHypothesis(hypothesis: string): void {
+		const value = hypothesis.trim();
+		if (value && !this.hypotheses.includes(value)) this.hypotheses.push(value);
+	}
+
+	/** Registra evidência e devolve o id gerado. */
+	addEvidence(input: EvidenceInput): Evidence {
+		const id = input.id?.trim() ? input.id.trim() : evidenceId(++this.sequence);
+		const evidence: Evidence = { ...input, id };
+		this.evidence.set(id, evidence);
+		return evidence;
+	}
+
+	/** Evidência por id (undefined se não existe). */
+	getEvidence(id: string): Evidence | undefined {
+		return this.evidence.get(id);
+	}
+
+	/** Evidências de uma tool/esécie. */
+	evidenceOfKind(kind: EvidenceKind): Evidence[] {
+		return [...this.evidence.values()].filter((item) => item.kind === kind);
+	}
+
+	/** Adiciona um draft de finding. */
+	addDraft(draft: FindingDraft): void {
+		this.drafts.push(draft);
+	}
+
+	/** Define a cobertura de uma regra (idempotente por texto). */
+	setCoverage(rule: string, status: RuleCoverageStatus, reason?: string): void {
+		const existing = this.coverage.get(rule);
+		if (existing) {
+			existing.status = status;
+			if (reason) existing.reason = reason;
+			return;
+		}
+		this.coverage.set(rule, {
+			rule,
+			status,
+			files: [],
+			symbols: [],
+			...(reason ? { reason } : {}),
+		});
+	}
+
+	/** Cobertura atual de uma regra. */
+	coverageOf(rule: string): RuleCoverage | undefined {
+		return this.coverage.get(rule);
+	}
+
+	/** `true` quando a regra já foi coberta de alguma forma. */
+	isCovered(rule: string): boolean {
+		return this.coverage.has(rule);
+	}
+
+	/** Registra o uso de uma tool (contagem por nome). */
+	recordToolCall(name: string): void {
+		this.toolCalls.set(name, (this.toolCalls.get(name) ?? 0) + 1);
+	}
+
+	/** Chamadas registradas de uma tool. */
+	callsOf(name: string): number {
+		return this.toolCalls.get(name) ?? 0;
+	}
+
+	/** Snapshot serializável (sem prompts). */
+	toJSON(): Record<string, unknown> {
+		return {
+			hypotheses: this.hypotheses,
+			tasks: this.tasks,
+			evidence: [...this.evidence.values()],
+			coverage: [...this.coverage.values()],
+			drafts: this.drafts,
+			toolCalls: Object.fromEntries(this.toolCalls),
+		};
+	}
+}

package/src/harness/investigation/evidence-verifier.ts

@@ -0,0 +1,129 @@
+/**
+ * Verificador de evidências (`EvidenceVerifier`).
+ *
+ * Confere arquivo/linha/snippet contra o working tree. Evidência inválida não
+ * sustenta finding: o draft é descartado (ou reancorado quando o snippet existe
+ * em outra linha).
+ */
+
+import { normalizeLine } from "../../core/finding-anchor";
+import type { AgentState } from "./agent-state";
+import type { Evidence, FindingDraft } from "./evidence";
+
+/** Resultado da verificação de uma evidência. */
+export type EvidenceVerdict = {
+	evidence: Evidence;
+	valid: boolean;
+	reason?: string;
+	/** Linhas corrigidas quando o snippet foi reancorado. */
+	startLine?: number;
+	endLine?: number;
+};
+
+/** Resultado da verificação de um draft. */
+export type DraftVerdict = {
+	draft: FindingDraft;
+	valid: boolean;
+	evidence: Evidence[];
+	reason?: string;
+};
+
+/** Verificador de evidências por conteúdo. */
+export class EvidenceVerifier {
+	private readonly allowedFiles: ReadonlySet<string>;
+	private readonly readFile: (path: string) => string | null;
+
+	constructor(options: {
+		allowedFiles: Iterable<string>;
+		readFile: (path: string) => string | null;
+	}) {
+		this.allowedFiles = new Set(options.allowedFiles);
+		this.readFile = options.readFile;
+	}
+
+	/** Verifica uma evidência (arquivo permitido + snippet localizado). */
+	verify(evidence: Evidence): EvidenceVerdict {
+		if (!this.allowedFiles.has(evidence.file)) {
+			return { evidence, valid: false, reason: "arquivo fora do domínio/impacto" };
+		}
+		const content = this.readFile(evidence.file);
+		if (content === null) {
+			return { evidence, valid: false, reason: "arquivo ausente" };
+		}
+		const lines = content.replace(/\r\n/g, "\n").split("\n");
+		const expected = evidence.snippet
+			.split("\n")
+			.map(normalizeLine)
+			.filter((line) => line.length > 0);
+		if (expected.length === 0) {
+			return { evidence, valid: false, reason: "snippet vazio" };
+		}
+
+		const start = Math.max(1, evidence.startLine);
+		const actual = lines
+			.slice(start - 1, start - 1 + expected.length)
+			.map(normalizeLine);
+		if (sameLines(actual, expected)) {
+			return {
+				evidence,
+				valid: true,
+				startLine: start,
+				endLine: start + expected.length - 1,
+			};
+		}
+
+		const relocated = lines.findIndex((_line, index) =>
+			sameLines(
+				lines.slice(index, index + expected.length).map(normalizeLine),
+				expected,
+			),
+		);
+		if (relocated >= 0) {
+			return {
+				evidence,
+				valid: true,
+				reason: "reancorado",
+				startLine: relocated + 1,
+				endLine: relocated + expected.length,
+			};
+		}
+		return { evidence, valid: false, reason: "snippet não encontrado no arquivo" };
+	}
+
+	/** Verifica um draft: precisa de ao menos uma evidência válida. */
+	verifyDraft(draft: FindingDraft, state: AgentState): DraftVerdict {
+		const evidence: Evidence[] = [];
+		const reasons: string[] = [];
+		for (const id of draft.evidenceIds) {
+			const item = state.getEvidence(id);
+			if (!item) {
+				reasons.push(`evidência '${id}' inexistente`);
+				continue;
+			}
+			const verdict = this.verify(item);
+			if (verdict.valid) {
+				evidence.push({
+					...item,
+					startLine: verdict.startLine ?? item.startLine,
+					endLine: verdict.endLine ?? item.endLine,
+				});
+			} else {
+				reasons.push(verdict.reason ?? "evidência inválida");
+			}
+		}
+		return {
+			draft,
+			valid: evidence.length > 0,
+			evidence,
+			...(evidence.length === 0
+				? { reason: reasons.join("; ") || "sem evidência" }
+				: {}),
+		};
+	}
+}
+
+/** Compara linhas normalizadas. */
+function sameLines(a: readonly string[], b: readonly string[]): boolean {
+	if (a.length !== b.length) return false;
+	return a.every((line, index) => line === b[index]);
+}

package/src/harness/investigation/evidence.ts

@@ -0,0 +1,110 @@
+/**
+ * Tipos de investigação (harness nativo).
+ *
+ * Uma revisão é uma investigação: regras viram tarefas, tarefas produzem
+ * evidências, e só drafts com evidência válida viram findings.
+ */
+
+import type { Severity } from "../../core/types";
+import type { ToolCapability } from "../tools/agent-tool";
+
+/** Tipo de tarefa investigável. */
+export type InvestigationTaskKind =
+	| "rule-evidence"
+	| "symbol-impact"
+	| "tests"
+	| "context";
+
+/** Tarefa de investigação derivada de uma regra. */
+export type InvestigationTask = {
+	id: string;
+	rule: string;
+	severity: Severity;
+	kind: InvestigationTaskKind;
+	files: string[];
+	symbols: string[];
+	capabilities: ToolCapability[];
+	/** Prioridade (menor = antes). */
+	priority: number;
+	status: "pending" | "in_progress" | "done" | "skipped";
+	reason?: string;
+};
+
+/** Plano completo de um agente. */
+export type InvestigationPlan = {
+	tasks: InvestigationTask[];
+	totalFiles: number;
+	estimatedToolCalls: number;
+};
+
+/** Estratégia substituível de planejamento. */
+export interface InvestigationStrategy {
+	plan(
+		context: {
+			watchdogId: string;
+			files: readonly string[];
+			symbols: readonly string[];
+		},
+		rules: readonly import("./rule-analyzer").RuleAnalysis[],
+	): InvestigationPlan;
+}
+
+/** Evidência coletada por uma tool. */
+export type EvidenceKind =
+	| "definition"
+	| "reference"
+	| "import"
+	| "diff"
+	| "test"
+	| "doc";
+
+/** Trecho de código/docs que sustenta uma conclusão. */
+export type Evidence = {
+	id: string;
+	file: string;
+	startLine: number;
+	endLine: number;
+	snippet: string;
+	kind: EvidenceKind;
+	sourceTool: string;
+	confidence: number;
+};
+
+/** Status de cobertura de uma regra. */
+export type RuleCoverageStatus = "checked" | "not_applicable" | "skipped";
+
+/** Cobertura de uma regra (toda regra precisa terminar aqui). */
+export type RuleCoverage = {
+	rule: string;
+	status: RuleCoverageStatus;
+	files: string[];
+	symbols: string[];
+	reason?: string;
+};
+
+/** Achado proposto pelo agente (ainda não é finding final). */
+export type FindingDraft = {
+	rule: string;
+	severity: Severity;
+	file: string;
+	line?: number;
+	message: string;
+	action: string;
+	evidenceIds: string[];
+	confidence: number;
+};
+
+/** Decisão do crítico sobre um draft. */
+export type CriticVerdict = "keep" | "drop" | "downgrade";
+
+/** Resultado do crítico. */
+export type CriticDecision = {
+	draft: FindingDraft;
+	verdict: CriticVerdict;
+	reason: string;
+};
+
+/** Gera o id de uma evidência (determinístico por ordem de coleta). */
+export function evidenceId(sequence: number): string {
+	return `ev-${String(sequence).padStart(3, "0")}`;
+}

package/src/harness/investigation/finding-critic.ts

@@ -0,0 +1,96 @@
+/**
+ * Crítico de findings (`FindingCritic`).
+ *
+ * Segunda passada com o objetivo de **refutar** cada draft. Regras:
+ *  - sem evidência válida → drop;
+ *  - regra inexistente → drop;
+ *  - confiança baixa → downgrade; muito baixa → drop;
+ *  - `blocking`/`attention` exigem crítica (determinística aqui; um crítico
+ *    por IA pode ser injetado no futuro).
+ */
+
+import { emergentText, isEmergentRule } from "../../core/rule-text";
+import { type Severity, severityRank } from "../../core/types";
+import type { AgentState } from "./agent-state";
+import type { CriticDecision, FindingDraft } from "./evidence";
+import type { EvidenceVerifier } from "./evidence-verifier";
+
+/** Regras válidas do watchdog (texto). */
+export type CriticOptions = {
+	knownRules: ReadonlySet<string>;
+	verifier: EvidenceVerifier;
+	/** Aceita findings `Lógica:`/`Domínio:` fora das regras. */
+	allowEmergentFindings?: boolean;
+};
+
+/** Crítico determinístico. */
+export class FindingCritic {
+	private readonly options: CriticOptions;
+
+	constructor(options: CriticOptions) {
+		this.options = options;
+	}
+
+	/** Avalia todos os drafts, na ordem. */
+	review(drafts: readonly FindingDraft[], state: AgentState): CriticDecision[] {
+		return drafts.map((draft) => this.reviewOne(draft, state));
+	}
+
+	/** Avalia um draft. */
+	reviewOne(draft: FindingDraft, state: AgentState): CriticDecision {
+		const known = this.options.knownRules.has(draft.rule.trim());
+		const emergent = isEmergentRule(draft.rule);
+		if (!known && !(emergent && this.options.allowEmergentFindings)) {
+			return {
+				draft,
+				verdict: "drop",
+				reason: emergent
+					? "finding emergente desabilitado no watchdog"
+					: "regra não existe no watchdog",
+			};
+		}
+		if (emergent && !emergentText(draft.rule)) {
+			return { draft, verdict: "drop", reason: "finding emergente sem descrição" };
+		}
+		const verdict = this.options.verifier.verifyDraft(draft, state);
+		if (!verdict.valid) {
+			return { draft, verdict: "drop", reason: verdict.reason ?? "sem evidência" };
+		}
+		if (draft.confidence < 0.4) {
+			return { draft, verdict: "drop", reason: "confiança abaixo de 0.4" };
+		}
+		const normalized = emergent
+			? { ...draft, severity: capSeverity(draft.severity, "attention") }
+			: draft;
+		if (
+			normalized.confidence < 0.7 &&
+			(normalized.severity === "blocking" || normalized.severity === "attention")
+		) {
+			return {
+				draft: normalized,
+				verdict: "downgrade",
+				reason: "confiança insuficiente para a severidade",
+			};
+		}
+		return { draft: normalized, verdict: "keep", reason: "evidência válida" };
+	}
+}
+
+/** Limita a severidade a um teto (rank menor = mais grave). */
+export function capSeverity(severity: Severity, max: Severity): Severity {
+	return severityRank(severity) < severityRank(max) ? max : severity;
+}
+
+/** Rebaixa uma severidade em um nível. */
+export function downgrade(severity: Severity): Severity {
+	switch (severity) {
+		case "blocking":
+			return "attention";
+		case "attention":
+			return "suggestion";
+		case "suggestion":
+			return "nit";
+		default:
+			return "nit";
+	}
+}