py-wlcli 0.8.0__py3-none-any.whl

wl_cli/commands/format/format_path_handler.py

@@ -0,0 +1,1016 @@
+"""Format path handler module."""
+
+import os
+import re
+from collections.abc import Iterable, Iterator
+from pathlib import Path
+from typing import cast
+
+import tomllib
+
+from ...utils.logging import log_info_pair, log_warning_pair
+from ...utils.pre_commit import PreCommitRun, run_pre_commit
+from ...utils.pre_commit_config import managed_pre_commit_config
+from ...utils.root import RootKind
+from ...utils.root_fallback import current_root
+from ...utils.subprocess_utils import SubprocessExecutor
+from ...utils.uv_run import run_uv_command
+from .format_executor import FormatExecutor
+from .format_outcome import FormatFailure, FormatOutcome
+from .python_formatter import format_with_python_tools
+from .rust_formatter import format_rust_code
+
+#: Directories discovery never descends into (#187): virtualenvs, dependency
+#: trees, packaging output and caches. Unconditional -- unlike the ruff
+#: patterns below, an explicit config cannot re-include them, because handing
+#: one of their files to ruff as an *explicit* path is exactly the ``.venv``
+#: rewrite this ticket reports (ruff does not apply ``exclude`` to explicit
+#: files). ``dist`` and ``build`` are in ruff's own default ``exclude``; they
+#: are repeated here because a project config replaces those defaults outright
+#: and the user docs promise they stay ignored (#206).
+_FIXED_IGNORED_DIRS = frozenset(
+    {
+        ".git",
+        ".hg",
+        ".svn",
+        ".venv",
+        "venv",
+        "node_modules",
+        "site-packages",
+        "dist-packages",
+        "dist",
+        "build",
+        "__pycache__",
+        ".mypy_cache",
+        ".pytest_cache",
+        ".ruff_cache",
+        ".tox",
+        ".nox",
+        ".hypothesis",
+        ".eggs",
+    }
+)
+
+#: Compiled exclude pattern, in config order.
+_ExcludeMatcher = re.Pattern[str]
+
+
+def _ignored_dir_name(name: str) -> bool:
+    """Whether *name* is in the unconditional ignore set."""
+    return name in _FIXED_IGNORED_DIRS or name.endswith(".egg-info")
+
+
+def _load_toml(path: Path) -> dict | None:
+    """Read *path* as TOML; ``None`` when it is unreadable or malformed."""
+    try:
+        with path.open("rb") as handle:
+            return tomllib.load(handle)
+    except (OSError, tomllib.TOMLDecodeError):
+        return None
+
+
+def _string_list(value: object) -> tuple[str, ...]:
+    """The string entries of a ruff list option (anything else is ignored)."""
+    if not isinstance(value, list):
+        return ()
+    return tuple(item for item in value if isinstance(item, str))
+
+
+def _base_exclude_patterns(ruff_config: dict) -> tuple[str, ...]:
+    """The top-level ``exclude`` / ``extend-exclude`` ruff's resolver applies.
+
+    These are directory patterns: an excluded directory excludes everything
+    below it, which is why they are compiled with descendant matching.
+    ``ruff check --show-files`` already applies them, so discovery only needs
+    them on the local-walk fallback.
+    """
+    patterns: list[str] = []
+    for key in ("exclude", "extend-exclude"):
+        patterns.extend(_string_list(ruff_config.get(key)))
+    return tuple(patterns)
+
+
+def _mode_exclude_patterns(ruff_config: dict) -> tuple[str, ...]:
+    """``lint.exclude`` / ``format.exclude``, applied per mode after discovery.
+
+    Ruff matches these against **file paths**, not against directory prefixes:
+    with ``exclude = ["gen"]`` ruff still visits ``gen/x.py``; ``gen/*.py`` or
+    ``**/gen/**`` is what excludes it (ruff 0.15). ``*`` and ``?`` cross ``/``
+    there, so ``gen/*.py`` also drops ``gen/sub/y.py``. Discovery has to
+    mirror that exactly, because it hands every file to ruff as an *explicit*
+    path, where ruff never applies ``exclude`` at all: a file dropped here is
+    never linted, and a file kept here is linted whatever the mode list says.
+
+    Both mode lists are invisible to ``ruff check --show-files``, which stops
+    at the base resolver (#195), and both follow the *nearest* config -- so a
+    subpackage's own ``[tool.ruff.lint] exclude`` governs its files (#206).
+    The ``lint`` / ``format`` tables have no ``extend-exclude`` of their own
+    (ruff rejects the key as unknown), so only ``exclude`` is read.
+
+    The two lists are **unioned** here and applied to both commands (#206):
+    ``wl lint`` runs ``ruff check`` *and* ``ruff format``, so the union is the
+    safe reading for it; ``wl format`` is consequently conservative -- a file
+    only ``lint.exclude`` names is not formatted even though ``ruff format``
+    would format it. Documented as a trade-off in ``docs/user/commands/lint.md``;
+    splitting the matcher per command would need the mode threaded through
+    discovery, which the union avoids.
+    """
+    patterns: list[str] = []
+    for mode in ("lint", "format"):
+        section = ruff_config.get(mode)
+        if isinstance(section, dict):
+            patterns.extend(_string_list(section.get("exclude")))
+    return tuple(patterns)
+
+
+def _ruff_config_for(directory: Path) -> tuple[Path, dict | None]:
+    """The directory and ruff config table governing files under *directory*.
+
+    Mirrors ruff's own discovery: the nearest ancestor carrying
+    ``ruff.toml`` / ``.ruff.toml`` (same-directory files win over
+    ``pyproject.toml``), else the nearest ``pyproject.toml`` with a
+    ``[tool.ruff]`` table. Files without ruff config are transparent. The
+    lookup starts at each file's own directory, so a nested config governs its
+    own subtree exactly as ruff's hierarchical configuration does (#206).
+    """
+    try:
+        start = directory.resolve()
+    except OSError:
+        start = directory
+    for candidate in (start, *start.parents):
+        for name in ("ruff.toml", ".ruff.toml"):
+            config_file = candidate / name
+            if config_file.is_file():
+                data = _load_toml(config_file)
+                if data is not None:
+                    return candidate, data
+        pyproject = candidate / "pyproject.toml"
+        if pyproject.is_file():
+            data = _load_toml(pyproject)
+            if data is not None:
+                tool = data.get("tool")
+                ruff = tool.get("ruff") if isinstance(tool, dict) else None
+                if isinstance(ruff, dict):
+                    return candidate, ruff
+    return start, None
+
+
+class _RuffExcludes:
+    """Per-directory cache of the exclude matchers that govern a directory.
+
+    Discovery asks once per directory rather than once per file: a scan can
+    list hundreds of files and every lookup walks ancestors and parses TOML.
+    The cache lives for one discovery call, so a config edited mid-process is
+    still read fresh next time.
+    """
+
+    def __init__(self) -> None:
+        self._cache: dict[
+            Path, tuple[Path, tuple[_ExcludeMatcher, ...], tuple[_ExcludeMatcher, ...]]
+        ] = {}
+
+    def for_directory(
+        self, directory: Path
+    ) -> tuple[Path, tuple[_ExcludeMatcher, ...], tuple[_ExcludeMatcher, ...]]:
+        """``(config directory, base matchers, mode matchers)`` for *directory*."""
+        cached = self._cache.get(directory)
+        if cached is not None:
+            return cached
+        config_dir, ruff_config = _ruff_config_for(directory)
+        ruff_config = ruff_config or {}
+        entry = (
+            config_dir,
+            _compile_excludes(_base_exclude_patterns(ruff_config)),
+            _compile_excludes(_mode_exclude_patterns(ruff_config), descendants=False),
+        )
+        self._cache[directory] = entry
+        return entry
+
+
+def _warn_listing_fallback(directory: Path, reason: str) -> None:
+    """Say out loud that discovery degraded to the local walk (#206).
+
+    A warning, not a hard failure: the formatting run that follows is the
+    authority on a broken ruff and reports its own error, while failing here
+    would preempt that with "could not list files". What must not happen is
+    the pre-#206 silence -- the local walk loses ruff's default excludes,
+    ``respect-gitignore`` and nested configs, so a caller has to know the run
+    is only a partial mirror of what ruff would do.
+    """
+    log_warning_pair(
+        f"ruff could not list files under {directory} ({reason}); falling back to "
+        "wl's own walk, which cannot fully mirror ruff's exclude rules",
+        f"ruff 无法枚举 {directory} 下的文件（{reason}），改用 wl 自己的遍历；"
+        "该遍历无法完全对齐 ruff 的排除规则",
+    )
+
+
+def _ruff_listed_files(directory: Path, env: dict | None) -> tuple[Path, ...] | None:
+    """The files ruff itself would visit under *directory*, or ``None``.
+
+    ``ruff check --show-files`` *is* ruff's file resolution (#195), so
+    discovery stops re-implementing it: the built-in default ``exclude``
+    (``dist``, ``.venv`` ...), the top-level project ``exclude`` /
+    ``extend-exclude``, nested configs and ``respect-gitignore`` all come from
+    ruff rather than from a partial local copy -- which is how ``dist`` used
+    to be handed over as an *explicit* file, where ruff never applies
+    ``exclude``.
+
+    It stops at the *base* resolver. ``[tool.ruff.lint]`` and
+    ``[tool.ruff.format]`` ``exclude`` are applied per mode, afterwards, so the
+    caller keeps filtering with those lists (see
+    :meth:`FormatPathHandler._discovered_python_files`); ``ruff format`` has no
+    ``--show-files`` at all.
+
+    Returns ``None`` when ruff could not be asked at all (not installed,
+    refused the config). Discovery then falls back to the local walk rather
+    than failing the gate: the formatting run itself reports a broken ruff, and
+    failing closed here would replace that diagnosis with a less actionable
+    one. The fallback is no longer silent, though (#206): it cannot mirror
+    ruff's default excludes, ``respect-gitignore`` or nested configs, so the
+    degradation is announced by :func:`_warn_listing_fallback`.
+    """
+    try:
+        result = run_uv_command(
+            SubprocessExecutor(),
+            ["uv", "run", "ruff", "check", "--show-files", str(directory)],
+            # An empty mapping would strip PATH from the child and make every
+            # launch fail; ``None`` inherits, which is what "no environment
+            # given" means at both call sites.
+            env=env or None,
+            quiet=True,
+        )
+    except Exception as exc:
+        _warn_listing_fallback(directory, f"{type(exc).__name__}: {exc}")
+        return None
+    if result.returncode != 0:
+        _warn_listing_fallback(directory, f"exit code {result.returncode}")
+        return None
+    return tuple(
+        Path(line.strip()) for line in result.stdout.splitlines() if line.strip()
+    )
+
+
+def _relative_to_root(path: Path, root: Path) -> Path | None:
+    """Where *path* sits under *root*, ``None`` when it sits outside.
+
+    Ruff echoes the prefix it was handed (``/var/...``) while *root* is
+    resolved (``/private/var/...`` on macOS), so the plain subtraction is
+    retried with the file's *parent* canonicalised. Only the parent is
+    canonicalised on purpose: a symlinked file must keep its own identity so
+    the caller can still recognise (and skip) it.
+    """
+    try:
+        return path.relative_to(root)
+    except ValueError:
+        pass
+    try:
+        canonical = Path(os.path.realpath(path.parent)) / path.name
+        return canonical.relative_to(root)
+    except (OSError, ValueError):
+        return None
+
+
+def _glob_to_regex(pattern: str, *, descendants: bool = True) -> re.Pattern[str] | None:
+    """Translate one ruff exclude pattern into an anchored regex.
+
+    Ruff compiles ``exclude`` entries with ``globset`` **without**
+    ``literal_separator``, which is not gitignore syntax: ``*`` and ``?``
+    match ``/`` too, so ``a/*`` matches ``a/b/w.py`` and ``gen/*.py`` matches
+    ``gen/sub/y.py`` (verified against ruff 0.15.21). ``**`` is equivalent for
+    path matching; the only place it differs is the zero-directory form
+    ``**/`` at the start or middle of a pattern, which also matches no
+    directory at all. Character classes, a leading ``/`` anchor and the
+    ``!`` literal (ruff does **not** support negation) are handled too.
+
+    ``descendants`` selects which ruff matcher is being mirrored (#206):
+
+    * ``True`` -- the base ``exclude`` / ``extend-exclude`` resolved by
+      ``ruff check --show-files`` (and mirrored on wl's fallback walk). It is
+      directory-aware: an unanchored pattern is matched at any depth
+      (``w.py`` excludes ``a/b/w.py``) and a matched directory excludes its
+      contents.
+    * ``False`` -- ``lint.exclude`` / ``format.exclude``. Ruff matches those
+      against **file paths**, never directory prefixes: a bare ``gen`` does
+      not match ``gen/x.py`` (a matched directory does not pull its contents
+      in). Depth still applies, though -- ruff resolves a pattern without
+      ``/`` at any depth (``w.py`` drops ``a/b/w.py``), and a pattern with
+      ``/`` is anchored at its config root (``gen/*.py`` leaves
+      ``a/gen/x.py`` alone). Cross-directory reach also comes from ``*``.
+    """
+    body = pattern
+    anchored = body.startswith("/")
+    if anchored:
+        body = body[1:]
+    body = body.rstrip("/")
+    if not body:
+        return None
+    anchored = anchored or "/" in body
+
+    parts: list[str] = []
+    index = 0
+    while index < len(body):
+        char = body[index]
+        if char == "*":
+            if body.startswith("**", index):
+                index += 2
+                if index < len(body) and body[index] == "/":
+                    index += 1
+                    parts.append("(?:.*/)?")
+                else:
+                    parts.append(".*")
+                continue
+            # globset's default: ``*`` crosses path separators.
+            parts.append(".*")
+        elif char == "?":
+            parts.append(".")
+        elif char == "[" and (end := body.find("]", index + 1)) != -1:
+            stuff = body[index + 1 : end]
+            if stuff.startswith("!"):
+                stuff = "^" + stuff[1:]
+            parts.append(f"[{stuff}]")
+            index = end
+        else:
+            parts.append(re.escape(char))
+        index += 1
+
+    # Both ruff matchers resolve a pattern without "/" at any depth: the base
+    # walker and the mode lists (``lint.exclude = ["w.py"]`` drops
+    # ``a/b/w.py``). Only the directory-descendant suffix is base-only, since
+    # a mode list never matches a directory (#206).
+    prefix = "" if anchored else r"(?:.*/)?"
+    suffix = r"(?:/.*)?" if descendants else ""
+    return re.compile(prefix + "".join(parts) + suffix + r"\Z")
+
+
+def _compile_excludes(
+    patterns: Iterable[str], *, descendants: bool = True
+) -> tuple[_ExcludeMatcher, ...]:
+    """Compile exclude patterns in config order.
+
+    ``!`` is not a negation: ruff compiles exclude entries as globs, so a
+    leading ``!`` is an ordinary character (#206). Applying gitignore-style
+    negation here would keep a file ruff excludes and hand it to
+    ``ruff --fix``.
+    """
+    matchers: list[_ExcludeMatcher] = []
+    for pattern in patterns:
+        regex = _glob_to_regex(pattern, descendants=descendants)
+        if regex is not None:
+            matchers.append(regex)
+    return tuple(matchers)
+
+
+def _is_excluded(relative: str, matchers: tuple[_ExcludeMatcher, ...]) -> bool:
+    """Whether *relative* matches any exclude pattern."""
+    return any(regex.match(relative) for regex in matchers)
+
+
+def _relative_posix(path: Path, root: Path) -> str:
+    """*path* relative to *root* as a posix string, for pattern matching.
+
+    *root* is a resolved directory (the config's), so the plain subtraction is
+    tried first; resolving is only needed when the scan root is a symlink.
+    """
+    try:
+        return path.relative_to(root).as_posix()
+    except ValueError:
+        pass
+    try:
+        return path.resolve().relative_to(root).as_posix()
+    except (OSError, ValueError):
+        return path.as_posix()
+
+
+class FormatPathHandler:
+    """Handler for formatting paths."""
+
+    def __init__(self):
+        self.executor = FormatExecutor()
+
+    @staticmethod
+    def _as_path(path: object) -> Path:
+        """Normalise a path argument (``str`` or ``Path``-like) to ``Path``."""
+        if (
+            hasattr(path, "exists")
+            and hasattr(path, "is_file")
+            and hasattr(path, "is_dir")
+            and hasattr(path, "name")
+        ):
+            return cast("Path", path)
+        return Path(cast("str", path))
+
+    @staticmethod
+    def _is_discovered_file(path_obj: Path) -> bool:
+        """Whether a discovered ``.py`` file may be rewritten by the gate.
+
+        A symlink can point anywhere (including a virtualenv's sources), so
+        the walk never follows one (#187).
+        """
+        return path_obj.suffix == ".py" and not path_obj.is_symlink()
+
+    @staticmethod
+    def _is_named_python_file(path_obj: Path) -> bool:
+        """Whether an *explicitly named* path names a Python file to rewrite.
+
+        ``Path.is_file`` follows a symlink, and that is the point (#195): the
+        user named this path, ruff follows it too, and ``wl format <link>``
+        rewrote through it before #187 stopped the *walk* from following
+        links. ``wl format -s link.py`` silently doing nothing is the
+        regression this restores.
+        """
+        return path_obj.suffix == ".py"
+
+    @staticmethod
+    def _in_ignored_directory(path_obj: Path) -> bool:
+        """Whether any ancestor of an *explicit* path is in the ignore set."""
+        return any(_ignored_dir_name(part) for part in path_obj.parts[:-1])
+
+    def _get_all_python_files(self, path, env: dict | None = None):
+        """Get the Python files under *path* that ruff would actually format.
+
+        An explicit path is taken at face value; a directory is resolved by
+        ruff's own file resolution (#195) plus the filters ruff cannot express
+        downstream (see :meth:`_discovered_python_files`).
+        """
+        path_obj = self._as_path(path)
+        if not path_obj.exists():
+            return []
+        if path_obj.is_file():
+            if not self._is_named_python_file(path_obj):
+                return []
+            return [] if self._in_ignored_directory(path_obj) else [path_obj]
+        if not path_obj.is_dir() or _ignored_dir_name(path_obj.name):
+            return []
+        return self._discovered_python_files(path_obj, env)
+
+    def _discovered_python_files(
+        self, directory: Path, env: dict | None = None
+    ) -> list[Path]:
+        """The ``.py`` files under *directory* that ``wl format`` may rewrite.
+
+        The candidate set comes from ruff itself (:func:`_ruff_listed_files`),
+        which is the only thing that knows the *effective* base exclude:
+        built-in defaults, project config, nested configs and
+        ``respect-gitignore``. Three filters stay here because ``--show-files``
+        cannot apply them:
+
+        * the unconditional ignore set -- a project that writes its own
+          ``exclude`` replaces ruff's defaults outright, so ``.venv`` would
+          reappear (#187);
+        * symlinks -- ruff *does* list one inside a scanned directory, and it
+          may point into a virtualenv (#187);
+        * ``[tool.ruff.lint]`` / ``[tool.ruff.format] exclude`` -- ruff applies
+          those *after* the base file resolver ``--show-files`` reports, so
+          neither leg's own list is visible there (#195), and each file's
+          *nearest* config supplies them (#206).
+        """
+        listed = _ruff_listed_files(directory, env)
+        if listed is None:
+            # Ruff could not be asked; the local walk is still better than
+            # handing the directory over blindly (the failure was warned).
+            return list(self._iter_python_files(directory))
+
+        try:
+            root = directory.resolve()
+        except OSError:
+            root = directory
+        excludes = _RuffExcludes()
+
+        discovered: list[Path] = []
+        for absolute in listed:
+            relative = _relative_to_root(absolute, root)
+            if relative is None:
+                continue
+            candidate = directory / relative
+            if not self._is_discovered_file(candidate):
+                continue
+            if any(_ignored_dir_name(part) for part in relative.parts[:-1]):
+                continue
+            config_dir, _base, mode = excludes.for_directory(candidate.parent)
+            if mode and _is_excluded(_relative_posix(candidate, config_dir), mode):
+                continue
+            discovered.append(candidate)
+        return discovered
+
+    def _iter_python_files(self, directory: Path) -> Iterator[Path]:
+        """Walk *directory*, for when ruff cannot list the files itself.
+
+        Everything ruff's resolver would have applied has to be re-applied
+        here, from each file's own config: the base lists with their
+        directory semantics, the mode lists with ruff's file-path semantics.
+        """
+        excludes = _RuffExcludes()
+        for dirpath, dirnames, filenames in os.walk(directory, followlinks=False):
+            current = Path(dirpath)
+            config_dir, base, mode = excludes.for_directory(current)
+            # Base patterns are directory-aware, exactly as ruff's walker
+            # treats them: a matched directory is pruned with its contents.
+            # Mode lists never prune -- ruff matches them against file paths
+            # only (#206).
+            kept: list[str] = []
+            for name in sorted(dirnames):
+                if _ignored_dir_name(name):
+                    continue
+                candidate = current / name
+                if base and _is_excluded(_relative_posix(candidate, config_dir), base):
+                    continue
+                kept.append(name)
+            dirnames[:] = kept
+
+            for name in sorted(filenames):
+                if not name.endswith(".py"):
+                    continue
+                candidate = current / name
+                if not self._is_discovered_file(candidate):
+                    continue
+                relative = _relative_posix(candidate, config_dir)
+                if base and _is_excluded(relative, base):
+                    continue
+                if mode and _is_excluded(relative, mode):
+                    continue
+                yield candidate
+
+    def _step_by_step_processing(
+        self, paths, env, quiet, unsafe, for_lint: bool = False
+    ) -> FormatOutcome:
+        """Process files in step-by-step mode with parallel execution.
+
+        Step-by-step truncates at the first failure: a ruff/format failure
+        skips pre-commit entirely, and the *result* keeps only the first
+        failure. The executor aggregates every file (audit patch 2 / F3) --
+        truncation lives here, not there.
+
+        A directory named on the command line that is called ``rust`` also
+        goes through ``format_rust_code`` (#187): ``wl format -s rust`` used
+        to skip Rust entirely, so the step-by-step gate never judged it.
+
+        ``for_lint`` skips pre-commit (#180): ``wl lint`` owns that run
+        through ``LintExecutor.run_all``, so the format prefix must not judge
+        the same hooks a second time.
+        """
+        # Get all Python files from all specified paths
+        all_python_files: list[Path] = []
+        rust_dirs: list[Path] = []
+        for path in paths:
+            path_obj = self._as_path(path)
+            all_python_files.extend(self._get_all_python_files(path_obj, env))
+            if path_obj.is_dir() and path_obj.name == "rust":
+                rust_dirs.append(path_obj)
+
+        # Process files in parallel
+        failures: tuple[FormatFailure, ...] = ()
+        if all_python_files:
+            # Use parallel execution with caching
+            failures = self.executor.run_format_parallel(
+                all_python_files, env, quiet, unsafe
+            )
+
+        if failures:
+            # Step-by-step reports the first failure only (input order).
+            return FormatOutcome(failures[:1])
+
+        # An explicit ``rust`` path is formatted here too (#187).
+        for rust_dir in rust_dirs:
+            rust_failure = format_rust_code(str(rust_dir), env, quiet)
+            if rust_failure is not None:
+                return FormatOutcome((rust_failure,))
+
+        # Run pre-commit on all files after step-by-step processing is complete.
+        # A hook that *failed* (as opposed to merely auto-fixing) is a real
+        # failure and must make the step-by-step run red (#149). ``not
+        # for_lint`` alone decides: whether Python files were *discovered*
+        # must not gate the verdict, or a subdirectory run with none skips
+        # every hook and exits 0 (#187). ``wl lint`` runs pre-commit itself,
+        # so its prefix never lands here (#180).
+        if not for_lint:
+            pre_commit_failure = self._run_pre_commit_on_all_files(env, quiet)
+            if pre_commit_failure is not None:
+                return FormatOutcome((pre_commit_failure,))
+
+        return FormatOutcome()
+
+    def _non_step_by_step_processing(
+        self, paths, env, quiet, unsafe, for_lint: bool = False
+    ) -> tuple[FormatFailure, ...]:
+        """Process files in normal (non-step-by-step) mode.
+
+        Aggregates every failure -- ruff first, pre-commit last -- rather than
+        stopping at the first one (#164).
+
+        ``for_lint`` keeps pre-commit out of the ``wl lint`` prefix (#180): the
+        lint run owns that verdict.
+        """
+        failures: list[FormatFailure] = []
+
+        # Original behavior: process paths normally
+        for path in paths:
+            path_obj = self._as_path(path)
+
+            if path_obj.exists():
+                if path_obj.is_file() and path_obj.suffix == ".py":
+                    failure = self.executor.format_python_file(
+                        path_obj, path, env, quiet, unsafe
+                    )
+                    if failure is not None:
+                        failures.append(failure)
+                elif path_obj.is_dir():
+                    failures.extend(
+                        self._format_directory(
+                            path_obj, path, env, quiet, unsafe, for_lint
+                        )
+                    )
+            else:
+                if not quiet:
+                    print(f"Warning: Path {path} does not exist")
+
+        return tuple(failures)
+
+    def format_specified_paths(
+        self, paths, env, quiet, unsafe=False, step_by_step=False, for_lint=False
+    ) -> FormatOutcome:
+        """Format specified paths and report what failed (#164).
+
+        ``for_lint`` is the ``wl lint`` prefix (#180): it still formats, but
+        the pre-commit verdict belongs to the lint run, so it is never taken
+        here.
+        """
+        if step_by_step:
+            return self._step_by_step_processing(paths, env, quiet, unsafe, for_lint)
+        return FormatOutcome(
+            self._non_step_by_step_processing(paths, env, quiet, unsafe, for_lint)
+        )
+
+    def _format_directory(
+        self, path_obj, original_path, env, quiet, unsafe, for_lint: bool = False
+    ) -> tuple[FormatFailure, ...]:
+        """Format a directory; returns ruff failures then the pre-commit one.
+
+        ``for_lint`` drops the pre-commit verdict: ``wl lint`` runs the hooks
+        once itself, so its format prefix only formats (#180).
+        """
+        failures = list(
+            format_with_python_tools(str(path_obj), env, quiet, unsafe=unsafe)
+        )
+
+        # Special handling for rust directory; the cargo verdict is a failure
+        # like any other, never a printed warning (#187).
+        if path_obj.name == "rust":
+            rust_failure = format_rust_code(str(path_obj), env, quiet)
+            if rust_failure is not None:
+                failures.append(rust_failure)
+
+        # Run pre-commit on the directory
+        if not for_lint:
+            pre_commit_failure = self._run_pre_commit_on_directory(
+                path_obj, original_path, env, quiet
+            )
+            if pre_commit_failure is not None:
+                failures.append(pre_commit_failure)
+        return tuple(failures)
+
+    def _get_pre_commit_config_path(self):
+        """Find the pre-commit config path.
+
+        Priority: the managed ``.wl/.pre-commit-config.yaml`` of the **DEPLOY**
+        root -> ``.pre-commit-config.yaml`` (fallback).
+
+        The self-sync writes the managed file at the *deploy* root (the git
+        work-tree top), so that is where this lookup anchors too (#189).
+        Anchoring it at the PROJECT root -- as it did before -- made the file
+        invisible whenever the project root is a sub-package below the git top:
+        the fallback was a CWD-relative path that does not exist either, so
+        every hook was skipped and ``wl format`` exited 0. The root anchor
+        still comes from the process CWD (:func:`current_root`), exactly as
+        #125 established; only the *kind* moved, and the shared locator owns
+        the path itself.
+        """
+        precommit_config_path = str(
+            managed_pre_commit_config(current_root(RootKind.PROJECT).path)
+        )
+        if not os.path.exists(precommit_config_path):
+            precommit_config_path = ".pre-commit-config.yaml"
+        return precommit_config_path
+
+    def _run_git_flow_hint(self, executor, env, quiet) -> None:
+        """Run git-flow check and display simplified output for AI agent."""
+        result = executor.run(
+            ["uv", "run", "wl", "git-flow", "check"], env=env, quiet=True
+        )
+        if result.stdout:
+            info = self._parse_git_flow_output(result.stdout)
+            self._print_git_flow_info(info)
+        if result.stderr and not quiet:
+            print(result.stderr)
+
+    def _parse_git_flow_output(self, output):
+        """Parse git-flow output into a dictionary."""
+        info = {}
+        lines = output.strip().split("\n")
+        for line in lines:
+            if ":" in line and '"' in line:
+                key_part, value_part = line.split(":", 1)
+                key = key_part.strip()
+                value = value_part.strip().strip('",')
+                info[key] = value
+        return info
+
+    def _print_git_flow_info(self, info):
+        """Print git-flow info in AI-agent-friendly format."""
+        status = info.get("status")
+        if not status or status == "OK":
+            return
+
+        output_lines = [f"Git Flow [{status}]"]
+        keys_to_print = [
+            ("branch", "branch"),
+            ("branch_type", "type"),
+            ("recommended_action", "action"),
+            ("source_branch", "source_branch"),
+            ("allowed_push", "allowed_push"),
+            ("rename_required", "rename_required"),
+            ("direct_push_allowed", "direct_push_allowed"),
+            ("merge_targets", "merge_targets"),
+            ("suggested_branch_patterns", "suggested_patterns"),
+            ("next_step", "next_step"),
+        ]
+
+        for key, label in keys_to_print:
+            value = info.get(key)
+            if value:
+                output_lines.append(f"  {label}: {value}")
+
+        print("\n".join(output_lines))
+
+    def _run_pre_commit_command(
+        self, env, quiet, description=None, original_path=None
+    ) -> FormatFailure | None:
+        """Run pre-commit and report whether a hook judged the check failed.
+
+        Returns a :class:`FormatFailure` only when a hook *failed* -- the case
+        ``wl format`` has to propagate so the gate cannot go falsely green
+        (#149). A run whose only non-zero effect was auto-fixing files returns
+        ``None``: that is the expected behaviour of running formatters and must
+        stay green.
+
+        The reading of the run itself lives in
+        :class:`wl_cli.utils.pre_commit.PreCommitRun` (#165); this method only
+        chooses what format means by "no config" and how the result is shown.
+        """
+        from ...utils.subprocess_utils import SubprocessExecutor
+
+        try:
+            executor = SubprocessExecutor()
+            precommit_config_path = self._get_pre_commit_config_path()
+
+            # The single skip decision every format path reaches (#172): for
+            # ``wl format`` a missing managed config means "nothing to check",
+            # never a failure. ``_run_pre_commit_defaults`` used to repeat this
+            # check and own the only warning.
+            if not os.path.exists(precommit_config_path):
+                if not quiet:
+                    print(
+                        "Warning: .pre-commit-config.yaml not found in current directory or .wl directory, skipping pre-commit hooks"
+                    )
+                return None
+
+            self._run_git_flow_hint(executor, env, quiet)
+            if not quiet and description:
+                print(description)
+
+            # The run's exit code is deliberately *not* propagated as-is:
+            # pre-commit also exits non-zero when a hook simply rewrote files.
+            run = run_pre_commit(
+                files=None,
+                config=Path(precommit_config_path),
+                cwd=Path.cwd(),
+                env=env,
+                quiet=True,
+            )
+            hooks_failed = run.hooks_failed
+
+            # Show the same blocks the verdict was computed from (#172), and
+            # read stderr as well: a run that failed through stderr alone used
+            # to be invisible here. ``filtered_output`` stays lint's view --
+            # text filtering can include auto-fix sections the verdict ignores.
+            if run.combined_output:
+                failed_blocks = run.failed_blocks
+                if failed_blocks:
+                    for block in failed_blocks:
+                        print("\n".join(block))
+                elif hooks_failed:
+                    # Failed without any hook ``Failed`` block: pre-commit
+                    # erroring before it could judge (e.g. an invalid config).
+                    # Show what it said rather than claiming the hooks passed
+                    # while exiting non-zero.
+                    print(run.combined_output)
+                elif not quiet:
+                    print("All pre-commit hooks passed.")
+
+            if not hooks_failed:
+                return None
+
+            return FormatFailure(
+                path=Path(original_path) if original_path else Path.cwd(),
+                kind="pre_commit",
+                message="pre-commit reported a failing hook",
+                details=self._pre_commit_failure_details(run),
+            )
+
+        except Exception as e:
+            # A hook that cannot be launched at all is a *warning*, not a hook
+            # verdict: keep the historical lenient behaviour here so a machine
+            # without pre-commit does not turn ``wl format`` red.
+            if not quiet:
+                if original_path:
+                    print(f"Warning: Pre-commit failed for {original_path}: {e}")
+                else:
+                    print(f"Warning: Pre-commit failed: {e}")
+        return None
+
+    def _pre_commit_failure_details(self, run: PreCommitRun) -> tuple[str, ...]:
+        """One detail entry per failing hook, already joined into a block.
+
+        Taken straight from ``run.failed_blocks``, which already excludes
+        auto-fix blocks for the same reason they are not failures (#149): they
+        only rewrote files. When pre-commit errored before printing any hook
+        verdict there are no blocks, so the raw output is the detail.
+        """
+        details = tuple("\n".join(block) for block in run.failed_blocks)
+        if details:
+            return details
+        output = run.combined_output.strip()
+        return (output,) if output else ()
+
+    def _run_pre_commit_on_all_files(self, env, quiet) -> FormatFailure | None:
+        """Run pre-commit on all files; failure when a hook judged failure."""
+        description = "\nRunning pre-commit on all files..."
+        return self._run_pre_commit_command(env, quiet, description)
+
+    def _run_pre_commit_on_directory(
+        self, path_obj, original_path, env, quiet
+    ) -> FormatFailure | None:
+        """Run pre-commit on a directory; failure when a hook judged failure."""
+        return self._run_pre_commit_command(env, quiet, original_path=original_path)
+
+    def _step_by_step_defaults(
+        self, current_path: Path, env: dict, quiet: bool, unsafe: bool, for_lint: bool
+    ) -> FormatOutcome:
+        """Process default paths in step-by-step mode with parallel execution.
+
+        The rust branch matches the non-step-by-step default path (#180): it
+        used to be missing here, so ``wl format -s`` -- the documented
+        pre-commit quality gate -- never formatted ``rust/``.
+        """
+        src_path = current_path / "src"
+        tools_path = current_path / "tools"
+        tests_path = current_path / "tests"
+
+        # Get all Python files from all default paths
+        all_python_files = []
+        for path in [src_path, tools_path, tests_path]:
+            if path.exists():
+                python_files = self._get_all_python_files(path, env)
+                all_python_files.extend(python_files)
+
+        # Process files in parallel
+        failures: tuple[FormatFailure, ...] = ()
+        if all_python_files:
+            # Use parallel execution with caching
+            failures = self.executor.run_format_parallel(
+                all_python_files, env, quiet, unsafe
+            )
+
+        if failures:
+            # Step-by-step reports the first failure only (input order).
+            return FormatOutcome(failures[:1])
+
+        # Same rust branch as the non-step-by-step default path (#180); the
+        # cargo verdict is folded into the outcome instead of being dropped
+        # (#187).
+        rust_failure = self._format_rust_if_present(current_path, env, quiet, for_lint)
+        if rust_failure is not None:
+            return FormatOutcome((rust_failure,))
+
+        # Run pre-commit on all files after step-by-step processing is complete.
+        # A hook that *failed* (not merely auto-fixed) makes the run red (#149).
+        # ``not for_lint`` alone decides (#187): discovery results no longer
+        # gate the verdict, so a run with no Python files still judges hooks.
+        # ``wl lint`` runs pre-commit itself, so its prefix skips it (#180).
+        if not for_lint:
+            pre_commit_failure = self._run_pre_commit_on_all_files(env, quiet)
+            if pre_commit_failure is not None:
+                return FormatOutcome((pre_commit_failure,))
+
+        return FormatOutcome()
+
+    def _format_rust_if_present(
+        self, current_path: Path, env: dict, quiet: bool, for_lint: bool
+    ) -> FormatFailure | None:
+        """Format ``rust/`` under *current_path* when it exists and not linting.
+
+        Both default paths -- step-by-step and not -- go through this one
+        condition, so the two cannot drift apart (#180). ``wl lint`` skips it:
+        Rust formatting is not what lint judges (the non-step path always did).
+        A failing ``cargo fmt`` is returned so the caller can fold it into
+        ``FormatOutcome`` (#187).
+        """
+        rust_path = current_path / "rust"
+        if rust_path.exists() and not for_lint:
+            if not quiet:
+                log_info_pair("Formatting Rust code...", "正在格式化 Rust 代码...")
+            return format_rust_code(str(rust_path), env, quiet)
+        return None
+
+    def _process_python_directory(
+        self,
+        path: Path,
+        env: dict,
+        quiet: bool,
+        unsafe: bool,
+        description: tuple[str, str],
+    ) -> tuple[FormatFailure, ...]:
+        """Process a single Python directory if it exists."""
+        if path.exists():
+            if not quiet:
+                # Spelled out rather than ``*description`` so the ledger can
+                # register the pair site by name (#187).
+                log_info_pair(description[0], description[1])
+            return format_with_python_tools(str(path), env, quiet, unsafe=unsafe)
+        return ()
+
+    def _non_step_by_step_defaults(
+        self, current_path: Path, env: dict, quiet: bool, unsafe: bool, for_lint: bool
+    ) -> tuple[FormatFailure, ...]:
+        """Process default paths in normal (non-step-by-step) mode.
+
+        Collects every ruff failure (src/tools/tests) then the pre-commit
+        verdict, in that order (#164).
+        """
+        failures: list[FormatFailure] = []
+
+        # Process standard Python directories
+        directories = [
+            (
+                current_path / "src",
+                ("Formatting src directory...", "正在格式化 src 目录..."),
+            ),
+            (
+                current_path / "tools",
+                ("Formatting tools directory...", "正在格式化 tools 目录..."),
+            ),
+            (
+                current_path / "tests",
+                ("Formatting tests directory...", "正在格式化 tests 目录..."),
+            ),
+        ]
+
+        for path, description in directories:
+            failures.extend(
+                self._process_python_directory(path, env, quiet, unsafe, description)
+            )
+
+        # Type stubs generation removed from format; handled in build dist
+        rust_failure = self._format_rust_if_present(current_path, env, quiet, for_lint)
+        if rust_failure is not None:
+            failures.append(rust_failure)
+
+        # Run pre-commit on all files -- except for the ``wl lint`` prefix,
+        # whose pre-commit run belongs to ``LintExecutor.run_all`` (#180).
+        if not for_lint:
+            pre_commit_failure = self._run_pre_commit_defaults(env, quiet)
+            if pre_commit_failure is not None:
+                failures.append(pre_commit_failure)
+        return tuple(failures)
+
+    def format_defaults(
+        self,
+        current_path: Path,
+        env: dict,
+        quiet: bool,
+        unsafe: bool,
+        for_lint: bool,
+        step_by_step=False,
+    ) -> FormatOutcome:
+        """Format default paths and report what failed (#164).
+
+        ``for_lint`` marks the ``wl lint`` format prefix (#180): it formats,
+        but leaves pre-commit and Rust to the lint run.
+        """
+        if step_by_step:
+            return self._step_by_step_defaults(
+                current_path, env, quiet, unsafe, for_lint
+            )
+        return FormatOutcome(
+            self._non_step_by_step_defaults(current_path, env, quiet, unsafe, for_lint)
+        )
+
+    def _run_pre_commit_defaults(self, env: dict, quiet: bool) -> FormatFailure | None:
+        """Run pre-commit for default formatting mode.
+
+        Returns a failure when a hook judged the check failed. The missing-
+        config skip, its warning, and the one "Running pre-commit" message all
+        live in :meth:`_run_pre_commit_command`, the single choke point every
+        format entry path reaches (#172).
+        """
+        return self._run_pre_commit_on_all_files(env, quiet)