@payconductor/houndsman 0.0.0-stage → 0.1.0

package/src/core/config-loader.ts

@@ -0,0 +1,87 @@
+/**
+ * Descoberta e carregamento da configuração do projeto — biblioteca.
+ *
+ * O motor é agnóstico: a config do projeto (`HoundsmanConfig`) é resolvida em
+ * runtime a partir do cwd do consumidor — nunca importada estaticamente.
+ *
+ * Ordem de resolução:
+ *   1. `--config <path>` (explícito)
+ *   2. `houndsman.config.{ts,mts,js,mjs}`
+ *   3. `.houndsman/config.{ts,js}`
+ */
+
+import { existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import type { HoundsmanConfig } from "./config";
+
+/** Nomes de arquivo procurados no cwd, em ordem de precedência. */
+export const CONFIG_FILE_CANDIDATES: readonly string[] = [
+	"houndsman.config.ts",
+	"houndsman.config.mts",
+	"houndsman.config.js",
+	"houndsman.config.mjs",
+	".houndsman/config.ts",
+	".houndsman/config.js",
+];
+
+export type LoadedConfig<TId extends string = string> = {
+	config: HoundsmanConfig<TId>;
+	/** Caminho absoluto do arquivo de config carregado. */
+	path: string;
+};
+
+/** Primeiro arquivo de config existente no diretório (ou `null`). */
+export function resolveConfigPath(cwd: string = process.cwd()): string | null {
+	for (const name of CONFIG_FILE_CANDIDATES) {
+		const candidate = join(cwd, name);
+		if (existsSync(candidate)) return candidate;
+	}
+	return null;
+}
+
+const MISSING_CONFIG_HINT =
+	"Nenhuma configuração do houndsman encontrada.\n" +
+	`Esperado: ${CONFIG_FILE_CANDIDATES.join(" | ")} na raiz do projeto.\n` +
+	"Rode `houndsman setup` para criar uma configuração inicial.";
+
+/**
+ * Carrega o `HoundsmanConfig` do projeto. Lança se ausente ou inválido.
+ * `configPath` sobrepõe a descoberta automática.
+ */
+export async function loadConfig<TId extends string = string>(
+	options: { cwd?: string; configPath?: string } = {},
+): Promise<LoadedConfig<TId>> {
+	const cwd = options.cwd ?? process.cwd();
+	const path = options.configPath
+		? resolve(cwd, options.configPath)
+		: resolveConfigPath(cwd);
+
+	if (!path || !existsSync(path)) {
+		throw new Error(MISSING_CONFIG_HINT);
+	}
+
+	const module = (await import(pathToFileURL(path).href)) as {
+		default?: HoundsmanConfig<TId>;
+		houndsmanConfig?: HoundsmanConfig<TId>;
+	};
+	const config = module.default ?? module.houndsmanConfig;
+
+	if (!config) {
+		throw new Error(
+			`Configuração inválida em ${path}: exporte \`export default houndsmanConfig\`.`,
+		);
+	}
+	if (!config.watchdogs || typeof config.watchdogs !== "object") {
+		throw new Error(`Configuração inválida em ${path}: campo 'watchdogs' ausente.`);
+	}
+	// Deriva `watchdogIds` de quem não passou por `defineHoundsmanConfig` (ex.: objeto
+	// literal) — mantém o motor robusto a configs escritas à mão.
+	if (!Array.isArray(config.watchdogIds)) {
+		(config as unknown as { watchdogIds: string[] }).watchdogIds = Object.keys(
+			config.watchdogs,
+		);
+	}
+
+	return { config, path };
+}

package/src/core/config.ts

@@ -0,0 +1,59 @@
+/**
+ * Contrato de configuração do motor de revisão (houndsman) — biblioteca.
+ *
+ * O motor (`core/` + `cli/`) é agnóstico ao projeto: consome um `HoundsmanConfig`
+ * por injeção explícita. O projeto fornece a config em `houndsman.config.ts`
+ * (camada `houndsman/`) — único ponto de troca ao portar para outro repositório.
+ */
+
+import { ARTIFACT_DIR } from "./paths";
+import type { WatchdogDefinition } from "./types";
+
+/** Documentos sempre incluídos nos briefs (default). */
+export const DEFAULT_ALWAYS_INCLUDE_DOCS: readonly string[] = ["AGENTS.md"];
+
+/**
+ * Configuração completa do motor de revisão para um projeto.
+ *
+ * `TId` é o union de ids de watchdog do projeto (ex.: `WatchdogId`).
+ */
+export type HoundsmanConfig<TId extends string = string> = {
+	/** Nome legível do projeto (usado em prompts e docs). */
+	projectName: string;
+	/** Diretório dos artefatos (default: `ARTIFACT_DIR` da camada). */
+	artifactDir?: string;
+	/**
+	 * Ids dos watchdogs — **derivados** das chaves de `watchdogs` por
+	 * `defineHoundsmanConfig` (não informar manualmente).
+	 */
+	watchdogIds: readonly TId[];
+	/** Definições dos watchdogs do projeto (fonte dos ids). */
+	watchdogs: Record<TId, WatchdogDefinition>;
+	/** Arquivos que nunca entram na revisão. */
+	exclusions: readonly RegExp[];
+	/** Mapeamentos path → documentação relevante. */
+	docMappings: readonly (readonly [RegExp, readonly string[]])[];
+	/** Docs sempre incluídos nos briefs (default: `DEFAULT_ALWAYS_INCLUDE_DOCS`). */
+	alwaysIncludeDocs?: readonly string[];
+};
+
+/** Entrada de `defineHoundsmanConfig` — `watchdogIds` é derivado, não informado. */
+export type HoundsmanConfigInput<TId extends string = string> = Omit<
+	HoundsmanConfig<TId>,
+	"watchdogIds"
+>;
+
+/**
+ * Helper de autoria: **deriva `watchdogIds`** das chaves de `watchdogs`
+ * (fonte única) e preserva a inferência de `TId`.
+ */
+export function defineHoundsmanConfig<TId extends string>(
+	input: HoundsmanConfigInput<TId>,
+): HoundsmanConfig<TId> {
+	return { ...input, watchdogIds: Object.keys(input.watchdogs) as TId[] };
+}
+
+/** Diretório dos artefatos — o valor do projeto ou o default da camada. */
+export function resolveArtifactDir(config: HoundsmanConfig): string {
+	return config.artifactDir ?? ARTIFACT_DIR;
+}

package/src/core/doc-discoverer.ts

@@ -0,0 +1,33 @@
+/**
+ * Descobre documentação relevante para um conjunto de arquivos alterados
+ * (biblioteca). Entrypoint: `cli/review.ts`.
+ *
+ * Os mapeamentos (`docMappings`) e os docs sempre incluídos vivem no projeto
+ * (`project/doc-mappings.ts`) e chegam via `HoundsmanConfig`.
+ */
+
+import { DEFAULT_ALWAYS_INCLUDE_DOCS, type HoundsmanConfig } from "./config";
+
+/** Descobre docs relevantes com base nos paths + docs sempre incluídos. */
+export function discoverDocs(filePaths: string[], config: HoundsmanConfig): string[] {
+	const docs = new Set<string>();
+
+	for (const doc of config.alwaysIncludeDocs ?? DEFAULT_ALWAYS_INCLUDE_DOCS) {
+		docs.add(doc);
+	}
+
+	for (const filePath of filePaths) {
+		const normalized = filePath.trim().toLowerCase();
+		if (!normalized) continue;
+
+		for (const [pattern, docPaths] of config.docMappings) {
+			if (pattern.test(normalized)) {
+				for (const docPath of docPaths) {
+					docs.add(docPath);
+				}
+			}
+		}
+	}
+
+	return [...docs].sort();
+}

package/src/core/file-classifier.ts

@@ -0,0 +1,247 @@
+/**
+ * Classificação de arquivos alterados por domínio de review (biblioteca).
+ *
+ * Cada watchdog declara os arquivos que cobre (`classify`); exclusões chegam via
+ * `HoundsmanConfig`. Use `classifyRange(base, head, config)`.
+ */
+
+import { readFileSync } from "node:fs";
+import type { HoundsmanConfig } from "./config";
+import type { ClassifyRule, WatchdogDefinition } from "./types";
+
+type FileStatus = "added" | "modified" | "deleted" | "renamed" | "copied" | "unknown";
+
+type FileEntry = {
+	path: string;
+	status: FileStatus;
+	oldPath?: string;
+};
+
+export type ClassificationResult = {
+	/** watchdogId → file paths (apenas arquivos revisáveis) */
+	watchdogs: Record<string, string[]>;
+	/** path → metadados (status, oldPath) */
+	files: Record<string, { status: FileStatus; oldPath?: string }>;
+	/** Arquivos não classificados (revisar manualmente) */
+	unclassified: string[];
+	/** Arquivos excluídos da revisão (gerados, locks, builds) */
+	excluded: string[];
+	/** Arquivos deletados — candidatos a breaking change, sem conteúdo para ler */
+	deleted: string[];
+	/** Estatísticas por watchdog */
+	stats: Record<string, number>;
+	excludedCount: number;
+	base?: string;
+	head?: string;
+};
+
+// ---------------------------------------------------------------------------
+// Matchers genéricos (reutilizados pelo projeto)
+// ---------------------------------------------------------------------------
+
+/** Tipo de classificação assumido quando `type` é omitido. */
+const DEFAULT_CLASSIFY_TYPE: NonNullable<ClassifyRule["type"]> = "filename";
+
+/** `true` se há entradas de conteúdo (as únicas que exigem ler o arquivo). */
+function hasContentRules<TId extends string>(
+	watchdogs: Record<TId, WatchdogDefinition>,
+	watchdogIds: readonly TId[],
+): boolean {
+	return watchdogIds.some((id) =>
+		watchdogs[id]?.classify?.some((rule) => rule.type === "content"),
+	);
+}
+
+/** Lê o arquivo em UTF-8; `undefined` se indisponível (binário, ausente). */
+function readFileContent(filePath: string): string | undefined {
+	try {
+		return readFileSync(filePath, "utf8");
+	} catch {
+		return undefined;
+	}
+}
+
+/** `true` se o arquivo casa a entrada de classificação. */
+function matchesClassifyRule(
+	filePath: string,
+	rule: ClassifyRule,
+	content: string | undefined,
+): boolean {
+	if ((rule.type ?? DEFAULT_CLASSIFY_TYPE) === "content") {
+		return content !== undefined && new RegExp(rule.value).test(content);
+	}
+	return new RegExp(rule.value).test(filePath);
+}
+
+/** Watchdogs que declaram o arquivo (união dos `classify`). */
+export function matchWatchdogs<TId extends string>(
+	filePath: string,
+	watchdogs: Record<TId, WatchdogDefinition>,
+	watchdogIds: readonly TId[],
+	content?: string,
+): TId[] {
+	const ids: TId[] = [];
+	for (const id of watchdogIds) {
+		if (
+			watchdogs[id]?.classify?.some((rule) =>
+				matchesClassifyRule(filePath, rule, content),
+			)
+		) {
+			ids.push(id);
+		}
+	}
+	return ids;
+}
+
+/** `true` se o arquivo casa algum padrão de exclusão. */
+export function isExcludedPath(filePath: string, patterns: readonly RegExp[]): boolean {
+	return patterns.some((pattern) => pattern.test(filePath));
+}
+
+// ---------------------------------------------------------------------------
+// Execução do git diff
+// ---------------------------------------------------------------------------
+
+function runGitDiff(base: string, head: string): string {
+	const result = Bun.spawnSync(["git", "diff", `${base}...${head}`, "--name-status"], {
+		stdout: "pipe",
+		stderr: "pipe",
+	});
+	if (result.exitCode !== 0) {
+		const stderr = new TextDecoder().decode(result.stderr).trim();
+		throw new Error(`git diff falhou (base='${base}', head='${head}'): ${stderr}`);
+	}
+	return new TextDecoder().decode(result.stdout);
+}
+
+// ---------------------------------------------------------------------------
+// Parsing de `git diff --name-status`
+// ---------------------------------------------------------------------------
+
+function mapStatus(code: string): FileStatus {
+	const letter = code[0]?.toUpperCase();
+	switch (letter) {
+		case "A":
+			return "added";
+		case "M":
+			return "modified";
+		case "D":
+			return "deleted";
+		case "R":
+			return "renamed";
+		case "C":
+			return "copied";
+		default:
+			return "unknown";
+	}
+}
+
+export function parseEntries(raw: string): FileEntry[] {
+	const entries: FileEntry[] = [];
+	for (const line of raw.split("\n")) {
+		const trimmed = line.trim();
+		if (!trimmed) continue;
+
+		const fields = trimmed.split("\t");
+		if (fields.length === 1) {
+			// Sem status — assume modificado
+			entries.push({ path: fields[0].trim(), status: "modified" });
+			continue;
+		}
+
+		const status = mapStatus(fields[0].trim());
+		if (fields.length >= 3 && (status === "renamed" || status === "copied")) {
+			// R100\told\tnew
+			entries.push({ path: fields[2].trim(), oldPath: fields[1].trim(), status });
+		} else {
+			entries.push({ path: fields[1].trim(), status });
+		}
+	}
+	return entries;
+}
+
+// ---------------------------------------------------------------------------
+// Classificação
+// ---------------------------------------------------------------------------
+
+export function classifyEntries<TId extends string>(
+	entries: FileEntry[],
+	config: HoundsmanConfig<TId>,
+): ClassificationResult {
+	const watchdogFiles: Record<string, string[]> = {};
+	const files: ClassificationResult["files"] = {};
+	const unclassified: string[] = [];
+	const excluded: string[] = [];
+	const deleted: string[] = [];
+	// Leitura de conteúdo só é habilitada se algum watchdog declarar regra `content`.
+	const needsContent = hasContentRules(config.watchdogs, config.watchdogIds);
+
+	for (const entry of entries) {
+		const { path, status, oldPath } = entry;
+		files[path] = oldPath ? { status, oldPath } : { status };
+
+		if (isExcludedPath(path, config.exclusions)) {
+			excluded.push(path);
+			continue;
+		}
+
+		if (status === "deleted") {
+			// Sem conteúdo para revisar — exposto separadamente p/ checagem de breaking change
+			deleted.push(path);
+			continue;
+		}
+
+		const content = needsContent ? readFileContent(path) : undefined;
+		const ids: string[] = matchWatchdogs(
+			path,
+			config.watchdogs,
+			config.watchdogIds,
+			content,
+		);
+
+		if (ids.length === 0) {
+			unclassified.push(path);
+			continue;
+		}
+
+		for (const id of ids) {
+			watchdogFiles[id] ??= [];
+			watchdogFiles[id].push(path);
+		}
+	}
+
+	const watchdogs: Record<string, string[]> = {};
+	const stats: Record<string, number> = {};
+	for (const id of config.watchdogIds) {
+		const list = [...new Set(watchdogFiles[id] ?? [])];
+		if (list.length > 0) {
+			watchdogs[id] = list;
+			stats[id] = list.length;
+		}
+	}
+
+	return {
+		watchdogs,
+		files,
+		unclassified,
+		excluded,
+		deleted,
+		stats,
+		excludedCount: excluded.length,
+	};
+}
+
+/**
+ * Executa `git diff` entre base e head e classifica os arquivos alterados.
+ */
+export function classifyRange<TId extends string>(
+	base: string,
+	head: string,
+	config: HoundsmanConfig<TId>,
+): ClassificationResult {
+	const entries = parseEntries(runGitDiff(base, head));
+	const result = classifyEntries(entries, config);
+	result.base = base;
+	result.head = head;
+	return result;
+}

package/src/core/jev/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Barrel do módulo Jev (pré-análise do houndsman — Passo 1.5).
+ *
+ * Consumidores importam daqui (`"./jev"`). Tudo relacionado ao Jev vive nesta
+ * pasta — nada solto em `core/`.
+ */
+
+export * from "./jev-candidates";
+export * from "./jev-client";
+export * from "./jev-detector";
+export * from "./jev-questions";
+export * from "./jev-types";

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

@@ -0,0 +1,105 @@
+/**
+ * Candidatos a achado produzidos pelo passo de pré-análise Jev (Passo 1.5).
+ *
+ * Um candidato NÃO é um achado: é um indício com confiança calibrada, injetado
+ * nos briefs para o subagente **confirmar ou refutar**. A severidade/validação
+ * final continua sendo do watchdog (LLM) ou humano.
+ */
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { SEVERITY_ORDER, type Severity } from "../types";
+
+export type JevCandidate = {
+	watchdogId: string;
+	/** Descrição da regra (deve ser usada como `rule` se confirmada). */
+	rule: string;
+	severity: Severity;
+	file: string;
+	/** Probabilidade calibrada retornada pelo modelo (0–1). */
+	confidence: number;
+	/** Chave da pergunta que originou o candidato. */
+	questionKey: string;
+};
+
+export type JevSkippedFile = { file: string; reason: string };
+
+export type JevCandidatesFile = {
+	available: boolean;
+	/** Motivo quando `available: false` (sem chave, erro, etc.). */
+	reason?: string;
+	model?: string;
+	threshold?: number;
+	analyzedFiles?: number;
+	candidates: JevCandidate[];
+	skipped?: JevSkippedFile[];
+};
+
+const SEVERITY_SET = new Set<string>(SEVERITY_ORDER);
+
+/** Persistência do artefato `candidates.json` para um diretório de review. */
+export class JevCandidatesStore {
+	/** Limiar padrão de confiança (`noul`) para virar candidato. */
+	static readonly THRESHOLD = 0.6;
+
+	/** Artefato vazio/indisponível (sem chave, erro, `--no-jev`). */
+	static unavailable(reason: string): JevCandidatesFile {
+		return { available: false, reason, candidates: [] };
+	}
+
+	private readonly filePath: string;
+	/** Ids válidos (null = sem filtro por id). */
+	private readonly watchdogIdSet: Set<string> | null;
+
+	constructor(filePath: string, validIds: readonly string[] = []) {
+		this.filePath = filePath;
+		this.watchdogIdSet = validIds.length > 0 ? new Set(validIds) : null;
+	}
+
+	/** Grava o `candidates.json` (sempre com candidatos válidos apenas). */
+	write(data: JevCandidatesFile): void {
+		writeFileSync(this.filePath, `${JSON.stringify(data, null, 2)}\n`);
+	}
+
+	/** Lê o `candidates.json`; null se ausente/inválido. */
+	read(): JevCandidatesFile | null {
+		if (!existsSync(this.filePath)) return null;
+		try {
+			const raw = JSON.parse(readFileSync(this.filePath, "utf8")) as Record<
+				string,
+				unknown
+			>;
+			const candidates = Array.isArray(raw.candidates)
+				? raw.candidates.filter((c) => this.isCandidate(c))
+				: [];
+			return {
+				available: raw.available === true,
+				reason: typeof raw.reason === "string" ? raw.reason : undefined,
+				model: typeof raw.model === "string" ? raw.model : undefined,
+				threshold: typeof raw.threshold === "number" ? raw.threshold : undefined,
+				analyzedFiles:
+					typeof raw.analyzedFiles === "number" ? raw.analyzedFiles : undefined,
+				candidates,
+				skipped: Array.isArray(raw.skipped)
+					? (raw.skipped as JevSkippedFile[])
+					: undefined,
+			};
+		} catch {
+			return null;
+		}
+	}
+
+	private isCandidate(value: unknown): value is JevCandidate {
+		if (typeof value !== "object" || value === null) return false;
+		const c = value as Record<string, unknown>;
+		return (
+			typeof c.watchdogId === "string" &&
+			(this.watchdogIdSet === null || this.watchdogIdSet.has(c.watchdogId)) &&
+			typeof c.rule === "string" &&
+			typeof c.severity === "string" &&
+			SEVERITY_SET.has(c.severity) &&
+			typeof c.file === "string" &&
+			typeof c.confidence === "number" &&
+			typeof c.questionKey === "string"
+		);
+	}
+}

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

@@ -0,0 +1,99 @@
+/**
+ * Cliente HTTP mínimo para a API TypeSafe "System One" (Jev).
+ *
+ * Implementação própria sobre `axios` (sem SDK oficial) para manter o
+ * pipeline de review sem dependências novas de SDK e com tipagem explícita
+ * do request/response (`./jev-types`).
+ *
+ * Config: apenas `TYPESAFE_API_KEY` (via env). Origem e modelo da API são
+ * fixos no código (constantes abaixo).
+ *
+ * Erros são normalizados em `JevError` — o chamador decide falhar-aberto.
+ */
+
+import axios, { type AxiosInstance, isAxiosError } from "axios";
+import type { JevEvaluateRequest, JevEvaluateResponse } from "./jev-types";
+
+const DEFAULT_BASE_URL = "https://api.typesafe.ai";
+const DEFAULT_MODEL = "jev-latest";
+const DEFAULT_TIMEOUT_MS = 20_000;
+/** Caminho fixo do endpoint System One. */
+const JEV_PATH = "/v1/systemone";
+
+export class JevError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "JevError";
+	}
+}
+
+export type JevClientOptions = {
+	/** Chave de API (default: `process.env.TYPESAFE_API_KEY`). */
+	apiKey?: string;
+	/** Sobreposição da origem da API (default: constante `DEFAULT_BASE_URL`). */
+	baseURL?: string;
+	/** Sobreposição do modelo (default: constante `DEFAULT_MODEL`). */
+	model?: string;
+	timeoutMs?: number;
+	/** Instância axios injetável (testes). */
+	http?: AxiosInstance;
+};
+
+export class JevClient {
+	private readonly http: AxiosInstance;
+	private readonly apiKey?: string;
+	/** Modelo usado quando o request não informa um. */
+	readonly model: string;
+
+	constructor(options: JevClientOptions = {}) {
+		this.apiKey = options.apiKey ?? process.env.TYPESAFE_API_KEY;
+		this.model = options.model ?? DEFAULT_MODEL;
+		const baseURL = options.baseURL ?? DEFAULT_BASE_URL;
+		this.http =
+			options.http ??
+			axios.create({
+				baseURL,
+				timeout: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+			});
+	}
+
+	/** `true` se há chave configurada (sem chave o passo é pulado). */
+	isConfigured(): boolean {
+		return Boolean(this.apiKey);
+	}
+
+	/**
+	 * Avalia as `questions` contra o `state` em uma única chamada.
+	 * Lança `JevError` em falha de rede/HTTP/parse — o chamador trata.
+	 */
+	async evaluate(request: JevEvaluateRequest): Promise<JevEvaluateResponse> {
+		if (!this.apiKey) {
+			throw new JevError("TYPESAFE_API_KEY não configurada.");
+		}
+		try {
+			const { data } = await this.http.post<JevEvaluateResponse>(
+				JEV_PATH,
+				{ ...request, model: request.model ?? this.model },
+				{ headers: { Authorization: `Bearer ${this.apiKey}` } },
+			);
+			return data;
+		} catch (error) {
+			throw new JevError(JevClient.describeError(error));
+		}
+	}
+
+	/** Normaliza o erro do axios em mensagem legível (sem expor o payload bruto). */
+	private static describeError(error: unknown): string {
+		if (isAxiosError(error)) {
+			const status = error.response?.status;
+			const detail =
+				typeof error.response?.data === "string"
+					? error.response.data
+					: error.response?.data
+						? JSON.stringify(error.response.data)
+						: error.message;
+			return status ? `HTTP ${status}: ${detail}` : detail;
+		}
+		return error instanceof Error ? error.message : String(error);
+	}
+}