#!/usr/bin/env python3
"""Verify every public ``pythonnative`` symbol is exercised by an E2E demo.

Run as part of ``./scripts/check.sh`` or directly:

    python scripts/check-e2e-coverage.py

The script:

1. Reads ``pythonnative.__all__`` to get the list of public symbols.
2. Reads ``examples/e2e-suite/app/registry.py`` to discover every
   demo's ``feature`` field. Each ``feature`` either matches a name
   in ``__all__`` or uses a ``"category::name"`` form for sub-features
   that aren't directly listed.
3. Reports any public symbol not covered by at least one demo.
4. Reports any demo flow file missing for a registered demo.

Exit code is ``0`` when every public symbol is covered and every demo
has a matching flow file; ``1`` otherwise.

This script is *static analysis only*: it doesn't run the app or the
flows. It exists so that adding a new public export to ``pythonnative``
without adding an E2E demo is a CI failure rather than a silent
regression.
"""

from __future__ import annotations

import ast
import json
import re
import sys
from pathlib import Path
from typing import Iterable, Set

ROOT = Path(__file__).resolve().parents[1]
SRC = ROOT / "src" / "pythonnative" / "__init__.py"
REGISTRY = ROOT / "examples" / "e2e-suite" / "app" / "registry.py"
FLOWS_DIR = ROOT / "tests" / "e2e" / "flows"

# Symbols intentionally NOT covered by a directly-mapped E2E flow.
# Each entry has a comment explaining why the symbol is exempt: type
# alias, ambient infrastructure exercised by every flow, or platform
# capability that requires real device hardware. New entries should
# justify themselves in the same way.
INTENTIONAL_EXEMPTIONS: Set[str] = {
    # --------------------------------------------------------------
    # Type-only re-exports: statically checkable, no UI surface.
    # --------------------------------------------------------------
    "Element",
    "AlignItems",
    "AlignSelf",
    "AutoCapitalize",
    "Color",
    "Dimension",
    "EdgeInsets",
    "FlexDirection",
    "FontWeight",
    "JustifyContent",
    "KeyboardType",
    "Overflow",
    "Position",
    "ReturnKeyType",
    "ScaleType",
    "ShadowOffset",
    "Style",
    "StyleProp",
    "TextAlign",
    "TextDecoration",
    "ThemeContext",
    "TransformSpec",
    "AnimatedValue",  # observed via use_animated_value usage in animations
    "QueryResult",  # observed via use_query demo
    "MutationCall",  # observed via use_mutation demo
    "MutationState",  # observed via use_mutation demo
    # --------------------------------------------------------------
    # Built-in Props dataclasses: exercised indirectly via their
    # corresponding component demos.
    # --------------------------------------------------------------
    "ActivityIndicatorProps",
    "ButtonProps",
    "CheckboxProps",
    "DatePickerProps",
    "ImageBackgroundProps",
    "ImageProps",
    "KeyboardAvoidingViewProps",
    "ModalProps",
    "PickerProps",
    "PressableProps",
    "ProgressBarProps",
    "SafeAreaViewProps",
    "ScrollViewProps",
    "SegmentedControlProps",
    "SliderProps",
    "SpacerProps",
    "StatusBarProps",
    "SwitchProps",
    "TextInputProps",
    "TextProps",
    "TouchableOpacityProps",
    "ViewProps",
    "WebViewProps",
    # --------------------------------------------------------------
    # Ambient infrastructure exercised by every flow (importing the
    # app + rendering any screen invokes them, so a dedicated demo
    # would be redundant).
    # --------------------------------------------------------------
    "component",  # @pn.component decorator, every screen uses it
    "Column",  # used everywhere; co-tested with View in ViewColumnRowDemo
    "Row",  # used everywhere; co-tested with View in ViewColumnRowDemo
    "NavigationContainer",  # wraps the root navigator; used by main.py
    "create_stack_navigator",  # used by main.py; every flow pushes screens
    "create_screen",  # platform bridge invoked by the native templates
    "use_navigation",  # used by every screen for go_back
    "use_animated_value",  # used in every animation demo
    "Provider",  # covered by use_context demo
    "create_context",  # covered by use_context demo
    "style",  # the style helper itself is exercised by every styled demo
    "resolve_style",  # internal helper exposed for SDK authors
    # --------------------------------------------------------------
    # Hooks whose values depend on physical device state that an
    # emulator/simulator can't reliably reproduce.
    # --------------------------------------------------------------
    "use_safe_area_insets",  # no reliable insets in emulator viewport
    "use_keyboard_height",  # requires a real keyboard transition
    "use_app_state",  # requires backgrounding the app (device lifecycle)
    "use_net_info",  # requires toggling real connectivity
    # --------------------------------------------------------------
    # Networking + native-module surfaces. These need network or
    # platform hardware (camera, location, notifications, clipboard,
    # haptics, biometrics, …) that CI emulators don't reliably
    # provide; tested via unit tests in tests/test_net.py and
    # tests/test_native_modules.py against their desktop fallbacks.
    # --------------------------------------------------------------
    "fetch",
    "HTTPError",
    "Response",
    "AppState",
    "Battery",
    "Biometrics",
    "Camera",
    "Clipboard",
    "FileSystem",
    "Haptics",
    "Linking",
    "Location",
    "NetInfo",
    "Notifications",
    "Permissions",
    "SecureStore",
    "Share",
    "Vibration",
    # --------------------------------------------------------------
    # SDK re-exports: module-level names mirroring submodule content.
    # --------------------------------------------------------------
    "runtime",  # module re-export; run_async demo covers it
    "sdk",  # module re-export; custom_component demo covers it
    "ViewHandler",  # ABC; subclassed by built-in handlers
    "element_factory",  # tested via unit tests; needs registered handlers
    "register_component",  # tested via unit tests; needs handler implementations
    "Props",  # tested in custom_component demo and SDK unit tests
}


def _public_symbols() -> Set[str]:
    """Return the values of ``__all__`` in the pythonnative package.

    Parsed via ``ast`` rather than imported, so the check can run
    without instantiating the package (which would pull in iOS/Android
    code paths that fail off-device).
    """
    tree = ast.parse(SRC.read_text(encoding="utf-8"))
    for node in ast.walk(tree):
        if isinstance(node, ast.Assign):
            for target in node.targets:
                if isinstance(target, ast.Name) and target.id == "__all__":
                    if isinstance(node.value, ast.List):
                        names: Set[str] = set()
                        for el in node.value.elts:
                            if isinstance(el, ast.Constant) and isinstance(el.value, str):
                                names.add(el.value)
                        return names
    raise RuntimeError(f"No __all__ list found in {SRC}")


def _read_registry_features() -> Set[str]:
    text = REGISTRY.read_text(encoding="utf-8")
    # Match: DemoEntry("id", "Category", "Title", "feature", ComponentName),
    pattern = re.compile(
        r'DemoEntry\(\s*"(?P<id>[^"]+)"\s*,\s*"(?P<category>[^"]+)"\s*,'
        r'\s*"(?P<title>[^"]+)"\s*,\s*"(?P<feature>[^"]+)"\s*,',
        re.MULTILINE,
    )
    return {m.group("feature") for m in pattern.finditer(text)}


def _read_registry_ids() -> Set[str]:
    text = REGISTRY.read_text(encoding="utf-8")
    pattern = re.compile(r'DemoEntry\(\s*"(?P<id>[^"]+)"', re.MULTILINE)
    return {m.group("id") for m in pattern.finditer(text)}


def _flow_files() -> Set[str]:
    """Return the set of demo ids that have a flow file."""
    ids: Set[str] = set()
    for path in FLOWS_DIR.rglob("*.yaml"):
        # Flow filename is the demo id (e.g. ``use_state.yaml``).
        ids.add(path.stem)
    return ids


def _format_report(
    public: Iterable[str],
    features: Set[str],
    demo_ids: Set[str],
    flow_ids: Set[str],
) -> dict:
    public_set = set(public)
    direct_covered = features & public_set
    missing_public = public_set - features - INTENTIONAL_EXEMPTIONS
    missing_flows = demo_ids - flow_ids
    extra_flows = flow_ids - demo_ids
    return {
        "public_symbols": len(public_set),
        "demos": len(demo_ids),
        "flows": len(flow_ids),
        "directly_covered_public_symbols": sorted(direct_covered),
        "missing_public_symbols": sorted(missing_public),
        "demos_without_flow": sorted(missing_flows),
        "flow_files_without_demo": sorted(extra_flows),
    }


def main(argv: list[str]) -> int:
    """Run the coverage check and print a human or JSON report."""
    public = _public_symbols()
    features = _read_registry_features()
    demo_ids = _read_registry_ids()
    flow_ids = _flow_files()

    report = _format_report(public, features, demo_ids, flow_ids)

    json_mode = "--json" in argv
    if json_mode:
        print(json.dumps(report, indent=2))
    else:
        print("E2E coverage report")
        print("===================")
        print(f"  Public symbols in pythonnative.__all__: {report['public_symbols']}")
        print(f"  Demo entries in registry:               {report['demos']}")
        print(f"  Flow files under tests/e2e/flows:       {report['flows']}")
        print(f"  Public symbols directly covered:        {len(report['directly_covered_public_symbols'])}")
        print(f"  Intentional exemptions:                 {len(INTENTIONAL_EXEMPTIONS)}")
        if report["missing_public_symbols"]:
            print()
            print("  ERROR: the following public symbols have no E2E demo:")
            for name in report["missing_public_symbols"]:
                print(f"    - {name}")
            print()
            print(
                "  Fix: add a DemoEntry to examples/e2e-suite/app/registry.py "
                'with feature="<name>", create the screen, and add a '
                "tests/e2e/flows/<category>/<id>.yaml file.\n"
                "  Alternatively, if the symbol genuinely can't be tested "
                "via a UI flow, add it to INTENTIONAL_EXEMPTIONS in this "
                "script with a justification comment."
            )
        if report["demos_without_flow"]:
            print()
            print("  ERROR: the following registered demos have no flow file:")
            for name in report["demos_without_flow"]:
                print(f"    - {name}")
        if report["flow_files_without_demo"]:
            print()
            print("  WARNING: the following flow files don't match any registered demo:")
            for name in report["flow_files_without_demo"]:
                print(f"    - {name}")

    failed = bool(report["missing_public_symbols"]) or bool(report["demos_without_flow"])
    return 1 if failed else 0


if __name__ == "__main__":
    sys.exit(main(sys.argv[1:]))