hecks 3.9.1 → 3.11.0

data/lib/hecks/adapters/driving/usage_cache.rb

@@ -0,0 +1,144 @@
+require "digest"
+require "fileutils"
+require "json"
+
+module Hecks
+  module Adapters
+    module Driving
+      # Remembers the help a launcher prints, so a repeat `hecks` need not read the domain again.
+      #
+      # The help is a pure function of the domain's declarations and of the gem that projects them,
+      # and reading those is most of what a launcher costs. The answer is kept in a file named for a
+      # digest of everything it depends on (the domain's declaration files, the gem's judging code
+      # and adapters, the hecks and Ruby versions, the environment overlay, the command line and
+      # the program name),
+      # so any edit to one of them is simply a different entry: nothing is ever stale, only unused.
+      # Only an answer that ended well is kept, and any trouble with the cache itself is ignored
+      # and the help is worked out as if it did not exist.
+      #
+      # `HECKS_NO_USAGE_CACHE=1` turns it off; `HECKS_CACHE_DIR` moves it.
+      module UsageCache
+        # The variable that turns the cache off when set to anything but empty or `0`.
+        DISABLE_VARIABLE = "HECKS_NO_USAGE_CACHE".freeze
+        # The variable that names the directory the cache lives in.
+        DIRECTORY_VARIABLE = "HECKS_CACHE_DIR".freeze
+        # The declaration files whose contents shape a help text.
+        DECLARATIONS = "*.{bluebook,world,hecksagon,rb}".freeze
+        # How long an unused entry stays before the next write sweeps it away.
+        KEEP_SECONDS = 14 * 24 * 60 * 60
+
+        module_function
+
+        # Answers the cached help for this command line, or works it out with the block and
+        # remembers it.
+        #
+        # @param runtime [#directory] what `Hecks.describe` answered; anything else bypasses the
+        #   cache
+        # @param argv [Array<String>] the command line
+        # @param program [String] how the caller was invoked
+        # @param audience [String] who the help is for, since the same line reads differently to
+        #   each
+        # @yield works the answer out, loading the domain
+        # @yieldreturn [Array(String, Integer), nil] the text and status; nil if it runs a command
+        # @return [Array(String, Integer), nil] the block's answer, or the remembered one
+        def fetch(runtime, argv, program, audience: "")
+          directory = runtime.respond_to?(:directory) ? runtime.directory : nil
+          return yield unless directory && enabled?
+
+          file = entry_path(directory, argv, program, audience)
+          remembered = file && recall(file)
+          return remembered if remembered
+
+          answer = yield
+          remember(file, answer) if worth_keeping?(file, answer)
+          answer
+        end
+
+        # Whether an answer that ended well can be written to the entry's file.
+        def worth_keeping?(file, answer)
+          file && answer&.last&.zero?
+        end
+
+        # @return [Boolean] whether the cache is on
+        def enabled?
+          off = ENV[DISABLE_VARIABLE].to_s
+          off.empty? || off == "0"
+        end
+
+        # @return [String] the directory entries live in
+        def directory
+          ENV[DIRECTORY_VARIABLE] || File.join(ENV["XDG_CACHE_HOME"] || File.join(Dir.home, ".cache"), "hecks")
+        end
+
+        # The file that holds the answer for this command line, named by what it depends on.
+        #
+        # @return [String, nil] nil when the digest cannot be taken
+        def entry_path(domain, argv, program, audience = "")
+          digest = Digest::SHA256.new
+          key_parts(program, audience, argv).each { |part| digest << part.to_s << "\0" }
+          fingerprint_code(domain, digest)
+          File.join(directory, "usage-#{digest.hexdigest}.json")
+        rescue SystemCallError
+          nil
+        end
+
+        # @return [Array<String>] what the answer depends on besides the files: the gem and Ruby
+        #   series, the environment overlay, the program and audience and the command line
+        def key_parts(program, audience, argv)
+          [Hecks::VERSION, Hecks::Bluebook::MetaValidator::VerdictCache.ruby_series,
+           ENV["HECKS_ENVIRONMENT"].to_s, program, audience, argv.join("\0")]
+        end
+
+        # Feeds the digest every declaration file under `root`: its path below `root` and its bytes,
+        # so a touch or a checkout elsewhere keeps the entry and an edit does not.
+        def fingerprint(root, digest)
+          Dir.glob(File.join(root, "**", DECLARATIONS)).each do |file|
+            digest << file.delete_prefix(root) << "\0" << File.binread(file) << "\0"
+          end
+        end
+
+        # Feeds the digest what shapes a help text: the domain's declarations, the judging trees of
+        # the gem (the same set the verdict cache keys on) and the adapters that render the text. An
+        # edit to the gem's projections, deploy or release code cannot change a help line.
+        def fingerprint_code(domain, digest)
+          fingerprint(domain, digest)
+          digest << Hecks::Bluebook::MetaValidator::VerdictCache.code_digest << "\0"
+          fingerprint(__dir__, digest)
+        end
+
+        # Reads the remembered answer and marks the entry as used, so a sweep keeps what is read.
+        #
+        # @return [Array(String, Integer), nil] the remembered answer, or nil when none can be
+        #   trusted
+        def recall(file)
+          record = JSON.parse(File.read(file))
+          File.utime(nil, nil, file)
+          [record.fetch("text"), record.fetch("status")]
+        rescue SystemCallError, JSON::ParserError, KeyError
+          nil
+        end
+
+        # Writes the answer beside its name and sweeps entries nobody has read for a while.
+        def remember(file, answer)
+          FileUtils.mkdir_p(File.dirname(file))
+          scratch = "#{file}.#{Process.pid}"
+          File.write(scratch, JSON.generate("text" => answer.first, "status" => answer.last))
+          File.rename(scratch, file)
+          sweep(File.dirname(file))
+        rescue SystemCallError
+          nil
+        end
+
+        # Removes the entries older than `KEEP_SECONDS`.
+        def sweep(dir)
+          cutoff = Time.now - KEEP_SECONDS
+          Dir.glob(File.join(dir, "usage-*.json")).each do |entry|
+            File.delete(entry) if File.mtime(entry) < cutoff
+          end
+        rescue SystemCallError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/hecks/{doors.rb → adapters/driving.rb}

@@ -1,6 +1,9 @@
 module Hecks
-  # The class-free public surface, installed per boot by `Runtime::Loader.bind_runtime`.
-  module Doors
+  module Adapters
+    # Driving adapters: how an outside caller reaches in. The Ruby one is the class-free public
+    # surface, installed per boot by `Runtime::Loader.bind_runtime`.
+    module Driving
+    end
   end
 
   # Installs facade constants at top level, replacing only what it installed itself.
@@ -44,7 +47,8 @@ module Hecks
   end
 end
 
-require_relative "doors/handle"
-require_relative "doors/ruby_door"
-require_relative "doors/command_request"
-require_relative "doors/json_door"
+require_relative "driving/admission"
+require_relative "driving/handle"
+require_relative "driving/ruby"
+require_relative "driving/command_request"
+require_relative "driving/json"

data/lib/hecks/behaviors/expectations/boot.rb

@@ -43,7 +43,7 @@ module Hecks
         #   Memory-only-guarded runtime
         # @raise [Malformed] if any aggregate is bound to a non-Memory adapter
         def boot_and_guard(files)
-          runtime = Hecks::Runtime::Loader.boot_files(files, install_doors: false)
+          runtime = Hecks::Runtime::Loader.boot_files(files, install_driving: false)
           guard_memory_only!(runtime)
           runtime
         end

data/lib/hecks/bench/ruby_runner.rb

@@ -35,7 +35,7 @@ module Hecks
       def boot(workload, adapter, schema)
         Hecks::Fuzzing::IsolatedBoot.call(workload.domain_path, adapter: adapter, database: DATABASE,
                                           schema: schema, scratch: { database: DATABASE, schema: schema }) do |copy|
-          yield Hecks.boot(copy, install_doors: false)
+          yield Hecks.boot(copy, install_driving: false)
         end
       end
 

data/lib/hecks/bluebook/ask_resolution.rb

@@ -0,0 +1,130 @@
+require_relative "../naming"
+
+module Hecks
+  module Bluebook
+    # Maps a policy's `ask :name` onto the port operation the hecksagon declared for it.
+    #
+    # The match is by the event's aggregate and the ask's name against that aggregate's declared
+    # `asks`. When one aggregate has the same ask name on two ports, the operation the hecksagon
+    # marked with `ask_via` is the one; otherwise the ask is ambiguous.
+    module AskResolution
+      # One ask's outcome: the verb it resolves to, or why it resolves to none.
+      #
+      # @!attribute [r] verb
+      #   @return [String, nil] `Aggregate::Port.Operation` when resolved, spelled as the
+      #     `trigger Aggregate::Port::Operation` it stands for is
+      # @!attribute [r] problem
+      #   @return [Symbol, nil] `:no_aggregate`, `:unmatched` or `:ambiguous` when not
+      # @!attribute [r] detail
+      #   @return [String, nil] what the refusal says, naming the aggregate and candidates
+      Outcome = Struct.new(:verb, :problem, :detail, keyword_init: true) do
+        # @return [Boolean] whether the ask resolved to one operation
+        def resolved? = problem.nil?
+      end
+
+      module_function
+
+      # Resolves one ask policy against a chapter's aggregates and their declared ports.
+      #
+      # @param chapter [Bluebook::Chapter] the chapter the policy is declared in
+      # @param policy [Bluebook::Policy] a policy that `asks?`
+      # @return [Outcome] the verb, or the problem
+      def call(chapter, policy)
+        aggregate = event_aggregate(chapter, policy)
+        return no_aggregate(policy) unless aggregate
+
+        found = picked(candidates(aggregate, policy.ask))
+        return unmatched(aggregate, policy) if found.empty?
+        return ambiguous(aggregate, policy, found) if found.size > 1
+
+        port, operation = found.first
+        Outcome.new(verb: "#{aggregate.hecks_name}::#{port.name}.#{operation.hecks_name}")
+      end
+
+      # The operations a tie leaves once `ask_via` has spoken: the chosen ones, or all of them
+      # when the hecksagon chose none.
+      #
+      # @return [Array<Array(Bluebook::DomainPort, Bluebook::PortOperation)>]
+      def picked(found)
+        chosen = found.select { |_port, operation| operation.chosen? }
+        found.size > 1 && !chosen.empty? ? chosen : found
+      end
+
+      # Binds every ask policy of a chapter that resolves, leaving the rest for the boot gate and
+      # `model_check` to name.
+      #
+      # @param chapter [Bluebook::Chapter] the chapter whose policies to resolve
+      # @return [void]
+      def bind_resolved(chapter)
+        chapter.policies.select(&:asks?).each do |policy|
+          outcome = call(chapter, policy)
+          policy.resolve_ask!(outcome.verb) if outcome.resolved?
+        end
+      end
+
+      # Marks the named ask on the named port as the one policies reach, for `ask_via`, and
+      # re-binds every ask the pick settles.
+      #
+      # @param chapter [Bluebook::Chapter, nil] the chapter the aggregate belongs to
+      # @param aggregate_name [String] the aggregate declaring the port
+      # @param name [String, Symbol] the ask's declared name
+      # @param port [String, Symbol] the port whose ask is picked
+      # @return [void]
+      # @raise [Bluebook::DSL::Malformed] if no such ask is declared on that port yet
+      def pick!(chapter, aggregate_name, name, port)
+        held = chapter&.aggregate(aggregate_name)&.port(port)
+        operation = held&.operation(name)
+        unless operation
+          raise DSL::Malformed, "#{aggregate_name}.ask_via #{name.to_s.inspect}, port: #{port.to_s.inspect} " \
+                                "names no declared ask — declare the port's `asks` before picking it"
+        end
+
+        operation.choose!
+        bind_resolved(chapter)
+      end
+
+      # The aggregate whose event the policy reacts to: the one the event is qualified with, or
+      # the one whose commands emit it when the event is written bare.
+      #
+      # @return [Bluebook::Aggregate, nil]
+      def event_aggregate(chapter, policy)
+        qualifier = policy.event_qualifier
+        return chapter.aggregate(Naming.demodulise(qualifier)) if qualifier
+
+        chapter.aggregates.find do |aggregate|
+          aggregate.commands.any? { |command| Array(command.emits).include?(policy.event_name) }
+        end
+      end
+
+      # @return [Array<Array(Bluebook::DomainPort, Bluebook::PortOperation)>] each outbound
+      #   operation on the aggregate's ports the ask name spells
+      def candidates(aggregate, ask)
+        aggregate.ports.flat_map do |port|
+          port.operations.select { |op| op.outbound? && Naming.snake(op.hecks_name) == ask.to_s }
+              .map { |operation| [port, operation] }
+        end
+      end
+
+      def no_aggregate(policy)
+        Outcome.new(problem: :no_aggregate,
+                    detail:  "#{policy.name}'s ask #{policy.ask.to_sym.inspect} reacts to " \
+                             "#{policy.on_event.inspect}, whose aggregate this chapter does not declare")
+      end
+
+      def unmatched(aggregate, policy)
+        Outcome.new(problem: :unmatched,
+                    detail:  "#{policy.name}'s ask #{policy.ask.to_sym.inspect} matches no `asks` declared on " \
+                             "#{aggregate.hecks_name} — declare `asks \"#{Naming.pascal(policy.ask)}\"` " \
+                             "on one of its ports in the hecksagon")
+      end
+
+      def ambiguous(aggregate, policy, found)
+        ports = found.map { |port, _operation| port.name.inspect }.join(" and ")
+        Outcome.new(problem: :ambiguous,
+                    detail:  "#{policy.name}'s ask #{policy.ask.to_sym.inspect} is asked on #{ports} of " \
+                             "#{aggregate.hecks_name} — pick one in the hecksagon with " \
+                             "`#{aggregate.hecks_name}.ask_via \"#{Naming.pascal(policy.ask)}\", port: \"...\"`")
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/assembly/aggregate_assembly.rb

@@ -75,7 +75,7 @@ module Hecks
           end
         end
 
-        # Folds `state_field`, `state_start` and `transitions` into the IR's one Lifecycle.
+        # Folds `state_field`, `state_start`, `transitions` and `marks` into the IR's one Lifecycle.
         def lifecycle_of(row)
           declared = row[:lifecycle]
           return nil unless declared
@@ -83,7 +83,8 @@ module Hecks
           Lifecycle.new(
             field:       declared[:field],
             default:     declared[:default],
-            transitions: transitions(Array(declared[:transitions]))
+            transitions: transitions(Array(declared[:transitions])),
+            marks:       marks(Array(declared[:marks]))
           )
         end
 
@@ -97,6 +98,11 @@ module Hecks
               end
         end
 
+        # Regroups the one-row-per-state marks back into `name => states`, in declared order.
+        def marks(rows)
+          rows.group_by { |held| held[:name].to_s }.transform_values { |held| held.map { |row| row[:state].to_s } }
+        end
+
         def from_of(froms)
           return nil         if froms.empty?
           return froms.first if froms.size == 1

data/lib/hecks/bluebook/assembly/contracts/rules.rb

@@ -49,7 +49,7 @@ module Hecks
             # this entity rather than the aggregate's flat state.
             invariants:    [:invariants,    [:each, :invariant]]
           },
-          rows: { transitions: :transition_rows, identified_by: :identity_rows },
+          rows: { transitions: :transition_rows, marks: :mark_rows, identified_by: :identity_rows },
           reads: { identified_by: [:each, :identity_path], attributes: [:each, :shape_field],
                    preconditions: [:each, :rule], invariants: [:each, :rule] },
           derived: {
@@ -57,7 +57,8 @@ module Hecks
             owner:       :parent,
             state_field: [:folded, :lifecycle, :field],
             state_start: [:folded, :lifecycle, :default],
-            transitions: [:folded, :lifecycle, :transitions]
+            transitions: [:folded, :lifecycle, :transitions],
+            marks:       [:folded, :lifecycle, :marks]
           }
         ),
 
@@ -68,6 +69,7 @@ module Hecks
             aggregate:          [:aggregate,       :plain],
             on_event:           [:on_event,        :plain],
             trigger_command:    [:trigger_command, :plain],
+            ask:                [:ask,             :plain],
             target_domain:      [:target_domain,   :plain],
             expect_undelivered: [:expect_undelivered, :plain],
             where:              [:where,           :plain],

data/lib/hecks/bluebook/assembly/contracts/structure.rb

@@ -34,7 +34,8 @@ module Hecks
             projected_fields: [:projected_fields, [:each, :projected_field]],
             provenance:       [:provenance, :plain]
           },
-          rows: { transitions: :transition_rows, value_objects: :value_object_names, identified_by: :identity_rows },
+          rows: { transitions: :transition_rows, marks: :mark_rows, value_objects: :value_object_names,
+                  identified_by: :identity_rows },
           reads: { identified_by: [:each, :identity_path], attributes: [:each_with_id, :attribute],
                    invariants: [:each, :rule], preconditions: [:each, :rule],
                    projected_fields: [:each, :projected_field] },
@@ -43,6 +44,7 @@ module Hecks
             state_field:   [:folded, :lifecycle, :field],
             state_start:   [:folded, :lifecycle, :default],
             transitions:   [:folded, :lifecycle, :transitions],
+            marks:         [:folded, :lifecycle, :marks],
             value_objects: :children
           }
         ),

data/lib/hecks/bluebook/assembly/marks.rb

@@ -110,6 +110,7 @@ module Hecks
           case source[:kind].to_s
           when "argument" then source[:name].to_sym
           when "state"    then StateRef.new(source[:name].to_sym)
+          when "expression" then Computed.new(source[:text])
           else source[:value]
           end
         end

data/lib/hecks/bluebook/attribute.rb

@@ -52,7 +52,7 @@ module Hecks
 
       # A bare constant in a bluebook is a name, even when Ruby has heard of it.
       #
-      # `Doors::RubyDoor` installs aggregate names as top-level constants, which would win
+      # `Adapters::Driving::Ruby` installs aggregate names as top-level constants, which would win
       # over the `const_missing` resolver and silently rebind the attribute. Demodulising
       # spells `:Target` and `QualityControl::Target` the same.
       def spell(type)

data/lib/hecks/bluebook/behaviour/command.rb

@@ -78,15 +78,20 @@ module Hecks
         #
         # @return [Hash{Symbol => Object}] `{kind: "argument", name:}` for a
         #   command argument, `{kind: "state", name:}` for a state
-        #   self-reference, or `{kind: "literal", value:}` for a literal value
+        #   self-reference, `{kind: "expression", text:, ast:}` for a computed value, or
+        #   `{kind: "literal", value:}` for a literal value
         def classified_source
-          if source.is_a?(Symbol)
-            { kind: "argument", name: source.to_s }
-          elsif source.is_a?(StateRef)
-            { kind: "state", name: source.name.to_s }
-          else
-            { kind: "literal", value: source }
-          end
+          return { kind: "argument", name: source.to_s } if source.is_a?(Symbol)
+          return { kind: "state", name: source.name.to_s } if source.is_a?(StateRef)
+          return computed_source if source.is_a?(Computed)
+
+          { kind: "literal", value: source }
+        end
+
+        # A computed value on the wire: its canonical text, and the AST the Rust side reads.
+        def computed_source
+          tree = Expression::Resolver.parse(source.text)
+          { kind: "expression", text: source.text, ast: Expression::AstJson.emit_resolver(tree) }
         end
       end
     end

data/lib/hecks/bluebook/behaviour/policy.rb

@@ -18,6 +18,36 @@ module Hecks
         # @return [String]
         def event_name = Naming.unqualified(@on_event)
 
+        # Whether this policy puts a need to the outside by name rather than triggering a command.
+        #
+        # @return [Boolean]
+        def asks? = !@ask.to_s.empty?
+
+        # What the policy reaches, as a reader names it: the trigger, or the ask while no
+        # hecksagon has bound it to a port operation.
+        #
+        # @return [String]
+        def reaches = @trigger_command.to_s.empty? && asks? ? "ask :#{@ask}" : @trigger_command.to_s
+
+        # Binds an `ask` to the verb the hecksagon's declared ask resolves to, so everything
+        # that reads `trigger_command` reads the port operation the old spelling named.
+        #
+        # @param verb [String] the resolved `Aggregate::Port.Operation`
+        # @return [String] the verb
+        def resolve_ask!(verb) = @trigger_command = verb
+
+        # The wire form: an ask policy carries `ask` where a trigger policy carries
+        # `trigger_command`, and a trigger policy carries no `ask` key at all, so the pinned
+        # shape of every existing policy does not move.
+        #
+        # @return [Hash] the policy's IR
+        def to_h
+          shape = super
+          return shape.except(:ask) unless asks?
+
+          shape.except(:ask).to_h { |key, value| key == :trigger_command ? [:ask, @ask] : [key, value] }
+        end
+
         # Whether `for_each` names a query, turning one reaction into a dispatch per row.
         #
         # @return [Boolean]

data/lib/hecks/bluebook/capabilities/attribute_values.rb

@@ -0,0 +1,72 @@
+module Hecks
+  module Bluebook
+    module Capabilities
+      # Reads the value a capability entry names ("Aggregate.attribute"): whole seconds, text,
+      # or the attribute's own name. Extended onto {Capabilities}, whose singleton methods
+      # these become.
+      module AttributeValues
+        # The whole seconds a duration attribute's `default:` holds: a bare integer, or the
+        # `{ value: N }` fill of a one-field value object (how a bluebook types a number).
+        #
+        # @param default [Object] an attribute's `default:`
+        # @return [Integer, nil] the positive whole seconds, or `nil` when it is not that
+        def duration_seconds(default)
+          seconds = filled_value(default)
+          seconds if seconds.is_a?(Integer) && seconds.positive?
+        end
+
+        # The seconds a `:duration` verb ("Aggregate.attribute") resolves to in `chapter`.
+        #
+        # @param chapter [Bluebook::Chapter] the chapter that declares the aggregate
+        # @param verb [String] the entry, spelled "Aggregate.attribute"
+        # @return [Integer, nil] the positive whole seconds, or `nil` when the verb names no such
+        #   attribute or its default is not whole seconds
+        def duration_of(chapter, verb)
+          duration_seconds(attribute_default(chapter, verb))
+        end
+
+        # The `default:` of the attribute a verb ("Aggregate.attribute") names in `chapter`.
+        #
+        # @param chapter [Bluebook::Chapter] the chapter that declares the aggregate
+        # @param verb [String] the entry, spelled "Aggregate.attribute"
+        # @return [Object, nil] that attribute's `default:`, or `nil` when there is none
+        def attribute_default(chapter, verb)
+          aggregate_name, attribute_name = verb.split(".", 2)
+          chapter.aggregate(aggregate_name)&.attributes&.find { |a| a.name.to_s == attribute_name }&.default
+        end
+
+        # A default's value: the bare value, or the `{ value: x }` fill of a one-field value object.
+        #
+        # @param default [Object] an attribute's `default:`
+        # @return [Object] the bare value
+        def filled_value(default)
+          default.is_a?(Hash) ? default.fetch(:value) { default["value"] } : default
+        end
+
+        # The string a `:text` verb ("Aggregate.attribute") resolves to in `chapter`: the
+        # attribute's `default:`, bare or as the `{ value: "..." }` fill of a one-field value
+        # object (ADR 0099).
+        #
+        # @param chapter [Bluebook::Chapter] the chapter that declares the aggregate
+        # @param verb [String] the entry, spelled "Aggregate.attribute"
+        # @return [String, nil] the non-empty text, or `nil` when the verb names no such attribute
+        #   or its default is not text
+        def text_of(chapter, verb)
+          text = filled_value(attribute_default(chapter, verb))
+          text if text.is_a?(String) && !text.empty?
+        end
+
+        # The attribute name an `:attribute` verb ("Aggregate.attribute") resolves to in `chapter`.
+        #
+        # @param chapter [Bluebook::Chapter] the chapter that declares the aggregate
+        # @param verb [String] the entry, spelled "Aggregate.attribute"
+        # @return [String, nil] the attribute's name, or `nil` when the aggregate lacks it
+        def attribute_of(chapter, verb)
+          aggregate_name, attribute_name = verb.split(".", 2)
+          found = chapter.aggregate(aggregate_name)&.attributes&.any? { |a| a.name.to_s == attribute_name }
+          attribute_name if found
+        end
+      end
+    end
+  end
+end