@payconductor/houndsman 0.5.0 → 0.7.0

package/src/core/ast/diff.ts

@@ -0,0 +1,220 @@
+/**
+ * Delta estrutural entre duas versões de um arquivo (biblioteca).
+ *
+ * O patch unificado informa quais linhas novas mudaram; os símbolos da versão
+ * atual com intervalo tocado viram `modifiedSymbols`. Símbolos que só existem
+ * em um dos lados viram `added`/`removed`. Tudo é puro e determinístico.
+ */
+
+import type {
+	AstDelta,
+	AstExportChange,
+	AstFacts,
+	AstSignatureChange,
+	AstSymbol,
+} from "./types";
+
+/** Um hunk do patch, com as linhas novas adicionadas. */
+export type AstHunk = {
+	oldStart: number;
+	oldLines: number;
+	newStart: number;
+	newLines: number;
+	/** Linhas novas (1-based) introduzidas pelo hunk. */
+	addedLines: number[];
+};
+
+/** Regex do cabeçalho de hunk (`@@ -a,b +c,d @@`). */
+const HUNK_HEADER = /^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/;
+
+/** Converte um número opcional do header (default 1). */
+function countOf(value: string | undefined): number {
+	const parsed = value ? Number.parseInt(value, 10) : 1;
+	return Number.isNaN(parsed) ? 1 : parsed;
+}
+
+/** Fatia um patch unificado por arquivo em hunks. */
+export function parseHunks(patch: string): AstHunk[] {
+	const hunks: AstHunk[] = [];
+	let current: AstHunk | null = null;
+	let newLine = 0;
+
+	for (const line of patch.split("\n")) {
+		if (line.startsWith("@@ ")) {
+			const match = HUNK_HEADER.exec(line);
+			if (!match) {
+				current = null;
+				continue;
+			}
+			current = {
+				oldStart: Number.parseInt(match[1], 10),
+				oldLines: countOf(match[2]),
+				newStart: Number.parseInt(match[3], 10),
+				newLines: countOf(match[4]),
+				addedLines: [],
+			};
+			newLine = current.newStart;
+			hunks.push(current);
+			continue;
+		}
+		if (!current) continue;
+		if (line.startsWith("diff --git ")) {
+			current = null;
+			continue;
+		}
+		if (line.startsWith("+++ ") || line.startsWith("--- ")) continue;
+		if (line.startsWith("+")) {
+			current.addedLines.push(newLine);
+			newLine++;
+			continue;
+		}
+		if (line.startsWith("-")) continue;
+		if (line.startsWith("\\")) continue;
+		if (line.startsWith(" ")) newLine++;
+	}
+
+	return hunks;
+}
+
+/** Conjunto de linhas novas (1-based) adicionadas pelo patch. */
+export function changedNewLines(patch: string): Set<number> {
+	const lines = new Set<number>();
+	for (const hunk of parseHunks(patch)) {
+		for (const line of hunk.addedLines) lines.add(line);
+	}
+	return lines;
+}
+
+/** Chave estável de um símbolo (espécie + nome). */
+function symbolKey(symbol: AstSymbol): string {
+	return `${symbol.kind}:${symbol.name}`;
+}
+
+/** Indexa símbolos por chave. */
+function indexSymbols(symbols: readonly AstSymbol[]): Map<string, AstSymbol> {
+	const map = new Map<string, AstSymbol>();
+	for (const symbol of symbols) map.set(symbolKey(symbol), symbol);
+	return map;
+}
+
+/** `true` se alguma linha alterada cai no intervalo do símbolo. */
+function touches(symbol: AstSymbol, changed: ReadonlySet<number>): boolean {
+	for (const line of changed) {
+		if (line >= symbol.startLine && line <= symbol.endLine) return true;
+	}
+	return false;
+}
+
+/** Fonte dos imports (deduplicada e ordenada). */
+function importSources(facts: AstFacts | null): Set<string> {
+	return new Set((facts?.imports ?? []).map((item) => item.source));
+}
+
+/** Nomes dos exports (deduplicados e ordenados). */
+function exportNames(facts: AstFacts | null): Set<string> {
+	return new Set((facts?.exports ?? []).map((item) => item.name));
+}
+
+/** Compara dois conjuntos e devolve o que foi adicionado/removido. */
+function setDelta(
+	before: Set<string>,
+	after: Set<string>,
+): {
+	added: string[];
+	removed: string[];
+} {
+	const added = [...after].filter((item) => !before.has(item)).sort();
+	const removed = [...before].filter((item) => !after.has(item)).sort();
+	return { added, removed };
+}
+
+/** Delta vazio (arquivos sem alteração estrutural). */
+export function emptyDelta(): AstDelta {
+	return {
+		addedSymbols: [],
+		removedSymbols: [],
+		modifiedSymbols: [],
+		changedSignatures: [],
+		addedImports: [],
+		removedImports: [],
+		changedExports: [],
+	};
+}
+
+/**
+ * Compara a versão base com a atual e o patch do arquivo.
+ * `before`/`after` ausentes representam arquivo adicionado/deletado.
+ */
+export function computeDelta(
+	before: AstFacts | null,
+	after: AstFacts | null,
+	patch: string,
+): AstDelta {
+	if (!before && !after) return emptyDelta();
+
+	const changed = changedNewLines(patch);
+	const beforeSymbols = indexSymbols(before?.symbols ?? []);
+	const afterSymbols = indexSymbols(after?.symbols ?? []);
+	const beforeExportNames = exportNames(before);
+	const afterExportNames = exportNames(after);
+	const withExport = (symbol: AstSymbol, names: ReadonlySet<string>): AstSymbol =>
+		symbol.exported || names.has(symbol.name)
+			? { ...symbol, exported: true }
+			: symbol;
+
+	const addedSymbols: AstSymbol[] = [];
+	const removedSymbols: AstSymbol[] = [];
+	const modifiedSymbols: AstSymbol[] = [];
+	const changedSignatures: AstSignatureChange[] = [];
+
+	for (const [key, symbol] of afterSymbols) {
+		const previous = beforeSymbols.get(key);
+		if (!previous) {
+			addedSymbols.push(withExport(symbol, afterExportNames));
+			continue;
+		}
+		if (touches(symbol, changed)) {
+			modifiedSymbols.push(withExport(symbol, afterExportNames));
+		}
+		if (
+			(previous.signature || symbol.signature) &&
+			previous.signature !== symbol.signature
+		) {
+			changedSignatures.push({
+				name: symbol.name,
+				before: previous.signature ?? "",
+				after: symbol.signature ?? "",
+				exported:
+					symbol.exported ||
+					previous.exported ||
+					beforeExportNames.has(symbol.name) ||
+					afterExportNames.has(symbol.name),
+			});
+		}
+	}
+	for (const [key, symbol] of beforeSymbols) {
+		if (!afterSymbols.has(key)) {
+			removedSymbols.push(withExport(symbol, beforeExportNames));
+		}
+	}
+
+	const imports = setDelta(importSources(before), importSources(after));
+	const exports = setDelta(exportNames(before), exportNames(after));
+	const changedExports: AstExportChange[] = [
+		...exports.added.map((name) => ({ name, change: "added" as const })),
+		...exports.removed.map((name) => ({ name, change: "removed" as const })),
+	];
+
+	const byPosition = (a: AstSymbol, b: AstSymbol): number =>
+		a.startLine - b.startLine || a.name.localeCompare(b.name);
+
+	return {
+		addedSymbols: addedSymbols.sort(byPosition),
+		removedSymbols: removedSymbols.sort(byPosition),
+		modifiedSymbols: modifiedSymbols.sort(byPosition),
+		changedSignatures: changedSignatures.sort((a, b) => a.name.localeCompare(b.name)),
+		addedImports: imports.added,
+		removedImports: imports.removed,
+		changedExports,
+	};
+}

package/src/core/ast/impact.ts

@@ -0,0 +1,127 @@
+/**
+ * Impacto estrutural (biblioteca).
+ *
+ * Resolve imports relativos/aliases e monta o mapa reverso (quem importa os
+ * arquivos alterados) e os exports públicos que mudaram. O serviço decide como
+ * descobrir candidatos; aqui ficam apenas as funções puras.
+ */
+
+import { posix } from "node:path";
+import type { AstAnalysis, AstImpact } from "./types";
+
+/** Testa se um caminho existe (working tree ou índice do git). */
+export type PathExists = (path: string) => boolean;
+
+/** Extensões tentadas ao resolver um import sem extensão. */
+const CANDIDATE_EXTENSIONS = [".ts", ".tsx", ".d.ts", ".js", ".jsx", ".mjs", ".cjs"];
+
+/** Índices de diretório tentados. */
+const INDEX_FILES = ["index.ts", "index.tsx", "index.js", "index.jsx"];
+
+/** Remove query/hash de um specifier. */
+function stripQuery(source: string): string {
+	const index = source.search(/[?#]/);
+	return index >= 0 ? source.slice(0, index) : source;
+}
+
+/** Remove a extensão de runtime usada em imports ESM (`./x.js` → `./x`). */
+function stripRuntimeExtension(source: string): string {
+	return source.replace(/\.(?:js|jsx|mjs|cjs)$/i, "");
+}
+
+/** Normaliza uma chave de alias (`@/*` / `@/` → `@/`). */
+function normalizeAliasKey(key: string): string {
+	const withoutWildcard = key.endsWith("*") ? key.slice(0, -1) : key;
+	return withoutWildcard.endsWith("/") ? withoutWildcard : `${withoutWildcard}/`;
+}
+
+/** Normaliza o alvo do alias (`src/*` → `src/`). */
+function normalizeAliasTarget(target: string): string {
+	const withoutWildcard = target.endsWith("*") ? target.slice(0, -1) : target;
+	return withoutWildcard.replace(/\/+$/, "");
+}
+
+/**
+ * Resolve um specifier para um caminho relativo à raiz do repo.
+ * `null` quando é pacote externo, alias desconhecido ou candidato inexistente.
+ */
+export function resolveImport(
+	fromFile: string,
+	source: string,
+	aliases: Record<string, string>,
+	exists: PathExists,
+): string | null {
+	const clean = stripRuntimeExtension(stripQuery(source.trim()));
+	if (!clean) return null;
+
+	let base: string | null = null;
+	if (clean.startsWith(".")) {
+		base = posix.normalize(posix.join(posix.dirname(fromFile), clean));
+	} else {
+		for (const [rawKey, rawTarget] of Object.entries(aliases)) {
+			const key = normalizeAliasKey(rawKey);
+			if (!clean.startsWith(key)) continue;
+			const target = normalizeAliasTarget(rawTarget);
+			const rest = clean.slice(key.length);
+			base = posix.normalize(posix.join(target, rest));
+			break;
+		}
+	}
+	if (!base) return null;
+
+	const candidates = [base];
+	for (const extension of CANDIDATE_EXTENSIONS) candidates.push(`${base}${extension}`);
+	for (const index of INDEX_FILES) candidates.push(posix.join(base, index));
+
+	for (const candidate of candidates) {
+		const normalized = candidate.replace(/^\.\//, "");
+		if (exists(normalized)) return normalized;
+	}
+	return null;
+}
+
+/**
+ * Monta o impacto a partir das análises dos arquivos alterados e do mapa de
+ * importadores descoberto pelo serviço (`arquivo alterado → importadores`).
+ */
+export function buildImpact(
+	analyses: ReadonlyMap<string, AstAnalysis>,
+	importersByFile: ReadonlyMap<string, ReadonlySet<string>>,
+): AstImpact {
+	const importers: Record<string, string[]> = {};
+	const affected = new Set<string>();
+	const exportedChanges: AstImpact["exportedChanges"] = [];
+
+	for (const [file, files] of importersByFile) {
+		const sorted = [...files].sort();
+		if (sorted.length === 0) continue;
+		importers[file] = sorted;
+		for (const importer of sorted) affected.add(importer);
+	}
+
+	for (const [file, analysis] of analyses) {
+		const delta = analysis.delta;
+		if (!delta) continue;
+		for (const symbol of delta.removedSymbols) {
+			if (!symbol.exported) continue;
+			exportedChanges.push({ file, symbol: symbol.name, change: "removed" });
+		}
+		for (const change of delta.changedSignatures) {
+			if (!change.exported) continue;
+			exportedChanges.push({ file, symbol: change.name, change: "signature" });
+		}
+	}
+
+	exportedChanges.sort(
+		(a, b) =>
+			a.file.localeCompare(b.file) ||
+			a.symbol.localeCompare(b.symbol) ||
+			a.change.localeCompare(b.change),
+	);
+
+	return {
+		importers,
+		affectedFiles: [...affected].sort(),
+		exportedChanges,
+	};
+}

package/src/core/ast/parser.ts

@@ -0,0 +1,167 @@
+/**
+ * Parser tree-sitter (biblioteca).
+ *
+ * Inicialização lazy e por linguagem: o wasm só é carregado quando existe um
+ * arquivo compatível. Qualquer falha (grammar ausente, ABI incompatível, arquivo
+ * grande/binário) devolve `null` — o chamador segue sem AST.
+ */
+
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { extname, join } from "node:path";
+import { Language, Parser } from "web-tree-sitter";
+import { grammarPath } from "../assets";
+import { DEFAULT_AST_MAX_FILE_BYTES } from "../defaults";
+import { extractFacts } from "./symbols";
+import type { AstFacts, AstLanguage } from "./types";
+
+/** Arquivo wasm de cada linguagem suportada. */
+const GRAMMAR_BY_LANGUAGE: Record<AstLanguage, string> = {
+	typescript: "tree-sitter-typescript.wasm",
+	tsx: "tree-sitter-tsx.wasm",
+	javascript: "tree-sitter-javascript.wasm",
+};
+
+/** Extensões reconhecidas por padrão (override via config). */
+const DEFAULT_LANGUAGE_BY_EXTENSION: Record<string, AstLanguage> = {
+	".ts": "typescript",
+	".mts": "typescript",
+	".cts": "typescript",
+	".tsx": "tsx",
+	".jsx": "tsx",
+	".js": "javascript",
+	".mjs": "javascript",
+	".cjs": "javascript",
+};
+
+/** Teto default de bytes por arquivo (evita parsear bundles/minificados). */
+export const DEFAULT_MAX_FILE_BYTES = DEFAULT_AST_MAX_FILE_BYTES;
+
+/** Opções do parser. */
+export type AstParserOptions = {
+	maxFileBytes?: number;
+	/** Override de extensão → linguagem (chave com ou sem ponto). */
+	languages?: Record<string, AstLanguage>;
+	/** Diretório com grammars locais (`.houndsman/core/grammars`) — tem precedência. */
+	grammarDir?: string;
+};
+
+/** Normaliza a chave de extensão (`ts`/`.ts` → `.ts`). */
+function normalizeExtension(key: string): string {
+	const trimmed = key.trim().toLowerCase();
+	return trimmed.startsWith(".") ? trimmed : `.${trimmed}`;
+}
+
+/**
+ * Resolve a linguagem de um arquivo pela extensão. `null` quando não suportado.
+ */
+export function languageForPath(
+	filePath: string,
+	overrides: Record<string, AstLanguage> = {},
+): AstLanguage | null {
+	const extension = extname(filePath).toLowerCase();
+	if (!extension) return null;
+	const normalized = Object.fromEntries(
+		Object.entries(overrides).map(([key, value]) => [normalizeExtension(key), value]),
+	);
+	return normalized[extension] ?? DEFAULT_LANGUAGE_BY_EXTENSION[extension] ?? null;
+}
+
+/** Parser lazy, com uma instância por linguagem. */
+export class AstParser {
+	private initPromise: Promise<void> | null = null;
+	private readonly languages = new Map<AstLanguage, Language>();
+	private readonly parsers = new Map<AstLanguage, Parser>();
+	private readonly options: Required<Pick<AstParserOptions, "maxFileBytes">> &
+		AstParserOptions;
+
+	constructor(options: AstParserOptions = {}) {
+		this.options = {
+			maxFileBytes: options.maxFileBytes ?? DEFAULT_MAX_FILE_BYTES,
+			languages: options.languages,
+			grammarDir: options.grammarDir,
+		};
+	}
+
+	/** Resolve uma grammar: camada do projeto primeiro, pacote como fallback. */
+	private grammarFile(name: string): string {
+		if (this.options.grammarDir) {
+			const local = join(this.options.grammarDir, name);
+			if (existsSync(local)) return local;
+		}
+		return grammarPath(name);
+	}
+
+	/** Inicializa o runtime wasm (idempotente). */
+	async init(): Promise<void> {
+		if (!this.initPromise) {
+			this.initPromise = Parser.init({
+				locateFile: (name: string) => this.grammarFile(name),
+			});
+		}
+		await this.initPromise;
+	}
+
+	/** Parser configurado para a linguagem (carrega a grammar sob demanda). */
+	private async parserFor(language: AstLanguage): Promise<Parser> {
+		const existing = this.parsers.get(language);
+		if (existing) return existing;
+
+		await this.init();
+		const loaded = await Language.load(
+			this.grammarFile(GRAMMAR_BY_LANGUAGE[language]),
+		);
+		const parser = new Parser();
+		parser.setLanguage(loaded);
+		this.languages.set(language, loaded);
+		this.parsers.set(language, parser);
+		return parser;
+	}
+
+	/** Parseia um texto e devolve os fatos; `null` se a linguagem falhar. */
+	async parseSource(language: AstLanguage, source: string): Promise<AstFacts | null> {
+		try {
+			const parser = await this.parserFor(language);
+			const tree = parser.parse(source);
+			if (!tree) return null;
+			try {
+				return extractFacts(tree.rootNode, language);
+			} finally {
+				tree.delete();
+			}
+		} catch {
+			return null;
+		}
+	}
+
+	/**
+	 * Parseia um arquivo do working tree. `source` permite reaproveitar conteúdo
+	 * já lido; sem ele, o arquivo é lido do disco.
+	 */
+	async parseFile(filePath: string, source?: string): Promise<AstFacts | null> {
+		const language = languageForPath(filePath, this.options.languages);
+		if (!language) return null;
+
+		let content = source;
+		if (content === undefined) {
+			try {
+				const size = statSync(filePath).size;
+				if (size <= 0 || size > this.options.maxFileBytes) return null;
+				content = readFileSync(filePath, "utf8");
+			} catch {
+				return null;
+			}
+		}
+		if (content.length > this.options.maxFileBytes || content.includes("\0")) {
+			return null;
+		}
+		return this.parseSource(language, content);
+	}
+
+	/** Libera parsers/grammars (usado em testes). */
+	dispose(): void {
+		for (const parser of this.parsers.values()) parser.delete();
+		this.parsers.clear();
+		this.languages.clear();
+		this.initPromise = null;
+	}
+}