hecks 3.5.0 → 3.7.0

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

@@ -1,19 +1,23 @@
 # frozen_string_literal: true
 
 require "json"
+require_relative "lifecycle/text"
+require_relative "lifecycle/text_tail"
 
 module Hecks
   module Projections
     module Site
       module Payload
         # The module that turns a spec and a saved document into the commands between the host's
-        # state and
-        # the wanted one. It is the same for every project but for the role its commands declare
-        # and the
-        # path of the module that talks to the host.
+        # state and the wanted one. It is the same for every project but for the role its commands
+        # declare and the path of the module that talks to the host.
         module Lifecycle
           BANNER = "// Generated by hecks site site_projection.project_site. Do not edit."
 
+          # The whole module, with `__ROLE__` and `__HECKS__` standing for the role and the path of
+          # the module that talks to the host.
+          TEXT = (HEAD + TAIL).freeze
+
           module_function
 
           # @param role [String, nil] the role every driven command declares
@@ -22,168 +26,6 @@ module Hecks
           def render(role:, hecks:)
             [BANNER, TEXT.sub("__ROLE__", role.to_json).sub("__HECKS__", hecks.to_json)].join("\n\n")
           end
-
-          TEXT = <<~TS
-            // Driving one aggregate from a save: what every driven collection shares.
-            //
-            // An editor's save says what the document should look like and where it should
-            // be (live, withdrawn, cancelled). The domain answers with where the aggregate
-            // is now. This works out the commands between the two: create it if the domain
-            // has never seen it, Revise when its facts differ, then walk its lifecycle to
-            // the wanted status along the shortest path the bluebook allows.
-            //
-            // The pure parts (the plan) are separate from `drive`, the one function that
-            // talks to the domain, so the decisions test without a network.
-            import { domain, instancesOf, refusalOf, type Answer } from __HECKS__;
-
-            /** The role every driven command declares; the host compares the role as a plain string. */
-            const ROLE = __ROLE__;
-
-            export type Wire = Record<string, unknown>;
-
-            export interface Command<S> {
-              verb: string;
-              to?: string;
-              with: Wire;
-              /** True when the instances that came back show the command took effect. */
-              confirm: (after: S[]) => boolean;
-            }
-
-            export interface Instance {
-              slug: string;
-              status: string;
-            }
-
-            export interface Spec<S extends Instance, I extends { slug: string }> {
-              /** The aggregate as the host names it, chapter first: "Club::Event". */
-              aggregate: string;
-              /** Its instances in an answer, keyed by slug. */
-              read: (answer: Answer) => S[];
-              /** What the host holds, in the shape a save produces, so the two compare. */
-              toInput: (state: S) => Omit<I, "status">;
-              /** Every attribute but the slug, as `Revise` takes it. */
-              fields: (input: Omit<I, "status">) => Wire;
-              /** The command that creates one (it takes the slug and the fields) and the status it leaves it in. */
-              create: { verb: string; status: string };
-              /** The lifecycle: from a status, the commands that leave it and where they lead. */
-              edges: Record<string, Record<string, string>>;
-            }
-
-            /** A refusal-free plan: nothing is sent for a status the domain cannot reach from where it is. */
-            export class UnreachableStatus extends Error {}
-
-            export const wrapped = (value: string) => ({ value });
-            export const optionalValue = (name: string, value: string | null | undefined) => (value ? { [name]: wrapped(value) } : {});
-
-            /** The text inside a one-attribute value object (`{value}`, `{url}`, `{address}`), or null. */
-            export function unwrap(value: unknown): string | null {
-              if (typeof value === "string") return value || null;
-              if (value && typeof value === "object") {
-                for (const key of ["value", "url", "address"]) {
-                  const inner = (value as Record<string, unknown>)[key];
-                  if (typeof inner === "string" && inner) return inner;
-                }
-              }
-              return null;
-            }
-
-            export const unwrapList = (value: unknown): string[] =>
-              Array.isArray(value) ? value.map(unwrap).filter((item): item is string => !!item) : [];
-
-            export const statusOf = (state: Record<string, unknown>): string => (typeof state.status === "string" ? state.status : "");
-
-            /** The verbs, in order, that take an aggregate from one status to another; null when none does. */
-            export function pathBetween(edges: Record<string, Record<string, string>>, from: string, to: string): string[] | null {
-              if (from === to) return [];
-              const seen = new Set([from]);
-              let frontier: { status: string; verbs: string[] }[] = [{ status: from, verbs: [] }];
-              while (frontier.length) {
-                const next: typeof frontier = [];
-                for (const { status, verbs } of frontier) {
-                  for (const [verb, target] of Object.entries(edges[status] ?? {})) {
-                    if (seen.has(target)) continue;
-                    if (target === to) return [...verbs, verb];
-                    seen.add(target);
-                    next.push({ status: target, verbs: [...verbs, verb] });
-                  }
-                }
-                frontier = next;
-              }
-              return null;
-            }
-
-            const stateOf = <S extends Instance>(after: S[], slug: string) => after.find((s) => s.slug === slug);
-
-            /**
-             * The commands that make the domain's aggregate match `input` and sit in
-             * `desired`. `desired` null means "not on the site": a document the domain has
-             * never seen sends nothing; one it holds is walked to `withdrawn`.
-             */
-            export function planCommands<S extends Instance, I extends { slug: string }>(
-              spec: Spec<S, I>,
-              current: S | undefined,
-              input: Omit<I, "status">,
-              desired: string,
-            ): Command<S>[] {
-              const slug = input.slug;
-              const fields = spec.fields(input);
-              const commands: Command<S>[] = [];
-              let status = current?.status;
-
-              if (!current) {
-                if (spec.create.status !== desired && !pathBetween(spec.edges, spec.create.status, desired)) {
-                  throw new UnreachableStatus(`${spec.aggregate} cannot reach "${desired}" from "${spec.create.status}".`);
-                }
-                commands.push({
-                  verb: spec.create.verb,
-                  with: { slug: wrapped(slug), ...fields },
-                  confirm: (after) => stateOf(after, slug)?.status === spec.create.status,
-                });
-                status = spec.create.status;
-              } else if (JSON.stringify(spec.fields(spec.toInput(current))) !== JSON.stringify(fields)) {
-                commands.push({
-                  verb: "Revise",
-                  to: slug,
-                  with: fields,
-                  confirm: (after) => {
-                    const now = stateOf(after, slug);
-                    return !!now && JSON.stringify(spec.fields(spec.toInput(now))) === JSON.stringify(fields);
-                  },
-                });
-              }
-
-              const path = pathBetween(spec.edges, status ?? "", desired);
-              if (path === null) throw new UnreachableStatus(`${spec.aggregate} "${slug}" cannot go from "${status}" to "${desired}".`);
-              let at = status ?? "";
-              for (const verb of path) {
-                const to = spec.edges[at][verb];
-                commands.push({ verb, to: slug, with: {}, confirm: (after) => stateOf(after, slug)?.status === to });
-                at = to;
-              }
-              return commands;
-            }
-
-            /** Runs the plan against the domain; a command whose result does not show it took effect throws the domain's own words. */
-            export async function drive<S extends Instance, I extends { slug: string }>(
-              spec: Spec<S, I>,
-              input: Omit<I, "status">,
-              desired: string | null,
-              /** The status that means "off the site", used when `desired` is null and the domain holds the aggregate. */
-              offSite: string,
-            ): Promise<void> {
-              const current = spec.read(await domain().read()).find((s) => s.slug === input.slug);
-              // Not on the site and never was (a draft): the domain hears nothing about it.
-              if (desired === null && !current) return;
-              for (const command of planCommands(spec, current, input, desired ?? offSite)) {
-                const verb = `${spec.aggregate.split("::")[1]}.${command.verb}`;
-                const answer = await domain().dispatch(verb, command.with, command.to, ROLE);
-                if (!command.confirm(spec.read(answer))) throw refusalOf(answer, verb);
-              }
-            }
-
-            /** Reads an aggregate's instances, slug first, from an answer. */
-            export const instancesBySlug = (answer: Answer, aggregate: string) => instancesOf(answer, aggregate);
-          TS
         end
       end
     end

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

@@ -5,25 +5,23 @@ module Hecks
     module Site
       module Payload
         # What the generators read from a domain chapter about one aggregate the content system
-        # drives:
-        # its attributes with the shape each takes over the wire, the command that creates it, the
-        # lifecycle edges, and the role its commands declare.
+        # drives: its attributes with the shape each takes over the wire, the command that creates
+        # it, the lifecycle edges, and the role its commands declare.
         #
         # The model is pure data. It refuses an aggregate it cannot drive, naming why, so a project
         # learns at generation time rather than from a runtime refusal.
         class Model
           # One attribute: `name` is the domain's (snake case), `ts` the camel case the content
-          # system
-          # uses, `shape` one of :value, :url, :address, :integer or :composite, and `parts` the
-          # attributes of a composite value object.
+          # system uses, `shape` one of :value, :url, :address, :integer or :composite, and `parts`
+          # the attributes of a composite value object.
           Attr = Struct.new(:name, :ts, :shape, :wire_key, :optional, :list, :type, :parts, keyword_init: true)
 
           # One aggregate: `noun` ("Event"), `fqn` ("Club::Event"), `create` ({verb:, status:}),
           # `edges` (status => { verb => status }) and `attrs` (the identity first).
           Aggregate = Struct.new(:noun, :fqn, :create, :edges, :attrs, :identity, :role, keyword_init: true)
 
-          # The single attribute names a one-attribute value object may carry, with the shape each
-          # is.
+          # The single attribute names a one-attribute value object may carry, with the shape
+          # each is.
           SINGLE = { "value" => :value, "url" => :url, "address" => :address }.freeze
 
           # @param chapter [Bluebook::Chapter] the domain chapter
@@ -58,15 +56,16 @@ module Hecks
           def edges
             creating = @agg.commands.select(&:creates?).map(&:hecks_name)
             map = Hash.new { |hash, key| hash[key] = {} }
-            @agg.lifecycle.transitions.each do |verb, move|
-              next if creating.include?(verb)
-
-              Array(move.from).each { |from| map[from][verb] = move.target }
-              map[move.target]
-            end
+            @agg.lifecycle.transitions.each { |verb, move| add_edges(map, verb, move) unless creating.include?(verb) }
             map.transform_values(&:dup)
           end
 
+          # Records the edge from each of the move's states, and makes sure its target has a key.
+          def add_edges(map, verb, move)
+            Array(move.from).each { |from| map[from][verb] = move.target }
+            map[move.target]
+          end
+
           def role
             roles = @agg.commands.filter_map { |command| command.role if command.respond_to?(:role) }.uniq
             if roles.size > 1
@@ -95,14 +94,15 @@ module Hecks
           end
 
           def shape_of(attribute, members)
-            if members.size == 1 && SINGLE.key?(members.first.name.to_s)
-              key = members.first.name.to_s
-              [members.first.type.to_s == "Integer" ? :integer : SINGLE.fetch(key), key, nil]
-            elsif attribute.list? && members.size > 1
-              [:composite, nil, members.map { |member| part(member) }]
-            else
-              raise ArgumentError, "#{@agg.hecks_name}.#{attribute.name} is #{attribute.type}, which the driver cannot carry"
-            end
+            return single_shape(members.first) if members.size == 1 && SINGLE.key?(members.first.name.to_s)
+            return [:composite, nil, members.map { |member| part(member) }] if attribute.list? && members.size > 1
+
+            raise ArgumentError, "#{@agg.hecks_name}.#{attribute.name} is #{attribute.type}, which the driver cannot carry"
+          end
+
+          def single_shape(member)
+            key = member.name.to_s
+            [member.type.to_s == "Integer" ? :integer : SINGLE.fetch(key), key, nil]
           end
 
           def part(member)

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