npm package: @mikekilic/codemapper
Description: Extensible architectural code mapper with plugin support for multiple languages
Author: Code Map Generator
Latest version: 2.9.2

# 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

```bash
# 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:**
```bash
# 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.

```bash
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:

```json
{
  "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:

```bash
# 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
   ```bash
   # 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
   ```bash
   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
   ```bash
   which codemapper  # Check installation location
   npm list -g codemapper  # Verify global installation
   ```

## 🛠️ Development

```bash
# 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