主線 pipeline：detect → extract → build → cluster

這是整個管線的「分類開關」。它依序檢查、先比對特殊情況、再比對副檔名：

• 套件 manifest 優先：pyproject.toml、go.mod、pom.xml 等被導向 CODE（用確定性的 manifest 解析，而不是丟給 LLM）——否則一個 apm.yml 會被當成「文件」送 LLM，把套件拆成重複節點。
• 複合副檔名先查：.blade.php 要在查 .php 之前判斷。
• 接著依序查 CODE_EXTENSIONS、PAPER_EXTENSIONS（PDF 在 Xcode asset catalog 裡是向量圖示，要排除）、IMAGE_EXTENSIONS、DOC_EXTENSIONS（再檢查是否長得像論文）、office、Google Workspace、video。
• 無副檔名時退回 _shebang_file_type()（#!/usr/bin/env bash 的 CLI 也是程式碼）。

這就是「程式碼零 LLM、文件要 LLM」的源頭——類型決定後，走哪條抽取路徑就定了。

detect() 是管線的第一站，也承擔最多「別掃到不該掃的」責任：

1. 前置：解析 root、處理已移除的 .graphifyinclude（印警告）、讀取 .graphifyignore 合併 .gitignore 規則。
2. 走訪：os.walk(followlinks=…, onerror=…) 遞迴掃描。onerror 確保中途的 PermissionError 不會變成「靜默地少掃一個資料夾」。
3. 逐目錄修剪：遇到 noise 目錄（node_modules、.next 等）、被 ignore 規則排除的目錄，直接 dirnames[:] = kept_dirs 就地修剪，os.walk 就不會往下走。
4. 逐檔過濾：跳過 _SKIP_FILES、自己輸出的 converted/ sidecar、symlink 逃出掃描根目錄的、敏感檔。
5. 特別處理：Google Workspace shortcut 與 Office 檔轉成 Markdown sidecar；每個非影片檔統計字數（有 stat 快取）。
6. 回報：回傳 {files, total_files, total_words, needs_graph, warning, skipped_sensitive, unclassified, ignored, …}——所有「被排除的」都有記錄，不會默默消失。

注意回傳結構：needs_graph 與 warning 會告訴上層「語料太小，可能不需要圖」或「語料太大，語意抽取會很貴」。

三個段落式講解的過濾器：

• _is_noise_dir(part, parent) — 判斷目錄名是不是框架快取/產物（.next、.nuxt、node_modules…）。注意：dot 目錄（.github、.claude）是允許的，使用者常常想把它們畫進圖。
• _is_sensitive(path) — 環境變數檔（.env 等）與金鑰相關檔案不進圖，避免把密鑰抽成節點。
• _is_ignored(path, root, patterns, _cache=…) — 核心 ignore 引擎，支援 gitignore 語法（! 否定、anchored patterns、.gitignore 合併、last-match-wins）。_cache 在整個掃描過程共享，避免每個檔重算。

這是程式碼抽取的入口。docstring 講得很清楚，兩遍：

1. Phase 1 — 逐檔結構抽取：每個程式碼檔用 tree-sitter 解析，抽出類別、函數、import。
2. Phase 2 — 跨檔解析：把「檔案級 import」變成「類別級 INFERRED 邊」——例如 DigestAuth --uses--> Response。

實作上最關鍵的是「快取與平行化」：

• 先依 _get_extractor(path) 找出每個檔的抽取器；沒有抽取器的檔直接給空結果。
• 非 bypass 快取的檔先查 SHA256 內容快取（load_cached），命中就直接用。
• 剩下的 uncached_work 若超過平行門檻（_PARALLEL_THRESHOLD）就用 ProcessPoolExecutor 平行抽取（_extract_parallel，繞過 GIL）；池中途壞掉時，_extract_sequential 只重抽沒完成的（issue #2444）。
• 抽取結果後段有一大串「醒目標記」：零節點檔（#1666）、無抽取器但歸類為 code 的副檔名（#1689）、缺相依套件的副檔名（#1745）——每一種都印出清楚警告，並附上解決提示（例如 pip install "graphifyy[sql]"）。

dispatch 邏輯的「動腦」所在：

• 檔名優先：.blade.php、MCP config、套件 manifest 都先於泛型副檔名比對。
• 歧義副檔名特判：.h 可能是 C/C++/ObjC——用內容 sniff（_is_objc_header、_is_cpp_header）決定；.m 可能是 Objective-C 或 MATLAB——只有真的像 ObjC 才走 extract_objc，否則寧可沒抽取器（會被警告）也不硬解析。
• 無副檔名：靠 shebang 判斷直譯器（#!/usr/bin/env bash → extract_bash）。
• 最後才查 _DISPATCH 表。

語言的抽取函數其實都很薄——真正的邏輯在 _extract_generic(path, config)（來自 extractors/engine.py，見 extractors 頁）與一顆 LanguageConfig：

def extract_python(path: Path) -> dict:
    result = _extract_generic(path, _PYTHON_CONFIG)   # 通用 tree-sitter 走訪
    if "error" not in result:
        _extract_python_rationale(path, result)       # 補 docstring / # NOTE 節點
    return result

這說明了 0.3.0 那次「2527 → 1588 行」重構的成果：12 份複製貼上的語言抽取器收斂成「設定 + 通用引擎」。

節點 ID 是 graphify 最容易踩雷的地方。規範：{parent_dir}_{stem}——只取一層父目錄、去掉副檔名。頂層檔收斂成裸 stem（setup.py → setup）。

docstring 強調 這必須跟語意子代理產生的 ID 一致，否則 AST 與 semantic 抽取會把同一檔案拆成兩個不相連的「ghost 節點」。

段落式說明：

• _import_python / _import_js / _import_java … — 每種語言的 import 語句怎麼變成邊。簽名幾乎一致：(node, source, file_nid, stem, edges, str_path, scope_stack)。
• _extract_python_rationale — 把 docstring 與 # NOTE: / # WHY: 註解抽成「rationale 節點」並連回它們說明的程式碼——這是 GRAPH_REPORT 裡「the why」的來源。
• _shorten_rationale_label — 過長註解截斷成 80 字元。
• _is_autogenerated_python — 偵測自動產生的 Python（避免把產物當原始碼抽）。

這是「進料 → 一張圖」的合併點：

1. 把每份 extraction 的 nodes、edges、hyperedges、token 統計全部併進一個 combined dict。
2. 預設 dedup=True：先做型別強制（_coerce_non_string_ids）與欄位別名整併（_fold_node_aliases），再呼叫 deduplicate_entities()（見 ops · dedup），處理同實體不同 label 的問題。
3. 最後交給 build_from_json() 真正組圖。

一個很有趣的「活化石」：docstring 很誠實地承認——這個函數沒有接進 build()。真正在用的是 deduplicate_entities()（dedup.py）。它只依 label 合併、沒有 file_type 保護，所以不能給 code 節點用（兩個不同檔案的 Account 型別會被錯誤併成一個）。

它是「label-only 去重」的對照組：合併時偏好無 chunk 後綴（_c\d+）的短 ID，並丟掉合併造成的自環。

教學價值：一份開源專案保留「被取代的舊實作」並用 docstring 說明為什麼不用，勝過直接刪掉——這份歷史讓新讀者理解去重演進。

這是最髒也最重要的組圖函數（741–1264 約 500 行），它處理一大堆邊角：

• ID 正規化：非字串 ID 轉字串、legacy ID 遷移（_semantic_id_remap）、doc/ AST twin 重映射。
• 檔名消歧：不同目錄同名檔案標籤加上最短唯一後綴（_disambiguate_file_node_labels）。
• 超邊：G.graph["hyperedges"] 的寫入與正規化。
• 防護：shrink guard（不讓更小的圖覆蓋）、錯誤標記、prune。

實際看 graph 屬性時，節點會帶 _community、_source_file、_degree 等前綴屬性——那是在 export 前由 cluster/analyze 加上去的。

這是 增量更新設計 的實作點。與 build()（從零合併）不同，build_merge() 讀取既有的 graph.json，把這次的 new_chunks 併進去，並用 prune_sources 把已刪除檔案產生的節點剪掉。它處理跨檔邊的存活（changed file 指到 unchanged target 的邊要保留）、shrink guard、與 manifest 的一致性。

「最佳品質優先、退化優雅」的代表作：

• 先把節點/邊排序後重組成 stable 圖——讓分群輸入確定性（同樣的圖一定同樣的輸入順序）。
• 試 from graspologic.partition import leiden，透過 inspect.signature 動態傳 random_seed=42、trials=1、resolution（相容不同版本的 graspologic）。
• 呼叫期間把 stdout/stderr 導到 devnull——graspologic 會印 ANSI 進度條，在 Windows PowerShell 5.1 會毀掉 scroll buffer（issue #19，一個很實用的雷）。
• ImportError 就退回 networkx 的 Louvain，同樣用 inspect.signature 相容版本差異（max_level 只傳給支援的版本）。

這是 cluster.py 的主角，把「分群」這件事補齊到實用：

1. 空圖/無邊：0 節點回空；無邊時每個節點自成一群。
2. 有向轉無向：Leiden/Louvain 需要無向輸入。
3. hub 排除（exclude_hubs_percentile）：度數超過百分位的「超集線器」不參與分群（避免把無關子系統拉進同群），之後依鄰居社群多數決重新掛回。
4. isolate：0 度的節點各自成單節點社群。
5. 過大社群拆分：> 25% 節點（至少 10 個）的社群，在子圖上再跑一次 _partition 拆開。
6. 凝聚力再拆分：doc-hub 節點（如 CLAUDE.md 連到所有東西）會製造低凝聚力社群——凝聚力 < 0.05 且 ≥ 50 節點的再拆一次。
7. ID 穩定化：社群依大小降序重新編號，同大小用 tuple(sorted(nodes)) 當總序 tiebreak——否則每次跑，那些等大小的社群 ID 會亂跳，造成偽「社群 churn」（issue #1090）。

社群名稱的「零成本」方案：直接用最高度數成員的 label（去掉尾綴 ()）。所以報告讀起來是 auth / log_action 而不是 Community 70。平手時用節點 ID 保證跨跑穩定。當有設定 LLM 時，這個預設命名會被更豐富的 LLM 命名覆蓋。

段落式說明：

• cohesion_score(G, nodes) — 實際社內邊數 / 最大可能邊數（n(n-1)/2）。這就是社群「緊密度」的量化。
• score_all(G, communities) — 一行迴圈，把每個社群算一遍凝聚力，回傳 {cid: score}。
• community_member_sigs(communities) — 每個社群算「成員 ID 排序後的 SHA256 指紋」，存到 .graphify_labels.json 旁。之後 cluster-only 可以判斷哪個社群真的變了——成員不再雜湊一致的社群是「不同社群」，沿用舊 label 就是「stale label」bug。