// Debug and inspect KGF specs — view tokenization results, parse trees, and extracted edges from source files. Use when adding/fixing language support or when indexion's analysis output looks wrong.
| name | indexion-kgf |
| description | Debug and inspect KGF specs — view tokenization results, parse trees, and extracted edges from source files. Use when adding/fixing language support or when indexion's analysis output looks wrong. |
Inspect and debug KGF language specs by viewing tokens, parse events, and extracted edges.
kgf tokens to see the actual token kindsindexion kgf list — List Installed Specsindexion kgf list
indexion kgf update — Update All SpecsDownload the latest specs from GitHub.
indexion kgf update
indexion kgf add — Install a Single Specindexion kgf add <spec-name>
indexion kgf inspect — Full InspectionShow tokens, events, and edges all at once.
indexion kgf inspect <file>
indexion kgf inspect --spec=typescript src/app.ts
indexion kgf tokens — Tokenization OnlyShow how a file is tokenized.
indexion kgf tokens <file>
indexion kgf tokens --spec=go-mod go.mod
indexion kgf events — Parse Events OnlyShow parse events generated from tokens.
indexion kgf events <file>
indexion kgf edges — Extracted Edges OnlyShow the dependency edges extracted from a file.
indexion kgf edges <file>
indexion kgf edges fixtures/project/npm/package.json
| Option | Default | Description |
|---|---|---|
--spec=NAME | auto-detect | KGF spec name to use |
--kgf-dir=PATH | kgfs | KGF specs directory |
indexion grep uses KGF tokenization under the hood. Pattern aliases
(pub → KW_pub) are derived from the === lex section of KGF specs.
When a grep pattern doesn't match as expected:
# 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
Common token kinds (MoonBit):
KW_pub, KW_fn, KW_struct, KW_enum, KW_type, KW_trait, KW_let, KW_forIdent (lowercase identifiers), TypeIdent (PascalCase type names)LPAREN, RPAREN, LBRACE, RBRACE, LBRACKET, RBRACKETNL (newline), SKIP (whitespace — filtered from grep patterns)DocComment, DocLine, DocSection, LineComment, BlockCommentString, Number, Charindexion kgf inspect <file> to see the full processing pipelinetokens, events, or edgeskgfs/<lang>.kgf) to diagnose issuesCommon bugs found when writing or modifying KGF specs:
KGF uses PEG parsing. In Item -> A / B / C, if A matches, B and C are
never tried. DocComment as a standalone alternative before declaration
rules will consume doc comments that should be attached to declarations.
# 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
Source code has newlines between doc comments and declarations. Without
NL? or NL*, the optional doc capture fails silently:
# 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 ...
Events fire bottom-up: child rules before parent rules. If ExportDecl
wraps FunctionDecl, FunctionDecl fires first. Use bind/$scope to
pass data from child to parent:
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, ...)
}
Tokens defined earlier take priority. A generic Operator /[=+\-*]+/
before EQ /=/ will consume = as Operator. Define specific tokens first:
# BAD: Operator matches = before EQ can
TOKEN Operator /[!$%&*+\-.\/:<=>?@^|~]+/
TOKEN EQ /=/
# GOOD: EQ defined first, takes priority
TOKEN EQ /=/
TOKEN Operator /[!$%&*+\-.\/:<=>?@^|~]+/
After modifying a KGF, always verify doc appears in declares edges:
# 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
README construction — initialize template structure, generate per-package READMEs from doc comments, plan writing tasks, assemble root README from docs/ and package READMEs via doc.json config, and verify edits with `plan drift`.
Detect and review name/content drift in code using `indexion identity audit`, then plan verified renames, moves, folder changes, or splits.
Generate and use a pre-edit structure brief so coding agents learn likely owners, consumer surfaces, and unsafe edit locations before implementing.
Generate SDD requirements from RFCs/specs and quantitatively verify implementation conformance. spec draft → spec align → spec verify → automated validation loop with codex/claude. Operate spec-to-impl drift gates as CI checks.
Documentation analysis — assess coverage, detect code-to-doc drift with plan reconcile, visualize dependencies with doc graph. Answers "what needs docs?" and "are docs still accurate?"
Project wiki lifecycle — create pages, track source changes with ingest, update stale pages, lint structural integrity, detect code-to-doc drift with reconcile, and manage search indexes. A runbook for navigating and maintaining the wiki as an agent.