hecks 3.5.0 → 3.7.0

data/lib/hecks/tools/deploy_recipe_lint/checks.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require_relative "../../tools"
+
+module Hecks
+  module Tools
+    module DeployRecipeLint
+      # The three recipe checks, each answering the violations it finds in one target.
+      module Checks
+        # Flags a chain that runs an AWS/DB command and later hits an unconditional `exit 0`.
+        def check_blind_exit_zero(target, chains)
+          chains.filter_map { |chain| blind_exit_zero(target, chain) }
+        end
+
+        # Flags `exit $?` whose preceding statement in the chain is a benign echo/no-op.
+        def check_stale_dollar_question(target, chains)
+          chains.filter_map { |chain| stale_dollar_question(target, chain) }
+        end
+
+        # Flags a target whose first AWS/DB command has no earlier echo step.
+        def check_prod_touch_without_echo(target, recipe_lines)
+          ordered = real_statements(recipe_lines)
+          first_risky = ordered.find { |_, text| RISKY_REGEX.match?(text) }
+          return [] if first_risky.nil? || echo_before?(ordered, first_risky)
+
+          [Violation.new(
+            target: target, line: first_risky.first + 1, rule: "PROD_TOUCH_WITHOUT_ECHO",
+            message: "touches AWS/DB (#{first_risky.last.strip.inspect}) with no earlier echo/validation step in this " \
+                     "recipe naming what it's about to do to a human running it interactively."
+          )]
+        end
+
+        private
+
+        def blind_exit_zero(target, chain)
+          exit_zero = chain.find { |_, stmt| BARE_EXIT_ZERO_REGEX.match?(normalize_statement(stmt)) }
+          return unless exit_zero
+
+          risky_before = chain.take_while { |line_no, _| line_no != exit_zero.first }
+                              .select { |_, stmt| RISKY_REGEX.match?(stmt) }
+          return if risky_before.empty?
+
+          Violation.new(target: target, line: exit_zero.first + 1, rule: "UNVERIFIED_EXIT_ZERO",
+                        message: blind_exit_message(risky_before.last))
+        end
+
+        def blind_exit_message(risky)
+          "unconditional `exit 0` follows an AWS/DB-touching command (line #{risky.first + 1}: " \
+            "#{risky.last.strip.inspect}) whose own exit status this chain never checks — a real " \
+            "failure there would still report success."
+        end
+
+        def stale_dollar_question(target, chain)
+          idx = chain.index { |_, stmt| DOLLAR_QUESTION_EXIT_REGEX.match?(normalize_statement(stmt)) }
+          return unless idx
+
+          prev = idx.positive? ? chain[idx - 1] : nil
+          return unless prev && BENIGN_REGEX.match?(normalize_statement(prev.last))
+
+          Violation.new(target: target, line: chain[idx].first + 1, rule: "STALE_DOLLAR_QUESTION",
+                        message: stale_question_message(prev))
+        end
+
+        def stale_question_message(prev)
+          "`exit $?` follows a benign statement (line #{prev.first + 1}: #{prev.last.strip.inspect}), " \
+            "not the meaningful command it claims to report on — capture the real command's status into a " \
+            "named variable instead (this codebase's own convention, e.g. `BOOT_STATUS=$$?` ... " \
+            "`exit $$BOOT_STATUS`) and exit that, not a bare $?."
+        end
+
+        def echo_before?(ordered, first_risky)
+          ordered.take_while { |line_no, _| line_no != first_risky.first }
+                 .any? { |_, text| ECHO_REGEX.match?(text) }
+        end
+      end
+    end
+  end
+end

data/lib/hecks/tools/deploy_recipe_lint/fixtures.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require "tmpdir"
+require "fileutils"
+require_relative "../../tools"
+
+module Hecks
+  module Tools
+    module DeployRecipeLint
+      # Generated fixture domains for the deploy generator, so the lint has real Makefiles to read.
+      module Fixtures
+        # The fixture's bluebook, where `__NAME__` stands for the domain's name.
+        FIXTURE_BLUEBOOK = <<~BLUEBOOK
+          Hecks.bluebook "__NAME__" do
+            aggregate "Thing" do
+              identified_by :name
+              attribute :name, ThingName
+              value_object "ThingName" do
+                attribute :value, String
+                invariant("named") { !value.to_s.empty? }
+              end
+              command "Create" do
+                attribute :name, ThingName
+                sets :name
+                emits "ThingCreated"
+              end
+            end
+          end
+        BLUEBOOK
+
+        # The fixture's world, where `__NAME__` stands for the domain's name and `__BODY__` for its
+        # deployment settings.
+        FIXTURE_WORLD = <<~WORLD
+          Hecks.world "__NAME__" do
+            deployed_to("AwsLambda") do
+              __BODY__
+            end
+          end
+        WORLD
+
+        # Writes a minimal bluebook/world pair under `dir` for the deploy generator to generate
+        # from.
+        def write_fixture(dir, basename, world_body, env_local: nil)
+          domain_dir = File.join(dir, basename)
+          bluebook_dir = File.join(domain_dir, "bluebook")
+          FileUtils.mkdir_p(bluebook_dir)
+          name = basename.split("_").map(&:capitalize).join
+
+          File.write(File.join(bluebook_dir, "#{basename}.bluebook"), FIXTURE_BLUEBOOK.gsub("__NAME__") { name })
+          File.write(File.join(bluebook_dir, "#{basename}.world"), world_text(name, world_body))
+          File.write(File.join(domain_dir, ".env.local"), env_local) if env_local
+
+          domain_dir
+        end
+
+        # Runs the deploy generator on a tmpdir fixture; output always lands in
+        # <root>/deploy/<basename>.
+        def generate!(root, basename, world_body, env_local: nil)
+          Dir.mktmpdir do |dir|
+            domain_dir = write_fixture(dir, basename, world_body, env_local: env_local)
+            outcome = Hecks::Adapters::ConsoleCapture.capture { DeployRecipe.main([domain_dir], root: root) }
+            outcome.ok? or raise "hecks deploy project failed generating the #{basename} fixture: #{outcome.output}"
+          end
+          File.join(root, "deploy", basename)
+        end
+
+        # Own-RDS, Shared-mode and OAuth domains: together they hit every branch of the recipe
+        # builders.
+        def fixtures
+          {
+            "own fixture"    => ["region \"us-east-1\"", nil],
+            "shared fixture" => ["region \"us-east-1\"\n    database \"Shared\"\n    owner \"SomeOwner\"", nil],
+            "oauth fixture"  => [
+              "region \"us-east-1\"\n    web \"Rust\"",
+              "GOOGLE_CLIENT_ID=test-client-id.apps.googleusercontent.com\nGOOGLE_CLIENT_SECRET=test-secret\n"
+            ]
+          }
+        end
+
+        private
+
+        def world_text(name, world_body)
+          FIXTURE_WORLD.gsub("__NAME__") { name }.gsub("__BODY__") { world_body }
+        end
+      end
+    end
+  end
+end

data/lib/hecks/tools/deploy_recipe_lint/makefile.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require_relative "../../tools"
+
+module Hecks
+  module Tools
+    module DeployRecipeLint
+      # Reads a Makefile into its targets, recipe lines and shell chains.
+      module Makefile
+        # A target line: a name, a colon, and nothing but prerequisites after it.
+        TARGET_LINE = %r{\A([A-Za-z0-9_./$(){}-]+):(?:\s.*)?\z}
+
+        # Maps each target name to its `[line_no, raw_text]` recipe lines, tabs and continuations
+        # intact.
+        def parse_targets(text)
+          lines = text.lines
+          targets = {}
+          index = 0
+          index = read_line(lines, index, targets) while index < lines.length
+          targets
+        end
+
+        # Drops comment and blank lines; a comment can quote "sam deploy" or "echo" but never runs.
+        def real_statements(recipe_lines)
+          recipe_lines.reject { |_, text| text.delete_prefix("\t").start_with?("#") || text.strip.empty? }
+        end
+
+        # Splits real statements into shell chains; Make runs each backslash-terminated run as one
+        # shell.
+        def shell_chains(recipe_lines)
+          statements = real_statements(recipe_lines).map { |line_no, text| continued_statement(line_no, text) }
+          statements.slice_after { |_, _, continues| !continues }
+                    .map { |chain| chain.map { |line_no, statement, _| [line_no, statement] } }
+        end
+
+        # Drops the leading Make `@` and trailing `;` so exit-code checks match the bare statement.
+        def normalize_statement(text)
+          text.sub(/\A@/, "").strip.sub(/;\s*\z/, "")
+        end
+
+        private
+
+        # Reads the target that starts at `index` into `targets`, when a target starts there.
+        #
+        # @return [Integer] the index of the next line to read
+        def read_line(lines, index, targets)
+          match = skippable_line?(lines[index]) ? nil : lines[index].match(TARGET_LINE)
+          return index + 1 unless match
+
+          targets[match[1]], index = recipe_from(lines, index + 1)
+          index
+        end
+
+        # A line that neither starts a target nor belongs to a recipe.
+        def skippable_line?(line)
+          line.start_with?("\t", "#") || line.strip.empty? || line.include?(":=") || line.start_with?(".PHONY")
+        end
+
+        # @return [Array(Array, Integer)] the recipe lines from `start` on, and the index after them
+        def recipe_from(lines, start)
+          recipe = []
+          index = start
+          while index < lines.length && recipe_line?(lines[index])
+            recipe << [index, lines[index].chomp]
+            index += 1
+          end
+          [recipe, index]
+        end
+
+        def recipe_line?(line)
+          line == "\n" || line.start_with?("\t") || line.start_with?("#")
+        end
+
+        # @return [Array] the line number, the statement without its continuation backslash, and
+        #   whether it continues on the next line
+        def continued_statement(line_no, text)
+          stripped = text.delete_prefix("\t")
+          continues = stripped.end_with?("\\")
+          [line_no, continues ? stripped.delete_suffix("\\").rstrip : stripped, continues]
+        end
+      end
+    end
+  end
+end

data/lib/hecks/tools/deploy_recipe_lint.rb

@@ -6,6 +6,9 @@ require "hecks"
 require_relative "../tools"
 require_relative "deploy_recipe"
 require_relative "../hecks/adapters/console_capture"
+require_relative "deploy_recipe_lint/makefile"
+require_relative "deploy_recipe_lint/checks"
+require_relative "deploy_recipe_lint/fixtures"
 
 module Hecks
   module Tools
@@ -34,121 +37,11 @@ module Hecks
         end
       end
 
-      module_function
-
-      # Maps each target name to its `[line_no, raw_text]` recipe lines, tabs and continuations
-      # intact.
-      def parse_targets(text)
-        lines = text.lines
-        targets = {}
-        i = 0
-        while i < lines.length
-          line = lines[i]
-          if line.start_with?("\t", "#") || line.strip.empty? || line.include?(":=") || line.start_with?(".PHONY")
-            i += 1
-            next
-          end
-
-          if (m = line.match(%r{\A([A-Za-z0-9_./$(){}-]+):(?:\s.*)?\z}))
-            recipe = []
-            j = i + 1
-            while j < lines.length && (lines[j] == "\n" || lines[j].start_with?("\t") || lines[j].start_with?("#"))
-              recipe << [j, lines[j].chomp]
-              j += 1
-            end
-            targets[m[1]] = recipe
-            i = j
-          else
-            i += 1
-          end
-        end
-        targets
-      end
-
-      # Drops comment and blank lines; a comment can quote "sam deploy" or "echo" but never runs.
-      def real_statements(recipe_lines)
-        recipe_lines.reject { |_, text| text.sub(/\A\t/, "").start_with?("#") || text.strip.empty? }
-      end
-
-      # Splits real statements into shell chains; Make runs each backslash-terminated run as one
-      # shell.
-      def shell_chains(recipe_lines)
-        chains = []
-        current = []
-        real_statements(recipe_lines).each do |line_no, text|
-          stripped = text.sub(/\A\t/, "")
-          continues = stripped.end_with?("\\")
-          statement = continues ? stripped.sub(/\\\z/, "").rstrip : stripped
-          current << [line_no, statement]
-          unless continues
-            chains << current
-            current = []
-          end
-        end
-        chains << current unless current.empty?
-        chains
-      end
-
-      # Drops the leading Make `@` and trailing `;` so exit-code checks match the bare statement.
-      def normalize_statement(text)
-        text.sub(/\A@/, "").strip.sub(/;\s*\z/, "")
-      end
-
-      # Flags a chain that runs an AWS/DB command and later hits an unconditional `exit 0`.
-      def check_blind_exit_zero(target, chains)
-        chains.filter_map do |chain|
-          exit_zero = chain.find { |_, stmt| BARE_EXIT_ZERO_REGEX.match?(normalize_statement(stmt)) }
-          next unless exit_zero
-
-          risky_before = chain.take_while { |line_no, _| line_no != exit_zero.first }
-                              .select { |_, stmt| RISKY_REGEX.match?(stmt) }
-          next if risky_before.empty?
-
-          Violation.new(
-            target: target, line: exit_zero.first + 1, rule: "UNVERIFIED_EXIT_ZERO",
-            message: "unconditional `exit 0` follows an AWS/DB-touching command (line #{risky_before.last.first + 1}: " \
-                     "#{risky_before.last.last.strip.inspect}) whose own exit status this chain never checks — a real " \
-                     "failure there would still report success."
-          )
-        end
-      end
-
-      # Flags `exit $?` whose preceding statement in the chain is a benign echo/no-op.
-      def check_stale_dollar_question(target, chains)
-        chains.filter_map do |chain|
-          idx = chain.index { |_, stmt| DOLLAR_QUESTION_EXIT_REGEX.match?(normalize_statement(stmt)) }
-          next unless idx
-
-          prev = idx.positive? ? chain[idx - 1] : nil
-          next unless prev
-          next unless BENIGN_REGEX.match?(normalize_statement(prev.last))
-
-          Violation.new(
-            target: target, line: chain[idx].first + 1, rule: "STALE_DOLLAR_QUESTION",
-            message: "`exit $?` follows a benign statement (line #{prev.first + 1}: #{prev.last.strip.inspect}), " \
-                     "not the meaningful command it claims to report on — capture the real command's status into a " \
-                     "named variable instead (this codebase's own convention, e.g. `BOOT_STATUS=$$?` ... " \
-                     "`exit $$BOOT_STATUS`) and exit that, not a bare $?."
-          )
-        end
-      end
+      extend Makefile
+      extend Checks
+      extend Fixtures
 
-      # Flags a target whose first AWS/DB command has no earlier echo step.
-      def check_prod_touch_without_echo(target, recipe_lines)
-        ordered = real_statements(recipe_lines)
-        first_risky = ordered.find { |_, text| RISKY_REGEX.match?(text) }
-        return [] unless first_risky
-
-        seen_echo = ordered.take_while { |line_no, _| line_no != first_risky.first }
-                           .any? { |_, text| ECHO_REGEX.match?(text) }
-        return [] if seen_echo
-
-        [Violation.new(
-          target: target, line: first_risky.first + 1, rule: "PROD_TOUCH_WITHOUT_ECHO",
-          message: "touches AWS/DB (#{first_risky.last.strip.inspect}) with no earlier echo/validation step in this " \
-                   "recipe naming what it's about to do to a human running it interactively."
-        )]
-      end
+      module_function
 
       # Runs all three checks over every target; `source` labels each violation.
       def lint(text, source:)
@@ -163,68 +56,6 @@ module Hecks
         violations
       end
 
-      # Writes a minimal bluebook/world pair under `dir` for the deploy generator to generate from.
-      def write_fixture(dir, basename, world_body, env_local: nil)
-        domain_dir = File.join(dir, basename)
-        bluebook_dir = File.join(domain_dir, "bluebook")
-        FileUtils.mkdir_p(bluebook_dir)
-        bluebook_name = basename.split("_").map(&:capitalize).join
-
-        File.write(File.join(bluebook_dir, "#{basename}.bluebook"), <<~BLUEBOOK)
-          Hecks.bluebook "#{bluebook_name}" do
-            aggregate "Thing" do
-              identified_by :name
-              attribute :name, ThingName
-              value_object "ThingName" do
-                attribute :value, String
-                invariant("named") { !value.to_s.empty? }
-              end
-              command "Create" do
-                attribute :name, ThingName
-                sets :name
-                emits "ThingCreated"
-              end
-            end
-          end
-        BLUEBOOK
-
-        File.write(File.join(bluebook_dir, "#{basename}.world"), <<~WORLD)
-          Hecks.world "#{bluebook_name}" do
-            deployed_to("AwsLambda") do
-              #{world_body}
-            end
-          end
-        WORLD
-
-        File.write(File.join(domain_dir, ".env.local"), env_local) if env_local
-
-        domain_dir
-      end
-
-      # Runs the deploy generator on a tmpdir fixture; output always lands in
-      # <root>/deploy/<basename>.
-      def generate!(root, basename, world_body, env_local: nil)
-        Dir.mktmpdir do |dir|
-          domain_dir = write_fixture(dir, basename, world_body, env_local: env_local)
-          outcome = Hecks::Adapters::ConsoleCapture.capture { DeployRecipe.main([domain_dir], root: root) }
-          outcome.ok? or raise "hecks deploy project failed generating the #{basename} fixture: #{outcome.output}"
-        end
-        File.join(root, "deploy", basename)
-      end
-
-      # Own-RDS, Shared-mode and OAuth domains: together they hit every branch of the recipe
-      # builders.
-      def fixtures
-        {
-          "own fixture"    => ["region \"us-east-1\"", nil],
-          "shared fixture" => ["region \"us-east-1\"\n    database \"Shared\"\n    owner \"SomeOwner\"", nil],
-          "oauth fixture"  => [
-            "region \"us-east-1\"\n    web \"Rust\"",
-            "GOOGLE_CLIENT_ID=test-client-id.apps.googleusercontent.com\nGOOGLE_CLIENT_SECRET=test-secret\n"
-          ]
-        }
-      end
-
       # Lints the Makefiles named in `argv`, or three generated fixture domains when there are none.
       #
       # @param argv [Array<String>] Makefile paths, or `-h`/`--help`
@@ -233,29 +64,35 @@ module Hecks
       def main(argv, root: Tools::ROOT)
         return usage if %w[-h --help].include?(argv.first)
 
-        violations = []
         generated_dirs = []
         begin
-          if argv.empty?
-            fixtures.each do |label, (world_body, env_local)|
-              basename = "lint_deploy_recipes_fixture_#{label.tr(' ', '_')}"
-              dir = generate!(root, basename, world_body, env_local: env_local)
-              generated_dirs << dir
-              makefile_path = File.join(dir, "Makefile")
-              violations.concat(lint(File.read(makefile_path), source: "#{label} (#{makefile_path})"))
-            end
-          else
-            argv.each do |path|
-              File.exist?(path) or abort "hecks deploy lint: no such file #{path}"
-              violations.concat(lint(File.read(path), source: path))
-            end
-          end
-          report(violations)
+          report(argv.empty? ? lint_fixtures(root, generated_dirs) : lint_files(argv))
         ensure
           generated_dirs.each { |dir| FileUtils.rm_rf(dir) }
         end
       end
 
+      # Generates each fixture domain's recipes, noting their directories in `generated_dirs`.
+      #
+      # @return [Array<Violation>] what the lint found in their Makefiles
+      def lint_fixtures(root, generated_dirs)
+        fixtures.flat_map do |label, (world_body, env_local)|
+          basename = "lint_deploy_recipes_fixture_#{label.tr(" ", "_")}"
+          dir = generate!(root, basename, world_body, env_local: env_local)
+          generated_dirs << dir
+          makefile_path = File.join(dir, "Makefile")
+          lint(File.read(makefile_path), source: "#{label} (#{makefile_path})")
+        end
+      end
+
+      # @return [Array<Violation>] what the lint found in the named Makefiles
+      def lint_files(paths)
+        paths.flat_map do |path|
+          File.exist?(path) or abort "hecks deploy lint: no such file #{path}"
+          lint(File.read(path), source: path)
+        end
+      end
+
       # @return [Integer] 0, after printing the usage
       def usage
         puts "usage: hecks deploy lint [Makefile ...]"

data/lib/hecks/tools/drop_implicit_append_fields.rb

@@ -52,22 +52,30 @@ module Hecks
         Hecks::Codemod.each_command(registry) do |construct, command|
           command.mutations.select { |m| m.op == :append }.each do |mutation|
             element = Hecks::Codemod.element_construct_for(construct, mutation.target)
-            next unless element
+            found.concat(appended_candidates(command, mutation, element)) if element
+          end
+        end
+        found
+      end
 
-            mutation.source.each do |field, value|
-              next unless value.is_a?(Symbol) && value.to_s == field.to_s
+      # @param command [Object] a command construct
+      # @param mutation [Object] one of its `append:` mutations
+      # @param element [Object] the element the mutation appends to
+      # @return [Array<Candidate>] the fields the mutation copies from same-named attributes
+      def appended_candidates(command, mutation, element)
+        mutation.source.filter_map do |field, value|
+          next unless value.is_a?(Symbol) && value.to_s == field.to_s
 
-              local = command.attributes.find { |attr| attr.name.to_s == field.to_s }
-              next unless local
+          candidate_for(command, element, field)
+        end
+      end
 
-              owner_attr = Hecks::Codemod.owner_attribute(element, field)
-              next unless identical_attribute?(local, owner_attr)
+      # @return [Candidate, nil] the command's own attribute, when the element declares the same one
+      def candidate_for(command, element, field)
+        local = command.attributes.find { |attr| attr.name.to_s == field.to_s }
+        return unless local && identical_attribute?(local, Hecks::Codemod.owner_attribute(element, field))
 
-              found << Candidate.new(command_name: command.hecks_name, field: field.to_s, type: local.type)
-            end
-          end
-        end
-        found
+        Candidate.new(command_name: command.hecks_name, field: field.to_s, type: local.type)
       end
 
       # @param text [String] a bluebook's source

data/lib/hecks/tools/era_projection_backfill.rb

@@ -22,6 +22,13 @@ module Hecks
         domain_path = argv.first
         abort "usage: hecks backfill_projections <domain path>" unless domain_path
 
+        registry, bluebook = load_domain(domain_path)
+        backfill(bluebook, lineage_settings(registry, bluebook))
+      end
+
+      # @param domain_path [String] the domain directory
+      # @return [Array] the registry and its bluebook
+      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))
@@ -32,7 +39,7 @@ module Hecks
         end
 
         bluebook = registry.bluebooks.values.first or abort "no bluebook in #{directory}"
-        backfill(bluebook, lineage_settings(registry, bluebook))
+        [registry, bluebook]
       end
 
       # @return [Hash] the persistence binding's settings
@@ -40,55 +47,65 @@ module Hecks
       def lineage_settings(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
-        capable =
-          begin
-            adapter_class = registry.adapter_class(adapter_name)
-            adapter_class.respond_to?(:lineage_capable?) && adapter_class.lineage_capable?
-          rescue StandardError
-            false
-          end
         # Only a lineage-capable adapter holds eras — every other adapter has no held_projection
         # column to migrate.
-        abort "#{bluebook.name} is bound to #{adapter_name}, which holds no eras — nothing to migrate." unless capable
+        unless lineage_capable?(registry, adapter_name)
+          abort "#{bluebook.name} is bound to #{adapter_name}, which holds no eras — nothing to migrate."
+        end
 
         registry.binding_settings(bluebook.name, Hecks::Ports::Persistence::VERB, adapter_name)
       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
+
       # @return [Integer] the exit status
       def backfill(bluebook, settings)
         db = Hecks::Adapters::PostgresEra.connect_for(bluebook.name, settings)
         lineage = Hecks::Adapters::PostgresEra::Lineage.new(db, bluebook.name)
         lineage.ensure_base!
 
-        missing = lambda {
-          db.exec_params(
-            "SELECT count(*)::int AS n FROM hecks_eras WHERE domain = $1 AND held_projection IS NULL",
-            [bluebook.name]
-          )[0]["n"].to_i
-        }
+        before = missing_projections(db, bluebook)
+        return nothing_to_do(bluebook) if before.zero?
+        return 1 unless rows_intact?(bluebook, lineage)
 
-        before = missing.call
-        if before.zero?
-          puts "#{bluebook.name}: every held era already carries a projection — nothing to do."
-          return 0
-        end
+        backfilled = before - missing_projections(db, bluebook)
+        puts "#{bluebook.name}: backfilled #{backfilled} era#{"s" unless backfilled == 1} — " \
+             "every row now carries a projection."
+        0
+      end
 
-        begin
-          # Raises on the first row whose own digest check fails — a tampered row, not a merely
-          # legacy one, which backfilling must not paper over.
-          lineage.eras
-        rescue Hecks::Runtime::WiringError => e
-          puts "#{bluebook.name}: stopped at a row that isn't merely legacy — it fails its own integrity check:"
-          puts "  #{e.message}"
-          puts "  resolve that first (see hecks reattest), then run this again for the remaining rows."
-          return 1
-        end
+      # @return [Integer] how many of the domain's era rows carry no projection
+      def missing_projections(db, bluebook)
+        db.exec_params(
+          "SELECT count(*)::int AS n FROM hecks_eras WHERE domain = $1 AND held_projection IS NULL",
+          [bluebook.name]
+        )[0]["n"].to_i
+      end
 
-        backfilled = before - missing.call
-        puts "#{bluebook.name}: backfilled #{backfilled} era#{'s' unless backfilled == 1} — " \
-             "every row now carries a projection."
+      # @return [Integer] 0
+      def nothing_to_do(bluebook)
+        puts "#{bluebook.name}: every held era already carries a projection — nothing to do."
         0
       end
+
+      # Reading the eras backfills them, and raises on the first row whose own digest check fails —
+      # a tampered row, not a merely legacy one, which backfilling must not paper over.
+      #
+      # @return [Boolean] false, after printing why, when a row fails its own integrity check
+      def rows_intact?(bluebook, lineage)
+        lineage.eras
+        true
+      rescue Hecks::Runtime::WiringError => e
+        puts "#{bluebook.name}: stopped at a row that isn't merely legacy — it fails its own integrity check:"
+        puts "  #{e.message}"
+        puts "  resolve that first (see hecks reattest), then run this again for the remaining rows."
+        false
+      end
     end
   end
 end