hecks 3.0.4 → 3.1.0

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

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Projections
+    module Site
+      # The marked regions of a template a project owns, where the generated blocks go.
+      #
+      # A region is a pair of comment lines, `# BEGIN GENERATED site_cdn <name> ...` and
+      # `# END GENERATED site_cdn <name>`, at the indentation the block's lines take. Everything
+      # outside the pair is the project's; everything inside is replaced on each run.
+      module Regions
+        module_function
+
+        # @param name [String] a region's name
+        # @return [Regexp] the region: its begin line, whatever is inside, its end line
+        def pattern(name)
+          escaped = Regexp.escape(name)
+          /^([ \t]*)# BEGIN GENERATED site_cdn #{escaped}\b[^\n]*\n.*?^\1# END GENERATED site_cdn #{escaped}$/m
+        end
+
+        # @param text [String] a template
+        # @param name [String] a region's name
+        # @return [Boolean] whether the template has the region
+        def region?(text, name) = text.match?(pattern(name))
+
+        # @param text [String] a template
+        # @param name [String] a region's name
+        # @param block [String] the lines that go inside, from the left margin
+        # @return [String] the template with the region's markers and block rewritten
+        def replace(text, name, block)
+          text.sub(pattern(name)) do
+            indent = Regexp.last_match(1)
+            [
+              "#{indent}# BEGIN GENERATED site_cdn #{name} (hecks site site_projection.project_site; " \
+              "edit the Route and Edge rows). Do not hand-edit.",
+              block.each_line.map { |line| line.strip.empty? ? line : "#{indent}#{line}" }.join.chomp,
+              "#{indent}# END GENERATED site_cdn #{name}"
+            ].join("\n")
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,284 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../../projector"
+require_relative "table"
+
+module Hecks
+  module Projections
+    module Site
+      # A site's route table as one dependency-free TypeScript module, `routes.ts`.
+      #
+      # The module holds the table as `as const` data and the few pure helpers the site's
+      # middleware, navigation, sitemap, robots file and content system need over it, so each reads
+      # one file instead of carrying its own copy of which pages exist. Nothing in it depends on a
+      # framework: it is an ES module that Node (type stripping) and any bundler load as it stands.
+      #
+      # The text is a pure function of the table: rows keep the order the client declared them in,
+      # every list derived from them is sorted by an explicit key, and nothing in it names a time
+      # or a machine, so regenerating from the same table changes nothing.
+      module RoutesTs
+        extend Projector::Target
+
+        projects_as :site_routes_ts, emits: :files
+
+        # The banner every generated file starts with.
+        BANNER = "// Generated by hecks site site_projection.project_site. Do not edit."
+
+        # The path of the row that stands for the edge's default behaviour. It matches every path,
+        # so it hides none from search.
+        CATCH_ALL = "/*"
+
+        # The URL prefix under which a draft preview is served.
+        PREVIEW_PREFIX = "/admin-preview"
+
+        module_function
+
+        # Renders `routes.ts` for a route table.
+        #
+        # @param bluebook [Bluebook::Chapter] the chapter that declares the route table
+        # @param options [Hash{Symbol => Object}] `:registry` (Runtime::Registry) the project booted
+        #   into, which holds the Site chapter; `:table` (Table) a table already read, instead
+        # @return [Hash{String => String}] `"routes.ts"` to its text
+        # @raise [Table::Invalid] when the table is refused
+        def call(bluebook:, options: {})
+          table = options[:table] || Table.read(bluebook, registry: options.fetch(:registry))
+          { "routes.ts" => render(table) }
+        end
+
+        # @param table [Table] a checked table
+        # @return [String] the module's text, ending in a newline
+        def render(table)
+          rows = table.rows
+          [BANNER, header, routes(rows), types, switches(rows), redirects(rows), middleware(rows),
+           navigation(table), search(rows), sources(rows), helpers].join("\n\n") << "\n"
+        end
+
+        # @param rows [Array<Table::Row>] the table's rows
+        # @return [Array<Table::Row>] the rows that exist: those not switched off
+        def live(rows) = rows.reject(&:off)
+
+        def header
+          <<~TS.chomp
+            // The route table of this site, projected from its bluebook's Route rows. Change the rows and run
+            // `hecks site site_projection.project_site`; `hecks site site_projection.project_site --check` fails when this file is out of date.
+          TS
+        end
+
+        def types
+          <<~TS.chomp
+            export type Route = (typeof ROUTES)[number];
+          TS
+        end
+
+        def routes(rows)
+          lines = rows.map { |row| "  #{literal(route_fields(row))}," }
+          "export const ROUTES = [\n#{lines.join("\n")}\n] as const;"
+        end
+
+        def route_fields(row)
+          { path: row.path, kind: row.kind, render: row.render, auth: row.auth, methods: row.verbs,
+            cache: row.cache, origin: row.origin, source: row.source, indexable: row.indexable,
+            switch: blank_to_nil(row.switch), off: row.off, preview: row.preview,
+            label: blank_to_nil(row.label), seo: blank_to_nil(row.seo), redirectTo: row.redirect_to }
+        end
+
+        def switches(rows)
+          switched = rows.reject { |row| row.switch.empty? }.group_by(&:switch)
+          ids = switched.sort.to_h { |id, group| [id.to_sym, group.none?(&:off)] }
+          "// A page's switch: false while the page is off. A page without a switch is always on.\n" \
+            "export const SWITCHES: Readonly<Record<string, boolean>> = #{literal(ids)};"
+        end
+
+        def redirects(rows)
+          pairs = rows.flat_map do |row|
+            targeted = row.kind == "redirect" ? [[row.path, row.redirect_to]] : []
+            targeted + row.aliases.map { |from| [from, row.path] }
+          end
+          items = pairs.sort.map { |from, to| "  #{literal({ from: from, to: to, status: 301 })}," }
+          "export const REDIRECTS = [\n#{items.join("\n")}\n] as const;".sub("[\n\n]", "[]")
+        end
+
+        def middleware(rows)
+          off = rows.select(&:off).flat_map { |row| [row.path, *row.aliases] }.sort
+          <<~TS.chomp
+            // The three rules the site's middleware applies, as data: a switched-off page answers 404, a
+            // request under the preview prefix is served from draft content, and `.html` is dropped.
+            export const MIDDLEWARE = {
+              off: { status: 404, paths: #{literal(off)} },
+              preview: { prefix: #{literal(PREVIEW_PREFIX)} },
+              stripHtml: { suffix: ".html" },
+            } as const;
+          TS
+        end
+
+        def navigation(table)
+          rows = live(table.rows)
+          [nav_const("NAV_DESKTOP", "The desktop navigation: a page with no group is its own entry; a group holds its pages.",
+                     desktop(rows)),
+           nav_const("NAV_MOBILE", "The mobile navigation, in its own order.", mobile(rows)),
+           nav_const("NAV_FOOTER", "The footer columns, left to right, each with its links.", footer(rows)),
+           nav_const("NAV_ADMIN", "The admin navigation: each admin page under its key.", admin(rows))].join("\n\n")
+        end
+
+        def nav_const(name, comment, entries)
+          body = entries.map { |entry| "  #{literal(entry)}," }
+          "// #{comment}\nexport const #{name} = #{body.empty? ? '[]' : "[\n#{body.join("\n")}\n]"} as const;"
+        end
+
+        def desktop(rows)
+          items = rows.reject { |row| row.nav_order.nil? }.sort_by { |row| [row.nav_order, row.path] }
+          entries = []
+          items.each do |row|
+            item = { path: row.path, label: row.label }
+            group = row.nav_group
+            slot = group && entries.find { |entry| entry[:group] == group }
+            slot ? slot[:items] << item : entries << { group: group, items: [item] }
+          end
+          entries
+        end
+
+        def mobile(rows)
+          rows.reject { |row| row.mobile_order.nil? }.sort_by { |row| [row.mobile_order, row.path] }
+              .map { |row| { path: row.path, label: row.label } }
+        end
+
+        def footer(rows)
+          columns = rows.select(&:footer_column).sort_by { |row| [row.footer_order, row.path] }.group_by(&:footer_column)
+          columns.sort_by { |name, group| [group.first.footer_order, name] }
+                 .map { |name, group| { column: name, items: group.map { |row| { path: row.path, label: row.label } } } }
+        end
+
+        def admin(rows)
+          rows.select(&:admin_key).sort_by { |row| [row.admin_order, row.admin_key] }
+              .map { |row| { key: row.admin_key, path: row.path, label: row.label } }
+        end
+
+        def search(rows)
+          sitemap = live(rows).select { |row| row.indexable && !row.path.match?(/[:*]/) }.map(&:path).sort
+          hidden = rows.reject { |row| row.indexable || row.path == CATCH_ALL }.flat_map { |row| [row.path, *row.aliases] }.sort
+          <<~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 = #{literal(sitemap)} as const;
+
+            // The routes a search engine is kept away from: every route that is not indexable.
+            export const NOT_FOR_SEARCH = #{literal(hidden)} as const;
+
+            // robots.txt `Disallow` prefixes: each non-public route up to its first parameter.
+            export const ROBOTS_DISALLOW = #{literal(robots(live(rows)))} as const;
+          TS
+        end
+
+        def robots(rows)
+          prefixes = rows.reject { |row| row.auth == "public" }.map { |row| robots_prefix(row.path) }
+          prefixes = (prefixes + ["#{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)
+          globals = sourced(rows, "global:", &:path)
+          collections = sourced(rows, "collection:") { |row| { path: row.path, indexable: row.indexable } }
+          previews = rows.select { |row| row.source.match?(/\A(global|collection):/) }
+                         .to_h { |row| [row.source, { path: row.path, draft: row.preview == "draft" }] }.sort.to_h
+          <<~TS.chomp
+            // A CMS global's slug to the page that shows it.
+            export const globalPages = #{literal(globals)} 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 = #{literal(collections)} as const;
+
+            const PREVIEWS: Readonly<Record<string, { readonly path: string; readonly draft: boolean }>> = #{literal(previews)};
+          TS
+        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
+
+        def helpers = [path_helpers, page_helpers].join("\n\n")
+
+        def path_helpers
+          <<~'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 === "*" ? ".*" : part.startsWith(":") ? "[^/]+" : part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"),
+                )
+                .join("/");
+              return new RegExp("^" + source + "$");
+            }
+
+            /** Whether a pathname is one a route pattern (`/blog/:slug.html`, `/pay/*`) describes, with or without `.html`. */
+            export function matchesPath(pattern: string, pathname: string): boolean {
+              return toRegExp(pattern).test(stripHtml(pathname));
+            }
+          TS
+        end
+
+        def page_helpers
+          <<~'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
+        end
+
+        def blank_to_nil(text) = text.nil? || text.empty? ? nil : text
+
+        # @param value [Object] a string, number, boolean, nil, array or hash
+        # @return [String] the TypeScript literal for it: objects with bare keys, on one line
+        def literal(value)
+          case value
+          when nil then "null"
+          when true, false, Integer then value.to_s
+          when String then JSON.generate(value)
+          when Array then "[#{value.map { |item| literal(item) }.join(', ')}]"
+          when Hash then "{ #{value.map { |key, item| "#{key_literal(key)}: #{literal(item)}" }.join(', ')} }".sub("{  }", "{}")
+          else raise ArgumentError, "no TypeScript literal for #{value.inspect}"
+          end
+        end
+
+        def key_literal(key)
+          key.to_s.match?(/\A[A-Za-z_$][\w$]*\z/) ? key.to_s : JSON.generate(key.to_s)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require_relative "../../projector"
+require_relative "../deploy/fargate/yaml"
+require_relative "edge"
+
+module Hecks
+  module Projections
+    module Site
+      # The edge of a site's route table as the two blocks of a CloudFormation template that depend
+      # on it: the distribution's cache behaviours and the load balancer's listener rules.
+      #
+      # The blocks are returned by name, `"behaviors"` and `"listener_rules"`, as text from the
+      # left margin. `Regions` puts each between the markers of the same name in the project's
+      # template, at the markers' indentation. The text is a pure function of the table and the
+      # edge rows.
+      module SiteCdn
+        extend Projector::Target
+
+        projects_as :site_cdn, emits: :files
+
+        module_function
+
+        # @param bluebook [Bluebook::Chapter] the chapter that declares the route table and the edge
+        # @param options [Hash{Symbol => Object}] `:registry` (Runtime::Registry) the project booted
+        #   into; or `:table` (Table) and `:edge` (Edge), already read
+        # @return [Hash{String => String}] each region's name to its text; empty when the chapter
+        #   declares no edge
+        # @raise [Table::Invalid] when the table or the edge is refused
+        def call(bluebook:, options: {})
+          registry = options[:registry]
+          table = options[:table] || Table.read(bluebook, registry: registry)
+          edge = options[:edge] || Edge.read(bluebook, table: table, vocabulary: Table.vocabulary(registry))
+          return {} unless edge
+
+          { "behaviors" => behaviors(edge), "listener_rules" => listener_rules(edge) }
+        end
+
+        # @param edge [Edge] a checked edge
+        # @return [String] the default behaviour and the ordered list, ending in a newline
+        def behaviors(edge)
+          fargate = Deploy::Fargate::Cdn
+          lines = fargate.behavior_lines("DefaultCacheBehavior", edge.default_behaviour, "")
+          unless edge.behaviours.empty?
+            lines << "CacheBehaviors:"
+            edge.behaviours.each { |entry| lines.concat(fargate.behavior_lines(nil, entry, "  ")) }
+          end
+          "#{lines.join("\n")}\n"
+        end
+
+        # @param edge [Edge] a checked edge
+        # @return [String] one listener rule resource per rule, by priority, ending in a newline
+        def listener_rules(edge)
+          edge.listener_rules.map { |rule| listener_rule(edge.setting, rule) }.join("\n")
+        end
+
+        def listener_rule(setting, rule)
+          paths = rule.fetch(:paths)
+          conditions = []
+          unless paths == ["/*"]
+            conditions.push("      - Field: path-pattern", "        Values: #{Deploy::Fargate::Yaml.flow_list(paths)}")
+          end
+          if setting.secret_header
+            conditions.push("      - Field: http-header", "        HttpHeaderConfig:",
+                            "          HttpHeaderName: #{setting.secret_header}",
+                            "          Values: #{Deploy::Fargate::Yaml.flow_list([setting.secret_value])}")
+          end
+          [
+            "#{rule.fetch(:rule)}:", "  Type: AWS::ElasticLoadBalancingV2::ListenerRule", "  Properties:",
+            "    ListenerArn: #{setting.listener}", "    Priority: #{rule.fetch(:priority)}",
+            *("    Conditions:" unless conditions.empty?), *conditions,
+            "    Actions:", "      - Type: forward", "        TargetGroupArn: #{rule.fetch(:target_group)}"
+          ].join("\n") << "\n"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Projections
+    module Site
+      class Table
+        # What no single row can show, and what a row contradicts in itself once its defaults are
+        # filled: a path declared twice, a switch the rows disagree on, an off route that sits in a
+        # navigation, an indexable route that is not public.
+        class Checks
+          SWITCH_ID = /\A[a-z][a-z0-9_]*\z/
+          PUBLIC_MENUS = %w[desktop mobile footer].freeze
+
+          # The navigation slots a row sits in.
+          #
+          # @param row [Row] a row
+          # @return [Array<String>] some of `desktop`, `mobile`, `footer`, `admin`
+          def self.navigation(row)
+            { "desktop" => row.nav_order, "mobile" => row.mobile_order, "footer" => row.footer_column,
+              "admin" => row.admin_key }.compact.keys
+          end
+
+          # @param rows [Array<Row>] the table's rows, defaults filled in
+          # @param problems [Array<String>] collects each problem found, one line each
+          def initialize(rows, problems)
+            @rows = rows
+            @problems = problems
+          end
+
+          # @return [void]
+          def call
+            check_duplicate_paths
+            check_switches
+            @rows.each { |row| check_row(row) }
+            check_unique(@rows.filter_map(&:admin_key), "admin key")
+            check_unique(@rows.map(&:source).grep(/\Aglobal:/), "source")
+          end
+
+          private
+
+          def check_duplicate_paths
+            seen = Hash.new { |hash, path| hash[path] = [] }
+            @rows.each do |row|
+              [row.path, *row.aliases].compact.each do |path|
+                problem(path, "is declared twice") if seen[path].any? { |other| other.verbs.intersect?(row.verbs) }
+                seen[path] << row
+              end
+            end
+          end
+
+          def check_switches
+            @rows.reject { |row| row.switch.empty? }.group_by(&:switch).each do |id, rows|
+              next if rows.map(&:off).uniq.size == 1
+
+              problem("switch #{id}", "is on for #{rows.reject(&:off).map(&:path).join(', ')} and off for the rest")
+            end
+          end
+
+          def check_row(row)
+            path = row.path.to_s
+            problem(path, "must start with /") unless path.start_with?("/")
+            check_switch(row, path)
+            check_redirect(row, path)
+            check_navigation(row, path)
+            check_indexing(row, path)
+            return unless row.preview == "draft" && row.source == "none"
+
+            problem(path, "previews as a draft but has source none; a draft preview needs a global: or collection: source")
+          end
+
+          def check_switch(row, path)
+            problem(path, "is off but names no switch (add switch: \"<id>\")") if row.off && row.switch.empty?
+            return if row.switch.empty? || row.switch.match?(SWITCH_ID)
+
+            problem(path, "has switch #{row.switch.inspect}; a switch is a lowercase id")
+          end
+
+          def check_redirect(row, path)
+            targeted = %w[redirect rewrite].include?(row.kind)
+            problem(path, "is a #{row.kind} and needs redirect_to") if targeted && row.redirect_to.to_s.empty?
+            if !targeted && row.redirect_to
+              problem(path, "has redirect_to but is a #{row.kind}; only a redirect or rewrite has a target")
+            end
+            return if row.aliases.empty? || row.kind == "page"
+
+            problem(path, "has aliases but is a #{row.kind}; aliases redirect to a page")
+          end
+
+          def check_navigation(row, path)
+            slots = self.class.navigation(row)
+            return if slots.empty?
+
+            problem(path, "is off and sits in the #{slots.join(' and ')} navigation") if row.off
+            problem(path, "sits in the navigation but is a #{row.kind}; only a page does") unless row.kind == "page"
+            problem(path, "sits in the navigation and has a parameter") if path.match?(/[:*]/)
+            problem(path, "sits in the navigation and has no label") if row.label.to_s.empty?
+            check_menu_audience(row, path, slots)
+          end
+
+          def check_menu_audience(row, path, slots)
+            public_slots = slots & PUBLIC_MENUS
+            if row.auth != "public" && public_slots.any?
+              problem(path, "is an admin page in the #{public_slots.join(' and ')} navigation")
+            end
+            problem(path, "is public and sits in the admin navigation") if row.auth == "public" && slots.include?("admin")
+          end
+
+          def check_indexing(row, path)
+            return unless row.indexable
+
+            problem(path, "is indexable but is #{row.auth}") unless row.auth == "public"
+            problem(path, "is indexable but is off") if row.off
+          end
+
+          def check_unique(values, name)
+            values.tally.each { |value, count| problem("#{name} #{value}", "is used by #{count} routes") if count > 1 }
+          end
+
+          def problem(label, text) = @problems << "#{label} #{text}"
+        end
+      end
+    end
+  end
+end