Skip to content

ADR-0069: LSP Server for IDE Integration

  • Status: Accepted
  • Date: 2026-05-02
  • Supersedes: —
  • Superseded by: —
  • Related: ADR-0021 (Progressive Enhancement), ADR-0006 (Cedar Policy), ADR-0017 (ActiveGraph ORM)

Context

Trails developers work across multiple languages in a single project: Python decorators (@capability, @node_type, @shape), Cedar .cedar policy files, SPARQL queries embedded in triple-quoted strings, and trails.toml configuration. Without IDE support, errors like duplicate capability names, undefined node-type references, and unknown config keys surface only at runtime.

The VS Code extension client stub (editor/vscode/src/lsp-client.ts) already expects trails lsp --stdio but there is no server to connect to.

Decision

Implement a trails.lsp module using pygls (Python Language Server Protocol library), served via trails lsp --stdio.

Features

  1. Diagnostics — on save/change:
  2. Duplicate capability names across files
  3. Undefined node-type references in field declarations
  4. Missing required fields on decorators
  5. Cedar policy references to non-existent capabilities

  6. Unknown keys in trails.toml

  7. Completions:

  8. Python type suggestions inside @node_type(fields={...})
  9. Capability name suggestions inside .cedar files

  10. Registered prefix suggestions inside SPARQL strings

  11. Hover:

  12. @capability signature + docstring

  13. @node_type field listing

  14. Go-to-definition:

  15. From node-type name references to their @node_type declaration

Design constraints

  • Pure AST analysis via Python's ast module — no Store or runtime import required.
  • pygls is an optional dependency; the module guards the import and raises a clear error if missing.
  • Lazy-loaded via the CLI's existing LazyGroup mechanism.

Consequences

  • IDE users get immediate feedback on cross-language consistency errors.
  • The server can evolve incrementally: new diagnostic rules or completion sources are additive.
  • pygls becomes an optional dependency (not added to core requirements).