"""gapfill2 H4：G5 调用方契约的文档钉死（只改文档、不改行为）。

本文件断言的全部是 docstring 文本，不是行为：上一批残留
“可信 main 头的来源仍是调用方责任”在本批补进 scorecard
相关模块与端点的 docstring 后，必须写清四点——
current_main_head 由调用方提供、接受什么形式的值、缺失与
空串按未传入处理且不做 stale 判定、传入后永远 200 且不改写
overall；且绝不新增任何校验或拒绝行为（行为断言见既有
test_gapfill_g5_baseline_snapshot，本文件不重复测行为）。
"""

import sys
import unittest
from pathlib import Path

REPO_ROOT = Path(__file__).resolve().parents[2]
sys.path.insert(0, str(REPO_ROOT))

import cloud.audit_scorecard as scorecard_mod  # noqa: E402
import cloud.scorecard_baseline_store as store_mod  # noqa: E402
from cloud.server import CloudControlPlaneHandler  # noqa: E402


def _flat(doc):
    """docstring 空白归一化：去掉全部空白后按语义短语查，
    不依赖换行位置（中文短语常被换行切开）。"""
    return "".join((doc or "").split())


class CallerContractDocsTestCase(unittest.TestCase):
    def test_endpoint_docstring_states_caller_contract(self):
        doc = _flat(CloudControlPlaneHandler._audit_scorecard.__doc__)
        self.assertIn("由调用方提供", doc)
        self.assertIn("接受任意字符串", doc)
        self.assertIn("不做任何格式校验", doc)
        self.assertIn("不要求形如commithash", doc)
        self.assertIn("缺失", doc)
        self.assertIn("空串一律按未传入处理", doc)
        self.assertIn("不附加baseline_staleness字段", doc)
        self.assertIn("永远返回200", doc)
        self.assertIn("绝不改写报告的overall/overall_pass", doc)
        self.assertIn("可信main头的来源仍是调用方责任", doc)

    def test_check_baseline_stale_docstring_states_contract(self):
        doc = _flat(scorecard_mod.check_baseline_stale.__doc__)
        self.assertIn("接受任意字符串", doc)
        self.assertIn("不做任何格式校验", doc)
        self.assertIn("空串先归一化为None", doc)
        self.assertIn("根本不调用本函数", doc)
        self.assertIn("可信", doc)

    def test_module_and_store_docstrings_state_contract(self):
        self.assertIn("接受任意字符串",
                      _flat(scorecard_mod.__doc__))
        self.assertIn("不做格式校验", _flat(store_mod.__doc__))
        self.assertIn("可信来源仍是调用方责任",
                      _flat(store_mod.__doc__))


if __name__ == "__main__":
    unittest.main()