hecks 3.5.0 → 3.7.0

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

@@ -0,0 +1,35 @@
+module Hecks
+  module Projections
+    module Deploy
+      # Fills the `@@name@@` markers of a text file under `templates/`: the CloudFormation, Makefile
+      # and shell text a deploy target emits lives there, and Ruby supplies each marker's value.
+      #
+      # A value is spliced as it is, so a multi-line value brings its own indentation. Every marker
+      # must be given a value; one left unfilled raises rather than reaching the emitted file.
+      module TextTemplate
+        DIR = File.join(__dir__, "templates").freeze
+        MARKER = /@@(\w+)@@/
+
+        module_function
+
+        # @param name [String] the template's path under `templates/`, e.g. `"preview/header.tmpl"`
+        # @param values [Hash{Symbol => #to_s}] each marker's replacement
+        # @return [String] the template text with every marker replaced
+        # @raise [KeyError] if the template holds a marker `values` does not name
+        def render(name, **values)
+          File.read(File.join(DIR, name)).gsub(MARKER) { values.fetch(Regexp.last_match(1).to_sym).to_s }
+        end
+
+        # Fills a template from an object that answers each marker's name.
+        #
+        # @param name [String] the template's path under `templates/`
+        # @param source [Object] answers a public method for every marker the template holds
+        # @return [String] the template text with every marker replaced
+        # @raise [NoMethodError] if the template holds a marker `source` does not answer
+        def render_from(name, source)
+          File.read(File.join(DIR, name)).gsub(MARKER) { source.public_send(Regexp.last_match(1)).to_s }
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projections/deploy/vercel/settings.rb

@@ -0,0 +1,83 @@
+module Hecks
+  module Projections
+    module Deploy
+      module Vercel
+        # Resolves a world's `deployed_to("Vercel")` settings into the checked plan the generator
+        # renders from.
+        #
+        # Every string that reaches `vercel.json` or the deploy script is matched against a
+        # conservative pattern first, so a world file cannot splice shell or JSON into the output.
+        # Secrets are named here, never held: `env` lists variable names, and the deploy script
+        # reads each value from the caller's environment.
+        module Settings
+          NAME      = /\A[a-z0-9][a-z0-9-]{0,99}\z/
+          SCOPE     = /\A[a-z0-9][a-z0-9_-]{0,99}\z/
+          ENV_VAR   = /\A[A-Z][A-Z0-9_]{0,99}\z/
+          CRON_PATH = %r{\A/[A-Za-z0-9/_.-]{0,200}\z}
+          SCHEDULE  = %r{\A[0-9*/,-]+( [0-9A-Za-z*/,-]+){4}\z}
+
+          # The variable the hecksagon's Postgres adapter reads; always set on deploy.
+          DATABASE_ENV = "DATABASE_URL".freeze
+
+          Plan = Data.define(:project, :scope, :region, :memory, :max_duration, :crons, :env)
+
+          module_function
+
+          # @param deploy_settings [Hash{Symbol => Object}] the world's `Vercel` settings
+          # @param target [Object] the validated `VercelTarget` (region, memory and duration,
+          #   already checked by `Declare`)
+          # @param infra_name [String] the project name the world or the domain gives
+          # @return [Plan] the resolved plan
+          # @raise [ArgumentError] when a setting is malformed
+          def resolve(deploy_settings:, target:, infra_name:)
+            s = deploy_settings
+            Plan.new(project: check(:project, infra_name, NAME), scope: optional(:scope, s[:scope], SCOPE),
+                     **declared_sizes(target), crons: read_crons(s.fetch(:crons, [])),
+                     env: read_env(s.fetch(:env, [])))
+          end
+
+          # @param target [Object] the declared `VercelTarget`
+          # @return [Hash{Symbol => Object}] the values `Declare` has already validated
+          def declared_sizes(target)
+            %i[region memory max_duration].to_h { |key| [key, target.state[key].value] }
+          end
+
+          # @return [String] the value, when it matches
+          # @raise [ArgumentError] when it does not
+          def check(key, value, pattern)
+            return value.to_s if value.to_s.match?(pattern)
+
+            raise ArgumentError, "#{key} #{value.inspect} is not allowed here (it must match #{pattern.source})"
+          end
+
+          # @return [String, nil] the value, or nil when the world left it out
+          def optional(key, value, pattern)
+            value.nil? ? nil : check(key, value, pattern)
+          end
+
+          # @param list [Array<Hash>] `[{ path: "/cron/tick", schedule: "0 * * * *" }]`
+          # @return [Array<Hash{Symbol => String}>] the checked crons
+          def read_crons(list)
+            raise ArgumentError, "crons must be a list of { path:, schedule: }" unless list.is_a?(Array)
+
+            list.map do |cron|
+              unless cron.is_a?(Hash) && cron.key?(:path) && cron.key?(:schedule)
+                raise ArgumentError, "a cron needs a path and a schedule, got #{cron.inspect}"
+              end
+
+              { path: check(:cron_path, cron[:path], CRON_PATH), schedule: check(:cron_schedule, cron[:schedule], SCHEDULE) }
+            end
+          end
+
+          # @param list [Array<String>] environment variable names the deploy sets on Vercel
+          # @return [Array<String>] the names, `DATABASE_URL` first, each once
+          def read_env(list)
+            raise ArgumentError, "env must be a list of variable names" unless list.is_a?(Array)
+
+            ([DATABASE_ENV] + list.map { |name| check(:env, name, ENV_VAR) }).uniq
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,134 @@
+require "json"
+require_relative "../../projector"
+require_relative "vercel/settings"
+
+module Hecks
+  module Projections
+    module Deploy
+      # The Vercel deploy target for `deployed_to("Vercel")`: the domain's Rust host as one Vercel
+      # function. It renders `vercel.json` (the function's size, region, the rewrite that sends
+      # every path to it, crons), `.vercelignore`, `deploy-vercel.sh` and a `Makefile`.
+      #
+      # Persistence is the hecksagon's: the host reads `DATABASE_URL`, which the deploy script sets
+      # from the caller's environment. This projection creates no database and holds no secret.
+      module Vercel
+        extend Projector::Target
+
+        projects_as :vercel, needs_world: true, emits: :files
+
+        # The function every request is rewritten to; its file is the host's Vercel entry point.
+        FUNCTION = "api/host".freeze
+
+        # Keeps only the release binaries in an uploaded `target/`, as Vercel's Rust guide advises.
+        VERCELIGNORE = <<~IGNORE.freeze
+          target/**
+          !target/release
+          !target/x86_64-unknown-linux-gnu/release/**
+          !target/aarch64-unknown-linux-gnu/release/**
+        IGNORE
+
+        module_function
+
+        # @param bluebook [Bluebook::Behaviour::Chapter] the domain's own booted chapter
+        # @param options [Hash] generation options; same shape as `Box.call`'s
+        # @return [Hash{String => String}] the generated file contents, keyed by filename
+        # @raise [ArgumentError] if the domain's deploy settings are invalid
+        def call(bluebook:, options: {})
+          world, domain, world_file = options.values_at(:world, :domain_dir, :world_file)
+          settings = tenant_settings(world.for_verb("deployed_to"), options[:tenant] || {}, File.basename(domain))
+          target = declare(world.domain, settings, world_file)
+          infra_name = (settings[:stack_name] || File.basename(domain)).to_s.tr("_", "-").downcase
+          plan = Settings.resolve(deploy_settings: settings, target: target, infra_name: infra_name)
+          render_all(plan)
+        end
+
+        # @return [Hash{Symbol => Object}] the settings with the `--tenant` suffix on the stack name
+        def tenant_settings(settings, tenant, domain_name)
+          return settings unless tenant[:tenant]
+
+          settings.merge(stack_name: "#{settings[:stack_name] || domain_name}-#{tenant[:tenant]}")
+        end
+
+        # Validates the target through the Deploy bluebook's own `VercelTarget.Declare`.
+        #
+        # @return [Object] the declared target aggregate
+        # @raise [ArgumentError] when the bluebook refuses a value
+        def declare(domain, settings, world_file)
+          dispatcher = Hecks.boot(File.expand_path("../../deploy", __dir__))
+          dispatcher.dispatch("Deploy::VercelTarget.Declare", with: declare_arguments(domain, settings)).instance
+        rescue *Hecks::Runtime::DOMAIN_REFUSALS => e
+          raise ArgumentError, "#{world_file}'s deployed_to(\"Vercel\") is invalid: #{e.message}"
+        end
+
+        # @return [Hash{Symbol => Hash}] the `VercelTarget.Declare` arguments, each a `{ value: }`
+        def declare_arguments(domain, settings)
+          {
+            domain: { value: domain }, region: { value: settings.fetch(:region, "iad1") },
+            memory: { value: settings.fetch(:memory, 1024) },
+            max_duration: { value: settings.fetch(:max_duration, 30) }
+          }
+        end
+
+        # @param plan [Settings::Plan] the resolved settings
+        # @return [Hash{String => String}] every generated file
+        def render_all(plan)
+          { "vercel.json" => vercel_json(plan), ".vercelignore" => VERCELIGNORE,
+            "deploy-vercel.sh" => deploy_script(plan), "Makefile" => makefile(plan) }
+        end
+
+        # @param plan [Settings::Plan] the resolved settings
+        # @return [String] `vercel.json`
+        def vercel_json(plan)
+          config = {
+            "$schema"   => "https://openapi.vercel.sh/vercel.json",
+            "functions" => { "#{FUNCTION}.rs" => { "memory" => plan.memory, "maxDuration" => plan.max_duration } },
+            "regions"   => [plan.region],
+            "rewrites"  => [{ "source" => "/(.*)", "destination" => "/#{FUNCTION}" }]
+          }
+          config["crons"] = plan.crons.map { |cron| cron.transform_keys(&:to_s) } if plan.crons.any?
+          "#{JSON.pretty_generate(config)}\n"
+        end
+
+        # The script sets each named variable on the project from the caller's environment over
+        # stdin, so no value is on a command line or in a file, then deploys to production.
+        #
+        # @param plan [Settings::Plan] the resolved settings
+        # @return [String] `deploy-vercel.sh`
+        def deploy_script(plan)
+          scope = plan.scope ? " --scope #{plan.scope}" : ""
+          sets = plan.env.map { |name| env_command(name, scope) }
+          <<~SH
+            #!/bin/bash
+            # Deploys #{plan.project} to Vercel production. Needs VERCEL_TOKEN and each variable below in the
+            # environment, e.g. `op run --env-file=.env.tpl -- make deploy`; no value is written to disk.
+            set -euo pipefail
+            cd "$(dirname "$0")"
+            vercel link --yes --project #{plan.project}#{scope}
+            #{sets.join("\n")}
+            vercel deploy --prod --yes#{scope}
+          SH
+        end
+
+        # @param name [String] a checked variable name
+        # @param scope [String] the ` --scope team` flag, or empty
+        # @return [String] the line that reads the variable and sets it on the project
+        def env_command(name, scope)
+          "printf '%s' \"${#{name}:?#{name} must be set in the environment}\" | " \
+            "vercel env add #{name} production --sensitive --force --yes#{scope}"
+        end
+
+        # @param plan [Settings::Plan] the resolved settings
+        # @return [String] the `Makefile`
+        def makefile(plan)
+          <<~MAKE
+            # #{plan.project}: one Vercel function.
+            #   make deploy   (needs VERCEL_TOKEN and #{plan.env.join(", ")} in the environment)
+            .PHONY: deploy
+            deploy:
+            \t./deploy-vercel.sh
+          MAKE
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projections/diagrams/dispatch.rb

@@ -0,0 +1,114 @@
+module Hecks
+  module Projections
+    module Diagrams
+      # The diagrams of what happens when something is called: the command-to-event-to-policy
+      # flow, and each aggregate's surface of commands, mutations and queries.
+      module Dispatch
+        module_function
+
+        # @param bluebook [Bluebook::Chapter] the assembled chapter
+        # @return [String, nil] commands, the events they emit and the policies those trigger,
+        #   or nil when there are none
+        def dispatch_diagram(bluebook)
+          lines = (command_edges(bluebook) + bluebook.policies.map { |policy| trigger_edge(policy) }).compact
+          return nil if lines.empty?
+
+          subject = "#{bluebook.name}'s own declared commands' emits and policies' on/trigger"
+          Diagrams.flowchart(bluebook, subject, lines)
+        end
+
+        def command_edges(bluebook)
+          Diagrams.holders(bluebook).flat_map do |holder|
+            holder.commands.flat_map do |command|
+              command.emits.map { |event| emits_edge(holder, command, event) }
+            end
+          end
+        end
+
+        def emits_edge(holder, command, event)
+          %(    #{command_node(holder.hecks_name, command.hecks_name)} -->|emits| #{event_node(event)})
+        end
+
+        # `on_event` may be aggregate-qualified while `emits` never is, so match on the bare tail.
+        def trigger_edge(policy)
+          bare_event = policy.on_event.to_s.split(".").last
+          aggregate_name, command_name = policy.trigger_command.to_s.split(".", 2)
+          label = policy.target_domain ? "triggers in #{policy.target_domain}" : "triggers"
+          %(    #{event_node(bare_event)} -->|#{label}| #{command_node(aggregate_name, command_name)})
+        end
+
+        # Qualified by aggregate since two aggregates may share a command name.
+        #
+        # @param aggregate_name [String] the aggregate or entity that holds the command
+        # @param command_name [String] the command
+        # @return [String] its Mermaid node
+        def command_node(aggregate_name, command_name)
+          %(cmd_#{aggregate_name}_#{command_name}(["#{aggregate_name}.#{command_name}"]))
+        end
+
+        # @param event_name [String] the event
+        # @return [String] its Mermaid node
+        def event_node(event_name) = %(evt_#{event_name}{{"#{event_name}"}})
+
+        # @param bluebook [Bluebook::Chapter] the assembled chapter
+        # @param holder [Object] an aggregate or entity with commands or queries
+        # @return [String] what the holder does, writes and answers
+        def surface_diagram(bluebook, holder)
+          lines = capability_edges(holder) + mutation_edges(holder) + asks_edges(holder)
+          subject = "#{holder.hecks_name}'s own declared commands (and what each writes) and queries"
+          Diagrams.flowchart(bluebook, subject, lines)
+        end
+
+        def capability_edges(holder)
+          holder.commands.map do |command|
+            "    #{holder.hecks_name}[(#{holder.hecks_name})] -->|does| #{command_node(holder.hecks_name, command.hecks_name)}"
+          end
+        end
+
+        def mutation_edges(holder)
+          holder.commands.flat_map do |command|
+            command.mutations.map { |mutation| mutation_edge(holder, command, mutation) }
+          end
+        end
+
+        def asks_edges(holder)
+          holder.queries.map do |query|
+            "    #{holder.hecks_name}[(#{holder.hecks_name})] -.->|asks| #{query_node(holder.hecks_name, query.hecks_name)}"
+          end
+        end
+
+        def query_node(aggregate_name, query_name)
+          %(qry_#{aggregate_name}_#{query_name}{"#{aggregate_name}.#{query_name}"})
+        end
+
+        def mutation_edge(holder, command, mutation)
+          shape = mutation.to_h
+          label = mutation_label(shape)
+          target = attribute_node(holder.hecks_name, shape[:target])
+          %(    #{command_node(holder.hecks_name, command.hecks_name)} -->|"#{label}"| #{target})
+        end
+
+        def mutation_label(shape)
+          verb = "#{shape[:op]}s"
+          # Keyed on `fields:` being present, not on a list of multi-binding ops.
+          detail = shape[:fields] ? shape[:fields].keys.join(", ") : mutation_source_detail(shape[:source])
+          "#{verb}: #{detail}"
+        end
+
+        # A literal can contain `"`, which breaks the label's `|"..."|` quoting; swap it for `'`.
+        def mutation_source_detail(source)
+          case source[:kind]
+          when "literal"  then "'#{source[:value].to_s.tr('"', "'")}'"
+          when "argument" then source[:name]
+          else
+            source[:kind]
+          end
+        end
+
+        def attribute_node(holder_name, attribute_name)
+          %(attr_#{holder_name}_#{attribute_name}[#{attribute_name}])
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projections/diagrams/statecharts.rb

@@ -0,0 +1,59 @@
+module Hecks
+  module Projections
+    module Diagrams
+      # The state diagrams: an aggregate's declared lifecycle and a process manager's saga.
+      module Statecharts
+        module_function
+
+        # @param bluebook [Bluebook::Chapter] the assembled chapter
+        # @param holder [Object] an aggregate or entity with a lifecycle
+        # @return [String] the lifecycle's states and the commands that move between them
+        def lifecycle_diagram(bluebook, holder)
+          lifecycle = holder.lifecycle
+          edges = lifecycle.transitions.flat_map do |command_name, transition|
+            Array(transition.from).map { |from_state| "    #{from_state} --> #{transition.target}: #{command_name}" }
+          end
+
+          subject = "#{holder.hecks_name}'s own declared lifecycle (field: #{lifecycle.field})"
+          <<~MERMAID
+            #{Diagrams.header(bluebook.name, subject)}stateDiagram-v2
+                [*] --> #{lifecycle.default}
+            #{edges.join("\n")}
+          MERMAID
+        end
+
+        # @param bluebook [Bluebook::Chapter] the assembled chapter
+        # @param saga [Object] a process manager
+        # @return [String] the saga's states and what each transition dispatches
+        def saga_diagram(bluebook, saga)
+          edges = saga.handlers.map { |handler| saga_edge(handler, saga) }
+
+          subject = "#{saga.hecks_name}'s own declared states and what each transition dispatches " \
+                    "(starts on #{saga.starts_on}, ends on #{saga.ends_on})"
+          <<~MERMAID
+            #{Diagrams.header(bluebook.name, subject)}stateDiagram-v2
+                [*] --> #{saga.states.first}
+            #{edges.join("\n")}
+          MERMAID
+        end
+
+        # `saga` is needed only for the `REFUSED` edge, whose compensating dispatches are
+        # derived from the forward dispatches' `compensates`, not written on the handler.
+        def saga_edge(handler, saga)
+          label = handler.event_type
+          # Derived compensations first, matching the order `SagaInterpreter#unwind` runs them.
+          dispatched = handler.event_type == Bluebook::ProcessManager::REFUSED ? derived_compensations(saga) : []
+          dispatched += handler.dispatches.map(&:command_name)
+          label += " / dispatches #{dispatched.join(", ")}" unless dispatched.empty?
+
+          "    #{handler.from_state} --> #{handler.to_state}: #{label}"
+        end
+
+        # Listed in declaration order; at refusal the runtime fires them newest first.
+        def derived_compensations(saga)
+          saga.handlers.flat_map { |handler| handler.dispatches.filter_map { |dispatch| dispatch.compensates&.command_name } }
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projections/diagrams/structure.rb

@@ -0,0 +1,114 @@
+module Hecks
+  module Projections
+    module Diagrams
+      # The diagrams of what a domain holds and connects: references between aggregates, who
+      # issues each command, what each port exposes and what each read model is assembled from.
+      module Structure
+        module_function
+
+        # `has_many`/`has_one` read from the owning side; `belongs_to`/`reference_to` read
+        # from the target's side, since a bare reference does not promise uniqueness.
+        #
+        # @param bluebook [Bluebook::Chapter] the assembled chapter
+        # @return [String, nil] the entity-relationship diagram, or nil without references
+        def relationship_diagram(bluebook)
+          edges = Diagrams.holders(bluebook).flat_map do |holder|
+            holder.attributes.select(&:reference?).map { |attribute| relationship_edge(holder, attribute) }
+          end
+          return nil if edges.empty?
+
+          subject = "#{bluebook.name}'s own declared reference_to/belongs_to/has_many/has_one attributes"
+          "#{Diagrams.header(bluebook.name, subject)}erDiagram\n#{edges.join("\n")}\n"
+        end
+
+        def relationship_edge(holder, attribute)
+          target = attribute.type.target_name
+          case attribute.relationship
+          when "has_many"
+            %(    #{holder.hecks_name} ||--o{ #{target} : "#{attribute.name}")
+          when "has_one"
+            %(    #{holder.hecks_name} ||--#{attribute.optional? ? "o|" : "||"} #{target} : "#{attribute.name}")
+          when "belongs_to", "reference_to"
+            %(    #{target} #{attribute.optional? ? "|o" : "||"}--o{ #{holder.hecks_name} : "#{attribute.name}")
+          end
+        end
+
+        # @param bluebook [Bluebook::Chapter] the assembled chapter
+        # @return [String, nil] who issues which command, or nil when no command names a role
+        def roles_diagram(bluebook)
+          lines = Diagrams.holders(bluebook).flat_map do |holder|
+            holder.commands.select(&:role).map { |command| role_edge(holder, command) }
+          end
+          return nil if lines.empty?
+
+          Diagrams.flowchart(bluebook, "#{bluebook.name}'s own declared command roles", lines)
+        end
+
+        def role_edge(holder, command)
+          %(    #{role_node(command.role)} -->|issues| #{Dispatch.command_node(holder.hecks_name, command.hecks_name)})
+        end
+
+        def role_node(role_name) = %(#{role_id(role_name)}((#{role_name})))
+
+        # A role is free text ("Back office"), so only its id is sanitized; the label keeps
+        # the text.
+        def role_id(role_name) = "role_#{role_name.to_s.gsub(/[^A-Za-z0-9]+/, "_")}"
+
+        # Walks `bluebook.aggregates`, not `holders`: an entity has no `ports` method.
+        #
+        # @param bluebook [Bluebook::Chapter] the assembled chapter
+        # @return [String, nil] the port operations, or nil when no aggregate has a port
+        def ports_diagram(bluebook)
+          lines = bluebook.aggregates.flat_map do |holder|
+            holder.ports.flat_map { |port| port.operations.map { |operation| port_edges(holder, port, operation) } }
+          end.flatten
+          return nil if lines.empty?
+
+          subject = "#{bluebook.name}'s own declared port operations (which aggregate exposes each, its to:, and its emits)"
+          Diagrams.flowchart(bluebook, subject, lines)
+        end
+
+        def port_edges(holder, port, operation)
+          op = port_operation_node(holder.hecks_name, port.name, operation.hecks_name)
+          edges = ["    #{holder.hecks_name}[(#{holder.hecks_name})] -.->|exposes| #{op}"]
+          edges << "    #{op} -->|to: #{operation.to}| #{operation.to}[(#{operation.to})]" if operation.to
+          operation.emits.each { |event| edges << "    #{op} -->|emits| #{Dispatch.event_node(event)}" }
+          edges
+        end
+
+        def port_operation_node(aggregate_name, port_name, operation_name)
+          id = "op_#{aggregate_name}_#{port_name}_#{operation_name}"
+          %(#{id}[/"#{port_name}.#{operation_name}"/])
+        end
+
+        # @param bluebook [Bluebook::Chapter] the assembled chapter
+        # @return [String, nil] each read model and its source aggregates, or nil without any
+        def read_model_diagram(bluebook)
+          lines = bluebook.read_models.flat_map { |read_model| read_model_edges(read_model) }
+          return nil if lines.empty?
+
+          subject = "#{bluebook.name}'s own declared read_models and the aggregates each is assembled from"
+          Diagrams.flowchart(bluebook, subject, lines)
+        end
+
+        def read_model_edges(read_model)
+          shape = read_model.to_h
+          node = %(rm_#{shape[:name]}[["#{read_model_label(shape)}"]])
+          Array(shape[:aggregate_heads]).map do |head|
+            # Quoted because an unquoted `[` in an edge label (`accounts[]`) breaks Mermaid's
+            # parser.
+            label = head[:many] ? "#{head[:as]}[]" : head[:as]
+            %(    #{head[:aggregate]}[(#{head[:aggregate]})] -->|"#{label}"| #{node})
+          end
+        end
+
+        def read_model_label(shape)
+          return "#{shape[:name]} (count)" if shape[:count]
+          return "#{shape[:name]} (median: #{shape[:median_field]})" if shape[:median_field]
+
+          shape[:name]
+        end
+      end
+    end
+  end
+end