hecks 3.9.1 → 3.11.0

data/lib/hecks/projections/site/cms_editor/media.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Projections
+    module Site
+      module CmsEditor
+        # The aggregate that registers pictures, found by shape in the schema the editor reads.
+        #
+        # It is an aggregate with a creating command whose attributes are the aggregate's identity
+        # (the key), an alt text and a mime type, and optionally a width and a height; every other
+        # attribute of that command must be optional, because an upload cannot fill it. Neither the
+        # aggregate's name nor the command's decides it; the attribute names are the vocabulary, the
+        # way `blocks`, `kind` and `spans` are for a document body. An attribute is a plain value or
+        # a value object whose first part is a plain value; the editor sends a value the same way.
+        #
+        # The domain keeps the picture's record, never its bytes.
+        module Media
+          # The attribute names that carry each part of a picture's record besides its key.
+          ROLES = { "alt" => %w[alt alt_text], "mime" => %w[mime_type mime content_type],
+                    "width" => %w[width], "height" => %w[height] }.freeze
+
+          # The parts every picture's registration must take.
+          REQUIRED = %w[key alt mime].freeze
+
+          module_function
+
+          # @param aggregates [Array<Hash{String => Object}>] the aggregates, as `Schema` reads them
+          # @return [Hash{String => Object}, nil] the aggregate and command that register a
+          #   picture, each part's attribute and the query that lists the pictures; nil when no
+          #   aggregate has the shape
+          def read(aggregates)
+            aggregates.each do |agg|
+              agg["commands"].select { |command| command["creates"] }.each do |command|
+                found = fields(agg, command)
+                return describe(agg, command, found) if found
+              end
+            end
+            nil
+          end
+
+          # @return [Hash{String => Hash}, nil] each part's attribute and how its value is sent, or
+          #   nil when the command is not a picture's registration
+          def fields(agg, command)
+            chosen = parts(agg, command["attributes"])
+            return nil unless REQUIRED.all? { |role| chosen.key?(role) } && others_optional?(command, chosen)
+
+            wrapped = chosen.transform_values { |attr| wrap(agg, attr) }
+            return nil if wrapped.value?(false)
+
+            chosen.to_h { |role, attr| [role, { "name" => attr["name"], "wrap" => wrapped.fetch(role) }] }
+          end
+
+          # @return [Boolean] whether every attribute that is not a part of the record is optional
+          def others_optional?(command, chosen)
+            (command["attributes"] - chosen.values).all? { |attr| attr["optional"] }
+          end
+
+          # @return [Hash{String => Hash}] each part of the record to the attribute that carries it
+          def parts(agg, attrs)
+            found = { "key" => attrs.find { |attr| attr["name"] == agg["identity"] } }
+            ROLES.each { |role, names| found[role] = attrs.find { |attr| names.include?(attr["name"]) } }
+            found.compact
+          end
+
+          # @return [String, nil, false] the part a value object's value is sent in, nil for a
+          #   plain value, false for an attribute an upload cannot fill
+          def wrap(agg, attr)
+            return false if attr["list"] || attr["kind"] == "reference"
+            return nil unless attr["kind"] == "object"
+
+            first = agg["valueObjects"].fetch(attr["type"], []).first
+            first && first["kind"] != "object" && !first["list"] ? first["name"] : false
+          end
+
+          # @return [Hash{String => Object}] the picture aggregate as the editor's schema names it
+          def describe(agg, command, found)
+            listing = agg["queries"].find { |query| query["attributes"].empty? }
+            { "aggregate" => agg["name"], **agg.slice("chapter"), "command" => command["name"], "fields" => found,
+              "listing" => listing && listing["name"] }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projections/site/cms_editor/moment.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Projections
+    module Site
+      module CmsEditor
+        # Which integer attributes are moments in time, read from the names the bluebook gave them.
+        #
+        # An integer is a moment when one of the names it goes by (the attribute's, its value
+        # object's, the value object's part's) ends in `_at` or `At` (a date and a time), ends in
+        # `_on` or `On` (a date), or has `epoch` in it (seconds since 1970, so a date and a time).
+        # The value is always whole seconds since 1970 UTC; the editor shows it in the viewer's own
+        # time zone. A name is the only evidence the bluebook gives, so the rule is this narrow:
+        # an integer named `duration` or `Season` is never a date.
+        module Moment
+          # Names that end in `at` or `on` as a word, so `created_at` and `CreatedAt` match and
+          # `format`, `Season` and `Combat` do not.
+          AT = /(?:_at|[a-z0-9]At)\z/
+          ON = /(?:_on|[a-z0-9]On)\z/
+
+          module_function
+
+          # @param names [Array<String>] the names the integer goes by
+          # @return [String, nil] `"datetime"`, `"date"`, or nil when the integer is not a moment
+          def widget(names)
+            return "datetime" if names.any? { |name| AT.match?(name) || name.match?(/epoch/i) }
+
+            "date" if names.any? { |name| ON.match?(name) }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projections/site/cms_editor/palette.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require_relative "color"
+
+module Hecks
+  module Projections
+    module Site
+      module CmsEditor
+        # The editor's colours, light and dark, derived from one accent colour, as the custom
+        # properties of a daisyUI theme (`--color-base-100`, `--color-primary`, ...) and the few
+        # extras the pages use (`--ed-muted`, `--ed-edge`). Every text and fill pair is moved
+        # until it reaches the accessibility standard's level for it (4.5:1 for text, 3:1 for the
+        # edge of a control), so a brand colour that would fail cannot make the editor unreadable.
+        #
+        # The neutrals (ground, page, ink, muted ink, rule) are fixed when the row names no
+        # accent, and take the accent's hue at low saturation when it does, so an accent retints
+        # the whole theme. Primary buttons are filled with ink (daisyUI's `neutral`); the accent
+        # (`primary`) marks selection, focus, links, the active navigation item and the saved or
+        # published state.
+        class Palette
+          # The accent a row that names none gets: a deep verdigris.
+          DEFAULT_ACCENT = "#1f7a6d"
+
+          # The neutrals a row that names no accent gets, per theme.
+          FIXED = {
+            light: { ground: "#f4f6f8", surface: "#ffffff", ink: "#1a222c", muted: "#5a6675", rule: "#dce1e7" },
+            dark:  { ground: "#11161b", surface: "#181f26", ink: "#e7ebef", muted: "#9aa6b3", rule: "#28313b" }
+          }.freeze
+
+          # Hues of the status colours, in degrees.
+          TONES = { ok: 150.0, warn: 38.0, danger: 4.0 }.freeze
+
+          # The daisyUI variable each status tone fills.
+          STATUS = { ok: "success", warn: "warning", danger: "error" }.freeze
+
+          # @param accent [String, nil] a six-digit hex colour, or nil for the default
+          def initialize(accent = nil)
+            @custom = !accent.to_s.empty?
+            @accent = (accent.to_s.empty? ? DEFAULT_ACCENT : accent).downcase
+          end
+
+          # @return [Hash{Symbol => Hash{String => String}}] each theme's properties, name to value
+          def themes = { light: properties(:light), dark: properties(:dark) }
+
+          private
+
+          def properties(theme)
+            base = neutrals(theme)
+            found = base.merge(accents(theme, base)).merge(tones(theme, base))
+            { **daisy(found), **extras(found) }
+          end
+
+          def lighter(theme) = theme == :light ? :darker : :lighter
+
+          def neutrals(theme)
+            fixed = @custom ? tinted(FIXED.fetch(theme)) : FIXED.fetch(theme)
+            backs = [fixed[:surface], fixed[:ground]]
+            edge = Color.reach(Color.mix(fixed[:rule], fixed[:muted], 0.5), backs, 3.0, lighter(theme))
+            { **fixed, muted: Color.reach(fixed[:muted], backs, 4.5, lighter(theme)), edge: edge }
+          end
+
+          # The fixed neutrals with the accent's hue at the saturation each already has.
+          def tinted(fixed)
+            hue = Color.hsl(@accent).first
+            fixed.transform_values do |hex|
+              _, sat, light = Color.hsl(hex)
+              hex == "#ffffff" ? hex : Color.from_hsl(hue, sat, light)
+            end
+          end
+
+          def accents(theme, base)
+            backs = [base[:surface], base[:ground]]
+            fill = theme == :light ? @accent : Color.reach(@accent, backs, 4.5, :lighter)
+            soft = Color.mix(base[:surface], fill, theme == :light ? 0.1 : 0.18)
+            { primary: Color.reach(fill, [*backs, soft], 4.5, lighter(theme)), accent_soft: soft }
+          end
+
+          def tones(theme, base)
+            TONES.each_with_object({}) do |(name, hue), found|
+              back = theme == :light ? Color.from_hsl(hue, 0.5, 0.94) : Color.from_hsl(hue, 0.28, 0.18)
+              start = Color.from_hsl(hue, 0.55, theme == :light ? 0.3 : 0.72)
+              found[:"#{name}_bg"] = back
+              found[:"#{name}_fg"] = Color.reach(start, [back, base[:surface]], 4.5, lighter(theme))
+            end
+          end
+
+          # The first of white, a near-black and black that reads on `fill`.
+          def on(fill) = ["#ffffff", "#0f151a", "#000000"].find { |hex| Color.contrast(hex, fill) >= 4.5 }
+
+          def daisy(found)
+            colours = surfaces(found).merge(fills(found))
+            named = colours.slice("primary", "secondary", "accent", "info", *STATUS.values)
+            contents = named.to_h { |name, value| ["#{name}-content", on(value)] }
+            colours.merge(contents).transform_keys { |name| "--color-#{name}" }
+          end
+
+          def surfaces(found)
+            { "base-100" => found[:surface], "base-200" => found[:ground], "base-300" => found[:rule],
+              "base-content" => found[:ink], "neutral" => found[:ink], "neutral-content" => found[:surface] }
+          end
+
+          def fills(found)
+            { "primary" => found[:primary], "secondary" => found[:muted], "accent" => found[:primary], "info" => found[:primary],
+              **STATUS.to_h { |tone, name| [name, found[:"#{tone}_fg"]] } }
+          end
+
+          def extras(found)
+            { "--ed-muted" => found[:muted], "--ed-edge" => found[:edge], "--ed-soft" => found[:accent_soft],
+              "--ed-ok-bg" => found[:ok_bg], "--ed-warn-bg" => found[:warn_bg], "--ed-danger-bg" => found[:danger_bg] }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projections/site/cms_editor/pickers.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require_relative "targets"
+
+module Hecks
+  module Projections
+    module Site
+      module CmsEditor
+        # Which attributes name another aggregate's instance, found by the bluebook's own
+        # declarations, so the editor offers the instances in place of a text box. In this order:
+        # a `<kind>:<slug>` key by its pattern (see `KeyKinds`), each kind that is an aggregate's
+        # snake-case name offering that aggregate; a `reference_to` attribute whose target is an
+        # editor aggregate; a value object of one text part named `<Stem>Ref`, where `<Stem>` is
+        # the type of an editor aggregate's identity or its name; and `<Image|Picture|Photo|Media>
+        # Ref` with a picture aggregate, which suggests pictures and accepts any other text. A
+        # target is found once: the same chapter's, else the only one of its name; else none.
+        module Pickers
+          # The stems that name a picture, for the editor's picture aggregate.
+          PICTURE_STEMS = %w[Image Picture Photo Media].freeze
+
+          module_function
+
+          # @param aggregates [Array<Hash{String => Object}>] the aggregates as `Schema` shapes them
+          # @param media [Hash{String => Object}, nil] the picture aggregate, as `Media` says
+          # @return [Array<Hash{String => Object}>] the aggregates, each attribute that names an
+          #   instance carrying its `picker`
+          def apply(aggregates, media = nil)
+            targets = Targets.new(aggregates, media)
+            aggregates.map { |agg| annotate(agg, targets) }
+          end
+
+          # @return [Hash{String => Object}] `agg` with a picker on each attribute that has one
+          def annotate(agg, targets)
+            mark = ->(list) { list.map { |attr| with_picker(attr, agg, targets) } }
+            agg.merge("attributes" => mark.call(agg["attributes"]), "valueObjects" => objects(agg, mark),
+                      "commands" => marked(agg["commands"], mark), "queries" => marked(agg["queries"], mark))
+          end
+
+          # @return [Array<Hash>] the commands or queries, the attributes of each marked
+          def marked(items, mark) = items.map { |item| item.merge("attributes" => mark.call(item["attributes"])) }
+
+          # @return [Hash{String => Array}] the value objects, the parts of one of several parts
+          #   marked; a value object of one part is entered as the attribute that names it
+          def objects(agg, mark)
+            agg["valueObjects"].transform_values do |parts|
+              parts.size == 1 ? parts.map { |part| part.except("keys") } : mark.call(parts)
+            end
+          end
+
+          # @return [Hash{String => Object}] `attr` with its `picker`, or as it was
+          def with_picker(attr, agg, targets)
+            picker = picker_for(attr, agg, targets)
+            picker ? attr.except("keys").merge("picker" => picker) : attr
+          end
+
+          def picker_for(attr, agg, targets)
+            return kinds(attr["keys"], agg, targets) if attr["keys"]
+            return targets.named(attr["target"], agg) if attr["kind"] == "reference"
+
+            stem = reference_stem(attr, agg)
+            stem && (targets.keyed_by(stem, agg) || (targets.pictures if PICTURE_STEMS.include?(stem)))
+          end
+
+          # @return [Hash{String => Array}] one entry per kind, with the aggregate it names if any
+          def kinds(words, agg, targets)
+            { "kinds" => words.map { |word| { "kind" => word, **(targets.kind(word, agg) || {}) } } }
+          end
+
+          # @return [String, nil] `Stem` of a `StemRef` value object that has one plain text part
+          def reference_stem(attr, agg)
+            return nil unless plain_text_object?(attr, agg["valueObjects"][attr["type"]])
+
+            stem = attr["type"].delete_suffix("Ref")
+            stem unless stem.empty? || stem == attr["type"]
+          end
+
+          # @return [Boolean] whether `attr` is a value object whose one part is a single text
+          def plain_text_object?(attr, parts)
+            attr["kind"] == "object" && parts&.size == 1 && parts.first["kind"] == "text" && !parts.first["list"]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projections/site/cms_editor/pretty.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Hecks
+  module Projections
+    module Site
+      module CmsEditor
+        # JSON indented two spaces, with an empty list or object as `[]` or `{}`. It does not use
+        # `JSON.pretty_generate`, whose spelling of an empty list depends on which JSON extensions
+        # are loaded, so the projection's text is the same wherever it runs.
+        module Pretty
+          module_function
+
+          # @param value [Object] a hash, array, string, number, boolean or nil
+          # @param depth [Integer] the indentation level of the line the value starts on
+          # @return [String] the value as indented JSON
+          def generate(value, depth = 0)
+            case value
+            when Hash then block("{", "}", value.map { |key, item| member(key, item, depth) }, depth)
+            when Array then block("[", "]", value.map { |item| generate(item, depth + 1) }, depth)
+            else JSON.generate(value)
+            end
+          end
+
+          # @return [String] one `"key": value` line of an object
+          def member(key, item, depth) = "#{JSON.generate(key.to_s)}: #{generate(item, depth + 1)}"
+
+          # @return [String] the lines between `open` and `close`, each indented under `depth`
+          def block(open, close, lines, depth)
+            return "#{open}#{close}" if lines.empty?
+
+            pad = "  " * (depth + 1)
+            "#{open}\n#{lines.map { |line| "#{pad}#{line}" }.join(",\n")}\n#{"  " * depth}#{close}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projections/site/cms_editor/preview.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Hecks
+  module Projections
+    module Site
+      module CmsEditor
+        # The `Editor` row's `preview`: where a record is shown on the site, as a URL template the
+        # editor frames in a side drawer.
+        #
+        # A template is an `http://` or `https://` address, or a path that starts with one slash,
+        # with the placeholders `{key}`, `{kind}`, `{slug}` and `{id}` filled from a record's
+        # identity when the page is built. Anything else is refused, so a template cannot name a
+        # scheme that runs script (`javascript:`), a host written with credentials, or a
+        # placeholder the editor would leave unfilled. A placeholder may not stand in the origin
+        # (scheme, host and port), because the content security policy names that origin once, at
+        # build time, and allows no other frame.
+        module Preview
+          # The words a template may put in braces.
+          PLACEHOLDERS = %w[key kind slug id].freeze
+
+          # An absolute address: the origin, then whatever follows it.
+          ABSOLUTE = %r{\A(?<origin>https?://[^/?#\s]+)(?<rest>.*)\z}m
+
+          module_function
+
+          # @param template [String] the row's `preview`, which may be empty
+          # @return [Array<String>] every reason the template is refused; empty when it is usable
+          def problems(template)
+            return [] if template.empty?
+
+            found = []
+            found << "must not hold whitespace" if template.match?(/\s/)
+            found.concat(shape_problems(template))
+            found.concat(placeholder_problems(template))
+            found.map { |problem| "preview #{template.inspect} #{problem}" }
+          end
+
+          # @return [String, nil] what the content security policy's `frame-src` names for the
+          #   template: its origin, `'self'` for a path, or nil for no preview
+          def frame_source(template)
+            return nil if template.empty?
+
+            found = ABSOLUTE.match(template)
+            found ? found[:origin] : "'self'"
+          end
+
+          # @return [Array<String>] the problems with the scheme, the host and the path
+          def shape_problems(template)
+            found = ABSOLUTE.match(template)
+            return path_problems(template) unless found
+
+            origin_problems(found[:origin])
+          end
+
+          # @return [Array<String>] the problems with a path template
+          def path_problems(template)
+            return ["must be an http(s) address or a path that starts with one slash"] unless template.start_with?("/")
+            return ["must not start with two slashes, which names another host"] if template.start_with?("//")
+
+            []
+          end
+
+          # @return [Array<String>] the problems with the origin of an absolute template
+          def origin_problems(origin)
+            found = []
+            found << "must not name credentials in the address" if origin.include?("@")
+            found << "must not hold a placeholder in the scheme, host or port" if origin.include?("{")
+            found << "names no host" if !origin.include?("{") && URI.parse(origin).host.to_s.empty?
+            found
+          rescue URI::InvalidURIError
+            ["is not a valid address"]
+          end
+
+          # @return [Array<String>] a problem for each unknown placeholder and each stray brace
+          def placeholder_problems(template)
+            unknown = template.scan(/\{([^{}]*)\}/).flatten.uniq - PLACEHOLDERS
+            found = unknown.map do |name|
+              "names the placeholder {#{name}}; the placeholders are #{PLACEHOLDERS.map do |word|
+                "{#{word}}"
+              end.join(", ")}"
+            end
+            found << "has a brace that is not part of a placeholder" if template.gsub(/\{[^{}]*\}/, "").match?(/[{}]/)
+            found
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projections/site/cms_editor/relations.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Projections
+    module Site
+      module CmsEditor
+        # The records that belong to one record, found by the keys they carry. Aggregate `B` is
+        # related to `A` when `B`'s identity is a `<kind>:<slug>` key (see `KeyKinds`) whose
+        # kinds include `A`'s snake-case name, so `post:first-light` keys the `B` of the `Post`
+        # `first-light`.
+        #
+        # The rule reads the declared pattern and what the kind resolves to (see `Pickers`),
+        # never a name. A `B` is shown by its shape: a **document** (a rich-text body), a
+        # **gallery** (a list that names pictures) or **metadata** (anything else). Its creating
+        # command is the first that takes the identity; its editing command is the draft-saving
+        # command of a document that keeps drafts (see `Drafts`), else the first command on an
+        # existing record that is neither a lifecycle move nor destructive and takes the body or
+        # the pictures.
+        module Relations
+          module_function
+
+          # @param aggregates [Array<Hash{String => Object}>] the aggregates as `Pickers` leaves
+          #   them
+          # @param media [Hash{String => Object}, nil] the picture aggregate, as `Media` says
+          # @return [Array<Hash{String => Object}>] each aggregate, carrying `related` when other
+          #   aggregates are keyed by it
+          def apply(aggregates, media = nil)
+            aggregates.map do |agg|
+              found = aggregates.reject { |other| other.equal?(agg) }.filter_map { |other| relation(other, agg, media) }
+              found.empty? ? agg : agg.merge("related" => found)
+            end
+          end
+
+          # @return [Hash{String => Object}, nil] how `other` is related to `agg`, or nil when it
+          #   is not
+          def relation(other, agg, media)
+            key = other["attributes"].find { |attr| attr["name"] == other["identity"] }
+            return nil unless key && keyed_by?(key, agg)
+
+            shape, field = shape_of(other, media)
+            { "aggregate" => other["name"], "chapter" => other["chapter"], "field" => key["name"], "shape" => shape,
+              "create" => creating(other, key), "edit" => editing(other, field) }.compact
+          end
+
+          # @return [Boolean] whether `key` is declared a key of `<agg's snake name>:<slug>`
+          def keyed_by?(key, agg)
+            (key.dig("picker", "kinds") || []).any? { |kind| kind["target"] == agg["name"] && kind["chapter"] == agg["chapter"] }
+          end
+
+          # @return [Array(String, String)] the shape, and the attribute that gives it
+          def shape_of(other, media)
+            body = other["attributes"].find { |attr| attr["widget"] == "body" && !attr["list"] }
+            return ["document", body["name"]] if body
+
+            pictures = pictures_of(other, media)
+            pictures ? ["gallery", pictures["name"]] : ["metadata", nil]
+          end
+
+          # @return [Hash{String => Object}, nil] the list attribute that names pictures
+          def pictures_of(other, media)
+            return nil unless media
+
+            other["attributes"].find { |attr| attr["list"] && attr.dig("picker", "target") == media["aggregate"] }
+          end
+
+          # @return [String, nil] the first creating command that takes the identity
+          def creating(other, key)
+            other["commands"].find do |command|
+              command["creates"] && command["attributes"].any? do |attr|
+                attr["name"] == key["name"]
+              end
+            end&.fetch("name")
+          end
+
+          # @return [String, nil] the command that changes the record's body, pictures or fields
+          def editing(other, field)
+            return other.dig("drafts", "save") if other["drafts"] && field == other.dig("drafts", "live")
+
+            moves = (other.dig("lifecycle", "transitions") || []).map { |move| move["verb"] }
+            other["commands"].find { |command| edits?(command, field, moves) }&.fetch("name")
+          end
+
+          def edits?(command, field, moves)
+            names = command["attributes"].map { |attr| attr["name"] }
+            !command["creates"] && !command["destructive"] && !moves.include?(command["name"]) &&
+              !names.empty? && (field.nil? || names.include?(field))
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projections/site/cms_editor/scale_checks.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Projections
+    module Site
+      module CmsEditor
+        # What the `Editor` row's settings for many chapters and long lists must satisfy: chapters
+        # named once each, roles given for a chapter the editor edits, and a page size a list can
+        # hold. A chapter's name is part of an address, so it cannot be spelled as one of the
+        # editor's own paths.
+        module ScaleChecks
+          # The most instances a list may show to a page.
+          MAX_PAGE = 1000
+
+          # The first segments of the editor's own addresses, which no chapter may be named.
+          RESERVED = %w[assets media logout api scheduled].freeze
+
+          module_function
+
+          # @param row [Hash{Symbol => String}] the row, defaults filled
+          # @return [Array<String>] every problem with `chapter`, `chapter_roles` and `page_size`
+          def problems(row)
+            chapters = row[:chapter].split(",").map(&:strip)
+            [*chapter_problems(chapters), *role_problems(row[:chapter_roles], chapters), *page_size_problems(row[:page_size])]
+          end
+
+          # @return [Array<String>] the problems with an empty, repeated or reserved chapter name
+          def chapter_problems(chapters)
+            found = []
+            found << "chapter names no chapter" if chapters.reject(&:empty?).empty?
+            repeated = chapters.find { |name| chapters.count(name) > 1 }
+            found << "chapter names #{repeated.inspect} twice" if repeated
+            [*found, *reserved_problems(chapters)]
+          end
+
+          # @return [Array<String>] a problem for each chapter spelled as an address of the editor's
+          def reserved_problems(chapters)
+            return [] if chapters.size < 2
+
+            (chapters & RESERVED).map do |name|
+              "chapter #{name.inspect} is the first part of an address the editor serves; name it another way"
+            end
+          end
+
+          # @return [Array<String>] the problems with `Chapter=Role,Role;Chapter=Role` entries
+          def role_problems(text, chapters)
+            text.split(";").map(&:strip).reject(&:empty?).flat_map do |entry|
+              name, roles = entry.split("=", 2)
+              next ["chapter_roles #{entry.inspect} must read Chapter=Role,Role"] if roles.to_s.strip.empty?
+              next [] if chapters.include?(name.strip)
+
+              ["chapter_roles names #{name.strip.inspect}, which is not a chapter of this editor"]
+            end
+          end
+
+          # @return [Array<String>] the problem with a page size that is not a whole 1 to 1000
+          def page_size_problems(size)
+            return [] if size.match?(/\A[1-9]\d{0,3}\z/) && size.to_i <= MAX_PAGE
+
+            ["page_size #{size.inspect} must be a whole number from 1 to #{MAX_PAGE}"]
+          end
+        end
+      end
+    end
+  end
+end