hecks 4.0.0 → 6.0.0

data/lib/hecks/tools/regeneration_run.rb

@@ -32,6 +32,9 @@ module Hecks
                          "Only pizzas, mod.rs and Cargo.toml are committed; run " \
                          "`hecks regenerate_corpus --confirm` first, then the check."
 
+      # The `hecks project_rust` flag that leaves the `meta/` module as an earlier domain wrote it.
+      SKIP_META = "--skip-meta"
+
       module_function
 
       # Regenerates the corpus, or checks it.
@@ -43,8 +46,8 @@ module Hecks
       def main(argv, root: Tools::ROOT)
         Dir.chdir(root) do
           domains = plan(root)
-          # A check projects into a scratch copy of the crate; the forked children inherit
-          # HECKS_RUST_DIR.
+          # A check projects into a scratch copy of the crate; the forked children inherit the
+          # workspace with the process.
           scratch = argv.include?("--check") && scratch_crate(root)
           run_plan(domains, scratch)
         end
@@ -62,13 +65,12 @@ module Hecks
         FileUtils.rm_rf(scratch) if scratch
       end
 
-      # Points `HECKS_RUST_DIR` at `scratch` while the block runs, then puts it back.
-      def with_rust_dir(scratch)
-        saved = ENV.fetch("HECKS_RUST_DIR", nil)
-        ENV["HECKS_RUST_DIR"] = scratch if scratch
-        yield
-      ensure
-        saved ? ENV["HECKS_RUST_DIR"] = saved : ENV.delete("HECKS_RUST_DIR")
+      # Builds in `scratch` while the block runs; with none, in the workspace already chosen.
+      def with_rust_dir(scratch, &)
+        require "hecks/rust_build"
+        return yield unless scratch
+
+        Hecks::RustBuild.in_workspace(scratch, &)
       end
 
       # `meta` is never in the list: `Hecks::Corpus::RUST_ELSEWHERE` routes it to the check that
@@ -98,7 +100,8 @@ module Hecks
         require "hecks/bluebook/meta_validator"
         require "hecks/rust_build"
         Hecks::Bluebook::MetaValidator.grammar_registry
-        domains.each { |domain| project_rust_in_fork(domain) }
+        # Every domain writes the same `meta/` module, so the first one does and the rest skip it.
+        domains.each_with_index { |domain, index| project_rust_in_fork(domain, skip_meta: index.positive?) }
       end
 
       # Forks so the child inherits the memoized grammar registry instead of rebuilding it. The
@@ -106,12 +109,14 @@ module Hecks
       # process's stdout.
       #
       # @param domain [String] the domain, relative to the checkout
+      # @param skip_meta [Boolean] leave the `meta/` module as an earlier domain wrote it
       # @return [void]
       # @raise [SystemExit] when the child fails
-      def project_rust_in_fork(domain)
+      def project_rust_in_fork(domain, skip_meta: false)
         puts "== hecks project_rust #{domain} =="
         reader, writer = IO.pipe
-        pid = fork { run_child(reader, writer, domain) }
+        argv = skip_meta ? [domain, SKIP_META] : [domain]
+        pid = fork { run_child(reader, writer, argv) }
         writer.close
         $stdout.write(reader.read)
         reader.close
@@ -122,23 +127,23 @@ module Hecks
 
       # @param reader [IO] the parent's end of the pipe, closed here
       # @param writer [IO] the child's end, which becomes its stdout and stderr
-      # @param domain [String] the domain
+      # @param argv [Array<String>] the domain, and any flag for `hecks project_rust`
       # @return [void] never returns: the child leaves without the parent's exit handlers
-      def run_child(reader, writer, domain)
+      def run_child(reader, writer, argv)
         reader.close
         # The real descriptors, not the globals: a caller may have swapped those for a buffer.
         STDOUT.reopen(writer) # rubocop:disable Style/GlobalStdStream
         STDERR.reopen(writer) # rubocop:disable Style/GlobalStdStream
         $stdout = STDOUT
         $stderr = STDERR
-        status = child_status(domain)
+        status = child_status(argv)
         $stdout.flush
         exit!(status)
       end
 
       # @return [Integer] the exit status of `hecks project_rust` for the domain
-      def child_status(domain)
-        Hecks::RustBuild.run("project_rust", [domain], out: STDOUT, err: STDERR) # rubocop:disable Style/GlobalStdStream
+      def child_status(argv)
+        Hecks::RustBuild.run("project_rust", argv, out: STDOUT, err: STDERR) # rubocop:disable Style/GlobalStdStream
       rescue SystemExit => e
         e.status
       rescue StandardError => e

data/lib/hecks/tools/release_only.rb

@@ -11,7 +11,7 @@ module Hecks
     # inherit the base's certification instead of running the suite again.
     #
     # The files a bump edits, and which of their lines it may change, are the `ReleaseFile` rows of
-    # the Vocabulary chapter. A change is a release bump when it touches at least one file, every
+    # the Vocabulary bluebook. A change is a release bump when it touches at least one file, every
     # file it touches is a row, and every line it adds or removes in a file matches that row's
     # `lines` pattern (an empty pattern admits any line). Whether the base is certified is read
     # from the base commit's own check runs: every `RequiredCheck` row that is not marked
@@ -21,6 +21,9 @@ module Hecks
     module ReleaseOnly
       GREEN = %w[success skipped].freeze
 
+      # The `+` or `-` that opens an added or removed line of a diff.
+      CHANGE_MARK = /\A[+-]/
+
       module_function
 
       # @param changes [Hash{String => Array<String>}] each changed path to the lines it adds or
@@ -91,7 +94,7 @@ module Hecks
 
       # @return [Boolean] whether the line is an added or removed line, not a header
       def content_line?(line)
-        line.match?(/\A[+-]/) && !line.start_with?("+++ ", "--- ")
+        line.match?(CHANGE_MARK) && !line.start_with?("+++ ", "--- ")
       end
 
       # @param repository [String] `owner/name`

data/lib/hecks/tools/rust_comment_style/caps_words.rb

@@ -69,17 +69,17 @@ module Hecks
         end
 
         def keep_capitals?(word)
-          bare = word.sub(/'[A-Z]{1,2}\z/, "")
+          bare = word.sub(CommentStyle::SHOUTED_SUFFIX, "")
           return false if CommentStyle::PROPER_NOUNS.key?(bare) || RUST_PROPER_NOUNS.key?(bare)
 
           CommentStyle::ACRONYMS.include?(bare) || RUST_ACRONYMS.include?(bare) ||
-            @constants.include?(bare) || bare.match?(/\A[IVX]+\z/)
+            @constants.include?(bare) || bare.match?(CommentStyle::ROMAN_NUMERAL)
         end
 
         def sentence_start?(comment, masked, offset)
           before = masked[0, offset].sub(MARKER, "")
-          return before.match?(/[.!?]["')\]]*\s+\z/) if before.match?(/[[:alnum:]#{FILLER}]/o)
-          return true if before.match?(/\A\s*(?:[-*•]|─+|\d+[.)])\s+\z/)
+          return before.match?(CommentStyle::SENTENCE_BREAK) if before.match?(/[[:alnum:]#{FILLER}]/o)
+          return true if before.match?(CommentStyle::LIST_MARKER)
 
           after_sentence_end?(comment)
         end
@@ -90,7 +90,7 @@ module Hecks
           return true unless previous&.full_line
 
           body = previous.text.sub(MARKER, "").strip
-          body.empty? || body.match?(/[.!?]["')\]]*\z/)
+          body.empty? || body.match?(CommentStyle::SENTENCE_END)
         end
       end
     end

data/lib/hecks/tools/rust_comment_style/fixing.rb

@@ -75,7 +75,7 @@ module Hecks
           return false if masked[0, offset].sub(MARKER, "").match?(/[[:alnum:]#{FILLER}]/o)
 
           above = comment.full_line ? @by_line[comment.line - 1] : nil
-          !above&.full_line || above.text.match?(%r{\A/{2,3}!?\s*\z})
+          !above&.full_line || above.text.match?(EMPTY_COMMENT)
         end
 
         # Splits one over-long prose comment line in two. Lines with no safe

data/lib/hecks/tools/rust_comment_style/masking.rb

@@ -5,6 +5,9 @@ require_relative "../../tools"
 module Hecks
   module Tools
     module RustCommentStyle
+      # A comment line with nothing after its slashes: a paragraph break.
+      EMPTY_COMMENT = %r{\A/{2,3}!?\s*\z}
+
       # Blanks the spans of a Rust comment that must keep their capitals (code spans, quotes, SQL),
       # and decides which capitalised SQL keywords on a line to leave alone.
       module Masking
@@ -21,7 +24,7 @@ module Hecks
 
         def continues_paragraph?(comment)
           above = @by_line[comment.line - 1]
-          comment.full_line && above&.full_line && !above.text.match?(%r{\A/{2,3}!?\s*\z})
+          comment.full_line && above&.full_line && !above.text.match?(EMPTY_COMMENT)
         end
 
         def mask(comment)
@@ -52,8 +55,8 @@ module Hecks
         def quoted_heading?(span)
           return false unless span.start_with?('"') && !span.match?(CommentStyle::SQL_PHRASES)
 
-          capitals = span.scan(/\b[A-Z]{2,}\b/).size
-          capitals >= 3 || (capitals == 2 && !span.match?(/[a-z]/))
+          capitals = span.scan(CommentStyle::SHOUTED_WORD).size
+          capitals >= 3 || (capitals == 2 && !span.match?(CommentStyle::LOWERCASE))
         end
 
         def sql_keywords(comment, words)
@@ -65,7 +68,7 @@ module Hecks
         end
 
         def sql_classes(words)
-          bare = words.map { |w| w.sub(/'[A-Z]{1,2}\z/, "") } - ["A"]
+          bare = words.map { |w| w.sub(CommentStyle::SHOUTED_SUFFIX, "") } - ["A"]
           [bare, bare.select { |w| CommentStyle::SQL_STRONG.include?(w) }, bare.select { |w| CommentStyle::SQL_WEAK.include?(w) }]
         end
 

data/lib/hecks/tools/rust_comment_style/source_file.rb

@@ -12,6 +12,11 @@ module Hecks
     module RustCommentStyle
       # One parsed `.rs` file and the violations found in it.
       class SourceFile
+        # A `const` or `static` item, capturing its all-caps name.
+        CONSTANT_ITEM = /\b(?:const|static)\s+(?:mut\s+)?([A-Z][A-Z0-9_]*)\b/
+        # A string holding nothing but an all-caps name of three or more characters.
+        QUOTED_CONSTANT = /"([A-Z][A-Z0-9_]{2,})"/
+
         include Masking
         include CapsWords
         include TextChecks
@@ -61,8 +66,8 @@ module Hecks
           code_only = @source.dup
           Tokenizer.comments(@source).each { |c| code_only[c.line - 1] ||= "" }
           names = Set.new
-          code_only.scan(/\b(?:const|static)\s+(?:mut\s+)?([A-Z][A-Z0-9_]*)\b/) { |(n)| names << n }
-          code_only.scan(/"([A-Z][A-Z0-9_]{2,})"/) { |(n)| names << n }
+          code_only.scan(CONSTANT_ITEM) { |(n)| names << n }
+          code_only.scan(QUOTED_CONSTANT) { |(n)| names << n }
           names
         end
       end

data/lib/hecks/tools/rust_comment_style/text_checks.rb

@@ -44,7 +44,7 @@ module Hecks
         end
 
         def history_violations(comment)
-          masked = comment.text.gsub(/`[^`]*`/) { |span| " " * span.length }
+          masked = comment.text.gsub(CommentStyle::CODE_SPAN) { |span| " " * span.length }
           pattern = CommentStyle::HISTORY.find { |candidate| masked.match?(candidate) }
           return [] unless pattern
 

data/lib/hecks/tools/rust_comment_style/tokenizer.rb

@@ -8,6 +8,9 @@ module Hecks
       # Finds Rust source's line comments, distinguishing them from `//` inside
       # code, strings, raw strings, and char literals. Block comments are not recognised.
       class Tokenizer
+        # A Rust char literal: one character or one escape between single quotes.
+        CHAR_LITERAL = /\A'(?:\\.|[^'\\\n]){1}'/
+
         # Lexes `source` for its line comments in one pass.
         def self.comments(source)
           new(source).run
@@ -67,7 +70,7 @@ module Hecks
         end
 
         def consume_quote(pos, col)
-          match = @src[pos..].match(/\A'(?:\\.|[^'\\\n]){1}'/)
+          match = @src[pos..].match(CHAR_LITERAL)
           match ? [pos + match[0].length, col + match[0].length] : [pos + 1, col + 1]
         end
 

data/lib/hecks/tools/site_routes/editor_files.rb

@@ -10,34 +10,37 @@ module Hecks
       module EditorFiles
         # @param editor [String] the directory the files are written under
         # @param project [String] the project directory; the row's `domain` is relative to it
-        # @param site [Site] the project's route-table chapter, checked table and registry
+        # @param site [Site] the project's route-table bluebook, checked table and registry
         # @return [Hash{String => String}] each file's absolute path to its text
         # @raise [SystemExit] when `--editor` is named and the project declares no `Editor` row, or
-        #   the row names a domain or chapter that is not there
+        #   the row names a domain or bluebook that is not there
         def editor_files(editor, project, site)
-          setting = Projections::Site::CmsEditor::Setting.read(site.chapter, table: site.table)
+          setting = Projections::Site::CmsEditor::Setting.read(site.declaration, table: site.table)
           abort "project_site: --editor names #{editor}, but the project declares no Editor row" if setting.nil?
 
-          files = Projector.call(:site_cms_editor, bluebook: site.chapter, options: options(project, setting, site))
+          files = Projector.call(:site_cms_editor, bluebook: site.declaration, options: options(project, setting, site))
           files.to_h { |name, text| [File.join(File.expand_path(editor), name), text] }
         rescue ArgumentError, Projections::Site::Table::Invalid => e
           abort "project_site: #{e.message}"
         end
 
-        # @return [Hash{Symbol => Object}] the chapters the editor reads, and the route table
+        # @return [Hash{Symbol => Object}] the bluebooks the editor reads, and the route table
         def options(project, setting, site)
-          chosen = { domain_chapters: setting.chapters.map { |name| domain_chapter(project, setting, name) }, table: site.table }
-          chosen[:media_chapter] = domain_chapter(project, setting, setting.media_chapter) if setting.media_chapter
+          chosen = { domain_bluebooks: setting.bluebooks.map do |name|
+            domain_bluebook(project, setting, name)
+          end, table: site.table }
+          chosen[:media_bluebook] = domain_bluebook(project, setting, setting.media_bluebook) if setting.media_bluebook
           chosen
         end
 
-        # @param name [String] the chapter to find; the row's first `chapter` unless given
-        # @return [Bluebook::Chapter] the chapter the `Editor` row names, from its domain directory
-        def domain_chapter(project, setting, name = setting.chapter)
+        # @param name [String] the bluebook to find; the row's first `bluebook` unless given
+        # @return [Bluebook::Declaration] the bluebook the `Editor` row names, from its domain
+        #   directory
+        def domain_bluebook(project, setting, name = setting.bluebook)
           domain_root = File.join(project, setting.domain)
-          chapter = registry_for(domain_root).bluebooks.values.find { |candidate| candidate.name == name }
-          abort "project_site: #{domain_root} declares no chapter #{name}" unless chapter
-          chapter
+          declaration = registry_for(domain_root).bluebooks.values.find { |candidate| candidate.name == name }
+          abort "project_site: #{domain_root} declares no bluebook #{name}" unless declaration
+          declaration
         end
       end
     end

data/lib/hecks/tools/site_routes/root_files.rb

@@ -13,12 +13,12 @@ module Hecks
         #
         # @param dir [String] the directory they are written under, relative to the working
         #   directory
-        # @param chapter [Bluebook::Chapter] the chapter that declares the route table
+        # @param bluebook [Bluebook::Declaration] the bluebook that declares the route table
         # @return [Hash{String => String}] each file's absolute path to its text; empty with no rows
-        def root_files(dir, chapter)
+        def root_files(dir, declaration)
           base = File.expand_path(dir)
-          files = Projector.call(:site_root, bluebook: chapter).merge(Projector.call(:site_host, bluebook: chapter))
-          files = files.merge(payload_files(base, chapter))
+          files = Projector.call(:site_root, bluebook: declaration).merge(Projector.call(:site_host, bluebook: declaration))
+          files = files.merge(payload_files(base, declaration))
           files.to_h { |name, text| [File.join(base, name), text] }
         end
 
@@ -26,16 +26,17 @@ module Hecks
         # `Payload` row.
         #
         # @param base [String] the directory the project's root files are written under
-        # @param chapter [Bluebook::Chapter] the chapter that declares the route table and the rows
+        # @param bluebook [Bluebook::Declaration] the bluebook that declares the route table and the
+        #   rows
         # @return [Hash{String => String}] each file's path relative to `base` to its text
-        def payload_files(base, chapter)
-          row = Projections::Site::PayloadDriver::PAYLOAD.read(chapter).first
+        def payload_files(base, declaration)
+          row = Projections::Site::PayloadDriver::PAYLOAD.read(declaration).first
           return {} unless row
 
           domain_root = File.join(base, row[:domain])
-          domain = registry_for(domain_root).bluebooks.values.find { |candidate| candidate.name == row[:chapter] }
-          abort "project_site: #{domain_root} declares no chapter #{row[:chapter]}" unless domain
-          Projector.call(:payload_driver, bluebook: chapter, options: { domain_chapter: domain })
+          domain = registry_for(domain_root).bluebooks.values.find { |candidate| candidate.name == row[:bluebook] }
+          abort "project_site: #{domain_root} declares no bluebook #{row[:bluebook]}" unless domain
+          Projector.call(:payload_driver, bluebook: declaration, options: { domain_bluebook: domain })
         rescue ArgumentError => e
           abort "project_site: #{e.message}"
         end
@@ -43,14 +44,14 @@ module Hecks
         # The content system's half of the admin sign-in: four files under the `--cms` directory.
         #
         # @param cms [String] the directory the files are written under
-        # @param chapter [Bluebook::Chapter] the chapter that declares the route table
+        # @param bluebook [Bluebook::Declaration] the bluebook that declares the route table
         # @param admin [Projections::Site::Admin, nil] the checked admin row
         # @return [Hash{String => String}] each file's absolute path to its text
         # @raise [SystemExit] when `--cms` is named and the project declares no `Admin` row
-        def cms_files(cms, chapter, admin)
+        def cms_files(cms, declaration, admin)
           abort "project_site: --cms names #{cms}, but the project declares no Admin row" if admin.nil?
 
-          files = Projector.call(:site_admin_cms, bluebook: chapter, options: { admin: admin })
+          files = Projector.call(:site_admin_cms, bluebook: declaration, options: { admin: admin })
           files.to_h { |name, text| [File.join(File.expand_path(cms), name), text] }
         end
       end

data/lib/hecks/tools/site_routes/templates.rb

@@ -12,7 +12,7 @@ module Hecks
         # @param root [String] the project directory
         # @param out [String, nil] the directory to write to, or nil to rewrite the template in
         #   place
-        # @param site [Site] the chapter that declares the route table, its checked table and
+        # @param site [Site] the bluebook that declares the route table, its checked table and
         #   registry
         # @param template [String, nil] a template named on the command line, rewritten in place
         # @return [Hash{String => String}] the template's path to its text; empty with no edge
@@ -20,12 +20,13 @@ module Hecks
         #   template is missing or lacks a region it needs, or holds a region an edge without a load
         #   balancer does not use
         def template_files(root, out, site, template: nil)
-          edge = Projections::Site::Edge.read(site.chapter, table: site.table, template: template,
+          edge = Projections::Site::Edge.read(site.declaration, table: site.table, template: template,
                                                             vocabulary: Projections::Site::Table.vocabulary(site.registry))
           return missing_edge(template) unless edge
 
-          regions = Projector.call(:site_cdn, bluebook: site.chapter, options: { table: site.table, edge: edge })
-          relative = template || edge.setting.template
+          regions = Projector.call(:site_cdn, bluebook: site.declaration, options: { table: site.table, edge: edge })
+          setting = edge.setting
+          relative = template || setting.template
           source = template_source(root, template, relative)
           text = rewritten(File.read(source), regions, relative)
           { destination(source, out, template, relative) => text }

data/lib/hecks/tools/site_routes.rb

@@ -40,6 +40,9 @@ module Hecks
       # The extensions the module may take; the first is the default.
       EXTENSIONS = %w[ts mts].freeze
 
+      # The `.ts` extension a generated file is written with, before the module's own is applied.
+      TS_EXTENSION = /\.ts\z/
+
       USAGE = "usage: hecks site site_projection.project_site [<project>] [--out=<dir>] " \
               "[--template=<file>] [--cms=<dir>] [--root=<dir>] [--editor=<dir>] " \
               "[--extension=#{EXTENSIONS.join("|")}] [--check]".freeze
@@ -50,8 +53,8 @@ module Hecks
       # The keywords `projection` takes, each nil until given.
       Settings = Struct.new(:out, :template, :extension, :cms, :root_dir, :editor, keyword_init: true)
 
-      # A project's route-table chapter with its checked table and the registry it booted into.
-      Site = Struct.new(:chapter, :table, :registry)
+      # A project's route-table bluebook with its checked table and the registry it booted into.
+      Site = Struct.new(:declaration, :table, :registry)
 
       extend Cli
       extend Templates
@@ -99,8 +102,8 @@ module Hecks
         refuse_extension(settings.extension)
         dir = output_dir(root, settings)
         registry = registry_for(root)
-        chapter = Projections::Site::Table.chapter(registry)
-        site = Site.new(chapter, Projections::Site::Table.read(chapter, registry: registry), registry)
+        declaration = Projections::Site::Table.declaration(registry)
+        site = Site.new(declaration, Projections::Site::Table.read(declaration, registry: registry), registry)
         assemble(root, dir, site, settings)
       rescue Projections::Site::Table::Invalid => e
         abort "project_site: #{e.message}"
@@ -109,15 +112,15 @@ module Hecks
       # @return [Hash{String => String}] every file the project's rows write, by absolute path
       def assemble(root, dir, site, settings)
         written = route_files(dir, site, settings.extension)
-        admin = Projections::Site::Admin.read(site.chapter, table: site.table)
-        written.merge!(admin_files(dir, site.chapter, admin, settings.extension))
+        admin = Projections::Site::Admin.read(site.declaration, table: site.table)
+        written.merge!(admin_files(dir, site.declaration, admin, settings.extension))
         written.merge!(optional_files(settings, site, admin, root))
         written.merge(template_files(root, settings.out, site, template: settings.template))
       end
 
       # @return [Hash{String => String}] the route table module, by absolute path
       def route_files(dir, site, extension)
-        files = Projector.call(:site_routes_ts, bluebook: site.chapter, options: { table: site.table })
+        files = Projector.call(:site_routes_ts, bluebook: site.declaration, options: { table: site.table })
         renamed(dir, files, extension)
       end
 
@@ -125,8 +128,8 @@ module Hecks
       # given.
       def optional_files(settings, site, admin, project)
         files = {}
-        files.merge!(cms_files(settings.cms, site.chapter, admin)) if settings.cms
-        files.merge!(root_files(settings.root_dir, site.chapter)) if settings.root_dir
+        files.merge!(cms_files(settings.cms, site.declaration, admin)) if settings.cms
+        files.merge!(root_files(settings.root_dir, site.declaration)) if settings.root_dir
         files.merge!(editor_files(settings.editor, project, site)) if settings.editor
         files
       end
@@ -134,7 +137,7 @@ module Hecks
       # @return [Hash{String => String}] `files` placed under `dir`, with the module extension
       #   applied
       def renamed(dir, files, extension)
-        files.to_h { |name, text| [File.join(dir, name.sub(/\.ts\z/, ".#{extension}")), text] }
+        files.to_h { |name, text| [File.join(dir, name.sub(TS_EXTENSION, ".#{extension}")), text] }
       end
 
       # @raise [SystemExit] when `extension` is not one the module may take
@@ -156,17 +159,17 @@ module Hecks
       # The admin sign-in module, when the project declares an `Admin` row.
       #
       # @param dir [String] the directory the route table module is written to
-      # @param chapter [Bluebook::Chapter] the chapter that declares the route table
+      # @param bluebook [Bluebook::Declaration] the bluebook that declares the route table
       # @param admin [Projections::Site::Admin, nil] the checked admin row
       # @param extension [String] the extension the modules are written with
       # @return [Hash{String => String}] the module's path to its text; empty with no admin row
-      def admin_files(dir, chapter, admin, extension)
-        files = Projector.call(:site_admin, bluebook: chapter, options: { admin: admin, extension: extension })
+      def admin_files(dir, declaration, admin, extension)
+        files = Projector.call(:site_admin, bluebook: declaration, options: { admin: admin, extension: extension })
         renamed(dir, files, extension)
       end
 
-      # Loads the project's chapters the way a deploy does: the bluebooks, then the hecksagons that
-      # attach the chapters they need.
+      # Loads the project's bluebooks the way a deploy does: the bluebooks, then the hecksagons that
+      # attach the bluebooks they need.
       #
       # @param root [String] the project directory
       # @return [Hecks::Runtime::Registry] the registry

data/lib/hecks/tools/tail_merge.rb

@@ -63,13 +63,13 @@ module Hecks
         loading = Hecks::Ports::Loading.bootstrap
         directory = loading.bluebook_directory(domain_path)
         registry = Hecks::Runtime::Registry.new(root: File.dirname(directory))
-        load_chapters(loading, registry, directory)
-        bluebook = registry.bluebooks.values.first or abort "no bluebook in #{directory}"
+        load_declarations(loading, registry, directory)
+        bluebook = registry.first_bluebook or abort "no bluebook in #{directory}"
         [registry, bluebook]
       end
 
       # Loads the library, the project and the domain into `registry`.
-      def load_chapters(loading, registry, directory)
+      def load_declarations(loading, registry, directory)
         Hecks.with_registry(registry) do
           loading.load_library
           loading.load_project(loading.shared_root(nil, directory))

data/lib/hecks/tools/tenant_provisioning.rb

@@ -22,16 +22,16 @@ module Hecks
       USAGE = "usage: hecks deploy provision <domain-directory> <slug> --domain=NAME --realm=NAME " \
               "--schema=NAME --database=NAME [--adapter=PostgresEra]"
 
-      # The chapters that must boot together for a tenant to be declared and registered.
-      CHAPTER_FILES = %w[deploy/bluebook/deploy.bluebook deploy/bluebook/deploy.hecksagon
-                         tenancy/bluebook/tenancy.bluebook tenancy/bluebook/tenancy.hecksagon].freeze
+      # The bluebooks that must boot together for a tenant to be declared and registered.
+      BLUEBOOK_FILES = %w[deploy/bluebook/deploy.bluebook deploy/bluebook/deploy.hecksagon
+                          tenancy/bluebook/tenancy.bluebook tenancy/bluebook/tenancy.hecksagon].freeze
 
       module_function
 
       # Provisions the tenant and prints what it wrote and confirmed.
       #
       # @param argv [Array<String>] the domain directory, the tenant's slug, then the flags
-      # @param root [String] unused: the chapters are read from the library
+      # @param root [String] unused: the bluebooks are read from the library
       # @return [Integer] 0
       # @raise [SystemExit] with the reason on stderr when the shape is invalid, provisioning is
       #   refused, or the tenant never registers
@@ -76,11 +76,11 @@ module Hecks
       # @param slug [String] the tenant's slug
       # @param options [Hash] the parsed flags
       # @param domain_directory [String] the domain's directory
-      # @return [Hecks::Runtime::Dispatcher] the dispatcher both chapters share
+      # @return [Hecks::Runtime::Dispatcher] the dispatcher both bluebooks share
       # @raise [SystemExit] when the declared shape is refused, or provisioning is refused
       def provision(slug, options, domain_directory)
         lib_hecks  = File.expand_path("..", __dir__)
-        dispatcher = Hecks.boot_files(CHAPTER_FILES.map { |file| File.join(lib_hecks, file) }, install_driving: false)
+        dispatcher = Hecks.boot_files(BLUEBOOK_FILES.map { |file| File.join(lib_hecks, file) }, install_driving: false)
         provision_tenant(dispatcher, slug, tenant_facts(slug, options, domain_directory))
         refuse_if_refused(dispatcher, slug)
 

data/lib/hecks/tools/tools_doc.rb

@@ -7,7 +7,7 @@ require_relative "../tools"
 module Hecks
   module Tools
     # Writes the launcher forms of `docs/tools.md` from the `RetiredScript` rows of the Vocabulary
-    # chapter. Each row names a command (or, in QualityControl, a query); its form is rendered from
+    # bluebook. Each row names a command (or, in QualityControl, a query); its form is rendered from
     # that command's own arguments, the same projection the launcher parses against, so a form can
     # neither keep an argument the command dropped nor miss one it gained.
     #
@@ -73,7 +73,7 @@ module Hecks
       end
 
       # @param section [String] one of `SECTIONS`
-      # @param context [Context] the booted chapters
+      # @param context [Context] the booted bluebooks
       # @return [String] the section's table, header included
       def table(section, context)
         lines = rows.select { |row| row["section"] == section }.group_by { |row| row["script"] }.map do |script, group|
@@ -87,7 +87,7 @@ module Hecks
       def cell(row, context) = "`#{form(row, context).gsub("|", '\|')}`"
 
       # @param row [Hash{String => String}] a `RetiredScript` row
-      # @param context [Context] the booted chapters
+      # @param context [Context] the booted bluebooks
       # @return [String] the launcher form of the row's command or query
       def form(row, context)
         return row["form"] unless row["form"].to_s.empty?
@@ -173,7 +173,7 @@ module Hecks
         text[/<!-- generated:begin tools section=#{section} -->\n(.*?)<!-- generated:end tools -->/m, 1]
       end
 
-      # The booted Hecks chapters the forms are rendered from, built once.
+      # The booted Hecks bluebooks the forms are rendered from, built once.
       class Context
         # @param root [String] the checkout
         def initialize(root)
@@ -186,10 +186,10 @@ module Hecks
         #   name it on the command line
         # @raise [SystemExit] when the row names no command or query
         def spec_for(row)
-          chapter = %w[Custodian Codebase].include?(row["section"]) ? "Hecks" : row["section"]
+          declaration = %w[Custodian Codebase].include?(row["section"]) ? "Hecks" : row["section"]
           name = "#{Naming.snake(row["aggregate"])}.#{row["verb"]}"
-          spec = find_spec(projection(chapter), name) or abort "tools_doc: #{chapter} has no command or query #{name}"
-          [spec, words(chapter, name, row)]
+          spec = find_spec(projection(declaration), name) or abort "tools_doc: #{declaration} has no command or query #{name}"
+          [spec, words(declaration, name, row)]
         end
 
         private
@@ -199,27 +199,27 @@ module Hecks
           cli[:commands][cli[:names][:command][name]] || cli[:questions][cli[:names][:question][name]]
         end
 
-        def projection(chapter)
-          @projections[chapter] ||= begin
-            launcher = Adapters::Driving::LauncherOptions.settings(@runtime, chapter)
+        def projection(declaration)
+          @projections[declaration] ||= begin
+            launcher = Adapters::Driving::LauncherOptions.settings(@runtime, declaration)
             options = Adapters::Driving::LauncherOptions.projection(launcher, "hecks")
-            Projector.call(:cli, bluebook: @runtime.registry.bluebook(chapter), options: options)
+            Projector.call(:cli, bluebook: @runtime.bluebook(declaration), options: options)
           end
         end
 
         # `hecks ir`, `hecks console`, `hecks quality_control sweep.run`, `hecks host.check_era`.
         # The launcher takes a name that is only a query as a query, so no `query` word is needed.
-        def words(chapter, name, row)
-          route = route_for(Adapters::Driving::LauncherOptions.settings(@runtime, chapter) || {}, chapter, name, row)
+        def words(declaration, name, row)
+          route = route_for(Adapters::Driving::LauncherOptions.settings(@runtime, declaration) || {}, declaration, name, row)
           return [route] if route
 
-          [*(Naming.snake(chapter) unless chapter == "Hecks"), name]
+          [*(Naming.snake(declaration) unless declaration == "Hecks"), name]
         end
 
         # @return [String, nil] the one word the launcher routes the name by, when it has one
-        def route_for(settings, chapter, name, row)
+        def route_for(settings, declaration, name, row)
           route = (settings[:names] || {}).key(name)
-          route || (row["verb"] if chapter == "Hecks" && Array(settings[:legacy]).include?(row["verb"]))
+          route || (row["verb"] if declaration == "Hecks" && Array(settings[:legacy]).include?(row["verb"]))
         end
       end
     end