hecks 3.5.0 → 3.6.0

data/lib/hecks/codemod/sweep.rb

@@ -0,0 +1,94 @@
+module Hecks
+  module Codemod
+    # Judges candidate edits to a set of bluebook files one at a time: each is applied, the files
+    # are re-booted, and the edit is kept when the booted IR is unchanged and reverted when it is
+    # not. A dry run stages every edit in memory and reverts it, still counting a safe one as
+    # applied, so the next candidate is judged against the true original state.
+    class Sweep
+      # What one sweep runs over.
+      #
+      # - `files`: the bluebook files an edit may land in
+      # - `before`: what booting the unedited files answered, which a safe edit leaves alone
+      # - `no_match_file`: what a candidate no file's source line matches is reported under
+      # - `failure_file`: answers what a reverted edit to a target file is reported under
+      # - `reboot`: boots the files as they stand, answering what to compare with `before`
+      # - `stage_files`: answers which files an edit to a target file stages
+      # - `reason`: words why an edit was reverted, given the error the reboot raised or nil
+      Setup = Struct.new(:files, :before, :no_match_file, :failure_file, :reboot, :stage_files, :reason,
+                         keyword_init: true)
+
+      # @param runner [Runner] the codemod run, which knows how to apply and label a candidate
+      # @param setup [Setup] what to sweep
+      # @param results [Hash{Symbol => Array}] the run's `:applied`, `:skipped` and `:clean`
+      # @param dry_run [Boolean] whether to leave every file as it was
+      def initialize(runner, setup, results, dry_run)
+        @runner = runner
+        @setup = setup
+        @results = results
+        @dry_run = dry_run
+        @live = setup.files.to_h { |file| [file, File.read(file)] }
+        @applied = Hash.new { |hash, file| hash[file] = [] }
+      end
+
+      # Judges each candidate, then records what was applied under the file it landed in.
+      #
+      # @param candidates [Array<Object>] what the codemod found to edit
+      # @return [void]
+      def call(candidates)
+        candidates.each { |candidate| judge(candidate) }
+        @applied.each do |file, applied|
+          @results[:applied] << { file: file, candidates: applied.map(&@runner.label) }
+        end
+      end
+
+      private
+
+      def judge(candidate)
+        target = @setup.files.find { |file| @runner.apply_candidate.call(@live[file], candidate).last }
+        return skip(@setup.no_match_file, "no matching source line", candidate) unless target
+
+        original = edit(target, candidate)
+        after, error = Codemod.safely(&@setup.reboot)
+        return keep(target, original, candidate) if after == @setup.before
+
+        reject(target, original, error, candidate)
+      end
+
+      # Applies the candidate to the target's text and stages it.
+      #
+      # @return [String] the target's text before the edit
+      def edit(target, candidate)
+        original = @live[target]
+        @live[target] = @runner.apply_candidate.call(original, candidate).first
+        stage(target)
+        original
+      end
+
+      def reject(target, original, error, candidate)
+        revert(target, original)
+        skip(@setup.failure_file.call(target), @setup.reason.call(error), candidate)
+      end
+
+      def keep(target, original, candidate)
+        revert(target, original) if @dry_run
+        @applied[target] << candidate
+      end
+
+      def stage(target)
+        @setup.stage_files.call(target).each { |file| Codemod.stage(file, @live[file], dry_run: @dry_run) }
+      end
+
+      # Puts the target's original text back and re-boots, so memoized state matches the reverted
+      # text.
+      def revert(target, original)
+        @live[target] = original
+        @setup.stage_files.call(target).each { |file| Codemod.unstage(file, @live[file], dry_run: @dry_run) }
+        Codemod.safely(&@setup.reboot)
+      end
+
+      def skip(file, reason, candidate)
+        @results[:skipped] << { file: file, reason: reason, candidates: [@runner.label.call(candidate)] }
+      end
+    end
+  end
+end

data/lib/hecks/codemod.rb

@@ -1,5 +1,6 @@
 require_relative "bluebook/meta_validator"
 require_relative "corpus"
+require_relative "codemod/runner"
 
 module Hecks
   # Shared machinery for a codemod that migrates real `.bluebook` source: boot,
@@ -18,6 +19,7 @@ module Hecks
     EXTRACTION_PORT  = File.join(ROOT, "lib/hecks/ports/extraction.port")
     MEMORY_ADAPTER   = File.join(ROOT, "lib/hecks/adapters/driven/memory.adapter")
     PRISM_ADAPTER    = File.join(ROOT, "lib/hecks/adapters/driven/prism.adapter")
+    BOOT_FILES       = [PERSISTENCE_PORT, EXTRACTION_PORT, MEMORY_ADAPTER, PRISM_ADAPTER].freeze
 
     def self.export_json(registry) = Hecks::Projector::Exporter.json(registry)
 
@@ -93,27 +95,27 @@ module Hecks
     # Forgets each path's cached AST first — a stale tree after editing a file
     # misreports that file's own source locations.
     def self.load_bluebook(path)
-      paths = if path.is_a?(Array)
-                path
-              elsif File.directory?(path)
-                Dir.glob(File.join(path, "*.bluebook"))
-              else
-                [path]
-              end
+      paths = bluebook_paths(path)
       paths.each { |file| Hecks::Adapters::Prism.forget(file) }
 
       registry = Hecks::Runtime::Registry.new
       Hecks.with_registry(registry) do
-        Kernel.load(PERSISTENCE_PORT)
-        Kernel.load(EXTRACTION_PORT)
-        Kernel.load(MEMORY_ADAPTER)
-        Kernel.load(PRISM_ADAPTER)
+        BOOT_FILES.each { |file| Kernel.load(file) }
         Hecks::Bluebook::MetaValidator.defer { paths.each { |file| Kernel.load(file) } }
         Hecks::Bluebook::MetaValidator.judge_deferred!(registry)
       end
       registry
     end
 
+    # @param path [String, Array<String>] a bluebook file, a directory of them, or a list of files
+    # @return [Array<String>] the bluebook files it names
+    def self.bluebook_paths(path)
+      return path if path.is_a?(Array)
+
+      File.directory?(path) ? Dir.glob(File.join(path, "*.bluebook")) : [path]
+    end
+    private_class_method :bluebook_paths
+
     # Forgets every tree, not just one — callers rarely know which of the
     # meta-domain's several files they just edited.
     def self.boot_meta
@@ -151,10 +153,7 @@ module Hecks
       list_attr = owner_attribute(construct, list_field)
       return nil unless list_attr&.list?
 
-      value_objects = construct.respond_to?(:value_objects) ? construct.value_objects : []
-      entities      = construct.respond_to?(:entities) ? construct.entities : []
-      matches = (value_objects + entities).select { |c| c.hecks_name.to_s == list_attr.type.to_s }
-
+      matches = element_candidates(construct).select { |c| c.hecks_name.to_s == list_attr.type.to_s }
       if matches.size > 1
         raise "#{construct.hecks_name}##{list_field} names #{list_attr.type}, held by both a value " \
               "object and an entity — ambiguous, cannot resolve which one the list holds"
@@ -163,6 +162,14 @@ module Hecks
       matches.first
     end
 
+    # @return [Array<Object>] the construct's value objects and entities, whichever it has
+    def self.element_candidates(construct)
+      value_objects = construct.respond_to?(:value_objects) ? construct.value_objects : []
+      entities      = construct.respond_to?(:entities) ? construct.entities : []
+      value_objects + entities
+    end
+    private_class_method :element_candidates
+
     # Rescues StandardError only, so a genuine bug still raises rather than
     # silently counting as an unsafe candidate to revert.
     def self.safely
@@ -170,155 +177,5 @@ module Hecks
     rescue StandardError => e
       [nil, "#{e.class}: #{e.message}"]
     end
-
-    # Runs one codemod rule across every example domain and the meta-domain,
-    # verifying each candidate edit via IR diff before keeping it.
-    class Runner
-      def initialize(find_candidates:, apply_candidate:, label:)
-        @find_candidates = find_candidates
-        @apply_candidate = apply_candidate
-        @label = label
-      end
-
-      def run(dry_run: false)
-        results = { applied: [], skipped: [], clean: [] }
-        run_example_domains(results, dry_run)
-        run_meta_domain(results, dry_run)
-        results
-      end
-
-      def report(results, dry_run:)
-        puts "== results (#{dry_run ? 'DRY RUN — nothing written' : 'applied'}) =="
-        puts "clean (no candidates): #{results[:clean].join(', ')}" unless results[:clean].empty?
-        results[:applied].each { |r| puts "APPLIED  #{r[:file]}: #{r[:candidates].join(', ')}" }
-        results[:skipped].each { |r| puts "SKIPPED  #{r[:file]} (#{r[:reason]}): #{Array(r[:candidates]).join(', ')}" }
-      end
-
-      private
-
-      def apply_many(text, candidates)
-        applied = []
-        candidates.each do |c|
-          text, changed = @apply_candidate.call(text, c)
-          applied << c if changed
-        end
-        [text, applied]
-      end
-
-      # Kept as one method: the write/verify/revert sequence is a single unit,
-      # and splitting it would scatter shared state for no readability gain.
-      # rubocop:disable-next Metrics/AbcSize
-      # rubocop:disable-next Metrics/BlockLength
-      # rubocop:disable-next Metrics/CyclomaticComplexity
-      # rubocop:disable-next Metrics/MethodLength
-      # rubocop:disable-next Metrics/PerceivedComplexity
-      def run_example_domains(results, dry_run)
-        Codemod::EXAMPLE_ROOTS.each do |domain_dir|
-          bluebook_files = Dir.glob(File.join(domain_dir, "bluebook", "*.bluebook"))
-          next if bluebook_files.empty?
-
-          before_json = Codemod.export_json(Codemod.load_bluebook(bluebook_files))
-          candidates  = @find_candidates.call(Codemod.load_bluebook(bluebook_files))
-
-          if candidates.empty?
-            results[:clean] << domain_dir
-            next
-          end
-
-          live = bluebook_files.to_h { |file| [file, File.read(file)] }
-          applied_by_file = Hash.new { |hash, file| hash[file] = [] }
-
-          candidates.each do |candidate|
-            target_file = bluebook_files.find { |file| apply_many(live[file], [candidate]).last.any? }
-            unless target_file
-              results[:skipped] << { file: domain_dir, reason: "no matching source line", candidates: [@label.call(candidate)] }
-              next
-            end
-
-            original_text = live[target_file]
-            text, = apply_many(original_text, [candidate])
-            live[target_file] = text
-            Codemod.stage(target_file, text, dry_run: dry_run)
-            after_json, error = Codemod.safely do
-              Codemod.export_json(Codemod.load_bluebook(bluebook_files))
-            end
-
-            if after_json == before_json && !dry_run
-              applied_by_file[target_file] << candidate
-            elsif after_json == before_json
-              live[target_file] = original_text
-              Codemod.unstage(target_file, original_text, dry_run: dry_run)
-              Codemod.safely { Codemod.load_bluebook(bluebook_files) }
-              applied_by_file[target_file] << candidate
-            else
-              live[target_file] = original_text
-              Codemod.unstage(target_file, original_text, dry_run: dry_run)
-              Codemod.safely { Codemod.load_bluebook(bluebook_files) }
-              reason = error ? "reboot raised after edit (#{error}) — reverted" : "IR changed after edit — reverted"
-              results[:skipped] << { file: target_file, reason: reason, candidates: [@label.call(candidate)] }
-            end
-          end
-
-          applied_by_file.each do |file, applied|
-            results[:applied] << { file: file, candidates: applied.map(&@label) }
-          end
-        end
-      end
-
-      # Per-candidate, not batched — the meta-domain is one shared,
-      # self-dispatching registry (S14), so a single unsafe candidate could
-      # otherwise sink every other, genuinely safe one in the same run.
-      # rubocop:disable-next Metrics/AbcSize
-      # rubocop:disable-next Metrics/CyclomaticComplexity
-      # rubocop:disable-next Metrics/PerceivedComplexity
-      def run_meta_domain(results, dry_run)
-        before_meta     = Codemod.boot_meta
-        meta_candidates = @find_candidates.call(Codemod.meta_registry)
-
-        if meta_candidates.empty?
-          results[:clean] << "meta-domain"
-          return
-        end
-
-        live_meta = Codemod::META_FILES.to_h { |f| [f, File.read(f)] }
-        applied_by_file = Hash.new { |h, k| h[k] = [] }
-
-        meta_candidates.each do |candidate|
-          target_file = Codemod::META_FILES.find { |f| apply_many(live_meta[f], [candidate]).last.any? }
-          unless target_file
-            results[:skipped] << { file: "meta-domain", reason: "no matching source line", candidates: [@label.call(candidate)] }
-            next
-          end
-
-          text, = apply_many(live_meta[target_file], [candidate])
-          original_text = live_meta[target_file]
-          live_meta[target_file] = text
-          Codemod::META_FILES.each { |f| Codemod.stage(f, live_meta[f], dry_run: dry_run) }
-
-          # A dry run stages the text in memory and reboots from it, then drops it — so the next
-          # candidate is judged against the true original state and no file is written.
-          after_meta, error = Codemod.safely { Codemod.boot_meta }
-
-          if after_meta == before_meta && !dry_run
-            applied_by_file[target_file] << candidate
-          elsif after_meta == before_meta # dry-run, safe — revert, but count as applied
-            live_meta[target_file] = original_text
-            Codemod::META_FILES.each { |f| Codemod.unstage(f, live_meta[f], dry_run: dry_run) }
-            Codemod.safely { Codemod.boot_meta }
-            applied_by_file[target_file] << candidate
-          else
-            live_meta[target_file] = original_text
-            Codemod::META_FILES.each { |f| Codemod.unstage(f, live_meta[f], dry_run: dry_run) }
-            Codemod.safely { Codemod.boot_meta } # resync memoized state to the reverted text
-            reason = error ? "reboot raised (#{error})" : "IR changed"
-            results[:skipped] << { file: "meta-domain", reason: reason, candidates: [@label.call(candidate)] }
-          end
-        end
-
-        applied_by_file.each do |file, candidates|
-          results[:applied] << { file: file, candidates: candidates.map(&@label) }
-        end
-      end
-    end
   end
 end

data/lib/hecks/corpus/routes.rb

@@ -0,0 +1,34 @@
+module Hecks
+  module Corpus
+    # A route sends what the sweep does not boot elsewhere; each entry's
+    # `check` (:named_in, :gitignored, :gap) is verified by
+    # spec/corpus_accounting_spec.rb, matched in order.
+    Route = Struct.new(:pattern, :check, :destination, :names, :why)
+
+    ROUTES = [
+      Route.new(%r{\Atmp/}, :gitignored, ".gitignore", "tmp/",
+                "scratch output — generated and mined candidate domains, fuzz failures — never committed"),
+      Route.new(%r{/\.aws-sam/}, :gitignored, ".gitignore", ".aws-sam/",
+                "SAM build output — a vendored copy of real sources, never committed"),
+      Route.new(%r{/data/eras/}, :gitignored, ".gitignore", "**/data/eras/",
+                "era snapshots a file adapter writes at runtime, never committed"),
+      Route.new(%r{\Arust/}, :named_in, "rust/parser/tests/gates.rs", :each_file,
+                "the Rust parser's own fixtures, each loaded by its gate tests"),
+      Route.new(%r{/translations/}, :named_in, "spec/translation/committed_edges_spec.rb", "bluebook/translations",
+                "translation edges, not chapters; each must load, chain era to era, and end at the storage " \
+                "shape its bluebook declares today"),
+      Route.new(%r{\Alib/hecks/forms/examples/}, :named_in, "spec/forms/app_spec.rb", :each_file,
+                "a Forms presentation config wearing the .bluebook extension"),
+      Route.new(%r{\Aspec/fixtures/eras/}, :named_in, "spec/runtime/storage_shape_spec.rb", "fixtures/eras",
+                "deliberately conflicting versions of one domain; each must classify as the verdict " \
+                "its filename declares (bump_* / same_*)"),
+      Route.new(%r{\Aspec/fixtures/model_check/}, :named_in, "spec/model_check_spec.rb", :each_file,
+                "domains broken on purpose; each must produce exactly the finding kinds it is built to trigger"),
+      # hecks fuzz sweeps it too, once Fuzzing::Replay coerces value-object args
+      # before recomputing givens — today it doesn't, so this given reads as
+      # wrongly admitted.
+      Route.new(%r{\Aspec/fixtures/rust_host/}, :named_in, "rust/host/src/web.rs", "checkout_fixture",
+                "the Rust host's checkout fixture, pinned by its web and /api tests")
+    ].freeze
+  end
+end

data/lib/hecks/corpus/rust.rb

@@ -0,0 +1,193 @@
+module Hecks
+  module Corpus
+    # Every Rust-facing list reads `rust/Cargo.toml`'s `[features]` as its
+    # one source, rather than each consumer typing it out by hand.
+    GENERATED_DIR = "rust/src/generated".freeze
+    RUST_DOMAIN_KINDS = %i[example stress fixture].freeze
+
+    RustDomain = Struct.new(:feature, :dir, :kind)
+
+    # `check: :named_in` — `destination` must name `names`.
+    Elsewhere = Struct.new(:check, :destination, :names, :why)
+
+    RUST_ELSEWHERE = {
+      "meta" => Elsewhere.new(:named_in, "lib/hecks/tools/regeneration_run.rb", "rust/src/generated",
+                              "the self-hosted grammar (lib/hecks/language), not a domain directory — every " \
+                              "hecks project_rust run rewrites it, so the drift check diffs it with the rest " \
+                              "of rust/src/generated, and there is no directory to fuzz")
+    }.freeze
+
+    # **Shrink-only**: a generated module `hecks rust_coverage` still flags.
+    # `hecks corpus_rust_coverage --rust-coverage` requires each entry to still fail, so a
+    # newly-passing module breaks the build until removed here.
+    RUST_COVERAGE_PENDING = {}.freeze
+
+    # The stamp hecks project_rust writes into metadata.rs, e.g.
+    # `examples/pizzas` or `the self-hosted language (...)`, with any
+    # ` (attaches "X")`/` (attaches "x", from: :vendor)` suffix stripped.
+    SOURCE_STAMP = /
+      GENERATED\ by\ hecks\ project_rust\ —\ (.+?)
+      (?:\ \(attaches\ "\w+"(?:,\ from:\ :vendor)?\))?
+      's\ own\ canonical\ IR,
+    /x
+
+    # The Rust-facing lists: which domains and chapters `rust/` carries, read off Cargo's
+    # `[features]` and the generated modules rather than typed out by hand. Extended onto
+    # `Corpus`.
+    module Rust
+      # Every place a Rust-facing domain's own `attaches` attachment could be declared.
+      #
+      # @param root [String] repository root to search under
+      # @return [String] every reachable hecksagon file's own text, joined by newlines
+      def rust_attachment_hecksagon_text(root: ROOT)
+        rust_domains(root: root).flat_map { |domain| Dir.glob(File.join(domain.dir, "**", "*.hecksagon")) }
+                                .map { |path| File.read(path) }.join("\n")
+      end
+
+      # The Cargo `[features]` table's raw text.
+      #
+      # @param root [String] repository root to search under
+      # @return [String] the table's text, or `""` when `rust/Cargo.toml` has none
+      def cargo_features_table(root: ROOT)
+        File.read(File.join(root, "rust/Cargo.toml"))[Fuzzing::TargetCapabilities::FEATURES_TABLE] || ""
+      end
+
+      # Every feature name Cargo declares with no dependency array of its own.
+      #
+      # @param root [String] repository root to search under
+      # @return [Array<String>] feature names, in file order
+      def cargo_features(root: ROOT)
+        cargo_features_table(root: root).scan(/^(\w+)\s*=\s*\[\]/).flatten
+      end
+
+      # The feature `hecks project_rust` last wrote as Cargo's `default`.
+      #
+      # @param root [String] repository root to search under
+      # @return [String, nil] the default feature's name, or nil when Cargo.toml
+      #   declares none
+      def cargo_default(root: ROOT)
+        cargo_features_table(root: root)[/^default\s*=\s*\["(\w+)"\]/, 1]
+      end
+
+      # Every in-repo domain directory whose name is a Cargo feature, sorted
+      # by path — disambiguated by the generated module's metadata.rs stamp when one exists.
+      #
+      # @param root [String] repository root to search under
+      # @return [Array<RustDomain>] each Rust-facing domain, sorted by directory path
+      def rust_domains(root: ROOT)
+        features = cargo_features(root: root)
+        members(*RUST_DOMAIN_KINDS, root: root)
+          .map { |member| [domain_dir_of(member), member.kind] }
+          .uniq(&:first)
+          .select { |dir, _| rust_domain_dir?(dir, features, root) }
+          .sort_by(&:first)
+          .map { |dir, kind| RustDomain.new(File.basename(dir).downcase, dir, kind) }
+      end
+
+      # Tells whether `dir` is the real source directory for its Cargo feature.
+      #
+      # @param dir [String] a candidate domain directory
+      # @param features [Array<String>] known Cargo feature names
+      # @param root [String] repository root `dir` is rooted under
+      # @return [Boolean]
+      def rust_domain_dir?(dir, features, root)
+        feature = File.basename(dir).downcase
+        source = generated_source(feature, root: root)
+        features.include?(feature) && (source.nil? || source == dir.delete_prefix("#{root}/"))
+      end
+
+      # Where a generated module came from, read off the stamp `hecks project_rust`
+      # writes into its metadata.rs.
+      #
+      # @param module_name [String] a generated module's name
+      # @param root [String] repository root to search under
+      # @return [String, nil] the source path the stamp names, or nil when the module
+      #   is not generated
+      def generated_source(module_name, root: ROOT)
+        metadata = File.join(root, GENERATED_DIR, module_name, "metadata.rs")
+        File.file?(metadata) ? File.read(metadata)[SOURCE_STAMP, 1] : nil
+      end
+
+      # Every module directory under `rust/src/generated`.
+      #
+      # @param root [String] repository root to search under
+      # @return [Array<String>] generated module names, sorted
+      def generated_modules(root: ROOT)
+        Dir.children(File.join(root, GENERATED_DIR)).select { |name| File.directory?(File.join(root, GENERATED_DIR, name)) }.sort
+      end
+
+      # Tells whether `feature` has already been generated (has a merged.rs).
+      #
+      # @param feature [String] a Cargo feature / domain name
+      # @param root [String] repository root to search under
+      # @return [Boolean]
+      def generated?(feature, root: ROOT)
+        File.file?(File.join(root, GENERATED_DIR, feature, "merged.rs"))
+      end
+
+      # Chapters attached via `kind` that get a generated module as a side
+      # effect of the attaching domain's regen, with no merged.rs of their own.
+      #
+      # @param kind [Symbol] :framework or :vendored
+      # @param root [String] repository root to search under
+      # @return [Array<String>] stems with a generated module but no merged.rs
+      #   of their own
+      def rust_side_chapters(kind, root: ROOT)
+        modules = generated_modules(root: root)
+        members(kind, root: root).map(&:stem)
+                                 .select do |stem|
+                                   module_name = Naming.pascal(stem).downcase
+                                   modules.include?(module_name) && !generated?(module_name, root: root)
+                                 end
+      end
+
+      # The generated module name a `:framework`/`:vendored` stem writes
+      # under — strips underscores, so it can differ from the raw stem.
+      #
+      # @param stem [String] a `:framework`/`:vendored` corpus member's stem
+      # @return [String] the generated module's own directory name
+      def rust_side_module_name(stem)
+        Naming.pascal(stem).downcase
+      end
+
+      # Names the framework chapters Rust carries as modules, beside its domains' own bluebooks.
+      #
+      # @param root [String] repository root to search under
+      # @return [Array<String>] generated module names for the `:framework` corpus members
+      def rust_framework_chapters(root: ROOT)
+        rust_side_chapters(:framework, root: root)
+      end
+
+      # Names the vendored chapters Rust carries as modules, beside its domains' own bluebooks.
+      #
+      # @param root [String] repository root to search under
+      # @return [Array<String>] generated module names for the `:vendored` corpus members
+      def rust_vendored_chapters(root: ROOT)
+        rust_side_chapters(:vendored, root: root)
+      end
+
+      # Chapters an in-repo Rust domain carries beside its own bluebook,
+      # written as a module by `hecks project_rust` with no merged.rs of its own.
+      #
+      # @param root [String] repository root to search under
+      # @return [Array<String>] generated module names with no merged.rs of their own
+      def rust_sibling_chapters(root: ROOT)
+        modules = generated_modules(root: root)
+        rust_domains(root: root)
+          .flat_map { |domain| Dir.glob(File.join(domain.dir, "bluebook", "*.bluebook")) }
+          .map { |path| Naming.pascal(File.basename(path, ".bluebook")).downcase }
+          .uniq
+          .select { |name| modules.include?(name) && !generated?(name, root: root) }
+      end
+
+      # The regeneration order the drift check runs, sorted by path — so which
+      # domain wins Cargo's `default` is derived, not hand-picked.
+      #
+      # @param root [String] repository root to search under
+      # @return [Array<RustDomain>] already-generated Rust domains, in regeneration order
+      def rust_regen_order(root: ROOT)
+        rust_domains(root: root).select { |domain| generated?(domain.feature, root: root) }
+      end
+    end
+  end
+end

data/lib/hecks/corpus/sources.rb

@@ -0,0 +1,46 @@
+module Hecks
+  module Corpus
+    # How a domain's hecksagon names a chapter the gem carries and loads by name, as the QA
+    # ledger's does (`Hecks::Chapters.load!("QualityControl")`).
+    ATTACHED_CHAPTER = /Chapters\.load!\(\s*"([^"]+)"\s*\)/
+
+    # Where a domain path keeps its bluebooks, and what a member boots. Extended onto `Corpus`.
+    module Sources
+      # Where a domain path keeps its bluebooks — `<domain>/bluebook/*.bluebook`, or the directory
+      # itself when that holds none, or the chapter files its hecksagons load by name (the QA
+      # ledger, `qa/bluebook`, holds only wiring: its chapter ships in
+      # `lib/hecks/quality_control/`).
+      #
+      # @param domain_path [String] path to a domain directory
+      # @return [Array<String>, nil] `.bluebook` file paths found, or nil when none
+      def bluebook_files(domain_path)
+        [File.join(domain_path, "bluebook"), domain_path].each do |dir|
+          files = Dir[File.join(dir, "*.bluebook")]
+          return files unless files.empty?
+        end
+        attached_chapter_files(domain_path)
+      end
+
+      # The bluebook files of every chapter a domain's own hecksagons load by name.
+      #
+      # @param domain_path [String] path to a domain directory
+      # @return [Array<String>, nil] the chapters' `.bluebook` file paths, or nil when none is named
+      def attached_chapter_files(domain_path)
+        names = Dir[File.join(domain_path, "{bluebook/,}*.hecksagon")]
+                .flat_map { |path| File.read(path).scan(ATTACHED_CHAPTER).flatten }.uniq
+        files = names.flat_map { |name| Chapters.index.fetch(name, []) }
+        files.empty? ? nil : files
+      end
+
+      # The directory holding `domain_path`'s bluebooks.
+      #
+      # @param domain_path [String] path to a domain directory
+      # @return [String, nil] directory of the first `.bluebook` file found, or nil
+      #   when `domain_path` holds none
+      def bluebook_dir(domain_path)
+        files = bluebook_files(domain_path)
+        files && File.dirname(files.first)
+      end
+    end
+  end
+end