@payconductor/houndsman 0.3.0 → 0.5.0

package/src/core/paths.ts

@@ -2,11 +2,13 @@
  * Caminhos do houndsman (biblioteca): raiz relativa para logs + layout fixo da
  * camada de projeto (`.houndsman/`).
  *
- * A camada gerada tem local fixo, então nada aqui é configurável pelo projeto:
- * o CLI deriva os artefatos e o schema de output destas constantes.
+ * A camada gerada tem local fixo, então nada aqui é configurável pelo projeto.
+ * Dados de execução (reviews/findings/artefatos) vivem no storage global; aqui
+ * ficam só os paths da camada e os nomes dos artefatos de staging.
  */
 
-import { relative } from "node:path";
+import { homedir } from "node:os";
+import { relative, sep } from "node:path";
 import { OUTPUT_FORMAT_FILE } from "./assets";
 
 /** Caminho relativo ao cwd, sempre com `/` (portável/legível em logs). */
@@ -14,6 +16,16 @@ export function relFromRoot(absPath: string): string {
 	return relative(process.cwd(), absPath).replace(/\\/g, "/");
 }
 
+/** Caminho legível para mensagens: `~/...` quando sob o home, senão absoluto. */
+export function displayPath(absPath: string): string {
+	const home = homedir();
+	if (absPath === home) return "~";
+	if (absPath.startsWith(`${home}${sep}`)) {
+		return `~${absPath.slice(home.length).replace(/\\/g, "/")}`;
+	}
+	return absPath.replace(/\\/g, "/");
+}
+
 /** Diretório da camada de projeto (regras + artefatos). */
 export const PROJECT_DIR = ".houndsman";
 
@@ -23,26 +35,23 @@ export const CORE_DIR = `${PROJECT_DIR}/core`;
 /** Skill canônico (markdown) dentro da camada gerada. */
 export const CORE_SKILL_DIR = `${CORE_DIR}/skill`;
 
-/** Artefatos da revisão (briefs, findings, review.md) — default de `artifactDir`. */
-export const ARTIFACT_DIR = `${PROJECT_DIR}/.runs`;
-
 /** Schema de output dos watchdogs, citado nos briefs. */
 export const OUTPUT_FORMAT_PATH = `${CORE_SKILL_DIR}/${OUTPUT_FORMAT_FILE}`;
 
-/** Estado de triagem dos findings, dentro da pasta da run (`<slug>/state.json`). */
-export const STATE_FILE = "state.json";
-
-/** Status da run (revisão/correção), dentro da pasta da run (`<slug>/run.json`). */
-export const RUN_STATUS_FILE = "run.json";
-
-/** Relatório da verificação de findings, dentro da pasta da run (`<slug>/verify.md`). */
-export const VERIFY_FILE = "verify.md";
-
-/** Contexto bruto da PR (`gh pr view`), dentro da pasta da run. */
+/** Contexto bruto da PR (`gh pr view`), no staging da review. */
 export const CONTEXT_FILE = "context.json";
 
-/** Resumo do contexto gravado pelo subagente, dentro da pasta da run. */
+/** Resumo do contexto gravado pelo subagente, no staging da review. */
 export const CONTEXT_SUMMARY_FILE = "context-summary.json";
 
 /** Brief do subagente que resume o contexto da PR. */
 export const CONTEXT_BRIEF_FILE = "context-brief.md";
+
+/** Relatório da verificação de findings (artefato `verify.md`). */
+export const VERIFY_FILE = "verify.md";
+
+/** Relatório consolidado da review (artefato `review.md`). */
+export const REVIEW_FILE = "review.md";
+
+/** Resumo final da review (artefato `review-resume.md`) — leitura humana apenas. */
+export const REVIEW_RESUME_FILE = "review-resume.md";

package/src/core/pr-context.ts

@@ -5,7 +5,7 @@
  * OPCIONAL: sem binário, sem login ou sem PR para a branch, grava
  * `context.json` com `{ available: false, reason }` e sai com código 0.
  *
- * Artefatos (em --dir, default .houndsman/.runs/<branch-slug>/):
+ * Artefatos no staging da review (`<HOUNDSMAN_HOME>/work/<reviewId>/`):
  *   context.json      payload bruto do `gh pr view` (ou marcador de indisponível)
  *   context-brief.md  instruções para o subagente resumir o contexto
  *
@@ -22,13 +22,19 @@ import {
 } from "./paths";
 import type { ContextSummary } from "./report-builder";
 import { parseContextSummary } from "./report-builder";
-import { type ContextPaths, RunLayout } from "./run-layout";
 import { systemClock } from "./services/clock";
 import { defaultGhRunner, GhClient, type GhRunner } from "./services/gh-client";
 import { GitRepository } from "./services/git-repository";
 
 export { CONTEXT_BRIEF_FILE, CONTEXT_FILE, CONTEXT_SUMMARY_FILE };
-export type { ContextPaths };
+
+/** Caminhos dos artefatos de contexto da PR (staging da review). */
+export type ContextPaths = {
+	dir: string;
+	context: string;
+	summary: string;
+	brief: string;
+};
 
 const GH_JSON_FIELDS =
 	"number,title,body,url,baseRefName,headRefName,author,commits,files";
@@ -60,8 +66,16 @@ export type PrContextRaw = {
 };
 
 /** Caminhos dos artefatos de contexto para uma branch. */
-export function contextPaths(dir: string, branch: string): ContextPaths {
-	return new RunLayout(dir, branch).contextPaths;
+export function contextFileNames(): {
+	context: string;
+	summary: string;
+	brief: string;
+} {
+	return {
+		context: CONTEXT_FILE,
+		summary: CONTEXT_SUMMARY_FILE,
+		brief: CONTEXT_BRIEF_FILE,
+	};
 }
 
 /** Detecta a branch atual; lança se não houver (o CLI decide o exit). */

package/src/core/project-config.ts

@@ -2,17 +2,16 @@
  * Configuração do projeto (domínio) — resolve defaults e expõe o registry.
  *
  * Evita o "data clump" de passar `HoundsmanConfig` para dezenas de funções:
- * quem precisa de `artifactDir`/orçamento/concorrência/watchdogs pede aqui.
+ * quem precisa de orçamento/concorrência/watchdogs pede aqui.
  * O contrato do consumidor (`houndsman.config.ts`) não muda.
  */
 
-import type { HoundsmanConfig } from "./config";
+import type { HoundsmanConfig, HoundsmanStorage } from "./config";
 import {
 	DEFAULT_ALWAYS_INCLUDE_DOCS,
 	DEFAULT_JEV_CONCURRENCY,
 	DEFAULT_MAX_FILES_PER_BRIEF,
 } from "./defaults";
-import { ARTIFACT_DIR } from "./paths";
 import { WatchdogRegistry } from "./watchdog-registry";
 
 /** Configuração resolvida do projeto. */
@@ -29,8 +28,8 @@ export class ProjectConfig<TId extends string = string> {
 		return this.raw.projectName;
 	}
 
-	get artifactDir(): string {
-		return this.raw.artifactDir ?? ARTIFACT_DIR;
+	get storage(): HoundsmanStorage {
+		return this.raw.storage ?? {};
 	}
 
 	get maxFilesPerBrief(): number {

package/src/core/renderers/manifest-writer.ts

@@ -1,20 +1,20 @@
 /**
- * Manifesto da run (biblioteca) — monta e grava o `manifest.json`.
+ * Manifesto da run (biblioteca) — monta e grava o artefato `manifest.json`.
  *
  * Concentra o resumo do que foi ativado (watchdogs, orçamento, churn, contexto,
- * Jev e incremental), hoje espalhado em helpers do orquestrador.
+ * Jev e incremental). O manifesto vive no storage; os caminhos de briefs e
+ * findings apontam para o staging da review.
  */
 
 import { Classification } from "../domain/classification";
 import type { ClassificationResult } from "../file-classifier";
 import type { JevCandidatesFile } from "../jev";
-import { OUTPUT_FORMAT_PATH, relFromRoot } from "../paths";
-import { readContextSummary } from "../pr-context";
+import { OUTPUT_FORMAT_PATH } from "../paths";
 import type { ProjectConfig } from "../project-config";
 import type { MergedFinding } from "../report-builder";
-import type { RunLayout } from "../run-layout";
 import { systemClock } from "../services/clock";
-import { ProjectFiles } from "../services/project-files";
+import type { ReviewRecord, StorageProvider } from "../storage/types";
+import type { ReviewWorkArea } from "../storage/work-area";
 
 /** Opções do manifesto (subset do `ReviewOptions`). */
 export type ManifestOptions = {
@@ -32,12 +32,22 @@ export type ManifestClassification = ClassificationResult & {
 
 /** Escreve o `manifest.json` de uma run. */
 export class ManifestWriter {
-	private readonly layout: RunLayout;
+	private readonly storage: StorageProvider;
+	private readonly review: ReviewRecord;
+	private readonly work: ReviewWorkArea;
 	private readonly project: ProjectConfig;
 	private readonly options: ManifestOptions;
 
-	constructor(layout: RunLayout, project: ProjectConfig, options: ManifestOptions) {
-		this.layout = layout;
+	constructor(
+		storage: StorageProvider,
+		review: ReviewRecord,
+		work: ReviewWorkArea,
+		project: ProjectConfig,
+		options: ManifestOptions,
+	) {
+		this.storage = storage;
+		this.review = review;
+		this.work = work;
 		this.project = project;
 		this.options = options;
 	}
@@ -60,16 +70,16 @@ export class ManifestWriter {
 				name: this.project.watchdogs.nameOf(id),
 				files: selection.selected,
 				overflow: selection.overflow.length,
-				brief: relFromRoot(this.layout.briefFile(id)),
-				findings: relFromRoot(this.layout.findingFile(id)),
+				brief: this.work.briefFile(id),
+				findings: this.work.findingFile(id),
 				status: pending.includes(id) ? "pending" : "done",
 			};
 		});
 
-		const summary = readContextSummary(this.layout.contextPaths.summary);
+		const summary = this.work.readContextSummary();
 		const manifest = {
-			branch: this.layout.branch,
-			slug: this.layout.slug,
+			branch: this.review.branch,
+			slug: this.review.slug,
 			base: this.options.base,
 			head: this.options.head,
 			headSha: classification.headSha,
@@ -104,9 +114,10 @@ export class ManifestWriter {
 			excludedCount: classification.excludedCount,
 		};
 
-		new ProjectFiles().write(
-			this.layout.manifestFile,
-			`${JSON.stringify(manifest, null, 2)}\n`,
-		);
+		this.storage.writeArtifact(this.review.id, {
+			name: "manifest.json",
+			kind: "manifest",
+			content: `${JSON.stringify(manifest, null, 2)}\n`,
+		});
 	}
 }

package/src/core/renderers/resume-renderer.ts

@@ -0,0 +1,151 @@
+/**
+ * Resumo final da revisão (`review-resume.md`).
+ *
+ * Artefato somente-leitura para humanos: não entra em briefs, não é lido pelos
+ * watchdogs e não participa de nenhuma etapa seguinte. Une o contexto de
+ * negócio da PR aos números técnicos diretos da revisão, com limite de
+ * `RESUME_MAX_CHARS`.
+ */
+
+import type {
+	ContextSummary,
+	MergedFinding,
+	WatchdogNameResolver,
+} from "../report-builder";
+import { systemClock } from "../services/clock";
+
+/** Teto de caracteres do artefato (inclui cabeçalho e quebras de linha). */
+export const RESUME_MAX_CHARS = 2500;
+
+/** Dados de classificação usados no resumo. */
+export type ResumeClassification = {
+	files: Record<string, { status: string }>;
+	watchdogs: Record<string, string[]>;
+};
+
+export type ReviewResumeInput = {
+	branch: string;
+	/** `YYYY-MM-DD`; default: data corrente do sistema. */
+	date?: string;
+	context?: ContextSummary | null;
+	classification: ResumeClassification;
+	findings: readonly MergedFinding[];
+	nameOf?: WatchdogNameResolver;
+};
+
+const identityName: WatchdogNameResolver = (id) => id;
+
+const STATUS_BY_SEVERITY: Record<"blocking" | "attention" | "clean", string> = {
+	blocking: "❌ Mudanças necessárias",
+	attention: "⚠️ Aprovado com ressalvas",
+	clean: "✅ Aprovado",
+};
+
+/** Corta o texto em `max` caracteres, sinalizando com reticências. */
+function truncate(value: string, max: number): string {
+	const text = value.trim().replace(/\s+/g, " ");
+	return text.length <= max ? text : `${text.slice(0, max - 1).trimEnd()}…`;
+}
+
+function plural(count: number, singular: string, plural: string): string {
+	return `${count} ${count === 1 ? singular : plural}`;
+}
+
+/** Resumo de negócio: contexto da PR; sem ele, o alcance da branch. */
+function businessSection(input: ReviewResumeInput): string[] {
+	const context = input.context;
+	const hasContext =
+		context?.available === true &&
+		Boolean(
+			context.objective ||
+				context.motivation ||
+				(context.changeSummary && context.changeSummary.length > 0),
+		);
+	const lines = ["## Resumo de negócio", ""];
+
+	if (!hasContext) {
+		const domainCount = Object.keys(input.classification.watchdogs).length;
+		lines.push(
+			`A branch \`${input.branch}\` altera ${plural(
+				Object.keys(input.classification.files).length,
+				"arquivo",
+				"arquivos",
+			)} em ${plural(domainCount, "domínio", "domínios")} de revisão.`,
+			"Sem resumo de contexto da PR disponível.",
+			"",
+		);
+		return lines;
+	}
+
+	if (context.objective) lines.push(context.objective, "");
+	if (context.motivation) lines.push(`**Por quê:** ${context.motivation}`, "");
+	if (context.changeSummary && context.changeSummary.length > 0) {
+		for (const item of context.changeSummary.slice(0, 4)) {
+			lines.push(`- ${truncate(item, 180)}`);
+		}
+		lines.push("");
+	}
+	return lines;
+}
+
+/** Achados que exigem ação, em formato direto (máximo 5). */
+function technicalSection(
+	findings: readonly MergedFinding[],
+	nameOf: WatchdogNameResolver,
+): string[] {
+	const relevant = findings
+		.filter(
+			(finding) =>
+				finding.severity === "blocking" || finding.severity === "attention",
+		)
+		.slice(0, 5);
+	const lines = ["## Pontos técnicos", ""];
+	if (relevant.length === 0) {
+		lines.push("- Nenhum bloqueio ou ponto de atenção.", "");
+		return lines;
+	}
+	for (const finding of relevant) {
+		const location = finding.line ? `${finding.file}:${finding.line}` : finding.file;
+		const watchdogs = finding.watchdogs.map((id) => nameOf(id)).join(", ");
+		lines.push(
+			`- \`${location}\` — ${truncate(finding.message, 130)}${watchdogs ? ` _(${watchdogs})_` : ""}`,
+		);
+	}
+	lines.push("");
+	return lines;
+}
+
+/** Garante o teto de caracteres cortando em uma quebra de linha. */
+function clamp(markdown: string, max: number): string {
+	if (markdown.length <= max) return markdown;
+	const head = markdown.slice(0, max - 2);
+	const cut = head.lastIndexOf("\n");
+	return `${(cut > 0 ? head.slice(0, cut) : head).trimEnd()}\n…`;
+}
+
+/**
+ * Renderiza o resumo final. Determinístico e sem chamadas externas: o texto
+ * nasce do contexto já disponível e dos findings consolidados.
+ */
+export function renderReviewResume(input: ReviewResumeInput): string {
+	const nameOf = input.nameOf ?? identityName;
+	const blockers = input.findings.filter((f) => f.severity === "blocking").length;
+	const attention = input.findings.filter((f) => f.severity === "attention").length;
+	const status =
+		blockers > 0
+			? STATUS_BY_SEVERITY.blocking
+			: attention > 0
+				? STATUS_BY_SEVERITY.attention
+				: STATUS_BY_SEVERITY.clean;
+
+	const lines = [
+		`# Resumo da revisão — ${input.branch}`,
+		"",
+		`**Data:** ${input.date ?? systemClock().slice(0, 10)} · **Status:** ${status}`,
+		"",
+		...businessSection(input),
+		...technicalSection(input.findings, nameOf),
+	];
+
+	return clamp(`${lines.join("\n").trimEnd()}\n`, RESUME_MAX_CHARS);
+}

package/src/core/report-builder.ts

@@ -294,6 +294,7 @@ function renderConclusion(counts: Record<Severity, number>): string[] {
 		"",
 		`**Status:** ${status}`,
 		`**Resumo:** ${counts.blocking} violações bloqueantes, ${counts.attention} pontos de atenção, ${counts.suggestion} sugestões e ${counts.nit} nits.`,
+		"",
 	];
 }
 
@@ -453,6 +454,12 @@ export function renderReport(
 
 	if (context) lines.push(...renderContext(context));
 
+	// Sumário primeiro: quem lê o review.md vê domínios, cobertura e conclusão
+	// antes dos pontos específicos.
+	lines.push(...renderDomainIndex(domains));
+	lines.push(...renderCoverage(reports, coverage, nameOf));
+	lines.push(...renderConclusion(counts));
+
 	lines.push(...renderFindingsSections(merged, nameOf));
 
 	if (merged.length === 0) {
@@ -463,9 +470,5 @@ export function renderReport(
 		lines.push(...renderUnconfirmedCandidates(candidates, merged));
 	}
 
-	lines.push(...renderDomainIndex(domains));
-	lines.push(...renderCoverage(reports, coverage, nameOf));
-	lines.push(...renderConclusion(counts));
-
 	return lines.join("\n");
 }

package/src/core/run-layout.ts

@@ -1,108 +1,8 @@
 /**
- * Layout de uma run (biblioteca) — único ponto que conhece os nomes/estrutura
- * dos artefatos em `.houndsman/.runs/<slug>/`.
+ * Removido: o layout de artefatos do projeto deu lugar ao staging global por
+ * review (`ReviewWorkArea` em `core/storage/work-area.ts`).
  *
- * Evita o "data clump" de `(dir, branch)`/`(outDir, branch)` espalhado pelo
- * motor: quem precisa de um caminho pede ao layout.
+ * Mantido apenas para não quebrar imports antigos de tipos.
  */
 
-import { join } from "node:path";
-import {
-	CONTEXT_BRIEF_FILE,
-	CONTEXT_FILE,
-	CONTEXT_SUMMARY_FILE,
-	RUN_STATUS_FILE,
-	STATE_FILE,
-	VERIFY_FILE,
-} from "./paths";
-import { sanitizeBranch } from "./report-builder";
-
-/** Caminhos dos artefatos de contexto da PR. */
-export type ContextPaths = {
-	dir: string;
-	context: string;
-	summary: string;
-	brief: string;
-};
-
-/** Diretório e caminhos de uma run (branch-slug). */
-export class RunLayout {
-	readonly artifactDir: string;
-	readonly branch: string;
-
-	constructor(artifactDir: string, branch: string) {
-		this.artifactDir = artifactDir;
-		this.branch = branch;
-	}
-
-	get slug(): string {
-		return sanitizeBranch(this.branch);
-	}
-
-	get outDir(): string {
-		return join(this.artifactDir, this.slug);
-	}
-
-	get briefsDir(): string {
-		return join(this.outDir, "briefs");
-	}
-
-	get findingsDir(): string {
-		return join(this.outDir, "findings");
-	}
-
-	/** Caminho de um arquivo dentro da pasta da run. */
-	file(name: string): string {
-		return join(this.outDir, name);
-	}
-
-	briefFile(id: string): string {
-		return join(this.briefsDir, `${id}.md`);
-	}
-
-	findingFile(id: string): string {
-		return join(this.findingsDir, `${id}.json`);
-	}
-
-	get classificationFile(): string {
-		return this.file("classification.json");
-	}
-
-	get manifestFile(): string {
-		return this.file("manifest.json");
-	}
-
-	get candidatesFile(): string {
-		return this.file("candidates.json");
-	}
-
-	get reviewFile(): string {
-		return this.file("review.md");
-	}
-
-	get stateFile(): string {
-		return this.file(STATE_FILE);
-	}
-
-	get runStatusFile(): string {
-		return this.file(RUN_STATUS_FILE);
-	}
-
-	get verifyFile(): string {
-		return this.file(VERIFY_FILE);
-	}
-
-	/** Relatório isolado de um watchdog (`review.<id>.md`). */
-	domainReportFile(id: string): string {
-		return this.file(`review.${sanitizeBranch(id)}.md`);
-	}
-
-	get contextPaths(): ContextPaths {
-		return {
-			dir: this.outDir,
-			context: this.file(CONTEXT_FILE),
-			summary: this.file(CONTEXT_SUMMARY_FILE),
-			brief: this.file(CONTEXT_BRIEF_FILE),
-		};
-	}
-}
+export type { ContextPaths } from "./storage/work-area";