@payconductor/houndsman 0.1.0 → 0.1.1

package/src/index.ts

@@ -7,8 +7,22 @@
 
 export { assetPath, OUTPUT_FORMAT_FILE } from "./core/assets";
 export { defaultRenderBrief, PROCEDURE, renderBrief } from "./core/brief";
-export type { HoundsmanConfig, HoundsmanConfigInput } from "./core/config";
-export { DEFAULT_ALWAYS_INCLUDE_DOCS, defineHoundsmanConfig } from "./core/config";
+export type { FindingsCommandResult } from "./core/commands/findings";
+export { runFindingsCommand } from "./core/commands/findings";
+export type {
+	HoundsmanBudgets,
+	HoundsmanConcurrency,
+	HoundsmanConfig,
+	HoundsmanConfigInput,
+} from "./core/config";
+export {
+	DEFAULT_ALWAYS_INCLUDE_DOCS,
+	DEFAULT_JEV_CONCURRENCY,
+	DEFAULT_MAX_FILES_PER_BRIEF,
+	defineHoundsmanConfig,
+	resolveJevConcurrency,
+	resolveMaxFilesPerBrief,
+} from "./core/config";
 export type { LoadedConfig } from "./core/config-loader";
 export {
 	CONFIG_FILE_CANDIDATES,
@@ -16,12 +30,67 @@ export {
 	resolveConfigPath,
 } from "./core/config-loader";
 export {
+	collectChurn,
+	collectDiff,
+	type DiffSource,
+	parseDiffIndex,
+	parseNumstat,
+} from "./core/diff-source";
+export {
+	churnOf,
 	classifyEntries,
 	classifyRange,
 	isExcludedPath,
 	matchWatchdogs,
 	parseEntries,
+	selectByBudget,
+	sortByRisk,
 } from "./core/file-classifier";
+export type {
+	AnchorLocation,
+	FindingAnchor,
+	ReanchorStatus,
+} from "./core/finding-anchor";
+export {
+	buildAnchor,
+	fingerprintOf,
+	hashKey,
+	locateAnchor,
+	normalizeLine,
+	reanchor,
+} from "./core/finding-anchor";
+export type {
+	BuildStateOptions,
+	FileReader,
+	FindingDecision,
+	FindingExecState,
+	FindingHistoryEntry,
+	FindingState,
+	FindingsFilter,
+	FindingsStateFile,
+	FindingsSummary,
+	FindingUpdate,
+	SyncResult,
+} from "./core/findings-state";
+export {
+	applyFindingUpdate,
+	buildStateFromFindings,
+	buildStateFromRunDir,
+	compareFindings,
+	emptyState,
+	FINDING_DECISIONS,
+	FINDING_EXEC_STATES,
+	FINDINGS_STATE_VERSION,
+	FindingsStateStore,
+	fileReader,
+	filterFindings,
+	newFindingId,
+	reorder,
+	runDir,
+	stateFile,
+	summarize,
+	syncState,
+} from "./core/findings-state";
 export {
 	ARTIFACT_DIR,
 	CORE_DIR,
@@ -29,10 +98,15 @@ export {
 	OUTPUT_FORMAT_PATH,
 	PROJECT_DIR,
 	relFromRoot,
+	STATE_FILE,
 } from "./core/paths";
 export { checkRegistry } from "./core/registry-check";
+export type { DomainReport } from "./core/report-builder";
+export { renderDomainReport } from "./core/report-builder";
 export type {
+	ChurnMap,
 	ClassifyRule,
+	FileChurn,
 	FileStatus,
 	FileStatusMap,
 	Rule,
@@ -54,3 +128,5 @@ export {
 	getWatchdog,
 	getWatchdogContext,
 } from "./core/watchdog-registry";
+export type { ServerOptions } from "./server";
+export { createRequestHandler, startServer } from "./server";

package/src/server/artifacts.ts

@@ -0,0 +1,66 @@
+/**
+ * Descoberta de runs e leitura segura de artefatos (servidor).
+ *
+ * Toda leitura é restrita à pasta da run — `readRunFile` barra path traversal.
+ */
+
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { isAbsolute, join, relative, resolve } from "node:path";
+
+/** Arquivos que marcam uma pasta como "run" do houndsman. */
+const RUN_MARKERS = [
+	"manifest.json",
+	"state.json",
+	"classification.json",
+	"review.md",
+] as const;
+
+/** Slugs (nomes de pasta) das runs sob o `artifactDir`. */
+export function listRunSlugs(artifactDir: string): string[] {
+	if (!existsSync(artifactDir)) return [];
+	try {
+		return readdirSync(artifactDir, { withFileTypes: true })
+			.filter((entry) => entry.isDirectory())
+			.map((entry) => entry.name)
+			.filter((slug) =>
+				RUN_MARKERS.some((marker) => existsSync(join(artifactDir, slug, marker))),
+			)
+			.sort();
+	} catch {
+		return [];
+	}
+}
+
+/** Diretório absoluto de uma run; null se o slug for inválido/inexistente. */
+export function runDirForSlug(artifactDir: string, slug: string): string | null {
+	if (!/^[a-zA-Z0-9._-]+$/.test(slug)) return null;
+	const dir = join(artifactDir, slug);
+	if (!existsSync(dir) || !statSync(dir).isDirectory()) return null;
+	return dir;
+}
+
+/** Lê um arquivo DENTRO da run; null se ausente ou fora do diretório. */
+export function readRunFile(runDir: string, name: string): string | null {
+	const root = resolve(runDir);
+	const target = resolve(root, name);
+	const rel = relative(root, target);
+	if (rel === "" || rel.startsWith("..") || isAbsolute(rel)) return null;
+	try {
+		return existsSync(target) && statSync(target).isFile()
+			? readFileSync(target, "utf8")
+			: null;
+	} catch {
+		return null;
+	}
+}
+
+/** Lê e faz parse de um JSON da run (null se ausente/inválido). */
+export function readRunJson<T>(runDir: string, name: string): T | null {
+	const raw = readRunFile(runDir, name);
+	if (raw === null) return null;
+	try {
+		return JSON.parse(raw) as T;
+	} catch {
+		return null;
+	}
+}

package/src/server/client/App.tsx

@@ -0,0 +1,158 @@
+/**
+ * App: layout do servidor — sidebar de runs, abas (Findings/Artefatos), legenda
+ * da aba ativa e os painéis. Concentra o estado e as chamadas à API.
+ */
+
+import { useCallback, useEffect, useMemo, useState } from "preact/hooks";
+import { ArtifactsPanel } from "./ArtifactsPanel";
+import { api, computeSummary } from "./api";
+import { TAB_CAPTIONS } from "./constants";
+import { Filters, type FiltersState } from "./Filters";
+import { FindingsList } from "./FindingsList";
+import { RunList } from "./RunList";
+import { SummaryBar } from "./SummaryBar";
+import type { Finding, FindingsResponse, RunSummary } from "./types";
+
+type Tab = "findings" | "artifacts";
+
+export function App() {
+	const [runs, setRuns] = useState<RunSummary[]>([]);
+	const [slug, setSlug] = useState<string | null>(null);
+	const [data, setData] = useState<FindingsResponse | null>(null);
+	const [tab, setTab] = useState<Tab>("findings");
+	const [filters, setFilters] = useState<FiltersState>({
+		query: "",
+		decision: "all",
+		severity: "all",
+		showAbsent: false,
+	});
+	const [error, setError] = useState("");
+
+	const reloadRuns = useCallback(async () => {
+		try {
+			const { runs: list } = await api<{ runs: RunSummary[] }>("/api/runs");
+			setRuns(list);
+			setSlug((current) => current ?? list[0]?.slug ?? null);
+		} catch (err) {
+			setError(String(err));
+		}
+	}, []);
+
+	const loadFindings = useCallback(async (target: string) => {
+		try {
+			setData(await api<FindingsResponse>(`/api/runs/${target}/findings?all=1`));
+			setError("");
+		} catch (err) {
+			setError(String(err));
+		}
+	}, []);
+
+	useEffect(() => {
+		reloadRuns();
+	}, [reloadRuns]);
+
+	useEffect(() => {
+		if (slug) loadFindings(slug);
+	}, [slug, loadFindings]);
+
+	const onUpdated = useCallback(
+		(updated: Finding) => {
+			setData((current) =>
+				current
+					? {
+							...current,
+							findings: current.findings.map((finding) =>
+								finding.id === updated.id ? updated : finding,
+							),
+						}
+					: current,
+			);
+			reloadRuns();
+		},
+		[reloadRuns],
+	);
+
+	const sync = useCallback(async () => {
+		if (!slug) return;
+		await api(`/api/runs/${slug}/sync`, { method: "POST" });
+		await loadFindings(slug);
+		await reloadRuns();
+	}, [slug, loadFindings, reloadRuns]);
+
+	const findings = useMemo(() => {
+		const needle = filters.query.trim().toLowerCase();
+		return (data?.findings ?? [])
+			.filter((finding) => filters.showAbsent || finding.present)
+			.filter(
+				(finding) =>
+					filters.decision === "all" || finding.decision === filters.decision,
+			)
+			.filter(
+				(finding) =>
+					filters.severity === "all" || finding.severity === filters.severity,
+			)
+			.filter(
+				(finding) =>
+					!needle ||
+					finding.file.toLowerCase().includes(needle) ||
+					finding.rule.toLowerCase().includes(needle) ||
+					finding.message.toLowerCase().includes(needle),
+			);
+	}, [data, filters]);
+
+	const summary = useMemo(() => computeSummary(data?.findings ?? []), [data]);
+
+	return (
+		<div class="app">
+			<RunList runs={runs} slug={slug} onSelect={setSlug} />
+			<main class="main">
+				<header class="topbar">
+					<div class="tabs">
+						<button
+							type="button"
+							title="Achados da revisão: triagem e decisões por finding"
+							class={`btn tab${tab === "findings" ? " active" : ""}`}
+							onClick={() => setTab("findings")}
+						>
+							Findings
+						</button>
+						<button
+							type="button"
+							title="Arquivos brutos gerados pela revisão (manifesto, classificação, relatório…)"
+							class={`btn tab${tab === "artifacts" ? " active" : ""}`}
+							onClick={() => setTab("artifacts")}
+						>
+							Artefatos
+						</button>
+					</div>
+					{slug && (
+						<button
+							type="button"
+							title="Reancorar: recalcula a linha de cada finding lendo o arquivo atual — use após um auto-fix que deslocou as linhas"
+							class="btn sync"
+							onClick={sync}
+						>
+							↻ Reancorar (sync)
+						</button>
+					)}
+				</header>
+
+				<p class="caption">{TAB_CAPTIONS[tab]}</p>
+				{error && <p class="error">{error}</p>}
+
+				{slug && tab === "findings" && data && (
+					<>
+						<SummaryBar summary={summary} />
+						<Filters value={filters} onChange={setFilters} />
+						<FindingsList
+							slug={slug}
+							findings={findings}
+							onUpdated={onUpdated}
+						/>
+					</>
+				)}
+				{slug && tab === "artifacts" && <ArtifactsPanel slug={slug} />}
+			</main>
+		</div>
+	);
+}

package/src/server/client/ArtifactsPanel.tsx

@@ -0,0 +1,48 @@
+/**
+ * Painel de artefatos: abas para ver o conteúdo bruto dos arquivos da run.
+ */
+
+import { useEffect, useState } from "preact/hooks";
+import { ARTIFACT_INFO, ARTIFACTS, type ArtifactName } from "./constants";
+
+export function ArtifactsPanel({ slug }: { slug: string }) {
+	const [name, setName] = useState<ArtifactName>(ARTIFACTS[0]);
+	const [content, setContent] = useState("");
+	const [error, setError] = useState("");
+
+	useEffect(() => {
+		setError("");
+		fetch(`/api/runs/${slug}/artifacts/${name}`)
+			.then(async (res) => {
+				if (!res.ok) throw new Error(`HTTP ${res.status}`);
+				setContent(await res.text());
+			})
+			.catch((err) => {
+				setContent("");
+				setError(String(err));
+			});
+	}, [slug, name]);
+
+	return (
+		<div class="artifacts">
+			<div class="tabs">
+				{ARTIFACTS.map((artifact) => (
+					<button
+						type="button"
+						title={ARTIFACT_INFO[artifact]}
+						class={`btn tab${artifact === name ? " active" : ""}`}
+						onClick={() => setName(artifact)}
+					>
+						{artifact}
+					</button>
+				))}
+			</div>
+			<p class="artifact-desc">{ARTIFACT_INFO[name]}</p>
+			{error ? (
+				<p class="error">{error}</p>
+			) : (
+				<pre class="artifact-view">{content}</pre>
+			)}
+		</div>
+	);
+}

package/src/server/client/Filters.tsx

@@ -0,0 +1,83 @@
+/**
+ * Barra de filtros dos findings: busca, decisão, severidade e "mostrar ausentes".
+ */
+
+import { DECISION_LABELS, DECISIONS, SEVERITY_ORDER } from "./constants";
+import type { Decision, Severity } from "./types";
+
+export type FiltersState = {
+	query: string;
+	decision: "all" | Decision;
+	severity: "all" | Severity;
+	showAbsent: boolean;
+};
+
+export function Filters({
+	value,
+	onChange,
+}: {
+	value: FiltersState;
+	onChange: (next: FiltersState) => void;
+}) {
+	const patch = (part: Partial<FiltersState>) => onChange({ ...value, ...part });
+
+	return (
+		<div class="filters">
+			<input
+				title="Filtrar por arquivo, regra ou mensagem"
+				placeholder="Buscar arquivo, regra ou mensagem…"
+				value={value.query}
+				onInput={(event) =>
+					patch({ query: (event.target as HTMLInputElement).value })
+				}
+			/>
+			<select
+				title="Filtrar por decisão de triagem"
+				value={value.decision}
+				onChange={(event) =>
+					patch({
+						decision: (event.target as HTMLSelectElement).value as
+							| "all"
+							| Decision,
+					})
+				}
+			>
+				<option value="all">Todas as decisões</option>
+				{DECISIONS.map((decision) => (
+					<option value={decision}>{DECISION_LABELS[decision]}</option>
+				))}
+			</select>
+			<select
+				title="Filtrar por severidade"
+				value={value.severity}
+				onChange={(event) =>
+					patch({
+						severity: (event.target as HTMLSelectElement).value as
+							| "all"
+							| Severity,
+					})
+				}
+			>
+				<option value="all">Todas as severidades</option>
+				{SEVERITY_ORDER.map((severity) => (
+					<option value={severity}>{severity}</option>
+				))}
+			</select>
+			<label
+				class="toggle"
+				title="Incluir findings que sumiram do último relatório"
+			>
+				<input
+					type="checkbox"
+					checked={value.showAbsent}
+					onChange={(event) =>
+						patch({
+							showAbsent: (event.target as HTMLInputElement).checked,
+						})
+					}
+				/>
+				mostrar ausentes
+			</label>
+		</div>
+	);
+}

package/src/server/client/FindingCard.tsx

@@ -0,0 +1,122 @@
+/**
+ * Cartão de um finding: dados + decisão (Executar/Ignorar), comentário e "feito".
+ */
+
+import { useCallback, useEffect, useState } from "preact/hooks";
+import { api } from "./api";
+import { DECISION_LABELS, DECISIONS, EXEC_LABELS, SEVERITY_EMOJI } from "./constants";
+import type { Finding } from "./types";
+
+export function FindingCard({
+	slug,
+	finding,
+	onUpdated,
+}: {
+	slug: string;
+	finding: Finding;
+	onUpdated: (finding: Finding) => void;
+}) {
+	const [comment, setComment] = useState(finding.comment ?? "");
+	const [busy, setBusy] = useState(false);
+
+	useEffect(() => {
+		setComment(finding.comment ?? "");
+	}, [finding.comment]);
+
+	const patch = useCallback(
+		async (body: Record<string, unknown>) => {
+			setBusy(true);
+			try {
+				const { finding: updated } = await api<{ finding: Finding }>(
+					`/api/runs/${slug}/findings/${finding.id}`,
+					{
+						method: "PATCH",
+						headers: { "content-type": "application/json" },
+						body: JSON.stringify(body),
+					},
+				);
+				onUpdated(updated);
+			} finally {
+				setBusy(false);
+			}
+		},
+		[finding.id, onUpdated, slug],
+	);
+
+	const location = finding.line ? `${finding.file}:${finding.line}` : finding.file;
+	const count = finding.count > 1 ? `×${finding.count}` : "";
+	const isDone = finding.execState === "done";
+
+	return (
+		<article
+			class={`card sev-${finding.severity}${finding.present ? "" : " absent"}`}
+		>
+			<header class="card-head">
+				<span class="sev">
+					{SEVERITY_EMOJI[finding.severity]} {finding.severity}
+				</span>
+				<code class="loc">{location}</code>
+				{count && <span class="count">{count}</span>}
+				<span class="spacer" />
+				<code class="id" title="id do finding">
+					{finding.id}
+				</code>
+			</header>
+			<h3 class="rule">{finding.rule}</h3>
+			<p class="msg">{finding.message}</p>
+			<p class="action">
+				<strong>Ação:</strong> {finding.action}
+			</p>
+			{finding.evidence && <pre class="evidence">{finding.evidence}</pre>}
+			<footer class="card-foot">
+				<span class="watchdogs">{finding.watchdogIds.join(", ") || "—"}</span>
+				<span class="exec-state">{EXEC_LABELS[finding.execState]}</span>
+			</footer>
+			<div class="decisions">
+				{DECISIONS.map((decision) => (
+					<button
+						type="button"
+						title={`Marcar como ${DECISION_LABELS[decision]}`}
+						class={`btn dec-${decision}${finding.decision === decision ? " active" : ""}`}
+						disabled={busy}
+						onClick={() =>
+							patch({ decision, comment: comment.trim() || undefined })
+						}
+					>
+						{DECISION_LABELS[decision]}
+					</button>
+				))}
+			</div>
+			<div class="comment-row">
+				<textarea
+					title="Comentário ou instrução adicional para o auto-fix"
+					placeholder="Comentário / instrução para o auto-fix (opcional)"
+					value={comment}
+					onInput={(event) =>
+						setComment((event.target as HTMLTextAreaElement).value)
+					}
+				/>
+				<div class="comment-actions">
+					<button
+						type="button"
+						title="Salvar o comentário neste finding"
+						class="btn"
+						disabled={busy}
+						onClick={() => patch({ comment: comment.trim() })}
+					>
+						Salvar comentário
+					</button>
+					<button
+						type="button"
+						title="Alternar o estado de execução deste finding (feito/pendente)"
+						class={`btn done${isDone ? " active" : ""}`}
+						disabled={busy}
+						onClick={() => patch({ execState: isDone ? "pending" : "done" })}
+					>
+						{isDone ? "✓ Feito" : "Marcar feito"}
+					</button>
+				</div>
+			</div>
+		</article>
+	);
+}

package/src/server/client/FindingsList.tsx

@@ -0,0 +1,54 @@
+/**
+ * Lista de findings agrupada por severidade (❌ > ⚠️ > 💡 > 🔎).
+ */
+
+import { useMemo } from "preact/hooks";
+import { SEVERITY_EMOJI, SEVERITY_ORDER } from "./constants";
+import { FindingCard } from "./FindingCard";
+import type { Finding, Severity } from "./types";
+
+export function FindingsList({
+	slug,
+	findings,
+	onUpdated,
+}: {
+	slug: string;
+	findings: Finding[];
+	onUpdated: (finding: Finding) => void;
+}) {
+	const grouped = useMemo(() => {
+		const bySeverity = new Map<Severity, Finding[]>();
+		for (const severity of SEVERITY_ORDER) bySeverity.set(severity, []);
+		for (const finding of findings) bySeverity.get(finding.severity)?.push(finding);
+		return bySeverity;
+	}, [findings]);
+
+	if (findings.length === 0) {
+		return <p class="empty">Nenhum finding para os filtros.</p>;
+	}
+
+	return (
+		<>
+			{SEVERITY_ORDER.map((severity) => {
+				const items = grouped.get(severity) ?? [];
+				if (items.length === 0) return null;
+				return (
+					<section class="sev-group">
+						<h2>
+							{SEVERITY_EMOJI[severity]} {severity}{" "}
+							<span class="n">({items.length})</span>
+						</h2>
+						{items.map((finding) => (
+							<FindingCard
+								key={finding.id}
+								slug={slug}
+								finding={finding}
+								onUpdated={onUpdated}
+							/>
+						))}
+					</section>
+				);
+			})}
+		</>
+	);
+}

package/src/server/client/RunList.tsx

@@ -0,0 +1,43 @@
+/**
+ * Sidebar: logo do houndsman + lista de runs (branch e nº de findings).
+ */
+
+import type { RunSummary } from "./types";
+
+export function RunList({
+	runs,
+	slug,
+	onSelect,
+}: {
+	runs: RunSummary[];
+	slug: string | null;
+	onSelect: (slug: string) => void;
+}) {
+	return (
+		<aside class="sidebar">
+			<div class="brand">
+				<img class="logo" src="/assets/logo.png" alt="houndsman" />
+				<div>
+					<h1>Houndsman</h1>
+					<p class="sub">Revisões e triagem</p>
+				</div>
+			</div>
+			<nav class="runs">
+				{runs.length === 0 && <p class="empty">Nenhuma run encontrada.</p>}
+				{runs.map((run) => (
+					<button
+						type="button"
+						title={`Abrir a run da branch ${run.branch}`}
+						class={`run${run.slug === slug ? " active" : ""}`}
+						onClick={() => onSelect(run.slug)}
+					>
+						<span class="run-branch">{run.branch}</span>
+						<span class="run-meta">
+							{run.summary.present}/{run.summary.total} presentes
+						</span>
+					</button>
+				))}
+			</nav>
+		</aside>
+	);
+}