hecks 3.4.2 → 3.6.0

data/lib/hecks/projector/narrate_projector.rb

@@ -21,45 +21,50 @@ module Hecks
 
         sections = []
         sections << chapter_intro(bluebook, depth) unless only
-        Array(DocsProjector.aggregates(bluebook, only)).each do |aggregate|
-          sections << aggregate_narrative(aggregate, only ? depth : depth + 1)
-        end
-        sections << reactions_narrative(bluebook, depth + 1) unless only
+        sections.concat(aggregate_narratives(bluebook, only, only ? depth : depth + 1))
+        sections << Reactions.narrative(bluebook, depth + 1) unless only
         "#{sections.compact.join("\n\n").rstrip}\n"
       end
 
+      # One narrative per aggregate, at heading level `depth`.
+      def aggregate_narratives(bluebook, only, depth)
+        Array(DocsProjector.aggregates(bluebook, only)).map { |aggregate| aggregate_narrative(aggregate, depth) }
+      end
+
       def chapter_intro(bluebook, depth)
-        parts = [DocsProjector.h(depth, bluebook.name)]
-        parts << bluebook.vision if bluebook.vision
+        names = bluebook.aggregates.map(&:hecks_name)
+        parts = [DocsProjector.h(depth, bluebook.name), bluebook.vision, chapter_meta(bluebook)]
+        parts << "It's told through #{to_sentence_list(names)}." unless names.empty?
+        parts.compact.join("\n\n")
+      end
 
+      # The chapter's classification and former name as one paragraph, or `nil` when it has neither.
+      def chapter_meta(bluebook)
         meta = []
         meta << "This is a #{bluebook.classification} domain." if bluebook.classification
         meta << "It was formerly known as `#{bluebook.formerly_known_as}`." if bluebook.formerly_known_as
-        parts << meta.join(" ") unless meta.empty?
-
-        names = bluebook.aggregates.map(&:hecks_name)
-        parts << "It's told through #{to_sentence_list(names)}." unless names.empty?
-        parts.join("\n\n")
+        meta.join(" ") unless meta.empty?
       end
 
       def aggregate_narrative(aggregate, depth)
-        parts = [DocsProjector.h(depth, aggregate.hecks_name)]
-        parts << aggregate.description if aggregate.description
-        parts << identity_sentence(aggregate)
+        entities = aggregate.entities.map { |entity| entity_narrative(aggregate, entity, depth + 1) }
+        [DocsProjector.h(depth, aggregate.hecks_name), *aggregate_facts(aggregate),
+         lifecycle_narrative(aggregate), Commands.verbs_narrative(aggregate, depth + 1),
+         queries_narrative(aggregate.queries, aggregate.hecks_name, depth + 1), *entities].compact.join("\n\n")
+      end
 
-        refs = aggregate.attributes.select(&:reference?)
-        unless refs.empty?
-          parts << "Each one is linked to #{to_sentence_list(refs.map do |r|
-            "#{a_or_an(r.type.target_name)} #{r.type.target_name}"
-          end)}."
-        end
+      # What an aggregate says of itself: its description, identity and references.
+      def aggregate_facts(aggregate)
+        [aggregate.description, identity_sentence(aggregate), references_sentence(aggregate)]
+      end
 
-        parts << lifecycle_narrative(aggregate)
-        parts << verbs_narrative(aggregate, depth + 1)
-        parts << queries_narrative(aggregate.queries, aggregate.hecks_name, depth + 1)
+      # The sentence naming the records an aggregate is linked to, or `nil` when it has none.
+      def references_sentence(aggregate)
+        refs = aggregate.attributes.select(&:reference?)
+        return nil if refs.empty?
 
-        aggregate.entities.each { |entity| parts << entity_narrative(aggregate, entity, depth + 1) }
-        parts.compact.join("\n\n")
+        targets = refs.map { |r| "#{a_or_an(r.type.target_name)} #{r.type.target_name}" }
+        "Each one is linked to #{to_sentence_list(targets)}."
       end
 
       def identity_sentence(holder)
@@ -69,15 +74,11 @@ module Hecks
       end
 
       def entity_narrative(aggregate, entity, depth)
-        parts = [DocsProjector.h(depth, "#{entity.hecks_name} (within #{aggregate.hecks_name})")]
-        parts << entity.description if entity.description
-        parts << "Reached through its #{aggregate.hecks_name} — you address it by the #{aggregate.hecks_name}'s " \
-                 "id together with its own `#{entity.identity_heads.join('`, `')}`."
-
-        parts << lifecycle_narrative(entity)
-        parts << verbs_narrative(entity, depth + 1)
-        parts << queries_narrative(entity.queries, entity.hecks_name, depth + 1)
-        parts.compact.join("\n\n")
+        [DocsProjector.h(depth, "#{entity.hecks_name} (within #{aggregate.hecks_name})"), entity.description,
+         "Reached through its #{aggregate.hecks_name} — you address it by the #{aggregate.hecks_name}'s " \
+         "id together with its own `#{entity.identity_heads.join("`, `")}`.",
+         lifecycle_narrative(entity), Commands.verbs_narrative(entity, depth + 1),
+         queries_narrative(entity.queries, entity.hecks_name, depth + 1)].compact.join("\n\n")
       end
 
       def lifecycle_narrative(holder)
@@ -86,150 +87,46 @@ module Hecks
         sentences = ["It carries a `#{lifecycle.field}`, starting out at `#{lifecycle.default}`."]
         lifecycle.transitions.each do |name, transition|
           froms = Array(transition.from).map { |f| "`#{f}`" }
-          sentences << "**#{name}** moves it from #{to_sentence_list(froms, conj: 'or')} to `#{transition.target}`."
+          sentences << "**#{name}** moves it from #{to_sentence_list(froms, conj: "or")} to `#{transition.target}`."
         end
         sentences << "A verb not listed here can be issued from any state."
         sentences.join(" ")
       end
 
-      def verbs_narrative(holder, depth)
-        return nil if holder.commands.empty?
-
-        header = DocsProjector.h(depth, "What can happen to #{a_or_an(holder.hecks_name)} #{holder.hecks_name}")
-        body   = holder.commands.map { |command| command_paragraph(command, holder) }.join("\n\n")
-        "#{header}\n\n#{body}"
-      end
-
-      # Each sentence states one independent fact, so nil-or-string plus `compact.join` suffices.
-      def command_paragraph(command, holder)
-        [
-          command_headline_sentence(command),
-          command_role_sentence(command),
-          command_creation_sentence(command, holder),
-          command_arguments_sentence(command),
-          command_references_sentence(command),
-          command_conditions_sentence(command, holder),
-          command_guarantees_sentence(command),
-          command_emits_sentence(command)
-        ].compact.join(" ")
-      end
-
-      # The goal is quoted exactly as declared, never recased to fit mid-sentence.
-      def command_headline_sentence(command)
-        "**#{command.hecks_name}**#{command.goal ? " — #{command.goal}." : '.'}"
-      end
-
-      def command_role_sentence(command)
-        return nil unless command.role
-
-        "Issued by #{a_or_an(command.role)} #{command.role}."
-      end
-
-      # `acts_on.nil?`, not `creates?`: `creates?` is true for every entity verb, which would
-      # wrongly say `LedgerEntry.Amend` creates a new ledger entry.
-      def command_creation_sentence(command, holder)
-        return nil unless command.acts_on.nil?
-
-        "This is how a new #{holder.hecks_name} comes into being."
-      end
-
-      def command_arguments_sentence(command)
-        arguments = command.attributes.reject(&:reference?)
-        return nil if arguments.empty?
-
-        "It takes #{to_sentence_list(arguments.map { |a| Forms::Humanize.label(a.name.to_s).downcase })}."
-      end
-
-      def command_references_sentence(command)
-        refs = command.attributes.select(&:reference?)
-        return nil if refs.empty?
-
-        "It's aimed at one existing #{to_sentence_list(refs.map { |r| r.type.target_name })}, by id."
-      end
-
-      def command_conditions_sentence(command, holder)
-        conditions = conditions_of(command, holder)
-        return nil if conditions.empty?
-
-        "It only goes through if #{conditions.join('; ')}."
-      end
-
-      def command_guarantees_sentence(command)
-        guarantees = command.ensures.map(&:description)
-        return nil if guarantees.empty?
+      def queries_narrative(queries, holder_name, depth)
+        return nil if queries.empty?
 
-        "When it succeeds: #{guarantees.join('; ')}."
+        header = DocsProjector.h(depth, "Questions you can ask about #{a_or_an(holder_name)} #{holder_name}")
+        "#{header}\n\n#{queries.map { |query| query_line(query) }.join("\n")}"
       end
 
-      def command_emits_sentence(command)
-        return nil if command.emits.empty?
-
-        "It records `#{command.emits.join('`, `')}` as a fact."
+      # One question as a bullet: its name, what it is given, its description and its filters.
+      def query_line(query)
+        shape = query.to_h
+        sentence = "- **#{query.hecks_name}**#{given_clause(shape)}"
+        sentence << " — #{query.description}" if query.description
+        sentence << "." unless sentence.end_with?(".")
+        sentence << filter_clause(shape)
       end
 
-      # Required conditions stated positively ("only goes through if X"), from the lifecycle
-      # edge and the command's `given`s.
-      def conditions_of(command, holder)
-        conditions = []
-
-        lifecycle = holder.lifecycle
-        if lifecycle
-          froms = lifecycle.transitions.filter_map do |name, transition|
-            Array(transition.from) if name.to_s == command.hecks_name
-          end.flatten.uniq
-          unless froms.empty?
-            conditions << "its `#{lifecycle.field}` is currently #{to_sentence_list(froms.map do |f|
-              "`#{f}`"
-            end, conj: 'or')}"
-          end
-        end
-
-        conditions + command.givens.map(&:description)
+      # " (given a, b)" for a question that takes arguments, else nothing.
+      def given_clause(shape)
+        takes = Array(shape[:attributes]).map { |a| Forms::Humanize.label(a[:name].to_s).downcase }
+        takes.empty? ? "" : " (given #{to_sentence_list(takes)})"
       end
 
-      def queries_narrative(queries, holder_name, depth)
-        return nil if queries.empty?
-
-        header = DocsProjector.h(depth, "Questions you can ask about #{a_or_an(holder_name)} #{holder_name}")
-        lines = queries.map do |query|
-          shape   = query.to_h
-          takes   = Array(shape[:attributes]).map { |a| Forms::Humanize.label(a[:name].to_s).downcase }
-          # `w[:value]` is already `Literal.render`ed (quoted), so no `.inspect`.
-          filters = Array(shape[:wheres]).map { |w| "`#{w[:field]}` #{op_words(w[:op])} #{w[:value]}" }
-
-          sentence = "- **#{query.hecks_name}**"
-          sentence << " (given #{to_sentence_list(takes)})" unless takes.empty?
-          sentence << " — #{query.description}" if query.description
-          sentence << "." unless sentence.end_with?(".")
-          sentence << " Only where #{to_sentence_list(filters)}." unless filters.empty?
-          sentence
-        end
-        "#{header}\n\n#{lines.join("\n")}"
+      # " Only where ..." for a question that filters, else nothing.
+      #
+      # `w[:value]` is already `Literal.render`ed (quoted), so no `.inspect`.
+      def filter_clause(shape)
+        filters = Array(shape[:wheres]).map { |w| "`#{w[:field]}` #{op_words(w[:op])} #{w[:value]}" }
+        filters.empty? ? "" : " Only where #{to_sentence_list(filters)}."
       end
 
       def op_words(comparator)
         { eq: "is", lt: "under", lte: "at most", gt: "over", gte: "at least" }[comparator.to_s.to_sym] || comparator.to_s
       end
 
-      def reactions_narrative(bluebook, depth)
-        return nil if bluebook.policies.empty? && bluebook.process_managers.empty?
-
-        parts = [DocsProjector.h(depth, "Reactions")]
-        bluebook.policies.each do |policy|
-          elsewhere = policy.target_domain ? " in #{policy.target_domain}" : ""
-          parts << "Whenever `#{policy.on_event}` happens, `#{policy.trigger_command}` fires on its own#{elsewhere} — " \
-                   "nobody has to ask for it."
-        end
-
-        bluebook.process_managers.each do |saga|
-          shape = saga.to_h
-          parts << "**#{shape[:name]}** is a saga: it starts when `#{shape[:starts_on]}` happens and ends when " \
-                   "`#{shape[:ends_on]}` happens, with each run tracked by its `#{shape[:correlates_by]}`. Along the " \
-                   "way it moves through #{Array(shape[:states]).map { |s| "`#{s}`" }.join(' → ')}."
-        end
-        parts.join("\n\n")
-      end
-
       def to_sentence_list(items, conj: "and") = Naming.to_sentence_list(items, conj: conj)
 
       # Picks the article for `word`.
@@ -239,3 +136,6 @@ module Hecks
     end
   end
 end
+
+require_relative "narrate_projector/commands"
+require_relative "narrate_projector/reactions"

data/lib/hecks/projector.rb

@@ -56,25 +56,33 @@ module Hecks
     # @raise [WrongConstruct] if a required capability or aggregate is missing, or the
     #   projector needs `world:` and `world` is nil
     def admits!(name, projector, construct, world = nil)
+      refuse_missing_capabilities!(name, projector, construct)
+      refuse_absent_aggregates!(name, projector, construct)
+      return unless projector.respond_to?(:projection_needs_world?) && projector.projection_needs_world? && world.nil?
+
+      raise WrongConstruct, "#{name.inspect} needs .world/.hecksagon bindings — pass world: to Projector.call."
+    end
+
+    # @raise [WrongConstruct] if the construct lacks a capability the projector requires
+    def refuse_missing_capabilities!(name, projector, construct)
       needed = projector.respond_to?(:projection_requires) ? projector.projection_requires : []
       missing = needed.reject { |capability| capable?(construct, capability) }
-      unless missing.empty?
-        raise WrongConstruct,
-              "#{name.inspect} needs #{missing.map(&:name).join(' and ')}, and was handed " \
-              "#{construct.class} (#{construct.respond_to?(:hecks_name) ? construct.hecks_name : construct.inspect})."
-      end
+      return if missing.empty?
 
+      raise WrongConstruct,
+            "#{name.inspect} needs #{missing.map(&:name).join(" and ")}, and was handed " \
+            "#{construct.class} (#{construct.respond_to?(:hecks_name) ? construct.hecks_name : construct.inspect})."
+    end
+
+    # @raise [WrongConstruct] if the construct declares no aggregate the projector requires
+    def refuse_absent_aggregates!(name, projector, construct)
       declared = projector.respond_to?(:projection_declares) ? projector.projection_declares : []
       absent   = declared.reject { |named| construct.aggregate(named) }
-      unless absent.empty?
-        raise WrongConstruct,
-              "#{name.inspect} needs a chapter declaring #{absent.join(' and ')}; " \
-              "#{construct.name} declares no such aggregate."
-      end
+      return if absent.empty?
 
-      return unless projector.respond_to?(:projection_needs_world?) && projector.projection_needs_world? && world.nil?
-
-      raise WrongConstruct, "#{name.inspect} needs .world/.hecksagon bindings — pass world: to Projector.call."
+      raise WrongConstruct,
+            "#{name.inspect} needs a chapter declaring #{absent.join(" and ")}; " \
+            "#{construct.name} declares no such aggregate."
     end
 
     # Tells whether `construct` has the capability `admits!` requires of it.
@@ -166,6 +174,7 @@ require_relative "projector/target"
 # These need only `Naming`, not this file, so they are safe to load from here.
 require_relative "projector/docs_projector"
 require_relative "projector/narrate_projector"
+require_relative "projector/cli_audience"
 require_relative "projector/cli_projector"
 
 Hecks::Projector.register(:ir, Hecks::Projector::IRProjector)

data/lib/hecks/quality_control/adapters/agent_profile.rb

@@ -31,6 +31,9 @@ module Hecks
 
       SANDBOX = "/usr/bin/sandbox-exec"
 
+      # The keywords `new` takes besides the four lists, with what each defaults to.
+      LIMIT_DEFAULTS = { timeout: nil, budget: nil, confinement: :sandbox }.freeze
+
       # @return [Array<String>] the tools the agent is given
       attr_reader :tools
       # @return [Array<String>] the directories the agent may write, besides the temp directory
@@ -50,26 +53,19 @@ module Hecks
       # @param writable [Array<String>] directories the agent may write
       # @param network [Symbol] one of `NETWORKS`
       # @param env [Array<String>] environment variable names to pass through
-      # @param timeout [Integer, nil] seconds the run may take
-      # @param budget [Float, nil] dollars the run may spend
-      # @param confinement [Symbol] one of `CONFINEMENTS`; `network` applies to the sandbox only
+      # @param limits [Hash] `timeout:` (Integer, nil) seconds the run may take, `budget:`
+      #   (Float, nil) dollars it may spend, `confinement:` one of `CONFINEMENTS` (`network`
+      #   applies to the sandbox only)
       # @raise [ArgumentError] when `network` or `confinement` is not one it knows
-      def initialize(tools: [], writable: [], network: :none, env: [], timeout: nil, budget: nil,
-                     confinement: :sandbox)
-        unless NETWORKS.include?(network)
-          raise ArgumentError, "network must be one of #{NETWORKS.inspect}, not #{network.inspect}"
-        end
-        unless CONFINEMENTS.include?(confinement)
-          raise ArgumentError, "confinement must be one of #{CONFINEMENTS.inspect}, not #{confinement.inspect}"
-        end
-
+      def initialize(tools: [], writable: [], network: :none, env: [], **limits)
+        limits = LIMIT_DEFAULTS.merge(reject_unknown(limits))
+        ensure_known(:network, NETWORKS, network)
+        ensure_known(:confinement, CONFINEMENTS, limits[:confinement])
         @tools = tools.dup.freeze
         @writable = writable.dup.freeze
         @network = network
         @env = env.dup.freeze
-        @timeout = timeout
-        @budget = budget
-        @confinement = confinement
+        @timeout, @budget, @confinement = limits.values_at(:timeout, :budget, :confinement)
       end
 
       # @return [Boolean] whether this profile is enforced by the operating system's sandbox
@@ -151,6 +147,19 @@ module Hecks
         end
       end
 
+      def reject_unknown(limits)
+        unknown = limits.keys - LIMIT_DEFAULTS.keys
+        return limits if unknown.empty?
+
+        raise ArgumentError, "unknown keyword#{"s" if unknown.size > 1}: #{unknown.map(&:inspect).join(", ")}"
+      end
+
+      def ensure_known(name, allowed, value)
+        return if allowed.include?(value)
+
+        raise ArgumentError, "#{name} must be one of #{allowed.inspect}, not #{value.inspect}"
+      end
+
       def real(path)
         File.realpath(path)
       rescue SystemCallError
@@ -158,7 +167,7 @@ module Hecks
       end
 
       def quote(path)
-        %("#{path.gsub('\\', '\\\\\\\\').gsub('"', '\\"')}")
+        %("#{path.gsub("\\", "\\\\\\\\").gsub('"', '\\"')}")
       end
     end
   end

data/lib/hecks/quality_control/adapters/github_checks.rb

@@ -28,25 +28,61 @@ module Hecks
       # @raise [RuntimeError] when the sha is malformed, `gh` is missing or fails, no checks
       #   exist, any are incomplete, or any failed
       def run(commit:, **)
+        sha = valid_sha(commit)
+        runs = settled_runs(sha)
+        failing = runs.reject { |run| PASSING.include?(run["conclusion"]) }
+        raise failure_message(failing, runs, sha) unless failing.empty?
+
+        { summary: { value: "#{runs.length} checks, all green (#{sha[0, 7]})" } }
+      end
+
+      # Where each named check stands against a commit, for a caller that must tell a check that is
+      # still running from one that failed (`run` raises for both). A name that reported more than
+      # once (a re-run) stands as its most recent report.
+      #
+      # @param commit [Hash, String] a materialized value object (`{value: sha}`) or a bare sha
+      # @param names [Array<String>] the checks to look up
+      # @return [Hash{String => Symbol}] each name to `:passed`, `:failed`, `:pending` (reported but
+      #   not completed) or `:missing` (not reported at all)
+      # @raise [RuntimeError] when the sha is malformed or `gh` is missing or fails
+      def states(commit:, names:)
+        reported = check_runs(valid_sha(commit)).group_by { |run| run["name"] }
+        latest = reported.transform_values { |runs| runs.max_by { |run| run["id"].to_i } }
+        names.to_h { |name| [name, state_of(latest[name])] }
+      end
+
+      private
+
+      def valid_sha(commit)
         sha = sha_of(commit)
         raise "not a commit sha: #{sha.inspect}" unless sha.match?(SHA_PATTERN)
 
-        runs = check_runs(sha)
+        sha
+      end
 
+      # The check runs against `sha`, once none is still running.
+      def settled_runs(sha)
+        runs = check_runs(sha)
         raise "gh reports no checks at all against #{sha}" if runs.empty?
 
         # Refuse rather than answer on an incomplete run; asking again once it settles is safe.
         incomplete = runs.reject { |run| run["status"] == "completed" }
         raise "checks against #{sha} are still running — asked before they settled" if incomplete.any?
 
-        failing = runs.reject { |run| PASSING.include?(run["conclusion"]) }
-        return { summary: { value: "#{runs.length} checks, all green (#{sha[0, 7]})" } } if failing.empty?
+        runs
+      end
 
-        raise "#{failing.length} of #{runs.length} checks failed against #{sha[0, 7]}: " \
-              "#{failing.map { |run| run['name'] }.join(', ')}"
+      def failure_message(failing, runs, sha)
+        "#{failing.length} of #{runs.length} checks failed against #{sha[0, 7]}: " \
+          "#{failing.map { |run| run["name"] }.join(", ")}"
       end
 
-      private
+      def state_of(run)
+        return :missing unless run
+        return :pending unless run["status"] == "completed"
+
+        PASSING.include?(run["conclusion"]) ? :passed : :failed
+      end
 
       # Accepts a materialized value hash with symbol or string keys, or a bare string.
       def sha_of(commit)

data/lib/hecks/quality_control/adapters/github_ci_webhook.rb

@@ -44,7 +44,7 @@ module Hecks
             return ignored("passing check_suite from app #{app.inspect}, not #{CI_APP_SLUG.inspect}")
           end
 
-          summary = "check_suite #{suite['id']} conclusion=#{conclusion} for #{sha[0, 7]} — via webhook"
+          summary = "check_suite #{suite["id"]} conclusion=#{conclusion} for #{sha[0, 7]} — via webhook"
 
           cleared = Hecks::QA::ClearanceRecorder.record(commit: sha, passed: passed, summary: summary)
 

data/lib/hecks/quality_control/adapters/github_issues.rb

@@ -20,23 +20,35 @@ module Hecks
       #   ticket's `Filed` command takes
       # @raise [RuntimeError] when `gh` exits non-zero or prints no issue URL
       def file(**held)
-        repository = plain(held[:repository])
-        proposed   = plain(held[:pull_request]).to_s
-        body       = plain(held[:body]).to_s
-        body      += "\n\nA fix is proposed in #{proposed}" unless proposed.empty?
+        out = create_issue(plain(held[:repository]), plain(held[:title]).to_s, issue_body(held))
+        url, number = issue_url_and_number(out)
 
-        out, err, status = Open3.capture3("gh", "issue", "create", "--repo", repository,
-                                          "--title", plain(held[:title]).to_s, "--body", body)
-        raise "gh issue create failed — #{err.strip.empty? ? out.strip : err.strip}" unless status.success?
+        { number: { value: number.to_i }, url: { value: url } }
+      end
+
+      private
+
+      def issue_body(held)
+        proposed = plain(held[:pull_request]).to_s
+        body     = plain(held[:body]).to_s
+        proposed.empty? ? body : "#{body}\n\nA fix is proposed in #{proposed}"
+      end
 
-        url    = out.strip.lines.last.to_s.strip
+      def issue_url_and_number(out)
+        url = out.strip.lines.last.to_s.strip
         number = url[%r{/issues/(\d+)\z}, 1]
         raise "gh issue create printed no issue URL: #{out.strip.inspect}" unless number
 
-        { number: { value: number.to_i }, url: { value: url } }
+        [url, number]
       end
 
-      private
+      def create_issue(repository, title, body)
+        out, err, status = Open3.capture3("gh", "issue", "create", "--repo", repository,
+                                          "--title", title, "--body", body)
+        raise "gh issue create failed — #{err.strip.empty? ? out.strip : err.strip}" unless status.success?
+
+        out
+      end
 
       # A materialized value object (`{value: x}`, symbol or string keys) or the value itself.
       def plain(field)

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

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Hecks
+  module QualityControlCli
+    class QaDiscoverExternalDomains
+      # The command line of `target.discover_external_domains`: flags into an options hash.
+      module Parsing
+        HELP_FLAGS = %w[-h --help].freeze
+
+        private
+
+        # @param argv [Array<String>] consumed as it is read
+        # @return [Hash, Symbol] `:projects_dir`, `:max_depth` and `:known_paths`, or `:help` after
+        #   the usage line was printed
+        def parse(argv)
+          options = { projects_dir: DEFAULT_PROJECTS_DIR, max_depth: DEFAULT_MAX_DEPTH, known_paths: nil }
+          until argv.empty?
+            arg = argv.shift
+            if HELP_FLAGS.include?(arg)
+              puts USAGE
+              return :help
+            end
+            apply_option(options, arg, argv)
+          end
+          validate_options(options)
+        end
+
+        def apply_option(options, arg, argv)
+          case arg
+          when "--projects-dir" then options[:projects_dir] = File.expand_path(option_value(arg, argv, "a path"))
+          when "--max-depth" then options[:max_depth] = Integer(option_value(arg, argv, "a number"))
+          when "--known-path" then (options[:known_paths] ||= []) << File.expand_path(option_value(arg, argv, "a path"))
+          else refuse!("unexpected argument #{arg.inspect}")
+          end
+        end
+
+        def option_value(flag, argv, kind)
+          refuse!("#{flag} needs #{kind}") if argv.empty?
+          argv.shift
+        end
+
+        def validate_options(options)
+          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
+      end
+    end
+  end
+end

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

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Hecks
+  module QualityControlCli
+    class QaDiscoverExternalDomains
+      # What `target.discover_external_domains` prints once the scan is done.
+      module Reporting
+        private
+
+        def report(options, candidates, skipped, siblings)
+          print_summary(options, skipped, siblings)
+          puts
+          return print_no_candidates(options) if candidates.empty?
+
+          puts "#{candidates.size} candidate(s) — report only, nothing identified. Review each, then run " \
+               "the command yourself to enroll it:"
+          puts
+          candidates.each { |candidate| print_candidate(candidate) }
+        end
+
+        def print_summary(options, 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"
+          return if skipped.empty?
+
+          puts "no hecks dependency, skipped: #{skipped.map { |path| File.basename(path) }.join(", ")}"
+        end
+
+        def print_no_candidates(options)
+          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]}."
+        end
+
+        def print_candidate(candidate)
+          puts "  #{candidate[:reference]}"
+          puts "    path: #{candidate[:path]}"
+          puts "    enroll: hecks run qa/bluebook identify reference=#{candidate[:reference]} path=#{candidate[:path]}"
+          puts
+        end
+      end
+    end
+  end
+end