# CodeKnowledgeMapper — AI-Agent-First Codebase Blueprint Tool

Give AI agents a map before they read your code.

CodeKnowledgeMapper statically analyzes any Python codebase and produces a structured blueprint — a portable JSON graph of every module, class, function, and method, along with their signatures, dependencies, and who calls whom.

AI agents read this blueprint before touching source files, enabling them to:

• Know exactly which file/component to look at for any task
• Understand the full impact of a proposed change before making it
• See the complete dependency chain without reading 5–10 files first
• Make more accurate, context-aware decisions with fewer tokens

---

Quick Start

# Install
pip install -e /path/to/codeknowledge-mapper

# Scan your project (run from project root or pass a path)
codeknowledge-mapper scan .

# Output:
#   .codeknowledge-mapper/codeknowledge_mapper.blueprint.json  ← full component graph
#   .codeknowledge-mapper/codeknowledge_mapper.summary.json    ← compact AI-optimized index

---

CLI Commands

scan — Analyze a project

codeknowledge-mapper scan /path/to/project
codeknowledge-mapper scan . --output ./docs/blueprint
codeknowledge-mapper scan . --no-tests                  # skip test files
codeknowledge-mapper scan . --skip "**/migrations/**"   # custom exclusions

show — Inspect a specific component

codeknowledge-mapper show myapp.utils.helpers.format_date

Output: full JSON node including signature, file location, line numbers, docstring, calls list, called_by list.

impact — Impact analysis before a change

codeknowledge-mapper impact myapp.utils.helpers.format_date --depth 3

Shows all callers up to N levels deep. Use this before modifying any component.

deps — Dependency lookup

codeknowledge-mapper deps myapp.models.user.UserService

Shows everything UserService depends on — calls, inherits.

ingest — Pull external context from Jira, Git, and Confluence

pip install 'codeknowledgeMapper[ingest]'

# Set credentials (Jira)
export JIRA_USER="your.email@company.com"
export JIRA_TOKEN="your_jira_api_token"

# Run all enabled ingesters
codeknowledge-mapper ingest .

# Run only a specific ingester
codeknowledge-mapper ingest . --source git
codeknowledge-mapper ingest . --source jira

# Validate connectivity without writing files
codeknowledge-mapper ingest . --dry-run

Fetches Jira tickets, Confluence pages, and Git commit history, then writes structured JSON files (ingest_jira.json, ingest_git.json, etc.) to the output directory.

When you run scan after ingest, the Context Linker automatically maps ticket keys to code nodes via Git commit file paths — giving each component its business context (e.g., "PROJ-123: Implement login flow").

enrich — AI-powered summaries (optional)

export GEMINI_API_KEY=your_key_here
pip install 'codeknowledgeMapper[enrich]'
codeknowledge-mapper enrich .

# Use a different provider
codeknowledge-mapper enrich . --provider openai --model gpt-4o
codeknowledge-mapper enrich . --provider claude --api-key $ANTHROPIC_API_KEY

Adds plain-English summaries to every node explaining what it does, how, and why. If you ran ingest before scan, the AI prompt includes linked Jira ticket context for richer, business-aware summaries.

---

Output Format

codeknowledge_mapper.blueprint.json

The authoritative, complete graph. Use for deep component lookup.

{
  "meta": { "total_files": 12, "total_nodes": 147, ... },
  "files": { "src/utils/helpers.py": { ... } },
  "nodes": {
    "src.utils.helpers.format_date": {
      "kind": "function",
      "signature": "format_date(date: datetime, fmt: str = '%Y-%m-%d') -> str",
      "file": "src/utils/helpers.py",
      "line_start": 24,
      "docstring": "Formats a datetime object into a string.",
      "calls": ["datetime.strftime"],
      "called_by": ["src.api.views.get_user_profile"],
      "related_tickets": ["PROJ-42: Standardise date formatting across API"]
    }
  },
  "tree": { "id": "root", "kind": "root", "children": [ ... ] },
  "edges": [
    { "from": "src.api.views.get_user_profile", "to": "src.utils.helpers.format_date", "kind": "calls" }
  ]
}

codeknowledge_mapper.summary.json

Ultra-compact index. An AI agent reads this first to orient itself.

{
  "meta": { "total_files": 12, "total_nodes": 147, ... },
  "index": [
    {
      "id": "src.utils.helpers",
      "kind": "module",
      "file": "src/utils/helpers.py",
      "exports": ["format_date", "parse_date", "validate_email"],
      "depends_on": ["myapp.config"],
      "depended_on_by": ["src.api.views", "src.models.user"]
    },
    {
      "id": "src.utils.helpers.format_date",
      "kind": "function",
      "signature": "format_date(date: datetime, fmt: str = '%Y-%m-%d') -> str",
      "called_by_count": 3
    }
  ]
}

---

How AI Agents Should Use CodeKnowledgeMapper

Recommended workflow for any coding task:

1. Read codeknowledge_mapper.summary.json — orient yourself in 1–2k tokens. Find relevant modules.
2. Run codeknowledge-mapper show <node_id> — get full details for specific components.
3. Run codeknowledge-mapper impact <node_id> before any change — understand the blast radius.
4. Only then read the actual source files — now you know exactly which ones matter.

---

Configuration

Create a codeknowledge_mapper.config.toml in your project root (optional):

# Core scan settings
output_dir = "projectData"
include_tests = true
skip_patterns = [
    "**/migrations/**",
    "**/*.pb.py",
]

# AI provider for enrichment
[ai]
provider = "gemini"            # gemini, openai, or claude
model = "gemini-1.5-flash"     # model name (uses provider default if omitted)

# Git commit log ingester
[ingesters.git]
enabled = true
repo_path = "."
ticket_pattern = '([A-Z]+-\d+)'   # regex to extract ticket keys from commit messages

# Jira ticket ingester
[ingesters.jira]
enabled = true
url = "https://jira.yourdomain.com"
project = "MYPROJ"
jql_query = "project=MYPROJ AND issuetype in (Story, Bug, Task) AND created >= -365d"
ticket_pattern = '([A-Z]+-\d+)'

# Confluence page ingester
[ingesters.confluence]
enabled = false
url = "https://confluence.yourdomain.com"
spaces = ["ENG", "DOCS"]
max_pages_per_space = 300

Environment Variables

Variable	Used By	Description
GEMINI_API_KEY	enrich (Gemini)	Google Gemini API key
OPENAI_API_KEY	enrich (OpenAI)	OpenAI API key
ANTHROPIC_API_KEY	enrich (Claude)	Anthropic API key
JIRA_USER	ingest --source jira	Jira username or email
JIRA_TOKEN	ingest --source jira	Jira API token
CONFLUENCE_USER	ingest --source confluence	Confluence username or email
CONFLUENCE_TOKEN	ingest --source confluence	Confluence API token

---

Development

# Install dev dependencies
pip install -e ".[dev]"

# Run all tests
pytest

# With coverage
pytest --cov=codeknowledge-mapper --cov-report=term-missing

# Lint
ruff check codeknowledge-mapper/

---

Architecture

codeknowledge_mapper/
├── scanner.py          # File discovery (respects skip rules)
├── config.py           # TOML config loader with defaults
├── runner.py           # Orchestration: scanner → parsers → graph → linker → exporters
├── parsers/
│   ├── base.py         # Abstract BaseParser interface
│   └── python_parser.py # Python AST parser (stdlib ast, no external deps)
├── graph/
│   ├── builder.py      # Assembles CodeGraph (nodes + tree + edges)
│   ├── resolver.py     # Cross-file call/import resolution + called_by index
│   ├── linker.py       # Maps Jira/Git data onto graph nodes (related_tickets)
│   └── enricher.py     # AI summary enrichment (Gemini / OpenAI / Claude)
├── providers/
│   ├── base.py         # Abstract AIProvider interface
│   ├── gemini.py       # Google Gemini provider
│   ├── openai_provider.py # OpenAI provider
│   ├── claude.py       # Anthropic Claude provider
│   └── factory.py      # Provider factory (selects by config)
├── ingesters/
│   ├── base.py         # Abstract BaseIngester interface
│   ├── jira.py         # Jira ticket ingester
│   ├── confluence.py   # Confluence page ingester
│   ├── git_mapper.py   # Git commit log → ticket mapping
│   └── orchestrator.py # Runs all enabled ingesters
├── models/
│   └── schema.py       # Pydantic v2 models (CodeNode, Edge, Tree, etc.)
└── exporters/
    ├── blueprint.py    # Full JSON export → codeknowledge_mapper.blueprint.json
    └── summary.py      # Compact AI index → codeknowledge_mapper.summary.json

Pipeline Flow

1. ingest   →  Fetch Jira tickets + Git log  →  ingest_*.json
2. scan     →  Parse source → Resolve deps → Link tickets → Export blueprint
3. enrich   →  Re-scan → Generate AI summaries (with ticket context) → Export

---

Roadmap

• JS/TypeScript support (Babel AST + Python regex fallback)
• Change impact diff: codeknowledge-mapper impact-diff --before HEAD~1 --after HEAD
• Watch mode: auto-rescan on file change (Watchdog + MCP server)
• External context linking: Jira/Git ticket mapping onto code graph nodes
• Multi-provider AI enrichment: Gemini, OpenAI, Claude
• VS Code extension wrapper