@shanepadgett/tau-agent 0.27.0 → 0.28.1

package/extensions/explore/ast/format/ast-search.ts

@@ -0,0 +1,97 @@
+import type { AstSearchMatch, AstSearchResult } from "../queries/ast-search.ts";
+import type { ScanOutcome } from "../scan.ts";
+import type { TraversalLimit } from "../../traverse.ts";
+import { formatPathForDisplay } from "../../traverse.ts";
+
+function lineRange(startLine: number, endLine: number): string {
+	return startLine === endLine ? `L${startLine}` : `L${startLine}-${endLine}`;
+}
+
+function formatMatchRows(match: AstSearchMatch): string[] {
+	const lines: string[] = [];
+	const preview = match.text.length > 0 ? match.text : "(empty)";
+	const previewLines = preview.split("\n");
+	const first = previewLines[0] ?? "(empty)";
+	lines.push(`${lineRange(match.startLine, match.endLine)} ${first}`);
+	for (let i = 1; i < previewLines.length; i += 1) {
+		lines.push(`  ${previewLines[i] ?? ""}`);
+	}
+	for (const binding of match.bindings) {
+		const bindLines = binding.text.split("\n");
+		lines.push(`  $${binding.name} = ${bindLines[0] ?? ""}`);
+		for (let i = 1; i < bindLines.length; i += 1) {
+			lines.push(`    ${bindLines[i] ?? ""}`);
+		}
+	}
+	if (match.enclosing !== undefined) {
+		lines.push(`  in ${match.enclosing.kind} ${match.enclosing.name} L${match.enclosing.startLine}`);
+	}
+	if (match.parseDegraded) {
+		lines.push("  warning: parser recovered with errors");
+	}
+	return lines;
+}
+
+/** One complete file group (path header + matches). */
+export function formatAstSearchFile(path: string, matches: readonly AstSearchMatch[], cwd: string): string {
+	const lines = [formatPathForDisplay(path, cwd)];
+	for (const match of matches) {
+		lines.push(...formatMatchRows(match));
+	}
+	return lines.join("\n");
+}
+
+export function formatAstSearchEmpty(): string {
+	return "No matches";
+}
+
+function limitLabel(limit: TraversalLimit): string {
+	switch (limit) {
+		case "maxFiles":
+			return "file count";
+		case "maxSourceBytes":
+			return "source bytes";
+		case "maxDepth":
+			return "depth";
+		case "maxElapsedMs":
+			return "elapsed time";
+		case "cancelled":
+			return "cancelled";
+	}
+}
+
+/** Footers only when something was cut, a budget tripped, or file diagnostics exist. */
+export function formatAstSearchFooters(result: AstSearchResult, cwd: string): string | undefined {
+	const limits: string[] = [];
+	if (result.resultLimitReached) {
+		limits.push(`matches omitted (result limit ${result.resultLimit})`);
+	}
+	const scan: ScanOutcome | undefined = result.scan;
+	if (scan?.limit !== undefined && scan.limit !== "cancelled") {
+		limits.push(limitLabel(scan.limit));
+	}
+	const diagnostics = result.fileErrors.map((err) => `${formatPathForDisplay(err.path, cwd)}: ${err.message}`);
+	const parts: string[] = [];
+	if (limits.length > 0) parts.push(`limits reached: ${limits.join(", ")}`);
+	if (diagnostics.length > 0) parts.push(`file errors: ${diagnostics.join("; ")}`);
+	if (parts.length === 0) return undefined;
+	return parts.join("\n");
+}
+
+/** Group matches by file (path order of first appearance). */
+export function groupAstSearchByFile(
+	matches: readonly AstSearchMatch[],
+): { path: string; matches: AstSearchMatch[] }[] {
+	const groups: { path: string; matches: AstSearchMatch[] }[] = [];
+	const indexByPath = new Map<string, number>();
+	for (const match of matches) {
+		const existing = indexByPath.get(match.path);
+		if (existing === undefined) {
+			indexByPath.set(match.path, groups.length);
+			groups.push({ path: match.path, matches: [match] });
+		} else {
+			groups[existing]?.matches.push(match);
+		}
+	}
+	return groups;
+}

package/extensions/explore/ast/format/composite.ts

@@ -0,0 +1,26 @@
+export type CompositeBlock = {
+	id: string;
+	label: string;
+	text: string;
+};
+
+/** Shared section packing for impact/context complete-block emission. */
+export function compositeSectionBlocks(args: {
+	header: string;
+	emptyLabel: string;
+	sections: readonly { id: string; label: string; text: string }[];
+	footers: readonly string[];
+}): CompositeBlock[] {
+	const blocks: CompositeBlock[] = [{ id: "header", label: "header", text: args.header }];
+	if (args.sections.length === 0) {
+		blocks.push({ id: "empty", label: "empty", text: args.emptyLabel });
+	} else {
+		for (const section of args.sections) {
+			blocks.push({ id: section.id, label: section.label, text: section.text });
+		}
+	}
+	if (args.footers.length > 0) {
+		blocks.push({ id: "footer", label: "footer", text: args.footers.join("\n") });
+	}
+	return blocks;
+}

package/extensions/explore/ast/format/context.ts

@@ -0,0 +1,66 @@
+import { formatPathForDisplay } from "../../traverse.ts";
+import type { ContextEntry, ContextGroup, ContextResult, ContextTarget } from "../queries/context.ts";
+import { compositeSectionBlocks, type CompositeBlock } from "./composite.ts";
+import { formatCandidateList } from "./relationships.ts";
+
+function formatTargetHeader(target: ContextTarget, budget: number, used: number, cwd: string): string {
+	const path = formatPathForDisplay(target.path, cwd);
+	return `${target.qualifiedName || target.name}  ${target.kind}  ${path}:${target.startLine}  budget=${budget} used=${used}`;
+}
+
+function formatEntry(entry: ContextEntry, cwd: string): string {
+	const path = formatPathForDisplay(entry.path, cwd);
+	const flags = entry.flags.length > 0 ? `  ${entry.flags.join(",")}` : "";
+	const head = `${path}:${entry.startLine}  ${entry.kind} ${entry.qualifiedName || entry.name}  ~${entry.tokens}tok ${entry.view}${flags}`;
+	return `${head}\n${entry.text}`;
+}
+
+function formatGroup(group: ContextGroup, cwd: string): string {
+	const lines = [`${group.label}:`];
+	for (const entry of group.entries) {
+		lines.push(formatEntry(entry, cwd));
+		lines.push("");
+	}
+	if (lines.at(-1) === "") lines.pop();
+	return lines.join("\n");
+}
+
+function formatResolved(result: Extract<ContextResult, { kind: "resolved" }>, cwd: string): string {
+	const lines = [formatTargetHeader(result.target, result.budget, result.used, cwd)];
+	if (result.groups.length === 0) {
+		lines.push("No context entries.");
+	} else {
+		for (const group of result.groups) {
+			lines.push("");
+			lines.push(formatGroup(group, cwd));
+		}
+	}
+	if (result.truncated) {
+		lines.push("");
+		lines.push("truncated: budget exhausted or entry skipped");
+	}
+	return lines.join("\n");
+}
+
+export function formatContextResult(result: ContextResult, cwd: string): string {
+	if (result.kind === "error") return result.message;
+	if (result.kind === "notFound") return "No matching declaration.";
+	if (result.kind === "candidates") return formatCandidateList(result.candidates, cwd);
+	return formatResolved(result, cwd);
+}
+
+export function contextSectionBlocks(
+	result: Extract<ContextResult, { kind: "resolved" }>,
+	cwd: string,
+): CompositeBlock[] {
+	return compositeSectionBlocks({
+		header: formatTargetHeader(result.target, result.budget, result.used, cwd),
+		emptyLabel: "No context entries.",
+		sections: result.groups.map((group) => ({
+			id: group.id,
+			label: group.label,
+			text: formatGroup(group, cwd),
+		})),
+		footers: result.truncated ? ["truncated: budget exhausted or entry skipped"] : [],
+	});
+}

package/extensions/explore/ast/format/deps.ts

@@ -0,0 +1,86 @@
+import type { FileDepHit, FileDepQueryResult } from "../graph/file-graph.ts";
+import { formatPathForDisplay } from "../../traverse.ts";
+
+function depthPrefix(depth: number, showDepth: boolean): string {
+	return showDepth ? `d${depth} ` : "";
+}
+
+/** Factor shared directory prefixes into a small indent tree. */
+function formatInternalTree(
+	paths: readonly { depth: number; path: string }[],
+	cwd: string,
+	showDepth: boolean,
+): string[] {
+	if (paths.length === 0) return [];
+	const rows = paths.map((hit) => ({
+		depth: hit.depth,
+		display: formatPathForDisplay(hit.path, cwd),
+	}));
+
+	// Common directory prefix across displays (posix-ish split on /).
+	const split = rows.map((row) => row.display.split("/"));
+	let common = 0;
+	const first = split[0];
+	if (first !== undefined && split.length > 1) {
+		while (common < first.length - 1) {
+			const part = first[common];
+			if (part === undefined) break;
+			if (!split.every((parts) => parts[common] === part)) break;
+			common += 1;
+		}
+	}
+
+	const lines: string[] = [];
+	if (common > 0 && first !== undefined) {
+		lines.push(first.slice(0, common).join("/"));
+	}
+
+	for (let i = 0; i < rows.length; i += 1) {
+		const row = rows[i];
+		const parts = split[i];
+		if (row === undefined || parts === undefined) continue;
+		const leaf = common > 0 ? parts.slice(common).join("/") : row.display;
+		const indent = common > 0 ? "  " : "";
+		lines.push(`${indent}${depthPrefix(row.depth, showDepth)}${leaf}`);
+	}
+	return lines;
+}
+
+export function formatDepsResult(result: FileDepQueryResult, cwd: string, emptyLabel: string): string {
+	const showDepth = result.depth > 1;
+	const internal = result.hits
+		.filter((hit): hit is FileDepHit & { path: string } => hit.path !== undefined)
+		.map((hit) => ({ depth: hit.depth, path: hit.path }));
+	const external = result.hits
+		.filter((hit): hit is FileDepHit & { externalId: string } => hit.externalId !== undefined)
+		.map((hit) => ({ depth: hit.depth, id: hit.externalId }));
+
+	if (internal.length === 0 && external.length === 0) {
+		return emptyLabel;
+	}
+
+	const lines: string[] = [];
+	lines.push(...formatInternalTree(internal, cwd, showDepth));
+
+	if (external.length > 0) {
+		if (lines.length > 0) lines.push("external:");
+		else lines.push("external:");
+		for (const hit of external) {
+			lines.push(`  ${depthPrefix(hit.depth, showDepth)}${hit.id}`);
+		}
+	}
+
+	if (result.resultLimitReached) {
+		lines.push(`omitted (result limit ${result.resultLimit})`);
+	}
+
+	return lines.join("\n");
+}
+
+export function formatDepsEmpty(): string {
+	return "No file dependencies";
+}
+
+export function formatReverseDepsEmpty(): string {
+	return "No reverse file dependencies";
+}

package/extensions/explore/ast/format/discover.ts

@@ -0,0 +1,85 @@
+import type { DiscoverCandidate, DiscoverResult } from "../queries/discover.ts";
+import type { ScanOutcome } from "../scan.ts";
+import type { TraversalLimit } from "../../traverse.ts";
+import { formatPathForDisplay } from "../../traverse.ts";
+
+function lineRange(startLine: number, endLine: number): string {
+	return startLine === endLine ? `L${startLine}` : `L${startLine}-${endLine}`;
+}
+
+function formatCandidateRows(candidate: DiscoverCandidate): string[] {
+	const lines: string[] = [];
+	const signature = candidate.signature.length > 0 ? candidate.signature : candidate.name;
+	const sigLines = signature.split("\n");
+	const first = sigLines[0] ?? candidate.name;
+	lines.push(`${lineRange(candidate.startLine, candidate.endLine)} ${candidate.kind}: ${first}`);
+	for (let i = 1; i < sigLines.length; i += 1) {
+		lines.push(`  ${sigLines[i] ?? ""}`);
+	}
+	if (candidate.access !== undefined) {
+		lines.push(`  ${candidate.access}`);
+	}
+	return lines;
+}
+
+/** One complete file group (path header + candidates). */
+export function formatDiscoverFile(path: string, candidates: readonly DiscoverCandidate[], cwd: string): string {
+	const lines = [formatPathForDisplay(path, cwd)];
+	for (const candidate of candidates) {
+		lines.push(...formatCandidateRows(candidate));
+	}
+	return lines.join("\n");
+}
+
+export function formatDiscoverEmpty(): string {
+	return "No matching declarations";
+}
+
+function limitLabel(limit: TraversalLimit): string {
+	switch (limit) {
+		case "maxFiles":
+			return "file count";
+		case "maxSourceBytes":
+			return "source bytes";
+		case "maxDepth":
+			return "depth";
+		case "maxElapsedMs":
+			return "elapsed time";
+		case "cancelled":
+			return "cancelled";
+	}
+}
+
+/** Footers only when something was cut or a budget tripped. */
+export function formatDiscoverFooters(result: DiscoverResult): string | undefined {
+	const parts: string[] = [];
+	if (result.resultLimitReached) {
+		parts.push(`candidates omitted (result limit ${result.resultLimit})`);
+	}
+	if (result.workLimitReached) parts.push("query work");
+	if (result.candidateLimitReached) parts.push("query candidates");
+	const scan: ScanOutcome | undefined = result.scan;
+	if (scan?.limit !== undefined && scan.limit !== "cancelled") {
+		parts.push(limitLabel(scan.limit));
+	}
+	if (parts.length === 0) return undefined;
+	return `limits reached: ${parts.join(", ")}`;
+}
+
+/** Group candidates by defining file (stable path order from caller). */
+export function groupDiscoverByFile(
+	candidates: readonly DiscoverCandidate[],
+): { path: string; candidates: DiscoverCandidate[] }[] {
+	const groups: { path: string; candidates: DiscoverCandidate[] }[] = [];
+	const indexByPath = new Map<string, number>();
+	for (const candidate of candidates) {
+		const existing = indexByPath.get(candidate.path);
+		if (existing === undefined) {
+			indexByPath.set(candidate.path, groups.length);
+			groups.push({ path: candidate.path, candidates: [candidate] });
+		} else {
+			groups[existing]?.candidates.push(candidate);
+		}
+	}
+	return groups;
+}

package/extensions/explore/ast/format/impact.ts

@@ -0,0 +1,105 @@
+import { formatPathForDisplay } from "../../traverse.ts";
+import type { ImpactFileRow, ImpactResult, ImpactSection, ImpactSiteRow, ImpactTarget } from "../queries/impact.ts";
+import { compositeSectionBlocks, type CompositeBlock } from "./composite.ts";
+import { formatCandidateList } from "./relationships.ts";
+
+function formatTargetHeader(target: ImpactTarget, cwd: string): string {
+	const path = formatPathForDisplay(target.path, cwd);
+	return `${target.qualifiedName || target.name}  ${target.kind}  ${path}:${target.startLine}`;
+}
+
+function formatSiteRow(row: ImpactSiteRow): string {
+	const certainty = row.certainty === "exact" ? "" : `  ${row.certainty}`;
+	const preview = row.preview.length > 0 ? `  ${row.preview}` : "";
+	const name = row.name.length > 0 ? `  ${row.name}` : "";
+	return `  L${row.line}  ${row.siteKind}${name}${certainty}${preview}`;
+}
+
+function formatFileRow(row: ImpactFileRow, cwd: string, showDepth: boolean): string {
+	const depth = showDepth ? `d${row.depth} ` : "";
+	if (row.path !== undefined) {
+		return `  ${depth}${formatPathForDisplay(row.path, cwd)}`;
+	}
+	return `  ${depth}${row.externalId ?? "?"}`;
+}
+
+function formatSection(section: ImpactSection, cwd: string): string[] {
+	const lines = [`${section.label}:`];
+	const showDepth = section.id === "transitiveDependents";
+	const siteRows = section.rows.filter((row): row is ImpactSiteRow => row.kind === "site");
+	const fileRows = section.rows.filter((row): row is ImpactFileRow => row.kind === "file");
+
+	if (siteRows.length > 0) {
+		let currentPath = "";
+		for (const row of siteRows) {
+			if (row.path !== currentPath) {
+				currentPath = row.path;
+				lines.push(formatPathForDisplay(row.path, cwd));
+			}
+			lines.push(formatSiteRow(row));
+		}
+	}
+
+	if (fileRows.length > 0) {
+		const internal = fileRows.filter((row) => row.path !== undefined);
+		const external = fileRows.filter((row) => row.externalId !== undefined);
+		for (const row of internal) {
+			lines.push(formatFileRow(row, cwd, showDepth));
+		}
+		if (external.length > 0) {
+			lines.push("  external:");
+			for (const row of external) {
+				lines.push(`  ${formatFileRow(row, cwd, showDepth).trimStart()}`);
+			}
+		}
+	}
+
+	if (section.omitted) {
+		lines.push(`  omitted (limit ${section.limit})`);
+	}
+	return lines;
+}
+
+function formatResolved(result: Extract<ImpactResult, { kind: "resolved" }>, cwd: string): string {
+	const lines = [formatTargetHeader(result.target, cwd)];
+	if (result.sections.length === 0) {
+		lines.push("No impact edges.");
+	} else {
+		for (const section of result.sections) {
+			lines.push("");
+			lines.push(...formatSection(section, cwd));
+		}
+	}
+	for (const note of result.notes) {
+		lines.push(note);
+	}
+	if (result.parseDegraded) {
+		lines.push("parser: degraded on at least one file");
+	}
+	return lines.join("\n");
+}
+
+export function formatImpactResult(result: ImpactResult, cwd: string): string {
+	if (result.kind === "error") return result.message;
+	if (result.kind === "notFound") return "No matching declaration.";
+	if (result.kind === "candidates") return formatCandidateList(result.candidates, cwd);
+	return formatResolved(result, cwd);
+}
+
+export function impactSectionBlocks(
+	result: Extract<ImpactResult, { kind: "resolved" }>,
+	cwd: string,
+): CompositeBlock[] {
+	const footers = [...result.notes];
+	if (result.parseDegraded) footers.push("parser: degraded on at least one file");
+	return compositeSectionBlocks({
+		header: formatTargetHeader(result.target, cwd),
+		emptyLabel: "No impact edges.",
+		sections: result.sections.map((section) => ({
+			id: section.id,
+			label: section.label,
+			text: formatSection(section, cwd).join("\n"),
+		})),
+		footers,
+	});
+}

package/extensions/explore/ast/format/outline.ts

@@ -0,0 +1,66 @@
+import type { OutlineFileView, OutlineRow } from "../queries/outline.ts";
+import type { ScanOutcome } from "../scan.ts";
+import type { TraversalLimit } from "../../traverse.ts";
+import { formatPathForDisplay } from "../../traverse.ts";
+
+function lineRange(startLine: number, endLine: number): string {
+	return startLine === endLine ? `L${startLine}` : `L${startLine}-${endLine}`;
+}
+
+function formatRow(row: OutlineRow): string[] {
+	const indent = "  ".repeat(row.depth);
+	const lines: string[] = [];
+	if (row.docs !== undefined && row.docs.length > 0) {
+		for (const docLine of row.docs.replace(/\s+$/u, "").split("\n")) {
+			lines.push(`${indent}${docLine}`);
+		}
+	}
+	const signature = row.signature.replace(/\s+$/u, "");
+	const sigLines = signature.length > 0 ? signature.split("\n") : [row.name];
+	const first = sigLines[0] ?? row.name;
+	lines.push(`${indent}${lineRange(row.startLine, row.endLine)}: ${first}`);
+	for (let i = 1; i < sigLines.length; i += 1) {
+		lines.push(`${indent}${sigLines[i] ?? ""}`);
+	}
+	return lines;
+}
+
+/** One complete outline unit (optional path header + rows). */
+export function formatOutlineFile(view: OutlineFileView, cwd: string, includePathHeader: boolean): string {
+	const lines: string[] = [];
+	if (includePathHeader) lines.push(formatPathForDisplay(view.path, cwd));
+	if (view.parseDegraded) {
+		lines.push("warning: parser recovered with errors");
+	}
+	if (view.rows.length === 0) {
+		lines.push("No declarations");
+	} else {
+		for (const row of view.rows) lines.push(...formatRow(row));
+	}
+	return lines.join("\n");
+}
+
+export function formatOutlineEmpty(names: readonly string[]): string {
+	return names.length > 0 ? "No matching declarations" : "No declarations";
+}
+
+function limitLabel(limit: TraversalLimit): string {
+	switch (limit) {
+		case "maxFiles":
+			return "file count";
+		case "maxSourceBytes":
+			return "source bytes";
+		case "maxDepth":
+			return "depth";
+		case "maxElapsedMs":
+			return "elapsed time";
+		case "cancelled":
+			return "cancelled";
+	}
+}
+
+/** Budget/limit footer line when a recursive scan stopped early. */
+export function formatOutlineBudgetFooter(outcome: ScanOutcome): string | undefined {
+	if (outcome.limit === undefined || outcome.limit === "cancelled") return undefined;
+	return `limits reached: ${limitLabel(outcome.limit)}`;
+}

package/extensions/explore/ast/format/relationships.ts

@@ -0,0 +1,81 @@
+import type { Candidate } from "../identity.ts";
+import type { RelationshipQueryResult, RelationshipSite, RelationshipTarget } from "../graph/relationships.ts";
+import { formatPathForDisplay } from "../../traverse.ts";
+
+function formatCompetitors(competitors: readonly Candidate[], cwd: string): string[] {
+	const lines: string[] = [];
+	for (const c of competitors) {
+		const path = formatPathForDisplay(c.path, cwd);
+		const sig = c.signature.replace(/\s+/gu, " ").trim();
+		const short = sig.length > 80 ? `${sig.slice(0, 77)}...` : sig;
+		lines.push(`    - ${path}:${c.startLine}  ${c.kind} ${c.qualifiedName || c.name}  ${short}`);
+	}
+	return lines;
+}
+
+function formatSiteRow(site: RelationshipSite): string {
+	const certainty = site.certainty === "exact" ? "" : `  ${site.certainty}`;
+	const preview = site.preview.length > 0 ? `  ${site.preview}` : "";
+	return `  L${site.line}  ${site.kind}${certainty}${preview}`;
+}
+
+function formatResolved(
+	target: RelationshipTarget,
+	sites: readonly RelationshipSite[],
+	cwd: string,
+	resultLimit: number,
+	resultLimitReached: boolean,
+	parseDegraded: boolean,
+): string {
+	const path = formatPathForDisplay(target.path, cwd);
+	const header = `${target.qualifiedName || target.name}  ${target.kind}  ${path}:${target.startLine}`;
+	if (sites.length === 0) {
+		const lines = [header, "No relationship sites."];
+		if (parseDegraded) lines.push("parser: degraded on at least one file");
+		return lines.join("\n");
+	}
+
+	const lines: string[] = [header, ""];
+	let currentPath = "";
+	for (const site of sites) {
+		if (site.path !== currentPath) {
+			currentPath = site.path;
+			lines.push(formatPathForDisplay(site.path, cwd));
+		}
+		lines.push(formatSiteRow(site));
+		if (site.competitors.length > 0) {
+			lines.push("  competitors:");
+			lines.push(...formatCompetitors(site.competitors, cwd));
+		}
+	}
+
+	if (resultLimitReached) lines.push(`omitted (result limit ${resultLimit})`);
+	if (parseDegraded) lines.push("parser: degraded on at least one file");
+	return lines.join("\n");
+}
+
+export function formatCandidateList(candidates: readonly Candidate[], cwd: string): string {
+	const lines = ["Ambiguous target — disambiguate with targetPath or line:", ""];
+	for (const c of candidates) {
+		const path = formatPathForDisplay(c.path, cwd);
+		const sig = c.signature.replace(/\s+/gu, " ").trim();
+		const short = sig.length > 80 ? `${sig.slice(0, 77)}...` : sig;
+		lines.push(`${path}:${c.startLine}  ${c.kind} ${c.qualifiedName || c.name}`);
+		if (short.length > 0) lines.push(`  ${short}`);
+	}
+	return lines.join("\n");
+}
+
+export function formatRelationshipResult(result: RelationshipQueryResult, cwd: string): string {
+	if (result.kind === "error") return result.message;
+	if (result.kind === "notFound") return "No matching declaration.";
+	if (result.kind === "candidates") return formatCandidateList(result.candidates, cwd);
+	return formatResolved(
+		result.target,
+		result.sites,
+		cwd,
+		result.resultLimit,
+		result.resultLimitReached,
+		result.parseDegraded,
+	);
+}

package/extensions/explore/ast/format/show.ts

@@ -0,0 +1,38 @@
+import type { ShowBatch, ShowBlock } from "../queries/show.ts";
+import { formatPathForDisplay } from "../../traverse.ts";
+
+function lineRange(startLine: number, endLine: number): string {
+	return startLine === endLine ? `L${startLine}` : `L${startLine}-${endLine}`;
+}
+
+function formatBlock(block: ShowBlock, cwd: string, includePath: boolean): string {
+	const lines: string[] = [];
+	if (includePath) lines.push(formatPathForDisplay(block.path, cwd));
+	lines.push(`${lineRange(block.startLine, block.endLine)}: ${block.name}`);
+	for (const warning of block.warnings) {
+		lines.push(`warning: ${warning}`);
+	}
+	lines.push(block.text);
+	return lines.join("\n");
+}
+
+/**
+ * Exact source blocks.
+ * Single block: no path chrome. Multi-block: path header when the path changes.
+ */
+export function formatShowBatch(batch: ShowBatch, cwd: string): string {
+	if (batch.blocks.length === 0) return "";
+	if (batch.blocks.length === 1) {
+		const only = batch.blocks[0];
+		if (only === undefined) return "";
+		return formatBlock(only, cwd, false);
+	}
+	const parts: string[] = [];
+	let lastPath: string | undefined;
+	for (const block of batch.blocks) {
+		const includePath = block.path !== lastPath;
+		lastPath = block.path;
+		parts.push(formatBlock(block, cwd, includePath));
+	}
+	return parts.join("\n\n");
+}