pycmdcheck 0.1.0__py3-none-any.whl

pycmdcheck/__init__.py

@@ -0,0 +1,104 @@
+"""pycmdcheck - Python package quality checker.
+
+A Python equivalent of R's `R CMD check` for validating Python packages.
+
+Example usage:
+
+    from pycmdcheck import check
+
+    # Check current directory
+    report = check(".")
+
+    # Check specific package
+    report = check("/path/to/package")
+
+    # Check with options
+    report = check(
+        ".",
+        checks=["metadata", "tests"],
+        skip=["linting"],
+    )
+
+    # Check results
+    if report.passed:
+        print("All checks passed!")
+    else:
+        for result in report.results:
+            print(f"{result.status}: {result.name} - {result.message}")
+"""
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _get_version
+from typing import Any
+
+from pycmdcheck.results import CheckResult, CheckStatus, Report
+from pycmdcheck.runner import run_checks
+
+try:
+    __version__ = _get_version("pycmdcheck")
+except PackageNotFoundError:
+    __version__ = "0.0.0"
+
+__all__ = [
+    "check",
+    "run_checks",
+    "CheckResult",
+    "CheckStatus",
+    "Report",
+    "__version__",
+]
+
+
+def check(
+    path: str = ".",
+    *,
+    checks: list[str] | None = None,
+    skip: list[str] | None = None,
+    config: dict[str, Any] | None = None,
+    parallel: bool = True,
+    fail_fast: bool = False,
+) -> Report:
+    """Check a Python package for quality issues.
+
+    This is the main entry point for programmatic use of pycmdcheck.
+    It discovers available checks via entry points, loads configuration
+    from pyproject.toml, and runs the enabled checks.
+
+    Args:
+        path: Path to the package directory. Defaults to current directory.
+        checks: List of check names to run. If None, runs all enabled checks
+            from configuration. Available checks: build, dependencies, docs,
+            formatting, imports, license, linting, metadata, py_typed,
+            structure, tests, typing, version.
+        skip: List of check names to skip, even if enabled in configuration.
+        config: Pre-loaded configuration dictionary. If None, configuration
+            is loaded from the package's pyproject.toml.
+        parallel: Whether to run checks in parallel. Defaults to True.
+        fail_fast: Whether to stop after the first ERROR. Defaults to False.
+
+    Returns:
+        A Report object containing all check results. Use report.passed to
+        check if all checks passed, or iterate report.results for details.
+
+    Examples:
+        Basic usage - check current directory:
+
+        >>> from pycmdcheck import check  # doctest: +SKIP
+        >>> report = check(".")
+        >>> report.passed
+        True
+
+        Run only specific checks:
+
+        >>> report = check(".", checks=["metadata", "tests"])  # doctest: +SKIP
+    """
+    report = run_checks(
+        package_path=path,
+        checks=checks,
+        skip=skip,
+        config=config,
+        parallel=parallel,
+        fail_fast=fail_fast,
+    )
+
+    return report

pycmdcheck/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for python -m pycmdcheck."""
+
+from pycmdcheck.cli import main
+
+if __name__ == "__main__":
+    main()

pycmdcheck/ast_cache.py

@@ -0,0 +1,45 @@
+"""Thread-safe AST parse cache for pycmdcheck.
+
+Multiple checks parse the same Python files independently. This module
+provides a shared cache so each file is parsed at most once per run.
+"""
+
+from __future__ import annotations
+
+import ast
+import logging
+import threading
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+_cache: dict[Path, ast.Module | None] = {}
+_lock = threading.Lock()
+
+
+def parse_file(path: Path) -> ast.Module | None:
+    """Parse a Python file, returning cached result if available.
+
+    Returns None if the file cannot be read or parsed.
+    """
+    resolved = path.resolve()
+    with _lock:
+        if resolved in _cache:
+            return _cache[resolved]
+
+    try:
+        with open(resolved, encoding="utf-8") as f:
+            tree = ast.parse(f.read(), filename=str(resolved))
+    except (SyntaxError, UnicodeDecodeError, OSError) as exc:
+        logger.debug("Failed to parse %s: %s", resolved, exc)
+        tree = None
+
+    with _lock:
+        _cache[resolved] = tree
+    return tree
+
+
+def clear_cache() -> None:
+    """Clear the AST cache (call between test runs)."""
+    with _lock:
+        _cache.clear()

pycmdcheck/checks/__init__.py

@@ -0,0 +1 @@
+"""Built-in checks for pycmdcheck."""

pycmdcheck/checks/base.py

@@ -0,0 +1,143 @@
+"""Base check protocol and abstract class."""
+
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import Any, Protocol, runtime_checkable
+
+from pycmdcheck.results import CheckResult
+
+
+@runtime_checkable
+class Check(Protocol):
+    """Protocol defining the interface for all checks.
+
+    This protocol defines what a check must implement to be usable
+    by pycmdcheck. Checks can be implemented by either:
+
+    1. Inheriting from BaseCheck (recommended for most cases)
+    2. Implementing this Protocol directly (for structural subtyping)
+
+    Attributes:
+        name: Unique identifier for the check (e.g., "metadata", "tests").
+        description: Human-readable description of what the check does.
+
+    Examples:
+        Implement a check using the protocol directly:
+
+        >>> class MyCheck:
+        ...     name = "my_check"
+        ...     description = "My custom check"
+        ...
+        ...     def run(self, package_path, config):
+        ...         return CheckResult(
+        ...             name=self.name,
+        ...             status=CheckStatus.OK,
+        ...             message="Check passed",
+        ...         )
+        >>> isinstance(MyCheck(), Check)
+        True
+    """
+
+    name: str
+    description: str
+
+    def run(self, package_path: Path, config: dict[str, Any]) -> CheckResult:
+        """Execute the check and return result.
+
+        Args:
+            package_path: Path to the package directory to check.
+            config: Configuration dictionary for this check, loaded from
+                pyproject.toml [tool.pycmdcheck.checks.<name>] section.
+
+        Returns:
+            A CheckResult containing the status, message, and optional details.
+        """
+        ...
+
+
+class BaseCheck(ABC):
+    """Abstract base class for implementing checks.
+
+    This is the recommended way to implement custom checks. Subclasses
+    must override the `name`, `description` attributes and implement
+    the `run` method.
+
+    Attributes:
+        name: Unique identifier for the check. Override in subclass.
+        description: Human-readable description. Override in subclass.
+
+    Examples:
+        Create a custom check:
+
+        >>> from pycmdcheck.checks.base import BaseCheck
+        >>> from pycmdcheck.results import CheckResult, CheckStatus
+        >>>
+        >>> class CopyrightCheck(BaseCheck):
+        ...     name = "copyright"
+        ...     description = "Check for copyright headers"
+        ...
+        ...     def run(self, package_path, config):
+        ...         # Check logic here
+        ...         return CheckResult(
+        ...             name=self.name,
+        ...             status=CheckStatus.OK,
+        ...             message="All files have copyright headers",
+        ...         )
+
+        Register via entry points in pyproject.toml:
+
+        ```toml
+        [project.entry-points."pycmdcheck.checks"]
+        copyright = "my_package.checks:CopyrightCheck"
+        ```
+    """
+
+    name: str = "base"
+    description: str = "Base check"
+
+    @abstractmethod
+    def run(self, package_path: Path, config: dict[str, Any]) -> CheckResult:
+        """Execute the check and return result.
+
+        Subclasses must implement this method to perform the actual check.
+
+        Args:
+            package_path: Path to the package directory to check. This is
+                always an absolute, resolved path.
+            config: Configuration dictionary for this check. Contains any
+                options specified in pyproject.toml under
+                [tool.pycmdcheck.checks.<name>]. Common keys include
+                "enabled" (bool) and check-specific options.
+
+        Returns:
+            A CheckResult with:
+            - name: Should match self.name
+            - status: One of CheckStatus values (OK, WARNING, ERROR, etc.)
+            - message: Brief description of the result
+            - details: Optional list of specific issues found
+
+        Examples:
+            >>> def run(self, package_path, config):
+            ...     issues = self._find_issues(package_path)
+            ...     if issues:
+            ...         return CheckResult(
+            ...             name=self.name,
+            ...             status=CheckStatus.WARNING,
+            ...             message=f"Found {len(issues)} issues",
+            ...             details=issues,
+            ...         )
+            ...     return CheckResult(
+            ...         name=self.name,
+            ...         status=CheckStatus.OK,
+            ...         message="No issues found",
+            ...     )
+        """
+        ...
+
+    def __repr__(self) -> str:
+        """Return string representation of the check.
+
+        Returns:
+            A string in the format "<ClassName: check_name>".
+        """
+        return f"<{self.__class__.__name__}: {self.name}>"

pycmdcheck/checks/build.py

@@ -0,0 +1,101 @@
+"""Build check — verifies the package can be built."""
+
+import importlib.util
+import tempfile
+from pathlib import Path
+from typing import Any
+
+from pycmdcheck.checks.base import BaseCheck
+from pycmdcheck.constants import DEFAULT_TIMEOUT, MAX_DETAIL_LINES
+from pycmdcheck.results import CheckResult, CheckStatus
+from pycmdcheck.subprocess_runner import run_tool, sanitize_args
+
+
+class BuildCheck(BaseCheck):
+    """Check that the package can be built into a wheel."""
+
+    name = "build"
+    description = "Verify package builds successfully"
+
+    def run(self, package_path: Path, config: dict[str, Any]) -> CheckResult:
+        """Attempt to build the package."""
+        # Check if build module is available
+        if importlib.util.find_spec("build") is None:
+            return CheckResult(
+                name=self.name,
+                status=CheckStatus.SKIPPED,
+                message="'build' module not installed",
+                details=["Install it: pip install build"],
+            )
+
+        # Check pyproject.toml exists
+        if not (package_path / "pyproject.toml").exists():
+            return CheckResult(
+                name=self.name,
+                status=CheckStatus.ERROR,
+                message="No pyproject.toml found",
+                details=["Cannot build without pyproject.toml"],
+            )
+
+        timeout = config.get("timeout", DEFAULT_TIMEOUT)
+        args = sanitize_args(config.get("args", []))
+
+        with tempfile.TemporaryDirectory() as tmpdir:
+            cmd = ["python", "-m", "build", "--outdir", tmpdir, *args]
+            result = run_tool(cmd, cwd=package_path, timeout=timeout)
+
+            if result.timed_out:
+                return CheckResult(
+                    name=self.name,
+                    status=CheckStatus.ERROR,
+                    message="Build timed out",
+                    details=[f"Build took longer than {timeout} seconds"],
+                )
+
+            if result.error is not None:
+                return CheckResult(
+                    name=self.name,
+                    status=CheckStatus.ERROR,
+                    message="Failed to run build",
+                    details=[result.error],
+                )
+
+            if result.success:
+                # Verify wheel was created
+                wheels = list(Path(tmpdir).glob("*.whl"))
+                sdists = list(Path(tmpdir).glob("*.tar.gz"))
+                details = []
+                if wheels:
+                    details.append(f"Built wheel: {wheels[0].name}")
+                if sdists:
+                    details.append(f"Built sdist: {sdists[0].name}")
+
+                if wheels or sdists:
+                    return CheckResult(
+                        name=self.name,
+                        status=CheckStatus.OK,
+                        message="Package built successfully",
+                        details=details,
+                    )
+
+                # Build command succeeded but produced no artifacts
+                return CheckResult(
+                    name=self.name,
+                    status=CheckStatus.WARNING,
+                    message="Build succeeded but no artifacts found",
+                    details=["No .whl or .tar.gz files were produced"],
+                )
+
+            # Build failed (non-zero exit code)
+            output_lines = result.output_lines()
+            details = (
+                output_lines[-MAX_DETAIL_LINES:]
+                if output_lines
+                else ["No output captured"]
+            )
+            return CheckResult(
+                name=self.name,
+                status=CheckStatus.ERROR,
+                message="Build failed",
+                details=details,
+            )

pycmdcheck/checks/changelog.py

@@ -0,0 +1,101 @@
+"""Changelog file check.
+
+Verifies that a package has a changelog or news file documenting
+changes across releases.
+"""
+
+from pathlib import Path
+from typing import Any
+
+from pycmdcheck.checks.base import BaseCheck
+from pycmdcheck.constants import MIN_CHANGELOG_LENGTH
+from pycmdcheck.results import CheckResult, CheckStatus
+
+
+class ChangelogCheck(BaseCheck):
+    """Check for changelog or news file.
+
+    Searches for common changelog file names and verifies
+    the file has meaningful content.
+
+    Attributes:
+        name: The check identifier ("changelog").
+        description: Human-readable description of this check.
+    """
+
+    name = "changelog"
+    description = "Check for changelog or news file"
+
+    CHANGELOG_FILENAMES = [
+        "CHANGELOG.md",
+        "CHANGELOG.rst",
+        "CHANGELOG.txt",
+        "CHANGELOG",
+        "CHANGES.md",
+        "CHANGES.rst",
+        "CHANGES.txt",
+        "CHANGES",
+        "NEWS.md",
+        "NEWS.rst",
+        "NEWS.txt",
+        "NEWS",
+        "HISTORY.md",
+        "HISTORY.rst",
+        "HISTORY.txt",
+        "HISTORY",
+    ]
+
+    def run(self, package_path: Path, config: dict[str, Any]) -> CheckResult:
+        """Check for changelog file presence and content.
+
+        Args:
+            package_path: Path to the package directory to check.
+            config: Configuration dictionary for this check.
+
+        Returns:
+            A CheckResult with:
+
+            - OK status if a changelog with content is found
+            - WARNING status if changelog exists but is too short
+            - NOTE status if no changelog found
+        """
+        details: list[str] = []
+
+        for filename in self.CHANGELOG_FILENAMES:
+            candidate = package_path / filename
+            if candidate.exists():
+                details.append(f"Found: {candidate.name}")
+                try:
+                    content = candidate.read_text(encoding="utf-8")
+                    if len(content.strip()) < MIN_CHANGELOG_LENGTH:
+                        details.append("Changelog appears empty or incomplete")
+                        return CheckResult(
+                            name=self.name,
+                            status=CheckStatus.WARNING,
+                            message="Changelog file is too short",
+                            details=details,
+                        )
+                except (OSError, UnicodeDecodeError) as e:
+                    details.append(f"Could not read changelog: {e}")
+                    return CheckResult(
+                        name=self.name,
+                        status=CheckStatus.WARNING,
+                        message="Could not read changelog file",
+                        details=details,
+                    )
+
+                return CheckResult(
+                    name=self.name,
+                    status=CheckStatus.OK,
+                    message="Changelog present",
+                    details=details,
+                )
+
+        return CheckResult(
+            name=self.name,
+            status=CheckStatus.NOTE,
+            message="No changelog found",
+            details=[
+                "Consider adding CHANGELOG.md to document changes across releases"
+            ],
+        )

pycmdcheck/checks/ci.py

@@ -0,0 +1,87 @@
+"""Continuous integration configuration check.
+
+Verifies that a package has CI configuration files for automated
+testing and deployment.
+"""
+
+from pathlib import Path
+from typing import Any
+
+from pycmdcheck.checks.base import BaseCheck
+from pycmdcheck.results import CheckResult, CheckStatus
+
+
+class CICheck(BaseCheck):
+    """Check for continuous integration configuration.
+
+    Searches for common CI configuration files and directories
+    such as GitHub Actions workflows, CircleCI, Travis CI, etc.
+
+    Attributes:
+        name: The check identifier ("ci").
+        description: Human-readable description of this check.
+    """
+
+    name = "ci"
+    description = "Check for CI configuration"
+
+    # (path_relative_to_root, description)
+    CI_INDICATORS: list[tuple[str, str]] = [
+        (".github/workflows", "GitHub Actions"),
+        (".circleci", "CircleCI"),
+        (".travis.yml", "Travis CI"),
+        (".gitlab-ci.yml", "GitLab CI"),
+        ("Jenkinsfile", "Jenkins"),
+        ("azure-pipelines.yml", "Azure Pipelines"),
+        (".buildkite", "Buildkite"),
+        ("appveyor.yml", "AppVeyor"),
+        (".appveyor.yml", "AppVeyor"),
+    ]
+
+    def run(self, package_path: Path, config: dict[str, Any]) -> CheckResult:
+        """Check for CI configuration presence.
+
+        Args:
+            package_path: Path to the package directory to check.
+            config: Configuration dictionary for this check.
+
+        Returns:
+            A CheckResult with:
+
+            - OK status if CI configuration is found
+            - NOTE status if no CI configuration detected
+        """
+        details: list[str] = []
+        found_ci: list[str] = []
+
+        for path_str, ci_name in self.CI_INDICATORS:
+            candidate = package_path / path_str
+            if candidate.exists():
+                # For directories, check they contain config files
+                if candidate.is_dir():
+                    config_files = list(candidate.glob("*.yml")) + list(
+                        candidate.glob("*.yaml")
+                    )
+                    if config_files:
+                        found_ci.append(ci_name)
+                        details.append(
+                            f"Found {ci_name}: {len(config_files)} config file(s)"
+                        )
+                else:
+                    found_ci.append(ci_name)
+                    details.append(f"Found {ci_name}: {candidate.name}")
+
+        if found_ci:
+            return CheckResult(
+                name=self.name,
+                status=CheckStatus.OK,
+                message=f"CI configured ({', '.join(found_ci)})",
+                details=details,
+            )
+
+        return CheckResult(
+            name=self.name,
+            status=CheckStatus.NOTE,
+            message="No CI configuration found",
+            details=["Consider adding GitHub Actions, CircleCI, or similar CI setup"],
+        )

pycmdcheck/checks/citation.py

@@ -0,0 +1,102 @@
+"""Citation file check.
+
+Verifies that a package has a citation file such as CITATION.cff
+or CITATION.bib for proper academic attribution.
+"""
+
+from pathlib import Path
+from typing import Any
+
+from pycmdcheck.checks.base import BaseCheck
+from pycmdcheck.results import CheckResult, CheckStatus
+
+
+class CitationCheck(BaseCheck):
+    """Check for citation file.
+
+    Searches for CITATION.cff, CITATION.bib, or similar files
+    that enable proper academic citation of the package.
+
+    Attributes:
+        name: The check identifier ("citation").
+        description: Human-readable description of this check.
+    """
+
+    name = "citation"
+    description = "Check for citation file"
+
+    CITATION_FILENAMES = [
+        "CITATION.cff",
+        "CITATION.bib",
+        "CITATION",
+        "CITATION.md",
+        "CITATION.txt",
+    ]
+
+    # Required keys in a valid CITATION.cff
+    CFF_REQUIRED_KEYS = ["title", "authors"]
+
+    def run(self, package_path: Path, config: dict[str, Any]) -> CheckResult:
+        """Check for citation file presence.
+
+        Args:
+            package_path: Path to the package directory to check.
+            config: Configuration dictionary for this check.
+
+        Returns:
+            A CheckResult with:
+
+            - OK status if a citation file is found
+            - NOTE status if no citation file found
+        """
+        details: list[str] = []
+
+        for filename in self.CITATION_FILENAMES:
+            candidate = package_path / filename
+            if candidate.exists():
+                details.append(f"Found: {candidate.name}")
+
+                # Basic validation for CITATION.cff
+                if candidate.name == "CITATION.cff":
+                    self._validate_cff(candidate, details)
+
+                return CheckResult(
+                    name=self.name,
+                    status=CheckStatus.OK,
+                    message="Citation file present",
+                    details=details,
+                )
+
+        return CheckResult(
+            name=self.name,
+            status=CheckStatus.NOTE,
+            message="No citation file found",
+            details=[
+                "Consider adding CITATION.cff for academic attribution",
+                "See https://citation-file-format.github.io/",
+            ],
+        )
+
+    def _validate_cff(self, cff_path: Path, details: list[str]) -> None:
+        """Basic validation of CITATION.cff content.
+
+        Checks that required keys (title, authors) are present
+        by scanning for key patterns in the YAML content.
+        Does not require a YAML parser — uses simple line scanning.
+        """
+        try:
+            content = cff_path.read_text(encoding="utf-8")
+        except (OSError, UnicodeDecodeError):
+            details.append("Could not read CITATION.cff")
+            return
+
+        missing = []
+        for key in self.CFF_REQUIRED_KEYS:
+            # Check for top-level key (not indented)
+            if not any(line.startswith(f"{key}:") for line in content.splitlines()):
+                missing.append(key)
+
+        if missing:
+            details.append(f"CITATION.cff missing keys: {', '.join(missing)}")
+        else:
+            details.append("CITATION.cff has required keys")