lattice-graph 0.1.0

package/src/commands/init.ts

@@ -0,0 +1,111 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { err, ok, type Result } from "../types/result.ts";
+
+/**
+ * Initializes a Lattice project by creating .lattice/ directory
+ * and a starter lattice.toml with detected languages.
+ *
+ * @param projectRoot - Path to the project root directory
+ * @returns Ok on success, Err with a message on failure
+ */
+// @lattice:flow init
+function executeInit(projectRoot: string): Result<string, string> {
+	try {
+		// Create .lattice directory
+		const latticeDir = join(projectRoot, ".lattice");
+		mkdirSync(latticeDir, { recursive: true });
+
+		// Generate lattice.toml if it doesn't exist
+		const tomlPath = join(projectRoot, "lattice.toml");
+		if (!existsSync(tomlPath)) {
+			const languages = detectLanguages(projectRoot);
+			const root = detectRoot(projectRoot);
+			const toml = generateToml(languages, root);
+			writeFileSync(tomlPath, toml);
+		}
+
+		return ok("Initialized Lattice project");
+	} catch (error) {
+		return err(`Init failed: ${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+
+/** Detects which languages are present in the project by scanning for file extensions. */
+function detectLanguages(projectRoot: string): readonly string[] {
+	const languages: string[] = [];
+	const glob = new Bun.Glob("**/*.{py,ts,tsx,js,jsx}");
+
+	let hasPython = false;
+	let hasTypeScript = false;
+
+	for (const path of glob.scanSync({ cwd: projectRoot, dot: false })) {
+		if (
+			path.includes("node_modules") ||
+			path.includes(".git") ||
+			path.includes("test") ||
+			path.includes("fixture") ||
+			path.includes("vendor") ||
+			path.includes("dist")
+		)
+			continue;
+		if (path.endsWith(".py")) hasPython = true;
+		if (path.endsWith(".ts") || path.endsWith(".tsx")) hasTypeScript = true;
+		if (hasPython && hasTypeScript) break;
+	}
+
+	if (hasPython) languages.push("python");
+	if (hasTypeScript) languages.push("typescript");
+
+	return languages;
+}
+
+/** Detects the source root — uses "src" if it exists, otherwise ".". */
+function detectRoot(projectRoot: string): string {
+	const srcPath = `${projectRoot}/src`;
+	try {
+		const { statSync } = require("node:fs");
+		if (statSync(srcPath).isDirectory()) return "src";
+	} catch {
+		// src/ doesn't exist
+	}
+	return ".";
+}
+
+/** Generates a starter lattice.toml with detected languages. */
+function generateToml(languages: readonly string[], root: string): string {
+	const langArray = languages.map((l) => `"${l}"`).join(", ");
+	const lines: string[] = [
+		"[project]",
+		`languages = [${langArray}]`,
+		`root = "${root}"`,
+		'exclude = ["node_modules", "venv", ".git", "dist", "__pycache__", ".lattice"]',
+		"",
+	];
+
+	if (languages.includes("python")) {
+		lines.push(
+			"[python]",
+			`source_roots = ["${root}"]`,
+			'test_paths = ["tests"]',
+			"frameworks = []",
+			"",
+		);
+	}
+
+	if (languages.includes("typescript")) {
+		lines.push(
+			"[typescript]",
+			`source_roots = ["${root}"]`,
+			'test_paths = ["tests"]',
+			"frameworks = []",
+			"",
+		);
+	}
+
+	lines.push("[lint]", "strict = false", "ignore = []", "");
+
+	return lines.join("\n");
+}
+
+export { executeInit };

package/src/commands/lint.ts

@@ -0,0 +1,245 @@
+import type { Database } from "bun:sqlite";
+import type { LatticeConfig } from "../types/config.ts";
+import type { LintIssue, LintResult } from "../types/lint.ts";
+
+/**
+ * Runs all lint checks against the built knowledge graph.
+ * Does not modify the database — reports only.
+ *
+ * @param db - An open Database handle (readonly)
+ * @param config - Lattice configuration for boundary package detection
+ * @returns Lint result with issues, coverage, and unresolved count
+ */
+// @lattice:flow lint
+function executeLint(db: Database, _config: LatticeConfig): LintResult {
+	const issues: LintIssue[] = [];
+
+	checkMissingFlowTags(db, issues);
+	checkInvalidTags(db, issues);
+	checkTypos(db, issues);
+	checkOrphanedEvents(db, issues);
+	checkStaleBoundaryTags(db, issues);
+
+	const coverage = computeCoverage(db);
+	const unresolvedCount = countUnresolved(db);
+
+	return { issues, coverage, unresolvedCount };
+}
+
+/** Checks for route handlers without @lattice:flow tags. */
+function checkMissingFlowTags(db: Database, issues: LintIssue[]): void {
+	// Nodes with route metadata (detected by framework extractors) but no flow tag
+	const rows = db
+		.query(
+			`SELECT n.id, n.name, n.file, n.line_start FROM nodes n
+			WHERE n.metadata IS NOT NULL AND n.metadata LIKE '%"route"%'
+			AND NOT EXISTS (SELECT 1 FROM tags t WHERE t.node_id = n.id AND t.kind = 'flow')`,
+		)
+		.all() as { id: string; name: string; file: string; line_start: number }[];
+
+	for (const row of rows) {
+		issues.push({
+			severity: "error",
+			file: row.file,
+			line: row.line_start,
+			symbol: row.name,
+			message: `Route handler missing @lattice:flow tag`,
+		});
+	}
+}
+
+/** Checks for tags placed on invalid node kinds (e.g., flow tag on a class). */
+function checkInvalidTags(db: Database, issues: LintIssue[]): void {
+	const rows = db
+		.query(
+			`SELECT t.kind AS tag_kind, t.value, n.id, n.name, n.kind AS node_kind, n.file, n.line_start
+			FROM tags t JOIN nodes n ON t.node_id = n.id
+			WHERE n.kind NOT IN ('function', 'method')`,
+		)
+		.all() as {
+		tag_kind: string;
+		value: string;
+		id: string;
+		name: string;
+		node_kind: string;
+		file: string;
+		line_start: number;
+	}[];
+
+	for (const row of rows) {
+		issues.push({
+			severity: "error",
+			file: row.file,
+			line: row.line_start,
+			symbol: row.name,
+			message: `@lattice:${row.tag_kind} tag on a ${row.node_kind} — tags should only be on functions or methods`,
+		});
+	}
+}
+
+/** Checks for probable typos by finding tag values used only once when similar values exist. */
+function checkTypos(db: Database, issues: LintIssue[]): void {
+	// Group tag values by kind, find singletons
+	const tagCounts = db
+		.query("SELECT kind, value, COUNT(*) as cnt FROM tags GROUP BY kind, value")
+		.all() as { kind: string; value: string; cnt: number }[];
+
+	const singletons = tagCounts.filter((t) => t.cnt === 1);
+	const commons = tagCounts.filter((t) => t.cnt > 1);
+
+	for (const single of singletons) {
+		const similar = commons.filter(
+			(c) => c.kind === single.kind && editDistance(single.value, c.value) <= 2,
+		);
+		if (similar.length > 0) {
+			const bestMatch = similar[0];
+			const tagNode = db
+				.query(
+					`SELECT n.name, n.file, n.line_start FROM tags t JOIN nodes n ON t.node_id = n.id
+					WHERE t.kind = ? AND t.value = ?`,
+				)
+				.get(single.kind, single.value) as {
+				name: string;
+				file: string;
+				line_start: number;
+			} | null;
+
+			if (tagNode && bestMatch) {
+				issues.push({
+					severity: "warning",
+					file: tagNode.file,
+					line: tagNode.line_start,
+					symbol: tagNode.name,
+					message: `@lattice:${single.kind} "${single.value}" — did you mean "${bestMatch.value}"? (used ${bestMatch.cnt} times elsewhere)`,
+				});
+			}
+		}
+	}
+}
+
+/** Checks for events that are emitted but never handled, or handled but never emitted. */
+function checkOrphanedEvents(db: Database, issues: LintIssue[]): void {
+	// Emits with no matching handles
+	const orphanedEmits = db
+		.query(
+			`SELECT t.value, n.name, n.file, n.line_start FROM tags t
+			JOIN nodes n ON t.node_id = n.id
+			WHERE t.kind = 'emits'
+			AND NOT EXISTS (SELECT 1 FROM tags h WHERE h.kind = 'handles' AND h.value = t.value)`,
+		)
+		.all() as { value: string; name: string; file: string; line_start: number }[];
+
+	for (const row of orphanedEmits) {
+		issues.push({
+			severity: "warning",
+			file: row.file,
+			line: row.line_start,
+			symbol: row.name,
+			message: `@lattice:emits "${row.value}" has no handler — no @lattice:handles "${row.value}" found`,
+		});
+	}
+
+	// Handles with no matching emits
+	const orphanedHandles = db
+		.query(
+			`SELECT t.value, n.name, n.file, n.line_start FROM tags t
+			JOIN nodes n ON t.node_id = n.id
+			WHERE t.kind = 'handles'
+			AND NOT EXISTS (SELECT 1 FROM tags e WHERE e.kind = 'emits' AND e.value = t.value)`,
+		)
+		.all() as { value: string; name: string; file: string; line_start: number }[];
+
+	for (const row of orphanedHandles) {
+		issues.push({
+			severity: "warning",
+			file: row.file,
+			line: row.line_start,
+			symbol: row.name,
+			message: `@lattice:handles "${row.value}" has no emitter — no @lattice:emits "${row.value}" found`,
+		});
+	}
+}
+
+/**
+ * Checks for stale boundary tags.
+ * A boundary tag is stale if the tagged function has no uncertain call edges at all
+ * (meaning it doesn't call any external code that could be the boundary).
+ */
+function checkStaleBoundaryTags(db: Database, issues: LintIssue[]): void {
+	const boundaryTags = db
+		.query(
+			`SELECT t.node_id, t.value, n.name, n.file, n.line_start FROM tags t
+			JOIN nodes n ON t.node_id = n.id
+			WHERE t.kind = 'boundary'`,
+		)
+		.all() as { node_id: string; value: string; name: string; file: string; line_start: number }[];
+
+	for (const tag of boundaryTags) {
+		// A boundary function should have at least one uncertain call edge
+		// (calls to external packages are marked uncertain during extraction)
+		const hasExternalCall = db
+			.query("SELECT 1 FROM edges WHERE source_id = ? AND certainty = 'uncertain' LIMIT 1")
+			.get(tag.node_id);
+
+		if (!hasExternalCall) {
+			issues.push({
+				severity: "warning",
+				file: tag.file,
+				line: tag.line_start,
+				symbol: tag.name,
+				message: `@lattice:boundary "${tag.value}" may be stale — no external calls found in this function`,
+			});
+		}
+	}
+}
+
+/** Computes tag coverage: how many detected entry points are tagged vs total. */
+function computeCoverage(db: Database): { tagged: number; total: number } {
+	const total = db
+		.query(
+			"SELECT COUNT(*) as c FROM nodes WHERE metadata IS NOT NULL AND metadata LIKE '%\"route\"%'",
+		)
+		.get() as { c: number };
+
+	const tagged = db
+		.query(
+			`SELECT COUNT(*) as c FROM nodes n
+			WHERE n.metadata IS NOT NULL AND n.metadata LIKE '%"route"%'
+			AND EXISTS (SELECT 1 FROM tags t WHERE t.node_id = n.id AND t.kind = 'flow')`,
+		)
+		.get() as { c: number };
+
+	return { tagged: tagged.c, total: total.c };
+}
+
+/** Counts unresolved references in the database. */
+function countUnresolved(db: Database): number {
+	const row = db.query("SELECT COUNT(*) as c FROM unresolved").get() as { c: number };
+	return row.c;
+}
+
+/**
+ * Computes the Levenshtein edit distance between two strings.
+ * Used for typo detection in tag values.
+ */
+function editDistance(a: string, b: string): number {
+	const m = a.length;
+	const n = b.length;
+
+	// Use two rows instead of a full matrix to avoid index safety issues
+	let prev = Array.from({ length: n + 1 }, (_, j) => j);
+	let curr = new Array<number>(n + 1).fill(0);
+
+	for (let i = 1; i <= m; i++) {
+		curr[0] = i;
+		for (let j = 1; j <= n; j++) {
+			const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+			curr[j] = Math.min((prev[j] ?? 0) + 1, (curr[j - 1] ?? 0) + 1, (prev[j - 1] ?? 0) + cost);
+		}
+		[prev, curr] = [curr, prev];
+	}
+
+	return prev[n] ?? 0;
+}
+
+export { executeLint };

package/src/commands/populate.ts

@@ -0,0 +1,224 @@
+import type { Database } from "bun:sqlite";
+import type { LatticeConfig } from "../types/config.ts";
+
+/**
+ * Generates a structured workflow that instructs a coding agent to tag the codebase.
+ * Includes tag spec, few-shot examples, project context, and a step-by-step process
+ * with explicit validation checkpoints.
+ *
+ * @param db - An open Database handle with a built graph
+ * @param _config - Lattice configuration (reserved for future use)
+ * @returns A complete instruction string for the coding agent
+ */
+// @lattice:flow populate
+function executePopulate(db: Database, _config: LatticeConfig): string {
+	const sections: string[] = [];
+
+	sections.push(tagSpecSection());
+	sections.push(examplesSection());
+	sections.push(projectSummarySection(db));
+	sections.push(workflowSection());
+
+	return sections.join("\n\n");
+}
+
+/** Outputs the tag spec — what each tag means and the syntax rules. */
+function tagSpecSection(): string {
+	return `## Lattice Tag Specification
+
+Four tags, placed in comments directly above function definitions:
+
+- \`@lattice:flow <name>\` — Flow entry point. Where execution begins for a business operation. Route handlers, CLI commands, cron jobs, queue consumers.
+- \`@lattice:boundary <system>\` — External boundary. Where code leaves the codebase. API calls, database queries, cache operations, third-party SDKs.
+- \`@lattice:emits <event>\` — Event emission. Publishes to a queue, event bus, or notification system.
+- \`@lattice:handles <event>\` — Event consumption. Subscribes to or processes events. Must match a corresponding emits tag.
+
+Rules:
+- Place the tag comment directly above the function definition, no blank lines between
+- Names are kebab-case: \`checkout\`, \`user-registration\`, \`order.created\`, \`aws-s3\`
+- Multiple values: \`# @lattice:flow checkout, payment\`
+- Do NOT tag intermediate functions — only entry points and boundaries. Everything in between is derived from the call graph automatically.`;
+}
+
+/** Few-shot examples showing correct tagging across different scenarios. */
+function examplesSection(): string {
+	return `## Examples
+
+### Python — FastAPI route with boundary and events
+
+\`\`\`python
+# @lattice:flow checkout
+@app.post("/api/checkout")
+def handle_checkout(req):
+    order = create_order(req)       # no tag — derived from call graph
+    return order
+
+def create_order(req):              # no tag — derived from call graph
+    charge(req.amount, req.token)
+    save_order(req)
+    emit_order_created(req.order_id)
+
+# @lattice:boundary stripe
+def charge(amount, token):
+    return stripe.charges.create(amount=amount, source=token)
+
+# @lattice:boundary postgres
+def save_order(req):
+    db.execute("INSERT INTO orders ...")
+
+# @lattice:emits order.created
+def emit_order_created(order_id):
+    queue.publish("order.created", {"order_id": order_id})
+
+# @lattice:handles order.created
+def send_confirmation(event):
+    sendgrid.send(event.order_id)
+\`\`\`
+
+### TypeScript — Express route with database boundary
+
+\`\`\`typescript
+// @lattice:flow user-registration
+router.post("/api/users", async (req, res) => {
+  const user = await createUser(req.body);
+  res.json(user);
+});
+
+// @lattice:boundary postgres
+async function createUser(data: CreateUserInput): Promise<User> {
+  return db.query("INSERT INTO users ...").run(data);
+}
+\`\`\`
+
+### Python — Celery task as entry point
+
+\`\`\`python
+# @lattice:flow invoice-generation
+@shared_task
+def generate_invoice(order_id):
+    order = fetch_order(order_id)
+    pdf = render_invoice(order)
+    send_invoice_email(order, pdf)
+
+# @lattice:boundary s3
+def render_invoice(order):
+    pdf = create_pdf(order)
+    s3.upload(f"invoices/{order.id}.pdf", pdf)
+    return pdf
+\`\`\``;
+}
+
+/** Brief project summary from the graph — just enough context, not a file listing. */
+function projectSummarySection(db: Database): string {
+	const lines: string[] = ["## This Project", ""];
+
+	const fileCount = (db.query("SELECT COUNT(DISTINCT file) as c FROM nodes").get() as { c: number })
+		.c;
+	const nodeCount = (db.query("SELECT COUNT(*) as c FROM nodes").get() as { c: number }).c;
+	const edgeCount = (db.query("SELECT COUNT(*) as c FROM edges").get() as { c: number }).c;
+
+	lines.push(`${fileCount} files, ${nodeCount} symbols, ${edgeCount} call edges in the graph.`);
+
+	const existingTags = db
+		.query("SELECT kind, value, node_id FROM tags ORDER BY kind, value")
+		.all() as { kind: string; value: string; node_id: string }[];
+
+	if (existingTags.length > 0) {
+		lines.push("");
+		lines.push("### Already Tagged");
+		lines.push("");
+		for (const tag of existingTags) {
+			lines.push(`- \`@lattice:${tag.kind} ${tag.value}\` on \`${tag.node_id}\``);
+		}
+		lines.push("");
+		lines.push("Review these existing tags and add any that are missing.");
+	} else {
+		lines.push("");
+		lines.push("No tags exist yet. Read the source files and add tags where appropriate.");
+	}
+
+	return lines.join("\n");
+}
+
+/** The complete step-by-step workflow with validation checkpoints. */
+function workflowSection(): string {
+	return `## Workflow
+
+Follow these steps in order. Do not skip validation steps.
+
+### Step 1: Tag entry points
+
+Read the source files and identify all entry points — route handlers, CLI commands, cron jobs, queue consumers, event listeners. Add \`@lattice:flow <name>\` above each one.
+
+Use domain names for flows: "checkout", "user-registration", "invoice-generation" — not function names.
+
+### Step 2: Tag boundaries
+
+Identify all functions that call external systems — APIs, databases, caches, file storage, third-party SDKs. Add \`@lattice:boundary <system>\` above each one.
+
+Use the external system name: "stripe", "postgres", "redis", "s3" — not the function or library name.
+
+### Step 3: Tag events
+
+If the codebase uses event-driven patterns, identify publishers and consumers. Add \`@lattice:emits <event>\` and \`@lattice:handles <event>\` where applicable. Event names must match between emitters and handlers.
+
+### Step 4: Rebuild and lint
+
+\`\`\`bash
+lattice build && lattice lint
+\`\`\`
+
+Fix any errors reported by lint:
+- Missing tags on detected entry points or boundary calls
+- Invalid tags (wrong placement, bad syntax)
+- Typos in tag names
+- Orphaned events (emits without handles, or vice versa)
+- Stale tags (boundary tag on a function that no longer calls that system)
+
+Repeat this step until lint reports zero errors.
+
+### Step 5: Verify flows
+
+Run \`lattice overview\` and check:
+- Are all business flows listed?
+- Are all external systems represented in boundaries?
+- Are all event connections shown?
+
+If anything is missing, go back to steps 1-3 and add the missing tags.
+
+### Step 6: Verify call trees
+
+For each flow listed in \`lattice overview\`, run:
+
+\`\`\`bash
+lattice flow <name>
+\`\`\`
+
+Check each call tree:
+- Does it start at the correct entry point?
+- Does it reach the expected boundaries?
+- Are there functions in the tree that should be boundaries but aren't tagged?
+- Does event propagation cross into the expected handlers?
+
+If a call tree is missing expected functions, those functions may not be reachable from the entry point through the call graph. Check if there are missing call edges (dynamic dispatch, dependency injection) and consider whether additional tags are needed.
+
+### Step 7: Verify impact
+
+For each boundary, run:
+
+\`\`\`bash
+lattice impact <symbol>
+\`\`\`
+
+Check that the affected flows make sense. If a boundary is used by flows you didn't expect, investigate whether the flow tagging is correct.
+
+### Done
+
+The codebase is tagged when:
+- \`lattice lint\` reports zero errors
+- \`lattice overview\` shows all expected flows, boundaries, and events
+- Each \`lattice flow <name>\` shows a complete, sensible call tree
+- \`lattice impact\` on key functions shows the expected affected flows`;
+}
+
+export { executePopulate };