rigortype 0.1.5 → 0.1.7

data/lib/rigor/language_server/signature_help_provider.rb

@@ -0,0 +1,249 @@
+# 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/refined"
+require_relative "../type/difference"
+require_relative "../type/tuple"
+require_relative "../type/hash_shape"
+
+module Rigor
+  module LanguageServer
+    # Answers `textDocument/signatureHelp` requests. When the user
+    # types `(` inside a method call (`obj.foo(|`) editors fire
+    # `signatureHelp` to show the method's parameter signature
+    # inline. The provider parses the buffer, locates the enclosing
+    # `CallNode`, infers the receiver's type, and returns the
+    # method's first overload as a `SignatureInformation`.
+    #
+    # Slice C1 (this commit) ships:
+    # - Sentinel patching for `obj.foo(|` so Prism's parse
+    #   succeeds (mirrors `CompletionProvider`'s slice B4 pattern).
+    # - First-overload signature only.
+    # - Active parameter = comma count before cursor.
+    #
+    # Multi-overload presentation + `documentation` field +
+    # active-parameter override per overload land in follow-up
+    # slices (queued in the design doc § "Out of scope for v2").
+    class SignatureHelpProvider
+      ARG_SENTINEL = "__rigor_lsp_arg_sentinel__"
+      private_constant :ARG_SENTINEL
+
+      def initialize(buffer_table:, project_context:)
+        @buffer_table = buffer_table
+        @project_context = project_context
+      end
+
+      # @return [Hash, nil] LSP `SignatureHelp` payload or nil
+      #   when the cursor isn't inside a resolvable method call.
+      def provide(uri:, line:, character:, context: nil)
+        _ = context # Trigger info accepted but not routed in v1.
+        path = Uri.to_path(uri)
+        return nil if path.nil?
+
+        entry = @buffer_table[uri]
+        return nil if entry.nil?
+
+        bytes, locate_at = parse_attempt_bytes(entry.bytes, line, character)
+        parse_result = Prism.parse(bytes, filepath: path,
+                                          version: @project_context.configuration.target_ruby)
+        return nil unless parse_result.errors.empty?
+
+        cursor_offset = byte_offset_for(bytes, locate_at[0], locate_at[1])
+        return nil if cursor_offset.nil?
+
+        call_node = enclosing_call_for_offset(parse_result.value, cursor_offset)
+        return nil if call_node.nil?
+
+        build_signature(call_node, parse_result.value, path, bytes, locate_at[0], locate_at[1])
+      end
+
+      private
+
+      def parse_attempt_bytes(original_bytes, line, character)
+        return [original_bytes, [line, character]] if Prism.parse(original_bytes).errors.empty?
+
+        patch_with_arg_sentinel(original_bytes, line, character)
+      end
+
+      # Mid-edit buffer at `obj.foo(|` or `obj.foo(1,|`: truncate
+      # everything from the cursor onwards and append `SENTINEL)`
+      # so the call is syntactically complete. The truncation is
+      # aggressive — signatureHelp only cares about the enclosing
+      # call's signature; downstream content (closing parens,
+      # subsequent statements) is irrelevant.
+      def patch_with_arg_sentinel(original_bytes, line, character)
+        prefix_offset = byte_offset_for(original_bytes, line, character)
+        return [original_bytes, [line, character]] if prefix_offset.nil?
+
+        prefix = original_bytes.byteslice(0, prefix_offset)
+        stripped = prefix.rstrip
+        return [original_bytes, [line, character]] unless stripped.end_with?("(") || stripped.end_with?(",")
+
+        patched = "#{prefix}#{ARG_SENTINEL})\n"
+        [patched, [line, character]]
+      end
+
+      # Walks the AST for the smallest CallNode whose `arguments`
+      # location encloses the cursor offset. Prism doesn't expose
+      # parent pointers, so NodeLocator's leaf-returning shape
+      # isn't enough; we re-walk. For LSP usage this is cheap —
+      # the buffer is parsed once per request.
+      def enclosing_call_for_offset(root, cursor_offset)
+        result = nil
+        walk = lambda do |n|
+          next unless n.is_a?(Prism::Node)
+
+          if n.is_a?(Prism::CallNode) && n.arguments && offset_in?(n.arguments.location, cursor_offset)
+            result = n # Innermost-wins because we keep walking children.
+          end
+          n.compact_child_nodes.each(&walk)
+        end
+        walk.call(root)
+        result
+      end
+
+      def offset_in?(location, offset)
+        offset.between?(location.start_offset, location.end_offset)
+      end
+
+      def build_signature(call_node, root, path, bytes, line, character)
+        scope_index = build_scope_index(root, path)
+        receiver_node = call_node.receiver
+        return nil if receiver_node.nil?
+
+        receiver_type = scope_index[receiver_node].type_of(receiver_node)
+        definition = lookup_method(receiver_type, call_node.name, scope_index[receiver_node])
+        return nil if definition.nil? || definition.method_types.empty?
+
+        active_param = active_parameter_index(call_node, bytes, line, character)
+        doc = rbs_documentation(definition)
+        signatures = definition.method_types.map do |method_type|
+          info = {
+            label: "#{call_node.name}#{method_type}",
+            parameters: parameter_information(method_type)
+          }
+          info[:documentation] = { kind: "markdown", value: doc } if doc
+          info
+        end
+        {
+          signatures: signatures,
+          # `activeSignature` is the index editors highlight by
+          # default. Slice C2 picks the first overload uniformly;
+          # a future slice could choose the overload that best
+          # matches the current argument shape.
+          activeSignature: 0,
+          activeParameter: active_param
+        }
+      end
+
+      # Builds the LSP `ParameterInformation[]` for a method type's
+      # parameter list. Each entry's `label` is a STRING form
+      # (e.g. `"::int width"`, `"?::string pad_string"`); LSP's
+      # offset-tuple form (`[start, end]`) for in-signature
+      # highlighting is queued. Order matches `activeParameter`'s
+      # index expectation: required positionals, then optionals,
+      # then rest, then trailing, then required keywords, then
+      # optional keywords, then rest keywords.
+      def parameter_information(method_type) # rubocop:disable Metrics/AbcSize
+        func = method_type.type
+        return [] unless func.respond_to?(:required_positionals)
+
+        params = func.required_positionals.map { |p| { label: format_param(p) } }
+        func.optional_positionals.each { |p| params << { label: "?#{format_param(p)}" } }
+        params << { label: "*#{format_param(func.rest_positionals)}" } if func.rest_positionals
+        func.trailing_positionals.each { |p| params << { label: format_param(p) } }
+        func.required_keywords.each { |name, p| params << { label: "#{name}: #{format_param(p)}" } }
+        func.optional_keywords.each { |name, p| params << { label: "?#{name}: #{format_param(p)}" } }
+        params << { label: "**#{format_param(func.rest_keywords)}" } if func.rest_keywords
+        params
+      end
+
+      def format_param(param)
+        param.name ? "#{param.type} #{param.name}" : param.type.to_s
+      end
+
+      # Identical contract to HoverRenderer#rbs_documentation —
+      # surfaces the method's RBS comment text or nil. Kept inline
+      # rather than extracted to a shared mixin because the two
+      # call sites are small and the shape may diverge (signatureHelp
+      # might want per-parameter docs split out; hover wants the
+      # full paragraph).
+      def rbs_documentation(definition)
+        comments = definition.respond_to?(:comments) ? definition.comments : nil
+        return nil if comments.nil? || comments.empty?
+
+        text = comments.map(&:string).join("\n\n").strip
+        text.empty? ? nil : text
+      end
+
+      def lookup_method(receiver_type, method_name, scope)
+        case receiver_type
+        when Type::Singleton
+          Reflection.singleton_method_definition(receiver_type.class_name, method_name, scope: scope)
+        when Type::Refined, Type::Difference
+          lookup_method(receiver_type.base, method_name, scope)
+        else
+          class_name = nominal_class_name(receiver_type)
+          return nil if class_name.nil?
+
+          Reflection.instance_method_definition(class_name, method_name, scope: scope)
+        end
+      end
+
+      # Mirrors CompletionProvider's receiver-type mapping. Tuple →
+      # Array, HashShape → Hash, Refined / Difference unwrap to
+      # their base (handled in `lookup_method` above for clarity).
+      def nominal_class_name(type)
+        case type
+        when Type::Nominal then type.class_name
+        when Type::Constant then type.value.class.name
+        when Type::Tuple then "Array"
+        when Type::HashShape then "Hash"
+        end
+      end
+
+      def build_scope_index(root, _path)
+        scope = Scope.empty(environment: @project_context.environment)
+        Inference::ScopeIndexer.index(root, default_scope: scope)
+      end
+
+      # Counts commas in the buffer between the call's opening `(`
+      # and the cursor position. Cursor on the first argument → 0;
+      # after one comma → 1; etc. Bounded by the call's arguments
+      # location so commas in nested expressions don't bleed in.
+      def active_parameter_index(call_node, bytes, line, character)
+        return 0 if call_node.arguments.nil?
+
+        cursor_offset = byte_offset_for(bytes, line, character)
+        args_loc = call_node.arguments.location
+        return 0 if args_loc.nil? || cursor_offset.nil?
+
+        scan_start = args_loc.start_offset
+        scan_end = [cursor_offset, args_loc.end_offset].min
+        return 0 if scan_end <= scan_start
+
+        bytes.byteslice(scan_start, scan_end - scan_start).count(",")
+      end
+
+      def byte_offset_for(bytes, line, character)
+        offset = 0
+        bytes.each_line.with_index do |line_bytes, idx|
+          return offset + character if idx == line
+
+          offset += line_bytes.bytesize
+        end
+        nil
+      end
+    end
+  end
+end

data/lib/rigor/language_server/synchronized_writer.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Rigor
+  module LanguageServer
+    # Wraps the LSP gem's `Io::Writer` with a Mutex so concurrent
+    # writes (the dispatch loop's response writes + the Debouncer's
+    # async `publishDiagnostics` writes) don't interleave on the
+    # shared STDOUT.
+    #
+    # Pass-through proxy: `#write(message)` is the only call site
+    # the rest of the LSP uses; `#close` is forwarded for
+    # completeness.
+    class SynchronizedWriter
+      def initialize(inner)
+        @inner = inner
+        @mutex = Mutex.new
+      end
+
+      def write(message)
+        @mutex.synchronize { @inner.write(message) }
+      end
+
+      def close
+        @mutex.synchronize { @inner.close }
+      end
+    end
+  end
+end

data/lib/rigor/language_server/uri.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Rigor
+  module LanguageServer
+    # LSP DocumentUri ↔ filesystem path conversions. v1 supports
+    # only `file://` URIs; other schemes (e.g. `untitled:`) return
+    # nil from `#to_path` so the caller can short-circuit.
+    #
+    # Windows drive-letter handling: `file:///C:/path` → `C:/path`.
+    # The leading slash after the scheme is dropped on Windows; on
+    # POSIX it stays. v1 ships POSIX behaviour; Windows specifics
+    # land when Windows CI is wired (see design doc § "Open
+    # questions").
+    module Uri
+      module_function
+
+      FILE_SCHEME = "file://"
+      private_constant :FILE_SCHEME
+
+      # @return [String, nil] absolute filesystem path for a
+      #   `file://` URI, or nil for unsupported schemes.
+      def to_path(uri)
+        return nil unless uri.is_a?(String) && uri.start_with?(FILE_SCHEME)
+
+        # Percent-decode at the BYTE level so multi-byte UTF-8
+        # escapes (`%E6%97%A5` → `日`) reassemble correctly. Each
+        # `%xx` decodes to one raw byte; the result is a byte string
+        # we re-interpret as UTF-8. `delete_prefix` always returns
+        # a String (vs `byteslice` whose RBS return is `String?`).
+        uri.delete_prefix(FILE_SCHEME).b
+           .gsub(/%([0-9A-Fa-f]{2})/) { ::Regexp.last_match(1).hex.chr }
+           .force_encoding(Encoding::UTF_8)
+      end
+
+      def from_path(path)
+        "#{FILE_SCHEME}#{path}"
+      end
+    end
+  end
+end

data/lib/rigor/language_server.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Rigor
+  # The Language Server subsystem. See
+  # `docs/design/20260517-language-server.md` for the design.
+  # Slice 1 ships the namespace + a minimal {Server} lifecycle the
+  # `rigor lsp` CLI subcommand can drive. Later slices add the
+  # stdio JSON-RPC transport (slice 2), the BufferTable (slice 3),
+  # `publishDiagnostics` (slice 4), and the rest of the v1 capability
+  # surface.
+  module LanguageServer
+  end
+end
+
+require_relative "language_server/buffer_table"
+require_relative "language_server/uri"
+require_relative "language_server/project_context"
+require_relative "language_server/debouncer"
+require_relative "language_server/synchronized_writer"
+require_relative "language_server/diagnostic_publisher"
+require_relative "language_server/hover_renderer"
+require_relative "language_server/hover_provider"
+require_relative "language_server/completion_provider"
+require_relative "language_server/signature_help_provider"
+require_relative "language_server/document_symbol_provider"
+require_relative "language_server/folding_range_provider"
+require_relative "language_server/selection_range_provider"
+require_relative "language_server/server"
+require_relative "language_server/loop"

data/lib/rigor/plugin/base.rb

@@ -243,8 +243,71 @@ module Rigor
         end
       end
 
+      # Builds a `Cache::Descriptor` covering every file matched by
+      # `pattern` (a glob, e.g. `"**/*.rb"`) under any of `roots`.
+      # Each matching file contributes a `:digest`-comparator
+      # `FileEntry` so the cache invalidates on any content change,
+      # any addition (a newly-glob-matched file appears in the
+      # descriptor), or any removal (the previously-matched file
+      # drops out).
+      #
+      # Pass the returned descriptor as `cache_for(..., descriptor: …)`
+      # so the cache key reflects the project files the producer
+      # reads from. Without it, `Plugin::Base#cache_for`'s
+      # auto-built descriptor only includes files the
+      # {Plugin::IoBoundary} has already read in the current
+      # process — empty on the first call of a fresh process — so
+      # the cache key is identical regardless of project state and
+      # warm runs return stale producer output when files have
+      # changed between sessions.
+      #
+      # Discovery-style producers (`actioncable`'s `:channel_index`,
+      # `actionmailer`'s `:mailer_index`, `rails-i18n`'s
+      # `:locale_index`) all follow the same pattern: walk a glob
+      # under one or more search roots, parse / read every match,
+      # build a typed index. They MUST call this helper at the
+      # `cache_for(descriptor: …)` site to be cache-correct under
+      # the persistent `Cache::Store` `rigor check` uses by
+      # default.
+      #
+      # The helper pays one SHA-256 read per matched file at
+      # call time; the producer block typically re-reads through
+      # `io_boundary.read_file` so the cost is doubled. For
+      # discovery globs in the 10-100 file range this is
+      # negligible (~ms) relative to the parse + walk the
+      # producer does on cache miss.
+      #
+      # @param roots    [Array<String>] search roots (relative to
+      #   the project root, or absolute paths)
+      # @param patterns [Array<String>] glob suffixes joined under
+      #   each root via `File.join(root, pattern)`. Multiple
+      #   patterns union into one descriptor (`"**/*.erb",
+      #   "**/*.html"` etc.).
+      # @return [Rigor::Cache::Descriptor]
+      def glob_descriptor(roots, *patterns)
+        files = collect_glob_files(Array(roots), patterns)
+        entries = files.map do |path|
+          Cache::Descriptor::FileEntry.new(
+            path: path,
+            comparator: :digest,
+            value: Digest::SHA256.file(path).hexdigest
+          )
+        end
+        Cache::Descriptor.new(files: entries)
+      end
+
       private
 
+      def collect_glob_files(roots, patterns)
+        matched = roots.flat_map do |root|
+          absolute = File.expand_path(root.to_s)
+          next [] unless File.directory?(absolute)
+
+          patterns.flat_map { |pattern| Dir.glob(File.join(absolute, pattern.to_s)) }
+        end
+        matched.uniq.sort.select { |path| File.file?(path) }
+      end
+
       # ADR-7 § "Slice 6-B" — composes the per-call cache
       # descriptor from (1) the plugin's PluginEntry template
       # and (2) the IoBoundary's accumulated FileEntry rows.

data/lib/rigor/plugin/macro/heredoc_template.rb

@@ -73,8 +73,8 @@ module Rigor
       # This file ships the value class only. Slice 2b wires the
       # pre-pass that scans Tier C call sites + the
       # `SyntheticMethodIndex` the dispatcher consults; slice 2c
-      # authors `examples/rigor-dry-struct/` and
-      # `examples/rigor-dry-types/` as the worked consumers.
+      # authors `plugins/rigor-dry-struct/` and
+      # `plugins/rigor-dry-types/` as the worked consumers.
       class HeredocTemplate
         NAME_PLACEHOLDER = "\#{name}"
 
@@ -115,37 +115,147 @@ module Rigor
         # One row of an emit table: the synthetic method's
         # name-template (the analyzer interpolates `\#{name}` with
         # the call-site literal symbol) and its declared return
-        # type (recorded as a string in slice 2a, resolved by the
-        # ceiling slice via ADR-13).
+        # type. The return type can be a static String (resolved
+        # via `Environment#nominal_for_name` per ADR-16 slice 6b)
+        # or a per-call-site lookup ({ReturnsFromArg}) — see
+        # [ADR-18](../../../../../docs/adr/18-substrate-per-call-site-return-type.md).
+        # When both are nil, the synthesised method's return type
+        # falls back to `Dynamic[Top]`.
         class Emit
-          attr_reader :name, :returns
+          attr_reader :name, :returns, :returns_from_arg
 
-          def initialize(name:, returns:)
+          def initialize(name:, returns: nil, returns_from_arg: nil)
             unless name.is_a?(String) && !name.empty?
               raise ArgumentError,
                     "Macro::HeredocTemplate::Emit#name must be a non-empty String, got #{name.inspect}"
             end
-            unless returns.is_a?(String) && !returns.empty?
+            unless returns.nil? || (returns.is_a?(String) && !returns.empty?)
               raise ArgumentError,
-                    "Macro::HeredocTemplate::Emit#returns must be a non-empty String, got #{returns.inspect}"
+                    "Macro::HeredocTemplate::Emit#returns must be a non-empty String or nil, got #{returns.inspect}"
             end
 
             @name = name.dup.freeze
-            @returns = returns.dup.freeze
+            @returns = returns.nil? ? nil : returns.dup.freeze
+            @returns_from_arg = ReturnsFromArg.coerce(returns_from_arg)
             freeze
           end
 
           def to_h
-            { "name" => name, "returns" => returns }
+            {
+              "name" => name,
+              "returns" => returns,
+              "returns_from_arg" => returns_from_arg&.to_h
+            }.compact
           end
 
           def ==(other)
-            other.is_a?(Emit) && name == other.name && returns == other.returns
+            other.is_a?(Emit) && to_h == other.to_h
           end
           alias eql? ==
 
           def hash
-            [name, returns].hash
+            to_h.hash
+          end
+        end
+
+        # ADR-18 — per-call-site return-type DSL. Declares which
+        # call-site argument's source representation to look up
+        # in a cross-plugin fact channel for the synthesised
+        # method's return type.
+        #
+        # Authoring shape:
+        #
+        #     returns_from_arg: {
+        #       position: 1,
+        #       lookup_via: { plugin_id: "dry-types", fact: :dry_type_aliases }
+        #     }
+        #
+        # Slice 1 (this file) ships the value class + validation
+        # only. The scanner-side arg-position extraction +
+        # fact-store lookup land in slice 2 / 3.
+        class ReturnsFromArg
+          attr_reader :position, :plugin_id, :fact
+
+          # @return [ReturnsFromArg, nil] coerced value class
+          #   for a Hash / nil / ReturnsFromArg input. Raises on
+          #   any other shape so manifest authoring failures
+          #   surface at construction time.
+          def self.coerce(value)
+            return nil if value.nil?
+            return value if value.is_a?(ReturnsFromArg)
+            return new_from_hash(value) if value.is_a?(Hash)
+
+            raise ArgumentError,
+                  "Macro::HeredocTemplate::Emit#returns_from_arg must be a Hash or ReturnsFromArg, " \
+                  "got #{value.inspect}"
+          end
+
+          def self.new_from_hash(hash)
+            position = hash[:position] || hash["position"]
+            lookup_via = hash[:lookup_via] || hash["lookup_via"]
+            unless lookup_via.is_a?(Hash)
+              raise ArgumentError,
+                    "Macro::HeredocTemplate::Emit#returns_from_arg requires a `lookup_via:` Hash, " \
+                    "got #{hash.inspect}"
+            end
+            new(
+              position: position,
+              plugin_id: lookup_via[:plugin_id] || lookup_via["plugin_id"],
+              fact: lookup_via[:fact] || lookup_via["fact"]
+            )
+          end
+
+          def initialize(position:, plugin_id:, fact:)
+            validate_position!(position)
+            validate_plugin_id!(plugin_id)
+            validate_fact!(fact)
+
+            @position = position
+            @plugin_id = plugin_id.dup.freeze
+            @fact = fact.to_sym
+            freeze
+          end
+
+          def to_h
+            {
+              "position" => position,
+              "lookup_via" => {
+                "plugin_id" => plugin_id,
+                "fact" => fact.to_s
+              }
+            }
+          end
+
+          def ==(other)
+            other.is_a?(ReturnsFromArg) && to_h == other.to_h
+          end
+          alias eql? ==
+
+          def hash
+            to_h.hash
+          end
+
+          private
+
+          def validate_position!(value)
+            return if value.is_a?(Integer) && value >= 0
+
+            raise ArgumentError,
+                  "ReturnsFromArg#position must be a non-negative Integer, got #{value.inspect}"
+          end
+
+          def validate_plugin_id!(value)
+            return if value.is_a?(String) && !value.empty?
+
+            raise ArgumentError,
+                  "ReturnsFromArg#plugin_id must be a non-empty String, got #{value.inspect}"
+          end
+
+          def validate_fact!(value)
+            return if value.is_a?(Symbol) || (value.is_a?(String) && !value.empty?)
+
+            raise ArgumentError,
+                  "ReturnsFromArg#fact must be a Symbol or non-empty String, got #{value.inspect}"
           end
         end
 
@@ -188,7 +298,11 @@ module Rigor
           case entry
           when Emit then entry
           when Hash
-            Emit.new(name: entry[:name] || entry["name"], returns: entry[:returns] || entry["returns"])
+            Emit.new(
+              name: entry[:name] || entry["name"],
+              returns: entry[:returns] || entry["returns"],
+              returns_from_arg: entry[:returns_from_arg] || entry["returns_from_arg"]
+            )
           else
             raise ArgumentError,
                   "Plugin::Macro::HeredocTemplate##{label} entry must be an Emit or Hash, " \

data/lib/rigor/plugin/macro/trait_registry.rb

@@ -83,7 +83,7 @@ module Rigor
       # This file ships the value class only. Slice 3b wires the
       # scanner that walks Tier B call sites + the per-method
       # explosion via `SyntheticMethodIndex`; slice 3c authors
-      # `examples/rigor-devise/` model side as the worked consumer.
+      # `plugins/rigor-devise/` model side as the worked consumer.
       class TraitRegistry
         REST_POSITION = :rest