py-wlcli 0.8.0__py3-none-any.whl

wl_cli/utils/pre_commit.py

@@ -0,0 +1,266 @@
+"""What a ``pre-commit`` run means, in one place (#165).
+
+Before this module, three sets of rules read the same output: the format path
+handler classified hooks (``- hook id:`` blocks + the auto-fix marker), its
+filter decided what to show (``Failed`` lines), and the lint reporter decided
+what to report (line tails ending in ``Passed``/``Failed``). The run was also
+started two ways -- ``uv run pre-commit`` for format, a bare ``pre-commit`` for
+lint. Now both commands call :func:`run_pre_commit` and read the answer from
+:class:`PreCommitRun`.
+
+This module knows about *one run*. It does not know where the config lives, and
+it never reads the filesystem to find out -- see :func:`run_pre_commit`.
+"""
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+from pathlib import Path
+
+from .subprocess_utils import SubprocessResult
+from .uv_run import run_uv_command, uv_unavailable
+
+#: pre-commit detail line naming the hook a ``Failed`` block belongs to. It is
+#: printed for every hook pre-commit *failed* and for none it passed, which is
+#: what makes it the marker identifying a hook verdict in the run's output.
+_HOOK_ID_PREFIX = "- hook id:"
+
+#: pre-commit detail line emitted when a hook *rewrote* files -- an auto-fix,
+#: the expected outcome of running a formatter, which must leave the format
+#: gate green. The built-in fixers (``trailing-whitespace``,
+#: ``end-of-file-fixer``) exit ``1`` after rewriting and print this marker next
+#: to their ``- exit code: 1`` line; hooks that only *report* a failure print
+#: the exit-code line without it.
+_MODIFIED_MARKER = "- files were modified by this hook"
+
+
+@dataclass(frozen=True)
+class PreCommitRun:
+    """One finished ``pre-commit run``, and the verdict it carries.
+
+    The exit code alone cannot answer "did a hook judge a failure?": pre-commit
+    also exits non-zero when a hook merely rewrote files. The verdict, the
+    blocks and the filtered display text are all *derived* from ``result`` so
+    they can never disagree with each other.
+    """
+
+    result: SubprocessResult
+
+    @property
+    def stdout(self) -> str:
+        """Captured stdout (empty string, never ``None``)."""
+        return self.result.stdout or ""
+
+    @property
+    def stderr(self) -> str:
+        """Captured stderr (empty string, never ``None``).
+
+        Sits beside :attr:`stdout` because lint used to merge the two before
+        reading the verdict (#165 audit patch 1).
+        """
+        return self.result.stderr or ""
+
+    @property
+    def combined_output(self) -> str:
+        """stdout and stderr joined in that order, as lint used to see them."""
+        parts = [part for part in (self.stdout, self.stderr) if part]
+        return "\n".join(parts)
+
+    @property
+    def verdict_blocks(self) -> tuple[tuple[str, ...], ...]:
+        """One block per hook pre-commit reported, auto-fixes included.
+
+        A block is a maximal run of ``-``-prefixed lines carrying
+        pre-commit's own ``- hook id:`` line. Requiring that line is what keeps
+        other output from inventing a block: pre-commit prints it per *failing*
+        hook and never for a passing one, while hook output can contain
+        ``-``-prefixed lines of its own (``ruff`` prints `` --> file:1:8``) or a
+        line ending in the word ``Failed`` (the phantom block of #149 review
+        D2).
+        """
+        return _hook_verdict_blocks(self.stdout)
+
+    @property
+    def failed_blocks(self) -> tuple[tuple[str, ...], ...]:
+        """The verdict blocks that are real failures -- auto-fixes excluded.
+
+        Auto-fix blocks are dropped for the same reason they do not fail the
+        run (#149): they only rewrote files. ``FormatFailure.details`` is built
+        directly from this property (#164/#165).
+        """
+        return tuple(
+            block for block in self.verdict_blocks if not _is_auto_fix_block(block)
+        )
+
+    @property
+    def hooks_failed(self) -> bool:
+        """Classify the run as "a hook judged failure" or not.
+
+        ``pre-commit`` exits non-zero for two different reasons, and only one
+        of them may turn the format gate red (#149):
+
+        * a hook **rewrote files** (auto-fix) -- expected while formatting;
+        * a hook **judged the check failed** (``check-yaml`` parse error,
+          ``codespell`` hit, ...) -- must propagate.
+
+        The two are *not* told apart by the exit code. Captured from real
+        ``pre-commit`` runs, every built-in fixer exits ``1`` after rewriting
+        and prints ``- exit code: 1`` right beside
+        ``- files were modified by this hook``; a reporting hook prints the
+        exit-code line *without* that marker. So the modification marker
+        decides: **a hook that rewrote files never counts as a failure**
+        (review D1).
+
+        The accepted trade-off: a hook that rewrites files *and* leaves a real
+        violation behind (``ruff --fix`` with findings left over) reads as an
+        auto-fix and stays green. No hook in this repo's managed config behaves
+        that way -- its fixers (``end-of-file-fixer``, ``trailing-whitespace``,
+        ``ruff-format``) only rewrite, and ``ruff``/``codespell``/``check-yaml``
+        only report -- and recovering that case would cost a second full
+        pre-commit run on every dirty tree.
+
+        A non-zero exit with no hook verdict at all -- pre-commit refusing to
+        run, e.g. an invalid config -- is a real failure as well.
+        """
+        if self.result.returncode == 0:
+            return False
+
+        blocks = self.verdict_blocks
+        if blocks and all(_is_auto_fix_block(block) for block in blocks):
+            # Non-zero *only* because hooks rewrote files: not a failure.
+            return False
+        return True
+
+    @property
+    def filtered_output(self) -> str | None:
+        """Only the sections pre-commit marked failed -- lint's display view.
+
+        Passing hooks print nothing but their ``Passed`` header, so the filter
+        drops their header lines and keeps each failed hook's detail lines --
+        including stderr, which lint used to append to the stdout it filtered.
+        Returns ``None`` when nothing failed.
+
+        This is deliberately **not** what ``wl format`` shows (#172). Format's
+        display has to agree with the verdict it reports: it prints
+        :attr:`failed_blocks` (the same blocks :attr:`hooks_failed` was
+        computed from) and falls back to :attr:`combined_output` when
+        pre-commit failed before printing any hook verdict. Text-filtered
+        output can include auto-fix sections the verdict ignores, and can hide
+        a stderr-only failure; the blocks cannot.
+        """
+        return _filter_failed_sections(self.combined_output)
+
+
+def _hook_verdict_blocks(output: str) -> tuple[tuple[str, ...], ...]:
+    """Group pre-commit output into one detail block per reported hook."""
+    blocks: list[list[str]] = []
+    current: list[str] = []
+    for line in output.splitlines():
+        stripped = line.strip()
+        if stripped.startswith("-"):
+            current.append(stripped)
+        elif current:
+            blocks.append(current)
+            current = []
+    if current:
+        blocks.append(current)
+    return tuple(
+        tuple(block)
+        for block in blocks
+        if any(line.startswith(_HOOK_ID_PREFIX) for line in block)
+    )
+
+
+def _is_auto_fix_block(block: tuple[str, ...]) -> bool:
+    """True when this failing hook's only effect was rewriting files."""
+    return any(_MODIFIED_MARKER in line for line in block)
+
+
+def _filter_failed_sections(text: str) -> str | None:
+    """Keep the failed hooks' header and detail lines; drop the passed ones."""
+    filtered: list[str] = []
+    in_failure = False
+    for line in text.splitlines():
+        stripped = line.strip()
+        if stripped.endswith("Passed"):
+            in_failure = False
+            continue
+        if stripped.endswith("Failed"):
+            in_failure = True
+            filtered.append(line)
+        elif in_failure:
+            filtered.append(line)
+    return "\n".join(filtered) if filtered else None
+
+
+def run_pre_commit(
+    *,
+    files: Sequence[str] | None,
+    config: Path | None,
+    cwd: Path,
+    env: dict[str, str] | None = None,
+    quiet: bool = True,
+    prefer_uv: bool = True,
+) -> PreCommitRun:
+    """Run ``pre-commit run`` once and return its :class:`PreCommitRun`.
+
+    With ``prefer_uv`` the run starts as ``uv run pre-commit`` (the formatters'
+    launcher); otherwise it starts as the bare ``pre-commit`` on ``PATH`` (what
+    ``wl lint`` wants -- it already runs inside the project environment and
+    does not need uv re-resolving it). Either launcher falls back to the other
+    when ``uv_unavailable`` says it never ran -- a ``launch_error``, or the
+    shell's ``127`` "command not found" -- so a machine with only one of the
+    two still runs the hooks.
+
+    ``config=None`` means *let pre-commit use its own config discovery* and
+    nothing else. This function never probes the filesystem: what a missing
+    config means is the caller's explicit choice (#165 audit patch 2). ``wl
+    format`` skips the run when its managed config is absent; ``wl lint`` falls
+    back to the default discovery by passing ``None``.
+
+    Args:
+        files: Paths to check; ``None`` or an empty sequence means
+            ``--all-files``. An empty sequence used to reach pre-commit as
+            "no paths", which silently checks only the staged files instead of
+            everything (#172).
+        config: Explicit config path, or ``None`` for pre-commit's discovery.
+        cwd: Directory the run happens in (lint runs from the project root).
+        env: Environment for the child process.
+        quiet: Whether to capture the child's output.
+        prefer_uv: Start through ``uv run``; ``False`` starts with the bare
+            ``pre-commit`` executable.
+
+    Returns:
+        The finished run; its ``result`` may still carry ``launch_error``.
+    """
+    # Resolved at call time so patching the class -- the seam both callers
+    # already use for their other children (``lint_executor``'s ruff/mypy
+    # runs, the git-flow hint in the same format handler) -- intercepts this
+    # run too. Each caller still builds its own instance, here and in the
+    # handler; the class is the one patch point, not a shared instance.
+    from .subprocess_utils import SubprocessExecutor
+
+    command = ["pre-commit", "run"]
+    if not files:
+        command.append("--all-files")
+    else:
+        command.extend(files)
+    if config is not None:
+        command.extend(["--config", str(config)])
+
+    executor = SubprocessExecutor()
+    if prefer_uv:
+        result = run_uv_command(
+            executor, ["uv", "run", *command], env=env, cwd=cwd, quiet=quiet
+        )
+    else:
+        result = executor.run(command, env=env, cwd=cwd, quiet=quiet)
+        if uv_unavailable(result):
+            # The bare launcher never started: retry once through ``uv run``,
+            # the launcher ``wl format`` starts with.
+            try:
+                result = executor.run(
+                    ["uv", "run", *command], env=env, cwd=cwd, quiet=quiet
+                )
+            except Exception:
+                pass
+    return PreCommitRun(result)

wl_cli/utils/pre_commit_config.py

@@ -0,0 +1,72 @@
+"""Where the managed pre-commit config lives -- one answer, DEPLOY-anchored (#189).
+
+The self-sync writes ``.wl/.pre-commit-config.yaml`` at the **DEPLOY** root
+(``wl_dir_updater`` -> ``setup_handler`` -> ``generate_configs(context.deploy)``),
+while ``wl format`` and ``wl lint`` used to look it up at the **PROJECT** root.
+In the ``git root > sub-package with its own pyproject.toml`` layout the two
+roots differ, so the managed config written at the git top was invisible from
+the sub-package: ``wl format`` skipped every hook and exited 0, and ``wl lint``
+handed pre-commit a root with no config (``InvalidConfigError``), staying red
+forever.
+
+:func:`managed_pre_commit_config` is the single definition of that location;
+both consumers take the path from it and keep only their own *missing config*
+policy (format skips the run, lint falls back to pre-commit's own discovery).
+Nothing else is re-anchored: the file-tool scopes (ruff, mypy) stay where they
+were -- only this one lookup moves from PROJECT to DEPLOY.
+
+The anchor is deliberately **narrow**: DEPLOY is the git work-tree top whenever
+there is one, so a ``.wl/.pre-commit-config.yaml`` placed by hand inside a
+sub-package is *not* adopted in that layout -- the only managed config consulted
+is the one at the work-tree top. That exclusion is the anchor alone: this module
+never reads ``config.json`` and never probes for the config file, so whether a
+by-hand copy happens to sit next to a ``config.json`` changes nothing (the
+``LEGACY`` kind is the only root-resolution rule that looks at ``config.json``).
+With no work tree, DEPLOY falls back to the project-marker root, which can
+legitimately be the sub-package itself. One step further, when *start* is in no
+work tree and no project marker (``.wl`` directory / ``pyproject.toml`` file)
+sits at or above it, the caller-side fallback policy
+(:func:`~wl_cli.utils.root_fallback.resolve_root_or_start`, the one place ADR
+0006 puts that policy) substitutes *start* itself -- so a bare directory yields
+``<start>/.wl/.pre-commit-config.yaml``. This is a decision, not an accident:
+one anchor is what makes format and lint agree. It is recorded in
+``docs/adr/0008-managed-pre-commit-config-anchored-at-deploy-root.md`` and
+pinned by ``tests/test_managed_pre_commit_config_203.py``.
+"""
+
+from pathlib import Path
+
+from .root import RootKind
+from .root_fallback import resolve_root_or_start
+
+#: The managed control file's name inside a root's ``.wl`` directory.
+_MANAGED_CONFIG_NAME = ".pre-commit-config.yaml"
+
+
+def managed_pre_commit_config(start: Path) -> Path:
+    """The managed ``.wl/.pre-commit-config.yaml`` of *start*'s DEPLOY root.
+
+    *start* is the anchor the caller already holds -- ``wl format`` passes its
+    ``PROJECT`` root, ``wl lint`` the project root it runs from -- and the
+    **DEPLOY** root is resolved from it here, once, because that is where the
+    self-sync writes the file: the git work-tree top when there is one, else
+    the project marker root. Passing the PROJECT root is therefore right in
+    both layouts: when the two coincide the answer is unchanged (#125), and in
+    the sub-package layout it climbs to the git top where the file actually is
+    (#189).
+
+    The anchor has one step more than ``utils/root.py``'s own ``DEPLOY`` rule:
+    when *start* is in no git work tree and no project marker sits at or above
+    it, :func:`~wl_cli.utils.root_fallback.resolve_root_or_start` substitutes
+    *start* itself (ADR 0006's caller-side fallback, not part of the root
+    module's rule), so the derived path is ``<start>/.wl/.pre-commit-config.yaml``.
+
+    The path is **derived, never probed**: this function does not check whether
+    the config file exists, so each caller keeps its own decision about what a
+    missing config means. Deriving it is not I/O-free, though -- resolving the
+    DEPLOY root runs ``git rev-parse --show-toplevel`` and, when that misses,
+    stats the project markers on the way up. What it never does is *look for the
+    config*: no existence probe, no walk past the anchor hunting for another
+    copy.
+    """
+    return resolve_root_or_start(start, RootKind.DEPLOY).wl_dir() / _MANAGED_CONFIG_NAME