gitflow-analytics 3.10.6__tar.gz → 3.11.1__tar.gz

{gitflow_analytics-3.10.6 → gitflow_analytics-3.11.1}/CLAUDE.md

@@ -128,6 +128,7 @@ GitFlow Analytics uses a comprehensive documentation system organized for differ
 
 - **[docs/STRUCTURE.md](docs/STRUCTURE.md)** - Complete documentation organization guide
 - **[docs/README.md](docs/README.md)** - Main documentation index and navigation
+- **[docs/reference/PROJECT_ORGANIZATION.md](docs/reference/PROJECT_ORGANIZATION.md)** - **Official project organization standard**
 - **[docs/getting-started/](docs/getting-started/)** - New user onboarding and tutorials
 - **[docs/guides/](docs/guides/)** - Task-oriented configuration and usage guides
 - **[docs/examples/](docs/examples/)** - Real-world usage scenarios and templates
@@ -140,6 +141,7 @@ GitFlow Analytics uses a comprehensive documentation system organized for differ
 ### 🟢 Documentation Guidelines for Developers
 
 When working on the project:
+- **Follow PROJECT_ORGANIZATION.md** - See [docs/reference/PROJECT_ORGANIZATION.md](docs/reference/PROJECT_ORGANIZATION.md) for file placement rules
 - **Update docs with code changes** - Documentation should stay current with implementation
 - **Follow the structure** - Place new documentation in the appropriate section
 - **Cross-reference related topics** - Use relative links to connect related information
@@ -589,6 +591,8 @@ When adding features:
 
 ## 🟡 Project Structure
 
+**See [docs/reference/PROJECT_ORGANIZATION.md](docs/reference/PROJECT_ORGANIZATION.md) for complete organization standards.**
+
 ```
 gitflow-analytics/
 ├── src/gitflow_analytics/
@@ -636,12 +640,16 @@ gitflow-analytics/
 ├── tests/                   # Test suite
 │   └── qualitative/        # ML system tests
 ├── docs/                    # Documentation
+│   ├── reference/           # Technical reference
+│   │   └── PROJECT_ORGANIZATION.md  # Official organization standard
 │   ├── design/              # Design documents
-│   └── DEPLOY.md            # Deployment guide
-├── config-sample.yaml       # Sample configuration
-├── config-sample-ml.yaml    # ML configuration sample
-├── pyproject.toml           # Project metadata
-└── README.md                # User documentation
+│   └── [other sections]/   # See docs/STRUCTURE.md
+├── configs/                 # Sample configuration files
+│   ├── config-sample.yaml  # Sample configuration
+│   └── config-sample-ml.yaml # ML configuration sample
+├── scripts/                 # Utility scripts
+├── pyproject.toml          # Project metadata
+└── README.md               # User documentation
 ```
 
 ## 🟡 Atomic Versioning System

{gitflow_analytics-3.10.6 → gitflow_analytics-3.11.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitflow-analytics
-Version: 3.10.6
+Version: 3.11.1
 Summary: Analyze Git repositories for developer productivity insights
 Author-email: Bob Matyas <bobmatnyc@gmail.com>
 License: MIT
@@ -987,7 +987,7 @@ python -m spacy download en_core_web_sm
 # Medium model (more accurate, larger)
 python -m spacy download en_core_web_md
 
-# Large model (most accurate, largest) 
+# Large model (most accurate, largest)
 python -m spacy download en_core_web_lg
 ```
 
@@ -995,7 +995,7 @@ python -m spacy download en_core_web_lg
 
 - **Accuracy**: 85-95% accuracy on typical commit messages
 - **Speed**: ~50-100 commits/second with caching enabled
-- **Fallback**: Graceful degradation to rule-based when ML unavailable
+- **Fallback**: Gracefully disables qualitative analysis if spaCy model unavailable (provides helpful error messages)
 - **Memory**: ~200MB additional memory usage for spaCy models
 
 ### Enhanced Reports

{gitflow_analytics-3.10.6 → gitflow_analytics-3.11.1}/README.md

@@ -929,7 +929,7 @@ python -m spacy download en_core_web_sm
 # Medium model (more accurate, larger)
 python -m spacy download en_core_web_md
 
-# Large model (most accurate, largest) 
+# Large model (most accurate, largest)
 python -m spacy download en_core_web_lg
 ```
 
@@ -937,7 +937,7 @@ python -m spacy download en_core_web_lg
 
 - **Accuracy**: 85-95% accuracy on typical commit messages
 - **Speed**: ~50-100 commits/second with caching enabled
-- **Fallback**: Graceful degradation to rule-based when ML unavailable
+- **Fallback**: Gracefully disables qualitative analysis if spaCy model unavailable (provides helpful error messages)
 - **Memory**: ~200MB additional memory usage for spaCy models
 
 ### Enhanced Reports

gitflow_analytics-3.11.1/docs/_archive/README.md

@@ -0,0 +1,97 @@
+# Documentation Archive
+
+This directory contains archived documentation files that are no longer actively used but are preserved for historical reference and context.
+
+## Purpose
+
+The `_archive/` directory serves to:
+- Preserve temporary documentation created during development
+- Maintain historical context for major features and bug fixes
+- Keep the root directory clean while preserving file history
+- Provide reference material for understanding project evolution
+
+## Organization Policy
+
+### What Goes Here
+
+Files that should be archived include:
+- **Temporary implementation summaries** - Created during feature development
+- **Bug resolution reports** - Detailed investigation and fix documentation
+- **Feature test reports** - Testing documentation for completed features
+- **Code analysis reports** - One-time code structure analyses
+- **Migration guides** - Completed migration documentation
+- **Deprecated guides** - Documentation for removed or replaced features
+
+### What Stays Active
+
+Files that should remain in active documentation:
+- **User guides** - Ongoing usage documentation (docs/guides/)
+- **API references** - Current API specifications (docs/reference/)
+- **Architecture docs** - Current system design (docs/architecture/)
+- **Getting started guides** - Onboarding documentation (docs/getting-started/)
+
+## Retention Policy
+
+- **Permanent retention**: All archived files are kept indefinitely in version control
+- **No automatic deletion**: Files are never automatically removed from archive
+- **Manual cleanup**: Archive review occurs during major version milestones
+- **Git history preservation**: All files moved using `git mv` to maintain history
+
+## Archive Structure
+
+```
+docs/_archive/
+├── README.md                    # This file
+├── temp-files/                  # Temporary documentation files
+│   ├── README.md               # Index of temporary files
+│   ├── code_analysis_report.md
+│   ├── IMPLEMENTATION_SUMMARY.md
+│   └── ...
+├── features/                    # Archived feature documentation
+├── bugs/                        # Archived bug reports
+└── migrations/                  # Archived migration guides
+```
+
+## Finding Archived Content
+
+### By File Name
+```bash
+find docs/_archive -name "*.md" -type f
+```
+
+### By Content
+```bash
+grep -r "search term" docs/_archive/
+```
+
+### By Git History
+```bash
+git log --all --full-history -- "docs/_archive/filename.md"
+```
+
+## Archiving New Files
+
+To archive a file while preserving git history:
+
+```bash
+# 1. Identify the appropriate archive subdirectory
+# 2. Use git mv to preserve history
+git mv path/to/file.md docs/_archive/subdirectory/
+
+# 3. Update the archive index
+# Edit docs/_archive/subdirectory/README.md
+
+# 4. Commit the change
+git commit -m "chore: archive filename.md"
+```
+
+## Cross-References
+
+For current documentation organization, see:
+- [Documentation Structure](../STRUCTURE.md) - Overall documentation organization
+- [Main Documentation Index](../README.md) - Active documentation navigation
+- [Project Organization](../reference/PROJECT_ORGANIZATION.md) - File organization standards
+
+## Version History
+
+- **2025-10-20**: Initial archive structure created with temp-files subdirectory

gitflow_analytics-3.11.1/docs/_archive/temp-files/CHANGELOG_INTERACTIVE_LAUNCHER.md

@@ -0,0 +1,223 @@
+# Changelog - Interactive Launcher & Enhanced Identity Detection
+
+## Version: Next Release
+
+### 🚀 New Features
+
+#### Interactive Launcher (`gitflow-analytics run`)
+- **Interactive repository selection**: Multi-select interface with visual indicators
+- **Persistent preferences**: Automatically saves your selections for future runs
+- **Smart defaults**: Remembers last selected repositories, analysis period, and cache settings
+- **Auto-discovery**: Finds configuration files automatically in common locations
+- **User-friendly workflow**: Guided prompts for all analysis options
+
+**Example Usage**:
+```bash
+gitflow-analytics run  # Interactive mode with auto-discovery
+gitflow-analytics run -c config.yaml  # With specific config
+```
+
+**Preferences Storage**:
+```yaml
+launcher:
+  last_selected_repos: [frontend-app, mobile-app]
+  default_weeks: 8
+  auto_clear_cache: false
+  skip_identity_analysis: false
+  last_run: "2025-10-06T19:00:00Z"
+```
+
+#### Enhanced Identity Detection (90% Confidence)
+- **Increased confidence threshold**: 90% (up from 80%) for higher accuracy
+- **Color-coded display**: Visual confidence indicators (🟢🟡🟠)
+- **Reasoning display**: Shows LLM's reasoning for each identity match
+- **Confidence metadata**: Stores confidence scores and reasoning in config
+- **Better visibility**: See why identities were matched or rejected
+
+**Example Output**:
+```
+🟢 Cluster 1 (Confidence: 95.3%):
+   Primary: john.doe@company.com
+   Alias:   150280367+johndoe@users.noreply.github.com
+   Reason:  Same person based on name patterns and commit timing
+```
+
+### 🔧 Improvements
+
+#### Configuration
+- Added `LauncherPreferences` dataclass for type safety
+- Support for both `canonical_email` and `primary_email` (backward compatible)
+- Confidence and reasoning fields in manual identity mappings
+- Optional `launcher` section in config YAML
+
+#### CLI
+- New `run` command with comprehensive help text
+- Enhanced `identities` command display with confidence scores
+- Improved error messages and user feedback
+- Better subprocess handling for analysis execution
+
+#### Code Quality
+- Comprehensive test suite (5/5 tests passing)
+- Full ruff and black compliance
+- Detailed docstrings and type hints
+- Modular architecture for easy extension
+
+### 📚 Documentation
+
+#### New Guides
+- **Interactive Launcher Guide** (`docs/guides/interactive-launcher.md`)
+  - Complete usage instructions
+  - Troubleshooting section
+  - Advanced usage patterns
+
+- **Enhanced Identity Resolution Guide** (`docs/guides/identity-resolution-enhanced.md`)
+  - Confidence level explanations
+  - Best practices
+  - Configuration examples
+
+- **Quick Reference** (`docs/quick-reference/launcher-and-identity.md`)
+  - Command cheat sheet
+  - Common workflows
+  - Configuration snippets
+
+#### Updated Documentation
+- Implementation summary with architecture details
+- Test coverage documentation
+- Migration guide for existing users
+
+### 🔄 Backward Compatibility
+
+**100% Backward Compatible** - All changes are additive:
+- ✅ Existing configs work without modification
+- ✅ All existing commands unchanged
+- ✅ Manual identity mappings still work
+- ✅ Heuristic fallback still available
+- ✅ No breaking changes to any APIs
+
+### 🧪 Testing
+
+**Test Coverage**:
+- ✅ Import validation
+- ✅ Confidence threshold verification (90%)
+- ✅ Launcher preferences functionality
+- ✅ Manual mappings format
+- ✅ CLI command registration
+
+**Code Quality**:
+- ✅ Ruff: All checks passed
+- ✅ Black: All files formatted correctly
+- ✅ MyPy: Type hints complete (where applicable)
+
+### 📊 Impact Metrics
+
+**Lines of Code**:
+- New code: ~600 LOC
+- Modified: ~100 LOC
+- Documentation: ~800 LOC
+- Tests: ~200 LOC
+
+**Files Changed**:
+- Created: 7 files
+- Modified: 6 files
+- Deleted: 0 files
+
+**Consolidation**:
+- ✅ Reused existing `ConfigLoader` infrastructure
+- ✅ Leveraged existing `IdentityAnalysisPass` system
+- ✅ Extended existing CLI framework
+- ✅ No duplicate functionality added
+
+### 🔐 Security
+
+**Security Enhancements**:
+- ✅ Subprocess execution uses `sys.executable` (no shell=True)
+- ✅ Path validation for configuration files
+- ✅ No credentials stored in preferences
+- ✅ API keys still managed via .env
+- ✅ Manual approval required for identity suggestions
+
+### ⚡ Performance
+
+**Performance Impact**:
+- Interactive launcher: Instant config loading, minimal memory
+- Identity detection: 90% threshold reduces false positives
+- Subprocess isolation: Prevents memory leaks
+- Preference caching: Fast startup for subsequent runs
+
+### 🎯 User Experience
+
+**Before**:
+```bash
+gitflow-analytics analyze -c config.yaml --weeks 8 --clear-cache
+```
+
+**After**:
+```bash
+gitflow-analytics run
+# Interactive prompts guide you through all options
+```
+
+**Benefits**:
+- ⚡ Faster workflow (fewer keystrokes)
+- 🎯 Better accuracy (90% confidence)
+- 👁️ Better visibility (reasoning displayed)
+- 💾 Persistent preferences (remembers your choices)
+- 🎨 Visual feedback (color-coded indicators)
+
+### 🐛 Bug Fixes
+
+None - This is a pure feature addition with enhancements.
+
+### 📝 Notes for Developers
+
+**Architecture Decisions**:
+1. **Subprocess execution**: Chosen over Click context invocation to avoid context pollution
+2. **90% confidence**: Based on testing, provides optimal balance of recall/precision
+3. **Preference storage**: Stored in config YAML for easy version control
+4. **Color indicators**: Universal green/yellow/orange for intuitive understanding
+
+**Extension Points**:
+- Repository filtering can be enhanced with tag-based selection
+- Multiple preference profiles could be supported
+- Batch operations for multiple analyses
+- Active learning from user approvals/rejections
+
+### 🚀 Migration Guide
+
+**For Existing Users**:
+No migration needed! Just start using:
+```bash
+gitflow-analytics run
+```
+
+**For Administrators**:
+Optional config enhancement:
+```yaml
+launcher:
+  default_weeks: 8  # Set your preferred default
+```
+
+### 🔮 Future Enhancements
+
+**Potential Improvements**:
+1. Repository filtering by project tags
+2. Multiple saved preference profiles
+3. Batch analysis operations
+4. Integration testing framework
+5. Confidence threshold per repository
+6. Active learning from user feedback
+7. Pattern caching for common identities
+8. Bulk identity operations
+
+### 🙏 Credits
+
+Implementation based on research findings:
+- LLM identity analyzer architecture
+- Click interactive prompting patterns
+- GitFlow Analytics existing infrastructure
+- User feedback on identity detection accuracy
+
+---
+
+**Release Date**: TBD
+**Version**: TBD (Semantic versioning via conventional commits)