hecks 6.0.0 → 7.0.0

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

@@ -0,0 +1,87 @@
+module Hecks
+  module Projector
+    module CliProjector
+      # `hecks completion <shell>` (ADR 0163, plan step 7): the words a shell completes, read from
+      # the same listing the help prints, and the script that registers them. Nothing here is typed
+      # by hand: a renamed command or a new module reaches the completions with the next projection.
+      module Completion
+        # The shells a completion script is written for. PowerShell is not among them (step 48).
+        SHELLS = %w[bash zsh fish].freeze
+
+        # The words a completion offers: the first word of a line (modules, the everyday names and
+        # the launcher's own words), and per aggregate, its calls with the bang on commands.
+        #
+        # @param bluebook [Bluebook::Declaration] the bluebook whose modules are offered
+        # @param cli [Hash] the projection (`:commands`, `:questions`)
+        # @param options [Hash] the listing's options, which decide the calls shown (`:everyday`)
+        # @return [Hash{Symbol => Object}] `:first` (the words of the first place), `:calls` (the
+        #   calls per aggregate name) and `:all` (every call, for a shell that filters by prefix)
+        def completion_words(bluebook, cli, options)
+          calls = shown_calls(cli, options).group_by { |spec| spec[:group] }
+                                           .transform_values { |specs| specs.map { |spec| label(spec) } }
+          { first: first_words(bluebook, options) + calls.keys.map { |name| "#{name}." },
+            calls: calls, all: calls.values.flatten }
+        end
+
+        # The script a shell sources to complete the words, registered for the program's first word.
+        #
+        # @param shell [String] one of `SHELLS`
+        # @param program [String] the launcher's name, such as `hecks`
+        # @param words [Hash] what `completion_words` returned
+        # @return [String, nil] the script, or nil for a shell this projection does not write
+        def completion_script(shell, program, words)
+          name = program.split.first
+          case shell
+          when "bash" then bash_script(name, words)
+          when "zsh" then zsh_script(name, words)
+          when "fish" then fish_script(name, words)
+          end
+        end
+
+        # The calls the audience is shown, internal ones left out.
+        def shown_calls(cli, options)
+          [cli[:commands], cli[:questions]].flat_map do |table|
+            CliAudience.audience_specs(table, options).values.reject { |spec| spec[:internal] }
+          end
+        end
+
+        # The module names, the everyday names and the launcher's own words.
+        def first_words(bluebook, options)
+          modules = bluebook.modules.map { |row| Naming.snake(row.name) }.uniq
+          modules + Array(options[:everyday]) + %w[search completion help --all --maintainer]
+        end
+
+        # A bash script: a function completing the current word, registered for the program.
+        def bash_script(name, words)
+          fn = "_#{name.tr("^A-Za-z0-9_", "_")}_complete"
+          lines = ["#{fn}() {", %(  local cur="${COMP_WORDS[COMP_CWORD]}"), "  COMPREPLY=()", %(  case "$cur" in)]
+          lines += words[:calls].map { |agg, calls| "    #{agg}.*) #{bash_reply(calls, "$cur")} ;;" }
+          lines += ["    *) #{bash_reply(words[:first], "$cur")} ;;", "  esac", "}", "complete -F #{fn} #{name}"]
+          "#{lines.join("\n")}\n"
+        end
+
+        # The bash assignment offering a list of words that start with the current one.
+        def bash_reply(list, cur)
+          %{COMPREPLY=( $(compgen -W '#{list.join(" ")}' -- "#{cur}") )}
+        end
+
+        # A zsh script: a function offering the same words through `compadd`.
+        def zsh_script(name, words)
+          lines = [
+            "_#{name.tr("^A-Za-z0-9_", "_")}() {", "  local cur=$words[CURRENT]", "  case $cur in"
+          ]
+          lines += words[:calls].map { |agg, calls| "    #{agg}.*) compadd -- #{calls.map { |c| "'#{c}'" }.join(" ")} ;;" }
+          lines += ["    *) compadd -- #{words[:first].map { |w| "'#{w}'" }.join(" ")} ;;", "  esac", "}"]
+          lines << "compdef _#{name.tr("^A-Za-z0-9_", "_")} #{name}"
+          "#{lines.join("\n")}\n"
+        end
+
+        # A fish script: every word offered for the program, fish filtering them by prefix.
+        def fish_script(name, words)
+          offered = (words[:first] + words[:all]).join(" ")
+          "complete -c #{name} -f -a '#{offered}'\n"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,40 @@
+module Hecks
+  module Projector
+    module CliProjector
+      # The lines the help opens with: the commands and queries a person types most, which the
+      # launcher setting names as `everyday`, each line the call to type (ADR 0163).
+      module Everyday
+        # The `everyday` section: a heading, then one row per named command or query the audience
+        # is shown, in the setting's order, each spelled in full. A name the audience is not shown,
+        # or that names nothing, is left out; nothing is listed for a newcomer, whose help lists
+        # only the newcomer commands.
+        #
+        # @param commands [Hash{String => Hash}] the command specs the audience is shown
+        # @param questions [Hash{String => Hash}] the query specs the audience is shown
+        # @param options [Hash] the projection's options; `:everyday` names the lines, `:only`
+        #   marks a newcomer's help
+        # @return [Array<String>] the section's lines, or none
+        def everyday_lines(commands, questions, options)
+          return [] if Array(options[:only]).any?
+
+          specs = Array(options[:everyday]).filter_map { |name| commands[name] || questions[name] }
+          return [] if specs.empty?
+
+          ["everyday:", *everyday_rows(specs), ""]
+        end
+
+        # How much of what a line does fits beside its call on one terminal line.
+        EVERYDAY_TEXT = 72
+
+        # One row per spec: its full call padded to the widest, then the first sentence of what it
+        # does, cut at a word to fit one line.
+        def everyday_rows(specs)
+          row = row_formatter(specs.to_h { |spec| [spec, label(spec, real: true)] }) do |spec|
+            CliAudience.clipped(first_sentence(spec[:summary]), EVERYDAY_TEXT)
+          end
+          specs.map { |spec| row.call(spec, "  ") }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,77 @@
+require "json"
+require_relative "../../naming"
+
+module Hecks
+  module Projector
+    module CliProjector
+      # `hecks --json` and `hecks <module> --json` (ADR 0163, plan step 9): the same entries the
+      # help lists, as JSON, so the MCP door, the docs and scripts read one projection. Each entry
+      # is one command or query, with the call to type and the module it sits under.
+      module JsonListing
+        # The JSON document for the listing: one array of entries, in the order the help lists them.
+        #
+        # @param bluebook [Bluebook::Declaration] the bluebook whose modules name each entry
+        # @param commands [Hash{Symbol => Hash}] the projected command specs
+        # @param questions [Hash{Symbol => Hash}] the projected query specs
+        # @param options [Hash{Symbol => Object}] the listing's options: `:all` includes the
+        #   internal entries; `:module` limits the entries to one module's name; `:everyday` names
+        #   the calls the everyday section lists
+        # @return [String] the JSON text
+        def json_listing(bluebook, commands, questions, options)
+          entries = [commands, questions].flat_map { |specs| json_entries(bluebook, specs, options) }
+          JSON.generate(entries)
+        end
+
+        # The entries of one table the audience is shown, internal ones only with `:all`, and
+        # limited to a module when one is named.
+        def json_entries(bluebook, specs, options)
+          shown = CliAudience.audience_specs(specs, options).reject { |_, spec| hidden?(spec, options) }
+          entries = shown.map { |key, spec| json_entry(bluebook, spec, key, options) }
+          entries.select { |entry| in_requested_module?(entry, options) }
+        end
+
+        # Whether an entry is internal and the listing leaves internal entries out.
+        def hidden?(spec, options)
+          spec[:internal] && !options[:all]
+        end
+
+        # Whether an entry sits in the module the listing was asked for, or in any when none was.
+        def in_requested_module?(entry, options)
+          options[:module].nil? || entry["module"] == Naming.snake(options[:module])
+        end
+
+        # One entry: its call, its qualified name, its verb, its kind, the module and aggregate it
+        # sits under, its description, its audience, and whether it is in the everyday section.
+        def json_entry(bluebook, spec, key, options)
+          call = label(spec)
+          {
+            "call"     => call,
+            "everyday" => Array(options[:everyday]).include?(key),
+            "module"   => group_name(bluebook, spec),
+            **entry_identity(spec),
+            **entry_flags(spec)
+          }
+        end
+
+        # What an entry is called: its call, qualified name, verb, kind and aggregate.
+        def entry_identity(spec)
+          {
+            "name"      => spec[:command],
+            "verb"      => spec[:short].to_s,
+            "kind"      => spec[:kind].to_s,
+            "aggregate" => spec[:group]
+          }
+        end
+
+        # What an entry says about itself: its description, audience and whether it is internal.
+        def entry_flags(spec)
+          {
+            "description" => spec[:summary].to_s,
+            "audience"    => Array(spec[:audience]).map(&:to_s),
+            "internal"    => spec[:internal] ? true : false
+          }
+        end
+      end
+    end
+  end
+end

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

@@ -58,7 +58,7 @@ module Hecks
         end
 
         # A launcher name in the bluebook's verb form: the aggregate as the bluebook spells it, then
-        # the rest of the name (`push_train.board` as `PushTrain.board`). A name that does not start
+        # the rest of the name (`send_train.board` as `SendTrain.board`). A name that does not start
         # with its aggregate, such as a short name a bluebook gave a command, is left as it is.
         def verb_form(spec, name)
           group = spec[:group]

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

@@ -0,0 +1,39 @@
+module Hecks
+  module Projector
+    module CliProjector
+      # The help of one module of a bluebook (ADR 0163): the commands and queries of the
+      # aggregates the module groups, listed under the module's name and vision.
+      module Modules
+        # The module a word names, in the bluebook's own spelling: `deliver` for `Deliver`.
+        #
+        # @param bluebook [Bluebook::Declaration] the bluebook whose modules are searched
+        # @param word [String, nil] a word of the command line
+        # @return [String, nil] the module's name, or nil when the bluebook has none by that word
+        def module_named(bluebook, word)
+          module_names(bluebook).find { |name| Naming.snake(name) == word }
+        end
+
+        # Each module's name once, in declaration order.
+        def module_names(bluebook)
+          bluebook.modules.map(&:name).uniq
+        end
+
+        # The specs of the aggregates `name` groups; every spec when no module is asked for.
+        def in_module(bluebook, specs, name)
+          return specs unless name
+
+          members = bluebook.modules.select { |row| row.name == name }.map(&:aggregate)
+          specs.select { |_, spec| members.include?(spec[:group]) }
+        end
+
+        # A module's heading: its word and its vision, then the two ways to call what it lists.
+        def module_header(bluebook, name, program)
+          vision = bluebook.modules.find { |row| row.name == name }.vision
+          ["#{Naming.snake(name)} — #{vision}", "",
+           "  #{program} <Aggregate.command>! [name=value …]    do something",
+           "  #{program} <Aggregate.query> [name=value …]       read something", ""]
+        end
+      end
+    end
+  end
+end

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

@@ -49,6 +49,7 @@ module Hecks
         # 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,
+            formerly: aggregate.former_name,
             internal: entity.nil? && bookkeeping_query?(aggregate, query),
             summary: query.description, arguments: query_arguments(query, aggregate, entity),
             returns: query.returns }

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

@@ -0,0 +1,58 @@
+module Hecks
+  module Projector
+    module CliProjector
+      # The launcher's rename table: the old command names a bluebook's `launcher` setting lists as
+      # `renamed`, each mapped to the command it became. An old spelling resolves to the new command
+      # and the launcher prints the new spelling once; an entry may also translate old argument names.
+      #
+      # The table resolves through 8.0; its removal is recorded in docs/compatibility.md.
+      module Renames
+        # The old spellings a `renamed` table maps to the commands they became, in the snake form
+        # the name index uses.
+        #
+        # @param commands [Hash{String => Hash}] the projected commands, keyed by snake-form name
+        # @param renamed [Hash{String => String, Hash}, nil] old name to new name, or to a hash
+        #   with `to:` and `arguments:` (old argument name to new)
+        # @return [Hash{Symbol => Hash{String => String}}] `:command` and `:question`, each mapping an
+        #   old spelling to the name it became
+        # @raise [Bluebook::DSL::Malformed] if an entry names no projected command
+        def renamed_aliases(commands, questions, renamed)
+          Hash(renamed).each_with_object({ command: {}, question: {} }) do |(old, target), map|
+            to = renamed_target(target)
+            space = renamed_space(commands, questions, to, old)
+            map[space][old.to_s] = to
+          end
+        end
+
+        # The namespace a renamed name's target belongs to: a command, or a query when no command
+        # has that name.
+        #
+        # @raise [Bluebook::DSL::Malformed] if the target is neither a command nor a query
+        def renamed_space(commands, questions, to, old)
+          return :command if commands.key?(to)
+          return :question if questions.key?(to)
+
+          raise Bluebook::DSL::Malformed, "renamed #{old.inspect} names no command or query"
+        end
+
+        # The argument renames of each old spelling, read by the launcher to translate `old=value`.
+        #
+        # @return [Hash{String => Hash{String => String}}] old spelling to its argument renames
+        def renamed_arguments(renamed)
+          Hash(renamed).each_with_object({}) do |(old, target), map|
+            map[old.to_s] = renamed_entry(target)[:arguments].to_h.transform_keys(&:to_s)
+          end
+        end
+
+        # The new command name an entry names.
+        def renamed_target(target) = renamed_entry(target)[:to].to_s
+
+        # An entry as a hash with symbol keys: a bare string names the command, and a hash gives
+        # `to:` and, optionally, `arguments:`.
+        def renamed_entry(target)
+          target.is_a?(Hash) ? target.transform_keys(&:to_sym) : { to: target }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,74 @@
+module Hecks
+  module Projector
+    module CliProjector
+      # `hecks search <word>` (ADR 0163, plan step 20): the commands and queries whose call or
+      # description holds a word, each as the call to type, grouped by module when the bluebook
+      # declares one and by aggregate otherwise. It reads the listing's own specs and labels, so
+      # a renamed command is found under its new name without a second index.
+      module Search
+        # The lines answering a search, or nil when nothing matches.
+        #
+        # @param bluebook [Bluebook::Declaration] the bluebook whose modules group the hits
+        # @param commands [Hash{Symbol => Hash}] the projected command specs
+        # @param questions [Hash{Symbol => Hash}] the projected query specs
+        # @param options [Hash{Symbol => Object}] the listing's options; `:all` includes the
+        #   internal commands and queries, as `--all` does
+        # @param word [String] the word to find, matched case-insensitively
+        # @return [Array<String>, nil] the lines to print, or nil when no command or query matches
+        def search_lines(bluebook, commands, questions, options, word)
+          hits = [commands, questions].flat_map { |specs| hits_in(specs, options, word.downcase) }
+          return if hits.empty?
+
+          ranked_lines(bluebook, hits)
+        end
+
+        # The hits in rank order, name matches first, each rank under its module or aggregate.
+        def ranked_lines(bluebook, hits)
+          width = hits.map { |hit| label(hit[:spec]).length }.max
+          hits.sort_by { |hit| [hit[:rank], label(hit[:spec])] }
+              .partition { |hit| hit[:rank].zero? }
+              .flat_map { |part| grouped_lines(bluebook, part, width) }
+        end
+
+        # The hits of one rank, under a heading per module or aggregate, in the order they appear.
+        def grouped_lines(bluebook, hits, width)
+          hits.group_by { |hit| group_name(bluebook, hit[:spec]) }.flat_map do |group, members|
+            ["#{group}:", *members.map { |hit| hit_line(hit[:spec], width) }]
+          end
+        end
+
+        # The matching specs of one table with the rank of each: 0 for a match on the call,
+        # 1 for a match on the description only. Internal specs stay out unless `:all` is given.
+        def hits_in(specs, options, needle)
+          CliAudience.audience_specs(specs, options).values.filter_map do |spec|
+            next if spec[:internal] && !options[:all]
+
+            rank = rank_of(spec, needle)
+            { spec: spec, rank: rank } if rank
+          end
+        end
+
+        # Where a spec matches the needle: its call (0), its description (1), or nowhere (nil).
+        def rank_of(spec, needle)
+          return 0 if label(spec).downcase.include?(needle)
+          return 1 if spec[:summary].to_s.downcase.include?(needle)
+
+          nil
+        end
+
+        # The heading a hit sits under: its module's name when a module of the bluebook groups its
+        # aggregate, else the aggregate's own name.
+        def group_name(bluebook, spec)
+          row = bluebook.modules.find { |module_row| module_row.aggregate == spec[:group] }
+          row ? Naming.snake(row.name) : spec[:group]
+        end
+
+        # One hit: the call to type, padded to the widest, then what it does in one sentence.
+        def hit_line(spec, width)
+          text = spec[:kind] == :command ? spec[:summary].to_s : first_sentence(spec[:summary].to_s)
+          "  #{label(spec).ljust(width)}  #{text}"
+        end
+      end
+    end
+  end
+end

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

@@ -1,4 +1,5 @@
 require_relative "../../naming"
+require_relative "../../adapters/driving/exit_status"
 
 module Hecks
   module Projector
@@ -35,10 +36,13 @@ module Hecks
           pool[key] || questions[key]
         end
 
-        # The whole help: the two tables, the bluebooks, then the hints.
+        # The whole help: the everyday lines, the two tables, the bluebooks, then the hints.
         def full_usage(bluebook, commands, questions, options, program)
-          shown = [commands, questions].map { |specs| CliAudience.audience_specs(specs, options) }
-          [usage_header(bluebook, program),
+          shown = [commands, questions].map do |specs|
+            in_module(bluebook, CliAudience.audience_specs(specs, options), options[:module])
+          end
+          [header_for(bluebook, program, options[:module]),
+           everyday_lines(*shown, options),
            tables(*shown, all: options[:all], notes: aggregate_notes(bluebook)),
            CliAudience.bluebook_lines(program, options[:declarations]),
            usage_footer(program, shown, options, left_out(commands, questions, shown))].flatten(1).join("\n")
@@ -49,9 +53,14 @@ module Hecks
           commands.size + questions.size - shown.sum(&:size)
         end
 
-        # The bluebook's vision and the two ways to call it.
+        # The heading of the help: the bluebook's, or the module's when one is asked for.
+        def header_for(bluebook, program, module_name)
+          module_name ? module_header(bluebook, module_name, program) : usage_header(bluebook, program)
+        end
+
+        # The bluebook's vision, the release of the gem this launcher runs, and the two ways to call it.
         def usage_header(bluebook, program)
-          ["#{bluebook.name} — #{bluebook.vision}", "",
+          ["#{bluebook.name} — #{bluebook.vision}", "  hecks #{Hecks::VERSION}", "",
            "  #{program} <command>! [name=value …]       do something",
            "  #{program} query <query> [name=value …]    read something", ""]
         end
@@ -66,7 +75,15 @@ module Hecks
 
           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)}"
+          out.concat(closing_lines(shown, options))
+        end
+
+        # The example call and, for a launcher that opted in, the line naming the three exit
+        # statuses. A launcher that did not opt in keeps the text every earlier generator wrote,
+        # which exits 1 for every line it could not read, so it claims nothing.
+        def closing_lines(shown, options)
+          lines = ["  a command is called with its aggregate — #{example_qualified(shown.first)}"]
+          options[:opted] ? lines << "  #{Adapters::Driving::ExitStatus::HELP_LINE}" : lines
         end
 
         # The commands table then the queries table.

data/lib/hecks/projector/cli_projector.rb

@@ -3,9 +3,15 @@ require_relative "cli_projector/claims"
 require_relative "cli_projector/command_specs"
 require_relative "cli_projector/query_specs"
 require_relative "cli_projector/option_specs"
+require_relative "cli_projector/renames"
 require_relative "cli_projector/usage"
 require_relative "cli_projector/listing"
+require_relative "cli_projector/everyday"
 require_relative "cli_projector/command_help"
+require_relative "cli_projector/modules"
+require_relative "cli_projector/search"
+require_relative "cli_projector/completion"
+require_relative "cli_projector/json_listing"
 
 module Hecks
   module Projector
@@ -17,6 +23,17 @@ module Hecks
     module CliProjector
       module_function
 
+      # The alias tables: each command and query under its short name and its old spellings, and
+      # the renamed table's old names routed to the namespace of their targets.
+      #
+      # @return [Hash{Symbol => Object}] `:command` and `:question` alias tables, and `:renamed`
+      #   (the old spellings and their argument renames)
+      def launcher_names(commands, questions, renamed)
+        table = renamed_aliases(commands, questions, renamed)
+        { command: aliases(commands).merge(table[:command]), question: aliases(questions).merge(table[:question]),
+          renamed: { spellings: Hash(renamed).keys.map(&:to_s), arguments: renamed_arguments(renamed) } }
+      end
+
       # Projects the command and question tables and the usage text. Commands and queries are
       # separate namespaces (a bluebook may declare both under one name); ask a query with `ask`.
       #
@@ -41,17 +58,23 @@ module Hecks
         display_names([commands, questions], options[:names])
 
         { commands: commands, questions: questions,
-          names: { command: aliases(commands), question: aliases(questions) },
+          names: launcher_names(commands, questions, options[:renamed]),
           usage: usage(bluebook, commands, questions, options) }
       end
 
       extend Claims
+      extend Renames
       extend CommandSpecs
       extend QuerySpecs
       extend OptionSpecs
       extend Usage
       extend Listing
+      extend Everyday
       extend CommandHelp
+      extend Modules
+      extend Search
+      extend Completion
+      extend JsonListing
     end
   end
 end

data/lib/hecks/quality_control/adapters/ci_head.adapter

@@ -0,0 +1,8 @@
+# Binds the `CiHead` port to `CiRunner`, which answers `Head`'s `Check` from the verdict GitHub
+# reports for a commit.
+# Required by name, not relative, so a copy of this directory shares the one implementation loaded.
+require "hecks/ci_pipeline/adapters/ci_runner"
+
+Hecks.adapter "CiRunner" do
+  port "CiHead"
+end

data/lib/hecks/quality_control/adapters/image_roll.adapter

@@ -0,0 +1,9 @@
+# Binds the `ImageRoll` port to `ImageRoll`, which classifies a green commit of embryonaut_platform
+# and rolls its
+# console image. Required by name, not relative, so a copy of this directory shares the one
+# implementation loaded.
+require "hecks/quality_control/adapters/image_roll"
+
+Hecks.adapter "ImageRoll" do
+  port "ImageRoll"
+end