py-wlcli 0.8.0__py3-none-any.whl

wl_cli/commands/lint/lint_executor.py

@@ -0,0 +1,409 @@
+"""
+Lint executor module.
+Runs every tool one ``wl lint`` needs -- ruff, pre-commit, mypy -- exactly once.
+"""
+
+from pathlib import Path
+
+from ...utils.pre_commit import PreCommitRun, run_pre_commit
+from ...utils.pre_commit_config import managed_pre_commit_config
+from ...utils.root import Root, RootKind
+from ...utils.subprocess_utils import SubprocessExecutor, SubprocessResult
+from .lint_run import LintRun
+from .mypy_config import mypy_config_file
+
+
+def _scope_path(root: Root, token: str) -> Path:
+    """The directory *token* names under *root*.
+
+    ``src/`` is the one scope directory the root module names
+    (:meth:`Root.src_dir`), so ask it for that one; every other token --
+    ``tests/`` or a caller-supplied path -- has no derived-path method and is
+    joined onto the root the plain way. Routing the ``src`` probe through the
+    module keeps the root layout with a single owner (#114) without widening
+    ``Root``'s interface.
+    """
+    if Path(token).parts == ("src",):
+        return root.src_dir()
+    return root.path / token
+
+
+def _scope_token_path(token: str, root: Root | None) -> Path:
+    """The path *token* names when the command runs from the anchored root.
+
+    Both an explicit user path and a fallback default resolve through here, so
+    the two probes cannot drift apart (#174). *root* is ``None`` when the
+    caller pinned no project root; the token is then used as-is and resolves
+    against the cwd, which is where the command will run.
+    """
+    candidate = Path(token)
+    if root is not None and not candidate.is_absolute():
+        return _scope_path(root, token)
+    return candidate
+
+
+def _existing_scope_tokens(tokens: tuple[str, ...], root: Root | None) -> list[str]:
+    """The *tokens* that resolve to an existing path, probed like explicit paths.
+
+    A probe that raises counts as missing, matching the explicit-path loop's
+    blanket guard: an unreadable path must not crash command construction.
+    """
+    existing = []
+    for token in tokens:
+        try:
+            if _scope_token_path(token, root).exists():
+                existing.append(token)
+        except Exception:
+            pass
+    return existing
+
+
+def _cwd_anchored_scope_tokens(tokens: list[str]) -> list[str]:
+    """*tokens* re-anchored on the cwd, as absolute paths where they exist there.
+
+    The floor for an explicit scope that resolved nowhere under the project
+    root (#179). A token can still name a real path relative to where the user
+    typed the command -- ``cd pkg && wl lint commands`` -- while the ruff run
+    happens at the project root; handing it over unchanged only produced
+    ``E902``. Resolving it here hands ruff the same directory, absolute, so
+    every process agrees on it (the symlink reasoning of #170 review F4).
+
+    A token that exists nowhere -- an absolute path included -- is returned
+    untouched, so ruff reports it instead of lint silently widening to ``"."``.
+    """
+    anchored = []
+    for token in tokens:
+        try:
+            candidate = Path(token)
+            resolved = candidate.resolve()
+            if not candidate.is_absolute() and resolved.exists():
+                anchored.append(str(resolved))
+            else:
+                anchored.append(token)
+        except Exception:
+            # Same blanket guard as the probes: an unreadable path must not
+            # crash command construction; ruff reports it.
+            anchored.append(token)
+    return anchored
+
+
+def _resolved_scope_tokens(tokens: tuple[str, ...], root: Root | None) -> list[str]:
+    """Every token, in order: anchored on *root* or passed through (#188).
+
+    Filtering the missing tokens out -- the old ``existing or cwd_anchored``
+    -- silently narrowed a partially-missing scope: ``wl lint src typo`` ran
+    ``ruff check src`` and never mentioned ``typo``. Each token is now kept:
+
+    * one that resolves under *root* is handed over as typed;
+    * one that does not is re-anchored on the cwd (absolute when it is real
+      there -- ``cd pkg && wl lint commands``, the #179 floor);
+    * one that exists nowhere is passed through untouched, so ruff reports it
+      as ``E902`` and mypy as ``Cannot read file ...`` instead of lint
+      checking less than asked.
+
+    Probes share :func:`_scope_token_path` with the existence filters, so the
+    two can never disagree about what "resolves under the root" means.
+    """
+    resolved: list[str] = []
+    for token in tokens:
+        try:
+            if _scope_token_path(token, root).exists():
+                resolved.append(token)
+                continue
+        except Exception:
+            # Same blanket guard as the probes: an unreadable path must not
+            # crash command construction; the tool reports it.
+            pass
+        resolved.append(_cwd_anchored_scope_tokens([token])[0])
+    return resolved
+
+
+class LintExecutor:
+    """Executor for lint commands."""
+
+    def prepare_ruff_command(
+        self,
+        paths: list[str] | None,
+        fix: bool,
+        quiet: bool,
+        *,
+        structured: bool = False,
+        project_root: Path | None = None,
+    ) -> list[str]:
+        """Prepare the ruff command.
+
+        *project_root* is the directory this command will be **run from**:
+        the explicit-path probes below resolve against it the same way mypy's
+        explicit paths do (#179). Without it, a bare token was probed against
+        the process cwd even though the command later ran with
+        ``cwd=project_root``, so from a subdirectory ``wl lint src`` could drop
+        an existing scope and widen to the whole repo. ``None`` keeps the
+        historical cwd probe, which is correct when the caller runs the command
+        from wherever it built it.
+
+        A requested scope is never widened to ``"."`` either, and no token is
+        dropped (#188): a partially-missing scope used to run only the tokens
+        that existed. Each token that does not resolve under *project_root* is
+        re-probed against the cwd: one that is real there -- ``cd pkg && wl
+        lint commands`` -- goes to ruff as an absolute path, so the run at the
+        root reaches it, while a token that exists nowhere is passed through
+        for ruff to report (``E902``). This is this function's own floor,
+        **not** mypy's #174 one: mypy's *fallback* scope is filtered, whereas
+        ruff has no default scope to fall back to and none is invented. With
+        no explicit paths at all the default stays ``"."`` (the documented
+        default, which ``wl gate`` depends on).
+
+        ``structured`` asks ruff for the report's ``--output-format full``
+        text. One such run carries every finding -- header, ``-->`` location,
+        snippet, caret, ``help:``, and ruff's own closing summary -- which is
+        what lets the report group the verbatim blocks into its per-directory
+        sections without re-running ruff once per section (#170 audit patch 4 /
+        review F1-F2). ``--fix`` is orthogonal: ruff applies the fixes, then
+        reports whatever diagnostics remain, so the same single run stays
+        enough.
+
+        ``--quiet`` is *not* passed on a structured run even when the caller
+        asked for it: ruff's quiet mode suppresses the summary, and with it the
+        ``Found N errors.`` / ``[*] N fixable ... (N hidden fixes ...)`` lines
+        the report must keep (#170 review F2). The caller's quiet still governs
+        wl's own logging and the capture.
+        """
+        # Prepare ruff command (offline, no uv fetch)
+        cmd = ["ruff", "check"]
+
+        # The directory the command will run from, as a value the scope probe
+        # can resolve against. ``None`` when the caller pinned no root -- then
+        # a bare token is probed against the cwd exactly as before
+        # ``project_root`` existed.
+        root = (
+            Root(project_root, RootKind.PROJECT) if project_root is not None else None
+        )
+
+        # Every token the caller named is handed over, or the whole directory
+        # when none were named. A token missing under the root is re-anchored
+        # on the cwd (absolute when real there) rather than widened to ".";
+        # a token real in neither place is passed through for ruff to report.
+        if paths:
+            cmd.extend(_resolved_scope_tokens(tuple(paths), root))
+        else:
+            cmd.append(".")
+
+        # One structured run feeds every report section
+        if structured:
+            cmd.extend(["--output-format", "full"])
+
+        # Add fix flag if requested
+        if fix:
+            cmd.append("--fix")
+
+        # Add quiet flag if requested, but never for the structured run whose
+        # summary and fixable count the report renders.
+        if quiet and not structured:
+            cmd.append("--quiet")
+
+        return cmd
+
+    def prepare_mypy_command(
+        self,
+        paths: list[str] | None,
+        quiet: bool,
+        project_root: Path | None = None,
+        *,
+        fallback_paths: tuple[str, ...] = ("src/", "tests/"),
+    ) -> list[str]:
+        """Prepare the mypy command.
+
+        *project_root* is the directory this command will be **run from**: the
+        config lookup and the path-existence checks below resolve against it.
+        It defaults to the current working directory, which is only correct
+        when the caller runs the command from wherever it built it -- the gate
+        builds its command before running it with the project root as cwd.
+
+        *fallback_paths* is the scope used when the requested *paths* cannot be
+        used, or when none were requested; it defaults to the historical
+        ``src/ tests/``. A caller whose scope is a *contract* narrows it:
+        ``wl gate`` checks ``src/`` and nothing else, so a root that cannot
+        satisfy that scope must fail on its own terms rather than silently
+        widen the leg to directories the change under test has nothing to do
+        with (review F0 -- a monorepo whose git work-tree root has no
+        ``src/``).
+
+        An **explicit** path is never filtered (#188, the same floor as ruff's
+        command): a token that resolves nowhere under the root is handed over
+        -- cwd-anchored when it is real there -- so mypy says ``Cannot read
+        file ...`` instead of lint quietly checking only the tokens that
+        happened to exist. Only the caller's *fallback* is filtered, below.
+
+        The fallback itself is filtered to the tokens that resolve to an
+        existing path, probed exactly like an explicit one (#174): a project
+        with only ``src/`` must not ask mypy to read ``tests/``, which would
+        exit 2 and leave ``wl lint`` permanently red. When *none* of the
+        fallback tokens exists, the original fallback is passed unchanged --
+        the scope is never silently widened or emptied, so mypy still fails
+        with ``Cannot read file ...`` and ``wl gate``'s ``src/`` contract
+        still fails on its own terms. That floor assumes a non-empty
+        *fallback_paths*, as every current caller passes one; an empty
+        fallback would necessarily yield an empty scope.
+        """
+        # Prepare mypy command
+        root_path = Path.cwd() if project_root is None else project_root
+        # The same directory as a value, for the scope probes below. ``None``
+        # when the caller pinned no root -- then a bare token is probed against
+        # the cwd exactly as before ``project_root`` existed.
+        root = Root(root_path, RootKind.PROJECT) if project_root is not None else None
+        cmd = ["mypy"]
+
+        # Absolute, never cwd-relative (#170 review F4). The command is built
+        # from *project_root* and then run with it as cwd, but the two can
+        # disagree through a symlink (``/tmp`` vs ``/private/tmp`` on macOS):
+        # a relative token computed against one spelling and resolved against
+        # the other points nowhere, and mypy then fails to start. An absolute
+        # path means the same file to every process.
+        wl_mypy_config = mypy_config_file(root_path, relative=False)
+        if wl_mypy_config is not None:
+            cmd.extend(["--config-file", str(wl_mypy_config)])
+
+        # Add every requested path, or the caller's fallback scope when none
+        # were requested. An explicit token is never dropped (#188): mypy
+        # reports the missing ones instead of lint silently narrowing.
+        if paths:
+            cmd.extend(_resolved_scope_tokens(tuple(paths), root))
+        else:
+            # Keep only fallback directories that exist (#174). ``or`` is the
+            # fail-closed floor: an all-missing fallback passes through
+            # unchanged, so mypy reports the missing scope itself.
+            cmd.extend(_existing_scope_tokens(fallback_paths, root) or fallback_paths)
+
+        # Add quiet flag if requested
+        if quiet:
+            cmd.append("--quiet")
+
+        return cmd
+
+    def run_mypy_command(
+        self, cmd: list[str], project_root: Path, quiet: bool
+    ) -> SubprocessResult:
+        """Run the mypy command and return the result (统一子进程执行)."""
+        executor = SubprocessExecutor()
+        capture = quiet
+        return executor.run(command=cmd, cwd=project_root, quiet=capture)
+
+    def run_ruff_command(
+        self, cmd: list[str], project_root: Path, quiet: bool, noreport: bool
+    ) -> SubprocessResult:
+        """Run the ruff command and return the result (统一子进程执行)."""
+        executor = SubprocessExecutor()
+        capture = quiet or not noreport
+        return executor.run(command=cmd, cwd=project_root, quiet=capture)
+
+    def run_pre_commit_command(self, project_root: Path) -> PreCommitRun:
+        """Run the whole pre-commit suite once, for the report.
+
+        The verdict and the display text come from :class:`PreCommitRun`
+        (#165). Lint's only own decision is what a missing config means: it
+        falls back to pre-commit's default discovery instead of skipping the
+        run (#165 audit patch 2), which is why ``config`` is ``None`` there.
+
+        *Where* the managed config lives is not decided here: the shared
+        locator answers it with the ``DEPLOY`` anchor (#189). Looking it up at
+        the ``PROJECT`` root -- as this did -- missed the file whenever the
+        project root is a sub-package below the git top, and pre-commit then
+        failed with ``InvalidConfigError`` instead of discovering anything.
+        """
+        try:
+            managed = managed_pre_commit_config(project_root)
+            config = managed if managed.exists() else None
+            # Bare ``pre-commit`` first (#172): lint already runs inside the
+            # project environment, so ``uv run`` would only re-resolve it.
+            # ``run_pre_commit`` falls back to ``uv run`` if the launcher is
+            # absent. Format keeps the uv-first default for its uv-managed env.
+            return run_pre_commit(
+                files=None,
+                config=config,
+                cwd=project_root,
+                quiet=True,
+                prefer_uv=False,
+            )
+        except FileNotFoundError as e:
+            # Defensive parity with the reporter this replaced: a launcher that
+            # cannot be found reads as "not installed", not as a config error.
+            return PreCommitRun(
+                SubprocessResult(
+                    returncode=-1, stdout="", stderr=str(e), launch_error=str(e)
+                )
+            )
+        except Exception as e:
+            # The same catch-all the reporter had: an unreadable config path is
+            # a reported pre-commit failure, never a lint crash.
+            return PreCommitRun(
+                SubprocessResult(
+                    returncode=-1,
+                    stdout=f"Error running pre-commit dry-run: {e}",
+                    stderr="",
+                )
+            )
+
+    def run_all(
+        self,
+        project_root: Path,
+        paths: list[str] | None = None,
+        *,
+        quiet: bool = False,
+        fix: bool = False,
+        with_mypy: bool = True,
+        with_pre_commit: bool = True,
+        structured_ruff: bool = True,
+        format_code: int = 0,
+    ) -> LintRun:
+        """Run each requested tool once and return the finished :class:`LintRun`.
+
+        The caller picks the tool set (#170 audit patch 3): ``--noreport`` asks
+        for ruff alone, ``--report`` and the default path ask for all three.
+        ``structured_ruff`` is the same choice seen from the report's side --
+        only a rendered report needs ruff's ``--output-format full``
+        diagnostics.
+
+        Order matches the report: ruff, then pre-commit, then mypy. Pre-commit
+        hooks may rewrite files, so mypy must run after them to judge what is
+        actually on disk.
+        """
+        ruff_cmd = self.prepare_ruff_command(
+            paths,
+            fix,
+            quiet,
+            structured=structured_ruff,
+            project_root=project_root,
+        )
+        ruff = SubprocessExecutor().run(
+            command=ruff_cmd,
+            cwd=project_root,
+            # A structured run is captured even outside ``--quiet``: the
+            # report renders it instead of the child streaming it.
+            quiet=quiet or structured_ruff,
+        )
+
+        pre_commit = (
+            self.run_pre_commit_command(project_root) if with_pre_commit else None
+        )
+
+        mypy: SubprocessResult | None = None
+        if with_mypy:
+            # ``quiet=False`` on purpose: the report's "MyPy Results" section
+            # has always shown mypy's own summary line, even under ``--quiet``.
+            mypy_cmd = self.prepare_mypy_command(
+                None, quiet=False, project_root=project_root
+            )
+            mypy = SubprocessExecutor().run(
+                command=mypy_cmd, cwd=project_root, quiet=True
+            )
+
+        return LintRun(
+            ruff=ruff,
+            project_root=project_root,
+            mypy=mypy,
+            pre_commit=pre_commit,
+            paths=tuple(paths or ()),
+            quiet=quiet,
+            fix=fix,
+            format_code=format_code,
+        )