gitflow-analytics 1.0.0__py3-none-any.whl → 1.0.3__py3-none-any.whl

gitflow_analytics/tui/widgets/progress_widget.py

@@ -0,0 +1,192 @@
+"""Progress widget with ETA for GitFlow Analytics TUI."""
+
+import time
+from typing import Optional
+from datetime import datetime, timedelta
+
+from textual.widgets import ProgressBar, Label
+from textual.containers import Container, Vertical
+from textual.reactive import reactive
+from rich.text import Text
+
+
+class AnalysisProgressWidget(Container):
+    """
+    Custom progress widget that shows progress with ETA calculation.
+    
+    WHY: Standard progress bars don't provide time estimates which are crucial 
+    for long-running analysis operations. This widget combines progress tracking
+    with ETA calculations to give users better feedback.
+    
+    DESIGN DECISION: Uses reactive attributes for real-time updates and 
+    calculates ETA based on average processing speed rather than simple linear
+    extrapolation for more accurate estimates.
+    """
+    
+    DEFAULT_CSS = """
+    AnalysisProgressWidget {
+        height: auto;
+        border: solid $primary;
+        margin: 1;
+        padding: 1;
+    }
+    
+    .progress-title {
+        text-style: bold;
+        color: $primary;
+        margin-bottom: 1;
+    }
+    
+    .progress-status {
+        color: $text;
+        margin-top: 1;
+    }
+    
+    .progress-eta {
+        color: $accent;
+        text-style: italic;
+    }
+    """
+    
+    progress = reactive(0.0)
+    total = reactive(100.0)
+    status_text = reactive("Initializing...")
+    
+    def __init__(
+        self,
+        title: str,
+        total: float = 100.0,
+        *,
+        name: Optional[str] = None,
+        id: Optional[str] = None,
+        classes: Optional[str] = None
+    ) -> None:
+        super().__init__(name=name, id=id, classes=classes)
+        self.title = title
+        self.total = total
+        self.start_time = time.time()
+        self.last_update_time = time.time()
+        self.progress_history = []
+        
+    def compose(self):
+        """Compose the progress widget."""
+        yield Label(self.title, classes="progress-title")
+        yield ProgressBar(total=self.total, id="progress-bar")
+        yield Label(self.status_text, classes="progress-status", id="status-label")
+        yield Label("", classes="progress-eta", id="eta-label")
+    
+    def update_progress(self, value: float, status: str = "") -> None:
+        """
+        Update progress and status with ETA calculation.
+        
+        WHY: Provides comprehensive progress updates including time estimates
+        which are essential for user experience during long operations.
+        
+        @param value: Current progress value
+        @param status: Status message to display
+        """
+        current_time = time.time()
+        
+        # Update reactive values
+        self.progress = value
+        if status:
+            self.status_text = status
+            
+        # Update progress bar
+        progress_bar = self.query_one("#progress-bar", ProgressBar)
+        progress_bar.update(progress=value)
+        
+        # Update status label
+        status_label = self.query_one("#status-label", Label)
+        status_label.update(status)
+        
+        # Calculate and update ETA
+        eta_text = self._calculate_eta(value, current_time)
+        eta_label = self.query_one("#eta-label", Label)
+        eta_label.update(eta_text)
+        
+        # Store progress history for better ETA calculation
+        self.progress_history.append({
+            'time': current_time,
+            'progress': value
+        })
+        
+        # Keep only recent history (last 10 updates)
+        if len(self.progress_history) > 10:
+            self.progress_history = self.progress_history[-10:]
+    
+    def _calculate_eta(self, current_progress: float, current_time: float) -> str:
+        """
+        Calculate estimated time of arrival based on progress history.
+        
+        WHY: Uses historical data points to calculate a more accurate ETA
+        than simple linear extrapolation, accounting for variations in 
+        processing speed.
+        """
+        if current_progress <= 0 or current_progress >= self.total:
+            return ""
+            
+        # Need at least 2 data points for calculation
+        if len(self.progress_history) < 2:
+            return "Calculating ETA..."
+        
+        # Calculate average rate from recent history
+        recent_history = self.progress_history[-5:]  # Last 5 updates
+        if len(recent_history) < 2:
+            return "Calculating ETA..."
+        
+        time_span = recent_history[-1]['time'] - recent_history[0]['time']
+        progress_span = recent_history[-1]['progress'] - recent_history[0]['progress']
+        
+        if time_span <= 0 or progress_span <= 0:
+            return "Calculating ETA..."
+        
+        # Calculate rate (progress per second)
+        rate = progress_span / time_span
+        
+        # Calculate remaining work and time
+        remaining_progress = self.total - current_progress
+        estimated_seconds = remaining_progress / rate
+        
+        # Format ETA
+        if estimated_seconds < 60:
+            return f"ETA: {estimated_seconds:.0f}s"
+        elif estimated_seconds < 3600:
+            minutes = estimated_seconds / 60
+            return f"ETA: {minutes:.1f}m"
+        else:
+            hours = estimated_seconds / 3600
+            return f"ETA: {hours:.1f}h"
+    
+    def reset(self) -> None:
+        """Reset the progress widget to initial state."""
+        self.progress = 0.0
+        self.status_text = "Initializing..."
+        self.start_time = time.time()
+        self.progress_history = []
+        
+        # Reset UI elements
+        progress_bar = self.query_one("#progress-bar", ProgressBar)
+        progress_bar.update(progress=0)
+        
+        status_label = self.query_one("#status-label", Label)
+        status_label.update("Initializing...")
+        
+        eta_label = self.query_one("#eta-label", Label)
+        eta_label.update("")
+    
+    def complete(self, final_message: str = "Complete!") -> None:
+        """Mark progress as complete."""
+        self.update_progress(self.total, final_message)
+        
+        # Calculate total elapsed time
+        total_time = time.time() - self.start_time
+        if total_time < 60:
+            time_str = f"{total_time:.1f}s"
+        elif total_time < 3600:
+            time_str = f"{total_time/60:.1f}m"
+        else:
+            time_str = f"{total_time/3600:.1f}h"
+            
+        eta_label = self.query_one("#eta-label", Label)
+        eta_label.update(f"Completed in {time_str}")

gitflow_analytics-1.0.3.dist-info/METADATA

@@ -0,0 +1,490 @@
+Metadata-Version: 2.4
+Name: gitflow-analytics
+Version: 1.0.3
+Summary: Analyze Git repositories for developer productivity insights
+Author-email: Bob Matyas <bobmatnyc@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/bobmatnyc/gitflow-analytics
+Project-URL: Documentation, https://github.com/bobmatnyc/gitflow-analytics/blob/main/README.md
+Project-URL: Repository, https://github.com/bobmatnyc/gitflow-analytics
+Project-URL: Issues, https://github.com/bobmatnyc/gitflow-analytics/issues
+Keywords: git,analytics,productivity,metrics,development
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Version Control :: Git
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.1
+Requires-Dist: gitpython>=3.1
+Requires-Dist: tqdm>=4.65
+Requires-Dist: sqlalchemy>=2.0
+Requires-Dist: pandas>=2.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: python-dateutil>=2.8
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: spacy>=3.7.0
+Requires-Dist: scikit-learn>=1.3.0
+Requires-Dist: openai>=1.30.0
+Requires-Dist: tiktoken>=0.7.0
+Requires-Dist: numpy>=1.24.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Requires-Dist: black>=23.0; extra == "dev"
+Requires-Dist: isort>=5.0; extra == "dev"
+Requires-Dist: bandit[toml]>=1.7; extra == "dev"
+Requires-Dist: safety>=2.0; extra == "dev"
+Requires-Dist: python-semantic-release>=8.0.0; extra == "dev"
+Requires-Dist: types-PyYAML>=6.0; extra == "dev"
+Requires-Dist: types-requests>=2.28; extra == "dev"
+Provides-Extra: github
+Requires-Dist: pygithub>=1.58; extra == "github"
+Provides-Extra: tui
+Requires-Dist: textual>=0.41.0; extra == "tui"
+Provides-Extra: all
+Requires-Dist: gitflow-analytics[github,tui]; extra == "all"
+Dynamic: license-file
+
+# GitFlow Analytics
+
+[![PyPI version](https://badge.fury.io/py/gitflow-analytics.svg)](https://badge.fury.io/py/gitflow-analytics)
+[![Python Support](https://img.shields.io/pypi/pyversions/gitflow-analytics.svg)](https://pypi.org/project/gitflow-analytics/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A Python package for analyzing Git repositories to generate comprehensive developer productivity reports. It extracts data directly from Git history and GitHub APIs, providing weekly summaries, productivity insights, and gap analysis.
+
+## Features
+
+- 🚀 **Multi-repository analysis** with project grouping
+- 🏢 **Organization-based repository discovery** from GitHub
+- 👥 **Developer identity resolution** and normalization
+- 📊 **Work volume analysis** (absolute vs relative effort)
+- 🎯 **Story point extraction** from commit messages and PR descriptions
+- 🎫 **Multi-platform ticket tracking** (JIRA, GitHub Issues, ClickUp, Linear)
+- 📈 **Weekly CSV reports** with productivity metrics
+- 🔒 **Data anonymization** for external sharing
+- ⚡ **Smart caching** for fast repeated analyses
+- 🔄 **Batch processing** for large repositories
+
+## Quick Start
+
+### Installation
+
+**From PyPI (Recommended):**
+
+```bash
+pip install gitflow-analytics
+```
+
+**From Source (Development):**
+
+```bash
+git clone https://github.com/bobmatnyc/gitflow-analytics.git
+cd gitflow-analytics
+pip install -e ".[dev]"
+```
+
+### Basic Usage
+
+1. Create a configuration file (`config.yaml`):
+
+**Option A: Organization-based (Automatic Repository Discovery)**
+```yaml
+version: "1.0"
+
+github:
+  token: "${GITHUB_TOKEN}"
+  organization: "myorg"  # Automatically discovers all repositories
+
+analysis:
+  story_point_patterns:
+    - "(?:story\\s*points?|sp|pts?)\\s*[:=]\\s*(\\d+)"
+    - "\\[(\\d+)\\s*(?:sp|pts?)\\]"
+```
+
+**Option B: Repository-based (Manual Configuration)**
+```yaml
+version: "1.0"
+
+github:
+  token: "${GITHUB_TOKEN}"
+  owner: "${GITHUB_OWNER}"
+
+repositories:
+  - name: "frontend"
+    path: "~/repos/frontend"
+    github_repo: "myorg/frontend"
+    project_key: "FRONTEND"
+    
+  - name: "backend"
+    path: "~/repos/backend"
+    github_repo: "myorg/backend"
+    project_key: "BACKEND"
+
+analysis:
+  story_point_patterns:
+    - "(?:story\\s*points?|sp|pts?)\\s*[:=]\\s*(\\d+)"
+    - "\\[(\\d+)\\s*(?:sp|pts?)\\]"
+```
+
+2. Create a `.env` file in the same directory as your `config.yaml`:
+
+```bash
+# .env
+GITHUB_TOKEN=ghp_your_github_token_here
+GITHUB_OWNER=your_github_org  # Only for repository-based setup
+```
+
+3. Run the analysis:
+
+```bash
+gitflow-analytics analyze -c config.yaml
+```
+
+## Configuration Options
+
+### Environment Variables and Credentials
+
+GitFlow Analytics automatically loads environment variables from a `.env` file in the same directory as your configuration YAML. This is the recommended approach for managing credentials securely.
+
+#### Step 1: Create a `.env` file
+
+Create a `.env` file next to your configuration YAML:
+
+```bash
+# .env file (same directory as your config.yaml)
+# GitHub credentials (required)
+GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx
+GITHUB_OWNER=myorg  # Optional: default owner for repositories
+
+# JIRA credentials (optional - only if using JIRA integration)
+JIRA_ACCESS_USER=your.email@company.com
+JIRA_ACCESS_TOKEN=xxxxxxxxxxxxxxxxxxxx
+
+# Other optional tokens
+CLICKUP_TOKEN=pk_xxxxxxxxxxxx
+LINEAR_TOKEN=lin_api_xxxxxxxxxxxx
+```
+
+#### Step 2: Reference in YAML configuration
+
+Use `${VARIABLE_NAME}` syntax in your YAML to reference environment variables:
+
+```yaml
+# config.yaml
+version: "1.0"
+
+github:
+  token: "${GITHUB_TOKEN}"        # Required
+  owner: "${GITHUB_OWNER}"        # Optional
+  organization: "${GITHUB_ORG}"   # Optional (for org-based discovery)
+
+# Optional: JIRA integration
+jira:
+  access_user: "${JIRA_ACCESS_USER}"
+  access_token: "${JIRA_ACCESS_TOKEN}"
+  base_url: "https://yourcompany.atlassian.net"
+
+# Optional: Configure which JIRA fields contain story points
+jira_integration:
+  story_point_fields:
+    - "Story Points"
+    - "customfield_10016"  # Your custom field ID
+```
+
+#### Important Notes:
+
+- **Never commit `.env` files** to version control (add to `.gitignore`)
+- If credentials are not found in the `.env` file, the tool will exit with an informative error
+- The `.env` file must be in the same directory as your YAML configuration
+- All configured services must have corresponding environment variables set
+
+### Organization vs Repository-based Setup
+
+GitFlow Analytics supports two main configuration approaches:
+
+#### Organization-based Configuration (Recommended)
+
+Automatically discovers all non-archived repositories from a GitHub organization:
+
+```yaml
+version: "1.0"
+
+github:
+  token: "${GITHUB_TOKEN}"
+  organization: "myorg"  # Your GitHub organization name
+
+# Optional: Customize analysis settings
+analysis:
+  story_point_patterns:
+    - "(?:story\\s*points?|sp|pts?)\\s*[:=]\\s*(\\d+)"
+  
+  exclude:
+    authors:
+      - "dependabot[bot]"
+      - "github-actions[bot]"
+```
+
+**Benefits:**
+- Automatically discovers new repositories as they're added to the organization
+- No need to manually configure each repository
+- Simplified configuration management
+- Perfect for teams with many repositories
+
+**Requirements:**
+- Your GitHub token must have organization read access
+- Repositories will be automatically cloned to local directories if they don't exist
+
+#### Repository-based Configuration
+
+Manually specify each repository to analyze:
+
+```yaml
+version: "1.0"
+
+github:
+  token: "${GITHUB_TOKEN}"
+  owner: "${GITHUB_OWNER}"  # Default owner for repositories
+
+repositories:
+  - name: "frontend"
+    path: "~/repos/frontend"
+    github_repo: "myorg/frontend"
+    project_key: "FRONTEND"
+    
+  - name: "backend"
+    path: "~/repos/backend"
+    github_repo: "myorg/backend"
+    project_key: "BACKEND"
+
+analysis:
+  story_point_patterns:
+    - "(?:story\\s*points?|sp|pts?)\\s*[:=]\\s*(\\d+)"
+```
+
+**Benefits:**
+- Fine-grained control over which repositories to analyze
+- Custom project keys and local paths
+- Works with mixed-ownership repositories
+- Compatible with existing configurations
+
+### Directory Defaults
+
+GitFlow Analytics now defaults cache and report directories to be relative to the configuration file location:
+
+- **Reports**: Default to same directory as config file (unless overridden with `--output`)
+- **Cache**: Default to `.gitflow-cache/` in config file directory
+- **Backward compatibility**: Absolute paths in configuration continue to work as before
+
+Example directory structure:
+```
+/project/
+├── config.yaml          # Configuration file
+├── weekly_metrics.csv    # Reports generated here by default
+├── summary.csv
+└── .gitflow-cache/       # Cache directory
+    ├── gitflow_cache.db
+    └── identities.db
+```
+
+## Command Line Interface
+
+### Main Commands
+
+```bash
+# Analyze repositories
+gitflow-analytics analyze -c config.yaml --weeks 12 --output ./reports
+
+# Show cache statistics
+gitflow-analytics cache-stats -c config.yaml
+
+# List known developers
+gitflow-analytics list-developers -c config.yaml
+
+# Merge developer identities
+gitflow-analytics merge-identity -c config.yaml dev1_id dev2_id
+
+# Discover JIRA story point fields
+gitflow-analytics discover-jira-fields -c config.yaml
+```
+
+### Options
+
+- `--weeks, -w`: Number of weeks to analyze (default: 12)
+- `--output, -o`: Output directory for reports (default: ./reports)
+- `--anonymize`: Anonymize developer information
+- `--no-cache`: Disable caching for fresh analysis
+- `--clear-cache`: Clear cache before analysis
+- `--validate-only`: Validate configuration without running
+
+## Complete Configuration Example
+
+Here's a complete example showing `.env` file and corresponding YAML configuration:
+
+### `.env` file
+```bash
+# GitHub Configuration
+GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx
+GITHUB_ORG=EWTN-Global
+
+# JIRA Configuration
+JIRA_ACCESS_USER=developer@ewtn.com
+JIRA_ACCESS_TOKEN=ATATT3xxxxxxxxxxx
+
+# Optional: Other integrations
+# CLICKUP_TOKEN=pk_xxxxxxxxxxxx
+# LINEAR_TOKEN=lin_api_xxxxxxxxxxxx
+```
+
+### `config.yaml` file
+```yaml
+version: "1.0"
+
+# GitHub configuration with organization discovery
+github:
+  token: "${GITHUB_TOKEN}"
+  organization: "${GITHUB_ORG}"
+
+# JIRA integration for story points
+jira:
+  access_user: "${JIRA_ACCESS_USER}"
+  access_token: "${JIRA_ACCESS_TOKEN}"
+  base_url: "https://ewtn.atlassian.net"
+
+jira_integration:
+  enabled: true
+  fetch_story_points: true
+  story_point_fields:
+    - "Story point estimate"     # Your field name
+    - "customfield_10016"        # Fallback field ID
+
+# Analysis configuration
+analysis:
+  # Only track JIRA tickets (ignore GitHub issues, etc.)
+  ticket_platforms:
+    - jira
+  
+  # Exclude bot commits and boilerplate files
+  exclude:
+    authors:
+      - "dependabot[bot]"
+      - "renovate[bot]"
+    paths:
+      - "**/node_modules/**"
+      - "**/*.min.js"
+      - "**/package-lock.json"
+  
+  # Developer identity consolidation
+  identity:
+    similarity_threshold: 0.85
+    manual_mappings:
+      - primary_email: "john.doe@company.com"
+        aliases:
+          - "jdoe@oldcompany.com"
+          - "john@personal.com"
+
+# Output configuration
+output:
+  directory: "./reports"
+  formats:
+    - csv
+    - markdown
+```
+
+## Output Reports
+
+The tool generates three CSV reports:
+
+1. **Weekly Metrics** (`weekly_metrics_YYYYMMDD.csv`)
+   - Week-by-week developer productivity
+   - Story points, commits, lines changed
+   - Ticket coverage percentages
+   - Per-project breakdown
+
+2. **Summary Statistics** (`summary_YYYYMMDD.csv`)
+   - Overall project statistics
+   - Platform-specific ticket counts
+   - Top contributors
+
+3. **Developer Report** (`developers_YYYYMMDD.csv`)
+   - Complete developer profiles
+   - Total contributions
+   - Identity aliases
+
+## Story Point Patterns
+
+Configure custom regex patterns to match your team's story point format:
+
+```yaml
+story_point_patterns:
+  - "SP: (\\d+)"           # SP: 5
+  - "\\[([0-9]+) pts\\]"   # [3 pts]
+  - "estimate: (\\d+)"     # estimate: 8
+```
+
+## Ticket Platform Support
+
+Automatically detects and tracks tickets from:
+- **JIRA**: `PROJ-123`
+- **GitHub**: `#123`, `GH-123`
+- **ClickUp**: `CU-abc123`
+- **Linear**: `ENG-123`
+
+### JIRA Integration
+
+GitFlow Analytics can fetch story points directly from JIRA tickets. Configure your JIRA instance:
+
+```yaml
+jira:
+  access_user: "${JIRA_ACCESS_USER}"
+  access_token: "${JIRA_ACCESS_TOKEN}"
+  base_url: "https://your-company.atlassian.net"
+
+jira_integration:
+  enabled: true
+  story_point_fields:
+    - "Story point estimate"  # Your custom field name
+    - "customfield_10016"     # Or use field ID
+```
+
+To discover your JIRA story point fields:
+```bash
+gitflow-analytics discover-jira-fields -c config.yaml
+```
+
+## Caching
+
+The tool uses SQLite for intelligent caching:
+- Commit analysis results
+- Developer identity mappings
+- Pull request data
+
+Cache is automatically managed with configurable TTL.
+
+## Developer Identity Resolution
+
+Intelligently merges developer identities across:
+- Different email addresses
+- Name variations
+- GitHub usernames
+
+Manual overrides supported in configuration.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.