py-wlcli 0.8.0__py3-none-any.whl

wl_cli/commands/testcommands/coverage_analyzer.py

@@ -0,0 +1,955 @@
+"""Coverage analyzer module for analyzing test coverage and generating improvement suggestions."""
+
+import ast
+import configparser
+import fnmatch
+import json
+import os
+import subprocess
+import tempfile
+from collections.abc import Iterator
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import tomllib
+
+from .test_utils import _probe_pytest_cov
+
+# pytest's default test-module patterns: a basename matching neither can never
+# be collected as a test module, whatever symbols it defines.
+_PYTEST_PYTHON_FILES = ("test_*.py", "*_test.py")
+
+# Files pytest reads for its configuration, in pytest's own precedence order.
+_PYTEST_CONFIG_FILES = ("pytest.ini", "pyproject.toml", "tox.ini", "setup.cfg")
+
+# Directories whose contents can never be coverage inputs (or sources): tool
+# caches and virtualenvs are neither executed by pytest nor part of the tree.
+_PRUNED_DIRECTORY_NAMES = frozenset(
+    {
+        ".git",
+        ".mypy_cache",
+        ".pytest_cache",
+        ".ruff_cache",
+        ".tox",
+        ".venv",
+        "__pycache__",
+        "build",
+        "dist",
+        "node_modules",
+        "venv",
+    }
+)
+
+
+def _read_pytest_options(project_root: Path) -> dict[str, list[str]]:
+    """Read ``testpaths`` from the config file pytest itself would load.
+
+    Follows pytest's precedence (``pytest.ini`` > ``pyproject.toml`` >
+    ``tox.ini`` > ``setup.cfg``) and stops at the first file that carries a
+    pytest config section, whether or not that file sets ``testpaths``. That
+    is the file pytest reads, so a lower-priority ``testpaths`` is ignored by
+    the test run itself and must not steer coverage roots either (rv237
+    MEDIUM-1). Unreadable or unparsable configs are treated as absent: a
+    broken config must not stop a coverage run from reporting.
+
+    Only ``testpaths`` is read, because it is the only option this subsystem
+    consumes (:func:`pytest_test_roots`). Filename-collection patterns are not
+    parsed here: the source scanner uses pytest's fixed defaults, never a
+    configured pattern, so reading them would be dead data (rv192 NIT-1).
+    """
+    for filename in _PYTEST_CONFIG_FILES:
+        config_path = project_root / filename
+        if not config_path.is_file():
+            continue
+        options = _read_pytest_options_from(config_path)
+        if options is not None:
+            return options
+    return {}
+
+
+def _read_pytest_options_from(config_path: Path) -> dict[str, list[str]] | None:
+    """Parse ``testpaths`` from one config file; ``None`` if it is not a pytest config.
+
+    ``{}`` means the file *is* the config pytest would load but sets no
+    ``testpaths`` -- distinct from ``None``, where a lower-priority file still
+    gets a chance, exactly as pytest's own config discovery treats them.
+    """
+    if config_path.suffix == ".toml":
+        try:
+            data = tomllib.loads(config_path.read_text(encoding="utf-8"))
+        except (OSError, tomllib.TOMLDecodeError, UnicodeDecodeError):
+            return None
+        tool_section = data.get("tool")
+        if not isinstance(tool_section, dict):
+            return None
+        pytest_section = tool_section.get("pytest")
+        if not isinstance(pytest_section, dict):
+            return None
+        section = pytest_section.get("ini_options")
+        if not isinstance(section, dict):
+            return None
+        return {
+            str(key): _as_option_values(value)
+            for key, value in section.items()
+            if key == "testpaths"
+        }
+
+    section_name = "tool:pytest" if config_path.name == "setup.cfg" else "pytest"
+    parser = configparser.ConfigParser(strict=False)
+    try:
+        parser.read(config_path, encoding="utf-8")
+    except (OSError, configparser.Error, UnicodeDecodeError):
+        return None
+    if not parser.has_section(section_name):
+        # pytest.ini is always the config source, even without a [pytest]
+        # section; tox.ini and setup.cfg only count when it is present.
+        return {} if config_path.name == "pytest.ini" else None
+    return {
+        key: _as_option_values(raw)
+        for key, raw in parser.items(section_name)
+        if key == "testpaths"
+    }
+
+
+def _as_option_values(value: Any) -> list[str]:
+    """Normalise a config option value (list or newline/comma string) to a list."""
+    if isinstance(value, (list, tuple)):
+        return [str(item).strip() for item in value if str(item).strip()]
+    return [
+        part.strip()
+        for line in str(value).splitlines()
+        for part in line.split(",")
+        if part.strip()
+    ]
+
+
+def pytest_test_roots(project_root: Path) -> list[Path]:
+    """Directories ``run_coverage`` hands to pytest, in the project's own terms.
+
+    ``testpaths`` from the config file pytest itself would load when it sets
+    them; otherwise ``tests/`` when it exists. An empty list means the project
+    declares no test tree, and the caller keeps pytest's own argument
+    behaviour.
+    """
+    options = _read_pytest_options(project_root)
+    roots = [project_root / raw for raw in options.get("testpaths", []) if raw.strip()]
+    roots = [root for root in roots if root.is_dir()]
+    if roots:
+        return roots
+    default_root = project_root / "tests"
+    return [default_root] if default_root.is_dir() else []
+
+
+def _iter_files(root: Path, pattern: str) -> Iterator[Path]:
+    """Yield files under ``root`` matching ``pattern``, skipping tool caches."""
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = sorted(
+            name for name in dirnames if name not in _PRUNED_DIRECTORY_NAMES
+        )
+        for filename in sorted(filenames):
+            if fnmatch.fnmatchcase(filename, pattern):
+                yield Path(dirpath) / filename
+
+
+def detect_source_packages(project_root: Path) -> list[Path]:
+    """Source package directories under the project's ``src/`` root.
+
+    Initialised packages (a directory with ``__init__.py``) win; a layout that
+    only has plain directories with modules (namespace packages, or a tree
+    without ``__init__.py``) falls back to those. This is what the coverage
+    target and the source-to-test mapping resolve against -- never a hardcoded
+    ``wl_cli``.
+    """
+    source_root = project_root / "src"
+    if not source_root.is_dir():
+        return []
+    candidates = [
+        path
+        for path in sorted(source_root.iterdir())
+        if path.is_dir()
+        and not path.name.startswith((".", "_"))
+        and path.name != "tests"
+    ]
+    initialised = [path for path in candidates if (path / "__init__.py").is_file()]
+    if initialised:
+        return initialised
+    return [path for path in candidates if any(path.rglob("*.py"))]
+
+
+def coverage_targets(project_root: Path) -> list[str]:
+    """``--cov`` targets for the project, resolved from its actual layout.
+
+    Package names when ``src/<pkg>`` exists (the form ``pytest --cov`` accepts
+    as module names), then the ``src`` directory itself (a path target
+    pytest-cov measures recursively), then ``.`` so a project with neither
+    still gets a report instead of silently measuring the hardcoded
+    ``wl_cli``.
+    """
+    packages = detect_source_packages(project_root)
+    if packages:
+        return [package.name for package in packages]
+    if (project_root / "src").is_dir():
+        return ["src"]
+    return ["."]
+
+
+def collect_coverage_inputs(project_root: Path) -> list[Path]:
+    """The Python files whose change can invalidate collected coverage data.
+
+    Deliberately wider than the source-to-test one-to-one mapping: that
+    mapping names at most one test module per source file, while
+    :meth:`CoverageAnalyzer.run_coverage` executes the *whole* test tree. The
+    cache key and the freshness check must cover what actually ran, so this
+    returns all Python modules under the resolved test roots, every
+    ``conftest.py`` below the project root, and the pytest configuration
+    files this analyzer recognises: ``pytest.ini``, ``pyproject.toml`` (its
+    ``[tool.pytest.ini_options]`` table only), ``tox.ini``, and ``setup.cfg``.
+    Any other config form (``pytest.toml``, ``.pytest.ini``, a bare
+    ``[tool.pytest]`` table) is not recognised and is treated as no
+    configuration at all: it is not tracked here and contributes no
+    ``testpaths``.
+
+    Every ``.py`` file under the resolved test roots is in scope, whether or
+    not pytest can import it: a syntactically broken helper still changes what
+    runs. Known boundary: non-Python fixtures (for example
+    ``tests/data/*.json``) are not tracked, so changing one does not
+    invalidate cached coverage.
+    """
+    inputs: set[Path] = set()
+    for test_root in pytest_test_roots(project_root):
+        inputs.update(_iter_files(test_root, "*.py"))
+    inputs.update(_iter_files(project_root, "conftest.py"))
+    for filename in _PYTEST_CONFIG_FILES:
+        config_path = project_root / filename
+        if config_path.is_file():
+            inputs.add(config_path)
+    return sorted(inputs)
+
+
+def _is_click_decorator(decorator: ast.expr) -> bool:
+    """Whether a decorator is Click's ``command`` or ``group``.
+
+    Covers ``@click.command()`` / ``@click.group()``, the
+    ``from click import command`` spelling, and the stacked form where other
+    decorators (``@click.option(...)``) sit above or below it.
+    """
+    target = decorator.func if isinstance(decorator, ast.Call) else decorator
+    if isinstance(target, ast.Name):
+        return target.id in {"command", "group"}
+    if not isinstance(target, ast.Attribute):
+        return False
+    if target.attr not in {"command", "group"}:
+        return False
+    root: ast.expr = target.value
+    while isinstance(root, ast.Attribute):
+        root = root.value
+    return isinstance(root, ast.Name) and root.id == "click"
+
+
+@dataclass
+class CoverageStats:
+    """Statistics for a single file's coverage."""
+
+    filename: str
+    covered_lines: int
+    total_lines: int
+    coverage_percent: float
+    uncovered_lines: list[int]
+    uncovered_ranges: list[tuple[int, int]]
+
+
+@dataclass
+class CoverageSuggestion:
+    """Suggestion for improving coverage."""
+
+    filename: str
+    line_start: int
+    line_end: int
+    suggestion: str
+    suggestion_zh: str
+    severity: str  # low, medium, high
+
+
+class CoverageAnalyzer:
+    """Analyzes test coverage and generates improvement suggestions."""
+
+    def __init__(self, project_root: Path):
+        """Initialize coverage analyzer.
+
+        Args:
+            project_root: Root directory of the project
+        """
+        self.project_root = project_root
+        self.coverage_data: dict[str, Any] = {}
+        self.source_files: list[Path] = []
+        # Resolved once: the project's own packages, test roots and the files
+        # whose change invalidates a coverage report. Never a hardcoded
+        # ``wl_cli`` / ``tests`` pair (#192).
+        self.source_packages: list[Path] = detect_source_packages(project_root)
+        self.test_roots: list[Path] = pytest_test_roots(project_root)
+
+    def coverage_inputs(self) -> list[Path]:
+        """Files whose change must invalidate cached / on-disk coverage data."""
+        return collect_coverage_inputs(self.project_root)
+
+    def _coverage_cov_arguments(self) -> list[str]:
+        """``--cov=`` arguments for this project's layout."""
+        return [f"--cov={target}" for target in coverage_targets(self.project_root)]
+
+    def set_coverage_data(self, coverage_data: dict[str, Any]):
+        """Set coverage data directly from memory.
+
+        Args:
+            coverage_data: Coverage data dictionary in pytest-cov JSON format
+        """
+        self.coverage_data = coverage_data
+
+    def _find_source_files(self) -> list[Path]:
+        """Find all Python source files in the project.
+
+        Test modules are recognised the way pytest recognises them, not by a
+        ``test`` substring in the file name (#182): a file is an inline test
+        module only when pytest could collect it -- its basename matches
+        pytest's default test-file patterns (``test_*.py`` / ``*_test.py``)
+        *and* it defines a top-level ``test_*`` plain function. So
+        ``test_utils.py``,
+        ``buildcommands/test.py`` and ``gate/preflight.py`` stay in the list
+        even when they carry a ``test_*`` symbol, and a Click command named
+        ``test_command`` does not turn a production module into a test one.
+
+        A file is skipped when it is an ``__init__.py``, when any part of its
+        path below ``project_root`` is a ``tests`` directory, or when it is an
+        inline test module by the rule above.
+        """
+        source_dir = self.project_root / "src"
+        if not source_dir.exists():
+            return []
+
+        source_files = []
+        for py_file in source_dir.rglob("*.py"):
+            if py_file.name == "__init__.py":
+                continue
+            if "tests" in self._parts_below_project_root(py_file):
+                continue
+            if self._is_inline_test_module(py_file):
+                continue
+            source_files.append(py_file)
+
+        return sorted(source_files)
+
+    def _parts_below_project_root(self, py_file: Path) -> tuple[str, ...]:
+        """Path components of ``py_file`` relative to the project root.
+
+        Falls back to the absolute components when the file is not under the
+        project root (only reachable for symlinked or moved trees).
+        """
+        try:
+            return py_file.relative_to(self.project_root).parts
+        except ValueError:
+            return py_file.parts
+
+    @classmethod
+    def _is_inline_test_module(cls, py_file: Path) -> bool:
+        """Whether ``py_file`` is a module pytest would collect tests from.
+
+        Both halves are required (#182 review): a collectable basename --
+        ``gate/preflight.py``'s ``test_interpreter`` once hid a 434-line
+        production module -- and a top-level ``test_*`` that pytest would
+        actually run, so ``test_commands.py``'s ``@click.command()`` is not a
+        test function.
+        """
+        if not any(
+            fnmatch.fnmatchcase(py_file.name, pattern)
+            for pattern in _PYTEST_PYTHON_FILES
+        ):
+            return False
+        return cls._defines_plain_test_function(py_file)
+
+    @staticmethod
+    def _defines_plain_test_function(py_file: Path) -> bool:
+        """Whether the module has a top-level, non-Click ``test_*`` function.
+
+        Files that cannot be read or parsed are treated as regular source,
+        never silently dropped.
+        """
+        try:
+            tree = ast.parse(py_file.read_bytes(), filename=str(py_file))
+        except (OSError, SyntaxError, ValueError):
+            return False
+
+        for node in tree.body:
+            if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                continue
+            if not node.name.startswith("test_"):
+                continue
+            if any(_is_click_decorator(decorator) for decorator in node.decorator_list):
+                continue
+            return True
+        return False
+
+    def run_coverage(
+        self,
+        python_executable: str,
+        output_path: Path | str | None = None,
+        step_by_step: bool = False,
+    ) -> dict | None:
+        """Run pytest with coverage collection.
+
+        Args:
+            python_executable: Path to Python executable
+            output_path: Where to write the coverage JSON report. Defaults to
+                ``todos/coverage.json`` when not provided.
+            step_by_step: Whether to run in step-by-step mode
+
+        Returns:
+            Parsed coverage data dictionary on success, or None when
+            pytest-cov is unavailable, pytest fails, or the coverage JSON is
+            missing or unparsable.
+        """
+        if output_path is None:
+            coverage_json_path = self.project_root / "todos" / "coverage.json"
+        else:
+            coverage_json_path = Path(output_path)
+        coverage_json_path.parent.mkdir(parents=True, exist_ok=True)
+        if coverage_json_path.exists():
+            coverage_json_path.unlink()
+
+        if not self._check_pytest_cov_available(python_executable):
+            return None
+
+        # The test tree and the covered package both come from the project's
+        # own layout/config (#192): ``tests/`` + ``--cov=wl_cli`` only describe
+        # this repository, not every project that runs ``wl test --cover``.
+        test_paths = [str(root) for root in self.test_roots] or ["tests/"]
+        cmd_args = [
+            python_executable,
+            "-m",
+            "pytest",
+            *test_paths,
+            *self._coverage_cov_arguments(),
+            "--cov-branch",
+            "--cov-context=test",
+            f"--cov-report=json:{coverage_json_path}",
+            "--no-cov-on-fail",
+            "-q",
+        ]
+
+        if step_by_step:
+            # In step-by-step mode, capture all output and show progress
+            # First, collect test count
+            collect_cmd = cmd_args + ["--collect-only"]
+            collect_result = subprocess.run(
+                collect_cmd,
+                cwd=self.project_root,
+                check=False,
+                capture_output=True,
+                text=True,
+            )
+
+            test_count = 0
+            if collect_result.stdout:
+                import re
+
+                match = re.search(r"collected\s+(\d+)\s+items", collect_result.stdout)
+                if match:
+                    test_count = int(match.group(1))
+
+            # Show progress bar and run tests
+            if test_count > 0:
+                from tqdm import tqdm
+
+                with tqdm(
+                    total=test_count,
+                    unit="test",
+                    dynamic_ncols=True,
+                    bar_format="{l_bar}{bar}| {n_fmt}/{total_fmt} [{elapsed}<{remaining}]",
+                    desc="Running tests",
+                ) as pbar:
+                    # Run tests and capture output
+                    result = subprocess.run(
+                        cmd_args,
+                        cwd=self.project_root,
+                        check=False,
+                        capture_output=True,
+                        text=True,
+                    )
+
+                    # Update progress bar to 100%
+                    pbar.update(test_count)
+            else:
+                # Fall back if can't parse test count
+                result = subprocess.run(
+                    cmd_args,
+                    cwd=self.project_root,
+                    check=False,
+                    capture_output=True,
+                    text=True,
+                )
+
+            # Show test failure output only if there was an error
+            if result.returncode != 0:
+                print("[Coverage] Tests failed during coverage collection:")
+                if result.stdout:
+                    print(
+                        result.stdout[-2000:]
+                        if len(result.stdout) > 2000
+                        else result.stdout
+                    )
+                if result.stderr:
+                    print(
+                        result.stderr[-1000:]
+                        if len(result.stderr) > 1000
+                        else result.stderr
+                    )
+        else:
+            # Normal mode: capture output to match the pre-#39 runner UX (no
+            # live pytest chatter); on failure show the tail of pytest stderr.
+            result = subprocess.run(
+                cmd_args,
+                cwd=self.project_root,
+                check=False,
+                capture_output=True,
+                text=True,
+            )
+
+            if result.returncode != 0 and result.stderr:
+                print("Last 20 lines of pytest stderr:")
+                print("\n".join(result.stderr.splitlines()[-20:]))
+
+        return self._read_coverage_json(coverage_json_path)
+
+    def run_coverage_for_file(
+        self,
+        python_executable: str,
+        source_file: Path,
+        fail_under: float = 0.0,
+        output_path: Path | str | None = None,
+    ) -> bool:
+        """Run pytest with coverage collection for a single source file.
+
+        The per-file coverage JSON is written to a temporary file (or the
+        provided ``output_path``) so the main coverage JSON is never
+        overwritten. The measured coverage percentage for ``source_file`` is
+        compared against ``fail_under``.
+
+        Args:
+            python_executable: Path to Python executable
+            source_file: Path to the source file to test
+            fail_under: Coverage percentage threshold. Defaults to ``0.0`` so a
+                plain call reports whether coverage was collected at all.
+            output_path: Where to write the per-file coverage JSON. Defaults to
+                a temporary file when not provided.
+
+        Returns:
+            True when coverage was collected and the file's measured coverage
+            is at or above ``fail_under``. False on any error or shortfall.
+        """
+        # Find corresponding test file
+        test_file = self._find_test_file(source_file)
+        if not test_file:
+            return False
+
+        if output_path is None:
+            owns_temp_path = True
+            temp_file = tempfile.NamedTemporaryFile(suffix=".json", delete=False)
+            coverage_json_path = Path(temp_file.name)
+            temp_file.close()
+        else:
+            owns_temp_path = False
+            coverage_json_path = Path(output_path)
+            coverage_json_path.parent.mkdir(parents=True, exist_ok=True)
+            if coverage_json_path.exists():
+                coverage_json_path.unlink()
+
+        try:
+            # Build command with specific test file
+            cmd_args = [
+                python_executable,
+                "-m",
+                "pytest",
+                str(test_file),
+                *self._coverage_cov_arguments(),
+                "--cov-branch",
+                "--cov-context=test",
+                f"--cov-report=json:{coverage_json_path}",
+                "--no-cov-on-fail",
+                "-q",
+            ]
+
+            result = subprocess.run(
+                cmd_args,
+                cwd=self.project_root,
+                check=False,
+                capture_output=True,
+                text=True,
+            )
+
+            if result.returncode != 0:
+                return False
+
+            coverage_data = self._read_coverage_json(coverage_json_path)
+            if coverage_data is None:
+                return False
+
+            stats = self._parse_coverage_for_file(source_file)
+            if stats is None:
+                return False
+            return stats.coverage_percent >= fail_under
+        finally:
+            if owns_temp_path:
+                coverage_json_path.unlink(missing_ok=True)
+
+    def _read_coverage_json(self, path: Path) -> dict | None:
+        """Read and parse a coverage JSON report.
+
+        Args:
+            path: Path to the coverage JSON report
+
+        Returns:
+            Parsed dictionary, or None when missing, empty, or unparsable.
+        """
+        if not path.exists():
+            return None
+        try:
+            content = path.read_text()
+            if not content.strip():
+                return None
+            data = json.loads(content)
+            if not isinstance(data, dict):
+                return None
+            self.coverage_data = data
+            return data
+        except (OSError, json.JSONDecodeError):
+            return None
+
+    def _check_pytest_cov_available(self, python_executable: str) -> bool:
+        """pytest-cov 是否可被**执行 pytest 的那个解释器**导入。
+
+        `run_coverage` 用传入的 `python_executable` 起 pytest，判定就必须问同一
+        个解释器：只在 wl 进程内 `__import__` 时，`--cover` 会按 wl 的环境决定
+        是否传 `--cov*` —— 两者不一致时要么漏跑 coverage，要么把 pytest 认不出
+        的 flag 交给子进程。此处不做缓存（一次 `--cover` 只探一次）。
+
+        执行用 env 未显式传给子进程（`subprocess.run` 不带 `env=`），故探针同样
+        只传解释器：判定的环境与执行的环境一致。
+
+        探针本体是 `test_utils._probe_pytest_cov`（#112 起三处入口共用）。
+        """
+        if _probe_pytest_cov(python_executable):
+            return True
+        print(
+            "[Coverage] pytest-cov is not installed. Install with: "
+            "pip install py_wlcli[test]"
+        )
+        return False
+
+    def _find_test_file(self, source_file: Path) -> Path | None:
+        """Find the corresponding test file for a source file.
+
+        Args:
+            source_file: Path to the source file
+
+        Returns:
+            Path to the test file if found, None otherwise
+        """
+        # Locate the source package this project actually ships instead of the
+        # hardcoded ``src/wl_cli`` (#192).
+        rel_path: Path | None = None
+        for package_dir in self.source_packages:
+            try:
+                rel_path = source_file.relative_to(package_dir)
+            except ValueError:
+                continue
+            break
+        if rel_path is None:
+            return None
+
+        # Build test file path under the project's own test root
+        test_root = (
+            self.test_roots[0] if self.test_roots else self.project_root / "tests"
+        )
+        test_path = test_root / rel_path
+        test_path = test_path.with_name(f"test_{test_path.name}")
+
+        if test_path.exists():
+            return test_path
+
+        # Try alternative test locations
+        alternatives = [
+            test_root / "testcommands" / f"test_{source_file.name}",
+            test_root / f"test_{source_file.name}",
+        ]
+
+        for alt_path in alternatives:
+            if alt_path.exists():
+                return alt_path
+
+        return None
+
+    def _parse_coverage_for_file(
+        self, file_path: Path, file_lines: list[str] | None = None
+    ) -> CoverageStats | None:
+        """Parse coverage data for a single file.
+
+        Args:
+            file_path: Path to the source file
+            file_lines: Pre-read file content (for performance optimization)
+
+        Returns:
+            CoverageStats if file was found in coverage data, None otherwise
+        """
+        file_key = str(file_path.resolve())
+
+        # Try different path formats
+        files_data = self.coverage_data.get("files", {})
+        if file_key not in files_data:
+            # Try relative path (normalize to forward slashes for cross-platform compatibility)
+            rel_path = file_path.relative_to(self.project_root)
+            file_key = str(rel_path).replace("\\", "/")
+
+        if file_key not in files_data:
+            return None
+
+        file_data = self.coverage_data["files"][file_key]
+        lines = file_data.get("executed_lines", [])
+        missing = file_data.get("missing_lines", [])
+        excluded = file_data.get("excluded_lines", [])
+        summary = file_data.get("summary", {})
+
+        total_lines = int(summary.get("num_statements") or 0)
+        if total_lines == 0:
+            total_lines = int(summary.get("num_lines") or 0)
+        if total_lines == 0:
+            if file_lines is not None:
+                total_lines = len(file_lines)
+            else:
+                try:
+                    with open(file_path) as f:
+                        total_lines = len(f.readlines())
+                except Exception:
+                    total_lines = 0
+
+        covered_lines = int(summary.get("covered_lines") or len(lines))
+        uncovered_lines = sorted(set(missing) - set(excluded))
+
+        summary_percent = summary.get("percent_covered")
+        if summary_percent is not None:
+            coverage_percent = float(summary_percent)
+        elif total_lines > 0:
+            coverage_percent = (covered_lines / total_lines) * 100
+        else:
+            coverage_percent = 0.0
+
+        # Group uncovered lines into ranges
+        uncovered_ranges = self._group_lines_into_ranges(uncovered_lines)
+
+        return CoverageStats(
+            filename=str(file_path.relative_to(self.project_root)),
+            covered_lines=covered_lines,
+            total_lines=total_lines,
+            coverage_percent=coverage_percent,
+            uncovered_lines=uncovered_lines,
+            uncovered_ranges=uncovered_ranges,
+        )
+
+    def _group_lines_into_ranges(self, lines: list[int]) -> list[tuple[int, int]]:
+        """Group consecutive lines into ranges.
+
+        Args:
+            lines: Sorted list of line numbers
+
+        Returns:
+            List of (start, end) tuples representing ranges
+        """
+        if not lines:
+            return []
+
+        ranges = []
+        start = lines[0]
+        end = lines[0]
+
+        for line in lines[1:]:
+            if line == end + 1:
+                end = line
+            else:
+                ranges.append((start, end))
+                start = line
+                end = line
+
+        ranges.append((start, end))
+        return ranges
+
+    def analyze_file(
+        self, file_path: Path
+    ) -> tuple[CoverageStats, list[CoverageSuggestion]]:
+        """Analyze coverage for a single file and generate suggestions.
+
+        Args:
+            file_path: Path to the source file
+
+        Returns:
+            Tuple of CoverageStats and list of CoverageSuggestion
+        """
+        # Read file content once and reuse to avoid multiple file I/O operations
+        try:
+            with open(file_path) as f:
+                file_lines = f.readlines()
+        except Exception:
+            file_lines = []
+
+        stats = self._parse_coverage_for_file(file_path, file_lines)
+        if stats is None:
+            # Create empty stats if no coverage data found
+            stats = CoverageStats(
+                filename=str(file_path.relative_to(self.project_root)),
+                covered_lines=0,
+                total_lines=len(file_lines),
+                coverage_percent=0.0,
+                uncovered_lines=[],
+                uncovered_ranges=[],
+            )
+
+        suggestions = self._generate_suggestions(file_path, stats, file_lines)
+        return stats, suggestions
+
+    def _generate_suggestions(
+        self, file_path: Path, stats: CoverageStats, file_lines: list[str] | None = None
+    ) -> list[CoverageSuggestion]:
+        """Generate coverage improvement suggestions for a file.
+
+        Args:
+            file_path: Path to the source file
+            stats: Coverage statistics for the file
+            file_lines: Pre-read file content (for performance optimization)
+
+        Returns:
+            List of coverage improvement suggestions
+        """
+        suggestions: list[CoverageSuggestion] = []
+
+        if not stats.uncovered_ranges:
+            return suggestions
+
+        # Get file lines from pre-read content or read file
+        if file_lines is None:
+            try:
+                with open(file_path) as f:
+                    file_lines = f.readlines()
+            except Exception:
+                return suggestions
+
+        for start, end in stats.uncovered_ranges:
+            # Extract the code snippet
+            snippet = ""
+            for i in range(max(0, start - 1), min(len(file_lines), end)):
+                snippet += file_lines[i]
+
+            suggestion, suggestion_zh, severity = self._analyze_code_snippet(
+                file_path.name, start, end, snippet
+            )
+
+            suggestions.append(
+                CoverageSuggestion(
+                    filename=stats.filename,
+                    line_start=start,
+                    line_end=end,
+                    suggestion=suggestion,
+                    suggestion_zh=suggestion_zh,
+                    severity=severity,
+                )
+            )
+
+        return suggestions
+
+    def _analyze_code_snippet(
+        self, filename: str, start: int, end: int, snippet: str
+    ) -> tuple[str, str, str]:
+        """Analyze a code snippet to generate a specific suggestion.
+
+        Args:
+            filename: Name of the file
+            start: Starting line number
+            end: Ending line number
+            snippet: The code snippet to analyze
+
+        Returns:
+            Tuple of (suggestion_en, suggestion_zh, severity)
+        """
+        lines = snippet.strip().split("\n")
+
+        # Detect function definitions
+        for line in lines:
+            if line.strip().startswith("def "):
+                func_name = line.strip()[4:].split("(")[0].strip()
+                suggestion = f"Function '{func_name}' (lines {start}-{end}) is not covered by tests"
+                suggestion_zh = f"函数 '{func_name}'（第 {start}-{end} 行）没有测试覆盖"
+                severity = "high"
+                return suggestion, suggestion_zh, severity
+
+            if line.strip().startswith("class "):
+                class_name = line.strip()[6:].split("(")[0].strip()
+                suggestion = (
+                    f"Class '{class_name}' (lines {start}-{end}) is not fully covered"
+                )
+                suggestion_zh = f"类 '{class_name}'（第 {start}-{end} 行）未完全覆盖"
+                severity = "high"
+                return suggestion, suggestion_zh, severity
+
+            if "except " in line or "try:" in line:
+                suggestion = (
+                    f"Exception handling block (lines {start}-{end}) is not covered"
+                )
+                suggestion_zh = f"异常处理块（第 {start}-{end} 行）没有测试覆盖"
+                severity = "medium"
+                return suggestion, suggestion_zh, severity
+
+            if "if " in line or "elif " in line:
+                suggestion = f"Conditional branch (lines {start}-{end}) is not covered"
+                suggestion_zh = f"条件分支（第 {start}-{end} 行）没有测试覆盖"
+                severity = "medium"
+                return suggestion, suggestion_zh, severity
+
+        # Default suggestion
+        suggestion = f"Code block (lines {start}-{end}) is not covered by tests"
+        suggestion_zh = f"代码块（第 {start}-{end} 行）没有测试覆盖"
+        severity = "low"
+
+        return suggestion, suggestion_zh, severity
+
+    def get_overall_stats(self) -> dict[str, Any]:
+        """Get overall coverage statistics for the project.
+
+        Returns:
+            Dictionary with overall coverage statistics
+        """
+        if not self.coverage_data:
+            return {
+                "total_covered": 0,
+                "total_lines": 0,
+                "overall_percent": 0.0,
+                "files_analyzed": 0,
+            }
+
+        files_data = self.coverage_data.get("files", {})
+        total_covered = 0
+        total_lines = 0
+
+        for _file_key, file_data in files_data.items():
+            if "summary" in file_data:
+                # Ensure integer conversion
+                covered = file_data["summary"].get("covered_lines", 0)
+                statements = file_data["summary"].get("num_statements", 0)
+                total_covered += int(covered) if covered else 0
+                total_lines += int(statements) if statements else 0
+
+        overall_percent = (
+            (total_covered / total_lines) * 100 if total_lines > 0 else 0.0
+        )
+
+        return {
+            "total_covered": total_covered,
+            "total_lines": total_lines,
+            "overall_percent": float(overall_percent),
+            "files_analyzed": len(files_data),
+        }