evision

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""Parse OpenCV's ``platforms/js/opencv_js.config.py`` whitelist.

Used by the evision codegen to learn which generated bindings have an
opencv.js counterpart so a persistent ``@js`` module attribute can be
emitted per matching function. See
``projects/evision/context/js-correspondence-tag.md`` in the
``cocoa/ai-native`` notebook for the full design.

The config file is plain Python: each OpenCV module (``core``, ``imgproc``,
``dnn``, ...) is a ``dict[classname_or_'', list[fn_name]]`` later merged
into a single flat ``white_list`` via ``makeWhiteList``. The merge loses
the per-module bucketing, so this parser executes the file with a stub
``makeWhiteList`` and walks the resulting namespace itself to keep
``module_name`` on every entry.

embindgen treats the ``cv::dnn`` and ``cv::aruco`` namespaces as
prefix-stripped when the whitelist is a ``.py`` file
(``embindgen.py:1066-1069``). The same defaults are applied here so
consumers see the JS-side function name as opencv.js would expose it.
"""

from __future__ import annotations

import os
from pathlib import Path
from typing import Dict, Iterator, List, Optional, Set, Tuple


# Hardcoded in embindgen.py for the ``.py`` whitelist mode.
DEFAULT_NAMESPACE_PREFIX_OVERRIDE: Dict[str, str] = {
    "dnn": "",
    "aruco": "",
}

ModuleWhitelist = Dict[str, List[str]]
ParsedWhitelist = Dict[str, ModuleWhitelist]
Entry = Tuple[str, Optional[str], str, str]


class ConfigNotFoundError(FileNotFoundError):
    """Raised when no opencv_js.config.py can be located."""


def discover_config_path(
    repo_root: Optional[os.PathLike] = None,
    opencv_ver: Optional[str] = None,
) -> Path:
    """Locate ``opencv_js.config.py`` for the active OpenCV checkout.

    Resolution order:

    1. ``OPENCV_VER`` arg, then ``$OPENCV_VER`` env var, then any single
       ``3rd_party/opencv/opencv-*`` directory present on disk.
    2. ``repo_root`` arg, then ``$EVISION_REPO_ROOT`` env var, then the
       repo root inferred from this file's location.

    Raises ``ConfigNotFoundError`` if neither yields a readable file.
    """
    root = Path(repo_root) if repo_root else _default_repo_root()
    ver = opencv_ver or os.environ.get("OPENCV_VER")

    if ver:
        candidate = root / "3rd_party" / "opencv" / f"opencv-{ver}" / "platforms" / "js" / "opencv_js.config.py"
        if candidate.is_file():
            return candidate
        raise ConfigNotFoundError(
            f"opencv_js.config.py not found for OPENCV_VER={ver} at {candidate}"
        )

    opencv_root = root / "3rd_party" / "opencv"
    if not opencv_root.is_dir():
        raise ConfigNotFoundError(
            f"OpenCV root {opencv_root} does not exist; pass repo_root or run `make download_opencv` first"
        )

    candidates = sorted(
        p for p in opencv_root.glob("opencv-*")
        if p.is_dir() and not p.name.startswith("opencv_contrib")
    )
    if not candidates:
        raise ConfigNotFoundError(
            f"No opencv-* checkout under {opencv_root}; set OPENCV_VER or run `make download_opencv`"
        )

    config = candidates[-1] / "platforms" / "js" / "opencv_js.config.py"
    if not config.is_file():
        raise ConfigNotFoundError(
            f"Found {candidates[-1]} but its platforms/js/opencv_js.config.py is missing"
        )
    return config


def load_modules(config_path: Optional[os.PathLike] = None) -> ParsedWhitelist:
    """Execute the config file and return its per-module whitelist dicts.

    Keys are the module variable names from the file (``core``,
    ``imgproc``, ``dnn``, ...); values are the original
    ``{classname_or_'': [fn_name, ...]}`` dicts.

    Raises ``ConfigNotFoundError`` (a subclass of ``FileNotFoundError``)
    when the path does not resolve to an existing file.
    """
    path = Path(config_path) if config_path else discover_config_path()
    if not path.is_file():
        raise ConfigNotFoundError(f"opencv_js.config.py not found at {path}")

    namespace: Dict[str, object] = {
        "makeWhiteList": _stub_make_whitelist,
        "__file__": str(path),
    }
    source = path.read_text()
    exec(compile(source, str(path), "exec"), namespace)

    modules: ParsedWhitelist = {}
    for name, value in namespace.items():
        if name.startswith("_") or name in _RESERVED_NAMES:
            continue
        if not isinstance(value, dict):
            continue
        if not all(
            isinstance(k, str) and isinstance(v, list) and all(isinstance(item, str) for item in v)
            for k, v in value.items()
        ):
            continue
        modules[name] = {k: list(v) for k, v in value.items()}
    return modules


def namespace_prefix_override(
    config_path: Optional[os.PathLike] = None,
) -> Dict[str, str]:
    """Return the effective ``namespace_prefix_override`` mapping.

    Starts from the embindgen-side ``.py`` defaults
    (``{'dnn': '', 'aruco': ''}``) and merges any value assigned to
    ``namespace_prefix_override`` inside the config file itself.
    """
    path = Path(config_path) if config_path else discover_config_path()
    if not path.is_file():
        raise ConfigNotFoundError(f"opencv_js.config.py not found at {path}")

    namespace: Dict[str, object] = {
        "makeWhiteList": _stub_make_whitelist,
        "__file__": str(path),
    }
    exec(compile(path.read_text(), str(path), "exec"), namespace)

    overrides = dict(DEFAULT_NAMESPACE_PREFIX_OVERRIDE)
    extra = namespace.get("namespace_prefix_override")
    if isinstance(extra, dict):
        for k, v in extra.items():
            if isinstance(k, str) and isinstance(v, str):
                overrides[k] = v
    return overrides


def flat_set(
    config_path: Optional[os.PathLike] = None,
    modules: Optional[ParsedWhitelist] = None,
) -> Set[Tuple[str, Optional[str], str]]:
    """Return ``{(module, classname_or_None, fn_name)}`` for fast lookup.

    Pass an already-loaded ``modules`` dict to avoid re-executing the
    config file; otherwise the file at ``config_path`` (or the discovered
    default) is loaded.
    """
    if modules is None:
        modules = load_modules(config_path)
    out: Set[Tuple[str, Optional[str], str]] = set()
    for module_name, module_dict in modules.items():
        for class_key, fn_names in module_dict.items():
            classname = class_key or None
            for fn_name in fn_names:
                out.add((module_name, classname, fn_name))
    return out


def entries(
    config_path: Optional[os.PathLike] = None,
    modules: Optional[ParsedWhitelist] = None,
) -> Iterator[Entry]:
    """Yield ``(module, classname_or_None, fn_name, js_kind)`` for the emitter.

    ``js_kind`` is one of ``'function'``, ``'method'``, ``'constructor'``.
    A class entry is treated as the constructor when its function name
    equals the bare class name (the segment after the last ``_`` in the
    class key) — this matches OpenCV's convention where
    e.g. ``'aruco_Dictionary': ['Dictionary', ...]`` lists ``Dictionary``
    as the constructor.
    """
    if modules is None:
        modules = load_modules(config_path)
    for module_name in sorted(modules):
        module_dict = modules[module_name]
        for class_key in sorted(module_dict):
            fn_names = module_dict[class_key]
            classname = class_key or None
            bare = class_key.rsplit("_", 1)[-1] if class_key else None
            for fn_name in fn_names:
                if classname is None:
                    kind = "function"
                elif fn_name == bare:
                    kind = "constructor"
                else:
                    kind = "method"
                yield (module_name, classname, fn_name, kind)


def _stub_make_whitelist(module_list):
    merged: ModuleWhitelist = {}
    for module in module_list:
        for k, v in module.items():
            merged.setdefault(k, []).extend(v)
    return merged


def _default_repo_root() -> Path:
    env = os.environ.get("EVISION_REPO_ROOT")
    if env:
        return Path(env)
    return Path(__file__).resolve().parent.parent


_RESERVED_NAMES = frozenset({
    "makeWhiteList",
    "white_list",
    "namespace_prefix_override",
})