lattice-graph 0.1.0 → 0.3.0

package/src/lsp/client.ts

@@ -0,0 +1,211 @@
+import { type ChildProcess, spawn } from "node:child_process";
+import { readFileSync } from "node:fs";
+import type {
+	CallHierarchyItem,
+	CallHierarchyOutgoingCall,
+	DocumentSymbol,
+	JsonRpcMessage,
+	Location,
+} from "./types.ts";
+
+/** Options for creating an LSP client. */
+type LspClientOptions = {
+	readonly command: string;
+	readonly args: readonly string[];
+	readonly rootUri: string;
+	readonly languageId?: string;
+};
+
+/** An LSP client that communicates with a language server over stdio. */
+type LspClient = {
+	/** Waits for the server to be ready by probing a known file. */
+	waitForReady(filePath: string): Promise<void>;
+	/** Returns all symbols in a file. */
+	documentSymbol(filePath: string): Promise<readonly DocumentSymbol[]>;
+	/** Prepares a call hierarchy item at a position. */
+	prepareCallHierarchy(
+		filePath: string,
+		line: number,
+		character: number,
+	): Promise<readonly CallHierarchyItem[]>;
+	/** Returns outgoing calls from a call hierarchy item. */
+	outgoingCalls(item: CallHierarchyItem): Promise<readonly CallHierarchyOutgoingCall[]>;
+	/** Returns all reference locations for a symbol at a position. */
+	references(filePath: string, line: number, character: number): Promise<readonly Location[]>;
+	/** Shuts down the language server and kills the process. */
+	shutdown(): Promise<void>;
+};
+
+/**
+ * Creates an LSP client by spawning a language server process.
+ * Sends initialize/initialized, waits for readiness, then returns the client handle.
+ *
+ * @param opts - Server command, args, and project root URI
+ * @returns A ready LSP client
+ */
+async function createLspClient(opts: LspClientOptions): Promise<LspClient> {
+	let nextId = 1;
+	const pending = new Map<number, { resolve: (v: unknown) => void; reject: (e: Error) => void }>();
+	let buffer = "";
+	const openedFiles = new Set<string>();
+
+	const proc: ChildProcess = spawn(opts.command, [...opts.args], {
+		stdio: ["pipe", "pipe", "pipe"],
+	});
+
+	if (!proc.stdin || !proc.stdout) {
+		throw new Error(`Failed to spawn ${opts.command}`);
+	}
+
+	// Parse incoming JSON-RPC messages from stdout
+	proc.stdout.on("data", (chunk: Buffer) => {
+		buffer += chunk.toString();
+		while (true) {
+			const headerEnd = buffer.indexOf("\r\n\r\n");
+			if (headerEnd === -1) break;
+
+			const header = buffer.slice(0, headerEnd);
+			const match = header.match(/Content-Length:\s*(\d+)/i);
+			if (!match) {
+				buffer = buffer.slice(headerEnd + 4);
+				continue;
+			}
+
+			const contentLength = Number.parseInt(match[1] as string, 10);
+			const bodyStart = headerEnd + 4;
+			if (buffer.length < bodyStart + contentLength) break;
+
+			const body = buffer.slice(bodyStart, bodyStart + contentLength);
+			buffer = buffer.slice(bodyStart + contentLength);
+
+			try {
+				const msg = JSON.parse(body) as JsonRpcMessage;
+				if (msg.id !== undefined && pending.has(msg.id)) {
+					const handler = pending.get(msg.id);
+					pending.delete(msg.id);
+					if (msg.error) {
+						handler?.reject(new Error(`LSP error: ${msg.error.message}`));
+					} else {
+						handler?.resolve(msg.result);
+					}
+				}
+			} catch {
+				// Ignore malformed messages
+			}
+		}
+	});
+
+	function sendRequest(method: string, params: unknown): Promise<unknown> {
+		const id = nextId++;
+		const msg: JsonRpcMessage = { jsonrpc: "2.0", id, method, params };
+		const body = JSON.stringify(msg);
+		const header = `Content-Length: ${Buffer.byteLength(body)}\r\n\r\n`;
+		proc.stdin?.write(header + body);
+
+		return new Promise((resolve, reject) => {
+			pending.set(id, { resolve, reject });
+		});
+	}
+
+	function sendNotification(method: string, params: unknown): void {
+		const msg = { jsonrpc: "2.0", method, params };
+		const body = JSON.stringify(msg);
+		const header = `Content-Length: ${Buffer.byteLength(body)}\r\n\r\n`;
+		proc.stdin?.write(header + body);
+	}
+
+	const langId = opts.languageId ?? "typescript";
+
+	function openFile(filePath: string): void {
+		const uri = `file://${filePath}`;
+		if (openedFiles.has(uri)) return;
+		openedFiles.add(uri);
+
+		const text = readFileSync(filePath, "utf-8");
+		sendNotification("textDocument/didOpen", {
+			textDocument: { uri, languageId: langId, version: 1, text },
+		});
+	}
+
+	// Initialize
+	await sendRequest("initialize", {
+		processId: process.pid,
+		rootUri: opts.rootUri,
+		capabilities: {
+			textDocument: {
+				documentSymbol: { hierarchicalDocumentSymbolSupport: true },
+				callHierarchy: { dynamicRegistration: false },
+			},
+		},
+	});
+
+	sendNotification("initialized", {});
+
+	const client: LspClient = {
+		async waitForReady(probePath: string): Promise<void> {
+			openFile(probePath);
+			const delays = [100, 200, 400, 800, 1600, 3200];
+			for (const delay of delays) {
+				const result = (await sendRequest("textDocument/documentSymbol", {
+					textDocument: { uri: `file://${probePath}` },
+				})) as readonly DocumentSymbol[] | null;
+				if (result && result.length > 0) return;
+				await new Promise((r) => setTimeout(r, delay));
+			}
+		},
+
+		async documentSymbol(filePath: string): Promise<readonly DocumentSymbol[]> {
+			openFile(filePath);
+			const result = await sendRequest("textDocument/documentSymbol", {
+				textDocument: { uri: `file://${filePath}` },
+			});
+			return (result as readonly DocumentSymbol[]) ?? [];
+		},
+
+		async prepareCallHierarchy(
+			filePath: string,
+			line: number,
+			character: number,
+		): Promise<readonly CallHierarchyItem[]> {
+			openFile(filePath);
+			const result = await sendRequest("textDocument/prepareCallHierarchy", {
+				textDocument: { uri: `file://${filePath}` },
+				position: { line, character },
+			});
+			return (result as readonly CallHierarchyItem[]) ?? [];
+		},
+
+		async outgoingCalls(item: CallHierarchyItem): Promise<readonly CallHierarchyOutgoingCall[]> {
+			const result = await sendRequest("callHierarchy/outgoingCalls", { item });
+			return (result as readonly CallHierarchyOutgoingCall[]) ?? [];
+		},
+
+		async references(
+			filePath: string,
+			line: number,
+			character: number,
+		): Promise<readonly Location[]> {
+			openFile(filePath);
+			const result = await sendRequest("textDocument/references", {
+				textDocument: { uri: `file://${filePath}` },
+				position: { line, character },
+				context: { includeDeclaration: false },
+			});
+			return (result as readonly Location[]) ?? [];
+		},
+
+		async shutdown(): Promise<void> {
+			try {
+				await sendRequest("shutdown", null);
+				sendNotification("exit", null);
+			} catch {
+				// Server may already be dead
+			}
+			proc.kill();
+		},
+	};
+
+	return client;
+}
+
+export { createLspClient, type LspClient, type LspClientOptions };

package/src/lsp/symbols.ts

@@ -0,0 +1,146 @@
+import type { Node, NodeKind } from "../types/graph.ts";
+import { type DocumentSymbol, SymbolKind } from "./types.ts";
+
+/**
+ * Converts LSP DocumentSymbol responses into Lattice Node objects.
+ * Flattens the hierarchy and builds qualified names (e.g., ClassName.methodName).
+ *
+ * @param symbols - DocumentSymbol array from LSP
+ * @param filePath - Relative file path for node IDs
+ * @param language - Language identifier
+ * @param isTest - Whether this file is in a test directory
+ * @returns Flat array of Lattice Nodes
+ */
+function documentSymbolsToNodes(
+	symbols: readonly DocumentSymbol[],
+	filePath: string,
+	language: string,
+	isTest: boolean,
+): readonly Node[] {
+	const nodes: Node[] = [];
+	flattenSymbols(symbols, filePath, language, isTest, [], nodes);
+	return nodes;
+}
+
+function flattenSymbols(
+	symbols: readonly DocumentSymbol[],
+	filePath: string,
+	language: string,
+	isTest: boolean,
+	parentNames: readonly string[],
+	results: Node[],
+): 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);
+			}
+			continue;
+		}
+
+		const qualifiedName = [...parentNames, sym.name].join(".");
+		const id = `${filePath}::${qualifiedName}`;
+
+		results.push({
+			id,
+			kind,
+			name: sym.name,
+			file: filePath,
+			lineStart: sym.range.start.line + 1,
+			lineEnd: sym.range.end.line + 1,
+			language,
+			signature: undefined,
+			isTest,
+			metadata: undefined,
+		});
+
+		if (sym.children) {
+			flattenSymbols(sym.children, filePath, language, isTest, [...parentNames, sym.name], results);
+		}
+	}
+}
+
+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";
+	return undefined;
+}
+
+/** A Lattice Node paired with the LSP selectionRange position for call hierarchy queries. */
+type NodeWithPosition = {
+	readonly node: Node;
+	readonly selectionLine: number;
+	readonly selectionCharacter: number;
+};
+
+/**
+ * Like documentSymbolsToNodes but also returns the selectionRange position
+ * needed for prepareCallHierarchy requests.
+ */
+function documentSymbolsToNodesWithPositions(
+	symbols: readonly DocumentSymbol[],
+	filePath: string,
+	language: string,
+	isTest: boolean,
+): readonly NodeWithPosition[] {
+	const results: NodeWithPosition[] = [];
+	flattenSymbolsWithPositions(symbols, filePath, language, isTest, [], results);
+	return results;
+}
+
+function flattenSymbolsWithPositions(
+	symbols: readonly DocumentSymbol[],
+	filePath: string,
+	language: string,
+	isTest: boolean,
+	parentNames: readonly string[],
+	results: NodeWithPosition[],
+): void {
+	for (const sym of symbols) {
+		const kind = symbolKindToNodeKind(sym.kind);
+		if (!kind) {
+			if (sym.children) {
+				flattenSymbolsWithPositions(sym.children, filePath, language, isTest, parentNames, results);
+			}
+			continue;
+		}
+
+		const qualifiedName = [...parentNames, sym.name].join(".");
+		const id = `${filePath}::${qualifiedName}`;
+
+		results.push({
+			node: {
+				id,
+				kind,
+				name: sym.name,
+				file: filePath,
+				lineStart: sym.range.start.line + 1,
+				lineEnd: sym.range.end.line + 1,
+				language,
+				signature: undefined,
+				isTest,
+				metadata: undefined,
+			},
+			selectionLine: sym.selectionRange.start.line,
+			selectionCharacter: sym.selectionRange.start.character,
+		});
+
+		if (sym.children) {
+			flattenSymbolsWithPositions(
+				sym.children,
+				filePath,
+				language,
+				isTest,
+				[...parentNames, sym.name],
+				results,
+			);
+		}
+	}
+}
+
+export { documentSymbolsToNodes, documentSymbolsToNodesWithPositions, type NodeWithPosition };

package/src/lsp/types.ts

@@ -0,0 +1,73 @@
+/** JSON-RPC message envelope. */
+type JsonRpcMessage = {
+	readonly jsonrpc: "2.0";
+	readonly id?: number;
+	readonly method?: string;
+	readonly params?: unknown;
+	readonly result?: unknown;
+	readonly error?: { readonly code: number; readonly message: string; readonly data?: unknown };
+};
+
+/** Position in a text document (0-based). */
+type Position = {
+	readonly line: number;
+	readonly character: number;
+};
+
+/** Range in a text document. */
+type Range = {
+	readonly start: Position;
+	readonly end: Position;
+};
+
+/** LSP SymbolKind values (subset Lattice uses). */
+const SymbolKind = {
+	Function: 12,
+	Method: 6,
+	Class: 5,
+	Interface: 11,
+	Constructor: 9,
+	Variable: 13,
+	Property: 7,
+} as const;
+
+/** A symbol in a document, returned by textDocument/documentSymbol. */
+type DocumentSymbol = {
+	readonly name: string;
+	readonly kind: number;
+	readonly range: Range;
+	readonly selectionRange: Range;
+	readonly children?: readonly DocumentSymbol[];
+};
+
+/** A call hierarchy item, returned by textDocument/prepareCallHierarchy. */
+type CallHierarchyItem = {
+	readonly name: string;
+	readonly kind: number;
+	readonly uri: string;
+	readonly range: Range;
+	readonly selectionRange: Range;
+};
+
+/** An outgoing call, returned by callHierarchy/outgoingCalls. */
+type CallHierarchyOutgoingCall = {
+	readonly to: CallHierarchyItem;
+	readonly fromRanges: readonly Range[];
+};
+
+/** A location in a document, returned by textDocument/references. */
+type Location = {
+	readonly uri: string;
+	readonly range: Range;
+};
+
+export {
+	type CallHierarchyItem,
+	type CallHierarchyOutgoingCall,
+	type DocumentSymbol,
+	type JsonRpcMessage,
+	type Location,
+	type Position,
+	type Range,
+	SymbolKind,
+};

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.1.0";
+const VERSION = "0.3.0";
 
 const program = new Command();
 program.name("lattice").description("Knowledge graph CLI for coding agents").version(VERSION);
@@ -109,8 +109,7 @@ program
 	.command("lint")
 	.description("Validate tags: syntax, typos, orphans, missing tags")
 	.option("--strict", "Treat warnings as errors")
-	.option("--unresolved", "Show detailed unresolved references")
-	.action((opts: { strict?: boolean; unresolved?: boolean }) => {
+	.action((opts: { strict?: boolean }) => {
 		const cwd = process.cwd();
 		const configResult = loadConfig(cwd);
 		if (!isOk(configResult)) {
@@ -147,21 +146,6 @@ program
 		console.log(
 			`Info:\n  Coverage: ${result.coverage.tagged}/${result.coverage.total} entry points tagged (${result.coverage.total > 0 ? Math.round((result.coverage.tagged / result.coverage.total) * 100) : 0}%)`,
 		);
-		console.log(`  Unresolved references: ${result.unresolvedCount}`);
-
-		// Unresolved details
-		if (opts.unresolved) {
-			const refs = db
-				.query("SELECT file, line, expression, reason FROM unresolved ORDER BY file, line")
-				.all() as { file: string; line: number; expression: string; reason: string }[];
-			if (refs.length > 0) {
-				console.log("\nUnresolved references:");
-				for (const ref of refs) {
-					console.log(`  ${ref.file}:${ref.line}  ${ref.expression} (${ref.reason})`);
-				}
-			}
-		}
-
 		db.close();
 
 		// Exit code

package/src/types/config.ts

@@ -2,7 +2,6 @@
 type PythonConfig = {
 	readonly sourceRoots: readonly string[];
 	readonly testPaths: readonly string[];
-	readonly frameworks: readonly string[];
 };
 
 /** Configuration for a TypeScript language section. */
@@ -10,7 +9,6 @@ type TypeScriptConfig = {
 	readonly sourceRoots: readonly string[];
 	readonly testPaths: readonly string[];
 	readonly tsconfig: string | undefined;
-	readonly frameworks: readonly string[];
 };
 
 /** Lint-specific configuration. */

package/src/types/graph.ts

@@ -10,19 +10,6 @@ type EdgeKind = (typeof EDGE_KINDS)[number];
 const TAG_KINDS = ["flow", "boundary", "emits", "handles"] as const;
 type TagKind = (typeof TAG_KINDS)[number];
 
-/** Certainty level of an edge relationship. */
-const CERTAINTY_LEVELS = ["certain", "uncertain"] as const;
-type Certainty = (typeof CERTAINTY_LEVELS)[number];
-
-/** Reasons an extractor may fail to resolve a reference. */
-const UNRESOLVED_REASONS = [
-	"dynamic_dispatch",
-	"unknown_module",
-	"computed_property",
-	"untyped_call",
-] as const;
-type UnresolvedReason = (typeof UNRESOLVED_REASONS)[number];
-
 /** A symbol in the codebase (function, class, method, type, module). */
 type Node = {
 	readonly id: string;
@@ -42,7 +29,6 @@ type Edge = {
 	readonly sourceId: string;
 	readonly targetId: string;
 	readonly kind: EdgeKind;
-	readonly certainty: Certainty;
 };
 
 /** A lattice annotation on a node. */
@@ -52,36 +38,22 @@ type Tag = {
 	readonly value: string;
 };
 
-/** A reference that could not be resolved during extraction. */
-type UnresolvedReference = {
-	readonly file: string;
-	readonly line: number;
-	readonly expression: string;
-	readonly reason: UnresolvedReason;
-};
-
-/** The complete output of extracting a single file. */
-type ExtractionResult = {
-	readonly nodes: readonly Node[];
-	readonly edges: readonly Edge[];
-	readonly tags: readonly Tag[];
-	readonly unresolved: readonly UnresolvedReference[];
+/** A call from a project function to an external package. */
+type ExternalCall = {
+	readonly nodeId: string;
+	readonly package: string;
+	readonly symbol: string;
 };
 
 export {
-	CERTAINTY_LEVELS,
-	type Certainty,
 	EDGE_KINDS,
 	type Edge,
 	type EdgeKind,
-	type ExtractionResult,
+	type ExternalCall,
 	NODE_KINDS,
 	type Node,
 	type NodeKind,
 	TAG_KINDS,
 	type Tag,
 	type TagKind,
-	UNRESOLVED_REASONS,
-	type UnresolvedReason,
-	type UnresolvedReference,
 };

package/src/types/lint.ts

@@ -15,7 +15,6 @@ type LintIssue = {
 type LintResult = {
 	readonly issues: readonly LintIssue[];
 	readonly coverage: { readonly tagged: number; readonly total: number };
-	readonly unresolvedCount: number;
 };
 
 export type { LintIssue, LintResult, LintSeverity };

package/src/extract/extractor.ts

@@ -1,13 +0,0 @@
-import type { ExtractionResult } from "../types/graph.ts";
-
-/**
- * Language-specific extractor that produces nodes, edges, and tags from source files.
- * Each supported language implements this type.
- */
-type Extractor = {
-	readonly language: string;
-	readonly fileExtensions: readonly string[];
-	readonly extract: (filePath: string, source: string) => Promise<ExtractionResult>;
-};
-
-export type { Extractor };

package/src/extract/parser.ts

@@ -1,117 +0,0 @@
-/**
- * Shared tree-sitter parser initialization.
- * Uses web-tree-sitter with WASM grammars from tree-sitter-wasms.
- */
-
-// web-tree-sitter 0.24.x uses CJS exports
-// biome-ignore lint/suspicious/noExplicitAny: web-tree-sitter 0.24 has no ESM types
-const TreeSitter = require("web-tree-sitter") as any;
-
-type TreeSitterParser = {
-	setLanguage(lang: TreeSitterLanguage): void;
-	parse(input: string): TreeSitterTree;
-};
-
-type TreeSitterLanguage = {
-	readonly version: number;
-};
-
-type TreeSitterTree = {
-	readonly rootNode: TreeSitterNode;
-};
-
-type TreeSitterNode = {
-	readonly type: string;
-	readonly text: string;
-	readonly startPosition: { row: number; column: number };
-	readonly endPosition: { row: number; column: number };
-	readonly startIndex: number;
-	readonly endIndex: number;
-	readonly childCount: number;
-	readonly children: readonly TreeSitterNode[];
-	readonly parent: TreeSitterNode | null;
-	readonly firstChild: TreeSitterNode | null;
-	readonly lastChild: TreeSitterNode | null;
-	readonly nextSibling: TreeSitterNode | null;
-	readonly previousSibling: TreeSitterNode | null;
-	childForFieldName(fieldName: string): TreeSitterNode | null;
-	childrenForFieldName(fieldName: string): readonly TreeSitterNode[];
-	descendantsOfType(type: string | readonly string[]): readonly TreeSitterNode[];
-};
-
-let initialized = false;
-const languageCache = new Map<string, TreeSitterLanguage>();
-
-/**
- * Resolves the WASM file path for a language grammar.
- * Tries multiple locations to support both dev and compiled binary modes:
- * 1. Relative to this source file (dev: bun src/main.ts)
- * 2. Relative to the compiled binary (binary: ./lattice)
- * 3. Relative to CWD (when node_modules exists in working dir)
- */
-function grammarPath(language: string): string {
-	const { existsSync } = require("node:fs");
-	const { dirname, join } = require("node:path");
-	const filename = `tree-sitter-${language}.wasm`;
-	const subpath = `node_modules/tree-sitter-wasms/out/${filename}`;
-
-	// Try relative to this source file (dev mode)
-	const packageRoot = new URL("../../", import.meta.url).pathname;
-	const devPath = join(packageRoot, subpath);
-	if (existsSync(devPath)) return devPath;
-
-	// Try relative to the binary's location (compiled mode)
-	const binDir = dirname(process.execPath);
-	const binPath = join(binDir, subpath);
-	if (existsSync(binPath)) return binPath;
-
-	// Try relative to CWD
-	const cwdPath = join(process.cwd(), subpath);
-	if (existsSync(cwdPath)) return cwdPath;
-
-	// Fall back — will produce a clear error
-	return devPath;
-}
-
-/**
- * Initializes tree-sitter WASM runtime. Must be called once before parsing.
- * Safe to call multiple times — subsequent calls are no-ops.
- */
-async function initTreeSitter(): Promise<void> {
-	if (initialized) return;
-	await TreeSitter.init();
-	initialized = true;
-}
-
-/**
- * Creates a parser configured for the given language.
- *
- * @param language - Language name matching the WASM grammar file (e.g., "python", "typescript")
- * @returns A configured parser ready to parse source code
- */
-async function createParser(language: string): Promise<TreeSitterParser> {
-	await initTreeSitter();
-
-	const cached = languageCache.get(language);
-	const lang = cached ?? (await loadAndCacheLanguage(language));
-
-	const parser = new TreeSitter();
-	parser.setLanguage(lang);
-	return parser as TreeSitterParser;
-}
-
-/** Loads a language grammar from WASM and caches it. */
-async function loadAndCacheLanguage(language: string): Promise<TreeSitterLanguage> {
-	const lang = (await TreeSitter.Language.load(grammarPath(language))) as TreeSitterLanguage;
-	languageCache.set(language, lang);
-	return lang;
-}
-
-export {
-	createParser,
-	initTreeSitter,
-	type TreeSitterLanguage,
-	type TreeSitterNode,
-	type TreeSitterParser,
-	type TreeSitterTree,
-};