hecks 6.0.0 → 7.0.0

data/lib/hecks/command_names/check.rb

@@ -0,0 +1,39 @@
+require "hecks/adapters/driving/cli_runner"
+require_relative "index"
+require_relative "scan"
+require_relative "sources"
+
+module Hecks
+  module CommandNames
+    # The check that every launcher name a file invokes is one the launcher accepts.
+    #
+    # A renamed command leaves its old name in gate rows, workflows, specs and docs, and a gate that
+    # runs a name the launcher refuses runs nothing. This reads those places for `exe/hecks <name>`
+    # and `hecks <name>` and looks each up in the launcher's own name table, once.
+    module Check
+      # One invocation the launcher would refuse.
+      Finding = Struct.new(:path, :line, :text, :problem) do
+        # @return [String] `file:line`, the string, the fault and the nearest valid name
+        def to_s
+          near = problem.nearest ? "; nearest valid name: #{problem.nearest}" : ""
+          "#{path}:#{line}: #{text[0, 120]} -- #{problem.text}#{near}"
+        end
+      end
+
+      module_function
+
+      # @param root [String] the checkout
+      # @param scopes [Hash] `CliRunner.name_index`
+      # @return [Array<Finding>] every invocation the launcher would refuse, by file then line
+      def findings(root:, scopes:)
+        index = Index.new(scopes)
+        Sources.files(root).flat_map do |path|
+          Scan.new(path, File.read(File.join(root, path), encoding: "UTF-8")).calls.filter_map do |call|
+            problem = index.problem(call.words)
+            Finding.new(path, call.line, call.text, problem) if problem && !Sources.allowed?(call.text)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/command_names/extractor.rb

@@ -0,0 +1,67 @@
+module Hecks
+  module CommandNames
+    # The launcher invocations in a file's text: where each is, and the words typed after it.
+    class Extractor
+      # One invocation found.
+      Call = Struct.new(:line, :text, :words)
+
+      # `exe/hecks` names the launcher wherever it appears.
+      STRONG = %r{exe/hecks(?=\s)\s+(?<rest>[^`"'|;&)>\\]*)}
+      # `exe/hecks` as the head of an argument list.
+      LISTED = %r{exe/hecks["']\s*,\s*["'](?<rest>[^"']*)}
+      # A bare `hecks` counts when a backtick opens it, or a prompt precedes it.
+      QUOTED = /(?<=`)hecks\s+(?<rest>[^`"'|;&)>\\]*)/
+      PROMPT = /(?:\A|\s)\$\s+hecks\s+(?<rest>[^`"'|;&)>\\]*)/
+      # A bare `hecks` that opens a line of shell, in a fence or a shell file.
+      SHELL = /\A\s*(?:bundle exec\s+)?hecks\s+(?<rest>[^`"'|;&)>\\]*)/
+
+      # A word that can be a launcher name, with the punctuation prose puts after it cut off.
+      NAME = /\A[A-Za-z_][\w:]*(?:\.\w+)*!?\z/
+
+      # The punctuation prose puts after a name.
+      TRAILING = /[,.;:)\]]+\z/
+
+      # A name with a regex-escaped dot (`gate_run\.gate!`): a pattern, not a launcher call.
+      ESCAPED = /[\w:!]+(?:\\\.[\w!]*)+/
+
+      # The line marker that excuses an illustrative invocation, on its own line or the one before.
+      MARKER = "dead-name-check: skip".freeze
+
+      # @param shell [Boolean] whether a line may open with a bare `hecks` (a fence, a shell file)
+      # @param strong_only [Boolean] whether only `exe/hecks` counts, as in a code comment's prose
+      def initialize(shell: false, strong_only: false)
+        @shell = shell
+        @strong_only = strong_only
+      end
+
+      # @param line [String] one line of text
+      # @param number [Integer] its line number
+      # @return [Array<Call>] the invocations on it
+      def calls(line, number)
+        return [] unless line.include?("hecks")
+
+        text = line.gsub(ESCAPED, "")
+        patterns.flat_map { |pattern| text.scan(pattern).flatten }.filter_map { |rest| call(rest, number, line) }
+      end
+
+      private
+
+      def patterns
+        return [STRONG, LISTED] if @strong_only
+
+        [STRONG, LISTED, QUOTED, PROMPT, (SHELL if @shell)].compact
+      end
+
+      def call(rest, number, line)
+        words = words(rest)
+        Call.new(number, line.strip, words) unless words.empty?
+      end
+
+      # The leading words of a line that spell a launcher name, after the flags before it.
+      def words(rest)
+        tokens = rest.split.drop_while { |token| token.start_with?("-") }
+        tokens.map { |token| token.sub(TRAILING, "") }.take_while { |token| token.match?(NAME) }.first(3)
+      end
+    end
+  end
+end

data/lib/hecks/command_names/index.rb

@@ -0,0 +1,40 @@
+require "hecks/adapters/driving/cli_runner"
+require_relative "resolution"
+
+module Hecks
+  module CommandNames
+    # The launcher's accepted names, by scope, and what becomes of a typed line.
+    class Index
+      # Words the launcher answers before it looks a name up.
+      PROGRAM_WORDS = %w[help usage search tour completion resume].freeze
+
+      # @param scopes [Hash{String => Hash}] `CliRunner.name_index`
+      def initialize(scopes)
+        @scopes = scopes
+      end
+
+      # @param words [Array<String>] the words after the launcher's name
+      # @return [Problem, nil] what is wrong with the line, or nil when the launcher accepts it
+      def problem(words)
+        scope, rest = scope_of(words)
+        asking = Adapters::Driving::CliRunner::QUERY_WORDS.include?(rest.first)
+        typed = rest.drop(asking ? 1 : 0).first
+        return if typed.nil? || free?(scope, typed)
+
+        Resolution.new(scope, typed, asking).problem
+      end
+
+      private
+
+      # An attached bluebook's word hands the rest of the line to that bluebook.
+      def scope_of(words)
+        scope = words.first && !words.first.empty? && @scopes[words.first]
+        scope ? [scope, words.drop(1)] : [@scopes.fetch(""), words]
+      end
+
+      def free?(scope, typed)
+        PROGRAM_WORDS.include?(typed) || scope["modules"].include?(typed)
+      end
+    end
+  end
+end

data/lib/hecks/command_names/resolution.rb

@@ -0,0 +1,81 @@
+require "hecks/adapters/driving/cli_runner"
+
+module Hecks
+  module CommandNames
+    # What is wrong with a typed line.
+    Problem = Struct.new(:text, :nearest)
+
+    # One typed word looked up the way the launcher looks it up: every spelling through
+    # `canonical_name`, the bang rule of `BangRule`, the neighbours of `Suggestions`.
+    class Resolution
+      RUNNER = Adapters::Driving::CliRunner
+
+      # The marks a name carries that a plain English word does not.
+      NAME_MARKS = /[_.]/
+
+      # @param scope [Hash] one scope of `CliRunner.name_index`
+      # @param typed [String] the word, with its `!` if it has one
+      # @param asking [Boolean] whether `query` came before it
+      def initialize(scope, typed, asking)
+        @scope = scope
+        @cli = { names: { command: scope["command"], question: scope["question"] } }
+        @typed = typed.chomp("!")
+        @bang = typed.end_with?("!")
+        @asking = asking
+        @name = RUNNER.canonical_name(@cli, @typed)
+      end
+
+      # @return [Problem, nil] nil when the launcher would run the line
+      def problem
+        return unknown unless command || question
+
+        bare_command || banged_query || query_of_command
+      end
+
+      private
+
+      def command = @scope["command"][@name]
+
+      def question = @scope["question"][@name]
+
+      def bare_command
+        return unless command && !@asking && !@bang
+
+        Problem.new("#{@typed} is a command and writes; write it as #{@typed}!", "#{command}!")
+      end
+
+      def banged_query
+        return unless @bang && !@asking && !command && question
+
+        Problem.new("#{@typed}! is a query and reads; write it without the !", "query #{question}")
+      end
+
+      def query_of_command
+        return unless @asking && !question
+
+        Problem.new("#{@typed} is a command, not a query", "#{command}!")
+      end
+
+      def unknown
+        return if plain? && !homed?
+
+        near = RUNNER.near_names(@cli, RUNNER.snake_form(@name), @asking).first
+        Problem.new("#{@typed} is not a command or query", near && listed(near))
+      end
+
+      # A lone word with no underscore, dot or bang is as likely English as a name.
+      def plain? = !@bang && !@typed.match?(NAME_MARKS)
+
+      # Whether the word is the last part of some name, so a launcher once accepted it bare.
+      def homed?
+        (@cli[:names][:command].keys + @cli[:names][:question].keys).any? { |key| key.split(".").last == @name }
+      end
+
+      def listed(near)
+        return "#{@scope["command"][near]}!" if @scope["command"][near]
+
+        "query #{@scope["question"][near]}"
+      end
+    end
+  end
+end

data/lib/hecks/command_names/scan.rb

@@ -0,0 +1,54 @@
+require_relative "extractor"
+
+module Hecks
+  module CommandNames
+    # One file read for launcher invocations, leaving out the ones marked as illustrative.
+    class Scan
+      # A fence whose opening line says its content is shown and not meant to run.
+      EXCUSED_FENCE = /\b(?:skip|historical|illustrative)\b/
+
+      # @param path [String] the file's path, relative to the checkout
+      # @param text [String] its text
+      def initialize(path, text)
+        @path = path
+        @lines = text.scrub.lines
+        @markdown = path.end_with?(".md")
+        @ruby = path.end_with?(".rb")
+        @shell = !path.end_with?(".rb", ".md", ".bluebook")
+      end
+
+      # @return [Array<Extractor::Call>] the invocations, each as `calls` of the extractor
+      def calls
+        fence = nil
+        @lines.each_with_index.flat_map do |line, index|
+          fence = fence_after(fence, line)
+          next [] if skipped?(line, index, fence)
+
+          extractor(fence, line).calls(line, index + 1)
+        end
+      end
+
+      private
+
+      # The open fence after a line: nil outside one, else its opening line.
+      def fence_after(fence, line)
+        return fence unless @markdown && line.lstrip.start_with?("```")
+
+        fence ? nil : line
+      end
+
+      def skipped?(line, index, fence)
+        return true if line.lstrip.start_with?("```") || excused?(fence)
+
+        [line, (@lines[index - 1] if index.positive?)].compact.any? { |text| text.include?(Extractor::MARKER) }
+      end
+
+      def excused?(fence) = fence&.match?(EXCUSED_FENCE)
+
+      # A Ruby comment is prose, so only the launcher's path names a call in it.
+      def extractor(fence, line)
+        Extractor.new(shell: @shell || !fence.nil?, strong_only: @ruby && line.lstrip.start_with?("#"))
+      end
+    end
+  end
+end

data/lib/hecks/command_names/sources.rb

@@ -0,0 +1,73 @@
+module Hecks
+  module CommandNames
+    # The files whose text shells out to the launcher, and the ones left out.
+    module Sources
+      # Globs, relative to the checkout, of the files a line may invoke the launcher in.
+      INCLUDED = %w[
+        .github/workflows/*.yml .github/workflows/*.yaml .github/actions/**/* .githooks/*
+        lib/hecks/language/bluebook/vocabulary.bluebook Makefile scripts/**/* spec/**/*.rb
+        docs/implemented/**/*.md CLAUDE.md
+        lib/**/*.rb qa/**/*.rb qa/**/*.md qa/**/*.sh qa/**/*.yml
+        .claude/hooks/* .claude/settings.json .claude/skills/**/*.md .claude/agents/**/*.md
+      ].freeze
+
+      # Exact lines left unflagged. Each is a dead name kept on purpose until a person picks the
+      # command that replaces it; remove the entry when that command exists.
+      #
+      # The headers below are written into committed generated files (diagrams, the Rust syntax and
+      # phrase tables, the site routes, the kernel templates) and specs assert them, so renaming
+      # one is a regeneration of those files and its own change.
+      ALLOWED_LINES = [
+        # The mint plan's ledger line has no successor command yet.
+        "exe/hecks Maintenance.mint_era! run.value=<run-id>",
+        "hecks project_diagrams", "hecks project_parser_table", "hecks project_phrase_table",
+        "hecks measure_kernel_coverage",
+        # The installed gem's own `hecks vendor`, which a client runs outside this launcher.
+        "(the name `hecks vendor` accepts)", "`hecks site site_projection.project_site"
+      ].freeze
+
+      # Paths that record what was once true, so a retired name in them is history, not a fault.
+      HISTORICAL = %r{\A(?:docs/decisions/|docs/implemented/decisions/|docs/archive/|CHANGELOG\.md\z)}
+
+      # A banner in a document's first lines that says it records a moment.
+      SNAPSHOT = /\A(?:>\s*)?\*\*Historical snapshot\b/
+
+      # A line in a document's first lines that excuses the whole file, such as a page that lists
+      # the names a rename leaves behind.
+      SKIP_FILE = "dead-name-check: skip-file".freeze
+
+      # How many lines from the top count as "the first lines".
+      BANNER_WINDOW = 12
+
+      module_function
+
+      # @param root [String] the checkout
+      # @return [Array<String>] the paths to scan, relative to `root`, sorted
+      def files(root)
+        scanned(root).reject { |path| historical?(root, path) }
+      end
+
+      # @return [Array<String>] every file the globs reach, relative to `root`, sorted
+      def scanned(root)
+        paths = INCLUDED.flat_map { |glob| Dir.glob(File.join(root, glob), File::FNM_DOTMATCH) }
+        relative(root, paths.select { |path| File.file?(path) })
+      end
+
+      # @return [Array<String>] the paths below `root`, once each, sorted
+      def relative(root, paths) = paths.map { |path| path.delete_prefix("#{root}/") }.uniq.sort
+
+      # @return [Boolean] whether a path is history: a decision record, the changelog, an archive, a
+      #   document whose first lines call it a historical snapshot, or one that excuses itself
+      def historical?(root, path)
+        return true if path.match?(HISTORICAL)
+
+        File.foreach(File.join(root, path), encoding: "UTF-8").first(BANNER_WINDOW).any? { |line| excused?(line) }
+      end
+
+      # @return [Boolean] whether a line carries one of the allowed strings
+      def allowed?(text) = ALLOWED_LINES.any? { |allowed| text.include?(allowed) }
+
+      def excused?(line) = line.match?(SNAPSHOT) || line.include?(SKIP_FILE)
+    end
+  end
+end

data/lib/hecks/command_names.rb

@@ -0,0 +1,26 @@
+require_relative "command_names/check"
+
+module Hecks
+  # Reads the places that shell out to the launcher for names the launcher does not accept.
+  module CommandNames
+    # The clean verdict.
+    CLEAN = "every launcher name invoked in workflows, hooks, gate rows, specs and docs is one the launcher accepts".freeze
+
+    module_function
+
+    # @param root [String] the checkout
+    # @param runtime [#registry] what `Hecks.describe` answers
+    # @return [String] the clean verdict
+    # @raise [Failure] with a line for each name the launcher would refuse
+    def check(root:, runtime:)
+      scopes = Adapters::Driving::CliRunner.name_index(runtime: runtime)
+      found = Check.findings(root: root, scopes: scopes)
+      raise Failure, found.join("\n") unless found.empty?
+
+      CLEAN
+    end
+
+    # Raised with every finding.
+    class Failure < StandardError; end
+  end
+end

data/lib/hecks/composer/jobs.rb

@@ -35,7 +35,7 @@ module Hecks
       # @param confirm [String, nil] the confirmation the runner requires, if any
       # @return [true]
       # @raise [Busy] when a job is running
-      def start(kind:, verb:, args: {}, confirm: nil) # rubocop:disable Naming/PredicateMethod
+      def start(kind:, verb:, args: {}, confirm: nil)
         @mutex.synchronize do
           raise Busy, "a job is already running" if running?
 

data/lib/hecks/composer/toolbox.rb

@@ -157,11 +157,18 @@ module Hecks
         Hecks.boot(File.join(Parse::ROOT, "lib/hecks/hecks"), install_driving: false, environment: "memory")
       end
 
+      # A safe-listed command writes through the runner only with its bang; the list names bare commands.
+      def writing(argv)
+        return argv unless argv.first && SAFE_COMMANDS.include?(argv.first)
+
+        ["#{argv.first}!", *argv.drop(1)]
+      end
+
       # @api private
       def invoke(argv)
         rt = runtime
         @lock.synchronize do
-          Hecks::Adapters::Driving::CliRunner.call(runtime: rt, program: "hecks", argv: argv)
+          Hecks::Adapters::Driving::CliRunner.call(runtime: rt, program: "hecks", argv: writing(argv))
         end
       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