Metadata-Version: 2.4
Name: gapmap-ai
Version: 0.1.0
Summary: Find the riskiest undocumented code in your repository and draft the missing ADRs.
Author: Utkrisht12
License-Expression: MIT
Project-URL: Homepage, https://github.com/Utkrisht12/GapMaP
Project-URL: Repository, https://github.com/Utkrisht12/GapMaP
Project-URL: Issues, https://github.com/Utkrisht12/GapMaP/issues
Project-URL: Documentation, https://github.com/Utkrisht12/GapMaP#readme
Keywords: documentation,static-analysis,python,adr,technical-debt
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
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 :: Documentation
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.12
Requires-Dist: rich>=13.0
Requires-Dist: networkx>=3.0
Requires-Dist: tree-sitter>=0.22
Requires-Dist: tree-sitter-python>=0.23
Requires-Dist: numpy<2.0,>=1.24
Provides-Extra: vector
Requires-Dist: sentence-transformers<3.0,>=2.7.0; extra == "vector"
Requires-Dist: faiss-cpu<2.0,>=1.7.4; extra == "vector"
Provides-Extra: llm
Requires-Dist: openai<2.0,>=1.30; extra == "llm"
Provides-Extra: dev
Requires-Dist: pytest<9.0,>=8.0; extra == "dev"
Provides-Extra: all
Requires-Dist: sentence-transformers<3.0,>=2.7.0; extra == "all"
Requires-Dist: faiss-cpu<2.0,>=1.7.4; extra == "all"
Requires-Dist: openai<2.0,>=1.30; extra == "all"
Requires-Dist: pytest<9.0,>=8.0; extra == "all"
Dynamic: license-file

# GapMap

Find the riskiest undocumented code in a **Python** repository, draft missing
Architecture Decision Records, and answer questions about the codebase with
grounded, cited retrieval.

| Component | Path | What it does |
|-----------|------|--------------|
| **GapMap CLI** | `gapmap/` | Entity call graph, documentation-debt scoring, ADR drafting |
| **RAG pipeline** | `gapmap/src/`, `main.py` | Semantic search and grounded Q&A over repo text |
| **Dashboard** | `dashboard/` | Next.js UI over `.gapmap/audit.json` |

## Table of contents

- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Run on any Python repo](#run-on-any-python-repo)
- [GapMap CLI](#gapmap-cli)
- [Documentation automation](#documentation-automation)
- [Risk dashboard](#risk-dashboard)
- [Semantic search and Q&A](#semantic-search-and-qa)
- [Configuration](#configuration)
- [CI workflows](#ci-workflows)
- [Development](#development)
- [Architecture](#architecture)

## Prerequisites

| Requirement | Needed for |
|-------------|------------|
| **Python 3.10+** | All commands |
| **Git** (recommended) | `git blame` risk signals, ownership, trend history |
| **Node.js 18+ & npm** | `gapmap dashboard` only (not required for audit/CLI) |
| **OPENAI_API_KEY** (optional) | LLM-polished ADRs and Q&A (`pip install "gapmap-ai[llm]"`) |

GapMap analyzes **Python repos only** today. Point `--repo` at the root of the
project you want to scan (where your `.py` files live).

## Installation

### Option A — PyPI or uvx (recommended for users)

No clone required. Installs the CLI only (dashboard still needs Option C).

```bash
# Zero-install — runs in a temporary env (requires uv: https://docs.astral.sh/uv/)
uvx gapmap-ai audit --repo /path/to/your/project

# Or install permanently
pip install gapmap-ai
gapmap audit --repo /path/to/your/project

# Full features (vector search + LLM + tests)
pip install "gapmap-ai[all]"
```

Extras: `pip install "gapmap-ai[vector]"` or `"gapmap-ai[llm]"`.

### Option B — Clone and install (contributors / dashboard)

```bash
git clone https://github.com/Utkrisht12/GapMaP.git
cd GapMaP

python3 -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate

pip install -e ".[all]"
```

`[all]` installs the CLI, vector search (FAISS), LLM support, and pytest. For a
minimal audit-only install:

```bash
pip install -e .
```

### Option C — Install from Git without cloning (CLI only)

```bash
pip install "gapmap-ai[all] @ git+https://github.com/Utkrisht12/GapMaP.git"
```

The dashboard still requires a full clone (Option B) because `gapmap dashboard`
runs the Next.js app from the `dashboard/` directory in this repo.

### Verify

```bash
gapmap --help
# or
gapmap-ai --help
```

## Run on any Python repo

Replace `/path/to/your/project` with the repository you want to audit.

```bash
# 1. Scan structure and call-graph quality
gapmap parse --repo /path/to/your/project

# 2. Top undocumented risks (writes .gapmap/audit.json)
gapmap audit --repo /path/to/your/project

# 3. Explain why a specific entity is risky
gapmap ask route_payment "why is this risky?" --repo /path/to/your/project

# 4. Draft a node profile for the top gap (or a named entity)
gapmap generate --repo /path/to/your/project

# 5. Optional — open the risk dashboard (requires Node.js + repo clone)
gapmap dashboard --repo /path/to/your/project
# → http://localhost:3000
```

**Audit this repo** after install:

```bash
gapmap audit --repo .
gapmap dashboard --repo .
```

GapMap works fully offline for audit, parse, generate, stale, ownership, and
trend. Vector search and LLM polish need the optional extras (`[vector]`,
`[llm]`).

## GapMap CLI

GapMap parses every Python file with tree-sitter, builds an **entity-level call
graph** (NetworkX), scores each entity with weighted incoming callers × LOC × a
temporal git factor, checks which risky entities are missing from docs and
docstrings, and turns the result into audits, explanations, ADR drafts, and an
HTML report.

### All commands

| Command | Purpose |
|---------|---------|
| `gapmap parse` | Files, LOC, imports, graph resolution breakdown |
| `gapmap audit` | Top undocumented high-risk entities |
| `gapmap ask` | Graph-grounded explanation for one entity |
| `gapmap generate` | Draft node profile(s) under `docs/adr/` |
| `gapmap report` | Self-contained HTML report |
| `gapmap dashboard` | Interactive risk UI |
| `gapmap stale` | Find generated docs drifted from source |
| `gapmap ownership` | Knowledge-debt ownership and bus-factor |
| `gapmap trend` | Documentation coverage over time |
| `gapmap autodoc` | Batch-document new critical hubs (CI / auto-PR) |

Common flags: `--repo PATH` (default: `.`), `--refresh` (ignore `.gapmap_cache`).

### Example session

```bash
export REPO=/path/to/your/project

gapmap parse --repo "$REPO"
gapmap audit --repo "$REPO" --top 15
gapmap ask payment_router.py "why is this risky?" --repo "$REPO"
gapmap generate route_payment --repo "$REPO"
gapmap report --repo "$REPO" -o gapmap-report.html
```

### What makes the graph accurate

- **Import-aware call resolution.** `from auth import Handler` resolves to the
  imported entity, not every same-named class. Edges carry `confidence` and
  `resolution` (symbol, qualified, same-file, import, ambiguous).
- **Smarter documentation detection.** `MCPClient` matches "MCP client";
  single-word names stay strict to avoid false positives.
- **Temporal risk from git history.** Author churn and bus-factor signals from
  `git blame` amplify volatile or single-owner hotspots.

## Documentation automation

```bash
export REPO=/path/to/your/project

# Batch-document gaps
gapmap generate --all-critical --repo "$REPO"
gapmap generate --top 10 --repo "$REPO"
gapmap generate --min-score 300 --repo "$REPO"

# Drift detection (exits non-zero in CI when stale docs exist)
gapmap stale --repo "$REPO"
gapmap stale --fix --repo "$REPO"

gapmap ownership --repo "$REPO"
gapmap trend --repo "$REPO"
gapmap autodoc --regenerate-stale --repo "$REPO"
```

Generated docs embed a `Source-Hash` fingerprint so `gapmap stale` knows when
code has drifted away from its documentation.

## Risk dashboard

Requires **Node.js**, a **clone of this repo**, and an audit JSON file.

```bash
# From the GapMap repo root, after pip install -e ".[all]"
gapmap audit --repo /path/to/your/project
gapmap dashboard --repo /path/to/your/project --port 3000
```

Opens http://localhost:3000 with risk scores, call graph, coverage trends, stale
docs, ownership, and graph-quality metrics from `.gapmap/audit.json`.

**UI-only** (mock data, no audit):

```bash
cd dashboard
npm install    # first time only
NEXT_PUBLIC_GAPMAP_USE_MOCK=true npm run dev
```

See [`dashboard/README.md`](dashboard/README.md) for component details.

## Semantic search and Q&A

Separate from `gapmap ask`: `main.py` runs repo-wide semantic retrieval (not
entity-specific). Requires `[vector]` extra.

```bash
pip install -e ".[vector]"   # or .[all]

python main.py --repo /path/to/your/project -v
python main.py --repo /path/to/your/project --query "How does caching work?"
python main.py --repo /path/to/your/project --ask "How does caching work?"
python main.py --repo /path/to/your/project --interactive
python main.py --repo /path/to/your/project --save .cache/gapmap-index
```

| | `gapmap ask` | `main.py --query` | `main.py --ask` |
|---|--------------|-------------------|-----------------|
| **Scope** | One entity | Whole repo | Whole repo |
| **Output** | Risk explanation | Raw chunks + scores | Synthesized answer + citations |
| **Context** | Call graph + risk + optional vectors | Vectors only | Vectors + synthesis |

Without `openai` or an API key, synthesis falls back to a deterministic
extractive engine (works offline).

```bash
pip install -e ".[llm]"
export OPENAI_API_KEY=sk-...
python main.py --repo . --ask "How does staleness detection work?"
```

## Configuration

Copy [`.gapmap.toml.example`](.gapmap.toml.example) to `.gapmap.toml` in the
**target repo** you are auditing:

```toml
[policy]
critical_threshold = 500
auto_document = true
regenerate_when_stale = true

[docs]
output_dir = "docs/adr"
min_score = 100

[ownership]
departed_contributors = ["alice", "bob@corp.com"]
```

### Optional dependencies

```bash
pip install "gapmap-ai[vector]"   # RAG
pip install "gapmap-ai[llm]"      # LLM polish
pip install "gapmap-ai[all]"      # full install
pip install -e ".[all]"           # from source (contributors)
```

| Extra | Enables |
|-------|---------|
| `vector` | RAG indexing and search (`sentence-transformers`, `faiss-cpu`) |
| `llm` | LLM-backed ADR polish and Q&A (`openai`) |
| `dev` | Test suite (`pytest`) |
| `all` | Everything above |

## CI workflows

| Workflow | Purpose | Trigger |
|----------|---------|---------|
| [`gapmap-sentinel.yml`](.github/workflows/gapmap-sentinel.yml) | Fail on new critical undocumented hubs | Manual only |
| [`gapmap-autodoc.yml`](.github/workflows/gapmap-autodoc.yml) | Open a PR with drafted ADRs | Manual only |

Both use `workflow_dispatch` while the project is under construction. Uncomment
`push` / `pull_request` in each file when ready.

```bash
gapmap audit --repo . --json-export report.json
```

Writes CI export JSON; `.gapmap/audit.json` is always updated for the dashboard.

## Development

```bash
git clone https://github.com/Utkrisht12/GapMaP.git && cd GapMaP
pip install -e ".[all]"
pytest
```

Tests use a deterministic fake encoder — no network or model downloads.

### Project layout

```
.
├── gapmap/                 CLI and analysis engine
├── dashboard/              Next.js risk dashboard
├── docs/                   ARCHITECTURE.md, generated ADRs
├── tests/                  pytest suite
├── main.py                 RAG pipeline entry point
└── .gapmap.toml.example    policy template
```

## Publishing to PyPI

Package name on PyPI: **`gapmap-ai`** (console commands: `gapmap` and `gapmap-ai`).

```bash
pip install build twine
python -m build

# Optional dry run on TestPyPI
twine upload --repository testpypi dist/*

# Production (username is always __token__)
export TWINE_USERNAME=__token__
export TWINE_PASSWORD='pypi-...'   # your API token — never commit this
twine upload dist/*
```

After publish, users can run:

```bash
uvx gapmap-ai audit --repo /path/to/your/project
pip install gapmap-ai && gapmap audit --repo /path/to/your/project
```

## Architecture

Module-level diagrams, data flow, and CI details:
[`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md).
