"""Backward-compatibility layer for feature key resolution.

Phase C introduced 3-level feature naming (``module.capability.feature``).
This module provides alias lookup so that old 2-level keys
(``module.feature_name``) continue to work for 6 months during the
transition period.

Usage::

    from simorgh.apps.modules.compat import resolve_feature_key

    canonical = resolve_feature_key("crm.pipeline_management")
    # → "crm.sales.pipeline" (or the same key if already 3-level)

    if is_feature_available(tenant, resolve_feature_key("old.key"), user):
        ...

Sunset: 2027-01-01.  After sunset, old keys will raise ``DeprecationWarning``
and eventually be removed.
"""

from __future__ import annotations

import warnings

# ---------------------------------------------------------------------------
# Old (2-level) → New (3-level) feature key aliases
# ---------------------------------------------------------------------------
# Generated from the Phase C taxonomy analysis.
# Each entry maps a 2-level key to its canonical 3-level replacement.

FEATURE_KEY_ALIASES: dict[str, str] = {
    # ── Workbox ────────────────────────────────────────────────────────
    "workbox.workitem_my_work": "workbox.work.workitem_my_work",
    "workbox.workitem_pending_approvals": "workbox.work.workitem_pending_approvals",
    "workbox.workitem_delegated": "workbox.work.workitem_delegated",
    "workbox.workitem_overdue": "workbox.work.workitem_overdue",
    "workbox.workitem_completed": "workbox.work.workitem_completed",
    "workbox.workitem_dashboard": "workbox.work.workitem_dashboard",
    "workbox.workitem_unified_search": "workbox.work.workitem_unified_search",
    "workbox.workitem_realtime": "workbox.work.workitem_realtime",
    "workbox.workitem_create": "workbox.work.workitem_create",
    "workbox.workitem_timeline": "workbox.work.workitem_timeline",
    # ── Visualization ───────────────────────────────────────────────────
    "visualization.view_configurations": "visualization.views.view_configurations",
    "visualization.dashboard_engine": "visualization.views.dashboard_engine",
    "visualization.chart_engine": "visualization.views.chart_engine",
    "visualization.saved_views": "visualization.views.saved_views",
    "visualization.view_export": "visualization.views.view_export",
    # ── Time Tracking ───────────────────────────────────────────────────
    "time_tracking.time_logging": "time_tracking.tracking.time_logging",
    "time_tracking.time_approval": "time_tracking.tracking.time_approval",
    "time_tracking.time_reports": "time_tracking.tracking.time_reports",
    "time_tracking.billable_tracking": "time_tracking.tracking.billable_tracking",
    # ── Notifications ───────────────────────────────────────────────────
    "notifications.in_app_notifications": "notifications.delivery.in_app_notifications",
    "notifications.email_notifications": "notifications.delivery.email_notifications",
    "notifications.sms_notifications": "notifications.delivery.sms_notifications",
    "notifications.notification_preferences": "notifications.delivery.notification_preferences",
    # ── Reporting ───────────────────────────────────────────────────────
    "reporting.report_viewer": "reporting.reports.report_viewer",
    "reporting.report_filters": "reporting.reports.report_filters",
    "reporting.report_exports": "reporting.reports.report_exports",
    "reporting.scheduled_reports": "reporting.reports.scheduled_reports",
    "reporting.kpi_dashboards": "reporting.dashboards.kpi_dashboards",
    # ── Platform Core ───────────────────────────────────────────────────
    "platform_core.base_models": "platform_core.core.base_models",
    "platform_core.scoped_queries": "platform_core.core.scoped_queries",
    "platform_core.global_search": "platform_core.search.global_search",
    "platform_core.attachments": "platform_core.files.attachments",
    "platform_core.comments": "platform_core.collaboration.comments",
    "platform_core.activity_feed": "platform_core.collaboration.activity_feed",
    "platform_core.custom_fields": "platform_core.forms.custom_fields",
    "platform_core.tags": "platform_core.collaboration.tags",
    "platform_core.notes": "platform_core.collaboration.notes",
    "platform_core.dynamic_forms": "platform_core.forms.dynamic_forms",
    "platform_core.reference_numbers": "platform_core.core.reference_numbers",
    "platform_core.import_engine": "platform_core.io.import_engine",
    "platform_core.export_engine": "platform_core.io.export_engine",
    "platform_core.print_engine": "platform_core.print.print_engine",
    "platform_core.message_templates": "platform_core.templates.message_templates",
    "platform_core.document_templates": "platform_core.templates.document_templates",
    "platform_core.export_layouts": "platform_core.io.export_layouts",
    # ── Escalation Engine ───────────────────────────────────────────────
    "escalation_engine.escalation_rule_management": "escalation_engine.management.escalation_rule_management",
    "escalation_engine.escalation_instance_tracking": "escalation_engine.management.escalation_instance_tracking",
    "escalation_engine.escalation_hierarchy": "escalation_engine.management.escalation_hierarchy",
    "escalation_engine.escalation_time_based": "escalation_engine.management.escalation_time_based",
    # ── Storage ─────────────────────────────────────────────────────────
    "storage.file_processing": "storage.files.file_processing",
    # ── Provisioning ────────────────────────────────────────────────────
    "provisioning.seed_runner": "provisioning.fixtures.seed_runner",
    "provisioning.snapshot_manager": "provisioning.fixtures.snapshot_manager",
    "provisioning.benchmark_generator": "provisioning.fixtures.benchmark_generator",
    # ── BPM ─────────────────────────────────────────────────────────────
    "bpm.pcf_framework": "bpm.processes.pcf_framework",
    "bpm.process_definition": "bpm.processes.process_definition",
    "bpm.raci_matrix": "bpm.processes.raci_matrix",
    "bpm.kpi_management": "bpm.processes.kpi_management",
    "bpm.process_execution": "bpm.processes.process_execution",
    "bpm.process_control": "bpm.processes.process_control",
    "bpm.bpmn_diagrams": "bpm.processes.bpmn_diagrams",
    # ── Projects (mixed — some were already 3-level) ────────────────────
    "projects.project_phases": "projects.management.project_phases",
    "projects.milestones": "projects.management.milestones",
    "projects.team_management": "projects.collaboration.team_management",
    "projects.gantt_view": "projects.management.gantt_view",
    "projects.project_templates": "projects.management.project_templates",
    # ── SLA Engine (mixed — some were already 3-level) ──────────────────
    "sla_engine.sla_breach_monitoring": "sla_engine.policies.sla_breach_monitoring",
    "sla_engine.sla_recovery": "sla_engine.policies.sla_recovery",
    # ── Tasks (mixed — some were already 3-level) ───────────────────────
    "tasks.subtasks": "tasks.management.subtasks",
    "tasks.task_comments": "tasks.management.task_comments",
    "tasks.task_attachments": "tasks.management.task_attachments",
    "tasks.task_watchers": "tasks.management.task_watchers",
    "tasks.task_templates": "tasks.management.task_templates",
}


# ---------------------------------------------------------------------------
# Public API
# ---------------------------------------------------------------------------


def resolve_feature_key(key: str, *, warn: bool = False) -> str:
    """Resolve a feature key, translating old 2-level keys to 3-level.

    If *key* is already a 3-level (or unknown) key, it is returned unchanged.

    Args:
        key: A feature key that may be in the old 2-level format.
        warn: If ``True``, issue a ``DeprecationWarning`` when an old key
              is resolved.  Set to ``True`` in development/staging to
              find stragglers.

    Returns:
        The canonical 3-level feature key.
    """
    resolved = FEATURE_KEY_ALIASES.get(key)
    if resolved is not None:
        if warn:
            warnings.warn(
                f"Feature key {key!r} is deprecated; use {resolved!r} instead.",
                DeprecationWarning,
                stacklevel=2,
            )
        return resolved
    return key


def is_canonical(key: str) -> bool:
    """Return ``True`` if *key* is already in canonical 3-level format."""
    return key not in FEATURE_KEY_ALIASES


# ---------------------------------------------------------------------------
# Reverse map — for migration rollback
# ---------------------------------------------------------------------------

REVERSE_ALIASES: dict[str, str] = {v: k for k, v in FEATURE_KEY_ALIASES.items()}