⚡ Codebase Memory Engine (CME)

Advanced Architecture Intelligence & Dependency Visualization Platform — 100% static analysis, zero external AI calls.

Codebase Memory Engine is a powerful, local-first VS Code extension designed to automatically map, visualize, and police your JavaScript and TypeScript codebases. By parsing import graphs, function calls, and directory layers statically, CME gives you the complete blueprint of your architecture without sending a single line of code to external APIs.

📖 New User Guide - Start Here!

Welcome to Codebase Memory Engine! Think of this extension as Google Maps for your code. When you work on a large project, it's easy to get lost in hundreds of files. This extension solves that by acting as a "brain" for your project.

Who is this for?

• New Developers: Understand a massive codebase in minutes instead of weeks by looking at the visual map.
• Tech Leads & Architects: Ensure the team is following good coding practices and catch bad dependencies early.
• Anyone Refactoring Code: Know exactly what will break before you make a change.

What does it do? (Core Features Simplified)

1. 🕸️ Interactive Blueprint (Dependency Graph): Visualizes your entire code as a mind-map. Each file is a capsule, and lines show how they connect. You can view them by folders or structural layers.
2. ⚡ Impact Analysis (Blast Radius): If you edit a file, this tells you exactly which other files depend on it, so you know what you might accidentally break.
3. 👻 Dead Code Cleaner: Finds "Ghost Files" (files no one is using) and unreferenced code to help you keep the project clean.
4. ⭕ Circular Dependency Detector: Finds infinite loops (A calls B, B calls C, C calls A) that can crash your app, and warns you instantly.
5. 🚧 Layer Violation Engine: Lets you set rules (e.g., "Database files shouldn't talk to UI files"). If a developer breaks a rule, it throws an error!
6. 🏥 Health Score: Grades every file out of 100 based on how fragile or tangled its connections are.
7. 🔄 Async Flow Trace: Traces API calls and async functions across multiple files so you can see the chain of execution.
8. 💡 Editor Hints (CodeLens): While typing in your editor, you'll see small hints above your imports showing their health and connections.

🗂️ 4 Smart Sidebar Views (VS Code Activity Bar)

In addition to the main graph, CME adds 4 dedicated sections to your VS Code sidebar so you can monitor your project's health without ever leaving the editor:

1. 🗺️ Project Map: A "Smart Explorer" that mirrors your project's folder structure, but displays the Health Score (0-100) and connection count next to every single file.
2. 👻 Dead Code & Tech Debt: Flags unused "orphan" files, unreferenced exports (functions no one calls), and oversized files so you can safely delete them.
3. ⭕ Circular Dependencies: Lists all infinite import loops (e.g., File A imports B, which imports A) that could cause runtime crashes, showing you the exact chain of files to fix.
4. 🚧 Layer Violations (Architecture Cops): If you define architectural rules (like "Database models cannot import UI components"), this view catches and lists any developer who breaks those rules.

(Note: The extension actively watches your project. If you add, delete, or modify files, CME detects it instantly and updates the map and metrics in the background!)

🎨 Premium Visual Features

• Interactive Force-Directed Dependency Graph: A high-performance, physics-simulated, and color-coded dependency canvas inside a VS Code webview. Supports smooth mouse wheel panning, zooming, node dragging, and double-clicking to open files in your editor.
• Ego-Centric Focus Mode: Toggle between a bird's-eye view of your entire repository and a specialized "Focus Mode" that visualizes only the active file and its immediate 1-hop imports/exporters.
• Architecture Violation Inspector: Group and view architectural rule breaches in your codebase via custom sidebar tree views, complete with inline warnings and errors in the VS Code Problems tab.
• Interactive CodeLens & Hover Tooltips: View instability index, coupling metrics, circular import loops, and git authors directly in your editor code.

⚙️ Core Analysis Engines

📂 1. Cache-First Workspace Scanner

• Near-instant startup times backed by an incremental, mtime-based cache (.cme-cache.json).
• Runs incremental, debounced re-scans in the background as you edit, ensuring your visualization is always up-to-date.

⭕ 2. High-Performance Cycle Detection

• Instantly finds complex cyclic imports and circular dependencies in your code.
• Lists all loop chains clearly in the sidebar, with direct file navigation to resolve loops immediately.

👻 3. Dead Code & Tech Debt Detector

• Orphan Files: Finds TS/JS files that have no importers across the codebase (excluding entry points and configs).
• Unreferenced Exports: Identifies specific functions, classes, and variables exported from modules but never imported or called.
• Oversized Files: Flags complex, bloated files that exceed your configured line threshold.

🛡️ 4. Directory Layer Rule Enforcer

Enforce boundaries across your clean architecture, domain-driven design, or monorepo components. Define rules in .cme-arch.json in the root of your workspace:

{
  "rules": [
    {
      "from": "src/controllers/**",
      "deny": "src/models/**",
      "message": "Controllers must access database models through services!",
      "severity": "error"
    }
  ]
}

⚙️ Extension Settings

Configure CME to match your codebase style in your User or Workspace settings.json:

• cme.excludePatterns: Array of file/directory names to exclude (e.g., ["node_modules", "dist", ".next"]).
• cme.maxFileSize: Maximum file size in KB to analyze (default: 500).
• cme.complexityThreshold: Line count threshold for "oversized file" warnings (default: 200).
• cme.codeLensThreshold: Minimum imports required for import CodeLens indicators to appear (default: 5).
• cme.enableGitIntegration: Integrates git history details in hover tooltips (default: true).
• cme.healthScoreWeights: Point deduction weights for Modular Health calculation.

🛠️ Commands

Open the Command Palette (Ctrl+Shift+P or Cmd+Shift+P) and type CME:

• CME: Show Full Project Graph — Open the global force-directed interactive dependency view.
• CME: Show Dependency Graph — Show interactive focus mode for the active file.
• CME: Analyze Impact Radius — Highlight the files and routes affected if you edit the active file.
• CME: Detect Circular Dependencies — Instantly scan for cyclic dependencies.
• CME: Detect Dead Code & Tech Debt — Run unused exports and orphan file scans.
• CME: Show Health Score — Display the Instability and Coupling metrics for the active file.
• CME: Save Architecture Snapshot — Save the current dependency graph state.
• CME: Compare with Snapshot — Highlight new or removed dependencies compared to the saved snapshot.

📄 License

This extension is licensed under the MIT License. Created with 💙 for premium codebase insights.