rigortype 0.2.9 → 0.3.0

data/docs/manual/11-ci.md

@@ -246,6 +246,57 @@ updates:
 extra files — but Dependabot does not see a version inside a `run:`
 step, so updates to the pin are manual.
 
+## Persisting the analysis cache across runs
+
+By default each CI run starts cold and re-analyses everything. The
+templates leave it that way on purpose — cold runs are simple,
+deterministic, and fast enough for most projects. When the Rigor
+job's runtime starts to matter (a large codebase, many plugins),
+persist [the analysis cache](12-caching.md) between runs.
+
+**Restore and save the cache directory** with your CI's cache
+facility, keyed on anything that changes the analysis wholesale
+(the Rigor version / lockfile). That is the whole setup: Rigor
+detects CI and switches its cache freshness check from stat
+metadata (which a fresh checkout regenerates, and which would
+otherwise force parts of the restored cache to recompute every
+run) to content hashes, which are identical across checkouts.
+Details: [How a file is checked for changes](12-caching.md#how-a-file-is-checked-for-changes).
+
+GitHub Actions:
+
+```yaml
+      - uses: actions/cache@v4
+        with:
+          path: .rigor/cache
+          key: rigor-cache-${{ runner.os }}-${{ hashFiles('.github/rigor/Gemfile.lock') }}-${{ github.sha }}
+          restore-keys: rigor-cache-${{ runner.os }}-${{ hashFiles('.github/rigor/Gemfile.lock') }}-
+      - run: bundle exec rigor check
+```
+
+GitLab CI:
+
+```yaml
+rigor:
+  cache:
+    key: rigor-cache
+    paths:
+      - .rigor/cache
+```
+
+Two refinements:
+
+- A **self-hosted runner that reuses its workspace** keeps stable
+  stat metadata, so the faster stat check works there — opt back
+  into it with `cache.validation: stat`.
+- On Rigor versions before the `auto` default, set
+  `RIGOR_STRICT_VALIDATION: "1"` on the job explicitly.
+
+The cache is content-keyed and self-invalidating — a stale or
+corrupt restore degrades to a recompute, never a wrong result. If
+you would rather guarantee every run is independent, pass
+`--no-cache` instead and skip this section.
+
 ## Container image
 
 A standalone image is published to GHCR with Ruby 4.0 and Rigor

data/docs/manual/12-caching.md

@@ -38,6 +38,49 @@ The cache is also schema-versioned: after a Rigor upgrade that
 changes the cache format, the stale cache is purged on the
 first writable run.
 
+## How a file is checked for changes
+
+To decide whether a cached entry is still valid, Rigor needs to
+know which of your files changed since the entry was written. By
+default it checks each file's **stat metadata** first — size,
+nanosecond modification and change timestamps, and inode — and
+only re-hashes a file's content when that metadata moved. On a
+large project an unchanged run then reads *zero* content bytes to
+validate the cache, instead of re-hashing every file.
+
+The content hash stays the sole authority on whether a file
+actually changed: the stat check only decides whether the hash
+needs recomputing. A file that was merely `touch`ed (new
+timestamp, identical content) is re-hashed once and correctly
+found unchanged. Editing a file always moves its timestamps, so
+an edit is never missed.
+
+The stat check is skipped where it cannot work: the default
+setting is `validation: auto`, which behaves as `stat` on your
+machine and switches to hashing every file (`digest`) when a CI
+environment is detected. CI is the common case of untrustworthy
+stat metadata — a fresh checkout regenerates every timestamp and
+inode, so a cache restored across CI runs (for example with
+`actions/cache`) never passes the stat check, and parts of it
+(plugin watch-glob entries, which are stat-signature only) would
+be recomputed on every run. Content hashes are identical across
+checkouts, so under `digest` the restored cache simply hits.
+
+The setting can be forced either way:
+
+```yaml
+cache:
+  validation: digest    # hash always — for any filesystem whose
+                        # timestamps or inodes cannot be trusted
+  # validation: stat    # stat always — e.g. a self-hosted CI
+                        # runner that reuses its workspace, where
+                        # stat metadata IS stable across runs
+```
+
+For a single run, `RIGOR_STRICT_VALIDATION=1` forces `digest`
+and wins over the config key; `RIGOR_CI_DETECT=0` turns off the
+CI detection that `auto` relies on.
+
 ## Controlling the cache
 
 | Flag | Effect |
@@ -90,6 +133,28 @@ gate, `rigor check --verify-incremental`, asserts this on every
 build: it runs the incremental analyzer and a full analysis and
 fails if they disagree on a single diagnostic.
 
+Rigor is also precise about *what* an edit changed. Re-checking a
+file that many others depend on — a base class, a widely-used
+concern, a shared utility — used to re-check every dependent.
+Now, if your edit did not change the file's declaration shape
+(the signatures of its methods, its superclass and includes) or
+the types its methods return, the files that only depend on those
+things are left untouched: a comment, a formatting change, or an
+internal refactor that preserves every method's return type stops
+at the edited file. An edit that *does* change a return type or a
+signature still propagates to the dependents that consume it, so
+the result stays identical to a full run.
+
+Types contributed by plugins (a Sorbet signature, an
+ActiveRecord column type, a dry-types alias) are validated too:
+if a plugin's cross-file contributions change between runs, the
+snapshot is dropped and the next run is a full one, so a plugin
+edit can never leave a dependent stale.
+
+An `--incremental` re-check honours `--workers=N` (and
+`RIGOR_RACTOR_WORKERS` / `parallel.workers:`), analysing the
+affected files in parallel just as a full run does.
+
 The snapshot lives under the cache directory (`.rigor/cache`)
 and is keyed by a fingerprint of your configuration, your locked
 gems, your project's own `sig/` RBS, and the Rigor version.

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

@@ -2,6 +2,9 @@
 
 require "prism"
 
+require_relative "../../source/node_children"
+require_relative "inferred_param_guard"
+
 module Rigor
   module Analysis
     module CheckRules
@@ -81,7 +84,7 @@ module Rigor
           visit(node) if conditional_node?(node) && !in_loop_or_block
 
           child_in_loop_or_block = in_loop_or_block || enters_loop_or_block?(node)
-          node.compact_child_nodes.each { |child| walk(child, in_loop_or_block: child_in_loop_or_block) }
+          node.rigor_each_child { |child| walk(child, in_loop_or_block: child_in_loop_or_block) }
         end
 
         def conditional_node?(node)
@@ -100,6 +103,11 @@ module Rigor
           scope = @scope_index[node]
           return if scope.nil?
 
+          # ADR-67 WD6b — a predicate rooted at an inferred parameter (`opts.key?(:x)`) folds to a constant only
+          # because the seed's lower-bound type pinned it; a wider real caller would not. Declining preserves
+          # the precision-additive contract.
+          return if InferredParamGuard.rooted?(predicate, scope)
+
           predicate_type = scope.type_of(predicate)
           return unless predicate_type.is_a?(Type::Constant)
 

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

@@ -2,6 +2,8 @@
 
 require "prism"
 
+require_relative "../../source/node_children"
+
 module Rigor
   module Analysis
     module CheckRules
@@ -65,7 +67,7 @@ module Rigor
           return unless node.is_a?(Prism::Node)
 
           collect_def_assignments(node) if node.is_a?(Prism::DefNode)
-          node.compact_child_nodes.each { |child| walk_for_def_nodes(child) }
+          node.rigor_each_child { |child| walk_for_def_nodes(child) }
         end
 
         def collect_def_assignments(def_node)
@@ -92,7 +94,7 @@ module Rigor
           # / similar shapes don't trip the rule.
           accumulator << node.name if reading_assignment?(node)
 
-          node.compact_child_nodes.each { |child| gather_read_names(child, accumulator) }
+          node.rigor_each_child { |child| gather_read_names(child, accumulator) }
           accumulator
         end
 
@@ -110,7 +112,7 @@ module Rigor
           # outer walker visits them separately.
           return accumulator if node.is_a?(Prism::DefNode) && !accumulator.last.equal?(node)
 
-          node.compact_child_nodes.each { |child| gather_write_nodes(child, accumulator) }
+          node.rigor_each_child { |child| gather_write_nodes(child, accumulator) }
           accumulator
         end
 

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