learningcircuit--local-deep-research/.pre-commit-hooks/check-loguru-formatting.py

#!/usr/bin/env python3
"""
Pre-commit hook to prevent stdlib printf-style formatting in direct loguru calls.

loguru uses brace formatting (`{}`), not stdlib logging placeholders like
`%s` or `%d`. Mixing the two leaves placeholders unrendered in runtime logs.

Applies to files importing either raw loguru or the project's diagnose-gated
``security.secure_logging`` wrapper (which delegates formatting to loguru).
The pytest guardian ``tests/utilities/test_loguru_placeholder_formatting.py``
imports this module so hook and guardian cannot diverge.
"""

import ast
from pathlib import Path
import re
import sys


PRINTF_PLACEHOLDER_RE = re.compile(
    r"%(?:\([^)]+\))?[#0 +\-]*\d*(?:\.\d+)?[sdfr]"
)
LOGURU_METHODS = {
    "trace",
    "debug",
    "info",
    "success",
    "warning",
    "error",
    "critical",
    "exception",
    "log",
}

# The secure_logging wrapper import, matched exactly (module + level) like
# check-sensitive-logging.py does — never by suffix.
WRAPPER_MODULE_RELATIVE = "security.secure_logging"
WRAPPER_MODULE_ABSOLUTE = "local_deep_research.security.secure_logging"

# SecureLogger.bind()/.patch() re-wrap and keep loguru brace formatting, so
# chained calls need the same placeholder check as direct ones.
WRAPPER_CHAIN_METHODS = {"bind", "patch"}


def imports_project_logger(tree: ast.AST) -> bool:
    """True if the module imports ``logger`` from loguru or the wrapper.

    Walks the whole tree so function-local imports are detected too.
    """
    for node in ast.walk(tree):
        if not isinstance(node, ast.ImportFrom):
            continue
        if not any(alias.name == "logger" for alias in node.names):
            continue
        if node.level == 0 and node.module in (
            "loguru",
            WRAPPER_MODULE_ABSOLUTE,
        ):
            return True
        if node.level > 0 and node.module == WRAPPER_MODULE_RELATIVE:
            return True
    return False


def _is_logger_receiver(expr: ast.AST) -> bool:
    """True for ``logger`` or a bind()/patch() chain rooted at ``logger``."""
    while (
        isinstance(expr, ast.Call)
        and isinstance(expr.func, ast.Attribute)
        and expr.func.attr in WRAPPER_CHAIN_METHODS
    ):
        expr = expr.func.value
    return isinstance(expr, ast.Name) and expr.id == "logger"


def find_printf_violations(tree: ast.AST) -> list[tuple[int, str]]:
    """Return (lineno, message) for logger calls using printf placeholders."""
    violations = []
    for node in ast.walk(tree):
        if not (
            isinstance(node, ast.Call)
            and isinstance(node.func, ast.Attribute)
            and node.func.attr in LOGURU_METHODS
            and _is_logger_receiver(node.func.value)
        ):
            continue

        method_name = node.func.attr
        message_index = 1 if method_name == "log" else 0
        min_args = 3 if method_name == "log" else 2
        if len(node.args) < min_args:
            continue

        message_arg = node.args[message_index]
        if not (
            isinstance(message_arg, ast.Constant)
            and isinstance(message_arg.value, str)
            and PRINTF_PLACEHOLDER_RE.search(message_arg.value)
        ):
            continue

        violations.append(
            (
                node.lineno,
                message_arg.value,
            )
        )

    return violations


def check_file(file_path: str) -> list[tuple[int, str]]:
    path = Path(file_path)
    if path.suffix != ".py":
        return []

    try:
        source = path.read_text(encoding="utf-8")
    except Exception as exc:
        return [(0, f"failed to read file: {exc}")]

    try:
        tree = ast.parse(source, filename=file_path)
    except SyntaxError:
        return []

    if not imports_project_logger(tree):
        return []

    return find_printf_violations(tree)


def main() -> int:
    exit_code = 0

    for file_path in sys.argv[1:]:
        violations = check_file(file_path)
        for lineno, message in violations:
            print(
                f"{file_path}:{lineno}: loguru logger call uses printf-style placeholders"
            )
            print(f"  {message!r}")
            exit_code = 1

    if exit_code:
        print()
        print(
            "Hint: use loguru brace formatting, e.g. logger.info('value: {}', x)"
        )

    return exit_code


if __name__ == "__main__":
    sys.exit(main())