hecks 6.0.0 → 7.0.0

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

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require_relative "table/rows"
+require_relative "table/checks"
+
+module Hecks
+  module Projections
+    module CiPipeline
+      # A client's workflow rows, read from its bluebook and checked against the CiPipeline
+      # bluebook's vocabulary.
+      #
+      # The rows are the `member` lines of the value objects `Workflow`, `Trigger`, `Secret`,
+      # `Job`, `Need`, `Output`, `Env`, `Step` and `StepInput` in any bluebook of the project (the
+      # CiPipeline bluebook's Workflow, JobSpec and Step aggregates name the fields and the closed
+      # sets). This class joins them by workflow and job name into one tree and refuses a table that
+      # contradicts itself, naming every problem at once, each on the row it concerns.
+      class Table
+        # A table the projection refuses; the message lists each problem on its own line.
+        class Invalid < ArgumentError; end
+
+        # The name of the bluebook that declares the shape of a row.
+        BLUEBOOK = "CiPipeline"
+
+        # The value object whose member rows mark a bluebook as the client's.
+        MARKER = "Workflow"
+
+        # @return [Array<Tree::Workflow>] the workflows, in the order the client declared them
+        attr_reader :workflows
+
+        # Finds the one bluebook of a project that declares workflow rows.
+        #
+        # @param registry [Runtime::Registry] the registry the project booted into
+        # @return [Bluebook::Declaration] the bluebook holding `Workflow` rows
+        # @raise [Invalid] when no bluebook, or more than one, declares one
+        def self.bluebook(registry)
+          claimed = holders(registry)
+          raise Invalid, "no bluebook declares a value_object \"#{MARKER}\" with member rows" if claimed.empty?
+          return claimed.first if claimed.one?
+
+          raise Invalid, "#{claimed.size} bluebooks declare a value_object \"#{MARKER}\": " \
+                         "#{claimed.map(&:name).join(", ")}; a project has one set of workflow rows"
+        end
+
+        # @return [Array<Bluebook::Declaration>] the project's bluebooks that declare `Workflow` rows
+        def self.holders(registry)
+          clients = registry.bluebooks.values.reject { |bluebook| bluebook.name == BLUEBOOK }
+          clients.select { |bluebook| rows_of(bluebook, MARKER).any? }
+        end
+
+        # Reads and checks one bluebook's workflow rows.
+        #
+        # @param bluebook [Bluebook::Declaration] the bluebook that declares the rows
+        # @param registry [Runtime::Registry] the registry the project booted into, which holds the
+        #   CiPipeline bluebook
+        # @return [Table] the checked table
+        # @raise [Invalid] when the CiPipeline bluebook is not attached or a row is refused
+        def self.read(bluebook, registry:)
+          rows = Typing::SHAPES.keys.to_h { |object| [object, rows_of(bluebook, object)] }
+          new(rows, vocabulary: vocabulary(registry))
+        end
+
+        # @param registry [Runtime::Registry] a registry holding the CiPipeline bluebook
+        # @return [Hash{Symbol => Object}] `:trigger` and `:uses`, the closed sets, as arrays of
+        #   members, and `:patterns`, each named field to the regexp its bluebook value object holds
+        # @raise [Invalid] when the registry does not hold the CiPipeline bluebook
+        def self.vocabulary(registry)
+          pipeline = registry.bluebook(BLUEBOOK) or
+            raise Invalid, "the project does not attach the #{BLUEBOOK} bluebook (attaches \"#{BLUEBOOK}\")"
+          { trigger:  members(pipeline, "Workflow", "Trigger"),
+            uses:     members(pipeline, "JobSpec", "ActionRef").reject(&:empty?),
+            patterns: Rows::PATTERNS.transform_values { |(aggregate, object)| pattern(pipeline, aggregate, object) } }
+        end
+
+        # @param bluebook [Bluebook::Declaration] a bluebook to search
+        # @param object [String] the name of the value object whose rows are wanted
+        # @return [Array<Hash{Symbol => Object}>] the member rows of its value objects of that name
+        def self.rows_of(bluebook, object)
+          objects = bluebook.aggregates.flat_map(&:value_objects)
+          objects.select { |candidate| candidate.hecks_name == object }.flat_map(&:members)
+        end
+
+        # @return [Array<String>] the members of a closed set held as a value object of an aggregate
+        def self.members(bluebook, aggregate, object)
+          held(bluebook, aggregate, object).members.map { |member| member.fetch(:value) }
+        end
+
+        # @return [Regexp] the pattern of a value object's one attribute
+        def self.pattern(bluebook, aggregate, object)
+          Regexp.new(held(bluebook, aggregate, object).attributes.first.pattern)
+        end
+
+        # @return [Bluebook::ValueObject] a value object of an aggregate of the bluebook
+        def self.held(bluebook, aggregate, object)
+          bluebook.aggregate(aggregate).value_objects.find { |candidate| candidate.hecks_name == object }
+        end
+        private_class_method :holders, :members, :pattern, :held
+
+        # @param rows [Hash{String => Array<Hash{Symbol => Object}>}] each object's declared rows
+        # @param vocabulary [Hash{Symbol => Object}] the closed sets and patterns
+        # @raise [Invalid] when a row is refused
+        def initialize(rows, vocabulary:)
+          problems = []
+          @workflows = Rows.new(rows, vocabulary, problems).workflows
+          Checks.new(@workflows, vocabulary, problems).call
+          return if problems.empty?
+
+          raise Invalid, "the workflow rows are refused:\n#{problems.map { |line| "  - #{line}" }.join("\n")}"
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projections/ci_pipeline/workflows.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+require_relative "../../projector"
+require_relative "table"
+require_relative "yaml_text"
+
+module Hecks
+  module Projections
+    module CiPipeline
+      # A client's workflow rows as GitHub Actions workflow files, one per `Workflow` row.
+      #
+      # The text is a pure function of the rows: workflows, jobs and steps keep the order the client
+      # declared them in, and nothing in it names a time or a machine, so regenerating from the same
+      # rows changes nothing. A modeled `note` is written as the comment above what it belongs to.
+      module Workflows
+        extend Projector::Target
+
+        projects_as :ci_workflows, emits: :files
+
+        # Where the files go, relative to the checkout.
+        DIRECTORY = ".github/workflows"
+
+        # The banner every generated file starts with.
+        BANNER = "# Generated by hecks regeneration_run.project_ci_pipeline!. Do not edit; change the workflow rows."
+
+        # What each event of the bluebook's `Trigger` set is written as under `on:`.
+        EVENTS = { "push_main" => ["push:", "  branches: [main]"], "pull_request" => ["pull_request:"],
+                   "workflow_dispatch" => ["workflow_dispatch:"] }.freeze
+
+        module_function
+
+        # Renders each workflow of a table of rows.
+        #
+        # @param bluebook [Bluebook::Declaration] the bluebook that declares the rows
+        # @param options [Hash{Symbol => Object}] `:registry` (Runtime::Registry) the project booted
+        #   into, which holds the CiPipeline bluebook; `:table` (Table) a table already read
+        # @return [Hash{String => String}] each file's path under the checkout to its text; empty
+        #   when the bluebook declares no `Workflow` rows, as a site's root files are
+        # @raise [Table::Invalid] when the rows are refused
+        def call(bluebook:, options: {})
+          table = options[:table] || read(bluebook, options)
+          return {} unless table
+
+          table.workflows.to_h { |workflow| ["#{DIRECTORY}/#{workflow.name}", render(workflow)] }
+        end
+
+        # @return [Table, nil] the bluebook's rows checked against the registry's CiPipeline
+        #   bluebook, or nil when the bluebook holds none, which needs no registry to say
+        def read(bluebook, options)
+          return if Table.rows_of(bluebook, Table::MARKER).empty?
+
+          Table.read(bluebook, registry: options.fetch(:registry))
+        end
+
+        # @param workflow [Table::Rows::Workflow] a checked workflow
+        # @return [String] the file's text, ending in a newline
+        def render(workflow)
+          sections = [[BANNER], ["name: #{YamlText.scalar(workflow.display_name)}"], note(workflow.note),
+                      triggers(workflow), concurrency(workflow), jobs(workflow)]
+          "#{sections.reject(&:empty?).map { |lines| lines.join("\n") }.join("\n\n")}\n"
+        end
+
+        def note(text) = text.empty? ? [] : YamlText.comment(text)
+
+        def triggers(workflow)
+          ["on:", *YamlText.indent(workflow.triggers.flat_map { |event| event_lines(event, workflow) }, 2)]
+        end
+
+        def event_lines(event, workflow)
+          return EVENTS.fetch(event) unless event == "workflow_call"
+
+          ["workflow_call:", *YamlText.indent(secrets(workflow), 2)]
+        end
+
+        def secrets(workflow)
+          return [] if workflow.secrets.empty?
+
+          ["secrets:", *YamlText.indent(workflow.secrets.flat_map { |secret| secret_lines(secret) }, 2)]
+        end
+
+        def secret_lines(secret)
+          ["#{YamlText.key(secret.name)}:", "  required: #{secret.required}"]
+        end
+
+        def concurrency(workflow)
+          return [] if workflow.concurrency_group.empty?
+
+          ["concurrency:", "  group: #{YamlText.scalar(workflow.concurrency_group)}",
+           "  cancel-in-progress: #{workflow.cancel_in_progress}"]
+        end
+
+        def jobs(workflow)
+          blocks = workflow.jobs.map { |job| YamlText.indent([*note(job.note), *job_lines(job)], 2) }
+          ["jobs:", *blocks.flat_map { |lines| [*lines, ""] }[0...-1]]
+        end
+
+        def job_lines(job)
+          body = [*headline(job), *needs(job), *condition(job), *strategy(job), *pairs("outputs", job.outputs),
+                  *pairs("env", job.env), *steps(job)]
+          ["#{YamlText.key(job.name)}:", *YamlText.indent(body, 2)]
+        end
+
+        def headline(job)
+          ["runs-on: #{YamlText.scalar(job.runner)}", "timeout-minutes: #{job.timeout_minutes}", *permissions(job)]
+        end
+
+        def permissions(job)
+          return [] if job.permissions.empty?
+
+          ["permissions:", *job.permissions.split(", ").map { |scope| "  #{scope}" }]
+        end
+
+        def needs(job)
+          return [] if job.needs.empty?
+          return ["needs: #{YamlText.scalar(job.needs.first)}"] if job.needs.one?
+
+          ["needs: [#{job.needs.map { |name| YamlText.scalar(name) }.join(", ")}]"]
+        end
+
+        def condition(job) = job.condition.empty? ? [] : YamlText.folded("if", job.condition)
+
+        # A sharded job runs one leg for each number up to its total, and no leg cancels another.
+        def strategy(job)
+          return [] unless job.shard_total > 1
+
+          ["strategy:", "  fail-fast: false", "  matrix:",
+           "    #{YamlText.key(job.shard_axis)}: [#{(1..job.shard_total).to_a.join(", ")}]"]
+        end
+
+        def pairs(key, entries)
+          return [] if entries.empty?
+
+          ["#{key}:", *entries.map { |pair| "  #{YamlText.key(pair.key)}: #{YamlText.scalar(pair.value)}" }]
+        end
+
+        def steps(job)
+          lines = job.steps.each_with_index.flat_map do |step, index|
+            separator = index.positive? && !step.note.empty? ? [""] : []
+            [*separator, *note(step.note), *step_lines(step, job)]
+          end
+          ["steps:", *YamlText.indent(lines, 2)]
+        end
+
+        def step_lines(step, job)
+          fields = [*scalar_field("name", step.title), *scalar_field("id", step.id), *condition_of(step),
+                    *scalar_field("uses", step.uses), *pairs("with", step.inputs), *command(step, job)]
+          fields.each_with_index.map { |line, index| index.zero? ? "- #{line}" : "  #{line}" }
+        end
+
+        def scalar_field(key, text) = text.empty? ? [] : ["#{key}: #{YamlText.scalar(text)}"]
+
+        def condition_of(step) = step.condition.empty? ? [] : YamlText.folded("if", step.condition)
+
+        def command(step, job)
+          return [] if step.run.empty?
+
+          YamlText.literal("run", step.run.gsub(Table::Checks::SHARD_TOKEN, job.shard_total.to_s))
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projections/ci_pipeline/yaml_text.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "json"
+require "psych"
+
+module Hecks
+  module Projections
+    module CiPipeline
+      # The few shapes of YAML text a workflow needs: a scalar quoted only where YAML needs it, a
+      # comment, a literal block for a command and a folded block for a long condition.
+      #
+      # A scalar is written as the row spells it, so `14` and `false` stay a number and a boolean
+      # and any other text is the string, in double quotes when plain text would read as something
+      # else. Every function answers lines without a trailing newline.
+      module YamlText
+        # The longest a `key: value` line may be before a condition folds onto its own lines.
+        WIDTH = 100
+
+        # A character that makes plain text mean something other than a string when it comes first.
+        INDICATOR = /\A[-?:,\[\]{}#&*!|>'"%@`]/
+
+        # Text plain YAML cannot carry as it stands: padding, a colon, a comment, a line break.
+        UNPLAIN = /\A\s|\s\z|: | #|\n/
+
+        # Text that would not survive being folded at its spaces: a line break or padding.
+        UNFOLDABLE = /\n|\A\s|\s\z|\s\s/
+
+        # The line breaks that end a command.
+        TRAILING_BREAKS = /\n+\z/
+
+        # A key YAML takes bare.
+        BARE_KEY = /\A[A-Za-z_][\w.-]*\z/
+
+        # What a literal block's header says about the breaks that end it: none, one or all.
+        KEEP = { 0 => "-", 1 => "" }.freeze
+
+        module_function
+
+        # @param text [String] a key
+        # @return [String] the key, quoted when it is not a plain word
+        def key(text) = BARE_KEY.match?(text) ? text : JSON.generate(text)
+
+        # @param value [String, Integer, Boolean] a row's value
+        # @return [String] the scalar as YAML text
+        def scalar(value)
+          return value.to_s unless value.is_a?(String)
+
+          plain?(value) ? value : JSON.generate(value)
+        end
+
+        # @param text [String] some text
+        # @return [Boolean] whether plain YAML reads it back as a scalar that spells the same text
+        def plain?(text)
+          return false if text.empty? || text.match?(INDICATOR) || text.match?(UNPLAIN)
+
+          read = Psych.safe_load("v: #{text}").fetch("v")
+          !read.is_a?(Hash) && !read.is_a?(Array) && read.to_s == text
+        rescue Psych::Exception
+          false
+        end
+
+        # @param text [String] a note, one line per line of text
+        # @return [Array<String>] the comment lines, a blank line as a bare `#`
+        def comment(text)
+          text.split("\n", -1).map { |line| line.empty? ? "#" : "# #{line}" }
+        end
+
+        # @param key [String] the key the value belongs to
+        # @param text [String] a condition
+        # @return [Array<String>] one line, or the key and a folded block when the line is long
+        def folded(key, text)
+          line = "#{key}: #{scalar(text)}"
+          return [line] if line.length <= WIDTH || text.match?(UNFOLDABLE)
+
+          ["#{key}: >-", *wrap(text).map { |row| "  #{row}" }]
+        end
+
+        # @param key [String] the key the value belongs to
+        # @param text [String] a command
+        # @return [Array<String>] one line for a one-line command, else the key and a literal block
+        def literal(key, text)
+          return ["#{key}: #{scalar(text)}"] unless text.include?("\n")
+
+          body = text.sub(TRAILING_BREAKS, "")
+          breaks = text.length - body.length
+          rows = body.split("\n", -1).map { |row| row.empty? ? "" : "  #{row}" }
+          ["#{key}: |#{KEEP.fetch(breaks, "+")}", *rows, *[""] * [breaks - 1, 0].max]
+        end
+
+        # @param lines [Array<String>] lines
+        # @param width [Integer] how many spaces to put before each non-empty one
+        # @return [Array<String>] the indented lines
+        def indent(lines, width) = lines.map { |line| line.empty? ? line : "#{" " * width}#{line}" }
+
+        # @return [Array<String>] the words of the text packed into lines of at most the width
+        def wrap(text)
+          text.split.each_with_object([]) do |word, rows|
+            rows.empty? || rows.last.length + 1 + word.length > WIDTH - 6 ? rows << word.dup : rows.last << " #{word}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projections/deploy/box/hosting.rb

@@ -60,7 +60,7 @@ module Hecks
             args = "service=$(SERVICE) $(if $(EXISTING_TAG),existing_tag=$(EXISTING_TAG)) " \
                    "$(if $(LOCAL_IMAGE),local_image=$(LOCAL_IMAGE))"
             direct = "bash ./deploy-service.sh $(SERVICE)"
-            Box::RollRecipe.call(command: "service_roll.run", args: args, direct: direct)
+            Box::RollRecipe.call(command: "service_roll.run!", args: args, direct: direct)
           end
 
           # @param plan [Settings::Plan] the resolved settings

data/lib/hecks/projections/deploy/box/roll_recipe.rb

@@ -20,7 +20,7 @@ module Hecks
             args = plan.task_definition ? "$(if $(TASKDEF),taskdef=$(TASKDEF))" : "$(if $(TAGS),tags=\"$(TAGS)\")"
             direct = "bash ./deploy-box.sh $(#{variable})"
             direct += " || exit $$?; TASKDEF=\"$(TASKDEF)\" bash ./smoke-after-deploy.sh" if plan.hosting
-            "\t#{call(command: "box_roll.run", args: args, direct: direct)}"
+            "\t#{call(command: "box_roll.run!", args: args, direct: direct)}"
           end
 
           # @param command [String] the Deploy command, such as `box_roll.run`

data/lib/hecks/projections/deploy/box/roll_scripts.rb

@@ -117,7 +117,7 @@ module Hecks
           end
 
           def health_probe(label, args, wanted)
-            write_out = '-w "%{http_code}"' # rubocop:disable Style/FormatStringToken -- curl's own token
+            write_out = '-w "%{http_code}"'
             <<~SH.chomp
               code=$(curl -s -o /dev/null #{write_out} --max-time 40 localhost/#{args})
               #{wanted} && echo "ok   #{label} -> $code" || { echo "FAIL #{label} -> $code"; BAD=1; }

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

@@ -62,7 +62,7 @@ module Hecks
         # exits non-zero (24 when the smoke passed).
         SMOKE_RECIPE = [
           "@err=$$(mktemp); \\",
-          '$(HECKS) deploy smoke_run.run project="$(CURDIR)" --wait $(if $(TASKDEF),taskdef=$(TASKDEF)) 2>"$$err"; rc=$$?; \\',
+          '$(HECKS) deploy smoke_run.run! project="$(CURDIR)" --wait $(if $(TASKDEF),taskdef=$(TASKDEF)) 2>"$$err"; rc=$$?; \\',
           'if [ $$rc -ne 0 ] && grep -q \'^cannot open Hecks\' "$$err"; then \\',
           '  echo "==> the deploy record was NOT written: $$(grep -m1 \'^cannot open Hecks\' "$$err")" >&2; \\',
           *NO_DATABASE_ADVICE,

data/lib/hecks/projections/deploy/templates/fargate/Makefile.tmpl

@@ -35,7 +35,7 @@ build:
 # generator the Lambda deploy path already uses to produce
 # rust/dist/@@domain_name@@.wasm/.ir.json from this domain's own
 # .bluebook.
-	cd $(ROOT) && HECKS_ENVIRONMENT=memory ruby exe/hecks build.build_wasm domain=$(DOMAIN) --wait
+	cd $(ROOT) && HECKS_ENVIRONMENT=memory ruby exe/hecks build.build_wasm! domain=$(DOMAIN) --wait
 	cd $(HOST_DIR) && CARGO_TARGET_AARCH64_UNKNOWN_LINUX_GNU_LINKER=aarch64-linux-gnu-gcc rustup run stable cargo build --release --target aarch64-unknown-linux-gnu --bin bootstrap
 	cp $(HOST_DIR)/target/aarch64-unknown-linux-gnu/release/bootstrap @@domain_name@@-host
 	cp $(ROOT)/rust/dist/@@domain_name@@.wasm @@domain_name@@.wasm

data/lib/hecks/projections/deploy/templates/lambda/Makefile.tmpl

@@ -27,7 +27,7 @@ build-@@logical_id@@:
 # field). `hecks build_wasm` recompiles fast enough that "always
 # rebuild" is the safe default, matching rust/host's own bootstrap
 # build just below, which was never guarded this way to begin with.
-	cd @@root@@ && HECKS_ENVIRONMENT=memory ruby exe/hecks build.build_wasm domain=@@domain@@ --wait
+	cd @@root@@ && HECKS_ENVIRONMENT=memory ruby exe/hecks build.build_wasm! domain=@@domain@@ --wait
 	@rustup target list --installed 2>/dev/null | grep -qx aarch64-unknown-linux-gnu || rustup target add aarch64-unknown-linux-gnu
 # `rustup run stable`, not a bare `cargo lambda` — same reasoning
 # `hecks build_wasm`'s own Makefile-equivalent line holds itself to: a
@@ -129,12 +129,12 @@ restore-@@logical_id@@-build:
 .PHONY: verify-parity-@@logical_id@@
 verify-parity-@@logical_id@@:
 	@if [ -f @@root@@/spec/corpus/@@domain_name@@.json ]; then \
-		cd @@root@@ && HECKS_ENVIRONMENT=memory ruby exe/hecks build.check_conformance domain=@@domain@@ script=spec/corpus/@@domain_name@@.json artifact=$(WASM) --wait; \
+		cd @@root@@ && HECKS_ENVIRONMENT=memory ruby exe/hecks build.check_conformance! domain=@@domain@@ script=spec/corpus/@@domain_name@@.json artifact=$(WASM) --wait; \
 	else \
 		echo "verify-parity-@@logical_id@@: no spec/corpus/@@domain_name@@.json -- SKIPPING the pre-deploy Ruby/Rust parity check, nothing to compare $(WASM) against. Write one (hecks fuzz/hecks run's own script shape) before this domain's next deploy."; \
 	fi
 	@echo "verify-parity-@@logical_id@@: fuzzing $(WASM) against generated sequences (ADR 0037's bridge, WARN-ONLY -- see this target's own comment)..."
-	-@cd @@root@@ && HECKS_ENVIRONMENT=memory ruby exe/hecks build.fuzz_conformance domain=@@domain@@ artifact=$(WASM) --wait
+	-@cd @@root@@ && HECKS_ENVIRONMENT=memory ruby exe/hecks build.fuzz_conformance! domain=@@domain@@ artifact=$(WASM) --wait
 
 # `make mint-era` — takes @@stack_name@@'s RDS instance from freshly
 # created to "era 1 minted, ready for HECKS_DOMAIN/HECKS_ERA to

data/lib/hecks/projections/undo.rb

@@ -0,0 +1,46 @@
+require_relative "../projector"
+
+module Hecks
+  module Projections
+    # The command that undoes a declared command, read from the bluebook's compensations: a
+    # process manager's dispatch that names a `compensates` for the command. Answers "none
+    # declared" when no compensation is declared, and never invents one.
+    #
+    #   Projector.call(:undo, bluebook: bluebook, options: { command: "Account.Debit" })
+    module Undo
+      extend Hecks::Projector::Target
+
+      projects_as :undo
+
+      module_function
+
+      # @param bluebook [Bluebook::Declaration] the bluebook holding the process managers
+      # @param options [Hash{Symbol => Object}] `command:`, the command's verb form, e.g. "Account.Debit"
+      # @return [Array<String>] one sentence: the undoing command, or that none is declared
+      def call(bluebook:, options: {})
+        command = options.fetch(:command)
+        compensation = compensation_for(bluebook, command)
+        return ["#{command} has no undo declared: its bluebook names no compensating command."] unless compensation
+
+        ["#{command} is undone by #{compensation}, a compensation the bluebook declares."]
+      end
+
+      # The name of the command that undoes the named one, or nil.
+      #
+      # @return [String, nil]
+      def compensation_for(bluebook, command)
+        dispatch = bluebook.process_managers
+                           .flat_map { |manager| manager.handlers.flat_map(&:dispatches) }
+                           .find { |candidate| same_command?(candidate.command_name, command) && candidate.compensates }
+        compensation = dispatch&.compensates
+        compensation&.command_name
+      end
+
+      # Whether two command names are the same command, in either the `::` or the `.` spelling.
+      def same_command?(left, right)
+        normal = ->(name) { name.to_s.gsub("::", ".") }
+        normal.call(left) == normal.call(right)
+      end
+    end
+  end
+end

data/lib/hecks/projections.rb

@@ -20,6 +20,7 @@ require_relative "projections/reference"
 require_relative "projections/model"
 require_relative "projections/diagrams"
 require_relative "projections/statements"
+require_relative "projections/undo"
 require_relative "projections/context_relationships"
 require_relative "projections/world_skeleton"
 require_relative "projections/glossary"
@@ -32,4 +33,5 @@ require_relative "projections/deploy/vercel"
 require_relative "projections/deploy/smoke"
 require_relative "projections/deploy/template_diff"
 require_relative "projections/site/routes_ts"
+require_relative "projections/ci_pipeline/workflows"
 require_relative "projections/rails_app"

data/lib/hecks/projector/cli_projector/claims.rb

@@ -108,14 +108,25 @@ module Hecks
 
         # Maps every accepted spelling (full name, `:short` and a renamed command's old name)
         # to the full name.
+        LEAD_SEGMENT = /\A[^.]+/
+
         def aliases(specs)
           specs.each_with_object({}) do |(name, spec), map|
             map[name]         = name
             map[spec[:short]] = name
             map[spec[:short_was]] = name if spec[:short_was]
+            map[former_key(name, spec)] ||= name if spec[:formerly]
           end
         end
 
+        # The spelling a command had while its aggregate carried its former name, such as
+        # `old_name.board` for `new_name.board`; it resolves to the command, with a note.
+        #
+        # @return [String] the command's name with its aggregate's first segment replaced
+        def former_key(name, spec)
+          name.sub(LEAD_SEGMENT, Naming.snake(spec[:formerly]))
+        end
+
         # Stores `spec` under `name`, refusing a second claim rather than silently
         # keeping whichever command was walked first.
         #

data/lib/hecks/projector/cli_projector/command_help.rb

@@ -19,7 +19,12 @@ module Hecks
           out << "dispatches #{spec[:command]}" if spec[:kind] == :command
           out << "reads #{spec[:command]}"      if spec[:kind] == :query
           out << "issued by #{spec[:role]}" if spec[:role]
-          out
+          out.concat(command_help_audience_lines(spec))
+        end
+
+        # The audiences a command declares it is listed for, or nothing when it declares none.
+        def command_help_audience_lines(spec)
+          Array(spec[:audience]).any? ? ["listed for #{spec[:audience].join(", ")}"] : []
         end
 
         # The example call with every argument as `path=…`.

data/lib/hecks/projector/cli_projector/command_specs.rb

@@ -52,10 +52,20 @@ module Hecks
         # What the command declares about itself, apart from its arguments.
         def command_facts(aggregate, command)
           { summary: command.goal, role: command.role, role_gated: !command.role.to_s.empty?,
-            group: aggregate.hecks_name, internal: command.role.to_s == "System",
+            group: aggregate.hecks_name, internal: internal?(command), audience: command.audience,
+            formerly: aggregate.former_name,
             creates: command.creates? }
         end
 
+        # Whether the default listing leaves the command out. A declared audience decides: the
+        # listing is for a person. A command that declares none is a run's own bookkeeping when
+        # its role is `System`, else listed.
+        def internal?(command)
+          return command.role.to_s == "System" if command.audience.empty?
+
+          !command.audience.include?("person")
+        end
+
         # The receiver entries of a spec. `id=...` is still accepted for aggregate receivers but
         # hidden from help, which teaches only `to=...`.
         def receiver_facts(receiver)