hecks 3.5.0 → 3.6.0

data/lib/hecks/tools/tenant_provisioning.rb

@@ -56,11 +56,9 @@ module Hecks
       def parse(argv)
         options = { adapter: "PostgresEra" }
         OptionParser.new do |parser|
-          parser.on("--domain=NAME")   { |v| options[:domain] = v }
-          parser.on("--realm=NAME")    { |v| options[:realm] = v }
-          parser.on("--schema=NAME")   { |v| options[:schema] = v }
-          parser.on("--database=NAME") { |v| options[:database] = v }
-          parser.on("--adapter=NAME")  { |v| options[:adapter] = v }
+          %i[domain realm schema database adapter].each do |flag|
+            parser.on("--#{flag}=NAME") { |v| options[flag] = v }
+          end
         end.parse!(argv)
 
         %i[domain realm schema database].each do |flag|
@@ -83,32 +81,38 @@ module Hecks
       def provision(slug, options, domain_directory)
         lib_hecks  = File.expand_path("..", __dir__)
         dispatcher = Hecks.boot_files(CHAPTER_FILES.map { |file| File.join(lib_hecks, file) }, install_doors: false)
-        facts = {
-          slug:      { value: slug },
-          domain:    { value: options[:domain] },
-          realm:     { value: options[:realm] },
-          schema:    { value: options[:schema] },
-          database:  { value: options[:database] },
-          adapter:   { value: options[:adapter] },
-          directory: { value: domain_directory }
-        }
-
-        begin
-          dispatcher.dry_run?("Deploy::Tenant.Provision", **facts)
-          dispatcher.dispatch("Deploy::Tenant.Provision", to: slug, with: facts)
-        rescue *Hecks::Runtime::DOMAIN_REFUSALS => e
-          abort "tenant #{slug.inspect} is invalid: #{e.message}"
-        end
+        provision_tenant(dispatcher, slug, tenant_facts(slug, options, domain_directory))
+        refuse_if_refused(dispatcher, slug)
+
+        puts "wrote #{File.join(domain_directory, "environments", "#{slug}.world")}"
+        dispatcher
+      end
+
+      # @return [Hash{Symbol => Hash}] each fact of the `Tenant.Provision` command, as a value
+      def tenant_facts(slug, options, domain_directory)
+        values = { slug: slug }.merge(options.slice(:domain, :realm, :schema, :database, :adapter))
+                               .merge(directory: domain_directory)
+        values.transform_values { |value| { value: value } }
+      end
+
+      # Dry-runs `Tenant.Provision` to validate the shape, then dispatches it.
+      #
+      # @raise [SystemExit] when the declared shape is refused
+      def provision_tenant(dispatcher, slug, facts)
+        dispatcher.dry_run?("Deploy::Tenant.Provision", **facts)
+        dispatcher.dispatch("Deploy::Tenant.Provision", to: slug, with: facts)
+      rescue *Hecks::Runtime::DOMAIN_REFUSALS => e
+        abort "tenant #{slug.inspect} is invalid: #{e.message}"
+      end
 
+      # @raise [SystemExit] when the port refused the provisioning
+      def refuse_if_refused(dispatcher, slug)
         tenant = dispatcher.registry.bluebook("Deploy").aggregate("Tenant")
         record = dispatcher.registry.repository("Deploy", tenant).find(slug)
         refused = record&.state&.dig(:refusal)
         refused = refused[:value] if refused.is_a?(Hash)
         record&.state&.dig(:status) == "refused" and
           abort "provisioning #{slug.inspect} was refused: #{refused}"
-
-        puts "wrote #{File.join(domain_directory, 'environments', "#{slug}.world")}"
-        dispatcher
       end
 
       # Boots the domain under the tenant's overlay (which also provisions the schema, since
@@ -125,18 +129,28 @@ module Hecks
         target = Hecks.boot(domain_directory, environment: slug, install_doors: false)
         puts "booted #{options[:domain]} for tenant #{slug.inspect} under realm #{options[:realm].inspect}"
 
-        target.registry.bluebooks.each_key do |name|
-          Hecks::Runtime::TenantCheck.refuse_unless_tenant_capable!(target.registry, name)
-        end
+        refuse_unless_tenant_capable(target.registry)
 
         # A refused reaction never raises, so the record itself is the proof.
-        tenant = dispatcher.registry.repository("Tenancy", dispatcher.registry.bluebook("Tenancy").aggregate("Tenant"))
-                           .find(slug)
-        tenant or abort "provisioning succeeded but #{slug.inspect} was never registered in Tenancy — " \
-                        "check registry.reaction_log for a silently refused Register"
+        tenancy_record(dispatcher, slug) or abort "provisioning succeeded but #{slug.inspect} was never " \
+                                                  "registered in Tenancy — " \
+                                                  "check registry.reaction_log for a silently refused Register"
 
         puts "#{options[:domain]} is tenant_capable? for #{slug.inspect} — registered under realm #{options[:realm].inspect}"
       end
+
+      # @raise [SystemExit] when a bluebook of the registry is not tenant capable
+      def refuse_unless_tenant_capable(registry)
+        registry.bluebooks.each_key do |name|
+          Hecks::Runtime::TenantCheck.refuse_unless_tenant_capable!(registry, name)
+        end
+      end
+
+      # @return [Object, nil] the tenant's record in Tenancy
+      def tenancy_record(dispatcher, slug)
+        dispatcher.registry.repository("Tenancy", dispatcher.registry.bluebook("Tenancy").aggregate("Tenant"))
+                  .find(slug)
+      end
     end
   end
 end

data/lib/hecks/tools/tools_doc.rb

@@ -78,13 +78,13 @@ module Hecks
       def table(section, context)
         lines = rows.select { |row| row["section"] == section }.group_by { |row| row["script"] }.map do |script, group|
           cell = group.map { |row| cell(row, context) }.join("; ")
-          "| #{cell} | #{script == '(new)' ? '(new: no `bin/` script)' : "`bin/#{script}`"} |"
+          "| #{cell} | #{script == "(new)" ? "(new: no `bin/` script)" : "`bin/#{script}`"} |"
         end
         [HEADER, *lines].join("\n")
       end
 
       # One form as the table shows it: in backticks, with a `|` escaped.
-      def cell(row, context) = "`#{form(row, context).gsub('|', '\|')}`"
+      def cell(row, context) = "`#{form(row, context).gsub("|", '\|')}`"
 
       # @param row [Hash{String => String}] a `RetiredScript` row
       # @param context [Context] the booted chapters
@@ -96,7 +96,7 @@ module Hecks
         passes = row["passes"].to_s
         text = [*words, *argument_words(spec, skip: passes.empty? ? [] : %w[arguments])].join(" ")
         text += %( [arguments="#{passes}"]) unless passes.empty?
-        text += " (#{row['note']})" unless row["note"].to_s.empty?
+        text += " (#{row["note"]})" unless row["note"].to_s.empty?
         "hecks #{text}"
       end
 
@@ -106,17 +106,34 @@ module Hecks
       # @param skip [Array<String>] arguments not to spell, because the row documents them itself
       # @return [Array<String>] each argument as the launcher spells it
       def argument_words(spec, skip: [])
-        named = by_attribute(spec[:arguments].reject do |argument|
-          argument[:minted] || skip.include?(argument[:path].split(".").first)
-        end)
-        # The launcher reads a bare word as the first argument, when that is not a flag.
-        bare = named.first unless named.empty? || named.first[:type] == "Boolean"
+        named = spelled_arguments(spec, skip)
+        bare = bare_argument(named)
         flags, plain = (named - [bare].compact).partition { |argument| argument[:type] == "Boolean" }
-        [*(bracket(bare, "<#{bare[:path]}>") if bare),
+        [*bare_word(bare),
          *plain.map { |argument| bracket(argument, "#{argument[:path]}=") },
          *flags.map { |argument| flag_word(argument) }]
       end
 
+      # @return [Array<String>] the bare argument as the launcher spells it, none without one
+      def bare_word(bare) = bare ? [bracket(bare, "<#{bare[:path]}>")] : []
+
+      # @return [Array<Hash>] the arguments the launcher spells, per attribute
+      def spelled_arguments(spec, skip)
+        by_attribute(spec[:arguments].reject { |argument| skipped?(argument, skip) })
+      end
+
+      # @return [Boolean] whether the launcher mints the argument itself, or the row documents it
+      def skipped?(argument, skip)
+        argument[:minted] || skip.include?(argument[:path].split(".").first)
+      end
+
+      # The launcher reads a bare word as the first argument, when that is not a flag.
+      #
+      # @return [Hash, nil] the argument spelled bare
+      def bare_argument(named)
+        named.first unless named.empty? || named.first[:type] == "Boolean"
+      end
+
       # A one-field value object's `x.value` leaf is spelled as the attribute, `x`; a value object
       # with more fields keeps one leaf each.
       #
@@ -135,7 +152,7 @@ module Hecks
 
       # `--confirm` is what makes a verb act, so it stands bare; any other flag is optional.
       def flag_word(argument)
-        word = "--#{argument[:path].tr('_', '-')}"
+        word = "--#{argument[:path].tr("_", "-")}"
         argument[:path] == "confirm" ? word : "[#{word}]"
       end
 
@@ -146,7 +163,7 @@ module Hecks
         return 0 if text == fresh
 
         stale = SECTIONS.reject { |section| section_text(text, section) == section_text(fresh, section) }
-        warn "tools_doc: #{DOCUMENT} differs from the RetiredScript rows in: #{stale.join(', ')} " \
+        warn "tools_doc: #{DOCUMENT} differs from the RetiredScript rows in: #{stale.join(", ")} " \
              "(run hecks regeneration_run.project_tools_doc --confirm)"
         1
       end
@@ -170,16 +187,18 @@ module Hecks
         # @raise [SystemExit] when the row names no command or query
         def spec_for(row)
           chapter = %w[Custodian Codebase].include?(row["section"]) ? "Hecks" : row["section"]
-          cli = projection(chapter)
-          name = "#{Naming.snake(row['aggregate'])}.#{row['verb']}"
-          command = cli[:commands][cli[:names][:command][name]]
-          question = cli[:questions][cli[:names][:question][name]]
-          spec = command || question or abort "tools_doc: #{chapter} has no command or query #{name}"
+          name = "#{Naming.snake(row["aggregate"])}.#{row["verb"]}"
+          spec = find_spec(projection(chapter), name) or abort "tools_doc: #{chapter} has no command or query #{name}"
           [spec, words(chapter, name, row)]
         end
 
         private
 
+        # @return [Hash, nil] the projected command, or else the query, of that name
+        def find_spec(cli, name)
+          cli[:commands][cli[:names][:command][name]] || cli[:questions][cli[:names][:question][name]]
+        end
+
         def projection(chapter)
           @projections[chapter] ||= begin
             launcher = Doors::LauncherOptions.settings(@runtime, chapter)
@@ -191,13 +210,17 @@ module Hecks
         # `hecks ir`, `hecks console`, `hecks quality_control sweep.run`, `hecks host.check_era`.
         # The launcher takes a name that is only a query as a query, so no `query` word is needed.
         def words(chapter, name, row)
-          settings = Doors::LauncherOptions.settings(@runtime, chapter) || {}
-          route = (settings[:names] || {}).key(name)
-          route ||= row["verb"] if chapter == "Hecks" && Array(settings[:legacy]).include?(row["verb"])
+          route = route_for(Doors::LauncherOptions.settings(@runtime, chapter) || {}, chapter, name, row)
           return [route] if route
 
           [*(Naming.snake(chapter) unless chapter == "Hecks"), name]
         end
+
+        # @return [String, nil] the one word the launcher routes the name by, when it has one
+        def route_for(settings, chapter, name, row)
+          route = (settings[:names] || {}).key(name)
+          route || (row["verb"] if chapter == "Hecks" && Array(settings[:legacy]).include?(row["verb"]))
+        end
       end
     end
   end

data/lib/hecks/tools/translation_audit/domain_loading.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require_relative "../../tools"
+
+module Hecks
+  module Tools
+    module TranslationAudit
+      # Loads the domain to audit and opens its lineage journal.
+      module DomainLoading
+        # @param domain_path [String] the domain directory
+        # @return [Array] the registry, its bluebook and the bluebook directory
+        def load_domain(domain_path)
+          loading = Hecks::Ports::Loading.bootstrap
+          directory = loading.bluebook_directory(domain_path)
+          registry = Hecks::Runtime::Registry.new(root: File.dirname(directory))
+          load_chapters(registry, loading, directory)
+          bluebook = registry.bluebooks.values.first or abort "no bluebook in #{directory}"
+          [registry, bluebook, directory]
+        end
+
+        # @param registry [Hecks::Runtime::Registry] the loaded registry
+        # @param bluebook [Object] the domain's bluebook
+        # @return [Array] the open connection and its ensured lineage
+        # @raise [SystemExit] when the bound adapter is not lineage-capable
+        def open_lineage(registry, bluebook)
+          first = bluebook.aggregates.first or abort "#{bluebook.name} declares no aggregates"
+          adapter_name = Hecks::Ports::Persistence::BindingPolicy.resolve(registry, bluebook.name, first).adapter
+          refuse_unless_lineage_capable(registry, bluebook, adapter_name)
+
+          db = Hecks::Adapters::PostgresEra.connect_for(bluebook.name, binding_settings(registry, bluebook, adapter_name))
+          lineage = Hecks::Adapters::PostgresEra::Lineage.new(db, bluebook.name)
+          lineage.ensure_base!
+          [db, lineage]
+        end
+
+        private
+
+        def load_chapters(registry, loading, directory)
+          Hecks.with_registry(registry) do
+            loading.load_library
+            loading.load_project(loading.shared_root(nil, directory))
+            # Passes an environment overlay to `load_domain`, as `scaffold_translation` does.
+            loading.load_domain(directory, environment: ENV.fetch("HECKS_PROJECT_ENVIRONMENT", nil))
+          end
+        rescue Hecks::Bluebook::DSL::Malformed => e
+          abort "REFUSED at load: #{e.message}"
+        end
+
+        def refuse_unless_lineage_capable(registry, bluebook, adapter_name)
+          return if lineage_capable?(registry, adapter_name)
+
+          abort "the audit reads a lineage journal; #{bluebook.name} is bound to #{adapter_name}, " \
+                "not PostgresEra"
+        end
+
+        def lineage_capable?(registry, adapter_name)
+          adapter_class = registry.adapter_class(adapter_name)
+          adapter_class.respond_to?(:lineage_capable?) && adapter_class.lineage_capable?
+        rescue StandardError
+          false
+        end
+
+        def binding_settings(registry, bluebook, adapter_name)
+          settings = registry.world(bluebook.name)&.for_binding(Hecks::Ports::Persistence::VERB, adapter_name) || {}
+          # The same `HECKS_SCHEMA` support as `scaffold_translation`.
+          ENV["HECKS_SCHEMA"] ? settings.merge(schema: ENV["HECKS_SCHEMA"]) : settings
+        end
+      end
+    end
+  end
+end

data/lib/hecks/tools/translation_audit/edges.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require_relative "../../tools"
+
+module Hecks
+  module Tools
+    module TranslationAudit
+      # Finds the edge to audit: the translations leading from the journal's latest era to the
+      # bluebook as it stands.
+      module Edges
+        # The era the edge leads to and the chain of translations ending in it, or nil when the
+        # journal stands at era 1 with nothing to audit.
+        #
+        # @return [Array, nil] the era ordinal and the chain
+        def edge_chain(registry, bluebook, lineage)
+          eras = lineage.eras
+          current_shape = Hecks::Runtime::StorageShape.project(bluebook)
+          held_shape = Hecks::Runtime::StorageShape.project(lineage_manager.shadow(eras.last[:held_text]))
+
+          if held_shape == current_shape
+            standing_chain(registry, bluebook, eras)
+          else
+            pending_chain(registry, bluebook, lineage, eras)
+          end
+        end
+
+        private
+
+        def lineage_manager
+          Hecks::Adapters::PostgresEra::LineageManager
+        end
+
+        # The chain when the held journal already matches the bluebook.
+        def standing_chain(registry, bluebook, eras)
+          latest = eras.last
+          era = latest[:ordinal]
+          if era == 1
+            puts "#{bluebook.name} stands at era 1 — no edge to audit."
+            return nil
+          end
+          [era, lineage_manager.edge_chain(registry, bluebook, eras, latest[:label])]
+        end
+
+        # The chain when the bluebook has moved past the held journal: audit the pending edge
+        # before any mint.
+        def pending_chain(registry, bluebook, lineage, eras)
+          lineage_manager.ensure_named!(lineage, eras.last)
+          latest = lineage.eras.last
+          pending = pending_translation(registry, bluebook, latest)
+          chain = begin
+            lineage_manager.edge_chain(registry, bluebook, eras, latest[:label])
+          rescue StandardError
+            []
+          end
+          [latest[:ordinal] + 1, (chain || []) + [{ translation: pending }]]
+        end
+
+        # @return [Object] the translation leading from `latest` to the bluebook
+        # @raise [SystemExit] when none is declared
+        def pending_translation(registry, bluebook, latest)
+          to_label = Hecks::Runtime::StorageShape.mint_hash(bluebook)[0, Hecks::Runtime::StorageShape::LABEL_LENGTH]
+          pending = registry.translations.find do |t|
+            t.domain == bluebook.name && t.from == latest[:label] && t.to == to_label
+          end
+          pending or abort "no translation edge leads #{latest[:label]} to #{to_label} — " \
+                           "run hecks scaffold_translation first"
+        end
+      end
+    end
+  end
+end

data/lib/hecks/tools/translation_audit/verdicts.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../../tools"
+
+module Hecks
+  module Tools
+    module TranslationAudit
+      # Judges each aggregate across the edge, prints the verdicts and concludes the audit.
+      module Verdicts
+        # Prints each aggregate's verdict.
+        #
+        # @return [Boolean] whether any aggregate's audit was refused
+        def report(bluebook, lineage, edge, era, chain)
+          failed = false
+          bluebook.aggregates.each do |aggregate|
+            after, verdict = audit_aggregate(aggregate, lineage, edge, era, chain)
+            print_verdict(bluebook, aggregate, edge, after, verdict)
+            failed ||= !verdict.ok?
+          end
+          failed
+        end
+
+        # @return [Array(Array, Object)] the records after the edge, and the audit's verdict on them
+        def audit_aggregate(aggregate, lineage, edge, era, chain)
+          declared = edge.for_aggregate(aggregate.name)
+          after = translated_after(lineage, aggregate, era, chain)
+          before = records_before(lineage, aggregate, era, chain)
+          [after, Hecks::Translation::Audit.check(aggregate: aggregate, declared: declared, before: before, after: after)]
+        end
+
+        # @return [Integer] the exit status
+        def conclude(db, lineage, edge, failed, approve)
+          if failed
+            db.close
+            puts "AUDIT REFUSED."
+            return 1
+          end
+
+          needs_approval = edge.aggregates.any? { |declared| !declared.computes.empty? || !declared.rekeys.empty? }
+          record_approval(lineage, edge) if needs_approval && approve
+          db.close
+          print_passed(needs_approval, approve)
+          0
+        end
+
+        private
+
+        def translated_after(lineage, aggregate, era, chain)
+          lineage.translated_latest(aggregate, era, chain)
+        rescue PG::Error => e
+          abort "REFUSED: #{e.message.strip}"
+        end
+
+        def records_before(lineage, aggregate, era, chain)
+          return lineage.translated_latest(aggregate, era, chain[0..-2]) if chain.size > 1
+
+          lineage.ancestor_latest(aggregate, era, chain)
+        end
+
+        # @return [void]
+        def print_verdict(bluebook, aggregate, edge, after, verdict)
+          puts "── #{bluebook.name}::#{aggregate.name} (edge #{edge.from} → #{edge.to}, " \
+               "#{after.size} record#{"s" unless after.size == 1})"
+          verdict.violations.each { |violation| puts "   REFUSED: #{violation}" }
+          print_losses(verdict)
+          verdict.samples.each { |sample| print_sample(sample) }
+        end
+
+        def print_losses(verdict)
+          puts "   dropped (declared data loss): #{verdict.dropped.join(", ")}" unless verdict.dropped.empty?
+          return if verdict.unfed.empty?
+
+          puts "   unfed (no rule, no default — add default: if required): #{verdict.unfed.join(", ")}"
+        end
+
+        def print_sample(sample)
+          puts "   ##{sample[:id]}"
+          puts "     before: #{JSON.generate(sample[:before])}" if sample[:before]
+          puts "     after:  #{JSON.generate(sample[:after])}" if sample[:after]
+        end
+
+        # Binds to what was reviewed — this edge and the journal as it stands now — so it must
+        # live in the database, not the repo.
+        def record_approval(lineage, edge)
+          lineage.record_approval!(
+            from: edge.from, to: edge.to,
+            edge_digest: Hecks::Translation::Audit.edge_digest(edge)
+          )
+        end
+
+        def print_passed(needs_approval, approve)
+          if needs_approval && approve
+            puts "AUDIT PASSED — approval recorded in the database, bound to this edge and this journal."
+            puts "A journal that advances before the mint invalidates it; re-run with --approve if that happens."
+          elsif needs_approval
+            puts "AUDIT PASSED — this edge carries a compute or rekey rule, and the samples above are " \
+                 "its ONLY verification."
+            puts "If they show what you intended, run again with --approve; the mint refuses until you do."
+          else
+            puts "AUDIT PASSED — review the samples above; intent is yours to approve."
+          end
+        end
+      end
+    end
+  end
+end