@payconductor/houndsman 0.5.0 → 0.7.0

package/src/server/pr-comments.ts

@@ -0,0 +1,256 @@
+/**
+ * Comentários de uma Pull Request (servidor) — threads de revisão + comentários
+ * gerais, lidos via `gh api`.
+ *
+ * A aba é lazy: só chama o GitHub quando o cliente pede. O resultado fica em
+ * cache por branch (TTL de 60s); `refresh` ignora o cache. Tudo fail-open: sem
+ * PR/gh/login, devolve `available:false` e a UI mostra o motivo.
+ */
+
+import { resolve } from "node:path";
+import { resolvePrTarget } from "../core/github-review";
+import { systemClock } from "../core/services/clock";
+import { describeGhError, type GhRunner } from "../core/services/gh-client";
+
+/** Cache do payload já processado (por raiz do repositório + branch). */
+const CACHE_TTL_MS = 60_000;
+const cache = new Map<string, { expiresAt: number; value: PrCommentsResponse }>();
+
+/** Limpa o cache (testes e shutdown). */
+export function clearPrCommentsCache(): void {
+	cache.clear();
+}
+
+/** Comentário já normalizado para a UI. */
+export type PrCommentView = {
+	id: number;
+	author: string;
+	authorType: string;
+	body: string;
+	createdAt?: string;
+	url?: string;
+	path?: string;
+	line: number | null;
+	absFile?: string;
+	replyTo?: number | null;
+};
+
+/** Thread de revisão (comentário raiz + respostas). */
+export type PrCommentThread = {
+	id: number;
+	path: string;
+	line: number | null;
+	absFile: string;
+	comments: PrCommentView[];
+};
+
+/** Resposta de `GET /api/runs/:slug/comments`. */
+export type PrCommentsResponse = {
+	available: boolean;
+	reason?: string;
+	target?: { number: number; repo: string; url?: string };
+	fetchedAt: string;
+	threads: PrCommentThread[];
+	issueComments: PrCommentView[];
+	counts: { threads: number; inline: number; issue: number };
+};
+
+type GhInlineComment = {
+	id?: number;
+	body?: string;
+	path?: string;
+	line?: number | null;
+	original_line?: number | null;
+	created_at?: string;
+	html_url?: string;
+	in_reply_to_id?: number | null;
+	user?: { login?: string; type?: string };
+};
+
+type GhIssueComment = {
+	id?: number;
+	body?: string;
+	created_at?: string;
+	html_url?: string;
+	user?: { login?: string; type?: string };
+};
+
+type ApiList = { ok: true; items: unknown[] } | { ok: false; reason: string };
+
+function unavailable(
+	reason: string,
+	target?: PrCommentsResponse["target"],
+): PrCommentsResponse {
+	return {
+		available: false,
+		reason,
+		target,
+		fetchedAt: systemClock(),
+		threads: [],
+		issueComments: [],
+		counts: { threads: 0, inline: 0, issue: 0 },
+	};
+}
+
+/** Lista paginada via `gh api`; `--slurp` junta as páginas num único array. */
+function ghApiList(runner: GhRunner, path: string): ApiList {
+	let result = runner(["api", "--paginate", "--slurp", path]);
+	if (!result.ok && /unknown flag|unknown shorthand|slurp/i.test(result.stderr)) {
+		result = runner(["api", path]);
+	}
+	if (!result.ok) return { ok: false, reason: describeGhError(result) };
+	try {
+		const parsed = JSON.parse(result.stdout);
+		if (Array.isArray(parsed)) {
+			// Dependendo da versão do gh, `--slurp` pode devolver `[[...], [...]]`
+			// (um array por página) ou um array já achatado.
+			const items: unknown[] = [];
+			for (const item of parsed) {
+				if (Array.isArray(item)) items.push(...item);
+				else items.push(item);
+			}
+			return { ok: true, items };
+		}
+		return { ok: false, reason: "Resposta inesperada do gh (esperava uma lista)." };
+	} catch {
+		return { ok: false, reason: "Resposta inválida do gh (JSON malformado)." };
+	}
+}
+
+function toView(
+	raw: GhInlineComment | GhIssueComment,
+	repoRoot: string,
+): PrCommentView | null {
+	const id = Number(raw.id);
+	const body = raw.body?.trim() ?? "";
+	if (!Number.isFinite(id) || body.length === 0) return null;
+	const path = "path" in raw ? raw.path : undefined;
+	const line = "line" in raw ? (raw.line ?? raw.original_line ?? null) : null;
+	return {
+		id,
+		author: raw.user?.login ?? "desconhecido",
+		authorType: raw.user?.type ?? "User",
+		body,
+		createdAt: raw.created_at,
+		url: raw.html_url,
+		path,
+		line,
+		absFile: path ? resolve(repoRoot, path) : undefined,
+		replyTo: "in_reply_to_id" in raw ? (raw.in_reply_to_id ?? null) : null,
+	};
+}
+
+/** Agrupa comentários inline em threads (raiz + respostas). */
+function buildThreads(
+	items: unknown[],
+	repoRoot: string,
+): {
+	threads: PrCommentThread[];
+	inline: number;
+} {
+	const raws = (items as GhInlineComment[])
+		.filter((raw) => raw && typeof raw === "object")
+		.sort(
+			(a, b) =>
+				(a.created_at ?? "").localeCompare(b.created_at ?? "") ||
+				Number(a.id ?? 0) - Number(b.id ?? 0),
+		);
+
+	const views: PrCommentView[] = [];
+	const parent = new Map<number, number | null>();
+	for (const raw of raws) {
+		const view = toView(raw, repoRoot);
+		if (!view) continue;
+		views.push(view);
+		parent.set(view.id, raw.in_reply_to_id ?? null);
+	}
+
+	const rootOf = (id: number): number => {
+		let current = id;
+		const seen = new Set<number>();
+		for (;;) {
+			const next = parent.get(current);
+			if (!next || seen.has(current)) return current;
+			seen.add(current);
+			current = next;
+		}
+	};
+
+	const byRoot = new Map<number, PrCommentThread>();
+	for (const view of views) {
+		const rootId = rootOf(view.id);
+		const existing = byRoot.get(rootId);
+		if (existing) {
+			existing.comments.push(view);
+			continue;
+		}
+		const path = view.path ?? "";
+		byRoot.set(rootId, {
+			id: rootId,
+			path,
+			line: view.line,
+			absFile: view.absFile ?? (path ? resolve(repoRoot, path) : ""),
+			comments: [view],
+		});
+	}
+
+	const threads = [...byRoot.values()].sort(
+		(a, b) =>
+			a.path.localeCompare(b.path) ||
+			(a.line ?? Number.MAX_SAFE_INTEGER) - (b.line ?? Number.MAX_SAFE_INTEGER) ||
+			a.id - b.id,
+	);
+	return { threads, inline: views.length };
+}
+
+/** Lê e agrupa os comentários da PR da branch (com cache de 60s). */
+export function fetchPrComments(options: {
+	runner: GhRunner;
+	branch: string;
+	repoRoot: string;
+	refresh?: boolean;
+	now?: number;
+}): PrCommentsResponse {
+	const { runner, branch, repoRoot, refresh = false } = options;
+	const now = options.now ?? Date.now();
+	const key = `${resolve(repoRoot)}\0${branch}`;
+	const cached = cache.get(key);
+	if (!refresh && cached && cached.expiresAt > now) return cached.value;
+
+	const target = resolvePrTarget(runner, branch);
+	if (!target.ok) return unavailable(target.reason);
+
+	const pr = {
+		number: target.target.number,
+		repo: target.target.repo,
+		url: target.target.url,
+	};
+	const inline = ghApiList(runner, `repos/${pr.repo}/pulls/${pr.number}/comments`);
+	if (!inline.ok) return unavailable(inline.reason, pr);
+
+	const issue = ghApiList(runner, `repos/${pr.repo}/issues/${pr.number}/comments`);
+	if (!issue.ok) return unavailable(issue.reason, pr);
+
+	const { threads, inline: inlineCount } = buildThreads(inline.items, repoRoot);
+	const issueComments = (issue.items as GhIssueComment[])
+		.map((raw) => toView(raw, repoRoot))
+		.filter((view): view is PrCommentView => view !== null)
+		.sort(
+			(a, b) => (a.createdAt ?? "").localeCompare(b.createdAt ?? "") || a.id - b.id,
+		);
+
+	const value: PrCommentsResponse = {
+		available: true,
+		target: pr,
+		fetchedAt: systemClock(),
+		threads,
+		issueComments,
+		counts: {
+			threads: threads.length,
+			inline: inlineCount,
+			issue: issueComments.length,
+		},
+	};
+	cache.set(key, { expiresAt: now + CACHE_TTL_MS, value });
+	return value;
+}

package/src/server/pr-inbox.ts

@@ -0,0 +1,202 @@
+/**
+ * Caixa de entrada de Pull Requests do repositório atual (servidor).
+ *
+ * Lista as PRs abertas via `gh` e executa o checkout somente quando a árvore
+ * de trabalho está limpa. Fail-open: sem `gh` (ou sem git), devolve o motivo e
+ * a UI degrada sem quebrar as demais abas.
+ */
+
+import { describeGhError, type GhRunner } from "../core/services/gh-client";
+import type { GitRepository } from "../core/services/git-repository";
+
+/** Estado da árvore de trabalho (base do bloqueio do checkout). */
+export type WorktreeState = {
+	/** `false` quando o `git status` falhou. */
+	available: boolean;
+	clean: boolean;
+	changes: number;
+	/** Amostra dos caminhos alterados (limitada para a UI). */
+	sample: string[];
+};
+
+/** PR aberta exibida na sidebar. */
+export type PrListItem = {
+	number: number;
+	title: string;
+	headRefName: string;
+	baseRefName: string;
+	author: string;
+	updatedAt?: string;
+	isDraft: boolean;
+	reviewDecision?: string;
+	url?: string;
+	/** Run local correspondente à branch, quando existir. */
+	runSlug?: string;
+};
+
+/** Resposta de `GET /api/prs`. */
+export type PrListResponse = {
+	available: boolean;
+	reason?: string;
+	currentBranch: string | null;
+	worktree: WorktreeState;
+	prs: PrListItem[];
+};
+
+/** Resultado do checkout de uma PR. */
+export type CheckoutResponse =
+	| { ok: true; number: number; branch: string | null }
+	| {
+			ok: false;
+			reason: "dirty" | "git" | "gh";
+			detail: string;
+			changes?: string[];
+	  };
+
+const PR_LIST_FIELDS =
+	"number,title,headRefName,baseRefName,author,updatedAt,isDraft,reviewDecision,url";
+
+type GhPrListItem = {
+	number?: number;
+	title?: string;
+	headRefName?: string;
+	baseRefName?: string;
+	author?: { login?: string; name?: string };
+	updatedAt?: string;
+	isDraft?: boolean;
+	reviewDecision?: string;
+	url?: string;
+};
+
+function toItem(
+	raw: GhPrListItem,
+	runSlugs: ReadonlyMap<string, string>,
+): PrListItem | null {
+	const number = Number(raw.number);
+	const headRefName = raw.headRefName?.trim();
+	if (!Number.isFinite(number) || number <= 0 || !headRefName) return null;
+	return {
+		number,
+		title: raw.title?.trim() || `PR #${number}`,
+		headRefName,
+		baseRefName: raw.baseRefName?.trim() || "",
+		author: raw.author?.login ?? raw.author?.name ?? "desconhecido",
+		updatedAt: raw.updatedAt,
+		isDraft: Boolean(raw.isDraft),
+		reviewDecision: raw.reviewDecision?.trim() || undefined,
+		url: raw.url,
+		runSlug: runSlugs.get(headRefName),
+	};
+}
+
+/** Acesso às PRs do repositório atual. */
+export class PrInbox {
+	constructor(
+		private readonly ghRunner: GhRunner,
+		private readonly git: GitRepository,
+	) {}
+
+	/** Estado da árvore de trabalho (`git status --porcelain`). */
+	worktree(): WorktreeState {
+		const result = this.git.tryRun(["status", "--porcelain"]);
+		if (!result.ok) {
+			return { available: false, clean: false, changes: 0, sample: [] };
+		}
+		const lines = result.stdout
+			.split("\n")
+			.map((line) => line.trimEnd())
+			.filter((line) => line.length > 0);
+		return {
+			available: true,
+			clean: lines.length === 0,
+			changes: lines.length,
+			sample: lines.slice(0, 20),
+		};
+	}
+
+	/** Lista as PRs abertas (limite 50) e o estado local do repositório. */
+	list(runSlugs: ReadonlyMap<string, string> = new Map()): PrListResponse {
+		const currentBranch = this.git.currentBranch();
+		const worktree = this.worktree();
+		const result = this.ghRunner([
+			"pr",
+			"list",
+			"--state",
+			"open",
+			"--limit",
+			"50",
+			"--json",
+			PR_LIST_FIELDS,
+		]);
+
+		if (!result.ok) {
+			return {
+				available: false,
+				reason: describeGhError(result),
+				currentBranch,
+				worktree,
+				prs: [],
+			};
+		}
+
+		let parsed: unknown;
+		try {
+			parsed = JSON.parse(result.stdout);
+		} catch {
+			return {
+				available: false,
+				reason: "Resposta inválida do gh (JSON malformado).",
+				currentBranch,
+				worktree,
+				prs: [],
+			};
+		}
+		if (!Array.isArray(parsed)) {
+			return {
+				available: false,
+				reason: "Resposta inesperada do gh (esperava uma lista de PRs).",
+				currentBranch,
+				worktree,
+				prs: [],
+			};
+		}
+
+		const prs = (parsed as GhPrListItem[])
+			.map((item) => toItem(item, runSlugs))
+			.filter((item): item is PrListItem => item !== null)
+			.sort((a, b) => (b.updatedAt ?? "").localeCompare(a.updatedAt ?? ""));
+
+		return { available: true, currentBranch, worktree, prs };
+	}
+
+	/**
+	 * Faz checkout da PR via `gh pr checkout`.
+	 *
+	 * A árvore precisa estar limpa: alterações locais não commitadas bloqueiam a
+	 * operação para não descartar trabalho do usuário.
+	 */
+	checkout(number: number): CheckoutResponse {
+		const worktree = this.worktree();
+		if (!worktree.available) {
+			return {
+				ok: false,
+				reason: "git",
+				detail: "Não foi possível ler o estado do git.",
+			};
+		}
+		if (!worktree.clean) {
+			return {
+				ok: false,
+				reason: "dirty",
+				detail: `${worktree.changes} alteração(ões) não commitada(s).`,
+				changes: worktree.sample,
+			};
+		}
+
+		const result = this.ghRunner(["pr", "checkout", String(number)]);
+		if (!result.ok) {
+			return { ok: false, reason: "gh", detail: describeGhError(result) };
+		}
+		return { ok: true, number, branch: this.git.currentBranch() };
+	}
+}

package/src/server/run-repository.ts

@@ -34,9 +34,11 @@ import {
 } from "../core/github-review";
 import { pingFindingsStatus } from "../core/run-status";
 import { systemClock } from "../core/services/clock";
+import { defaultGhRunner } from "../core/services/gh-client";
 import type { RepoIdentity, ReviewRecord, StorageProvider } from "../core/storage/types";
 import type { Severity } from "../core/types";
 import { isSlug } from "./artifacts";
+import { fetchPrComments, type PrCommentsResponse } from "./pr-comments";
 
 /** Item da lista de execuções (sidebar) — já ordenado do mais recente ao antigo. */
 export type RunListItem = {
@@ -78,10 +80,16 @@ export type ArtifactListItem = {
 export class RunRepository {
 	private readonly storage: StorageProvider;
 	private readonly repo: RepoIdentity;
+	private readonly ghRunner: GhRunner;
 
-	constructor(storage: StorageProvider, repo: RepoIdentity) {
+	constructor(
+		storage: StorageProvider,
+		repo: RepoIdentity,
+		ghRunner: GhRunner = defaultGhRunner,
+	) {
 		this.storage = storage;
 		this.repo = repo;
+		this.ghRunner = ghRunner;
 	}
 
 	/** `true` se o slug aponta para uma run do repositório atual. */
@@ -105,6 +113,15 @@ export class RunRepository {
 		});
 	}
 
+	/** Mapa branch → slug das runs (usado para casar PRs com execuções). */
+	branchIndex(): Map<string, string> {
+		return new Map(
+			this.storage
+				.listReviews(this.repo.key)
+				.map((review) => [review.branch, review.slug]),
+		);
+	}
+
 	/** Detalhe da run (null se o slug for inválido). */
 	detail(slug: string): RunDetail | null {
 		const review = this.findBySlug(slug);
@@ -273,6 +290,21 @@ export class RunRepository {
 		return { available: true, target: target.target, outcome };
 	}
 
+	/** Comentários da PR da run (null se o slug for inválido). */
+	comments(
+		slug: string,
+		options: { refresh?: boolean } = {},
+	): PrCommentsResponse | null {
+		const review = this.findBySlug(slug);
+		if (!review) return null;
+		return fetchPrComments({
+			runner: this.ghRunner,
+			branch: review.branch,
+			repoRoot: review.repoRoot,
+			refresh: options.refresh,
+		});
+	}
+
 	/** Lista os artefatos da run (sem conteúdo). */
 	artifacts(slug: string): ArtifactListItem[] | null {
 		const review = this.findBySlug(slug);

package/src/skill/OUTPUT-FORMAT.md

@@ -70,3 +70,15 @@ staging global da review:
 - Um achado por regra violada; não agrupar regras diferentes.
 - `file:line` sempre que possível; `evidence` quando o achado não é óbvio.
 - Não inventar achados — se não houver violação, o array fica vazio.
+
+## Findings emergentes (opt-in)
+
+Quando o watchdog declara `allowEmergentFindings: true`, você pode reportar falhas de
+**lógica** ou **domínio** que não correspondem a uma regra explícita usando os prefixos
+reservados:
+
+- `Lógica: <descrição>` — nome/contrato vs comportamento, fluxos, estados, bordas.
+- `Domínio: <descrição>` — transições, idempotência, invariantes, arredondamento, timezone.
+
+Esses findings continuam exigindo `evidence` e têm severidade máxima `attention`. Sem o
+opt-in, todo finding precisa citar uma regra existente.

package/src/skill/SETUP.md

@@ -7,8 +7,11 @@ no seu projeto é **autocontida** — não exige nenhuma dependência local do p
 
 - **Bun** — o CLI e o motor usam a runtime Bun (execução de TS, `Bun.spawnSync`).
 - **git** — o diff usa `git diff <base>...<head> --name-status`.
-- Opcional: **`gh`** (contexto da PR) e **`TYPESAFE_API_KEY`** (pré-análise Jev). O pipeline
-  segue normalmente sem eles.
+- **gh** (Opcional) — Obtém contexto da PR e dispara comentários para o GitHub
+- **`HOUNDSMAN_TYPE_SAFE_API_KEY`** (opcional) — pré-análise Jev.
+- **`HOUNDSMAN_DEEP_SEEK_API_KEY`** (opcional) — IA própria do `hunt` nativo e das features de IA.
+- **`HOUNDSMAN_OPENAI_API_KEY`** / **`HOUNDSMAN_ANTHROPIC_API_KEY`** (opcional) — apenas se
+  `ai.provider` for `openai`/`anthropic`.
 
 ## Instalação (global)
 
@@ -87,6 +90,7 @@ Definido em `src/core/config.ts` (pacote) e espelhado em `.houndsman/core/types.
 | `alwaysIncludeDocs` | Docs sempre presentes nos briefs (default `["AGENTS.md"]`). |
 | `budgets` | **Opcional** — teto de arquivos por brief (`maxFilesPerBrief`, default `40`); o excedente vira "fora do orçamento" (registrar em `skipped`). |
 | `concurrency` | **Opcional** — chamadas Jev simultâneas (`jev`, default `5`). |
+| `ast` | **Opcional** — AST determinístico para TS/JS (`enabled`, `maxFileBytes`, `maxImpactFiles`, `languages`, `aliases`). Default: ligado; falhas são fail-open. |
 
 > O motor **não contém** ids, paths ou regras do projeto — tudo chega por `HoundsmanConfig`,
 > carregado em runtime a partir de `houndsman.config.ts` (ou `--config <path>`).

package/src/skill/hunt.md

@@ -10,6 +10,11 @@ as regras do projeto ficam em `houndsman.config.ts` + `.houndsman/`.
 **Quando usar:** revisar PR antes de merge · code review de feature branch · validar
 mudanças antes de push.
 
+> **Harness nativo (opcional):** além deste skill, o CLI tem `houndsman hunt` — o mesmo
+> fluxo executado pelo próprio houndsman, com tools read-only, investigação por evidência
+> e `VERIFY` obrigatório. Use `houndsman hunt --dry-run` para inspecionar sem IA. Detalhes
+> em `docs/HARNESS.md`.
+
 ## Quem executa o quê
 
 - **Você** só invoca o skill: `/houndsman [hunt]`. Não precisa rodar nenhum script à mão.
@@ -76,6 +81,8 @@ staging dos subagentes em `<HOUNDSMAN_HOME>/work/<reviewId>/`:
 | Artefato | Conteúdo |
 |---|---|
 | `classification.json` | Watchdogs ativados por arquivo + status (A/M/D/R) + churn (storage) |
+| `ast-summary.json` | Fatos estruturais + delta por arquivo (AST TS/JS) (storage) |
+| `ast-impact.json` | Importadores reversos e exports públicos alterados (storage) |
 | `candidates.json` | Indícios da pré-análise Jev (regra + arquivo + confiança) (storage) |
 | `briefs/<watchdog>.md` | Instruções prontas para cada subagente (staging + storage, para auditoria) |
 | `manifest.json` | Resumo: watchdogs, arquivos, deletados, status, contexto, Jev, orçamento (storage) |
@@ -83,6 +90,11 @@ staging dos subagentes em `<HOUNDSMAN_HOME>/work/<reviewId>/`:
 > O prepare imprime o caminho absoluto do diretório de briefs e cada brief traz o
 > `outputPath` do JSON que o subagente deve gravar. Briefs e contexto também ficam
 > persistidos no storage para auditoria; o staging é limpo após o `--finalize`.
+>
+> **AST (TS/JS, ligado por padrão):** cada brief ganha a seção `Estrutura (AST)` com
+> símbolos adicionados/removidos/alterados, assinaturas e imports; o impacto reverso
+> (quem importa os arquivos alterados) aparece como mapa de leitura. É fail-open:
+> sem grammar/ABI, a revisão segue só com regex. Desative com `--no-ast`.
 
 **Excluídos automaticamente:** lock files, `dist/`, `build/`, `.env*`, imagens, source
 maps (padrões do projeto em `.houndsman/exclusions.ts`).
@@ -106,7 +118,7 @@ arquivos da PR. Cada brief recebe no máximo `budgets.maxFilesPerBrief` arquivos
 
 ### Pré-análise Jev (Passo 1.5, opcional)
 
-Se `TYPESAFE_API_KEY` estiver definida, cada arquivo é avaliado pelo modelo **Jev** contra
+Se `HOUNDSMAN_TYPE_SAFE_API_KEY` estiver definida, cada arquivo é avaliado pelo modelo **Jev** contra
 as regras atômicas dos watchdogs. Respostas acima do limiar viram **candidatos** em
 `candidates.json` e entram no brief como *warm start* — o subagente **confirma ou refuta**.
 
@@ -264,7 +276,7 @@ Se a branch não for informada, detecta com `git branch --show-current`. Base do
 | `houndsman watchdog <id>` | Contexto de um watchdog (`--json`, `--rules`) |
 
 Flags do review: `--base` · `--head` · `--branch` · `--clean` · `--full` (força
-completo) · `--no-jev` · `--fail-on-blocking` (com `--finalize`).
+completo) · `--no-jev` · `--no-ast` · `--fail-on-blocking` (com `--finalize`).
 
 > Persistência: SQLite global em `<HOUNDSMAN_HOME>/houndsman.db`. O staging dos subagentes
 > (`briefs/`, `findings/`, contexto) vive em `<HOUNDSMAN_HOME>/work/<reviewId>/` e é limpo

package/src/skill/verify.md

@@ -24,7 +24,7 @@ altera regras.
    - **âncora sumida** (`stale`) → provável **resolvido** — mas o trecho pode ter sido reescrito;
    - **arquivo ausente** → fora da verificação (deletado/movido).
 
-2. **Tier Jev (opcional, só nos ambíguos).** Com `TYPESAFE_API_KEY`, os casos `stale` / sem
+2. **Tier Jev (opcional, só nos ambíguos).** Com `HOUNDSMAN_TYPE_SAFE_API_KEY`, os casos `stale` / sem
    âncora são confirmados pelo LLM sobre um **diff focado** do arquivo (`foundAtSha..HEAD`), uma
    pergunta `noul` por finding. Falha-aberto: sem chave/erro → vale o resultado local.