@payconductor/houndsman 0.1.4 → 0.3.0

package/src/core/watchdog-registry.ts

@@ -1,18 +1,70 @@
 /**
- * Acesso tipado aos watchdogs de um `HoundsmanConfig` (biblioteca).
+ * Registry de watchdogs (biblioteca) — acesso tipado ao `HoundsmanConfig`.
  *
- * O motor não conhece ids concretos — tudo chega via `config`.
+ * O motor não conhece ids concretos: o registry resolve definições, contexto e
+ * casamento de arquivos por domínio. As funções antigas continuam como
+ * adaptadores para a API pública.
  */
 
 import type { HoundsmanConfig } from "./config";
+import { Watchdog, type WatchdogContext } from "./domain/watchdog";
 import type { WatchdogDefinition } from "./types";
 
+/** Coleção tipada de watchdogs do projeto. */
+export class WatchdogRegistry<TId extends string = string> {
+	private readonly config: HoundsmanConfig<TId>;
+
+	constructor(config: HoundsmanConfig<TId>) {
+		this.config = config;
+	}
+
+	/** Ids na ordem de declaração. */
+	get ids(): readonly TId[] {
+		return this.config.watchdogIds;
+	}
+
+	/** Definição de um watchdog (id string em runtime). */
+	get(watchdogId: string): WatchdogDefinition {
+		return this.config.watchdogs[watchdogId as TId];
+	}
+
+	/** Busca null-safe por id. */
+	find(watchdogId: string): Watchdog | null {
+		const definition = this.config.watchdogs[watchdogId as TId];
+		return definition ? new Watchdog(definition) : null;
+	}
+
+	/** Nome legível (default: o próprio id). */
+	nameOf(watchdogId: string): string {
+		return this.find(watchdogId)?.name ?? watchdogId;
+	}
+
+	/** Contexto essencial (sem regras). */
+	context(watchdogId: string): WatchdogContext {
+		return new Watchdog(this.get(watchdogId)).context();
+	}
+
+	/** Ids dos watchdogs que cobrem o arquivo. */
+	matching(filePath: string, content?: string): TId[] {
+		return this.config.watchdogIds.filter((id) =>
+			new Watchdog(this.config.watchdogs[id]).matches(filePath, content),
+		);
+	}
+
+	/** Todos os watchdogs (na ordem de declaração). */
+	all(): Watchdog[] {
+		return this.config.watchdogIds.map(
+			(id) => new Watchdog(this.config.watchdogs[id]),
+		);
+	}
+}
+
 /** Acesso tipado a um watchdog do projeto (id string em runtime). */
 export function getWatchdog<TId extends string>(
 	config: HoundsmanConfig<TId>,
 	watchdogId: string,
 ): WatchdogDefinition {
-	return config.watchdogs[watchdogId as TId];
+	return new WatchdogRegistry(config).get(watchdogId);
 }
 
 /** Busca null-safe por id string (runtime). */
@@ -20,23 +72,13 @@ export function findWatchdog<TId extends string>(
 	config: HoundsmanConfig<TId>,
 	watchdogId: string,
 ): WatchdogDefinition | null {
-	return config.watchdogs[watchdogId as TId] ?? null;
+	return new WatchdogRegistry(config).find(watchdogId)?.definition ?? null;
 }
 
 /** Contexto "essencial" do watchdog — SEM regras (docs/UI/inspeção). */
 export function getWatchdogContext<TId extends string>(
 	config: HoundsmanConfig<TId>,
 	watchdogId: string,
-) {
-	const { id, name, description, scope, reviewFocus, exclude, contextFiles } =
-		getWatchdog(config, watchdogId);
-	return {
-		id,
-		name,
-		description,
-		scope,
-		reviewFocus,
-		exclude,
-		contextFiles,
-	};
+): WatchdogContext {
+	return new WatchdogRegistry(config).context(watchdogId);
 }

package/src/index.ts

@@ -5,10 +5,12 @@
  * (`houndsman.config.ts`): watchdogs, tipos e helpers de autoria.
  */
 
+export { ArgParser } from "./core/arg-parser";
 export { assetPath, OUTPUT_FORMAT_FILE } from "./core/assets";
 export { defaultRenderBrief, PROCEDURE, renderBrief } from "./core/brief";
 export type { FindingsCommandResult } from "./core/commands/findings";
 export { runFindingsCommand, runVerifyCommand } from "./core/commands/findings";
+export { ProjectScaffolder } from "./core/commands/scaffold";
 export type {
 	HoundsmanBudgets,
 	HoundsmanConcurrency,
@@ -36,6 +38,14 @@ export {
 	parseDiffIndex,
 	parseNumstat,
 } from "./core/diff-source";
+export { DocDiscoverer } from "./core/doc-discoverer";
+export { Classification } from "./core/domain/classification";
+export { Diff } from "./core/domain/diff";
+export { Watchdog } from "./core/domain/watchdog";
+export { buildCarryover, mergeCarryover } from "./core/engine/carryover";
+export { HoundsmanEngine } from "./core/engine/houndsman-engine";
+export { ReviewScopeResolver } from "./core/engine/review-scope";
+export { ReviewSession } from "./core/engine/review-session";
 export {
 	churnOf,
 	classifyEntries,
@@ -81,6 +91,9 @@ export {
 	FINDING_DECISIONS,
 	FINDING_EXEC_STATES,
 	FINDINGS_STATE_VERSION,
+	Finding,
+	FindingsRepository,
+	FindingsState,
 	FindingsStateStore,
 	fileReader,
 	filterFindings,
@@ -91,6 +104,7 @@ export {
 	summarize,
 	syncState,
 } from "./core/findings-state";
+export type { GitResult, GitRunner } from "./core/git-runner";
 export {
 	ARTIFACT_DIR,
 	CORE_DIR,
@@ -100,9 +114,23 @@ export {
 	relFromRoot,
 	STATE_FILE,
 } from "./core/paths";
+export { ProjectConfig } from "./core/project-config";
 export { checkRegistry } from "./core/registry-check";
+export { BriefRenderer } from "./core/renderers/brief-renderer";
+export { ManifestWriter } from "./core/renderers/manifest-writer";
+export { ReportRenderer } from "./core/renderers/report-renderer";
 export type { DomainReport } from "./core/report-builder";
 export { renderDomainReport } from "./core/report-builder";
+export { RunLayout } from "./core/run-layout";
+export type { Clock } from "./core/services/clock";
+export { systemClock } from "./core/services/clock";
+export { FileClassifier } from "./core/services/file-classifier";
+export { FixBatchBuilder } from "./core/services/fix-batch-builder";
+export type { GhResult, GhRunner } from "./core/services/gh-client";
+export { GhClient } from "./core/services/gh-client";
+export { GitRepository } from "./core/services/git-repository";
+export { ProjectFiles } from "./core/services/project-files";
+export { Verifier } from "./core/services/verifier";
 export type {
 	ChurnMap,
 	ClassifyRule,
@@ -127,6 +155,8 @@ export {
 	findWatchdog,
 	getWatchdog,
 	getWatchdogContext,
+	WatchdogRegistry,
 } from "./core/watchdog-registry";
 export type { ServerOptions } from "./server";
-export { createRequestHandler, startServer } from "./server";
+export { createRequestHandler, HoundsmanServer, startServer } from "./server";
+export { RunRepository } from "./server/run-repository";

package/src/server/client/App.tsx

@@ -1,20 +1,37 @@
 /**
- * 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.
+ * App: layout do servidor — sidebar de execuções, header fixo (abas segmentadas,
+ * auto-refresh e reancoragem), KPIs, filtros e os painéis de findings/artefatos.
+ * Concentra o estado e as chamadas à API.
  */
 
-import { useCallback, useEffect, useMemo, useState } from "preact/hooks";
+import { useCallback, useEffect, useMemo, useRef, useState } from "preact/hooks";
 import { ArtifactsPanel } from "./ArtifactsPanel";
+import { AutoRefresh } from "./AutoRefresh";
 import { api, computeSummary } from "./api";
-import { TAB_CAPTIONS } from "./constants";
+import { AUTO_REFRESH_MS, TAB_CAPTIONS } from "./constants";
 import { Filters, type FiltersState } from "./Filters";
 import { FindingsList } from "./FindingsList";
+import { Layers, ListIcon, Refresh, Send } from "./icons";
 import { RunList } from "./RunList";
+import { SubmitModal } from "./SubmitModal";
 import { SummaryBar } from "./SummaryBar";
 import type { Finding, FindingsResponse, RunSummary } from "./types";
 
 type Tab = "findings" | "artifacts";
 
+const TABS: { id: Tab; label: string; hint: string }[] = [
+	{
+		id: "findings",
+		label: "Findings",
+		hint: "Achados da revisão: triagem e decisões por finding",
+	},
+	{
+		id: "artifacts",
+		label: "Artefatos",
+		hint: "Arquivos brutos gerados pela revisão (manifesto, classificação, relatório…)",
+	},
+];
+
 export function App() {
 	const [runs, setRuns] = useState<RunSummary[]>([]);
 	const [slug, setSlug] = useState<string | null>(null);
@@ -27,6 +44,23 @@ export function App() {
 		showAbsent: false,
 	});
 	const [error, setError] = useState("");
+	const [lastSync, setLastSync] = useState(() => Date.now());
+	const [refreshing, setRefreshing] = useState(false);
+	const [syncing, setSyncing] = useState(false);
+	const [submitOpen, setSubmitOpen] = useState(false);
+	/** Refs espelhando estado volátil — o polling não deve recriar o intervalo. */
+	const lastSyncRef = useRef(lastSync);
+	const slugRef = useRef<string | null>(null);
+	const refreshingRef = useRef(false);
+
+	useEffect(() => {
+		slugRef.current = slug;
+	}, [slug]);
+
+	const markSynced = useCallback(() => {
+		lastSyncRef.current = Date.now();
+		setLastSync(lastSyncRef.current);
+	}, []);
 
 	const reloadRuns = useCallback(async () => {
 		try {
@@ -47,6 +81,31 @@ export function App() {
 		}
 	}, []);
 
+	/** Revalidação leve (auto-refresh): runs + findings da run selecionada. */
+	const refresh = useCallback(async () => {
+		if (refreshingRef.current) return;
+		refreshingRef.current = true;
+		setRefreshing(true);
+		try {
+			const { runs: list } = await api<{ runs: RunSummary[] }>("/api/runs");
+			setRuns(list);
+			const target = slugRef.current ?? list[0]?.slug ?? null;
+			if (target) {
+				setSlug((current) => current ?? target);
+				setData(
+					await api<FindingsResponse>(`/api/runs/${target}/findings?all=1`),
+				);
+			}
+			setError("");
+		} catch (err) {
+			setError(String(err));
+		} finally {
+			refreshingRef.current = false;
+			setRefreshing(false);
+			markSynced();
+		}
+	}, [markSynced]);
+
 	useEffect(() => {
 		reloadRuns();
 	}, [reloadRuns]);
@@ -55,6 +114,16 @@ export function App() {
 		if (slug) loadFindings(slug);
 	}, [slug, loadFindings]);
 
+	// Auto-refresh: só o badge mostra o tempo decorrido; a lista só refaz o fetch
+	// quando o intervalo estourou (e a aba está visível).
+	useEffect(() => {
+		const id = setInterval(() => {
+			if (document.hidden || refreshingRef.current) return;
+			if (Date.now() - lastSyncRef.current >= AUTO_REFRESH_MS) void refresh();
+		}, 1000);
+		return () => clearInterval(id);
+	}, [refresh]);
+
 	const onUpdated = useCallback(
 		(updated: Finding) => {
 			setData((current) =>
@@ -74,10 +143,22 @@ export function App() {
 
 	const sync = useCallback(async () => {
 		if (!slug) return;
-		await api(`/api/runs/${slug}/sync`, { method: "POST" });
-		await loadFindings(slug);
-		await reloadRuns();
-	}, [slug, loadFindings, reloadRuns]);
+		setSyncing(true);
+		try {
+			await api(`/api/runs/${slug}/sync`, { method: "POST" });
+			await loadFindings(slug);
+			await reloadRuns();
+			markSynced();
+		} finally {
+			setSyncing(false);
+		}
+	}, [slug, loadFindings, reloadRuns, markSynced]);
+
+	/** Após enviar a revisão: a triagem ganhou o vínculo remoto — recarrega. */
+	const afterSubmit = useCallback(() => {
+		if (slugRef.current) void loadFindings(slugRef.current);
+		void reloadRuns();
+	}, [loadFindings, reloadRuns]);
 
 	const findings = useMemo(() => {
 		const needle = filters.query.trim().toLowerCase();
@@ -102,56 +183,100 @@ export function App() {
 
 	const summary = useMemo(() => computeSummary(data?.findings ?? []), [data]);
 
+	const branch =
+		data?.branch ?? runs.find((run) => run.slug === slug)?.branch ?? slug ?? "";
+
 	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 class="segmented">
+						{TABS.map((item) => (
+							<button
+								type="button"
+								key={item.id}
+								title={item.hint}
+								class={`seg-btn${tab === item.id ? " active" : ""}`}
+								onClick={() => setTab(item.id)}
+							>
+								{item.id === "findings" ? (
+									<ListIcon size={15} />
+								) : (
+									<Layers size={15} />
+								)}
+								{item.label}
+							</button>
+						))}
+					</div>
+					<div class="topbar-right">
+						<AutoRefresh
+							lastSync={lastSync}
+							refreshing={refreshing || syncing}
+						/>
+						{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"
+								disabled={syncing}
+								onClick={sync}
+							>
+								<Refresh
+									size={15}
+									class={`icon${syncing ? " spin" : ""}`}
+								/>
+								{syncing ? "Reancorando…" : "Reancorar"}
+							</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}
-						/>
-					</>
+				<div class="content">
+					<div class="page-header">
+						<div class="page-header-text">
+							{slug && <h1 class="page-title">{branch}</h1>}
+							<p class="page-sub">{TAB_CAPTIONS[tab]}</p>
+						</div>
+						{slug && tab === "findings" && data && (
+							<div class="page-header-actions">
+								<button
+									type="button"
+									class="btn submit-review"
+									title="Publicar os findings selecionados como comentários na PR (via gh)"
+									onClick={() => setSubmitOpen(true)}
+								>
+									<Send size={15} />
+									Enviar revisão
+								</button>
+							</div>
+						)}
+					</div>
+					{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} />}
+					{!slug && !error && <p class="empty">Nenhuma execução para triar.</p>}
+				</div>
+				{slug && (
+					<SubmitModal
+						slug={slug}
+						branch={branch}
+						open={submitOpen}
+						onClose={() => setSubmitOpen(false)}
+						onSubmitted={afterSubmit}
+					/>
 				)}
-				{slug && tab === "artifacts" && <ArtifactsPanel slug={slug} />}
 			</main>
 		</div>
 	);

package/src/server/client/ArtifactsPanel.tsx

@@ -25,12 +25,12 @@ export function ArtifactsPanel({ slug }: { slug: string }) {
 
 	return (
 		<div class="artifacts">
-			<div class="tabs">
+			<div class="artifact-tabs">
 				{ARTIFACTS.map((artifact) => (
 					<button
 						type="button"
 						title={ARTIFACT_INFO[artifact]}
-						class={`btn tab${artifact === name ? " active" : ""}`}
+						class={`chip${artifact === name ? " active" : ""}`}
 						onClick={() => setName(artifact)}
 					>
 						{artifact}

package/src/server/client/AutoRefresh.tsx

@@ -0,0 +1,38 @@
+/**
+ * Indicador de auto-refresh: ponto de pulso (verde estável / âmbar pulsando
+ * durante a atualização) + tempo decorrido desde a última sincronização.
+ *
+ * O tique de 1s vive aqui — a lista de findings não re-renderiza por causa dele.
+ */
+
+import { useEffect, useState } from "preact/hooks";
+import { formatElapsed } from "./format";
+
+export function AutoRefresh({
+	lastSync,
+	refreshing,
+}: {
+	lastSync: number;
+	refreshing: boolean;
+}) {
+	const [now, setNow] = useState(() => Date.now());
+
+	useEffect(() => {
+		const id = setInterval(() => setNow(Date.now()), 1000);
+		return () => clearInterval(id);
+	}, []);
+
+	const seconds = Math.max(0, Math.floor((now - lastSync) / 1000));
+
+	return (
+		<span
+			class="auto-refresh"
+			title="A lista é revalidada automaticamente enquanto esta página estiver aberta"
+		>
+			<span class={`dot${refreshing ? " busy" : ""}`} />
+			{refreshing
+				? "Auto-refresh · atualizando…"
+				: `Auto-refresh · ${formatElapsed(seconds)}`}
+		</span>
+	);
+}

package/src/server/client/Filters.tsx

@@ -1,8 +1,10 @@
 /**
- * Barra de filtros dos findings: busca, decisão, severidade e "mostrar ausentes".
+ * Barra de filtros dos findings: busca, chips de severidade, chips de decisão e
+ * o toggle "ausentes".
  */
 
-import { DECISION_LABELS, DECISIONS, SEVERITY_ORDER } from "./constants";
+import { DECISION_LABELS, DECISIONS, SEVERITY_LABELS, SEVERITY_ORDER } from "./constants";
+import { Search, Watch } from "./icons";
 import type { Decision, Severity } from "./types";
 
 export type FiltersState = {
@@ -23,61 +25,78 @@ export function Filters({
 
 	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"
-			>
+			<label class="search" title="Filtrar por arquivo, regra ou mensagem">
+				<Search size={15} />
 				<input
-					type="checkbox"
-					checked={value.showAbsent}
-					onChange={(event) =>
-						patch({
-							showAbsent: (event.target as HTMLInputElement).checked,
-						})
+					type="text"
+					placeholder="Buscar arquivo, regra ou mensagem…"
+					value={value.query}
+					onInput={(event) =>
+						patch({ query: (event.target as HTMLInputElement).value })
 					}
 				/>
-				mostrar ausentes
+				{value.query && (
+					<button
+						type="button"
+						class="search-clear"
+						title="Limpar busca"
+						onClick={() => patch({ query: "" })}
+					>
+						×
+					</button>
+				)}
 			</label>
+
+			<div class="chips">
+				<button
+					type="button"
+					title="Todas as severidades"
+					class={`chip${value.severity === "all" ? " active" : ""}`}
+					onClick={() => patch({ severity: "all" })}
+				>
+					Todas
+				</button>
+				{SEVERITY_ORDER.map((severity) => (
+					<button
+						type="button"
+						title={`Somente severidade ${severity}`}
+						class={`chip sev-${severity}${value.severity === severity ? " active" : ""}`}
+						onClick={() => patch({ severity })}
+					>
+						{SEVERITY_LABELS[severity]}
+					</button>
+				))}
+			</div>
+
+			<div class="chips">
+				<button
+					type="button"
+					title="Todas as decisões"
+					class={`chip${value.decision === "all" ? " active" : ""}`}
+					onClick={() => patch({ decision: "all" })}
+				>
+					Todas
+				</button>
+				{DECISIONS.map((decision) => (
+					<button
+						type="button"
+						title={`Somente ${DECISION_LABELS[decision]}`}
+						class={`chip dec-${decision}${value.decision === decision ? " active" : ""}`}
+						onClick={() => patch({ decision })}
+					>
+						{DECISION_LABELS[decision]}
+					</button>
+				))}
+			</div>
+
+			<button
+				type="button"
+				title="Incluir findings que sumiram do último relatório"
+				class={`chip${value.showAbsent ? " active" : ""}`}
+				onClick={() => patch({ showAbsent: !value.showAbsent })}
+			>
+				<Watch size={13} /> Ausentes
+			</button>
 		</div>
 	);
 }