hecks 5.0.0 → 7.0.0

data/lib/hecks/adapters/driving/cli_runner/run_replay.rb

@@ -0,0 +1,118 @@
+module Hecks
+  module Adapters
+    module Driving
+      module CliRunner
+        # Answers a creating command that names a run key the store already holds.
+        #
+        # Where the aggregate persists (SQLite, Postgres), a repeat with the same key and the same
+        # arguments answers the record written first, and a repeat with other arguments is refused:
+        # the key names a different run. Memory holds nothing across processes, so it cannot
+        # answer a repeat; it refuses the key and says which store would answer it.
+        module RunReplay
+          MEMORY = "Memory".freeze
+
+          module_function
+
+          # @param runtime [Runtime::Dispatcher] the booted domain
+          # @param spec [Hash] the command's projected spec
+          # @param args [Hash] the parsed arguments, including `run` when one was given
+          # @return [Array(String, Integer), nil] the answer and its status, or nil when the
+          #   key is not recorded and the command should run
+          def answer(runtime, spec, args)
+            return unless replayable?(runtime, spec, args)
+
+            target = target(runtime, spec)
+            record = target && recorded(target, run_key(args))
+            return unless record
+
+            return memory_refusal(args) if memory?(target)
+
+            same?(record, args) ? [recorded_text(record, args), ExitStatus::ANSWERED] : [different_text(args), ExitStatus::REFUSED]
+          end
+
+          # Whether the command creates a record under a run key the caller gave.
+          def replayable?(runtime, spec, args)
+            spec[:creates] && args.key?(:run) && runtime.respond_to?(:registry)
+          end
+
+          # The registry, domain and aggregate the command writes to, or nil when it has none.
+          def target(runtime, spec)
+            registry = runtime.registry
+            domain = registry.first_domain_name
+            aggregate = registry.bluebook(domain)&.aggregate(spec[:group].to_s)
+            aggregate && { registry: registry, domain: domain, aggregate: aggregate }
+          end
+
+          # Whether the aggregate's authoritative store is Memory.
+          def memory?(target)
+            bind = Ports::Persistence::BindingPolicy.resolve(target[:registry], target[:domain], target[:aggregate])
+            bind.adapter.to_s == MEMORY
+          end
+
+          # The run key's value, whether given bare or as `{ value: }`.
+          def run_key(args)
+            value = args[:run]
+            value.is_a?(Hash) ? value[:value] : value
+          end
+
+          # The stored record of the key, or nil when none is held.
+          def recorded(target, key)
+            registry, domain = target.values_at(:registry, :domain)
+            registry.repository(domain, target[:aggregate]).find(key.to_s)
+          end
+
+          # Whether the stored record holds every argument the repeat gave.
+          def same?(record, args)
+            given(args).all? { |name, value| stored(record, name) == value.to_s }
+          end
+
+          # A stored field as its text: a value object answers its `value` field.
+          def stored(record, name)
+            held = record.state[name.to_sym]
+            (held.is_a?(Hecks::Runtime::Value) ? held[:value] : held).to_s
+          end
+
+          # The arguments that describe the record, without the run key.
+          def given(args)
+            args.except(:run).transform_values { |value| plain(value) }
+          end
+
+          # A value as its text: `{ value: x }` and `{ cents: x }` both answer `x`.
+          def plain(value)
+            return value unless value.is_a?(Hash)
+
+            value.values.first
+          end
+
+          # The first answer's text: the run key, the record it already holds and the ids it named.
+          def recorded_text(record, args)
+            JSON.pretty_generate("id" => run_key(args).to_s, "state" => recorded_state(record), "events" => [],
+                                 "ids" => { "run" => run_key(args).to_s, "id" => record.id.to_s })
+          end
+
+          # The stored fields as text, keyed by name, then the record's id, as the first answer
+          # printed them.
+          def recorded_state(record)
+            fields = record.state.keys.to_h { |name| [name.to_s, stored(record, name)] }
+            fields.merge("id" => record.id.to_s)
+          end
+
+          # The refusal for a key held with other arguments.
+          def different_text(args)
+            "[already_recorded] refused: run #{run_key(args)} is already recorded with other arguments: nothing written"
+          end
+
+          # The refusal for a key held in Memory, which does not remember runs across processes.
+          def memory_refusal(args) = [refusal_text(args), ExitStatus::REFUSED]
+
+          # The text naming Memory and the persisting stores that would answer the repeat.
+          def refusal_text(args)
+            "[memory_store] refused: run #{run_key(args)} is held in Memory, which does not remember runs across " \
+              "processes: nothing written. A persisting store (SQLite or Postgres) answers a repeat " \
+              "with the first outcome."
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/adapters/driving/cli_runner/search_words.rb

@@ -0,0 +1,35 @@
+module Hecks
+  module Adapters
+    module Driving
+      module CliRunner
+        # The launcher word `search`: the commands and queries a word appears in, read from the same
+        # projection the help prints (ADR 0163, step 20). Extended into `CliRunner`.
+        module SearchWords
+          # The answer to `search <word> [--all]`: the commands and queries a word appears in, or
+          # the line saying none does.
+          def search_answer(scope, argv)
+            return unless argv.first == "search"
+
+            word = argv.drop(1).find { |arg| !arg.start_with?("--") }
+            return { answer: ["usage: #{scope[:program]} search <word> [--all]", ExitStatus::USAGE] } unless word
+
+            options = search_options(scope, argv.include?("--all"))
+            lines = Projector::CliProjector.search_lines(scope[:bluebook], scope[:cli][:commands],
+                                                         scope[:cli][:questions], options, word)
+            return { answer: ["no command or query matches #{word}", ExitStatus::REFUSED] } unless lines
+
+            { answer: [lines.join("\n"), ExitStatus::ANSWERED] }
+          end
+
+          # The listing's options for a search: the audience the help shows, or with `--all` the
+          # maintainer's audience and the internal commands too.
+          def search_options(scope, all)
+            return scope[:shown] unless all
+
+            scope[:options].merge(audience(scope[:runtime], scope[:launcher], maintainer: true)).merge(all: true)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/adapters/driving/cli_runner/settling.rb

@@ -6,6 +6,9 @@ module Hecks
       module CliRunner
         # The answer `--wait` gives once every reaction has run. Extended into `CliRunner`.
         module Settling
+          # The `Some::ErrorClass: ` an adapter's failure text opens with.
+          QUALIFIED_CLASS_PREFIX = /\A(\w+::)+\w+: /
+
           # The answer `--wait` gives: the record re-read after every reaction has run, with all its
           # events, and a status of 1 when its lifecycle ended in a failure state, a refused
           # reaction
@@ -18,7 +21,7 @@ module Hecks
           #
           # @return [Array(String, Integer)] the JSON and the status, plus (Array(String, Integer,
           #   String)) why the run failed when it did
-          def settled(runtime, spec, handle, bluebook, launcher, extra) # rubocop:disable Metrics/ParameterLists -- pinned by the callers and specs
+          def settled(runtime, spec, handle, bluebook, launcher, extra, text: false)
             why = reactions_failed(handle)
             return finish(stateless_json(handle, extra), why) if handle.state.nil?
 
@@ -26,7 +29,7 @@ module Hecks
             state     = reread(runtime, bluebook, aggregate, handle) || handle.state
             answer    = settled_answer(handle, state, settled_event_names(runtime, bluebook, aggregate, handle), extra)
             why      += failure_reasons(aggregate, state, launcher)
-            settled_result(answer, LauncherOptions.report?(launcher, spec), why)
+            settled_result(answer, text || LauncherOptions.report?(launcher, spec), why)
           end
 
           # The settled answer as the launcher's report when it prints one, else as JSON.
@@ -55,16 +58,16 @@ module Hecks
           def failure_reasons(aggregate, state, launcher)
             return [] unless LauncherOptions.failed?(aggregate, state, launcher)
 
-            [failure_sentence(aggregate, state, aggregate.lifecycle.field)]
+            [failure_sentence(aggregate, state, aggregate.lifecycle_field)]
           end
 
           # The answer of a command the launcher prints as its report: the text it recorded, with
-          # the status 1 when the run failed, and nothing else.
+          # the status `REFUSED` when the run failed, and nothing else.
           def report_of(state, why)
             text = state[why.empty? ? :output : :refusal]
             text = text[:value] if text.is_a?(Hash)
             text = why.join("\n") if text.to_s.strip.empty?
-            [text.to_s, why.empty? ? 0 : 1]
+            [text.to_s, why.empty? ? ExitStatus::ANSWERED : ExitStatus::REFUSED]
           end
 
           # The sentence for a record that ended in a failure state: the state, then the record's
@@ -77,12 +80,13 @@ module Hecks
             refusal  = refusal[:value] if refusal.is_a?(Hash)
             return sentence if refusal.to_s.strip.empty?
 
-            "#{sentence}: #{refusal.to_s.strip.sub(/\A(\w+::)+\w+: /, "")}"
+            "#{sentence}: #{refusal.to_s.strip.sub(QUALIFIED_CLASS_PREFIX, "")}"
           end
 
-          # The answer and its status: 0 when nothing failed, else 1 with the reasons joined.
+          # The answer and its status: `ANSWERED` when nothing failed, else `REFUSED` with the
+          # reasons joined.
           def finish(text, reasons)
-            reasons.empty? ? [text, 0] : [text, 1, reasons.join("\n")]
+            reasons.empty? ? [text, ExitStatus::ANSWERED] : [text, ExitStatus::REFUSED, reasons.join("\n")]
           end
 
           # What the reactions of the run the handle reports did wrong: each refusal that blocks it
@@ -111,7 +115,8 @@ module Hecks
           def reread(runtime, bluebook, aggregate, handle)
             return unless aggregate && runtime.respond_to?(:registry)
 
-            runtime.registry.repository(bluebook.name, aggregate)&.find(handle.id)&.to_h
+            repository = runtime.repository(bluebook.name, aggregate)
+            repository&.find(handle.id)&.to_h
           end
         end
       end

data/lib/hecks/adapters/driving/cli_runner/streaming.rb

@@ -12,37 +12,38 @@ module Hecks
           # setting lists under `streams`, given `--stream`; `from_now` applies to the first ask
           # only.
           #
-          # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted domain
+          # @param runtime [Runtime::Dispatcher, Adapters::Lambda::RemoteDispatcher] the domain
           # @param argv [Array<String>] as for `call`, with `--stream`
           # @param program [String] how the caller was invoked
           # @param out [IO] where each entry's line goes
           # @param err [IO] where a refusal goes
           # @param max_polls [Integer, nil] stop after this many asks; unbounded when nil
-          # @return [Integer, nil] 0 or 1 for a stream, nil when `call` should run the line
-          def stream(runtime:, argv:, program: "hecks run", out: $stdout, err: $stderr, max_polls: nil) # rubocop:disable Metrics/ParameterLists -- the keyword API is what callers pass
-            plan  = resolve(runtime, argv, program)
+          # @return [Integer, nil] the stream's `ExitStatus`, nil when `call` should run the line
+          def stream(runtime:, argv:, program: "hecks run", out: $stdout, err: $stderr, max_polls: nil)
+            plan  = resolve(runtime, split_verbosity(argv).last, program)
             words = stream_words(plan)
             return unless words
 
             run_stream(runtime, plan[:spec], words, out, max_polls)
           rescue Interrupt, Errno::EPIPE
-            0
+            ExitStatus::ANSWERED
           rescue Runtime::NotFound, Runtime::TypeMismatch => e
-            refuse(err, "#{e.message}\n\n  #{program} #{plan[:name]} --help")
+            refuse(err, "#{e.message}\n\n  #{program} #{plan[:name]} --help", ExitStatus::USAGE)
           rescue *Runtime::DOMAIN_REFUSALS => e
             refuse(err, e.message)
           end
 
-          # Tails the question the line names and answers 0, the status of a stream that ended.
+          # Tails the question the line names and answers `ANSWERED`, the status of a stream that
+          # ended.
           def run_stream(runtime, spec, words, out, max_polls)
             tail(runtime, spec, Cli.arguments(spec, words), out, max_polls)
-            0
+            ExitStatus::ANSWERED
           end
 
-          # Prints a refusal and answers status 1.
-          def refuse(err, text)
+          # Prints a refusal and answers its status, `REFUSED` unless told otherwise.
+          def refuse(err, text, status = ExitStatus::REFUSED)
             err.puts(text)
-            1
+            status
           end
 
           # One ask after another, each from the cursor the last gave.

data/lib/hecks/adapters/driving/cli_runner/suggestions.rb

@@ -2,19 +2,28 @@ module Hecks
   module Adapters
     module Driving
       module CliRunner
-        # Words the answer for a command or question the chapter does not declare. Extended into
+        # Words the answer for a command or question the bluebook does not declare. Extended into
         # `CliRunner`.
         module Suggestions
           # Words the answer for an unknown command or question, suggesting up to five near names.
           # Ranked by shared prefix, which survives a dropped letter where a substring would not.
           def unknown(cli, name, asking, program)
-            near  = near_names(cli, name, asking)
-            lines = ["no such #{asking ? "query" : "command"}: #{name}"]
-            lines += ["", "did you mean:", *near.first(5).map { |candidate| "  #{candidate}" }] unless near.empty?
+            near  = near_names(cli, snake_form(name), asking)
+            lines = ["[unknown_#{asking ? "query" : "command"}] no such #{asking ? "query" : "command"}: #{name}"]
+            shown = near.first(5).map { |candidate| "  #{shown_name(cli, candidate, asking)}" }
+            lines += ["", "did you mean:", *shown] unless near.empty?
             lines += ["", "  #{program}#{" query" if asking}   for the full list"]
             lines.join("\n")
           end
 
+          # A suggested name as the listing prints it, in the bluebook's verb form. A candidate from
+          # the other namespace (a bare name's home) is printed as it is.
+          def shown_name(cli, candidate, asking)
+            specs = asking ? cli[:questions] : cli[:commands]
+            spec  = specs[cli[:names][asking ? :question : :command][candidate]]
+            spec ? Projector::CliProjector.verb_form(spec, candidate) : candidate
+          end
+
           # The names worth suggesting: the bare name's homes first, then the names sharing a
           # prefix.
           def near_names(cli, name, asking)
@@ -29,10 +38,9 @@ module Hecks
 
           # The pool's names that share at least half of `name` (and three letters) as a prefix.
           def similar_names(pool, name)
-            pool.map { |candidate| [shared_prefix(candidate, name), candidate] }
-                .select { |shared, _| shared >= [name.length / 2, 3].max }
-                .sort_by { |shared, candidate| [-shared, candidate] }
-                .map(&:last)
+            scored = pool.map { |candidate| [shared_prefix(candidate, name), candidate] }
+            close = scored.select { |shared, _| shared >= [name.length / 2, 3].max }
+            close.sort_by { |shared, candidate| [-shared, candidate] }.map(&:last)
           end
 
           # The length of the prefix two words share.

data/lib/hecks/adapters/driving/cli_runner/tour_words.rb

@@ -0,0 +1,77 @@
+require "fileutils"
+require "stringio"
+
+module Hecks
+  module Adapters
+    module Driving
+      module CliRunner
+        # The launcher word `tour [dir]` (ADR 0163, plan step 40): writes a sample domain into a new
+        # directory, runs one command against it in memory, and says what to type next. It writes
+        # only into a directory that does not exist yet.
+        module TourWords
+          TOUR_NAME = "Tour".freeze
+          TOUR_COMMAND = %w[Example.create! name=hello].freeze
+          TOUR_DIRECTORY = "hecks-tour".freeze
+
+          # The answer to `tour [dir]`, or nil when the line is not a tour.
+          def tour_answer(scope, argv)
+            return unless argv.first == "tour"
+
+            target = File.expand_path(argv[1] || TOUR_DIRECTORY, Dir.pwd)
+            return { answer: [tour_refusal(target), ExitStatus::REFUSED] } if File.exist?(target)
+
+            write_tour(target)
+            { answer: [tour_report(scope, target), ExitStatus::ANSWERED] }
+          end
+
+          # The reason a tour refuses a directory that already exists.
+          def tour_refusal(target)
+            "tour refused: #{shown_tour(target)} already exists; name a new directory: hecks tour <dir>"
+          end
+
+          # Writes each stub file of the sample domain under `target`.
+          def write_tour(target)
+            require_relative "../../../tools/domain_stub"
+            Tools::DomainStub.files(name: TOUR_NAME).each do |path, text|
+              full = File.join(target, path)
+              FileUtils.mkdir_p(File.dirname(full))
+              File.write(full, text)
+            end
+          end
+
+          # The report of a tour: what was written, the command's result, and the next command.
+          def tour_report(scope, target)
+            shown = shown_tour(target)
+            result = capture_run(target)
+            ran = "ran: #{tour_line(scope, shown, TOUR_COMMAND)}"
+            lines = ["wrote a sample domain in #{shown}/", "", ran, result]
+            lines + ["", "next: #{tour_line(scope, shown, %w[Example.create! name=yourname])}"]
+          end
+
+          # The launcher line that runs `command` (a verb and its arguments) against the domain in
+          # `shown`: `run` is a verb of Operation, not a launcher word.
+          def tour_line(scope, shown, command)
+            verb, *arguments = command
+            given = arguments.map { |argument| "arguments.value=#{argument}" }
+            [scope[:program], "Operation.run!", "subject.value=#{shown}", "verb.value=#{verb}",
+             *given].join(" ")
+          end
+
+          # The command's own answer, from a booted copy of the sample domain. The runner answers
+          # without exiting, unlike the launcher's `run`, so the report can carry the text.
+          def capture_run(target)
+            runtime = Hecks.boot(target, install_driving: false)
+            Assembly.bind_ported_runtime(runtime)
+            text, _status = CliRunner.call(runtime: runtime, argv: TOUR_COMMAND, program: "hecks run #{target}")
+            text.to_s.strip
+          end
+
+          # The directory as the user typed it, relative to where they are, when it is inside.
+          def shown_tour(target)
+            target.delete_prefix("#{Dir.pwd}/")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/adapters/driving/cli_runner/verb_names.rb

@@ -0,0 +1,81 @@
+module Hecks
+  module Adapters
+    module Driving
+      module CliRunner
+        # Reads the spellings a line may give a command or query. The launcher indexes them by the
+        # snake-case `aggregate.verb` the projection prints; the bluebook's own verb form, such as
+        # `Hecks::SendTrain.Board`, reaches the same one. Extended into `CliRunner`.
+        module VerbNames
+          # A realm written before the aggregate: `Hecks::`.
+          REALM = /\A(?:[A-Z]\w*::)+/
+
+          # The spelling notices this process has already printed, keyed by the spelling typed, so each
+          # prints once.
+          NOTED = Set.new
+
+          # The name the projection indexes a typed name under: the name itself when it is one,
+          # else its verb form read into snake case, else the name as typed, for the refusal to
+          # name.
+          #
+          # @param cli [Hash] the projection, holding the `:names` it indexes
+          # @param typed [String] the word typed, without its `!`
+          # @return [String] the indexed name, or `typed` when none matches
+          def canonical_name(cli, typed)
+            [typed, *verb_form_names(typed)].find { |name| indexed?(cli, name) } || typed
+          end
+
+          # Says once, on standard error, that a line used an aggregate's former name and names the
+          # spelling to use. Short-name aliases stay silent.
+          #
+          # @param cli [Hash] the projection
+          # @param typed [String] the word typed, without its `!`
+          # @param name [String] the name the index resolved the word to
+          # @return [void]
+          def note_former_name(cli, typed, name)
+            spec = indexed_spec(cli, name)
+            return unless former_spelling?(spec, typed)
+            return unless NOTED.add?("spelling #{typed}")
+
+            warn "hecks: #{typed} is the former name of #{spec[:command]}; use that spelling (this notice prints once)"
+          end
+
+          # The command or query a name in the index resolves to, or nil.
+          def indexed_spec(cli, name)
+            target = cli[:names][:command][name] || cli[:names][:question][name]
+            cli[:commands][target] || cli[:questions][target]
+          end
+
+          # Whether the word typed begins with the former name of the aggregate its spec belongs to.
+          def former_spelling?(spec, typed)
+            return false unless spec && spec[:formerly]
+
+            snake_form(typed).start_with?("#{Naming.snake(spec[:formerly])}.")
+          end
+
+          # A typed name as the projection spells it, to match what was typed against the names it
+          # indexes: `Hecks::SendTrain.bord` as `send_train.bord`.
+          #
+          # @param typed [String] the word typed, without its `!`
+          # @return [String] the realm dropped and each dotted segment in snake case
+          def snake_form(typed) = snake_segments(typed).join(".")
+
+          private
+
+          # `Hecks::SendTrain.board` as `send_train.board`; a verb that names an entity's command,
+          # `SendTrain.Launcher.Refresh`, also as `send_train.refresh`, the way the projection
+          # exposes it.
+          def verb_form_names(typed)
+            segments = snake_segments(typed)
+            [segments.join("."), [segments.first, segments.last].join(".")].uniq
+          end
+
+          def snake_segments(typed) = typed.sub(REALM, "").split(".").map { |segment| Naming.snake(segment) }
+
+          def indexed?(cli, name)
+            cli[:names][:command].key?(name) || cli[:names][:question].key?(name)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/adapters/driving/cli_runner/verbosity.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Adapters
+    module Driving
+      module CliRunner
+        # The launcher's output levels. `-q` prints only the result and any refusal, so the progress
+        # and the context line are left out. `-v` adds, on standard error, the command that ran, its
+        # checkout and stores, and how long it took. The default prints what the launcher always
+        # printed. The flags are taken from anywhere in the line, and cannot be given together.
+        module Verbosity
+          QUIET_FLAG = "-q"
+          VERBOSE_FLAG = "-v"
+          FLAGS = { QUIET_FLAG => :quiet, VERBOSE_FLAG => :verbose }.freeze
+          CONFLICT = "hecks: -q and -v cannot be given together; give one of them, or neither"
+
+          # Takes the level flags out of a line.
+          #
+          # @param argv [Array<String>] the words the launcher was given
+          # @return [Array(Symbol, Array<String>)] the level (`:quiet`, `:verbose`, `:default`, or
+          #   `:conflict` when both flags came) and the words without the flags
+          def split_verbosity(argv)
+            levels = argv.filter_map { |word| FLAGS[word] }.uniq
+            return [:conflict, argv] if levels.length > 1
+
+            [levels.first || :default, argv.reject { |word| FLAGS.key?(word) }]
+          end
+
+          # Runs a block at one level, and resets the level and the stage progress afterwards.
+          #
+          # @param level [Symbol] `:quiet`, `:verbose` or `:default`
+          # @yield the answer the line gets at that level
+          # @return [Object] the block's value
+          def with_verbosity(level)
+            require_relative "../../../tools/stage_progress"
+            previous = Thread.current[:hecks_verbosity]
+            Thread.current[:hecks_verbosity] = level
+            Tools::StageProgress.quiet = level == :quiet
+            yield
+          ensure
+            Thread.current[:hecks_verbosity] = previous
+            Tools::StageProgress.quiet = previous == :quiet
+          end
+
+          # @return [Symbol] the level the line runs at
+          def verbosity = Thread.current[:hecks_verbosity] || :default
+
+          # @return [Boolean] whether only the result and any refusal are printed
+          def quiet? = verbosity == :quiet
+
+          # @return [Boolean] whether each step's details are printed on standard error
+          def verbose? = verbosity == :verbose
+
+          # The details `-v` adds after a command ran: the command, how long it took, and the
+          # checkout and stores the line ran in.
+          #
+          # @param err [#puts] where the details go
+          # @param name [String] the command or query that ran
+          # @param started [Float] the monotonic clock reading when the line began
+          # @return [void]
+          def verbose_details(err, name, started)
+            elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started
+            err.puts("command #{name}", format("took %.2fs", elapsed), checkout_line)
+          end
+
+          # @return [String] the context line, as `-v` prints it
+          def checkout_line
+            ContextLine.line(directory: Dir.pwd, stores: SettingsReading.new.stores(Dir.pwd),
+                             audience: ContextLine.audience(Dir.pwd))
+          end
+        end
+      end
+    end
+  end
+end