Metadata-Version: 2.4
Name: projetmap
Version: 1.0.1
Summary: Knowledge graph generator for codebases — scan, analyze, and understand any project
Author: Akinseye Akin-Oyewole
License: MIT
Project-URL: Homepage, https://github.com/360integree/projetmap
Project-URL: Repository, https://github.com/360integree/projetmap
Project-URL: Issues, https://github.com/360integree/projetmap/issues
Keywords: codebase,knowledge-graph,static-analysis,dead-code,architecture
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: networkx>=3.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: full
Requires-Dist: leidenalg>=0.10.0; extra == "full"
Requires-Dist: mcp>=1.0.0; extra == "full"
Provides-Extra: mcp
Requires-Dist: mcp>=1.0.0; extra == "mcp"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: ruff>=0.4.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Dynamic: license-file

# 🗺️ Projetmap

**Knowledge graph generator for codebases.**

[![PyPI version](https://badge.fury.io/py/projetmap.svg)](https://pypi.org/project/projetmap/)
[![Tests](https://github.com/360integree/projetmap/actions/workflows/tests.yml/badge.svg)](https://github.com/360integree/projetmap/actions/workflows/tests.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)

Turns any folder of code, docs, and configs into a queryable knowledge graph. Understand your codebase structure, dependencies, dead code, state mutations, and architectural patterns — all from a single CLI command.

## Quick Start

### Install from PyPI

```bash
pip install projetmap
```

### Or install from source

```bash
git clone https://github.com/360integree/projetmap.git
cd projetmap
pip install -e ".[full]"
```

### Scan a project

```bash
# Basic structural analysis
projetmap /path/to/your/project

# Or with Python module syntax
python -m projetmap /path/to/your/project

# With behavioral analysis (dead code, state flow, call graphs)
projetmap /path/to/your/project --behavioral
```

## What It Does

| Capability | Description |
|-----------|-------------|
| **Structural Analysis** | Extracts classes, functions, imports, and relationships from source code |
| **Community Detection** | Identifies logical clusters using Leiden modularity + path-based fallback |
| **Dead Code Detection** | BFS reachability from entry points — finds unreachable functions |
| **State Mutation Hotspots** | Classes with the most state changes (risk assessment) |
| **Listener Health** | Detects unpaired add/remove listeners (memory leak signals) |
| **Hot Path Analysis** | Most-called functions via call graph in-degree |
| **Instruction Analysis** | Detects redundancies, scope conflicts, and semantic duplicates in prompt files |
| **Runtime Comprehension** | Entry points, config surface, test coverage, convention detection |
| **God Node Detection** | Identifies overly-connected modules (architectural bottlenecks) |
| **Interactive HTML** | vis.js graph with clusters, search, drill-down, and dark theme |

## Supported Languages

- **Dart/Flutter** — Full behavioral analysis (AST-based)
- **Python** — Structural extraction + behavioral (extensible)
- **JavaScript/TypeScript** — Structural extraction + behavioral (extensible)
- **Any language** — Generic regex-based extraction as fallback

## CLI Reference

```bash
projetmap <path>                    # Full pipeline
projetmap <path> --refresh          # Force re-scan (ignore cache)
projetmap <path> --behavioral       # Include behavioral analysis
projetmap <path> --report           # Output only the Markdown report
projetmap <path> --json             # Output only graph.json
projetmap <path> --html             # Output only interactive HTML
projetmap <path> --mermaid          # Output only Mermaid diagram
projetmap <path> --query <entity>   # Query a specific entity
projetmap <path> --path A B         # Find path between entities
projetmap <path> --analyze-prompts  # Analyze instruction files
projetmap <path> --runtime-analysis # Runtime comprehension
projetmap <path> --scan-dirs lib    # Scan specific directories
projetmap <path> --ignore dist build  # Ignore patterns
```

## Output

Results are saved to `.projetmap/` in the target directory:

```
.projetmap/
├── graph.json                  # Full knowledge graph
├── GRAPH_REPORT.md             # Human-readable report
├── graph.html                  # Interactive vis.js visualization
├── graph.mermaid               # Mermaid diagram
├── behavioral_analysis.json    # Dead code, state mutations, listeners
├── runtime_analysis.json       # Entry points, config, tests, conventions
├── instruction_analysis.json   # Prompt/instruction redundancies
└── cache/
    └── file_hashes.json        # SHA256 hashes for incremental updates
```

## Architecture

```
projetmap/
├── core/               # Graph building, community detection, caching
├── extractors/         # Structural extractors (per-language, regex-based)
├── behavioral/         # Behavioral analysis layer
│   ├── extractors/     # Pluggable per-language AST extractors
│   │   ├── dart/       # Dart AST extractor (uses analyzer package)
│   │   └── (future: python/, js/)
│   ├── call_graph.py   # Dead code, hot paths (language-agnostic)
│   └── state_flow.py   # Mutation hotspots, listener health
├── exporters/          # JSON, Markdown, HTML, Mermaid output
├── analyzers/          # Runtime analysis (entry points, config, tests, conventions)
└── instructions/       # Instruction/prompt redundancy analysis
```

## Adding a Language Extractor

See `projetmap/behavioral/SCHEMA.md` for the full contract.

1. Create `projetmap/behavioral/extractors/<language>/`
2. Write an extractor that outputs `behavioral_data.json` matching the schema
3. Register it in `projetmap/behavioral/extractors/__init__.py`:
   ```python
   DETECTORS["python"] = (_detect_python, _run_python_extractor)
   ```

The Python analyzers (`call_graph.py`, `state_flow.py`) work automatically with any language's output.

## MCP Server (IDE Integration)

Projetmap includes an MCP server that AI agents in IDEs can call natively.

```bash
# Start the MCP server
projetmap mcp
```

### Auto-Install MCP Config

```bash
# Auto-detect IDE and install MCP config
projetmap --install-mcp

# Or specify IDE explicitly
projetmap --install-mcp cursor
projetmap --install-mcp claude
projetmap --install-mcp windsurf
projetmap --install-mcp zcode
```

### Uninstall MCP Config

```bash
projetmap --uninstall-mcp
# Or: projetmap --uninstall-mcp claude
```

## ZCode Skill (AI Agent Integration)

Projetmap includes a skill for ZCode and other AI agent platforms.

### Install Skill (after pip install)

```bash
projetmap --install-skill
```

This copies the skill files to `~/.agents/skills/projetmap/` for use with ZCode.

### Usage in ZCode

```
/projetmap /path/to/project           # Scan project
/projetmap /path/to/project --journeys # Scan with user journeys
```

### Alternative: Manual Installation

```bash
git clone https://github.com/360integree/projetmap.git ~/.agents/skills/projetmap
chmod +x ~/.agents/skills/projetmap/bin/projetmap
```

### Uninstall Skill

```bash
projetmap --uninstall-skill
```

This removes the skill files from `~/.agents/skills/projetmap/`.

### Manual Configuration (if needed)

Add to your IDE's MCP config file:
```json
{
  "mcpServers": {
    "projetmap": {
      "command": "/path/to/python",
      "args": ["-m", "projetmap", "mcp"],
      "env": {
        "PYTHONPATH": "/path/to/projetmap"
      }
    }
  }
}
```

> Config file locations: Cursor (`~/.cursor/mcp.json`), Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json`), Windsurf (`~/.codeium/windsurf/mcp.json`), ZCode (`~/.zcode/mcp.json`)

### MCP Tools

| Tool | Description |
|------|-------------|
| `projetmap_scan` | Scan a project and build the knowledge graph |
| `projetmap_report` | Get the full Markdown report |
| `projetmap_query` | Query an entity by name (details + relationships) |
| `projetmap_path` | Find dependency path between two entities |
| `projetmap_dead_code` | List dead code (unreachable functions) |
| `projetmap_hotspots` | State mutation hotspots (risk assessment) |
| `projetmap_listeners` | Unpaired listener warnings (memory leaks) |
| `projetmap_god_nodes` | Most-connected modules (architectural bottlenecks) |

## Development

See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.

### Quick Start (Development)

```bash
git clone https://github.com/360integree/projetmap.git
cd projetmap
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev,full]"
pytest
```

## Dependencies

- Python 3.10+
- networkx ≥ 3.0
- pyyaml ≥ 6.0
- leidenalg ≥ 0.10.0 (optional, falls back to greedy modularity)
- mcp ≥ 1.0.0 (for MCP server / IDE integration)
- Dart SDK (only for Dart behavioral analysis)

## Uninstall

### Full uninstall (recommended)

```bash
projetmap --uninstall
```

Removes skill files, MCP configs from all IDEs, and prompts to pip uninstall.

### Partial uninstall

```bash
projetmap --uninstall-skill     # Remove skill files only
projetmap --uninstall-mcp       # Remove MCP config only
pip uninstall projetmap         # Remove package only
```

### Remove output files

Delete the `.projetmap/` directory in any scanned project:

```bash
rm -rf .projetmap/
```

## License

MIT — see [LICENSE](LICENSE) for details.
