psf / black · 架構

被分析的清單有 482 個檔案，集中在 tests（326 個檔案）、src（48）、docs（48）、.github（22）和 scripts（9），根目錄另有 19 個檔案。有四筆子系統記錄把 docs、scripts、src 和 tests 描述為可能代表子系統的頂層目錄。進入點和角色記錄裡的路徑顯示，src/ 包含 black 套件（包括 __init__.py、linegen.py、trans.py、comments.py、nodes.py）、blackd，以及帶有 pgen2 子套件（driver.py）的 blib2to3（pytree.py）。角色和進入點記錄也顯示了 tests/test_black.py 和 tests/util.py 這類測試程式碼，以及 tests/data/cases/ 底下的測試案例檔案。進入點摘錄顯示有兩支檢查文件的腳本，會開啟 CHANGES.md 以及 docs/integrations/ 和 docs/usage_and_configuration/ 底下的 markdown。

重建結果算到 18 個進入點和 176 條有界執行路徑。有十七筆進入點記錄回報了 Python __main__ 守衛（if __name__ == "__main__":）：scripts/ 裡八筆、src/ 裡五筆（black、blackd，以及三個 blib2to3.pgen2 模組），tests/ 裡四筆（tests/test_tokenize.py 加上 tests/data/cases/ 的檔案）。第十八筆記錄依檔名啟發式規則，把 action/main.py 標為可能可執行，一條教學陳述也稱它為偵測到的起點。列出的十條有界路徑全都從 action/main.py 開始，走一步就停在 os.getenv（七條）、re.compile（兩條）或 Path（一條），終止原因都是 'unresolved_boundary'，沒有偵測到循環，也沒有截斷。列出的路徑沒有一條到達 src/ 目錄樹。repository 摘要另外把 scripts/check_pre_commit_rev_in_example.py 稱為看起來的主要起點。

每一筆角色記錄都把證據基礎列為已解析的靜態呼叫次數和是否屬於進入點，所以這些角色是從呼叫計數推論的，不是在執行時觀察到的。角色記錄回報 tests/util.py 有 118 個呼入，tests/test_black.py 有 104 個呼入和 177 個呼出。在 src/ 裡，記錄回報 src/black/linegen.py 有 79 個呼入和 79 個呼出，src/black/trans.py 則呼入呼出各 66 個。分析器把 linegen.py、trans.py、comments.py、nodes.py 和 tests/test_black.py 標為 'service/core candidate'，而 src/black/__init__.py、src/blackd/__init__.py、tests/test_tokenize.py 和 scripts/diff_shades_gha_helper.py 則是 'entry/orchestration candidate'。在 blib2to3 裡，角色記錄顯示 src/blib2to3/pytree.py 有 13 個呼入，src/blib2to3/pgen2/driver.py 有 10 個呼入和 13 個呼出。

列出的每一條有界路徑都停在 action/main.py 裡，停在標為 external_or_unresolved 的 os.getenv、re.compile 或 Path 呼叫。關係計數顯示，在總共 9,339 條關係中，8,487 條是 external_or_unresolved，本地的只有 852 條。分析器不解析動態分派、動態 import、反射、monkey-patching、產生的程式碼或框架在執行期的接線，這也限制了任何靜態路徑能顯示的內容。檔案清單裡有兩個只含一個檔案的頂層目錄，名叫 plugin 和 autoload；列出的十條有界路徑沒有一條連到它們（依執行路徑記錄，十條都留在 action/main.py 裡），分析資料也沒有確立它們的載入機制。

依類型來看，分析資料在 9,339 條靜態關係中記錄了 8,219 條呼叫關係和 1,120 條 import。重建結果另外回報，在 482 個被分析的檔案中有 813 條已解析的靜態呼叫關係。至於清單檔層級的依賴：這次分析的依賴記錄只來自 requirements 形式的清單檔，pyproject.toml 的依賴表不會被解析。至於內部呼叫集中在哪裡，角色記錄指向 tests/util.py（118 個呼入）和 tests/test_black.py（177 個呼出、104 個呼入）。除了這些逐模組的次數之外，具體的跨模組依賴邊無法從這份分析資料逐一引用。

這份指南建立在靜態分析上，而分析器自己記錄了它無法解析反射、執行期依賴注入、動態 import、monkey-patching、產生的程式碼、框架在執行期的接線和動態分派。安裝、執行與建置的推論並不完整，安裝指令也沒有驗證。README 陳述的擷取是逐行進行的，可能抓到程式碼行而不是說明文字，所以來自 README 的陳述最多只算 author_claimed。manifest 的能力欄位描述的是分析器，不是這個 repository，所以不算在 repository 的證據裡。最後，檔案清單算到 326 個類測試檔案，但這些測試套件執行時的表現，這裡無法確定。

從分析器歸為專案層級重要檔案的 README.md、pyproject.toml 和 LICENSE 開始。接著打開 action/main.py：修改建議推薦從這個偵測到的進入點開始，並手動確認下游的影響。核心部分，讀 src/black/__init__.py：它的 __main__ 守衛呼叫 patched_main，角色記錄是 'entry/orchestration candidate'。然後讀 src/black/linegen.py 和 src/black/trans.py，它們是這裡引用的 src/ 角色記錄中連結次數最高的，並用 tests/test_black.py 當作行為範例。把 8,487 條未解析的關係和未解析的動態機制，當作這張地圖的邊界。