py-wlcli 0.8.0__py3-none-any.whl

wl_cli/commands/lint/lint_run.py

@@ -0,0 +1,258 @@
+"""One ``wl lint`` run, and the verdict it carries (#170).
+
+Before this module a single ``wl lint`` started ruff four times (once for the
+verdict, once per report section) and mypy three times (once for the main
+section, once per ``error.md`` scope), while ``issues_found`` re-read ruff's
+stdout a fourth time. The executor now runs each requested tool exactly once
+and hands the finished results back as a :class:`LintRun`; the reporter only
+renders it.
+
+The value is deliberately dumb. It stores the subprocess results and derives
+the two decisions lint makes -- :attr:`LintRun.exit_code` and
+:attr:`LintRun.issues_found`. Both are read off ruff's *status*, never off its
+stdout, which is what let the old reporter call a launch failure "no issues".
+
+ruff's report section is its own ``--output-format full`` text, captured
+verbatim (#170 review F1/F5). The old report stored exactly that text; the
+first cut of this module ran ruff with ``--output-format json`` and rendered a
+lossy concise line per finding, so the report shrank from ruff's snippets,
+carets and ``help:`` lines down to one line each. Grouping the verbatim blocks
+by the path on their ``-->`` line keeps the single execution *and* the old
+report's content -- see :func:`parse_ruff_output`.
+"""
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+from ...utils.pre_commit import PreCommitRun
+from ...utils.subprocess_utils import SubprocessResult
+
+#: ruff's ``full`` renderer locates every diagnostic with one arrow line. The
+#: path is captured greedily so Windows drive letters (``C:\...:1:1``) and
+#: paths containing spaces survive; the trailing ``:row:column`` is what makes
+#: the match unambiguous.
+_LOCATION_LINE = re.compile(r"^\s*--> (.+):(\d+):(\d+)$")
+
+
+def display_path(path: str, project_root: Path) -> str:
+    """*path* relative to *project_root* when it lies under it, else unchanged.
+
+    Both sides are resolved first: mypy reports the real path, while the root
+    can arrive through a symlink (``/var`` vs ``/private/var`` on macOS), and
+    an unresolved comparison would leave every finding looking "outside" the
+    scope it belongs to.
+    """
+    candidate = Path(path)
+    if not candidate.is_absolute():
+        return path
+    try:
+        return str(candidate.resolve().relative_to(project_root.resolve()))
+    except (OSError, ValueError):
+        return path
+
+
+@dataclass(frozen=True)
+class RuffBlock:
+    """One diagnostic block, verbatim from ``ruff check --output-format full``.
+
+    ``text`` keeps ruff's own header, ``-->`` location, source snippet, caret
+    and ``help:`` lines exactly as emitted. ``path``/``row``/``column`` are
+    lifted from the ``-->`` line so the reporter can group the block into its
+    per-directory section without re-rendering anything.
+    """
+
+    text: str
+    path: str
+    row: int
+    column: int
+
+
+@dataclass(frozen=True)
+class RuffOutput:
+    """One ruff run's full text, split into diagnostic blocks plus the rest.
+
+    ``tail`` holds everything that is not a diagnostic block -- ruff's own
+    summary (``Found N errors.`` and the ``[*] N fixable ...`` line, including
+    the ``--unsafe-fixes`` hint) and ``All checks passed!``. Keeping it
+    verbatim is what makes the fixable count and the ``[*]`` markers ruff's
+    own facts instead of a second, hand-rolled tally (#170 review F2).
+    """
+
+    blocks: tuple[RuffBlock, ...]
+    tail: tuple[str, ...]
+
+    @property
+    def empty(self) -> bool:
+        """Whether the run produced no text at all (launch failure)."""
+        return not self.blocks and not self.tail
+
+
+def parse_ruff_output(stdout: str) -> RuffOutput:
+    """Split ``ruff check --output-format full`` text into blocks and tail.
+
+    ruff separates its rendered diagnostics with a blank line, and every
+    snippet line carries a gutter (``  |`` or ``12 | ...``), so a truly empty
+    line is always a block boundary. A block is a *diagnostic* when it carries
+    an ``--> path:row:column`` line; anything else (the summary, or a ruff
+    version that only printed a final sentence) is kept in the tail.
+
+    The function is pure and never re-renders: block text is handed back
+    byte-for-byte, which is what lets the differential test in
+    ``tests/test_lint_report_equivalence.py`` compare against ruff itself.
+    """
+    text = (stdout or "").replace("\r\n", "\n").replace("\r", "\n")
+    groups: list[list[str]] = []
+    current: list[str] = []
+    for line in text.split("\n"):
+        if not line.strip():
+            if current:
+                groups.append(current)
+                current = []
+            continue
+        current.append(line)
+    if current:
+        groups.append(current)
+
+    blocks: list[RuffBlock] = []
+    tail: list[str] = []
+    for group in groups:
+        location: re.Match[str] | None = None
+        for line in group:
+            location = _LOCATION_LINE.match(line)
+            if location is not None:
+                break
+        if location is None:
+            tail.extend(group)
+            continue
+        blocks.append(
+            RuffBlock(
+                text="\n".join(group),
+                path=location.group(1),
+                row=int(location.group(2)),
+                column=int(location.group(3)),
+            )
+        )
+    return RuffOutput(blocks=tuple(blocks), tail=tuple(tail))
+
+
+@dataclass(frozen=True)
+class LintRun:
+    """The finished tools of one ``wl lint`` execution.
+
+    ``project_root``, ``quiet`` and ``fix`` are the inputs the render needs;
+    ``paths`` is the scope as the user asked for it (``()`` means the default,
+    repository-wide scope). ``format_code`` is the #166 format prefix's verdict:
+    the caller stops before ruff when it is non-zero, so in practice it is
+    ``0`` here, but keeping it in the value makes :attr:`exit_code` the single
+    place the whole lint exit contract is spelled (#170 audit patch 5).
+
+    Field order note: ``project_root`` has no default, so it sits beside
+    ``ruff`` ahead of the optional results rather than after ``paths`` where the
+    ticket sketched it.
+    """
+
+    ruff: SubprocessResult
+    project_root: Path
+    mypy: SubprocessResult | None = None
+    pre_commit: PreCommitRun | None = None
+    paths: tuple[str, ...] = ()
+    quiet: bool = False
+    fix: bool = False
+    format_code: int = 0
+
+    @property
+    def ruff_launch_failed(self) -> bool:
+        """Whether ruff itself could not be started.
+
+        Asked of ``launch_error``, never of ``returncode < 0``: a child killed
+        by a signal also reports a negative code (#100).
+        """
+        return self.ruff.launch_error is not None
+
+    @property
+    def exit_code(self) -> int:
+        """The lint verdict: prefix, ruff, mypy, or a failing pre-commit hook.
+
+        A run that never started exits ``1`` rather than propagating the
+        executor's ``-1`` sentinel to ``sys.exit`` (where ``-1`` becomes 255).
+        A run that *was* killed by a signal is a failure too: ``subprocess``
+        reports it as ``-signum``, and ``max(format_code, -9)`` used to hand
+        back ``0`` -- a ruff killed by OOM/SIGKILL passed the gate (#170 review
+        F3). Both non-verdict states collapse to ``1``.
+
+        mypy follows the same rule whenever :attr:`mypy_failure` names a run
+        that produced no verdict -- it could not be started, was killed by a
+        signal, exited with code ``>= 2``, or exited non-zero with no
+        diagnostics at all -- and only on the paths that ran it (``--report``
+        and the default; ``--noreport`` never has a mypy result). An ordinary
+        ``rc == 1`` mypy exit *with* diagnostics is a type-error verdict and
+        deliberately leaves the exit code alone (#172 wave 9 ruling).
+
+        A hook that *judged the check failed* is part of the verdict too
+        (#188): the report already rendered it as ``Failed`` while the exit
+        code said ``0``, so the terminal announced success for a red report.
+        Auto-fix-only runs stay green -- :attr:`PreCommitRun.hooks_failed`
+        already excludes blocks that merely rewrote files (#149).
+        """
+        ruff_code = self.ruff.returncode
+        if self.ruff_launch_failed or self.ruff.was_signalled:
+            ruff_code = 1
+        code = max(self.format_code, ruff_code)
+        # One predicate for both the report and the exit code (#172 review
+        # M1): a mypy that never produced a verdict must not let the terminal
+        # announce success while the report says "mypy failed". Ordinary
+        # type errors answer ``None`` here and stay a verdict.
+        if self.mypy_failure is not None:
+            code = max(code, 1)
+        if self.pre_commit is not None and self.pre_commit.hooks_failed:
+            code = max(code, 1)
+        return code
+
+    @property
+    def issues_found(self) -> bool:
+        """Whether ruff judged the code to have issues.
+
+        Only ruff's status is read. Its stdout is *not* consulted -- the old
+        reporter decided this by ``stdout.strip()``, so a launch failure (empty
+        stdout) read as "no issues" (#170).
+        """
+        return self.ruff_launch_failed or self.ruff.returncode != 0
+
+    @property
+    def ruff_output(self) -> RuffOutput:
+        """The captured ``full`` text of the one ruff run, as blocks + tail."""
+        return parse_ruff_output(self.ruff.stdout)
+
+    @property
+    def mypy_failure(self) -> str | None:
+        """A one-line description when mypy could not produce a verdict.
+
+        The exit code, not the presence of output, is the discriminator:
+        ``0`` is clean, ``1`` means "type errors found" -- a verdict the gate
+        leaves alone -- and ``>= 2`` is abnormal termination (bad config, bad
+        command, internal error). So ``returncode >= 2`` is a failure whatever
+        mypy managed to print first; a broken mypy that emitted partial
+        diagnostics before dying must not pass for a type-error verdict
+        (#172 r1). ``rc == 1`` is a failure only when stdout is empty, which
+        is what a config file that cannot be found looks like:
+        ``mypy: error: Cannot find config file ...`` on stderr, empty stdout.
+        A child killed by a signal is a failure regardless of what it managed
+        to print first: ``was_signalled`` is asked separately because a
+        ``-signum`` exit with partial diagnostics would otherwise pass for a
+        normal type-error verdict (#172 wave 9). Naming these keeps the report
+        from answering "No issues found." to a run that never started (#170
+        review F4).
+        """
+        result = self.mypy
+        if result is None:
+            return None
+        if result.launch_error is not None:
+            return f"mypy could not be started: {result.launch_error}"
+        if result.was_signalled:
+            return f"mypy was killed by signal {-result.returncode}."
+        if result.returncode >= 2:
+            return f"mypy failed with exit code {result.returncode}."
+        if result.returncode != 0 and not (result.stdout or "").strip():
+            return f"mypy failed with exit code {result.returncode}."
+        return None

wl_cli/commands/lint/mypy_config.py

@@ -0,0 +1,90 @@
+"""Single 'which mypy config file applies?' decision (map #35 / ticket #42).
+
+Consolidates the three duplicated ``.wl/mypy.ini`` existence checks that used
+to live in LintExecutor and LintReporter into one module, so moving the mypy
+baseline (industrialization IS-2 keeps it in ``.wl/mypy.ini``) is a one-place
+change.
+
+When ``.wl/mypy.ini`` is absent (a fresh clone that has not run ``wl init``, or
+a CI job that has not materialised it yet), the decision falls back to the
+vendored ``vendors/config/mypy.ini`` template shipped inside the package, so
+callers always get a usable ``--config-file``.
+"""
+
+import os
+from pathlib import Path
+
+from ...utils.root import Root, RootKind
+
+# Vendored mypy baseline shipped with the package and deployed to
+# ``.wl/mypy.ini`` by ``wl init``. ``parents[2]`` of this module is the
+# ``wl_cli`` package directory.
+_VENDORED_MYPY_INI = (
+    Path(__file__).resolve().parents[2] / "vendors" / "config" / "mypy.ini"
+)
+
+
+def mypy_config_file(project_root: Path, *, relative: bool = False) -> Path | None:
+    """Return the mypy config to pass to ``--config-file``, or ``None``.
+
+    Prefers the project baseline ``.wl/mypy.ini``; when that is missing, falls
+    back to the vendored template shipped with the package. ``None`` is
+    returned only when neither is available.
+
+    Both the **selection** and the returned *form* are anchored at
+    *project_root* -- the directory mypy will run from. The default yields an
+    absolute path, which is what both callers use: ``LintExecutor`` (mypy runs
+    with *project_root* as cwd, but an absolute config cannot be broken by a
+    symlinked root spelling, #170 review F4) and ``wl gate`` when it names the
+    config in its warning. ``relative=True`` still yields a token relative to
+    *project_root*; both sides are resolved first, so a symlinked root cannot
+    turn the vendored fallback into ``../private/tmp/...``.
+
+    The selection must be anchored here, not at the process cwd: callers build
+    the command *before* running it (``LintExecutor.prepare_mypy_command`` can
+    be invoked from any directory, and ``wl gate`` builds every step up front),
+    so probing a bare ``Path(".wl/mypy.ini")`` would read the *caller's* cwd --
+    picking a different baseline whenever the two disagree, and falling back to
+    the vendored template when the project baseline is merely out of view (the
+    review F3 residual).
+    """
+    # The ``.wl/mypy.ini`` layout lives in the root module; ask it rather than
+    # spelling the path here (#114). The derived path is a pure builder from
+    # *project_root*, so the kind is only a label, not a resolution.
+    candidate = Root(project_root, RootKind.PROJECT).mypy_ini()
+    try:
+        baseline_exists = candidate.exists()
+    except OSError:
+        # Same contract as the vendored probe below: a path that cannot be
+        # stat'ed means "not this baseline", never a crash.
+        baseline_exists = False
+    if baseline_exists:
+        if relative:
+            return _relative_to(candidate, project_root)
+        return candidate
+
+    try:
+        vendored_exists = _VENDORED_MYPY_INI.exists()
+    except OSError:
+        return None
+    if not vendored_exists:
+        return None
+
+    if relative:
+        return _relative_to(_VENDORED_MYPY_INI, project_root)
+    return _VENDORED_MYPY_INI
+
+
+def _relative_to(path: Path, project_root: Path) -> Path:
+    """*path* expressed relative to *project_root*, with both sides resolved.
+
+    The vendored template is already resolved (``Path(__file__).resolve()``),
+    while *project_root* can still be a symlink spelling -- ``/tmp`` on macOS
+    resolves to ``/private/tmp``. A lexical ``os.path.relpath`` between the two
+    spellings produced a token like ``../../private/tmp/...`` that mypy could
+    not open; resolving both first keeps the token honest (#170 review F4).
+    """
+    try:
+        return Path(os.path.relpath(path.resolve(), start=project_root.resolve()))
+    except OSError:
+        return Path(os.path.relpath(path, start=project_root))

wl_cli/commands/registry.py

@@ -0,0 +1,103 @@
+"""Command registration and management module.
+
+Single source of truth for the user-visible ``wl`` command surface is the
+:data:`COMMAND_TABLE` defined below. Each entry maps a canonical (user-visible
+Click) command name to a :class:`CommandSpec` describing where the Click
+command object lives and how to obtain it.
+"""
+
+import importlib
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class CommandSpec:
+    """Static spec of one user-visible Click command on the ``wl`` group.
+
+    Attributes:
+        module_path: Import path of the command module, relative to
+            :attr:`package` (e.g. ``"buildcommands.build"``).
+        symbol: Name of the module-level Click command object, or of a
+            zero-argument factory returning one.
+        aliases: Extra user-visible names registered alongside the canonical
+            name.
+        instantiate: If True, call the symbol to obtain the Click object
+            (``obj = obj()``); otherwise the module attribute is used as-is.
+        package: Import root :attr:`module_path` is resolved against. Legacy
+            commands live under ``wl_cli.commands``; domain namespaces (env /
+            cc / mcp, issue #220) live directly under ``wl_cli``.
+    """
+
+    module_path: str
+    symbol: str
+    aliases: tuple[str, ...] = ()
+    instantiate: bool = False
+    package: str = "wl_cli.commands"
+
+
+#: Canonical user-visible command name -> its spec.
+COMMAND_TABLE: dict[str, CommandSpec] = {
+    "lint": CommandSpec("lint.lint_command", "lint_command"),
+    "clean": CommandSpec("clean.clean", "clean_command", aliases=("c",)),
+    "cleanup": CommandSpec("cleanup", "cleanup_command"),
+    "format": CommandSpec("format.format_command", "format_command", aliases=("f",)),
+    "config": CommandSpec("config.config", "config_command"),
+    "test": CommandSpec("testcommands.test_commands", "test_command"),
+    "build": CommandSpec("buildcommands.build", "build_command", aliases=("b",)),
+    "builddist": CommandSpec("buildcommands.dist", "builddist_command"),
+    "buildtest": CommandSpec("buildcommands.test", "buildtest_command"),
+    "init": CommandSpec("initenv.initenv", "initenv_group", aliases=("i",)),
+    "self": CommandSpec("self.self_command", "self_command", instantiate=True),
+    "update": CommandSpec("update.update_command", "update_command"),
+    "workflow": CommandSpec("workflow", "workflow_command"),
+    "version": CommandSpec(
+        "version.version_command", "version_command", instantiate=True
+    ),
+    "debug": CommandSpec("debug.debug", "debug_command"),
+    "git-flow": CommandSpec("git.git_flow", "git_flow_command"),
+    "lfs": CommandSpec("lfs.cli", "lfs_command"),
+    "gate": CommandSpec("gate.gate_command", "gate_command"),
+    # Domain namespaces (issue #220). Their Click groups live at
+    # ``src/wl_cli/<domain>/cli.py``, outside ``wl_cli.commands``, hence the
+    # explicit package; imports stay lazy — ``wl --help`` imports the module
+    # only when the group is registered, never at registry import time.
+    "env": CommandSpec("env.cli", "env_group", package="wl_cli"),
+    "cc": CommandSpec("cc.cli", "cc_group", package="wl_cli"),
+    "mcp": CommandSpec("mcp.cli", "mcp_group", package="wl_cli"),
+}
+
+#: Live alias -> canonical command name, derived from the table.
+_ALIAS_TO_COMMAND: dict[str, str] = {
+    alias: name for name, spec in COMMAND_TABLE.items() for alias in spec.aliases
+}
+
+
+def list_commands() -> list[str]:
+    """Return the canonical user-visible command names in registration order."""
+    return list(COMMAND_TABLE)
+
+
+def get_command(name: str):
+    """Return the Click command/group object for a canonical name or alias.
+
+    The owning module is imported on first access. Aliases resolve to their
+    canonical command before lookup.
+
+    Args:
+        name: A canonical command name or one of its aliases.
+
+    Returns:
+        The Click command/group object.
+
+    Raises:
+        ValueError: If ``name`` is not a known command or alias.
+    """
+    resolved = _ALIAS_TO_COMMAND.get(name, name)
+    spec = COMMAND_TABLE.get(resolved)
+    if spec is None:
+        raise ValueError(f"Command '{name}' not found")
+    module = importlib.import_module(f"{spec.package}.{spec.module_path}")
+    obj = getattr(module, spec.symbol)
+    if spec.instantiate:
+        obj = obj()
+    return obj

wl_cli/commands/self/__init__.py

@@ -0,0 +1,7 @@
+"""
+Self commands module.
+"""
+
+from .self_command import SelfCommand
+
+__all__ = ["SelfCommand"]

wl_cli/commands/self/common/__init__.py

@@ -0,0 +1,8 @@
+"""
+Common shared components for self module.
+"""
+
+from .config import SelfConfig
+from .version_cache import VersionCache
+
+__all__ = ["SelfConfig", "VersionCache"]

wl_cli/commands/self/common/capabilities.py

@@ -0,0 +1,30 @@
+"""Backwards-compatible re-export of the shared capability registry (#221).
+
+The single source of truth now lives in :mod:`wl_cli.capabilities`: both
+``wl env check`` (``wl_cli.env``) and this package's deprecated
+``wl self capabilities`` alias (``wl_cli.commands``) must serve the same
+dotted names, and the quality domain may not import the env domain (#220).
+This module keeps the historical import path working; it defines no data.
+"""
+
+from __future__ import annotations
+
+from ....capabilities import (
+    CAPABILITIES,
+    CAPABILITY_SINCE,
+    SCHEMA_VERSION,
+    capabilities_payload,
+    capability_details,
+    capability_names,
+    capability_since,
+)
+
+__all__ = [
+    "CAPABILITIES",
+    "CAPABILITY_SINCE",
+    "SCHEMA_VERSION",
+    "capabilities_payload",
+    "capability_details",
+    "capability_names",
+    "capability_since",
+]

wl_cli/commands/self/common/config.py

@@ -0,0 +1,27 @@
+"""
+Configuration for self commands.
+"""
+
+from dataclasses import dataclass
+
+from wl_cli.utils.config import get_config
+
+
+@dataclass
+class SelfConfig:
+    """Configuration container for self commands."""
+
+    cache_enabled: bool
+    cache_timeout: int
+    parallel_enabled: bool
+    max_workers: int
+
+    @classmethod
+    def load(cls) -> "SelfConfig":
+        """Load configuration from config store."""
+        return cls(
+            cache_enabled=get_config("cache_enabled", True),
+            cache_timeout=get_config("cache_timeout", 300),
+            parallel_enabled=get_config("parallel_enabled", True),
+            max_workers=get_config("max_workers", 4),
+        )

wl_cli/commands/self/common/version_cache.py

@@ -0,0 +1,85 @@
+"""
+Generic version cache with TTL support.
+"""
+
+import time
+from typing import Any
+
+
+class VersionCache:
+    """Generic cache for version information with time-based expiration."""
+
+    def __init__(self, default_timeout: int = 300) -> None:
+        """
+        Initialize the version cache.
+
+        Args:
+            default_timeout: Default cache timeout in seconds (default: 5 minutes)
+        """
+        self._cache: dict[str, Any] = {}
+        self._last_update: dict[str, float] = {}
+        self._default_timeout = default_timeout
+
+    def get(self, key: str) -> Any | None:
+        """
+        Get a cached value if it exists and hasn't expired.
+
+        Args:
+            key: Cache key to retrieve
+
+        Returns:
+            The cached value if valid, None otherwise
+        """
+        if key not in self._cache:
+            return None
+
+        current_time = time.time()
+        if current_time - self._last_update[key] > self._default_timeout:
+            return None
+
+        return self._cache[key]
+
+    def set(self, key: str, value: Any) -> None:
+        """
+        Store a value in the cache.
+
+        Args:
+            key: Cache key
+            value: Value to cache
+        """
+        self._cache[key] = value
+        self._last_update[key] = time.time()
+
+    def get_or_set(self, key: str, supplier) -> Any:
+        """
+        Get from cache or supply a new value.
+
+        Args:
+            key: Cache key
+            supplier: Function to call if value not cached or expired
+
+        Returns:
+            The cached or newly supplied value
+        """
+        value = self.get(key)
+        if value is None:
+            value = supplier()
+            if value is not None:
+                self.set(key, value)
+        return value
+
+    def invalidate(self, key: str) -> None:
+        """
+        Invalidate a specific cache entry.
+
+        Args:
+            key: Cache key to invalidate
+        """
+        if key in self._cache:
+            del self._cache[key]
+            del self._last_update[key]
+
+    def clear(self) -> None:
+        """Clear all cache entries."""
+        self._cache.clear()
+        self._last_update.clear()

wl_cli/commands/self/handlers/__init__.py

@@ -0,0 +1,19 @@
+"""
+Subcommand handlers for self command.
+"""
+
+from .base_handler import BaseHandler
+from .install_handler import InstallHandler
+from .status_handler import StatusHandler
+from .uninstall_handler import UninstallHandler
+from .update_handler import UpdateHandler
+from .version_handler import VersionHandler
+
+__all__ = [
+    "BaseHandler",
+    "VersionHandler",
+    "UpdateHandler",
+    "InstallHandler",
+    "UninstallHandler",
+    "StatusHandler",
+]

wl_cli/commands/self/handlers/base_handler.py

@@ -0,0 +1,28 @@
+"""
+Base class for self command handlers.
+"""
+
+import sys
+from abc import ABC, abstractmethod
+
+from wl_cli.utils.logging import log_error_pair
+
+
+class BaseHandler(ABC):
+    """Abstract base class for self command subcommand handlers."""
+
+    @abstractmethod
+    def execute(self) -> None:
+        """Execute the subcommand."""
+        pass
+
+    def handle_error(self, error: Exception, exit_code: int = 1) -> None:
+        """
+        Handle an error with logging and exit.
+
+        Args:
+            error: The exception to handle
+            exit_code: Exit code to use (default: 1)
+        """
+        log_error_pair(f"Unexpected error: {error}", f"意外错误：{error}")
+        sys.exit(exit_code)