@nahisaho/musubix-codegraph 2.3.0

package/README.md

@@ -0,0 +1,187 @@
+# @nahisaho/musubix-codegraph
+
+**Multi-language Code Graph Analysis Engine for MUSUBIX**
+
+[![npm version](https://img.shields.io/npm/v/@nahisaho/musubix-codegraph.svg)](https://www.npmjs.com/package/@nahisaho/musubix-codegraph)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## 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)
+- **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
+
+```bash
+npm install @nahisaho/musubix-codegraph
+```
+
+## Quick Start
+
+### Direct Library Usage
+
+```typescript
+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
+
+```typescript
+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
+
+| Language | Extensions | Status |
+|----------|-----------|--------|
+| TypeScript | `.ts`, `.tsx` | ✅ |
+| JavaScript | `.js`, `.jsx`, `.mjs` | ✅ |
+| Python | `.py` | ✅ |
+| Rust | `.rs` | ✅ |
+| Go | `.go` | ✅ |
+| Java | `.java` | ✅ |
+| PHP | `.php` | ✅ |
+| C# | `.cs` | ✅ |
+| C | `.c`, `.h` | ✅ |
+| C++ | `.cpp`, `.hpp`, `.cc` | ✅ |
+| Ruby | `.rb` | ✅ |
+| HCL | `.tf`, `.hcl` | ✅ |
+
+## API Reference
+
+### CodeGraph (Facade)
+
+```typescript
+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
+
+```typescript
+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:
+
+```bash
+# Index repository
+musubix codegraph index /path/to/repo
+
+# Query graph
+musubix codegraph query "UserService"
+
+# Find dependencies
+musubix codegraph find-deps UserService --depth 3
+
+# Show statistics
+musubix codegraph stats
+
+# Start MCP server
+musubix codegraph serve
+```
+
+## 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](../../LICENSE)
+
+## Related
+
+- [MUSUBIX](https://github.com/nahisaho/MUSUBIX) - Neuro-Symbolic AI Integration System
+- [@nahisaho/yata-local](../yata-local) - Local Knowledge Graph Storage
+- [CodeGraphMCPServer](https://github.com/nahisaho/CodeGraphMCPServer) - Original Python implementation

package/dist/codegraph.d.ts

@@ -0,0 +1,218 @@
+/**
+ * @nahisaho/musubix-codegraph - CodeGraph Facade
+ *
+ * Main entry point for code graph analysis
+ *
+ * @packageDocumentation
+ * @module @nahisaho/musubix-codegraph
+ *
+ * @see REQ-CG-API-001
+ * @see REQ-CG-API-002
+ * @see REQ-CG-API-003
+ * @see DES-CG-001
+ */
+import type { CodeGraphOptions, Entity, QueryResult, IndexResult, GraphStatistics, CallPath, ModuleAnalysis, CodeSnippet, FileStructure, SearchResult, GraphQuery, DependencyOptions, LocalSearchOptions, GlobalSearchOptions } from './types.js';
+import { CodeGraphEventEmitter } from './events/index.js';
+/**
+ * CodeGraph - Main facade for code graph analysis
+ *
+ * Provides a unified API for:
+ * - AST parsing and entity extraction
+ * - Graph construction and querying
+ * - Dependency and call graph analysis
+ * - GraphRAG-based semantic search
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const codeGraph = new CodeGraph({ storage: 'memory' });
+ * await codeGraph.index('/path/to/repo');
+ *
+ * const deps = await codeGraph.findDependencies('UserService');
+ * const callers = await codeGraph.findCallers('authenticate');
+ * const results = await codeGraph.globalSearch('authentication');
+ * ```
+ *
+ * @see REQ-CG-API-001 - Library as standalone
+ * @see REQ-CG-API-002 - Programmatic API
+ */
+export declare class CodeGraph extends CodeGraphEventEmitter {
+    private options;
+    private storage;
+    private initialized;
+    /**
+     * Create a new CodeGraph instance
+     *
+     * @param options - Configuration options
+     */
+    constructor(options?: CodeGraphOptions);
+    /**
+     * Register a handler for indexing start events
+     */
+    onIndexingStart(handler: (path: string) => void): this;
+    /**
+     * Register a handler for indexing complete events
+     */
+    onIndexingComplete(handler: (result: {
+        entitiesIndexed: number;
+        relationsIndexed: number;
+        errors: unknown[];
+    }) => void): this;
+    /**
+     * Register a handler for indexing progress events
+     */
+    onIndexingProgress(handler: (processed: number, total: number, currentFile: string) => void): this;
+    /**
+     * Register a handler for indexing error events
+     */
+    onIndexingError(handler: (error: Error, file?: string) => void): this;
+    /**
+     * Register a handler for query start events
+     */
+    onQueryStart(handler: (query: GraphQuery) => void): this;
+    /**
+     * Register a handler for query complete events
+     */
+    onQueryComplete(handler: (result: QueryResult, durationMs: number) => void): this;
+    /**
+     * Initialize the CodeGraph instance
+     *
+     * @internal
+     */
+    private ensureInitialized;
+    /**
+     * Create storage adapter based on options
+     *
+     * @internal
+     */
+    private createStorage;
+    /**
+     * Index a repository or directory
+     *
+     * @param path - Path to repository or directory
+     * @returns Index result with statistics
+     *
+     * @see REQ-CG-IDX-001
+     *
+     * @example
+     * ```typescript
+     * const result = await codeGraph.index('/path/to/repo');
+     * console.log(`Indexed ${result.entitiesIndexed} entities`);
+     * ```
+     */
+    index(path: string): Promise<IndexResult>;
+    /**
+     * Reindex a repository (clear and index fresh)
+     *
+     * @param path - Path to repository or directory
+     * @returns Index result with statistics
+     */
+    reindex(path: string): Promise<IndexResult>;
+    /**
+     * Query the code graph
+     *
+     * @param query - Search query string or query object
+     * @returns Query result with matching entities
+     *
+     * @see REQ-CG-GRF-003
+     */
+    query(query: string | GraphQuery): Promise<QueryResult>;
+    /**
+     * Find dependencies of an entity
+     *
+     * @param entityName - Name or ID of the entity
+     * @param options - Dependency analysis options
+     * @returns List of dependent entities
+     *
+     * @see REQ-CG-GRF-004
+     */
+    findDependencies(entityName: string, options?: DependencyOptions): Promise<Entity[]>;
+    /**
+     * Find callers of a function or method
+     *
+     * @param entityName - Name or ID of the function/method
+     * @returns List of call paths
+     *
+     * @see REQ-CG-GRF-005
+     */
+    findCallers(entityName: string): Promise<CallPath[]>;
+    /**
+     * Find callees of a function or method
+     *
+     * @param entityName - Name or ID of the function/method
+     * @returns List of call paths
+     *
+     * @see REQ-CG-GRF-005
+     */
+    findCallees(entityName: string): Promise<CallPath[]>;
+    /**
+     * Find implementations of an interface
+     *
+     * @param interfaceName - Name or ID of the interface
+     * @returns List of implementing entities
+     */
+    findImplementations(interfaceName: string): Promise<Entity[]>;
+    /**
+     * Analyze module structure
+     *
+     * @param path - Path to module/file
+     * @returns Module analysis result
+     */
+    analyzeModule(path: string): Promise<ModuleAnalysis>;
+    /**
+     * Get source code snippet for an entity
+     *
+     * @param entityId - Entity ID
+     * @returns Code snippet with context
+     */
+    getSnippet(entityId: string): Promise<CodeSnippet>;
+    /**
+     * Get file structure overview
+     *
+     * @param path - File path
+     * @returns File structure with entities
+     */
+    getFileStructure(path: string): Promise<FileStructure>;
+    /**
+     * Global search across all code communities
+     *
+     * @param query - Search query
+     * @param options - Search options
+     * @returns Search results with relevance scores
+     *
+     * @see REQ-CG-RAG-002
+     */
+    globalSearch(query: string, options?: GlobalSearchOptions): Promise<SearchResult[]>;
+    /**
+     * Local search in entity neighborhood
+     *
+     * @param entityName - Entity name or ID
+     * @param options - Search options
+     * @returns Search results from entity neighborhood
+     *
+     * @see REQ-CG-RAG-003
+     */
+    localSearch(entityName: string, options?: LocalSearchOptions): Promise<SearchResult[]>;
+    /**
+     * Get graph statistics
+     *
+     * @returns Graph statistics
+     */
+    getStats(): Promise<GraphStatistics>;
+    /**
+     * Close the CodeGraph instance and release resources
+     */
+    close(): Promise<void>;
+    /**
+     * Check if instance is initialized
+     */
+    isInitialized(): boolean;
+}
+/**
+ * Create a new CodeGraph instance
+ *
+ * @param options - Configuration options
+ * @returns CodeGraph instance
+ */
+export declare function createCodeGraph(options?: CodeGraphOptions): CodeGraph;
+//# sourceMappingURL=codegraph.d.ts.map

package/dist/codegraph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codegraph.d.ts","sourceRoot":"","sources":["../src/codegraph.ts"],"names":[],"mappings":"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"}