hecks 1.3.0 → 1.5.0

data/lib/hecks/facade/cli_door.rb

@@ -2,7 +2,7 @@ require_relative "../runtime/errors"
 
 module Hecks
   module Facade
-    # THE CLI DOOR — WHERE Facade MEETS A CALLER HOLDING FLAT STRINGS.
+    # **The CLI door** — where Facade meets a caller holding flat strings.
     #
     # `JsonDoor` beside this one translates for a caller holding parsed JSON:
     # String keys, already-nested objects, real Integers. A command line has
@@ -12,7 +12,7 @@ module Hecks
     # So this does the two things that turns into: rebuild the nesting, and
     # give every leaf the type the chapter declared for it.
     #
-    # THE TYPE COMES FROM THE PROJECTION, NEVER FROM THE VALUE. A door that
+    # The type comes from the projection, never from the value. A door that
     # guessed — "99 looks like a number" — would send the Integer 99 for a
     # version string of "99", and be wrong in a way nothing downstream could
     # detect, because both are perfectly good arguments. `Projector::CliProjector`
@@ -21,8 +21,24 @@ module Hecks
     module CliDoor
       module_function
 
+      # Builds a verb's nested, typed argument Hash out of the `name=value` words on a
+      # command line.
+      #
       # `["reference.value=BUG#1", "sequence.value=99"]` against a projected
       # verb spec -> `{ reference: { value: "BUG#1" }, sequence: { value: 99 } }`
+      #
+      # @param spec [Hash{Symbol => Object}] one verb's entry from `Projector::CliProjector`;
+      #   read for `:arguments` and the optional `:legacy_arguments`, each an Array of
+      #   option Hashes with `:path`, `:type` and, for a list, `:list`
+      # @param pairs [Array<String>] the words after the verb, each `path=value`; a path
+      #   may be the short form of a single-field value object (`reference` for
+      #   `reference.value`)
+      # @return [Hash{Symbol => Object}] the arguments nested by path, each leaf cast to
+      #   its declared type and each list option collected into an Array; `{}` for no pairs
+      # @raise [Runtime::NotFound] if a pair has no `=`, or names a path the verb does
+      #   not take
+      # @raise [Runtime::TypeMismatch] if a value cannot be read as the declared Integer
+      #   or Float
       def arguments(spec, pairs)
         # Legacy options are accepted but not printed in help. This lets an
         # existing id=... aggregate invocation cross the new receiver boundary
@@ -46,6 +62,12 @@ module Hecks
         end
       end
 
+      # Cuts one command-line word at its first `=`, so a value may itself contain `=`.
+      #
+      # @param pair [String] one word, such as `"reference.value=BUG#1"`
+      # @return [Array(String, String)] the path and the value; the value is `""` for
+      #   `"name="`
+      # @raise [Runtime::NotFound] if the word contains no `=`
       def split(pair)
         name, value = pair.split("=", 2)
         raise Runtime::NotFound, "#{pair.inspect} is not name=value" if value.nil?
@@ -53,16 +75,32 @@ module Hecks
         [name, value]
       end
 
-      # THE SHORT FORM, FOR THE COMMON CASE. Almost every value object in this
+      # Expands a bare value-object name into the full path of its only field.
+      #
+      # The short form, for the common case. Almost every value object in this
       # corpus has exactly one field, so `reference=BUG#1` is unambiguous and
       # is what anybody types. Expanded only when precisely one option starts
       # with that prefix — two would be a guess, and a guess about which field
       # a caller meant is worse than asking them to say.
+      #
+      # @param path [String] the path as typed, such as `"reference"`
+      # @param options [Hash{String => Hash}] the verb's options keyed by full path
+      # @return [String] the one full path beginning `"#{path}."`, or `path` unchanged when
+      #   none or several do
       def expand(path, options)
         candidates = options.keys.select { |key| key.start_with?("#{path}.") }
         candidates.length == 1 ? candidates.first : path
       end
 
+      # Converts one command-line value to the type the chapter declares for its field.
+      #
+      # @param value [String] the text after the `=`
+      # @param type [String] the declared type name; `"Integer"`, `"Float"` and
+      #   `"Boolean"` are converted, anything else leaves the value a String
+      # @return [Integer, Float, Boolean, String] the typed value; a Boolean is true only
+      #   for `true`, `yes` or `1` in any letter case, and false for every other text
+      # @raise [Runtime::TypeMismatch] if the text does not parse as the declared Integer
+      #   or Float
       def cast(value, type)
         case type
         when "Integer" then Integer(value)
@@ -74,27 +112,36 @@ module Hecks
         raise Runtime::TypeMismatch, "#{value.inspect} is not #{type} — the chapter declares this field as #{type}"
       end
 
-      # A LIST GROWS RATHER THAN OVERWRITES, and getting this wrong is silent.
+      # Adds one element to a list argument, creating the list on first use.
+      #
+      # A list grows rather than overwrites, and getting this wrong is silent.
       #
-      # `tags.value=framework tags.value=model-checker` used to reach `bury`
-      # twice and store the second one alone — no refusal, no warning, one tag
+      # `tags.value=framework tags.value=model-checker` sent through `bury`
+      # twice would store the second one alone — no refusal, no warning, one tag
       # simply gone. That is the failure the interview named first: not the
       # loud kind, the kind where a value is forgotten and the caller has no
       # way to notice.
       #
-      # A LIST OF ONE IS STILL A LIST. `tags.value=flaky` produces
+      # A list of one is still a list. `tags.value=flaky` produces
       # `[{ value: "flaky" }]`, not `{ value: "flaky" }`, because the chapter
       # declared a collection and a caller who sent one element did not
-      # thereby declare a different shape. The old behaviour handed a bare
-      # object to a `list_of` attribute, and everything downstream that walks
+      # thereby declare a different shape. A bare object must never reach a
+      # `list_of` attribute: everything downstream that walks
       # it — a query's `contains`, a projection, the Postgres adapter's own
       # array handling — is entitled to assume it can iterate.
       #
-      # MULTI-FIELD ELEMENTS ARE NOT SUPPORTED HERE, deliberately. A flat
+      # Multi-field elements are not supported here, deliberately. A flat
       # command line has no way to say which `a.x=` goes with which `a.y=`,
       # and inventing an index syntax would be a language nobody asked for.
       # Every list in this corpus is a list of single-field value objects; a
       # richer one is a job for `JsonDoor`, which has real nesting.
+      #
+      # @param hash [Hash{Symbol => Object}] the arguments built so far; mutated in place
+      # @param path [Array<String>] the option's path segments, at least two: the last
+      #   names the element's field, the one before it names the list
+      # @param value [Integer, Float, Boolean, String] the cast value for the new element
+      # @return [Hash{Symbol => Object}] `hash`, with `{ leaf => value }` appended to the
+      #   Array at the list's key
       def append(hash, path, value)
         *branches, leaf = path.map(&:to_sym)
         holder = branches[0..-2].reduce(hash) { |node, key| node[key] ||= {} }
@@ -104,6 +151,13 @@ module Hecks
         hash
       end
 
+      # Sets one value at a nested path, creating each intermediate Hash on the way and
+      # overwriting whatever the leaf already held.
+      #
+      # @param hash [Hash{Symbol => Object}] the arguments built so far; mutated in place
+      # @param path [Array<String>] the option's path segments, outermost first
+      # @param value [Integer, Float, Boolean, String] the cast value to store at the leaf
+      # @return [Hash{Symbol => Object}] `hash`, with the value set under Symbol keys
       def bury(hash, path, value)
         *branches, leaf = path.map(&:to_sym)
         target = branches.reduce(hash) { |node, key| node[key] ||= {} }
@@ -111,6 +165,11 @@ module Hecks
         hash
       end
 
+      # Words the refusal for an argument the verb does not take, listing what it does.
+      #
+      # @param path [String] the path as the caller typed it
+      # @param known [Array<String>] every path the verb accepts, in any order
+      # @return [String] a one-line message naming `path` and the sorted accepted paths
       def unknown(path, known)
         "no argument #{path.inspect} — this verb takes #{known.sort.join(', ')}"
       end

data/lib/hecks/facade/cli_runner.rb

@@ -7,23 +7,44 @@ require_relative "../ports/clock"
 
 module Hecks
   module Facade
-    # THE RUNNER BEHIND A PROJECTED CLI.
+    # The runner behind a projected CLI.
     #
-    # `Projector::CliProjector` answers what a domain's command line LOOKS
+    # `Projector::CliProjector` answers what a domain's command line looks
     # like; this is the twenty lines that parse against it and dispatch. It
     # lives in `lib/` rather than in a `bin/` because more than one front door
     # wants it — `bin/run` for whichever domain you are standing in, `bin/qc`
     # pinned to the QA ledger — and a second copy of the parse-and-dispatch
     # would be the exact duplication the projection exists to avoid.
     #
-    # NO IO. It answers `[text, status]` and never prints or exits, so a spec
+    # No IO. It answers `[text, status]` and never prints or exits, so a spec
     # can call it without capturing streams or trapping SystemExit. The `bin/`
     # scripts do the printing, the same division `Router` and `JsonDoor`
     # already keep against HTTP.
     module CliRunner
       module_function
 
+      # Runs one command line against a booted domain: resolves the verb or question,
+      # parses its `name=value` arguments, dispatches or queries, and answers with the text
+      # to print.
+      #
       # `[text, status]` — status 0 answered, 1 refused or misused.
+      #
+      # Only the first bluebook in the registry (the booted domain's own) is projected
+      # into verbs. `--help`, `-h`, `help` or an empty `argv` answers the usage text; a
+      # verb followed by `--help` answers that verb's help.
+      #
+      # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted domain,
+      #   as `Hecks.boot` returns it
+      # @param argv [Array<String>] the words after the program name: an optional `ask`,
+      #   the verb or question name (bare or aggregate-qualified), then `path=value` pairs
+      # @param program [String] how the caller was invoked, echoed in usage and hints
+      # @return [Array(String, Integer)] the text to print and the exit status: 0 with
+      #   usage, help, or pretty-printed JSON of the outcome; 1 with a message when the
+      #   verb is unknown, an argument is wrong, a record is missing, or the domain refuses
+      # @raise [Runtime::WiringError] if a repository, or the clock adapter a `now`
+      #   argument needs, cannot be resolved
+      # @raise [Runtime::StaleWrite] if concurrent writers beat the command through every
+      #   retry
       def call(runtime:, argv:, program: "bin/run")
         bluebook = runtime.registry.bluebooks.values.first
         cli      = Projector.call(:cli, bluebook: bluebook, options: { program: program })
@@ -31,14 +52,14 @@ module Hecks
         name = argv.first
         return [cli[:usage], 0] if name.nil? || %w[--help -h help].include?(name)
 
-        # `ask` PUTS A QUESTION IN ITS OWN NAMESPACE — a chapter may declare a
+        # `ask` puts a question in its own namespace — a chapter may declare a
         # command and a query of one name, and banking does.
         asking = name == "ask"
         argv   = argv[1..] if asking
         name   = argv.first
         return [cli[:usage], 1] if name.nil?
 
-        # RESOLVED THROUGH THE ALIAS MAP, so `pizzas create_pizza` and
+        # Resolved through the alias map, so `pizzas create_pizza` and
         # `pizzas order.create_pizza` reach the same verb — the aggregate is
         # worth typing only when two of them declare the same word.
         pool = asking ? cli[:questions] : cli[:verbs]
@@ -56,6 +77,26 @@ module Hecks
         dispatch(runtime, spec, name, rest, program, asking)
       end
 
+      # Parses one resolved verb's arguments, runs it as a query or a command, and turns
+      # the outcome, or the domain's refusal, into printable text.
+      #
+      # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted domain
+      # @param spec [Hash{Symbol => Object}] the verb's entry from `Projector::CliProjector`;
+      #   read for `:kind`, `:verb`, `:arguments`, `:receiver` and `:legacy_receiver`
+      # @param name [String] the verb as the caller typed it, echoed in the `--help` hint
+      # @param rest [Array<String>] the `path=value` words after the verb
+      # @param program [String] how the caller was invoked, echoed in the `--help` hint
+      # @param asking [Boolean] whether the verb was reached through `ask`, which only
+      #   changes the wording of the hint
+      # @return [Array(String, Integer)] status 0 with pretty-printed JSON: the materialized
+      #   rows for a query; `id`, `state` and event names for a command; `id` and events
+      #   with payloads for a port operation. Status 1 with the message of a
+      #   `Runtime::DOMAIN_REFUSALS` error, followed by a `--help` hint when it is a
+      #   `Runtime::NotFound` or `Runtime::TypeMismatch`
+      # @raise [Runtime::WiringError] if a repository, or the clock adapter a `now`
+      #   argument needs, cannot be resolved
+      # @raise [Runtime::StaleWrite] if concurrent writers beat the command through every
+      #   retry
       def dispatch(runtime, spec, name, rest, program, asking)
         args = stamp_time(runtime, spec, CliDoor.arguments(spec, rest))
 
@@ -64,34 +105,36 @@ module Hecks
           return [JSON.pretty_generate(rows.map { |row| JsonDoor.materialize(row) }), 0]
         end
 
-        # THE ANSWER IS SCOPED TO WHAT WAS ASKED. `bin/run`'s step-list form
+        # The answer is scoped to what was asked. `bin/run`'s step-list form
         # reports the whole store because a corpus run is judged on all of it;
         # somebody who issued one verb wants that verb's outcome, and against a
         # Postgres-backed domain the full dump is every record there has been.
         request = CommandRequest.normalize(args, receiver:        spec[:receiver],
                                                  legacy_receiver: spec[:legacy_receiver])
-        handle = runtime.dispatch(spec[:verb], **request)
+        handle = runtime.dispatch_flat(spec[:verb], request)
         return [JSON.pretty_generate(answered(handle)), 0] if handle.state.nil?
 
         [JSON.pretty_generate(id:     handle.id,
                               state:  JsonDoor.materialize(handle.state),
                               events: handle.events.map(&:name)), 0]
       rescue Runtime::NotFound, Runtime::TypeMismatch => e
-        # A BAD ARGUMENT AND A MISSING RECORD BOTH LAND HERE, and both want the
+        # A bad argument and a missing record both land here, and both want the
         # same next step: read what the verb actually takes.
         ["#{e.message}\n\n  #{program} #{'ask ' if asking}#{name} --help", 1]
       rescue *Runtime::DOMAIN_REFUSALS => e
-        # THE REFUSAL IS THE PRODUCT — the chapter's own sentence, verbatim.
+        # **The refusal is the product** — the chapter's own sentence, verbatim.
         [e.message, 1]
       end
 
-      # THE CLOCK, FILLED IN AT THE DOOR.
+      # Supplies the current time for a verb that takes a `now` argument the caller left out.
+      #
+      # The clock, filled in at the door.
       #
       # A staleness rule needs the time, and the sublanguage cannot ask for it
       # — a `given` that read the clock would judge the same record differently
       # on two runs, and every replay, audit and fuzz oracle here assumes it
-      # does not. So `now` stays an ARGUMENT the predicate merely reads, and
-      # the question becomes who types it. Before this, the caller did:
+      # does not. So `now` stays an argument the predicate merely reads, and
+      # the question becomes who types it. Left to the caller, that is:
       #
       #   qa/quality_control target.claim id=QC held_by.value=me \
       #     now.value=$(date +%s) window.value=900
@@ -99,20 +142,20 @@ module Hecks
       # which is a shell incantation in front of every claim, and one an agent
       # gets wrong by pasting a stale number.
       #
-      # AT THE DOOR, NOT IN THE RUNTIME, and the distinction is load-bearing.
+      # At the door, not in the runtime, and the distinction is load-bearing.
       # `Ports::IdentityGeneration` reasons the same question through for a
       # minted uuid and lands on "the value is baked into the caller's args at
-      # the first live dispatch". A clock consulted INSIDE the interpreter
+      # the first live dispatch". A clock consulted inside the interpreter
       # would not have that property — a recorded corpus step replayed
       # tomorrow would quietly get tomorrow's time, and the fuzzer's oracle and
       # the adapter-agreement gate both compare runs of exactly that shape. Here
       # it fills only what a person or an agent is typing, and `runtime.dispatch`
       # is left alone.
       #
-      # AN EXPLICIT VALUE ALWAYS WINS, so a spec or a caller reproducing a
+      # An explicit value always wins, so a spec or a caller reproducing a
       # moment says so and is believed. This only supplies what was omitted.
       #
-      # BY NAME, WHICH IS THE ONE UNCOMFORTABLE PART. `now` is a plausible
+      # By name, which is the one uncomfortable part. `now` is a plausible
       # domain word and nothing declares that it means the clock. It is
       # tolerable because this is a convenience layer rather than semantics —
       # the verb's own help says the argument exists, dispatch is unchanged,
@@ -120,6 +163,17 @@ module Hecks
       # declaration in the chapter (`attribute :now, Instant, from: :clock`),
       # which is a language change: DSL, IR, the self-hosted grammar and its
       # goldens. Worth doing; not worth smuggling in here.
+      #
+      # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted domain,
+      #   whose registry names the clock adapter
+      # @param spec [Hash{Symbol => Object}] the verb's projected entry; only an option whose
+      #   `:path` starts `"now."` makes this method act
+      # @param args [Hash{Symbol => Object}] the parsed arguments; not mutated
+      # @return [Hash{Symbol => Object}] `args` itself when the verb takes no `now` or the
+      #   caller gave one; otherwise a copy with `now: { value: seconds }`, the clock port's
+      #   current time in whole seconds
+      # @raise [Runtime::WiringError] if the time is needed and zero or several adapters
+      #   implement the clock port
       def stamp_time(runtime, spec, args)
         return args unless spec[:arguments].any? { |argument| argument[:path].start_with?("now.") }
         return args if args.key?(:now)
@@ -127,12 +181,15 @@ module Hecks
         args.merge(now: { value: Ports::Clock.now(runtime.registry) })
       end
 
-      # A PORT OPERATION HAS NO STATE, AND ITS PAYLOAD IS THE ENTIRE POINT.
+      # Shapes a port operation's outcome for printing: the record asked about, and each
+      # event with its full payload.
+      #
+      # A port operation has no state, and its payload is the entire point.
       #
       # A command answers with the record it changed, so naming the events is
       # enough — the interesting part is in `state`. A port operation changes
       # no record: it asked something outside and came back with what was
-      # said, and that lives ONLY in the event payload. Reporting names alone
+      # said, and that lives only in the event payload. Reporting names alone
       # would print `SpecsCompleted` and drop the spec output on the floor.
       #
       # This is what makes a projected CLI usable as somebody's only door. An
@@ -140,13 +197,19 @@ module Hecks
       # it asks the port and reads the answer, and if the answer is a bare
       # event name then the door leads nowhere and it needs a shell after all.
       #
-      # BOTH ENDINGS COME BACK THE SAME WAY, and the status stays 0 for both.
+      # Both endings come back the same way, and the status stays 0 for both.
       # A refusal here is not a misuse — `IssueStillOpen` and `SuiteFailed`
       # are answers the caller asked for, correctly delivered. Exit 1 is for
       # "you typed something wrong", and conflating the two would have a
       # scripted agent treat a healthy no as a broken call.
+      #
+      # @param handle [Runtime::Dispatcher::Result, Runtime::RemoteDispatcher::Result] the
+      #   dispatch result, which for a port operation has a nil `state`
+      # @return [Hash{Symbol => Object}] `:id`, the result's id or else the first event's
+      #   (nil when there is neither), and `:events`, an Array of `{ name:, payload: }`
+      #   Hashes with each payload materialized to plain data
       def answered(handle)
-        # THE ID COMES OFF THE EVENT, because a port operation hydrates no
+        # The ID comes off the event, because a port operation hydrates no
         # instance and the handle's own `id` is nil by design. The event knows
         # which record was asked about — it was stamped with it — and printing
         # `null` beside a payload that plainly says `SW-TOOL` would read as a
@@ -157,15 +220,27 @@ module Hecks
           end }
       end
 
-      # A NEAR MISS IS WORTH MORE THAN A LIST. Somebody who typed
+      # Words the answer to a verb or question that does not exist, suggesting up to five
+      # names that start the same way.
+      #
+      # A near miss is worth more than a list. Somebody who typed
       # `bug.discovr` wants one line, not eighty-seven of them.
       #
-      # RANKED BY SHARED PREFIX, not by substring. Substring was the first
-      # attempt and it finds nothing for the commonest typo of all — a dropped
+      # Ranked by shared prefix, not by substring. Substring matching finds
+      # nothing for the commonest typo of all — a dropped
       # letter, `order.create_piza`, which is a substring of nothing. Prefix
       # length survives an error anywhere after it, which is where errors are.
+      #
+      # @param cli [Hash{Symbol => Object}] the `Projector::CliProjector` projection; read
+      #   for `cli[:names]`, the alias maps under `:command` and `:question`
+      # @param name [String] what the caller typed
+      # @param asking [Boolean] whether it was typed after `ask`, which picks the question
+      #   names and the wording
+      # @param program [String] how the caller was invoked, echoed in the closing hint
+      # @return [String] a multi-line message; candidates must share a prefix of at least
+      #   half of `name`'s length, and never fewer than three characters
       def unknown(cli, name, asking, program)
-        # BOTH SPELLINGS ARE CANDIDATES. A caller who typed the qualified
+        # **Both spellings are candidates**. A caller who typed the qualified
         # form with a typo — `order.create_piza` — shares no prefix with the
         # short name `create_pizza`, so pooling only one of them suggests
         # nothing for half the mistakes anybody makes.
@@ -181,6 +256,12 @@ module Hecks
         lines.join("\n")
       end
 
+      # Counts how many leading characters two names have in common.
+      #
+      # @param one [String] a candidate name
+      # @param other [String] the name to compare it with
+      # @return [Integer] the length of the common prefix, from 0 up to the shorter
+      #   name's length
       def shared_prefix(one, other)
         length = [one.length, other.length].min
         (0...length).find { |index| one[index] != other[index] } || length

data/lib/hecks/facade/command_request.rb

@@ -16,6 +16,29 @@ module Hecks
     module CommandRequest
       module_function
 
+      # Splits one external request into routing (`to:`) and facts (`with:`), accepting
+      # either the explicit envelope or a flat Hash, and refuses a receiver that does
+      # not fit the kind of command being called.
+      #
+      # Keys are symbolized at every depth first, so a parsed JSON body and a Ruby Hash
+      # are treated alike. In a flat Hash everything but `to` (or the legacy receiver
+      # keys) is a fact.
+      #
+      # @param input [Hash, Object] the request, with String or Symbol keys; anything
+      #   that is not a Hash is refused
+      # @param receiver [Symbol, nil] the kind of receiver the command takes:
+      #   `:aggregate` (an identity), `:entity` (a Hash of `aggregate:` and `entity:`
+      #   identities), or `nil` for a command that takes none, such as a creating command
+      # @param legacy_receiver [Symbol, String, Hash{Symbol => Symbol, String}, nil] where
+      #   a flat request without `to` may carry its receiver instead: one key name (such
+      #   as `:id`) for an `:aggregate` receiver, or `{ aggregate: key, entity: key }` for
+      #   an `:entity` receiver; `nil` accepts no legacy spelling
+      # @return [Hash{Symbol => Object}] `{ with: facts }`, plus `to:` holding the route
+      #   whenever `receiver` is not `nil`; ready to pass to `Dispatcher#dispatch_flat`
+      # @raise [Runtime::TypeMismatch] if `input` or its `with:` is not a Hash, if an
+      #   explicit envelope carries keys other than `to:` and `with:`, or if the route
+      #   is missing, blank, malformed, or given to a command that takes no receiver
+      # @raise [ArgumentError] if `receiver` is not `nil`, `:aggregate` or `:entity`
       def normalize(input, receiver:, legacy_receiver: nil)
         request = symbolize(input)
         raise Runtime::TypeMismatch, "a command request must be a hash" unless request.is_a?(Hash)