Mapify

A semantic codebase mapping engine for AI.

Mapify scans a project, parses the abstract syntax trees (ASTs) of its code, and produces a lightweight semantic knowledge graph — a machine-readable map of how files, classes, functions, API calls, routes, state, and database models are connected. Every node is ranked with PageRank, so Mapify can tell you which files architecturally matter most: the "God Nodes".

Feed that map to an LLM as plain JSON and your AI agents get precise, grounded context about how a codebase is wired together.

Features

• AST-grade parsing via tree-sitter, with regex fallbacks for SQL & Prisma
• Semantic graph — classes, functions, imports, API calls, route handlers, React state, and database reads/writes as typed nodes & relationships
• God Nodes — the most important files, ranked by PageRank
• Fast & safe — skips .gitignore-ignored and build directories automatically
• Four outputs — Blueprint, Symbol Table, Graph (JSON + GraphML), Summary
• Cross-platform — works on macOS, Linux, and Windows

Supported Languages

Missing grammars never crash Mapify — it simply skips languages that aren't installed (all grammars ship by default).

Installation

From PyPI

pip install mapifyy-cli

Or, for an isolated globally-available install:

pipx install mapifyy-cli

From source

git clone https://github.com/uditc0derr/mapifyy-cli
cd mapifyy-cli
python -m venv .venv && source .venv/bin/activate
pip install -e .

Quick Start

cd your-project-folder
mapify run .

This generates a mapify-out/ folder and prints a summary:

╭──────────────────────────────────────╮
│ Mapify Engine                       │
│ Target: /path/to/your-project       │
╰──────────────────────────────────────╯
✔ Discovered 128 valid files.
✔ Knowledge Graph generated successfully!
Saved to: /path/to/your-project/mapify-out
     God Nodes (most important files)
┏━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━┳━━━━━━━━┓
┃ # ┃ Node                   ┃ Type ┃  Score ┃
┡━━━╇━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━╇━━━━━━━━┩
│ 1 │ src/app/main.py        │ file │ 0.3667 │
│ 2 │ src/services/auth.py   │ file │ 0.2333 │
└───┴────────────────────────┴───────┴────────┘

The Score column is the node's PageRank value: how central a file is to your architecture. Higher is more important; the top-ranked files are your God Nodes. (If PageRank can't be computed, a degree-centrality fallback is used.)

CLI reference

# Map a whole directory
mapify run ./src

# Map a single file
mapify run ./src/main.py

# Custom output location (default: mapify-out/codebase_blueprint.json)
mapify run . --output artifacts/blueprint.json

# Change how many God Nodes are reported (default: 5)
mapify run . --god-nodes 10

# Show the version
mapify --version

Tips for better results

• Mapify always respects your .gitignore, plus a built-in denylist (.git/, node_modules/, .venv/, __pycache__/, dist/, build/, .next/, and more).
• mapify-out/ is excluded, so Mapify never maps its own output.
• No .gitignore present? Add one — it makes analysis dramatically cleaner.

Generated Outputs

mapify run writes everything into mapify-out/ (or the folder you pass to --output):

Node types & relationships

Node types: file, class, function, module, api, state, route, database_model.

Edges: contains, imports, calls, calls_api, uses_state, defines_route, reads, writes.

How It Works

1. Discover — walk the target directory, honoring .gitignore and the denylist.
2. Parse — extract symbols from each file with tree-sitter queries.
3. Resolve — link imports and calls between files (dotted and relative imports like ../utils/x).
4. Build — assemble the typed, directed graph with NetworkX.
5. Rank — run PageRank to compute the God Nodes.
6. Export — write the Blueprint, Symbol Table, Graph (JSON + GraphML), and Summary.

Project Structure

src/mapify/
├── cli.py          # Typer CLI (run / --version)
├── parser.py       # AST extraction (tree-sitter + regex fallbacks)
├── graph.py        # NetworkX semantic graph + PageRank God Nodes
├── symbols.py      # Global symbol registry & import resolution
├── resolver.py     # Cross-file import & call resolution
└── utils/
    └── file_ops.py # File discovery, .gitignore handling, hashing

Development

git clone https://github.com/uditc0derr/mapifyy-cli
cd mapifyy-cli
python -m venv .venv && source .venv/bin/activate
pip install -e .
mapify run . --output mapify-out/codebase_blueprint.json

Mapify maps itself — run the command above to inspect the outputs it produces about its own codebase.

Contributing

Pull requests are welcome. For significant changes, please open an issue first to discuss what you'd like to do.

License

MIT — see the project repository for details.