Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[0.9.9] - 2025-11-29

Fixed

• CLI vs GUI Report Inconsistencies: Comprehensive fixes ensuring consistent, transparent analytics reports
  • Chart.js ctx variable duplication eliminated - using unique variable names (velocityCtx, burndownCtx, radarCtx)
  • False 'Partial Data' warnings fixed - commits and branches no longer incorrectly marked as missing
  • Releases export/count mismatch resolved - 219 exported releases now correctly counted in analytics
  • GUI diff mode now explicit - users can see full backup exports are performed, not incremental filtering
  • Data collection transparency improved - collection method clearly shown in reports

Added

• Data Collection Summary Section: New report section showing
  • Collection Method (Full Repository Backup vs Partial Export)
  • Analysis Period (start date, end date, duration)
  • Data Types Analyzed with item counts
  • Notes about missing data types if applicable
• Enhanced Report Metadata: Comprehensive metadata now includes
  • Report generation timestamp
  • Data collection mode
  • Precise period analyzed (From/To dates)
  • Analysis duration for each module
  • Tool version information
• GUI Export Mode Indicator: Export summary now displays
  • "Export Mode: Full Backup (Complete data export)"
  • Making full vs partial exports immediately visible to users

Changed

• Data Completeness Validator: Updated to only mark core data types as missing
  • PRs, Issues, Releases: marked as missing if count is 0
  • Commits, Branches: not marked as missing (may be legitimately 0 or exported in other formats)
  • Prevents false warnings for complete full-backup exports
• Report Structure: Reorganized sections for better clarity
  • Data Collection Summary now appears before Executive Summary
  • Enhanced metadata section with comprehensive collection info
  • Better visual separation of report sections

Technical

• Markdown Generator Enhancement: Added generateDataSummary() method for transparency
• Electron GUI: Updated ExportPanel to display export mode information
• Data Validator: Improved logic to distinguish between "missing" and "not applicable" data types
• Stalled PR Ordering: Verified consistent sorting by waitingDays across CLI and GUI

Quality Assurance

• Verified CLI and GUI reports generate identical metrics
• Confirmed no false "Partial Data" warnings for complete exports
• Validated data consistency: both interfaces show same PR counts, contributors, and metrics
• Tested full backup workflows: all 5 data types exported and counted correctly

[0.9.8] - 2025-11-28

Fixed

• npm Publish Workflow: Fixed duplicate and conflicting npm publish jobs that caused 403 errors
  • Removed fallback publish job that was causing duplicate publish attempts
  • Simplified workflow structure: combine build verification with release creation
  • Fixed references to changelog output variable (changelog → extract-changelog)
  • Added explicit build artifact verification before npm publish
  • Changed to use npm ci for reproducible installs (skips audit and peer dependency warnings)
• npm Package Warnings: Eliminated warnings about bin files not found
  • Cleaned up .npmignore to exclude coverage output files
  • Improved package contents to only include necessary production files
• Release Process: Improved consistency and clarity
  • All builds now use npm run build:all for consistency
  • Tests run with coverage in release job
  • Documentation URLs fixed in publish summary

Changed

• Workflow Architecture: Streamlined GitHub Actions publish workflow
  • Single verify-and-release job replaces separate create-release job
  • Reduced from 3 to 2 parallel publish jobs
  • Better logging and verification steps
  • Improved artifact checking before publishing

Technical

• Updated publish workflow to use latest best practices
• Improved build reproducibility with npm ci
• Enhanced error detection with artifact verification

[0.9.7] - 2025-11-28

Added

• TypeScript Error Resolution: Fixed and resolved all TypeScript compilation errors
  • Strict type checking across entire codebase
  • Enhanced type safety for better code quality
  • Proper error handling in async operations
  • Improved type definitions for all components

Fixed

• TypeScript Compilation: Resolved all TypeScript errors and strict type checking violations
  • Fixed type mismatches in analytics processors
  • Corrected async/await handling in report generators
  • Enhanced type safety in export orchestrator
  • Fixed null/undefined checks in validators
  • Standardized report formatting for consistency
  • Improved data validation in analytics pipeline
• Documentation Cleanup: Removed obsolete and redundant documentation files
  • Cleaned up deprecated documentation artifacts
  • Streamlined documentation structure
  • Improved documentation maintainability

Changed

• Report Formatting: Standardized report output formatting across all report types
  • Consistent section headers and spacing
  • Unified styling for markdown reports
  • Better readability for analytics reports
  • Improved table formatting and alignment

Technical

• Improved code quality through stricter TypeScript checks
• Enhanced type safety throughout the analytics and export modules
• Streamlined development documentation

[0.9.6] - 2025-11-28

Added

• Context-Aware Validation System: Dynamic validation thresholds that adapt to export conditions
  • Base validation threshold: 40% variance acceptable for full online exports
  • Increased thresholds for diff mode (+30%), offline mode (+20%), small datasets (<50 items, +30%), very small datasets (<20 items, +50%)
  • Maximum threshold capped at 95% to prevent false positives
  • Automatic diff mode detection via heuristics (dataset <150 items OR period <60 days)
  • Enhanced validation logging with context information
• Growing Backlog Paradox Detection: New paradox explaining high PR creation with falling merge rates
  • Detects when PR creation velocity exceeds merge rate decline significantly
  • Provides actionable insights about backlog accumulation risks
• Improved Offline Mode Support: Better handling of parsed markdown data
  • All PRs in offline mode now correctly marked as reviewed
  • Cleaned up reviewed-PR filtering logic
  • More accurate analytics from exported markdown files

Changed

• Report Generation Improvements: Enhanced clarity and professionalism
  • Clearer merge-rate recommendations with industry benchmarks
  • Improved table readability with standardized formatting
  • Better business impact notes for stale PRs (Value at Risk, Business Impact, Actions sections)
  • Reduced emoji usage for cleaner presentation
  • Executive Summary now uses h3 instead of h1 to avoid duplicate headers
• Export Logic Simplification: Removed unnecessary UI state management
  • Removed exportComplete state (no longer showing success message in GUI)
  • Removed lastExportPath and lastExportedRepo states
  • Cleaned up redundant export handler updates
• Analytics Metrics: More accurate age-based calculations
  • Added createdAt field to PR data for precise age calculations
  • Value-at-risk now calculated as: PR age (days) × ~2 hours per day
  • Precalculated PR age and metrics for faster report generation

Fixed

• PR Count Consistency: Clarified contradictory PR counts in reports
  • Executive Summary now shows "PRs in period" vs "PRs total" to distinguish scope
  • Resolved 17 vs 41 PR contradiction by labeling data sources clearly
• Projection Confidence: Fixed contradictory low-confidence warnings
  • Projections with low confidence now only show "Insufficient data" message
  • No longer shows alarmist forecasts (e.g., "merge rate will drop to 0%") with low-confidence data
  • Improved logic to check confidence of ALL predictions before forecasting
• Report Quality Issues (from Claude's PM review):
  • Fixed "Data unavailable" display in benchmark tables (now shows "N/A")
  • Removed awkward "Only 0 releases" wording
  • Improved spacing and paragraph breaks in Business Impact sections
  • Removed duplicate headers and fixed HTML structure

Performance

• Increased Data Fetch Limits: Better support for large repositories
  • PRs: 500 → 2000 items
  • Issues: 500 → 2000 items
  • Releases: default → 500 items
  • Extended pagination with configurable timeouts
  • Disabled internal rate limiting for large data fetches
  • Added support for unlimited commits with pagination
• Optimized Stale Items Section: Faster report generation
  • Single pass through bottlenecks array for age calculations
  • Cached timestamp instead of recalculating Date.now() multiple times
  • Reduced from 3 separate iterations to 1 consolidated calculation

Technical

• GitHub CLI Authentication: Improved error messaging
  • Better formatted authentication alerts for users
  • Clear instructions for gh auth login when not authenticated

[0.9.4] - 2025-11-28

Fixed

• NPM Global Installation: Fixed GUI not being pre-built in npm package
  • prepublishOnly script now runs npm run build:all to build both CLI and GUI before publishing
  • GUI files (out/ directory) are now included in npm tarball
  • Global installations now have pre-built GUI - no build tools required
  • Better error handling when GUI files are missing (clear reinstall instructions)
• Graceful GUI Startup: Improved error messages for GUI launch failures
  • Clear instructions to reinstall if GUI files are missing
  • No longer attempts to build GUI when globally installed (no dev dependencies)

[0.9.3] - 2025-11-28

Added

• Electron GUI Application: Complete graphical user interface built with Electron
  • Interactive repository selector with auto-complete
  • Real-time export progress tracking with visual feedback
  • Advanced filtering options (date range, contributor filters)
  • Multi-format export support (Markdown, JSON, PDF)
  • Dark/Light theme support with persistent user preferences
  • Custom cross-platform titlebar with window controls
  • Dropdown menu for reload and dev tools access
  • Fully responsive design for various screen sizes
• Custom UI Components: Professional, theme-aware GUI elements
  • Auto-build and launch system (no manual build required)
  • Theme-aware scrollbar styling that matches app theme
  • System menu with reload and dev tools options
  • Real-time data validation and completeness checks
• Data Completeness Validation: New validation system ensuring consistent reports
  • DataCompletenessValidator checks for required data types
  • Warnings when partial exports are detected
  • Prevents analytics generation from incomplete data
  • User-friendly status messages explaining data gaps
• Enhanced Export Limits: Increased default data capture limits
  • PRs: 500 → 1000 items
  • Issues: 500 → 1000 items
  • Commits: 100 → 500 items (with auto-pagination)
  • Centralized limit configuration in config/export-limits.ts
• Improved Report Consistency: Reports are now complete and accurate regardless of export type
  • Full analytics generated for full backups
  • Partial analytics with warnings for filtered exports
  • Consistent metrics across all export scenarios
  • Debug logging to track metric calculations

Changed

• Architecture Refactoring: Major improvements to codebase organization
  • Separated renderer UI logic from main process logic
  • Modular component structure with dedicated CSS files
  • Clear separation of concerns across CLI and GUI code
  • Better code organization for maintainability
• Export Validation: Enhanced validator behavior
  • Changed from warnings to errors on validation failure
  • Throws exception instead of continuing with inconsistent data
  • Provides actionable error messages to users
• Markdown Parser Extensions: Added support for parsing additional data types
  • parseCommits() method for extracting commit information
  • parseBranches() method for branch data extraction
  • Both methods with proper TypeScript interfaces

Fixed

• Windows PowerShell Compatibility: Fixed titlebar menu button rendering
  • Menu button (hamburguesa icon) displays correctly on Windows
  • Reload button SVG fixed with valid path syntax
  • Dev Tools button properly toggles dev tools open/close
  • Cross-platform compatibility verified for Windows, macOS, Linux
• PDF Report Generation: Fixed Unicode character handling
  • Previously failed on Unicode symbols (emojis, special chars)
  • Now properly handles all Unicode characters in reports
• Linux Support: Verified GUI works on Linux (tested on Nobara/Fedora)
  • Custom titlebar works cross-platform
  • Window controls functional on all platforms

Technical

• Electron Integration:
  • IPC communication between main and renderer processes
  • Window controls (minimize, maximize, close)
  • Dev tools toggle for debugging
  • File system access for folder selection
• Theme System:
  • CSS variables for dark/light theme switching
  • Real-time theme updates without reload
  • Theme preference persistence
• UI/UX Improvements:
  • Custom scrollbar styling with theme awareness
  • Professional icon system with SVGs
  • Smooth transitions and hover effects
  • Accessible color contrast ratios

CI/CD Changes

• Removed skipped workflow jobs from GitHub Actions
  • Removed: Performance Benchmarks (placeholder)
  • Removed: CodeQL Analysis (requires special setup)
  • Removed: Dependency Review (requires special setup)
  • Removed: OSSF Scorecard (requires special setup)
  • Removed: Snyk Security Scan (requires API token)
  • Reason: These are future enhancements, not needed for current releases

[0.9.2] - 2025-11-23

Fixed

• Version Detection: Fixed issues with version detection in built distributions
  • VersionCommand now properly reads package version from multiple possible paths
  • StateManager now uses actual package version instead of hardcoded '1.0.0'
  • getCurrentVersion() utility enhanced to try multiple paths for package.json
  • Added comprehensive tests to prevent future regressions
  • Fixed failing version-checker tests that expected semver format

[0.9.1] - 2025-11-23

Fixed

• Version Command: Fixed --version flag showing incorrect version (0.1.0 instead of actual version)
  • VersionCommand now tries multiple paths to find package.json in different environments
  • Works correctly in npm global installs, local development, and both ESM/CJS contexts
  • Validates package name before using version to ensure correct package.json is read

[0.9.0] - 2025-11-23

Added

• Modular Analytics Report Generation System: Complete refactoring of analytics into reusable, testable components
  • Exporter Factory: Factory pattern for creating format-specific exporters (Markdown/JSON)
  • Metrics Calculator: Pure functions for computing analytics metrics (PR merge rate, bus factor, commit velocity, etc.)
  • Export Orchestrator: Coordinates multi-format exports with comprehensive error handling and graceful degradation
  • Section-Based Report Generators: Specialized generators for activity, contributors, labels, health metrics, and recommendations
  • Status Helpers: Centralized logic for health status indicators with visual emoji indicators
• Enhanced Test Coverage: Added 56 new comprehensive tests (161 → 201 total tests)
  • 16 tests for Exporter Factory (100% coverage)
  • 26 tests for Metrics Calculator (100% coverage)
  • 14 tests for Export Orchestrator (83.58% coverage)
• Command Pattern for CLI: Extracted command handlers into dedicated classes
  • HelpCommand: Displays usage information and examples
  • VersionCommand: Shows package version from package.json
  • CheckCommand: Verifies GitHub CLI setup and authentication

Changed

• Reduced Code Complexity: Major reduction in large file sizes
  • analytics-processor.ts: 1,082 → 761 lines (-30%)
  • index.ts: 836 → 761 lines (-9%)
  • Total reduction: -396 lines (-21%) in main files
  • Created 14 new focused modules averaging ~54 lines each
• Improved Architecture: Separation of concerns and better maintainability
  • Presentation logic separated from business logic
  • Each module has a single, clear responsibility
  • Pure functions for easier testing and reasoning
  • Well-defined interfaces and type safety throughout
• Better Export System: Enhanced multi-format export capabilities
  • Supports partial export failures (e.g., markdown succeeds but JSON fails)
  • Provides detailed operation results and summary messages
  • Helper methods for result interpretation
  • Handles directory creation failures gracefully

Removed

• Dead Code Cleanup: Removed 3 unused files and 17 unused dependencies
  • Deleted src/analytics/type-specific-reports.ts (empty file)
  • Deleted src/types/filter.ts (unused filter functions)
  • Deleted tests/benchmarks/performance.bench.ts (unused benchmark)
  • Removed 17 npm packages: cli-progress, conf, @types/cli-progress, @types/handlebars, @semantic-release/github, conventional-changelog-conventionalcommits, husky, and others
  • Cleaned 4 unused type imports from src/analytics/report-generators/types.ts

Fixed

• Export Orchestrator Tests: Resolved 6 failing tests by properly mocking the executeExport method
• Status Helper Return Values: Fixed status helpers to return full text (e.g., "🟢 Excellent") instead of just emojis
• TypeScript Compilation: Resolved all type errors and unused import warnings
• Code Formatting: Applied Prettier formatting and ESLint fixes across entire codebase

Technical

• Design Patterns Implemented:
  • Factory Method: Creates objects without specifying exact class (Exporter Factory)
  • Strategy: Encapsulates export algorithms (Markdown vs JSON)
  • Orchestrator: Coordinates complex multi-step operations (Export Orchestrator)
  • Command: Encapsulates CLI operations (Help, Version, Check commands)
  • Composition: Main classes compose smaller, focused components
• Tools Used:
  • knip: Dead code detection and automatic removal
  • ts-prune: Unused export detection
  • vitest: Testing framework with enhanced test suite
  • TypeScript: Full type safety with strict null checks

Performance

• Reduced Bundle Size: Smaller, more focused modules improve tree-shaking
• Better Testability: Unit tests can now target specific modules in isolation
• Faster Development: Easier to locate and modify specific functionality

Migration Notes

For developers using the analytics API:

• The MarkdownReportGenerator now requires a packageVersion parameter
• Export operations should use the new ExportOrchestrator for multi-format support
• Metrics can be calculated independently using MetricsCalculator.calculateAll(report)
• Old export code will still work but consider migrating to the new orchestrator pattern

[0.8.0] - 2025-11-22

Added

• Enhanced Analytics Report Formatting: Improved visual presentation and data clarity
  • Dynamic contributor table that only shows columns with non-zero data
  • Summary stats section with key metrics for executive overview
  • Better handling of missing data with explanatory messages
• Improved Offline Mode Reliability: Fixed core analytics processor to properly use parsed markdown data
  • Active contributors now correctly calculated from PR authors (122 contributors vs 0)
  • Review coverage accurately reflects PR review status
  • All metrics now show meaningful values instead of zeros

Fixed

• Analytics Report Display Issues: Resolved confusing "0 commits" displays in contributor tables
• Version Display: Shows "n/a" instead of "unknown" when version cannot be determined
• PR Size Messaging: Enhanced "No data available" message with explanation "(PRs contain no diff metadata)"
• Formatting Issues: Fixed code style issues that were preventing clean commits

Changed

• Report Structure: Added summary statistics section at end of analytics reports
  • Total PRs processed and reviewed counts
  • Release count and active contributor metrics
  • Percentage of release-notes labels for quick insights

[0.7.4] - 2025-11-22

Added

• Initial Analytics Features: First implementation of analytics reporting capabilities
  • Basic contributor tables with commit counts
  • Simple PR review coverage metrics
  • Preliminary release tracking statistics
• Offline Analytics Mode: Analytics can now work with exported data instead of requiring GitHub API access
  • Parses exported markdown files (PRs, Issues, Releases)
  • Works with private repositories and offline environments
  • Basic implementation with limited metrics

Fixed

• Analytics Report Generation: Fixed issue where analytics reports were empty in some cases
  • Resolved problems with data parsing from exported files
  • Improved error handling for missing data scenarios

[0.7.2] - 2025-01-21

Added

• Automatic Update Notifications: CLI now checks for new versions and notifies users when updates are available
  • Non-blocking background check (once per day)
  • Clear visual notification with update command
  • Direct link to release changelog
  • Skipped during tests and for help/version flags
• Offline Analytics Mode: Analytics now work with exported data instead of requiring GitHub API access
  • Automatically enabled when generating analytics after exports
  • Parses exported markdown files (PRs, Issues, Releases)
  • Works with private repositories and offline environments
  • No more empty analytics reports!

Fixed

• Analytics Report Generation: Fixed issue where analytics reports were empty
  • Previous version tried to fetch from GitHub API even after export
  • Now uses offline mode by default to parse local exported files
  • Analytics now accurately reflect exported data

Technical

• Added update-notifier dependency for version checking
• Created version-checker utility module
• Integrated version check into CLI startup flow
• Created MarkdownParser class for parsing exported markdown files
• Updated AnalyticsProcessor to support offline mode with offline and exportedDataPath options
• Modified all analytics generation calls to use offline mode by default

[0.7.0] - 2025-11-21

Added

• Automatic Analytics Generation: Analytics reports are now automatically generated with every export operation
• Enhanced Data Extraction Limits: Increased data limits for better analysis of large repositories
  • PR/Issue lists: 300 → 1000 items
  • Release lists: 50 → 200 items
  • Exporters: 100 → 500 items
  • Comprehensive test coverage: Added extensive unit tests for analytics module with 92%+ coverage

Changed

• Analytics Integration: Removed --analytics flag as analytics are now automatically generated
• CLI Interface: Removed analytics option from interactive prompts
• Data Processing: Increased GitHub API limits for more comprehensive repository analysis

Technical

• Updated export logic to automatically generate analytics after each export
• Enhanced error handling for analytics generation
• Improved test coverage for all analytics modules

[0.6.3] - 2025-11-21

Fixed

• Version Conflict: Incremented version to resolve npm publishing conflict

[0.6.2] - 2025-11-21

Fixed

• CI/CD Pipeline: Enhanced npm publishing workflow with fallback mechanism and improved authentication

[0.6.1] - 2025-11-21

Fixed

• CI/CD Pipeline: Resolved npm authentication issues in GitHub Actions workflow

[0.6.0] - 2025-11-21

Added

• Enterprise-Grade Batch Processing: Export multiple repositories simultaneously with controlled concurrency
  • Process dozens or hundreds of repositories in a single command
  • Configurable parallelism (default: 3 repositories at a time)
  • JSON configuration file support for complex batch operations
  • Command-line options for quick batch exports
  • Comprehensive batch summary report with per-repository details
• Automatic Code Quality Enforcement: Pre-commit and pre-push hooks to ensure code is properly formatted and linted
  • Automatic Prettier formatting on commit
  • ESLint validation on commit
  • Pre-push validation to prevent unformatted code from being pushed
• Enhanced CI/CD Workflow: Streamlined GitHub Actions with reduced redundancy and improved efficiency

Changed

• Improved Developer Experience: More flexible linting configuration with reduced strictness
• Optimized CI Processes: Consolidated multiple CI jobs into more efficient workflows
• Code Quality Standards: Relaxed certain ESLint rules to reduce noise while maintaining code quality

Fixed

• Code Formatting Issues: Resolved all Prettier formatting warnings across the codebase
• Linting Configuration: Fixed ESLint configuration to properly include all project files

[0.5.0] - 2025-11-21

Added

• Documentation Updates: Added milestone status documentation
• Workflow Improvements: Enhanced CI/CD pipelines for better reliability

Changed

• Version Bump: Incremented version to v0.5.0 for continued development

[0.4.0] - 2025-11-21

Added

• Diff Mode (Incremental Exports): Revolutionary feature that exports only new/updated items since last run
  • New --diff and --incremental flags for incremental exports
  • State management system tracks last export timestamps
  • --force-full flag to override diff mode and force full export
  • Persistent state stored in ~/.ghextractor/state/exports.json
  • Automatic detection of first-time exports
  • State updates after successful exports for future incremental runs

Changed

• ExportOptions interface now includes optional diffMode parameter
• BaseExporter class enhanced with diff mode support methods
• CLI help updated with new diff mode flags and examples
• Export flow now integrates state management for incremental exports

Performance

• 80-95% reduction in API calls for subsequent exports with --diff
• 10x faster exports for large repositories using incremental mode
• Minimal rate limit impact on repeated exports

Technical

• New StateManager singleton for managing export states
• New types in src/types/state.ts for state management
• Full integration with existing exporter architecture
• Backward compatible - diff mode is opt-in

[0.3.0] - 2025-11-21

Fixed

• Complete Release Export: Fixed incomplete release exports that were missing release notes (body content)
• Changed from GitHub API endpoint to gh release view command for more reliable data fetching
• Releases now export with full content including complete release notes, assets, and author information
• Increased timeout from 10s to 30s and enabled automatic retries for better reliability with large repositories

Changed

• Updated release fetching mechanism in ReleaseExporter to use native GitHub CLI commands
• Improved error handling for release details fetching

[0.2.0] - 2025-11-20

Added

• Public Repository Support: Users can now document any public repository by entering the repository manually in owner/repo format (e.g., facebook/react)
• Collaboration Support: Automatically includes repositories where the authenticated user is a collaborator (not just owned repositories)
• New interactive option "📝 Enter a repository manually" in repository selection menu
• Repository validation and error handling for manually entered repositories
• getRepositoryFromString() function for validating and fetching public repository information
• promptRepositoryInput() function with format validation

Changed

• listUserRepositories() now uses GitHub API endpoint user/repos to include collaborator repositories (37 total repos instead of 34)
• selectRepository() return type changed to Promise<Repository | null> to support manual entry option
• Updated README with new features and usage examples for public repositories

Improved

• Better user experience for documenting open-source projects
• Enhanced repository discovery including collaboration repos
• Comprehensive documentation with use cases for public repository documentation

[0.1.0] - 2025-11-20

Added

• Initial release

  • GitHub CLI integration

  • Repository scanner

  • Interactive CLI interface

  • Data exporters (PRs, Issues, Commits, Branches, Releases)

  • Rate limiting with Bottleneck

  • Caching system with ETag support

  • Full backup mode

  • Markdown and JSON export formats

  • Custom template support

  • Configuration file support

  • Progress tracking and spinners

  • Error handling and retry logic

  • Comprehensive test suite

  • Initial release with basic functionality