@shanepadgett/tau-agent 0.33.1 → 0.35.0

package/src/ast/queries/impact.ts

@@ -0,0 +1,291 @@
+import type { ExploreEngine } from "../engine.ts";
+import type { Candidate } from "../identity.ts";
+import type { ExploreFileGraph, FileDepHit, FileDepTarget, FileGraphEdge } from "../graph/file-graph.ts";
+import {
+	queryRelationships,
+	type RelationshipCertainty,
+	type RelationshipSite,
+	type RelationshipSiteKind,
+} from "../graph/relationships.ts";
+import { resolveCompositeTarget, type CompositeTarget } from "./composite-target.ts";
+
+const IMPACT_SECTION_LIMIT = 50;
+/** File edges are lower value per row than symbol sites; a module import can carry hundreds. */
+const IMPACT_FILE_LIMIT = 20;
+export const IMPACT_DEPTH_DEFAULT = 2;
+export const IMPACT_DEPTH_MAX = 5;
+
+export type ImpactMode = "all" | "deps" | "dependents";
+
+export type ImpactSectionId = "callees" | "fileImports" | "callers" | "fileImporters" | "transitiveDependents";
+
+export type ImpactSiteRow = {
+	kind: "site";
+	path: string;
+	line: number;
+	siteKind: RelationshipSiteKind;
+	name: string;
+	preview: string;
+	certainty: RelationshipCertainty;
+};
+
+export type ImpactFileRow = {
+	kind: "file";
+	depth: number;
+	target: FileDepTarget;
+};
+
+export type ImpactRow = ImpactSiteRow | ImpactFileRow;
+
+export type ImpactSection = {
+	id: ImpactSectionId;
+	label: string;
+	rows: ImpactRow[];
+	limit: number;
+	omitted: boolean;
+};
+
+export type ImpactTarget = CompositeTarget;
+
+export type ImpactResult =
+	| {
+			kind: "resolved";
+			target: ImpactTarget;
+			sections: ImpactSection[];
+			parseDegraded: boolean;
+			notes: string[];
+	  }
+	| { kind: "candidates"; candidates: Candidate[] }
+	| { kind: "notFound" }
+	| { kind: "error"; message: string };
+
+export type ImpactQueryArgs = {
+	engine: ExploreEngine;
+	graph: ExploreFileGraph;
+	scopePath: string;
+	targetPath: string | undefined;
+	name: string;
+	line: number | undefined;
+	depth: number;
+	mode: ImpactMode;
+	signal: AbortSignal;
+};
+
+function siteRows(sites: readonly RelationshipSite[]): ImpactSiteRow[] {
+	return sites.slice(0, IMPACT_SECTION_LIMIT).map((site) => ({
+		kind: "site" as const,
+		path: site.path,
+		line: site.line,
+		siteKind: site.kind,
+		name: site.name,
+		preview: site.preview,
+		certainty: site.certainty,
+	}));
+}
+
+function fileRowsFromEdges(edges: readonly FileGraphEdge[]): ImpactFileRow[] {
+	const rows: ImpactFileRow[] = [];
+	for (const edge of edges) {
+		if (rows.length >= IMPACT_FILE_LIMIT) break;
+		if (edge.kind === "internal") {
+			rows.push({ kind: "file", depth: 1, target: { kind: "internal", path: edge.to } });
+			continue;
+		}
+		if (edge.kind === "package") {
+			rows.push({
+				kind: "file",
+				depth: 1,
+				target: { kind: "package", id: edge.id, dir: edge.dir, fileCount: edge.fileCount },
+			});
+			continue;
+		}
+		rows.push({ kind: "file", depth: 1, target: { kind: "external", id: edge.id } });
+	}
+	return rows;
+}
+
+function fileRowsFromHits(hits: readonly FileDepHit[]): ImpactFileRow[] {
+	return hits.slice(0, IMPACT_FILE_LIMIT).map((hit): ImpactFileRow => {
+		const { depth, ...target } = hit;
+		return { kind: "file", depth, target };
+	});
+}
+
+function noteFromError(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+function maybeFileSection(
+	id: ImpactSectionId,
+	label: string,
+	rows: ImpactFileRow[],
+	totalCount: number,
+	limitReached = false,
+): ImpactSection | undefined {
+	if (rows.length === 0) return undefined;
+	return {
+		id,
+		label,
+		rows,
+		limit: IMPACT_FILE_LIMIT,
+		omitted: totalCount > IMPACT_FILE_LIMIT || limitReached,
+	};
+}
+
+type SectionBatch = {
+	sections: ImpactSection[];
+	parseDegraded: boolean;
+	notes: string[];
+};
+
+function emptyBatch(): SectionBatch {
+	return { sections: [], parseDegraded: false, notes: [] };
+}
+
+function absorbRelationship(
+	batch: SectionBatch,
+	part: { section: ImpactSection | undefined; parseDegraded: boolean; note: string | undefined },
+): void {
+	if (part.section !== undefined) batch.sections.push(part.section);
+	if (part.parseDegraded) batch.parseDegraded = true;
+	if (part.note !== undefined) batch.notes.push(part.note);
+}
+
+async function relationshipSection(
+	args: ImpactQueryArgs,
+	op: "callees" | "callers",
+	id: ImpactSectionId,
+	label: string,
+	target: ImpactTarget,
+): Promise<{ section: ImpactSection | undefined; parseDegraded: boolean; note: string | undefined }> {
+	const result = await queryRelationships({
+		engine: args.engine,
+		graph: args.graph,
+		scopePath: args.scopePath,
+		op,
+		targetPath: target.path,
+		name: target.name,
+		line: target.startLine,
+		resultLimit: IMPACT_SECTION_LIMIT,
+		signal: args.signal,
+	});
+	if (result.kind === "resolved") {
+		const rows = siteRows(result.sites);
+		if (rows.length === 0) return { section: undefined, parseDegraded: result.parseDegraded, note: undefined };
+		return {
+			section: {
+				id,
+				label,
+				rows,
+				limit: IMPACT_SECTION_LIMIT,
+				omitted: result.resultLimitReached || result.sites.length > IMPACT_SECTION_LIMIT,
+			},
+			parseDegraded: result.parseDegraded,
+			note: undefined,
+		};
+	}
+	if (result.kind === "error") {
+		return { section: undefined, parseDegraded: false, note: result.message };
+	}
+	return { section: undefined, parseDegraded: false, note: undefined };
+}
+
+async function collectDepsSections(args: ImpactQueryArgs, target: ImpactTarget): Promise<SectionBatch> {
+	const batch = emptyBatch();
+	absorbRelationship(batch, await relationshipSection(args, "callees", "callees", "callees", target));
+	try {
+		const edges = await args.graph.forwardEdges(target.path, args.signal);
+		const section = maybeFileSection("fileImports", "file imports", fileRowsFromEdges(edges), edges.length);
+		if (section !== undefined) batch.sections.push(section);
+	} catch (error) {
+		batch.notes.push(noteFromError(error));
+	}
+	return batch;
+}
+
+async function collectDependentsSections(
+	args: ImpactQueryArgs,
+	target: ImpactTarget,
+	depth: number,
+): Promise<SectionBatch> {
+	const batch = emptyBatch();
+	absorbRelationship(batch, await relationshipSection(args, "callers", "callers", "callers", target));
+	try {
+		const reverseLimit = IMPACT_SECTION_LIMIT * Math.max(depth, 1);
+		const reverse = await args.graph.reverseDeps(target.path, depth, reverseLimit, args.signal);
+		const importerHits = reverse.hits.filter((hit) => hit.depth === 1);
+		const importers = maybeFileSection(
+			"fileImporters",
+			"file importers",
+			fileRowsFromHits(importerHits),
+			importerHits.length,
+		);
+		if (importers !== undefined) batch.sections.push(importers);
+
+		if (depth >= 2) {
+			const transitiveHits = reverse.hits.filter((hit) => hit.depth >= 2 && hit.depth <= depth);
+			const transitive = maybeFileSection(
+				"transitiveDependents",
+				"transitive dependents",
+				fileRowsFromHits(transitiveHits),
+				transitiveHits.length,
+				reverse.resultLimitReached,
+			);
+			if (transitive !== undefined) batch.sections.push(transitive);
+		}
+	} catch (error) {
+		batch.notes.push(noteFromError(error));
+	}
+	return batch;
+}
+
+function mergeBatch(into: SectionBatch, part: SectionBatch): void {
+	into.sections.push(...part.sections);
+	if (part.parseDegraded) into.parseDegraded = true;
+	into.notes.push(...part.notes);
+}
+
+/**
+ * Blast radius composite: symbol callees/callers + file imports/importers + transitive file dependents.
+ * Symbol hops are depth 1 only; `depth` applies to reverse file BFS only.
+ */
+export async function queryImpact(args: ImpactQueryArgs): Promise<ImpactResult> {
+	if (args.depth < 1) {
+		return { kind: "error", message: "depth must be >= 1" };
+	}
+	const depth = Math.min(args.depth, IMPACT_DEPTH_MAX);
+
+	const resolved = await resolveCompositeTarget(
+		args.engine,
+		args.scopePath,
+		args.targetPath,
+		args.name,
+		args.line,
+		"impact",
+		args.signal,
+	);
+	if (resolved.kind !== "resolved") return resolved;
+
+	const target = resolved.value.target;
+	const mode = args.mode;
+	const batch: SectionBatch = {
+		sections: [],
+		parseDegraded: resolved.value.parseDegraded,
+		notes: [],
+	};
+
+	if (mode === "all" || mode === "deps") {
+		mergeBatch(batch, await collectDepsSections(args, target));
+	}
+	if (mode === "all" || mode === "dependents") {
+		mergeBatch(batch, await collectDependentsSections(args, target, depth));
+	}
+
+	return {
+		kind: "resolved",
+		target,
+		sections: batch.sections,
+		parseDegraded: batch.parseDegraded,
+		notes: [...new Set(batch.notes)],
+	};
+}

package/{extensions/explore → src}/ast/queries/outline.ts

@@ -4,7 +4,7 @@ import type { Decl, DeclKind, FileIr } from "../ir.ts";
 import { filterDeclForest, walkDecls } from "../query.ts";
 import { scanSources, type ScanOutcome } from "../scan.ts";
 import { docsText, signatureText } from "../slice.ts";
-import { formatPathForDisplay, pathResolutionError, resolveExplorePath, walkPaths } from "../../traverse.ts";
+import { formatPathForDisplay, pathResolutionError, resolveExplorePath, walkPaths } from "../traverse.ts";
 
 export type OutlineOptions = {
 	includePrivate: boolean;
@@ -38,7 +38,9 @@ export type OutlineResult = { mode: "file"; file: OutlineFileView } | { mode: "d
 
 function keepVisibility(includePrivate: boolean): (decl: Decl) => boolean {
 	if (includePrivate) return () => true;
-	return (decl) => decl.visibility === "public" || decl.visibility === "protected";
+	// Only file/type-private declarations are hidden. `internal` (pub(crate), Go
+	// package scope, C#/Kotlin internal) is module-visible surface a caller needs.
+	return (decl) => decl.visibility !== "private";
 }
 
 /** Keep decls that match a name, or ancestors of a match (structure preserved). */

package/{extensions/explore → src}/ast/queries/show.ts

@@ -3,7 +3,7 @@ import type { Candidate, Target } from "../identity.ts";
 import { resolveTarget } from "../identity.ts";
 import type { Decl, FileIr, ImportRef } from "../ir.ts";
 import { declarationText, signatureText, signatureWithDocsText } from "../slice.ts";
-import { formatPathForDisplay, stripLeadingAt } from "../../traverse.ts";
+import { formatPathForDisplay, stripLeadingAt } from "../traverse.ts";
 
 export type ShowView = "signature" | "signatureWithDocs" | "declaration" | "declarationWithImports";
 
@@ -199,6 +199,48 @@ function formatCandidateError(label: string, candidates: readonly Candidate[], c
 	return lines.join("\n");
 }
 
+function targetLabel(target: ShowTargetInput): string {
+	return target.line === undefined
+		? `${target.name} @ ${target.path}`
+		: `${target.name} @ ${target.path}:${target.line}`;
+}
+
+async function resolveShowBlock(
+	engine: ExploreEngine,
+	target: ShowTargetInput,
+	view: ShowView,
+	context: number,
+	signal: AbortSignal,
+): Promise<ShowBlock> {
+	const resolutionTarget: Target = {
+		path: target.path,
+		name: target.name,
+		...(target.line === undefined ? {} : { line: target.line }),
+	};
+	const resolution = await resolveTarget(engine, engine.cwd, resolutionTarget, signal);
+	const label = targetLabel(target);
+	if (resolution.kind === "notFound") {
+		throw new Error(`No declaration matched ${label}`);
+	}
+	if (resolution.kind === "candidates") {
+		throw new Error(formatCandidateError(label, resolution.candidates, engine.cwd));
+	}
+	const adapter = engine.registry.adapterForPath(resolution.path);
+	const importNoise = adapter?.importNoiseIdentifiers ?? NO_IMPORT_NOISE;
+	return buildBlock(resolution.decl, resolution.path, resolution.ir, resolution.source, view, context, importNoise);
+}
+
+function dedupeDocWarnings(blocks: ShowBlock[]): void {
+	let docsWarningEmitted = false;
+	for (const block of blocks) {
+		if (docsWarningEmitted) {
+			block.warnings = block.warnings.filter((warning) => warning !== "no attached documentation");
+		} else if (block.warnings.includes("no attached documentation")) {
+			docsWarningEmitted = true;
+		}
+	}
+}
+
 /**
  * Resolve every target before emitting. Any missing/ambiguous target fails the whole batch.
  * `contextLines` must be omitted (undefined) unless view is declaration.
@@ -214,49 +256,11 @@ export async function showTargets(
 		throw new Error("contextLines is supported only with view=declaration");
 	}
 	const context = contextLines ?? 0;
-
-	const unique = dedupeShowTargets(targets);
 	const blocks: ShowBlock[] = [];
-	let docsWarningEmitted = false;
-
-	for (const target of unique) {
+	for (const target of dedupeShowTargets(targets)) {
 		signal.throwIfAborted();
-		const resolutionTarget: Target = {
-			path: target.path,
-			name: target.name,
-			...(target.line === undefined ? {} : { line: target.line }),
-		};
-		const resolution = await resolveTarget(engine, engine.cwd, resolutionTarget, signal);
-		const label =
-			target.line === undefined
-				? `${target.name} @ ${target.path}`
-				: `${target.name} @ ${target.path}:${target.line}`;
-
-		if (resolution.kind === "notFound") {
-			throw new Error(`No declaration matched ${label}`);
-		}
-		if (resolution.kind === "candidates") {
-			throw new Error(formatCandidateError(label, resolution.candidates, engine.cwd));
-		}
-
-		const adapter = engine.registry.adapterForPath(resolution.path);
-		const importNoise = adapter?.importNoiseIdentifiers ?? NO_IMPORT_NOISE;
-		const block = buildBlock(
-			resolution.decl,
-			resolution.path,
-			resolution.ir,
-			resolution.source,
-			view,
-			context,
-			importNoise,
-		);
-		if (docsWarningEmitted) {
-			block.warnings = block.warnings.filter((warning) => warning !== "no attached documentation");
-		} else if (block.warnings.includes("no attached documentation")) {
-			docsWarningEmitted = true;
-		}
-		blocks.push(block);
+		blocks.push(await resolveShowBlock(engine, target, view, context, signal));
 	}
-
+	dedupeDocWarnings(blocks);
 	return { blocks };
 }

package/{extensions/explore → src}/ast/query.ts

@@ -12,7 +12,7 @@ export function walkDecls(decls: readonly Decl[], visit: (decl: Decl, depth: num
 }
 
 function nameMatches(decl: Decl, name: string): boolean {
-	return decl.name === name || decl.qualifiedName === name;
+	return decl.name === name || decl.qualifiedName === name || decl.qualifiedName.endsWith(`.${name}`);
 }
 
 function coversLine(decl: Decl, line: number): boolean {

package/{extensions/explore → src}/ast/registry.ts

@@ -4,7 +4,6 @@ import { csharpAdapter } from "./languages/csharp.ts";
 import { goAdapter } from "./languages/go.ts";
 import { javaAdapter } from "./languages/java.ts";
 import { kotlinAdapter } from "./languages/kotlin.ts";
-import { odinAdapter } from "./languages/odin.ts";
 import { rustAdapter } from "./languages/rust.ts";
 import { swiftAdapter } from "./languages/swift.ts";
 import { tsxAdapter, typescriptAdapter } from "./languages/typescript.ts";
@@ -34,6 +33,7 @@ const MARKDOWN_CAPABILITIES: LanguageCapabilities = {
 	fileDeps: false,
 	callEdges: false,
 	packageSurface: false,
+	structuralImplements: false,
 };
 
 function markdownAdapter(): LanguageAdapter {
@@ -115,6 +115,5 @@ export function createDefaultRegistry(): AdapterRegistry {
 		javaAdapter(),
 		kotlinAdapter(),
 		swiftAdapter(),
-		odinAdapter(),
 	]);
 }

package/{extensions/explore → src}/ast/scan.ts

@@ -1,5 +1,5 @@
 import type { ExploreEngine, FileSource } from "./engine.ts";
-import { DEFAULT_TRAVERSAL_BUDGETS, type TraversalBudgets, type TraversalLimit, walkPaths } from "../traverse.ts";
+import { DEFAULT_TRAVERSAL_BUDGETS, type TraversalBudgets, type TraversalLimit, walkPaths } from "./traverse.ts";
 
 export type ScanOptions = {
 	engine: ExploreEngine;

package/src/ast/session.ts

@@ -0,0 +1,50 @@
+import { resolve } from "node:path";
+import { createExploreEngine, type ExploreEngine } from "./engine.ts";
+import { createFileGraph, type ExploreFileGraph } from "./graph/file-graph.ts";
+
+// One engine and file graph per process. Explore tools and file injection share
+// the same parse caches instead of standing up competing engines per caller.
+let current: { engine: ExploreEngine; graph: ExploreFileGraph } | undefined;
+
+function sessionFor(cwd: string): { engine: ExploreEngine; graph: ExploreFileGraph } {
+	const absoluteCwd = resolve(cwd);
+	if (current !== undefined && current.engine.cwd === absoluteCwd) return current;
+	current?.engine.shutdown();
+	current?.graph.clear();
+	const engine = createExploreEngine({ cwd: absoluteCwd });
+	current = { engine, graph: createFileGraph(engine) };
+	return current;
+}
+
+export function astEngineFor(cwd: string): ExploreEngine {
+	return sessionFor(cwd).engine;
+}
+
+export function astGraphFor(cwd: string): ExploreFileGraph {
+	return sessionFor(cwd).graph;
+}
+
+export function restartAstSession(cwd: string): void {
+	current?.engine.shutdown();
+	current?.graph.clear();
+	current = undefined;
+	sessionFor(cwd);
+}
+
+export function invalidateAstPaths(paths: readonly string[], topologyChanged: boolean): void {
+	if (current === undefined) return;
+	current.engine.invalidate([...paths]);
+	if (topologyChanged) current.graph.clear();
+	else current.graph.invalidate([...paths]);
+}
+
+export function clearAstSession(): void {
+	current?.engine.clear();
+	current?.graph.clear();
+}
+
+export function shutdownAstSession(): void {
+	current?.engine.shutdown();
+	current?.graph.clear();
+	current = undefined;
+}

package/{extensions/explore → src}/ast/slice.ts

@@ -27,6 +27,14 @@ export function docsText(decl: Decl, source: string): string | undefined {
 	return text.length === 0 ? undefined : text;
 }
 
+const COMPACT_SIGNATURE_MAX = 80;
+
+/** One-line signature for row output: whitespace collapsed, capped. */
+export function compactSignature(text: string): string {
+	const collapsed = text.replace(/\s+/gu, " ").trim();
+	return collapsed.length > COMPACT_SIGNATURE_MAX ? `${collapsed.slice(0, COMPACT_SIGNATURE_MAX - 3)}...` : collapsed;
+}
+
 /** Full declaration span [startOffset, endOffset) — no leading docs. */
 export function declarationText(decl: Decl, source: string): string {
 	return source.slice(decl.startOffset, decl.endOffset);

package/{extensions/explore → src/ast}/traverse.ts

@@ -350,17 +350,15 @@ export async function walkPaths(options: WalkOptions): Promise<TraversalResult>
 		return { entries, limit, filesVisited, sourceBytes, elapsedMs: elapsed() };
 	}
 
-	async function walkDir(directory: string, depth: number, rules: readonly IgnoreRule[]): Promise<void> {
-		if (stopIfNeeded()) return;
-		if (depth >= budgets.maxDepth) {
-			limit = limit ?? "maxDepth";
-			return;
-		}
-
+	async function listChildren(
+		directory: string,
+		depth: number,
+		rules: readonly IgnoreRule[],
+	): Promise<TraversalHit[] | undefined> {
 		const names = await listNames(directory, options.cwd);
 		const children: TraversalHit[] = [];
 		for (const name of names) {
-			if (stopIfNeeded()) return;
+			if (stopIfNeeded()) return undefined;
 			const childPath = join(directory, name);
 			let stats: Stats;
 			try {
@@ -378,20 +376,34 @@ export async function walkPaths(options: WalkOptions): Promise<TraversalResult>
 				depth: depth + 1,
 			});
 		}
+		return sortHits(children);
+	}
+
+	async function visitChild(child: TraversalHit, rules: readonly IgnoreRule[]): Promise<boolean> {
+		if (child.type === "file") return pushFile(child);
+		if (!filesOnly) entries.push(child);
+		if (child.depth >= budgets.maxDepth) {
+			limit = limit ?? "maxDepth";
+			return true;
+		}
+		const childRules = includeIgnored ? rules : await appendIgnoreRules(child.absolutePath, rules);
+		await walkDir(child.absolutePath, child.depth, childRules);
+		return true;
+	}
+
+	async function walkDir(directory: string, depth: number, rules: readonly IgnoreRule[]): Promise<void> {
+		if (stopIfNeeded()) return;
+		if (depth >= budgets.maxDepth) {
+			limit = limit ?? "maxDepth";
+			return;
+		}
+
+		const children = await listChildren(directory, depth, rules);
+		if (children === undefined) return;
 
-		for (const child of sortHits(children)) {
+		for (const child of children) {
 			if (stopIfNeeded()) return;
-			if (child.type === "file") {
-				if (!(await pushFile(child))) return;
-				continue;
-			}
-			if (!filesOnly) entries.push(child);
-			if (child.depth >= budgets.maxDepth) {
-				limit = limit ?? "maxDepth";
-				continue;
-			}
-			const childRules = includeIgnored ? rules : await appendIgnoreRules(child.absolutePath, rules);
-			await walkDir(child.absolutePath, child.depth, childRules);
+			if (!(await visitChild(child, rules))) return;
 		}
 	}