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 — 安装单个规范

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	自动检测	要使用的 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