beaconled 0.5.0

Your delivery compass for empowered product builders. A comprehensive toolkit for analyzing git repository statistics and development metrics.

Beacon Delivery Compass

Your delivery compass for empowered product builders. Transform engineering activity into executive-ready insights and data-driven product delivery decisions.

Quick Install

Beacon requires Python 3.10+ and Git 2.23+. We recommend installing in a virtual environment.

# Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install from PyPI
pip install beaconled

# Verify installation
beaconled --version

Quick Start

Analyze a git repository:

beaconled /path/to/repo

Generate a weekly team report:

beaconled --since 1w --until "now"

Usage Examples

Basic Analysis

# Analyze changes in the last 3 days
beaconled --since "3d"

# Date range analysis with timezone support
beaconled --since "2025-01-01" --until "2025-01-31"

# Extended analysis with team, quality, and risk metrics
beaconled --since "2w" --format extended

# Generate visual heatmaps of commit activity (requires matplotlib)
beaconled --since "1w" --format heatmap

# Disable emoji icons for plain text output
beaconled --since "1w" --no-emoji

Extended Format Features

The extended format (--format extended) includes comprehensive analytics:

• Time-Based Analytics: Velocity trends, activity heatmaps, peak periods
• Team Collaboration: Co-authorship patterns, ownership distribution
• Code Quality: Churn metrics, complexity trends, large changes
• Risk Assessment: Risk indicators, hotspot detection, stability metrics
• File Analysis:
  • Largest Changes: Identify files with most modifications (additions + deletions)
  • Frequently Changed: Track most active files during the analysis period
  • Lifecycle Tracking: Monitor file operations (added/modified/deleted/renamed)

Example:

=== TIME-BASED ANALYTICS ===
• Velocity: 5.2 commits/day
• Peak hours: 10:00, 14:00
• Bus factor: 3

=== TEAM COLLABORATION ===
• Core contributors: alice, bob
• Knowledge distribution: Balanced

=== CODE QUALITY ===
• Churn rate: 12.5%
• Complexity trend: Decreasing

=== RISK ASSESSMENT ===
• Risk score: 4/10
• Hotspots: src/auth/, src/api/

=== FILE ANALYSIS ===
• Largest Changes (Top 5):
  - src/core/engine.py: 1,245 lines changed
  - tests/test_engine.py: 856 lines changed
  - src/api/endpoints.py: 732 lines changed
  - src/utils/helpers.py: 521 lines changed
  - docs/api_reference.md: 487 lines changed

• Frequently Changed:
  - src/utils/helpers.py: 12 changes
  - src/config/settings.py: 8 changes
  - tests/conftest.py: 7 changes
  - src/api/middleware/auth.py: 6 changes
  - src/core/models.py: 5 changes

• File Lifecycle (this period):
  - Added: 12 files
  - Modified: 45 files
  - Deleted: 5 files
  - Renamed: 3 files

Date Formats

Beacon supports flexible date parsing with UTC timezone handling:

# Relative dates
beaconled --since "1d"   # 1 day ago
beaconled --since "2w"   # 2 weeks ago
beaconled --since "3m"   # 3 months ago

# Absolute dates (UTC)
beaconled --since "2025-01-15"
beaconled --since "2025-01-15 14:30"

For more examples, see Basic Usage and Advanced Usage guides.

Sample Outputs

Repository Analysis

beaconled /path/to/my-project

Repository Analysis: /path/to/my-project
Analysis Period: Last 30 commits

=== COMMIT SUMMARY ===
Total Commits: 30
Contributors: 4
Date Range: 2025-01-15 to 2025-01-23

=== COMMIT DETAILS ===
[2025-01-23 14:32] feat: Add user authentication module (John Doe)
  Impact: HIGH - 8 files changed, 245 insertions, 12 deletions
  Components: auth/, middleware/, tests/

[2025-01-23 10:15] fix: Resolve database connection timeout (Jane Smith)
  Impact: MEDIUM - 3 files changed, 28 insertions, 15 deletions
  Components: database/, config/

=== FILE CHANGE METRICS ===
Most Active Files:
  src/auth/login.py: 12 changes
  config/database.py: 8 changes
  tests/test_auth.py: 6 changes

=== IMPACT ASSESSMENT ===
High Impact Commits: 8 (27%)
Medium Impact Commits: 15 (50%)
Low Impact Commits: 7 (23%)

Weekly Team Report

beaconled --since "1w" --format extended

🗓️ Analysis Period: 2025-01-16 to 2025-01-23 (7 days)

commits Total commits: 23
files changed Total files changed: 156
lines added Total lines added: 2,847
lines deleted Total lines deleted: 1,234
net change Net change: 1,613

🚀 === TEAM OVERVIEW ===
👥 Total Contributors: 4
Total Commits: 23
Average Commits/Day: 2.9
Active Days: 6/7

🔍 === CONTRIBUTOR BREAKDOWN ===
John Doe <[e-mail]>: 9 commits (39%)
  - High Impact: 3 commits
  - Medium Impact: 4 commits
  - Low Impact: 2 commits
  - Most Active: Monday, Wednesday

Jane Smith <[e-mail]>: 7 commits (30%)
  - High Impact: 2 commits
  - Medium Impact: 3 commits
  - Low Impact: 2 commits
  - Most Active: Tuesday, Friday

Bob Wilson <[e-mail]>: 7 commits (30%)
  - High Impact: 1 commits
  - Medium Impact: 4 commits
  - Low Impact: 2 commits
  - Most Active: Wednesday, Thursday

🔥 === COMPONENT ACTIVITY ===
Most Changed Components:
  frontend/: 8 commits, 1,234 lines
  backend/api/: 6 commits, 892 lines
  tests/: 5 commits, 567 lines
  docs/: 4 commits, 154 lines

=== TIME-BASED ANALYTICS ===
• Velocity: 5.2 commits/day
• Peak hours: 10:00, 14:00
• Bus factor: 3

=== TEAM COLLABORATION ===
• Core contributors: alice, bob
• Knowledge distribution: Balanced

=== CODE QUALITY ===
• Churn rate: 12.5%
• Complexity trend: Decreasing

=== RISK ASSESSMENT ===
• Risk score: 4/10
• Hotspots: src/auth/, src/api/

=== FILE ANALYSIS ===
• Largest Changes (Top 5):
  - src/core/engine.py: 1,245 lines changed
  - tests/test_engine.py: 856 lines changed
  - src/api/endpoints.py: 732 lines changed
  - src/utils/helpers.py: 521 lines changed
  - docs/api_reference.md: 487 lines changed

• Frequently Changed:
  - src/utils/helpers.py: 12 changes
  - src/config/settings.py: 8 changes
  - tests/conftest.py: 7 changes
  - src/api/middleware/auth.py: 6 changes
  - src/core/models.py: 5 changes

• File Lifecycle (this period):
  - Added: 12 files
  - Modified: 45 files
  - Deleted: 5 files
  - Renamed: 3 files

Features

• Executive-Ready Reports: Transform engineering metrics into business insights for leadership decisions
• Team Health Monitoring: Data-driven team management with contribution analysis and workload distribution
• Product Delivery Analytics: Comprehensive insights into development patterns, release readiness, and technical health
• Multi-Stakeholder Value: One platform serving executives, engineering managers, and technical leads
• Flexible Output Formats: Choose from standard, extended, JSON, and heatmap formats to fit your workflow needs
• Visual Analytics: Generate interactive heatmaps showing commit patterns and author activity over time
• Emoji-Enhanced Visual Scanning: Optional emoji icons for better visual parsing of output (configurable via --no-emoji)
• Reliable Git Integration: Built on GitPython for robust and secure repository operations
• Rich Terminal Output: Colorized and well-formatted output powered by rich

Documentation

• Installation Guide - Detailed setup instructions and troubleshooting
• Basic Usage - Standard repository analysis
• Advanced Usage - Executive reporting, team health, and technical debt analysis
• Integration Guide - CI/CD pipelines and git hooks
• API Reference - Detailed API documentation
• System Architecture - High-level system design

Development & Contribution

We welcome contributions! For details on how to contribute, please see our Contribution Guidelines.

Project Roadmap

Our development priorities and planned improvements are tracked in the Enhancement Plan. This document provides visibility into:

• Upcoming features and improvements
• Current technical debt
• Performance optimization plans
• Testing and quality assurance goals

Code Quality

Beacon is built with a strong focus on code quality and maintainability. We use pre-commit hooks to ensure consistent code quality across the project.

Pre-commit Configuration

We use a unified pre-commit configuration (.pre-commit-config.yaml) that works for both development and production environments:

# Setup pre-commit hooks (unified configuration for dev and prod)
make dev-setup

Note: Both dev-setup and prod-setup now use the same unified configuration for consistency.

Key Quality Tools

• Type Safety: Full static type checking with mypy
• Code Style: Consistent code formatting with Ruff
• Linting: Code quality enforcement with Ruff
• Documentation: Comprehensive docstrings and API documentation

Development Workflow

1. Use make dev-setup to install the pre-commit hooks
2. Before pushing changes, ensure all checks pass (they will run automatically on commit)
3. Use git commit --no-verify sparingly when needed

Manual Checks

# Run type checking
mypy --ignore-missing-imports src/beaconled

# Run all code quality checks
make lint

Testing

For contributors, run the test suite with:

python run_tests.py

For detailed testing options, see our Testing Guide.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Roadmap

Check out our Roadmap to see what we're working on and what's coming next!