@shanepadgett/tau-agent 0.26.0 → 0.28.0

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");
+}

package/extensions/explore/ast/grammars/manifest.json

@@ -0,0 +1,41 @@
+{
+	"webTreeSitter": "0.26.11",
+	"vscodeTreeSitterWasm": "0.3.1",
+	"treeSitterCli": "0.26.11",
+	"wasiSdk": "wasi-sdk-29",
+	"grammars": [
+		{ "id": "typescript", "source": "vscode", "file": "tree-sitter-typescript.wasm" },
+		{ "id": "tsx", "source": "vscode", "file": "tree-sitter-tsx.wasm" },
+		{ "id": "go", "source": "vscode", "file": "tree-sitter-go.wasm" },
+		{ "id": "rust", "source": "vscode", "file": "tree-sitter-rust.wasm" },
+		{ "id": "c_sharp", "source": "vscode", "file": "tree-sitter-c-sharp.wasm" },
+		{ "id": "java", "source": "vscode", "file": "tree-sitter-java.wasm" },
+		{
+			"id": "kotlin",
+			"source": "built",
+			"file": "kotlin.wasm",
+			"repo": "https://github.com/fwcd/tree-sitter-kotlin",
+			"tag": "0.3.8",
+			"rev": "9e7e62415a0546efb4549e730af1d9bf5460a37b",
+			"subdir": "."
+		},
+		{
+			"id": "swift",
+			"source": "release",
+			"file": "swift.wasm",
+			"repo": "https://github.com/alex-pinkus/tree-sitter-swift",
+			"tag": "0.7.3",
+			"rev": "b8b22bffbb3441780e6471665bacfb263741c86a",
+			"url": "https://github.com/alex-pinkus/tree-sitter-swift/releases/download/0.7.3/tree-sitter-swift.wasm"
+		},
+		{
+			"id": "odin",
+			"source": "built",
+			"file": "odin.wasm",
+			"repo": "https://github.com/tree-sitter-grammars/tree-sitter-odin",
+			"tag": "v1.3.0",
+			"rev": "e8adc739b78409a99f8c31313f0bb54cc538cf73",
+			"subdir": "."
+		}
+	]
+}

package/extensions/explore/ast/grammars/manifest.ts

@@ -0,0 +1,99 @@
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export type VscodeGrammarPin = {
+	id: string;
+	source: "vscode";
+	file: string;
+};
+
+export type BuiltGrammarPin = {
+	id: string;
+	source: "built";
+	file: string;
+	repo: string;
+	tag: string;
+	rev: string;
+	subdir: string;
+};
+
+export type ReleaseGrammarPin = {
+	id: string;
+	source: "release";
+	file: string;
+	repo: string;
+	tag: string;
+	rev: string;
+	url: string;
+};
+
+export type GrammarPin = VscodeGrammarPin | BuiltGrammarPin | ReleaseGrammarPin;
+
+export type GrammarManifest = {
+	webTreeSitter: string;
+	vscodeTreeSitterWasm: string;
+	treeSitterCli: string;
+	wasiSdk: string;
+	grammars: GrammarPin[];
+};
+
+export const grammarsDir = dirname(fileURLToPath(import.meta.url));
+const resolveModule = createRequire(import.meta.url).resolve;
+
+export function runtimeWasmPath(): string {
+	return join(dirname(resolveModule("web-tree-sitter")), "web-tree-sitter.wasm");
+}
+
+export function grammarWasmPath(pin: GrammarPin): string {
+	if (pin.source === "vscode") {
+		return join(dirname(resolveModule("@vscode/tree-sitter-wasm")), pin.file);
+	}
+	return join(grammarsDir, pin.file);
+}
+
+function requireString(record: Record<string, unknown>, key: string, context: string): string {
+	const value = record[key];
+	if (typeof value !== "string" || value.length === 0) {
+		throw new Error(`grammar manifest: ${context}.${key} must be a non-empty string`);
+	}
+	return value;
+}
+
+function parseGrammarPin(entry: unknown, index: number): GrammarPin {
+	if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+		throw new Error(`grammar manifest: grammars[${index}] must be an object`);
+	}
+	const record = entry as Record<string, unknown>;
+	const context = `grammars[${index}]`;
+	const id = requireString(record, "id", context);
+	const file = requireString(record, "file", context);
+	const source = requireString(record, "source", context);
+	if (source === "vscode") return { id, source, file };
+	const repo = requireString(record, "repo", context);
+	const tag = requireString(record, "tag", context);
+	const rev = requireString(record, "rev", context);
+	if (source === "built")
+		return { id, source, file, repo, tag, rev, subdir: requireString(record, "subdir", context) };
+	if (source === "release") return { id, source, file, repo, tag, rev, url: requireString(record, "url", context) };
+	throw new Error(`grammar manifest: ${context}.source must be vscode, built, or release`);
+}
+
+export function loadGrammarManifest(): GrammarManifest {
+	const parsed: unknown = JSON.parse(readFileSync(join(grammarsDir, "manifest.json"), "utf8"));
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+		throw new Error("grammar manifest: root must be an object");
+	}
+	const root = parsed as Record<string, unknown>;
+	if (!Array.isArray(root.grammars) || root.grammars.length === 0) {
+		throw new Error("grammar manifest: grammars must be a non-empty array");
+	}
+	return {
+		webTreeSitter: requireString(root, "webTreeSitter", "root"),
+		vscodeTreeSitterWasm: requireString(root, "vscodeTreeSitterWasm", "root"),
+		treeSitterCli: requireString(root, "treeSitterCli", "root"),
+		wasiSdk: requireString(root, "wasiSdk", "root"),
+		grammars: root.grammars.map(parseGrammarPin),
+	};
+}