@shanepadgett/tau-agent 0.33.0 → 0.34.0

package/{extensions/explore → src}/ast/graph/file-graph.ts

@@ -1,21 +1,23 @@
 import { lstat, opendir } from "node:fs/promises";
 import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
-import type { FileDepHost, LanguageAdapter } from "../adapter.ts";
+import type { FileDepHost, FileDepResolution, LanguageAdapter } from "../adapter.ts";
 import type { ExploreEngine } from "../engine.ts";
 import { scanSources } from "../scan.ts";
-import { formatPathForDisplay, pathResolutionError, resolveExplorePath } from "../../traverse.ts";
+import { formatPathForDisplay, pathResolutionError, resolveExplorePath } from "../traverse.ts";
 
 export type FileGraphEdge =
 	| { kind: "internal"; from: string; to: string }
+	| { kind: "package"; from: string; id: string; dir: string; fileCount: number }
 	| { kind: "external"; from: string; id: string };
 
-export type FileDepHit = {
-	depth: number;
-	/** Absolute path for internal hits. */
-	path: string | undefined;
-	/** External package/module id. */
-	externalId: string | undefined;
-};
+/** One resolved dependency endpoint, independent of traversal depth. */
+export type FileDepTarget =
+	| { kind: "internal"; path: string }
+	/** In-repo directory too large to list; `id` is the import as written. */
+	| { kind: "package"; id: string; dir: string; fileCount: number }
+	| { kind: "external"; id: string };
+
+export type FileDepHit = { depth: number } & FileDepTarget;
 
 export type FileDepQueryResult = {
 	seedPath: string;
@@ -23,6 +25,8 @@ export type FileDepQueryResult = {
 	hits: FileDepHit[];
 	resultLimit: number;
 	resultLimitReached: boolean;
+	/** External edges dropped after the external cap (internal edges keep the full limit). */
+	externalOmitted: number;
 };
 
 export type ExploreFileGraph = {
@@ -44,6 +48,9 @@ type ReverseIndex = {
 	byTarget: Map<string, string[]>;
 };
 
+/** External ids are cheap noise in bulk; in-repo edges get the caller's full budget. */
+const EXTERNAL_HIT_LIMIT = 10;
+
 function isWithin(parent: string, child: string): boolean {
 	const rel = relative(resolve(parent), resolve(child));
 	return rel === "" || (!rel.startsWith(`..${sep}`) && rel !== ".." && !isAbsolute(rel));
@@ -112,6 +119,148 @@ function sortUnique(paths: readonly string[]): string[] {
 	return [...new Set(paths.map((path) => resolve(path)))].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
 }
 
+type EdgeSeen = {
+	internal: Set<string>;
+	package: Set<string>;
+	external: Set<string>;
+};
+
+function emptyEdgeSeen(): EdgeSeen {
+	return { internal: new Set(), package: new Set(), external: new Set() };
+}
+
+function appendInternalPaths(
+	edges: FileGraphEdge[],
+	from: string,
+	paths: readonly string[],
+	scopeRoot: string,
+	ownsPath: (path: string) => boolean,
+	seen: Set<string>,
+): void {
+	for (const target of sortUnique(paths)) {
+		if (!isWithin(scopeRoot, target)) continue;
+		if (!ownsPath(target)) continue;
+		if (target === from) continue;
+		if (seen.has(target)) continue;
+		seen.add(target);
+		edges.push({ kind: "internal", from, to: target });
+	}
+}
+
+function appendResolution(
+	edges: FileGraphEdge[],
+	from: string,
+	resolution: FileDepResolution,
+	scopeRoot: string,
+	ownsPath: (path: string) => boolean,
+	seen: EdgeSeen,
+): void {
+	if (resolution.kind === "unresolved") return;
+	if (resolution.kind === "external") {
+		if (seen.external.has(resolution.id)) return;
+		seen.external.add(resolution.id);
+		edges.push({ kind: "external", from, id: resolution.id });
+		return;
+	}
+	if (resolution.kind === "package") {
+		if (!isWithin(scopeRoot, resolution.dir) || seen.package.has(resolution.dir)) return;
+		seen.package.add(resolution.dir);
+		edges.push({
+			kind: "package",
+			from,
+			id: resolution.id,
+			dir: resolution.dir,
+			fileCount: resolution.fileCount,
+		});
+		return;
+	}
+	appendInternalPaths(edges, from, resolution.paths, scopeRoot, ownsPath, seen.internal);
+}
+
+function recordImporter(byTarget: Map<string, string[]>, target: string, from: string): void {
+	const list = byTarget.get(target);
+	if (list === undefined) byTarget.set(target, [from]);
+	else if (!list.includes(from)) list.push(from);
+}
+
+type ForwardHitState = {
+	hits: FileDepHit[];
+	resultLimitReached: boolean;
+	externalOmitted: number;
+	inRepoCount: number;
+	externalCount: number;
+	listedInternal: Set<string>;
+	listedPackage: Set<string>;
+	listedExternal: Set<string>;
+};
+
+function pushForwardEdge(
+	state: ForwardHitState,
+	edge: FileGraphEdge,
+	nextDepth: number,
+	resultLimit: number,
+	enqueue: (next: string) => void,
+): boolean {
+	if (edge.kind === "external") {
+		if (state.listedExternal.has(edge.id)) return true;
+		state.listedExternal.add(edge.id);
+		if (state.externalCount >= EXTERNAL_HIT_LIMIT) {
+			state.externalOmitted += 1;
+			return true;
+		}
+		state.externalCount += 1;
+		state.hits.push({ depth: nextDepth, kind: "external", id: edge.id });
+		return true;
+	}
+	if (state.inRepoCount >= resultLimit) {
+		state.resultLimitReached = true;
+		return false;
+	}
+	if (edge.kind === "package") {
+		if (state.listedPackage.has(edge.dir)) return true;
+		state.listedPackage.add(edge.dir);
+		state.inRepoCount += 1;
+		state.hits.push({
+			depth: nextDepth,
+			kind: "package",
+			id: edge.id,
+			dir: edge.dir,
+			fileCount: edge.fileCount,
+		});
+		return true;
+	}
+	if (state.listedInternal.has(edge.to)) return true;
+	state.listedInternal.add(edge.to);
+	state.inRepoCount += 1;
+	state.hits.push({ depth: nextDepth, kind: "internal", path: edge.to });
+	enqueue(edge.to);
+	return true;
+}
+
+/** Breadth-first walk bounded by depth. `expand` returns false to stop the walk. */
+async function walkDepth(
+	seedPath: string,
+	depth: number,
+	signal: AbortSignal,
+	expand: (path: string, nextDepth: number, enqueue: (next: string) => void) => Promise<boolean>,
+): Promise<void> {
+	const queue: { path: string; depth: number }[] = [{ path: seedPath, depth: 0 }];
+	const visited = new Set<string>([seedPath]);
+	while (queue.length > 0) {
+		signal.throwIfAborted();
+		const current = queue.shift();
+		if (current === undefined) break;
+		if (current.depth >= depth) continue;
+		const nextDepth = current.depth + 1;
+		const enqueue = (next: string): void => {
+			if (nextDepth >= depth || visited.has(next)) return;
+			visited.add(next);
+			queue.push({ path: next, depth: nextDepth });
+		};
+		if (!(await expand(current.path, nextDepth, enqueue))) break;
+	}
+}
+
 /**
  * Session file-import graph. Shared code never interprets import syntax —
  * adapters own resolveFileDep.
@@ -152,33 +301,35 @@ export function createFileGraph(engine: ExploreEngine): ExploreFileGraph {
 
 		const host = makeHost(scopeRoot);
 		const edges: FileGraphEdge[] = [];
-		const seenInternal = new Set<string>();
-		const seenExternal = new Set<string>();
-
+		const seen = emptyEdgeSeen();
 		for (const imp of ir.imports) {
 			signal.throwIfAborted();
 			const resolution = await resolveFileDep(absolutePath, imp.specifier, host, signal);
-			if (resolution.kind === "unresolved") continue;
-			if (resolution.kind === "external") {
-				if (seenExternal.has(resolution.id)) continue;
-				seenExternal.add(resolution.id);
-				edges.push({ kind: "external", from: absolutePath, id: resolution.id });
-				continue;
-			}
-			for (const target of sortUnique(resolution.paths)) {
-				if (!isWithin(scopeRoot, target)) continue;
-				if (!host.ownsPath(target)) continue;
-				if (target === absolutePath) continue;
-				if (seenInternal.has(target)) continue;
-				seenInternal.add(target);
-				edges.push({ kind: "internal", from: absolutePath, to: target });
-			}
+			appendResolution(edges, absolutePath, resolution, scopeRoot, host.ownsPath, seen);
 		}
 
 		forwardCache.set(absolutePath, { contentHash: ir.contentHash, edges });
 		return edges;
 	};
 
+	const indexForwardImporters = async (
+		filePath: string,
+		scopeRoot: string,
+		byTarget: Map<string, string[]>,
+		signal: AbortSignal,
+	): Promise<void> => {
+		const adapter = engine.registry.adapterForPath(filePath);
+		if (adapter?.capabilities.fileDeps !== true || adapter.resolveFileDep === undefined) return;
+		try {
+			const edges = await loadForward(filePath, scopeRoot, signal);
+			for (const edge of edges) {
+				if (edge.kind === "internal") recordImporter(byTarget, edge.to, edge.from);
+			}
+		} catch {
+			// Skip files that fail resolve/parse during reverse build; keep scanning.
+		}
+	};
+
 	const ensureReverse = async (scopeRoot: string, signal: AbortSignal): Promise<ReverseIndex> => {
 		const cached = reverseCache.get(scopeRoot);
 		if (cached !== undefined) return cached;
@@ -193,21 +344,7 @@ export function createFileGraph(engine: ExploreEngine): ExploreFileGraph {
 		let step = await scan.next();
 		while (!step.done) {
 			signal.throwIfAborted();
-			const filePath = step.value.ir.path;
-			const adapter = engine.registry.adapterForPath(filePath);
-			if (adapter?.capabilities.fileDeps === true && adapter.resolveFileDep !== undefined) {
-				try {
-					const edges = await loadForward(filePath, scopeRoot, signal);
-					for (const edge of edges) {
-						if (edge.kind !== "internal") continue;
-						const list = byTarget.get(edge.to);
-						if (list === undefined) byTarget.set(edge.to, [edge.from]);
-						else if (!list.includes(edge.from)) list.push(edge.from);
-					}
-				} catch {
-					// Skip files that fail resolve/parse during reverse build; keep scanning.
-				}
-			}
+			await indexForwardImporters(step.value.ir.path, scopeRoot, byTarget, signal);
 			step = await scan.next();
 		}
 
@@ -227,46 +364,33 @@ export function createFileGraph(engine: ExploreEngine): ExploreFileGraph {
 		signal: AbortSignal,
 	): Promise<FileDepQueryResult> => {
 		const scopeRoot = await scopeRootFor(seedPath, engine.cwd);
-		const hits: FileDepHit[] = [];
-		let resultLimitReached = false;
-		const listedInternal = new Set<string>();
-		const listedExternal = new Set<string>();
-
-		const queue: { path: string; depth: number }[] = [{ path: seedPath, depth: 0 }];
-		const visited = new Set<string>([seedPath]);
-
-		while (queue.length > 0) {
-			signal.throwIfAborted();
-			const current = queue.shift();
-			if (current === undefined) break;
-			if (current.depth >= depth) continue;
-
-			const edges = await loadForward(current.path, scopeRoot, signal);
-			const nextDepth = current.depth + 1;
-
+		const state: ForwardHitState = {
+			hits: [],
+			resultLimitReached: false,
+			externalOmitted: 0,
+			inRepoCount: 0,
+			externalCount: 0,
+			listedInternal: new Set(),
+			listedPackage: new Set(),
+			listedExternal: new Set(),
+		};
+
+		await walkDepth(seedPath, depth, signal, async (path, nextDepth, enqueue) => {
+			const edges = await loadForward(path, scopeRoot, signal);
 			for (const edge of edges) {
-				if (hits.length >= resultLimit) {
-					resultLimitReached = true;
-					break;
-				}
-				if (edge.kind === "external") {
-					if (listedExternal.has(edge.id)) continue;
-					listedExternal.add(edge.id);
-					hits.push({ depth: nextDepth, path: undefined, externalId: edge.id });
-					continue;
-				}
-				if (listedInternal.has(edge.to)) continue;
-				listedInternal.add(edge.to);
-				hits.push({ depth: nextDepth, path: edge.to, externalId: undefined });
-				if (nextDepth < depth && !visited.has(edge.to)) {
-					visited.add(edge.to);
-					queue.push({ path: edge.to, depth: nextDepth });
-				}
+				if (!pushForwardEdge(state, edge, nextDepth, resultLimit, enqueue)) break;
 			}
-			if (resultLimitReached) break;
-		}
+			return !state.resultLimitReached;
+		});
 
-		return { seedPath, depth, hits, resultLimit, resultLimitReached };
+		return {
+			seedPath,
+			depth,
+			hits: state.hits,
+			resultLimit,
+			resultLimitReached: state.resultLimitReached,
+			externalOmitted: state.externalOmitted,
+		};
 	};
 
 	const collectReverseHits = async (
@@ -281,17 +405,8 @@ export function createFileGraph(engine: ExploreEngine): ExploreFileGraph {
 		let resultLimitReached = false;
 		const listed = new Set<string>();
 
-		const queue: { path: string; depth: number }[] = [{ path: seedPath, depth: 0 }];
-		const visited = new Set<string>([seedPath]);
-
-		while (queue.length > 0) {
-			signal.throwIfAborted();
-			const current = queue.shift();
-			if (current === undefined) break;
-			if (current.depth >= depth) continue;
-
-			const importers = index.byTarget.get(current.path) ?? [];
-			const nextDepth = current.depth + 1;
+		await walkDepth(seedPath, depth, signal, async (path, nextDepth, enqueue) => {
+			const importers = index.byTarget.get(path) ?? [];
 			for (const importer of importers) {
 				if (hits.length >= resultLimit) {
 					resultLimitReached = true;
@@ -299,16 +414,13 @@ export function createFileGraph(engine: ExploreEngine): ExploreFileGraph {
 				}
 				if (listed.has(importer)) continue;
 				listed.add(importer);
-				hits.push({ depth: nextDepth, path: importer, externalId: undefined });
-				if (nextDepth < depth && !visited.has(importer)) {
-					visited.add(importer);
-					queue.push({ path: importer, depth: nextDepth });
-				}
+				hits.push({ depth: nextDepth, kind: "internal", path: importer });
+				enqueue(importer);
 			}
-			if (resultLimitReached) break;
-		}
+			return !resultLimitReached;
+		});
 
-		return { seedPath, depth, hits, resultLimit, resultLimitReached };
+		return { seedPath, depth, hits, resultLimit, resultLimitReached, externalOmitted: 0 };
 	};
 
 	const resolveSeedFile = async (pathInput: string): Promise<string> => {