@nahisaho/musubix-codegraph

Multi-language Code Graph Analysis Engine for MUSUBIX

Overview

@nahisaho/musubix-codegraph is a high-performance code graph analysis library that provides:

• AST Parsing: Tree-sitter based multi-language code parsing (16 languages in v2.3.2)
• Graph Engine: Code entity and relationship graph construction
• GraphRAG: Graph-based Retrieval Augmented Generation for code search
• YATA Integration: Seamless integration with YATA knowledge graph

Installation

npm install @nahisaho/musubix-codegraph

Quick Start

Direct Library Usage

import { CodeGraph } from '@nahisaho/musubix-codegraph';

// Create instance
const codeGraph = new CodeGraph({
  storage: 'memory', // or 'sqlite', 'yata'
});

// Index a repository
const result = await codeGraph.index('/path/to/repo');
console.log(`Indexed ${result.entitiesIndexed} entities`);

// Query the graph
const deps = await codeGraph.findDependencies('UserService', { depth: 3 });
const callers = await codeGraph.findCallers('authenticate');

// GraphRAG search
const results = await codeGraph.globalSearch('authentication flow');

// Get statistics
const stats = await codeGraph.getStats();

Using Individual Components

import { ASTParser, GraphEngine, GraphRAGSearch } from '@nahisaho/musubix-codegraph';

// Parse a single file
const parser = new ASTParser();
const parseResult = await parser.parseFile('src/index.ts');

// Use graph engine directly
const graph = new GraphEngine(storage);
await graph.addEntity(entity);
const path = await graph.findPath('A', 'B');

// GraphRAG search
const search = new GraphRAGSearch(graph);
const communities = await search.detectCommunities();

Supported Languages (16 languages - v2.3.2)

| Priority | Language | Extensions | Status | |----------|----------|-----------|--------| | Existing | TypeScript | .ts, .tsx | ✅ Full Support | | Existing | JavaScript | .js, .jsx, .mjs | ✅ Full Support | | Existing | Python | .py, .pyw | ✅ Full Support | | P0 | Rust | .rs | ✅ Full Support | | P0 | Go | .go | ✅ Full Support | | P0 | Java | .java | ✅ Full Support | | P1 | PHP | .php | ✅ Full Support | | P1 | C# | .cs | ✅ Full Support | | P1 | C | .c, .h | ✅ Full Support | | P1 | C++ | .cpp, .hpp, .cc, .hh | ✅ Full Support | | P1 | Ruby | .rb | ✅ Full Support | | P2 | HCL/Terraform | .tf, .hcl | ✅ Full Support | | P2 | Kotlin | .kt, .kts | ✅ Full Support | | P2 | Swift | .swift | ✅ Full Support | | P2 | Scala | .scala, .sc | ✅ Full Support | | P2 | Lua | .lua | ✅ Full Support |

Entity Types Extracted:

• Functions, Methods, Constructors
• Classes, Interfaces, Traits, Protocols
• Structs, Enums, Records, Unions
• Modules, Packages, Namespaces
• Variables, Constants, Properties
• Type Definitions, Templates
• Language-specific constructs (Terraform resources, Swift extensions, etc.)

API Reference

CodeGraph (Facade)

class CodeGraph {
  // Indexing
  index(path: string): Promise<IndexResult>;
  reindex(path: string): Promise<IndexResult>;
  
  // Querying
  query(query: string): Promise<QueryResult>;
  findDependencies(entity: string, options?: DepOptions): Promise<Entity[]>;
  findCallers(entity: string): Promise<CallPath[]>;
  findCallees(entity: string): Promise<CallPath[]>;
  findImplementations(interfaceName: string): Promise<Entity[]>;
  analyzeModule(path: string): Promise<ModuleAnalysis>;
  
  // Code Retrieval
  getSnippet(entityId: string): Promise<CodeSnippet>;
  getFileStructure(path: string): Promise<FileStructure>;
  
  // GraphRAG
  globalSearch(query: string): Promise<SearchResult[]>;
  localSearch(entity: string, options?: LocalSearchOptions): Promise<SearchResult[]>;
  
  // Statistics
  getStats(): Promise<GraphStatistics>;
  
  // Events
  on(event: 'indexing:start' | 'indexing:progress' | 'indexing:complete', handler): void;
}

Storage Options

const codeGraph = new CodeGraph({
  storage: 'memory',  // In-memory (default, fast, no persistence)
});

const codeGraph = new CodeGraph({
  storage: 'sqlite',  // SQLite (persistent)
  sqlitePath: '.codegraph/index.db',
});

// YATA integration
import { YataDatabase } from '@nahisaho/yata-local';
import { createYataAdapter } from '@nahisaho/musubix-codegraph/storage';

const yata = new YataDatabase();
await yata.open();

const codeGraph = new CodeGraph({
  storage: createYataAdapter(yata),
});

CLI Usage

When used with MUSUBIX CLI:

# Index repository
musubix cg index /path/to/repo

# Query graph
musubix cg query "UserService"

# Find dependencies
musubix cg deps UserService

# Find callers/callees
musubix cg callers functionName
musubix cg callees functionName

# Semantic search
musubix cg search "authentication flow"

# Show statistics
musubix cg stats

# Show supported languages (v2.3.2)
musubix cg languages        # Table format
musubix cg languages --json # JSON format
musubix cg langs            # Alias

Performance

| Metric | Value | |--------|-------| | Indexing speed | ~32 entities/sec | | Query response | < 500ms | | Incremental index | < 2 sec | | Memory usage | < 500MB |

Requirements

• Node.js >= 20.0.0
• npm >= 10.0.0

License

MIT License - see LICENSE

Related

• MUSUBIX - Neuro-Symbolic AI Integration System
• @nahisaho/yata-local - Local Knowledge Graph Storage
• CodeGraphMCPServer - Original Python implementation