diagramming-code

程式碼圖表化

從 Trailmark 的程式碼圖表產生 Mermaid 圖表。預先寫好的腳本負責處理 Mermaid 語法產生；Claude 選擇圖表類型和參數。

使用時機

• 視覺化函式間的呼叫路徑
• 繪製類別繼承階層
• 對應模組匯入相依性
• 顯示類別結構與成員
• 用顏色標示複雜度熱點
• 從進入點到敏感函式的資料流程追蹤

不適合使用時機

• 查詢圖表但不需視覺化（請使用 trailmark 技能）
• 突變測試分類（請使用 genotoxic 技能）
• 非從程式碼衍生的架構圖（請手繪）

前置需求

必須安裝 trailmark。如果 uv run trailmark 執行失敗，請執行：

uv pip install trailmark

請勿 退而求其次，直接從原始碼閱讀手寫 Mermaid。腳本使用 Trailmark 解析的圖表以確保準確性。如果安裝失敗，請向使用者回報錯誤。

---

快速開始

uv run {baseDir}/scripts/diagram.py \
    --target {targetDir} --language auto --type call-graph \
    --focus main --depth 2

輸出為純 Mermaid 文字。請用圍欄程式碼區塊包覆：

```mermaid
flowchart TB
    ...
```

---

圖表類型

├─ "誰呼叫誰？"               → --type call-graph
├─ "類別繼承？"               → --type class-hierarchy
├─ "模組相依性？"             → --type module-deps
├─ "類別成員與結構？"         → --type containment
├─ "哪裡複雜度最高？"         → --type complexity
└─ "從輸入到函式的路徑？"     → --type data-flow

各類型的詳細範例請參閱
references/diagram-types.md。

---

工作流程

圖表進度：
- [ ] 步驟 1：確認 trailmark 已安裝
- [ ] 步驟 2：根據使用者需求判斷圖表類型
- [ ] 步驟 3：決定焦點節點與參數
- [ ] 步驟 4：執行 diagram.py 腳本
- [ ] 步驟 5：確認輸出非空且格式正確
- [ ] 步驟 6：將圖表嵌入回應中

步驟 1： 執行 uv run trailmark analyze --language auto --summary {targetDir}。如果失敗則安裝。接著透過程式化 API 執行預先分析：

from trailmark.query.api import QueryEngine

engine = QueryEngine.from_directory("{targetDir}", language="auto")
engine.preanalysis()

預先分析會為圖表加入爆炸半徑、汙染傳播及權限邊界資料，這些資料用於 data-flow 圖表。

如果自動偵測對目標不正確，請使用明確語言或逗號分隔清單重新執行，例如 python,rust。

步驟 2： 使用上述決策樹將使用者需求對應到 --type。

步驟 3： 對於 call-graph 和 data-flow，找出焦點函式。預設 --depth 2。相依性流程請使用 --direction LR。

步驟 4： 執行腳本並擷取標準輸出。

步驟 5： 檢查：輸出是否以 flowchart 或 classDiagram 開頭，且至少包含一個節點。如果為空或格式錯誤，請參閱 references/mermaid-syntax.md。

步驟 6： 將輸出包覆在 ```mermaid ``` 圍欄程式碼區塊中。

---

腳本參考

uv run {baseDir}/scripts/diagram.py [選項]

參數	簡寫	預設值	說明
--target	-t	必填	要分析的目錄
--language	-l	python	原始碼語言
--type	-T	必填	圖表類型（見上方）
--focus	-f	無	將圖表以此節點為中心
--depth	-d	2	BFS 遍歷深度
--direction		TB	佈局：TB（上到下）或 LR（左到右）
--threshold		10	complexity 類型的最小複雜度

範例

# 以函式為中心的呼叫圖
uv run {baseDir}/scripts/diagram.py -t src/ -T call-graph -f parse_file

# Rust 專案的類別階層
uv run {baseDir}/scripts/diagram.py -t src/ -l rust -T class-hierarchy

# 模組相依性圖，由左至右
uv run {baseDir}/scripts/diagram.py -t src/ -T module-deps --direction LR

# 類別成員
uv run {baseDir}/scripts/diagram.py -t src/ -T containment

# 複雜度熱力圖（門檻值 5）
uv run {baseDir}/scripts/diagram.py -t src/ -T complexity --threshold 5

# 從進入點到特定函式的資料流程
uv run {baseDir}/scripts/diagram.py -t src/ -T data-flow -f execute_query

---

自訂選項

方向： 使用 TB（預設）呈現階層檢視，LR 用於從左到右的流程，例如相依性鏈。

深度： 增加 --depth 可看到更多呼叫圖；減少則可降低雜亂度。腳本會在圖表超過 100 個節點時發出警告。

焦點： 對於非平凡的程式碼庫，call-graph 務必使用 --focus。對於 data-flow，省略焦點會自動鎖定前 10 大複雜度熱點。

語言： 對於多語言或不熟悉的儲存庫，建議使用 --language auto。只有在確定目標為單一語言或需要排除不相關元件時，才使用明確語言。

---

輔助文件

• references/diagram-types.md -
  各圖表類型的詳細說明與 Mermaid 範例
• references/mermaid-syntax.md -
  ID 清理、跳脫、樣式定義及常見陷阱