How dynge/norgmaestro works
Project Type and Purpose
• That NorgMaestro is an LSP server designed to support Norg files.
• The purpose is to receive LSP messages from an editor/IDE client, process them via specialized handlers, and respond using defined RPC message formats.
• Emphasis should be on the messaging protocol, modular handlers, parsing subsystem, and the overall server orchestration.
Major Components
A. Language Server Core:
• Central component encapsulated in files like LanguageServer.cs and LanguageServerState.cs.
• Responsible for receiving LSP messages, managing server state, and coordinating the various subcomponents.
B. Method Handlers:
• Represented by the Methods folder (e.g., CompletionHandler.cs, HoverHandler.cs, InitializeHandler.cs).
• Each handler implements IMessageHandler to process specific LSP requests such as completion, hover, document save events, etc.
• HandlerFactory that determines which handler to use for an incoming message.
C. Parsing Subsystem:
• Located in the Parser directory.
• Components include NorgParser.cs and FileUtil.cs to help process Norg files.
• A subcomponent in the TS subdirectory (Treesitter.cs) indicates that Treesitter is used to parse the language’s grammar or syntax trees.
D. RPC Communication Layer:
• Found under the Rpc directory, which includes message classes for CallHierarchy, Completion, DidSave, and others.
• RpcMessageWriter.cs is an important connection point for serializing and sending responses.
• This layer abstracts the communication over the LSP protocol.
E. Entry Point:
• Program.cs which bootstraps the LanguageServer and sets up orchestrations possibly including dependency injection, initialization, etc.
F. Testing Suite:
• The tests folder (NorgMaestro.Tests) contains unit tests for critical components like the HandlerFactory and the RPC reader/writer implementations.
• Even if not part of the runtime architecture, tests verify that component interactions are correct.
Relationships and Data Flow
• The Client (IDE/editor) sends LSP messages to the LanguageServer.
• The LanguageServer (core) receives these messages and consults the HandlerFactory to route the message to an appropriate Method Handler.
• Each Method Handler processes the message (often using the Parser for syntactic analysis if needed) and then interacts with the RPC layer to send back responses.
• The RPC modules encapsulate the structure for requests/responses and handle the encoding/decoding of messages.
• Overall, the flow is: Client → LanguageServer Core → Handler Factory → Specific Method Handler → (Optional) Parser → RPC Layer → Client.
Architectural Patterns & Design Principles
• Modularity: Different directories for methods, parser, and RPC indicate separation of concerns.
• Factory Pattern: The HandlerFactory dynamically routes messages to the correct handler.
• Layered Architecture: An outer communication layer (RPC) interfaces with inner processing layers (handlers and parser).
• Interface-Driven Design: Use of interfaces (e.g., IMessageHandler) ensures handlers can be swapped or extended easily.