purecontext-mcp 1.1.1 → 1.1.2

package/docs/dev/PHASE24_TASKS.md

@@ -1,326 +0,0 @@
-# Phase 24 — Git & History Integration
-
-**Goal**: Make code history navigable at the symbol level. Show when a symbol was introduced, who last changed it, how frequently it churns, and which symbols a PR touches — turning PureContext from a static index into a living history of the codebase.
-
-**Scope rationale**: jCodeMunch has no git integration whatsoever. This phase is pure differentiation. Developers and AI agents routinely need to know "when was this added?", "who owns this?", and "what does this PR break?" — today they must leave their tool and run git commands manually. PureContext can answer all of this inline.
-
----
-
-## Task 154: Git Metadata Indexing
-
-Extend the indexing pipeline to capture commit-level metadata (SHA, author, date, message) for each file and persist it in the database.
-
-**Current state**: The `files` table stores file paths, content hashes, and byte sizes. No git metadata is captured. The `index_repo` tool uses `git clone --depth=1` — a shallow clone that loses history.
-
-**Deliverables**:
-
-- `src/core/db/schema.ts` — extend `files` table:
-  ```sql
-  ALTER TABLE files ADD COLUMN last_commit_sha TEXT;
-  ALTER TABLE files ADD COLUMN last_commit_author TEXT;
-  ALTER TABLE files ADD COLUMN last_commit_date INTEGER;   -- Unix timestamp
-  ALTER TABLE files ADD COLUMN last_commit_message TEXT;
-  ALTER TABLE files ADD COLUMN commit_count INTEGER;       -- Total commits touching this file
-  ```
-  Add `git_metadata` table for full per-file commit history (limited):
-  ```sql
-  CREATE TABLE IF NOT EXISTS git_metadata (
-    repo_id      TEXT NOT NULL,
-    file_path    TEXT NOT NULL,
-    commit_sha   TEXT NOT NULL,
-    author_name  TEXT NOT NULL,
-    author_email TEXT NOT NULL,
-    commit_date  INTEGER NOT NULL,
-    message      TEXT NOT NULL,
-    PRIMARY KEY (repo_id, file_path, commit_sha)
-  );
-  ```
-- `src/core/git-log-reader.ts` — new module:
-  ```typescript
-  interface CommitRecord {
-    sha: string;
-    authorName: string;
-    authorEmail: string;
-    date: number;         // Unix timestamp
-    message: string;
-  }
-
-  interface FileGitMeta {
-    lastCommit: CommitRecord;
-    commitCount: number;
-    history: CommitRecord[];  // Last N commits (default: 10)
-  }
-
-  async function readFileHistory(
-    repoRoot: string,
-    filePath: string,
-    limit?: number
-  ): Promise<FileGitMeta>
-
-  async function readRepoMeta(repoRoot: string): Promise<{
-    defaultBranch: string;
-    headSha: string;
-    remoteUrl?: string;
-  }>
-  ```
-- Use `git log --follow --format="%H|%an|%ae|%at|%s" -n {limit} -- {filePath}` parsed line-by-line
-- `src/core/index-manager.ts` — after indexing, run `git-log-reader` for each processed file and store in `files` + `git_metadata` tables
-- Make git metadata capture optional: skip gracefully if not a git repo (e.g. local folder without git)
-- For GitHub API-indexed repos (Task 137): populate from the GitHub commits API instead of local git
-
-**Key technical notes**:
-- Shallow clones lack history — switch `index_repo` from `--depth=1` to `--depth=50` (configurable via `GIT_HISTORY_DEPTH` env var) to capture recent commits
-- For local folder indexing, git metadata is available at no extra cost — just parse `git log` output
-- `commit_count` is expensive for large repos (requires `git log --follow -- file | wc -l`) — use `git log --oneline -n 501 -- file | wc -l` to count up to 500, then cap display at "500+"
-- Schema migration: add `SCHEMA_VERSION` bump and migration path for existing indexes
-
-**Tests**: `test/core/git-log-reader.test.ts`
-- Parse `git log` output correctly (all fields)
-- Handle files with no git history (non-git folder)
-- `commitCount` accurate for files with < 10 commits
-- GitHub API fallback (mocked)
-
-**Verify**:
-```bash
-# After indexing a git repo, query the files table:
-# SELECT file_path, last_commit_author, last_commit_date FROM files LIMIT 5
-```
-
----
-
-## Task 155: Symbol-Level Change Tracking Tool
-
-New `get_symbol_history` tool — show the git history of the file containing a symbol, filtered to commits that actually touched the symbol's line range.
-
-**Current state**: Git metadata is stored at the file level (Task 154). There is no way to ask "when was *this specific function* last changed?" — file history includes unrelated changes.
-
-**Deliverables**:
-
-- `src/server/tools/get-symbol-history.ts` — new MCP tool:
-  ```typescript
-  interface GetSymbolHistoryInput {
-    repoId: string;
-    symbolId: string;
-    limit?: number;          // Default 10, max 50
-  }
-
-  interface SymbolCommit {
-    sha: string;
-    shortSha: string;        // First 8 chars
-    author: string;
-    date: string;            // ISO 8601
-    daysAgo: number;
-    message: string;
-    linesAdded?: number;
-    linesRemoved?: number;
-  }
-
-  interface GetSymbolHistoryOutput {
-    symbol: {
-      name: string;
-      kind: SymbolKind;
-      filePath: string;
-    };
-    history: SymbolCommit[];
-    totalCommits: number;
-    firstSeen?: SymbolCommit;   // Oldest commit in history (commit that introduced it)
-    lastChanged: SymbolCommit;  // Most recent commit
-    churnScore: number;          // Commits per 90 days — higher = more volatile
-    _meta: ResponseMeta;
-  }
-  ```
-- Implementation:
-  1. Look up symbol → get `filePath`, `startByte`, `endByte`
-  2. Convert byte offsets to line range (start line, end line)
-  3. Run `git log -L {startLine},{endLine}:{filePath}` (line-range log) — captures only commits touching those lines
-  4. Parse output into `SymbolCommit[]`
-  5. Calculate `churnScore`: `(commitCount / daysSinceFirstCommit) * 90`
-- `src/core/git-log-reader.ts` — add `readSymbolHistory(repoRoot, filePath, startLine, endLine, limit)`
-- For GitHub API repos: fall back to file-level history from `git_metadata` table (line-range tracking not available without local clone)
-
-**Key technical notes**:
-- `git log -L` is slow on large files with long histories — apply the `limit` early via `-n {limit}` flag
-- Line-range tracking: `git log -L` follows the code even if it moves within the file (renamed lines) — this is more accurate than date-filtering the file history
-- `churnScore` is a useful proxy for "how risky is this symbol?" — high churn = frequently changing = more likely to have bugs, more risky to modify
-- `firstSeen` may not be in the `limit` window — use a separate `git log -L ... --diff-filter=A` call to find the introducing commit
-
-**Tests**: `test/server/get-symbol-history.test.ts`
-- Returns commits touching the symbol's line range
-- `churnScore` calculated correctly
-- `firstSeen` populated
-- Symbol not found → error
-- No git history (non-git folder) → graceful empty response
-
-**Verify**:
-```bash
-# get_symbol_history { repoId: "...", symbolId: "abc123", limit: 10 }
-# Should show commits that touched the function's line range, with churn score
-```
-
----
-
-## Task 156: PR / Diff Impact Analysis Tool
-
-New `analyze_diff` tool — given a git diff (unified format), identify all symbols that are added, modified, or deleted, and calculate the downstream blast radius.
-
-**Current state**: Agents reviewing PRs must manually call `get_blast_radius` for each changed file. There is no tool that accepts a diff and produces a consolidated impact summary.
-
-**Deliverables**:
-
-- `src/server/tools/analyze-diff.ts` — new MCP tool:
-  ```typescript
-  interface AnalyzeDiffInput {
-    repoId: string;
-    diff: string;              // Unified diff format (git diff output)
-    includeBlastRadius?: boolean;  // Default true — compute downstream impact
-    blastRadiusDepth?: number;     // Default 2
-  }
-
-  interface ChangedSymbol {
-    symbolId: string;
-    name: string;
-    kind: SymbolKind;
-    filePath: string;
-    changeType: 'added' | 'modified' | 'deleted' | 'signature_changed';
-    signatureBefore?: string;  // For modified symbols
-    signatureAfter?: string;
-  }
-
-  interface AnalyzeDiffOutput {
-    summary: {
-      filesChanged: number;
-      symbolsAdded: number;
-      symbolsModified: number;
-      symbolsDeleted: number;
-      signatureBreaks: number;   // Public API surface changes
-    };
-    changedSymbols: ChangedSymbol[];
-    blastRadius?: {
-      filesImpacted: number;
-      symbolsImpacted: number;
-      impactedFiles: string[];
-    };
-    reviewPriority: 'low' | 'medium' | 'high' | 'critical';  // Derived from blast radius + signature breaks
-    _meta: ResponseMeta;
-  }
-  ```
-- Diff parsing (`src/core/diff-parser.ts`):
-  - Parse unified diff into per-file changed line ranges
-  - Map changed line ranges to symbols using byte-offset lookup from the DB
-  - Detect signature changes: compare old symbol signature (from git history) vs new (from current index)
-- `reviewPriority` heuristic:
-  - `critical`: any public API signature changed + blast radius > 10 files
-  - `high`: signature changed or blast radius > 5 files
-  - `medium`: implementation changes with blast radius 1–5
-  - `low`: changes to files with no importers
-- Optionally call `get_blast_radius` logic for each modified symbol and aggregate
-
-**Key technical notes**:
-- The diff must be in unified format (`git diff` output with `---`/`+++`/`@@` headers)
-- Line-to-symbol mapping: for each changed line range, query symbols where `startByte <= lineEnd` and `endByte >= lineStart` (using the file's content to convert lines to bytes)
-- "Signature changed": compare `symbols.signature` in DB (current index) vs parsing the old content from the diff's `-` lines
-- This tool is most valuable in CI pipelines (GitHub Actions) and code review workflows
-
-**Tests**: `test/server/analyze-diff.test.ts`
-- Simple diff with added function → `changeType: 'added'`
-- Modified function body → `changeType: 'modified'`
-- Changed function signature → `changeType: 'signature_changed'`
-- Deleted function → `changeType: 'deleted'`
-- `blastRadius` aggregated correctly
-- `reviewPriority` heuristic validated
-
-**Verify**:
-```bash
-# git diff HEAD~1 | npx purecontext-mcp  # pipe diff to the tool via CLI
-# analyze_diff { repoId: "...", diff: "<unified diff content>" }
-```
-
----
-
-## Task 157: Change Velocity Metrics Tool
-
-New `get_churn_metrics` tool — report code churn (change frequency) across the entire repo or a specific directory, identifying the most volatile files and symbols.
-
-**Current state**: Git metadata is stored per-file (Task 154) but not surfaced as a tool. There is no way to ask "which parts of this codebase change most often?" — critical for risk assessment and architecture decisions.
-
-**Deliverables**:
-
-- `src/server/tools/get-churn-metrics.ts` — new MCP tool:
-  ```typescript
-  interface GetChurnMetricsInput {
-    repoId: string;
-    scope?: string;           // Directory prefix filter (e.g. "src/core/")
-    dayWindow?: number;       // Look back N days, default 90
-    topN?: number;            // Return top N files/symbols by churn, default 20
-    granularity: 'file' | 'symbol';
-  }
-
-  interface ChurnRecord {
-    filePath: string;
-    symbolName?: string;      // Only when granularity: 'symbol'
-    symbolKind?: SymbolKind;
-    commitCount: number;
-    uniqueAuthors: number;
-    lastChanged: string;      // ISO date
-    churnScore: number;       // Commits per 90 days
-    riskLevel: 'stable' | 'active' | 'volatile' | 'hotspot';
-  }
-
-  interface GetChurnMetricsOutput {
-    repoId: string;
-    dayWindow: number;
-    topChurn: ChurnRecord[];
-    summary: {
-      totalFilesAnalyzed: number;
-      hotspots: number;        // Files with churnScore > 10
-      stableFiles: number;     // Files with churnScore < 1
-      mostActiveAuthor: string;
-    };
-    _meta: ResponseMeta;
-  }
-  ```
-- Data source: `git_metadata` table (populated by Task 154)
-- `churnScore`: commits in the `dayWindow` ÷ (dayWindow / 90)
-- `riskLevel` thresholds: `stable` < 1, `active` 1–5, `volatile` 5–10, `hotspot` > 10
-- For `granularity: 'symbol'`, join against `symbols` table — use line-range overlap to assign commits to symbols (same approach as Task 155)
-- `scope` filter: `WHERE file_path LIKE 'src/core/%'`
-
-**Key technical notes**:
-- This tool requires `git_metadata` to be populated — skip gracefully if git metadata wasn't captured (non-git project)
-- `granularity: 'symbol'` is expensive for large repos — apply `topN` limit and use indexed queries
-- Hotspot identification is actionable: files with high churn and high blast radius are the most dangerous areas to modify
-- Consider adding a combined metric: `churnScore × blastRadius` as a "refactoring priority" score
-
-**Tests**: `test/server/get-churn-metrics.test.ts`
-- `granularity: 'file'` — top N files by commit count
-- `granularity: 'symbol'` — top N symbols
-- `scope` filter narrows to directory
-- `dayWindow` correctly scopes to date range
-- `riskLevel` assigned correctly
-- No git metadata → clear error with hint
-
-**Verify**:
-```bash
-# get_churn_metrics { repoId: "...", granularity: "file", topN: 10 }
-# Should show the 10 most frequently changed files with risk levels
-```
-
----
-
-## Order of Execution
-
-```
-154 (git metadata indexing)  ──▶  155 (symbol history)
-                              ──▶  156 (diff analysis — needs symbol-to-line mapping)
-                              ──▶  157 (churn metrics — needs git_metadata table)
-```
-
-Task 154 is the prerequisite for all others. 155, 156, and 157 can be parallelized after 154.
-
----
-
-## Phase 24 Completion
-
-**Before**: PureContext is a snapshot tool — it sees code as it is now, with no sense of time. Agents must leave PureContext to run git commands for history, authorship, and PR review.
-
-**After**: Code history is queryable at the symbol level. Agents can see when a function was introduced, who last changed it, how volatile it is, and what a PR touches — all inline, without leaving the MCP session. No competing code navigation tool offers this. jCodeMunch has zero git integration.