hecks 3.4.2 → 3.6.0

data/lib/hecks/projections/rust_vocabulary/tests.rb

@@ -0,0 +1,144 @@
+require_relative "../../runtime/refusal_wording"
+
+module Hecks
+  module Projections
+    module RustVocabulary
+      # The `#[cfg(test)]` module each projected enum file carries, as Rust lines.
+      module Tests
+        # The body of the placeholder test, after the line that opens its loop over the sites.
+        PLACEHOLDER_BODY = [
+          "            let template = site.template();",
+          "            let mut keys: Vec<String> = Vec::new();",
+          "            let mut current: Option<String> = None;",
+          "            for ch in template.chars() {",
+          "                match (ch, current.as_mut()) {",
+          "                    ('{', _) => current = Some(String::new()),",
+          "                    ('}', Some(key)) => {",
+          "                        keys.push(key.clone());",
+          "                        current = None;",
+          "                    }",
+          "                    (_, Some(key)) => key.push(ch),",
+          "                    (_, None) => {}",
+          "                }",
+          "            }",
+          "            let dummies: Vec<(String, String)> = keys.iter().map(|k| (k.clone(), format!(\"<{k}>\"))).collect();",
+          "            let pairs: Vec<(&str, &str)> = dummies.iter().map(|(k, v)| (k.as_str(), v.as_str())).collect();",
+          "            let rendered = site.render(&pairs);",
+          "            assert!(",
+          "                !rendered.contains('{') && !rendered.contains('}'),",
+          "                \"{site:?} left an unrendered placeholder behind: {rendered:?}\"",
+          "            );",
+          "        }",
+          "    }"
+        ].freeze
+
+        # Argument lists a refusal site's render test tries: empty, single and unsorted.
+        LIST_CASES = [[], ["only \"one\""], %w[zeta alpha mid]].freeze
+
+        module_function
+
+        # @param enum [String] the enum's name
+        # @param kind [Symbol] `:order`, `:templates` or `:set`
+        # @param variants [Array<String>] the variant names
+        # @param rows [Array<Hash>] the table's rows
+        # @param by_site [Hash, nil] a template table's argument rows by site
+        # @return [Array<String>] the test module, as Rust lines
+        def tests(enum, kind, variants = [], rows = [], by_site = nil)
+          lines = ["#[cfg(test)]", "mod tests {", "    use super::*;", ""] + kind_tests(enum, kind, variants, rows, by_site)
+          lines.pop while lines.last == ""
+          lines + ["}"]
+        end
+
+        # @return [Array<String>] the tests this kind of table has
+        def kind_tests(enum, kind, variants, rows, by_site)
+          return placeholder_test(enum) + [""] + render_args_test(variants, rows, by_site) if kind == :templates
+
+          lines = name_test(enum, kind)
+          kind == :order ? lines + order_test(enum) : lines
+        end
+
+        # @return [Array<String>] the test that every row is found by its own name
+        def name_test(enum, kind)
+          list = kind == :order ? "ORDER" : "ALL"
+          name = RustVocabulary.accessor_name(RustVocabulary.name_field(kind))
+          ["    #[test]",
+           "    fn every_row_is_found_by_its_own_name() {",
+           "        for row in #{enum}::#{list}.iter() {",
+           "            assert_eq!(#{enum}::from_name(row.#{name}()), Some(*row));",
+           "        }",
+           "    }",
+           ""]
+        end
+
+        # @return [Array<String>] the test that `position` is the index in `ORDER`
+        def order_test(enum)
+          ["    #[test]",
+           "    fn position_is_the_index_in_order() {",
+           "        for (index, step) in #{enum}::ORDER.iter().enumerate() {",
+           "            assert_eq!(step.position(), index);",
+           "        }",
+           "    }",
+           ""]
+        end
+
+        # Placeholders are read off each template's own text, never a second hand-kept list.
+        #
+        # @return [Array<String>] the test that no site renders a leftover placeholder
+        def placeholder_test(enum)
+          ["    #[test]",
+           "    fn every_site_renders_with_no_leftover_placeholder() {",
+           "        for site in #{enum}::ALL {"] + PLACEHOLDER_BODY
+        end
+
+        # Pins each site's typed `render_args` to Runtime::RefusalWording.render_with, computed
+        # here, for empty, single and unsorted list arguments; scalars carry a `"` to compare
+        # quoting.
+        #
+        # @return [Array<String>] the test that the Rust wording matches Ruby's
+        def render_args_test(variants, rows, by_site)
+          asserts = variants.zip(rows).flat_map do |variant, row|
+            specs = by_site.fetch(Arguments.site_key(row))
+            argument_cases(specs).map { |arguments| assertion(variant, row, specs, arguments) }
+          end
+          ["    #[test]",
+           "    fn render_args_matches_ruby_render_site() {",
+           asserts,
+           "    }"].flatten
+        end
+
+        # @return [Array<String>] one `assert_eq!` of a variant's rendered arguments
+        def assertion(variant, row, specs, arguments)
+          expected = Runtime::RefusalWording.render_with(row.fetch("template"), specs, arguments)
+          fields = specs.map do |spec|
+            name = spec.fetch("argument")
+            "#{Arguments.rust_field(name)}: #{rust_value(arguments.fetch(name.to_sym))}"
+          end
+          ["        assert_eq!(",
+           "            #{variant}Args { #{fields.join(", ")} }.render_args(),",
+           "            #{RustVocabulary.rust_string(expected)}",
+           "        );"]
+        end
+
+        # @param value [String, Array<String>] an argument value
+        # @return [String] the Rust expression for it
+        def rust_value(value)
+          return RustVocabulary.rust_string(value) unless value.is_a?(Array)
+
+          "&[#{value.map { |item| RustVocabulary.rust_string(item) }.join(", ")}]"
+        end
+
+        # @param specs [Array<Hash>] a site's argument rows
+        # @return [Array<Hash>] the argument values to try, by argument name
+        def argument_cases(specs)
+          cases = specs.any? { |spec| spec.fetch("shape") == "list" } ? LIST_CASES : [nil]
+          cases.map do |items|
+            specs.to_h do |spec|
+              name = spec.fetch("argument")
+              [name.to_sym, spec.fetch("shape") == "list" ? items : "#{name} \"x\""]
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projections/rust_vocabulary.rb

@@ -1,6 +1,9 @@
 require_relative "../projector"
 require_relative "../runtime/refusal_wording"
 require_relative "vocabulary"
+require_relative "rust_vocabulary/enum_body"
+require_relative "rust_vocabulary/arguments"
+require_relative "rust_vocabulary/tests"
 
 module Hecks
   module Projections
@@ -62,6 +65,10 @@ module Hecks
       def mod_file
         mods    = TABLES.values.map { |spec| "pub mod #{spec[:file]};" }.join("\n")
         exports = TABLES.values.map { |spec| "pub use #{spec[:file]}::#{spec[:enum]};" }.join("\n")
+        "#{mod_banner}\n#{mods}\n\n#{exports}\n"
+      end
+
+      def mod_banner
         <<~RUST
           // GENERATED by #{GENERATOR} (Hecks::Projections::RustVocabulary,
           // lib/hecks/projections/rust_vocabulary.rb) from the Vocabulary
@@ -71,319 +78,43 @@ module Hecks
           // One module per projected table. Every enum below is matched
           // exhaustively by its own accessors — no wildcard arm — so a row the
           // language gains fails to compile until it is handled.
-
-          #{mods}
-
-          #{exports}
         RUST
       end
 
       def table_file(table, spec, rows, argument_rows = nil)
         variants = rows.map { |row| variant_name(row, spec[:variant_from]) }
-        duplicates = variants.tally.select { |_, count| count > 1 }.keys
-        raise ArgumentError, "duplicate #{spec[:enum]} variant(s): #{duplicates.join(', ')}" if duplicates.any?
-
-        enum   = spec[:enum]
-        fields = rows.first.keys
-        by_site = spec[:kind] == :templates ? site_arguments(rows, argument_rows) : nil
-        body = [
-          header(table),
-          "#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]",
-          "pub enum #{enum} {",
-          variants.map { |variant| "    #{variant}," },
-          "}",
-          "",
-          "impl #{enum} {",
-          constants(enum, variants, spec[:kind]),
-          fields.map { |field| accessor(enum, field, variants, rows) },
-          from_name(enum, spec[:kind]),
-          extras(enum, variants, spec[:kind]),
-          "}",
-          "",
-          by_site ? argument_types(enum, variants, rows, by_site) : [],
-          tests(enum, spec[:kind], variants, rows, by_site)
-        ]
+        reject_duplicates!(spec[:enum], variants)
+        by_site = site_arguments_of(spec, rows, argument_rows)
+        body = [header(table), enum_lines(spec[:enum], variants), EnumBody.impl_lines(spec, variants, rows),
+                argument_lines(spec[:enum], variants, rows, by_site), tests_lines(spec, variants, rows, by_site)]
         "#{body.flatten.join("\n").rstrip}\n"
       end
 
-      def constants(enum, variants, kind)
-        list = variants.map { |variant| "        #{enum}::#{variant}," }
-        if kind == :order
-          ["    /// The declared step order, first to last.",
-           "    pub const ORDER: [#{enum}; #{variants.size}] = [", list, "    ];", ""]
-        else
-          ["    /// Every row, in declared order.",
-           "    pub const ALL: &'static [#{enum}] = &[", list, "    ];", ""]
-        end
-      end
-
-      def accessor(enum, field, variants, rows)
-        arms = variants.zip(rows).map { |variant, row| "            #{enum}::#{variant} => #{rust_string(row.fetch(field))}," }
-        ["    /// The row's declared `#{field}`.",
-         "    pub fn #{accessor_name(field)}(&self) -> &'static str {",
-         "        match self {",
-         arms,
-         "        }",
-         "    }",
-         ""]
+      def site_arguments_of(spec, rows, argument_rows)
+        Arguments.site_arguments(rows, argument_rows) if spec[:kind] == :templates
       end
 
-      # Built on the enum's own list and name accessor, not a string match, so no wildcard arm.
-      def from_name(enum, kind)
-        list  = kind == :order ? "ORDER" : "ALL"
-        field = kind == :templates ? "site" : name_field(kind)
-        ["    /// The row whose `#{field}` is `name`, if any.",
-         "    pub fn from_name(name: &str) -> Option<#{enum}> {",
-         "        #{enum}::#{list}.iter().copied().find(|row| row.#{accessor_name(field)}() == name)",
-         "    }",
-         ""]
+      def argument_lines(enum, variants, rows, by_site)
+        by_site ? Arguments.argument_types(enum, variants, rows, by_site) : []
       end
 
-      def extras(enum, variants, kind)
-        case kind
-        when :order
-          arms = variants.each_with_index.map { |variant, index| "            #{enum}::#{variant} => #{index}," }
-          ["    /// This step's index in `ORDER`.",
-           "    pub fn position(&self) -> usize {",
-           "        match self {",
-           arms,
-           "        }",
-           "    }"]
-        when :templates
-          ["    /// `RefusalWording.substitute`: replace every `{key}` marker, in the",
-           "    /// order given. A template is read, never evaluated. Private: call",
-           "    /// sites go through a site's typed `<Variant>Args::render_args`,",
-           "    /// which formats and supplies every declared argument.",
-           "    fn render(&self, values: &[(&str, &str)]) -> String {",
-           "        let mut text = self.template().to_string();",
-           "        for (key, value) in values {",
-           "            text = text.replace(&format!(\"{{{key}}}\"), value);",
-           "        }",
-           "        text",
-           "    }"]
-        else
-          []
-        end
+      def tests_lines(spec, variants, rows, by_site)
+        Tests.tests(spec[:enum], spec[:kind], variants, rows, by_site)
       end
 
-      # [refusal, site] => that site's argument rows; refused unless they name exactly the
-      # template's placeholders, in first-appearance order, with known formatting rules.
-      def site_arguments(rows, argument_rows)
-        grouped = argument_rows.group_by { |row| [row.fetch("refusal"), row.fetch("site")] }
-        orphans = grouped.keys - rows.map { |row| [row.fetch("refusal"), row.fetch("site")] }
-        raise ArgumentError, "RefusalSiteArgument rows name no RefusalTemplate: #{orphans.inspect}" if orphans.any?
-
-        rows.to_h do |row|
-          key   = [row.fetch("refusal"), row.fetch("site")]
-          specs = grouped.fetch(key, [])
-          wants = row.fetch("template").scan(/\{(\w+)\}/).flatten.uniq
-          names = specs.map { |spec| spec.fetch("argument") }
-          unless names == wants
-            raise ArgumentError, "RefusalSiteArgument for #{key.join('/')} declares #{names.inspect}; " \
-                                 "its template's placeholders are #{wants.inspect}"
-          end
-          specs.each { |spec| check_rule!(key, spec) }
-          [key, specs]
-        end
-      end
-
-      def check_rule!(key, spec)
-        where = "#{key.join('/')}.#{spec.fetch('argument')}"
-        unless Runtime::RefusalWording::SHAPES.include?(spec.fetch("shape"))
-          raise ArgumentError, "#{where}: unknown shape #{spec['shape'].inspect}"
-        end
-        unless Runtime::RefusalWording::QUOTINGS.include?(spec.fetch("quoting"))
-          raise ArgumentError, "#{where}: unknown quoting #{spec['quoting'].inspect}"
-        end
-        return if %w[true false].include?(spec.fetch("sorted"))
-
-        raise ArgumentError, "#{where}: sorted must be \"true\" or \"false\""
-      end
-
-      def argument_types(enum, variants, rows, by_site)
-        support = [
-          "/// Ruby's `#inspect` of a name, as a refusal quotes it: `{:?}` on a",
-          "/// `&str`, the quoting every kernel call site used before",
-          "/// RefusalSiteArgument existed.",
-          "fn quoted(text: &str) -> String {",
-          "    format!(\"{text:?}\")",
-          "}",
-          "",
-          "/// A list argument, written the way its RefusalSiteArgument row says:",
-          "/// sorted first (before quoting), each item quoted, then joined; an",
-          "/// empty list reads `when_empty`.",
-          "fn list(items: &[&str], sorted: bool, inspect: bool, separator: &str, when_empty: &str) -> String {",
-          "    let mut items = items.to_vec();",
-          "    if sorted {",
-          "        items.sort_unstable();",
-          "    }",
-          "    if items.is_empty() {",
-          "        return when_empty.to_string();",
-          "    }",
-          "    let write = |item: &&str| if inspect { quoted(item) } else { item.to_string() };",
-          "    items.iter().map(write).collect::<Vec<_>>().join(separator)",
-          "}",
-          ""
-        ]
-        support + variants.zip(rows).flat_map do |variant, row|
-          args_struct(enum, variant, row, by_site.fetch([row.fetch("refusal"), row.fetch("site")]))
-        end
+      def reject_duplicates!(enum, variants)
+        duplicates = variants.tally.select { |_, count| count > 1 }.keys
+        raise ArgumentError, "duplicate #{enum} variant(s): #{duplicates.join(", ")}" if duplicates.any?
       end
 
-      def args_struct(enum, variant, row, specs)
-        fields = specs.flat_map do |spec|
-          type = spec.fetch("shape") == "list" ? "&'a [&'a str]" : "&'a str"
-          ["    /// #{rule_reading(spec)}", "    pub #{rust_field(spec.fetch('argument'))}: #{type},"]
-        end
-        locals = specs.filter_map { |spec| formatted_local(spec) }
-        pairs  = specs.map do |spec|
-          name  = spec.fetch("argument")
-          value = formatted_local(spec) ? "#{local_name(name)}.as_str()" : "self.#{rust_field(name)}"
-          "            (#{rust_string(name)}, #{value}),"
-        end
-        ["/// `#{enum}::#{variant}`'s arguments — `RefusalWording.render_site(" \
-         "#{rust_string(row.fetch('refusal'))}, #{rust_string(row.fetch('site'))}, ...)`.",
-         "#[derive(Debug, Clone, Copy)]",
-         "pub struct #{variant}Args<'a> {",
-         fields,
-         "}",
-         "",
-         "impl #{variant}Args<'_> {",
-         "    /// The site's wording, every argument formatted by its declared row.",
-         "    pub fn render_args(&self) -> String {",
-         locals.map { |line| "        #{line}" },
-         "        #{enum}::#{variant}.render(&[",
-         pairs,
-         "        ])",
-         "    }",
+      def enum_lines(enum, variants)
+        ["#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]",
+         "pub enum #{enum} {",
+         variants.map { |variant| "    #{variant}," },
          "}",
          ""]
       end
 
-      def formatted_local(spec)
-        name  = spec.fetch("argument")
-        field = "self.#{rust_field(name)}"
-        if spec.fetch("shape") == "list"
-          "let #{local_name(name)} = list(#{field}, #{spec.fetch('sorted')}, #{spec.fetch('quoting') == 'inspect'}, " \
-            "#{rust_string(spec.fetch('separator'))}, #{rust_string(spec.fetch('when_empty'))});"
-        elsif spec.fetch("quoting") == "inspect"
-          "let #{local_name(name)} = quoted(#{field});"
-        end
-      end
-
-      def rule_reading(spec)
-        quoting = spec.fetch("quoting") == "inspect" ? ", quoted" : ""
-        return "scalar#{quoting}" unless spec.fetch("shape") == "list"
-
-        sorted = spec.fetch("sorted") == "true" ? ", sorted" : ""
-        "list#{sorted}#{quoting}, joined #{spec.fetch('separator').inspect}, empty reads #{spec.fetch('when_empty').inspect}"
-      end
-
-      def local_name(argument) = "#{argument}_text"
-
-      def rust_field(argument) = RUST_KEYWORDS.include?(argument) ? "r##{argument}" : argument
-
-      def tests(enum, kind, variants = [], rows = [], by_site = nil)
-        list = kind == :order ? "ORDER" : "ALL"
-        name = accessor_name(kind == :templates ? "site" : name_field(kind))
-        lines = ["#[cfg(test)]",
-                 "mod tests {",
-                 "    use super::*;",
-                 ""]
-        unless kind == :templates
-          lines += ["    #[test]",
-                    "    fn every_row_is_found_by_its_own_name() {",
-                    "        for row in #{enum}::#{list}.iter() {",
-                    "            assert_eq!(#{enum}::from_name(row.#{name}()), Some(*row));",
-                    "        }",
-                    "    }",
-                    ""]
-        end
-        lines += order_test(enum) if kind == :order
-        if kind == :templates
-          lines += placeholder_test(enum)
-          lines += [""] + render_args_test(variants, rows, by_site)
-        end
-        lines.pop while lines.last == ""
-        lines + ["}"]
-      end
-
-      def order_test(enum)
-        ["    #[test]",
-         "    fn position_is_the_index_in_order() {",
-         "        for (index, step) in #{enum}::ORDER.iter().enumerate() {",
-         "            assert_eq!(step.position(), index);",
-         "        }",
-         "    }",
-         ""]
-      end
-
-      # Placeholders are read off each template's own text, never a second hand-kept list.
-      def placeholder_test(enum)
-        ["    #[test]",
-         "    fn every_site_renders_with_no_leftover_placeholder() {",
-         "        for site in #{enum}::ALL {",
-         "            let template = site.template();",
-         "            let mut keys: Vec<String> = Vec::new();",
-         "            let mut current: Option<String> = None;",
-         "            for ch in template.chars() {",
-         "                match (ch, current.as_mut()) {",
-         "                    ('{', _) => current = Some(String::new()),",
-         "                    ('}', Some(key)) => {",
-         "                        keys.push(key.clone());",
-         "                        current = None;",
-         "                    }",
-         "                    (_, Some(key)) => key.push(ch),",
-         "                    (_, None) => {}",
-         "                }",
-         "            }",
-         "            let dummies: Vec<(String, String)> = keys.iter().map(|k| (k.clone(), format!(\"<{k}>\"))).collect();",
-         "            let pairs: Vec<(&str, &str)> = dummies.iter().map(|(k, v)| (k.as_str(), v.as_str())).collect();",
-         "            let rendered = site.render(&pairs);",
-         "            assert!(",
-         "                !rendered.contains('{') && !rendered.contains('}'),",
-         "                \"{site:?} left an unrendered placeholder behind: {rendered:?}\"",
-         "            );",
-         "        }",
-         "    }"]
-      end
-
-      # Pins each site's typed `render_args` to Runtime::RefusalWording.render_with, computed here,
-      # for empty, single and unsorted list arguments; scalars carry a `"` to compare quoting.
-      def render_args_test(variants, rows, by_site)
-        asserts = variants.zip(rows).flat_map do |variant, row|
-          specs = by_site.fetch([row.fetch("refusal"), row.fetch("site")])
-          argument_cases(specs).map do |arguments|
-            expected = Runtime::RefusalWording.render_with(row.fetch("template"), specs, arguments)
-            fields = specs.map do |spec|
-              value = arguments.fetch(spec.fetch("argument").to_sym)
-              rust_value = value.is_a?(Array) ? "&[#{value.map { |item| rust_string(item) }.join(', ')}]" : rust_string(value)
-              "#{rust_field(spec.fetch('argument'))}: #{rust_value}"
-            end
-            ["        assert_eq!(",
-             "            #{variant}Args { #{fields.join(', ')} }.render_args(),",
-             "            #{rust_string(expected)}",
-             "        );"]
-          end
-        end
-        ["    #[test]",
-         "    fn render_args_matches_ruby_render_site() {",
-         asserts,
-         "    }"].flatten
-      end
-
-      LIST_CASES = [[], ["only \"one\""], %w[zeta alpha mid]].freeze
-
-      def argument_cases(specs)
-        cases = specs.any? { |spec| spec.fetch("shape") == "list" } ? LIST_CASES : [nil]
-        cases.map do |items|
-          specs.to_h do |spec|
-            name = spec.fetch("argument")
-            [name.to_sym, spec.fetch("shape") == "list" ? items : "#{name} \"x\""]
-          end
-        end
-      end
-
       def name_field(kind) = kind == :order ? "step" : "name"
 
       # `refusal` reads ambiguously beside the kernel's own `Refusal` enum.

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

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require_relative "table"
+
+module Hecks
+  module Projections
+    module Site
+      # What a site's route table cannot say about who may use its admin pages: the session cookie,
+      # the host that vouches for it, the roles that count as an admin, and the two routes the
+      # sign-in is built from.
+      #
+      # A project declares one `member` row of a `value_object "Admin"` in the chapter that holds
+      # its route table. `docs/site-routes.md` lists the fields. A project that declares none has
+      # no admin sign-in to project.
+      class Admin
+        Setting = Struct.new(:session_cookie, :session_max_age, :host_env, :host_default, :roles,
+                             :account_path, :members_path, :sso_token_path, :sso_target, :login,
+                             :sso, :verdict_ttl_ms, :timeout_ms, :cms_base, keyword_init: true)
+
+        # The value object a project declares its admin row in.
+        OBJECT = "Admin"
+
+        # The fields the row may carry, with the Ruby class each takes.
+        FIELDS = {
+          session_cookie: String, session_max_age: Integer, host_env: String, host_default: String,
+          roles: String, account_path: String, members_path: String, sso_token_path: String,
+          sso_target: String, login: String, sso: String, verdict_ttl_ms: Integer, timeout_ms: Integer,
+          cms_base: String
+        }.freeze
+
+        # The fields the row must carry.
+        REQUIRED = %i[session_cookie host_env login sso].freeze
+
+        # What a field takes when the row does not carry it.
+        DEFAULTS = {
+          session_max_age: 14 * 24 * 60 * 60, host_default: "http://127.0.0.1:4322",
+          roles: "Admin,Owner", account_path: "/accounts/me", members_path: "/members",
+          sso_token_path: "/accounts/sso-token", sso_target: "/cms/api/sso",
+          verdict_ttl_ms: 10_000, timeout_ms: 5_000, cms_base: "/cms"
+        }.freeze
+
+        # The fields that name a path on the host or the content system, which start with a slash.
+        PATH_FIELDS = %i[account_path members_path sso_token_path sso_target cms_base].freeze
+
+        # @return [Setting] the checked row, defaults filled
+        attr_reader :setting
+
+        # Reads and checks the admin row a chapter declares.
+        #
+        # @param chapter [Bluebook::Chapter] the chapter that declares the route table
+        # @param table [Table] the checked route table
+        # @return [Admin, nil] the checked setting, or nil when the chapter declares none
+        # @raise [Table::Invalid] when the row is refused or contradicts the routes
+        def self.read(chapter, table:)
+          members = Table.rows_of(chapter, OBJECT)
+          return nil if members.empty?
+
+          new(members, table: table)
+        end
+
+        # @param members [Array<Hash{Symbol => Object}>] the declared rows
+        # @param table [Table] the checked route table
+        # @raise [Table::Invalid] naming every problem when there is one
+        def initialize(members, table:)
+          problems = []
+          problems << "a project declares one Admin row, not #{members.size}" if members.size > 1
+          row = members.first
+          typed = typed_fields(row, problems)
+          @setting = Setting.new(**DEFAULTS, **typed)
+          check(table.rows, problems) if problems.empty?
+          return if problems.empty?
+
+          raise Table::Invalid, "the admin sign-in is refused:\n#{problems.map { |line| "  - #{line}" }.join("\n")}"
+        end
+
+        # @return [Array<String>] the roles that count as an admin
+        def roles = setting.roles.split(",").map(&:strip).reject(&:empty?)
+
+        # @return [String] the path of the content system's sign-in endpoint inside its own API, the
+        #   part of `sso_target` after `<cms_base>/api`
+        def cms_endpoint = setting.sso_target.delete_prefix("#{setting.cms_base}/api")
+
+        private
+
+        def typed_fields(row, problems)
+          check_fields(row, problems)
+          row.slice(*FIELDS.keys).select do |field, value|
+            value.is_a?(FIELDS.fetch(field)) ||
+              (problems << "Admin row has #{field} #{value.inspect}; #{field} is a #{FIELDS.fetch(field)}")
+          end
+        end
+
+        def check_fields(row, problems)
+          unknown = row.keys - FIELDS.keys
+          problems << "Admin row has no field #{unknown.join(", ")}; fields are #{FIELDS.keys.join(", ")}" if unknown.any?
+          (REQUIRED - row.keys).each { |field| problems << "Admin row needs #{field}" }
+        end
+
+        def check(rows, problems)
+          check_paths(problems)
+          check_cms_base(problems)
+          problems << "Admin roles name no role" if roles.empty?
+          check_login(rows, problems)
+          check_sso(rows, problems)
+        end
+
+        def check_paths(problems)
+          (PATH_FIELDS + %i[login sso]).each do |field|
+            value = setting[field]
+            problems << "Admin #{field} #{value.inspect} must start with a slash" unless value.start_with?("/")
+          end
+        end
+
+        # The sign-in endpoint is the content system's own API route, under its base path.
+        def check_cms_base(problems)
+          return if setting.sso_target.start_with?("#{setting.cms_base}/api/")
+
+          problems << "Admin sso_target #{setting.sso_target} must be under #{setting.cms_base}/api/"
+        end
+
+        # The login page is a public row: a visitor with no session must reach it.
+        def check_login(rows, problems)
+          row = rows.find { |candidate| candidate.path == setting.login }
+          if row.nil?
+            problems << "Admin login #{setting.login} is not a route of the table"
+          elsif row.auth != "public"
+            problems << "Admin login #{setting.login} is #{row.auth}; the login page must be public"
+          end
+        end
+
+        # The hand-off to the content system is an admin endpoint: it answers only an admin.
+        def check_sso(rows, problems)
+          row = rows.find { |candidate| candidate.path == setting.sso }
+          return problems << "Admin sso #{setting.sso} is not a route of the table" if row.nil?
+
+          check_sso_row(row, problems)
+        end
+
+        def check_sso_row(row, problems)
+          problems << "Admin sso #{setting.sso} is #{row.auth}; it must be admin" unless row.auth == "admin"
+          problems << "Admin sso #{setting.sso} is a #{row.kind}; it must be an endpoint" unless row.kind == "endpoint"
+        end
+      end
+    end
+  end
+end