hecks 3.2.0 → 3.3.0

data/lib/hecks/embryonaut_bluebook/manifest.rb

@@ -0,0 +1,117 @@
+require "json"
+require_relative "lock"
+
+module Hecks
+  module EmbryonautBluebook
+    # Checks a project's vendored packages against their `bluebook.lock` files and describes
+    # them as data: the manifest a client image carries to say which bluebooks it holds.
+    #
+    #     { "built_from" => { "commit" => "<project commit>", "dirty" => false },
+    #       "bluebooks"  => { "payments" => { "version" => "1.0.0", "tag" => "payments-v1.0.0",
+    #                                          "commit" => "<sha>", "digest" => "<sha256>",
+    #                                          "shape"  => ["Payments d33c23"] } } }
+    #
+    # There is no timestamp: the same inputs give the same manifest. The digest is `Lock.digest_of`,
+    # the one implementation `Vendor` also writes locks with.
+    class Manifest
+      # The lock fields every package must carry besides its shape.
+      FIELDS = %w[package version tag commit digest].freeze
+
+      # The fields a package's manifest entry repeats from its lock.
+      ENTRY = %w[version tag commit digest].freeze
+
+      # A refusal: every way the vendored packages disagree with their locks, one per line.
+      class Mismatch < StandardError
+        # @return [Array<String>] one sentence per disagreement
+        attr_reader :problems
+
+        # @param problems [Array<String>] the disagreements found
+        def initialize(problems)
+          @problems = problems
+          super(problems.map { |problem| "FAIL #{problem}" }.join("\n"))
+        end
+      end
+
+      # @param root [String] the project directory holding `vendor/embryonaut_bluebooks/`
+      # @param built_from [Hash{String => Object}, nil] the project's own commit and whether the
+      #   tree is dirty; left out of the manifest when nil
+      def initialize(root, built_from: nil)
+        @root = root
+        @built_from = built_from
+      end
+
+      # Checks every vendored package and describes them.
+      #
+      # @return [Hash{String => Object}] the manifest
+      # @raise [Mismatch] when any package disagrees with its lock
+      def call
+        problems = []
+        packages = names.to_h { |name| [name, entry(name, problems)] }.compact
+        raise Mismatch, problems unless problems.empty?
+
+        { "built_from" => @built_from, "bluebooks" => packages }.compact
+      end
+
+      # The manifest as the text a label or file holds: keys sorted, two-space indent.
+      #
+      # @return [String] JSON ending in a newline
+      def to_json_text
+        "#{JSON.pretty_generate(sort(call))}\n"
+      end
+
+      private
+
+      def vendor_dir = File.join(@root, "vendor", "embryonaut_bluebooks")
+
+      def names
+        return [] unless File.directory?(vendor_dir)
+
+        Dir.children(vendor_dir).sort.select { |name| File.directory?(File.join(vendor_dir, name)) }
+      end
+
+      # One package's manifest entry, or nil (its reasons added to `problems`) when it has no lock.
+      def entry(name, problems)
+        dir  = File.join(vendor_dir, name)
+        path = File.join(dir, "bluebook.lock")
+        unless File.exist?(path)
+          problems << "#{name}: no bluebook.lock (hecks package.vendor #{name}@<version>)"
+          return nil
+        end
+
+        lock = Lock.read(path)
+        judge(name, dir, lock, problems)
+        lock.to_h.transform_keys(&:to_s).slice(*ENTRY).merge("shape" => Array(lock.shape))
+      end
+
+      def judge(name, dir, lock, problems)
+        FIELDS.each { |field| problems << "#{name}: bluebook.lock has no #{field}" if blank?(lock[field.to_sym]) }
+        problems << "#{name}: bluebook.lock names package #{lock.package}" if lock.package && lock.package != name
+        problems << "#{name}: bluebook.lock has no shape" if Array(lock.shape).empty?
+        judge_release(name, lock, problems)
+        actual = Lock.digest_of(File.join(dir, "bluebook"))
+        return if actual == lock.digest
+
+        problems << "#{name}: vendored files hash to #{(actual || 'nothing')[0, 12]}, but bluebook.lock says " \
+                    "#{(lock.digest || '?')[0, 12]} (edited by hand, or re-vendored without its lock?)"
+      end
+
+      # The tag of a release is `<package>-v<version>`; a lock saying otherwise was edited.
+      def judge_release(name, lock, problems)
+        return if blank?(lock.tag) || blank?(lock.version)
+        return if lock.tag == "#{name}-v#{lock.version}"
+
+        problems << "#{name}: bluebook.lock tag #{lock.tag} is not #{name}-v#{lock.version}"
+      end
+
+      def blank?(value) = value.nil? || value.to_s.empty?
+
+      def sort(value)
+        case value
+        when Hash  then value.sort.to_h { |key, inner| [key, sort(inner)] }
+        when Array then value.map { |inner| sort(inner) }
+        else value
+        end
+      end
+    end
+  end
+end

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/properties/dispatch_and_mutations.rb

@@ -118,8 +118,9 @@ module Hecks
 
             owner = owner_for_verb(bluebooks, entry[:verb]) || aggregate
 
+            args = with_declared_defaults(command, entry[:args])
             command.mutations.select { |m| RECOMPUTABLE_MUTATION_OPS.include?(m.op) }.filter_map do |mutation|
-              expected = recompute_mutation(mutation, entry[:before][mutation.target], entry[:args], entry[:before],
+              expected = recompute_mutation(mutation, entry[:before][mutation.target], args, entry[:before],
                                             aggregate, command, owner)
               next if expected == :unrecomputable
 
@@ -134,6 +135,21 @@ module Hecks
           offenders.empty? || offenders.join("; ")
         end
 
+        # The arguments the command actually ran with: an argument the caller left out takes the
+        # default its attribute declares, as dispatch fills it, so the recomputation starts from
+        # the same facts.
+        #
+        # @param command [Object] the command the step dispatched
+        # @param args [Hash] the arguments the step offered
+        # @return [Hash] `args`, with each omitted defaulted argument filled
+        def with_declared_defaults(command, args)
+          command.attributes.each_with_object(args.dup) do |attribute, held|
+            next if attribute.default.nil? || held.key?(attribute.name.to_sym) || held.key?(attribute.name.to_s)
+
+            held[attribute.name.to_sym] = attribute.default
+          end
+        end
+
         # Root aggregate for `verb`, derived from the verb alone because hand-built
         # entries may lack `:domain`/`:aggregate`. Value-object types resolve against
         # the root's namespace only.

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/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`