⬡ CodeMap

CodeMap is a high-performance, browser-native visualization engine that transforms complex codebases into interactive dependency maps. It provides an instant, entirely local structural audit of any project folder using the browser's native File System Access API.

---

📖 Table of Contents

• The "Why"
• 🎯 Who Is This For?
• ✨ Core Features
• 🛠 How It Works
• 🚀 Getting Started
• 🧪 Usage Examples
• ⚙️ Configuration
• 🗺 Roadmap
• 🤝 Support & Community
• 📄 License

---

🌟 The "Why"

As codebases grow, your mental map of the architecture inevitably fractures. Existing tools are either heavy (requiring servers or complex CLI setups) or disconnected (static diagrams that grow stale).

CodeMap solves this by generating an instant structural audit directly in your browser. No code is uploaded; the entire engine runs locally in your browser's memory, ensuring 100% privacy and zero setup time.

---

🎯 Who Is This For?

• Developers: Speed up onboarding or audit legacy codebases before a refactor.
• Architects: Visualize "Blast Radius" and identify "God Objects" with too many responsibilities.
• AI Agents: Feed LLMs a token-efficient, structural map to improve their understanding of your code's context.

---

✨ Core Features

• Local-First Discovery: Uses FileSystemDirectoryHandle for direct, secure folder access.
• Polyglot Parsing: Traces dependencies for TS/JS, Python, Java/Kotlin, Go, C/C++, and Dart.
• AI-Optimized Export: Downloads an ai-project-map.md specifically formatted to save tokens in LLM context windows.
• Interactive Graph: Force-directed layout with zoom, drag, and connection highlighting.
• Dual Themes: Optimized "Midnight" and "Cloud" themes for any environment.

---

🛠 How It Works (The Engine)

CodeMap operates as a deterministic four-stage pipeline:

1. The Scanner: Recursively walks the directory tree while respecting .gitignore patterns.
2. The Parser: Uses high-speed Static Regex Analysis to extract imports/exports (faster than AST parsing).
3. The Resolver: Normalizes relative paths and fuzzy-matches extensions (e.g., matching util to util.ts).
4. The Visualizer: Renders a D3-force physics simulation on a high-performance HTML5 <canvas>.

---

🖼 Demo

---

🚀 Getting Started

Project Setup

# Clone the repository
git clone https://github.com/babe051/codeMap.git

# Install dependencies
npm install

# Start development server
npm run dev

The app will be available at http://localhost:5173.

---

🧪 Usage Examples

Example 1: Auditing an Android/Java Project

1. Run CodeMap locally or via a live demo link.
2. Click "Open Project Folder" and select your Android root.
3. The tool will automatically skip build/ and .gradle/ folders.
4. Export the AI Context to help an AI agent understand your package structure.

Example 2: Next.js Refactoring

1. Scan your Next.js project.
2. Fix "Core" nodes (like Layout.tsx or api/client.ts) by left-clicking them.
3. Observe the "Out-Degree" count to see high-risk files that many other components depend on.

---

⚙️ Configuration

You can customize the engine's behavior in these key files:

• Library Support: Add new languages or tweak regex in src/engine/languages.ts.
• System Filtering: Modify DEFAULT_IGNORES in src/engine/scanner.ts to include/exclude custom directories.
• Physics Tuning: Adjust force strengths and collision radii in src/components/NetworkGraph.tsx.

---

🗺 Roadmap

• Git Interaction: Color-code nodes based on "Code Churn" (frequency of changes).
• Module Grouping: Visually cluster files by parent directory.
• Framework Detection: Standard library highlighting for React, Spring, etc.

---

🤝 Support & Community

Found a bug? Have a feature request?

• Issues: Open an issue on GitHub

---

📄 License

Distributed under the MIT License. See LICENSE for more information.

---

Created for engineers who build for humans and AI alike.