@payconductor/houndsman 0.1.0 → 0.1.3

package/src/core/commands/scaffold.ts

@@ -15,7 +15,7 @@
 
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, join } from "node:path";
-import { SKILL_DIR } from "../assets";
+import { SKILL_DIR, SKILL_FILE } from "../assets";
 import {
 	ARTIFACT_DIR,
 	CORE_DIR,
@@ -164,6 +164,24 @@ export type FileStatus =
 
 export type FileStatusMap = Record<string, { status: FileStatus; oldPath?: string }>;
 
+/** Linhas adicionadas/removidas de um arquivo no diff (churn). */
+export type FileChurn = { additions: number; deletions: number };
+
+/** Churn por caminho de arquivo. */
+export type ChurnMap = Record<string, FileChurn>;
+
+/** Limites de triage para PRs grandes. */
+export type HoundsmanBudgets = {
+	/** Máx. de arquivos por brief (default: 40). Excedente vai para "fora do orçamento". */
+	maxFilesPerBrief?: number;
+};
+
+/** Concorrência das fases paralelas internas. */
+export type HoundsmanConcurrency = {
+	/** Chamadas Jev simultâneas (default: 5). */
+	jev?: number;
+};
+
 /** Contrato de configuração do motor. */
 export type HoundsmanConfig<TId extends string = string> = {
 	projectName: string;
@@ -173,6 +191,8 @@ export type HoundsmanConfig<TId extends string = string> = {
 	exclusions: readonly RegExp[];
 	docMappings: readonly (readonly [RegExp, readonly string[]])[];
 	alwaysIncludeDocs?: readonly string[];
+	budgets?: HoundsmanBudgets;
+	concurrency?: HoundsmanConcurrency;
 };
 
 /** Helper de autoria (identidade) — apenas tipagem. */
@@ -259,25 +279,6 @@ core/
 .runs/
 `;
 
-const SKILL_POINTER = (
-	name: string,
-	projectName: string,
-	canonical: string,
-	description: string,
-	argumentHint: string,
-): string => `---
-name: ${name}
-description: '${description}'
-argument-hint: '${argumentHint}'
----
-
-# ${name} — ${projectName}
-
-> **Ponteiro.** O conteúdo canônico está em \`${canonical}\`.
-
-Leia e siga \`${canonical}\`.
-`;
-
 // ---------------------------------------------------------------------------
 // Escrita
 // ---------------------------------------------------------------------------
@@ -325,15 +326,17 @@ export function writeUserLayer(ctx: ScaffoldContext): void {
 
 /**
  * Arquivos auto-gerados: tipos, docs do skill, `.gitignore` (ignora `core/` e
- * `.runs/`) e os ponteiros de skill dos harnesses. Sempre sobrescritos (é o
- * alvo do `update`).
+ * `.runs/`) e o `SKILL.md` de cada harness. Sempre sobrescritos (é o alvo do
+ * `update`).
  */
 export function syncGeneratedFiles(ctx: ScaffoldContext): void {
 	writeGeneratedFile(ctx, join(CORE_DIR, "types.ts"), TYPES_TEMPLATE);
 	writeGeneratedFile(ctx, join(PROJECT_DIR, ".gitignore"), PROJECT_GITIGNORE);
 
+	// Docs do skill vão para `.houndsman/core/skill/`. O `SKILL.md` é o entry point
+	// dos harnesses (escrito em `writeHarnessPointers`), não um doc da camada.
 	for (const name of readdirSync(SKILL_DIR)) {
-		if (!name.endsWith(".md")) continue;
+		if (!name.endsWith(".md") || name === SKILL_FILE) continue;
 		const raw = readFileSync(join(SKILL_DIR, name), "utf8");
 		writeGeneratedFile(
 			ctx,
@@ -345,29 +348,15 @@ export function syncGeneratedFiles(ctx: ScaffoldContext): void {
 	for (const harness of ctx.harnesses) writeHarnessPointers(ctx, harness);
 }
 
-/** Escreve os ponteiros de skill de um harness. */
+/**
+ * Escreve o `SKILL.md` do harness a partir do asset base (`src/skill/SKILL.md`),
+ * resolvendo `{{projectName}}`. O texto do skill vive no asset — não aqui.
+ */
 function writeHarnessPointers(ctx: ScaffoldContext, harness: Harness): void {
-	const pointerDir = `.${harness}/skills`;
-	writeGeneratedFile(
-		ctx,
-		join(pointerDir, "houndsman", "SKILL.md"),
-		SKILL_POINTER(
-			"houndsman",
-			ctx.projectName,
-			`${CORE_SKILL_DIR}/houndsman.md`,
-			"Revisa Pull Requests com watchdogs especializados por domínio. Orquestra `bun run houndsman context` → `bun run houndsman` → subagentes → `bun run houndsman --finalize`. Config em `houndsman.config.ts`; regras em `.houndsman/`; relatório em `.houndsman/.runs/<branch-slug>/review.md`.",
-			"Nome da branch (opcional, detecta automaticamente se omitido)",
-		),
-	);
+	const raw = readFileSync(join(SKILL_DIR, SKILL_FILE), "utf8");
 	writeGeneratedFile(
 		ctx,
-		join(pointerDir, "houndsman-update", "SKILL.md"),
-		SKILL_POINTER(
-			"houndsman-update",
-			ctx.projectName,
-			`${CORE_SKILL_DIR}/houndsman-update.md`,
-			"Atualiza as regras e protocolos do skill houndsman (watchdogs, exclusões, mapeamentos de docs).",
-			"Watchdog alvo (opcional)",
-		),
+		join(`.${harness}`, "skills", "houndsman", SKILL_FILE),
+		raw.replaceAll("{{projectName}}", ctx.projectName),
 	);
 }

package/src/core/config.ts

@@ -12,6 +12,29 @@ import type { WatchdogDefinition } from "./types";
 /** Documentos sempre incluídos nos briefs (default). */
 export const DEFAULT_ALWAYS_INCLUDE_DOCS: readonly string[] = ["AGENTS.md"];
 
+/**
+ * Teto default de arquivos por brief. Um PR grande (milhares de linhas) pode
+ * concentrar centenas de arquivos em um único domínio; o teto mantém o contexto
+ * do subagente limitado — o excedente vira "fora do orçamento" (cobertura
+ * honesta), nunca some silenciosamente.
+ */
+export const DEFAULT_MAX_FILES_PER_BRIEF = 40;
+
+/** Concorrência default das chamadas simultâneas ao Jev. */
+export const DEFAULT_JEV_CONCURRENCY = 5;
+
+/** Limites de triage para PRs grandes. */
+export type HoundsmanBudgets = {
+	/** Máx. de arquivos por brief (default: 40). Excedente vai para "fora do orçamento". */
+	maxFilesPerBrief?: number;
+};
+
+/** Concorrência das fases paralelas internas. */
+export type HoundsmanConcurrency = {
+	/** Chamadas Jev simultâneas (default: 5). */
+	jev?: number;
+};
+
 /**
  * Configuração completa do motor de revisão para um projeto.
  *
@@ -35,6 +58,10 @@ export type HoundsmanConfig<TId extends string = string> = {
 	docMappings: readonly (readonly [RegExp, readonly string[]])[];
 	/** Docs sempre incluídos nos briefs (default: `DEFAULT_ALWAYS_INCLUDE_DOCS`). */
 	alwaysIncludeDocs?: readonly string[];
+	/** Limites de triage para PRs grandes (default: `DEFAULT_MAX_FILES_PER_BRIEF`). */
+	budgets?: HoundsmanBudgets;
+	/** Concorrência das fases paralelas internas. */
+	concurrency?: HoundsmanConcurrency;
 };
 
 /** Entrada de `defineHoundsmanConfig` — `watchdogIds` é derivado, não informado. */
@@ -57,3 +84,18 @@ export function defineHoundsmanConfig<TId extends string>(
 export function resolveArtifactDir(config: HoundsmanConfig): string {
 	return config.artifactDir ?? ARTIFACT_DIR;
 }
+
+/**
+ * Teto de arquivos por brief. Valor ausente/não-positivo cai no default —
+ * mantém o contexto do subagente limitado em PRs grandes.
+ */
+export function resolveMaxFilesPerBrief(config: HoundsmanConfig): number {
+	const value = config.budgets?.maxFilesPerBrief;
+	return value !== undefined && value > 0 ? value : DEFAULT_MAX_FILES_PER_BRIEF;
+}
+
+/** Concorrência das chamadas Jev (valor ausente/não-positivo cai no default). */
+export function resolveJevConcurrency(config: HoundsmanConfig): number {
+	const value = config.concurrency?.jev;
+	return value !== undefined && value > 0 ? value : DEFAULT_JEV_CONCURRENCY;
+}

package/src/core/diff-source.ts

@@ -0,0 +1,140 @@
+/**
+ * Coleta do diff em um único passo (biblioteca).
+ *
+ * Roda `git diff base...head` **uma vez** (patch) e `--numstat` **uma vez**
+ * (churn), fatiando o patch por arquivo em memória — o custo não cresce com o
+ * número de arquivos da PR.
+ *
+ * Usado por `orchestrator.prepare` (churn para a classificação + patch para o
+ * Jev) e por `classifyRange` (fallback standalone).
+ */
+
+import type { ChurnMap, FileChurn } from "./types";
+
+export type DiffSource = {
+	/** path → patch do arquivo (header + hunks), truncado por `maxPerFileChars`. */
+	byFile: Map<string, string>;
+	/** path (novo) → linhas adicionadas/removidas. */
+	churn: Map<string, FileChurn>;
+};
+
+export type CollectDiffOptions = {
+	/** Teto de caracteres por arquivo no patch (default: 8_000). */
+	maxPerFileChars?: number;
+};
+
+/** Teto default de caracteres por arquivo no patch (compartilhado com o git-revision). */
+export const DEFAULT_MAX_PER_FILE_CHARS = 8_000;
+
+/** Executa `git` com `core.quotepath=false` (paths literais) e devolve o stdout. */
+function runGit(args: string[]): string {
+	const result = Bun.spawnSync(["git", "-c", "core.quotepath=false", ...args], {
+		stdout: "pipe",
+		stderr: "pipe",
+	});
+	if (result.exitCode !== 0) {
+		const stderr = new TextDecoder().decode(result.stderr).trim();
+		throw new Error(`git ${args.join(" ")} falhou: ${stderr}`);
+	}
+	return new TextDecoder().decode(result.stdout);
+}
+
+/** Novo caminho do arquivo a partir do cabeçalho de um segmento do patch. */
+function extractPath(segment: string): string | undefined {
+	// Só o cabeçalho (antes do primeiro hunk) pode conter as linhas `---`/`+++` —
+	// assim uma linha de conteúdo como `+++ b/x` não é confundida com o header.
+	const hunkAt = segment.indexOf("\n@@");
+	const header = hunkAt >= 0 ? segment.slice(0, hunkAt) : segment;
+	const lines = header.split("\n");
+
+	for (const line of lines) {
+		if (line.startsWith("+++ b/")) return line.slice(6);
+	}
+	for (const line of lines) {
+		// Deletados têm `+++ /dev/null`; o caminho antigo é a melhor referência.
+		if (line.startsWith("--- a/")) return line.slice(6);
+	}
+
+	// Fallback (ex.: binário, sem `---`/`+++`): `a/<old> b/<new>`.
+	const firstLine = lines[0] ?? "";
+	const marker = firstLine.lastIndexOf(" b/");
+	return marker >= 0 ? firstLine.slice(marker + 3) : undefined;
+}
+
+/** Fatia um patch unificado por arquivo (`diff --git`). */
+export function parseDiffIndex(
+	patch: string,
+	maxPerFileChars = Number.POSITIVE_INFINITY,
+): Map<string, string> {
+	const map = new Map<string, string>();
+	for (const segment of patch.split(/^diff --git /m)) {
+		if (!segment.trim()) continue;
+		const path = extractPath(segment);
+		if (!path) continue;
+		const text = `diff --git ${segment}`;
+		map.set(
+			path,
+			text.length > maxPerFileChars ? text.slice(0, maxPerFileChars) : text,
+		);
+	}
+	return map;
+}
+
+/** Contagem do `--numstat` (`-` em binários) → número. */
+function toCount(value: string): number {
+	const parsed = Number.parseInt(value, 10);
+	return Number.isNaN(parsed) ? 0 : parsed;
+}
+
+/** Fatia `git diff --numstat -z` em path → churn (trata renames/cópias/bins). */
+export function parseNumstat(raw: string): Map<string, FileChurn> {
+	const map = new Map<string, FileChurn>();
+	const tokens = raw.split("\0");
+
+	for (let i = 0; i < tokens.length; i++) {
+		const token = tokens[i];
+		if (!token) continue;
+		const fields = token.split("\t");
+		if (fields.length < 3) continue;
+
+		let path = fields[2];
+		if (path === "") {
+			// Renomeado/copiado: os dois caminhos seguem como tokens próprios.
+			path = tokens[i + 2] ?? "";
+			i += 2;
+		}
+		if (!path) continue;
+
+		map.set(path, { additions: toCount(fields[0]), deletions: toCount(fields[1]) });
+	}
+	return map;
+}
+
+/** Churn por arquivo (`git diff --numstat -z`) — 1 spawn. */
+export function collectChurn(base: string, head: string): Map<string, FileChurn> {
+	return parseNumstat(runGit(["diff", "--numstat", "-z", `${base}...${head}`]));
+}
+
+/**
+ * Patch + churn em uma passada: 2 spawns fixos, independentes do nº de arquivos.
+ */
+export function collectDiff(
+	base: string,
+	head: string,
+	options: CollectDiffOptions = {},
+): DiffSource {
+	const range = `${base}...${head}`;
+	const patch = runGit(["diff", range]);
+	return {
+		byFile: parseDiffIndex(
+			patch,
+			options.maxPerFileChars ?? DEFAULT_MAX_PER_FILE_CHARS,
+		),
+		churn: collectChurn(base, head),
+	};
+}
+
+/** Converte o Map de churn em Record (para o `classification.json`). */
+export function churnToRecord(churn: Map<string, FileChurn>): ChurnMap {
+	return Object.fromEntries(churn);
+}

package/src/core/file-classifier.ts

@@ -7,7 +7,8 @@
 
 import { readFileSync } from "node:fs";
 import type { HoundsmanConfig } from "./config";
-import type { ClassifyRule, WatchdogDefinition } from "./types";
+import { churnToRecord, collectChurn, type DiffSource } from "./diff-source";
+import type { ChurnMap, ClassifyRule, WatchdogDefinition } from "./types";
 
 type FileStatus = "added" | "modified" | "deleted" | "renamed" | "copied" | "unknown";
 
@@ -22,6 +23,8 @@ export type ClassificationResult = {
 	watchdogs: Record<string, string[]>;
 	/** path → metadados (status, oldPath) */
 	files: Record<string, { status: FileStatus; oldPath?: string }>;
+	/** path → linhas adicionadas/removidas (churn do diff) */
+	churn: ChurnMap;
 	/** Arquivos não classificados (revisar manualmente) */
 	unclassified: string[];
 	/** Arquivos excluídos da revisão (gerados, locks, builds) */
@@ -167,6 +170,7 @@ export function parseEntries(raw: string): FileEntry[] {
 export function classifyEntries<TId extends string>(
 	entries: FileEntry[],
 	config: HoundsmanConfig<TId>,
+	churn: ChurnMap = {},
 ): ClassificationResult {
 	const watchdogFiles: Record<string, string[]> = {};
 	const files: ClassificationResult["files"] = {};
@@ -223,6 +227,7 @@ export function classifyEntries<TId extends string>(
 	return {
 		watchdogs,
 		files,
+		churn,
 		unclassified,
 		excluded,
 		deleted,
@@ -233,15 +238,58 @@ export function classifyEntries<TId extends string>(
 
 /**
  * Executa `git diff` entre base e head e classifica os arquivos alterados.
+ *
+ * `diff` (opcional) reaproveita um `DiffSource` já coletado — evita rodar o git
+ * de novo quando o chamador (ex.: `prepare`) precisa também do patch para o Jev.
  */
 export function classifyRange<TId extends string>(
 	base: string,
 	head: string,
 	config: HoundsmanConfig<TId>,
+	diff?: DiffSource,
 ): ClassificationResult {
 	const entries = parseEntries(runGitDiff(base, head));
-	const result = classifyEntries(entries, config);
+	const churn = diff?.churn ?? collectChurn(base, head);
+	const result = classifyEntries(entries, config, churnToRecord(churn));
 	result.base = base;
 	result.head = head;
 	return result;
 }
+
+// ---------------------------------------------------------------------------
+// Triage (PRs grandes)
+// ---------------------------------------------------------------------------
+
+/** Churn total (adições + remoções) de um arquivo; 0 quando ausente. */
+export function churnOf(filePath: string, churn: ChurnMap | undefined): number {
+	const entry = churn?.[filePath];
+	return entry ? entry.additions + entry.deletions : 0;
+}
+
+/** Ordena os arquivos por risco (churn desc; empate pelo caminho). */
+export function sortByRisk(files: readonly string[], churn?: ChurnMap): string[] {
+	return [...files].sort((a, b) => {
+		const delta = churnOf(b, churn) - churnOf(a, churn);
+		return delta !== 0 ? delta : a.localeCompare(b);
+	});
+}
+
+/** Resultado da aplicação do orçamento: o que revisar e o que ficou de fora. */
+export type BudgetSelection = { selected: string[]; overflow: string[] };
+
+/**
+ * Aplica o orçamento por brief: mantém os `maxFiles` de maior risco e devolve o
+ * restante em `overflow` (nunca descarta silenciosamente). `maxFiles` não-positivo
+ * ou não-finito desativa o orçamento.
+ */
+export function selectByBudget(
+	files: readonly string[],
+	churn: ChurnMap | undefined,
+	maxFiles: number,
+): BudgetSelection {
+	const ordered = sortByRisk(files, churn);
+	if (!Number.isFinite(maxFiles) || maxFiles <= 0 || ordered.length <= maxFiles) {
+		return { selected: ordered, overflow: [] };
+	}
+	return { selected: ordered.slice(0, maxFiles), overflow: ordered.slice(maxFiles) };
+}

package/src/core/finding-anchor.ts

@@ -0,0 +1,147 @@
+/**
+ * Identidade e reancoragem de findings (biblioteca).
+ *
+ * Um finding NÃO é identificado pela linha: a linha desloca após um auto-fix.
+ * A identidade é o `fingerprint` (arquivo + regra + âncora de conteúdo); a linha
+ * é apenas cache, recalculada varrendo o arquivo (`locateAnchor`).
+ *
+ * Âncora = linha ofensora normalizada + contexto (linha anterior/seguinte).
+ * Quando o fix altera a linha ofensora, a âncora some → o finding fica `stale`.
+ *
+ * Ocorrências byte-idênticas (mesmo snippet E mesmo contexto) compartilham o
+ * fingerprint: são tratadas como um grupo (limitação conhecida).
+ */
+
+import { createHash } from "node:crypto";
+
+/** Âncora de conteúdo de um finding (independente do número da linha). */
+export type FindingAnchor = {
+	/** Linha ofensora normalizada. */
+	snippet: string;
+	/** Linha anterior normalizada (ausente se a ofensora for a primeira). */
+	contextBefore?: string;
+	/** Linha seguinte normalizada (ausente se a ofensora for a última). */
+	contextAfter?: string;
+	/** Última linha conhecida (1-based) — cache, nunca identidade. */
+	line: number;
+};
+
+/** Resultado da localização de uma âncora no conteúdo atual. */
+export type AnchorLocation = {
+	/** Linha atual (1-based) ou null se a âncora não existe mais. */
+	line: number | null;
+	/** Nº de ocorrências da âncora no arquivo. */
+	occurrences: number;
+};
+
+/** Normaliza uma linha: colapsa espaços internos e apara as pontas. */
+export function normalizeLine(raw: string): string {
+	return raw.replace(/\s+/g, " ").trim();
+}
+
+/** Conteúdo → linhas normalizadas (uma por linha do arquivo). */
+export function normalizedLines(content: string): string[] {
+	return content.split(/\r?\n/).map(normalizeLine);
+}
+
+/** Marcador de contexto ausente (não confundir com linha vazia). */
+const ABSENT = "\u0001";
+
+/** Chave estável da âncora (snippet + contexto, SEM a linha). */
+function anchorKey(anchor: FindingAnchor): string {
+	return [
+		anchor.snippet,
+		anchor.contextBefore ?? ABSENT,
+		anchor.contextAfter ?? ABSENT,
+	].join("\u0000");
+}
+
+/** Hash estável (sha256 truncado) — base das identidades do motor. */
+export function hashKey(input: string): string {
+	return createHash("sha256").update(input).digest("hex").slice(0, 16);
+}
+
+/**
+ * Fingerprint do finding: `arquivo + regra + âncora`. Sem a linha — permanece
+ * estável após edições que deslocam o trecho. Sem âncora, cai no `fallback`
+ * (ex.: `message`). Ocorrências com a MESMA âncora compartilham o fingerprint.
+ */
+export function fingerprintOf(
+	file: string,
+	rule: string,
+	anchor: FindingAnchor | null,
+	fallback = "",
+): string {
+	const key = anchor ? anchorKey(anchor) : `fallback:${fallback}`;
+	return hashKey(`${file}\u0000${rule}\u0000${key}`);
+}
+
+/**
+ * Monta a âncora a partir do conteúdo: usa a `line` (1-based) quando válida;
+ * senão procura a linha que contém a `evidence`. Retorna null se não localizar
+ * (ex.: arquivo deletado/binário).
+ */
+export function buildAnchor(
+	content: string,
+	line: number | undefined,
+	evidence?: string,
+): FindingAnchor | null {
+	const lines = normalizedLines(content);
+
+	let index = -1;
+	if (line !== undefined && line >= 1 && line <= lines.length) {
+		index = line - 1;
+	} else if (evidence) {
+		const needle = normalizeLine(evidence);
+		if (needle) index = lines.findIndex((l) => l.includes(needle));
+	}
+	if (index < 0) return null;
+
+	const anchor: FindingAnchor = { snippet: lines[index], line: index + 1 };
+	if (index - 1 >= 0) anchor.contextBefore = lines[index - 1];
+	if (index + 1 < lines.length) anchor.contextAfter = lines[index + 1];
+	return anchor;
+}
+
+/** `true` se a linha `i` casa a âncora (snippet + contexto). */
+function matchesAt(lines: string[], i: number, anchor: FindingAnchor): boolean {
+	if (lines[i] !== anchor.snippet) return false;
+	if (anchor.contextBefore !== undefined && lines[i - 1] !== anchor.contextBefore) {
+		return false;
+	}
+	if (anchor.contextAfter !== undefined && lines[i + 1] !== anchor.contextAfter) {
+		return false;
+	}
+	return true;
+}
+
+/** Localiza a âncora no conteúdo atual (linha + nº de ocorrências). */
+export function locateAnchor(
+	content: string,
+	anchor: FindingAnchor | null,
+): AnchorLocation {
+	if (!anchor) return { line: null, occurrences: 0 };
+	const lines = normalizedLines(content);
+	let occurrences = 0;
+	let first = -1;
+	for (let i = 0; i < lines.length; i++) {
+		if (!matchesAt(lines, i, anchor)) continue;
+		occurrences++;
+		if (first < 0) first = i;
+	}
+	return { line: first < 0 ? null : first + 1, occurrences };
+}
+
+export type ReanchorStatus = "ok" | "moved" | "stale";
+
+/** Reancora um finding: recalcula a linha e classifica o deslocamento. */
+export function reanchor(
+	content: string,
+	anchor: FindingAnchor | null,
+	previousLine: number | null,
+): { status: ReanchorStatus; line: number | null } {
+	const { line } = locateAnchor(content, anchor);
+	if (line === null) return { status: "stale", line: null };
+	if (previousLine !== null && line === previousLine) return { status: "ok", line };
+	return { status: "moved", line };
+}