hecks 3.4.2 → 3.6.0

data/lib/hecks/quality_control/cli/qa_discover_external_domains/scanning.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+
+module Hecks
+  module QualityControlCli
+    class QaDiscoverExternalDomains
+      # What `target.discover_external_domains` reads from disk: the sibling repos, the
+      # bluebook-shaped directories inside them, whether each depends on the hecks gem, and the
+      # ledger's known targets.
+      module Scanning
+        private
+
+        def depends_on_hecks?(dir)
+          gemfile = File.join(dir, "Gemfile")
+          lockfile = File.join(dir, "Gemfile.lock")
+
+          (File.file?(gemfile) && File.read(gemfile).match?(GEMFILE_PATTERN)) ||
+            (File.file?(lockfile) && File.read(lockfile).match?(GEMFILE_LOCK_PATTERN))
+        end
+
+        # A monorepo's real hecks-dependent Ruby app can live below the sibling repo's own top
+        # level (a nested `Gemfile` there, not one at `repo_root`). Checked against the candidate's
+        # own directory first, then each ancestor up to and including `repo_root`, so the common
+        # case, the dependency declared at `repo_root` itself, still answers exactly as it always
+        # has.
+        def depends_on_hecks_anywhere_above?(entity_dir, repo_root)
+          root = File.expand_path(repo_root)
+          dir = File.expand_path(entity_dir)
+          loop do
+            return true if depends_on_hecks?(dir)
+            return false if dir == root
+
+            parent = File.dirname(dir)
+            return false if parent == dir # filesystem root reached without finding repo_root
+
+            dir = parent
+          end
+        end
+
+        # `repo_root` itself is depth 0, so a project that is one domain at its own top can be a
+        # candidate too.
+        def bluebook_shaped_dirs(repo_root, max_depth)
+          found = []
+          collect_entity_dirs(repo_root, 0, max_depth, found)
+          found
+        end
+
+        def collect_entity_dirs(dir, depth, max_depth, found)
+          entity_name = File.basename(dir)
+          found << [dir, entity_name] if File.file?(File.join(dir, "bluebook", "#{entity_name}.bluebook"))
+          return if depth >= max_depth
+
+          descendable_children(dir).each { |path| collect_entity_dirs(path, depth + 1, max_depth, found) }
+        end
+
+        # The bluebook/ directory itself is never an entity dir.
+        def descendable_children(dir)
+          children_of(dir).filter_map do |child|
+            next if SKIP_DIR_BASENAMES.include?(child) || child == "bluebook"
+
+            path = File.join(dir, child)
+            path if real_directory?(path)
+          end
+        end
+
+        def real_directory?(path)
+          File.directory?(path) && !File.symlink?(path)
+        end
+
+        def children_of(dir)
+          Dir.children(dir).sort
+        rescue Errno::EACCES, Errno::ENOENT
+          []
+        end
+
+        # Shells out rather than booting the ledger in-process, so this is safe to run alongside a
+        # live qa_tick or qa_sweep.
+        def ledger_target_paths
+          out, err, status = Open3.capture3("bundle", "exec", "ruby", File.join(@root, "exe/hecks"),
+                                            "run", "qa/bluebook", "ask", "target.all", chdir: @root)
+          unless status.success?
+            raise Refused, "hecks quality_control discover_external_domains: could not read the ledger's targets " \
+                           "(hecks run qa/bluebook ask target.all exited #{status.exitstatus}):\n#{err}\n" \
+                           "pass --known-path <path> ... to run without the ledger", usage: false
+          end
+
+          JSON.parse(out).filter_map { |row| row.dig("path", "value") }
+        end
+
+        # The sibling directories under `projects_dir`, leaving out this repo (already fully covered
+        # by existing seeding) and symlinks.
+        def sibling_repos(projects_dir)
+          root = checkout_root
+          Dir.children(projects_dir).sort.filter_map do |child|
+            next if child == "hecks"
+
+            path = File.join(projects_dir, child)
+            path if real_directory?(path) && !same_checkout?(path, root)
+          end
+        end
+
+        def checkout_root
+          File.realpath(@root)
+        rescue Errno::ENOENT
+          @root
+        end
+
+        # A path that vanished mid-scan counts as the checkout, so it is skipped.
+        def same_checkout?(path, root)
+          File.realpath(path) == root
+        rescue Errno::ENOENT
+          true
+        end
+      end
+    end
+  end
+end

data/lib/hecks/quality_control/cli/qa_discover_external_domains.rb

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
-require "json"
-require "open3"
+require_relative "qa_discover_external_domains/parsing"
+require_relative "qa_discover_external_domains/scanning"
+require_relative "qa_discover_external_domains/reporting"
 
 module Hecks
   module QualityControlCli
@@ -15,6 +16,10 @@ module Hecks
     #   hecks quality_control target.discover_external_domains --known-path <path> ...   # bypass
     # the ledger read
     class QaDiscoverExternalDomains
+      include Parsing
+      include Scanning
+      include Reporting
+
       USAGE = "usage: hecks quality_control discover_external_domains [--projects-dir <path>] " \
               "[--max-depth N] [--known-path <path> ...]"
 
@@ -75,172 +80,40 @@ module Hecks
 
       private
 
-      def parse(argv)
-        options = { projects_dir: DEFAULT_PROJECTS_DIR, max_depth: DEFAULT_MAX_DEPTH, known_paths: nil }
-        until argv.empty?
-          case (arg = argv.shift)
-          when "-h", "--help"
-            puts USAGE
-            return :help
-          when "--projects-dir"
-            refuse!("--projects-dir needs a path") if argv.empty?
-            options[:projects_dir] = File.expand_path(argv.shift)
-          when "--max-depth"
-            refuse!("--max-depth needs a number") if argv.empty?
-            options[:max_depth] = Integer(argv.shift)
-          when "--known-path"
-            refuse!("--known-path needs a path") if argv.empty?
-            (options[:known_paths] ||= []) << File.expand_path(argv.shift)
-          else
-            refuse!("unexpected argument #{arg.inspect}")
-          end
-        end
-        refuse!("--max-depth must be >= 0") if options[:max_depth].negative?
-        refuse!("#{options[:projects_dir]} is not a directory") unless File.directory?(options[:projects_dir])
-        options
-      end
-
-      def refuse!(message)
-        raise Refused, message
-      end
-
-      def depends_on_hecks?(dir)
-        gemfile = File.join(dir, "Gemfile")
-        lockfile = File.join(dir, "Gemfile.lock")
-
-        (File.file?(gemfile) && File.read(gemfile).match?(GEMFILE_PATTERN)) ||
-          (File.file?(lockfile) && File.read(lockfile).match?(GEMFILE_LOCK_PATTERN))
-      end
-
-      # A monorepo's real hecks-dependent Ruby app can live below the sibling repo's own top level
-      # (a nested `Gemfile` there, not one at `repo_root`). Checked against the candidate's own
-      # directory first, then each ancestor up to and including `repo_root`, so the common case, the
-      # dependency declared at `repo_root` itself, still answers exactly as it always has.
-      def depends_on_hecks_anywhere_above?(entity_dir, repo_root)
-        root = File.expand_path(repo_root)
-        dir = File.expand_path(entity_dir)
-        loop do
-          return true if depends_on_hecks?(dir)
-          return false if dir == root
-
-          parent = File.dirname(dir)
-          return false if parent == dir # filesystem root reached without finding repo_root
-
-          dir = parent
-        end
-      end
-
-      # `repo_root` itself is depth 0, so a project that is one domain at its own top can be a
-      # candidate too.
-      def bluebook_shaped_dirs(repo_root, max_depth)
-        found = []
-        walk = lambda do |dir, depth|
-          entity_name = File.basename(dir)
-          found << [dir, entity_name] if File.file?(File.join(dir, "bluebook", "#{entity_name}.bluebook"))
-          return if depth >= max_depth
-
-          children_of(dir).each do |child|
-            next if SKIP_DIR_BASENAMES.include?(child)
-
-            child_path = File.join(dir, child)
-            next unless File.directory?(child_path) && !File.symlink?(child_path)
-            next if child == "bluebook" # the bluebook/ directory itself is never an entity dir
-
-            walk.call(child_path, depth + 1)
-          end
-        end
-        walk.call(repo_root, 0)
-        found
-      end
-
-      def children_of(dir)
-        Dir.children(dir).sort
-      rescue Errno::EACCES, Errno::ENOENT
-        []
-      end
-
-      # Shells out rather than booting the ledger in-process, so this is safe to run alongside a
-      # live qa_tick or qa_sweep.
-      def ledger_target_paths
-        out, err, status = Open3.capture3("bundle", "exec", "ruby", File.join(@root, "exe/hecks"),
-                                          "run", "qa/bluebook", "ask", "target.all", chdir: @root)
-        unless status.success?
-          raise Refused, "hecks quality_control discover_external_domains: could not read the ledger's targets " \
-                         "(hecks run qa/bluebook ask target.all exited #{status.exitstatus}):\n#{err}\n" \
-                         "pass --known-path <path> ... to run without the ledger", usage: false
-        end
-
-        JSON.parse(out).filter_map { |row| row.dig("path", "value") }
-      end
-
-      def sibling_repos(projects_dir)
-        hecks_root = begin
-          File.realpath(@root)
-        rescue Errno::ENOENT
-          @root
-        end
-        Dir.children(projects_dir).sort.filter_map do |child|
-          next if child == "hecks" # this repo, already fully covered by existing seeding
-
-          path = File.join(projects_dir, child)
-          next unless File.directory?(path) && !File.symlink?(path)
-
-          begin
-            next if File.realpath(path) == hecks_root
-          rescue Errno::ENOENT
-            next
-          end
-
-          path
-        end
-      end
-
       # @return [Array(Array<Hash>, Array<String>, Array<String>)] the candidates, the siblings
       #   with no hecks dependency, and every sibling scanned
       def discover(options)
-        known_raw = options[:known_paths] || ledger_target_paths
-        # Ledger paths may be stored root-relative or absolute; normalize both to compare.
-        known = known_raw.to_set { |path| path.start_with?("/") ? File.expand_path(path) : File.expand_path(path, @root) }
+        known = known_path_set(options)
         siblings = sibling_repos(options[:projects_dir])
         candidates = []
         skipped = []
         siblings.each do |repo_path|
-          found = false
-          bluebook_shaped_dirs(repo_path, options[:max_depth]).each do |entity_dir, entity_name|
-            next unless depends_on_hecks_anywhere_above?(entity_dir, repo_path)
-
-            found = true
-            absolute = File.expand_path(entity_dir)
-            next if known.include?(absolute)
-
-            repo_name = File.basename(repo_path)
-            candidates << { repo: repo_name, reference: "#{repo_name}/#{entity_name}", path: absolute }
-          end
-          skipped << repo_path unless found
+          entities = hecks_entities(repo_path, options[:max_depth])
+          skipped << repo_path if entities.empty?
+          candidates.concat(unenrolled(repo_path, entities, known))
         end
         [candidates.sort_by { |c| [c[:repo], c[:reference]] }, skipped, siblings]
       end
 
-      def report(options, candidates, skipped, siblings)
-        puts "scanned #{siblings.size} sibling(s) under #{options[:projects_dir]} " \
-             "(max depth #{options[:max_depth]}), #{siblings.size - skipped.size} depend on the hecks gem"
-        puts "no hecks dependency, skipped: #{skipped.map { |p| File.basename(p) }.join(', ')}" unless skipped.empty?
-        puts
-        if candidates.empty?
-          puts "no new candidates — every hecks-dependent sibling's bluebook-shaped domain is either " \
-               "already a Target or none was found in the shape <name>/bluebook/<name>.bluebook within " \
-               "--max-depth #{options[:max_depth]}."
-          return
+      # Ledger paths may be stored root-relative or absolute; normalize both to compare.
+      def known_path_set(options)
+        known_raw = options[:known_paths] || ledger_target_paths
+        known_raw.to_set { |path| File.expand_path(path, @root) }
+      end
+
+      def hecks_entities(repo_path, max_depth)
+        bluebook_shaped_dirs(repo_path, max_depth).select do |entity_dir, _entity_name|
+          depends_on_hecks_anywhere_above?(entity_dir, repo_path)
         end
+      end
+
+      def unenrolled(repo_path, entities, known)
+        repo_name = File.basename(repo_path)
+        entities.filter_map do |entity_dir, entity_name|
+          absolute = File.expand_path(entity_dir)
+          next if known.include?(absolute)
 
-        puts "#{candidates.size} candidate(s) — report only, nothing identified. Review each, then run " \
-             "the command yourself to enroll it:"
-        puts
-        candidates.each do |c|
-          puts "  #{c[:reference]}"
-          puts "    path: #{c[:path]}"
-          puts "    enroll: hecks run qa/bluebook identify reference=#{c[:reference]} path=#{c[:path]}"
-          puts
+          { repo: repo_name, reference: "#{repo_name}/#{entity_name}", path: absolute }
         end
       end
     end

data/lib/hecks/quality_control/cli/qa_domain_novelty/verdict.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Hecks
+  module QualityControlCli
+    class QaDomainNovelty
+      # The comparison `target.judge_novelty` ends in: the candidate's form pairs against the pairs
+      # the existing targets already meet, printed, and the exit status that follows.
+      module Verdict
+        # Why an empty result is a question about the census, not a verdict on the domain.
+        READ_AS_QUESTION = "READ THAT AS A QUESTION ABOUT THE CENSUS, NOT A VERDICT ON THE DOMAIN. This gate " \
+                           "measures ONE AGGREGATE's own declared forms, so a domain whose point is a " \
+                           "chapter-level construct — a policy, an `across` target, a process manager, a " \
+                           "read model's own group_by/median, an outbox, a dry run — is invisible to it by " \
+                           "construction, not by omission. `corrects` and `role_gated` were exactly that: " \
+                           "declared all over the corpus, unnamed here, so this line told three stress " \
+                           "domains built around retroactive correction that they were redundant (their own " \
+                           "NOTES.md each say so). If that is your domain's case, say which construct it " \
+                           "exists for in its NOTES.md and keep it."
+
+        private
+
+        def judge(candidate, present, existing_source)
+          census = Hecks::Fuzzing::FormCensus.census(normalize(candidate))
+          mine = Hecks::Fuzzing::FormCensus.covered_pairs(census)
+          theirs = pairs_met_by(present)
+          puts candidate_header(candidate, census, mine), against_header(present, existing_source, theirs)
+          puts
+          new_pairs = mine.reject { |pair, _| theirs.key?(pair) }
+          return nothing_new(candidate) if new_pairs.empty?
+
+          print_new_pairs(candidate, new_pairs)
+          EXIT_NOVEL
+        end
+
+        def pairs_met_by(present)
+          present.each_with_object(Hash.new { |h, k| h[k] = [] }) do |path, covered|
+            Hecks::Fuzzing::FormCensus.covered_pairs(Hecks::Fuzzing::FormCensus.census(path)).each do |pair, names|
+              covered[pair].concat(names.map { |name| "#{name} (#{path.delete_prefix("#{@root}/")})" })
+            end
+          end
+        end
+
+        def candidate_header(candidate, census, pairs)
+          "candidate: #{candidate} — #{census.size} aggregate(s), #{pairs.size} form pair(s) met"
+        end
+
+        def against_header(present, existing_source, pairs)
+          "against:   #{present.size} domain(s) from #{existing_source}, " \
+            "#{pairs.size} form pair(s) met between them"
+        end
+
+        def print_new_pairs(candidate, new_pairs)
+          width = new_pairs.keys.map(&:size).max
+          puts "new pair(s) — met on one aggregate here, on none of the existing targets:"
+          new_pairs.sort.each { |pair, names| puts "  #{pair.ljust(width)}  #{names.uniq.join(", ")}" }
+          puts
+          puts "#{new_pairs.size} new pair(s) — #{candidate} earns its place."
+        end
+
+        def nothing_new(candidate)
+          puts no_new_pair_line(candidate)
+          puts
+          puts READ_AS_QUESTION
+          EXIT_NOTHING
+        end
+
+        def no_new_pair_line(candidate)
+          "no new pair — every pair of forms #{candidate} puts together on one aggregate is already met " \
+            "by an existing target. Either the domain is not new, or the form it exists for is not yet " \
+            "named in Hecks::Fuzzing::FormCensus::FORMS (lib/hecks/fuzzing/form_census.rb) — name it " \
+            "there first, citing the gap it is one step from, and run this again."
+        end
+      end
+    end
+  end
+end

data/lib/hecks/quality_control/cli/qa_domain_novelty.rb

@@ -4,6 +4,7 @@ require "json"
 require "open3"
 require_relative "../../../hecks"
 require_relative "../../fuzzing/form_census"
+require_relative "qa_domain_novelty/verdict"
 
 module Hecks
   module QualityControlCli
@@ -19,6 +20,8 @@ module Hecks
     #
     # Exit codes: 0 new pair found; 1 no new pair; 2 usage or wrong path shape.
     class QaDomainNovelty
+      include Verdict
+
       EXIT_NOVEL = 0
       EXIT_NOTHING = 1
       EXIT_USAGE = 2
@@ -45,14 +48,7 @@ module Hecks
       def call(argv)
         candidate, against = parse(argv)
         refuse_unless_stress_domain_shaped!(normalize(candidate))
-        existing_source = against.empty? ? "the ledger's Target.path rows" : "--against"
-        existing = (against.empty? ? ledger_target_paths : against).map { |path| normalize(path) }.uniq
-        own = existing.select { |path| path == normalize(candidate) }
-        existing -= own
-        puts "note: #{candidate} is already a target — left out of the comparison" unless own.empty?
-
-        missing, present = existing.partition { |path| Hecks::Fuzzing::FormCensus.bluebook_files(path).nil? }
-        missing.each { |path| warn "skipping #{path}: no bluebook/*.bluebook on disk" }
+        present, existing_source = comparison_set(candidate, against)
         judge(candidate, present, existing_source)
       rescue UsageError => e
         warn e.message
@@ -70,25 +66,37 @@ module Hecks
       # Raised once the reason has been printed; it ends the run with `EXIT_USAGE`.
       class Stopped < StandardError; end
 
+      # The domains to compare against that exist on disk, and where they came from.
+      def comparison_set(candidate, against)
+        existing_source = against.empty? ? "the ledger's Target.path rows" : "--against"
+        existing = (against.empty? ? ledger_target_paths : against).map { |path| normalize(path) }.uniq
+        [present_domains(candidate, existing), existing_source]
+      end
+
+      def present_domains(candidate, existing)
+        own = existing.select { |path| path == normalize(candidate) }
+        puts "note: #{candidate} is already a target — left out of the comparison" unless own.empty?
+
+        missing, present = (existing - own).partition { |path| Hecks::Fuzzing::FormCensus.bluebook_files(path).nil? }
+        missing.each { |path| warn "skipping #{path}: no bluebook/*.bluebook on disk" }
+        present
+      end
+
       def parse(argv)
-        candidate = nil
-        against = []
-        mode = :candidate
-        argv.each do |arg|
-          if arg == "--against"
-            mode = :against
-          elsif mode == :against
-            against << arg
-          elsif candidate.nil?
-            candidate = arg
-          else
-            raise UsageError, "unexpected argument #{arg.inspect}"
-          end
-        end
-        raise UsageError, "no candidate domain given" if candidate.nil?
-        raise UsageError, "--against needs at least one path" if mode == :against && against.empty?
+        before, against = split_at_against(argv)
+        raise UsageError, "unexpected argument #{before[1].inspect}" if before.size > 1
+        raise UsageError, "no candidate domain given" if before.empty?
+        raise UsageError, "--against needs at least one path" if against == []
 
-        [candidate, against]
+        [before.first, against || []]
+      end
+
+      # The arguments before the first `--against`, and the paths after it (nil without the flag).
+      def split_at_against(argv)
+        split = argv.index("--against")
+        return [argv, nil] unless split
+
+        [argv.first(split), argv.drop(split + 1).reject { |arg| arg == "--against" }]
       end
 
       # `hecks project_rust` reads exactly `<name>/bluebook/<name>.bluebook`, so refuse anything
@@ -117,47 +125,6 @@ module Hecks
       end
 
       def normalize(path) = File.expand_path(path, @root)
-
-      def judge(candidate, present, existing_source)
-        census = Hecks::Fuzzing::FormCensus.census(normalize(candidate))
-        candidate_pairs = Hecks::Fuzzing::FormCensus.covered_pairs(census)
-        existing_pairs = present.each_with_object(Hash.new { |h, k| h[k] = [] }) do |path, covered|
-          Hecks::Fuzzing::FormCensus.covered_pairs(Hecks::Fuzzing::FormCensus.census(path)).each do |pair, names|
-            covered[pair].concat(names.map { |name| "#{name} (#{path.delete_prefix("#{@root}/")})" })
-          end
-        end
-        new_pairs = candidate_pairs.reject { |pair, _| existing_pairs.key?(pair) }
-
-        puts "candidate: #{candidate} — #{census.size} aggregate(s), #{candidate_pairs.size} form pair(s) met"
-        puts "against:   #{present.size} domain(s) from #{existing_source}, " \
-             "#{existing_pairs.size} form pair(s) met between them"
-        puts
-        return nothing_new(candidate) if new_pairs.empty?
-
-        width = new_pairs.keys.map(&:size).max
-        puts "new pair(s) — met on one aggregate here, on none of the existing targets:"
-        new_pairs.sort.each { |pair, names| puts "  #{pair.ljust(width)}  #{names.uniq.join(', ')}" }
-        puts
-        puts "#{new_pairs.size} new pair(s) — #{candidate} earns its place."
-        EXIT_NOVEL
-      end
-
-      def nothing_new(candidate)
-        puts "no new pair — every pair of forms #{candidate} puts together on one aggregate is already met " \
-             "by an existing target. Either the domain is not new, or the form it exists for is not yet " \
-             "named in Hecks::Fuzzing::FormCensus::FORMS (lib/hecks/fuzzing/form_census.rb) — name it " \
-             "there first, citing the gap it is one step from, and run this again."
-        puts
-        puts "READ THAT AS A QUESTION ABOUT THE CENSUS, NOT A VERDICT ON THE DOMAIN. This gate measures " \
-             "ONE AGGREGATE's own declared forms, so a domain whose point is a chapter-level construct — " \
-             "a policy, an `across` target, a process manager, a read model's own group_by/median, an " \
-             "outbox, a dry run — is invisible to it by construction, not by omission. `corrects` and " \
-             "`role_gated` were exactly that: declared all over the corpus, unnamed here, so this line " \
-             "told three stress domains built around retroactive correction that they were redundant " \
-             "(their own NOTES.md each say so). If that is your domain's case, say which construct it " \
-             "exists for in its NOTES.md and keep it."
-        EXIT_NOTHING
-      end
     end
   end
 end

data/lib/hecks/quality_control/cli/qa_generated_domains/arguments.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Hecks
+  module QualityControlCli
+    class QaGeneratedDomains
+      # The command line of `target.check_generated_domains`: flags into an options hash.
+      module Arguments
+        # Each flag that takes a value: the option it sets and how the value is read.
+        VALUE_FLAGS = {
+          "--domains" => [:domains, ->(v) { Integer(v) }], "--start" => [:start, ->(v) { Integer(v) }],
+          "--forms" => [:forms, ->(v) { v.split(",") }], "--seeds" => [:seeds, ->(v) { Integer(v) }],
+          "--steps" => [:steps, ->(v) { Integer(v) }], "--adversarial" => [:adversarial, ->(v) { Float(v) }],
+          "--shrink-budget" => [:shrink_budget, ->(v) { Integer(v) }],
+          "--domain-shrink-budget" => [:domain_shrink_budget, ->(v) { Integer(v) }],
+          "--check" => [:check, :itself.to_proc], "--binary" => [:binary, :itself.to_proc],
+          "--match" => [:match, ->(v) { JSON.parse(v) }], "--promote" => [:promote, :itself.to_proc],
+          "--name" => [:name, :itself.to_proc], "--blueprint" => [:blueprint, :itself.to_proc]
+        }.freeze
+
+        # Each flag that stands alone, and the option it turns on.
+        SWITCH_FLAGS = { "--rust" => :rust, "--from-dials" => :from_dials }.freeze
+
+        private
+
+        # @param argv [Array<String>] consumed as it is read
+        # @return [Hash, Symbol] the options, or `:help` after the usage line was printed
+        # @raise [SystemExit] on an unknown flag
+        def parse(argv)
+          options = default_options
+          until argv.empty?
+            arg = argv.shift
+            if %w[-h --help].include?(arg)
+              puts USAGE
+              return :help
+            end
+            parse_flag(options, arg, argv)
+          end
+          options
+        end
+
+        def default_options
+          { domains: 3, start: nil, forms: nil, seeds: 5, steps: 25, adversarial: 0.3, rust: false,
+            shrink_budget: 200, domain_shrink_budget: 40, check: nil, binary: nil, match: nil,
+            promote: nil, name: nil, sources: [] }
+        end
+
+        def parse_flag(options, arg, argv)
+          if VALUE_FLAGS.key?(arg)
+            key, reader = VALUE_FLAGS.fetch(arg)
+            options[key] = reader.call(argv.shift)
+          elsif SWITCH_FLAGS.key?(arg)
+            options[SWITCH_FLAGS.fetch(arg)] = true
+          elsif arg == "--source"
+            options[:sources] << argv.shift
+          else
+            abort "#{USAGE}\nunexpected argument: #{arg.inspect}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/quality_control/cli/qa_generated_domains/blueprints.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Hecks
+  module QualityControlCli
+    class QaGeneratedDomains
+      # Where the blueprints of a run come from: a saved one, bluebooks written elsewhere, or the
+      # generator.
+      module Blueprints
+        private
+
+        def blueprints(start)
+          return saved_blueprint(start) if @options[:blueprint]
+          return source_blueprints(start) if @options[:sources].any?
+
+          generated_blueprints(start)
+        end
+
+        def saved_blueprint(start)
+          saved = JSON.parse(File.read(@options[:blueprint]))
+          { saved.fetch("seed", start) => saved }
+        end
+
+        def source_blueprints(start)
+          @options[:sources].each_with_index.to_h { |file, index| [start + index, source_blueprint(file, start + index)] }
+        end
+
+        def generated_blueprints(start)
+          (start...(start + @options[:domains])).to_h do |seed|
+            [seed, Generator.generate(seed: seed, forms: @options[:forms])]
+          end
+        end
+
+        def source_blueprint(file, seed)
+          abort "no bluebook at #{file}" unless File.file?(file)
+
+          hypothesis = File.join(File.dirname(file), "HYPOTHESIS.md")
+          { "seed" => seed, "forms" => ["source:#{File.basename(File.dirname(file))}"],
+            "origin" => File.expand_path(file), "source" => File.read(file),
+            "hypothesis" => (File.read(hypothesis) if File.exist?(hypothesis)),
+            "aggregates" => [], "policies" => [] }.compact
+        end
+      end
+    end
+  end
+end