repo-wrapped 0.0.6 → 0.0.7

package/SPECS.md

@@ -0,0 +1,490 @@
+# Feature Specifications: Lead Developer Insights
+
+> **Goal**: Enable lead developers to gain data-driven insights on repository health, team velocity, and the impact of management decisions — providing ammunition for stakeholder discussions.
+
+---
+
+## 1. Velocity Timeline Visualization
+
+### Purpose
+Show productivity trends over time to demonstrate slowdowns, speedups, or the impact of events.
+
+### CLI Options
+```bash
+--velocity                    # Enable velocity analysis in output
+--velocity-window <weeks>     # Rolling average window (default: 4 weeks)
+```
+
+### Data Structure
+```typescript
+interface VelocityAnalysis {
+  // Time-series data
+  timeline: VelocityDataPoint[];
+  
+  // Computed metrics
+  overallTrend: 'increasing' | 'stable' | 'decreasing' | 'volatile';
+  trendPercentage: number;           // e.g., -35% over period
+  averageCommitsPerWeek: number;
+  peakWeek: { weekStart: Date; commits: number };
+  lowestWeek: { weekStart: Date; commits: number };
+  
+  // Anomaly detection
+  anomalies: VelocityAnomaly[];
+}
+
+interface VelocityDataPoint {
+  weekStart: Date;
+  weekEnd: Date;
+  commits: number;
+  linesAdded: number;
+  linesDeleted: number;
+  filesChanged: number;
+  authors: string[];
+  rollingAverage: number;            // N-week rolling avg
+}
+
+interface VelocityAnomaly {
+  weekStart: Date;
+  type: 'spike' | 'drop' | 'zero-activity';
+  severity: 'minor' | 'significant' | 'critical';  // >20%, >40%, >60% deviation
+  percentageChange: number;
+  possibleCauses: string[];          // Auto-generated hints
+}
+```
+
+### HTML Output
+- Line chart showing commits per week
+- Overlay line for rolling average
+- Highlighted anomaly zones (red for drops, orange for spikes)
+- Trend arrow with percentage in summary card
+
+### Acceptance Criteria
+- [ ] Weekly aggregation of commits with configurable window
+- [ ] Rolling average calculation
+- [ ] Anomaly detection (>30% deviation from rolling average)
+- [ ] Trend calculation over full period
+- [ ] HTML chart using inline SVG or lightweight charting
+
+---
+
+## 2. Date Range Comparison
+
+### Purpose
+Compare metrics between two arbitrary time periods (e.g., "before reorg" vs "after reorg").
+
+### CLI Options
+```bash
+--compare "<start1>..<end1>" "<start2>..<end2>"
+# Example: --compare "2025-01-01..2025-06-30" "2025-07-01..2025-12-31"
+
+--compare-labels "<label1>" "<label2>"
+# Example: --compare-labels "Before Reorg" "After Reorg"
+```
+
+### Data Structure
+```typescript
+interface RangeComparison {
+  range1: {
+    label: string;
+    start: Date;
+    end: Date;
+    metrics: ComparisonMetrics;
+  };
+  range2: {
+    label: string;
+    start: Date;
+    end: Date;
+    metrics: ComparisonMetrics;
+  };
+  
+  // Computed differences
+  changes: MetricChanges;
+  summary: string;                   // Auto-generated narrative
+}
+
+interface ComparisonMetrics {
+  totalCommits: number;
+  commitsPerWeek: number;
+  totalAuthors: number;
+  activeDays: number;
+  activeDaysPercentage: number;
+  averageCommitsPerDay: number;      // On active days
+  qualityScore: number;
+  streakData: { longest: number; average: number };
+  
+  // Detailed breakdowns
+  commitsByType: Record<string, number>;  // feat/fix/docs/etc
+  commitsByAuthor: Record<string, number>;
+}
+
+interface MetricChanges {
+  commits: { absolute: number; percentage: number; trend: 'up' | 'down' | 'stable' };
+  velocity: { absolute: number; percentage: number; trend: 'up' | 'down' | 'stable' };
+  quality: { absolute: number; percentage: number; trend: 'up' | 'down' | 'stable' };
+  activeDays: { absolute: number; percentage: number; trend: 'up' | 'down' | 'stable' };
+  // ... other metrics
+}
+```
+
+### HTML Output
+- Side-by-side cards for each period
+- Delta indicators with arrows and colors (green=improvement, red=decline)
+- Summary narrative: "Velocity decreased 35% in Period 2, with 40% fewer active days"
+
+### Acceptance Criteria
+- [ ] Parse date range format `YYYY-MM-DD..YYYY-MM-DD`
+- [ ] Calculate all metrics for each range independently
+- [ ] Compute percentage changes
+- [ ] Generate comparison narrative
+- [ ] Support custom labels for presentation clarity
+
+---
+
+## 3. Gap Detection & Blocker Analysis
+
+### Purpose
+Identify periods of zero or low activity that may indicate blockers, waiting time, or disruptions.
+
+### CLI Options
+```bash
+--gap-analysis                # Enable gap detection
+--gap-threshold <days>        # Minimum gap to report (default: 3 days)
+```
+
+### Data Structure
+```typescript
+interface GapAnalysis {
+  // All detected gaps
+  gaps: ActivityGap[];
+  
+  // Summary statistics
+  totalGapDays: number;
+  percentageOfPeriodInGaps: number;
+  longestGap: ActivityGap;
+  averageGapLength: number;
+  gapFrequency: number;              // Gaps per month
+  
+  // Pattern detection
+  patterns: GapPattern[];
+  
+  // Risk assessment
+  riskLevel: 'low' | 'medium' | 'high' | 'critical';
+  riskFactors: string[];
+}
+
+interface ActivityGap {
+  start: Date;
+  end: Date;
+  durationDays: number;
+  
+  // Context
+  commitBefore: { date: Date; message: string; author: string } | null;
+  commitAfter: { date: Date; message: string; author: string } | null;
+  
+  // Analysis
+  possibleType: 'weekend' | 'holiday' | 'vacation' | 'blocker' | 'unknown';
+  annotation?: string;               // From event annotations if matched
+}
+
+interface GapPattern {
+  type: 'recurring-weekly' | 'end-of-sprint' | 'after-release' | 'random';
+  description: string;
+  occurrences: number;
+}
+```
+
+### HTML Output
+- Timeline visualization with gap periods highlighted in red
+- Gap cards showing duration, dates, and surrounding context
+- Pattern summary: "4 gaps >5 days detected, totaling 28 lost days (15% of period)"
+
+### Acceptance Criteria
+- [ ] Detect gaps exceeding threshold (configurable, default 3 days)
+- [ ] Exclude weekends from gap calculation (optional flag)
+- [ ] Identify context (commits before/after gap)
+- [ ] Calculate total lost time
+- [ ] Pattern detection for recurring gaps
+
+---
+
+## 4. Author & Team Filtering
+
+### Purpose
+Filter analysis to specific contributors or teams, enabling team-level vs individual comparisons.
+
+### CLI Options
+```bash
+--author "<name>"              # Filter to single author (supports partial match)
+--authors "<name1>,<name2>"    # Filter to multiple authors
+--team <file>                  # Path to team members file (one name per line)
+--exclude-author "<name>"      # Exclude specific author (e.g., bots)
+--exclude-authors "<names>"    # Exclude multiple authors
+```
+
+### Team File Format
+```text
+# team-frontend.txt
+John Doe
+Jane Smith
+Bob Wilson
+```
+
+### Data Structure
+```typescript
+interface AuthorFilter {
+  mode: 'include' | 'exclude';
+  authors: string[];
+  matchType: 'exact' | 'partial';    // Partial allows "John" to match "John Doe"
+}
+
+interface TeamAnalysis {
+  teamName?: string;
+  members: string[];
+  
+  // Aggregated team metrics
+  teamMetrics: {
+    totalCommits: number;
+    commitsPerMember: number;
+    activeDays: number;
+    velocity: VelocityAnalysis;
+    quality: CommitQualityResult;
+  };
+  
+  // Individual breakdowns
+  memberBreakdown: {
+    author: string;
+    commits: number;
+    percentage: number;
+    activeDays: number;
+    qualityScore: number;
+    topAreas: string[];              // Most contributed directories
+  }[];
+  
+  // Distribution analysis
+  loadDistribution: {
+    giniCoefficient: number;         // 0=equal, 1=one person does all
+    assessment: 'balanced' | 'moderate-imbalance' | 'high-imbalance';
+    insights: string[];
+  };
+}
+```
+
+### HTML Output
+- Team summary card with aggregate metrics
+- Individual member cards with contribution breakdown
+- Load distribution chart (bar chart of commits per member)
+- Insights: "60% of commits come from 1 team member"
+
+### Acceptance Criteria
+- [ ] Filter commits by author name (partial match)
+- [ ] Support team file input
+- [ ] Support exclusion patterns (for bots)
+- [ ] Calculate team aggregate metrics
+- [ ] Individual member breakdown
+- [ ] Load distribution analysis (Gini coefficient)
+
+---
+
+## 5. Executive Summary Mode
+
+### Purpose
+Generate a stakeholder-ready 1-page summary with key metrics, trends, and traffic-light indicators.
+
+### CLI Options
+```bash
+--executive-summary           # Generate summary section/page
+--summary-only                # Output ONLY the executive summary
+--pdf                         # Export as PDF (requires puppeteer or similar)
+```
+
+### Data Structure
+```typescript
+interface ExecutiveSummary {
+  generatedAt: Date;
+  period: { start: Date; end: Date };
+  repoName: string;
+  
+  // Key Performance Indicators
+  kpis: {
+    name: string;
+    value: string | number;
+    trend: 'up' | 'down' | 'stable';
+    trendValue: string;              // e.g., "+15%"
+    status: 'green' | 'yellow' | 'red';
+    benchmark?: string;              // e.g., "vs last quarter"
+  }[];
+  
+  // Top-level insights (3-5 bullet points)
+  keyInsights: {
+    type: 'positive' | 'negative' | 'neutral';
+    insight: string;
+  }[];
+  
+  // Risk summary
+  risks: {
+    category: string;
+    level: 'low' | 'medium' | 'high';
+    description: string;
+  }[];
+  
+  // Recommendations (auto-generated)
+  recommendations: string[];
+}
+```
+
+### Default KPIs
+1. **Velocity**: Commits per week (trend vs previous period)
+2. **Quality Score**: Commit message quality (0-10)
+3. **Bus Factor**: Knowledge distribution risk
+4. **Active Contributors**: Unique authors
+5. **Consistency**: Days with commits / total days
+6. **Gap Days**: Lost days due to inactivity
+
+### HTML Output
+- Clean, printable single-page layout
+- Traffic light indicators (colored circles)
+- Trend arrows with percentages
+- Bullet point insights
+- Risk table with colored severity
+
+### Acceptance Criteria
+- [ ] Calculate all KPIs with trends
+- [ ] Auto-determine status thresholds (green/yellow/red)
+- [ ] Generate 3-5 key insights from data
+- [ ] Identify top risks
+- [ ] Clean print-friendly HTML
+- [ ] PDF export capability
+
+---
+
+## 6. Event Annotations
+
+### Purpose
+Mark known events (reorgs, departures, releases) to contextualize metrics and correlate with changes.
+
+### CLI Options
+```bash
+--events <file>               # Path to events JSON file
+--events-inline "<json>"      # Inline events JSON
+```
+
+### Events File Format
+```json
+{
+  "events": [
+    {
+      "date": "2025-07-15",
+      "label": "Reorg announced",
+      "type": "disruption",
+      "description": "Team restructure announced, 2 devs moved to other projects"
+    },
+    {
+      "date": "2025-08-01", 
+      "label": "Senior dev left",
+      "type": "attrition"
+    },
+    {
+      "date": "2025-09-15",
+      "label": "v2.0 Release",
+      "type": "release"
+    },
+    {
+      "date": "2025-10-01",
+      "label": "New team members onboarded",
+      "type": "growth"
+    }
+  ]
+}
+```
+
+### Event Types
+- `disruption` - Reorgs, process changes, blocking decisions
+- `attrition` - Team member departures
+- `growth` - New hires, team expansion
+- `release` - Major releases, deadlines
+- `incident` - Production issues, firefighting periods
+- `external` - Holidays, company events
+- `custom` - User-defined
+
+### Data Structure
+```typescript
+interface EventAnnotation {
+  date: Date;
+  label: string;
+  type: EventType;
+  description?: string;
+  
+  // Auto-computed correlation
+  correlation?: {
+    metricsBefore: Partial<ComparisonMetrics>;  // 2 weeks before
+    metricsAfter: Partial<ComparisonMetrics>;   // 2 weeks after
+    impact: {
+      velocityChange: number;
+      qualityChange: number;
+      activeAuthorsChange: number;
+    };
+    assessment: string;              // "Velocity dropped 40% after this event"
+  };
+}
+
+type EventType = 'disruption' | 'attrition' | 'growth' | 'release' | 'incident' | 'external' | 'custom';
+```
+
+### HTML Output
+- Event markers on timeline/velocity chart
+- Event legend with icons per type
+- Correlation cards: "After 'Reorg announced': velocity -35%, active contributors -2"
+- Event timeline view
+
+### Acceptance Criteria
+- [ ] Parse events JSON file
+- [ ] Display events on velocity timeline
+- [ ] Calculate before/after metrics for each event
+- [ ] Generate correlation assessments
+- [ ] Event filtering by type
+
+---
+
+## Implementation Priority
+
+| Feature | Priority | Complexity | Stakeholder Value |
+|---------|----------|------------|-------------------|
+| Velocity Timeline | P0 | Medium | Critical |
+| Date Range Comparison | P0 | Medium | Critical |
+| Gap Detection | P1 | Low | High |
+| Author/Team Filtering | P1 | Medium | High |
+| Executive Summary | P2 | Medium | High |
+| Event Annotations | P2 | Medium | Medium |
+
+---
+
+## Technical Notes
+
+### File Structure for New Features
+```
+src/
+├── utils/
+│   ├── velocityAnalyzer.ts         # NEW
+│   ├── rangeComparisonAnalyzer.ts  # NEW
+│   ├── gapAnalyzer.ts              # NEW
+│   ├── teamAnalyzer.ts             # NEW
+│   └── executiveSummaryGenerator.ts # NEW
+├── types/
+│   └── index.ts                    # Add new interfaces
+├── generators/html/
+│   ├── templates/
+│   │   ├── velocitySection.ts      # NEW
+│   │   ├── comparisonSection.ts    # NEW
+│   │   ├── gapSection.ts           # NEW
+│   │   ├── teamSection.ts          # NEW
+│   │   └── executiveSummary.ts     # NEW
+│   └── styles/
+│       └── charts.css              # NEW
+└── commands/
+    └── generate.ts                 # Add new CLI options
+```
+
+### Dependencies to Consider
+- Chart rendering: Consider lightweight SVG generation or inline charts
+- PDF export: `puppeteer` or `playwright` for HTML-to-PDF
+- Date handling: Already using `date-fns`