indexion-kgf

indexion kgf

透過檢視 token、剖析事件與提取的邊緣，檢查與偵錯 KGF 語言規格。

使用時機

• 使用者想偵錯 indexion 如何處理特定檔案
• 使用者正在開發或修改 KGF 規格
• 使用者問「indexion 如何剖析這個檔案？」
• 驗證某語言的斷詞/剖析是否正確
• 偵錯 grep 模式：當 grep 模式比對不到時，使用
  kgf tokens 查看實際的 token 種類

子指令

indexion kgf list — 列出已安裝的規格

indexion kgf list

indexion kgf update — 更新所有規格

從 GitHub 下載最新規格。

indexion kgf update

indexion kgf add — 安裝單一規格

indexion kgf add <spec-name>

indexion kgf inspect — 完整檢查

同時顯示 token、事件與邊緣。

indexion kgf inspect <file>
indexion kgf inspect --spec=typescript src/app.ts

indexion kgf tokens — 僅斷詞

顯示檔案如何被斷詞。

indexion kgf tokens <file>
indexion kgf tokens --spec=go-mod go.mod

indexion kgf events — 僅剖析事件

顯示從 token 產生的剖析事件。

indexion kgf events <file>

indexion kgf edges — 僅提取的邊緣

顯示從檔案中提取的依賴邊緣。

indexion kgf edges <file>
indexion kgf edges fixtures/project/npm/package.json

選項

選項	預設值	說明
--spec=NAME	自動偵測	使用的 KGF 規格名稱
--kgf-dir=PATH	kgfs	KGF 規格目錄

與 grep 的關係

indexion grep 底層使用 KGF 斷詞。模式別名
（pub → KW_pub）來自 KGF 規格的 === lex 區段。

當 grep 模式不如預期比對到時：

# 1. 查看檔案的實際 token
indexion kgf tokens src/config/paths.mbt

# 2. 檢查有哪些 token 種類
indexion kgf tokens src/config/paths.mbt | head -20

# 3. 然後調整 grep 模式以比對實際的 token 種類
indexion grep "KW_pub KW_fn Ident" src/config/paths.mbt

常見的 token 種類（MoonBit）：

• KW_pub, KW_fn, KW_struct, KW_enum, KW_type, KW_trait, KW_let, KW_for
• Ident（小寫識別字）, TypeIdent（大寫開頭型別名稱）
• LPAREN, RPAREN, LBRACE, RBRACE, LBRACKET, RBRACKET
• NL（換行）, SKIP（空白 — 從 grep 模式中過濾掉）
• DocComment, DocLine, DocSection, LineComment, BlockComment
• String, Number, Char

工作流程

1. 執行 indexion kgf inspect <file> 查看完整處理管線
2. 如果看起來有問題，用 tokens、events 或 edges 深入檢查
3. 與 KGF 規格檔（kgfs/<lang>.kgf）比較以診斷問題

KGF 開發常見陷阱

撰寫或修改 KGF 規格時常見的錯誤：

PEG 項目順序（先比對先贏）

KGF 使用 PEG 剖析。在 Item -> A / B / C 中，如果 A 比對成功，B 和 C 就不會再嘗試。將 DocComment 作為獨立選項放在宣告規則之前，會消耗掉本應附著在宣告上的文件註解。

# 錯誤：DocComment 在 FuncDecl 之前 — 文件被當作獨立項目消耗
Item -> NL / DocComment / FuncDecl / Other

# 正確：DocComment 在宣告之後 — FuncDecl 的 doc:DocComment? 會取得它
Item -> NL / FuncDecl / DocComment / Other

文件與關鍵字之間的換行

原始碼在文件註解與宣告之間有換行。沒有 NL? 或 NL*，選擇性的文件擷取會靜默失敗：

# 錯誤：DocComment 緊接在關鍵字之後 — 換行破壞了比對
FuncDecl -> doc:DocComment? KW_fn id:Ident ...

# 正確：NL? 允許文件與關鍵字之間常見的換行
FuncDecl -> doc:DocComment? NL? KW_fn id:Ident ...

由下而上的事件順序（bind/scope）

事件由下而上觸發：子規則先於父規則。如果 ExportDecl 包住 FunctionDecl，FunctionDecl 會先觸發。使用 bind/$scope 將資料從子規則傳遞給父規則：

on FunctionDecl {
  bind ns "value" name "child_decl_id" to $id
  edge declares from $file to sym_id attrs obj(...)
}
on ExportDecl when $doc {
  let id = $scope("value", "child_decl_id")
  edge declares from $file to sym_id attrs obj("doc", $doc, ...)
}

Token 優先權衝突

較早定義的 token 優先權較高。通用的 Operator /[=+\-*]+/ 在 EQ /=/ 之前會將 = 消耗為 Operator。先定義特定的 token：

# 錯誤：Operator 在 EQ 之前比對到 =
TOKEN Operator /[!$%&*+\-.\/:<=>?@^|~]+/
TOKEN EQ       /=/

# 正確：EQ 先定義，取得優先權
TOKEN EQ       /=/
TOKEN Operator /[!$%&*+\-.\/:<=>?@^|~]+/

驗證文件提取

修改 KGF 後，務必驗證文件是否出現在 declares 邊緣中：

# 必須在 declares 邊緣中顯示 doc="..."
indexion kgf edges test_file.ts --spec=typescript | grep declares

# 如果文件遺失，檢查事件以查看 DocComment 去了哪裡
indexion kgf events test_file.ts --spec=typescript | grep DocComment