hecks 3.2.1 → 3.4.0

data/lib/hecks/embryonaut_bluebook/registry.rb

@@ -0,0 +1,209 @@
+require "open3"
+require "tmpdir"
+require "fileutils"
+require_relative "../vendoring"
+require_relative "lock"
+
+module Hecks
+  module EmbryonautBluebook
+    # A bluebook registry repository, judged and released: packages at `<name>/bluebook.yml`, each
+    # with `<name>/bluebook/*.bluebook` and a `<name>/CHANGELOG.md`, released as the annotated tag
+    # `<name>-vX.Y.Z`.
+    #
+    # `check` is the rule that a package's bluebook files may not change without a version bump and
+    # a changelog entry; `release` is the sequence of refusals before a tag is made. A package's
+    # files are compared through `Lock.digest_of`, the digest a consuming project locks.
+    class Registry
+      # A version a package may carry, `X.Y.Z`.
+      VERSION = /\A\d+\.\d+\.\d+\z/
+
+      # A package name is a directory name.
+      NAME = /\A[a-z][a-z0-9_]*\z/
+
+      # What `check` found, in package order: a note for a package that has no release yet and a
+      # sentence for each fault.
+      class Report
+        # @return [Array<String>] each fault as `<package>: <why>`
+        attr_reader :failures
+
+        def initialize
+          @lines = []
+          @failures = []
+        end
+
+        # @param text [String] a fact about a package that is no fault
+        # @return [void]
+        def note(text) = @lines << "note #{text}"
+
+        # @param text [String] a fault, as `<package>: <why>`
+        # @return [void]
+        def fault(text)
+          @failures << text
+          @lines << "FAIL #{text}"
+        end
+
+        # @return [Boolean] whether no package is at fault
+        def ok? = @failures.empty?
+
+        # @return [String] the notes and faults in package order, then `versions ok` if none
+        def to_s = (@lines + (ok? ? ["versions ok"] : [])).join("\n")
+      end
+
+      # What a release made.
+      Tagged = Struct.new(:tag, :commit, keyword_init: true) do
+        # @return [String] the report, ending in the command that publishes the tag
+        def to_s = "Tagged #{tag} at #{commit}. Publish it with:\n  git push origin #{tag}"
+      end
+
+      # @param root [String] the registry's working tree
+      # @raise [Vendoring::Error] if `root` is not a git repository
+      def initialize(root)
+        @root = File.expand_path(root.to_s)
+        @source = Vendoring::GitSource.new(@root)
+        raise Vendoring::Error, "#{@root} is not a git repository" unless git("rev-parse", "--git-dir").last.success?
+      end
+
+      # Judges every package against its latest release.
+      #
+      # A package fails when its `bluebook.yml` has no `X.Y.Z` version or names another package,
+      # when a release tag points at a commit whose `bluebook.yml` says another version, or when
+      # its bluebook files differ from the latest release's without a newer version and a
+      # `CHANGELOG.md` entry for it.
+      #
+      # @return [Report] what was found
+      def check
+        report = Report.new
+        packages.each { |package| check_package(package, report) }
+        report
+      end
+
+      # Tags a package's current version, after the refusals that stand between a version and a
+      # release: the tag exists, the version is not newer, the changelog has no entry, the package
+      # has uncommitted changes, or its bluebook files are those of the latest release. Nothing is
+      # pushed.
+      #
+      # @param package [String] the package name
+      # @return [Tagged] the tag made and the commit it stands on
+      # @raise [Vendoring::Error] with the first refusal
+      def release(package)
+        fault!("#{package.inspect} is not a package name") unless package.to_s.match?(NAME)
+        version = manifest_version(package) or fault!("no #{package}/bluebook.yml")
+        fault!("#{package}/bluebook.yml: version '#{version}' is not X.Y.Z") unless version.match?(VERSION)
+
+        tag = "#{package}-v#{version}"
+        refuse_release!(package, version, tag)
+        notes = changelog_section(package, version)
+        _, _, status = git("tag", "-a", tag, "-m", "#{package} #{version}", "-m", notes)
+        raise Vendoring::Error, "git could not tag #{tag}" unless status.success?
+
+        Tagged.new(tag: tag, commit: git("rev-parse", "--short", "HEAD").first.strip)
+      end
+
+      private
+
+      def packages
+        Dir.glob(File.join(@root, "*", "bluebook.yml")).map { |file| File.basename(File.dirname(file)) }.sort
+      end
+
+      def check_package(package, report)
+        version = manifest_version(package).to_s
+        unless version.match?(VERSION)
+          report.fault "#{package}: version '#{version}' is not X.Y.Z"
+          return
+        end
+        name = File.read(File.join(@root, package, "bluebook.yml"))[/^name: *(.*)$/, 1]
+        report.fault "#{package}: bluebook.yml name does not match the directory" unless name == package
+        tags(package).each { |tag| check_tag(package, tag, report) }
+        latest = latest_version(package)
+        return report.note("#{package}: no release tag yet (#{version} unreleased)") unless latest
+
+        check_changes(package, version, latest, report)
+      end
+
+      def check_tag(package, tag, report)
+        tagged = @source.read(tag, "#{package}/bluebook.yml").to_s[/^version: *(.*)$/, 1].to_s
+        return if tagged == tag.delete_prefix("#{package}-v")
+
+        report.fault "#{package}: #{tag} points at a commit whose bluebook.yml says '#{tagged}'"
+      end
+
+      def check_changes(package, version, latest, report)
+        return if released_digest(package, latest) == current_digest(package)
+
+        if version == latest || newest(latest, version) != version
+          report.fault "#{package}: bluebook files changed since #{package}-v#{latest} but " \
+                       "bluebook.yml is still #{version}; bump it"
+        end
+        return if changelog_entry?(package, version)
+
+        report.fault "#{package}: CHANGELOG.md has no '## #{version}' entry"
+      end
+
+      def refuse_release!(package, version, tag)
+        fault!("#{tag} already exists") if git("rev-parse", "-q", "--verify", "refs/tags/#{tag}").last.success?
+
+        latest = latest_version(package)
+        fault!("#{version} is not newer than the latest release #{latest}") if latest && newest(latest, version) != version
+        fault!("#{package}/CHANGELOG.md has no '## #{version}' entry") unless changelog_entry?(package, version)
+        fault!("#{package} has uncommitted changes; commit them first") unless clean?(package)
+        return unless latest && released_digest(package, latest) == current_digest(package)
+
+        fault!("the bluebook files are identical to #{package}-v#{latest}; nothing to release")
+      end
+
+      def fault!(why) = raise(Vendoring::Error, why)
+
+      def clean?(package) = git("status", "--porcelain", "--", package).first.strip.empty?
+
+      def manifest_version(package)
+        file = File.join(@root, package, "bluebook.yml")
+        File.file?(file) ? File.read(file)[/^version: *(.*)$/, 1] : nil
+      end
+
+      def tags(package) = @source.tags("#{package}-v*")
+
+      def latest_version(package)
+        tags(package).map { |tag| tag.delete_prefix("#{package}-v") }.max_by { |version| order(version) }
+      end
+
+      # The greater of two versions, compared as `sort -V` does: runs of digits as numbers.
+      def newest(left, right) = [left, right].max_by { |version| order(version) }
+
+      def order(version) = version.scan(/\d+|\D+/).map { |part| part.match?(/\A\d/) ? [0, part.to_i, ""] : [1, 0, part] }
+
+      def changelog_entry?(package, version)
+        file = File.join(@root, package, "CHANGELOG.md")
+        File.file?(file) && File.read(file).match?(/^## #{Regexp.escape(version)}( |$)/)
+      end
+
+      # The lines under a version's heading, up to the next heading, without trailing blank lines.
+      def changelog_section(package, version)
+        on = false
+        lines = File.readlines(File.join(@root, package, "CHANGELOG.md"), chomp: true).select do |line|
+          on = line.match?(/^## #{Regexp.escape(version)}( |$)/) if line.start_with?("## ")
+          on && !line.start_with?("## ")
+        end
+        lines.join("\n").sub(/\n+\z/, "")
+      end
+
+      def current_digest(package)
+        dir = File.join(@root, package, "bluebook")
+        File.directory?(dir) ? Lock.digest_of(dir) : nil
+      end
+
+      # The digest of a package's bluebook files as a release tag holds them.
+      def released_digest(package, version)
+        tag = "#{package}-v#{version}"
+        files = @source.files(tag, "#{package}/bluebook", "*.bluebook")
+        return nil if files.empty?
+
+        Dir.mktmpdir("hecks-registry") do |scratch|
+          @source.export(tag, files, scratch)
+          Lock.digest_of(File.join(scratch, package, "bluebook"))
+        end
+      end
+
+      def git(*) = Open3.capture3(Vendoring::GitEnvironment.clean, "git", "-C", @root, *)
+    end
+  end
+end

data/lib/hecks/embryonaut_bluebook/vendor.rb

@@ -125,7 +125,7 @@ module Hecks
         return if @allow_downgrade || Gem::Version.new(version) >= Gem::Version.new(previous_version)
 
         raise Vendoring::Error, "#{@name} #{previous_version} is vendored; #{version} is older. " \
-                                "Pass allow_downgrade to do it anyway."
+                                "Pass allow_downgrade (ALLOW_DOWNGRADE=1 on the command line) to do it anyway."
       end
 
       def minor_or_more?(old, new)

data/lib/hecks/embryonaut_bluebook.rb

@@ -3,6 +3,8 @@ module Hecks
   # package that ships outside hecks's own lib/ (see .load! and .vendor!).
   module EmbryonautBluebook
     autoload :Lock, File.join(__dir__, "embryonaut_bluebook/lock")
+    autoload :Manifest, File.join(__dir__, "embryonaut_bluebook/manifest")
+    autoload :Registry, File.join(__dir__, "embryonaut_bluebook/registry")
     autoload :Shape, File.join(__dir__, "embryonaut_bluebook/shape")
     autoload :Vendor, File.join(__dir__, "embryonaut_bluebook/vendor")
     autoload :VendorCli, File.join(__dir__, "embryonaut_bluebook/vendor_cli")

data/lib/hecks/fuzzing/isolated_boot.rb

@@ -12,9 +12,6 @@ module Hecks
       # A vendored package named by `attaches "name", from: :vendor`.
       VENDORED_ATTACHED = /attaches\s*\(?\s*"([\w-]+)"\s*\)?\s*,\s*from:\s*:vendor/
 
-      # A vendored package named by the deprecated `uses_embryonaut_bluebook "name"`.
-      VENDORED_DEPRECATED = /uses_embryonaut_bluebook\s*\(?\s*"([\w-]+)"/
-
       module_function
 
       # Copies `domain_path` to a tmpdir, rebinds its persistence to `adapter`, and
@@ -74,7 +71,7 @@ module Hecks
       def carry_vendored_bluebooks!(source, destination)
         names = Dir.glob(File.join(destination, "**", "*.hecksagon")).flat_map do |path|
           text = File.read(path)
-          (text.scan(VENDORED_DEPRECATED) + text.scan(VENDORED_ATTACHED)).flatten
+          text.scan(VENDORED_ATTACHED).flatten
         end
         names.uniq.each do |name|
           package = File.join(File.dirname(source), "vendor", "embryonaut_bluebooks", name)

data/lib/hecks/fuzzing/qa_settings.rb

@@ -1,44 +1,26 @@
 require "yaml"
+require "hecks/vocabulary"
 
 module Hecks
   module Fuzzing
     # Loads and validates `qa/settings.yml`, the hecks_qa dials.
     #
     # Fails loud: a missing key, unknown key or wrong-typed value raises at load time.
-    # The meaning of each dial is documented on `QualityControlDials` in the bluebook.
+    # What each dial is and takes is declared as a `QaDial` row in the Vocabulary chapter.
     class QaSettings
-      # Accessor name to the class (or classes) a valid value must be an instance of.
-      # Booleans list both TrueClass and FalseClass; Numeric admits `0` as well as `0.0`.
-      EXPECTED_TYPES = {
-        cadence_seconds:              Integer,
-        pr_cap_per_day:               Integer,
-        widening_tiers:               Array,
-        sweep_max_parallel:           Integer,
-        liveness_fallback_seconds:    Integer,
-        draft_only:                   [TrueClass, FalseClass],
-        auto_merge:                   [TrueClass, FalseClass],
-        branch_prefix:                String,
-        adversarial_fraction:         Numeric,
-        guided_generation:            [TrueClass, FalseClass],
-        corpus_splice_probability:    Numeric,
-        favor_rare_verbs:             Integer,
-        self_consistency_checks:      [TrueClass, FalseClass],
-        shrink_budget:                Integer,
-        yield_weight_seconds:         Integer,
-        yield_decay_percent:          Integer,
-        rotation_stale_floor_seconds: Integer,
-        persistence_parity_seed_cap:  Integer,
-        concurrency_seed_cap:         Integer,
-        adapter_parity_pairs:         Hash,
-        modes:                        Hash,
-        role_draw_probability:        Numeric,
-        dry_run_fraction:             Numeric,
-        generated_domains_per_tick:   Integer,
-        generated_domains_rust:       [TrueClass, FalseClass],
-        generated_domain_seeds:       Integer,
-        structural_refusal_boundary:  Array
+      # The classes a value of each `type` of a `QaDial` row must be an instance of. Booleans list
+      # both TrueClass and FalseClass; Numeric admits `0` as well as `0.0`.
+      TYPE_CLASSES = {
+        "Integer" => [Integer], "Numeric" => [Numeric], "Boolean" => [TrueClass, FalseClass],
+        "String" => [String], "Array" => [Array], "Hash" => [Hash]
       }.freeze
 
+      # Accessor name to the classes a valid value must be an instance of, one entry per `QaDial`
+      # row of the Vocabulary chapter, where each dial is declared with its type and its meaning.
+      EXPECTED_TYPES = Hecks::Vocabulary.rows("QaDial").to_h do |dial|
+        [dial.fetch("name").to_sym, TYPE_CLASSES.fetch(dial.fetch("type"))]
+      end.freeze
+
       attr_reader(*EXPECTED_TYPES.keys)
 
       # The one real file, resolved from this file's `__dir__` rather than the bluebook's: the
@@ -68,8 +50,7 @@ module Hecks
         end
       end
 
-      # @param raw [Hash] parsed YAML settings keyed by symbol, one entry per dial in
-      #   `EXPECTED_TYPES`
+      # @param raw [Hash] parsed YAML settings keyed by symbol, one entry per `QaDial` row
       # @param path [String] path to the settings file, used only in error messages
       # @raise [ArgumentError] if `raw` is missing a required key, declares an unknown
       #   key, or gives a value the wrong type for its dial
@@ -81,7 +62,7 @@ module Hecks
         if extra.any?
           raise ArgumentError,
                 "#{path} declares unknown key(s) #{extra.sort.join(', ')} — " \
-                "Hecks::Fuzzing::QaSettings::EXPECTED_TYPES doesn't recognise them"
+                "no QaDial row of the Vocabulary chapter declares them"
         end
 
         EXPECTED_TYPES.each do |key, expected|

data/lib/hecks/fuzzing/target_capabilities.rb

@@ -16,7 +16,7 @@ module Hecks
       POSTGRES_ERA_VARIABLE = /^\s*([a-z_]\w*)\s*=\s*"PostgresEra"\s*(?:#.*)?$/
 
       # Captures the member a hecksagon attaches; authorization is read off its declaration.
-      FRAMEWORK_ATTACHED = /(?:attaches|uses_framework)\s*\(?\s*"([^"]+)"/
+      FRAMEWORK_ATTACHED = /attaches\s*\(?\s*"([^"]+)"/
 
       # A command-level `role "..."`, the only construct a role check can compare a caller against.
       ROLE_GATED = /^\s*role\s+"/

data/lib/hecks/gate/stages.yml

@@ -9,6 +9,16 @@
 #
 # `env` is set only where the caller has not set it: a push check has no use for the Hecks
 # domain's database, so it runs on Memory, as a pull-request run does in CI.
+#
+# A check a second stage repeats is written once, under an anchor (`&name`), and aliased
+# (`*name`) where the other stage takes it, so the two stages cannot drift apart.
+#
+# The `ci` stage is the checks the CI workflow `ci-checks.yml` holds. Each of its steps runs one
+# job's checks with `hecks gate_run.gate stage=ci only=<ids> --wait`, so the commands live here and
+# the workflow keeps only which job runs which ids and what each step is called;
+# spec/gate_ci_stage_spec.rb pins that every check is run by exactly one step. Select checks
+# with `only=`: several of them write generated files and compare, so the stage is not meant to
+# run whole in one checkout.
 pre_push:
   env:
     HECKS_ENVIRONMENT: memory
@@ -17,7 +27,8 @@ pre_push:
       title: rspec (parallel)
       run: [bundle, exec, parallel_rspec, spec, -n, "{workers}"]
       blocked: the suite is red.
-    - id: fuzzing
+    - &check_fuzzing
+      id: fuzzing
       title: spec/fuzzing, which the parallel run above excludes
       run: [bundle, exec, rspec, spec/fuzzing, --tag, fuzzing]
       blocked: spec/fuzzing is red.
@@ -25,31 +36,125 @@ pre_push:
       title: adapter agreement, one declared query and every engine giving the same answer
       run: [bundle, exec, rspec, spec/adapters/query_agreement_spec.rb, --tag, io]
       blocked: the engines disagree about a declared query; one of them is wrong, and a self-consistent adapter spec cannot tell which.
-    - id: engine_agreement
+    - &check_engine_agreement
+      id: engine_agreement
       title: engine agreement, every declared comparator on both engines
       run: [bundle, exec, exe/hecks, conformance_run.check_engine_agreement, --wait]
       blocked: a comparator is missing a shared case or a cross-engine spec.
-    - id: model_check
+    - &check_model_check
+      id: model_check
       title: model check, unreachable states, dead transitions and orphaned handlers
       run: [bundle, exec, exe/hecks, model_check, --wait]
       blocked: the model checker found something.
-    - id: doc_coverage
+    - &check_doc_coverage
+      id: doc_coverage
       title: docs coverage, words with no running example
       run: [bundle, exec, exe/hecks, conformance_run.measure_doc_coverage, --wait]
       blocked: the language ships something undocumented; write the missing sections and examples.
-    - id: rubocop
+    - &check_rubocop
+      id: rubocop
       title: rubocop, the static style and correctness gate
       run: [bundle, exec, rubocop, -c, .rubocop.yml]
       blocked: rubocop found an offense.
-    - id: codegen_drift
+    - &check_codegen_drift
+      id: codegen_drift
       title: codegen drift, the committed rust/src/generated/ must match a fresh regeneration
       run: [bundle, exec, exe/hecks, regeneration_run.regenerate_corpus, --check, --wait]
       blocked: regenerating hits a diff, so the committed Rust is stale; run `hecks regenerate_corpus --confirm` and commit the result.
-    - id: comment_style
+    - &check_comment_style
+      id: comment_style
       title: comment style, every comment under lib/hecks against docs/COMMENT_STYLE_GUIDE.md
       run: [bundle, exec, exe/hecks, style_run.check_comments, paths=lib/hecks, --wait]
       blocked: a comment breaks the style guide, such as a line past 100 characters; `hecks fix_comments` rewrites the mechanical ones, and the rest are shortened by hand. CI runs this same check.
-    - id: comment_blocks
+    - &check_comment_blocks
+      id: comment_blocks
       title: comment blocks, no run of comment lines past ADR 0075's cap
       run: [bundle, exec, exe/hecks, style_run.check_comments, "paths=lib,spec,examples", only=long_block, --wait]
       blocked: a comment block ran past the cap; shorten it.
+
+# The checks `.githooks/post-commit` runs after each commit. A red one is reported and never
+# blocks the commit; pre_push runs it again as the backstop.
+post_commit:
+  env:
+    HECKS_ENVIRONMENT: memory
+  checks:
+    - *check_fuzzing
+
+# The checks `.github/workflows/ci-checks.yml` runs. It sets no `env`: the job's journal choice
+# (the `hecks-environment` action) reaches every check, as it reached each command before.
+ci:
+  checks:
+    - *check_model_check
+    - *check_engine_agreement
+    - *check_doc_coverage
+    - *check_rubocop
+    - *check_comment_style
+    - *check_comment_blocks
+    - *check_codegen_drift
+    - id: lint_deploy_recipes
+      title: generated deploy recipes, a command with no checked exit status or no echo
+      run: [bundle, exec, exe/hecks, deploy, makefile_check.lint, --wait]
+      blocked: a generated deploy Makefile has an unchecked command, or real AWS or database work with no echo telling the person running it what is about to happen.
+    - id: fuzz
+      title: fuzz, every example domain on the Memory adapter
+      run: [bundle, exec, exe/hecks, fuzz_run.fuzz, --wait]
+      blocked: a property, an interpreter crash or a determinism check failed on a replayed sequence; the seed is in the output.
+    - id: fuzz_sqlite
+      title: fuzz on a real on-disk SQLite database
+      run: [bundle, exec, exe/hecks, fuzz_run.fuzz, adapter=sqlite, seeds=6, --wait]
+      blocked: the SQLite adapter broke a property the Memory adapter held; seeds are 1..N, so the run repeats.
+    - id: fuzz_postgres
+      title: fuzz on real Postgres, one worker (every ephemeral boot recreates the same scratch schema)
+      run: [bundle, exec, exe/hecks, fuzz_run.fuzz, adapter=postgres, seeds=3, steps=20, --wait]
+      blocked: the Postgres adapter broke a property the Memory adapter held; it needs PGHOST, PGUSER and PGPASSWORD.
+    - id: vocabulary_drift
+      title: vocabulary, the reserved-name tables regenerated must match the committed ones
+      run:
+        - sh
+        - -ec
+        - |
+          bundle exec exe/hecks language_run.project_vocabulary --confirm --wait
+          bundle exec exe/hecks language_run.project_reserved_names --confirm --wait
+          git diff --exit-code -- lib/hecks/vocabulary.rb rust/codegen/src/reserved_names.rs rust/build/src/reserved_names.rs
+      blocked: a generated vocabulary file is stale; the check rewrote it, so commit the result.
+    - id: ci_gates
+      title: ci gates, the CiGate rows must match the marked regions of the workflows
+      run: [bundle, exec, exe/hecks, regeneration_run.project_ci_gates, --wait]
+      blocked: a CiGate row changed with no projection, or a region was edited by hand; run `hecks regeneration_run.project_ci_gates --confirm`.
+    - id: tools_doc
+      title: tools doc, docs/tools.md must match the RetiredScript rows
+      run: [bundle, exec, exe/hecks, regeneration_run.project_tools_doc, --wait]
+      blocked: a command's arguments changed with no regenerated doc; run `hecks regeneration_run.project_tools_doc --confirm`.
+    - id: rust_coverage
+      title: rust coverage, every generated module
+      run: [bundle, exec, exe/hecks, query, corpus_run.corpus_rust_coverage, --wait]
+      blocked: a construct a domain declares has no generated Rust, or an entry on RUST_COVERAGE_PENDING is now fixed and must be deleted.
+    - id: rust_coverage_codegen
+      title: rust coverage against hecks-codegen's own manifest, pizzas governance identity banking meta
+      run:
+        - sh
+        - -ec
+        - |
+          for module in pizzas governance identity banking meta; do
+            bundle exec exe/hecks query build.rust_coverage module_name=$module codegen=rust --wait
+          done
+      blocked: hecks-codegen generated nothing for a construct a domain declares.
+    - id: kernel_coverage
+      title: rust kernel coverage, every capability variant has a kernel file
+      run: [bundle, exec, exe/hecks, kernel_run.measure_kernel_coverage, --wait]
+      blocked: a capability's enum variant has no rust/src/kernel file behind it.
+    - id: rust_vocabulary_drift
+      title: rust vocabulary, the kernel vocab tables regenerated must match the committed ones
+      run:
+        - sh
+        - -ec
+        - |
+          bundle exec exe/hecks language_run.project_rust_vocabulary --confirm --wait
+          git diff --exit-code -- rust/src/kernel/vocab/
+          untracked="$(git status --porcelain --untracked-files=all -- rust/src/kernel/vocab/)"
+          if [ -n "$untracked" ]; then
+            echo "rust/src/kernel/vocab has uncommitted generated files:" >&2
+            echo "$untracked" >&2
+            exit 1
+          fi
+      blocked: the generated kernel vocab tables are stale or untracked; the check rewrote them, so commit the result.

data/lib/hecks/hecks/adapters/codebase/regeneration.rb

@@ -16,7 +16,7 @@ module Hecks
       # files reports drift and writes only when it is confirmed.
       module Regeneration
         # Every operation this family carries out.
-        OPERATIONS = %w[regenerate_corpus project_ci_gates decide_ci_gate].freeze
+        OPERATIONS = %w[regenerate_corpus project_ci_gates project_tools_doc decide_ci_gate].freeze
 
         # How many lines of a script's output a refusal keeps.
         KEPT_LINES = 60
@@ -37,6 +37,7 @@ module Hecks
           check = flag.call(:check) || !flag.call(:confirm)
           child = RubyChild.new(tree)
           return project_ci_gates(child, check) if operation == "project_ci_gates"
+          return project_tools_doc(child, check) if operation == "project_tools_doc"
           return decide_ci_gate(child, held) if operation == "decide_ci_gate"
 
           result = child.capture("regen_codegen_domains", *("--check" if check))
@@ -53,6 +54,14 @@ module Hecks
           child.answer("project_ci_gates", *("--check" if check))
         end
 
+        # @param child [RubyChild] the checkout's tool runner
+        # @param check [Boolean] whether to only compare
+        # @return [String] what the tool printed
+        # @raise [ConsoleCapture::Failure] with the stale sections, when a check finds drift
+        def project_tools_doc(child, check)
+          child.answer("project_tools_doc", *("--check" if check))
+        end
+
         # @param child [RubyChild] the checkout's tool runner
         # @param held [Hash] the record's fields: `gate`, a `CiGate` row's name
         # @return [String] `touched=true` or `touched=false`

data/lib/hecks/hecks/adapters/first_admin.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require_relative "../../doors/json_door"
+
+module Hecks
+  module Adapters
+    # Gives a booted domain its first administrator through the chapter that provides
+    # `"membership"`, the way a project's hand-written bootstrap script does.
+    #
+    # The chapter names its own verbs (`provides "membership", admit:, grant:, people:`), so no
+    # aggregate is recognised by name. Both dispatches run as a caller that asserts the role the
+    # command is gated to and binds no `actor_id`: Governance checks an identified caller against
+    # its role assignments, which a domain with no administrator cannot have yet, and checks an
+    # unidentified one by comparing the role named (ADR 0025). That is the bootstrap step, and it is
+    # refused once anyone holds an administrator role, so it cannot add a second.
+    class FirstAdmin
+      # The roles that count as an administrator besides the one the grant command is gated to.
+      OWNER_ROLES = %w[Owner].freeze
+
+      # What a bootstrap did.
+      #
+      # @!attribute [r] email
+      #   @return [String] who was granted access
+      # @!attribute [r] role
+      #   @return [String] the role they now hold
+      # @!attribute [r] admitted
+      #   @return [Boolean] whether the person had to be admitted first
+      Result = Struct.new(:email, :role, :admitted, keyword_init: true) do
+        # @return [String] the sentence the verb answers with
+        def to_s = "Granted #{role} access to #{email}#{' (admitted first)' if admitted}"
+      end
+
+      # @param runtime [Hecks::Runtime] the booted domain
+      def initialize(runtime)
+        @runtime = runtime
+        @registry = runtime.registry
+      end
+
+      # Admits the person if they are not yet, then grants them a role.
+      #
+      # @param email [String] the person's email, the membership aggregate's identity
+      # @param name [String, nil] their name; the part of the email before the `@` when nil
+      # @param role [String, nil] the role to grant; the one the grant command is gated to when nil
+      # @return [Result] what was done
+      # @raise [Runtime::NotFound] when the domain has no membership chapter, the email is not an
+      #   email, or an administrator already exists
+      def call(email:, name: nil, role: nil)
+        raise Runtime::NotFound, "#{email.inspect} is not an email address" unless email.to_s.match?(/\A[^\s@]+@[^\s@]+\z/)
+
+        provider = membership_provider
+        verbs    = verbs_of(provider)
+        gate     = gated_role(provider, verbs.fetch(:grant))
+        people   = rows(verbs.fetch(:people))
+        refuse_if_administered!(people, [gate, *OWNER_ROLES].uniq)
+
+        admitted = people.none? { |person| person.dig(:email, :value) == email }
+        admit(provider, verbs.fetch(:admit), email, name || email[/\A[^@]+/]) if admitted
+        grant(provider, verbs.fetch(:grant), email, role || gate)
+        Result.new(email: email, role: role || gate, admitted: admitted)
+      end
+
+      private
+
+      def membership_provider
+        domain = @registry.bluebooks.values.first&.name
+        @registry.membership_provider_for(domain) or
+          raise Runtime::NotFound, "this domain attaches no chapter that provides \"membership\""
+      end
+
+      def verbs_of(provider)
+        %i[admit grant people].to_h { |key| [key, provider.provided_verb(Bluebook::Capabilities::MEMBERSHIP, key)] }
+      end
+
+      def rows(verb) = @runtime.query(verb).map { |row| Doors::JsonDoor.materialize(row) }
+
+      # The role a verb's command declares, which the dispatch must assert to be let through.
+      def gated_role(provider, verb)
+        aggregate, command = verb.split("::").last.split(".")
+        found = provider.aggregates.find { |candidate| candidate.hecks_name == aggregate }
+                        &.commands&.find { |candidate| candidate.hecks_name == command }
+        found&.role&.to_s or raise Runtime::NotFound, "#{verb} declares no role to bootstrap as"
+      end
+
+      def refuse_if_administered!(people, roles)
+        held = people.select { |person| roles.map(&:downcase).include?(person.dig(:role, :value).to_s.downcase) }
+        return if held.empty?
+
+        who = held.map { |person| person.dig(:email, :value) }.join(", ")
+        raise Runtime::NotFound, "an administrator already exists (#{who}); grant roles through the " \
+                                 "domain's own #{roles.first} access instead"
+      end
+
+      def admit(provider, verb, email, name)
+        as(provider, verb) do
+          @runtime.dispatch(verb, with: { email: { value: email }, name: { value: name } })
+        end
+      end
+
+      def grant(provider, verb, email, role)
+        as(provider, verb) { @runtime.dispatch(verb, to: email, with: { role: { value: role } }) }
+      end
+
+      def as(provider, verb, &)
+        Hecks.as_caller(role: gated_role(provider, verb), &)
+      end
+    end
+  end
+end