Metadata-Version: 2.5
Name: mapifyy-cli
Version: 1.0.0
Summary: AI coding assistant memory layer & semantic graph generator
Project-URL: Homepage, https://github.com/uditc0derr/mapifyy-cli
Author-email: uditcoderrr <uditcoderr@gmail.com>
Requires-Python: >=3.10
Requires-Dist: networkx
Requires-Dist: pathspec
Requires-Dist: rich
Requires-Dist: tree-sitter
Requires-Dist: tree-sitter-c
Requires-Dist: tree-sitter-cpp
Requires-Dist: tree-sitter-go
Requires-Dist: tree-sitter-java
Requires-Dist: tree-sitter-javascript
Requires-Dist: tree-sitter-python
Requires-Dist: tree-sitter-ruby
Requires-Dist: tree-sitter-rust
Requires-Dist: tree-sitter-typescript
Requires-Dist: typer
Description-Content-Type: text/markdown

# 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

| Language      | Extensions                | Parser     |
|---------------|---------------------------|------------|
| Python        | `.py`                     | tree-sitter|
| TypeScript    | `.ts`, `.tsx`             | tree-sitter|
| JavaScript    | `.js`, `.jsx`             | tree-sitter|
| Go            | `.go`                     | tree-sitter|
| Rust          | `.rs`                     | tree-sitter|
| Java          | `.java`                   | tree-sitter|
| C / C++       | `.c`, `.h`, `.cpp`, `.hpp`| tree-sitter|
| Ruby          | `.rb`                     | tree-sitter|
| SQL           | `.sql`                    | regex      |
| Prisma        | `.prisma`                 | regex      |

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

## Installation

### From PyPI

```bash
pip install mapifyy-cli
```

Or, for an isolated globally-available install:

```bash
pipx install mapifyy-cli
```

### From source

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

## Quick Start

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

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

| File                      | Contents |
|---------------------------|----------|
| `codebase_blueprint.json` | Per-file AST extract: classes, functions, imports, calls, API calls, states, routes, DB reads/writes, hash, size |
| `symbol_table.json`       | Global registry of every function, class, module, route, and model |
| `semantic_graph.json`     | NetworkX node-link graph. Edges: `imports`, `calls`, `calls_api`, `uses_state`, `defines_route`, `reads`, `writes`, `contains` |
| `semantic_graph.graphml`  | The same graph in GraphML — open it in Gephi, yEd, or Cytoscape |
| `summary.json`            | Stats, node breakdown, execution summary, and the top God Nodes |

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

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