@payconductor/houndsman 0.5.0 → 0.7.0

package/src/core/ast/service.ts

@@ -0,0 +1,233 @@
+/**
+ * Serviço de AST (biblioteca) — fachada usada pelo engine/pipeline.
+ *
+ * Concentra parse, delta e impacto. É **fail-open**: sem grammar, arquivo
+ * grande/binário, erro de git ou ABI incompatível, o resultado é vazio e a
+ * revisão segue pelo caminho de regex.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { basename, dirname, extname, join } from "node:path";
+import type { HoundsmanConfig } from "../config";
+import type { DiffSource } from "../diff-source";
+import { CORE_DIR } from "../paths";
+import { ProjectConfig } from "../project-config";
+import { GitRepository } from "../services/git-repository";
+import { computeDelta } from "./diff";
+import { buildImpact, resolveImport } from "./impact";
+import { AstParser, languageForPath } from "./parser";
+import type { AstAnalysis, AstEntry, AstFacts, AstImpact } from "./types";
+
+/** Padrões de arquivos candidatos para a busca reversa de imports. */
+const GREP_PATHSPECS = ["*.ts", "*.tsx", "*.js", "*.jsx", "*.mjs", "*.cjs"];
+
+/** Serviço de análise estrutural por AST. */
+export class AstService {
+	private readonly project: ProjectConfig;
+	private readonly git: GitRepository;
+	private readonly parser: AstParser;
+
+	constructor(config: HoundsmanConfig, git: GitRepository = new GitRepository()) {
+		this.project = new ProjectConfig(config);
+		this.git = git;
+		const layerGrammars = join(process.cwd(), CORE_DIR, "grammars");
+		this.parser = new AstParser({
+			maxFileBytes: this.project.astMaxFileBytes,
+			languages: this.project.ast.languages,
+			grammarDir: existsSync(layerGrammars) ? layerGrammars : undefined,
+		});
+	}
+
+	/** `true` quando o AST está habilitado na configuração. */
+	get enabled(): boolean {
+		return this.project.astEnabled;
+	}
+
+	/**
+	 * Smoke test do runtime/grammar (usado pelo `doctor`). Não lança: devolve o
+	 * diagnóstico para o chamador decidir. Fail-open.
+	 */
+	async check(): Promise<{ ok: boolean; detail: string }> {
+		if (!this.enabled) return { ok: true, detail: "desabilitado na config" };
+		const facts = await this.parser.parseSource(
+			"typescript",
+			"export const houndsmanAstCheck = 1;\n",
+		);
+		return facts
+			? { ok: true, detail: "typescript disponível" }
+			: { ok: false, detail: "grammar indisponível ou ABI incompatível" };
+	}
+
+	/**
+	 * Analisa os arquivos alterados: fatos da versão atual, delta contra a base
+	 * e (para deletados) os fatos da última versão disponível.
+	 */
+	async analyze(
+		entries: readonly AstEntry[],
+		diff: DiffSource,
+		baseRef: string,
+	): Promise<Map<string, AstAnalysis>> {
+		const analyses = new Map<string, AstAnalysis>();
+		if (!this.enabled) return analyses;
+
+		for (const entry of entries) {
+			const language = languageForPath(entry.path, this.project.ast.languages);
+			if (!language) continue;
+			const patch = diff.byFile.get(entry.path) ?? "";
+
+			if (entry.status === "deleted") {
+				const oldContent = this.readAt(baseRef, entry.path);
+				const facts = await this.parseContent(entry.path, oldContent);
+				if (facts) {
+					analyses.set(entry.path, {
+						facts,
+						delta: computeDelta(facts, null, patch),
+						deleted: true,
+					});
+				}
+				continue;
+			}
+
+			const current = this.readWorkingFile(entry.path);
+			if (current === null) continue;
+			const facts = await this.parser.parseFile(entry.path, current);
+			if (!facts) continue;
+
+			const oldPath = entry.oldPath ?? entry.path;
+			const oldContent =
+				entry.status === "added" ? null : this.readAt(baseRef, oldPath);
+			const before = oldContent
+				? await this.parseContent(oldPath, oldContent)
+				: null;
+
+			analyses.set(entry.path, {
+				facts,
+				delta: computeDelta(before, facts, patch),
+			});
+		}
+
+		return analyses;
+	}
+
+	/**
+	 * Descobre importadores dos arquivos alterados. A busca é heurística e
+	 * limitada por `ast.maxImpactFiles`: usa `git grep` pelo nome do módulo,
+	 * depois confirma o import resolvido (relativo/alias) no candidato.
+	 */
+	async impact(analyses: ReadonlyMap<string, AstAnalysis>): Promise<AstImpact> {
+		const changed = [...analyses.keys()];
+		const importersByFile = new Map<string, Set<string>>();
+		for (const file of changed) importersByFile.set(file, new Set<string>());
+		if (!this.enabled || changed.length === 0) {
+			return buildImpact(analyses, importersByFile);
+		}
+
+		const maxCandidates = this.project.astMaxImpactFiles;
+		if (maxCandidates <= 0) return buildImpact(analyses, importersByFile);
+
+		const changedSet = new Set(changed);
+		const candidates = this.candidateFiles(changed, maxCandidates);
+		const cache = new Map<string, AstFacts | null>();
+
+		for (const candidate of candidates) {
+			const content = this.readWorkingFile(candidate);
+			if (content === null) continue;
+			let facts: AstFacts | null;
+			if (cache.has(candidate)) {
+				facts = cache.get(candidate) ?? null;
+			} else {
+				facts = await this.parser.parseFile(candidate, content);
+				cache.set(candidate, facts);
+			}
+			if (!facts) continue;
+
+			for (const item of facts.imports) {
+				const resolved = resolveImport(
+					candidate,
+					item.source,
+					this.project.ast.aliases ?? {},
+					(path) => existsSync(path) || changedSet.has(path),
+				);
+				if (!resolved) continue;
+				const importers = importersByFile.get(resolved);
+				if (importers) importers.add(candidate);
+			}
+		}
+
+		return buildImpact(analyses, importersByFile);
+	}
+
+	/** Fatos estruturais do arquivo atual (usado pelas tools do harness). */
+	async factsOf(filePath: string): Promise<AstFacts | null> {
+		if (!this.enabled) return null;
+		const content = this.readWorkingFile(filePath);
+		if (content === null) return null;
+		return this.parser.parseFile(filePath, content);
+	}
+
+	/** Lê o conteúdo atual do arquivo; `null` se ausente/ilegível. */
+	private readWorkingFile(filePath: string): string | null {
+		try {
+			return readFileSync(filePath, "utf8");
+		} catch {
+			return null;
+		}
+	}
+
+	/** Lê o conteúdo de um arquivo numa ref; `null` se ausente. */
+	private readAt(ref: string, filePath: string): string | null {
+		if (!ref) return null;
+		try {
+			return this.git.readFileAt(ref, filePath);
+		} catch {
+			return null;
+		}
+	}
+
+	/** Parseia conteúdo textual reaproveitando a linguagem do caminho. */
+	private async parseContent(
+		filePath: string,
+		content: string | null,
+	): Promise<AstFacts | null> {
+		if (!content) return null;
+		const language = languageForPath(filePath, this.project.ast.languages);
+		if (!language) return null;
+		return this.parser.parseSource(language, content);
+	}
+
+	/** Candidatos a importadores via `git grep` pelo nome do módulo. */
+	private candidateFiles(changed: readonly string[], maxCandidates: number): string[] {
+		const candidates = new Set<string>();
+		for (const file of changed) {
+			for (const needle of needlesFor(file)) {
+				const result = this.git.tryRun([
+					"grep",
+					"-l",
+					"-I",
+					"-F",
+					"-e",
+					needle,
+					"--",
+					...GREP_PATHSPECS,
+				]);
+				for (const line of result.stdout.split("\n")) {
+					const candidate = line.trim().replace(/\\/g, "/");
+					if (!candidate) continue;
+					candidates.add(candidate);
+					if (candidates.size >= maxCandidates) return [...candidates];
+				}
+			}
+		}
+		return [...candidates].sort();
+	}
+}
+
+/** Nomes usados para localizar importadores de um arquivo. */
+function needlesFor(filePath: string): string[] {
+	const extension = extname(filePath);
+	const withoutExtension = extension ? filePath.slice(0, -extension.length) : filePath;
+	const base = basename(withoutExtension);
+	if (base !== "index") return base.length >= 2 ? [base] : [];
+	const directory = basename(dirname(filePath));
+	return directory.length >= 2 ? [directory] : [];
+}

package/src/core/ast/symbols.ts

@@ -0,0 +1,294 @@
+/**
+ * Extração de fatos estruturais (biblioteca).
+ *
+ * Usa a árvore do tree-sitter sem depender da API de queries: percorre os nós
+ * nomeados e extrai imports, exports, declarações, assinaturas e decorators.
+ * Tolerante a sintaxe inválida — o que der para ler vira fato; o resto é
+ * ignorado.
+ */
+
+import type { Node } from "web-tree-sitter";
+import type {
+	AstExport,
+	AstFacts,
+	AstImport,
+	AstLanguage,
+	AstSymbol,
+	AstSymbolKind,
+} from "./types";
+
+/** Tipos de nó que viram símbolo, com a espécie correspondente. */
+const DECLARATION_KINDS: Record<string, AstSymbolKind> = {
+	function_declaration: "function",
+	generator_function_declaration: "function",
+	class_declaration: "class",
+	interface_declaration: "interface",
+	type_alias_declaration: "type",
+	enum_declaration: "enum",
+	method_definition: "method",
+	method_signature: "method",
+	abstract_method_signature: "method",
+	public_field_definition: "property",
+	property_signature: "property",
+};
+
+/** Tipos de contêiner usados para qualificar métodos (`Classe.método`). */
+const OWNER_TYPES = ["class_declaration", "interface_declaration"];
+
+/** Percorre a árvore em profundidade, visitando nós nomeados. */
+function walk(node: Node, visit: (node: Node) => void): void {
+	visit(node);
+	for (const child of node.namedChildren) walk(child, visit);
+}
+
+/** Remove aspas simples/duplas de um literal de string. */
+function unquote(value: string): string {
+	const trimmed = value.trim();
+	if (trimmed.length < 2) return trimmed;
+	const first = trimmed[0];
+	const last = trimmed[trimmed.length - 1];
+	if ((first === '"' || first === "'") && last === first) {
+		return trimmed.slice(1, -1);
+	}
+	return trimmed;
+}
+
+/** Colapsa espaços em branco e trunca em `max` caracteres. */
+function collapse(value: string, max = 240): string {
+	const normalized = value.replace(/\s+/g, " ").trim();
+	return normalized.length > max ? `${normalized.slice(0, max - 1)}…` : normalized;
+}
+
+/** Sobe a árvore até encontrar um nó de um dos tipos informados. */
+function findAncestor(node: Node, types: readonly string[]): Node | null {
+	let current = node.parent;
+	while (current) {
+		if (types.includes(current.type)) return current;
+		current = current.parent;
+	}
+	return null;
+}
+
+/** `true` quando a declaração está sob um `export_statement`. */
+function isExported(node: Node): boolean {
+	return findAncestor(node, ["export_statement"]) !== null;
+}
+
+/** Nome da declaração (campo `name`). */
+function nameOf(node: Node): string | undefined {
+	return node.childForFieldName("name")?.text?.trim() || undefined;
+}
+
+/** Assinatura normalizada de função/método/arrow (parâmetros + retorno). */
+function signatureOf(node: Node, name: string): string | undefined {
+	const params = node.childForFieldName("parameters")?.text ?? "";
+	const returnType = node.childForFieldName("return_type")?.text ?? "";
+	if (!params && !returnType) return undefined;
+	return collapse(`${name}${params}${returnType}`);
+}
+
+/** Nome qualificado de métodos/propriedades (`Classe.membro`). */
+function qualifiedName(node: Node, name: string): string {
+	const owner = findAncestor(node, OWNER_TYPES);
+	const ownerName = owner ? nameOf(owner) : undefined;
+	return ownerName ? `${ownerName}.${name}` : name;
+}
+
+/** Adiciona um símbolo evitando duplicatas por espécie + nome. */
+function addSymbol(map: Map<string, AstSymbol>, symbol: AstSymbol): void {
+	const key = `${symbol.kind}:${symbol.name}`;
+	const existing = map.get(key);
+	if (
+		!existing ||
+		symbol.endLine - symbol.startLine > existing.endLine - existing.startLine
+	) {
+		map.set(key, symbol);
+	}
+}
+
+/** Extrai nomes de um `import_specifier` (importado e alias local). */
+function importSpecifierNames(node: Node, names: Set<string>): void {
+	const imported = node.childForFieldName("name")?.text?.trim();
+	const alias = node.childForFieldName("alias")?.text?.trim();
+	if (imported) names.add(imported);
+	if (alias) names.add(alias);
+}
+
+/** Nomes locais de um `import_clause` (default/namespace). */
+function importClauseNames(node: Node, names: Set<string>): void {
+	for (const child of node.namedChildren) {
+		if (child.type === "identifier") {
+			names.add(child.text.trim());
+			continue;
+		}
+		if (child.type === "namespace_import") {
+			const local = child.namedChildren.find((item) => item.type === "identifier");
+			if (local) names.add(local.text.trim());
+		}
+	}
+}
+
+/** Imports (`import`, `require` e `import()` dinâmico). */
+function collectImports(root: Node): AstImport[] {
+	const imports: AstImport[] = [];
+	walk(root, (node) => {
+		if (node.type === "import_statement") {
+			const sourceNode = node.childForFieldName("source");
+			const source = sourceNode ? unquote(sourceNode.text) : "";
+			if (!source) return;
+			const names = new Set<string>();
+			for (const child of node.descendantsOfType("import_specifier")) {
+				importSpecifierNames(child, names);
+			}
+			for (const child of node.descendantsOfType("import_clause")) {
+				importClauseNames(child, names);
+			}
+			imports.push({
+				source,
+				names: [...names],
+				typeOnly: /^import\s+type\b/.test(node.text.trim()),
+			});
+			return;
+		}
+
+		if (node.type !== "call_expression") return;
+		const fn = node.childForFieldName("function")?.text?.trim();
+		if (fn !== "require" && fn !== "import") return;
+		const args = node.childForFieldName("arguments");
+		const first = args?.namedChildren[0];
+		if (!first || first.type !== "string") return;
+		const source = unquote(first.text);
+		if (!source) return;
+		const names = new Set<string>();
+		const declarator = node.parent;
+		if (declarator?.type === "variable_declarator") {
+			const name = declarator.childForFieldName("name")?.text?.trim();
+			if (name) names.add(name);
+		}
+		imports.push({ source, names: [...names], typeOnly: false });
+	});
+	return imports;
+}
+
+/** Declarações (funções, classes, métodos, variáveis, tipos…). */
+function collectSymbols(root: Node): AstSymbol[] {
+	const symbols = new Map<string, AstSymbol>();
+
+	walk(root, (node) => {
+		// Declarações locais (dentro de função/bloco) não são símbolos de topo.
+		if (findAncestor(node, ["statement_block"]) !== null) return;
+
+		if (node.type === "lexical_declaration" || node.type === "variable_declaration") {
+			for (const declarator of node.namedChildren) {
+				if (declarator.type !== "variable_declarator") continue;
+				const name = nameOf(declarator);
+				if (!name || name.startsWith("{") || name.startsWith("[")) continue;
+				const value = declarator.childForFieldName("value");
+				const kind: AstSymbolKind =
+					value?.type === "arrow_function" ||
+					value?.type === "function_expression"
+						? "function"
+						: "variable";
+				addSymbol(symbols, {
+					name,
+					kind,
+					exported: isExported(declarator),
+					startLine: declarator.startPosition.row + 1,
+					endLine: declarator.endPosition.row + 1,
+					signature: value ? signatureOf(value, name) : undefined,
+				});
+			}
+			return;
+		}
+
+		const kind = DECLARATION_KINDS[node.type];
+		if (!kind) return;
+		const rawName = nameOf(node);
+		if (!rawName) return;
+		const name =
+			kind === "method" || kind === "property"
+				? qualifiedName(node, rawName)
+				: rawName;
+		const signature =
+			kind === "function" || kind === "method"
+				? signatureOf(node, name)
+				: kind === "interface" || kind === "type"
+					? collapse(node.text)
+					: undefined;
+		addSymbol(symbols, {
+			name,
+			kind,
+			exported: isExported(node),
+			startLine: node.startPosition.row + 1,
+			endLine: node.endPosition.row + 1,
+			signature,
+		});
+	});
+
+	return [...symbols.values()].sort(
+		(a, b) => a.startLine - b.startLine || a.name.localeCompare(b.name),
+	);
+}
+
+/** Exports declarados (inclui `export {}` e re-exports). */
+function collectExports(root: Node, symbols: readonly AstSymbol[]): AstExport[] {
+	const exports = new Map<string, AstExport>();
+
+	for (const symbol of symbols) {
+		if (symbol.exported)
+			exports.set(symbol.name, { name: symbol.name, kind: symbol.kind });
+	}
+
+	walk(root, (node) => {
+		if (node.type !== "export_statement") return;
+		const before = exports.size;
+		const clause = node.descendantsOfType("export_clause")[0];
+		if (clause) {
+			for (const specifier of clause.descendantsOfType("export_specifier")) {
+				const imported = specifier.childForFieldName("name")?.text?.trim();
+				const alias = specifier.childForFieldName("alias")?.text?.trim();
+				const name = alias ?? imported;
+				if (name) exports.set(name, { name, kind: "unknown" });
+			}
+		}
+		const source = node.childForFieldName("source");
+		if (source && !clause) {
+			exports.set("*", { name: "*", kind: "re-export" });
+		}
+		if (
+			!clause &&
+			/^export\s+default\b/.test(node.text.trim()) &&
+			exports.size === before
+		) {
+			exports.set("default", { name: "default", kind: "unknown" });
+		}
+	});
+
+	return [...exports.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/** Decorators normalizados (`@Controller` → `Controller`). */
+function collectDecorators(root: Node): string[] {
+	const decorators = new Set<string>();
+	walk(root, (node) => {
+		if (node.type !== "decorator") return;
+		const match = /^@\s*([A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*)/.exec(
+			node.text.trim(),
+		);
+		if (match) decorators.add(match[1]);
+	});
+	return [...decorators].sort();
+}
+
+/** Extrai todos os fatos de uma árvore já parseada. */
+export function extractFacts(root: Node, language: AstLanguage): AstFacts {
+	const symbols = collectSymbols(root);
+	return {
+		language,
+		symbols,
+		imports: collectImports(root),
+		exports: collectExports(root, symbols),
+		decorators: collectDecorators(root),
+		hasSyntaxErrors: root.hasError,
+	};
+}

package/src/core/ast/types.ts

@@ -0,0 +1,125 @@
+/**
+ * Tipos do subsistema AST (biblioteca).
+ *
+ * O AST é uma camada determinística de enriquecimento: fatos estruturais por
+ * arquivo, delta entre duas versões e impacto (importadores). Nunca substitui a
+ * classificação por regex — apenas a complementa quando a grammar está
+ * disponível.
+ */
+
+/** Linguagens suportadas na primeira fase (TS/JS). */
+export type AstLanguage = "typescript" | "tsx" | "javascript";
+
+/** Espécie de símbolo extraído do arquivo. */
+export type AstSymbolKind =
+	| "function"
+	| "class"
+	| "method"
+	| "interface"
+	| "type"
+	| "enum"
+	| "variable"
+	| "property"
+	| "unknown";
+
+/** Símbolo declarado no arquivo (nome, espécie, intervalo e assinatura). */
+export type AstSymbol = {
+	name: string;
+	kind: AstSymbolKind;
+	/** `true` quando a declaração está sob um `export_statement`. */
+	exported: boolean;
+	/** Linha inicial (1-based). */
+	startLine: number;
+	/** Linha final (1-based). */
+	endLine: number;
+	/** Assinatura normalizada (parâmetros/retorno), quando aplicável. */
+	signature?: string;
+};
+
+/** Import declarado no arquivo. */
+export type AstImport = {
+	source: string;
+	/** Nomes importados/locais (útil para classificação por símbolo). */
+	names: string[];
+	/** `import type` / `export type`. */
+	typeOnly: boolean;
+};
+
+/** Export declarado no arquivo (inclui re-exports). */
+export type AstExport = {
+	name: string;
+	kind: AstSymbolKind | "re-export";
+};
+
+/** Fatos estruturais de um arquivo. */
+export type AstFacts = {
+	language: AstLanguage;
+	symbols: AstSymbol[];
+	imports: AstImport[];
+	exports: AstExport[];
+	decorators: string[];
+	/** `true` quando o parser encontrou erro de sintaxe. */
+	hasSyntaxErrors: boolean;
+};
+
+/** Mudança de assinatura de um símbolo entre duas versões. */
+export type AstSignatureChange = {
+	name: string;
+	before: string;
+	after: string;
+	exported: boolean;
+};
+
+/** Mudança de export (nome adicionado/removido). */
+export type AstExportChange = {
+	name: string;
+	change: "added" | "removed";
+};
+
+/** Delta estrutural entre a versão base e a versão atual. */
+export type AstDelta = {
+	addedSymbols: AstSymbol[];
+	removedSymbols: AstSymbol[];
+	modifiedSymbols: AstSymbol[];
+	changedSignatures: AstSignatureChange[];
+	addedImports: string[];
+	removedImports: string[];
+	changedExports: AstExportChange[];
+};
+
+/** Análise de um arquivo alterado: fatos atuais + delta. */
+export type AstAnalysis = {
+	facts: AstFacts;
+	delta?: AstDelta;
+	/** `true` quando o arquivo foi removido (fatos são da versão base). */
+	deleted?: boolean;
+};
+
+/** Impacto estrutural de um conjunto de alterações. */
+export type AstImpact = {
+	/** arquivo alterado → arquivos que o importam (reverse deps). */
+	importers: Record<string, string[]>;
+	/** União ordenada dos importadores. */
+	affectedFiles: string[];
+	/** Exports públicos removidos/alterados (candidatos a breaking change). */
+	exportedChanges: {
+		file: string;
+		symbol: string;
+		change: "removed" | "signature";
+	}[];
+};
+
+/** Resumo de AST injetado no brief de um watchdog. */
+export type AstFileBrief = {
+	file: string;
+	delta: AstDelta;
+	/** Arquivos que importam este arquivo (impacto reverso). */
+	importers?: readonly string[];
+};
+
+/** Entrada mínima para analisar um arquivo alterado. */
+export type AstEntry = {
+	path: string;
+	oldPath?: string;
+	status: string;
+};