headquarter/openspec/changes/archive/2026-05-19-git-history-visualization/tasks.md

Git History Visualization - Tasks

Phase 1: Backend API

• Task 1.1: Create git history extraction module

  • Create src/utils/git_history.py
  • Implement get_commit_history(repo_path, limit=100) function
  • Parse git log --graph --format=... output
  • Extract commit hashes, parents, authors, dates, messages
  • Extract branch information
  • Add comprehensive unit tests

• Task 1.2: Create commit detail extraction

  • Implement get_commit_detail(repo_path, commit_hash) function
  • Parse git show --format=... --stat output
  • Extract full message, body, stats, file changes
  • Extract diff for each file
  • Add unit tests

• Task 1.3: Create graph data builder

  • Implement build_graph_data(commits) function
  • Calculate node positions (x, y coordinates)
  • Calculate edge connections between commits
  • Handle merge commits (multiple parents)
  • Add unit tests

• Task 1.4: Create history API endpoints

  • Add GET /projects/{project_id}/repositories/{repo_id}/history
  • Add GET /projects/{project_id}/repositories/{repo_id}/commits/{commit_hash}
  • Handle query parameters (view, branch, limit, offset)
  • Return structured JSON response
  • Handle errors (empty repo, invalid commit, etc.)
  • Add integration tests

Phase 2: Frontend Components

• Task 2.1: Create API client for history

  • Add fetchHistory(projectId, repoId, options) function
  • Add fetchCommitDetail(projectId, repoId, commitHash) function
  • Add TypeScript interfaces for all data types

• Task 2.2: Create GraphView component

  • SVG-based commit graph rendering
  • Draw commit nodes (circles)
  • Draw connection lines (straight/curved)
  • Show branch labels
  • Handle click events
  • Color coding for branches

• Task 2.3: Create ListView component

  • Linear list of commits
  • Show hash, message, author, date
  • Handle click events
  • Scrollable with virtualization for large lists

• Task 2.4: Create CommitDetails component

  • Show commit message, author, date
  • Show stats (files changed, insertions, deletions)
  • Show file list with change types
  • Expandable diff viewer
  • Syntax highlighting for diffs

• Task 2.5: Create DiffViewer component

  • Parse and display git diff format
  • Show line numbers
  • Color code: green for additions, red for deletions
  • Handle binary files
  • Collapsible file sections

Phase 3: Page Integration

• Task 3.1: Create GitHistoryPage

  • Layout with view toggle (graph/list)
  • Fetch history data on mount
  • Manage selected commit state
  • Show loading/error states
  • Responsive layout (details panel on right, below on mobile)

• Task 3.2: Add navigation from repository list

  • Add "View History" button to repository cards
  • Link to history page
  • Pass repository info

• Task 3.3: Add route

  • Add /projects/:projectId/repositories/:repoId/history route
  • Update router configuration

Phase 4: Testing & Polish

• Task 4.1: Add backend tests

  • Test git log parsing
  • Test graph data building
  • Test API endpoints
  • Test error handling

• Task 4.2: Add frontend tests

  • Test component rendering
  • Test user interactions (click, toggle)
  • Test data transformations

• Task 4.3: Run quality gates

  • Backend: ruff, mypy, pytest
  • Frontend: typecheck, lint, build

• Task 4.4: Performance optimization

  • Implement pagination for large repositories
  • Add caching for history data
  • Optimize graph rendering

• Task 4.5: Documentation

  • Update README with feature description
  • Add screenshots/diagrams
  • Document API endpoints