@payconductor/houndsman 0.5.0 → 0.7.0

package/src/harness/tools/builtin/imports-exports-tool.ts

@@ -0,0 +1,53 @@
+/**
+ * Tool `imports_exports` — imports, exports e decorators de um arquivo.
+ */
+
+import { z } from "zod";
+import type { AgentTool, ToolMetadata, ToolResult } from "../agent-tool";
+import { PathGuard } from "../path-guard";
+
+const Input = z.object({ file: z.string().min(1) });
+
+/** Lista estrutural do arquivo. */
+export class ImportsExportsTool implements AgentTool<z.infer<typeof Input>, unknown> {
+	readonly metadata: ToolMetadata = {
+		name: "imports_exports",
+		description: "Imports, exports e decorators de um arquivo (AST).",
+		category: "ast",
+		capabilities: ["ast"],
+		readOnly: true,
+		cost: 2,
+		cacheTtlMs: 120_000,
+	};
+
+	readonly inputSchema = Input;
+
+	async execute(
+		input: z.infer<typeof Input>,
+		context: import("../tool-context").ToolContext,
+	): Promise<ToolResult<unknown>> {
+		const guard = new PathGuard(context.repoRoot);
+		let path: string;
+		try {
+			path = guard.relativePath(input.file);
+		} catch (error) {
+			return {
+				ok: false,
+				error: error instanceof Error ? error.message : String(error),
+			};
+		}
+		const facts = await context.ast.factsOf(path);
+		if (!facts) {
+			return { ok: false, error: "AST indisponível para este arquivo." };
+		}
+		return {
+			ok: true,
+			data: {
+				file: path,
+				imports: facts.imports,
+				exports: facts.exports,
+				decorators: facts.decorators,
+			},
+		};
+	}
+}

package/src/harness/tools/builtin/index.ts

@@ -0,0 +1,59 @@
+/**
+ * Registro das tools built-in do harness.
+ *
+ * Adicionar uma tool = criar a classe + registrar aqui + contract test. O
+ * `ReviewAgent` não muda.
+ */
+
+import type { ToolModule, ToolRegistryLike } from "../agent-tool";
+import { ChangedSymbolsTool } from "./changed-symbols-tool";
+import { DocContextTool } from "./doc-context-tool";
+import { FileOutlineTool } from "./file-outline-tool";
+import { FindReferencesTool } from "./find-references-tool";
+import { FindSymbolTool } from "./find-symbol-tool";
+import { ImpactTool } from "./impact-tool";
+import { ImportsExportsTool } from "./imports-exports-tool";
+import { ListFilesTool } from "./list-files-tool";
+import { PrContextTool } from "./pr-context-tool";
+import { ReadFileRangeTool } from "./read-file-range-tool";
+import { RuleSignalsTool } from "./rule-signals-tool";
+import { SearchCodeTool } from "./search-code-tool";
+import { SymbolContextTool } from "./symbol-context-tool";
+import { TestsForSymbolTool } from "./tests-for-symbol-tool";
+
+/** Módulo com todas as tools read-only. */
+export class BuiltinToolsModule implements ToolModule {
+	register(registry: ToolRegistryLike): void {
+		registry.registerTool(new PrContextTool());
+		registry.registerTool(new ListFilesTool());
+		registry.registerTool(new FileOutlineTool());
+		registry.registerTool(new ReadFileRangeTool());
+		registry.registerTool(new SearchCodeTool());
+		registry.registerTool(new FindSymbolTool());
+		registry.registerTool(new FindReferencesTool());
+		registry.registerTool(new SymbolContextTool());
+		registry.registerTool(new ChangedSymbolsTool());
+		registry.registerTool(new ImpactTool());
+		registry.registerTool(new ImportsExportsTool());
+		registry.registerTool(new RuleSignalsTool());
+		registry.registerTool(new TestsForSymbolTool());
+		registry.registerTool(new DocContextTool());
+	}
+}
+
+export {
+	ChangedSymbolsTool,
+	DocContextTool,
+	FileOutlineTool,
+	FindReferencesTool,
+	FindSymbolTool,
+	ImpactTool,
+	ImportsExportsTool,
+	ListFilesTool,
+	PrContextTool,
+	ReadFileRangeTool,
+	RuleSignalsTool,
+	SearchCodeTool,
+	SymbolContextTool,
+	TestsForSymbolTool,
+};

package/src/harness/tools/builtin/list-files-tool.ts

@@ -0,0 +1,85 @@
+/**
+ * Tool `list_files` — lista arquivos do repositório (mapa, não conteúdo).
+ */
+
+import { z } from "zod";
+import { runGit } from "../../../core/git-runner";
+import type { AgentTool, ToolMetadata, ToolResult } from "../agent-tool";
+import { TOOL_LIMITS } from "../result-limiter";
+
+const Input = z.object({
+	directory: z.string().optional(),
+	glob: z.string().optional(),
+});
+
+/** Lista até 200 arquivos rastreados pelo git. */
+export class ListFilesTool implements AgentTool<z.infer<typeof Input>, string[]> {
+	readonly metadata: ToolMetadata = {
+		name: "list_files",
+		description: "Lista arquivos rastreados (diretório/glob opcionais).",
+		category: "code",
+		capabilities: ["outline"],
+		readOnly: true,
+		cost: 1,
+		cacheTtlMs: 120_000,
+	};
+
+	readonly inputSchema = Input;
+
+	async execute(
+		input: z.infer<typeof Input>,
+		context: import("../tool-context").ToolContext,
+	): Promise<ToolResult<string[]>> {
+		// `git grep -l` com padrão vazio não lista tudo; usamos `ls-files`.
+		let files: string[];
+		try {
+			const stdout = runGit(["-C", context.repoRoot, "ls-files"]);
+			files = stdout
+				.split("\n")
+				.map((line) => line.trim())
+				.filter(Boolean);
+		} catch {
+			return { ok: false, error: "não foi possível listar os arquivos (git)." };
+		}
+		if (input.directory) {
+			const prefix = input.directory.replace(/\/+$/, "");
+			files = files.filter(
+				(file) => file.startsWith(`${prefix}/`) || file === prefix,
+			);
+		}
+		if (input.glob) {
+			const matcher = globToRegExp(input.glob);
+			files = files.filter((file) => matcher.test(file));
+		}
+		const truncated = files.length > TOOL_LIMITS.maxFiles;
+		return {
+			ok: true,
+			data: files.slice(0, TOOL_LIMITS.maxFiles),
+			truncated,
+			...(truncated ? { hint: "Refine com directory/glob." } : {}),
+		};
+	}
+}
+
+/** Converte um glob simples em regex. */
+export function globToRegExp(glob: string): RegExp {
+	let pattern = "";
+	for (let index = 0; index < glob.length; index++) {
+		const char = glob[index] ?? "";
+		if (char === "*") {
+			if (glob[index + 1] === "*") {
+				pattern += ".*";
+				index++;
+			} else {
+				pattern += "[^/]*";
+			}
+			continue;
+		}
+		if (char === "?") {
+			pattern += ".";
+			continue;
+		}
+		pattern += char.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+	}
+	return new RegExp(`^${pattern}$`);
+}

package/src/harness/tools/builtin/pr-context-tool.ts

@@ -0,0 +1,41 @@
+/**
+ * Tool `pr_context` — contexto resumido da PR (já compactado).
+ */
+
+import { z } from "zod";
+import type { AgentTool, ToolMetadata, ToolResult } from "../agent-tool";
+
+/** Contexto da PR para orientação do agente. */
+export class PrContextTool implements AgentTool<Record<string, never>, unknown> {
+	readonly metadata: ToolMetadata = {
+		name: "pr_context",
+		description: "Contexto resumido da PR (objetivo, motivação, mudanças).",
+		category: "context",
+		capabilities: ["read"],
+		readOnly: true,
+		cost: 1,
+		cacheTtlMs: 300_000,
+	};
+
+	readonly inputSchema = z.object({});
+
+	async execute(
+		_input: Record<string, never>,
+		context: import("../tool-context").ToolContext,
+	): Promise<ToolResult<unknown>> {
+		return {
+			ok: true,
+			data: {
+				project: context.agent.projectName,
+				branch: context.agent.branch,
+				watchdog: context.agent.watchdog.id,
+				scope: context.agent.watchdog.scope,
+				context: context.agent.context ?? null,
+				files: context.agent.files,
+				overflow: context.agent.overflow,
+				deleted: context.agent.deleted,
+				docs: context.agent.docs,
+			},
+		};
+	}
+}

package/src/harness/tools/builtin/read-file-range-tool.ts

@@ -0,0 +1,73 @@
+/**
+ * Tool `read_file_range` — lê um trecho explícito (nunca o arquivo inteiro).
+ */
+
+import { z } from "zod";
+import type { AgentTool, ToolMetadata, ToolResult } from "../agent-tool";
+import { PathGuard } from "../path-guard";
+import { TOOL_LIMITS } from "../result-limiter";
+import { readLines, readRange } from "./helpers";
+
+const Input = z.object({
+	path: z.string().min(1),
+	startLine: z.number().int().min(1),
+	endLine: z.number().int().min(1),
+});
+
+/** Leitura por faixa, com no máximo 200 linhas/32 KB. */
+export class ReadFileRangeTool implements AgentTool<z.infer<typeof Input>, unknown> {
+	readonly metadata: ToolMetadata = {
+		name: "read_file_range",
+		description: "Lê um trecho de arquivo (faixa obrigatória, até 200 linhas).",
+		category: "code",
+		capabilities: ["read"],
+		readOnly: true,
+		cost: 3,
+		cacheTtlMs: 60_000,
+	};
+
+	readonly inputSchema = Input;
+
+	async execute(
+		input: z.infer<typeof Input>,
+		context: import("../tool-context").ToolContext,
+	): Promise<ToolResult<unknown>> {
+		const guard = new PathGuard(context.repoRoot);
+		try {
+			const range = readRange(guard, input.path, input.startLine, input.endLine);
+			if (!range) return { ok: false, error: "arquivo ilegível." };
+			const lines = readLines(guard.assertReadable(input.path)) ?? [];
+			const evidence = {
+				id: "",
+				file: range.path,
+				startLine: range.startLine,
+				endLine: range.endLine,
+				snippet: lines.slice(range.startLine - 1, range.endLine).join("\n"),
+				kind: "diff" as const,
+				sourceTool: "read_file_range",
+				confidence: 0.6,
+			};
+			return {
+				ok: true,
+				data: range,
+				...(range.truncated
+					? {
+							truncated: true,
+							hint: `Faixa limitada a ${TOOL_LIMITS.maxLines} linhas; refine o intervalo.`,
+						}
+					: {}),
+				evidence: [
+					{
+						...evidence,
+						snippet: evidence.snippet.slice(0, TOOL_LIMITS.maxBytes),
+					},
+				],
+			};
+		} catch (error) {
+			return {
+				ok: false,
+				error: error instanceof Error ? error.message : String(error),
+			};
+		}
+	}
+}

package/src/harness/tools/builtin/rule-signals-tool.ts

@@ -0,0 +1,36 @@
+/**
+ * Tool `rule_signals` — traduz uma regra em sinais e checks.
+ */
+
+import { z } from "zod";
+import type { AgentTool, ToolMetadata, ToolResult } from "../agent-tool";
+
+const Input = z.object({ rule: z.string().min(3) });
+
+/** Devolve a `RuleAnalysis` determinística da regra. */
+export class RuleSignalsTool implements AgentTool<z.infer<typeof Input>, unknown> {
+	readonly metadata: ToolMetadata = {
+		name: "rule_signals",
+		description: "Sinais, keywords e checks sugeridos para uma regra do watchdog.",
+		category: "rules",
+		capabilities: ["rules"],
+		readOnly: true,
+		cost: 1,
+		cacheTtlMs: 300_000,
+	};
+
+	readonly inputSchema = Input;
+
+	async execute(
+		input: z.infer<typeof Input>,
+		context: import("../tool-context").ToolContext,
+	): Promise<ToolResult<unknown>> {
+		const analysis =
+			context.rules.get(input.rule) ??
+			[...context.rules.values()].find((item) => item.rule.includes(input.rule));
+		if (!analysis) {
+			return { ok: false, error: "regra não encontrada no watchdog." };
+		}
+		return { ok: true, data: analysis };
+	}
+}

package/src/harness/tools/builtin/search-code-tool.ts

@@ -0,0 +1,65 @@
+/**
+ * Tool `search_code` — localiza padrões via `git grep` e devolve snippets.
+ */
+
+import { z } from "zod";
+import type { AgentTool, ToolMetadata, ToolResult } from "../agent-tool";
+import { TOOL_LIMITS } from "../result-limiter";
+import { gitGrep, parseGrepLine } from "./helpers";
+
+const Input = z.object({
+	query: z.string().min(2),
+	mode: z.enum(["fixed", "regex"]).optional(),
+	path: z.string().optional(),
+	contextLines: z.number().int().min(0).max(3).optional(),
+	maxResults: z.number().int().min(1).max(50).optional(),
+});
+
+/** Busca com limite de resultados e snippets curtos. */
+export class SearchCodeTool implements AgentTool<z.infer<typeof Input>, unknown> {
+	readonly metadata: ToolMetadata = {
+		name: "search_code",
+		description: "Procura um padrão no código (até 50 resultados com snippet).",
+		category: "code",
+		capabilities: ["search"],
+		readOnly: true,
+		cost: 2,
+		cacheTtlMs: 60_000,
+	};
+
+	readonly inputSchema = Input;
+
+	async execute(
+		input: z.infer<typeof Input>,
+		context: import("../tool-context").ToolContext,
+	): Promise<ToolResult<unknown>> {
+		const mode = input.mode === "regex" ? "-E" : "-F";
+		const args = ["-n", "-I", mode, "-e", input.query];
+		if (input.path) args.push("--", input.path);
+		const result = gitGrep(context.repoRoot, args);
+		if (!result.ok) {
+			// `git grep` retorna 1 quando não há match (não é erro).
+			if (result.stderr.includes("exit") || result.stdout === "") {
+				return { ok: true, data: { results: [], truncated: false } };
+			}
+			return { ok: false, error: result.stderr || "falha no git grep." };
+		}
+		const max = input.maxResults ?? TOOL_LIMITS.maxResults;
+		const results = result.stdout
+			.split("\n")
+			.map(parseGrepLine)
+			.filter((line): line is NonNullable<typeof line> => line !== null)
+			.slice(0, max)
+			.map((line) => ({
+				file: line.file,
+				line: line.line,
+				text: line.text.slice(0, 240),
+			}));
+		const truncated = result.stdout.trim().split("\n").length > results.length;
+		return {
+			ok: true,
+			data: { results, truncated },
+			...(truncated ? { truncated: true, hint: "Refine a query/path." } : {}),
+		};
+	}
+}

package/src/harness/tools/builtin/symbol-context-tool.ts

@@ -0,0 +1,106 @@
+/**
+ * Tool `symbol_context` — definição + janela curta do corpo + referências.
+ */
+
+import { z } from "zod";
+import type { AgentTool, ToolMetadata, ToolResult } from "../agent-tool";
+import { PathGuard } from "../path-guard";
+import { TOOL_LIMITS } from "../result-limiter";
+import { gitGrep, numberedRange, parseGrepLine, readLines, snippet } from "./helpers";
+
+const Input = z.object({
+	symbol: z.string().min(2),
+	file: z.string().optional(),
+});
+
+/** Devolve no máximo ~120 linhas do símbolo (nunca o arquivo inteiro). */
+export class SymbolContextTool implements AgentTool<z.infer<typeof Input>, unknown> {
+	readonly metadata: ToolMetadata = {
+		name: "symbol_context",
+		description: "Definição + assinatura + corpo curto + referências de um símbolo.",
+		category: "symbol",
+		capabilities: ["symbol", "read"],
+		readOnly: true,
+		cost: 3,
+		cacheTtlMs: 60_000,
+	};
+
+	readonly inputSchema = Input;
+
+	async execute(
+		input: z.infer<typeof Input>,
+		context: import("../tool-context").ToolContext,
+	): Promise<ToolResult<unknown>> {
+		const guard = new PathGuard(context.repoRoot);
+		const files = input.file
+			? [input.file]
+			: [
+					...new Set([
+						...context.agent.files,
+						...(context.agent.impact?.affectedFiles ?? []),
+					]),
+				];
+		const maxLines = Math.min(TOOL_LIMITS.maxLines, 120);
+
+		for (const file of files.slice(0, 50)) {
+			let relative: string;
+			try {
+				relative = guard.relativePath(file);
+			} catch {
+				continue;
+			}
+			const facts = await context.ast.factsOf(relative);
+			if (!facts) continue;
+			const symbol = facts.symbols.find((item) => item.name === input.symbol);
+			if (!symbol) continue;
+
+			const lines = readLines(guard.assertReadable(relative)) ?? [];
+			const endLine = Math.min(symbol.endLine, symbol.startLine + maxLines - 1);
+			const references = referencesOf(context.repoRoot, input.symbol);
+			return {
+				ok: true,
+				data: {
+					file: relative,
+					name: symbol.name,
+					kind: symbol.kind,
+					exported: symbol.exported,
+					signature: symbol.signature,
+					startLine: symbol.startLine,
+					endLine,
+					truncatedBody: symbol.endLine > endLine,
+					body: numberedRange(lines, symbol.startLine, endLine),
+					references,
+				},
+				evidence: [
+					{
+						id: "",
+						file: relative,
+						startLine: symbol.startLine,
+						endLine,
+						snippet: snippet(lines, symbol.startLine, endLine),
+						kind: "definition",
+						sourceTool: "symbol_context",
+						confidence: 0.9,
+					},
+				],
+			};
+		}
+		return {
+			ok: false,
+			error: `símbolo '${input.symbol}' não encontrado (AST).`,
+			hint: "Use search_code/find_references.",
+		};
+	}
+}
+
+/** Referências resumidas (arquivo:linha). */
+function referencesOf(root: string, symbol: string): { file: string; line: number }[] {
+	const result = gitGrep(root, ["-n", "-I", "-F", "-w", "-e", symbol]);
+	if (!result.ok) return [];
+	return result.stdout
+		.split("\n")
+		.map(parseGrepLine)
+		.filter((line): line is NonNullable<typeof line> => line !== null)
+		.slice(0, 20)
+		.map((line) => ({ file: line.file, line: line.line }));
+}

package/src/harness/tools/builtin/tests-for-symbol-tool.ts

@@ -0,0 +1,61 @@
+/**
+ * Tool `tests_for_symbol` — arquivos de teste relacionados a um símbolo.
+ */
+
+import { z } from "zod";
+import type { AgentTool, ToolMetadata, ToolResult } from "../agent-tool";
+import { TOOL_LIMITS } from "../result-limiter";
+import { gitGrep, parseGrepLine } from "./helpers";
+
+const Input = z.object({ symbol: z.string().min(2), file: z.string().optional() });
+
+const TEST_PATHSPECS = [
+	"*.test.*",
+	"*.spec.*",
+	"**/__tests__/**",
+	"**/tests/**",
+	"**/test/**",
+];
+
+/** Referências em arquivos de teste (até 20 arquivos). */
+export class TestsForSymbolTool implements AgentTool<z.infer<typeof Input>, unknown> {
+	readonly metadata: ToolMetadata = {
+		name: "tests_for_symbol",
+		description: "Arquivos de teste que mencionam um símbolo.",
+		category: "evidence",
+		capabilities: ["tests", "search"],
+		readOnly: true,
+		cost: 2,
+		cacheTtlMs: 120_000,
+	};
+
+	readonly inputSchema = Input;
+
+	async execute(
+		input: z.infer<typeof Input>,
+		context: import("../tool-context").ToolContext,
+	): Promise<ToolResult<unknown>> {
+		const args = ["-n", "-I", "-F", "-w", "-e", input.symbol];
+		if (input.file) args.push("--", input.file);
+		else args.push("--", ...TEST_PATHSPECS);
+		const result = gitGrep(context.repoRoot, args);
+		if (!result.ok) return { ok: true, data: { files: [], references: [] } };
+		const references = result.stdout
+			.split("\n")
+			.map(parseGrepLine)
+			.filter((line): line is NonNullable<typeof line> => line !== null)
+			.slice(0, TOOL_LIMITS.maxResults);
+		const files = [...new Set(references.map((line) => line.file))].slice(0, 20);
+		const evidence = references.slice(0, 10).map((line) => ({
+			id: "",
+			file: line.file,
+			startLine: line.line,
+			endLine: line.line,
+			snippet: line.text,
+			kind: "test" as const,
+			sourceTool: "tests_for_symbol",
+			confidence: 0.6,
+		}));
+		return { ok: true, data: { files, references }, evidence };
+	}
+}

package/src/harness/tools/path-guard.ts

@@ -0,0 +1,90 @@
+/**
+ * Guarda de caminhos das tools — impede leitura fora do repositório e de
+ * arquivos sensíveis (`..`, `.git`, `.env*`, binários, arquivos enormes).
+ */
+
+import { statSync } from "node:fs";
+import { extname, isAbsolute, relative, resolve, sep } from "node:path";
+
+/** Erro de caminho bloqueado (mensagem segura). */
+export class PathGuardError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "PathGuardError";
+	}
+}
+
+/** Extensões consideradas binárias. */
+const BINARY_EXTENSIONS = new Set([
+	".png",
+	".jpg",
+	".jpeg",
+	".gif",
+	".webp",
+	".ico",
+	".pdf",
+	".zip",
+	".gz",
+	".tgz",
+	".wasm",
+	".node",
+	".so",
+	".dll",
+	".exe",
+	".lockb",
+]);
+
+/** Nomes/diretórios bloqueados. */
+function isBlockedPath(path: string): boolean {
+	const normalized = path.replace(/\\/g, "/");
+	if (/(^|\/)\.git(\/|$)/.test(normalized)) return true;
+	if (/(^|\/)node_modules(\/|$)/.test(normalized)) return true;
+	if (/(^|\/)\.env(\.|$)/.test(normalized)) return true;
+	if (/(^|\/)\.houndsman\/core\/grammars(\/|$)/.test(normalized)) return true;
+	return false;
+}
+
+/** Guarda de caminhos com raiz fixa. */
+export class PathGuard {
+	readonly root: string;
+	private readonly maxFileBytes: number;
+
+	constructor(root: string, maxFileBytes = 1_000_000) {
+		this.root = resolve(root);
+		this.maxFileBytes = maxFileBytes;
+	}
+
+	/** Resolve um caminho relativo dentro da raiz; lança se escapar. */
+	resolvePath(input: string): string {
+		if (!input.trim()) throw new PathGuardError("caminho vazio");
+		const absolute = isAbsolute(input) ? resolve(input) : resolve(this.root, input);
+		const rel = relative(this.root, absolute);
+		if (rel.startsWith("..") || rel.split(sep).includes("..")) {
+			throw new PathGuardError("caminho fora do repositório");
+		}
+		if (rel === "") throw new PathGuardError("caminho inválido");
+		if (isBlockedPath(rel)) throw new PathGuardError("caminho bloqueado");
+		if (BINARY_EXTENSIONS.has(extname(absolute).toLowerCase())) {
+			throw new PathGuardError("arquivo binário");
+		}
+		return absolute;
+	}
+
+	/** Resolve e valida tamanho/tipo; devolve o caminho absoluto. */
+	assertReadable(input: string): string {
+		const absolute = this.resolvePath(input);
+		let size = 0;
+		try {
+			size = statSync(absolute).size;
+		} catch {
+			throw new PathGuardError("arquivo inexistente");
+		}
+		if (size > this.maxFileBytes) throw new PathGuardError("arquivo muito grande");
+		return absolute;
+	}
+
+	/** Caminho relativo normalizado (para respostas). */
+	relativePath(input: string): string {
+		return relative(this.root, this.resolvePath(input)).replace(/\\/g, "/");
+	}
+}