nhl-scrabble 0.0.16

NHL Roster Scrabble Score Analyzer - Calculate Scrabble scores for NHL player names

NHL Scrabble Score Analyzer

A Python application that fetches current NHL roster data and calculates "Scrabble scores" for player names based on standard Scrabble letter values. Generate comprehensive reports showing team, division, and conference standings complete with playoff brackets!

Features

• 🏒 Live NHL Data - Fetches current roster data from the official NHL API
• 🌐 Web Interface - FastAPI-powered server with interactive dashboard
  • Interactive dashboard with real-time analysis
  • Chart.js visualizations and graphs
  • REST API with OpenAPI documentation
  • Mobile-friendly responsive design (WCAG 2.1 AA)
• 📊 Comprehensive Reports - Conference/division standings, playoff brackets, team scores, statistics
• 📈 Progress Tracking - Real-time progress bars for long operations
• 🎯 Flexible Output - Text, JSON, or HTML format
• 🎨 Colorized Logging - Color-coded log levels with TTY detection and NO_COLOR support
• 🌍 Internationalization - 12 locales supported (EN, FR, SV, RU, FI, CS, DE, IT, SK, LV) with gettext translations
• 🧪 Comprehensive Testing - >90% code coverage with 170+ unit/integration tests
  • Playwright-based E2E testing (40+ browser tests)
  • Visual regression testing across browsers (Chromium, Firefox, WebKit)
  • Performance and load testing with benchmarks
  • WCAG 2.1 AA accessibility compliance testing
  • Automated cross-browser QA in CI/CD
• ⚡ Lightning Fast - UV support for 10-100x faster installation
• 🔒 Production-Ready - Security headers, CORS, caching, deployment guides

Quality Assurance

This project includes comprehensive automated QA testing beyond unit/integration tests:

• Framework: Playwright with Page Object Model architecture
• Test Coverage: 40+ end-to-end tests across 4 categories
• Browser Support: Automated testing on Chromium, Firefox, and WebKit
• Test Types:
  • Functional - User workflows, interactions, navigation (15 tests)
  • Visual Regression - Screenshot comparison across browsers (10 tests)
  • Performance - Page load times, API response benchmarks (8 tests)
  • Accessibility - WCAG 2.1 AA compliance validation (7 tests)
• Documentation: See qa/README.md for detailed QA framework documentation
• CI Integration: Automated runs on PRs, commits to main, and nightly schedule (2 AM UTC)

Run QA tests locally:

make qa-install      # Install QA dependencies (Playwright, browsers)
make qa-test         # Run all QA tests (~5-7 minutes)
make qa-functional   # Run functional tests only
make qa-visual       # Run visual regression tests
make qa-performance  # Run performance tests
make qa-accessibility # Run accessibility tests

CI/CD Workflow: .github/workflows/qa-automation.yml

• Cross-browser matrix testing (parallel execution)
• Artifact uploads (reports, screenshots, visual diffs, performance metrics)
• PR comments with test summaries and failure details
• Manual workflow dispatch with test suite and browser selection

Screenshots

Web Interface

The NHL Scrabble web interface provides a modern, interactive experience:

• Main Dashboard - Clean, responsive design with one-click analysis
• Analysis Results - Sortable tables, standings, playoff brackets, statistics
• Interactive Features - Chart.js visualizations, export (JSON/CSV/PDF), table sorting
• API Documentation - Swagger UI (/docs) and ReDoc (/redoc)

CLI Output

Text Output (Default)

🏒 NHL SCRABBLE SCORE ANALYSIS 🏒

TOP 20 PLAYERS BY SCRABBLE SCORE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
1. Alexander Ovechkin (WSH)    45 points
2. Zdeno Chara (BOS)           42 points
...

JSON Output - Machine-readable format for integrations

HTML Output - Fully styled browser report with embedded CSS

Installation

From Source

# Clone the repository
git clone https://github.com/bdperkin/nhl-scrabble.git
cd nhl-scrabble

# Install in development mode
make init

# Or manually with pip
pip install -e ".[dev]"

Using Docker

Run the analyzer using Docker without installing Python:

# Pull from GitHub Container Registry
docker pull ghcr.io/bdperkin/nhl-scrabble:latest

# Run analysis
docker run --rm ghcr.io/bdperkin/nhl-scrabble:latest analyze

# Save output to a file
docker run --rm -v $(pwd):/output \
  ghcr.io/bdperkin/nhl-scrabble:latest \
  analyze --output /output/report.txt

# Use with environment variables
docker run --rm \
  -e NHL_SCRABBLE_VERBOSE=true \
  -e NHL_SCRABBLE_TOP_PLAYERS=50 \
  ghcr.io/bdperkin/nhl-scrabble:latest analyze

Available tags:

• latest - Latest stable release from main branch
• 2.1.0 - Specific version (replace with desired version)
• 2.1, 2 - Major.minor and major version tags

Supported platforms: linux/amd64, linux/arm64

Requirements

• Supported: Python 3.12, 3.13, 3.14
• Experimental: Python 3.15-dev (CI testing only, may have issues)
• Dependencies: requests, click, pydantic, python-dotenv, rich, fastapi, uvicorn, jinja2
• Note: UV acceleration is automatic when using tox (via tox-uv plugin)

Quick Start

Run the analysis with default settings:

nhl-scrabble analyze

Or use the Python module directly:

python -m nhl_scrabble analyze

For detailed usage, see the CLI Tutorial.

Usage

CLI Commands

# Basic analysis
nhl-scrabble analyze

# Verbose output with colorized logging
nhl-scrabble analyze -v

# JSON output to file
nhl-scrabble analyze -f json -o report.json

# HTML output
nhl-scrabble analyze -f html -o report.html

# Customize display
nhl-scrabble analyze --top-players 50 --top-team-players 10

Web Server

# Start web server (default port 8000)
nhl-scrabble serve

# Custom host and port with auto-reload
nhl-scrabble serve --host 0.0.0.0 --port 5000 --reload

Visit http://localhost:8000/docs for interactive API documentation.

Interactive Dashboard

# Launch terminal dashboard
nhl-scrabble dashboard

# Filter by division/conference
nhl-scrabble dashboard --divisions Atlantic --conferences Eastern

# Static snapshot (no live updates)
nhl-scrabble dashboard --static

Complete Usage Documentation:

• CLI Tutorial - Step-by-step CLI guide
• CLI Reference - All commands and options
• Configuration Guide - Environment variables and settings

How It Works

The analyzer uses standard English Scrabble letter point values (A=1, Z=10, etc.) to score player names. It fetches live NHL data, calculates scores, aggregates by team/division/conference, and generates comprehensive reports with playoff brackets.

Learn More:

• Why Scrabble Scoring? - The concept explained
• How Scrabble Scoring Works - Detailed scoring logic
• Architecture Overview - System design
• NHL API Strategy - API integration approach

Development

Quick Start

# Clone and setup
git clone https://github.com/bdperkin/nhl-scrabble.git
cd nhl-scrabble
make init
source .venv/bin/activate

# View all available commands (57 targets)
make help

Testing

# Run all tests
make test

# Run with coverage
make test-cov

# Multi-version testing with tox
make tox              # Test Python 3.12, 3.13, 3.14
make tox-parallel     # Faster parallel execution

Code Quality

# Format and lint
make ruff-format
make ruff-check

# Type checking
make mypy

# Run all quality checks
make quality

# Full validation (format + quality + tests)
make check

Pre-commit Hooks

The project uses 67 comprehensive pre-commit hooks for automatic code quality validation:

# Install hooks (one-time)
pre-commit install

# Run all hooks manually
pre-commit run --all-files

# Update hook versions
pre-commit autoupdate

Complete Development Documentation:

• CONTRIBUTING.md - Development guidelines and workflow
• Makefile Reference - All 57 Makefile targets
• Testing Guide - Test execution and configuration
• UV Package Manager - 10-100x faster installation

Project Structure

nhl-scrabble/
├── src/nhl_scrabble/          # Main package
│   ├── api/                   # NHL API client
│   ├── scoring/               # Scrabble scoring logic
│   ├── models/                # Data models (Pydantic)
│   ├── processors/            # Business logic
│   ├── reports/               # Report generators
│   ├── cli.py                 # CLI interface (Click)
│   └── config.py              # Configuration management
├── tests/                     # Test suite (170+ tests)
│   ├── unit/                  # Unit tests
│   └── integration/           # Integration tests
├── docs/                      # Documentation (Diátaxis framework)
├── pyproject.toml             # Project & UV configuration
└── uv.lock                    # Dependency lock file (1,957 lines)

See Architecture Overview for detailed system design.

Documentation

Online Documentation: https://bdperkin.github.io/nhl-scrabble/

Documentation follows the Diátaxis framework:

• Tutorials - Step-by-step lessons for beginners
  • Getting Started
  • Understanding Output
  • First Contribution
• How-to Guides - Practical solutions to specific tasks
  • Installation Variations
  • Run Tests
  • Add Report Type
  • Use UV Package Manager
• Reference - Technical specifications
  • CLI Reference
  • Configuration
  • Makefile Reference
  • Environment Variables
  • Project Stats
• Explanation - Design philosophy and concepts
  • Why Scrabble Scoring?
  • Architecture Overview
  • NHL API Strategy

Community:

• CONTRIBUTING.md - Development guidelines
• SECURITY.md - Security policy
• SUPPORT.md - Getting help
• CHANGELOG.md - Version history
• CLAUDE.md - Project overview for Claude Code

Contributing

Contributions are welcome! See CONTRIBUTING.md for detailed guidelines.

Quick Overview:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes with tests
4. Run quality checks (make check)
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

Security

This project takes security seriously with comprehensive automated scanning:

• Dependabot - Automated dependency updates and security alerts
• pip-audit - CI vulnerability scanning
• CodeQL - Weekly security scans
• Pre-commit hooks - 67 comprehensive quality and security checks

Reporting Vulnerabilities: See SECURITY.md for responsible disclosure guidelines. Do not report security vulnerabilities through public GitHub issues.

Support

• Documentation: https://bdperkin.github.io/nhl-scrabble/
• Issues: Report bugs or request features via GitHub Issues
• Discussions: Ask questions in GitHub Discussions

See SUPPORT.md for detailed support information.

License

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

All runtime dependencies use permissive licenses compatible with MIT (Apache, BSD, ISC, etc.). See LICENSES.md for the complete list.

To verify license compliance:

tox -e licenses

Project Statistics

• Test Coverage: 49.93% overall, >90% on core modules
• Tests: 170+ tests (100% passing)
• Modules: 15 core modules
• Makefile Targets: 57 documented targets
• Pre-commit Hooks: 67 comprehensive quality checks
• CI/CD: GitHub Actions on Python 3.12, 3.13, 3.14 (required), 3.15-dev (experimental)

See Project Stats for complete metrics.

Acknowledgments

• NHL API for providing roster data
• Scrabble is a trademark of Hasbro, Inc.

Changelog

See CHANGELOG.md for version history.

---

Made with ❤️ for hockey and word games