gapmap-ai 0.1.0

Find the riskiest undocumented code in your repository and draft the missing ADRs.

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
• Installation
• Run on any Python repo
• GapMap CLI
• Documentation automation
• Risk dashboard
• Semantic search and Q&A
• Configuration
• CI workflows
• Development
• 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).

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

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:

pip install -e .

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

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

gapmap --help
# or
gapmap-ai --help

Run on any Python repo

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

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

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

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

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.

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

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

See 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.

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).

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

Configuration

Copy .gapmap.toml.example to .gapmap.toml in the target repo you are auditing:

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

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

[ownership]
departed_contributors = ["alice", "[e-mail]"]

Optional dependencies

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	Fail on new critical undocumented hubs	Manual only
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.

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

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

Development

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).

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:

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.