hecks 3.2.0 → 3.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c79ef6cb53e23b9faa0f452f116af208c659512f00716e47c7f3cdaad3d51e86
-  data.tar.gz: b693ea21f847607ca2964759f9e0cec9dc7c4f8e1ea341b6636e99f8b4b1d294
+  metadata.gz: 288ec2962d96e6d9772c6fd6155d15461f69259cd7f69e107e308a2710fcb668
+  data.tar.gz: e71d1ec056df32604dc6ef8de8cab5069ae998faa74d89acd377d79b217820ed
 SHA512:
-  metadata.gz: 38d1467d95484bcf093d6671982bf5e4edc4fc1be8907d849a88df9b85ab2b9810f88ce9533a9d1d125187fd47c26191fbe3e104e90307ee6fb19b3cffa37546
-  data.tar.gz: 329631cf0d425b281c4a4770318d2956ae95ca7d2e0b12e2e0054bd2f0d72a3310a92d1ce2fa125d5a056c76026c27472230a0710335790267db173ada8e48db
+  metadata.gz: a2586bb29d327f576976c7573236abfde1f60deba2eec7529b13ea34fc1b4ea917abe996fd44076cb76690835fb7089f4d18f38d0693d0aa14da2a106334a1a7
+  data.tar.gz: 1101c11307086a6df1833e6cd7b4fb5fdaa5b0d265b0a4569fa9d4df5d85f27039975f46135dd90619ad69e50d553172eb82d203633177595503f9bbfb67998a

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

@@ -101,6 +101,7 @@ module Hecks
             order_by:       [:order_by,        :order_by],
             limit:          [:limit,           :limit],
             returns:        [:returns,         :plain],
+            needs:          [:needs,           [:each, :need]],
             # Held by the language as an open map, so every one of these reads the
             # same way and a ninth option needs no new field on either side.
             offset:         [:offset,          [:option, :offset]],
@@ -111,7 +112,7 @@ module Hecks
           },
           rows: { wheres: :where_rows, options: :option_rows },
           reads: { attributes: [:each, :shape_field], wheres: [:each, :where_clause],
-                  order_by: [:call, :order_by], limit: [:call, :limit] },
+                  needs: [:each, :need], order_by: [:call, :order_by], limit: [:call, :limit] },
           derived: {
             position:    :walk,
             order_field: [:folded, :order_by, :field],

data/lib/hecks/bluebook/dsl/bootstrap_table.rb

@@ -75,6 +75,7 @@ module Hecks
           ["Query", "where"] => :where_impl,
           ["Query", "order_by"] => :order_by_impl,
           ["Query", "authorize"] => :authorize_impl,
+          ["Query", "needs"] => :needs_impl,
           ["ValueObject", "attribute"] => :attribute_impl,
           ["ValueObject", "one_of"] => :one_of_impl,
           ["ValueObject", "invariant"] => :invariant_impl,

data/lib/hecks/bluebook/dsl/command_builder.rb

@@ -1,4 +1,5 @@
 require_relative "word_gate"
+require_relative "need_word"
 module Hecks
   module Bluebook
     module DSL
@@ -10,6 +11,7 @@ module Hecks
         include AttributeCollector
         include RuleReference
         include WordGate
+        include NeedWord
 
         # Sentinel for "this keyword was never passed" — distinct from Ruby's own
         # nil/false, so `to: false` doesn't get treated as absent.
@@ -67,31 +69,6 @@ module Hecks
         # @return [String] the description as stored
         def goal(value) = @goal = value
 
-        # The outside facts a command may declare it needs, each the name of the attribute the
-        # runtime fills when the caller leaves it out. `now` is the clock port's answer, in epoch
-        # seconds.
-        NEEDABLE_FACTS = %i[now].freeze
-
-        # Declares an outside fact the runtime supplies before any given runs (ADR 0081):
-        # `needs :now` fills the command's own `now` attribute from the clock port when the caller
-        # names none.
-        #
-        # @param fact [Symbol] one of `NEEDABLE_FACTS`
-        # @return [Array<Symbol>] the facts declared so far
-        # @raise [Bluebook::DSL::Malformed] if the fact is not one the runtime can supply, or is
-        #   declared twice
-        def needs_impl(fact)
-          fact = fact.to_sym
-          unless NEEDABLE_FACTS.include?(fact)
-            raise Malformed,
-                  "#{@name} needs :#{fact}, which the runtime cannot supply — it supplies " \
-                  "#{NEEDABLE_FACTS.map { |known| ":#{known}" }.join(', ')}"
-          end
-          raise Malformed, "#{@name} declares needs :#{fact} twice" if @needs.include?(fact)
-
-          @needs << fact
-        end
-
         # Names where a concept adopted from a canonical source came from.
         #
         # @param from [Object] the canonical source, captured exactly as written
@@ -344,20 +321,6 @@ module Hecks
           )
         end
 
-        # A fact is filled into the argument of the same name, so the command declares one.
-        #
-        # @raise [Bluebook::DSL::Malformed] if a needed fact has no attribute to fill
-        def refuse_undeclared_needs!
-          declared = attributes.map { |attribute| attribute.name.to_s }
-          missing  = @needs.reject { |fact| declared.include?(fact.to_s) }
-          return if missing.empty?
-
-          raise Malformed,
-                "#{@name} needs :#{missing.first} but declares no attribute :#{missing.first} " \
-                "for the runtime to fill — add `attribute :#{missing.first}, <type>`"
-        end
-        private :refuse_undeclared_needs!
-
         # Evaluates a `command` block against a fresh builder and returns what it built.
         #
         # @param name [String] the command's name

data/lib/hecks/bluebook/dsl/hecksagon_builder.rb

@@ -57,9 +57,9 @@ module Hecks
           end
         end
 
-        # The release that drops the deprecated spellings of `attaches`; kept in step with
-        # `Hecks::Doors::REMOVAL`, which this file cannot require.
-        REMOVAL = "3.2.0".freeze
+        # The release that drops the deprecated spellings of `attaches`; independent of
+        # `Hecks::Doors::REMOVAL`, which covers the older `Facade` aliases.
+        REMOVAL = "3.4.0".freeze
 
         attr_reader :binds, :subscriptions, :attachments
 

data/lib/hecks/bluebook/dsl/need_word.rb

@@ -0,0 +1,50 @@
+module Hecks
+  module Bluebook
+    module DSL
+      # The `needs` word, shared by the builders of the two declarations that may use it: a
+      # command and a query (ADR 0081). The including builder holds `@name` and `@needs` (an
+      # empty list) and answers `attributes`.
+      module NeedWord
+        # The outside facts a declaration may need, each the name of the attribute the runtime
+        # fills when the caller leaves it out. `now` is the clock port's reading in epoch seconds;
+        # `today` is the day it falls in, whole days since the epoch in UTC.
+        NEEDABLE_FACTS = %i[now today].freeze
+
+        # Declares an outside fact the runtime supplies before any given or filter runs:
+        # `needs :now` fills the declaration's own `now` attribute from the clock port when the
+        # caller names none.
+        #
+        # @param fact [Symbol] one of `NEEDABLE_FACTS`
+        # @return [Array<Symbol>] the facts declared so far
+        # @raise [Bluebook::DSL::Malformed] if the fact is not one the runtime can supply, or is
+        #   declared twice
+        def needs_impl(fact)
+          fact = fact.to_sym
+          unless NEEDABLE_FACTS.include?(fact)
+            raise Malformed,
+                  "#{@name} needs :#{fact}, which the runtime cannot supply — it supplies " \
+                  "#{NEEDABLE_FACTS.map { |known| ":#{known}" }.join(', ')}"
+          end
+          raise Malformed, "#{@name} declares needs :#{fact} twice" if @needs.include?(fact)
+
+          @needs << fact
+        end
+
+        private
+
+        # A fact is filled into the argument of the same name, so the declaration has one.
+        #
+        # @raise [Bluebook::DSL::Malformed] if a needed fact has no attribute to fill
+        def refuse_undeclared_needs!
+          declared = attributes.map { |attribute| attribute.name.to_s }
+          missing  = @needs.reject { |fact| declared.include?(fact.to_s) }
+          return if missing.empty?
+
+          raise Malformed,
+                "#{@name} needs :#{missing.first} but declares no attribute :#{missing.first} " \
+                "for the runtime to fill — add `attribute :#{missing.first}, <type>`"
+        end
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/dsl/query_builder.rb

@@ -1,4 +1,5 @@
 require_relative "word_gate"
+require_relative "need_word"
 module Hecks
   module Bluebook
     module DSL
@@ -14,11 +15,13 @@ module Hecks
         include AttributeCollector
         include QuerySpecification::Common::DSL
         include WordGate
+        include NeedWord
 
         # @param name [String] the query's name, as written after `query`
         def initialize(name)
           @name   = name
           @wheres = []
+          @needs  = []
         end
 
         # Sets the human-readable description shown for this query.
@@ -75,6 +78,7 @@ module Hecks
         #   implements
         def build
           seal_cursor
+          refuse_undeclared_needs!
           Query.new(
             name:           @name,
             description:    @description,
@@ -87,7 +91,8 @@ module Hecks
             authorization:  @authorization,
             null_semantics: @null_semantics,
             inspection:     @inspection,
-            returns:        @returns
+            returns:        @returns,
+            needs:          @needs
           )
         end
 

data/lib/hecks/bluebook/query.rb

@@ -25,14 +25,14 @@ module Hecks
         limit:       one(:limit)
       )
 
-      attr_reader :name, :description, :attributes, :returns
+      attr_reader :name, :description, :attributes, :returns, :needs
 
       # @param null_semantics [QuerySpecification::Common::NullSemantics, nil] defaults to
       #   `NullSemantics.default`
       def initialize(name:, description: nil, attributes: [], wheres: [],
                      order_by: nil, limit: nil, offset: nil, cursor: nil,
                      authorization: nil, null_semantics: nil,
-                     inspection: nil, returns: nil)
+                     inspection: nil, returns: nil, needs: [])
         null_semantics ||= QuerySpecification::Common::NullSemantics.default
         super(wheres: wheres, order_by: order_by, limit: limit, offset: offset, cursor: cursor,
               authorization: authorization,
@@ -42,6 +42,7 @@ module Hecks
         @description = description
         @attributes  = attributes
         @returns     = returns&.to_s
+        @needs       = needs
       end
 
       # The value object a `returns` names, without the `list_of(...)` wrapper.
@@ -55,13 +56,15 @@ module Hecks
       def returns_list? = !@returns.nil? && @returns.start_with?("list_of(")
 
       # `extra_options_to_h` (count, median, group_by, scope_to) stays dynamic; `super` covers the
-      # declared emission. `returns` follows, only when the query declares one, so a query that
-      # returns nothing keeps its wire shape.
+      # declared emission. `returns` and `needs` follow, only when the query declares them, so a
+      # query that returns nothing and needs nothing keeps its wire shape.
       #
       # @return [Hash] the declared emission merged with `extra_options_to_h`, then `returns`
+      #   and `needs`
       def to_h
         shape = super.merge(extra_options_to_h)
-        @returns ? shape.merge(returns: @returns) : shape
+        shape = shape.merge(returns: @returns) if @returns
+        @needs.empty? ? shape : shape.merge(needs: @needs.map { |fact| { fact: fact.to_s } })
       end
     end
   end

data/lib/hecks/cli/check_era.rb

@@ -2,11 +2,9 @@ require_relative "../ports/persistence/plugins/era/expected_era"
 
 module Hecks
   module CLI
-    # The command behind `hecks check_era` and Custodian's `Host.CheckEra`: asks a running host
-    # which era it reports and compares it with an allow-list file. Read-only: one GET, no writes.
+    # The check behind Custodian's `Host.CheckEra`: asks a running host which era it reports and
+    # compares it with an allow-list file. Read-only: one GET, no writes.
     module CheckEra
-      USAGE = "usage: hecks check_era <url> <expected-era-file> [--timeout=<seconds>]".freeze
-
       # What a check found.
       #
       # @!attribute [r] verdict
@@ -14,7 +12,7 @@ module Hecks
       # @!attribute [r] version
       #   @return [String] the gem version the host reports, empty when it reports none
       # @!attribute [r] line
-      #   @return [String] the sentence `hecks check_era` prints for this finding
+      #   @return [String] the sentence the check reports for this finding
       Finding = Struct.new(:verdict, :version, :line)
 
       module_function
@@ -36,35 +34,6 @@ module Hecks
         Finding.new(verdict, document.fetch("version"), sentence(verdict, file))
       end
 
-      # Runs `hecks check_era`: prints the finding and answers the exit status.
-      #
-      # @param argv [Array<String>] the url, the allow-list file and an optional `--timeout=N`
-      # @param out [IO] where a finding goes
-      # @param err [IO] where a refusal goes
-      # @return [Integer] 0 when the era is expected or unlisted, 1 on a mismatch, 2 on bad
-      #   usage or an unreadable file, 3 when the host cannot be reached or answers no era
-      def run(argv, out: $stdout, err: $stderr)
-        timeout = 10
-        args = argv.reject do |arg|
-          next false unless arg.start_with?("--timeout=")
-
-          timeout = arg.delete_prefix("--timeout=").to_f
-          true
-        end
-        url, file = args
-        return usage(err) unless url && file && args.size == 2 && timeout.positive?
-
-        finding = assess(url, file, timeout: timeout)
-        (finding.verdict.ok? ? out : err).puts(finding.line)
-        finding.verdict.ok? ? 0 : 1
-      rescue Errno::ENOENT, Errno::EACCES => e
-        err.puts("cannot read #{file}: #{e.message}")
-        2
-      rescue Runtime::EraCheck::ExpectedEra::Unreachable, Runtime::EraCheck::ExpectedEra::BadResponse => e
-        err.puts("era check failed: #{e.message}")
-        3
-      end
-
       # @param verdict [Runtime::EraCheck::ExpectedEra::Verdict] the comparison
       # @param file [String] the allow-list file, named in the sentence
       # @return [String] the one line that says what the comparison found
@@ -78,11 +47,6 @@ module Hecks
           "host reports era #{verdict.era}, which is not in #{file} (expected: #{verdict.allowed.join(', ')})"
         end
       end
-
-      def usage(err)
-        err.puts(USAGE)
-        2
-      end
     end
   end
 end

data/lib/hecks/cli/interview_draft.rb

@@ -1,5 +1,6 @@
 require_relative "../naming"
 require_relative "domain_stub"
+require_relative "interview_shape"
 
 module Hecks
   module CLI
@@ -20,7 +21,11 @@ module Hecks
 
       # What stands in for a creating command nothing in the interview named.
       STUB_NOTE = "    # TODO: no action that creates was accepted; replace Create with the real one.".freeze
-      private_constant :PATTERN, :STUB_NOTE
+
+      # One accepted thing: what it is called and identified by, its fields, its transitions, the
+      # actions that create it and the others.
+      Shape = Struct.new(:name, :identifier, :type, :fields, :steps, :creating, :rest, keyword_init: true)
+      private_constant :PATTERN, :STUB_NOTE, :Shape
 
       module_function
 
@@ -65,14 +70,21 @@ module Hecks
       #
       # @param interview [Object] the booted record
       # @return [Hash] the plain interview this module takes: `reference`, `subject`, `expert`,
-      #   `exchanges` (`question`, `answer`, `topic`), and `things`, `actions` and `rules`, each a
-      #   finding with its `number`, `source` and `status` and the fields of its kind
+      #   `exchanges` (`question`, `answer`, `topic`), and `things`, `actions`, `rules`,
+      #   `fields` and `transitions`, each a finding with its `number`, `source` and `status`
+      #   and the fields of its kind
       def from_record(interview)
         { reference: plain(interview.reference), subject: plain(interview.subject), expert: plain(interview.expert),
           exchanges: interview.exchanges.map { |ex| slice(ex, :question, :answer, :topic) },
           things:    interview.thing_findings.map { |f| slice(f, :number, :name, :identifier, :source, :status) },
-          actions:   interview.action_findings.map { |f| slice(f, :number, :name, :thing, :event, :creates, :source, :status) },
-          rules:     interview.rule_findings.map { |f| slice(f, :number, :statement, :source, :status) } }
+          actions:   interview.action_findings.map do |f|
+            slice(f, :number, :name, :thing, :event, :creates, :takes, :by, :source, :status)
+          end,
+          rules:     interview.rule_findings.map { |f| slice(f, :number, :statement, :source, :status) },
+          fields:    interview.field_findings.map { |f| slice(f, :number, :thing, :name, :values, :source, :status) },
+          transitions: interview.transition_findings.map do |f|
+            slice(f, :number, :thing, :action, :to, :from, :source, :status)
+          end }
       end
 
       # @api private
@@ -127,24 +139,48 @@ module Hecks
 
       # @api private
       def aggregate(interview, thing, actions)
+        shape = shape_of(interview, thing, actions)
+        lines = head_lines(interview, thing, shape)
+        lines.concat(command_lines(interview, shape))
+        lines.concat(InterviewShape.lifecycle(shape.steps, shape.creating, shape.rest))
+        (lines << "  end").join("\n")
+      end
+
+      # What one accepted thing is made of: its fields, its actions, and its steps.
+      # @api private
+      def shape_of(interview, thing, actions)
         name = word(thing[:name])
-        field = Naming.snake(word(thing[:identifier]))
-        field_type = identifier_type(name, field)
+        identifier = Naming.snake(word(thing[:identifier]))
         mine = actions.select { |a| word(a[:thing]) == name }
+        steps = accepted(interview, :transitions).select { |s| word(s[:thing]) == name }
+        found = accepted(interview, :fields).select { |f| word(f[:thing]) == name }
+        type = identifier_type(name, identifier)
+        fields = InterviewShape.fields(found, name, identifier, type, lifecycle: !steps.empty?)
         creating = mine.select { |a| a[:creates] }
-        rest = mine - creating
-        lines = ["  # #{source_note(interview, thing)}".rstrip,
-                 "  aggregate #{name.inspect} do",
-                 "    description #{"TODO: describe what a #{name} is.".inspect}", "",
-                 "    identified_by :#{field}", "",
-                 "    attribute :#{field}, #{field_type}", "",
-                 "    value_object #{field_type.inspect} do",
-                 "      attribute :value, String, pattern: #{PATTERN}",
-                 "    end"]
-        creating = [stub_create(name)] if creating.empty?
-        creating.each { |action| lines.concat(creating_command(interview, action, field, field_type)) }
-        rest.each { |action| lines.concat(mutating_command(interview, action, name)) }
-        (lines << "  end").join("\n")
+        Shape.new(name: name, identifier: identifier, type: type, fields: fields, steps: steps,
+                  creating: creating, rest: mine - creating)
+      end
+
+      # The aggregate's opening: its identity, its fields, and the value object of each.
+      # @api private
+      def head_lines(interview, thing, shape)
+        required = shape.creating.flat_map { |action| InterviewShape.takes(action) }
+        ["  # #{source_note(interview, thing)}".rstrip,
+         "  aggregate #{shape.name.inspect} do",
+         "    description #{"TODO: describe what a #{shape.name} is.".inspect}", "",
+         "    identified_by :#{shape.identifier}", "",
+         "    attribute :#{shape.identifier}, #{shape.type}",
+         *InterviewShape.attributes(shape.fields, required), "",
+         "    value_object #{shape.type.inspect} do",
+         "      attribute :value, String, pattern: #{PATTERN}", "    end",
+         *InterviewShape.value_objects(shape.fields)]
+      end
+
+      # @api private
+      def command_lines(interview, shape)
+        creating = shape.creating.empty? ? [stub_create(shape.name)] : shape.creating
+        creating.flat_map { |action| creating_command(interview, action, shape) } +
+          shape.rest.flat_map { |action| mutating_command(interview, action, shape) }
       end
 
       # The creating command nothing in the interview named: a stub, marked for the developer.
@@ -152,19 +188,24 @@ module Hecks
       def stub_create(name) = { name: "Create", event: "#{name}Created", stub: true }
 
       # @api private
-      def creating_command(interview, action, field, field_type)
+      def creating_command(interview, action, shape)
         verb = word(action[:name])
         note = action[:stub] ? STUB_NOTE : "    # #{source_note(interview, action)}"
-        ["", note, "    command #{verb.inspect} do", "      goal #{"TODO: say what #{verb} does".inspect}", "",
-         "      attribute :#{field}, #{field_type}", "", "      emits #{word(action[:event]).inspect}", "    end"]
+        given, unknown = InterviewShape.inputs(action, shape.fields, shape.identifier)
+        ["", note, "    command #{verb.inspect} do", "      goal #{"TODO: say what #{verb} does".inspect}",
+         *InterviewShape.who_lines(action), "", "      attribute :#{shape.identifier}, #{shape.type}",
+         *given.map { |f| "      attribute :#{f[:name]}, #{f[:type]}" }, *InterviewShape.unknown_lines(unknown), "",
+         "      emits #{word(action[:event]).inspect}", "    end"]
       end
 
       # @api private
-      def mutating_command(interview, action, name)
+      def mutating_command(interview, action, shape)
         verb = word(action[:name])
+        given, unknown = InterviewShape.inputs(action, shape.fields, shape.identifier)
         ["", "    # #{source_note(interview, action)}", "    command #{verb.inspect} do",
-         "      goal #{"TODO: say what #{verb} does".inspect}", "", "      reference_to #{name}", "",
-         "      emits #{word(action[:event]).inspect}", "    end"]
+         "      goal #{"TODO: say what #{verb} does".inspect}", *InterviewShape.who_lines(action), "",
+         "      reference_to #{shape.name}", *InterviewShape.input_lines(given), *InterviewShape.unknown_lines(unknown),
+         *InterviewShape.assignment_lines(given), "", "      emits #{word(action[:event]).inspect}", "    end"]
       end
 
       # An action whose thing nobody accepted has nowhere to go; it is kept as a comment, not lost.
@@ -196,10 +237,15 @@ module Hecks
         lines = interview.fetch(:things).map do |f|
           "- Thing #{f[:number]}, #{f[:status]}: **#{f[:name]}**, identified by `#{f[:identifier]}` (exchange #{f[:source]})"
         end
-        lines += interview.fetch(:actions).map do |f|
-          creates = f[:creates] ? ", creates it" : ""
-          "- Action #{f[:number]}, #{f[:status]}: **#{f[:name]}** on #{f[:thing]}, " \
-            "announcing `#{f[:event]}`#{creates} (exchange #{f[:source]})"
+        lines += interview.fetch(:actions).map { |f| action_line(f) }
+        lines += interview.fetch(:fields, []).map do |f|
+          values = f[:values].to_s.strip.empty? ? "" : ", one of #{f[:values]}"
+          "- Field #{f[:number]}, #{f[:status]}: **#{f[:name]}** on #{f[:thing]}#{values} (exchange #{f[:source]})"
+        end
+        lines += interview.fetch(:transitions, []).map do |f|
+          from = f[:from].to_s.strip.empty? ? "" : " from #{f[:from]}"
+          "- Transition #{f[:number]}, #{f[:status]}: **#{f[:action]}** on #{f[:thing]} to #{f[:to]}#{from} " \
+            "(exchange #{f[:source]})"
         end
         lines + interview.fetch(:rules).map do |f|
           "- Rule #{f[:number]}, #{f[:status]}: #{one_line(f[:statement])} (exchange #{f[:source]})"
@@ -207,7 +253,16 @@ module Hecks
       end
 
       # @api private
-      def accepted(interview, kind) = interview.fetch(kind).select { |finding| finding[:status] == ACCEPTED }
+      def action_line(finding)
+        creates = finding[:creates] ? ", creates it" : ""
+        takes = finding[:takes].to_s.strip.empty? ? "" : ", takes #{finding[:takes]}"
+        by = finding[:by].to_s.strip.empty? ? "" : ", by #{finding[:by]}"
+        "- Action #{finding[:number]}, #{finding[:status]}: **#{finding[:name]}** on #{finding[:thing]}, " \
+          "announcing `#{finding[:event]}`#{creates}#{takes}#{by} (exchange #{finding[:source]})"
+      end
+
+      # @api private
+      def accepted(interview, kind) = interview.fetch(kind, []).select { |finding| finding[:status] == ACCEPTED }
 
       # A free-text name as a PascalCase word safe to write into Ruby: `lend a book` is `LendABook`.
       # @api private