hecks 5.0.0 → 6.0.0

data/lib/hecks/tools/ci_gate_decision.rb

@@ -10,7 +10,7 @@ require_relative "release_only"
 module Hecks
   module Tools
     # Answers whether a change touches what a gated CI job covers: the decision a `CiGate` row of
-    # the Vocabulary chapter names, made by `hecks decide_ci_gate gate=<name>` in the detector job
+    # the Vocabulary bluebook names, made by `hecks decide_ci_gate gate=<name>` in the detector job
     # `hecks project_ci_gates` writes into each workflow.
     #
     # The change is read from the run's own event (`GITHUB_EVENT_PATH`) and head (`GITHUB_SHA`),
@@ -20,6 +20,9 @@ module Hecks
     module CiGateDecision
       NO_COMMIT = "0" * 40
 
+      # A `gate=<name>` argument, capturing the name.
+      GATE_ARG = /\Agate=(.+)\z/
+
       module_function
 
       # @param argv [Array<String>] `gate=<name>`, a `CiGate` row's name
@@ -28,7 +31,7 @@ module Hecks
       # @return [Integer] 0 once an answer is given
       # @raise [SystemExit] when no row has that name
       def main(argv, root: Tools::ROOT, env: ENV)
-        name = argv.filter_map { |arg| arg[/\Agate=(.+)\z/, 1] }.first
+        name = argv.filter_map { |arg| arg[GATE_ARG, 1] }.first
         abort "decide_ci_gate: name a gate, gate=<name>" unless name
         gate = CiGates.gates.find { |row| row["name"] == name }
         abort "decide_ci_gate: no CiGate row named #{name}" unless gate

data/lib/hecks/tools/ci_gates.rb

@@ -5,7 +5,7 @@ require_relative "../tools"
 
 module Hecks
   module Tools
-    # Projects the `CiGate` rows of the Vocabulary chapter into the workflows: each row becomes a
+    # Projects the `CiGate` rows of the Vocabulary bluebook into the workflows: each row becomes a
     # detector job between a pair of marker comments in its `workflow`. The job runs
     # `hecks decide_ci_gate gate=<name>` (`CiGateDecision`), so the decision is made by the binary
     # from the same row, never by shell the workflow carries.

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

@@ -7,6 +7,9 @@ module Hecks
     module CommentStyle
       # Finds the all-caps words in a comment and decides how each should be written instead.
       module CapsWords
+        # A comment indented past its hash, as a code sample or continuation is.
+        INDENTED_COMMENT = /\A#\s{3,}/
+
         private
 
         # @return [Array<Array>] each shouted word as `[offset, word, replacement]`, in text order
@@ -75,17 +78,17 @@ module Hecks
         end
 
         def keep_capitals?(word)
-          bare = word.sub(/'[A-Z]{1,2}\z/, "")
+          bare = word.sub(SHOUTED_SUFFIX, "")
           return false if PROPER_NOUNS.key?(bare)
 
-          ACRONYMS.include?(bare) || @constants.include?(bare) || bare.match?(/\A[IVX]+\z/)
+          ACRONYMS.include?(bare) || @constants.include?(bare) || bare.match?(ROMAN_NUMERAL)
         end
 
         def sentence_start?(comment, masked, offset)
-          before = masked[0, offset].sub(/\A#+\s*/, "")
-          return before.match?(/[.!?]["')\]]*\s+\z/) if before.match?(/[[:alnum:]#{FILLER}]/o)
-          return true if before.match?(/\A\s*(?:[-*•]|─+|\d+[.)])\s+\z/)
-          return false if masked[0, offset].match?(/\A#\s{3,}/)
+          before = masked[0, offset].sub(COMMENT_MARKER, "")
+          return before.match?(SENTENCE_BREAK) if before.match?(/[[:alnum:]#{FILLER}]/o)
+          return true if before.match?(LIST_MARKER)
+          return false if masked[0, offset].match?(INDENTED_COMMENT)
 
           after_sentence_end?(comment)
         end
@@ -95,8 +98,8 @@ module Hecks
           previous = comment.full_line ? @by_line[comment.line - 1] : nil
           return true unless previous&.full_line
 
-          body = previous.text.sub(/\A#+\s*/, "").strip
-          body.empty? || body.match?(/[.!?]["')\]]*\z/)
+          body = previous.text.sub(COMMENT_MARKER, "").strip
+          body.empty? || body.match?(SENTENCE_END)
         end
       end
     end

data/lib/hecks/tools/comment_style/dictionary.rb

@@ -10,6 +10,11 @@ module Hecks
       module Dictionary
         WORDS = "/usr/share/dict/words"
 
+        # An apostrophe and everything after it: the `'s` of a possessive.
+        APOSTROPHE_TAIL = /'.*\z/
+        # A word's last letter written twice, as in "stopp".
+        DOUBLED_LAST_LETTER = /(.)\1\z/
+
         # Technical vocabulary the system word list lacks.
         EXTRA = %w[
           adversarial allowlist anymore app apps arg args arity async backend backtrace baseline
@@ -46,12 +51,12 @@ module Hecks
         def english?(word)
           return true unless words
 
-          bare = word.downcase.delete_suffix("n't").sub(/'.*\z/, "")
+          bare = word.downcase.delete_suffix("n't").sub(APOSTROPHE_TAIL, "")
           SUFFIXES.any? do |suffix, replacement|
             next false unless bare.end_with?(suffix)
 
             stem = bare.delete_suffix(suffix) + replacement
-            words.include?(stem) || words.include?(stem.sub(/(.)\1\z/, '\1'))
+            words.include?(stem) || words.include?(stem.sub(DOUBLED_LAST_LETTER, '\1'))
           end
         end
       end

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

@@ -7,6 +7,11 @@ module Hecks
     module CommentStyle
       # The rewrites for the fixable categories: all-caps words, long bold headings, long lines.
       module Fixing
+        # A line that opens a method definition, after at most one modifier such as `private`.
+        DEF_LINE = /\A\s*(?:\w+\s+)?def\s/
+        # A comment line that opens with a doc tag such as `@param`.
+        TAG_LINE = /\A#+\s*@\w/
+
         private
 
         def fix_line(line, number, wanted)
@@ -79,14 +84,14 @@ module Hecks
         def documents_method?(comment)
           line = comment.line
           line += 1 while @by_line[line + 1]&.full_line
-          @lines[line].to_s.match?(/\A\s*(?:\w+\s+)?def\s/)
+          @lines[line].to_s.match?(DEF_LINE)
         end
 
         def paragraph_start?(comment, masked, offset)
-          return false if masked[0, offset].sub(/\A#+\s*/, "").match?(/[[:alnum:]#{FILLER}]/o)
+          return false if masked[0, offset].sub(COMMENT_MARKER, "").match?(/[[:alnum:]#{FILLER}]/o)
 
           above = comment.full_line ? @by_line[comment.line - 1] : nil
-          !above&.full_line || above.text.match?(/\A#+\s*\z/)
+          !above&.full_line || above.text.match?(EMPTY_COMMENT)
         end
 
         # Splits one over-long prose comment line in two. Lines with no safe
@@ -104,8 +109,8 @@ module Hecks
 
         # An `@tag` line continues, indented, under its tag.
         def wrap_lead(text)
-          lead = text[/\A#+\s*/]
-          text.match?(/\A#+\s*@\w/) ? "#{lead}  " : lead
+          lead = text[COMMENT_MARKER]
+          text.match?(TAG_LINE) ? "#{lead}  " : lead
         end
 
         # @return [Integer, nil] the offset to break at, nil when there is no safe one

data/lib/hecks/tools/comment_style/long_blocks.rb

@@ -28,7 +28,7 @@ module Hecks
         # The text of a block's first line, without its `#`, is its key. A second block opened by
         # the same text in this file gets a `#2` suffix, and so on.
         def block_key(run, seen)
-          text = run.first.text.sub(/\A#+\s*/, "").strip[0, MAX_ANCHOR]
+          text = run.first.text.sub(COMMENT_MARKER, "").strip[0, MAX_ANCHOR]
           text = "(empty)" if text.empty?
           seen[text] += 1
           seen[text] == 1 ? text : "#{text} ##{seen[text]}"

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

@@ -26,7 +26,7 @@ module Hecks
           text = comment.text
           return ["", text] unless @open_spans[comment.line]
 
-          lead = text[/\A#+\s*/].length
+          lead = text[COMMENT_MARKER].length
           close = text.index("`", lead)
           cut = close ? close + 1 : text.length
           [text[0, lead] + (FILLER * (cut - lead)), text[cut..]]
@@ -50,7 +50,7 @@ module Hecks
 
         def continues_paragraph?(comment)
           above = @by_line[comment.line - 1]
-          comment.full_line && above&.full_line && !above.text.match?(/\A#+\s*\z/)
+          comment.full_line && above&.full_line && !above.text.match?(EMPTY_COMMENT)
         end
 
         # Capitalised SQL keywords to leave alone on this line. A keyword such as
@@ -64,7 +64,7 @@ module Hecks
         end
 
         def sql_classes(words)
-          bare = words.map { |word| word.sub(/'[A-Z]{1,2}\z/, "") } - ["A"]
+          bare = words.map { |word| word.sub(SHOUTED_SUFFIX, "") } - ["A"]
           [bare, bare.select { |word| SQL_STRONG.include?(word) }, bare.select { |word| SQL_WEAK.include?(word) }]
         end
 
@@ -85,8 +85,8 @@ module Hecks
         def quoted_heading?(span)
           return false unless span.start_with?('"') && !span.match?(SQL_PHRASES)
 
-          capitals = span.scan(/\b[A-Z]{2,}\b/).size
-          capitals >= 3 || (capitals == 2 && !span.match?(/[a-z]/))
+          capitals = span.scan(SHOUTED_WORD).size
+          capitals >= 3 || (capitals == 2 && !span.match?(LOWERCASE))
         end
       end
     end

data/lib/hecks/tools/comment_style/run.rb

@@ -12,6 +12,9 @@ module Hecks
     module CommentStyle
       # Lints a set of paths and renders the result.
       class Run
+        # A shebang line that runs Ruby, matched as bytes.
+        RUBY_SHEBANG = /\A#!.*ruby/n
+
         # @param paths [Array<String>] files or directories
         # @param only [Array<String>, nil] categories to keep
         # @param baseline [Hash{String => Hash{String => Integer}}] the long blocks to tolerate
@@ -116,7 +119,7 @@ module Hecks
         # rather than refused for not being UTF-8.
         def ruby_files(dir)
           scripts = Dir[File.join(dir, "**", "*")].select do |path|
-            File.file?(path) && File.extname(path).empty? && File.open(path, "rb", &:gets).to_s.match?(/\A#!.*ruby/n)
+            File.file?(path) && File.extname(path).empty? && File.open(path, "rb", &:gets).to_s.match?(RUBY_SHEBANG)
           end
           Dir[File.join(dir, "**", "*.rb")] + scripts
         end

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

@@ -17,6 +17,13 @@ module Hecks
         # Raised when an automatic fix would change code rather than comments.
         class Error < RuntimeError; end
 
+        # A generator's banner: "generated", then "do not edit", in any case and across lines.
+        GENERATED_BANNER = /\bgenerated\b.*?\bdo not edit\b/im
+        # A whole token that is an all-caps name, such as `PATH` or `MAX_LINE`.
+        SHOUTED_NAME = /\A[A-Z][A-Z0-9_]+\z/
+        # An all-caps name anywhere in a token.
+        SHOUTED_NAME_IN = /[A-Z][A-Z0-9_]+/
+
         include LongBlocks
         include Masking
         include CapsWords
@@ -67,7 +74,7 @@ module Hecks
         # A generated file's comments belong to its generator, and its
         # `GENERATED ... DO NOT EDIT` banner is a convention tools recognise.
         def generated?
-          @lines.first(8).join.match?(/\bgenerated\b.*?\bdo not edit\b/im)
+          @lines.first(8).join.match?(GENERATED_BANNER)
         end
 
         # Helpers defined inside a spec are test scaffolding, not API, so the
@@ -97,8 +104,8 @@ module Hecks
         def code_words
           Ripper.lex(@source).each_with_object(Set.new) do |(_, type, text, _), words|
             case type
-            when :on_const, :on_tstring_content then words << text if text.match?(/\A[A-Z][A-Z0-9_]+\z/)
-            when :on_heredoc_beg, :on_heredoc_end then words.merge(text.scan(/[A-Z][A-Z0-9_]+/))
+            when :on_const, :on_tstring_content then words << text if text.match?(SHOUTED_NAME)
+            when :on_heredoc_beg, :on_heredoc_end then words.merge(text.scan(SHOUTED_NAME_IN))
             end
           end
         end

data/lib/hecks/tools/comment_style/structure_checks.rb

@@ -2,6 +2,7 @@
 
 require_relative "../../tools"
 require_relative "walker"
+require "hecks/naming"
 
 module Hecks
   module Tools
@@ -9,6 +10,13 @@ module Hecks
       # The structural categories: the doc tags a public method carries and the shape of a long
       # class doc.
       module StructureChecks
+        # A doc that opts out of the tag checks: private, no-doc, or a closing "(see ...)" pointer.
+        TAGS_EXEMPT = /@api private|@private|:nodoc:|\(see (?:`[^`]+`|#\w)[^)]*\)\W*\z/m
+        # The indent, hashes and one space that open a doc line.
+        DOC_LINE_MARKER = /\A\s*#+\s?/
+        # A `##` section heading inside a class doc.
+        SECTION_HEADING = /\A#\s*##+ /
+
         private
 
         def structure_violations
@@ -37,11 +45,11 @@ module Hecks
 
         def method_violations(method)
           return [] unless method.visibility == :public
-          return [] unless CommentStyle.public_surface.include?(method.type_fqn.to_s.split("::").last)
+          return [] unless CommentStyle.public_surface.include?(Hecks::Naming.demodulise(method.type_fqn))
 
           doc = doc_above(method.line).join("\n")
           return undocumented_violation(method) if doc.empty?
-          return [] if doc.match?(/@api private|@private|:nodoc:|\(see (?:`[^`]+`|#\w)[^)]*\)\W*\z/m)
+          return [] if doc.match?(TAGS_EXEMPT)
 
           tag_violations(method, doc)
         end
@@ -94,7 +102,8 @@ module Hecks
         end
 
         def lead_line(doc)
-          doc.lines.map { |line| line.sub(/\A\s*#+\s?/, "").strip }.reject(&:empty?).first.to_s
+          lines = doc.lines.map { |line| line.sub(DOC_LINE_MARKER, "").strip }
+          lines.reject(&:empty?).first.to_s
         end
 
         def violation(method, category, detail)
@@ -103,7 +112,7 @@ module Hecks
 
         def long_doc_violations(type)
           doc = doc_above(type.line)
-          return [] if doc.length <= LONG_CLASS_DOC || doc.any? { |l| l.match?(/\A#\s*##+ /) }
+          return [] if doc.length <= LONG_CLASS_DOC || doc.any? { |l| l.match?(SECTION_HEADING) }
 
           [Violation.new(path, type.line, "unstructured_class_doc", "#{type.fqn} (#{doc.length} lines)")]
         end

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

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

data/lib/hecks/tools/comment_style.rb

@@ -65,13 +65,36 @@ module Hecks
       # needs no doc unless it carries a real why.
       PUBLIC_SURFACE = Set["Storehouse"].freeze
 
+      # The hashes that open a comment and the space after them.
+      COMMENT_MARKER = /\A#+\s*/
+      # A comment line with nothing after its hashes: a paragraph break.
+      EMPTY_COMMENT = /\A#+\s*\z/
+      # A shouted contraction or possessive ending: `'S`, `'LL`, `'RE`.
+      SHOUTED_SUFFIX = /'[A-Z]{1,2}\z/
+      # A Roman numeral, which stays in capitals.
+      ROMAN_NUMERAL = /\A[IVX]+\z/
+      # Sentence punctuation, any closing quotes or brackets, then the space before a new word.
+      SENTENCE_BREAK = /[.!?]["')\]]*\s+\z/
+      # Sentence punctuation and any closing quotes or brackets, ending the text.
+      SENTENCE_END = /[.!?]["')\]]*\z/
+      # A list marker alone before the word: a bullet, a rule, or a number.
+      LIST_MARKER = /\A\s*(?:[-*•]|─+|\d+[.)])\s+\z/
+      # A whole word of two or more capitals.
+      SHOUTED_WORD = /\b[A-Z]{2,}\b/
+      # Any lowercase letter.
+      LOWERCASE = /[a-z]/
+      # A backtick code span.
+      CODE_SPAN = /`[^`]*`/
+      # A `class` or `module` line, capturing the type's own name.
+      TYPE_DEFINITION = /^\s*(?:class|module)\s+([A-Z]\w*)/
+
       extend Cli
 
       # Class and module names defined under `lib/`, keyed by their shouted form.
       def self.class_names
         @class_names ||= Dir["lib/**/*.rb"].each_with_object({}) do |file, names|
-          File.read(file).scan(/^\s*(?:class|module)\s+([A-Z]\w*)/) do |(name)|
-            names[name.upcase] ||= name if name.match?(/[a-z]/)
+          File.read(file).scan(TYPE_DEFINITION) do |(name)|
+            names[name.upcase] ||= name if name.match?(LOWERCASE)
           end
         end
       end

data/lib/hecks/tools/deploy_recipe/generation.rb

@@ -13,7 +13,7 @@ module Hecks
         # @param root [String] the checkout
         # @return [String] `--out`, else `deploy/<name>` in the checkout
         def output_dir(deployment, root)
-          out = deployment.options.out
+          out = deployment.out
           out ? File.expand_path(out) : File.join(root, "deploy", deployment.infra_name)
         end
 

data/lib/hecks/tools/deploy_recipe/targets.rb

@@ -50,7 +50,7 @@ module Hecks
                 env ["SESSION_SECRET"]
               end
 
-          then re-run hecks deploy project __DOMAIN__.
+          then re-run hecks deploy recipe.project __DOMAIN__.
         MSG
 
         # A world view whose `deployed_to` answers for one declared target, so a projector that

data/lib/hecks/tools/deploy_recipe/worlds.rb

@@ -7,8 +7,12 @@ module Hecks
     module DeployRecipe
       # Finds and loads the `.world` file a domain deploys from, and the registry it boots into.
       module Worlds
+        # A hecksagon's `FrameworkBluebooks.load!("Name")`, capturing the bluebook's name.
+        BLUEBOOK_LOAD = /FrameworkBluebooks\.load!\(\s*"([^"]+)"\s*\)/
+
         # The `.world` file named after the directory; failing that, the sole `*.world` file under
-        # `<domain>/bluebook/`; failing that, the one named after the chapter the domain's hecksagon
+        # `<domain>/bluebook/`; failing that, the one named after the bluebook the domain's
+        # hecksagon
         # attaches by name (`qa/` attaches QualityControl and also holds a Governance `.world`).
         # It picks by no other rule: guessing which is the domain is not this generator's call.
         #
@@ -26,16 +30,17 @@ module Hecks
           world_file
         end
 
-        # The snake-cased names of the chapters a domain's hecksagons attach by name
-        # (`Hecks::Chapters.load!("QualityControl")`), which its `.world` and `.hecksagon` files
+        # The snake-cased names of the bluebooks a domain's hecksagons attach by name
+        # (`Hecks::FrameworkBluebooks.load!("QualityControl")`), which its `.world` and `.hecksagon`
+        # files
         # are named after.
         #
         # @param domain [String] the domain directory
         # @return [Array<String>] such as `["quality_control"]`
         def attached_stems(domain)
-          Dir.glob(File.join(domain, "bluebook", "*.hecksagon"))
-             .flat_map { |path| File.read(path).scan(/Chapters\.load!\(\s*"([^"]+)"\s*\)/).flatten }
-             .map { |name| Hecks::Naming.snake(name) }.uniq
+          hecksagons = Dir.glob(File.join(domain, "bluebook", "*.hecksagon"))
+          names = hecksagons.flat_map { |path| File.read(path).scan(BLUEBOOK_LOAD).flatten }
+          names.map { |name| Hecks::Naming.snake(name) }.uniq
         end
 
         # @param world_file [String] the base `.world` file
@@ -69,8 +74,9 @@ module Hecks
         end
 
         # Loads the whole registry a domain boots with, not just its own `.bluebook`, because a
-        # cross-domain invoke grant can live in any attached chapter. A domain with no bluebook of
-        # its own (the QA ledger) gets its chapter from the hecksagon's `Chapters.load!`. `root:` is
+        # cross-domain invoke grant can live in any attached bluebook. A domain with no bluebook of
+        # its own (the QA ledger) gets its bluebook from the hecksagon's `FrameworkBluebooks.load!`.
+        # `root:` is
         # required or `attaches ... from: :vendor` refuses with "needs a registry with a root to
         # vendor from".
         #
@@ -85,7 +91,7 @@ module Hecks
 
         private
 
-        # The sole `*.world` file, or the sole one named after an attached chapter.
+        # The sole `*.world` file, or the sole one named after an attached bluebook.
         def sole_world_file(domain)
           candidates = Dir.glob(File.join(domain, "bluebook", "*.world"))
           named = candidates.select { |path| attached_stems(domain).include?(File.basename(path, ".world")) }

data/lib/hecks/tools/deploy_recipe.rb

@@ -22,7 +22,7 @@ module Hecks
     # `--schema` override the stack for shared-database hosting: `stack_name` is appended to, so
     # re-running with the same `--tenant` regenerates the same stack.
     module DeployRecipe
-      USAGE = "usage: hecks deploy project <domain> [--tenant=<slug>] [--schema=<name>] " \
+      USAGE = "usage: hecks deploy recipe.project <domain> [--tenant=<slug>] [--schema=<name>] " \
               "[--out=<dir>] [--environment=<name>] [--target=<adapter>]"
 
       # The directory `ports/` and `adapters/` live under, loaded into every domain's registry.
@@ -32,8 +32,15 @@ module Hecks
       Options = Struct.new(:tenant, :out, :environment, :target)
 
       # What the generator resolved about a domain: its directory, the flags, the `.world` file and
-      # its declaration, the `deployed_to` settings, the stack's name, the registry and the chapter.
-      Deployment = Struct.new(:domain, :options, :world_file, :world, :settings, :infra_name, :registry, :chapter)
+      # its declaration, the `deployed_to` settings, the stack's name, the registry and the
+      # bluebook.
+      Deployment = Struct.new(:domain, :options, :world_file, :world, :settings, :infra_name, :registry, :declaration) do
+        # @return [Hash{Symbol => String}] the `--tenant` and `--schema` flags
+        def tenant = options.tenant
+
+        # @return [String, nil] the `--out` directory, when one was given
+        def out = options.out
+      end
 
       extend Worlds
       extend Targets
@@ -94,7 +101,7 @@ module Hecks
 
       # @param domain [String] the domain directory
       # @param options [Options] the flags
-      # @return [Deployment] the world, settings, registry and chapter the recipe is projected from
+      # @return [Deployment] the world, settings, registry and bluebook the recipe is projected from
       # @raise [SystemExit] when the domain or its `.world` cannot generate
       def resolve(domain, options)
         world_file = world_file_for(domain)
@@ -103,14 +110,14 @@ module Hecks
         settings = tenant_settings(world.for_verb("deployed_to"), options, File.basename(domain))
         registry = cross_domain_registry(domain, basename)
         Deployment.new(domain, options, world_file, world, settings, settings[:stack_name] || File.basename(domain),
-                       registry, chapter_for(registry, world, world_file, basename))
+                       registry, bluebook_for(registry, world, world_file, basename))
       end
 
-      # @return [Object] the chapter the world names
+      # @return [Object] the bluebook the world names
       # @raise [SystemExit] when the registry holds none
-      def chapter_for(registry, world, world_file, bluebook_basename)
+      def bluebook_for(registry, world, world_file, bluebook_basename)
         registry.bluebook(world.domain) or
-          abort "#{world_file} declares no #{world.domain} chapter — #{bluebook_basename}.bluebook's own " \
+          abort "#{world_file} declares no #{world.domain} bluebook — #{bluebook_basename}.bluebook's own " \
                 "Hecks.bluebook name has to match world.domain."
       end
 
@@ -123,7 +130,7 @@ module Hecks
       # @return [Hash{String => String}] the files to write
       # @raise [SystemExit] when the domain's own settings conflict
       def project(target, deployment, root)
-        artifact = Hecks::Projector.call(target, bluebook: deployment.chapter,
+        artifact = Hecks::Projector.call(target, bluebook: deployment.declaration,
                                                  options: projector_options(deployment, root), world: deployment.world)
         # Only when the domain declared `smoke true`; otherwise nothing is added.
         artifact.merge(Hecks::Projections::Deploy::Smoke.files(deployment.settings, stack_name: deployment.infra_name))
@@ -133,7 +140,7 @@ module Hecks
 
       def projector_options(deployment, root)
         {
-          tenant:                deployment.options.tenant,
+          tenant:                deployment.tenant,
           domain_dir:            deployment.domain,
           root:                  root,
           world_file:            deployment.world_file,

data/lib/hecks/tools/deploy_recipe_lint/fixtures.rb

@@ -62,7 +62,7 @@ module Hecks
           Dir.mktmpdir do |dir|
             domain_dir = write_fixture(dir, basename, world_body, env_local: env_local)
             outcome = Hecks::Adapters::ConsoleCapture.capture { DeployRecipe.main([domain_dir], root: root) }
-            outcome.ok? or raise Error, "hecks deploy project failed generating the #{basename} fixture: #{outcome.output}"
+            outcome.ok? or raise Error, "hecks deploy recipe.project failed generating the #{basename} fixture: #{outcome.output}"
           end
           File.join(root, "deploy", basename)
         end

data/lib/hecks/tools/deploy_recipe_lint/makefile.rb

@@ -10,6 +10,12 @@ module Hecks
         # A target line: a name, a colon, and nothing but prerequisites after it.
         TARGET_LINE = %r{\A([A-Za-z0-9_./$(){}-]+):(?:\s.*)?\z}
 
+        # The leading `@` that stops Make echoing a recipe line.
+        ECHO_OFF = /\A@/
+
+        # A statement's trailing `;` and any space after it.
+        TRAILING_SEMICOLON = /;\s*\z/
+
         # Maps each target name to its `[line_no, raw_text]` recipe lines, tabs and continuations
         # intact.
         def parse_targets(text)
@@ -35,7 +41,7 @@ module Hecks
 
         # Drops the leading Make `@` and trailing `;` so exit-code checks match the bare statement.
         def normalize_statement(text)
-          text.sub(/\A@/, "").strip.sub(/;\s*\z/, "")
+          text.sub(ECHO_OFF, "").strip.sub(TRAILING_SEMICOLON, "")
         end
 
         private

data/lib/hecks/tools/drop_implicit_append_fields.rb

@@ -13,6 +13,9 @@ module Hecks
       # One attribute a command repeats.
       Candidate = Struct.new(:command_name, :field, :type, keyword_init: true)
 
+      # An `emits` line, which closes a command's block.
+      EMITS_LINE = /^\s*emits\s/
+
       module_function
 
       # Runs the codemod over every example domain and prints what it found.
@@ -86,7 +89,7 @@ module Hecks
         window_start = text.index(/^\s*command\s+"#{Regexp.escape(candidate.command_name)}"/)
         return [text, false] unless window_start
 
-        window_end = text.index(/^\s*emits\s/, window_start)
+        window_end = text.index(EMITS_LINE, window_start)
         return [text, false] unless window_end
 
         before = text[0...window_start]

data/lib/hecks/tools/era_projection_backfill.rb

@@ -32,16 +32,21 @@ module Hecks
         loading = Hecks::Ports::Loading.bootstrap
         directory = loading.bluebook_directory(domain_path)
         registry = Hecks::Runtime::Registry.new(root: File.dirname(directory))
-        Hecks.with_registry(registry) do
-          loading.load_library
-          loading.load_project(loading.shared_root(nil, directory))
-          loading.load_each(directory, %w[*.port *.adapter *.bluebook *.hecksagon *.world])
-        end
+        Hecks.with_registry(registry) { load_declarations(loading, directory) }
 
-        bluebook = registry.bluebooks.values.first or abort "no bluebook in #{directory}"
+        bluebook = registry.first_bluebook or abort "no bluebook in #{directory}"
         [registry, bluebook]
       end
 
+      # Loads the library, the project and the domain's files into the registry in scope, then the
+      # copy's local files and any named environment, so the bindings are the runtime's own.
+      def load_declarations(loading, directory)
+        loading.load_library
+        loading.load_project(loading.shared_root(nil, directory))
+        loading.load_each(directory, %w[*.port *.adapter *.bluebook *.hecksagon *.world])
+        loading.load_overlay(directory, ENV.fetch("HECKS_PROJECT_ENVIRONMENT", nil))
+      end
+
       # @return [Hash] the persistence binding's settings
       # @raise [SystemExit] when the bound adapter holds no eras
       def lineage_settings(registry, bluebook)

data/lib/hecks/tools/era_reattest.rb

@@ -46,15 +46,20 @@ module Hecks
         loading = Hecks::Ports::Loading.bootstrap
         directory = loading.bluebook_directory(domain_path)
         registry = Hecks::Runtime::Registry.new(root: File.dirname(directory))
-        Hecks.with_registry(registry) do
-          loading.load_library
-          loading.load_project(loading.shared_root(nil, directory))
-          loading.load_each(directory, %w[*.port *.adapter *.bluebook *.hecksagon *.world])
-        end
-        bluebook = registry.bluebooks.values.first or abort "no bluebook in #{directory}"
+        Hecks.with_registry(registry) { load_declarations(loading, directory) }
+        bluebook = registry.first_bluebook or abort "no bluebook in #{directory}"
         [registry, bluebook]
       end
 
+      # Loads the library, the project and the domain's files into the registry in scope, then the
+      # copy's local files and any named environment, so the bindings are the runtime's own.
+      def load_declarations(loading, directory)
+        loading.load_library
+        loading.load_project(loading.shared_root(nil, directory))
+        loading.load_each(directory, %w[*.port *.adapter *.bluebook *.hecksagon *.world])
+        loading.load_overlay(directory, ENV.fetch("HECKS_PROJECT_ENVIRONMENT", nil))
+      end
+
       # @return [Object] the domain's ensured lineage
       # @raise [SystemExit] when the bound adapter holds no eras
       def open_lineage(registry, bluebook)