rigortype 0.1.5 → 0.1.6

data/lib/rigor/builtins/hkt_builtins.rb

@@ -0,0 +1,342 @@
+# frozen_string_literal: true
+
+require_relative "../inference/hkt_registry"
+require_relative "../inference/hkt_body"
+require_relative "../inference/hkt_body_parser"
+
+module Rigor
+  module Builtins
+    # ADR-20 slices 2c + 3 — Rigor-bundled Lightweight HKT
+    # registrations that ship with every analyzer instance.
+    # The set is intentionally small at v0.1.x: only the URIs
+    # whose payoff justifies hardcoded definitions. Plugin
+    # authors register more URIs through their manifests; user
+    # `.rbs` overlays register through the
+    # `%a{rigor:v1:hkt_register}` /
+    # `%a{rigor:v1:hkt_define}` annotations Slice 1 ships.
+    #
+    # Today's contents:
+    #
+    # - `json::value[K]` — the recursive sum stdlib's
+    #   `JSON.parse` returns. Body:
+    #
+    #     nil | true | false | Integer | Float | String
+    #     | Array[App[json::value, K]]
+    #     | Hash[K, App[json::value, K]]
+    #
+    #   The reducer handles the self-recursive `App` nodes via
+    #   lazy "tying-the-knot" (see {HktReducer}). `K = String`
+    #   matches stdlib's default key handling; `K = Symbol`
+    #   matches `symbolize_names: true`.
+    module HktBuiltins
+      module_function
+
+      # Built via the body-string parser (slice 2b/2c) so the
+      # bundled overlay exercises the same authoring surface
+      # third-party plugins use. The body matches what user
+      # `.rbs` overlays would write through a
+      # `%a{rigor:v1:hkt_define: ...body=...}` annotation.
+      JSON_VALUE_BODY = "nil | true | false | Integer | Float | String | " \
+                        "Array[App[json::value, K]] | Hash[K, App[json::value, K]]"
+      private_constant :JSON_VALUE_BODY
+
+      def json_value_body_tree
+        Rigor::Inference::HktBodyParser.parse(JSON_VALUE_BODY, params: [:K])
+      end
+
+      # `csv::parsed[K]` — `Array[Array[K | nil]]` (CSV.parse's
+      # no-headers shape: an Array of rows; each row is an
+      # Array of optionally-nil cell values). When
+      # `headers: true` the runtime returns a `CSV::Table` /
+      # `CSV::Row` shape instead — that case is NOT covered
+      # by the bundled override (CSV::Row is its own class
+      # with Hash + Array access; a future slice may add a
+      # separate URI or a discriminator hook for it).
+      CSV_PARSED_BODY = "Array[Array[K | nil]]"
+      private_constant :CSV_PARSED_BODY
+
+      def csv_parsed_body_tree
+        Rigor::Inference::HktBodyParser.parse(CSV_PARSED_BODY, params: [:K])
+      end
+
+      def json_value_registration
+        Rigor::Inference::HktRegistry::Registration.new(
+          uri: :"json::value",
+          arity: 1,
+          variance: [:out],
+          bound: Rigor::Type::Combinator.untyped
+        )
+      end
+
+      def json_value_definition
+        Rigor::Inference::HktRegistry.definition_with_body_tree(
+          uri: :"json::value",
+          params: [:K],
+          body_tree: json_value_body_tree,
+          source_path: __FILE__,
+          source_line: __LINE__ - 5
+        )
+      end
+
+      def csv_parsed_registration
+        Rigor::Inference::HktRegistry::Registration.new(
+          uri: :"csv::parsed",
+          arity: 1,
+          variance: [:out],
+          bound: Rigor::Type::Combinator.untyped
+        )
+      end
+
+      def csv_parsed_definition
+        Rigor::Inference::HktRegistry.definition_with_body_tree(
+          uri: :"csv::parsed",
+          params: [:K],
+          body_tree: csv_parsed_body_tree,
+          source_path: __FILE__,
+          source_line: __LINE__ - 5
+        )
+      end
+
+      # @return [Rigor::Inference::HktRegistry] frozen registry
+      #   pre-seeded with all bundled HKT registrations +
+      #   bodies. Allocated fresh each call rather than
+      #   memoised — memoisation through a module-level
+      #   `@registry` ivar surfaces a `Ractor::IsolationError`
+      #   in pool workers (the ivar's contents include
+      #   `HktBody::AppRef` Symbol-keyed structures that the
+      #   current Ractor shareability audit hasn't yet been
+      #   walked through). The registry is small enough that
+      #   per-Environment construction is acceptable; an
+      #   eager-frozen constant is a future optimisation
+      #   once ADR-15 phase 4b.x covers the dependency graph.
+      def registry
+        Rigor::Inference::HktRegistry.new(
+          registrations: [json_value_registration, csv_parsed_registration],
+          definitions: [json_value_definition, csv_parsed_definition]
+        )
+      end
+
+      # ADR-20 slice 3 — hardcoded `(class_name, method_name,
+      # kind) => HKT application` table consulted by the
+      # dispatcher's new HKT-builtin tier. Sits ABOVE
+      # `RbsDispatch.try_dispatch` so a known stdlib method
+      # (`JSON.parse`, `JSON.parse!`) gets the reduced HKT
+      # type instead of the upstream rbs gem's `untyped`
+      # return. The annotation-based `%a{rigor:v1:return:
+      # App[...]}` path (parsed by
+      # `RbsExtended.parse_return_type_override`) is the
+      # general extension surface for user-authored sigs;
+      # this table is the Rigor-bundled shortcut for the
+      # handful of stdlib methods whose RBS declarations
+      # cannot be cleanly overridden via RBS overlay merging.
+      #
+      # Each entry maps to a hash with `:uri` and `:args`
+      # (an array of Ruby class names). The dispatcher
+      # builds `Type::App.new(uri, args.map { Nominal })`,
+      # then reduces via the env's `hkt_registry` so the
+      # caller observes the unfolded form
+      # (`Union[nil, true, false, ..., Array[App[json::value,
+      # String]], Hash[String, App[json::value, String]]]`)
+      # rather than the opaque carrier.
+      JSON_VALUE_SPEC = {
+        uri: :"json::value",
+        args: ["String"],
+        discriminator: :json_symbolize_names,
+        post_reduce: nil
+      }.freeze
+      private_constant :JSON_VALUE_SPEC
+
+      # YAML / Psych.safe_load reuse the json::value reducer
+      # for the JSON-equivalent leaf set BUT additionally
+      # honour `permitted_classes: [<Class>, ...]` literal
+      # Array arguments, unioning each permitted class as an
+      # extra arm of the result. Slice 2c-bis behaviour.
+      YAML_SAFE_VALUE_SPEC = {
+        uri: :"json::value",
+        args: ["String"],
+        discriminator: :json_symbolize_names,
+        post_reduce: :yaml_permitted_classes
+      }.freeze
+      private_constant :YAML_SAFE_VALUE_SPEC
+
+      CSV_PARSED_SPEC = {
+        uri: :"csv::parsed",
+        args: ["String"],
+        discriminator: nil,
+        post_reduce: nil
+      }.freeze
+      private_constant :CSV_PARSED_SPEC
+
+      METHOD_RETURN_OVERRIDES = {
+        # JSON — stdlib's `json` library. Upstream rbs declares
+        # `(string, ?options) -> untyped`; the HKT-builtin tier
+        # tightens to the recursive `json::value[K]` union.
+        # `load_file` / `load_file!` share the `?options` slot
+        # so the `symbolize_names: true` discriminator applies
+        # to them too (just like `parse` / `load`).
+        ["JSON", :parse,      :singleton] => JSON_VALUE_SPEC,
+        ["JSON", :parse!,     :singleton] => JSON_VALUE_SPEC,
+        ["JSON", :load,       :singleton] => JSON_VALUE_SPEC,
+        ["JSON", :load_file,  :singleton] => JSON_VALUE_SPEC,
+        ["JSON", :load_file!, :singleton] => JSON_VALUE_SPEC,
+        # YAML.safe_load / Psych.safe_load — default
+        # `permitted_classes: []` admits exactly the JSON
+        # vocabulary (nil / true / false / Integer / Float /
+        # String / Array / Hash), so the json::value tree
+        # also describes them. When the call passes a literal
+        # `permitted_classes: [Date, Symbol, ...]` Array, the
+        # `:yaml_permitted_classes` post_reduce unions each
+        # named class into the result. Non-literal options
+        # (a variable, a constant reference, a `+ classes`
+        # concat) silently no-op and the caller observes the
+        # base json::value envelope only. YAML.load /
+        # YAML.unsafe_load deliberately stay out of the
+        # override table — they can return ANY Ruby object
+        # and have no useful HKT envelope.
+        ["YAML",  :safe_load,      :singleton] => YAML_SAFE_VALUE_SPEC,
+        ["YAML",  :safe_load_file, :singleton] => YAML_SAFE_VALUE_SPEC,
+        ["Psych", :safe_load,      :singleton] => YAML_SAFE_VALUE_SPEC,
+        ["Psych", :safe_load_file, :singleton] => YAML_SAFE_VALUE_SPEC,
+        # CSV.parse / CSV.read — no-headers shape only.
+        # Upstream rbs declares broader return shapes but
+        # the common case is `Array[Array[String?]]` which
+        # the `csv::parsed[String]` URI matches. The
+        # `headers: true` shape (`CSV::Table` of `CSV::Row`)
+        # is NOT covered — calls passing the option fall
+        # through to the upstream RBS type. CSV.foreach also
+        # falls through (it yields rows rather than
+        # returning a typed structure).
+        ["CSV", :parse, :singleton] => CSV_PARSED_SPEC,
+        ["CSV", :read,  :singleton] => CSV_PARSED_SPEC
+      }.freeze
+
+      # @return [Rigor::Type, nil] the reduced HKT type for
+      #   the given (class_name, method_name, kind) triple,
+      #   or `nil` when no built-in override is registered.
+      #   When `arg_types` is supplied AND the entry carries a
+      #   `:discriminator` symbol, the discriminator may swap
+      #   the spec's default args for an alternate (e.g.
+      #   `JSON.parse(str, symbolize_names: true)` discriminates
+      #   `K = Symbol` instead of the default `K = String`).
+      def method_return_override(class_name:, method_name:, kind:, arg_types: nil, hkt_registry: nil)
+        spec = METHOD_RETURN_OVERRIDES[[class_name, method_name.to_sym, kind]]
+        return nil unless spec
+
+        args = discriminated_args(spec, arg_types)
+        registration = hkt_registry&.registration(spec[:uri])
+        bound = registration&.bound || Rigor::Type::Combinator.untyped
+        app = Rigor::Type::App.new(spec[:uri], args, bound: bound)
+
+        reduced =
+          if hkt_registry.nil? || !hkt_registry.defined?(spec[:uri])
+            app
+          else
+            hkt_registry.reduce(app) || app
+          end
+
+        apply_post_reduce(spec[:post_reduce], reduced, arg_types)
+      end
+
+      # Per-spec discriminator dispatch. Slice 3 ships one
+      # built-in discriminator (`json_symbolize_names`) that
+      # observes the optional 2nd argument's `HashShape` for a
+      # literal `symbolize_names: true` entry. Plugin / Rigor-
+      # bundled callers wanting their own discriminators add a
+      # branch here.
+      def discriminated_args(spec, arg_types)
+        default_args = spec[:args].map { |n| Rigor::Type::Nominal.new(n) }
+        return default_args if arg_types.nil?
+        return default_args unless spec[:discriminator] == :json_symbolize_names
+        return default_args unless json_symbolize_names?(arg_types)
+
+        [Rigor::Type::Nominal.new("Symbol")]
+      end
+
+      # Returns true iff the call-site's 2nd argument is a
+      # `Type::HashShape` carrying a literal
+      # `symbolize_names: true` entry. Anything else
+      # (no second arg, non-HashShape, missing key, non-literal
+      # `true`) returns false so the default `K = String`
+      # branch wins.
+      def json_symbolize_names?(arg_types)
+        return false unless arg_types.is_a?(Array) && arg_types.size >= 2
+
+        opts = arg_types[1]
+        return false unless opts.is_a?(Rigor::Type::HashShape)
+
+        value = opts.pairs[:symbolize_names] || opts.pairs["symbolize_names"]
+        value.is_a?(Rigor::Type::Constant) && value.value == true
+      end
+
+      # Slice 2c-bis — post-reduce hook. Receives the already-
+      # reduced `Type` and the call-site's `arg_types`; returns
+      # a (possibly augmented) `Type`. `kind = nil` is the
+      # identity (passes the reduced type through unchanged).
+      # Only `:yaml_permitted_classes` is implemented today;
+      # plugin / Rigor-bundled callers wanting their own
+      # post-reduce hooks add a branch here.
+      def apply_post_reduce(kind, reduced, arg_types)
+        case kind
+        when :yaml_permitted_classes
+          augment_with_yaml_permitted_classes(reduced, arg_types)
+        else
+          # `nil` (no post-reduce declared) and any future
+          # unrecognised kind both pass the reduced type
+          # through unchanged. Unknown kinds are silently
+          # tolerated rather than raised because adding a
+          # new kind on a Rigor upgrade should not crash a
+          # stale METHOD_RETURN_OVERRIDES entry on the
+          # caller side.
+          reduced
+        end
+      end
+
+      # Inspects arg_types for a `permitted_classes: [<Class>,
+      # ...]` literal Array in the options Hash and unions
+      # each named class into the reduced result. Non-literal
+      # `permitted_classes:` values (a variable, a constant
+      # reference, a concat) silently no-op and the caller
+      # observes the base json::value envelope only. Defensive
+      # against the various ways Ruby literal arrays surface
+      # as Rigor types: `Tuple[Singleton<Date>]` for a single
+      # element, `Tuple[Singleton<Date>, Singleton<Symbol>]`
+      # for multiple, `Nominal[Array, [Singleton<...>]]` if
+      # the analyzer widened (rare for literal arrays).
+      def augment_with_yaml_permitted_classes(reduced, arg_types)
+        return reduced unless arg_types.is_a?(Array) && arg_types.size >= 2
+
+        opts = arg_types[1]
+        return reduced unless opts.is_a?(Rigor::Type::HashShape)
+
+        value = opts.pairs[:permitted_classes] || opts.pairs["permitted_classes"]
+        return reduced if value.nil?
+
+        extras = permitted_class_nominals(value)
+        return reduced if extras.empty?
+
+        Rigor::Type::Combinator.union(reduced, *extras)
+      end
+
+      # Extract Singleton-class elements from a Tuple or
+      # Array-shape carrier, mapping each to its Nominal
+      # counterpart. Returns an empty array when no static
+      # Singletons are reachable (e.g. value is `Dynamic[T]`,
+      # element types are non-Singleton, etc.).
+      def permitted_class_nominals(value)
+        candidates =
+          if value.is_a?(Rigor::Type::Tuple)
+            value.elements
+          elsif value.is_a?(Rigor::Type::Nominal) && value.class_name == "Array" && value.type_args.size == 1
+            element = value.type_args.first
+            element.is_a?(Rigor::Type::Union) ? element.members : [element]
+          else
+            []
+          end
+
+        candidates.filter_map do |c|
+          c.is_a?(Rigor::Type::Singleton) ? Rigor::Type::Nominal.new(c.class_name) : nil
+        end
+      end
+    end
+  end
+end

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/store.rb

@@ -31,8 +31,22 @@ 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
@@ -59,6 +73,13 @@ module Rigor
 
       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
@@ -167,10 +188,10 @@ module Rigor
         end
 
         value = block.call
-        write_entry(path, descriptor, value, serialize: serialize)
+        write_entry(path, descriptor, value, serialize: serialize) unless @read_only
         @monitor.synchronize do
           record(:misses, producer_id)
-          record(:writes, producer_id)
+          record(:writes, producer_id) unless @read_only
           @memo[memo_key] = value
         end
         value
@@ -302,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