py-wlcli 0.8.0__py3-none-any.whl

wl_cli/commands/gate/preflight.py

@@ -0,0 +1,445 @@
+"""``wl gate`` step 0 -- preflight: can the chain actually run on this machine?
+
+The gate only earns its keep as a *trustworthy* local signal if its red always
+means "your change is bad" and never "this machine is incomplete" (issue #98).
+So before the four-step chain runs, ``wl gate`` checks -- read-only -- that the
+**subjects it is about to execute** are actually available. If anything is
+missing it fails fast with a named, actionable error and a distinct exit code,
+and the chain is never entered, so no phantom failure lines are produced.
+
+The subject is the whole point (review F1). The chain never runs
+``sys.executable``: it runs the bare ``ruff`` / ``mypy`` / ``wl`` that PATH
+resolves for it, and the pytest plugins inside whatever interpreter the test
+runner picks. Probing ``sys.executable`` answered a different question, which
+produced both a false red (a globally installed ``wl`` carries no project test
+extras, so the gate refused to run a chain that would have worked) and a false
+green (a bare PATH failure surfaced as ``ruff check - FAILED (exit -1)`` and an
+undocumented exit 255).
+
+So nothing here is hand-written twice: the executable list is derived from the
+chain's own ``build_steps()``, the plugin interpreter from the test step's own
+declared ``cwd`` fed to :class:`PythonEnvDetector`, and the PATH the executables
+are resolved against from the executor that will run them
+(``SubprocessExecutor.subprocess_path`` -- the chain does *not* necessarily
+search this process' own ``PATH``, because uv-tool runs have it rewritten).
+:func:`evaluate` stays a pure function over observations so it can be
+unit-tested without installing anything; :func:`observe` is the only part that
+touches the machine, and it only looks things up.
+
+A step that is *killed by a signal* is a different animal from a missing
+subject, and is reported as such (review N1). Such a step ran -- PATH resolved
+its executable and it was launched -- and then died, so it gets its own message
+and the shell's ``128 + signum`` exit code, never the environment-gap code.
+Collapsing the two, as the old fallback did, told the reader to go fix the
+machine when the cause could just as well be the change under test (a suite
+that grows until the runner is OOM-killed is one signal away from this path).
+"""
+
+from __future__ import annotations
+
+import contextlib
+import io
+import shutil
+import signal
+import subprocess
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from ...utils.subprocess_utils import SubprocessExecutor
+from ..testcommands.python_env_detector import PythonEnvDetector
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping, Sequence
+    from pathlib import Path
+
+    from .gate_command import GateStep
+
+EXIT_ENV_MISSING = 78
+"""Exit code for "the environment cannot run the chain".
+
+Chosen so it cannot collide with any code the four-step chain produces on its
+own (``ruff check``/``ruff format``/``mypy``: 0-2; pytest: 0-5, including the
+``INTERNALERROR`` code 3 that a broken coverage environment yields; Click usage
+errors: 2). Callers can therefore tell "go fix the environment" apart from "go
+fix your change" mechanically. 78 is ``EX_CONFIG`` from ``sysexits.h`` -- a
+configuration (here: environment) error.
+
+There is no third exit path: a step whose executable cannot even be launched is
+reported through this same code (:func:`render_launch_error`) rather than
+leaking the executor's sentinel ``-1``, which ``sys.exit`` would turn into an
+undocumented 255.
+
+A step that was *launched and then killed by a signal* is deliberately **not**
+reported through this code: see :data:`EXIT_SIGNALLED_BASE`.
+"""
+
+EXIT_SIGNALLED_BASE = 128
+"""Base for "a gate step was terminated by a signal" exit codes.
+
+A signalled process is not an environment gap. The step ran -- PATH resolved
+its executable and it was launched -- and then died, so its code follows the
+POSIX shell convention ``128 + signum`` (SIGKILL(9) -> 137, SIGTERM(15) -> 143).
+Because ``signum >= 1``, every such code is ``>= 129`` and can therefore never
+collide with :data:`EXIT_ENV_MISSING` (78) or with any step's own code
+(``ruff``/``mypy``/``format``: 0-2; pytest: 0-5). Callers can thus tell "go fix
+the environment" (78) apart from "this step, and possibly your change, died"
+(``128 + N``) mechanically.
+"""
+
+
+def signal_exit_code(signum: int) -> int:
+    """The exit code a POSIX shell reports for a process killed by *signum*."""
+    return EXIT_SIGNALLED_BASE + signum
+
+
+FIX_COMMAND = 'uv pip install -e ".[dev,test]"'
+"""Provisions the ``test`` extra's plugins (the module requirements below)."""
+
+
+@dataclass(frozen=True)
+class Requirement:
+    """One thing the chain needs, and how to check for it.
+
+    ``kind`` decides how :func:`observe` answers:
+
+    * ``"binary"`` -- the chain will exec this token, so PATH must resolve it.
+    * ``"module"`` -- the chain's test runner will import this name, so it must
+      import inside the interpreter that runner picks.
+    """
+
+    label: str
+    """User-facing name, as reported when it is missing."""
+
+    key: str
+    """Executable token (binary) or import name (module)."""
+
+    kind: str
+    """Either ``"binary"`` or ``"module"``."""
+
+    source: str
+    """Where the requirement comes from, for the error message."""
+
+    fix: str
+    """The command or action that supplies it."""
+
+
+#: The pytest plugins the chain's test step imports. These ride in the project's
+#: ``test`` extra, so they are probed as *modules* -- in the interpreter the test
+#: runner will use, never in the interpreter driving the gate.
+MODULE_REQUIREMENTS: tuple[Requirement, ...] = (
+    Requirement(
+        "pytest",
+        "pytest",
+        "module",
+        "imported by the pytest step",
+        FIX_COMMAND,
+    ),
+    Requirement(
+        "pytest-cov",
+        "pytest_cov",
+        "module",
+        "imported by the pytest step",
+        FIX_COMMAND,
+    ),
+    Requirement(
+        "pytest-asyncio",
+        "pytest_asyncio",
+        "module",
+        "imported by the pytest step",
+        FIX_COMMAND,
+    ),
+)
+
+
+@dataclass(frozen=True)
+class PreflightReport:
+    """The verdict: which requirements (if any) this machine cannot supply."""
+
+    subjects: tuple[str, ...]
+    """What was probed, for the error message."""
+
+    required: tuple[Requirement, ...]
+    """The rule set that was applied."""
+
+    missing: tuple[Requirement, ...]
+
+    @property
+    def ok(self) -> bool:
+        """True when every requirement is available."""
+        return not self.missing
+
+
+def requirements_for(steps: Sequence[GateStep]) -> tuple[Requirement, ...]:
+    """Derive what the chain will execute, from the chain itself.
+
+    Single source of truth: the executable tokens come out of the very step
+    commands that will be run, so the two can never drift apart.
+
+    A step that will be **skipped** contributes nothing (rv193/M2). The
+    pre-commit leg declares the managed config it needs; when that file is
+    absent the step is jumped over at execution time, so demanding its
+    executable here would refuse to start a chain whose hook leg was never
+    going to launch anything -- a 78 over a leg the gate itself skips. The
+    judgement is *not* re-made here: it is :attr:`GateStep.is_skipped`, the same
+    property the executing loop reads, so the two cannot disagree about which
+    steps the chain will run.
+    """
+    provenance: dict[str, list[str]] = {}
+    for index, step in enumerate(steps, start=1):
+        if step.is_skipped:
+            continue
+        provenance.setdefault(step.command[0], []).append(f"step {index} ({step.name})")
+
+    binaries = tuple(
+        Requirement(
+            label=token,
+            key=token,
+            kind="binary",
+            source="needed by " + ", ".join(where),
+            fix='uv pip install -e ".[dev]" (or activate the project environment)',
+        )
+        for token, where in provenance.items()
+    )
+    return binaries + MODULE_REQUIREMENTS
+
+
+def interpreter_anchor(steps: Sequence[GateStep]) -> Path | None:
+    """The directory whose interpreter the chain's test step will run in.
+
+    Read straight off the step that flags itself ``probe_interpreter`` -- the
+    ``wl test`` leg -- using that step's own ``cwd``, the very field
+    :meth:`GateCommand.execute
+    <wl_cli.commands.gate.gate_command.GateCommand.execute>` hands the executor.
+    Nothing here re-derives a root: the judged anchor *is* the executed step's
+    declared working directory, so the two cannot drift apart (issue #110).
+
+    ``None`` when no step claims the interpreter -- the historical, CWD-relative
+    probe, kept for callers that build a bare chain.
+    """
+    for step in steps:
+        if step.probe_interpreter:
+            return step.cwd
+    return None
+
+
+def test_interpreter(anchor_root: Path | None = None) -> str:
+    """The interpreter the chain's test step runs pytest with.
+
+    Reused from the chain rather than reimplemented: ``PythonEnvDetector`` is
+    exactly what ``wl test`` consults to pick that interpreter, so asking
+    anything else would judge a different subject than the one that executes.
+    Its chatty ``print`` is captured so the gate's own output stays parseable.
+
+    *anchor_root* is the directory that test step runs in -- for the real chain
+    it comes from :func:`interpreter_anchor`, i.e. the pytest step's own
+    ``cwd``, and the ``wl test`` subprocess it launches resolves *its*
+    interpreter from that same directory. Anchoring the detector here is what
+    keeps the claim below true: without it a gate invoked from anywhere else
+    asked about the caller's CWD while the chain ran elsewhere, so preflight
+    judged one interpreter and the chain ran another (issue #110). The
+    un-anchored default -- ``None`` -- is byte-for-byte the pre-#110 behaviour.
+    """
+    sink = io.StringIO()
+    with contextlib.redirect_stdout(sink):
+        return PythonEnvDetector(anchor_root).get_python_executable()
+
+
+def evaluate(
+    required: Sequence[Requirement],
+    subjects: Sequence[str],
+    observations: Mapping[str, bool],
+) -> PreflightReport:
+    """Decide which of *required* are missing. Pure: performs no I/O.
+
+    Args:
+        required: The rule set to apply.
+        subjects: What *observations* were taken from; carried into the report
+            so the error can name them.
+        observations: Availability keyed by ``Requirement.key``, as measured by
+            :func:`observe` (or fabricated by a test). A requirement with no
+            observation counts as missing.
+    """
+    missing = tuple(
+        requirement
+        for requirement in required
+        if not observations.get(requirement.key, False)
+    )
+    return PreflightReport(
+        subjects=tuple(subjects), required=tuple(required), missing=missing
+    )
+
+
+def observe(
+    required: Sequence[Requirement],
+    interpreter: str,
+    search_path: str | None = None,
+) -> dict[str, bool]:
+    """Look up every requirement. Read-only: resolves PATH, imports modules.
+
+    Nothing is installed, nothing is written, and no network is touched.
+
+    *search_path* is the ``PATH`` the chain's own subprocesses resolve a bare
+    ``ruff`` / ``mypy`` / ``wl`` against. It defaults to
+    :meth:`SubprocessExecutor.subprocess_path` -- the executor's own answer --
+    rather than to this process' ``PATH``, because the executor rewrites that
+    variable for uv-tool runs (``get_uv_tool_env`` prepends ``UV_TOOL_DIR``).
+    Probing the process ``PATH`` there judges a different path than the one that
+    executes, and can refuse a chain the child could have run (F1 residual).
+    """
+    if search_path is None:
+        search_path = SubprocessExecutor().subprocess_path()
+    observed = {
+        requirement.key: shutil.which(requirement.key, path=search_path) is not None
+        for requirement in required
+        if requirement.kind == "binary"
+    }
+    names = [
+        requirement.key for requirement in required if requirement.kind == "module"
+    ]
+    observed.update(_probe_modules(names, interpreter))
+    return observed
+
+
+def run_preflight(steps: Sequence[GateStep]) -> PreflightReport:
+    """Probe and judge the subjects *steps* will run, in one call.
+
+    The interpreter to probe is taken from the steps themselves -- the test
+    step's own ``cwd`` (see :func:`interpreter_anchor`) -- so there is no
+    separate root argument to hand over and no way for the judged root to
+    differ from the executed one (issue #110). A chain whose steps name no test
+    interpreter falls back to the historical, CWD-relative probe.
+    """
+    required = requirements_for(steps)
+    interpreter = test_interpreter(interpreter_anchor(steps))
+    subjects = ("PATH (the executables the chain runs)", interpreter)
+    return evaluate(required, subjects, observe(required, interpreter))
+
+
+def render_env_error(report: PreflightReport) -> str:
+    """Render the environment gap: named, actionable, not a step failure."""
+    return _frame(
+        [
+            f"  probed: {', '.join(report.subjects)}",
+            f"  missing {len(report.missing)} of {len(report.required)} required items:",
+        ],
+        [
+            f"{item.label}  ({item.source})\n      fix: {item.fix}"
+            for item in report.missing
+        ],
+    )
+
+
+def render_launch_error(step_name: str, executable: str) -> str:
+    """Render a step whose executable could not be launched at all.
+
+    A binary that survived preflight but cannot be exec'd is still an
+    environment problem, so it gets the environment shape and code -- not a
+    ``FAILED`` line, and never the executor's sentinel turned into 255.
+
+    The bullet no longer claims "PATH no longer resolves it": preflight already
+    proved PATH *did* resolve it, so an exec failure here is the kernel
+    refusing to run a file it found (removed in the race, or not executable),
+    and the old wording asserted a cause it had not established (review N1).
+    """
+    return _frame(
+        [f"  step: {step_name}"],
+        [
+            f"could not launch '{executable}' -- it was on PATH, but executing "
+            "it failed (removed since the check, or not executable)"
+        ],
+    )
+
+
+def render_signal_error(step_name: str, executable: str, signum: int) -> str:
+    """Render a step whose process was killed by a signal.
+
+    The step *ran*: PATH resolved *executable*, it was launched, and it then
+    died from signal *signum*. So this must not borrow the environment-gap
+    shape -- "the quality chain was NOT run" and "PATH no longer resolves it"
+    would both be false (review N1), and they sent the reader to fix the
+    machine when the cause could just as well be the change under test. It is
+    reported as a signalled step, with the shell's ``128 + signum`` code.
+    """
+    return "\n".join(
+        [
+            f"wl gate: step '{step_name}' was killed by signal {signum} "
+            f"({_signal_name(signum)}).",
+            f"  command: {executable}",
+            "  the step ran and was then signalled, so this is NOT an environment gap:",
+            "  the chain was entered (its earlier lines stand) and "
+            f"'{executable}' was resolved by PATH.",
+            (
+                f"  note: exit code {signal_exit_code(signum)} (128 + {signum}) means "
+                "'a step was signalled', not 'the environment is missing' "
+                f"({EXIT_ENV_MISSING}) -- check the step and the change, not the "
+                "machine."
+            ),
+        ]
+    )
+
+
+def _signal_name(signum: int) -> str:
+    """The conventional name for *signum*, or a readable fallback if unknown."""
+    try:
+        return signal.Signals(signum).name
+    except ValueError:
+        return f"unknown signal {signum}"
+
+
+def _frame(detail: Sequence[str], bullets: Sequence[str]) -> str:
+    """The shared envelope for every ``EXIT_ENV_MISSING`` message.
+
+    Deliberately shaped *unlike* a step result: no ``[i/n]`` numbering and no
+    ``FAILED`` token, so an environment gap can never be mistaken for a step
+    that ran and failed.
+    """
+    return "\n".join(
+        [
+            "wl gate: environment is incomplete - the quality chain was NOT run.",
+            *detail,
+            "  missing required items:",
+            *(f"    - {bullet}" for bullet in bullets),
+            (
+                f"  note: exit code {EXIT_ENV_MISSING} means 'environment problem', "
+                "not 'your change is broken'."
+            ),
+        ]
+    )
+
+
+def _probe_modules(names: Sequence[str], interpreter: str) -> dict[str, bool]:
+    """Ask *interpreter* which of *names* it can import.
+
+    Each module is imported for real rather than merely located: a broken
+    install could not run a gate step either.
+
+    One module per probe process, and the verdict is that process' **exit
+    status** -- never a parse of its stdout. A module that imports fine is free
+    to print whatever it likes; the old ``set(result.stdout.split())`` reader
+    took any token it printed for the name of a *failed* requirement, so a
+    chatty ``pytest_cov`` could have turned a working environment into a
+    phantom gap (review F5).
+    """
+    return {name: _imports(interpreter, name) for name in names}
+
+
+def _imports(interpreter: str, name: str) -> bool:
+    """True when *interpreter* can import *name*, judged by its exit status."""
+    try:
+        result = subprocess.run(
+            [interpreter, "-c", _PROBE_SOURCE, name],
+            capture_output=True,
+            text=True,
+            timeout=60,
+            check=False,
+        )
+    except (OSError, subprocess.SubprocessError):
+        # The interpreter itself could not be driven: nothing is verified.
+        return False
+    return result.returncode == 0
+
+
+# Imports the name given on argv; the interpreter's own exit status is the
+# answer, so nothing the module prints can be mistaken for a verdict. Run
+# inside the target interpreter so the answer describes *that* environment.
+_PROBE_SOURCE = "import importlib, sys; importlib.import_module(sys.argv[1])"

wl_cli/commands/git/__init__.py

@@ -0,0 +1 @@
+"""Git Flow commands and policy helpers."""

wl_cli/commands/git/config.py

@@ -0,0 +1,169 @@
+"""Git Flow configuration loading."""
+
+from __future__ import annotations
+
+from copy import deepcopy
+from typing import TYPE_CHECKING, Any, cast
+
+try:
+    from yaml import YAMLError
+except ImportError:
+    YAMLError = ValueError
+
+from ...utils.root import RootKind
+from ...utils.root_fallback import current_root
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+class GitFlowConfigError(ValueError):
+    """Raised when Git Flow configuration is malformed."""
+
+
+class GitFlowConfig:
+    DEFAULT_CONFIG: dict[str, Any] = {
+        "branches": {
+            "main": {"name": "main", "protected": True, "require_pr": True},
+            "develop": {"name": "develop", "protected": True, "require_pr": True},
+            "feature": {
+                "prefix": "feature/",
+                "source": "develop",
+                "merge_to": "develop",
+            },
+            "release": {
+                "prefix": "release/",
+                "source": "develop",
+                "merge_to": ["main", "develop"],
+                "require_version": True,
+                "require_changelog": True,
+            },
+            "hotfix": {
+                "prefix": "hotfix/",
+                "source": "main",
+                "merge_to": ["main", "develop"],
+                "require_version": True,
+                "require_changelog": True,
+            },
+        },
+        "version": {"file": "VERSION"},
+        "changelog": {"file": "CHANGELOG.md"},
+    }
+
+    def __init__(self, config_path: Path | None = None) -> None:
+        # Root-anchored (#125): the deploy root's ``.wl`` -- the directory the
+        # vendored pre-push hook reads from (git runs hooks with CWD = the
+        # work-tree top, which is exactly this root) -- not the process CWD's,
+        # so ``wl git-flow`` from a subdirectory reads the root's policy rather
+        # than silently falling back to the built-in defaults.
+        self.config_path = config_path or (
+            current_root(RootKind.DEPLOY).wl_dir() / "git-flow.yaml"
+        )
+        self._config = self._load_config()
+
+    @property
+    def config_source(self) -> str:
+        if self.config_path.exists():
+            return str(self.config_path)
+        return "built-in defaults"
+
+    @property
+    def main_branch(self) -> str:
+        return cast("str", self._config["branches"]["main"]["name"])
+
+    @property
+    def develop_branch(self) -> str:
+        return cast("str", self._config["branches"]["develop"]["name"])
+
+    def branch_prefix(self, branch_type: str) -> str:
+        return cast("str", self._config["branches"][branch_type]["prefix"])
+
+    def source_branch(self, branch_type: str) -> str:
+        return cast("str", self._config["branches"][branch_type]["source"])
+
+    def merge_targets(self, branch_type: str) -> list[str]:
+        targets = self._config["branches"][branch_type]["merge_to"]
+        if isinstance(targets, str):
+            return [targets]
+        return list(targets)
+
+    def _load_config(self) -> dict[str, Any]:
+        config = deepcopy(self.DEFAULT_CONFIG)
+        if not self.config_path.exists():
+            return config
+
+        try:
+            import yaml
+
+            loaded = yaml.safe_load(self.config_path.read_text(encoding="utf-8"))
+        except ImportError as exc:
+            raise GitFlowConfigError(
+                f"{self.config_path}: PyYAML is required to read Git Flow config "
+                "(bundled in the lfs extra). "
+                "Install with: pip install py_wlcli[lfs]"
+            ) from exc
+        except YAMLError as exc:
+            raise GitFlowConfigError(
+                f"{self.config_path}: invalid YAML: {exc}"
+            ) from exc
+
+        if loaded is None:
+            return config
+        if not isinstance(loaded, dict):
+            raise GitFlowConfigError(f"{self.config_path}: config must be a mapping")
+
+        self._validate_known_keys(loaded)
+        return self._deep_merge(config, loaded)
+
+    def _validate_known_keys(self, config: dict[str, Any]) -> None:
+        branches = config.get("branches")
+        if branches is None:
+            return
+        if not isinstance(branches, dict):
+            raise GitFlowConfigError(f"{self.config_path}: branches must be a mapping")
+
+        for branch_type, branch_config in branches.items():
+            if branch_type not in self.DEFAULT_CONFIG["branches"]:
+                continue
+            path = f"branches.{branch_type}"
+            if not isinstance(branch_config, dict):
+                raise GitFlowConfigError(
+                    f"{self.config_path}: {path} must be a mapping"
+                )
+            for key, value in branch_config.items():
+                if key not in self.DEFAULT_CONFIG["branches"][branch_type]:
+                    continue
+                self._validate_branch_value(path, key, value)
+
+    def _validate_branch_value(self, path: str, key: str, value: Any) -> None:
+        full_path = f"{path}.{key}"
+        if key in {"name", "prefix", "source"} and not isinstance(value, str):
+            raise GitFlowConfigError(
+                f"{self.config_path}: {full_path} must be a string"
+            )
+        if key == "merge_to":
+            if isinstance(value, str):
+                return
+            if isinstance(value, list) and all(isinstance(item, str) for item in value):
+                return
+            raise GitFlowConfigError(
+                f"{self.config_path}: {full_path} must be a string or list of strings"
+            )
+        if key in {"protected", "require_pr", "require_version", "require_changelog"}:
+            if not isinstance(value, bool):
+                raise GitFlowConfigError(
+                    f"{self.config_path}: {full_path} must be a boolean"
+                )
+
+    def _deep_merge(
+        self, base: dict[str, Any], override: dict[str, Any]
+    ) -> dict[str, Any]:
+        result = deepcopy(base)
+        for key, value in override.items():
+            if key not in result:
+                continue
+            if isinstance(result[key], dict) and isinstance(value, dict):
+                result[key] = self._deep_merge(result[key], value)
+            else:
+                result[key] = deepcopy(value)
+        return result

wl_cli/commands/git/git_facts.py

@@ -0,0 +1,60 @@
+"""Git facts used by Git Flow policy adapters."""
+
+from __future__ import annotations
+
+import subprocess
+
+
+def get_current_branch() -> str:
+    result = subprocess.run(
+        ["git", "rev-parse", "--abbrev-ref", "HEAD"],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if result.returncode != 0:
+        return ""
+    return result.stdout.strip()
+
+
+def get_changed_files(
+    source_branch: str,
+    file_filters: list[str] | None = None,
+    cwd: str | None = None,
+) -> frozenset[str]:
+    """Return files changed between ``source_branch`` and ``HEAD``.
+
+    When the local ``source_branch`` ref is absent (common in shallow/CI-style
+    clones that only carry ``origin/<source_branch>``), retry the diff against
+    the remote-tracking branch before falling back to an empty result.
+    """
+    cmd = [
+        "git",
+        "diff",
+        "--name-only",
+        f"{source_branch}...HEAD",
+    ]
+    if file_filters:
+        cmd.extend(["--", *file_filters])
+
+    result = subprocess.run(
+        cmd,
+        capture_output=True,
+        text=True,
+        check=False,
+        cwd=cwd,
+    )
+    if result.returncode != 0:
+        # The local <source_branch> may be missing; retry against
+        # origin/<source_branch> before treating the diff as "no changes".
+        cmd[3] = f"origin/{source_branch}...HEAD"
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            check=False,
+            cwd=cwd,
+        )
+        if result.returncode != 0:
+            return frozenset()
+    return frozenset(line for line in result.stdout.splitlines() if line)