rigortype 0.4.1 → 0.4.3

data/lib/rigor/lens/members.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require_relative "slot"
+require_relative "parameters"
+
+module Rigor
+  module Lens
+    # Groups the sites of the requested files into members and fills their signatures (docs/internal-spec/lens.md
+    # § Members). A member is one `(owner, scope, Ruby method name)`; an `attr_accessor :a` site defines `a` and
+    # `a=`. An inferred slot comes from a site's body only when the member has exactly one project definition.
+    class Members
+      # @param sites — every {FileReader::Site} of the requested files
+      # @param omissions — every omission of the requested files
+      # @param contracts — `{[owner, scope, name] => ContractReader::Contract or nil}`
+      # @param elsewhere — callable `(owner, scope, name) -> [{path, line}]`: other project files defining it
+      # @param site_paths — `{site key => absolute path of its file}`, to match an inline contract's buffer
+      def initialize(sites:, omissions:, contracts:, elsewhere:, site_paths:)
+        @sites = sites
+        @omissions = omissions
+        @contracts = contracts
+        @elsewhere = elsewhere
+        @site_paths = site_paths
+      end
+
+      def build
+        groups = Hash.new { |hash, key| hash[key] = [] }
+        @sites.each do |site|
+          site.data["members"].each { |name| groups[[site.data["owner"], site.data["scope"], name]] << site }
+        end
+        result = groups.sort_by { |key, _| key }.map { |key, sites| member(key, sites) }
+        mark_inline_sites
+        result
+      end
+
+      private
+
+      def member(key, sites)
+        owner, scope, name = key
+        contract = @contracts[key]
+        also = @elsewhere.call(owner, scope, name)
+        omitted = @omissions.count { |omission| [omission["owner"], omission["scope"], omission["name"]] == key }
+        single = sites.size == 1 && omitted.zero? && also.empty? ? sites.first : nil
+        { "owner" => owner, "scope" => scope, "name" => name, "kind" => member_kind(sites),
+          "visibility" => common_visibility(sites), "sites" => sites.map { |site| site.data["key"] },
+          "also_defined_at" => also, "basis" => basis(contract, single),
+          "overloads" => overloads(contract, sites.first, name, single) }
+      end
+
+      # A member a `def` defines anywhere in the requested files is a method, whatever `attr_*` also names it.
+      def member_kind(sites)
+        sites.any? { |site| site.data["kind"] == "method" } ? "method" : "attribute"
+      end
+
+      def basis(contract, single)
+        return "contract" if contract
+        return "single_site" if single
+
+        "contested"
+      end
+
+      def common_visibility(sites)
+        values = sites.map { |site| site.data["visibility"] }.uniq
+        values.size == 1 ? values.first : nil
+      end
+
+      # A contested member without a contract has no overloads: its definitions may differ in arity, and each
+      # method site carries its own parameter list.
+      def overloads(contract, site, name, single)
+        return [] if contract.nil? && single.nil?
+
+        overloads = contract ? contract_overloads(contract, single) : [body_overload(site, name, single)]
+        overloads.map { |overload| overload.merge("rbs" => rbs_unless_unavailable(overload)) }
+      end
+
+      # A contract's overloads. A defaulted return (`inferred-return`) is inferred as for a member without a
+      # contract, and its `untyped` parameters are unknown: Rigor cannot tell an authored `untyped` from a
+      # defaulted one.
+      def contract_overloads(contract, single)
+        contract.overloads.map do |overload|
+          next overload.except("return_rbs") unless contract.return_inferred
+
+          slot = inferred_return(single)
+          params = overload["params"]&.map do |param|
+            param["type"]["type"] == "untyped" ? param.merge("type" => Slot.unavailable("not_computed")) : param
+          end
+          rbs = overload["rbs"]
+          suffix = overload["return_rbs"]
+          rbs = rbs.delete_suffix(suffix) + return_spelling(slot) if rbs && suffix && rbs.end_with?(suffix)
+          overload.except("return_rbs").merge("rbs" => rbs, "params" => params, "return" => slot)
+        end
+      end
+
+      # A member with no contract: its parameters as written, each `untyped` with ADR-75's undeclared-parameter
+      # cause, and the return from its one body.
+      def body_overload(site, name, single)
+        return attribute_overload(name, single) if site.data["kind"] == "attribute"
+
+        params, block, head = Parameters.read(site.node.parameters, yields: Parameters.yields?(site.node.body))
+        slot = inferred_return(single)
+        block_rbs = block ? " ?{ (?) -> untyped }" : ""
+        { "rbs" => "#{head}#{block_rbs} -> #{return_spelling(slot)}", "params" => params, "block" => block,
+          "return" => slot }
+      end
+
+      # An attribute without a contract: Rigor does not report the ivar's type in revision 1.
+      def attribute_overload(name, _single)
+        unknown = Slot.unavailable("not_computed")
+        if name.end_with?("=")
+          param = { "name" => nil, "kind" => "required", "type" => Slot.unavailable("not_computed") }
+          { "rbs" => nil, "params" => [param], "block" => nil, "return" => unknown }
+        else
+          { "rbs" => nil, "params" => [], "block" => nil, "return" => unknown }
+        end
+      end
+
+      def inferred_return(single)
+        return Slot.unavailable("contested") unless single
+
+        body = single.data["body_return"]
+        return Slot.unavailable("not_computed") if body.nil?
+        return body if Slot.unavailable?(body)
+
+        body.merge("from_site" => single.data["key"])
+      end
+
+      def return_spelling(slot)
+        spelled = Slot.rbs_spelling(slot)
+        spelled.include?(" | ") ? "(#{spelled})" : spelled
+      end
+
+      # `rbs` is null when any slot of the overload is unavailable: an `untyped` there would read as an assertion.
+      def rbs_unless_unavailable(overload)
+        slots = [overload["return"], overload.dig("block", "type")] +
+                (overload["params"] || []).map { |param| param["type"] }
+        slots.any? { |slot| Slot.unavailable?(slot) } ? nil : overload["rbs"]
+      end
+
+      # A site reads `contract: inline` when its own contract comments produced an inline declaration of a member
+      # it defines.
+      def mark_inline_sites
+        @sites.each do |site|
+          path = @site_paths.fetch(site.data["key"])
+          asserted = site.contract_comments.any? { |comment| !comment.location.slice.match?(/\A#\s*@extrbs\b/) }
+          inline = asserted && site.data["members"].any? do |name|
+            contract = @contracts[[site.data["owner"], site.data["scope"], name]]
+            contract&.provenance == "inline" && contract.buffers.any? { |buffer| buffer.end_with?(":#{path}") }
+          end
+          site.data["contract"] = inline ? "inline" : nil
+        end
+      end
+    end
+  end
+end

data/lib/rigor/lens/parameters.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "slot"
+
+module Rigor
+  module Lens
+    # A `def`'s parameter list as slots and as the RBS head sig-gen would write for an undeclared method.
+    module Parameters
+      module_function
+
+      UNDECLARED = "inferred_return_untyped"
+
+      # [params (nil for an argument-forwarding list), block or nil, "(…)" head]. A definition takes a block when
+      # it declares `&blk` or `yields` (its body yields).
+      def read(node, yields: false)
+        block = yields ? undeclared_block : nil
+        return [[], block, "()"] if node.nil?
+        return [nil, block, "(?)"] if node.keyword_rest.is_a?(Prism::ForwardingParameterNode)
+
+        entries = entries(node)
+        params = entries.map { |kind, name| { "name" => name&.to_s, "kind" => kind, "type" => undeclared } }
+        block = undeclared_block if node.block
+        [params, block, "(#{entries.map { |kind, name| spell(kind, name) }.join(', ')})"]
+      end
+
+      # `[kind, name]` per parameter, in declaration order.
+      def entries(node)
+        node.requireds.map { |param| ["required", name_of(param)] } +
+          node.optionals.map { |param| ["optional", param.name] } +
+          rest(node.rest) +
+          node.posts.map { |param| ["post", name_of(param)] } +
+          node.keywords.map { |param| [keyword_kind(param), param.name] } +
+          keyword_rest(node.keyword_rest)
+      end
+
+      def undeclared
+        Slot.dynamic("inferred", UNDECLARED)
+      end
+
+      def undeclared_block
+        { "required" => false, "type" => undeclared }
+      end
+
+      # Whether a `def` body yields, outside the bodies whose `yield` belongs elsewhere: a nested `def`, a lambda,
+      # a `define_method` block.
+      def yields?(node)
+        return false if node.nil?
+        return true if node.is_a?(Prism::YieldNode)
+        return false if node.is_a?(Prism::DefNode) || node.is_a?(Prism::LambdaNode)
+        return false if node.is_a?(Prism::CallNode) && node.name == :define_method && node.receiver.nil?
+
+        node.compact_child_nodes.any? { |child| yields?(child) }
+      end
+
+      # The shape of a parameter list: names and kinds, with every type null (lens.md § Sites).
+      def shape(params, block)
+        [params&.map { |param| param.merge("type" => nil) }, block&.merge("type" => nil)]
+      end
+
+      def name_of(param)
+        param.respond_to?(:name) ? param.name : nil
+      end
+
+      def keyword_kind(param)
+        param.is_a?(Prism::RequiredKeywordParameterNode) ? "keyreq" : "key"
+      end
+
+      def rest(node)
+        node.is_a?(Prism::RestParameterNode) ? [["rest", node.name]] : []
+      end
+
+      def keyword_rest(node)
+        node.is_a?(Prism::KeywordRestParameterNode) ? [["keyrest", node.name]] : []
+      end
+
+      def spell(kind, name)
+        label = name ? " #{name}" : ""
+        case kind
+        when "required", "post" then "untyped#{label}"
+        when "optional" then "?untyped#{label}"
+        when "rest" then "*untyped#{label}"
+        when "keyreq" then "#{name}: untyped"
+        when "key" then "?#{name}: untyped"
+        when "keyrest" then "**untyped#{label}"
+        end
+      end
+    end
+  end
+end

data/lib/rigor/lens/plugins.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "../version"
+
+module Rigor
+  module Lens
+    # `context.plugins` (docs/internal-spec/lens.md § Context): the plugins a run loaded, by manifest id.
+    module Plugins
+      BUNDLED_PLUGINS = File.expand_path("../../../plugins", __dir__).freeze
+
+      module_function
+
+      # `[{id, version}]` by manifest id (the id slot provenance uses). The version is Rigor's for a plugin bundled
+      # with it, else the version of the gem whose files define the plugin class, else null. A plugin id is not a gem
+      # name: the bundled `rbs-inline` plugin shares its id with the upstream gem.
+      def loaded(environment)
+        plugins = environment&.plugin_registry&.plugins || []
+        rows = plugins.map { |plugin| { "id" => plugin.manifest.id.to_s, "version" => version(plugin) } }
+        rows.uniq.sort_by { |plugin| plugin["id"] }
+      rescue StandardError
+        []
+      end
+
+      def version(plugin)
+        file = Object.const_source_location(plugin.class.name)&.first
+        return nil if file.nil?
+
+        absolute = File.expand_path(file)
+        return Rigor::VERSION if absolute.start_with?("#{BUNDLED_PLUGINS}/")
+
+        spec = Gem.loaded_specs.each_value.find do |gem|
+          absolute.start_with?("#{gem.full_gem_path}/") # rigor:disable undefined-method
+        end
+        spec&.version&.to_s
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/rigor/lens/run.rb

@@ -0,0 +1,280 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "file_reader"
+require_relative "contract_reader"
+require_relative "members"
+require_relative "plugins"
+require_relative "slot"
+require_relative "../analysis/incremental_session"
+require_relative "../cache/incremental_snapshot"
+require_relative "../cache/store"
+require_relative "../sig_gen/alias_index"
+require_relative "../sig_gen/type_elaborator"
+
+module Rigor
+  module Lens
+    # The check-equivalent computation behind `rigor lens` (docs/internal-spec/lens.md § Computation). The session
+    # is the `--incremental` one rooted at the configuration's `paths:`, so it shares the snapshot with
+    # `rigor check --incremental`; the targets are forced into the run and read inside it, on the seeded index.
+    class Run
+      # One target's answer: `status` is `ok` or a failure reason; the rest is set only for `ok`.
+      Target = Data.define(:argument, :path, :absolute, :status, :reason, :reader, :diagnostics, :inputs)
+      Outcome = Data.define(:targets, :member_rows, :plugins, :warm)
+
+      # @param root — the project root (absolute); every path in the answer is relative to it
+      def initialize(configuration:, root:, arguments:, workers:)
+        @configuration = configuration
+        @root = root
+        @arguments = arguments
+        @argument_paths = arguments.to_set { |argument| File.expand_path(argument) }
+        @workers = workers
+        reset_captures
+        @capture_errors = {}
+        @plugins = []
+      end
+
+      def call
+        session = build_session
+        project = session.project_files.to_h { |path| [File.expand_path(path), path] }
+        resolved = mark_duplicates(@arguments.map { |argument| resolve(argument, project) })
+        forced = resolved.filter_map { |entry| entry[:session_path] }
+        session.force_targets = forced.uniq
+        diagnostics, warm = analyse(session, forced.uniq)
+        targets = resolved.map { |entry| target(entry, diagnostics, session) }
+        Outcome.new(targets: targets, member_rows: members(targets, session), plugins: @plugins, warm: warm)
+      end
+
+      private
+
+      def build_session
+        cache_root = @configuration.cache_path
+        Analysis::IncrementalSession.new(
+          configuration: @configuration,
+          cache_store: Cache::Store.new(root: cache_root, max_bytes: @configuration.cache_max_bytes),
+          workers: @workers, on_file_indexed: method(:capture)
+        )
+      end
+
+      # A warm run is a recheck that forced the targets. A cold one is a baseline: a sequential baseline indexes
+      # every target in this process, a pooled one in workers where the callback never runs. The session also
+      # falls back to a baseline after a recheck whose seeds it no longer trusts, and the captures that recheck
+      # made are stale. So after a pooled baseline the captures are dropped and one forced recheck, on the
+      # baseline's fresh state, reads the targets again.
+      def analyse(session, forced)
+        fingerprint = Cache::IncrementalSnapshot.fingerprint(configuration: @configuration,
+                                                             roots: @configuration.paths)
+        snapshot = Cache::IncrementalSnapshot.new(root: @configuration.cache_path)
+        diagnostics, warm = session.run_incremental(snapshot: snapshot, fingerprint: fingerprint)
+        missing = forced.reject { |path| @captured.key?(File.expand_path(path)) }
+        if (!warm && @workers.positive?) || !missing.empty?
+          reset_captures
+          diagnostics = session.recheck.diagnostics
+        end
+        [diagnostics, warm]
+      end
+
+      def reset_captures
+        @captured = {}
+        @contracts = {}
+        @site_paths = {}
+      end
+
+      # A file requested again, in any spelling, is answered once: the later entries read `duplicate`, naming the
+      # argument that carries the answer, so every site key stays unique in the document.
+      def mark_duplicates(entries)
+        first = {}
+        entries.map do |entry|
+          next entry unless entry[:status] == "ok"
+
+          seen = first[entry[:absolute]]
+          first[entry[:absolute]] ||= entry[:argument]
+          next entry unless seen
+
+          entry.merge(status: "duplicate", reason: "the same file as #{seen}", session_path: nil)
+        end
+      end
+
+      def resolve(argument, project)
+        absolute = File.expand_path(argument)
+        entry = { argument: argument, absolute: absolute, path: relative(absolute) }
+        return entry.merge(status: "not_found", reason: "no such file") unless File.file?(absolute)
+        return entry.merge(status: "not_ruby", reason: "not a Ruby source file") unless absolute.end_with?(".rb")
+
+        session_path = project[absolute]
+        return entry.merge(status: "outside_project", reason: "not under the configured paths:") unless session_path
+
+        entry.merge(status: "ok", session_path: session_path)
+      end
+
+      # The runner's index callback. An error here never reaches the run: it is recorded, and the target reads
+      # `failed` with the reason.
+      def capture(path, parse_result, scope, index)
+        absolute = File.expand_path(path)
+        return unless @argument_paths.include?(absolute)
+
+        @plugins = Plugins.loaded(scope.environment) if @plugins.empty?
+        read_target(absolute, parse_result, scope, index)
+        @capture_errors.delete(absolute)
+      rescue StandardError => e
+        @captured.delete(absolute)
+        @capture_errors[absolute] = "#{e.class}: #{e.message}"
+      end
+
+      def read_target(absolute, parse_result, scope, index)
+        reader = FileReader.new(path: relative(absolute), parse_result: parse_result, index: index,
+                                spell: speller(scope.environment)).read
+        reader.sites.each do |site|
+          @site_paths[site.data["key"]] = absolute
+          site.data["members"].each { |name| read_contract(site.data["owner"], site.data["scope"], name, scope) }
+        end
+        @captured[absolute] = reader
+      end
+
+      def read_contract(owner, member_scope, name, scope)
+        key = [owner, member_scope, name]
+        return if @contracts.key?(key)
+
+        @contracts[key] = contract_reader(scope.environment).read(owner, member_scope.to_sym, name, scope)
+      end
+
+      def target(entry, diagnostics, session)
+        base = { argument: entry[:argument], path: entry[:path], absolute: entry[:absolute], status: entry[:status],
+                 reason: entry[:reason], reader: nil, diagnostics: nil, inputs: nil }
+        return Target.new(**base) unless entry[:status] == "ok"
+
+        reader = @captured[entry[:absolute]]
+        own = diagnostics.select { |diagnostic| File.expand_path(diagnostic.path.to_s) == entry[:absolute] }
+        if reader
+          return Target.new(**base, reader: reader, diagnostics: own,
+                                    inputs: inputs(session, entry[:session_path]))
+        end
+
+        Target.new(**base, **uncaptured(entry[:absolute], own))
+      end
+
+      # A forced target the run did not read: one that does not parse stops before indexing; otherwise reading it
+      # failed, or the run never indexed it.
+      def uncaptured(absolute, own)
+        if parse_errors?(absolute)
+          { status: "parse_error", reason: "the file does not parse", diagnostics: own }
+        else
+          { status: "failed", reason: @capture_errors.fetch(absolute, "the file was not analysed") }
+        end
+      rescue StandardError => e
+        # The parse itself failed (an unsupported `target_ruby`, say): the run's own parse did too.
+        { status: "failed", reason: "#{e.class}: #{e.message}" }
+      end
+
+      def parse_errors?(absolute)
+        Prism.parse_file(absolute, version: @configuration.target_ruby).errors.any?
+      end
+
+      def inputs(session, session_path)
+        rows = session.dependency_sources(session_path).filter_map do |source|
+          absolute = File.expand_path(source)
+          next if absolute == File.expand_path(session_path) || !File.file?(absolute)
+
+          { "path" => relative(absolute), "digest" => Lens.digest(File.binread(absolute)) }
+        end
+        rows.sort_by { |input| input["path"] }
+      end
+
+      def members(targets, session)
+        # A file requested twice, in any spelling, contributes its declarations once.
+        readers = targets.filter_map { |target| target.reader && [target.absolute, target.reader] }.to_h
+        sites = readers.values.flat_map(&:sites)
+        omissions = readers.values.flat_map(&:omissions)
+        requested = readers.keys.to_set
+        Members.new(sites: sites, omissions: omissions, contracts: @contracts,
+                    elsewhere: elsewhere(session, requested), site_paths: @site_paths).build
+      end
+
+      # Other project files that define a member, from the per-file discovery bundles the session keeps. The bundle
+      # paths are resolved once; each member then costs one lookup per bundle.
+      def elsewhere(session, requested)
+        bundles = session.seed_bundles.filter_map do |path, bundle|
+          absolute = File.expand_path(path)
+          [relative(absolute), bundle] unless requested.include?(absolute)
+        end
+        lambda do |owner, scope, name|
+          entries = bundles.filter_map do |path, bundle|
+            line = defined_line(bundle, owner, scope, name)
+            line == false ? nil : { "path" => path, "line" => line }
+          end
+          entries.sort_by { |entry| entry["path"] }
+        end
+      end
+
+      # The line a bundle records for the member, nil when it defines the member without a recorded line (an
+      # `attr_*`), or false when it does not define it.
+      # A top-level `def` is recorded under discovery's own key, apart from `class Object`; both count for
+      # `Object#name`.
+      def defined_line(bundle, owner, scope, name)
+        owners = if owner == "Object" && scope == "instance"
+                   [owner,
+                    Inference::ScopeIndexer::TOP_LEVEL_DEF_KEY]
+                 else
+                   [owner]
+                 end
+        owners.each do |key|
+          line = defined_line_for(bundle, key, scope, name)
+          return line unless line == false
+        end
+        false
+      end
+
+      def defined_line_for(bundle, owner, scope, name)
+        table = scope == "singleton" ? bundle[:singleton_def_sources] : bundle[:def_sources]
+        source = table&.dig(owner, name.to_sym)
+        return Integer(source.to_s.split(":").last) if source
+
+        kinds = bundle[:methods]&.dig(owner, name.to_sym)
+        return false if kinds.nil?
+        return nil if kinds == :both || kinds.to_s == scope
+
+        false
+      end
+
+      def speller(environment)
+        @alias_index ||= SigGen::AliasIndex.build(environment: environment, signature_paths: signature_roots,
+                                                  excluded_paths: plugin_signature_paths(environment))
+        lambda do |type, owner|
+          @alias_index.fold(SigGen::TypeElaborator.elaborate(type, environment: environment).erase_to_rbs, owner)
+        end
+      end
+
+      def contract_reader(environment)
+        @contract_reader ||= ContractReader.new(
+          Provenance.new(root: @root, signature_roots: signature_roots.map { |path| File.expand_path(path.to_s) },
+                         plugin_roots: plugin_roots(environment))
+        )
+      end
+
+      # `{absolute signature directory => plugin id}` for every loaded plugin that ships signatures.
+      def plugin_roots(environment)
+        plugins = environment&.plugin_registry&.plugins || []
+        plugins.each_with_object({}) do |plugin, roots|
+          Array(plugin.signature_paths).each { |path| roots[File.expand_path(path.to_s)] = plugin.manifest.id }
+        end
+      rescue StandardError
+        {}
+      end
+
+      def signature_roots
+        @signature_roots ||= Environment.project_signature_roots(@configuration.signature_paths)
+      end
+
+      def plugin_signature_paths(environment)
+        environment&.plugin_registry&.signature_paths || []
+      rescue StandardError
+        []
+      end
+
+      def relative(absolute)
+        Pathname(absolute).relative_path_from(Pathname(@root)).to_s
+      end
+    end
+  end
+end

data/lib/rigor/lens/slot.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Rigor
+  module Lens
+    # Tagged type slots and RBS-buffer provenance (docs/internal-spec/lens.md § Slots).
+    module Slot
+      module_function
+
+      def typed(type, provenance, path: nil, from_site: nil)
+        { "state" => "typed", "type" => type, "provenance" => provenance, "path" => path, "from_site" => from_site }
+      end
+
+      def dynamic(provenance, cause, path: nil, from_site: nil)
+        { "state" => "dynamic", "type" => "untyped", "provenance" => provenance, "path" => path,
+          "from_site" => from_site, "cause" => cause&.to_s }
+      end
+
+      def unavailable(reason)
+        { "state" => "unavailable", "reason" => reason }
+      end
+
+      def unavailable?(slot)
+        slot.is_a?(Hash) && slot["state"] == "unavailable"
+      end
+
+      # A slot for an RBS type string read from a contract. `untyped` is a dynamic slot whose cause is the
+      # authored contract.
+      def from_rbs(type, provenance, path)
+        return dynamic(provenance, :explicit_untyped, path: path) if type == "untyped"
+
+        typed(type, provenance, path: path)
+      end
+
+      # The RBS type a slot puts in an overload's `rbs` string: an unavailable slot reads `untyped`.
+      def rbs_spelling(slot)
+        slot["state"] == "typed" ? slot["type"] : "untyped"
+      end
+    end
+
+    # Maps an RBS member's buffer name to a provenance (§ Slots).
+    class Provenance
+      CACHED_BUFFER = "<cached>"
+
+      # @param root — the project root (absolute)
+      # @param signature_roots — the project signature roots (absolute)
+      # @param plugin_roots — `{absolute signature directory => plugin id}` of the loaded plugins
+      def initialize(root:, signature_roots:, plugin_roots:)
+        @root = root
+        @signature_roots = signature_roots
+        @plugin_roots = plugin_roots
+      end
+
+      # [provenance, path] for a buffer name, or nil when the buffer cannot be classified.
+      def classify(buffer_name)
+        name = buffer_name.to_s
+        return ["inline", nil] if name.start_with?("virtual:rbs-inline:")
+        return ["plugin:#{name.split(':', 3)[1]}", nil] if name.start_with?("virtual:")
+        return nil if name.empty? || name == CACHED_BUFFER
+
+        absolute = File.expand_path(name, @root)
+        plugin = @plugin_roots.find { |root, _| under?(absolute, [root]) }
+        return ["plugin:#{plugin.last}", nil] if plugin
+        return ["sig", relative(absolute)] if under?(absolute, @signature_roots)
+
+        ["library", nil]
+      end
+
+      def relative(absolute)
+        Pathname(absolute).relative_path_from(Pathname(@root)).to_s
+      end
+
+      private
+
+      def under?(absolute, roots)
+        roots.any? { |root| absolute == root || absolute.start_with?("#{root}/") }
+      end
+    end
+  end
+end

data/lib/rigor/lens.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "hashing/xxh3"
+
+module Rigor
+  # `rigor lens`: a declaration map of the requested files with type provenance, computed as `rigor check` computes
+  # them (ADR-113; the output contract is docs/internal-spec/lens.md).
+  module Lens
+    SCHEMA = "lens/v0"
+    # Bumped on every breaking change to the `lens/v0` document (docs/internal-spec/lens.md § Status).
+    REVISION = 1
+    CAPABILITIES = %w[class module method attribute body_return diagnostics inputs].freeze
+
+    module_function
+
+    # A Prism location as the document's span object: 1-based lines, 0-based byte columns and offsets.
+    def span(location)
+      { "start_line" => location.start_line, "start_column" => location.start_column,
+        "end_line" => location.end_line, "end_column" => location.end_column,
+        "start_offset" => location.start_offset, "end_offset" => location.end_offset }
+    end
+
+    # The span from the first to the last of a site's contract comments, or nil when it has none.
+    def contract_span(comments)
+      return nil if comments.empty?
+
+      first = comments.first.location
+      last = comments.last.location
+      { "start_line" => first.start_line, "start_column" => first.start_column, "end_line" => last.end_line,
+        "end_column" => last.end_column, "start_offset" => first.start_offset, "end_offset" => last.end_offset }
+    end
+
+    def digest(bytes)
+      "xxh3-64:#{Hashing::XXH3.file_hash(bytes)}"
+    end
+  end
+end
+
+require_relative "lens/run"
+require_relative "lens/document"