lattice-graph 0.4.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "lattice-graph",
-	"version": "0.4.0",
+	"version": "0.5.0",
 	"description": "Knowledge graph CLI for coding agents — navigate code through flows, not grep.",
 	"module": "src/main.ts",
 	"type": "module",

package/src/commands/build.ts

@@ -82,4 +82,4 @@ function buildLanguageConfigs(config: LatticeConfig): readonly LanguageConfig[]
 	return configs;
 }
 
-export { executeBuild };
+export { buildLanguageConfigs, executeBuild };

package/src/commands/init.ts

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+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");
@@ -111,4 +122,135 @@ function checkLspAvailability(languages: readonly string[]): readonly string[] {
 	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/main.ts

@@ -37,7 +37,7 @@ import {
 import type { Node } from "./types/graph.ts";
 import { isOk, unwrap } from "./types/result.ts";
 
-const VERSION = "0.4.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,