rigortype 0.2.8 → 0.3.0

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

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "../../source/node_children"
+
+module Rigor
+  module Analysis
+    module CheckRules
+      # Walks a parse tree and collects every Hash-literal entry whose LITERAL key repeats an earlier
+      # literal key in the same literal. Ruby's runtime keeps the LAST entry silently (the interpreter
+      # itself only warns under `-w`), so the earlier value is dead — almost always a copy-paste or merge
+      # leftover. Modeled on PHPStan's `DuplicateKeysInLiteralArraysRule`.
+      #
+      # The collector is the read-side companion to the `flow.duplicate-hash-key` rule. The envelope is
+      # purely syntactic and deliberately narrow so it cannot fire on working code:
+      #
+      # - Only keys whose VALUE is pinned at parse time participate: symbols (including the `key:`
+      #   shorthand and the `:key =>` hashrocket spelling of the same symbol), plain non-interpolated
+      #   strings, integers, floats, and the `true` / `false` / `nil` literals. Any other key form —
+      #   interpolated strings/symbols, constants, method calls, locals — is never compared and never
+      #   fires.
+      # - Key spaces are tagged by literal kind, matching `Hash`'s `eql?`-based lookup: `:a` and `"a"`
+      #   are different keys, and `1` and `1.0` are different keys (`1.eql?(1.0)` is false), so Integer
+      #   and Float literals are never cross-compared.
+      # - A `**splat` element is itself never a key, and it does NOT rescue a literal duplicate around
+      #   it: in `{ a: 1, **h, a: 2 }` the second `a:` overwrites whatever the earlier entries (literal
+      #   or splatted) contributed, so the pair still collides and still fires.
+      # - Both `Prism::HashNode` (braced literals) and `Prism::KeywordHashNode` (bare keyword arguments,
+      #   `m(a: 1, a: 2)` — Prism parses these with only a `-w`-level warning, same as braced literals)
+      #   are scanned. Each literal is scanned independently; nested Hash literals are their own scope.
+      class DuplicateHashKeyCollector
+        # ADR-53 Track B — the node classes the shared {RuleWalk} dispatches to this collector. Prism node
+        # classes are leaves, so class-equality dispatch matches the legacy walk's `is_a?` gate. The
+        # collector needs no context gate: it is purely syntactic and fires wherever the full DFS reaches
+        # a Hash literal, loops and blocks included.
+        NODE_CLASSES = [Prism::HashNode, Prism::KeywordHashNode].freeze
+
+        # Returns `Array<{hash_node:, key_node:, first_key_node:, key_label:}>` — one entry per LATER
+        # occurrence of a repeated literal key (`key_node` is the repeat the diagnostic points at;
+        # `first_key_node` is the earliest occurrence its message references). Empty when the tree has no
+        # qualifying duplicates.
+        def initialize(scope_index)
+          @scope_index = scope_index
+          @results = []
+        end
+
+        # Legacy single-collector walk — kept as the oracle the ADR-53 Track B equivalence harness
+        # compares {RuleWalk} against.
+        def collect(root)
+          walk_for_hash_nodes(root)
+          @results.freeze
+        end
+
+        # {RuleWalk} entry point: the legacy walk's per-literal logic, invoked at every Hash literal under
+        # the shared traversal contract. The `context` is unused — this collector processes all literals.
+        def visit(hash_node, _context = nil)
+          collect_duplicate_keys(hash_node)
+        end
+
+        # The accumulated result, frozen the same way `#collect` returns it — used by {RuleWalk}-driven
+        # callers after the walk completes.
+        def results
+          @results.freeze
+        end
+
+        private
+
+        def walk_for_hash_nodes(node)
+          return unless node.is_a?(Prism::Node)
+
+          collect_duplicate_keys(node) if node.is_a?(Prism::HashNode) || node.is_a?(Prism::KeywordHashNode)
+          node.rigor_each_child { |child| walk_for_hash_nodes(child) }
+        end
+
+        def collect_duplicate_keys(hash_node)
+          seen = {}
+          hash_node.elements.each do |element|
+            # `**splat` elements (AssocSplatNode) contribute no literal key; they are skipped WITHOUT
+            # resetting `seen` — a splat between two identical literal keys does not rescue the collision.
+            next unless element.is_a?(Prism::AssocNode)
+
+            key = literal_key(element.key)
+            next if key.nil?
+
+            first = seen[key]
+            if first
+              @results << {
+                hash_node: hash_node,
+                key_node: element.key,
+                first_key_node: first,
+                key_label: key_label(element.key)
+              }
+            else
+              seen[key] = element.key
+            end
+          end
+        end
+
+        # Maps a key node to a comparable `[kind, value]` tag, or nil for any non-value-pinned key form.
+        # The kind tag keeps the literal spaces separate (`:a` ≠ `"a"`, `1` ≠ `1.0`); within a kind the
+        # parsed Ruby value is compared under Hash's own `eql?`/`hash` semantics, exactly reproducing the
+        # runtime collision.
+        def literal_key(key_node)
+          case key_node
+          when Prism::SymbolNode then [:symbol, key_node.unescaped]
+          when Prism::StringNode then [:string, key_node.unescaped]
+          when Prism::IntegerNode then [:integer, key_node.value]
+          when Prism::FloatNode then [:float, key_node.value]
+          when Prism::TrueNode then [:true_literal]
+          when Prism::FalseNode then [:false_literal]
+          when Prism::NilNode then [:nil_literal]
+          end
+        end
+
+        # Renders the key for the diagnostic message in its canonical Ruby spelling, so the `a:` shorthand
+        # and `:a =>` hashrocket occurrences of one symbol read as the same key.
+        def key_label(key_node)
+          case key_node
+          when Prism::SymbolNode then ":#{key_node.unescaped}"
+          when Prism::StringNode then key_node.unescaped.inspect
+          else key_node.slice
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "prism"
+
+module Rigor
+  module Analysis
+    module CheckRules
+      # ADR-67 WD6b — the shared "is this node rooted at an inferred parameter?" predicate.
+      #
+      # When the `parameter_inference:` gate seeds an undeclared parameter from its call-site union, that type
+      # is a *lower bound* (only the resolved call sites contribute; an unseen / dynamic caller could pass any
+      # wider value). A diagnostic decided against a lower bound is a false positive by construction — the same
+      # reasoning that keeps ADR-67 WD1 non-negotiable at the parameter boundary. So every negative in-body
+      # rule must decline when the value it reasons about is (transitively) an inferred parameter.
+      #
+      # `rooted?` walks a receiver / argument / condition-subject node down to its syntactic root and reports
+      # whether that root is a pristine inferred-parameter local. It is purely syntactic — a bounded AST walk
+      # over `.receiver` — not a value-flow provenance channel (the mark stays on the direct parameter local
+      # in the scope; this reads the chain root at the firing site). It covers:
+      #
+      # - the direct receiver / subject: `param.foo`, `case param`
+      # - an indexed element: `param[i] - x` (the `-` receiver is the `[]` call whose root is `param`)
+      # - any method chain: `param.foo.bar`, `param.foo(arg).baz`, `param.key?(:x)`
+      #
+      # Every value derived from an inferred parameter by dispatch is itself a lower bound, so firing against it
+      # is an FP by the same construction. No-op on a normal `check` run — `Scope#inferred_param?` is false
+      # unless the gate seeded the table.
+      module InferredParamGuard
+        module_function
+
+        # A defensive depth cap against a pathological receiver chain (the walk is otherwise linear in chain
+        # length, which is tiny in practice).
+        MAX_DEPTH = 64
+
+        def rooted?(node, scope, depth = 0)
+          return false if node.nil? || depth > MAX_DEPTH
+
+          case node
+          when Prism::LocalVariableReadNode then scope.inferred_param?(node.name)
+          when Prism::CallNode then rooted?(node.receiver, scope, depth + 1)
+          # Value-combining forms: the produced value is a union of the operands, so it is a lower bound when
+          # ANY operand is inferred-parameter-rooted (`cps[i] - x rescue -1`, `a && param.foo`, `param || b`).
+          # Declining on the whole expression is FP-safe by the same lower-bound argument.
+          when Prism::RescueModifierNode
+            rooted?(node.expression, scope, depth + 1) || rooted?(node.rescue_expression, scope, depth + 1)
+          when Prism::AndNode, Prism::OrNode
+            rooted?(node.left, scope, depth + 1) || rooted?(node.right, scope, depth + 1)
+          when Prism::ParenthesesNode then rooted?(last_statement(node.body), scope, depth + 1)
+          when Prism::StatementsNode then rooted?(node.body.last, scope, depth + 1)
+          else false
+          end
+        end
+
+        def last_statement(body)
+          body.is_a?(Prism::StatementsNode) ? body.body.last : body
+        end
+      end
+    end
+  end
+end

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

@@ -3,6 +3,7 @@
 require "prism"
 
 require_relative "../../source/constant_path"
+require_relative "../../source/node_children"
 
 module Rigor
   module Analysis
@@ -78,7 +79,7 @@ module Rigor
             return
           end
 
-          node.compact_child_nodes.each { |child| walk(child, qualified_prefix) }
+          node.rigor_each_child { |child| walk(child, qualified_prefix) }
         end
 
         def collect_def_writes(def_node, qualified_prefix)
@@ -95,7 +96,7 @@ module Rigor
           record_write(node, class_name) if node.is_a?(Prism::InstanceVariableWriteNode)
           return if BARRIER_NODES.any? { |klass| node.is_a?(klass) }
 
-          node.compact_child_nodes.each { |child| gather_writes(child, class_name) }
+          node.rigor_each_child { |child| gather_writes(child, class_name) }
         end
 
         def record_write(node, class_name)

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

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "../../source/node_children"
+
+module Rigor
+  module Analysis
+    module CheckRules
+      # Walks a parse tree and collects every explicit `ReturnNode` that sits lexically inside the `ensure`
+      # clause of a `begin` / `def` / `class` body. In Ruby, `return` inside `ensure` silently discards
+      # both the method's in-flight return value and any in-flight exception — the classic footgun RuboCop
+      # ships as `Lint/EnsureReturn` and PHPStan as `OverwrittenExitPointByFinallyRule`.
+      #
+      # The check is purely syntactic (no type engine involved) with a frame-aware envelope so it only
+      # flags a `return` that actually belongs to the frame whose `ensure` it sits in:
+      #
+      # - A `return` inside a nested `def`, a lambda (`-> {}` / `lambda {}`), or a `define_method` block
+      #   within the ensure body is skipped — that `return` exits the inner frame, not the one whose
+      #   in-flight exception the ensure guards.
+      # - A `return` inside a *plain* block (`each do ... return ... end`) within the ensure body DOES
+      #   belong to the enclosing method and fires.
+      # - A nested `begin ... ensure ... end` *inside* an ensure body is not descended into at its own
+      #   `ensure` clause — that inner `EnsureNode` is visited separately (every `BeginNode` is), so each
+      #   offending `return` is collected exactly once.
+      class ReturnInEnsureCollector
+        # ADR-53 Track B — the node classes the shared {RuleWalk} dispatches to this collector. Prism
+        # represents every construct that can carry an `ensure` clause — `begin ... end`, a `def` body with
+        # `rescue` / `ensure`, a class / module body with them — as a `BeginNode`, so one dispatch class
+        # covers all the syntactic hosts. No context gates: the footgun is frame-relative, not
+        # position-relative, so a `begin/ensure` inside a loop, block, or lambda is checked the same way.
+        NODE_CLASSES = [Prism::BeginNode].freeze
+
+        # Receiver-less calls whose attached block opens a new return frame: a `return` inside their block
+        # exits the lambda / defined method, not the method whose `ensure` we are scanning. `proc` is
+        # deliberately absent — `return` inside a `Proc` block returns from the enclosing method, so it
+        # stays in scope for the rule.
+        FRAME_BARRIER_CALL_NAMES = %i[lambda define_method].freeze
+
+        def initialize(scope_index)
+          @scope_index = scope_index
+          @results = []
+        end
+
+        # Legacy single-collector walk — the oracle the ADR-53 Track B equivalence harness compares
+        # {RuleWalk} against.
+        def collect(root)
+          walk_for_begin_nodes(root)
+          @results.freeze
+        end
+
+        # {RuleWalk} entry point: invoked at every `BeginNode` the shared traversal reaches. The `context`
+        # is unused — this collector checks every ensure clause.
+        def visit(begin_node, _context = nil)
+          collect_ensure_returns(begin_node)
+        end
+
+        # Returns `Array<{return_node:}>` — one entry per offending `return`, frozen the same way
+        # `#collect` returns it.
+        def results
+          @results.freeze
+        end
+
+        private
+
+        def walk_for_begin_nodes(node)
+          return unless node.is_a?(Prism::Node)
+
+          collect_ensure_returns(node) if node.is_a?(Prism::BeginNode)
+          node.rigor_each_child { |child| walk_for_begin_nodes(child) }
+        end
+
+        def collect_ensure_returns(begin_node)
+          ensure_clause = begin_node.ensure_clause
+          return if ensure_clause.nil?
+
+          gather_returns(ensure_clause.statements)
+        end
+
+        def gather_returns(node)
+          return unless node.is_a?(Prism::Node)
+
+          case node
+          when Prism::ReturnNode
+            @results << { return_node: node }
+          when Prism::DefNode, Prism::LambdaNode, Prism::EnsureNode
+            # Def / lambda open a new return frame — a `return` below them exits the nested frame, not the
+            # one whose ensure we are scanning. A nested `begin/ensure`'s own EnsureNode is skipped for a
+            # different reason: its BeginNode is visited separately, which collects those returns once —
+            # descending here would double-collect them.
+            return
+          when Prism::CallNode
+            return gather_returns_around_barrier_block(node) if frame_barrier_call?(node)
+          end
+
+          node.rigor_each_child { |child| gather_returns(child) }
+        end
+
+        # `lambda { ... }` / `define_method(:x) { ... }`: the receiver and arguments stay in the current
+        # frame (and may themselves contain an offending `return`), only the attached block opens a new
+        # one — descend into everything except the block.
+        def gather_returns_around_barrier_block(call_node)
+          barrier_block = call_node.block
+          call_node.rigor_each_child do |child|
+            gather_returns(child) unless child.equal?(barrier_block)
+          end
+        end
+
+        def frame_barrier_call?(call_node)
+          call_node.receiver.nil? &&
+            FRAME_BARRIER_CALL_NAMES.include?(call_node.name) &&
+            call_node.block.is_a?(Prism::BlockNode)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module Rigor
+  module Analysis
+    module CheckRules
+      # 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.
+      #
+      # 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
+      # — can require it WITHOUT loading the inference engine. The boot-slimming hit path stays engine-free
+      # even when it formats JSON.
+      RULE_UNDEFINED_METHOD = "call.undefined-method"
+      RULE_SELF_UNDEFINED_METHOD = "call.self-undefined-method"
+      RULE_UNRESOLVED_TOPLEVEL = "call.unresolved-toplevel"
+      RULE_WRONG_ARITY = "call.wrong-arity"
+      RULE_ARGUMENT_TYPE = "call.argument-type-mismatch"
+      RULE_NIL_RECEIVER = "call.possible-nil-receiver"
+      RULE_RAISE_NON_EXCEPTION = "call.raise-non-exception"
+      RULE_DUMP_TYPE = "dump.type"
+      RULE_ASSERT_TYPE = "assert.type-mismatch"
+      RULE_ALWAYS_RAISES = "flow.always-raises"
+      RULE_UNREACHABLE_BRANCH = "flow.unreachable-branch"
+      RULE_RETURN_TYPE = "def.return-type-mismatch"
+      RULE_VISIBILITY_MISMATCH = "def.method-visibility-mismatch"
+      RULE_OVERRIDE_VISIBILITY_REDUCED = "def.override-visibility-reduced"
+      RULE_OVERRIDE_RETURN_WIDENED = "def.override-return-widened"
+      RULE_OVERRIDE_PARAM_NARROWED = "def.override-param-narrowed"
+      RULE_IVAR_WRITE_MISMATCH = "def.ivar-write-mismatch"
+      RULE_DEAD_ASSIGNMENT = "flow.dead-assignment"
+      RULE_ALWAYS_TRUTHY_CONDITION = "flow.always-truthy-condition"
+      RULE_UNREACHABLE_CLAUSE = "flow.unreachable-clause"
+      RULE_DUPLICATE_HASH_KEY = "flow.duplicate-hash-key"
+      RULE_RETURN_IN_ENSURE = "flow.return-in-ensure"
+      RULE_SHADOWED_RESCUE_CLAUSE = "flow.shadowed-rescue-clause"
+      RULE_SUPPRESSION_UNKNOWN_RULE = "suppression.unknown-rule"
+      RULE_SUPPRESSION_EMPTY = "suppression.empty"
+      RULE_SUPPRESSION_UNKNOWN_MARKER = "suppression.unknown-marker"
+      # ADR-100 — the first `static.value-use.*` id: a value recovered from an author-declared `-> void`
+      # return, used in value context. Authored `:warning`, resolved `:off` by every profile and promoted to
+      # `:warning` only by the `use-of-void-value` bleeding-edge feature.
+      RULE_VALUE_USE_VOID = "static.value-use.void"
+
+      ALL_RULES = [
+        RULE_UNDEFINED_METHOD,
+        RULE_SELF_UNDEFINED_METHOD,
+        RULE_UNRESOLVED_TOPLEVEL,
+        RULE_WRONG_ARITY,
+        RULE_ARGUMENT_TYPE,
+        RULE_NIL_RECEIVER,
+        RULE_RAISE_NON_EXCEPTION,
+        RULE_DUMP_TYPE,
+        RULE_ASSERT_TYPE,
+        RULE_ALWAYS_RAISES,
+        RULE_UNREACHABLE_BRANCH,
+        RULE_DEAD_ASSIGNMENT,
+        RULE_ALWAYS_TRUTHY_CONDITION,
+        RULE_UNREACHABLE_CLAUSE,
+        RULE_DUPLICATE_HASH_KEY,
+        RULE_RETURN_IN_ENSURE,
+        RULE_SHADOWED_RESCUE_CLAUSE,
+        RULE_RETURN_TYPE,
+        RULE_VISIBILITY_MISMATCH,
+        RULE_OVERRIDE_VISIBILITY_REDUCED,
+        RULE_OVERRIDE_RETURN_WIDENED,
+        RULE_OVERRIDE_PARAM_NARROWED,
+        RULE_IVAR_WRITE_MISMATCH,
+        RULE_SUPPRESSION_UNKNOWN_RULE,
+        RULE_SUPPRESSION_EMPTY,
+        RULE_SUPPRESSION_UNKNOWN_MARKER,
+        RULE_VALUE_USE_VOID
+      ].freeze
+
+      # Backward-compat alias table (ADR-8 § "Backward compatibility"). Existing user code with
+      # `# rigor:disable undefined-method` / `disable: [undefined-method]` keeps working — the legacy
+      # unprefixed identifiers map to their canonical `family.rule-name` form here. Removing the aliases is a
+      # future ADR once user code has migrated; until then, both spellings resolve identically.
+      LEGACY_RULE_ALIASES = {
+        "undefined-method" => RULE_UNDEFINED_METHOD,
+        "self-undefined-method" => RULE_SELF_UNDEFINED_METHOD,
+        "wrong-arity" => RULE_WRONG_ARITY,
+        "argument-type-mismatch" => RULE_ARGUMENT_TYPE,
+        "possible-nil-receiver" => RULE_NIL_RECEIVER,
+        "raise-non-exception" => RULE_RAISE_NON_EXCEPTION,
+        "dump-type" => RULE_DUMP_TYPE,
+        "assert-type" => RULE_ASSERT_TYPE,
+        "always-raises" => RULE_ALWAYS_RAISES,
+        "unreachable-branch" => RULE_UNREACHABLE_BRANCH,
+        "method-visibility-mismatch" => RULE_VISIBILITY_MISMATCH,
+        "ivar-write-mismatch" => RULE_IVAR_WRITE_MISMATCH,
+        "dead-assignment" => RULE_DEAD_ASSIGNMENT,
+        "always-truthy-condition" => RULE_ALWAYS_TRUTHY_CONDITION,
+        "unreachable-clause" => RULE_UNREACHABLE_CLAUSE,
+        "duplicate-hash-key" => RULE_DUPLICATE_HASH_KEY,
+        "return-in-ensure" => RULE_RETURN_IN_ENSURE,
+        "shadowed-rescue-clause" => RULE_SHADOWED_RESCUE_CLAUSE
+      }.freeze
+
+      # 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].freeze
+
+      # Families of diagnostics the engine emits OUTSIDE the CheckRules catalogue (aggregator-level and
+      # reporter-level diagnostics such as `rbs_extended.unsatisfied-conformance`,
+      # `dynamic.dependency-source.*`, `rbs.coverage.*`, `pre-eval.parse-error`), plus the `plugin.` prefix
+      # reserved for plugin-produced identifiers. `suppression.unknown-rule` treats a dotted token whose
+      # first segment appears here as KNOWN and stays silent: these ids are legitimate suppression /
+      # `severity_overrides:` vocabulary the light rule-id table cannot enumerate (plugins load dynamically;
+      # aggregator ids live in the engine-heavy runner), so under-warning is the FP-safe direction.
+      NON_CHECK_DIAGNOSTIC_FAMILIES = %w[rbs_extended dynamic rbs pre-eval plugin].freeze
+
+      # Bare (dot-less) diagnostic ids the engine emits outside the catalogue (see the `rule:` literals in
+      # `Analysis::Runner` / `Runner::DiagnosticAggregator`). A token equal to one of these is treated as
+      # known by `suppression.unknown-rule` even though it carries no family prefix; extend the list when
+      # the runner grows a new bare id.
+      NON_CHECK_DIAGNOSTIC_IDS = %w[
+        configuration-error load-error pool-degraded runtime-error source-rbs-synthesis-failed
+      ].freeze
+    end
+  end
+end

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

@@ -3,6 +3,7 @@
 require "prism"
 
 require_relative "../../source/constant_path"
+require_relative "../../source/node_children"
 
 module Rigor
   module Analysis
@@ -145,7 +146,7 @@ module Rigor
 
             dispatch(node, hooks, context)
             child_context = descend(node, context)
-            node.compact_child_nodes.each { |child| walk(child, hooks, child_context) }
+            node.rigor_each_child { |child| walk(child, hooks, child_context) }
           end
 
           def dispatch(node, hooks, context)

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

@@ -3,6 +3,7 @@
 require "prism"
 
 require_relative "../../source/constant_path"
+require_relative "../../source/node_children"
 
 module Rigor
   module Analysis
@@ -52,7 +53,7 @@ module Rigor
             names << child_prefix.join("::") if name && class_surface_open?(node)
             walk(node.body, child_prefix, names) if node.body
           else
-            node.compact_child_nodes.each { |child| walk(child, prefix, names) }
+            node.rigor_each_child { |child| walk(child, prefix, names) }
           end
         end