# Code DNA Tracker

![Tests](https://github.com/sebachriss/code-dna-tracker/actions/workflows/ci.yml/badge.svg)
![Python](https://img.shields.io/badge/python-3.10+-blue.svg)
![License](https://img.shields.io/badge/license-MIT-green.svg)
![Status](https://img.shields.io/badge/status-beta-orange.svg)

An MCP (Model Context Protocol) server that tracks the complete lineage and DNA of every line of code — who wrote it, when, why, what PRs modified it, what bugs it introduced/fixed, and how it has evolved over time.

## Features

- **Lineage Tracking**: Complete history of every line of code
- **Impact Analysis**: Blast radius and dependency analysis
- **Code Archaeology**: Find zombie code, abandoned code, hot spots, and orphan code
- **Bug Risk Prediction**: Predict which lines are likely to cause bugs
- **Incremental Updates**: Only re-process files that changed since last analysis
- **Multi-Platform**: Works with Claude Code, Cursor, OpenCode, Cline, and any MCP-compatible host
- **Deterministic**: No LLMs, no API keys, no external costs — works fully offline

## Installation

```bash
pip install code-dna-tracker
```

Or from source:

```bash
git clone https://github.com/sebachriss/code-dna-tracker.git
cd code-dna-tracker
pip install -e .
```

Requirements:
- Python 3.10+
- Git repository to analyze

## Usage

### As MCP Server

Code DNA Tracker works with any MCP-compatible host. Configure it once and use it everywhere.

**Claude Code** (`~/.config/claude-code/mcp_config.json`):
```json
{
  "mcpServers": {
    "code-dna-tracker": {
      "command": "python",
      "args": ["-m", "code_dna_tracker.mcp.server"],
      "env": {
        "CODE_DNA_REPO_PATH": "/path/to/your/repository"
      }
    }
  }
}
```

**Cursor** (Settings → MCP):
```json
{
  "mcpServers": {
    "code-dna-tracker": {
      "command": "python",
      "args": ["-m", "code_dna_tracker.mcp.server"],
      "env": {
        "CODE_DNA_REPO_PATH": "/path/to/your/repository"
      }
    }
  }
}
```

See [MCP_CONFIG_EXAMPLES.md](MCP_CONFIG_EXAMPLES.md) for configuration examples for OpenCode, Cline, and other platforms.

### CLI Usage

```bash
# Initialize tracking for a repository
code-dna init ./my-repo

# Update tracking incrementally (only changed files)
code-dna update ./my-repo

# Get line DNA
code-dna get-line-dna ./my-repo path/to/file.py 42

# Get file DNA summary
code-dna get-file-dna ./my-repo path/to/file.py

# Calculate blast radius of a line change
code-dna blast-radius ./my-repo path/to/file.py 42

# Predict bug risk of a line
code-dna bug-risk ./my-repo path/to/file.py 42

# Find zombie code (files not modified in over 1 year)
code-dna zombie-code ./my-repo --days 365

# Analyze overall code health
code-dna code-health ./my-repo

# Launch web dashboard
code-dna web ./my-repo
```

## MCP Tools

### Lineage Tools

- `get_line_dna`: Get complete DNA of a specific line including author, commit, function context, and modification history
- `get_file_dna`: Get DNA summary for a file including commit history and structure
- `init_repository`: Initialize tracking for a repository (parses all files and builds database)
- `update_repository`: Update tracking incrementally — only re-parses files that changed since last analysis

### Impact Analysis Tools

- `get_blast_radius`: Calculate what other code is affected if a specific line changes
- `predict_bug_risk`: Predict bug risk for a line based on modification history and complexity

### Code Archaeology Tools

- `find_zombie_code`: Find files that haven't been modified in a long time (default: 365 days)
- `find_abandoned_code`: Find functions whose original authors have been inactive (default: 180 days)
- `find_hot_spots`: Find files that change frequently and may be unstable
- `find_orphan_code`: Find functions/classes that are never called or imported
- `analyze_code_health`: Get overall code health score with recommendations

## Architecture

```
code_dna_tracker/
├── core/                    # Core analysis engine
│   ├── git_analyzer.py      # Git operations and blame analysis
│   ├── ast_parser.py        # Tree-sitter based code parsing
│   ├── lineage_builder.py   # Combines git and AST data
│   ├── impact_calculator.py # Dependency and blast radius analysis
│   ├── code_archaeologist.py # Code health and archaeology
│   └── file_utils.py        # Code file discovery with exclusions
├── storage/                 # Data persistence
│   └── database.py          # SQLite storage layer
├── mcp/                     # MCP server
│   └── server.py            # MCP tools and protocol implementation
├── web/                     # Web UI dashboard
│   ├── app.py              # FastAPI backend
│   └── static/             # Frontend (HTML/CSS/JS)
└── cli.py                   # Command-line interface
```

### Components

- **Git Analyzer**: Extracts commit history, blame information, and file modifications from Git
- **AST Parser**: Parses code using Tree-sitter to extract functions, classes, imports, and variables
- **Lineage Builder**: Combines Git and AST data to build the complete DNA of each line
- **Impact Calculator**: Builds dependency graphs and calculates blast radius and bug risk
- **Code Archaeologist**: Analyzes code for zombie code, abandoned code, hot spots, orphan code, and overall health
- **Storage Layer**: Persists analysis data in SQLite for fast queries

## How It Works

1. **Initialization**: `code-dna init` parses all code files in a repository, extracts git blame for each line, and stores the data in SQLite
2. **Incremental Update**: `code-dna update` detects files changed since the last analyzed commit and only re-processes those, keeping updates fast
3. **Query**: The MCP server reads from the database and runs real-time analysis when tools are called
4. **Analysis**: Combines git history, AST structure, and graph algorithms to provide insights

## Supported Languages

- Python (`.py`)
- JavaScript (`.js`, `.jsx`)
- TypeScript (`.ts`, `.tsx`)
- Go (`.go`)
- Rust (`.rs`)
- Java (`.java`)

More languages can be added by including additional Tree-sitter grammars.

## Cost

Code DNA Tracker is a deterministic tool that does not use LLMs. The only cost is local computation time.

- **No API keys required**
- **No LLM costs**
- **Works offline**

## Development

```bash
# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

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

# Run tests
pytest
```

## Roadmap

- [x] Core lineage tracking
- [x] Impact analysis
- [x] Code archaeology
- [x] Incremental updates
- [x] Multi-language support (Python, JS, TS, Go, Rust, Java)
- [x] Web UI dashboard
- [ ] IDE extensions

## License

MIT