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. 查看文件的实际词法单元
indexion kgf tokens src/config/paths.mbt

# 2. 检查存在哪些词法单元类型
indexion kgf tokens src/config/paths.mbt | head -20

# 3. 然后调整 grep 模式以匹配实际的词法单元类型
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（帕斯卡命名法类型名）
• 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, ...)
}

词法单元优先级冲突

先定义的词法单元优先级更高。通用的 Operator /[=+\-*]+/
在 EQ /=/ 之前会消耗 = 作为 Operator。先定义特定的词法单元：

# 错误：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