Skip to content

Conversation

@prosdev
Copy link
Collaborator

@prosdev prosdev commented Nov 27, 2025

Summary

Implements #81 - Codebase Map (dev_map)

Adds a new MCP tool that returns a high-level overview of the codebase structure. When an AI asks "what does this codebase do?" or "show me the architecture", this tool provides a navigable map of directories, modules, and public APIs.

Changes

Core Map Module (packages/core/src/map/)

  • types.ts: MapNode, ExportInfo, MapOptions, CodebaseMap types
  • index.ts: generateCodebaseMap() and formatCodebaseMap() functions

Features:

  • Builds directory tree from indexed documents
  • Counts components per directory (recursive)
  • Extracts exported symbols
  • Configurable depth (1-5 levels)
  • Focus on specific directory
  • Token budget with automatic depth reduction
  • Alphabetical sorting

MCP Adapter (packages/mcp-server/src/adapters/built-in/map-adapter.ts)

  • dev_map tool with parameters:
    • depth: Directory depth (1-5, default: 2)
    • focus: Focus on specific directory path
    • includeExports: Show exported symbols (default: true)
    • tokenBudget: Max tokens for output (default: 2000)

Example Output

# Codebase Map

└── root/ (195 components)
    └── packages/ (150 components)
        ├── core/ (45 components)
        │   └── exports: RepositoryIndexer, VectorStorage, TypeScriptScanner...
        ├── cli/ (12 components)
        │   └── exports: createCLI, indexCommand, mcpCommand...
        ├── mcp-server/ (28 components)
        │   └── exports: MCPServer, SearchAdapter, PlanAdapter...
        └── subagents/ (18 components)
            └── exports: PlannerAgent, ExplorerAgent, Coordinator...

**Total:** 195 indexed components across 15 directories

Testing

  • 17 new tests for map generation in core
  • 22 new tests for MapAdapter
  • All 1359 tests passing

Closes #81

Add map module for generating hierarchical codebase views:
- MapNode, ExportInfo, MapOptions, CodebaseMap types
- generateCodebaseMap() builds tree from indexed documents
- formatCodebaseMap() renders tree as readable text
- Supports depth limiting, focus directory, export display
- Groups components by directory with counts

Part of #81
Create MapAdapter that provides the dev_map MCP tool:
- Shows directory tree with component counts
- Displays exported symbols per directory
- Configurable depth (1-5 levels)
- Focus on specific directory path
- Token budget with automatic depth reduction
- Uses startTimer and estimateTokensForText utilities

Registered in MCP server alongside existing adapters.

Part of #81
Add comprehensive test suites:
- 17 tests for generateCodebaseMap and formatCodebaseMap in core
- 22 tests for MapAdapter in mcp-server

Tests cover:
- Map structure and component counting
- Depth limiting and focus filtering
- Export extraction and limiting
- Token budget and truncation
- Validation of parameters
- Output formatting

Part of #81
@prosdev prosdev force-pushed the feat/81-codebase-map branch from fec1b6c to 6dacc5f Compare November 27, 2025 04:27
@prosdev prosdev merged commit 8173922 into main Nov 27, 2025
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Codebase Map (dev_map)

1 participant