rigortype 0.1.4 → 0.1.6

data/lib/rigor/language_server/server.rb

@@ -0,0 +1,384 @@
+# frozen_string_literal: true
+
+require_relative "../version"
+require_relative "buffer_table"
+
+module Rigor
+  module LanguageServer
+    # LSP server lifecycle state machine + JSON-RPC method dispatcher.
+    #
+    # Slice 1 (this commit) ships:
+    # - State machine: `:uninitialized` → `:initialized` → `:shutdown`
+    #   → `:exited`.
+    # - Three lifecycle handlers: `initialize`, `shutdown`, `exit`.
+    # - {#dispatch} which routes (method, params) to the matching
+    #   handler and returns the response payload (or `nil` for
+    #   notifications). Out-of-state requests return the
+    #   spec-defined `InvalidRequest` (-32002) / `MethodNotFound`
+    #   (-32601) error shapes.
+    #
+    # Slice 2 wraps this dispatcher in a stdio JSON-RPC reader /
+    # writer so the CLI subcommand can serve real LSP clients.
+    # Slice 3+ adds document sync; slice 4+ adds publishDiagnostics;
+    # slice 5-8 add the rest of the v1 capability surface.
+    class Server # rubocop:disable Metrics/ClassLength
+      # JSON-RPC error codes per LSP spec § "Response Message".
+      ERROR_PARSE_ERROR      = -32_700
+      ERROR_INVALID_REQUEST  = -32_600
+      ERROR_METHOD_NOT_FOUND = -32_601
+      ERROR_INVALID_PARAMS   = -32_602
+      ERROR_INTERNAL_ERROR   = -32_603
+      # LSP-specific reserved codes.
+      ERROR_SERVER_NOT_INITIALIZED = -32_002
+      ERROR_INVALID_REQUEST_AFTER_SHUTDOWN = -32_600
+
+      # `TextDocumentSyncKind::Full = 1`. Slice 10 (deferred)
+      # promotes to `Incremental = 2`.
+      TEXT_DOCUMENT_SYNC_FULL = 1
+
+      # Methods callable BEFORE `initialize`. Per LSP spec § 3 only
+      # `initialize` and `exit` are allowed pre-initialization; every
+      # other request returns `ServerNotInitialized`. We also accept
+      # `shutdown` so a sequence like `initialize → shutdown → exit`
+      # (the conformance harness) round-trips even when the client
+      # skips real work.
+      PRE_INITIALIZE_METHODS = %w[initialize shutdown exit].freeze
+
+      attr_reader :state, :exit_code, :buffer_table, :publisher,
+                  :hover_provider, :document_symbol_provider, :completion_provider,
+                  :signature_help_provider, :folding_range_provider,
+                  :selection_range_provider, :project_context
+
+      # @param completion_provider [Rigor::LanguageServer::CompletionProvider, nil]
+      #   resolves `textDocument/completion`. Nil → `MethodNotFound`.
+      # @param signature_help_provider [Rigor::LanguageServer::SignatureHelpProvider, nil]
+      #   resolves `textDocument/signatureHelp`. Nil → `MethodNotFound`.
+      # @param project_context [Rigor::LanguageServer::ProjectContext, nil]
+      #   the per-session cache of `Environment` + `Cache::Store`
+      #   the providers read on every request. When present,
+      #   `workspace/didChangeWatchedFiles` and
+      #   `workspace/didChangeConfiguration` invalidate the cache;
+      #   nil means "no project context", which is the slice 1-6
+      #   behaviour (each request rebuilds env from scratch).
+      def initialize(buffer_table: BufferTable.new, publisher: nil, # rubocop:disable Metrics/ParameterLists
+                     hover_provider: nil, document_symbol_provider: nil,
+                     completion_provider: nil, signature_help_provider: nil,
+                     folding_range_provider: nil, selection_range_provider: nil,
+                     project_context: nil)
+        @state = :uninitialized
+        @exit_code = nil
+        @buffer_table = buffer_table
+        @publisher = publisher
+        @hover_provider = hover_provider
+        @document_symbol_provider = document_symbol_provider
+        @completion_provider = completion_provider
+        @signature_help_provider = signature_help_provider
+        @folding_range_provider = folding_range_provider
+        @selection_range_provider = selection_range_provider
+        @project_context = project_context
+      end
+
+      # @return [Boolean] true once the client has called `exit` and
+      #   the server has set its terminal exit code. The CLI loop
+      #   reads this between dispatches to know when to stop.
+      def exited?
+        @state == :exited
+      end
+
+      # Routes one LSP method call.
+      #
+      # @param method [String] the LSP method name (e.g. "initialize").
+      # @param params [Hash, nil] the LSP `params` payload (Hash for
+      #   request / notification methods; nil for the empty case).
+      # @return [Hash, nil] one of:
+      #   - the response result Hash for request methods,
+      #   - nil for notification methods,
+      #   - { error: { code:, message: } } for state / shape errors.
+      def dispatch(method, params = nil) # rubocop:disable Metrics/CyclomaticComplexity
+        return state_violation_response(method) unless method_allowed_in_state?(method)
+
+        case method
+        when "initialize"             then handle_initialize(params)
+        when "initialized"            then handle_initialized
+        when "shutdown"               then handle_shutdown
+        when "exit"                   then handle_exit
+        when "textDocument/didOpen"   then handle_did_open(params)
+        when "textDocument/didChange" then handle_did_change(params)
+        when "textDocument/didClose"  then handle_did_close(params)
+        when "textDocument/hover"               then handle_hover(params)
+        when "textDocument/documentSymbol"      then handle_document_symbol(params)
+        when "textDocument/completion"          then handle_completion(params)
+        when "textDocument/signatureHelp"       then handle_signature_help(params)
+        when "textDocument/foldingRange"        then handle_folding_range(params)
+        when "textDocument/selectionRange"      then handle_selection_range(params)
+        when "workspace/didChangeWatchedFiles"  then handle_did_change_watched_files(params)
+        when "workspace/didChangeConfiguration" then handle_did_change_configuration(params)
+        else
+          method_not_found(method)
+        end
+      end
+
+      private
+
+      def method_allowed_in_state?(method)
+        case @state
+        when :uninitialized then PRE_INITIALIZE_METHODS.include?(method)
+        when :initialized   then method != "initialize"
+        when :shutdown      then method == "exit"
+        when :exited        then false
+        end
+      end
+
+      def state_violation_response(method)
+        case @state
+        when :uninitialized
+          rpc_error(
+            ERROR_SERVER_NOT_INITIALIZED,
+            "method #{method.inspect} requires `initialize` first"
+          )
+        when :initialized
+          rpc_error(
+            ERROR_INVALID_REQUEST,
+            "method #{method.inspect} is not valid after `initialize` has succeeded"
+          )
+        when :shutdown
+          rpc_error(
+            ERROR_INVALID_REQUEST_AFTER_SHUTDOWN,
+            "method #{method.inspect} is not valid after `shutdown`; only `exit` is accepted"
+          )
+        when :exited
+          rpc_error(ERROR_INVALID_REQUEST, "server has exited")
+        end
+      end
+
+      # Per LSP spec § "Server lifecycle / initialize": the server
+      # responds with its capabilities. Each later slice extends
+      # `advertised_capabilities` with the handler it wires;
+      # clients asking for unadvertised methods get `MethodNotFound`.
+      def handle_initialize(_params)
+        @state = :initialized
+        {
+          capabilities: advertised_capabilities,
+          serverInfo: {
+            name: "rigor-lsp",
+            version: Rigor::VERSION
+          }
+        }
+      end
+
+      def advertised_capabilities
+        caps = {
+          textDocumentSync: {
+            openClose: true,
+            change: TEXT_DOCUMENT_SYNC_FULL
+          }
+        }
+        caps[:hoverProvider] = true if @hover_provider
+        caps[:documentSymbolProvider] = true if @document_symbol_provider
+        if @completion_provider
+          caps[:completionProvider] = {
+            # `.` for method completion; `:` for constant-path
+            # completion (slice 6). The server detects which form
+            # by looking one character back when `:` triggers.
+            triggerCharacters: [".", ":"],
+            # v1 eager — full payload returned on first request.
+            # Resolve becomes relevant if large enumerations
+            # (Object descendants) become noticeable.
+            resolveProvider: false
+          }
+        end
+        if @signature_help_provider
+          caps[:signatureHelpProvider] = {
+            # `(` opens the argument list; `,` advances to the
+            # next argument. Editors retrigger on both.
+            triggerCharacters: ["(", ","]
+          }
+        end
+        caps[:foldingRangeProvider] = true if @folding_range_provider
+        caps[:selectionRangeProvider] = true if @selection_range_provider
+        caps
+      end
+
+      # `initialized` is a notification — no response body. Slice 7
+      # will hook this to register `workspace/didChangeWatchedFiles`
+      # if the client advertised the capability.
+      def handle_initialized
+        nil
+      end
+
+      def handle_shutdown
+        @state = :shutdown
+        # Drop any in-flight debounced publishes so they don't
+        # fire after the client has stopped listening.
+        @publisher&.cancel_pending
+        nil
+      end
+
+      def handle_exit
+        @exit_code = @state == :shutdown ? 0 : 1
+        @state = :exited
+        nil
+      end
+
+      # textDocument/didOpen notification. Per LSP spec § the
+      # `textDocument` payload carries `uri`, `languageId`,
+      # `version`, and the full initial `text`. Triggers a
+      # `publishDiagnostics` push when a publisher is wired.
+      def handle_did_open(params)
+        doc = params.fetch(:textDocument)
+        uri = doc.fetch(:uri)
+        @buffer_table.open(
+          uri: uri,
+          bytes: doc.fetch(:text),
+          version: doc.fetch(:version)
+        )
+        @publisher&.publish_for(uri)
+        nil
+      end
+
+      # textDocument/didChange under FULL sync. Each `contentChanges`
+      # entry carries only `{ text: }`; the LAST entry is the new
+      # full document text. Per LSP spec § "FULL sync" the array
+      # MUST be exactly one entry in practice — we still take
+      # `.last` defensively for clients that pad. Triggers
+      # `publishDiagnostics` afterwards.
+      def handle_did_change(params)
+        doc = params.fetch(:textDocument)
+        changes = params.fetch(:contentChanges)
+        return nil if changes.empty?
+
+        uri = doc.fetch(:uri)
+        @buffer_table.change(
+          uri: uri,
+          bytes: changes.last.fetch(:text),
+          version: doc.fetch(:version)
+        )
+        @publisher&.publish_for(uri)
+        nil
+      end
+
+      # textDocument/hover REQUEST. Slice 5 returns either a
+      # `Hover` payload (markdown contents wrapping type +
+      # erased-RBS info) or nil when no expression is at the
+      # queried position. Nil maps to `result: null` per LSP
+      # spec; clients suppress the popup. Returns
+      # `MethodNotFound` when no hover_provider is wired (slice
+      # 1-4 behaviour).
+      def handle_hover(params)
+        return method_not_found("textDocument/hover") unless @hover_provider
+
+        doc = params.fetch(:textDocument)
+        pos = params.fetch(:position)
+        @hover_provider.provide(
+          uri: doc.fetch(:uri),
+          line: pos.fetch(:line),
+          character: pos.fetch(:character)
+        )
+      end
+
+      # workspace/didChangeWatchedFiles NOTIFICATION. Invalidates
+      # the ProjectContext so cached pre-pass / Environment is
+      # rebuilt on the next request. Slice 7's floor: any watched
+      # file change triggers a full context rebuild. Per-file
+      # surgical invalidation (per design doc § "Project context
+      # refresh") is a follow-up; this is the LSP-correct floor.
+      def handle_did_change_watched_files(_params)
+        @project_context&.invalidate!
+        nil
+      end
+
+      # workspace/didChangeConfiguration NOTIFICATION. The payload
+      # shape is client-specific; v1 ignores the payload and
+      # invalidates the context so the next read picks up any
+      # external config changes (.rigor.yml / Gemfile.lock / etc).
+      def handle_did_change_configuration(_params)
+        @project_context&.invalidate!
+        nil
+      end
+
+      # textDocument/selectionRange REQUEST. Routes to the
+      # selection-range provider when wired; `MethodNotFound`
+      # otherwise.
+      def handle_selection_range(params)
+        return method_not_found("textDocument/selectionRange") unless @selection_range_provider
+
+        doc = params.fetch(:textDocument)
+        positions = params.fetch(:positions)
+        @selection_range_provider.provide(doc.fetch(:uri), positions)
+      end
+
+      # textDocument/foldingRange REQUEST. Routes to the
+      # folding-range provider when wired; `MethodNotFound`
+      # otherwise.
+      def handle_folding_range(params)
+        return method_not_found("textDocument/foldingRange") unless @folding_range_provider
+
+        doc = params.fetch(:textDocument)
+        @folding_range_provider.provide(doc.fetch(:uri))
+      end
+
+      # textDocument/signatureHelp REQUEST. Routes to the
+      # signature-help provider when wired; `MethodNotFound`
+      # otherwise.
+      def handle_signature_help(params)
+        return method_not_found("textDocument/signatureHelp") unless @signature_help_provider
+
+        doc = params.fetch(:textDocument)
+        pos = params.fetch(:position)
+        context = params[:context]
+        @signature_help_provider.provide(
+          uri: doc.fetch(:uri),
+          line: pos.fetch(:line),
+          character: pos.fetch(:character),
+          context: context
+        )
+      end
+
+      # textDocument/completion REQUEST. Routes to the completion
+      # provider when wired; `MethodNotFound` otherwise.
+      def handle_completion(params)
+        return method_not_found("textDocument/completion") unless @completion_provider
+
+        doc = params.fetch(:textDocument)
+        pos = params.fetch(:position)
+        context = params[:context] || {}
+        @completion_provider.provide(
+          uri: doc.fetch(:uri),
+          line: pos.fetch(:line),
+          character: pos.fetch(:character),
+          trigger_character: context[:triggerCharacter]
+        )
+      end
+
+      # textDocument/documentSymbol REQUEST. Returns the
+      # `DocumentSymbol[]` outline for the buffer at the requested
+      # URI. Returns `MethodNotFound` when no provider is wired.
+      def handle_document_symbol(params)
+        return method_not_found("textDocument/documentSymbol") unless @document_symbol_provider
+
+        doc = params.fetch(:textDocument)
+        @document_symbol_provider.provide(doc.fetch(:uri))
+      end
+
+      # textDocument/didClose. Drops the buffer table entry AND
+      # publishes an empty diagnostic set so clients clear inline
+      # markers — per LSP spec § "publishDiagnostics" the standard
+      # way to indicate "no diagnostics remain for this URI".
+      def handle_did_close(params)
+        doc = params.fetch(:textDocument)
+        uri = doc.fetch(:uri)
+        @buffer_table.close(uri: uri)
+        @publisher&.publish_empty(uri)
+        nil
+      end
+
+      def method_not_found(method)
+        rpc_error(ERROR_METHOD_NOT_FOUND, "method not found: #{method.inspect}")
+      end
+
+      def rpc_error(code, message)
+        { error: { code: code, message: message } }
+      end
+    end
+  end
+end

data/lib/rigor/language_server/signature_help_provider.rb

@@ -0,0 +1,249 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "uri"
+require_relative "../environment"
+require_relative "../reflection"
+require_relative "../scope"
+require_relative "../source/node_locator"
+require_relative "../inference/scope_indexer"
+require_relative "../type/nominal"
+require_relative "../type/singleton"
+require_relative "../type/constant"
+require_relative "../type/refined"
+require_relative "../type/difference"
+require_relative "../type/tuple"
+require_relative "../type/hash_shape"
+
+module Rigor
+  module LanguageServer
+    # Answers `textDocument/signatureHelp` requests. When the user
+    # types `(` inside a method call (`obj.foo(|`) editors fire
+    # `signatureHelp` to show the method's parameter signature
+    # inline. The provider parses the buffer, locates the enclosing
+    # `CallNode`, infers the receiver's type, and returns the
+    # method's first overload as a `SignatureInformation`.
+    #
+    # Slice C1 (this commit) ships:
+    # - Sentinel patching for `obj.foo(|` so Prism's parse
+    #   succeeds (mirrors `CompletionProvider`'s slice B4 pattern).
+    # - First-overload signature only.
+    # - Active parameter = comma count before cursor.
+    #
+    # Multi-overload presentation + `documentation` field +
+    # active-parameter override per overload land in follow-up
+    # slices (queued in the design doc § "Out of scope for v2").
+    class SignatureHelpProvider
+      ARG_SENTINEL = "__rigor_lsp_arg_sentinel__"
+      private_constant :ARG_SENTINEL
+
+      def initialize(buffer_table:, project_context:)
+        @buffer_table = buffer_table
+        @project_context = project_context
+      end
+
+      # @return [Hash, nil] LSP `SignatureHelp` payload or nil
+      #   when the cursor isn't inside a resolvable method call.
+      def provide(uri:, line:, character:, context: nil)
+        _ = context # Trigger info accepted but not routed in v1.
+        path = Uri.to_path(uri)
+        return nil if path.nil?
+
+        entry = @buffer_table[uri]
+        return nil if entry.nil?
+
+        bytes, locate_at = parse_attempt_bytes(entry.bytes, line, character)
+        parse_result = Prism.parse(bytes, filepath: path,
+                                          version: @project_context.configuration.target_ruby)
+        return nil unless parse_result.errors.empty?
+
+        cursor_offset = byte_offset_for(bytes, locate_at[0], locate_at[1])
+        return nil if cursor_offset.nil?
+
+        call_node = enclosing_call_for_offset(parse_result.value, cursor_offset)
+        return nil if call_node.nil?
+
+        build_signature(call_node, parse_result.value, path, bytes, locate_at[0], locate_at[1])
+      end
+
+      private
+
+      def parse_attempt_bytes(original_bytes, line, character)
+        return [original_bytes, [line, character]] if Prism.parse(original_bytes).errors.empty?
+
+        patch_with_arg_sentinel(original_bytes, line, character)
+      end
+
+      # Mid-edit buffer at `obj.foo(|` or `obj.foo(1,|`: truncate
+      # everything from the cursor onwards and append `SENTINEL)`
+      # so the call is syntactically complete. The truncation is
+      # aggressive — signatureHelp only cares about the enclosing
+      # call's signature; downstream content (closing parens,
+      # subsequent statements) is irrelevant.
+      def patch_with_arg_sentinel(original_bytes, line, character)
+        prefix_offset = byte_offset_for(original_bytes, line, character)
+        return [original_bytes, [line, character]] if prefix_offset.nil?
+
+        prefix = original_bytes.byteslice(0, prefix_offset)
+        stripped = prefix.rstrip
+        return [original_bytes, [line, character]] unless stripped.end_with?("(") || stripped.end_with?(",")
+
+        patched = "#{prefix}#{ARG_SENTINEL})\n"
+        [patched, [line, character]]
+      end
+
+      # Walks the AST for the smallest CallNode whose `arguments`
+      # location encloses the cursor offset. Prism doesn't expose
+      # parent pointers, so NodeLocator's leaf-returning shape
+      # isn't enough; we re-walk. For LSP usage this is cheap —
+      # the buffer is parsed once per request.
+      def enclosing_call_for_offset(root, cursor_offset)
+        result = nil
+        walk = lambda do |n|
+          next unless n.is_a?(Prism::Node)
+
+          if n.is_a?(Prism::CallNode) && n.arguments && offset_in?(n.arguments.location, cursor_offset)
+            result = n # Innermost-wins because we keep walking children.
+          end
+          n.compact_child_nodes.each(&walk)
+        end
+        walk.call(root)
+        result
+      end
+
+      def offset_in?(location, offset)
+        offset.between?(location.start_offset, location.end_offset)
+      end
+
+      def build_signature(call_node, root, path, bytes, line, character)
+        scope_index = build_scope_index(root, path)
+        receiver_node = call_node.receiver
+        return nil if receiver_node.nil?
+
+        receiver_type = scope_index[receiver_node].type_of(receiver_node)
+        definition = lookup_method(receiver_type, call_node.name, scope_index[receiver_node])
+        return nil if definition.nil? || definition.method_types.empty?
+
+        active_param = active_parameter_index(call_node, bytes, line, character)
+        doc = rbs_documentation(definition)
+        signatures = definition.method_types.map do |method_type|
+          info = {
+            label: "#{call_node.name}#{method_type}",
+            parameters: parameter_information(method_type)
+          }
+          info[:documentation] = { kind: "markdown", value: doc } if doc
+          info
+        end
+        {
+          signatures: signatures,
+          # `activeSignature` is the index editors highlight by
+          # default. Slice C2 picks the first overload uniformly;
+          # a future slice could choose the overload that best
+          # matches the current argument shape.
+          activeSignature: 0,
+          activeParameter: active_param
+        }
+      end
+
+      # Builds the LSP `ParameterInformation[]` for a method type's
+      # parameter list. Each entry's `label` is a STRING form
+      # (e.g. `"::int width"`, `"?::string pad_string"`); LSP's
+      # offset-tuple form (`[start, end]`) for in-signature
+      # highlighting is queued. Order matches `activeParameter`'s
+      # index expectation: required positionals, then optionals,
+      # then rest, then trailing, then required keywords, then
+      # optional keywords, then rest keywords.
+      def parameter_information(method_type) # rubocop:disable Metrics/AbcSize
+        func = method_type.type
+        return [] unless func.respond_to?(:required_positionals)
+
+        params = func.required_positionals.map { |p| { label: format_param(p) } }
+        func.optional_positionals.each { |p| params << { label: "?#{format_param(p)}" } }
+        params << { label: "*#{format_param(func.rest_positionals)}" } if func.rest_positionals
+        func.trailing_positionals.each { |p| params << { label: format_param(p) } }
+        func.required_keywords.each { |name, p| params << { label: "#{name}: #{format_param(p)}" } }
+        func.optional_keywords.each { |name, p| params << { label: "?#{name}: #{format_param(p)}" } }
+        params << { label: "**#{format_param(func.rest_keywords)}" } if func.rest_keywords
+        params
+      end
+
+      def format_param(param)
+        param.name ? "#{param.type} #{param.name}" : param.type.to_s
+      end
+
+      # Identical contract to HoverRenderer#rbs_documentation —
+      # surfaces the method's RBS comment text or nil. Kept inline
+      # rather than extracted to a shared mixin because the two
+      # call sites are small and the shape may diverge (signatureHelp
+      # might want per-parameter docs split out; hover wants the
+      # full paragraph).
+      def rbs_documentation(definition)
+        comments = definition.respond_to?(:comments) ? definition.comments : nil
+        return nil if comments.nil? || comments.empty?
+
+        text = comments.map(&:string).join("\n\n").strip
+        text.empty? ? nil : text
+      end
+
+      def lookup_method(receiver_type, method_name, scope)
+        case receiver_type
+        when Type::Singleton
+          Reflection.singleton_method_definition(receiver_type.class_name, method_name, scope: scope)
+        when Type::Refined, Type::Difference
+          lookup_method(receiver_type.base, method_name, scope)
+        else
+          class_name = nominal_class_name(receiver_type)
+          return nil if class_name.nil?
+
+          Reflection.instance_method_definition(class_name, method_name, scope: scope)
+        end
+      end
+
+      # Mirrors CompletionProvider's receiver-type mapping. Tuple →
+      # Array, HashShape → Hash, Refined / Difference unwrap to
+      # their base (handled in `lookup_method` above for clarity).
+      def nominal_class_name(type)
+        case type
+        when Type::Nominal then type.class_name
+        when Type::Constant then type.value.class.name
+        when Type::Tuple then "Array"
+        when Type::HashShape then "Hash"
+        end
+      end
+
+      def build_scope_index(root, _path)
+        scope = Scope.empty(environment: @project_context.environment)
+        Inference::ScopeIndexer.index(root, default_scope: scope)
+      end
+
+      # Counts commas in the buffer between the call's opening `(`
+      # and the cursor position. Cursor on the first argument → 0;
+      # after one comma → 1; etc. Bounded by the call's arguments
+      # location so commas in nested expressions don't bleed in.
+      def active_parameter_index(call_node, bytes, line, character)
+        return 0 if call_node.arguments.nil?
+
+        cursor_offset = byte_offset_for(bytes, line, character)
+        args_loc = call_node.arguments.location
+        return 0 if args_loc.nil? || cursor_offset.nil?
+
+        scan_start = args_loc.start_offset
+        scan_end = [cursor_offset, args_loc.end_offset].min
+        return 0 if scan_end <= scan_start
+
+        bytes.byteslice(scan_start, scan_end - scan_start).count(",")
+      end
+
+      def byte_offset_for(bytes, line, character)
+        offset = 0
+        bytes.each_line.with_index do |line_bytes, idx|
+          return offset + character if idx == line
+
+          offset += line_bytes.bytesize
+        end
+        nil
+      end
+    end
+  end
+end

data/lib/rigor/language_server/synchronized_writer.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Rigor
+  module LanguageServer
+    # Wraps the LSP gem's `Io::Writer` with a Mutex so concurrent
+    # writes (the dispatch loop's response writes + the Debouncer's
+    # async `publishDiagnostics` writes) don't interleave on the
+    # shared STDOUT.
+    #
+    # Pass-through proxy: `#write(message)` is the only call site
+    # the rest of the LSP uses; `#close` is forwarded for
+    # completeness.
+    class SynchronizedWriter
+      def initialize(inner)
+        @inner = inner
+        @mutex = Mutex.new
+      end
+
+      def write(message)
+        @mutex.synchronize { @inner.write(message) }
+      end
+
+      def close
+        @mutex.synchronize { @inner.close }
+      end
+    end
+  end
+end