GFA BASIC Rust Documentation

Language tooling and editor integration

Architecture

Language tooling and editor integration

  • Status: Accepted architecture direction; implementation is tracked by #209, #210, and #211.
  • Decision record: ADR 0012.

Goals and boundaries

Provide one reusable language engine for the selected Commodore Amiga GFA BASIC interpreter 3.5 dialect. The CLI, formatter, language server, and editor integrations must consume the same source and semantic models.

The language server is a protocol adapter. It is not another compiler frontend and must not reimplement tokenization, parsing, symbol resolution, diagnostics, or formatting. The frontend and semantic engine remain independent of LSP, VS Code, IntelliJ, LLVM, SDL3, and generated-program runtime code.

Logical architecture

VS Code extension                 IntelliJ plugin
       |                                |
       +----------- LSP / JSON-RPC -----+
                       |
                gfabasic-lsp
                       |
             shared compiler services
          +------------+-------------+
          |            |             |
      lossless CST   semantics    formatter
          |         symbol index      |
          +------------+-------------+
                       |
                 compiler / CLI
                       |
               typed IR / backend

The diagram shows logical responsibilities, not a mandatory Cargo crate split. The LSP server may be a separate crate because it owns a protocol/binary boundary and protocol dependencies; keep internal compiler stages as modules unless a demonstrated dependency or ownership boundary justifies another crate.

Shared frontend contract

The language tooling depends on these shared services:

  • Lossless source model: retain comments, whitespace/trivia, original literal payloads, line boundaries, and source spans. A semantic AST alone is not sufficient for formatting or precise editor edits.
  • Semantic model: expose stable symbol identities, declaration/reference relationships, scopes, signatures, and source locations.
  • Diagnostics: reuse compiler diagnostic codes, severity, source spans, and source-map conversion. Editor diagnostics must not be generated by a second parser.
  • Formatter: expose a library API independent of CLI and LSP. Formatting is available only for syntax the frontend can parse and safely preserve.
  • Build service: reuse the compiler's build pipeline and configuration. Editor build actions must not contain their own compiler or code generator.

The selected dialect/version is explicit. Rules found only in Amiga 3.0/3.03 references remain inherited candidates until confirmed for 3.5. Atari syntax and AmigaBASIC syntax must not be imported into the language server's Amiga GFA BASIC 3.5 grammar.

Identifiers are source data, not prose. Slovak, English, mixed-language, and other valid identifier names must be retained exactly. The formatter must not translate or normalize them. Rename changes only the symbol explicitly selected by the user and references proven to resolve to it.

LSP process and protocol

  • Use standard LSP over JSON-RPC with stdio as the initial transport.
  • Implement initialize, capability negotiation, shutdown, exit, and document lifecycle.
  • Begin with full-document synchronization. Advertise incremental synchronization only after correct versioned incremental updates and reparsing are implemented.
  • Keep document versions and reject or avoid stale diagnostics and workspace edits.
  • Compiler source spans remain byte-based. Convert to and from LSP line/character positions at the boundary; LSP character offsets are UTF-16 code units. Test non-ASCII identifiers/comments, supplementary Unicode characters, CRLF/LF, and edits around line boundaries.
  • Support cancellation and multiple open documents as the server matures.
  • Do not advertise a capability before its implementation and protocol tests pass.

Capability progression

Capability Shared prerequisite Planned behavior
Diagnostics Lexer/parser, source map, semantic diagnostics Publish compiler diagnostics for the current document version
Formatting Lossless CST/trivia and formatter library Whole-document and range formatting without changing program meaning
Go to definition Symbol resolution Navigate to the resolved declaration
Find references Symbol index Return references bound to the selected symbol
Completion Parser context and visible symbols Offer in-scope identifiers and only verified built-ins/keywords
Rename Stable symbol identity and reference index Emit versioned workspace edits for the selected symbol only
Code actions Diagnostics and safe transformation APIs Offer only transformations with verified preconditions
Build Shared compiler/build pipeline and stable CLI/configuration contract Invoke the same build implementation used outside the editor and report diagnostics/artifacts

Capability rollout is incremental. Initial server scaffolding may precede the semantic engine, but unsupported capabilities must remain unadvertised. Formatting and compiler diagnostics are the first useful capabilities; navigation and refactoring follow symbol resolution.

Refactoring correctness

Rename must never be implemented as a plain text search-and-replace. It must:

  1. Resolve the selected occurrence to a unique symbol identity.
  2. Obtain declarations and references from the semantic index.
  3. Exclude strings, comments, DATA payloads, unrelated identifiers, and shadowed symbols.
  4. Check document versions before returning or applying edits.
  5. Preserve spelling and encoding outside the explicitly renamed identifier.
  6. Return no unsafe edit when the symbol is unresolved or ambiguous.

Extract/inline refactoring and structural transformations are later capabilities. They require verified control-flow and scope semantics and are not part of the first LSP milestone.

Editor clients

Visual Studio Code

The extension owns language registration, file associations, basic syntax highlighting, server discovery/configuration, and task integration. It consumes LSP features and delegates builds to the common gfabasic CLI/build service. TextMate or similar highlighting is a presentation layer only and must not be treated as syntax validation.

Tracking: #210.

IntelliJ IDEA

Prefer a thin plugin using an established LSP client integration. It owns file-type registration, server configuration, settings, and build/run configuration integration. Add native IntelliJ PSI or refactoring adapters only when a concrete capability cannot be delivered through LSP and the maintenance cost is justified. Any native adapter must remain consistent with the shared frontend.

Tracking: #211.

Build and debug integration

The server may expose a documented gfabasic.build execute-command or equivalent. It must call the shared compiler/build pipeline, use the same configuration and diagnostics as the CLI, and report progress/result information through protocol notifications where supported. The LSP server does not own code generation, linking, runtime startup, or platform APIs.

Debugging is explicitly deferred. A future Debug Adapter Protocol (DAP) adapter requires a separate decision covering source-level stepping, variable inspection, runtime instrumentation, and the relationship between generated code and original BASIC source.

Testing and quality gates

  • Unit-test UTF-8 byte-span / UTF-16 position conversions and line-ending behavior.
  • Test document lifecycle, versioning, cancellation, and multiple documents.
  • Use protocol integration tests for diagnostics, formatting, navigation, references, completion, and rename.
  • Test that formatting is idempotent and preserves comments/literals as specified by #208.
  • Test rename against shadowed names, unresolved references, comments, strings, DATA statements, and non-ASCII identifiers.
  • Keep server tests independent of both editor applications and LLVM/SDL3 system dependencies.
  • Verify editor extensions from clean installations and test server discovery/failure behavior.
  • Keep the GFA BASIC 3.5 compatibility/evidence gate authoritative for all advertised language behavior.