@payconductor/houndsman 0.0.0-stage → 0.1.0

package/src/core/jev/jev-detector.ts

@@ -0,0 +1,203 @@
+/**
+ * Detector de candidatos (Passo 1.5) — roda as perguntas Jev por arquivo.
+ *
+ * Para cada arquivo revisável: monta o `state` (topo do arquivo + hunk do diff),
+ * reúne as perguntas dos watchdogs do arquivo e consulta o modelo. Respostas
+ * `noul` acima do limiar viram candidatos.
+ *
+ * Falha-aberto: erro por arquivo é registrado em `skipped` e não interrompe.
+ */
+
+import { readFileSync } from "node:fs";
+import type { ClassificationResult } from "../file-classifier";
+import type { WatchdogMeta } from "../types";
+import {
+	type JevCandidate,
+	JevCandidatesStore,
+	type JevSkippedFile,
+} from "./jev-candidates";
+import type { JevClient } from "./jev-client";
+import { type DerivedQuestion, JevQuestionFactory } from "./jev-questions";
+import type { JevQuestion } from "./jev-types";
+
+export type DetectOptions = {
+	/** Limiar de confiança (`noul`) para virar candidato. */
+	threshold?: number;
+	/** Nº de arquivos avaliados em paralelo. */
+	concurrency?: number;
+};
+
+export type DetectResult = {
+	candidates: JevCandidate[];
+	skipped: JevSkippedFile[];
+	analyzedFiles: number;
+	model?: string;
+};
+
+/** Orquestra a pré-análise Jev sobre um diff classificado. */
+export class JevDetector {
+	/** Linhas iniciais do arquivo (imports/declarações) incluídas no `state`. */
+	private static readonly HEADER_LINES = 60;
+	private static readonly MAX_STATE_CHARS = 8_000;
+	private static readonly MAX_DIFF_CHARS = 4_000;
+	private static readonly DEFAULT_CONCURRENCY = 5;
+
+	private readonly client: JevClient;
+	private readonly questions: JevQuestionFactory;
+
+	/** Construtor que recebe o cliente e o registry de watchdogs (injeção). */
+	constructor(client: JevClient, registry: Record<string, WatchdogMeta>) {
+		this.client = client;
+		this.questions = new JevQuestionFactory(registry);
+	}
+
+	/** Roda a pré-análise e devolve os candidatos (ordenados por confiança desc). */
+	async detect(
+		classification: ClassificationResult,
+		base: string,
+		head: string,
+		options: DetectOptions = {},
+	): Promise<DetectResult> {
+		const threshold = options.threshold ?? JevCandidatesStore.THRESHOLD;
+		const concurrency = options.concurrency ?? JevDetector.DEFAULT_CONCURRENCY;
+
+		const jobs = this.buildJobs(classification);
+		const questionByKey = new Map<string, DerivedQuestion>();
+		for (const job of jobs) {
+			for (const dq of job.questions) questionByKey.set(dq.key, dq);
+		}
+
+		const candidates: JevCandidate[] = [];
+		const skipped: JevSkippedFile[] = [];
+		let model: string | undefined;
+
+		await JevDetector.mapWithConcurrency(jobs, concurrency, async (job) => {
+			const questions: Record<string, JevQuestion> = {};
+			for (const dq of job.questions) questions[dq.key] = dq.question;
+
+			const status = classification.files[job.file]?.status ?? "modified";
+			const state = this.buildState(job.file, status, base, head);
+
+			try {
+				const response = await this.client.evaluate({ state, questions });
+				model ??= response.model;
+				for (const [key, answer] of Object.entries(response.answers)) {
+					if (answer.type !== "noul" || answer.noul < threshold) continue;
+					const dq = questionByKey.get(key);
+					if (!dq) continue;
+					candidates.push({
+						watchdogId: dq.watchdogId,
+						rule: dq.rule,
+						severity: dq.severity,
+						file: job.file,
+						confidence: answer.noul,
+						questionKey: key,
+					});
+				}
+			} catch (error) {
+				skipped.push({
+					file: job.file,
+					reason: error instanceof Error ? error.message : String(error),
+				});
+			}
+		});
+
+		candidates.sort((a, b) => b.confidence - a.confidence);
+
+		return {
+			candidates,
+			skipped,
+			analyzedFiles: jobs.length,
+			model,
+		};
+	}
+
+	/** Arquivo → perguntas dos watchdogs que o cobrem (só arquivos com perguntas). */
+	private buildJobs(
+		classification: ClassificationResult,
+	): { file: string; questions: DerivedQuestion[] }[] {
+		const filesToWatchdogs = JevDetector.mapFilesToWatchdogs(classification);
+		return [...filesToWatchdogs.entries()]
+			.map(([file, watchdogs]) => ({
+				file,
+				questions: this.questions.build([...watchdogs]),
+			}))
+			.filter((job) => job.questions.length > 0);
+	}
+
+	/** Monta o `state` de um arquivo: cabeçalho + hunk do diff, com cap de tamanho. */
+	private buildState(
+		filePath: string,
+		status: string,
+		base: string,
+		head: string,
+	): string {
+		const header = this.readHeader(filePath);
+		const hunk = this.readHunk(base, head, filePath);
+		const parts = [`Arquivo: ${filePath} (${status})`];
+		if (header) {
+			parts.push("--- topo do arquivo (imports/declarações) ---", header);
+		}
+		if (hunk) parts.push("--- diff ---", hunk);
+		return parts.join("\n").slice(0, JevDetector.MAX_STATE_CHARS);
+	}
+
+	private readHeader(filePath: string): string {
+		try {
+			return readFileSync(filePath, "utf8")
+				.split("\n")
+				.slice(0, JevDetector.HEADER_LINES)
+				.join("\n");
+		} catch {
+			return "";
+		}
+	}
+
+	private readHunk(base: string, head: string, filePath: string): string {
+		const result = Bun.spawnSync(
+			["git", "diff", `${base}...${head}`, "--", filePath],
+			{ stdout: "pipe", stderr: "pipe" },
+		);
+		if (result.exitCode !== 0) return "";
+		return new TextDecoder()
+			.decode(result.stdout)
+			.slice(0, JevDetector.MAX_DIFF_CHARS);
+	}
+
+	/** Arquivo → watchdogs que o cobrem. */
+	private static mapFilesToWatchdogs(
+		classification: ClassificationResult,
+	): Map<string, Set<string>> {
+		const map = new Map<string, Set<string>>();
+		for (const [id, files] of Object.entries(classification.watchdogs)) {
+			for (const file of files ?? []) {
+				let set = map.get(file);
+				if (!set) {
+					set = new Set<string>();
+					map.set(file, set);
+				}
+				set.add(id);
+			}
+		}
+		return map;
+	}
+
+	/** Executa `fn` sobre `items` com concorrência limitada (ordem irrelevante). */
+	private static async mapWithConcurrency<T>(
+		items: readonly T[],
+		limit: number,
+		fn: (item: T) => Promise<void>,
+	): Promise<void> {
+		let cursor = 0;
+		const workers = Array.from(
+			{ length: Math.min(limit, items.length) },
+			async () => {
+				while (cursor < items.length) {
+					const current = items[cursor++];
+					await fn(current);
+				}
+			},
+		);
+		await Promise.all(workers);
+	}
+}

package/src/core/jev/jev-questions.ts

@@ -0,0 +1,92 @@
+/**
+ * Deriva perguntas Jev (tipadas) a partir das regras do `WATCHDOG_DEFINITIONS`.
+ *
+ * Fonte única de verdade: o registry. Uma regra só gera pergunta se tiver a
+ * spec Jev (campo opcional `jev` de `Rule`). Assim não há lista paralela para
+ * sincronizar — alterar a regra no registry altera a pergunta.
+ */
+
+import type { Rule, Severity, WatchdogMeta } from "../types";
+import type { JevQuestion, JevRuleSpec } from "./jev-types";
+
+export type DerivedQuestion = {
+	/** Chave estável da pergunta (`<watchdogId>::<bucket>-<índice>`). */
+	key: string;
+	watchdogId: string;
+	severity: Severity;
+	/** Descrição original da regra (usada como `rule` no achado confirmado). */
+	rule: string;
+	question: JevQuestion;
+};
+
+/**
+ * Converte regras do registry em perguntas tipadas para a API.
+ *
+ * Encapsula toda a lógica de conversão/derivação. O registry (watchdogs) é
+ * injetado via `HoundsmanConfig`, permitindo testes sem tocar no registry real.
+ */
+export class JevQuestionFactory {
+	private readonly registry: Record<string, WatchdogMeta>;
+
+	constructor(registry: Record<string, WatchdogMeta>) {
+		this.registry = registry;
+	}
+
+	/** Converte uma `JevRuleSpec` em `JevQuestion`; null se a spec for inválida. */
+	fromSpec(description: string, spec: JevRuleSpec): JevQuestion | null {
+		const instructions = (spec.instructions ?? this.noul(description)).trim();
+		if (!instructions) return null;
+
+		if (spec.kind === "noul") return { type: "noul", instructions };
+
+		if (spec.kind === "choice") {
+			const criteria = spec.criteria;
+			if (!criteria || Array.isArray(criteria)) return null;
+			if (Object.keys(criteria).length === 0) return null;
+			return { type: "choice", instructions, criteria };
+		}
+
+		// score
+		if (!Array.isArray(spec.criteria) || spec.criteria.length === 0) return null;
+		return { type: "score", instructions, criteria: spec.criteria };
+	}
+
+	/** Perguntas derivadas das regras de um watchdog (`rules`). */
+	derive(watchdogId: string): DerivedQuestion[] {
+		const meta = this.registry[watchdogId];
+		if (!meta) return [];
+
+		const out: DerivedQuestion[] = [];
+		meta.rules.forEach((rule, index) => {
+			const spec = this.specOf(rule);
+			if (!spec) return;
+			const question = this.fromSpec(rule.text, spec);
+			if (!question) return;
+			out.push({
+				key: `${watchdogId}::rule-${index}`,
+				watchdogId,
+				severity: rule.severity,
+				rule: rule.text,
+				question,
+			});
+		});
+		return out;
+	}
+
+	/** Perguntas derivadas para um conjunto de watchdogs. */
+	build(watchdogIds: readonly string[]): DerivedQuestion[] {
+		return watchdogIds.flatMap((id) => this.derive(id));
+	}
+
+	/**
+	 * Acesso tipado à spec Jev da regra (campo opcional `jev`).
+	 */
+	specOf(rule: Rule): JevRuleSpec | undefined {
+		return rule.jev;
+	}
+
+	/** Instrução padrão quando a spec não traz `instructions`. */
+	private noul(description: string): string {
+		return `No estado fornecido, ocorre a seguinte violação? "${description}"`;
+	}
+}

package/src/core/jev/jev-types.ts

@@ -0,0 +1,91 @@
+/**
+ * Tipos da API TypeSafe "System One" (modelo Jev).
+ *
+ * Contrato: `POST {baseURL}/v1/systemone`
+ *   Body: { state, model?, questions: Record<key, JevQuestion> }
+ *   Resp: { model, answers: Record<key, JevAnswer>, usage? }
+ *
+ * Cada pergunta é avaliada em paralelo e em isolamento contra o mesmo `state`.
+ */
+
+/** Tipo de pergunta aceito pela API. */
+export type JevQuestionType = "noul" | "choice" | "score";
+
+/** "A afirmação é verdadeira?" → retorna probabilidade 0–1. */
+export type JevNoulQuestion = {
+	type: "noul";
+	instructions: string;
+};
+
+/** Escolhe uma opção de uma lista. */
+export type JevChoiceQuestion = {
+	type: "choice";
+	instructions: string;
+	criteria: Record<string, string>;
+};
+
+/** Pontua o estado em uma rubrica (índice da lista). */
+export type JevScoreQuestion = {
+	type: "score";
+	instructions: string;
+	criteria: string[];
+};
+
+export type JevQuestion = JevNoulQuestion | JevChoiceQuestion | JevScoreQuestion;
+
+export type JevEvaluateRequest = {
+	state: string;
+	model?: string;
+	questions: Record<string, JevQuestion>;
+};
+
+export type JevNoulAnswer = {
+	type: "noul";
+	noul: number;
+};
+
+export type JevChoiceAnswer = {
+	type: "choice";
+	choice: string;
+	confidence: number;
+	probabilities: Record<string, number>;
+};
+
+export type JevScoreAnswer = {
+	type: "score";
+	score: number;
+	confidence: number;
+	legend?: Record<string, string>;
+	probabilities?: Record<string, number>;
+};
+
+export type JevAnswer = JevNoulAnswer | JevChoiceAnswer | JevScoreAnswer;
+
+export type JevUsage = {
+	input_tokens?: number;
+	output_tokens?: number;
+};
+
+export type JevEvaluateResponse = {
+	model: string;
+	answers: Record<string, JevAnswer>;
+	usage?: JevUsage;
+};
+
+/**
+ * Spec de conversão de uma regra do registry em pergunta Jev.
+ *
+ * Sempre um objeto — `kind` é obrigatório para deixar explícito o que a spec
+ * faz (a presença de `jev` não é um liga/desliga do Jev).
+ *
+ * - `kind: "noul"`   → "a violação descrita ocorre?" (probabilidade 0–1).
+ * - `kind: "choice"` → escolha entre opções (`criteria` obrigatório, objeto).
+ * - `kind: "score"`  → nota numa rubrica (`criteria` obrigatório, lista).
+ *
+ * `instructions` omitida → derivada da própria descrição da regra.
+ */
+export type JevRuleSpec = {
+	kind: JevQuestionType;
+	instructions?: string;
+	criteria?: string[] | Record<string, string>;
+};