"""Dataset registry — the only dataset-specific surface in api/.

Each subdirectory is one dataset. The folder name doubles as the Postgres
schema name, the SQLite filename under `ctrl/seed/data/<name>.sqlite`, and
the value of the `NVI_DATASET` env var that selects it.

Inside each dataset folder:
  schema_docs.yaml   — human descriptions for tables/columns
  metrics.yaml       — canonical SQL fragments for business terms

Both files are consumed by `api.tools.schema.load_schema()`. The Plan,
Analyses, Tools, and Runtime code reference no dataset name — they read
the active dataset through `settings.dataset`.
"""

from __future__ import annotations

from functools import lru_cache
from pathlib import Path
from typing import Any

import yaml

from api.config import get_settings

DATASETS_DIR = Path(__file__).resolve().parent


def active_dir() -> Path:
    return DATASETS_DIR / get_settings().dataset


def available() -> list[str]:
    return sorted(p.name for p in DATASETS_DIR.iterdir() if p.is_dir() and not p.name.startswith("_"))


@lru_cache(maxsize=None)
def read_yaml(dataset: str, filename: str) -> dict[str, Any]:
    """Load one YAML file from a dataset folder. Cached per (dataset, file)."""
    return yaml.safe_load((DATASETS_DIR / dataset / filename).read_text()) or {}