hecks 7.0.0 → 7.1.0

data/lib/hecks/pipeline_board/adapters/pipeline_wiring/details.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Adapters
+    module PipelineBoard
+      # What a node declares, for the sidebar: an aggregate's description, commands with their goals
+      # and events, lifecycle and queries; a port's operations; an adapter's port. Read from the IR
+      # and never from a store.
+      class Details
+        # @param registry [Runtime::Registry] a booted registry
+        def initialize(registry)
+          @registry = registry
+        end
+
+        # @param node [Hash] a graph node
+        # @return [Hash] the node with its `details`
+        def enrich(node)
+          node.merge(details: send(node[:kind], node))
+        end
+
+        private
+
+        def aggregate(node)
+          book = @registry.bluebooks[node[:domain]]
+          held = book&.aggregates&.find { |candidate| candidate.hecks_name == node[:label] }
+          return {} unless held
+
+          { description: held.description.to_s, vision: vision(book, node), commands: commands(held),
+            lifecycle: lifecycle(held), queries: queries(held) }
+        end
+
+        def vision(book, node)
+          return "" unless node[:context] && book.respond_to?(:modules)
+
+          row = book.modules.find { |held| held.name.to_s == node[:context] }
+          row ? row.vision.to_s : ""
+        end
+
+        def commands(held)
+          held.commands.map do |command|
+            { name: name_of(command), goal: command.goal.to_s, emits: Array(command.emits).map(&:to_s) }
+          end
+        end
+
+        def lifecycle(held)
+          cycle = held.lifecycle
+          return nil unless cycle
+
+          { field: cycle.field.to_s, default: cycle.default.to_s, states: Array(cycle.states).map(&:to_s) }
+        end
+
+        def queries(held) = held.queries.map { |query| { name: name_of(query), description: query.description.to_s } }
+
+        def port(node)
+          declared = declared_ports.find { |held| held.name.to_s == node[:label] }
+          return {} unless declared
+
+          { operations: declared.operations.map { |operation| operation_of(operation) },
+            answers:    Array(declared.answered_queries).map(&:to_s) }
+        end
+
+        # Every operation port an aggregate of any booted bluebook declares.
+        def declared_ports
+          aggregates = @registry.bluebooks.each_value.flat_map(&:aggregates)
+          aggregates.flat_map { |held| held.respond_to?(:ports) ? held.ports : [] }
+        end
+
+        def operation_of(operation)
+          { name: name_of(operation), direction: operation.direction.to_s, answers: operation.answers.to_s,
+            refuses: operation.refuses.to_s, emits: Array(operation.emits).map(&:to_s) }
+        end
+
+        def adapter(node)
+          held = @registry.adapters[node[:label]]
+          return {} unless held
+
+          { port:   (held.respond_to?(:port_name) ? held.port_name : held.port).to_s,
+            fields: (held.respond_to?(:fields) ? Array(held.fields) : []).map(&:to_s) }
+        end
+
+        def name_of(item) = (item.respond_to?(:hecks_name) ? item.hecks_name : item.name).to_s
+      end
+    end
+  end
+end

data/lib/hecks/pipeline_board/adapters/pipeline_wiring/graph.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Adapters
+    module PipelineBoard
+      # The wiring of a booted registry as a graph: an aggregate is a node, a policy is an edge from
+      # the aggregate whose event it hears to the aggregate whose command it reaches, an `ask` goes
+      # to a port node, and a port goes to the adapter bound to it. Only what is wired is drawn, so
+      # an aggregate no policy or port touches is left out.
+      class Graph
+        # @param registry [Runtime::Registry] a booted registry
+        def initialize(registry)
+          @registry = registry
+          @nodes = {}
+          @edges = []
+        end
+
+        # @return [Hash] `nodes` and `edges`, each a Hash of plain strings
+        def to_h
+          policy_edges
+          adapter_edges
+          details = Details.new(@registry)
+          { nodes: @nodes.values.map { |node| details.enrich(node) }, edges: @edges.uniq }
+        end
+
+        private
+
+        def policy_edges
+          @registry.bluebooks.each_value do |bluebook|
+            bluebook.policies.each { |policy| edge_for(bluebook.name.to_s, policy) }
+          end
+        end
+
+        def edge_for(domain, policy)
+          from = aggregate_id(domain, policy.event_qualifier.to_s)
+          target = policy.reaches.to_s
+          return if from.empty? || target.empty?
+
+          to = target.start_with?("ask :") ? nil : destination(domain, target)
+          link(from, to, policy.name.to_s, to&.start_with?("port:") ? "ask" : "policy")
+        end
+
+        # The node a reach lands on: the port when the verb is a port operation, else the aggregate.
+        def destination(domain, verb)
+          parts = path_of(verb)
+          return aggregate_id(domain, parts.first) if parts.size == 1
+          return "port:#{parts.last}" if port?(parts.last)
+          return aggregate_id(parts.first, parts[1]) if @registry.bluebooks.key?(parts.first)
+
+          aggregate_id(domain, parts.first)
+        end
+
+        # The `Domain::Aggregate::Part` segments of a verb, without its command.
+        def path_of(verb)
+          owner = verb.split(".").first
+          owner.to_s.split("::")
+        end
+
+        def port?(name) = port_names.include?(name.to_s)
+
+        # Every port name: the plain ports the registry holds and the operation ports each
+        # aggregate declares.
+        def port_names
+          @port_names ||= @registry.ports.keys.map(&:to_s) + @registry.bluebooks.each_value.flat_map { |book| owned_ports(book) }
+        end
+
+        def owned_ports(bluebook)
+          bluebook.aggregates.flat_map { |aggregate| declared_ports(aggregate) }
+        end
+
+        def declared_ports(aggregate)
+          aggregate.respond_to?(:ports) ? aggregate.ports.map { |port| port.name.to_s } : []
+        end
+
+        def aggregate_id(domain, aggregate) = aggregate.to_s.empty? ? "" : "#{domain}::#{aggregate.split("::").last}"
+
+        def link(from, to, label, kind)
+          return unless to
+
+          origin = node(from, nil)
+          node(to, origin)
+          @edges << { from: from, to: to, label: label, kind: kind }
+        end
+
+        # An aggregate belongs to its own domain and to the module its bluebook declares it in,
+        # when there is one; a port to the domain and module of the aggregate that asks through it.
+        def node(id, asking)
+          port = id.start_with?("port:")
+          label = id.split("::").last.sub("port:", "")
+          domain = port ? asking[:domain] : id.split("::").first
+          context = port ? asking[:context] : module_of(domain, label)
+          @nodes[id] ||= { id: id, kind: port ? "port" : "aggregate", domain: domain, label: label, context: context }
+        end
+
+        def module_of(domain, aggregate)
+          book = @registry.bluebooks[domain]
+          return nil unless book.respond_to?(:modules)
+
+          row = book.modules.find { |held| held.aggregate.to_s == aggregate }
+          row && row.name.to_s
+        end
+
+        def adapter_edges
+          @registry.adapters.each_value do |adapter|
+            port = adapter.respond_to?(:port_name) ? adapter.port_name : adapter.port
+            next unless @nodes.key?("port:#{port}")
+
+            bind(port, adapter.name.to_s)
+          end
+        end
+
+        def bind(port, adapter)
+          id = "adapter:#{adapter}"
+          @nodes[id] = { id: id, kind: "adapter", domain: "", label: adapter }
+          @edges << { from: "port:#{port}", to: id, label: "", kind: "adapter" }
+        end
+      end
+    end
+  end
+end

data/lib/hecks/pipeline_board/adapters/pipeline_wiring.adapter

@@ -0,0 +1,7 @@
+# Binds the `Wiring` port to `PipelineWiring`, which answers `Wiring` from the booted registry.
+# Required by name, not relative, so a copy of this directory shares the one implementation loaded.
+require "hecks/pipeline_board/adapters/pipeline_wiring"
+
+Hecks.adapter "PipelineWiring" do
+  port "Wiring"
+end

data/lib/hecks/pipeline_board/adapters/pipeline_wiring.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "probe"
+require_relative "pipeline_wiring/details"
+require_relative "pipeline_wiring/graph"
+
+module Hecks
+  module Adapters
+    # The `Wiring` port's adapter: answers `Wiring` with what the loaded bluebooks wire together,
+    # for the diagram: which aggregate's events a policy listens to, which aggregate's command it
+    # reaches, which port an `ask` goes out through, and which adapter answers each port. It reads
+    # the booted registry and nothing else, and changes nothing.
+    class PipelineWiring
+      # @param registry [Runtime::Registry, nil] the booted registry whose bluebooks are read
+      # @param aggregate [Object, nil] unused
+      # @param settings [Hash] unused
+      # @param root [String, nil] unused
+      def initialize(registry: nil, aggregate: nil, settings: {}, root: nil)
+        @registry = registry
+      end
+
+      # @return [Hash{Symbol => String}] `text:` the graph as JSON: `nodes` and `edges`
+      # @raise [PipelineBoard::Unavailable] when no registry is booted here
+      def wiring = { text: JSON.generate(graph) }
+
+      # @return [Hash] `nodes` (aggregates, ports, adapters) and `edges` (policy, ask, adapter)
+      # @raise [PipelineBoard::Unavailable] when no registry is booted here
+      def graph
+        raise PipelineBoard::Unavailable, "no domain is booted here to read the wiring from" unless @registry
+
+        @graph ||= PipelineBoard::Graph.new(@registry).to_h
+      end
+    end
+  end
+end

data/lib/hecks/pipeline_board/adapters/probe.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+require "timeout"
+
+module Hecks
+  module Adapters
+    # What the PipelineBoard readers share: the reason a read failed, the outside command they run,
+    # and the short cache that keeps a polling page from hammering it.
+    module PipelineBoard
+      # A read that could not be answered. The message is the reason a stage shows after `unknown:`.
+      class Unavailable < StandardError; end
+
+      # Runs one outside command for a reader and answers its standard output.
+      module Probe
+        TIMEOUT_SECONDS = 25
+
+        # @param command [Array<String>] the program and its arguments, never a shell string
+        # @param chdir [String, nil] where it runs
+        # @return [String] standard output
+        # @raise [Unavailable] when the program is missing, times out or exits non-zero
+        def self.run(*command, chdir: nil, seconds: TIMEOUT_SECONDS)
+          out, err, status = Timeout.timeout(seconds) { Open3.capture3(*command, chdir: chdir || Dir.pwd) }
+          raise Unavailable, "#{command.first} #{command[1]}: #{reason(err)}" unless status.success?
+
+          out
+        rescue Errno::ENOENT then raise Unavailable, "#{command.first} is not installed"
+        rescue Timeout::Error then raise Unavailable, "#{command.first} did not answer in #{seconds}s"
+        end
+
+        # @return [String] the first line the command wrote to standard error
+        def self.reason(err)
+          first = err.lines.first
+          first.to_s.strip
+        end
+
+        # @return [Object] the JSON the command printed
+        # @raise [Unavailable] when the output is not JSON
+        def self.json(*command, chdir: nil)
+          JSON.parse(run(*command, chdir: chdir))
+        rescue JSON::ParserError => e
+          raise Unavailable, "#{command.first} printed no JSON: #{e.message[0, 60]}"
+        end
+      end
+    end
+  end
+end

data/lib/hecks/pipeline_board/pipeline_board.bluebook

@@ -0,0 +1,144 @@
+# PipelineBoard: the pipeline from coding to release, read live and shown on one local page. The
+# read side is six queries, each answered by an adapter behind a port: GitHub for the CI runs, Git
+# for local main and the train, Tickets for the Work items, Jobs for the sessions, Journal for the
+# events the tooling recorded. The bluebook names the questions and never fetches, shells out or
+# opens a file.
+#
+# The one command is `Serve`. It opens the page on 127.0.0.1 and answers `GET /` and
+# `GET /api/state` until it is stopped; no command is reachable from the page, so the board only
+# reads. A read that fails answers `unknown: <reason>` for its stage and leaves the others alone.
+#
+#   exe/hecks PipelineBoard.serve! port.value=4747 --wait
+
+Hecks.bluebook "PipelineBoard" do
+  vision "The pipeline from a Work row to a release is read live, stage by stage, and shown with the real events it emitted."
+
+  supporting
+
+  # The board. One run of it is one server opened on a local port, until it is stopped.
+  aggregate "PipelineBoard" do
+    description "The pipeline's stages, CI runs, work, sessions and events as they stand, and one server that shows them."
+
+    identified_by :run
+
+    attribute :run,  RunKey
+    attribute :port, Port, optional: true
+    attribute :last, Reason, optional: true
+
+    value_object "RunKey" do
+      attribute :value, String, matches: :present
+    end
+
+    # A local port the page is served on.
+    value_object "Port" do
+      attribute :value, Integer, default: 4747
+
+      invariant("a port is 1024 to 65535") { value >= 1024 && value <= 65535 }
+    end
+
+    # Why a server ended or was refused.
+    value_object "Reason" do
+      attribute :value, String
+    end
+
+    # A JSON document: the results of a query, or `unknown: <reason>` for a read that failed.
+    value_object "Document" do
+      attribute :text, String
+    end
+
+    # How many results a query answers, at most.
+    value_object "Limit" do
+      attribute :value, Integer, default: 20
+    end
+
+    lifecycle :status, default: "requested" do
+      mark :failure, "refused"
+      mark :terminal, "closed", "refused"
+      transition "Close"  => "closed",  from: "requested"
+      transition "Refuse" => "refused", from: "requested"
+    end
+
+    command "Serve" do
+      role "Maintainer"
+      goal "Show the pipeline on a page at 127.0.0.1 until stopped; the page reads and writes nothing"
+
+      attribute :run,  RunKey, sets: true
+      attribute :port, Port, default: 4747, sets: true
+
+      emits ServeRequested
+    end
+
+    command "Close" do
+      role "System"
+      goal "Record that the server ended"
+
+      reference_to PipelineBoard
+      attribute :last, Reason, sets: true
+
+      emits BoardClosed
+    end
+
+    command "Refuse" do
+      role "System"
+      goal "Record that the server could not open, and why"
+
+      reference_to PipelineBoard
+      attribute :last, Reason, sets: true
+
+      emits BoardRefused
+    end
+
+    query "Stages" do
+      description "One entry per stage, left to right: Work items, Sessions, Local main, Train, CI, Promote, Release, each with its state, count and a one-line detail."
+      returns Document
+    end
+
+    query "CiRuns" do
+      description "The last CI runs on main, oldest first: sha, started, wall minutes, conclusion and how many jobs failed."
+      attribute :limit, Limit, optional: true
+      returns Document
+    end
+
+    query "SlowestJobs" do
+      description "The jobs of the last completed CI run, slowest first, in minutes."
+      attribute :limit, Limit, optional: true
+      returns Document
+    end
+
+    query "OpenWork" do
+      description "The Work items that are not done: slug, status and area."
+      returns Document
+    end
+
+    query "Sessions" do
+      description "The busy and the recent dispatched sessions, with the job's own state."
+      returns Document
+    end
+
+    query "Wiring" do
+      description "What the loaded bluebooks wire together: aggregates, the policies between them, the ports an ask goes out through and the adapters that answer them."
+      returns Document
+    end
+
+    query "Events" do
+      description "The most recent events the tooling recorded, newest first: time, aggregate, event, and the policy that reacted where the journal holds one."
+      attribute :limit, Limit, optional: true
+      returns Document
+    end
+  end
+
+  policy "ListenWhenServed" do
+    on  "PipelineBoard.ServeRequested"
+    ask :listen, with: { port: :port }
+  end
+
+  policy "CloseWhenEnded" do
+    on      "PipelineBoard.ServerEnded"
+    trigger PipelineBoard::Close, with: { last: :last }
+  end
+
+  policy "RefuseWhenRefused" do
+    on      "PipelineBoard.ServerRefused"
+    trigger PipelineBoard::Refuse, with: { last: :last }
+  end
+end

data/lib/hecks/pipeline_board/pipeline_board.hecksagon

@@ -0,0 +1,12 @@
+# The PipelineBoard bluebook, bound so it boots standing alone (a behaviors or model_check boot of
+# this directory). The ports it shares with every attaching hecksagon are in
+# pipeline_board.ports.hecksagon.
+Hecks.hecksagon "PipelineBoard" do
+  attaches "Governance"
+  persisted_by "Memory"
+end
+
+# The anti-corruption layer for Governance, which the bluebook's roles are checked against.
+Hecks.hecksagon "Governance" do
+  persisted_by "Memory"
+end

data/lib/hecks/pipeline_board/pipeline_board.ports.hecksagon

@@ -0,0 +1,47 @@
+# The ports PipelineBoard declares, for every hecksagon that attaches the bluebook. Each names the
+# question it asks of the outside and never says how it is answered; an adapter binds each. Every
+# port but `Web` only reads.
+Hecks.hecksagon "PipelineBoard" do
+  attaches "Governance"
+
+  # CI as GitHub reports it, read with the `gh` CLI.
+  PipelineBoard::PipelineBoard.port "GitHub" do
+    answers_query "CiRuns"
+    answers_query "SlowestJobs"
+  end
+
+  # The Work items, read through the Tickets domain.
+  PipelineBoard::PipelineBoard.port "Tickets" do
+    answers_query "OpenWork"
+  end
+
+  # The dispatched sessions: each job's state file and `claude agents --json`.
+  PipelineBoard::PipelineBoard.port "Jobs" do
+    answers_query "Sessions"
+  end
+
+  # The events the tooling recorded, read from the journal store without writing to it.
+  PipelineBoard::PipelineBoard.port "Journal" do
+    answers_query "Events"
+  end
+
+  # The wiring of the booted domains, read from the registry, for the diagram.
+  PipelineBoard::PipelineBoard.port "Wiring" do
+    answers_query "Wiring"
+  end
+
+  # Every stage, composed from the readings above and from this checkout's git state.
+  PipelineBoard::PipelineBoard.port "Pipeline" do
+    answers_query "Stages"
+  end
+
+  # The page. The adapter opens a server on 127.0.0.1 and answers `GET /` and `GET /api/state`;
+  # it is the only effect the board has.
+  PipelineBoard::PipelineBoard.port "Web" do
+    asks "Listen", to: PipelineBoard do
+      attribute :port, Port
+      answers "ServerEnded"
+      refuses "ServerRefused"
+    end
+  end
+end

data/lib/hecks/ports/persistence/binding_policy.rb

@@ -80,7 +80,8 @@ module Hecks
         # @return [Bluebook::Bind] the authoritative bind
         # @raise [Runtime::WiringError] if the roleless count is not one, or a role is present
         def authoritative_among(bindings, domain, aggregate)
-          # The same adapter declared again, by a hecksagon that another domain also attaches, is one
+          # The same adapter declared again, by a hecksagon that another domain also attaches, is
+          # one
           # binding, not an ambiguous second one.
           authoritative = bindings.select { |bind| bind.role.nil? || bind.role.empty? }.uniq(&:adapter)
           raise ambiguous_binding(domain, aggregate, authoritative) unless authoritative.size == 1

data/lib/hecks/ports/persistence/plugins/era/translation/compose.rb

@@ -32,7 +32,6 @@ module Hecks
       # its one step is the edge from that label to itself, when such an edge exists.
       #
       # @return [Array<Bluebook::Translation>] the edges in order; empty when none leads `from` to `to`
-      #   and `from` is `to`
       # @raise [Runtime::WiringError] when a step has no edge, has two, or the walk loops
       def chain(translations, domain:, from:, to:)
         return self_edges(translations, domain, from) if from == to
@@ -48,7 +47,8 @@ module Hecks
         steps
       end
 
-      # @return [Bluebook::Translation] the one edge from the first step's origin to the last step's target
+      # @return [Bluebook::Translation] the one edge from the first step's origin to the last step's
+      #   target
       # @raise [Runtime::WiringError] when a step's rules cannot be composed into one edge
       def compose(domain:, from:, to:, chain:)
         refuse_unrenderable!(chain)
@@ -102,7 +102,8 @@ module Hecks
       # Follows each aggregate from its held name to its current one, and finds the one step that
       # carries field rules for each origin.
       #
-      # @return [Array(Hash, Array<String>, Hash)] origins keyed by current name, every retired name,
+      # @return [Array(Hash, Array<String>, Hash)] origins keyed by current name, every retired
+      #   name,
       #   and the aggregate carrying field rules for each origin
       def track_chain(chain)
         state = { origins: {}, retired: [], ruled: {} }

data/lib/hecks/ports/persistence/repository_factory.rb

@@ -55,7 +55,8 @@ module Hecks
           settings.merge(boot_marks(registry, domain))
         end
 
-        # The per-domain marks the boot gate left on the registry, merged into an adapter's settings.
+        # The per-domain marks the boot gate left on the registry, merged into an adapter's
+        # settings.
         #
         # @return [Hash] the domain, resolved era, superseding era and whether the shape is unminted
         def boot_marks(registry, domain)

data/lib/hecks/projections/ci_pipeline/table.rb

@@ -41,7 +41,8 @@ module Hecks
                          "#{claimed.map(&:name).join(", ")}; a project has one set of workflow rows"
         end
 
-        # @return [Array<Bluebook::Declaration>] the project's bluebooks that declare `Workflow` rows
+        # @return [Array<Bluebook::Declaration>] the project's bluebooks that declare `Workflow`
+        #   rows
         def self.holders(registry)
           clients = registry.bluebooks.values.reject { |bluebook| bluebook.name == BLUEBOOK }
           clients.select { |bluebook| rows_of(bluebook, MARKER).any? }

data/lib/hecks/projections/deploy/lambda/stack/recipes.rb

@@ -26,11 +26,11 @@ module Hecks
 
             # `hecks ask` answers the scaffold as text, and refuses (exit 1) where the script
             # aborted.
-            SCAFFOLD = Translation.new(verb: "scaffold-translation", script: "exe/hecks query era.scaffold_translation",
+            SCAFFOLD = Translation.new(verb: "scaffold-translation", script: "exe/hecks era.scaffold_translation",
                                        extra_args: "", cwd: "$(ROOT)", run_prefix: "HECKS_ENVIRONMENT=memory ruby",
                                        db_env_blind: true, domain_arg: "domain=$(DOMAIN) ")
             # A refused audit is a refused query: `hecks ask` exits 1, so the target fails too.
-            AUDIT = Translation.new(verb: "translation-audit", script: "exe/hecks query era.audit_translation",
+            AUDIT = Translation.new(verb: "translation-audit", script: "exe/hecks era.audit_translation",
                                     extra_args: "", cwd: "$(ROOT)", run_prefix: "HECKS_ENVIRONMENT=memory ruby",
                                     db_env_blind: true, domain_arg: "domain=$(DOMAIN) ")
             # An app-owned one-time migration script instead of a hecks tool:

data/lib/hecks/projections/undo.rb

@@ -15,7 +15,8 @@ module Hecks
       module_function
 
       # @param bluebook [Bluebook::Declaration] the bluebook holding the process managers
-      # @param options [Hash{Symbol => Object}] `command:`, the command's verb form, e.g. "Account.Debit"
+      # @param options [Hash{Symbol => Object}] `command:`, the command's verb form, e.g.
+      #   "Account.Debit"
       # @return [Array<String>] one sentence: the undoing command, or that none is declared
       def call(bluebook:, options: {})
         command = options.fetch(:command)

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

@@ -5,9 +5,9 @@ module Hecks
       module CommandHelp
         # Four independent blocks, concatenated in fixed order: meta, invocation,
         # arguments, refusals.
-        def command_help(program, name, spec, ask: false)
+        def command_help(program, name, spec, ask: false, qualified: false)
           out = command_help_meta_lines(name, spec)
-          out.concat(command_help_invocation_lines(program, name, spec, ask))
+          out.concat(command_help_invocation_lines(program, name, spec, [ask, qualified]))
           out.concat(command_help_argument_lines(spec))
           out.concat(command_help_refusal_lines(spec))
           out.join("\n")
@@ -28,8 +28,9 @@ module Hecks
         end
 
         # The example call with every argument as `path=…`.
-        def command_help_invocation_lines(program, name, spec, ask)
-          invocation = ask ? "#{program} query #{name}" : "#{program} #{name}!"
+        def command_help_invocation_lines(program, name, spec, asking)
+          ask, qualified = asking
+          invocation = ask ? [program, ("query" if qualified), name].compact.join(" ") : "#{program} #{name}!"
           ["", "  #{invocation}#{spec[:arguments].map { |a| " #{a[:path]}=…" }.join}", ""]
         end
 

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

@@ -3,7 +3,8 @@ module Hecks
     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.
+      # 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
@@ -13,7 +14,8 @@ module Hecks
         # @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
+        # @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)

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

@@ -25,7 +25,7 @@ module Hecks
           return unless only
 
           spec = help_spec(only, commands, questions, options[:ask])
-          command_help(program, verb_form(spec, spec[:short]), spec, ask: options[:ask]) if spec
+          command_help(program, verb_form(spec, spec[:short]), spec, ask: options[:ask], qualified: options[:query_word]) if spec
         end
 
         # `ask` picks the namespace when both hold the name; without it a
@@ -58,11 +58,12 @@ module Hecks
           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.
+        # 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}", "  hecks #{Hecks::VERSION}", "",
            "  #{program} <command>! [name=value …]       do something",
-           "  #{program} query <query> [name=value …]    read something", ""]
+           "  #{program} <query> [name=value …]          read something, written bare", ""]
         end
 
         # The pointers after the tables: `--help`, `--all`, `--maintainer` and an example call.