py-wlcli 0.8.0__py3-none-any.whl

wl_cli/commands/debug/output_formatter.py

@@ -0,0 +1,165 @@
+"""Output formatter for wl-debug command.
+
+Handles both text and JSON output modes with verbosity control.
+"""
+
+import json
+import re
+import sys
+from typing import Any
+
+
+def _sanitize_ansi(text: str) -> str:
+    """Remove ANSI escape sequences from text.
+
+    Args:
+        text: Text that may contain ANSI escape sequences
+
+    Returns:
+        Text with ANSI escape sequences removed
+    """
+    ansi_escape = re.compile(r"\x1b\[[0-9;]*[a-zA-Z]")
+    return ansi_escape.sub("", text)
+
+
+class OutputFormatter:
+    """Output formatter for wl-debug command.
+
+    Supports text and JSON output modes with configurable verbosity levels.
+    """
+
+    def __init__(
+        self,
+        json_mode: bool = False,
+        verbosity: int = 0,
+        file=sys.stdout,
+    ):
+        """Initialize output formatter.
+
+        Args:
+            json_mode: Whether to output in JSON format
+            verbosity: Verbosity level (0, 1, or 2)
+            file: Output file object
+        """
+        self.json_mode = json_mode
+        self.verbosity = max(0, min(2, verbosity))  # Ensure verbosity is 0-2
+        self.file = file
+        self._messages: list[dict[str, Any]] = []
+        self._finalized = False
+
+    def info(self, message: str, verbosity: int = 0, **kwargs) -> None:
+        """Output an info message.
+
+        Args:
+            message: Message text
+            verbosity: Minimum verbosity level required to show this message
+            **kwargs: Additional data to include in JSON output
+        """
+        if verbosity <= self.verbosity:
+            self._output("INFO", message, **kwargs)
+
+    def error(self, message: str, verbosity: int = 0, **kwargs) -> None:
+        """Output an error message.
+
+        Args:
+            message: Message text
+            verbosity: Minimum verbosity level required to show this message
+            **kwargs: Additional data to include in JSON output
+        """
+        if verbosity <= self.verbosity:
+            self._output("ERROR", message, **kwargs)
+
+    def success(self, message: str, verbosity: int = 0, **kwargs) -> None:
+        """Output a success message.
+
+        Args:
+            message: Message text
+            verbosity: Minimum verbosity level required to show this message
+            **kwargs: Additional data to include in JSON output
+        """
+        if verbosity <= self.verbosity:
+            self._output("SUCCESS", message, **kwargs)
+
+    def _output(self, level: str, message: str, **kwargs) -> None:
+        """Internal method to handle output.
+
+        Args:
+            level: Message level (INFO, ERROR, SUCCESS)
+            message: Message text
+            **kwargs: Additional data
+        """
+        if self._finalized:
+            return
+
+        # Ensure message is a string
+        message_str = str(message) if message is not None else ""
+
+        # Convert kwargs to JSON-serializable types
+        safe_kwargs = {}
+        for key, value in kwargs.items():
+            try:
+                # Try to serialize first, if fails convert to string
+                json.dumps(value)
+                safe_kwargs[key] = value
+            except (TypeError, OverflowError):
+                safe_kwargs[key] = str(value)
+
+        if self.json_mode:
+            # Sanitize ANSI sequences in JSON mode only
+            sanitized_message = _sanitize_ansi(message_str)
+            # Also sanitize any string values in kwargs
+            sanitized_kwargs = {}
+            for k, v in safe_kwargs.items():
+                if isinstance(v, str):
+                    sanitized_kwargs[k] = _sanitize_ansi(v)
+                else:
+                    sanitized_kwargs[k] = v
+
+            self._messages.append(
+                {
+                    "level": level,
+                    "message": sanitized_message,
+                    "verbosity": self.verbosity,
+                    **sanitized_kwargs,
+                }
+            )
+        else:
+            print(f"[{level}] {message_str}", file=self.file)
+            if safe_kwargs and self.verbosity >= 2:
+                for key, value in safe_kwargs.items():
+                    print(f"  {key}: {value}", file=self.file)
+
+    def finalize(self, success: bool = True, exit_code: int = 0, **kwargs) -> None:
+        """Finalize the output.
+
+        In JSON mode, this will print the complete JSON structure.
+        In text mode, this can be used to output a final summary.
+
+        Args:
+            success: Whether the operation was successful
+            exit_code: Exit code to include in JSON output
+            **kwargs: Additional data to include in the final output
+        """
+        if self._finalized:
+            return
+
+        self._finalized = True
+
+        if self.json_mode:
+            # Convert finalize kwargs to JSON-serializable types
+            safe_final_kwargs = {}
+            for key, value in kwargs.items():
+                try:
+                    json.dumps(value)
+                    safe_final_kwargs[key] = value
+                except (TypeError, OverflowError):
+                    safe_final_kwargs[key] = str(value)
+
+            final_output = {
+                "success": success,
+                "exit_code": exit_code,
+                "messages": self._messages,
+                **safe_final_kwargs,
+            }
+            json.dump(final_output, self.file, ensure_ascii=False, indent=2)
+            print(file=self.file)

wl_cli/commands/debug/source_hasher.py

@@ -0,0 +1,92 @@
+"""Source hasher module."""
+
+import fnmatch
+import hashlib
+from pathlib import Path
+
+
+class SourceHasher:
+    """Calculate combined hash of source files."""
+
+    DEFAULT_EXCLUDES = {
+        "__pycache__",
+        ".pytest_cache",
+        ".git",
+        # Directory-name token, not a derived path: matched against each path
+        # component while hashing, so it stays a bare name (#122).
+        ".wl",
+        "node_modules",
+        "dist",
+        "build",
+        "venv",
+        ".venv",
+        "env",
+        ".mypy_cache",
+        ".ruff_cache",
+        ".cache",
+    }
+
+    def __init__(self, project_root: Path | None = None) -> None:
+        self.project_root = project_root or Path.cwd()
+        self.ignore_patterns = self._load_gitignore()
+
+    def compute_hash(self) -> str:
+        """Calculate combined hash of all source files."""
+        try:
+            source_files = self._get_source_files()
+            hash_obj = hashlib.sha1()
+            for file_path in sorted(source_files):
+                content = file_path.read_bytes()
+                hash_obj.update(content)
+            return hash_obj.hexdigest()
+        except Exception:
+            # If any error occurs, return empty hash as fallback
+            return ""
+
+    def _load_gitignore(self) -> set[str]:
+        """Load patterns from .gitignore file."""
+        try:
+            gitignore_path = self.project_root / ".gitignore"
+            if not gitignore_path.exists():
+                return set()
+            patterns = set()
+            with gitignore_path.open("r", encoding="utf-8") as f:
+                for line in f:
+                    line = line.strip()
+                    if line and not line.startswith("#"):
+                        patterns.add(line)
+            return patterns
+        except Exception:
+            # If any error occurs, return empty set as fallback
+            return set()
+
+    def _get_source_files(self) -> list[Path]:
+        """Get list of source files to hash."""
+        try:
+            source_files = []
+            for py_file in self.project_root.rglob("*.py"):
+                relative_path = py_file.relative_to(self.project_root)
+                path_str = str(relative_path)
+
+                # Check default excludes
+                excluded = False
+                for part in relative_path.parts:
+                    if part in self.DEFAULT_EXCLUDES:
+                        excluded = True
+                        break
+                if excluded:
+                    continue
+
+                # Check gitignore patterns
+                for pattern in self.ignore_patterns:
+                    if fnmatch.fnmatch(path_str, pattern) or any(
+                        fnmatch.fnmatch(part, pattern) for part in relative_path.parts
+                    ):
+                        excluded = True
+                        break
+                if not excluded:
+                    source_files.append(py_file)
+            return source_files
+        except Exception:
+            # If any error occurs, return empty list as fallback
+            return []

wl_cli/commands/format/__init__.py

@@ -0,0 +1,13 @@
+"""Format command module."""
+
+# One implementation class lives in ``format_command`` (#166); the package
+# re-exports it so ``from ..format import FormatCommand`` (wl lint) keeps
+# working against the same class the Click command uses.
+#
+# ``format_command`` itself is deliberately not re-exported (#172): binding the
+# Click symbol here shadowed the same-named submodule, so ``format.format_command``
+# meant two different things depending on how it was reached.
+from .format_command import FormatCommand
+from .format_coordinator import FormatCoordinator
+
+__all__ = ["FormatCommand", "FormatCoordinator"]

wl_cli/commands/format/format_cache_adapter.py

@@ -0,0 +1,125 @@
+"""The format cache adapter over the single cache seam (#213, ADR-0011).
+
+Format results are cached per file: the key is the file's normalized path plus
+its content, and each entry is its own file under ``<project>/.wl/cache/format``
+(the old cache was one ``format_cache.json`` holding every entry). Key spelling,
+atomic writes, freshness and the write error policy belong to
+:class:`~wl_cli.utils.cache_ledger.CacheLedger`; this module only answers what is
+*this* cache's: the inputs, the project-level location and the 7-day TTL.
+
+The single-document cache rewrote only the fresh keys on every save, so stale
+entries vanished by construction. Per-entry files have no such side effect, so
+the adapter reclaims them once per run (``CacheLedger.purge_stale``) and renews
+an entry's timestamp when it is served (``CacheLedger.touch``), keeping both the
+bounded footprint and the "7 days after the last run that used it" semantics
+(#213 review MEDIUM-2 / LOW-3).
+
+The location is project-level (``.wl`` of the project root the process is in,
+#125) and deliberately not unified with the user-level test/coverage caches:
+ADR-0011 keeps each adapter's location as policy.
+"""
+
+from pathlib import Path
+
+from ...utils.cache_ledger import CacheInputs, CacheLedger
+from ...utils.root import RootKind
+from ...utils.root_fallback import current_root
+
+#: Format results stay fresh for 7 days -- this adapter's value, kept as-is.
+TTL_SECONDS = 7 * 24 * 60 * 60
+
+
+class FormatCacheAdapter:
+    """Cache the "this file formatted cleanly" verdict, keyed by path + content."""
+
+    NAMESPACE = "format"
+    TTL_SECONDS = TTL_SECONDS
+
+    def __init__(self, store_dir: Path | None = None) -> None:
+        """Initialize the adapter.
+
+        Args:
+            store_dir: Entry directory. Defaults to
+                ``<project root>/.wl/cache/format``, resolved on first use so
+                the adapter follows the project root of the process's current
+                directory (the behaviour the single-file cache had, #125), and
+                reused for the rest of the run (#213 review LOW-5).
+        """
+        self._store_dir = store_dir
+        self._ledger_instance: CacheLedger | None = None
+
+    def lookup(self, file_path: Path, content: str) -> tuple[str, bool]:
+        """Return this file's cache key and whether a fresh entry already exists.
+
+        A hit renews the entry's timestamp (``CacheLedger.touch``), so its
+        freshness is counted from the last run that used the verdict rather
+        than from the run that recorded it -- the old single-file cache
+        re-stamped what it served (#213 review LOW-3).
+
+        Args:
+            file_path: The file about to be formatted.
+            content: Its current text, already read for the format run.
+
+        Returns:
+            ``(key, hit)`` -- the key always, and True when the ledger holds a
+            fresh entry for it. A read failure is a miss, never an exception.
+        """
+        ledger = self._ledger()
+        key = ledger.key(self.inputs(file_path, content))
+        return key, ledger.touch(key)
+
+    def inputs(self, file_path: Path, content: str) -> CacheInputs:
+        """The ordered fragments that decide this file's key."""
+        path_str = str(file_path).replace("\\", "/")
+        return CacheInputs(self.NAMESPACE, (path_str, content))
+
+    def record(self, cache_key: str) -> bool:
+        """Record a clean format result.
+
+        The ledger logs a write failure; the caller continues either way.
+
+        Args:
+            cache_key: The key returned by :meth:`lookup`.
+
+        Returns:
+            True if the entry was written, False if the write failed.
+        """
+        return self._ledger().put(cache_key, {"result": True})
+
+    def print_statistics(
+        self, cache_hits: int, total_files: int, error_occurred: bool
+    ) -> None:
+        """Print how many files were served from the cache."""
+        cache_percent = (cache_hits / total_files) * 100
+        # Ensure we're on a new line before printing cache statistics
+        if not error_occurred:
+            print()
+        print(
+            f"Cache statistics: {cache_hits}/{total_files} files "
+            f"({cache_percent:.1f}%) loaded from cache"
+        )
+
+    def _ledger(self) -> CacheLedger:
+        """This run's ledger for the project's format cache.
+
+        Resolved once per adapter, which is once per ``wl format`` run: the
+        walk to the project root happens on first use, so the adapter still
+        follows the CWD of the call that started the run (#125), and every
+        later file in the same run reuses the answer instead of walking again
+        (#213 review LOW-5).
+
+        The first resolution also reclaims stale entries (#213 review
+        MEDIUM-2). Per-entry files never expire on their own, so without this
+        the store would grow with every changed file forever; the sweep runs
+        before any of this run's lookups, so what it deletes is exactly what
+        could no longer be a hit.
+        """
+        ledger = self._ledger_instance
+        if ledger is None:
+            store_dir = self._store_dir
+            if store_dir is None:
+                store_dir = current_root(RootKind.PROJECT).wl_dir() / "cache" / "format"
+            ledger = CacheLedger(store_dir, self.TTL_SECONDS)
+            ledger.purge_stale()
+            self._ledger_instance = ledger
+        return ledger

wl_cli/commands/format/format_command.py

@@ -0,0 +1,197 @@
+"""Format command implementation using Click decorators."""
+
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+
+import click
+
+from ...utils.logging import log_info_pair
+from .format_coordinator import FormatCoordinator
+from .format_executor import FormatExecutor
+from .format_reporter import FormatReporter
+
+
+class FormatCommand:
+    """Implementation of the format command."""
+
+    def __init__(self) -> None:
+        """Initialize the format command implementation."""
+        self.coordinator = FormatCoordinator()
+        self.executor = FormatExecutor()
+        self.reporter = FormatReporter()
+
+    @property
+    def name(self) -> str:
+        return "format"
+
+    @property
+    def help(self) -> str:
+        return "Format code with ruff format - equivalent to make format"
+
+    @property
+    def aliases(self) -> list[str]:
+        return []
+
+    def execute(
+        self,
+        quiet: bool = False,
+        paths: Sequence[str] | None = None,
+        unsafe: bool = True,
+        report: bool = False,
+        step_by_step: bool = False,
+        for_lint: bool = False,
+        project_root: Path | None = None,
+    ) -> int:
+        """
+        Format code - equivalent to make format
+        代码格式化 - 等效于 make format
+
+        Returns the exit code; only the Click wrapper turns it into a
+        ``SystemExit`` (#164).
+
+        *project_root* is the directory the scope means (#188). ``wl lint``
+        passes its root down so the prefix formats ``root/src`` instead of
+        resolving ``src`` against the process cwd; ``None`` -- every direct
+        ``wl format`` call -- keeps the historical cwd scope.
+        """
+        if not quiet:
+            self._log_info("Formatting code...", "正在进行代码格式化...")
+
+        try:
+            return self.coordinator._execute_internal(
+                paths=list(paths) if paths else None,
+                quiet=quiet,
+                unsafe=unsafe,
+                report=report,
+                step_by_step=step_by_step,
+                for_lint=for_lint,
+                project_root=project_root,
+            )
+
+        except FileNotFoundError:
+            self._handle_file_not_found_error(quiet)
+            return 1
+        except Exception as e:
+            self._handle_general_error(e, quiet)
+            return 1
+
+    def run(
+        self,
+        quiet: bool = False,
+        paths: Sequence[str] | None = None,
+        unsafe: bool = True,
+        report: bool = False,
+        step_by_step: bool = False,
+        for_lint: bool = False,
+        project_root: Path | None = None,
+    ) -> int:
+        """Lifecycle alias for :meth:`execute`.
+
+        ``wl lint`` calls the format prefix through this name with
+        ``for_lint=True``. The signature is spelled out -- rather than
+        ``*args, **kwargs`` -- so mypy checks the caller: lint passes a
+        ``list[str]``, which is why ``paths`` is a ``Sequence`` (#172), and
+        its project root, which #188 needs to keep the scope cwd-independent.
+        """
+        return self.execute(
+            quiet=quiet,
+            paths=paths,
+            unsafe=unsafe,
+            report=report,
+            step_by_step=step_by_step,
+            for_lint=for_lint,
+            project_root=project_root,
+        )
+
+    def format_specified_paths(
+        self, paths, env, quiet, unsafe=False, step_by_step=False
+    ):
+        """Delegate to coordinator's format_specified_paths."""
+        return self.coordinator.format_specified_paths(
+            paths, env, quiet, unsafe, step_by_step=step_by_step
+        )
+
+    def format_defaults(
+        self, current_path, env, quiet, unsafe, for_lint, step_by_step=False
+    ):
+        """Delegate to coordinator's format_defaults."""
+        return self.coordinator.format_defaults(
+            current_path, env, quiet, unsafe, for_lint, step_by_step=step_by_step
+        )
+
+    def _log_info(self, en_msg: str, zh_msg: str) -> None:
+        """Log info message in both English and Chinese."""
+        log_info_pair(
+            en_msg,
+            zh_msg,
+        )
+
+    def _handle_file_not_found_error(self, quiet: bool) -> None:
+        """Handle FileNotFoundError."""
+        if not quiet:
+            self._log_info(
+                "Error: ruff is not installed or not found in PATH",
+                "错误：未安装 ruff 或在 PATH 中找不到",
+            )
+
+    def _handle_general_error(self, e: Exception, quiet: bool) -> None:
+        """Handle general exceptions."""
+        if not quiet:
+            self._log_info(
+                f"Error during formatting: {e}", f"错误：格式化期间出错: {e}"
+            )
+
+
+@click.command()
+@click.argument("paths", nargs=-1)
+@click.option("-q", "--quiet", is_flag=True, help="Suppress detailed output")
+@click.option("--unsafe", is_flag=True, help="Enable ruff's unsafe fixes")
+@click.option("--no-unsafe", "safe_mode", is_flag=True, help="Disable unsafe fixes")
+@click.option(
+    "--report",
+    is_flag=True,
+    help="Generate format report in todos folder",
+)
+@click.option(
+    "-s",
+    "--step-by-step",
+    is_flag=True,
+    help="Format all files; report the first error",
+)
+def format_command(
+    paths: tuple[str, ...],
+    quiet: bool,
+    unsafe: bool,
+    safe_mode: bool,
+    report: bool,
+    step_by_step: bool,
+) -> None:
+    """Format command Click wrapper."""
+    cmd = FormatCommand()
+    if unsafe:
+        actual_unsafe = True
+    elif safe_mode:
+        actual_unsafe = False
+    else:
+        actual_unsafe = True
+    exit_code = cmd.execute(
+        paths=paths,
+        quiet=quiet,
+        unsafe=actual_unsafe,
+        report=report,
+        step_by_step=step_by_step,
+    )
+    # The only place the format command turns its contract into a process
+    # status (#164); everything below it returns an int. Zero returns normally,
+    # the same wrapper shape as lint/gate (#166).
+    if exit_code:
+        sys.exit(exit_code)
+
+
+class FormatCommandImpl(FormatCoordinator):
+    """Backward-compatible wrapper for FormatCommand using old interface."""
+
+    def __init__(self):
+        """Initialize the format command implementation."""
+        super().__init__()