codeowners-coverage 0.1.0__py3-none-any.whl

codeowners_coverage/__init__.py

@@ -0,0 +1,9 @@
+"""CODEOWNERS coverage checking tool."""
+
+__version__ = "0.1.0"
+
+from .checker import CoverageChecker
+from .config import Config
+from .matcher import CodeOwnersPatternMatcher
+
+__all__ = ["CoverageChecker", "Config", "CodeOwnersPatternMatcher"]

codeowners_coverage/__main__.py

@@ -0,0 +1,12 @@
+"""Entry point for codeowners-coverage CLI."""
+
+from .cli import cli
+
+
+def main() -> None:
+    """Main entry point."""
+    cli()
+
+
+if __name__ == "__main__":
+    main()

codeowners_coverage/checker.py

@@ -0,0 +1,157 @@
+"""Core coverage checking logic for CODEOWNERS."""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+from typing import Dict, List, Set
+
+import pathspec
+
+from .config import Config
+from .matcher import CodeOwnersPatternMatcher
+
+
+class CoverageChecker:
+    """Check CODEOWNERS coverage for repository files."""
+
+    def __init__(self, config: Config) -> None:
+        """
+        Initialize coverage checker.
+
+        Args:
+            config: Configuration object
+        """
+        self.config = config
+        self.matcher = CodeOwnersPatternMatcher(config.codeowners_path)
+        self.exclusions = pathspec.PathSpec.from_lines("gitignore", config.exclusions)
+
+    def get_repository_files(self) -> List[str]:
+        """
+        Get all files in repository using git ls-files.
+
+        Returns:
+            List of file paths relative to repository root
+        """
+        result = subprocess.run(
+            ["git", "ls-files"],
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+        files = result.stdout.strip().split("\n")
+        # Filter out empty strings
+        return [f for f in files if f]
+
+    def _load_baseline(self) -> Set[str]:
+        """
+        Load baseline file of allowed uncovered files.
+
+        Returns:
+            Set of file paths that are allowed to be uncovered
+        """
+        baseline_path = Path(self.config.baseline_path)
+
+        if not baseline_path.exists():
+            return set()
+
+        baseline_files = set()
+        with open(baseline_path) as f:
+            for line in f:
+                line = line.strip()
+                # Skip comments and empty lines
+                if line and not line.startswith("#"):
+                    baseline_files.add(line)
+
+        return baseline_files
+
+    def check_coverage(self, files: List[str] | None = None) -> Dict[str, object]:
+        """
+        Check which files lack CODEOWNERS coverage.
+
+        Args:
+            files: Optional list of specific files to check.
+                   If None, checks all repository files.
+
+        Returns:
+            Dictionary with coverage statistics:
+            {
+                "total_files": int,
+                "covered_files": int,
+                "uncovered_files": [list of uncovered file paths],
+                "baseline_files": [list of baseline file paths],
+                "coverage_percentage": float
+            }
+        """
+        if files is None:
+            files = self.get_repository_files()
+
+        # Filter excluded files
+        filtered_files = [f for f in files if not self.exclusions.match_file(f)]
+
+        # Check coverage
+        uncovered = [f for f in filtered_files if not self.matcher.matches(f)]
+
+        # Load baseline
+        baseline = self._load_baseline()
+
+        # Separate new uncovered files from baseline files
+        new_uncovered = [f for f in uncovered if f not in baseline]
+        baseline_files = [f for f in uncovered if f in baseline]
+
+        # Calculate coverage
+        total_files = len(filtered_files)
+        covered_files = total_files - len(uncovered)
+        coverage_percentage = (covered_files / total_files * 100) if total_files > 0 else 100.0
+
+        return {
+            "total_files": total_files,
+            "covered_files": covered_files,
+            "uncovered_files": new_uncovered,
+            "baseline_files": baseline_files,
+            "coverage_percentage": coverage_percentage,
+        }
+
+    def generate_baseline(self, files: List[str] | None = None) -> List[str]:
+        """
+        Generate a baseline of all currently uncovered files.
+
+        Args:
+            files: Optional list of specific files to check.
+                   If None, checks all repository files.
+
+        Returns:
+            List of uncovered file paths (sorted)
+        """
+        if files is None:
+            files = self.get_repository_files()
+
+        # Filter excluded files
+        filtered_files = [f for f in files if not self.exclusions.match_file(f)]
+
+        # Check coverage
+        uncovered = [f for f in filtered_files if not self.matcher.matches(f)]
+
+        return sorted(uncovered)
+
+    def write_baseline(self, baseline_files: List[str]) -> None:
+        """
+        Write baseline file.
+
+        Args:
+            baseline_files: List of file paths to write to baseline
+        """
+        baseline_path = Path(self.config.baseline_path)
+        baseline_path.parent.mkdir(parents=True, exist_ok=True)
+
+        with open(baseline_path, "w") as f:
+            f.write("# CODEOWNERS Coverage Baseline\n")
+            f.write("# Files lacking CODEOWNERS coverage (sorted)\n")
+            f.write("# Goal: Reduce this list to zero\n")
+            f.write("#\n")
+            f.write("# Generated by: codeowners-coverage baseline\n")
+            f.write("#\n")
+            f.write("\n")
+
+            for filepath in baseline_files:
+                f.write(f"{filepath}\n")

codeowners_coverage/cli.py

@@ -0,0 +1,130 @@
+"""CLI interface for codeowners-coverage."""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import List, Tuple
+
+import click
+
+from .checker import CoverageChecker
+from .config import Config
+
+
+@click.group()
+@click.version_option(version="0.1.0")
+def cli() -> None:
+    """CODEOWNERS coverage checking tool."""
+    pass
+
+
+@cli.command()
+@click.option("--json", "output_json", is_flag=True, help="Output JSON format")
+@click.option("--files", multiple=True, help="Specific files to check")
+@click.option("--config", default=".codeowners-config.yml", help="Config file path")
+def check(output_json: bool, files: Tuple[str, ...], config: str) -> None:
+    """
+    Check CODEOWNERS coverage.
+
+    Validates that all files in the repository have CODEOWNERS coverage.
+    Files in the baseline are allowed to be uncovered.
+    New uncovered files will cause the check to fail.
+    """
+    try:
+        cfg = Config.load(config)
+        checker = CoverageChecker(cfg)
+
+        file_list: List[str] | None = list(files) if files else None
+        result = checker.check_coverage(file_list)
+
+        if output_json:
+            click.echo(json.dumps(result, indent=2))
+        else:
+            _print_human_readable_result(result)
+
+        # Exit with error if there are new uncovered files
+        if result["uncovered_files"]:
+            sys.exit(1)
+
+        # Exit with code 2 if baseline can be reduced (positive signal)
+        # Check if any baseline files are now covered
+        baseline_set = set(result["baseline_files"])
+        current_uncovered = checker.generate_baseline(file_list)
+        current_uncovered_set = set(current_uncovered)
+
+        if len(baseline_set - current_uncovered_set) > 0:
+            if not output_json:
+                removable_files = sorted(baseline_set - current_uncovered_set)
+                click.echo(f"\n🎉 Great news! {len(removable_files)} files can be removed from the baseline:")
+                for f in removable_files[:10]:  # Show first 10
+                    click.echo(f"  - {f}")
+                if len(removable_files) > 10:
+                    click.echo(f"  ... and {len(removable_files) - 10} more")
+                click.echo("\nThese files now have CODEOWNERS coverage! Update the baseline:")
+                click.echo("  codeowners-coverage baseline")
+            sys.exit(2)
+
+    except FileNotFoundError as e:
+        click.echo(f"❌ Error: {e}", err=True)
+        sys.exit(1)
+    except Exception as e:
+        click.echo(f"❌ Unexpected error: {e}", err=True)
+        sys.exit(1)
+
+
+@cli.command()
+@click.option("--config", default=".codeowners-config.yml", help="Config file path")
+@click.option("--files", multiple=True, help="Specific files to check")
+def baseline(config: str, files: Tuple[str, ...]) -> None:
+    """
+    Generate or update baseline file of uncovered files.
+
+    Creates a baseline of all currently uncovered files. This allows
+    incremental improvement by preventing new uncovered files while
+    allowing existing gaps.
+    """
+    try:
+        cfg = Config.load(config)
+        checker = CoverageChecker(cfg)
+
+        file_list: List[str] | None = list(files) if files else None
+        baseline_files = checker.generate_baseline(file_list)
+
+        # Write baseline
+        checker.write_baseline(baseline_files)
+
+        click.echo(f"✅ Baseline written to {cfg.baseline_path}")
+        click.echo(f"📊 {len(baseline_files)} uncovered files in baseline")
+
+        if baseline_files:
+            click.echo(f"\n💡 Goal: Reduce this list to zero by adding CODEOWNERS coverage")
+
+    except FileNotFoundError as e:
+        click.echo(f"❌ Error: {e}", err=True)
+        sys.exit(1)
+    except Exception as e:
+        click.echo(f"❌ Unexpected error: {e}", err=True)
+        sys.exit(1)
+
+
+def _print_human_readable_result(result: dict) -> None:
+    """Print coverage check result in human-readable format."""
+    total = result["total_files"]
+    covered = result["covered_files"]
+    uncovered = result["uncovered_files"]
+    baseline = result["baseline_files"]
+    percentage = result["coverage_percentage"]
+
+    if uncovered:
+        click.echo("❌ CODEOWNERS Coverage Check Failed\n")
+        click.echo(f"The following {len(uncovered)} files lack CODEOWNERS coverage:")
+        for f in uncovered:
+            click.echo(f"  - {f}")
+        click.echo("\nPlease add these files to .github/CODEOWNERS with appropriate owners.")
+        click.echo("\n💡 Need help? Check the team mapping in the CODEOWNERS file")
+        click.echo(f"\n📊 Current status: {len(baseline)} files in baseline (unchanged)")
+    else:
+        click.echo(f"✅ CODEOWNERS Coverage: {percentage:.1f}% ({covered}/{total} files covered)")
+        if baseline:
+            click.echo(f"\n💡 Baseline: {len(baseline)} files still need coverage")

codeowners_coverage/config.py

@@ -0,0 +1,77 @@
+"""Configuration loading for codeowners-coverage."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import List
+
+import yaml
+
+
+@dataclass
+class Config:
+    """Configuration for codeowners-coverage."""
+
+    codeowners_path: str = ".github/CODEOWNERS"
+    baseline_path: str = ".github/codeowners-coverage-baseline.txt"
+    exclusions: List[str] = field(default_factory=list)
+
+    @classmethod
+    def load(cls, config_path: str = ".codeowners-config.yml") -> Config:
+        """
+        Load configuration from YAML file.
+
+        Args:
+            config_path: Path to the configuration file
+
+        Returns:
+            Config object with loaded settings
+        """
+        config_file = Path(config_path)
+
+        if not config_file.exists():
+            # Return default configuration with default exclusions
+            return cls(exclusions=cls.default_exclusions())
+
+        with open(config_file) as f:
+            data = yaml.safe_load(f) or {}
+
+        return cls(
+            codeowners_path=data.get("codeowners_path", cls.codeowners_path),
+            baseline_path=data.get("baseline_path", cls.baseline_path),
+            exclusions=data.get("exclusions", cls.default_exclusions()),
+        )
+
+    @staticmethod
+    def default_exclusions() -> List[str]:
+        """
+        Default exclusion patterns.
+
+        These are common build artifacts and dependency directories
+        that typically don't need CODEOWNERS coverage.
+
+        Returns:
+            List of default exclusion patterns
+        """
+        return [
+            # Python artifacts
+            "**/__pycache__/**",
+            "**/*.pyc",
+            "**/*.pyo",
+            "**/*.egg-info/**",
+            ".venv/**",
+            ".tox/**",
+            ".pytest_cache/**",
+            ".mypy_cache/**",
+            # JavaScript artifacts
+            "node_modules/**",
+            "dist/**",
+            "build/**",
+            "**/coverage/**",
+            # Version control
+            ".git/**",
+            # Build outputs
+            "htmlcov/**",
+            ".coverage",
+        ]

codeowners_coverage/matcher.py

@@ -0,0 +1,88 @@
+"""Pattern matching for CODEOWNERS files using pathspec."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import List
+
+import pathspec
+
+
+class CodeOwnersPatternMatcher:
+    """Match file paths against CODEOWNERS patterns."""
+
+    def __init__(self, codeowners_path: str) -> None:
+        """
+        Load and parse CODEOWNERS file.
+
+        Args:
+            codeowners_path: Path to the CODEOWNERS file
+        """
+        self.codeowners_path = codeowners_path
+        self.patterns = self._parse_codeowners(codeowners_path)
+        # Use gitignore for gitignore-style patterns
+        self.spec = pathspec.PathSpec.from_lines("gitignore", self.patterns)
+
+    def _parse_codeowners(self, path: str) -> List[str]:
+        """
+        Extract patterns from CODEOWNERS file.
+
+        The CODEOWNERS format is:
+        pattern @owner1 @owner2
+
+        We only care about the patterns, not the owners.
+
+        Args:
+            path: Path to CODEOWNERS file
+
+        Returns:
+            List of patterns extracted from the file
+        """
+        patterns = []
+        codeowners_file = Path(path)
+
+        if not codeowners_file.exists():
+            raise FileNotFoundError(f"CODEOWNERS file not found: {path}")
+
+        with open(codeowners_file) as f:
+            for line in f:
+                line = line.strip()
+                # Skip comments and empty lines
+                if not line or line.startswith("#"):
+                    continue
+
+                # Pattern is first token, owners follow
+                parts = line.split()
+                if parts:
+                    pattern = parts[0]
+                    patterns.append(pattern)
+
+        return patterns
+
+    def matches(self, filepath: str) -> bool:
+        """
+        Check if filepath is covered by any CODEOWNERS pattern.
+
+        Args:
+            filepath: File path to check (relative to repo root)
+
+        Returns:
+            True if the file matches any CODEOWNERS pattern
+        """
+        return self.spec.match_file(filepath)
+
+    def get_matching_pattern(self, filepath: str) -> str | None:
+        """
+        Get the first pattern that matches the given filepath.
+
+        Args:
+            filepath: File path to check (relative to repo root)
+
+        Returns:
+            The matching pattern, or None if no match
+        """
+        for pattern in self.patterns:
+            pattern_spec = pathspec.PathSpec.from_lines("gitignore", [pattern])
+            if pattern_spec.match_file(filepath):
+                return pattern
+        return None

codeowners_coverage-0.1.0.dist-info/METADATA

@@ -0,0 +1,158 @@
+Metadata-Version: 2.4
+Name: codeowners-coverage
+Version: 0.1.0
+Summary: Measure and enforce CODEOWNERS coverage
+Author-email: Sentry Team <hello@sentry.io>
+License: Apache-2.0
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: pathspec>=0.12.0
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: click>=8.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+
+# CODEOWNERS Coverage
+
+A tool to measure and enforce CODEOWNERS coverage in your repository.
+
+## Installation
+
+```bash
+pip install codeowners-coverage
+```
+
+## Usage
+
+### Check coverage
+
+```bash
+codeowners-coverage check
+```
+
+### Generate baseline
+
+```bash
+codeowners-coverage baseline
+```
+
+### Configuration
+
+Create a `.codeowners-config.yml` file in your repository root:
+
+```yaml
+# Path to CODEOWNERS file
+codeowners_path: ".github/CODEOWNERS"
+
+# Path to baseline file
+baseline_path: ".github/codeowners-coverage-baseline.txt"
+
+# File patterns to exclude from coverage checking
+exclusions:
+  - "**/__pycache__/**"
+  - "**/*.pyc"
+  - "node_modules/**"
+  - "dist/**"
+  - ".venv/**"
+```
+
+## GitHub Actions Integration
+
+Add a workflow to check CODEOWNERS coverage on pull requests:
+
+```yaml
+name: CODEOWNERS Coverage
+on: [pull_request]
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - run: pip install codeowners-coverage
+      - run: codeowners-coverage check
+```
+
+## Features
+
+- **Pattern Matching**: Supports all CODEOWNERS patterns (wildcards, globstars, etc.)
+- **Baseline Support**: Track progress incrementally with a baseline allowlist
+- **Configurable**: Customize exclusions and paths via YAML config
+- **Fast**: Uses `pathspec` library for efficient pattern matching
+- **GitHub Actions Ready**: Easy integration with CI/CD pipelines
+
+## Development
+
+### Using just (recommended)
+
+This project includes a `justfile` with common development commands:
+
+```bash
+# Install package in development mode
+just install
+
+# Run all tests
+just test
+
+# Run tests with coverage report
+just test-cov
+
+# Run type checking
+just typecheck
+
+# Run linting
+just lint
+
+# Run all checks (tests, typecheck, lint)
+just check
+
+# Clean build artifacts
+just clean
+
+# Build the package
+just build
+
+# Or build with uv (faster)
+just build-uv
+
+# Format code
+just format
+
+# Publish to Test PyPI
+just publish-test
+
+# Publish to production PyPI
+just publish
+
+# Full release workflow
+just release
+```
+
+### Manual commands
+
+```bash
+# Install in development mode
+uv pip install -e ".[dev]"
+
+# Run tests
+pytest tests/ -v
+
+# Run with coverage
+pytest tests/ -v --cov
+
+# Build package
+python -m build
+
+# Publish to PyPI
+twine upload dist/*
+```
+
+## License
+
+Apache-2.0

codeowners_coverage-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+codeowners_coverage/__init__.py,sha256=-wSyZqa_AYCSXRvyuHoVavpR6HevUoUcGgyONbAg36Q,244
+codeowners_coverage/__main__.py,sha256=dAxC9oNG2vWzxip2dYJL_rl0G8jqUuPu-5SMPEEplJ4,169
+codeowners_coverage/checker.py,sha256=AILAiKbSGzr7j8xCJGc-QNKQ7849e8JinfA5w-XbUrE,4969
+codeowners_coverage/cli.py,sha256=FBf9iaiUgiuj5-6BYC9k5ruYXQV9EQc8otVPBo_8o-c,4852
+codeowners_coverage/config.py,sha256=DIlBOjE5R_bNTI0uorSCVlJZte8iUycAWkXyzH04RZ4,2143
+codeowners_coverage/matcher.py,sha256=vj-TkLAqI0HUaaiNMAVcKMz6ZDmOeihil_zr9UKtGNo,2569
+codeowners_coverage-0.1.0.dist-info/METADATA,sha256=0GNMBoSNMe1-y5v34G8urDeWkbEH2kEZTsHCE2AEGWc,2885
+codeowners_coverage-0.1.0.dist-info/WHEEL,sha256=YCfwYGOYMi5Jhw2fU4yNgwErybb2IX5PEwBKV4ZbdBo,91
+codeowners_coverage-0.1.0.dist-info/entry_points.txt,sha256=luzL4lUNPBAX-alRgh9EkEXpESZ0hWdnyWhvWUaLza4,74
+codeowners_coverage-0.1.0.dist-info/top_level.txt,sha256=7i-oxjSacWaiBnAPUmHtqBVCouuW65HKMgbO4yDayeg,20
+codeowners_coverage-0.1.0.dist-info/RECORD,,

codeowners_coverage-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

codeowners_coverage-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+codeowners-coverage = codeowners_coverage.__main__:main

codeowners_coverage-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+codeowners_coverage