hecks 3.0.4 → 3.1.0

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

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Projections
+    module Site
+      class Table
+        # One row with its defaults filled in.
+        Row = Struct.new(:path, :kind, :render, :auth, :verbs, :cache, :origin, :source,
+                         :indexable, :switch, :off, :preview, :label, :seo, :redirect_to, :aliases,
+                         :nav_group, :nav_order, :mobile_order, :footer_column, :footer_order,
+                         :admin_key, :admin_order, :compress, :alb_rule, :cdn, keyword_init: true)
+
+        # Turns a declared member into a `Row`: checks its fields and their types, fills the
+        # defaults, and checks each closed-set value against the Site chapter's vocabulary.
+        class RowBuilder
+          # The fields a row may carry, with the Ruby class each takes (`:bool` is true or false).
+          FIELDS = { path: String, kind: String, render: String, auth: String, methods: String,
+                     cache: String, origin: String, source: String, indexable: :bool, switch: String,
+                     off: :bool, preview: String, label: String, seo: String, redirect_to: String,
+                     aliases: String, nav_group: String, nav_order: Integer, mobile_order: Integer,
+                     footer_column: String, footer_order: Integer, admin_key: String,
+                     admin_order: Integer, compress: :bool, alb_rule: String, cdn: :bool }.freeze
+
+          # The value objects of the Site chapter's `Route` aggregate whose members are the closed
+          # sets, by the row field each constrains.
+          VOCABULARY = { kind: "Kind", render: "Render", auth: "Auth", cache: "CacheClass",
+                         origin: "Origin", preview: "Preview" }.freeze
+
+          # A source that names a command or query, whose forms-scheme URL is the route's path.
+          DERIVED_SOURCE = /\A(command|query):([A-Za-z0-9_]+)\.([A-Za-z0-9_]+)\.([A-Za-z0-9_]+)\z/
+          NAMED_SOURCE = /\A(global|collection):[a-z0-9_-]+\z/
+
+          # @param vocabulary [Hash{Symbol => Array<String>}] the closed sets
+          # @param registry [Runtime::Registry, nil] where a `command:` or `query:` is looked up
+          # @param problems [Array<String>] collects each problem found, one line each
+          def initialize(vocabulary:, registry:, problems:)
+            @vocabulary = vocabulary
+            @registry = registry
+            @problems = problems
+          end
+
+          # @param member [Hash{Symbol => Object}] the declared fields of one row
+          # @param index [Integer] the row's position, for a message about a row with no path
+          # @return [Row] the row with its defaults filled in; its problems are in `problems`
+          def call(member, index)
+            label = member[:path] || "row #{index + 1}"
+            fields = checked_fields(member, label)
+            source = fields[:source] || "none"
+            path = fields[:path] || derived_path(source)
+            label = path || label
+            check_source(label, source)
+            verbs = fields.delete(:methods)
+            row = Row.new(**fields, verbs: verbs, path: path, source: source,
+                                    kind: fields[:kind] || default_kind(source), auth: fields[:auth] || "public",
+                                    origin: fields[:origin] || default_origin(source))
+            fill_defaults(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)
+            end
+            known = member.slice(*FIELDS.keys)
+            known.each { |key, value| check_type(label, key, value) }
+            known
+          end
+
+          def check_type(label, key, value)
+            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}"}")
+          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)
+            match = DERIVED_SOURCE.match(source) or return nil
+            "/#{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.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(', ')}")
+            end
+            row.verbs.each do |verb|
+              next if @vocabulary.fetch(:http_method).include?(verb)
+
+              problem(label, "has method #{verb.inspect}; methods are #{@vocabulary.fetch(:http_method).join(', ')}")
+            end
+          end
+
+          def check_source(label, source)
+            match = DERIVED_SOURCE.match(source)
+            unless match || source == "none" || source.match?(NAMED_SOURCE)
+              problem(label, "has source #{source.inspect}; use none, global:<slug>, collection:<name>, " \
+                             "command:<Chapter>.<Aggregate>.<Command> or query:<Chapter>.<Aggregate>.<Query>")
+            end
+            return unless match && @registry
+            return if verb_exists?(*match.captures)
+
+            problem(label, "names #{source}, which no attached chapter declares")
+          end
+
+          def verb_exists?(word, chapter, aggregate, name)
+            found = @registry.bluebook(chapter)&.aggregate(aggregate) or return false
+            (word == "command" ? found.commands : found.queries).any? { |verb| verb.hecks_name == name }
+          end
+
+          def problem(label, text) = @problems << "#{label} #{text}"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require_relative "table/row_builder"
+require_relative "table/checks"
+
+module Hecks
+  module Projections
+    module Site
+      # A client's route table, read from its chapter and checked against the Site chapter's
+      # vocabulary.
+      #
+      # The rows are the `member` lines of a `value_object "Route"` in any chapter of the project
+      # (the Site chapter's own `Route` aggregate names the fields and the closed sets). This class
+      # reads them, fills each row's defaults (the cache class from the auth and kind, the render
+      # from the kind, the path from a `command:` or `query:` source), and refuses a table that
+      # contradicts itself, naming every problem at once.
+      class Table
+        # A table the projection refuses; the message lists each problem on its own line.
+        class Invalid < ArgumentError; end
+
+        # The name of the value object a client declares its rows in.
+        ROW_OBJECT = "Route"
+
+        # @return [Array<Row>] the rows, in the order the client declared them
+        attr_reader :rows
+
+        # Finds the one chapter of a project that declares the route table.
+        #
+        # @param registry [Runtime::Registry] the registry the project booted into
+        # @return [Bluebook::Chapter] the chapter holding the `Route` value object with member rows
+        # @raise [Invalid] when no chapter, or more than one, declares one
+        def self.chapter(registry)
+          holders = registry.bluebooks.values.reject { |chapter| chapter.name == "Site" }
+                            .select { |chapter| rows_of(chapter).any? }
+          raise Invalid, "no chapter declares a value_object \"#{ROW_OBJECT}\" with member rows" if holders.empty?
+          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"
+        end
+
+        # Reads and checks one chapter's route table.
+        #
+        # @param chapter [Bluebook::Chapter] the chapter that declares the rows
+        # @param registry [Runtime::Registry] the registry the project booted into: it holds the
+        #   Site chapter and, for a `command:` or `query:` source, the command or query
+        # @return [Table] the checked table
+        # @raise [Invalid] when the Site chapter is not attached or a row is refused
+        def self.read(chapter, registry:)
+          new(rows_of(chapter), vocabulary: vocabulary(registry), registry: registry)
+        end
+
+        # @param registry [Runtime::Registry] a registry holding the Site chapter
+        # @return [Hash{Symbol => Array<String>}] each constrained field to its allowed values, and
+        #   `:http_method` to the verbs a route may answer
+        # @raise [Invalid] when the registry does not hold the Site chapter
+        def self.vocabulary(registry)
+          site = registry.bluebook("Site") or
+            raise Invalid, "the project does not attach the Site chapter (attaches \"Site\")"
+          route = site.aggregate("Route")
+          members = lambda do |name|
+            route.value_objects.find { |object| object.hecks_name == name }.members.map { |member| member.fetch(:value) }
+          end
+          RowBuilder::VOCABULARY.transform_values(&members).merge(http_method: members.call("HttpMethod"))
+        end
+
+        # @param chapter [Bluebook::Chapter] a chapter to search
+        # @param object [String] the name of the value object whose rows are wanted
+        # @return [Array<Hash{Symbol => Object}>] the member rows of its value objects of that name
+        def self.rows_of(chapter, object = ROW_OBJECT)
+          chapter.aggregates.flat_map(&:value_objects)
+                 .select { |candidate| candidate.hecks_name == object }.flat_map(&:members)
+        end
+
+        # @param members [Array<Hash{Symbol => Object}>] the declared member rows
+        # @param vocabulary [Hash{Symbol => Array<String>}] the closed sets
+        # @param registry [Runtime::Registry, nil] where a `command:` or `query:` source is looked
+        #   up; nil skips that check
+        # @raise [Invalid] when a row is refused
+        def initialize(members, vocabulary:, registry: nil)
+          problems = []
+          builder = RowBuilder.new(vocabulary: vocabulary, registry: registry, problems: problems)
+          @rows = members.each_with_index.map { |member, index| builder.call(member, index) }
+          Checks.new(@rows, problems).call
+          return if problems.empty?
+
+          raise Invalid, "the route table is refused:\n#{problems.map { |line| "  - #{line}" }.join("\n")}"
+        end
+
+        # The navigation slots a row sits in.
+        #
+        # @param row [Row] a row
+        # @return [Array<String>] some of `desktop`, `mobile`, `footer`, `admin`
+        def navigation(row) = Checks.navigation(row)
+      end
+    end
+  end
+end

data/lib/hecks/projections.rb

@@ -22,5 +22,7 @@ require_relative "projections/glossary"
 require_relative "projections/deploy/shared"
 require_relative "projections/deploy/lambda"
 require_relative "projections/deploy/fargate"
+require_relative "projections/deploy/box"
 require_relative "projections/deploy/smoke"
 require_relative "projections/deploy/template_diff"
+require_relative "projections/site/routes_ts"