hecks 3.4.2 → 3.6.0

data/lib/hecks/quality_control/cli/qa_tick/preflight.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Hecks
+  module QualityControlCli
+    class QaTick
+      # What a tick does before any step runs: the process set-up, the libraries every step shares,
+      # and the clean-tree check and rebase that start a tick from `origin/main`.
+      module Preflight
+        # The libraries the steps need, loaded once by the tick rather than once per step.
+        STEP_LIBRARIES = [
+          "hecks", "hecks/ports/persistence/plugins/era", "hecks/fuzzing", "hecks/fuzzing/self_consistency",
+          "hecks/fuzzing/differential", "hecks/fuzzing/era_boundary", "hecks/fuzzing/concurrent_dispatch",
+          "hecks/fuzzing/domain_generator", "hecks/fuzzing/generated_domain_check",
+          "hecks/quality_control/adapters/git_pr", "hecks/quality_control/cli/qa_pr_check",
+          "hecks/quality_control/cli/qa_sweep", "hecks/quality_control/cli/qa_generated_domains"
+        ].freeze
+
+        private
+
+        # **macOS only, harmless elsewhere.** `fork` below can race Apple's Objective-C runtime
+        # initializing a class in a background thread and crash the forked child outright ("may
+        # have been in progress in another thread when fork() was called... Crashing instead").
+        # Spring's preload-and-fork test runner sets this same flag for the same reason. It has to
+        # be in the environment before the Ruby interpreter itself starts, since setting it via
+        # `ENV[]` from inside an already-running process is too late (libobjc has already decided by
+        # then), so a bare macOS run re-execs itself once with it set,
+        # through the same launch form `Child.argv` uses (the process may be a `ruby -e` child,
+        # whose `$PROGRAM_NAME` is not a script). Linux has no Objective-C
+        # runtime, so this never runs there.
+        def reexec_with_fork_safety
+          return unless RUBY_PLATFORM.include?("darwin") && !ENV["OBJC_DISABLE_INITIALIZE_FORK_SAFETY"]
+
+          ENV["OBJC_DISABLE_INITIALIZE_FORK_SAFETY"] = "YES"
+          exec(*Child.argv(@root, "qa_tick"))
+        end
+
+        # **Loaded once, here.** The three steps each `require "hecks"` (plus their own era and
+        # fuzzing extras) at their own top. Loading the union up front means every `fork` below
+        # hands its step an already-booted Ruby with Bundler's gems already activated and each of
+        # these files already in `$LOADED_FEATURES`, so the step's own `require` lines are no-ops
+        # instead of a second, third, and fourth cold load of the whole runtime.
+        def load_steps
+          $LOAD_PATH.unshift File.join(@root, "lib")
+          STEP_LIBRARIES.each { |library| require library }
+        end
+
+        def git(*)
+          out, err, status = Open3.capture3("git", *, chdir: @repo_dir)
+          [out.strip, err.strip, status]
+        end
+
+        def banner(title)
+          puts
+          puts "── #{title} " + ("─" * [0, 70 - title.size].max)
+          puts
+        end
+
+        def refuse_unless_ready
+          require_clean_tree
+          rebase_on_origin_main
+        end
+
+        def require_clean_tree
+          banner "worktree (#{@repo_dir})"
+          dirty, err, status = git("status", "--porcelain")
+          abort "refused: could not read git status at #{@repo_dir} — #{err}" unless status.success?
+          refuse_dirty_tree(dirty) unless dirty.empty?
+          puts "clean"
+        end
+
+        def refuse_dirty_tree(dirty)
+          abort "refused: the working tree is dirty — a tick starts from a clean checkout, never over " \
+                "uncommitted work:\n#{dirty}"
+        end
+
+        def rebase_on_origin_main
+          banner "git fetch origin && git rebase origin/main"
+          out, err, status = git("fetch", "origin")
+          abort "refused: git fetch origin failed — #{err.empty? ? out : err}" unless status.success?
+          out, err, status = git("rebase", "origin/main")
+          abort_rebase(out, err) unless status.success?
+          head, = git("rev-parse", "--short", "HEAD")
+          puts "at #{head}"
+        end
+
+        def abort_rebase(out, err)
+          git("rebase", "--abort")
+          abort "refused: git rebase origin/main stopped (aborted, tree restored) — #{err.empty? ? out : err}"
+        end
+      end
+    end
+  end
+end

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

@@ -6,6 +6,8 @@ require "open3"
 require "rbconfig"
 require "tempfile"
 require_relative "child"
+require_relative "qa_tick/preflight"
+require_relative "qa_tick/output"
 
 module Hecks
   module QualityControlCli
@@ -18,6 +20,9 @@ module Hecks
     # checkout for the repo steps; `QA_SWEEP_DOMAIN_DIR` is inherited. It never logs bugs, releases
     # holds or opens PRs; those stay with a person or agent.
     class QaTick
+      include Preflight
+      include Output
+
       EXIT_OK = 0
       EXIT_ERROR = 1
       EXIT_FOUND_SOMETHING = 2
@@ -54,13 +59,8 @@ module Hecks
       # @return [Integer] the exit status
       # @raise [SystemExit] when given arguments, the tree is dirty or the rebase stops
       def call(argv)
-        unless argv.empty?
-          if %w[-h --help].include?(argv.first)
-            puts USAGE
-            return EXIT_OK
-          end
-          abort "#{USAGE}\nthis script takes no arguments — one tick is always the same tick"
-        end
+        return reject_arguments(argv) unless argv.empty?
+
         reexec_with_fork_safety
         load_steps
         refuse_unless_ready
@@ -69,76 +69,12 @@ module Hecks
 
       private
 
-      # **macOS only, harmless elsewhere.** `fork` below can race Apple's Objective-C runtime
-      # initializing a class in a background thread and crash the forked child outright ("may
-      # have been in progress in another thread when fork() was called... Crashing instead").
-      # Spring's preload-and-fork test runner sets this same flag for the same reason. It has to
-      # be in the environment before the Ruby interpreter itself starts, since setting it via
-      # `ENV[]` from inside an already-running process is too late (libobjc has already decided by
-      # then), so a bare macOS run re-execs itself once with it set,
-      # through the same launch form `Child.argv` uses (the process may be a `ruby -e` child,
-      # whose `$PROGRAM_NAME` is not a script). Linux has no Objective-C
-      # runtime, so this never runs there.
-      def reexec_with_fork_safety
-        return unless RUBY_PLATFORM.include?("darwin") && !ENV["OBJC_DISABLE_INITIALIZE_FORK_SAFETY"]
-
-        ENV["OBJC_DISABLE_INITIALIZE_FORK_SAFETY"] = "YES"
-        exec(*Child.argv(@root, "qa_tick"))
-      end
-
-      # **Loaded once, here.** The three steps each `require "hecks"` (plus their own era and
-      # fuzzing extras) at their own top. Loading the union up front means every `fork` below
-      # hands its step an already-booted Ruby with Bundler's gems already activated and each of
-      # these files already in `$LOADED_FEATURES`, so the step's own `require` lines are no-ops
-      # instead of a second, third, and fourth cold load of the whole runtime.
-      def load_steps
-        $LOAD_PATH.unshift File.join(@root, "lib")
-        require "hecks"
-        require "hecks/ports/persistence/plugins/era"
-        require "hecks/fuzzing"
-        require "hecks/fuzzing/self_consistency"
-        require "hecks/fuzzing/differential"
-        require "hecks/fuzzing/era_boundary"
-        require "hecks/fuzzing/concurrent_dispatch"
-        require "hecks/fuzzing/domain_generator"
-        require "hecks/fuzzing/generated_domain_check"
-        require "hecks/quality_control/adapters/git_pr"
-        require "hecks/quality_control/cli/qa_pr_check"
-        require "hecks/quality_control/cli/qa_sweep"
-        require "hecks/quality_control/cli/qa_generated_domains"
-      end
-
-      def git(*)
-        out, err, status = Open3.capture3("git", *, chdir: @repo_dir)
-        [out.strip, err.strip, status]
-      end
-
-      def banner(title)
-        puts
-        puts "── #{title} " + ("─" * [0, 70 - title.size].max)
-        puts
-      end
-
-      def refuse_unless_ready
-        banner "worktree (#{@repo_dir})"
-        dirty, err, status = git("status", "--porcelain")
-        abort "refused: could not read git status at #{@repo_dir} — #{err}" unless status.success?
-        unless dirty.empty?
-          abort "refused: the working tree is dirty — a tick starts from a clean checkout, never over " \
-                "uncommitted work:\n#{dirty}"
-        end
-        puts "clean"
-
-        banner "git fetch origin && git rebase origin/main"
-        out, err, status = git("fetch", "origin")
-        abort "refused: git fetch origin failed — #{err.empty? ? out : err}" unless status.success?
-        out, err, status = git("rebase", "origin/main")
-        unless status.success?
-          git("rebase", "--abort")
-          abort "refused: git rebase origin/main stopped (aborted, tree restored) — #{err.empty? ? out : err}"
+      def reject_arguments(argv)
+        if %w[-h --help].include?(argv.first)
+          puts USAGE
+          return EXIT_OK
         end
-        head, = git("rev-parse", "--short", "HEAD")
-        puts "at #{head}"
+        abort "#{USAGE}\nthis script takes no arguments — one tick is always the same tick"
       end
 
       # **A real fork, not a subprocess.** `bundle exec ruby <step>` would re-pay Bundler's gem
@@ -151,14 +87,7 @@ module Hecks
       # would clutter every real tick's report, so `$VERBOSE` drops in the child.
       def run_step(command, *argv)
         read, write = IO.pipe
-        pid = fork do
-          read.close
-          $stdout.reopen(write)
-          $stderr.reopen(write)
-          write.close
-          $VERBOSE = nil
-          exit(command.call(argv))
-        end
+        pid = fork { run_in_child(command, argv, read, write) }
         write.close
         output = read.read
         read.close
@@ -166,108 +95,46 @@ module Hecks
         [output, status.exitstatus]
       end
 
-      def collapse_held_lines(text)
-        text.gsub(/(?:#{HELD_SEED_LINE}\n)+/) do |run|
-          count = run.lines.size
-          "  (#{count} held seed(s) suppressed here — none surprised; full detail in the tick's log file)\n"
-        end
-      end
-
-      # The sweep's `--all` consolidated report is the one step whose bulk section can get
-      # large enough to put a relay at risk of truncation (a widened `clean_streak` means hundreds
-      # of "seed N: held" lines can precede either a real finding or an unrelated operational
-      # error). Everything from the first `OPERATIONAL ERRORS`/`FOUND SOMETHING` header through
-      # the end of the last such block is copied verbatim, never summarized or trimmed.
-      # `QA_SWEEP_TRACE` output, when present, is routine per-phase timing with no finding in it,
-      # so it is left out of stdout (still in the log).
-      def condense_sweep_output(raw)
-        errors_at = raw.index(/^OPERATIONAL ERRORS \(/)
-        found_at = raw.index(/^FOUND SOMETHING \(/)
-        trace_at = raw.index(/^QA_SWEEP_TRACE output /)
-        protect_from = [errors_at, found_at].compact.min
-        return collapse_held_lines(raw) if protect_from.nil?
-
-        protect_to = trace_at || raw.length
-        before = collapse_held_lines(raw[0...protect_from])
-        protected_block = raw[protect_from...protect_to]
-        after =
-          if trace_at
-            "\n(hecks quality_control ask run's QA_SWEEP_TRACE output omitted here — routine per-phase timing, not a " \
-              "finding; the full record is in the tick's log file)\n"
-          else
-            ""
-          end
-        "#{before}#{protected_block}#{after}"
-      end
-
-      def write_tick_log!(pr_check_output, sweep_output, generated_output)
-        dir = File.join(@root, "tmp/qa-tick-logs")
-        FileUtils.mkdir_p(dir)
-        path = File.join(dir, "#{Time.now.strftime('%Y%m%d-%H%M%S')}-#{Process.pid}.log")
-        File.write(path, <<~LOG)
-          #{'=' * 72}
-          hecks quality_control check_pull_requests -- full raw output
-          #{'=' * 72}
-          #{pr_check_output}
-
-          #{'=' * 72}
-          hecks quality_control ask run --all -- full raw output
-          #{'=' * 72}
-          #{sweep_output}
-
-          #{'=' * 72}
-          hecks quality_control check_generated_domains --from-dials -- full raw output
-          #{'=' * 72}
-          #{generated_output}
-        LOG
-        path
+      def run_in_child(command, argv, read, write)
+        read.close
+        $stdout.reopen(write)
+        $stderr.reopen(write)
+        write.close
+        $VERBOSE = nil
+        exit(command.call(argv))
       end
 
-      def verdict(code)
-        case code
-        when EXIT_OK then "clean"
-        when EXIT_FOUND_SOMETHING then "FOUND SOMETHING"
-        when EXIT_ERROR then "operational error"
-        else "exit #{code.inspect}"
-        end
+      def run_steps
+        pr_check_output, pr_check_exit = run_pr_check
+        sweep_output, sweep_exit = run_sweep
+        generated_output, generated_exit = run_generated_domains
+        log_path = write_tick_log!(pr_check_output, sweep_output, generated_output)
+        report([pr_check_exit, sweep_exit, generated_exit], reclaimed_holds(sweep_output), log_path)
       end
 
-      def run_steps
+      def run_pr_check
         banner "hecks quality_control check_pull_requests"
-        pr_check_output, pr_check_exit = run_step(->(argv) { QaPrCheck.call(argv, root: @root) })
-        puts pr_check_output
+        output, exit_code = run_step(->(argv) { QaPrCheck.call(argv, root: @root) })
+        puts output
+        [output, exit_code]
+      end
 
+      def run_sweep
         banner "hecks quality_control ask run --all"
-        sweep_output, sweep_exit = run_step(->(argv) { QaSweep.call(argv, root: @root) }, "--all")
-        puts condense_sweep_output(sweep_output)
-        reclaimed = sweep_output.scan(/^reclaimed stale hold: (\S+)/).flatten
+        output, exit_code = run_step(->(argv) { QaSweep.call(argv, root: @root) }, "--all")
+        puts condense_sweep_output(output)
+        [output, exit_code]
+      end
 
+      def run_generated_domains
         banner "hecks quality_control check_generated_domains --from-dials"
-        generated_output, generated_exit = run_step(->(argv) { QaGeneratedDomains.call(argv, root: @root) },
-                                                    "--from-dials")
-        puts generated_output
-
-        log_path = write_tick_log!(pr_check_output, sweep_output, generated_output)
-        report([pr_check_exit, sweep_exit, generated_exit], reclaimed, log_path)
+        output, exit_code = run_step(->(argv) { QaGeneratedDomains.call(argv, root: @root) }, "--from-dials")
+        puts output
+        [output, exit_code]
       end
 
-      def report(exits, reclaimed, log_path)
-        pr_check_exit, sweep_exit, generated_exit = exits
-        banner "tick report"
-        puts "hecks quality_control check_pull_requests:   #{verdict(pr_check_exit)} (exit #{pr_check_exit.inspect})"
-        puts "hecks quality_control ask run --all: #{verdict(sweep_exit)} (exit #{sweep_exit.inspect})"
-        puts "hecks quality_control check_generated_domains: #{verdict(generated_exit)} (exit #{generated_exit.inspect})"
-        named = reclaimed.empty? ? "" : " (#{reclaimed.join(', ')})"
-        puts "stale holds reclaimed: #{reclaimed.size}#{named}"
-
-        tick_exit =
-          if exits.include?(EXIT_FOUND_SOMETHING) then EXIT_FOUND_SOMETHING
-          elsif exits.all?(EXIT_OK) then EXIT_OK
-          else EXIT_ERROR
-          end
-        puts "tick: #{verdict(tick_exit)} (exit #{tick_exit})"
-        puts "full raw output (all three steps, unabridged): #{log_path}"
-        tick_exit
+      def reclaimed_holds(sweep_output)
+        sweep_output.scan(/^reclaimed stale hold: (\S+)/).flatten
       end
     end
   end

data/lib/hecks/query_ir/formatting.rb

@@ -0,0 +1,86 @@
+module Hecks
+  module QueryIR
+    # The text renderings of the diffs, previews and duplicate groups, shared by `hecks
+    # ir_constructs` and `hecks serve_query_ir_mcp`. Extended onto `QueryIR`.
+    module Formatting
+      # The line saying a construct's diff is empty.
+      CLEAN = "  clean — every declared field is emitted (or a named deviation), nothing emitted is undeclared".freeze
+
+      # Renders `constructs` output as text, shared by `hecks ir_constructs` and `hecks
+      # serve_query_ir_mcp`.
+      #
+      # @param diffs [Array<Hash>] `constructs`' own output
+      # @return [String] the human-readable rendering
+      def format_constructs(diffs)
+        diffs.map { |diff| format_construct(diff) }.join("\n\n")
+      end
+
+      # Renders one field's touchpoint checklist as text.
+      #
+      # @param preview [Hash] `impact_preview`'s own output
+      # @return [String] the human-readable rendering
+      def format_impact_preview(preview)
+        touchpoints = preview[:touchpoints]
+        lines = ["== #{preview[:name]}##{preview[:field]} =="] +
+                touchpoints.map { |t| "  [#{touchpoint_mark(t[:present]).rjust(7)}] #{t[:touchpoint]}" }
+        (lines + ["", advisory(touchpoints)]).join("\n")
+      end
+
+      # Renders the duplicate-rule groups as text.
+      #
+      # @param groups [Array<Hash>] `duplicates`' own output
+      # @return [String] the human-readable rendering
+      def format_duplicates(groups)
+        return "no duplicate given/invariant/ensures rule found" if groups.empty?
+
+        body = groups.map do |group|
+          ["== #{group[:kind]}: #{group[:description].inspect} — #{group[:canonical]} ==",
+           *group[:locations].map { |loc| "  #{loc}" }].join("\n")
+        end.join("\n\n")
+
+        "#{body}\n\n#{groups.size} duplicate group(s), #{groups.sum { |g| g[:locations].size }} declarations total"
+      end
+
+      private
+
+      def format_construct(diff)
+        lines = ["== #{diff[:name]} =="]
+        lines << "  emits:    #{diff[:emitted].join(", ")}"
+        lines << "  declares: #{diff[:declared].join(", ")}"
+        lines.concat(construct_verdict(diff))
+        lines.join("\n")
+      end
+
+      # @return [Array<String>] the lines saying what is missing or unaccounted, or that it is clean
+      def construct_verdict(diff)
+        missing = diff[:missing_from_ruby]
+        unaccounted = diff[:unaccounted_in_ruby]
+        return [CLEAN] if missing.empty? && unaccounted.empty?
+
+        [fields_line("MISSING FROM RUBY (declared, not emitted, not a named deviation)", missing),
+         fields_line("UNACCOUNTED IN RUBY (emitted, not declared, not a named deviation)", unaccounted)].compact
+      end
+
+      # @return [String, nil] the label and its fields on one line; nil when there are none
+      def fields_line(label, fields)
+        "  #{label}: #{fields.join(", ")}" unless fields.empty?
+      end
+
+      # @param present [Boolean, nil] whether a touchpoint shows signs of the field; nil when it
+      #   does not apply
+      def touchpoint_mark(present)
+        return "n/a" if present.nil?
+
+        present ? "yes" : "NOT YET"
+      end
+
+      def advisory(touchpoints)
+        done = touchpoints.count { |t| t[:present] == true }
+        total = touchpoints.count { |t| !t[:present].nil? }
+        "#{done}/#{total} applicable touchpoint(s) show signs of this field — advisory, not a gate; " \
+          "a NOT YET can be a legitimate exemption (Deviations, GUARANTEED_BY_CONSTRUCTION, or a spec-only " \
+          "META_DOMAIN_KNOWN_GAPS entry this module deliberately never reads)."
+      end
+    end
+  end
+end

data/lib/hecks/query_ir/rules.rb

@@ -0,0 +1,132 @@
+module Hecks
+  module QueryIR
+    # The given/ensures/invariant rules declared across a corpus, and which of them are duplicated.
+    # Extended onto `QueryIR`.
+    module Rules
+      # Every given/ensures/invariant reachable from a booted registry, walked recursively.
+      #
+      # Object identity carries no signal: `MetaValidator.call` rebuilds the graph from flat rows,
+      # so a bare `given("x")` reference and its block declaration are distinct objects by then.
+      # @param registry [Runtime::Registry] the booted registry to walk
+      # @param chapter_name [String, nil] one chapter to walk, every booted chapter when nil
+      # @return [Array<Rule>]
+      def collect_rules(registry, chapter_name = nil)
+        chapters = chapter_name ? [registry.bluebook(chapter_name)] : registry.bluebooks.values
+        chapters.flat_map { |chapter| chapter.aggregates.flat_map { |aggregate| aggregate_rules(aggregate) } }
+      end
+
+      # A rule's owner: the path a "(declared)" location names, or a command-level location
+      # with its trailing `.CommandName` stripped.
+      #
+      # @param location [String] a `Rule#location`
+      # @return [String] the owning construct's path, with `" (declared)"` or a trailing
+      #   `.CommandName` segment stripped
+      def owner_of(location)
+        return location.delete_suffix(" (declared)") if location.end_with?(" (declared)")
+
+        location.rpartition(".").first
+      end
+
+      # Groups rules by (kind, description, canonical) and reports groups with more than one
+      # real declaration, counted by owner rather than object identity (see `collect_rules`).
+      #
+      # `domains: []` scans the self-hosted meta-domain only; `nil` adds every real example.
+      # @param domains [Array<String>, nil] domain root directories to scan; every real
+      #   example (`Codemod::EXAMPLE_ROOTS`) when nil, none beyond the meta-domain when `[]`
+      # @param include_meta [Boolean] whether to also scan the self-hosted meta-domain
+      # @return [Array<Hash>] one entry per duplicate group: `:kind`, `:description`,
+      #   `:canonical`, and `:locations` (`Array<String>`)
+      def duplicates(domains: nil, include_meta: true)
+        all_rules = include_meta ? collect_rules(Codemod.meta_registry) : []
+        all_rules += (domains || Codemod::EXAMPLE_ROOTS).flat_map { |domain_dir| domain_rules(domain_dir) }
+        duplicate_groups(all_rules)
+      end
+
+      private
+
+      # @return [Array<Rule>] the rules of a real example domain, none when it has no bluebooks
+      def domain_rules(domain_dir)
+        files = Dir.glob(File.join(domain_dir, "bluebook", "*.bluebook"))
+        files.empty? ? [] : collect_rules(Codemod.load_bluebook(files))
+      end
+
+      def duplicate_groups(all_rules)
+        all_rules.group_by { |r| [r.kind, r.description, r.canonical] }
+                 .map { |key, rules| [key, rules, declaration_count(rules)] }
+                 .select { |_, _, count| count > 1 }
+                 .map do |(kind, description, canonical), rules, _|
+          { kind: kind, description: description, canonical: canonical, locations: rules.map(&:location) }
+        end
+      end
+
+      def aggregate_rules(aggregate)
+        rules = []
+        walk_construct_rules(aggregate, aggregate.hecks_name, rules)
+        aggregate.value_objects.each do |vo|
+          vo.invariants.each do |rule|
+            rules << build_rule("invariant", rule, "#{aggregate.hecks_name}::#{vo.hecks_name} (declared)")
+          end
+        end
+        rules
+      end
+
+      # Recursive walk behind `collect_rules`; appends to `rules` in place.
+      def walk_construct_rules(construct, path, rules)
+        declared_rules(construct).each { |kind, rule| rules << build_rule(kind, rule, "#{path} (declared)") }
+        construct.commands.each { |command| command_rules(command, path, rules) }
+        return unless construct.respond_to?(:entities)
+
+        construct.entities.each do |piece|
+          walk_construct_rules(piece, "#{path}.#{piece.hecks_name}", rules)
+        end
+      end
+
+      # @return [Array<Array(String, Object)>] the construct's own preconditions as `given` and its
+      #   invariants, each with the kind it is reported as
+      def declared_rules(construct)
+        givens = construct.respond_to?(:preconditions) ? construct.preconditions.map { |rule| ["given", rule] } : []
+        invariants = construct.respond_to?(:invariants) ? construct.invariants.map { |rule| ["invariant", rule] } : []
+        givens + invariants
+      end
+
+      def command_rules(command, path, rules)
+        location = "#{path}.#{command.hecks_name}"
+        command.givens.each { |rule| rules << build_rule("given", rule, location) }
+        command.ensures.each { |rule| rules << build_rule("ensures", rule, location) }
+      end
+
+      def build_rule(kind, rule, location)
+        Rule.new(kind: kind, description: rule.description, canonical: rule.canonical, location: location)
+      end
+
+      # A rule owned by a nested entity is also covered by a "(declared)" entry anywhere under the
+      # same root aggregate, matching the DSL's shared given pool.
+      #
+      # Known gap: a bare chapter-wide `given(desc)` reference still shows as its own "(declared)"
+      # owner, because the built IR cannot tell a reference from a declaration. Verify a flagged
+      # group by hand before treating it as fresh duplication.
+      # @param rules [Array<Rule>] one duplicate-key group's own rules
+      # @return [Integer] how many of `rules` are real, independent declarations
+      def declaration_count(rules)
+        declared = rules.select { |r| r.location.end_with?(" (declared)") }
+        declared_owners = declared.to_set { |r| owner_of(r.location) }
+        declared_given_roots = given_roots(declared)
+
+        declared_owners.size + rules.count { |rule| !covered?(rule, declared_owners, declared_given_roots) }
+      end
+
+      # @return [Set<String>] the root aggregates owning a "(declared)" `given`
+      def given_roots(declared)
+        declared.select { |r| r.kind == "given" }.to_set { |r| owner_of(r.location).split(".").first }
+      end
+
+      # @return [Boolean] whether a "(declared)" entry already accounts for the rule
+      def covered?(rule, declared_owners, declared_given_roots)
+        owner = owner_of(rule.location)
+        return true if declared_owners.include?(owner)
+
+        rule.kind == "given" && owner.include?(".") && declared_given_roots.include?(owner.split(".").first)
+      end
+    end
+  end
+end