lattice-graph 0.3.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "lattice-graph",
-	"version": "0.3.0",
+	"version": "0.5.0",
 	"description": "Knowledge graph CLI for coding agents — navigate code through flows, not grep.",
 	"module": "src/main.ts",
 	"type": "module",
@@ -9,12 +9,10 @@
 	},
 	"files": [
 		"src",
-		"scripts",
 		"README.md",
 		"LICENSE"
 	],
 	"scripts": {
-		"postinstall": "bun scripts/postinstall.ts",
 		"dev": "bun src/main.ts",
 		"test": "bun test",
 		"lint": "bunx biome check src/ tests/",

package/src/commands/build.ts

@@ -73,7 +73,13 @@ function buildLanguageConfigs(config: LatticeConfig): readonly LanguageConfig[]
 		configs.push(buildLanguageConfig("python", [config.root], ["tests"]));
 	}
 
+	if (config.languages.includes("go") && config.go) {
+		configs.push(buildLanguageConfig("go", config.go.sourceRoots, config.go.testPaths));
+	} else if (config.languages.includes("go")) {
+		configs.push(buildLanguageConfig("go", [config.root], []));
+	}
+
 	return configs;
 }
 
-export { executeBuild };
+export { buildLanguageConfigs, executeBuild };

package/src/commands/init.ts

@@ -1,5 +1,5 @@
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
 import { err, ok, type Result } from "../types/result.ts";
 
 /**
@@ -27,6 +27,17 @@ function executeInit(projectRoot: string): Result<string, string> {
 			writeFileSync(tomlPath, toml);
 		}
 
+		// Append Lattice section to CLAUDE.md (skip if already present)
+		const claudeDir = join(projectRoot, ".claude");
+		const claudeMdPath = join(claudeDir, "CLAUDE.md");
+		mkdirSync(claudeDir, { recursive: true });
+		const existing = existsSync(claudeMdPath) ? readFileSync(claudeMdPath, "utf-8") : "";
+		if (!existing.includes("## Code Navigation")) {
+			const snippet = generateClaudeSnippet(languages);
+			const separator = existing.length > 0 && !existing.endsWith("\n\n") ? "\n\n" : "";
+			appendFileSync(claudeMdPath, `${separator}${snippet}`);
+		}
+
 		// Check LSP server availability
 		const warnings = checkLspAvailability(languages);
 		const message = ["Initialized Lattice project", ...warnings].join("\n");
@@ -102,32 +113,144 @@ function generateToml(languages: readonly string[], root: string): string {
 	return lines.join("\n");
 }
 
-/** Checks if language server binaries are available (bundled or in PATH). */
+/** Checks prerequisites for language support. */
 function checkLspAvailability(languages: readonly string[]): readonly string[] {
 	const warnings: string[] = [];
-	const latticeRoot = resolve(import.meta.dir, "..", "..");
-
-	const checks: Record<string, { bundled: string; system: string; install: string }> = {
-		typescript: {
-			bundled: join(latticeRoot, "node_modules", ".bin", "typescript-language-server"),
-			system: "typescript-language-server",
-			install: "reinstall lattice-graph",
-		},
-		python: {
-			bundled: join(latticeRoot, "vendor", "venv", "bin", "zubanls"),
-			system: "zubanls",
-			install: "reinstall lattice-graph (or pip install zuban)",
-		},
-	};
-
-	for (const lang of languages) {
-		const check = checks[lang];
-		if (!check) continue;
-		if (!existsSync(check.bundled) && !Bun.which(check.system)) {
-			warnings.push(`Warning: ${check.system} not found. ${check.install}`);
-		}
+	if (languages.includes("python") && !Bun.which("python3") && !Bun.which("python")) {
+		warnings.push("Warning: Python 3 not found. Install Python 3 to enable Python support.");
 	}
 	return warnings;
 }
 
-export { executeInit };
+const PYTHON_EXAMPLE = `\`\`\`bash
+# 1. Orient: what flows exist?
+lattice overview
+
+# 2. Locate: find the relevant flow
+lattice flow user-registration
+
+# Output:
+# register (app/auth/routes.py:45)
+#   → validate_input (app/auth/validation.py:12)
+#   → create_user (app/auth/service.py:30)
+#     → hash_password (app/auth/crypto.py:8)
+#     → insert_user (app/storage/postgres.py:55) [postgres]
+#   → send_welcome_email (app/notifications/email.py:20) [sendgrid]
+
+# 3. Understand: zoom into the function you suspect
+lattice context create_user
+
+# 4. Scope: check what breaks if you change it
+lattice impact create_user
+
+# 5. Read: get just that function's source
+lattice code create_user
+
+# 6. Edit: use Read/Edit tools on app/auth/service.py:30
+\`\`\`
+
+### Symbol format
+
+Unique names work directly. Ambiguous names need file qualification.
+
+\`\`\`bash
+lattice context create_user                       # unique name
+lattice context app/auth/service.py::create_user  # file::function
+lattice context app/models.py::User.save          # file::Class.method
+\`\`\``;
+
+const TYPESCRIPT_EXAMPLE = `\`\`\`bash
+# 1. Orient: what flows exist?
+lattice overview
+
+# 2. Locate: find the relevant flow
+lattice flow checkout
+
+# Output:
+# handleCheckout (src/api/checkout.ts:25)
+#   → validateCart (src/cart/validation.ts:12)
+#   → createOrder (src/orders/service.ts:40)
+#     → insertOrder (src/db/orders.ts:18) [postgres]
+#     → chargePayment (src/payments/stripe.ts:30) [stripe]
+#   → sendConfirmation (src/notifications/email.ts:55) [sendgrid]
+
+# 3. Understand: zoom into the function you suspect
+lattice context createOrder
+
+# 4. Scope: check what breaks if you change it
+lattice impact createOrder
+
+# 5. Read: get just that function's source
+lattice code createOrder
+
+# 6. Edit: use Read/Edit tools on src/orders/service.ts:40
+\`\`\`
+
+### Symbol format
+
+Unique names work directly. Ambiguous names need file qualification.
+
+\`\`\`bash
+lattice context createOrder                          # unique name
+lattice context src/orders/service.ts::createOrder   # file::function
+\`\`\``;
+
+const GO_EXAMPLE = `\`\`\`bash
+# 1. Orient: what flows exist?
+lattice overview
+
+# 2. Locate: find the relevant flow
+lattice flow create-order
+
+# Output:
+# HandleCreateOrder (internal/api/orders.go:35)
+#   → ValidateRequest (internal/api/validation.go:20)
+#   → CreateOrder (internal/service/orders.go:45)
+#     → InsertOrder (internal/repo/orders.go:28) [postgres]
+#     → PublishEvent (internal/events/publisher.go:15) [nats]
+
+# 3. Understand: zoom into the function you suspect
+lattice context CreateOrder
+
+# 4. Scope: check what breaks if you change it
+lattice impact CreateOrder
+
+# 5. Read: get just that function's source
+lattice code CreateOrder
+
+# 6. Edit: use Read/Edit tools on internal/service/orders.go:45
+\`\`\`
+
+### Symbol format
+
+Unique names work directly. Ambiguous names need file qualification.
+
+\`\`\`bash
+lattice context CreateOrder                                # unique name
+lattice context internal/service/orders.go::CreateOrder    # file::function
+lattice context internal/api/server.go::Server.Handle      # file::Struct.Method
+\`\`\``;
+
+/** Generates a CLAUDE.md snippet with language-appropriate few-shot examples. */
+function generateClaudeSnippet(languages: readonly string[]): string {
+	const primary = languages[0] ?? "typescript";
+	const example =
+		primary === "python" ? PYTHON_EXAMPLE : primary === "go" ? GO_EXAMPLE : TYPESCRIPT_EXAMPLE;
+
+	return `## Code Navigation
+
+This project uses **Lattice** for codebase navigation. Use Lattice before reading files or Grep.
+
+### Example: full workflow
+
+${example}
+
+### After code changes
+
+\`\`\`bash
+lattice update
+\`\`\`
+`;
+}
+
+export { executeInit, generateClaudeSnippet };

package/src/commands/update.ts

@@ -5,7 +5,7 @@ import { discoverFiles } from "../files.ts";
 import { checkSchemaVersion } from "../graph/database.ts";
 import type { LatticeConfig } from "../types/config.ts";
 import { isOk, ok, type Result } from "../types/result.ts";
-import { executeBuild } from "./build.ts";
+import { buildLanguageConfigs, executeBuild } from "./build.ts";
 
 /** Statistics from an incremental update. */
 type UpdateStats = {
@@ -58,13 +58,14 @@ async function executeUpdate(
 	}
 	const lastBuild = Number.parseInt(metaRow.value, 10);
 
-	// Discover files
-	const extensions = [".ts", ".tsx"];
-	const sourceRoots = config.typescript?.sourceRoots ?? [config.root];
+	// Discover files across all configured languages
+	const languageConfigs = buildLanguageConfigs(config);
 	const allFiles: string[] = [];
-	for (const srcRoot of sourceRoots) {
-		const absRoot = resolve(projectRoot, srcRoot);
-		allFiles.push(...discoverFiles(absRoot, extensions, config.exclude));
+	for (const lang of languageConfigs) {
+		for (const srcRoot of lang.sourceRoots) {
+			const absRoot = resolve(projectRoot, srcRoot);
+			allFiles.push(...discoverFiles(absRoot, lang.extensions, config.exclude));
+		}
 	}
 
 	// Find changed files

package/src/config.ts

@@ -1,8 +1,22 @@
 import { parse as parseToml } from "smol-toml";
-import type { LatticeConfig, LintConfig, PythonConfig, TypeScriptConfig } from "./types/config.ts";
+import type {
+	GoConfig,
+	LatticeConfig,
+	LintConfig,
+	PythonConfig,
+	TypeScriptConfig,
+} from "./types/config.ts";
 import { err, ok, type Result } from "./types/result.ts";
 
-const DEFAULT_EXCLUDE = ["node_modules", "venv", ".git", "dist", "__pycache__", ".lattice"];
+const DEFAULT_EXCLUDE = [
+	"node_modules",
+	"venv",
+	"vendor",
+	".git",
+	"dist",
+	"__pycache__",
+	".lattice",
+];
 
 /**
  * Parses a TOML string into a validated LatticeConfig.
@@ -38,6 +52,8 @@ function parseConfig(tomlString: string): Result<LatticeConfig, string> {
 		? parseTypeScriptSection(raw.typescript)
 		: undefined;
 
+	const goConfig = languages.includes("go") ? parseGoSection(raw.go) : undefined;
+
 	const lintConfig = parseLintSection(raw.lint);
 
 	return ok({
@@ -46,6 +62,7 @@ function parseConfig(tomlString: string): Result<LatticeConfig, string> {
 		exclude,
 		python: pythonConfig,
 		typescript: typescriptConfig,
+		go: goConfig,
 		lint: lintConfig,
 	});
 }
@@ -69,6 +86,15 @@ function parseTypeScriptSection(raw: unknown): TypeScriptConfig {
 	};
 }
 
+/** Parses the [go] section with defaults for missing fields. */
+function parseGoSection(raw: unknown): GoConfig {
+	const section = isRecord(raw) ? raw : {};
+	return {
+		sourceRoots: isStringArray(section.source_roots) ? section.source_roots : ["."],
+		testPaths: isStringArray(section.test_paths) ? section.test_paths : [],
+	};
+}
+
 /** Parses the [lint] section with defaults for missing fields. */
 function parseLintSection(raw: unknown): LintConfig {
 	const section = isRecord(raw) ? raw : {};

package/src/extract/tag-scanner.ts

@@ -7,6 +7,7 @@ const NAME_PATTERN = /^[a-z][a-z0-9._-]*$/;
 const COMMENT_PREFIXES: Record<string, RegExp> = {
 	typescript: /^\s*(?:\/\/|\/\*\*?|\*)\s*/,
 	python: /^\s*(?:#|""")\s*/,
+	go: /^\s*(?:\/\/)\s*/,
 };
 const DEFAULT_COMMENT_PREFIX = /^\s*(?:\/\/|#|--|\/\*\*?|\*)\s*/;
 

package/src/lsp/builder.ts

@@ -40,12 +40,19 @@ type BuildStats = {
 	readonly durationMs: number;
 };
 
-/** Resolves the LSP server binary for a language, checking bundled paths first. */
+const VENDOR_VENV = join(import.meta.dir, "..", "..", "vendor", "venv");
+
+const LANGUAGE_EXTENSIONS: Record<string, readonly string[]> = {
+	typescript: [".ts", ".tsx"],
+	python: [".py"],
+	go: [".go"],
+};
+
+/** Resolves the LSP server binary for a language. Auto-installs zuban on first use. */
 function resolveLspServer(
 	language: string,
 ): { command: string; args: readonly string[]; languageId: string } | undefined {
 	if (language === "typescript") {
-		// Check node_modules/.bin/ first (bundled with lattice-graph)
 		const bundled = join(
 			import.meta.dir,
 			"..",
@@ -58,13 +65,131 @@ function resolveLspServer(
 		return { command, args: ["--stdio"], languageId: "typescript" };
 	}
 	if (language === "python") {
-		const bundled = join(import.meta.dir, "..", "..", "vendor", "venv", "bin", "zubanls");
-		const command = existsSync(bundled) ? bundled : "zubanls";
-		return { command, args: [], languageId: "python" };
+		const zubanls = resolveZuban();
+		if (!zubanls) return undefined;
+		return { command: zubanls, args: [], languageId: "python" };
+	}
+	if (language === "go") {
+		const goplsBin = resolveGopls();
+		if (!goplsBin) return undefined;
+		return { command: goplsBin, args: ["serve"], languageId: "go" };
+	}
+	return undefined;
+}
+
+/** Finds or installs zubanls. Returns the binary path, or undefined if installation fails. */
+function resolveZuban(): string | undefined {
+	const isWindows = process.platform === "win32";
+	const binDir = isWindows ? "Scripts" : "bin";
+	const binName = isWindows ? "zubanls.exe" : "zubanls";
+
+	// 1. Check vendored venv (installed by a previous build)
+	const vendored = join(VENDOR_VENV, binDir, binName);
+	if (existsSync(vendored)) return vendored;
+
+	// 2. Check system PATH
+	const system = Bun.which("zubanls");
+	if (system) return system;
+
+	// 3. Auto-install into vendored venv
+	return installZuban();
+}
+
+/** Creates a venv and pip-installs zuban. Returns zubanls path or undefined on failure. */
+function installZuban(): string | undefined {
+	const isWindows = process.platform === "win32";
+	const binDir = isWindows ? "Scripts" : "bin";
+	const binName = isWindows ? "zubanls.exe" : "zubanls";
+
+	const python = Bun.which("python3") ?? Bun.which("python");
+	if (!python) {
+		console.error("Python not found. Install Python 3 to enable Python support.");
+		return undefined;
+	}
+
+	console.log("Installing Python language server (zuban)...");
+
+	const venvResult = Bun.spawnSync([python, "-m", "venv", VENDOR_VENV], {
+		stdout: "ignore",
+		stderr: "pipe",
+	});
+	if (venvResult.exitCode !== 0) {
+		console.error(`Failed to create venv: ${venvResult.stderr.toString()}`);
+		return undefined;
 	}
+
+	const pip = join(VENDOR_VENV, binDir, isWindows ? "pip.exe" : "pip");
+	const pipResult = Bun.spawnSync([pip, "install", "zuban", "--quiet"], {
+		stdout: "ignore",
+		stderr: "pipe",
+	});
+	if (pipResult.exitCode !== 0) {
+		console.error(`Failed to install zuban: ${pipResult.stderr.toString()}`);
+		return undefined;
+	}
+
+	const zubanls = join(VENDOR_VENV, binDir, binName);
+	if (!existsSync(zubanls)) {
+		console.error("zubanls not found after installation");
+		return undefined;
+	}
+
+	console.log("done");
+	return zubanls;
+}
+
+/** Resolves gopls binary path from GOBIN or GOPATH/bin. */
+function findGoplsBinary(): string | undefined {
+	const gobin = process.env.GOBIN;
+	if (gobin) {
+		const goplsPath = join(gobin, "gopls");
+		if (existsSync(goplsPath)) return goplsPath;
+	}
+	const gopath = process.env.GOPATH ?? join(process.env.HOME ?? "", "go");
+	const gopathBin = join(gopath, "bin", "gopls");
+	if (existsSync(gopathBin)) return gopathBin;
 	return undefined;
 }
 
+/** Finds or installs gopls. Returns the binary path, or undefined if unavailable. */
+function resolveGopls(): string | undefined {
+	const system = Bun.which("gopls");
+	if (system) return system;
+
+	const found = findGoplsBinary();
+	if (found) return found;
+
+	return installGopls();
+}
+
+/** Installs gopls via go install. Returns binary path or undefined on failure. */
+function installGopls(): string | undefined {
+	const goBin = Bun.which("go");
+	if (!goBin) {
+		console.error("Go not found. Install Go to enable Go support.");
+		return undefined;
+	}
+
+	console.log("Installing Go language server (gopls)...");
+
+	const result = Bun.spawnSync([goBin, "install", "golang.org/x/tools/gopls@latest"], {
+		stdout: "ignore",
+		stderr: "pipe",
+	});
+	if (result.exitCode !== 0) {
+		console.error(`Failed to install gopls: ${result.stderr.toString()}`);
+		return undefined;
+	}
+
+	const installed = findGoplsBinary();
+	if (!installed) {
+		console.error("gopls not found after installation");
+		return undefined;
+	}
+	console.log("done");
+	return installed;
+}
+
 /**
  * Builds the knowledge graph by querying LSP servers for symbols and call hierarchy,
  * scanning for @lattice: tags, and writing everything to SQLite.
@@ -117,7 +242,10 @@ async function buildGraph(opts: BuildGraphOptions): Promise<BuildStats> {
 
 			for (const filePath of files) {
 				const relativePath = relative(projectRoot, filePath);
-				const isTest = langConfig.testPaths.some((tp) => relativePath.startsWith(tp));
+				const isTest =
+					langConfig.language === "go"
+						? relativePath.endsWith("_test.go")
+						: langConfig.testPaths.some((tp) => relativePath.startsWith(tp));
 				const source = await Bun.file(filePath).text();
 
 				const symbols = await client.documentSymbol(filePath);
@@ -136,30 +264,36 @@ async function buildGraph(opts: BuildGraphOptions): Promise<BuildStats> {
 				fileDataList.push({ filePath, relativePath, nodesWithPos });
 			}
 
-			// Phase 2a: outgoingCalls — "what does each function call?"
-			for (const fd of fileDataList) {
-				for (const nwp of fd.nodesWithPos) {
-					if (nwp.node.kind !== "function" && nwp.node.kind !== "method") continue;
+			// Phase 2a: outgoingCalls — gopls doesn't support this over stdio, so skip for Go
+			if (langConfig.language !== "go")
+				for (const fd of fileDataList) {
+					for (const nwp of fd.nodesWithPos) {
+						if (nwp.node.kind !== "function" && nwp.node.kind !== "method") continue;
 
-					try {
-						const items = await client.prepareCallHierarchy(
-							fd.filePath,
-							nwp.selectionLine,
-							nwp.selectionCharacter,
-						);
-						if (items.length === 0) continue;
-						const item = items[0];
-						if (!item) continue;
-
-						const calls = await client.outgoingCalls(item);
-						const { edges, externalCalls } = outgoingCallsToEdges(nwp.node.id, calls, projectRoot);
-						allEdges.push(...edges);
-						allExternalCalls.push(...externalCalls);
-					} catch {
-						// outgoingCalls not supported by this server — skip silently
+						try {
+							const items = await client.prepareCallHierarchy(
+								fd.filePath,
+								nwp.selectionLine,
+								nwp.selectionCharacter,
+							);
+							if (items.length === 0) continue;
+							const item = items[0];
+							if (!item) continue;
+
+							const calls = await client.outgoingCalls(item);
+							const { edges, externalCalls } = outgoingCallsToEdges(
+								nwp.node.id,
+								calls,
+								projectRoot,
+								langConfig.language,
+							);
+							allEdges.push(...edges);
+							allExternalCalls.push(...externalCalls);
+						} catch {
+							// outgoingCalls not supported by this server — skip silently
+						}
 					}
 				}
-			}
 
 			// Phase 2b: references — "who references each function?"
 			const nodesByFile = new Map<string, readonly Node[]>();
@@ -235,7 +369,7 @@ function buildLanguageConfig(
 	sourceRoots: readonly string[],
 	testPaths: readonly string[],
 ): LanguageConfig {
-	const extensions = language === "python" ? [".py"] : [".ts", ".tsx"];
+	const extensions = LANGUAGE_EXTENSIONS[language] ?? [];
 	return { language, extensions, sourceRoots, testPaths };
 }
 

package/src/lsp/calls.ts

@@ -14,12 +14,14 @@ type CallConversionResult = {
  * @param sourceId - The Lattice node ID of the calling function
  * @param calls - Outgoing calls from LSP
  * @param projectRoot - Absolute path to the project root
+ * @param language - Language identifier for external call detection
  * @returns Internal edges and external call records
  */
 function outgoingCallsToEdges(
 	sourceId: string,
 	calls: readonly CallHierarchyOutgoingCall[],
 	projectRoot: string,
+	language: string,
 ): CallConversionResult {
 	const edges: Edge[] = [];
 	const externalCalls: ExternalCall[] = [];
@@ -28,11 +30,15 @@ function outgoingCallsToEdges(
 	for (const call of calls) {
 		const uri = call.to.uri;
 
-		if (!uri.startsWith(projectFilePrefix) || uri.includes("/node_modules/")) {
-			// Skip type declarations — not runtime calls
-			if (isTypeDeclaration(uri)) continue;
+		const isExternal =
+			!uri.startsWith(projectFilePrefix) ||
+			uri.includes("/node_modules/") ||
+			uri.includes("/pkg/mod/");
 
-			const pkg = extractPackageName(uri);
+		if (isExternal) {
+			if (language !== "go" && isTypeDeclaration(uri)) continue;
+
+			const pkg = language === "go" ? extractGoModuleName(uri) : extractPackageName(uri);
 			if (pkg) {
 				externalCalls.push({ nodeId: sourceId, package: pkg, symbol: call.to.name });
 			}
@@ -63,6 +69,33 @@ function extractPackageName(uri: string): string | undefined {
 	return afterNm.split("/")[0];
 }
 
+/**
+ * Extracts the Go module name from a module cache or stdlib URI.
+ * Module cache paths contain /pkg/mod/ with @version.
+ * Stdlib paths contain /go/src/ without @version.
+ */
+function extractGoModuleName(uri: string): string | undefined {
+	const decoded = decodeURIComponent(uri);
+
+	// Go module cache: contains /pkg/mod/ with @version
+	const pkgModIdx = decoded.indexOf("/pkg/mod/");
+	if (pkgModIdx !== -1) {
+		const afterMod = decoded.slice(pkgModIdx + "/pkg/mod/".length);
+		const atIdx = afterMod.indexOf("@");
+		if (atIdx !== -1) {
+			return afterMod.slice(0, atIdx);
+		}
+	}
+
+	// Go stdlib: contains /go/src/ without @version
+	const goSrcMatch = decoded.match(/\/go\/src\/(.+?)\/[^/]+$/);
+	if (goSrcMatch && !decoded.includes("@")) {
+		return goSrcMatch[1];
+	}
+
+	return undefined;
+}
+
 /**
  * Checks if a URI points to a type-only package (not a runtime dependency).
  * Type definition packages (@types/*, typescript, bun-types) are filtered out.
@@ -81,4 +114,10 @@ function isTypeDeclaration(uri: string): boolean {
 	return false;
 }
 
-export { type CallConversionResult, extractPackageName, isTypeDeclaration, outgoingCallsToEdges };
+export {
+	type CallConversionResult,
+	extractGoModuleName,
+	extractPackageName,
+	isTypeDeclaration,
+	outgoingCallsToEdges,
+};

package/src/lsp/client.ts

@@ -80,7 +80,12 @@ async function createLspClient(opts: LspClientOptions): Promise<LspClient> {
 
 			try {
 				const msg = JSON.parse(body) as JsonRpcMessage;
-				if (msg.id !== undefined && pending.has(msg.id)) {
+				if (msg.method && msg.id !== undefined) {
+					// Server-initiated request — reply with null to unblock the server
+					const reply = JSON.stringify({ jsonrpc: "2.0", id: msg.id, result: null });
+					const replyHeader = `Content-Length: ${Buffer.byteLength(reply)}\r\n\r\n`;
+					proc.stdin?.write(replyHeader + reply);
+				} else if (msg.id !== undefined && pending.has(msg.id)) {
 					const handler = pending.get(msg.id);
 					pending.delete(msg.id);
 					if (msg.error) {
@@ -95,7 +100,7 @@ async function createLspClient(opts: LspClientOptions): Promise<LspClient> {
 		}
 	});
 
-	function sendRequest(method: string, params: unknown): Promise<unknown> {
+	function sendRequest(method: string, params: unknown, timeoutMs = 30000): Promise<unknown> {
 		const id = nextId++;
 		const msg: JsonRpcMessage = { jsonrpc: "2.0", id, method, params };
 		const body = JSON.stringify(msg);
@@ -103,7 +108,20 @@ async function createLspClient(opts: LspClientOptions): Promise<LspClient> {
 		proc.stdin?.write(header + body);
 
 		return new Promise((resolve, reject) => {
-			pending.set(id, { resolve, reject });
+			const timer = setTimeout(() => {
+				pending.delete(id);
+				reject(new Error(`LSP request ${method} timed out after ${timeoutMs}ms`));
+			}, timeoutMs);
+			pending.set(id, {
+				resolve: (v: unknown) => {
+					clearTimeout(timer);
+					resolve(v);
+				},
+				reject: (e: Error) => {
+					clearTimeout(timer);
+					reject(e);
+				},
+			});
 		});
 	}
 
@@ -144,7 +162,7 @@ async function createLspClient(opts: LspClientOptions): Promise<LspClient> {
 	const client: LspClient = {
 		async waitForReady(probePath: string): Promise<void> {
 			openFile(probePath);
-			const delays = [100, 200, 400, 800, 1600, 3200];
+			const delays = [100, 200, 400, 800, 1600, 3200, 5000, 5000];
 			for (const delay of delays) {
 				const result = (await sendRequest("textDocument/documentSymbol", {
 					textDocument: { uri: `file://${probePath}` },
@@ -168,10 +186,14 @@ async function createLspClient(opts: LspClientOptions): Promise<LspClient> {
 			character: number,
 		): Promise<readonly CallHierarchyItem[]> {
 			openFile(filePath);
-			const result = await sendRequest("textDocument/prepareCallHierarchy", {
-				textDocument: { uri: `file://${filePath}` },
-				position: { line, character },
-			});
+			const result = await sendRequest(
+				"textDocument/prepareCallHierarchy",
+				{
+					textDocument: { uri: `file://${filePath}` },
+					position: { line, character },
+				},
+				5000,
+			);
 			return (result as readonly CallHierarchyItem[]) ?? [];
 		},
 

package/src/lsp/symbols.ts

@@ -18,7 +18,7 @@ function documentSymbolsToNodes(
 	isTest: boolean,
 ): readonly Node[] {
 	const nodes: Node[] = [];
-	flattenSymbols(symbols, filePath, language, isTest, [], nodes);
+	flattenSymbols(symbols, filePath, language, isTest, [], nodes, new Map());
 	return nodes;
 }
 
@@ -29,19 +29,20 @@ function flattenSymbols(
 	isTest: boolean,
 	parentNames: readonly string[],
 	results: Node[],
+	seenIds: Map<string, number>,
 ): void {
 	for (const sym of symbols) {
 		const kind = symbolKindToNodeKind(sym.kind);
 		if (!kind) {
 			// Still recurse into children for non-matching kinds (e.g., modules)
 			if (sym.children) {
-				flattenSymbols(sym.children, filePath, language, isTest, parentNames, results);
+				flattenSymbols(sym.children, filePath, language, isTest, parentNames, results, seenIds);
 			}
 			continue;
 		}
 
 		const qualifiedName = [...parentNames, sym.name].join(".");
-		const id = `${filePath}::${qualifiedName}`;
+		const id = deduplicateId(`${filePath}::${qualifiedName}`, seenIds);
 
 		results.push({
 			id,
@@ -57,17 +58,33 @@ function flattenSymbols(
 		});
 
 		if (sym.children) {
-			flattenSymbols(sym.children, filePath, language, isTest, [...parentNames, sym.name], results);
+			flattenSymbols(
+				sym.children,
+				filePath,
+				language,
+				isTest,
+				[...parentNames, sym.name],
+				results,
+				seenIds,
+			);
 		}
 	}
 }
 
+/** Returns a unique ID, appending $N for duplicates (e.g., Go's multiple init() per file). */
+function deduplicateId(baseId: string, seenIds: Map<string, number>): string {
+	const count = seenIds.get(baseId) ?? 0;
+	seenIds.set(baseId, count + 1);
+	return count === 0 ? baseId : `${baseId}$${count + 1}`;
+}
+
 function symbolKindToNodeKind(kind: number): NodeKind | undefined {
 	if (kind === SymbolKind.Function) return "function";
 	if (kind === SymbolKind.Method) return "method";
 	if (kind === SymbolKind.Constructor) return "method";
 	if (kind === SymbolKind.Class) return "class";
 	if (kind === SymbolKind.Interface) return "type";
+	if (kind === SymbolKind.Struct) return "class";
 	return undefined;
 }
 
@@ -89,7 +106,7 @@ function documentSymbolsToNodesWithPositions(
 	isTest: boolean,
 ): readonly NodeWithPosition[] {
 	const results: NodeWithPosition[] = [];
-	flattenSymbolsWithPositions(symbols, filePath, language, isTest, [], results);
+	flattenSymbolsWithPositions(symbols, filePath, language, isTest, [], results, new Map());
 	return results;
 }
 
@@ -100,18 +117,27 @@ function flattenSymbolsWithPositions(
 	isTest: boolean,
 	parentNames: readonly string[],
 	results: NodeWithPosition[],
+	seenIds: Map<string, number>,
 ): void {
 	for (const sym of symbols) {
 		const kind = symbolKindToNodeKind(sym.kind);
 		if (!kind) {
 			if (sym.children) {
-				flattenSymbolsWithPositions(sym.children, filePath, language, isTest, parentNames, results);
+				flattenSymbolsWithPositions(
+					sym.children,
+					filePath,
+					language,
+					isTest,
+					parentNames,
+					results,
+					seenIds,
+				);
 			}
 			continue;
 		}
 
 		const qualifiedName = [...parentNames, sym.name].join(".");
-		const id = `${filePath}::${qualifiedName}`;
+		const id = deduplicateId(`${filePath}::${qualifiedName}`, seenIds);
 
 		results.push({
 			node: {
@@ -138,6 +164,7 @@ function flattenSymbolsWithPositions(
 				isTest,
 				[...parentNames, sym.name],
 				results,
+				seenIds,
 			);
 		}
 	}

package/src/lsp/types.ts

@@ -29,6 +29,7 @@ const SymbolKind = {
 	Constructor: 9,
 	Variable: 13,
 	Property: 7,
+	Struct: 23,
 } as const;
 
 /** A symbol in a document, returned by textDocument/documentSymbol. */

package/src/main.ts

@@ -37,7 +37,7 @@ import {
 import type { Node } from "./types/graph.ts";
 import { isOk, unwrap } from "./types/result.ts";
 
-const VERSION = "0.3.0";
+const VERSION = "0.5.0";
 
 const program = new Command();
 program.name("lattice").description("Knowledge graph CLI for coding agents").version(VERSION);
@@ -269,17 +269,14 @@ program
 		const nodes = resolveSymbol(db, symbol);
 
 		if (nodes.length === 0) {
+			printUnknownSymbolError(db, symbol);
 			db.close();
-			console.log(`Unknown symbol: ${symbol}`);
 			process.exit(1);
 		}
 
 		if (nodes.length > 1) {
+			printAmbiguousSymbolError(nodes);
 			db.close();
-			console.log("Ambiguous symbol. Matches:");
-			for (const n of nodes) {
-				console.log(`  ${n.id}`);
-			}
 			process.exit(1);
 		}
 
@@ -459,15 +456,12 @@ function resolveOne(db: Database, symbol: string): Node {
 	const nodes = resolveSymbol(db, symbol);
 	if (nodes.length === 0) {
 		db.close();
-		console.error(`Unknown symbol: ${symbol}`);
+		printUnknownSymbolError(db, symbol);
 		process.exit(1);
 	}
 	if (nodes.length > 1) {
 		db.close();
-		console.error("Ambiguous symbol. Matches:");
-		for (const n of nodes) {
-			console.error(`  ${n.id}`);
-		}
+		printAmbiguousSymbolError(nodes);
 		process.exit(1);
 	}
 	const node = nodes[0];
@@ -479,6 +473,41 @@ function resolveOne(db: Database, symbol: string): Node {
 	return node;
 }
 
+function printUnknownSymbolError(db: Database, symbol: string): void {
+	console.error(`Unknown symbol: ${symbol}\n`);
+	console.error("Symbol format:");
+	console.error("  function_name                      unique name (if unambiguous)");
+	console.error("  src/file.ts::functionName           file::function");
+	console.error("  src/file.py::Class.method           file::Class.method\n");
+
+	const similar = findSimilarSymbols(db, symbol);
+	if (similar.length > 0) {
+		console.error("Did you mean:");
+		for (const s of similar) {
+			console.error(`  ${s}`);
+		}
+	}
+}
+
+function printAmbiguousSymbolError(nodes: readonly Node[]): void {
+	console.error("Ambiguous symbol. Qualify with file path:\n");
+	for (const n of nodes) {
+		console.error(`  lattice context ${n.id}`);
+	}
+}
+
+function findSimilarSymbols(db: Database, symbol: string): readonly string[] {
+	const lower = symbol.toLowerCase();
+	const parts = lower.split(".");
+	const name = parts[parts.length - 1] ?? lower;
+
+	const rows = db
+		.query("SELECT id, name FROM nodes WHERE LOWER(name) LIKE ? LIMIT 5")
+		.all(`%${name}%`) as { id: string; name: string }[];
+
+	return rows.map((r) => r.id);
+}
+
 /** Builds a flow tree by recursively following call edges from a root node. */
 function buildFlowTree(
 	db: Database,

package/src/types/config.ts

@@ -11,6 +11,12 @@ type TypeScriptConfig = {
 	readonly tsconfig: string | undefined;
 };
 
+/** Configuration for a Go language section. */
+type GoConfig = {
+	readonly sourceRoots: readonly string[];
+	readonly testPaths: readonly string[];
+};
+
 /** Lint-specific configuration. */
 type LintConfig = {
 	readonly strict: boolean;
@@ -24,7 +30,8 @@ type LatticeConfig = {
 	readonly exclude: readonly string[];
 	readonly python: PythonConfig | undefined;
 	readonly typescript: TypeScriptConfig | undefined;
+	readonly go: GoConfig | undefined;
 	readonly lint: LintConfig;
 };
 
-export type { LatticeConfig, LintConfig, PythonConfig, TypeScriptConfig };
+export type { GoConfig, LatticeConfig, LintConfig, PythonConfig, TypeScriptConfig };

package/scripts/postinstall.ts

@@ -1,69 +0,0 @@
-#!/usr/bin/env bun
-/**
- * Postinstall script — creates a minimal Python venv and installs zuban into it.
- * This gives zuban a proper Python environment with typeshed stubs.
- */
-import { existsSync } from "node:fs";
-import { join } from "node:path";
-
-const VENDOR_DIR = join(import.meta.dir, "..", "vendor");
-const VENV_DIR = join(VENDOR_DIR, "venv");
-
-function findPython(): string | undefined {
-	for (const cmd of ["python3", "python"]) {
-		if (Bun.which(cmd)) return cmd;
-	}
-	return undefined;
-}
-
-async function main() {
-	const isWindows = process.platform === "win32";
-	const zubanBin = join(VENV_DIR, isWindows ? "Scripts" : "bin", isWindows ? "zubanls.exe" : "zubanls");
-
-	if (existsSync(zubanBin)) {
-		console.log("zuban already installed");
-		return;
-	}
-
-	const python = findPython();
-	if (!python) {
-		console.warn("Warning: Python not found. Python support requires python3 in PATH.");
-		return;
-	}
-
-	console.log("Installing zuban for Python support...");
-
-	try {
-		// Create venv
-		const venvResult = Bun.spawnSync([python, "-m", "venv", VENV_DIR], {
-			stdout: "ignore",
-			stderr: "pipe",
-		});
-		if (venvResult.exitCode !== 0) {
-			throw new Error(`Failed to create venv: ${venvResult.stderr.toString()}`);
-		}
-
-		// Install zuban via pip
-		const pip = join(VENV_DIR, isWindows ? "Scripts" : "bin", "pip");
-		const pipResult = Bun.spawnSync([pip, "install", "zuban", "--quiet"], {
-			stdout: "ignore",
-			stderr: "pipe",
-		});
-		if (pipResult.exitCode !== 0) {
-			throw new Error(`Failed to install zuban: ${pipResult.stderr.toString()}`);
-		}
-
-		if (!existsSync(zubanBin)) {
-			throw new Error("zubanls binary not found after installation");
-		}
-
-		console.log("zuban installed successfully");
-	} catch (error) {
-		console.warn(
-			`Warning: Failed to install zuban: ${error instanceof Error ? error.message : error}. ` +
-				"Python support requires: pip install zuban",
-		);
-	}
-}
-
-main();