🗺️ Code Cartographer

A CLI tool that visualizes code repository structures as interactive force-directed graphs. Analyze your codebase and see how your files connect through imports and exports in a beautiful, interactive web interface.

✨ Features

• 🔍 Static Analysis: Supports JavaScript, TypeScript, and their variants (.js, .jsx, .ts, .tsx, .mjs, .cjs)
• 🕷️ Dependency Mapping: Visualizes import/export relationships between files
• 🎨 Interactive Visualization: Zoom, pan, and explore your code structure
• 📱 Responsive Design: Works on desktop and mobile devices
• 🎯 Self-Contained Output: Generates a single HTML file with embedded visualization
• ⚡ Fast Analysis: Efficiently processes large codebases
• 🎛️ Customizable Views: Multiple layout options and interactive controls

🚀 Installation

Install globally via npm:

npm install -g code-cartographer

📖 Usage

Basic Usage

Analyze the current directory:

cartographer

Analyze a specific directory:

cartographer ./src

Options

• -o, --open: Automatically open the generated graph in your default browser
• --output <filename>: Specify the output filename (default: code-cartographer-graph.html)

Examples

# Analyze current directory and open in browser
cartographer -o

# Analyze src folder with custom output name
cartographer ./src --output my-project-graph.html

# Full example with all options
cartographer ./my-project -o --output project-structure.html

🎯 What Gets Analyzed

The tool scans for the following file types:

• JavaScript: .js, .jsx, .mjs, .cjs
• TypeScript: .ts, .tsx

It extracts:

• Import statements (import ... from '...')
• Require statements (require('...'))
• Export statements (export ...)
• Dynamic imports (import('...'))

🎨 Visualization Features

Interactive Controls

• Layout Options: Hierarchical, Force-Directed, Random
• Physics Toggle: Enable/disable physics simulation
• Size Controls: Adjust node and edge sizes
• Node Information: Click nodes to see details

Color Coding

• 🔵 TypeScript: Blue nodes for .ts/.tsx files
• 🟡 JavaScript: Yellow nodes for .js/.jsx files
• 🟦 ES Modules: Light blue for .mjs files
• 🟢 CommonJS: Green for .cjs files
• ⚫ Other: Gray for other supported files

🛠️ Development

Prerequisites

• Node.js 16.0.0 or higher
• npm or yarn

Setup

# Clone the repository
git clone https://github.com/yourusername/code-cartographer.git
cd code-cartographer

# Install dependencies
npm install

# Build the project
npm run build

# Link for local development
npm link

Scripts

• npm run build: Compile TypeScript to JavaScript
• npm run dev: Watch mode for development
• npm test: Run tests
• npm run lint: Run ESLint
• npm run format: Format code with Prettier

📦 Programmatic Usage

You can also use Code Cartographer programmatically:

import { CodeCartographer } from 'code-cartographer';

const cartographer = new CodeCartographer();
const htmlOutput = await cartographer.analyze('./my-project');
await cartographer.saveToFile(htmlOutput, 'output.html');

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Babel for JavaScript/TypeScript parsing
• Vis.js for network visualization
• Commander.js for CLI interface

📸 Screenshots

Example Output

The tool generates an interactive HTML file that looks like this:

🗺️ Code Cartographer - My Project    📊 42 Files  🔗 156 Connections

Layout: [Hierarchical ▼] Physics: [✓] Node Size: [■■■□□] Edge Width: [■■□□□]

[Interactive network visualization with nodes and edges representing files and their dependencies]

Legend:
🔵 TypeScript
🟡 JavaScript  
🟦 ES Module
🟢 CommonJS
⚫ Other

🔧 Configuration

The tool automatically skips common directories that shouldn't be analyzed:

• node_modules, .git, dist, build
• Hidden directories (starting with .)
• Common cache directories

⚡ Performance

• Handles codebases with thousands of files
• Uses streaming analysis for memory efficiency
• Progress indicators for large projects
• Optimized graph rendering for smooth interactions

🐛 Troubleshooting

Common Issues

"Cannot find module" errors

• Ensure you have Node.js 16+ installed
• Try reinstalling: npm uninstall -g code-cartographer && npm install -g code-cartographer

Large projects are slow

• The tool shows progress indicators
• Consider analyzing specific directories instead of entire projects
• Physics simulation can be disabled for better performance

Graph is too cluttered

• Use the layout controls to switch between visualization modes
• Adjust node and edge sizes using the control sliders
• Try the hierarchical layout for better organization

📈 Roadmap

• [ ] Support for more languages (Python, Go, Rust, etc.)
• [ ] Plugin system for custom analyzers
• [ ] Export to various formats (PNG, SVG, JSON)
• [ ] Integration with popular IDEs
• [ ] Advanced filtering and search capabilities
• [ ] Dependency health metrics and insights