indexion-kgf

indexion kgf

トークン、解析イベント、抽出されたエッジを表示して、KGF 言語仕様を調査およびデバッグします。

使用する場面

• 特定のファイルを indexion がどのように処理するかデバッグしたい場合
• KGF 仕様を開発または変更している場合
• 「indexion はこのファイルをどのように解析しますか？」と尋ねられた場合
• ある言語のトークン化／解析が正しく動作するか検証する場合
• grep パターンのデバッグ：grep パターンが一致しない場合は、 kgf tokens を使って実際のトークン種別を確認します

サブコマンド

indexion kgf list — インストール済みの仕様を一覧表示

indexion kgf list

indexion kgf update — すべての仕様を更新

GitHub から最新の仕様をダウンロードします。

indexion kgf update

indexion kgf add — 1 つの仕様をインストール

indexion kgf add <spec-name>

indexion kgf inspect — 全体を調査

トークン、イベント、エッジを一度に表示します。

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 — 解析イベントのみ

トークンから生成された解析イベントを表示します。

indexion kgf events <file>

indexion kgf edges — 抽出されたエッジのみ

ファイルから抽出された依存関係のエッジを表示します。

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

オプション

オプション	デフォルト	説明
--spec=NAME	auto-detect	使用する KGF 仕様の名前
--kgf-dir=PATH	kgfs	KGF 仕様のディレクトリ

grep との関係

indexion grep は内部で KGF のトークン化を使用します。パターンエイリアス （pub → KW_pub）は、KGF 仕様の === lex セクションから導出されます。

grep パターンが期待どおりに一致しない場合：

# 1. See the actual tokens for a file
indexion kgf tokens src/config/paths.mbt

# 2. Check which token kinds exist
indexion kgf tokens src/config/paths.mbt | head -20

# 3. Then adjust your grep pattern to match the actual token kinds
indexion grep "KW_pub KW_fn Ident" src/config/paths.mbt

一般的なトークン種別（MoonBit）：

• KW_pub、KW_fn、KW_struct、KW_enum、KW_type、KW_trait、KW_let、KW_for
• Ident（小文字の識別子）、TypeIdent（PascalCase の型名）
• 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 を置くと、 宣言に付加されるべきドキュメントコメントを消費してしまいます。

# BAD: DocComment before FuncDecl — doc is consumed as standalone item
Item -> NL / DocComment / FuncDecl / Other

# GOOD: DocComment after declarations — FuncDecl's doc:DocComment? gets it
Item -> NL / FuncDecl / DocComment / Other

ドキュメントとキーワードの間の NL

ソースコードでは、ドキュメントコメントと宣言の間に改行があります。 NL? または NL* がないと、省略可能なドキュメントのキャプチャは エラーを通知せずに失敗します。

# BAD: DocComment immediately followed by keyword — NL breaks the match
FuncDecl -> doc:DocComment? KW_fn id:Ident ...

# GOOD: NL? allows the typical newline between doc and keyword
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, ...)
}

トークン優先順位の競合

先に定義されたトークンが優先されます。EQ /=/ より前に汎用の Operator /[=+\-*]+/ を置くと、= が Operator として消費されます。 具体的なトークンを先に定義します。

# BAD: Operator matches = before EQ can
TOKEN Operator /[!$%&*+\-.\/:<=>?@^|~]+/
TOKEN EQ       /=/

# GOOD: EQ defined first, takes priority
TOKEN EQ       /=/
TOKEN Operator /[!$%&*+\-.\/:<=>?@^|~]+/

ドキュメント抽出の検証

KGF を変更した後は、必ず declares エッジにドキュメントが表示されることを確認します。

# Must show doc="..." in the declares edge
indexion kgf edges test_file.ts --spec=typescript | grep declares

# If doc is missing, check events to see where the DocComment went
indexion kgf events test_file.ts --spec=typescript | grep DocComment