gitflow-analytics 1.0.0__tar.gz

gitflow_analytics-1.0.0/CHANGELOG.md

@@ -0,0 +1,54 @@
+# Changelog
+
+All notable changes to GitFlow Analytics will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2025-07-29
+
+### Added
+- Initial release of GitFlow Analytics
+- Core Git repository analysis with batch processing
+- Developer identity resolution with fuzzy matching
+- Manual identity mapping support
+- Story point extraction from commit messages
+- Multi-platform ticket tracking (GitHub, JIRA, Linear, ClickUp)
+- Comprehensive caching system with SQLite
+- CSV report generation:
+  - Weekly metrics
+  - Developer statistics
+  - Activity distribution
+  - Developer focus analysis
+  - Qualitative insights
+- Markdown narrative reports with insights
+- JSON export for API integration
+- DORA metrics calculation:
+  - Deployment frequency
+  - Lead time for changes
+  - Mean time to recovery
+  - Change failure rate
+- GitHub PR enrichment (optional)
+- Branch to project mapping
+- YAML configuration with environment variable support
+- Progress bars for long operations
+- Anonymization support for reports
+
+### Configuration Features
+- Repository definitions with project keys
+- Story point extraction patterns
+- Developer identity similarity threshold
+- Manual identity mappings
+- Default ticket platform specification
+- Branch mapping rules
+- Output format selection
+- Cache TTL configuration
+
+### Developer Experience
+- Clear CLI with helpful error messages
+- Comprehensive documentation
+- Sample configuration files
+- Progress indicators during analysis
+- Detailed logging of operations
+
+[1.0.0]: https://github.com/bobmatnyc/gitflow-analytics/releases/tag/v1.0.0

gitflow_analytics-1.0.0/CLAUDE.md

@@ -0,0 +1,201 @@
+# Claude Developer Instructions for GitFlow Analytics
+
+This document provides specific instructions for Claude (AI assistant) when working on the GitFlow Analytics project. It ensures consistent development practices and helps maintain code quality.
+
+## Project Overview
+
+GitFlow Analytics is a Python package that analyzes Git repositories to generate developer productivity insights without requiring external project management tools. It provides comprehensive metrics including commit patterns, developer focus, ticket tracking, and DORA metrics.
+
+## Key Development Guidelines
+
+### 1. Code Quality Standards
+
+When modifying code:
+- **Always run linting and type checking** before committing:
+  ```bash
+  ruff check src/
+  mypy src/
+  black src/
+  ```
+- **Run tests** after making changes:
+  ```bash
+  pytest tests/
+  ```
+- **Follow existing code patterns** - check neighboring files for conventions
+
+### 2. Identity Resolution
+
+The project has a sophisticated developer identity resolution system:
+- Handles multiple email addresses per developer
+- Supports manual identity mappings in configuration
+- Uses fuzzy matching with configurable threshold (default: 0.85)
+- **Important**: When debugging identity issues, check `.gitflow-cache/identities.db`
+
+### 3. Caching System
+
+The project uses SQLite for caching:
+- Commit cache: `.gitflow-cache/gitflow_cache.db`
+- Identity cache: `.gitflow-cache/identities.db`
+- **Always provide `--clear-cache` option** when testing configuration changes
+
+### 4. Configuration Management
+
+Configuration uses YAML with environment variable support:
+- Variables use format: `${VARIABLE_NAME}`
+- Default ticket platform can be specified
+- Branch mapping rules for project inference
+- Manual identity mappings for consolidating developer identities
+
+### 5. Report Generation
+
+The system generates multiple report types:
+- **CSV Reports**: Weekly metrics, developer stats, activity distribution
+- **Markdown Reports**: Narrative summaries with insights
+- **JSON Export**: Complete data export for API integration
+
+### 6. Testing Workflow
+
+When testing changes:
+1. Use the recess-recreo repositories as test data
+2. Run with `--weeks 8` for consistent test periods
+3. Check all report outputs for correctness
+4. Verify identity resolution is working properly
+
+### 7. Common Tasks
+
+#### Adding a New Report Type
+
+1. Create report generator in `src/gitflow_analytics/reports/`
+2. Add to report generation pipeline in `cli.py`
+3. Update configuration to support format selection
+4. Document the report format in README
+
+#### Adding a New Ticket Platform
+
+1. Update regex patterns in `TicketExtractor`
+2. Add platform to ticket counting logic
+3. Test with sample commit messages
+4. Update documentation
+
+#### Debugging Identity Issues
+
+1. Check identity database:
+   ```bash
+   sqlite3 .gitflow-cache/identities.db "SELECT * FROM developer_identities"
+   ```
+2. Review manual mappings in config
+3. Clear cache and re-run analysis
+4. Check for typos in email addresses
+
+### 8. Performance Considerations
+
+- **Batch processing**: Commits are processed in batches (default: 1000)
+- **Progress bars**: Use tqdm for long operations
+- **Caching**: Aggressive caching to avoid re-processing
+- **Memory usage**: Be mindful with large repositories
+
+### 9. Error Handling
+
+- **GitHub API errors**: Handle rate limiting and authentication failures gracefully
+- **File system errors**: Check permissions and paths
+- **Database locks**: Use proper session management with SQLAlchemy
+- **Configuration errors**: Provide helpful error messages
+
+### 10. Documentation Updates
+
+When adding features:
+1. Update README.md with user-facing changes
+2. Update this file (CLAUDE.md) with developer notes
+3. Add docstrings to all new functions/classes
+4. Update configuration examples if needed
+
+## Project Structure
+
+```
+gitflow-analytics/
+├── src/gitflow_analytics/
+│   ├── __init__.py          # Package initialization
+│   ├── _version.py          # Version information
+│   ├── cli.py               # CLI entry point
+│   ├── config.py            # Configuration handling
+│   ├── core/                # Core analysis logic
+│   │   ├── analyzer.py      # Git analysis
+│   │   ├── branch_mapper.py # Branch to project mapping
+│   │   ├── cache.py         # Caching system
+│   │   └── identity.py      # Developer identity resolution
+│   ├── extractors/          # Data extraction
+│   │   ├── story_points.py  # Story point extraction
+│   │   └── tickets.py       # Ticket reference extraction
+│   ├── integrations/        # External integrations
+│   │   └── github_client.py # GitHub API client
+│   ├── metrics/             # Metric calculations
+│   │   └── dora.py          # DORA metrics
+│   ├── models/              # Data models
+│   │   └── database.py      # SQLAlchemy models
+│   └── reports/             # Report generation
+│       ├── analytics_writer.py
+│       ├── csv_writer.py
+│       └── narrative_writer.py
+├── tests/                   # Test suite
+├── docs/                    # Documentation
+│   ├── design/              # Design documents
+│   └── DEPLOY.md            # Deployment guide
+├── config-sample.yaml       # Sample configuration
+├── pyproject.toml           # Project metadata
+└── README.md                # User documentation
+```
+
+## Version Management
+
+- Version is stored in `src/gitflow_analytics/_version.py`
+- Follow semantic versioning (MAJOR.MINOR.PATCH)
+- Update version before releases
+- Tag releases with `v` prefix (e.g., `v1.0.0`)
+
+## Release Process
+
+1. Update version in `_version.py`
+2. Run full test suite
+3. Update CHANGELOG.md
+4. Commit with message: `chore: bump version to X.Y.Z`
+5. Tag the release: `git tag -a vX.Y.Z -m "Release version X.Y.Z"`
+6. Push tags: `git push origin main --tags`
+7. Build and publish to PyPI (see DEPLOY.md)
+
+## Common Gotchas
+
+1. **Timezone issues**: GitHub API returns timezone-aware timestamps
+2. **Branch detection**: Simplified branch detection may not work for all workflows
+3. **Memory usage**: Large repositories can consume significant memory
+4. **Identity resolution**: Manual mappings must be applied after initial analysis
+5. **Cache invalidation**: Some changes require clearing the cache
+
+## Quick Commands
+
+```bash
+# Install in development mode
+pip install -e ".[dev]"
+
+# Run analysis on test repos
+gitflow-analytics analyze --config config-recess.yaml --weeks 8
+
+# Clear cache and re-run
+gitflow-analytics analyze --config config-recess.yaml --weeks 8 --clear-cache
+
+# Run tests with coverage
+pytest --cov=gitflow_analytics --cov-report=html
+
+# Format code
+black src/ tests/
+
+# Check code quality
+ruff check src/
+mypy src/
+```
+
+## Contact
+
+For questions about development practices or architecture decisions, refer to:
+- Design documents in `docs/design/`
+- GitHub issues for bug reports
+- Pull request discussions for feature proposals

gitflow_analytics-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Bob Matyas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gitflow_analytics-1.0.0/MANIFEST.in

@@ -0,0 +1,11 @@
+include README.md
+include LICENSE
+include CHANGELOG.md
+include CLAUDE.md
+include pyproject.toml
+include config-sample.yaml
+recursive-include docs *.md
+recursive-include tests *.py
+global-exclude __pycache__
+global-exclude *.py[co]
+global-exclude .DS_Store

gitflow_analytics-1.0.0/PKG-INFO

@@ -0,0 +1,201 @@
+Metadata-Version: 2.4
+Name: gitflow-analytics
+Version: 1.0.0
+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: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+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.8
+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
+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"
+Provides-Extra: github
+Requires-Dist: pygithub>=1.58; extra == "github"
+Provides-Extra: all
+Requires-Dist: gitflow-analytics[github]; extra == "all"
+Dynamic: license-file
+
+# GitFlow Analytics
+
+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
+- 👥 **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
+
+```bash
+pip install gitflow-analytics
+```
+
+### Basic Usage
+
+1. Create a configuration file (`config.yaml`):
+
+```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. Set environment variables:
+
+```bash
+export GITHUB_TOKEN=your_github_token
+export GITHUB_OWNER=your_github_org
+```
+
+3. Run the analysis:
+
+```bash
+gitflow-analytics analyze -c config.yaml
+```
+
+## 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
+```
+
+### 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
+
+## 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`
+
+## 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.

gitflow_analytics-1.0.0/README.md

@@ -0,0 +1,156 @@
+# GitFlow Analytics
+
+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
+- 👥 **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
+
+```bash
+pip install gitflow-analytics
+```
+
+### Basic Usage
+
+1. Create a configuration file (`config.yaml`):
+
+```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. Set environment variables:
+
+```bash
+export GITHUB_TOKEN=your_github_token
+export GITHUB_OWNER=your_github_org
+```
+
+3. Run the analysis:
+
+```bash
+gitflow-analytics analyze -c config.yaml
+```
+
+## 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
+```
+
+### 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
+
+## 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`
+
+## 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.