rigortype 0.3.9 → 0.4.1

data/lib/rigor/analysis/check_rules/declaration_sourced_guard.rb

@@ -32,9 +32,19 @@ module Rigor
       # `docs/internal-spec/inference-engine.md` § "Declaration-sourced provenance mark (ADR-58)"; keep this
       # comment subordinate to it.
       #
-      # So `marked?` matches exactly the two node shapes the scope actually models and invents no propagation
-      # of its own; anything flow-live keeps firing.
+      # So `marked?` matches exactly the node shapes the scope actually models and invents no propagation of its
+      # own; anything flow-live keeps firing.
+      #
+      # Issue #1362 adds a third carrier, a global still on its program-global seed, which joins the non-nil part of
+      # the declared type of a global Ruby's own signatures declare with the file's writes (ADR-117 Decision point
+      # 2: never warn that a value might deviate from the idiom). Its declared members are the declaration-sourced
+      # part. The consumers judge such a value by the file's writes ({.written_type}, {.withholds_nil?}), and a
+      # value that mixes it with something else without the declared members the file never writes
+      # ({.declared_only_rejection?}), so a report the writes alone earn still fires.
       module DeclarationSourcedGuard
+        NO_GLOBALS = [].freeze
+        private_constant :NO_GLOBALS
+
         module_function
 
         # True when `node` is a direct read of a binding whose optionality is purely declaration-sourced. Any
@@ -44,9 +54,164 @@ module Rigor
           case node
           when Prism::InstanceVariableReadNode then scope.declaration_sourced?(:ivar, node.name)
           when Prism::LocalVariableReadNode then scope.declaration_sourced?(:local, node.name)
+          when Prism::GlobalVariableReadNode then scope.declaration_sourced?(:global, node.name)
           else false
           end
         end
+
+        # The globals whose declared seeds `node` still reads, empty for none: a read of a marked global, or of a
+        # local copied from one or more (`sep = $/`, `Scope#declaration_sourced_global_copies`), bare or in
+        # parentheses (`($stdout)`).
+        def global_sources(node, scope)
+          node = unparenthesised(node)
+          case node
+          when Prism::GlobalVariableReadNode
+            scope.declaration_sourced?(:global, node.name) ? [node.name] : NO_GLOBALS
+          when Prism::LocalVariableReadNode
+            scope.declaration_sourced_global_copies(node.name)
+          else NO_GLOBALS
+          end
+        end
+
+        # The globals a local written from `value` copies the declared seeds of, empty for none: a read of a marked
+        # global, bare or in parentheses (`sep = ($/)`), or a bare read of a local that copies some (`s = sep`).
+        # Unlike an ivar copy's, this mark follows bare local-to-local copies; a method result (`$/.dup`) or a
+        # container element (`[$/].each { |s| … }`) carries none, as ADR-58's one-hop boundary has it.
+        def copied_globals(value, scope)
+          return scope.declaration_sourced_global_copies(value.name) if value.is_a?(Prism::LocalVariableReadNode)
+
+          read = unparenthesised(value)
+          return NO_GLOBALS unless read.is_a?(Prism::GlobalVariableReadNode) &&
+                                   scope.declaration_sourced?(:global, read.name)
+
+          [read.name]
+        end
+
+        # `node` with its enclosing parentheses taken off while they hold a single expression.
+        def unparenthesised(node)
+          while node.is_a?(Prism::ParenthesesNode)
+            body = node.body
+            break unless body.is_a?(Prism::StatementsNode) && body.body.size == 1
+
+            node = body.body.first
+          end
+          node
+        end
+
+        # The union of the file's own writes to the globals `node` reads the seeds of ({.global_sources}), or nil.
+        def written_type(node, scope)
+          sources = global_sources(node, scope)
+          return nil if sources.empty?
+
+          written = sources.map { |source| scope.program_globals[source] }
+          written.include?(nil) ? nil : Type::Combinator.union(*written)
+        end
+
+        # True when a `nil` in `node`'s type is not diagnostic fuel: for a global's seed or its copy, when the file
+        # never writes `nil` to the global, so the declaration alone contributes it; otherwise when `node` carries
+        # the ADR-58 mark.
+        def withholds_nil?(node, scope)
+          written = written_type(node, scope)
+          return marked?(node, scope) if written.nil?
+
+          !nil_bearing?(written)
+        end
+
+        # Issue #1362 — true when every member of `type` that `expected` rejects is a declared member of a builtin
+        # global this file writes and joins ({#declared_only_members}), so the rejection rests on the join alone. The
+        # argument and return gates read it for a value that mixes such a global with something else
+        # (`c ? $stdout : StringIO.new`), which the ADR-58 mark does not follow. It is a type-level reading: it also
+        # withholds a rejection of such a member that comes from elsewhere in the file (`STDOUT` passed where a
+        # `StringIO` is required, in a file that writes `$stdout`).
+        #
+        # Otherwise the value with those members taken out of every union inside it ({#without_declared_only}) is
+        # handed to the block, which answers whether the caller's rule accepts it: the value as it was before the
+        # join, one level into a container it builds as well (`[$stdout]` or `{ io: $stdout }` passed where an
+        # `Array[StringIO]` is required), and with a `nil` the file writes judged as the rule judges a `nil`.
+        def declared_only_rejection?(type, expected, scope)
+          declared_only = declared_only_members(scope)
+          return false if declared_only.empty?
+
+          members = type.is_a?(Type::Union) ? type.members : [type]
+          rejected = members.select { |member| Inference::Acceptance.accepts(expected, member, mode: :gradual).no? }
+          return false if rejected.empty?
+          return true if rejected.all? { |member| declared_only.include?(member) }
+
+          stripped = without_declared_only(type, declared_only)
+          !stripped.equal?(type) && yield(stripped)
+        end
+
+        # `type` with each member of `declared_only` taken out of every union in it, through tuples, hash shapes and
+        # generic arguments; a union with nothing else left keeps its members. Answers `type` itself when nothing
+        # was taken out.
+        def without_declared_only(type, declared_only)
+          case type
+          when Type::Union then union_without_declared_only(type, declared_only)
+          when Type::Tuple
+            elements = type.elements.map { |element| without_declared_only(element, declared_only) }
+            elements == type.elements ? type : Type::Combinator.tuple_of(*elements)
+          when Type::HashShape
+            pairs = type.pairs.transform_values { |value| without_declared_only(value, declared_only) }
+            pairs == type.pairs ? type : rebuild_hash_shape(type, pairs)
+          when Type::Nominal
+            args = type.type_args.map { |arg| without_declared_only(arg, declared_only) }
+            args == type.type_args ? type : Type::Combinator.nominal_of(type.class_name, type_args: args)
+          else type
+          end
+        end
+
+        def union_without_declared_only(union, declared_only)
+          kept = union.members.reject { |member| declared_only.include?(member) }
+          kept = union.members if kept.empty?
+          rebuilt = kept.map { |member| without_declared_only(member, declared_only) }
+          rebuilt == union.members ? union : Type::Combinator.union(*rebuilt)
+        end
+
+        def rebuild_hash_shape(shape, pairs)
+          Type::Combinator.hash_shape_of(
+            pairs, required_keys: shape.required_keys, optional_keys: shape.optional_keys,
+                   read_only_keys: shape.read_only_keys, extra_keys: shape.extra_keys
+          )
+        end
+
+        # For each builtin global this file writes and joins, the non-nil members of its declared type that the file's
+        # writes to that global do not hold (`IO` after `$stdout = StringIO.new`, nothing after `$stderr = STDERR`),
+        # gathered over the globals. A declared literal also counts in its class form, which a method called on the
+        # joined union returns: `$VERBOSE.itself` reads `FalseClass | TrueClass` after `$VERBOSE = true`.
+        def declared_only_members(scope)
+          seeds = scope.discovery.program_global_seeds
+          return NO_GLOBALS if seeds.empty?
+
+          seeds.keys.flat_map do |name|
+            written = type_members(scope.program_globals[name])
+            type_members(scope.environment.global_for_name(name, builtin: true))
+              .reject { |member| nil_bearing?(member) }
+              .flat_map { |member| [member, *class_form(member)] }
+              .reject { |member| written.include?(member) }
+          end.uniq
+        end
+
+        def class_form(member)
+          return NO_GLOBALS unless member.is_a?(Type::Constant)
+
+          [Type::Combinator.nominal_of(member.value.class.name)]
+        end
+
+        def type_members(type)
+          return NO_GLOBALS if type.nil?
+
+          type.is_a?(Type::Union) ? type.members : [type]
+        end
+
+        def nil_bearing?(type)
+          members = type.is_a?(Type::Union) ? type.members : [type]
+          members.any? do |member|
+            (member.is_a?(Type::Constant) && member.value.nil?) ||
+              (member.is_a?(Type::Nominal) && member.class_name == "NilClass")
+          end
+        end
+        private_class_method :nil_bearing?, :unparenthesised, :declared_only_members, :type_members, :class_form,
+                             :without_declared_only, :union_without_declared_only, :rebuild_hash_shape
       end
     end
   end

data/lib/rigor/analysis/check_rules/lexical_method_sites.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "../../inference/scope_indexer"
+require_relative "../../source/constant_path"
+require_relative "../../source/node_children"
+
+module Rigor
+  module Analysis
+    module CheckRules
+      # Issue #1120 — the two ways one file makes a method callable at some sites and not at others, which
+      # `call.undefined-method` has to ask the file's syntax about because no project-wide table can answer:
+      #
+      # - **Refinements.** `using M` activates M's refinements from the end of the call to the end of the body
+      #   that holds it — the file's top level or a `class` / `module` body, including everything nested in it —
+      #   and nowhere else, not even in another file. A `refine X do … end` block is active inside itself. What
+      #   each module refines is the project-wide `Scope#discovered_refinements`; this answers whether any of
+      #   those modules is in effect at a call site. A `using` whose argument is not a constant
+      #   (`using Module.new { refine … }`) names no module, so every refinement counts as in effect throughout
+      #   its file. A `using` inside a `def` raises in Ruby and activates nothing.
+      # - **Singleton defs on locals.** `def o.m` defines `m` on the one object `o` holds. The local's type
+      #   is not changed; `o.m` is simply not reported within the scope the `def` is written in (the
+      #   enclosing `def`, `class` / `module` body, or file — a block shares its enclosing scope's locals).
+      #
+      # Built lazily: the walk runs the first time a would-fire call asks, so a file with no such call pays
+      # one small object and nothing else.
+      class LexicalMethodSites
+        def initialize(root)
+          @root = root
+          @built = false
+        end
+
+        # Is a refinement from one of `modules` (refining-module names) in effect at `call_node`?
+        def refinement_active?(call_node, modules)
+          build
+          return true if @unresolved_using
+
+          offset = call_node.location.start_offset
+          return true if @refine_blocks.any? { |start, stop| offset >= start && offset < stop }
+
+          @usings.any? do |start, stop, candidates|
+            offset >= start && offset < stop && candidates.any? { |name| modules.include?(name) }
+          end
+        end
+
+        # Issue #1367 — is any refinement in effect at `node`: a `using` of any module, a `using` of a non-constant, or
+        # the inside of a `refine` block? The `global.*` stream check asks it where it cannot name the refining
+        # module (a `define_method` or `alias_method` inside `refine` records none).
+        def using_in_effect?(node)
+          build
+          return true if @unresolved_using
+
+          offset = node.location.start_offset
+          @refine_blocks.any? { |start, stop| offset >= start && offset < stop } ||
+            @usings.any? { |start, stop, _candidates| offset >= start && offset < stop }
+        end
+
+        # Is `def_node` one of the defs a `refine X do … end` body defines on X? Such a def redefines X's method by
+        # design, so X's declared signature for the name is not its contract (issue #1120, maintainer ruling a′).
+        def refinement_def?(def_node)
+          build
+          @refinement_defs.include?(def_node.location.start_offset)
+        end
+
+        # Does a `def <local>.<name>` for this call's local receiver and method name sit in the scope the call
+        # is in?
+        def singleton_local_def?(call_node)
+          receiver = call_node.receiver
+          return false unless receiver.is_a?(Prism::LocalVariableReadNode)
+
+          build
+          offset = call_node.location.start_offset
+          @singleton_defs.any? do |local, method_name, start, stop|
+            local == receiver.name && method_name == call_node.name && offset >= start && offset < stop &&
+              !nested_scope_holds?(offset, start, stop)
+          end
+        end
+
+        private
+
+        # Is `offset` inside a local scope nested in the one `[start, stop)` spans? A `def` in the file's top level
+        # does not see the top level's `o`.
+        def nested_scope_holds?(offset, start, stop)
+          @scopes.any? do |inner_start, inner_stop|
+            (inner_start > start || inner_stop < stop) && inner_start >= start && inner_stop <= stop &&
+              offset >= inner_start && offset < inner_stop
+          end
+        end
+
+        def build
+          return if @built
+
+          @built = true
+          @usings = []
+          @refine_blocks = []
+          @singleton_defs = []
+          @scopes = []
+          @refinement_defs = Set.new
+          @unresolved_using = false
+          return if @root.nil?
+
+          location = @root.location
+          span = [location.start_offset, location.end_offset]
+          walk(@root, [], span, span, false)
+        end
+
+        # `body` is the `[start, end]` of the body a `using` here stays in effect to the end of; `locals` is the
+        # span of the scope a local written here belongs to.
+        def walk(node, prefix, body, locals, in_def)
+          case node
+          when Prism::ClassNode, Prism::ModuleNode
+            span = scope_span(node)
+            inner = Source::ConstantPath.declaration_prefix(prefix, node.constant_path) || prefix
+            return walk_children(node.body, inner, span, span, false)
+          when Prism::SingletonClassNode
+            walk(node.expression, prefix, body, locals, in_def)
+            span = scope_span(node)
+            return walk_children(node.body, prefix, span, span, false)
+          when Prism::DefNode
+            record_singleton_def(node, locals)
+            return walk_children(node.body, prefix, body, scope_span(node), true)
+          when Prism::CallNode
+            record_call(node, prefix, body, in_def)
+          end
+
+          walk_children(node, prefix, body, locals, in_def)
+        end
+
+        def walk_children(node, prefix, body, locals, in_def)
+          return if node.nil?
+
+          node.rigor_each_child { |child| walk(child, prefix, body, locals, in_def) }
+        end
+
+        def record_singleton_def(node, locals)
+          receiver = node.receiver
+          return unless receiver.is_a?(Prism::LocalVariableReadNode)
+
+          @singleton_defs << [receiver.name, node.name, *locals]
+        end
+
+        def record_call(node, prefix, body, in_def)
+          if Inference::ScopeIndexer.refine_target(node)
+            @refine_blocks << span_of(node.block)
+            record_refinement_defs(node.block.body)
+          elsif using_call?(node) && !in_def
+            record_using(node, prefix, body)
+          end
+        end
+
+        def record_refinement_defs(body)
+          return if body.nil?
+
+          Inference::ScopeIndexer.each_refinement_def(body) do |def_node|
+            @refinement_defs << def_node.location.start_offset
+          end
+        end
+
+        def using_call?(node)
+          node.name == :using && (node.receiver.nil? || node.receiver.is_a?(Prism::SelfNode)) &&
+            node.arguments&.arguments&.size == 1
+        end
+
+        def record_using(node, prefix, body)
+          argument = node.arguments.arguments.first
+          if argument.is_a?(Prism::ConstantReadNode) || argument.is_a?(Prism::ConstantPathNode)
+            candidates = Inference::ScopeIndexer.constant_receiver_candidates(argument, prefix)
+            @usings << [node.location.end_offset, body.last, candidates]
+          else
+            @unresolved_using = true
+          end
+        end
+
+        # The span of a node that opens a local scope, recorded for {#nested_scope_holds?}.
+        def scope_span(node)
+          span = span_of(node)
+          @scopes << span
+          span
+        end
+
+        def span_of(node)
+          location = node.location
+          [location.start_offset, location.end_offset]
+        end
+      end
+    end
+  end
+end

data/lib/rigor/analysis/check_rules/main_pass_collector.rb

@@ -19,10 +19,12 @@ module Rigor
       # accumulated {Diagnostic}s, in the same emission order the inline `NodeWalker.each` produced them (the
       # shared walk is the same visit-before-descend DFS over `compact_child_nodes`).
       class MainPassCollector
-        # The node classes the former inline pass branched on. A plain `Prism::IfNode` covers ternaries and
-        # postfix `if` too (the legacy `when Prism::IfNode, Prism::UnlessNode` arm did the same).
+        # The node classes the main pass branches on. A plain `Prism::IfNode` covers ternaries and postfix `if`
+        # too (the legacy `when Prism::IfNode, Prism::UnlessNode` arm did the same). The three global-write
+        # classes carry issue #1367's `global.*` rules.
         NODE_CLASSES = [
-          Prism::CallNode, Prism::DefNode, Prism::IfNode, Prism::UnlessNode
+          Prism::CallNode, Prism::DefNode, Prism::IfNode, Prism::UnlessNode,
+          Prism::GlobalVariableWriteNode, Prism::GlobalVariableOperatorWriteNode, Prism::MultiWriteNode
         ].freeze
 
         # @param node_diagnostics — maps a `Prism::Node` to the array of diagnostics the main pass emits

data/lib/rigor/analysis/check_rules/rule_ids.rb

@@ -6,9 +6,9 @@ module Rigor
       # Canonical identifiers for each rule. Per ADR-8 § "Diagnostic ID family hierarchy", rule names are
       # `family.rule-name` two-segment strings; the families group diagnostics by where they originate
       # (`call.*` for call-site rules, `flow.*` for flow-analysis proofs, `assert.*` for runtime-assertion
-      # rules, `dump.*` for debug helpers, `def.*` for method-definition rules). Used by the configuration
-      # `disable:` list and the in-source `# rigor:disable <rule>` suppression comment system; new rules MUST
-      # register here so user configuration can refer to them.
+      # rules, `dump.*` for debug helpers, `def.*` for method-definition rules, `global.*` for writes to special
+      # globals). Used by the configuration `disable:` list and the in-source `# rigor:disable <rule>`
+      # suppression comment system; new rules MUST register here so user configuration can refer to them.
       #
       # ADR-87 WD4 — this pure-data constant table is split out of the (engine-heavy) `check_rules.rb` so
       # {Analysis::RuleCatalog} — which the CLI's JSON `evidence_tier` / `documentation_url` enrichment reads
@@ -66,6 +66,18 @@ module Rigor
       # annotation must never turn collection on by itself (that would be a project-wide cost cliff
       # nobody asked for), and it must equally never be silently inert.
       RULE_EFFECT_ANNOTATIONS_UNCHECKED = "effect.annotations-unchecked"
+      # ADR-112 WD5 / #1075 — two statements of one member's contract that contradict: a `sig/` declaration
+      # against an inline `@rbs` / `#:` one (and, once #1073 reads it, `@rbs` / `#:` against `@extrbs`), or a
+      # `rigor:v1:` refinement outside the member's own declared type. `rbs.` because the finding is about
+      # the RBS the environment is built from, whichever file spelled it; not `rbs_extended.`, whose rows
+      # are payload validity, since most contradictions involve no `RBS::Extended` annotation at all.
+      RULE_CONTRADICTING_SIGNATURE = "rbs.contradicting-signature"
+      # Issue #1367 (ADR-117 WD2) — the `global.*` family: a write to a special global that its setter rejects, so
+      # the write raises on every run. Two ids so a project can tune the type check without hiding read-only
+      # writes; the `write` wording follows `def.ivar-write-mismatch`. The envelope is the interpreter's setter
+      # (`SpecialGlobalSetters`), not the global's RBS declaration.
+      RULE_GLOBAL_WRITE_TYPE_MISMATCH = "global.write-type-mismatch"
+      RULE_GLOBAL_READONLY_WRITE = "global.readonly-write"
 
       ALL_RULES = [
         RULE_UNDEFINED_METHOD,
@@ -91,6 +103,8 @@ module Rigor
         RULE_OVERRIDE_RETURN_WIDENED,
         RULE_OVERRIDE_PARAM_NARROWED,
         RULE_IVAR_WRITE_MISMATCH,
+        RULE_GLOBAL_WRITE_TYPE_MISMATCH,
+        RULE_GLOBAL_READONLY_WRITE,
         RULE_SUPPRESSION_UNKNOWN_RULE,
         RULE_SUPPRESSION_EMPTY,
         RULE_SUPPRESSION_UNKNOWN_MARKER,
@@ -98,7 +112,8 @@ module Rigor
         RULE_EFFECT_ENVELOPE_EXCEEDED,
         RULE_EFFECT_LISKOV_WIDENED,
         RULE_EFFECT_UNKNOWN_LABEL,
-        RULE_EFFECT_ANNOTATIONS_UNCHECKED
+        RULE_EFFECT_ANNOTATIONS_UNCHECKED,
+        RULE_CONTRADICTING_SIGNATURE
       ].freeze
 
       # Backward-compat alias table (ADR-8 § "Backward compatibility"). Existing user code with
@@ -128,7 +143,7 @@ module Rigor
 
       # Family wildcard — a `<family>` token in a suppression comment or `disable:` list disables every rule
       # whose canonical id starts with `<family>.`. Per ADR-8 § "1".
-      RULE_FAMILIES = %w[call flow assert dump def suppression static effect].freeze
+      RULE_FAMILIES = %w[call flow assert dump def global suppression static effect].freeze
 
       # Families of diagnostics the engine emits OUTSIDE the CheckRules catalogue (aggregator-level and
       # reporter-level diagnostics such as `rbs_extended.unsatisfied-conformance`,

data/lib/rigor/analysis/check_rules/rule_walk.rb

@@ -50,6 +50,7 @@ module Rigor
           Struct: %i[new],
           Data: %i[define]
         }.freeze
+        Ractor.make_shareable(DETACHED_CLASS_FACTORIES)
         private_constant :DETACHED_CLASS_FACTORIES
 
         EMPTY_METHODS = [].freeze
@@ -108,7 +109,7 @@ module Rigor
             end
           end
 
-          # The context the children of `node` descend under. Mirrors {RuleWalk.descend}.
+          # Mirrors {RuleWalk.descend}.
           def descend(node, context)
             RuleWalk.descend(node, context)
           end