pikuri-lsp 0.1.0

data/lib/pikuri/lsp/operation.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Pikuri
+  module Lsp
+    # One value of the +lsp+ tool's +operation+ enum: what the model may ask for,
+    # which LSP request answers it, which capability the server must advertise
+    # first, and how the answer is rendered.
+    #
+    #   Operation['goToDefinition'].capability   # => "definitionProvider"
+    #   Operation['incomingCalls'].prepare       # => "textDocument/prepareCallHierarchy"
+    #   Operation.names.size                     # => 10
+    #
+    # Eight names are the surface three shipped harnesses converged on, kept
+    # verbatim so they match what a model has seen elsewhere; +goToTypeDefinition+
+    # and +supertypes+ are measured additions.
+    #
+    # == Static enum, gate at dispatch
+    #
+    # Capabilities are per *workspace*, not per binary ({ClientWrapper#supports?}),
+    # and two registered servers have different sets — so a schema computed from
+    # them would have to advertise the union anyway, and would move whenever a
+    # server restarted or a project gained a formatter. A moving tool description
+    # is worse than a static one the model can learn.
+    #
+    # == Three absences that are decisions
+    #
+    # Each looks like an obvious addition, so each is worth a line:
+    # +prepareCallHierarchy+ is out because exposing it hands the model an opaque
+    # +CallHierarchyItem+ to hold and echo back — the tool runs the prepare hop
+    # itself; +subtypes+ is out because +goToImplementation+ answers the same
+    # question transitively in one call on the one server whose +subtypes+ is not
+    # a +# TODO+ stub; and the write-side operations (rename, formatting, code
+    # actions) are what this gem refuses to become.
+    class Operation < Data.define(:name, :capability, :request, :prepare, :anchor, :shape, :cap, :summary)
+      # @param prepare [String, nil] omitted for a one-hop operation.
+      def initialize(name:, capability:, request:, anchor:, shape:, cap:, summary:, prepare: nil)
+        super
+      end
+
+      # @return [Boolean] whether results get the source/tests split. True for the
+      #   two operations whose volume is dominated by test files — 40 references
+      #   to one method were 4 call sites, 2 declarations and 34 spec hits, and the
+      #   4 are what the model asked for.
+      def grouped?
+        %w[findReferences incomingCalls].include?(name)
+      end
+
+      # Every operation, in the order the tool description lists them.
+      #
+      # @return [Array<Operation>]
+      ALL = [
+        new(name: 'goToDefinition', capability: 'definitionProvider',
+            request: 'textDocument/definition', anchor: :position, shape: :locations, cap: 20,
+            summary: 'where a name is defined. Several answers are normal — a reopened Ruby ' \
+                     'namespace and a dynamically dispatched method both have more than one.'),
+        new(name: 'findReferences', capability: 'referencesProvider',
+            request: 'textDocument/references', anchor: :position, shape: :locations, cap: 40,
+            summary: 'every use of a name, declarations included — textual uses of the ' \
+                     'name, not only calls of it.'),
+        new(name: 'hover', capability: 'hoverProvider', request: 'textDocument/hover',
+            anchor: :position, shape: :hover, cap: 1,
+            summary: 'the documentation and signature a server holds for a name — often the ' \
+                     'whole class comment, and the one operation that answers for a library ' \
+                     'symbol whose source is not on disk.'),
+        new(name: 'documentSymbol', capability: 'documentSymbolProvider',
+            request: 'textDocument/documentSymbol', anchor: :document, shape: :symbols, cap: 200,
+            summary: 'the outline of one file, filtered to `symbol` when it matches a row — ' \
+                     'the way to find a method the project-wide index does not hold.'),
+        new(name: 'workspaceSymbol', capability: 'workspaceSymbolProvider',
+            request: 'workspace/symbol', anchor: :query, shape: :symbols, cap: 25,
+            summary: 'search the server\'s whole index by name, which reaches inside ' \
+                     'dependencies; matching is fuzzy.'),
+        new(name: 'goToImplementation', capability: 'implementationProvider',
+            request: 'textDocument/implementation', anchor: :position, shape: :locations, cap: 25,
+            summary: 'what implements or overrides this — an interface to its implementors, a ' \
+                     'method to its overriders, and on some servers a class to every subclass ' \
+                     'below it.'),
+        new(name: 'goToTypeDefinition', capability: 'typeDefinitionProvider',
+            request: 'textDocument/typeDefinition', anchor: :position, shape: :locations, cap: 10,
+            summary: 'the *type* of an expression rather than its declaration — the only way ' \
+                     'to recover a type written nowhere in the source, as with an inferred local.'),
+        new(name: 'incomingCalls', capability: 'callHierarchyProvider',
+            prepare: 'textDocument/prepareCallHierarchy', request: 'callHierarchy/incomingCalls',
+            anchor: :position, shape: :calls, cap: 40,
+            summary: 'which functions call this one, resolved through the call graph rather ' \
+                     'than by name — narrower and more exact than findReferences.'),
+        new(name: 'outgoingCalls', capability: 'callHierarchyProvider',
+            prepare: 'textDocument/prepareCallHierarchy', request: 'callHierarchy/outgoingCalls',
+            anchor: :position, shape: :calls, cap: 40,
+            summary: 'what this calls, without reading the body.'),
+        new(name: 'supertypes', capability: 'typeHierarchyProvider',
+            prepare: 'textDocument/prepareTypeHierarchy', request: 'typeHierarchy/supertypes',
+            anchor: :position, shape: :supertypes, cap: 8,
+            summary: 'the ancestor chain of a class, walked level by level to the root — not ' \
+                     'the one level a definition hop on the superclass name would give.')
+      ].freeze
+
+      # @return [Hash{String => Operation}] {ALL} keyed by {#name}.
+      BY_NAME = ALL.to_h { |operation| [operation.name, operation] }.freeze
+
+      # @param name [String] an enum value.
+      # @return [Operation, nil] +nil+ for a name outside the enum, which
+      #   +Tool::Parameters+ refuses before this is reached.
+      def self.[](name)
+        BY_NAME[name]
+      end
+
+      # @return [Array<String>] every enum value, in {ALL}'s order — what the
+      #   tool's +operation+ parameter advertises.
+      def self.names
+        BY_NAME.keys
+      end
+    end
+  end
+end

data/lib/pikuri/lsp/position.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Pikuri
+  module Lsp
+    # One cursor position in pikuri's coordinates: 1-based line, 1-based
+    # character column — the same numbers +read+ and +grep+ print, so a
+    # rendered location needs no arithmetic and the model never sees an encoded
+    # offset in either direction.
+    #
+    # The wire is 0-based and code-unit-encoded, and this pair of calls is the
+    # only place that is true:
+    #
+    #   line = File.readlines('read.rb')[164]        # "    workspace.resolve_for_read(path)"
+    #   pos  = Position.new(line: 165, column: line.index('resolve_for_read') + 1)
+    #   pos.to_wire(line_text: line, encoding: PositionEncoding::UTF8)
+    #   # => {:line=>164, :character=>14}
+    #
+    #   Position.from_wire({ 'line' => 164, 'character' => 14 },
+    #                      line_text: line, encoding: PositionEncoding::UTF8).to_s
+    #   # => "165:15"
+    #
+    # @!attribute [r] line
+    #   @return [Integer] 1-based line number.
+    # @!attribute [r] column
+    #   @return [Integer] 1-based column, counted in characters (not bytes, not
+    #     UTF-16 code units).
+    Position = Data.define(:line, :column) do
+      # Parse LSP's +Position+ object.
+      #
+      # @param hash [Hash{String => Integer}] +{"line" =>, "character" =>}+,
+      #   0-based.
+      # @param line_text [String, nil] the target line's text; +nil+ costs
+      #   column exactness on a line with multi-unit characters, see
+      #   {PositionEncoding.column_for}.
+      # @param encoding [String] the server's negotiated +positionEncoding+.
+      # @return [Position]
+      # @raise [KeyError] if either wire field is missing.
+      def self.from_wire(hash, line_text: nil, encoding: PositionEncoding::DEFAULT)
+        new(line: Integer(hash.fetch('line')) + 1,
+            column: PositionEncoding.column_for(line_text, Integer(hash.fetch('character')), encoding))
+      end
+
+      # @raise [ArgumentError] if either coordinate is below 1 — a 0 means an
+      #   unconverted wire value leaked in, which is the bug this type exists
+      #   to prevent.
+      def initialize(line:, column:)
+        raise ArgumentError, "line must be >= 1, got #{line}" if line < 1
+        raise ArgumentError, "column must be >= 1, got #{column}" if column < 1
+
+        super
+      end
+
+      # Render as LSP's +Position+ object.
+      #
+      # @param line_text [String] the text of {#line}, required because the
+      #   column's encoding depends on the characters preceding it.
+      # @param encoding [String] the server's negotiated +positionEncoding+.
+      # @return [Hash{Symbol => Integer}] +{line:, character:}+, 0-based,
+      #   ready for +JSON.generate+.
+      # @raise [ArgumentError] if {#column} points past the end of +line_text+.
+      def to_wire(line_text:, encoding: PositionEncoding::DEFAULT)
+        { line: line - 1, character: PositionEncoding.offset_for(line_text, column, encoding) }
+      end
+
+      # @return [String] +"165:15"+ — the form a rendered location appends to a
+      #   path.
+      def to_s
+        "#{line}:#{column}"
+      end
+    end
+  end
+end

data/lib/pikuri/lsp/position_encoding.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module Pikuri
+  module Lsp
+    # LSP's +positionEncoding+ values and the offset arithmetic each one
+    # implies. A column is a *character* index inside pikuri and a code-unit
+    # offset on the wire; column 12 of the same line is three different numbers
+    # depending on who is asking:
+    #
+    #   line = 'x = "héllo🎉"'                        # 'é' is 2 bytes, '🎉' is 4
+    #   PositionEncoding.offset_for(line, 12, UTF32)  # => 11  (just 0-based)
+    #   PositionEncoding.offset_for(line, 12, UTF16)  # => 12  (the emoji counts twice)
+    #   PositionEncoding.offset_for(line, 12, UTF8)   # => 15
+    #   PositionEncoding.column_for(line, 12, UTF16)  # => 12  (round-trips)
+    #
+    # Converting in the wrong direction, or not at all, yields a *plausible*
+    # column — so the server answers confidently about the wrong token instead
+    # of failing. {DEFAULT} is what a server that negotiates nothing means.
+    module PositionEncoding
+      # Offsets count UTF-8 bytes. ruby-lsp accepts pikuri's offer of this.
+      UTF8 = 'utf-8'
+
+      # Offsets count UTF-16 code units, so an astral character (emoji, rare
+      # CJK) counts twice. jdtls ignores the offer and stays here.
+      UTF16 = 'utf-16'
+
+      # Offsets count codepoints, i.e. exactly pikuri's own columns.
+      UTF32 = 'utf-32'
+
+      # What a server that answers no +positionEncoding+ means: UTF-16 is the
+      # 3.17 default, and the conversion is therefore mandatory code rather
+      # than a fallback for a hypothetical server.
+      DEFAULT = UTF16
+
+      # Encodings pikuri offers in +general.positionEncodings+, best first.
+      # UTF-32 is out: no measured server offers it, and it would be one more
+      # branch nothing exercises.
+      OFFERED = [UTF8, UTF16].freeze
+
+      # Every value a caller may pass.
+      SUPPORTED = [UTF8, UTF16, UTF32].freeze
+
+      module_function
+
+      # Wire offset for a 1-based character column on +line_text+.
+      #
+      #   offset_for('def résolve', 8, UTF8)   # => 8  ("def rés" is 8 bytes)
+      #
+      # @param line_text [String] the line the column points into; a trailing
+      #   newline is harmless.
+      # @param column [Integer] 1-based character column, as {Position} holds it.
+      # @param encoding [String] one of {SUPPORTED}.
+      # @return [Integer] 0-based offset in that encoding's code units.
+      # @raise [ArgumentError] if +column+ is below 1, points past the end of
+      #   +line_text+ (pikuri derived a column its own line cannot hold — a bug
+      #   in the caller, not a server quirk), or +encoding+ is unknown.
+      def offset_for(line_text, column, encoding)
+        raise ArgumentError, "column must be >= 1, got #{column}" if column < 1
+
+        chars = column - 1
+        if chars > line_text.length
+          raise ArgumentError,
+                "column #{column} is past the end of a #{line_text.length}-character " \
+                "line: #{line_text.inspect}"
+        end
+
+        prefix = line_text[0, chars]
+        case encoding
+        when UTF32 then chars
+        when UTF8  then prefix.bytesize
+        when UTF16 then utf16_units(prefix)
+        else raise ArgumentError, "unknown positionEncoding #{encoding.inspect}"
+        end
+      end
+
+      # 1-based character column for a wire offset into +line_text+.
+      #
+      # An offset past the end of the line clamps to one-past-the-last
+      # character rather than raising: a range's +end+ legitimately sits there,
+      # and a server that overshoots is relayed, not fought.
+      #
+      # @param line_text [String, nil] the line the offset points into, or +nil+
+      #   when the text is not to hand — the offset is then read as a character
+      #   count, exact for an all-ASCII line and off by one per preceding
+      #   multi-unit character otherwise. Locations a server walked to arrive
+      #   this way, and only their line number gets rendered.
+      # @param offset [Integer] 0-based offset in +encoding+'s code units.
+      # @param encoding [String] one of {SUPPORTED}.
+      # @return [Integer] 1-based character column.
+      # @raise [ArgumentError] if +offset+ is negative or +encoding+ is unknown.
+      def column_for(line_text, offset, encoding)
+        raise ArgumentError, "offset must be >= 0, got #{offset}" if offset.negative?
+        raise ArgumentError, "unknown positionEncoding #{encoding.inspect}" unless SUPPORTED.include?(encoding)
+        return offset + 1 if line_text.nil? || encoding == UTF32
+
+        chars =
+          if encoding == UTF8
+            (line_text.byteslice(0, offset) || line_text).scrub.length
+          else
+            chars_before_utf16(line_text, offset)
+          end
+        chars + 1
+      end
+
+      # UTF-16 code units +str+ occupies.
+      #
+      # @param str [String]
+      # @return [Integer]
+      def utf16_units(str)
+        str.each_char.sum { |ch| ch.valid_encoding? && ch.ord > 0xFFFF ? 2 : 1 }
+      end
+
+      # Characters preceding a UTF-16 +offset+, clamped to the line's length.
+      def chars_before_utf16(line_text, offset)
+        units = 0
+        line_text.each_char.with_index do |ch, index|
+          return index if units >= offset
+
+          units += utf16_units(ch)
+        end
+        line_text.length
+      end
+      private_class_method :chars_before_utf16
+    end
+  end
+end

data/lib/pikuri/lsp/range.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Pikuri
+  module Lsp
+    # A span between two {Position}s, in pikuri's 1-based coordinates. Servers
+    # answer with ranges everywhere — a definition's whole body, an
+    # identifier's own extent, the slice of a class file worth showing — so
+    # this is mostly a parse target:
+    #
+    #   range = Range.from_wire({ 'start' => { 'line' => 12, 'character' => 6 },
+    #                             'end'   => { 'line' => 12, 'character' => 22 } },
+    #                           text: File.read(path), encoding: PositionEncoding::UTF8)
+    #   range.to_s         # => "13:7-13:23"
+    #   range.start.line   # => 13
+    #
+    # There is deliberately no +#to_wire+: pikuri sends positions (an anchor
+    # for a query), never ranges. The one client-to-server range in LSP is a
+    # +didChange+ edit, and pikuri re-sends +didOpen+ instead.
+    #
+    # Note the shadowing: inside +Pikuri::Lsp+, +Range+ is this class, so
+    # Ruby's own needs +::Range+.
+    #
+    # @!attribute [r] start
+    #   @return [Position] first position inside the span.
+    # @!attribute [r] end
+    #   @return [Position] one position *past* the span, LSP's half-open
+    #     convention, so a zero-width range has +start == end+.
+    Range = Data.define(:start, :end) do
+      # Parse LSP's +Range+ object.
+      #
+      # @param hash [Hash{String => Hash}] +{"start" =>, "end" =>}+.
+      # @param text [String, nil] the *whole* document the range points into,
+      #   which is what makes both columns exact; +nil+ when the text is not to
+      #   hand (see {PositionEncoding.column_for}).
+      # @param encoding [String] the server's negotiated +positionEncoding+.
+      # @return [Range]
+      # @raise [KeyError] if +start+ or +end+ is missing.
+      def self.from_wire(hash, text: nil, encoding: PositionEncoding::DEFAULT)
+        lines = text&.lines
+        wire_start = hash.fetch('start')
+        wire_end = hash.fetch('end')
+        new(start: Position.from_wire(wire_start, line_text: line_at(lines, wire_start), encoding: encoding),
+            end: Position.from_wire(wire_end, line_text: line_at(lines, wire_end), encoding: encoding))
+      end
+
+      # The text of the line a wire position sits on, or +nil+ when the
+      # document text was not supplied.
+      def self.line_at(lines, wire_position)
+        lines && lines[Integer(wire_position.fetch('line'))]
+      end
+      private_class_method :line_at
+
+      # @return [Boolean] whether the span begins and ends on one line, i.e.
+      #   whether a one-line snippet can show all of it.
+      def single_line?
+        start.line == self.end.line
+      end
+
+      # @return [String] +"13:7-13:23"+.
+      def to_s
+        "#{start}-#{self.end}"
+      end
+    end
+  end
+end

data/lib/pikuri/lsp/readiness.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+module Pikuri
+  module Lsp
+    # Whether a server has finished indexing, and the wait that blocks until it
+    # has. One rule for every server: **no progress token open, and nothing said
+    # for {SETTLE} seconds.** Fed from the server's notification stream, drained
+    # by whoever is waiting — two different threads:
+    #
+    #   readiness = Readiness.new(server_id: 'java')
+    #   client.on_notification { |method, params| readiness.observe(method, params) }
+    #
+    #   readiness.wait(cancellable: cancellable, alive: -> { client.alive? }) do |progress|
+    #     emitter.call(progress)     # ServerProgress, on *this* thread
+    #   end
+    #
+    # The gate exists because the alternative is a lie: ruby-lsp answers a
+    # +definition+ sent mid-index with a successful +[]+, and an agent reads that
+    # as "this symbol has no definition" and proceeds. There is nothing in +[]+ to
+    # reason about, which is why this is the one case where pikuri waits instead
+    # of relaying.
+    #
+    # == Why a debounce, and why one rule fits every server
+    #
+    # Quiescence alone is a false edge: jdtls's long-lived +Initialize Workspace+
+    # token is *bracketed* by transient ones — a plain two-file project produced
+    # eight — and there every token was closed **0.9s before the server could
+    # answer**. The debounce is not the timeout pikuri removed: it never abandons
+    # the wait, it only refuses to call an idle moment the end.
+    #
+    # One rule covers both reference servers because their failure modes are
+    # opposite. jdtls *defers* mid-index requests and flushes the backlog when it
+    # is ready, so waiting too long costs latency and nothing else; ruby-lsp
+    # answers early and wrongly, so waiting is the only defense. No per-server
+    # predicate, no knob.
+    #
+    # == Two edges it cannot see, both relayed rather than papered over
+    #
+    # * A server whose *first* token opens more than {SETTLE} after its handshake
+    #   is briefly called ready before it ever began. Both measured servers open
+    #   theirs within milliseconds of +initialized+, so this is the residual cost
+    #   of a generic gate rather than an observed one.
+    # * A token the server opens and never closes waits forever — the no-clock
+    #   stance working as intended, with the human as the timeout via
+    #   +cancellable+.
+    #
+    # Thread-safe: {#observe} runs on the server's reader thread while {#wait}
+    # runs on the caller's, which is what the {Mailbox} is here for.
+    class Readiness
+      # Seconds of quiet, after the last token closes, before the index is
+      # called built. Above the 0.9s gap jdtls was measured to need, with margin;
+      # the cost is that much added to a first call against a warm server.
+      SETTLE = 1.5
+
+      # How often {#wait} wakes with nothing parked, to re-check readiness,
+      # liveness and cancellation.
+      TICK = 0.1
+
+      # @param server_id [String] the registry entry's id, carried on every
+      #   {ServerProgress} this emits.
+      # @param settle [Float] seconds of quiet that end the wait. Overridden in
+      #   tests; there is deliberately no configuration seam for it.
+      def initialize(server_id:, settle: SETTLE)
+        @server_id = server_id
+        @settle = settle
+        @mutex = Mutex.new
+        @mailbox = Mailbox.new
+        @open = {}
+        @quiet_since = now
+      end
+
+      # Take one server notification into account. Anything that is not
+      # +$/progress+ is ignored, so this can be handed the whole stream.
+      #
+      # Runs on the reader thread: it only records state and parks a
+      # {ServerProgress} for {#wait} to emit, because
+      # {Pikuri::Agent::ExtensionContext#emit_event} is the agent thread's.
+      #
+      # @param method [String] the notification method.
+      # @param params [Hash, nil] its +params+ member.
+      # @return [void]
+      def observe(method, params)
+        return unless method == '$/progress'
+
+        token = params&.fetch('token', nil).to_s
+        value = params&.fetch('value', nil)
+        return unless value.is_a?(Hash)
+
+        progress = record(token, value)
+        @mailbox.push(token, progress) if progress
+        nil
+      end
+
+      # @return [Boolean] whether every task the server announced has ended and
+      #   it has been quiet since — the gate's whole rule.
+      def ready?
+        @mutex.synchronize { @open.empty? && (now - @quiet_since) >= @settle }
+      end
+
+      # Block until the server is ready, yielding progress as it arrives.
+      #
+      # Returns immediately when the gate is already open, so a warm server
+      # costs one predicate. Otherwise it yields every {ServerProgress} the
+      # server sends — coalesced, so a three-minute wait yields *current* state
+      # rather than replaying the backlog — and finally a +done: true+ for every
+      # task still in flight, however the wait ended and whether or not this wait
+      # was the one that announced it: a host that drew a bar must be told to
+      # take it down even when the server never sent the +end+.
+      #
+      # @param cancellable [Pikuri::Agent::Control::Cancellable, nil] polled
+      #   every {TICK}; this is what makes an unbounded wait acceptable.
+      # @param alive [Proc] answers whether the server can still become ready.
+      #   Without it a dead child would be waited on forever.
+      # @yieldparam progress [ServerProgress]
+      # @return [Boolean] +true+ when the server is ready, +false+ when +alive+
+      #   went false first. Cancellation raises instead.
+      # @raise [Pikuri::Agent::Control::Cancellable::Cancelled] on cancellation.
+      def wait(cancellable: nil, alive: -> { true })
+        # Tracked by title, not token: the host draws its bars off what it was
+        # shown, and a ServerProgress carries no token for it to key on.
+        shown = []
+        @mailbox.drain(tick: TICK) do |progress|
+          cancellable&.check!
+          # Liveness first: a child that died without ever announcing a task is
+          # *quiet*, and quiet is half of what this gate calls ready.
+          break false unless alive.call
+          break true if ready?
+          next unless progress
+
+          progress.done ? shown.delete(progress.title) : shown |= [progress.title]
+          yield progress
+        end
+      ensure
+        (shown | open_titles).each do |title|
+          yield ServerProgress.new(server_id: @server_id, title: title, done: true)
+        end
+      end
+
+      # Forget everything: a restarted server has an empty index, so its previous
+      # tokens say nothing and the quiet clock starts over.
+      #
+      # @return [void]
+      def reset!
+        @mutex.synchronize do
+          @open.clear
+          @quiet_since = now
+        end
+        nil
+      end
+
+      private
+
+      # @return [Array<String>] titles of the tasks the server has not ended.
+      #   The union with what a wait showed is what guarantees no bar outlives
+      #   its wait — including a task announced before the wait even started.
+      def open_titles
+        @mutex.synchronize { @open.values.uniq }
+      end
+
+      # @return [ServerProgress, nil] what to park, or +nil+ for a +kind+ no
+      #   +WorkDoneProgress+ defines.
+      def record(token, value)
+        @mutex.synchronize do
+          @quiet_since = now
+          # A report or end whose begin we never saw is titled by its token: the
+          # spec requires the begin first, so that is a server bug to relay, not
+          # to invent a title for.
+          case value['kind']
+          when 'begin' then title = @open[token] = (value['title'] || token).to_s
+          when 'report' then title = (@open[token] ||= token)
+          when 'end' then title = @open.delete(token) || token
+          else return nil
+          end
+          ServerProgress.new(server_id: @server_id, title: title,
+                             message: value['message'], percentage: value['percentage'],
+                             done: value['kind'] == 'end')
+        end
+      end
+
+      def now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end

data/lib/pikuri/lsp/refusal.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Pikuri
+  module Lsp
+    # A model-facing decline: the tool will not answer this call, and the message
+    # is the sentence the model reads.
+    #
+    #   raise Refusal, "no language server is configured for .md files"
+    #
+    # Raised deep — routing, the capability gate, an anchor that resolves
+    # nowhere — and caught once, in {Navigator#navigate}, which prefixes
+    # +"Error: "+.
+    #
+    # It carries no code and no category, deliberately. The three answers a caller
+    # must be able to tell apart — *unsupported*, *the server answered nothing*,
+    # *the server could not be asked* — stay apart because each has its own
+    # sentence, not because a consumer switches on a symbol; collapsing them into
+    # one "nothing found, this may be because…" is the defect in the shipped prior
+    # art. And a refusal never proposes what to do instead: what failed is a fact,
+    # what to try next is the model's call on evidence this tool does not have.
+    class Refusal < StandardError; end
+  end
+end