pycmdcheck 0.1.0__py3-none-any.whl

pycmdcheck/checks/version.py

@@ -0,0 +1,184 @@
+"""Version consistency check."""
+
+import ast
+from pathlib import Path
+from typing import Any
+
+from pycmdcheck.ast_cache import parse_file
+from pycmdcheck.checks.base import BaseCheck
+from pycmdcheck.package_layout import PackageLayout
+from pycmdcheck.pyproject_reader import get_effective_project_table, read_pyproject
+from pycmdcheck.results import CheckResult, CheckStatus
+
+
+class VersionCheck(BaseCheck):
+    """Check that __version__ in code matches pyproject.toml version."""
+
+    name = "version"
+    description = "Verify version consistency"
+
+    def run(self, package_path: Path, config: dict[str, Any]) -> CheckResult:
+        """Compare __version__ in code with pyproject.toml version."""
+        # Distinguish "no pyproject.toml" from "pyproject present but no
+        # [project] table" (e.g. legacy Poetry / setup.py metadata).
+        if read_pyproject(package_path) is None:
+            return CheckResult(
+                name=self.name,
+                status=CheckStatus.NOTE,
+                message="No pyproject.toml found",
+            )
+
+        project = get_effective_project_table(package_path)
+        if not project:
+            return CheckResult(
+                name=self.name,
+                status=CheckStatus.NOTE,
+                message="No [project] table (legacy/setup.py metadata)",
+                details=["Version consistency not checked"],
+            )
+
+        # Check for dynamic version
+        dynamic = project.get("dynamic", [])
+        if "version" in dynamic:
+            return CheckResult(
+                name=self.name,
+                status=CheckStatus.SKIPPED,
+                message="Version is dynamic (set at build time)",
+            )
+
+        pyproject_version = project.get("version")
+        if not pyproject_version:
+            return CheckResult(
+                name=self.name,
+                status=CheckStatus.WARNING,
+                message="No version in pyproject.toml [project] table",
+            )
+
+        # Find __version__ in code (package __init__.py or single-module file)
+        raw_name = project.get("name")
+        fs_name = raw_name.replace("-", "_") if raw_name else None
+        layout = PackageLayout(package_path, package_name=fs_name)
+        version_source = self._find_version_source(layout, fs_name)
+        if version_source is None:
+            return CheckResult(
+                name=self.name,
+                status=CheckStatus.WARNING,
+                message="No __init__.py or module found to check __version__",
+            )
+
+        code_version = self._extract_version(version_source)
+        if code_version is None:
+            return CheckResult(
+                name=self.name,
+                status=CheckStatus.WARNING,
+                message="No __version__ defined in code",
+                details=[
+                    f"pyproject.toml version: {pyproject_version}",
+                    f'Consider adding __version__ = "{pyproject_version}"'
+                    f" to {version_source.name}",
+                ],
+            )
+
+        if code_version == self._DYNAMIC_VERSION:
+            return CheckResult(
+                name=self.name,
+                status=CheckStatus.OK,
+                message="Version set dynamically (e.g. importlib.metadata)",
+                details=[
+                    f"pyproject.toml version: {pyproject_version}",
+                    "__version__ is set via function call at runtime",
+                ],
+            )
+
+        if code_version == pyproject_version:
+            return CheckResult(
+                name=self.name,
+                status=CheckStatus.OK,
+                message=f"Version {pyproject_version} is consistent",
+                details=[
+                    f"pyproject.toml: {pyproject_version}",
+                    f"__version__: {code_version}",
+                ],
+            )
+
+        return CheckResult(
+            name=self.name,
+            status=CheckStatus.ERROR,
+            message="Version mismatch",
+            details=[
+                f"pyproject.toml: {pyproject_version}",
+                f"__version__: {code_version}",
+            ],
+        )
+
+    # Sentinel returned when __version__ is set via a function call
+    _DYNAMIC_VERSION = "<dynamic>"
+
+    def _find_version_source(
+        self, layout: PackageLayout, fs_name: str | None
+    ) -> Path | None:
+        """Return the file that should declare ``__version__``.
+
+        Prefers the primary package's ``__init__.py``; falls back to a
+        single-module package (``foo.py`` at the import root) when there is no
+        package directory.
+        """
+        pkg_dir = layout.primary_package
+        if pkg_dir is not None:
+            init_file = pkg_dir / "__init__.py"
+            if init_file.exists():
+                return init_file
+
+        modules = layout.top_level_modules()
+        if fs_name:
+            for module in modules:
+                if module.stem == fs_name:
+                    return module
+        if len(modules) == 1:
+            return modules[0]
+        return None
+
+    def _extract_version(self, init_file: Path) -> str | None:
+        """Extract __version__ from a Python file using AST.
+
+        Returns the literal version string, the sentinel ``_DYNAMIC_VERSION``
+        if the version is set via a function call (e.g.
+        ``importlib.metadata.version()``), or ``None`` if no ``__version__``
+        assignment is found.
+        """
+        tree = parse_file(init_file)
+        if tree is None:
+            return None
+
+        for node in ast.walk(tree):
+            # ``from ._version import __version__`` re-exports the version from
+            # another module — treat it like a runtime/dynamic source rather
+            # than "missing", since it cannot be compared statically here.
+            if isinstance(node, ast.ImportFrom):
+                for alias in node.names:
+                    if "__version__" in (alias.name, alias.asname):
+                        return self._DYNAMIC_VERSION
+            if isinstance(node, ast.Assign):
+                for target in node.targets:
+                    if isinstance(target, ast.Name) and target.id == "__version__":
+                        if isinstance(node.value, ast.Constant) and isinstance(
+                            node.value.value, str
+                        ):
+                            return node.value.value
+                        if isinstance(node.value, ast.Call):
+                            return self._DYNAMIC_VERSION
+            elif isinstance(node, ast.AnnAssign):
+                if (
+                    isinstance(node.target, ast.Name)
+                    and node.target.id == "__version__"
+                ):
+                    if (
+                        node.value
+                        and isinstance(node.value, ast.Constant)
+                        and isinstance(node.value.value, str)
+                    ):
+                        return node.value.value
+                    if node.value and isinstance(node.value, ast.Call):
+                        return self._DYNAMIC_VERSION
+
+        return None

pycmdcheck/cli.py

@@ -0,0 +1,296 @@
+"""Command-line interface for pycmdcheck."""
+
+import json
+import logging
+import sys
+from pathlib import Path
+
+import click
+from rich.console import Console
+from rich.table import Table
+from rich.text import Text
+
+from pycmdcheck.config import load_config
+from pycmdcheck.discovery import list_available_checks
+from pycmdcheck.profiles import PROFILES, get_profile, list_profiles
+from pycmdcheck.results import CheckStatus, Report
+from pycmdcheck.runner import run_checks
+
+console = Console()
+
+
+@click.command()
+@click.argument("path", default=".", type=click.Path(exists=True))
+@click.option(
+    "-c",
+    "--check",
+    multiple=True,
+    help="Run only specific check(s). Can be specified multiple times.",
+)
+@click.option(
+    "-s",
+    "--skip",
+    multiple=True,
+    help="Skip specific check(s). Can be specified multiple times.",
+)
+@click.option(
+    "--fail-on",
+    multiple=True,
+    type=click.Choice(["error", "warning", "note"]),
+    default=["error"],
+    help="Exit with non-zero code on these statuses. Default: error",
+)
+@click.option(
+    "--list",
+    "list_checks",
+    is_flag=True,
+    help="List available checks and exit.",
+)
+@click.option(
+    "-v",
+    "--verbose",
+    is_flag=True,
+    help="Show detailed output for each check.",
+)
+@click.option(
+    "--json",
+    "json_output",
+    is_flag=True,
+    help="Output results as JSON.",
+)
+@click.option(
+    "--no-parallel",
+    is_flag=True,
+    help="Run checks sequentially instead of in parallel.",
+)
+@click.option(
+    "-x",
+    "--fail-fast",
+    "fail_fast",
+    is_flag=True,
+    help="Stop after first check failure.",
+)
+@click.option(
+    "--profile",
+    type=click.Choice(list(PROFILES)),
+    default=None,
+    help="Use a predefined check profile.",
+)
+@click.option(
+    "--list-profiles",
+    "list_profiles_flag",
+    is_flag=True,
+    help="List available profiles and exit.",
+)
+@click.option("--debug", is_flag=True, help="Enable debug logging output.")
+@click.version_option(package_name="pycmdcheck")
+def main(
+    path: str,
+    check: tuple[str, ...],
+    skip: tuple[str, ...],
+    fail_on: tuple[str, ...],
+    list_checks: bool,
+    verbose: bool,
+    json_output: bool,
+    no_parallel: bool,
+    fail_fast: bool,
+    profile: str | None,
+    list_profiles_flag: bool,
+    debug: bool,
+) -> None:
+    """Check Python package quality.
+
+    PATH is the directory to check (default: current directory).
+
+    Examples:
+
+        pycmdcheck                    # Check current directory
+
+        pycmdcheck /path/to/package   # Check specific directory
+
+        pycmdcheck -c tests -c linting  # Run only tests and linting
+
+        pycmdcheck -s typing          # Skip type checking
+
+        pycmdcheck --fail-on error --fail-on warning  # Fail on warnings too
+    """
+    if debug:
+        logging.basicConfig(
+            level=logging.DEBUG,
+            format="%(name)s: %(message)s",
+        )
+
+    if list_profiles_flag:
+        _show_profiles()
+        return
+
+    if list_checks:
+        _show_available_checks()
+        return
+
+    # Resolve profile
+    profile_config: dict[str, dict[str, object]] = {}
+    if profile:
+        prof = get_profile(profile)
+        if prof:
+            profile_config = prof.config_overrides
+            if not check:
+                # Use profile's check set (converted to tuple for consistency)
+                check = tuple(sorted(prof.checks))
+
+    # Validate check names
+    if check:
+        from pycmdcheck.discovery import discover_checks
+
+        available = set(discover_checks().keys())
+        invalid = set(check) - available
+        if invalid:
+            console.print(
+                f"[bold red]Unknown check(s): {', '.join(sorted(invalid))}[/bold red]"
+            )
+            console.print(f"Available checks: {', '.join(sorted(available))}")
+            sys.exit(2)
+
+    package_path = Path(path).resolve()
+
+    if not json_output:
+        profile_label = f" (profile: {profile})" if profile else ""
+        console.print(
+            f"\n[bold]Checking package:[/bold] {package_path}{profile_label}\n"
+        )
+
+    # Load config from pyproject.toml and merge profile overrides
+    merged_config = load_config(package_path)
+    if profile_config:
+        checks_section = merged_config.setdefault("checks", {})
+        for check_name, overrides in profile_config.items():
+            existing = checks_section.get(check_name, {})
+            if isinstance(existing, bool):
+                existing = {"enabled": existing}
+            existing.update(overrides)
+            checks_section[check_name] = existing
+
+    # Run checks
+    if not json_output and console.is_terminal:
+        with console.status("[bold]Running checks...[/bold]"):
+            report = run_checks(
+                package_path=package_path,
+                checks=list(check) if check else None,
+                skip=list(skip),
+                config=merged_config,
+                parallel=not no_parallel,
+                fail_fast=fail_fast,
+            )
+    else:
+        report = run_checks(
+            package_path=package_path,
+            checks=list(check) if check else None,
+            skip=list(skip),
+            config=merged_config,
+            parallel=not no_parallel,
+            fail_fast=fail_fast,
+        )
+
+    # Output results
+    if json_output:
+        _output_json(report)
+    else:
+        _output_rich(report, verbose)
+
+    # Determine exit code
+    if report.failed_on(list(fail_on)):
+        sys.exit(1)
+
+
+def _show_profiles(con: Console | None = None) -> None:
+    """Display list of available profiles."""
+    con = con or console
+    profiles = list_profiles()
+
+    table = Table(title="Available Profiles")
+    table.add_column("Name", style="cyan")
+    table.add_column("Description")
+
+    for name, description in profiles:
+        table.add_row(name, description)
+
+    con.print(table)
+
+
+def _show_available_checks(con: Console | None = None) -> None:
+    """Display list of available checks."""
+    con = con or console
+    checks = list_available_checks()
+
+    table = Table(title="Available Checks")
+    table.add_column("Name", style="cyan")
+    table.add_column("Description")
+
+    for name, description in checks:
+        table.add_row(name, description)
+
+    con.print(table)
+
+
+def _output_json(report: Report) -> None:
+    """Output report as JSON."""
+    print(json.dumps(report.to_dict(), indent=2))
+
+
+def _output_rich(report: Report, verbose: bool, con: Console | None = None) -> None:
+    """Output report with rich formatting."""
+    con = con or console
+    if not report.results:
+        con.print("[yellow]No checks were run.[/yellow]")
+        return
+
+    # Create results table
+    table = Table(show_header=True, header_style="bold")
+    table.add_column("Status", width=3, justify="center")
+    table.add_column("Check", style="cyan")
+    table.add_column("Message")
+    if verbose:
+        table.add_column("Time", justify="right")
+
+    for result in report.results:
+        status_text = Text(result.status.symbol)
+        status_text.stylize(result.status.color)
+
+        if verbose:
+            table.add_row(
+                status_text, result.name, result.message, f"{result.duration:.2f}s"
+            )
+        else:
+            table.add_row(status_text, result.name, result.message)
+
+    con.print(table)
+
+    # Show details if verbose
+    if verbose:
+        for result in report.results:
+            if result.details:
+                con.print(f"\n[bold]{result.name}[/bold] details:")
+                for detail in result.details:
+                    con.print(f"  {detail}")
+
+    # Summary
+    con.print()
+    counts = report.count_by_status()
+    summary_parts: list[str] = []
+
+    for status in CheckStatus:
+        count = counts[status]
+        if count > 0:
+            colored = f"[{status.color}]{count} {status.value}[/{status.color}]"
+            summary_parts.append(colored)
+
+    con.print(" | ".join(summary_parts))
+
+    if report.passed:
+        con.print("\n[bold green]All checks passed![/bold green]")
+    else:
+        con.print("\n[bold red]Some checks failed.[/bold red]")
+
+
+if __name__ == "__main__":
+    main()

pycmdcheck/config.py

@@ -0,0 +1,194 @@
+"""Configuration loading for pycmdcheck."""
+
+import copy
+import logging
+from pathlib import Path
+from typing import Any
+
+from pycmdcheck.pyproject_reader import get_tool_table
+
+logger = logging.getLogger(__name__)
+
+VALID_FAIL_ON = {"error", "warning", "note"}
+
+
+DEFAULT_CONFIG: dict[str, Any] = {
+    "fail_on": ["error"],
+    "checks": {
+        "metadata": True,
+        "structure": True,
+        "tests": {"enabled": True, "runner": "pytest"},
+        "linting": {"enabled": True, "tool": "ruff"},
+        "typing": {"enabled": True, "tool": "mypy"},
+        "imports": True,
+        "license": True,
+        "docs": True,
+        "dependencies": True,
+        "build": True,
+        "formatting": {"enabled": True, "tool": "auto"},
+        "version": True,
+        "py_typed": True,
+    },
+}
+"""Default configuration applied when no pyproject.toml is found.
+
+This configuration enables all built-in checks with sensible defaults:
+- tests: Uses pytest as the test runner
+- linting: Uses ruff as the linter
+- typing: Uses mypy as the type checker
+"""
+
+
+def load_config(package_path: Path) -> dict[str, Any]:
+    """Load pycmdcheck configuration from pyproject.toml.
+
+    Reads the [tool.pycmdcheck] section from the package's pyproject.toml
+    and merges it with default configuration. If no pyproject.toml exists
+    or it doesn't contain pycmdcheck configuration, returns defaults.
+
+    Args:
+        package_path: Path to the package directory containing pyproject.toml.
+
+    Returns:
+        Configuration dictionary with the following structure:
+        - fail_on: List of statuses to fail on (default: ["error"])
+        - checks: Dictionary of check configurations
+
+    Examples:
+        >>> from pathlib import Path
+        >>> config = load_config(Path("."))
+        >>> config["fail_on"]
+        ['error']
+        >>> config["checks"]["tests"]["runner"]
+        'pytest'
+    """
+    config = copy.deepcopy(DEFAULT_CONFIG)
+    tool_config = get_tool_table(package_path, "pycmdcheck")
+    if tool_config:
+        config = _merge_config(config, tool_config)
+    config_warnings = validate_config(config)
+    for w in config_warnings:
+        logger.warning("Config: %s", w)
+    logger.debug("Loaded config from %s", package_path)
+    return config
+
+
+def get_check_config(config: dict[str, Any], check_name: str) -> dict[str, Any]:
+    """Get configuration for a specific check.
+
+    Extracts the configuration for a named check from the full configuration.
+    Handles both boolean shorthand (e.g., `metadata = true`) and dictionary
+    configuration (e.g., `tests = { enabled = true, runner = "pytest" }`).
+
+    Args:
+        config: Full pycmdcheck configuration dictionary, as returned by
+            load_config().
+        check_name: Name of the check to get configuration for (e.g.,
+            "metadata", "tests", "linting").
+
+    Returns:
+        Configuration dictionary for the check, always containing an
+        "enabled" key. Additional keys depend on the check type.
+
+    Examples:
+        Boolean config is converted to dict:
+
+        >>> config = {"checks": {"metadata": True}}
+        >>> get_check_config(config, "metadata")
+        {'enabled': True}
+
+        Dict config is passed through with enabled defaulting to True:
+
+        >>> config = {"checks": {"tests": {"runner": "pytest"}}}
+        >>> get_check_config(config, "tests")
+        {'runner': 'pytest', 'enabled': True}
+
+        Unknown checks default to enabled:
+
+        >>> config = {"checks": {}}
+        >>> get_check_config(config, "unknown")
+        {'enabled': True}
+    """
+    checks_config = config.get("checks", {})
+    check_config = checks_config.get(check_name, True)
+
+    # Handle boolean shorthand
+    if isinstance(check_config, bool):
+        return {"enabled": check_config}
+
+    # Handle dict config (ensure 'enabled' key exists)
+    if isinstance(check_config, dict):
+        result = dict(check_config)
+        result.setdefault("enabled", True)
+        return result
+
+    # Default to enabled
+    return {"enabled": True}
+
+
+def is_check_enabled(config: dict[str, Any], check_name: str) -> bool:
+    """Check if a specific check is enabled.
+
+    Convenience function to determine if a check should run based on
+    the configuration.
+
+    Args:
+        config: Full pycmdcheck configuration dictionary.
+        check_name: Name of the check to query.
+
+    Returns:
+        True if the check is enabled, False otherwise.
+
+    Examples:
+        >>> config = {"checks": {"metadata": True, "linting": False}}
+        >>> is_check_enabled(config, "metadata")
+        True
+        >>> is_check_enabled(config, "linting")
+        False
+        >>> is_check_enabled(config, "unknown")  # Defaults to enabled
+        True
+    """
+    check_config = get_check_config(config, check_name)
+    return bool(check_config.get("enabled", True))
+
+
+def validate_config(config: dict[str, Any]) -> list[str]:
+    """Validate config values and return a list of warning messages."""
+    warnings: list[str] = []
+
+    fail_on = config.get("fail_on", [])
+    if not isinstance(fail_on, list):
+        warnings.append(f"'fail_on' should be a list, got {type(fail_on).__name__}")
+    else:
+        for value in fail_on:
+            if value not in VALID_FAIL_ON:
+                warnings.append(
+                    f"Invalid fail_on value '{value}'. "
+                    f"Valid values: {', '.join(sorted(VALID_FAIL_ON))}"
+                )
+
+    return warnings
+
+
+def _merge_config(base: dict[str, Any], override: dict[str, Any]) -> dict[str, Any]:
+    """Recursively merge override into base configuration.
+
+    Values in override take precedence. Nested dictionaries are merged
+    recursively rather than replaced.
+
+    Args:
+        base: Base configuration dictionary.
+        override: Override configuration dictionary.
+
+    Returns:
+        Merged configuration dictionary.
+    """
+    result = copy.deepcopy(base)
+
+    for key, value in override.items():
+        if key in result and isinstance(result[key], dict) and isinstance(value, dict):
+            result[key] = _merge_config(result[key], value)
+        else:
+            result[key] = value
+
+    return result

pycmdcheck/constants.py

@@ -0,0 +1,29 @@
+"""Named constants used across pycmdcheck."""
+
+# Subprocess execution
+DEFAULT_TIMEOUT: int = 120
+LONG_TIMEOUT: int = 300
+
+# Output limits
+MAX_DETAIL_LINES: int = 10
+MAX_WORKERS: int = 4
+
+# Documentation thresholds
+MIN_README_WORDS: int = 50
+MIN_LICENSE_LENGTH: int = 50
+MAX_DOCSTRING_FILES: int = 20
+MAX_TYPE_SCAN_FILES: int = 20
+
+# URL validation
+URL_TIMEOUT: int = 10
+MAX_URL_CHECKS: int = 20
+
+# Changelog validation
+MIN_CHANGELOG_LENGTH: int = 50
+
+# Python version EOL dates (year, month) — versions whose EOL has passed
+# Source: https://devguide.python.org/versions/
+PYTHON_EOL_VERSIONS: dict[str, tuple[int, int]] = {
+    "3.8": (2024, 10),
+    "3.9": (2025, 10),
+}