rigortype 0.1.4 → 0.1.6

data/lib/rigor/builtins/regex_refinement.rb

@@ -9,7 +9,7 @@ module Rigor
     # (`decimal-int-string`, `hex-int-string`, `octal-int-string`,
     # `lowercase-string`, `uppercase-string`, `numeric-string`).
     # See `docs/type-specification/imported-built-in-types.md` for
-    # the registry the refinements come from and `docs/MILESTONES.md`
+    # the registry the refinements come from and `docs/ROADMAP.md`
     # § "v0.1.1 — Planned" Track 1 slice 1 for the binding scope of
     # this recogniser.
     #
@@ -47,17 +47,22 @@ module Rigor
       QUANTIFIER_SOURCE = '(?:\+|\{\d+(?:,\d+)?\})'
       private_constant :QUANTIFIER_SOURCE
 
-      RULES = [
-        [/\A\\d#{QUANTIFIER_SOURCE}\z/, :decimal_int_string],
-        [/\A\\h#{QUANTIFIER_SOURCE}\z/, :hex_int_string],
-        [/\A\[0-9a-fA-F\]#{QUANTIFIER_SOURCE}\z/, :hex_int_string],
-        [/\A\[0-9a-f\]#{QUANTIFIER_SOURCE}\z/, :hex_int_string],
-        [/\A\[0-9A-F\]#{QUANTIFIER_SOURCE}\z/, :hex_int_string],
-        [/\A\[0-7\]#{QUANTIFIER_SOURCE}\z/, :octal_int_string],
-        [/\A\[a-z\]#{QUANTIFIER_SOURCE}\z/, :lowercase_string],
-        [/\A\[A-Z\]#{QUANTIFIER_SOURCE}\z/, :uppercase_string],
-        [/\A\[\[:digit:\]\]#{QUANTIFIER_SOURCE}\z/, :numeric_string]
-      ].freeze
+      # ADR-15 Phase 4b.x — `Ractor.make_shareable` (not `.freeze`)
+      # because the outer Array contains two-element `[Regexp, Symbol]`
+      # rows whose inner Arrays are not frozen by the outer freeze.
+      # A worker Ractor iterating `RULES.find { ... }` would trip
+      # `Ractor::IsolationError` on the first row access.
+      RULES = Ractor.make_shareable([
+                                      [/\A\\d#{QUANTIFIER_SOURCE}\z/, :decimal_int_string],
+                                      [/\A\\h#{QUANTIFIER_SOURCE}\z/, :hex_int_string],
+                                      [/\A\[0-9a-fA-F\]#{QUANTIFIER_SOURCE}\z/, :hex_int_string],
+                                      [/\A\[0-9a-f\]#{QUANTIFIER_SOURCE}\z/, :hex_int_string],
+                                      [/\A\[0-9A-F\]#{QUANTIFIER_SOURCE}\z/, :hex_int_string],
+                                      [/\A\[0-7\]#{QUANTIFIER_SOURCE}\z/, :octal_int_string],
+                                      [/\A\[a-z\]#{QUANTIFIER_SOURCE}\z/, :lowercase_string],
+                                      [/\A\[A-Z\]#{QUANTIFIER_SOURCE}\z/, :uppercase_string],
+                                      [/\A\[\[:digit:\]\]#{QUANTIFIER_SOURCE}\z/, :numeric_string]
+                                    ])
       private_constant :RULES
 
       BOUND_RE = /\{(\d+)(?:,(\d+))?\}\z/

data/lib/rigor/builtins/static_return_refinements.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require_relative "../type"
+
+module Rigor
+  module Builtins
+    # Static return-type refinements for stdlib (or other built-in)
+    # methods whose upstream RBS signature is broader than the
+    # method's documented behaviour and where adding a
+    # `%a{rigor:v1:return: ...}` annotation upstream is impractical
+    # (the RBS lives in the vendored `ruby/rbs` submodule).
+    #
+    # This tier sits in `MethodDispatcher.dispatch` between the
+    # HKT-builtin tier (which handles parametric / shape-bearing
+    # returns like `JSON.parse`'s `json::value`) and the RBS
+    # dispatch tier (the canonical lookup). It is consulted only
+    # when the method name and arg shape match an entry in the
+    # table below, so the standard RBS path stays in charge of
+    # every other call.
+    #
+    # Match policy:
+    #
+    # - Entries are keyed by `(owner_class_name, method_name,
+    #   kind)`. `owner_class_name` is the class that *defines*
+    #   the method (e.g., `"Kernel"`), not necessarily the
+    #   receiver's static class — Kernel methods are mixed into
+    #   every non-BasicObject class, so a `__dir__` call on any
+    #   receiver routes here.
+    # - `kind: :both` matches both the singleton-receiver
+    #   shape (`Kernel.__dir__`, `Singleton[Kernel]` receiver)
+    #   AND the instance-receiver shape (an implicit-self call
+    #   like `__dir__` inside any class body, or `obj.__dir__`
+    #   on an instance).
+    # - `kind: :singleton` / `kind: :instance` restrict the
+    #   match to one of the two shapes.
+    # - The handler is called with `(arg_types)` so future
+    #   entries can refine based on argument types (e.g. a
+    #   `File.expand_path(string)` entry that returns
+    #   `non-empty-string` regardless of the upstream return).
+    #
+    # The override fires ABOVE RBS dispatch — if RBS would have
+    # returned a wider type (`String?` for `Kernel#__dir__`), the
+    # override returns the refined union (`non-empty-string | nil`)
+    # instead. RBS erasure of the refined return goes back to the
+    # original upstream shape, so downstream RBS-shaped observers
+    # see no difference.
+    module StaticReturnRefinements
+      # Pre-built carrier reused across calls so structural
+      # equality matches across analyzer invocations.
+      NON_EMPTY_STRING_OR_NIL = Type::Combinator.union(
+        Type::Combinator.non_empty_string,
+        Type::Combinator.constant_of(nil)
+      ).freeze
+      private_constant :NON_EMPTY_STRING_OR_NIL
+
+      # `Kernel#__dir__` returns the canonical directory of the
+      # source file the call appears in, or `nil` when the file
+      # is invalid / not available (typically `-e` and similar
+      # one-liner contexts). When non-nil the value is always a
+      # filesystem-canonical path — never the empty string — so
+      # `non-empty-string` is exact.
+      KERNEL_DIR = ->(_arg_types) { NON_EMPTY_STRING_OR_NIL }
+      private_constant :KERNEL_DIR
+
+      # Frozen ((owner_class_name, method_name, kind) => handler)
+      # table. The kind tag is `:both`, `:singleton`, or
+      # `:instance`. New entries SHOULD prefer `:both` unless the
+      # singleton- and instance-side shapes genuinely differ.
+      OVERRIDES = {
+        ["Kernel", :__dir__, :both] => KERNEL_DIR
+      }.freeze
+      private_constant :OVERRIDES
+
+      # Looks up a refined return type for the given call.
+      #
+      # @param owner_class_name [String, nil] the class on which
+      #   the method is defined (e.g., `"Kernel"`). Pass `nil`
+      #   when the caller hasn't resolved a defining owner yet —
+      #   the lookup will then fall back to matching by
+      #   `(method_name, kind)` against entries whose owner is
+      #   currently in the table.
+      # @param method_name [Symbol]
+      # @param kind [Symbol] one of `:singleton`, `:instance`. The
+      #   caller passes the shape of the actual call site; the
+      #   table stores `:both` for entries that match either.
+      # @param arg_types [Array<Rigor::Type>] positional argument
+      #   types. Forwarded to the handler so future entries can
+      #   discriminate on argument shape.
+      # @return [Rigor::Type, nil] the refined return type, or
+      #   `nil` when no override matches.
+      def self.lookup(owner_class_name:, method_name:, kind:, arg_types: [])
+        return nil if owner_class_name.nil?
+
+        method_sym = method_name.to_sym
+        handler = OVERRIDES[[owner_class_name, method_sym, :both]] ||
+                  OVERRIDES[[owner_class_name, method_sym, kind]]
+        handler&.call(arg_types)
+      end
+
+      # Indexed view by `(method_name, kind)` — used by the
+      # dispatcher when the receiver's owner is not yet resolved
+      # but the method name alone uniquely identifies a stdlib
+      # override (today: `__dir__` → Kernel). The table is small
+      # and the index rebuild cost trivial, but precomputing keeps
+      # `dispatch`'s hot path free of an O(n) scan.
+      OWNERS_BY_METHOD = OVERRIDES.each_with_object({}) do |((owner, mname, _kind), _h), acc|
+        acc[mname] ||= []
+        acc[mname] << owner unless acc[mname].include?(owner)
+      end.freeze
+      private_constant :OWNERS_BY_METHOD
+
+      # @return [Array<String>] the candidate owner class names
+      #   for a bare method-name lookup. Empty when no override
+      #   names this method.
+      def self.owners_for(method_name)
+        OWNERS_BY_METHOD[method_name.to_sym] || []
+      end
+    end
+  end
+end

data/lib/rigor/cache/rbs_descriptor.rb

@@ -28,7 +28,9 @@ module Rigor
       end
 
       def self.file_entries(loader)
-        loader.signature_paths.flat_map do |root|
+        roots = loader.signature_paths +
+                Rigor::Environment::RbsLoader.vendored_gem_sig_paths
+        roots.flat_map do |root|
           next [] unless root.directory?
 
           Dir.glob(root.join("**", "*.rbs")).map do |path|

data/lib/rigor/cache/store.rb

@@ -3,6 +3,7 @@
 require "digest"
 require "fileutils"
 require "json"
+require "monitor"
 require "securerandom"
 
 require_relative "descriptor"
@@ -21,7 +22,7 @@ module Rigor
     # next write replaces the bad entry. The trailing SHA-256 catches
     # accidental corruption (partial writes, FS errors); it is **not**
     # a security boundary, per ADR-2's trusted-gem trust model.
-    class Store
+    class Store # rubocop:disable Metrics/ClassLength
       # Header literal: 5-byte ASCII magic, 1-byte separator, 1-byte
       # format version. Bumped on incompatible on-disk format changes
       # (independent of {Descriptor::SCHEMA_VERSION}, which covers
@@ -30,16 +31,55 @@ module Rigor
 
       VALID_PRODUCER_ID = /\A[a-z][a-z0-9._-]*\z/
 
-      def initialize(root:)
+      # @param root [String] cache root directory.
+      # @param read_only [Boolean] when true, every disk-side
+      #   side-effect is suppressed: `fetch_or_compute` still
+      #   reads existing entries (hits) and still runs the
+      #   producer block on miss, but it does NOT write the
+      #   produced value to disk, does NOT update the
+      #   `schema_version.txt` marker, and does NOT touch the
+      #   on-disk root directory. The in-process memo is still
+      #   populated so repeated lookups within the same run stay
+      #   cheap. Used by editor mode so multiple buffer-mode
+      #   invocations can read from the same cache concurrently
+      #   without churning it. See
+      #   `docs/design/20260516-editor-mode.md` § "Cache behaviour".
+      def initialize(root:, read_only: false)
         @root = root.to_s.dup.freeze
+        @read_only = read_only
         @hits = 0
         @misses = 0
         @writes = 0
         @by_producer = Hash.new { |h, k| h[k] = { hits: 0, misses: 0, writes: 0 } }
+        # Process-level in-memory layer keyed by
+        # `(producer_id, cache_key)`. Avoids the disk read +
+        # `Marshal.load` cost (the dominant share of repeated
+        # cache-hit calls per stackprof) when many short-lived
+        # `Analysis::Runner` instances share one `Store` — the
+        # spec process, the LSP daemon's repeated re-check
+        # path, and any other "many runs, same project" loop.
+        # Keys are content-derived (descriptor digests), so
+        # cross-fixture contamination is impossible.
+        @memo = {}
+        # `Analysis::Runner` walks files concurrently (file-
+        # level parallelism); the per-file workers share one
+        # Store. The monitor guards `@memo` + the counter
+        # hashes against concurrent writes. The Monitor is
+        # re-entrant so producer blocks can recursively
+        # consult the Store (e.g. one cache layer building on
+        # another) without dead-locking.
+        @monitor = Monitor.new
       end
 
       attr_reader :root
 
+      # @return [Boolean] whether this Store suppresses disk writes
+      #   (`schema_version.txt`, entry creation). Reads are
+      #   unaffected.
+      def read_only?
+        @read_only
+      end
+
       # Returns a frozen snapshot of this Store's per-run hit / miss /
       # write counters. The bookkeeping is in-memory only — every new
       # `Store.new` starts at zero — so the counters reflect activity
@@ -49,8 +89,10 @@ module Rigor
       #
       # @return [Hash] `{ hits:, misses:, writes:, by_producer: { id => { hits:, misses:, writes: } } }`
       def stats
-        per_producer = @by_producer.transform_values { |counts| counts.dup.freeze }.freeze
-        { hits: @hits, misses: @misses, writes: @writes, by_producer: per_producer }.freeze
+        @monitor.synchronize do
+          per_producer = @by_producer.transform_values { |counts| counts.dup.freeze }.freeze
+          { hits: @hits, misses: @misses, writes: @writes, by_producer: per_producer }.freeze
+        end
       end
 
       # Walks the on-disk cache rooted at `root` and reports a
@@ -128,18 +170,30 @@ module Rigor
         ensure_schema_version!
 
         key = descriptor.cache_key_for(producer_id: producer_id, params: params)
-        path = entry_path(producer_id, key)
+        memo_key = [producer_id, key].freeze
+        memoed = @monitor.synchronize { @memo[memo_key] if @memo.key?(memo_key) }
+        unless memoed.nil?
+          @monitor.synchronize { record(:hits, producer_id) }
+          return memoed
+        end
 
+        path = entry_path(producer_id, key)
         cached = read_entry(path, deserialize: deserialize)
         unless cached.nil?
-          record(:hits, producer_id)
+          @monitor.synchronize do
+            record(:hits, producer_id)
+            @memo[memo_key] = cached.value
+          end
           return cached.value
         end
 
-        record(:misses, producer_id)
         value = block.call
-        write_entry(path, descriptor, value, serialize: serialize)
-        record(:writes, producer_id)
+        write_entry(path, descriptor, value, serialize: serialize) unless @read_only
+        @monitor.synchronize do
+          record(:misses, producer_id)
+          record(:writes, producer_id) unless @read_only
+          @memo[memo_key] = value
+        end
         value
       end
 
@@ -269,6 +323,15 @@ module Rigor
       end
 
       def ensure_schema_version!
+        # Read-only stores never touch the cache root — no mkdir,
+        # no marker write, no destructive clear on schema
+        # mismatch. A stale or wrong-schema marker simply yields
+        # nothing back (entries read through the version check
+        # are content-keyed, so a write under the new schema
+        # never collides with a read under the old). The next
+        # writable run will repair the cache.
+        return if @read_only
+
         FileUtils.mkdir_p(@root)
         marker = File.join(@root, "schema_version.txt")
         current = Descriptor::SCHEMA_VERSION.to_s

data/lib/rigor/cli/lsp_command.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require "optionparser"
+
+module Rigor
+  class CLI
+    # Executes the `rigor lsp` command.
+    #
+    # See `docs/design/20260517-language-server.md` for the design.
+    # Slice 1 (this commit) ships the CLI subcommand entry point.
+    # The actual stdio JSON-RPC reader / writer is queued for slice 2;
+    # invoking `rigor lsp` at slice 1 returns immediately after
+    # validating the transport flag.
+    class LspCommand
+      USAGE = "Usage: rigor lsp [options]"
+
+      def initialize(argv:, out:, err:)
+        @argv = argv
+        @out = out
+        @err = err
+      end
+
+      # @return [Integer] CLI exit status.
+      def run
+        options = parse_options
+        return CLI::EXIT_USAGE if options == :usage_error
+
+        transport = options.fetch(:transport)
+        unless transport == "stdio"
+          @err.puts("rigor lsp: unsupported transport: #{transport.inspect} (only `stdio` is supported in v1)")
+          return CLI::EXIT_USAGE
+        end
+
+        require_relative "../language_server"
+        require_relative "../configuration"
+        require "language_server-protocol"
+
+        # STDIN is read frame-by-frame via the gem's `Io::Reader`;
+        # STDOUT is wrapped in `SynchronizedWriter` so concurrent
+        # writes from the main dispatch thread + the Debouncer's
+        # async threads don't interleave frames. The Loop runs
+        # until either STDIN hits EOF or `server.exited?`; the
+        # process then exits with the server's recorded code
+        # (0 after a clean shutdown+exit, 1 otherwise).
+        writer = LanguageServer::SynchronizedWriter.new(
+          ::LanguageServer::Protocol::Transport::Io::Writer.new($stdout)
+        )
+        server, loop_runner = build_server(writer: writer, config_path: options.fetch(:config))
+        loop_runner.run
+        server.exit_code || 0
+      end
+
+      private
+
+      # Builds the full collaborator graph from a fresh
+      # `Configuration` + `ProjectContext`. Returns `[server,
+      # loop]` so the caller drives the loop and reads
+      # `server.exit_code` for the process exit status.
+      def build_server(writer:, config_path:) # rubocop:disable Metrics/MethodLength
+        configuration = Configuration.load(config_path)
+        # ProjectContext caches Environment + Cache::Store across
+        # requests so hover / publish hit the warm path. Invalidated
+        # by `workspace/didChangeWatchedFiles` and
+        # `workspace/didChangeConfiguration`.
+        project_context = LanguageServer::ProjectContext.new(configuration: configuration)
+        # Single source of truth for buffer state — threaded to
+        # Server + all three providers.
+        buffer_table = LanguageServer::BufferTable.new
+        debouncer = LanguageServer::Debouncer.new
+        publisher = LanguageServer::DiagnosticPublisher.new(
+          writer: writer, buffer_table: buffer_table, project_context: project_context,
+          debouncer: debouncer, debounce_seconds: 0.2
+        )
+        server = LanguageServer::Server.new(
+          buffer_table: buffer_table,
+          publisher: publisher,
+          hover_provider: LanguageServer::HoverProvider.new(
+            buffer_table: buffer_table, project_context: project_context
+          ),
+          document_symbol_provider: LanguageServer::DocumentSymbolProvider.new(
+            buffer_table: buffer_table, project_context: project_context
+          ),
+          completion_provider: LanguageServer::CompletionProvider.new(
+            buffer_table: buffer_table, project_context: project_context
+          ),
+          signature_help_provider: LanguageServer::SignatureHelpProvider.new(
+            buffer_table: buffer_table, project_context: project_context
+          ),
+          folding_range_provider: LanguageServer::FoldingRangeProvider.new(
+            buffer_table: buffer_table, project_context: project_context
+          ),
+          selection_range_provider: LanguageServer::SelectionRangeProvider.new(
+            buffer_table: buffer_table, project_context: project_context
+          ),
+          project_context: project_context
+        )
+        loop_runner = LanguageServer::Loop.new(
+          reader: ::LanguageServer::Protocol::Transport::Io::Reader.new($stdin),
+          writer: writer,
+          server: server
+        )
+        [server, loop_runner]
+      end
+
+      def parse_options
+        options = { transport: "stdio", log: nil, config: nil }
+
+        parser = OptionParser.new do |opts|
+          opts.banner = USAGE
+          opts.on("--transport=NAME", "Transport (default: stdio; only stdio supported in v1)") do |value|
+            options[:transport] = value
+          end
+          opts.on("--log=PATH", "Write LSP wire log + server debug to PATH (default: stderr)") do |value|
+            options[:log] = value
+          end
+          opts.on("--config=PATH", "Path to the Rigor configuration file") do |value|
+            options[:config] = value
+          end
+        end
+        parser.parse!(@argv)
+        options
+      rescue OptionParser::ParseError => e
+        @err.puts(e.message)
+        @err.puts(USAGE)
+        :usage_error
+      end
+    end
+  end
+end

data/lib/rigor/cli/type_of_command.rb

@@ -3,6 +3,7 @@
 require "optionparser"
 require "prism"
 
+require_relative "../analysis/buffer_binding"
 require_relative "../configuration"
 require_relative "../environment"
 require_relative "../scope"
@@ -38,35 +39,73 @@ module Rigor
       # @return [Integer] CLI exit status.
       def run
         options = parse_options
+        buffer = resolve_buffer_binding(options)
+        return CLI::EXIT_USAGE if buffer == :usage_error
 
         target = parse_position_argument(@argv)
         return CLI::EXIT_USAGE if target.nil?
 
-        execute(target: target, options: options)
+        execute(target: target, options: options, buffer: buffer)
       end
 
       private
 
       def parse_options
-        options = { format: "text", trace: false, config: nil }
+        options = { format: "text", trace: false, config: nil, tmp_file: nil, instead_of: nil }
 
         parser = OptionParser.new do |opts|
           opts.banner = USAGE
           opts.on("--format=FORMAT", "Output format: text or json") { |value| options[:format] = value }
           opts.on("--trace", "Record fail-soft fallbacks via FallbackTracer") { options[:trace] = true }
           opts.on("--config=PATH", "Path to the Rigor configuration file") { |value| options[:config] = value }
+          opts.on("--tmp-file=PATH",
+                  "Editor mode: read source bytes from PATH instead of --instead-of (paired)") do |value|
+            options[:tmp_file] = value
+          end
+          opts.on("--instead-of=PATH",
+                  "Editor mode: the logical project path the buffer represents (paired with --tmp-file)") do |value|
+            options[:instead_of] = value
+          end
         end
         parser.parse!(@argv)
 
         options
       end
 
-      def execute(target:, options:)
+      # Mirrors `Rigor::CLI#resolve_buffer_binding` (the `check`
+      # path). Returns nil / BufferBinding / :usage_error. The
+      # symbol return path lets the caller translate to
+      # `CLI::EXIT_USAGE` without raising.
+      def resolve_buffer_binding(options)
+        tmp = options[:tmp_file]
+        instead = options[:instead_of]
+        return nil if tmp.nil? && instead.nil?
+
+        if tmp.nil? || instead.nil?
+          @err.puts("--tmp-file and --instead-of must appear together")
+          return :usage_error
+        end
+
+        unless File.file?(tmp)
+          @err.puts("--tmp-file #{tmp.inspect}: no such file or not readable")
+          return :usage_error
+        end
+
+        Rigor::Analysis::BufferBinding.new(logical_path: instead, physical_path: tmp)
+      end
+
+      def execute(target:, options:, buffer: nil)
         file, line, column = target
-        return 1 unless file_exists?(file)
+        # Under editor mode the logical `file` may not exist on disk
+        # (user editing a new file); the runtime check is only that
+        # the BUFFER is readable, which `resolve_buffer_binding`
+        # has already enforced. For non-editor mode `file` must
+        # exist.
+        physical = buffer ? buffer.resolve(file) : file
+        return 1 unless file_exists?(buffer ? physical : file)
 
         configuration = Configuration.load(options.fetch(:config))
-        source = File.read(file)
+        source = File.read(physical)
         parse_result = Prism.parse(source, filepath: file, version: configuration.target_ruby)
         return 1 if parse_errors?(parse_result, file)