Moggi Language Server

The Moggi compiler is the language service: one long-lived process (PHP in a checkout or a PHP-bundling distribution, the native bin/moggi otherwise) owns typed AST, Merkle caches, export origins, doc comments/moogle, and a project-wide occurrence index (module-scoped binder ids + call edges).

php moggi.php lsp

Flags: --lib PATH (repeatable), --backend B (default php for LSP).

VS Code

Install the extension from moggi-lang/moggi-vscode-plugin. It starts this server from a compiler it finds — a checkout, or an installed distribution via moggi.serverPath. In an installation that bundles PHP that is <dist>/bin/moggi.phar; where PHP is not bundled (moggi-jvm, moggi-dotnet, moggi-minimal) the compiler archive is not shipped and the native compiler is the entry point: <dist>/bin/moggi lsp.

The server loads the compiler once, at startup, and keeps it: while you develop Moggi itself, an edit under src/ changes nothing until the server restarts, and the stale one keeps answering. It therefore watches its own revision (~6 ms on an idle tick) and says so when the sources move on — a warning naming the revision it is running and the one on disk, in the output log every time and once as a notification. Moggi: Restart Language Server applies the new compiler.

Capabilities

LSP 3.18 Feature Matrix

The Moggi language server implements the following LSP 3.18 features:

Initialization & Lifecycle

Server Capabilities

Workspace Features

Text Document Synchronization

Diagnostics

Semantic Tokens

Navigation Features

Code Intelligence

Code Editing

UI Features

Hierarchy

Protocol Compliance

VS Code Extension Support

Backend Support

Note: The LSP server always uses the PHP backend for analysis regardless of the target backend for code generation. The --lib flags can specify additional library paths for cross-backend development.

Records

A field name in Moggi belongs to its record, not to the module (there are no selector functions), so both record features start from the record’s type and look the label up inside it — which is what makes person.name and company.name two different fields rather than one ambiguous name.

• Completion inside { … } offers the record’s field labels and leaves out the ones already written. The record is the name in front of the brace: the constructor in Person { … }, or the receiver in p { … } — for the latter its type comes from the enclosing signature (renamed p = p { … } with renamed :: Person -> Person), for a where-bound helper from the enclosing function’s. This runs while the buffer does not parse — that is the state a record being written is in — so it reads the declaration from the source text once the parse tree has nothing to offer.
• Hover on a field label shows label :: Type, the record that declares it and where, for a projection (alice.name), a label the reader wrote in a construction or update (Person { name = … }, p { age = … }), a record pattern (Person { name = n }) and the label in the record declaration itself. Hovering the dot answers with the projection’s type; the label is one character in.
• Completion after . (alice.) lists the receiver’s fields, falling back to its nullary constructors, and keeps offering plain identifiers when the receiver’s type is unknown.

src/lsp/textdocument/records.php holds the shared record knowledge: declaration lookup by type or constructor name, field lists, and the type head of a record-valued expression.

Latency model

textDocument/didChange only updates the VFS and schedules a versioned typecheck (~200ms idle). Parse/lex diagnostics publish immediately via quickDiagnostics. The stdio loop uses stream_select timeouts so due analyzes flush between messages without threads. Stale versions are superseded; overlay writes skip when the content fingerprint is unchanged. When the client advertises window.workDoneProgress, due typechecks emit $/progress begin/end around the flush (plus moggi/status).

Architecture

┌─────────────────────────────────────────────────────────┐
│  AnalysisService (single process, owns PHP compiler)    │
│  VirtualFS → ProjectGraph → ModuleIndex                 │
│                      ↓                                  │
│              OccurrenceIndex (binder:Mod:id + edges)    │
│                      ↓                                  │
│  features / actions / format / tokens / hierarchy       │
└─────────────────────────────────────────────────────────┘
        │                              │
   stdio LSP                    VS Code extension
                                   ├─ status + $/progress
                                   ├─ Run (PHP) launch
                                   └─ Test Explorer

AnalysisService owns VirtualFS, ModuleIndex, OccurrenceIndex, and an optional DocIndex. Successful prepares reindex every checked module. Navigation prefers resolvedOrigin / backendResolved / externalFns; locals use binder:{Module}:{id}. Call edges are recorded at Apply / Infix sites.

Source layout under src/lsp/, where namespace = directory: protocol/ (framing, positions, messages), textdocument/ (one file per feature group: hover, navigation, symbols, completion, signature, semanticTokens, hints, color, formatting, rename, hierarchy, codeAction, codeLens, moniker, diagnostics), workspace/ (file operations, configuration, watched files), index/ (module index, occurrences, token map), analysis/ (service + VFS, analyzer, diagnostics) and formatter/; server.php is the stdio loop and dispatch only, capabilities.php is the one place a capability is named, lifecycle.php and sync.php shape the lifecycle and document-sync requests.

Capability ↔ dispatch drift is checked, not hoped away: capabilities.php’s capabilityDispatchMismatches() reports a handler without a capability and a capability without a handler, and the check runs in the test suite (tests/lsp/capability_drift_test.php).

Run vs debug

Not implemented: interactive Moggi debugging (step/break/locals) across backends.

What ships today:

• VS Code type moggi is labeled Moggi: Run (PHP): moggi compile --backend php, then php the artifact. Breakpoints are unverified (they never halt).
• Source maps still emit for exception stack mapping and a future DAP, but they no longer take the same shape per backend. On PHP each module carries its own const __MOGGI_MAP (positional, pre-resolved rows + a declaration-site table); the runtime reads it by the namespace of the frame’s function name, only when a frame from that module is reported, and nothing is decoded, registered or cached up front. On jvm/.NET the JSON .moggi.map is the packaging interchange: the packager parses it once and bakes moggi/rt/Frames / Moggi.Frames. An external consumer that wants a PHP module’s map must read the const out of the module source; no such reader exists yet (the JSON-only one was deleted together with the sidecar era), which is the open half of D-10.

Physical limits

• Host debugger required — maps alone cannot pause optimized code. PHP needs Xdebug; JVM needs JDWP; .NET needs netcoredbg. One DAP façade per backend; shared layer is Moggi sourcemaps only.
• Xdebug in nix — keep default php/moggi/runtest without Xdebug. A future php-debug wrapper would load the extension with xdebug.mode=debug only for DAP launch.
• Optimized IR — maps are built at backend emit from post-opt IR SrcLocs. Inlining, dict specialization, and folds can erase sites. A debug build will need -O0 / no-inline / retain dictionaries. Maps do not point at pre-opt IR.

Future debugger work

Per the Debug Adapter Protocol, the editor speaks to a debug adapter (launch/attach, setBreakpoints, configurationDone, stackTrace, scopes, variables, continue/next/stepIn in; initialized, stopped, output, terminated out); the adapter drives a real host debugger. That is a sibling of the LSP here, not a part of it, and none of it is implemented yet.

Formatter limits

The formatter pretty-prints from the AST and reattaches nearby -- line comments. Mid-expression comments may move; unparsable buffers fall back to whitespace normalization. Range formatting rewrites only intersecting top-level items (not a silent whole-file format). Comment-perfect formatting would need a comment-preserving CST.