hecks 3.2.1 → 3.4.0

data/lib/hecks/cli/interview_session.rb

@@ -24,36 +24,59 @@ module Hecks
 
       TASK = "You interview a subject matter expert, through the developer who sits beside them, about the " \
              "business domain called %<subject>s, so the developer can model it. Ask one plain-language " \
-             "question at a time about what the business keeps track of, what happens to it, and what must " \
-             "never happen. Use the expert's own words. Do not assume what kind of business it is, or an " \
+             "question at a time about what the business keeps track of, what each thing has, what happens to " \
+             "it and who does it, how it moves from one state to the next, and what must never happen. Use the " \
+             "expert's own words. Do not assume what kind of business it is, or an " \
              "industry, from the name of the domain: learn it from what the expert says. When you interpret " \
              "an answer, propose findings only with the verbs listed under `verbs`, using the argument " \
              "names given there, and nothing else.".freeze
 
       VERBS = {
-        "SME::Interview.ProposeThing"  => {
+        "SME::Interview.ProposeThing"      => {
           "meaning"   => "a thing the business keeps track of, and the field that identifies one of it",
           "arguments" => %w[name identifier]
         },
-        "SME::Interview.ProposeAction" => {
-          "meaning"   => "something that happens to a thing, and the event it announces, in the past tense",
-          "arguments" => %w[name thing event creates]
+        "SME::Interview.ProposeAction"     => {
+          "meaning"   => "something that happens to a thing, and the event it announces, in the past tense; " \
+                         "creates is true for the action that brings the thing into being; takes lists, comma " \
+                         "separated, the fields it needs to be told; by says who does it",
+          "arguments" => %w[name thing event creates takes by]
         },
-        "SME::Interview.ProposeRule"   => {
+        "SME::Interview.ProposeField"      => {
+          "meaning"   => "something a thing has; values lists, comma separated, what it may be when the " \
+                         "expert gave a closed set, and is left out for free text",
+          "arguments" => %w[thing name values]
+        },
+        "SME::Interview.ProposeTransition" => {
+          "meaning"   => "the state an action leaves a thing in, and the state it had to be in before; the " \
+                         "action that creates the thing has no from",
+          "arguments" => %w[thing action to from]
+        },
+        "SME::Interview.ProposeRule"       => {
           "meaning"   => "a rule the expert stated, in their own words",
           "arguments" => %w[statement]
         }
       }.freeze
 
-      # What each finding verb needs, and the SME commands that carry it out and decide it.
+      # What each finding verb needs, the fields it may leave out, and the SME commands that
+      # carry it out and decide it.
       KINDS = {
-        "SME::Interview.ProposeThing"  => { kind: "thing", fields: %w[name identifier], propose: :propose_thing!,
-                                           entity: "ThingFinding", accept: "AcceptThing", reject: "RejectThing" },
-        "SME::Interview.ProposeAction" => { kind: "action", fields: %w[name thing event creates],
-                                            propose: :propose_action!, entity: "ActionFinding",
-                                            accept: "AcceptAction", reject: "RejectAction" },
-        "SME::Interview.ProposeRule"   => { kind: "rule", fields: %w[statement], propose: :propose_rule!,
-                                          entity: "RuleFinding", accept: "AcceptRule", reject: "RejectRule" }
+        "SME::Interview.ProposeThing"      => { kind: "thing", fields: %w[name identifier], optional: [],
+                                           propose: :propose_thing!, entity: "ThingFinding",
+                                           accept: "AcceptThing", reject: "RejectThing" },
+        "SME::Interview.ProposeAction"     => { kind: "action", fields: %w[name thing event creates takes by],
+                                            optional: %w[creates takes by], propose: :propose_action!,
+                                            entity: "ActionFinding", accept: "AcceptAction", reject: "RejectAction" },
+        "SME::Interview.ProposeRule"       => { kind: "rule", fields: %w[statement], optional: [],
+                                          propose: :propose_rule!, entity: "RuleFinding",
+                                          accept: "AcceptRule", reject: "RejectRule" },
+        "SME::Interview.ProposeField"      => { kind: "field", fields: %w[thing name values], optional: %w[values],
+                                          propose: :propose_field!, entity: "FieldFinding",
+                                          accept: "AcceptField", reject: "RejectField" },
+        "SME::Interview.ProposeTransition" => { kind: "transition", fields: %w[thing action to from],
+                                                optional: %w[from], propose: :propose_transition!,
+                                                entity: "TransitionFinding", accept: "AcceptTransition",
+                                                reject: "RejectTransition" }
       }.freeze
 
       TRUE_WORDS = %w[true yes y 1].freeze
@@ -153,7 +176,7 @@ module Hecks
         return say("Ignored a proposal for #{proposal.verb}: not a finding I know.") unless config
 
         fields = fields_of(proposal, config)
-        missing = config[:fields].reject { |f| f == "creates" || fields[f].to_s.strip != "" }
+        missing = config[:fields].reject { |f| config[:optional].include?(f) || fields[f].to_s.strip != "" }
         return say("Ignored a #{config[:kind]} proposal with no #{missing.join(', ')}.") unless missing.empty?
 
         number = propose(config, fields) or return
@@ -166,7 +189,7 @@ module Hecks
         rows = proposal.arguments.to_h { |row| [row[:name].to_s, row[:value]] }
         fields = rows.slice(*config[:fields])
         fields["creates"] = TRUE_WORDS.include?(fields["creates"].to_s.downcase) if fields.key?("creates")
-        fields
+        fields.reject { |key, value| key != "creates" && config[:optional].include?(key) && value.to_s.strip.empty? }
       end
 
       def propose(config, fields)
@@ -192,19 +215,27 @@ module Hecks
         case config[:kind]
         when "thing" then "thing: #{fields['name']}, identified by #{fields['identifier']}"
         when "action" then "action: #{fields['name']} on #{fields['thing']}, announcing #{fields['event']}" \
-                           "#{', creating it' if fields['creates']}"
+                           "#{', creating it' if fields['creates']}#{action_extras(fields)}"
+        when "field" then "field: #{fields['name']} of #{fields['thing']}#{", one of #{fields['values']}" if fields['values']}"
+        when "transition" then "transition: #{fields['action']} leaves #{fields['thing']} #{fields['to']}" \
+                               "#{", from #{fields['from']}" if fields['from']}"
         else "rule: #{fields['statement']}"
         end
       end
 
+      # @api private
+      def action_extras(fields)
+        "#{", taking #{fields['takes']}" if fields['takes']}#{", by #{fields['by']}" if fields['by']}"
+      end
+
       # The plain prompt: findings typed by the developer, accepted as they are entered.
       def manual_findings
         loop do
-          kind = ask("Add a finding from that answer? thing, action or rule (enter to skip): ")
+          kind = ask("Add a finding from that answer? thing, action, rule, field or transition (enter to skip): ")
           kind = kind.to_s.strip.downcase
           break if kind.empty?
 
-          typed = typed_finding(kind) or next say("  I only know thing, action and rule.")
+          typed = typed_finding(kind) or next say("  I only know thing, action, rule, field and transition.")
           config = KINDS["SME::Interview.Propose#{kind.capitalize}"]
           number = propose(config, typed) or next
           decide(config, number, true)
@@ -216,6 +247,11 @@ module Hecks
         when "thing" then named("Name" => "name", "Identified by" => "identifier")
         when "action" then typed_action
         when "rule" then named("The rule, in the expert's words" => "statement")
+        when "field" then named({ "On which thing" => "thing", "Name" => "name",
+                                  "Values it may take, comma separated (enter for any)" => "values" }, %w[values])
+        when "transition" then named({ "On which thing" => "thing", "Caused by which action" => "action",
+                                       "Leaves it in the state" => "to",
+                                       "From the state (enter if it starts there)" => "from" }, %w[from])
         end
       end
 
@@ -224,9 +260,11 @@ module Hecks
         fields.merge("creates" => TRUE_WORDS.include?(ask("  Does it create the thing? [y/N] ").to_s.strip.downcase))
       end
 
-      def named(prompts)
+      def named(prompts, optional = [])
         fields = prompts.to_h { |label, key| [key, ask("  #{label}: ").to_s.strip] }
-        fields.values.all? { |v| !v.empty? } ? fields : nil
+        return nil unless fields.all? { |key, value| optional.include?(key) || !value.empty? }
+
+        fields.reject { |key, value| optional.include?(key) && value.empty? }
       end
 
       def suggest_enough
@@ -271,9 +309,11 @@ module Hecks
       end
 
       def accepted_state(plain)
-        { things:  InterviewDraft.accepted(plain, :things).map { |f| f.slice(:name, :identifier) },
-          actions: InterviewDraft.accepted(plain, :actions).map { |f| f.slice(:name, :thing, :event, :creates) },
-          rules:   InterviewDraft.accepted(plain, :rules).map { |f| f.slice(:statement) } }
+        { things:      InterviewDraft.accepted(plain, :things).map { |f| f.slice(:name, :identifier) },
+          actions:     InterviewDraft.accepted(plain, :actions).map { |f| f.slice(:name, :thing, :event, :creates, :takes, :by) },
+          fields:      InterviewDraft.accepted(plain, :fields).map { |f| f.slice(:thing, :name, :values) },
+          transitions: InterviewDraft.accepted(plain, :transitions).map { |f| f.slice(:thing, :action, :to, :from) },
+          rules:       InterviewDraft.accepted(plain, :rules).map { |f| f.slice(:statement) } }
       end
 
       # What the interview has not yet pinned down, in words a model can act on.
@@ -283,7 +323,18 @@ module Hecks
         gaps = things.reject { |t| actions.any? { |a| a[:thing] == t } }.map { |t| "nothing is yet said to happen to #{t}" }
         gaps += things.reject { |t| actions.any? { |a| a[:thing] == t && a[:creates] } }.map { |t| "nothing yet creates #{t}" }
         unplaced = actions.reject { |a| things.include?(a[:thing].to_s) }
-        gaps + unplaced.map { |a| "#{a[:name]} names #{a[:thing]}, not yet a thing" }
+        gaps + unplaced.map { |a| "#{a[:name]} names #{a[:thing]}, not yet a thing" } + shape_gaps(plain, things, actions)
+      end
+
+      # What a thing is not yet said to have, and how it moves from one state to the next.
+      def shape_gaps(plain, things, actions)
+        fields = InterviewDraft.accepted(plain, :fields)
+        steps = InterviewDraft.accepted(plain, :transitions)
+        bare = things.reject { |t| fields.any? { |f| f[:thing] == t } }
+        gaps = bare.map { |t| "nothing is yet said #{t} has, beyond its identifier" }
+        changing = things.select { |t| actions.count { |a| a[:thing] == t && !a[:creates] } > 1 }
+        unmoved = changing.reject { |t| steps.any? { |s| s[:thing] == t } }
+        gaps + unmoved.map { |t| "nothing yet says how #{t} moves from one state to the next" }
       end
 
       def reason(error) = error.message.sub(/\A[A-Z]\w* refused\s+[—-]\s+/, "").strip

data/lib/hecks/cli/interview_shape.rb

@@ -0,0 +1,198 @@
+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
+
+      # One action for each name: an expert who refines an answer gets the same action accepted more
+      # than once, and a command can be declared only once. The first one's event and place in the
+      # interview stay; what each takes is joined, who does it is joined, and it creates if any did.
+      #
+      # @param actions [Array<Hash>] a thing's accepted actions
+      # @return [Array<Hash>] the actions, with each name once and in the order first accepted
+      def merged_actions(actions)
+        actions.group_by { |action| InterviewDraft.word(action[:name]) }.values.map do |group|
+          group.first.merge(creates: group.any? { |a| a[:creates] }, takes: joined(group, :takes, ", "),
+                            by: joined(group, :by, " or "))
+        end
+      end
+
+      # @api private
+      def joined(group, key, separator)
+        parts = group.flat_map { |a| a[key].to_s.split(separator == ", " ? /\s*,\s*/ : /\s+or\s+/) }
+        parts.map(&:strip).reject(&:empty?).uniq.join(separator)
+      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/corpus.rb

@@ -241,8 +241,7 @@ module Hecks
                               "of rust/src/generated, and there is no directory to fuzz")
     }.freeze
 
-    # Every place a Rust-facing domain's own `attaches` (or the deprecated `uses_framework` /
-    # `uses_embryonaut_bluebook`) attachment could be declared.
+    # Every place a Rust-facing domain's own `attaches` attachment could be declared.
     #
     # @param root [String] repository root to search under
     # @return [String] every reachable hecksagon file's own text, joined by newlines
@@ -310,11 +309,10 @@ module Hecks
 
     # The stamp hecks project_rust writes into metadata.rs, e.g.
     # `examples/pizzas` or `the self-hosted language (...)`, with any
-    # ` (attaches "X")`/` (attaches "x", from: :vendor)` suffix stripped (the deprecated
-    # `uses_framework` / `uses_embryonaut_bluebook` spellings too).
+    # ` (attaches "X")`/` (attaches "x", from: :vendor)` suffix stripped.
     SOURCE_STAMP = /
       GENERATED\ by\ hecks\ project_rust\ —\ (.+?)
-      (?:\ \((?:attaches|uses_framework|uses_embryonaut_bluebook)\ "\w+"(?:,\ from:\ :vendor)?\))?
+      (?:\ \(attaches\ "\w+"(?:,\ from:\ :vendor)?\))?
       's\ own\ canonical\ IR,
     /x
 

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

@@ -1,23 +1,6 @@
 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
-
-    module_function
-
-    # Resolves the boot switch from the current keyword and its deprecated spelling.
-    #
-    # @param install_doors [Boolean] the `install_doors:` keyword
-    # @param install_facade [Boolean, nil] the deprecated `install_facade:` keyword; nil when
-    #   the caller did not pass it
-    # @return [Boolean] whether to install the Ruby door constants
-    def install?(install_doors, install_facade = nil)
-      return install_doors if install_facade.nil?
-
-      warn "[hecks] `install_facade:` is deprecated and is removed in #{REMOVAL}; use `install_doors:`"
-      install_facade
-    end
   end
 
   # Installs facade constants at top level, replacing only what it installed itself.

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