hecks 5.0.0 → 7.0.0

data/lib/hecks/bluebook/model_check/reaction_chains.rb

@@ -0,0 +1,114 @@
+require_relative "../ask_resolution"
+require_relative "reaction_cycles"
+require_relative "reaction_walk"
+
+module Hecks
+  module Bluebook
+    module ModelCheck
+      # The reaction graph of one bluebook: which verb emits which event, which policy reacts to
+      # it, and which verb that policy dispatches in turn, an `ask` resolved through the
+      # hecksagon to its port operation. `from` walks it to the longest chain a verb's events start.
+      #
+      # A policy already on the path is not followed again: a loop is cut where it closes, so a
+      # chain counts each policy once; `cycles` reports the loops themselves. A cross-domain
+      # (`across`) policy ends a chain, since the other domain's policies are not in this
+      # bluebook. A `where` is not evaluated, so a chain is the deepest one the declarations
+      # allow, not one a run is certain to take.
+      class ReactionChains
+        # One reaction step: the policy that fires and the verb it dispatches.
+        Step = Struct.new(:policy, :verb) do
+          # @return [String] the policy's name
+          def policy_name = policy.name
+        end
+
+        # @param bluebook [Bluebook::Declaration] the assembled bluebook, its hecksagon attached
+        def initialize(bluebook)
+          @bluebook  = bluebook
+          @emitted   = emitted_by_verb
+          @policies  = bluebook.policies.reject(&:target_domain)
+          @dispatch  = @policies.to_h { |policy| [policy, dispatched_by(policy)] }
+          @successors = @policies.to_h { |policy| [policy, @dispatch[policy] ? reacting_to(@dispatch[policy]) : []] }
+        end
+
+        # @return [Array<Array<String>>] each verb that emits an event, as split_verb parses it
+        def verbs = @emitted.keys
+
+        # @return [Set<Array>] the verbs some policy dispatches, which a longer chain already covers
+        def reaction_targets = @dispatch.values.compact.to_set
+
+        # @param verb [Array<String>] a verb, as `Naming.split_verb` parses it
+        # @return [Array<Step>] the longest chain of reactions the verb's events start, in order
+        def from(verb) = walk.longest(reacting_to(verb))
+
+        # @return [Boolean] whether the last `from` stopped searching, so its chain is a lower bound
+        def capped? = walk.capped?
+
+        # @return [Array<Array>] each loop in the graph, as the policies that reach one another
+        def cycles = @cycles ||= ReactionCycles.new(@policies, @successors).groups
+
+        # @param policy [Object] a policy of this bluebook
+        # @return [Step] the policy with the verb it dispatches
+        def step(policy) = Step.new(policy, @dispatch[policy])
+
+        # @param policy [Object] a policy of this bluebook
+        # @return [Array] the policies the verb it dispatches starts
+        def successors(policy) = @successors.fetch(policy)
+
+        private
+
+        def walk = @walk ||= ReactionWalk.new(self, cycles.flatten)
+
+        # Policies that react to an event the verb emits.
+        def reacting_to(verb)
+          events = @emitted.fetch(verb, [])
+          @policies.select { |policy| events.any? { |aggregate, event| hears?(policy, aggregate, event) } }
+        end
+
+        def hears?(policy, aggregate, event)
+          return false unless policy.event_name == event
+
+          qualifier = policy.event_qualifier
+          qualifier.nil? || Naming.demodulise(qualifier) == aggregate
+        end
+
+        def dispatched_by(policy)
+          verb = policy.asks? ? asked_verb(policy) : "#{@bluebook.name}::#{policy.trigger_command}"
+          Naming.split_verb(verb) if verb
+        end
+
+        # The port operation an `ask` resolves to, spelled as a trigger names it, or nil.
+        def asked_verb(policy)
+          outcome = AskResolution.call(@bluebook, policy)
+          "#{@bluebook.name}::#{outcome.verb}" if outcome.resolved?
+        end
+
+        # Each verb the bluebook declares to the `[aggregate, event]` pairs it announces.
+        def emitted_by_verb
+          @bluebook.aggregates.each_with_object({}) do |aggregate, held|
+            commands_of(aggregate).each { |verb, events| held[verb] = events.map { |event| [aggregate.hecks_name, event] } }
+          end
+        end
+
+        def commands_of(aggregate)
+          prefix = "#{@bluebook.name}::#{aggregate.hecks_name}"
+          [*aggregate.commands.map { |command| ["#{prefix}.#{command.hecks_name}", command.emits] },
+           *aggregate.entities.flat_map { |entity| entity_commands(prefix, entity) },
+           *aggregate.ports.flat_map { |port| operations(prefix, port) }]
+            .to_h { |verb, events| [Naming.split_verb(verb), bare_names(events)] }
+        end
+
+        def bare_names(events) = Array(events).map { |event| event.to_s.split("::").last }
+
+        def entity_commands(prefix, entity)
+          entity.commands.map { |command| ["#{prefix}.#{entity.hecks_name}.#{command.hecks_name}", command.emits] }
+        end
+
+        def operations(prefix, port)
+          port.operations.map do |operation|
+            ["#{prefix}.#{port.name}.#{operation.hecks_name}", [*operation.emits, operation.answers, operation.refuses].compact]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/model_check/reaction_cycles.rb

@@ -0,0 +1,53 @@
+module Hecks
+  module Bluebook
+    module ModelCheck
+      # The loops of a reaction graph: groups of policies that can each reach the others through
+      # the commands they dispatch (the strongly connected components with a cycle in them, found
+      # with Tarjan's algorithm), whether or not any command outside the group starts them.
+      class ReactionCycles
+        # @param policies [Array] the graph's nodes, in declaration order
+        # @param successors [Hash{Object => Array}] the policies each policy's dispatch can start
+        def initialize(policies, successors)
+          @policies   = policies
+          @successors = successors
+        end
+
+        # @return [Array<Array>] each loop's policies, in declaration order
+        def groups
+          @index = {}
+          @low = {}
+          @stack = []
+          @found = []
+          @policies.each { |policy| connect(policy) unless @index.key?(policy) }
+          @found.select { |group| loop?(group) }.map { |group| group.sort_by { |policy| @policies.index(policy) } }
+        end
+
+        private
+
+        def loop?(group) = group.size > 1 || @successors.fetch(group.first).include?(group.first)
+
+        def connect(node)
+          @index[node] = @low[node] = @index.size
+          @stack.push(node)
+          @successors.fetch(node).each { |next_node| visit(node, next_node) }
+          @found << pop_group(node) if @low[node] == @index[node]
+        end
+
+        def visit(node, next_node)
+          if @index.key?(next_node)
+            @low[node] = [@low[node], @index[next_node]].min if @stack.include?(next_node)
+          else
+            connect(next_node)
+            @low[node] = [@low[node], @low[next_node]].min
+          end
+        end
+
+        def pop_group(root)
+          group = []
+          group << @stack.pop until group.last.equal?(root)
+          group
+        end
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/model_check/reaction_depth_checks.rb

@@ -0,0 +1,58 @@
+require_relative "reaction_chains"
+
+module Hecks
+  module Bluebook
+    module ModelCheck
+      # The checks over reaction chains. A command whose events start a chain of policies longer
+      # than the dispatcher's reaction limit has the reactions past it refused without anyone
+      # being told; a chain of exactly the limit runs whole, in both runtimes. A loop of
+      # policies, which no limit on the chain's length can describe, is reported as a loop.
+      module ReactionDepthChecks
+        # @param bluebook [Bluebook::Declaration] the assembled bluebook, its hecksagon attached
+        # @param limit [Integer] the reaction depth limit; the dispatcher's own when not given
+        # @return [Array<Finding>] a warning for each entry command whose longest chain exceeds
+        #   `limit`, for each loop of policies, and for each chain search that gave up
+        def reaction_depth_findings(bluebook, limit: Hecks::Runtime::Dispatcher::MAX_REACTION_DEPTH)
+          chains = ReactionChains.new(bluebook)
+          [*(chains.verbs - chains.reaction_targets.to_a).flat_map { |verb| chain_findings(chains, verb, limit) },
+           *chains.cycles.map { |policies| loop_finding(policies, limit) }]
+        end
+
+        # @return [Array<Finding>] the deep-chain warning for the verb, and the search warning if
+        #   the walk gave up
+        def chain_findings(chains, verb, limit)
+          chain = chains.from(verb)
+          [(deep_chain_finding(verb, chain, limit) if chain.size > limit),
+           (capped_search_finding(verb, chain) if chains.capped?)].compact
+        end
+
+        # @return [Finding] the warning naming every policy of a loop
+        def loop_finding(policies, limit)
+          names = policies.map(&:name)
+          Finding.new(kind: :unbounded_reaction_loop, severity: :warning, subject: names.join(", "),
+                      message: "policies #{names.join(", ")} reach one another, so a command that starts " \
+                               "them reacts until the reaction depth limit of #{limit}, and the " \
+                               "#{limit + 1}th reaction is refused without anyone being told")
+        end
+
+        # @return [Finding] the warning that the chain found for the verb is a lower bound
+        def capped_search_finding(verb, chain)
+          Finding.new(kind: :reaction_chain_search_capped, severity: :warning, subject: verb_text(verb),
+                      message: "the search for the longest chain stopped after " \
+                               "#{ReactionWalk::WORK_LIMIT} steps; the chain of #{chain.size} reactions is a lower bound")
+        end
+
+        # @return [Finding] the warning naming the entry verb and each policy and verb of its chain
+        def deep_chain_finding(verb, chain, limit)
+          path = chain.map { |step| "#{step.policy_name} -> #{verb_text(step.verb)}" }.join(" -> ")
+          Finding.new(kind: :deep_reaction_chain, severity: :warning, subject: verb_text(verb),
+                      message: "starts a chain of #{chain.size} reactions, past the reaction depth " \
+                               "limit of #{limit}: the #{limit + 1}th and any after it are refused: " \
+                               "#{verb_text(verb)} -> #{path}")
+        end
+
+        def verb_text(verb) = "#{verb[0]}::#{verb[1]}.#{verb[2]}"
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/model_check/reaction_walk.rb

@@ -0,0 +1,62 @@
+module Hecks
+  module Bluebook
+    module ModelCheck
+      # The longest chain of reactions a policy starts, counting each policy once per chain. A
+      # policy that reaches no loop has one longest chain whatever path led to it, so those are
+      # remembered; the rest are searched path by path, and the search stops after `WORK_LIMIT`
+      # steps per chain, which `capped?` reports.
+      class ReactionWalk
+        # Policies visited by one search before it gives up and answers the best chain so far.
+        WORK_LIMIT = 10_000
+
+        # @param graph [ReactionChains] answers `step(policy)` and `successors(policy)`
+        # @param looping [Array] the policies that lie on a loop
+        def initialize(graph, looping)
+          @graph   = graph
+          @looping = looping.to_set
+          @settled = {}
+          @reaches = {}
+          @work    = 0
+        end
+
+        # @param starts [Array] the policies the first event reaches
+        # @return [Array<ReactionChains::Step>] the longest chain, in order
+        def longest(starts)
+          @work = 0
+          @capped = false
+          starts.map { |policy| search(policy, []) }.max_by(&:size) || []
+        end
+
+        # @return [Boolean] whether the last `longest` gave up, so its chain is a lower bound
+        def capped? = @capped
+
+        private
+
+        def search(policy, path)
+          return settled(policy) unless reaches_loop?(policy)
+          return give_up if (@work += 1) > WORK_LIMIT
+
+          open = @graph.successors(policy) - path - [policy]
+          [@graph.step(policy)] + (open.map { |next_policy| search(next_policy, [*path, policy]) }.max_by(&:size) || [])
+        end
+
+        def give_up
+          @capped = true
+          []
+        end
+
+        def settled(policy)
+          @settled[policy] ||= [@graph.step(policy)] +
+                               (@graph.successors(policy).map { |next_policy| settled(next_policy) }.max_by(&:size) || [])
+        end
+
+        def reaches_loop?(policy)
+          @reaches.fetch(policy) do
+            onward = @graph.successors(policy)
+            @reaches[policy] = @looping.include?(policy) || onward.any? { |next_policy| reaches_loop?(next_policy) }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/model_check/redundant_relationships.rb

@@ -0,0 +1,38 @@
+module Hecks
+  module Bluebook
+    module ModelCheck
+      # The check that a declared relationship says something its context's wiring does not already
+      # (ADR 0155). An `attaches` makes the attaching context a conformist of the attached one, so a
+      # bare conformist line that only an attach explains is dropped from the map.
+      module RedundantRelationships
+        # An `attaches` already says the attaching context conforms to the attached one (ADR 0155),
+        # so a plain conformist relationship that only the attach explains states nothing new.
+        #
+        # @return [Array<Finding>] one warning per such relationship
+        def redundant_relationship_findings(map, edges)
+          map.relationships.filter_map do |relationship|
+            next unless restates_attach?(relationship, edges)
+            next if relationship.acknowledges?(:redundant_relationship)
+
+            Finding.new(kind: :redundant_relationship, severity: :warning,
+                        subject: "#{relationship.downstream} <- #{relationship.upstream}",
+                        message: "the attach already makes #{relationship.downstream} a conformist of " \
+                                 "#{relationship.upstream}; drop this line")
+          end
+        end
+
+        # @return [Boolean] whether the relationship is a bare conformist that attaches alone explain
+        def restates_attach?(relationship, edges)
+          return false unless relationship.kind == :conformist && relationship.published.to_a.empty?
+
+          between = edges.select { |edge| [edge[:from], edge[:to]].sort == relationship.pair }
+          between.any? && between.all? { |edge| attach_from?(edge, relationship) }
+        end
+
+        def attach_from?(edge, relationship)
+          edge[:kind] == ContextMap::ATTACH && edge[:from] == relationship.downstream
+        end
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/model_check/reference_checks.rb

@@ -7,10 +7,19 @@ module Hecks
         # Types that name no aggregate's identity, however many aggregates declare one of them.
         PRIMITIVE_TYPES = %w[String Integer Float Boolean Date DateTime Time Symbol JSON Hash Array].freeze
 
+        # Every check over how aggregates relate: a link copied by value, a reference that outlives
+        # the record it names (OrphanChecks), and a branch on a tagged reference (OneOfChecks).
+        #
+        # @param bluebook [Bluebook::Declaration] the assembled bluebook to check
+        # @return [Array<Finding>] the three checks' findings, in that order
+        def reference_findings(bluebook)
+          [*key_by_value_findings(bluebook), *orphan_findings(bluebook), *one_of_branch_findings(bluebook)]
+        end
+
         # Flags each scalar attribute whose type is the identity type of another aggregate in
         # this domain and that is not itself a reference: the link exists only by convention.
         #
-        # @param bluebook [Bluebook::Chapter] the assembled chapter to check
+        # @param bluebook [Bluebook::Declaration] the assembled bluebook to check
         # @return [Array<Finding>] one :key_by_value warning per such attribute
         def key_by_value_findings(bluebook)
           owners = identity_type_owners(bluebook)
@@ -58,6 +67,7 @@ module Hecks
 
           target = (owners.fetch(attribute.type.to_s, []) - [aggregate.hecks_name]).first
           return unless target
+          return if Acknowledgements.held?(aggregate, :key_by_value, subject: attribute.name)
 
           Finding.new(kind: :key_by_value, severity: :warning,
                       subject: "#{aggregate.hecks_name}.#{attribute.name}",

data/lib/hecks/bluebook/model_check/saga_checks.rb

@@ -89,8 +89,9 @@ module Hecks
           return [] if process_manager.saga?
 
           handler.dispatches.select(&:compensates).map do |dispatch|
+            compensated = dispatch.compensates
             Finding.new(kind: :unarmed_compensation, severity: :error, subject: process_manager.name,
-                        message: "#{dispatch.command_name} compensates #{dispatch.compensates.command_name}, " \
+                        message: "#{dispatch.command_name} compensates #{compensated.command_name}, " \
                                  "but no handler anywhere in this saga answers a refusal — the " \
                                  "compensation is declared and can never fire")
           end
@@ -98,10 +99,14 @@ module Hecks
 
         # Checks whether a saga's own compensation leaves an unreachable state.
         def dead_compensation_findings(process_manager, reached)
-          return [] unless process_manager.saga? && !reached.include?(process_manager.saga.from_state)
+          return [] unless process_manager.saga?
+
+          saga = process_manager.saga
+          left = saga.from_state
+          return [] if reached.include?(left)
 
           [Finding.new(kind: :dead_compensation, severity: :error, subject: process_manager.name,
-                       message: "the compensation leaves #{process_manager.saga.from_state.inspect}, which no " \
+                       message: "the compensation leaves #{left.inspect}, which no " \
                                 "handler chain ever reaches — a refusal here can never fire it")]
         end
 

data/lib/hecks/bluebook/model_check/verbs.rb

@@ -6,16 +6,16 @@ module Hecks
         # Every bare event name this domain's commands and port operations emit,
         # answer, or refuse — an outbound `asks` port operation has no `.emits`.
         #
-        # @param bluebook [Bluebook::Chapter] the assembled chapter to enumerate
+        # @param bluebook [Bluebook::Declaration] the assembled bluebook to enumerate
         # @return [Array<String>] every bare event name emitted, answered, or refused
         #   across this domain, unique
         def emitted_events(bluebook)
           aggregate_emits = bluebook.aggregates.flat_map do |aggregate|
             command_emits(aggregate) + port_operation_events(aggregate.ports)
           end
-          chapter_emits = port_operation_events(bluebook.ports)
+          bluebook_emits = port_operation_events(bluebook.ports)
 
-          (aggregate_emits + chapter_emits).flatten.compact.uniq
+          (aggregate_emits + bluebook_emits).flatten.compact.uniq
         end
 
         # @return [Array] what each command of the aggregate and of its entities emits
@@ -44,7 +44,7 @@ module Hecks
 
         # Every aggregate-owned port operation's own fully-qualified verb — only an
         # aggregate's own ports are in scope; a policy trigger never names a
-        # chapter-level port directly.
+        # bluebook-level port directly.
         def port_verbs_of(bluebook)
           bluebook.aggregates.flat_map do |aggregate|
             aggregate.ports.flat_map do |port|

data/lib/hecks/bluebook/model_check.rb

@@ -4,8 +4,14 @@ require_relative "model_check/client_profile"
 require_relative "model_check/lifecycle_checks"
 require_relative "model_check/saga_checks"
 require_relative "model_check/policy_checks"
+require_relative "model_check/context_checks"
+require_relative "model_check/context_map_checks"
 require_relative "model_check/ask_checks"
+require_relative "model_check/reaction_depth_checks"
 require_relative "model_check/reference_checks"
+require_relative "model_check/orphan_checks"
+require_relative "model_check/one_of_checks"
+require_relative "model_check/aggregate_checks"
 require_relative "model_check/verbs"
 
 module Hecks
@@ -26,30 +32,35 @@ module Hecks
       # The profiles `call` accepts; `nil` is the default, unprofiled run.
       PROFILES = %i[client].freeze
 
-      # What `call` takes from one corpus scan besides the chapter, and each key's default.
+      # What `call` takes from one corpus scan besides the bluebook, and each key's default.
       CONTEXT_DEFAULTS = {
-        hecksagon: nil, known_domains: nil, global_emitted_events: nil, rust_target: false, strict: false
+        hecksagon: nil, known_domains: nil, global_emitted_events: nil, aggregate_owners: nil,
+        rust_target: false, strict: false
       }.freeze
 
-      extend LifecycleChecks
       extend SagaChecks
       extend PolicyChecks
+      extend ContextChecks
       extend AskChecks
+      extend ReactionDepthChecks
       extend ReferenceChecks
+      extend OrphanChecks
+      extend OneOfChecks
+      extend AggregateChecks
       extend Verbs
 
       module_function
 
       # Runs every static model check over `bluebook` and returns what it finds.
       #
-      # @param bluebook [Bluebook::Chapter] the assembled chapter to check
+      # @param bluebook [Bluebook::Declaration] the assembled bluebook to check
       # @param profile [Symbol, nil] :client adds ClientProfile's error findings
       # @param context [Hash] the rest of what one corpus scan knows, each key optional:
       #   `hecksagon` (this bluebook's own sibling wiring file, if the caller loaded one),
-      #   `known_domains` (every bluebook/hecksagon name booted anywhere in this corpus scan,
-      #   checked to catch a typo'd across/attaches target), `global_emitted_events` (every
-      #   event emitted anywhere in the corpus, checked as a fallback so a translates reaction
-      #   isn't flagged deaf), `rust_target` and `strict` (see `rust_reserved_name_findings`)
+      #   `known_domains` (every bluebook/hecksagon name in the scan, to catch a typo'd across or
+      #   attaches target), `global_emitted_events` (every event emitted in the corpus, so a
+      #   translates reaction isn't flagged deaf), `aggregate_owners` (each aggregate name to the
+      #   contexts declaring it, to find what a translates listens to), `rust_target` and `strict`
       # @return [Array<Finding>] every finding this bluebook triggers
       # @raise [ArgumentError] if profile is neither nil nor :client, or a context key is unknown
       def call(bluebook, profile: nil, **context)
@@ -63,17 +74,28 @@ module Hecks
         findings
       end
 
-      # Lifecycles, sagas, policies and references: what the model says about itself.
+      # Lifecycles, sagas, policies, references and aggregate size: what the model says about
+      # itself.
       def modelled_findings(bluebook, options)
         [
           *bluebook.aggregates.flat_map { |aggregate| aggregate_lifecycle_findings(aggregate) },
-          *key_by_value_findings(bluebook),
+          *reference_findings(bluebook),
+          *aggregate_findings(bluebook),
           *bluebook.process_managers.flat_map { |process_manager| saga_findings(bluebook, process_manager) },
+          *reaction_findings(bluebook, options),
+          *unused_ask_findings(bluebook),
+          *reaction_depth_findings(bluebook)
+        ]
+      end
+
+      # Each policy's own checks, then the context a translates listens to.
+      def reaction_findings(bluebook, options)
+        [
           *bluebook.policies.flat_map do |policy|
             policy_findings(bluebook, policy, options[:hecksagon], options[:known_domains],
                             options[:global_emitted_events])
           end,
-          *unused_ask_findings(bluebook)
+          *translates_source_findings(bluebook, options[:hecksagon], options[:aggregate_owners])
         ]
       end
 
@@ -93,30 +115,6 @@ module Hecks
           aggregate.entities.flat_map { |entity| lifecycle_findings(aggregate, entity) }
       end
 
-      # Flags a query the hecksagon binds to a port's adapter. Only the Ruby runtime asks an
-      # adapter for an answer; a Rust host would find nothing behind the query.
-      #
-      # @param bluebook [Bluebook::Chapter] the assembled chapter, its hecksagon's ports attached
-      # @param rust_target [Boolean] whether this domain has a real Rust target; a domain without
-      #   one is not checked, since nothing but the Ruby runtime serves it
-      # @return [Array<Finding>] one :external_query error per bound query, none off a Rust target
-      def external_query_findings(bluebook, rust_target: false)
-        return [] unless rust_target
-
-        bluebook.aggregates.flat_map do |aggregate|
-          aggregate.ports.flat_map do |port|
-            port.answered_queries.map { |answer| external_query_finding(aggregate, port, answer) }
-          end
-        end
-      end
-
-      def external_query_finding(aggregate, port, answer)
-        Finding.new(kind: :external_query, severity: :error,
-                    subject: "#{aggregate.hecks_name}.#{answer.name}",
-                    message: "the #{port.name} port's adapter answers this query, and only the Ruby " \
-                             "runtime asks an adapter — the Rust host cannot serve it")
-      end
-
       # Flags an aggregate or domain name that collides with a Rust keyword or reserved
       # Cargo key — both become bare module identifiers with no `r#` escape hatch.
       #

data/lib/hecks/bluebook/named_pattern.rb

@@ -14,7 +14,18 @@ module Hecks
         no_whitespace: '^[^ \t\n\r]+$',
         snake_name:    "^[a-z][a-z0-9_]*$",
         git_sha:       "^[0-9a-fA-F]{7,40}$",
-        digits:        "^[0-9]+$"
+        digits:        "^[0-9]+$",
+        identifier:    "^[A-Za-z][A-Za-z0-9_]*$",
+        csv_list:      '^[^ \t\n\r,]+(,[^ \t\n\r,]+)*$',
+        command_ref:   '^[A-Z][A-Za-z0-9]*::[A-Z][A-Za-z0-9]*\.[A-Z][A-Za-z0-9]*$',
+        host_port:     "^[A-Za-z0-9_-]+(:[0-9]+)?$",
+        instance_id:   "^i-[0-9a-f]+$",
+        hostname:      "^[A-Za-z0-9][A-Za-z0-9.-]*$",
+        word_chars:    "^[A-Za-z0-9_]*$",
+        version:       "^[0-9]+[.][0-9]+[.][0-9]+",
+        http_scheme:   "^https?://",
+        capitalized:   "[A-Z][A-Za-z0-9]*",
+        single_line:   '[^\n\r]'
       }.freeze
 
       module_function

data/lib/hecks/bluebook/one_of_union.rb

@@ -0,0 +1,35 @@
+module Hecks
+  module Bluebook
+    # The reading of a tagged reference (`reference_to one_of(A, B), as: :subject`, ADR 0127):
+    # its attribute carries the `one_of` relationship, its type is the tagged value object, and
+    # that value object's `type` admits the closed set of the variants' names.
+    module OneOfUnion
+      # The relationship the attribute of a tagged reference carries.
+      RELATIONSHIP = "one_of".freeze
+
+      module_function
+
+      # @param attribute [Bluebook::Attribute] any attribute
+      # @return [Boolean] whether it is a tagged reference to a closed union
+      def union?(attribute) = attribute.relationship == RELATIONSHIP
+
+      # The tagged references `owner` declares.
+      #
+      # @param owner [Bluebook::Aggregate] the aggregate to read
+      # @return [Array<Bluebook::Attribute>] each attribute carrying the `one_of` relationship
+      def attributes(owner) = Array(owner.attributes).select { |attribute| union?(attribute) }
+
+      # The aggregates a tagged reference may point at, in declared order.
+      #
+      # @param owner [Bluebook::Aggregate] the aggregate declaring `attribute`
+      # @param attribute [Bluebook::Attribute] a tagged reference of `owner`
+      # @return [Array<String>] the variants' aggregate names; empty when the shapes are missing
+      def variants(owner, attribute)
+        tagged = owner.value_object(attribute.type.to_s)
+        admits = tagged&.attribute(:type)&.admits
+        set = admits && owner.value_object(admits.split("::").last)
+        set ? set.members.map { |member| member.to_h[:value].to_s } : []
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/pattern_subset.rb

@@ -6,6 +6,15 @@ module Hecks
     # Which regexes a bluebook `pattern:` may say: only what every engine reads the same way.
     # Backtracking-only and ASCII/Unicode-dependent constructs are refused.
     module PatternSubset
+      # A digit from 1 to 9: what follows a backslash in a numbered backreference.
+      BACKREFERENCE_DIGIT = /[1-9]/
+
+      # One ASCII letter: a character of a POSIX class name such as `alpha`.
+      ASCII_LETTER = /[a-zA-Z]/
+
+      # One ASCII digit.
+      DIGIT = /[0-9]/
+
       module_function
 
       # Returns nil when the pattern is admitted, a Rejection when it is not.
@@ -43,7 +52,7 @@ module Hecks
       end
 
       def escape_refusal(nxt)
-        return :backreference if nxt&.match?(/[1-9]/)
+        return :backreference if nxt&.match?(BACKREFERENCE_DIGIT)
         return :named_backreference if %w[k g].include?(nxt)
 
         :perl_class if %w[d D w W s S].include?(nxt)
@@ -121,7 +130,7 @@ module Hecks
         return false unless chars[index] == "[" && chars[index + 1] == ":"
 
         cursor = index + 2
-        cursor += 1 while chars[cursor]&.match?(/[a-zA-Z]/)
+        cursor += 1 while chars[cursor]&.match?(ASCII_LETTER)
         chars[cursor] == ":" && chars[cursor + 1] == "]"
       end
 
@@ -146,7 +155,7 @@ module Hecks
       end
 
       def skip_digits(chars, cursor)
-        cursor += 1 while chars[cursor]&.match?(/[0-9]/)
+        cursor += 1 while chars[cursor]&.match?(DIGIT)
         cursor
       end
     end