hecks 4.0.0 → 6.0.0

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)

data/lib/hecks/tools/fuzz_sweep/findings.rb

@@ -8,7 +8,8 @@ module Hecks
       # Replays a generated sequence and judges, groups and shrinks what it finds.
       module Findings
         # An exception escaping Replay's per-step isolation is an interpreter defect, not a domain
-        # refusal.
+        # refusal. A sweep on SQLite or Postgres also checks that adapter's projection answers
+        # each rooted read model as the in-process loop does (ADR 0122).
         #
         # @param domain [String] the domain directory
         # @param steps [Array<Hash>] the sequence to replay
@@ -17,7 +18,7 @@ module Hecks
         #   `:crash`) and its message
         def outcome(domain, steps, adapter = :memory)
           history = Hecks::Fuzzing::Replay.call(domain, steps, adapter: adapter)
-          violations = Hecks::Fuzzing::Properties.check(history).reject { |_, result| result == true }
+          violations = property_results(domain, steps, adapter, history).reject { |_, result| result == true }
           return [:clean, nil] if violations.empty?
 
           [:property_violation, violations.map { |name, message| "#{name}: #{message}" }.join("; ")]
@@ -25,6 +26,21 @@ module Hecks
           [:crash, "#{e.class}: #{e.message}"]
         end
 
+        # The standard battery's results, and the projection agreement's when `adapter` has one.
+        #
+        # @param domain [String] the domain directory
+        # @param steps [Array<Hash>] the sequence replayed
+        # @param adapter [Symbol] the persistence it was replayed on
+        # @param history [Hash] the replayed history
+        # @return [Hash{Symbol => true, String}] each property name mapped to its result
+        def property_results(domain, steps, adapter, history)
+          results = Hecks::Fuzzing::Properties.check(history)
+          agreement = Hecks::Fuzzing::ProjectionAgreement
+          return results unless agreement.checks?(adapter)
+
+          results.merge(agreement::PROPERTY => agreement.property(domain, steps, adapter))
+        end
+
         # Groups findings by property name or exception class, stable across shrink candidates.
         #
         # @param message [String, nil] a finding's message

data/lib/hecks/tools/fuzz_sweep/options.rb

@@ -30,11 +30,15 @@ module Hecks
         def apply_option(options, arg, rest)
           if (key = INTEGER_OPTIONS[arg]) then options[key] = Integer(rest.shift)
           elsif arg == "--persist-regressions" then options[:persist] = true
-          elsif arg == "--adapter" then options[:adapter] = rest.shift.to_s.downcase.to_sym
+          elsif arg == "--adapter" then options[:adapter] = adapter_name(rest.shift)
           else options[:domain] = arg
           end
         end
 
+        # @param word [String, nil] the word after `--adapter`
+        # @return [Symbol] the adapter it names, lowercased
+        def adapter_name(word) = word.to_s.downcase.to_sym
+
         # @return [Boolean] whether `adapter` is one a sweep can boot on; warns when it is not
         def adapter_known?(adapter)
           return true if ADAPTERS.include?(adapter)

data/lib/hecks/tools/fuzz_sweep.rb

@@ -85,12 +85,12 @@ module Hecks
         fuzz_in_pool(domains, workers) { |domain| fuzz_in_child(options, domain, root) }
       end
 
-      # Runs in a forked child. A Postgres child gets its own scratch schema, so children can fuzz
-      # one database at once.
+      # Runs in a forked child. A Postgres child fuzzes in its own scratch schema, which
+      # `IsolatedBoot.scratch_schema` names by the child's pid, so children can fuzz one database
+      # at once.
       #
       # @return [Boolean] whether the domain was clean
       def fuzz_in_child(options, domain, root)
-        ENV[Hecks::Fuzzing::IsolatedBoot::FUZZ_SCHEMA_ENV] = "hecks_fuzz_#{Process.pid}" if options[:adapter] == :postgres
         fuzz_with(options, domain, root)
       end
 
@@ -177,13 +177,25 @@ module Hecks
       end
 
       # @return [Array(Symbol, String)] the verdict, replaying a clean run once more to see that it
-      #   repeats; and its message
+      #   repeats, and, for a domain that attaches Bulk, once more each way to see that a bulk run
+      #   matches dispatching its rows by hand, and on a SQL store that one statement matches row by
+      #   row (ADR 0129); and its message
       def verdict_for(domain, generated, adapter)
         verdict, message = outcome(domain, generated, adapter)
         return [verdict, message] unless verdict == :clean
 
         determinism = Hecks::Fuzzing::Properties.replay_is_deterministic(domain, generated, adapter: adapter)
-        determinism == true ? [:clean, nil] : [:nondeterminism, determinism]
+        return [:nondeterminism, determinism] unless determinism == true
+
+        parity = Hecks::Fuzzing::Properties.bulk_runs_match_hand_dispatch(domain, generated, adapter: adapter)
+        return [:bulk_parity, parity] unless parity == true
+
+        set_parity(domain, generated, adapter)
+      end
+
+      def set_parity(domain, generated, adapter)
+        parity = Hecks::Fuzzing::Properties.set_transform_matches_row_by_row(domain, generated, adapter: adapter)
+        parity == true ? [:clean, nil] : [:set_transform_parity, parity]
       end
     end
   end

data/lib/hecks/tools/gate.rb

@@ -1,13 +1,13 @@
 # frozen_string_literal: true
 
 require "open3"
-require "yaml"
+require "hecks/vocabulary"
 require_relative "../tools"
 
 module Hecks
   module Tools
-    # Runs a stage's checks, which `lib/hecks/gate/stages.yml` holds as data, all at once and
-    # reports every one, so a red check does not hide the others.
+    # Runs a stage's checks, which the `GateStage` and `GateCheck` rows of the Vocabulary bluebook
+    # hold as data, all at once and reports every one, so a red check does not hide the others.
     #
     #   hecks gate pre_push                # every check of the stage
     #   hecks gate pre_push only=rubocop   # the named checks
@@ -16,16 +16,38 @@ module Hecks
     # A green stage prints which checks passed; a red one prints each failing check's whole output
     # and what its failure means, and answers status 1.
     module Gate
-      STAGES_FILE = File.expand_path("../gate/stages.yml", __dir__)
       USAGE = "usage: hecks gate <stage> [only=a,b] | hecks gate --list"
 
       module_function
 
+      # @return [Hash{String => Hash}] each stage by name: its `env` and its `checks`, in order,
+      #   each check with its `id`, `title`, `run` words and `blocked`
+      def stages
+        checks = Vocabulary.rows("GateCheck").to_h { |row| [row["name"], check(row)] }
+        Vocabulary.rows("GateStage").to_h do |row|
+          stage = { "env" => env(row["env"]), "checks" => row["checks"].split(",").map { |name| checks.fetch(name) } }
+          [row["name"], stage]
+        end
+      end
+
+      # @param row [Hash{String => String}] a `GateCheck` row
+      # @return [Hash] the check: a script runs as `sh -ec`, otherwise `argv` is the command's words
+      def check(row)
+        run = row["script"].empty? ? row["argv"].split : ["sh", "-ec", row["script"]]
+        row.slice("id", "title", "blocked").merge("run" => run)
+      end
+
+      # @param words [String] `NAME=value` words
+      # @return [Hash{String => String}] the variables a stage sets
+      def env(words)
+        words.split.to_h { |word| word.split("=", 2) }
+      end
+
       # @param argv [Array<String>] a stage name and optionally `only=a,b`, or `--list`
       # @param root [String] the checkout the checks run in
       # @return [Integer] 0 when every check passed, 1 when one failed, 2 on bad usage
       def main(argv, root: Tools::ROOT, **)
-        stages = YAML.load_file(STAGES_FILE, aliases: true)
+        stages = self.stages
         return list(stages) if argv == ["--list"]
 
         name, only = parse(argv)

data/lib/hecks/tools/hoist_local_givens/rewriting.rb

@@ -105,11 +105,12 @@ module Hecks
         # `seg` with each of the candidate's occurrences swapped for a bare reference.
         def bare_references(seg, pattern, candidate)
           seg.gsub(pattern) do
-            indent, predicate_src = Regexp.last_match.captures
+            match = Regexp.last_match
+            indent, predicate_src = match.captures
             if matching_occurrence?(predicate_src, candidate)
               "#{indent}given(#{candidate.description.inspect})\n"
             else
-              Regexp.last_match(0)
+              match[0]
             end
           end
         end

data/lib/hecks/tools/hoist_local_givens.rb

@@ -104,10 +104,8 @@ module Hecks
       # @param registry [Object] the booted bluebooks
       # @return [Hash{String => Array}] each command's rules, by location
       def command_rule_map(registry)
-        Hecks::QueryIR.collect_rules(registry)
-                      .reject { |r| r.location.end_with?(" (declared)") }
-                      .group_by(&:location)
-                      .transform_values { |rules| rules.map { |r| [r.kind, r.description, r.canonical] }.sort }
+        local = Hecks::QueryIR.collect_rules(registry).reject { |r| r.location.end_with?(" (declared)") }
+        local.group_by(&:location).transform_values { |rules| rules.map { |r| [r.kind, r.description, r.canonical] }.sort }
       end
 
       # @param files [Array<String>] one example domain's bluebook files

data/lib/hecks/tools/lanes/prebuilt_workflow.rb

@@ -23,7 +23,7 @@ module Hecks
         def header(row)
           name = row["name"]
           ["name: Publish #{name}", "",
-           "# Generated by hecks project_lanes from the PrebuiltBinary rows of the Vocabulary chapter. Do not hand-edit.",
+           "# Generated by hecks project_lanes from the PrebuiltBinary rows of the Vocabulary bluebook. Do not hand-edit.",
            "#",
            "# Builds #{row["executable"]} from #{row["crate"]} for #{row["target"]} and publishes it as the release",
            "# #{name}-<key>, where the key is a hash of the crate's build inputs. A client that needs the same",

data/lib/hecks/tools/lanes/rows.rb

@@ -5,8 +5,14 @@ require "hecks/vocabulary"
 module Hecks
   module Tools
     module Lanes
-      # The `Lane` rows of the Vocabulary chapter, checked against what the projection can express.
+      # The `Lane` rows of the Vocabulary bluebook, checked against what the projection can express.
       module Rows
+        # Empty, or a trailer key of dash-joined words such as `Release-Approved-By`.
+        TRAILER_KEY = /\A([A-Za-z][A-Za-z0-9]*(-[A-Za-z0-9]+)*)?\z/
+
+        # Empty, or a whole number of hours.
+        WHOLE_HOURS = /\A\d*\z/
+
         module_function
 
         # @return [Array<Hash{String => String}>] the `Lane` rows
@@ -36,10 +42,10 @@ module Hecks
 
         # @return [Boolean] whether `release_trailer` is empty (nothing is released from the lane)
         #   or a git trailer key such as `Release-Approved-By`
-        def trailer?(lane) = lane["release_trailer"].to_s.match?(/\A([A-Za-z][A-Za-z0-9]*(-[A-Za-z0-9]+)*)?\z/)
+        def trailer?(lane) = lane["release_trailer"].to_s.match?(TRAILER_KEY)
 
         # @return [Boolean] whether `alert_after` is empty (never late) or whole hours
-        def hours?(lane) = lane["alert_after"].to_s.match?(/\A\d*\z/)
+        def hours?(lane) = lane["alert_after"].to_s.match?(WHOLE_HOURS)
 
         def follows_problem(lane, names)
           follows = lane["follows"].to_s

data/lib/hecks/tools/lanes/ruleset.rb

@@ -9,7 +9,7 @@ module Hecks
       # The ruleset GitHub is given for a guarded lane.
       #
       # A guarded lane cannot be deleted or rewound, and a `green` lane takes only a commit on
-      # which every `RequiredCheck` of the Vocabulary chapter has already passed. No actor is let
+      # which every `RequiredCheck` of the Vocabulary bluebook has already passed. No actor is let
       # past it: a push of a commit that passed is how a promotion moves the lane, and the GitHub
       # Actions app cannot be named as a bypass actor.
       module Ruleset

data/lib/hecks/tools/lanes/watch_workflow.rb

@@ -11,7 +11,7 @@ module Hecks
         HEADER = <<~YAML.chomp
           name: Watch lanes
 
-          # Generated by hecks project_lanes from the Lane rows of the Vocabulary chapter. Do not hand-edit.
+          # Generated by hecks project_lanes from the Lane rows of the Vocabulary bluebook. Do not hand-edit.
           #
           # Every hour, asks `PromotionRun` whether a lane has stood behind the lane it follows for
           # longer than its Lane row allows (`alert_after`, in hours). The rule is decided there, not

data/lib/hecks/tools/lanes/workflow.rb

@@ -10,7 +10,7 @@ module Hecks
         HEADER = <<~YAML.chomp
           name: Promote
 
-          # Generated by hecks project_lanes from the Lane rows of the Vocabulary chapter. Do not hand-edit.
+          # Generated by hecks project_lanes from the Lane rows of the Vocabulary bluebook. Do not hand-edit.
           #
           # After CI finishes on a push to the lane a lane follows, asks `PromotionRun` to move the
           # lane onto the newest commit of that lane every RequiredCheck passed on. Which commit may

data/lib/hecks/tools/lanes.rb

@@ -6,7 +6,7 @@ require_relative "../hecks/adapters/github_rulesets"
 
 module Hecks
   module Tools
-    # Projects the `Lane` rows of the Vocabulary chapter into what GitHub is told about them: a
+    # Projects the `Lane` rows of the Vocabulary bluebook into what GitHub is told about them: a
     # ruleset for each guarded lane (`.github/rulesets/<lane>.json`), one for the tag such a lane
     # feeds (`.github/rulesets/tag-<tag>.json`), and the workflow that promotes
     # each lane that follows another (`.github/workflows/promote.yml`). The workflow only runs

data/lib/hecks/tools/oidc_manifests.rb

@@ -6,7 +6,7 @@ require_relative "../tools"
 module Hecks
   module Tools
     # Projects each domain's OIDC client and scope manifest (`Hecks::Projections::OIDC`) into an
-    # `oidc.json` beside the domain, or into one `<chapter>.oidc.json` for each chapter of a
+    # `oidc.json` beside the domain, or into one `<bluebook>.oidc.json` for each bluebook of a
     # directory that holds several.
     #
     # A domain that has no bluebook is skipped and one that cannot be projected is reported, so a
@@ -38,15 +38,12 @@ module Hecks
       # @return [Array<String>] the domain directories, relative to `root`, sorted
       def domains(root)
         folder = Hecks::Adapters::Folder.new
-        Dir.glob(File.join(root, "**/*.hecksagon"))
-           .map { |path| folder.domain_root(File.dirname(path)) }
-           .compact
-           .map { |path| path.delete_prefix("#{root}/") }
-           .grep_v(NOT_DOMAINS)
-           .uniq.sort
+        roots = Dir.glob(File.join(root, "**/*.hecksagon")).map { |path| folder.domain_root(File.dirname(path)) }
+        relative = roots.compact.map { |path| path.delete_prefix("#{root}/") }
+        relative.grep_v(NOT_DOMAINS).uniq.sort
       end
 
-      # Projects one manifest for each chapter the directory holds.
+      # Projects one manifest for each bluebook the directory holds.
       #
       # @param root [String] the checkout
       # @param path [String] a domain directory, relative to `root`
@@ -55,20 +52,20 @@ module Hecks
         registry = Hecks.boot(File.join(root, path), install_driving: false).registry
         return warn("  #{path}: no bluebook found — skipped") if registry.bluebooks.empty?
 
-        project_chapters(registry, root, path)
+        project_bluebooks(registry, root, path)
       rescue StandardError => e
-        warn "  #{path}: cannot project — #{e.message.lines.first.strip}"
+        warn "  #{path}: cannot project — #{Hecks::Text.first_line(e.message)}"
       end
 
-      # The chapters a directory declares: those with a `.bluebook` file under it. A chapter it
+      # The bluebooks a directory declares: those with a `.bluebook` file under it. A bluebook it
       # only attaches (Governance, for one) is loaded from elsewhere and has its own directory's
       # manifest.
       #
       # @param registry [Hecks::Runtime::Registry] the booted registry of the directory
       # @param directory [String] the directory that was booted
-      # @return [Array<String>] the chapter names, in load order; the first loaded when none has a
+      # @return [Array<String>] the bluebook names, in load order; the first loaded when none has a
       #   recorded source
-      def chapters_of(registry, directory)
+      def bluebooks_of(registry, directory)
         under = "#{File.expand_path(directory)}/"
         own = registry.bluebooks.keys.select do |name|
           Array(registry.bluebook_sources[name]).any? { |source| File.expand_path(source).start_with?(under) }
@@ -80,8 +77,8 @@ module Hecks
       # @param root [String] the checkout
       # @param path [String] the domain directory, relative to `root`
       # @return [void]
-      def project_chapters(registry, root, path)
-        names = chapters_of(registry, File.join(root, path))
+      def project_bluebooks(registry, root, path)
+        names = bluebooks_of(registry, File.join(root, path))
         names.each do |name|
           file = file_for(names, name)
           write_manifest(registry, name, File.join(root, path, file))
@@ -89,12 +86,12 @@ module Hecks
         end
       end
 
-      # A domain of one chapter keeps `oidc.json`; a directory of several chapters, such as the
+      # A domain of one bluebook keeps `oidc.json`; a directory of several bluebooks, such as the
       # framework members, gets one manifest each, so none of them stands for the others.
       #
-      # @param names [Array<String>] every chapter the directory holds
-      # @param name [String] the chapter the manifest is for
-      # @return [String] the manifest's file name: `oidc.json`, or `<chapter>.oidc.json`
+      # @param names [Array<String>] every bluebook the directory holds
+      # @param name [String] the bluebook the manifest is for
+      # @return [String] the manifest's file name: `oidc.json`, or `<bluebook>.oidc.json`
       def file_for(names, name) = names.one? ? "oidc.json" : "#{Naming.snake(name)}.oidc.json"
 
       # @param registry [Hecks::Runtime::Registry] the booted registry