"""Public path helpers for observability artefacts.

This module exposes the on-disk locations the library writes to, so
consumers writing observability-adjacent UI (a log viewer, a
crash-report browser, a "where does my state live?" diagnostic) have
a public alternative to reaching into the underscore-prefixed
helpers in :mod:`mgf.common.observability.logging_setup` and
:mod:`mgf.common.observability.crash_reporter`.

Every helper here is **lazy** — paths are resolved at call time, not
at import time (rule CF-04). This is load-bearing for per-test
isolation when tests monkeypatch ``HOME`` / ``XDG_STATE_HOME``.

Layout (cross-platform via :func:`mgf.common.config.platform_dir`)::

    <state>/<app>/                  ← default_state_dir()
    <state>/<app>/logs/<app>.log    ← default_log_path()
    <state>/<app>/crashes/          ← default_crash_dir()

Where ``<state>`` resolves per platform (XDG always wins when set):

  - Linux:   ``$XDG_STATE_HOME`` or ``~/.local/state``
  - macOS:   ``~/Library/Application Support``
  - Windows: ``%LOCALAPPDATA%`` (or ``<home>/AppData/Local`` fallback)

``<app>`` comes from :func:`mgf.common.app_name`, so each consumer
project gets its own namespace without colliding with others.

History (RA-29): this module previously hardcoded
``~/.local/state`` for every platform, so logs and crash reports
on Windows / macOS landed in a Linux-shaped path. Cross-platform
consistency restored by composing with
:func:`mgf.common.config.platform_dir`, which already handles
the per-OS state-dir mapping (used by ``default_config_path``).
"""

from __future__ import annotations

from typing import TYPE_CHECKING

from mgf.common._identity import app_name
from mgf.common.config._paths import platform_dir

if TYPE_CHECKING:
    from pathlib import Path


def default_state_dir() -> Path:
    """Per-app state directory — parent of ``logs/`` and ``crashes/``.

    Cross-platform via :func:`mgf.common.config.platform_dir`:

      - Linux:   ``$XDG_STATE_HOME`` or ``~/.local/state``
      - macOS:   ``~/Library/Application Support``
      - Windows: ``%LOCALAPPDATA%`` (or ``<home>/AppData/Local``)

    The directory is **not** created — callers that need it on disk
    must ``mkdir(parents=True, exist_ok=True)`` themselves.
    """
    return platform_dir("state") / app_name()


def default_log_path() -> Path:
    """Default rotating-file destination — ``<state>/<app>/logs/<app>.log``.

    This is where :func:`mgf.common.observability.setup_logging`
    writes when called without an explicit ``log_file=`` override.
    Surface this in a UI when answering "where do my logs live?".
    """
    name = app_name()
    return default_state_dir() / "logs" / f"{name}.log"


def default_crash_dir() -> Path:
    """Default crash-report directory — ``<state>/<app>/crashes/``.

    This is where :func:`mgf.common.observability.report_now` writes
    serialised crash reports. Surface this in a UI when listing
    or browsing crash artefacts.
    """
    return default_state_dir() / "crashes"


__all__ = [
    "default_crash_dir",
    "default_log_path",
    "default_state_dir",
]
