hecks 3.5.0 → 3.7.0

data/lib/hecks/hecks/adapters/codebase/test_suite.rb

@@ -51,16 +51,35 @@ module Hecks
           case operation
           when "refresh_runtime_baseline" then refresh(args, tree)
           when "run_spec_example" then TestRunner.new(tree).run(file: args[:file], example: args[:example])
-          when "stress_concurrency"
-            answer { command("stress_concurrency_specs").call(stress_flags(args), root: tree.root) }
-          when "regenerate_legacy_fixtures"
-            SqliteFixture.new(tree, shell: shell).regenerate(confirm: args[:confirm] == true)
-          when "seed_semantics_corpus"
-            answer { command("seed_semantics_corpus").call(root: tree.root, env: seed_env(args)) }
+          when "stress_concurrency" then stress(args, tree)
+          when "regenerate_legacy_fixtures" then regenerate_fixtures(args, tree, shell)
+          when "seed_semantics_corpus" then seed(args, tree)
           else write_list(args, tree)
           end
         end
 
+        # @param args [Hash] `runs`, `parallel` and `seed_start`
+        # @param tree [Tree] the checkout
+        # @return [String] what the stress run printed
+        def stress(args, tree)
+          answer { command("stress_concurrency_specs").call(stress_flags(args), root: tree.root) }
+        end
+
+        # @param args [Hash] `confirm`
+        # @param tree [Tree] the checkout
+        # @param shell [#capture, nil] starts the fixtures' child process
+        # @return [String] what was regenerated, or (unconfirmed) what would be
+        def regenerate_fixtures(args, tree, shell)
+          SqliteFixture.new(tree, shell: shell).regenerate(confirm: args[:confirm] == true)
+        end
+
+        # @param args [Hash] `fixture`, perhaps absent
+        # @param tree [Tree] the checkout
+        # @return [String] what the seeding printed
+        def seed(args, tree)
+          answer { command("seed_semantics_corpus").call(root: tree.root, env: seed_env(args)) }
+        end
+
         # A pure read: a listing, or the recorded pattern cases.
         #
         # @param operation [String] `shard_specs`, `list_io_parallel_specs`, `record_pattern_cases`
@@ -130,8 +149,8 @@ module Hecks
           source = args[:from_run] ? ["--from-run", args[:from_run]] : [*args[:workers]&.to_s]
           return answer { command("refresh_rspec_runtime_baseline").call(source, root: tree.root) } if args[:confirm] == true
 
-          "dry run, would #{args[:from_run] ? "read CI run #{args[:from_run]}'s timings" : 'time a local run'} " \
-            "and rewrite #{BASELINES.join(', ')} (add --confirm)"
+          "dry run, would #{args[:from_run] ? "read CI run #{args[:from_run]}'s timings" : "time a local run"} " \
+            "and rewrite #{BASELINES.join(", ")} (add --confirm)"
         end
 
         # @param args [Hash] `runs`, `parallel` and `seed_start`

data/lib/hecks/hecks/adapters/console_capture.rb

@@ -44,23 +44,27 @@ module Hecks
       #
       # @yield the entry point to run
       # @return [Outcome] the text printed and the exit status
-      def capture
-        synchronize do
-          saved  = [$stdout, $stderr]
-          buffer = StringIO.new
-          begin
-            $stdout = $stderr = buffer
-            status = begin
-              yield
-              0
-            rescue SystemExit => e
-              e.status
-            end
-            Outcome.new(buffer.string, status)
-          ensure
-            $stdout, $stderr = saved
-          end
-        end
+      def capture(&)
+        synchronize { redirected(&) }
+      end
+
+      # Runs the block with both streams pointed at one buffer, putting them back afterwards.
+      def redirected(&)
+        saved  = [$stdout, $stderr]
+        buffer = StringIO.new
+        $stdout = $stderr = buffer
+        status = exit_status(&)
+        Outcome.new(buffer.string, status)
+      ensure
+        $stdout, $stderr = saved
+      end
+
+      # The status the block ends with: 0, or the one an `exit` inside it carries.
+      def exit_status
+        yield
+        0
+      rescue SystemExit => e
+        e.status
       end
 
       # Runs the block captured and answers its text, or refuses with it.

data/lib/hecks/hecks/adapters/cost_explorer.rb

@@ -78,16 +78,21 @@ module Hecks
 
       # @return [Float] the mean daily total, scaled to an average month
       def monthly_rate(days)
-        mean = days.values.sum { |services| services.values.sum } / days.size
-        mean * DAYS_IN_MONTH
+        mean_daily(days) * DAYS_IN_MONTH
       end
 
+      # @return [Float] the mean daily total across every service
+      def mean_daily(days) = days.values.sum { |services| services.values.sum } / days.size
+
       def report_line(first, last, days, budget)
-        mean = days.values.sum { |services| services.values.sum } / days.size
+        "#{first}..#{last - 1} (#{days.size} days): $#{format("%.2f", mean_daily(days))}/day, " \
+          "$#{format("%.2f", monthly_rate(days))}/month against $#{budget}; biggest: #{biggest_services(days)}"
+      end
+
+      # @return [String] the costliest services, each with its mean daily cost
+      def biggest_services(days)
         biggest = totals_by_service(days).max_by(TOP_SERVICES) { |_name, dollars| dollars }
-        named = biggest.map { |name, dollars| "#{name} $#{format('%.2f', dollars / days.size)}/day" }.join(", ")
-        "#{first}..#{last - 1} (#{days.size} days): $#{format('%.2f', mean)}/day, " \
-          "$#{format('%.2f', monthly_rate(days))}/month against $#{budget}; biggest: #{named}"
+        biggest.map { |name, dollars| "#{name} $#{format("%.2f", dollars / days.size)}/day" }.join(", ")
       end
 
       def totals_by_service(days)

data/lib/hecks/hecks/adapters/deploy_plans.rb

@@ -14,7 +14,7 @@ module Hecks
       # @param branch [String, nil] the branch named, or nil for the checked-out one
       # @return [String]
       def preview(text, action, branch)
-        stack = "#{variable(text, 'PREFIX') || '<prefix>'}-<name derived from #{branch || 'the checked-out branch'}>"
+        stack = "#{variable(text, "PREFIX") || "<prefix>"}-<name derived from #{branch || "the checked-out branch"}>"
         region = variable(text, "REGION")
         where = region ? " in #{region}" : ""
         case action
@@ -36,9 +36,9 @@ module Hecks
         stack = text[/out\s+(\S+)\s+InstanceId/, 1]
         project = text[/compose -p (\w+)/, 1] || companion
         directory = text[%r{mkdir -p (/\S+)}, 1]
-        place = directory ? " in #{directory}" : String.new
+        place = directory ? " in #{directory}" : +""
         "roll #{companion} (Compose project #{project}#{place}) from task definition " \
-          "#{taskdef} onto the box of stack #{stack || '<box stack>'} over SSM, beside the app's project, " \
+          "#{taskdef} onto the box of stack #{stack || "<box stack>"} over SSM, beside the app's project, " \
           "then check it on the box"
       end
 

data/lib/hecks/hecks/adapters/deploy_toolchain/answers.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require_relative "statuses"
+
+module Hecks
+  module Adapters
+    class DeployToolchain
+      # The answers the asks hand on to the policies that follow them: plans, confirmations, what a
+      # roll or a data copy carries, and the bluebook comparison.
+      module Answers
+        include Statuses
+
+        private
+
+        # Runs the confirmed restore and answers what it printed.
+        def restore(held)
+          script = Scripts::Script.new(RESTORE_SCRIPT, "restore", RESTORE_STATUS, copy_args(held))
+          copy_answer(held, run_script(script, held, copy_env(held))[:report][:value], planned: false)
+        end
+
+        # What a preview verb that writes would do, read from the script, or nil for one that reads.
+        # A dry run answers the plan; otherwise the write needs `confirm`.
+        #
+        # @return [Hash, nil] the dry run's answer, when it is one
+        def gate_preview(held, action)
+          return unless PREVIEW_WRITES.include?(action)
+
+          script = script_for(PREVIEW_SCRIPT, plain(held[:project]), plain(held[:script]))
+          plan = DeployPlans.preview(File.read(script), action, plain(held[:branch]))
+          return planned_answer("#{action}: #{plan}") if plain(held[:dry_run]) == true
+
+          require_confirm(held, "#{action} a preview", plan)
+          nil
+        end
+
+        # What rolling the companion would do, read from its script.
+        def companion_plan(held, name, companion)
+          script = script_for(name, plain(held[:project]), plain(held[:script]))
+          DeployPlans.companion(File.read(script), companion, plain(held[:taskdef]))
+        end
+
+        # A dry run's answer: the plan, and nothing run.
+        def planned_answer(plan)
+          { outcome: { value: "planned" }, report: { value: "#{plan}\ndry run: nothing was run" }, planned: { value: true } }
+        end
+
+        def require_confirm(held, what, plan)
+          return if plain(held[:confirm]) == true
+
+          raise ConsoleCapture::Failure,
+                "refusing to #{what}: #{plan}\npass confirm=true to run it (dry_run=true prints this plan)"
+        end
+
+        def diff_files(old, new)
+          report = BluebookReport.new(File.read(File.expand_path(old)), File.read(File.expand_path(new)))
+          diff_answer(report.changed? ? "changed" : "unchanged", report.text)
+        rescue SystemCallError, JSON::ParserError, TypeError, KeyError => e
+          diff_answer("unavailable", "bluebooks: could not compare #{old} and #{new} (#{e.message.lines.first.strip})")
+        end
+
+        # The script reads the registry and the local image; its report says what it found.
+        def diff_script(held)
+          text = run_script(Scripts::Script.new(DIFF_SCRIPT, "bluebook diff", {}), held, {}).dig(:report, :value)
+          return diff_answer("unavailable", text) if text.match?(DIFF_UNAVAILABLE)
+
+          diff_answer(text.include?("no bluebook changes.") ? "unchanged" : "changed", text)
+        rescue ConsoleCapture::Failure => e
+          diff_answer("unavailable", "bluebooks: #{e.message.lines.first.strip}; nothing to compare.")
+        end
+
+        def diff_answer(outcome, text) = { outcome: { value: outcome }, report: { value: text } }
+
+        # What a data copy's answer hands on to the policies that follow it.
+        def copy_answer(held, report, planned:)
+          carried = %i[project bastion source source_secret target target_secret source_db target_db]
+                    .to_h { |key| [key, { value: plain(held[key]).to_s }] }
+          verify = !planned && plain(held[:skip_verify]) != true
+          carried.merge(report: { value: report }, planned: { value: planned }, run_verify: { value: verify })
+        end
+
+        # A database name the record gave, or nil when it left the script's default.
+        def database(argument) = plain(argument).to_s.empty? ? nil : plain(argument)
+
+        def copy_args(held) = %i[bastion source source_secret target target_secret].map { |key| plain(held[key]) }
+
+        def copy_env(held)
+          { "FORCE" => flag(held[:force]), "SRC_DB" => database(held[:source_db]), "DST_DB" => database(held[:target_db]),
+            "VERIFY_BY_COMMAND" => "1" }.compact
+        end
+
+        # What the script would overwrite, read from the script itself (its schemas and databases).
+        # Its schemas are the default of the `SCHEMAS=${SCHEMAS:-"..."}` line (overridable).
+        def copy_plan(script, held)
+          text = File.read(script)
+          schemas = text[/^SCHEMAS=(?:\$\{SCHEMAS:-)?"([^"]*)"/, 1].to_s.split.join(", ")
+          source_db, target_db = copy_databases(text, held)
+          drop = plain(held[:force]) == true ? "; force=true drops each target schema first" : ""
+          "copy schemas #{schemas} from database #{source_db} on #{plain(held[:source])} into database " \
+            "#{target_db} on #{plain(held[:target])} through bastion #{plain(held[:bastion])}, " \
+            "OVERWRITING those schemas there#{drop}"
+        end
+
+        # The source and target databases: the record's, else the script's defaults.
+        def copy_databases(text, held)
+          databases = text.match(/^SRC_DB=\$\{SRC_DB:-([^}]*)\}; DST_DB=\$\{DST_DB:-([^}]*)\}/)
+          [database(held[:source_db]) || databases&.[](1), database(held[:target_db]) || databases&.[](2)]
+        end
+
+        # What a roll's answer hands on to the policies that follow it: the project to find the
+        # smoke in, whether to request the smoke (not when the record opted out or the project has
+        # no smoke script, either of which is noted on the record), and which roll asked.
+        def carried(held, kind)
+          skipped = plain(held[:skip_smoke]) == true
+          script = smoke_script?(plain(held[:project]))
+          note = "smoke skipped: skip_smoke=true" if skipped
+          note ||= "smoke skipped: no smoke script" unless script
+          { project: { value: plain(held[:project]) }, skip_smoke: { value: skipped },
+            run_smoke: { value: note.nil? }, smoke: wrapped(note), kind: { value: kind } }
+        end
+
+        # Whether the project has a generated smoke script the smoke could run.
+        def smoke_script?(project)
+          script_for(SMOKE_SCRIPT, project, nil)
+          true
+        rescue ConsoleCapture::Failure
+          false
+        end
+
+        def wrapped(text) = text.to_s.empty? ? nil : { value: text }
+
+        # What `deploy-box.sh` takes: a task definition, or `name=tag` words.
+        def box_args(held) = [plain(held[:taskdef]), *plain(held[:tags]).to_s.split].compact
+
+        # The taskdef and tag a service roll's last line names.
+        def rolled(text)
+          match = text.match(/^==> rolled taskdef=(\S*) tag=(\S+)$/)
+          { taskdef: wrapped(match&.[](1)), tag: wrapped(match&.[](2)) }
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/deploy_toolchain/scripts.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require_relative "statuses"
+
+module Hecks
+  module Adapters
+    class DeployToolchain
+      # Runs the scripts an ask names: the `Hecks::Tools` tools in this process, and the generated
+      # scripts of a project in a child.
+      module Scripts
+        include Statuses
+
+        # A generated script to run: its file name, how a refusal names it, what its statuses mean,
+        # its arguments, and the statuses that are an answer rather than a refusal.
+        Script = Struct.new(:name, :label, :statuses, :args, :answering) do
+          def initialize(name, label, statuses, args = [], answering = []) = super
+        end
+
+        private
+
+        # Runs one generated script, found for the record's project, from its own directory. Answers
+        # what it printed, or refuses with its status, that status's meaning and its output.
+        def run_script(script, held, env)
+          path = script_for(script.name, plain(held[:project]), plain(held[:script]))
+          result = Shell.new.capture("bash", path, *script.args, env: env, chdir: File.dirname(path))
+          report = printed(result)
+          return { report: { value: report } } if result.ok?
+
+          answer_or_refuse(script, result.status.exitstatus, report)
+        end
+
+        # What the script printed to either stream, trimmed.
+        def printed(result) = [result.out, result.err].map(&:strip).reject(&:empty?).join("\n")
+
+        def answer_or_refuse(script, code, report)
+          return { report: { value: report }, status: code } if script.answering.include?(code)
+
+          raise ConsoleCapture::Failure, "#{script.label} ended #{code} (#{script.statuses.fetch(code, "unexpected")})\n#{report}"
+        end
+
+        # The script a project runs: the override, else the named one in the project itself, else
+        # the only one beneath it (not under `node_modules`, `vendor` or `.git`).
+        def script_for(name, project, override)
+          return existing_script(override) if override
+
+          root = File.expand_path(project.to_s)
+          beside = File.join(root, name)
+          return beside if File.file?(beside)
+
+          found = Dir.glob(File.join(root, "**", name)).grep_v(%r{/(node_modules|vendor|\.git)/})
+          return found.first if found.one?
+
+          raise ConsoleCapture::Failure, ambiguity(name, root, found.sort)
+        end
+
+        def ambiguity(name, root, found)
+          return "no #{name} under #{root}; generate the AwsBox recipe or pass script=<path>" if found.empty?
+
+          "#{found.size} #{name} files under #{root}; pass script=<path>: #{found.join(", ")}"
+        end
+
+        def existing_script(path)
+          script = File.expand_path(path.to_s)
+          File.file?(script) ? script : raise(ConsoleCapture::Failure, "no such script: #{script}")
+        end
+
+        # The variables the generated script reads, set only when the record asks for them.
+        def smoke_env(held)
+          { "TASKDEF" => plain(held[:taskdef]), "SKIP_POST_DEPLOY_SMOKE" => flag(held[:skip]),
+            "SMOKE_ASYNC" => flag(held[:async]), "DRY_RUN" => flag(held[:dry_run]) }.compact
+        end
+
+        def flag(argument) = plain(argument) == true ? "1" : nil
+
+        def child(ask, argv)
+          tree = Codebase::Tree.new
+          tree.require_checkout!
+          run(tree, ask, argv)
+        end
+
+        def run(tree, ask, argv)
+          result = Codebase::RubyChild.new(tree).capture(SCRIPTS.fetch(ask), *argv)
+          raise ConsoleCapture::Failure, message_of(result) unless result.ok?
+
+          { output: { value: result.out } }
+        end
+
+        def message_of(result)
+          text = [result.err, result.out].map(&:strip).reject(&:empty?).join("\n")
+          text.empty? ? "the tool ended with status #{result.status.exitstatus}" : text
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/deploy_toolchain/statuses.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Adapters
+    class DeployToolchain
+      # The generated scripts an ask runs, by name, and what each status they end with means, for
+      # the reason a refusal gives.
+      module Statuses
+        # The `Hecks::Tools` tool an ask runs, by ask.
+        SCRIPTS = { generate: "project_deploy", lint: "lint_deploy_recipes", manifest: "project_oidc" }.freeze
+
+        # `hecks deploy recipe.project`'s flag for each `Recipe` field it takes.
+        GENERATE_FLAGS = { "--tenant" => :tenant, "--schema" => :schema, "--out" => :out,
+                           "--environment" => :environment }.freeze
+
+        # The file name the AwsBox projection gives the post-deploy smoke.
+        SMOKE_SCRIPT = "smoke-after-deploy.sh"
+
+        # What each status of `smoke-after-deploy.sh` means, for the reason a refusal gives.
+        SMOKE_STATUS = { 20 => "the roll did not settle", 21 => "gh missing or no repository, smoke not run",
+                         22 => "the smoke failed", 23 => "the smoke's result is unknown" }.freeze
+
+        # The file names the AwsBox projection gives the two rolls.
+        SERVICE_SCRIPT = "deploy-service.sh"
+        BOX_SCRIPT = "deploy-box.sh"
+
+        # What each status of `deploy-box.sh` means, for the reason a refusal gives.
+        BOX_STATUS = { 40 => "the box stack has no instance", 41 => "the roll did not succeed on the box",
+                       42 => "the box is not healthy after the roll" }.freeze
+
+        # What each status of `deploy-service.sh` means; it ends with the box roll's own statuses.
+        SERVICE_STATUS = { 2 => "unknown service", 30 => "the existing tag is not in ECR",
+                           31 => "the fresh tag is already in ECR", 32 => "the box's Compose file is unreadable",
+                           33 => "the box stack has no instance", 34 => "the stack has no parameter for the container",
+                           35 => "the stack update failed or did not settle",
+                           36 => "a parameter other than the container's changed",
+                           37 => "the task definition lacks the pushed image",
+                           38 => "the task definition has no such container" }.merge(BOX_STATUS).freeze
+
+        # The file names the AwsBox projection gives the data copy and its comparison.
+        RESTORE_SCRIPT = "restore-to-rds.sh"
+        VERIFY_SCRIPT = "verify-copy.sh"
+
+        # The status `verify-copy.sh` ends with when the databases differ: an answer, not a refusal.
+        DRIFT_STATUS = 50
+
+        # What each status of `restore-to-rds.sh` means, for the reason a refusal gives.
+        RESTORE_STATUS = { 60           => "a Postgres client older than 16",
+                           61           => "the target already has a schema; force=true replaces it",
+                           62           => "unexpected errors restoring a schema",
+                           DRIFT_STATUS => "the copy does not match the source" }.freeze
+
+        # The file name of the bluebook report script and of the preview script; a companion roll
+        # runs `deploy-<companion>.sh`.
+        DIFF_SCRIPT = "bluebooks-diff.sh"
+        PREVIEW_SCRIPT = "preview.sh"
+
+        # What `preview.sh` ends with: every refusal and failure is 1, a bad verb 2.
+        PREVIEW_STATUS = { 1 => "the preview script refused or failed", 2 => "usage" }.freeze
+
+        # What a roll script ends with: every refusal and failed check is 1.
+        COMPANION_STATUS = { 1 => "the roll was refused, did not succeed, or the companion is not healthy" }.freeze
+
+        # The outcome each `preview.sh` verb records; the writes among them need `confirm`.
+        PREVIEW_OUTCOMES = { "name" => "named", "url" => "located", "list" => "listed", "deploy" => "deployed",
+                             "destroy" => "destroyed", "login" => "signed_in" }.freeze
+        PREVIEW_WRITES = %w[deploy destroy login].freeze
+
+        # What `bluebooks-diff.sh` prints when it has nothing to compare.
+        DIFF_UNAVAILABLE = /^==> bluebooks: (could not read|the local domain image has no|the running domain image .* predates)/
+      end
+    end
+  end
+end