hecks 3.4.2 → 3.6.0

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

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

@@ -5,6 +5,11 @@ require_relative "shell"
 require_relative "codebase/tree"
 require_relative "codebase/ruby_child"
 require "hecks/projections/deploy/template_diff"
+require_relative "bluebook_report"
+require_relative "deploy_plans"
+require_relative "deploy_toolchain/statuses"
+require_relative "deploy_toolchain/scripts"
+require_relative "deploy_toolchain/answers"
 
 module Hecks
   module Adapters
@@ -18,19 +23,9 @@ module Hecks
     # the project it is given, wherever that is, so it needs no checkout, and neither does a
     # comparison.
     class DeployToolchain
-      # 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
+      include Statuses
+      include Scripts
+      include Answers
 
       # Accepts the arguments every driven adapter is built with and keeps none of them.
       #
@@ -121,65 +116,138 @@ module Hecks
       # @raise [ConsoleCapture::Failure] when no script, or more than one, is found, or it ends
       #   non-zero; the message names its status and what it printed
       def smoke(**held)
-        script = smoke_script(plain(held[:project]), plain(held[:script]))
-
-        result = Shell.new.capture("bash", script, env: smoke_env(held), chdir: File.dirname(script))
-        report = [result.out, result.err].map(&:strip).reject(&:empty?).join("\n")
-        return { report: { value: report } } if result.ok?
-
-        code = result.status.exitstatus
-        raise ConsoleCapture::Failure, "smoke ended #{code} (#{SMOKE_STATUS.fetch(code, 'unexpected')})\n#{report}"
+        run_script(Script.new(SMOKE_SCRIPT, "smoke", SMOKE_STATUS), held, smoke_env(held))
       end
 
-      private
-
-      # The script a project's smoke runs: the override, else `smoke-after-deploy.sh` in the project
-      # itself, else the only one beneath it (not under `node_modules`, `vendor` or `.git`).
-      def smoke_script(project, override)
-        return existing_script(override) if override
-
-        root = File.expand_path(project.to_s)
-        beside = File.join(root, SMOKE_SCRIPT)
-        return beside if File.file?(beside)
-
-        found = Dir.glob(File.join(root, "**", SMOKE_SCRIPT)).grep_v(%r{/(node_modules|vendor|\.git)/})
-        return found.first if found.one?
+      # Rolls one service with a project's generated `deploy-service.sh`, through
+      # `hecks deploy service_roll.run`.
+      #
+      # The script pushes the image under a fresh tag, sets the stack's tag parameter and rolls
+      # the box, so it writes to AWS (a spec puts stand-in programs first on `PATH`).
+      # `SMOKE_BY_COMMAND=1` leaves the smoke to the record's policy; the task definition and
+      # tag come from the script's last line.
+      #
+      # @param held [Hash] the `ServiceRoll` record: `project`, `service`, and `script`,
+      #   `existing_tag` and `local_image` when set
+      # @return [Hash{Symbol => Hash}] `report:`, and `taskdef:` and `tag:` when named
+      # @raise [ConsoleCapture::Failure] when no script is found or it ends non-zero
+      def roll_service(**held)
+        env = { "EXISTING_TAG" => plain(held[:existing_tag]), "LOCAL_IMAGE" => plain(held[:local_image]),
+                "SMOKE_BY_COMMAND" => "1" }.compact
+        script = Script.new(SERVICE_SCRIPT, "service roll", SERVICE_STATUS, [plain(held[:service])])
+        answer = run_script(script, held, env)
+        answer.merge(rolled(answer[:report][:value])).merge(carried(held, "service_roll"))
+      end
 
-        raise ConsoleCapture::Failure, ambiguity(root, found.sort)
+      # Rolls the whole box with a project's generated `deploy-box.sh`, through
+      # `hecks deploy box_roll.run`.
+      #
+      # @param held [Hash] the `BoxRoll` record: `project`, and `script`, `taskdef`, `tags` when set
+      # @return [Hash{Symbol => Hash}] `report:` what the script printed
+      # @raise [ConsoleCapture::Failure] when no script, or more than one, is found, or it ends
+      #   non-zero; the message names its status and what it printed
+      def roll_box(**held)
+        answer = run_script(Script.new(BOX_SCRIPT, "box roll", BOX_STATUS, box_args(held)), held, {})
+        answer.merge(carried(held, "box_roll")).merge(taskdef: wrapped(plain(held[:taskdef])))
       end
 
-      def ambiguity(root, found)
-        return "no #{SMOKE_SCRIPT} under #{root}; generate the AwsBox recipe or pass script=<path>" if found.empty?
+      # Copies a project's schemas into RDS with its generated `restore-to-rds.sh`, through
+      # `hecks deploy data_copy.restore`.
+      #
+      # The script overwrites the target database's schemas, so the adapter refuses unless the
+      # record says `confirm`, naming what would be overwritten. A `dry_run` answers the plan and
+      # runs nothing (confirmed or not). The script runs with `VERIFY_BY_COMMAND=1`: the record's
+      # policy requests the comparison, unless `skip_verify` or a dry run.
+      #
+      # @param held [Hash] the `DataCopy` record
+      # @return [Hash{Symbol => Hash}] `report:`, `planned:` and what the policies carry on
+      # @raise [ConsoleCapture::Failure] when no script is found, the copy is not confirmed, or the
+      #   script ends non-zero
+      def copy_data(**held)
+        script = script_for(RESTORE_SCRIPT, plain(held[:project]), plain(held[:script]))
+        plan = copy_plan(script, held)
+        return copy_answer(held, "#{plan}\ndry run: nothing was run", planned: true) if plain(held[:dry_run]) == true
 
-        "#{found.size} #{SMOKE_SCRIPT} files under #{root}; pass script=<path>: #{found.join(', ')}"
+        require_confirm(held, "restore", plan)
+        restore(held)
       end
 
-      def existing_script(path)
-        script = File.expand_path(path.to_s)
-        File.file?(script) ? script : raise(ConsoleCapture::Failure, "no such script: #{script}")
+      # Compares two databases with a project's generated `verify-copy.sh`, through
+      # `hecks deploy data_copy.verify`. Read-only on both. Differing databases are an answer
+      # (`drifted:`), not a refusal.
+      #
+      # @param held [Hash] the `CopyVerification` record
+      # @return [Hash{Symbol => Hash}] `report:` and `drifted:`
+      # @raise [ConsoleCapture::Failure] when no script is found or it fails for another reason
+      def compare_copy(**held)
+        env = { "A_DB" => database(held[:source_db]), "B_DB" => database(held[:target_db]) }.compact
+        script = Script.new(VERIFY_SCRIPT, "verify", {}, copy_args(held), [DRIFT_STATUS])
+        answer = run_script(script, held, env)
+        { report: answer[:report], drifted: { value: answer.key?(:status) } }
       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
+      # Reports which bluebook releases a deploy changes, through `hecks deploy bluebook_diff.run`.
+      #
+      # With `old` and `new` (two `package.verify` outputs) the comparison is made here, offline.
+      # With neither, the project's `bluebooks-diff.sh` reads the running image's bluebooks
+      # (read-only) and its report is classified. Never a failure: what cannot be compared is
+      # `unavailable`. Only one of `old` and `new` is refused.
+      #
+      # @param held [Hash] the `BluebookDiff` record
+      # @return [Hash{Symbol => Hash}] `outcome:` (unchanged, changed or unavailable) and `report:`
+      # @raise [ConsoleCapture::Failure] when only one of `old` and `new` is given
+      def compare_bluebooks(**held)
+        old = plain(held[:old])
+        new = plain(held[:new])
+        raise ConsoleCapture::Failure, "give old= and new= together, or neither" if old.nil? != new.nil?
+
+        old ? diff_files(old, new) : diff_script(held)
       end
 
-      def flag(argument) = plain(argument) == true ? "1" : nil
+      # Runs a project's `preview.sh` with one verb, through `hecks deploy preview_run.<verb>`.
+      #
+      # `name`, `url` and `list` read. `deploy`, `destroy` and `login` write to AWS or read its
+      # secrets, so they refuse unless the record says `confirm`, naming the plan; `dry_run` answers
+      # that plan and runs nothing. The branch travels in `BRANCH`, as the script reads it.
+      #
+      # @param held [Hash] the `PreviewRun` record
+      # @return [Hash{Symbol => Hash}] `outcome:`, `report:` and `planned:`
+      # @raise [ConsoleCapture::Failure] when no script is found, a write is not confirmed, or the
+      #   script ends non-zero
+      def run_preview(**held)
+        action = plain(held[:action]).to_s
+        planned = gate_preview(held, action)
+        return planned if planned
 
-      def child(ask, argv)
-        tree = Codebase::Tree.new
-        tree.require_checkout!
-        run(tree, ask, argv)
+        env = { "BRANCH" => plain(held[:branch]) }.compact
+        answer = run_script(Script.new(PREVIEW_SCRIPT, "preview #{action}", PREVIEW_STATUS, [action]), held, env)
+        { outcome: { value: PREVIEW_OUTCOMES.fetch(action) }, report: answer[:report], planned: { value: false } }
       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?
+      # Rolls a companion Compose project onto the box with a project's `deploy-<companion>.sh`,
+      # through `hecks deploy companion_roll.run`.
+      #
+      # The script sends the project and its secret references to the box over SSM and starts it, so
+      # the adapter refuses unless the record says `confirm`, naming the plan; `dry_run` answers the
+      # plan and runs nothing. The task definition is the script's one argument.
+      #
+      # @param held [Hash] the `CompanionRoll` record
+      # @return [Hash{Symbol => Hash}] `report:` and `planned:`
+      # @raise [ConsoleCapture::Failure] when no script is found, the roll is not confirmed, or the
+      #   script ends non-zero
+      def roll_companion(**held)
+        companion = plain(held[:companion]).to_s
+        name = "deploy-#{companion}.sh"
+        plan = companion_plan(held, name, companion)
+        return planned_answer(plan) if plain(held[:dry_run]) == true
 
-        { output: { value: result.out } }
+        require_confirm(held, "roll #{companion}", plan)
+        script = Script.new(name, "companion roll", COMPANION_STATUS, [plain(held[:taskdef])])
+        run_script(script, held, {}).merge(planned: { value: false })
       end
 
+      private
+
       # A project path the tool can read from `root`: relative to it when it lies beneath it, so a
       # recipe made in a checkout names `examples/pizzas`, else absolute.
       def project_path(path, root)
@@ -187,11 +255,6 @@ module Hecks
         absolute.start_with?("#{root}/") ? absolute.delete_prefix("#{root}/") : absolute
       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
-
       def plain(argument) = argument.is_a?(Hash) ? argument[:value] : argument
     end
   end

data/lib/hecks/hecks/adapters/finding_github.rb

@@ -47,7 +47,7 @@ module Hecks
         return said("no kind or severity to label") if labels.empty?
 
         gh("issue", "edit", issue(held), "--add-label", labels.join(","))
-        said("labelled #{labels.join(', ')}")
+        said("labelled #{labels.join(", ")}")
       end
 
       # Comments on the issue with the pull request that fixes the finding.
@@ -82,7 +82,7 @@ module Hecks
 
       def gh(*arguments)
         out, err, status = Open3.capture3("gh", *arguments, "--repo", repository)
-        raise "gh #{arguments.first(2).join(' ')} failed — #{err.strip.empty? ? out.strip : err.strip}" unless status.success?
+        raise "gh #{arguments.first(2).join(" ")} failed — #{err.strip.empty? ? out.strip : err.strip}" unless status.success?
 
         out
       end

data/lib/hecks/hecks/adapters/first_admin.rb

@@ -34,7 +34,7 @@ module Hecks
       #   @return [Boolean] whether the person had to be admitted first
       Result = Struct.new(:email, :role, :admitted, keyword_init: true) do
         # @return [String] the sentence the verb answers with
-        def to_s = "Granted #{role} access to #{email}#{' (admitted first)' if admitted}"
+        def to_s = "Granted #{role} access to #{email}#{" (admitted first)" if admitted}"
       end
 
       # @param runtime [Hecks::Runtime] the booted domain
@@ -52,13 +52,10 @@ module Hecks
       # @raise [Runtime::NotFound] when the domain has no membership chapter, the email is not an
       #   email, or an administrator already exists
       def call(email:, name: nil, role: nil)
-        raise Runtime::NotFound, "#{email.inspect} is not an email address" unless email.to_s.match?(/\A[^\s@]+@[^\s@]+\z/)
+        raise Runtime::NotFound, "#{email.inspect} is not an email address" unless email?(email)
 
         provider = membership_provider
-        verbs    = verbs_of(provider)
-        gate     = gated_role(provider, verbs.fetch(:grant))
-        people   = rows(verbs.fetch(:people))
-        refuse_if_administered!(people, [gate, *OWNER_ROLES].uniq)
+        verbs, gate, people = check_unadministered(provider)
 
         admitted = people.none? { |person| person.dig(:email, :value) == email }
         admit(provider, verbs.fetch(:admit), email, name || email[/\A[^@]+/]) if admitted
@@ -68,6 +65,18 @@ module Hecks
 
       private
 
+      def email?(email) = email.to_s.match?(/\A[^\s@]+@[^\s@]+\z/)
+
+      # The membership verbs, the role the grant is gated to and the people held, once no
+      # administrator is found among them.
+      def check_unadministered(provider)
+        verbs  = verbs_of(provider)
+        gate   = gated_role(provider, verbs.fetch(:grant))
+        people = rows(verbs.fetch(:people))
+        refuse_if_administered!(people, [gate, *OWNER_ROLES].uniq)
+        [verbs, gate, people]
+      end
+
       def membership_provider
         domain = @registry.bluebooks.values.first&.name
         @registry.membership_provider_for(domain) or
@@ -83,11 +92,16 @@ module Hecks
       # The role a verb's command declares, which the dispatch must assert to be let through.
       def gated_role(provider, verb)
         aggregate, command = verb.split("::").last.split(".")
-        found = provider.aggregates.find { |candidate| candidate.hecks_name == aggregate }
-                        &.commands&.find { |candidate| candidate.hecks_name == command }
+        found = declared_command(provider, aggregate, command)
         found&.role&.to_s or raise Runtime::NotFound, "#{verb} declares no role to bootstrap as"
       end
 
+      # The command the provider's aggregate declares, or nil when either is not declared.
+      def declared_command(provider, aggregate, command)
+        holder = provider.aggregates.find { |candidate| candidate.hecks_name == aggregate }
+        holder&.commands&.find { |candidate| candidate.hecks_name == command }
+      end
+
       def refuse_if_administered!(people, roles)
         held = people.select { |person| roles.map(&:downcase).include?(person.dig(:role, :value).to_s.downcase) }
         return if held.empty?

data/lib/hecks/hecks/adapters/git.rb

@@ -3,6 +3,7 @@
 require "stringio"
 require_relative "shell"
 require_relative "console_capture"
+require_relative "git_refs"
 require_relative "codebase/publishing"
 require "hecks/vendoring/git_environment"
 require "hecks/embryonaut_bluebook/vendor_cli"
@@ -15,6 +16,8 @@ module Hecks
     # or a parent process cannot redirect it to another repository. Subprocesses start through the
     # `Shell` adapter.
     class Git
+      include GitRefs
+
       # Accepts the arguments every driven adapter is built with and keeps none of them.
       #
       # @param aggregate [Object, nil] unused
@@ -50,14 +53,24 @@ module Hecks
         root = plain(held[:root]) || Dir.pwd
         require_repository!(from)
 
-        argv = [plain(held[:package])]
-        argv += ["--from", from] if from
+        { report: { value: vendored(held[:package], from, root) } }
+      end
+
+      # What the vendor command printed, once it ended well.
+      def vendored(package, from, root)
         out = StringIO.new
         err = StringIO.new
-        status = EmbryonautBluebook::VendorCli.run(argv + ["--root", root], out: out, err: err, root: root)
+        status = EmbryonautBluebook::VendorCli.run(vendor_argv(package, from, root), out: out, err: err, root: root)
         raise ConsoleCapture::Failure, err.string.strip unless status.zero?
 
-        { report: { value: out.string } }
+        out.string
+      end
+
+      # The words the vendor command takes: the package, where from when named, and the project.
+      def vendor_argv(package, from, root)
+        argv = [plain(package)]
+        argv += ["--from", from] if from
+        argv + ["--root", root]
       end
 
       # Checks a project's vendored packages against their `bluebook.lock` files and describes
@@ -162,7 +175,7 @@ module Hecks
         places = [File.join(name, "bluebook"), File.join("vendor", "embryonaut_bluebooks", name, "bluebook")]
         found = places.map { |place| File.join(root, place) }.find { |dir| File.directory?(dir) }
         found or raise Runtime::NotFound,
-                       "#{name} has no bluebook/ directory in #{root} (looked in #{places.join(' and ')})"
+                       "#{name} has no bluebook/ directory in #{root} (looked in #{places.join(" and ")})"
       end
 
       def registry(held)