rigortype 0.1.5 → 0.1.6

data/lib/rigor/language_server/completion_provider.rb

@@ -0,0 +1,438 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "uri"
+require_relative "../environment"
+require_relative "../reflection"
+require_relative "../scope"
+require_relative "../source/node_locator"
+require_relative "../inference/scope_indexer"
+require_relative "../type/nominal"
+require_relative "../type/singleton"
+require_relative "../type/constant"
+require_relative "../type/union"
+require_relative "../type/intersection"
+require_relative "../type/refined"
+require_relative "../type/difference"
+require_relative "../type/tuple"
+require_relative "../type/hash_shape"
+
+module Rigor
+  module LanguageServer
+    # Answers `textDocument/completion` requests. v1 (slice 5)
+    # ships method completion for `obj.|`: when the cursor sits on
+    # a `CallNode` with a known-type receiver, the provider
+    # enumerates the receiver's RBS-known methods and returns each
+    # as an LSP `CompletionItem`.
+    #
+    # Constant-path completion (slice 6), Union / Intersection /
+    # Refined / Shape receiver handling (slice 7), and parse-recovery
+    # fallback for malformed buffers (slice 8) extend this v1 floor.
+    #
+    # LSP `CompletionItemKind` values used:
+    # - 2 = Method
+    #
+    # Slice 6 will add 7 (Class), 9 (Module), 21 (Constant).
+    class CompletionProvider # rubocop:disable Metrics/ClassLength
+      KIND_METHOD   = 2
+      KIND_FIELD    = 5
+      KIND_CLASS    = 7
+      KIND_MODULE   = 9
+      KIND_CONSTANT = 21
+
+      def initialize(buffer_table:, project_context:)
+        @buffer_table = buffer_table
+        @project_context = project_context
+      end
+
+      # @return [Array<Hash>, nil] LSP `CompletionItem[]` or nil
+      #   when the cursor isn't at a position the provider can
+      #   enumerate completions for. Returning nil maps to
+      #   `result: null` per the LSP spec — clients treat it as
+      #   "no completions available," distinct from `[]` which
+      #   means "we tried and got nothing".
+      def provide(uri:, line:, character:, trigger_character: nil)
+        _ = trigger_character # Trigger info logged-not-routed in v1.
+        path = Uri.to_path(uri)
+        return nil if path.nil?
+
+        entry = @buffer_table[uri]
+        return nil if entry.nil?
+
+        # Slice B4 — parse recovery. The common mid-edit buffer
+        # (`obj.` / `Foo::`) doesn't parse cleanly; try inserting
+        # a sentinel name at the cursor before falling through.
+        bytes_to_parse, locate_at = parse_attempt_bytes(entry.bytes, line, character)
+        parse_result = Prism.parse(bytes_to_parse, filepath: path,
+                                                   version: @project_context.configuration.target_ruby)
+        return nil unless parse_result.errors.empty?
+
+        # Rigor's NodeLocator uses 1-based line / column; LSP uses 0-based.
+        node = locate_node(source: bytes_to_parse, root: parse_result.value,
+                           line: locate_at[0] + 1, character: locate_at[1] + 1)
+        return nil if node.nil?
+
+        case node
+        when Prism::CallNode
+          # `hash[:|` patches to `hash[:KEY_SENTINEL]`, an index
+          # access call whose argument is the sentinel symbol;
+          # NodeLocator at the sentinel returns the inner CallNode
+          # for `[]`. Hash-key completion wins when the call is an
+          # index access on a HashShape carrier; otherwise fall
+          # through to method completion.
+          hash_key_completion_for(node, parse_result.value, path) ||
+            method_completion_for(node, parse_result.value, path)
+        when Prism::SymbolNode
+          # The sentinel symbol's NodeLocator hit; walk up via the
+          # AST to find the enclosing `[]` call.
+          hash_key_completion_for_symbol(node, parse_result.value, path)
+        when Prism::ConstantPathNode
+          constant_path_completion_for(node, path)
+        end
+      end
+
+      private
+
+      # Slice B4 — parse recovery. Returns `[bytes, [line, character]]`:
+      # the source to feed Prism plus the cursor position the
+      # caller should locate against. When the original buffer
+      # parses cleanly we return it verbatim; when it doesn't AND
+      # the cursor sits at a mid-edit `.` / `::` trigger, we
+      # splice a sentinel identifier into the source so Prism's
+      # AST captures the receiver / parent constant cleanly.
+      #
+      # The sentinel is a syntactically-unique identifier the
+      # NodeLocator can find without ambiguity. We choose lower /
+      # upper case based on whether the trigger was `.` (method
+      # name — lowercase identifier) or `::` (constant path —
+      # uppercase identifier).
+      # Sentinels need to be parseable as their target shape:
+      # method sentinel is a lower-snake identifier; constant
+      # sentinel MUST start with an uppercase letter (Ruby
+      # constants reject `_`-leading names — `Process::__Foo`
+      # parses as a method call, not a constant path).
+      SENTINEL_METHOD   = "__rigor_lsp_sentinel__"
+      SENTINEL_CONSTANT = "RigorLspSentinelXyz"
+      SENTINEL_HASH_KEY = "__rigor_lsp_key__"
+      private_constant :SENTINEL_METHOD, :SENTINEL_CONSTANT, :SENTINEL_HASH_KEY
+
+      def parse_attempt_bytes(original_bytes, line, character)
+        # Cheap probe: try original first. Most editor sessions
+        # call completion in mid-keystroke where parse fails, but
+        # some land on a clean buffer (e.g. the trigger fires
+        # right after the user picked an item).
+        if Prism.parse(original_bytes).errors.empty?
+          [original_bytes, [line, character]]
+        else
+          patch_with_sentinel(original_bytes, line, character)
+        end
+      end
+
+      def patch_with_sentinel(original_bytes, line, character)
+        lines = original_bytes.lines
+        return [original_bytes, [line, character]] if line >= lines.size
+
+        target = lines[line]
+        prefix = target.byteslice(0, character) || ""
+        suffix_offset = [character, target.bytesize].min
+        suffix = target.byteslice(suffix_offset, target.bytesize - suffix_offset) || ""
+
+        sentinel = sentinel_for_prefix(prefix)
+        return [original_bytes, [line, character]] if sentinel.nil?
+
+        lines[line] = "#{prefix}#{sentinel}#{suffix}"
+        # The cursor stays at the same column — Prism's AST now
+        # has a node whose name occupies [character, character +
+        # sentinel.size). NodeLocator at that column returns the
+        # enclosing call / path.
+        [lines.join, [line, character]]
+      end
+
+      def sentinel_for_prefix(prefix)
+        # Strip trailing whitespace before checking for the
+        # trigger character; users often type the dot then a
+        # space mid-edit.
+        stripped = prefix.rstrip
+        # `[:` covers `hash[:|` symbol-key access — splice both
+        # the key name AND the closing `]` so Prism gets a
+        # complete index expression. The closing bracket is part
+        # of the sentinel string for this case (vs the bare
+        # identifier sentinels for `.` / `::`).
+        return "#{SENTINEL_HASH_KEY}]" if stripped.end_with?("[:")
+        return SENTINEL_METHOD if stripped.end_with?(".")
+        return SENTINEL_CONSTANT if stripped.end_with?("::")
+
+        nil
+      end
+
+      def method_completion_for(call_node, root, path)
+        receiver_node = call_node.receiver
+        return nil if receiver_node.nil? # implicit-self — slice-3 territory of completion
+
+        index = build_scope_index(root, path)
+        receiver_scope = index[receiver_node]
+        receiver_type = receiver_scope.type_of(receiver_node)
+        method_completions(receiver_type, receiver_scope)
+      end
+
+      # Slice D1 — `hash[:|` hash-key completion. Triggers when
+      # the cursor is on the synthetic key inside a `[]` call AND
+      # the receiver's inferred type is a `Type::HashShape`. Returns
+      # nil for any other receiver carrier so the dispatcher falls
+      # through to method completion (which still surfaces Hash's
+      # methods for genuine method calls on a hash receiver).
+      def hash_key_completion_for(call_node, root, path)
+        return nil unless call_node.name == :[]
+
+        receiver_node = call_node.receiver
+        return nil if receiver_node.nil?
+
+        index = build_scope_index(root, path)
+        receiver_type = index[receiver_node].type_of(receiver_node)
+        return nil unless receiver_type.is_a?(Type::HashShape)
+
+        hash_key_items(receiver_type)
+      end
+
+      # When NodeLocator returns the sentinel SymbolNode directly
+      # (rather than the enclosing CallNode), walk up the AST for
+      # the smallest `[]` call containing the symbol's location.
+      # Re-walks the root once; cheap for LSP-sized buffers.
+      def hash_key_completion_for_symbol(symbol_node, root, path)
+        call_node = enclosing_index_call(root, symbol_node)
+        return nil if call_node.nil?
+
+        hash_key_completion_for(call_node, root, path)
+      end
+
+      def enclosing_index_call(root, symbol_node)
+        symbol_offset = symbol_node.location.start_offset
+        result = nil
+        walk = lambda do |n|
+          next unless n.is_a?(Prism::Node)
+
+          if n.is_a?(Prism::CallNode) && n.name == :[] && n.location &&
+             n.location.start_offset <= symbol_offset && symbol_offset <= n.location.end_offset
+            result = n
+          end
+          n.compact_child_nodes.each(&walk)
+        end
+        walk.call(root)
+        result
+      end
+
+      def hash_key_items(hash_shape)
+        hash_shape.pairs.keys.map do |key|
+          label = key.inspect # `:foo` for symbols, `"bar"` for strings
+          {
+            label: label,
+            kind: KIND_FIELD,
+            detail: "key of HashShape",
+            insertText: label,
+            filterText: label,
+            sortText: "0_#{label}"
+          }
+        end
+      end
+
+      # Slice B2 — `Foo::|` constant-path completion. The cursor
+      # sits on a `ConstantPathNode` whose `parent` resolves to a
+      # class / module FQN; we enumerate every known class whose
+      # name is an immediate child of that parent. Top-level
+      # constants (`::Foo`) and parent-less paths are not yet
+      # supported (queued for slice 6 follow-up).
+      def constant_path_completion_for(const_path_node, path)
+        parent_fqn = parent_fqn_of(const_path_node)
+        return nil if parent_fqn.nil?
+
+        scope = base_scope(path)
+        children = enumerate_constant_children(parent_fqn, scope)
+        return nil if children.empty?
+
+        children.map { |child| constant_completion_item(parent_fqn, child) }
+      end
+
+      def parent_fqn_of(const_path_node)
+        # ConstantPathNode#parent is the LHS of the `::`. For
+        # `Foo::Bar` it's the ConstantReadNode for `Foo`; for
+        # `Foo::Bar::Baz` it's a ConstantPathNode. We render
+        # either to the dotted FQN string.
+        parent = const_path_node.parent
+        return nil if parent.nil?
+
+        qualified_name_of(parent)
+      end
+
+      def qualified_name_of(node)
+        case node
+        when Prism::ConstantReadNode
+          node.name.to_s
+        when Prism::ConstantPathNode
+          parent = qualified_name_of(node.parent) if node.parent
+          parent.nil? ? node.name.to_s : "#{parent}::#{node.name}"
+        end
+      end
+
+      # Walks `RbsLoader#known_class_names_set` for entries whose
+      # FQN is `parent_fqn::<one segment>` — the immediate children.
+      # Deeper descendants are filtered out so the popup shows
+      # only the next-level constants the user can directly write.
+      # `known_class_names_set` is private on RbsLoader per the
+      # type-system's internal API discipline; the LSP layer is a
+      # trusted internal consumer and `send` is the documented
+      # escape hatch (same pattern as `Type::Refined#canonical_name`
+      # in slice A4).
+      def enumerate_constant_children(parent_fqn, scope)
+        loader = scope.environment.rbs_loader
+        return [] if loader.nil?
+
+        names = loader.send(:known_class_names_set)
+        # RBS canonical names carry a leading `::` (so the table
+        # holds `::Process::Status` etc.). Match against both
+        # forms so the prefix walk works regardless of which form
+        # the caller passes.
+        prefix = "::#{parent_fqn}::"
+        names.filter_map do |fqn|
+          next nil unless fqn.start_with?(prefix)
+
+          tail = fqn.delete_prefix(prefix)
+          # Only immediate children — no `::` in the tail.
+          next nil if tail.empty? || tail.include?("::")
+
+          tail
+        end.uniq.sort
+      end
+
+      def constant_completion_item(parent_fqn, child_name)
+        {
+          label: child_name,
+          kind: KIND_CLASS, # heuristic; slice-7 follow-up may distinguish Module / Constant
+          detail: "#{parent_fqn}::#{child_name}",
+          insertText: child_name,
+          filterText: child_name,
+          sortText: "0_#{child_name}"
+        }
+      end
+
+      def base_scope(_path)
+        Scope.empty(environment: @project_context.environment)
+      end
+
+      def locate_node(source:, root:, line:, character:)
+        Source::NodeLocator.at_position(source: source, root: root, line: line, column: character)
+      rescue Source::NodeLocator::OutOfRangeError
+        nil
+      end
+
+      def build_scope_index(root, _path)
+        scope = Scope.empty(environment: @project_context.environment)
+        Inference::ScopeIndexer.index(root, default_scope: scope)
+      end
+
+      # Returns an Array<Hash> of LSP `CompletionItem`s for every
+      # public method callable on the receiver. Slice B3 extends
+      # the slice-B1 floor with:
+      # - `Type::Refined` / `Type::Difference` — enumerate the
+      #   underlying nominal (refinement narrows the value set,
+      #   not the method set).
+      # - `Type::Tuple` / `Type::HashShape` — enumerate the
+      #   nominal ancestor (`Array` / `Hash`); element-type-aware
+      #   completion is queued.
+      # - `Type::Union` — intersection of methods on each member
+      #   (only methods guaranteed to dispatch on every union case).
+      #   Conservative default per design doc § "Union receiver
+      #   completion".
+      # - `Type::Intersection` — union of methods on each member
+      #   (anything callable on at least one member).
+      def method_completions(receiver_type, scope)
+        method_set, kind = enumerate_method_set(receiver_type, scope)
+        return nil if method_set.nil? || method_set.empty?
+
+        method_set.filter_map do |name, method|
+          next nil unless method.public?
+
+          completion_item(name: name, method: method, kind: kind)
+        end
+      end
+
+      # Returns `[{Symbol => RBS::Definition::Method}, :instance | :singleton]`
+      # for the receiver. Composite carriers (Union / Intersection /
+      # Refined / shape carriers) reduce to instance-method
+      # enumeration; the receiver-class label that lands in each
+      # CompletionItem's `detail` still comes from each method's
+      # own `defs.first.implemented_in`, so the rendered prefix
+      # stays accurate per-method.
+      def enumerate_method_set(receiver_type, scope)
+        case receiver_type
+        when Type::Singleton
+          [Reflection.singleton_definition(receiver_type.class_name, scope: scope)&.methods, :singleton]
+        when Type::Union
+          [intersect_member_methods(receiver_type.members, scope), :instance]
+        when Type::Intersection
+          [union_member_methods(receiver_type.members, scope), :instance]
+        when Type::Refined, Type::Difference
+          enumerate_method_set(receiver_type.base, scope)
+        when Type::Tuple
+          [Reflection.instance_definition("Array", scope: scope)&.methods, :instance]
+        when Type::HashShape
+          [Reflection.instance_definition("Hash", scope: scope)&.methods, :instance]
+        else
+          class_name = nominal_class_name(receiver_type)
+          return [nil, nil] if class_name.nil?
+
+          [Reflection.instance_definition(class_name, scope: scope)&.methods, :instance]
+        end
+      end
+
+      # Union receiver — keep only methods present in EVERY
+      # member's set. Conservative semantically (every method
+      # returned is callable on every member) and prevents
+      # `obj.upcase` from appearing on a `String | Integer`
+      # union where only one side answers `upcase`.
+      def intersect_member_methods(members, scope)
+        member_sets = members.filter_map { |m| enumerate_method_set(m, scope).first }
+        return nil if member_sets.empty?
+
+        common_names = member_sets.map(&:keys).reduce(:&)
+        member_sets.first.slice(*common_names)
+      end
+
+      # Intersection receiver — accumulate every method declared on
+      # ANY member. A value of type `A & B` is callable through both
+      # interfaces; the completion popup MAY show either's methods.
+      def union_member_methods(members, scope)
+        members.filter_map { |m| enumerate_method_set(m, scope).first }.reduce({}, :merge)
+      end
+
+      def nominal_class_name(type)
+        case type
+        when Type::Nominal then type.class_name
+        when Type::Constant then type.value.class.name
+        end
+      end
+
+      def completion_item(name:, method:, kind:)
+        label = name.to_s
+        method_type = method.method_types.first
+        signature = method_type ? method_type.to_s : "(unknown)"
+        sep = kind == :singleton ? "." : "#"
+        receiver_name = method.defs.first&.implemented_in.to_s
+        detail = receiver_name.empty? ? signature : "#{receiver_name}#{sep}#{label}: #{signature}"
+
+        {
+          label: label,
+          kind: KIND_METHOD,
+          detail: detail,
+          insertText: label,
+          filterText: label,
+          # Inherited methods rank below own-class methods; the
+          # `defs.first.implemented_in` carries the declaring
+          # class. Inheritance-distance ranking is queued (design
+          # doc § "sortText").
+          sortText: "1_#{label}"
+        }
+      end
+    end
+  end
+end

data/lib/rigor/language_server/debouncer.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Rigor
+  module LanguageServer
+    # Per-key debouncer. The LSP uses this to defer
+    # `publishDiagnostics` until the user stops typing (200ms
+    # quiet-time floor per LSP UX conventions). Each
+    # `schedule(uri, delay:)` cancels the previous task for the
+    # same `uri` and queues a new one — only the LAST task in a
+    # burst actually runs.
+    #
+    # Threading model: each scheduled task runs in its own Thread
+    # so the dispatcher loop doesn't block. Concurrent writes to
+    # STDOUT from the Debouncer's threads + the main dispatch
+    # loop are serialised by `SynchronizedWriter`.
+    #
+    # Cancellation is cooperative: each task carries a
+    # `cancelled` flag; new schedules flip the prior task's flag
+    # and the prior thread skips the block on wake-up. This is
+    # safer than `Thread#kill` for in-flight Ruby code and good
+    # enough for the "drop stale debounce" use case.
+    class Debouncer
+      Task = Struct.new(:thread, :cancelled)
+
+      def initialize
+        @tasks = {}
+        @mutex = Mutex.new
+      end
+
+      # Schedule `block` to run after `delay` seconds, replacing
+      # any pending task for the same `key`. `delay: 0` makes the
+      # task fire immediately (still on its own thread); tests
+      # pair this with `#flush!` for deterministic assertions.
+      def schedule(key, delay:, &block)
+        task = Task.new(nil, false)
+
+        previous = @mutex.synchronize do
+          prev = @tasks[key]
+          @tasks[key] = task
+          prev
+        end
+        previous&.cancelled = true
+
+        task.thread = Thread.new do
+          sleep(delay) if delay.positive?
+          unless task.cancelled
+            begin
+              block.call
+            rescue StandardError => e
+              warn "Debouncer task #{key.inspect}: #{e.class}: #{e.message}"
+            end
+          end
+          @mutex.synchronize { @tasks.delete(key) if @tasks[key] == task }
+        end
+        nil
+      end
+
+      # Wait for every pending task to complete. Used by specs to
+      # synchronise with the async schedule; the production
+      # `shutdown` path uses `#cancel_all` instead.
+      def flush!
+        threads = @mutex.synchronize { @tasks.values.map(&:thread) }
+        threads.each do |thread|
+          thread.join
+        rescue StandardError
+          # Threads can die from raised exceptions; ignore.
+        end
+      end
+
+      # Cancel every pending task (sets the flag; the threads
+      # exit without running the block). Called on `shutdown` so
+      # in-flight publishes don't write to a closed STDOUT.
+      def cancel_all
+        @mutex.synchronize do
+          @tasks.each_value { |t| t.cancelled = true }
+          @tasks.clear
+        end
+      end
+
+      # @return [Integer] number of currently-pending tasks.
+      def pending_size
+        @mutex.synchronize { @tasks.size }
+      end
+    end
+  end
+end

data/lib/rigor/language_server/diagnostic_publisher.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require "tempfile"
+
+require_relative "uri"
+require_relative "../analysis/runner"
+require_relative "../analysis/buffer_binding"
+
+module Rigor
+  module LanguageServer
+    # Converts buffer state into `textDocument/publishDiagnostics`
+    # notifications. Owns the Rigor `Analysis::Runner` orchestration
+    # for the per-buffer single-file scope path that editor mode v1
+    # already supports — every `publish_for(uri)` call materialises
+    # a `BufferBinding` from the BufferTable entry, runs the Runner,
+    # and pushes the resulting LSP `Diagnostic[]` through the writer.
+    #
+    # Slice 4 is synchronous: each call blocks until analysis
+    # completes (typically 100-300ms warm). Debouncing (200ms
+    # quiet-time before publish) and Ractor-pool dispatch are
+    # queued for slice 4b / slice 8 respectively.
+    class DiagnosticPublisher
+      # Maps Rigor severity symbols to LSP DiagnosticSeverity
+      # integers per spec § "Diagnostic":
+      #   1 = Error, 2 = Warning, 3 = Information, 4 = Hint.
+      SEVERITY_MAP = {
+        error: 1,
+        warning: 2,
+        info: 3,
+        hint: 4
+      }.freeze
+
+      # @param debouncer [Rigor::LanguageServer::Debouncer, nil]
+      #   when present, `publish_for` schedules its work through
+      #   the debouncer (cancels prior pending task for the same
+      #   URI, fires after `debounce_seconds` quiet-time). Nil
+      #   keeps the slice 4-7 synchronous behaviour — primarily
+      #   useful for specs.
+      # @param debounce_seconds [Numeric] quiet-time before the
+      #   debounced publish fires. 0 with a debouncer means
+      #   "schedule on next-tick" (still async); without a
+      #   debouncer the value is unused.
+      def initialize(writer:, buffer_table:, project_context:,
+                     debouncer: nil, debounce_seconds: 0.2)
+        @writer = writer
+        @buffer_table = buffer_table
+        @project_context = project_context
+        @debouncer = debouncer
+        @debounce_seconds = debounce_seconds
+      end
+
+      # Run analysis for the buffer at `uri` (looked up in the
+      # BufferTable) and push a `textDocument/publishDiagnostics`
+      # notification. No-op when the URI isn't a `file://` form or
+      # the buffer isn't currently open. When a Debouncer is wired,
+      # the analysis is scheduled async per the configured
+      # `debounce_seconds`; otherwise it runs inline.
+      def publish_for(uri)
+        path = Uri.to_path(uri)
+        return if path.nil?
+
+        if @debouncer
+          @debouncer.schedule(uri, delay: @debounce_seconds) { run_and_notify(uri, path) }
+        else
+          run_and_notify(uri, path)
+        end
+      end
+
+      # Publishes an EMPTY diagnostic array for `uri`. The LSP-spec
+      # idiom for "clear inline markers" — called from `didClose`
+      # so clients drop stale highlights when the user closes a
+      # buffer.
+      def publish_empty(uri)
+        notify(uri, [])
+      end
+
+      # Cancels every in-flight debounced task. Called from
+      # `Server#handle_shutdown` so pending publishes don't fire
+      # against a closed STDOUT.
+      def cancel_pending
+        @debouncer&.cancel_all
+      end
+
+      private
+
+      def run_and_notify(uri, path)
+        entry = @buffer_table[uri]
+        # The buffer may have been closed during the debounce
+        # window — drop the publish; the empty notification from
+        # didClose already cleared the markers.
+        return if entry.nil?
+
+        diagnostics = run_analysis(path: path, bytes: entry.bytes)
+        notify(uri, diagnostics)
+      end
+
+      # Runs `Analysis::Runner` with a `BufferBinding` so the buffer
+      # bytes (instead of the on-disk file) drive the parse. The
+      # `Rigor::Analysis::ProjectScan` cached on the ProjectContext
+      # is passed through `prebuilt:` so plugin `#prepare`, the
+      # dependency-source walker, and the synthetic-method /
+      # project-patched scanners do not re-run per publish. The
+      # snapshot rebuilds only when `ProjectContext#invalidate!`
+      # fires (watched-file or configuration change). Returns
+      # the LSP-shaped Diagnostic Array, ready to serialize into
+      # the notification's `params.diagnostics` field.
+      def run_analysis(path:, bytes:)
+        with_tempfile(bytes) do |tmp|
+          binding = Analysis::BufferBinding.new(logical_path: path, physical_path: tmp.path)
+          runner = Analysis::Runner.new(
+            configuration: @project_context.configuration,
+            cache_store: @project_context.cache_store,
+            collect_stats: false,
+            buffer: binding,
+            prebuilt: @project_context.project_scan,
+            environment: @project_context.environment
+          )
+          result = runner.run([path])
+          result.diagnostics.filter_map { |diagnostic| to_lsp_diagnostic(diagnostic, path) }
+        end
+      end
+
+      def with_tempfile(bytes)
+        tmp = Tempfile.new(["rigor-lsp-buffer-", ".rb"])
+        tmp.write(bytes)
+        tmp.flush
+        yield tmp
+      ensure
+        tmp&.close
+        tmp&.unlink
+      end
+
+      # @return [Hash, nil] the LSP `Diagnostic` Hash, or nil to
+      #   skip diagnostics outside the buffer's own path (e.g.
+      #   `.rigor.yml`-anchored info diagnostics get filtered —
+      #   they belong to the project, not the buffer).
+      def to_lsp_diagnostic(diagnostic, buffer_path)
+        return nil if diagnostic.path != buffer_path
+
+        # Rigor uses 1-based line + 1-based byte column; LSP uses
+        # 0-based line + 0-based UTF-16 code unit. UTF-16 conversion
+        # is queued (design doc § "Open questions"); v1 emits byte
+        # columns which are correct for ASCII source.
+        line = (diagnostic.line - 1).clamp(0, Float::INFINITY).to_i
+        character = (diagnostic.column - 1).clamp(0, Float::INFINITY).to_i
+
+        {
+          range: {
+            start: { line: line, character: character },
+            end: { line: line, character: character }
+          },
+          severity: SEVERITY_MAP.fetch(diagnostic.severity, 3),
+          code: diagnostic.rule,
+          source: "rigor",
+          message: diagnostic.message
+        }.compact
+      end
+
+      def notify(uri, diagnostics)
+        @writer.write(
+          method: "textDocument/publishDiagnostics",
+          params: { uri: uri, diagnostics: diagnostics }
+        )
+      end
+    end
+  end
+end