feat(cli): add dev map command with 224x performance optimization

[prosdev]

🎯 What This Adds

New dev map command to visualize codebase structure with component counts, exports, and hot paths.

🚀 Performance Optimizations

Three Major Bottlenecks Fixed:

1. Semantic Search → Fast Scan (10-20x faster)

   • Added getAll() method to skip embedding generation
   • No vector similarity calculation needed for structural queries

2. Embedder Initialization (100+ seconds saved)

   • Added skipEmbedder option to initialize()
   • Lazy loading for read-only operations

3. Git Stats Enrichment (103 seconds saved)

   • Created getBasicStats() to skip expensive git analysis
   • Avoided scanning 1000 commits just to check if repo is indexed

Results

• Before: 103+ seconds ⏳
• After: 0.46 seconds ⚡
• Speedup: 224x faster!

🐛 Bugs Fixed

• Fixed component count propagation causing exponential overflow (2.4B → 3.7K)
• Added getAll() to test mocks

✨ Features

• --depth - Control directory nesting (1-5)
• --focus - Zoom into specific directories
• --exports / --no-exports - Show/hide exported symbols
• --change-frequency - Show git activity hotspots
• --token-budget - Control output size
• --verbose - Enable debug logging

📋 Examples

# Show full codebase structure
dev map

# Deeper nesting
dev map --depth 3

# Focus on specific directory
dev map --focus packages/core

# Show git activity hotspots
dev map --change-frequency

# Debug logging
dev map --verbose

🧪 Testing

• ✅ All 1,918 tests passing
• ✅ Lint clean
• ✅ TypeCheck passed
• ✅ Pre-commit hooks passed

📁 Files Changed

• packages/core/src/vector/store.ts - Added getAll()
• packages/core/src/vector/index.ts - Added lazy embedder init
• packages/core/src/indexer/index.ts - Added getBasicStats()
• packages/core/src/map/index.ts - Fixed count propagation + logging
• packages/cli/src/commands/map.ts - New command with verbose logging
• packages/cli/src/cli.ts - Registered map command
• Tests updated with getAll() mocks

[prosdev]

✅ Comprehensive Testing Complete

All features have been tested and verified working correctly:

1. Basic Map Generation ⚡

dev map --depth 2

• Time: 0.46 seconds
• Result: 3,733 components across 17 directories
• Status: ✅ Working perfectly

2. Change Frequency Analysis 🔥

dev map --depth 2 --change-frequency

• Time: 2.2 seconds (adds ~1.7s for git analysis)
• Indicators:
  • 🔥 for hot directories (5+ commits/month)
  • ✏️ for moderate activity (1-4 commits/month)
• Status: ✅ Accurate git activity tracking

3. Verbose Logging 🪵

dev map --verbose --change-frequency

• Features:
  • Detailed timing for each step (Retrieved docs: 41ms, Built tree: 1ms, Git analysis: 537ms)
  • DEBUG/INFO level logs with structured metadata
  • Duration breakdowns and component counts
• Status: ✅ Comprehensive debugging info

4. Focus on Directory 🎯

dev map --focus packages/cli --depth 3

• Result: Filters to specific directory with deeper nesting
• Graceful handling: Non-existent paths show 0 components (no crash)
• Status: ✅ Works as expected

5. Hide Exports 👁️

dev map --no-exports

• Result: Shows only structure and component counts, no export details
• Status: ✅ Clean output

6. Error Validation 🛡️

dev map --depth 10  # Invalid

• Error: "✖ Invalid depth - Depth must be between 1 and 5"
• Status: ✅ Clear error messages

7. Help Text 📖

dev map --help

• Content: Options, examples, use cases, emoji indicators
• Status: ✅ Comprehensive and helpful

---

🎯 Performance Verified

Operation	Time	Speedup
Before optimization	103+ seconds	-
Basic map (new)	0.46s	224x faster ⚡
With --change-frequency	2.2s	Git analysis adds ~1.7s (expected)
With --verbose	Same	Just adds logging output

---

🧪 Test Coverage

• ✅ All 1,918 tests passing
• ✅ Lint clean (Biome)
• ✅ TypeCheck passed
• ✅ Pre-commit hooks passed
• ✅ Mock updates for getAll() in test suites

---

📊 Sample Output

# Codebase Map

## Hot Paths (most referenced)
1. packages/core/src/scanner/typescript.ts - 257 refs
2. packages/core/src/scanner/go.ts - 115 refs
...

## Directory Structure

└── root/ (3733 components)
    ├── packages/ (2774 components) 🔥 100 commits this month
    │   ├── cli/ (146 components) 🔥 64 commits this month
    │   │   └── exports: Search, Explore, Update, Stats, Clean
    │   ├── core/ (950 components) 🔥 75 commits this month
    │   ├── mcp-server/ (887 components) 🔥 71 commits this month
    │   └── subagents/ (630 components) 🔥 71 commits this month
    ├── docs/ (42 components) 🔥 9 commits this month
    └── website/ (351 components) 🔥 27 commits this month

📊 Total: 3,733 components across 17 directories
🔥 5 hot paths identified

---

Ready for review and merge! 🚀