py-wlcli 0.8.0__py3-none-any.whl

wl_cli/commands/lint/lint_reporter.py

@@ -0,0 +1,579 @@
+"""Lint reporter module.
+Handles report generation for lint command.
+
+Rendering only (#170): :meth:`LintReporter.render` reads a finished
+:class:`~wl_cli.commands.lint.lint_run.LintRun` and writes the report files.
+It starts no child process -- the executor has already run each tool exactly
+once -- so the content cannot disagree with the verdict, and the number of
+executions is visible in one place.
+
+Freshness contract (#200): every report file :meth:`LintReporter.render`
+writes carries a ``- Generated at: <ISO-8601>`` line naming the run that wrote
+it. Two rounds over the same scope with the same findings therefore differ in
+that line even though every other byte is identical -- before this, a report
+could only be shown to be "this run's" by asserting the run wrote it, and two
+such reports compared byte-for-byte. The stamp is computed once per
+:meth:`render` call, so every file of one run names the same moment. It is a
+timestamp rather than a random id so the report also answers *when* it was
+produced; two runs inside the same microsecond would share it, which is the
+one residual ambiguity in the contract.
+"""
+
+import re
+from datetime import datetime
+from pathlib import Path
+
+from ...utils.logging import log_info_pair
+from ...utils.pre_commit import PreCommitRun
+from .lint_run import LintRun, RuffBlock, display_path
+
+#: The mypy scopes ``error.md`` reports on separately. One mypy run covers
+#: both; the output is split by these path prefixes.
+_MYPY_SCOPES = ("src/", "tests/")
+
+
+def _run_stamp(generated_at: datetime | None = None) -> str:
+    """The run stamp a report carries: ``generated_at`` or the current moment.
+
+    Microseconds, not seconds, are what makes two consecutive runs
+    distinguishable; the offset keeps the stamp unambiguous when the report
+    travels between machines (#200).
+
+    The only clock read this module performs: every report of one ``render``
+    call is passed the string it returns, so the files cannot disagree about
+    the moment. A naive ``generated_at`` is read as local wall time and given
+    the local offset (LOW-1) rather than emitting an offset-less ISO string
+    that reads as UTC to a distant reader.
+    """
+    moment = generated_at if generated_at is not None else datetime.now().astimezone()
+    if moment.tzinfo is None:
+        moment = moment.astimezone()
+    return moment.isoformat(timespec="microseconds")
+
+
+class LintReporter:
+    """Reporter for lint command."""
+
+    def render(self, run: LintRun, *, generated_at: datetime | None = None) -> None:
+        """Write every lint report from *run*.
+
+        The files and their locations are unchanged: ``todos/lint_report.md``,
+        ``todos/error.md``, and ``todos/to_packaging_modularization.md`` when
+        oversized modules exist.
+
+        #200: each file names this run with a ``- Generated at:`` line. The
+        moment is read once here, so all files of one run agree; callers pass
+        nothing in production. ``generated_at`` exists for tests: the committed
+        snapshots pin everything except the clock, which would otherwise make
+        them unrecordable and would hide the very line the freshness contract
+        is about.
+        """
+        stamp = _run_stamp(generated_at)
+
+        # Create todos directory in current working directory
+        todos_dir = Path("todos")
+        todos_dir.mkdir(exist_ok=True)
+
+        report_file = todos_dir / "lint_report.md"
+        error_file = todos_dir / "error.md"
+
+        paths = list(run.paths) or None
+        large_files = self._find_large_python_files(run.project_root, paths)
+
+        # Generate main lint report content
+        lint_report_content = self._generate_lint_report(run, large_files, stamp=stamp)
+        self._write_report_file(report_file, lint_report_content)
+
+        # Generate error report content
+        error_report_content = self._generate_error_report(run, stamp=stamp)
+        self._write_report_file(error_file, error_report_content)
+
+        # Handle large files report if needed
+        if large_files:
+            self._generate_packaging_todo(
+                large_files, run.project_root, run.quiet, stamp=stamp
+            )
+
+        # Log report generation messages
+        if not run.quiet:
+            log_info_pair(
+                f"Lint report generated at {report_file}",
+                f"静态检查报告已生成到 {report_file}",
+            )
+            log_info_pair(
+                f"Error report generated at {error_file}",
+                f"错误报告已生成到 {error_file}",
+            )
+
+    def issue_text(self, run: LintRun) -> str:
+        """The ruff findings as terminal text, exactly as ruff rendered them.
+
+        The one ruff run is asked for ``--output-format full`` (#170 review
+        F1), so its stdout is already the text the old reporter printed. A
+        previous cut captured JSON here and re-rendered one concise line per
+        finding; that is what shrank the report (and this terminal view) away
+        from ruff's snippets, carets and ``help:`` lines.
+        """
+        return run.ruff.stdout
+
+    def _render_pre_commit(self, pre_commit: PreCommitRun | None) -> str:
+        """Render the pre-commit section from the already-finished run.
+
+        The verdict, the blocks and the filtered text all come from
+        :class:`PreCommitRun` (#165); this method only chooses the wording.
+        """
+        if pre_commit is None:
+            return "pre-commit was not run."
+        if pre_commit.result.launch_error is not None:
+            # ``launch_error`` covers every way the launcher can raise -- a
+            # missing executable, but also a malformed environment or an
+            # undecodable stream -- so name the failure instead of guessing
+            # "not installed" (#165/#172).
+            return f"pre-commit could not be started: {pre_commit.result.launch_error}"
+
+        # A non-zero exit with no hook verdict is pre-commit itself failing
+        # (e.g. an invalid config), not "nothing to report" (#165 patch 4).
+        filtered = pre_commit.filtered_output
+        if filtered:
+            return filtered
+        if pre_commit.hooks_failed:
+            return pre_commit.combined_output.strip()
+        return "No pre-commit issues found."
+
+    def _render_ruff_sections(self, run: LintRun) -> list[str]:
+        """Render the per-directory ruff sections from the one verbatim run.
+
+        Each diagnostic block is ruff's own text; only its placement changes.
+        The run's tail -- ruff's summary, with its own ``[*]`` fixable count
+        and ``--unsafe-fixes`` hint -- is rendered once, after every section: a
+        single invocation can only produce one summary (#170 review F2/F5).
+        """
+        sections = self._existing_sections(run.project_root, list(run.paths) or None)
+        parsed = run.ruff_output
+        if parsed.empty:
+            return []
+
+        grouped: dict[str, list[RuffBlock]] = {title: [] for title, _ in sections}
+        ungrouped: list[RuffBlock] = []
+        for block in parsed.blocks:
+            title = _enclosing_section(block.path, sections, run.project_root)
+            if title is None:
+                ungrouped.append(block)
+            else:
+                grouped[title].append(block)
+
+        lines: list[str] = []
+        for title, _ in sections:
+            lines.extend(self._render_ruff_section(title, grouped[title]))
+        # Findings outside every section (a root-level module, say) used to be
+        # dropped from the report while still failing the run. Keep them, under
+        # the same "." the header uses for the default scope.
+        if ungrouped:
+            lines.extend(self._render_ruff_section(".", ungrouped))
+        if parsed.tail:
+            lines.extend(self._render_ruff_summary(parsed.tail))
+        return lines
+
+    def _render_ruff_section(self, title: str, blocks: list[RuffBlock]) -> list[str]:
+        """One ``## Issues in <title>`` fence, holding ruff's blocks verbatim."""
+        if not blocks:
+            return []
+        body = "\n\n".join(block.text for block in blocks)
+        return [
+            f"## Issues in {title}\n\n",
+            "```\n",
+            body + "\n",
+            "```\n\n",
+        ]
+
+    def _render_ruff_summary(self, tail: tuple[str, ...]) -> list[str]:
+        """ruff's own closing lines: totals, fixable count, unsafe hint."""
+        return [
+            "## Ruff Summary\n\n",
+            "```\n",
+            "\n".join(tail) + "\n",
+            "```\n\n",
+        ]
+
+    @staticmethod
+    def _start_section(lines: list[str], heading: str) -> None:
+        """Append *heading* with exactly one blank line before it (#170 F10)."""
+        while lines and lines[-1] == "":
+            lines.pop()
+        if lines:
+            text = "".join(lines)
+            if not text.endswith("\n\n"):
+                lines.append("\n" if text.endswith("\n") else "\n\n")
+        lines.append(heading)
+
+    def _existing_sections(
+        self, project_root: Path, paths: list[str] | None
+    ) -> list[tuple[str, Path]]:
+        return [
+            (title, path)
+            for title, path in self._resolve_sections(project_root, paths)
+            if path.exists()
+        ]
+
+    def _find_large_python_files(
+        self, project_root: Path, paths: list[str] | None = None
+    ) -> list[tuple[Path, int]]:
+        search_paths = self._build_search_paths(project_root, paths)
+        results: list[tuple[Path, int]] = []
+        for sp in search_paths:
+            for py_file in self._iter_python_files(sp):
+                count = self._count_lines(py_file)
+                if count is not None and count > 200:
+                    results.append((py_file, count))
+        results.sort(key=lambda x: x[1], reverse=True)
+        return results
+
+    def _build_search_paths(
+        self, project_root: Path, paths: list[str] | None
+    ) -> list[Path]:
+        if paths:
+            resolved: list[Path] = []
+            for p in paths:
+                path = Path(p)
+                if not path.is_absolute():
+                    path = project_root / path
+                if path.exists():
+                    resolved.append(path)
+            return resolved
+        base = [project_root / "src"]
+        t = project_root / "tools"
+        e = project_root / "examples"
+        if t.exists():
+            base.append(t)
+        if e.exists():
+            base.append(e)
+        return base
+
+    def _iter_python_files(self, path: Path):
+        if not path.exists():
+            return []
+        if path.is_file() and path.suffix == ".py":
+            return [path]
+        if path.is_dir():
+            return [p for p in path.rglob("*.py") if "__pycache__" not in str(p)]
+        return []
+
+    def _count_lines(self, file_path: Path) -> int | None:
+        try:
+            with open(file_path, encoding="utf-8") as f:
+                return sum(1 for _ in f)
+        except Exception:
+            return None
+
+    def _build_header(
+        self,
+        quiet: bool,
+        fix: bool,
+        paths: list[str] | None,
+        *,
+        stamp: str,
+    ) -> list[str]:
+        """The report's header. ``stamp`` is required: rendering a file never
+        reads the clock itself, it only carries the moment :meth:`render`
+        settled on (LOW-2 -- the ``stamp or _run_stamp()`` fallback let a
+        private helper start a second clock inside one run)."""
+        lines: list[str] = []
+        lines.append("# Lint Report\n\n")
+        lines.append(f"- Generated at: {stamp}\n\n")
+        lines.append("## Configuration\n\n")
+        lines.append(f"- Quiet mode: {quiet}\n")
+        lines.append(f"- Fix enabled: {fix}\n")
+        lines.append(f"- Paths: {', '.join(paths) if paths else '.'}\n\n")
+        return lines
+
+    def _resolve_sections(
+        self, project_root: Path, paths: list[str] | None
+    ) -> list[tuple[str, Path]]:
+        """The report's per-directory sections, in the order they render.
+
+        Section rule (#172): the user's ``paths`` are the sections when any
+        were given -- each title is the path exactly as typed. With no paths
+        the default scope is ``src/``, ``tools/`` and ``examples/``. A finding
+        that belongs to no section -- ``tests/`` under that default scope, or
+        a root-level module -- is rendered under ``.`` by
+        :meth:`_render_ruff_sections`. :meth:`_existing_sections` then drops
+        sections whose directory does not exist, so a fresh project with no
+        ``tools/`` renders no empty section.
+        """
+        if paths:
+            items: list[tuple[str, Path]] = []
+            for p in paths:
+                path = Path(p)
+                if not path.is_absolute():
+                    path = project_root / path
+                items.append((p, path))
+            return items
+        return [
+            ("src/", project_root / "src"),
+            ("tools/", project_root / "tools"),
+            ("examples/", project_root / "examples"),
+        ]
+
+    def _generate_lint_report(
+        self,
+        run: LintRun,
+        large_files: list[tuple[Path, int]],
+        *,
+        stamp: str,
+    ) -> list[str]:
+        """Generate the main lint report content from the run's one stamp."""
+        paths = list(run.paths) or None
+        lines = self._build_header(run.quiet, run.fix, paths, stamp=stamp)
+
+        lines.extend(self._render_ruff_sections(run))
+        parsed_ruff = run.ruff_output
+
+        # Pre-commit results, from the run the executor already finished
+        self._start_section(lines, "## Pre-commit Dry Run Results\n\n")
+        lines.append("```\n")
+        lines.append(self._render_pre_commit(run.pre_commit))
+        lines.append("```\n")
+
+        # MyPy results (one run over ``src/ tests/``)
+        self._start_section(lines, "## MyPy Results\n\n")
+        mypy_result = run.mypy
+        if mypy_result is None:
+            lines.append("mypy was not run.\n")
+        elif mypy_result.stdout:
+            lines.append("```\n")
+            lines.append(mypy_result.stdout)
+            lines.append("```\n")
+            if run.mypy_failure is not None:
+                # ``rc >= 2`` can print partial diagnostics before dying; the
+                # fenced stdout alone would read as an ordinary type-error
+                # listing, so keep the verdict next to it (#172 r1 review F1).
+                lines.append(run.mypy_failure + "\n")
+        elif run.mypy_failure is not None:
+            # A mypy that never produced a verdict is a failure, not "clean":
+            # the old shape answered "No MyPy issues found." to a run that
+            # could not even find its config (#170 review F4).
+            lines.append(run.mypy_failure + "\n")
+        else:
+            lines.append("No MyPy issues found.\n")
+        if mypy_result is not None and mypy_result.stderr:
+            self._start_section(lines, "## MyPy Errors\n\n")
+            lines.append("```\n")
+            lines.append(mypy_result.stderr)
+            lines.append("```\n")
+
+        mypy_output = "" if mypy_result is None else (mypy_result.stdout or "")
+        if (
+            not run.issues_found
+            and not large_files
+            and not mypy_output
+            and run.mypy_failure is None
+        ):
+            lines.append("No lint issues found.\n")
+        # ruff's stderr used to be rendered only when there were no findings at
+        # all, so a run that emitted diagnostics *and* a warning lost the
+        # warning (#170 review F8). Keep it whenever ruff actually produced
+        # findings or produced nothing at all; a clean run's config warnings
+        # stay out of the report, as they did before.
+        if run.ruff.stderr.strip() and (parsed_ruff.blocks or parsed_ruff.empty):
+            self._start_section(lines, "## Errors\n\n")
+            lines.append("```\n")
+            lines.append(run.ruff.stderr)
+            lines.append("```\n")
+
+        return lines
+
+    def _generate_error_report(self, run: LintRun, *, stamp: str) -> list[str]:
+        """Generate the per-scope mypy error report from the single run.
+
+        ``src/`` and ``tests/`` used to be two mypy invocations; now the one
+        run's output is split by path prefix. Only scopes that carry output get
+        a section -- the old report printed a section only when that scope's
+        run said something, so an empty scope never rendered an "No issues
+        found." placeholder (#170 review F7). The one run's totals stay in a
+        tail block because they cannot be attributed to either scope.
+        """
+        error_lines = ["# MyPy Error Report\n\n"]
+        error_lines.append(f"- Generated at: {stamp}\n\n")
+        mypy_result = run.mypy
+        if mypy_result is None:
+            error_lines.append("mypy was not run.\n")
+            return error_lines
+
+        failure = run.mypy_failure
+        if failure is not None:
+            error_lines.append(f"{failure}\n\n")
+
+        grouped, tail = _split_mypy_output(mypy_result.stdout or "", run.project_root)
+
+        for scope in _MYPY_SCOPES:
+            body = grouped[scope]
+            if not body:
+                continue
+            error_lines.append(f"## MyPy Results for {scope}\n\n")
+            error_lines.append("```\n")
+            error_lines.append("\n".join(body) + "\n")
+            error_lines.append("```\n\n")
+
+        # The one run's summary ("Found N errors in M files ...") cannot be
+        # attributed to either scope; keep it rather than dropping the totals.
+        if tail:
+            error_lines.append("```\n")
+            error_lines.append("\n".join(tail) + "\n")
+            error_lines.append("```\n")
+
+        if mypy_result.stderr:
+            self._start_section(error_lines, "## MyPy Errors\n\n")
+            error_lines.append("```\n")
+            error_lines.append(mypy_result.stderr)
+            error_lines.append("```\n")
+
+        return error_lines
+
+    def _write_report_file(self, file_path: Path, content: list[str]) -> None:
+        """Write report content to the specified file."""
+        with open(file_path, "w", encoding="utf-8") as f:
+            f.writelines(content)
+
+    def _generate_packaging_todo(
+        self,
+        large_files: list[tuple[Path, int]],
+        project_root: Path,
+        quiet: bool,
+        *,
+        stamp: str,
+    ) -> None:
+        """
+        生成用于打包模块化的待办事项报告（``stamp`` 必填：一次 render 只读一次时钟）
+        """
+        # Create todos directory in current working directory
+        todos_dir = Path("todos")
+        todos_dir.mkdir(exist_ok=True)
+
+        packaging_report_file = todos_dir / "to_packaging_modularization.md"
+
+        lines: list[str] = []
+        lines.append("# To Packaging Modularization\n\n")
+        lines.append(f"- Generated at: {stamp}\n\n")
+        lines.append("## Large Python Files (>200 lines)\n\n")
+        lines.append(
+            "These files are candidates for modularization due to their size.\n\n"
+        )
+        lines.append("| File Path | Line Count |\n")
+        lines.append("|-----------|------------|\n")
+        for file_path, line_count in large_files:
+            # 将路径转换为相对于项目根目录的路径
+            relative_path = file_path.relative_to(project_root)
+            lines.append(f"| {relative_path} | {line_count} |\n")
+        lines.append("\n")
+
+        with open(packaging_report_file, "w", encoding="utf-8") as f:
+            f.writelines(lines)
+
+        if not quiet:
+            log_info_pair(
+                f"Packaging todo list generated at {packaging_report_file}",
+                f"打包模块化待办列表已生成到 {packaging_report_file}",
+            )
+
+
+def _enclosing_section(
+    path: str,
+    sections: list[tuple[str, Path]],
+    project_root: Path,
+) -> str | None:
+    """The title of the section *path* belongs to, or ``None``.
+
+    ``None`` means the finding is outside every section; the caller renders
+    those under ``.`` -- which is why a ``tests/`` finding (not one of the
+    default sections, see :meth:`LintReporter._resolve_sections`) still
+    appears in the report instead of being dropped. When sections overlap
+    (``src`` and ``src/pkg``) the longest matching prefix wins, so each
+    finding is shown once, in its most specific section. Both sides are
+    resolved for the same symlinked-root reason as :func:`display_path`.
+    """
+    candidate = Path(path)
+    if not candidate.is_absolute():
+        candidate = project_root / candidate
+    try:
+        resolved = candidate.resolve()
+    except OSError:
+        resolved = candidate
+
+    best: tuple[str, Path] | None = None
+    for title, section in sections:
+        try:
+            section_resolved = section.resolve()
+        except OSError:
+            section_resolved = section
+        if resolved == section_resolved or section_resolved in resolved.parents:
+            if best is None or len(section_resolved.parts) > len(best[1].parts):
+                best = (title, section_resolved)
+    return None if best is None else best[0]
+
+
+#: mypy's diagnostic prefix: ``path:line: error:``, ``path:line:col: error:``
+#: or ``path: note:``. Diagnostic lines start at column 0; continuation lines
+#: (wrapped message, snippet, caret) are indented, which is what keeps a source
+#: line that happens to contain ``error:`` from being read as a new diagnostic.
+_MYPY_DIAGNOSTIC = re.compile(
+    r"^(?P<path>\S.*?):(?:(?P<row>\d+):(?:(?P<column>\d+):)?)?\s*"
+    r"(?P<severity>error|note|warning):"
+)
+
+
+def _split_mypy_output(
+    output: str, project_root: Path
+) -> tuple[dict[str, list[str]], list[str]]:
+    """Split one mypy run's output into the ``src/`` and ``tests/`` scopes.
+
+    mypy prints one diagnostic per prefixed line, followed by continuation
+    lines -- wrapped messages, source snippets, carets -- that carry no prefix
+    of their own. Those belong to the diagnostic above them, so the split
+    tracks the target of the last *diagnostic* line rather than classifying
+    every line on its own.
+
+    A diagnostic whose path is not under either scope (``tools/helper.py``,
+    an absolute path outside the project, or mypy's own ``mypy: error: ...``)
+    starts a tail target of its own. The previous version only looked at the
+    last scope it had seen, so such a line was appended to the *previous*
+    scope's section -- and an absolute path under ``src/`` was classified as
+    "outside", leaving both sections saying "No issues found." while the
+    finding hid in the tail (#170 review F6).
+    """
+    grouped: dict[str, list[str]] = {scope: [] for scope in _MYPY_SCOPES}
+    tail: list[str] = []
+    current: list[str] | None = None
+    for line in (output or "").splitlines():
+        if line.startswith(("Found ", "Success:")):
+            current = tail
+            tail.append(line)
+            continue
+        match = _MYPY_DIAGNOSTIC.match(line)
+        if match is not None:
+            path = match.group("path")
+            scope = _mypy_scope(path, project_root)
+            current = tail if scope is None else grouped[scope]
+            current.append(line)
+            continue
+        if current is None:
+            tail.append(line)
+        else:
+            current.append(line)
+    return grouped, tail
+
+
+def _mypy_scope(path: str, project_root: Path) -> str | None:
+    """The scope whose path prefix covers *path*, or ``None``.
+
+    Absolute paths are expressed relative to *project_root* first (with both
+    sides resolved, so a symlinked root such as ``/tmp`` still matches), then
+    the same prefix rule the report uses applies to either form.
+    """
+    shown = display_path(path, project_root).replace("\\", "/")
+    while shown.startswith("./"):
+        shown = shown[2:]
+    for scope in _MYPY_SCOPES:
+        name = scope.rstrip("/")
+        if shown == name or shown.startswith(scope):
+            return scope
+    return None