@payconductor/houndsman 0.0.0-stage → 0.1.1

package/src/core/config-loader.ts

@@ -0,0 +1,87 @@
+/**
+ * Descoberta e carregamento da configuração do projeto — biblioteca.
+ *
+ * O motor é agnóstico: a config do projeto (`HoundsmanConfig`) é resolvida em
+ * runtime a partir do cwd do consumidor — nunca importada estaticamente.
+ *
+ * Ordem de resolução:
+ *   1. `--config <path>` (explícito)
+ *   2. `houndsman.config.{ts,mts,js,mjs}`
+ *   3. `.houndsman/config.{ts,js}`
+ */
+
+import { existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import type { HoundsmanConfig } from "./config";
+
+/** Nomes de arquivo procurados no cwd, em ordem de precedência. */
+export const CONFIG_FILE_CANDIDATES: readonly string[] = [
+	"houndsman.config.ts",
+	"houndsman.config.mts",
+	"houndsman.config.js",
+	"houndsman.config.mjs",
+	".houndsman/config.ts",
+	".houndsman/config.js",
+];
+
+export type LoadedConfig<TId extends string = string> = {
+	config: HoundsmanConfig<TId>;
+	/** Caminho absoluto do arquivo de config carregado. */
+	path: string;
+};
+
+/** Primeiro arquivo de config existente no diretório (ou `null`). */
+export function resolveConfigPath(cwd: string = process.cwd()): string | null {
+	for (const name of CONFIG_FILE_CANDIDATES) {
+		const candidate = join(cwd, name);
+		if (existsSync(candidate)) return candidate;
+	}
+	return null;
+}
+
+const MISSING_CONFIG_HINT =
+	"Nenhuma configuração do houndsman encontrada.\n" +
+	`Esperado: ${CONFIG_FILE_CANDIDATES.join(" | ")} na raiz do projeto.\n` +
+	"Rode `houndsman setup` para criar uma configuração inicial.";
+
+/**
+ * Carrega o `HoundsmanConfig` do projeto. Lança se ausente ou inválido.
+ * `configPath` sobrepõe a descoberta automática.
+ */
+export async function loadConfig<TId extends string = string>(
+	options: { cwd?: string; configPath?: string } = {},
+): Promise<LoadedConfig<TId>> {
+	const cwd = options.cwd ?? process.cwd();
+	const path = options.configPath
+		? resolve(cwd, options.configPath)
+		: resolveConfigPath(cwd);
+
+	if (!path || !existsSync(path)) {
+		throw new Error(MISSING_CONFIG_HINT);
+	}
+
+	const module = (await import(pathToFileURL(path).href)) as {
+		default?: HoundsmanConfig<TId>;
+		houndsmanConfig?: HoundsmanConfig<TId>;
+	};
+	const config = module.default ?? module.houndsmanConfig;
+
+	if (!config) {
+		throw new Error(
+			`Configuração inválida em ${path}: exporte \`export default houndsmanConfig\`.`,
+		);
+	}
+	if (!config.watchdogs || typeof config.watchdogs !== "object") {
+		throw new Error(`Configuração inválida em ${path}: campo 'watchdogs' ausente.`);
+	}
+	// Deriva `watchdogIds` de quem não passou por `defineHoundsmanConfig` (ex.: objeto
+	// literal) — mantém o motor robusto a configs escritas à mão.
+	if (!Array.isArray(config.watchdogIds)) {
+		(config as unknown as { watchdogIds: string[] }).watchdogIds = Object.keys(
+			config.watchdogs,
+		);
+	}
+
+	return { config, path };
+}

package/src/core/config.ts

@@ -0,0 +1,101 @@
+/**
+ * Contrato de configuração do motor de revisão (houndsman) — biblioteca.
+ *
+ * O motor (`core/` + `cli/`) é agnóstico ao projeto: consome um `HoundsmanConfig`
+ * por injeção explícita. O projeto fornece a config em `houndsman.config.ts`
+ * (camada `houndsman/`) — único ponto de troca ao portar para outro repositório.
+ */
+
+import { ARTIFACT_DIR } from "./paths";
+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.
+ *
+ * `TId` é o union de ids de watchdog do projeto (ex.: `WatchdogId`).
+ */
+export type HoundsmanConfig<TId extends string = string> = {
+	/** Nome legível do projeto (usado em prompts e docs). */
+	projectName: string;
+	/** Diretório dos artefatos (default: `ARTIFACT_DIR` da camada). */
+	artifactDir?: string;
+	/**
+	 * Ids dos watchdogs — **derivados** das chaves de `watchdogs` por
+	 * `defineHoundsmanConfig` (não informar manualmente).
+	 */
+	watchdogIds: readonly TId[];
+	/** Definições dos watchdogs do projeto (fonte dos ids). */
+	watchdogs: Record<TId, WatchdogDefinition>;
+	/** Arquivos que nunca entram na revisão. */
+	exclusions: readonly RegExp[];
+	/** Mapeamentos path → documentação relevante. */
+	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. */
+export type HoundsmanConfigInput<TId extends string = string> = Omit<
+	HoundsmanConfig<TId>,
+	"watchdogIds"
+>;
+
+/**
+ * Helper de autoria: **deriva `watchdogIds`** das chaves de `watchdogs`
+ * (fonte única) e preserva a inferência de `TId`.
+ */
+export function defineHoundsmanConfig<TId extends string>(
+	input: HoundsmanConfigInput<TId>,
+): HoundsmanConfig<TId> {
+	return { ...input, watchdogIds: Object.keys(input.watchdogs) as TId[] };
+}
+
+/** Diretório dos artefatos — o valor do projeto ou o default da camada. */
+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. Substitui os N spawns de
+ * `git diff -- <arquivo>` (antes feitos por arquivo, no `jev-detector`): o custo
+ * deixa de crescer 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;
+};
+
+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/doc-discoverer.ts

@@ -0,0 +1,33 @@
+/**
+ * Descobre documentação relevante para um conjunto de arquivos alterados
+ * (biblioteca). Entrypoint: `cli/review.ts`.
+ *
+ * Os mapeamentos (`docMappings`) e os docs sempre incluídos vivem no projeto
+ * (`project/doc-mappings.ts`) e chegam via `HoundsmanConfig`.
+ */
+
+import { DEFAULT_ALWAYS_INCLUDE_DOCS, type HoundsmanConfig } from "./config";
+
+/** Descobre docs relevantes com base nos paths + docs sempre incluídos. */
+export function discoverDocs(filePaths: string[], config: HoundsmanConfig): string[] {
+	const docs = new Set<string>();
+
+	for (const doc of config.alwaysIncludeDocs ?? DEFAULT_ALWAYS_INCLUDE_DOCS) {
+		docs.add(doc);
+	}
+
+	for (const filePath of filePaths) {
+		const normalized = filePath.trim().toLowerCase();
+		if (!normalized) continue;
+
+		for (const [pattern, docPaths] of config.docMappings) {
+			if (pattern.test(normalized)) {
+				for (const docPath of docPaths) {
+					docs.add(docPath);
+				}
+			}
+		}
+	}
+
+	return [...docs].sort();
+}

package/src/core/file-classifier.ts

@@ -0,0 +1,295 @@
+/**
+ * Classificação de arquivos alterados por domínio de review (biblioteca).
+ *
+ * Cada watchdog declara os arquivos que cobre (`classify`); exclusões chegam via
+ * `HoundsmanConfig`. Use `classifyRange(base, head, config)`.
+ */
+
+import { readFileSync } from "node:fs";
+import type { HoundsmanConfig } from "./config";
+import { churnToRecord, collectChurn, type DiffSource } from "./diff-source";
+import type { ChurnMap, ClassifyRule, WatchdogDefinition } from "./types";
+
+type FileStatus = "added" | "modified" | "deleted" | "renamed" | "copied" | "unknown";
+
+type FileEntry = {
+	path: string;
+	status: FileStatus;
+	oldPath?: string;
+};
+
+export type ClassificationResult = {
+	/** watchdogId → file paths (apenas arquivos revisáveis) */
+	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) */
+	excluded: string[];
+	/** Arquivos deletados — candidatos a breaking change, sem conteúdo para ler */
+	deleted: string[];
+	/** Estatísticas por watchdog */
+	stats: Record<string, number>;
+	excludedCount: number;
+	base?: string;
+	head?: string;
+};
+
+// ---------------------------------------------------------------------------
+// Matchers genéricos (reutilizados pelo projeto)
+// ---------------------------------------------------------------------------
+
+/** Tipo de classificação assumido quando `type` é omitido. */
+const DEFAULT_CLASSIFY_TYPE: NonNullable<ClassifyRule["type"]> = "filename";
+
+/** `true` se há entradas de conteúdo (as únicas que exigem ler o arquivo). */
+function hasContentRules<TId extends string>(
+	watchdogs: Record<TId, WatchdogDefinition>,
+	watchdogIds: readonly TId[],
+): boolean {
+	return watchdogIds.some((id) =>
+		watchdogs[id]?.classify?.some((rule) => rule.type === "content"),
+	);
+}
+
+/** Lê o arquivo em UTF-8; `undefined` se indisponível (binário, ausente). */
+function readFileContent(filePath: string): string | undefined {
+	try {
+		return readFileSync(filePath, "utf8");
+	} catch {
+		return undefined;
+	}
+}
+
+/** `true` se o arquivo casa a entrada de classificação. */
+function matchesClassifyRule(
+	filePath: string,
+	rule: ClassifyRule,
+	content: string | undefined,
+): boolean {
+	if ((rule.type ?? DEFAULT_CLASSIFY_TYPE) === "content") {
+		return content !== undefined && new RegExp(rule.value).test(content);
+	}
+	return new RegExp(rule.value).test(filePath);
+}
+
+/** Watchdogs que declaram o arquivo (união dos `classify`). */
+export function matchWatchdogs<TId extends string>(
+	filePath: string,
+	watchdogs: Record<TId, WatchdogDefinition>,
+	watchdogIds: readonly TId[],
+	content?: string,
+): TId[] {
+	const ids: TId[] = [];
+	for (const id of watchdogIds) {
+		if (
+			watchdogs[id]?.classify?.some((rule) =>
+				matchesClassifyRule(filePath, rule, content),
+			)
+		) {
+			ids.push(id);
+		}
+	}
+	return ids;
+}
+
+/** `true` se o arquivo casa algum padrão de exclusão. */
+export function isExcludedPath(filePath: string, patterns: readonly RegExp[]): boolean {
+	return patterns.some((pattern) => pattern.test(filePath));
+}
+
+// ---------------------------------------------------------------------------
+// Execução do git diff
+// ---------------------------------------------------------------------------
+
+function runGitDiff(base: string, head: string): string {
+	const result = Bun.spawnSync(["git", "diff", `${base}...${head}`, "--name-status"], {
+		stdout: "pipe",
+		stderr: "pipe",
+	});
+	if (result.exitCode !== 0) {
+		const stderr = new TextDecoder().decode(result.stderr).trim();
+		throw new Error(`git diff falhou (base='${base}', head='${head}'): ${stderr}`);
+	}
+	return new TextDecoder().decode(result.stdout);
+}
+
+// ---------------------------------------------------------------------------
+// Parsing de `git diff --name-status`
+// ---------------------------------------------------------------------------
+
+function mapStatus(code: string): FileStatus {
+	const letter = code[0]?.toUpperCase();
+	switch (letter) {
+		case "A":
+			return "added";
+		case "M":
+			return "modified";
+		case "D":
+			return "deleted";
+		case "R":
+			return "renamed";
+		case "C":
+			return "copied";
+		default:
+			return "unknown";
+	}
+}
+
+export function parseEntries(raw: string): FileEntry[] {
+	const entries: FileEntry[] = [];
+	for (const line of raw.split("\n")) {
+		const trimmed = line.trim();
+		if (!trimmed) continue;
+
+		const fields = trimmed.split("\t");
+		if (fields.length === 1) {
+			// Sem status — assume modificado
+			entries.push({ path: fields[0].trim(), status: "modified" });
+			continue;
+		}
+
+		const status = mapStatus(fields[0].trim());
+		if (fields.length >= 3 && (status === "renamed" || status === "copied")) {
+			// R100\told\tnew
+			entries.push({ path: fields[2].trim(), oldPath: fields[1].trim(), status });
+		} else {
+			entries.push({ path: fields[1].trim(), status });
+		}
+	}
+	return entries;
+}
+
+// ---------------------------------------------------------------------------
+// Classificação
+// ---------------------------------------------------------------------------
+
+export function classifyEntries<TId extends string>(
+	entries: FileEntry[],
+	config: HoundsmanConfig<TId>,
+	churn: ChurnMap = {},
+): ClassificationResult {
+	const watchdogFiles: Record<string, string[]> = {};
+	const files: ClassificationResult["files"] = {};
+	const unclassified: string[] = [];
+	const excluded: string[] = [];
+	const deleted: string[] = [];
+	// Leitura de conteúdo só é habilitada se algum watchdog declarar regra `content`.
+	const needsContent = hasContentRules(config.watchdogs, config.watchdogIds);
+
+	for (const entry of entries) {
+		const { path, status, oldPath } = entry;
+		files[path] = oldPath ? { status, oldPath } : { status };
+
+		if (isExcludedPath(path, config.exclusions)) {
+			excluded.push(path);
+			continue;
+		}
+
+		if (status === "deleted") {
+			// Sem conteúdo para revisar — exposto separadamente p/ checagem de breaking change
+			deleted.push(path);
+			continue;
+		}
+
+		const content = needsContent ? readFileContent(path) : undefined;
+		const ids: string[] = matchWatchdogs(
+			path,
+			config.watchdogs,
+			config.watchdogIds,
+			content,
+		);
+
+		if (ids.length === 0) {
+			unclassified.push(path);
+			continue;
+		}
+
+		for (const id of ids) {
+			watchdogFiles[id] ??= [];
+			watchdogFiles[id].push(path);
+		}
+	}
+
+	const watchdogs: Record<string, string[]> = {};
+	const stats: Record<string, number> = {};
+	for (const id of config.watchdogIds) {
+		const list = [...new Set(watchdogFiles[id] ?? [])];
+		if (list.length > 0) {
+			watchdogs[id] = list;
+			stats[id] = list.length;
+		}
+	}
+
+	return {
+		watchdogs,
+		files,
+		churn,
+		unclassified,
+		excluded,
+		deleted,
+		stats,
+		excludedCount: excluded.length,
+	};
+}
+
+/**
+ * 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 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) };
+}