Deploy FastAPI & MCP server over SSE

.gitignore

@@ -0,0 +1,24 @@
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+*.egg
+state.json
+diffcontext_state.json
+benchmark_results.json
+.venv/
+venv/
+yt-dlp/
+benchmark_repos/
+a.txt
+ctxsync/
+demo-visual.html
+node_modules/
+sync-context.sh
+test_fixtures.tar.gz
+test_graph_resolution.py
+.diffcontext_cache.db
+benchmarks/results/

Dockerfile

@@ -0,0 +1,30 @@
+# Use python:3.11-slim as a lightweight base image
+FROM python:3.11-slim
+
+# Install system dependencies (git is needed for diffcontext)
+RUN apt-get update && apt-get install -y git && rm -rf /var/lib/apt/lists/*
+
+# Set up user with UID 1000 (Hugging Face Spaces requirement)
+RUN useradd -m -u 1000 user
+WORKDIR /app
+
+# Copy configuration and project files
+COPY pyproject.toml /app/
+COPY README.md /app/
+COPY diffcontext /app/diffcontext
+COPY diffcontext-service /app/diffcontext-service
+
+# Install package dependencies and extra tools
+RUN pip install --no-cache-dir fastapi uvicorn python-multipart mcp sse-starlette .
+
+# Grant write permissions for cached SQLite database and temp directories
+RUN chown -R user:user /app
+
+# Switch to the non-root user
+USER user
+
+# Expose port 7860 (Hugging Face Spaces requirement)
+EXPOSE 7860
+
+# Start the FastAPI server using Uvicorn
+CMD ["uvicorn", "diffcontext-service.backend.main:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -1,12 +1,263 @@
----
-title: Diffcontext
-emoji: 📚
-colorFrom: indigo
-colorTo: gray
-sdk: docker
-pinned: false
-license: mit
-short_description: 'DiffContext, a static-analysis-based context compiler '
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# DiffContext
+
+Static-analysis-powered repository context compiler for LLMs.
+
+**Git diff + AST parsing + dependency graph + blast radius + impact scoring → optimized context package**
+
+Instead of dumping an entire codebase (or doing keyword/vector search), DiffContext:
+
+1. **Parses** Python files via AST → extracts every function, method, class
+2. **Builds a dependency graph** → calls, imports, inheritance, attribute ownership, decorators
+3. **Detects changes** → via git diff (including uncommitted edits) or snapshot comparison
+4. **Computes blast radius** → everything transitively affected by the change
+5. **Scores impact** → prioritizes symbols by structural importance
+6. **Selects relevant code** → respects a token budget
+7. **Compiles context** → structured output ready to paste into an LLM
+
+On a real ~1,100-symbol production repo, this reliably produces **95–99% token
+reduction** versus pasting the whole codebase, while keeping the functions that
+are actually call-graph-connected to your change.
+
+## Quick Start
+
+### Step 1: Install
+
+```bash
+git clone https://github.com/trakshan-mishra/Diffcontext.git
+cd Diffcontext
+pip install -e .
+diffcontext --help
+```
+
+### Step 2: Index a repository
+
+```bash
+diffcontext index /path/to/any/python/project
+```
+
+If any file fails to parse (a real `SyntaxError`), it's reported explicitly —
+not silently skipped:
+
+```
+Skipping broken_file.py due to SyntaxError: unmatched ')' (line 237)
+```
+
+### Step 3: Check impact of a function you're working on
+
+This is the recommended default mode while actively editing — it doesn't
+depend on git at all, so it works on uncommitted or untracked files too:
+
+```bash
+diffcontext blast --changed ./src/auth.py:validate_jwt
+```
+
+Shows who calls it, what it calls, and the full transitive blast radius.
+
+### Step 4: Auto-detect changes from git (optional)
+
+```bash
+diffcontext diff
+```
+
+Compares your working tree (including uncommitted edits to **tracked** files)
+against `HEAD~1` by default. Note: this only sees changes to files git
+already knows about — a brand-new untracked file is invisible to any
+git-diff-based tool until you `git add -N <file>` or commit it. Use
+`--committed-only` to compare two commits and ignore working-tree changes.
+
+### Step 5: Build LLM-ready context
+
+```bash
+# From a specific function:
+diffcontext compile --changed ./src/auth.py:validate_jwt
+
+# From git diff:
+diffcontext compile --ref HEAD~1
+
+# With a token budget:
+diffcontext compile --changed ./src/auth.py:validate_jwt --max-tokens 8000
+
+# JSON output (for piping into another tool):
+diffcontext compile --changed ./src/auth.py:validate_jwt --json
+```
+
+Then paste the output into Claude / ChatGPT / your LLM of choice, **with a
+specific question** — not just the raw context. E.g.:
+
+> "Is the dynamic SQL construction in `update_run` safe, given how `kwargs`
+> is validated against `_UPDATABLE_RUN_COLUMNS`?"
+
+### Step 6: Use as a library
+
+```python
+from diffcontext.pipeline import index_repository, analyze_impact, compile
+
+idx = index_repository("/path/to/repo")
+impact = analyze_impact(idx, ["./src/auth.py:validate_jwt"])
+ctx = compile(idx, impact, max_tokens=10000)
+
+print(ctx.text)             # the context to send to the LLM
+print(f"{ctx.token_estimate:,} / {ctx.total_repo_tokens:,} tokens")
+print(f"{ctx.reduction_pct:.1f}% reduction")
+```
+
+See `USAGE.md` for the full day-to-day workflow, including shell aliases.
+
+### Step 7: Cloud sync (CtxSync) (yet to be impemented)
+
+```bash
+diffcontext sync
+```
+
+One command. Compiles blast radius and pushes to your CtxSync cloud endpoint.
+Credentials are read from `~/.ctxsync`, env vars, or `--url`/`--key` flags.
+
+### Step 8: Use as an MCP Server (Claude Desktop / Cursor)
+
+DiffContext includes a built-in **Model Context Protocol (MCP)** server, allowing AI assistants to natively query your codebase's blast radius without manual copy-pasting.
+
+**1. Install with MCP support:**
+```bash
+pip install -e .[mcp]
+```
+
+**2. Configure your AI client:**
+For Claude Desktop (`claude_desktop_config.json`) or Cursor:
+```json
+{
+  "mcpServers": {
+    "diffcontext": {
+      "command": "diffcontext-mcp"
+    }
+  }
+}
+```
+
+Now you can just ask your AI: *"What is the blast radius of validate_jwt in the diffcontext repo?"* and it will autonomously use DiffContext to find the precise context!
+
+## What the resolver actually handles
+
+Confirmed via an automated test suite (`tests/`) that builds small repos on
+the fly and asserts on real resolved call-graph edges — not just "it ran
+without crashing":
+
+- Function and method calls, including multi-hop attribute chains (`self.a.b.method()`)
+- Multiple inheritance / MRO, including cross-file base classes
+- Circular imports
+- Local variables instantiating a class inside a **free function** (not just
+  `self.x = ...` inside a method) — e.g. `h = Handler(); h.process()`
+- Annotated parameters as call receivers (`def run(h: Handler): h.process()`)
+- Import aliasing (`from .user import Handler as UserHandler`), including
+  disambiguating two same-named classes in different files
+- Bare `import x` where `x` lives in a sibling directory rather than the
+  repo root (common in script-style codebases)
+- **Decorators**: a decorated function's graph entry now correctly includes
+  calls made by its decorator's wrapper — e.g. `@require_auth` wrapping
+  `get_profile` correctly shows `get_profile` depending on whatever
+  `require_auth`'s wrapper calls (like a session check), not falsely
+  attributed to `require_auth` itself
+- Higher-order stdlib functions: `map(fn, items)`, `sorted(x, key=fn)`,
+  `filter(fn, items)` — a function passed *by reference* to these is
+  tracked as an implicit call
+
+## Known limitations (genuinely unfixable by static analysis, not bugs)
+
+- **Dynamic dispatch / `getattr()`-based routing**: `getattr(obj, name)()`
+  can't be resolved statically when `name` is computed at runtime (from
+  config, user input, etc.) — no static analysis tool can do this in
+  general, including IDEs.
+- **Cross-file changes related by theme, not by function calls**: e.g. "remove
+  a dependency," touching 3 files for one conceptual reason with no direct
+  call-graph edges between them. Blast radius is a call-graph tool; it
+  cannot detect relatedness that isn't expressed as a function call.
+- **User-defined higher-order functions**: only the common stdlib cases
+  (`map`, `filter`, `sorted`/`max`/`min` with `key=`) are recognized.
+  A custom function like `def apply_twice(fn, value): return fn(fn(value))`
+  is not — this would need cross-function signature analysis to know which
+  parameter is expected to be callable.
+
+Run `grep -rn "function_name(" --include="*.py" .` to spot-check anything
+important before fully trusting "no callers found."
+
+## Architecture
+
+```
+diffcontext/
+├── __init__.py          # Package entry, high-level API
+├── models.py             # Data classes (Symbol, RepositoryIndex, etc.)
+├── scanner.py             # File discovery with exclusion list
+├── parser.py               # AST symbol extraction
+├── resolver.py              # Import -> filesystem path resolution
+├── symbols.py                 # Attribute / local-var type tracking
+├── graph_builder.py             # Core: dependency graph construction
+├── pipeline.py                    # Pipeline orchestrator
+├── _warn_once.py                    # De-duplicated warnings (broken files, encoding, unknown symbols)
+├── diff/
+│   ├── git_diff.py                    # Git diff -> changed symbols
+│   └── state_manager.py                # Snapshot-based change detection
+├── impact/
+│   ├── blast_radius.py                  # Reverse graph traversal
+│   ├── scoring.py                         # Impact scoring
+│   ├── traversal.py                         # Forward dependency expansion
+│   └── visualizer.py                          # Terminal tree rendering
+├── context/
+│   ├── selector.py                              # Token-budget-aware selection
+│   └── compiler.py                                # Structured output formatting
+└── cli/
+    └── __init__.py                                  # CLI: index, impact, diff, compile, blast, sync
+```
+
+## Try it (30 seconds)
+
+```bash
+bash demos.sh         # interactive — pick from 5 famous repos or use your own
+```
+
+## How symbol IDs work
+
+Every function gets a unique ID: `./relative/path.py:ClassName.method_name`
+
+```
+./src/auth.py:validate_jwt
+./src/flask/app.py:Flask.route
+```
+
+**No parentheses, no arguments** — `validate_jwt`, never `validate_jwt(token)`.
+
+## Testing
+
+```bash
+python3 -m pytest tests/ -v
+```
+
+17 tests, all self-contained (no external clone needed), covering both
+correct resolution and the documented limitations above — including tests
+that were written to fail loudly if a future change silently regresses
+something that's currently working.
+
+## Status
+
+This is a personal project, built and iteratively debugged against real
+production codebases (openai/whisper, pallets/click, pallets/flask). Several
+real resolver bugs were found and fixed through dogfooding — decorators,
+higher-order functions, and sibling-directory imports all required fixes
+that were only visible on real code, not toy examples. Treat blast-radius
+output as a strong starting point, not a guarantee, and spot-check with
+`grep` on anything load-bearing.
+
+## License
+
+MIT
+
+## Benchmarks & Performance (Baseline)
+
+We adhere strictly to **Measure Before Optimizing**. Our baseline metrics demonstrate that traversal and compilation are nearly instantaneous, while parsing and graph construction are the primary bottlenecks. This data drives our roadmap for v0.4 (Incremental Caching).
+
+| Repo | Files | Symbols | Parse (ms) | Graph Build (ms) | Traversal (ms) | Compile (ms) | Token Reduction |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| **Flask** | 20 | 354 | 488 | 930 | 0.1 | 0.0 | 98.15% |
+| **Click** | 19 | 506 | 1273 | 1824 | 0.2 | 0.0 | 96.51% |
+| **HTTPX** | 21 | 434 | 665 | 1147 | 0.1 | 0.0 | 96.70% |
+| **Pydantic** | 90 | 1826 | 4519 | 7914 | 0.6 | 0.0 | 98.43% |
+
+*Note: Peak memory for Pydantic (the largest repo) was only 66.4 MB, validating that memory is not currently a bottleneck.*

USAGE.md

@@ -0,0 +1,122 @@
+# DiffContext — Day-to-Day Usage
+
+This captures the actual workflow that works, based on real use against a
+1000+ symbol production repo (not just toy examples).
+
+## Setup (once per shell session, or add to ~/.bashrc / ~/.zshrc)
+
+```bash
+alias dcb='diffcontext blast --changed'
+alias dcc='diffcontext compile --changed'
+alias dci='diffcontext index'
+alias dcs='diffcontext sync'
+```
+
+To make these permanent, append the three lines above to `~/.bashrc` (or
+`~/.zshrc` if you use zsh), then `source ~/.bashrc`.
+
+## The core workflow
+
+### 1. While actively editing — don't rely on git diff detection
+
+Git-diff-based commands (`diffcontext diff`, `diffcontext blast` with no
+`--changed`) only see **tracked** changes that are committed or staged.
+An edit to an **untracked** (brand new) file is invisible to them — not a
+bug, that's just what `git diff` means.
+
+For active editing, skip git entirely and name the symbol directly:
+
+```bash
+dcb ./path/to/file.py:function_name
+```
+
+This works immediately, no commit, no `git add`, no staging.
+
+### 2. Symbol IDs — exact format
+
+```
+./relative/path.py:function_name
+./relative/path.py:ClassName.method_name
+```
+
+Rules:
+- Path is relative to the repo root you indexed, always starts with `./`
+- **No parentheses, no arguments, no type hints** — `update_run`, never
+  `update_run(run_id: int, **kwargs)`. Bash will choke on unquoted `()`
+  with a `syntax error near unexpected token` — that's bash, not
+  diffcontext, complaining.
+- Find real names fast:
+  ```bash
+  grep -n "^def \|^    def " path/to/file.py
+  ```
+
+### 3. Before trusting "no callers found" — spot-check with grep
+
+This caught 3 real bugs during testing. Make it a habit, not a one-off:
+
+```bash
+grep -rn "function_name(" --include="*.py" .
+```
+
+If grep finds callers diffcontext's blast radius missed, that's a real
+gap worth knowing about (and worth reporting) — don't assume the blast
+radius is complete just because it ran without error.
+
+### 4. Getting LLM-ready context
+
+```bash
+dcc ./path/to/file.py:function_name --max-tokens 4000
+```
+
+Paste the output into Claude/ChatGPT **with a specific question**, not
+just the raw context:
+
+- Bad: "review this"
+- Good: "I'm about to add a new field to `update_run` — given these 5
+  callers, what do I need to check?"
+- Good: "Is the dynamic SQL construction in `update_run` safe given how
+  `kwargs` is validated against `_UPDATABLE_RUN_COLUMNS`?"
+
+### 5. Tuning context size
+
+- `--depth N` (default 2-3): how many hops of callers/callees to pull in.
+  Use `--depth 1` for a tight, single-function check. Use `--depth 4+`
+  for "how does this fit into the bigger picture."
+- `--max-tokens N`: hard cap. Lower it to force tighter selection (only
+  the highest-scored symbols survive); raise it if you have a
+  large-context model and want more surrounding code.
+
+### 6. Checking what changed (only works for committed/staged files)
+
+```bash
+diffcontext diff                    # working tree vs HEAD~1, tracked files only
+diffcontext diff --committed-only   # two commits only, ignores uncommitted edits
+```
+
+If a file shows as broken (`Skipping X due to SyntaxError`), diffcontext
+will still report a best-effort diff using the prior committed version —
+look for the `⚠ N file(s) failed to parse` block in the output.
+
+## Known limitations (don't trust blast radius blindly here)
+
+- **Dynamic dispatch / `getattr()`-based routing**: common in CLI
+  argument dispatch and plugin systems — invisible to static analysis.
+- **Cross-file changes related by theme, not by function calls**: e.g.
+  "remove a dependency" touching 3 unrelated-by-call-graph files for one
+  conceptual reason. Blast radius won't connect these.
+- **User-defined higher-order functions**: only the common stdlib cases
+  (`map`, `filter`, `sorted`/`max`/`min` with `key=`) are recognized.
+  A custom `def apply_twice(fn, value)` is not tracked.
+
+When in doubt: grep first, trust second.
+
+## Cloud sync (CtxSync)
+
+Push your blast radius to the cloud in one command:
+
+```bash
+diffcontext sync
+```
+
+Reads credentials from `~/.ctxsync` (or `--url`/`--key` flags, or env vars).
+The system prompt URL can be pasted into any AI tool for live context awareness.

diffcontext-service/README.md

@@ -0,0 +1,177 @@
+# DiffContext Web Service — Complete Setup Guide
+
+## What you just built
+
+```
+diffcontext-service/
+├── backend/
+│   └── main.py          ← FastAPI REST API server
+├── frontend/
+│   └── index.html       ← Web UI (open in browser, no server needed)
+├── mcp/
+│   └── mcp_server.py    ← MCP server for Claude Desktop / Cursor
+└── README.md            ← This file
+```
+
+---
+
+## Option A — Web UI (easiest, for beginners)
+
+### Step 1: Install dependencies
+```bash
+pip install fastapi uvicorn python-multipart aiofiles
+```
+
+### Step 2: Start the API server
+```bash
+cd /path/to/Diffcontext
+uvicorn diffcontext-service.backend.main:app --reload --port 8000
+```
+
+### Step 3: Open the web UI
+Just open `diffcontext-service/frontend/index.html` in your browser.
+(Double-click it, or drag it into Chrome/Firefox.)
+
+### Step 4: Use it
+1. Zip your Python project folder
+2. Upload the zip on the "Upload Project" tab
+3. Pick a function from the list
+4. Click "Analyse Blast Radius"
+5. See what breaks!
+
+---
+
+## Option B — REST API (for developers)
+
+Once the server is running at `http://localhost:8000`:
+
+```python
+import requests
+
+# 1. Upload your project
+with open("myproject.zip", "rb") as f:
+    r = requests.post("http://localhost:8000/upload", files={"file": f})
+repo_id = r.json()["repo_id"]
+
+# 2. List all functions
+r = requests.get(f"http://localhost:8000/symbols?repo_id={repo_id}")
+print(r.json()["symbols"][:5])
+
+# 3. Get blast radius
+r = requests.post("http://localhost:8000/blast", json={
+    "repo_id": repo_id,
+    "symbol": "./src/auth.py:validate_jwt"
+})
+print(r.json())
+
+# 4. Get LLM context to paste into Claude
+r = requests.post("http://localhost:8000/compile", json={
+    "repo_id": repo_id,
+    "symbol": "./src/auth.py:validate_jwt",
+    "max_tokens": 8000
+})
+print(r.json()["context_text"])
+```
+
+### Or use curl:
+```bash
+# Upload
+curl -X POST http://localhost:8000/upload -F "file=@myproject.zip"
+
+# Blast radius
+curl -X POST http://localhost:8000/blast \
+  -H "Content-Type: application/json" \
+  -d '{"repo_id": "abc123", "symbol": "./main.py:my_function"}'
+
+# Paste code directly (no upload)
+curl -X POST http://localhost:8000/inline \
+  -H "Content-Type: application/json" \
+  -d '{
+    "files": {"main.py": "def greet(name):\n  msg = build_message(name)\n  print(msg)\n\ndef build_message(name):\n  return f\"Hello {name}\""},
+    "symbol": "./main.py:greet"
+  }'
+```
+
+Interactive docs: http://localhost:8000/docs
+
+---
+
+## Option C — MCP Server (Claude Desktop / Cursor)
+
+This lets Claude Desktop call DiffContext automatically — no copy-paste needed.
+
+### Step 1: Install MCP
+```bash
+pip install mcp
+```
+
+### Step 2: Find the full path to mcp_server.py
+```bash
+# Mac/Linux
+realpath diffcontext-service/mcp/mcp_server.py
+
+# Windows
+cd diffcontext-service\mcp && echo %CD%\mcp_server.py
+```
+
+### Step 3: Add to Claude Desktop config
+
+**Mac:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "diffcontext": {
+      "command": "python",
+      "args": ["/FULL/PATH/TO/diffcontext-service/mcp/mcp_server.py"]
+    }
+  }
+}
+```
+
+### Step 4: Restart Claude Desktop
+
+### Step 5: Use it in Claude Desktop
+```
+"List all functions in /Users/me/myproject"
+
+"What is the blast radius of ./src/auth.py:validate_jwt 
+ in /Users/me/myproject?"
+
+"I'm about to change create_user in /Users/me/myproject.
+ Compile context so I can understand the impact."
+```
+
+Claude will call DiffContext automatically and show you the results.
+
+---
+
+## Troubleshooting
+
+| Problem | Fix |
+|---------|-----|
+| `Connection refused` on localhost:8000 | Run the uvicorn command first |
+| `No Python files found` | Make sure your zip contains .py files |
+| Symbol not found | Use format `./filename.py:function_name` (no parentheses) |
+| MCP not working | Check the full path in claude_desktop_config.json |
+| `ModuleNotFoundError: mcp` | Run `pip install mcp` |
+
+---
+
+## API response format
+
+```json
+{
+  "symbol": "./service.py:onboard_user",
+  "direct_callers": ["./api.py:handle_signup"],
+  "direct_callees": ["./service.py:create_user", "./service.py:create_order"],
+  "blast_radius_count": 5,
+  "blast_radius_by_file": {
+    "./api.py": ["handle_signup", "process_request"],
+    "./tests/test_service.py": ["test_onboard"]
+  },
+  "all_affected": ["./api.py:handle_signup", ...],
+  "total_symbols_in_repo": 47
+}
+```

diffcontext-service/backend/main.py

@@ -0,0 +1,435 @@
+"""
+DiffContext Web Service — FastAPI Backend
+Exposes DiffContext as a REST API so anyone can use it online.
+"""
+
+import ast
+import json
+import os
+import tempfile
+import zipfile
+import shutil
+from pathlib import Path
+from typing import Dict, List, Optional
+
+from fastapi import FastAPI, File, UploadFile, HTTPException
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse
+from pydantic import BaseModel
+
+
+app = FastAPI(
+    title="DiffContext API",
+    description="Analyse your Python code's blast radius — which functions break when you change one?",
+    version="1.0.0",
+)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# ── In-memory session store (repo_id -> temp dir path) ──────────────────────
+SESSIONS: Dict[str, str] = {}
+
+
+# ── Pydantic models ──────────────────────────────────────────────────────────
+
+class BlastRequest(BaseModel):
+    repo_id: str
+    symbol: str           # e.g. "./service.py:onboard_user"
+
+class CompileRequest(BaseModel):
+    repo_id: str
+    symbol: str
+    max_tokens: int = 8000
+
+class InlineRequest(BaseModel):
+    """Lets beginners paste code directly without uploading a zip."""
+    files: Dict[str, str]   # filename -> source code
+    symbol: str             # which function to analyze
+
+
+# ── Helpers ─────────────────────────────────────────────────────────────────
+
+def _run_diffcontext(repo_path: str, symbol: str):
+    """
+    Run the DiffContext pipeline on repo_path for one symbol.
+    Returns a plain dict so it's JSON-serialisable.
+    Falls back to a lightweight AST-only analysis if DiffContext
+    isn't installed (so the service still works standalone).
+    """
+    try:
+        # Try real DiffContext first
+        import sys
+        sys.path.insert(0, str(Path(__file__).parent.parent.parent))
+        from diffcontext.pipeline import index_repository, analyze_impact
+
+        idx = index_repository(repo_path)
+        if symbol not in idx.symbols and symbol not in idx.graph:
+            # Suggest similar ones
+            import difflib
+            suggestions = difflib.get_close_matches(symbol, list(idx.symbols.keys()), n=3, cutoff=0.4)
+            return {
+                "error": f"Symbol '{symbol}' not found.",
+                "suggestions": suggestions,
+                "all_symbols": list(idx.symbols.keys()),
+            }
+
+        impact = analyze_impact(idx, [symbol])
+
+        # Build callers / callees for response
+        reverse: Dict[str, List[str]] = {}
+        for caller, callees in idx.graph.items():
+            for callee in callees:
+                reverse.setdefault(callee, []).append(caller)
+
+        direct_callers = reverse.get(symbol, [])
+        direct_callees = idx.graph.get(symbol, [])
+
+        # Group blast radius by file
+        by_file: Dict[str, List[str]] = {}
+        for sym in impact.blast_radius:
+            file_part = sym.split(":")[0]
+            by_file.setdefault(file_part, []).append(sym.split(":")[-1])
+
+        return {
+            "symbol": symbol,
+            "direct_callers": direct_callers,
+            "direct_callees": direct_callees,
+            "blast_radius_count": len(impact.blast_radius),
+            "blast_radius_by_file": by_file,
+            "all_affected": impact.blast_radius[:50],
+            "scores": {k: round(v, 1) for k, v in list(impact.scores.items())[:30]},
+            "total_symbols_in_repo": len(idx.symbols),
+        }
+
+    except ImportError:
+        # Fallback: pure AST analysis without DiffContext
+        return _ast_fallback(repo_path, symbol)
+
+
+def _ast_fallback(repo_path: str, symbol: str) -> dict:
+    """
+    Lightweight fallback: parse all .py files with stdlib ast,
+    build a simple call graph, return blast radius.
+    Works even without DiffContext installed.
+    """
+    file_part, func_name = (symbol.split(":", 1) + [""])[:2]
+    if not func_name:
+        return {"error": "Invalid symbol format. Use ./file.py:function_name"}
+
+    # Collect all functions from all .py files
+    all_functions: Dict[str, str] = {}   # id -> source snippet
+    call_graph: Dict[str, List[str]] = {}
+
+    for py_file in Path(repo_path).rglob("*.py"):
+        rel = "./" + str(py_file.relative_to(repo_path))
+        try:
+            source = py_file.read_text(errors="ignore")
+            tree = ast.parse(source)
+        except SyntaxError:
+            continue
+
+        for node in ast.walk(tree):
+            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                fid = f"{rel}:{node.name}"
+                all_functions[fid] = ast.get_source_segment(source, node) or ""
+                # Collect calls made inside this function
+                calls = []
+                for child in ast.walk(node):
+                    if isinstance(child, ast.Call):
+                        if isinstance(child.func, ast.Name):
+                            calls.append(child.func.id)
+                        elif isinstance(child.func, ast.Attribute):
+                            calls.append(child.func.attr)
+                call_graph[fid] = calls
+
+    # Resolve calls to full IDs
+    name_to_ids: Dict[str, List[str]] = {}
+    for fid in all_functions:
+        name = fid.split(":")[-1]
+        name_to_ids.setdefault(name, []).append(fid)
+
+    resolved_graph: Dict[str, List[str]] = {}
+    for fid, raw_calls in call_graph.items():
+        resolved = []
+        for call in raw_calls:
+            for candidate in name_to_ids.get(call, []):
+                if candidate != fid:
+                    resolved.append(candidate)
+        resolved_graph[fid] = resolved
+
+    # Build reverse graph
+    reverse: Dict[str, List[str]] = {}
+    for caller, callees in resolved_graph.items():
+        for callee in callees:
+            reverse.setdefault(callee, []).append(caller)
+
+    if symbol not in all_functions:
+        import difflib
+        suggestions = difflib.get_close_matches(symbol, list(all_functions.keys()), n=3, cutoff=0.4)
+        return {
+            "error": f"Symbol '{symbol}' not found.",
+            "suggestions": suggestions,
+            "all_symbols": list(all_functions.keys()),
+        }
+
+    # BFS blast radius
+    visited = {symbol}
+    blast = []
+    frontier = [symbol]
+    while frontier:
+        next_f = []
+        for node in frontier:
+            for caller in reverse.get(node, []):
+                if caller not in visited:
+                    visited.add(caller)
+                    blast.append(caller)
+                    next_f.append(caller)
+        frontier = next_f
+
+    by_file: Dict[str, List[str]] = {}
+    for sym in blast:
+        fp = sym.split(":")[0]
+        by_file.setdefault(fp, []).append(sym.split(":")[-1])
+
+    return {
+        "symbol": symbol,
+        "direct_callers": reverse.get(symbol, []),
+        "direct_callees": resolved_graph.get(symbol, []),
+        "blast_radius_count": len(blast),
+        "blast_radius_by_file": by_file,
+        "all_affected": blast[:50],
+        "scores": {},
+        "total_symbols_in_repo": len(all_functions),
+        "note": "Lightweight AST mode (install DiffContext for full analysis)",
+    }
+
+
+def _list_symbols(repo_path: str) -> List[str]:
+    """Return all function symbol IDs in the repo."""
+    symbols = []
+    for py_file in Path(repo_path).rglob("*.py"):
+        rel = "./" + str(py_file.relative_to(repo_path))
+        try:
+            source = py_file.read_text(errors="ignore")
+            tree = ast.parse(source)
+        except SyntaxError:
+            continue
+        for node in ast.walk(tree):
+            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                symbols.append(f"{rel}:{node.name}")
+    return sorted(symbols)
+
+
+# ── Routes ───────────────────────────────────────────────────────────────────
+
+@app.get("/")
+def root():
+    return {
+        "service": "DiffContext API",
+        "docs": "/docs",
+        "endpoints": [
+            "POST /upload    — upload a .zip of your project",
+            "POST /inline    — paste code directly (no upload needed)",
+            "POST /blast     — get blast radius for a function",
+            "GET  /symbols   — list all functions in uploaded repo",
+            "POST /compile   — get LLM-ready context string",
+            "GET  /health    — service health check",
+        ],
+    }
+
+
+@app.get("/health")
+def health():
+    return {"status": "ok"}
+
+
+@app.post("/upload")
+async def upload_repo(file: UploadFile = File(...)):
+    """
+    Upload a .zip of your Python project.
+    Returns a repo_id you use in all other calls.
+    """
+    if not file.filename.endswith(".zip"):
+        raise HTTPException(400, "Please upload a .zip file of your project folder.")
+
+    # Save zip to temp dir
+    tmp_dir = tempfile.mkdtemp(prefix="diffctx_")
+    zip_path = os.path.join(tmp_dir, "repo.zip")
+    extract_path = os.path.join(tmp_dir, "repo")
+
+    content = await file.read()
+    with open(zip_path, "wb") as f:
+        f.write(content)
+
+    # Extract
+    try:
+        with zipfile.ZipFile(zip_path, "r") as zf:
+            zf.extractall(extract_path)
+    except zipfile.BadZipFile:
+        shutil.rmtree(tmp_dir)
+        raise HTTPException(400, "Could not open zip file. Make sure it's a valid .zip.")
+
+    # Find the actual Python root (handle nested folder inside zip)
+    py_files = list(Path(extract_path).rglob("*.py"))
+    if not py_files:
+        shutil.rmtree(tmp_dir)
+        raise HTTPException(400, "No Python (.py) files found in your zip.")
+
+    # Use shallowest common directory
+    repo_root = str(min(py_files, key=lambda p: len(p.parts)).parent)
+
+    # Store session
+    import uuid
+    repo_id = str(uuid.uuid4())[:8]
+    SESSIONS[repo_id] = repo_root
+
+    symbols = _list_symbols(repo_root)
+
+    return {
+        "repo_id": repo_id,
+        "message": f"Uploaded successfully! Found {len(symbols)} functions.",
+        "symbol_count": len(symbols),
+        "sample_symbols": symbols[:10],
+        "next_step": f'Now call POST /blast with {{"repo_id": "{repo_id}", "symbol": "<pick from symbols above>"}}',
+    }
+
+
+@app.post("/inline")
+def analyze_inline(req: InlineRequest):
+    """
+    Paste code directly — no upload needed.
+    Great for quick testing.
+
+    Example body:
+    {
+      "files": {
+        "service.py": "def create_user(name): ...\\ndef onboard(name): create_user(name)"
+      },
+      "symbol": "./service.py:onboard"
+    }
+    """
+    tmp_dir = tempfile.mkdtemp(prefix="diffctx_inline_")
+    try:
+        for filename, code in req.files.items():
+            # Safety: strip any path traversal
+            safe_name = Path(filename).name
+            filepath = os.path.join(tmp_dir, safe_name)
+            with open(filepath, "w") as f:
+                f.write(code)
+
+        result = _run_diffcontext(tmp_dir, req.symbol)
+        return result
+    finally:
+        shutil.rmtree(tmp_dir, ignore_errors=True)
+
+
+@app.get("/symbols")
+def list_symbols(repo_id: str):
+    """List all functions in your uploaded repo."""
+    if repo_id not in SESSIONS:
+        raise HTTPException(404, f"repo_id '{repo_id}' not found. Upload your project first via POST /upload.")
+    repo_path = SESSIONS[repo_id]
+    symbols = _list_symbols(repo_path)
+    return {
+        "repo_id": repo_id,
+        "count": len(symbols),
+        "symbols": symbols,
+    }
+
+
+@app.post("/blast")
+def blast_radius(req: BlastRequest):
+    """
+    Get the blast radius for a function.
+    Tells you: who calls it, what it calls, what breaks if you change it.
+    """
+    if req.repo_id not in SESSIONS:
+        raise HTTPException(404, f"repo_id '{req.repo_id}' not found. Upload your project first.")
+    repo_path = SESSIONS[req.repo_id]
+    result = _run_diffcontext(repo_path, req.symbol)
+    return result
+
+
+@app.post("/compile")
+def compile_context(req: CompileRequest):
+    """
+    Get an LLM-ready context string you can paste into Claude or ChatGPT.
+    """
+    if req.repo_id not in SESSIONS:
+        raise HTTPException(404, f"repo_id '{req.repo_id}' not found. Upload your project first.")
+
+    repo_path = SESSIONS[req.repo_id]
+
+    try:
+        import sys
+        sys.path.insert(0, str(Path(__file__).parent.parent.parent))
+        from diffcontext.pipeline import index_repository, analyze_impact, compile as dc_compile
+
+        idx = index_repository(repo_path)
+        impact = analyze_impact(idx, [req.symbol])
+        ctx = dc_compile(idx, impact, max_tokens=req.max_tokens)
+
+        return {
+            "context_text": ctx.text,
+            "symbol_count": ctx.symbol_count,
+            "token_estimate": ctx.token_estimate,
+            "reduction_pct": round(ctx.reduction_pct, 1),
+            "usage_tip": "Paste context_text into Claude/ChatGPT with a specific question about your change.",
+        }
+    except ImportError:
+        # Fallback: return basic info
+        result = _run_diffcontext(repo_path, req.symbol)
+        context_text = f"""
+=== DIFFCONTEXT ANALYSIS ===
+Symbol: {req.symbol}
+
+Direct callers (will break if signature changes):
+{chr(10).join(f'  - {c}' for c in result.get('direct_callers', [])) or '  (none found)'}
+
+Direct callees (dependencies):
+{chr(10).join(f'  - {c}' for c in result.get('direct_callees', [])) or '  (none found)'}
+
+Full blast radius ({result.get('blast_radius_count', 0)} functions affected):
+{chr(10).join(f'  - {s}' for s in result.get('all_affected', [])[:20]) or '  (none found)'}
+"""
+        return {
+            "context_text": context_text,
+            "symbol_count": result.get("blast_radius_count", 0),
+            "token_estimate": len(context_text) // 4,
+            "reduction_pct": 0,
+        }
+
+
+# ── Optional MCP SSE integration ─────────────────────────────────────────────
+try:
+    from fastapi import Request
+    from starlette.routing import Mount
+    from mcp.server.sse import SseServerTransport
+    from diffcontext.mcp_server import server as mcp_server, HAS_MCP
+
+    if HAS_MCP and mcp_server is not None:
+        sse = SseServerTransport("/messages/")
+
+        # Mount the /messages endpoint
+        app.router.routes.append(Mount("/messages", app=sse.handle_post_message))
+
+        @app.get("/sse")
+        async def handle_sse(request: Request):
+            async with sse.connect_sse(
+                request.scope,
+                request.receive,
+                request._send
+            ) as (read_stream, write_stream):
+                await mcp_server.run(
+                    read_stream,
+                    write_stream,
+                    mcp_server.create_initialization_options()
+                )
+except ImportError:
+    pass
+

diffcontext-service/frontend/index.html

@@ -0,0 +1,1097 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>DiffContext — Code Blast Radius Analyser</title>
+<style>
+  :root {
+    --bg: #0d0f14;
+    --surface: #13161e;
+    --surface2: #1a1e2a;
+    --border: #252a38;
+    --accent: #7c6fff;
+    --accent2: #ff6b6b;
+    --accent3: #43e97b;
+    --text: #e2e8f0;
+    --muted: #64748b;
+    --warn: #f59e0b;
+    --mono: 'JetBrains Mono', 'Fira Code', monospace;
+  }
+
+  * { box-sizing: border-box; margin: 0; padding: 0; }
+
+  body {
+    background: var(--bg);
+    color: var(--text);
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+    min-height: 100vh;
+    display: flex;
+    flex-direction: column;
+  }
+
+  /* ── Header ── */
+  header {
+    background: var(--surface);
+    border-bottom: 1px solid var(--border);
+    padding: 18px 32px;
+    display: flex;
+    align-items: center;
+    gap: 16px;
+  }
+
+  .logo {
+    font-size: 22px;
+    font-weight: 700;
+    color: var(--accent);
+    letter-spacing: -0.5px;
+  }
+
+  .logo span { color: var(--text); }
+
+  .tagline {
+    color: var(--muted);
+    font-size: 13px;
+    margin-left: auto;
+  }
+
+  /* ── Tabs ── */
+  .tabs {
+    display: flex;
+    gap: 0;
+    border-bottom: 1px solid var(--border);
+    background: var(--surface);
+    padding: 0 32px;
+  }
+
+  .tab {
+    padding: 12px 20px;
+    cursor: pointer;
+    font-size: 13px;
+    font-weight: 500;
+    color: var(--muted);
+    border-bottom: 2px solid transparent;
+    transition: all 0.15s;
+    user-select: none;
+  }
+
+  .tab:hover { color: var(--text); }
+  .tab.active { color: var(--accent); border-bottom-color: var(--accent); }
+
+  /* ── Main layout ── */
+  main {
+    flex: 1;
+    display: flex;
+    gap: 0;
+    overflow: hidden;
+  }
+
+  .panel {
+    padding: 28px 32px;
+    overflow-y: auto;
+  }
+
+  .left { width: 380px; min-width: 320px; border-right: 1px solid var(--border); }
+  .right { flex: 1; }
+
+  /* ── Section headers ── */
+  .section-title {
+    font-size: 11px;
+    font-weight: 600;
+    text-transform: uppercase;
+    letter-spacing: 1px;
+    color: var(--muted);
+    margin-bottom: 12px;
+  }
+
+  /* ── Input groups ── */
+  .input-group {
+    margin-bottom: 20px;
+  }
+
+  label {
+    display: block;
+    font-size: 12px;
+    font-weight: 500;
+    color: var(--muted);
+    margin-bottom: 6px;
+  }
+
+  input, select, textarea {
+    width: 100%;
+    background: var(--surface2);
+    border: 1px solid var(--border);
+    color: var(--text);
+    padding: 10px 14px;
+    border-radius: 8px;
+    font-size: 13px;
+    font-family: var(--mono);
+    outline: none;
+    transition: border-color 0.15s;
+  }
+
+  input:focus, select:focus, textarea:focus {
+    border-color: var(--accent);
+  }
+
+  textarea { resize: vertical; min-height: 120px; }
+
+  /* ── Buttons ── */
+  .btn {
+    padding: 10px 20px;
+    border-radius: 8px;
+    border: none;
+    font-size: 13px;
+    font-weight: 600;
+    cursor: pointer;
+    transition: all 0.15s;
+    display: inline-flex;
+    align-items: center;
+    gap: 8px;
+  }
+
+  .btn-primary {
+    background: var(--accent);
+    color: white;
+  }
+
+  .btn-primary:hover { background: #6b5fee; }
+  .btn-primary:disabled { opacity: 0.5; cursor: not-allowed; }
+
+  .btn-secondary {
+    background: var(--surface2);
+    color: var(--text);
+    border: 1px solid var(--border);
+  }
+
+  .btn-secondary:hover { border-color: var(--accent); color: var(--accent); }
+
+  .btn-full { width: 100%; justify-content: center; }
+
+  /* ── Upload zone ── */
+  .upload-zone {
+    border: 2px dashed var(--border);
+    border-radius: 12px;
+    padding: 32px;
+    text-align: center;
+    cursor: pointer;
+    transition: all 0.15s;
+    margin-bottom: 20px;
+  }
+
+  .upload-zone:hover, .upload-zone.drag-over {
+    border-color: var(--accent);
+    background: rgba(124, 111, 255, 0.04);
+  }
+
+  .upload-icon { font-size: 36px; margin-bottom: 10px; }
+
+  .upload-zone p { font-size: 13px; color: var(--muted); }
+  .upload-zone strong { color: var(--text); }
+
+  /* ── Result cards ── */
+  .result-area {
+    display: none;
+  }
+
+  .result-area.visible { display: block; }
+
+  .stat-row {
+    display: grid;
+    grid-template-columns: repeat(3, 1fr);
+    gap: 12px;
+    margin-bottom: 24px;
+  }
+
+  .stat-card {
+    background: var(--surface2);
+    border: 1px solid var(--border);
+    border-radius: 10px;
+    padding: 16px;
+    text-align: center;
+  }
+
+  .stat-value {
+    font-size: 28px;
+    font-weight: 700;
+    color: var(--accent);
+    font-family: var(--mono);
+    line-height: 1;
+    margin-bottom: 4px;
+  }
+
+  .stat-label {
+    font-size: 11px;
+    color: var(--muted);
+    text-transform: uppercase;
+    letter-spacing: 0.5px;
+  }
+
+  /* ── Symbol lists ── */
+  .sym-section {
+    margin-bottom: 20px;
+  }
+
+  .sym-header {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    margin-bottom: 10px;
+  }
+
+  .sym-badge {
+    font-size: 11px;
+    font-weight: 600;
+    padding: 2px 8px;
+    border-radius: 20px;
+    font-family: var(--mono);
+  }
+
+  .badge-caller { background: rgba(255, 107, 107, 0.15); color: var(--accent2); }
+  .badge-callee { background: rgba(67, 233, 123, 0.15); color: var(--accent3); }
+  .badge-blast  { background: rgba(124, 111, 255, 0.15); color: var(--accent); }
+
+  .sym-list {
+    display: flex;
+    flex-direction: column;
+    gap: 6px;
+  }
+
+  .sym-item {
+    background: var(--surface2);
+    border: 1px solid var(--border);
+    border-radius: 6px;
+    padding: 8px 12px;
+    font-family: var(--mono);
+    font-size: 12px;
+    color: var(--text);
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    cursor: pointer;
+    transition: border-color 0.1s;
+  }
+
+  .sym-item:hover { border-color: var(--accent); }
+
+  .sym-file { color: var(--muted); }
+  .sym-name { color: var(--text); font-weight: 500; }
+  .sym-dot { color: var(--border); }
+
+  /* ── File groups in blast radius ── */
+  .file-group {
+    margin-bottom: 14px;
+  }
+
+  .file-label {
+    font-size: 11px;
+    color: var(--accent);
+    font-family: var(--mono);
+    margin-bottom: 6px;
+    display: flex;
+    align-items: center;
+    gap: 6px;
+  }
+
+  .file-fns {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 6px;
+  }
+
+  .fn-chip {
+    background: var(--surface2);
+    border: 1px solid var(--border);
+    padding: 3px 10px;
+    border-radius: 20px;
+    font-size: 11px;
+    font-family: var(--mono);
+    color: var(--text);
+  }
+
+  /* ── Code paste tab ── */
+  .code-file-row {
+    display: flex;
+    gap: 8px;
+    margin-bottom: 10px;
+    align-items: flex-start;
+  }
+
+  .code-file-name {
+    width: 160px;
+    flex-shrink: 0;
+  }
+
+  .code-remove {
+    background: none;
+    border: none;
+    color: var(--accent2);
+    cursor: pointer;
+    font-size: 16px;
+    padding: 8px;
+    opacity: 0.6;
+  }
+
+  .code-remove:hover { opacity: 1; }
+
+  /* ── Context output ── */
+  .context-out {
+    background: var(--surface2);
+    border: 1px solid var(--border);
+    border-radius: 8px;
+    padding: 16px;
+    font-family: var(--mono);
+    font-size: 12px;
+    white-space: pre-wrap;
+    max-height: 500px;
+    overflow-y: auto;
+    color: var(--text);
+    line-height: 1.6;
+  }
+
+  /* ── Status / error ── */
+  .status {
+    padding: 10px 14px;
+    border-radius: 8px;
+    font-size: 13px;
+    margin-bottom: 16px;
+    display: none;
+  }
+
+  .status.visible { display: block; }
+  .status.error   { background: rgba(255,107,107,0.1); border: 1px solid rgba(255,107,107,0.3); color: var(--accent2); }
+  .status.success { background: rgba(67,233,123,0.1);  border: 1px solid rgba(67,233,123,0.3);  color: var(--accent3); }
+  .status.loading { background: rgba(124,111,255,0.1); border: 1px solid rgba(124,111,255,0.3); color: var(--accent); }
+
+  /* ── Tip box ── */
+  .tip {
+    background: var(--surface2);
+    border-left: 3px solid var(--accent);
+    padding: 12px 16px;
+    border-radius: 0 8px 8px 0;
+    font-size: 12px;
+    color: var(--muted);
+    margin-bottom: 20px;
+    line-height: 1.6;
+  }
+
+  .tip strong { color: var(--text); }
+
+  /* ── Symbol picker ── */
+  .sym-picker {
+    max-height: 240px;
+    overflow-y: auto;
+    border: 1px solid var(--border);
+    border-radius: 8px;
+    background: var(--surface2);
+  }
+
+  .sym-picker-item {
+    padding: 8px 12px;
+    font-family: var(--mono);
+    font-size: 12px;
+    cursor: pointer;
+    border-bottom: 1px solid var(--border);
+    transition: background 0.1s;
+  }
+
+  .sym-picker-item:hover { background: rgba(124,111,255,0.1); }
+  .sym-picker-item:last-child { border-bottom: none; }
+
+  /* ── API docs callout ── */
+  .api-box {
+    background: var(--surface2);
+    border: 1px solid var(--border);
+    border-radius: 10px;
+    padding: 20px;
+    margin-top: 20px;
+  }
+
+  .api-endpoint {
+    display: flex;
+    align-items: center;
+    gap: 10px;
+    margin-bottom: 10px;
+  }
+
+  .method {
+    font-family: var(--mono);
+    font-size: 11px;
+    font-weight: 700;
+    padding: 2px 8px;
+    border-radius: 4px;
+  }
+
+  .method-post { background: rgba(124,111,255,0.2); color: var(--accent); }
+  .method-get  { background: rgba(67,233,123,0.2);  color: var(--accent3); }
+
+  .endpoint-path {
+    font-family: var(--mono);
+    font-size: 12px;
+    color: var(--text);
+  }
+
+  .endpoint-desc { font-size: 12px; color: var(--muted); }
+
+  /* ── Divider ── */
+  .divider { border: none; border-top: 1px solid var(--border); margin: 20px 0; }
+
+  /* ── Spinner ── */
+  @keyframes spin { to { transform: rotate(360deg); } }
+  .spinner {
+    display: inline-block;
+    width: 14px; height: 14px;
+    border: 2px solid rgba(255,255,255,0.2);
+    border-top-color: white;
+    border-radius: 50%;
+    animation: spin 0.6s linear infinite;
+  }
+
+  /* ── Pane visibility ── */
+  .pane { display: none; }
+  .pane.active { display: flex; flex: 1; overflow: hidden; }
+
+  /* ── Scrollbar ── */
+  ::-webkit-scrollbar { width: 6px; height: 6px; }
+  ::-webkit-scrollbar-track { background: transparent; }
+  ::-webkit-scrollbar-thumb { background: var(--border); border-radius: 3px; }
+</style>
+</head>
+<body>
+
+<header>
+  <div class="logo">Diff<span>Context</span></div>
+  <div class="tagline">Which functions break when you change one?</div>
+</header>
+
+<div class="tabs">
+  <div class="tab active" onclick="switchTab('upload')">📁 Upload Project</div>
+  <div class="tab" onclick="switchTab('paste')">📋 Paste Code</div>
+  <div class="tab" onclick="switchTab('api')">⚡ API & MCP</div>
+</div>
+
+<!-- ══════════════════ TAB: UPLOAD ══════════════════ -->
+<div class="pane active" id="pane-upload">
+  <div class="panel left">
+    <p class="section-title">Step 1 — Upload your project</p>
+
+    <div class="tip">
+      <strong>What to do:</strong> Zip your Python project folder, upload it here,
+      then pick a function to analyse. DiffContext will tell you what breaks if you change it.
+    </div>
+
+    <div class="upload-zone" id="uploadZone" onclick="document.getElementById('fileInput').click()">
+      <input type="file" id="fileInput" accept=".zip" style="display:none" onchange="handleUpload(this)">
+      <div class="upload-icon">📦</div>
+      <p><strong>Click to upload a .zip</strong></p>
+      <p>of your Python project</p>
+    </div>
+
+    <div id="uploadStatus" class="status"></div>
+
+    <div id="symbolSection" style="display:none">
+      <hr class="divider">
+      <p class="section-title">Step 2 — Pick a function</p>
+      <div class="input-group">
+        <label>Search functions</label>
+        <input type="text" id="symSearch" placeholder="type to filter..." oninput="filterSymbols()">
+      </div>
+      <div class="sym-picker" id="symPicker"></div>
+
+      <div class="input-group" style="margin-top:14px">
+        <label>Selected function</label>
+        <input type="text" id="selectedSym" placeholder="./file.py:function_name" readonly>
+      </div>
+
+      <button class="btn btn-primary btn-full" onclick="runBlast()" id="blastBtn">
+        ⚡ Analyse Blast Radius
+      </button>
+    </div>
+  </div>
+
+  <div class="panel right">
+    <div id="uploadResultArea" class="result-area">
+      <p class="section-title">Blast Radius Results</p>
+
+      <div class="stat-row">
+        <div class="stat-card">
+          <div class="stat-value" id="statCallers">—</div>
+          <div class="stat-label">Direct Callers</div>
+        </div>
+        <div class="stat-card">
+          <div class="stat-value" id="statCallees">—</div>
+          <div class="stat-label">Direct Callees</div>
+        </div>
+        <div class="stat-card">
+          <div class="stat-value" id="statBlast">—</div>
+          <div class="stat-label">Total Affected</div>
+        </div>
+      </div>
+
+      <div class="sym-section">
+        <div class="sym-header">
+          <span class="sym-badge badge-caller">▲ CALLERS</span>
+          <span style="font-size:12px;color:var(--muted)">These will break if you change the function</span>
+        </div>
+        <div class="sym-list" id="callerList"></div>
+      </div>
+
+      <div class="sym-section">
+        <div class="sym-header">
+          <span class="sym-badge badge-callee">▼ CALLEES</span>
+          <span style="font-size:12px;color:var(--muted)">Functions this one depends on</span>
+        </div>
+        <div class="sym-list" id="calleeList"></div>
+      </div>
+
+      <div class="sym-section">
+        <div class="sym-header">
+          <span class="sym-badge badge-blast">◉ BLAST RADIUS</span>
+          <span style="font-size:12px;color:var(--muted)">All transitively affected, by file</span>
+        </div>
+        <div id="blastByFile"></div>
+      </div>
+
+      <hr class="divider">
+      <button class="btn btn-secondary" onclick="getContext()" style="width:100%">
+        📋 Get LLM Context (paste into Claude)
+      </button>
+      <div id="contextOut" style="display:none;margin-top:14px">
+        <div class="sym-header" style="justify-content:space-between">
+          <span class="section-title" style="margin:0">Context ready to paste</span>
+          <button class="btn btn-secondary" onclick="copyContext()" style="padding:6px 12px;font-size:12px">Copy</button>
+        </div>
+        <div class="context-out" id="contextText"></div>
+      </div>
+    </div>
+
+    <div id="uploadEmpty" style="display:flex;align-items:center;justify-content:center;height:100%;flex-direction:column;gap:12px;color:var(--muted)">
+      <div style="font-size:48px">🎯</div>
+      <p>Upload a project and pick a function to see results here</p>
+    </div>
+  </div>
+</div>
+
+<!-- ══════════════════ TAB: PASTE ══════════��═══════ -->
+<div class="pane" id="pane-paste">
+  <div class="panel left">
+    <p class="section-title">Paste your Python code</p>
+
+    <div class="tip">
+      <strong>No upload needed.</strong> Paste one or more Python files below
+      and pick a function to analyse instantly.
+    </div>
+
+    <div id="codeFiles">
+      <div class="code-file-row" id="codeRow0">
+        <input class="code-file-name" type="text" value="main.py" placeholder="filename.py">
+        <textarea style="flex:1;height:140px;font-size:12px" placeholder="def greet(name):&#10;    msg = build_message(name)&#10;    print(msg)&#10;&#10;def build_message(name):&#10;    return f'Hello, {name}!'"></textarea>
+        <button class="code-remove" onclick="removeCodeFile(0)">✕</button>
+      </div>
+    </div>
+
+    <button class="btn btn-secondary" onclick="addCodeFile()" style="width:100%;margin-bottom:16px">
+      + Add another file
+    </button>
+
+    <div class="input-group">
+      <label>Function to analyse</label>
+      <input type="text" id="pasteSymbol" placeholder="./main.py:greet">
+    </div>
+
+    <div id="pasteStatus" class="status"></div>
+
+    <button class="btn btn-primary btn-full" onclick="runPasteBlast()">
+      ⚡ Analyse
+    </button>
+  </div>
+
+  <div class="panel right">
+    <div id="pasteResultArea" class="result-area">
+      <p class="section-title">Blast Radius Results</p>
+
+      <div class="stat-row">
+        <div class="stat-card">
+          <div class="stat-value" id="pStatCallers">—</div>
+          <div class="stat-label">Direct Callers</div>
+        </div>
+        <div class="stat-card">
+          <div class="stat-value" id="pStatCallees">—</div>
+          <div class="stat-label">Direct Callees</div>
+        </div>
+        <div class="stat-card">
+          <div class="stat-value" id="pStatBlast">—</div>
+          <div class="stat-label">Total Affected</div>
+        </div>
+      </div>
+
+      <div class="sym-section">
+        <div class="sym-header">
+          <span class="sym-badge badge-caller">▲ CALLERS</span>
+        </div>
+        <div class="sym-list" id="pCallerList"></div>
+      </div>
+
+      <div class="sym-section">
+        <div class="sym-header">
+          <span class="sym-badge badge-callee">▼ CALLEES</span>
+        </div>
+        <div class="sym-list" id="pCalleeList"></div>
+      </div>
+
+      <div class="sym-section">
+        <div class="sym-header">
+          <span class="sym-badge badge-blast">◉ BLAST RADIUS</span>
+        </div>
+        <div id="pBlastByFile"></div>
+      </div>
+    </div>
+
+    <div id="pasteEmpty" style="display:flex;align-items:center;justify-content:center;height:100%;flex-direction:column;gap:12px;color:var(--muted)">
+      <div style="font-size:48px">✏️</div>
+      <p>Paste some code and click Analyse</p>
+    </div>
+  </div>
+</div>
+
+<!-- ══════════════════ TAB: API ══════════════════ -->
+<div class="pane" id="pane-api">
+  <div class="panel" style="width:100%;max-width:820px;margin:0 auto">
+    <p class="section-title">API & MCP Integration</p>
+
+    <div class="tip" style="margin-bottom:24px">
+      Run DiffContext as a local server and call it from your own tools,
+      scripts, or connect it to Claude Desktop as an MCP server.
+    </div>
+
+    <div class="api-box">
+      <p style="font-size:14px;font-weight:600;margin-bottom:16px">🚀 Start the web server</p>
+      <div class="context-out" style="max-height:none">pip install fastapi uvicorn
+cd /path/to/Diffcontext
+uvicorn diffcontext-service.backend.main:app --reload --port 8000
+
+# Now open: http://localhost:8000/docs  ← interactive API docs</div>
+    </div>
+
+    <div class="api-box" style="margin-top:16px">
+      <p style="font-size:14px;font-weight:600;margin-bottom:16px">📡 REST API Endpoints</p>
+
+      <div class="api-endpoint">
+        <span class="method method-post">POST</span>
+        <span class="endpoint-path">/upload</span>
+        <span class="endpoint-desc">Upload a .zip of your project → get a repo_id</span>
+      </div>
+
+      <div class="api-endpoint">
+        <span class="method method-get">GET</span>
+        <span class="endpoint-path">/symbols?repo_id=abc123</span>
+        <span class="endpoint-desc">List all functions in your project</span>
+      </div>
+
+      <div class="api-endpoint">
+        <span class="method method-post">POST</span>
+        <span class="endpoint-path">/blast</span>
+        <span class="endpoint-desc">Get blast radius for a function</span>
+      </div>
+
+      <div class="api-endpoint">
+        <span class="method method-post">POST</span>
+        <span class="endpoint-path">/inline</span>
+        <span class="endpoint-desc">Analyse pasted code (no upload needed)</span>
+      </div>
+
+      <div class="api-endpoint">
+        <span class="method method-post">POST</span>
+        <span class="endpoint-path">/compile</span>
+        <span class="endpoint-desc">Get LLM-ready context string</span>
+      </div>
+
+      <hr class="divider">
+
+      <p style="font-size:12px;color:var(--muted);margin-bottom:10px">Example — call from Python:</p>
+      <div class="context-out" style="max-height:none">import requests
+
+# 1. Upload your project
+with open("myproject.zip", "rb") as f:
+    r = requests.post("http://localhost:8000/upload", files={"file": f})
+repo_id = r.json()["repo_id"]
+
+# 2. Get blast radius
+r = requests.post("http://localhost:8000/blast", json={
+    "repo_id": repo_id,
+    "symbol": "./src/auth.py:validate_jwt"
+})
+print(r.json())
+
+# 3. Get LLM context
+r = requests.post("http://localhost:8000/compile", json={
+    "repo_id": repo_id,
+    "symbol": "./src/auth.py:validate_jwt",
+    "max_tokens": 8000
+})
+print(r.json()["context_text"])  # paste this into Claude</div>
+    </div>
+
+    <div class="api-box" style="margin-top:16px">
+      <p style="font-size:14px;font-weight:600;margin-bottom:16px">🤖 Connect to Claude Desktop (MCP)</p>
+
+      <p style="font-size:12px;color:var(--muted);margin-bottom:10px">1. Install MCP package:</p>
+      <div class="context-out" style="max-height:none">pip install mcp</div>
+
+      <p style="font-size:12px;color:var(--muted);margin:12px 0 6px">2. Add to Claude Desktop config:</p>
+      <p style="font-size:11px;color:var(--muted);margin-bottom:8px">
+        Mac: <code style="color:var(--accent)">~/Library/Application Support/Claude/claude_desktop_config.json</code><br>
+        Windows: <code style="color:var(--accent)">%APPDATA%\Claude\claude_desktop_config.json</code>
+      </p>
+      <div class="context-out" style="max-height:none">{
+  "mcpServers": {
+    "diffcontext": {
+      "command": "python",
+      "args": ["/path/to/Diffcontext/diffcontext-service/mcp/mcp_server.py"]
+    }
+  }
+}</div>
+
+      <p style="font-size:12px;color:var(--muted);margin:12px 0 6px">3. Restart Claude Desktop, then ask:</p>
+      <div class="context-out" style="max-height:none">"List all functions in /Users/me/myproject"
+"What is the blast radius of ./src/auth.py:validate_jwt in /Users/me/myproject?"
+"Compile context for ./service.py:onboard_user in /Users/me/myproject"</div>
+    </div>
+  </div>
+</div>
+
+<script>
+// ── State ────────────────────────────────────────────────────────────────────
+const API = 'http://localhost:8000';
+let repoId = null;
+let allSymbols = [];
+let codeFileCount = 1;
+let lastBlastResult = null;
+
+// ── Tab switching ─────────────────────────────────────────────────────────────
+function switchTab(tab) {
+  document.querySelectorAll('.tab').forEach((t, i) => {
+    t.classList.toggle('active', ['upload','paste','api'][i] === tab);
+  });
+  document.querySelectorAll('.pane').forEach(p => p.classList.remove('active'));
+  document.getElementById(`pane-${tab}`).classList.add('active');
+}
+
+// ── Status helpers ─────────────────────────────────────────────────────────────
+function setStatus(id, msg, type) {
+  const el = document.getElementById(id);
+  el.className = `status visible ${type}`;
+  el.textContent = msg;
+}
+
+function clearStatus(id) {
+  const el = document.getElementById(id);
+  el.className = 'status';
+}
+
+// ── Drag & drop ───────────────────────────────────────────────────────────────
+const uploadZone = document.getElementById('uploadZone');
+uploadZone.addEventListener('dragover', e => { e.preventDefault(); uploadZone.classList.add('drag-over'); });
+uploadZone.addEventListener('dragleave', () => uploadZone.classList.remove('drag-over'));
+uploadZone.addEventListener('drop', e => {
+  e.preventDefault();
+  uploadZone.classList.remove('drag-over');
+  const file = e.dataTransfer.files[0];
+  if (file) doUpload(file);
+});
+
+// ── Upload ────────────────────────────────────────────────────────────────────
+function handleUpload(input) {
+  if (input.files[0]) doUpload(input.files[0]);
+}
+
+async function doUpload(file) {
+  setStatus('uploadStatus', '⏳ Uploading and analysing...', 'loading');
+
+  const form = new FormData();
+  form.append('file', file);
+
+  try {
+    const r = await fetch(`${API}/upload`, { method: 'POST', body: form });
+    const data = await r.json();
+
+    if (!r.ok) {
+      setStatus('uploadStatus', data.detail || 'Upload failed.', 'error');
+      return;
+    }
+
+    repoId = data.repo_id;
+    allSymbols = data.sample_symbols || [];
+
+    // Fetch full symbol list
+    const symR = await fetch(`${API}/symbols?repo_id=${repoId}`);
+    if (symR.ok) {
+      const symData = await symR.json();
+      allSymbols = symData.symbols || [];
+    }
+
+    setStatus('uploadStatus', `✓ ${data.message}`, 'success');
+    document.getElementById('symbolSection').style.display = 'block';
+    renderSymbolPicker(allSymbols);
+
+  } catch (e) {
+    setStatus('uploadStatus',
+      'Could not connect to DiffContext server. Make sure it\'s running on localhost:8000',
+      'error'
+    );
+  }
+}
+
+// ── Symbol picker ──────────────────────────────────────────────────────────────
+function renderSymbolPicker(syms) {
+  const picker = document.getElementById('symPicker');
+  picker.innerHTML = syms.slice(0, 100).map(s => {
+    const [file, fn] = s.split(':');
+    return `<div class="sym-picker-item" onclick="selectSymbol('${s}')">
+      <span style="color:var(--muted);font-size:11px">${file}</span>
+      <span style="color:var(--text);font-weight:500">:${fn}</span>
+    </div>`;
+  }).join('');
+}
+
+function filterSymbols() {
+  const q = document.getElementById('symSearch').value.toLowerCase();
+  const filtered = allSymbols.filter(s => s.toLowerCase().includes(q));
+  renderSymbolPicker(filtered);
+}
+
+function selectSymbol(sym) {
+  document.getElementById('selectedSym').value = sym;
+  document.querySelectorAll('.sym-picker-item').forEach(el => {
+    el.style.background = el.textContent.includes(sym.split(':')[1]) ?
+      'rgba(124,111,255,0.15)' : '';
+  });
+}
+
+// ── Blast radius ───────────────────────────────────────────────────────────────
+async function runBlast() {
+  const symbol = document.getElementById('selectedSym').value.trim();
+  if (!symbol) { alert('Pick a function first.'); return; }
+  if (!repoId) { alert('Upload a project first.'); return; }
+
+  const btn = document.getElementById('blastBtn');
+  btn.innerHTML = '<span class="spinner"></span> Analysing...';
+  btn.disabled = true;
+
+  try {
+    const r = await fetch(`${API}/blast`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ repo_id: repoId, symbol }),
+    });
+    const data = await r.json();
+
+    if (data.error) {
+      setStatus('uploadStatus', data.error + (data.suggestions ? ' Did you mean: ' + data.suggestions.join(', ') : ''), 'error');
+      return;
+    }
+
+    lastBlastResult = data;
+    renderBlastResults(data, 'upload');
+    document.getElementById('uploadEmpty').style.display = 'none';
+    document.getElementById('uploadResultArea').classList.add('visible');
+    document.getElementById('contextOut').style.display = 'none';
+
+  } catch (e) {
+    setStatus('uploadStatus', 'Server not reachable. Is it running?', 'error');
+  } finally {
+    btn.innerHTML = '⚡ Analyse Blast Radius';
+    btn.disabled = false;
+  }
+}
+
+function renderBlastResults(data, prefix) {
+  const p = prefix === 'upload' ? '' : 'p';
+  const cap = s => s.charAt(0).toUpperCase() + s.slice(1);
+
+  document.getElementById(`${p}stat${p ? cap('Callers') : 'Callers'}`).textContent = data.direct_callers?.length ?? 0;
+  document.getElementById(`${p}stat${p ? cap('Callees') : 'Callees'}`).textContent = data.direct_callees?.length ?? 0;
+  document.getElementById(`${p}stat${p ? cap('Blast') : 'Blast'}`).textContent = data.blast_radius_count ?? 0;
+
+  // Helpers
+  const symItem = sym => {
+    const parts = sym.split(':');
+    return `<div class="sym-item">
+      <span class="sym-file">${parts[0]}</span>
+      <span class="sym-dot">:</span>
+      <span class="sym-name">${parts[1] || sym}</span>
+    </div>`;
+  };
+
+  const listEl = (id, items) => {
+    const el = document.getElementById(id);
+    el.innerHTML = items?.length
+      ? items.map(symItem).join('')
+      : '<div style="color:var(--muted);font-size:12px;padding:8px">(none found)</div>';
+  };
+
+  listEl(`${p === 'p' ? 'p' : ''}CallerList`, data.direct_callers);
+  listEl(`${p === 'p' ? 'p' : ''}CalleeList`, data.direct_callees);
+
+  const blastEl = document.getElementById(`${p === 'p' ? 'p' : ''}BlastByFile`);
+  const byFile = data.blast_radius_by_file || {};
+  if (Object.keys(byFile).length === 0) {
+    blastEl.innerHTML = '<div style="color:var(--muted);font-size:12px;padding:8px">(no transitive impact found)</div>';
+  } else {
+    blastEl.innerHTML = Object.entries(byFile).map(([file, fns]) => `
+      <div class="file-group">
+        <div class="file-label">📄 ${file} (${fns.length})</div>
+        <div class="file-fns">${fns.map(f => `<span class="fn-chip">${f}</span>`).join('')}</div>
+      </div>
+    `).join('');
+  }
+}
+
+// Fix the IDs for paste tab
+function renderBlastResults(data, tab) {
+  if (tab === 'upload') {
+    document.getElementById('statCallers').textContent = data.direct_callers?.length ?? 0;
+    document.getElementById('statCallees').textContent = data.direct_callees?.length ?? 0;
+    document.getElementById('statBlast').textContent = data.blast_radius_count ?? 0;
+    _renderList('callerList', data.direct_callers);
+    _renderList('calleeList', data.direct_callees);
+    _renderByFile('blastByFile', data.blast_radius_by_file);
+  } else {
+    document.getElementById('pStatCallers').textContent = data.direct_callers?.length ?? 0;
+    document.getElementById('pStatCallees').textContent = data.direct_callees?.length ?? 0;
+    document.getElementById('pStatBlast').textContent = data.blast_radius_count ?? 0;
+    _renderList('pCallerList', data.direct_callers);
+    _renderList('pCalleeList', data.direct_callees);
+    _renderByFile('pBlastByFile', data.blast_radius_by_file);
+  }
+}
+
+function _renderList(id, items) {
+  const el = document.getElementById(id);
+  el.innerHTML = items?.length
+    ? items.map(sym => {
+        const parts = sym.split(':');
+        return `<div class="sym-item">
+          <span class="sym-file">${parts[0]}</span>
+          <span class="sym-dot">:</span>
+          <span class="sym-name">${parts[1] || sym}</span>
+        </div>`;
+      }).join('')
+    : '<div style="color:var(--muted);font-size:12px;padding:8px">(none found)</div>';
+}
+
+function _renderByFile(id, byFile) {
+  const el = document.getElementById(id);
+  const obj = byFile || {};
+  if (!Object.keys(obj).length) {
+    el.innerHTML = '<div style="color:var(--muted);font-size:12px;padding:8px">(no transitive impact)</div>';
+    return;
+  }
+  el.innerHTML = Object.entries(obj).map(([file, fns]) => `
+    <div class="file-group">
+      <div class="file-label">📄 ${file} (${fns.length})</div>
+      <div class="file-fns">${fns.map(f => `<span class="fn-chip">${f}</span>`).join('')}</div>
+    </div>
+  `).join('');
+}
+
+// ── Get LLM context ────────────────────────────────────────────────────────────
+async function getContext() {
+  const symbol = document.getElementById('selectedSym').value.trim();
+  if (!symbol || !repoId) return;
+
+  const btn = event.target;
+  btn.textContent = '⏳ Compiling...';
+  btn.disabled = true;
+
+  try {
+    const r = await fetch(`${API}/compile`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ repo_id: repoId, symbol, max_tokens: 8000 }),
+    });
+    const data = await r.json();
+
+    document.getElementById('contextText').textContent = data.context_text || JSON.stringify(data, null, 2);
+    document.getElementById('contextOut').style.display = 'block';
+  } catch (e) {
+    alert('Could not compile context. Is the server running?');
+  } finally {
+    btn.textContent = '📋 Get LLM Context (paste into Claude)';
+    btn.disabled = false;
+  }
+}
+
+function copyContext() {
+  const text = document.getElementById('contextText').textContent;
+  navigator.clipboard.writeText(text).then(() => {
+    const btn = event.target;
+    btn.textContent = '✓ Copied!';
+    setTimeout(() => btn.textContent = 'Copy', 1500);
+  });
+}
+
+// ── Paste tab ─────────────────────────────────────────────────────────────────
+function addCodeFile() {
+  const container = document.getElementById('codeFiles');
+  const idx = codeFileCount++;
+  const row = document.createElement('div');
+  row.className = 'code-file-row';
+  row.id = `codeRow${idx}`;
+  row.innerHTML = `
+    <input class="code-file-name" type="text" value="file${idx}.py" placeholder="filename.py">
+    <textarea style="flex:1;height:140px;font-size:12px" placeholder="def my_function(): ..."></textarea>
+    <button class="code-remove" onclick="removeCodeFile(${idx})">✕</button>
+  `;
+  container.appendChild(row);
+}
+
+function removeCodeFile(idx) {
+  const row = document.getElementById(`codeRow${idx}`);
+  if (row) row.remove();
+}
+
+async function runPasteBlast() {
+  const symbol = document.getElementById('pasteSymbol').value.trim();
+  if (!symbol) { setStatus('pasteStatus', 'Enter a function name like ./main.py:greet', 'error'); return; }
+
+  const files = {};
+  document.querySelectorAll('.code-file-row').forEach(row => {
+    const name = row.querySelector('input').value.trim();
+    const code = row.querySelector('textarea').value.trim();
+    if (name && code) files[name] = code;
+  });
+
+  if (!Object.keys(files).length) {
+    setStatus('pasteStatus', 'Paste some Python code first.', 'error');
+    return;
+  }
+
+  setStatus('pasteStatus', '⏳ Analysing...', 'loading');
+
+  try {
+    const r = await fetch(`${API}/inline`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ files, symbol }),
+    });
+    const data = await r.json();
+
+    clearStatus('pasteStatus');
+
+    if (data.error) {
+      setStatus('pasteStatus', data.error + (data.suggestions ? ' Try: ' + data.suggestions.join(', ') : ''), 'error');
+      return;
+    }
+
+    renderBlastResults(data, 'paste');
+    document.getElementById('pasteEmpty').style.display = 'none';
+    document.getElementById('pasteResultArea').classList.add('visible');
+
+  } catch (e) {
+    setStatus('pasteStatus', 'Could not reach server. Is it running on localhost:8000?', 'error');
+  }
+}
+</script>
+</body>
+</html>

diffcontext-service/mcp/mcp_server.py

@@ -0,0 +1,19 @@
+"""
+DiffContext MCP Server Wrapper
+Forwards execution to the package-level mcp_server module.
+"""
+
+import sys
+from pathlib import Path
+
+# Add the project root to sys.path so we can import diffcontext
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent.parent))
+
+try:
+    from diffcontext.mcp_server import main
+except ImportError as e:
+    print(f"Error: Could not import diffcontext.mcp_server: {e}", file=sys.stderr)
+    sys.exit(1)
+
+if __name__ == "__main__":
+    main()

diffcontext/__init__.py

@@ -0,0 +1,199 @@
+"""
+DiffContext — static-analysis-powered repository context compiler for LLMs.
+
+Converts code changes into dependency-aware, blast-radius-aware context
+packages, enabling far more accurate code understanding than keyword search
+or traditional RAG.
+
+Usage as a library:
+
+    from diffcontext import blast_radius, index, diff, compile_context
+
+    # Get blast radius for a symbol
+    result = blast_radius("./auth.py:validate_jwt", repo="/path/to/project")
+    print(result.callers)          # who calls this?
+    print(result.dependencies)     # what does this call?
+    print(result.total_affected)   # total transitive impact
+
+    # Auto-detect changes and get blast radius
+    result = blast_radius(ref="HEAD~1", repo="/path/to/project")
+
+    # Index a repository
+    idx = index("/path/to/project")
+    print(idx.symbols)    # all parsed symbols
+    print(idx.graph)      # call graph
+
+    # Find changed symbols from git diff
+    changed = diff(repo="/path/to/project", ref="HEAD~1")
+
+    # Full context compilation for LLMs
+    ctx = compile_context(ref="HEAD~1", repo="/path/to/project")
+    print(ctx.text)             # LLM-ready context
+    print(ctx.reduction_pct)    # how much code was filtered out
+"""
+
+__version__ = "0.2.0"
+
+import os
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional
+
+from .pipeline import index_repository, analyze_impact
+from .pipeline import compile as _compile_pipeline
+from .diff.git_diff import find_changed_symbols
+from .impact.blast_radius import get_blast_radius
+
+
+# ---------------------------------------------------------------------------
+# Public data classes
+# ---------------------------------------------------------------------------
+
+@dataclass
+class BlastResult:
+    """Result of a blast radius analysis — the public API return type."""
+    changed: List[str]
+    callers: List[str]
+    dependencies: List[str]
+    total_affected: int
+    scores: Dict[str, float] = field(default_factory=dict)
+    graph: Dict[str, List[str]] = field(default_factory=dict)
+
+    @property
+    def affected_files(self) -> List[str]:
+        """Unique files in the blast radius."""
+        files = set()
+        for sym in self.callers:
+            parts = sym.split(":", 1)
+            if len(parts) == 2:
+                files.add(parts[0])
+        return sorted(files)
+
+    def __repr__(self):
+        return (
+            f"BlastResult(changed={len(self.changed)}, "
+            f"callers={len(self.callers)}, "
+            f"dependencies={len(self.dependencies)}, "
+            f"total_affected={self.total_affected})"
+        )
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def blast_radius(
+    symbol: Optional[str] = None,
+    *,
+    ref: Optional[str] = None,
+    repo: str = ".",
+    depth: int = 3,
+) -> BlastResult:
+    """
+    Compute the blast radius of a change.
+
+    Args:
+        symbol: Symbol ID like "./auth.py:validate_jwt". If None, uses `ref`.
+        ref:    Git ref to auto-detect changes (e.g. "HEAD~1").
+        repo:   Path to the repository root.
+        depth:  Max traversal depth.
+
+    Returns:
+        BlastResult with callers, dependencies, scores, etc.
+
+    Examples:
+        >>> from diffcontext import blast_radius
+        >>> r = blast_radius("./auth.py:validate_jwt", repo="/path/to/project")
+        >>> r = blast_radius(ref="HEAD~1", repo="/path/to/project")
+    """
+    idx = index_repository(repo)
+
+    # Determine changed symbols
+    if symbol:
+        changed = [symbol]
+    elif ref:
+        changed = find_changed_symbols(repo, idx.symbols, ref=ref)
+    else:
+        changed = find_changed_symbols(repo, idx.symbols, ref="HEAD~1")
+
+    if not changed:
+        return BlastResult(
+            changed=[], callers=[], dependencies=[],
+            total_affected=0, scores={}, graph=idx.graph,
+        )
+
+    impact = analyze_impact(idx, changed, max_depth=depth)
+
+    return BlastResult(
+        changed=impact.changed,
+        callers=impact.blast_radius,
+        dependencies=impact.dependencies,
+        total_affected=len(impact.all_relevant),
+        scores=impact.scores,
+        graph=idx.graph,
+    )
+
+
+def index(repo: str = "."):
+    """
+    Index a repository: parse all Python files and build the call graph.
+
+    Returns a RepositoryIndex with .symbols and .graph attributes.
+
+    Example:
+        >>> from diffcontext import index
+        >>> idx = index("/path/to/project")
+        >>> len(idx.symbols)
+        354
+    """
+    return index_repository(repo)
+
+
+def diff(repo: str = ".", ref: str = "HEAD~1") -> List[str]:
+    """
+    Find changed symbol IDs from git diff.
+
+    Returns list of symbol IDs that were modified.
+
+    Example:
+        >>> from diffcontext import diff
+        >>> diff(repo="/path/to/project", ref="HEAD~1")
+        ['./auth.py:validate_jwt', './models.py:User.__init__']
+    """
+    idx = index_repository(repo)
+    return find_changed_symbols(repo, idx.symbols, ref=ref)
+
+
+def compile_context(
+    symbol: Optional[str] = None,
+    *,
+    ref: Optional[str] = None,
+    repo: str = ".",
+    depth: int = 2,
+    max_tokens: int = 10000,
+):
+    """
+    Full pipeline: detect changes → blast radius → compile LLM context.
+
+    Returns a ContextPackage with .text, .token_estimate, .reduction_pct.
+
+    Example:
+        >>> from diffcontext import compile_context
+        >>> ctx = compile_context(ref="HEAD~1", repo="/path/to/project")
+        >>> print(ctx.text)          # LLM-ready context
+        >>> print(ctx.reduction_pct) # e.g. 99.2
+    """
+    idx = index_repository(repo)
+
+    if symbol:
+        changed = [symbol]
+    elif ref:
+        changed = find_changed_symbols(repo, idx.symbols, ref=ref)
+    else:
+        changed = find_changed_symbols(repo, idx.symbols, ref="HEAD~1")
+
+    if not changed:
+        from .models import ContextPackage
+        return ContextPackage(text="", symbol_count=0, token_estimate=0, total_repo_tokens=0)
+
+    impact = analyze_impact(idx, changed, max_depth=depth)
+    return _compile_pipeline(idx, impact, max_tokens=max_tokens)

diffcontext/_warn_once.py

@@ -0,0 +1,73 @@
+"""
+_warn_once.py — De-duplicate repeated warnings for the same file.
+
+parser.py, graph_builder.py, and resolver.py each independently call
+ast.parse() on every file. When a file has a syntax error, all three would
+otherwise log their own identical warning. This module tracks which files
+have already been warned about (per process run) so only the first one
+actually prints.
+
+Also covers invalid-UTF-8 source files: these are read with
+errors="ignore", which silently DROPS any byte that isn't valid UTF-8 with
+no warning, anywhere. A dropped byte inside a string literal corrupts that
+literal's contents (e.g. "Café Menu" -> "Caf Menu") without raising any
+error or appearing in any log -- the file still parses fine, the symbol
+still extracts fine, the code text is just silently wrong. warn_encoding_
+issue_once exists so this corruption is at least visible once per file.
+"""
+
+import logging
+import os
+import threading
+from typing import Set
+
+_warned_files: Set[str] = set()
+_warned_encoding_files: Set[str] = set()
+_lock = threading.Lock()
+
+
+def warn_syntax_error_once(logger: logging.Logger, filename: str, exc: SyntaxError) -> None:
+    """Log a SyntaxError warning for `filename`, but only the first time it's seen."""
+    key = os.path.abspath(filename)
+    with _lock:
+        if key in _warned_files:
+            return
+        _warned_files.add(key)
+
+    logger.warning(
+        "\033[93mSkipping %s due to SyntaxError: %s (line %s)\033[0m",
+        os.path.basename(filename), exc.msg, exc.lineno,
+    )
+
+
+def check_and_warn_encoding(logger: logging.Logger, filename: str, raw_bytes: bytes) -> None:
+    """
+    Check whether `raw_bytes` is valid UTF-8. If not, warn once per file --
+    the caller will go on to decode with errors="ignore", which silently
+    drops the offending bytes (and anything that decoded incorrectly around
+    them). This doesn't stop processing; it just makes the data loss
+    visible instead of completely silent.
+    """
+    try:
+        raw_bytes.decode("utf-8")
+        return
+    except UnicodeDecodeError as e:
+        key = os.path.abspath(filename)
+        with _lock:
+            if key in _warned_encoding_files:
+                return
+            _warned_encoding_files.add(key)
+
+        logger.warning(
+            "\033[93m%s is not valid UTF-8 (%s at byte %d) -- invalid bytes "
+            "will be silently dropped, which can corrupt string literals "
+            "in the extracted code\033[0m",
+            os.path.basename(filename), e.reason, e.start,
+        )
+
+
+def reset_warned_files() -> None:
+    """Clear the de-dup caches. Mainly useful for tests."""
+    with _lock:
+        _warned_files.clear()
+        _warned_encoding_files.clear()

diffcontext/cache.py

@@ -0,0 +1,115 @@
+"""
+cache.py — SQLite-backed persistent caching for AST parsed symbols.
+"""
+
+import hashlib
+import sqlite3
+import os
+from contextlib import contextmanager
+from typing import Dict, Callable
+
+from .models import Symbol
+
+
+def get_file_hash(filepath: str) -> str:
+    """Compute SHA-256 hash of a file."""
+    hasher = hashlib.sha256()
+    with open(filepath, "rb") as f:
+        # Python files are small enough to read into memory safely
+        hasher.update(f.read())
+    return hasher.hexdigest()
+
+
+class SymbolCache:
+    """Persistent SQLite cache for parsed AST symbols."""
+
+    def __init__(self, db_path: str = ".diffcontext_cache.db"):
+        self.db_path = db_path
+        self._conn = None
+        self._connect()
+
+    def _connect(self):
+        if self._conn is None:
+            self._conn = sqlite3.connect(self.db_path)
+            self._conn.execute("PRAGMA journal_mode=WAL")
+            self._conn.execute("PRAGMA foreign_keys=ON")
+            self._init_db()
+            
+    def close(self):
+        if self._conn:
+            self._conn.close()
+            self._conn = None
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.close()
+
+    def _init_db(self):
+        with self._conn:
+            self._conn.executescript('''
+                CREATE TABLE IF NOT EXISTS files (
+                    file_path TEXT PRIMARY KEY,
+                    file_hash TEXT NOT NULL
+                );
+                
+                CREATE TABLE IF NOT EXISTS symbols (
+                    id TEXT PRIMARY KEY,
+                    file_path TEXT NOT NULL,
+                    name TEXT NOT NULL,
+                    code TEXT NOT NULL,
+                    lineno INTEGER,
+                    FOREIGN KEY(file_path) REFERENCES files(file_path) ON DELETE CASCADE
+                );
+                
+                CREATE INDEX IF NOT EXISTS idx_symbols_file ON symbols(file_path);
+            ''')
+
+    def get_or_parse(self, filepath: str, parse_fn: Callable[[str], Dict[str, Symbol]]) -> Dict[str, Symbol]:
+        """
+        Return cached symbols if file hash matches, otherwise parse and persist.
+        """
+        file_hash = get_file_hash(filepath)
+        
+        cursor = self._conn.execute("SELECT file_hash FROM files WHERE file_path = ?", (filepath,))
+        row = cursor.fetchone()
+        
+        if row and row[0] == file_hash:
+            # Cache hit!
+            cursor = self._conn.execute(
+                "SELECT id, file_path, name, code, lineno FROM symbols WHERE file_path = ?", 
+                (filepath,)
+            )
+            symbols = {}
+            for row in cursor:
+                sym_id, f_path, name, code, lineno = row
+                symbols[sym_id] = Symbol(
+                    id=sym_id, 
+                    file=f_path, 
+                    name=name, 
+                    code=code, 
+                    lineno=lineno
+                )
+            return symbols
+            
+        # Cache miss or hash mismatch -> parse it
+        symbols = parse_fn(filepath)
+        
+        # Persist the new state
+        with self._conn:
+            # DELETE CASCADE will drop all existing symbols for this file
+            self._conn.execute("DELETE FROM files WHERE file_path = ?", (filepath,))
+            
+            self._conn.execute(
+                "INSERT INTO files (file_path, file_hash) VALUES (?, ?)", 
+                (filepath, file_hash)
+            )
+            
+            if symbols:
+                self._conn.executemany(
+                    "INSERT INTO symbols (id, file_path, name, code, lineno) VALUES (?, ?, ?, ?, ?)",
+                    [(s.id, s.file, s.name, s.code, s.lineno) for s in symbols.values()]
+                )
+                
+        return symbols

diffcontext/cli/__init__.py

@@ -0,0 +1,486 @@
+"""
+cli/main.py — DiffContext command-line interface.
+
+Usage:
+    diffcontext index .
+    diffcontext impact auth.py:validate_jwt
+    diffcontext diff HEAD~1
+    diffcontext compile --changed ./api.py:get_user
+    diffcontext blast --ref HEAD~1          # visual blast radius
+    diffcontext blast --ref HEAD~1 --verify # with proof chains
+"""
+
+import argparse
+import json
+import logging
+import os
+import sys
+import time
+
+from ..pipeline import index_repository, analyze_impact, compile, warn_unknown_symbols
+from ..diff.git_diff import find_changed_symbols
+from ..impact.visualizer import render_blast_radius, render_verification
+
+
+def main():
+    # Make sure warnings from anywhere in the pipeline (broken files,
+    # invalid encoding, unknown --changed symbols) are actually visible.
+    # Without this, they depend on logging's lastResort fallback, which is
+    # unreliable -- some warnings showed up by accident, others silently
+    # didn't, depending on subtle propagation/level details.
+    logging.basicConfig(level=logging.WARNING, format="%(message)s", stream=sys.stderr)
+
+    parser = argparse.ArgumentParser(
+        prog="diffcontext",
+        description="Static-analysis-powered repository context compiler for LLMs",
+    )
+    sub = parser.add_subparsers(dest="command", help="Available commands")
+
+    # --- index ---
+    p_index = sub.add_parser("index", help="Index a repository")
+    p_index.add_argument("repo", default=".", nargs="?", help="Path to repository")
+
+    # --- impact ---
+    p_impact = sub.add_parser("impact", help="Analyze impact of a symbol change")
+    p_impact.add_argument("symbols", nargs="+", help="Changed symbol IDs (e.g. ./auth.py:validate_jwt)")
+    p_impact.add_argument("--repo", default=".", help="Repository path")
+    p_impact.add_argument("--depth", type=int, default=2, help="Max dependency depth")
+    p_impact.add_argument("--tree", action="store_true", help="Show visual blast radius tree")
+    p_impact.add_argument("--verify", action="store_true", help="Show proof chains for each edge")
+
+    # --- diff ---
+    p_diff = sub.add_parser("diff", help="Find changed symbols from git diff")
+    p_diff.add_argument("ref", default="HEAD~1", nargs="?", help="Git ref to compare against")
+    p_diff.add_argument("--repo", default=".", help="Repository path")
+    p_diff.add_argument(
+        "--committed-only", action="store_true",
+        help="Compare two commits only (ref vs HEAD); ignores uncommitted working-tree changes",
+    )
+
+    # --- compile ---
+    p_compile = sub.add_parser("compile", help="Build LLM context for changes")
+    p_compile.add_argument("--changed", nargs="+", help="Changed symbol IDs")
+    p_compile.add_argument("--ref", default=None, help="Git ref (auto-detect changes)")
+    p_compile.add_argument("--repo", default=".", help="Repository path")
+    p_compile.add_argument("--depth", type=int, default=2, help="Max dependency depth")
+    p_compile.add_argument("--max-tokens", type=int, default=10000, help="Token budget")
+    p_compile.add_argument("--notes", type=str, default=None, help="Developer notes to prepend to the context output")
+    p_compile.add_argument("--json", action="store_true", help="Output as JSON")
+    p_compile.add_argument("--sync", action="store_true", help="Sync output to CtxSync cloud")
+
+    # --- blast (NEW: visual blast radius) ---
+    p_blast = sub.add_parser("blast", help="Visual blast radius analysis")
+    p_blast.add_argument("--changed", nargs="+", help="Changed symbol IDs (manual)")
+    p_blast.add_argument("--ref", default=None, help="Git ref (auto-detect changes)")
+    p_blast.add_argument("--repo", default=".", help="Repository path")
+    p_blast.add_argument("--depth", type=int, default=3, help="Max traversal depth for tree")
+    p_blast.add_argument("--verify", action="store_true", help="Show proof chains for each edge")
+    p_blast.add_argument("--no-color", action="store_true", help="Disable ANSI colors")
+    p_blast.add_argument(
+        "--committed-only", action="store_true",
+        help="Compare two commits only (ref vs HEAD); ignores uncommitted working-tree changes",
+    )
+
+    # --- sync (push blast radius to CtxSync cloud) ---
+    p_sync = sub.add_parser("sync", help="Compile and push context to CtxSync cloud")
+    p_sync.add_argument("--ref", default="HEAD~1", help="Git ref to diff against (default: HEAD~1)")
+    p_sync.add_argument("--repo", default=".", help="Repository path")
+    p_sync.add_argument("--depth", type=int, default=2, help="Max dependency depth")
+    p_sync.add_argument("--max-tokens", type=int, default=10000, help="Token budget")
+    p_sync.add_argument("--project", default=None, help="Project name (default: repo directory name)")
+    p_sync.add_argument("--url", default=None, help="CtxSync URL (or set CTXSYNC_URL env var)")
+    p_sync.add_argument("--key", default=None, help="CtxSync API key (or set CTXSYNC_KEY env var)")
+
+    args = parser.parse_args()
+
+    if args.command is None:
+        parser.print_help()
+        sys.exit(1)
+
+    if args.command == "index":
+        _cmd_index(args)
+    elif args.command == "impact":
+        _cmd_impact(args)
+    elif args.command == "diff":
+        _cmd_diff(args)
+    elif args.command == "compile":
+        _cmd_compile(args)
+    elif args.command == "blast":
+        _cmd_blast(args)
+    elif args.command == "sync":
+        _cmd_sync(args)
+
+
+def _cmd_index(args):
+    """Index repository: show stats."""
+    t0 = time.perf_counter()
+    idx = index_repository(args.repo)
+    elapsed = (time.perf_counter() - t0) * 1000
+
+    print(f"Symbols : {len(idx.symbols)}")
+    print(f"Edges   : {idx.total_edges}")
+    print(f"Time    : {elapsed:.0f}ms")
+
+    # Show top-level breakdown
+    files = set()
+    for sym in idx.symbols.values():
+        files.add(sym.file)
+    print(f"Files   : {len(files)}")
+
+    if idx.broken_files:
+        print(f"Broken  : {len(idx.broken_files)} file(s) failed to parse (see warnings above)")
+
+
+def _cmd_impact(args):
+    """Analyze impact of specific symbol changes."""
+    idx = index_repository(args.repo)
+    impact = analyze_impact(idx, args.symbols, max_depth=args.depth)
+
+    if getattr(args, 'tree', False) or getattr(args, 'verify', False):
+        # Visual tree mode
+        output = render_blast_radius(
+            idx.graph, args.symbols, idx.symbols,
+            max_depth=args.depth,
+            show_proof=getattr(args, 'verify', False),
+            repo_path=os.path.abspath(args.repo),
+        )
+        print(output)
+
+        if getattr(args, 'verify', False):
+            verification = render_verification(
+                idx.graph, args.symbols, idx.symbols,
+            )
+            print(verification)
+    else:
+        # Original text mode
+        print(f"\nChanged: {impact.changed}")
+        print(f"\nBlast radius ({len(impact.blast_radius)}):")
+        for sym in impact.blast_radius[:20]:
+            score = impact.scores.get(sym, 0)
+            print(f"  {sym} (score: {score:.0f})")
+
+        print(f"\nTotal impacted: {len(impact.all_relevant)}")
+
+
+def _print_broken_files(idx, broken_patches):
+    """Shared helper: print patch text for any files that failed to parse."""
+    if not idx.broken_files:
+        return
+
+    print(f"\n⚠ {len(idx.broken_files)} file(s) failed to parse and could not be fully analyzed:")
+    for f in idx.broken_files:
+        print(f"\n--- {f} ---")
+        patch = broken_patches.get(f)
+        if patch:
+            print(patch.rstrip("\n"))
+        else:
+            print("  (no patch text available -- file may be new/untracked)")
+
+
+def _cmd_diff(args):
+    """Find changed symbols from git diff."""
+    idx = index_repository(args.repo)
+
+    against = "HEAD" if args.committed_only else None
+    broken_patches = {}
+    changed = find_changed_symbols(
+        args.repo, idx.symbols, ref=args.ref, against=against,
+        broken_files=idx.broken_files,
+        broken_file_patches=broken_patches,
+        known_broken_files=idx.broken_files,
+    )
+
+    if not changed:
+        print("No changed symbols found.")
+        _print_broken_files(idx, broken_patches)
+        return
+
+    print(f"Changed symbols ({len(changed)}):")
+    for sym_id in changed:
+        print(f"  {sym_id}")
+
+    _print_broken_files(idx, broken_patches)
+
+
+def _cmd_compile(args):
+    """Build full context package."""
+    idx = index_repository(args.repo)
+
+    # Determine changed symbols
+    if args.changed:
+        changed = args.changed
+    elif args.ref:
+        changed = find_changed_symbols(
+            args.repo, idx.symbols, ref=args.ref,
+            broken_files=idx.broken_files,
+            known_broken_files=idx.broken_files,
+        )
+    else:
+        print("Error: provide --changed or --ref", file=sys.stderr)
+        sys.exit(1)
+
+    if not changed:
+        print("No changes detected.")
+        return
+
+    impact = analyze_impact(idx, changed, max_depth=args.depth)
+    max_tokens = args.max_tokens if args.max_tokens > 0 else None
+    ctx = compile(idx, impact, max_tokens=max_tokens, notes=args.notes)
+
+    if args.json:
+        result = {
+            "symbol_count": ctx.symbol_count,
+            "token_estimate": ctx.token_estimate,
+            "total_repo_tokens": ctx.total_repo_tokens,
+            "reduction_pct": round(ctx.reduction_pct, 2),
+            "context": ctx.text,
+        }
+        print(json.dumps(result, indent=2))
+    elif getattr(args, "sync", False):
+        import urllib.request
+        import urllib.error
+        url = os.environ.get("CTXSYNC_URL")
+        key = os.environ.get("CTXSYNC_KEY")
+        if not url or not key:
+            print("Error: CTXSYNC_URL and CTXSYNC_KEY environment variables must be set.", file=sys.stderr)
+            sys.exit(1)
+        
+        url_event = url.rstrip("/") + "/event"
+        url_switch = url.rstrip("/") + "/project/switch"
+        project_name = os.path.basename(os.path.abspath(args.repo))
+        
+        # Switch active project first
+        try:
+            req_switch = urllib.request.Request(url_switch, data=json.dumps({"name": project_name}).encode("utf-8"), headers={
+                "Authorization": f"Bearer {key}",
+                "Content-Type": "application/json",
+                "User-Agent": "CtxSync-DiffContext/1.0"
+            })
+            urllib.request.urlopen(req_switch)
+        except Exception:
+            pass
+
+        data = json.dumps({
+            "type": "diffcontext_update",
+            "text": ctx.text,
+            "project": project_name
+        }).encode("utf-8")
+        req = urllib.request.Request(url_event, data=data, headers={
+            "Authorization": f"Bearer {key}",
+            "Content-Type": "application/json",
+            "User-Agent": "CtxSync-DiffContext/1.0"
+        })
+        try:
+            with urllib.request.urlopen(req) as res:
+                response_body = res.read().decode("utf-8")
+                print(f"☁️ Automatically synced blast radius to CtxSync Cloud!\nResponse: {response_body}")
+        except urllib.error.URLError as e:
+            print(f"Error syncing to CtxSync: {e}", file=sys.stderr)
+            sys.exit(1)
+    else:
+        print(ctx.text)
+        print(f"\n--- Stats ---")
+        print(f"Symbols  : {ctx.symbol_count}")
+        print(f"Tokens   : {ctx.token_estimate:,} / {ctx.total_repo_tokens:,}")
+        print(f"Reduction: {ctx.reduction_pct:.1f}%")
+
+
+def _cmd_blast(args):
+    """Visual blast radius analysis."""
+    t0 = time.perf_counter()
+    idx = index_repository(args.repo)
+    index_ms = (time.perf_counter() - t0) * 1000
+
+    against = "HEAD" if getattr(args, "committed_only", False) else None
+    broken_patches = {}
+
+    # Determine changed symbols
+    if args.changed:
+        changed = args.changed
+    elif args.ref:
+        changed = find_changed_symbols(
+            args.repo, idx.symbols, ref=args.ref, against=against,
+            broken_files=idx.broken_files, broken_file_patches=broken_patches,
+            known_broken_files=idx.broken_files,
+        )
+    else:
+        # Default: compare against HEAD~1
+        changed = find_changed_symbols(
+            args.repo, idx.symbols, ref="HEAD~1", against=against,
+            broken_files=idx.broken_files, broken_file_patches=broken_patches,
+            known_broken_files=idx.broken_files,
+        )
+
+    if not changed:
+        print("No changed symbols detected.")
+        print("  Tip: make a Python change and commit it, or use --changed <symbol_id>")
+        print(f"  Available symbols: {len(idx.symbols)} (use 'diffcontext index' to see stats)")
+        _print_broken_files(idx, broken_patches)
+        return
+
+    # blast renders directly from idx.graph and never calls analyze_impact,
+    # so it needs its own unknown-symbol check (typo'd --changed, renamed/
+    # deleted symbol) -- otherwise a typo silently renders as "0 impact"
+    # indistinguishable from a real, genuinely-isolated symbol.
+    warn_unknown_symbols(idx, changed)
+
+    # Strip ANSI if --no-color
+    if args.no_color:
+        from ..impact import visualizer
+        visualizer._C.RED = ""
+        visualizer._C.YELLOW = ""
+        visualizer._C.GREEN = ""
+        visualizer._C.CYAN = ""
+        visualizer._C.MAGENTA = ""
+        visualizer._C.BLUE = ""
+        visualizer._C.DIM = ""
+        visualizer._C.BOLD = ""
+        visualizer._C.RESET = ""
+        visualizer._C.WHITE = ""
+
+    # Render visual blast radius
+    output = render_blast_radius(
+        idx.graph, changed, idx.symbols,
+        max_depth=args.depth,
+        show_proof=args.verify,
+        repo_path=os.path.abspath(args.repo),
+    )
+    print(output)
+
+    # If --verify, also show detailed proof chains
+    if args.verify:
+        verification = render_verification(
+            idx.graph, changed, idx.symbols,
+        )
+        print(verification)
+
+    _print_broken_files(idx, broken_patches)
+
+    # Timing footer
+    total_ms = (time.perf_counter() - t0) * 1000
+    print(f"  Indexed {len(idx.symbols)} symbols in {index_ms:.0f}ms")
+    print(f"  Total analysis time: {total_ms:.0f}ms")
+    print()
+
+
+def _cmd_sync(args):
+    """Compile blast radius and push to CtxSync cloud in one step."""
+    import urllib.request
+    import urllib.error
+
+    # --- Resolve credentials: CLI flags > env vars > ~/.ctxsync config ---
+    url = args.url or os.environ.get("CTXSYNC_URL")
+    key = args.key or os.environ.get("CTXSYNC_KEY")
+
+    if not url or not key:
+        config_path = os.path.expanduser("~/.ctxsync")
+        if os.path.exists(config_path):
+            with open(config_path) as f:
+                for line in f:
+                    line = line.strip()
+                    if line.startswith("#") or "=" not in line:
+                        continue
+                    k, v = line.split("=", 1)
+                    k, v = k.strip(), v.strip()
+                    if k == "CTXSYNC_URL" and not url:
+                        url = v
+                    elif k == "CTXSYNC_KEY" and not key:
+                        key = v
+
+    if not url or not key:
+        print("Error: CtxSync credentials not found.", file=sys.stderr)
+        print("", file=sys.stderr)
+        print("Set them via any of:", file=sys.stderr)
+        print("  1. CLI flags:    diffcontext sync --url <URL> --key <KEY>", file=sys.stderr)
+        print("  2. Env vars:     export CTXSYNC_URL=... CTXSYNC_KEY=...", file=sys.stderr)
+        print("  3. Config file:  ~/.ctxsync with CTXSYNC_URL=... and CTXSYNC_KEY=...", file=sys.stderr)
+        sys.exit(1)
+
+    # --- Compile blast radius ---
+    idx = index_repository(args.repo)
+    changed = find_changed_symbols(
+        args.repo, idx.symbols, ref=args.ref,
+        broken_files=idx.broken_files,
+        known_broken_files=idx.broken_files,
+    )
+
+    if not changed:
+        print("No changes detected — nothing to sync.")
+        return
+
+    impact = analyze_impact(idx, changed, max_depth=args.depth)
+    max_tokens = args.max_tokens if args.max_tokens > 0 else None
+    ctx = compile(idx, impact, max_tokens=max_tokens)
+
+    project_name = args.project or os.path.basename(os.path.abspath(args.repo))
+
+    # --- Push to CtxSync ---
+    url_base = url.rstrip("/")
+
+    # Switch active project
+    try:
+        req_switch = urllib.request.Request(
+            url_base + "/project/switch",
+            data=json.dumps({"name": project_name}).encode("utf-8"),
+            headers={
+                "Authorization": f"Bearer {key}",
+                "Content-Type": "application/json",
+                "User-Agent": "DiffContext-Sync/1.0",
+            },
+        )
+        urllib.request.urlopen(req_switch)
+    except Exception:
+        pass
+
+    # Push context
+    data = json.dumps({
+        "type": "diffcontext_update",
+        "text": ctx.text,
+        "project": project_name,
+    }).encode("utf-8")
+    req = urllib.request.Request(
+        url_base + "/event",
+        data=data,
+        headers={
+            "Authorization": f"Bearer {key}",
+            "Content-Type": "application/json",
+            "User-Agent": "DiffContext-Sync/1.0",
+        },
+    )
+
+    try:
+        with urllib.request.urlopen(req) as res:
+            body = json.loads(res.read().decode("utf-8"))
+            print(f"☁️  Synced to CtxSync!")
+            print(f"   Project : {project_name}")
+            print(f"   Symbols : {ctx.symbol_count} compiled ({ctx.reduction_pct:.1f}% reduction)")
+            print(f"   Tokens  : {ctx.token_estimate:,}")
+            print(f"   Nodes   : {body.get('nodes', '?')}")
+            print(f"   Errors  : {body.get('activeErrors', '?')}")
+    except urllib.error.URLError as e:
+        print(f"Error syncing to CtxSync: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()
+
+
+def cli_main():
+    """
+    Entry point for the `diffcontext` console script.
+
+    Wraps main() to handle BrokenPipeError gracefully -- this happens
+    whenever stdout is piped into something that closes early (a missing
+    command, `head`, a reader that exits before reading everything). Without
+    this, piping `diffcontext compile | some-missing-tool` prints a full
+    Python traceback even though nothing is actually wrong.
+    """
+    try:
+        sys.exit(main())
+    except BrokenPipeError:
+        # Redirect remaining stdout to devnull so the interpreter's own
+        # shutdown-time flush doesn't also raise BrokenPipeError.
+        devnull = os.open(os.devnull, os.O_WRONLY)
+        os.dup2(devnull, sys.stdout.fileno())
+        sys.exit(1)

diffcontext/context/__init__.py

@@ -0,0 +1 @@
+"""context subpackage — selection, expansion, compilation."""

diffcontext/context/compiler.py

@@ -0,0 +1,438 @@
+"""
+compiler.py — Compile selected symbols into an LLM-ready context package.
+
+Key additions over the naive "dump code blocks" approach:
+  - META header: LLM knows repo size, what was dropped, graph confidence,
+    broken files, and scoring basis BEFORE reading any code.
+  - Per-symbol relationship annotations: callers / callees, and explicit
+    "NOT IN CONTEXT" tags so the LLM doesn't hallucinate missing deps.
+  - Dropped-symbol manifest: explicit list of symbols cut by token budget.
+  - Graph confidence score: fraction of edges that resolved to known symbols.
+  - Auto-generated suggestions: rule-based hints derived from graph data.
+"""
+
+import ast
+import re
+from typing import Dict, List, Optional, Set, Tuple
+
+from ..models import Symbol, ContextPackage
+
+
+def _get_module_docstring(abs_file_path: str) -> str:
+    """
+    Read the first line of the module-level docstring from an ABSOLUTE path.
+    Returns "" if file is unreadable or has no docstring.
+    Must receive sym.file (absolute), NOT the relative path from sym_id.
+    """
+    try:
+        with open(abs_file_path, "r", encoding="utf-8") as f:
+            source = f.read()
+        tree = ast.parse(source)
+        doc = ast.get_docstring(tree)
+        if doc:
+            first_line = doc.strip().split("\n")[0]
+            first_line = re.sub(r'^[\w/\-\.]+\.py\s*[—\-]+\s*', '', first_line).strip()
+            if len(first_line) > 60:
+                return first_line[:57] + "..."
+            return first_line
+    except Exception:
+        pass
+    return ""
+
+
+# ---------------------------------------------------------------------------
+# Public entry point
+# ---------------------------------------------------------------------------
+
+def compile_context(
+    symbols: Dict[str, Symbol],
+    selected_ids: List[str],
+    changed_ids: List[str],
+    scores: Dict[str, float],
+    graph: Optional[Dict[str, List[str]]] = None,
+    dropped_ids: Optional[List[str]] = None,
+    skipped_files: Optional[List[str]] = None,
+    notes: Optional[str] = None,
+) -> ContextPackage:
+    """
+    Build the final context text from selected symbols.
+
+    Args:
+        symbols:       Full symbol table for the repo.
+        selected_ids:  Symbols chosen for this context (respects token budget).
+        changed_ids:   The symbols that actually changed (always selected).
+        scores:        Impact scores for all scored symbols.
+        graph:         Full call graph (id -> [dep ids]). Enables relationship
+                       annotations and confidence calculation.
+        dropped_ids:   Symbols that were scored but cut by token budget.
+        skipped_files: Files that raised SyntaxError (graph has holes here).
+        notes:         Optional user notes injected into meta header.
+    """
+    dropped_ids   = dropped_ids   or []
+    skipped_files = skipped_files or []
+
+    changed_set  = set(changed_ids)
+    selected_set = set(selected_ids)
+
+    # Build reverse graph for caller annotation
+    reverse: Dict[str, Set[str]] = {}
+    if graph:
+        for caller, callees in graph.items():
+            for callee in callees:
+                reverse.setdefault(callee, set()).add(caller)
+
+    # Graph confidence: fraction of edges that point to a known symbol
+    graph_confidence = _compute_confidence(graph, symbols)
+
+    # Token bookkeeping
+    total_repo_code   = "\n\n".join(s.code for s in symbols.values())
+    total_repo_tokens = max(1, len(total_repo_code) // 4)
+
+    # --- Bucket symbols into sections ---
+    sections: Dict[str, List[str]] = {"CHANGED": [], "IMPACTED": [], "DEPENDENCIES": []}
+
+    for sym_id in selected_ids:
+        if sym_id not in symbols:
+            continue
+
+        sym   = symbols[sym_id]
+        score = scores.get(sym_id, 0)
+        file_name, func_name = sym_id.split(":", 1)
+
+        # Relationship annotation block
+        rel_block = _build_relationship_block(
+            sym_id, graph, reverse, selected_set, symbols
+        )
+
+        entry = (
+            f"FILE: {file_name}\n"
+            f"FUNCTION: {func_name} (score: {score:.0f})\n"
+            + rel_block +
+            f"\n{sym.code}"
+        )
+
+        if sym_id in changed_set:
+            sections["CHANGED"].append(entry)
+        elif score >= 70:
+            sections["IMPACTED"].append(entry)
+        else:
+            sections["DEPENDENCIES"].append(entry)
+
+    # --- Assemble code sections ---
+    parts = []
+    for label, entries in sections.items():
+        if entries:
+            parts.append(f"=== {label} SYMBOLS ===\n")
+            parts.append("\n\n---\n\n".join(entries))
+
+    code_text = "\n\n".join(parts)
+    context_tokens = max(1, len(code_text) // 4)
+
+    # --- Build meta-header (prepended so LLM reads it first) ---
+    meta = _build_meta_header(
+        symbols        = symbols,
+        selected_ids   = selected_ids,
+        dropped_ids    = dropped_ids,
+        skipped_files  = skipped_files,
+        changed_ids    = changed_ids,
+        graph          = graph,
+        reverse        = reverse,
+        graph_confidence = graph_confidence,
+        token_budget   = total_repo_tokens,   # not the budget cap; just total repo
+        context_tokens = context_tokens,
+        scores         = scores,
+        notes          = notes,
+    )
+
+    # --- Build suggestions block (appended at bottom) ---
+    suggestions = _build_suggestions(
+        changed_ids      = changed_ids,
+        dropped_ids      = dropped_ids,
+        skipped_files    = skipped_files,
+        graph            = graph,
+        reverse          = reverse,
+        graph_confidence = graph_confidence,
+        scores           = scores,
+    )
+
+    full_text = meta + "\n\n" + code_text
+    if suggestions:
+        full_text += "\n\n" + suggestions
+
+    return ContextPackage(
+        text               = full_text,
+        symbol_count       = len(selected_ids),
+        token_estimate     = context_tokens,
+        total_repo_tokens  = total_repo_tokens,
+        dropped_symbols    = dropped_ids,
+        skipped_files      = skipped_files,
+        graph_confidence   = graph_confidence,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Meta-header
+# ---------------------------------------------------------------------------
+
+def _build_meta_header(
+    symbols: Dict[str, Symbol],
+    selected_ids: List[str],
+    dropped_ids: List[str],
+    skipped_files: List[str],
+    changed_ids: List[str],
+    graph: Optional[Dict[str, List[str]]],
+    reverse: Dict[str, Set[str]],
+    graph_confidence: float,
+    token_budget: int,
+    context_tokens: int,
+    scores: Dict[str, float],
+    notes: Optional[str] = None,
+) -> str:
+    total_syms    = len(symbols)
+    selected_cnt  = len(selected_ids)
+    dropped_cnt   = len(dropped_ids)
+    scored_cnt    = len(scores)
+    total_edges   = sum(len(v) for v in graph.values()) if graph else 0
+
+    direct_callers  = sum(
+        1 for s in changed_ids
+        for c in reverse.get(s, set())
+    )
+    direct_callees  = sum(
+        len(graph.get(s, []))
+        for s in changed_ids
+    ) if graph else 0
+
+    lines = [
+        "=== DIFFCONTEXT META ===",
+        f"Repo symbols total    : {total_syms}",
+        f"Symbols scored        : {scored_cnt}",
+        f"Symbols IN context    : {selected_cnt}",
+        f"Symbols DROPPED       : {dropped_cnt}  ← you cannot see these",
+        f"Graph edges total     : {total_edges}",
+        f"Graph confidence      : {graph_confidence * 100:.0f}%"
+          + ("  ✓" if graph_confidence >= 0.9 else "  ⚠ incomplete"),
+        f"Changed symbols       : {len(changed_ids)}",
+        f"Direct callers found  : {direct_callers}",
+        f"Direct callees found  : {direct_callees}",
+        f"Context tokens (est.) : {context_tokens:,}",
+        f"Scoring basis         : changed=100 | direct_callee=90 | direct_caller=80 "
+          f"| 2hop_callee=60 | 2hop_caller=50 | indegree*2+outdegree bonus",
+    ]
+
+    # --- Repository Architecture Snapshot ---
+    # Build rel_file -> absolute_path mapping from symbol table.
+    # sym_id gives us relative path; sym.file gives us the absolute path we
+    # need to actually open the file for its docstring.
+    rel_to_abs: Dict[str, str] = {}
+    for sym_id, sym in symbols.items():
+        rel_file = sym_id.split(":", 1)[0]
+        if rel_file not in rel_to_abs:
+            rel_to_abs[rel_file] = sym.file  # sym.file is always absolute
+
+    modules_total = {}
+    modules_selected = {}
+    for sym_id in symbols:
+        file_name = sym_id.split(":", 1)[0]
+        modules_total[file_name] = modules_total.get(file_name, 0) + 1
+        
+    for sym_id in selected_ids:
+        if sym_id in symbols:
+            file_name = sym_id.split(":", 1)[0]
+            modules_selected[file_name] = modules_selected.get(file_name, 0) + 1
+
+    lines.append("")
+    lines.append("=== REPOSITORY ARCHITECTURE SNAPSHOT ===")
+    
+    loaded_files = []
+    blind_files = []
+    
+    for file_name, total in sorted(modules_total.items()):
+        selected = modules_selected.get(file_name, 0)
+        
+        doc_snippet = ""
+        if file_name.endswith(".py"):
+            # FIX: use absolute path, not the relative file_name
+            abs_path = rel_to_abs.get(file_name, "")
+            doc_str = _get_module_docstring(abs_path) if abs_path else ""
+            if doc_str:
+                doc_snippet = f" — {doc_str}"
+                
+        if selected > 0:
+            loaded_files.append(f"  - {file_name} ({selected}/{total} symbols loaded){doc_snippet}")
+        else:
+            blind_files.append(f"  - {file_name} ({total} symbols){doc_snippet}")
+
+    lines.append("MODULES IN CONTEXT:")
+    if loaded_files:
+        lines.extend(loaded_files)
+    else:
+        lines.append("  (none)")
+        
+    lines.append("")
+    lines.append("KNOWN MODULES (NOT IN CONTEXT - BLIND SPOTS):")
+    if blind_files:
+        lines.extend(blind_files)
+    else:
+        lines.append("  (none)")
+
+    if skipped_files:
+        lines.append("")
+        lines.append(f"FILES WITH SYNTAXERROR ({len(skipped_files)}) — graph has holes here:")
+        for f in skipped_files:
+            lines.append(f"  ✗ {f}")
+
+    if dropped_cnt > 0:
+        lines.append("")
+        lines.append(f"DROPPED SYMBOLS ({dropped_cnt}) — scored but cut by token budget:")
+        for d in dropped_ids[:15]:
+            lines.append(f"  - {d}  (score: {scores.get(d, 0):.0f})")
+        if dropped_cnt > 15:
+            lines.append(f"  ... and {dropped_cnt - 15} more")
+        lines.append("  → If any of these are critical, re-run with a higher --max-tokens.")
+
+    warnings = []
+    if skipped_files:
+        warnings.append(
+            f"⚠ {len(skipped_files)} file(s) had SyntaxErrors. "
+            "Call graph may be incomplete for those files."
+        )
+    if dropped_cnt > 0:
+        warnings.append(
+            f"⚠ {dropped_cnt} symbol(s) were dropped. "
+            "References to them in the code below are NOT backed by visible implementations."
+        )
+    if graph_confidence < 0.8:
+        warnings.append(
+            f"⚠ Graph confidence is {graph_confidence * 100:.0f}%. "
+            "Many calls could not be resolved — likely external/stdlib deps or dynamic dispatch."
+        )
+
+    if warnings:
+        lines.append("")
+        for w in warnings:
+            lines.append(w)
+
+    if notes:
+        lines.append(f"\n=== DEVELOPER NOTES ===\n{notes}")
+
+    lines.append("=== END META ===")
+    return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# Per-symbol relationship block
+# ---------------------------------------------------------------------------
+
+def _build_relationship_block(
+    sym_id: str,
+    graph: Optional[Dict[str, List[str]]],
+    reverse: Dict[str, Set[str]],
+    selected_set: Set[str],
+    symbols: Dict[str, Symbol],
+) -> str:
+    if not graph:
+        return ""
+
+    lines = []
+
+    callers = sorted(reverse.get(sym_id, set()))
+    callees = graph.get(sym_id, [])
+
+    if callers:
+        caller_parts = []
+        for c in callers[:6]:
+            tag = "" if c in selected_set else " [NOT IN CONTEXT]"
+            caller_parts.append(c + tag)
+        if len(callers) > 6:
+            caller_parts.append(f"... +{len(callers) - 6} more")
+        lines.append(f"CALLERS: {', '.join(caller_parts)}")
+
+    if callees:
+        callee_parts = []
+        for c in callees[:6]:
+            tag = "" if c in selected_set else " [NOT IN CONTEXT]"
+            callee_parts.append(c + tag)
+        if len(callees) > 6:
+            callee_parts.append(f"... +{len(callees) - 6} more")
+        lines.append(f"CALLEES: {', '.join(callee_parts)}")
+
+    if not callers and not callees:
+        lines.append("CALLERS: (none found in repo)")
+        lines.append("CALLEES: (none found in repo)")
+
+    return "\n".join(lines) + "\n" if lines else ""
+
+
+# ---------------------------------------------------------------------------
+# Suggestions block
+# ---------------------------------------------------------------------------
+
+def _build_suggestions(
+    changed_ids, dropped_ids, skipped_files,
+    graph, reverse, graph_confidence, scores,
+) -> str:
+    tips = []
+
+    if skipped_files:
+        tips.append(
+            f"Fix SyntaxErrors in {len(skipped_files)} file(s) to improve graph accuracy."
+        )
+
+    if graph_confidence < 0.7:
+        tips.append(
+            f"Graph confidence is {graph_confidence * 100:.0f}%. "
+            "Consider running diffcontext on installed site-packages too, "
+            "or add the dependency source to your repo path."
+        )
+
+    for sym_id in changed_ids:
+        callers = list(reverse.get(sym_id, set()))
+        if len(callers) > 20:
+            tips.append(
+                f"'{sym_id.split(':')[-1]}' has {len(callers)} callers — "
+                "unusually high blast radius. Review changes carefully."
+            )
+
+    if dropped_ids:
+        tips.append(
+            f"{len(dropped_ids)} symbol(s) were dropped by token budget. "
+            "Run with --max-tokens=0 (unlimited) to see full context."
+        )
+
+    if not tips:
+        return ""
+
+    lines = ["=== DIFFCONTEXT SUGGESTIONS ==="]
+    for i, tip in enumerate(tips, 1):
+        lines.append(f"  {i}. {tip}")
+    lines.append("=== END SUGGESTIONS ===")
+    return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# Graph confidence
+# ---------------------------------------------------------------------------
+
+def _compute_confidence(
+    graph: Optional[Dict[str, List[str]]],
+    symbols: Dict[str, Symbol],
+) -> float:
+    """
+    Fraction of graph edges that resolve to a known symbol.
+    Edges to external/stdlib deps count as unresolved.
+    Returns 1.0 if graph is empty or None (no data = no known holes).
+    """
+    if not graph:
+        return 1.0
+
+    total    = 0
+    resolved = 0
+
+    for deps in graph.values():
+        for d in deps:
+            total += 1
+            if d in symbols:
+                resolved += 1
+
+    return resolved / total if total > 0 else 1.0

diffcontext/context/selector.py

@@ -0,0 +1,102 @@
+"""
+selector.py — Select which symbols to include in context, respecting token budget.
+
+Key fix over original:
+  - Changed symbols are the ONLY unconditional include.
+  - Score >= 80 threshold no longer bypasses the token budget.
+    That rule caused direct callees (score ~90 after structural bonus)
+    to consume the entire budget before any co-change sibling candidates
+    (score ~38-50) were even evaluated. Precision suffered badly.
+  - Instead: rank strictly by score, apply budget universally, with one
+    exception: changed symbols always fit (they're the reason we're here).
+  - Added a per-symbol token cap so one giant function can't crowd out
+    ten relevant small ones.
+
+Fix vs previous version:
+  The token cap logic was wrong: it counted a capped amount toward the
+  budget (250 tokens) but included the full symbol in the result, causing
+  silent overruns. The correct behavior is: if a symbol exceeds the cap,
+  SKIP IT ENTIRELY rather than including it at a lie. This means the
+  selector tries smaller candidates next instead of filling context with
+  one huge function and then claiming there's room for more.
+"""
+
+from typing import Dict, List, Optional, Tuple
+
+from ..models import Symbol
+
+
+# A single symbol can burn at most this fraction of the total budget.
+# Prevents one huge function from crowding out ten relevant small ones.
+MAX_SINGLE_SYMBOL_FRACTION = 0.25
+
+
+def select_context(
+    symbols: Dict[str, Symbol],
+    scores: Dict[str, float],
+    changed: List[str],
+    max_tokens: Optional[int] = None,
+) -> Tuple[List[str], List[str]]:
+    """
+    Select symbols for context based on scores and token budget.
+
+    Priority:
+      1. Changed symbols always included (no budget bypass for anything else)
+      2. All remaining symbols ranked by score, included until budget exhausted
+
+    Returns:
+        (selected_ids, dropped_ids)
+        dropped_ids: scored symbols that exist in `symbols` but were cut by
+        the token budget. The LLM is told about these explicitly.
+    """
+    if not scores:
+        return list(changed), []
+
+    per_sym_cap = int(max_tokens * MAX_SINGLE_SYMBOL_FRACTION) if max_tokens else None
+
+    changed_set = set(changed)
+    result: List[str] = []
+    dropped: List[str] = []
+    current_tokens = 0
+
+    # ── Pass 1: changed symbols always in, no budget check ───────────────
+    for sym_id in changed:
+        if sym_id in symbols:
+            result.append(sym_id)
+            current_tokens += _estimate_tokens(symbols[sym_id].code)
+
+    # ── Pass 2: everything else ranked by score, budget-gated ────────────
+    scored = sorted(
+        ((sid, sc) for sid, sc in scores.items() if sid not in changed_set),
+        key=lambda x: x[1],
+        reverse=True,
+    )
+
+    for sym_id, score in scored:
+        if sym_id not in symbols:
+            continue
+
+        sym_tokens = _estimate_tokens(symbols[sym_id].code)
+
+        # FIX: if the symbol exceeds the per-symbol cap, skip it entirely.
+        # Previous code counted the capped amount toward the budget but
+        # still included the full symbol, silently overrunning the budget
+        # and then continuing to include more symbols as if there were room.
+        # Skipping is correct: the budget should gate what's actually included.
+        if per_sym_cap is not None and sym_tokens > per_sym_cap:
+            dropped.append(sym_id)
+            continue
+
+        if max_tokens is not None and current_tokens + sym_tokens > max_tokens:
+            dropped.append(sym_id)
+            continue
+
+        result.append(sym_id)
+        current_tokens += sym_tokens
+
+    return result, dropped
+
+
+def _estimate_tokens(text: str) -> int:
+    """~4 chars per token (GPT approximation). Add 20% buffer for safety."""
+    return max(1, int(len(text) / 4 * 1.2))

diffcontext/diff/__init__.py

@@ -0,0 +1 @@
+"""diff subpackage — git diff + state-based change detection."""

diffcontext/diff/git_diff.py

@@ -0,0 +1,301 @@
+"""
+git_diff.py — Extract changed files/symbols from git diff output.
+"""
+
+import os
+import subprocess
+from typing import List, Optional, Set
+
+
+def get_changed_files(
+    repo_path: str,
+    ref: str = "HEAD~1",
+    against: "Optional[str]" = None,
+) -> List[str]:
+    """
+    Get list of Python files changed between `ref` and `against`.
+
+    against=None (default): compare against the WORKING TREE, i.e. include
+    uncommitted changes (staged or not). This is `git diff <ref>` with no
+    second ref -- the same thing `git status`-style tools show you before
+    you commit.
+    against="HEAD" (or any other ref): compare two committed snapshots only;
+    uncommitted edits are invisible to this mode.
+
+    Returns list of relative paths like ["./src/auth.py", "./api/login.py"]
+    """
+    repo_path = os.path.abspath(repo_path)
+    try:
+        cmd = ["git", "diff", "--name-only", "--diff-filter=ACMR", ref]
+        if against is not None:
+            cmd.append(against)
+
+        result = subprocess.run(
+            cmd,
+            cwd=repo_path,
+            capture_output=True,
+            text=True,
+            timeout=30,
+        )
+        if result.returncode != 0:
+            return []
+
+        files = []
+        for line in result.stdout.strip().split("\n"):
+            line = line.strip()
+            if line.endswith(".py"):
+                files.append("./" + line)
+        return files
+
+    except (subprocess.TimeoutExpired, FileNotFoundError):
+        return []
+
+
+def get_changed_lines(
+    repo_path: str,
+    filepath: str,
+    ref: str = "HEAD~1",
+    against: "Optional[str]" = None,
+) -> Set[int]:
+    """
+    Get set of changed line numbers for a specific file.
+
+    against=None (default): compare `ref` against the working tree,
+    including uncommitted edits. See get_changed_files for details.
+
+    Returns set of 1-indexed line numbers that were added or modified.
+    """
+    repo_path = os.path.abspath(repo_path)
+    try:
+        cmd = ["git", "diff", "-U0", ref]
+        if against is not None:
+            cmd.append(against)
+        cmd += ["--", filepath.lstrip("./")]
+
+        result = subprocess.run(
+            cmd,
+            cwd=repo_path,
+            capture_output=True,
+            text=True,
+            timeout=30,
+        )
+        if result.returncode != 0:
+            return set()
+
+        changed_lines: Set[int] = set()
+        for line in result.stdout.split("\n"):
+            if line.startswith("@@"):
+                # Parse @@ -old,count +new,count @@
+                parts = line.split()
+                for part in parts:
+                    if part.startswith("+") and "," in part:
+                        start_str, count_str = part[1:].split(",", 1)
+                        start = int(start_str)
+                        count = int(count_str)
+                        for i in range(start, start + max(count, 1)):
+                            changed_lines.add(i)
+                    elif part.startswith("+") and part[1:].isdigit():
+                        changed_lines.add(int(part[1:]))
+
+        return changed_lines
+
+    except (subprocess.TimeoutExpired, FileNotFoundError, ValueError):
+        return set()
+
+
+def get_patch_text(
+    repo_path: str,
+    filepath: str,
+    ref: str = "HEAD~1",
+    against: "Optional[str]" = None,
+    context_lines: int = 3,
+) -> str:
+    """
+    Return the raw unified-diff patch text for a single file between
+    `ref` and `against` (working tree if against=None).
+
+    Useful for files that no longer parse: you can't get a line-level
+    symbol diff out of AST comparison, but the raw patch still shows
+    exactly what text changed (e.g. a commented-out `class` line).
+
+    Returns "" if there's no diff, the file/ref doesn't exist, or git fails.
+    """
+    repo_path = os.path.abspath(repo_path)
+    try:
+        cmd = ["git", "diff", f"-U{context_lines}", ref]
+        if against is not None:
+            cmd.append(against)
+        cmd += ["--", filepath.lstrip("./")]
+
+        result = subprocess.run(
+            cmd,
+            cwd=repo_path,
+            capture_output=True,
+            text=True,
+            timeout=30,
+        )
+        if result.returncode != 0:
+            return ""
+        return result.stdout
+
+    except (subprocess.TimeoutExpired, FileNotFoundError):
+        return ""
+
+
+def find_changed_symbols(
+    repo_path: str,
+    symbols: dict,
+    ref: str = "HEAD~1",
+    against: "Optional[str]" = None,
+    broken_files: Optional[List[str]] = None,
+    broken_file_patches: Optional[dict] = None,
+    known_broken_files: Optional[List[str]] = None,
+) -> List[str]:
+    """
+    Find which symbol IDs are affected by a git diff.
+
+    against=None (default): compares `ref` against the WORKING TREE, so
+    uncommitted edits are picked up. Pass against="HEAD" explicitly if you
+    only want committed changes.
+
+    Cross-references changed lines with symbol line ranges to find
+    exactly which functions/methods were modified.
+
+    `symbols` is the CURRENT index (built from the working tree / `against`
+    ref). A changed file that contributes zero entries to `symbols` is
+    ambiguous on its own -- it might have failed to parse (SyntaxError), or
+    it might just be a file with no function/method definitions (setup.py,
+    a constants module, an __init__.py with only imports, etc). To tell
+    these apart correctly, pass `known_broken_files` -- the ground-truth
+    list from extract_all_symbols()/RepositoryIndex.broken_files, which
+    only contains files that actually raised SyntaxError. Only files in
+    that list get the broken-file fallback treatment below; any other
+    zero-symbol file is treated as a normal (legitimately function-less)
+    file and simply contributes no changed symbols.
+
+    For files confirmed broken via `known_broken_files`:
+      - the file's relative path is appended to `broken_files` (if provided)
+      - we fall back to the symbol IDs that existed in the file at `ref`
+        (the prior, presumably-working revision) via `git show`, so the
+        change is still reported instead of silently disappearing.
+      - if `broken_file_patches` (a dict) is provided, it's populated with
+        {relative_file: raw_patch_text} -- the actual unified diff, since a
+        broken file can't be symbol-diffed and the patch is the only real
+        signal of what changed.
+    """
+    known_broken = set(known_broken_files or ())
+    changed_files = get_changed_files(repo_path, ref, against)
+    if not changed_files:
+        return []
+
+    # Which changed files actually have symbols in the current index?
+    files_with_current_symbols = {
+        "./" + os.path.relpath(sym.file, os.path.abspath(repo_path))
+        for sym in symbols.values()
+    }
+
+    changed_symbols = []
+
+    for sym_id, sym in symbols.items():
+        sym_file = "./" + os.path.relpath(sym.file, os.path.abspath(repo_path))
+        if sym_file not in changed_files:
+            continue
+
+        changed_lines = get_changed_lines(repo_path, sym_file, ref, against)
+        if not changed_lines:
+            continue
+
+        code_lines = sym.code.count("\n") + 1
+        sym_lines = set(range(sym.lineno, sym.lineno + code_lines))
+
+        if sym_lines & changed_lines:
+            changed_symbols.append(sym_id)
+
+    # Check for deleted symbols or broken files
+    for changed_file in changed_files:
+        # Handle broken files (SyntaxError)
+        if changed_file in known_broken:
+            if broken_files is not None and changed_file not in broken_files:
+                broken_files.append(changed_file)
+
+            if broken_file_patches is not None:
+                broken_file_patches[changed_file] = get_patch_text(
+                    repo_path, changed_file, ref, against
+                )
+
+            prior_ids = _symbol_ids_at_ref(repo_path, changed_file, ref)
+            for p_id in prior_ids:
+                if p_id not in changed_symbols:
+                    changed_symbols.append(p_id)
+            continue
+
+        # Handle valid files: find symbols that existed before but are gone now
+        prior_ids = _symbol_ids_at_ref(repo_path, changed_file, ref)
+        current_ids = {
+            sym_id for sym_id, sym in symbols.items()
+            if "./" + os.path.relpath(sym.file, os.path.abspath(repo_path)) == changed_file
+        }
+        
+        deleted_ids = set(prior_ids) - current_ids
+        for d_id in deleted_ids:
+            if d_id not in changed_symbols:
+                changed_symbols.append(d_id)
+
+    return changed_symbols
+
+
+def _symbol_ids_at_ref(repo_path: str, filepath: str, ref: str) -> List[str]:
+    """
+    Best-effort: list symbol IDs ("./file.py:Name") that existed in
+    `filepath` at git ref `ref`, by parsing the file's contents at that
+    revision. Returns [] if the file didn't exist, wasn't valid Python
+    at that ref either, or git/parse fails for any reason.
+    """
+    repo_path = os.path.abspath(repo_path)
+    try:
+        result = subprocess.run(
+            ["git", "show", f"{ref}:{filepath.lstrip('./')}"],
+            cwd=repo_path,
+            capture_output=True,
+            text=True,
+            timeout=30,
+        )
+        if result.returncode != 0:
+            return []
+
+        import ast as _ast
+        try:
+            tree = _ast.parse(result.stdout)
+        except SyntaxError:
+            return []
+
+        class _FuncVisitor(_ast.NodeVisitor):
+            def __init__(self):
+                self.class_stack = []
+                self.names = []
+
+            def visit_ClassDef(self, node):
+                self.class_stack.append(node.name)
+                self.generic_visit(node)
+                self.class_stack.pop()
+
+            def visit_FunctionDef(self, node):
+                self._add(node)
+                self.generic_visit(node)
+
+            def visit_AsyncFunctionDef(self, node):
+                self._add(node)
+                self.generic_visit(node)
+
+            def _add(self, node):
+                if self.class_stack:
+                    self.names.append(f"{self.class_stack[-1]}.{node.name}")
+                else:
+                    self.names.append(node.name)
+
+        visitor = _FuncVisitor()
+        visitor.visit(tree)
+        return [f"{filepath}:{name}" for name in visitor.names]
+
+    except (subprocess.TimeoutExpired, FileNotFoundError):
+        return []

diffcontext/diff/state_manager.py

@@ -0,0 +1,75 @@
+"""
+state_manager.py — Snapshot-based change detection (no git required).
+"""
+
+import json
+import os
+from typing import Dict, Iterable, List, Optional
+
+from ..models import DiffResult
+
+
+def _symbol_file(fn_id: str) -> str:
+    """Extract the file portion of a 'file.py:Class.method' symbol id."""
+    return fn_id.split(":", 1)[0] if ":" in fn_id else fn_id
+
+
+def compare_states(
+    previous: Dict[str, dict],
+    current: Dict[str, dict],
+    broken_files: Optional[Iterable[str]] = None,
+) -> DiffResult:
+    """
+    Compare two snapshots of repository functions.
+
+    Each snapshot is: {function_id: {"code": "..."}}
+
+    broken_files: relative paths (e.g. "./objects.py") of files that failed
+    to parse (SyntaxError) when building `current`. Symbols that previously
+    existed in one of these files are reported as `modified` rather than
+    `deleted` -- the function wasn't removed, the file just can't be parsed
+    right now. The file itself is also recorded in `broken_files` so callers
+    can flag it distinctly from a normal diff.
+    """
+    broken_files = set(broken_files or ())
+
+    modified = []
+    added = []
+    deleted = []
+
+    for fn_id in previous:
+        if fn_id not in current:
+            if _symbol_file(fn_id) in broken_files:
+                # File failed to parse this run -- treat every symbol that
+                # used to live there as modified (not deleted), since the
+                # change (the syntax break) is exactly what needs review.
+                modified.append(fn_id)
+            else:
+                deleted.append(fn_id)
+        elif previous[fn_id] != current[fn_id]:
+            modified.append(fn_id)
+
+    for fn_id in current:
+        if fn_id not in previous:
+            added.append(fn_id)
+
+    return DiffResult(
+        modified=modified,
+        added=added,
+        deleted=deleted,
+        broken_files=sorted(broken_files),
+    )
+
+
+def save_state(state: Dict, path: str = "diffcontext_state.json"):
+    """Save function snapshot to disk."""
+    with open(path, "w") as f:
+        json.dump(state, f, indent=2)
+
+
+def load_state(path: str = "diffcontext_state.json") -> Dict:
+    """Load previous function snapshot from disk."""
+    if not os.path.exists(path):
+        return {}
+    with open(path, "r") as f:
+        return json.load(f)

diffcontext/graph_builder.py

@@ -0,0 +1,737 @@
+"""
+graph_builder.py — Build the full dependency graph for a Python repository.
+
+Edge types (v2):
+  1. Direct call edges           — f() calls g()  →  f→g
+  2. Inheritance override edges  — Child.method → Parent.method (child only)
+  3. Shared-import consumer edges— files co-importing same module (capped ≤10)
+  4. Decorator edges             — @decorator applied to a function  →  fn→decorator
+  5. Annotated return-type edges — def f() -> MyClass: ...  →  f→MyClass.__init__
+  6. Same-directory sibling edges— one representative per file, light connectivity
+
+Performance:
+  - Import maps built ONCE in pre-pass.
+  - _resolve_owner_type results memoized (manual dict cache).
+"""
+
+import ast
+import logging
+import os
+from typing import Dict, List, Optional, Set, Tuple
+
+from .scanner import find_python_files
+from .parser import extract_all_symbols
+from .resolver import build_import_map
+from .symbols import (
+    extract_attribute_ownerships,
+    extract_local_var_types,
+    extract_param_types,
+    _iter_statements,
+)
+from ._warn_once import warn_syntax_error_once, check_and_warn_encoding
+
+logger = logging.getLogger(__name__)
+
+# Fan-out caps — keep shared-import and sibling edges from becoming mega-hubs
+_SHARED_IMPORT_MAX_CONSUMERS = 10   # skip if >10 files share the same import
+_SAME_DIR_MAX_FILES = 20            # skip same-dir bonus if directory is huge
+_DECORATOR_EDGE_MAX = 6             # max decorator edges per function (guards chains)
+
+
+def build_repository_graph(repo_path: str) -> Dict[str, List[str]]:
+    """
+    Build the complete call graph for a repository.
+
+    Returns:
+        dict mapping function_id -> [list of called function_ids]
+    """
+    repo_path = os.path.abspath(repo_path)
+
+    functions = extract_all_symbols(repo_path)
+    function_ids = set(functions)
+
+    # ── pre-pass: per-file ASTs, import maps, class registry ─────────────
+    file_trees:      Dict[str, ast.Module]          = {}
+    import_maps:     Dict[str, Dict[str, str]]      = {}
+    class_registry:  Dict[str, List[str]]           = {}   # class_name -> [rel_file, ...]
+    classes_by_file: Dict[str, List[str]]           = {}   # rel_file -> [class_name, ...]
+    inheritance:     Dict[str, List[Tuple]]         = {}   # "rel_file:ClassName" -> bases
+    factory_returns: Dict[str, Tuple]               = {}   # "rel_file:func" -> (q, type)
+    # Module-level var types: rel_file -> {var_name: (qualifier, bare_name)}
+    # e.g. `app = Flask(__name__)` at module scope -> {"app": (None, "Flask")}
+    module_var_types: Dict[str, Dict[str, Tuple]]   = {}
+
+    for filename in find_python_files(repo_path):
+        with open(filename, "rb") as f:
+            raw = f.read()
+        check_and_warn_encoding(logger, filename, raw)
+        source = raw.decode("utf-8", errors="ignore")
+
+        try:
+            tree = ast.parse(source)
+        except SyntaxError as e:
+            warn_syntax_error_once(logger, filename, e)
+            continue
+
+        relative_file = "./" + os.path.relpath(filename, repo_path)
+        file_trees[relative_file]  = tree
+        import_maps[relative_file] = build_import_map(filename, repo_path)
+
+        mvt: Dict[str, Tuple] = {}
+        for node in tree.body:
+            if isinstance(node, ast.ClassDef):
+                class_registry.setdefault(node.name, []).append(relative_file)
+                classes_by_file.setdefault(relative_file, []).append(node.name)
+
+                bases = []
+                for b in node.bases:
+                    if isinstance(b, ast.Name):
+                        bases.append((None, b.id))
+                    elif isinstance(b, ast.Attribute) and isinstance(b.value, ast.Name):
+                        bases.append((b.value.id, b.attr))
+                    elif isinstance(b, ast.Attribute):
+                        bases.append((None, b.attr))
+                inheritance[f"{relative_file}:{node.name}"] = bases
+
+            elif isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                ref = _find_return_type(node)
+                if ref:
+                    factory_returns[f"{relative_file}:{node.name}"] = ref
+                ann_ref = _find_annotated_return(node)
+                if ann_ref and not ref:
+                    factory_returns[f"{relative_file}:{node.name}"] = ann_ref
+
+            elif isinstance(node, ast.Assign):
+                # Track module-level: `app = Flask(__name__)`
+                if isinstance(node.value, ast.Call):
+                    func = node.value.func
+                    if isinstance(func, ast.Name):
+                        type_ref = (None, func.id)
+                    elif isinstance(func, ast.Attribute) and isinstance(func.value, ast.Name):
+                        type_ref = (func.value.id, func.attr)
+                    else:
+                        type_ref = None
+                    if type_ref:
+                        for tgt in node.targets:
+                            if isinstance(tgt, ast.Name):
+                                mvt[tgt.id] = type_ref
+
+            elif isinstance(node, ast.AnnAssign):
+                # Track: `db: SQLAlchemy = SQLAlchemy(app)`
+                if node.value and isinstance(node.value, ast.Call):
+                    func = node.value.func
+                    if isinstance(func, ast.Name):
+                        type_ref = (None, func.id)
+                    elif isinstance(func, ast.Attribute) and isinstance(func.value, ast.Name):
+                        type_ref = (func.value.id, func.attr)
+                    else:
+                        type_ref = None
+                    if type_ref and isinstance(node.target, ast.Name):
+                        mvt[node.target.id] = type_ref
+
+        if mvt:
+            module_var_types[relative_file] = mvt
+
+    # ── Resolution cache ──────────────────────────────────────────────────
+    # _resolve_owner_type is called O(symbols * calls_per_function) times.
+    # The same (qualifier, bare_name, rel_file) triple recurs constantly on
+    # large repos. Cache the result to avoid redundant work.
+    _resolve_cache: Dict[Tuple, Optional[str]] = {}
+
+    def _cached_resolve_owner_type(qualifier, bare_name, relative_file, import_map, _seen=None):
+        key = (qualifier, bare_name, relative_file)
+        if key in _resolve_cache:
+            return _resolve_cache[key]
+        result = _resolve_owner_type(
+            qualifier, bare_name, relative_file, import_map,
+            class_registry, factory_returns, import_maps, repo_path,
+            _seen=_seen,
+            classes_by_file=classes_by_file,
+        )
+        _resolve_cache[key] = result
+        return result
+
+    # ── Attribute owners ──────────────────────────────────────────────────
+    attribute_owners: Dict[str, str] = {}
+
+    # Also register module-level vars as attribute owners so that
+    # `app.run()` in a function body resolves to Flask.run.
+    for rel_file, mvt in module_var_types.items():
+        import_map = import_maps[rel_file]
+        for var_name, type_ref in mvt.items():
+            qualifier, bare_name = type_ref
+            resolved = _resolve_owner_type(
+                qualifier, bare_name, rel_file, import_map,
+                class_registry, factory_returns, import_maps, repo_path,
+                classes_by_file=classes_by_file,
+            )
+            if resolved:
+                # Key format matches attribute_owners: "ClassName.attr"
+                # but here var_name is the module-level variable.
+                attribute_owners[f"{rel_file}:{var_name}"] = resolved
+
+    for relative_file, tree in file_trees.items():
+        import_map = import_maps[relative_file]
+        raw_own = extract_attribute_ownerships(tree)
+
+        for key, type_ref in raw_own.items():
+            if type_ref is None:
+                continue
+            qualifier, bare_name = type_ref
+            resolved = _cached_resolve_owner_type(qualifier, bare_name, relative_file, import_map)
+            if resolved:
+                attribute_owners[f"{relative_file}:{key}"] = resolved
+
+    # ── Build the call graph ──────────────────────────────────────────────
+    graph: Dict[str, List[str]] = {}
+
+    for relative_file, tree in file_trees.items():
+        import_map = import_maps[relative_file]
+
+        local_name_to_id = {
+            fid.split(":", 1)[1]: fid
+            for fid in functions
+            if fid.startswith(relative_file + ":")
+        }
+
+        function_nodes = _collect_function_nodes(tree)
+
+        for fn_node, is_method, class_name in function_nodes:
+            function_name = f"{class_name}.{fn_node.name}" if class_name else fn_node.name
+            function_id   = f"{relative_file}:{function_name}"
+
+            graph.setdefault(function_id, [])
+
+            param_types    = extract_param_types(fn_node)
+            local_var_types = {**param_types, **extract_local_var_types(fn_node, param_types)}
+
+            for child in ast.walk(fn_node):
+                if not isinstance(child, ast.Call):
+                    continue
+
+                dep = _resolve_call(
+                    child,
+                    is_method,
+                    class_name,
+                    relative_file,
+                    local_name_to_id,
+                    import_map,
+                    functions,
+                    function_ids,
+                    repo_path,
+                    attribute_owners,
+                    inheritance,
+                    class_registry,
+                    factory_returns,
+                    import_maps,
+                    local_var_types,
+                    classes_by_file,
+                    _cached_resolve_owner_type,
+                )
+
+                if dep and dep != function_id and dep not in graph[function_id]:
+                    graph[function_id].append(dep)
+
+    # ── Phase 1A: Inheritance override edges ─────────────────────────────
+    # When ChildClass overrides ParentClass.method, add child → parent edge.
+    # Only child → parent direction: "if I changed the child, show me the
+    # parent contract I might be violating." The reverse (parent → all 400
+    # children) would create mega-hubs that destroy ranking.
+    for child_key, bases in inheritance.items():
+        child_file, child_class = child_key.split(":", 1)
+        for qualifier, base_name in bases:
+            base_owner = _resolve_owner_type(
+                qualifier, base_name, child_file,
+                import_maps.get(child_file, {}),
+                class_registry, factory_returns, import_maps, repo_path,
+                classes_by_file=classes_by_file,
+            )
+            if not base_owner:
+                continue
+
+            # Find all methods in the child class and look for same-named parent methods
+            child_prefix = f"{child_key}."
+            for fid in function_ids:
+                if not fid.startswith(child_prefix):
+                    continue
+                method_name = fid[len(child_prefix):]
+                parent_method = f"{base_owner}.{method_name}"
+                if parent_method in function_ids and parent_method != fid:
+                    # Child → parent only (avoids mega-hub on parent side)
+                    if parent_method not in graph.get(fid, []):
+                        graph.setdefault(fid, []).append(parent_method)
+
+    # ── Phase 1B: Decorator edges ─────────────────────────────────────────
+    # A function decorated with @my_decorator has an implicit dependency on
+    # my_decorator. This is one of the strongest co-change signals:
+    # if the decorator changes, all its callsites likely change too.
+    for relative_file, tree in file_trees.items():
+        import_map = import_maps[relative_file]
+        for fn_node, _is_method, _class_name in _collect_function_nodes(tree):
+            added = 0
+            for deco in fn_node.decorator_list:
+                if added >= _DECORATOR_EDGE_MAX:
+                    break
+                # @plain_name  or  @module.name  or  @name(args)
+                deco_func = deco.func if isinstance(deco, ast.Call) else deco
+                dep = None
+                if isinstance(deco_func, ast.Name):
+                    dep = _lookup(
+                        deco_func.id,
+                        {fid.split(":", 1)[1]: fid
+                         for fid in functions
+                         if fid.startswith(relative_file + ":")},
+                        import_map, functions, repo_path,
+                    )
+                elif isinstance(deco_func, ast.Attribute) and isinstance(deco_func.value, ast.Name):
+                    if deco_func.value.id in import_map:
+                        src = import_map[deco_func.value.id]
+                        rel_src = "./" + os.path.relpath(src, repo_path)
+                        dep = f"{rel_src}:{deco_func.attr}"
+                        if dep not in function_ids:
+                            dep = None
+                if dep:
+                    fn_name_local = (
+                        f"{_class_name}.{fn_node.name}"
+                        if _class_name else fn_node.name
+                    )
+                    fid = f"{relative_file}:{fn_name_local}"
+                    if fid in function_ids and dep != fid and dep not in graph.get(fid, []):
+                        graph.setdefault(fid, []).append(dep)
+                        added += 1
+
+    # ── Build file_groups for use by shared-import edges ────────────────────
+    file_groups: Dict[str, List[str]] = {}
+    for fid in function_ids:
+        ffile = fid.split(":")[0]
+        file_groups.setdefault(ffile, []).append(fid)
+
+    # ── Phase 1C: Shared-import consumer edges ───────────────────────────
+    # If file_a and file_b both import from the same internal module,
+    # functions in file_a and file_b are likely to co-change when that
+    # module changes. Create edges between functions across those files.
+    import_consumers: Dict[str, List[str]] = {}
+    for rel_file, imap in import_maps.items():
+        for _local_name, abs_path in imap.items():
+            # Only track internal (in-repo) imports
+            rel_imported = "./" + os.path.relpath(abs_path, repo_path)
+            if not rel_imported.startswith("./"):
+                continue
+            import_consumers.setdefault(rel_imported, []).append(rel_file)
+
+    # Deduplicate consumer file lists, then connect representatives
+    for _imported_mod, consumer_files in import_consumers.items():
+        consumer_files = list(dict.fromkeys(consumer_files))  # deduplicate, preserve order
+        if len(consumer_files) < 2 or len(consumer_files) > _SHARED_IMPORT_MAX_CONSUMERS:
+            continue
+        # Pick a representative symbol from each consumer file
+        representatives = []
+        for cfile in consumer_files:
+            rep_syms = file_groups.get(cfile, [])
+            if rep_syms:
+                representatives.append(rep_syms[0])
+        # Connect representatives pairwise
+        for i, a in enumerate(representatives):
+            for b in representatives[i + 1:]:
+                if b not in graph.get(a, []):
+                    graph.setdefault(a, []).append(b)
+                if a not in graph.get(b, []):
+                    graph.setdefault(b, []).append(a)
+
+    # ── Phase 1D: Same-directory sibling edges ────────────────────────────
+    # Files in the same package directory tend to co-change (tests ↔ impl,
+    # models ↔ serializers, etc.).  Connect one representative per file to
+    # one representative from every other file in the same directory.
+    # Cap: skip directories with >_SAME_DIR_MAX_FILES Python files to avoid
+    # linking unrelated utility grab-bags.
+    dir_files: Dict[str, List[str]] = {}
+    for rel_file in file_groups:
+        dir_part = os.path.dirname(rel_file)
+        dir_files.setdefault(dir_part, []).append(rel_file)
+
+    for _dir, dir_file_list in dir_files.items():
+        if len(dir_file_list) < 2 or len(dir_file_list) > _SAME_DIR_MAX_FILES:
+            continue
+        reps = []
+        for df in dir_file_list:
+            syms = file_groups.get(df, [])
+            if syms:
+                reps.append(syms[0])   # one rep per file
+        for i, a in enumerate(reps):
+            for b in reps[i + 1:]:
+                if b not in graph.get(a, []):
+                    graph.setdefault(a, []).append(b)
+                if a not in graph.get(b, []):
+                    graph.setdefault(b, []).append(a)
+
+    # ── Phase 1E: Sliding-window within-file edges ────────────────────────
+    # Functions defined near each other in the same file are empirically the
+    # strongest co-change signal after direct calls.  A sliding window of
+    # WINDOW_SIZE links each function to its closest neighbours in definition
+    # order.  Cap: skip files with >FILE_WINDOW_MAX_SYMS symbols (e.g. a
+    # 600-function god-file would create O(n*w) noise edges).
+    WINDOW_SIZE = 3          # each function linked to ±3 neighbours
+    FILE_WINDOW_MAX_SYMS = 60  # skip window edges in very large files
+
+    for rel_file, syms_in_file in file_groups.items():
+        if len(syms_in_file) < 2 or len(syms_in_file) > FILE_WINDOW_MAX_SYMS:
+            continue
+        for i, a in enumerate(syms_in_file):
+            for j in range(i + 1, min(i + 1 + WINDOW_SIZE, len(syms_in_file))):
+                b = syms_in_file[j]
+                if b not in graph.get(a, []):
+                    graph.setdefault(a, []).append(b)
+                if a not in graph.get(b, []):
+                    graph.setdefault(b, []).append(a)
+
+    # ── Phase 1F: Light parent→child inheritance edges ────────────────────
+    # Child→parent already exists (Phase 1A).  For parents with FEW children
+    # (≤PARENT_CHILD_MAX_CHILDREN), also add parent→child so that a change
+    # to the parent method surfaces its direct overriders.  We skip parents
+    # with many children to avoid creating mega-hubs (e.g. BaseModel in
+    # pydantic has 400+ subclasses — those would destroy ranking).
+    PARENT_CHILD_MAX_CHILDREN = 8
+
+    # Build a map: parent_method_id -> [child_method_ids]
+    parent_to_children: Dict[str, List[str]] = {}
+    for child_key, bases in inheritance.items():
+        child_file, child_class = child_key.split(":", 1)
+        for qualifier, base_name in bases:
+            base_owner = _resolve_owner_type(
+                qualifier, base_name, child_file,
+                import_maps.get(child_file, {}),
+                class_registry, factory_returns, import_maps, repo_path,
+                classes_by_file=classes_by_file,
+            )
+            if not base_owner:
+                continue
+            child_prefix = f"{child_key}."
+            for fid in function_ids:
+                if not fid.startswith(child_prefix):
+                    continue
+                method_name = fid[len(child_prefix):]
+                parent_method = f"{base_owner}.{method_name}"
+                if parent_method in function_ids and parent_method != fid:
+                    parent_to_children.setdefault(parent_method, []).append(fid)
+
+    for parent_method, children in parent_to_children.items():
+        if len(children) > PARENT_CHILD_MAX_CHILDREN:
+            continue   # too many — would create a mega-hub
+        for child_fid in children:
+            if child_fid not in graph.get(parent_method, []):
+                graph.setdefault(parent_method, []).append(child_fid)
+
+    return graph
+
+
+# ── Internal helpers ──────────────────────────────────────────────────────
+
+def _collect_function_nodes(tree):
+    """
+    Return list of (function_node, is_method, class_name) for EVERY function
+    in the file, including nested functions and closures.
+
+    Mirrors what parser.py's _FunctionCollector does so that the graph covers
+    every symbol the parser emits (previously missed ~30-40% of nodes).
+    """
+    result = []
+    _collect_recursive(tree.body, class_stack=[], result=result)
+    return result
+
+
+def _collect_recursive(stmts, class_stack, result):
+    """Recursively collect function nodes from a list of statements."""
+    for node in stmts:
+        if isinstance(node, ast.ClassDef):
+            class_stack.append(node.name)
+            _collect_recursive(node.body, class_stack, result)
+            class_stack.pop()
+        elif isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            if class_stack:
+                class_name = ".".join(class_stack)
+                is_method = True
+            else:
+                class_name = None
+                is_method = False
+            result.append((node, is_method, class_name))
+            # Also recurse into the function body to catch closures/nested funcs
+            _collect_recursive(node.body, class_stack, result)
+
+
+def _find_return_type(node):
+    found = None
+    for stmt in _iter_statements(node.body):
+        if isinstance(stmt, ast.Return) and stmt.value is not None:
+            if not isinstance(stmt.value, ast.Call):
+                return None
+            func = stmt.value.func
+            if isinstance(func, ast.Name):
+                ref = (None, func.id)
+            elif isinstance(func, ast.Attribute) and isinstance(func.value, ast.Name):
+                ref = (func.value.id, func.attr)
+            elif isinstance(func, ast.Attribute):
+                ref = (None, func.attr)
+            else:
+                return None
+            if found is None:
+                found = ref
+            elif found != ref:
+                return None
+    return found
+
+
+def _find_annotated_return(node):
+    """
+    Extract (qualifier, bare_name) from a PEP-3107 return annotation.
+
+        def f() -> MyClass: ...         ->  (None, "MyClass")
+        def f() -> module.MyClass: ...  ->  ("module", "MyClass")
+
+    Skips primitive annotations (str, int, bool, None, etc.) and generics
+    like List[X] where the outer type is not a class we own.
+    """
+    PRIMITIVES = frozenset({
+        "str", "int", "float", "bool", "bytes", "None",
+        "list", "dict", "set", "tuple", "Any", "Optional",
+        "List", "Dict", "Set", "Tuple", "Iterator", "Generator",
+        "Iterable", "Sequence", "Mapping", "Type", "Union",
+    })
+    ann = node.returns
+    if ann is None:
+        return None
+    if isinstance(ann, ast.Constant):
+        return None
+    if isinstance(ann, ast.Name):
+        if ann.id in PRIMITIVES:
+            return None
+        return (None, ann.id)
+    if isinstance(ann, ast.Attribute) and isinstance(ann.value, ast.Name):
+        if ann.attr in PRIMITIVES:
+            return None
+        return (ann.value.id, ann.attr)
+    # Subscript like Optional[Router] — unwrap one level
+    if isinstance(ann, ast.Subscript):
+        return _find_annotated_return(
+            type("_Stub", (), {"returns": ann.slice})()  # type: ignore[arg-type]
+        )
+    return None
+
+
+def _resolve_owner_type(
+    qualifier, bare_name, relative_file, import_map,
+    class_registry, factory_returns, import_maps, repo_path, _seen=None,
+    classes_by_file=None,
+):
+    if _seen is None:
+        _seen = set()
+
+    cache_key = (qualifier, bare_name, relative_file)
+    if cache_key in _seen:
+        return None
+    _seen.add(cache_key)
+
+    if qualifier:
+        if qualifier not in import_map:
+            return None
+        target_file = "./" + os.path.relpath(import_map[qualifier], repo_path)
+
+        if bare_name in class_registry:
+            if target_file in class_registry[bare_name]:
+                return f"{target_file}:{bare_name}"
+            if target_file.endswith("__init__.py"):
+                target_dir = target_file[:-12]
+                for cand_file in class_registry[bare_name]:
+                    if cand_file.startswith(target_dir + "/"):
+                        return f"{cand_file}:{bare_name}"
+
+        factory_key = f"{target_file}:{bare_name}"
+        if factory_key in factory_returns:
+            return _resolve_owner_type(
+                *factory_returns[factory_key], target_file,
+                import_maps.get(target_file, {}), class_registry,
+                factory_returns, import_maps, repo_path, _seen,
+                classes_by_file,
+            )
+        return None
+
+    # bare name
+    if bare_name in class_registry and relative_file in class_registry[bare_name]:
+        return f"{relative_file}:{bare_name}"
+
+    if bare_name in import_map:
+        target_file = "./" + os.path.relpath(import_map[bare_name], repo_path)
+
+        if bare_name in class_registry:
+            if target_file in class_registry[bare_name]:
+                return f"{target_file}:{bare_name}"
+            if target_file.endswith("__init__.py"):
+                target_dir = target_file[:-12]
+                for cand_file in class_registry[bare_name]:
+                    if cand_file.startswith(target_dir + "/"):
+                        return f"{cand_file}:{bare_name}"
+        elif classes_by_file:
+            file_classes = classes_by_file.get(target_file, [])
+            if len(file_classes) == 1:
+                return f"{target_file}:{file_classes[0]}"
+
+        factory_key = f"{target_file}:{bare_name}"
+        if factory_key in factory_returns:
+            return _resolve_owner_type(
+                *factory_returns[factory_key], target_file,
+                import_maps.get(target_file, {}), class_registry,
+                factory_returns, import_maps, repo_path, _seen,
+                classes_by_file,
+            )
+        return None
+
+    factory_key = f"{relative_file}:{bare_name}"
+    if factory_key in factory_returns:
+        return _resolve_owner_type(
+            *factory_returns[factory_key], relative_file,
+            import_map, class_registry, factory_returns,
+            import_maps, repo_path, _seen,
+            classes_by_file=classes_by_file,
+        )
+    return None
+
+
+def _resolve_owner_of_expr(
+    node, class_name, relative_file, is_method, attribute_owners,
+    local_var_types=None, import_map=None, class_registry=None,
+    factory_returns=None, import_maps=None, repo_path=None,
+    classes_by_file=None, _cached_resolve=None,
+):
+    if isinstance(node, ast.Name) and node.id == "self" and is_method and class_name:
+        return f"{relative_file}:{class_name}"
+
+    if (
+        isinstance(node, ast.Name)
+        and local_var_types
+        and node.id in local_var_types
+        and import_map is not None
+    ):
+        qualifier, bare_name = local_var_types[node.id]
+        if _cached_resolve:
+            return _cached_resolve(qualifier, bare_name, relative_file, import_map)
+        return _resolve_owner_type(
+            qualifier, bare_name, relative_file, import_map,
+            class_registry or {}, factory_returns or {},
+            import_maps or {}, repo_path or "",
+            classes_by_file=classes_by_file,
+        )
+
+    # Module-level variable fallback: `app = Flask()` at module scope.
+    # attribute_owners stores these as "{rel_file}:{var_name}".
+    if isinstance(node, ast.Name) and attribute_owners:
+        module_key = f"{relative_file}:{node.id}"
+        if module_key in attribute_owners:
+            return attribute_owners[module_key]
+
+    if isinstance(node, ast.Attribute):
+        base_owner = _resolve_owner_of_expr(
+            node.value, class_name, relative_file, is_method, attribute_owners,
+            local_var_types, import_map, class_registry,
+            factory_returns, import_maps, repo_path,
+            classes_by_file, _cached_resolve,
+        )
+        if base_owner is None:
+            return None
+        return attribute_owners.get(f"{base_owner}.{node.attr}")
+
+    return None
+
+
+def _resolve_via_inheritance(
+    owner_type, method_name, inheritance, class_registry,
+    import_maps, function_ids, repo_path, _seen=None,
+    classes_by_file=None,
+):
+    if _seen is None:
+        _seen = set()
+    if owner_type in _seen:
+        return None
+    _seen.add(owner_type)
+
+    rel_file, class_name = owner_type.split(":", 1)
+    import_map = import_maps.get(rel_file, {})
+
+    for qualifier, base_name in inheritance.get(owner_type, []):
+        base_owner = _resolve_owner_type(
+            qualifier, base_name, rel_file, import_map,
+            class_registry, {}, import_maps, repo_path,
+            classes_by_file=classes_by_file,
+        )
+        if not base_owner:
+            continue
+
+        candidate = f"{base_owner}.{method_name}"
+        if candidate in function_ids:
+            return candidate
+
+        deeper = _resolve_via_inheritance(
+            base_owner, method_name, inheritance, class_registry,
+            import_maps, function_ids, repo_path, _seen,
+            classes_by_file,
+        )
+        if deeper:
+            return deeper
+
+    return None
+
+
+def _resolve_call(
+    call_node, is_method, class_name, relative_file,
+    local_name_to_id, import_map, all_functions, function_ids,
+    repo_path, attribute_owners, inheritance, class_registry,
+    factory_returns, import_maps, local_var_types=None,
+    classes_by_file=None, _cached_resolve=None,
+):
+    func = call_node.func
+
+    if isinstance(func, ast.Name):
+        return _lookup(func.id, local_name_to_id, import_map, all_functions, repo_path)
+
+    if isinstance(func, ast.Attribute):
+        method_name = func.attr
+
+        owner_type = _resolve_owner_of_expr(
+            func.value, class_name, relative_file, is_method, attribute_owners,
+            local_var_types, import_map, class_registry,
+            factory_returns, import_maps, repo_path,
+            classes_by_file, _cached_resolve,
+        )
+
+        if owner_type:
+            candidate = f"{owner_type}.{method_name}"
+            if candidate in function_ids:
+                return candidate
+
+            resolved = _resolve_via_inheritance(
+                owner_type, method_name, inheritance, class_registry,
+                import_maps, function_ids, repo_path,
+                classes_by_file=classes_by_file,
+            )
+            if resolved:
+                return resolved
+            return None
+
+        if isinstance(func.value, ast.Name) and func.value.id in import_map:
+            source_file = import_map[func.value.id]
+            relative_source = "./" + os.path.relpath(source_file, repo_path)
+            candidate = f"{relative_source}:{method_name}"
+            if candidate in all_functions:
+                return candidate
+
+    return None
+
+
+def _lookup(called_name, local_name_to_id, import_map, all_functions, repo_path):
+    if called_name in local_name_to_id:
+        return local_name_to_id[called_name]
+    if called_name in import_map:
+        source_file = import_map[called_name]
+        relative_source = "./" + os.path.relpath(source_file, repo_path)
+        candidate = f"{relative_source}:{called_name}"
+        if candidate in all_functions:
+            return candidate
+    return None

diffcontext/impact/__init__.py

@@ -0,0 +1 @@
+"""impact subpackage — blast radius, scoring, traversal."""

diffcontext/impact/blast_radius.py

@@ -0,0 +1,58 @@
+"""
+blast_radius.py — Find all symbols transitively affected by a change.
+
+Given a changed symbol, walks the REVERSE graph (callers) to find
+everything that depends on it.
+
+Performance fix: accept an optional pre-built reverse graph so the caller
+can build it once and reuse it across multiple symbols instead of
+rebuilding it O(N) times.
+"""
+
+from typing import Dict, List, Optional, Set
+
+
+def build_reverse_graph(graph: Dict[str, List[str]]) -> Dict[str, Set[str]]:
+    """Build the reverse (caller) graph once; reuse for many queries."""
+    reverse: Dict[str, Set[str]] = {}
+    for caller, callees in graph.items():
+        for callee in callees:
+            reverse.setdefault(callee, set()).add(caller)
+    return reverse
+
+
+def get_blast_radius(
+    graph: Dict[str, List[str]],
+    changed_symbol: str,
+    reverse: Optional[Dict[str, Set[str]]] = None,
+) -> List[str]:
+    """
+    All functions that (transitively) call changed_symbol.
+
+    Args:
+        graph:          Forward call graph (caller -> [callees]).
+        changed_symbol: The symbol whose blast radius we want.
+        reverse:        Pre-built reverse graph. If None it is built here
+                        (correct but wasteful when called in a loop).
+
+    Uses iterative DFS with cycle detection.
+    """
+    if reverse is None:
+        reverse = build_reverse_graph(graph)
+
+    affected: List[str] = []
+    visited: Set[str] = set()
+
+    # Iterative DFS on reverse graph
+    stack = [changed_symbol]
+    visited.add(changed_symbol)
+
+    while stack:
+        current = stack.pop()
+        for caller in reverse.get(current, ()):
+            if caller not in visited:
+                visited.add(caller)
+                affected.append(caller)
+                stack.append(caller)
+
+    return affected

diffcontext/impact/scoring.py

@@ -0,0 +1,160 @@
+"""
+scoring.py — Impact scoring for prioritizing symbols in context.
+
+Algorithm: Bidirectional decay propagation from changed symbols.
+
+Forward  (callees): score decays by CALLEE_DECAY per hop
+Backward (callers): score decays by CALLER_DECAY per hop
+
+Structural bonuses:
+  - Sibling bonus: shares a caller with a changed symbol (co-change signal),
+    weighted by 1/caller_outdegree so hub callers don’t flood the pool,
+    and log-scaled before capping to dampen compounding across many hubs.
+  - Structural bonus: log2(1 + indegree)*3 + log2(1 + outdegree),
+    hard-capped at STRUCT_MAX so mega-hub nodes (outdegree=400) don’t
+    accumulate +800 and crowd out genuinely co-changed code.
+
+Changes vs v1:
+  1. Structural bonus capped (STRUCT_MAX=15). Uncapped bonus turned hubs
+     into permanent top-scorers regardless of actual co-change signal.
+  2. BFS propagation cutoff raised 5.0 → 8.0. Large repos (transformers)
+     have long paths; 5.0 prematurely cut valid propagation chains.
+  3. Sibling bonus log-scaled before accumulation to dampen compounding.
+"""
+
+import math
+from collections import deque
+from typing import Dict, List, Optional, Set
+
+
+# Tunable constants
+CHANGED_SCORE   = 100.0
+CALLEE_DECAY    = 0.65   # lowered: callees are less likely to co-change
+CALLER_DECAY    = 0.85   # raised: callers co-change more than callees
+CALLEE_BASE     = 90.0   # direct callee of changed symbol
+CALLER_BASE     = 85.0   # direct caller
+SIBLING_BASE    = 60.0   # base for sibling contribution (divided by caller_outdegree)
+SIBLING_MAX     = 80.0   # cap: a symbol can’t accumulate more than this from siblings
+BLAST_BASE      = 30.0   # in blast_radii but not reached by BFS
+MAX_HOPS        = 8      # propagation depth limit
+BFS_CUTOFF      = 8.0    # stop propagating a path when score drops below this
+STRUCT_MAX      = 15.0   # hard cap on structural bonus (log-scaled)
+
+
+def compute_impact_scores(
+    graph: Dict[str, List[str]],
+    changed_symbols: List[str],
+    blast_radii: Dict[str, List[str]],
+    expanded_deps: List[str] = None,
+    reverse: Optional[Dict[str, Set[str]]] = None,
+) -> Dict[str, float]:
+    """
+    Score every symbol's relevance to understanding the change.
+
+    Args:
+        graph:           Forward call graph.
+        changed_symbols: Symbols that were modified.
+        blast_radii:     Pre-computed blast radii per changed symbol.
+        expanded_deps:   Symbols reachable by forward dependency expansion.
+        reverse:         Pre-built reverse graph (built internally if None).
+
+    Returns dict of symbol_id -> score (higher = more important).
+    """
+    # Build reverse graph once (or reuse caller's)
+    if reverse is None:
+        reverse = {}
+        for caller, callees in graph.items():
+            for callee in callees:
+                reverse.setdefault(callee, set()).add(caller)
+
+    changed_set = set(changed_symbols)
+    scores: Dict[str, float] = {}
+
+    # ── 1. Changed symbols = 100 ──────────────────────────────────────────
+    for sym in changed_symbols:
+        scores[sym] = CHANGED_SCORE
+
+    # ── 2. Forward BFS (callees) with decay ──────────────────────────────
+    queue: deque = deque()
+    for sym in changed_symbols:
+        for callee in graph.get(sym, []):
+            if callee not in changed_set:
+                queue.append((callee, CALLEE_BASE, 1))
+
+    visited_fwd: Set[str] = set(changed_symbols)
+    while queue:
+        node, score, hop = queue.popleft()
+        if node in visited_fwd or hop > MAX_HOPS:
+            continue
+        visited_fwd.add(node)
+        scores[node] = max(scores.get(node, 0.0), score)
+        next_score = score * CALLEE_DECAY
+        if next_score >= BFS_CUTOFF:
+            for callee in graph.get(node, []):
+                if callee not in visited_fwd:
+                    queue.append((callee, next_score, hop + 1))
+
+    # ── 3. Backward BFS (callers) with decay ─────────────────────────────
+    queue2: deque = deque()
+    for sym in changed_symbols:
+        for caller in reverse.get(sym, set()):
+            if caller not in changed_set:
+                queue2.append((caller, CALLER_BASE, 1))
+
+    visited_bwd: Set[str] = set(changed_symbols)
+    while queue2:
+        node, score, hop = queue2.popleft()
+        if node in visited_bwd or hop > MAX_HOPS:
+            continue
+        visited_bwd.add(node)
+        scores[node] = max(scores.get(node, 0.0), score)
+        next_score = score * CALLER_DECAY
+        if next_score >= BFS_CUTOFF:
+            for caller in reverse.get(node, set()):
+                if caller not in visited_bwd:
+                    queue2.append((caller, next_score, hop + 1))
+
+    # ── 4. Specificity-weighted sibling bonus ────────────────────────────
+    sibling_accumulator: Dict[str, float] = {}
+
+    for sym in changed_symbols:
+        for caller in reverse.get(sym, set()):
+            caller_callees = graph.get(caller, [])
+            caller_outdegree = len(caller_callees)
+            if caller_outdegree <= 1:
+                continue
+            raw_contribution = SIBLING_BASE / caller_outdegree
+            contribution = math.log2(1.0 + raw_contribution)
+            for sibling in caller_callees:
+                if sibling not in changed_set and sibling != sym:
+                    sibling_accumulator[sibling] = (
+                        sibling_accumulator.get(sibling, 0.0) + contribution
+                    )
+
+    for sibling, bonus in sibling_accumulator.items():
+        capped_bonus = min(bonus, SIBLING_MAX)
+        scores[sibling] = scores.get(sibling, 0.0) + capped_bonus
+
+    # ── 5. Expanded deps: give them a meaningful score ────────────────────
+    if expanded_deps:
+        for sym in expanded_deps:
+            if sym not in scores:
+                scores[sym] = BLAST_BASE
+
+    # ── 6. Remaining blast radius symbols not yet scored ─────────────────
+    for sym, radius in blast_radii.items():
+        for affected in radius:
+            if affected not in scores:
+                scores[affected] = BLAST_BASE
+
+    # ── 7. Structural bonus: log-scaled, hard-capped ──────────────────────────
+    # Previous formula (indegree*2 + outdegree) was unbounded: a hub with
+    # indegree=50 got +100 structural bonus, drowning all co-change signal.
+    # log2(1+degree) grows slowly and the STRUCT_MAX cap prevents run-away.
+    for sym in scores:
+        indegree  = len(reverse.get(sym, set()))
+        outdegree = len(graph.get(sym, []))
+        struct_bonus = math.log2(1 + indegree) * 3 + math.log2(1 + outdegree)
+        scores[sym] += min(struct_bonus, STRUCT_MAX)
+
+    return scores

diffcontext/impact/traversal.py

@@ -0,0 +1,58 @@
+"""
+traversal.py — Dependency expansion (forward graph walk).
+
+Given selected symbols, walk forward edges to include their callees.
+Supports both unbounded DFS and bounded BFS.
+"""
+
+from typing import Dict, List, Optional, Set
+
+
+def expand_dependencies(
+    graph: Dict[str, List[str]],
+    selected_symbols: List[str],
+    max_depth: Optional[int] = None,
+) -> List[str]:
+    """
+    Walk forward edges from selected_symbols.
+
+    max_depth=None  -> full transitive closure (iterative DFS)
+    max_depth=N     -> only nodes reachable within N hops (BFS)
+    """
+    visited: Set[str] = set()
+    result: List[str] = []
+
+    if max_depth is None:
+        # Iterative DFS — safe on large repos (no recursion limit)
+        stack = list(selected_symbols)
+        while stack:
+            func = stack.pop()
+            if func in visited:
+                continue
+            visited.add(func)
+            result.append(func)
+            for dep in reversed(graph.get(func, [])):
+                if dep not in visited:
+                    stack.append(dep)
+        return result
+
+    # Bounded BFS
+    frontier = list(selected_symbols)
+    for func in frontier:
+        if func not in visited:
+            visited.add(func)
+            result.append(func)
+
+    depth = 0
+    while frontier and depth < max_depth:
+        next_frontier = []
+        for func in frontier:
+            for dep in graph.get(func, []):
+                if dep not in visited:
+                    visited.add(dep)
+                    result.append(dep)
+                    next_frontier.append(dep)
+        frontier = next_frontier
+        depth += 1
+
+    return result

diffcontext/impact/visualizer.py

@@ -0,0 +1,341 @@
+"""
+visualizer.py — Visual blast radius renderer.
+
+Renders the blast radius as a colored, indented tree showing:
+  - The changed symbol at the root
+  - Direct callers (who calls this?)
+  - Direct callees (what does this call?)
+  - Transitive impact propagation
+  - Proof chains: the actual code line creating each edge
+
+Designed for terminal output with ANSI colors.
+"""
+
+import ast
+import os
+import re
+from typing import Dict, List, Optional, Set, Tuple
+
+
+# ANSI color codes
+class _C:
+    RED = "\033[91m"
+    YELLOW = "\033[93m"
+    GREEN = "\033[92m"
+    CYAN = "\033[96m"
+    MAGENTA = "\033[95m"
+    BLUE = "\033[94m"
+    DIM = "\033[2m"
+    BOLD = "\033[1m"
+    RESET = "\033[0m"
+    WHITE = "\033[97m"
+
+
+def render_blast_radius(
+    graph: Dict[str, List[str]],
+    changed_symbols: List[str],
+    symbols: dict,
+    max_depth: int = 3,
+    show_proof: bool = False,
+    repo_path: str = "",
+) -> str:
+    """
+    Render a visual tree of the blast radius for changed symbols.
+
+    Returns a formatted string ready for terminal output.
+    """
+    # Build reverse graph (callers)
+    reverse: Dict[str, Set[str]] = {}
+    for caller, callees in graph.items():
+        for callee in callees:
+            reverse.setdefault(callee, set()).add(caller)
+
+    lines: List[str] = []
+
+    lines.append("")
+    lines.append(f"{_C.BOLD}{_C.WHITE}{'═' * 70}{_C.RESET}")
+    lines.append(f"{_C.BOLD}{_C.WHITE}  BLAST RADIUS ANALYSIS{_C.RESET}")
+    lines.append(f"{_C.BOLD}{_C.WHITE}{'═' * 70}{_C.RESET}")
+
+    for sym_id in changed_symbols:
+        lines.append("")
+        lines.append(f"  {_C.BOLD}{_C.RED}⚡ CHANGED:{_C.RESET} {_C.BOLD}{sym_id}{_C.RESET}")
+
+        # Show symbol location info
+        if sym_id in symbols:
+            sym = symbols[sym_id]
+            lines.append(f"  {_C.DIM}   File: {sym.file}{_C.RESET}")
+            lines.append(f"  {_C.DIM}   Line: {sym.lineno}{_C.RESET}")
+
+        lines.append("")
+
+        # ---- CALLERS (who is affected by this change?) ----
+        direct_callers = sorted(reverse.get(sym_id, set()))
+        lines.append(f"  {_C.BOLD}{_C.YELLOW}▲ WHO CALLS THIS? (directly affected){_C.RESET}")
+
+        if not direct_callers:
+            lines.append(f"  {_C.DIM}  (no direct callers found){_C.RESET}")
+        else:
+            for i, caller in enumerate(direct_callers):
+                is_last = i == len(direct_callers) - 1
+                prefix = "└──" if is_last else "├──"
+                lines.append(f"  {_C.YELLOW}  {prefix} {caller}{_C.RESET}")
+
+                if show_proof:
+                    proof = _find_proof(caller, sym_id, symbols, graph)
+                    if proof:
+                        pad = "    " if is_last else "│   "
+                        lines.append(f"  {_C.DIM}  {pad} proof: {proof}{_C.RESET}")
+
+                # 2nd-level callers (transitive)
+                if max_depth >= 2:
+                    indirect_callers = sorted(reverse.get(caller, set()))
+                    for j, caller2 in enumerate(indirect_callers[:5]):
+                        is_last2 = j == len(indirect_callers[:5]) - 1
+                        indent = "    " if is_last else "│   "
+                        prefix2 = "└──" if is_last2 else "├──"
+                        lines.append(
+                            f"  {_C.DIM}  {indent}{prefix2} {caller2}{_C.RESET}"
+                        )
+                    if len(indirect_callers) > 5:
+                        indent = "    " if is_last else "│   "
+                        lines.append(
+                            f"  {_C.DIM}  {indent}... +{len(indirect_callers) - 5} more{_C.RESET}"
+                        )
+
+        lines.append("")
+
+        # ---- CALLEES (what does this function depend on?) ----
+        direct_callees = sorted(graph.get(sym_id, []))
+        lines.append(f"  {_C.BOLD}{_C.GREEN}▼ WHAT DOES THIS CALL? (dependencies){_C.RESET}")
+
+        if not direct_callees:
+            lines.append(f"  {_C.DIM}  (no outgoing calls resolved){_C.RESET}")
+        else:
+            for i, callee in enumerate(direct_callees):
+                is_last = i == len(direct_callees) - 1
+                prefix = "└──" if is_last else "├──"
+                lines.append(f"  {_C.GREEN}  {prefix} {callee}{_C.RESET}")
+
+                if show_proof:
+                    proof = _find_proof(sym_id, callee, symbols, graph)
+                    if proof:
+                        pad = "    " if is_last else "│   "
+                        lines.append(f"  {_C.DIM}  {pad} proof: {proof}{_C.RESET}")
+
+                # 2nd-level callees
+                if max_depth >= 2:
+                    indirect_callees = sorted(graph.get(callee, []))
+                    for j, callee2 in enumerate(indirect_callees[:5]):
+                        is_last2 = j == len(indirect_callees[:5]) - 1
+                        indent = "    " if is_last else "│   "
+                        prefix2 = "└──" if is_last2 else "├──"
+                        lines.append(
+                            f"  {_C.DIM}  {indent}{prefix2} {callee2}{_C.RESET}"
+                        )
+                    if len(indirect_callees) > 5:
+                        indent = "    " if is_last else "│   "
+                        lines.append(
+                            f"  {_C.DIM}  {indent}... +{len(indirect_callees) - 5} more{_C.RESET}"
+                        )
+
+        lines.append("")
+
+        # ---- FULL TRANSITIVE BLAST RADIUS ----
+        all_affected = _get_transitive_callers(reverse, sym_id, max_depth)
+        lines.append(f"  {_C.BOLD}{_C.CYAN}◉ FULL BLAST RADIUS{_C.RESET}")
+        lines.append(
+            f"  {_C.CYAN}  {len(all_affected)} symbols transitively affected{_C.RESET}"
+        )
+
+        # Group by file
+        by_file: Dict[str, List[str]] = {}
+        for affected_sym in all_affected:
+            parts = affected_sym.split(":", 1)
+            filepath = parts[0] if len(parts) == 2 else "unknown"
+            by_file.setdefault(filepath, []).append(affected_sym)
+
+        for filepath, syms in sorted(by_file.items()):
+            lines.append(f"  {_C.BLUE}  📄 {filepath} ({len(syms)} symbols){_C.RESET}")
+            for sym in sorted(syms)[:8]:
+                name = sym.split(":", 1)[1] if ":" in sym else sym
+                lines.append(f"  {_C.DIM}     · {name}{_C.RESET}")
+            if len(syms) > 8:
+                lines.append(f"  {_C.DIM}     ... +{len(syms) - 8} more{_C.RESET}")
+
+    # ---- SUMMARY ----
+    lines.append("")
+    lines.append(f"{_C.BOLD}{_C.WHITE}{'─' * 70}{_C.RESET}")
+
+    total_blast = set()
+    for sym_id in changed_symbols:
+        total_blast.update(_get_transitive_callers(reverse, sym_id, max_depth))
+
+    total_deps = set()
+    for sym_id in changed_symbols:
+        total_deps.update(_get_transitive_callees(graph, sym_id, max_depth))
+
+    blast_files = set()
+    for sym in total_blast:
+        parts = sym.split(":", 1)
+        if len(parts) == 2:
+            blast_files.add(parts[0])
+
+    lines.append(f"  {_C.BOLD}Summary:{_C.RESET}")
+    lines.append(f"    Changed symbols    : {_C.RED}{len(changed_symbols)}{_C.RESET}")
+    lines.append(f"    Direct callers     : {_C.YELLOW}{sum(len(reverse.get(s, set())) for s in changed_symbols)}{_C.RESET}")
+    lines.append(f"    Direct dependencies: {_C.GREEN}{sum(len(graph.get(s, [])) for s in changed_symbols)}{_C.RESET}")
+    lines.append(f"    Total blast radius : {_C.CYAN}{len(total_blast)} symbols across {len(blast_files)} files{_C.RESET}")
+    lines.append(f"    Total dependencies : {_C.GREEN}{len(total_deps)} symbols{_C.RESET}")
+    lines.append(f"{_C.BOLD}{_C.WHITE}{'═' * 70}{_C.RESET}")
+    lines.append("")
+
+    return "\n".join(lines)
+
+
+def render_verification(
+    graph: Dict[str, List[str]],
+    changed_symbols: List[str],
+    symbols: dict,
+) -> str:
+    """
+    Render verification proof: for each edge in the blast radius,
+    show the actual code line that creates the dependency.
+    """
+    reverse: Dict[str, Set[str]] = {}
+    for caller, callees in graph.items():
+        for callee in callees:
+            reverse.setdefault(callee, set()).add(caller)
+
+    lines: List[str] = []
+    lines.append("")
+    lines.append(f"{_C.BOLD}{_C.WHITE}{'═' * 70}{_C.RESET}")
+    lines.append(f"{_C.BOLD}{_C.WHITE}  VERIFICATION: Proof of each connection{_C.RESET}")
+    lines.append(f"{_C.BOLD}{_C.WHITE}{'═' * 70}{_C.RESET}")
+
+    for sym_id in changed_symbols:
+        lines.append("")
+        lines.append(f"  {_C.BOLD}{_C.RED}⚡ {sym_id}{_C.RESET}")
+        lines.append("")
+
+        # Verify each caller
+        callers = sorted(reverse.get(sym_id, set()))
+        if callers:
+            lines.append(f"  {_C.BOLD}{_C.YELLOW}  Callers (these functions call the changed code):{_C.RESET}")
+            for caller in callers:
+                lines.append(f"  {_C.YELLOW}    → {caller}{_C.RESET}")
+                proof = _find_proof(caller, sym_id, symbols, graph)
+                if proof:
+                    lines.append(f"  {_C.DIM}      evidence: {proof}{_C.RESET}")
+                else:
+                    lines.append(f"  {_C.DIM}      evidence: (edge exists in call graph){_C.RESET}")
+            lines.append("")
+
+        # Verify each callee
+        callees = sorted(graph.get(sym_id, []))
+        if callees:
+            lines.append(f"  {_C.BOLD}{_C.GREEN}  Callees (the changed code calls these):{_C.RESET}")
+            for callee in callees:
+                lines.append(f"  {_C.GREEN}    → {callee}{_C.RESET}")
+                proof = _find_proof(sym_id, callee, symbols, graph)
+                if proof:
+                    lines.append(f"  {_C.DIM}      evidence: {proof}{_C.RESET}")
+                else:
+                    lines.append(f"  {_C.DIM}      evidence: (edge exists in call graph){_C.RESET}")
+
+    lines.append("")
+    lines.append(f"{_C.BOLD}{_C.WHITE}{'═' * 70}{_C.RESET}")
+    lines.append("")
+    return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _get_transitive_callers(
+    reverse: Dict[str, Set[str]],
+    start: str,
+    max_depth: int,
+) -> List[str]:
+    """BFS up the reverse graph to find all transitively affected symbols."""
+    visited: Set[str] = {start}
+    result: List[str] = []
+    frontier = [start]
+    depth = 0
+
+    while frontier and depth < max_depth:
+        next_frontier = []
+        for node in frontier:
+            for caller in reverse.get(node, set()):
+                if caller not in visited:
+                    visited.add(caller)
+                    result.append(caller)
+                    next_frontier.append(caller)
+        frontier = next_frontier
+        depth += 1
+
+    return result
+
+
+def _get_transitive_callees(
+    graph: Dict[str, List[str]],
+    start: str,
+    max_depth: int,
+) -> List[str]:
+    """BFS down the forward graph to find all dependencies."""
+    visited: Set[str] = {start}
+    result: List[str] = []
+    frontier = [start]
+    depth = 0
+
+    while frontier and depth < max_depth:
+        next_frontier = []
+        for node in frontier:
+            for callee in graph.get(node, []):
+                if callee not in visited:
+                    visited.add(callee)
+                    result.append(callee)
+                    next_frontier.append(callee)
+        frontier = next_frontier
+        depth += 1
+
+    return result
+
+
+def _find_proof(
+    caller_id: str,
+    callee_id: str,
+    symbols: dict,
+    graph: Dict[str, List[str]],
+) -> Optional[str]:
+    """
+    Find the actual code line in `caller` that references `callee`.
+
+    This is the "proof" that the edge is real — a grep through the caller's
+    source code for the callee's function name.
+    """
+    if caller_id not in symbols:
+        return None
+
+    caller_sym = symbols[caller_id]
+    callee_name = callee_id.split(":")[-1] if ":" in callee_id else callee_id
+
+    # Strip class prefix for method calls: "ClassName.method" -> "method"
+    if "." in callee_name:
+        bare_name = callee_name.split(".")[-1]
+    else:
+        bare_name = callee_name
+
+    # Search caller's code for the call
+    for i, line in enumerate(caller_sym.code.splitlines(), start=1):
+        stripped = line.strip()
+        # Look for function/method call pattern
+        if bare_name + "(" in stripped or f".{bare_name}(" in stripped:
+            # Truncate long lines
+            if len(stripped) > 80:
+                stripped = stripped[:77] + "..."
+            return f"line {caller_sym.lineno + i - 1}: {stripped}"
+
+    return None

diffcontext/mcp_server.py

@@ -0,0 +1,401 @@
+"""
+DiffContext MCP Server
+Lets Claude Desktop / Cursor call DiffContext natively — no copy-paste needed.
+
+How to use:
+  1. pip install mcp
+  2. Run: python -m diffcontext.mcp_server
+"""
+
+import ast
+import json
+import os
+import sys
+import tempfile
+import shutil
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+# ── Try to import MCP; give a clear error if not installed ──────────────────
+try:
+    from mcp.server import Server
+    from mcp.server.stdio import stdio_server
+    from mcp.types import Tool, TextContent
+    HAS_MCP = True
+except ImportError:
+    HAS_MCP = False
+
+# ── Try to import DiffContext ────────────────────────────────────────────────
+try:
+    from .pipeline import index_repository, analyze_impact
+    from .pipeline import compile as dc_compile
+    HAS_DIFFCONTEXT = True
+except ImportError:
+    try:
+        from diffcontext.pipeline import index_repository, analyze_impact
+        from diffcontext.pipeline import compile as dc_compile
+        HAS_DIFFCONTEXT = True
+    except ImportError:
+        HAS_DIFFCONTEXT = False
+
+
+# ── Sessions helper for remote hosted servers ────────────────────────────────
+
+def _get_sessions() -> Dict[str, str]:
+    try:
+        import importlib
+        backend_main = importlib.import_module("diffcontext-service.backend.main")
+        return backend_main.SESSIONS
+    except Exception:
+        try:
+            import importlib
+            backend_main = importlib.import_module("backend.main")
+            return backend_main.SESSIONS
+        except Exception:
+            return {}
+
+
+# ── Shared analysis logic (same as web service) ──────────────────────────────
+
+def _list_symbols_in_dir(repo_path: str) -> List[str]:
+    symbols = []
+    for py_file in Path(repo_path).rglob("*.py"):
+        rel = "./" + str(py_file.relative_to(repo_path))
+        try:
+            source = py_file.read_text(errors="ignore")
+            tree = ast.parse(source)
+        except SyntaxError:
+            continue
+        for node in ast.walk(tree):
+            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                symbols.append(f"{rel}:{node.name}")
+    return sorted(symbols)
+
+
+def _blast_radius(repo_path: str, symbol: str) -> dict:
+    if HAS_DIFFCONTEXT:
+        idx = index_repository(repo_path)
+        if symbol not in idx.symbols and symbol not in idx.graph:
+            import difflib
+            suggestions = difflib.get_close_matches(symbol, list(idx.symbols.keys()), n=3, cutoff=0.4)
+            return {"error": f"'{symbol}' not found.", "suggestions": suggestions}
+
+        impact = analyze_impact(idx, [symbol])
+
+        reverse: Dict[str, List[str]] = {}
+        for caller, callees in idx.graph.items():
+            for callee in callees:
+                reverse.setdefault(callee, []).append(caller)
+
+        by_file: Dict[str, List[str]] = {}
+        for sym in impact.blast_radius:
+            fp = sym.split(":")[0]
+            by_file.setdefault(fp, []).append(sym.split(":")[-1])
+
+        return {
+            "symbol": symbol,
+            "direct_callers": reverse.get(symbol, []),
+            "direct_callees": idx.graph.get(symbol, []),
+            "blast_radius_count": len(impact.blast_radius),
+            "blast_radius_by_file": by_file,
+            "all_affected": impact.blast_radius[:50],
+        }
+
+    # AST fallback
+    all_functions: Dict[str, str] = {}
+    call_graph: Dict[str, List[str]] = {}
+
+    for py_file in Path(repo_path).rglob("*.py"):
+        rel = "./" + str(py_file.relative_to(repo_path))
+        try:
+            source = py_file.read_text(errors="ignore")
+            tree = ast.parse(source)
+        except SyntaxError:
+            continue
+        for node in ast.walk(tree):
+            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                fid = f"{rel}:{node.name}"
+                all_functions[fid] = ""
+                calls = []
+                for child in ast.walk(node):
+                    if isinstance(child, ast.Call):
+                        if isinstance(child.func, ast.Name):
+                            calls.append(child.func.id)
+                        elif isinstance(child.func, ast.Attribute):
+                            calls.append(child.func.attr)
+                call_graph[fid] = calls
+
+    name_to_ids: Dict[str, List[str]] = {}
+    for fid in all_functions:
+        name_to_ids.setdefault(fid.split(":")[-1], []).append(fid)
+
+    resolved_graph: Dict[str, List[str]] = {}
+    for fid, raw_calls in call_graph.items():
+        resolved = []
+        for call in raw_calls:
+            for candidate in name_to_ids.get(call, []):
+                if candidate != fid:
+                    resolved.append(candidate)
+        resolved_graph[fid] = resolved
+
+    reverse: Dict[str, List[str]] = {}
+    for caller, callees in resolved_graph.items():
+        for callee in callees:
+            reverse.setdefault(callee, []).append(caller)
+
+    if symbol not in all_functions:
+        import difflib
+        suggestions = difflib.get_close_matches(symbol, list(all_functions.keys()), n=3, cutoff=0.4)
+        return {"error": f"'{symbol}' not found.", "suggestions": suggestions}
+
+    visited = {symbol}
+    blast = []
+    frontier = [symbol]
+    while frontier:
+        next_f = []
+        for node in frontier:
+            for caller in reverse.get(node, []):
+                if caller not in visited:
+                    visited.add(caller)
+                    blast.append(caller)
+                    next_f.append(caller)
+        frontier = next_f
+
+    by_file: Dict[str, List[str]] = {}
+    for sym in blast:
+        fp = sym.split(":")[0]
+        by_file.setdefault(fp, []).append(sym.split(":")[-1])
+
+    return {
+        "symbol": symbol,
+        "direct_callers": reverse.get(symbol, []),
+        "direct_callees": resolved_graph.get(symbol, []),
+        "blast_radius_count": len(blast),
+        "blast_radius_by_file": by_file,
+        "all_affected": blast[:50],
+    }
+
+
+# ── MCP Tool definitions ──────────────────────────────────────────────────────
+
+if HAS_MCP:
+    TOOLS = [
+        Tool(
+            name="list_symbols",
+            description=(
+                "List all Python functions/methods in a repository. "
+                "Returns symbol IDs in the format './file.py:function_name'. "
+                "Provide either repo_path (local absolute path) or repo_id (from /upload on remote hosted servers)."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "repo_path": {
+                        "type": "string",
+                        "description": "Absolute path to the Python project directory on the local machine.",
+                    },
+                    "repo_id": {
+                        "type": "string",
+                        "description": "The session ID of an uploaded repository (for remote MCP servers).",
+                    }
+                },
+                "required": [],
+            },
+        ),
+        Tool(
+            name="blast_radius",
+            description=(
+                "Find the blast radius of a Python function — which other functions "
+                "will break if you change it. Returns direct callers, direct callees, "
+                "and the full transitive set of affected functions grouped by file."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "repo_path": {
+                        "type": "string",
+                        "description": "Absolute path to the Python project directory.",
+                    },
+                    "repo_id": {
+                        "type": "string",
+                        "description": "The session ID of an uploaded repository (for remote MCP servers).",
+                    },
+                    "symbol": {
+                        "type": "string",
+                        "description": "Symbol ID in format './relative/path.py:function_name' or './path.py:ClassName.method'",
+                    },
+                },
+                "required": ["symbol"],
+            },
+        ),
+        Tool(
+            name="compile_context",
+            description=(
+                "Compile a token-efficient LLM context package for a code change. "
+                "Returns the relevant functions and their relationships, trimmed to a token budget."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "repo_path": {
+                        "type": "string",
+                        "description": "Absolute path to the Python project directory.",
+                    },
+                    "repo_id": {
+                        "type": "string",
+                        "description": "The session ID of an uploaded repository (for remote MCP servers).",
+                    },
+                    "symbol": {
+                        "type": "string",
+                        "description": "Symbol ID to analyze, e.g. './src/auth.py:validate_jwt'",
+                    },
+                    "max_tokens": {
+                        "type": "integer",
+                        "description": "Token budget for context (default 8000). Lower = tighter selection.",
+                        "default": 8000,
+                    },
+                },
+                "required": ["symbol"],
+            },
+        ),
+        Tool(
+            name="analyze_inline",
+            description=(
+                "Analyze Python code you paste directly — no file upload or local repo needed. "
+                "Useful for quick analysis of code snippets. "
+                "Returns blast radius and caller/callee relationships."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "files": {
+                        "type": "object",
+                        "description": "Dict of filename -> Python source code. E.g. {'service.py': 'def foo(): ...'}",
+                    },
+                    "symbol": {
+                        "type": "string",
+                        "description": "Symbol to analyze, e.g. './service.py:foo'",
+                    },
+                },
+                "required": ["files", "symbol"],
+            },
+        ),
+    ]
+else:
+    TOOLS = []
+
+
+# ── MCP Server ────────────────────────────────────────────────────────────────
+
+if HAS_MCP:
+    server = Server("diffcontext")
+
+    @server.list_tools()
+    async def list_tools():
+        return TOOLS
+
+    @server.call_tool()
+    async def call_tool(name: str, arguments: Dict[str, Any]):
+        try:
+            repo_path = arguments.get("repo_path")
+            repo_id = arguments.get("repo_id")
+
+            if name != "analyze_inline" and not repo_path and not repo_id:
+                result = {"error": "Must provide either 'repo_path' or 'repo_id'."}
+            else:
+                if repo_id:
+                    sessions = _get_sessions()
+                    if repo_id not in sessions:
+                        result = {"error": f"repo_id '{repo_id}' not found. Please upload the repository zip first."}
+                        return [TextContent(type="text", text=json.dumps(result, indent=2))]
+                    repo_path = sessions[repo_id]
+
+                if name == "list_symbols":
+                    if not os.path.isdir(repo_path):
+                        result = {"error": f"Directory not found: {repo_path}"}
+                    else:
+                        symbols = _list_symbols_in_dir(repo_path)
+                        result = {"count": len(symbols), "symbols": symbols}
+
+                elif name == "blast_radius":
+                    symbol = arguments["symbol"]
+                    if not os.path.isdir(repo_path):
+                        result = {"error": f"Directory not found: {repo_path}"}
+                    else:
+                        result = _blast_radius(repo_path, symbol)
+
+                elif name == "compile_context":
+                    symbol = arguments["symbol"]
+                    max_tokens = arguments.get("max_tokens", 8000)
+
+                    if not os.path.isdir(repo_path):
+                        result = {"error": f"Directory not found: {repo_path}"}
+                    elif not HAS_DIFFCONTEXT:
+                        br = _blast_radius(repo_path, symbol)
+                        result = {
+                            "context": json.dumps(br, indent=2),
+                            "note": "Install DiffContext for full compiled context.",
+                        }
+                    else:
+                        idx = index_repository(repo_path)
+                        impact = analyze_impact(idx, [symbol])
+                        ctx = dc_compile(idx, impact, max_tokens=max_tokens)
+                        result = {
+                            "context": ctx.text,
+                            "symbol_count": ctx.symbol_count,
+                            "token_estimate": ctx.token_estimate,
+                            "reduction_pct": round(ctx.reduction_pct, 1),
+                        }
+
+                elif name == "analyze_inline":
+                    files = arguments["files"]
+                    symbol = arguments["symbol"]
+                    tmp_dir = tempfile.mkdtemp(prefix="diffctx_mcp_")
+                    try:
+                        for filename, code in files.items():
+                            safe_name = Path(filename).name
+                            with open(os.path.join(tmp_dir, safe_name), "w") as f:
+                                f.write(code)
+                        result = _blast_radius(tmp_dir, symbol)
+                    finally:
+                        shutil.rmtree(tmp_dir, ignore_errors=True)
+
+                else:
+                    result = {"error": f"Unknown tool: {name}"}
+
+        except Exception as e:
+            result = {"error": str(e)}
+
+        return [TextContent(type="text", text=json.dumps(result, indent=2))]
+else:
+    server = None
+
+
+async def run_mcp_server():
+    if not HAS_MCP:
+        print(
+            "ERROR: 'mcp' package not installed.\n"
+            "Fix: pip install mcp\n",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    async with stdio_server() as (read_stream, write_stream):
+        await server.run(read_stream, write_stream, server.create_initialization_options())
+
+
+def main():
+    import asyncio
+    print("Starting DiffContext MCP Server...", file=sys.stderr)
+    print(f"DiffContext installed: {HAS_DIFFCONTEXT}", file=sys.stderr)
+    print(f"MCP installed: {HAS_MCP}", file=sys.stderr)
+
+    if not HAS_MCP:
+        print("\nTo install: pip install mcp", file=sys.stderr)
+        sys.exit(1)
+
+    asyncio.run(run_mcp_server())
+
+
+if __name__ == "__main__":
+    main()

diffcontext/models.py

@@ -0,0 +1,122 @@
+"""
+models.py — Data classes used across the pipeline.
+"""
+
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional, Set, Tuple
+
+
+@dataclass
+class Symbol:
+    """A single extracted symbol (function/method)."""
+    id: str               # "./path.py:ClassName.method" or "./path.py:func"
+    file: str             # absolute path to source file
+    name: str             # bare name like "ClassName.method" or "func"
+    code: str             # source code text
+    lineno: int = 0       # start line number
+
+
+@dataclass
+class RepositoryIndex:
+    """Complete index of a repository."""
+    symbols: Dict[str, Symbol] = field(default_factory=dict)     # id -> Symbol
+    graph: Dict[str, List[str]] = field(default_factory=dict)    # id -> [dependency ids]
+    broken_files: List[str] = field(default_factory=list)
+
+    @property
+    def reverse_graph(self) -> Dict[str, Set[str]]:
+        """Build reverse graph (callers of each symbol)."""
+        rev: Dict[str, Set[str]] = {}
+        for caller, callees in self.graph.items():
+            for callee in callees:
+                rev.setdefault(callee, set()).add(caller)
+        return rev
+
+    @property
+    def total_edges(self) -> int:
+        return sum(len(deps) for deps in self.graph.values())
+
+
+@dataclass
+class DiffResult:
+    """Result of comparing two states."""
+    modified: List[str] = field(default_factory=list)
+    added: List[str] = field(default_factory=list)
+    deleted: List[str] = field(default_factory=list)
+    broken_files: List[str] = field(default_factory=list)
+
+    @property
+    def all_changed(self) -> List[str]:
+        return self.modified + self.added
+
+
+@dataclass
+class ImpactResult:
+    """Result of impact analysis."""
+    changed: List[str] = field(default_factory=list)
+    blast_radius: List[str] = field(default_factory=list)
+    dependencies: List[str] = field(default_factory=list)
+    scores: Dict[str, float] = field(default_factory=dict)
+
+    @property
+    def all_relevant(self) -> List[str]:
+        """All symbols that should be in context, deduplicated, ordered by score."""
+        seen = set()
+        result = []
+        # Score-ordered
+        scored = sorted(self.scores.items(), key=lambda x: x[1], reverse=True)
+        for sym_id, _ in scored:
+            if sym_id not in seen:
+                seen.add(sym_id)
+                result.append(sym_id)
+        # Any remaining that weren't scored
+        for sym_id in self.changed + self.blast_radius + self.dependencies:
+            if sym_id not in seen:
+                seen.add(sym_id)
+                result.append(sym_id)
+        return result
+
+
+@dataclass
+class ContextPackage:
+    """Final compiled context for an LLM."""
+    text: str
+    symbol_count: int
+    token_estimate: int
+    total_repo_tokens: int
+    # LLM self-awareness fields
+    dropped_symbols: List[str] = field(default_factory=list)   # scored but cut by budget
+    skipped_files: List[str] = field(default_factory=list)     # SyntaxError'd files
+    graph_confidence: float = 1.0                              # fraction of edges that resolved
+
+    @property
+    def reduction_pct(self) -> float:
+        if self.total_repo_tokens == 0:
+            return 0.0
+        return (1 - self.token_estimate / self.total_repo_tokens) * 100
+
+
+@dataclass
+class BenchmarkResult:
+    """Result of a single benchmark run."""
+    name: str
+    repo_path: str
+    changed_functions: List[str]
+    # Graph stats
+    total_symbols: int = 0
+    total_edges: int = 0
+    graph_build_ms: float = 0.0
+    # Retrieval stats
+    retrieved_count: int = 0
+    retrieved_ids: List[str] = field(default_factory=list)
+    # Token stats
+    total_tokens: int = 0
+    context_tokens: int = 0
+    token_reduction_pct: float = 0.0
+    function_reduction_pct: float = 0.0
+    # Precision/Recall (when ground truth available)
+    precision: Optional[float] = None
+    recall: Optional[float] = None
+    f1: Optional[float] = None
+    # Timing
+    pipeline_ms: float = 0.0

diffcontext/parser.py

@@ -0,0 +1,121 @@
+"""
+parser.py — AST-based symbol extraction from Python source files.
+
+Extracts functions, methods (including async), with class-aware naming.
+"""
+
+import ast
+import logging
+import os
+from typing import Dict, List, Optional
+
+from .models import Symbol
+from ._warn_once import warn_syntax_error_once, check_and_warn_encoding
+
+logger = logging.getLogger(__name__)
+
+
+class _FunctionCollector(ast.NodeVisitor):
+    """AST visitor that collects all function/method definitions."""
+
+    def __init__(self):
+        self.class_stack: list = []
+        self.collected: list = []
+
+    def visit_ClassDef(self, node):
+        self.class_stack.append(node.name)
+        for child in node.body:
+            self.visit(child)
+        self.class_stack.pop()
+
+    def visit_FunctionDef(self, node):
+        self._collect(node)
+        self.generic_visit(node)
+
+    def visit_AsyncFunctionDef(self, node):
+        self._collect(node)
+        self.generic_visit(node)
+
+    def _collect(self, node):
+        if self.class_stack:
+            name = ".".join(self.class_stack) + "." + node.name
+        else:
+            name = node.name
+        self.collected.append((name, node))
+
+
+def extract_symbols(
+    filename: str,
+    repo_path: str,
+    broken_files: "Optional[List[str]]" = None,
+) -> Dict[str, Symbol]:
+    """
+    Parse a single Python file, return dict of symbol_id -> Symbol.
+
+    Symbol IDs look like: "./relative/path.py:ClassName.method_name"
+
+    If parsing fails and `broken_files` is provided (a list), the file's
+    relative path is appended to it so callers can distinguish "file failed
+    to parse" from "file legitimately has no functions."
+    """
+    with open(filename, "rb") as f:
+        raw = f.read()
+    check_and_warn_encoding(logger, filename, raw)
+    source = raw.decode("utf-8", errors="ignore")
+
+    relative_file = "./" + os.path.relpath(filename, repo_path)
+
+    try:
+        tree = ast.parse(source)
+    except SyntaxError as e:
+        warn_syntax_error_once(logger, filename, e)
+        if broken_files is not None:
+            broken_files.append(relative_file)
+        return {}
+
+    collector = _FunctionCollector()
+    collector.visit(tree)
+
+    symbols = {}
+    for name, node in collector.collected:
+        symbol_id = f"{relative_file}:{name}"
+        code = ast.get_source_segment(source, node)
+        if code is None:
+            continue
+        symbols[symbol_id] = Symbol(
+            id=symbol_id,
+            file=filename,
+            name=name,
+            code=code,
+            lineno=node.lineno,
+        )
+
+    return symbols
+
+
+def extract_all_symbols(
+    repo_path: str,
+    broken_files: "Optional[List[str]]" = None,
+) -> Dict[str, Symbol]:
+    """
+    Extract symbols from all Python files in a repository.
+
+    If `broken_files` is provided (a list), relative paths of any files
+    that failed to parse (SyntaxError) are appended to it.
+    """
+    from .scanner import find_python_files
+    from .cache import SymbolCache
+
+    repo_path = os.path.abspath(repo_path)
+    all_symbols: Dict[str, Symbol] = {}
+    
+    db_path = os.path.join(repo_path, ".diffcontext_cache.db")
+
+    with SymbolCache(db_path) as cache:
+        for filepath in find_python_files(repo_path):
+            def _parse(path: str) -> Dict[str, Symbol]:
+                return extract_symbols(path, repo_path, broken_files=broken_files)
+            
+            all_symbols.update(cache.get_or_parse(filepath, _parse))
+
+    return all_symbols

diffcontext/pipeline.py

@@ -0,0 +1,168 @@
+"""
+pipeline.py — The main DiffContext pipeline.
+
+Connects all stages: parse -> graph -> diff -> blast radius -> score -> select -> compile
+
+Key fixes vs original:
+  - expanded_deps is now passed into compute_impact_scores so those symbols
+    are actually scored (previously they were collected but never used).
+  - Graph is built with a single pass and cached import maps (see graph_builder).
+  - warn_unknown_symbols is called before any scoring to surface typos early.
+"""
+
+import difflib
+import logging
+import os
+import time
+from typing import Dict, List, Optional
+
+from .models import (
+    RepositoryIndex, ImpactResult, ContextPackage, Symbol,
+)
+from .parser import extract_all_symbols
+from .graph_builder import build_repository_graph
+from .impact.blast_radius import get_blast_radius
+from .impact.scoring import compute_impact_scores
+from .impact.traversal import expand_dependencies
+from .context.selector import select_context
+from .context.compiler import compile_context
+
+logger = logging.getLogger(__name__)
+
+
+def _suggest_similar_symbol(unknown_id: str, known_ids) -> Optional[str]:
+    """Fuzzy-match an unknown symbol ID against known ones (typo correction)."""
+    matches = difflib.get_close_matches(unknown_id, known_ids, n=1, cutoff=0.6)
+    return matches[0] if matches else None
+
+
+def index_repository(repo_path: str) -> RepositoryIndex:
+    """
+    Phase 1: Parse repository and build dependency graph.
+
+    Returns a RepositoryIndex with all symbols, the call graph, and the
+    list of files (if any) that failed to parse due to a SyntaxError.
+    """
+    repo_path = os.path.abspath(repo_path)
+
+    broken_files: List[str] = []
+    symbols = extract_all_symbols(repo_path, broken_files=broken_files)
+    graph = build_repository_graph(repo_path)
+
+    return RepositoryIndex(symbols=symbols, graph=graph, broken_files=broken_files)
+
+
+def warn_unknown_symbols(index: RepositoryIndex, changed_symbols: List[str]) -> List[str]:
+    """
+    Check `changed_symbols` against the index and warn about any that don't
+    actually exist. Returns the list of unknown symbol IDs.
+    """
+    unknown = [s for s in changed_symbols if s not in index.graph and s not in index.symbols]
+    for sym_id in unknown:
+        suggestion = _suggest_similar_symbol(sym_id, index.symbols.keys())
+        if suggestion:
+            logger.warning(
+                "\033[93m'%s' was not found in the index -- did you mean '%s'? "
+                "Its blast radius will show as empty, which does NOT mean "
+                "the real symbol has no impact.\033[0m",
+                sym_id, suggestion,
+            )
+        else:
+            logger.warning(
+                "\033[93m'%s' was not found in the index (typo, renamed, or "
+                "deleted symbol?). Its blast radius will show as empty, "
+                "which does NOT mean the real symbol has no impact.\033[0m",
+                sym_id,
+            )
+    return unknown
+
+
+def analyze_impact(
+    index: RepositoryIndex,
+    changed_symbols: List[str],
+    max_depth: Optional[int] = 2,
+) -> ImpactResult:
+    """
+    Phase 2: Given changed symbols, compute blast radius and impact scores.
+
+    Fix: expanded_deps is now passed into compute_impact_scores so those
+    nodes are actually scored. Previously they were computed and discarded.
+    """
+    warn_unknown_symbols(index, changed_symbols)
+
+    # ── Blast radius (reverse graph / callers) ────────────────────────────
+    blast_radii: Dict[str, List[str]] = {}
+    all_blast: List[str] = []
+
+    for sym_id in changed_symbols:
+        if sym_id in index.graph:
+            radius = get_blast_radius(index.graph, sym_id)
+            blast_radii[sym_id] = radius
+            all_blast.extend(radius)
+
+    # ── Forward dependency expansion ──────────────────────────────────────
+    # Seed with changed + blast so we also pull in what callers depend on.
+    deps = expand_dependencies(
+        index.graph,
+        changed_symbols + all_blast,
+        max_depth=max_depth,
+    )
+
+    # ── Impact scoring ────────────────────────────────────────────────────
+    # FIX: pass expanded deps so they get scored (previously ignored).
+    scores = compute_impact_scores(
+        index.graph,
+        changed_symbols,
+        blast_radii,
+        expanded_deps=deps,
+    )
+
+    return ImpactResult(
+        changed=changed_symbols,
+        blast_radius=list(set(all_blast)),
+        dependencies=deps,
+        scores=scores,
+    )
+
+
+def compile(
+    index: RepositoryIndex,
+    impact: ImpactResult,
+    max_tokens: Optional[int] = 10000,
+    notes: Optional[str] = None,
+) -> ContextPackage:
+    """
+    Phase 3: Select symbols and compile into LLM context.
+    """
+    selected, dropped = select_context(
+        index.symbols,
+        impact.scores,
+        impact.changed,
+        max_tokens=max_tokens,
+    )
+
+    return compile_context(
+        index.symbols,
+        selected,
+        impact.changed,
+        impact.scores,
+        graph=index.graph,
+        dropped_ids=dropped,
+        skipped_files=index.broken_files,
+        notes=notes,
+    )
+
+
+def run_pipeline(
+    repo_path: str,
+    changed_symbols: List[str],
+    max_depth: Optional[int] = 2,
+    max_tokens: Optional[int] = 10000,
+) -> ContextPackage:
+    """
+    Full pipeline in one call:
+        repo_path + changed_symbols -> ContextPackage
+    """
+    index = index_repository(repo_path)
+    impact = analyze_impact(index, changed_symbols, max_depth=max_depth)
+    return compile(index, impact, max_tokens=max_tokens)

diffcontext/resolver.py

@@ -0,0 +1,157 @@
+"""
+resolver.py — Resolve Python import statements to filesystem paths.
+"""
+
+import ast
+import logging
+import os
+from typing import Dict, Optional
+
+from ._warn_once import warn_syntax_error_once, check_and_warn_encoding
+
+logger = logging.getLogger(__name__)
+
+
+def build_import_map(filename: str, repo_path: str) -> Dict[str, str]:
+    """
+    Parse imports in a file and resolve them to absolute paths.
+
+    Returns:
+        dict: local_name -> absolute_path_of_source_file
+        e.g. {"helper": "/repo/utils.py", "Session": "/repo/sessions.py"}
+
+    __init__.py transparency:
+        When an import resolves to a package __init__.py, we scan that
+        __init__.py for re-export statements (`from .sub import Name`) and
+        follow them to the actual definition file. This means:
+
+            from flask import Flask
+            # resolves to src/flask/__init__.py
+            # __init__.py has: from .app import Flask
+            # final result: src/flask/app.py   ← correct
+    """
+    with open(filename, "rb") as f:
+        raw = f.read()
+    check_and_warn_encoding(logger, filename, raw)
+    source = raw.decode("utf-8", errors="ignore")
+
+    try:
+        tree = ast.parse(source)
+    except SyntaxError as e:
+        warn_syntax_error_once(logger, filename, e)
+        return {}
+
+    imports: Dict[str, str] = {}
+    file_dir = os.path.dirname(os.path.abspath(filename))
+    repo_abs = os.path.abspath(repo_path)
+
+    for node in ast.walk(tree):
+
+        if isinstance(node, ast.ImportFrom):
+            module = node.module or ""
+            level = node.level
+
+            if level > 0:
+                # Relative import: from .utils import helper
+                base = file_dir
+                for _ in range(level - 1):
+                    base = os.path.dirname(base)
+                module_path = os.path.join(base, module.replace(".", os.sep))
+            else:
+                # Absolute import: from requests.utils import helper
+                module_path = os.path.join(repo_abs, module.replace(".", os.sep))
+
+            resolved = _resolve_module_path(module_path)
+
+            for alias in node.names:
+                local_name = alias.asname or alias.name
+
+                # Check if this is a submodule import (from package import module)
+                submodule_path = os.path.join(module_path, alias.name)
+                submodule_resolved = _resolve_module_path(submodule_path)
+
+                if submodule_resolved:
+                    imports[local_name] = submodule_resolved
+                elif resolved:
+                    # __init__.py transparency: follow re-exports one level
+                    if resolved.endswith("__init__.py"):
+                        real = _follow_init_reexport(resolved, alias.name, repo_abs)
+                        imports[local_name] = real if real else resolved
+                    else:
+                        imports[local_name] = resolved
+
+        elif isinstance(node, ast.Import):
+            for alias in node.names:
+                top_module = alias.name.split(".")[0]
+                local_name = alias.asname or top_module
+                module_path = os.path.join(repo_abs, alias.name.replace(".", os.sep))
+                resolved = _resolve_module_path(module_path)
+
+                if not resolved:
+                    # Bare `import x` — try the importing file's own directory
+                    sibling_path = os.path.join(file_dir, alias.name.replace(".", os.sep))
+                    resolved = _resolve_module_path(sibling_path)
+
+                if resolved:
+                    imports[local_name] = resolved
+
+    return imports
+
+
+def _follow_init_reexport(init_path: str, name: str, repo_abs: str) -> Optional[str]:
+    """
+    Given a package __init__.py and a name imported from it, check whether
+    __init__.py re-exports that name from a submodule.
+
+    Example:
+        __init__.py contains:  from .app import Flask
+        name = "Flask"
+        → returns /abs/path/to/app.py
+
+    Only follows one level (no recursive re-export chasing) to stay fast.
+    Returns None if the name is not re-exported or the submodule can't be found.
+    """
+    try:
+        with open(init_path, "rb") as f:
+            raw = f.read()
+        source = raw.decode("utf-8", errors="ignore")
+        tree = ast.parse(source)
+    except (OSError, SyntaxError):
+        return None
+
+    init_dir = os.path.dirname(init_path)
+
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.ImportFrom):
+            continue
+        if node.level == 0:
+            continue  # only relative re-exports (from .sub import X)
+        for alias in node.names:
+            exported_name = alias.asname or alias.name
+            if exported_name != name:
+                continue
+            # Found the re-export — resolve the submodule
+            module = node.module or ""
+            base = init_dir
+            for _ in range(node.level - 1):
+                base = os.path.dirname(base)
+            sub_path = os.path.join(base, module.replace(".", os.sep))
+            # Check if alias.name itself is a submodule
+            submodule_path = os.path.join(sub_path, alias.name)
+            resolved = _resolve_module_path(submodule_path) or _resolve_module_path(sub_path)
+            if resolved:
+                return resolved
+
+    return None
+
+
+def _resolve_module_path(module_path: str) -> Optional[str]:
+    """Try to find a .py file or package __init__.py for a given path."""
+    candidates = [
+        module_path + ".py",
+        os.path.join(module_path, "__init__.py"),
+    ]
+    for candidate in candidates:
+        if os.path.isfile(candidate):
+            return os.path.normpath(candidate)
+    return None

diffcontext/scanner.py

@@ -0,0 +1,46 @@
+"""
+scanner.py — Discover Python files in a repository.
+"""
+
+import os
+from typing import List, Set
+
+EXCLUDED_DIRS: Set[str] = {
+    "__pycache__",
+    ".git",
+    ".tox",
+    ".mypy_cache",
+    ".pytest_cache",
+    "venv",
+    ".venv",
+    "env",
+    "node_modules",
+    "experimental",
+    "examples",
+    "docs",
+    "tests",
+    "test",
+    "benchmarks",
+    "datasets",
+    "dist",
+    "build",
+    "egg-info",
+}
+
+
+def find_python_files(root_dir: str) -> List[str]:
+    """Walk repo tree, return list of .py file paths, skipping excluded dirs."""
+    python_files = []
+
+    for root, dirs, files in os.walk(root_dir):
+        dirs[:] = [
+            d for d in dirs
+            if d not in EXCLUDED_DIRS
+            and not d.endswith(".egg-info")
+        ]
+
+        for f in files:
+            if f.endswith(".py"):
+                python_files.append(os.path.join(root, f))
+
+    return python_files

diffcontext/symbols.py

@@ -0,0 +1,254 @@
+"""
+symbols.py — Attribute ownership extraction for resolving self.attr.method() chains.
+
+Given a class with `self.router = APIRouter()`, this module figures out that
+`self.router` has type `APIRouter`, enabling cross-file method resolution.
+"""
+
+import ast
+from typing import Dict, Optional, Tuple, List
+
+
+def _iter_statements(body):
+    """Yield statements in source order, recursing into if/for/while/with/try."""
+    for stmt in body:
+        yield stmt
+
+        if isinstance(stmt, (ast.If, ast.For, ast.AsyncFor, ast.While)):
+            yield from _iter_statements(stmt.body)
+            yield from _iter_statements(stmt.orelse)
+
+        elif isinstance(stmt, (ast.With, ast.AsyncWith)):
+            yield from _iter_statements(stmt.body)
+
+        elif isinstance(stmt, ast.Try):
+            yield from _iter_statements(stmt.body)
+            for handler in stmt.handlers:
+                yield from _iter_statements(handler.body)
+            yield from _iter_statements(stmt.orelse)
+            yield from _iter_statements(stmt.finalbody)
+
+
+def _extract_annotation_name(annotation) -> Optional[Tuple[Optional[str], str]]:
+    """
+    Returns (qualifier, bare_name) or None.
+
+    Router          ->  (None, "Router")
+    Optional[Router]->  (None, "Router")       <- unwrap subscript
+    routing.Router  ->  ("routing", "Router")
+    """
+    if isinstance(annotation, ast.Name):
+        return (None, annotation.id)
+
+    if isinstance(annotation, ast.Attribute) and isinstance(annotation.value, ast.Name):
+        return (annotation.value.id, annotation.attr)
+
+    # Optional[Router], List[Router], etc.  — unwrap one level
+    if isinstance(annotation, ast.Subscript):
+        return _extract_annotation_name(annotation.slice)
+
+    return None
+
+
+def _extract_call_owner(value) -> Optional[Tuple[Optional[str], str]]:
+    """
+    Returns (qualifier, bare_name) or None.
+
+    APIRouter()          ->  (None,      "APIRouter")
+    routing.APIRouter()  ->  ("routing", "APIRouter")
+    make_helper()        ->  (None,      "make_helper")
+    """
+    if not isinstance(value, ast.Call):
+        return None
+
+    func = value.func
+
+    if isinstance(func, ast.Name):
+        return (None, func.id)
+
+    if isinstance(func, ast.Attribute) and isinstance(func.value, ast.Name):
+        return (func.value.id, func.attr)
+
+    if isinstance(func, ast.Attribute):
+        return (None, func.attr)
+
+    return None
+
+
+def _extract_assign_owner(value, local_var_types=None, param_types=None):
+    """
+    Handles non-Call RHS cases that still indicate a type:
+      self.x = router or Router()   -> BoolOp -> try each operand
+      self.x = router               -> bare Name -> no type info (return None)
+    """
+    if local_var_types is None:
+        local_var_types = {}
+    if param_types is None:
+        param_types = {}
+
+    if isinstance(value, ast.Call):
+        return _extract_call_owner(value)
+
+    if isinstance(value, ast.Name):
+        if value.id in param_types:
+            return param_types[value.id]
+        if value.id in local_var_types:
+            return local_var_types[value.id]
+        return None
+
+    if isinstance(value, ast.BoolOp):
+        call_result = None
+        name_result = None
+        for operand in value.values:
+            ref = _extract_assign_owner(operand, local_var_types, param_types)
+            if ref is None:
+                continue
+            if isinstance(operand, ast.Call):
+                call_result = call_result or ref
+            else:
+                name_result = name_result or ref
+        return call_result or name_result
+
+    return None
+
+
+def extract_local_var_types(
+    fn_node,
+    param_types: Optional[Dict[str, Tuple[Optional[str], str]]] = None,
+) -> Dict[str, Tuple[Optional[str], str]]:
+    """
+    Track local variable -> type assignments within a SINGLE function body,
+    free function or method alike:
+
+        h = Helper()              -> {"h": (None, "Helper")}
+        r: routing.Router = ...   -> {"r": ("routing", "Router")}
+        x = make_helper()         -> chases factory functions the same way
+                                      attribute ownership tracking does
+                                      (resolution of the factory return type
+                                      itself happens later, in graph_builder)
+
+    This is the free-function counterpart to the self.attr tracking that
+    extract_attribute_ownerships does for class bodies. It exists because
+    a huge fraction of real code instantiates a class in a local variable
+    inside a plain function (not as a self.attr) and immediately calls a
+    method on it -- e.g.:
+
+        def run():
+            h = Handler()
+            return h.process()
+
+    Without this, `h.process()` can never resolve: there's nowhere that
+    records "h" has type "Handler". extract_attribute_ownerships alone
+    can't help, because it only ever looks inside ast.ClassDef bodies.
+
+    Returns: {local_var_name: (qualifier, bare_type_name)}
+    """
+    if param_types is None:
+        param_types = {}
+
+    local_var_types: Dict[str, Tuple[Optional[str], str]] = {}
+
+    for stmt in _iter_statements(fn_node.body):
+
+        if isinstance(stmt, ast.AnnAssign):
+            target = stmt.target
+            if isinstance(target, ast.Name):
+                ref = _extract_annotation_name(stmt.annotation)
+                if ref:
+                    local_var_types[target.id] = ref
+            continue
+
+        if isinstance(stmt, ast.Assign):
+            for target in stmt.targets:
+                if isinstance(target, ast.Name):
+                    ref = _extract_assign_owner(
+                        stmt.value, local_var_types, param_types
+                    )
+                    if ref:
+                        local_var_types[target.id] = ref
+            continue
+
+    return local_var_types
+
+
+def extract_param_types(fn_node) -> Dict[str, Tuple[Optional[str], str]]:
+    """
+    Map annotated parameter names to their (qualifier, bare_name) type, e.g.
+
+        def f(router: routing.Router, name: str): ...
+
+    -> {"router": ("routing", "Router")}   (unannotated/non-type params skipped)
+    """
+    param_types: Dict[str, Tuple[Optional[str], str]] = {}
+    for arg in fn_node.args.args:
+        if arg.annotation is not None:
+            ref = _extract_annotation_name(arg.annotation)
+            if ref:
+                param_types[arg.arg] = ref
+    return param_types
+
+
+def extract_attribute_ownerships(tree) -> Dict[str, Tuple[Optional[str], str]]:
+    """
+    Extracts mappings like:
+        self.router: routing.Router = routing.Router()
+        self.router = Router()
+        self.router2 = router            # typed constructor param
+        h = Helper(); self.helper = h    # local var tracking
+        self.router3 = router or Router()
+        self.opt_router: Optional[Router] = None
+
+    Returns: {"FastAPI.router": (qualifier, type_name), ...}
+    """
+    ownerships: Dict[str, Tuple[Optional[str], str]] = {}
+
+    for node in tree.body:
+        if not isinstance(node, ast.ClassDef):
+            continue
+
+        class_name = node.name
+
+        for item in node.body:
+            if not isinstance(item, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                continue
+
+            param_types = extract_param_types(item)
+
+            local_var_types = {}
+
+            for stmt in _iter_statements(item.body):
+
+                if isinstance(stmt, ast.AnnAssign):
+                    target = stmt.target
+                    if (
+                        isinstance(target, ast.Attribute)
+                        and isinstance(target.value, ast.Name)
+                        and target.value.id == "self"
+                    ):
+                        ref = _extract_annotation_name(stmt.annotation)
+                        if ref:
+                            ownerships[f"{class_name}.{target.attr}"] = ref
+                    continue
+
+                if isinstance(stmt, ast.Assign):
+                    for target in stmt.targets:
+                        if (
+                            isinstance(target, ast.Attribute)
+                            and isinstance(target.value, ast.Name)
+                            and target.value.id == "self"
+                        ):
+                            ref = _extract_assign_owner(
+                                stmt.value, local_var_types, param_types
+                            )
+                            if ref:
+                                ownerships[f"{class_name}.{target.attr}"] = ref
+
+                        elif isinstance(target, ast.Name):
+                            ref = _extract_assign_owner(
+                                stmt.value, local_var_types, param_types
+                            )
+                            if ref:
+                                local_var_types[target.id] = ref
+                    continue
+
+    return ownerships

pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "diffcontext"
+version = "0.1.0"
+description = "Static-analysis-powered repository context compiler for LLMs"
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [
+    { name = "Your Name" },
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+]
+mcp = [
+    "mcp>=1.0.0",
+]
+
+[project.scripts]
+diffcontext = "diffcontext.cli:cli_main"
+diffcontext-mcp = "diffcontext.mcp_server:main"
+
+[tool.setuptools.packages.find]
+include = ["diffcontext*"]
+
+[tool.setuptools.package-data]
+diffcontext = ["py.typed"]