py-wlcli 0.8.0__py3-none-any.whl

wl_cli/utils/logging.py

@@ -0,0 +1,458 @@
+"""Logging utilities for WL Commands."""
+
+import inspect
+import os
+import sys
+import traceback
+from dataclasses import dataclass
+from typing import Any, Literal, cast
+
+from .language_utils import _should_display_language
+from .log_levels import LogLevel
+from .structured_logging.core import StructuredLogger
+from .structured_logging.env import is_performance_test as _is_performance_test
+from .structured_logging.env import is_pytest
+
+# default_logger 是**延迟**构造的。早先这里是模块级直接构造，于是 `import wl_cli`
+# 这一个动作就会经由 StructuredLogger → LoggingConfig → get_config() → ConfigManager
+# 去解析配置：读盘，并（在当时 _load_config 的写法下）把 .wl/config.json 写进 CWD。
+# 导入一个库不该有文件系统副作用，故模块级只放一个惰性代理。
+_logger_instance: StructuredLogger | None = None
+
+
+def _logger() -> StructuredLogger:
+    """Return the module-level logger, constructing it on first use."""
+    global _logger_instance
+    if _logger_instance is None:
+        _logger_instance = StructuredLogger("wl", min_level=LogLevel.INFO)
+        _logger_instance.enable_console = True
+    return _logger_instance
+
+
+class _LazyLogger:
+    """Module-level proxy that builds the real logger on first attribute use.
+
+    Keeps the `default_logger` name — including unittest.mock's ability to
+    patch it — without paying StructuredLogger's filesystem work at import.
+
+    Attribute writes and deletes are forwarded to the real logger, so
+    ``default_logger.min_level = X`` and ``mock.patch.object(default_logger,
+    "info")`` behave exactly as they did when the module held a concrete
+    logger: patch installs the mock on the real instance, and its ``delattr``
+    round-trip restores the bound method.
+    """
+
+    def __getattr__(self, item: str) -> Any:
+        return getattr(_logger(), item)
+
+    def __setattr__(self, key: str, value: Any) -> None:
+        setattr(_logger(), key, value)
+
+    def __delattr__(self, key: str) -> None:
+        delattr(_logger(), key)
+
+
+default_logger: StructuredLogger = cast("StructuredLogger", _LazyLogger())
+
+
+def _is_log_level_enabled(level: int) -> bool:
+    """Check if the given log level is enabled based on the current minimum level."""
+    try:
+        min_level = default_logger.min_level
+        if isinstance(min_level, int | float):
+            return min_level <= level
+    except (TypeError, AttributeError):
+        pass
+    return True
+
+
+def _add_caller_info(kwargs: dict[str, Any], frame_offset: int = 1) -> None:
+    """Add caller module/function/line information to kwargs."""
+    try:
+        frame = inspect.currentframe()
+        for _ in range(frame_offset):
+            if frame:
+                frame = frame.f_back
+        if frame:
+            caller_info = inspect.getframeinfo(frame)
+            kwargs.update(
+                {
+                    "module": os.path.basename(caller_info.filename).split(".")[0],
+                    "function": caller_info.function,
+                    "line": caller_info.lineno,
+                }
+            )
+    except (TypeError, AttributeError):
+        pass
+
+
+# ---------------------------------------------------------------------------
+# The single emit funnel (#135)
+#
+# The six verbs below are thin one-line aliases over `_emit`; the four guards
+# (level / lang / perf / caller) and the caller-frame choice are assembled in
+# `_emit` alone, driven by the per-verb policy table `_POLICIES`.
+#
+# The guards were never uniform across the verbs, and that drift is *behaviour*
+# kept verbatim here -- do not "fix" it in this change (explicitly out of scope,
+# tracked separately):
+#   * perf guard: only info / error / critical bail out under a performance test;
+#     debug / warning / exception log straight through.
+#   * caller info: debug / exception always attach it, error / critical attach it
+#     only outside pytest, info / warning never include it.
+# ---------------------------------------------------------------------------
+
+_CallerMode = Literal["never", "always", "outside_pytest"]
+
+
+@dataclass(frozen=True)
+class _EmitPolicy:
+    """Guard policy for one verb, consumed by :func:`_emit`.
+
+    ``logger_method`` is the :class:`StructuredLogger` method to call; note the
+    exception verb logs through ``error``.
+    """
+
+    logger_method: str
+    level: int
+    perf_guard: bool = False
+    caller: _CallerMode = "never"
+    formats_exception: bool = False
+
+
+_POLICIES: dict[str, _EmitPolicy] = {
+    "debug": _EmitPolicy("debug", LogLevel.DEBUG, caller="always"),
+    "info": _EmitPolicy("info", LogLevel.INFO, perf_guard=True),
+    "warning": _EmitPolicy("warning", LogLevel.WARNING),
+    "error": _EmitPolicy(
+        "error", LogLevel.ERROR, perf_guard=True, caller="outside_pytest"
+    ),
+    "critical": _EmitPolicy(
+        "critical", LogLevel.CRITICAL, perf_guard=True, caller="outside_pytest"
+    ),
+    "exception": _EmitPolicy(
+        "error", LogLevel.ERROR, caller="always", formats_exception=True
+    ),
+}
+
+# The funnel sits between the verb and `_add_caller_info`, so this offset is one
+# deeper than the pre-#135 value of 2. The extra hop is exactly the bump, which
+# keeps the resolved caller frame identical to before -- both for a direct verb
+# call and for a `log(level, ...)` dispatch.
+_CALLER_FRAME_OFFSET = 3
+
+
+def _attach_exception(kwargs: dict[str, Any], exc_info: Any) -> None:
+    """Attach the active (or explicitly supplied) exception to ``kwargs``."""
+    if exc_info is None:
+        exc_type, exc_value, exc_tb = sys.exc_info()
+        if exc_type:
+            kwargs.update(
+                {
+                    "error": str(exc_value),
+                    "traceback": "".join(
+                        traceback.format_exception(exc_type, exc_value, exc_tb)
+                    ),
+                }
+            )
+    else:
+        kwargs["error"] = str(exc_info)
+
+
+def _emit(
+    verb: str,
+    message: str,
+    *,
+    lang: str,
+    kwargs: dict[str, Any],
+    exc_info: Any = None,
+) -> None:
+    """The single funnel every verb logs through.
+
+    Guard order matches the pre-#135 verbs: level, then the perf gate, then the
+    language gate, then caller info / exception formatting.
+    """
+    policy = _POLICIES[verb]
+    if not _is_log_level_enabled(policy.level):
+        return
+    if policy.perf_guard and _is_performance_test():
+        return
+    if not _should_display_language(lang):
+        return
+    if policy.caller == "always" or (
+        policy.caller == "outside_pytest" and not is_pytest()
+    ):
+        _add_caller_info(kwargs, frame_offset=_CALLER_FRAME_OFFSET)
+    if policy.formats_exception:
+        _attach_exception(kwargs, exc_info)
+    getattr(default_logger, policy.logger_method)(message, lang=lang, **kwargs)
+
+
+# ``lang`` is keyword-only (#167). As a second positional parameter it silently
+# absorbed a Chinese message -- ``log_info(en_msg, zh_msg)`` emitted nothing
+# under any language setting, the #152 shape -- so the mistake now raises
+# TypeError instead. ``log_*_pair`` is the bilingual entry point and is
+# unaffected.
+def log_debug(message: str, *, lang: str = "en", **kwargs) -> None:
+    """Log a debug message (caller info attached)."""
+    _emit("debug", message, lang=lang, kwargs=kwargs)
+
+
+def log_info(message: str, *, lang: str = "en", **kwargs) -> None:
+    """Log an informational message (skipped under a performance test)."""
+    _emit("info", message, lang=lang, kwargs=kwargs)
+
+
+def log_warning(message: str, *, lang: str = "en", **kwargs) -> None:
+    """Log a warning message."""
+    _emit("warning", message, lang=lang, kwargs=kwargs)
+
+
+def log_error(message: str, *, lang: str = "en", **kwargs) -> None:
+    """Log an error message (caller info only outside pytest)."""
+    _emit("error", message, lang=lang, kwargs=kwargs)
+
+
+def log_critical(message: str, *, lang: str = "en", **kwargs) -> None:
+    """Log a critical message (caller info only outside pytest)."""
+    _emit("critical", message, lang=lang, kwargs=kwargs)
+
+
+# ``exc_info`` is keyword-only for the same reason ``lang`` is (#167): as a
+# second positional parameter it silently absorbed the Chinese half of a
+# translation pair -- ``log_exception(en_msg, zh_msg)`` bound ``zh_msg`` to
+# ``exc_info``, attached it as the error text, and emitted nothing under the
+# Chinese language setting (#172 wave 9). Keyword-only makes that shape a
+# ``TypeError`` at the call instead of a silent misbinding.
+def log_exception(
+    message: str, *, exc_info: Any = None, lang: str = "en", **kwargs
+) -> None:
+    """Log an exception, attaching the active/explicit exception details.
+
+    ``message`` is positional; ``exc_info`` and ``lang`` are keyword-only, so a
+    second positional argument (the old ``log_exception(en, zh)`` shape) fails
+    at the call rather than binding the Chinese text to ``exc_info``.
+    """
+    _emit("exception", message, lang=lang, kwargs=kwargs, exc_info=exc_info)
+
+
+# ---------------------------------------------------------------------------
+# The bilingual double-write entry point (#146)
+#
+# A *pair* is the two adjacent statements the codebase used to spell out by
+# hand -- an English line and a Chinese line carrying the same message:
+#
+#     log_info("✓ Git repository initialized")
+#     log_info("✓ Git仓库初始化完成", lang="zh")
+#
+# `log_pair` collapses them into one call whose observable output is identical:
+# the two `_emit` calls below are exactly the two the hand-written form made,
+# in the same order, each judged by the same level / perf / language guards.
+# The language decision stays in `_should_display_language` (reached through
+# `_emit`) -- this module never re-derives it.
+#
+# Every entry point below calls `_emit` *directly* rather than delegating to a
+# shared helper, because `_emit` resolves caller info at a fixed frame depth
+# (_CALLER_FRAME_OFFSET): one extra hop would move debug/error/critical caller
+# info onto the wrapper. Each `_emit` call also gets its own copy of `kwargs`,
+# matching the fresh dict that `**kwargs` gave each hand-written call.
+# ---------------------------------------------------------------------------
+
+
+def log_pair(en: str, zh: str, level: str = "info", **kwargs) -> None:
+    """Log the English and Chinese variants of one message (#146).
+
+    Args:
+        en: The English variant, emitted with ``lang="en"``.
+        zh: The Chinese variant, emitted with ``lang="zh"``.
+        level: Verb to log through -- one of "debug", "info", "warning",
+            "error", "critical" or "exception". Defaults to "info".
+        **kwargs: Extra context, applied to both variants. ``exc_info`` is
+            forwarded to `_emit` for the "exception" verb.
+    """
+    exc_info = kwargs.pop("exc_info", None)
+    _emit(level, en, lang="en", kwargs=dict(kwargs), exc_info=exc_info)
+    _emit(level, zh, lang="zh", kwargs=dict(kwargs), exc_info=exc_info)
+
+
+def log_debug_pair(en: str, zh: str, **kwargs) -> None:
+    """Debug-level `log_pair` (caller info attached to both variants)."""
+    _emit("debug", en, lang="en", kwargs=dict(kwargs))
+    _emit("debug", zh, lang="zh", kwargs=dict(kwargs))
+
+
+def log_info_pair(en: str, zh: str, **kwargs) -> None:
+    """Info-level `log_pair` (both variants skipped under a performance test)."""
+    _emit("info", en, lang="en", kwargs=dict(kwargs))
+    _emit("info", zh, lang="zh", kwargs=dict(kwargs))
+
+
+def log_warning_pair(en: str, zh: str, **kwargs) -> None:
+    """Warning-level `log_pair`."""
+    _emit("warning", en, lang="en", kwargs=dict(kwargs))
+    _emit("warning", zh, lang="zh", kwargs=dict(kwargs))
+
+
+def log_error_pair(en: str, zh: str, **kwargs) -> None:
+    """Error-level `log_pair` (caller info on both, only outside pytest)."""
+    _emit("error", en, lang="en", kwargs=dict(kwargs))
+    _emit("error", zh, lang="zh", kwargs=dict(kwargs))
+
+
+def log(level: int, message: str, **kwargs) -> None:
+    """
+    Log a message with specified level.
+
+    Dispatch stays by verb name (each verb funnels through `_emit`); the
+    `mock.patch("wl_cli.utils.logging.log_*")` contract depends on it.
+
+    Args:
+        level: Log level as integer (use LogLevel enum).
+        message (str): Message to log.
+        **kwargs: Additional context for the log message.
+    """
+    # Backward compatibility: handle old keyword argument names
+    # Old signature: def log(message: int, message_str: str, **kwargs)
+    if "message_str" in kwargs:
+        message = kwargs.pop("message_str")
+    old_level = kwargs.pop("message", None)
+    if old_level is not None and isinstance(old_level, int):
+        level = old_level
+
+    if level == LogLevel.DEBUG:
+        log_debug(message, **kwargs)
+    elif level == LogLevel.INFO:
+        log_info(message, **kwargs)
+    elif level == LogLevel.WARNING:
+        log_warning(message, **kwargs)
+    elif level == LogLevel.ERROR:
+        log_error(message, **kwargs)
+    elif level == LogLevel.CRITICAL:
+        log_critical(message, **kwargs)
+
+
+# Context management utilities
+def push_log_context(**context) -> None:
+    """
+    Push context to the default logger's context stack.
+
+    Args:
+        **context: Context key-value pairs.
+    """
+    if hasattr(default_logger, "push_context"):
+        default_logger.push_context(**context)
+
+
+def pop_log_context() -> dict[str, Any] | None:
+    """
+    Pop context from the default logger's context stack.
+
+    Returns:
+        The popped context or None if stack is empty.
+    """
+    if hasattr(default_logger, "pop_context"):
+        return cast("dict[str, Any] | None", default_logger.pop_context())
+    return None
+
+
+def clear_log_context() -> None:
+    """
+    Clear all context from the default logger's context stack.
+    """
+    if hasattr(default_logger, "clear_context"):
+        default_logger.clear_context()
+
+
+# Enhanced get_logger function
+def get_logger(
+    name: str = "wl", config: dict[str, Any] | None = None
+) -> StructuredLogger:
+    """
+    Get a logger instance with the specified name and optional configuration.
+
+    Args:
+        name (str, optional): Logger name. Defaults to "wl".
+        config (Optional[Dict[str, Any]]): Optional configuration dictionary.
+
+    Returns:
+        StructuredLogger: Logger instance.
+    """
+    if config:
+        # Create logger with custom configuration
+        logger = StructuredLogger(name)
+        # Apply configuration
+        if "log_level" in config:
+            if isinstance(config["log_level"], str):
+                logger.min_level = getattr(
+                    LogLevel, config["log_level"].upper(), LogLevel.INFO
+                )
+            else:
+                logger.min_level = config["log_level"]
+        if "log_file" in config:
+            logger.log_file = config["log_file"]
+        return logger
+    else:
+        return StructuredLogger(name)
+
+
+# Aliases for backward compatibility
+info = log_info
+debug = log_debug
+warning = log_warning
+error = log_error
+critical = log_critical
+exception = log_exception
+
+
+# Module-level convenience functions
+def configure_logging(config: dict[str, Any]) -> None:
+    """
+    Configure the default logger with the specified configuration.
+
+    Args:
+        config (Dict[str, Any]): Configuration dictionary.
+    """
+    global _logger_instance, default_logger
+    _logger_instance = get_logger("wl", config)
+    default_logger = _logger_instance
+
+
+def get_log_level() -> int:
+    """
+    Get the current log level of the default logger.
+
+    Returns:
+        int: Current log level.
+    """
+    return cast("int", default_logger.min_level)
+
+
+def set_log_level(level: int) -> None:
+    """
+    Set the log level of the default logger.
+
+    Args:
+        level (int): New log level.
+    """
+    default_logger.min_level = level
+
+
+def enable_console_logging(enable: bool = True) -> None:
+    """
+    Enable or disable console logging for the default logger.
+
+    Args:
+        enable (bool): Whether to enable console logging.
+    """
+    if hasattr(default_logger, "enable_console"):
+        default_logger.enable_console = enable
+
+
+def set_log_file(file_path: str | None) -> None:
+    """
+    Set the log file path for the default logger.
+
+    Args:
+        file_path (Optional[str]): Log file path or None to disable file logging.
+    """
+    default_logger.log_file = file_path

wl_cli/utils/output_context.py

@@ -0,0 +1,142 @@
+"""Output context detection utility.
+
+Detects execution context (Claude skill vs manual terminal) and provides
+output verbosity configuration to optimize token consumption.
+"""
+
+import os
+import sys
+from dataclasses import dataclass
+
+
+@dataclass
+class OutputConfig:
+    """Configuration for output behavior based on execution context."""
+
+    verbose: bool
+    show_progress_bars: bool
+    concise_mode: bool
+
+
+def detect_output_context() -> OutputConfig:
+    """Detect the execution context and determine output configuration.
+
+    Detection strategy:
+    1. Check environment variables for explicit override (WL_VERBOSE, WL_QUIET)
+    2. Check if running in Claude/Anthropic skill context (CLAUDE, ANTHROPIC)
+    3. Check if stdout is a terminal (tty)
+    4. Check if running in CI
+    5. Default to verbose output if no indicators found
+
+    Returns:
+        OutputConfig with appropriate verbosity settings.
+    """
+    # Check for explicit environment variable overrides first
+    if "WL_VERBOSE" in os.environ:
+        return OutputConfig(verbose=True, show_progress_bars=True, concise_mode=False)
+    if "WL_QUIET" in os.environ:
+        return OutputConfig(verbose=False, show_progress_bars=False, concise_mode=True)
+
+    # Check if running in Claude skill context
+    in_claude = (
+        "CLAUDE" in os.environ or "ANTHROPIC" in os.environ or "WL_SKILL" in os.environ
+    )
+
+    # Check if stdout is a terminal
+    is_tty = sys.stdout.isatty()
+
+    # Check if running in CI
+    is_ci = (
+        "CI" in os.environ
+        or "GITHUB_ACTIONS" in os.environ
+        or "GITLAB_CI" in os.environ
+    )
+
+    # Decision logic:
+    # - In Claude context: use concise output, no progress bars
+    # - In CI/non-tty: use concise output
+    # - In terminal (tty): use full output with progress bars
+    if in_claude or is_ci or not is_tty:
+        return OutputConfig(verbose=False, show_progress_bars=False, concise_mode=True)
+    else:
+        return OutputConfig(verbose=True, show_progress_bars=True, concise_mode=False)
+
+
+def get_output_config(
+    override_quiet: bool | None = None, override_verbose: bool | None = None
+) -> OutputConfig:
+    """Get output configuration with optional overrides.
+
+    Args:
+        override_quiet: If True, force concise output. If False, no override.
+        override_verbose: If True, force verbose output. If False, no override.
+
+    Returns:
+        OutputConfig with overrides applied if specified.
+    """
+    config = detect_output_context()
+
+    # Command-line flags override automatic detection
+    if override_verbose:
+        config.verbose = True
+        config.show_progress_bars = True
+        config.concise_mode = False
+    elif override_quiet:
+        config.verbose = False
+        config.show_progress_bars = False
+        config.concise_mode = True
+
+    return config
+
+
+def should_show_progress_bars(
+    override_quiet: bool | None = None, override_verbose: bool | None = None
+) -> bool:
+    """Check if progress bars should be shown.
+
+    Convenience helper for places that only need this decision.
+
+    Args:
+        override_quiet: Force quiet from command-line flag.
+        override_verbose: Force verbose from command-line flag.
+
+    Returns:
+        True if progress bars should be shown, False otherwise.
+    """
+    config = get_output_config(override_quiet, override_verbose)
+    return config.show_progress_bars
+
+
+def is_concise_mode(
+    override_quiet: bool | None = None, override_verbose: bool | None = None
+) -> bool:
+    """Check if we should run in concise mode.
+
+    Concise mode reduces verbose logging and unnecessary output
+    to save tokens when running in Claude skill context.
+
+    Args:
+        override_quiet: Force quiet from command-line flag.
+        override_verbose: Force verbose from command-line flag.
+
+    Returns:
+        True if concise mode should be used.
+    """
+    config = get_output_config(override_quiet, override_verbose)
+    return config.concise_mode
+
+
+def is_verbose(
+    override_quiet: bool | None = None, override_verbose: bool | None = None
+) -> bool:
+    """Check if verbose output is enabled.
+
+    Args:
+        override_quiet: Force quiet from command-line flag.
+        override_verbose: Force verbose from command-line flag.
+
+    Returns:
+        True if verbose output should be shown.
+    """
+    config = get_output_config(override_quiet, override_verbose)
+    return config.verbose

wl_cli/utils/performance/__init__.py

@@ -0,0 +1 @@
+"""Performance monitoring utilities package."""