ibex 0.1.0 → 0.3.0

data/lib/ibex/lsp/position_codec.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Ibex
+  module LSP
+    # @rbs!
+    #   type lsp_value = String | Integer | Float | bool | nil | Array[lsp_value] | Hash[String, lsp_value]
+    #   type lsp_object = Hash[String, lsp_value]
+
+    # Converts between frontend byte offsets and zero-based LSP UTF-16 positions.
+    class PositionCodec
+      # @rbs (String source) -> void
+      def initialize(source)
+        @source = Frontend::SourceEncoding.validated_utf8(source, "(lsp)")
+        @line_starts = build_line_starts.freeze #: Array[Integer]
+      end
+
+      # @rbs (Integer byte_offset) -> Hash[String, Integer]
+      def position(byte_offset)
+        validate_byte_offset(byte_offset)
+        prefix = @source.byteslice(0, byte_offset) || ""
+        raise ArgumentError, "byte offset is not on a UTF-8 character boundary" unless prefix.valid_encoding?
+
+        line = (@line_starts.bsearch_index { |start| start > byte_offset } || @line_starts.length) - 1
+        line_start = @line_starts.fetch(line)
+        line_end = content_end(line)
+        raise ArgumentError, "byte offset points inside a line ending" if byte_offset > line_end
+
+        text = @source.byteslice(line_start, byte_offset - line_start) || ""
+        { "line" => line, "character" => utf16_length(text) }
+      end
+
+      # @rbs (lsp_object position) -> Integer
+      def byte_offset(position)
+        line = integer_member(position, "line")
+        character = integer_member(position, "character")
+        raise ArgumentError, "line and character must be non-negative" if line.negative? || character.negative?
+
+        line_start = @line_starts[line]
+        raise ArgumentError, "line is outside the document" unless line_start
+
+        text = @source.byteslice(line_start, content_end(line) - line_start) || ""
+        line_start + byte_length_at_utf16(text, character)
+      end
+
+      # @rbs (Frontend::SourceSpan span) -> Hash[String, Hash[String, Integer]]
+      def range(span)
+        { "start" => position(span.start_byte), "end" => position(span.end_byte) }
+      end
+
+      private
+
+      # @rbs () -> Array[Integer]
+      def build_line_starts
+        starts = [0]
+        offset = 0
+        @source.each_char do |character|
+          offset += character.bytesize
+          starts << offset if character == "\n"
+        end
+        starts
+      end
+
+      # @rbs (Integer line) -> Integer
+      def content_end(line)
+        boundary = @line_starts[line + 1] || @source.bytesize
+        return boundary unless @line_starts[line + 1]
+
+        before_newline = boundary - 1
+        @source.getbyte(before_newline - 1) == 13 ? before_newline - 1 : before_newline
+      end
+
+      # @rbs (String text) -> Integer
+      def utf16_length(text)
+        text.each_codepoint.sum { |codepoint| codepoint > 0xFFFF ? 2 : 1 }
+      end
+
+      # @rbs (String text, Integer units) -> Integer
+      def byte_length_at_utf16(text, units)
+        consumed_units = 0
+        consumed_bytes = 0
+        text.each_char do |character|
+          return consumed_bytes if consumed_units == units
+
+          width = character.ord > 0xFFFF ? 2 : 1
+          if consumed_units + width > units
+            raise ArgumentError, "character points into the middle of a UTF-16 surrogate pair"
+          end
+
+          consumed_units += width
+          consumed_bytes += character.bytesize
+        end
+        return consumed_bytes if consumed_units == units
+
+        raise ArgumentError, "character is outside the document line"
+      end
+
+      # @rbs (lsp_object position, String name) -> Integer
+      def integer_member(position, name)
+        value = position[name]
+        raise ArgumentError, "#{name} must be an integer" unless value.is_a?(Integer)
+
+        value
+      end
+
+      # @rbs (Integer byte_offset) -> void
+      def validate_byte_offset(byte_offset)
+        return if byte_offset.is_a?(Integer) && byte_offset.between?(0, @source.bytesize)
+
+        raise ArgumentError, "byte offset is outside the document"
+      end
+    end
+  end
+end

data/lib/ibex/lsp/protocol_error.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Ibex
+  module LSP
+    # Resource bounds shared by transport and open-document validation.
+    module Limits
+      MAX_HEADER_BYTES = 16 * 1024
+      MAX_MESSAGE_BYTES = 1024 * 1024
+      MAX_DOCUMENT_BYTES = 2 * 1024 * 1024
+      MAX_OUTPUT_BYTES = 1024 * 1024
+      MAX_ERROR_MESSAGE_CHARACTERS = 1024
+      MAX_REQUEST_ID_BYTES = 256
+    end
+
+    # Bounded protocol and workspace failures with their JSON-RPC error code.
+    class ProtocolError < Ibex::Error
+      attr_reader :code #: Integer
+      attr_reader :request_id #: String | Integer | nil
+      attr_reader :fatal #: bool
+
+      # @rbs (String message, ?code: Integer, ?request_id: String | Integer | nil, ?fatal: bool) -> void
+      def initialize(message, code: -32_600, request_id: nil, fatal: false)
+        normalized = message.encode(Encoding::UTF_8, invalid: :replace, undef: :replace)
+        bounded = normalized[0, Limits::MAX_ERROR_MESSAGE_CHARACTERS] || ""
+        bounded += "…" if bounded.length < normalized.length
+        super("(lsp):1:1: #{bounded}")
+        @code = code
+        @request_id = request_id
+        @fatal = fatal
+      end
+    end
+  end
+end

data/lib/ibex/lsp/request_handlers.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Ibex
+  module LSP
+    # Dispatches the finite LSP surface to focused lifecycle, document, and navigation handlers.
+    module RequestHandlers
+      include InitializationHandlers
+      include DocumentHandlers
+      include NavigationHandlers
+      include RequestSupport
+
+      HANDLERS = {
+        "initialize" => :initialize_workspace,
+        "initialized" => :initialized_notification,
+        "shutdown" => :shutdown_request,
+        "exit" => :exit_notification,
+        "textDocument/didOpen" => :did_open,
+        "textDocument/didChange" => :did_change,
+        "textDocument/didSave" => :did_save,
+        "textDocument/didClose" => :did_close,
+        "textDocument/definition" => :definition,
+        "textDocument/references" => :references,
+        "textDocument/prepareRename" => :prepare_rename,
+        "textDocument/rename" => :rename,
+        "textDocument/hover" => :hover,
+        "textDocument/completion" => :completion,
+        "$/cancelRequest" => :cancel_request
+      }.freeze #: Hash[String, Symbol]
+
+      private
+
+      # @rbs (String method, lsp_value? params) -> lsp_value?
+      def dispatch(method, params)
+        handler = HANDLERS[method]
+        raise ProtocolError.new("method not found: #{method}", code: -32_601) unless handler
+
+        send(handler, params)
+      end
+
+      # @rbs (lsp_value? params) -> nil
+      def cancel_request(_params)
+        nil
+      end
+    end
+  end
+end

data/lib/ibex/lsp/request_support.rb

@@ -0,0 +1,94 @@
+# 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)
+          } #: lsp_object
+          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 (lsp_value? value) -> lsp_object
+      def params_hash(value)
+        return {} if value.nil?
+
+        if value.is_a?(Hash)
+          result = value #: lsp_object
+          return result
+        end
+
+        raise ProtocolError.new("params must be an object", code: -32_602)
+      end
+
+      # @rbs (lsp_object value, String name) -> lsp_object
+      def hash_member(value, name)
+        member = value[name]
+        if member.is_a?(Hash)
+          result = member #: lsp_object
+          return result
+        end
+
+        raise ProtocolError.new("#{name} must be an object", code: -32_602)
+      end
+
+      # @rbs (lsp_object 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 (lsp_object 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,148 @@
+# 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 textDocument/completion
+      ].freeze #: Array[String]
+      NOTIFICATION_METHODS = %w[
+        initialized exit textDocument/didOpen textDocument/didChange textDocument/didSave textDocument/didClose
+        $/cancelRequest
+      ].freeze #: Array[String]
+
+      # @rbs (stdin: Transport::_Input, stdout: Transport::_Output, stderr: Object?) -> 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 () -> lsp_object?
+      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 (lsp_object 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") #: String
+        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 (lsp_object message) -> (String | Integer)?
+      def safe_request_id(message)
+        value = message["id"]
+        return unless value.is_a?(String) || value.is_a?(Integer)
+
+        value if valid_request_id?(value)
+      end
+
+      # @rbs (lsp_object 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 (lsp_object 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 (request_id.is_a?(String) || request_id.is_a?(Integer)) && 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 (Object? 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, lsp_value 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, [Integer?, String]?]
+      end
+
+      # @rbs (String path, lsp_object position) -> Array[lsp_object]
+      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, lsp_object position, ?include_declaration: bool) -> Array[lsp_object]
+      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, lsp_object position) -> lsp_object?
+      def prepare_rename(path, position)
+        occurrence = renameable_occurrence(path, position)
+        { "range" => range(occurrence), "placeholder" => occurrence.name }
+      end
+
+      # @rbs (String path, lsp_object position, String new_name) -> lsp_object
+      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, lsp_object position) -> lsp_object?
+      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, lsp_object 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 (symbol_key key, ?role: Symbol?) -> Array[SymbolOccurrence]
+      def matching(key, role: nil)
+        @occurrences.select { |entry| entry.key == key && (!role || entry.role == role) }
+      end
+
+      # @rbs (SymbolOccurrence occurrence) -> lsp_object
+      def location(occurrence)
+        { "uri" => @store.uri_for(occurrence.path), "range" => range(occurrence) }
+      end
+
+      # @rbs (SymbolOccurrence occurrence) -> lsp_object
+      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, lsp_object 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])
+          precedence_data = precedence #: Hash[Symbol, symbol_data_value]
+          lines << "Precedence: #{precedence_data[:associativity]} level #{precedence_data[:level]}"
+        end
+        lines.join("\n\n")
+      end
+    end
+  end
+end