"""Cross-Skill-Helper-Import für Bundle-Skills mit Bindestrich-Ordnernamen.

Kapselt die importlib.util.spec_from_file_location-Mechanik, damit Bundle-Convention
(Ordnernamen mit Bindestrich) und Python-Modul-Imports (kein Bindestrich in Identifiern)
koexistieren können. Cache-Kontrolle über frischen Modul-Schlüssel pro Aufruf.
"""

from importlib.util import spec_from_file_location, module_from_spec
from pathlib import Path
import sys


def import_helper(
    skill_name: str,
    module_name: str,
    bundle_root: "Path | None" = None,
    subpath: str = "",
):
    """Importiert <bundle_root>/.skills/<skill_name>/[<subpath>/]<module_name>.py als frisches Modul.

    Args:
        skill_name: Bundle-Skill-Ordnername mit Bindestrich, z.B. "vault-gap-analysis".
        module_name: Python-Modul-Name ohne .py-Suffix, z.B. "graph_analyzer".
        bundle_root: Optionaler Override für den Bundle-Root-Pfad. Standard: aus
            der Datei-Position von cross_skill.py abgeleitet. Für Tests nützlich
            (z.B. als CLI-Argument via --bundle-root durchgereicht).
        subpath: Optionaler Sub-Pfad innerhalb des Skill-Verzeichnisses, z.B.
            "scripts" für Skills, deren Python-Module unter einem scripts/-
            Ordner liegen (Beispiel: getmyinvoices/scripts/gmi_client.py).
            Leer-String (Default) sucht direkt im Skill-Root.

    Returns:
        Das importierte Modul.

    Raises:
        FileNotFoundError: wenn das Modul-File nicht existiert.
        ImportError: wenn das Modul nicht geladen werden kann.

    Cache-Verhalten: Modul wird unter dem Schlüssel
    f"_bundle_skill_{skill_name}_{module_name}" in sys.modules abgelegt —
    Bindestrich-Skill-Namen werden zu Unterstrichen normalisiert, damit
    Python-Identifier-Regeln eingehalten werden. Der subpath fließt NICHT in
    den Cache-Schlüssel ein (Modul-Identität ist Skill+Modulname, nicht der
    Layout-Pfad). Wiederholte Aufrufe geben das gleiche Modul-Objekt zurück
    (keine doppelte Initialisierung).
    """
    if bundle_root is None:
        bundle_root = Path(__file__).resolve().parents[2]  # .skills/_lib/cross_skill.py → bundle_root
    skill_dir = bundle_root / ".skills" / skill_name
    if subpath:
        module_file = skill_dir / subpath / f"{module_name}.py"
    else:
        module_file = skill_dir / f"{module_name}.py"
    if not module_file.exists():
        raise FileNotFoundError(f"Cross-skill module not found: {module_file}")

    cache_key = f"_bundle_skill_{skill_name.replace('-', '_')}_{module_name}"
    if cache_key in sys.modules:
        return sys.modules[cache_key]

    spec = spec_from_file_location(cache_key, module_file)
    if spec is None or spec.loader is None:
        raise ImportError(f"Cannot load spec for {module_file}")
    module = module_from_spec(spec)
    sys.modules[cache_key] = module
    spec.loader.exec_module(module)
    return module
