py-wlcli 0.8.0__py3-none-any.whl

wl_cli/utils/root_fallback.py

@@ -0,0 +1,256 @@
+"""The one place ADR 0006's caller-side CWD fallback policy is implemented.
+
+``utils/root.py`` answers "which root does this starting point belong to" and
+reports "no root found" as ``None`` -- it performs no fallback of its own. *What
+to do* with that ``None`` is the caller's policy, and ADR 0006
+(``docs/adr/0006-root-resolution-layering.md``) commits to implementing it in
+exactly one place at the CLI top level. This module is that place.
+
+The policy is one rule: a ``wl`` run from a directory that belongs to no root is
+not an error, so the starting directory itself is used as the root, labelled
+with the kind the caller asked for. Before #126 that rule was written out at
+every call site -- sixteen markers across nine files, converging on nine real
+landing points, several of them byte-identical copies of the same three lines --
+and they now all route through :func:`resolve_root_or_start`.
+
+Two properties are load-bearing and deliberate:
+
+* **It takes the kind.** Both the ``PROJECT`` and ``DEPLOY`` roots fall back the
+  same way, so the rule is parameterised by kind rather than copied per kind.
+* **It never touches *start*.** ``resolve`` answers for the *resolved* spelling
+  of its input, but every old resolver fell back to the spelling the caller
+  actually passed. So this function uses *start* verbatim -- as the ``resolve``
+  input and as the fallback answer's ``path`` -- and leaves canonicalisation to
+  the caller. The callers that resolved their start through a ``_start_directory``
+  helper still do (keeping their fallback byte-identical to the answer it
+  replaces), and ``ConfigPathResolver.get_default_config_path`` keeps passing its
+  *un-resolved* ``Path.cwd()`` exactly as before.
+
+This module is deliberately **not** part of ``utils/root.py``: that module's
+whole contract is that it performs no fallback, and folding this in would widen
+its deliberate three-name interface (``Root`` / ``RootKind`` / ``resolve``) with
+a fourth name that answers a different question.
+
+#125 added :func:`current_root` -- the *other* caller-side policy over the root
+module: which directory the process itself is anchored at. ``resolve`` requires
+an explicit starting point and never reads an implicit CWD (ADR 0006), so
+something has to supply the process CWD as that start, and this is the single
+place that does. It exists because a bare ``Path(".wl")`` -- resolved against
+the process CWD -- used to be scattered across ~20 sites, so a ``wl`` run from a
+subdirectory read the subdirectory's ``.wl`` instead of the root's.
+
+#160 added :func:`_start_directory` (the one CWD read both policies below share)
+and :func:`current_context`, which resolves the three roots one invocation is
+anchored on -- project, deploy and the legacy ``.wl`` to migrate -- *together*,
+once, at a public entry. Callers that need only one root go through
+:func:`current_root` instead of carrying a context they do not use.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from .root import Root, RootKind, resolve
+
+__all__ = [
+    "resolve_root_or_start",
+    "current_root",
+    "current_worktree",
+    "RootContext",
+    "current_context",
+]
+
+
+@dataclass(frozen=True)
+class RootContext:
+    """The roots one ``wl`` invocation is anchored on, resolved once (#160).
+
+    Before #160 the self-sync chain re-derived its roots at every layer, each
+    layer spelling the derivation out as ``Root | None = None`` with an
+    ``else _deploy_root()`` default. A caller that forgot to thread the value
+    down did not fail -- it silently fell back to the process CWD, which is the
+    bug class #140 removed. Resolving the three values once at the public entry
+    and handing this frozen value down makes a missing value a type error.
+
+    * ``project`` -- the ``PROJECT`` root (nearest ``.wl`` / ``pyproject.toml``);
+    * ``deploy`` -- the ``DEPLOY`` root (git work-tree top, else project root);
+    * ``legacy_wl_dir`` -- the pre-#95/#96 ``.wl`` still to be migrated, or
+      ``None`` when there is none (see :func:`current_context`).
+
+    Every field is already a real root: the fallback policy (:func:`current_root`
+    / :func:`resolve_root_or_start`) has been applied, so no consumer has to
+    re-answer "what if there is none".
+    """
+
+    project: Root
+    deploy: Root
+    legacy_wl_dir: Path | None
+
+
+def resolve_root_or_start(start: Path, kind: RootKind) -> Root:
+    """The ``kind``-root for *start*, falling back to *start* when there is none.
+
+    ``resolve(start, kind)`` reports "no root found from here" as ``None`` (ADR
+    0006: a result, not an error). Commands whose contract is to return *some*
+    root -- ``wl lint``, ``wl gate``, ``wl clean``, the ``.wl`` self-sync, the
+    test subsystem -- substitute the starting directory instead, and this is the
+    single function that does so.
+
+    *start* is used exactly as given, both as the ``resolve`` input and as the
+    fallback answer's ``path``: no canonicalisation happens here, so a caller
+    that needs a resolved spelling resolves it before calling (see the module
+    docstring for why that preserves behaviour).
+
+    The returned value is always a :class:`~wl_cli.utils.root.Root`; a caller
+    that previously handed back a bare :class:`~pathlib.Path` (``lint`` /
+    ``clean`` / ``TemplateManager``) or a ``str`` (``project_root_for``) keeps
+    that outward type by taking ``.path`` or ``str(...)`` of the result, so no
+    caller's signature changes.
+    """
+    root = resolve(start, kind)
+    if root is not None:
+        return root
+    return Root(start, kind)
+
+
+def current_root(kind: RootKind) -> Root:
+    """The ``kind``-root the process's *current directory* belongs to (#125).
+
+    The root module requires an explicit starting point and never reads an
+    implicit CWD (ADR 0006). Callers that hold a start of their own pass it to
+    :func:`resolve_root_or_start`; callers that *are* the process -- a
+    :class:`~click.Command` with no start in hand -- need the CWD turned into a
+    start, and this is the single place that does so. Before #125 each such
+    caller spelled this out as a bare ``Path(".wl")``, which resolves against
+    the process CWD: a ``wl`` run from a subdirectory then read the
+    subdirectory's ``.wl`` instead of the root's. Routing every one of them
+    through here is what makes the anchor the *root* the CWD belongs to.
+
+    The read is :func:`_start_directory` -- a deleted working directory falls
+    back to a relative ``.`` (#95), and the result is canonicalised so the anchor
+    matches the resolved root -- and the "no root found" policy is
+    :func:`resolve_root_or_start`'s, not a private copy. The returned value is
+    always a :class:`~wl_cli.utils.root.Root`: callers wanting the root itself
+    take ``.path``, those wanting its control directory take ``.wl_dir()``.
+    """
+    return resolve_root_or_start(_start_directory(), kind)
+
+
+def current_worktree() -> Root | None:
+    """The ``WORKTREE`` root the process's current directory belongs to, or ``None``.
+
+    The hooks leg is the one consumer (#160): it must tell "inside a git work
+    tree" from "not inside one", because outside one there is no
+    ``core.hooksPath`` to read and nothing git would run. :func:`current_root`
+    cannot serve that question -- its whole point is to *never* answer ``None``,
+    so applying its fallback here would turn "not a work tree" into "the CWD",
+    and ``hooks_path_is_stale`` would then report a stale path forever.
+
+    So this is the same start read and the same ``resolve`` call the deleted
+    per-module copies spelled out, exposed once: a public seam rather than a
+    cross-module import of :func:`_start_directory`, which no caller outside
+    this module should reach for.
+    """
+    return resolve(_start_directory(), RootKind.WORKTREE)
+
+
+def _start_directory() -> Path:
+    """The directory ``wl`` was invoked from, spelled the way the callers expect.
+
+    The only CWD read **on the root-resolution path** (#160). It is not the only
+    CWD read in the tree: :func:`_legacy_wl_dir` below deliberately keeps its own
+    raw read (see its docstring), and unrelated subsystems read the CWD for their
+    own purposes. What matters here is that ``resolve`` requires an explicit
+    starting point and never reads an implicit CWD (ADR 0006), so every root
+    policy in this module needs this one value handed to it rather than each
+    caller reading it for itself -- the four byte-identical ``_start_directory``
+    copies #160 deleted.
+
+    Spelled *resolved*: the callers being migrated resolved their start before
+    passing it to the root module, which keeps their fallbacks byte-identical to
+    the answers the old resolvers gave. A deleted working directory falls back
+    to a relative ``.`` (the #95 shape); an unresolvable one keeps its verbatim
+    spelling.
+    """
+    try:
+        start = Path.cwd()
+    except OSError:
+        # A deleted working directory -- the #95 shape. The old resolvers
+        # bottomed out at a relative ``.``; keep that as the last resort.
+        return Path(".")
+    try:
+        return start.resolve()
+    except Exception:
+        return start
+
+
+def current_context() -> RootContext:
+    """The three roots the process's current directory is anchored on (#160).
+
+    The public-entry half of :class:`RootContext`: a caller that needs more than
+    one root (the ``.wl`` self-sync) resolves this **once** and threads the
+    frozen value down, instead of each layer re-deriving a root from the process
+    CWD. Single-root callers use :func:`current_root` and never build one.
+
+    ``project`` and ``deploy`` go through :func:`resolve_root_or_start`, i.e. the
+    same CLI-top-level fallback policy as :func:`current_root`; the values are
+    therefore exactly what those callers resolved before #160.
+
+    ``legacy_wl_dir`` keeps the historical spelling on purpose: the pre-#95/#96
+    walk has always been handed the **un-resolved** ``Path.cwd()`` (the F2
+    residual in ``wl_dir_updater``). Unifying that spelling with the resolved
+    start above is a separate ticket; ``resolve`` canonicalises internally
+    either way, so the only observable difference is the deleted-CWD state,
+    where the raw read raises where the resolved read would fall back to a
+    relative ``.`` (:func:`_legacy_wl_dir` catches it and answers ``None``).
+    There is no invocation directory to walk from then, so the context carries
+    ``None`` -- which is also what the old chain concluded: both ``.wl`` anchors
+    live under a CWD that is gone, so its anchor check returned before the
+    legacy walk was ever reached.
+    """
+    start = _start_directory()
+    return RootContext(
+        project=resolve_root_or_start(start, RootKind.PROJECT),
+        deploy=resolve_root_or_start(start, RootKind.DEPLOY),
+        legacy_wl_dir=_legacy_wl_dir(),
+    )
+
+
+def _legacy_wl_dir() -> Path | None:
+    """The pre-#95/#96 ``.wl`` at the *invocation* directory, or ``None``.
+
+    Read with the raw, un-resolved ``Path.cwd()`` -- the spelling
+    ``wl_dir_updater.check_and_update_wl_dir`` has always used (the F2 residual:
+    it must be resolved *before* the deploy ``.wl`` exists, or the walk resolves
+    to the deploy root itself and the migration is silently skipped).
+
+    A deleted working directory raises ``OSError`` on that raw read, and the
+    exception **is caught here and turned into ``None``**: this state has no
+    invocation directory to walk from, so there is nothing a legacy walk could
+    find. Catching it is load-bearing for the component-level callers that
+    drive :func:`current_context` or :meth:`ProjectStructureSetup.setup`
+    *directly* (component use, tests, embedding), where an escaping ``OSError``
+    would abort the call. No shipped ``wl`` CLI entry reaches this leg in a
+    deleted-CWD shell: ``wl init`` reads ``Path.cwd()`` earlier
+    (``EnvironmentInitializer.__init__`` /
+    ``ProjectStructureInitializer.initialize``), and the per-command hot path
+    returns at its anchor early-return (``check_and_update_wl_dir``) before this
+    function is reached. The #95 fallback in :func:`_start_directory` must not
+    be used for this leg (it would walk a relative ``.`` instead of the
+    invocation directory); ``None`` is the answer.
+    ``tests/test_root_context_160.py::test_deleted_cwd`` pins this leg, and
+    driving ``ProjectStructureSetup.setup`` through it is pinned by
+    ``tests/test_project_structure_modules.py::
+    test_setup_in_a_deleted_cwd_does_not_raise_oserror``.
+
+    The bounds of the walk (volume-root ceiling, system-scope blacklist, the
+    ``<home>/.wl`` refusal) are the root module's ``LEGACY`` kind (#118); this
+    reads no legacy directory of its own.
+    """
+    try:
+        invocation_dir = Path.cwd()
+    except OSError:
+        return None
+    legacy_root = resolve(invocation_dir, RootKind.LEGACY)
+    return legacy_root.wl_dir() if legacy_root is not None else None

wl_cli/utils/run_evidence.py

@@ -0,0 +1,236 @@
+"""Structured evidence for one ``wl test`` run -- the cross-process seam (#212).
+
+``wl gate`` used to decide "did this run exercise the tree?" by regex-matching
+the human-readable ``Cache usage: N/M files`` line in ``wl test``'s stdout
+(``_CACHE_USAGE_RE`` / ``cached_result_count``). That made a *presentation*
+string a decision input, with two concrete failures (ADR-0010):
+
+* The line is suppressed whenever ``concise`` renders the summary, so the fact
+  simply disappears and the gate reads "0 hits".
+* The all-cached run short-circuits before pytest, so it writes no junit report
+  -- and a cached run is exactly the state the gate must judge red.
+
+This module carries the fact across the process boundary as a versioned value
+instead: which files ran, how many results came from the cache, whether
+``--no-cache`` was requested, whether the run was cacheable at all, its exit
+code, and when it started/finished. It carries **facts only**; the verdict
+("a cache hit is red") belongs to :mod:`wl_cli.commands.gate.gate_command`.
+
+Reading is deliberately fail-closed: a missing, unreadable, corrupt or
+unknown-version file is ``None`` -- never a half-parsed value. The gate turns
+``None`` into red and names the path.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+import os
+import tempfile
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+#: Bumped whenever the payload gains, loses, or renames a fact. A reader that
+#: does not know the version returns ``None`` rather than guessing -- a stale
+#: schema can silently mean something else (ADR-0010: "绝不半信").
+SCHEMA_VERSION = 1
+
+#: Every fact a reader must find. ``cache_blocked_reason`` is nullable but not
+#: optional: an absent key and an explicit ``null`` mean different things to a
+#: producer, so the reader requires the key and rejects the missing one.
+_REQUIRED_FIELDS: tuple[str, ...] = (
+    "schema_version",
+    "executed_files",
+    "cache_hits",
+    "cache_total",
+    "no_cache_requested",
+    "cacheable",
+    "cache_blocked_reason",
+    "exit_code",
+    "started_at",
+    "finished_at",
+)
+
+
+@dataclass(frozen=True, kw_only=True)
+class TestRunEvidence:
+    """The facts one ``wl test`` invocation produced.
+
+    ``executed_files`` are spellings relative to the project root, in the order
+    the run observed them. They are a *record*, not the verdict: the gate only
+    refuses runs whose ``cache_hits`` is non-zero.
+
+    ``no_cache_requested`` states what the caller asked for, so
+    "``--no-cache`` was requested but the runner still hit the cache" becomes a
+    fact instead of something the gate has to guess.
+
+    ``cacheable`` / ``cache_blocked_reason`` describe whether the run was
+    eligible to write cache at all (an unsafe passthrough switch or
+    ``PYTEST_ADDOPTS`` closes it). They are independent of
+    ``no_cache_requested``: a run may be cacheable and still asked to bypass
+    the cache.
+    """
+
+    #: Keep pytest from collecting this value class as a test case: its name
+    #: starts with ``Test`` and it has an ``__init__``. Same guard the CLI's
+    #: ``TestCommand`` uses (``commands/testcommands/test_commands.py``).
+    __test__ = False
+
+    executed_files: tuple[str, ...]
+    cache_hits: int
+    cache_total: int
+    no_cache_requested: bool
+    cacheable: bool
+    cache_blocked_reason: str | None
+    exit_code: int
+    started_at: float
+    finished_at: float
+    schema_version: int = SCHEMA_VERSION
+
+    def to_dict(self) -> dict[str, Any]:
+        """The JSON payload, with an explicit shape (and field order)."""
+        return {
+            "schema_version": self.schema_version,
+            "executed_files": list(self.executed_files),
+            "cache_hits": self.cache_hits,
+            "cache_total": self.cache_total,
+            "no_cache_requested": self.no_cache_requested,
+            "cacheable": self.cacheable,
+            "cache_blocked_reason": self.cache_blocked_reason,
+            "exit_code": self.exit_code,
+            "started_at": self.started_at,
+            "finished_at": self.finished_at,
+        }
+
+    @classmethod
+    def from_dict(cls, raw: Any) -> TestRunEvidence | None:
+        """Rebuild from a decoded payload, or ``None`` when anything is off.
+
+        Every required field must be present *and* of the right type, and the
+        schema version must be exactly :data:`SCHEMA_VERSION`. A payload that
+        merely looks close is rejected whole -- a half-trusted record is worse
+        than no record, because the gate would act on a guess.
+        """
+        if not isinstance(raw, dict):
+            return None
+        if any(field not in raw for field in _REQUIRED_FIELDS):
+            return None
+        version = raw.get("schema_version")
+        # ``bool`` is a subclass of ``int``, so ``isinstance(True, int)`` is
+        # true; the explicit bool exclusion keeps a flag from masquerading as
+        # a version.
+        if not isinstance(version, int) or isinstance(version, bool):
+            return None
+        if version != SCHEMA_VERSION:
+            return None
+
+        executed_files = raw.get("executed_files")
+        if not isinstance(executed_files, list) or not all(
+            isinstance(entry, str) for entry in executed_files
+        ):
+            return None
+
+        cache_hits = raw.get("cache_hits")
+        cache_total = raw.get("cache_total")
+        exit_code = raw.get("exit_code")
+        if (
+            not isinstance(cache_hits, int)
+            or isinstance(cache_hits, bool)
+            or not isinstance(cache_total, int)
+            or isinstance(cache_total, bool)
+            or not isinstance(exit_code, int)
+            or isinstance(exit_code, bool)
+        ):
+            return None
+
+        no_cache_requested = raw.get("no_cache_requested")
+        cacheable = raw.get("cacheable")
+        if not isinstance(no_cache_requested, bool) or not isinstance(cacheable, bool):
+            return None
+
+        cache_blocked_reason = raw.get("cache_blocked_reason")
+        if cache_blocked_reason is not None and not isinstance(
+            cache_blocked_reason, str
+        ):
+            return None
+
+        started_at = raw.get("started_at")
+        finished_at = raw.get("finished_at")
+        if (
+            not isinstance(started_at, (int, float))
+            or isinstance(started_at, bool)
+            or not isinstance(finished_at, (int, float))
+            or isinstance(finished_at, bool)
+        ):
+            return None
+        # ``json`` accepts bare ``NaN`` / ``Infinity`` literals by default, and
+        # both are ``float`` -- so the type check above lets them through.
+        # Neither is an epoch second, so a non-finite timestamp is a corrupt
+        # record, judged like any other corrupt payload: whole record rejected
+        # (review N1).
+        if not math.isfinite(started_at) or not math.isfinite(finished_at):
+            return None
+
+        return cls(
+            executed_files=tuple(executed_files),
+            cache_hits=cache_hits,
+            cache_total=cache_total,
+            no_cache_requested=no_cache_requested,
+            cacheable=cacheable,
+            cache_blocked_reason=cache_blocked_reason,
+            exit_code=exit_code,
+            started_at=float(started_at),
+            finished_at=float(finished_at),
+        )
+
+    def write(self, path: Path) -> None:
+        """Write this record to *path* atomically.
+
+        The payload lands in a sibling temporary file and is moved into place
+        with :func:`os.replace`, so a concurrent reader observes either the old
+        file or the complete new one -- never a truncated JSON document. Missing
+        parent directories are created (the gate hands us a path under the
+        system temp directory, which always exists).
+        """
+        parent = path.parent
+        parent.mkdir(parents=True, exist_ok=True)
+        payload = json.dumps(self.to_dict(), ensure_ascii=False) + "\n"
+
+        descriptor, temporary = tempfile.mkstemp(
+            prefix=f".{path.name}.", suffix=".tmp", dir=str(parent)
+        )
+        try:
+            with os.fdopen(descriptor, "w", encoding="utf-8") as handle:
+                handle.write(payload)
+                handle.flush()
+                os.fsync(handle.fileno())
+            os.replace(temporary, path)
+        except BaseException:
+            try:
+                os.unlink(temporary)
+            except OSError:
+                pass
+            raise
+
+    @classmethod
+    def read(cls, path: Path | None) -> TestRunEvidence | None:
+        """Read the evidence at *path*, or ``None`` when it cannot be trusted.
+
+        Missing, unreadable, non-JSON, wrong-shape, wrong-type and
+        unknown-version payloads all collapse to ``None``: the gate's
+        fail-closed red. There is no partial result and no fallback.
+        """
+        if path is None:
+            return None
+        try:
+            text = path.read_text(encoding="utf-8")
+        except (OSError, UnicodeDecodeError):
+            return None
+        try:
+            raw = json.loads(text)
+        except (ValueError, RecursionError):
+            return None
+        return cls.from_dict(raw)

wl_cli/utils/structured_logger.py

@@ -0,0 +1,18 @@
+"""
+Structured logging implementation for WL Commands.
+
+This file maintains backward compatibility while delegating to the modularized
+structured_logging package.
+"""
+
+# Import the modularized StructuredLogger from the structured_logging package
+# Import datetime for backward compatibility with tests
+import datetime as _datetime
+
+from .structured_logging.core import StructuredLogger
+
+# Re-export for backward compatibility
+__all__ = ["StructuredLogger"]
+
+# For backward compatibility, expose datetime
+datetime = _datetime

wl_cli/utils/structured_logging/__init__.py

@@ -0,0 +1,19 @@
+"""Structured logging module for WL Commands."""
+
+# Export main components from submodules
+from .config import LoggingConfig
+from .core import StructuredLogger, StructuredLoggerCore
+from .filtering import LogLevelChecker
+from .filters import LogFilter
+from .formatters import LogFormatter
+from .handlers import LogHandler
+
+__all__ = [
+    "StructuredLogger",
+    "StructuredLoggerCore",
+    "LoggingConfig",
+    "LogLevelChecker",
+    "LogFormatter",
+    "LogHandler",
+    "LogFilter",
+]