rigortype 0.1.4 → 0.1.6

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

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Rigor
+  module Plugin
+    # Frozen, `Ractor.shareable?` description of how to materialise
+    # a single plugin instance inside a worker.
+    # [ADR-15](../../../docs/adr/15-ractor-concurrency.md) Phase 3
+    # introduces the carrier so the eventual worker pool can pass
+    # `Array<Blueprint>` across a Ractor boundary verbatim; each
+    # worker calls {#materialize} once at startup, then owns its
+    # plugin instances (and their mutable per-run accumulators)
+    # for the lifetime of the worker.
+    #
+    # Holds the constant path (`String`) of the plugin class — NOT
+    # the class object itself. Plugin gems are required from the
+    # main Ractor BEFORE any worker spawns, so every Ractor
+    # resolves the same constant via `Object.const_get`.
+    #
+    # The `config` Hash is deep-copied + made shareable at
+    # construction so the Blueprint stays decoupled from whatever
+    # Hash the project configuration emitted. The original config
+    # Hash held by the loader is therefore unaffected by Blueprint
+    # construction.
+    class Blueprint
+      attr_reader :klass_name, :config
+
+      def initialize(klass_name:, config: {})
+        @klass_name = normalise_klass_name(klass_name)
+        @config = Ractor.make_shareable(Marshal.load(Marshal.dump(config)))
+        freeze
+      end
+
+      # Resolves the plugin class via `Object.const_get`, builds a
+      # fresh instance bound to the supplied services container,
+      # and calls `#init(services)`. Mirrors
+      # {Rigor::Plugin::Loader#instantiate} bit-for-bit so the
+      # blueprint-driven path stays consistent with the
+      # configuration-driven load path.
+      def materialize(services:)
+        klass = Object.const_get(@klass_name)
+        plugin = klass.new(services: services, config: @config)
+        plugin.init(services)
+        plugin
+      end
+
+      private
+
+      def normalise_klass_name(name)
+        case name
+        when String
+          name.dup.freeze
+        when Module
+          name.name.dup.freeze
+        else
+          raise ArgumentError, "Blueprint klass_name must be a String or Module, got #{name.class}"
+        end
+      end
+    end
+  end
+end

data/lib/rigor/plugin/loader.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "blueprint"
 require_relative "registry"
 require_relative "load_error"
 
@@ -72,7 +73,8 @@ module Rigor
         plugins, sort_errors = topo_sort_plugins(plugins)
         load_errors.concat(sort_errors)
 
-        Registry.new(plugins: plugins, load_errors: load_errors)
+        blueprints = plugins.map { |plugin| Blueprint.new(klass_name: plugin.class.name, config: plugin.config) }
+        Registry.new(plugins: plugins, blueprints: blueprints, load_errors: load_errors)
       end
 
       private

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

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module Rigor
+  module Plugin
+    module Macro
+      # ADR-16 Tier A declaration: "the block passed to a
+      # class-level DSL call of one of `verbs` runs as an instance
+      # method on `receiver_constraint`'s subclass tree, with
+      # `self` typed accordingly."
+      #
+      # Authored on a plugin manifest:
+      #
+      #   manifest(
+      #     id: "sinatra",
+      #     version: "0.1.0",
+      #     block_as_methods: [
+      #       Rigor::Plugin::Macro::BlockAsMethod.new(
+      #         receiver_constraint: "Sinatra::Base",
+      #         verbs: %i[get post put delete head options patch link unlink]
+      #       )
+      #     ]
+      #   )
+      #
+      # Sinatra is the canonical worked target (`Sinatra::Base#generate_method`
+      # at `lib/sinatra/base.rb:1788-1793` literally does
+      # `define_method(name, &block); remove_method` — the block IS
+      # the method body, byte-for-byte). The substrate adopts the
+      # same contract: declare the receiver constraint + the
+      # class-level methods whose block argument runs as if it were
+      # an instance method of the receiver.
+      #
+      # Slice 1a (this file) is **the contract only**. The engine
+      # hook that consults registered entries and narrows
+      # `Scope#self_type` for a block whose enclosing call matches
+      # arrives in slice 1b.
+      #
+      # ## Fields
+      #
+      # - `receiver_constraint` — fully-qualified class name (String)
+      #   that the call's lexical receiver MUST be (or inherit from)
+      #   for the entry to fire. For Sinatra modular-style this is
+      #   `"Sinatra::Base"`; the substrate's class-context match
+      #   accepts every subclass.
+      # - `verbs` — Array of Symbol method names. A call shape
+      #   `<receiver_subclass>.get('/path') { ... }` matches when
+      #   `:get` is in this list.
+      # - `self_type` — Symbol selecting the kind of `self`-binding
+      #   the substrate applies inside the block. Slice 1a accepts
+      #   only `:receiver_instance` (the block runs as an instance
+      #   method of the receiver class). Other kinds (`:receiver_singleton`,
+      #   `:dsl_recorder`) are reserved for later slices.
+      #
+      # ## Ractor-shareability
+      #
+      # All fields are frozen at construction (ADR-15 Phase 1).
+      # `verbs` is dup-frozen so the caller's mutable array does
+      # not leak into the value. `Ractor.shareable?` returns true
+      # after `#initialize`.
+      class BlockAsMethod
+        SELF_TYPE_RECEIVER_INSTANCE = :receiver_instance
+        VALID_SELF_TYPES = [SELF_TYPE_RECEIVER_INSTANCE].freeze
+
+        attr_reader :receiver_constraint, :verbs, :self_type
+
+        def initialize(receiver_constraint:, verbs:, self_type: SELF_TYPE_RECEIVER_INSTANCE)
+          validate_receiver_constraint!(receiver_constraint)
+          validate_verbs!(verbs)
+          validate_self_type!(self_type)
+
+          @receiver_constraint = receiver_constraint.dup.freeze
+          @verbs = verbs.map(&:to_sym).freeze
+          @self_type = self_type
+          freeze
+        end
+
+        def to_h
+          {
+            "receiver_constraint" => receiver_constraint,
+            "verbs" => verbs.map(&:to_s),
+            "self_type" => self_type.to_s
+          }
+        end
+
+        def ==(other)
+          other.is_a?(BlockAsMethod) &&
+            receiver_constraint == other.receiver_constraint &&
+            verbs == other.verbs &&
+            self_type == other.self_type
+        end
+        alias eql? ==
+
+        def hash
+          [receiver_constraint, verbs, self_type].hash
+        end
+
+        private
+
+        def validate_receiver_constraint!(value)
+          return if value.is_a?(String) && !value.empty?
+
+          raise ArgumentError,
+                "Plugin::Macro::BlockAsMethod#receiver_constraint must be a non-empty String, " \
+                "got #{value.inspect}"
+        end
+
+        def validate_verbs!(verbs)
+          unless verbs.is_a?(Array) && !verbs.empty?
+            raise ArgumentError,
+                  "Plugin::Macro::BlockAsMethod#verbs must be a non-empty Array, got #{verbs.inspect}"
+          end
+
+          verbs.each do |v|
+            next if v.is_a?(Symbol) || (v.is_a?(String) && !v.empty?)
+
+            raise ArgumentError,
+                  "Plugin::Macro::BlockAsMethod#verbs entries must be Symbol/non-empty String, " \
+                  "got #{v.inspect}"
+          end
+        end
+
+        def validate_self_type!(self_type)
+          return if VALID_SELF_TYPES.include?(self_type)
+
+          raise ArgumentError,
+                "Plugin::Macro::BlockAsMethod#self_type must be one of #{VALID_SELF_TYPES.inspect}, " \
+                "got #{self_type.inspect}"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module Rigor
+  module Plugin
+    module Macro
+      # ADR-16 Tier D declaration: "files matching `glob` are
+      # analysed as if their body were pasted at a call site whose
+      # `self` is an instance of `receiver_type` (and whose `@ivar`
+      # facts come from `bound_ivars`)."
+      #
+      # Worked motivating cases (per the per-library survey):
+      #
+      # - Redmine's `WebhookPayload#instance_eval(File.read(path), path, 1)`
+      #   at `app/models/webhook_payload.rb:71`. The payload templates
+      #   under `config/webhooks/*.rb` run with `self` typed as
+      #   `Redmine::WebhookPayload` and ivars like `@event` / `@issue`
+      #   / `@user` pre-bound by the caller.
+      # - tDiary Core's plugin loader pattern — `misc/plugin/*.rb`
+      #   files loaded under `instance_eval` with the tDiary plugin
+      #   instance as `self`.
+      #
+      # ## Authoring shape
+      #
+      #     manifest(
+      #       id: "redmine-webhook-payloads",
+      #       version: "0.1.0",
+      #       external_files: [
+      #         Rigor::Plugin::Macro::ExternalFile.new(
+      #           glob: "config/webhooks/*.rb",
+      #           receiver_type: "Redmine::WebhookPayload",
+      #           bound_ivars: {
+      #             "@event" => "Symbol",
+      #             "@issue" => "Issue?",
+      #             "@user"  => "User"
+      #           }
+      #         )
+      #       ]
+      #     )
+      #
+      # ## Fields
+      #
+      # - `glob` — non-empty String pattern. Interpreted relative
+      #   to the project root (the directory containing `.rigor.yml`)
+      #   at scan time. Slice 5a accepts any non-empty glob
+      #   pattern syntactically; the engine integration (slice 5b)
+      #   pins the resolution rule.
+      # - `receiver_type` — non-empty String. The class name `self`
+      #   inside the loaded file binds to. Engine integration (slice
+      #   5b) narrows the file-entry scope's `self_type` to
+      #   `Nominal[receiver_type]`.
+      # - `bound_ivars` — Hash<String, String>. Each key MUST start
+      #   with `@`; each value is a non-empty type-name String. The
+      #   engine pre-binds these as ivar facts in the file-entry
+      #   scope (slice 5b).
+      #
+      # ## Slice 5a scope
+      #
+      # **This file ships the value class + manifest hook ONLY.**
+      # The engine integration that (a) adds matched files to the
+      # analysis set, (b) narrows the file-entry `self_type`, and
+      # (c) pre-binds `bound_ivars` as ivar facts is **queued for
+      # slice 5b**, gated on demonstrated demand. The survey
+      # identifies only Redmine + tDiary as concrete consumers;
+      # premature engine work is deferred until those cases (or
+      # equivalents) materialise as committed plugin targets.
+      #
+      # With only this slice landed, plugin authors CAN declare a
+      # Tier D manifest entry today — the declaration round-trips
+      # through `Manifest#to_h` (cache-key stable) and is exposed
+      # on `Manifest#external_files` — but the substrate does not
+      # yet act on it. The contract is forward-compatible: when
+      # slice 5b lands, the engine reads the same declarations and
+      # plugin gems do not need to change.
+      class ExternalFile
+        attr_reader :glob, :receiver_type, :bound_ivars
+
+        def initialize(glob:, receiver_type:, bound_ivars: {})
+          validate_glob!(glob)
+          validate_receiver_type!(receiver_type)
+          validate_bound_ivars!(bound_ivars)
+
+          @glob = glob.dup.freeze
+          @receiver_type = receiver_type.dup.freeze
+          @bound_ivars = bound_ivars.to_h { |k, v| [k.dup.freeze, v.dup.freeze] }.freeze
+          freeze
+        end
+
+        def to_h
+          {
+            "glob" => glob,
+            "receiver_type" => receiver_type,
+            "bound_ivars" => bound_ivars
+          }
+        end
+
+        def ==(other)
+          other.is_a?(ExternalFile) && to_h == other.to_h
+        end
+        alias eql? ==
+
+        def hash
+          to_h.hash
+        end
+
+        private
+
+        def validate_glob!(value)
+          return if value.is_a?(String) && !value.empty?
+
+          raise ArgumentError,
+                "Plugin::Macro::ExternalFile#glob must be a non-empty String, got #{value.inspect}"
+        end
+
+        def validate_receiver_type!(value)
+          return if value.is_a?(String) && !value.empty?
+
+          raise ArgumentError,
+                "Plugin::Macro::ExternalFile#receiver_type must be a non-empty String, got #{value.inspect}"
+        end
+
+        def validate_bound_ivars!(value)
+          unless value.is_a?(Hash)
+            raise ArgumentError,
+                  "Plugin::Macro::ExternalFile#bound_ivars must be a Hash, got #{value.inspect}"
+          end
+
+          value.each do |k, v|
+            unless k.is_a?(String) && k.start_with?("@") && k.length > 1
+              raise ArgumentError,
+                    "Plugin::Macro::ExternalFile#bound_ivars key must be a String starting with `@`, " \
+                    "got #{k.inspect}"
+            end
+            next if v.is_a?(String) && !v.empty?
+
+            raise ArgumentError,
+                  "Plugin::Macro::ExternalFile#bound_ivars value must be a non-empty String, " \
+                  "got #{v.inspect}"
+          end
+        end
+      end
+    end
+  end
+end