hecks 3.2.1 → 3.3.0

data/lib/hecks/cli/interview_shape.rb

@@ -0,0 +1,179 @@
+require_relative "../naming"
+
+module Hecks
+  module CLI
+    # What an interview's fields, command inputs and state changes become in a drafted aggregate
+    # (ADR 0088): its attributes and their value objects, the fields a command is told, a note of
+    # who does it, and the lifecycle.
+    #
+    # Pure, like `InterviewDraft`, which calls it: each method answers lines of bluebook text and
+    # writes none. A name is written as `InterviewDraft.word` writes it.
+    module InterviewShape
+      module_function
+
+      # The accepted fields of one thing, each with the type it will be written under. The
+      # identifier is already a field, and a lifecycle owns `status`, so neither is repeated.
+      #
+      # @param found [Array<Hash>] the accepted field findings that name the thing
+      # @param name [String] the thing's name, which no type may repeat
+      # @param identifier [String] the identifying field, snake-cased
+      # @param identifier_type [String] the type the identifier is written under
+      # @param lifecycle [Boolean] whether the thing has a lifecycle
+      # @return [Array<Hash>] each field's `name`, `type` and `values`
+      def fields(found, name, identifier, identifier_type, lifecycle:)
+        taken = [name, identifier_type]
+        found.filter_map { |finding| field_row(finding, taken, identifier, lifecycle) }.uniq { |row| row[:name] }
+      end
+
+      # The attribute lines of the fields: required when the creating action takes one, else
+      # optional.
+      #
+      # @param fields [Array<Hash>] the thing's fields, from `fields`
+      # @param required [Array<String>] the field names the creating actions take
+      # @return [Array<String>] one line per field
+      def attributes(fields, required)
+        fields.map do |field|
+          suffix = required.include?(field[:name]) ? "" : ", optional: true"
+          "    attribute :#{field[:name]}, #{field[:type]}#{suffix}"
+        end
+      end
+
+      # The value object of each field, a blank line before each: a closed set when the expert
+      # listed two or more values, and free text otherwise.
+      #
+      # @param fields [Array<Hash>] the thing's fields, from `fields`
+      # @return [Array<String>] the lines
+      def value_objects(fields)
+        fields.flat_map do |field|
+          rule = field[:values].size > 1 ? ", one_of: #{field[:values].inspect}" : ""
+          ["", "    value_object #{field[:type].inspect} do", "      attribute :value, String#{rule}", "    end"]
+        end
+      end
+
+      # The field names an action says it is told.
+      #
+      # @param action [Hash] an accepted action
+      # @return [Array<String>] snake-cased field names
+      def takes(action)
+        action[:takes].to_s.split(/\s*,\s*/).map { |text| Naming.snake(InterviewDraft.word(text)) }.reject(&:empty?)
+      end
+
+      # What an action is told that the thing has as a field, and what it names that the thing
+      # does not. The identifier is never counted: a command already carries it.
+      #
+      # @param action [Hash] an accepted action
+      # @param fields [Array<Hash>] the thing's fields, from `fields`
+      # @param identifier [String] the identifying field, snake-cased
+      # @return [Array(Array<Hash>, Array<String>)] the fields it is told, and the names that have
+      #   no field
+      def inputs(action, fields, identifier)
+        known, unknown = (takes(action) - [identifier]).partition { |text| fields.any? { |field| field[:name] == text } }
+        [known.map { |text| fields.find { |field| field[:name] == text } }, unknown]
+      end
+
+      # @param inputs [Array<Hash>] the fields a command is told
+      # @return [Array<String>] a blank line and an attribute line for each, or none
+      def input_lines(inputs)
+        inputs.empty? ? [] : ["", *inputs.map { |f| "      attribute :#{f[:name]}, #{f[:type]}" }]
+      end
+
+      # @param inputs [Array<Hash>] the fields a command is told
+      # @return [Array<String>] a blank line and a `sets` line for each, or none
+      def assignment_lines(inputs)
+        inputs.empty? ? [] : ["", *inputs.map { |f| "      sets :#{f[:name]}" }]
+      end
+
+      # @param unknown [Array<String>] names an action is told that no accepted field has
+      # @return [Array<String>] a note for each
+      def unknown_lines(unknown)
+        unknown.map { |text| "      # TODO: takes #{text}, but no accepted field of that name." }
+      end
+
+      # Who may do an action, as the expert said it. It is a note, not a role: a role is only
+      # checked once the domain attaches Governance.
+      #
+      # @param action [Hash] an accepted action
+      # @return [Array<String>] the note, or none
+      def who_lines(action)
+        by = action[:by].to_s.strip
+        by.empty? ? [] : ["      # Who: #{by}. Declare it as a role once Governance is attached."]
+      end
+
+      # The lifecycle the accepted transitions describe. The state a creating action's step
+      # leads to is where a thing starts; a step for an action the thing does not have is kept
+      # as a comment.
+      #
+      # @param steps [Array<Hash>] the thing's accepted transitions
+      # @param creating [Array<Hash>] the accepted actions that create it
+      # @param rest [Array<Hash>] its other accepted actions
+      # @return [Array<String>] the lines, or none when no step and start state can be placed
+      def lifecycle(steps, creating, rest)
+        births = creating.map { |action| InterviewDraft.word(action[:name]) }
+        has = ->(names, step) { names.include?(InterviewDraft.word(step[:action])) }
+        starts, moves = steps.partition { |step| has.call(births, step) }
+        heres = rest.map { |action| InterviewDraft.word(action[:name]) }
+        placed, loose = moves.partition { |step| has.call(heres, step) }
+        placed = merged(placed)
+        start = beginning(starts, placed)
+        return [] if start.empty? || placed.empty?
+
+        ["", "    lifecycle :status, default: #{start.inspect} do", *placed.map { |step| transition_line(step) },
+         "    end", *loose.map { |step| loose_line(step) }]
+      end
+
+      # @api private
+      def field_row(finding, taken, identifier, lifecycle)
+        field = Naming.snake(InterviewDraft.word(finding[:name]))
+        return if field == identifier || (lifecycle && field == "status")
+
+        type = Naming.pascal(field)
+        type = "#{type}Value" while taken.include?(type)
+        taken << type
+        { name: field, type: type, values: finding[:values].to_s.split(/\s*,\s*|\s+or\s+/).map(&:strip).reject(&:empty?).uniq }
+      end
+
+      # One step for each action and state it leads to: the states it starts from are joined, and a
+      # step with no state to start from means it may be taken from any.
+      # @api private
+      def merged(steps)
+        steps.group_by { |step| [InterviewDraft.word(step[:action]), state_word(step[:to])] }.values.map do |group|
+          froms = group.map { |step| step[:from].to_s.strip }
+          group.first.merge(from: froms.any?(&:empty?) ? "" : froms.join(","))
+        end
+      end
+
+      # The state a thing starts in: where its creating action's step leads, else the first state a
+      # change is said to start from.
+      # @api private
+      def beginning(starts, placed)
+        from = placed.map { |step| step[:from].to_s.split(",").first }.find { |text| !text.to_s.strip.empty? }
+        state_word(starts.first&.fetch(:to) || from)
+      end
+
+      # @api private
+      def transition_line(step)
+        "      transition #{InterviewDraft.word(step[:action]).inspect} => #{state_word(step[:to]).inspect}" \
+          "#{from_clause(step)}"
+      end
+
+      # @api private
+      def loose_line(step)
+        "    # UNPLACED transition: #{InterviewDraft.word(step[:action])} to #{state_word(step[:to])}; " \
+          "no accepted action has that name."
+      end
+
+      # The states a step may start from: none, one, or several.
+      # @api private
+      def from_clause(step)
+        states = step[:from].to_s.split(/\s*,\s*/).map { |text| state_word(text) }.reject(&:empty?)
+        return "" if states.empty?
+
+        states.one? ? ", from: #{states.first.inspect}" : ", from: %w[#{states.join(' ')}]"
+      end
+
+      # A state as a lowercase word: `Not Yet Triaged` is `not_yet_triaged`.
+      # @api private
+      def state_word(text) = text.to_s.strip.downcase.gsub(/[^a-z0-9]+/, "_").gsub(/\A_|_\z/, "")
+    end
+  end
+end

data/lib/hecks/doors/cli_runner.rb

@@ -188,6 +188,7 @@ module Hecks
       # @param launcher [Hash, nil] the chapter's `launcher` world setting; nil when not opted in
       def dispatch(runtime, spec, name, rest, program, asking, bluebook: nil, launcher: nil)
         rest, wait = LauncherOptions.take_wait(spec, rest) if launcher
+        wait ||= LauncherOptions.settled?(launcher, spec)
         args = CliDoor.arguments(spec, rest)
 
         return answer_query(runtime, spec, args, wait) if spec[:kind] == :query
@@ -252,11 +253,23 @@ module Hecks
                       events: (events.empty? ? handle.events : events).map(&:name) }.merge(extra)
         if LauncherOptions.failed?(aggregate, state, launcher)
           field = aggregate.lifecycle.field
-          why  += ["#{aggregate.hecks_name} ended in the failure state #{state[field.to_sym].to_s.inspect}"]
+          why  += [failure_sentence(aggregate, state, field)]
         end
         finish(JSON.pretty_generate(answer), why)
       end
 
+      # The sentence for a record that ended in a failure state: the state, then the record's own
+      # `refusal` when it keeps one, without the class name an adapter's failure carries.
+      def failure_sentence(aggregate, state, field)
+        sentence = "#{aggregate.hecks_name} ended in the failure state #{state[field.to_sym].to_s.inspect}"
+        refusal  = state[:refusal]
+        refusal  = refusal.value if refusal.respond_to?(:value)
+        refusal  = refusal[:value] if refusal.is_a?(Hash)
+        return sentence if refusal.to_s.strip.empty?
+
+        "#{sentence}: #{refusal.to_s.strip.sub(/\A(\w+::)+\w+: /, '')}"
+      end
+
       # The answer and its status: 0 when nothing failed, else 1 with the reasons joined.
       def finish(text, reasons)
         reasons.empty? ? [text, 0] : [text, 1, reasons.join("\n")]

data/lib/hecks/doors/launcher_options.rb

@@ -10,11 +10,10 @@ module Hecks
     # A `.world` that declares a `launcher` setting switches these on for that chapter; a
     # domain without one keeps the launcher's plain forms exactly:
     #
-    #     launcher "Launcher", run_keys: true, failure_states: %w[flagged failed],
-    #                          names: { "mcp" => "serve_mcp" }
-    #
     # - **run_keys** mints the `run` key of a creating command that was given none.
     # - **failure_states** are the lifecycle states `--wait` reports as a failure (exit 1).
+    # - **settled** lists the commands (`aggregate.command`) that always behave as if `--wait` was
+    #   given, so a script gets their outcome in its exit status.
     # - **names** maps a launcher name to the command it stands for (see `CliProjector`).
     # - **streams** lists the questions `--stream` may tail, one JSON line per new entry.
     module LauncherOptions
@@ -87,6 +86,17 @@ module Hecks
         [rest, wait]
       end
 
+      # Whether a command always waits for its reactions, as if `--wait` had been given.
+      #
+      # @param launcher [Hash, nil] the chapter's `launcher` setting
+      # @param spec [Hash] the command's projected spec
+      # @return [Boolean] true for a command the setting lists under `settled`
+      def settled?(launcher, spec)
+        return false unless launcher && spec[:kind] == :command
+
+        Array(launcher[:settled]).map(&:to_s).include?(spec[:short].to_s)
+      end
+
       # Whether a question may be tailed with `--stream`: the chapter's `launcher` setting lists it
       # under `streams`, by the question's own name.
       #

data/lib/hecks/doors/mcp_door_scope.rb

@@ -28,7 +28,8 @@ module Hecks
       # switch to, or flips a command from a preview to a change of state.
       DENIED_ARGUMENTS = %w[
         adapter artifact confirm expected from gem_only header health_path host no_wait npm_local
-        npm_only output path payload payload_file port rust_binary scheme state_path stdio url write
+        npm_only output path payload payload_file port rust_binary scheme stage_dir state_path stdio url
+        write
       ].freeze
 
       # Argument names whose values are paths (a comma-separated list for some). A restricted door

data/lib/hecks/doors.rb

@@ -2,7 +2,7 @@ module Hecks
   # The class-free public surface, installed per boot by `Runtime::Loader.bind_runtime`.
   module Doors
     # The removal release of the `Facade` and `install_facade:` spellings.
-    REMOVAL = "3.2.0".freeze
+    REMOVAL = "3.4.0".freeze
 
     module_function
 

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")