hecks 3.4.2 → 3.6.0

data/lib/hecks/projections/site/payload/specs.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "specs/wire"
+
+module Hecks
+  module Projections
+    module Site
+      module Payload
+        # The TypeScript the content system drives each aggregate with: its input type, how an input
+        # goes over the wire, how the host's state reads back into one, and the lifecycle the domain
+        # allows. The decisions that turn these into commands are in the lifecycle module, which the
+        # specs only describe.
+        module Specs
+          BANNER = "// Generated by hecks site site_projection.project_site. Do not edit."
+
+          module_function
+
+          # @param aggregates [Array<Model::Aggregate>] the aggregates to drive
+          # @param lifecycle [String] the import path of the lifecycle module
+          # @param hecks [String] the import path of the module that talks to the host
+          # @return [String] the module
+          def render(aggregates, lifecycle:, hecks:)
+            body = aggregates.map { |agg| aggregate(agg) }.join("\n\n")
+            [BANNER, header(aggregates, lifecycle, hecks), helpers(aggregates), body].reject(&:empty?).join("\n\n") << "\n"
+          end
+
+          def header(aggregates, lifecycle, hecks)
+            imports = %w[instancesOf] + (uses?(aggregates, :integer) ? %w[whole] : [])
+            names = %w[optionalValue statusOf unwrap unwrapList wrapped] + %w[type\ Instance type\ Spec type\ Wire]
+            <<~TS.chomp
+              import { #{imports.join(", ")} } from #{hecks.to_json};
+              import { #{names.join(", ")} } from #{lifecycle.to_json};
+            TS
+          end
+
+          def helpers(aggregates)
+            <<~TS.chomp
+              const list = (items: string[]) => items.map(wrapped);
+              const orNull = (value: unknown) => unwrap(value);#{composite_reader(aggregates)}
+            TS
+          end
+
+          def composite_reader(aggregates)
+            return "" unless uses?(aggregates, :composite)
+
+            <<~TS.chomp.prepend("\n")
+              const text = (value: unknown) => (typeof value === "string" ? value : "");
+            TS
+          end
+
+          def uses?(aggregates, shape) = aggregates.any? { |agg| agg.attrs.any? { |attr| attr.shape == shape } }
+
+          def aggregate(agg)
+            [heading(agg), composites(agg), input_type(agg), state_type(agg), composite_readers(agg), spec(agg)]
+              .reject(&:empty?).join("\n\n")
+          end
+
+          def heading(agg) = "// ---- #{agg.noun} ----"
+
+          def composites(agg)
+            agg.attrs.select { |attr| attr.shape == :composite }.map do |attr|
+              fields = attr.parts.map { |part| "  #{part.ts}: string;" }.join("\n")
+              "export interface #{attr.type} {\n#{fields}\n}"
+            end.join("\n\n")
+          end
+
+          def input_type(agg)
+            fields = agg.attrs.map { |attr| "  #{attr.ts}: #{ts_type(attr)};" }.join("\n")
+            "export interface #{agg.noun}Input {\n#{fields}\n}"
+          end
+
+          def state_type(agg) = "export type #{agg.noun}State = #{agg.noun}Input & Instance;"
+
+          def ts_type(attr)
+            base = if attr.shape == :integer
+                     "number"
+                   else
+                     (attr.shape == :composite ? attr.type : "string")
+                   end
+            return "#{base}[]" if attr.list
+
+            attr.optional ? "#{base} | null" : base
+          end
+
+          def composite_readers(agg)
+            agg.attrs.select { |attr| attr.shape == :composite }.map do |attr|
+              parts = attr.parts.map { |part| "#{part.ts}: text(s.#{part.name})" }.join(", ")
+              <<~TS.chomp
+                const #{reader(agg, attr)} = (value: unknown): #{attr.type}[] =>
+                  Array.isArray(value) ? value.map((raw) => { const s = (raw ?? {}) as Record<string, unknown>; return { #{parts} }; }) : [];
+              TS
+            end.join("\n\n")
+          end
+
+          def reader(agg, attr) = "#{agg.noun[0].downcase}#{agg.noun[1..]}#{attr.ts[0].upcase}#{attr.ts[1..]}From"
+
+          # The three lines between a spec's reads and its writes.
+          SPEC_MIDDLE = ["    })),",
+                         "  toInput: ({ status: _status, ...input }) => input,",
+                         "  fields: (input): Wire => ({"].freeze
+
+          def spec(agg)
+            [*spec_head(agg), Wire.reads(agg), *SPEC_MIDDLE, Wire.writes(agg), *spec_tail(agg)].join("\n")
+          end
+
+          def spec_head(agg)
+            var = "#{agg.noun[0].downcase}#{agg.noun[1..]}"
+            ["export const #{var}Spec: Spec<#{agg.noun}State, #{agg.noun}Input> = {",
+             "  aggregate: #{agg.fqn.to_json},",
+             "  read: (answer) =>",
+             "    instancesOf(answer, #{agg.fqn.to_json}).map(([#{agg.identity}, s]) => ({",
+             "      #{agg.identity},",
+             "      status: statusOf(s),"]
+          end
+
+          def spec_tail(agg)
+            ["  }),",
+             "  create: { verb: #{agg.create[:verb].to_json}, status: #{agg.create[:status].to_json} },",
+             "  edges: #{edges(agg.edges)},",
+             "};"]
+          end
+
+          def edges(edges)
+            rows = edges.map do |status, moves|
+              inner = moves.map { |verb, target| "#{verb}: #{target.to_json}" }.join(", ")
+              "    #{status}: { #{inner} },"
+            end
+            "{\n#{rows.join("\n")}\n  }"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require "pathname"
+require_relative "../../projector"
+require_relative "root_rows"
+require_relative "payload/model"
+require_relative "payload/specs"
+require_relative "payload/fields"
+require_relative "payload/lifecycle"
+
+module Hecks
+  module Projections
+    module Site
+      # What the content system needs to drive a domain's aggregates, from the domain itself: the
+      # lifecycle module, a spec per aggregate (its input, its wire form, its lifecycle edges and
+      # the command that creates it) and the Payload field definitions with the readers that turn a
+      # saved document back into an input.
+      #
+      # A `Payload` row names the domain, its chapter and where the files go; `PayloadField` rows
+      # say what the editor needs that an attribute's shape cannot (a date picker, a choice list,
+      # an upload, a relation). The domain stays free of the content system: it is read, never
+      # annotated.
+      module PayloadDriver
+        extend Projector::Target
+
+        projects_as :payload_driver, emits: :files
+
+        # The `Payload` row.
+        PAYLOAD = RootRows.new("Payload",
+                               fields:   { domain: String, chapter: String, out: String, hecks: String, helpers: String,
+skip: String },
+                               required: %i[domain chapter],
+                               defaults: { out: "cms/src/generated", hecks: "cms/src/driver/hecks",
+                                           helpers: "cms/src/collections/hooks/content", skip: "" })
+
+        # A `PayloadField` row: what the editor needs for one attribute (or `attribute.part` of a
+        # composite).
+        FIELD = RootRows.new("PayloadField",
+                             fields: { aggregate: String, attribute: String, field: String, kind: String, options: String,
+                                       relation: String, via: String, label: String, description: String,
+                                       required: [TrueClass, FalseClass],
+                                       default: String },
+                             required: %i[aggregate attribute], many: true)
+
+        module_function
+
+        # @param bluebook [Bluebook::Chapter] the chapter that declares the route table and the rows
+        # @param options [Hash{Symbol => Object}] `:domain_chapter` the domain's chapter, or nil
+        # @return [Hash{String => String}] each file's path relative to the project root to its
+        #   text; empty when the project declares no `Payload` row
+        # @raise [Table::Invalid] when a row is refused
+        # @raise [ArgumentError] when an aggregate cannot be driven or a row names what is not there
+        def call(bluebook:, options: {})
+          row = PAYLOAD.read(bluebook).first
+          return {} unless row
+
+          chapter = options.fetch(:domain_chapter)
+          aggregates = Payload::Model.read(chapter, skip: row[:skip].split(",").map(&:strip))
+          raise ArgumentError, "the #{chapter.name} chapter has no aggregate with a lifecycle to drive" if aggregates.empty?
+
+          files(row, aggregates, FIELD.read(bluebook))
+        end
+
+        def files(row, aggregates, rows)
+          out = row[:out]
+          role = driver_role(aggregates)
+          hecks = relative(row[:hecks], "#{out}/driver")
+          helpers = relative(row[:helpers], "#{out}/collections")
+          { "#{out}/driver/lifecycle.ts"   => Payload::Lifecycle.render(role: role, hecks: hecks),
+            "#{out}/driver/specs.ts"       => Payload::Specs.render(aggregates, lifecycle: "./lifecycle", hecks: hecks),
+            "#{out}/collections/fields.ts" => Payload::Fields.render(aggregates, rows: rows, specs: "../driver/specs",
+                                                                     helpers: helpers) }
+        end
+
+        # @return [String, nil] the one role every driven command declares
+        # @raise [ArgumentError] when the aggregates' commands declare more than one
+        def driver_role(aggregates)
+          roles = aggregates.map(&:role).uniq
+          if roles.size > 1
+            raise ArgumentError,
+                  "the driven aggregates' commands declare roles #{roles.inspect}; the driver acts as one"
+          end
+
+          roles.first
+        end
+
+        # @return [String] `path` as an import from `dir`, both relative to the project root
+        def relative(path, dir)
+          target = Pathname.new(path).relative_path_from(Pathname.new(dir)).to_s
+          target.start_with?(".") ? target : "./#{target}"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require_relative "table"
+
+module Hecks
+  module Projections
+    module Site
+      # Reads and checks the rows a project declares beside its route table for the files at the
+      # project's root, one row object at a time: the fields it may carry, the Ruby class each
+      # takes, which are required and what the others default to.
+      #
+      # A row that is refused raises `Table::Invalid` naming every problem, so a project sees all of
+      # them at once.
+      class RootRows
+        # @param object [String] the value object the rows are declared in
+        # @param fields [Hash{Symbol => Class, Array<Class>}] the fields a row may carry, by class
+        # @param required [Array<Symbol>] the fields a row must carry
+        # @param defaults [Hash{Symbol => Object}] what a field takes when the row omits it
+        # @param many [Boolean] whether the project may declare more than one row
+        def initialize(object, fields:, required: [], defaults: {}, many: false)
+          @object = object
+          @fields = fields
+          @required = required
+          @defaults = defaults
+          @many = many
+        end
+
+        # @param chapter [Bluebook::Chapter] the chapter that declares the route table
+        # @return [Array<Hash{Symbol => Object}>] each checked row, defaults filled; empty when the
+        #   chapter declares none
+        # @raise [Table::Invalid] when a row is refused
+        def read(chapter)
+          members = Table.rows_of(chapter, @object)
+          problems = []
+          problems << "a project declares one #{@object} row, not #{members.size}" if members.size > 1 && !@many
+          rows = members.each_with_index.map { |member, index| check(member, index, problems) }
+          return rows if problems.empty?
+
+          raise Table::Invalid, "the #{@object} rows are refused:\n#{problems.map { |line| "  - #{line}" }.join("\n")}"
+        end
+
+        private
+
+        def check(member, index, problems)
+          label = "#{@object} row #{index + 1}"
+          check_fields(member, label, problems)
+          @defaults.merge(typed_fields(member, label, problems))
+        end
+
+        def check_fields(member, label, problems)
+          unknown = member.keys - @fields.keys
+          problems << "#{label} has no field #{unknown.join(", ")}; fields are #{@fields.keys.join(", ")}" if unknown.any?
+          (@required - member.keys).each { |field| problems << "#{label} needs #{field}" }
+        end
+
+        # A field of the wrong class is recorded as a problem and kept, so the row still reads.
+        def typed_fields(member, label, problems)
+          member.slice(*@fields.keys).select do |field, value|
+            kinds = Array(@fields.fetch(field))
+            kinds.any? { |kind| value.is_a?(kind) } ||
+              (problems << "#{label} has #{field} #{value.inspect}; it is a #{kinds.join(" or ")}")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projections/site/routes_ts/helpers.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Projections
+    module Site
+      module RoutesTs
+        # The pure TypeScript helpers every `routes.ts` ends with: path matching, then the page
+        # switches, search exclusion and draft previews. They are the same text for every table.
+        module Helpers
+          # Path matching: `stripHtml` and `matchesPath`.
+          PATH = <<~'TS'.chomp
+            /** Drops a trailing `.html` and a trailing slash, so `/about.html`, `/about/` and `/about` are one path. */
+            export function stripHtml(pathname: string): string {
+              const bare = pathname.endsWith(".html") ? pathname.slice(0, -".html".length) : pathname;
+              return bare.length > 1 && bare.endsWith("/") ? bare.slice(0, -1) : bare;
+            }
+
+            function toRegExp(pattern: string): RegExp {
+              const source = stripHtml(pattern)
+                .split("/")
+                .map((part) =>
+                  part.startsWith(":")
+                    ? "[^/]+"
+                    : part
+                        .split("*")
+                        .map((piece) => piece.replace(/[.+?^${}()|[\]\\]/g, "\\$&"))
+                        .join(".*"),
+                )
+                .join("/");
+              return new RegExp("^" + source + "$");
+            }
+
+            /**
+             * Whether a pathname is one a route pattern describes, with or without `.html`. A `:name` is one
+             * segment; a `*` is any run of characters, `/` included, wherever it stands, as in a CDN's path
+             * pattern: `/pay/*` matches `/pay/7` and `/admin*` matches `/admin`, `/admin-inbox` and `/admin/x`.
+             */
+            export function matchesPath(pattern: string, pathname: string): boolean {
+              return toRegExp(pattern).test(stripHtml(pathname));
+            }
+          TS
+
+          # Page switches, search exclusion and draft previews.
+          PAGE = <<~'TS'.chomp
+            /** Whether a page is on: true for an id no row switches off, and for an id no row names. */
+            export function pageIsOn(id: string): boolean {
+              return Object.prototype.hasOwnProperty.call(SWITCHES, id) ? SWITCHES[id] : true;
+            }
+
+            /** Whether a pathname belongs to a switched-off page, with or without `.html`. */
+            export function isOffPath(pathname: string): boolean {
+              return MIDDLEWARE.off.paths.some((pattern) => matchesPath(pattern, pathname));
+            }
+
+            /** Whether a search engine is kept away from a pathname. */
+            export function notForSearch(pathname: string): boolean {
+              return NOT_FOR_SEARCH.some((pattern) => matchesPath(pattern, pathname));
+            }
+
+            /** The URL that previews a CMS source (`global:<slug>` or `collection:<name>`), under the preview prefix when it is a draft. */
+            export function previewUrl(source: string, slug?: string): string {
+              const entry = PREVIEWS[source];
+              if (entry === undefined) throw new Error(`no route has the source ${source}`);
+              let path = entry.path;
+              if (path.includes(":")) {
+                if (slug === undefined) throw new Error(`${source} previews one entry: pass its slug`);
+                path = path.replace(/:[A-Za-z_]\w*/, encodeURIComponent(slug));
+              }
+              return entry.draft ? MIDDLEWARE.preview.prefix + stripHtml(path) : path;
+            }
+          TS
+
+          # @return [String] both groups of helpers, as one block of TypeScript
+          def self.text = [PATH, PAGE].join("\n\n")
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projections/site/routes_ts/listings.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Projections
+    module Site
+      module RoutesTs
+        # The lists `routes.ts` derives from the rows for search engines and the content system:
+        # the sitemap and robots paths, and the content-system sources that name a page.
+        module Listings
+          module_function
+
+          def search(rows)
+            <<~TS.chomp
+              // The paths a sitemap lists: indexable pages with no parameter. A collection's pages are listed
+              // from its entries, through `collectionPages`.
+              export const SITEMAP_PATHS = #{RoutesTs.literal(sitemap_paths(rows))} as const;
+
+              // The routes a search engine is kept away from: every route that is not indexable.
+              export const NOT_FOR_SEARCH = #{RoutesTs.literal(hidden_paths(rows))} as const;
+
+              // robots.txt `Disallow` prefixes: each non-public route up to its first parameter.
+              export const ROBOTS_DISALLOW = #{RoutesTs.literal(robots(RoutesTs.live(rows)))} as const;
+            TS
+          end
+
+          def sitemap_paths(rows)
+            RoutesTs.live(rows).select { |row| row.indexable && !row.path.match?(/[:*]/) }.map(&:path).sort
+          end
+
+          def hidden_paths(rows)
+            hidden = rows.reject { |row| row.indexable || row.path == RoutesTs::CATCH_ALL }
+            hidden.flat_map { |row| [row.path, *row.aliases] }.sort
+          end
+
+          def robots(rows)
+            prefixes = rows.reject { |row| row.auth == "public" }.map { |row| robots_prefix(row.path) }
+            prefixes = (prefixes + ["#{RoutesTs::PREVIEW_PREFIX}/"]).uniq.sort
+            prefixes.reject { |prefix| prefixes.any? { |other| other != prefix && prefix.start_with?(other) } }
+          end
+
+          def robots_prefix(path)
+            head = path.split("/").take_while { |part| !part.match?(/\A[:*]/) }.join("/")
+            head == path ? path : "#{head}/"
+          end
+
+          def sources(rows)
+            <<~TS.chomp
+              // A CMS global's slug to the page that shows it.
+              export const globalPages = #{RoutesTs.literal(sourced(rows, "global:", &:path))} as const;
+
+              // A CMS collection's name to the page that shows one of its entries, and whether the sitemap lists them.
+              export const collectionPages = #{RoutesTs.literal(collection_pages(rows))} as const;
+
+              const PREVIEWS: Readonly<Record<string, { readonly path: string; readonly draft: boolean }>> = #{RoutesTs.literal(previews(rows))};
+            TS
+          end
+
+          def collection_pages(rows)
+            sourced(rows, "collection:") { |row| { path: row.path, indexable: row.indexable } }
+          end
+
+          def previews(rows)
+            rows.select { |row| row.source.match?(/\A(global|collection):/) }
+                .to_h { |row| [row.source, { path: row.path, draft: row.preview == "draft" }] }.sort.to_h
+          end
+
+          def sourced(rows, prefix)
+            rows.select { |row| row.source.start_with?(prefix) }
+                .to_h { |row| [row.source.delete_prefix(prefix), yield(row)] }.sort.to_h
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projections/site/routes_ts/navigation.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Projections
+    module Site
+      module RoutesTs
+        # The four navigation arrays of `routes.ts`: desktop, mobile, footer and admin.
+        #
+        # They hold every entry that has a slot, a switched-off page's too: an entry of an off page
+        # carries its `switch` and `on: false`, and the site drops it while `pageIsOn(switch)` is
+        # false. An entry of a page that is on carries neither.
+        module Navigation
+          module_function
+
+          # @param table [Table] a checked table
+          # @return [String] the four `NAV_*` constants, as TypeScript
+          def render(table)
+            items = table.rows + table.links
+            [nav_const("NAV_DESKTOP", "The desktop navigation: a page with no group is its own entry; a group holds its pages.",
+                       desktop(items)),
+             nav_const("NAV_MOBILE", "The mobile navigation, in its own order.", mobile(items)),
+             nav_const("NAV_FOOTER", "The footer columns, left to right, each with its links.", footer(items)),
+             nav_const("NAV_ADMIN", "The admin navigation: each admin page under its key.", admin(items))].join("\n\n")
+          end
+
+          def nav_const(name, comment, entries)
+            body = entries.map { |entry| "  #{RoutesTs.literal(entry)}," }
+            "// #{comment}\nexport const #{name} = #{body.empty? ? "[]" : "[\n#{body.join("\n")}\n]"} as const;"
+          end
+
+          # One link: a row's or a link's path and label, the fragment a link names, and for a page
+          # that is off the switch that turns it on.
+          def entry(item, **before)
+            link = { **before, path: item.path, label: item.label }
+            link[:fragment] = item.fragment if item.respond_to?(:fragment) && item.fragment
+            if item.off
+              link[:switch] = item.switch
+              link[:on] = false
+            end
+            link
+          end
+
+          def order_key(item, order) = [order, item.path, item.respond_to?(:fragment) ? item.fragment.to_s : ""]
+
+          def desktop(items)
+            entries = []
+            items.reject { |item| item.nav_order.nil? }.sort_by { |item| order_key(item, item.nav_order) }
+                 .each { |item| place(entries, item) }
+            entries
+          end
+
+          # Adds the item to its group's entry, opening the group's entry when it is the first.
+          def place(entries, item)
+            group = item.nav_group
+            slot = group && entries.find { |candidate| candidate[:group] == group }
+            slot ? slot[:items] << entry(item) : entries << { group: group, items: [entry(item)] }
+          end
+
+          def mobile(items)
+            items.reject { |item| item.mobile_order.nil? }.sort_by { |item| order_key(item, item.mobile_order) }
+                 .map { |item| item.mobile_heading ? entry(item, heading: item.mobile_heading) : entry(item) }
+          end
+
+          def footer(items)
+            ordered = items.select(&:footer_column).sort_by { |item| order_key(item, item.footer_order) }
+            columns = ordered.group_by(&:footer_column)
+            columns.sort_by { |name, group| [group.first.footer_order, name] }
+                   .map { |name, group| { column: name, items: group.map { |item| entry(item) } } }
+          end
+
+          def admin(items)
+            items.select(&:admin_key).sort_by { |item| [item.admin_order, item.admin_key] }
+                 .map { |item| entry(item, key: item.admin_key) }
+          end
+        end
+      end
+    end
+  end
+end