test: api §7 与异常树错误码一致性门禁测试（防文档漂移）

tests/test_api_design_consistency.py

@@ -0,0 +1,83 @@
+"""错误码一致性门禁：api-design §7 ↔ 异常树 error_code 的机器契约。
+
+变更错误码必须两处同步修改：api-design.md §7 错误码表
+与 src/genesis/inference/exceptions.py 的 error_code 类属性。
+本测试防文档漂移：文档多/少/错一行都会变红，且失败信息给出差异清单。
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from genesis.inference.exceptions import LLMError
+
+# 项目根定位（与 tests/test_real_samples.py:7 同款先例；不依赖 CWD）
+API_DOC = Path(__file__).resolve().parents[1] / "docs/api-design.md"
+
+# §7 表格 LLM 行：| `CODE` | 语义 | ... | exceptions.Xxx |
+_LLM_ROW_RE = re.compile(
+    r"^\|\s*`([A-Z][A-Z_]+)`\s*\|.*\|\s*exceptions\.([A-Za-z_]+)\s*\|$"
+)
+
+
+def _extract_llm_error_rows(document: str) -> dict[str, str]:
+    """解析 §7 表格中来源列以 exceptions. 开头的行，返回 {错误码: 来源类名}。
+
+    非 LLM 行（来源列为 "—"）被天然排除。
+    """
+    mapping: dict[str, str] = {}
+    for line in document.splitlines():
+        m = _LLM_ROW_RE.match(line.strip())
+        if m:
+            mapping[m.group(1)] = m.group(2)
+    return mapping
+
+
+def _llm_exception_classes() -> list[type[LLMError]]:
+    """error_code 非 None 的全部 LLM 异常子类（不硬编码清单，新增异常自动纳入）。"""
+    return sorted(
+        (cls for cls in LLMError.__subclasses__() if cls.error_code is not None),
+        key=lambda cls: cls.__name__,
+    )
+
+
+def test_error_doc_lists_every_llm_error_code():
+    # 异常树 → 文档：每个子类 error_code 必须登记在 §7，且来源类名匹配
+    mapping = _extract_llm_error_rows(API_DOC.read_text(encoding="utf-8"))
+    missing = {
+        cls.__name__: cls.error_code
+        for cls in _llm_exception_classes()
+        if cls.error_code not in mapping or mapping[cls.error_code] != cls.__name__
+    }
+    assert not missing, (
+        "异常类表存在文档未登记的 error_code（请同步 api-design.md §7）：\n"
+        + repr(missing)
+    )
+
+
+def test_error_doc_llm_rows_resolve_to_exception():
+    # 文档 → 异常树：每个 LLM 行都要能解析到同码同名的异常类
+    mapping = _extract_llm_error_rows(API_DOC.read_text(encoding="utf-8"))
+    by_code = {cls.error_code: cls.__name__ for cls in _llm_exception_classes()}
+    unresolved = {code: name for code, name in mapping.items() if by_code.get(code) != name}
+    assert not unresolved, (
+        "§7 LLM 行解析不到对应异常类（请核对来源列或错误码名）：\n"
+        + repr(unresolved)
+    )
+
+
+def test_error_doc_stable_llm_row_count():
+    # 格式护栏：LLM 行数 === 4（与 _llm_exception_classes 子类数一致，现为 4）
+    # 新增/删除 LLM 错误码需显式更新此数
+    mapping = _extract_llm_error_rows(API_DOC.read_text(encoding="utf-8"))
+    assert len(mapping) == 4, (
+        f"api §7 LLM 错误码行数应为 4，实际 {len(mapping)}；"
+        "新增/删除错误码须同步更新此计数。"
+    )
+
+
+def test_error_doc_parse_guard_prevents_silent_noop():
+    # 格式护栏：解析结果为空须硬失败（表格格式变更会静默失效，这里立即暴露）
+    mapping = _extract_llm_error_rows(API_DOC.read_text(encoding="utf-8"))
+    assert mapping, "api §7 表格解析结果为空：若无匹配行，请检查表格格式与 _LLM_ROW_RE 是否一致。"