pycmdcheck 0.1.0__py3-none-any.whl

pycmdcheck/checks/linting.py

@@ -0,0 +1,304 @@
+"""Linting check with configurable backends.
+
+This module provides the LintingCheck class which runs code linting
+tools (ruff, flake8, or pylint) on the package and reports any issues.
+"""
+
+from pathlib import Path
+from typing import Any
+
+from pycmdcheck.checks.base import BaseCheck
+from pycmdcheck.constants import DEFAULT_TIMEOUT, LONG_TIMEOUT, MAX_DETAIL_LINES
+from pycmdcheck.results import CheckResult, CheckStatus
+from pycmdcheck.subprocess_runner import run_tool, sanitize_args, tool_available
+
+
+class LintingCheck(BaseCheck):
+    """Run linting tools on the package.
+
+    Executes a configurable linting tool to check code quality and
+    style. Supports ruff (default), flake8, and pylint.
+
+    Attributes:
+        name: The check identifier ("linting").
+        description: Human-readable description of this check.
+        SUPPORTED_TOOLS: List of supported linting tools.
+
+    Configuration Options:
+        tool (str): Linter to use ("ruff", "flake8", or "pylint").
+            Defaults to "ruff".
+        args (list[str]): Additional arguments to pass to the linter.
+
+    Examples:
+        Run linting with default settings (ruff):
+
+        >>> from pathlib import Path
+        >>> check = LintingCheck()
+        >>> result = check.run(Path("."), {"enabled": True})
+        >>> result.name
+        'linting'
+
+        Configure to use flake8:
+
+        >>> config = {"enabled": True, "tool": "flake8"}
+        >>> result = check.run(Path("."), config)
+
+        Pass additional ruff arguments:
+
+        >>> config = {"enabled": True, "args": ["--select", "E,W"]}
+        >>> result = check.run(Path("."), config)
+    """
+
+    name = "linting"
+    description = "Run code linting (ruff/flake8/pylint)"
+
+    SUPPORTED_TOOLS = ["ruff", "flake8", "pylint"]
+
+    def run(self, package_path: Path, config: dict[str, Any]) -> CheckResult:
+        """Run linting check on the package.
+
+        Executes the configured linting tool and collects any issues found.
+        Issues are reported in the result details (limited to first 10).
+
+        Args:
+            package_path: Path to the package directory to lint.
+            config: Configuration dictionary with options:
+
+                - tool (str): "ruff", "flake8", or "pylint" (default: "ruff")
+                - args (list[str]): Additional arguments for the linter
+
+        Returns:
+            A CheckResult with:
+
+            - OK status if no linting issues found
+            - WARNING status if linting issues found
+            - ERROR status if linter fails or unsupported tool specified
+            - SKIPPED status if the linting tool is not installed
+        """
+        tool = config.get("tool", "ruff")
+
+        if tool not in self.SUPPORTED_TOOLS:
+            return CheckResult(
+                name=self.name,
+                status=CheckStatus.ERROR,
+                message=f"Unsupported linting tool: {tool}",
+                details=[f"Supported tools: {', '.join(self.SUPPORTED_TOOLS)}"],
+            )
+
+        preamble = [f"Using linter: {tool}"]
+
+        if tool == "ruff":
+            return self._run_ruff(package_path, config, preamble)
+        elif tool == "flake8":
+            return self._run_flake8(package_path, config, preamble)
+        else:  # pylint
+            return self._run_pylint(package_path, config, preamble)
+
+    def _run_ruff(
+        self, package_path: Path, config: dict[str, Any], preamble: list[str]
+    ) -> CheckResult:
+        """Run ruff linter."""
+        if not tool_available("ruff"):
+            return CheckResult(
+                name=self.name,
+                status=CheckStatus.SKIPPED,
+                message="ruff not installed",
+                details=["Install ruff: pip install ruff"],
+            )
+
+        args = sanitize_args(config.get("args", []))
+        cmd = ["ruff", "check", ".", *args]
+
+        result = run_tool(cmd, cwd=package_path, timeout=DEFAULT_TIMEOUT)
+
+        if result.timed_out:
+            return CheckResult(
+                name=self.name,
+                status=CheckStatus.ERROR,
+                message="Linting timed out",
+                details=[f"Linting took longer than {DEFAULT_TIMEOUT} seconds"],
+            )
+
+        if result.error is not None:
+            return CheckResult(
+                name=self.name,
+                status=CheckStatus.ERROR,
+                message="Failed to run ruff",
+                details=[result.error],
+            )
+
+        if result.success:
+            return CheckResult(
+                name=self.name,
+                status=CheckStatus.OK,
+                message="No linting issues found",
+                details=list(preamble),
+            )
+
+        issues = result.output_lines()
+        issue_count = len(issues)
+
+        # A tool/config/usage failure (ruff exit code >= 2, or a non-zero exit
+        # with no parsable issues on stdout) is NOT a code-quality finding —
+        # surface the real error instead of "Found 0 linting issue(s)".
+        tool_error = self._tool_failure(result, "ruff", issue_count)
+        if tool_error is not None:
+            return tool_error
+
+        details = [*preamble, *issues[:MAX_DETAIL_LINES]]
+
+        if issue_count > MAX_DETAIL_LINES:
+            details.append(f"... and {issue_count - MAX_DETAIL_LINES} more issues")
+
+        return CheckResult(
+            name=self.name,
+            status=CheckStatus.WARNING,
+            message=f"Found {issue_count} linting issue(s)",
+            details=details,
+        )
+
+    def _tool_failure(
+        self, result: Any, tool: str, issue_count: int
+    ) -> CheckResult | None:
+        """Return an ERROR result if the linter failed to run, else ``None``.
+
+        Treats an exit code >= 2 (ruff/flake8 configuration or usage error) or
+        a non-zero exit that produced no parsable issues but did write to stderr
+        as a tool failure rather than a lint finding.
+        """
+        is_config_error = result.returncode >= 2
+        stderr = (result.stderr or "").strip()
+        no_issues_but_stderr = issue_count == 0 and bool(stderr)
+        if not (is_config_error or no_issues_but_stderr):
+            return None
+        detail_lines = (result.output or "").strip().splitlines()
+        return CheckResult(
+            name=self.name,
+            status=CheckStatus.ERROR,
+            message=f"{tool} failed to run (configuration or usage error)",
+            details=[f"Using linter: {tool}", *detail_lines[:MAX_DETAIL_LINES]],
+        )
+
+    def _run_flake8(
+        self, package_path: Path, config: dict[str, Any], preamble: list[str]
+    ) -> CheckResult:
+        """Run flake8 linter."""
+        if not tool_available("flake8"):
+            return CheckResult(
+                name=self.name,
+                status=CheckStatus.SKIPPED,
+                message="flake8 not installed",
+                details=["Install flake8: pip install flake8"],
+            )
+
+        args = sanitize_args(config.get("args", []))
+        cmd = ["flake8", ".", *args]
+
+        result = run_tool(cmd, cwd=package_path, timeout=DEFAULT_TIMEOUT)
+
+        if result.timed_out:
+            return CheckResult(
+                name=self.name,
+                status=CheckStatus.ERROR,
+                message="Linting timed out",
+                details=[f"Linting took longer than {DEFAULT_TIMEOUT} seconds"],
+            )
+
+        if result.error is not None:
+            return CheckResult(
+                name=self.name,
+                status=CheckStatus.ERROR,
+                message="Failed to run flake8",
+                details=[result.error],
+            )
+
+        if result.success:
+            return CheckResult(
+                name=self.name,
+                status=CheckStatus.OK,
+                message="No linting issues found",
+                details=list(preamble),
+            )
+
+        issues = result.output_lines()
+        issue_count = len(issues)
+
+        tool_error = self._tool_failure(result, "flake8", issue_count)
+        if tool_error is not None:
+            return tool_error
+
+        details = [*preamble, *issues[:MAX_DETAIL_LINES]]
+
+        if issue_count > MAX_DETAIL_LINES:
+            details.append(f"... and {issue_count - MAX_DETAIL_LINES} more issues")
+
+        return CheckResult(
+            name=self.name,
+            status=CheckStatus.WARNING,
+            message=f"Found {issue_count} linting issue(s)",
+            details=details,
+        )
+
+    def _run_pylint(
+        self, package_path: Path, config: dict[str, Any], preamble: list[str]
+    ) -> CheckResult:
+        """Run pylint linter."""
+        if not tool_available("pylint"):
+            return CheckResult(
+                name=self.name,
+                status=CheckStatus.SKIPPED,
+                message="pylint not installed",
+                details=["Install pylint: pip install pylint"],
+            )
+
+        # Find Python files to lint
+        src_dir = package_path / "src"
+        if src_dir.is_dir():
+            target = str(src_dir)
+        else:
+            target = "."
+
+        args = sanitize_args(config.get("args", []))
+        cmd = ["pylint", target, "--output-format=text", *args]
+
+        result = run_tool(cmd, cwd=package_path, timeout=LONG_TIMEOUT)
+
+        if result.timed_out:
+            return CheckResult(
+                name=self.name,
+                status=CheckStatus.ERROR,
+                message="Linting timed out",
+                details=[f"Linting took longer than {LONG_TIMEOUT} seconds"],
+            )
+
+        if result.error is not None:
+            return CheckResult(
+                name=self.name,
+                status=CheckStatus.ERROR,
+                message="Failed to run pylint",
+                details=[result.error],
+            )
+
+        if result.success:
+            return CheckResult(
+                name=self.name,
+                status=CheckStatus.OK,
+                message="No linting issues found",
+                details=list(preamble),
+            )
+
+        # Parse output
+        issues = result.output_lines()
+        issue_lines = [i for i in issues if ": " in i and i[0] != "*"]
+
+        details = [*preamble, *issue_lines[:MAX_DETAIL_LINES]]
+
+        if len(issue_lines) > MAX_DETAIL_LINES:
+            details.append(f"... and {len(issue_lines) - MAX_DETAIL_LINES} more issues")
+
+        return CheckResult(
+            name=self.name,
+            status=CheckStatus.WARNING,
+            message=f"Found {len(issue_lines)} linting issue(s)",
+            details=details,
+        )

pycmdcheck/checks/metadata.py

@@ -0,0 +1,233 @@
+"""Package metadata validation check.
+
+This module provides the MetadataCheck class which validates that a
+Python package has proper metadata defined in pyproject.toml (preferred)
+or legacy setup.py/setup.cfg files.
+"""
+
+from pathlib import Path
+from typing import Any
+
+from pycmdcheck.checks.base import BaseCheck
+from pycmdcheck.pyproject_reader import get_effective_project_table, read_pyproject
+from pycmdcheck.results import CheckResult, CheckStatus
+
+
+class MetadataCheck(BaseCheck):
+    """Check that package metadata is valid and complete.
+
+    Validates package metadata according to PEP 621 (pyproject.toml).
+    Checks for required fields (name, version) and recommends additional
+    fields (description, readme, license, requires-python).
+
+    Attributes:
+        name: The check identifier ("metadata").
+        description: Human-readable description of this check.
+        REQUIRED_FIELDS: List of fields that must be present in [project].
+        RECOMMENDED_FIELDS: List of fields that should be present.
+        EXTENDED_FIELDS: List of extended fields checked for completeness.
+
+    Examples:
+        Run the metadata check on a package:
+
+        >>> from pathlib import Path
+        >>> check = MetadataCheck()
+        >>> result = check.run(Path("."), {"enabled": True})
+        >>> result.status in [CheckStatus.OK, CheckStatus.NOTE, CheckStatus.ERROR]
+        True
+
+        The check validates pyproject.toml structure:
+
+        >>> check.REQUIRED_FIELDS
+        ['name', 'version']
+    """
+
+    name = "metadata"
+    description = "Validate package metadata (pyproject.toml)"
+
+    REQUIRED_FIELDS = ["name", "version"]
+    RECOMMENDED_FIELDS = ["description", "readme", "license", "requires-python"]
+    EXTENDED_FIELDS = ["authors", "urls", "classifiers"]
+
+    def run(self, package_path: Path, config: dict[str, Any]) -> CheckResult:
+        """Check package metadata for validity and completeness.
+
+        Looks for pyproject.toml first (preferred), falling back to
+        setup.py/setup.cfg (legacy). Validates required fields and
+        suggests recommended fields.
+
+        Args:
+            package_path: Path to the package directory containing
+                pyproject.toml or setup files.
+            config: Configuration dictionary for this check. Currently
+                no check-specific options are used.
+
+        Returns:
+            A CheckResult with:
+
+            - OK status if all required and recommended fields present
+            - NOTE status if required fields present but some recommended missing
+            - WARNING status if using legacy setup.py/setup.cfg
+            - ERROR status if pyproject.toml is invalid or missing required fields
+        """
+        pyproject_path = package_path / "pyproject.toml"
+        setup_py_path = package_path / "setup.py"
+        setup_cfg_path = package_path / "setup.cfg"
+
+        details: list[str] = []
+
+        # Check for pyproject.toml (preferred)
+        if pyproject_path.exists():
+            return self._check_pyproject(pyproject_path, details)
+
+        # Check for setup.py or setup.cfg
+        if setup_py_path.exists() or setup_cfg_path.exists():
+            details.append("Using legacy setup.py/setup.cfg instead of pyproject.toml")
+            return CheckResult(
+                name=self.name,
+                status=CheckStatus.WARNING,
+                message="Consider migrating to pyproject.toml",
+                details=details,
+            )
+
+        return CheckResult(
+            name=self.name,
+            status=CheckStatus.ERROR,
+            message="No package metadata found",
+            details=["Missing pyproject.toml, setup.py, or setup.cfg"],
+        )
+
+    def _check_pyproject(self, pyproject_path: Path, details: list[str]) -> CheckResult:
+        """Validate pyproject.toml contents."""
+        try:
+            pyproject = read_pyproject(pyproject_path.parent)
+        except (ValueError, OSError) as e:
+            return CheckResult(
+                name=self.name,
+                status=CheckStatus.ERROR,
+                message="Invalid pyproject.toml",
+                details=[f"TOML parse error: {e}"],
+            )
+
+        if pyproject is None:
+            return CheckResult(
+                name=self.name,
+                status=CheckStatus.ERROR,
+                message="No package metadata found",
+                details=["Missing pyproject.toml"],
+            )
+
+        # Use the effective table so legacy Poetry ([tool.poetry], no [project])
+        # is treated like a PEP 621 [project] table rather than reported empty.
+        project = get_effective_project_table(pyproject_path.parent)
+        missing_required: list[str] = []
+        missing_recommended: list[str] = []
+
+        # Check required fields
+        for field in self.REQUIRED_FIELDS:
+            if not self._is_declared(project, field):
+                missing_required.append(field)
+
+        # Check recommended fields
+        for field in self.RECOMMENDED_FIELDS:
+            if not self._is_declared(project, field):
+                missing_recommended.append(field)
+
+        # Build result
+        if missing_required:
+            details.append(f"Missing required fields: {', '.join(missing_required)}")
+            return CheckResult(
+                name=self.name,
+                status=CheckStatus.ERROR,
+                message="Missing required metadata fields",
+                details=details,
+            )
+
+        if missing_recommended:
+            details.append(
+                f"Missing recommended fields: {', '.join(missing_recommended)}"
+            )
+            self._check_extended_fields(project, pyproject, details)
+            return CheckResult(
+                name=self.name,
+                status=CheckStatus.NOTE,
+                message="Some recommended metadata fields are missing",
+                details=details,
+            )
+
+        self._check_extended_fields(project, pyproject, details)
+
+        if any("missing extended" in d.lower() for d in details):
+            return CheckResult(
+                name=self.name,
+                status=CheckStatus.NOTE,
+                message="Some extended metadata fields are missing",
+                details=details,
+            )
+
+        details.append("All metadata fields present")
+        return CheckResult(
+            name=self.name,
+            status=CheckStatus.OK,
+            message="Package metadata is valid",
+            details=details,
+        )
+
+    @staticmethod
+    def _is_declared(project: dict[str, Any], field: str) -> bool:
+        """Return whether a ``[project]`` field is declared.
+
+        A field counts as declared if it is statically present in the
+        ``[project]`` table OR listed in PEP 621 ``dynamic`` (in which case
+        the build backend supplies its value at build time, e.g. via
+        setuptools_scm, hatch-vcs, or uv-dynamic-versioning). Fields named
+        in ``dynamic`` must not be reported as missing.
+        """
+        if field in project:
+            return True
+        dynamic = project.get("dynamic", [])
+        return isinstance(dynamic, list) and field in dynamic
+
+    def _check_extended_fields(
+        self,
+        project: dict[str, Any],
+        pyproject: dict[str, Any],
+        details: list[str],
+    ) -> None:
+        """Check extended metadata fields and append notes to details.
+
+        Validates that ``authors``, ``classifiers``, and ``[project.urls]``
+        are present and non-empty.  Missing or empty fields are reported as
+        a single NOTE-level detail line.  Fields declared in PEP 621
+        ``dynamic`` are considered present (the build backend supplies them).
+
+        Args:
+            project: The ``[project]`` table from pyproject.toml.
+            pyproject: The full parsed pyproject.toml dictionary.
+            details: Mutable list to which detail strings are appended.
+        """
+        missing: list[str] = []
+
+        # authors: must be a non-empty list (or declared dynamic)
+        authors = project.get("authors")
+        if not self._is_declared(project, "authors") and (
+            not isinstance(authors, list) or len(authors) == 0
+        ):
+            missing.append("authors")
+
+        # urls: the [project.urls] table must exist with >=1 entry (or dynamic)
+        urls = project.get("urls")
+        if not self._is_declared(project, "urls") and (
+            not isinstance(urls, dict) or len(urls) == 0
+        ):
+            missing.append("urls")
+
+        # classifiers: must be a non-empty list (or declared dynamic)
+        classifiers = project.get("classifiers")
+        if not self._is_declared(project, "classifiers") and (
+            not isinstance(classifiers, list) or len(classifiers) == 0
+        ):
+            missing.append("classifiers")
+
+        if missing:
+            details.append(f"Missing extended metadata fields: {', '.join(missing)}")