rigortype 0.1.19 → 0.2.0

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

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "../analysis/runner"
+require_relative "mutator"
+
+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:
+    # re-analyse the mutated SOURCE against a clean baseline and read whether a
+    # NEW diagnostic appears. A *killed* mutation is a caught breakage; a
+    # *survived* one is a breakage Rigor missed — an "add a type here" site.
+    #
+    # The expensive builds (RBS environment + the whole-project pre-pass scan)
+    # are paid ONCE by the caller and threaded in via `environment:` /
+    # `project_scan:`; 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 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
+
+      # @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.
+      def initialize(configuration:, environment:, project_scan:, limit: nil, seed: 1)
+        @configuration = configuration
+        @environment = environment
+        @project_scan = project_scan
+        @limit = limit
+        @seed = seed
+      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)
+        mutator = Mutator.new(source)
+        kept, = mutator.filter_by_type(mutator.mutations, environment: @environment, path: path)
+        kept = sample(kept)
+        return FileResult.new(path: path, killed: 0, survived: 0, sites: []) if kept.empty?
+
+        baseline = signatures(analyse(source, path))
+        measure(source, path, kept, baseline)
+      end
+
+      private
+
+      def measure(source, path, mutations, baseline)
+        killed = 0
+        sites = []
+        mutations.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
+
+      def classify(source, path, mut, baseline)
+        mutant_source = mut.apply(source)
+        return :invalid unless Prism.parse(mutant_source).success?
+
+        new_diagnostics = analyse(mutant_source, path).reject { |d| baseline.include?(sig(d)) }
+        new_diagnostics.empty? ? :survived : :killed
+      rescue StandardError
+        # A harness-level failure on one mutant must not abort the file.
+        :invalid
+      end
+
+      # cache_store: nil + prebuilt: scan ⇒ the run cache is bypassed and the
+      # mutant is always re-analysed against the in-memory bytes.
+      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 sample(mutations)
+        return mutations unless @limit
+
+        mutations.sample(@limit, random: Random.new(@seed))
+      end
+
+      def signatures(diagnostics) = diagnostics.to_set { |d| sig(d) }
+      def sig(diagnostic) = [diagnostic.rule, diagnostic.path, diagnostic.line, diagnostic.column, diagnostic.message]
+
+      def surviving_site(mut)
+        SurvivingSite.new(line: mut.line, receiver: mut.anchor_type,
+                          method_name: mut.method_name, operator: mut.operator.to_s)
+      end
+    end
+  end
+end

data/lib/rigor/protection/mutator.rb

@@ -0,0 +1,246 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "../scope"
+require_relative "../inference/scope_indexer"
+
+module Rigor
+  # ADR-63 Tier 2 — the productized subset of the dev-only mutation-testing
+  # harness (`tool/mutation/`, ADR-62). Only the *per-file effectiveness
+  # measurement* lives here — the type-visible {Mutator} and the warm-loop
+  # {MutationScanner} kill-rate measurement. The dev sweep / fuzz / survivor
+  # clustering stay off the frozen surface in `tool/mutation/mutate.rb`
+  # (which now reuses this {Mutator} so there is one source of truth).
+  module Protection
+    # One concrete edit: replace source bytes [start, stop) with `replacement`.
+    # `anchor` is the Prism node whose inferred type decides type-relevance —
+    # the call receiver whose contract the mutation could violate, or nil when
+    # there is no concrete receiver (implicit-self call, literal outside a call).
+    # `anchor_type` (the rendered receiver type) and `method_name` are filled in
+    # for reporting a surviving site; both may stay nil.
+    Mutation = Struct.new(
+      :operator, :expected_rule, :start, :stop, :replacement, :line, :label, :anchor,
+      :anchor_type, :method_name,
+      keyword_init: true
+    ) do
+      def apply(source)
+        prefix = source.byteslice(0, start)
+        suffix = source.byteslice(stop, source.bytesize - stop) || ""
+        "#{prefix}#{replacement}#{suffix}"
+      end
+    end
+
+    # Generates type-visible mutations of a Ruby source string by walking the
+    # Prism AST and recording byte-range splices (no unparser needed — Prism
+    # hands us exact offsets, and the analyzer re-parses the spliced source).
+    #
+    # A mutation is "type-visible" when it should trip a diagnostic rule *if*
+    # Rigor holds a type at the site: a call-argument literal dropped to `nil`
+    # or type-swapped (→ `call.argument-type-mismatch`), or a call site renamed
+    # to a missing method (→ `call.undefined-method`). Only call sites and
+    # bodies are mutated, never `def` signatures, so a reused project scan stays
+    # valid.
+    class Mutator
+      IDENT = /\A[a-z_][A-Za-z0-9_]*\z/
+      QUOTES = ['"', "'"].freeze
+      # Mutating an argument to a universal-equality method is always an
+      # equivalent mutant: Ruby's `==` / `<=>` family returns false / nil on a
+      # type mismatch rather than raising, so the engine exempts them
+      # (`UNIVERSAL_EQUALITY_METHODS`). Skip them to keep survivors meaningful.
+      UNIVERSAL_EQUALITY = %w[== != eql? equal? <=>].freeze
+
+      # Every operator the mutator knows. Each maps to the diagnostic rule
+      # family it is *engineered* to trip when the mutated value/call sits in a
+      # context where Rigor has type knowledge.
+      ALL_OPERATORS = %i[nil_inject type_swap undefined_method arity_extra].freeze
+
+      # The default set. `arity_extra` is excluded: most Ruby methods accept an
+      # extra argument (splat / optional), so appending one is usually an
+      # equivalent mutant — it contributes almost only noise. Re-enable it
+      # explicitly via `operators:` to measure arity teeth. (A signature-arity
+      # guard would make it default-worthy — a follow-up.)
+      OPERATORS = %i[nil_inject type_swap undefined_method].freeze
+
+      def initialize(source, operators: OPERATORS)
+        @source = source
+        @operators = operators
+        @parse = Prism.parse(source)
+        @anchor_for = {} # literal node -> its enclosing call's receiver node (or nil)
+      end
+
+      def mutations
+        return [] unless @parse.success?
+
+        index_literal_anchors(@parse.value)
+        out = []
+        walk(@parse.value) { |node| collect(node, out) }
+        out
+      end
+
+      # Phase 1.5 — keep only mutations whose anchor types to a concrete,
+      # non-Dynamic type, i.e. a site where Rigor actually holds a contract the
+      # mutation could violate. Drops implicit-self calls and literals outside a
+      # typed call (no contract → guaranteed survival → noise). FP-safe
+      # direction: an unresolved/probe-failed type KEEPS the mutation, so the
+      # filter never hides a kill it is unsure about — it only removes
+      # provably-Dynamic sites. Returns [kept, dropped_count]. Builds the scope
+      # index from THIS mutator's parse so anchor node identity matches the keys.
+      def filter_by_type(mutations, environment:, path:)
+        base = Rigor::Scope.empty(environment: environment, source_path: path)
+        index = Rigor::Inference::ScopeIndexer.index(@parse.value, default_scope: base)
+        cache = {}
+        kept = mutations.select do |mut|
+          keep, type = anchor_decision(mut.anchor, index, cache)
+          mut.anchor_type = type if keep
+          keep
+        end
+        [kept, mutations.size - kept.size]
+      end
+
+      private
+
+      def walk(node, &blk)
+        return if node.nil?
+
+        blk.call(node)
+        node.compact_child_nodes.each { |child| walk(child, &blk) }
+      end
+
+      def collect(node, out)
+        case node
+        when Prism::IntegerNode, Prism::FloatNode
+          literal_mutations(node, out, numeric: true)
+        when Prism::StringNode
+          literal_mutations(node, out, numeric: false)
+        when Prism::CallNode
+          call_mutations(node, out)
+        end
+      end
+
+      # Record, for each literal that is a direct call argument, the receiver of
+      # the enclosing call — the anchor whose param contract a literal mutation
+      # could violate. Literals elsewhere get a nil anchor (filtered out under
+      # the type filter).
+      def index_literal_anchors(node)
+        return if node.nil?
+
+        if node.is_a?(Prism::CallNode) && node.arguments
+          node.arguments.arguments.each do |arg|
+            @anchor_for[arg] = [node.receiver, node.name.to_s] if literal?(arg)
+          end
+        end
+        node.compact_child_nodes.each { |child| index_literal_anchors(child) }
+      end
+
+      def literal?(node)
+        node.is_a?(Prism::IntegerNode) || node.is_a?(Prism::FloatNode) || node.is_a?(Prism::StringNode)
+      end
+
+      # Returns [keep?, rendered_type]. Keep when `anchor` is a site where Rigor
+      # holds a concrete (non-Dynamic/Top) type. FP-safe: an unresolved or
+      # probe-failed type keeps the mutation (with a nil rendered type).
+      def anchor_decision(anchor, index, cache)
+        return [false, nil] if anchor.nil?
+        return cache[anchor] if cache.key?(anchor)
+
+        cache[anchor] = compute_anchor_decision(anchor, index)
+      end
+
+      def compute_anchor_decision(anchor, index)
+        scope = index[anchor]
+        return [true, nil] if scope.nil? # unresolved scope → keep (FP-safe)
+
+        type = scope.type_of(anchor)
+        return [true, nil] if type.nil?
+
+        concrete = !non_concrete_type?(type)
+        [concrete, concrete ? render_type(type) : nil]
+      rescue StandardError
+        [true, nil] # never let a probe failure hide a candidate
+      end
+
+      # A receiver type Rigor cannot bite on, so a mutation anchored to it would
+      # survive as noise: `Dynamic` / `Top` / `bot`, or a union with any such arm
+      # (gradually valid — `Array | Dynamic[top]`.whatever never fires). A union
+      # of fully-concrete arms (`String | Symbol`) stays concrete — it now has
+      # undefined-method teeth.
+      def non_concrete_type?(type)
+        return true if type.is_a?(Rigor::Type::Dynamic) || type.is_a?(Rigor::Type::Top) ||
+                       type.is_a?(Rigor::Type::Bot)
+        return type.members.any? { |member| non_concrete_type?(member) } if type.is_a?(Rigor::Type::Union)
+
+        false
+      end
+
+      def render_type(type)
+        type.respond_to?(:describe) ? type.describe(:short) : type.to_s
+      rescue StandardError
+        type.class.name
+      end
+
+      # Mutate a literal: drop it to nil (possible-nil channel) and swap its
+      # type (type-mismatch channel). String literals are only touched when the
+      # node is a real quoted string, so we never corrupt `%w[...]` words.
+      def literal_mutations(node, out, numeric:)
+        return if !numeric && !QUOTES.include?(node.opening_loc&.slice)
+
+        anchor, method = @anchor_for[node]
+        return if UNIVERSAL_EQUALITY.include?(method)
+
+        loc = node.location
+        add(out, :nil_inject, "call.argument-type-mismatch", loc.start_offset, loc.end_offset,
+            "nil", loc.start_line, "literal → nil  (#{snippet(loc)})", anchor, method)
+        swap = numeric ? '"rigor_mutant"' : "0"
+        add(out, :type_swap, "call.argument-type-mismatch", loc.start_offset, loc.end_offset,
+            swap, loc.start_line, "literal type swap  (#{snippet(loc)} → #{swap})", anchor, method)
+      end
+
+      def call_mutations(node, out)
+        rename_call(node, out)
+        extend_arity(node, out)
+      end
+
+      # Rename the *call site* (not the def) to a method that cannot exist, so a
+      # typed receiver trips call.undefined-method. We leave `def` signatures
+      # untouched on purpose: the prebuilt ProjectScan still carries the file's
+      # original declarations, so mutating only bodies/call-sites keeps it valid.
+      # Anchor is the explicit receiver (nil ⇒ implicit self ⇒ filtered out, as
+      # call.self-undefined-method ships `:off`).
+      def rename_call(node, out)
+        name = node.name.to_s
+        mloc = node.message_loc
+        return unless mloc && IDENT.match?(name)
+
+        add(out, :undefined_method, "call.undefined-method", mloc.start_offset, mloc.end_offset,
+            "#{name}__rigor_absent", mloc.start_line, "call ##{name} → missing method", node.receiver, name)
+      end
+
+      # Append a trailing argument inside explicit `(...)` parens to trip an
+      # arity diagnostic against a known fixed-arity signature.
+      def extend_arity(node, out)
+        open = node.opening_loc
+        close = node.closing_loc
+        return unless close && open&.slice == "("
+
+        args = node.arguments&.arguments
+        insertion = args && !args.empty? ? ", nil" : "nil"
+        add(out, :arity_extra, "call.wrong-arity", close.start_offset, close.start_offset,
+            insertion, node.location.start_line, "call ##{node.name} +1 arg", node.receiver, node.name.to_s)
+      end
+
+      def add(out, operator, rule, start, stop, replacement, line, label, anchor, method_name) # rubocop:disable Metrics/ParameterLists
+        return unless @operators.include?(operator)
+
+        out << Mutation.new(operator: operator, expected_rule: rule, start: start, stop: stop,
+                            replacement: replacement, line: line, label: label, anchor: anchor,
+                            method_name: method_name)
+      end
+
+      def snippet(loc)
+        text = loc.slice.gsub(/\s+/, " ")
+        text.length > 30 ? "#{text[0, 27]}..." : text
+      end
+    end
+  end
+end