hecks 2.8.0 → 3.0.0

data/lib/hecks/projection_files.rb

@@ -0,0 +1,285 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "tempfile"
+
+module Hecks
+  # What each `project_*` generator of the language writes, held as data: absolute path to text.
+  #
+  # The tables of the language (the model's holding half, the vocabulary, the parser's keywords, the
+  # Rust vocabulary, reserved names, field hints, the expression tables and the DSL reference) are
+  # projected from the Bluebook chapter's own declarations. Building them apart from writing them
+  # lets a caller compare a projection with the tree before anything is changed: a
+  # `hecks project_*` verb writes the answer, and the Hecks domain's Language commands report
+  # drift and write only when confirmed.
+  module ProjectionFiles
+    # The repository root this file lives in.
+    ROOT = File.expand_path("../..", __dir__)
+
+    # Raised when a projection would leave the language unable to boot.
+    class Refused < StandardError; end
+
+    # The files a projection writes, and the ones it leaves stale.
+    #
+    # @!attribute [r] content
+    #   @return [Hash{String => String}] absolute path to the text it should hold
+    # @!attribute [r] stale
+    #   @return [Array<String>] absolute paths the projection does not emit and removes
+    Result = Struct.new(:content, :stale)
+
+    # Rust keyword and Cargo name tables, by the constant each becomes.
+    RESERVED_TABLES = {
+      "RUST_KEYWORDS"               => "RustReservedWord",
+      "CARGO_RESERVED_DOMAIN_NAMES" => "CargoReservedName"
+    }.freeze
+
+    # Names of the projections, in the order a full regeneration runs them.
+    NAMES = %i[model vocabulary rust_vocabulary reserved_names parser_table bootstrap_table
+               field_hints expression_tables reference].freeze
+
+    module_function
+
+    # Builds one projection without writing anything.
+    #
+    # @param name [Symbol] one of `NAMES`
+    # @param root [String] the checkout the projection is for
+    # @return [Result] what it would write and remove
+    # @raise [ArgumentError] if the projection is not known
+    # @raise [Refused] if the projection would leave the language unable to boot
+    def build(name, root: ROOT)
+      raise ArgumentError, "no projection named #{name.inspect}" unless NAMES.include?(name.to_sym)
+
+      public_send(name, root)
+    end
+
+    # Writes one projection, each file through a temporary file and a rename so a reader never sees
+    # a partial file, and removes what it does not emit.
+    #
+    # @param name [Symbol] one of `NAMES`
+    # @param root [String] the checkout the projection is for
+    # @return [Array<String>] one `wrote <path>` or `removed <path>` line for each change
+    def write(name, root: ROOT)
+      result = build(name, root: root)
+      lines = result.content.map { |path, text| write_atomically(path, text) }
+      lines + result.stale.map { |path| File.delete(path) && "removed #{path}" }
+    end
+
+    # Writes one projection and prints what changed, as the `project_*` commands do.
+    #
+    # @param name [Symbol] one of `NAMES`
+    # @param root [String] the checkout the projection is for
+    # @return [void] the `wrote`/`removed` lines go to stdout
+    # @raise [SystemExit] with the reason on stderr when the projection is refused
+    def run(name, root: ROOT)
+      puts write(name, root: root)
+    rescue Refused => e
+      abort e.message
+    end
+
+    # Replaces a file through a same-directory temporary file and a rename.
+    #
+    # @param target [String] the file to write
+    # @param text [String] what it holds afterwards
+    # @return [String] the `wrote <path>` line
+    def write_atomically(target, text)
+      FileUtils.mkdir_p(File.dirname(target))
+      Tempfile.create(File.basename(target), File.dirname(target)) do |tmp|
+        tmp.write(text)
+        tmp.flush
+        File.rename(tmp.path, target)
+      end
+      "wrote #{target}"
+    end
+
+    # @param root [String] the checkout
+    # @return [Result] the model's holding half, one file for each thing the chapter holds
+    def model(root)
+      require "hecks"
+      files = Projector.call(:model, bluebook: chapter)
+      out = File.join(root, "lib/hecks/bluebook")
+      Result.new(files.to_h { |relative, text| [File.join(out, relative), text] }, [])
+    end
+
+    # @param root [String] the checkout
+    # @return [Result] `lib/hecks/vocabulary.rb`, the language's closed sets
+    def vocabulary(root)
+      require "hecks"
+      Result.new({ File.join(root, "lib/hecks/vocabulary.rb") => artifact_text(:vocabulary) }, [])
+    end
+
+    # @param root [String] the checkout
+    # @return [Result] one Rust enum a table under `rust/src/kernel/vocab/`; files it does
+    #   not emit are stale
+    def rust_vocabulary(root)
+      require "hecks"
+      kernel = File.join(root, "rust/src/kernel")
+      files = Projector.call(:rust_vocabulary, bluebook: chapter)
+      content = files.to_h { |relative, text| [File.join(kernel, relative), text] }
+      Result.new(content, Dir.glob(File.join(kernel, "vocab", "*.rs")) - content.keys)
+    end
+
+    # @param root [String] the checkout
+    # @return [Result] `reserved_names.rs` for the codegen and build crates, which share no library
+    # @raise [Refused] if a vocabulary declares no members
+    def reserved_names(root)
+      require "hecks/vocabulary"
+      consts = RESERVED_TABLES.map do |const, vocabulary|
+        words = Hecks::Vocabulary.fetch(vocabulary)
+        raise Refused, "vocabulary #{vocabulary} declares no members" if words.empty?
+
+        lines = words.map { |word| "    #{word.inspect}," }.join("\n")
+        "/// The `#{vocabulary}` vocabulary, #{words.size} entries.\n" \
+          "pub const #{const}: &[&str] = &[\n#{lines}\n];"
+      end
+      text = reserved_names_text(consts)
+      targets = %w[rust/codegen/src/reserved_names.rs rust/build/src/reserved_names.rs]
+      Result.new(targets.to_h { |target| [File.join(root, target), text] }, [])
+    end
+
+    # @param root [String] the checkout
+    # @return [Result] the Rust parser's keyword table
+    def parser_table(root)
+      require "hecks"
+      Result.new({ File.join(root, "rust/parser/src/keywords.rs") => artifact_text(:parser_table) }, [])
+    end
+
+    # @param root [String] the checkout
+    # @return [Result] the DSL's bootstrap-window fallbacks
+    def bootstrap_table(root)
+      require "hecks"
+      path = File.join(root, "lib/hecks/bluebook/dsl/bootstrap_table.rb")
+      Result.new({ path => artifact_text(:bootstrap_table) }, [])
+    end
+
+    # @param root [String] the checkout
+    # @return [Result] `rust/host/src/field_hints.rs`, the hints the host's form fields guess from
+    def field_hints(root)
+      require "hecks"
+      vocabulary = chapter.aggregates.find { |aggregate| aggregate.hecks_name == "Vocabulary" }
+      field_hint = vocabulary.value_objects.find { |value_object| value_object.hecks_name == "FieldHint" }
+      hints = field_hint.members.map(&:to_h)
+      Result.new({ File.join(root, "rust/host/src/field_hints.rs") => field_hints_text(hints) }, [])
+    end
+
+    # @param root [String] the checkout
+    # @return [Result] `lib/hecks/bluebook/expression/projection.json`
+    # @raise [Refused] if an admitted operator has no declared algebra, or the projection drops an
+    #   operator the language's own guards evaluate through
+    def expression_tables(root)
+      require "hecks"
+      require "hecks/grammar"
+      operators = expression_operators(Grammar.expression)
+      dropped = Grammar.self_bearing_operators.except(*operators.map { |row| row[:symbol] })
+      raise Refused, dropped_message(dropped) unless dropped.empty?
+
+      dispatcher = Grammar.expression
+      text = "#{JSON.pretty_generate(operators: operators, normalisations: Grammar.admitted_normalisations(dispatcher))}\n"
+      Result.new({ File.join(root, "lib/hecks/bluebook/expression/projection.json") => text }, [])
+    end
+
+    # The DSL reference pages and the README regions generated from the same declarations.
+    #
+    # @param root [String] the checkout
+    # @return [Result] every page of `docs/implemented/reference/` and `README.md`
+    def reference(root)
+      require "hecks"
+      directory = File.join(root, "docs/implemented/reference")
+      pages = Projector.call(:reference, bluebook: chapter, options: { from: directory })
+      content = pages.to_h { |relative, text| [File.join(directory, relative), text] }
+      readme = File.join(root, "README.md")
+      content[readme] = Doc::Reference.render_readme(root, File.read(readme))
+      Result.new(content, [])
+    end
+
+    # @param projection [Symbol] a projection registered with the projector
+    # @return [String] what it projects from the Bluebook chapter, as the text a file holds
+    def artifact_text(projection)
+      artifact = Projector.call(projection, bluebook: chapter)
+      artifact.is_a?(String) ? artifact : "#{JSON.pretty_generate(artifact)}\n"
+    end
+
+    # @return [Bluebook::Aggregate] the Bluebook chapter, which every projection reads
+    def chapter
+      Bluebook::MetaValidator.grammar_registry.bluebook("Bluebook")
+    end
+
+    # @param dispatcher [Object] the expression dispatcher
+    # @return [Array<Hash>] each admitted operator, with the algebra a comparison declares
+    # @raise [Refused] if a comparison has no declared algebra
+    def expression_operators(dispatcher)
+      vocabulary = chapter.aggregates.find { |aggregate| aggregate.name == "Vocabulary" }
+      algebra = vocabulary.value_objects.find { |value_object| value_object.hecks_name == "Comparison" }
+                          .members.to_h { |row| [row.to_h.values.first, row.to_h] }
+      Grammar.admitted_operators(dispatcher).map do |op|
+        row = { symbol: op[:symbol], category: op[:category], precedence: op[:precedence], arity: op[:arity] }
+        next row unless op[:category] == "comparison"
+
+        declared = algebra.fetch(op[:symbol]) do
+          raise Refused, "#{op[:symbol]} is admitted but Vocabulary::Comparison declares no algebra for it"
+        end
+        row.merge(compares_less_than: declared[:compares_less_than],
+                  compares_equal: declared[:compares_equal], negated: declared[:negated])
+      end
+    end
+
+    # @param dropped [Hash{String => Array<String>}] operator to the guards evaluating through it
+    # @return [String] one line for each operator a projection would strand
+    def dropped_message(dropped)
+      dropped.map do |symbol, sites|
+        "#{symbol} is self-bearing — the language's own predicates evaluate through it " \
+          "(#{sites.first(3).join('; ')}) — rewrite those guards before retiring it"
+      end.join("\n")
+    end
+
+    # @param consts [Array<String>] the rendered Rust constants
+    # @return [String] the whole `reserved_names.rs`
+    def reserved_names_text(consts)
+      <<~RUST
+        // GENERATED by hecks project_reserved_names from the RustReservedWord and
+        // CargoReservedName vocabularies (lib/hecks/language/bluebook/
+        // vocabulary.bluebook). Do not hand-edit — re-run hecks project_reserved_names.
+
+        #{consts.join("\n\n")}
+      RUST
+    end
+
+    # @param hints [Array<Hash>] the rows of `Vocabulary::FieldHint`
+    # @return [String] the whole `field_hints.rs`
+    def field_hints_text(hints)
+      consts = hints.map { |hint| field_hint_constant(hint) }.join("\n")
+      <<~RUST
+        // GENERATED by hecks project_field_hints from Vocabulary::FieldHint
+        // (lib/hecks/language/bluebook/vocabulary.bluebook). Do not
+        // hand-edit — re-run hecks project_field_hints instead.
+        //
+        // web.rs's `text_field` matches these in the SAME precedence Ruby's
+        // own `text_field` does: EMAIL_HINT, then URL_HINT, then TEL_HINT —
+        // against `html_type`, first match wins — then, only if `html_type`
+        // stayed "text", TEXTAREA_HINT against `kind`.
+
+        use regex::Regex;
+        use std::sync::LazyLock;
+
+        #{consts}
+      RUST
+    end
+
+    # @param hint [Hash] one `FieldHint` row: its name, pattern and what it resolves to
+    # @return [String] the Rust `static` for it
+    def field_hint_constant(hint)
+      name = "#{hint[:name].upcase}_HINT"
+      <<~RUST
+        /// #{hint[:name].capitalize} hint, resolving to `#{hint[:resolves_to]}` on a match —
+        /// Vocabulary::FieldHint's own declared pattern, unmodified (the
+        /// same text `Regexp#source` reads off FieldShape's own
+        /// #{name}, which is built from this same row).
+        /// `(?i)` up front is this crate's spelling
+        /// of Ruby's trailing `/i` — the WHOLE pattern is case-insensitive
+        /// on both sides, never partially.
+        pub static #{name}: LazyLock<Regex> =
+            LazyLock::new(|| Regex::new(r#"(?i)#{hint[:pattern]}"#).expect("declared field-hint pattern must compile"));
+      RUST
+    end
+  end
+end

data/lib/hecks/projections/bootstrap_table.rb

@@ -2,28 +2,12 @@ require_relative "../projector"
 
 module Hecks
   module Projections
-    # **The bootstrap-window fallbacks, projected** — lib/hecks/bluebook/dsl/
-    # bootstrap_table.rb rendered from the chapter's own Keyword rows.
+    # Projects lib/hecks/bluebook/dsl/bootstrap_table.rb from the chapter's Keyword rows.
+    # Committed, not built at boot: it is read before the grammar table exists.
     #
     #   Projector.call(:bootstrap_table, bluebook: <the Bluebook chapter>)
     #
-    # While `MetaValidator.bootstrapping?` the grammar table does not exist
-    # yet, so `WordGate#method_missing` and `RuleReference#lookup` cannot
-    # read `calls:`/`resolves_via:`/`disambiguator:` off it — this table is
-    # what they read instead.
-    #
-    # A partition, not a filter: every live row lands in the table, not only
-    # the ones a bootstrap chapter happens to call. Picking a subset by
-    # grepping which words the core chapters use during bootstrap would risk
-    # quietly dropping any word a chapter starts using later. Including
-    # every row instead costs nothing: a builder with its own `def` never
-    # reaches `method_missing` at all, so a row no bootstrap chapter calls
-    # is simply never read.
-    #
-    # The table cannot be built at boot for the same reason it exists: it
-    # is read before the grammar it comes from has been assembled. So it is
-    # committed, like lib/hecks/vocabulary.rb, and spec/bootstrap_table_
-    # spec.rb re-projects it in memory and refuses a diff.
+    # Every live row is included, not only those a bootstrap chapter calls.
     module BootstrapTable
       extend Projector::Target
 
@@ -37,7 +21,7 @@ module Hecks
         # KeywordSeed under lib/hecks/language/).
         #
         # Do not edit. spec/bootstrap_table_spec.rb re-projects this in memory
-        # and refuses a diff — run bin/project_bootstrap_table instead.
+        # and refuses a diff — run hecks project_bootstrap_table instead.
         #
         # Plain data, no requires: this is read while the grammar table it was
         # projected from is still being built (`MetaValidator.bootstrapping?`).
@@ -45,20 +29,13 @@ module Hecks
 
       module_function
 
-      # Projects the bootstrap fallback table — the only real work this projector
-      # does, `bluebook` unused because the table is the whole language's grammar,
-      # not any one chapter's.
+      # Projects the bootstrap fallback table; both arguments are ignored (the table is
+      # the whole grammar) and exist for the `Projector::Target` calling convention.
       #
-      # @param bluebook [Bluebook::Chapter] ignored; present to satisfy the
-      #   `Projector::Target` calling convention
-      # @param options [Hash{Symbol => Object}] ignored; present to satisfy the
-      #   `Projector::Target` calling convention
       # @return [String] the rendered `lib/hecks/bluebook/dsl/bootstrap_table.rb` source
       def call(bluebook:, options: {}) = render(bluebook)
 
-      # Retired rows are out of the language; admitted and deprecated rows
-      # still dispatch — the same `status != "retired"` reading
-      # `GenericDispatch.shape_for` gives the live table.
+      # Every keyword row that is not retired; admitted and deprecated rows still dispatch.
       #
       # @return [Array<Hash{Symbol => String}>] every non-retired keyword row, each with
       #   at least `:context`, `:word`, `:status`, `:calls`, `:resolves_via` and
@@ -67,11 +44,8 @@ module Hecks
         Bluebook::MetaValidator::SyntaxBoot.call[:keywords].reject { |row| row[:status] == "retired" }
       end
 
-      # `[context, word] => :method` — WordGate's own key order.
-      #
-      # An overloaded word has one row per argument shape, and they all
-      # name the same method. Two that don't would make the table keep
-      # whichever came last, so that is refused instead.
+      # `[context, word] => :method`, in WordGate's key order.
+      # Overloaded rows must all name the same method; a mismatch raises rather than last-wins.
       #
       # @param rows [Array<Hash{Symbol => String}>] the keyword rows to build from,
       #   defaulting to every live one
@@ -90,9 +64,7 @@ module Hecks
             end
       end
 
-      # `[word, context] => { resolves_via:, disambiguator: }` —
-      # RuleReference's own key order, blank columns omitted, the same
-      # shape its live `lookup` answers.
+      # `[word, context] => { resolves_via:, disambiguator: }`, in RuleReference's key order.
       #
       # @param rows [Array<Hash{Symbol => String}>] the keyword rows to build from,
       #   defaulting to every live one
@@ -106,13 +78,9 @@ module Hecks
         end
       end
 
-      # Renders the bootstrap table as committable Ruby source — `CALLS` and
-      # `RESOLVES` frozen Hash literals under the generated-file header.
+      # Renders the `CALLS` and `RESOLVES` frozen Hash literals as Ruby source.
       #
-      # @param _bluebook [Bluebook::Chapter] ignored; the table draws from the whole
-      #   language's grammar, not this argument
-      # @return [String] the full `lib/hecks/bluebook/dsl/bootstrap_table.rb` source,
-      #   ready to write to disk
+      # @return [String] the full `lib/hecks/bluebook/dsl/bootstrap_table.rb` source
       def render(_bluebook)
         rows = live_keywords
         calls_lines = calls(rows).map { |key, target| "          #{key.inspect} => #{target.inspect}" }

data/lib/hecks/projections/deploy/fargate/assembly.rb

@@ -5,25 +5,12 @@ module Hecks
   module Projections
     module Deploy
       module Fargate
-        # Fills the optional sections of a rendered Fargate template.
-        #
-        # The template text carries `# TMPL:<name>` marker lines where an
-        # optional section belongs. `apply` replaces each with what the stack's
-        # `Settings::Plan` calls for, and with nothing when the plan sets
-        # nothing there, so a world that uses none of the optional settings
-        # renders the template it always did.
+        # Fills the optional `# TMPL:<name>` sections of a rendered Fargate template with
+        # what the plan calls for, or nothing when a world uses none of them.
         module Assembly
           module_function
 
           # Replaces every optional-section marker in a rendered template.
-          #
-          # @param template [String] the rendered template holding `# TMPL:` marker lines
-          # @param plan [Settings::Plan] the stack's checked optional settings
-          # @param context [Hash{Symbol => Object}] `:stack_name`, `:vpc_ref`, `:listener_id`,
-          #   `:alb_id`, `:distribution_id` and `:db_secret_ref`
-          # @return [String] the template with the markers replaced
-          # @raise [ArgumentError] if `domain_env` removes a variable the generator does not set, or
-          #   the finished template declares one logical id or parameter twice
           def apply(template, plan, context)
             text = override_domain_env(template, plan.domain_env)
             sections(plan, context).each { |marker, block| text = Yaml.splice(text, marker, block) }

data/lib/hecks/projections/deploy/fargate/cdn.rb

@@ -7,38 +7,7 @@ module Hecks
     module Deploy
       module Fargate
         # The CloudFront distribution in front of the load balancer.
-        #
-        # With no `cdn` setting the stack gets `default_yaml`: the default
-        # certificate, one origin, and one behavior that caches nothing. A
-        # `cdn` setting replaces that with a distribution described by the
-        # world.
-        #
-        # ## Settings
-        #
-        # `cdn` is a hash with these optional keys:
-        #
-        # - `aliases`: hostnames the distribution answers to. Needs `certificate_arn`.
-        # - `certificate_arn`: an `ACM` certificate in us-east-1, or an intrinsic such as
-        #   `"!Ref CertArn"`.
-        # - `minimum_protocol`: the TLS policy for the certificate; `TLSv1.2_2021` by default.
-        # - `origin_id`: the id of the load-balancer origin; `<AlbId>Origin` by default.
-        # - `origin_ssl_protocols`: the TLS versions CloudFront may use to reach the origin, such
-        #   as `["TLSv1.2"]`.
-        # - `explicit_origin_ports`: false leaves `HTTPPort` and `HTTPSPort` unset; true by
-        #   default.
-        # - `origin_secret`: `{header:, parameter:}` sends a secret header to the origin, filled
-        #   from a `NoEcho` template parameter the stack declares under that name.
-        # - `extra_origins`: S3 origins, each `{id:, domain_name:, origin_access_control_id:}`.
-        # - `default_behavior`: `{origin:, viewer_protocol:, methods:, compress:, cache_policy:,
-        #   origin_request_policy:}`.
-        # - `behaviors`: entries of the same shape with a required `path`; the first match wins,
-        #   so order matters.
-        # - `retain`: true keeps the distribution when the stack is deleted or replaces it.
-        #
-        # A cache or origin-request policy is a managed policy's name (`caching_disabled`,
-        # `caching_optimized`, `all_viewer`, `all_viewer_except_host`, or `none` to omit an origin
-        # request policy) or the id of a policy in the account. `methods` is `all`, `read` or
-        # `get_head`.
+        # With no `cdn` setting the stack gets `default_yaml`; settings are in the DSL reference.
         module Cdn
           module_function
 
@@ -64,14 +33,6 @@ module Hecks
           HOSTNAME = /\A(\*\.)?([A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?\.)+[A-Za-z]{2,}\z/
 
           # Reads and checks the `cdn` setting.
-          #
-          # @param setting [Hash, nil] the world's `cdn` value, or nil when it sets none
-          # @param default_origin_id [String] the load-balancer origin's id when `origin_id` is not
-          #   set
-          # @return [Hash{Symbol => Object}, nil] the checked options with defaults applied, or nil
-          #   for none
-          # @raise [ArgumentError] if an option is unknown, malformed, or names an origin that does
-          #   not exist
           def normalize(setting, default_origin_id:)
             return nil if setting.nil?
 
@@ -87,9 +48,6 @@ module Hecks
           end
 
           # Lists the template parameters the options need.
-          #
-          # @param options [Hash, nil] the checked options from `normalize`
-          # @return [String] flush-left parameter text, or empty
           def parameters_yaml(options)
             secret = options && options[:origin_secret]
             return "" unless secret
@@ -103,11 +61,6 @@ module Hecks
           end
 
           # Renders the distribution for a set of checked options.
-          #
-          # @param options [Hash] the checked options from `normalize`
-          # @param distribution_id [String] the logical id the distribution is given
-          # @param alb_id [String] the logical id of the load balancer the origin points at
-          # @return [String] the flush-left resource text ending in a newline
           def yaml(options, distribution_id:, alb_id:)
             lines = ["#{distribution_id}:", "  Type: AWS::CloudFront::Distribution"]
             lines.push("  DeletionPolicy: Retain", "  UpdateReplacePolicy: Retain") if options[:retain]

data/lib/hecks/projections/deploy/fargate/cdn_default.rb

@@ -6,17 +6,8 @@ module Hecks
         module Cdn
           module_function
 
-          # The distribution a stack gets when its world sets no `cdn` options.
-          #
-          # Real HTTPS in front of the load balancer's HTTP-only listener, and
-          # the one safe caching default the generator can offer: every route
-          # is treated as session-driven, so nothing is cached. The comment
-          # inside the rendered block explains why, and reaches the generated
-          # template unchanged.
-          #
-          # @param alb_id [String] the logical id of the load balancer
-          # @param distribution_id [String] the logical id the distribution is given
-          # @return [String] the flush-left resource text with its comments, ending in a newline
+          # The distribution a stack gets when its world sets no `cdn` options: HTTPS in
+          # front of the HTTP-only ALB, caching disabled since every route is session-driven.
           def default_yaml(alb_id:, distribution_id:)
             <<~DEFAULT
               # Real HTTPS (the ALB's own Listener above is HTTP-only —

data/lib/hecks/projections/deploy/fargate/check.rb

@@ -2,15 +2,8 @@ module Hecks
   module Projections
     module Deploy
       module Fargate
-        # Validation for the optional settings a `deployed_to("AwsFargate")`
-        # block accepts beyond the required ones.
-        #
-        # `FargateTarget.Declare` in deploy.bluebook owns the baseline
-        # settings (`cpu`, `memory`, `port`, `database`, `web`). The keys added
-        # for multi-container stacks are nested shapes (lists of hashes, maps),
-        # which that aggregate's flat attributes cannot describe, so they are
-        # checked here. Every check raises `ArgumentError` naming the setting
-        # it was reading, so a mistake in a `.world` file points at its line.
+        # Validation for the optional Fargate settings beyond the baseline ones.
+        # Every check raises `ArgumentError` naming the setting it was reading.
         module Check
           module_function
 
@@ -71,7 +64,7 @@ module Hecks
                                  "(letters and digits, starting with a letter), got #{value.inspect}"
           end
 
-          # Checks that a value is a name AWS accepts for a container, repository or stack resource.
+          # Checks that a value is a name AWS accepts for a container, repository or stack.
           #
           # @param value [Object] the name as written in the world file
           # @param where [String] the setting's name, used in the error message
@@ -116,7 +109,7 @@ module Hecks
           # @param min [Integer] the fewest entries allowed
           # @param max [Integer, nil] the most entries allowed, or nil for no limit
           # @return [Array<String>] the entries as strings
-          # @raise [ArgumentError] if the value is not a list of strings or its size is out of range
+          # @raise [ArgumentError] if the value is not a list of strings or is out of size range
           def strings!(value, where, min: 0, max: nil)
             list = value.is_a?(Array) ? value : nil
             ok = list&.all? { |item| (item.is_a?(String) || item.is_a?(Symbol)) && !item.to_s.empty? }
@@ -128,9 +121,7 @@ module Hecks
           end
 
           # Checks that a value is a map of names to strings and returns it string-keyed.
-          #
-          # A `nil` value is kept: for the domain container's environment it
-          # removes a default variable.
+          # A `nil` value is kept: the domain container's env setting removes a variable with it.
           #
           # @param value [Object] the map as written in the world file
           # @param where [String] the setting's name, used in the error message