pycmdcheck 0.1.0__py3-none-any.whl

pycmdcheck/checks/docs.py

@@ -0,0 +1,305 @@
+"""Documentation check.
+
+This module provides the DocsCheck class which verifies that a package
+has proper documentation including a README file and optionally checks
+for docstrings in the code.
+"""
+
+import ast
+import logging
+import re
+from pathlib import Path
+from typing import Any
+
+from pycmdcheck.ast_cache import parse_file
+from pycmdcheck.checks.base import BaseCheck
+from pycmdcheck.constants import MAX_DOCSTRING_FILES, MIN_README_WORDS
+from pycmdcheck.package_layout import PackageLayout
+from pycmdcheck.results import CheckResult, CheckStatus
+
+logger = logging.getLogger(__name__)
+
+
+class DocsCheck(BaseCheck):
+    """Check for documentation presence and quality.
+
+    Verifies that the package has a README file and optionally checks
+    that public modules, classes, and functions have docstrings.
+
+    Attributes:
+        name: The check identifier ("docs").
+        description: Human-readable description of this check.
+        README_FILENAMES: List of recognized README file names.
+
+    Configuration Options:
+        require_readme (bool): Whether README is required. Defaults to True.
+        check_docstrings (bool): Whether to check for docstrings in code.
+            Defaults to False.
+        check_readme_sections (bool): Whether to check for common README
+            sections (Installation, Usage). Defaults to False.
+        min_docstring_coverage (float): Minimum docstring coverage percentage
+            (0.0-100.0). When > 0 and coverage is below threshold, an issue
+            is reported. Defaults to 0.0 (disabled).
+
+    Examples:
+        Run the docs check with defaults:
+
+        >>> from pathlib import Path
+        >>> check = DocsCheck()
+        >>> result = check.run(Path("."), {"enabled": True})
+        >>> result.name
+        'docs'
+
+        Enable docstring checking:
+
+        >>> config = {"enabled": True, "check_docstrings": True}
+        >>> result = check.run(Path("."), config)
+
+        Make README optional:
+
+        >>> config = {"enabled": True, "require_readme": False}
+        >>> result = check.run(Path("."), config)
+    """
+
+    name = "docs"
+    description = "Check documentation (README, docstrings)"
+
+    README_FILENAMES = [
+        "README.md",
+        "README.rst",
+        "README.txt",
+        "README",
+    ]
+
+    def run(self, package_path: Path, config: dict[str, Any]) -> CheckResult:
+        """Check documentation presence and quality.
+
+        Looks for a README file and optionally scans code for missing
+        docstrings on public items.
+
+        Args:
+            package_path: Path to the package directory to check.
+            config: Configuration dictionary with options:
+
+                - require_readme (bool): Require README (default: True)
+                - check_docstrings (bool): Check code docstrings (default: False)
+                - check_readme_sections (bool): Check for common README
+                  sections (default: False)
+                - min_docstring_coverage (float): Minimum coverage %
+                  (default: 0.0, disabled)
+
+        Returns:
+            A CheckResult with:
+
+            - OK status if all documentation requirements met
+            - NOTE status if minor improvements suggested
+            - WARNING status if README missing (when required)
+        """
+        details: list[str] = []
+        issues: list[str] = []
+
+        # Check for README
+        require_readme = config.get("require_readme", True)
+        readme_found = self._check_readme(package_path, details, issues, require_readme)
+
+        # Check README sections (opt-in)
+        if config.get("check_readme_sections", False) and readme_found:
+            self._check_readme_sections(package_path, details, issues)
+
+        # Check for docstrings (optional)
+        check_docstrings = config.get("check_docstrings", False)
+        if check_docstrings:
+            min_coverage = config.get("min_docstring_coverage", 0.0)
+            self._check_docstrings(package_path, details, issues, min_coverage)
+
+        # Determine status
+        if issues and require_readme and not readme_found:
+            return CheckResult(
+                name=self.name,
+                status=CheckStatus.WARNING,
+                message="Documentation incomplete",
+                details=details + issues,
+            )
+
+        if issues:
+            return CheckResult(
+                name=self.name,
+                status=CheckStatus.NOTE,
+                message="Some documentation improvements suggested",
+                details=details + issues,
+            )
+
+        return CheckResult(
+            name=self.name,
+            status=CheckStatus.OK,
+            message="Documentation present",
+            details=details,
+        )
+
+    def _check_readme(
+        self,
+        package_path: Path,
+        details: list[str],
+        issues: list[str],
+        require_readme: bool,
+    ) -> bool:
+        """Check for README file."""
+        for filename in self.README_FILENAMES:
+            readme_path = package_path / filename
+            if readme_path.exists():
+                details.append(f"Found README: {filename}")
+
+                # Check README is not too short
+                try:
+                    content = readme_path.read_text(encoding="utf-8")
+                    word_count = len(content.split())
+                    if word_count < MIN_README_WORDS:
+                        issues.append(
+                            f"README is very short (< {MIN_README_WORDS} words)"
+                        )
+                    else:
+                        details.append(f"README has {word_count} words")
+                except (OSError, UnicodeDecodeError) as exc:
+                    logger.debug("Could not read README %s: %s", readme_path, exc)
+
+                return True
+
+        if require_readme:
+            issues.append("No README file found")
+        return False
+
+    def _check_readme_sections(
+        self,
+        package_path: Path,
+        details: list[str],
+        issues: list[str],
+    ) -> None:
+        """Check that the README mentions common sections.
+
+        Searches the whole README body (case-insensitive) for Installation
+        and Usage keywords rather than only Markdown ``#`` headings, so that
+        RST/Setext/plain-text READMEs and synonyms (Quick Start, Getting
+        Started, Example, Tutorial) are recognized and not falsely flagged.
+        """
+        readme_content = ""
+        for filename in self.README_FILENAMES:
+            readme_path = package_path / filename
+            if readme_path.exists():
+                try:
+                    readme_content = readme_path.read_text(encoding="utf-8")
+                except (OSError, UnicodeDecodeError) as exc:
+                    logger.debug("Could not read README %s: %s", readme_path, exc)
+                break
+
+        if not readme_content:
+            return
+
+        text = readme_content.lower()
+
+        expected_sections = {
+            "Installation": r"install",
+            "Usage": (
+                r"usage|quick[\s-]?start|getting[\s-]?started"
+                r"|example|tutorial|how to use"
+            ),
+        }
+
+        for section_name, pattern in expected_sections.items():
+            if not re.search(pattern, text):
+                issues.append(f"README missing section: {section_name}")
+
+    def _check_docstrings(
+        self,
+        package_path: Path,
+        details: list[str],
+        issues: list[str],
+        min_coverage: float = 0.0,
+    ) -> None:
+        """Check for docstrings in public modules and functions."""
+        # Find Python files
+        layout = PackageLayout(package_path)
+        py_files = layout.python_files()
+
+        # Exclude test files
+        py_files = [f for f in py_files if not f.name.startswith("test_")]
+
+        missing_docstrings: list[str] = []
+        total_public_items = 0
+
+        for py_file in py_files[:MAX_DOCSTRING_FILES]:  # Limit to first N files
+            try:
+                total, missing = self._check_file_docstrings_counted(py_file)
+                total_public_items += total
+                missing_docstrings.extend(missing)
+            except (OSError, UnicodeDecodeError) as exc:
+                logger.debug("Could not parse %s: %s", py_file, exc)
+
+        if missing_docstrings:
+            issues.append(
+                f"Missing docstrings in {len(missing_docstrings)} public items"
+            )
+            for missing_item in missing_docstrings[:5]:
+                issues.append(f"  - {missing_item}")
+            if len(missing_docstrings) > 5:
+                issues.append(f"  ... and {len(missing_docstrings) - 5} more")
+        else:
+            details.append("All public items have docstrings")
+
+        # Report coverage percentage
+        documented = total_public_items - len(missing_docstrings)
+        if total_public_items > 0:
+            pct = documented / total_public_items * 100
+            details.append(
+                f"Docstring coverage: {documented}/{total_public_items}"
+                f" public items ({pct:.0f}%)"
+            )
+
+            # Check minimum coverage threshold
+            if min_coverage > 0 and pct < min_coverage:
+                issues.append(
+                    f"Docstring coverage {pct:.0f}% is below"
+                    f" minimum {min_coverage:.0f}%"
+                )
+        else:
+            details.append("Docstring coverage: 0/0 public items (100%)")
+
+    def _check_file_docstrings(self, py_file: Path) -> list[str]:
+        """Check docstrings in a single Python file."""
+        _total, missing = self._check_file_docstrings_counted(py_file)
+        return missing
+
+    def _check_file_docstrings_counted(self, py_file: Path) -> tuple[int, list[str]]:
+        """Check docstrings in a single Python file.
+
+        Returns:
+            A tuple of (total_public_items, missing_items) where
+            *total_public_items* is the count of public items inspected
+            and *missing_items* is the list of items without docstrings.
+        """
+        tree = parse_file(py_file)
+        if tree is None:
+            return 0, []
+        missing: list[str] = []
+        total = 0
+
+        # Check module docstring
+        total += 1
+        if not ast.get_docstring(tree):
+            missing.append(f"{py_file.name}: module")
+
+        for node in ast.walk(tree):
+            # Check class docstrings
+            if isinstance(node, ast.ClassDef):
+                if not node.name.startswith("_"):
+                    total += 1
+                    if not ast.get_docstring(node):
+                        missing.append(f"{py_file.name}: class {node.name}")
+
+            # Check function docstrings
+            elif isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                if not node.name.startswith("_"):
+                    total += 1
+                    if not ast.get_docstring(node):
+                        missing.append(f"{py_file.name}: function {node.name}")
+
+        return total, missing

pycmdcheck/checks/doctests.py

@@ -0,0 +1,129 @@
+"""Doctest execution check.
+
+Runs doctests embedded in module docstrings using pytest's
+``--doctest-modules`` flag.
+"""
+
+import logging
+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, tool_available
+
+logger = logging.getLogger(__name__)
+
+
+class DoctestsCheck(BaseCheck):
+    """Run doctests via pytest --doctest-modules.
+
+    Executes all doctests embedded in module docstrings and reports
+    failures.
+
+    Attributes:
+        name: The check identifier ("doctests").
+        description: Human-readable description of this check.
+    """
+
+    name = "doctests"
+    description = "Run doctests in package modules"
+
+    def run(self, package_path: Path, config: dict[str, Any]) -> CheckResult:
+        """Run doctests for the package.
+
+        Args:
+            package_path: Path to the package directory to check.
+            config: Configuration dictionary for this check.
+                Supports ``args`` (list[str]) for additional pytest args
+                and ``timeout`` (int) to override default.
+
+        Returns:
+            A CheckResult with:
+
+            - OK status if all doctests pass or no doctests found
+            - WARNING status if some doctests fail
+            - ERROR status if doctest runner failed to execute
+            - SKIPPED status if pytest is not installed
+        """
+        if not tool_available("pytest"):
+            return CheckResult(
+                name=self.name,
+                status=CheckStatus.SKIPPED,
+                message="pytest not installed",
+                details=["Install pytest to run doctests"],
+            )
+
+        # Find the package source directory
+        src_dir = package_path / "src"
+        target = src_dir if src_dir.is_dir() else package_path
+
+        timeout = config.get("timeout", DEFAULT_TIMEOUT)
+        extra_args = config.get("args", [])
+
+        cmd = [
+            "pytest",
+            "--doctest-modules",
+            "--tb=short",
+            "-q",
+            str(target),
+            *extra_args,
+        ]
+
+        details = ["Running: pytest --doctest-modules"]
+
+        result = run_tool(cmd, cwd=package_path, timeout=timeout)
+
+        if result.error:
+            return CheckResult(
+                name=self.name,
+                status=CheckStatus.ERROR,
+                message="Failed to run pytest for doctests",
+                details=[f"Error: {result.error}"],
+            )
+
+        if result.timed_out:
+            return CheckResult(
+                name=self.name,
+                status=CheckStatus.ERROR,
+                message="Doctest execution timed out",
+                details=[f"Timeout after {timeout}s"],
+            )
+
+        stdout = result.stdout or ""
+        lines = stdout.strip().splitlines()
+
+        # pytest exit code 5 means "no tests were collected" — for a package
+        # with no doctests this is success, not a failure.
+        if result.returncode == 5 or "no tests ran" in stdout.lower():
+            details.append("No doctests found in package modules")
+            return CheckResult(
+                name=self.name,
+                status=CheckStatus.OK,
+                message="No doctests found",
+                details=details,
+            )
+
+        if result.returncode == 0:
+            details.append("All doctests passed")
+            return CheckResult(
+                name=self.name,
+                status=CheckStatus.OK,
+                message="All doctests passed",
+                details=details,
+            )
+
+        # Doctests failed — extract failure info
+        failed_lines = [ln for ln in lines if "FAILED" in ln or "ERROR" in ln]
+        details.extend(failed_lines[:MAX_DETAIL_LINES])
+        if len(failed_lines) > MAX_DETAIL_LINES:
+            details.append(f"... and {len(failed_lines) - MAX_DETAIL_LINES} more")
+
+        fail_count = len(failed_lines) if failed_lines else "some"
+        return CheckResult(
+            name=self.name,
+            status=CheckStatus.WARNING,
+            message=f"{fail_count} doctest(s) failed",
+            details=details,
+        )

pycmdcheck/checks/formatting.py

@@ -0,0 +1,200 @@
+"""Code formatting check."""
+
+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.pyproject_reader import read_pyproject
+from pycmdcheck.results import CheckResult, CheckStatus
+from pycmdcheck.subprocess_runner import run_tool, sanitize_args, tool_available
+
+
+class FormattingCheck(BaseCheck):
+    """Check code formatting without modifying files."""
+
+    name = "formatting"
+    description = "Check code formatting (ruff format/black)"
+
+    SUPPORTED_TOOLS = ["ruff", "black"]
+
+    def run(self, package_path: Path, config: dict[str, Any]) -> CheckResult:
+        """Run formatting check.
+
+        The formatter defaults to ``"auto"``: the package's configured
+        formatter is detected from pyproject.toml / ``ruff.toml``. A package
+        that has not opted into a formatter is SKIPPED rather than being held
+        to one tool's default style (pyOpenSci does not mandate a specific
+        formatter).
+        """
+        tool = config.get("tool", "auto")
+
+        if tool == "auto":
+            detected = self._detect_formatter(package_path)
+            if detected is None:
+                return CheckResult(
+                    name=self.name,
+                    status=CheckStatus.SKIPPED,
+                    message="No formatter configured",
+                    details=[
+                        "No [tool.ruff]/[tool.black] config or ruff.toml found; "
+                        "skipping formatting check"
+                    ],
+                )
+            tool = detected
+
+        if tool not in self.SUPPORTED_TOOLS:
+            return CheckResult(
+                name=self.name,
+                status=CheckStatus.ERROR,
+                message=f"Unsupported formatting tool: {tool}",
+                details=[f"Supported tools: {', '.join(self.SUPPORTED_TOOLS)}"],
+            )
+
+        if tool == "ruff":
+            return self._run_ruff_format(package_path, config)
+        else:
+            return self._run_black(package_path, config)
+
+    @staticmethod
+    def _detect_formatter(package_path: Path) -> str | None:
+        """Detect the formatter a package has opted into, or ``None``.
+
+        Returns ``"ruff"`` if ``[tool.ruff]`` / ``ruff.toml`` is present,
+        ``"black"`` if ``[tool.black]`` is present, otherwise ``None``.
+        """
+        if (package_path / "ruff.toml").exists() or (
+            package_path / ".ruff.toml"
+        ).exists():
+            return "ruff"
+        data = read_pyproject(package_path)
+        tool_table = data.get("tool", {}) if data else {}
+        if "ruff" in tool_table:
+            return "ruff"
+        if "black" in tool_table:
+            return "black"
+        return None
+
+    def _run_ruff_format(
+        self, package_path: Path, config: dict[str, Any]
+    ) -> CheckResult:
+        """Run ruff format --check."""
+        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", []))
+        result = run_tool(
+            ["ruff", "format", "--check", ".", *args],
+            cwd=package_path,
+            timeout=DEFAULT_TIMEOUT,
+        )
+
+        if result.timed_out:
+            return CheckResult(
+                name=self.name,
+                status=CheckStatus.ERROR,
+                message="Formatting check timed out",
+            )
+        if result.error is not None:
+            return CheckResult(
+                name=self.name,
+                status=CheckStatus.ERROR,
+                message="Failed to run ruff format",
+                details=[result.error],
+            )
+        if result.success:
+            return CheckResult(
+                name=self.name,
+                status=CheckStatus.OK,
+                message="Code is properly formatted",
+                details=["Using formatter: ruff"],
+            )
+
+        # Files need reformatting
+        lines = result.output_lines()
+        reformat_lines = [ln for ln in lines if "would reformat" in ln.lower()]
+        file_count = len(reformat_lines)
+        details = ["Using formatter: ruff"]
+        if reformat_lines:
+            details.extend(reformat_lines[:MAX_DETAIL_LINES])
+            if file_count > MAX_DETAIL_LINES:
+                details.append(f"... and {file_count - MAX_DETAIL_LINES} more files")
+        else:
+            # Tool failed but output doesn't list specific files
+            details.extend(lines[:MAX_DETAIL_LINES])
+
+        return CheckResult(
+            name=self.name,
+            status=CheckStatus.WARNING,
+            message=(
+                f"{file_count} file(s) need reformatting"
+                if file_count
+                else "Code formatting issues found"
+            ),
+            details=details,
+        )
+
+    def _run_black(self, package_path: Path, config: dict[str, Any]) -> CheckResult:
+        """Run black --check."""
+        if not tool_available("black"):
+            return CheckResult(
+                name=self.name,
+                status=CheckStatus.SKIPPED,
+                message="black not installed",
+                details=["Install black: pip install black"],
+            )
+
+        args = sanitize_args(config.get("args", []))
+        result = run_tool(
+            ["black", "--check", ".", *args],
+            cwd=package_path,
+            timeout=DEFAULT_TIMEOUT,
+        )
+
+        if result.timed_out:
+            return CheckResult(
+                name=self.name,
+                status=CheckStatus.ERROR,
+                message="Formatting check timed out",
+            )
+        if result.error is not None:
+            return CheckResult(
+                name=self.name,
+                status=CheckStatus.ERROR,
+                message="Failed to run black",
+                details=[result.error],
+            )
+        if result.success:
+            return CheckResult(
+                name=self.name,
+                status=CheckStatus.OK,
+                message="Code is properly formatted",
+                details=["Using formatter: black"],
+            )
+
+        lines = result.output_lines()
+        reformat_lines = [ln for ln in lines if "would reformat" in ln.lower()]
+        file_count = len(reformat_lines)
+        details = ["Using formatter: black"]
+        if reformat_lines:
+            details.extend(reformat_lines[:MAX_DETAIL_LINES])
+            if file_count > MAX_DETAIL_LINES:
+                details.append(f"... and {file_count - MAX_DETAIL_LINES} more files")
+        else:
+            details.extend(lines[:MAX_DETAIL_LINES])
+
+        return CheckResult(
+            name=self.name,
+            status=CheckStatus.WARNING,
+            message=(
+                f"{file_count} file(s) need reformatting"
+                if file_count
+                else "Code formatting issues found"
+            ),
+            details=details,
+        )