hecks 3.5.0 → 3.6.0

data/lib/hecks/tools/corpus_report.rb

@@ -59,29 +59,39 @@ module Hecks
       def rust_coverage
         modules = Hecks::Corpus.generated_modules
         pending = Hecks::Corpus::RUST_COVERAGE_PENDING
-        unknown = pending.keys - modules
-        if unknown.any?
-          abort "hecks corpus_rust_coverage: RUST_COVERAGE_PENDING names #{unknown.join(', ')}, " \
-                "which has no generated module"
-        end
+        refuse_unknown_pending(pending.keys - modules)
 
         results = coverage_results(modules)
-        problems = modules.filter_map do |name|
-          passed, output = results.fetch(name)
-          if pending.key?(name)
-            puts "#{name}: pending (#{passed ? 'NOW PASSES' : 'still fails'}) — #{pending[name]}"
-            "#{name} passes now — delete it from Hecks::Corpus::RUST_COVERAGE_PENDING" if passed
-          else
-            puts "#{name}: #{passed ? 'ok' : 'FAILED'}"
-            "#{name} failed:\n#{output}" unless passed
-          end
-        end
-
+        problems = modules.filter_map { |name| coverage_problem(name, results.fetch(name), pending) }
         return puts("hecks corpus_rust_coverage: #{modules.size} generated modules checked").then { 0 } if problems.empty?
 
         warn problems.join("\n\n")
         1
       end
+
+      # @raise [SystemExit] when `unknown` is not empty
+      def refuse_unknown_pending(unknown)
+        return if unknown.empty?
+
+        abort "hecks corpus_rust_coverage: RUST_COVERAGE_PENDING names #{unknown.join(", ")}, " \
+              "which has no generated module"
+      end
+
+      # Prints one module's line.
+      #
+      # @param result [Array] the module's `[passed, output]`
+      # @param pending [Hash{String => String}] the modules whose check is expected to fail, and why
+      # @return [String, nil] what is wrong with the module, nil when it is as it must be
+      def coverage_problem(name, result, pending)
+        passed, output = result
+        if pending.key?(name)
+          puts "#{name}: pending (#{passed ? "NOW PASSES" : "still fails"}) — #{pending[name]}"
+          "#{name} passes now — delete it from Hecks::Corpus::RUST_COVERAGE_PENDING" if passed
+        else
+          puts "#{name}: #{passed ? "ok" : "FAILED"}"
+          "#{name} failed:\n#{output}" unless passed
+        end
+      end
     end
   end
 end

data/lib/hecks/tools/deploy_recipe/targets.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require_relative "../../tools"
+
+module Hecks
+  module Tools
+    module DeployRecipe
+      # Which `deployed_to(...)` block a world declares, and what to tell a world that declares
+      # none.
+      module Targets
+        # The refusal for a world with no deploy target, where `__WORLD_FILE__` and `__DOMAIN__`
+        # stand for the world file and the domain directory.
+        NO_TARGET = <<~MSG
+          __WORLD_FILE__ declares no deployed_to("AwsLambda"), deployed_to("AwsFargate") or deployed_to("AwsBox") block. Add one, e.g.:
+
+              deployed_to("AwsLambda") do
+                region "us-east-1"
+                memory 512
+                timeout 10
+              end
+
+          or:
+
+              deployed_to("AwsFargate") do
+                region "us-east-1"
+                cpu 256
+                memory 512
+                port 8080
+              end
+
+          or:
+
+              deployed_to("AwsBox") do
+                region "us-east-1"
+                containers [{ name: "web", port: 8080 }]
+              end
+
+          then re-run hecks deploy project __DOMAIN__.
+        MSG
+
+        # Each adapter maps to a registered `Projector` export (`needs_world: true`); this only
+        # finds which one to call.
+        #
+        # @param deploy_settings [Hash] the world's `deployed_to` settings
+        # @param world_file [String] the `.world` file, named in the refusal
+        # @param domain [String] the domain directory, named in the refusal
+        # @return [Symbol] `:aws_lambda`, `:aws_fargate` or `:aws_box`
+        # @raise [SystemExit] with an example block when the world declares none of them
+        def target_key(deploy_settings, world_file, domain)
+          case deploy_settings[:adapter]
+          when "AwsLambda" then :aws_lambda
+          when "AwsFargate" then :aws_fargate
+          when "AwsBox" then :aws_box
+          else
+            abort NO_TARGET.gsub("__WORLD_FILE__") { world_file }.gsub("__DOMAIN__") { domain }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/tools/deploy_recipe/worlds.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require_relative "../../tools"
+
+module Hecks
+  module Tools
+    module DeployRecipe
+      # Finds and loads the `.world` file a domain deploys from, and the registry it boots into.
+      module Worlds
+        # The `.world` file named after the directory; failing that, the sole `*.world` file under
+        # `<domain>/bluebook/`; failing that, the one named after the chapter the domain's hecksagon
+        # attaches by name (`qa/` attaches QualityControl and also holds a Governance `.world`).
+        # It picks by no other rule: guessing which is the domain is not this generator's call.
+        #
+        # @param domain [String] the domain directory
+        # @return [String] the `.world` file
+        # @raise [SystemExit] when there is none
+        def world_file_for(domain)
+          named = File.join(domain, "bluebook", "#{File.basename(domain)}.world")
+          world_file = File.exist?(named) ? named : (sole_world_file(domain) || named)
+
+          File.exist?(world_file) or
+            abort "#{world_file} does not exist — a domain needs a .world file to declare " \
+                  "deployed_to(\"AwsLambda\"), deployed_to(\"AwsFargate\") or deployed_to(\"AwsBox\")"
+          world_file
+        end
+
+        # The snake-cased names of the chapters a domain's hecksagons attach by name
+        # (`Hecks::Chapters.load!("QualityControl")`), which its `.world` and `.hecksagon` files
+        # are named after.
+        #
+        # @param domain [String] the domain directory
+        # @return [Array<String>] such as `["quality_control"]`
+        def attached_stems(domain)
+          Dir.glob(File.join(domain, "bluebook", "*.hecksagon"))
+             .flat_map { |path| File.read(path).scan(/Chapters\.load!\(\s*"([^"]+)"\s*\)/).flatten }
+             .map { |name| Hecks::Naming.snake(name) }.uniq
+        end
+
+        # @param world_file [String] the base `.world` file
+        # @param domain [String] the domain directory
+        # @param environment [String, nil] the overlay to layer over the base
+        # @return [Object] the world's own declaration, named as the bluebook is
+        # @raise [SystemExit] when an overlay is missing or the file declares no world
+        def load_world(world_file, domain, environment)
+          registry = Hecks::Runtime::Registry.new
+          Hecks.with_registry(registry) do
+            Kernel.load(world_file)
+            load_overlay(domain, environment) if environment
+          end
+
+          registry.worlds.values.first or abort "#{world_file} declares no Hecks.world block at all"
+        end
+
+        # Applied before the stack's name is computed, so the output directory agrees with the stack
+        # name `Lambda`/`Fargate` generate: they re-apply this same override against the `world` and
+        # `tenant:` they are handed.
+        #
+        # @param deploy_settings [Hash] the world's `deployed_to` settings
+        # @param options [Options] the flags
+        # @param domain_name [String] the domain directory's name
+        # @return [Hash] the settings, with the tenant appended to `stack_name` when there is one
+        def tenant_settings(deploy_settings, options, domain_name)
+          return deploy_settings unless options.tenant[:tenant]
+
+          base = deploy_settings[:stack_name] || domain_name
+          deploy_settings.merge(stack_name: "#{base}-#{options.tenant[:tenant]}")
+        end
+
+        # Loads the whole registry a domain boots with, not just its own `.bluebook`, because a
+        # cross-domain invoke grant can live in any attached chapter. A domain with no bluebook of
+        # its own (the QA ledger) gets its chapter from the hecksagon's `Chapters.load!`. `root:` is
+        # required or `attaches ... from: :vendor` refuses with "needs a registry with a root to
+        # vendor from".
+        #
+        # @param domain [String] the domain directory
+        # @param bluebook_basename [String] the file name the domain's bluebook and hecksagon share
+        # @return [Hecks::Runtime::Registry] the registry
+        def cross_domain_registry(domain, bluebook_basename)
+          registry = Hecks::Runtime::Registry.new(root: File.expand_path(domain))
+          Hecks.with_registry(registry) { load_attached(domain, bluebook_basename) }
+          registry
+        end
+
+        private
+
+        # The sole `*.world` file, or the sole one named after an attached chapter.
+        def sole_world_file(domain)
+          candidates = Dir.glob(File.join(domain, "bluebook", "*.world"))
+          named = candidates.select { |path| attached_stems(domain).include?(File.basename(path, ".world")) }
+          pick = candidates.size == 1 ? candidates : named
+          pick.first if pick.size == 1
+        end
+
+        def load_overlay(domain, environment)
+          overlay_file = File.join(domain, "bluebook", "environments", "#{environment}.world")
+          File.exist?(overlay_file) or
+            abort "#{overlay_file} does not exist — --environment=#{environment} needs that overlay"
+          Kernel.load(overlay_file)
+        end
+
+        # Loads the attached ports and adapters, then the domain's bluebook and hecksagon.
+        def load_attached(domain, bluebook_basename)
+          %w[ports/persistence.port ports/extraction.port adapters/driven/memory.adapter
+             adapters/driven/prism.adapter].each { |file| Kernel.load(File.join(LIB_HECKS, file)) }
+          %w[bluebook hecksagon].each do |extension|
+            file = File.join(domain, "bluebook", "#{bluebook_basename}.#{extension}")
+            Kernel.load(file) if File.exist?(file)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/tools/deploy_recipe.rb

@@ -4,6 +4,8 @@ require "hecks"
 require "fileutils"
 require "optparse"
 require_relative "../tools"
+require_relative "deploy_recipe/worlds"
+require_relative "deploy_recipe/targets"
 
 module Hecks
   module Tools
@@ -22,9 +24,19 @@ module Hecks
       USAGE = "usage: hecks deploy project <domain> [--tenant=<slug>] [--schema=<name>] " \
               "[--out=<dir>] [--environment=<name>]"
 
+      # The directory `ports/` and `adapters/` live under, loaded into every domain's registry.
+      LIB_HECKS = File.expand_path("..", __dir__)
+
       # What the flags asked for.
       Options = Struct.new(:tenant, :out, :environment)
 
+      # What the generator resolved about a domain: its directory, the flags, the `.world` file and
+      # its declaration, the `deployed_to` settings, the stack's name, the registry and the chapter.
+      Deployment = Struct.new(:domain, :options, :world_file, :world, :settings, :infra_name, :registry, :chapter)
+
+      extend Worlds
+      extend Targets
+
       module_function
 
       # Generates the recipe and prints each file written.
@@ -40,22 +52,10 @@ module Hecks
         options = parse(argv)
         domain = argv.shift or abort USAGE
 
-        world_file = world_file_for(domain)
-        bluebook_basename = File.basename(world_file, ".world")
-        world = load_world(world_file, domain, options.environment)
-        deploy_settings = tenant_settings(world.for_verb("deployed_to"), options, File.basename(domain))
-        infra_name = deploy_settings[:stack_name] || File.basename(domain)
-
-        registry = cross_domain_registry(domain, bluebook_basename)
-        chapter = registry.bluebook(world.domain) or
-          abort "#{world_file} declares no #{world.domain} chapter — #{bluebook_basename}.bluebook's own " \
-                "Hecks.bluebook name has to match world.domain."
-
-        out_dir = options.out ? File.expand_path(options.out) : File.join(root, "deploy", infra_name)
-        artifact = project(target_key(deploy_settings, world_file, domain), chapter, world, registry,
-                           deploy_settings: deploy_settings, infra_name: infra_name, options: options,
-                           domain: domain, root: root, world_file: world_file)
-        write(artifact, out_dir)
+        deployment = resolve(domain, options)
+        out_dir = options.out ? File.expand_path(options.out) : File.join(root, "deploy", deployment.infra_name)
+        target = target_key(deployment.settings, deployment.world_file, domain)
+        write(project(target, deployment, root), out_dir)
         0
       end
 
@@ -64,12 +64,7 @@ module Hecks
       # @raise [SystemExit] when `--schema` has no `--tenant`
       def parse(argv)
         options = Options.new({}, nil, nil)
-        OptionParser.new do |parser|
-          parser.on("--tenant=SLUG") { |v| options.tenant[:tenant] = v }
-          parser.on("--schema=NAME") { |v| options.tenant[:schema] = v }
-          parser.on("--out=DIR") { |v| options.out = v }
-          parser.on("--environment=NAME") { |v| options.environment = v }
-        end.parse!(argv)
+        option_parser(options).parse!(argv)
 
         if options.tenant[:schema] && !options.tenant[:tenant]
           abort "--schema needs --tenant=<slug> — a schema override with no tenant to scope it to is meaningless"
@@ -77,184 +72,75 @@ module Hecks
         options
       end
 
-      # The `.world` file named after the directory; failing that, the sole `*.world` file under
-      # `<domain>/bluebook/`; failing that, the one named after the chapter the domain's hecksagon
-      # attaches by name (`qa/` attaches QualityControl and also holds a Governance `.world`).
-      # It picks by no other rule: guessing which is the domain is not this generator's call.
-      #
-      # @param domain [String] the domain directory
-      # @return [String] the `.world` file
-      # @raise [SystemExit] when there is none
-      def world_file_for(domain)
-        world_file = File.join(domain, "bluebook", "#{File.basename(domain)}.world")
-        unless File.exist?(world_file)
-          candidates = Dir.glob(File.join(domain, "bluebook", "*.world"))
-          named = candidates.select { |path| attached_stems(domain).include?(File.basename(path, ".world")) }
-          pick = candidates.size == 1 ? candidates : named
-          world_file = pick.first if pick.size == 1
+      # @return [OptionParser] the parser that fills `options` as flags are seen
+      def option_parser(options)
+        OptionParser.new do |parser|
+          parser.on("--tenant=SLUG") { |v| options.tenant[:tenant] = v }
+          parser.on("--schema=NAME") { |v| options.tenant[:schema] = v }
+          parser.on("--out=DIR") { |v| options.out = v }
+          parser.on("--environment=NAME") { |v| options.environment = v }
         end
-
-        File.exist?(world_file) or
-          abort "#{world_file} does not exist — a domain needs a .world file to declare " \
-                "deployed_to(\"AwsLambda\"), deployed_to(\"AwsFargate\") or deployed_to(\"AwsBox\")"
-        world_file
-      end
-
-      # The snake-cased names of the chapters a domain's hecksagons attach by name
-      # (`Hecks::Chapters.load!("QualityControl")`), which its `.world` and `.hecksagon` files
-      # are named after.
-      #
-      # @param domain [String] the domain directory
-      # @return [Array<String>] such as `["quality_control"]`
-      def attached_stems(domain)
-        Dir.glob(File.join(domain, "bluebook", "*.hecksagon"))
-           .flat_map { |path| File.read(path).scan(/Chapters\.load!\(\s*"([^"]+)"\s*\)/).flatten }
-           .map { |name| Hecks::Naming.snake(name) }.uniq
       end
 
-      # @param world_file [String] the base `.world` file
       # @param domain [String] the domain directory
-      # @param environment [String, nil] the overlay to layer over the base
-      # @return [Object] the world's own declaration, named as the bluebook is
-      # @raise [SystemExit] when an overlay is missing or the file declares no world
-      def load_world(world_file, domain, environment)
-        registry = Hecks::Runtime::Registry.new
-        Hecks.with_registry(registry) do
-          Kernel.load(world_file)
-          if environment
-            overlay_file = File.join(domain, "bluebook", "environments", "#{environment}.world")
-            File.exist?(overlay_file) or
-              abort "#{overlay_file} does not exist — --environment=#{environment} needs that overlay"
-            Kernel.load(overlay_file)
-          end
-        end
-
-        registry.worlds.values.first or abort "#{world_file} declares no Hecks.world block at all"
-      end
-
-      # Applied before the stack's name is computed, so the output directory agrees with the stack
-      # name `Lambda`/`Fargate` generate: they re-apply this same override against the `world` and
-      # `tenant:` they are handed.
-      #
-      # @param deploy_settings [Hash] the world's `deployed_to` settings
       # @param options [Options] the flags
-      # @param domain_name [String] the domain directory's name
-      # @return [Hash] the settings, with the tenant appended to `stack_name` when there is one
-      def tenant_settings(deploy_settings, options, domain_name)
-        return deploy_settings unless options.tenant[:tenant]
-
-        base = deploy_settings[:stack_name] || domain_name
-        deploy_settings.merge(stack_name: "#{base}-#{options.tenant[:tenant]}")
-      end
-
-      # Loads the whole registry a domain boots with, not just its own `.bluebook`, because a
-      # cross-domain invoke grant can live in any attached chapter. A domain with no bluebook of
-      # its own (the QA ledger) gets its chapter from the hecksagon's `Chapters.load!`. `root:` is
-      # required or `attaches ... from: :vendor` refuses with "needs a registry with a root to
-      # vendor from".
-      #
-      # @param domain [String] the domain directory
-      # @param bluebook_basename [String] the file name the domain's bluebook and hecksagon share
-      # @return [Hecks::Runtime::Registry] the registry
-      def cross_domain_registry(domain, bluebook_basename)
-        registry = Hecks::Runtime::Registry.new(root: File.expand_path(domain))
-        lib_hecks = File.expand_path("..", __dir__)
-        Hecks.with_registry(registry) do
-          %w[ports/persistence.port ports/extraction.port adapters/driven/memory.adapter
-             adapters/driven/prism.adapter].each { |file| Kernel.load(File.join(lib_hecks, file)) }
-          bluebook_file = File.join(domain, "bluebook", "#{bluebook_basename}.bluebook")
-          Kernel.load(bluebook_file) if File.exist?(bluebook_file)
-          hecksagon_file = File.join(domain, "bluebook", "#{bluebook_basename}.hecksagon")
-          Kernel.load(hecksagon_file) if File.exist?(hecksagon_file)
-        end
-        registry
+      # @return [Deployment] the world, settings, registry and chapter the recipe is projected from
+      # @raise [SystemExit] when the domain or its `.world` cannot generate
+      def resolve(domain, options)
+        world_file = world_file_for(domain)
+        basename = File.basename(world_file, ".world")
+        world = load_world(world_file, domain, options.environment)
+        settings = tenant_settings(world.for_verb("deployed_to"), options, File.basename(domain))
+        registry = cross_domain_registry(domain, basename)
+        Deployment.new(domain, options, world_file, world, settings, settings[:stack_name] || File.basename(domain),
+                       registry, chapter_for(registry, world, world_file, basename))
       end
 
-      # Each adapter maps to a registered `Projector` export (`needs_world: true`); this only finds
-      # which one to call.
-      #
-      # @param deploy_settings [Hash] the world's `deployed_to` settings
-      # @param world_file [String] the `.world` file, named in the refusal
-      # @param domain [String] the domain directory, named in the refusal
-      # @return [Symbol] `:aws_lambda`, `:aws_fargate` or `:aws_box`
-      # @raise [SystemExit] with an example block when the world declares none of them
-      def target_key(deploy_settings, world_file, domain)
-        case deploy_settings[:adapter]
-        when "AwsLambda" then :aws_lambda
-        when "AwsFargate" then :aws_fargate
-        when "AwsBox" then :aws_box
-        else
-          abort <<~MSG
-            #{world_file} declares no deployed_to("AwsLambda"), deployed_to("AwsFargate") or deployed_to("AwsBox") block. Add one, e.g.:
-
-                deployed_to("AwsLambda") do
-                  region "us-east-1"
-                  memory 512
-                  timeout 10
-                end
-
-            or:
-
-                deployed_to("AwsFargate") do
-                  region "us-east-1"
-                  cpu 256
-                  memory 512
-                  port 8080
-                end
-
-            or:
-
-                deployed_to("AwsBox") do
-                  region "us-east-1"
-                  containers [{ name: "web", port: 8080 }]
-                end
-
-            then re-run hecks deploy project #{domain}.
-          MSG
-        end
+      # @return [Object] the chapter the world names
+      # @raise [SystemExit] when the registry holds none
+      def chapter_for(registry, world, world_file, bluebook_basename)
+        registry.bluebook(world.domain) or
+          abort "#{world_file} declares no #{world.domain} chapter — #{bluebook_basename}.bluebook's own " \
+                "Hecks.bluebook name has to match world.domain."
       end
 
       # `Lambda` and `Fargate` raise `ArgumentError` for a domain's own deploy conflicts; it is
       # caught here so the message reaches stderr with a failing exit code instead of a backtrace.
       #
       # @param target [Symbol] the projector export
-      # @param chapter [Object] the domain's chapter
-      # @param world [Object] the domain's world
-      # @param registry [Hecks::Runtime::Registry] the registry the chapter came from
-      # @param context [Hash] `deploy_settings`, `infra_name`, `options`, `domain`, `root` and
-      #   `world_file`
+      # @param deployment [Deployment] what the generator resolved about the domain
+      # @param root [String] the checkout
       # @return [Hash{String => String}] the files to write
       # @raise [SystemExit] when the domain's own settings conflict
-      def project(target, chapter, world, registry, **context)
-        artifact = Hecks::Projector.call(
-          target,
-          bluebook: chapter,
-          options:  {
-            tenant:                context[:options].tenant,
-            domain_dir:            context[:domain],
-            root:                  context[:root],
-            world_file:            context[:world_file],
-            cross_domain_registry: registry
-          },
-          world:    world
-        )
+      def project(target, deployment, root)
+        artifact = Hecks::Projector.call(target, bluebook: deployment.chapter,
+                                                 options: projector_options(deployment, root), world: deployment.world)
         # Only when the domain declared `smoke true`; otherwise nothing is added.
-        artifact.merge(Hecks::Projections::Deploy::Smoke.files(context[:deploy_settings],
-                                                               stack_name: context[:infra_name]))
+        artifact.merge(Hecks::Projections::Deploy::Smoke.files(deployment.settings, stack_name: deployment.infra_name))
       rescue ArgumentError => e
         abort e.message
       end
 
+      def projector_options(deployment, root)
+        {
+          tenant:                deployment.options.tenant,
+          domain_dir:            deployment.domain,
+          root:                  root,
+          world_file:            deployment.world_file,
+          cross_domain_registry: deployment.registry
+        }
+      end
+
       # Writes the files, and prints where the recipe deploys from.
       #
       # @param artifact [Hash{String => String}] the files to write
       # @param out_dir [String] where they go
       # @return [void]
       def write(artifact, out_dir)
-        written = Hecks::Projector.write(artifact, out_dir, as: :files)
-        written.each { |path| File.chmod(0o755, path) if path.end_with?(".sh") }
-
-        written.each { |path| puts "wrote #{path}" }
+        Hecks::Projector.write(artifact, out_dir, as: :files).each do |path|
+          File.chmod(0o755, path) if path.end_with?(".sh")
+          puts "wrote #{path}"
+        end
         puts
         puts "deploy from #{out_dir} — one command, nothing to type, nothing to remember:"
         puts "    make deploy"

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