lattice-graph 0.1.0 → 0.3.0

package/src/extract/tags.ts

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

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

@@ -1,130 +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 { 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 };

package/src/extract/typescript/imports.ts

@@ -1,71 +0,0 @@
-import type { TreeSitterNode, TreeSitterTree } from "../parser.ts";
-
-/** A parsed import statement from TypeScript source. */
-type TypeScriptImport = {
-	readonly module: string;
-	readonly names: readonly string[];
-	readonly defaultImport: string | undefined;
-	readonly isRelative: boolean;
-	readonly line: number;
-};
-
-/**
- * Extracts import statements from a TypeScript AST.
- *
- * @param tree - Parsed tree-sitter tree
- * @param _filePath - Relative file path (unused, kept for interface consistency)
- * @returns Parsed imports with module paths and imported names
- */
-function extractTypeScriptImports(
-	tree: TreeSitterTree,
-	_filePath: string,
-): readonly TypeScriptImport[] {
-	const imports: TypeScriptImport[] = [];
-
-	for (const child of tree.rootNode.children) {
-		if (child.type === "import_statement") {
-			parseImportStatement(child, imports);
-		}
-	}
-
-	return imports;
-}
-
-/** Parses an import statement into module path, named imports, and default import. */
-function parseImportStatement(node: TreeSitterNode, results: TypeScriptImport[]): void {
-	const fromClause = node.children.find((c) => c.type === "string");
-	if (!fromClause) return;
-
-	const contentNode = fromClause.children.find((c) => c.type === "string_fragment");
-	const module = contentNode?.text ?? "";
-	const isRelative = module.startsWith(".");
-
-	const importClause = node.children.find((c) => c.type === "import_clause");
-	if (!importClause) return;
-
-	let defaultImport: string | undefined;
-	const names: string[] = [];
-
-	for (const child of importClause.children) {
-		if (child.type === "identifier") {
-			defaultImport = child.text;
-		} else if (child.type === "named_imports") {
-			for (const spec of child.children) {
-				if (spec.type === "import_specifier") {
-					const nameNode = spec.childForFieldName("name");
-					if (nameNode) names.push(nameNode.text);
-				}
-			}
-		}
-	}
-
-	results.push({
-		module,
-		names,
-		defaultImport,
-		isRelative,
-		line: node.startPosition.row + 1,
-	});
-}
-
-export { extractTypeScriptImports, type TypeScriptImport };

package/src/extract/typescript/symbols.ts

@@ -1,252 +0,0 @@
-import type { Node, NodeKind } from "../../types/graph.ts";
-import type { TreeSitterNode, TreeSitterTree } from "../parser.ts";
-
-/**
- * Extracts symbols (functions, classes, methods, interfaces, type aliases)
- * from a TypeScript AST.
- *
- * @param tree - Parsed tree-sitter tree
- * @param filePath - Relative file path for node ID construction
- * @param _source - Original source text (unused, kept for interface consistency)
- * @returns Extracted nodes with deterministic IDs
- */
-function extractTypeScriptSymbols(
-	tree: TreeSitterTree,
-	filePath: string,
-	_source: string,
-): readonly Node[] {
-	const nodes: Node[] = [];
-	visitNode(tree.rootNode, filePath, [], nodes);
-	return nodes;
-}
-
-/** Scope entry for tracking parent context. */
-type ScopeEntry = { readonly name: string; readonly isClass: boolean };
-
-/** Recursively visits AST nodes to extract symbols. */
-function visitNode(
-	node: TreeSitterNode,
-	filePath: string,
-	scopeStack: readonly ScopeEntry[],
-	results: Node[],
-): void {
-	switch (node.type) {
-		case "function_declaration":
-			extractFunction(node, filePath, scopeStack, results);
-			return;
-		case "class_declaration":
-			extractClass(node, filePath, scopeStack, results);
-			return;
-		case "interface_declaration":
-			extractTypeDecl(node, filePath, scopeStack, results, "type");
-			return;
-		case "type_alias_declaration":
-			extractTypeDecl(node, filePath, scopeStack, results, "type");
-			return;
-		case "export_statement": {
-			// Unwrap: export function X, export class X, export const X = ...
-			for (const child of node.children) {
-				visitNode(child, filePath, scopeStack, results);
-			}
-			return;
-		}
-		case "lexical_declaration": {
-			// const handler = async () => { ... }
-			extractArrowFunctions(node, filePath, scopeStack, results);
-			return;
-		}
-		case "method_definition": {
-			extractMethod(node, filePath, scopeStack, results);
-			return;
-		}
-		default:
-			for (const child of node.children) {
-				visitNode(child, filePath, scopeStack, results);
-			}
-	}
-}
-
-/** Extracts a function declaration. */
-function extractFunction(
-	node: TreeSitterNode,
-	filePath: string,
-	scopeStack: readonly ScopeEntry[],
-	results: Node[],
-): void {
-	const nameNode = node.childForFieldName("name");
-	if (!nameNode) return;
-
-	const name = nameNode.text;
-	const qualifiedName = [...scopeStack.map((s) => s.name), name].join(".");
-	const id = `${filePath}::${qualifiedName}`;
-
-	results.push({
-		id,
-		kind: "function",
-		name,
-		file: filePath,
-		lineStart: node.startPosition.row + 1,
-		lineEnd: node.endPosition.row + 1,
-		language: "typescript",
-		signature: buildSignature(node, name),
-		isTest: false,
-		metadata: undefined,
-	});
-}
-
-/** Extracts a class declaration and recurses into its body for methods. */
-function extractClass(
-	node: TreeSitterNode,
-	filePath: string,
-	scopeStack: readonly ScopeEntry[],
-	results: Node[],
-): void {
-	const nameNode = node.childForFieldName("name");
-	if (!nameNode) return;
-
-	const name = nameNode.text;
-	const qualifiedName = [...scopeStack.map((s) => s.name), name].join(".");
-	const id = `${filePath}::${qualifiedName}`;
-
-	results.push({
-		id,
-		kind: "class",
-		name,
-		file: filePath,
-		lineStart: node.startPosition.row + 1,
-		lineEnd: node.endPosition.row + 1,
-		language: "typescript",
-		signature: undefined,
-		isTest: false,
-		metadata: undefined,
-	});
-
-	// Recurse into class body for methods
-	const body = node.childForFieldName("body");
-	if (body) {
-		const newScope = [...scopeStack, { name, isClass: true }];
-		for (const child of body.children) {
-			visitNode(child, filePath, newScope, results);
-		}
-	}
-}
-
-/** Extracts a method definition inside a class. */
-function extractMethod(
-	node: TreeSitterNode,
-	filePath: string,
-	scopeStack: readonly ScopeEntry[],
-	results: Node[],
-): void {
-	const nameNode = node.childForFieldName("name");
-	if (!nameNode) return;
-
-	const name = nameNode.text;
-	const qualifiedName = [...scopeStack.map((s) => s.name), name].join(".");
-	const id = `${filePath}::${qualifiedName}`;
-
-	results.push({
-		id,
-		kind: "method",
-		name,
-		file: filePath,
-		lineStart: node.startPosition.row + 1,
-		lineEnd: node.endPosition.row + 1,
-		language: "typescript",
-		signature: buildSignature(node, name),
-		isTest: false,
-		metadata: undefined,
-	});
-}
-
-/** Extracts an interface or type alias declaration. */
-function extractTypeDecl(
-	node: TreeSitterNode,
-	filePath: string,
-	scopeStack: readonly ScopeEntry[],
-	results: Node[],
-	kind: NodeKind,
-): void {
-	const nameNode = node.childForFieldName("name");
-	if (!nameNode) return;
-
-	const name = nameNode.text;
-	const qualifiedName = [...scopeStack.map((s) => s.name), name].join(".");
-	const id = `${filePath}::${qualifiedName}`;
-
-	results.push({
-		id,
-		kind,
-		name,
-		file: filePath,
-		lineStart: node.startPosition.row + 1,
-		lineEnd: node.endPosition.row + 1,
-		language: "typescript",
-		signature: undefined,
-		isTest: false,
-		metadata: undefined,
-	});
-}
-
-/** Extracts arrow functions assigned to const/let variables. */
-function extractArrowFunctions(
-	node: TreeSitterNode,
-	filePath: string,
-	scopeStack: readonly ScopeEntry[],
-	results: Node[],
-): void {
-	for (const child of node.children) {
-		if (child.type === "variable_declarator") {
-			const nameNode = child.childForFieldName("name");
-			const valueNode = child.childForFieldName("value");
-			if (nameNode && valueNode?.type === "arrow_function") {
-				const name = nameNode.text;
-				const qualifiedName = [...scopeStack.map((s) => s.name), name].join(".");
-				const id = `${filePath}::${qualifiedName}`;
-
-				results.push({
-					id,
-					kind: "function",
-					name,
-					file: filePath,
-					lineStart: node.startPosition.row + 1,
-					lineEnd: node.endPosition.row + 1,
-					language: "typescript",
-					signature: buildArrowSignature(valueNode, name),
-					isTest: false,
-					metadata: undefined,
-				});
-			}
-		}
-	}
-}
-
-/** Builds a signature string from a function/method declaration. */
-function buildSignature(node: TreeSitterNode, name: string): string {
-	const params = node.childForFieldName("parameters");
-	const returnType =
-		node.childForFieldName("return_type") ??
-		node.children.find((c) => c.type === "type_annotation");
-
-	const paramsStr = params?.text ?? "()";
-	const returnStr = returnType?.text ?? "";
-
-	return `${name}${paramsStr}${returnStr ? ` ${returnStr}` : ""}`;
-}
-
-/** Builds a signature string from an arrow function. */
-function buildArrowSignature(node: TreeSitterNode, name: string): string {
-	const params =
-		node.childForFieldName("parameters") ??
-		node.children.find((c) => c.type === "formal_parameters");
-	const returnType =
-		node.childForFieldName("return_type") ??
-		node.children.find((c) => c.type === "type_annotation");
-
-	const paramsStr = params?.text ?? "()";
-	const returnStr = returnType?.text ?? "";
-
-	return `${name}${paramsStr}${returnStr ? ` ${returnStr}` : ""}`;
-}
-
-export { extractTypeScriptSymbols };