purecontext-mcp 1.1.1 → 1.1.2

package/docs/dev/PHASE13_TASKS.md

@@ -1,381 +0,0 @@
-# Phase 13 — Task Breakdown
-
-**Goal**: Build a web-based UI for visually exploring the symbol graph, viewing dependencies, and navigating codebases interactively. This makes PureContext accessible to developers who prefer visual exploration over CLI/API tools.
-
-**Scope rationale**: While MCP tools serve AI agents effectively, human developers often prefer visual navigation. A web UI enables: exploring unfamiliar codebases, understanding dependency relationships at a glance, and onboarding new team members. The UI complements rather than replaces MCP tools.
-
-**Approach**: Tasks build from a minimal static UI through interactive features to a full-featured code explorer. The UI is optional — PureContext functions fully without it.
-
----
-
-## Task 101: Web UI Foundation
-
-Create the foundational web application structure and build pipeline.
-
-**Deliverables:**
-
-- `src/ui/` — web UI source directory
-  - Technology stack:
-    - **Framework**: React 19 with TypeScript
-    - **Build**: Vite for fast development and optimized production builds
-    - **Styling**: Tailwind CSS for utility-first styling
-    - **State**: Zustand for lightweight state management
-    - **Routing**: React Router for client-side navigation
-
-- `src/ui/package.json`:
-  - Separate package for UI dependencies
-  - Scripts: `dev`, `build`, `preview`
-  - Production build outputs to `dist/ui/`
-
-- `src/ui/src/main.tsx`:
-  - React application entry point
-  - Router configuration
-  - Global error boundary
-
-- `src/ui/src/App.tsx`:
-  - Main application layout
-  - Header with navigation
-  - Sidebar for repo list
-  - Main content area
-
-- `src/ui/src/api/`:
-  - `client.ts`: HTTP client for PureContext API
-  - Type definitions matching MCP tool schemas
-  - Error handling and retry logic
-
-- Integration with PureContext server:
-  - Update `src/server/http-server.ts`:
-    - Serve static files from `dist/ui/` at `/`
-    - SPA fallback: serve `index.html` for client-side routes
-    - API routes at `/api/*` (proxy to MCP tools)
-  - Add REST endpoints for UI:
-    - `GET /api/repos` → `list-repos` tool
-    - `GET /api/repos/:id/tree` → `get-file-tree` tool
-    - `GET /api/repos/:id/outline` → `get-repo-outline` tool
-    - `GET /api/repos/:id/search` → `search-symbols` tool
-    - `GET /api/symbols/:id` → `get-symbol-source` tool
-
-- Build integration:
-  - `npm run build:ui` — build UI only
-  - `npm run build` — build server + UI
-  - `npm run dev` — run server + UI in dev mode (Vite proxy)
-
-**Key technical notes:**
-- UI is optional — server works without UI assets
-- Production build embeds UI in the server package
-- REST endpoints wrap MCP tools for HTTP convenience
-- Vite proxy enables hot reload during development
-
-**Verify:** Run `npm run dev`. Open browser to `http://localhost:3000`. Verify basic layout renders. Verify API calls work via browser dev tools.
-
-**Tests:** API client: mock fetch, verify request format. Build: verify production bundle created. Static serving: verify index.html served. API proxy: verify tool calls work via REST.
-
----
-
-## Task 102: Repository Browser
-
-Implement the repository listing and file tree browser.
-
-**Deliverables:**
-
-- `src/ui/src/pages/RepoList.tsx`:
-  - Display all indexed repositories
-  - Show for each: name, path, symbol count, last indexed
-  - Search/filter repos by name
-  - Click to open repo details
-
-- `src/ui/src/pages/RepoDetail.tsx`:
-  - Repository overview: stats, language breakdown
-  - File tree navigation (collapsible directories)
-  - Click file to view outline
-  - Breadcrumb navigation
-
-- `src/ui/src/components/FileTree.tsx`:
-  - Recursive tree component
-  - Icons for file types (based on extension)
-  - Lazy loading for large directories
-  - Expand/collapse state persistence
-
-- `src/ui/src/components/FileOutline.tsx`:
-  - List symbols in selected file
-  - Group by kind (functions, classes, etc.)
-  - Show signature and summary
-  - Click to view source
-
-- `src/ui/src/stores/repoStore.ts`:
-  - Zustand store for repository state
-  - Caches loaded repos and trees
-  - Tracks current selection
-
-**Key technical notes:**
-- File tree uses virtual scrolling for large repos
-- Lazy loading prevents loading entire tree upfront
-- Icons improve scannability (file type at a glance)
-- State persistence enables back/forward navigation
-
-**Verify:** Open UI. View repo list. Click repo to see details. Navigate file tree. Click file to see outline. Verify symbols displayed correctly.
-
-**Tests:** RepoList: render with mock data. FileTree: expand/collapse. FileOutline: symbol grouping. Store: state updates correctly.
-
----
-
-## Task 103: Symbol Search Interface
-
-Implement interactive symbol search with filtering and results display.
-
-**Deliverables:**
-
-- `src/ui/src/pages/Search.tsx`:
-  - Search input with debounce (300ms)
-  - Filters: kind (dropdown), file pattern (input), language (dropdown)
-  - Results list with highlighting
-  - Keyboard navigation (arrow keys, enter)
-
-- `src/ui/src/components/SearchResults.tsx`:
-  - Display search results
-  - Show: name, kind icon, file path, signature
-  - Highlight matching terms in name/signature
-  - Click to view symbol source
-  - Pagination or infinite scroll
-
-- `src/ui/src/components/SymbolCard.tsx`:
-  - Compact symbol display for search results
-  - Kind icon and badge
-  - Truncated signature
-  - File path with link
-
-- `src/ui/src/components/SearchFilters.tsx`:
-  - Kind filter: multiselect dropdown
-  - Language filter: dropdown from repo languages
-  - File pattern: text input with glob hint
-  - Clear all filters button
-
-- `src/ui/src/hooks/useSearch.ts`:
-  - Custom hook for search state
-  - Debounced query execution
-  - Loading and error states
-  - Result caching
-
-**Key technical notes:**
-- Debounce prevents excessive API calls during typing
-- Highlighting uses the query terms to mark matches
-- Keyboard navigation improves power-user experience
-- Caching recent searches improves perceived performance
-
-**Verify:** Navigate to search. Type query. Verify results appear with debounce. Apply filters. Verify results update. Click result to view source.
-
-**Tests:** Debounce: verify delay. Highlighting: verify term marking. Filters: verify API params. Keyboard nav: arrow/enter work.
-
----
-
-## Task 104: Symbol Source Viewer
-
-Implement syntax-highlighted source code viewing.
-
-**Deliverables:**
-
-- `src/ui/src/pages/SymbolView.tsx`:
-  - Display symbol source code
-  - Syntax highlighting (language-appropriate)
-  - Line numbers with links
-  - Symbol metadata header (name, kind, signature)
-
-- `src/ui/src/components/CodeViewer.tsx`:
-  - Syntax highlighting using `shiki` or `prism-react-renderer`
-  - Language detection from file extension
-  - Line number gutter
-  - Copy button
-
-- `src/ui/src/components/SymbolHeader.tsx`:
-  - Symbol name and kind badge
-  - Full signature display
-  - Summary/docstring
-  - File path link
-
-- `src/ui/src/components/RelatedSymbols.tsx`:
-  - Symbols in same file
-  - Symbols imported by this file
-  - Files that import this symbol
-  - Quick links to navigate
-
-- Language themes:
-  - Light and dark mode support
-  - Theme toggle in header
-  - Persist preference in localStorage
-
-**Key technical notes:**
-- Shiki provides accurate syntax highlighting matching VS Code
-- Related symbols help understand context
-- Theme persistence respects user preference
-- Line numbers enable sharing specific lines
-
-**Verify:** Click symbol from search. Verify source displayed with highlighting. Verify line numbers present. Toggle theme. Verify related symbols listed.
-
-**Tests:** Syntax highlighting: various languages. Theme toggle: state persists. Related symbols: correct links. Copy button: clipboard works.
-
----
-
-## Task 105: Dependency Graph Visualization
-
-Implement interactive dependency graph visualization.
-
-**Deliverables:**
-
-- `src/ui/src/pages/DependencyGraph.tsx`:
-  - Interactive graph of file/symbol dependencies
-  - Nodes: files or symbols (toggleable)
-  - Edges: import relationships
-  - Pan and zoom controls
-  - Click node to view details
-
-- `src/ui/src/components/GraphViewer.tsx`:
-  - Graph rendering using `@xyflow/react` (React Flow)
-  - Force-directed layout using `d3-force`
-  - Node styling by kind/type
-  - Edge styling by relationship type
-  - Performance: limit visible nodes, cluster distant nodes
-
-- `src/ui/src/components/GraphControls.tsx`:
-  - Zoom in/out buttons
-  - Fit to view button
-  - Layout selector (force, hierarchical, radial)
-  - Node filter by kind
-  - Depth slider (1-hop, 2-hop, N-hop dependencies)
-
-- `src/ui/src/components/GraphNode.tsx`:
-  - File node: icon, name, symbol count
-  - Symbol node: kind icon, name
-  - Hover: show details tooltip
-  - Click: select and highlight edges
-
-- Graph data preparation:
-  - `GET /api/repos/:id/graph` endpoint
-  - Returns nodes and edges for visualization
-  - Supports filtering by file/symbol, depth
-  - Pagination for large graphs
-
-**Key technical notes:**
-- React Flow handles canvas interactions
-- Force-directed layout works well for dependency graphs
-- Node clustering prevents visual clutter in large graphs
-- Depth limiting prevents overwhelming visualization
-
-**Verify:** Navigate to dependency graph. Verify nodes and edges render. Pan and zoom. Click node to see details. Adjust depth slider.
-
-**Tests:** Graph rendering: mock data renders correctly. Layout: force simulation stabilizes. Interactions: pan, zoom, click work. Depth filter: correct nodes shown.
-
----
-
-## Task 106: Blast Radius Visualization
-
-Implement blast radius analysis visualization.
-
-**Deliverables:**
-
-- `src/ui/src/pages/BlastRadius.tsx`:
-  - Select a file or symbol to analyze
-  - Display affected files/symbols as graph or list
-  - Color-coded by impact depth
-  - Statistics: files affected, symbols affected, test coverage
-
-- `src/ui/src/components/BlastRadiusGraph.tsx`:
-  - Radial layout with source at center
-  - Rings for 1-hop, 2-hop, 3-hop+ impact
-  - Color gradient from red (direct) to yellow (indirect)
-  - Node size by symbol count
-
-- `src/ui/src/components/BlastRadiusList.tsx`:
-  - Grouped by impact depth
-  - Expandable sections
-  - File path and affected symbols
-  - Link to view each file
-
-- `src/ui/src/components/ImpactStats.tsx`:
-  - Total files affected
-  - Total symbols affected
-  - Direct vs indirect impact breakdown
-  - Estimated review effort (based on file count)
-
-- Integration with `get-blast-radius` tool:
-  - Call tool via REST endpoint
-  - Parse response into visualization data
-  - Handle large result sets (pagination/limiting)
-
-**Key technical notes:**
-- Radial layout clearly shows impact distance
-- Color coding provides instant understanding
-- Statistics help prioritize review effort
-- List view complements graph for detailed review
-
-**Verify:** Select a file. Analyze blast radius. Verify graph shows impacted files with correct depth coloring. Verify statistics match tool output.
-
-**Tests:** Graph layout: radial positioning correct. Color coding: depth colors match. Stats calculation: totals correct. Large result: pagination works.
-
----
-
-## Task 107: Phase 13 Integration Tests
-
-Validate the complete web UI.
-
-**Deliverables:**
-
-- E2E tests using Playwright:
-  - `test/e2e/ui.test.ts`:
-    1. Load home page: verify repo list renders
-    2. Click repo: verify file tree loads
-    3. Navigate tree: expand directories, click file
-    4. View outline: verify symbols displayed
-    5. Search: type query, verify results
-    6. Apply filters: verify results update
-    7. View symbol: verify source highlighted
-    8. Toggle theme: verify colors change
-    9. View graph: verify nodes/edges render
-    10. Analyze blast radius: verify visualization
-
-- Visual regression tests:
-  - Screenshot comparison for key pages
-  - Detect unintended style changes
-
-- Performance tests:
-  - Initial load: < 2 seconds
-  - Search response: < 500ms
-  - Graph render (1000 nodes): < 3 seconds
-
-- Accessibility tests:
-  - Keyboard navigation works throughout
-  - Screen reader compatibility
-  - Color contrast meets WCAG AA
-
-**Verify:** `npm run test:e2e` passes. Visual regressions detected. Performance targets met. Accessibility audit passes.
-
----
-
-## Order of Execution
-
-```
-Task 101: Web UI foundation               ██░░░░░░░░ Foundation
-Task 102: Repository browser              ████░░░░░░ Browse
-Task 103: Symbol search interface         █████░░░░░ Search
-Task 104: Symbol source viewer            ██████░░░░ View
-Task 105: Dependency graph visualization  ████████░░ Graph
-Task 106: Blast radius visualization      █████████░ Analysis
-Task 107: Integration tests               ██████████ Polish
-```
-
-Tasks proceed in order: foundation (101) enables browsing (102) and search (103), which enable viewing (104). Visualization (105, 106) builds on the foundation. Testing (107) validates everything.
-
----
-
-## Phase 13 Completion
-
-With Phase 13 complete, PureContext provides:
-
-1. **MCP Tools** (Phase 1–7): AI-native code navigation via Model Context Protocol
-2. **Token Tracking** (Phase 8): Measurable efficiency gains
-3. **18 Languages** (Phase 9): Comprehensive language coverage
-4. **20+ Framework Adapters** (Phase 10): Deep framework understanding
-5. **Semantic Search** (Phase 11): Meaning-based code discovery
-6. **Multi-tenant Hosting** (Phase 12): Team and enterprise deployments
-7. **Web UI** (Phase 13): Visual exploration for human developers
-
-PureContext is now a complete code intelligence platform serving both AI agents and human developers.