hecks 2.9.0 → 3.0.1

data/lib/hecks/tools/corpus_report.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require_relative "../tools"
+require_relative "../corpus"
+
+module Hecks
+  module Tools
+    # Prints the Rust-facing corpus from `Hecks::Corpus`, for CI steps and for asking what CI walks.
+    # Takes one flag (`hecks corpus_rust_coverage <flag>`):
+    #
+    #   --rust-domains      feature and path of every in-repo domain with a Cargo feature
+    #   --rust-regen-order  paths `hecks regenerate_corpus` regenerates, in order
+    #   --rust-coverage     run the coverage tool over every generated module; a
+    #                       Corpus::RUST_COVERAGE_PENDING module must still fail,
+    #                       every other one must pass
+    module CorpusReport
+      USAGE = "usage: hecks corpus_rust_coverage --rust-domains | --rust-regen-order | --rust-coverage"
+
+      module_function
+
+      # Prints the report the first argument asks for.
+      #
+      # @param argv [Array<String>] one of the three flags
+      # @param root [String] the checkout
+      # @return [Integer] 0, or 1 when a coverage check does not come out as it must
+      # @raise [SystemExit] with the usage line when the flag is unknown
+      def main(argv, root: Tools::ROOT)
+        case argv.first
+        when "--rust-domains"
+          Hecks::Corpus.rust_domains.each { |domain| puts "#{domain.feature}\t#{relative(domain.dir, root)}" }
+          0
+        when "--rust-regen-order"
+          Hecks::Corpus.rust_regen_order.each { |domain| puts relative(domain.dir, root) }
+          0
+        when "--rust-coverage" then rust_coverage
+        else abort USAGE
+        end
+      end
+
+      # @param path [String] an absolute path
+      # @param root [String] the checkout
+      # @return [String] the path relative to `root`
+      def relative(path, root) = path.delete_prefix("#{root}/")
+
+      # Runs the coverage tool for each module in this process.
+      #
+      # @param modules [Array<String>] the generated modules
+      # @return [Hash{String => Array}] each module's `[passed, output]`
+      def coverage_results(modules)
+        require_relative "../rust_build"
+        modules.to_h do |name|
+          result = Hecks::RustBuild.capture("rust_coverage", [name])
+          [name, [result.ok?, result.out + result.err]]
+        end
+      end
+
+      # @return [Integer] 0 when every module is as it must be, 1 otherwise
+      # @raise [SystemExit] when `RUST_COVERAGE_PENDING` names a module that does not exist
+      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
+
+        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
+
+        return puts("hecks corpus_rust_coverage: #{modules.size} generated modules checked").then { 0 } if problems.empty?
+
+        warn problems.join("\n\n")
+        1
+      end
+    end
+  end
+end

data/lib/hecks/tools/deploy_recipe.rb

@@ -0,0 +1,255 @@
+# frozen_string_literal: true
+
+require "hecks"
+require "fileutils"
+require "optparse"
+require_relative "../tools"
+
+module Hecks
+  module Tools
+    # The AWS deployment generator (ADR 0018): resolves a domain's declared `deployed_to(...)`
+    # target and dispatches to the matching `Projector` export, writing the recipe (template,
+    # scripts and Makefile) under `deploy/<stack>/` of the checkout.
+    #
+    #   hecks deploy project <domain> [--tenant=<slug>] [--schema=<name>]
+    #       [--out=<dir>] [--environment=<name>]
+    #
+    # `--environment` layers an overlay `.world` file over the base one; a missing overlay is an
+    # error. `--out` writes the recipe elsewhere, for a domain in a client's repo. `--tenant` and
+    # `--schema` override the stack for shared-database hosting: `stack_name` is appended to, so
+    # re-running with the same `--tenant` regenerates the same stack.
+    module DeployRecipe
+      USAGE = "usage: hecks deploy project <domain> [--tenant=<slug>] [--schema=<name>] " \
+              "[--out=<dir>] [--environment=<name>]"
+
+      # What the flags asked for.
+      Options = Struct.new(:tenant, :out, :environment)
+
+      module_function
+
+      # Generates the recipe and prints each file written.
+      #
+      # @param argv [Array<String>] the domain directory, then the flags
+      # @param root [String] the checkout whose `deploy/` receives the recipe unless `--out` says
+      #   otherwise
+      # @return [Integer] 0
+      # @raise [SystemExit] with the reason on stderr when the domain or its `.world` cannot
+      #   generate
+      def main(argv, root: Tools::ROOT)
+        argv = argv.dup
+        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)
+        0
+      end
+
+      # @param argv [Array<String>] the arguments; the flags are removed from it
+      # @return [Options] the flags, with `tenant` a hash of `tenant` and `schema`
+      # @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)
+
+        if options.tenant[:schema] && !options.tenant[:tenant]
+          abort "--schema needs --tenant=<slug> — a schema override with no tenant to scope it to is meaningless"
+        end
+        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
+        end
+
+        File.exist?(world_file) or
+          abort "#{world_file} does not exist — a domain needs a .world file to declare " \
+                "deployed_to(\"AwsLambda\") or deployed_to(\"AwsFargate\")"
+        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 `uses_embryonaut_bluebook` 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
+      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` or `:aws_fargate`
+      # @raise [SystemExit] with an example block when the world declares neither
+      def target_key(deploy_settings, world_file, domain)
+        case deploy_settings[:adapter]
+        when "AwsLambda" then :aws_lambda
+        when "AwsFargate" then :aws_fargate
+        else
+          abort <<~MSG
+            #{world_file} declares no deployed_to("AwsLambda") or deployed_to("AwsFargate") 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
+
+            then re-run hecks deploy project #{domain}.
+          MSG
+        end
+      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`
+      # @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
+        )
+        # 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]))
+      rescue ArgumentError => e
+        abort e.message
+      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| puts "wrote #{path}" }
+        puts
+        puts "deploy from #{out_dir} — one command, nothing to type, nothing to remember:"
+        puts "    make deploy"
+      end
+    end
+  end
+end

data/lib/hecks/tools/deploy_recipe_lint.rb

@@ -0,0 +1,282 @@
+# frozen_string_literal: true
+
+require "tmpdir"
+require "fileutils"
+require "hecks"
+require_relative "../tools"
+require_relative "deploy_recipe"
+require_relative "../hecks/adapters/console_capture"
+
+module Hecks
+  module Tools
+    # Lints generated deploy Makefiles for prod-touching recipes that hide failure.
+    module DeployRecipeLint
+      # Commands that touch AWS or a real Postgres; `sam build` is excluded because it stays local.
+      RISKY_REGEX = /\baws\s+(?:cloudformation|ssm|secretsmanager|lambda|ec2)\b|\bpsql\b|DATABASE_URL=|\bsam\s+deploy\b/
+
+      # Deliberately loose: any real statement with "echo" counts, since only a missing step
+      # matters.
+      ECHO_REGEX = /\becho\b/
+
+      # An unconditional `exit 0` statement; `command && exit 0` is one statement and never matches.
+      BARE_EXIT_ZERO_REGEX = /\Aexit\s+0\s*\z/
+
+      # `exit $?` is only sound right after the command it reports on; an `@echo` in between
+      # resets it.
+      DOLLAR_QUESTION_EXIT_REGEX = /\Aexit\s+\$\$?\?\s*\z/
+
+      # Print-only or no-op statements, never the command a nearby `exit $?` reports on.
+      BENIGN_REGEX = /\A(?:@)?(?:echo\b|:\s*\z)/
+
+      Violation = Struct.new(:source, :target, :line, :rule, :message, keyword_init: true) do
+        def to_s
+          "#{source}:#{line}: [#{rule}] target #{target.inspect} — #{message}"
+        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
+
+      # 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
+
+      # Runs all three checks over every target; `source` labels each violation.
+      def lint(text, source:)
+        targets = parse_targets(text)
+        violations = targets.flat_map do |name, recipe_lines|
+          chains = shell_chains(recipe_lines)
+          check_blind_exit_zero(name, chains) +
+            check_stale_dollar_question(name, chains) +
+            check_prod_touch_without_echo(name, recipe_lines)
+        end
+        violations.each { |v| v.source = source }
+        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`
+      # @param root [String] the checkout the fixtures are generated into
+      # @return [Integer] 0 when clean, 1 when a violation was found
+      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)
+        ensure
+          generated_dirs.each { |dir| FileUtils.rm_rf(dir) }
+        end
+      end
+
+      # @return [Integer] 0, after printing the usage
+      def usage
+        puts "usage: hecks deploy lint [Makefile ...]"
+        puts "  no args: generates 3 representative fixture domains (own/shared/oauth)"
+        puts "           via the real deploy generator, lints each one's Makefile"
+        puts "  with args: lints the given Makefile(s) directly (e.g. deploy/<domain>/Makefile)"
+        0
+      end
+
+      # @param violations [Array<Violation>] what the lint found
+      # @return [Integer] 0 when there are none, 1 after printing them to stderr
+      def report(violations)
+        if violations.empty?
+          puts "hecks deploy lint: no violations found."
+          return 0
+        end
+
+        warn "hecks deploy lint: #{violations.size} violation(s) found:\n\n"
+        violations.each { |v| warn "  #{v}\n" }
+        1
+      end
+    end
+  end
+end