Codemapper

A powerful CLI tool that generates architectural "Code Maps" for PHP, JavaScript, and Python web projects. Analyze your codebase to create comprehensive documentation that helps developers and AI assistants understand project structure quickly.

🚀 Quick Start

1# Install globally via npm
2npm install -g @mikekilic/codemapper
3
4# Analyze your project
5codemapper scan
6
7# Analyze with specific options
8codemapper scan --php              # PHP files only
9codemapper scan --js               # JavaScript files only
10codemapper scan --python           # Python files only
11codemapper scan --format json      # JSON output
12codemapper scan --quiet            # Minimal output

📋 Features

• Multi-language Support: Analyzes PHP, JavaScript/TypeScript, and Python files
• Framework Detection: Recognizes Laravel, WordPress, React, Vue.js, Django, Flask patterns
• Dependency Mapping: Tracks imports, requires, and cross-language dependencies
• Multiple Output Formats: Markdown, JSON, and plain text
• Flexible Verbosity: From minimal architectural overview to detailed analysis
• Smart File Handling: Respects .gitignore, handles large codebases efficiently

📖 Commands

codemapper scan [path]

Analyze a project and generate code maps.

Options:

• --php - Analyze only PHP files
• --js - Analyze only JavaScript/TypeScript files
• --python - Analyze only Python files
• -f, --format <type> - Output format: md (default), json, plaintext
• --minimal - Architectural constants only (cleanest output)
• -q, --quiet - Core components only (classes, functions, exports)
• -v, --verbose - Detailed analysis with all components
• -d, --debug - Full debug output with parser internals

Examples:

1# Analyze current directory
2codemapper scan
3
4# Analyze specific directory
5codemapper scan ./src
6
7# PHP-only analysis with JSON output
8codemapper scan --php --format json
9
10# Minimal architectural overview
11codemapper scan --minimal

codemapper clean [path]

Remove generated files and caches.

1codemapper clean        # Clean current directory
2codemapper clean --all  # Remove all codemapper files

codemapper version

Display version and system information.

🎚️ Verbosity Levels

• --minimal: Only architectural constants (const declarations, ALL_CAPS variables)
• -q, --quiet: Core components (classes, functions, const/let variables)
• Default: All components and variables
• -v, --verbose: Detailed output including all variables
• -d, --debug: Everything including parser debug information

📁 Output

Files are generated in .codemapper/output/ with smart naming:

• codemap.md - All languages analyzed
• codemap-php.md - PHP-only analysis
• codemap-js.md - JavaScript-only analysis
• codemap.json - JSON format output

🔧 Configuration

Codemapper works out of the box with sensible defaults. For advanced configuration, it will use .codemapper/config.json if present:

1{
2  "analysis": {
3    "languages": {
4      "php": { "enabled": true },
5      "javascript": { "enabled": true },
6      "python": { "enabled": true }
7    }
8  },
9  "output": {
10    "destination": "./.codemapper/output",
11    "formats": [{ "type": "markdown", "enabled": true }]
12  }
13}

📊 What Gets Analyzed

PHP

• Classes, interfaces, traits with full method signatures
• Functions with parameters and return types
• Properties with types and default values
• Constants (class and global)
• Namespaces and use statements
• Include/require dependencies

JavaScript/TypeScript

• Functions (named, arrow, async)
• Classes with methods and properties
• ES6 modules (imports/exports)
• React components
• Constants and variables (filtered by verbosity)
• CommonJS requires

Python

• Classes with methods and inheritance
• Functions with type hints and decorators
• Async functions and generators
• Module imports (import, from...import)
• Constants and variables
• Docstrings and type annotations

🔄 Updating CodeMapper

When updating to a new version, it's important to properly uninstall the old version first to avoid conflicts:

1# Method 1: Clean update (Recommended)
2npm uninstall -g codemapper
3npm install -g @mikekilic/codemapper
4
5# Method 2: Force reinstall
6npm install -g @mikekilic/codemapper --force
7
8# Verify the update
9codemapper --version

Common Update Issues

If you experience issues after updating:

1. Old version still running: The global npm cache may be holding the old version

   1# Clear npm cache and reinstall
   2npm cache clean --force
   3npm uninstall -g codemapper
   4npm install -g @mikekilic/codemapper

2. Permission errors: On macOS/Linux, you may need to use sudo

   1sudo npm uninstall -g codemapper
   2sudo npm install -g @mikekilic/codemapper

3. Multiple Node versions: If using nvm or similar, ensure you're in the correct Node environment

   1which codemapper  # Check installation location
   2npm list -g codemapper  # Verify global installation

🛠️ Development

1# Clone and install
2git clone <repository>
3cd codemapper
4npm install
5
6# Build
7npm run build
8
9# Link for development
10npm link
11
12# Run tests
13npm test

📝 License

MIT License - see LICENSE file for details.

---

Generated by Codemapper v2.5.1 - Understanding your codebase architecture