lattice-graph 0.1.0 → 0.3.0

package/src/extract/python/calls.ts

@@ -1,121 +0,0 @@
-import type { TreeSitterNode, TreeSitterTree } from "../parser.ts";
-
-/** A raw call detected in the AST before resolution to graph edges. */
-type RawCall = {
-	readonly sourceId: string;
-	readonly callee: string;
-	readonly line: number;
-};
-
-/**
- * Extracts function calls from a Python AST.
- * Each call is scoped to its enclosing function or method.
- *
- * @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 extractPythonCalls(tree: TreeSitterTree, filePath: string): readonly RawCall[] {
-	const calls: RawCall[] = [];
-	visitForCalls(tree.rootNode, filePath, [], calls);
-	return calls;
-}
-
-/** Scope entry for tracking the enclosing function/class context. */
-type ScopeEntry = { readonly name: string };
-
-/**
- * Recursively walks the AST to find call expressions inside function bodies.
- * Tracks the enclosing function scope to produce correct source IDs.
- */
-function visitForCalls(
-	node: TreeSitterNode,
-	filePath: string,
-	scopeStack: readonly ScopeEntry[],
-	results: RawCall[],
-): void {
-	// Enter a new scope for function/class definitions
-	if (node.type === "function_definition" || node.type === "class_definition") {
-		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;
-		}
-	}
-
-	// Handle decorated definitions — unwrap to the inner definition
-	if (node.type === "decorated_definition") {
-		for (const child of node.children) {
-			if (child.type === "function_definition" || child.type === "class_definition") {
-				visitForCalls(child, filePath, scopeStack, results);
-			}
-		}
-		return;
-	}
-
-	// Detect call expressions inside a function scope
-	if (node.type === "call" && 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,
-			});
-		}
-	}
-
-	// Recurse into children
-	for (const child of node.children) {
-		visitForCalls(child, filePath, scopeStack, results);
-	}
-}
-
-/**
- * Extracts the callee name from a call node.
- * Handles: simple calls (foo()), attribute calls (obj.method()), chained calls (a.b.c()).
- */
-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 === "attribute") {
-		return flattenAttribute(funcNode);
-	}
-
-	return undefined;
-}
-
-/**
- * Flattens a nested attribute access into a dotted string.
- * e.g., attribute(attribute(identifier("stripe"), "charges"), "create") → "stripe.charges.create"
- */
-function flattenAttribute(node: TreeSitterNode): string {
-	const parts: string[] = [];
-	let current: TreeSitterNode | null = node;
-
-	while (current?.type === "attribute") {
-		const attrName = current.children.at(-1);
-		if (attrName?.type === "identifier") {
-			parts.unshift(attrName.text);
-		}
-		current = current.children[0] ?? null;
-	}
-
-	// The leftmost part is an identifier
-	if (current?.type === "identifier") {
-		parts.unshift(current.text);
-	}
-
-	return parts.join(".");
-}
-
-export { extractPythonCalls, type RawCall };

package/src/extract/python/extractor.ts

@@ -1,171 +0,0 @@
-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 { extractPythonCalls } from "./calls.ts";
-import { detectPythonFrameworks } from "./frameworks.ts";
-import { extractPythonSymbols } from "./symbols.ts";
-
-/**
- * Creates a Python extractor with an initialized tree-sitter parser.
- * Must be called after initTreeSitter().
- *
- * @returns An Extractor configured for Python source files
- */
-async function createPythonExtractor(): Promise<Extractor> {
-	const parser = await createParser("python");
-
-	return {
-		language: "python",
-		fileExtensions: [".py"],
-		extract: (filePath: string, source: string): Promise<ExtractionResult> =>
-			extractPython(parser, filePath, source),
-	};
-}
-
-/**
- * Extracts symbols, calls, imports, tags, and framework metadata from a Python file.
- *
- * @param parser - Initialized tree-sitter parser for Python
- * @param filePath - Relative file path for node ID construction
- * @param source - Raw source code
- * @returns Complete extraction result with nodes, edges, tags, and unresolved references
- */
-async function extractPython(
-	parser: TreeSitterParser,
-	filePath: string,
-	source: string,
-): Promise<ExtractionResult> {
-	if (!source.trim()) {
-		return { nodes: [], edges: [], tags: [], unresolved: [] };
-	}
-
-	const tree = parser.parse(source);
-
-	// 1. Extract symbols (functions, classes, methods)
-	const nodes = [...extractPythonSymbols(tree, filePath, source)];
-
-	// 2. Extract calls and convert to edges
-	const rawCalls = extractPythonCalls(tree, filePath);
-	const edges: Edge[] = [];
-	const nodeIds = new Set(nodes.map((n) => n.id));
-
-	for (const call of rawCalls) {
-		// Try to resolve the callee to a known node in this file
-		const targetId = resolveCalleeInFile(call.callee, filePath, nodeIds);
-		if (targetId) {
-			edges.push({
-				sourceId: call.sourceId,
-				targetId,
-				kind: "calls",
-				certainty: "certain",
-			});
-		} else {
-			// The callee is external or unresolvable within this file.
-			// Store as an edge with the raw callee expression as target.
-			// Cross-file resolution happens in the build command.
-			edges.push({
-				sourceId: call.sourceId,
-				targetId: call.callee,
-				kind: "calls",
-				certainty: "uncertain",
-			});
-		}
-	}
-
-	// 3. Parse lattice tags from comments above functions
-	const tags = extractTagsFromSource(source, filePath, nodes);
-
-	// 4. Detect framework patterns and attach route metadata to nodes
-	const frameworks = detectPythonFrameworks(tree, filePath);
-	for (const detection of frameworks) {
-		if (detection.route) {
-			const node = nodes.find((n) => n.name === detection.functionName);
-			if (node) {
-				const idx = nodes.indexOf(node);
-				nodes[idx] = {
-					...node,
-					metadata: { ...node.metadata, route: detection.route },
-				};
-			}
-		}
-	}
-
-	return { nodes, edges, tags, unresolved: [] };
-}
-
-/**
- * Resolves a callee name to a node ID within the same file.
- * Handles simple names (bar → filePath::bar) and self.method references.
- */
-function resolveCalleeInFile(
-	callee: string,
-	filePath: string,
-	nodeIds: Set<string>,
-): string | undefined {
-	// Direct match: callee is a function name in this file
-	const directId = `${filePath}::${callee}`;
-	if (nodeIds.has(directId)) return directId;
-
-	// self.method → try ClassName.method for each class in this file
-	if (callee.startsWith("self.")) {
-		const methodName = callee.slice(5);
-		for (const id of nodeIds) {
-			if (id.endsWith(`.${methodName}`) && id.startsWith(`${filePath}::`)) {
-				return id;
-			}
-		}
-	}
-
-	return undefined;
-}
-
-/**
- * Extracts lattice tags by finding comment blocks directly above function definitions.
- * Associates each parsed tag with the node ID of the function below it.
- */
-function extractTagsFromSource(
-	source: string,
-	_filePath: string,
-	nodes: readonly { readonly id: string; readonly lineStart: number }[],
-): readonly Tag[] {
-	const lines = source.split("\n");
-	const tags: Tag[] = [];
-
-	for (const node of nodes) {
-		// Collect comment lines directly above the function (no blank lines between)
-		const commentLines: string[] = [];
-		let lineIdx = node.lineStart - 2; // lineStart is 1-based, array is 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("@")) {
-				// Skip decorators — they're between the tags and the function
-				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 { createPythonExtractor };

package/src/extract/python/frameworks.ts

@@ -1,142 +0,0 @@
-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

@@ -1,115 +0,0 @@
-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

@@ -1,121 +0,0 @@
-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 };