hecks 3.5.0 → 3.6.0

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

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