purecontext-mcp 1.1.1 → 1.1.2

package/docs/dev/PHASE25_TASKS.md

@@ -1,452 +0,0 @@
-# Phase 25 — AI-Powered Architecture Analysis
-
-**Goal**: Turn PureContext into a code intelligence platform — not just retrieval, but diagnosis and guidance. Detect anti-patterns, calculate complexity, generate architecture docs, find refactoring opportunities, and bundle the right context for any task description.
-
-**Scope rationale**: jCodeMunch is a retrieval tool. PureContext already has the dependency graph, symbol index, semantic embeddings, and AI summarization pipeline — the ingredients for analysis. This phase combines them into tools that reason about code quality, risk, and structure. No other MCP tool does this.
-
----
-
-## Task 158: Code Quality Metrics
-
-Calculate and store per-symbol code quality metrics (complexity, size, coupling) during indexing, and expose them via a query tool.
-
-**Current state**: Symbols store source code, signatures, and summaries. No quality metrics are calculated. Agents assessing risk must read source code manually.
-
-**Deliverables**:
-
-- `src/core/db/schema.ts` — extend `symbols` table:
-  ```sql
-  ALTER TABLE symbols ADD COLUMN line_count INTEGER;
-  ALTER TABLE symbols ADD COLUMN cyclomatic_complexity INTEGER;
-  ALTER TABLE symbols ADD COLUMN cognitive_complexity INTEGER;
-  ALTER TABLE symbols ADD COLUMN param_count INTEGER;
-  ALTER TABLE symbols ADD COLUMN return_count INTEGER;     -- Number of return statements
-  ALTER TABLE symbols ADD COLUMN nesting_depth INTEGER;    -- Max nesting level
-  ```
-- `src/core/metrics/complexity-calculator.ts`:
-  ```typescript
-  interface ComplexityMetrics {
-    lineCount: number;
-    cyclomaticComplexity: number;   // Decision points + 1
-    cognitiveComplexity: number;    // SonarSource cognitive complexity score
-    paramCount: number;
-    returnCount: number;
-    nestingDepth: number;
-  }
-
-  function calculateComplexity(
-    source: string,
-    language: 'typescript' | 'javascript' | 'python' | ...
-  ): ComplexityMetrics
-  ```
-- Cyclomatic complexity: count `if`, `else if`, `for`, `while`, `case`, `catch`, `&&`, `||`, `?` → +1 each, start at 1
-- Cognitive complexity: weight nested structures higher (SonarSource algorithm — nesting adds to the increment)
-- `src/core/parse-dispatcher.ts` — after extracting symbols, run `calculateComplexity` on each symbol's source and store metrics
-- `src/server/tools/get-quality-metrics.ts` — new MCP tool:
-  ```typescript
-  interface GetQualityMetricsInput {
-    repoId: string;
-    scope?: string;          // Directory filter
-    kind?: SymbolKind;
-    sortBy?: 'complexity' | 'size' | 'nesting' | 'params';
-    threshold?: {
-      cyclomaticComplexity?: number;   // Only return symbols above threshold
-      lineCount?: number;
-      nestingDepth?: number;
-    };
-    limit?: number;          // Default 20
-  }
-
-  interface SymbolQualityRecord {
-    symbolId: string;
-    name: string;
-    kind: SymbolKind;
-    filePath: string;
-    lineCount: number;
-    cyclomaticComplexity: number;
-    cognitiveComplexity: number;
-    paramCount: number;
-    nestingDepth: number;
-    qualityScore: number;    // 0–100 composite (higher = worse)
-    riskLevel: 'good' | 'moderate' | 'high' | 'critical';
-  }
-
-  interface GetQualityMetricsOutput {
-    reposId: string;
-    symbolsAnalyzed: number;
-    worstOffenders: SymbolQualityRecord[];
-    summary: {
-      avgComplexity: number;
-      avgLineCount: number;
-      criticalCount: number;
-      goodCount: number;
-    };
-    _meta: ResponseMeta;
-  }
-  ```
-- `qualityScore` composite: weighted average of normalized complexity, size, nesting, params
-- `riskLevel`: `good` (score < 25), `moderate` (25–50), `high` (50–75), `critical` (> 75)
-
-**Key technical notes**:
-- Complexity calculation is pure text/token analysis — no tree-sitter traversal needed for basic cyclomatic complexity (token counting). For cognitive complexity, nesting detection benefits from AST traversal
-- Start with token-based heuristics; tree-sitter traversal can be added incrementally per language handler
-- Metrics are calculated at index time — zero overhead at query time
-- Do not calculate metrics for `kind: 'const'` or `kind: 'type'` — only for functions, methods, and classes
-
-**Tests**: `test/core/complexity-calculator.test.ts`
-- Simple function → complexity 1
-- Function with 3 if-branches → complexity 4
-- Nested loops → higher cognitive complexity than equivalent non-nested code
-- `get_quality_metrics` returns sorted results
-- Threshold filter works
-
-**Verify**:
-```bash
-# get_quality_metrics { repoId: "...", threshold: { cyclomaticComplexity: 10 }, sortBy: "complexity" }
-# Returns functions with CC > 10, sorted descending
-```
-
----
-
-## Task 159: Anti-Pattern Detection Tool
-
-New `detect_antipatterns` tool — scan the indexed repo for structural anti-patterns: circular dependencies, god classes, high-coupling modules, and overly deep inheritance.
-
-**Current state**: `get_layer_violations` detects one specific class of violations (layered architecture breaks). There is no general-purpose anti-pattern scanner.
-
-**Deliverables**:
-
-- `src/server/tools/detect-antipatterns.ts` — new MCP tool:
-  ```typescript
-  interface DetectAntipatternsInput {
-    repoId: string;
-    checks?: AntipatternCheck[];  // Omit to run all checks
-    severity?: 'all' | 'warning' | 'error';
-  }
-
-  type AntipatternCheck =
-    | 'circular_dependencies'
-    | 'god_class'
-    | 'high_coupling'
-    | 'dead_code'
-    | 'deep_nesting'
-    | 'long_parameter_list'
-    | 'duplicate_code';
-
-  interface AntipatternFinding {
-    check: AntipatternCheck;
-    severity: 'warning' | 'error';
-    filePath: string;
-    symbolId?: string;
-    symbolName?: string;
-    description: string;       // Human-readable explanation
-    evidence: string;          // Specific data supporting the finding
-    suggestion: string;        // Actionable remediation hint
-  }
-
-  interface DetectAntipatternsOutput {
-    repoId: string;
-    findingsCount: number;
-    errorCount: number;
-    warningCount: number;
-    findings: AntipatternFinding[];
-    healthScore: number;   // 0–100 (100 = no findings)
-    _meta: ResponseMeta;
-  }
-  ```
-- Individual checks:
-  - **`circular_dependencies`**: traverse `dep_edges` with DFS cycle detection — any cycle is an error
-  - **`god_class`**: classes with `line_count > 500` OR `method_count > 20` — error
-  - **`high_coupling`**: files imported by > 10 other files (efferent coupling) — warning; > 20 — error
-  - **`dead_code`**: reuse `find_dead_code` tool logic — exported symbols with zero importers — warning
-  - **`deep_nesting`**: symbols with `nesting_depth > 5` (from Task 158 metrics) — error
-  - **`long_parameter_list`**: functions/methods with `param_count > 7` — warning; > 10 — error
-  - **`duplicate_code`**: symbols with cosine similarity > 0.95 to another symbol of the same kind (uses HNSW index) — warning
-- `healthScore`: `100 - (errors × 10 + warnings × 2)` clamped to 0
-
-**Key technical notes**:
-- `duplicate_code` check requires HNSW semantic index — skip gracefully if not available and note in response
-- Cycle detection: existing `graph-traversal.ts` has DFS infrastructure — extend with cycle tracking
-- `god_class` method count: query `COUNT(*)` from `symbols` where `file_path = class_file AND kind = 'method'`
-- This tool is intended to be run periodically (e.g. in CI) and the output consumed by humans or AI reviewers
-
-**Tests**: `test/server/detect-antipatterns.test.ts`
-- Circular dependency detected in fixture with cycle
-- God class detected when method count > 20
-- High coupling detected for widely-imported file
-- Dead code reuses find_dead_code logic
-- `healthScore` calculation correct
-- `checks` filter runs only specified checks
-
-**Verify**:
-```bash
-# detect_antipatterns { repoId: "...", checks: ["circular_dependencies", "god_class"] }
-```
-
----
-
-## Task 160: Architecture Documentation Generator
-
-New `generate_docs` tool — produce a structured markdown architecture document for a repo (or a directory within it) from the indexed symbols, dependency graph, and AI summaries.
-
-**Current state**: Repos are indexed with AI-generated summaries per symbol. There is no tool that assembles these into a coherent architecture document. Teams spend significant time writing and maintaining architecture docs manually.
-
-**Deliverables**:
-
-- `src/server/tools/generate-docs.ts` — new MCP tool:
-  ```typescript
-  interface GenerateDocsInput {
-    repoId: string;
-    scope?: string;            // Directory prefix (e.g. "src/core/")
-    format?: 'markdown' | 'json';
-    includeSymbols?: boolean;  // Default true — list key symbols per module
-    includeDependencies?: boolean;  // Default true — show import relationships
-    includeMetrics?: boolean;  // Default false — append quality metrics
-    aiEnhance?: boolean;       // Default true — use AI to write module descriptions
-  }
-
-  interface ModuleDoc {
-    path: string;
-    title: string;
-    description: string;       // AI-generated or from top docstring
-    publicSymbols: {
-      name: string;
-      kind: SymbolKind;
-      signature: string;
-      summary: string;
-    }[];
-    dependsOn: string[];       // Modules this one imports from
-    importedBy: string[];      // Modules that import this one
-    metrics?: {
-      symbolCount: number;
-      avgComplexity: number;
-    };
-  }
-
-  interface GenerateDocsOutput {
-    repoId: string;
-    title: string;
-    generatedAt: string;
-    moduleCount: number;
-    document: string;          // Full markdown or JSON
-    _meta: ResponseMeta;
-  }
-  ```
-- Document structure (markdown):
-  ```markdown
-  # {Repo Name} — Architecture Overview
-  _Generated by PureContext on {date}_
-
-  ## Modules
-
-  ### src/core/index-manager.ts
-  {AI-generated description of what this module does}
-
-  **Public API:**
-  - `indexFolder(path, options)` — Orchestrates full indexing pipeline
-  - `reindexFiles(repoId, paths)` — Incremental re-index for changed files
-
-  **Depends on:** `file-discovery`, `parse-dispatcher`, `symbol-store`
-  **Imported by:** `mcp-server`, `index-folder tool`
-
-  ---
-  ```
-- AI enhancement (`aiEnhance: true`): for modules without a top-level docstring, call the configured AI summarizer with a prompt: "Given these exported symbols from {filePath}, write a 2-sentence description of what this module does and its role in the codebase."
-- Batch AI calls: group up to 10 modules per API call (same batch infrastructure as `ai-summarizer.ts`)
-- Non-AI fallback: assemble description from the first docstring found in the file, or from the summary of the most-imported symbol
-
-**Key technical notes**:
-- This tool is intentionally token-heavy (it generates a document, not retrieves one) — do not include it in `_meta` token savings calculations
-- `aiEnhance` requires a configured AI provider — check config and warn clearly if none is set
-- Output is useful both for humans (review the markdown) and for AI agents (pass the doc to another LLM for higher-level analysis)
-- The `json` format produces structured data for downstream tooling (CI pipelines, wikis, etc.)
-
-**Tests**: `test/server/generate-docs.test.ts`
-- Markdown output contains all modules in scope
-- Each module has public symbols listed
-- Dependencies listed correctly from dep_edges
-- `aiEnhance: false` — no AI calls made
-- `scope` filter narrows to directory
-- `format: 'json'` returns parseable JSON
-
-**Verify**:
-```bash
-# generate_docs { repoId: "...", scope: "src/core/", aiEnhance: false }
-# Should produce a markdown architecture doc for the core module
-```
-
----
-
-## Task 161: Smart Context Bundling
-
-New `get_task_context` tool — given a natural language task description, determine and return the minimal but complete set of symbols and files an agent needs to complete that task.
-
-**Current state**: `get_context_bundle` returns a fixed symbol + its imports. Agents must still iterate — run multiple searches, read multiple symbols, discover what they need through trial and error. There is no tool that reasons about "what do I need to understand to accomplish X?"
-
-**Deliverables**:
-
-- `src/server/tools/get-task-context.ts` — new MCP tool:
-  ```typescript
-  interface GetTaskContextInput {
-    repoId: string;
-    task: string;              // Natural language: "add OAuth login to the user service"
-    maxSymbols?: number;       // Default 15, max 50
-    includeSource?: boolean;   // Default false — return source or just metadata
-    model?: string;            // AI model for context planning (default: configured summarizer)
-  }
-
-  interface ContextItem {
-    symbolId: string;
-    name: string;
-    kind: SymbolKind;
-    filePath: string;
-    signature: string;
-    summary: string;
-    relevanceReason: string;   // Why this symbol is needed for the task
-    source?: string;           // Only when includeSource: true
-    role: 'primary' | 'dependency' | 'test' | 'config';
-  }
-
-  interface GetTaskContextOutput {
-    task: string;
-    plan: string;              // AI-generated brief plan: what files/areas to touch
-    contextItems: ContextItem[];
-    estimatedFiles: string[];  // Files the agent will likely need to modify
-    totalTokens: number;       // Estimated tokens for all context items
-    _meta: ResponseMeta;
-  }
-  ```
-- Two-stage pipeline:
-  1. **Discovery**: run `search_semantic` (hybrid mode) with the task description to find the top 30 candidate symbols
-  2. **Ranking**: call the AI with: task description + top 30 candidate symbol summaries + dependency graph context → ask the AI to select the most relevant 15 and explain each one's role
-- AI prompt template (in `src/server/tools/get-task-context.ts`):
-  ```
-  Task: {task}
-
-  Available symbols (name, kind, file, summary):
-  {candidates}
-
-  Select the most relevant symbols for completing this task. For each selected symbol, state:
-  - Why it's needed (relevanceReason)
-  - Its role: primary (directly implements the feature), dependency (needed to understand/call), test (test file to update), config (configuration to modify)
-
-  Also provide: a brief plan (2-3 sentences) and which files are likely to be modified.
-  ```
-- Fall back to pure semantic search ranking (no AI call) if no AI provider configured
-- `includeSource: true` fetches full source for each symbol using batch retrieval (`get_symbols` logic from Task 133)
-
-**Key technical notes**:
-- This tool's value is in reducing agent iteration loops — instead of 10 search-and-read cycles, one call delivers everything needed
-- The AI stage is optional but dramatically improves relevance — without it, the tool degrades to a ranked semantic search
-- Cost: one embedding call (task description) + one AI completion call (selection + planning) + N symbol source reads
-- The AI model used for planning need not be the same as the summarization model — configure separately if needed
-
-**Tests**: `test/server/get-task-context.test.ts`
-- Semantic discovery returns candidates
-- AI selection narrows to `maxSymbols`
-- `relevanceReason` populated for each item
-- `includeSource: true` returns symbol source
-- No AI provider → falls back to semantic ranking
-- `_meta` does not double-count token savings
-
-**Verify**:
-```bash
-# get_task_context { repoId: "...", task: "add rate limiting to the API endpoints", maxSymbols: 10 }
-# Should return relevant symbols with roles and a brief plan
-```
-
----
-
-## Task 162: Refactoring Opportunity Detector
-
-New `find_refactoring_opportunities` tool — identify functions that are too large, parameters that should be objects, duplicated logic, and classes that could be extracted.
-
-**Current state**: Code quality metrics (Task 158) flag individual symbols. There is no tool that connects these signals into actionable refactoring recommendations with specific suggestions.
-
-**Deliverables**:
-
-- `src/server/tools/find-refactoring-opportunities.ts` — new MCP tool:
-  ```typescript
-  interface FindRefactoringOpportunitiesInput {
-    repoId: string;
-    scope?: string;
-    types?: RefactoringType[];  // Omit for all
-    minImpact?: 'low' | 'medium' | 'high';
-  }
-
-  type RefactoringType =
-    | 'extract_function'       // Function too long → split it
-    | 'introduce_parameter_object'  // Too many params → group them
-    | 'extract_class'          // File too large, too many responsibilities
-    | 'inline_function'        // Trivial wrapper with one callsite
-    | 'consolidate_duplicates' // Near-duplicate functions → merge
-    | 'simplify_conditional'   // Deep nesting → early returns
-
-  interface RefactoringOpportunity {
-    type: RefactoringType;
-    impact: 'low' | 'medium' | 'high';
-    symbolId: string;
-    symbolName: string;
-    filePath: string;
-    description: string;       // "Function has 120 lines and complexity 24"
-    suggestion: string;        // "Extract lines 45-80 into a separate validateInput() function"
-    effort: 'trivial' | 'small' | 'medium' | 'large';
-  }
-
-  interface FindRefactoringOpportunitiesOutput {
-    repoId: string;
-    totalOpportunities: number;
-    opportunities: RefactoringOpportunity[];
-    estimatedImpact: string;   // "Reducing complexity by ~30% across 8 symbols"
-    _meta: ResponseMeta;
-  }
-  ```
-- Detection logic per type:
-  - **`extract_function`**: `line_count > 50 AND cyclomatic_complexity > 10`
-  - **`introduce_parameter_object`**: `param_count > 5`
-  - **`extract_class`**: file with `symbol_count > 15` of mixed kinds — multiple responsibilities
-  - **`inline_function`**: function with `line_count <= 3` AND imported by exactly 1 file
-  - **`consolidate_duplicates`**: HNSW similarity > 0.92 between two functions of the same kind
-  - **`simplify_conditional`**: `nesting_depth > 4 AND return_count > 3` — candidate for early-return refactor
-- Suggestions are templated per type — not AI-generated (deterministic, fast)
-- `effort` heuristic: based on line count and blast radius of the symbol
-
-**Key technical notes**:
-- All detection uses stored metrics (Task 158) + dep_edges — no additional parsing at query time
-- `consolidate_duplicates` requires HNSW — skip if not available
-- Sort by `impact` descending, then `effort` ascending (highest value, lowest effort first)
-- Results are actionable: each opportunity points to a specific symbol with a specific suggestion
-
-**Tests**: `test/server/find-refactoring-opportunities.test.ts`
-- Long complex function → `extract_function` opportunity
-- Many-param function → `introduce_parameter_object`
-- Trivial single-callsite function → `inline_function`
-- Deep nesting → `simplify_conditional`
-- `types` filter limits to specified types
-- `minImpact` filter excludes low-impact findings
-
-**Verify**:
-```bash
-# find_refactoring_opportunities { repoId: "...", types: ["extract_function", "simplify_conditional"] }
-```
-
----
-
-## Order of Execution
-
-```
-158 (quality metrics)          ──▶  159 (antipatterns — uses metrics)
-                               ──▶  162 (refactoring — uses metrics)
-160 (generate docs)            ── independent (uses AI summarizer)
-161 (smart context bundling)   ── independent (uses semantic search + AI)
-```
-
-Recommended sequence: 158 → 159 → 162 → 161 → 160
-
----
-
-## Phase 25 Completion
-
-**Before**: PureContext retrieves code. Quality, risk, and architecture are invisible without reading source manually.
-
-**After**: Every symbol carries a quality score. Anti-patterns are detected automatically. Architecture docs are generated on demand. Smart context bundling eliminates the multi-step "what do I need?" discovery loop. Refactoring opportunities are served on a plate with specific suggestions. This is a fundamentally different product category from jCodeMunch — not a retrieval tool but a code intelligence platform.