hecks 3.4.2 → 3.6.0

data/lib/hecks/projections/site/table/row_builder.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "row_defaults"
+
 module Hecks
   module Projections
     module Site
@@ -49,25 +51,31 @@ module Hecks
             fields = checked_fields(member, label)
             source = fields[:source] || "none"
             path = fields[:path] || derived_path(source)
-            label = path || label
-            check_source(label, source)
+            check_source(path || label, source)
+            finish(build_row(fields, path, source), path || label)
+          end
+
+          private
+
+          def build_row(fields, path, source)
             verbs = fields.delete(:methods)
             edge_verbs = fields.delete(:edge_methods)
-            row = Row.new(**fields, verbs: verbs, edge_verbs: edge_verbs, path: path, source: source,
-                                    explicit_cache: !fields[:cache].nil?,
-                                    kind: fields[:kind] || default_kind(source), auth: fields[:auth] || "public",
-                                    origin: fields[:origin] || default_origin(source))
-            fill_defaults(row)
+            Row.new(**fields, verbs: verbs, edge_verbs: edge_verbs, path: path, source: source,
+                              explicit_cache: !fields[:cache].nil?,
+                              kind: fields[:kind] || RowDefaults.kind(source), auth: fields[:auth] || "public",
+                              origin: fields[:origin] || RowDefaults.origin(source))
+          end
+
+          def finish(row, label)
+            RowDefaults.fill(row)
             check_values(row, label)
             problem(label, "needs a path") if row.path.nil?
             row
           end
 
-          private
-
           def checked_fields(member, label)
             member.each_key do |key|
-              problem(label, "has no field #{key}; fields are #{FIELDS.keys.join(', ')}") unless FIELDS.key?(key)
+              problem(label, "has no field #{key}; fields are #{FIELDS.keys.join(", ")}") unless FIELDS.key?(key)
             end
             known = member.slice(*FIELDS.keys)
             known.each { |key, value| check_type(label, key, value) }
@@ -78,13 +86,9 @@ module Hecks
             expected = FIELDS.fetch(key)
             return if expected == :bool ? [true, false].include?(value) : value.is_a?(expected)
 
-            problem(label, "has #{key} #{value.inspect}; #{key} is #{expected == :bool ? 'true or false' : "a #{expected}"}")
+            problem(label, "has #{key} #{value.inspect}; #{key} is #{expected == :bool ? "true or false" : "a #{expected}"}")
           end
 
-          def default_kind(source) = source.match?(DERIVED_SOURCE) ? "endpoint" : "page"
-
-          def default_origin(source) = source.match?(DERIVED_SOURCE) ? "domain" : "website"
-
           # A `command:` or `query:` source leaves the path to the forms scheme,
           # `/Chapter/Aggregate/Verb`.
           def derived_path(source)
@@ -92,57 +96,31 @@ module Hecks
             "/#{match[2]}/#{match[3]}/#{match[4]}"
           end
 
-          def fill_defaults(row)
-            row.off = false if row.off.nil?
-            row.compress = true if row.compress.nil?
-            row.cdn = true if row.cdn.nil?
-            row.render ||= row.kind == "page" ? "prerender" : "ssr"
-            row.verbs = list(row.verbs || (row.source.start_with?("command:") ? "POST" : "GET"))
-            row.edge_verbs = row.edge_verbs.nil? ? row.verbs : list(row.edge_verbs)
-            row.aliases = list(row.aliases)
-            row.cache ||= default_cache(row)
-            row.indexable = indexable_by_default?(row) if row.indexable.nil?
-            fill_slots(row)
-          end
-
-          def fill_slots(row)
-            row.preview ||= "public"
-            row.switch ||= ""
-            row.footer_order ||= 0 if row.footer_column
-            row.admin_order ||= 0 if row.admin_key
-          end
-
-          def list(text) = text.to_s.split(",").map(&:strip).reject(&:empty?)
-
-          def default_cache(row)
-            return "no_store" if row.auth != "public" || row.kind == "endpoint"
-
-            row.origin == "assets" ? "immutable" : "page"
-          end
-
-          def indexable_by_default?(row) = row.kind == "page" && row.auth == "public" && !row.off
-
           def check_values(row, label)
             VOCABULARY.each_key do |field|
               next if @vocabulary.fetch(field).include?(row[field])
 
-              problem(label, "has #{field} #{row[field].inspect}; #{field} is one of #{@vocabulary.fetch(field).join(', ')}")
+              problem(label, "has #{field} #{row[field].inspect}; #{field} is one of #{@vocabulary.fetch(field).join(", ")}")
             end
             check_verbs(row, label)
           end
 
           def check_verbs(row, label)
             { "method" => row.verbs, "edge method" => row.edge_verbs }.each do |what, verbs|
-              verbs.each do |verb|
-                next if @vocabulary.fetch(:http_method).include?(verb)
-
-                problem(label, "has #{what} #{verb.inspect}; methods are #{@vocabulary.fetch(:http_method).join(', ')}")
-              end
+              check_known_verbs(label, what, verbs)
             end
             return if (row.verbs - row.edge_verbs).empty?
 
-            problem(label, "has edge_methods #{row.edge_verbs.join(',')}, which leave out its methods " \
-                           "#{(row.verbs - row.edge_verbs).join(',')}; the edge must allow every verb the route answers")
+            problem(label, "has edge_methods #{row.edge_verbs.join(",")}, which leave out its methods " \
+                           "#{(row.verbs - row.edge_verbs).join(",")}; the edge must allow every verb the route answers")
+          end
+
+          def check_known_verbs(label, what, verbs)
+            verbs.each do |verb|
+              next if @vocabulary.fetch(:http_method).include?(verb)
+
+              problem(label, "has #{what} #{verb.inspect}; methods are #{@vocabulary.fetch(:http_method).join(", ")}")
+            end
           end
 
           def check_source(label, source)

data/lib/hecks/projections/site/table/row_defaults.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Projections
+    module Site
+      class Table
+        # The values a row takes when its declaration leaves them out: what its source implies for
+        # kind, origin and verbs, and what its kind and auth imply for render, cache and indexing.
+        module RowDefaults
+          module_function
+
+          # @param source [String] the row's source
+          # @return [String] `endpoint` for a command or query source, else `page`
+          def kind(source) = source.match?(RowBuilder::DERIVED_SOURCE) ? "endpoint" : "page"
+
+          # @param source [String] the row's source
+          # @return [String] `domain` for a command or query source, else `website`
+          def origin(source) = source.match?(RowBuilder::DERIVED_SOURCE) ? "domain" : "website"
+
+          # Fills every field a row may leave undeclared, in the order each depends on the last.
+          #
+          # @param row [Row] the row, with its kind, auth, origin and source set
+          # @return [void]
+          def fill(row)
+            fill_flags(row)
+            fill_lists(row)
+            row.cache ||= default_cache(row)
+            row.indexable = indexable_by_default?(row) if row.indexable.nil?
+            fill_slots(row)
+          end
+
+          def fill_flags(row)
+            row.off = false if row.off.nil?
+            row.compress = true if row.compress.nil?
+            row.cdn = true if row.cdn.nil?
+            row.render ||= row.kind == "page" ? "prerender" : "ssr"
+          end
+
+          def fill_lists(row)
+            row.verbs = list(row.verbs || (row.source.start_with?("command:") ? "POST" : "GET"))
+            row.edge_verbs = row.edge_verbs.nil? ? row.verbs : list(row.edge_verbs)
+            row.aliases = list(row.aliases)
+          end
+
+          def fill_slots(row)
+            row.preview ||= "public"
+            row.switch ||= ""
+            row.footer_order ||= 0 if row.footer_column
+            row.admin_order ||= 0 if row.admin_key
+          end
+
+          def list(text) = text.to_s.split(",").map(&:strip).reject(&:empty?)
+
+          def default_cache(row)
+            return "no_store" if row.auth != "public" || row.kind == "endpoint"
+
+            row.origin == "assets" ? "immutable" : "page"
+          end
+
+          def indexable_by_default?(row) = row.kind == "page" && row.auth == "public" && !row.off
+        end
+      end
+    end
+  end
+end

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

@@ -43,7 +43,7 @@ module Hecks
           return holders.first if holders.one?
 
           raise Invalid, "#{holders.size} chapters declare a value_object \"#{ROW_OBJECT}\": " \
-                         "#{holders.map(&:name).join(', ')}; a project has one route table"
+                         "#{holders.map(&:name).join(", ")}; a project has one route table"
         end
 
         # Reads and checks one chapter's route table.
@@ -88,16 +88,20 @@ module Hecks
         # @raise [Invalid] when a row is refused
         def initialize(members, vocabulary:, registry: nil, links: [])
           problems = []
-          builder = RowBuilder.new(vocabulary: vocabulary, registry: registry, problems: problems)
-          @rows = members.each_with_index.map { |member, index| builder.call(member, index) }
-          link_builder = LinkBuilder.new(@rows, problems)
-          @links = links.each_with_index.map { |member, index| link_builder.call(member, index) }
+          @rows = build_all(members, RowBuilder.new(vocabulary: vocabulary, registry: registry, problems: problems))
+          @links = build_all(links, LinkBuilder.new(@rows, problems))
           Checks.new(@rows, problems, links: @links).call
           return if problems.empty?
 
           raise Invalid, "the route table is refused:\n#{problems.map { |line| "  - #{line}" }.join("\n")}"
         end
 
+        # @param members [Array<Hash{Symbol => Object}>] declared rows or links
+        # @param builder [#call] a `RowBuilder` or `LinkBuilder`
+        # @return [Array<Row, Link>] what the builder makes of each, in order
+        def build_all(members, builder) = members.each_with_index.map { |member, index| builder.call(member, index) }
+        private :build_all
+
         # The navigation slots a row or link sits in.
         #
         # @param row [Row, Link] a row or link

data/lib/hecks/projections/vocabulary.rb

@@ -25,6 +25,39 @@ module Hecks
         # be the table the framework loads with.
       RUBY
 
+      # The generated file, with `@@ROWS@@` standing for the table entries.
+      TEMPLATE = <<~RUBY.freeze
+        #{HEADER}
+        module Hecks
+          module Vocabulary
+            TABLES = {
+        @@ROWS@@
+            }.freeze
+
+            # The terms — the first field of each row, which for a
+            # one-field vocabulary is the whole of it. Derived once and
+            # frozen rather than mapped per call: these are constant
+            # tables, and a constant that allocates a new array every
+            # time it is read is not one.
+            TERMS = TABLES.transform_values { |rows| rows.map { |row| row.values.first }.freeze }.freeze
+
+            module_function
+
+            # Refuses an unknown name rather than answering nil: a set
+            # the language does not declare is a typo, not an empty set.
+            def fetch(name) = TERMS.fetch(name)
+
+            # The rows whole, for the vocabularies that carry more than
+            # a term — Comparison's own algebra, RefusalTemplate's text.
+            def rows(name) = TABLES.fetch(name)
+
+            def symbols(name) = fetch(name).map(&:to_sym)
+
+            def names = TABLES.keys
+          end
+        end
+      RUBY
+
       module_function
 
       # The projector protocol; `options` is unused.
@@ -62,37 +95,7 @@ module Hecks
           "      #{name.inspect} => [\n#{members.map { |row| "        #{row.inspect}.freeze" }.join(",\n")}\n      ].freeze"
         end
 
-        <<~RUBY
-          #{HEADER}
-          module Hecks
-            module Vocabulary
-              TABLES = {
-          #{rows.join(",\n")}
-              }.freeze
-
-              # The terms — the first field of each row, which for a
-              # one-field vocabulary is the whole of it. Derived once and
-              # frozen rather than mapped per call: these are constant
-              # tables, and a constant that allocates a new array every
-              # time it is read is not one.
-              TERMS = TABLES.transform_values { |rows| rows.map { |row| row.values.first }.freeze }.freeze
-
-              module_function
-
-              # Refuses an unknown name rather than answering nil: a set
-              # the language does not declare is a typo, not an empty set.
-              def fetch(name) = TERMS.fetch(name)
-
-              # The rows whole, for the vocabularies that carry more than
-              # a term — Comparison's own algebra, RefusalTemplate's text.
-              def rows(name) = TABLES.fetch(name)
-
-              def symbols(name) = fetch(name).map(&:to_sym)
-
-              def names = TABLES.keys
-            end
-          end
-        RUBY
+        TEMPLATE.sub("@@ROWS@@") { rows.join(",\n") }
       end
     end
   end

data/lib/hecks/projector/cli_audience.rb

@@ -0,0 +1,42 @@
+module Hecks
+  module Projector
+    # What a launcher's help leaves out and points at for whoever typed the line: the aggregates
+    # only a maintainer of a hecks checkout runs, and the attached chapters worth a line each.
+    # `CliProjector` renders the help; the runner decides the audience (`Doors::LauncherOptions`).
+    module CliAudience
+      module_function
+
+      # The specs whose aggregate the audience does not run.
+      def without_hidden(specs, hide)
+        hidden = Array(hide)
+        hidden.empty? ? specs : specs.reject { |_, spec| hidden.include?(spec[:group]) }
+      end
+
+      # The attached chapters the help points at, one line each, under the call that opens them.
+      #
+      # @param chapters [Array<Array(String, String)>, nil] each chapter's word and its summary
+      def chapter_lines(program, chapters)
+        return [] if Array(chapters).empty?
+
+        width = chapters.map { |word, _| word.length }.max
+        ["", "chapters (`#{program} <chapter>` lists a chapter's own commands and queries):",
+         *chapters.map { |word, summary| "  #{word.ljust(width)}  #{clipped(summary)}".rstrip }]
+      end
+
+      # A summary cut to one terminal line, at a word, with an ellipsis where it was cut.
+      def clipped(text, limit = 96)
+        return text if text.length <= limit
+
+        "#{text[0, limit].sub(/\s+\S*\z/, "")}…"
+      end
+
+      # The line saying the commands for working on hecks itself were left out and how to list
+      # them, or no line when none were.
+      def maintainer_hint(program, count)
+        return [] unless count.positive?
+
+        ["  #{program} --maintainer           also list the #{count} commands and queries for working on hecks itself"]
+      end
+    end
+  end
+end

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

@@ -0,0 +1,149 @@
+require_relative "../../naming"
+
+module Hecks
+  module Projector
+    module CliProjector
+      # The command-line names of a projection: who claims which name, how a command is
+      # qualified, and the launcher names a chapter gives its commands.
+      module Claims
+        # Claims the commands and questions of one aggregate and its entities and ports.
+        #
+        # @param commands [Hash{String => Hash}] the command map, mutated in place
+        # @param questions [Hash{String => Hash}] the question map, mutated in place
+        # @param bluebook [Bluebook::Chapter] the booted domain
+        # @param aggregate [Bluebook::Aggregate] the aggregate to claim
+        # @return [void]
+        def claim_aggregate(commands, questions, bluebook, aggregate)
+          claim_members(commands, questions, bluebook, aggregate, nil)
+          aggregate.entities.each { |entity| claim_members(commands, questions, bluebook, aggregate, entity) }
+
+          # Port operations dispatch by the same name as a command, so they are commands too.
+          aggregate.ports.each do |port|
+            port.operations.each { |o| claim(commands, name_for(aggregate, o), port_spec(bluebook, aggregate, port, o)) }
+          end
+        end
+
+        # Claims the commands and queries one aggregate or one of its entities declares.
+        def claim_members(commands, questions, bluebook, aggregate, entity)
+          owner = entity || aggregate
+          owner.commands.each do |c|
+            claim(commands, name_for(aggregate, c, entity), command_spec(bluebook, aggregate, entity, c))
+          end
+          owner.queries.each do |q|
+            claim(questions, name_for(aggregate, q, entity), query_spec(bluebook, aggregate, entity, q))
+          end
+        end
+
+        # Claims each report under its chapter-qualified name. A report belongs to the chapter,
+        # not an aggregate, so it is addressed `Chapter.Report` (one dot) where a query is
+        # `Chapter::Aggregate.Query`.
+        def claim_reports(questions, bluebook)
+          bluebook.read_models.each do |model|
+            claim(questions, Naming.snake(model.hecks_name), report_spec(bluebook, model))
+          end
+        end
+
+        # Sets `:short` on each spec to its full `aggregate.command` name: a command is always
+        # called with its aggregate, so adding a command elsewhere never changes what a call means.
+        #
+        # @param specs [Hash{String => Hash}] the command or query map, mutated in place
+        # @return [void]
+        def qualify(specs)
+          specs.each { |name, spec| spec[:short] = name }
+        end
+
+        # Marks the `run` key of each creating command `minted`: optional, and never filled by a
+        # bare word, since the launcher makes one when it is left out.
+        def mint_run_keys(commands)
+          commands.each_value do |spec|
+            next unless spec[:creates]
+
+            spec[:arguments] = spec[:arguments].map do |argument|
+              next argument unless argument[:path] == "run.value"
+
+              argument.merge(required: false, minted: true, note: "minted when omitted")
+            end
+          end
+        end
+
+        # Sets the display name of every spec in each map: its full name, then renamed by `names`.
+        #
+        # @param maps [Array<Hash{String => Hash}>] the command and question maps, mutated in place
+        # @param names [Hash, nil] the chapter's launcher names
+        # @return [void]
+        def display_names(maps, names)
+          maps.each do |specs|
+            qualify(specs)
+            rename(specs, names)
+          end
+        end
+
+        # Gives a command the launcher name a chapter's `names` table assigns it.
+        #
+        # The alias replaces the short name in help, so it is listed once; the spelling it
+        # replaced keeps working (`:short_was`, read by `aliases`). A table entry naming no
+        # command in `specs` belongs to the other namespace and is skipped.
+        #
+        # @param specs [Hash{String => Hash}] the command or question map, mutated in place
+        # @param names [Hash{String, Symbol => String, Symbol}, nil] launcher name to command name
+        # @return [void]
+        # @raise [Bluebook::DSL::Malformed] if a launcher name is already another command's name
+        def rename(specs, names)
+          Hash(names).each do |launcher_name, command|
+            _, spec = specs.find { |key, candidate| [key, candidate[:short]].include?(command.to_s) }
+            next unless spec
+
+            reserve_launcher_name(specs, launcher_name)
+            spec[:short_was] = spec[:short]
+            spec[:short]     = launcher_name.to_s
+          end
+        end
+
+        # Refuses a launcher name that is already some command's short name.
+        def reserve_launcher_name(specs, launcher_name)
+          return unless specs.values.any? { |spec| spec[:short] == launcher_name.to_s }
+
+          raise Bluebook::DSL::Malformed, "launcher name #{launcher_name.to_s.inspect} is already a command"
+        end
+
+        # Maps every accepted spelling (full name, `:short` and a renamed command's old name)
+        # to the full name.
+        def aliases(specs)
+          specs.each_with_object({}) do |(name, spec), map|
+            map[name]         = name
+            map[spec[:short]] = name
+            map[spec[:short_was]] = name if spec[:short_was]
+          end
+        end
+
+        # Stores `spec` under `name`, refusing a second claim rather than silently
+        # keeping whichever command was walked first.
+        #
+        # @raise [Bluebook::DSL::Malformed] if `name` is already claimed by another command
+        def claim(commands, name, spec)
+          if commands.key?(name)
+            raise Bluebook::DSL::Malformed,
+                  "two commands project to the command-line name #{name.inspect}: " \
+                  "#{commands[name][:command]} and #{spec[:command]} — rename one"
+          end
+
+          commands[name] = spec
+        end
+
+        # The dotted command-line name, `aggregate[.entity].command`, snake-cased.
+        def name_for(aggregate, command, entity = nil)
+          parts = [Naming.snake(aggregate.hecks_name)]
+          parts << Naming.snake(entity.hecks_name) if entity
+          parts << Naming.snake(command.hecks_name)
+          parts.join(".")
+        end
+
+        # The command's language name, `Chapter::Aggregate[.Entity].Verb`, for help text.
+        def fqn(bluebook, aggregate, command, entity = nil)
+          [bluebook.name, "::", aggregate.hecks_name, ".",
+           entity ? "#{entity.hecks_name}." : "", command.hecks_name].join
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,65 @@
+module Hecks
+  module Projector
+    module CliProjector
+      # The `--help` text of one command or query.
+      module CommandHelp
+        # Four independent blocks, concatenated in fixed order: meta, invocation,
+        # arguments, refusals.
+        def command_help(program, name, spec, ask: false)
+          out = command_help_meta_lines(name, spec)
+          out.concat(command_help_invocation_lines(program, name, spec, ask))
+          out.concat(command_help_argument_lines(spec))
+          out.concat(command_help_refusal_lines(spec))
+          out.join("\n")
+        end
+
+        # The title, what the command dispatches or reads, and who issues it.
+        def command_help_meta_lines(name, spec)
+          out = ["#{name} — #{spec[:summary]}", ""]
+          out << "dispatches #{spec[:command]}" if spec[:kind] == :command
+          out << "reads #{spec[:command]}"      if spec[:kind] == :query
+          out << "issued by #{spec[:role]}" if spec[:role]
+          out
+        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}!"
+          ["", "  #{invocation}#{spec[:arguments].map { |a| " #{a[:path]}=…" }.join}", ""]
+        end
+
+        # One line per argument: its path padded to the widest, then its notes.
+        def command_help_argument_lines(spec)
+          return [] if spec[:arguments].empty?
+
+          width = spec[:arguments].map { |a| a[:path].length }.max
+          lines = spec[:arguments].map do |argument|
+            "  #{argument[:path].ljust(width)}  #{argument_notes(argument).join("; ")}"
+          end
+          lines << ""
+        end
+
+        # What an argument's line says about it: type, constraints, note, then `optional`.
+        def argument_notes(argument)
+          [argument[:type], *constraint_notes(argument), *argument[:note], *("optional" unless argument[:required])]
+        end
+
+        # The enum, pattern and default an argument carries.
+        def constraint_notes(argument)
+          notes = []
+          notes << "one of #{argument[:enum].join(", ")}" if argument[:enum]
+          notes << "matches #{argument[:pattern]}"        if argument[:pattern]
+          notes << "defaults to #{argument[:default].inspect}" unless argument[:default].nil?
+          notes
+        end
+
+        # The `refused when:` and `refused unless:` blocks, each present only when it has items.
+        def command_help_refusal_lines(spec)
+          [["refused when:", spec[:refusals]], ["refused unless:", spec[:requirements]]].flat_map do |heading, items|
+            Array(items).empty? ? [] : [heading, *items.map { |item| "  #{item}" }, ""]
+          end
+        end
+      end
+    end
+  end
+end