@codeflow-map/core 0.1.0 → 0.1.2

package/README.md

@@ -1,157 +1,206 @@
-# @flowmap/core
+# @codeflow-map/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.
+Language-agnostic call-graph engine powered by [Tree-sitter](https://tree-sitter.github.io/tree-sitter/). Feed it source files, get back a structured graph of every function, every call relationship, and every execution flow — deterministic, fully 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.
+Used by the [CallSight VS Code extension](https://github.com/devricky-codes/callsight-vscode-extension) to render interactive call-flow diagrams for any codebase.
+
+---
 
 ## Supported Languages
 
-| Language   | Functions | Calls | Components/Hooks |
-|------------|-----------|-------|------------------|
-| TypeScript | ✅        | ✅    | ✅               |
-| JavaScript | ✅        | ✅    | ✅               |
-| TSX        | ✅        | ✅    | ✅               |
-| JSX        | ✅        | ✅    | ✅               |
-| Python     | ✅        | ✅    | —                |
-| Go         | ✅        | ✅    | —                |
+| Language   | Functions | Calls | Components / Hooks |
+|------------|:---------:|:-----:|:-----------------:|
+| TypeScript | ✅        | ✅   | ✅                |
+| JavaScript | ✅        | ✅   | ✅                |
+| TSX        | ✅        | ✅   | ✅                |
+| JSX        | ✅        | ✅   | ✅                |
+| Python     | ✅        | ✅   |  -                |
+| Go         | ✅        | ✅   |  -                 |
+
+---
 
 ## Installation
 
 ```bash
-npm install @flowmap/core
+npm install @codeflow-map/core
 # or
-pnpm add @flowmap/core
+pnpm add @codeflow-map/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.
+> **Runtime requirement:** `web-tree-sitter` parses source files using WebAssembly grammar files.
+> You must supply a `wasmDirectory` that contains one `.wasm` file per language you want to analyse
+> (e.g. `tree-sitter-typescript.wasm`, `tree-sitter-python.wasm`).
+> Pre-built grammars are available from the official
+> [tree-sitter grammar repositories](https://github.com/tree-sitter).
+
+---
 
-## Usage
+## Quick Start
 
-### Parse a directory into a call graph
+### Analyse an entire directory
 
 ```typescript
-import { analyzeDirectory } from '@flowmap/core';
+import { analyzeDirectory } from '@codeflow-map/core';
 
 const graph = await analyzeDirectory({
-  rootPath: '/absolute/path/to/project',
+  rootPath:      '/absolute/path/to/project',
   wasmDirectory: '/path/to/wasm/grammars',
-  include: ['**/*.ts', '**/*.tsx'],
-  exclude: ['**/node_modules/**', '**/dist/**'],
+  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`);
+console.log(`${graph.nodes.length} functions · ${graph.edges.length} call edges · ${graph.flows.length} flows`);
 ```
 
-### Parse a single file
+### Analyse a single file
 
 ```typescript
-import { parseFile } from '@flowmap/core';
+import { parseFile } from '@codeflow-map/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)
+  'src/index.ts',           // relative path — used as node ID prefix
+  '/absolute/src/index.ts', // absolute path — used to read the file
   '/path/to/wasm',          // wasmDirectory
-  'typescript'              // SupportedLanguage
+  'typescript',             // SupportedLanguage
 );
 ```
 
-### Build a call graph manually
+### Build a call graph from raw parse results
 
 ```typescript
-import { buildCallGraph, detectEntryPoints, partitionFlows } from '@flowmap/core';
+import { buildCallGraph, detectEntryPoints, partitionFlows } from '@codeflow-map/core';
 
-// nodes: FunctionNode[], rawCalls: RawCall[] — from parseFile()
-const edges = buildCallGraph(nodes, rawCalls);
-const nodesWithEntries = detectEntryPoints(nodes, edges);
-const { flows, orphans } = partitionFlows(nodesWithEntries, edges);
+const edges               = buildCallGraph(functions, calls);
+const nodesWithEntries    = detectEntryPoints(functions, edges);
+const { flows, orphans }  = partitionFlows(nodesWithEntries, edges);
 ```
 
+---
+
 ## Data Model
 
 ### `FunctionNode`
 
+Represents a single function, method, component, or hook extracted from source.
+
 ```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;
+  id:               string;            // "relative/path.ts::functionName::startLine"
+  name:             string;            // human-readable, e.g. "UserService.getUser"
+  filePath:         string;            // relative to workspace root
+  startLine:        number;            // 0-indexed
+  endLine:          number;
+  params:           Parameter[];       // name + type (type is null for untyped languages)
+  returnType:       string | null;
+  isAsync:          boolean;
+  isExported:       boolean;
+  isEntryPoint:     boolean;           // true when in-degree = 0 and out-degree > 0
+  language:         SupportedLanguage;
+  kind?:            'function' | 'component' | 'hook' | 'method' | 'class' | 'iife';
+  parentFunctionId?: string;           // set for inner / nested functions
 }
 ```
 
 ### `CallEdge`
 
+Represents a directed call relationship between two functions.
+
 ```typescript
 interface CallEdge {
-  from: string;   // caller FunctionNode.id
-  to: string;     // callee FunctionNode.id
-  line: number;
+  from:      string;    // caller FunctionNode.id
+  to:        string;    // callee FunctionNode.id
+  line:      number;    // source line where the call occurs
   callType?: 'direct' | 'ref' | 'concurrent' | 'goroutine';
 }
 ```
 
+`callType` distinguishes how the call happens:
+- `direct` — standard synchronous call
+- `ref` — function passed as a reference (e.g. event handler, callback)
+- `concurrent` — call inside `Promise.all`, `asyncio.gather`, etc.
+- `goroutine` — Go `go fn()` launch
+
 ### `Flow`
 
+A connected subgraph reachable from a single entry point.
+
 ```typescript
 interface Flow {
-  id: string;
-  entryPoint: string;  // FunctionNode.id of the root function
-  nodeIds: string[];   // all reachable function IDs in this flow
+  id:           string;    // derived from the entry point's FunctionNode.id
+  entryPoint:   string;    // FunctionNode.id of the root function
+  nodeIds:      string[];  // all function IDs reachable from this entry point
 }
 ```
 
 ### `Graph`
 
+The complete analysis result returned by `analyzeDirectory`.
+
 ```typescript
 interface Graph {
-  nodes: FunctionNode[];
-  edges: CallEdge[];
-  flows: Flow[];
-  orphans: string[];   // FunctionNode IDs with no connections
+  nodes:        FunctionNode[];
+  edges:        CallEdge[];
+  flows:        Flow[];
+  orphans:      string[];   // FunctionNode IDs unreachable from any entry point
   scannedFiles: number;
-  durationMs: number;
+  durationMs:   number;
 }
 ```
 
+---
+
 ## API Reference
 
 ### `analyzeDirectory(options): Promise<Graph>`
 
-Scans a directory, parses all matched source files, and returns a complete `Graph`.
+Scans a directory, parses all matched source files, builds the call graph, detects entry points, and partitions execution flows in a single call.
+
+| Option          | Type       | Required | Description                                      |
+|-----------------|------------|:--------:|--------------------------------------------------|
+| `rootPath`      | `string`   | ✅       | Absolute path to the project root                |
+| `wasmDirectory` | `string`   | ✅       | Directory containing `.wasm` Tree-sitter grammars |
+| `include`       | `string[]` | ✅       | Glob patterns for files to include               |
+| `exclude`       | `string[]` |           | Glob patterns for files to exclude               |
 
-| 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}>`
+### `parseFile(relativePath, absolutePath, wasmDirectory, language): Promise<{ functions, calls }>`
 
-Parses a single source file using Tree-sitter.
+Parses a single source file and returns the raw extracted functions and call sites. Use this when you want fine-grained control over the analysis pipeline.
+
+---
 
 ### `buildCallGraph(nodes, rawCalls): CallEdge[]`
 
-Resolves raw call references into typed `CallEdge` objects.
+Resolves raw call references into typed `CallEdge` objects by matching callee names against the indexed function nodes.
+
+---
 
 ### `detectEntryPoints(nodes, edges): FunctionNode[]`
 
-Marks functions with no callers (in-degree = 0) but at least one outgoing call as entry points.
+Marks nodes as entry points using graph topology — a node is an entry point when nothing calls it (in-degree = 0) but it calls at least one other function (out-degree > 0). No language-specific heuristics, no name matching.
+
+---
 
 ### `partitionFlows(nodes, edges): { flows: Flow[], orphans: string[] }`
 
-Groups the call graph into independent execution flows using BFS from each entry point.
+Runs BFS from each entry point to group the call graph into independent execution flows. Functions unreachable from any entry point are collected separately as `orphans` — useful for dead code detection.
+
+---
+
+## How Entry Points Are Detected
+
+Entry point detection is purely graph-based — no hardcoded names, no language-specific rules. A function is an entry point if and only if:
+
+1. No other function in the graph calls it (in-degree = 0)
+2. It calls at least one other function (out-degree > 0)
+
+This means `main()` in Go, route handlers in Flask, React root components, and CLI entry functions are all detected automatically and consistently across all supported languages.
+
+> **Single-file caveat:** When analysing a single file in isolation, functions that only call external code will appear as orphans because their callees are not in scope. Run `analyzeDirectory` across the full workspace for accurate entry point detection.
+
+---
 
 ## License
 

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@codeflow-map/core",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Language-agnostic call-graph analysis engine powered by Tree-sitter. Parses TypeScript, JavaScript, TSX, JSX, Python, and Go source files into a structured call graph with flows.",
   "keywords": [
-    "flowmap",
+    "callsight",
     "call-graph",
     "tree-sitter",
     "static-analysis",
@@ -18,10 +18,10 @@
   "author": "devricky-codes",
   "repository": {
     "type": "git",
-    "url": "https://github.com/devricky-codes/flowmap-vscode-extension.git",
+    "url": "https://github.com/devricky-codes/callsight-vscode-extension.git",
     "directory": "packages/core"
   },
-  "homepage": "https://github.com/devricky-codes/flowmap-vscode-extension#readme",
+  "homepage": "https://github.com/devricky-codes/callsight-vscode-extension#readme",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
@@ -35,14 +35,15 @@
     "access": "public"
   },
   "scripts": {
-    "build": "../../node_modules/.bin/tsc",
-    "watch": "../../node_modules/.bin/tsc --watch"
+    "build": "tsc",
+    "watch": "tsc --watch"
   },
   "dependencies": {
     "web-tree-sitter": "^0.24.4",
     "minimatch": "^9.0.3"
   },
   "devDependencies": {
-    "@types/node": "^20.10.6"
+    "@types/node": "^20.10.6",
+    "typescript": "^5.3.3"
   }
 }