@payconductor/houndsman 0.0.0-stage → 0.1.1

package/src/core/finding-anchor.ts

@@ -0,0 +1,147 @@
+/**
+ * Identidade e reancoragem de findings (biblioteca).
+ *
+ * Um finding NÃO é identificado pela linha: a linha desloca após um auto-fix.
+ * A identidade é o `fingerprint` (arquivo + regra + âncora de conteúdo); a linha
+ * é apenas cache, recalculada varrendo o arquivo (`locateAnchor`).
+ *
+ * Âncora = linha ofensora normalizada + contexto (linha anterior/seguinte).
+ * Quando o fix altera a linha ofensora, a âncora some → o finding fica `stale`.
+ *
+ * Ocorrências byte-idênticas (mesmo snippet E mesmo contexto) compartilham o
+ * fingerprint: são tratadas como um grupo (limitação conhecida).
+ */
+
+import { createHash } from "node:crypto";
+
+/** Âncora de conteúdo de um finding (independente do número da linha). */
+export type FindingAnchor = {
+	/** Linha ofensora normalizada. */
+	snippet: string;
+	/** Linha anterior normalizada (ausente se a ofensora for a primeira). */
+	contextBefore?: string;
+	/** Linha seguinte normalizada (ausente se a ofensora for a última). */
+	contextAfter?: string;
+	/** Última linha conhecida (1-based) — cache, nunca identidade. */
+	line: number;
+};
+
+/** Resultado da localização de uma âncora no conteúdo atual. */
+export type AnchorLocation = {
+	/** Linha atual (1-based) ou null se a âncora não existe mais. */
+	line: number | null;
+	/** Nº de ocorrências da âncora no arquivo. */
+	occurrences: number;
+};
+
+/** Normaliza uma linha: colapsa espaços internos e apara as pontas. */
+export function normalizeLine(raw: string): string {
+	return raw.replace(/\s+/g, " ").trim();
+}
+
+/** Conteúdo → linhas normalizadas (uma por linha do arquivo). */
+export function normalizedLines(content: string): string[] {
+	return content.split(/\r?\n/).map(normalizeLine);
+}
+
+/** Marcador de contexto ausente (não confundir com linha vazia). */
+const ABSENT = "\u0001";
+
+/** Chave estável da âncora (snippet + contexto, SEM a linha). */
+function anchorKey(anchor: FindingAnchor): string {
+	return [
+		anchor.snippet,
+		anchor.contextBefore ?? ABSENT,
+		anchor.contextAfter ?? ABSENT,
+	].join("\u0000");
+}
+
+/** Hash estável (sha256 truncado) — base das identidades do motor. */
+export function hashKey(input: string): string {
+	return createHash("sha256").update(input).digest("hex").slice(0, 16);
+}
+
+/**
+ * Fingerprint do finding: `arquivo + regra + âncora`. Sem a linha — permanece
+ * estável após edições que deslocam o trecho. Sem âncora, cai no `fallback`
+ * (ex.: `message`). Ocorrências com a MESMA âncora compartilham o fingerprint.
+ */
+export function fingerprintOf(
+	file: string,
+	rule: string,
+	anchor: FindingAnchor | null,
+	fallback = "",
+): string {
+	const key = anchor ? anchorKey(anchor) : `fallback:${fallback}`;
+	return hashKey(`${file}\u0000${rule}\u0000${key}`);
+}
+
+/**
+ * Monta a âncora a partir do conteúdo: usa a `line` (1-based) quando válida;
+ * senão procura a linha que contém a `evidence`. Retorna null se não localizar
+ * (ex.: arquivo deletado/binário).
+ */
+export function buildAnchor(
+	content: string,
+	line: number | undefined,
+	evidence?: string,
+): FindingAnchor | null {
+	const lines = normalizedLines(content);
+
+	let index = -1;
+	if (line !== undefined && line >= 1 && line <= lines.length) {
+		index = line - 1;
+	} else if (evidence) {
+		const needle = normalizeLine(evidence);
+		if (needle) index = lines.findIndex((l) => l.includes(needle));
+	}
+	if (index < 0) return null;
+
+	const anchor: FindingAnchor = { snippet: lines[index], line: index + 1 };
+	if (index - 1 >= 0) anchor.contextBefore = lines[index - 1];
+	if (index + 1 < lines.length) anchor.contextAfter = lines[index + 1];
+	return anchor;
+}
+
+/** `true` se a linha `i` casa a âncora (snippet + contexto). */
+function matchesAt(lines: string[], i: number, anchor: FindingAnchor): boolean {
+	if (lines[i] !== anchor.snippet) return false;
+	if (anchor.contextBefore !== undefined && lines[i - 1] !== anchor.contextBefore) {
+		return false;
+	}
+	if (anchor.contextAfter !== undefined && lines[i + 1] !== anchor.contextAfter) {
+		return false;
+	}
+	return true;
+}
+
+/** Localiza a âncora no conteúdo atual (linha + nº de ocorrências). */
+export function locateAnchor(
+	content: string,
+	anchor: FindingAnchor | null,
+): AnchorLocation {
+	if (!anchor) return { line: null, occurrences: 0 };
+	const lines = normalizedLines(content);
+	let occurrences = 0;
+	let first = -1;
+	for (let i = 0; i < lines.length; i++) {
+		if (!matchesAt(lines, i, anchor)) continue;
+		occurrences++;
+		if (first < 0) first = i;
+	}
+	return { line: first < 0 ? null : first + 1, occurrences };
+}
+
+export type ReanchorStatus = "ok" | "moved" | "stale";
+
+/** Reancora um finding: recalcula a linha e classifica o deslocamento. */
+export function reanchor(
+	content: string,
+	anchor: FindingAnchor | null,
+	previousLine: number | null,
+): { status: ReanchorStatus; line: number | null } {
+	const { line } = locateAnchor(content, anchor);
+	if (line === null) return { status: "stale", line: null };
+	if (previousLine !== null && line === previousLine) return { status: "ok", line };
+	return { status: "moved", line };
+}

package/src/core/findings-state.ts

@@ -0,0 +1,538 @@
+/**
+ * Estado de triagem dos findings (biblioteca).
+ *
+ * Persistido em `.houndsman/.runs/<slug>/state.json` (local — coberto pelo
+ * `.gitignore` gerado, que ignora `.runs/`). Cada finding tem um `id` curto e um
+ * `fingerprint` de conteúdo: nas re-execuções do `--finalize` o estado é
+ * preservado casando por fingerprint.
+ *
+ * A `line` é cache — `syncState` a recalcula após edições (auto-fix) e marca
+ * `stale` quando a âncora some.
+ */
+
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import {
+	buildAnchor,
+	type FindingAnchor,
+	fingerprintOf,
+	locateAnchor,
+	reanchor,
+} from "./finding-anchor";
+import { STATE_FILE } from "./paths";
+import {
+	dedupeFindings,
+	type MergedFinding,
+	parseWatchdogReport,
+	sanitizeBranch,
+	type WatchdogReport,
+} from "./report-builder";
+import { SEVERITY_ORDER, type Severity, severityRank } from "./types";
+
+// ---------------------------------------------------------------------------
+// Tipos
+// ---------------------------------------------------------------------------
+
+/** Decisão de triagem: o que fazer com o finding. */
+export type FindingDecision = "pending" | "execute" | "ignore";
+
+/** Estado de execução: em que pé está a ação. */
+export type FindingExecState = "pending" | "in_progress" | "done" | "stale";
+
+/** Valores canônicos (na ordem de exibição). */
+export const FINDING_DECISIONS: readonly FindingDecision[] = [
+	"pending",
+	"execute",
+	"ignore",
+];
+
+/** Valores canônicos de `execState`. */
+export const FINDING_EXEC_STATES: readonly FindingExecState[] = [
+	"pending",
+	"in_progress",
+	"done",
+	"stale",
+];
+
+const DECISION_SET = new Set<string>(FINDING_DECISIONS);
+const EXEC_SET = new Set<string>(FINDING_EXEC_STATES);
+
+/** Entrada de auditoria (quem mudou o quê). */
+export type FindingHistoryEntry = {
+	at: string;
+	decision: FindingDecision;
+	execState: FindingExecState;
+	comment?: string;
+	by?: string;
+};
+
+/** Um finding triável, com o estado das duas dimensões. */
+export type FindingState = {
+	id: string;
+	fingerprint: string;
+	watchdogIds: string[];
+	rule: string;
+	severity: Severity;
+	file: string;
+	line: number | null;
+	message: string;
+	action: string;
+	evidence?: string;
+	anchor: FindingAnchor | null;
+	/** Ocorrências idênticas colapsadas neste fingerprint (>1 = grupo). */
+	count: number;
+	/** Ainda presente no último relatório consolidado. */
+	present: boolean;
+	decision: FindingDecision;
+	comment?: string;
+	execState: FindingExecState;
+	createdAt: string;
+	updatedAt: string;
+	history: FindingHistoryEntry[];
+};
+
+/** Conteúdo do `state.json`. */
+export type FindingsStateFile = {
+	version: 1;
+	branch: string;
+	slug: string;
+	updatedAt: string;
+	/** Ids na ordem de exibição (estável). */
+	order: string[];
+	findings: Record<string, FindingState>;
+};
+
+export const FINDINGS_STATE_VERSION = 1;
+
+// ---------------------------------------------------------------------------
+// Caminhos
+// ---------------------------------------------------------------------------
+
+/** Diretório de artefatos da run (branch-slug). */
+export function runDir(artifactDir: string, branch: string): string {
+	return join(artifactDir, sanitizeBranch(branch));
+}
+
+/** Caminho do `state.json` da run. */
+export function stateFile(artifactDir: string, branch: string): string {
+	return join(runDir(artifactDir, branch), STATE_FILE);
+}
+
+/** Leitor de arquivos relativos à raiz do projeto (injetável nos testes). */
+export type FileReader = (relativePath: string) => string | null;
+
+/** Leitor padrão a partir do cwd (null se ausente/ilegível). */
+export function fileReader(cwd: string): FileReader {
+	return (relativePath: string) => {
+		try {
+			const full = join(cwd, relativePath);
+			return existsSync(full) ? readFileSync(full, "utf8") : null;
+		} catch {
+			return null;
+		}
+	};
+}
+
+/** Id curto aleatório (hex) para um finding novo. */
+export function newFindingId(): string {
+	return randomUUID().replace(/-/g, "").slice(0, 10);
+}
+
+/** Estado vazio para uma branch. */
+export function emptyState(branch: string): FindingsStateFile {
+	return {
+		version: FINDINGS_STATE_VERSION,
+		branch,
+		slug: sanitizeBranch(branch),
+		updatedAt: new Date().toISOString(),
+		order: [],
+		findings: {},
+	};
+}
+
+// ---------------------------------------------------------------------------
+// Ordenação / resumo
+// ---------------------------------------------------------------------------
+
+/** Presentes primeiro; depois severidade, arquivo e linha. */
+export function compareFindings(a: FindingState, b: FindingState): number {
+	if (a.present !== b.present) return a.present ? -1 : 1;
+	const bySeverity = severityRank(a.severity) - severityRank(b.severity);
+	if (bySeverity !== 0) return bySeverity;
+	if (a.file !== b.file) return a.file.localeCompare(b.file);
+	return (a.line ?? 0) - (b.line ?? 0);
+}
+
+/** Ordena os ids do estado (recomputa `order`). */
+export function reorder(state: FindingsStateFile): void {
+	state.order = Object.values(state.findings)
+		.sort(compareFindings)
+		.map((f) => f.id);
+}
+
+export type FindingsSummary = {
+	total: number;
+	present: number;
+	byDecision: Record<FindingDecision, number>;
+	byExecState: Record<FindingExecState, number>;
+	bySeverity: Record<Severity, number>;
+};
+
+/** Contagens por decisão, execução e severidade. */
+export function summarize(state: FindingsStateFile): FindingsSummary {
+	const byDecision = Object.fromEntries(FINDING_DECISIONS.map((d) => [d, 0])) as Record<
+		FindingDecision,
+		number
+	>;
+	const byExecState = Object.fromEntries(
+		FINDING_EXEC_STATES.map((e) => [e, 0]),
+	) as Record<FindingExecState, number>;
+	const bySeverity = Object.fromEntries(SEVERITY_ORDER.map((s) => [s, 0])) as Record<
+		Severity,
+		number
+	>;
+
+	let total = 0;
+	let present = 0;
+	for (const finding of Object.values(state.findings)) {
+		total++;
+		if (finding.present) present++;
+		byDecision[finding.decision]++;
+		byExecState[finding.execState]++;
+		bySeverity[finding.severity]++;
+	}
+	return { total, present, byDecision, byExecState, bySeverity };
+}
+
+// ---------------------------------------------------------------------------
+// Filtro
+// ---------------------------------------------------------------------------
+
+export type FindingsFilter = {
+	decision?: FindingDecision;
+	execState?: FindingExecState;
+	watchdog?: string;
+	severity?: Severity;
+	/** Substring do caminho (case-insensitive). */
+	file?: string;
+	/** Inclui findings ausentes do último relatório (default: só presentes). */
+	includeAbsent?: boolean;
+};
+
+/** Aplica o filtro e devolve os findings ordenados. */
+export function filterFindings(
+	state: FindingsStateFile,
+	filter: FindingsFilter = {},
+): FindingState[] {
+	const needle = filter.file?.toLowerCase();
+	return Object.values(state.findings)
+		.filter((finding) => {
+			if (!filter.includeAbsent && !finding.present) return false;
+			if (filter.decision && finding.decision !== filter.decision) return false;
+			if (filter.execState && finding.execState !== filter.execState) return false;
+			if (filter.severity && finding.severity !== filter.severity) return false;
+			if (filter.watchdog && !finding.watchdogIds.includes(filter.watchdog)) {
+				return false;
+			}
+			if (needle && !finding.file.toLowerCase().includes(needle)) return false;
+			return true;
+		})
+		.sort(compareFindings);
+}
+
+// ---------------------------------------------------------------------------
+// Construção (finalize)
+// ---------------------------------------------------------------------------
+
+export type BuildStateOptions = {
+	branch: string;
+	readFile: FileReader;
+	previous?: FindingsStateFile | null;
+	now?: string;
+};
+
+/**
+ * Constrói o estado a partir dos findings consolidados, preservando o que já
+ * existia (casando por `fingerprint`). Depende de ler o arquivo para ancorar;
+ * sem conteúdo (deletado/binário) a âncora fica nula e o fingerprint cai no
+ * `message`.
+ *
+ * Muta cada `finding` recebido com o `id` correspondente (para o relatório).
+ */
+export function buildStateFromFindings(
+	merged: readonly MergedFinding[],
+	options: BuildStateOptions,
+): FindingsStateFile {
+	const now = options.now ?? new Date().toISOString();
+	const previous = options.previous ?? null;
+
+	const result: Record<string, FindingState> = {};
+	// 1. Preserva o estado anterior (marca como ausente até provar o contrário).
+	for (const prev of Object.values(previous?.findings ?? {})) {
+		result[prev.id] = {
+			...prev,
+			present: false,
+			execState:
+				prev.execState === "pending" && prev.decision === "execute"
+					? "done"
+					: prev.execState,
+			updatedAt: now,
+		};
+	}
+
+	// 2. Findings atuais, agrupados por fingerprint.
+	const byFingerprint = new Map<string, FindingState>();
+	for (const finding of merged) {
+		const content = options.readFile(finding.file);
+		const anchor = content
+			? buildAnchor(content, finding.line, finding.evidence)
+			: null;
+		const fingerprint = fingerprintOf(
+			finding.file,
+			finding.rule,
+			anchor,
+			finding.message,
+		);
+
+		const group = byFingerprint.get(fingerprint);
+		if (group) {
+			group.count++;
+			for (const w of finding.watchdogs) {
+				if (!group.watchdogIds.includes(w)) group.watchdogIds.push(w);
+			}
+			finding.id = group.id;
+			continue;
+		}
+
+		const prev = previous
+			? Object.values(previous.findings).find((f) => f.fingerprint === fingerprint)
+			: undefined;
+		const created: FindingState = {
+			id: prev?.id ?? newFindingId(),
+			fingerprint,
+			watchdogIds: [...finding.watchdogs],
+			rule: finding.rule,
+			severity: finding.severity,
+			file: finding.file,
+			line: anchor ? anchor.line : null,
+			message: finding.message,
+			action: finding.action,
+			evidence: finding.evidence,
+			anchor,
+			count: 1,
+			present: true,
+			decision: prev?.decision ?? "pending",
+			comment: prev?.comment,
+			execState: prev?.execState ?? "pending",
+			createdAt: prev?.createdAt ?? now,
+			updatedAt: now,
+			history: prev?.history ?? [],
+		};
+		byFingerprint.set(fingerprint, created);
+		result[created.id] = created;
+		finding.id = created.id;
+	}
+
+	const state: FindingsStateFile = {
+		version: FINDINGS_STATE_VERSION,
+		branch: options.branch,
+		slug: sanitizeBranch(options.branch),
+		updatedAt: now,
+		order: [],
+		findings: result,
+	};
+	reorder(state);
+	return state;
+}
+
+/**
+ * Reconstrói o estado a partir dos artefatos da run (`classification.json` +
+ * `findings/<id>.json`), sem exigir `--finalize`. Devolve null se não houver
+ * findings gravados.
+ */
+export function buildStateFromRunDir(
+	outDir: string,
+	branch: string,
+	readFile: FileReader,
+): FindingsStateFile | null {
+	const classificationPath = join(outDir, "classification.json");
+	if (!existsSync(classificationPath)) return null;
+
+	let activeIds: string[] = [];
+	try {
+		const classification = JSON.parse(readFileSync(classificationPath, "utf8")) as {
+			watchdogs?: Record<string, string[]>;
+		};
+		activeIds = Object.keys(classification.watchdogs ?? {});
+	} catch {
+		return null;
+	}
+
+	const reports: WatchdogReport[] = [];
+	for (const id of activeIds) {
+		const path = join(outDir, "findings", `${id}.json`);
+		if (!existsSync(path)) continue;
+		try {
+			const report = parseWatchdogReport(
+				JSON.parse(readFileSync(path, "utf8")),
+				path,
+			);
+			if (report) reports.push(report);
+		} catch {
+			// Ignora findings ilegíveis — reconstrução best-effort.
+		}
+	}
+	if (reports.length === 0) return null;
+
+	return buildStateFromFindings(dedupeFindings(reports), { branch, readFile });
+}
+// ---------------------------------------------------------------------------
+
+export type FindingUpdate = {
+	decision?: FindingDecision;
+	comment?: string;
+	execState?: FindingExecState;
+	by?: string;
+};
+
+/** Aplica uma atualização a um finding (registrando histórico). */
+export function applyFindingUpdate(
+	finding: FindingState,
+	update: FindingUpdate,
+	now: string = new Date().toISOString(),
+): FindingState {
+	if (update.decision && DECISION_SET.has(update.decision)) {
+		finding.decision = update.decision;
+	}
+	if (update.execState && EXEC_SET.has(update.execState)) {
+		finding.execState = update.execState;
+	}
+	if (update.comment !== undefined) finding.comment = update.comment;
+	finding.updatedAt = now;
+	finding.history.push({
+		at: now,
+		decision: finding.decision,
+		execState: finding.execState,
+		comment: finding.comment,
+		by: update.by,
+	});
+	return finding;
+}
+
+export type SyncResult = {
+	ok: number;
+	moved: string[];
+	stale: string[];
+};
+
+/**
+ * Reancora todos os findings presentes lendo os arquivos atuais. Findings cuja
+ * âncora sumiu viram `stale` (ou `done` se a decisão era `execute`).
+ * Muta o estado em memória (o caller persiste).
+ */
+export function syncState(
+	state: FindingsStateFile,
+	readFile: FileReader,
+	now: string = new Date().toISOString(),
+): SyncResult {
+	const moved: string[] = [];
+	const stale: string[] = [];
+	let ok = 0;
+
+	for (const finding of Object.values(state.findings)) {
+		if (!finding.present) continue;
+		const content = readFile(finding.file);
+		if (content === null) {
+			if (finding.execState !== "done") finding.execState = "stale";
+			finding.updatedAt = now;
+			stale.push(finding.id);
+			continue;
+		}
+		const { status, line } = reanchor(content, finding.anchor, finding.line);
+		if (status === "stale") {
+			finding.execState =
+				finding.decision === "execute" && finding.execState === "pending"
+					? "done"
+					: finding.execState === "done"
+						? "done"
+						: "stale";
+			finding.updatedAt = now;
+			stale.push(finding.id);
+			continue;
+		}
+		if (status === "moved" && line !== null) {
+			finding.line = line;
+			if (finding.anchor) finding.anchor.line = line;
+			finding.updatedAt = now;
+			moved.push(finding.id);
+			continue;
+		}
+		ok++;
+	}
+
+	if (moved.length > 0 || stale.length > 0) state.updatedAt = now;
+	return { ok, moved, stale };
+}
+
+/** Nº de ocorrências da âncora na versão atual do arquivo (diagnóstico). */
+export function occurrenceCount(
+	fileContent: string,
+	anchor: FindingAnchor | null,
+): number {
+	return locateAnchor(fileContent, anchor).occurrences;
+}
+
+// ---------------------------------------------------------------------------
+// Store (I/O atômico)
+// ---------------------------------------------------------------------------
+
+/** Persistência do `state.json` — escrita atômica (tmp + rename). */
+export class FindingsStateStore {
+	private readonly path: string;
+	private readonly branch: string;
+
+	constructor(path: string, branch: string) {
+		this.path = path;
+		this.branch = branch;
+	}
+
+	/** Store para a run de uma branch. */
+	static at(artifactDir: string, branch: string): FindingsStateStore {
+		return new FindingsStateStore(stateFile(artifactDir, branch), branch);
+	}
+
+	get filePath(): string {
+		return this.path;
+	}
+
+	/** Lê o estado; null se ausente/inválido. */
+	read(): FindingsStateFile | null {
+		if (!existsSync(this.path)) return null;
+		try {
+			const raw = JSON.parse(readFileSync(this.path, "utf8")) as FindingsStateFile;
+			if (raw?.version !== FINDINGS_STATE_VERSION || !raw.findings) return null;
+			return raw;
+		} catch {
+			return null;
+		}
+	}
+
+	/** Grava o estado de forma atômica. */
+	write(state: FindingsStateFile): void {
+		mkdirSync(dirname(this.path), { recursive: true });
+		const tmp = `${this.path}.${process.pid}.tmp`;
+		writeFileSync(tmp, `${JSON.stringify(state, null, 2)}\n`);
+		renameSync(tmp, this.path);
+	}
+
+	/** Lê-modifica-grava; parte de um estado vazio se não existir. */
+	update(mutator: (state: FindingsStateFile) => void): FindingsStateFile {
+		const state = this.read() ?? emptyState(this.branch);
+		mutator(state);
+		state.updatedAt = new Date().toISOString();
+		reorder(state);
+		this.write(state);
+		return state;
+	}
+}

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";