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

# Install globally via npm
npm install -g @mikekilic/codemapper

# Analyze your project
codemapper scan

# Analyze with specific options
codemapper scan --php              # PHP files only
codemapper scan --js               # JavaScript files only
codemapper scan --python           # Python files only
codemapper scan --format json      # JSON output
codemapper 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:

# Analyze current directory
codemapper scan

# Analyze specific directory
codemapper scan ./src

# PHP-only analysis with JSON output
codemapper scan --php --format json

# Minimal architectural overview
codemapper scan --minimal

codemapper clean [path]

Remove generated files and caches.

codemapper clean        # Clean current directory
codemapper 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:

{
  "analysis": {
    "languages": {
      "php": { "enabled": true },
      "javascript": { "enabled": true },
      "python": { "enabled": true }
    }
  },
  "output": {
    "destination": "./.codemapper/output",
    "formats": [{ "type": "markdown", "enabled": true }]
  }
}

📊 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:

# Method 1: Clean update (Recommended)
npm uninstall -g codemapper
npm install -g @mikekilic/codemapper

# Method 2: Force reinstall
npm install -g @mikekilic/codemapper --force

# Verify the update
codemapper --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

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

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

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

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

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

🛠️ Development

# Clone and install
git clone <repository>
cd codemapper
npm install

# Build
npm run build

# Link for development
npm link

# Run tests
npm test

📝 License

MIT License - see LICENSE file for details.

Generated by Codemapper v2.5.1 - Understanding your codebase architecture