@payconductor/houndsman 0.2.0 → 0.4.0

package/src/core/services/verifier.ts

@@ -0,0 +1,58 @@
+/**
+ * Verificação de findings (biblioteca) — superfície OO sobre `verify.ts`.
+ *
+ * O tier local (âncora de conteúdo) e o tier Jev continuam em funções puras; a
+ * classe concentra a sequência usada pelo comando `findings verify`.
+ */
+
+import type {
+	FileReader,
+	FindingState,
+	FindingsFilter,
+	FindingsStateFile,
+} from "../findings-state";
+import {
+	applyJev,
+	applyResolutions,
+	selectVerifiable,
+	summarizeVerify,
+	type VerifyEntry,
+	type VerifySummary,
+	verifyLocal,
+} from "../verify";
+
+/** Encadeia seleção, tier local, confirmação Jev e persistência. */
+export class Verifier {
+	/** Fila de verificação (presentes, sem `ignore`). */
+	select(state: FindingsStateFile, filter: FindingsFilter = {}): FindingState[] {
+		return selectVerifiable(state, filter);
+	}
+
+	/** Tier 0 — checagem local por reancoragem de conteúdo. */
+	verifyLocal(findings: readonly FindingState[], readFile: FileReader): VerifyEntry[] {
+		return verifyLocal(findings, readFile);
+	}
+
+	/** Tier 1 — aplica a confirmação do Jev aos casos ambíguos. */
+	applyJev(
+		entries: VerifyEntry[],
+		confidence: Map<string, number>,
+		threshold: number,
+	): number {
+		return applyJev(entries, confidence, threshold);
+	}
+
+	/** Contagem por status. */
+	summarize(entries: readonly VerifyEntry[]): VerifySummary {
+		return summarizeVerify(entries);
+	}
+
+	/** Persiste os `resolved` como `done`. */
+	applyResolutions(
+		state: FindingsStateFile,
+		entries: readonly VerifyEntry[],
+		now?: string,
+	): string[] {
+		return applyResolutions(state, entries, now);
+	}
+}

package/src/core/storage/factory.ts

@@ -0,0 +1,24 @@
+/**
+ * Fábrica do provider de persistência (biblioteca).
+ *
+ * Default: SQLite no diretório global. `storage.provider: "file"` mantém o
+ * backend em arquivos sob o mesmo home — útil para debug ou rollback.
+ */
+
+import type { HoundsmanConfig } from "../config";
+import { FileStorageProvider } from "./file/file-storage";
+import { databasePath, fileRoot } from "./paths";
+import { SQLiteStorageProvider } from "./sqlite/sqlite-storage";
+import type { StorageProvider } from "./types";
+
+/** Cria o provider configurado pelo projeto. */
+export function createStorage(config: HoundsmanConfig): StorageProvider {
+	return config.storage?.provider === "file"
+		? new FileStorageProvider(fileRoot(config))
+		: new SQLiteStorageProvider(databasePath(config));
+}
+
+/** Provider SQLite em memória (testes). */
+export function createMemoryStorage(): StorageProvider {
+	return new SQLiteStorageProvider(":memory:");
+}

package/src/core/storage/file/file-storage.ts

@@ -0,0 +1,269 @@
+/**
+ * Provider de arquivos do houndsman (biblioteca) — fallback do SQLite.
+ *
+ * Mantém o formato antigo (JSON por review), mas sob o diretório global do
+ * houndsman. Serve para debug/rollback: trocar `storage.provider` para `"file"`.
+ */
+
+import { createHash, randomUUID } from "node:crypto";
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { FINDINGS_STATE_VERSION, type FindingsStateFile } from "../../findings-state";
+import { systemClock } from "../../services/clock";
+import { ProjectFiles } from "../../services/project-files";
+import type {
+	ArtifactRecord,
+	CreateReviewInput,
+	ReviewPatch,
+	ReviewRecord,
+	StorageProvider,
+	WriteArtifactInput,
+} from "../types";
+
+const REVIEW_FILE = "review.json";
+const FINDINGS_FILE = "findings.json";
+const ARTIFACTS_FILE = "artifacts.json";
+
+/** Provider em arquivos sob uma raiz global. */
+export class FileStorageProvider implements StorageProvider {
+	readonly kind = "file" as const;
+	private readonly root: string;
+	private readonly files = new ProjectFiles();
+
+	constructor(root: string) {
+		this.root = root;
+	}
+
+	// -----------------------------------------------------------------------
+	// Reviews
+	// -----------------------------------------------------------------------
+
+	getOrCreateReview(input: CreateReviewInput): ReviewRecord {
+		const existing = this.findReview(input.repo.key, input.branch);
+		if (existing) {
+			if (
+				existing.repoRoot !== input.repo.root ||
+				existing.repoRemote !== input.repo.remote
+			) {
+				return this.writeReview({
+					...existing,
+					repoRoot: input.repo.root,
+					repoRemote: input.repo.remote,
+				});
+			}
+			return existing;
+		}
+
+		const now = input.now ?? systemClock();
+		const record: ReviewRecord = {
+			id: randomUUID(),
+			repoKey: input.repo.key,
+			repoRoot: input.repo.root,
+			repoRemote: input.repo.remote,
+			branch: input.branch,
+			slug: input.slug,
+			base: input.base,
+			head: input.head,
+			status: null,
+			createdAt: now,
+			updatedAt: now,
+		};
+		return this.writeReview(record);
+	}
+
+	findReview(repoKey: string, branch: string): ReviewRecord | null {
+		return (
+			this.readReviews(repoKey).find((review) => review.branch === branch) ?? null
+		);
+	}
+
+	getReview(id: string): ReviewRecord | null {
+		return this.readReviews().find((review) => review.id === id) ?? null;
+	}
+
+	listReviews(repoKey?: string): ReviewRecord[] {
+		return this.readReviews(repoKey).sort((a, b) =>
+			b.updatedAt.localeCompare(a.updatedAt),
+		);
+	}
+
+	updateReview(id: string, patch: ReviewPatch): ReviewRecord | null {
+		const review = this.getReview(id);
+		if (!review) return null;
+		const now = patch.updatedAt ?? systemClock();
+		const updated: ReviewRecord = { ...review };
+		if (patch.branch !== undefined) updated.branch = patch.branch;
+		if (patch.slug !== undefined) updated.slug = patch.slug;
+		if (patch.base !== undefined) updated.base = patch.base;
+		if (patch.head !== undefined) updated.head = patch.head;
+		if (patch.headSha !== undefined) updated.headSha = patch.headSha;
+		if (patch.reviewedSha !== undefined) updated.reviewedSha = patch.reviewedSha;
+		if (patch.reviewedAt !== undefined) updated.reviewedAt = patch.reviewedAt;
+		if (patch.status !== undefined) updated.status = patch.status;
+		if (patch.resetStartedAt) updated.startedAt = now;
+		else if (patch.startedAt !== undefined) updated.startedAt = patch.startedAt;
+		updated.updatedAt = patch.updatedAt ?? now;
+		return this.writeReview(updated);
+	}
+
+	deleteReview(id: string): void {
+		const review = this.getReview(id);
+		if (!review) return;
+		this.files.removeDir(this.reviewDir(review));
+	}
+
+	// -----------------------------------------------------------------------
+	// Findings
+	// -----------------------------------------------------------------------
+
+	readFindings(reviewId: string): FindingsStateFile | null {
+		const review = this.getReview(reviewId);
+		if (!review) return null;
+		const raw = this.files.readJson<FindingsStateFile>(
+			join(this.reviewDir(review), FINDINGS_FILE),
+		);
+		if (!raw || raw.version !== FINDINGS_STATE_VERSION || !raw.findings) return null;
+		return raw;
+	}
+
+	writeFindings(reviewId: string, state: FindingsStateFile): void {
+		const review = this.getReview(reviewId);
+		if (!review) throw new Error(`Review '${reviewId}' não encontrada.`);
+		this.writeJson(join(this.reviewDir(review), FINDINGS_FILE), state);
+		this.writeReview({
+			...review,
+			reviewedSha: state.reviewed?.headSha,
+			reviewedAt: state.reviewed?.at,
+			updatedAt: state.updatedAt || systemClock(),
+		});
+	}
+
+	// -----------------------------------------------------------------------
+	// Artefatos
+	// -----------------------------------------------------------------------
+
+	readArtifact(reviewId: string, name: string): ArtifactRecord | null {
+		const review = this.getReview(reviewId);
+		if (!review) return null;
+		return this.readArtifacts(review)[name] ?? null;
+	}
+
+	writeArtifact(reviewId: string, input: WriteArtifactInput): ArtifactRecord {
+		const review = this.getReview(reviewId);
+		if (!review) throw new Error(`Review '${reviewId}' não encontrada.`);
+		const index = this.readArtifacts(review);
+		const now = systemClock();
+		const existing = index[input.name];
+		const contentType =
+			input.contentType ??
+			(input.name.toLowerCase().endsWith(".json")
+				? "application/json; charset=utf-8"
+				: "text/markdown; charset=utf-8");
+		const record: ArtifactRecord = {
+			id: existing?.id ?? randomUUID(),
+			reviewId,
+			name: input.name,
+			kind: input.kind,
+			content: input.content,
+			contentType,
+			createdAt: existing?.createdAt ?? now,
+			updatedAt: now,
+		};
+		index[input.name] = record;
+		this.writeJson(join(this.reviewDir(review), ARTIFACTS_FILE), index);
+		return record;
+	}
+
+	listArtifacts(reviewId: string): ArtifactRecord[] {
+		const review = this.getReview(reviewId);
+		if (!review) return [];
+		return Object.values(this.readArtifacts(review)).sort((a, b) =>
+			a.name.localeCompare(b.name),
+		);
+	}
+
+	deleteArtifact(reviewId: string, name: string): void {
+		const review = this.getReview(reviewId);
+		if (!review) return;
+		const index = this.readArtifacts(review);
+		if (!index[name]) return;
+		delete index[name];
+		this.writeJson(join(this.reviewDir(review), ARTIFACTS_FILE), index);
+	}
+
+	// -----------------------------------------------------------------------
+	// Manutenção / ciclo de vida
+	// -----------------------------------------------------------------------
+
+	maintain(): void {
+		// Nada a compactar: arquivos JSON são reescritos por inteiro.
+	}
+
+	location(reviewId: string): string {
+		const review = this.getReview(reviewId);
+		return review
+			? `file:${join(this.reviewDir(review), FINDINGS_FILE)}#${reviewId}`
+			: `file:${this.root}#${reviewId}`;
+	}
+
+	close(): void {
+		// Sem recurso aberto.
+	}
+
+	// -----------------------------------------------------------------------
+	// Internos
+	// -----------------------------------------------------------------------
+
+	private repoDir(repoKey: string): string {
+		const hash = createHash("sha256").update(repoKey).digest("hex").slice(0, 16);
+		return join(this.root, hash);
+	}
+
+	private reviewDir(review: ReviewRecord): string {
+		return join(this.repoDir(review.repoKey), review.slug);
+	}
+
+	private writeReview(record: ReviewRecord): ReviewRecord {
+		this.writeJson(join(this.reviewDir(record), REVIEW_FILE), record);
+		return record;
+	}
+
+	private readReviews(repoKey?: string): ReviewRecord[] {
+		const roots = repoKey ? [this.repoDir(repoKey)] : this.subdirectories(this.root);
+		const reviews: ReviewRecord[] = [];
+		for (const repoDir of roots) {
+			for (const slugDir of this.subdirectories(repoDir)) {
+				const review = this.files.readJson<ReviewRecord>(
+					join(slugDir, REVIEW_FILE),
+				);
+				if (review && (!repoKey || review.repoKey === repoKey)) {
+					reviews.push(review);
+				}
+			}
+		}
+		return reviews;
+	}
+
+	private readArtifacts(review: ReviewRecord): Record<string, ArtifactRecord> {
+		return (
+			this.files.readJson<Record<string, ArtifactRecord>>(
+				join(this.reviewDir(review), ARTIFACTS_FILE),
+			) ?? {}
+		);
+	}
+
+	private writeJson(path: string, value: unknown): void {
+		this.files.writeAtomic(path, `${JSON.stringify(value, null, 2)}\n`);
+	}
+
+	private subdirectories(dir: string): string[] {
+		if (!existsSync(dir)) return [];
+		try {
+			return readdirSync(dir)
+				.map((name) => join(dir, name))
+				.filter((path) => statSync(path).isDirectory());
+		} catch {
+			return [];
+		}
+	}
+}

package/src/core/storage/paths.ts

@@ -0,0 +1,64 @@
+/**
+ * Localização global do houndsman (biblioteca).
+ *
+ * O banco e o staging vivem no diretório de dados do usuário — nunca dentro do
+ * projeto nem da instalação npm. `HOUNDSMAN_HOME` sobrescreve tudo (útil em
+ * testes e para manter múltiplos ambientes).
+ */
+
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import type { HoundsmanConfig } from "../config";
+
+export const HOUNDSMAN_HOME_ENV = "HOUNDSMAN_HOME";
+
+/** Diretório-base global do houndsman. */
+export function houndsmanHome(): string {
+	const override = process.env[HOUNDSMAN_HOME_ENV];
+	if (override && override.trim().length > 0) return resolve(override);
+
+	const home = homedir();
+	if (process.platform === "win32") {
+		const local = process.env.LOCALAPPDATA;
+		return join(
+			local && local.length > 0 ? local : join(home, "AppData", "Local"),
+			"houndsman",
+		);
+	}
+	if (process.platform === "darwin") {
+		return join(home, "Library", "Application Support", "houndsman");
+	}
+	const xdg = process.env.XDG_DATA_HOME;
+	return join(xdg && xdg.length > 0 ? xdg : join(home, ".local", "share"), "houndsman");
+}
+
+/** Caminho do banco SQLite (config `storage.path` ou `<home>/houndsman.db`). */
+export function databasePath(config: HoundsmanConfig): string {
+	const configured = config.storage?.path;
+	if (configured && configured.trim().length > 0) return resolve(configured);
+	return join(houndsmanHome(), "houndsman.db");
+}
+
+/** Raiz das runs do provider de arquivos (config `storage.path` ou `<home>/runs`). */
+export function fileRoot(config: HoundsmanConfig): string {
+	const configured = config.storage?.path;
+	if (configured && configured.trim().length > 0) return resolve(configured);
+	return join(houndsmanHome(), "runs");
+}
+
+/** Raiz do staging por review (briefs/findings/contexto dos subagentes). */
+export function workRoot(): string {
+	return join(houndsmanHome(), "work");
+}
+
+/** Referência legível do storage configurado (diagnóstico). */
+export function storageLocation(config: HoundsmanConfig): string {
+	return config.storage?.provider === "file"
+		? `file:${fileRoot(config)}`
+		: `sqlite:${databasePath(config)}`;
+}
+
+/** Diretório de staging de uma review. */
+export function workDir(reviewId: string): string {
+	return join(workRoot(), reviewId);
+}

package/src/core/storage/repo-identity.ts

@@ -0,0 +1,70 @@
+/**
+ * Identidade do repositório (biblioteca).
+ *
+ * A UI e o CLI escopam runs por repositório. Preferimos o remote `origin`
+ * normalizado (`github.com/org/repo`) porque a pasta local pode ser movida;
+ * sem remote, caímos no caminho absoluto da raiz git.
+ */
+
+import { resolve } from "node:path";
+import { GitRepository } from "../services/git-repository";
+import type { RepoIdentity } from "./types";
+
+/** Normaliza um remote para `host/owner/repo` (sem protocolo, credencial ou `.git`). */
+export function normalizeRemote(raw: string): string | null {
+	const value = raw.trim().replace(/\/+$/, "");
+	if (value.length === 0) return null;
+
+	// SCP-like: `git@github.com:owner/repo.git`.
+	if (!value.includes("://")) {
+		const scp = value.match(/^(?:[^@/]+@)?([^:/]+):(.+)$/);
+		if (scp) return `${scp[1].toLowerCase()}/${stripGitSuffix(scp[2])}`;
+		// Caminho local — não é um remote utilizável para identidade.
+		return null;
+	}
+
+	try {
+		const url = new URL(value);
+		const host = url.hostname.toLowerCase();
+		const path = stripGitSuffix(url.pathname.replace(/^\/+/, "").replace(/\/+$/, ""));
+		return path.length > 0 ? `${host}/${path}` : host;
+	} catch {
+		return null;
+	}
+}
+
+function stripGitSuffix(value: string): string {
+	return value.replace(/\.git$/i, "").replace(/^\/+/, "");
+}
+
+/** Normaliza a raiz local para comparação (Windows é case-insensitive). */
+function normalizeRoot(root: string): string {
+	const normalized = resolve(root).replace(/\\/g, "/").replace(/\/+$/, "");
+	return process.platform === "win32" ? normalized.toLowerCase() : normalized;
+}
+
+/** Monta a identidade a partir do remote cru e da raiz do repositório. */
+export function buildRepoIdentity(
+	remote: string | null | undefined,
+	root: string,
+): RepoIdentity {
+	const normalized = remote ? normalizeRemote(remote) : null;
+	const absoluteRoot = resolve(root);
+	if (normalized) {
+		return {
+			key: `remote:${normalized}`,
+			root: absoluteRoot,
+			remote: remote ?? undefined,
+		};
+	}
+	return { key: `path:${normalizeRoot(absoluteRoot)}`, root: absoluteRoot };
+}
+
+/** Resolve a identidade do repositório a partir do cwd (nunca lança). */
+export function resolveRepoIdentity(
+	git: GitRepository = new GitRepository(),
+	cwd: string = process.cwd(),
+): RepoIdentity {
+	const root = git.rootPath() ?? resolve(cwd);
+	return buildRepoIdentity(git.remoteUrl(), root);
+}

package/src/core/storage/sqlite/mappers.ts

@@ -0,0 +1,160 @@
+/**
+ * Mapeamento row ↔ domínio do storage SQLite.
+ *
+ * O banco guarda `short_id` (id curto exibido no CLI) e um `id` UUID como PK.
+ * O domínio continua usando `FindingState.id` = short id.
+ */
+
+import type { FindingAnchor } from "../../finding-anchor";
+import type {
+	FindingDecision,
+	FindingExecState,
+	FindingHistoryEntry,
+	FindingState,
+	GitHubLink,
+} from "../../findings-state";
+import type { Severity } from "../../types";
+import type { ArtifactKind, ArtifactRecord, ReviewRecord } from "../types";
+
+export type ReviewRow = {
+	id: string;
+	repo_key: string;
+	repo_root: string;
+	repo_remote: string | null;
+	branch: string;
+	slug: string;
+	base: string | null;
+	head: string | null;
+	head_sha: string | null;
+	reviewed_sha: string | null;
+	reviewed_at: string | null;
+	status: string | null;
+	started_at: string | null;
+	created_at: string;
+	updated_at: string;
+};
+
+export type FindingRow = {
+	id: string;
+	review_id: string;
+	short_id: string;
+	fingerprint: string;
+	watchdog_ids: string;
+	rule: string;
+	severity: string;
+	file: string;
+	line: number | null;
+	message: string;
+	action: string;
+	evidence: string | null;
+	anchor: string | null;
+	found_at_sha: string | null;
+	count: number;
+	present: number;
+	decision: string;
+	comment: string | null;
+	exec_state: string;
+	github: string | null;
+	created_at: string;
+	updated_at: string;
+};
+
+export type HistoryRow = {
+	id: string;
+	finding_id: string;
+	at: string;
+	decision: string;
+	exec_state: string;
+	comment: string | null;
+	by: string | null;
+};
+
+export type ArtifactRow = {
+	id: string;
+	review_id: string;
+	name: string;
+	kind: string;
+	content: string;
+	content_type: string;
+	created_at: string;
+	updated_at: string;
+};
+
+/** Converte a row de review no DTO do contrato. */
+export function reviewFromRow(row: ReviewRow): ReviewRecord {
+	return {
+		id: row.id,
+		repoKey: row.repo_key,
+		repoRoot: row.repo_root,
+		repoRemote: row.repo_remote ?? undefined,
+		branch: row.branch,
+		slug: row.slug,
+		base: row.base ?? undefined,
+		head: row.head ?? undefined,
+		headSha: row.head_sha ?? undefined,
+		reviewedSha: row.reviewed_sha ?? undefined,
+		reviewedAt: row.reviewed_at ?? undefined,
+		status: (row.status as ReviewRecord["status"]) ?? null,
+		startedAt: row.started_at ?? undefined,
+		createdAt: row.created_at,
+		updatedAt: row.updated_at,
+	};
+}
+
+function parseJson<T>(raw: string | null): T | undefined {
+	if (!raw) return undefined;
+	try {
+		return JSON.parse(raw) as T;
+	} catch {
+		return undefined;
+	}
+}
+
+/** Converte a row de finding (+ histórico) no DTO do domínio. */
+export function findingFromRow(row: FindingRow, history: HistoryRow[]): FindingState {
+	return {
+		id: row.short_id,
+		fingerprint: row.fingerprint,
+		watchdogIds: parseJson<string[]>(row.watchdog_ids) ?? [],
+		rule: row.rule,
+		severity: row.severity as Severity,
+		file: row.file,
+		line: row.line === null ? null : Number(row.line),
+		message: row.message,
+		action: row.action,
+		evidence: row.evidence ?? undefined,
+		anchor: parseJson<FindingAnchor>(row.anchor) ?? null,
+		foundAtSha: row.found_at_sha ?? undefined,
+		count: Number(row.count),
+		present: row.present === 1,
+		decision: row.decision as FindingDecision,
+		comment: row.comment ?? undefined,
+		execState: row.exec_state as FindingExecState,
+		createdAt: row.created_at,
+		updatedAt: row.updated_at,
+		history: history.map((entry) => ({
+			at: entry.at,
+			decision: entry.decision as FindingDecision,
+			execState: entry.exec_state as FindingExecState,
+			comment: entry.comment ?? undefined,
+			by: entry.by ?? undefined,
+		})),
+		github: parseJson<GitHubLink>(row.github),
+	};
+}
+
+/** Converte a row de artefato no DTO do contrato. */
+export function artifactFromRow(row: ArtifactRow): ArtifactRecord {
+	return {
+		id: row.id,
+		reviewId: row.review_id,
+		name: row.name,
+		kind: row.kind as ArtifactKind,
+		content: row.content,
+		contentType: row.content_type,
+		createdAt: row.created_at,
+		updatedAt: row.updated_at,
+	};
+}
+
+export type { FindingHistoryEntry };