rigortype 0.1.19 → 0.2.1

data/lib/rigor/plugin/manifest.rb

@@ -32,9 +32,9 @@ module Rigor
       # its `#prepare(services)` hook. `consumes:` lists the
       # `(plugin_id, name)` pairs this plugin reads from
       # `services.fact_store`. The loader uses both for
-      # topological sort + missing-producer detection (slice 5);
-      # slice 4 carries the declarations on the manifest but the
-      # loader does not yet enforce them.
+      # topological sort + missing-producer detection; slice 4
+      # added the declarations; slice 5 (`Loader#topo_sort_plugins`)
+      # enforces ordering and missing-producer validation.
       class Consumption < Data.define(:plugin_id, :name, :optional)
         def initialize(plugin_id:, name:, optional: false)
           super(plugin_id: plugin_id.to_s, name: name.to_sym, optional: optional ? true : false)
@@ -277,10 +277,18 @@ module Rigor
         end
       end
 
-      def validate_produces!(produces)
-        return if produces.is_a?(Array) && produces.all? { |p| p.is_a?(Symbol) || p.is_a?(String) }
+      # Shared shape check for the Array-of-X manifest fields. Every entry
+      # must satisfy the block; otherwise raise the uniform "must be an
+      # Array of <label>" message. Centralises the message format the
+      # field validators below share so it cannot drift between them.
+      def validate_array_of!(field, value, label, &)
+        return if value.is_a?(Array) && value.all?(&)
 
-        raise ArgumentError, "plugin manifest produces must be an Array of Symbol/String, got #{produces.inspect}"
+        raise ArgumentError, "plugin manifest #{field} must be an Array of #{label}, got #{value.inspect}"
+      end
+
+      def validate_produces!(produces)
+        validate_array_of!("produces", produces, "Symbol/String") { |p| p.is_a?(Symbol) || p.is_a?(String) }
       end
 
       # ADR-10 5a — `owns_receivers:` declares the class names
@@ -291,11 +299,7 @@ module Rigor
       # so plugin contributions stay authoritative for those
       # types.
       def validate_owns_receivers!(owns_receivers)
-        return if owns_receivers.is_a?(Array) && owns_receivers.all? { |c| c.is_a?(String) && !c.empty? }
-
-        raise ArgumentError,
-              "plugin manifest owns_receivers must be an Array of non-empty String, " \
-              "got #{owns_receivers.inspect}"
+        validate_array_of!("owns_receivers", owns_receivers, "non-empty String") { |c| c.is_a?(String) && !c.empty? }
       end
 
       # ADR-26 — `open_receivers:` declares the class names this
@@ -309,11 +313,7 @@ module Rigor
       # `owns_receivers:` (which routes dispatch); this one only
       # suppresses the diagnostic.
       def validate_open_receivers!(open_receivers)
-        return if open_receivers.is_a?(Array) && open_receivers.all? { |c| c.is_a?(String) && !c.empty? }
-
-        raise ArgumentError,
-              "plugin manifest open_receivers must be an Array of non-empty String, " \
-              "got #{open_receivers.inspect}"
+        validate_array_of!("open_receivers", open_receivers, "non-empty String") { |c| c.is_a?(String) && !c.empty? }
       end
 
       # ADR-13 slice 2 — `type_node_resolvers:` declares the
@@ -325,11 +325,9 @@ module Rigor
       # integration that actually drives the chain lands in
       # slice 3.
       def validate_type_node_resolvers!(resolvers)
-        return if resolvers.is_a?(Array) && resolvers.all?(TypeNodeResolver)
-
-        raise ArgumentError,
-              "plugin manifest type_node_resolvers must be an Array of " \
-              "Rigor::Plugin::TypeNodeResolver instances, got #{resolvers.inspect}"
+        validate_array_of!("type_node_resolvers", resolvers, "Rigor::Plugin::TypeNodeResolver instances") do |r|
+          r.is_a?(TypeNodeResolver)
+        end
       end
 
       # ADR-16 slice 1a — `block_as_methods:` declares the Tier A
@@ -338,11 +336,9 @@ module Rigor
       # actually narrows `Scope#self_type` for matching blocks
       # arrives in a subsequent slice.
       def validate_block_as_methods!(entries)
-        return if entries.is_a?(Array) && entries.all?(Macro::BlockAsMethod)
-
-        raise ArgumentError,
-              "plugin manifest block_as_methods must be an Array of " \
-              "Rigor::Plugin::Macro::BlockAsMethod instances, got #{entries.inspect}"
+        validate_array_of!("block_as_methods", entries, "Rigor::Plugin::Macro::BlockAsMethod instances") do |e|
+          e.is_a?(Macro::BlockAsMethod)
+        end
       end
 
       # ADR-16 slice 2a — `heredoc_templates:` declares the Tier C
@@ -351,11 +347,9 @@ module Rigor
       # manifest; the pre-pass + `SyntheticMethodIndex` that actually
       # emit synthetic methods arrive in slice 2b.
       def validate_heredoc_templates!(entries)
-        return if entries.is_a?(Array) && entries.all?(Macro::HeredocTemplate)
-
-        raise ArgumentError,
-              "plugin manifest heredoc_templates must be an Array of " \
-              "Rigor::Plugin::Macro::HeredocTemplate instances, got #{entries.inspect}"
+        validate_array_of!("heredoc_templates", entries, "Rigor::Plugin::Macro::HeredocTemplate instances") do |e|
+          e.is_a?(Macro::HeredocTemplate)
+        end
       end
 
       # ADR-36 — `nested_class_templates:` declares the
@@ -365,11 +359,10 @@ module Rigor
       # subclasses + their `#inner` reader through the existing
       # `SyntheticMethodIndex` primitive.
       def validate_nested_class_templates!(entries)
-        return if entries.is_a?(Array) && entries.all?(Macro::NestedClassTemplate)
-
-        raise ArgumentError,
-              "plugin manifest nested_class_templates must be an Array of " \
-              "Rigor::Plugin::Macro::NestedClassTemplate instances, got #{entries.inspect}"
+        validate_array_of!("nested_class_templates", entries,
+                           "Rigor::Plugin::Macro::NestedClassTemplate instances") do |e|
+          e.is_a?(Macro::NestedClassTemplate)
+        end
       end
 
       # ADR-16 slice 3a — `trait_registries:` declares the Tier B
@@ -379,11 +372,9 @@ module Rigor
       # `SyntheticMethodIndex` (slice 2b primitive) arrives in
       # slice 3b.
       def validate_trait_registries!(entries)
-        return if entries.is_a?(Array) && entries.all?(Macro::TraitRegistry)
-
-        raise ArgumentError,
-              "plugin manifest trait_registries must be an Array of " \
-              "Rigor::Plugin::Macro::TraitRegistry instances, got #{entries.inspect}"
+        validate_array_of!("trait_registries", entries, "Rigor::Plugin::Macro::TraitRegistry instances") do |e|
+          e.is_a?(Macro::TraitRegistry)
+        end
       end
 
       # ADR-20 slice 6 — `hkt_registrations:` declares the
@@ -398,11 +389,9 @@ module Rigor
       # user `.rbs` overlays merge on top of plugin entries
       # last-write-wins.
       def validate_hkt_registrations!(entries)
-        return if entries.is_a?(Array) && entries.all?(Inference::HktRegistry::Registration)
-
-        raise ArgumentError,
-              "plugin manifest hkt_registrations must be an Array of " \
-              "Rigor::Inference::HktRegistry::Registration instances, got #{entries.inspect}"
+        validate_array_of!("hkt_registrations", entries, "Rigor::Inference::HktRegistry::Registration instances") do |e|
+          e.is_a?(Inference::HktRegistry::Registration)
+        end
       end
 
       # ADR-20 slice 6 — `hkt_definitions:` declares the
@@ -415,11 +404,9 @@ module Rigor
       # via {Rigor::Inference::HktBody}'s node-constructor API
       # without parsing a string.
       def validate_hkt_definitions!(entries)
-        return if entries.is_a?(Array) && entries.all?(Inference::HktRegistry::Definition)
-
-        raise ArgumentError,
-              "plugin manifest hkt_definitions must be an Array of " \
-              "Rigor::Inference::HktRegistry::Definition instances, got #{entries.inspect}"
+        validate_array_of!("hkt_definitions", entries, "Rigor::Inference::HktRegistry::Definition instances") do |e|
+          e.is_a?(Inference::HktRegistry::Definition)
+        end
       end
 
       # ADR-25 — `signature_paths:` declares the RBS signature
@@ -429,11 +416,7 @@ module Rigor
       # loader validates each exists and `Environment.for_project`
       # merges the resolved set into the RBS environment.
       def validate_signature_paths!(paths)
-        return if paths.is_a?(Array) && paths.all? { |p| p.is_a?(String) && !p.empty? }
-
-        raise ArgumentError,
-              "plugin manifest signature_paths must be an Array of non-empty String, " \
-              "got #{paths.inspect}"
+        validate_array_of!("signature_paths", paths, "non-empty String") { |p| p.is_a?(String) && !p.empty? }
       end
 
       # ADR-28 — `protocol_contracts:` declares the path-scoped
@@ -449,11 +432,9 @@ module Rigor
       # MAY override `Plugin::Base#protocol_contracts` to fold in
       # per-project config (e.g. a custom convention path).
       def validate_protocol_contracts!(entries)
-        return if entries.is_a?(Array) && entries.all?(ProtocolContract)
-
-        raise ArgumentError,
-              "plugin manifest protocol_contracts must be an Array of " \
-              "Rigor::Plugin::ProtocolContract instances, got #{entries.inspect}"
+        validate_array_of!("protocol_contracts", entries, "Rigor::Plugin::ProtocolContract instances") do |e|
+          e.is_a?(ProtocolContract)
+        end
       end
 
       # ADR-38 — `additional_initializers:` declares the
@@ -465,11 +446,9 @@ module Rigor
       # loaded plugins; `Inference::ScopeIndexer` consults the set at
       # its single gate.
       def validate_additional_initializers!(entries)
-        return if entries.is_a?(Array) && entries.all?(AdditionalInitializer)
-
-        raise ArgumentError,
-              "plugin manifest additional_initializers must be an Array of " \
-              "Rigor::Plugin::AdditionalInitializer instances, got #{entries.inspect}"
+        validate_array_of!("additional_initializers", entries, "Rigor::Plugin::AdditionalInitializer instances") do |e|
+          e.is_a?(AdditionalInitializer)
+        end
       end
 
       # ADR-32 WD4 — `source_rbs_synthesizer:` declares a callable

data/lib/rigor/plugin/registry.rb

@@ -317,13 +317,12 @@ module Rigor
         !load_errors.empty?
       end
 
-      # ADR-13 slice 2 — flat ordered list of every loaded
-      # plugin's manifest-declared {TypeNodeResolver} instances,
-      # in plugin registration order. Slice 3 wires this into
-      # the parser's resolver chain; until then the method is a
-      # read-side aggregator only. The first non-nil
-      # `#resolve(node, scope)` return wins per ADR-13 WD3 / WD5
-      # — registration order is the user's lever.
+      # ADR-13 — flat ordered list of every loaded plugin's
+      # manifest-declared {TypeNodeResolver} instances, in plugin
+      # registration order. `Environment#build_name_scope` builds a
+      # `TypeNode::ResolverChain` from this list (environment.rb).
+      # The first non-nil `#resolve(node, scope)` return wins per
+      # ADR-13 WD3 / WD5 — registration order is the user's lever.
       def type_node_resolvers
         plugins.flat_map { |plugin| plugin.manifest.type_node_resolvers }
       end

data/lib/rigor/plugin/type_node_resolver.rb

@@ -24,14 +24,12 @@ module Rigor
     #     )
     #   end
     #
-    # Slice 2 of the ADR-13 envelope (this file) ships the base
-    # class + manifest hook + registry aggregation. The parser-
-    # side wiring that actually consults the resolver chain
-    # arrives in slice 3, when {Rigor::TypeNode::NameScope} and
-    # the dispatcher between {Rigor::Builtins::ImportedRefinements::Parser}
-    # and the chain land. Until then resolvers can be unit-tested
-    # in isolation but never run for a real `%a{rigor:v1:...}`
-    # payload.
+    # ADR-13 — base class, manifest hook, and registry aggregation
+    # for plugin-contributed type-node resolvers. Resolvers declared
+    # via `manifest(type_node_resolvers:)` run for every real
+    # `%a{rigor:v1:...}` payload through `TypeNode::ResolverChain`
+    # (built by `Environment#build_name_scope` from
+    # `Plugin::Registry#type_node_resolvers`).
     #
     # Resolvers SHOULD be stateless and re-entrant; the registry
     # builds the chain once per `Analysis::Runner.run` and may

data/lib/rigor/protection/diagnostic_oracle.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require_relative "../analysis/runner"
+
+module Rigor
+  module Protection
+    # ADR-69 Seam 1 — the **kill oracle** Rigor's analyzer-teeth measurement uses:
+    # a mutant is killed iff re-analysing it introduces a diagnostic absent from
+    # the clean baseline. This is exactly the behaviour ADR-62/63 shipped, lifted
+    # out of {MutationScanner} so a {TestSuiteOracle} (ADR-70) — which kills by
+    # *running tests* rather than by re-analysis — can sit beside it without the
+    # scanner baking in either assumption.
+    #
+    # The expensive builds (RBS environment + the whole-project pre-pass scan) are
+    # paid once by the caller and threaded in; each mutant reuses them through
+    # `Runner.new(prebuilt:)#run_source` (in-memory overlay, no disk write).
+    # Passing `prebuilt:` disables the run-result cache (whose key digests the
+    # *disk* file), so a mutant is never served a stale clean hit.
+    class DiagnosticOracle
+      def initialize(configuration:, environment:, project_scan:)
+        @configuration = configuration
+        @environment = environment
+        @project_scan = project_scan
+      end
+
+      # The clean per-file baseline: the diagnostic signatures a mutant must add
+      # to count as killed. Computed once per file by the caller.
+      def baseline(source:, path:)
+        analyse(source, path).to_set { |d| sig(d) }
+      end
+
+      # Killed iff the mutant introduces a diagnostic not in `baseline`.
+      def killed?(mutant_source:, path:, baseline:)
+        analyse(mutant_source, path).any? { |d| !baseline.include?(sig(d)) }
+      end
+
+      private
+
+      def analyse(source, path)
+        Rigor::Analysis::Runner.new(
+          configuration: @configuration, environment: @environment, prebuilt: @project_scan,
+          cache_store: nil, collect_stats: false
+        ).run_source(source: source, path: path).diagnostics
+      end
+
+      def sig(diagnostic)
+        [diagnostic.rule, diagnostic.path, diagnostic.line, diagnostic.column, diagnostic.message]
+      end
+    end
+  end
+end

data/lib/rigor/protection/mutation_scanner.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "mutator"
+require_relative "diagnostic_oracle"
+
+module Rigor
+  module Protection
+    # ADR-63 Tier 2 — the mutation *effectiveness* tier (the truth tier behind
+    # Tier 1's static {Inference::ProtectionScanner} proxy). For one file it
+    # answers the question Tier 1 only bounds: when a type-visible bug is
+    # introduced at a dispatch site, does Rigor actually catch it?
+    #
+    # Mechanism (the ADR-62 warm loop, narrowed to per-file measurement):
+    # generate the type-visible mutations ({Mutator}), keep only those whose
+    # receiver Rigor holds a concrete type for (the type-aware filter — the
+    # FP-safe meaning-maker; an unresolved receiver is kept), then for each ask
+    # the **kill oracle** whether the mutant is caught. The oracle is the ADR-69
+    # seam: {#scan_file} uses the {DiagnosticOracle} (a *new Rigor diagnostic* =
+    # a kill); {#scan_file_fused} additionally consults a {TestSuiteOracle} on the
+    # type-survivors (ADR-70 — the dynamic protection axis).
+    #
+    # The expensive builds (RBS environment + the whole-project pre-pass scan)
+    # are paid ONCE by the caller and threaded into the {DiagnosticOracle}; each
+    # mutant reuses them through `Runner.new(prebuilt:)#run_source` (in-memory
+    # overlay, no disk write).
+    class MutationScanner
+      # A surviving mutation site — a breakage Rigor did not catch.
+      SurvivingSite = Data.define(:line, :receiver, :method_name, :operator)
+
+      FileResult = Data.define(:path, :killed, :survived, :sites) do
+        # Mutations actually analysed (parse-invalid mutants are not counted).
+        def total = killed + survived
+
+        # Effectiveness ratio; a file with no type-relevant mutation is
+        # vacuously fully effective (no breakage was available to miss).
+        def ratio = total.zero? ? 1.0 : killed.to_f / total
+      end
+
+      # ADR-70 — one type-survivor classified by the dynamic (test) axis.
+      # `protection` is `:test` (a test caught it) or `:none` (unprotected — the
+      # "add a type OR a test here" sites).
+      FusedSite = Data.define(:line, :receiver, :method_name, :operator, :protection)
+
+      # ADR-70 — the per-file fused classification. The gradual short-circuit
+      # collapses the conceptual "doubly-protected" bucket into `type_killed`:
+      # a mutant the type checker already kills never reaches the suite, because
+      # the static net already suffices and re-running the suite to learn a test
+      # *would also* catch it is wasted work. So the observed buckets are three.
+      FusedFileResult = Data.define(:path, :type_killed, :test_killed, :sites) do
+        # The unprotected sites (neither a type nor a test caught the breakage).
+        def unprotected = sites.size
+        def total = type_killed + test_killed + unprotected
+
+        # Fused protected ratio — caught by *either* axis.
+        def ratio = total.zero? ? 1.0 : (type_killed + test_killed).to_f / total
+      end
+
+      # @param configuration [Rigor::Configuration]
+      # @param environment [Rigor::Environment] pre-built once by the caller
+      # @param project_scan [Rigor::Analysis::ProjectScan] pre-built once
+      # @param limit [Integer, nil] optional per-file mutation cap (sampled with
+      #   `seed`); nil analyses every type-relevant mutation (deterministic).
+      # @param seed [Integer] RNG seed for the optional sample.
+      # @param oracle [#baseline, #killed?, nil] the kill oracle (ADR-69 Seam 1);
+      #   defaults to the {DiagnosticOracle} (the ADR-62/63 behaviour).
+      # @param site_selector [:biteable, :all] which sites to mutate (ADR-69
+      #   Seam 2). `:biteable` (default) keeps only concrete-type sites Rigor can
+      #   bite; `:all` also mutates Dynamic-receiver dispatch sites — use only
+      #   with a {TestSuiteOracle} (the fused overlay), never the diagnostic path.
+      def initialize(configuration:, environment:, project_scan:, limit: nil, seed: 1, oracle: nil,
+                     site_selector: :biteable)
+        @environment = environment
+        @limit = limit
+        @seed = seed
+        @site_selector = site_selector
+        @oracle = oracle || DiagnosticOracle.new(
+          configuration: configuration, environment: environment, project_scan: project_scan
+        )
+      end
+
+      # @param path [String] the file to measure (used as the in-memory bind path)
+      # @param source [String, nil] the file's source; read from disk when nil
+      # @return [FileResult]
+      def scan_file(path, source: nil)
+        source ||= File.read(path, encoding: Encoding::UTF_8)
+        kept = kept_mutations(source, path)
+        return FileResult.new(path: path, killed: 0, survived: 0, sites: []) if kept.empty?
+
+        baseline = @oracle.baseline(source: source, path: path)
+        killed = 0
+        sites = []
+        kept.each do |mut|
+          case classify(source, path, mut, baseline)
+          when :killed then killed += 1
+          when :survived then sites << surviving_site(mut)
+            # :invalid — a parse-broken mutant; not a measurement, skip it.
+          end
+        end
+        FileResult.new(path: path, killed: killed, survived: sites.size, sites: sites)
+      end
+
+      # ADR-70 — the fused static∪dynamic measurement. Runs the type pass
+      # (the {DiagnosticOracle}); for every mutant the type checker did **not**
+      # kill, asks `test_oracle` whether the project's test suite catches it.
+      # The expensive suite run is paid only for type-survivors (the gradual
+      # short-circuit), so the cost is proportional to the protection hole.
+      # @param test_oracle [TestSuiteOracle]
+      # @return [FusedFileResult]
+      def scan_file_fused(path, test_oracle:, source: nil)
+        source ||= File.read(path, encoding: Encoding::UTF_8)
+        kept = kept_mutations(source, path)
+        return FusedFileResult.new(path: path, type_killed: 0, test_killed: 0, sites: []) if kept.empty?
+
+        baseline = @oracle.baseline(source: source, path: path)
+        type_killed = 0
+        test_killed = 0
+        sites = []
+        kept.each do |mut|
+          case classify(source, path, mut, baseline)
+          when :killed then type_killed += 1
+          when :survived
+            if test_oracle.killed?(path: path, original: source, mutant_source: mut.apply(source))
+              test_killed += 1
+            else
+              sites << fused_site(mut, :none)
+            end
+            # :invalid — a parse-broken mutant; not a measurement, skip it.
+          end
+        end
+        FusedFileResult.new(path: path, type_killed: type_killed, test_killed: test_killed, sites: sites)
+      end
+
+      private
+
+      # The mutations to measure: the biteable filter (concrete-type sites only;
+      # the FP-safe default — an unresolved receiver is kept) or, under the
+      # `:all` selector (ADR-69 Seam 2), every dispatch site including Dynamic
+      # receivers. Optionally sampled.
+      def kept_mutations(source, path)
+        mutator = Mutator.new(source)
+        muts = mutator.mutations
+        kept =
+          if @site_selector == :all
+            mutator.dispatch_site_mutations(muts, environment: @environment, path: path)
+          else
+            mutator.filter_by_type(muts, environment: @environment, path: path).first
+          end
+        sample(kept)
+      end
+
+      def classify(source, path, mut, baseline)
+        mutant_source = mut.apply(source)
+        return :invalid unless Prism.parse(mutant_source).success?
+
+        @oracle.killed?(mutant_source: mutant_source, path: path, baseline: baseline) ? :killed : :survived
+      rescue StandardError
+        # A harness-level failure on one mutant must not abort the file.
+        :invalid
+      end
+
+      def sample(mutations)
+        return mutations unless @limit
+
+        mutations.sample(@limit, random: Random.new(@seed))
+      end
+
+      def surviving_site(mut)
+        SurvivingSite.new(line: mut.line, receiver: mut.anchor_type,
+                          method_name: mut.method_name, operator: mut.operator.to_s)
+      end
+
+      def fused_site(mut, protection)
+        FusedSite.new(line: mut.line, receiver: mut.anchor_type, method_name: mut.method_name,
+                      operator: mut.operator.to_s, protection: protection)
+      end
+    end
+  end
+end