"""finish-task.sh 18단계 stage 경과시간 JSONL 로깅 헬퍼."""

from __future__ import annotations

import json
import os
from datetime import datetime, timezone
from pathlib import Path
from typing import Dict, Union

VALID_STAGES: tuple = (
    "qc_verify",
    "scope_guard",
    "worktree_manager_finish",
    "gh_pr_check",
    "git_gate",
    "impact_scanner",
    "ci_preflight",
    "bg_cleanup",
    "g3_verifier",
    "g4_gemini_gate",
    "lv4_audit",
    "codex_gate",
    "unresolved_gate",
    "goal_assertions",
    "task_timer_end",
    "token_tracker",
    "notify_completion",
    "extract_followup",
)

_DEFAULT_RELATIVE_LOG_PATH = Path("memory") / "logs" / "finish-task-timing.jsonl"
_ENV_OVERRIDE_KEY = "FINISH_TASK_TIMING_LOG_PATH"


def _detect_workspace_root() -> Path:
    """utils/finish_task_timing_logger.py 기준 한 단계 위 디렉토리를 workspace 루트로 본다."""
    return Path(__file__).resolve().parent.parent


def _resolve_log_path() -> Path:
    override = os.environ.get(_ENV_OVERRIDE_KEY)
    if override:
        return Path(override).resolve()
    return (_detect_workspace_root() / _DEFAULT_RELATIVE_LOG_PATH).resolve()


def record_stage_elapsed(
    stage_name: str,
    elapsed_sec: Union[float, int],
    task_id: str,
    team_id: str,
) -> Dict[str, object]:
    """18개 stage 중 하나의 경과시간을 JSONL 한 줄로 append 하고 row dict를 반환한다."""
    if stage_name not in VALID_STAGES:
        raise ValueError(
            f"invalid stage_name={stage_name!r}; must be one of VALID_STAGES"
        )

    try:
        elapsed_float = float(elapsed_sec)
    except (TypeError, ValueError) as exc:
        raise ValueError(f"elapsed_sec must be numeric, got {elapsed_sec!r}") from exc

    if elapsed_float < 0:
        raise ValueError(f"elapsed_sec must be >= 0, got {elapsed_float}")

    log_path = _resolve_log_path()
    log_path.parent.mkdir(parents=True, exist_ok=True)

    row: Dict[str, object] = {
        "ts": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.%f")[:-3] + "Z",
        "task_id": task_id,
        "team_id": team_id,
        "stage": stage_name,
        "elapsed_sec": elapsed_float,
    }

    line = json.dumps(row, ensure_ascii=False, separators=(",", ":"))
    with log_path.open("a", encoding="utf-8") as fh:
        fh.write(line + "\n")

    return row