"""
日志工具函数

提供标准化的 RuleFiles 模块日志格式化工具。
"""

from typing import Any


def format_log(action: str, stage: str, **kwargs: Any) -> str:
    """
    格式化日志消息，确保一致的日志格式。

    格式: [RULES] <action> | stage=<stage> key1=<v1> key2=<v2> ...

    Args:
        action: 一句话动作描述
        stage: 阶段名称 (discover_dirs, scan, parse, load, select, summary, index, init_rule, fallback, reset, deprecated)
        **kwargs: 其他上下文字段

    Returns:
        str: 格式化的日志消息

    Examples:
        >>> format_log("开始加载规则", "load", project_root="/path")
        '[RULES] 开始加载规则 | stage=load project_root=/path'

        >>> format_log("扫描完成", "scan", file_count=10, loaded_count=8)
        '[RULES] 扫描完成 | stage=scan file_count=10 loaded_count=8'
    """
    parts = [f"[RULES] {action} | stage={stage}"]

    for key, value in kwargs.items():
        parts.append(f"{key}={value}")

    return " ".join(parts)


def format_duration_ms(start_time: float, end_time: float) -> int:
    """
    计算并格式化持续时间（毫秒）。

    Args:
        start_time: 开始时间（通过 time.perf_counter() 获取）
        end_time: 结束时间（通过 time.perf_counter() 获取）

    Returns:
        int: 持续时间（毫秒）
    """
    return int((end_time - start_time) * 1000)
