preen 0.1.0__py3-none-any.whl

preen/__init__.py

@@ -0,0 +1,25 @@
+"""Top-level package for preen.
+
+This module exposes a small public API for programmatic use.  At this stage the
+implementation is minimal, providing only the `sync` function used by the
+command‑line interface.  Future versions will add additional helpers for
+checking and releasing packages.
+"""
+
+from importlib.metadata import version as _get_version  # type: ignore
+
+from .syncer import sync_project
+
+__all__ = ["__version__", "sync_project"]
+
+
+def __getattr__(name: str):
+    """Lazily expose the package version.
+
+    The version is looked up using importlib.metadata when accessed.  This
+    avoids importing pkg_resources at runtime and follows the recommended
+    pattern for modern packaging.
+    """
+    if name == "__version__":
+        return _get_version(__name__)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

preen/__main__.py

@@ -0,0 +1,6 @@
+"""Allow preen to be run as a module."""
+
+from .cli import run
+
+if __name__ == "__main__":
+    run()

preen/checks/__init__.py

@@ -0,0 +1,10 @@
+"""Check framework for preen.
+
+This module provides the base infrastructure for running checks and
+managing issues/fixes.
+"""
+
+from .base import Check, CheckResult, Issue, Fix, Severity
+from .runner import run_checks
+
+__all__ = ["Check", "CheckResult", "Issue", "Fix", "Severity", "run_checks"]

preen/checks/base.py

@@ -0,0 +1,148 @@
+"""Base classes for the check framework."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+from typing import Callable
+
+
+class Severity(Enum):
+    """Severity levels for issues."""
+
+    ERROR = "error"
+    WARNING = "warning"
+    INFO = "info"
+
+
+class Impact(Enum):
+    """Impact classification for release workflow decision making."""
+
+    CRITICAL = "critical"  # Must fix - blocks release (security, broken builds)
+    IMPORTANT = "important"  # Should fix but can override (style, deprecations)
+    INFORMATIONAL = "info"  # Nice to fix (suggestions, optimizations)
+
+
+@dataclass
+class Fix:
+    """Represents a proposed fix for an issue."""
+
+    description: str
+    diff: str
+    apply: Callable[[], None]
+
+    def preview(self) -> str:
+        """Return a preview of the fix as a diff."""
+        return self.diff
+
+
+@dataclass
+class Issue:
+    """Represents an issue found by a check."""
+
+    check: str
+    severity: Severity
+    description: str
+    file: Path | None = None
+    line: int | None = None
+    proposed_fix: Fix | None = None
+    impact: Impact = Impact.IMPORTANT  # Default to important (can override)
+    explanation: str = ""  # Why this issue matters
+    override_question: str = ""  # Custom question for override prompt
+
+    def __str__(self) -> str:
+        location = ""
+        if self.file:
+            location = f" in {self.file}"
+            if self.line:
+                location += f":{self.line}"
+        return f"[{self.severity.value}] {self.check}: {self.description}{location}"
+
+    def get_impact_symbol(self) -> str:
+        """Get emoji symbol for impact level."""
+        symbols = {
+            Impact.CRITICAL: "🚫",
+            Impact.IMPORTANT: "⚠️",
+            Impact.INFORMATIONAL: "ℹ️",
+        }
+        return symbols[self.impact]
+
+    def is_blocking(self) -> bool:
+        """Return True if this issue should block release by default."""
+        return self.impact == Impact.CRITICAL
+
+    def can_override(self) -> bool:
+        """Return True if this issue can be overridden in interactive mode."""
+        return self.impact in [Impact.IMPORTANT, Impact.INFORMATIONAL]
+
+
+@dataclass
+class CheckResult:
+    """Result of running a check."""
+
+    check: str
+    passed: bool
+    issues: list[Issue] = field(default_factory=list)
+    duration: float = 0.0
+
+    @property
+    def has_errors(self) -> bool:
+        """Return True if any issues are errors."""
+        return any(issue.severity == Severity.ERROR for issue in self.issues)
+
+    @property
+    def has_warnings(self) -> bool:
+        """Return True if any issues are warnings."""
+        return any(issue.severity == Severity.WARNING for issue in self.issues)
+
+    @property
+    def has_blocking_issues(self) -> bool:
+        """Return True if any issues are blocking (critical impact)."""
+        return any(issue.is_blocking() for issue in self.issues)
+
+    @property
+    def has_overridable_issues(self) -> bool:
+        """Return True if any issues can be overridden."""
+        return any(issue.can_override() for issue in self.issues)
+
+    def get_issues_by_impact(self, impact: Impact) -> list[Issue]:
+        """Get all issues with a specific impact level."""
+        return [issue for issue in self.issues if issue.impact == impact]
+
+
+class Check(ABC):
+    """Abstract base class for all checks."""
+
+    def __init__(self, project_dir: Path):
+        """Initialize the check.
+
+        Args:
+            project_dir: Path to the project directory.
+        """
+        self.project_dir = project_dir
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Return the name of this check."""
+        pass
+
+    @property
+    def description(self) -> str:
+        """Return a description of what this check does."""
+        return ""
+
+    @abstractmethod
+    def run(self) -> CheckResult:
+        """Run the check and return the result.
+
+        Returns:
+            CheckResult containing any issues found.
+        """
+        pass
+
+    def can_fix(self) -> bool:
+        """Return True if this check can automatically fix issues."""
+        return False

preen/checks/ci_matrix.py

@@ -0,0 +1,154 @@
+"""CI matrix validation check."""
+
+from __future__ import annotations
+
+import yaml
+from pathlib import Path
+
+from ..config import PreenConfig
+from ..syncer import _read_pyproject
+from .base import Check, CheckResult, Issue, Fix, Severity
+
+
+class CIMatrixCheck(Check):
+    """Check if CI matrix covers all declared Python versions."""
+
+    @property
+    def name(self) -> str:
+        return "ci-matrix"
+
+    @property
+    def description(self) -> str:
+        return "Check if CI matrix tests all declared Python versions"
+
+    def run(self) -> CheckResult:
+        """Check CI matrix against declared Python versions."""
+        issues = []
+
+        # Load project configuration
+        try:
+            config = PreenConfig.from_pyproject(self.project_dir)
+            pyproject = _read_pyproject(self.project_dir / "pyproject.toml")
+            declared_versions = config.get_ci_python_versions(pyproject)
+        except Exception as e:
+            return CheckResult(
+                check=self.name,
+                passed=False,
+                issues=[
+                    Issue(
+                        check=self.name,
+                        severity=Severity.ERROR,
+                        description=f"Failed to read project metadata: {e}",
+                    )
+                ],
+            )
+
+        # Check if CI workflow exists
+        ci_path = self.project_dir / ".github" / "workflows" / "ci.yml"
+        if not ci_path.exists():
+            issues.append(
+                Issue(
+                    check=self.name,
+                    severity=Severity.WARNING,
+                    description="No CI workflow found at .github/workflows/ci.yml",
+                    proposed_fix=Fix(
+                        description="Generate CI workflow from pyproject.toml",
+                        diff="Run: preen sync --only ci",
+                        apply=self._fix_ci_workflow,
+                    ),
+                )
+            )
+            return CheckResult(
+                check=self.name,
+                passed=False,
+                issues=issues,
+            )
+
+        # Parse CI workflow
+        try:
+            with ci_path.open("r", encoding="utf-8") as f:
+                ci_content = yaml.safe_load(f)
+        except Exception as e:
+            issues.append(
+                Issue(
+                    check=self.name,
+                    severity=Severity.ERROR,
+                    description=f"Failed to parse CI workflow: {e}",
+                )
+            )
+            return CheckResult(
+                check=self.name,
+                passed=False,
+                issues=issues,
+            )
+
+        # Extract Python versions from CI matrix
+        ci_versions = set()
+        try:
+            jobs = ci_content.get("jobs", {})
+            test_job = jobs.get("test", {})
+            strategy = test_job.get("strategy", {})
+            matrix = strategy.get("matrix", {})
+            python_versions = matrix.get("python-version", [])
+
+            # Handle both list format and string format
+            if isinstance(python_versions, list):
+                ci_versions.update(python_versions)
+            elif isinstance(python_versions, str):
+                ci_versions.add(python_versions)
+        except Exception:
+            pass
+
+        # Compare versions
+        declared_set = set(declared_versions)
+        missing_in_ci = declared_set - ci_versions
+        extra_in_ci = ci_versions - declared_set
+
+        if missing_in_ci:
+            missing_versions = ", ".join(sorted(missing_in_ci))
+            issues.append(
+                Issue(
+                    check=self.name,
+                    severity=Severity.WARNING,
+                    description=f"CI matrix missing Python versions: {missing_versions}",
+                    file=Path(".github/workflows/ci.yml"),
+                    proposed_fix=Fix(
+                        description="Update CI matrix to include all declared Python versions",
+                        diff=f"Add Python versions to CI matrix: {missing_versions}",
+                        apply=self._fix_ci_workflow,
+                    ),
+                )
+            )
+
+        if extra_in_ci and not missing_in_ci:
+            # Only warn about extra versions if we're not missing any
+            extra_versions = ", ".join(sorted(extra_in_ci))
+            issues.append(
+                Issue(
+                    check=self.name,
+                    severity=Severity.INFO,
+                    description=f"CI matrix has extra Python versions not declared in classifiers: {extra_versions}",
+                    file=Path(".github/workflows/ci.yml"),
+                )
+            )
+
+        return CheckResult(
+            check=self.name,
+            passed=len([issue for issue in issues if issue.severity != Severity.INFO])
+            == 0,
+            issues=issues,
+        )
+
+    def can_fix(self) -> bool:
+        return True
+
+    def _fix_ci_workflow(self) -> None:
+        """Regenerate CI workflow to fix matrix issues."""
+        from ..syncer import sync_project
+
+        sync_project(
+            self.project_dir,
+            quiet=True,
+            check=False,
+            targets={"ci"},
+        )

preen/checks/citation.py

@@ -0,0 +1,107 @@
+"""Citation file check."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ..syncer import sync_project
+from .base import Check, CheckResult, Issue, Fix, Severity
+
+
+class CitationCheck(Check):
+    """Check if CITATION.cff is in sync with pyproject.toml."""
+
+    @property
+    def name(self) -> str:
+        return "citation"
+
+    @property
+    def description(self) -> str:
+        return "Check if CITATION.cff is synced with pyproject.toml"
+
+    def run(self) -> CheckResult:
+        """Check if citation file needs updating."""
+        issues = []
+
+        # Run sync in check mode for citation only
+        try:
+            result = sync_project(
+                self.project_dir,
+                quiet=True,
+                check=True,
+                targets={"citation"},
+            )
+        except SystemExit:
+            # sync_project exits with 1 if files would change
+            result = sync_project(
+                self.project_dir,
+                quiet=True,
+                check=False,
+                targets={"citation"},
+            )
+
+            # Get the diff
+            citation_path = self.project_dir / "CITATION.cff"
+            old_content = ""
+            if citation_path.exists():
+                old_content = citation_path.read_text()
+
+            new_content = result.get("updated", {}).get("CITATION.cff", "")
+
+            def apply_fix():
+                sync_project(
+                    self.project_dir,
+                    quiet=True,
+                    check=False,
+                    targets={"citation"},
+                )
+
+            issues.append(
+                Issue(
+                    check=self.name,
+                    severity=Severity.WARNING,
+                    description="CITATION.cff is out of sync with pyproject.toml",
+                    file=Path("CITATION.cff"),
+                    proposed_fix=Fix(
+                        description="Regenerate CITATION.cff from pyproject.toml",
+                        diff=self._generate_diff(old_content, new_content),
+                        apply=apply_fix,
+                    ),
+                )
+            )
+
+        return CheckResult(
+            check=self.name,
+            passed=len(issues) == 0,
+            issues=issues,
+        )
+
+    def can_fix(self) -> bool:
+        return True
+
+    def _generate_diff(self, old: str, new: str) -> str:
+        """Generate a simple diff between old and new content."""
+        if not old:
+            return f"Create new file:\n{new}"
+
+        old_lines = old.split("\n")
+        new_lines = new.split("\n")
+
+        diff_lines = []
+        for i, (old_line, new_line) in enumerate(zip(old_lines, new_lines)):
+            if old_line != new_line:
+                diff_lines.append(f"@@ Line {i + 1} @@")
+                diff_lines.append(f"- {old_line}")
+                diff_lines.append(f"+ {new_line}")
+
+        # Handle different lengths
+        if len(new_lines) > len(old_lines):
+            diff_lines.append("@@ Added lines @@")
+            for line in new_lines[len(old_lines) :]:
+                diff_lines.append(f"+ {line}")
+        elif len(old_lines) > len(new_lines):
+            diff_lines.append("@@ Removed lines @@")
+            for line in old_lines[len(new_lines) :]:
+                diff_lines.append(f"- {line}")
+
+        return "\n".join(diff_lines) if diff_lines else "No changes"

preen/checks/codespell.py

@@ -0,0 +1,216 @@
+"""Codespell spell checking check."""
+
+from __future__ import annotations
+
+import re
+import subprocess
+from pathlib import Path
+# from typing import List  # No longer needed with Python 3.12+
+
+from .base import Check, CheckResult, Issue, Fix, Severity, Impact
+
+
+class CodespellCheck(Check):
+    """Check for spelling errors in documentation and comments using codespell."""
+
+    @property
+    def name(self) -> str:
+        return "codespell"
+
+    @property
+    def description(self) -> str:
+        return "Check spelling in documentation and comments with codespell"
+
+    def _parse_codespell_output(self, output: str) -> list[Issue]:
+        """Parse codespell output and convert to Issue objects."""
+        issues = []
+        
+        # Pattern to match codespell output format:
+        # path/to/file.py:line: word ==> suggestion
+        pattern = r'^(.+?):(\d+): (.+) ==> (.+)$'
+        
+        for line in output.strip().split('\n'):
+            if not line.strip():
+                continue
+                
+            match = re.match(pattern, line)
+            if match:
+                file_path, line_num, misspelled, suggestion = match.groups()
+                
+                # Convert absolute path to relative
+                try:
+                    rel_path = Path(file_path).relative_to(self.project_dir)
+                except ValueError:
+                    # If path is not under project_dir, use as-is
+                    rel_path = Path(file_path)
+                
+                # Determine impact based on file location
+                impact = self._get_impact_for_file(rel_path)
+                
+                issues.append(Issue(
+                    check=self.name,
+                    severity=Severity.WARNING,  # Spelling errors are usually warnings
+                    description=f"'{misspelled}' should be '{suggestion}'",
+                    file=rel_path,
+                    line=int(line_num),
+                    impact=impact,
+                    explanation=f"Spelling error detected. '{misspelled}' should be spelled '{suggestion}'. Good spelling improves documentation quality and professionalism.",
+                ))
+        
+        return issues
+
+    def _get_impact_for_file(self, file_path: Path) -> Impact:
+        """Determine impact level based on file location."""
+        file_str = str(file_path).lower()
+        
+        # Critical for user-facing documentation
+        if any(critical in file_str for critical in ['readme', 'changelog', 'license', 'contributing']):
+            return Impact.CRITICAL
+            
+        # Important for documentation and code
+        if file_path.suffix in ['.md', '.rst', '.py', '.txt'] or 'docs/' in file_str:
+            return Impact.IMPORTANT
+            
+        # Informational for other files
+        return Impact.INFORMATIONAL
+
+    def _get_codespell_command(self) -> list[str]:
+        """Build codespell command with appropriate options."""
+        cmd = ["codespell"]
+        
+        # Add skip patterns for common directories/files that don't need spell checking
+        skip_patterns = [
+            ".git",
+            "__pycache__", 
+            "*.pyc",
+            "*.egg-info",
+            ".pytest_cache",
+            "node_modules",
+            ".mypy_cache",
+            "dist",
+            "build",
+            ".venv",
+            "venv"
+        ]
+        
+        cmd.extend(["--skip", ",".join(skip_patterns)])
+        
+        # Focus on text files and code
+        # Don't spell check binary files, images, etc.
+        cmd.extend([
+            "--check-filenames",  # Also check file names
+            "--quiet-level", "2",  # Suppress binary file warnings
+        ])
+        
+        # Add project directory as target
+        cmd.append(str(self.project_dir))
+        
+        return cmd
+
+    def run(self) -> CheckResult:
+        """Run codespell check."""
+        issues = []
+        
+        # Check if codespell is available
+        try:
+            subprocess.run(
+                ["codespell", "--version"],
+                capture_output=True,
+                check=True,
+                cwd=self.project_dir,
+            )
+        except (subprocess.SubprocessError, FileNotFoundError):
+            return CheckResult(
+                check=self.name,
+                passed=False,
+                issues=[
+                    Issue(
+                        check=self.name,
+                        severity=Severity.ERROR,
+                        description="codespell is not installed. Install with: pip install codespell",
+                        impact=Impact.CRITICAL,
+                        explanation="codespell is required for spell checking documentation and comments",
+                    )
+                ],
+            )
+
+        # Run codespell 
+        cmd = self._get_codespell_command()
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            cwd=self.project_dir,
+        )
+        
+        # codespell returns:
+        # 0: No misspellings found
+        # >0: Misspellings found (exit code represents number of files with issues)
+        
+        match result.returncode:
+            case 0:
+                # No misspellings found - issues list stays empty
+                pass
+            case code if code > 0 and (result.stdout or result.stderr):
+                # Misspellings found - check both stdout and stderr
+                output = result.stdout if result.stdout else result.stderr
+                if output:
+                    issues = self._parse_codespell_output(output)
+                    
+                    # Add a single fix for all spelling issues if any exist
+                    if issues:
+                        fix = self._get_fix_for_issues(issues)
+                        # Attach the fix to the first issue (consolidated approach)
+                        issues[0].proposed_fix = fix
+            case code if code > 0:
+                # Non-zero exit code but no output - likely an error
+                error_msg = result.stderr.strip() or f"codespell exited with code {result.returncode}"
+                issues.append(Issue(
+                    check=self.name,
+                    severity=Severity.WARNING,
+                    description=f"codespell error: {error_msg}",
+                    impact=Impact.INFORMATIONAL,
+                    explanation="codespell had trouble analyzing some files",
+                ))
+
+        return CheckResult(
+            check=self.name,
+            passed=len(issues) == 0,
+            issues=issues,
+        )
+
+    def can_fix(self) -> bool:
+        return True  # Codespell can auto-fix spelling errors
+
+    def _get_fix_for_issues(self, issues: list[Issue]) -> Fix:
+        """Create a Fix object for codespell auto-correction."""
+        def apply_codespell_fix():
+            """Apply codespell automatic fixes."""
+            cmd = self._get_codespell_command()
+            # Add write flag to actually apply fixes
+            cmd.insert(-1, "--write-changes")  # Insert before directory argument
+            
+            subprocess.run(
+                cmd,
+                cwd=self.project_dir,
+                check=False,  # Don't raise on exit code 1 (fixes applied)
+            )
+
+        # Get diff preview by running with --diff flag
+        cmd = self._get_codespell_command() 
+        cmd.insert(-1, "--diff")  # Insert before directory argument
+        
+        diff_result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            cwd=self.project_dir,
+        )
+        
+        diff_output = diff_result.stdout if diff_result.stdout else "No diff available"
+        
+        return Fix(
+            description=f"Apply codespell automatic fixes for {len(issues)} spelling error(s)",
+            diff=diff_output,
+            apply=apply_codespell_fix,
+        )