Thalo Language Server

Language Server Protocol (LSP) implementation for thalo (Thought And Lore Language).

Features

| Feature | Status | Description | | ------------------- | ------ | ------------------------------------------------ | | Go to Definition | ✅ | Navigate to definitions (links, entities, etc.) | | Find All References | ✅ | Find usages of links, tags, entities, and fields | | Semantic Tokens | ✅ | Syntax highlighting via LSP | | Diagnostics | ✅ | Validation errors and warnings | | Hover | ✅ | Context-aware info for all syntax elements | | Completions | ✅ | Schema-aware suggestions throughout entries |

Architecture

The language server uses @rejot-dev/thalo for parsing and semantic analysis:

┌─────────────────────────────────────────────────────────┐
│                      IDE / Editor                       │
│                   (VSCode, Neovim, etc.)                │
└─────────────────────────┬───────────────────────────────┘
                          │ LSP Protocol
┌─────────────────────────▼───────────────────────────────┐
│                    @rejot-dev/thalo-lsp                     │
│  ┌────────────────────────────────────────────────────┐ │
│  │ server.ts - LSP server lifecycle & routing         │ │
│  └────────────────────────────────────────────────────┘ │
│  ┌────────────────────────────────────────────────────┐ │
│  │ handlers/ - Request handlers                       │ │
│  │   definition.ts   - Go to definition               │ │
│  │   references.ts   - Find all references            │ │
│  │   semantic-tokens.ts - Syntax highlighting         │ │
│  │   diagnostics.ts  - Validation errors              │ │
│  │   hover.ts        - Hover information              │ │
│  │   completions/    - Autocomplete suggestions       │ │
│  │     context.ts    - Context detection              │ │
│  │     providers/    - Modular completion providers   │ │
│  └────────────────────────────────────────────────────┘ │
│  ┌────────────────────────────────────────────────────┐ │
│  │ capabilities.ts - LSP capability configuration     │ │
│  └────────────────────────────────────────────────────┘ │
└─────────────────────────┬───────────────────────────────┘
                          │
┌─────────────────────────▼───────────────────────────────┐
│                      @rejot-dev/thalo                       │
│  ┌─────────────┐ ┌─────────────┐ ┌───────────────────┐  │
│  │   parser    │ │   model     │ │     services      │  │
│  │  (parsing)  │ │ (workspace) │ │ (definition, etc) │  │
│  └─────────────┘ └─────────────┘ └───────────────────┘  │
│  ┌─────────────┐ ┌──────────────────────────────────┐   │
│  │   checker   │ │   semantic-tokens (highlighting) │   │
│  │ (diagnostics)│ └──────────────────────────────────┘  │
│  └─────────────┘                                        │
└─────────────────────────────────────────────────────────┘

Development

# Build
pnpm build

# Type check
pnpm types:check

# Run tests
pnpm test

Usage

The server communicates over stdio:

# Run the server (after building)
node dist/server.js --stdio

Integration with Editors

The server can be integrated with any editor that supports LSP:

• VSCode: Use the @rejot-dev/thalo-vscode extension
• Neovim: Configure with nvim-lspconfig
• Other editors: Configure to run thalo-lsp --stdio

Feature Details

Go to Definition

Navigate to the definition of various syntax elements:

| Element | Navigates to | | ----------------------------- | ----------------------------------- | | ^link-id | Entry where the link is defined | | Entity name (create lore) | define-entity for that entity | | Metadata key (confidence:) | Field definition in entity schema | | Section header (# Claim) | Section definition in entity schema | | alter-entity entity name | Original define-entity | | actualize-synthesis ^target | define-synthesis target entry |

Find All References

Find all usages of various syntax elements across the workspace:

| Element | Finds | | ----------------------------- | ------------------------------------------- | | ^link-id | All references to that link | | #tag | All entries with that tag | | Entity name | All entries using that entity type | | Metadata key | All entries using that field | | Section header | All entries with that section | | define-entity entity name | All usages + alter-entity entries | | define-synthesis ^link-id | All references + actualize-synthesis usages |

Hover

Context-aware hover information for various syntax elements:

| Element | Information shown | | --------------------- | --------------------------------------------------------------------- | | ^link-id | Entry title, metadata, tags, and file location | | #tag | Usage count and list of entries with that tag | | Directive | Documentation with syntax and examples | | Entity name | Full schema: fields (with types), sections, and where defined | | Metadata key | Field type, required/optional, default value, and description | | Timestamp | Entry info and hint to add explicit link ID for referencing | | Type expr | Documentation for string, datetime, daterange, link, number | | Section header | Section description and required/optional status from schema | | define-synthesis | Documentation for defining synthesis operations | | actualize-synthesis | Documentation for triggering synthesis regeneration |

Completions

Context-aware completions throughout the entry lifecycle:

| Context | Trigger | Suggests | | --------------- | -------------------------- | ------------------------------------------------------------------------------ | | Empty line | Start typing | Current timestamp (2026-01-06T14:30) | | After timestamp | Space | All directives (create, update, define-entity, define-synthesis, etc.) | | After directive | Space | Entity types (lore, opinion, reference, etc.) | | After title | ^ or # | Link IDs or tags | | Metadata key | Indented line | Field names from entity schema | | Metadata value | After key: | Valid values (literals, ^self, etc.) | | Content section | # in content area | Section names from schema (Claim, Reasoning) | | Schema block | # in schema entry | # Metadata, # Sections, etc. | | Field type | After field name in schema | string, datetime, link, daterange, number | | Link reference | ^ | All link IDs from workspace | | Tag | # | Existing tags with usage counts |

Schema-aware: Metadata keys, values, and sections are pulled from entity schemas defined via define-entity.

Smart filtering:

• Already-used metadata keys are excluded
• Required fields/sections sorted before optional
• Partial text filtering on all completions

Diagnostics

Real-time validation errors using the @rejot-dev/thalo checker:

• Unresolved link references
• Unknown entity types
• Missing required fields/sections
• Invalid field types
• Duplicate link IDs

Semantic Tokens

Provides rich syntax highlighting for:

• Timestamps
• Directives (create, update, define-entity, alter-entity, define-synthesis, actualize-synthesis)
• Entity types
• Link references (with declaration modifier for definitions)
• Tags
• Metadata keys and values
• Section headers

Limitations

Not Yet Implemented

• Rename Symbol: No support for renaming link IDs, tags, or entities across files
• Code Actions: No quick fixes or refactoring actions
• Workspace Symbols: No symbol search across the workspace
• Document Symbols: No outline/breadcrumb support for entry structure
• Folding Ranges: No collapsible regions for entries or sections
• Document Links: No clickable links in content (only ^link-id in metadata)
• Signature Help: No parameter hints (not applicable to thalo syntax)
• Call Hierarchy: No incoming/outgoing call navigation
• Type Hierarchy: No type relationship navigation

Partial Support

• Incremental Updates: Full document re-parse on each edit (no incremental parsing)
• Large Workspaces: Performance may degrade with very large .thalo files (>10K lines)
• Markdown Files: Only .thalo code blocks within .md files are parsed; frontmatter is ignored
• Query Language: The sources: field in define-synthesis entries is not semantically validated
• Synthesis Completions: No specialized completions for synthesis query syntax (where clauses, etc.)

Known Issues

• Hover on timestamps shows entry info but timestamps are not valid link targets (use explicit ^link-id)
• Section header completions only appear when cursor is directly after # in content area
• Field type completions in schema entries don't suggest custom entity types for nested references