projetmap 1.0.0

Knowledge graph generator for codebases — scan, analyze, and understand any project

🗺️ Projetmap

Knowledge graph generator for codebases.

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

pip install projetmap

Or install from source

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

Scan a project

# 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

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:

   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.

# Start the MCP server
projetmap mcp

Auto-Install MCP Config

# 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

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)

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

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

Uninstall Skill

projetmap --uninstall-skill

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

Manual Configuration (if needed)

Add to your IDE's MCP config file:

{
  "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 for development setup and guidelines.

Quick Start (Development)

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)

projetmap --uninstall

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

Partial uninstall

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:

rm -rf .projetmap/

License

MIT — see LICENSE for details.