multi-language dependency graph construction with bidirectional tracking
Parses source code in Python, Lua, C, C++, Rust, and Zig using language-specific import pattern matching (regex-based for each language) to build a bidirectional dependency map. The system constructs a directed graph where nodes are files and edges represent import relationships, enabling traversal of both incoming and outgoing dependencies. Uses buildDependentMap() to resolve import paths and track which files depend on which other files across the entire codebase.
Unique: Implements language-agnostic dependency parsing via configurable regex patterns per language (IMPORT_PATTERNS in file-utils.ts) rather than AST parsing, enabling lightweight analysis across 6+ languages without heavy parser dependencies. Tracks bidirectional relationships (both 'depends on' and 'is depended by') in a single pass.
vs alternatives: Faster than AST-based tools like Understand or Lattix for initial codebase scans due to regex simplicity, but less accurate for complex import patterns; better suited for AI context generation than enterprise dependency analyzers
file importance scoring with multi-factor ranking algorithm
Calculates a normalized importance score (0-10) for each file using a weighted combination of factors: dependency count (how many files depend on it), file type heuristics (core files like main.py or index.ts score higher), directory depth (files closer to root are weighted higher), and naming patterns (files matching keywords like 'config', 'utils', 'core' receive boosts). The calculateImportance() function in file-utils.ts combines these signals into a single comparable metric, enabling AI assistants to prioritize which files to analyze first.
Unique: Combines dependency-based ranking (graph centrality) with file-type heuristics and naming pattern recognition in a single normalized score, rather than using only dependency counts or only static heuristics. Allows setFileImportance() to override scores manually, enabling human-in-the-loop refinement.
vs alternatives: More lightweight than machine-learning-based importance ranking (e.g., using code metrics) but more context-aware than simple dependency counting; designed specifically for AI assistant context prioritization rather than general code metrics
mermaid diagram generation with customizable visualization and filtering
Generates interactive Mermaid flowchart diagrams from the dependency graph, with support for customizable node styling, layout algorithms, and filtering options. The MermaidGenerator class in mermaid-generator.ts converts the file dependency graph into Mermaid syntax, applies visual styling based on file importance scores (color intensity, node size), and produces HTML output via createMermaidHtml(). Supports filtering by file type, importance threshold, or specific file patterns to reduce diagram complexity for large codebases.
Unique: Integrates importance scores into visual encoding (node color/size reflects file criticality) rather than treating all files equally, making architectural hierarchy immediately visible. Supports dynamic filtering to generate focused diagrams for subsystems without manual graph manipulation.
vs alternatives: Simpler and more accessible than GraphViz or Cytoscape for quick visualization, but less powerful for complex layout control; better suited for documentation and AI context than specialized dependency analyzers like Understand
file tree state persistence with multi-project configuration management
Manages persistent storage of file analysis results across multiple independent projects using a configuration-based approach. The storage-utils.ts module provides createFileTreeConfig(), saveFileTree(), and loadFileTree() functions that serialize the complete file tree (nodes, edges, importance scores, metadata) to disk in JSON format. Each project maintains its own configuration file, enabling users to analyze multiple codebases independently and reload previous analyses without re-scanning.
Unique: Implements per-project configuration files that store complete analysis state (not just metadata), enabling independent file trees for different project areas. Uses JSON serialization for human-readable configs that can be version-controlled or manually edited.
vs alternatives: Simpler than database-backed persistence (no external dependencies) but less queryable; suitable for AI tool integration where config files are preferred over databases
real-time filesystem monitoring with automatic dependency graph updates
Watches the filesystem for changes (file creation, deletion, modification) using Node.js fs.watch() and automatically updates the dependency graph when files are added or removed. The FileWatcher class in mcp-server.ts implements handleFileEvent() to detect changes, re-analyze affected files, and update the bidirectional dependency map incrementally. This enables the MCP server to maintain a current view of the codebase without requiring manual refresh or full re-scans.
Unique: Integrates filesystem monitoring directly into the MCP server lifecycle, automatically updating the dependency graph on file system events rather than requiring explicit refresh calls. Uses incremental re-analysis (only affected files) rather than full re-scans.
vs alternatives: More responsive than polling-based approaches but less precise than AST-aware change detection; suitable for AI assistants that need current codebase state without manual refresh
mcp protocol server implementation with tool-based api exposure
Implements the Model Context Protocol (MCP) specification as a TypeScript server that exposes file analysis capabilities as callable tools. The mcp-server.ts file (lines 297-369, 571-575, 578-1584) defines the MCP server initialization, tool registration, and request/response handling. Tools are registered with JSON schemas describing parameters and return types, enabling AI clients to discover and invoke capabilities like 'analyze_codebase', 'get_file_importance', 'generate_diagram' through standard MCP protocol messages over stdio transport.
Unique: Wraps all file analysis capabilities as discoverable MCP tools with JSON schemas, enabling AI clients to understand and invoke them without hardcoding. Uses stdio transport for seamless integration with AI development environments.
vs alternatives: More standardized and composable than REST APIs or custom protocols; enables AI assistants to discover and use tools dynamically without pre-configuration
file metadata and summary storage with human-ai annotation support
Stores and retrieves file-level metadata including human-written or AI-generated summaries, descriptions, and custom annotations. The updateFileNode() and getFileNode() functions in storage-utils.ts manage a file node structure that includes not just dependency information but also descriptive text, tags, and custom properties. This enables AI assistants to augment their understanding of files with human-provided context or to store AI-generated summaries for future reference.
Unique: Integrates annotation storage directly into the file tree structure rather than as a separate system, enabling metadata to be persisted alongside analysis results. Supports both human-written and AI-generated summaries in the same field.
vs alternatives: Simpler than external knowledge bases (no additional dependencies) but less queryable; suitable for lightweight annotation workflows integrated with file analysis
language-specific import pattern matching and path resolution
Implements language-specific regex patterns to extract import statements from source code and resolve them to actual file paths. For each supported language (Python, Lua, C, C++, Rust, Zig), the system defines IMPORT_PATTERNS that match language-specific import syntax (e.g., 'import X' for Lua, 'from X import Y' for Python, '#include' for C/C++). The resolveImportPath() function in file-utils.ts converts extracted import names to filesystem paths, handling relative imports, package names, and file extensions.
Unique: Uses configurable regex patterns per language (IMPORT_PATTERNS in file-utils.ts) rather than language-specific parsers, enabling support for multiple languages without heavyweight dependencies. Patterns are centralized and can be extended for new languages.
vs alternatives: Much faster than AST-based parsing for initial scans, but less accurate for complex import patterns; better for breadth (many languages) than depth (complex syntax handling)
+2 more capabilities