ibex 0.1.0 → 0.2.0

data/lib/ibex/lsp/request_support.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Ibex
+  module LSP
+    # Shared publication, state, and parameter validation for request handlers.
+    module RequestSupport
+      private
+
+      # @rbs (Array[DocumentStore::publication] publications) -> void
+      def publish(publications)
+        publications.each do |publication|
+          version = publication[:version]
+          next if version && stale_publication?(publication.fetch(:uri), version)
+
+          params = {
+            "uri" => publication.fetch(:uri),
+            "diagnostics" => publication.fetch(:diagnostics)
+          } #: Hash[String, untyped]
+          params["version"] = version if version
+          @transport.write_message(
+            "jsonrpc" => "2.0", "method" => "textDocument/publishDiagnostics", "params" => params
+          )
+        end
+      end
+
+      # @rbs (String uri, Integer version) -> bool
+      def stale_publication?(uri, version)
+        path = workspace.path(uri)
+        store.snapshot_for(path)&.fetch(:version) != version
+      end
+
+      # @rbs (untyped value) -> Hash[String, untyped]
+      def params_hash(value)
+        return {} if value.nil?
+        return value if value.is_a?(Hash)
+
+        raise ProtocolError.new("params must be an object", code: -32_602)
+      end
+
+      # @rbs (Hash[String, untyped] value, String name) -> Hash[String, untyped]
+      def hash_member(value, name)
+        member = value[name]
+        return member if member.is_a?(Hash)
+
+        raise ProtocolError.new("#{name} must be an object", code: -32_602)
+      end
+
+      # @rbs (Hash[String, untyped] value, String name) -> String
+      def string_member(value, name)
+        member = value[name]
+        return member if member.is_a?(String)
+
+        raise ProtocolError.new("#{name} must be a string", code: -32_602)
+      end
+
+      # @rbs (Hash[String, untyped] value, String name) -> Integer
+      def integer_member(value, name)
+        member = value[name]
+        return member if member.is_a?(Integer)
+
+        raise ProtocolError.new("#{name} must be an integer", code: -32_602)
+      end
+
+      # @rbs (Symbol state) -> void
+      def require_state!(state)
+        return if @state == state
+
+        raise ProtocolError.new("request requires #{state} server state", code: -32_600)
+      end
+
+      # @rbs () -> void
+      def require_running!
+        require_state!(:running)
+      end
+
+      # @rbs () -> DocumentStore
+      def store
+        @store || raise(ProtocolError.new("server is not initialized", code: -32_002))
+      end
+
+      # @rbs () -> Workspace
+      def workspace
+        @workspace || raise(ProtocolError.new("server is not initialized", code: -32_002))
+      end
+    end
+  end
+end

data/lib/ibex/lsp/server.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+module Ibex
+  module LSP
+    # Coordinates JSON-RPC lifecycle, request responses, and protocol-safe logging.
+    class Server
+      include RequestHandlers
+
+      REQUEST_METHODS = %w[
+        initialize shutdown textDocument/definition textDocument/references textDocument/prepareRename
+        textDocument/rename textDocument/hover
+      ].freeze #: Array[String]
+      NOTIFICATION_METHODS = %w[
+        initialized exit textDocument/didOpen textDocument/didChange textDocument/didSave textDocument/didClose
+        $/cancelRequest
+      ].freeze #: Array[String]
+
+      # @rbs (stdin: untyped, stdout: untyped, stderr: untyped) -> void
+      def initialize(stdin:, stdout:, stderr:)
+        @transport = Transport.new(stdin, stdout)
+        @stderr = stderr
+        @state = :uninitialized
+        @exit_requested = false
+        @exit_status = nil #: Integer?
+      end
+
+      # @rbs () -> Integer
+      def run
+        until @exit_requested
+          message = read_message
+          break unless message
+
+          process_message(message)
+        end
+        @exit_status || 1
+      end
+
+      private
+
+      # @rbs () -> Hash[String, untyped]?
+      def read_message
+        @transport.read_message
+      rescue ProtocolError => e
+        send_error(nil, e)
+        @exit_requested = true if e.fatal
+        retry unless e.fatal
+        nil
+      end
+
+      # @rbs (Hash[String, untyped] message) -> void
+      def process_message(message)
+        request_id = safe_request_id(message)
+        notification = notification_envelope?(message)
+        request_id = validate_envelope(message)
+        method = message.fetch("method")
+        validate_message_kind!(method, message.key?("id"))
+        return if request_id.nil? && method.start_with?("$/")
+
+        validate_lifecycle!(method)
+        result = dispatch(method, message["params"])
+        send_result(request_id, result) if request_id
+      rescue ProtocolError => e
+        notification ? log(e.message) : send_error(request_id, e)
+      rescue StandardError => e
+        error = ProtocolError.new("internal error: #{e.message}", code: -32_603)
+        notification ? log(error.message) : send_error(request_id, error)
+      end
+
+      # @rbs (Hash[String, untyped] message) -> (String | Integer)?
+      def safe_request_id(message)
+        value = message["id"]
+        value if valid_request_id?(value)
+      end
+
+      # @rbs (Hash[String, untyped] message) -> bool
+      def notification_envelope?(message)
+        !message.key?("id") && message["jsonrpc"] == "2.0" && message["method"].is_a?(String)
+      end
+
+      # @rbs (String method, bool request) -> void
+      def validate_message_kind!(method, request)
+        if REQUEST_METHODS.include?(method) && !request
+          raise ProtocolError.new("#{method} must be a request", code: -32_600)
+        end
+        return unless NOTIFICATION_METHODS.include?(method) && request
+
+        raise ProtocolError.new("#{method} must be a notification", code: -32_600)
+      end
+
+      # @rbs (Hash[String, untyped] message) -> (String | Integer)?
+      def validate_envelope(message)
+        unless message["jsonrpc"] == "2.0" && message["method"].is_a?(String)
+          raise ProtocolError.new("invalid JSON-RPC request", code: -32_600)
+        end
+        return nil unless message.key?("id")
+
+        request_id = message["id"]
+        unless valid_request_id?(request_id)
+          raise ProtocolError.new("request id must be a bounded string or integer", code: -32_600)
+        end
+
+        request_id
+      end
+
+      # @rbs (untyped value) -> bool
+      def valid_request_id?(value)
+        return false unless value.is_a?(String) || value.is_a?(Integer)
+
+        value.to_s.bytesize <= Limits::MAX_REQUEST_ID_BYTES
+      end
+
+      # @rbs (String method) -> void
+      def validate_lifecycle!(method)
+        return if method == "exit"
+        return if @state == :uninitialized && method == "initialize"
+        return if @state == :initialized && %w[initialized shutdown].include?(method)
+        return if @state == :running
+
+        code = @state == :uninitialized ? -32_002 : -32_600
+        raise ProtocolError.new("request is invalid in #{@state} server state", code: code)
+      end
+
+      # @rbs (String | Integer request_id, untyped result) -> void
+      def send_result(request_id, result)
+        @transport.write_message("jsonrpc" => "2.0", "id" => request_id, "result" => result)
+      rescue ProtocolError => e
+        send_error(request_id, e)
+      end
+
+      # @rbs (String | Integer | nil request_id, ProtocolError error) -> void
+      def send_error(request_id, error)
+        @transport.write_message(
+          "jsonrpc" => "2.0", "id" => request_id,
+          "error" => { "code" => error.code, "message" => error.message }
+        )
+      rescue ProtocolError => e
+        log(e.message)
+      end
+
+      # @rbs (String message) -> void
+      def log(message)
+        @stderr.puts(message)
+      end
+    end
+  end
+end

data/lib/ibex/lsp/symbol_index.rb

@@ -0,0 +1,241 @@
+# frozen_string_literal: true
+
+module Ibex
+  module LSP
+    # Answers source navigation and guarded workspace rename operations.
+    class SymbolIndex
+      IDENTIFIER = /\A[A-Za-z_][A-Za-z0-9_]*\z/ #: Regexp
+      RESERVED = %w[
+        class fragment include token prechigh preclow left right nonassoc options expect start
+        recover sync on_error_reduce convert display type pragma extended rule end
+        separated_list separated_nonempty_list
+      ].freeze #: Array[String]
+
+      # @rbs (DocumentStore store, String path) -> void
+      def initialize(store, path)
+        @store = store
+        @path = path
+        files = store.files_for(path)
+        @occurrences, @documents = SymbolIndexBuilder.new(store, files).build
+        @snapshot_state = files.to_h do |file|
+          snapshot = store.snapshot_for(file)
+          [file, snapshot && [snapshot.fetch(:version), snapshot.fetch(:source)]]
+        end #: Hash[String, Array[untyped]?]
+      end
+
+      # @rbs (String path, Hash[String, untyped] position) -> Array[Hash[String, untyped]]
+      def definition(path, position)
+        occurrence = occurrence_at(path, position)
+        return [] unless occurrence
+        return [include_target_location(occurrence)] if occurrence.kind == :include
+
+        matching(occurrence.key, role: :definition).map { |entry| location(entry) }
+      end
+
+      # @rbs (String path, Hash[String, untyped] position, ?include_declaration: bool) ->
+      #   Array[Hash[String, untyped]]
+      def references(path, position, include_declaration: false)
+        occurrence = occurrence_at(path, position)
+        return [] unless occurrence
+
+        entries = matching(occurrence.key)
+        entries = entries.reject { |entry| entry.role == :definition } unless include_declaration
+        entries.map { |entry| location(entry) }
+      end
+
+      # @rbs (String path, Hash[String, untyped] position) -> Hash[String, untyped]?
+      def prepare_rename(path, position)
+        occurrence = renameable_occurrence(path, position)
+        { "range" => range(occurrence), "placeholder" => occurrence.name }
+      end
+
+      # @rbs (String path, Hash[String, untyped] position, String new_name) -> Hash[String, untyped]
+      def rename(path, position, new_name)
+        ensure_fresh!
+        occurrence = renameable_occurrence(path, position)
+        validate_new_name(occurrence, new_name)
+        entries = matching(occurrence.key)
+        validate_unshared(entries)
+        validate_nonoverlapping(entries)
+        changes = entries.group_by(&:path).transform_values do |path_entries|
+          path_entries.sort_by { |entry| entry.span.start_byte }.map do |entry|
+            { "range" => range(entry), "newText" => new_name }
+          end
+        end
+        replacements = changed_sources(entries, new_name)
+        unless @store.valid_replacements?(replacements)
+          raise ProtocolError.new("rename would make the affected grammar closure invalid", code: -32_602)
+        end
+
+        document_changes = changes.sort.map do |changed_path, edits|
+          snapshot = @store.snapshot_for(changed_path)
+          version = snapshot&.fetch(:open) ? snapshot.fetch(:version) : nil
+          {
+            "textDocument" => { "uri" => @store.uri_for(changed_path), "version" => version },
+            "edits" => edits
+          }
+        end
+        { "documentChanges" => document_changes }
+      end
+
+      # @rbs (String path, Hash[String, untyped] position) -> Hash[String, untyped]?
+      def hover(path, position)
+        occurrence = occurrence_at(path, position)
+        return unless occurrence
+
+        value = hover_value(occurrence)
+        return unless value
+
+        {
+          "contents" => { "kind" => "markdown", "value" => value },
+          "range" => range(occurrence)
+        }
+      end
+
+      private
+
+      # @rbs (String path, Hash[String, untyped] position) -> SymbolOccurrence?
+      def occurrence_at(path, position)
+        document = @documents[path]
+        return unless document
+
+        offset = PositionCodec.new(document.source).byte_offset(position)
+        candidates = @occurrences.select do |entry|
+          entry.path == path && entry.span.start_byte <= offset && offset < entry.span.end_byte
+        end
+        candidates.min_by { |entry| entry.span.length }
+      end
+
+      # @rbs (Array[untyped] key, ?role: Symbol?) -> Array[SymbolOccurrence]
+      def matching(key, role: nil)
+        @occurrences.select { |entry| entry.key == key && (!role || entry.role == role) }
+      end
+
+      # @rbs (SymbolOccurrence occurrence) -> Hash[String, untyped]
+      def location(occurrence)
+        { "uri" => @store.uri_for(occurrence.path), "range" => range(occurrence) }
+      end
+
+      # @rbs (SymbolOccurrence occurrence) -> Hash[String, untyped]
+      def include_target_location(occurrence)
+        target = occurrence.data.fetch(:target)
+        point = { "line" => 0, "character" => 0 }
+        { "uri" => @store.uri_for(target), "range" => { "start" => point, "end" => point.dup } }
+      end
+
+      # @rbs (SymbolOccurrence occurrence) -> Hash[String, Hash[String, Integer]]
+      def range(occurrence)
+        document = @documents.fetch(occurrence.path)
+        PositionCodec.new(document.source).range(occurrence.span)
+      end
+
+      # @rbs (String path, Hash[String, untyped] position) -> SymbolOccurrence
+      def renameable_occurrence(path, position)
+        occurrence = occurrence_at(path, position)
+        unless occurrence && %i[rule terminal parameter].include?(occurrence.kind) &&
+               occurrence.name.match?(IDENTIFIER) && !RESERVED.include?(occurrence.name)
+          raise ProtocolError.new("symbol at position cannot be renamed", code: -32_602)
+        end
+        unless matching(occurrence.key, role: :definition).any?
+          raise ProtocolError.new("unresolved symbol cannot be renamed", code: -32_602)
+        end
+
+        occurrence
+      end
+
+      # @rbs (SymbolOccurrence occurrence, String new_name) -> void
+      def validate_new_name(occurrence, new_name)
+        unless new_name.is_a?(String) && new_name.match?(IDENTIFIER) && !RESERVED.include?(new_name)
+          raise ProtocolError.new("new name must be a non-reserved grammar identifier", code: -32_602)
+        end
+
+        collision = @occurrences.any? do |entry|
+          entry.role == :definition && entry.name == new_name && entry.key != occurrence.key &&
+            collision_scope?(entry, occurrence)
+        end
+        raise ProtocolError.new("rename collides with existing symbol #{new_name}", code: -32_602) if collision
+      end
+
+      # @rbs (SymbolOccurrence candidate, SymbolOccurrence occurrence) -> bool
+      def collision_scope?(candidate, occurrence)
+        return candidate.key.take(3) == occurrence.key.take(3) if occurrence.kind == :parameter
+
+        candidate.kind != :parameter
+      end
+
+      # @rbs (Array[SymbolOccurrence] entries) -> void
+      def validate_nonoverlapping(entries)
+        entries.group_by(&:path).each_value do |path_entries|
+          ordered = path_entries.sort_by { |entry| [entry.span.start_byte, entry.span.end_byte] }
+          overlap = (1...ordered.length).any? do |index|
+            ordered.fetch(index - 1).span.end_byte > ordered.fetch(index).span.start_byte
+          end
+          raise ProtocolError.new("rename contains overlapping source edits", code: -32_603) if overlap
+        end
+      end
+
+      # @rbs (Array[SymbolOccurrence] entries) -> void
+      def validate_unshared(entries)
+        return unless entries.any? { |entry| @store.roots_for(entry.path).length > 1 }
+
+        raise ProtocolError.new("rename affecting a fragment shared by multiple roots is ambiguous", code: -32_602)
+      end
+
+      # @rbs () -> void
+      def ensure_fresh!
+        stale = @snapshot_state.any? do |path, expected|
+          snapshot = @store.snapshot_for(path)
+          actual = snapshot && [snapshot.fetch(:version), snapshot.fetch(:source)]
+          actual != expected
+        end
+        raise ProtocolError.new("symbol snapshot is stale; retry the request", code: -32_602) if stale
+      end
+
+      # @rbs (Array[SymbolOccurrence] entries, String new_name) -> Hash[String, String]
+      def changed_sources(entries, new_name)
+        entries.group_by(&:path).to_h do |path, path_entries|
+          document = @documents.fetch(path)
+          source = document.source.dup
+          path_entries.sort_by { |entry| -entry.span.start_byte }.each do |entry|
+            prefix = source.byteslice(0, entry.span.start_byte) || ""
+            suffix = source.byteslice(entry.span.end_byte, source.bytesize - entry.span.end_byte) || ""
+            source = prefix + new_name + suffix
+          end
+          [path, source]
+        end
+      end
+
+      # @rbs (SymbolOccurrence occurrence) -> String?
+      def hover_value(occurrence)
+        case occurrence.kind
+        when :rule then rule_hover(occurrence)
+        when :terminal then terminal_hover(occurrence)
+        when :parameter then "`#{occurrence.name}` — formal parameter of `#{occurrence.data[:rule]}`"
+        when :include then "Includes `#{occurrence.data[:target]}`"
+        end
+      end
+
+      # @rbs (SymbolOccurrence occurrence) -> String
+      def rule_hover(occurrence)
+        definition = matching(occurrence.key, role: :definition).first
+        data = definition&.data || occurrence.data
+        lines = ["```ibex", data[:signature] || occurrence.name, "```"]
+        lines << data[:documentation] if data[:documentation]
+        lines.join("\n")
+      end
+
+      # @rbs (SymbolOccurrence occurrence) -> String
+      def terminal_hover(occurrence)
+        definition = matching(occurrence.key, role: :definition).first
+        data = definition&.data || occurrence.data
+        lines = ["`#{occurrence.name}` — terminal"]
+        lines << "Display: #{data[:display]}" if data[:display]
+        lines << "Type: `#{data[:type]}`" if data[:type]
+        if (precedence = data[:precedence])
+          lines << "Precedence: #{precedence[:associativity]} level #{precedence[:level]}"
+        end
+        lines.join("\n\n")
+      end
+    end
+  end
+end