rigortype 0.2.7 → 0.2.8

data/lib/rigor/analysis/self_call_resolution_recorder.rb

@@ -2,50 +2,40 @@
 
 module Rigor
   module Analysis
-    # ADR-24 slice 4a — records every *implicit-self* method call the
-    # inference engine could not resolve to any method (RBS tier miss +
-    # user-class ancestor-walk miss + not a `Dynamic` receiver), captured
-    # at the single engine choke-point where such a call falls through to
-    # `Dynamic[top]` (`ExpressionTyper#call_type_for` → `fallback_for`).
+    # ADR-24 slice 4a — records every *implicit-self* method call the inference engine could not resolve to any
+    # method (RBS tier miss + user-class ancestor-walk miss + not a `Dynamic` receiver), captured at the single
+    # engine choke-point where such a call falls through to `Dynamic[top]` (`ExpressionTyper#call_type_for` →
+    # `fallback_for`).
     #
     # ## Why a recorder, not a check-rule
     #
-    # Slice 4 attempt 1 reimplemented self-call resolution inside
-    # `CheckRules` and produced 135 false positives on Rigor's own `lib`
-    # ([ADR-24](../../../docs/adr/24-self-method-call-resolution.md)
-    # § "Slice 4"): the second, weaker resolution path could not see
-    # `module_function` siblings, `Data.define` / `Struct` accessors, or
-    # mixin-contributed methods that the *engine's* real resolution
-    # handles. Recording at the engine's own miss point reuses that real
-    # resolution — those methods resolve before the miss, so they never
-    # reach the recorder. This module is the ADR-46 / ADR-47 "collect at
-    # evaluation time, never recompute" lesson applied to self-calls.
+    # Slice 4 attempt 1 reimplemented self-call resolution inside `CheckRules` and produced 135 false
+    # positives on Rigor's own `lib` ([ADR-24](../../../docs/adr/24-self-method-call-resolution.md) § "Slice
+    # 4"): the second, weaker resolution path could not see `module_function` siblings, `Data.define` /
+    # `Struct` accessors, or mixin-contributed methods that the *engine's* real resolution handles. Recording
+    # at the engine's own miss point reuses that real resolution — those methods resolve before the miss, so
+    # they never reach the recorder. This module is the ADR-46 / ADR-47 "collect at evaluation time, never
+    # recompute" lesson applied to self-calls.
     #
-    # ADR-24 slice 4 (`call.self-undefined-method`) consumes the recorded
-    # misses behind a confidently-closed-class gate (see `CheckRules` L775).
-    # The rule ships `:off` by default — {active?} is false on a normal run, so the
-    # instrumented choke-point pays a single integer read and records
-    # nothing. Recording is purely observational; it never changes a
-    # diagnostic.
+    # ADR-24 slice 4 (`call.self-undefined-method`) consumes the recorded misses behind a confidently-closed-class
+    # gate (see `CheckRules` L775). The rule ships `:off` by default — {active?} is false on a normal run, so
+    # the instrumented choke-point pays a single integer read and records nothing. Recording is purely
+    # observational; it never changes a diagnostic.
     #
-    # Modelled on {DependencyRecorder}: process-thread-local accumulator,
-    # a cheap disabled fast path, and a frozen snapshot for consumers.
+    # Modelled on {DependencyRecorder}: process-thread-local accumulator, a cheap disabled fast path, and a
+    # frozen snapshot for consumers.
     module SelfCallResolutionRecorder
       KEY = :__rigor_self_call_resolution_recorder__
       private_constant :KEY
 
-      # One unresolved implicit-self call. `class_name` is the receiver's
-      # statically known class (the enclosing `self` type); `method_name`
-      # the called name; `node` the Prism `CallNode` (held in-memory so the
-      # `call.self-undefined-method` collector can resolve its scope from the
-      # scope index and apply the closed-class gate); `path` / `line` /
-      # `column` locate the call site for the diagnostic.
+      # One unresolved implicit-self call. `class_name` is the receiver's statically known class (the
+      # enclosing `self` type); `method_name` the called name; `node` the Prism `CallNode` (held in-memory so
+      # the `call.self-undefined-method` collector can resolve its scope from the scope index and apply the
+      # closed-class gate); `path` / `line` / `column` locate the call site for the diagnostic.
       UnresolvedSelfCall = Data.define(:class_name, :method_name, :node, :path, :line, :column)
 
-      # Mutable per-consumer accumulator, frozen into a {Record} snapshot
-      # when {record_for} returns. Dedupes by the full call tuple so a
-      # method body re-typed under several call-site signatures records the
-      # miss once.
+      # Mutable per-consumer accumulator, frozen into a {Record} snapshot when {record_for} returns. Dedupes by
+      # the full call tuple so a method body re-typed under several call-site signatures records the miss once.
       class Accumulator
         attr_reader :consumer, :calls
 
@@ -68,18 +58,16 @@ module Rigor
 
       Record = Data.define(:consumer, :calls)
 
-      # Module-level activation count so the disabled fast path ({active?})
-      # is a plain integer read rather than a `Thread.current` hash lookup —
-      # the instrumented choke-point is on the dispatch miss path, so a
+      # Module-level activation count so the disabled fast path ({active?}) is a plain integer read rather
+      # than a `Thread.current` hash lookup — the instrumented choke-point is on the dispatch miss path, so a
       # normal (non-recording) run must pay as little as possible.
       @active_count = 0
       @mutex = Mutex.new
 
       module_function
 
-      # Activates recording for `consumer` (the path being analyzed) for the
-      # duration of the block and returns the frozen {Record}. Nests safely;
-      # restores the previous recorder on exit.
+      # Activates recording for `consumer` (the path being analyzed) for the duration of the block and returns
+      # the frozen {Record}. Nests safely; restores the previous recorder on exit.
       def record_for(consumer)
         previous = Thread.current[KEY]
         accumulator = Accumulator.new(consumer.to_s)
@@ -92,14 +80,13 @@ module Rigor
         @mutex.synchronize { @active_count -= 1 }
       end
 
-      # Plain integer read (GVL-atomic) — no `Thread.current` lookup on the
-      # disabled fast path.
+      # Plain integer read (GVL-atomic) — no `Thread.current` lookup on the disabled fast path.
       def active?
         @active_count.positive?
       end
 
-      # Records one unresolved implicit-self call. No-op when no consumer is
-      # active on this thread (another thread may have flipped {active?}).
+      # Records one unresolved implicit-self call. No-op when no consumer is active on this thread (another
+      # thread may have flipped {active?}).
       def record(class_name:, method_name:, node:, path:, line:, column:)
         accumulator = Thread.current[KEY]
         return if accumulator.nil?

data/lib/rigor/analysis/worker_session.rb

@@ -19,69 +19,49 @@ require_relative "erb_template_detector"
 
 module Rigor
   module Analysis
-    # ADR-15 Phase 4a — per-worker analysis substrate.
-    # [ADR-15](../../../docs/adr/15-ractor-concurrency.md)
-    # § Phase 4 carves the Ractor-isolated worker pool into sub-phases;
-    # 4a/4b/4c all landed, but the Ractor pool (4b) is blocked by Ruby
-    # Bug #22075 (UAF) — the active pool backend is fork (ADR-15 Amendment).
-    # This class exists so the per-worker ownership boundary is testable
-    # independently of any pool coordinator.
+    # ADR-15 Phase 4a — per-worker analysis substrate. [ADR-15](../../../docs/adr/15-ractor-concurrency.md) §
+    # Phase 4 carves the Ractor-isolated worker pool into sub-phases; 4a/4b/4c all landed, but the Ractor
+    # pool (4b) is blocked by Ruby Bug #22075 (UAF) — the active pool backend is fork (ADR-15 Amendment).
+    # This class exists so the per-worker ownership boundary is testable independently of any pool
+    # coordinator.
     #
     # The constructor takes only `Ractor.shareable?` inputs:
     #
-    # - `configuration` — Phase 2a ({Rigor::Configuration} is
-    #   `Ractor.shareable?`).
-    # - `cache_store` — the fork backend passes the parent runner's
-    #   pre-built Store (`cache_store: @cache_store` in PoolCoordinator);
-    #   workers share it rather than building their own at `cache_root`.
-    # - `plugin_blueprints` — Phase 3a
-    #   (`Array<Plugin::Blueprint>` is `Ractor.shareable?`).
+    # - `configuration` — Phase 2a ({Rigor::Configuration} is `Ractor.shareable?`).
+    # - `cache_store` — the fork backend passes the parent runner's pre-built Store (`cache_store:
+    #   @cache_store` in PoolCoordinator); workers share it rather than building their own at `cache_root`.
+    # - `plugin_blueprints` — Phase 3a (`Array<Plugin::Blueprint>` is `Ractor.shareable?`).
     # - `explain` — Boolean.
-    # - `synthetic_method_index` / `project_patched_methods` /
-    #   `project_scope_seed` — optional (default `nil` / `{}`). NOT
-    #   `Ractor.shareable?` (the seed tables carry Prism def nodes),
-    #   so the Ractor pool path leaves them unset; the fork backend
-    #   (ADR-15 Amendment), which builds the session pre-fork on the
-    #   parent, threads the runner's project-scan results through so
-    #   per-file inference matches the sequential path exactly.
-    #   `project_scope_seed` is `Runner#project_scope_seed_tables` —
-    #   the cross-file discovery tables `seed_project_scope` applies
-    #   to every per-file scope on the sequential path; without it a
-    #   worker cannot resolve calls to methods defined in OTHER
-    #   project files and emits `call.undefined-method` false
-    #   positives the sequential path does not.
+    # - `synthetic_method_index` / `project_patched_methods` / `project_scope_seed` — optional (default `nil`
+    #   / `{}`). NOT `Ractor.shareable?` (the seed tables carry Prism def nodes), so the Ractor pool path
+    #   leaves them unset; the fork backend (ADR-15 Amendment), which builds the session pre-fork on the
+    #   parent, threads the runner's project-scan results through so per-file inference matches the
+    #   sequential path exactly. `project_scope_seed` is `Runner#project_scope_seed_tables` — the cross-file
+    #   discovery tables `seed_project_scope` applies to every per-file scope on the sequential path;
+    #   without it a worker cannot resolve calls to methods defined in OTHER project files and emits
+    #   `call.undefined-method` false positives the sequential path does not.
     #
     # Internally the session OWNS (and never shares):
     #
     # - {Rigor::Plugin::Services} bound to the per-worker Store.
-    # - {Rigor::Plugin::Registry} materialised from the blueprints
-    #   via {Rigor::Plugin::Registry.materialize}; each plugin
-    #   instance, with its mutable per-run accumulators
-    #   (`@reachable_absurd_nodes`, `*_index`, …) lives entirely
-    #   inside this session.
-    # - {Rigor::RbsExtended::Reporter} +
-    #   {Rigor::Analysis::DependencySourceInference::BoundaryCrossReporter}
-    #   (Mutex-bearing; intentionally per-worker — the runner
-    #   merges entries post-pool via {#drain_reporters}).
-    # - {Rigor::Environment} threaded with the per-worker reporters
-    #   so reporter writes from inference / dispatcher accumulate
-    #   into the worker's own state.
+    # - {Rigor::Plugin::Registry} materialised from the blueprints via {Rigor::Plugin::Registry.materialize};
+    #   each plugin instance, with its mutable per-run accumulators (`@reachable_absurd_nodes`, `*_index`,
+    #   …) lives entirely inside this session.
+    # - {Rigor::RbsExtended::Reporter} + {Rigor::Analysis::DependencySourceInference::BoundaryCrossReporter}
+    #   (Mutex-bearing; intentionally per-worker — the runner merges entries post-pool via
+    #   {#drain_reporters}).
+    # - {Rigor::Environment} threaded with the per-worker reporters so reporter writes from inference /
+    #   dispatcher accumulate into the worker's own state.
     #
-    # Plugin `prepare` runs ONCE at construction time so each
-    # worker is "warm" by the time `#analyze` is first called. Any
-    # raise from `prepare` is captured into {#prepare_diagnostics}
-    # so the runner can surface them alongside the per-file
-    # diagnostic stream.
+    # Plugin `prepare` runs ONCE at construction time so each worker is "warm" by the time `#analyze` is
+    # first called. Any raise from `prepare` is captured into {#prepare_diagnostics} so the runner can
+    # surface them alongside the per-file diagnostic stream.
     #
-    # Equivalence contract (proven by spec): given identical
-    # `(configuration, cache_store, plugin_blueprints)`, the
-    # multiset of diagnostics from
-    # `paths.flat_map { |p| session.analyze(p) }` plus
-    # {#prepare_diagnostics} plus reporter drains MUST equal the
-    # corresponding subset of {Rigor::Analysis::Runner#run}'s
-    # output (modulo severity-profile re-stamping, which the
-    # session leaves to the caller because it is a per-run
-    # aggregate concern).
+    # Equivalence contract (proven by spec): given identical `(configuration, cache_store,
+    # plugin_blueprints)`, the multiset of diagnostics from `paths.flat_map { |p| session.analyze(p) }` plus
+    # {#prepare_diagnostics} plus reporter drains MUST equal the corresponding subset of
+    # {Rigor::Analysis::Runner#run}'s output (modulo severity-profile re-stamping, which the session leaves
+    # to the caller because it is a per-run aggregate concern).
     class WorkerSession # rubocop:disable Metrics/ClassLength
       attr_reader :configuration, :cache_store, :services, :plugin_registry,
                   :dependency_source_index, :environment,
@@ -89,16 +69,12 @@ module Rigor
                   :prepare_diagnostics
 
       # @param configuration [Rigor::Configuration]
-      # @param cache_store [Rigor::Cache::Store, nil] persistent
-      #   cache the session exposes to plugin-side producers and
-      #   the RBS loader. Pass `nil` to disable caching.
-      # @param plugin_blueprints [Array<Rigor::Plugin::Blueprint>]
-      #   replay descriptors. Empty array yields a session with
-      #   no plugin contributions.
-      # @param explain [Boolean] when true, `#analyze` additionally
-      #   emits one `:info` `fallback` diagnostic per
-      #   directly-unrecognised node, mirroring
-      #   {Rigor::Analysis::Runner#explain_diagnostics}.
+      # @param cache_store [Rigor::Cache::Store, nil] persistent cache the session exposes to plugin-side
+      #   producers and the RBS loader. Pass `nil` to disable caching.
+      # @param plugin_blueprints [Array<Rigor::Plugin::Blueprint>] replay descriptors. Empty array yields a
+      #   session with no plugin contributions.
+      # @param explain [Boolean] when true, `#analyze` additionally emits one `:info` `fallback` diagnostic
+      #   per directly-unrecognised node, mirroring {Rigor::Analysis::Runner#explain_diagnostics}.
       def initialize(configuration:, cache_store: nil, # rubocop:disable Metrics/MethodLength,Metrics/ParameterLists
                      plugin_blueprints: [], explain: false, buffer: nil,
                      synthetic_method_index: nil, project_patched_methods: nil,
@@ -110,18 +86,14 @@ module Rigor
         @synthetic_method_index = synthetic_method_index
         @project_patched_methods = project_patched_methods
         @project_scope_seed = project_scope_seed || {}
-        # ADR-32 WD4 — full project file list (frozen
-        # Array<String>) for env-build-time invocation of any
+        # ADR-32 WD4 — full project file list (frozen Array<String>) for env-build-time invocation of any
         # loaded plugin's `source_rbs_synthesizer` callable.
         @source_files = source_files
 
-        # NOTE: `Inference::MethodDispatcher::FileFolding.fold_platform_specific_paths`
-        # is process-global state. Writing it from a non-main
-        # Ractor would raise `Ractor::IsolationError`, so the
-        # session does NOT touch it — the CALLER (typically
-        # {Rigor::Analysis::Runner#run}) is responsible for
-        # setting it on the main Ractor before spawning the
-        # pool. The substrate stays Ractor-safe by construction.
+        # NOTE: `Inference::MethodDispatcher::FileFolding.fold_platform_specific_paths` is process-global
+        # state. Writing it from a non-main Ractor would raise `Ractor::IsolationError`, so the session does
+        # NOT touch it — the CALLER (typically {Rigor::Analysis::Runner#run}) is responsible for setting it
+        # on the main Ractor before spawning the pool. The substrate stays Ractor-safe by construction.
         @rbs_extended_reporter = RbsExtended::Reporter.new
         @boundary_cross_reporter = DependencySourceInference::BoundaryCrossReporter.new
         @source_rbs_synthesis_reporter = Plugin::SourceRbsSynthesisReporter.new
@@ -158,11 +130,9 @@ module Rigor
         @prepare_diagnostics = run_plugin_prepare.freeze
       end
 
-      # Equivalent of {Rigor::Analysis::Runner#analyze_file} +
-      # `plugin_emitted_diagnostics` + `explain_diagnostics`.
-      # Returns a flat `Array<Diagnostic>` for the file. Severity
-      # profile re-stamping is intentionally NOT applied — that
-      # is a per-run aggregate concern handled by the caller.
+      # Equivalent of {Rigor::Analysis::Runner#analyze_file} + `plugin_emitted_diagnostics` +
+      # `explain_diagnostics`. Returns a flat `Array<Diagnostic>` for the file. Severity profile re-stamping
+      # is intentionally NOT applied — that is a per-run aggregate concern handled by the caller.
       def analyze(path)
         parse_result = parse_source(path)
         unless parse_result.errors.empty?
@@ -192,11 +162,9 @@ module Rigor
         [analyzer_error(path, "internal analyzer error: #{e.class}: #{e.message}")]
       end
 
-      # Read-once snapshot of the per-worker reporters so the
-      # caller (or the eventual Phase 4b pool aggregator) can
-      # merge into a single coordinator-side reporter. Both
-      # reporters dedupe at write time, so a post-hoc concat +
-      # de-dup at the entry-key level is sound.
+      # Read-once snapshot of the per-worker reporters so the caller (or the eventual Phase 4b pool
+      # aggregator) can merge into a single coordinator-side reporter. Both reporters dedupe at write time,
+      # so a post-hoc concat + de-dup at the entry-key level is sound.
       def drain_reporters
         {
           rbs_extended: {
@@ -210,21 +178,18 @@ module Rigor
 
       private
 
-      # Mirrors {Runner#seed_project_scope}: applies the cross-file
-      # pre-pass discovery tables the constructor received (fork
-      # backend only — see the class comment) to a fresh per-file
-      # scope, so worker-side inference resolves project-internal
-      # cross-file calls exactly like the sequential path.
+      # Mirrors {Runner#seed_project_scope}: applies the cross-file pre-pass discovery tables the
+      # constructor received (fork backend only — see the class comment) to a fresh per-file scope, so
+      # worker-side inference resolves project-internal cross-file calls exactly like the sequential path.
       def seed_project_scope(scope)
         return scope if @project_scope_seed.empty?
 
         scope.with_discovery(scope.discovery.with(**@project_scope_seed))
       end
 
-      # See {Runner#parse_source}. Same contract: if `@buffer`
-      # binds `path` to a physical file, read the physical bytes
-      # but stamp the parse buffer's `filepath:` as the LOGICAL
-      # path so downstream diagnostics carry the logical path.
+      # See {Runner#parse_source}. Same contract: if `@buffer` binds `path` to a physical file, read the
+      # physical bytes but stamp the parse buffer's `filepath:` as the LOGICAL path so downstream
+      # diagnostics carry the logical path.
       def parse_source(path)
         physical = @buffer ? @buffer.resolve(path) : path
         return Prism.parse_file(physical, version: @configuration.target_ruby) if physical == path
@@ -232,9 +197,8 @@ module Rigor
         Prism.parse(File.read(physical), filepath: path, version: @configuration.target_ruby)
       end
 
-      # Mirrors {Runner#build_trust_policy}. Deriving trust inside
-      # the session keeps the substrate decoupled from the
-      # coordinator; configuration is already Ractor-shareable.
+      # Mirrors {Runner#build_trust_policy}. Deriving trust inside the session keeps the substrate decoupled
+      # from the coordinator; configuration is already Ractor-shareable.
       def build_trust_policy
         trusted_gems = @configuration.plugins.map { |entry| trusted_gem_name(entry) }.uniq
         roots = [Dir.pwd]
@@ -302,11 +266,10 @@ module Rigor
         end
       end
 
-      # ADR-52 WD4 + ADR-53 B4 — single engine-owned walk per file drives
-      # both the plugin node rules (bucketed per plugin in registry order,
-      # plugin-major emission) and the built-in node collectors
-      # (`node_collectors`, populated in place). Runs even with no node-rule
-      # plugins so the collectors still get driven (converged path).
+      # ADR-52 WD4 + ADR-53 B4 — single engine-owned walk per file drives both the plugin node rules
+      # (bucketed per plugin in registry order, plugin-major emission) and the built-in node collectors
+      # (`node_collectors`, populated in place). Runs even with no node-rule plugins so the collectors still
+      # get driven (converged path).
       def node_rule_results_by_plugin(path, root, scope, node_collectors, scope_index)
         walk = @plugin_registry.node_rule_walk
         driver = node_collectors && CheckRules.node_collector_driver(node_collectors)
@@ -325,9 +288,8 @@ module Rigor
 
       def collect_plugin_diagnostics(plugin, path, root, scope, node_result)
         raw = Array(plugin.diagnostics_for_file(path: path, scope: scope, root: root))
-        # A node-rule context/rule raise isolates the whole plugin's
-        # node-rule contribution, matching the old combined per-plugin
-        # rescue (which discarded `diagnostics_for_file` output too).
+        # A node-rule context/rule raise isolates the whole plugin's node-rule contribution, matching the
+        # old combined per-plugin rescue (which discarded `diagnostics_for_file` output too).
         raise node_result.error if node_result&.error
 
         raw += node_result.diagnostics if node_result

data/lib/rigor/ast/type_node.rb

@@ -2,16 +2,14 @@
 
 module Rigor
   module AST
-    # A virtual node that wraps a Rigor::Type. Allows callers to ask
-    # "what would the analyzer infer at this position if the value's type
-    # were T?" without constructing a real Prism expression.
+    # A virtual node that wraps a Rigor::Type. Allows callers to ask "what would the analyzer infer at this
+    # position if the value's type were T?" without constructing a real Prism expression.
     #
-    # Rigor::Scope#type_of(TypeNode.new(t)) MUST return a structurally-
-    # equal t. The engine MUST NOT modify or annotate the wrapped type.
+    # Rigor::Scope#type_of(TypeNode.new(t)) MUST return a structurally-equal t. The engine MUST NOT modify or
+    # annotate the wrapped type.
     #
-    # Inspired by PHPStan's TypeExpr (a synthetic Expr that returns a
-    # specific Type from $scope->getType). The Rigor counterpart is
-    # spelled "TypeNode" to align with Prism's "Node" suffix convention.
+    # Inspired by PHPStan's TypeExpr (a synthetic Expr that returns a specific Type from $scope->getType). The
+    # Rigor counterpart is spelled "TypeNode" to align with Prism's "Node" suffix convention.
     class TypeNode
       include Node
 

data/lib/rigor/ast.rb

@@ -1,17 +1,13 @@
 # frozen_string_literal: true
 
 module Rigor
-  # Synthetic AST nodes accepted by Rigor::Scope#type_of alongside real
-  # Prism nodes. Rigor::AST::Node is a documentation-only marker module
-  # that production code uses to detect virtual-node arguments. Concrete
-  # virtual node classes include Rigor::AST::Node and provide whatever
-  # node-specific data the engine needs to translate them into a
-  # Rigor::Type.
+  # Synthetic AST nodes accepted by Rigor::Scope#type_of alongside real Prism nodes. Rigor::AST::Node is a
+  # documentation-only marker module that production code uses to detect virtual-node arguments. Concrete virtual
+  # node classes include Rigor::AST::Node and provide whatever node-specific data the engine needs to translate
+  # them into a Rigor::Type.
   #
-  # The contract for virtual nodes lives in
-  # docs/internal-spec/inference-engine.md; the rationale and the rejected
-  # alternative of specialising type classes for operator-method dispatch
-  # live in docs/adr/4-type-inference-engine.md.
+  # The contract for virtual nodes lives in docs/internal-spec/inference-engine.md; the rationale and the rejected
+  # alternative of specialising type classes for operator-method dispatch live in docs/adr/4-type-inference-engine.md.
   module AST
     # Marker module included by every synthetic node. Carries no behaviour.
     module Node

data/lib/rigor/bleeding_edge.rb

@@ -3,26 +3,21 @@
 module Rigor
   # ADR-50 § WD2 — the bleeding-edge overlay.
   #
-  # A Rigor-maintained set of the *next major's* queued changes —
-  # severity-map promotions and new-discipline rule enablements — that a
-  # user can adopt early, before they become default-on at a major
-  # (ADR-50 § WD7). It is orthogonal to `severity_profile:` (how loud
-  # *today's* rules are) and is versioned with the gem, NOT a
-  # user-supplied file: the inspectable counterpart to PHPStan's
-  # `bleedingEdge` include.
+  # A Rigor-maintained set of the *next major's* queued changes — severity-map promotions and
+  # new-discipline rule enablements — that a user can adopt early, before they become
+  # default-on at a major (ADR-50 § WD7). It is orthogonal to `severity_profile:` (how loud
+  # *today's* rules are) and is versioned with the gem, NOT a user-supplied file: the
+  # inspectable counterpart to PHPStan's `bleedingEdge` include.
   #
-  # The overlay is **empty today** — no discipline has yet been queued
-  # for the next major. This module is the WD2 *foundation* (the v0.1.19
-  # slice): the surface (`bleeding_edge:` config, the
-  # `rigor show-bleedingedge` command, the severity-composition hook in
-  # {Configuration::SeverityProfile.resolve}) exists and is wired
-  # end-to-end, so the first real feature lands as a single {FEATURES}
-  # entry with no engine plumbing.
+  # The overlay is **empty today** — no discipline has yet been queued for the next major.
+  # This module is the WD2 *foundation* (the v0.1.19 slice): the surface (`bleeding_edge:`
+  # config, the `rigor show-bleedingedge` command, the severity-composition hook in
+  # {Configuration::SeverityProfile.resolve}) exists and is wired end-to-end, so the first
+  # real feature lands as a single {FEATURES} entry with no engine plumbing.
   #
-  # Each feature carries a **stable feature id** — part of the ADR-50
-  # WD1 contract vocabulary: the config, the `show` command, and the
-  # eventual CHANGELOG migration note all name the same id, and a
-  # feature graduates to default-on at a major by being removed from
+  # Each feature carries a **stable feature id** — part of the ADR-50 WD1 contract
+  # vocabulary: the config, the `show` command, and the eventual CHANGELOG migration note all
+  # name the same id, and a feature graduates to default-on at a major by being removed from
   # {FEATURES}.
   module BleedingEdge
     # One queued change.
@@ -32,10 +27,9 @@ module Rigor
     # @!attribute summary
     #   @return [String] a one-line description of what it changes.
     # @!attribute severity_overrides
-    #   @return [Hash{String => Symbol}] canonical rule id → the
-    #     severity this feature imposes. Composed *below* the user's own
-    #     `severity_overrides:` and *above* the active `severity_profile`
-    #     (see {Configuration::SeverityProfile.resolve}).
+    #   @return [Hash{String => Symbol}] canonical rule id → the severity this feature
+    #     imposes. Composed *below* the user's own `severity_overrides:` and *above* the
+    #     active `severity_profile` (see {Configuration::SeverityProfile.resolve}).
     Feature = Data.define(:id, :summary, :severity_overrides) do
       def to_h
         {
@@ -46,8 +40,8 @@ module Rigor
       end
     end
 
-    # The overlay. Empty until the first next-major discipline is
-    # queued; add a {Feature} here (with a stable id) when one is.
+    # The overlay. Empty until the first next-major discipline is queued; add a {Feature}
+    # here (with a stable id) when one is.
     FEATURES = [].freeze
 
     module_function
@@ -68,12 +62,11 @@ module Rigor
       FEATURES.find { |f| f.id == id }
     end
 
-    # Resolves a normalized `bleeding_edge:` selector (see
-    # {Configuration#bleeding_edge}) to the active {Feature} list.
-    # Unknown ids in a `list` / `except` selector are simply absent from
-    # the overlay and contribute nothing — symmetric with how
-    # `severity_overrides:` keeps an unknown rule id inert until it
-    # lands (robust across gem versions).
+    # Resolves a normalized `bleeding_edge:` selector (see {Configuration#bleeding_edge}) to
+    # the active {Feature} list. Unknown ids in a `list` / `except` selector are simply
+    # absent from the overlay and contribute nothing — symmetric with how
+    # `severity_overrides:` keeps an unknown rule id inert until it lands (robust across gem
+    # versions).
     #
     # @param selector [Hash] `{ "mode" => "none" }`,
     #   `{ "mode" => "all" }`, `{ "mode" => "all", "except" => [ids] }`,
@@ -92,8 +85,8 @@ module Rigor
       end
     end
 
-    # The merged severity-override map the active features impose for a
-    # selector. Frozen so the result is `Ractor.shareable?`.
+    # The merged severity-override map the active features impose for a selector. Frozen so
+    # the result is `Ractor.shareable?`.
     #
     # @param selector [Hash] see {#active_features}.
     # @return [Hash{String => Symbol}]
@@ -103,9 +96,8 @@ module Rigor
       end.freeze
     end
 
-    # Feature ids named by a selector that are NOT in the overlay
-    # (typo / graduated / from a newer gem). Surfaced by
-    # `rigor show-bleedingedge` as a hint; never an error.
+    # Feature ids named by a selector that are NOT in the overlay (typo / graduated / from a
+    # newer gem). Surfaced by `rigor show-bleedingedge` as a hint; never an error.
     #
     # @param selector [Hash] see {#active_features}.
     # @return [Array<String>]

data/lib/rigor/builtins/hkt_builtins.rb

@@ -6,28 +6,21 @@ require_relative "../inference/hkt_body_parser"
 
 module Rigor
   module Builtins
-    # ADR-20 slices 2c + 3 — Rigor-bundled Lightweight HKT
-    # registrations that ship with every analyzer instance.
-    # The set is intentionally small at v0.1.x: only the URIs
-    # whose payoff justifies hardcoded definitions. Plugin
-    # authors register more URIs through their manifests; user
-    # `.rbs` overlays register through the
-    # `%a{rigor:v1:hkt_register}` /
-    # `%a{rigor:v1:hkt_define}` annotations Slice 1 ships.
+    # ADR-20 slices 2c + 3 — Rigor-bundled Lightweight HKT registrations that ship with every analyzer instance.
+    # The set is intentionally small at v0.1.x: only the URIs whose payoff justifies hardcoded definitions. Plugin
+    # authors register more URIs through their manifests; user `.rbs` overlays register through the
+    # `%a{rigor:v1:hkt_register}` / `%a{rigor:v1:hkt_define}` annotations Slice 1 ships.
     #
     # Today's contents:
     #
-    # - `json::value[K]` — the recursive sum stdlib's
-    #   `JSON.parse` returns. Body:
+    # - `json::value[K]` — the recursive sum stdlib's `JSON.parse` returns. Body:
     #
     #     nil | true | false | Integer | Float | String
     #     | Array[App[json::value, K]]
     #     | Hash[K, App[json::value, K]]
     #
-    #   The reducer handles the self-recursive `App` nodes via
-    #   lazy "tying-the-knot" (see {HktReducer}). `K = String`
-    #   matches stdlib's default key handling; `K = Symbol`
-    #   matches `symbolize_names: true`.
+    #   The reducer handles the self-recursive `App` nodes via lazy "tying-the-knot" (see {HktReducer}). `K = String`
+    #   matches stdlib's default key handling; `K = Symbol` matches `symbolize_names: true`.
     module HktBuiltins
       module_function