hecks 3.5.0 → 3.6.0

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

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Hecks
+  module Projections
+    module Site
+      module Payload
+        module Specs
+          # The TypeScript for how an aggregate's attributes cross the wire: the lines that read
+          # each one from the host's state, and the lines that write each one from an input.
+          module Wire
+            module_function
+
+            def others(agg) = agg.attrs.reject { |attr| attr.name == agg.identity }
+
+            def reads(agg)
+              others(agg).map { |attr| "      #{attr.ts}: #{read(agg, attr)}," }.join("\n")
+            end
+
+            def read(agg, attr)
+              return "#{Specs.reader(agg, attr)}(s.#{attr.name})" if attr.shape == :composite
+              return "unwrapList(s.#{attr.name})" if attr.list
+              return "whole(s.#{attr.name}, #{attr.wire_key.to_json})" if attr.shape == :integer
+
+              attr.optional ? "orNull(s.#{attr.name})" : "orNull(s.#{attr.name}) ?? \"\""
+            end
+
+            def writes(agg)
+              others(agg).map { |attr| "    #{write(attr)}," }.join("\n")
+            end
+
+            def write(attr)
+              name = attr.name
+              case attr.shape
+              when :composite then composite_write(attr)
+              when :integer then optional_write(attr, "{ #{attr.wire_key}: input.#{attr.ts} }", "input.#{attr.ts} != null")
+              else
+                return "#{name}: list(input.#{attr.ts})" if attr.list
+
+                scalar_write(attr)
+              end
+            end
+
+            def composite_write(attr)
+              parts = attr.parts.map { |part| "#{part.name}: item.#{part.ts}" }.join(", ")
+              "#{attr.name}: input.#{attr.ts}.map((item) => ({ #{parts} }))"
+            end
+
+            def scalar_write(attr)
+              if attr.wire_key == "value"
+                return "#{attr.name}: wrapped(input.#{attr.ts})" unless attr.optional
+
+                return "...optionalValue(#{attr.name.to_json}, input.#{attr.ts})"
+              end
+              optional_write(attr, "{ #{attr.wire_key}: input.#{attr.ts} }", "input.#{attr.ts}")
+            end
+
+            def optional_write(attr, wire, present)
+              return "#{attr.name}: #{wire}" unless attr.optional
+
+              "...(#{present} ? { #{attr.name}: #{wire} } : {})"
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "json"
+require_relative "specs/wire"
 
 module Hecks
   module Projections
@@ -28,8 +29,8 @@ module 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};
+              import { #{imports.join(", ")} } from #{hecks.to_json};
+              import { #{names.join(", ")} } from #{lifecycle.to_json};
             TS
           end
 
@@ -94,75 +95,30 @@ module Hecks
 
           def reader(agg, attr) = "#{agg.noun[0].downcase}#{agg.noun[1..]}#{attr.ts[0].upcase}#{attr.ts[1..]}From"
 
-          def spec(agg)
-            var = "#{agg.noun[0].downcase}#{agg.noun[1..]}"
-            <<~TS.chomp
-              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),
-              #{reads(agg)}
-                  })),
-                toInput: ({ status: _status, ...input }) => input,
-                fields: (input): Wire => ({
-              #{writes(agg)}
-                }),
-                create: { verb: #{agg.create[:verb].to_json}, status: #{agg.create[:status].to_json} },
-                edges: #{edges(agg.edges)},
-              };
-            TS
-          end
-
-          def others(agg) = agg.attrs.reject { |attr| attr.name == agg.identity }
-
-          def reads(agg)
-            others(agg).map { |attr| "      #{attr.ts}: #{read(agg, attr)}," }.join("\n")
-          end
-
-          def read(agg, attr)
-            return "#{reader(agg, attr)}(s.#{attr.name})" if attr.shape == :composite
-            return "unwrapList(s.#{attr.name})" if attr.list
-            return "whole(s.#{attr.name}, #{attr.wire_key.to_json})" if attr.shape == :integer
-
-            attr.optional ? "orNull(s.#{attr.name})" : "orNull(s.#{attr.name}) ?? \"\""
-          end
-
-          def writes(agg)
-            others(agg).map { |attr| "    #{write(attr)}," }.join("\n")
-          end
-
-          def write(attr)
-            name = attr.name
-            case attr.shape
-            when :composite then composite_write(attr)
-            when :integer then optional_write(attr, "{ #{attr.wire_key}: input.#{attr.ts} }", "input.#{attr.ts} != null")
-            else
-              return "#{name}: list(input.#{attr.ts})" if attr.list
-
-              scalar_write(attr)
-            end
-          end
-
-          def composite_write(attr)
-            parts = attr.parts.map { |part| "#{part.name}: item.#{part.ts}" }.join(", ")
-            "#{attr.name}: input.#{attr.ts}.map((item) => ({ #{parts} }))"
-          end
-
-          def scalar_write(attr)
-            if attr.wire_key == "value"
-              return "#{attr.name}: wrapped(input.#{attr.ts})" unless attr.optional
+          # The three lines between a spec's reads and its writes.
+          SPEC_MIDDLE = ["    })),",
+                         "  toInput: ({ status: _status, ...input }) => input,",
+                         "  fields: (input): Wire => ({"].freeze
 
-              return "...optionalValue(#{attr.name.to_json}, input.#{attr.ts})"
-            end
-            optional_write(attr, "{ #{attr.wire_key}: input.#{attr.ts} }", "input.#{attr.ts}")
+          def spec(agg)
+            [*spec_head(agg), Wire.reads(agg), *SPEC_MIDDLE, Wire.writes(agg), *spec_tail(agg)].join("\n")
           end
 
-          def optional_write(attr, wire, present)
-            return "#{attr.name}: #{wire}" unless attr.optional
-
-            "...(#{present} ? { #{attr.name}: #{wire} } : {})"
+          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)

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

@@ -13,16 +13,13 @@ module Hecks
     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.
+      # 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.
+      # 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
 
@@ -50,8 +47,7 @@ skip: String },
         # @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
+        #   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: {})
@@ -67,19 +63,25 @@ skip: String },
 
         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
 
-          from_driver = ->(path) { relative(path, "#{out}/driver") }
-          from_collections = ->(path) { relative(path, "#{out}/collections") }
-          { "#{out}/driver/lifecycle.ts"   => Payload::Lifecycle.render(role: roles.first, hecks: from_driver.call(row[:hecks])),
-            "#{out}/driver/specs.ts"       => Payload::Specs.render(aggregates, lifecycle: "./lifecycle",
-                                                                                hecks:     from_driver.call(row[:hecks])),
-            "#{out}/collections/fields.ts" => Payload::Fields.render(aggregates, rows: rows, specs: "../driver/specs",
-                                                                     helpers: from_collections.call(row[:helpers])) }
+          roles.first
         end
 
         # @return [String] `path` as an import from `dir`, both relative to the project root

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

@@ -43,15 +43,23 @@ module Hecks
 
         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?
+          problems << "#{label} has no field #{unknown.join(", ")}; fields are #{@fields.keys.join(", ")}" if unknown.any?
           (@required - member.keys).each { |field| problems << "#{label} needs #{field}" }
-          typed = member.slice(*@fields.keys).select do |field, value|
+        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 ')}")
+              (problems << "#{label} has #{field} #{value.inspect}; it is a #{kinds.join(" or ")}")
           end
-          @defaults.merge(typed)
         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