tests/test_one_definition.py
Rama main · réplica de lectura del repositorio original.
"""一件事只能有一個定義。
這裡的每一條規則都對應一次真的發生過的故障，不是風格意見：
路徑 2026-07-28 資料目錄搬家，兩半管線各自推導位置，卡片全被吃掉。
xkb_paths 是為了這件事寫的，但十五支腳本 import 了它之後，
又用 WORKSPACE / "memory" / ... 自己拼一次，共二十八處。
數量 「有幾張卡片」有兩個答案，1,538 和 1,539：一支用 rglob，
把治理判定重複而移走的卡片也算了進去。
出處 self-derived 的判斷曾經有三個寫法，於是 913 條自產知識繞過了
回音室降權。
斷詞 「這段文字的詞是哪些」有過八份實作。那個正則對中文是壞的：
整串中文被吃成一個 token，於是中文問句幾乎命中不了任何東西，
看起來像知識庫沒內容。xkb_text 修好了它，但四支腳本仍各留一份。
門檻 餘弦門檻曾經有三個數字、兩個預設值共用同一個環境變數
（XKB_CARD_MIN_SIMILARITY 同時被 0.55 和 0.58 兩處讀走）。
舊的防護存在，但白名單只列了兩支腳本，第三支自動繞過。
尺度 score_scale 是散在各處的字串字面量。打錯一個字不會報錯，
會靜默掉到 0.5 的 fallback，整層排序錯位。
編碼 「檔案是什麼編碼」曾經有兩個答案：程式沒說，於是 Linux 上是
UTF-8、Windows 上是 cp950。同一份卡片在 VPS 讀得到、在本機
炸掉，而本機是 Pan 每次改動的第一站。
一個新的定義出現時，這裡會失敗，而不是等它在某個早上說出錯的數字。
"""
from __future__ import annotations
import ast
import re
import sys
import unittest
from pathlib import Path
ROOT = Path(__file__).resolve().parents[1]
SCRIPTS = ROOT / "scripts"
sys.path.insert(0, str(SCRIPTS))
import xkb_score # noqa: E402
SHARED_PATHS = (
"CARDS_DIR", "BOOKMARKS_DIR", "WIKI_DIR", "WIKI_TOPICS_DIR",
"INDEX_FILE", "VECTOR_FILE", "TOPIC_PROFILE_FILE", "DATA_DIR",
)
ASSIGNMENT = re.compile(r"^(%s)\s*=\s*(.+)$" % "|".join(SHARED_PATHS), re.M)
def _sources() -> list[Path]:
return [p for p in sorted(SCRIPTS.glob("*.py")) if p.name != "xkb_paths.py"]
class OneDefinitionTest(unittest.TestCase):
def test_shared_paths_come_from_xkb_paths(self) -> None:
"""別名可以，重新推導不行。
`CARDS_DIR = xkb_paths.CARDS_DIR` 只是本地名字；
`CARDS_DIR = WORKSPACE / "memory" / "cards"` 是第二個定義，
而且它不會跟著 .xkb.json 或 XKB_DATA_DIR 走。
"""
offenders = []
for path in _sources():
lines = path.read_text(encoding="utf-8").splitlines()
for i, line in enumerate(lines):
match = ASSIGNMENT.match(line)
if not match:
continue
rhs, j = match.group(2), i + 1
while rhs.count("(") > rhs.count(")") and j < len(lines):
rhs += " " + lines[j].strip()
j += 1
if "xkb_paths" not in rhs:
offenders.append(f"{path.name}:{i + 1} {match.group(1)} = {rhs[:60]}")
self.assertEqual(offenders, [], "這些路徑沒有取自 xkb_paths，資料目錄一搬就會指到舊位置")
def test_cards_are_counted_in_one_place(self) -> None:
"""卡片是哪些檔案，只有 xkb_paths.card_files 說了算。
cards/_deduped_redundant/ 裡是治理判定重複而移走的卡片。用 rglob
會把它們算回來，用 glob 不會，於是同一個問題有兩個答案。
"""
offenders = [
f"{path.name}:{i + 1}"
for path in _sources()
for i, line in enumerate(path.read_text(encoding="utf-8").splitlines())
if re.search(r"\bCARDS_DIR\b.*\.r?glob\(", line)
]
self.assertEqual(offenders, [], "改用 xkb_paths.card_files() / card_ids()")
def test_provenance_has_one_reader(self) -> None:
"""判斷「這是不是自己產的」只有 xkb_provenance 一份規則。
健檢曾經自己寫一套，於是把 322 條正確標記的知識報成壞的。
"""
offenders = []
for path in _sources():
text = path.read_text(encoding="utf-8")
if path.name == "xkb_provenance.py":
continue
if re.search(r'["\']self-derived["\']|self-derived\|', text) \
and "xkb_provenance" not in text and "is_self_derived" not in text:
offenders.append(path.name)
self.assertEqual(offenders, [], "self-derived 的判斷要走 xkb_provenance")
def test_tokenising_goes_through_xkb_text(self) -> None:
"""切詞的規則只有 xkb_text 一份。
判準是「有沒有自己拿一條含 CJK 範圍的正則去掃文字」——re.sub 做
slug、re.search 判斷有沒有中文都不算，那些不是在決定「詞是哪些」。
"""
tokenising = re.compile(r"\b(findall|finditer|re\.compile|re\.split)\b")
# 原始碼兩種寫法都算：跳脫的 \u4e00-\u9fff，和直接寫的字元範圍。
cjk_range = re.compile(r"(?:\\u4e00|一)\s*-")
offenders = []
for path in _sources():
if path.name == "xkb_text.py":
continue
for i, line in enumerate(path.read_text(encoding="utf-8").splitlines()):
if line.lstrip().startswith("#"):
continue
if tokenising.search(line) and cjk_range.search(line):
offenders.append(f"{path.name}:{i + 1}")
self.assertEqual(offenders, [], "自己寫斷詞正則；改用 xkb_text.tokenize()")
def test_similarity_thresholds_come_from_xkb_relevance(self) -> None:
"""餘弦門檻只有 xkb_relevance 說了算。
別名可以（`CARD_MIN_SIMILARITY = xkb_relevance.threshold("card_recall")`），
自己算一個不行。這條規則刻意掃全部腳本：上一版的防護寫死了兩支
呼叫端的白名單，於是第三支寫自己的門檻時沒有任何東西發現。
recall_router 的 MIN_SCORE_HARD / SOFT 不在這裡，因為它們不是餘弦：
那是 xkb_score.rank() 之後的合併分數，另一套尺度、另一個量。
"""
assignment = re.compile(r"^([A-Z_]*(?:MIN_SIMILARITY|MIN_RELEVANCE)[A-Z_]*)\s*=\s*(.+)$", re.M)
offenders = []
for path in _sources():
if path.name == "xkb_relevance.py":
continue
for i, line in enumerate(path.read_text(encoding="utf-8").splitlines()):
match = assignment.match(line)
if match and "xkb_relevance" not in match.group(2):
offenders.append(f"{path.name}:{i + 1} {match.group(1)}")
self.assertEqual(
offenders, [],
"這些門檻沒有取自 xkb_relevance；改用 threshold() 並把值寫進 DEFAULT_THRESHOLDS",
)
def test_every_score_scale_is_in_the_anchor_table(self) -> None:
"""宣告出來的尺度，跨層排序時必須認得。
xkb_score.rank() 對不認得的鍵會靜默退回 0.5，那一層的排序整段錯位，
而且不會有任何錯誤訊息——只會是一個看起來排好、實際上翻轉了的順序。
"""
literal = re.compile(r"""["\']score_scale["\']\]?\s*[:=]\s*["\']([a-z_]+)["\']""")
known = set(xkb_score.DEFAULT_ANCHORS)
offenders = []
for path in _sources():
for i, line in enumerate(path.read_text(encoding="utf-8").splitlines()):
for name in literal.findall(line):
if name not in known:
offenders.append(f"{path.name}:{i + 1} score_scale={name!r}")
self.assertEqual(offenders, [], "不在 xkb_score.DEFAULT_ANCHORS 裡的尺度 = 靜默錯位")
def test_file_io_says_which_encoding(self) -> None:
"""讀寫檔案一律講明 utf-8，不要讓作業系統替我們決定。
不指定時 Python 用平台預設：VPS 是 UTF-8，Windows 是 cp950。
知識庫裡幾乎每個檔案都有中文，於是同一支腳本在 VPS 正常、在本機
丟 UnicodeDecodeError——而本機是每次改動的第一站。
這條連 tests/ 一起掃：抓到的第一個違規就在測試自己身上。
"""
offenders = []
for path in sorted(list(SCRIPTS.glob("*.py")) + list((ROOT / "tests").glob("*.py"))):
try:
tree = ast.parse(path.read_text(encoding="utf-8"))
except SyntaxError:
continue
for node in ast.walk(tree):
if not isinstance(node, ast.Call):
continue
fn = node.func
if not (isinstance(fn, ast.Attribute) and fn.attr in ("read_text", "write_text")):
continue
if any(kw.arg == "encoding" or kw.arg is None for kw in node.keywords):
continue
offenders.append(f"{path.name}:{node.lineno} .{fn.attr}()")
self.assertEqual(offenders, [], "加上 encoding=\"utf-8\"；平台預設編碼不是一個定義")
if __name__ == "__main__":
unittest.main()