hecks 3.2.0 → 3.3.0

data/lib/hecks/rust_build/project_rust/codegen_run.rb

@@ -3,7 +3,6 @@
 require "fileutils"
 require "json"
 require "tmpdir"
-require_relative "../rust_literal"
 require_relative "../write_if_changed"
 
 module Hecks
@@ -78,7 +77,6 @@ module Hecks
         def generate_meta(stage, tmp)
           ir_path = write_ir(tmp, "meta", @meta)
           run("full", stage, "meta", META_LABEL, ir_path)
-          write_sidecars(File.join(stage, "meta"), @meta, META_LABEL)
         end
 
         def generate_target(stage, tmp)
@@ -87,9 +85,6 @@ module Hecks
             args.push(chapter.mod_name, chapter.label, write_ir(tmp, chapter.mod_name, chapter.ir))
           end
           run("full", *args)
-          [@target, *@chapters].each do |chapter|
-            write_sidecars(File.join(stage, chapter.mod_name), chapter.ir, chapter.label)
-          end
         end
 
         def write_ir(tmp, name, tree)
@@ -98,19 +93,6 @@ module Hecks
           path
         end
 
-        # `ir.json` is what `rust/host` reads at runtime, and `metadata.rs` embeds the same text;
-        # the codegen binary writes neither.
-        def write_sidecars(mod_dir, tree, label)
-          text = JSON.pretty_generate(tree)
-          File.write(File.join(mod_dir, "ir.json"), text)
-          File.write(File.join(mod_dir, "metadata.rs"), <<~RUST)
-            // GENERATED by hecks project_rust — #{label}'s own canonical IR,
-            // embedded for runtime self-description. Not read by any dispatch
-            // function in this module — introspection only.
-            pub const IR_JSON: &str = #{RustLiteral.string(text)};
-          RUST
-        end
-
         def run(*args)
           return if system(self.class.binary(@rust_dir), *args, out: $stdout, err: $stderr)
 

data/lib/hecks/rust_build/project_rust.rb

@@ -5,7 +5,6 @@ require "json"
 require_relative "../../hecks"
 require_relative "../bluebook/meta_validator"
 require_relative "../ports/persistence/plugins/era"
-require_relative "append_optionals"
 require_relative "domain_name"
 require_relative "write_if_changed"
 
@@ -17,9 +16,8 @@ module Hecks
     #   ProjectRust.call(["path/to/domain"])
     #
     # `hecks-codegen` is the generator (ADR 0086): this class builds the IR from the live registry
-    # and `CodegenRun` runs the binary on it. `HECKS_CODEGEN=ruby` selects the Ruby generator in
-    # `rust/project` until that is deleted; `HECKS_PARSER=rust` with `HECKS_CODEGEN=rust` runs
-    # `rust/project_rust_pipeline.rb` instead, with no Ruby load of the domain.
+    # and `CodegenRun` runs the binary on it. The Ruby-free path is `hecks-build`, which feeds the
+    # same binary from `hecks-parse`.
     #
     # The era plugin is required unconditionally so the generator works for any domain, lineage
     # capable or not; `pg` stays lazy inside it, so nothing here opens a database connection.
@@ -46,13 +44,7 @@ module Hecks
       # @return [Integer] the exit status
       def call
         validate_name!
-        if ENV["HECKS_PARSER"] == "rust" && ENV["HECKS_CODEGEN"] == "rust"
-          require_relative "../../../rust/project"
-          require_relative "../../../rust/project_rust_pipeline"
-          RustProjectPipeline.call(@domain)
-        else
-          generate
-        end
+        generate
         0
       end
 
@@ -78,18 +70,11 @@ module Hecks
         FileUtils.mkdir_p(@out_root)
         build_target_ir
         FileUtils.rm_rf(File.join(@out_root, "active"))
-        ENV["HECKS_CODEGEN"] == "ruby" ? generate_with_ruby : generate_with_codegen
+        generate_with_codegen
         write_root_mod
         sync_cargo_features
       end
 
-      # The rollback path (ADR 0086): the Ruby generator in `rust/project`, until it is deleted.
-      def generate_with_ruby
-        require_relative "../../../rust/project"
-        write_meta
-        write_target
-      end
-
       # `hecks-codegen` is the generator; this process only builds the IR it reads from the live
       # registry, so a domain's persistence, seams, translations and source text reach `ir.json`.
       def generate_with_codegen
@@ -97,20 +82,14 @@ module Hecks
         vendored = @registry.hecksagons.values.flat_map(&:vendored_packages)
         chapters = (@registry.bluebooks.keys - [@domain_name]).map do |name|
           ir = Hecks::Projector::Exporter.call(@registry).fetch(name)
-          CodegenRun::Chapter.new(name.downcase, "#{@domain} (#{attachment(name, vendored)})", prepared_ir(ir))
+          CodegenRun::Chapter.new(name.downcase, "#{@domain} (#{attachment(name, vendored)})", json_shaped(ir))
         end
         CodegenRun.new(
-          rust_dir: @rust_dir, out_root: @out_root, meta: prepared_ir(meta), chapters: chapters,
-          target: CodegenRun::Chapter.new(@mod_name, @domain, prepared_ir(@ir, shaped: false))
+          rust_dir: @rust_dir, out_root: @out_root, meta: json_shaped(meta), chapters: chapters,
+          target: CodegenRun::Chapter.new(@mod_name, @domain, @ir)
         ).call
       end
 
-      # The IR as `rust/project` hands it to its generators: string-keyed through JSON, with the
-      # append-optional fields marked, since `ir.json` records them.
-      def prepared_ir(tree, shaped: true)
-        AppendOptionals.mark(shaped ? json_shaped(tree) : tree)
-      end
-
       # Round-trips a value through JSON so generators see the string-keyed shape a real `ir.json`
       # carries, never live Ruby symbols.
       def json_shaped(payload) = JSON.parse(JSON.generate(payload), symbolize_names: true)
@@ -186,78 +165,6 @@ module Hecks
         )
       end
 
-      # The self-hosted language goes through the same codegen as the target, read from the
-      # grammar registry `MetaValidator` boots with.
-      def write_meta
-        meta_ir = json_shaped(
-          Hecks::Projector::Exporter.call(Hecks::Bluebook::MetaValidator.grammar_registry).fetch("Bluebook")
-        )
-        dir = File.join(@out_root, "meta")
-        # Tracked per directory: several domains coexist on disk, and `pop_and_prune` deletes only
-        # the files this run never touched. `active` is a set of feature re-exports in the root
-        # `mod.rs`, never a directory.
-        WriteIfChanged.push_directory(dir)
-        result = RustProjection::DomainGenerator.call(
-          meta_ir, "the self-hosted language (lib/hecks/language/bluebook)", dir, "meta"
-        )
-        write_merged(File.join(dir, "merged.rs"), result[:aggregates], result[:queries], result[:read_models],
-                     policies: RustProjection::Projector.emit_policy_table(meta_ir[:name], meta_ir[:policies],
-                                                                           meta_ir[:aggregates]),
-                     cross:    RustProjection::Projector.emit_cross_domain_policy_table(meta_ir[:name],
-                                                                                        meta_ir[:policies]),
-                     managers: meta_ir[:process_managers],
-                     keys:     [[meta_ir[:name], result[:aggregates].map { |a| a[:name] }]])
-        append_merged_mod(File.join(dir, "mod.rs"))
-        WriteIfChanged.pop_and_prune(dir)
-      end
-
-      def write_target
-        dir = File.join(@out_root, @mod_name)
-        WriteIfChanged.push_directory(dir)
-        result = RustProjection::DomainGenerator.call(@ir, @domain, dir, @mod_name)
-        chapters = write_chapters
-        aggregates = result[:aggregates] + chapters[:aggregates]
-        write_merged(File.join(dir, "merged.rs"), aggregates, result[:queries] + chapters[:queries],
-                     result[:read_models] + chapters[:read_models],
-                     policies: RustProjection::Projector.emit_merged_policy_table(chapters[:policy_sources]),
-                     cross:    RustProjection::Projector.emit_merged_cross_domain_policy_table(chapters[:policy_sources]),
-                     managers: @ir[:process_managers] + chapters[:process_managers],
-                     keys:     reference_keys(result[:aggregates], chapters))
-        append_merged_mod(File.join(dir, "mod.rs"))
-        WriteIfChanged.pop_and_prune(dir)
-      end
-
-      # Every other bluebook the target's `attaches` calls pulled into the registry, each
-      # generated into its own module. A framework chapter is a function of its bluebook alone, so
-      # regenerating one is safe whichever domain last touched it.
-      def write_chapters
-        totals = { aggregates: [], queries: [], read_models: [], process_managers: [],
-                   policy_sources: [{ domain_name: @domain_name, policies: @ir[:policies],
-                                      aggregates: @ir[:aggregates] }],
-                   mod_names: { @mod_name => @domain_name } }
-        vendored = @registry.hecksagons.values.flat_map(&:vendored_packages)
-        (@registry.bluebooks.keys - [@domain_name]).each { |chapter| write_chapter(chapter, vendored, totals) }
-        totals
-      end
-
-      def write_chapter(chapter_name, vendored, totals)
-        mod_name = chapter_name.downcase
-        totals[:mod_names][mod_name] = chapter_name
-        chapter_ir = json_shaped(Hecks::Projector::Exporter.call(@registry).fetch(chapter_name))
-        result = nil
-        WriteIfChanged.track_directory(File.join(@out_root, mod_name)) do
-          result = RustProjection::DomainGenerator.call(chapter_ir, "#{@domain} (#{attachment(chapter_name, vendored)})",
-                                                        File.join(@out_root, mod_name), mod_name,
-                                                        merged_module: false)
-        end
-        totals[:aggregates].concat(result[:aggregates])
-        totals[:queries].concat(result[:queries])
-        totals[:read_models].concat(result[:read_models])
-        totals[:process_managers].concat(chapter_ir[:process_managers])
-        totals[:policy_sources] << { domain_name: chapter_name, policies: chapter_ir[:policies],
-                                     aggregates: chapter_ir[:aggregates] }
-      end
-
       # How the target attached a chapter, across every hecksagon the registry loaded: a chapter a
       # sibling hecksagon vendors in is labelled as vendored.
       def attachment(chapter_name, vendored)
@@ -265,46 +172,6 @@ module Hecks
         name ? "attaches #{name.inspect}, from: :vendor" : "attaches #{chapter_name.inspect}"
       end
 
-      def reference_keys(target_aggregates, chapters)
-        chapters[:mod_names].map do |mod_name, chapter_name|
-          own = mod_name == @mod_name ? target_aggregates : chapters[:aggregates].select { |a| a[:chapter_mod] == mod_name }
-          [chapter_name, own.map { |a| a[:name] }]
-        end
-      end
-
-      # Writes a module's `merged.rs`: the registry and every dispatch table over its aggregates.
-      def write_merged(path, aggregates, queries, read_models, policies:, cross:, managers:, keys:)
-        projector = RustProjection::Projector
-        wrote = WriteIfChanged.block(path) do |file|
-          [projector.emit_registry(aggregates), projector.emit_reference_lookup(aggregates), policies, cross,
-           projector.emit_process_manager_table(managers), projector.emit_reference_key_table(keys),
-           projector.emit_creates_table(aggregates), projector.emit_identity_head_table(aggregates),
-           projector.emit_entity_identity_head_table(aggregates),
-           projector.emit_command_attributes_table(aggregates), projector.emit_query_table(queries),
-           projector.emit_query_arg_check_table(queries)].each do |table|
-            file.puts table
-            file.puts
-          end
-          # A read model's `group_by` function is written before the table names it.
-          read_models.each do |model|
-            next unless model[:group_by_fn_body]
-
-            file.puts model[:group_by_fn_body]
-            file.puts
-          end
-          file.puts projector.emit_read_model_table(read_models)
-        end
-        puts(wrote ? "wrote #{path}" : "#{path} unchanged")
-      end
-
-      # Appends the `pub mod merged;` line once; appending it again would grow the file and bump
-      # its mtime on every run.
-      def append_merged_mod(path)
-        return if File.exist?(path) && File.read(path).include?("pub mod merged;")
-
-        File.open(path, "a") { |file| file.puts "pub mod merged;" }
-      end
-
       # `src/generated/mod.rs`: every domain ever generated, scanned off disk. A directory is a
       # selectable domain exactly when it carries its own `merged.rs`; a framework chapter has
       # none and is always compiled in.

data/lib/hecks/rust_build.rb

@@ -31,6 +31,7 @@ module Hecks
     TOOLS = {
       "project_rust"          => ["rust_build/project_rust", :ProjectRust],
       "project_wasm"          => ["rust_build/wasm", :Wasm],
+      "project_host"          => ["rust_build/host", :Host],
       "project_wasm_browser"  => ["rust_build/wasm_browser", :WasmBrowser],
       "rust_conformance"      => ["rust_build/conformance", :Conformance],
       "rust_conformance_fuzz" => ["rust_build/conformance_fuzz", :ConformanceFuzz],

data/lib/hecks/site/bluebook/site.bluebook

@@ -95,12 +95,18 @@ Hecks.bluebook "Site" do
   aggregate "SiteProjection" do
     description "One projection of a site's route table into its routes.ts, or the check that the file on disk is current."
 
-    attribute :domain,  DomainPath
-    attribute :run,     RunKey
-    attribute :out,     Location, optional: true
-    attribute :check,   Switch,   optional: true
-    attribute :output,  Report,   optional: true
-    attribute :refusal, Report,   optional: true
+    attribute :domain,    DomainPath
+    attribute :run,       RunKey
+    attribute :out,       Location,  optional: true
+    attribute :template,  Location,  optional: true
+    attribute :extension, Extension, optional: true
+    attribute :check,     Switch,    optional: true
+    attribute :live,      Location,  optional: true
+    attribute :distribution, DistributionId, optional: true
+    attribute :expect_new, PathList, optional: true
+    attribute :refs,      PolicyRefs, optional: true
+    attribute :output,    Report,    optional: true
+    attribute :refusal,   Report,    optional: true
     identified_by :run
 
     value_object "RunKey" do
@@ -116,15 +122,37 @@ Hecks.bluebook "Site" do
       invariant("a project is named by its path") { !value.to_s.empty? }
     end
 
-    # Where routes.ts is written, when not beside the project's bluebook.
+    # A directory or file anywhere on disk, relative to where the command runs: where routes.ts is
+    # written when not in the project's generated/ directory, or the template to rewrite in place.
     value_object "Location" do
       attribute :value, String, pattern: '[^\t\n\r]'
     end
 
+    # The file extension of the generated module: `ts` (routes.ts), or `mts` (routes.mts), which
+    # Node loads as an ES module even in a package whose "type" is "commonjs".
+    value_object "Extension" do
+      attribute :value, String, one_of: ["ts", "mts"]
+    end
+
     value_object "Switch" do
       attribute :value, Boolean
     end
 
+    # A CloudFront distribution's id, whose configuration `check_live` reads.
+    value_object "DistributionId" do
+      attribute :value, String, pattern: '^[A-Z0-9]+$'
+    end
+
+    # Path patterns, comma separated: the behaviours a change is about to add to the live distribution.
+    value_object "PathList" do
+      attribute :value, String, pattern: '[^\t\n\r]'
+    end
+
+    # Policy references and the ids they stand for live, as `!Ref Name=id`, comma separated.
+    value_object "PolicyRefs" do
+      attribute :value, String, pattern: '[^\t\n\r]'
+    end
+
     value_object "Report" do
       attribute :value, String
     end
@@ -134,26 +162,59 @@ Hecks.bluebook "Site" do
       transition "Fault"    => "faulted",   from: "requested"
     end
 
-    # `hecks site site_projection.project_site <project> [out=<dir>] [--check]`. With `check` nothing is written: a
-    # routes.ts that differs from the table is faulted, naming the file, so a CI job fails on drift.
+    # `hecks site site_projection.project_site <project> [out=<dir>] [template=<file>] [extension=ts|mts] [--check]`.
+    # With `check` nothing is written: a routes.ts that differs from the table is faulted, naming the
+    # file, so a CI job fails on drift.
     command "ProjectSite" do
       goal "Project a site's route table into routes.ts, or with check only compare it with the file on disk"
 
-      attribute :domain, DomainPath
-      attribute :run,    RunKey
-      attribute :out,    Location, optional: true
-      attribute :check,  Switch,   optional: true
+      attribute :domain,    DomainPath
+      attribute :run,       RunKey
+      attribute :out,       Location,  optional: true
+      attribute :template,  Location,  optional: true
+      attribute :extension, Extension, optional: true
+      attribute :check,     Switch,    optional: true
 
       sets :domain
       sets :run
       sets :out
+      sets :template
+      sets :extension
       sets :check
 
       emits "SiteProjectionRequested"
     end
 
+    # `hecks site site_projection.check_live <project> live=<saved-config.json> | distribution=<id>
+    # [expect_new=<paths>] [refs=<!Ref Name=id,...>]`. Compares the project's generated CloudFront
+    # behaviours with a live distribution's, changing neither. `live` is a saved answer of
+    # `aws cloudfront get-distribution-config`; `distribution` fetches it with that one read-only call.
+    command "CheckLive" do
+      goal "Compare a project's generated CloudFront behaviours with a live distribution's"
+
+      attribute :domain,       DomainPath
+      attribute :run,          RunKey
+      attribute :live,         Location,       optional: true
+      attribute :distribution, DistributionId, optional: true
+      attribute :expect_new,   PathList,       optional: true
+      attribute :refs,         PolicyRefs,     optional: true
+
+      given("exactly one of a saved configuration and a distribution is named: pass live= or distribution=, not both") do
+        (live.set? && distribution.unset?) || (live.unset? && distribution.set?)
+      end
+
+      sets :domain
+      sets :run
+      sets :live
+      sets :distribution
+      sets :expect_new
+      sets :refs
+
+      emits "LiveCheckRequested"
+    end
+
     command "Complete" do
-      goal "Record that routes.ts was written, or found current, and where"
+      goal "Record that routes.ts was written, or found current, or the live edge matched, and what it said"
 
       reference_to SiteProjection
       attribute :output, Report
@@ -193,6 +254,11 @@ Hecks.bluebook "Site" do
     trigger SiteProjection::SiteToolchain::Project, with: { run: :run }
   end
 
+  policy "CheckWhenRequested" do
+    on      "SiteProjection.LiveCheckRequested"
+    trigger SiteProjection::SiteToolchain::Compare, with: { run: :run }
+  end
+
   policy "RecordTheProjection" do
     on      "SiteProjection.SiteAnswered"
     trigger SiteProjection::Complete, with: { output: :output }

data/lib/hecks/site/bluebook/site.ports.hecksagon

@@ -11,5 +11,11 @@ Hecks.hecksagon "Site" do
       answers "SiteAnswered"
       refuses "SiteRefused"
     end
+
+    asks "Compare", to: SiteProjection do
+      attribute :run, RunKey
+      answers "SiteAnswered"
+      refuses "SiteRefused"
+    end
   end
 end

data/lib/hecks/sme/bluebook/sme.bluebook

@@ -21,6 +21,8 @@ Hecks.bluebook "SME" do
     attribute :thing_findings,  list_of(ThingFinding)
     attribute :action_findings, list_of(ActionFinding)
     attribute :rule_findings,   list_of(RuleFinding)
+    attribute :field_findings,      list_of(FieldFinding)
+    attribute :transition_findings, list_of(TransitionFinding)
 
     # Held as counts because a rule cannot look inside a list: `Conclude` needs to know that at least
     # one thing and one action were accepted, and each acceptance adds one here (see the policies).
@@ -92,6 +94,17 @@ Hecks.bluebook "SME" do
       attribute :value, Boolean
     end
 
+    # A list the expert gave in a breath, comma separated: the values a field may take, or the
+    # fields an action needs to be told. Absent when the expert gave none.
+    value_object "Listing" do
+      attribute :value, String, pattern: '[^\t\n\r]'
+    end
+
+    # Who may do an action, in the expert's words ("a maintainer", "QA engineer").
+    value_object "Actor" do
+      attribute :value, String, pattern: '[^\t\n\r]'
+    end
+
     # A thing the domain keeps track of, and the field that identifies one: an aggregate to be.
     entity "ThingFinding" do
       description "A thing the expert described, proposed as an aggregate, with the field that identifies one."
@@ -136,6 +149,8 @@ Hecks.bluebook "SME" do
       attribute :thing,   Name
       attribute :event,   Name
       attribute :creates, Creates, optional: true
+      attribute :takes,   Listing, optional: true
+      attribute :by,      Actor, optional: true
       attribute :source,  Source
 
       lifecycle :status, default: "proposed" do
@@ -192,6 +207,77 @@ Hecks.bluebook "SME" do
       end
     end
 
+    # Something the expert said a thing has, and the values it may take when they listed them: an
+    # attribute to be, with a closed set when the expert gave one.
+    entity "FieldFinding" do
+      description "A field the expert said a thing has, with the values it may take when they listed them."
+
+      identified_by :number
+
+      attribute :number, FindingNumber
+      attribute :thing,  Name
+      attribute :name,   Name
+      attribute :values, Listing, optional: true
+      attribute :source, Source
+
+      lifecycle :status, default: "proposed" do
+        transition "AcceptField" => "accepted", from: "proposed"
+        transition "RejectField" => "rejected", from: "proposed"
+      end
+
+      command "AcceptField", from: "proposed" do
+        goal "Establish that the field is real"
+
+        attribute :number, FindingNumber
+
+        emits "FieldAccepted"
+      end
+
+      command "RejectField", from: "proposed" do
+        goal "Set the proposed field aside"
+
+        attribute :number, FindingNumber
+
+        emits "FieldRejected"
+      end
+    end
+
+    # The state a thing is in after an action, and the state it had to be in before: one step of a
+    # lifecycle to be. The step an action that creates the thing makes names the state it starts in.
+    entity "TransitionFinding" do
+      description "A change of state an action makes to a thing, and the state it must be in before."
+
+      identified_by :number
+
+      attribute :number, FindingNumber
+      attribute :thing,  Name
+      attribute :action, Name
+      attribute :to,     Name
+      attribute :from,   Name, optional: true
+      attribute :source, Source
+
+      lifecycle :status, default: "proposed" do
+        transition "AcceptTransition" => "accepted", from: "proposed"
+        transition "RejectTransition" => "rejected", from: "proposed"
+      end
+
+      command "AcceptTransition", from: "proposed" do
+        goal "Establish that the change of state is real"
+
+        attribute :number, FindingNumber
+
+        emits "TransitionAccepted"
+      end
+
+      command "RejectTransition", from: "proposed" do
+        goal "Set the proposed change of state aside"
+
+        attribute :number, FindingNumber
+
+        emits "TransitionRejected"
+      end
+    end
+
     lifecycle :status, default: "planned" do
       transition "Begin"    => "underway",  from: "planned"
       transition "Conclude" => "concluded", from: "underway"
@@ -257,16 +343,57 @@ Hecks.bluebook "SME" do
       attribute :thing,   Name
       attribute :event,   Name
       attribute :creates, Creates, optional: true
+      attribute :takes,   Listing, optional: true
+      attribute :by,      Actor, optional: true
       attribute :source,  Source
 
       given("findings are proposed only while the interview is underway") { status == "underway" }
       given("a finding cites an exchange that was recorded") { source.value <= exchanges.size }
 
-      sets :action_findings, append: { number: :number, name: :name, thing: :thing, event: :event, creates: :creates, source: :source }
+      sets :action_findings, append: { number: :number, name: :name, thing: :thing, event: :event, creates: :creates,
+                                       takes: :takes, by: :by, source: :source }
 
       emits "ActionProposed"
     end
 
+    command "ProposeField" do
+      goal "Propose a field the expert said a thing has, and the values it may take"
+
+      reference_to Interview
+      attribute :number, FindingNumber
+      attribute :thing,  Name
+      attribute :name,   Name
+      attribute :values, Listing, optional: true
+      attribute :source, Source
+
+      given("findings are proposed only while the interview is underway") { status == "underway" }
+      given("a finding cites an exchange that was recorded") { source.value <= exchanges.size }
+
+      sets :field_findings, append: { number: :number, thing: :thing, name: :name, values: :values, source: :source }
+
+      emits "FieldProposed"
+    end
+
+    command "ProposeTransition" do
+      goal "Propose the change of state an action makes to a thing"
+
+      reference_to Interview
+      attribute :number, FindingNumber
+      attribute :thing,  Name
+      attribute :action, Name
+      attribute :to,     Name
+      attribute :from,   Name, optional: true
+      attribute :source, Source
+
+      given("findings are proposed only while the interview is underway") { status == "underway" }
+      given("a finding cites an exchange that was recorded") { source.value <= exchanges.size }
+
+      sets :transition_findings, append: { number: :number, thing: :thing, action: :action, to: :to, from: :from,
+                                           source: :source }
+
+      emits "TransitionProposed"
+    end
+
     command "ProposeRule" do
       goal "Keep a rule in the expert's words"
 

data/lib/hecks/storehouse.rb

@@ -230,10 +230,44 @@ module Hecks
       result = runtime.dispatch_flat(spec[:command], envelope)
       ok(summary: summary,
          id:      result.id,
-         state:   result.state.nil? ? nil : Doors::JsonDoor.materialize(result.state),
+         state:   settled_state(runtime, spec, result),
          events:  result.events.map { |event| { name: event.name, payload: Doors::JsonDoor.materialize(event.payload) } })
     end
 
+    # The record as its repository holds it once every reaction has run, which is the state the
+    # dispatch resulted in; the handle's own state is the record as the command left it, so a run
+    # record that a reaction completes would otherwise read as `requested`. Falls back to the
+    # handle's state for a command that belongs to no top-level aggregate or whose record cannot be
+    # read.
+    # :nodoc:
+    def settled_state(runtime, spec, result)
+      return if result.state.nil?
+
+      bluebook = bluebook_for(runtime)
+      head = spec[:command].split("::", 2).last
+      aggregate = bluebook.aggregates.find { |candidate| candidate.hecks_name == head.split(".").first } if
+        head.count(".") == 1
+      record = aggregate && runtime.registry.repository(bluebook.name, aggregate)&.find(result.id)&.to_h
+      Doors::JsonDoor.materialize(record || result.state)
+    end
+
+    # What a caller needs to call each of the named commands: its qualified name, the role it
+    # declares, what it does, and its argument names, a trailing `*` marking a required one.
+    #
+    # @param runtime [Runtime::Dispatcher] the booted domain
+    # @param names [Array<String>] short or qualified command names
+    # @return [Array<String>] one line per name that resolves, in order
+    def command_guide(runtime, names)
+      cli = Projector.call(:cli, bluebook: bluebook_for(runtime), options: { program: "mcp" })
+      names.filter_map do |name|
+        spec = resolve!(cli, name.to_s, asking: false)
+        arguments = spec[:arguments].map { |arg| arg[:path].split(".").first + (arg[:required] ? "*" : "") }
+        "#{name} (role #{spec[:role] || 'none'}): #{spec[:summary]}. Arguments: #{arguments.uniq.join(', ')}"
+      rescue Runtime::NotFound
+        nil
+      end
+    end
+
     # :nodoc:
     def dry_run_outcome(runtime, spec, envelope, summary:)
       flat = flatten_legacy(envelope, spec[:receiver], spec[:legacy_receiver])

data/lib/hecks/tools/comment_style.rb

@@ -946,10 +946,12 @@ module Hecks
           $CHILD_STATUS.success? ? out : nil
         end
 
-        # `.rb` files, plus extensionless scripts with a Ruby shebang.
+        # `.rb` files, plus extensionless scripts with a Ruby shebang. The first line is read as
+        # bytes, so an extensionless binary (a compiled test fixture's output) is passed over
+        # rather than refused for not being UTF-8.
         def ruby_files(dir)
           scripts = Dir[File.join(dir, "**", "*")].select do |path|
-            File.file?(path) && File.extname(path).empty? && File.open(path, &:gets).to_s.match?(/\A#!.*ruby/)
+            File.file?(path) && File.extname(path).empty? && File.open(path, "rb", &:gets).to_s.match?(/\A#!.*ruby/n)
           end
           Dir[File.join(dir, "**", "*.rb")] + scripts
         end

data/lib/hecks/tools/gate.rb

@@ -25,7 +25,7 @@ module Hecks
       # @param root [String] the checkout the checks run in
       # @return [Integer] 0 when every check passed, 1 when one failed, 2 on bad usage
       def main(argv, root: Tools::ROOT, **)
-        stages = YAML.load_file(STAGES_FILE)
+        stages = YAML.load_file(STAGES_FILE, aliases: true)
         return list(stages) if argv == ["--list"]
 
         name = argv.find { |arg| !arg.include?("=") && !arg.start_with?("--") }