Tooling · Guide

VS Code Extension.

Syntax highlighting, schema-aware autocomplete, and inline linter warnings for .kgl files. Powered by a Python LSP server that reuses the core kgl parser and linter.

Installation

From the VS Code Marketplace

First install the Python package — the extension requires it for the language server:
bash
```
pip install kgl-lang
```
Install the extension from the Marketplace. Open VS Code, go to Extensions (⇧⌘X), and search for KGL. Or run the command:
VS Code Quick Open (⌘P)
```
ext install kgl.kgl
```

From source (development)

Install the Python package and clone the repo, then build the extension:
bash
```
cd kgl-vscode
npm install
npm run compile
```
Open VS Code and run Extensions: Install from VSIX, or press F5 to launch a development host.

Verify

Open any .kgl file. You should see:

Syntax highlighting for @Type, field names, tags, and links
Squiggly underlines for linter warnings on save (requires a _schema.kgl)

Features

Syntax highlighting

The extension ships a TextMate grammar (syntaxes/kgl.tmLanguage.json) that colours:

Element	TextMate scope
@Person — type token	`entity.name.type.kgl`
Node name	`entity.name.function.kgl`
→ / `->`	`keyword.operator.link.hard.kgl`
~>	`keyword.operator.link.soft.kgl`
[rel-name] block	`keyword.control.relationship.kgl`
Field/property key	`variable.other.property.kgl`
Field/property value	`string.unquoted.field-value.kgl`
#tag	`storage.type.tag.kgl`
# comment	`comment.line.kgl`
`---` separator	`markup.heading.separator.kgl`

Diagnostics (linter squiggles)

On file save, the language server runs the KGL linter and pushes diagnostics to VS Code. Warnings appear as yellow squiggles. Hover over a squiggle to see the warning code and message.

Requires a _schema.kgl at the workspace root or in the same folder as the .kgl file.

Autocomplete

The language server provides context-aware completions:

After @ — suggests node types defined in _schema.kgl
After [ — suggests relationship types defined in _schema.kgl
After : in a node body — suggests field names for the current node type

Go to definition

Place the cursor on a link target (e.g. → people/diana.kgl#Diana Park) and press F12 (Go to Definition) to open diana.kgl at the line where @Person Diana Park is declared.

Hover

Hover over a link target to see a Markdown summary of the target node: its type, fields, and tags.

Configuration

Setting	Default	Description
`kgl.pythonPath`	`"python"`	Path to the Python interpreter that has `kgl` installed
`kgl.lintOnSave`	`true`	Run the linter when a `.kgl` file is saved

Set these in VS Code's settings.json:

settings.json

{
  "kgl.pythonPath": "/usr/local/bin/python3",
  "kgl.lintOnSave": true
}

Architecture

The extension has three layers:

TextMate grammar (syntaxes/kgl.tmLanguage.json) — syntax highlighting, no JS required
TypeScript shim (src/extension.ts) — spawns the Python LSP server as a subprocess
Python LSP server (kgl/lsp_server.py, entry point kgl-lsp) — implements JSON-RPC 2.0 over stdio; reuses the parser, model, schema, and linter from the core kgl package

The LSP server communicates over stdin/stdout. VS Code spawns it when the first .kgl file is opened and keeps it running for the session.