hecks 6.0.0 → 7.0.0

data/lib/hecks/ports/persistence/plugins/era/translation/reconcile_files.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Hecks
+  module Translation
+    # Carries out an admitted `Reconcile` plan on the translations directory, and puts the files
+    # back when the audit of what was written refuses.
+    module ReconcileFiles
+      module_function
+
+      # Writes the plan's composed edge and deletes the edge files it supersedes.
+      #
+      # @param plan [Reconcile::Plan] a plan with status `:write`
+      # @return [Hash{String => String, nil}] each touched path with the text it held, nil if absent
+      def write!(plan)
+        originals = [plan.write_path, *plan.removals].compact.to_h { |path| [path, read_if_present(path)] }
+        File.write(plan.write_path, plan.text) if plan.write_path
+        plan.removals.each { |path| FileUtils.rm_f(path) }
+        originals
+      end
+
+      # Puts each touched file back as `write!` found it.
+      #
+      # @param originals [Hash{String => String, nil}] what `write!` returned
+      def restore!(originals)
+        originals.each do |path, text|
+          text ? File.write(path, text) : FileUtils.rm_f(path)
+        end
+      end
+
+      def read_if_present(path) = File.exist?(path) ? File.read(path) : nil
+    end
+  end
+end

data/lib/hecks/ports/persistence/plugins/era/translation/scaffold/differ.rb

@@ -1,4 +1,5 @@
 require_relative "../../storage_shape"
+require_relative "../../projected_bluebook"
 require_relative "path_diff"
 
 module Hecks
@@ -9,14 +10,19 @@ module Hecks
       module Differ
         include PathDiff
 
-        # Diffs two bluebook IRs into the edge's declarations.
+        # Diffs two storage shapes into the edge's declarations. Either side is a storage shape, a
+        # `Runtime::ProjectedBluebook` over one, or a declared bluebook, which is projected first.
         #
-        # @param held_bluebook [Bluebook::Declaration] the era being translated from
-        # @param current_bluebook [Bluebook::Declaration] the era being translated to
+        # @param held_bluebook [Hash, Runtime::ProjectedBluebook, Bluebook::Declaration] the era
+        #   being translated from
+        # @param current_bluebook [Hash, Runtime::ProjectedBluebook, Bluebook::Declaration] the era
+        #   being translated to
         # @return [Hash{Symbol => Object}] `:aggregates` (Array<Scaffold::ScaffoldedAggregate>),
         #   `:retired` (Array<String>, vanished names with no successor), `:unclaimed`
         #   (Array<String>, vanished names left ambiguous)
         def diff(held_bluebook, current_bluebook)
+          held_bluebook = Runtime::ProjectedBluebook.wrap(held_bluebook)
+          current_bluebook = Runtime::ProjectedBluebook.wrap(current_bluebook)
           held_shapes = projections(held_bluebook)
           current_shapes = projections(current_bluebook)
 
@@ -40,9 +46,11 @@ module Hecks
           ScaffoldedAggregate.new(name: aggregate.name, was: was, rules: rules)
         end
 
-        # Projects a bluebook's storage shape, indexing its aggregates by name.
+        # A side's storage shape, its aggregates indexed by name: a view's stored shape as it is, a
+        # declared bluebook's as `StorageShape.project` answers it.
         def projections(bluebook)
-          Runtime::StorageShape.project(bluebook)["aggregates"].to_h { |shape| [shape["name"], shape] }
+          shape = bluebook.is_a?(Runtime::ProjectedBluebook) ? bluebook.projection : Runtime::StorageShape.project(bluebook)
+          shape["aggregates"].to_h { |aggregate| [aggregate["name"], aggregate] }
         end
 
         # Pairs vanished aggregates with new ones whose full shape reappears under exactly one

data/lib/hecks/ports/persistence/plugins/era/translation.rb

@@ -7,5 +7,10 @@ end
 
 require_relative "translation/rule_compiler"
 require_relative "translation/scaffold"
+require_relative "translation/implicit_edge"
 require_relative "translation/audit"
+require_relative "translation/compose"
+require_relative "translation/edge_files"
+require_relative "translation/reconcile"
+require_relative "translation/reconcile_files"
 require_relative "translation/reattest"

data/lib/hecks/ports/persistence/plugins/era.rb

@@ -1,5 +1,6 @@
 require_relative "../plugin"
 require_relative "era/era_check"
+require_relative "era/era_status"
 require_relative "era/era_guard"
 require_relative "era/era_tamper"
 require_relative "era/storage_shape"

data/lib/hecks/ports/persistence/repository_factory.rb

@@ -43,7 +43,7 @@ module Hecks
         # @param bind [Bluebook::Bind] the bind naming the adapter
         # @param settings_verb [String] the verb whose settings configure the adapter
         # @return [Hash] the declared settings, under the adapter's own declared defaults, plus
-        #   the domain, resolved era and superseding era
+        #   the domain, resolved era, superseding era and whether the shape is unminted
         def adapter_settings(registry, domain, aggregate, bind, settings_verb)
           registry.check_verb(bind)
           settings = registry.binding_settings(domain, settings_verb, bind.adapter)
@@ -52,8 +52,16 @@ module Hecks
           settings = registry.with_adapter_defaults(bind.adapter, aggregate, settings)
           # domain, resolved era and superseding era ride along outside the declared
           # settings: a lineage adapter needs them to journal per domain, per-era.
-          settings.merge(domain: domain.to_s, era: registry.resolved_eras[domain.to_s],
-                         superseded_by: registry.superseded_eras[domain.to_s])
+          settings.merge(boot_marks(registry, domain))
+        end
+
+        # The per-domain marks the boot gate left on the registry, merged into an adapter's settings.
+        #
+        # @return [Hash] the domain, resolved era, superseding era and whether the shape is unminted
+        def boot_marks(registry, domain)
+          name = domain.to_s
+          { domain: name, era: registry.resolved_eras[name], superseded_by: registry.superseded_eras[name],
+            unminted: registry.unminted_eras.key?(name) }
         end
       end
     end

data/lib/hecks/ports/persistence/stored_name_guard.rb

@@ -0,0 +1,36 @@
+require_relative "../../runtime/errors"
+
+module Hecks
+  module Ports
+    module Persistence
+      # Refuses the boot that would store an aggregate in a new, empty table beside rows an earlier
+      # name still holds. A renamed aggregate's rows are found by its `stored_as`; if that line is
+      # missing or wrong, the adapter would create the empty table the new name implies and the
+      # rows would seem gone. This names the table the rows are in instead, and creates nothing.
+      module StoredNameGuard
+        module_function
+
+        # @param aggregate [Bluebook::Aggregate] the aggregate about to be stored
+        # @param row_count [#call] given a table's base name, the rows it holds (0 when absent)
+        # @return [void]
+        # @raise [Runtime::WiringError] when the aggregate's own table holds no rows and a prior
+        #   name's table does
+        def check!(aggregate, row_count:)
+          return if row_count.call(aggregate.storage_name).positive?
+
+          held = aggregate.prior_storage_names.to_h { |name| [name, row_count.call(name)] }.select { |_, rows| rows.positive? }
+          return if held.empty?
+
+          raise Runtime::WiringError, refusal(aggregate, held)
+        end
+
+        def refusal(aggregate, held)
+          name, rows = held.first
+          "cannot boot #{aggregate.name}: it would be stored in #{aggregate.storage_name.inspect}, which holds no rows, " \
+            "but #{name.inspect} holds rows (#{rows}) from an earlier name. Point the world at them with " \
+            "`stored_as #{aggregate.name}: #{name.inspect}`, or move the rows first. Nothing was created."
+        end
+      end
+    end
+  end
+end

data/lib/hecks/ports/persistence.rb

@@ -2,6 +2,8 @@ require_relative "persistence/constants"
 require_relative "persistence/binding_policy"
 require_relative "persistence/plugin"
 require_relative "persistence/repository_factory"
+require_relative "persistence/mint_door"
+require_relative "persistence/stored_name_guard"
 require_relative "persistence/append_only"
 require_relative "persistence/execution"
 require_relative "persistence/remote_runtime"

data/lib/hecks/projections/ci_pipeline/table/checks.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require_relative "tree"
+
+module Hecks
+  module Projections
+    module CiPipeline
+      class Table
+        # What no single row can show: a workflow nothing starts, secrets no caller can pass, a
+        # shard count that is not one a matrix can have, jobs that wait on one another in a circle,
+        # and a command that names a shard total its job does not have.
+        class Checks
+          # The text a step's command writes where its job's shard total belongs.
+          SHARD_TOKEN = "%{shard_total}"
+
+          # One scope of a job's `permissions:` line: a scope, a colon and what is allowed.
+          PERMISSION = /\A[a-z-]+: (read|write|none)\z/
+
+          # A command that begins with whitespace, which a literal block cannot carry.
+          LEADING_SPACE = /\A\s/
+
+          # @param workflows [Array<Tree::Workflow>] the joined workflows
+          # @param vocabulary [Hash{Symbol => Object}] the closed sets and patterns
+          # @param problems [Array<String>] collects each problem found, one line each
+          def initialize(workflows, vocabulary, problems)
+            @workflows = workflows
+            @vocabulary = vocabulary
+            @problems = problems
+          end
+
+          # @return [void]
+          def call
+            @workflows.each do |workflow|
+              check_workflow(workflow)
+              workflow.jobs.each { |job| check_job(job) }
+              check_cycles(workflow)
+            end
+          end
+
+          private
+
+          def check_workflow(workflow)
+            events = @vocabulary.fetch(:trigger)
+            problem(workflow, "has no Trigger row; an event is one of #{events.join(", ")}") if workflow.triggers.empty?
+            if workflow.secrets.any? && !workflow.triggers.include?("workflow_call")
+              problem(workflow, "has Secret rows but no workflow_call Trigger; only a called workflow takes secrets")
+            end
+            return unless workflow.cancel_in_progress && workflow.concurrency_group.empty?
+
+            problem(workflow, "cancels in progress without a concurrency_group to cancel within")
+          end
+
+          def check_job(job)
+            check_time_limit(job)
+            check_shard_total(job)
+            check_shard_axis(job)
+            check_shard_token(job)
+            check_permissions(job)
+            job.steps.select { |step| step.run.match?(LEADING_SPACE) }.each do |step|
+              problem(step, "starts its command with whitespace, which a block scalar cannot carry")
+            end
+          end
+
+          def check_time_limit(job)
+            return if job.timeout_minutes.to_i.positive?
+
+            problem(job, "has timeout_minutes #{job.timeout_minutes.inspect}; a job has a positive time limit")
+          end
+
+          def check_shard_total(job)
+            return unless job.shard_total < 1
+
+            problem(job, "has shard_total #{job.shard_total}; a sharded job has at least one shard")
+          end
+
+          def check_shard_axis(job)
+            if job.shard_total > 1 && job.shard_axis.empty?
+              problem(job, "has shard_total #{job.shard_total} and no shard_axis; the matrix needs a name")
+            elsif job.shard_total <= 1 && !job.shard_axis.empty?
+              problem(job, "has shard_axis #{job.shard_axis.inspect} but shard_total #{job.shard_total}; " \
+                           "a job with one shard has no matrix")
+            end
+          end
+
+          def check_shard_token(job)
+            return if job.shard_total > 1
+
+            job.steps.select { |step| step.run.include?(SHARD_TOKEN) }.each do |step|
+              problem(step, "writes #{SHARD_TOKEN} but its job has no shards")
+            end
+          end
+
+          def check_permissions(job)
+            scopes = job.permissions.split(", ")
+            scopes.grep_v(PERMISSION).each do |scope|
+              problem(job, "has permissions scope #{scope.inspect}; a scope is `<name>: read`, `write` or `none`, " \
+                           "separated by a comma and a space")
+            end
+          end
+
+          # Each cycle among a workflow's jobs, named once from the first job in it.
+          def check_cycles(workflow)
+            needs = needs_among(workflow)
+            reported = []
+            needs.each_key do |name|
+              cycle = cycle_from(name, needs) or next
+              next if reported.include?(cycle.sort)
+
+              reported << cycle.sort
+              problem(workflow, "has jobs that need each other in a circle: #{[*cycle, cycle.first].join(" -> ")}")
+            end
+          end
+
+          # @return [Hash{String => Array<String>}] each job's name to the declared jobs it needs
+          def needs_among(workflow)
+            names = workflow.jobs.map(&:name)
+            workflow.jobs.to_h { |job| [job.name, job.needs & names] }
+          end
+
+          # @return [Array<String>, nil] the jobs of a cycle that begins and ends at `start`
+          def cycle_from(start, needs, path = [start])
+            needs.fetch(path.last).each do |next_job|
+              return path if next_job == start
+              next if path.include?(next_job)
+
+              found = cycle_from(start, needs, [*path, next_job])
+              return found if found
+            end
+            nil
+          end
+
+          def problem(row, text) = @problems << "#{row.label} #{text}"
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projections/ci_pipeline/table/lookup.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Projections
+    module CiPipeline
+      class Table
+        # How a row finds what it belongs to: the workflow, job and step its fields name, and the
+        # refusal, naming what is declared, when there is none. Mixed into `Rows`, which holds the
+        # joined workflows in `@workflows` and the problems in `@problems`.
+        module Lookup
+          private
+
+          def workflow_of(row)
+            found = @workflows.find { |workflow| workflow.name == row[:workflow] }
+            return found if found
+
+            problem(row, "names workflow #{row[:workflow].inspect}, which no Workflow row declares; " \
+                         "its workflows are #{@workflows.map(&:name).join(", ")}")
+            nil
+          end
+
+          def job_of(row)
+            workflow = workflow_of(row) or return
+            found = workflow.jobs.find { |job| job.name == row[:job] }
+            return found if found
+
+            problem(row, "names job #{row[:job].inspect}, which workflow #{row[:workflow]} does not declare; " \
+                         "its jobs are #{workflow.jobs.map(&:name).join(", ")}")
+            nil
+          end
+
+          def step_of(job, row)
+            found = job.steps.find { |candidate| candidate.name == row[:step] }
+            return found if found
+
+            problem(row, "names step #{row[:step].inspect}, which job #{row[:job]} does not declare; " \
+                         "its steps are #{job.steps.map(&:name).join(", ")}")
+            nil
+          end
+
+          def check_pattern(row, pattern, field, reason)
+            regexp = @vocabulary.fetch(:patterns).fetch(pattern)
+            return if row[field].is_a?(String) && regexp.match?(row[field])
+
+            problem(row, "has #{field} #{row[field].inspect}; #{reason}, matching #{regexp.source}")
+          end
+
+          def twice(row, declared)
+            return unless declared
+
+            problem(row, "is declared twice")
+          end
+
+          def problem(row, text) = @problems << "#{row.fetch(:label)} #{text}"
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projections/ci_pipeline/table/refusals.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Projections
+    module CiPipeline
+      class Table
+        # The refusals a row earns from the bluebook's closed sets and from what its job declares,
+        # each naming the row and listing what is valid. Mixed into `Rows`, which holds the
+        # vocabulary in `@vocabulary` and the problems in `@problems`.
+        module Refusals
+          private
+
+          def refuse_event(row)
+            events = @vocabulary.fetch(:trigger)
+            return if events.include?(row[:event])
+
+            problem(row, "has event #{row[:event].inspect}; an event is one of #{events.join(", ")}")
+          end
+
+          def refuse_unknown_need(row)
+            names = workflow_of(row).jobs.map(&:name)
+            return if names.include?(row[:needs])
+
+            problem(row, "names job #{row[:needs].inspect}, which workflow #{row[:workflow]} does not declare; " \
+                         "its jobs are #{names.join(", ")}")
+          end
+
+          # A step uses an action or runs a command, and an action is one the bluebook admits.
+          def refuse_uses(row)
+            uses = row[:uses]
+            refuse_both(row) unless uses.empty? || row[:run].empty?
+            refuse_neither(row) if uses.empty? && row[:run].empty?
+            refuse_action(row) unless uses.empty?
+          end
+
+          def refuse_both(row)
+            problem(row, "has both uses and run; a step uses an action or runs a command, not both")
+          end
+
+          def refuse_neither(row)
+            problem(row, "has neither uses nor run; a step uses an action or runs a command")
+          end
+
+          def refuse_action(row)
+            actions = @vocabulary.fetch(:uses)
+            return if actions.include?(row[:uses])
+
+            problem(row, "has uses #{row[:uses].inspect}; uses is one of #{actions.join(", ")}")
+          end
+
+          def refuse_input_of_command(row)
+            problem(row, "names a step that runs a command; only a step that uses an action takes inputs")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projections/ci_pipeline/table/rows.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require_relative "tree"
+require_relative "typing"
+require_relative "lookup"
+require_relative "refusals"
+
+module Hecks
+  module Projections
+    module CiPipeline
+      class Table
+        # Joins the declared member rows into a tree of workflows, jobs and steps: each row is
+        # joined to its workflow and job by name, and each closed-set value is checked against
+        # the CiPipeline bluebook's vocabulary. A row that names what is not declared is refused,
+        # with what is declared listed.
+        class Rows
+          include Lookup
+          include Refusals
+
+          # The bluebook value objects whose pattern a field's text must match, by name.
+          PATTERNS = { workflow: %w[Workflow WorkflowName], secret: %w[Workflow SecretName],
+                       env: %w[JobSpec EnvName], output: %w[JobSpec OutputKey], step_id: %w[JobSpec StepId],
+                       shard_axis: %w[JobSpec ShardAxis] }.freeze
+
+          # The row objects in the order they are joined, each with the method that joins one row.
+          JOINS = { "Trigger" => :join_trigger, "Secret" => :join_secret, "Job" => :join_job,
+                    "Need" => :join_need, "Output" => :join_output, "Env" => :join_env,
+                    "Step" => :join_step, "StepInput" => :join_input }.freeze
+
+          # @return [Array<Tree::Workflow>] the workflows, in the order declared
+          attr_reader :workflows
+
+          # @param rows [Hash{String => Array<Hash{Symbol => Object}>}] each object's declared rows
+          # @param vocabulary [Hash{Symbol => Object}] the closed sets and patterns
+          # @param problems [Array<String>] collects each problem found, one line each
+          def initialize(rows, vocabulary, problems)
+            @vocabulary = vocabulary
+            @problems = problems
+            @typed = type_all(rows, Typing.new(problems))
+            @workflows = []
+            @typed.fetch("Workflow").each { |row| @workflows << build_workflow(row) }
+            JOINS.each { |object, join| @typed.fetch(object).each { |row| send(join, row) } }
+          end
+
+          private
+
+          def type_all(rows, typing)
+            rows.to_h { |object, members| [object, members.each_with_index.map { |row, i| typing.call(object, row, i) }] }
+          end
+
+          def build_workflow(row)
+            check_pattern(row, :workflow, :name, "a workflow is named by its file")
+            twice(row, @workflows.any? { |workflow| workflow.name == row[:name] })
+            fields = row.slice(:label, :name, :display_name, :note, :concurrency_group, :cancel_in_progress)
+            Tree::Workflow.new(**fields, triggers: [], secrets: [], jobs: [])
+          end
+
+          def join_trigger(row)
+            workflow = workflow_of(row) or return
+            refuse_event(row)
+            twice(row, workflow.triggers.include?(row[:event]))
+            workflow.triggers << row[:event]
+          end
+
+          def join_secret(row)
+            workflow = workflow_of(row) or return
+            check_pattern(row, :secret, :name, "a secret is named in capitals")
+            twice(row, workflow.secrets.any? { |secret| secret.name == row[:name] })
+            workflow.secrets << Tree::Secret.new(row[:name], row[:required])
+          end
+
+          def join_job(row)
+            workflow = workflow_of(row) or return
+            twice(row, workflow.jobs.any? { |job| job.name == row[:name] })
+            check_pattern(row, :shard_axis, :shard_axis, "a matrix is named in lower case") unless row[:shard_axis].empty?
+            fields = row.slice(:label, :name, :runner, :timeout_minutes, :permissions, :condition, :shard_total,
+                               :shard_axis, :note)
+            workflow.jobs << Tree::Job.new(**fields, needs: [], outputs: [], env: [], steps: [])
+          end
+
+          def join_need(row)
+            job = job_of(row) or return
+            refuse_unknown_need(row)
+            twice(row, job.needs.include?(row[:needs]))
+            job.needs << row[:needs]
+          end
+
+          def join_output(row) = join_pair(row, :output, :outputs, "an output is named by a key")
+
+          def join_env(row) = join_pair(row, :env, :env, "a variable is named in capitals")
+
+          def join_pair(row, pattern, list, reason)
+            job = job_of(row) or return
+            check_pattern(row, pattern, :key, reason)
+            twice(row, job[list].any? { |pair| pair.key == row[:key] })
+            job[list] << Tree::Pair.new(row[:key], row[:value])
+          end
+
+          def join_step(row)
+            job = job_of(row) or return
+            twice(row, job.steps.any? { |step| step.name == row[:name] })
+            check_pattern(row, :step_id, :id, "an id is lower case") unless row[:id].empty?
+            refuse_uses(row)
+            fields = row.slice(:label, :name, :title, :id, :uses, :run, :condition, :note)
+            job.steps << Tree::Step.new(**fields, inputs: [])
+          end
+
+          def join_input(row)
+            job = job_of(row) or return
+            step = step_of(job, row) or return
+            twice(row, step.inputs.any? { |pair| pair.key == row[:key] })
+            refuse_input_of_command(row) if step.uses.empty?
+            step.inputs << Tree::Pair.new(row[:key], row[:value])
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projections/ci_pipeline/table/tree.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Projections
+    module CiPipeline
+      class Table
+        # The workflows a table of rows joins into: each workflow holds its triggers, secrets and
+        # jobs, each job its needs, outputs, environment and steps, each step its `with:` inputs.
+        module Tree
+          # One workflow file with the rows that belong to it.
+          Workflow = Struct.new(:label, :name, :display_name, :note, :concurrency_group, :cancel_in_progress,
+                                :triggers, :secrets, :jobs, keyword_init: true)
+
+          # One secret a called workflow takes.
+          Secret = Struct.new(:name, :required)
+
+          # One job with the rows that belong to it.
+          Job = Struct.new(:label, :name, :runner, :timeout_minutes, :permissions, :condition, :shard_total,
+                           :shard_axis, :note, :needs, :outputs, :env, :steps, keyword_init: true)
+
+          # One step with its `with:` inputs.
+          Step = Struct.new(:label, :name, :title, :id, :uses, :run, :condition, :note, :inputs, keyword_init: true)
+
+          # A key and its value: a job output, an environment variable or a step input.
+          Pair = Struct.new(:key, :value)
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projections/ci_pipeline/table/typing.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Projections
+    module CiPipeline
+      class Table
+        # Checks the fields of each declared row and their types, and fills the defaults, so a row
+        # reaches the join as a hash of every field its object may carry.
+        class Typing
+          # The fields a row of each object may carry, with the Ruby class each takes (`:bool` is
+          # true or false). The order is the order the objects are joined in.
+          SHAPES = {
+            "Workflow"  => { name: String, display_name: String, note: String, concurrency_group: String,
+                            cancel_in_progress: :bool },
+            "Trigger"   => { workflow: String, event: String },
+            "Secret"    => { workflow: String, name: String, required: :bool },
+            "Job"       => { workflow: String, name: String, runner: String, timeout_minutes: Integer,
+                       permissions: String, condition: String, shard_total: Integer, shard_axis: String,
+                       note: String },
+            "Need"      => { workflow: String, job: String, needs: String },
+            "Output"    => { workflow: String, job: String, key: String, value: String },
+            "Env"       => { workflow: String, job: String, key: String, value: String },
+            "Step"      => { workflow: String, job: String, name: String, title: String, id: String, uses: String,
+                        run: String, condition: String, note: String },
+            "StepInput" => { workflow: String, job: String, step: String, key: String, value: String }
+          }.freeze
+
+          # The fields a row must name; every other field has a default.
+          REQUIRED = {
+            "Workflow" => %i[name display_name], "Trigger" => %i[workflow event],
+            "Secret" => %i[workflow name], "Job" => %i[workflow name runner timeout_minutes],
+            "Need" => %i[workflow job needs], "Output" => %i[workflow job key value],
+            "Env" => %i[workflow job key value], "Step" => %i[workflow job name],
+            "StepInput" => %i[workflow job step key value]
+          }.freeze
+
+          # The shard total of a job that is not split into legs.
+          UNSHARDED = 1
+
+          # The fields whose values name the row, in the order a label lists them.
+          IDENTITY = %i[workflow job step name event needs key].freeze
+
+          # @param problems [Array<String>] collects each problem found, one line each
+          def initialize(problems)
+            @problems = problems
+          end
+
+          # @param object [String] the row object's name, such as `Step`
+          # @param member [Hash{Symbol => Object}] the declared fields of one row
+          # @param index [Integer] the row's position, for a label when the row names nothing
+          # @return [Hash{Symbol => Object}] the row's `:label`, and each field, defaults filled
+          def call(object, member, index)
+            label = label_of(object, member, index)
+            shape = SHAPES.fetch(object)
+            refuse(label, member, shape, REQUIRED.fetch(object))
+            fields = shape.to_h { |key, type| [key, member.fetch(key) { default(object, key, type) }] }
+            { label: label, **fields }
+          end
+
+          private
+
+          def refuse(label, member, shape, required)
+            (member.keys - shape.keys).each do |key|
+              problem(label, "has no field #{key}; fields are #{shape.keys.join(", ")}")
+            end
+            member.slice(*shape.keys).each { |key, value| check_type(label, key, value, shape.fetch(key)) }
+            (required - member.keys).each { |key| problem(label, "has no #{key}") }
+          end
+
+          def label_of(object, member, index)
+            identity = member.values_at(*IDENTITY).compact
+            "#{object} #{identity.empty? ? "row #{index + 1}" : identity.join("/")}"
+          end
+
+          def default(object, key, type)
+            return UNSHARDED if object == "Job" && key == :shard_total
+
+            { String => "", Integer => nil, bool: false }.fetch(type)
+          end
+
+          def check_type(label, key, value, expected)
+            return if expected == :bool ? [true, false].include?(value) : value.is_a?(expected)
+
+            problem(label, "has #{key} #{value.inspect}; #{key} is #{expected == :bool ? "true or false" : "a #{expected}"}")
+          end
+
+          def problem(label, text) = @problems << "#{label} #{text}"
+        end
+      end
+    end
+  end
+end