tooling

LSP EXTENSION LLD

Editor integration, implementation workflow, and operational runbooks.

Mutant LSP + VS Code Extension Low-Level Design (LLD)

This is the implementation-level developer guide for the Mutant language tooling stack.

Audience:

• Junior or new engineers who need to understand how Mutant language tooling works end-to-end.
• Maintainers adding or changing LSP features, diagnostics, formatting, completion, hover/signature behavior, or extension lifecycle behavior.

Scope:

• Go LSP server in lsp/cmd/mlsp/main.go and lsp/internal/server/server.go
• Analyzer pipeline in lsp/internal/analyzer
• Workspace state/index in lsp/internal/workspace
• VS Code extension host/client in mutant-vscode-extension/src/extension.ts

1. Architecture Overview

Core separation of concerns:

• Extension is process lifecycle + UX shell around the language server.
• LSP server is request handling, state, and protocol behavior.
• Analyzer is language intelligence over current AST snapshot.
• Workspace index enables cross-file symbol/reference behavior.

2. Runtime Components

2.1 LSP binary entrypoint

• Entrypoint: lsp/cmd/mlsp/main.go
• Behavior:

1. Parse -debug flag
2. Build server via server.New(debug)
3. Run over stdio via server.Run()

2.2 JSON-RPC transport bridge

• Adapter: lsp/internal/server/transport.go
• Why it exists:
• glsp handler methods are wired into a jsonrpc2 stdio connection.
• It translates method/params and maps validation failures to JSON-RPC error codes.

Transport flow:

1. Read request from stdin stream.
2. Build glsp.Context with method, params, Notify, and Call handlers.
3. Dispatch with handler.Handle(...).
4. Reply (unless notification).

2.3 Server state and handler wiring

• Main implementation: lsp/internal/server/server.go

Server owns:

• LSP method handler table
• Document store (documents)
• Symbol index (symbols)
• Analyzer instance (analyzer)
• Per-document snapshots map (snapshots)
• Lint configuration
• Crash/fallback flags (for semantic token panic fallback warning)

Important constructor behavior:

• New(debug bool) binds all supported LSP endpoints to receiver methods.
• initialize advertises capabilities like completion, hover, signature help, references, rename, formatting, semantic tokens.

2.4 Document store

• Files: lsp/internal/workspace/store.go, lsp/internal/workspace/document.go
• Responsibility:
• Track opened documents and versions.
• Apply incremental text changes from LSP content change events.
• Return immutable clone snapshots to avoid accidental shared mutation.

2.5 Analyzer snapshot model

• Files: lsp/internal/analyzer/snapshot.go, lsp/internal/analyzer/analyzer.go
• Snapshot contains:
• raw source
• parsed AST program (Program)
• parse errors (hard failures)
• recoverables (Recoverables): non-fatal parser findings — most importantly the missing/redundant semicolon channel — surfaced via SemicolonProblems(). The tree still parses into a usable AST; these drive the semicolon diagnostic and its quick fixes.

Analyzer steps:

1. Lex + parse source into AST.
2. Preserve node ranges (NodePositions) from parser output.
3. Serve semantic queries (hover, completion, definitions, references, symbols, semantic tokens, signature help).

2.6 Workspace symbol index

• File: lsp/internal/workspace/symbol_index.go
• Purpose:
• Cache top-level symbols per document for workspace symbol search.
• Cache unresolved identifier usages to improve cross-document references.

This enables cross-file behaviors when a symbol is not resolvable only within a single snapshot.

3. LSP Capability Map (Method -> Implementation)

4. Key Request Flows

4.1 Open/change diagnostics flow

4.2 Completion flow

Implementation notes:

• Completions include keywords, builtins, snippets, visible scope bindings.
• Ordering is deterministic and stabilized with explicit sort keys in analyzer.

4.3 Rename flow

5. Diagnostics and Linting

Core file: lsp/internal/analyzer/diagnostics.go

Diagnostics sources:

• mutant-parser: parser errors from snapshot parse errors, plus the string/comment-aware delimiter-balance checker.
• mutant-lint: semantic lint rules.
• mutant-format: strict-formatting rules (the semicolon rule) — distinct from mutant-lint so quick fixes can key off it.

Current lint rules (rule id -> default severity):

• duplicateTopLevelDeclaration -> warning (also nested duplicates)
• unusedDeclaration -> warning (top-level and local; skips _)
• undefinedDeclaration -> error (scope-aware; builtins + macro special forms count as defined)
• nestingComplexity -> warning (if/for nesting depth > 2 in function bodies)
• semicolon -> warning (missing/redundant ;, source mutant-format; both have quick fixes and the formatter also repairs them on save)
• unreachableCode -> warning (statements after an unconditional return/break/continue in a statement list; literal control flow only)
• platformSupport -> warning (OS-aware: warns when a program calls a builtin that is not supported on the operating system the language server is running on, e.g. a Windows/Linux-only builtin such as process_modules used on macOS). The supported-platform set comes from builtin.PlatformSupport / builtin.UnsupportedOn in builtin/metadata.go; the host OS is runtime.GOOS (overridable in tests via the analyzer's hostGOOS).

Config ingestion path:

1. Extension sends settings changes via workspace/didChangeConfiguration.
2. Server parses with lsp/internal/server/lint_config.go.
3. republishAllDiagnostics updates existing open documents.

Supported severities:

• error, warning, information, hint, off

6. Formatting Design

Core file: lsp/internal/server/formatter.go

Behavior model:

• If hard parse errors exist (or the snapshot is invalid), the formatter degrades to whitespace normalization only (CRLF -> LF, strip trailing whitespace, exactly one trailing newline).
• Otherwise it applies AST-driven formatting for statements/expressions. Comments and blank lines are handled through the AST printer (re-attached from the program.Comments side-table; runs of blank lines collapse to one), so the presence of comments/blank lines no longer forces the normalization path.

Strict semicolons (canonical):

• Semicolons are emitted from the AST via ast.Statement.RequiresSemicolon(), not copied from source. The formatter therefore repairs missing semicolons and removes redundant ones on format. Recoverable semicolon issues do not trigger the normalization fallback; only hard parse errors do. Struct fields are ;-terminated including the last.

Canonical style policy:

• Four-space indent (never tabs); client tabSize/insertSpaces are ignored. The only user control is the master mutant.strictFormatting on/off toggle.
• Opening braces stay on the same line for supported constructs (if (...) {, for (...) {, fn(...) {, else {); operator expressions are fully parenthesized and space-padded for a canonical form.

On-type formatting behavior:

• Server advertises textDocument/onTypeFormatting and supports triggers for }, ;, and newline.
• Extension keeps on-type formatting disabled by default to avoid intrusive edits, and exposes an opt-in setting.

Important safety guarantees:

• String literal quotes are preserved and escaped.
• Formatting returns nil edits for noop output.

7. Semantic Tokens and Resilience

Semantic token production is in analyzer logic and requested through textDocument/semanticTokens/full.

Resilience behavior in lsp/internal/server/server.go:

• method-level panic recovery in semantic token handler
• one-time user warning if fallback path is used
• returns empty token list on failure instead of crashing LSP process

This prevents editor crash loops from semantic token panics.

8. Hover, Signature Help, and Teaching Metadata

Teaching metadata source:

• lsp/internal/analyzer/language_teach.go

What it provides:

• keyword hover docs
• builtin hover/signature docs
• snippet completion templates

Builtin coverage model:

• Rich docs from builtinDocs map when defined.
• Prefix-based fallback for builtin families (fs_, db_, bytes_, http_, etc.).
• Generic fallback for any builtin registered in builtin/builtin.go.

Capability categories and platform metadata (both surfaced without a custom token legend):

• Hover appends a _Category: <capability>_ line (from builtin.CapabilityCategory, e.g. filesystem, network, graph database, runtime integration, forensics) and, for platform-constrained builtins, a Platforms: line plus any behavioral note (from builtin.PlatformSupport).
• Completion Detail becomes builtin · <capability> so the completion list shows the category inline. Sorting still groups all builtins together (the completion category test now prefix-matches builtin).

Result:

• Newly added builtins are auto-discoverable in completion and still have baseline hover/signature coverage, with their capability category and platform support shown automatically.

9. VS Code Extension Design

Main file: mutant-vscode-extension/src/extension.ts

Responsibilities:

• Activate language client and commands.
• Resolve language server command path.
• Manage restarts and crash-loop backoff.
• Offer operational commands (status, logs, restart, smoke checks).

9.1 Binary selection algorithm

If mutant.languageServer.path is configured and non-empty:

• use it exactly.

Else:

1. Gather workspace roots and parent directories.
2. Search for mlsp* binaries with accepted naming variants.
3. Pick latest by modification time.
4. Fallback to mlsp.exe on Windows or mlsp elsewhere.

Code path:

• resolveLanguageServerCommandFromInputs
• findLatestServerBinary
• isLanguageServerBinaryName

9.2 Crash-loop mitigation

The extension tracks crash timestamps in a rolling window:

• window: 3 minutes
• block threshold: 5 crashes in window

When threshold is reached:

• automatic restart is disabled
• user is prompted to run manual restart command

Code path:

• recordCrashAndGetStatus
• language client errorHandler.closed

9.3 Commands exposed

Declared in mutant-vscode-extension/package.json, implemented in mutant-vscode-extension/src/extension.ts:

• Mutant: Open Smoke File
• Mutant: Run LSP Smoke Checks
• Mutant: Show LSP Status
• Mutant: Show LSP Logs
• Mutant: Restart LSP
• Mutant: Copy LSP Logs

10. Deterministic Behavior Rules

Determinism safeguards already in codebase:

• Completion ordering is canonicalized and stable (category + label + kind + explicit SortText).
• Node selection tie-breaks use deterministic specificity logic.
• Workspace symbol ordering is sorted by name/location.
• Rename edits are sorted by range per file before response.

These rules reduce editor flicker and test flakiness.

11. Testing Strategy

11.1 Server tests

• File: lsp/internal/server/server_test.go
• Covers initialization capabilities, diagnostics, completion, hover, references, formatting, semantic tokens, rename, configuration behavior, and regressions.

11.2 Analyzer tests

• File: lsp/internal/analyzer/analyzer_test.go
• Includes semantic robustness and builtin teaching coverage regression checks.

11.3 Extension integration tests

• File: mutant-vscode-extension/src/test/suite/extension.test.ts
• Covers activation, command registration, crash backoff, binary selection, and config override behavior.

12. Change Playbooks

12.1 Add a new LSP feature

1. Add capability advertisement in initialize if needed.
2. Add server handler in constructor wiring.
3. Implement method in server layer.
4. Add analyzer APIs if semantic analysis is needed.
5. Add tests in server/analyzer test suites.
6. Add extension-side UX command only if user-facing operation is needed.

12.2 Add a new builtin function

1. Register builtin in builtin/builtin.go (append-only; see the 4 touch-points: names.go const, builtin.go slice, impl func, metadata.go doc).
2. Add a rich doc entry to the builtinDocs map in builtin/metadata.go (required — a meta-test enforces per-function docs). The LSP reads hover/signature/completion docs from here.
3. If the builtin is platform-constrained, set platforms (supported GOOS set) and/or platformNote on its builtinDoc; the platformSupport diagnostic and hover pick it up automatically. Its capability category is derived from the name prefix in CapabilityCategory (extend capabilityCategories if it is a new family).
4. Run analyzer/server tests. Existing regression tests verify baseline completion/hover/signature coverage for all builtins.

12.3 Add a new lint rule

1. Implement lint function in lsp/internal/analyzer/diagnostics.go.
2. Add config field to LintConfig and severity parser in lsp/internal/server/lint_config.go.
3. Expose setting in mutant-vscode-extension/package.json.
4. Add tests for default severity, override, and off behavior.

12.4 Add or change extension setting

1. Add schema entry under contributes.configuration.properties in mutant-vscode-extension/package.json.
2. Read/consume in mutant-vscode-extension/src/extension.ts.
3. Add integration test in mutant-vscode-extension/src/test/suite/extension.test.ts.
4. Document in mutant-vscode-extension/README.md and troubleshooting docs.

13. Build, Run, and Debug

LSP/server tests:

• go test ./lsp/internal/server -v
• go test ./lsp/internal/analyzer -v
• go test ./...

Extension:

• cd vscode-extension
• npm install
• npm run compile
• npm test
• Launch Extension Development Host with VS Code F5

Operational debugging:

• Use Mutant: Show LSP Status
• Use Mutant: Show LSP Logs
• Use Mutant: Copy LSP Logs
• Use Mutant: Restart LSP for manual recovery

14. Known Design Trade-offs

• Current formatter chooses preservation for comments/blank-line input rather than forcing full AST rewrite, to avoid destructive edits.
• Workspace reference fallback focuses on top-level symbols for predictable and performant cross-document behavior.
• Semantic token failures degrade gracefully to empty token data instead of hard-failing language services.

15. Related Docs

• docs/LSP_EXTENSION_ONBOARDING_60_MIN.md
• docs/MUTANT_LANGUAGE_REFERENCE.md
• docs/CAPABILITY_REFERENCE.md