rigortype 0.3.2 → 0.3.4

data/lib/rigor/effects/catalog.rb

@@ -0,0 +1,275 @@
+# frozen_string_literal: true
+
+require "digest"
+require "yaml"
+
+require_relative "../inference/mutation_widening"
+require_relative "label_set"
+require_relative "mutation_classifier"
+require_relative "narrowing"
+
+module Rigor
+  module Effects
+    # The built-in effect catalogue — which core-library methods colour a summary, and with what
+    # (ADR-103 WD3 / WD14; the data is `data/effects/core.yml`, the contract is
+    # `docs/internal-spec/effect-summaries.md` § The catalogue).
+    #
+    # **The loader is deliberately dumb.** Every audit decision lives in the data file's `why:` lines;
+    # nothing here decides what a method does. What this class adds over `YAML.safe_load` is three
+    # things the data cannot express on its own:
+    #
+    # 1. **Per-class default postures.** A class the catalogue lists answers its posture's labels for a
+    #    method it does not row, so the reading of Ruby's enormous core surface does not depend on the
+    #    catalogue being complete. A class the catalogue does NOT list answers nil — contribute nothing,
+    #    do not taint — which stays the reading for project and gem classes.
+    # 2. **Argument-dependent narrowing.** A row's `narrow:` names a {Narrowing} handler, which reads
+    #    the call's own argument literals.
+    # 3. **Mutator sets by reference.** A value class names `mutators: array | hash | string` and the
+    #    loader resolves it to the set the widening rules and the mutation classifier already maintain,
+    #    so the two can never drift. The YAML never re-spells a mutator list.
+    #
+    # What this is **not** is a re-reading of `data/builtins/ruby_core/*.yml`'s `purity:` facet. That
+    # facet answers fold-safety in the C-dispatch sense — `Random#rand` is `leaf`, `Array#push` is
+    # `leaf` — and reading it as effect freedom would be wrong in both directions (ADR-103 WD3). This
+    # loader never opens `data/builtins`, and a spec asserts it.
+    class Catalog
+      class Error < StandardError
+      end
+
+      DATA_PATH = File.expand_path("../../../data/effects/core.yml", __dir__)
+
+      # The mutator sets a value class may name, by reference. Adding a name here is the only way a
+      # class gets one — the data file may not spell a selector list of its own.
+      MUTATOR_SETS = {
+        "array" => Inference::MutationWidening::ARRAY_MUTATORS,
+        "hash" => Inference::MutationWidening::HASH_MUTATORS,
+        "string" => MutationClassifier::STRING_MUTATORS
+      }.freeze
+
+      NO_MUTATORS = Set[].freeze
+      private_constant :NO_MUTATORS
+
+      # What the catalogue answers for one call.
+      #
+      # `labels` may be empty two ways, and the difference matters: a ∅ **row** says the catalogue knows
+      # this call and knows it contributes nothing (which is what stops `Thread.new` from reading as an
+      # unresolved call while its block joins the enclosing method by containment), while a ∅ **posture**
+      # says only that the class is a value class. Both stop the caller treating the call as unresolved;
+      # only the posture keeps a project edge, because a project may reopen a core class.
+      class Entry < Data.define(:labels, :mutates_receiver, :from_posture)
+        def posture?
+          from_posture
+        end
+
+        def mutates_receiver?
+          mutates_receiver
+        end
+      end
+
+      # One row of the data file, resolved. `entry` is the row's own unnarrowed {Entry}, built at load
+      # time: the lookup sits inside the effect scan's walk, and every un-narrowed row hit in a project
+      # answers the same value.
+      Row = Data.define(:labels, :narrow, :mutates_receiver, :entry)
+      private_constant :Row
+
+      # One class of the data file, resolved: its two method buckets, its posture's labels, its mutator
+      # set, and the two memoised posture {Entry}s (allocated once rather than per call — the lookup
+      # sits inside the effect scan's walk).
+      class ClassEntry
+        attr_reader :instance_methods, :singleton_methods, :posture_labels, :singleton_posture_labels,
+                    :mutators, :object
+
+        def initialize(instance_methods:, singleton_methods:, posture_labels:, singleton_posture_labels:,
+                       mutators:, object:)
+          @instance_methods = instance_methods
+          @singleton_methods = singleton_methods
+          @posture_labels = posture_labels
+          @singleton_posture_labels = singleton_posture_labels
+          @mutators = mutators
+          @object = object
+          @entries = {
+            [false, false] => Entry.new(labels: posture_labels, mutates_receiver: false, from_posture: true),
+            [false, true] => Entry.new(labels: posture_labels, mutates_receiver: true, from_posture: true),
+            [true, false] => Entry.new(labels: singleton_posture_labels, mutates_receiver: false,
+                                       from_posture: true)
+          }.freeze
+          freeze
+        end
+
+        def object?
+          @object
+        end
+
+        # Memoised rather than built per call — the lookup sits inside the effect scan's walk. Only the
+        # instance side can be a receiver mutation, so the singleton side needs one entry.
+        def posture_entry(singleton, mutating)
+          @entries[[singleton, !singleton && mutating]]
+        end
+      end
+
+      # The shipped catalogue. Memoised: the YAML parse is a once-per-process cost, paid on the first
+      # collecting run rather than at `require "rigor"`, and inherited as-is across the fork pool
+      # (workers fork after load, and nothing here ever crosses a Marshal boundary — a `FileCollection`
+      # carries `LabelSet`s and Strings, never a catalogue reference).
+      def self.default
+        @default ||= load_file(DATA_PATH)
+      end
+
+      # Build a catalogue from a catalogue-shaped YAML file. A missing or unreadable file degrades to an
+      # empty catalogue rather than raising, matching {Registry.load_file} and the built-in catalogues'
+      # posture for a bare install that opted data out: every call then reads as uncatalogued, which is
+      # fail-open. A file that IS present but malformed raises — that is a packaging bug, not a choice.
+      def self.load_file(path)
+        raw = File.exist?(path) ? YAML.safe_load_file(path) : nil
+        raw = {} unless raw.is_a?(Hash)
+        new(
+          defaults: raw["defaults"] || {}, classes: raw["classes"] || {},
+          universal: raw["universal"] || [], schema: raw.fetch("schema", 0),
+          digest: file_digest(path)
+        )
+      end
+
+      # A content digest of the catalogue file, so {#identity} moves when a row's audit decision moves.
+      # `schema:` alone cannot carry that: it is bumped for a shape change, and the whole point of the
+      # data file is that rows are edited without one. An absent file digests as `"absent"`, matching
+      # {load_file}'s fail-open posture for a bare install that opted data out.
+      def self.file_digest(path)
+        File.file?(path) ? Digest::SHA256.file(path).hexdigest : "absent"
+      rescue StandardError
+        "unreadable"
+      end
+      private_class_method :file_digest
+
+      attr_reader :schema, :digest
+
+      def initialize(defaults:, classes:, universal: [], schema: 0, digest: "unknown")
+        @schema = schema
+        @digest = digest.to_s.freeze
+        @postures = build_postures(defaults)
+        @universal = universal.to_set(&:to_s).freeze
+        @classes = build_classes(classes)
+        @object_constants = @classes.select { |_, entry| entry.object? }.keys.to_set.freeze
+        freeze
+      end
+
+      # What the effects cache identity records this catalogue as (#382, {Effects::Identity}): the schema
+      # AND the content digest, so a re-audited row invalidates persisted summaries the same way a shape
+      # change does.
+      def identity
+        "#{@schema}:#{@digest}"
+      end
+
+      # Every catalogued class name, sorted — the surface a spec walks.
+      def class_names
+        @classes.keys.sort
+      end
+
+      def class_entry(owner)
+        @classes[owner]
+      end
+
+      # Whether `name` is a constant that names an OBJECT rather than a class, so a call on it spells
+      # `ENV#[]` and not `ENV.[]`.
+      def object_constant?(name)
+        @object_constants.include?(name)
+      end
+
+      # What `owner#name` (or `owner.name`, with `singleton:`) contributes, or nil when the catalogue
+      # has nothing to say — which is not a taint, and leaves the caller to treat the call as ordinary.
+      #
+      # `call_node` is the Prism call, consulted only by a row that carries a `narrow:` handler.
+      # `posture:` false asks for a ROW ONLY, which is how the collector suppresses the class default
+      # where it would be wrong: an implicit-self call spells `Kernel#name`, and defaulting every
+      # unqualified call in a project body to `io` would colour the world.
+      def lookup(owner, name, singleton: false, call_node: nil, posture: true)
+        entry = @classes[owner]
+        return nil if entry.nil?
+
+        bucket = singleton ? entry.singleton_methods : entry.instance_methods
+        row = bucket[name]
+        return row_entry(row, call_node) if row
+        return UNIVERSAL if @universal.include?(name)
+        return nil unless posture
+
+        entry.posture_entry(singleton, entry.mutators.include?(name))
+      end
+
+      # An `Object`-level selector that exists on every receiver and touches nothing. Answered as a row
+      # rather than a posture, because it IS a statement about the selector.
+      UNIVERSAL = Entry.new(labels: LabelSet::EMPTY, mutates_receiver: false, from_posture: false)
+
+      private
+
+      # A narrowed row's own `effects:` is its **unnarrowed** answer — the upper bound the handler
+      # degrades to — so a caller that has no call node still gets a sound reading rather than ∅.
+      def row_entry(row, call_node)
+        return row.entry unless row.narrow && call_node
+
+        Entry.new(labels: Narrowing.apply(row.narrow, call_node), mutates_receiver: row.mutates_receiver,
+                  from_posture: false)
+      end
+
+      def build_postures(defaults)
+        defaults.to_h { |name, labels| [name.to_s, LabelSet.new(Array(labels).map(&:to_s))] }.freeze
+      end
+
+      def build_classes(classes)
+        classes.to_h { |name, body| [name.to_s, build_class(name.to_s, body || {})] }.freeze
+      end
+
+      def build_class(name, body)
+        mutators = resolve_mutators(name, body["mutators"])
+        ClassEntry.new(
+          instance_methods: build_rows(name, body["methods"], mutators),
+          singleton_methods: build_rows(name, body["singleton_methods"], nil),
+          posture_labels: resolve_posture(name, body["posture"]),
+          singleton_posture_labels: resolve_posture(name, body["singleton_posture"] || body["posture"]),
+          mutators: mutators,
+          object: body["kind"] == "object"
+        )
+      end
+
+      def resolve_posture(class_name, posture)
+        return LabelSet::EMPTY if posture.nil?
+
+        @postures[posture.to_s] ||
+          raise(Error, "#{class_name}: unknown posture #{posture.inspect}; add it to the catalogue's defaults:")
+      end
+
+      def resolve_mutators(class_name, named)
+        return NO_MUTATORS if named.nil?
+
+        set = MUTATOR_SETS[named.to_s] ||
+              raise(Error, "#{class_name}: unknown mutator set #{named.inspect}")
+        set.to_set(&:to_s).freeze
+      end
+
+      def build_rows(class_name, rows, mutators)
+        return EMPTY_ROWS if rows.nil?
+
+        rows.to_h do |name, body|
+          key = name.to_s
+          [key, build_row("#{class_name}##{key}", body || {}, mutators&.include?(key) == true)]
+        end.freeze
+      end
+
+      def build_row(key, body, in_mutator_set)
+        narrow = body["narrow"]&.to_s
+        raise Error, "#{key}: unknown narrowing handler #{narrow.inspect}" if narrow && !Narrowing.known?(narrow)
+        raise Error, "#{key}: every catalogue row needs a `why:` justification" if body["why"].to_s.empty?
+
+        labels = LabelSet.new(Array(body["effects"]).map(&:to_s))
+        mutates_receiver = body["mutates"].to_s == "receiver" || in_mutator_set
+        Row.new(
+          labels: labels,
+          narrow: narrow,
+          mutates_receiver: mutates_receiver,
+          entry: Entry.new(labels: labels, mutates_receiver: mutates_receiver, from_posture: false)
+        )
+      end
+
+      EMPTY_ROWS = {}.freeze
+      private_constant :EMPTY_ROWS
+    end
+  end
+end

data/lib/rigor/effects/collector.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+require_relative "../type"
+require_relative "../inference/origin_lookup"
+require_relative "attribution"
+require_relative "envelope_index"
+require_relative "file_collection"
+require_relative "plugin_facts"
+require_relative "scanner"
+
+module Rigor
+  module Effects
+    # Records what the typer already decided about each call site, and turns one file's decisions into a
+    # {FileCollection} (ADR-103 WD13; the contract is `docs/internal-spec/effect-summaries.md`).
+    #
+    # Modelled on {Rigor::Analysis::DependencyRecorder}, for the same reason: the recording site sits on
+    # the per-dispatch hot path, so **the disabled fast path must be a plain integer read**. A
+    # module-level activation count answers {active?} without a `Thread.current` lookup; the per-thread
+    # accumulator isolates the actual recording, so a non-recording thread that sees `active?` true (a
+    # sibling thread is recording) pays one extra nil-check and nothing else.
+    #
+    # The recorder is **observational**. It never triggers inference, never resolves what the dispatcher
+    # declined, and never touches `Scope` — it reads the receiver type the typer computed anyway and the
+    # `dynamic_origins` cause the typer already recorded. With no `effects:` block nothing calls
+    # {collect_for}, `@active_count` stays zero, and `rigor check` is byte-identical.
+    module Collector
+      KEY = :__rigor_effects_collector__
+      private_constant :KEY
+
+      # What one call site decided, as the typer saw it.
+      #
+      # `receiver_class` / `kind` are the class the receiver's type projects to (`Nominal[Foo]` →
+      # `["Foo", :instance]`, `Singleton[Time]` → `["Time", :singleton]`), nil when it projects to none.
+      # `dynamic` marks a `Dynamic` receiver and `cause` carries the {Inference::DynamicOrigin} name
+      # behind it, which is the detail the `dynamic-receiver` taint reports. `resolved` is false only when
+      # every dispatch tier declined — the typer's own "nothing here resolved" verdict, which is what
+      # separates an unresolvable implicit-self call from an ordinary one.
+      CallRecord = Data.define(:receiver_class, :kind, :dynamic, :cause, :resolved)
+
+      # Per-file, per-thread accumulator. Not frozen and never shared: it lives for one `analyze_file`.
+      class Accumulator
+        attr_reader :path, :calls, :attribution, :envelopes, :plugin_facts
+        attr_accessor :root
+
+        def initialize(path, attribution: Attribution.empty, envelopes: EnvelopeIndex.empty,
+                       plugin_facts: PluginFacts.empty)
+          @path = path
+          @attribution = attribution
+          @envelopes = envelopes
+          @plugin_facts = plugin_facts
+          # Node identity, not equality: two structurally identical call nodes in one file are different
+          # sites, and `Prism::Node#hash` is structural.
+          @calls = {}.compare_by_identity
+          @root = nil
+        end
+
+        # First write wins. The main typing pass records a site before any re-query does (`CheckRules`
+        # re-runs `type_of` over the same nodes, and a call-site-driven body re-type may visit a node a
+        # second time with a different receiver), so pinning the first decision keeps a file's record
+        # independent of how many times the node is visited — which is what makes pooled and sequential
+        # runs agree.
+        def record(node, call_record)
+          @calls[node] = call_record unless @calls.key?(node)
+        end
+
+        # Whether this node's decision is already pinned. Asked BEFORE the record is built, because the
+        # re-queries below are roughly half of all recording calls on a Rails app and building a record
+        # only to drop it is the whole of that half's cost.
+        def recorded?(node)
+          @calls.key?(node)
+        end
+
+        def mark_unresolved(node)
+          existing = @calls[node]
+          @calls[node] = existing.with(resolved: false) if existing
+        end
+      end
+
+      # Module-level activation count so {active?} is a plain integer read (GVL-atomic) rather than a
+      # `Thread.current` hash lookup.
+      @active_count = 0
+      @mutex = Mutex.new
+
+      module_function
+
+      # Runs `block` with collection active for `path` and returns the resulting {FileCollection}. Nests
+      # safely and restores the previous accumulator on exit.
+      #
+      # `attribution` is the project's `effects.attribution:` table (#385), carried on the window rather
+      # than read from a global: a worker process and the parent must scan under the same table, and the
+      # only thing that knows it is the configuration the run was built from. `envelopes` is the
+      # {EnvelopeIndex} of #386, carried the same way and for the same reason — the declared lane a call
+      # site imports must not depend on which process typed the file.
+      def collect_for(path, attribution: Attribution.empty, envelopes: EnvelopeIndex.empty,
+                      plugin_facts: PluginFacts.empty)
+        previous = Thread.current[KEY]
+        accumulator = Accumulator.new(path.to_s, attribution: attribution, envelopes: envelopes,
+                                                 plugin_facts: plugin_facts)
+        Thread.current[KEY] = accumulator
+        @mutex.synchronize { @active_count += 1 }
+        yield
+        build(accumulator)
+      ensure
+        Thread.current[KEY] = previous
+        @mutex.synchronize { @active_count -= 1 }
+      end
+
+      def active?
+        @active_count.positive?
+      end
+
+      # The parsed root of the file being analyzed. Recorded by the analysis body once the parse is known
+      # to have succeeded, so the scan runs over exactly what the typer saw.
+      def record_root(root)
+        accumulator = Thread.current[KEY]
+        accumulator.root = root if accumulator && accumulator.root.nil?
+      end
+
+      # One call site's dispatch decision. `receiver` is the type the typer computed for the receiver and
+      # `scope` the scope it computed it in; nothing here asks either for more.
+      #
+      # The `scope.source_path` guard matters: inter-procedural inference re-types a *callee's* body while
+      # the caller's file is being analyzed, and those nodes belong to the callee's own file collection.
+      def record_call(node, receiver, scope)
+        accumulator = Thread.current[KEY]
+        return if accumulator.nil? || accumulator.path != scope.source_path
+        # First write wins, so a re-query has nothing to add — and asking here rather than inside
+        # {Accumulator#record} is what stops it paying for the `Data` and the origin lookup below.
+        return if accumulator.recorded?(node)
+
+        dynamic = receiver.is_a?(Type::Dynamic)
+        class_name, kind = descriptor_for(receiver)
+        accumulator.record(
+          node,
+          CallRecord.new(
+            receiver_class: class_name, kind: kind, dynamic: dynamic,
+            cause: dynamic ? Inference::OriginLookup.origin_for(scope, node.receiver)&.to_s : nil,
+            resolved: true
+          )
+        )
+      end
+
+      # The typer's fallback verdict: no tier resolved this call.
+      def record_unresolved(node, source_path)
+        accumulator = Thread.current[KEY]
+        return if accumulator.nil? || accumulator.path != source_path
+
+        accumulator.mark_unresolved(node)
+      end
+
+      # The class a receiver type projects to, as `[class_name, kind]`. A deliberately small mirror of the
+      # dispatcher's own receiver descriptor: enough shapes that a fresh `[]` reads as `Array` and a
+      # constant receiver as its singleton, and nothing more. An unmapped type simply has no class name,
+      # which costs an edge rather than producing a wrong one.
+      def descriptor_for(receiver)
+        case receiver
+        when Type::Nominal then [receiver.class_name, :instance]
+        when Type::Singleton then [receiver.class_name, :singleton]
+        when Type::Tuple then ["Array", :instance]
+        when Type::HashShape then ["Hash", :instance]
+        when Type::Constant then [receiver.value.class.name, :instance]
+        when Type::Dynamic then descriptor_for(receiver.static_facet)
+        end
+      end
+
+      # Fail-soft (WD13): the scan raising drops this file's summaries and never reaches `rigor check`.
+      def build(accumulator)
+        return FileCollection.empty(accumulator.path) if accumulator.root.nil?
+
+        Scanner.scan(
+          root: accumulator.root, path: accumulator.path, calls: accumulator.calls,
+          attribution: accumulator.attribution, envelopes: accumulator.envelopes,
+          plugin_facts: accumulator.plugin_facts
+        )
+      rescue StandardError
+        FileCollection.new(path: accumulator.path, failed: true)
+      end
+
+      private_class_method :build, :descriptor_for
+    end
+  end
+end

data/lib/rigor/effects/config_envelopes.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+require_relative "envelope"
+require_relative "label_set"
+require_relative "method_key"
+
+module Rigor
+  module Effects
+    # Envelopes by **convention** — the `effects.envelopes:` block of `.rigor.yml` (ADR-103 WD5 (2);
+    # design note § 6.2).
+    #
+    # ```yaml
+    # effects:
+    #   envelopes:
+    #     - match: "app/presenters/**/*.rb"   # File.fnmatch, project-relative — the ADR-28 shape
+    #       effect: []                        # the empty envelope: `pure`
+    #     - namespace: "Policies::*"
+    #       effect: [mutate.local]
+    # ```
+    #
+    # This is the surface that pays on day one for a project that writes no RBS: one stanza bounds a whole
+    # architectural layer. An entry attaches an envelope to every method of every class it selects and
+    # **distributes exactly as a class-level annotation does** — reopenings and synthesised `attr_*` /
+    # `define_method` members included, never subclasses (a subclass matches only if it matches on its own
+    # account).
+    #
+    # ## Selection
+    #
+    # - `match:` selects by the class's **defining file**. A class matches when *any* file that defines a
+    #   method of it matches the glob — a class opened in `app/presenters/user.rb` and reopened in
+    #   `lib/patch.rb` is a presenter. `File.fnmatch?` with `FNM_PATHNAME`, project-relative, so `**` is
+    #   the only way across a directory boundary: the `unused --entry-point` and
+    #   `effects.snapshot.reach:` semantics, spelled once ({.path_match?}).
+    # - `namespace:` selects by the class's **fully-qualified name**, segment by segment ({.namespace_match?}).
+    #
+    # ## Precedence
+    #
+    # Nearest wins, and configuration is the furthest thing from the method:
+    #
+    #     per-method annotation  >  class-level annotation  >  config entry
+    #
+    # Among config entries, the **first** matching entry in file order wins — a list is read top to
+    # bottom, and a later entry never silently overrides one an author put above it. There is no merging:
+    # one method has at most one envelope, from exactly one source.
+    module ConfigEnvelopes
+      # What `location` carries for a configured envelope. Not a `path:line` — the loader cannot say which
+      # line the entry was written on — so it names the key path instead, which is what a reader greps for.
+      CONFIG_PATH = ".rigor.yml"
+
+      NO_ENVELOPES = {}.freeze
+      private_constant :NO_ENVELOPES
+
+      # One entry, resolved against the vocabulary.
+      #
+      # `bound` is {LabelSet::TOP} when some member of `effect:` is unrecognised — the fail-open rule, the
+      # same degradation an annotation carrying an unknown label takes — and `unknown_labels` is what
+      # `effect.unknown-label` reports off.
+      Entry = Data.define(:index, :match, :namespace, :bound, :labels, :unknown_labels) do
+        # `.rigor.yml effects.envelopes[2]` — how the `effect.envelope-exceeded` message names the source.
+        def location = "#{CONFIG_PATH} effects.envelopes[#{index}]"
+
+        # The bound quoted back the way the author wrote it, in the config's own spelling.
+        def spelling = "effect: [#{labels.join(', ')}]"
+
+        def top? = bound.top?
+      end
+
+      module_function
+
+      # Resolves `Configuration#effects_envelopes` against a registry.
+      #
+      # @param entries [Array<Hash>] the loaded, shape-validated entries
+      # @param registry [Registry] the vocabulary, project extensions included
+      # @return [Array<Entry>]
+      def build(entries:, registry:)
+        entries.each_with_index.map do |entry, index|
+          labels = Array(entry["effect"]).map(&:to_s)
+          unknown = labels.reject { |label| registry.known?(label) }
+          Entry.new(
+            index: index, match: entry["match"], namespace: entry["namespace"],
+            bound: unknown.empty? ? LabelSet.new(labels) : LabelSet::TOP,
+            labels: labels.freeze, unknown_labels: unknown.freeze
+          )
+        end.freeze
+      end
+
+      # The class-level envelopes the entries put on a project.
+      #
+      # @param entries [Array<Entry>]
+      # @param class_names [Enumerable<String>] every class the run collected units for
+      # @param sources [Hash{String => Array<String>}] `Runner#effect_sources` — `{method key => [path]}`
+      # @param project_root [String] what `sources` paths are relativised against
+      # @return [Hash{String => Envelope}] one envelope per selected class, keyed by class name
+      def for_classes(entries:, class_names:, sources: {}, project_root: Dir.pwd)
+        return NO_ENVELOPES if entries.empty?
+
+        files = files_by_class(sources, project_root)
+        class_names.each_with_object({}) do |class_name, out|
+          entry = entries.find { |candidate| selects?(candidate, class_name, files[class_name]) }
+          next if entry.nil?
+
+          out[class_name] = envelope_for(entry, class_name)
+        end
+      end
+
+      # The {Envelope} an entry puts on one class. Public because {EnvelopeIndex} resolves the same
+      # entries per *call site* rather than per project class ({.for_classes}'s shape), and the two
+      # must build the identical value: a bound that read differently at a call site and at the `def`
+      # would make the `≤` lane disagree with the check that enforces it.
+      def envelope_for(entry, class_name)
+        Envelope.build(
+          owner_key: class_name, bound: entry.bound, source: Envelope::CONFIG_SOURCE,
+          location: entry.location, spelling: entry.spelling,
+          unknown_labels: entry.unknown_labels, declared_labels: entry.labels
+        )
+      end
+
+      def selects?(entry, class_name, paths)
+        return namespace_match?(entry.namespace, class_name) if entry.namespace
+
+        Array(paths).any? { |path| path_match?(entry.match, path) }
+      end
+
+      # `File.fnmatch?` with `FNM_PATHNAME` over a project-relative path — the ADR-28 `path_glob` shape
+      # and the `unused --entry-point` one. `FNM_PATHNAME` is what makes `app/*/x.rb` stop at one
+      # directory and `**` the only way past it.
+      def path_match?(glob, path)
+        File.fnmatch?(glob, path, File::FNM_PATHNAME)
+      end
+
+      # A constant-path glob, matched **segment by segment** over the `::`-separated FQN:
+      #
+      # - a literal segment matches itself, and `*` inside one matches any run of characters *within* that
+      #   segment (`Api::V*` matches `Api::V2`);
+      # - `*` alone matches exactly one segment — `Presenters::*` matches `Presenters::User` and NOT
+      #   `Presenters::Admin::User`, nor bare `Presenters`;
+      # - `**` matches one or more consecutive segments — `Presenters::**` matches both `Presenters::User`
+      #   and `Presenters::Admin::User`, and still not bare `Presenters`.
+      #
+      # Deliberately not `File.fnmatch` over a `/`-substituted name: the semantics above are the ones the
+      # documentation states, and borrowing a path matcher would make them depend on how one library
+      # happens to treat a trailing `**`.
+      def namespace_match?(glob, class_name)
+        match_segments?(glob.to_s.split("::"), class_name.to_s.split("::"))
+      end
+
+      def match_segments?(pattern, name)
+        return name.empty? if pattern.empty?
+
+        head, *rest = pattern
+        return match_deep?(rest, name) if head == "**"
+        return false if name.empty?
+        return false unless File.fnmatch?(head, name.first)
+
+        match_segments?(rest, name.drop(1))
+      end
+
+      # `**` consumes at least one segment, then the remaining pattern must match what is left. Bounded by
+      # the name's own depth, so the recursion is a handful of frames on any real constant path.
+      def match_deep?(rest, name)
+        (1..name.length).any? { |taken| match_segments?(rest, name.drop(taken)) }
+      end
+
+      # `{class name => [project-relative path]}`, from the per-unit source table. Sorted and de-duplicated
+      # so a glob decision does not depend on Hash order.
+      def files_by_class(sources, project_root)
+        root = "#{File.absolute_path(project_root.to_s).chomp('/')}/"
+        sources.each_with_object({}) do |(key, paths), out|
+          owner = MethodKey.owner(key)
+          next if owner.nil?
+
+          bucket = (out[owner] ||= [])
+          Array(paths).each { |path| bucket << relativize(path, root) }
+        end.each_value(&:uniq!)
+      end
+
+      def relativize(path, root)
+        absolute = File.absolute_path(path.to_s)
+        absolute.start_with?(root) ? absolute[root.length..] : path.to_s
+      end
+
+      private_class_method :selects?, :match_segments?, :match_deep?, :files_by_class, :relativize
+    end
+  end
+end