msnav 0.2.0

data/lib/msnav/navigator.rb

@@ -0,0 +1,326 @@
+# frozen_string_literal: true
+
+module Msnav
+  # Cross-service code navigation over the coderag graph — a line-for-line
+  # port of coderag/navigation.py's Navigator, answering:
+  #
+  #   definition(file, line0)   where an outgoing call/publish LANDS in the
+  #                             other service's source (Faraday call -> Roda
+  #                             route, RabbitMQ publish -> consumer handler,
+  #                             route line -> the Process class it routes to)
+  #   references(file, line0)   who calls the endpoint under the cursor, from
+  #                             other services
+  #   hover(file, line0)        the target endpoint's doc for the call on the line
+  #   file_targets(file)        every cross-service jump point in a file
+  #                             (the editor's CodeLens data)
+  #
+  # Lines are 0-based at this boundary (LSP convention, same as the HTTP API);
+  # the index stores 1-based lines, converted on the way in/out. Locations are
+  # returned as {"path", "line", "character"} hashes, ready for the JSON API.
+  class Navigator
+    # edge kinds whose target is a cross-service / framework "definition"
+    DEF_EDGES = ["http_call", "publishes", "routes_to"].freeze
+
+    attr_reader :graph, :roots
+
+    def initialize(graph)
+      @graph = graph
+      # service name -> absolute root path
+      @roots = {}
+      graph.services.each do |_id, data|
+        name = data["name"]
+        root = data["root"]
+        @roots[name] = root if name && present?(root)
+      end
+    end
+
+    # Map an absolute path to [service_name, path_relative_to_service_root],
+    # longest matching root wins (nested service dirs). nil when the path is
+    # under no indexed service.
+    def locate(abs_path)
+      abs_path = File.expand_path(abs_path)
+      best = nil
+      @roots.each do |name, root|
+        root_abs = File.expand_path(root)
+        rel = begin
+          Pathname.new(abs_path).relative_path_from(Pathname.new(root_abs)).to_s
+        rescue ArgumentError
+          next
+        end
+        next if rel.start_with?("..")
+        best = [name, rel, root_abs] if best.nil? || root_abs.length > best[2].length
+      end
+      best && [best[0], best[1].tr(File::SEPARATOR, "/")]
+    end
+
+    def definition(abs_path, line0, _character = 0)
+      loc = locate(abs_path)
+      return [] if loc.nil?
+      service, rel = loc
+      line1 = line0 + 1
+      targets = []
+
+      # 1) cursor inside a class that makes outgoing calls / publishes
+      sym_id = covering_symbol(service, rel, line1)
+      unless sym_id.nil?
+        edges = @graph.out(sym_id, DEF_EDGES)
+        # prefer an edge whose call site is exactly on this line
+        exact = edges.select { |_t, e| e["line"] == line1 }
+        chosen = exact.empty? ? edges : exact
+        chosen.each do |tgt, edata|
+          kind = edata["kind"]
+          if kind == "publishes"
+            tnode = @graph.node(tgt) || {}
+            if tnode["kind"] == "topic"
+              targets.concat(publish_targets(tgt))
+              next
+            end
+          end
+          t = node_target(tgt)
+          targets << t if t
+        end
+      end
+
+      # 2) cursor on a route line -> the Process it routes to (DI indirection)
+      ep_id = endpoint_at(service, rel, line1)
+      unless ep_id.nil?
+        @graph.out(ep_id, ["routes_to"]).each do |tgt, _edata|
+          t = node_target(tgt)
+          targets << t if t
+        end
+      end
+
+      dedupe(targets.map { |t| to_location(t) })
+    end
+
+    # Cross-service callers of the endpoint under the cursor.
+    def references(abs_path, line0, _character = 0)
+      loc = locate(abs_path)
+      return [] if loc.nil?
+      service, rel = loc
+      line1 = line0 + 1
+      ep_id = endpoint_at(service, rel, line1)
+      return [] if ep_id.nil?
+      out = []
+      @graph.in_edges(ep_id).each do |src, edata|
+        next unless edata["kind"] == "http_call"
+        src_d = @graph.node(src) || {}
+        src_service = src_d["service"]
+        call_file = edata["file"] || src_d["file"]
+        call_line = edata["line"] || src_d["start_line"] || 1
+        abs_p = src_service ? target_path(src_service, call_file) : nil
+        next if abs_p.nil?
+        out << { path: abs_p, line: [call_line - 1, 0].max, character: 0 }
+      end
+      dedupe(out.map { |t| to_location(t) })
+    end
+
+    # Markdown describing the cross-service endpoint the call on this line
+    # targets; fires ONLY when an http_call edge's call site is exactly on
+    # `line0`. nil when there is nothing to show.
+    def hover(abs_path, line0, _character = 0)
+      loc = locate(abs_path)
+      return nil if loc.nil?
+      service, rel = loc
+      line1 = line0 + 1
+      sym_id = covering_symbol(service, rel, line1)
+      return nil if sym_id.nil?
+      edges = @graph.out(sym_id, ["http_call"]).select { |_t, e| e["line"] == line1 }
+      return nil if edges.empty?
+      blocks = []
+      edges.each do |tgt, edata|
+        tnode = @graph.node(tgt) || {}
+        case tnode["kind"]
+        when "endpoint"
+          b = endpoint_hover(tgt, tnode)
+          blocks << b if b
+        when "service"
+          blocks << "**#{edata['verb'] || '?'} #{edata['path'] || '?'}** — " \
+                    "route not found in `#{tnode['name']}`"
+        end
+      end
+      return nil if blocks.empty?
+      { "markdown" => blocks.join("\n\n---\n\n") }
+    end
+
+    # All CROSS-service jump points in a file. Each item: the 0-based source
+    # line where the call/publish is, and the target's absolute path +
+    # 0-based line in the OTHER service. Same-service targets are excluded —
+    # ruby-lsp handles those in-window.
+    def file_targets(abs_path)
+      loc = locate(abs_path)
+      return [] if loc.nil?
+      service, rel = loc
+      out = []
+      @graph.nodes_in_file(service, rel).each do |node_id, d|
+        next unless d["kind"] == "symbol"
+        @graph.out(node_id, ["http_call", "publishes"]).each do |tgt, edata|
+          src_line0 = [(edata["line"] || d["start_line"] || 1) - 1, 0].max
+          kind = edata["kind"]
+          tnode = @graph.node(tgt) || {}
+          if kind == "publishes"
+            next unless tnode["kind"] == "topic"
+            publish_targets(tgt).each do |t|
+              out << target_item(src_line0, t, "publish")
+            end
+          elsif tnode["kind"] == "endpoint"
+            next if tnode["service"] == service # same service -> skip
+            t = node_target(tgt)
+            out << target_item(src_line0, t, "http") if t
+          elsif tnode["kind"] == "service" && tnode["name"] != service
+            # service resolved but NO matching route — link to its routes so
+            # you can see what it does expose
+            rl = service_routes_location(tnode["name"])
+            next if rl.nil?
+            path, tline = rl
+            out << { "line" => src_line0, "path" => path, "target_line" => tline,
+                     "label" => "#{edata['verb'] || '?'} #{edata['path'] || '?'}" \
+                                " — route not found in #{tnode['name']}",
+                     "kind" => "http-unresolved" }
+          end
+        end
+      end
+      # dedupe on (source line, target path, target line)
+      seen = {}
+      out.select do |item|
+        key = [item["line"], item["path"], item["target_line"]]
+        seen.key?(key) ? false : (seen[key] = true)
+      end
+    end
+
+    private
+
+    def present?(value)
+      !value.nil? && value != ""
+    end
+
+    def target_path(service, rel_file)
+      root = @roots[service]
+      return nil if root.nil? || !present?(rel_file) || rel_file == "?"
+      File.join(root, rel_file)
+    end
+
+    # Smallest symbol node (class/module) whose span covers a 1-based line;
+    # when the smallest covering node is an endpoint, fall back to the
+    # smallest covering *symbol* in the same file.
+    def covering_symbol(service, rel_file, line1)
+      nid = @graph.covering_symbol(service, rel_file, line1)
+      if !nid.nil? && (@graph.node(nid) || {})["kind"] == "symbol"
+        return nid
+      end
+      best_id = nil
+      best_span = nil
+      @graph.nodes_in_file(service, rel_file).each do |node_id, d|
+        next unless d["kind"] == "symbol"
+        start_line = d["start_line"]
+        next if start_line.nil?
+        end_line = d["end_line"] || start_line
+        next unless start_line <= line1 && line1 <= end_line
+        span = end_line - start_line
+        if best_span.nil? || span < best_span
+          best_id = node_id
+          best_span = span
+        end
+      end
+      best_id
+    end
+
+    # Endpoint node whose route definition is on/near (± 2 lines) a 1-based line.
+    def endpoint_at(service, rel_file, line1)
+      candidates = []
+      @graph.nodes_in_file(service, rel_file).each do |node_id, d|
+        next unless d["kind"] == "endpoint"
+        eline = d["line"]
+        next if eline.nil?
+        candidates << [(eline - line1).abs, node_id]
+      end
+      return nil if candidates.empty?
+      nearest = candidates.min
+      nearest[0] <= 2 ? nearest[1] : nil
+    end
+
+    # A resolved navigation target: {path, line (0-based), character, label,
+    # kind}, or nil when the node can't be materialized to a file position.
+    def node_target(node_id)
+      return nil unless @graph.has_node?(node_id)
+      d = @graph.node(node_id)
+      kind = d["kind"]
+      service = d["service"]
+      rel = d["file"]
+      line = d["line"] || d["start_line"]
+      return nil unless %w[endpoint symbol].include?(kind) &&
+                        present?(service) && present?(rel) && line && line != 0
+      abs_path = target_path(service, rel)
+      return nil if abs_path.nil?
+      label = if kind == "endpoint"
+                "#{d['verb'] || ''} #{d['path'] || ''} [#{service}]"
+              else
+                "#{d['name'] || node_id} [#{service}]"
+              end
+      { path: abs_path, line: [line - 1, 0].max, character: 0,
+        label: label, kind: kind }
+    end
+
+    # publish edge -> topic -> queue(s) -> consumer handler(s), plus each
+    # handler's target Process.
+    def publish_targets(topic_id)
+      out = []
+      @graph.out(topic_id, ["binds"]).each do |queue_id, _e|
+        @graph.out(queue_id, ["consumes"]).each do |consumer_id, _e2|
+          t = node_target(consumer_id)
+          out << t if t
+          @graph.out(consumer_id, ["calls"]).each do |tgt, _e3|
+            ht = node_target(tgt)
+            out << ht if ht
+          end
+        end
+      end
+      out
+    end
+
+    # Topmost route of a service — the landing spot when a call resolved the
+    # service but matched no specific route. [abs_path, 0-based line] or nil.
+    def service_routes_location(svc_name)
+      best = nil
+      @graph.endpoints(svc_name).each do |_node_id, d|
+        line = d["line"] || 1
+        next unless best.nil? || line < best[1]
+        abs_path = target_path(svc_name, d["file"])
+        best = [abs_path, line] if abs_path
+      end
+      best && [best[0], [best[1] - 1, 0].max]
+    end
+
+    def endpoint_hover(ep_id, d)
+      verb = d["verb"] || "?"
+      path = d["path"] || "?"
+      service = d["service"] || "?"
+      parts = ["**#{verb} #{path}**  ·  _#{service}_"]
+      @graph.out(ep_id, ["routes_to"]).each do |tgt, _e|
+        hd = @graph.node(tgt) || {}
+        parts << "**Handler:** `#{hd['name']}`" if present?(hd["name"])
+        doc = hd["call_doc"] || hd["doc"]
+        parts << (present?(doc) ? doc : "_No `@return` documented on the handler._")
+        break
+      end
+      parts.join("\n\n")
+    end
+
+    def target_item(src_line0, t, kind)
+      { "line" => src_line0, "path" => t[:path], "target_line" => t[:line],
+        "label" => t[:label], "kind" => kind }
+    end
+
+    def to_location(t)
+      { "path" => t[:path], "line" => t[:line], "character" => t[:character] || 0 }
+    end
+
+    def dedupe(locations)
+      seen = {}
+      locations.select do |l|
+        key = [l["path"], l["line"], l["character"]]
+        seen.key?(key) ? false : (seen[key] = true)
+      end
+    end
+  end
+end

data/lib/msnav/server.rb

@@ -0,0 +1,341 @@
+# frozen_string_literal: true
+
+require "json"
+require "webrick"
+
+module Msnav
+  # The msnav daemon: WEBrick serving the coderag daemon's navigation API.
+  #
+  # The Holder is the single source of index state (graph + navigator),
+  # replaced atomically when the shared DB's `index_generation` moves — a
+  # host-side `coderag index` or a peer daemon's rebuild hot-reloads every
+  # msnav on the hub within a second, requests always see a consistent index.
+  class Holder
+    attr_reader :cfg, :store, :windows, :service_root, :service_name
+
+    def initialize(cfg, service_root: nil, service_name: nil)
+      @cfg = cfg
+      # service scope: this daemon's container sees ONE service's source at
+      # this path (msnav never extracts from it — the scope only names which
+      # indexed service this window holds, for the extension's path mapping)
+      @service_root = service_root
+      @service_name = service_name
+      @store = Store.new(cfg.db_path)
+      @windows = WindowRegistry.new(@store)
+      @mutex = Mutex.new
+      @generation = 0
+      @db_generation = @store.index_generation
+      @navigator = load_navigator
+    end
+
+    # A service-scoped daemon's identity: the container path holding the
+    # service and its canonical (host) location from the shared DB — the
+    # exact path mapping the editor extension needs, with no folder-name
+    # guessing (mounts like `/app` carry no service name).
+    def scope
+      return nil unless @service_root
+      base = @service_name ||
+             File.basename(File.expand_path(@service_root))
+      @store.services.each do |name, dirname, canonical_root|
+        next unless dirname == base
+        return { "service" => name, "dirname" => dirname,
+                 "service_root" => @service_root.to_s,
+                 "root" => canonical_root }
+      end
+      { "service" => nil, "dirname" => base,
+        "service_root" => @service_root.to_s, "root" => nil }
+    end
+
+    def navigator
+      @mutex.synchronize { @navigator }
+    end
+
+    def generation
+      @mutex.synchronize { @generation }
+    end
+
+    # Follower path: hot-swap the navigator when another daemon (or a host
+    # reindex) moved the persisted generation. True when a reload happened.
+    def maybe_reload
+      gen = @store.index_generation
+      return false if gen == @db_generation
+      nav = load_navigator
+      @mutex.synchronize do
+        @navigator = nav
+        @generation += 1
+        @db_generation = gen
+      end
+      warn "msnav: index changed in the shared DB — reloaded (generation #{gen})"
+      true
+    end
+
+    private
+
+    def load_navigator
+      Navigator.new(Graph.load(@store, @cfg.workspace_root))
+    end
+  end
+
+  class Server
+    GENERATION_POLL_SECONDS = 1.0
+
+    # host editor CLI used to open a project folder at a position
+    EDITOR_ENV = "CODERAG_EDITOR"
+    DEFAULT_EDITOR = "cursor"
+
+    def initialize(cfg, host: "127.0.0.1", port: 8787,
+                   service_root: nil, service_name: nil)
+      @holder = Holder.new(cfg, service_root: service_root,
+                                service_name: service_name)
+      @host = host
+      @port = port
+    end
+
+    def start
+      server = WEBrick::HTTPServer.new(
+        BindAddress: @host, Port: @port, AccessLog: [],
+        Logger: WEBrick::Log.new($stderr, WEBrick::Log::WARN))
+      server.mount_proc("/") { |req, res| dispatch(req, res) }
+
+      poller = Thread.new do
+        loop do
+          sleep GENERATION_POLL_SECONDS
+          begin
+            @holder.maybe_reload
+          rescue StandardError => e # the poller must survive anything
+            warn "msnav: reload check failed: #{e.message}"
+          end
+        end
+      end
+
+      %w[INT TERM].each { |sig| trap(sig) { server.shutdown } }
+      puts "msnav daemon on http://#{@host}:#{@port}  " \
+           "(navigation API for #{@holder.cfg.workspace_root})"
+      server.start
+    ensure
+      poller && poller.kill
+    end
+
+    private
+
+    ROUTES = {
+      ["GET", "/api/health"] => :health,
+      ["GET", "/api/nav/definition"] => :nav_definition,
+      ["GET", "/api/nav/references"] => :nav_references,
+      ["GET", "/api/nav/hover"] => :nav_hover,
+      ["GET", "/api/nav/file-targets"] => :nav_file_targets,
+      ["POST", "/api/register-window"] => :register_window,
+      ["GET", "/api/window-commands"] => :window_commands,
+      ["GET", "/api/windows"] => :list_windows,
+      ["POST", "/api/open"] => :open_in_editor,
+      ["GET", "/api/services"] => :services,
+      ["GET", "/api/routes"] => :routes,
+    }.freeze
+
+    def dispatch(req, res)
+      handler = ROUTES[[req.request_method, req.path]]
+      res["Content-Type"] = "application/json"
+      if handler.nil?
+        res.status = 404
+        res.body = JSON.generate("detail" => "Not Found")
+        return
+      end
+      begin
+        res.status = 200
+        res.body = JSON.generate(send(handler, req))
+      rescue HttpError => e
+        res.status = e.status
+        res.body = JSON.generate("detail" => e.message)
+      rescue StandardError => e
+        warn "msnav: #{req.request_method} #{req.path} failed: " \
+             "#{e.class}: #{e.message}\n  #{e.backtrace.first(5).join("\n  ")}"
+        res.status = 500
+        res.body = JSON.generate("detail" => "#{e.class}: #{e.message}")
+      end
+    end
+
+    class HttpError < StandardError
+      attr_reader :status
+
+      def initialize(status, message)
+        @status = status
+        super(message)
+      end
+    end
+
+    def param(req, name)
+      value = req.query[name]
+      raise HttpError.new(422, "query must include '#{name}'") if value.nil? || value.empty?
+      # WEBrick query values are binary-encoded FormData; sqlite3 would bind
+      # binary strings as BLOBs (and TEXT comparisons would silently miss),
+      # so normalize to a plain UTF-8 String at the boundary
+      String.new(value.to_s).force_encoding(Encoding::UTF_8)
+    end
+
+    def body_json(req)
+      JSON.parse(req.body || "")
+    rescue JSON::ParserError
+      raise HttpError.new(422, "body must be a JSON object")
+    end
+
+    # ----------------------------------------------------------------- health
+
+    def health(_req)
+      graph = @holder.navigator.graph
+      {
+        "ok" => true,
+        "generation" => @holder.generation,
+        "root" => @holder.cfg.workspace_root.to_s,
+        "version" => VERSION,
+        "pid" => Process.pid,
+        "services" => graph.services.map { |_id, d| d["name"] }.compact.sort,
+        # canonical service locations (host paths in the service-scoped flow)
+        # — callers use these for coverage checks and host opens
+        "service_roots" => graph.services.map { |_id, d| d["root"] }
+                                .reject { |r| r.nil? || r.empty? }.sort,
+        # a scoped daemon's own service: the container path it holds and the
+        # canonical root — the extension's exact path mapping
+        "scope" => @holder.scope,
+      }
+    end
+
+    # ------------------------------------------------------------- navigation
+
+    def nav_definition(req)
+      @holder.navigator.definition(param(req, "file"), param(req, "line").to_i)
+    end
+
+    def nav_references(req)
+      @holder.navigator.references(param(req, "file"), param(req, "line").to_i)
+    end
+
+    def nav_hover(req)
+      @holder.navigator.hover(param(req, "file"), param(req, "line").to_i) || {}
+    end
+
+    def nav_file_targets(req)
+      @holder.navigator.file_targets(param(req, "file"))
+    end
+
+    # ---------------------------------------------------------------- windows
+
+    def register_window(req)
+      payload = body_json(req)
+      window_id = payload["window_id"]
+      raise HttpError.new(422, "body must include 'window_id'") if window_id.nil? || window_id.empty?
+      @holder.windows.register(window_id, payload["authority"],
+                               payload["roots"], payload["path_mappings"])
+      { "registered" => true, "window_id" => window_id,
+        "windows" => @holder.windows.count }
+    end
+
+    def window_commands(req)
+      window_id = param(req, "window_id")
+      if @holder.windows.touch(window_id).nil?
+        { "known" => false, "commands" => [] }
+      else
+        { "known" => true, "commands" => @holder.windows.drain(window_id) }
+      end
+    end
+
+    def list_windows(_req)
+      now = Time.now.to_f
+      @holder.windows.all.map do |r|
+        { "window_id" => r.window_id, "authority" => r.authority,
+          "roots" => r.roots, "host_roots" => r.host_roots,
+          "alive" => r.alive?(now),
+          "last_poll_ago" => (now - r.last_poll).round(1) }
+      end
+    end
+
+    # Open the target at file:line where it is already open: if a live window
+    # owns the target, push an open-command to it; otherwise fall back to a
+    # new local host window — or, in a container, hand the open back to the
+    # caller (its extension has the one host capability we lack).
+    def open_in_editor(req)
+      payload = body_json(req)
+      file = payload["file"]
+      line = (payload["line"] || 1).to_i
+      raise HttpError.new(422, "body must include 'file'") if file.nil? || file.empty?
+
+      reg = @holder.windows.enqueue_open(file, line)
+      unless reg.nil?
+        return { "opened" => true, "routed" => true, "route" => "pushed",
+                 "window_id" => reg.window_id }
+      end
+
+      nav = @holder.navigator
+      loc = nav.locate(file)
+      folder = loc ? nav.roots[loc[0]] : nil
+      folder ||= File.dirname(file) # fall back to the file's dir
+
+      unless host_editor_reachable?
+        # in-container daemon with no live window owning the target: hand the
+        # SERVICE FOLDER back to the caller (its extension opens it on the
+        # host — the one capability we lack) and park the file:line open; the
+        # new window's extension claims it when it registers
+        @holder.windows.park_open(file, [line, 1].max)
+        return { "opened" => false, "routed" => false, "folder" => folder,
+                 "path" => file, "line" => [line, 1].max }
+      end
+
+      editor = ENV[EDITOR_ENV] || DEFAULT_EDITOR
+      launch([editor, folder, "--goto", "#{file}:#{[line, 1].max}:1"])
+      { "opened" => true, "routed" => false, "route" => "fallback",
+        "folder" => folder, "goto" => "#{file}:#{line}" }
+    end
+
+    # ------------------------------------------------------------ diagnostics
+
+    def services(_req)
+      graph = @holder.navigator.graph
+      graph.services.sort_by { |id, _d| id }.map do |_id, svc|
+        eps = graph.endpoints(svc["name"])
+                   .sort_by { |_n, d| [d["path"] || "", d["verb"] || ""] }
+        { "name" => svc["name"], "root" => svc["root"],
+          "endpoints" => eps.map { |_n, d| { "verb" => d["verb"], "path" => d["path"] } } }
+      end
+    end
+
+    def routes(req)
+      service = req.query["service"]
+      graph = @holder.navigator.graph
+      out = []
+      graph.services.sort_by { |id, _d| id }.each do |_id, svc|
+        next if service && !service.empty? && svc["name"] != service
+        eps = graph.endpoints(svc["name"])
+                   .sort_by { |_n, d| [d["path"] || "", d["verb"] || ""] }
+        eps.each do |node_id, ep|
+          handlers = graph.out(node_id, ["routes_to"])
+                          .select { |t, _e| graph.has_node?(t) }
+                          .map { |t, _e| graph.node(t)["name"] }
+          out << { "service" => svc["name"], "verb" => ep["verb"],
+                   "path" => ep["path"], "handler" => handlers.first }
+        end
+      end
+      out
+    end
+
+    # --------------------------------------------------------------- editors
+
+    # An in-container daemon cannot launch a host editor — /api/open then
+    # hands the target back to the caller instead. Overridable for tests and
+    # exotic setups via CODERAG_HOST_EDITOR.
+    def host_editor_reachable?
+      override = ENV["CODERAG_HOST_EDITOR"]
+      unless override.nil?
+        return !["0", "false", "no", ""].include?(override)
+      end
+      !File.exist?("/.dockerenv")
+    end
+
+    # Fire the editor CLI detached; false if the process could not start.
+    def launch(cmd)
+      pid = Process.spawn(*cmd, out: File::NULL, err: File::NULL)
+      Process.detach(pid)
+      true
+    rescue SystemCallError
+      false
+    end
+  end
+end