hecks 3.4.2 → 3.6.0

data/lib/hecks/projector/cli_projector/command_specs.rb

@@ -0,0 +1,133 @@
+require_relative "../../naming"
+
+module Hecks
+  module Projector
+    module CliProjector
+      # The spec hash of each command, port operation, query and report: what the runner parses
+      # a call against and what `--help` describes.
+      module CommandSpecs
+        # The options that name the record a command acts on, before its own arguments.
+        # `nil` (a creating command) takes none: there is no record yet.
+        # Ports always pass `:aggregate`, since a port is declared on an aggregate.
+        def receiver_options(receiver, aggregate, entity)
+          case receiver
+          when :entity then entity_receiver_options(aggregate, entity)
+          when :aggregate
+            [{ path: "to", type: "String", required: true,
+               note: "id of the #{aggregate.hecks_name} to act on" }]
+          else
+            []
+          end
+        end
+
+        # The two ids that name an entity inside its aggregate.
+        def entity_receiver_options(aggregate, entity)
+          [{ path: "to.aggregate", type: "String", required: true,
+             note: "id of the #{aggregate.hecks_name} holding the #{entity.hecks_name}" },
+           { path: "to.entity", type: "String", required: true,
+             note: "id of the #{entity.hecks_name} to act on" }]
+        end
+
+        # The spec of one command of an aggregate or of one of its entities.
+        def command_spec(bluebook, aggregate, entity, command)
+          receiver = receiver_for(entity, command)
+
+          { command: fqn(bluebook, aggregate, command, entity), kind: :command }
+            .merge(command_facts(aggregate, command))
+            .merge(receiver_facts(receiver))
+            .merge(refusals: refusals(command, entity || aggregate), requirements: requirements(command),
+                   arguments: command_arguments(receiver, aggregate, entity, command))
+        end
+
+        # Who a command acts on: its entity, its aggregate, or nobody (a creating command).
+        def receiver_for(entity, command)
+          return :entity if entity
+
+          command.creates? ? nil : :aggregate
+        end
+
+        # What the command declares about itself, apart from its arguments.
+        def command_facts(aggregate, command)
+          { summary: command.goal, role: command.role, role_gated: !command.role.to_s.empty?,
+            group: aggregate.hecks_name, internal: command.role.to_s == "System",
+            creates: command.creates? }
+        end
+
+        # The receiver entries of a spec. `id=...` is still accepted for aggregate receivers but
+        # hidden from help, which teaches only `to=...`.
+        def receiver_facts(receiver)
+          { receiver: receiver, legacy_receiver: (receiver == :aggregate ? :id : nil),
+            legacy_arguments: receiver == :aggregate ? [{ path: "id", type: "String", required: true }] : [] }
+        end
+
+        # The receiver paths stay in the projected option list so the request is complete;
+        # CommandRequest strips them before building `with:`.
+        def command_arguments(receiver, aggregate, entity, command)
+          holder = entity || aggregate
+          receiver_options(receiver, aggregate, entity) +
+            command.attributes.flat_map { |a| options_for(a, holder, aggregate) }
+        end
+
+        # A port operation reads as a command but reports as a boundary: it creates no
+        # record, and an outbound failure is the other side's sentence, so `refusals` is empty.
+        def port_spec(bluebook, aggregate, port, operation)
+          arguments = receiver_options(:aggregate, aggregate, nil) +
+                      operation.attributes.flat_map { |a| options_for(a, aggregate, aggregate) }
+
+          { command: port_wire_name(bluebook, aggregate, port, operation),
+            kind: :command, creates: false, receiver: :aggregate, refusals: [],
+            # `role:` is help text only; port dispatch never reaches the role check,
+            # so `role_gated` is always false here.
+            role: port_role(aggregate, port, operation),
+            role_gated: false, group: aggregate.hecks_name, internal: true,
+            summary: port_summary(port, operation), arguments: arguments }
+        end
+
+        # `Dispatcher#dispatch` looks the head up as a port, so the wire name is
+        # `Aggregate.Port.Operation`; the launcher name hides the port.
+        def port_wire_name(bluebook, aggregate, port, operation)
+          [fqn(bluebook, aggregate, operation).sub(/\.[^.]+\z/, ""), port.name, operation.hecks_name].join(".")
+        end
+
+        # Who issues a port operation, in the direction it runs.
+        def port_role(aggregate, port, operation)
+          if operation.outbound?
+            "#{aggregate.hecks_name} asking #{port.name}"
+          else
+            "#{port.name} telling #{aggregate.hecks_name}"
+          end
+        end
+
+        # Names both endings of a port operation, since `--help` is where a caller
+        # learns that e.g. a spec run answers `SpecsCompleted` even when the suite is red.
+        def port_summary(port, operation)
+          return "#{port.name} reports it; emits #{operation.emits.join(", ")}" unless operation.outbound?
+
+          "Ask #{port.name} — answers #{operation.answers}, refuses #{operation.refuses}"
+        end
+
+        # The conditions that refuse the command when they hold, in the chapter's own words: a
+        # lifecycle state mismatch and a missing referenced record per `reference_to`.
+        def refusals(command, holder)
+          lifecycle_refusals(command, holder) +
+            command.attributes.select(&:reference?).map { |r| "no #{r.type.target_name} has that #{r.name}" }
+        end
+
+        # The refusal for a lifecycle state the command does not run from, or none.
+        def lifecycle_refusals(command, holder)
+          lifecycle = holder.lifecycle
+          return [] unless lifecycle
+
+          froms = lifecycle.transitions.filter_map do |name, transition|
+            Array(transition.from) if name.to_s == command.hecks_name
+          end.flatten.uniq
+          froms.empty? ? [] : ["#{lifecycle.field} is not #{froms.join(" or ")}"]
+        end
+
+        # The conditions the command needs: each `given` states what must hold, so the command is
+        # refused unless it does.
+        def requirements(command) = command.givens.map(&:description)
+      end
+    end
+  end
+end

data/lib/hecks/projector/cli_projector/listing.rb

@@ -0,0 +1,100 @@
+require_relative "../../naming"
+
+module Hecks
+  module Projector
+    module CliProjector
+      # The command and question lines of the help: grouped under their aggregate, with the
+      # bookkeeping a run records about itself set apart.
+      module Listing
+        # The command or question lines of the help. A domain with more than one aggregate is listed
+        # under a heading per aggregate, so related commands sit together; the heading is the prefix
+        # every call to them carries, so the lines under it leave it out. The bookkeeping a run
+        # records about itself (`internal`: system-role commands and port operations) is left out,
+        # since a person never types them; `all` lists them as names only. A single-aggregate
+        # domain keeps the plain list, each name in full.
+        #
+        # @param notes [Hash{String => String}] a line of prose per aggregate, shown
+        #   under its heading
+        def listing(specs, all: false, notes: {}, &description)
+          shown, internal = specs.values.partition { |spec| !spec[:internal] }
+          lines = listed_rows(shown, notes, &description)
+          lines.concat(internal_lines(internal)) if all && !internal.empty?
+          lines
+        end
+
+        # The rows of one table: one line per spec, under a heading per aggregate when grouped.
+        def listed_rows(shown, notes, &)
+          grouped = shown.map { |spec| spec[:group] }.uniq.length > 1
+          row = row_formatter(shown.to_h { |spec| [spec, entry_name(spec, grouped)] }, &)
+          return shown.map { |spec| row.call(spec, "  ") } unless grouped
+
+          grouped_rows(shown, notes, row)
+        end
+
+        # A lambda that renders one spec at an indent: its name padded to the widest, then its text.
+        def row_formatter(named, &)
+          width = named.values.map(&:length).max.to_i
+          ->(spec, indent) { "#{indent}#{named[spec].ljust(width)}  #{yield(spec)}#{alias_note(spec)}" }
+        end
+
+        # The rows under a heading per aggregate.
+        def grouped_rows(shown, notes, row)
+          shown.group_by { |spec| spec[:group] }.flat_map do |group, members|
+            [*heading_lines(group, notes), *members.map { |spec| row.call(spec, "    ") }]
+          end
+        end
+
+        # The lines that open an aggregate's group: its heading, then its note when it has one.
+        def heading_lines(group, notes)
+          return [] unless group
+
+          ["  #{heading(group)}", *notes[group]&.then { |note| "    #{note}" }]
+        end
+
+        # The aggregate's own name as a heading: the prefix of every call to the lines under it.
+        def heading(group)
+          "#{Naming.snake(group)}:"
+        end
+
+        # A spec's name as listed: under its aggregate's heading the aggregate prefix is left out.
+        # A command the chapter gives a short name (`mcp`) is listed by its real name, so the
+        # heading and the line still spell a call; `alias_note` says the short name.
+        def entry_name(spec, grouped)
+          name = label(spec, real: true)
+          return name unless grouped && spec[:group]
+
+          name.delete_prefix("#{Naming.snake(spec[:group])}.")
+        end
+
+        # " (also: mcp!)" for a spec the chapter gave a short name, else nothing. A short name that
+        # is only the command's own name (`init` for `door.init`) is already in the line.
+        def alias_note(spec)
+          return "" if spec[:short_was].nil? || spec[:short_was].split(".").last == spec[:short]
+
+          " (also: #{label(spec)})"
+        end
+
+        # A command is written with the `!` that marks it; a query without one.
+        # With `real:`, a short name the chapter gave it gives way to the name it was given for.
+        def label(spec, real: false)
+          name = real && spec.key?(:short_was) ? spec[:short_was] : spec[:short]
+          spec[:kind] == :command ? "#{name}!" : name
+        end
+
+        # The internal commands as bare names, wrapped, under one line saying what they are.
+        def internal_lines(specs)
+          lines = ["  internal — what a run records about itself, named here only (`--help` still works):"]
+          line = "   "
+          specs.map { |spec| label(spec) }.each do |name|
+            if line.length + name.length + 1 > 98
+              lines << line
+              line = "   "
+            end
+            line += " #{name}"
+          end
+          lines << line
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projector/cli_projector/option_specs.rb

@@ -0,0 +1,116 @@
+module Hecks
+  module Projector
+    module CliProjector
+      # The options of a command or query: one per leaf field, typed from the declared field
+      # type and carrying its enum, pattern, default and list flag.
+      module OptionSpecs
+        # Flattens an attribute into one option per leaf field. A value object becomes
+        # dotted options (`--commit.value`), recursing into nested value objects so
+        # `{ cents: 1500 }` is never sent as the string "1500".
+        #
+        # @param attribute [Bluebook::Attribute] the field being projected
+        # @param holder [Bluebook::Aggregate, Bluebook::Entity, Class] what declares `attribute`
+        # @param aggregate [Bluebook::Aggregate] the top-level aggregate, kept across recursion
+        # @param prefix [String, nil] the dotted path built so far
+        # @param optional [Boolean, nil] whether an enclosing field already makes this one optional
+        # @return [Array<Hash{Symbol => Object}>] one option spec per leaf field
+        def options_for(attribute, holder, aggregate, prefix = nil, optional = nil)
+          path = [prefix, attribute.name].compact.join(".")
+          optional ||= attribute.optional?
+          return [reference_option(attribute)] if attribute.reference?
+
+          value_object = value_object_for(attribute, holder, aggregate)
+          return with_declared_default([scalar_option(path, attribute, optional)], attribute) unless value_object
+
+          fields = with_declared_default(leaf_options(value_object, aggregate, path, optional), attribute)
+          attribute.list? ? fields.map { |option| repeatable(option) } : fields
+        end
+
+        # One option per field of a value object, recursing into a field that is itself one.
+        #
+        # The list flag rides on each leaf: without it a repeated flag overwrote the
+        # leaf silently, and CliDoor only ever sees a path and a spec.
+        def leaf_options(value_object, aggregate, path, optional)
+          value_object.attributes.flat_map do |field|
+            nested = value_object_for(field, value_object, aggregate)
+            next options_for(field, value_object, aggregate, path, optional) if nested
+
+            scalar_option("#{path}.#{field.name}", field, optional || field.optional?,
+                          enum: closed_members(value_object, field))
+          end
+        end
+
+        # The option marked as one that may be given more than once.
+        def repeatable(option)
+          option.merge(list: true, note: [option[:note], "repeatable"].compact.join("; "))
+        end
+
+        # Shows the default the attribute itself declares (`attribute :runs, Count, default: 30`) on
+        # the leaf it fills: the matching field for a hash default, the lone field for a bare one.
+        # An argument with a default is never required, since the runtime fills it when omitted.
+        #
+        # @param options [Array<Hash{Symbol => Object}>] the attribute's leaf option specs
+        # @param attribute [Object] the attribute, which may declare a default
+        # @return [Array<Hash{Symbol => Object}>] `options`, with the default shown where it lands
+        def with_declared_default(options, attribute)
+          declared = attribute.default if attribute.respond_to?(:default)
+          return options if declared.nil?
+
+          options.map do |option|
+            value = leaf_default(declared, option[:path].split(".").last, options)
+            value.nil? ? option : option.merge(default: value, required: false)
+          end
+        end
+
+        # The part of a declared default that fills the leaf named `leaf`.
+        def leaf_default(declared, leaf, options)
+          return declared.fetch(leaf.to_sym) { declared[leaf] } if declared.is_a?(Hash)
+
+          declared if options.one?
+        end
+
+        # The option of an attribute that references another record, which is given by its id.
+        def reference_option(attribute)
+          { path: attribute.name.to_s, type: "String", required: !attribute.optional?,
+            note: "id of a #{attribute.type.target_name}" }
+        end
+
+        # A `list_of` scalar carries `list: true, words: true`: the launcher reads a comma-separated
+        # value or a repeated name as the list's elements, since the runtime refuses a lone scalar.
+        def scalar_option(path, field, optional, enum: [])
+          option = { path: path, type: field.type.to_s, required: !optional }
+          option.merge!(list: true, words: true, note: "list: comma-separated or repeated") if field.list?
+          option[:enum] = enum unless enum.empty?
+          option.merge!(declared_rules(field))
+        end
+
+        # The pattern and default a field declares, when it declares them.
+        def declared_rules(field)
+          rules = {}
+          rules[:pattern] = field.pattern if field.respond_to?(:pattern) && field.pattern
+          rules[:default] = field.default if field.respond_to?(:default) && !field.default.nil?
+          rules
+        end
+
+        # The values a `one_of` value object's field is closed to, or `[]` for an open one.
+        def closed_members(value_object, field)
+          return [] unless value_object.closed_set?
+
+          value_object.members.filter_map { |member| member[field.name] }.uniq
+        end
+
+        # The `Bluebook::ValueObject` subclass an attribute's type names, searching
+        # `holder` then `aggregate`, or `nil` for a plain scalar.
+        def value_object_for(attribute, holder, aggregate)
+          [holder, aggregate].compact.each do |scope|
+            next unless scope.respond_to?(:value_objects)
+
+            found = scope.value_objects.find { |v| v.hecks_name == attribute.type.to_s }
+            return found if found
+          end
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projector/cli_projector/query_specs.rb

@@ -0,0 +1,67 @@
+module Hecks
+  module Projector
+    module CliProjector
+      # The spec hash of each query and report: the questions a caller reads rather than commands
+      # it issues.
+      module QuerySpecs
+        # A rootless report takes nothing; a rooted one takes the id of the record it
+        # is a view of, under the name the model gave that reference.
+        def report_spec(bluebook, model)
+          arguments =
+            if model.reference_target
+              [{ path: model.reference_name.to_s, type: "String", required: true,
+                 note: "id of the #{model.reference_target} this is a view of" }]
+            else
+              []
+            end
+
+          { command: "#{bluebook.name}.#{model.hecks_name}", kind: :query,
+            summary: model.description, arguments: arguments }
+        end
+
+        # A question that only reads the aggregate's own records back: it returns no document and
+        # filters on nothing but the record's identity ("how one request ended") or its lifecycle
+        # status ("every request that was refused"). Each journaled run has such a pair, which a
+        # person reads through `hecks <command> --wait` rather than asking for by name, so the help
+        # sets them apart with the bookkeeping commands. A query that returns a document, or filters
+        # on anything else, is a real question. Only an aggregate that journals its own runs (it has
+        # system-role commands, the ones `internal` commands are made of) has such a pair: a
+        # release's "every version that was shipped" is a question worth asking by name.
+        def bookkeeping_query?(aggregate, query)
+          return false if query.returns || query.wheres.empty?
+          return false unless journals_own_runs?(aggregate)
+
+          own = own_fields(aggregate)
+          query.wheres.all? { |clause| own.include?(clause.field.to_s) }
+        end
+
+        # Whether the aggregate has system-role commands, the ones that record its own runs.
+        def journals_own_runs?(aggregate)
+          aggregate.commands.any? { |command| command.role.to_s == "System" }
+        end
+
+        # The fields that are the aggregate's own bookkeeping: its identity and its
+        # lifecycle status.
+        def own_fields(aggregate)
+          Array(aggregate.identified_by).map(&:to_s) + [aggregate.lifecycle&.field.to_s]
+        end
+
+        # The spec of one query of an aggregate or of one of its entities.
+        def query_spec(bluebook, aggregate, entity, query)
+          { command: fqn(bluebook, aggregate, query, entity), kind: :query, group: aggregate.hecks_name,
+            internal: entity.nil? && bookkeeping_query?(aggregate, query),
+            summary: query.description, arguments: query_arguments(query, aggregate, entity),
+            returns: query.returns }
+        end
+
+        # The options of the attributes a query declares.
+        def query_arguments(query, aggregate, entity)
+          Array(query.to_h[:attributes]).flat_map do |declared|
+            attribute = query.attributes.find { |a| a.name.to_s == declared[:name].to_s }
+            attribute ? options_for(attribute, entity || aggregate, aggregate) : []
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projector/cli_projector/usage.rb

@@ -0,0 +1,101 @@
+require_relative "../../naming"
+
+module Hecks
+  module Projector
+    module CliProjector
+      # The usage text of a projection: the command and query tables, or one command's help.
+      module Usage
+        # Renders the full command/question table, or one command's `--help` text when
+        # `options[:command]` names one.
+        def usage(bluebook, commands, questions, options)
+          program = options[:program] || "hecks run"
+
+          requested_help(program, commands, questions, options) ||
+            full_usage(bluebook, commands, questions, options, program)
+        end
+
+        # The `--help` text of the command named by `options[:command]`, or `nil` when none is
+        # asked for or the name matches nothing.
+        def requested_help(program, commands, questions, options)
+          only = options[:command]
+          return unless only
+
+          spec = help_spec(only, commands, questions, options[:ask])
+          command_help(program, spec[:short], spec, ask: options[:ask]) if spec
+        end
+
+        # `ask` picks the namespace when both hold the name; without it a
+        # question's `--help` would print the command sharing its name.
+        def help_spec(name, commands, questions, ask)
+          pool = ask ? questions : commands
+          key  = aliases(pool)[name] || (ask ? nil : aliases(questions)[name])
+          pool[key] || questions[key]
+        end
+
+        # The whole help: the two tables, the chapters, then the hints.
+        def full_usage(bluebook, commands, questions, options, program)
+          shown = [CliAudience.without_hidden(commands, options[:hide]),
+                   CliAudience.without_hidden(questions, options[:hide])]
+          [usage_header(bluebook, program),
+           tables(*shown, all: options[:all], notes: aggregate_notes(bluebook)),
+           CliAudience.chapter_lines(program, options[:chapters]),
+           usage_footer(program, shown, options, left_out(commands, questions, shown))].flatten(1).join("\n")
+        end
+
+        # How many commands and queries the audience's `hide` list left out of `shown`.
+        def left_out(commands, questions, shown)
+          commands.size + questions.size - shown.sum(&:size)
+        end
+
+        # The chapter's vision and the two ways to call it.
+        def usage_header(bluebook, program)
+          ["#{bluebook.name} — #{bluebook.vision}", "",
+           "  #{program} <command>! [name=value …]       do something",
+           "  #{program} query <query> [name=value …]    read something", ""]
+        end
+
+        # The pointers after the tables: `--help`, `--all`, `--maintainer` and an example call.
+        def usage_footer(program, shown, options, hidden_count)
+          out = ["", "  #{program} <command> --help       what one command wants, and every way it refuses"]
+          out.concat(all_hint(program, *shown)) unless options[:all]
+          out.concat(CliAudience.maintainer_hint(program, hidden_count))
+          out << "  a command is called with its aggregate — #{example_qualified(shown.first)}"
+        end
+
+        # The commands table then the queries table.
+        def tables(commands, questions, all:, notes:)
+          ["commands:", *listing(commands, all: all, notes: notes) { |spec| spec[:summary] }, "",
+           "queries (nothing here changes anything):",
+           *listing(questions, all: all, notes: notes) { |spec| first_sentence(spec[:summary]) }]
+        end
+
+        # The line saying the internal commands and queries were left out and how to list them,
+        # or no line when there are none.
+        def all_hint(program, commands, questions)
+          hidden = (commands.values + questions.values).count { |spec| spec[:internal] }
+          return [] if hidden.zero?
+
+          ["  #{program} --all                  also list the #{hidden} internal commands and queries"]
+        end
+
+        # The first sentence of each aggregate's description, keyed by aggregate name; an aggregate
+        # with no description has no entry.
+        def aggregate_notes(bluebook)
+          bluebook.aggregates.to_h { |aggregate| [aggregate.hecks_name, first_sentence(aggregate.description)] }
+                  .reject { |_, note| note.empty? }
+        end
+
+        # An example call, `aggregate.command!`, from the first command, or `""` when there is none.
+        def example_qualified(commands)
+          name = commands.keys.first
+          name ? "#{name}!" : ""
+        end
+
+        # The command table wants a query description's first sentence; `--help` prints all.
+        def first_sentence(text)
+          text.to_s.split(/(?<=\.)\s/).first.to_s
+        end
+      end
+    end
+  end
+end