lattice-graph 0.1.0 → 0.2.0

package/src/commands/lint.ts

@@ -7,45 +7,24 @@ import type { LintIssue, LintResult } from "../types/lint.ts";
  * 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
+ * @param config - Lattice configuration
+ * @returns Lint result with issues and coverage
  */
 // @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);
+	checkMissingBoundaryTags(db, issues);
+	checkDeadEndFlows(db, issues);
+	checkDisconnectedFunctions(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`,
-		});
-	}
+	return { issues, coverage };
 }
 
 /** Checks for tags placed on invalid node kinds (e.g., flow tag on a class). */
@@ -79,7 +58,6 @@ function checkInvalidTags(db: Database, issues: LintIssue[]): void {
 
 /** 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 }[];
@@ -88,8 +66,15 @@ function checkTypos(db: Database, issues: LintIssue[]): void {
 	const commons = tagCounts.filter((t) => t.cnt > 1);
 
 	for (const single of singletons) {
+		// Require longer names for typo detection — short names like "s3" and "sqs" are distinct
+		const minLength = 4;
+		if (single.value.length < minLength) continue;
+
 		const similar = commons.filter(
-			(c) => c.kind === single.kind && editDistance(single.value, c.value) <= 2,
+			(c) =>
+				c.kind === single.kind &&
+				c.value.length >= minLength &&
+				editDistance(single.value, c.value) <= 2,
 		);
 		if (similar.length > 0) {
 			const bestMatch = similar[0];
@@ -119,7 +104,6 @@ function checkTypos(db: Database, issues: LintIssue[]): void {
 
 /** 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
@@ -139,7 +123,6 @@ function checkOrphanedEvents(db: Database, issues: LintIssue[]): void {
 		});
 	}
 
-	// Handles with no matching emits
 	const orphanedHandles = db
 		.query(
 			`SELECT t.value, n.name, n.file, n.line_start FROM tags t
@@ -162,23 +145,31 @@ function checkOrphanedEvents(db: Database, issues: LintIssue[]): void {
 
 /**
  * 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).
+ * A boundary tag is stale if the function has no external calls recorded in the external_calls table.
  */
 function checkStaleBoundaryTags(db: Database, issues: LintIssue[]): void {
+	// Skip stale boundary check if no external call data is available
+	// (e.g., when the LSP server doesn't support outgoingCalls)
+	const hasAnyExternalCalls = db.query("SELECT 1 FROM external_calls LIMIT 1").get();
+	if (!hasAnyExternalCalls) return;
+
 	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 }[];
+		.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")
+			.query("SELECT 1 FROM external_calls WHERE node_id = ? LIMIT 1")
 			.get(tag.node_id);
 
 		if (!hasExternalCall) {
@@ -193,29 +184,131 @@ function checkStaleBoundaryTags(db: Database, issues: LintIssue[]): void {
 	}
 }
 
-/** Computes tag coverage: how many detected entry points are tagged vs total. */
-function computeCoverage(db: Database): { tagged: number; total: number } {
-	const total = db
+/**
+ * Checks for functions that call external packages but have no @lattice:boundary tag.
+ */
+function checkMissingBoundaryTags(db: Database, issues: LintIssue[]): void {
+	const rows = db
 		.query(
-			"SELECT COUNT(*) as c FROM nodes WHERE metadata IS NOT NULL AND metadata LIKE '%\"route\"%'",
+			`SELECT DISTINCT ec.node_id, ec.package, n.name, n.file, n.line_start
+			FROM external_calls ec
+			JOIN nodes n ON ec.node_id = n.id
+			WHERE NOT EXISTS (
+				SELECT 1 FROM tags t WHERE t.node_id = ec.node_id AND t.kind = 'boundary'
+			)`,
 		)
-		.get() as { c: number };
+		.all() as {
+		node_id: string;
+		package: string;
+		name: string;
+		file: string;
+		line_start: number;
+	}[];
 
-	const tagged = db
+	for (const row of rows) {
+		issues.push({
+			severity: "warning",
+			file: row.file,
+			line: row.line_start,
+			symbol: row.name,
+			message: `Function calls external package '${row.package}' but has no @lattice:boundary tag`,
+		});
+	}
+}
+
+/**
+ * Checks for flow entry points with zero callees — the flow tree is just the root node.
+ * This typically indicates dynamic dispatch, decorated functions, or missing event connections.
+ */
+function checkDeadEndFlows(db: Database, issues: LintIssue[]): void {
+	const flowEntries = 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')`,
+			`SELECT t.value AS flow_name, n.id, n.name, n.file, n.line_start
+			FROM tags t JOIN nodes n ON t.node_id = n.id
+			WHERE t.kind = 'flow'`,
 		)
-		.get() as { c: number };
+		.all() as {
+		flow_name: string;
+		id: string;
+		name: string;
+		file: string;
+		line_start: number;
+	}[];
+
+	for (const entry of flowEntries) {
+		const hasCallees = db
+			.query("SELECT 1 FROM edges WHERE source_id = ? AND kind IN ('calls', 'event') LIMIT 1")
+			.get(entry.id);
 
-	return { tagged: tagged.c, total: total.c };
+		if (!hasCallees) {
+			issues.push({
+				severity: "warning",
+				file: entry.file,
+				line: entry.line_start,
+				symbol: entry.name,
+				message: `Flow "${entry.flow_name}" entry point has no callees — the call tree may be incomplete. If this function dispatches through a queue or dynamic dispatch, add @lattice:emits/@lattice:handles tags.`,
+			});
+		}
+	}
 }
 
-/** 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;
+/**
+ * Checks for functions that have callees but are unreachable from any flow.
+ * These are likely worker handlers or event consumers that need flow/handles tags.
+ */
+function checkDisconnectedFunctions(db: Database, issues: LintIssue[]): void {
+	// Find functions with callees (they do work) that no flow can reach
+	const disconnected = db
+		.query(
+			`SELECT n.id, n.name, n.file, n.line_start,
+				(SELECT COUNT(*) FROM edges WHERE source_id = n.id AND kind IN ('calls', 'event')) as callee_count
+			FROM nodes n
+			WHERE n.kind IN ('function', 'method')
+			AND n.is_test = 0
+			AND NOT EXISTS (SELECT 1 FROM tags WHERE node_id = n.id)
+			AND EXISTS (SELECT 1 FROM edges WHERE source_id = n.id AND kind IN ('calls', 'event'))
+			AND NOT EXISTS (
+				WITH RECURSIVE flow_reachable AS (
+					SELECT node_id AS id FROM tags WHERE kind = 'flow'
+					UNION
+					SELECT e.target_id FROM edges e
+					JOIN flow_reachable fr ON e.source_id = fr.id
+					WHERE e.kind IN ('calls', 'event')
+				)
+				SELECT 1 FROM flow_reachable WHERE id = n.id
+			)`,
+		)
+		.all() as {
+		id: string;
+		name: string;
+		file: string;
+		line_start: number;
+		callee_count: number;
+	}[];
+
+	// Only report functions with 3+ callees to reduce noise
+	for (const fn of disconnected) {
+		if (fn.callee_count < 3) continue;
+		issues.push({
+			severity: "info",
+			file: fn.file,
+			line: fn.line_start,
+			symbol: fn.name,
+			message: `Function has ${fn.callee_count} callees but is unreachable from any flow. Consider adding @lattice:flow or @lattice:handles tag.`,
+		});
+	}
+}
+
+/** Computes tag coverage: how many tags exist vs total functions. */
+function computeCoverage(db: Database): { tagged: number; total: number } {
+	const total = (
+		db.query("SELECT COUNT(*) as c FROM nodes WHERE kind IN ('function', 'method')").get() as {
+			c: number;
+		}
+	).c;
+	const tagged = (db.query("SELECT COUNT(DISTINCT node_id) as c FROM tags").get() as { c: number })
+		.c;
+	return { tagged, total };
 }
 
 /**
@@ -226,7 +319,6 @@ 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);
 

package/src/commands/populate.ts

@@ -158,11 +158,22 @@ Identify all functions that call external systems — APIs, databases, caches, f
 
 Use the external system name: "stripe", "postgres", "redis", "s3" — not the function or library name.
 
-### Step 3: Tag events
+### Step 3: Tag async dispatch (queues, Lambda, Celery)
 
-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.
+If the codebase submits work to a queue (SQS, RabbitMQ), invokes Lambda functions, or dispatches Celery tasks, these create invisible connections between the submitter and the handler. Tag both sides:
 
-### Step 4: Rebuild and lint
+- Add \`@lattice:emits job.<name>\` on the function that submits/invokes the async work
+- Add \`@lattice:handles job.<name>\` on the function that processes the work on the other side
+
+Important: Worker handlers and Lambda consumers are NOT separate flows — they are the receiving side of an async dispatch. Tag them with \`@lattice:handles\`, not \`@lattice:flow\`.
+
+Place \`emits\` tags on the function the flow actually passes through, not on a concrete implementation behind a protocol or interface.
+
+### Step 4: Tag events
+
+If the codebase uses event-driven patterns (pub/sub, event bus, signals), identify publishers and consumers. Add \`@lattice:emits <event>\` and \`@lattice:handles <event>\` where applicable. Event names must match between emitters and handlers.
+
+### Step 5: Rebuild and lint
 
 \`\`\`bash
 lattice build && lattice lint

package/src/commands/update.ts

@@ -1,37 +1,26 @@
 import { Database } from "bun:sqlite";
 import { existsSync, statSync } from "node:fs";
-import { join, relative } from "node:path";
-import type { Extractor } from "../extract/extractor.ts";
-import { initTreeSitter } from "../extract/parser.ts";
-import { createPythonExtractor } from "../extract/python/extractor.ts";
-import { createTypeScriptExtractor } from "../extract/typescript/extractor.ts";
+import { join, resolve } from "node:path";
+import { discoverFiles } from "../files.ts";
 import { checkSchemaVersion } from "../graph/database.ts";
-import {
-	deleteFileData,
-	insertEdges,
-	insertNodes,
-	insertTags,
-	insertUnresolved,
-	synthesizeEventEdges,
-} from "../graph/writer.ts";
 import type { LatticeConfig } from "../types/config.ts";
-import type { ExtractionResult } from "../types/graph.ts";
-import { err, isOk, ok, type Result } from "../types/result.ts";
+import { isOk, ok, type Result } from "../types/result.ts";
+import { executeBuild } from "./build.ts";
 
 /** Statistics from an incremental update. */
 type UpdateStats = {
-	readonly totalFiles: number;
 	readonly filesReindexed: number;
+	readonly totalFiles: number;
 	readonly durationMs: number;
 };
 
 /**
- * Performs an incremental update of the knowledge graph.
- * Only re-indexes files that have changed since the last build.
- * Falls back to a full rebuild if >30% of files are dirty.
+ * Performs an incremental update: re-indexes only files changed since the last build.
+ * Falls back to a full rebuild if the database is missing, schema mismatches,
+ * or more than 30% of files have changed.
  *
- * @param projectRoot - Path to the project root
- * @param config - Lattice configuration
+ * @param projectRoot - Absolute path to the project root
+ * @param config - Parsed lattice.toml configuration
  * @returns Update statistics or an error message
  */
 // @lattice:flow update
@@ -39,137 +28,86 @@ async function executeUpdate(
 	projectRoot: string,
 	config: LatticeConfig,
 ): Promise<Result<UpdateStats, string>> {
-	const startTime = Date.now();
-	const dbPath = join(projectRoot, ".lattice", "graph.db");
+	const start = performance.now();
 
+	const dbPath = join(projectRoot, ".lattice", "graph.db");
 	if (!existsSync(dbPath)) {
-		return err("No existing graph found. Run 'lattice build' first.");
+		const buildResult = await executeBuild(projectRoot, config);
+		if (!isOk(buildResult)) return buildResult;
+		return ok({ filesReindexed: 0, totalFiles: 0, durationMs: 0 });
 	}
 
-	try {
-		const db = new Database(dbPath);
-		const schemaCheck = checkSchemaVersion(db);
-		if (!isOk(schemaCheck)) {
-			db.close();
-			return err(schemaCheck.error);
-		}
-
-		// Get last build time
-		const lastBuildRow = db.query("SELECT value FROM meta WHERE key = 'last_build'").get() as {
-			value: string;
-		} | null;
-		if (!lastBuildRow) {
-			db.close();
-			return err("No last_build timestamp found. Run 'lattice build' first.");
-		}
-		const lastBuild = new Date(lastBuildRow.value);
-
-		// Initialize extractors
-		await initTreeSitter();
-		const extractors = await createExtractors(config);
-		const extByExt = new Map<string, Extractor>();
-		for (const ext of extractors) {
-			for (const fileExt of ext.fileExtensions) {
-				extByExt.set(fileExt, ext);
-			}
-		}
-
-		// Scan all files, find changed ones
-		const sourceRoot = join(projectRoot, config.root);
-		const glob = new Bun.Glob("**/*");
-		const allFiles: string[] = [];
-		const changedFiles: string[] = [];
-
-		for await (const path of glob.scan({ cwd: sourceRoot, dot: false })) {
-			const ext = `.${path.split(".").pop()}`;
-			if (!extByExt.has(ext)) continue;
-			if (isExcluded(path, config.exclude)) continue;
-			allFiles.push(path);
-
-			const fullPath = join(sourceRoot, path);
-			const stat = statSync(fullPath);
-			if (stat.mtime > lastBuild) {
-				changedFiles.push(path);
-			}
-		}
-
-		// Fall back to full rebuild if >30% changed
-		if (changedFiles.length > allFiles.length * 0.3) {
-			db.close();
-			const { executeBuild } = await import("./build.ts");
-			return executeBuild(projectRoot, config).then((result) => {
-				if (isOk(result)) {
-					return ok({
-						totalFiles: allFiles.length,
-						filesReindexed: allFiles.length,
-						durationMs: Date.now() - startTime,
-					});
-				}
-				return err(result.error);
-			});
-		}
-
-		// Re-extract changed files
-		for (const file of changedFiles) {
-			const ext = `.${file.split(".").pop()}`;
-			const extractor = extByExt.get(ext);
-			if (!extractor) continue;
-
-			const fullPath = join(sourceRoot, file);
-			const source = await Bun.file(fullPath).text();
-			const relativePath = relative(projectRoot, fullPath);
+	const db = new Database(dbPath);
+	const schemaCheck = checkSchemaVersion(db);
+	if (!isOk(schemaCheck)) {
+		db.close();
+		const buildResult = await executeBuild(projectRoot, config);
+		if (!isOk(buildResult)) return buildResult;
+		return ok({ filesReindexed: 0, totalFiles: 0, durationMs: 0 });
+	}
 
-			// Delete old data for this file
-			deleteFileData(db, relativePath);
+	// Get last build timestamp
+	const metaRow = db.query("SELECT value FROM meta WHERE key = 'last_build'").get() as {
+		value: string;
+	} | null;
+	if (!metaRow) {
+		db.close();
+		const buildResult = await executeBuild(projectRoot, config);
+		if (!isOk(buildResult)) return buildResult;
+		return ok({ filesReindexed: 0, totalFiles: 0, durationMs: 0 });
+	}
+	const lastBuild = Number.parseInt(metaRow.value, 10);
+
+	// Discover files
+	const extensions = [".ts", ".tsx"];
+	const sourceRoots = config.typescript?.sourceRoots ?? [config.root];
+	const allFiles: string[] = [];
+	for (const srcRoot of sourceRoots) {
+		const absRoot = resolve(projectRoot, srcRoot);
+		allFiles.push(...discoverFiles(absRoot, extensions, config.exclude));
+	}
 
-			// Re-extract
-			const result: ExtractionResult = await extractor.extract(relativePath, source);
-			insertNodes(db, result.nodes);
-			insertEdges(db, result.edges);
-			insertTags(db, result.tags);
-			insertUnresolved(db, result.unresolved);
+	// Find changed files
+	const changedFiles = allFiles.filter((f) => {
+		try {
+			return statSync(f).mtimeMs > lastBuild;
+		} catch {
+			return true;
 		}
+	});
 
-		// Rebuild event edges
-		synthesizeEventEdges(db);
-
-		// Update timestamp
-		db.run("INSERT OR REPLACE INTO meta (key, value) VALUES ('last_build', ?)", [
-			new Date().toISOString(),
-		]);
-
+	if (changedFiles.length === 0) {
 		db.close();
-
 		return ok({
+			filesReindexed: 0,
 			totalFiles: allFiles.length,
-			filesReindexed: changedFiles.length,
-			durationMs: Date.now() - startTime,
+			durationMs: Math.round(performance.now() - start),
 		});
-	} catch (error) {
-		return err(`Update failed: ${error instanceof Error ? error.message : String(error)}`);
 	}
-}
 
-/** Creates extractors for configured languages. */
-async function createExtractors(config: LatticeConfig): Promise<readonly Extractor[]> {
-	const extractors: Extractor[] = [];
-	for (const lang of config.languages) {
-		if (lang === "python") {
-			extractors.push(await createPythonExtractor());
-		}
-		if (lang === "typescript") {
-			extractors.push(await createTypeScriptExtractor());
-		}
+	// Fall back to full rebuild if too many files changed
+	if (changedFiles.length > allFiles.length * 0.3) {
+		db.close();
+		const buildResult = await executeBuild(projectRoot, config);
+		if (!isOk(buildResult)) return buildResult;
+		return ok({
+			filesReindexed: changedFiles.length,
+			totalFiles: allFiles.length,
+			durationMs: Math.round(performance.now() - start),
+		});
 	}
-	return extractors;
-}
 
-/** Checks if a file path matches any exclude pattern. */
-function isExcluded(filePath: string, excludePatterns: readonly string[]): boolean {
-	for (const pattern of excludePatterns) {
-		if (filePath.includes(pattern.replace("**", "").replace("*", ""))) return true;
-	}
-	return false;
+	// Any changed files → full rebuild via executeBuild
+	// True incremental (per-file LSP re-extraction) is a future optimization
+	db.close();
+	const buildResult = await executeBuild(projectRoot, config);
+	if (!isOk(buildResult)) return buildResult;
+
+	return ok({
+		filesReindexed: changedFiles.length,
+		totalFiles: allFiles.length,
+		durationMs: Math.round(performance.now() - start),
+	});
 }
 
-export { executeUpdate, type UpdateStats };
+export { executeUpdate };

package/src/config.ts

@@ -56,7 +56,6 @@ function parsePythonSection(raw: unknown): PythonConfig {
 	return {
 		sourceRoots: isStringArray(section.source_roots) ? section.source_roots : ["."],
 		testPaths: isStringArray(section.test_paths) ? section.test_paths : ["tests"],
-		frameworks: isStringArray(section.frameworks) ? section.frameworks : [],
 	};
 }
 
@@ -67,7 +66,6 @@ function parseTypeScriptSection(raw: unknown): TypeScriptConfig {
 		sourceRoots: isStringArray(section.source_roots) ? section.source_roots : ["."],
 		testPaths: isStringArray(section.test_paths) ? section.test_paths : ["__tests__"],
 		tsconfig: typeof section.tsconfig === "string" ? section.tsconfig : undefined,
-		frameworks: isStringArray(section.frameworks) ? section.frameworks : [],
 	};
 }
 

package/src/extract/tag-scanner.ts

@@ -0,0 +1,94 @@
+import type { Node, Tag, TagKind } from "../types/graph.ts";
+import { TAG_KINDS } from "../types/graph.ts";
+
+const TAG_PATTERN = /^@lattice:(\S+)\s+(.+)/;
+const NAME_PATTERN = /^[a-z][a-z0-9._-]*$/;
+
+const COMMENT_PREFIXES: Record<string, RegExp> = {
+	typescript: /^\s*(?:\/\/|\/\*\*?|\*)\s*/,
+	python: /^\s*(?:#|""")\s*/,
+};
+const DEFAULT_COMMENT_PREFIX = /^\s*(?:\/\/|#|--|\/\*\*?|\*)\s*/;
+
+/** Result of scanning a file for @lattice: tags. */
+type TagScanResult = {
+	readonly tags: readonly Tag[];
+	readonly errors: readonly string[];
+};
+
+/**
+ * Scans source code for @lattice: tags and associates them with LSP-provided symbols.
+ * Validates tag syntax and names. Returns tags and any validation errors.
+ *
+ * @param source - File source code
+ * @param nodes - Nodes from LSP documentSymbol for this file
+ * @param language - Language identifier for comment prefix detection
+ * @returns Parsed tags and validation errors
+ */
+function scanTags(source: string, nodes: readonly Node[], language?: string): TagScanResult {
+	const lines = source.split("\n");
+	const tags: Tag[] = [];
+	const errors: string[] = [];
+	const commentPrefix =
+		(language ? COMMENT_PREFIXES[language] : undefined) ?? DEFAULT_COMMENT_PREFIX;
+
+	const candidateNodes = [...nodes]
+		.filter((n) => n.kind === "function" || n.kind === "method" || n.kind === "class")
+		.sort((a, b) => a.lineStart - b.lineStart);
+
+	for (let i = 0; i < lines.length; i++) {
+		const line = lines[i];
+		if (!line) continue;
+		const tagLine = i + 1;
+
+		// Only process lines that start with a comment prefix for this language
+		if (!commentPrefix.test(line)) continue;
+
+		// Skip tags that are inside a function body and point to the SAME function
+		// (these are @lattice: mentions in string literals, not real tags).
+		// Tags between functions (e.g., above a decorated function whose predecessor's
+		// range overlaps) are fine — the target will be a different, later function.
+		const containingNode = candidateNodes.find(
+			(n) => tagLine > n.lineStart && tagLine <= n.lineEnd,
+		);
+		// If the tag is inside a function and the next function IS that same function, skip it
+		const nextNode = candidateNodes.find((n) => n.lineStart >= tagLine);
+		if (containingNode && nextNode && containingNode.id === nextNode.id) continue;
+
+		const stripped = line.replace(commentPrefix, "");
+		const match = stripped.match(TAG_PATTERN);
+		if (!match) continue;
+
+		const kind = match[1] as string;
+		const rawValue = match[2] as string;
+
+		if (!TAG_KINDS.includes(kind as TagKind)) {
+			errors.push(`Line ${tagLine}: unknown tag kind '${kind}'`);
+			continue;
+		}
+
+		const values = rawValue
+			.split(",")
+			.map((v) => v.trim())
+			.filter(Boolean);
+
+		for (const value of values) {
+			if (!NAME_PATTERN.test(value)) {
+				errors.push(`Line ${tagLine}: invalid tag name '${value}' — must be lowercase kebab-case`);
+				continue;
+			}
+
+			const targetNode = candidateNodes.find((n) => n.lineStart >= tagLine);
+			if (!targetNode) {
+				errors.push(`Line ${tagLine}: @lattice:${kind} ${value} has no function below it`);
+				continue;
+			}
+
+			tags.push({ nodeId: targetNode.id, kind: kind as TagKind, value });
+		}
+	}
+
+	return { tags, errors };
+}
+
+export { scanTags, type TagScanResult };