lattice-graph 0.1.0

package/src/extract/python/frameworks.ts

@@ -0,0 +1,142 @@
+import type { TreeSitterNode, TreeSitterTree } from "../parser.ts";
+
+/** A detected framework pattern on a function. */
+type FrameworkDetection = {
+	readonly functionName: string;
+	readonly route: string | undefined;
+	readonly isEntryPoint: boolean;
+	readonly line: number;
+};
+
+/** HTTP methods recognized in route decorators. */
+const HTTP_METHODS = new Set(["get", "post", "put", "delete", "patch", "head", "options"]);
+
+/**
+ * Detects framework patterns (FastAPI, Flask, Celery) on decorated functions.
+ * Used by the linter to flag untagged entry points and by populate to suggest tags.
+ *
+ * @param tree - Parsed tree-sitter tree
+ * @param _filePath - Relative file path (unused, kept for interface consistency)
+ * @returns Detected framework patterns with route info and entry point flags
+ */
+function detectPythonFrameworks(
+	tree: TreeSitterTree,
+	_filePath: string,
+): readonly FrameworkDetection[] {
+	const results: FrameworkDetection[] = [];
+
+	for (const child of tree.rootNode.children) {
+		if (child.type === "decorated_definition") {
+			processDecoratedDefinition(child, results);
+		}
+	}
+
+	return results;
+}
+
+/** Processes a decorated_definition node to check for framework patterns. */
+function processDecoratedDefinition(node: TreeSitterNode, results: FrameworkDetection[]): void {
+	const funcDef = node.children.find((c) => c.type === "function_definition");
+	if (!funcDef) return;
+
+	const funcName = funcDef.childForFieldName("name")?.text;
+	if (!funcName) return;
+
+	const decorators = node.children.filter((c) => c.type === "decorator");
+
+	for (const decorator of decorators) {
+		const detection = analyzeDecorator(decorator, funcName, node.startPosition.row + 1);
+		if (detection) {
+			results.push(detection);
+		}
+	}
+}
+
+/**
+ * Analyzes a single decorator to determine if it matches a framework pattern.
+ * Recognizes: @app.get("/path"), @router.post("/path"), @app.route("/path"),
+ * @bp.route("/path"), @app.task, @shared_task
+ */
+function analyzeDecorator(
+	decorator: TreeSitterNode,
+	funcName: string,
+	line: number,
+): FrameworkDetection | undefined {
+	// The decorator's child after '@' is either a call or an attribute/identifier
+	const content = decorator.children.find(
+		(c) => c.type === "call" || c.type === "attribute" || c.type === "identifier",
+	);
+	if (!content) return undefined;
+
+	// Case 1: @shared_task (bare identifier)
+	if (content.type === "identifier" && content.text === "shared_task") {
+		return { functionName: funcName, route: undefined, isEntryPoint: true, line };
+	}
+
+	// Case 2: @app.task (bare attribute, no call)
+	if (content.type === "attribute") {
+		const attrName = content.children.at(-1)?.text;
+		if (attrName === "task") {
+			return { functionName: funcName, route: undefined, isEntryPoint: true, line };
+		}
+	}
+
+	// Case 3: @app.get("/path") or @router.post("/path") or @app.route("/path") — a call
+	if (content.type === "call") {
+		return analyzeDecoratorCall(content, funcName, line);
+	}
+
+	return undefined;
+}
+
+/** Analyzes a decorator that is a function call, e.g., @app.post("/api/checkout"). */
+function analyzeDecoratorCall(
+	callNode: TreeSitterNode,
+	funcName: string,
+	line: number,
+): FrameworkDetection | undefined {
+	const callee = callNode.children[0];
+	if (!callee || callee.type !== "attribute") return undefined;
+
+	const methodName = callee.children.at(-1)?.text;
+	if (!methodName) return undefined;
+
+	const args = callNode.children.find((c) => c.type === "argument_list");
+	const firstArg = args?.children.find((c) => c.type === "string");
+	const routePath = firstArg ? extractStringContent(firstArg) : undefined;
+
+	// @app.get("/path"), @router.post("/path"), etc.
+	if (HTTP_METHODS.has(methodName) && routePath) {
+		return {
+			functionName: funcName,
+			route: `${methodName.toUpperCase()} ${routePath}`,
+			isEntryPoint: true,
+			line,
+		};
+	}
+
+	// @app.route("/path") or @bp.route("/path")
+	if (methodName === "route" && routePath) {
+		return {
+			functionName: funcName,
+			route: routePath,
+			isEntryPoint: true,
+			line,
+		};
+	}
+
+	// @app.task() with parentheses
+	if (methodName === "task") {
+		return { functionName: funcName, route: undefined, isEntryPoint: true, line };
+	}
+
+	return undefined;
+}
+
+/** Extracts the string content from a tree-sitter string node, stripping quotes. */
+function extractStringContent(stringNode: TreeSitterNode): string | undefined {
+	const contentNode = stringNode.children.find((c) => c.type === "string_content");
+	return contentNode?.text;
+}
+
+export { detectPythonFrameworks, type FrameworkDetection };

package/src/extract/python/imports.ts

@@ -0,0 +1,115 @@
+import type { TreeSitterNode, TreeSitterTree } from "../parser.ts";
+
+/** A parsed import statement from Python source. */
+type PythonImport = {
+	readonly module: string;
+	readonly names: readonly string[];
+	readonly isRelative: boolean;
+	readonly aliases: Map<string, string> | undefined;
+	readonly line: number;
+};
+
+/**
+ * Extracts import statements from a Python AST.
+ *
+ * @param tree - Parsed tree-sitter tree
+ * @param _filePath - Relative file path (unused, kept for interface consistency)
+ * @returns Parsed imports with module paths, imported names, and alias mappings
+ */
+function extractPythonImports(tree: TreeSitterTree, _filePath: string): readonly PythonImport[] {
+	const imports: PythonImport[] = [];
+
+	for (const child of tree.rootNode.children) {
+		if (child.type === "import_statement") {
+			parseImportStatement(child, imports);
+		} else if (child.type === "import_from_statement") {
+			parseImportFromStatement(child, imports);
+		}
+	}
+
+	return imports;
+}
+
+/** Parses `import x` or `import x as y` statements. */
+function parseImportStatement(node: TreeSitterNode, results: PythonImport[]): void {
+	for (const child of node.children) {
+		if (child.type === "dotted_name") {
+			results.push({
+				module: child.text,
+				names: [],
+				isRelative: false,
+				aliases: undefined,
+				line: node.startPosition.row + 1,
+			});
+		} else if (child.type === "aliased_import") {
+			const moduleName = extractDottedName(child);
+			const alias = extractAlias(child);
+			const aliases = alias ? new Map([[moduleName, alias]]) : undefined;
+			results.push({
+				module: moduleName,
+				names: [],
+				isRelative: false,
+				aliases,
+				line: node.startPosition.row + 1,
+			});
+		}
+	}
+}
+
+/** Parses `from x import y` or `from .x import y as z` statements. */
+function parseImportFromStatement(node: TreeSitterNode, results: PythonImport[]): void {
+	let module = "";
+	let isRelative = false;
+	const names: string[] = [];
+	const aliases = new Map<string, string>();
+
+	for (const child of node.children) {
+		if (child.type === "dotted_name" && !module) {
+			module = child.text;
+		} else if (child.type === "relative_import") {
+			isRelative = true;
+			const prefix = child.children.find((c) => c.type === "import_prefix");
+			const dottedName = child.children.find((c) => c.type === "dotted_name");
+			const dots = prefix?.text ?? ".";
+			module = dottedName ? `${dots}${dottedName.text}` : dots;
+		} else if (child.type === "dotted_name" && module) {
+			names.push(child.text);
+		} else if (child.type === "aliased_import") {
+			const name = extractDottedName(child);
+			names.push(name);
+			const alias = extractAlias(child);
+			if (alias) {
+				aliases.set(name, alias);
+			}
+		}
+	}
+
+	results.push({
+		module,
+		names,
+		isRelative,
+		aliases: aliases.size > 0 ? aliases : undefined,
+		line: node.startPosition.row + 1,
+	});
+}
+
+/** Extracts the dotted name from an aliased_import node. */
+function extractDottedName(aliasedNode: TreeSitterNode): string {
+	const dottedName = aliasedNode.children.find((c) => c.type === "dotted_name");
+	return dottedName?.text ?? "";
+}
+
+/** Extracts the alias identifier from an aliased_import node. */
+function extractAlias(aliasedNode: TreeSitterNode): string | undefined {
+	const children = aliasedNode.children;
+	const asIdx = children.findIndex((c) => c.type === "as");
+	if (asIdx >= 0) {
+		const aliasNode = children[asIdx + 1];
+		if (aliasNode?.type === "identifier") {
+			return aliasNode.text;
+		}
+	}
+	return undefined;
+}
+
+export { extractPythonImports, type PythonImport };

package/src/extract/python/symbols.ts

@@ -0,0 +1,121 @@
+import type { Node, NodeKind } from "../../types/graph.ts";
+import type { TreeSitterNode, TreeSitterTree } from "../parser.ts";
+
+/** Scope entry tracking the name and whether it's a class scope. */
+type ScopeEntry = { readonly name: string; readonly isClass: boolean };
+
+/**
+ * Extracts symbols (functions, classes, methods) from a Python AST.
+ *
+ * @param tree - Parsed tree-sitter tree
+ * @param filePath - Relative file path for node ID construction
+ * @param _source - Original source text (unused but kept for interface consistency)
+ * @returns Extracted nodes with deterministic IDs
+ */
+function extractPythonSymbols(
+	tree: TreeSitterTree,
+	filePath: string,
+	_source: string,
+): readonly Node[] {
+	const nodes: Node[] = [];
+	visitNode(tree.rootNode, filePath, [], nodes);
+	return nodes;
+}
+
+/**
+ * Recursively visits AST nodes to extract symbols.
+ * Tracks parent scope for generating nested IDs (e.g., Class.method, outer.inner).
+ */
+function visitNode(
+	node: TreeSitterNode,
+	filePath: string,
+	scopeStack: readonly ScopeEntry[],
+	results: Node[],
+): void {
+	if (node.type === "decorated_definition") {
+		// Decorated definitions wrap a function/class. Find the inner definition
+		// and use the decorated_definition's line range (includes decorators).
+		const inner = node.children.find(
+			(c) => c.type === "function_definition" || c.type === "class_definition",
+		);
+		if (inner) {
+			extractDefinition(inner, filePath, scopeStack, results, node);
+		}
+	} else if (node.type === "function_definition" || node.type === "class_definition") {
+		extractDefinition(node, filePath, scopeStack, results, undefined);
+	} else {
+		for (const child of node.children) {
+			visitNode(child, filePath, scopeStack, results);
+		}
+	}
+}
+
+/**
+ * Extracts a function or class definition into a Node and recurses into its body.
+ * If a decorated parent is provided, uses its line range to include decorator lines.
+ */
+function extractDefinition(
+	node: TreeSitterNode,
+	filePath: string,
+	scopeStack: readonly ScopeEntry[],
+	results: Node[],
+	decoratedParent: TreeSitterNode | undefined,
+): void {
+	const nameNode = node.childForFieldName("name");
+	if (!nameNode) return;
+
+	const name = nameNode.text;
+	const isClass = node.type === "class_definition";
+	const kind = resolveKind(isClass, scopeStack);
+	const qualifiedName = [...scopeStack.map((s) => s.name), name].join(".");
+	const id = `${filePath}::${qualifiedName}`;
+
+	const signature = kind !== "class" ? buildSignature(node, name) : undefined;
+
+	// Use the decorated parent's line range if it exists (includes decorator lines)
+	const rangeNode = decoratedParent ?? node;
+
+	results.push({
+		id,
+		kind,
+		name,
+		file: filePath,
+		lineStart: rangeNode.startPosition.row + 1,
+		lineEnd: rangeNode.endPosition.row + 1,
+		language: "python",
+		signature,
+		isTest: false,
+		metadata: undefined,
+	});
+
+	// Recurse into children with updated scope
+	const newScope: readonly ScopeEntry[] = [...scopeStack, { name, isClass }];
+	for (const child of node.children) {
+		visitNode(child, filePath, newScope, results);
+	}
+}
+
+/** Determines the node kind based on whether this is a class or function, and the parent scope. */
+function resolveKind(isClass: boolean, scopeStack: readonly ScopeEntry[]): NodeKind {
+	if (isClass) return "class";
+	// A function directly inside a class is a method
+	const parentScope = scopeStack.at(-1);
+	if (parentScope?.isClass) return "method";
+	return "function";
+}
+
+/**
+ * Builds a human-readable signature from a function definition node.
+ * Includes parameter names with type annotations and return type.
+ */
+function buildSignature(node: TreeSitterNode, name: string): string {
+	const paramsNode = node.childForFieldName("parameters");
+	const returnTypeNode = node.childForFieldName("return_type");
+
+	const params = paramsNode ? paramsNode.text : "()";
+	const returnType = returnTypeNode ? ` -> ${returnTypeNode.text}` : "";
+
+	return `${name}${params}${returnType}`;
+}
+
+export { extractPythonSymbols };

package/src/extract/tags.ts

@@ -0,0 +1,77 @@
+import type { TagKind } from "../types/graph.ts";
+import { err, ok, type Result } from "../types/result.ts";
+
+/** A parsed tag before it's associated with a specific node ID. */
+type ParsedTag = {
+	readonly kind: TagKind;
+	readonly value: string;
+};
+
+const VALID_TAG_KINDS = new Set<string>(["flow", "boundary", "emits", "handles"]);
+
+/** Matches @lattice:<kind> <value> at the START of a stripped comment line. */
+const TAG_PATTERN = /^@lattice:(\w+)\s+(.+)/;
+
+/** Valid tag name: lowercase letters, numbers, hyphens, dots. Must start with a letter or number. */
+const NAME_PATTERN = /^[a-z0-9][a-z0-9\-.]*$/;
+
+/** Strips common comment prefixes from a line. */
+function stripCommentPrefix(line: string): string {
+	const trimmed = line.trim();
+	// Try each prefix in order
+	if (trimmed.startsWith("//")) return trimmed.slice(2).trim();
+	if (trimmed.startsWith("#")) return trimmed.slice(1).trim();
+	if (trimmed.startsWith("--")) return trimmed.slice(2).trim();
+	if (trimmed.startsWith("/*"))
+		return trimmed
+			.slice(2)
+			.replace(/\*\/\s*$/, "")
+			.trim();
+	return trimmed;
+}
+
+/**
+ * Parses lattice tags from a comment block.
+ * Recognizes any comment style: #, //, /∗ ∗/, --.
+ * Returns parsed tags or an error for invalid tag name syntax.
+ *
+ * @param commentBlock - Raw comment text, possibly multiline
+ * @returns Parsed tags or an error message
+ */
+function parseTags(commentBlock: string): Result<readonly ParsedTag[], string> {
+	if (!commentBlock.trim()) return ok([]);
+
+	const tags: ParsedTag[] = [];
+	const lines = commentBlock.split("\n");
+
+	for (const line of lines) {
+		const stripped = stripCommentPrefix(line);
+		const match = TAG_PATTERN.exec(stripped);
+		if (!match) continue;
+
+		const kindStr = match[1];
+		const valuesStr = match[2];
+		if (!kindStr || !valuesStr) continue;
+
+		if (!VALID_TAG_KINDS.has(kindStr)) continue;
+
+		const kind = kindStr as TagKind;
+		const rawValues = valuesStr.split(",").map((v) => v.trim());
+
+		for (const value of rawValues) {
+			if (!value) continue;
+
+			if (!NAME_PATTERN.test(value)) {
+				return err(
+					`Invalid tag name "${value}": must be kebab-case (lowercase letters, numbers, hyphens, dots)`,
+				);
+			}
+
+			tags.push({ kind, value });
+		}
+	}
+
+	return ok(tags);
+}
+
+export { type ParsedTag, parseTags };

package/src/extract/typescript/calls.ts

@@ -0,0 +1,110 @@
+import type { TreeSitterNode, TreeSitterTree } from "../parser.ts";
+
+/** A raw call detected in the TypeScript AST. */
+type RawCall = {
+	readonly sourceId: string;
+	readonly callee: string;
+	readonly line: number;
+};
+
+/**
+ * Extracts function calls from a TypeScript AST.
+ * Each call is scoped to its enclosing function, method, or arrow function.
+ *
+ * @param tree - Parsed tree-sitter tree
+ * @param filePath - Relative file path for source ID construction
+ * @returns Raw calls with caller ID and callee expression
+ */
+function extractTypeScriptCalls(tree: TreeSitterTree, filePath: string): readonly RawCall[] {
+	const calls: RawCall[] = [];
+	visitForCalls(tree.rootNode, filePath, [], calls);
+	return calls;
+}
+
+type ScopeEntry = { readonly name: string };
+
+/** Recursively walks the AST finding call_expression nodes inside functions. */
+function visitForCalls(
+	node: TreeSitterNode,
+	filePath: string,
+	scopeStack: readonly ScopeEntry[],
+	results: RawCall[],
+): void {
+	// Enter new scope for function/method/class declarations
+	if (
+		node.type === "function_declaration" ||
+		node.type === "method_definition" ||
+		node.type === "class_declaration"
+	) {
+		const nameNode = node.childForFieldName("name");
+		if (nameNode) {
+			const newScope = [...scopeStack, { name: nameNode.text }];
+			for (const child of node.children) {
+				visitForCalls(child, filePath, newScope, results);
+			}
+			return;
+		}
+	}
+
+	// Arrow function assigned to const
+	if (node.type === "variable_declarator") {
+		const nameNode = node.childForFieldName("name");
+		const valueNode = node.childForFieldName("value");
+		if (nameNode && valueNode?.type === "arrow_function") {
+			const newScope = [...scopeStack, { name: nameNode.text }];
+			for (const child of valueNode.children) {
+				visitForCalls(child, filePath, newScope, results);
+			}
+			return;
+		}
+	}
+
+	// Export statement — unwrap
+	if (node.type === "export_statement") {
+		for (const child of node.children) {
+			visitForCalls(child, filePath, scopeStack, results);
+		}
+		return;
+	}
+
+	// Detect call expressions inside a function scope
+	if (node.type === "call_expression" && scopeStack.length > 0) {
+		const callee = extractCalleeName(node);
+		if (callee) {
+			const sourceId = `${filePath}::${scopeStack.map((s) => s.name).join(".")}`;
+			results.push({ sourceId, callee, line: node.startPosition.row + 1 });
+		}
+	}
+
+	for (const child of node.children) {
+		visitForCalls(child, filePath, scopeStack, results);
+	}
+}
+
+/** Extracts the callee name from a call_expression node. */
+function extractCalleeName(callNode: TreeSitterNode): string | undefined {
+	const funcNode = callNode.children[0];
+	if (!funcNode) return undefined;
+	if (funcNode.type === "identifier") return funcNode.text;
+	if (funcNode.type === "member_expression") return flattenMemberExpression(funcNode);
+	return undefined;
+}
+
+/** Flattens a.b.c member expression into "a.b.c". */
+function flattenMemberExpression(node: TreeSitterNode): string {
+	const parts: string[] = [];
+	let current: TreeSitterNode | null = node;
+
+	while (current?.type === "member_expression") {
+		const prop = current.children.find((c) => c.type === "property_identifier");
+		if (prop) parts.unshift(prop.text);
+		current = current.children[0] ?? null;
+	}
+
+	if (current?.type === "identifier") parts.unshift(current.text);
+	if (current?.type === "this") parts.unshift("this");
+
+	return parts.join(".");
+}
+
+export { extractTypeScriptCalls, type RawCall };

package/src/extract/typescript/extractor.ts

@@ -0,0 +1,130 @@
+import type { Edge, ExtractionResult, Tag } from "../../types/graph.ts";
+import { isOk, unwrap } from "../../types/result.ts";
+import type { Extractor } from "../extractor.ts";
+import { createParser, type TreeSitterParser } from "../parser.ts";
+import { parseTags } from "../tags.ts";
+import { extractTypeScriptCalls } from "./calls.ts";
+import { extractTypeScriptSymbols } from "./symbols.ts";
+
+/**
+ * Creates a TypeScript extractor with an initialized tree-sitter parser.
+ * Must be called after initTreeSitter().
+ *
+ * @returns An Extractor configured for TypeScript source files
+ */
+async function createTypeScriptExtractor(): Promise<Extractor> {
+	const parser = await createParser("typescript");
+
+	return {
+		language: "typescript",
+		fileExtensions: [".ts", ".tsx"],
+		extract: (filePath: string, source: string): Promise<ExtractionResult> =>
+			extractTypeScript(parser, filePath, source),
+	};
+}
+
+/**
+ * Extracts symbols, calls, and tags from a TypeScript file.
+ *
+ * @param parser - Initialized tree-sitter parser for TypeScript
+ * @param filePath - Relative file path
+ * @param source - Raw source code
+ * @returns Complete extraction result
+ */
+async function extractTypeScript(
+	parser: TreeSitterParser,
+	filePath: string,
+	source: string,
+): Promise<ExtractionResult> {
+	if (!source.trim()) {
+		return { nodes: [], edges: [], tags: [], unresolved: [] };
+	}
+
+	const tree = parser.parse(source);
+
+	// 1. Extract symbols
+	const nodes = [...extractTypeScriptSymbols(tree, filePath, source)];
+
+	// 2. Extract calls and convert to edges
+	const rawCalls = extractTypeScriptCalls(tree, filePath);
+	const edges: Edge[] = [];
+	const nodeIds = new Set(nodes.map((n) => n.id));
+
+	for (const call of rawCalls) {
+		const targetId = resolveCalleeInFile(call.callee, filePath, nodeIds);
+		if (targetId) {
+			edges.push({ sourceId: call.sourceId, targetId, kind: "calls", certainty: "certain" });
+		} else {
+			edges.push({
+				sourceId: call.sourceId,
+				targetId: call.callee,
+				kind: "calls",
+				certainty: "uncertain",
+			});
+		}
+	}
+
+	// 3. Parse lattice tags from comments above functions
+	const tags = extractTagsFromSource(source, nodes);
+
+	return { nodes, edges, tags, unresolved: [] };
+}
+
+/** Resolves a callee name to a node ID within the same file. */
+function resolveCalleeInFile(
+	callee: string,
+	filePath: string,
+	nodeIds: Set<string>,
+): string | undefined {
+	const directId = `${filePath}::${callee}`;
+	if (nodeIds.has(directId)) return directId;
+
+	// this.method → try ClassName.method
+	if (callee.startsWith("this.")) {
+		const methodName = callee.slice(5);
+		for (const id of nodeIds) {
+			if (id.endsWith(`.${methodName}`) && id.startsWith(`${filePath}::`)) return id;
+		}
+	}
+
+	return undefined;
+}
+
+/** Extracts lattice tags from comment blocks above functions. */
+function extractTagsFromSource(
+	source: string,
+	nodes: readonly { readonly id: string; readonly lineStart: number }[],
+): readonly Tag[] {
+	const lines = source.split("\n");
+	const tags: Tag[] = [];
+
+	for (const node of nodes) {
+		const commentLines: string[] = [];
+		let lineIdx = node.lineStart - 2; // 1-based to 0-based
+		while (lineIdx >= 0) {
+			const line = lines[lineIdx]?.trim();
+			if (!line) break;
+			if (line.startsWith("//") || line.startsWith("/*") || line.startsWith("*")) {
+				commentLines.unshift(line);
+				lineIdx--;
+			} else if (line.startsWith("@")) {
+				lineIdx--;
+			} else {
+				break;
+			}
+		}
+
+		if (commentLines.length === 0) continue;
+
+		const parseResult = parseTags(commentLines.join("\n"));
+		if (isOk(parseResult)) {
+			for (const parsed of unwrap(parseResult)) {
+				tags.push({ nodeId: node.id, kind: parsed.kind, value: parsed.value });
+			}
+		}
+	}
+
+	return tags;
+}
+
+export { createTypeScriptExtractor };