hecks 1.0.2 → 1.1.0

data/lib/hecks/bluebook/model_check.rb

@@ -1,5 +1,3 @@
-require "set"
-
 module Hecks
   module Bluebook
     # Lightweight formal methods over the IR — the same family as TLA+/
@@ -89,7 +87,7 @@ module Hecks
           findings.concat(lifecycle_findings(aggregate, aggregate))
           aggregate.entities.each { |entity| findings.concat(lifecycle_findings(aggregate, entity)) }
         end
-        bluebook.process_managers.each { |pm| findings.concat(saga_findings(bluebook, pm)) }
+        bluebook.process_managers.each { |process_manager| findings.concat(saga_findings(bluebook, process_manager)) }
         bluebook.policies.each { |policy| findings.concat(policy_findings(bluebook, policy, hecksagon, known_domains)) }
         findings
       end
@@ -103,38 +101,46 @@ module Hecks
         subject = declaring.equal?(aggregate) ? aggregate.hecks_name : "#{aggregate.hecks_name}::#{declaring.hecks_name}"
         commands = Array(declaring.commands).map(&:hecks_name)
 
-        findings = []
-        findings.concat(unknown_transition_commands(lifecycle, commands, subject))
-
         full = full_states(lifecycle)
         reached = reachable_states(lifecycle)
 
-        (full - reached.to_a).each do |state|
-          findings << Finding.new(kind: :unreachable_state, severity: :error, subject: subject,
-                                  message: "#{state.inspect} is declared (in a transition's from: or target) " \
-                                           "but no path from #{lifecycle.default.inspect} ever reaches it")
+        findings = []
+        findings.concat(unknown_transition_commands(lifecycle, commands, subject))
+        findings.concat(unreachable_state_findings(lifecycle, full, reached, subject))
+        findings.concat(dead_transition_findings(lifecycle, reached, subject))
+        findings.concat(stuck_state_findings(lifecycle, reached, subject))
+        findings
+      end
+
+      def unreachable_state_findings(lifecycle, full, reached, subject)
+        (full - reached.to_a).map do |state|
+          Finding.new(kind: :unreachable_state, severity: :error, subject: subject,
+                      message: "#{state.inspect} is declared (in a transition's from: or target) " \
+                               "but no path from #{lifecycle.default.inspect} ever reaches it")
         end
+      end
 
-        lifecycle.transitions.each do |command, transition|
+      def dead_transition_findings(lifecycle, reached, subject)
+        lifecycle.transitions.filter_map do |command, transition|
           next unless transition.constrained?
           next if Array(transition.from).any? { |source| reached.include?(source) }
 
-          findings << Finding.new(kind: :dead_transition, severity: :error, subject: subject,
-                                  message: "#{command} from #{Array(transition.from).inspect} can never fire — " \
-                                           "none of those states is ever reached")
+          Finding.new(kind: :dead_transition, severity: :error, subject: subject,
+                      message: "#{command} from #{Array(transition.from).inspect} can never fire — " \
+                               "none of those states is ever reached")
         end
+      end
 
+      def stuck_state_findings(lifecycle, reached, subject)
         any_unconstrained = lifecycle.transitions.any? { |_, t| !t.constrained? }
-        (reached - terminal_exempt(lifecycle)).each do |state|
+        (reached - terminal_exempt(lifecycle)).filter_map do |state|
           next if any_unconstrained
           next if lifecycle.transitions.any? { |_, t| t.constrained? && Array(t.from).include?(state) }
 
-          findings << Finding.new(kind: :stuck_state, severity: :warning, subject: subject,
-                                  message: "#{state.inspect} is reached but no transition ever leaves it — " \
-                                           "fine if that is meant to be terminal")
+          Finding.new(kind: :stuck_state, severity: :warning, subject: subject,
+                      message: "#{state.inspect} is reached but no transition ever leaves it — " \
+                               "fine if that is meant to be terminal")
         end
-
-        findings
       end
 
       def unknown_transition_commands(lifecycle, commands, subject)
@@ -165,6 +171,11 @@ module Hecks
         reached = Set.new([lifecycle.default])
         loop do
           grown = false
+          # `transitions` is an Array of [from, transition]-shaped entries
+          # (Lifecycle#transitions), not a Hash — Style/HashEachMethods'
+          # `each_value` rewrite assumed otherwise from the block shape
+          # alone. False positive.
+          # rubocop:disable-next Style/HashEachMethods
           lifecycle.transitions.each do |_, transition|
             next if reached.include?(transition.target)
             next if transition.constrained? && Array(transition.from).none? { |source| reached.include?(source) }
@@ -202,79 +213,105 @@ module Hecks
 
       # ── process managers / sagas ──────────────────────────────────────
 
-      def saga_findings(bluebook, pm)
+      def saga_findings(bluebook, process_manager)
+        emitted = emitted_events(bluebook)
+        verbs   = verbs_of(bluebook)
+        reached = pm_reachable_states(process_manager, emitted)
+
         findings = []
-        emitted  = emitted_events(bluebook)
-        verbs    = verbs_of(bluebook)
+        findings.concat(deaf_trigger_findings(process_manager, emitted))
+        findings.concat(unreachable_pm_state_findings(process_manager, reached))
+        process_manager.handlers.each do |handler|
+          findings.concat(handler_findings(bluebook, process_manager, emitted, verbs, handler))
+        end
+        findings.concat(dead_compensation_findings(process_manager, reached))
+        findings
+      end
 
-        [pm.starts_on, pm.ends_on].compact.each do |event|
+      def deaf_trigger_findings(process_manager, emitted)
+        [process_manager.starts_on, process_manager.ends_on].compact.filter_map do |event|
           next if emitted.include?(bare(event))
 
-          findings << Finding.new(kind: :deaf_trigger, severity: :error, subject: pm.name,
-                                  message: "starts_on/ends_on names #{event.inspect}, which no command in this " \
-                                           "domain emits")
+          Finding.new(kind: :deaf_trigger, severity: :error, subject: process_manager.name,
+                      message: "starts_on/ends_on names #{event.inspect}, which no command in this " \
+                               "domain emits")
         end
+      end
 
-        reached = pm_reachable_states(pm, emitted)
-        (Array(pm.states) - reached.to_a).each do |state|
-          findings << Finding.new(kind: :unreachable_pm_state, severity: :error, subject: pm.name,
-                                  message: "#{state.inspect} is declared but no handler chain from " \
-                                           "#{pm.states.first.inspect} ever reaches it")
+      def unreachable_pm_state_findings(process_manager, reached)
+        (Array(process_manager.states) - reached.to_a).map do |state|
+          Finding.new(kind: :unreachable_pm_state, severity: :error, subject: process_manager.name,
+                      message: "#{state.inspect} is declared but no handler chain from " \
+                               "#{process_manager.states.first.inspect} ever reaches it")
         end
+      end
 
-        pm.handlers.each do |handler|
-          # The compensating leg answers REFUSED, a synthetic trigger no
-          # command ever emits by name (ProcessManager::REFUSED) — not
-          # a deaf handler, the one handler this domain's own events can
-          # never satisfy on purpose.
-          if handler.event_type != ProcessManager::REFUSED && !emitted.include?(bare(handler.event_type))
-            findings << Finding.new(kind: :deaf_handler, severity: :error, subject: pm.name,
-                                    message: "a handler answers #{handler.event_type.inspect}, which no command " \
-                                             "in this domain emits")
-          end
+      # ONE HANDLER'S OWN FINDINGS — deaf_handler, unknown_dispatch (one
+      # per dispatch), and unarmed_compensation (one per compensating
+      # dispatch), pulled out of saga_findings' own handler loop; each
+      # check reads only this handler plus the domain-wide emitted/verbs
+      # sets saga_findings already resolved once, no state shared BETWEEN
+      # handlers.
+      def handler_findings(bluebook, process_manager, emitted, verbs, handler)
+        findings = []
 
-          handler.dispatches.each do |dispatch|
-            # SAME-DOMAIN, same as `SagaInterpreter#qualified` — a dispatch
-            # naming no domain at all (the ordinary shape a bare command
-            # constant now produces, S6) means THIS one, and is compared
-            # against `verbs_of`'s own fully-qualified spelling qualified
-            # the identical way, not left bare to miss it on a technicality.
-            qualified = dispatch.command_name.include?("::") ? dispatch.command_name : "#{bluebook.name}::#{dispatch.command_name}"
-            next if verbs.include?(qualified)
-
-            findings << Finding.new(kind: :unknown_dispatch, severity: :error, subject: pm.name,
-                                    message: "dispatches #{dispatch.command_name.inspect}, which this domain " \
-                                             "declares no command at — cross-domain dispatch is out of this " \
-                                             "checker's scope, same as CommandRules#resolve_references")
-          end
+        # The compensating leg answers REFUSED, a synthetic trigger no
+        # command ever emits by name (ProcessManager::REFUSED) — not
+        # a deaf handler, the one handler this domain's own events can
+        # never satisfy on purpose.
+        if handler.event_type != ProcessManager::REFUSED && !emitted.include?(bare(handler.event_type))
+          findings << Finding.new(kind: :deaf_handler, severity: :error, subject: process_manager.name,
+                                  message: "a handler answers #{handler.event_type.inspect}, which no command " \
+                                           "in this domain emits")
+        end
 
-          # A `compensates` DECLARED WITH NOWHERE TO EVER FIRE — the exact
-          # shape of the real bug this whole feature closes ("the
-          # reversal was written and never armed"), caught at build/
-          # model-check time instead of discovered in production. No
-          # handler anywhere answers REFUSED (`pm.saga?` false) means
-          # `SagaInterpreter#unwind` never runs for this process
-          # manager at all, so a declared `compensates` is structurally
-          # unreachable — not a warning about style, a dead declaration.
-          if !pm.saga? && handler.dispatches.any?(&:compensates)
-            handler.dispatches.select(&:compensates).each do |dispatch|
-              findings << Finding.new(kind: :unarmed_compensation, severity: :error, subject: pm.name,
-                                      message: "#{dispatch.command_name} compensates #{dispatch.compensates.command_name}, " \
-                                               "but no handler anywhere in this saga answers a refusal — the " \
-                                               "compensation is declared and can never fire")
-            end
-          end
+        handler.dispatches.each do |dispatch|
+          # SAME-DOMAIN, same as `SagaInterpreter#qualified` — a dispatch
+          # naming no domain at all (the ordinary shape a bare command
+          # constant now produces, S6) means THIS one, and is compared
+          # against `verbs_of`'s own fully-qualified spelling qualified
+          # the identical way, not left bare to miss it on a technicality.
+          qualified = if dispatch.command_name.include?("::")
+                        dispatch.command_name
+                      else
+                        "#{bluebook.name}::#{dispatch.command_name}"
+                      end
+          next if verbs.include?(qualified)
+
+          findings << Finding.new(kind: :unknown_dispatch, severity: :error, subject: process_manager.name,
+                                  message: "dispatches #{dispatch.command_name.inspect}, which this domain " \
+                                           "declares no command at — cross-domain dispatch is out of this " \
+                                           "checker's scope, same as CommandRules#resolve_references")
         end
 
-        if pm.saga? && !reached.include?(pm.saga.from_state)
-          findings << Finding.new(kind: :dead_compensation, severity: :error, subject: pm.name,
-                                  message: "the compensation leaves #{pm.saga.from_state.inspect}, which no " \
-                                           "handler chain ever reaches — a refusal here can never fire it")
+        # A `compensates` DECLARED WITH NOWHERE TO EVER FIRE — the exact
+        # shape of the real bug this whole feature closes ("the
+        # reversal was written and never armed"), caught at build/
+        # model-check time instead of discovered in production. No
+        # handler anywhere answers REFUSED (`process_manager.saga?` false) means
+        # `SagaInterpreter#unwind` never runs for this process
+        # manager at all, so a declared `compensates` is structurally
+        # unreachable — not a warning about style, a dead declaration.
+        if !process_manager.saga? && handler.dispatches.any?(&:compensates)
+          handler.dispatches.select(&:compensates).each do |dispatch|
+            findings << Finding.new(kind: :unarmed_compensation, severity: :error, subject: process_manager.name,
+                                    message: "#{dispatch.command_name} compensates #{dispatch.compensates.command_name}, " \
+                                             "but no handler anywhere in this saga answers a refusal — the " \
+                                             "compensation is declared and can never fire")
+          end
         end
 
         findings
       end
 
+      def dead_compensation_findings(process_manager, reached)
+        return [] unless process_manager.saga? && !reached.include?(process_manager.saga.from_state)
+
+        [Finding.new(kind: :dead_compensation, severity: :error, subject: process_manager.name,
+                     message: "the compensation leaves #{process_manager.saga.from_state.inspect}, which no " \
+                              "handler chain ever reaches — a refusal here can never fire it")]
+      end
+
       # A handler edge is only usable in the closure if it can actually
       # FIRE — REFUSED always can (it is a compensation trigger, not an
       # event), and any other handler needs its event genuinely emitted.
@@ -283,13 +320,13 @@ module Hecks
       # it, which would hide exactly the states this walk exists to
       # catch (a state only "reachable" through a handler that itself
       # never fires).
-      def pm_reachable_states(pm, emitted)
-        return Set.new if Array(pm.states).empty?
+      def pm_reachable_states(process_manager, emitted)
+        return Set.new if Array(process_manager.states).empty?
 
-        reached = Set.new([pm.states.first])
+        reached = Set.new([process_manager.states.first])
         loop do
           grown = false
-          pm.handlers.each do |handler|
+          process_manager.handlers.each do |handler|
             next unless handler.event_type == ProcessManager::REFUSED || emitted.include?(bare(handler.event_type))
             next unless reached.include?(handler.from_state)
             next if reached.include?(handler.to_state)
@@ -446,9 +483,9 @@ module Hecks
         bluebook.aggregates.flat_map do |aggregate|
           verbs = aggregate.commands.map { |command| "#{bluebook.name}::#{aggregate.hecks_name}.#{command.hecks_name}" }
           verbs + aggregate.entities.flat_map do |entity|
-            entity.commands.map { |command|
+            entity.commands.map do |command|
               "#{bluebook.name}::#{aggregate.hecks_name}.#{entity.hecks_name}.#{command.hecks_name}"
-            }
+            end
           end
         end
       end

data/lib/hecks/bluebook/pattern_subset.rb

@@ -63,6 +63,15 @@ module Hecks
       # characters "(?=" and says nothing about lookahead — which is why this
       # steps over each backslash pair rather than matching the pattern as a
       # whole.
+      # One character walk is the subset's DEFINITION (see the method
+      # comment above): each construct-check is a branch in a single
+      # ordered pass sharing `index`/`in_class`/`class_start`. Splitting
+      # the branches into separate methods would force those three cursor
+      # variables to thread as parameters/return values between them,
+      # turning "the subset is this walk" into "the subset is these
+      # methods agreeing about a shared cursor" — exactly what the walk's
+      # own comment says a cleverer spelling would obscure.
+      # rubocop:disable-next Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
       def validate(pattern)
         chars = pattern.to_s.chars
         index = 0

data/lib/hecks/bluebook/policy.rb

@@ -16,7 +16,8 @@ module Hecks
         target_domain:   :target_domain,
         where:           :where,
         for_each:        :for_each,
-        with_spec:       -> { with_spec.map { |key, value| [key.to_s, Bluebook.render_value(value)] } }
+        with_spec:       -> { with_spec.map { |key, value| [key.to_s, Bluebook.render_value(value)] } },
+        where_ast:       -> { where_ast }
       )
 
       attr_reader :name, :on_event, :trigger_command, :target_domain, :where, :for_each, :with_spec

data/lib/hecks/bluebook/process_manager.rb

@@ -74,6 +74,12 @@ module Hecks
       def to_s = "#{trigger} → #{to_state} (#{undoes.join(', ')})"
     end
 
+    # The built form of a `process_manager "Name" do ... end` block,
+    # produced by `DSL::ProcessManagerBuilder` — its start/end events,
+    # correlation field, derived states, and handler rows. Its
+    # compensation half (`saga`, `Behaviour::ProcessManager#saga`) is
+    # DERIVED from the handler answering `REFUSED`, below, not declared as
+    # its own construct.
     class ProcessManager
       # The BLUEBOOK's name for this construct, asked the same way of a class
       # that has crossed over and of an IR object that has not. Collapses into

data/lib/hecks/bluebook/project_register.rb

@@ -35,34 +35,56 @@ module Hecks
                   "#{bluebook.name} in #{directory} declares latest #{world.latest.inspect}, not #{bluebook.version.inspect}"
           end
 
-          bluebook.aggregates.each do |aggregate|
-            aggregate.commands.each do |command|
-              add(Fqn.command(realm: realm, domain: bluebook.name, version: bluebook.version,
-                              aggregate: aggregate.hecks_name, command: command.hecks_name), directory, dispatcher, command.hecks_name, bluebook.version) if bluebook.version
-              add(Fqn.command(realm: realm, domain: bluebook.name, aggregate: aggregate.hecks_name,
-                              command: command.hecks_name), directory, dispatcher, command.hecks_name, bluebook.version) if current?(
-                                bluebook, world
-                              )
-            end
-            aggregate.queries.each do |query|
-              name = Naming.snake(query.name)
-              add(Fqn.query(realm: realm, domain: bluebook.name, version: bluebook.version,
-                            aggregate: aggregate.hecks_name, query: name), directory, dispatcher, query.name, bluebook.version) if bluebook.version
-              add(Fqn.query(realm: realm, domain: bluebook.name, aggregate: aggregate.hecks_name,
-                            query: name), directory, dispatcher, query.name, bluebook.version) if current?(bluebook, world)
-            end
+          bluebook.aggregates.each { |aggregate| register_aggregate!(aggregate, bluebook, world, realm, directory, dispatcher) }
+          bluebook.read_models.each { |model| register_read_model!(model, bluebook, world, realm, directory, dispatcher) }
+        end
+        self
+      end
+
+      private
+
+      # Split out of `register` per-aggregate: same versioned-then-current
+      # registration shape as `register_read_model!`, just applied to a
+      # command/query pair instead of a single report. No state threads
+      # back to `register` — each `add` call is independent.
+      def register_aggregate!(aggregate, bluebook, world, realm, directory, dispatcher)
+        aggregate.commands.each do |command|
+          if bluebook.version
+            add(Fqn.command(realm: realm, domain: bluebook.name, version: bluebook.version,
+                            aggregate: aggregate.hecks_name, command: command.hecks_name),
+                directory, dispatcher, command.hecks_name, bluebook.version)
           end
-          bluebook.read_models.each do |model|
+          if current?(bluebook, world)
+            add(Fqn.command(realm: realm, domain: bluebook.name, aggregate: aggregate.hecks_name,
+                            command: command.hecks_name), directory, dispatcher, command.hecks_name, bluebook.version)
+          end
+        end
+        aggregate.queries.each do |query|
+          name = Naming.snake(query.name)
+          if bluebook.version
             add(Fqn.query(realm: realm, domain: bluebook.name, version: bluebook.version,
-                          query: model.query_name), directory, dispatcher, model.query_name, bluebook.version) if bluebook.version
-            add(Fqn.query(realm: realm, domain: bluebook.name, query: model.query_name),
-                directory, dispatcher, model.query_name, bluebook.version) if current?(bluebook, world)
+                          aggregate: aggregate.hecks_name, query: name), directory, dispatcher, query.name, bluebook.version)
+          end
+          if current?(bluebook, world)
+            add(Fqn.query(realm: realm, domain: bluebook.name, aggregate: aggregate.hecks_name,
+                          query: name), directory, dispatcher, query.name, bluebook.version)
           end
         end
-        self
       end
 
-      private
+      # Split out of `register` per-read-model: registers the versioned FQN
+      # (if this bluebook declares a version) and the current/unversioned
+      # FQN (if this bluebook is the world's latest) for one report.
+      def register_read_model!(model, bluebook, world, realm, directory, dispatcher)
+        if bluebook.version
+          add(Fqn.query(realm: realm, domain: bluebook.name, version: bluebook.version,
+                        query: model.query_name), directory, dispatcher, model.query_name, bluebook.version)
+        end
+        if current?(bluebook, world)
+          add(Fqn.query(realm: realm, domain: bluebook.name, query: model.query_name),
+              directory, dispatcher, model.query_name, bluebook.version)
+        end
+      end
 
       # THE ACTUAL "more than one tenant" MOMENT — Runtime::TenantCheck's
       # own header names this table as the one place real multitenancy
@@ -93,9 +115,7 @@ module Hecks
 
       def add(fqn, directory, dispatcher, declared_verb, domain_version)
         existing = entries[fqn.to_s]
-        if existing
-          raise DuplicateFqn, "#{fqn} is declared in both #{existing.source_directory} and #{directory}"
-        end
+        raise DuplicateFqn, "#{fqn} is declared in both #{existing.source_directory} and #{directory}" if existing
 
         entries[fqn.to_s] = Entry.new(
           fqn: fqn, source_directory: directory, dispatcher: dispatcher,

data/lib/hecks/bluebook/query.rb

@@ -1,6 +1,10 @@
 require_relative "behaviour/query"
 
 module Hecks
+  # Reopened here only to add `render_value` below — the pinned
+  # wire-literal rendering (`Literal.render`) the `emits_ir` Procs
+  # throughout this chapter reach for. See lib/hecks/bluebook.rb's own
+  # header for what `Bluebook` is as a whole.
   module Bluebook
     def self.render_value(value) = Literal.render(value)
 

data/lib/hecks/bluebook/read_model.rb

@@ -35,8 +35,8 @@ module Hecks
       # `reference_target.nil?` stays a real, checkable fact for the
       # interpreter instead of silently becoming `""`.
       def initialize(name:, description: nil, reference_name: nil, reference_target: nil, aggregate_heads: [],
-                     group_by: [], count: nil, median_field: nil, **options)
-        super(joins: aggregate_heads, **options)
+                     group_by: [], count: nil, median_field: nil, **)
+        super(joins: aggregate_heads, **)
         @name             = name.to_s
         @hecks_name       = @name
         @description      = description

data/lib/hecks/bluebook/smoke_test.rb

@@ -118,6 +118,11 @@ module Hecks
       # the time that aggregate's own turn comes, the same reason
       # `Synthesizer#args_for`'s `created` map is threaded through in
       # this same order.
+      # `created` and `failures` thread through both the aggregate loop and the
+      # read_models loop below in the declaration order the comment above already
+      # documents; splitting would turn that ordering into an implicit contract on
+      # parameter/return passing instead of one visible sequence.
+      # rubocop:disable-next Metrics/AbcSize
       def smoke_domain(dispatcher, domain)
         chapter = dispatcher.registry.bluebook(domain)
         return [] unless chapter

data/lib/hecks/bluebook/synthesizer.rb

@@ -64,7 +64,8 @@ module Hecks
                        chapter.aggregates.filter_map { |a| a.value_object(type_name) }.first
         return "smoke-test" unless value_object
 
-        return value_object.members.first.to_h if value_object.respond_to?(:closed_set?) && value_object.closed_set? && value_object.members.any?
+        closed_set = value_object.respond_to?(:closed_set?) && value_object.closed_set? && value_object.members.any?
+        return value_object.members.first.to_h if closed_set
 
         value_object.attributes.to_h { |field| [field.name, field_value_for(chapter, aggregate, field.type)] }
       end

data/lib/hecks/bluebook/translation.rb

@@ -11,6 +11,9 @@ module Hecks
     # Paths follow `TranslationMove`'s convention (dotted reaches a VO
     # member); `values` maps every old-era value that can appear to its
     # new-era replacement.
+    # `:values` shadows Struct#values on purpose (same reasoning as
+    # AttributeCollector::OneOf) — no caller reads the built-in behavior.
+    # rubocop:disable-next Lint/StructNewOverride
     TranslationConvert = Struct.new(:from, :to, :values)
 
     # A value object's or entity's own TYPE NAME changed with its member

data/lib/hecks/bluebook/value_object.rb

@@ -3,7 +3,7 @@ require_relative "expression/ast_json"
 
 module Hecks
   module Bluebook
-    Invariant = Struct.new(:description, :canonical, :predicate, keyword_init: true)
+    Invariant = Struct.new(:description, :canonical, :predicate, :ast, keyword_init: true)
 
     # A value object — a DECLARATION HOLDER, never instantiated.
     #
@@ -37,7 +37,7 @@ module Hecks
         # `Expression::AstJson`'s own header — built for `rust/host`'s
         # own mint-time invariant check (`reference_validate.rs`), which
         # has no kernel crate to parse `canonical` with.
-        invariants: -> { invariants.map { |rule| { description: rule.description, canonical: rule.canonical, ast: Expression::AstJson.emit_predicate(rule.canonical) } } },
+        invariants: -> { invariants.map { |rule| Expression::AstJson.rule_row(rule) } },
         closed_set: :closed_set?,
         # THE FIELD NAME IS STRINGIFIED, NEVER THE VALUE. A `member` row can
         # hold any of the scalar types an attribute declares — `Integer 84`

data/lib/hecks/codemod.rb

@@ -221,7 +221,11 @@ module Hecks
       # loop for why it can't batch) — splitting it across methods just
       # to satisfy the line count would scatter state four ways for no
       # readability gain.
+      # rubocop:disable-next Metrics/AbcSize
       # rubocop:disable-next Metrics/BlockLength
+      # rubocop:disable-next Metrics/CyclomaticComplexity
+      # rubocop:disable-next Metrics/MethodLength
+      # rubocop:disable-next Metrics/PerceivedComplexity
       def run_example_domains(results, dry_run)
         Codemod::EXAMPLE_ROOTS.each do |domain_dir|
           bluebook_files = Dir.glob(File.join(domain_dir, "bluebook", "*.bluebook"))
@@ -286,6 +290,15 @@ module Hecks
       # changes the IR, so the running state's own export should always
       # still equal the pristine original after each kept edit, by
       # definition, no moving target needed.
+      # Same shape and same reason as run_example_domains just above (see
+      # its own comment) — the write/verify/revert sequence, PER
+      # CANDIDATE (this method's own comment explains why it cannot
+      # batch), is one coherent unit; splitting it would scatter
+      # before_meta/live_meta/applied_by_file state across methods for
+      # no gain.
+      # rubocop:disable-next Metrics/AbcSize
+      # rubocop:disable-next Metrics/CyclomaticComplexity
+      # rubocop:disable-next Metrics/PerceivedComplexity
       def run_meta_domain(results, dry_run)
         before_meta     = Codemod.boot_meta
         meta_candidates = @find_candidates.call(Codemod.meta_registry)

data/lib/hecks/doc/reference.rb

@@ -114,7 +114,7 @@ module Hecks
           by `bin/reference` — do not edit inside the markers. The prose
           between them is hand-written and survives regeneration.*
           #{GENERATED_END}
-          #{preamble.empty? ? '' : "\n#{preamble}\n"}
+          #{"\n#{preamble}\n" unless preamble.empty?}
           #{sections.join("\n")}
         PAGE
       end
@@ -145,7 +145,7 @@ module Hecks
           ## #{row[:word]}
 
           #{generated_begin(row[:word])}
-          #{spellings}#{facts.empty? ? '' : " — #{facts.join(', ')}"}
+          #{spellings}#{" — #{facts.join(', ')}" unless facts.empty?}
           #{table}#{GENERATED_END}
 
           #{prose_or_sentinel(prose)}
@@ -181,7 +181,7 @@ module Hecks
           name = arg[:at].to_s.empty? ? "`#{arg[:named]}:`" : "positional #{arg[:at]}"
           lines << "| #{name} | #{arg[:kind]} | #{arg[:required]} | #{arg[:fills]} |"
         end
-        lines.join("\n") + "\n"
+        "#{lines.join("\n")}\n"
       end
 
       def render_index
@@ -210,6 +210,11 @@ module Hecks
       # region existed has no generated marker ahead of its first `## `,
       # so nothing is collecting when that heading arrives and no empty
       # preamble is invented — the older shape reads back unchanged.
+      # A single-pass line-scanning state machine (current/collecting/
+      # buffer/in_fence) — each branch mutates shared local state that
+      # carries into the NEXT iteration, so splitting per branch would
+      # mean passing all four back and forth by reference every line.
+      # rubocop:disable-next Metrics/PerceivedComplexity
       def harvest(text)
         prose = {}
         current = PREAMBLE
@@ -263,7 +268,7 @@ module Hecks
       end
 
       def guide_index(root)
-        paths = Dir.glob(File.join(root, "docs/implemented/guides/*.md")).sort
+        paths = Dir.glob(File.join(root, "docs/implemented/guides/*.md"))
                    .reject { |p| %w[AUTHORING.md].include?(File.basename(p)) }
         lines = paths.map do |path|
           heading = File.foreach(path).find { |line| line.start_with?("# ") }
@@ -273,7 +278,7 @@ module Hecks
         lines.join("\n")
       end
 
-      def reference_index(root)
+      def reference_index(_root)
         count = contexts.size
         "[The DSL reference](docs/implemented/reference/index.md) — #{count} contexts, generated from " \
           "the aggregate-local tables under `lib/hecks/language/` and held to them by " \
@@ -333,11 +338,11 @@ module Hecks
       end
 
       def corpus_roster(root)
-        dirs = Dir.glob(File.join(root, "examples/*/")).sort
+        dirs = Dir.glob(File.join(root, "examples/*/"))
         lines = dirs.filter_map do |dir|
           name = File.basename(dir.chomp("/"))
-          bluebooks = Dir.glob(File.join(dir, "bluebook/*.bluebook")).sort
-          bluebooks = Dir.glob(File.join(dir, "*.bluebook")).sort if bluebooks.empty?
+          bluebooks = Dir.glob(File.join(dir, "bluebook/*.bluebook"))
+          bluebooks = Dir.glob(File.join(dir, "*.bluebook")) if bluebooks.empty?
           next if bluebooks.empty?
 
           vision = bluebooks.filter_map { |bluebook| File.read(bluebook)[/vision\s+"([^"]*)"/, 1] }.first
@@ -364,7 +369,7 @@ module Hecks
       # example — a word whose only "example" is invisible or inert is a
       # word still shipping on its prose alone, which is the thing this
       # gate exists to refuse.
-      EXAMPLE_FENCE = /^```ruby(?: bluebook| boot)?[ \t]*$/.freeze
+      EXAMPLE_FENCE = /^```ruby(?: bluebook| boot)?[ \t]*$/
 
       def exemplified?(prose) = prose.to_s.match?(EXAMPLE_FENCE)
 
@@ -378,12 +383,13 @@ module Hecks
       # `harvest` already rejects empty prose and the TODO sentinel, so a
       # word with nothing written for it arrives here with a nil.
       def live_words(directory)
-        contexts.flat_map { |context|
+        rows = contexts.flat_map do |context|
           path = File.join(directory, page_name(context))
           prose = File.exist?(path) ? harvest(File.read(path)) : {}
           keywords.select { |row| row[:context] == context && live?(row) }
                   .map { |row| [row[:word], context, prose[row[:word]]] }
-        }.uniq { |word, context, _| [word, context] }
+        end
+        rows.uniq { |word, context, _| [word, context] }
       end
 
       def name_of(word, context) = "#{word} (#{context})"