MoviePilot/tests/test_module_method_contracts.py

"""模块字符串方法契约清单的架构测试。"""

import json
from pathlib import Path

from app.runtime.extensions.module.contracts import (
    ModuleErrorPolicy,
    ModuleExecutionMode,
    ModuleResultAggregation,
    ModuleResultShape,
    diagnose_module_callable,
    diagnose_module_result,
    get_module_method_contract,
    is_explicit_module_method,
    list_explicit_module_contracts,
)


RUNTIME_BASELINE = (
    Path(__file__).parent / "fixtures" / "architecture" / "runtime-contract-baseline.json"
)


def test_all_scanned_host_module_methods_have_explicit_v2_contracts() -> None:
    """架构快照中的全部宿主字符串方法都必须显式登记 V2 契约。"""
    payload = json.loads(RUNTIME_BASELINE.read_text(encoding="utf-8"))
    methods = set(payload["run_module"]["methods"])
    contracts = list_explicit_module_contracts()

    assert methods
    assert methods <= contracts.keys()
    for method in methods:
        contract = contracts[method]
        assert isinstance(contract.aggregation, ModuleResultAggregation)
        assert contract.input_contract != "legacy_args"
        assert contract.result_contract != "Any"
        assert contract.plugin_short_circuit is True


def test_high_frequency_capability_families_are_explicit() -> None:
    """媒体发现、识别、存储和消息族不能退回未分类 legacy 契约。"""
    expected_families = {
        "async_tmdb_discover": "tmdb",
        "async_douban_discover": "douban",
        "bangumi_info": "bangumi",
        "anilist_info": "anilist",
        "recognize_media": "media-recognition",
        "mediaserver_items": "media-server",
        "list_files": "storage",
        "finalize_message": "messaging",
        "scheduler_job": "scheduling",
    }

    for method, family in expected_families.items():
        assert is_explicit_module_method(method)
        assert get_module_method_contract(method).family == family


def test_unknown_plugin_method_keeps_legacy_compatibility() -> None:
    """第三方插件自定义方法仍应落入开放的 legacy 调度协议。"""
    contract = get_module_method_contract("third_party_custom_method")

    assert contract.family == "legacy"
    assert contract.supports_sync is True
    assert contract.supports_async is True


def test_contract_v2_freezes_every_observed_host_method() -> None:
    """全部已观察宿主能力必须具备可生成文档和诊断的完整 V2 字段。"""
    contracts = list_explicit_module_contracts()

    assert len(contracts) >= 211
    for contract in contracts.values():
        assert contract.version == 1
        assert contract.input_contract != "legacy_args"
        assert contract.result_contract
        assert contract.execution is ModuleExecutionMode.SYNC_OR_ASYNC
        assert contract.timeout_policy == "caller_budget"
        assert contract.error_policy is ModuleErrorPolicy.ISOLATE_PROVIDER
        assert contract.public_to_plugins is True


def test_signature_diagnostics_do_not_reject_legacy_callable() -> None:
    """无法检查的旧插件 callable 只产生诊断，仍由 dispatcher 决定是否执行。"""
    class _OpaqueCallable:
        """模拟 inspect 无法解析签名的第三方 callable。"""

        @property
        def __signature__(self):
            """模拟扩展对象不提供 Python signature。"""
            raise ValueError("opaque")

        def __call__(self):
            """保留可调用行为。"""
            return "ok"

    assert diagnose_module_callable("recognize_media", _OpaqueCallable()) == (
        "signature-unavailable",
    )
    assert _OpaqueCallable()() == "ok"


def test_signature_diagnostics_report_missing_contract_parameters() -> None:
    """显式 Contract 应能指出 provider 遗漏的宿主调用参数。"""
    def incomplete_storage_provider(fileitem):
        """模拟仍未接受 recursion 参数的旧存储 provider。"""
        return [fileitem]

    assert diagnose_module_callable(
        "list_files", incomplete_storage_provider
    ) == ("missing-parameter:recursion",)


def test_signature_diagnostics_accept_keyword_compatibility_provider() -> None:
    """带 **kwargs 的第三方 provider 继续兼容逐步扩展的输入契约。"""
    def compatible_provider(**kwargs):
        """模拟通过关键字参数保持前向兼容的第三方 provider。"""
        return kwargs

    assert diagnose_module_callable("snapshot_storage", compatible_provider) == ()


def test_result_diagnostics_check_only_enabled_basic_shapes() -> None:
    """高频方法检查基础结果形状，业务对象合同仍留给逐族适配器。"""
    assert get_module_method_contract("list_files").result_shape is ModuleResultShape.LIST
    assert diagnose_module_result("list_files", [object()]) == ()
    assert diagnose_module_result("list_files", None) == ()
    assert diagnose_module_result("list_files", "legacy-value") == (
        "unexpected-result:list:str",
    )
    assert diagnose_module_result("mediaserver_play_url", "https://example.test") == ()
    assert diagnose_module_result("mediaserver_play_url", 7) == (
        "unexpected-result:string:int",
    )


def test_message_attachment_contracts_use_messaging_family() -> None:
    """消息附件下载能力不得因 download 前缀误归入下载器能力族。"""
    expected_parameters = {
        "download_telegram_file_bytes": ("file_id", "source"),
        "download_wechat_media_bytes": ("media_ref", "source"),
        "download_slack_file_to_data_url": ("file_url", "source"),
        "download_feishu_image_to_data_url": ("image_ref", "source"),
    }

    for method, parameters in expected_parameters.items():
        contract = get_module_method_contract(method)
        assert contract.family == "messaging"
        assert contract.aggregation is ModuleResultAggregation.FIRST_NON_EMPTY
        assert contract.required_parameters == parameters


def test_downloader_query_contracts_merge_provider_lists() -> None:
    """下载器查询能力应显式合并各 provider 的有序列表结果。"""
    for method in ("list_torrents", "downloader_info"):
        contract = get_module_method_contract(method)
        assert contract.family == "downloader"
        assert contract.aggregation is ModuleResultAggregation.ORDERED_LIST_MERGE
        assert contract.result_shape is ModuleResultShape.LIST


def test_media_server_contracts_distinguish_streams_lists_and_scalar_routes() -> None:
    """媒体服务器能力应按真实返回形状选择合并或目标路由语义。"""
    list_methods = {
        "media_statistic",
        "mediaserver_latest",
        "mediaserver_latest_images",
        "mediaserver_librarys",
        "mediaserver_playing",
    }
    scalar_methods = {
        "media_exists",
        "mediaserver_image_cookies",
        "mediaserver_items_count",
        "mediaserver_season_episode_ids",
    }

    for method in list_methods:
        contract = get_module_method_contract(method)
        assert contract.aggregation is ModuleResultAggregation.ORDERED_LIST_MERGE
        assert contract.result_shape is ModuleResultShape.LIST
    for method in scalar_methods:
        contract = get_module_method_contract(method)
        assert contract.aggregation is ModuleResultAggregation.FIRST_NON_EMPTY

    items = get_module_method_contract("mediaserver_items")
    assert items.result_contract == "Iterable[MediaServerItem] | None"
    assert items.aggregation is ModuleResultAggregation.FIRST_NON_EMPTY
    assert items.result_shape is ModuleResultShape.ANY


def test_storage_value_contracts_use_explicit_provider_semantics() -> None:
    """存储值查询和动作应停止 legacy 接力，仅文件清单合并 provider 结果。"""
    for method in ("any_files", "create_folder", "delete_file", "transfer"):
        contract = get_module_method_contract(method)
        assert contract.family == "storage"
        assert contract.aggregation is ModuleResultAggregation.FIRST_NON_EMPTY
        assert contract.required_parameters

    media_files = get_module_method_contract("media_files")
    assert media_files.aggregation is ModuleResultAggregation.ORDERED_LIST_MERGE
    assert media_files.result_shape is ModuleResultShape.LIST
    assert media_files.required_parameters == ("mediainfo",)


def test_lookup_contracts_separate_value_routes_from_list_aggregation() -> None:
    """分类、站点、元数据、认证与 TVDB 查询应声明真实的值或列表语义。"""
    list_methods = {"site_subtitle_links", "search_tvdb"}
    value_methods = {
        "media_category",
        "load_category_config",
        "save_category_config",
        "get_search_page_size",
        "refresh_userdata",
        "metadata_img",
        "metadata_nfo",
        "obtain_specific_image",
        "recommend_name",
        "user_authenticate",
        "tvdb_info",
        "tvdb_slug",
    }

    for method in list_methods:
        contract = get_module_method_contract(method)
        assert contract.aggregation is ModuleResultAggregation.ORDERED_LIST_MERGE
        assert contract.result_shape is ModuleResultShape.LIST
    for method in value_methods:
        contract = get_module_method_contract(method)
        assert contract.aggregation is ModuleResultAggregation.FIRST_NON_EMPTY
        assert contract.result_contract


def test_heterogeneous_torrent_files_result_remains_legacy_compatible() -> None:
    """下载器文件集合尚未归一前不得声明虚假的列表聚合语义。"""
    contract = get_module_method_contract("torrent_files")

    assert contract.required_parameters == ("tid", "downloader")
    assert contract.result_contract == "DownloaderFileCollection | None"
    assert contract.aggregation is ModuleResultAggregation.LEGACY
    assert contract.result_shape is ModuleResultShape.ANY


def test_torrent_tracker_contract_merges_downloader_mappings() -> None:
    """Tracker 查询应登记跨下载器有序映射合并，而不是首个字典短路。"""
    contract = get_module_method_contract("get_torrent_trackers")

    assert contract.required_parameters == ("hash_string", "downloader")
    assert contract.aggregation is ModuleResultAggregation.ORDERED_MAPPING_MERGE
    assert contract.result_shape is ModuleResultShape.MAPPING


def test_downloader_action_contracts_freeze_shared_provider_signatures() -> None:
    """三种宿主下载器的目标选择动作应使用一致的首个非空契约。"""
    expected_parameters = {
        "download": (
            "content",
            "download_dir",
            "cookie",
            "episodes",
            "category",
            "label",
            "downloader",
        ),
        "remove_torrents": ("hashs", "delete_file", "downloader"),
        "set_torrents_tag": ("hashs", "tags", "downloader"),
        "start_torrents": ("hashs", "downloader"),
        "stop_torrents": ("hashs", "downloader"),
        "update_torrent": (
            "hash_string",
            "downloader",
            "download_limit",
            "upload_limit",
            "tracker_list",
            "save_path",
            "category",
            "ratio_limit",
            "seeding_time_limit",
        ),
    }

    for method, parameters in expected_parameters.items():
        contract = get_module_method_contract(method)
        assert contract.family == "downloader"
        assert contract.aggregation is ModuleResultAggregation.FIRST_NON_EMPTY
        assert contract.required_parameters == parameters


def test_sync_and_async_media_capabilities_share_contracts() -> None:
    """同一识别能力的同步与异步入口必须复用完全相同的契约。"""
    for sync_method, async_method in (
        ("recognize_media", "async_recognize_media"),
        ("search_medias", "async_search_medias"),
        ("obtain_images", "async_obtain_images"),
    ):
        assert get_module_method_contract(sync_method) is get_module_method_contract(
            async_method
        )

    assert (
        get_module_method_contract("obtain_images").aggregation
        is ModuleResultAggregation.PIPELINE_RELAY
    )


def test_sync_and_async_discovery_lists_share_contracts() -> None:
    """媒体榜单与搜索的同步、异步入口必须共享有序列表契约。"""
    sync_methods = (
        "movie_hot",
        "movie_showing",
        "movie_top250",
        "search_collections",
        "search_persons",
        "search_subtitles",
        "search_torrents",
        "tv_animation",
        "tv_hot",
        "tv_weekly_chinese",
        "tv_weekly_global",
    )

    for sync_method in sync_methods:
        async_method = f"async_{sync_method}"
        contract = get_module_method_contract(sync_method)
        assert contract is get_module_method_contract(async_method)
        assert contract.aggregation is ModuleResultAggregation.ORDERED_LIST_MERGE
        assert contract.result_shape is ModuleResultShape.LIST
        assert contract.required_parameters


def test_attachment_result_diagnostics_distinguish_bytes_and_strings() -> None:
    """附件契约应区分二进制内容和可展示字符串，偏差仍仅供诊断。"""
    assert diagnose_module_result("download_qq_file_bytes", b"content") == ()
    assert diagnose_module_result("download_qq_file_bytes", "content") == (
        "unexpected-result:bytes:str",
    )
    assert diagnose_module_result(
        "download_wechat_image_to_data_url",
        "data:image/png;base64,AA==",
    ) == ()


def test_unknown_plugin_result_keeps_unchecked_legacy_compatibility() -> None:
    """未知第三方方法的任意返回值继续不做结果形状诊断。"""
    assert diagnose_module_result("third_party_custom_method", object()) == ()