complete refactoring to make a python package

[vuillaut]

🚀 Transform contrib-checker into a Full-Featured Python Library

Summary

This PR transforms contrib-checker from a simple GitHub Action into a comprehensive, installable Python library while maintaining 100% backward compatibility. The tool now supports multiple usage patterns: Python library, CLI tool, GitHub Action, and GitLab CI integration.

🎯 Key Achievements

✅ Complete Library Transformation

• Installable Package: Available via pip install contrib-checker
• Command-line Tool: New contrib-checker CLI for local usage
• Maintained Compatibility: All existing GitHub Action and GitLab CI functionality preserved
• Platform Independence: Extensible architecture for future CI platforms

✅ Comprehensive Testing

• 71 passing tests covering all functionality
• Unit tests: Core logic validation
• Integration tests: End-to-end workflows
• Platform-specific tests: GitHub and GitLab integration
• CLI tests: Command-line interface validation

📦 New Package Structure

contrib_checker/
├── __init__.py          # Package exports and public API
├── core.py              # Platform-independent contributor checking logic
├── github.py            # GitHub-specific wrapper with PR commenting
├── gitlab.py            # GitLab-specific wrapper with MR commenting
└── cli.py               # Command-line interface implementation

🛠️ Installation & Usage

Python Package Installation

pip install contrib-checker

Command-line Usage

# Basic checking
contrib-checker

# Advanced options
contrib-checker --mode fail --ignore-emails bot@example.com --from-sha abc123 --to-sha def456

Library Usage

from contrib_checker import ContributorChecker, GitHubContributorChecker, GitLabContributorChecker

# Core usage
checker = ContributorChecker(repo_path=Path('.'), config={'mode': 'warn'})
success, results = checker.check_all_contributors()

# Platform-specific usage
github_checker = GitHubContributorChecker()
gitlab_checker = GitLabContributorChecker()

🔧 Architecture Improvements

Eliminated Code Duplication

• Before: Separate implementations for GitHub (check_contributors.py) and GitLab
• After: Shared core logic in contrib_checker.core.ContributorChecker
• Result: ~300 lines of duplicated code eliminated

Smart Wrapper Pattern

All platform scripts now use a smart wrapper pattern:

try:
    from contrib_checker.github import main  # Use installed package
except ImportError:
    # Fallback to local implementation for development

Clean API Design

• Platform-independent core: ContributorChecker class
• Platform-specific wrappers: GitHubContributorChecker, GitLabContributorChecker
• Consistent interface: All methods return (success: bool, results: dict)

📋 Files Changed

New Package Files

• contrib_checker/__init__.py - Package exports and public API
• contrib_checker/core.py - Core contributor checking logic (refactored from existing code)
• contrib_checker/github.py - GitHub integration with PR commenting
• contrib_checker/gitlab.py - GitLab integration with MR commenting
• contrib_checker/cli.py - Command-line interface implementation

Distribution & Configuration

• pyproject.toml - Modern Python packaging configuration
• setup.py - Backward compatibility setup script
• MANIFEST.in - Include additional files in distribution
• requirements.txt - Updated dependencies

Updated Action & CI

• action.yml - Updated to install package instead of copying files
• .github/workflows/pytest.yml - Added comprehensive test automation

Enhanced Documentation

• README.md - Complete rewrite with library usage examples
• LIBRARY_SUMMARY.md - Detailed transformation documentation
• CONTRIBUTING.md - Development guidelines
• examples/library_usage.py - Comprehensive usage examples

Comprehensive Test Suite

• tests/test_core.py - Core functionality tests
• tests/test_github.py - GitHub integration tests
• tests/test_gitlab.py - GitLab integration tests
• tests/test_cli.py - Command-line interface tests
• tests/test_integration.py - End-to-end workflow tests
• tests/conftest.py - Shared test fixtures

🔄 Backward Compatibility

Zero Breaking Changes

• ✅ Existing GitHub Action workflows continue to work unchanged
• ✅ GitLab CI configurations require no modifications
• ✅ All configuration options preserved (mode, ignore_emails, ignore_logins)
• ✅ Comment posting behavior identical

Preserved Files (now smart wrappers)

• check_contributors.py - GitHub Action script (now wrapper)
• Original functionality available as fallback during development

🧪 Testing Coverage

Test Statistics

• 71 total tests - All passing ✅
• 8 core tests - Platform-independent logic
• 13 CLI tests - Command-line interface
• 16 GitHub tests - GitHub Action integration
• 16 GitLab tests - GitLab CI integration
• 18 integration tests - End-to-end workflows

Test Categories

1. Unit Tests: Core parsing, normalization, filtering logic
2. Integration Tests: Full workflow simulation with mocked git/API calls
3. Platform Tests: GitHub PR and GitLab MR comment posting
4. CLI Tests: Argument parsing, error handling, execution paths
5. Error Handling: Malformed files, network errors, git failures

🔍 Key Features

Enhanced Bot Filtering

• Built-in filtering for common bots (dependabot[bot], github-actions[bot])
• Configurable email and login ignore lists
• Intelligent pattern matching

Robust Git Integration

• Uses git log --use-mailmap for canonical contributor names
• Supports commit range checking (--from-sha to --to-sha)
• Handles missing repositories gracefully

Flexible Configuration

• Command-line arguments
• Environment variables
• Configuration files (.github/contrib-metadata-check.yml)
• Programmatic configuration via Python API

Comprehensive Metadata Support

• CITATION.cff parsing with full schema support
• codemeta.json parsing for multiple contributor types
• Intelligent name normalization and matching