pikuri-lsp 0.1.0

data/lib/pikuri/lsp/servers.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+module Pikuri
+  module Lsp
+    # Every language server this agent may use: one {ClientWrapper} per
+    # {Registry} entry, and the routing that picks which one answers for a file.
+    # **Nothing is spawned until a call needs it** — construction is pure, and
+    # each of the two routes starts what it needs:
+    #
+    #   servers = Servers.new(registry: registry, root: filesystem.project_root)
+    #   servers.client_for('lib/pikuri/agent.rb')   # the claiming server, spawned now
+    #   servers.client_for('README.md')             # => nil, and nothing spawned
+    #   servers.active                              # every project-relevant server, spawned
+    #   servers.close
+    #
+    # Arm teardown straight after construction, not after the first call: a
+    # server that started before a later one failed is registered here precisely
+    # so an already-armed +close+ still sweeps it.
+    #
+    # == Implementation details
+    #
+    # Because a start is lazy, a misconfigured +command+ is discovered by the
+    # call that needed it — a {ClientWrapper::ServerDied} naming the id and the
+    # argv, which {Navigator} relays as an +"Error: …"+ observation. That is the
+    # same path a server dying *after* a successful spawn already took.
+    #
+    # Sharing: +P_one_agent+, accepted for today — +@clients+ / +@active+ are
+    # unguarded, {#close} kills children another caller may be mid-request on,
+    # and a per-agent {Pikuri::Agent::Control::Cancellable} is threaded into
+    # every handshake. A shared server pool is buildable and simply isn't built,
+    # so N agents over one project means N sets of language servers.
+    class Servers
+      LOGGER = Pikuri.logger_for('Lsp::Servers')
+      private_constant :LOGGER
+
+      # @return [Registry] the configuration these clients run.
+      attr_reader :registry
+
+      # @param registry [Registry] which servers exist. {Registry::EMPTY} makes
+      #   every method here a no-op answer, so a host with no config wires no
+      #   tool and nothing else has to care.
+      # @param root [String, Pathname] the workspace root: every child's cwd, the
+      #   +rootUri+ it indexes, and the tree {#active_entries} scans.
+      # @param cancellable [Pikuri::Agent::Control::Cancellable, nil] threaded
+      #   into each handshake.
+      # @param spawn [Proc, nil] +entry+ → a started {ClientWrapper}. The seam a
+      #   spec replaces to drive fake servers over pipes; production passes
+      #   nothing.
+      def initialize(registry:, root:, cancellable: nil, spawn: nil)
+        @registry = registry
+        @root = root
+        @cancellable = cancellable
+        @spawn = spawn || lambda { |entry|
+          ClientWrapper.spawn(entry, root: @root, cancellable: @cancellable)
+        }
+        @clients = {}
+        @active = nil
+      end
+
+      # The fan-out set: every project-relevant server, **each spawned here** if
+      # it was not running.
+      #
+      # Relevant rather than registered because a fan-out cannot choose between
+      # servers without starting them — {Navigator} gates on what each advertised
+      # in *this* workspace, and only a live handshake carries that.
+      #
+      # @return [Array<ClientWrapper>] in declaration order; empty when nothing is
+      #   configured or nothing in the project matches.
+      # @raise [ClientWrapper::ServerDied] from the first server that cannot be
+      #   started.
+      def active
+        active_entries.map { |entry| client(entry) }
+      end
+
+      # The registered entries this project has files for — the relevance question
+      # answered without spawning anything.
+      #
+      # Rescanned while the answer is *incomplete*, memoized once every
+      # registered entry is accounted for. A project gains its first +.java+
+      # file mid-session — the agent wrote it — and a scan memoized at the first
+      # call would leave jdtls out of every later fan-out, which the model reads
+      # as "no such symbol" rather than "nobody asked". A walk costs ~4 ms on
+      # this repo against a path that is about to block on a whole index, so
+      # paying it until the answer stops changing is free; once every entry is
+      # relevant nothing can invalidate it and the walk stops.
+      #
+      # The first entry claiming a basename wins, exactly as
+      # {Registry#entry_for} decides, so an entry shadowed by an earlier one is
+      # never activated by files it would not be asked about.
+      #
+      # @return [Array<Registry::StdioEntry>] in declaration order.
+      def active_entries
+        return @active if @active && @active.size == @registry.entries.size
+
+        @active = relevant_entries
+      end
+
+      # The server that answers for +path+, started if it was not running.
+      #
+      # Cheap: the path is its own evidence of relevance, so this route never
+      # walks the project the way {#active_entries} must.
+      #
+      # @param path [String, Pathname] matched on its basename by
+      #   {Registry::StdioEntry#claims?}.
+      # @return [ClientWrapper, nil] +nil+ when no entry claims the file.
+      # @raise [ClientWrapper::ServerDied] when the claiming server cannot start.
+      def client_for(path)
+        entry = @registry.entry_for(path)
+        entry && client(entry)
+      end
+
+      # @return [Array<String>] ids of the servers actually running, in start
+      #   order — nothing at all until a call needs one.
+      def started_ids
+        @clients.keys
+      end
+
+      # @return [Boolean] whether there is nothing to ask — a *registry* question,
+      #   not a liveness one: a configured server counts whether or not it has
+      #   started, or this would answer "none" to the very first call.
+      def empty?
+        @registry.empty?
+      end
+
+      # Shut every started server down. Idempotent, and never raises — it runs
+      # from an +on_close+ at exit, where one bad teardown must not take the rest
+      # of the sweep with it ({ClientWrapper#close} already swallows its own).
+      #
+      # @return [void]
+      def close
+        @clients.each_value(&:close)
+        @clients.clear
+        LOGGER.debug('closed')
+        nil
+      end
+
+      private
+
+      # @return [ClientWrapper]
+      def client(entry)
+        # A raising spawn stays unmemoized on purpose: installing the missing
+        # binary mid-session then recovers, and re-learning an ENOENT is free.
+        started = @clients[entry.id] ||= begin
+          LOGGER.info("#{entry.id}: starting on first use")
+          @spawn.call(entry)
+        end
+        note_relevant(entry)
+        started
+      end
+
+      # A started server is relevant by construction: the file that routed here
+      # is the evidence {#relevant_entries} goes walking for. That outranks the
+      # walk, which skips dot-directories and symlinks — without this, a server
+      # started for +.hidden/Foo.java+ would be rescanned for, never found, and
+      # left out of every fan-out.
+      #
+      # @param entry [Registry::StdioEntry]
+      # @return [void]
+      def note_relevant(entry)
+        return if @active.nil? || @active.include?(entry)
+
+        @active = @registry.entries.select { |e| e == entry || @active.include?(e) }
+        nil
+      end
+
+      # One pruned walk, stopping as soon as every entry is accounted for.
+      #
+      # Neither dot-directories nor symlinked ones are descended — +.git+ and a
+      # vendored bundle say nothing about what *this* project is written in, and
+      # not following a symlink is the cheapest cycle-free rule. So relevance is
+      # a heuristic, and it only ever narrows the fan-out: {#client_for} starts
+      # its server regardless.
+      #
+      # @return [Array<Registry::StdioEntry>]
+      def relevant_entries
+        return [] if @registry.empty?
+
+        pending = @registry.entries.dup
+        found = []
+        scan(@root.to_s, pending, found)
+        @registry.entries.select { |entry| found.include?(entry) }
+      end
+
+      # @return [void]
+      def scan(dir, pending, found)
+        Dir.children(dir).each do |name|
+          return if pending.empty?
+
+          path = File.join(dir, name)
+          if !File.symlink?(path) && File.directory?(path)
+            scan(path, pending, found) unless name.start_with?('.')
+          else
+            claimant = pending.find { |entry| entry.claims?(name) }
+            next if claimant.nil?
+
+            found << claimant
+            pending.delete(claimant)
+          end
+        end
+      rescue SystemCallError => e
+        # A heuristic must not fail the call it serves, and an unreadable
+        # directory says nothing about relevance either way.
+        LOGGER.debug("relevance scan skipped #{dir}: #{e.message}")
+        nil
+      end
+    end
+  end
+end

data/lib/pikuri/lsp/sources.rb

@@ -0,0 +1,272 @@
+# frozen_string_literal: true
+
+module Pikuri
+  module Lsp
+    # Where the bytes behind a result come from, and what a result is *called*.
+    # One instance per tool call, so the memo and the fetch budget are per call.
+    #
+    #   sources = Sources.new(filesystem: filesystem)
+    #   sources.label_for(location.uri)
+    #   # => "pikuri-workspace/lib/pikuri/workspace/filesystem.rb"
+    #   # => "org.slf4j.LoggerFactory (slf4j-api-2.0.18.jar)"
+    #   sources.snippet_for(location, client: client)   # => "def resolve_for_read(path)"
+    #
+    # == Three tiers, keyed on the URI's scheme
+    #
+    # There is no standard "read this URI" request in the LSP that ships today and
+    # no way to discover a server's non-standard one, so this is policy, not a
+    # lookup:
+    #
+    # 1. **+file:+ — the only scheme pikuri reads itself.** In-root results carry
+    #    the workspace-relative path, and the read goes through the +Workspace+
+    #    seam. Out-of-root results (the 45 gem hits one +goToDefinition+ on a
+    #    constant returned) always carry the line of code — "what does this library
+    #    method do" is a top reason to want LSP at all — and carry a **path only
+    #    when this workspace would read that file**, which is a per-wiring answer:
+    #    +AllowAll+ (the +--yolo+ and OS-agent wirings) opens a gem checkout
+    #    happily, a root-confined one refuses it, and quoting a path the +read+
+    #    tool will reject is a dead-end citation. Every +file:+ URI takes a
+    #    {#denied?} pass first — a result is a *walked* path, so nothing else stops
+    #    an index hit under +~/.ssh+ from being quoted.
+    # 2. **A server-private scheme — standard first, one hardcoded row behind
+    #    it.** LSP 3.18's +workspace/textDocumentContent+ is real discovery (the
+    #    server lists the +schemes+ it will read) and wins where advertised.
+    #    Nothing implements it yet, and a standard-only stance made the Java arm
+    #    untestable, so {SCHEME_REQUESTS} carries exactly one row with a written
+    #    deletion condition: **delete the +jdt:+ row the day jdtls advertises
+    #    +textDocumentContent+**, and the standard path above it takes over with no
+    #    other edit. The bar for adding a row is a server someone wired and can
+    #    test.
+    # 3. **+http(s):+ and any scheme with no row — printed, never dereferenced.**
+    #    The load-bearing refusal: fetching a URI the *server* chose is egress with
+    #    the payload in the URL, and no network row may ever enter the table. A
+    #    scheme with no row still gets the inline reason, never a bare count.
+    #
+    # One reply of attached Java source measured 22,639 bytes in 10 ms — cheap to
+    # fetch, ruinous to inline — so content is sliced to the line the result points
+    # at, memoized per URI (a 45-hit answer repeats URIs) and capped at
+    # {MAX_FETCHES} documents per call.
+    class Sources
+      # Documents one tool call may fetch over the wire. A cap rather than a
+      # budget because the failure it prevents is one call inlining a jar.
+      MAX_FETCHES = 5
+
+      # Characters of a source line a snippet keeps. A row is one line — not the
+      # result's whole +range+, which for a reopened namespace is the whole file.
+      MAX_SNIPPET_CHARS = 160
+
+      # LSP 3.18's client→server content request: +{uri}+ → +{text}+.
+      STANDARD_REQUEST = 'workspace/textDocumentContent'
+
+      # The scheme→request table. One row, and the deletion condition is in the
+      # class header. +java/classFileContents+ answers with a **bare String**
+      # where the standard request answers +{text:}+; {#fetch_from_server} accepts
+      # either, which is the whole reason both paths can share a call site.
+      SCHEME_REQUESTS = { 'jdt' => 'java/classFileContents' }.freeze
+
+      # @param filesystem [Pikuri::Workspace::Filesystem] the root confinement,
+      #   the +denied?+ pass, and the seam every in-root read routes through.
+      def initialize(filesystem:)
+        @filesystem = filesystem
+        @root = filesystem.project_root.to_s
+        @memo = {}
+        @readable = {}
+        @fetches = 0
+      end
+
+      # What to call this URI in a rendered row.
+      #
+      # @param uri [String] as the server sent it.
+      # @return [String] a workspace-relative path in-root; the absolute path for a
+      #   file outside the root this workspace would still read, or a bare basename
+      #   for one it would refuse; +"org.slf4j.LoggerFactory
+      #   (slf4j-api-2.0.18.jar)"+ for a +jdt:+ handle; else the URI itself,
+      #   truncated — a real +jdt:+ URI runs to ~300 characters of encoded
+      #   classpath and must never be shown raw.
+      def label_for(uri)
+        path = Uris.to_path(uri)
+        return relative(path) if path && in_root?(path)
+        return out_of_root_label(path) if path
+
+        scheme = Uris.scheme(uri)
+        return jdt_label(uri) if scheme == 'jdt'
+
+        truncate(uri, 200)
+      end
+
+      # @param uri [String]
+      # @return [Boolean] whether this names a file under the workspace root —
+      #   which is what decides whether a row carries a path the model can act
+      #   on.
+      def in_root_file?(uri)
+        path = Uris.to_path(uri)
+        !path.nil? && in_root?(path)
+      end
+
+      # Whether this workspace would actually open the document behind a +file:+
+      # URI — what decides whether a citation may carry a *link*, since a link to
+      # a path the +read+ tool refuses is the dead-end citation this class exists
+      # to avoid. Includes the {#denied?} pass, so it is safe to ask on its own.
+      #
+      # @param uri [String]
+      # @return [Boolean] +false+ for any non-+file:+ URI: a jar entry is not a
+      #   path, so nothing here can open one.
+      def actionable?(uri)
+        path = Uris.to_path(uri)
+        !path.nil? && !@filesystem.denied?(path) && readable?(path)
+      end
+
+      # Whether this URI must be dropped rather than rendered.
+      #
+      # A result is a path the *server* walked to, so it reaches no
+      # +resolve_for_read+ and this check is the only thing standing between an
+      # index hit under a credential root and the model's context. It fails
+      # closed, never raises, and is exact — the file tools run as the real user.
+      #
+      # @param uri [String]
+      # @return [Boolean] +false+ for a non-+file:+ URI, which cannot be
+      #   denylist-checked at all: a jar's contents are not a path.
+      def denied?(uri)
+        path = Uris.to_path(uri)
+        !path.nil? && @filesystem.denied?(path)
+      end
+
+      # One line of code for a result, or the reason there is none.
+      #
+      # @param location [Location] what the server pointed at.
+      # @param client [ClientWrapper, nil] the server that issued the URI — the
+      #   only one that can read its private schemes.
+      # @return [String] the source line, stripped and truncated, or a bracketed
+      #   reason. Never +nil+: a row with no snippet still has to say why.
+      def snippet_for(location, client: nil)
+        lines, reason = lines_for(location.uri, client: client)
+        return "[#{reason}]" if lines.nil?
+
+        line = lines[location.anchor.start.line - 1]
+        return '[the server pointed past the end of this document]' if line.nil?
+
+        truncate(line.strip, MAX_SNIPPET_CHARS)
+      end
+
+      # The document behind a URI, memoized for this call.
+      #
+      # @param uri [String]
+      # @param client [ClientWrapper, nil]
+      # @return [Array(Array<String>, nil), Array(nil, String)] its lines, or
+      #   +nil+ and the reason.
+      def lines_for(uri, client: nil)
+        @memo[uri] ||= fetch(uri, client)
+      end
+
+      private
+
+      def fetch(uri, client)
+        path = Uris.to_path(uri)
+        return [nil, 'this path is on the workspace denylist'] if path && @filesystem.denied?(path)
+        return read_file(path) if path
+
+        scheme = Uris.scheme(uri)
+        if %w[http https].include?(scheme)
+          # The refusal, and it is the whole no-network claim: the URI was chosen
+          # by the server, so fetching it would be egress with the payload in the
+          # URL.
+          return [nil, 'pikuri-lsp never fetches a remote URI; this one is printed as text only']
+        end
+
+        fetch_from_server(uri, scheme, client)
+      end
+
+      # In-root reads route through the seam; an out-of-root result is read
+      # directly, because +resolve_for_read+ exists to refuse exactly that path
+      # and the result is a citation rather than a file the model asked for.
+      def read_file(path)
+        text = in_root?(path) ? @filesystem.resolve_for_read(path).read : File.read(path)
+        [text.lines, nil]
+      rescue Pikuri::Workspace::Filesystem::Error, SystemCallError, IOError => e
+        [nil, "could not be read (#{e.class}: #{e.message})"]
+      end
+
+      def fetch_from_server(uri, scheme, client)
+        return [nil, "only the server that issued this #{scheme}: URI can read it"] if client.nil?
+
+        request = content_request(client, scheme)
+        if request.nil?
+          return [nil, "this server's #{scheme}: URIs need LSP 3.18 content support, " \
+                       'which it does not advertise']
+        end
+        if @fetches >= MAX_FETCHES
+          return [nil, "not fetched: one call reads at most #{MAX_FETCHES} documents from a server"]
+        end
+
+        @fetches += 1
+        parse_content(client.request(request, { uri: uri }), scheme)
+      rescue Connection::ServerError, ClientWrapper::ServerDied => e
+        # Try-then-degrade: a wrongly-matched scheme, or a server that refuses
+        # the request it advertised, costs one round trip and an honest row.
+        [nil, "the server would not read this #{scheme}: URI (#{e.message})"]
+      end
+
+      # 3.18 answers +{text:}+; +java/classFileContents+ answers a bare String.
+      def parse_content(reply, scheme)
+        text = reply.is_a?(Hash) ? reply['text'] : reply
+        return [nil, "the server answered no text for this #{scheme}: URI"] unless text.is_a?(String)
+
+        [text.lines, nil]
+      end
+
+      # Standard first: the server lists the schemes it will read, which is real
+      # discovery. Only if it advertises nothing does the one-row table apply —
+      # and keying on the scheme is exact rather than a guess, because only the
+      # server that issued a +jdt:+ URI can read one.
+      def content_request(client, scheme)
+        declared = client.capabilities.dig('workspace', 'textDocumentContent')
+        schemes = declared.is_a?(Hash) ? declared['schemes'] : nil
+        return STANDARD_REQUEST if declared && (schemes.nil? || schemes.include?(scheme))
+
+        SCHEME_REQUESTS[scheme]
+      end
+
+      def in_root?(path)
+        path == @root || path.start_with?("#{@root}/")
+      end
+
+      # Outside the root the label is the *actionable* form: the path where this
+      # workspace would open the file, its basename where it would not. Suppressing
+      # a readable path would delete a capability the wiring granted; printing an
+      # unreadable one invites a refused read.
+      def out_of_root_label(path)
+        readable?(path) ? path : "outside the workspace: #{File.basename(path)}"
+      end
+
+      def readable?(path)
+        @readable.fetch(path) do
+          @readable[path] = begin
+            @filesystem.resolve_for_read(path)
+            true
+          rescue Pikuri::Workspace::Filesystem::Error
+            false
+          end
+        end
+      end
+
+      def relative(path)
+        path == @root ? File.basename(path) : path[(@root.length + 1)..]
+      end
+
+      # +jdt://contents/<jar>/<package>/<Type>.class?=<the whole classpath entry>+
+      # → +"<package>.<Type> (<jar>)"+, which is the only readable thing in it.
+      def jdt_label(uri)
+        segments = uri.split('?').first.to_s.split('/')
+        index = segments.index('contents')
+        return truncate(uri, 120) if index.nil? || segments.length < index + 4
+
+        jar, package, file = segments[(index + 1)..(index + 3)]
+        "#{package}.#{File.basename(file, '.*')} (#{jar})"
+      end
+
+      def truncate(text, limit)
+        text.length > limit ? "#{text[0, limit - 4]} ..." : text
+      end
+    end
+  end
+end

data/lib/pikuri/lsp/symbol_name.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Pikuri
+  module Lsp
+    # Comparing a name the model typed against a name a server's index reports,
+    # which are not the same string even when they mean the same thing:
+    #
+    #   SymbolName.last_segment('Pikuri::Workspace::Read')   # => "Read"
+    #   SymbolName.last_segment('Read#resolve_for_read')      # => "resolve_for_read"
+    #   SymbolName.last_segment('greet(String)')              # => "greet"
+    #   SymbolName.matches?('Pikuri::Tool', 'Tool')           # => true
+    #
+    # The rule is *compare the last segment*, and it is a measured requirement
+    # rather than tidiness: ruby-lsp deliberately reports the **fully qualified**
+    # name in +workspace/symbol+ (its source says why — so that searching for
+    # +Foo::Bar+ works), servers separate a method from its owner with +#+ or +.+
+    # depending on the language, and jdtls appends a Java signature. An exact-name
+    # filter comparing +name+ verbatim therefore rejects every correct hit, which
+    # is the silent-empty failure this gem exists to avoid producing itself.
+    #
+    # It is deliberately not a fuzzy match. The server has already been fuzzy —
+    # one three-letter query returned 11 hits matched on scattered letters — and
+    # what this filter is for is picking the hits that really are the name asked
+    # for.
+    module SymbolName
+      # Separators a server may put between a container and its member.
+      SEPARATORS = /::|#|\.|\$/
+
+      module_function
+
+      # @param name [String, nil] a name as a server reported it.
+      # @return [String] the member half, with any signature dropped. +""+ for
+      #   +nil+, so a nameless row simply matches nothing.
+      def last_segment(name)
+        name.to_s.split('(').first.to_s.split(SEPARATORS).last.to_s
+      end
+
+      # @param name [String, nil] the indexed name.
+      # @param query [String] what the model asked for, which may itself be
+      #   qualified (+"Pikuri::Workspace::Read"+).
+      # @return [Boolean] whether they name the same member.
+      def matches?(name, query)
+        segment = last_segment(name)
+        !segment.empty? && segment == last_segment(query)
+      end
+    end
+  end
+end