hecks 5.0.0 → 7.0.0

data/lib/hecks/composer/web.rb

@@ -138,13 +138,14 @@ module Hecks
       end
 
       def check(body)
-        json(200, Check.call(dir: workspace, buffers: buffers(body), chapter_name: body["chapter_name"]))
+        json(200, Check.call(dir: workspace, buffers: buffers(body), declaration_name: body["bluebook_name"]))
       end
 
       def buffers(body) = body.fetch("buffers", {})
 
       def body(request)
-        raw = request.body&.read.to_s
+        stream = request.body
+        raw = stream&.read.to_s
         raw.empty? ? {} : JSON.parse(raw)
       end
 

data/lib/hecks/composer/workbench.rb

@@ -9,12 +9,22 @@ module Hecks
     # the agent that edits it and the panels beneath the editor. Opening another domain builds a
     # new workbench, so nothing of the old workspace carries over.
     class Workbench
+      # The registry of one agent adapter: the real `claude`, or a scripted `fake`.
+      #
+      # @param name [String, nil] `claude` (the default) or `fake`
+      # @return [Runtime::Registry] a registry holding the `composer_agent` port and that adapter
+      def self.agents_named(name)
+        adapter = name == "fake" ? "fake_agent" : "claude_composer"
+        require_relative "adapters/#{adapter}"
+        Agent.registry_with(File.join(Agent::ADAPTERS, "#{adapter}.adapter"))
+      end
+
       # @return [String] the domain directory this workbench is for
       attr_reader :workspace
 
       # @param workspace [String] the domain directory
       # @param agents [Runtime::Registry, nil] a registry holding the `composer_agent` port and one
-      #   adapter; the one `HECKS_COMPOSER_AGENT` names (`claude`, the default, or `fake`) when nil
+      #   adapter; the real `claude` one when nil
       def initialize(workspace:, agents: nil)
         @workspace = File.expand_path(workspace)
         @agents = agents
@@ -38,14 +48,7 @@ module Hecks
 
       private
 
-      def agents = @agents ||= default_agents
-
-      # The adapter `HECKS_COMPOSER_AGENT` names: the real `claude`, or a scripted `fake`.
-      def default_agents
-        name = ENV.fetch("HECKS_COMPOSER_AGENT", "claude") == "fake" ? "fake_agent" : "claude_composer"
-        require_relative "adapters/#{name}"
-        Agent.registry_with(File.join(Agent::ADAPTERS, "#{name}.adapter"))
-      end
+      def agents = @agents ||= self.class.agents_named("claude")
     end
   end
 end

data/lib/hecks/composer.rb

@@ -11,7 +11,7 @@ require_relative "composer/check"
 
 module Hecks
   # The Composer's outside, on the hecksagon side: staging a workspace, judging its text and
-  # projecting what it declares. The Composer chapter's bluebook is in `composer/bluebook/`.
+  # projecting what it declares. The Composer bluebook's bluebook is in `composer/bluebook/`.
   module Composer
   end
 end

data/lib/hecks/construct.rb

@@ -4,8 +4,8 @@ module Hecks
   #
   # The fully-qualified name walks owners and matches the id `MetaValidator::Judge#identify` mints.
   #
-  #     Pizzas                     the chapter, no owner
-  #     Pizzas::Pizza              an aggregate joins its chapter with ::
+  #     Pizzas                     the bluebook, no owner
+  #     Pizzas::Pizza              an aggregate joins its bluebook with ::
   #     Pizzas::Pizza.Price        everything else joins its owner with .
   #     price = Class.new(ValueObject)   # a declaration holder
   #     price.hecks_name  = "Price"
@@ -15,17 +15,17 @@ module Hecks
     # A construct asked for an identity it cannot compute.
     class Unowned < StandardError; end
 
-    # What declares this construct; nil for a chapter, which is the top.
+    # What declares this construct; nil for a bluebook, which is the top.
     attr_accessor :hecks_owner
 
     attr_writer :hecks_name
 
-    # Marks a chapter, the only construct that legitimately has no owner.
+    # Marks a bluebook, the only construct that legitimately has no owner.
     attr_writer :hecks_root
 
     # Whether this construct is the top of its own owner chain.
     #
-    # @return [Boolean] true for a chapter, which sets `hecks_root`; false otherwise
+    # @return [Boolean] true for a bluebook, which sets `hecks_root`; false otherwise
     def hecks_root? = @hecks_root ? true : false
 
     # The name as the bluebook declares it, never the constant path.
@@ -41,9 +41,9 @@ module Hecks
     # Refuses rather than answering a bare name for an unstamped construct.
     #
     # @return [String] the fully-qualified name, joining every owner from the
-    #   chapter down to this construct
+    #   bluebook down to this construct
     # @raise [Construct::Unowned] if this construct has no owner and is not itself
-    #   a chapter (root)
+    #   a bluebook (root)
     def hecks_fqn
       return hecks_name.to_s if hecks_root?
 

data/lib/hecks/corpus/adapters.rb

@@ -13,7 +13,8 @@ module Hecks
       # @return [Array<String>] absolute paths, sorted, none under a vendored, `node_modules`,
       #   `target` or scratch directory
       def adapter_files(root: Corpus::ROOT)
-        ADAPTER_GLOBS.flat_map { |glob| Dir.glob(File.join(root, glob)) }.uniq.sort.reject do |path|
+        found = ADAPTER_GLOBS.flat_map { |glob| Dir.glob(File.join(root, glob)) }.uniq.sort
+        found.reject do |path|
           path.delete_prefix("#{root}/").split("/").intersect?(EXCLUDED_DIRS)
         end
       end

data/lib/hecks/corpus/generated_key.rb

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Hecks
+  module Corpus
+    # A content hash of everything that decides what `hecks regenerate_corpus` writes for some of
+    # the corpus's domains: the generator, and each named domain's own sources. A job that reads a
+    # few domains of the generated tree keys its cache on those, so a change to any other domain
+    # leaves its cache where it was.
+    #
+    # The hash reads file contents only, never a time, and only tracked files: a bare checkout and
+    # one that has already regenerated hash the same. It errs wide, never narrow: a file that might
+    # be read is hashed, so a key can move for a change that did not matter, and never stay put for
+    # one that did.
+    #
+    #   Hecks::Corpus::GeneratedKey.key(%w[lease_clock nested_pieces])  # => "9c1e..."
+    module GeneratedKey
+      # Bumped when what the key hashes changes shape, so every saved entry stops matching.
+      VERSION = "1"
+
+      # What the generator is made of, relative to the checkout: the Rust crates it runs, and the
+      # Ruby that builds the IR it reads. Every domain's output depends on all of it.
+      GENERATOR_INPUTS = %w[
+        rust/codegen/**/* rust/build/**/* rust/parser/**/* rust/Cargo.toml rust/src/generated/mod.rs
+        lib/hecks/rust_build/**/* lib/hecks/projector/**/* lib/hecks/corpus/**/* lib/hecks/corpus.rb
+        lib/hecks/tools/regeneration_run.rb lib/hecks/tools/regeneration_run/**/*
+        lib/hecks/bluebook/**/* lib/hecks/language/**/*
+        lib/hecks/runtime/**/* lib/hecks/ports/**/* lib/hecks/rust_format.rb rust-toolchain.toml Gemfile.lock
+        lib/hecks/*.rb lib/hecks/grammar/**/* lib/hecks/literal/**/*
+        lib/hecks/adapters/driven/*.adapter lib/hecks/adapters/driven/folder*
+      ].freeze
+
+      # The generated modules hashed into every key, whichever domains are named: pizzas, whose
+      # translations carry SQL only the Ruby toolchain compiles, so it is not a function of its
+      # own bluebook alone.
+      COMMITTED_OUTPUT = %w[pizzas].freeze
+
+      # Every bluebook, hecksagon, world and adapter file of the gem: what a domain that attaches a
+      # bluebook this key cannot name exactly is hashed against.
+      ALL_BLUEBOOK_FILES = %w[lib/hecks/**/*.bluebook lib/hecks/**/*.hecksagon lib/hecks/**/*.world
+                              lib/hecks/**/adapters/*.adapter].freeze
+
+      # The one way a hecksagon attaches a gem bluebook or a vendored package, which this key can
+      # follow exactly.
+      ATTACHES_LINE = /\A\s*attaches\s+"(?<name>\w+)"(?<vendored>,\s*from:\s*:vendor)?\s*(?:#.*)?\z/
+
+      # Any other line that names an attachment, which this key cannot follow: it hashes wide.
+      ATTACHMENT_WORD = /\battaches\b|FrameworkBluebooks\.|\battach!|Framework\.load!/
+
+      # The files a hecksagon's own text can name an attachment in.
+      ATTACHING_FILES = /\.(hecksagon|world|adapter)\z/
+
+      # The directory of the gem's Ruby, which a bluebook's absolute path is read relative to.
+      GEM_LIB = File.expand_path("..", __dir__).freeze
+
+      # Raised inside this module when an attachment cannot be followed to the files it reads.
+      class Unresolved < StandardError; end
+
+      module_function
+
+      # The key of the generated output of the named domains.
+      #
+      # @param names [Array<String>, nil] feature names; nil names every domain
+      # @param root [String] the checkout
+      # @return [String] the hex digest
+      # @raise [UnknownDomain] when a name is not a domain, listing the valid ones
+      def key(names = nil, root: ROOT)
+        digest(listing(names, root: root))
+      end
+
+      # @param lines [Array<String>] the rows of `listing`
+      # @return [String] the hex digest the rows add up to
+      def digest(lines) = Digest::SHA256.hexdigest("generated-key-#{VERSION}\n#{lines.join("\n")}")
+
+      # What `hecks corpus_run.generated_key` answers: the key, with each file hashed above it when
+      # they are asked for.
+      #
+      # @param names [Array<String>, nil] feature names; nil names every domain
+      # @param files [Boolean] whether to list each file hashed, with its own digest
+      # @param root [String] the checkout
+      # @return [String] the lines
+      # @raise [UnknownDomain] when a name is not a domain, listing the valid ones
+      def report(names = nil, files: false, root: ROOT)
+        rows = listing(names, root: root)
+        [*(rows if files), digest(rows)].join("\n")
+      end
+
+      # Each file the key hashes, with its own digest, so a reviewer can see why a key moved.
+      #
+      # @param names [Array<String>, nil] feature names; nil names every domain
+      # @param root [String] the checkout
+      # @return [Array<String>] `"<sha256>  <path>"` rows, sorted by path
+      # @raise [UnknownDomain] when a name is not a domain, listing the valid ones
+      def listing(names = nil, root: ROOT)
+        files(names, root: root).map { |path| "#{Digest::SHA256.file(File.join(root, path)).hexdigest}  #{path}" }
+      end
+
+      # @param names [Array<String>, nil] feature names; nil names every domain
+      # @param root [String] the checkout
+      # @return [Array<String>] the paths the key hashes, relative to the checkout, sorted
+      # @raise [UnknownDomain] when a name is not a domain, listing the valid ones
+      def files(names = nil, root: ROOT)
+        domains = Corpus.rust_domains_named(names, root: root)
+        (generator_files(root) + domains.flat_map { |domain| domain_files(domain, root) }).uniq.sort
+      end
+
+      # @return [Array<String>] the generator's files that exist, and the committed generated output
+      def generator_files(root)
+        globs = GENERATOR_INPUTS + COMMITTED_OUTPUT.map { |feature| "rust/src/generated/#{feature}/**/*" }
+        globs.flat_map { |glob| expand(glob, root) }
+      end
+
+      # One domain's own directory and every bluebook it attaches.
+      #
+      # @param domain [RustDomain] the domain
+      # @param root [String] the checkout
+      # @return [Array<String>] the paths, relative to the checkout
+      def domain_files(domain, root)
+        own = expand("#{domain.dir.delete_prefix("#{root}/")}/**/*", root)
+        own + attached_files(own, root)
+      end
+
+      # The files of every bluebook the domain's own hecksagons attach, followed through the ports
+      # and adapters a bluebook ships. A bluebook this cannot follow exactly widens to all of them.
+      #
+      # @param own [Array<String>] the domain's own files, relative to the checkout
+      # @param root [String] the checkout
+      # @return [Array<String>] the bluebook files, relative to the checkout
+      def attached_files(own, root)
+        follow(names_in(own, root).uniq, root)
+      rescue Unresolved
+        ALL_BLUEBOOK_FILES.flat_map { |glob| expand(glob, root) }
+      end
+
+      # @param path [String] a hecksagon, world or adapter file, relative to the checkout
+      # @param root [String] the checkout
+      # @return [Array<String>] the gem bluebooks it attaches, by name
+      # @raise [Unresolved] when it names an attachment in a way this does not follow
+      def attached_names(path, root)
+        File.readlines(File.join(root, path), chomp: true, encoding: "UTF-8").filter_map do |line|
+          next if line.strip.start_with?("#") || !line.match?(ATTACHMENT_WORD)
+
+          match = ATTACHES_LINE.match(line) or raise Unresolved, "#{path}: #{line.strip}"
+          match[:name] unless match[:vendored]
+        end
+      end
+
+      # Every file of the named bluebooks and of the bluebooks their own hecksagons attach.
+      #
+      # @param pending [Array<String>] bluebook names still to read
+      # @param root [String] the checkout
+      # @return [Array<String>] the files, relative to the checkout
+      # @raise [Unresolved] when a bluebook is not one the gem carries
+      def follow(pending, root)
+        files = []
+        seen = []
+        while (name = pending.shift)
+          next if seen.include?(name)
+
+          seen << name
+          files.concat(bluebook = bluebook_paths(name, root))
+          pending.concat(names_in(bluebook, root))
+        end
+        files
+      end
+
+      # @param paths [Array<String>] files relative to the checkout
+      # @param root [String] the checkout
+      # @return [Array<String>] the bluebooks the hecksagons, worlds and adapters among them attach
+      # @raise [Unresolved] when one names an attachment in a way this does not follow
+      def names_in(paths, root)
+        paths.grep(ATTACHING_FILES).flat_map { |path| attached_names(path, root) }
+      end
+
+      # @param name [String] a bluebook's name
+      # @param root [String] the checkout
+      # @return [Array<String>] the files attaching it reads, relative to the checkout
+      # @raise [Unresolved] when the gem carries no bluebook of that name
+      def bluebook_paths(name, root)
+        require_relative "../framework_bluebooks"
+        FrameworkBluebooks.files_of(name).map do |path|
+          raise Unresolved, "#{name}: #{path} is outside the gem" unless path.start_with?("#{GEM_LIB}/")
+
+          relative = File.join("lib/hecks", path.delete_prefix("#{GEM_LIB}/"))
+          File.file?(File.join(root, relative)) ? relative : nil
+        end.compact
+      rescue Runtime::WiringError => e
+        raise Unresolved, e.message
+      end
+
+      # The files a glob finds, relative to the checkout: no directory, and nothing under a Cargo
+      # `target`, which a build fills and a bare checkout does not have.
+      #
+      # @param glob [String] a glob, relative to the checkout
+      # @param root [String] the checkout
+      # @return [Array<String>] the paths
+      def expand(glob, root)
+        Dir.glob(glob, File::FNM_DOTMATCH, base: root).select do |path|
+          File.file?(File.join(root, path)) && !path.split("/").include?("target") && File.basename(path) != ".DS_Store"
+        end
+      end
+    end
+  end
+end

data/lib/hecks/corpus/listing.rb

@@ -0,0 +1,34 @@
+module Hecks
+  module Corpus
+    # How a kind's glob becomes its members: a directory each, or a file each.
+    # Extended onto `Corpus`.
+    module Listing
+      # @return [Array<Member>] the members of one kind: a directory each, or a file each
+      # @raise [ArgumentError] if `kind` is not in `KINDS`
+      def kind_members(kind, root)
+        if (glob = DIRECTORY_KINDS[kind])
+          directory_members(kind, root, glob)
+        elsif (glob = FILE_KINDS[kind])
+          file_members(kind, root, glob)
+        else
+          raise ArgumentError, "unknown corpus kind #{kind.inspect} — known: #{KINDS.join(", ")}"
+        end
+      end
+
+      def directory_members(kind, root, glob)
+        directories(root, glob).map { |dir| Member.new(File.basename(dir), kind, dir) }
+      end
+
+      def directories(root, glob) = Dir.glob(File.join(root, glob)).select { |path| File.directory?(path) }.sort
+
+      # The part of a glob before its first wildcard.
+      GLOB_FIXED_PREFIX = /\A[^*]*/
+
+      def file_members(kind, root, glob)
+        prefix = File.join(root, glob[GLOB_FIXED_PREFIX].chomp("/"))
+        Dir.glob(File.join(root, glob))
+           .map { |file| Member.new(file.delete_prefix("#{prefix}/").delete_suffix(".bluebook"), kind, file) }
+      end
+    end
+  end
+end

data/lib/hecks/corpus/routes.rb

@@ -15,7 +15,7 @@ module Hecks
       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 " \
+                "translation edges, not bluebooks; 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"),
@@ -24,9 +24,9 @@ module Hecks
                 "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"),
-      Route.new(%r{\Aspec/fixtures/site/editor_chapters/domain/}, :named_in, "spec/site_cms_editor_chapters_spec.rb",
-                "site/editor_chapters",
-                "two chapters that both declare a Category, so the editor must tell them apart; one SQLite " \
+      Route.new(%r{\Aspec/fixtures/site/editor_bluebooks/domain/}, :named_in, "spec/site_cms_editor_bluebooks_spec.rb",
+                "site/editor_bluebooks",
+                "two bluebooks that both declare a Category, so the editor must tell them apart; one SQLite " \
                 "file keeps tables by bare aggregate name, which cannot hold both, so the sweep cannot boot it"),
       # hecks fuzz sweeps it too, once Fuzzing::Replay coerces value-object args
       # before recomputing givens — today it doesn't, so this given reads as
@@ -34,8 +34,28 @@ module Hecks
       Route.new(%r{\Aspec/corpus/asks/}, :named_in, "spec/policy_ask_spec.rb", "spec/corpus/asks",
                 "a corpus-owned domain whose ports have no adapter, so an ask is refused; its frozen " \
                 "targets are held to the Ruby runtime there and to the Rust policy table in rust/codegen"),
+      Route.new(%r{\Aspec/fixtures/sentence/cms_page/sentence_form\.bluebook\z}, :named_in, "spec/sentence_form_spec.rb",
+                :each_file,
+                "a bluebook written as sentences, which only a built hecks-parse can read; the sweep boots its " \
+                "Ruby twin instead, and spec/sentence_form_spec.rb compares the pair byte for byte"),
+      Route.new(%r{\Aspec/fixtures/sentence/pizzas/}, :named_in, "spec/sentence_form_spec.rb", :each_file,
+                "Pizzas written as sentences beside its Ruby twin, whose payment policy reacts to an event " \
+                "the payment webhook emits outside this bluebook, so model_check finds it deaf; " \
+                "spec/sentence_form_spec.rb compares the pair byte for byte"),
+      Route.new(%r{\Aspec/fixtures/sentence_examples/shop/shop\.bluebook\z}, :named_in,
+                "spec/sentence_multi_word_examples_spec.rb", :each_file,
+                "a bluebook written as sentences, which only a built hecks-parse can read; the spec runs its " \
+                "examples against it, so the sweep has nothing to add"),
+      Route.new(%r{\Aspec/fixtures/sentence/orders/}, :named_in, "spec/sentence_form_spec.rb", :each_file,
+                "a bluebook written as sentences beside its Ruby twin, whose policies ask the outside and " \
+                "wait for its answers; model_check wants the hecksagon that declares that port, which the " \
+                "sweep does not load. The spec compares each pair and spec/sentence_examples_spec.rb runs " \
+                "its examples against the hecksagon"),
       Route.new(%r{\Aspec/fixtures/rust_host/}, :named_in, "rust/host/src/web/commerce.rs", "checkout_fixture",
-                "the Rust host's checkout fixture, pinned by its web and /api tests")
+                "the Rust host's checkout fixture, pinned by its web and /api tests"),
+      Route.new(%r{\Apackages/hecks-rails/spec/fixtures/}, :named_in, "packages/hecks-rails/spec/support/ledger_app.rb",
+                :each_file,
+                "the hecks-rails gem's fixture app; its own specs boot it under Rails, which this sweep cannot")
     ].freeze
   end
 end

data/lib/hecks/corpus/rust.rb

@@ -23,18 +23,31 @@ module Hecks
     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
+    # `examples/pizzas` or `the self-hosted language (...)`; a bluebook's is its own name.
+    SOURCE_STAMP = /GENERATED\ by\ hecks\ project_rust\ —\ (.+?)'s\ own\ canonical\ IR,/
+
+    # Raised when a name is not a domain the corpus regenerates; the message lists the valid ones.
+    class UnknownDomain < ArgumentError; end
+
+    # The Rust-facing lists: which domains and bluebooks `rust/` carries, read off Cargo's
     # `[features]` and the generated modules rather than typed out by hand. Extended onto
     # `Corpus`.
     module Rust
+      # A Cargo feature line with an empty dependency array, capturing the feature's name.
+      EMPTY_FEATURE = /^(\w+)\s*=\s*\[\]/
+
+      # Cargo's `default = ["name"]` line, capturing the default feature's name.
+      DEFAULT_FEATURE = /^default\s*=\s*\["(\w+)"\]/
+
+      # A hecksagon's `attaches "Name"` line for a gem bluebook (no `from:`), capturing the name.
+      ATTACHED_BY_NAME = /^\s*attaches\s+"(\w+)"\s*$/
+
+      # A bluebook file's `Hecks.bluebook "Name"` header, capturing the bluebook's name.
+      BLUEBOOK_NAME = /^\s*Hecks\.bluebook\s+"([^"]+)"/
+
+      # The corpus kinds holding bluebooks the gem carries and a hecksagon attaches by name.
+      GEM_BLUEBOOK_KINDS = %i[qa deploy site tickets composer tenancy sme bulk ci_pipeline].freeze
+
       # Every place a Rust-facing domain's own `attaches` attachment could be declared.
       #
       # @param root [String] repository root to search under
@@ -57,16 +70,16 @@ module Hecks
       # @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
+        cargo_features_table(root: root).scan(EMPTY_FEATURE).flatten
       end
 
-      # The feature `hecks project_rust` last wrote as Cargo's `default`.
+      # The feature Cargo's `default` names: the one a corpus run keeps it on.
       #
       # @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]
+        cargo_features_table(root: root)[DEFAULT_FEATURE, 1]
       end
 
       # Every in-repo domain directory whose name is a Cargo feature, sorted
@@ -76,12 +89,11 @@ module Hecks
       # @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) }
+        candidates = members(*RUST_DOMAIN_KINDS, root: root).map { |member| [domain_dir_of(member), member.kind] }
+                                                            .uniq(&:first)
+        candidates.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.
@@ -125,14 +137,14 @@ module Hecks
         File.file?(File.join(root, GENERATED_DIR, feature, "merged.rs"))
       end
 
-      # Chapters attached via `kind` that get a generated module as a side
+      # Bluebooks 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)
+      def rust_side_bluebooks(kind, root: ROOT)
         modules = generated_modules(root: root)
         members(kind, root: root).map(&:stem)
                                  .select do |stem|
@@ -150,38 +162,59 @@ module Hecks
         Naming.pascal(stem).downcase
       end
 
-      # Names the framework chapters Rust carries as modules, beside its domains' own bluebooks.
+      # Names the framework bluebooks 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)
+      def rust_framework_bluebooks(root: ROOT)
+        rust_side_bluebooks(:framework, root: root)
       end
 
-      # Names the vendored chapters Rust carries as modules, beside its domains' own bluebooks.
+      # Names the vendored bluebooks 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)
+      def rust_vendored_bluebooks(root: ROOT)
+        rust_side_bluebooks(:vendored, root: root)
       end
 
-      # Chapters an in-repo Rust domain carries beside its own bluebook,
+      # Bluebooks 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)
+      def rust_sibling_bluebooks(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) }
+        names = rust_domains(root: root)
+                .flat_map { |domain| Dir.glob(File.join(domain.dir, "bluebook", "*.bluebook")) }
+                .map { |path| Naming.pascal(File.basename(path, ".bluebook")).downcase }
+        names.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.
+      # Gem bluebooks outside the framework (`FrameworkBluebooks.index`, such as Bulk) that an
+      # in-repo Rust
+      # domain's hecksagon attaches by name, written as a module by `hecks project_rust` with no
+      # merged.rs of their own.
+      #
+      # @param root [String] repository root to search under
+      # @return [Array<String>] generated module names for the attached gem bluebooks
+      def rust_attached_bluebooks(root: ROOT)
+        modules = generated_modules(root: root)
+        names = rust_attachment_hecksagon_text(root: root).scan(ATTACHED_BY_NAME).flatten & gem_bluebook_names(root: root)
+        names.map { |name| Naming.pascal(name).downcase }.uniq
+             .select { |name| modules.include?(name) && !generated?(name, root: root) }
+      end
+
+      # The names the gem's own attachable bluebooks declare in their `Hecks.bluebook` headers.
+      #
+      # @param root [String] repository root to search under
+      # @return [Array<String>] bluebook names, from the files `GEM_BLUEBOOK_KINDS` hold
+      def gem_bluebook_names(root: ROOT)
+        members(*GEM_BLUEBOOK_KINDS, root: root).filter_map { |member| File.read(member.path)[BLUEBOOK_NAME, 1] }.uniq
+      end
+
+      # The regeneration order the drift check runs, sorted by path, and the domains a corpus
+      # run declares to `hecks project_rust`.
       #
       # @param root [String] repository root to search under
       # @return [Array<RustDomain>] every Rust domain with a Cargo feature, in regeneration order:
@@ -189,6 +222,24 @@ module Hecks
       def rust_regen_order(root: ROOT)
         rust_domains(root: root)
       end
+
+      # The named domains of the regeneration order, in that order whatever order they are named in.
+      #
+      # @param names [Array<String>, nil] feature names; nil names every domain
+      # @param root [String] repository root to search under
+      # @return [Array<RustDomain>] the named domains, in regeneration order
+      # @raise [UnknownDomain] when a name is not a domain's feature, listing the valid ones
+      def rust_domains_named(names, root: ROOT)
+        order = rust_regen_order(root: root)
+        return order if names.nil?
+
+        unknown = names - order.map(&:feature)
+        unless unknown.empty?
+          raise UnknownDomain, "unknown domain(s) #{unknown.join(", ")}; valid: #{order.map(&:feature).sort.join(", ")}"
+        end
+
+        order.select { |domain| names.include?(domain.feature) }
+      end
     end
   end
 end