hecks 2.8.0 → 3.0.0

data/lib/hecks/projections/deploy/smoke.rb

@@ -1,37 +1,8 @@
 module Hecks
   module Projections
     module Deploy
-      # The smoke-test files a deployed stack can opt in to: a client-independent
-      # JavaScript harness and a GitHub Actions workflow that runs it on a schedule.
-      #
-      # Not a registered `Projector::Target` of its own. It adds files to whatever a
-      # deploy target already produced, so `bin/project_deploy` merges what `files`
-      # returns into the artifact, and a stack that has not opted in gets nothing.
-      #
-      # ## Opting in
-      #
-      # In the domain's `.world`, inside its `deployed_to` block:
-      #
-      #     deployed_to("AwsFargate") do
-      #       smoke true
-      #       smoke_role_arn "arn:aws:iam::123456789012:role/example-smoke"
-      #       smoke_secret_id "example-stack/session-secret"
-      #       smoke_site_url "https://example.org"
-      #     end
-      #
-      # `smoke_secret_field` names a JSON field when the secret is a JSON document,
-      # `smoke_secret_env` names the variable the harness reads it from (default
-      # `SESSION_SECRET`), `smoke_schedule` is a cron expression (default every 15
-      # minutes), `smoke_harness` and `smoke_config` are the repository-relative paths
-      # the workflow runs (defaults `smoke/harness.js` and `smoke/config.js`), and
-      # `smoke_setup` is one shell command run before the AWS steps, such as an
-      # install step the client's checks need.
-      #
-      # ## What stays with the client
-      #
-      # The harness knows nothing about any site. The pages and flows to assert, the
-      # cookie name, and the expected-era file are the client's own `config.js`, which
-      # this never writes.
+      # The smoke-test files a deployed stack can opt in to: a client-independent harness
+      # plus a scheduled GitHub Actions workflow, merged into whatever the deploy target made.
       module Smoke
         TEMPLATES = File.expand_path("smoke", __dir__).freeze
         DEFAULTS = {
@@ -59,10 +30,6 @@ module Hecks
 
         module_function
 
-        # Whether the domain's `deployed_to` settings ask for the smoke files.
-        #
-        # @param deploy_settings [Hash{Symbol => Object}] the `deployed_to` block's settings
-        # @return [Boolean] true only when `smoke true` was declared
         def enabled?(deploy_settings)
           deploy_settings[:smoke] == true
         end
@@ -87,12 +54,6 @@ module Hecks
           }
         end
 
-        # Applies the defaults and validates every value.
-        #
-        # @param deploy_settings [Hash{Symbol => Object}] the `deployed_to` block's settings
-        # @return [Hash{Symbol => String, nil}] the template values, keyed by placeholder name
-        # @raise [ArgumentError] if a required setting is missing or a value does not match its
-        #   pattern
         def resolve(deploy_settings)
           missing = REQUIRED.reject { |name| deploy_settings[setting_key(name)] }
           unless missing.empty?
@@ -109,22 +70,12 @@ module Hecks
           picked
         end
 
-        # The `deployed_to` setting that supplies a template value. The region is the
-        # deploy target's own; every other value has a `smoke_` prefix.
-        #
-        # @param name [Symbol] a template value name, such as `:role_arn`
-        # @return [Symbol] the setting key, such as `:smoke_role_arn`
+        # The region has no `smoke_` prefix; every other setting does.
         def setting_key(name)
           name == :region ? :region : :"smoke_#{name}"
         end
 
-        # Fills the workflow template. A placeholder line that resolves to nothing
-        # disappears whole rather than leaving a blank.
-        #
-        # @param template [String] the workflow template text
-        # @param values [Hash{Symbol => String, nil}] placeholder values, plus `:name`
-        # @return [String] the rendered workflow
-        # @raise [ArgumentError] if a placeholder is left unfilled
+        # A placeholder line that resolves to nothing disappears whole, not as a blank line.
         def render(template, values)
           filled = template.gsub(/^@@setup@@\n/) { setup_step(values[:setup]) }
           filled = filled.gsub("@@secret_field_pipe@@") { secret_field_pipe(values[:secret_field]) }
@@ -134,20 +85,12 @@ module Hecks
           filled
         end
 
-        # Renders the optional setup step, quoting the command for YAML.
-        #
-        # @param command [String, nil] the shell command from `smoke_setup`
-        # @return [String] a workflow step running it, or nothing
         def setup_step(command)
           return "" if command.nil?
 
           "      - name: Set up the smoke run\n        run: '#{command.gsub("'", "''")}'\n\n"
         end
 
-        # Builds the pipe that pulls one field out of a JSON secret document.
-        #
-        # @param field [String, nil] the JSON field of the secret document
-        # @return [String] the pipe that extracts it, or nothing when the secret is plain text
         def secret_field_pipe(field)
           return "" if field.nil?
 

data/lib/hecks/projections/deploy/template_diff/comparer.rb

@@ -2,29 +2,14 @@ module Hecks
   module Projections
     module Deploy
       module TemplateDiff
-        # Compares two loaded CloudFormation templates.
-        #
-        # Resources, parameters, outputs, conditions and mappings are matched
-        # by name, then compared property by property. A list of mappings that
-        # each carry a `Name`, `Id`, `Key` or similar field (container
-        # definitions, environment variables, tags, origins) is matched by that
-        # field, not by position, so inserting one entry reports one addition
-        # instead of a cascade of shifted values. Cache behaviors are matched
-        # the same way but their order is also checked, because CloudFront
-        # takes the first pattern that matches.
-        #
-        # Two values that differ only in how they are written (a number and
-        # the same digits as text, a `!Sub` with nothing but one `${Name}` and
-        # a `!Ref Name`) are equal after normalization or marked `cosmetic`.
+        # Compares two loaded CloudFormation templates, matching entries by an
+        # identity field such as `Name` or `Id` rather than by position.
         module Comparer
           module_function
 
           Change = Struct.new(:path, :kind, :before, :after, :cosmetic, keyword_init: true)
           Entity = Struct.new(:name, :type, :changes, :replaced, keyword_init: true)
           SectionDiff = Struct.new(:added, :removed, :changed, keyword_init: true) do
-            # Tells whether nothing in the section differs.
-            #
-            # @return [Boolean] true when no entity was added, removed or changed
             def empty? = added.empty? && removed.empty? && changed.empty?
           end
 
@@ -32,14 +17,7 @@ module Hecks
           IDENTITY_KEYS = %w[Name Id Key PolicyName PathPattern HeaderName ContainerName Sid Field].freeze
           ORDERED_BY = %w[PathPattern].freeze
 
-          # Compares two templates.
-          #
-          # @param before [Hash{String => Object}] the template as `Loader.load` returns it
-          # @param after [Hash{String => Object}] the template to compare it with
-          # @return [Hash{String => SectionDiff, Array<Change>}] one `SectionDiff` per entity
-          #   section
-          #   that either template has, and `"Template"` mapped to the changes in every other
-          #   top-level key such as `Description`
+          # Diffs each entity section by name, with other top-level keys grouped under "Template".
           def compare(before, after)
             before = normalize(before)
             after = normalize(after)

data/lib/hecks/projections/deploy/template_diff/loader.rb

@@ -4,17 +4,8 @@ module Hecks
   module Projections
     module Deploy
       module TemplateDiff
-        # Reads a CloudFormation template in YAML into plain Ruby data.
-        #
-        # CloudFormation's short forms (`!Ref Name`, `!GetAtt A.B`, `!Sub "..."`)
-        # are YAML tags that a stock loader refuses or drops. This loader walks
-        # the parsed document and turns each into the long form CloudFormation
-        # itself reads (`{"Ref" => "Name"}`, `{"Fn::GetAtt" => ["A", "B"]}`), so
-        # a template written with short forms and one written with long forms
-        # load to the same data. Comments and key order do not survive loading,
-        # which is what a comparison of two templates wants.
-        #
-        # Nothing here evaluates a template or contacts AWS.
+        # Reads a CloudFormation template in YAML into plain Ruby data, converting
+        # short-form intrinsics (`!Ref`, `!GetAtt`, `!Sub`) into their long form.
         module Loader
           module_function
 

data/lib/hecks/projections/deploy/template_diff.rb

@@ -5,39 +5,13 @@ require_relative "template_diff/comparer"
 module Hecks
   module Projections
     module Deploy
-      # An offline comparison of two CloudFormation templates.
-      #
-      # It answers "what would change if this template replaced that one"
-      # from the two files alone, the offline half of checking that a
-      # generated template leaves a live stack untouched: when the generated
-      # template and the one already deployed differ in nothing but comments,
-      # ordering and spelling, a change set against the live stack should be
-      # empty too. It reads no AWS state and changes nothing.
-      #
-      # ## What it reports
-      #
-      # Resources, parameters, outputs, conditions and mappings that were
-      # added, removed or changed, by logical id, and for a changed one every
-      # property that differs, with the value before and after. Other
-      # top-level keys, such as `Description`, are compared as values.
-      # Comments and the order of keys do not count, and the short and long
-      # forms of an intrinsic (`!Ref Name`, `{"Ref": "Name"}`) are the same
-      # thing. A change to a resource's `Type` is marked as a replacement.
-      # Differences that are only in how a value is written are marked
-      # cosmetic and do not count as a difference unless `strict` is set.
-      #
-      # ## What it does not do
-      #
-      # It does not know which property changes CloudFormation applies in
-      # place and which replace the resource beyond a change of `Type`, so a
-      # changed immutable property is listed as a change, not flagged.
+      # An offline diff of two CloudFormation templates: what would change if one replaced
+      # the other, ignoring comments, key order and equivalent intrinsic spellings.
       module TemplateDiff
         module_function
 
         Report = Struct.new(:sections, :strict, keyword_init: true) do
-          # Tells whether the two templates differ in a way that counts.
-          #
-          # @return [Boolean] false when every difference is cosmetic and the report is not strict
+          # False when every difference is cosmetic and the report is not strict.
           def different?
             sections.any? do |name, diff|
               if name == "Template"
@@ -48,32 +22,13 @@ module Hecks
             end
           end
 
-          # Keeps the changes that count towards a difference.
-          #
-          # @param changes [Array<Comparer::Change>] the changes to filter
-          # @return [Array<Comparer::Change>] every change, or only the non-cosmetic ones unless
-          #   strict
           def counted(changes) = strict ? changes : changes.reject(&:cosmetic)
         end
 
-        # Compares two template texts.
-        #
-        # @param before [String] the first template, YAML
-        # @param after [String] the second template, YAML
-        # @param strict [Boolean] whether cosmetic differences count as differences
-        # @return [Report] the differences, by section
-        # @raise [ArgumentError] if either text is not a valid template
         def diff(before, after, strict: false)
           Report.new(sections: Comparer.compare(Loader.load(before), Loader.load(after)), strict: strict)
         end
 
-        # Compares two template files.
-        #
-        # @param before_path [String] the path of the first template
-        # @param after_path [String] the path of the template to compare it with
-        # @param strict [Boolean] whether cosmetic differences count as differences
-        # @return [Report] the differences, by section
-        # @raise [ArgumentError] if either file is missing or is not a valid template
         def diff_files(before_path, after_path, strict: false)
           Report.new(
             sections: Comparer.compare(Loader.load_file(before_path), Loader.load_file(after_path)),
@@ -81,11 +36,7 @@ module Hecks
           )
         end
 
-        # Writes a report as text for a person to read.
-        #
-        # @param report [Report] the differences to describe
-        # @return [String] one section per kind of entity, each entity on a `+`, `-` or `~` line,
-        #   or `no differences` when nothing differs
+        # One line per entity: `+` added, `-` removed, `~` changed; `no differences` when none.
         def render(report)
           lines = report.sections.flat_map do |name, diff|
             name == "Template" ? template_lines(report, diff) : section_lines(report, name, diff)
@@ -96,10 +47,7 @@ module Hecks
           "#{(lines + note).join("\n")}\n"
         end
 
-        # Writes a report as JSON for a program to read.
-        #
-        # @param report [Report] the differences to describe
-        # @return [String] a JSON document with `different` and one entry per section
+        # Top-level keys: `different` and one entry per section.
         def render_json(report)
           sections = report.sections.to_h do |name, diff|
             [name, name == "Template" ? diff.map { |change| change_hash(change) } : section_hash(diff)]