@codeflow-map/core 0.1.0

package/README.md

@@ -0,0 +1,158 @@
+# @flowmap/core
+
+Language-agnostic call-graph analysis engine powered by [Tree-sitter](https://tree-sitter.github.io/tree-sitter/). Parse source files into a structured call graph with typed nodes, edges, and execution flows — entirely local, no LLM, no cloud.
+
+Used by the [FlowMap VS Code extension](https://github.com/devricky-codes/flowmap-vscode-extension) to render interactive call-flow diagrams.
+
+## Supported Languages
+
+| Language   | Functions | Calls | Components/Hooks |
+|------------|-----------|-------|------------------|
+| TypeScript | ✅        | ✅    | ✅               |
+| JavaScript | ✅        | ✅    | ✅               |
+| TSX        | ✅        | ✅    | ✅               |
+| JSX        | ✅        | ✅    | ✅               |
+| Python     | ✅        | ✅    | —                |
+| Go         | ✅        | ✅    | —                |
+
+## Installation
+
+```bash
+npm install @flowmap/core
+# or
+pnpm add @flowmap/core
+```
+
+> **Note:** `web-tree-sitter` requires WASM grammar files at runtime. You must provide a `wasmDirectory` pointing to a folder that contains the relevant `tree-sitter-<language>.wasm` files. These are available from the [`tree-sitter-<language>`](https://github.com/tree-sitter) grammar packages.
+
+## Usage
+
+### Parse a directory into a call graph
+
+```typescript
+import { analyzeDirectory } from '@flowmap/core';
+
+const graph = await analyzeDirectory({
+  rootPath: '/absolute/path/to/project',
+  wasmDirectory: '/path/to/wasm/grammars',
+  include: ['**/*.ts', '**/*.tsx'],
+  exclude: ['**/node_modules/**', '**/dist/**'],
+});
+
+console.log(`Scanned ${graph.scannedFiles} files in ${graph.durationMs}ms`);
+console.log(`Found ${graph.nodes.length} functions, ${graph.edges.length} call edges`);
+console.log(`Partitioned into ${graph.flows.length} flows`);
+```
+
+### Parse a single file
+
+```typescript
+import { parseFile } from '@flowmap/core';
+
+const { functions, calls } = await parseFile(
+  'src/index.ts',          // relative path (used as node IDs)
+  '/absolute/src/index.ts', // absolute path (for reading the file)
+  '/path/to/wasm',          // wasmDirectory
+  'typescript'              // SupportedLanguage
+);
+```
+
+### Build a call graph manually
+
+```typescript
+import { buildCallGraph, detectEntryPoints, partitionFlows } from '@flowmap/core';
+
+// nodes: FunctionNode[], rawCalls: RawCall[] — from parseFile()
+const edges = buildCallGraph(nodes, rawCalls);
+const nodesWithEntries = detectEntryPoints(nodes, edges);
+const { flows, orphans } = partitionFlows(nodesWithEntries, edges);
+```
+
+## Data Model
+
+### `FunctionNode`
+
+```typescript
+interface FunctionNode {
+  id: string;            // "relative/path.ts::functionName::startLine"
+  name: string;
+  filePath: string;      // relative to workspace root
+  startLine: number;     // 0-indexed
+  endLine: number;
+  params: Parameter[];
+  returnType: string | null;
+  isAsync: boolean;
+  isExported: boolean;
+  isEntryPoint: boolean;
+  language: SupportedLanguage;
+  kind?: 'function' | 'component' | 'hook' | 'method' | 'class' | 'iife';
+  parentFunctionId?: string;
+}
+```
+
+### `CallEdge`
+
+```typescript
+interface CallEdge {
+  from: string;   // caller FunctionNode.id
+  to: string;     // callee FunctionNode.id
+  line: number;
+  callType?: 'direct' | 'ref' | 'concurrent' | 'goroutine';
+}
+```
+
+### `Flow`
+
+```typescript
+interface Flow {
+  id: string;
+  entryPoint: string;  // FunctionNode.id of the root function
+  nodeIds: string[];   // all reachable function IDs in this flow
+}
+```
+
+### `Graph`
+
+```typescript
+interface Graph {
+  nodes: FunctionNode[];
+  edges: CallEdge[];
+  flows: Flow[];
+  orphans: string[];   // FunctionNode IDs with no connections
+  scannedFiles: number;
+  durationMs: number;
+}
+```
+
+## API Reference
+
+### `analyzeDirectory(options): Promise<Graph>`
+
+Scans a directory, parses all matched source files, and returns a complete `Graph`.
+
+| Option         | Type       | Description                                      |
+|----------------|------------|--------------------------------------------------|
+| `rootPath`     | `string`   | Absolute path to the project root                |
+| `wasmDirectory`| `string`   | Directory containing `.wasm` grammar files       |
+| `include`      | `string[]` | Glob patterns for files to include               |
+| `exclude`      | `string[]` | Glob patterns for files to exclude               |
+
+### `parseFile(relativePath, absolutePath, wasmDirectory, language): Promise<{functions, calls}>`
+
+Parses a single source file using Tree-sitter.
+
+### `buildCallGraph(nodes, rawCalls): CallEdge[]`
+
+Resolves raw call references into typed `CallEdge` objects.
+
+### `detectEntryPoints(nodes, edges): FunctionNode[]`
+
+Marks functions with no callers (in-degree = 0) but at least one outgoing call as entry points.
+
+### `partitionFlows(nodes, edges): { flows: Flow[], orphans: string[] }`
+
+Groups the call graph into independent execution flows using BFS from each entry point.
+
+## License
+
+MIT

package/dist/analyzer/extractorUtils.d.ts

@@ -0,0 +1,50 @@
+import { Parameter } from '../types';
+export declare const JS_NESTED_FN_TYPES: string[];
+export declare const PYTHON_NESTED_FN_TYPES: string[];
+export declare const GO_NESTED_FN_TYPES: string[];
+/**
+ * Walk an AST node collecting return statement values, skipping nested function scopes.
+ */
+export declare function getReturnValues(node: any, skipNestedTypes: string[]): string[];
+/**
+ * Walk parent chain to check for export_statement. Used by JS/TS family analyzers.
+ */
+export declare function checkExportedByParentWalk(node: any): boolean;
+/**
+ * Check if a declaration node has an `async` keyword child.
+ */
+export declare function checkIsAsync(node: any): boolean;
+/**
+ * Build parameter list from a formal_parameters AST node. Used by JS/TS family analyzers.
+ * @param paramsNode The formal_parameters AST node (may be null)
+ * @param includeTypes Whether to extract type annotations (true for TS/TSX, false for JS/JSX)
+ */
+export declare function buildJsParams(paramsNode: any, includeTypes: boolean): Parameter[];
+/**
+ * Walk parent chain to find an enclosing class (class_declaration or class_definition).
+ * Returns the class name or null.
+ */
+export declare function getEnclosingClassName(node: any): string | null;
+export declare const JS_FN_SCOPE_TYPES: string[];
+export declare const JS_CLASS_SCOPE_TYPES: string[];
+/**
+ * Walk parent chain collecting enclosing function and class scopes.
+ * Returns scopes from outermost to innermost.
+ */
+export declare function getEnclosingScopeChain(node: any, functionTypes: string[], classTypes: string[]): {
+    name: string;
+    type: 'function' | 'class' | 'object';
+}[];
+/**
+ * Extract parameters from an arrow_function or function_expression node directly.
+ * Used when the query doesn't capture @fn.params (e.g., lexical_declaration patterns).
+ */
+export declare function getParamsFromFunctionNode(node: any, includeTypes: boolean): Parameter[];
+/**
+ * Check if a call_expression node is inside a Promise.all/race/allSettled array argument.
+ */
+export declare function isInsidePromiseCombinator(node: any): boolean;
+/**
+ * Find the enclosing function and construct its expected ID.
+ */
+export declare function getEnclosingFunctionId(node: any, filePath: string): string | null;

package/dist/analyzer/extractorUtils.js

@@ -0,0 +1,247 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JS_CLASS_SCOPE_TYPES = exports.JS_FN_SCOPE_TYPES = exports.GO_NESTED_FN_TYPES = exports.PYTHON_NESTED_FN_TYPES = exports.JS_NESTED_FN_TYPES = void 0;
+exports.getReturnValues = getReturnValues;
+exports.checkExportedByParentWalk = checkExportedByParentWalk;
+exports.checkIsAsync = checkIsAsync;
+exports.buildJsParams = buildJsParams;
+exports.getEnclosingClassName = getEnclosingClassName;
+exports.getEnclosingScopeChain = getEnclosingScopeChain;
+exports.getParamsFromFunctionNode = getParamsFromFunctionNode;
+exports.isInsidePromiseCombinator = isInsidePromiseCombinator;
+exports.getEnclosingFunctionId = getEnclosingFunctionId;
+// Nested function/class types to skip when walking for return statements
+exports.JS_NESTED_FN_TYPES = ['function_declaration', 'arrow_function', 'function_expression', 'method_definition', 'generator_function_declaration', 'generator_function', 'class_declaration', 'class'];
+exports.PYTHON_NESTED_FN_TYPES = ['function_definition', 'class_definition'];
+exports.GO_NESTED_FN_TYPES = ['function_declaration', 'method_declaration', 'func_literal'];
+/**
+ * Walk an AST node collecting return statement values, skipping nested function scopes.
+ */
+function getReturnValues(node, skipNestedTypes) {
+    const returns = [];
+    function walk(n) {
+        if (!n)
+            return;
+        if (n.type === 'return_statement') {
+            const returnClause = n.children.find((c) => c.type !== 'return' && c.type !== ';');
+            if (returnClause && !skipNestedTypes.includes(returnClause.type))
+                returns.push(returnClause.text);
+        }
+        else {
+            for (const child of n.children) {
+                if (n !== node && skipNestedTypes.includes(child.type))
+                    continue;
+                walk(child);
+            }
+        }
+    }
+    walk(node);
+    return Array.from(new Set(returns));
+}
+/**
+ * Walk parent chain to check for export_statement. Used by JS/TS family analyzers.
+ */
+function checkExportedByParentWalk(node) {
+    let current = node;
+    while (current && current.type !== 'program') {
+        if (current.type === 'export_statement')
+            return true;
+        current = current.parent;
+    }
+    return false;
+}
+/**
+ * Check if a declaration node has an `async` keyword child.
+ */
+function checkIsAsync(node) {
+    for (const child of node.children) {
+        if (child.type === 'async')
+            return true;
+    }
+    return false;
+}
+/**
+ * Build parameter list from a formal_parameters AST node. Used by JS/TS family analyzers.
+ * @param paramsNode The formal_parameters AST node (may be null)
+ * @param includeTypes Whether to extract type annotations (true for TS/TSX, false for JS/JSX)
+ */
+function buildJsParams(paramsNode, includeTypes) {
+    const params = [];
+    if (!paramsNode)
+        return params;
+    for (const child of paramsNode.namedChildren) {
+        if (child.type === 'identifier') {
+            params.push({ name: child.text, type: null });
+        }
+        else {
+            const pName = child.childForFieldName('pattern') || child.childForFieldName('name');
+            const pType = includeTypes ? child.childForFieldName('type') : null;
+            params.push({
+                name: pName ? pName.text : child.text,
+                type: pType ? pType.text.replace(/^:\s*/, '') : null
+            });
+        }
+    }
+    return params;
+}
+/**
+ * Walk parent chain to find an enclosing class (class_declaration or class_definition).
+ * Returns the class name or null.
+ */
+function getEnclosingClassName(node) {
+    let parent = node.parent;
+    while (parent) {
+        if (parent.type === 'class_declaration' || parent.type === 'class_definition') {
+            const nameNode = parent.childForFieldName('name');
+            return nameNode ? nameNode.text : null;
+        }
+        parent = parent.parent;
+    }
+    return null;
+}
+exports.JS_FN_SCOPE_TYPES = ['function_declaration', 'method_definition', 'arrow_function', 'function_expression', 'generator_function_declaration', 'generator_function'];
+exports.JS_CLASS_SCOPE_TYPES = ['class_declaration', 'class_definition', 'class'];
+/**
+ * Walk parent chain collecting enclosing function and class scopes.
+ * Returns scopes from outermost to innermost.
+ */
+function getEnclosingScopeChain(node, functionTypes, classTypes) {
+    const chain = [];
+    let current = node.parent;
+    while (current) {
+        if (functionTypes.includes(current.type)) {
+            let name = null;
+            const nameNode = current.childForFieldName('name');
+            if (nameNode) {
+                name = nameNode.text;
+            }
+            else if (['arrow_function', 'function_expression', 'generator_function'].includes(current.type)) {
+                const varDecl = current.parent;
+                if (varDecl?.type === 'variable_declarator') {
+                    const nm = varDecl.childForFieldName('name');
+                    if (nm)
+                        name = nm.text;
+                }
+            } // Handle wrapper patterns: forwardRef, memo, etc.
+            // Walk up through arguments → call_expression chains for known wrappers
+            if (!name) {
+                let target = current.parent;
+                while (target?.type === 'arguments') {
+                    const callExpr = target.parent;
+                    if (callExpr?.type !== 'call_expression')
+                        break;
+                    const fn = callExpr.childForFieldName('function');
+                    const isWrapper = fn && ((fn.type === 'identifier' && /^(forwardRef|memo)$/.test(fn.text)) ||
+                        (fn.type === 'member_expression' && /^(forwardRef|memo)$/.test(fn.childForFieldName('property')?.text ?? '')));
+                    if (!isWrapper)
+                        break;
+                    target = callExpr.parent;
+                }
+                if (target?.type === 'variable_declarator') {
+                    const nm = target.childForFieldName('name');
+                    if (nm)
+                        name = nm.text;
+                }
+            }
+            if (name) {
+                chain.unshift({ name, type: 'function' });
+            }
+        }
+        else if (classTypes.includes(current.type)) {
+            const nameNode = current.childForFieldName('name');
+            if (nameNode) {
+                chain.unshift({ name: nameNode.text, type: 'class' });
+            }
+        }
+        else if (current.type === 'object') {
+            // Object literal assigned to a variable: const foo = { method() {} }
+            const varDecl = current.parent;
+            if (varDecl?.type === 'variable_declarator') {
+                const nm = varDecl.childForFieldName('name');
+                if (nm) {
+                    chain.unshift({ name: nm.text, type: 'object' });
+                }
+            }
+        }
+        current = current.parent;
+    }
+    return chain;
+}
+/**
+ * Extract parameters from an arrow_function or function_expression node directly.
+ * Used when the query doesn't capture @fn.params (e.g., lexical_declaration patterns).
+ */
+function getParamsFromFunctionNode(node, includeTypes) {
+    const formalParams = node.childForFieldName('parameters');
+    if (formalParams && formalParams.type === 'formal_parameters') {
+        return buildJsParams(formalParams, includeTypes);
+    }
+    const singleParam = node.childForFieldName('parameter');
+    if (singleParam && singleParam.type === 'identifier') {
+        return [{ name: singleParam.text, type: null }];
+    }
+    return [];
+}
+/**
+ * Check if a call_expression node is inside a Promise.all/race/allSettled array argument.
+ */
+function isInsidePromiseCombinator(node) {
+    let current = node.parent;
+    while (current) {
+        if (current.type === 'array') {
+            const argsParent = current.parent;
+            if (argsParent?.type === 'arguments') {
+                const callParent = argsParent.parent;
+                if (callParent?.type === 'call_expression') {
+                    const fn = callParent.childForFieldName('function');
+                    if (fn?.type === 'member_expression') {
+                        const obj = fn.childForFieldName('object');
+                        const prop = fn.childForFieldName('property');
+                        if (obj?.text === 'Promise' && ['all', 'race', 'allSettled'].includes(prop?.text)) {
+                            return true;
+                        }
+                    }
+                }
+            }
+        }
+        current = current.parent;
+    }
+    return false;
+}
+/**
+ * Find the enclosing function and construct its expected ID.
+ */
+function getEnclosingFunctionId(node, filePath) {
+    const fnTypes = ['function_declaration', 'method_definition', 'arrow_function', 'function_expression',
+        'generator_function_declaration', 'generator_function'];
+    let parent = node.parent;
+    while (parent) {
+        if (fnTypes.includes(parent.type)) {
+            let parentName = null;
+            if (parent.type === 'function_declaration' || parent.type === 'generator_function_declaration') {
+                const nameNode = parent.childForFieldName('name');
+                parentName = nameNode?.text ?? null;
+            }
+            else if (parent.type === 'method_definition') {
+                const nameNode = parent.childForFieldName('name');
+                parentName = nameNode?.text ?? null;
+                const className = getEnclosingClassName(parent);
+                if (className && parentName)
+                    parentName = `${className}.${parentName}`;
+            }
+            else if (parent.type === 'arrow_function' || parent.type === 'function_expression'
+                || parent.type === 'generator_function') {
+                const varDecl = parent.parent;
+                if (varDecl?.type === 'variable_declarator') {
+                    const nameNode = varDecl.childForFieldName('name');
+                    parentName = nameNode?.text ?? null;
+                }
+            }
+            if (parentName) {
+                return `${filePath}::${parentName}::${parent.startPosition.row}`;
+            }
+        }
+        parent = parent.parent;
+    }
+    return null;
+}

package/dist/analyzer/index.d.ts

@@ -0,0 +1,9 @@
+import { FunctionNode, RawCall, SupportedLanguage } from '../types';
+export declare function parseFile(filePath: string, absolutePath: string, wasmDirectory: string, languageId: SupportedLanguage): Promise<{
+    functions: FunctionNode[];
+    calls: RawCall[];
+}>;
+export declare function parseFileContent(filePath: string, content: string, wasmDirectory: string, languageId: SupportedLanguage): Promise<{
+    functions: FunctionNode[];
+    calls: RawCall[];
+}>;

package/dist/analyzer/index.js

@@ -0,0 +1,149 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseFile = parseFile;
+exports.parseFileContent = parseFileContent;
+// TODO v0.2: cross-file import resolution
+const fs = __importStar(require("fs/promises"));
+const web_tree_sitter_1 = __importDefault(require("web-tree-sitter"));
+const treeSitter_1 = require("./treeSitter");
+const typescript_1 = require("./languages/typescript");
+const javascript_1 = require("./languages/javascript");
+const tsx_1 = require("./languages/tsx");
+const jsx_1 = require("./languages/jsx");
+const go_1 = require("./languages/go");
+const python_1 = require("./languages/python");
+const ANALYZERS = {
+    typescript: typescript_1.typescriptAnalyzer,
+    tsx: tsx_1.tsxAnalyzer,
+    javascript: javascript_1.javascriptAnalyzer,
+    jsx: jsx_1.jsxAnalyzer,
+    python: python_1.pythonAnalyzer,
+    java: null,
+    go: go_1.goAnalyzer,
+    rust: null
+};
+async function parseFile(filePath, absolutePath, wasmDirectory, languageId) {
+    const analyzer = ANALYZERS[languageId];
+    if (!analyzer)
+        return { functions: [], calls: [] };
+    const content = await fs.readFile(absolutePath, 'utf8');
+    const treeSitterLang = await (0, treeSitter_1.loadLanguage)(languageId, wasmDirectory);
+    const parser = new web_tree_sitter_1.default();
+    parser.setLanguage(treeSitterLang);
+    const tree = parser.parse(content);
+    let functionQuery = null;
+    let callQuery = null;
+    try {
+        functionQuery = treeSitterLang.query(analyzer.functionQuery);
+        callQuery = treeSitterLang.query(analyzer.callQuery);
+        const functions = [];
+        const calls = [];
+        for (const match of functionQuery.matches(tree.rootNode)) {
+            const fn = analyzer.extractFunction(match, filePath, languageId);
+            if (fn)
+                functions.push(fn);
+        }
+        for (const match of callQuery.matches(tree.rootNode)) {
+            const call = analyzer.extractCall(match, filePath);
+            if (call) {
+                if (Array.isArray(call)) {
+                    calls.push(...call);
+                }
+                else {
+                    calls.push(call);
+                }
+            }
+        }
+        return { functions, calls };
+    }
+    finally {
+        if (functionQuery)
+            functionQuery.delete();
+        if (callQuery)
+            callQuery.delete();
+        if (tree)
+            tree.delete();
+        if (parser)
+            parser.delete();
+    }
+}
+async function parseFileContent(filePath, content, wasmDirectory, languageId) {
+    const analyzer = ANALYZERS[languageId];
+    if (!analyzer)
+        return { functions: [], calls: [] };
+    const treeSitterLang = await (0, treeSitter_1.loadLanguage)(languageId, wasmDirectory);
+    const parser = new web_tree_sitter_1.default();
+    parser.setLanguage(treeSitterLang);
+    const tree = parser.parse(content);
+    let functionQuery = null;
+    let callQuery = null;
+    try {
+        functionQuery = treeSitterLang.query(analyzer.functionQuery);
+        callQuery = treeSitterLang.query(analyzer.callQuery);
+        const functions = [];
+        const calls = [];
+        for (const match of functionQuery.matches(tree.rootNode)) {
+            const fn = analyzer.extractFunction(match, filePath, languageId);
+            if (fn)
+                functions.push(fn);
+        }
+        for (const match of callQuery.matches(tree.rootNode)) {
+            const call = analyzer.extractCall(match, filePath);
+            if (call) {
+                if (Array.isArray(call)) {
+                    calls.push(...call);
+                }
+                else {
+                    calls.push(call);
+                }
+            }
+        }
+        return { functions, calls };
+    }
+    finally {
+        if (functionQuery)
+            functionQuery.delete();
+        if (callQuery)
+            callQuery.delete();
+        if (tree)
+            tree.delete();
+        if (parser)
+            parser.delete();
+    }
+}

package/dist/analyzer/languages/go.d.ts

@@ -0,0 +1,2 @@
+import { LanguageAnalyzer } from '../../types';
+export declare const goAnalyzer: LanguageAnalyzer;