@payconductor/houndsman 0.1.0 → 0.1.3

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,52 @@
+/**
+ * Sidebar: logo do houndsman + lista de runs (branch e nº de findings).
+ */
+
+import { describeRunStatus } from "./constants";
+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) => {
+					const status = describeRunStatus(run);
+					return (
+						<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>
+							{status && (
+								<span class={`run-status status-${status.kind}`}>
+									{status.label}
+								</span>
+							)}
+						</button>
+					);
+				})}
+			</nav>
+		</aside>
+	);
+}

package/src/server/client/SummaryBar.tsx

@@ -0,0 +1,21 @@
+/**
+ * Barra de resumo da triagem (total, presentes e contagens por decisão/execução).
+ */
+
+import { DECISION_LABELS, DECISIONS } from "./constants";
+import type { Summary } from "./types";
+
+export function SummaryBar({ summary }: { summary: Summary }) {
+	return (
+		<div class="summary-bar">
+			<span>Total: {summary.total}</span>
+			<span>Presentes: {summary.present}</span>
+			{DECISIONS.filter((decision) => decision !== "pending").map((decision) => (
+				<span key={decision}>
+					{DECISION_LABELS[decision]}: {summary.byDecision[decision] ?? 0}
+				</span>
+			))}
+			<span>Feitos: {summary.byExecState.done ?? 0}</span>
+		</div>
+	);
+}

package/src/server/client/api.ts

@@ -0,0 +1,37 @@
+/**
+ * Helpers de acesso à API local do servidor.
+ */
+
+import { DECISIONS, EXEC_STATES, SEVERITY_ORDER } from "./constants";
+import type { Decision, ExecState, Finding, Severity, Summary } from "./types";
+
+/** `fetch` JSON: lança com o corpo do erro quando a resposta não é 2xx. */
+export async function api<T>(path: string, init?: RequestInit): Promise<T> {
+	const res = await fetch(path, init);
+	if (!res.ok) throw new Error((await res.text()) || `HTTP ${res.status}`);
+	return (await res.json()) as T;
+}
+
+/** Recalcula o resumo a partir dos findings atuais (contadores vivos na UI). */
+export function computeSummary(findings: Finding[]): Summary {
+	const byDecision = Object.fromEntries(DECISIONS.map((d) => [d, 0])) as Record<
+		Decision,
+		number
+	>;
+	const byExecState = Object.fromEntries(EXEC_STATES.map((e) => [e, 0])) as Record<
+		ExecState,
+		number
+	>;
+	const bySeverity = Object.fromEntries(SEVERITY_ORDER.map((s) => [s, 0])) as Record<
+		Severity,
+		number
+	>;
+	let present = 0;
+	for (const finding of findings) {
+		if (finding.present) present++;
+		byDecision[finding.decision]++;
+		byExecState[finding.execState]++;
+		bySeverity[finding.severity]++;
+	}
+	return { total: findings.length, present, byDecision, byExecState, bySeverity };
+}

package/src/server/client/constants.ts

@@ -0,0 +1,94 @@
+/**
+ * Constantes de apresentação do cliente (labels, ordem, emojis).
+ */
+
+import type { Decision, ExecState, RunStatus, RunSummary, Severity } from "./types";
+
+export const SEVERITY_EMOJI: Record<Severity, string> = {
+	blocking: "❌",
+	attention: "⚠️",
+	suggestion: "💡",
+	nit: "🔎",
+};
+
+export const SEVERITY_ORDER: Severity[] = ["blocking", "attention", "suggestion", "nit"];
+
+export const DECISIONS: Decision[] = ["pending", "execute", "ignore"];
+
+export const DECISION_LABELS: Record<Decision, string> = {
+	pending: "Pendente",
+	execute: "Executar",
+	ignore: "Ignorar",
+};
+
+export const EXEC_STATES: ExecState[] = ["pending", "in_progress", "done", "stale"];
+
+export const EXEC_LABELS: Record<ExecState, string> = {
+	pending: "exec: pendente",
+	in_progress: "exec: em andamento",
+	done: "exec: feito",
+	stale: "exec: stale",
+};
+
+export const RUN_STATUS_LABELS: Record<RunStatus, string> = {
+	reviewing: "Revisando",
+	review_done: "Revisão pronta",
+	fixing: "Corrigindo",
+	fix_done: "Correção pronta",
+};
+
+/** Limiar de inatividade para exibir timeout (display-only; não é status). */
+export const STATUS_TIMEOUT_MS = 10 * 60 * 1000;
+
+export type RunStatusView = { kind: string; label: string; timeout: boolean };
+
+/** View do status de uma run — label; vira timeout quando ativo e sem ping recente. */
+export function describeRunStatus(
+	run: RunSummary,
+	now: number = Date.now(),
+): RunStatusView | null {
+	const status = run.status;
+	if (!status) return null;
+	const active = status === "reviewing" || status === "fixing";
+	const updated = run.updatedAt ? Date.parse(run.updatedAt) : Number.NaN;
+	if (active && Number.isFinite(updated) && now - updated > STATUS_TIMEOUT_MS) {
+		return {
+			kind: "timeout",
+			label: status === "reviewing" ? "Timeout na revisão" : "Timeout na correção",
+			timeout: true,
+		};
+	}
+	return { kind: status, label: RUN_STATUS_LABELS[status], timeout: false };
+}
+
+/** Artefatos que podem ser lidos na aba "Artefatos". */
+export const ARTIFACTS = [
+	"manifest.json",
+	"classification.json",
+	"candidates.json",
+	"context-summary.json",
+	"review.md",
+] as const;
+
+export type ArtifactName = (typeof ARTIFACTS)[number];
+
+/** Descrição de cada artefato (mostrada ao selecioná-lo na aba). */
+export const ARTIFACT_INFO: Record<ArtifactName, string> = {
+	"manifest.json":
+		"Resumo da execução: watchdogs ativos, arquivos, orçamento, churn, Jev e contexto da PR.",
+	"classification.json":
+		"Classificação do diff: watchdogs ativados por arquivo, status (A/M/D/R) e churn por arquivo.",
+	"candidates.json":
+		"Indícios da pré-análise Jev (regra + arquivo + confiança) — não são achados.",
+	"context-summary.json":
+		"Resumo da PR (objetivo, motivação e alterações) gerado no Passo 0.",
+	"review.md": "Relatório consolidado da revisão — o entregável.",
+};
+
+/** Legenda única de cada aba (explica o que a aba é; mostrada quando selecionada). */
+export const TAB_CAPTIONS = {
+	findings:
+		"Triagem dos achados da revisão: decida Executar, Ignorar ou deixe Pendente — o comentário orienta o auto-fix. Agente: houndsman findings list --decision pending --json · findings done <id>.",
+	artifacts:
+		"Artefatos brutos da run: manifesto, classificação, candidatos Jev, contexto da PR e o relatório consolidado (review.md).",
+} as const;

package/src/server/client/index.tsx

@@ -0,0 +1,12 @@
+/**
+ * Entry do cliente (Preact): monta o `<App />` no `#app`.
+ *
+ * Bundle gerado em memória por `Bun.build` (`client-build.ts`). Os componentes
+ * vivem em arquivos irmãos nesta pasta (`App.tsx`, `RunList.tsx`, ...).
+ */
+
+import { render } from "preact";
+import { App } from "./App";
+
+const root = document.getElementById("app");
+if (root) render(<App />, root);