rigortype 0.3.2 → 0.3.4

data/lib/rigor/effects/registry.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+require_relative "label"
+
+module Rigor
+  module Effects
+    # The effect-label vocabulary: which spellings are recognised, which have been retired, and who
+    # may open a new root (ADR-103 WD2; normative in
+    # `docs/type-specification/effect-labels.md`).
+    #
+    # The shared layer is hand-written in `data/effects/registry.yml` — Steins' v1 set verbatim,
+    # Ruby's `mutate` leaves, the proposed shared core leaves and the application-meaning roots —
+    # so a later slice or a plugin extends the data, not this Ruby. Extensions arrive through
+    # {#with}, which is the one place root ownership is enforced.
+    #
+    # A Registry is a frozen value object; {#with} returns a new one rather than mutating.
+    class Registry
+      class Error < StandardError
+      end
+
+      # An added label whose root neither exists already nor belongs to the extender.
+      class OwnershipError < Error
+      end
+
+      # An added label that is not well-formed under {Label::PATTERN}.
+      class InvalidLabelError < Error
+      end
+
+      DATA_PATH = File.expand_path("../../../data/effects/registry.yml", __dir__)
+
+      # How far a misspelling may be from a known label before {#suggest} declines to guess. Two
+      # edits catches a transposition or a dropped segment character ("io.nte", "nondet.tim")
+      # without proposing an unrelated label for a genuinely new spelling.
+      SUGGESTION_DISTANCE_CAP = 2
+
+      # The shared registry as shipped. Memoised: the YAML parse is a once-per-process cost, and
+      # nothing consumes the registry yet, so it stays lazy rather than paying at `require "rigor"`.
+      def self.default
+        @default ||= load_file(DATA_PATH)
+      end
+
+      # The vocabulary one run works in: the shipped registry plus whatever `effects.labels:` opened
+      # (ADR-103 WD2 / #385). The project is the one extender that may open ANY root — listing a label in
+      # its own configuration is the vouching act — so this can only fail on a spelling `Configuration`
+      # already rejected at load, and a failure degrades to the shipped vocabulary rather than taking the
+      # run down.
+      #
+      # Memoised on the label list, because the answer is a frozen value object and every effects surface
+      # in a run asks for the same one: the envelope pass, the unknown-label check, the snapshot header.
+      #
+      # `plugin_facts` (#387) folds in every loaded plugin's `effect_labels:` FIRST, each under its own
+      # owner, so that a project's `effects.labels:` can then name a plugin-opened root and an envelope may
+      # bound `rails.activejob.enqueue` without the project having to re-declare the framework's vocabulary.
+      # The plugin layer is not memoised on its own — {PluginFacts} is already per-process — and the
+      # project layer keeps its memo keyed on the pair.
+      def self.for_configuration(configuration, plugin_facts: nil)
+        base = plugin_facts.nil? || plugin_facts.empty? ? default : plugin_facts.extend_registry(default)
+        labels = configuration.effects_labels
+        return base if labels.nil? || labels.empty?
+
+        (@extended ||= {})[[labels, base.labels]] ||= base.with(labels: labels, owner: nil)
+      rescue Error
+        default
+      end
+
+      # Build a registry from a registry-shaped YAML file. Missing or unreadable data degrades to
+      # an empty vocabulary rather than raising, matching the built-in catalogues' posture for a
+      # bare install that opted data out; every label then reads as unknown, which is fail-open.
+      def self.load_file(path)
+        raw = File.exist?(path) ? YAML.safe_load_file(path) : nil
+        raw = {} unless raw.is_a?(Hash)
+        new(
+          vocabulary_version: raw.fetch("vocabulary", 0),
+          labels: raw.fetch("labels", nil) || [],
+          retired: raw.fetch("retired", nil) || {}
+        )
+      end
+
+      attr_reader :vocabulary_version
+
+      def initialize(vocabulary_version:, labels:, retired: {})
+        @vocabulary_version = vocabulary_version
+        @labels = labels.map(&:to_s).uniq.sort.freeze
+        @known = build_known(@labels)
+        @roots = @known.select { |label| Label.parent(label).nil? }.sort.freeze
+        @retired = build_retired(retired)
+        freeze
+      end
+
+      # Every declared label, sorted. Implied ancestors (`email`, because `email.send` is declared)
+      # are recognised by {#known?} but are not rows of the vocabulary and are not listed here.
+      attr_reader :labels
+
+      # The roots of the vocabulary — the outermost segments {#with} treats as already owned.
+      attr_reader :roots
+
+      # Whether the vocabulary recognises `label`: an exact row, or an ancestor of one. A declared
+      # `io` is recognised because `io.net` exists, so a bound may name an interior node the data
+      # file never spells out on its own line.
+      def known?(label)
+        @known.include?(label)
+      end
+
+      # The nearest recognised label to a misspelling, within {SUGGESTION_DISTANCE_CAP} edits, or
+      # `nil` when nothing is close enough. A recognised label suggests nothing — ask {#known?}
+      # first.
+      def suggest(label)
+        return nil unless Label.valid?(label)
+        return nil if known?(label)
+
+        best = nil
+        best_distance = SUGGESTION_DISTANCE_CAP + 1
+        @known.each do |candidate|
+          distance = levenshtein(label, candidate, best_distance)
+          next unless distance < best_distance
+
+          best = candidate
+          best_distance = distance
+        end
+        best
+      end
+
+      # The replacement labels for a retired spelling, or `nil` when the spelling was never
+      # retired. A rename or a removal bumps {#vocabulary_version} and records the old spelling
+      # here so a snapshot written by an older Rigor still reads.
+      def retired(label)
+        @retired[label]
+      end
+
+      # A new registry carrying `labels` on top of this one.
+      #
+      # `owner` is the identity opening a root: a plugin id, or — for a first-party plugin that
+      # models a framework — the framework root it owns. `nil` is the project, which may open any
+      # root. Every added label must either descend from a root this registry already knows or
+      # open a root equal to `owner`.
+      def with(labels:, owner:)
+        added = labels.map(&:to_s)
+        added.each do |label|
+          raise InvalidLabelError, "not a well-formed effect label: #{label.inspect}" unless Label.valid?(label)
+
+          check_ownership(label, owner)
+        end
+        self.class.new(vocabulary_version: @vocabulary_version, labels: @labels + added, retired: @retired)
+      end
+
+      private
+
+      def check_ownership(label, owner)
+        root = Label.root(label)
+        return if @roots.include?(root)
+        return if owner.nil?
+        return if owner == root
+
+        raise OwnershipError,
+              "#{owner.inspect} may not open the effect-label root #{root.inspect} (from #{label.inspect}); " \
+              "a non-project extender opens only the root it owns"
+      end
+
+      def build_known(labels)
+        known = labels.to_set
+        labels.each { |label| Label.ancestors(label).each { |ancestor| known << ancestor } }
+        known.freeze
+      end
+
+      def build_retired(retired)
+        retired.to_h { |spelling, replacements| [spelling.to_s, Array(replacements).map(&:to_s).freeze] }.freeze
+      end
+
+      # Bounded Levenshtein. Answers `cap + 1` — "further than the cap" — as soon as the length
+      # difference or a whole row of the matrix rules the candidate out, so scanning the vocabulary
+      # for a suggestion stays cheap.
+      def levenshtein(from, to, cap)
+        beyond = cap + 1
+        return beyond if (from.length - to.length).abs > cap
+
+        previous = (0..to.length).to_a
+        from.each_char.with_index(1) do |char, row|
+          current = [row]
+          to.each_char.with_index(1) do |other, column|
+            cost = char == other ? 0 : 1
+            current << [current[column - 1] + 1, previous[column] + 1, previous[column - 1] + cost].min
+          end
+          return beyond if current.min > cap
+
+          previous = current
+        end
+        previous.last > cap ? beyond : previous.last
+      end
+    end
+  end
+end

data/lib/rigor/effects/scanner.rb

@@ -0,0 +1,290 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "../source/constant_path"
+require_relative "../source/node_children"
+require_relative "attribution"
+require_relative "envelope_index"
+require_relative "file_collection"
+require_relative "local_ownership"
+require_relative "origin"
+require_relative "framework_units"
+require_relative "plugin_facts"
+require_relative "summary"
+require_relative "unit_scan"
+
+module Rigor
+  module Effects
+    # Turns one file's AST plus the call decisions the typer recorded for it into a {FileCollection}.
+    #
+    # The scanner owns **identity** — which effect units the file defines and what each is keyed as — and
+    # delegates each unit's body to {UnitScan}. Keys follow the existing symbol tables (ADR-103 WD14):
+    # `Class#m` for an instance method, `Class.m` for a singleton one, and `<toplevel>#m` for a `def`
+    # outside any class body. Reopenings in one file join here; reopenings across files join when the
+    # runner merges the collections.
+    #
+    # Three kinds of unit exist beyond a plain `def`:
+    #
+    # - `define_method(:literal) { … }` — the block is the method's body. The def-node discovery tables
+    #   skip it, so this is the minimal extension WD14 calls for, made here rather than in `ScopeIndexer`
+    #   because nothing outside effects needs it yet.
+    # - `attr_reader` / `attr_writer` / `attr_accessor` — synthesised: a reader is ∅, a writer is
+    #   `mutate.self`. Without them a caller's edge into an accessor would read as unresolved.
+    # - a nested `def` — its own unit under the same class, never contained in the enclosing method.
+    #
+    # **This walk exists only when collection is on.** ADR-103 WD13 prefers riding `ScopeIndexer`'s
+    # existing `def` descent; a separate walk is taken here because the scanner must also attribute each
+    # recorded call *node* to its enclosing unit, and doing that inside the indexer would put an
+    # effects-shaped concern on the hot path for every run. Off, this file is never loaded past `require`.
+    class Scanner
+      # Mirrors `Inference::ScopeIndexer::TOP_LEVEL_DEF_KEY`. Spelled again rather than required so the
+      # effects namespace does not pull the indexer in; the two are pinned together by spec.
+      TOP_LEVEL_KEY = "<toplevel>"
+
+      # Receiver-less calls in a class / module body that {#record_declaration} interprets. Everything
+      # else in a class body is out of scope in v1 — its statements run at load time, which is a unit of
+      # its own that no slice models yet.
+      DECLARATION_MACROS = %i[include prepend attr_reader attr_writer attr_accessor define_method].to_set.freeze
+
+      MUTATE_SELF = LabelSet.new(["mutate.self"])
+      private_constant :MUTATE_SELF
+
+      # A synthesised writer's summary is the same value at every `attr_accessor` in the project, so it is
+      # built once rather than per accessor.
+      WRITER_SUMMARY = Summary.new(bundles: { Origin.construct("attr-writer") => MUTATE_SELF })
+      private_constant :WRITER_SUMMARY
+
+      def self.scan(root:, path:, calls:, attribution: Attribution.empty, envelopes: EnvelopeIndex.empty,
+                    plugin_facts: PluginFacts.empty)
+        new(path: path, calls: calls, attribution: attribution, envelopes: envelopes,
+            plugin_facts: plugin_facts).scan(root)
+      end
+
+      def initialize(path:, calls:, attribution: Attribution.empty, envelopes: EnvelopeIndex.empty,
+                     plugin_facts: PluginFacts.empty)
+        @path = path
+        @calls = calls
+        @attribution = attribution
+        @envelopes = envelopes
+        @plugin_facts = plugin_facts
+        @summaries = {}
+        @edges = {}
+        @superclasses = {}
+        @includes = {}
+        # ADR-103 WD10 / #387 — the class-body facts the framework-edge strategies read, harvested only
+        # when a loaded plugin declared one. A run with no `effect_edges:` never allocates them.
+        @harvest = plugin_facts.edges? ? {} : nil
+      end
+
+      def scan(root)
+        walk(root, [], false)
+        synthesize_framework_units
+        FileCollection.new(
+          path: @path, summaries: @summaries, edges: @edges,
+          superclasses: @superclasses, includes: @includes
+        )
+      end
+
+      private
+
+      def walk(node, prefix, singleton)
+        return unless node.is_a?(Prism::Node)
+
+        case node
+        when Prism::ClassNode, Prism::ModuleNode
+          return walk_namespace(node, prefix)
+        when Prism::SingletonClassNode
+          return walk(node.body, prefix, true) if node.body
+        when Prism::DefNode
+          return enter_def(node, prefix, singleton)
+        when Prism::CallNode
+          harvest_class_body_macro(node, prefix)
+          return record_declaration(node, prefix) if declaration?(node)
+        end
+
+        node.rigor_each_child { |child| walk(child, prefix, singleton) }
+      end
+
+      def walk_namespace(node, prefix)
+        name = Source::ConstantPath.qualified_name(node.constant_path)
+        return node.rigor_each_child { |child| walk(child, prefix, false) } if name.nil?
+
+        nested = prefix + [name]
+        record_superclass(nested.join("::"), node, prefix) if node.is_a?(Prism::ClassNode)
+        walk(node.body, nested, false) if node.body
+      end
+
+      def enter_def(node, prefix, singleton)
+        instance_method = !singleton && node.receiver.nil?
+        harvest_for(prefix)[:defs] << node.name.to_s if @harvest && instance_method && !prefix.empty?
+        add_unit(
+          class_name_for(prefix), node.name.to_s, singleton || !node.receiver.nil?,
+          node.body, node.parameters
+        )
+      end
+
+      # ADR-103 WD10 — a receiver-less call in a class body, recorded as `macro => [literal symbol
+      # arguments]`. That is all the framework-edge strategies need: `before_save :normalize` names a
+      # method on the same class, and a computed callback (`before_save -> { … }`, a method object) names
+      # none the strategy could resolve, so it contributes nothing rather than a guess. The block form is
+      # already contained in the class body, which v1 does not model as a unit at all.
+      def harvest_class_body_macro(node, prefix)
+        return if @harvest.nil? || prefix.empty? || !node.receiver.nil?
+
+        entry = harvest_for(prefix)
+        name = node.name.to_s
+        if FrameworkUnits::CALLBACK_MACROS.include?(name)
+          (entry[:macros][name] ||= []).concat(symbol_arguments(node))
+        elsif uniqueness_validator?(node, name)
+          entry[:uniqueness] = true
+        end
+      end
+
+      # `validates :email, uniqueness: true` and `validates_uniqueness_of :email` — the validation whose
+      # implementation is a `SELECT`.
+      def uniqueness_validator?(node, name)
+        return true if name == FrameworkUnits::UNIQUENESS_MACRO
+        return false unless name == FrameworkUnits::VALIDATES_MACRO
+
+        node.arguments&.arguments&.any? do |argument|
+          argument.is_a?(Prism::KeywordHashNode) && argument.elements.any? do |element|
+            element.is_a?(Prism::AssocNode) && element.key.is_a?(Prism::SymbolNode) &&
+              element.key.unescaped == FrameworkUnits::UNIQUENESS_OPTION
+          end
+        end || false
+      end
+
+      def harvest_for(prefix)
+        @harvest[class_name_for(prefix)] ||= { defs: [], macros: {}, uniqueness: false }
+      end
+
+      # Files the units the framework contributes for each class this file declares. Runs after the walk,
+      # because a callback macro may be written below the `def` it names and a mailer action may be
+      # declared anywhere in the body.
+      def synthesize_framework_units
+        return if @harvest.nil?
+
+        @harvest.each do |class_name, entry|
+          FrameworkUnits.synthesize(
+            class_name: class_name, instance_methods: entry[:defs], macros: entry[:macros],
+            uniqueness: entry[:uniqueness], plugin_facts: @plugin_facts
+          ).each { |key, summary, edges| merge_unit(key, summary, edges) }
+        end
+      end
+
+      # Scans one unit and files its summary, then recurses into the units its body declared. Fail-soft
+      # per unit (ADR-103 WD13): a unit the scanner cannot finish is recorded as non-exhaustive with
+      # `collector-error` and its siblings are unaffected.
+      def add_unit(class_name, method_name, singleton, body, parameters)
+        key = "#{class_name}#{singleton ? '.' : '#'}#{method_name}"
+        names = parameter_names(parameters)
+        scan = UnitScan.new(
+          singleton: singleton, parameters: names,
+          block_parameter: block_parameter_name(parameters),
+          owned_locals: LocalOwnership.owned(body, names), calls: @calls,
+          attribution: @attribution, envelopes: @envelopes, plugin_facts: @plugin_facts,
+          owner_class: class_name
+        )
+        summary, edges = scan.run(body)
+        merge_unit(key, summary, edges)
+        scan.nested.each do |name, nested_singleton, nested_body, nested_parameters|
+          add_unit(class_name, name, singleton || nested_singleton, nested_body, nested_parameters)
+        end
+      rescue StandardError
+        merge_unit(key, Summary.tainted("collector-error", method_name), [])
+      end
+
+      # A receiver-less call in a class / module body that declares units or ancestry. Class bodies are
+      # not themselves effect units in v1 (their statements run at load time), so nothing else in one
+      # contributes labels — but `include` and the accessor macros decide what the *methods* are.
+      def declaration?(node)
+        node.receiver.nil? && DECLARATION_MACROS.include?(node.name)
+      end
+
+      def record_declaration(node, prefix)
+        class_name = class_name_for(prefix)
+        case node.name
+        when :include, :prepend then record_includes(class_name, node, prefix)
+        when :define_method then declare_define_method(class_name, node)
+        else synthesize_accessors(class_name, node)
+        end
+      end
+
+      def declare_define_method(class_name, node)
+        unit = UnitScan.define_method_unit(node)
+        return if unit.nil?
+
+        name, singleton, body, parameters = unit
+        add_unit(class_name, name, singleton, body, parameters)
+      end
+
+      def synthesize_accessors(class_name, node)
+        symbol_arguments(node).each do |name|
+          merge_unit("#{class_name}##{name}", Summary.empty, []) unless node.name == :attr_writer
+          next if node.name == :attr_reader
+
+          merge_unit("#{class_name}##{name}=", WRITER_SUMMARY, [])
+        end
+      end
+
+      def record_includes(class_name, node, prefix)
+        names = constant_arguments(node).flat_map { |name| lexical_candidates(name, prefix) }
+        (@includes[class_name] ||= []).concat(names) unless names.empty?
+      end
+
+      def record_superclass(full_name, node, prefix)
+        superclass = node.superclass && Source::ConstantPath.qualified_name(node.superclass)
+        @superclasses[full_name] = lexical_candidates(superclass, prefix) if superclass
+      end
+
+      # An ancestry name is recorded AS WRITTEN — `class Loud < Base` inside `module Tracer` names
+      # `Base`, not `Tracer::Base` — and a single file cannot say which constant that resolves to. So the
+      # scanner records the candidates Ruby's own lexical lookup would try, most-qualified first, and the
+      # propagator picks the one the merged project actually defines. Same shape as `ScopeIndexer`'s
+      # as-written superclass table, resolved at the same point: when the whole project is in view.
+      def lexical_candidates(name, prefix)
+        return [name] if prefix.empty? || name.start_with?("#{prefix.join('::')}::")
+
+        prefix.length.downto(1).map { |depth| "#{prefix.first(depth).join('::')}::#{name}" } + [name]
+      end
+
+      def merge_unit(key, summary, edges)
+        @summaries[key] = @summaries.key?(key) ? @summaries[key].join(summary) : summary
+        (@edges[key] ||= []).concat(edges) unless edges.empty?
+      end
+
+      def class_name_for(prefix)
+        prefix.empty? ? TOP_LEVEL_KEY : prefix.join("::")
+      end
+
+      def symbol_arguments(node)
+        node.arguments&.arguments&.filter_map { |argument| argument.unescaped if argument.is_a?(Prism::SymbolNode) } ||
+          []
+      end
+
+      def constant_arguments(node)
+        node.arguments&.arguments&.filter_map { |argument| Source::ConstantPath.qualified_name(argument) } || []
+      end
+
+      def parameter_names(parameters)
+        return Set.new unless parameters.is_a?(Prism::ParametersNode)
+
+        names = Set.new
+        [parameters.requireds, parameters.optionals, parameters.posts, parameters.keywords].each do |group|
+          group.each { |parameter| names << parameter.name.to_s if parameter.respond_to?(:name) && parameter.name }
+        end
+        [parameters.rest, parameters.keyword_rest].each do |parameter|
+          names << parameter.name.to_s if parameter.respond_to?(:name) && parameter&.name
+        end
+        names
+      end
+
+      def block_parameter_name(parameters)
+        return nil unless parameters.is_a?(Prism::ParametersNode)
+
+        parameters.block&.name&.to_s
+      end
+    end
+  end
+end

data/lib/rigor/effects/signature_sources.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Rigor
+  module Effects
+    # Everything an effect envelope may be written in, as `[buffer name, RBS source]` pairs
+    # (ADR-103 WD5 / WD6; #383 / #384).
+    #
+    # Two strata, and the exclusion is the point: the project's own `signature_paths:` tree (or the
+    # `sig/` default `Environment.for_project` falls back to) plus the loader's **virtual** entries —
+    # which is how rbs-inline's `# @rbs %a{…}` comments and a plugin's `source_rbs` synthesis arrive.
+    # Gem-shipped and bundled RBS is deliberately absent: WD6 makes project-authored envelopes the
+    # checked stratum, so a `%a{pure}` in rbs core cannot bound a project method that shares its key.
+    #
+    # Shared by the two passes that read declarations — the envelope check and the
+    # annotations-unchecked residual — so the residual can never disagree with the check about what
+    # counts as "the project's own signatures".
+    module SignatureSources
+      # Where `Environment.for_project` looks when no `signature_paths:` is configured. Spelled again
+      # here rather than required, because the constant is private to {Rigor::Environment} and a walk
+      # over the project's own files has no business reaching into its builder.
+      DEFAULT_ROOTS = ["sig"].freeze
+
+      # A cheap text pre-filter for "does this source carry an effect annotation at all". It matches
+      # the two spellings the envelope reader honours and nothing else, so a signature tree with no
+      # effect annotation is answered by one regex per file and never parsed. It is a ROUTING test,
+      # not the grammar — `RbsExtended.parse_effect_annotation` is still what decides meaning.
+      ANNOTATION_HINT = /%a\{\s*(?:pure\s*\}|rigor:v1:effect\b)/
+
+      # A `virtual:<plugin-id>:<source path>` buffer is rbs-inline's (or a plugin's) synthesized RBS for
+      # a Ruby file the author actually wrote in. Naming that file is what a reader can act on, so the
+      # synthetic prefix comes off before the name is made project-relative.
+      VIRTUAL_BUFFER_PATTERN = /\Avirtual:[^:]*:/
+
+      module_function
+
+      # The path a reader can open, for a buffer name from {.collect}: the `.rbs` file as configured,
+      # or the `.rb` file behind a `virtual:` buffer, project-relative either way.
+      def source_path(name)
+        stripped = name.to_s.sub(VIRTUAL_BUFFER_PATTERN, "")
+        root = "#{Dir.pwd}#{File::SEPARATOR}"
+        stripped.start_with?(root) ? stripped[root.length..] : stripped
+      end
+
+      # @param signature_paths [Array<String>, nil] the configured roots; empty / nil takes the default.
+      # @param virtual_rbs [Array<Array(String, String)>, nil] the loader's virtual entries.
+      # @return [Array<Array(String, String)>]
+      def collect(signature_paths:, virtual_rbs: nil)
+        files = roots(signature_paths).flat_map { |root| Dir.glob(File.join(root.to_s, "**", "*.rbs")).sort }
+        sources = files.filter_map do |path|
+          [path, File.read(path)]
+        rescue StandardError
+          nil
+        end
+        sources + Array(virtual_rbs).map { |name, content| [name.to_s, content.to_s] }
+      end
+
+      def roots(signature_paths)
+        signature_paths.nil? || signature_paths.empty? ? DEFAULT_ROOTS : signature_paths
+      end
+
+      # The first `[name, content, line]` carrying an effect annotation, or nil. Line numbers are
+      # 1-based and count into `content`, which for a `virtual:` buffer is the SYNTHESIZED text — the
+      # caller re-anchors it against the Ruby file when that matters.
+      def first_annotated(sources)
+        sources.each do |name, content|
+          content.each_line.with_index(1) do |line, number|
+            return [name, content, number] if ANNOTATION_HINT.match?(line)
+          end
+        end
+        nil
+      end
+    end
+  end
+end