@payconductor/houndsman 0.0.0-stage → 0.1.1

package/src/core/commands/scaffold.ts

@@ -0,0 +1,393 @@
+/**
+ * Scaffold da camada de projeto (`.houndsman/`) — templates e helpers.
+ *
+ * Separa o que é **auto-gerado** (sincronizável com `houndsman update`) do que é
+ * **do usuário**:
+ *
+ *   .houndsman/
+ *   ├── .gitignore          AUTO — ignora core/ e .runs/ (gerados/temporários)
+ *   ├── core/types.ts       AUTO — snapshot dos tipos + helpers
+ *   ├── core/skill/*.md     AUTO — docs do skill (com {{projectName}} resolvido)
+ *   ├── watchdogs/*.ts      USUÁRIO
+ *   ├── doc-mappings.ts     USUÁRIO
+ *   └── exclusions.ts       USUÁRIO
+ */
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { SKILL_DIR } from "../assets";
+import {
+	ARTIFACT_DIR,
+	CORE_DIR,
+	CORE_SKILL_DIR,
+	OUTPUT_FORMAT_PATH,
+	PROJECT_DIR,
+} from "../paths";
+
+export type Harness = "agents" | "claude";
+
+export type ScaffoldContext = {
+	cwd: string;
+	projectName: string;
+	harnesses: Harness[];
+	/** Sobrescreve também os arquivos do usuário (só o `setup --force`). */
+	force: boolean;
+	/** Arquivos do usuário criados/sobrescritos. */
+	created: string[];
+	/** Arquivos auto-gerados (re)escritos. */
+	generated: string[];
+	/** Arquivos do usuário mantidos (já existiam). */
+	skipped: string[];
+};
+
+function readFlag(args: string[], flag: string): string | undefined {
+	const index = args.indexOf(flag);
+	return index >= 0 ? args[index + 1] : undefined;
+}
+
+/** Resolve os harnesses a configurar a partir de `--harness`. */
+export function resolveHarnesses(args: string[]): Harness[] {
+	const raw = readFlag(args, "--harness");
+	if (!raw || raw === "both") return ["agents", "claude"];
+	if (raw === "none") return [];
+	return raw
+		.split(",")
+		.map((value) => value.trim())
+		.filter((value): value is Harness => value === "agents" || value === "claude");
+}
+
+/** Monta o contexto do scaffold (nome do projeto, harnesses, flags). */
+export function createScaffoldContext(
+	cwd: string,
+	args: string[],
+	force: boolean,
+): ScaffoldContext {
+	return {
+		cwd,
+		projectName: readFlag(args, "--name") ?? basename(cwd),
+		harnesses: resolveHarnesses(args),
+		force,
+		created: [],
+		generated: [],
+		skipped: [],
+	};
+}
+
+// ---------------------------------------------------------------------------
+// Templates
+// ---------------------------------------------------------------------------
+
+const CONFIG_TEMPLATE = (
+	projectName: string,
+): string => `import { DOC_MAPPINGS } from "./${PROJECT_DIR}/doc-mappings";
+import { EXCLUSION_PATTERNS } from "./${PROJECT_DIR}/exclusions";
+import { WATCHDOG_DEFINITIONS } from "./${PROJECT_DIR}/watchdogs";
+import type { HoundsmanConfig } from "./${CORE_DIR}/types";
+
+/**
+ * Configuração do houndsman para ${projectName}.
+ *
+ * Caminhos são resolvidos pela camada: artefatos em ${ARTIFACT_DIR} e schema de
+ * output em ${OUTPUT_FORMAT_PATH}. Ajuste watchdogs, exclusões e mapeamentos de
+ * docs conforme o projeto.
+ */
+export const houndsmanConfig = {
+	projectName: "${projectName}",
+	watchdogs: WATCHDOG_DEFINITIONS,
+	exclusions: EXCLUSION_PATTERNS,
+	docMappings: DOC_MAPPINGS,
+} satisfies HoundsmanConfig;
+
+export default houndsmanConfig;
+`;
+
+const TYPES_TEMPLATE = `/**
+ * Tipos e helpers locais do houndsman (GERADO — não edite).
+ *
+ * Snapshot do contrato público, para tipar a camada de projeto sem depender de um
+ * install local do pacote. Sincronize com \`houndsman update\`.
+ */
+
+export type Severity = "blocking" | "attention" | "suggestion" | "nit";
+
+/** Tipo de pergunta aceito pela API Jev. */
+export type JevQuestionType = "noul" | "choice" | "score";
+
+/**
+ * Spec de pré-análise Jev (opcional) — sempre um objeto; \`kind\` é obrigatório.
+ * \`criteria\`: objeto para \`choice\`, lista para \`score\`.
+ */
+export type JevRuleSpec = {
+	kind: JevQuestionType;
+	instructions?: string;
+	criteria?: string[] | Record<string, string>;
+};
+
+/** Regra do watchdog: severidade + texto — o texto declara a polaridade
+ *  (\`Promover:\` = deve acontecer; \`Evitar:\`/\`Não\`/\`Nunca\` = não deve acontecer). */
+export type Rule = {
+	severity: Severity;
+	text: string;
+	jev?: JevRuleSpec;
+};
+
+/** Como o watchdog casa um arquivo alterado. \`value\` é sempre regex. */
+export type ClassifyRule = {
+	type?: "filename" | "content";
+	value: string;
+};
+
+export type WatchdogMeta = {
+	name: string;
+	scope: string;
+	classify?: readonly ClassifyRule[];
+	rules: readonly Rule[];
+	contextFiles: string[];
+};
+
+/** Definição completa de um watchdog — 1 por arquivo em \`${PROJECT_DIR}/watchdogs/\`. */
+export type WatchdogDefinition = WatchdogMeta & {
+	id: string;
+	description: string;
+	breakingChange?: boolean;
+	reviewFocus?: readonly string[];
+	exclude?: readonly string[];
+};
+
+export type FileStatus =
+	| "added"
+	| "modified"
+	| "deleted"
+	| "renamed"
+	| "copied"
+	| "unknown";
+
+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;
+	artifactDir?: string;
+	watchdogIds?: readonly TId[];
+	watchdogs: Record<TId, WatchdogDefinition>;
+	exclusions: readonly RegExp[];
+	docMappings: readonly (readonly [RegExp, readonly string[]])[];
+	alwaysIncludeDocs?: readonly string[];
+	budgets?: HoundsmanBudgets;
+	concurrency?: HoundsmanConcurrency;
+};
+
+/** Helper de autoria (identidade) — apenas tipagem. */
+export function defineWatchdog(definition: WatchdogDefinition): WatchdogDefinition {
+	return definition;
+}
+
+/** Helper de autoria — deriva \`watchdogIds\` das chaves de \`watchdogs\`. */
+export function defineHoundsmanConfig<TId extends string>(
+	input: Omit<HoundsmanConfig<TId>, "watchdogIds">,
+): HoundsmanConfig<TId> {
+	return { ...input, watchdogIds: Object.keys(input.watchdogs) as TId[] };
+}
+`;
+
+const WATCHDOG_EXAMPLE = `import { defineWatchdog } from "../core/types";
+
+/**
+ * Watchdog de exemplo — substitua pelas regras reais do projeto.
+ * Um watchdog declara seus arquivos via \`classify\` (regex de path ou conteúdo).
+ * O texto de cada regra começa com a polaridade: \`Promover:\` (DEVE acontecer)
+ * ou \`Evitar:\`/\`Não\`/\`Nunca\` (NÃO DEVE acontecer).
+ */
+export const exampleWatchdog = defineWatchdog({
+	id: "example",
+	name: "Exemplo",
+	description: "Watchdog de exemplo — descreva o propósito em uma frase.",
+	scope: "Todo o repositório (ajuste o escopo)",
+	classify: [{ value: "^src/" }],
+	rules: [
+		{
+			severity: "attention",
+			text: "Promover: descreva aqui um padrão do projeto (algo que DEVE acontecer).",
+			jev: { kind: "noul" },
+		},
+		{
+			severity: "nit",
+			text: "Evitar: descreva aqui um anti-padrão (algo que NÃO DEVE acontecer).",
+		},
+	],
+	contextFiles: ["AGENTS.md"],
+});
+`;
+
+const WATCHDOGS_INDEX = `import { exampleWatchdog } from "./example";
+
+/**
+ * Definições dos watchdogs — as chaves definem o union \`WatchdogId\`.
+ * Adicionar um watchdog = criar \`<id>.ts\` e registrá-lo aqui.
+ */
+export const WATCHDOG_DEFINITIONS = {
+	example: exampleWatchdog,
+};
+
+export type WatchdogId = keyof typeof WATCHDOG_DEFINITIONS;
+`;
+
+const EXCLUSIONS_TEMPLATE = `/** Arquivos que nunca entram na revisão — gerados, locks, builds. */
+export const EXCLUSION_PATTERNS: readonly RegExp[] = [
+	/bun\\.lockb?$/,
+	/^package-lock\\.json$/,
+	/^dist\\//,
+	/^build\\//,
+];
+
+/** \`true\` se o caminho é excluído da revisão. */
+export function isExcluded(filePath: string): boolean {
+	return EXCLUSION_PATTERNS.some((pattern) => pattern.test(filePath));
+}
+`;
+
+const DOC_MAPPINGS_TEMPLATE = `/**
+ * Mapeamento de padrões nos paths → documentação relevante.
+ * Consumido pelo motor via \`HoundsmanConfig.docMappings\`.
+ */
+export const DOC_MAPPINGS: readonly (readonly [RegExp, readonly string[]])[] = [
+	[/^src\\//, ["AGENTS.md"]],
+];
+`;
+
+const PROJECT_GITIGNORE = `# Diretórios gerados pelo houndsman — \`core/\` é regenerado por \`houndsman update\`
+# e \`.runs/\` guarda os artefatos de revisão.
+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
+// ---------------------------------------------------------------------------
+
+/** Escreve um arquivo do usuário somente se ausente (ou se `force`). */
+function writeUserFile(
+	ctx: ScaffoldContext,
+	relativePath: string,
+	content: string,
+): void {
+	const full = join(ctx.cwd, relativePath);
+	if (existsSync(full) && !ctx.force) {
+		ctx.skipped.push(relativePath);
+		return;
+	}
+	mkdirSync(join(full, ".."), { recursive: true });
+	writeFileSync(full, content);
+	ctx.created.push(relativePath);
+}
+
+/** Escreve/sobrescreve um arquivo auto-gerado. */
+function writeGeneratedFile(
+	ctx: ScaffoldContext,
+	relativePath: string,
+	content: string,
+): void {
+	const full = join(ctx.cwd, relativePath);
+	mkdirSync(join(full, ".."), { recursive: true });
+	writeFileSync(full, content);
+	ctx.generated.push(relativePath);
+}
+
+// ---------------------------------------------------------------------------
+// Camadas
+// ---------------------------------------------------------------------------
+
+/** Arquivos do usuário: config, watchdogs, exclusões e mapeamentos. */
+export function writeUserLayer(ctx: ScaffoldContext): void {
+	writeUserFile(ctx, "houndsman.config.ts", CONFIG_TEMPLATE(ctx.projectName));
+	writeUserFile(ctx, join(PROJECT_DIR, "watchdogs", "example.ts"), WATCHDOG_EXAMPLE);
+	writeUserFile(ctx, join(PROJECT_DIR, "watchdogs", "index.ts"), WATCHDOGS_INDEX);
+	writeUserFile(ctx, join(PROJECT_DIR, "exclusions.ts"), EXCLUSIONS_TEMPLATE);
+	writeUserFile(ctx, join(PROJECT_DIR, "doc-mappings.ts"), DOC_MAPPINGS_TEMPLATE);
+}
+
+/**
+ * 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`).
+ */
+export function syncGeneratedFiles(ctx: ScaffoldContext): void {
+	writeGeneratedFile(ctx, join(CORE_DIR, "types.ts"), TYPES_TEMPLATE);
+	writeGeneratedFile(ctx, join(PROJECT_DIR, ".gitignore"), PROJECT_GITIGNORE);
+
+	for (const name of readdirSync(SKILL_DIR)) {
+		if (!name.endsWith(".md")) continue;
+		const raw = readFileSync(join(SKILL_DIR, name), "utf8");
+		writeGeneratedFile(
+			ctx,
+			join(CORE_SKILL_DIR, name),
+			raw.replaceAll("{{projectName}}", ctx.projectName),
+		);
+	}
+
+	for (const harness of ctx.harnesses) writeHarnessPointers(ctx, harness);
+}
+
+/** Escreve os ponteiros de skill de um harness. */
+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)",
+		),
+	);
+	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)",
+		),
+	);
+}

package/src/core/commands/setup.ts

@@ -0,0 +1,75 @@
+/**
+ * Subcomando `setup` — cria a configuração inicial do houndsman no projeto.
+ *
+ * Gera a camada `.houndsman/`: arquivos do usuário (config, watchdogs, exclusões,
+ * mapeamentos) + arquivos auto-gerados (tipos, skill, `.houndsman/.gitignore`,
+ * ponteiros de harness). O `houndsman update` sincroniza só os auto-gerados.
+ *
+ * A camada é **autocontida** — não importa o pacote `@payconductor/houndsman` em
+ * runtime, o que permite instalar o CLI **globalmente** e usar `bun run houndsman`
+ * sem dependência local no projeto.
+ *
+ * Idempotente: arquivos do usuário só são sobrescritos com `--force`.
+ */
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+	createScaffoldContext,
+	type ScaffoldContext,
+	syncGeneratedFiles,
+	writeUserLayer,
+} from "./scaffold";
+
+export type SetupOptions = {
+	cwd: string;
+	args: string[];
+};
+
+/**
+ * Garante o script `houndsman` no `package.json` do projeto (para
+ * `bun run houndsman [...]`), sem reformatar o restante do arquivo.
+ */
+function ensurePackageScript(ctx: ScaffoldContext): void {
+	const pkgPath = join(ctx.cwd, "package.json");
+	if (!existsSync(pkgPath)) return;
+
+	const raw = readFileSync(pkgPath, "utf8");
+	if (raw.includes('"houndsman"')) {
+		ctx.skipped.push("package.json#scripts.houndsman");
+		return;
+	}
+	const scriptsBlock = /"scripts"\s*:\s*\{/;
+	if (!scriptsBlock.test(raw)) return;
+
+	writeFileSync(
+		pkgPath,
+		raw.replace(scriptsBlock, (match) => `${match}\n\t\t"houndsman": "houndsman",`),
+	);
+	ctx.created.push("package.json#scripts.houndsman");
+}
+
+/** Cria a configuração inicial do projeto. */
+export async function runSetupCommand(options: SetupOptions): Promise<void> {
+	const ctx = createScaffoldContext(
+		options.cwd,
+		options.args,
+		options.args.includes("--force"),
+	);
+
+	console.log(`→ Configurando houndsman em ${ctx.cwd} (projeto: ${ctx.projectName})`);
+
+	writeUserLayer(ctx);
+	syncGeneratedFiles(ctx);
+	ensurePackageScript(ctx);
+
+	for (const path of ctx.created) console.log(`  + ${path}`);
+	for (const path of ctx.skipped) console.log(`  = ${path} (mantido)`);
+	for (const path of ctx.generated) console.log(`  ~ ${path} (auto)`);
+
+	console.log("\nPróximos passos:");
+	console.log("  1. Ajuste `houndsman.config.ts` e `.houndsman/watchdogs/`.");
+	console.log("  2. Valide: bun run houndsman doctor");
+	console.log("  3. Prepare a revisão: bun run houndsman");
+	console.log("  ·  Sincronizar arquivos auto-gerados: bun run houndsman update");
+}

package/src/core/commands/test.ts

@@ -0,0 +1,20 @@
+/**
+ * Subcomando `test` — roda a suíte de testes da lib (project-agnóstica).
+ *
+ * A suíte vive em `src/tests/` e usa um "project fake"; o adotante
+ * da lib não precisa escrever testes.
+ */
+
+import { join } from "node:path";
+
+/** Diretório da suíte de testes da lib (independente do projeto). */
+export const LIB_TESTS_DIR = join(import.meta.dir, "..", "..", "tests");
+
+/** Roda a suíte de testes da lib. Devolve o exit code. */
+export function runLibTests(): number {
+	const result = Bun.spawnSync(["bun", "test", LIB_TESTS_DIR], {
+		stdout: "inherit",
+		stderr: "inherit",
+	});
+	return result.exitCode ?? 1;
+}

package/src/core/commands/update.ts

@@ -0,0 +1,30 @@
+/**
+ * Subcomando `update` — sincroniza os arquivos **auto-gerados** da camada `.houndsman/`.
+ *
+ * Reescreve `core/types.ts`, `core/skill/*.md`, `.houndsman/.gitignore` e os
+ * ponteiros de skill dos harnesses. Nunca toca nos arquivos do usuário
+ * (`watchdogs/`, `doc-mappings.ts`, `exclusions.ts`, `houndsman.config.ts`).
+ */
+
+import { createScaffoldContext, syncGeneratedFiles } from "./scaffold";
+
+export type UpdateOptions = {
+	cwd: string;
+	args: string[];
+};
+
+/** Sincroniza os arquivos auto-gerados da camada de projeto. */
+export async function runUpdateCommand(options: UpdateOptions): Promise<void> {
+	const ctx = createScaffoldContext(options.cwd, options.args, false);
+
+	console.log(`→ Sincronizando arquivos auto-gerados em ${ctx.cwd}`);
+
+	syncGeneratedFiles(ctx);
+
+	for (const path of ctx.generated) console.log(`  ~ ${path} (auto)`);
+
+	console.log("\nArquivos do usuário não foram tocados:");
+	console.log(
+		"  .houndsman/watchdogs/ · exclusions.ts · doc-mappings.ts · houndsman.config.ts",
+	);
+}

package/src/core/commands/watchdog.ts

@@ -0,0 +1,105 @@
+/**
+ * Subcomando `watchdog` — contexto de um watchdog (biblioteca).
+ *
+ * Devolve o texto pronto (markdown ou JSON); `null` se o id não existe.
+ * O CLI decide o log/exit.
+ */
+
+import type { HoundsmanConfig } from "../config";
+import {
+	type Rule,
+	SEVERITY_EMOJI,
+	severityRank,
+	type WatchdogDefinition,
+} from "../types";
+import { findWatchdog, getWatchdogContext } from "../watchdog-registry";
+
+export type WatchdogContextOptions = {
+	/** Inclui `criticalRules` + `antiPatterns`. */
+	withRules?: boolean;
+	/** Saída JSON (default: markdown legível). */
+	json?: boolean;
+};
+
+type WatchdogContext = ReturnType<typeof getWatchdogContext>;
+
+/** Renderiza o contexto de um watchdog (markdown ou JSON). `null` se o id não existe. */
+export function renderWatchdogContext(
+	config: HoundsmanConfig,
+	id: string,
+	opts: WatchdogContextOptions = {},
+): string | null {
+	const def = findWatchdog(config, id);
+	if (!def) return null;
+	const ctx = getWatchdogContext(config, def.id);
+	const withRules = opts.withRules ?? false;
+	return opts.json
+		? serializeWatchdogContext(ctx, def, withRules)
+		: renderWatchdogMarkdown(ctx, def, withRules);
+}
+
+/** Payload serializável (regras incluídas apenas com `withRules`). */
+function serializeWatchdogContext(
+	ctx: WatchdogContext,
+	def: WatchdogDefinition,
+	withRules: boolean,
+): string {
+	const payload = withRules ? { ...ctx, rules: def.rules } : { ...ctx };
+	return JSON.stringify(payload, null, 2);
+}
+
+/** Lista de itens em bloco `## <título>` (vazio se não houver itens). */
+function section(title: string, items: readonly string[] | undefined): string[] {
+	if (!items || items.length === 0) return [];
+	return [`## ${title}`, "", ...items.map((item) => `- ${item}`), ""];
+}
+
+/** Regras com emoji de severidade em bloco `## <título>`. */
+function ruleSection(title: string, rules: readonly Rule[]): string[] {
+	return [
+		`## ${title}`,
+		"",
+		...rules.map(
+			(rule) =>
+				`- ${SEVERITY_EMOJI[rule.severity]} **${rule.severity}** — ${rule.text}`,
+		),
+		"",
+	];
+}
+
+/** Render markdown legível do contexto do watchdog. */
+function renderWatchdogMarkdown(
+	ctx: WatchdogContext,
+	def: WatchdogDefinition,
+	withRules: boolean,
+): string {
+	const lines: string[] = [
+		`# ${ctx.name} (\`${ctx.id}\`)`,
+		"",
+		`**Descrição:** ${ctx.description}`,
+		`**Escopo:** ${ctx.scope}`,
+		"",
+	];
+
+	lines.push(...section("Prioridade de leitura", ctx.reviewFocus));
+	lines.push(...section("Não carregar", ctx.exclude));
+	lines.push(
+		...section(
+			"Docs de contexto",
+			ctx.contextFiles.map((doc) => `\`${doc}\``),
+		),
+	);
+
+	if (withRules) {
+		lines.push(
+			...ruleSection(
+				"Regras",
+				[...def.rules].sort(
+					(a, b) => severityRank(a.severity) - severityRank(b.severity),
+				),
+			),
+		);
+	}
+
+	return lines.join("\n").trimEnd();
+}