hecks 3.14.0 → 5.0.0

data/lib/hecks/quality_control/adapters/agent.rb

@@ -62,7 +62,7 @@ module Hecks
 
       # Permission rules are a feature of `claude`: any other command would run unconfined.
       def refuse_unconfinable!(words, profile)
-        return if profile.nil? || profile.sandboxed? || words == default_command(profile)
+        return if profile.nil? || words == default_command(profile)
 
         raise Failed, "permission confinement applies only to the default claude command"
       end
@@ -79,15 +79,14 @@ module Hecks
         %w[claude -p --permission-mode] + [profile.permission_mode] + profile.tool_flags
       end
 
-      # Runs `words` under the profile's sandbox with only the environment it names, in its own
-      # process group so a timeout takes the agent's children with it.
+      # Runs `words` with only the environment the profile names, in its own process group so a
+      # timeout takes the agent's children with it. The reader starts first so an agent that
+      # writes before it has read its whole prompt cannot block both sides on a full pipe.
       def run_confined(words, prompt, chdir, profile)
-        raise Failed, "no sandbox here; refusing to run an agent unconfined" unless profile.available?
-
-        Open3.popen2e(profile.environment, *profile.confine(words),
+        Open3.popen2e(profile.environment, *words,
                       chdir: chdir, unsetenv_others: true, pgroup: true) do |stdin, out, waiter|
-          feed(stdin, prompt)
           reader = Thread.new { out.read }
+          feed(stdin, prompt)
           finish(waiter, reader, profile.timeout)
         end
       end

data/lib/hecks/quality_control/adapters/agent_profile.rb

@@ -1,93 +1,47 @@
 # frozen_string_literal: true
 
-require "tmpdir"
-
 module Hecks
   module Adapters
-    # What one `Agent` run may do: which tools it holds, where it may write, what it may reach on
-    # the network, which environment variables it sees and how long it may run.
+    # What one `Agent` run may do: which tools it holds, where it may write, which environment
+    # variables it sees and how long it may run.
     #
-    # Confinement uses the macOS sandbox. Where there is none, a confined run refuses to start
-    # rather than run unconfined.
+    # Confinement is the permission rules of the `claude` command itself, so a run keeps the
+    # user's own login. Only the default `claude` command understands them; `Agent` refuses to
+    # run any other command under a profile.
     class AgentProfile
-      # What the network rule lets through: nothing, outbound HTTPS and name lookups, or anything.
-      NETWORKS = %i[none https any].freeze
-
-      # How a run is confined: under the operating system's sandbox, or by the permission rules
-      # of the `claude` command itself. Only the second leaves the user's own login usable, since
-      # the sandbox refuses the keychain and `~/.claude`.
-      CONFINEMENTS = %i[sandbox permissions].freeze
-
       # The variables every confined agent sees besides the ones its profile names.
       BASE_ENV = %w[PATH HOME USER LOGNAME SHELL LANG LC_ALL TERM TMPDIR].freeze
 
-      # The tools that write files; a permissions-confined run holds them only through path rules.
+      # The tools that write files; a confined run holds them only through path rules.
       WRITING_TOOLS = %w[Write Edit MultiEdit NotebookEdit].freeze
 
-      # Home-relative places an agent may not read: credentials and the harness's own state.
-      CREDENTIAL_PATHS = %w[
-        .ssh .aws .gnupg .claude .config/gh .config/op .gem/credentials .netrc Library/Keychains
-      ].freeze
-
-      SANDBOX = "/usr/bin/sandbox-exec"
-
-      # The keywords `new` takes besides the four lists, with what each defaults to.
-      LIMIT_DEFAULTS = { timeout: nil, budget: nil, confinement: :sandbox }.freeze
-
       # @return [Array<String>] the tools the agent is given
       attr_reader :tools
-      # @return [Array<String>] the directories the agent may write, besides the temp directory
+      # @return [Array<String>] the directories the agent may write
       attr_reader :writable
-      # @return [Symbol] one of `NETWORKS`
-      attr_reader :network
       # @return [Array<String>] the environment variable names the agent may see besides `BASE_ENV`
       attr_reader :env
       # @return [Integer, nil] seconds the run may take; nil for no limit
       attr_reader :timeout
       # @return [Float, nil] the most the run may spend, in dollars, for an agent that takes one
       attr_reader :budget
-      # @return [Symbol] one of `CONFINEMENTS`
-      attr_reader :confinement
 
       # @param tools [Array<String>] the tools the agent is given
       # @param writable [Array<String>] directories the agent may write
-      # @param network [Symbol] one of `NETWORKS`
       # @param env [Array<String>] environment variable names to pass through
-      # @param limits [Hash] `timeout:` (Integer, nil) seconds the run may take, `budget:`
-      #   (Float, nil) dollars it may spend, `confinement:` one of `CONFINEMENTS` (`network`
-      #   applies to the sandbox only)
-      # @raise [ArgumentError] when `network` or `confinement` is not one it knows
-      def initialize(tools: [], writable: [], network: :none, env: [], **limits)
-        limits = LIMIT_DEFAULTS.merge(reject_unknown(limits))
-        ensure_known(:network, NETWORKS, network)
-        ensure_known(:confinement, CONFINEMENTS, limits[:confinement])
+      # @param timeout [Integer, nil] seconds the run may take
+      # @param budget [Float, nil] dollars it may spend
+      def initialize(tools: [], writable: [], env: [], timeout: nil, budget: nil)
         @tools = tools.dup.freeze
         @writable = writable.dup.freeze
-        @network = network
         @env = env.dup.freeze
-        @timeout, @budget, @confinement = limits.values_at(:timeout, :budget, :confinement)
-      end
-
-      # @return [Boolean] whether this profile is enforced by the operating system's sandbox
-      def sandboxed?
-        confinement == :sandbox
-      end
-
-      # @return [Boolean] whether this machine can apply this profile's confinement
-      def available?
-        !sandboxed? || File.executable?(SANDBOX)
-      end
-
-      # @param words [Array<String>] the agent's command
-      # @return [Array<String>] `words`, run under the sandbox with this profile's policy; the
-      #   words unchanged when the confinement is the command's own permission rules
-      def confine(words)
-        sandboxed? ? [SANDBOX, "-p", policy, *words] : words
+        @timeout = timeout
+        @budget = budget
       end
 
       # @return [String] the `claude` permission mode this profile runs under
       def permission_mode
-        sandboxed? ? "acceptEdits" : "dontAsk"
+        "dontAsk"
       end
 
       # @param source [Hash{String => String}] the environment to take values from
@@ -96,79 +50,27 @@ module Hecks
         source.to_h.slice(*BASE_ENV, *env)
       end
 
-      # The `claude` flags this profile's tools and budget become.
+      # The `claude` flags this profile's tools and budget become. The writing tools are held only
+      # through an `Edit` rule per writable directory, which every file-writing tool answers to.
       #
       # @return [Array<String>]
       def tool_flags
         flags = tools.empty? ? [] : ["--tools", tools.join(","), "--allowedTools", *allowed_tools]
-        flags += ["--strict-mcp-config"] unless sandboxed?
+        flags += ["--strict-mcp-config"]
         flags + (budget ? ["--max-budget-usd", budget.to_s] : [])
       end
 
-      # @return [String] the sandbox policy: reads open but for credentials, writes where allowed
-      def policy
-        [
-          "(version 1)", "(allow default)",
-          "(deny file-write*)", write_rule, "(deny file-read*#{paths_clause(credential_paths)})",
-          *network_rules
-        ].join("\n")
-      end
-
       private
 
-      # The tools allowed without asking. A permissions-confined run holds the writing tools only
-      # through an `Edit` rule per writable directory, which every file-writing tool answers to.
       def allowed_tools
-        return [tools.join(",")] if sandboxed?
-
         tools - WRITING_TOOLS + writable.map { |path| "Edit(/#{real(path)}/**)" }
       end
 
-      def write_rule
-        allowed = [real(Dir.tmpdir), *writable.map { |path| real(path) }]
-        devices = '(literal "/dev/null") (literal "/dev/tty") (regex #"^/dev/fd/")'
-        "(allow file-write*#{paths_clause(allowed)} #{devices})"
-      end
-
-      def credential_paths
-        CREDENTIAL_PATHS.map { |path| File.join(Dir.home, path) }
-      end
-
-      def paths_clause(paths)
-        paths.map { |path| " (subpath #{quote(path)})" }.join
-      end
-
-      def network_rules
-        case network
-        when :any then []
-        when :https then ["(deny network*)", '(allow network-outbound (remote tcp "*:443") (remote udp "*:53"))',
-                          '(allow network-outbound (remote unix-socket (path-literal "/private/var/run/mDNSResponder")))']
-        else ["(deny network*)"]
-        end
-      end
-
-      def reject_unknown(limits)
-        unknown = limits.keys - LIMIT_DEFAULTS.keys
-        return limits if unknown.empty?
-
-        raise ArgumentError, "unknown keyword#{"s" if unknown.size > 1}: #{unknown.map(&:inspect).join(", ")}"
-      end
-
-      def ensure_known(name, allowed, value)
-        return if allowed.include?(value)
-
-        raise ArgumentError, "#{name} must be one of #{allowed.inspect}, not #{value.inspect}"
-      end
-
       def real(path)
         File.realpath(path)
       rescue SystemCallError
         File.expand_path(path)
       end
-
-      def quote(path)
-        %("#{path.gsub("\\", "\\\\\\\\").gsub('"', '\\"')}")
-      end
     end
   end
 end

data/lib/hecks/quality_control/cli/qa_mine_combinations.rb

@@ -116,7 +116,7 @@ module Hecks
       # The profile `--confine` runs the agent under: it writes only the candidates directory.
       def confinement_profile
         FileUtils.mkdir_p(@out_dir)
-        Hecks::Adapters::AgentProfile.new(confinement: :permissions, tools: CONFINED_TOOLS, writable: [@out_dir],
+        Hecks::Adapters::AgentProfile.new(tools: CONFINED_TOOLS, writable: [@out_dir],
                                           timeout: CONFINED_TIMEOUT, budget: CONFINED_BUDGET)
       end
 

data/lib/hecks/runtime/loader/boot_steps.rb

@@ -43,7 +43,6 @@ module Hecks
           gates = BootGates.new
           load_bound_adapters!(registry)
           Ports::Persistence.each_plugin { |plugin| plugin.contribute_boot_gates(registry, gates) }
-          check_compute_rules_backstop!(registry)
 
           gates.run!(:pre_verify, registry, directory)
           registry.verify!
@@ -67,25 +66,6 @@ module Hecks
           (bound + default).each { |name| load_adapter(registry, name) }
         end
 
-        # A backstop only: fires when a translation declares a `computes`/
-        # `rekeys` rule but no persistence plugin is loaded to interpret it.
-        # Any loaded plugin's own compute-rules gate refuses earlier, by name,
-        # whenever one is loaded — this only runs when nothing was.
-        def check_compute_rules_backstop!(registry)
-          return if Ports::Persistence.plugins_loaded?
-
-          registry.translations.each do |translation|
-            translation.aggregates.each do |aggregate|
-              next if aggregate.computes.empty? && aggregate.rekeys.empty?
-
-              raise WiringError,
-                    "cannot boot #{translation.domain}::#{aggregate.name}: a compute/rekey rule is declared, but no " \
-                    "persistence plugin that can interpret it is loaded (e.g. require " \
-                    "\"hecks/ports/persistence/plugins/era\")"
-            end
-          end
-        end
-
         private
 
         def load_adapter(registry, name)

data/lib/hecks/runtime/outbox.rb

@@ -2,6 +2,7 @@ require "json"
 require "securerandom"
 require "time"
 require_relative "event"
+require_relative "value"
 require_relative "../naming"
 
 module Hecks
@@ -48,19 +49,11 @@ module Hecks
           name:        hash[:name],
           aggregate:   hash[:aggregate],
           id:          hash[:id],
-          payload:     deep_symbolize(hash[:payload] || {}),
+          payload:     Value.deep_symbolize(hash[:payload] || {}),
           occurred_at: hash[:occurred_at],
           correlation: hash[:correlation]
         ).emit!
       end
-
-      def deep_symbolize(value)
-        case value
-        when Hash  then value.to_h { |k, v| [k.to_sym, deep_symbolize(v)] }
-        when Array then value.map { |element| deep_symbolize(element) }
-        else value
-        end
-      end
     end
   end
 end

data/lib/hecks/runtime/port_operation_interpreter.rb

@@ -101,15 +101,7 @@ module Hecks
       def spread(answer)
         return { answered: answer } unless answer.is_a?(Hash)
 
-        answer.to_h { |key, value| [key.to_sym, deep_symbolize(value)] }
-      end
-
-      def deep_symbolize(value)
-        case value
-        when Hash  then value.to_h { |k, v| [k.to_sym, deep_symbolize(v)] }
-        when Array then value.map { |element| deep_symbolize(element) }
-        else value
-        end
+        Value.deep_symbolize(answer)
       end
 
       # The record, if there is one. A missing record is not an error here: the ask still

data/lib/hecks/runtime/remote_dispatcher.rb

@@ -117,8 +117,8 @@ module Hecks
         [domain, aggregate]
       end
 
-      # Not every aggregate in a routed domain is Lambda-bound (a `compute` rule can
-      # only run against Postgres). Test the adapter's capability, not its name.
+      # Not every aggregate in a routed domain is Lambda-bound (a persistence binding
+      # may name another adapter). Test the adapter's capability, not its name.
       def remote_bound?(domain, aggregate)
         adapter_name = Ports::Persistence::BindingPolicy.resolve(@registry, domain, aggregate).adapter
         @registry.adapter_class(adapter_name) <= Ports::Persistence::RemoteRuntime

data/lib/hecks/runtime/value/unwrapping.rb

@@ -0,0 +1,60 @@
+module Hecks
+  module Runtime
+    class Value
+      # The shape a caller is answered with: a single-attribute value object as its bare field,
+      # following the declared types down through nested value objects and lists. Extended into
+      # `Value` beside `Coercion`; `materialize` keeps the wrapped shape stored state depends on.
+      module Unwrapping
+        # `materialize`, but a single-attribute value object unwraps to its bare field. What
+        # `group_by` rows and `Driving::Json.materialize` answer with.
+        #
+        # @param value [Object] the value to materialize; anything that is not a `Runtime::Value`,
+        #   Array or Hash passes through unchanged
+        # @return [Object] `value` with every nested `Runtime::Value` replaced by its own sole
+        #   field's value (recursively unwrapped), or by its own `Hash` of fields when it has
+        #   more than one
+        def materialize_unwrapped(value)
+          case value
+          when self then unwrap_typed(value.value_object, value.raw_fields)
+          when Array then value.map { |item| materialize_unwrapped(item) }
+          when Hash then value.transform_values { |item| materialize_unwrapped(item) }
+          else value
+          end
+        end
+
+        private
+
+        # A value object's fields by its declared attributes. A nested value object is often held
+        # as a plain Hash, so its own type is looked up rather than read off the field.
+        def unwrap_typed(value_object, fields)
+          sole = value_object.sole_attribute
+          return unwrap_field(value_object, sole, fields[sole.name]) if sole
+
+          value_object.attributes.to_h { |attr| [attr.name, unwrap_field(value_object, attr, fields[attr.name])] }
+        end
+
+        def unwrap_field(value_object, attribute, held)
+          case held
+          when Array then held.map { |item| unwrap_field(value_object, attribute, item) }
+          when Hash then unwrap_held_hash(value_object, attribute, held)
+          else materialize_unwrapped(held)
+          end
+        end
+
+        def unwrap_held_hash(value_object, attribute, held)
+          nested = nested_value_object(value_object, attribute.type)
+          return materialize_unwrapped(held) unless nested
+
+          unwrap_typed(nested, held.transform_keys(&:to_sym))
+        end
+
+        # The value object a field's type names, resolved against the aggregate that declares
+        # `value_object`; nil for a primitive, or when the owner is not known.
+        def nested_value_object(value_object, type)
+          owner = value_object.respond_to?(:hecks_owner) ? value_object.hecks_owner : nil
+          owner.respond_to?(:value_object) ? value_object_for(owner, type) : nil
+        end
+      end
+    end
+  end
+end

data/lib/hecks/runtime/value.rb

@@ -9,12 +9,13 @@ require_relative "value/flags"
 require_relative "value/identifiers"
 require_relative "value/entity_list_coercion"
 require_relative "value/admission"
+require_relative "value/unwrapping"
 
 module Hecks
   module Runtime
     # A typed value object: frozen fields, read by name.
     # Construction lives in value/coercion.rb, field_checks.rb, entity_list_coercion.rb and
-    # admission.rb.
+    # admission.rb; the shape a caller is answered with in unwrapping.rb.
     class Value
       extend FieldChecks
       extend Coercion
@@ -24,6 +25,7 @@ module Hecks
       extend Identifiers
       extend EntityListCoercion
       extend Admission
+      extend Unwrapping
 
       attr_reader :value_object
 
@@ -102,32 +104,19 @@ module Hecks
         end
       end
 
-      # `materialize`, but a single-attribute value object unwraps to its bare field.
-      # Opt-in for `group_by` rows; `materialize` keeps the wrapped shape callers depend on.
+      # Converts every Hash key to a Symbol, at every depth of parsed JSON.
       #
-      # @param value [Object] the value to materialize; anything that is not a `Runtime::Value`,
-      #   Array or Hash passes through unchanged
-      # @return [Object] `value` with every nested `Runtime::Value` replaced by its own sole
-      #   field's value (recursively unwrapped), or by its own `Hash` of fields when it has
-      #   more than one
-      def self.materialize_unwrapped(value)
+      # @param value [Hash, Array, Object] a Hash or Array is walked; any other value is a leaf
+      # @return [Hash{Symbol => Object}, Array, Object] a new structure of the same shape with
+      #   Symbol keys; a leaf is returned as it came
+      def self.deep_symbolize(value)
         case value
-        when self then unwrap_value_object(value)
-        when Array then value.map { |item| materialize_unwrapped(item) }
-        when Hash then value.transform_values { |item| materialize_unwrapped(item) }
+        when Hash then value.to_h { |key, item| [key.to_sym, deep_symbolize(item)] }
+        when Array then value.map { |item| deep_symbolize(item) }
         else value
         end
       end
 
-      def self.unwrap_value_object(value)
-        sole = value.value_object.sole_attribute
-        return materialize_unwrapped(value[sole.name]) if sole
-
-        # Not `value.to_h`: it materializes nested values to Hashes, ending the recursion.
-        value.value_object.attributes.to_h { |attr| [attr.name, materialize_unwrapped(value[attr.name])] }
-      end
-      private_class_method :unwrap_value_object
-
       # Reduces an append-only `list_of` sub-log to its current state: the latest row per `key`.
       # Grouping only; what counts as removed, and the ordering, belong to the caller.
       #

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

@@ -36,6 +36,7 @@ module Hecks
           ir = shaped(exporter.call(@registry).fetch(@domain_name))
           ir[:lineage] = shaped(exporter.lineage(@registry, @domain_name))
           ir[:persistence] = shaped(exporter.persistence(@registry, @domain_name))
+          add_persistence_wiring(ir, exporter)
           add_seams(ir, exporter)
           add_edges_and_source(ir)
           ir
@@ -43,8 +44,28 @@ module Hecks
 
         private
 
+        # The adapters and the world that the host checks the persistence against.
+        def add_persistence_wiring(document, exporter)
+          document[:adapters] = adapters(exporter, document[:persistence])
+          document[:world] = world(exporter)
+        end
+
         def shaped(payload) = self.class.json_shaped(payload)
 
+        # The bound persistence adapters' declarations, from the `.adapter` files under the
+        # source root's `lib/` and the domain's own directory, so the host can look them up.
+        def adapters(exporter, persistence)
+          files = exporter.adapter_files_under([File.join(RustBuild::ROOT, "lib"), File.dirname(@bluebook_dir)])
+          shaped(exporter.persistence_adapters(persistence, files))
+        end
+
+        # The target's world persistence, from `<domain directory name>.world` beside the bluebooks
+        # (names only), so the host can check what the world binds against the adapters.
+        def world(exporter)
+          path = File.join(@bluebook_dir, "#{File.basename(File.dirname(@bluebook_dir))}.world")
+          shaped(exporter.persistence_world(path, @domain_name))
+        end
+
         def add_seams(document, exporter)
           seams = SEAMS.to_h { |seam| [seam, exporter.public_send(seam, @registry, @domain_name)] }
           seams.each { |seam, value| document[seam] = shaped(value) unless value.empty? }
@@ -56,14 +77,12 @@ module Hecks
                          "hecksagon, not a deploy-time guess, names the identity verbs."
         end
 
-        # Edges carry their own precompiled SQL, so a boot-time mint only executes it. Committed
-        # approvals sit beside the edges. The source text is verbatim: the era's integrity digest is
+        # Edges carry their own precompiled SQL, so a boot-time mint only executes it. The source
+        # text is verbatim: the era's integrity digest is
         # the SHA256 of it, not of anything re-derived from the parsed IR.
         def add_edges_and_source(document)
           edges = Hecks::Projector::Exporter.translations(@registry).select { |edge| edge[:domain] == @domain_name }
           document[:translations] = shaped(edges)
-          approvals = Hecks::Translation::ApprovalFile.read_all(@bluebook_dir)
-          document[:approvals] = shaped(approvals) unless approvals.empty?
           document[:source_text] = Hecks::Runtime::EraCheck.source_text_for(
             @registry.bluebooks.fetch(@domain_name), @bluebook_dir, registry: @registry
           )

data/lib/hecks/rust_build/wasm.rb

@@ -31,7 +31,6 @@ module Hecks
       # @raise [Failure] when the target is not installed or a step fails
       def call(argv)
         domain = argv.first or raise Failure, "usage: hecks build_wasm <domain>"
-        return build_with_rust(domain) if ENV["HECKS_PARSER"] == "rust" && ENV["HECKS_CODEGEN"] == "rust"
 
         require_target!
         rust_dir = RustBuild.rust_dir
@@ -48,17 +47,6 @@ module Hecks
         raise Failure, "project_rust failed for #{domain}" unless status.zero?
       end
 
-      # With the Rust parser and codegen, `hecks-build` runs the same steps and writes the same
-      # outputs.
-      def build_with_rust(domain)
-        build_dir = File.join(ROOT, "rust", "build")
-        puts "== cargo build (hecks-build) =="
-        RustBuild.command!("cargo", "build", chdir: build_dir)
-        puts "== hecks-build #{domain} --wasm =="
-        RustBuild.command!(File.join(build_dir, "target", "debug", "hecks-build"), domain, "--wasm")
-        0
-      end
-
       def require_target!
         return if RustBuild.target_installed?(TARGET)
 

data/lib/hecks/rust_build/write_if_changed.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "fileutils"
+require_relative "../rust_format"
 
 module Hecks
   module RustBuild
@@ -9,17 +10,8 @@ module Hecks
     module WriteIfChanged
       module_function
 
-      # Records every path written or confirmed unchanged inside the block, then deletes
-      # files left in `dir` that were never touched (orphans of removed aggregates).
-      # Every write is recorded against every open ancestor directory.
-      # `push_directory`/`pop_and_prune` are the same operation split for non-adjacent writes.
-      def track_directory(dir)
-        push_directory(dir)
-        yield
-      ensure
-        pop_and_prune(dir)
-      end
-
+      # Starts recording every path written or confirmed unchanged inside `dir`, against every open
+      # ancestor directory too; `pop_and_prune` closes it and deletes the files never touched.
       def push_directory(dir)
         FileUtils.mkdir_p(dir)
         stack.push([File.expand_path(dir), Set.new])
@@ -56,6 +48,7 @@ module Hecks
       # Returns whether it wrote.
       def call(path, content)
         record_touch(path)
+        content = RustFormat.call(content) if RustFormat.rust?(path)
         # `.b` on both sides: String#== is encoding-aware, so UTF-8 vs ASCII-8BIT
         # content can compare unequal even when the bytes are identical.
         return false if File.exist?(path) && File.binread(path) == content.b
@@ -64,13 +57,20 @@ module Hecks
         true
       end
 
+      # Fills `tmp` from the block, then lays it out with rustfmt when `path` is Rust source.
+      def write_formatted(tmp, path, &)
+        File.open(tmp, "w", &)
+        File.write(tmp, RustFormat.call(File.read(tmp))) if RustFormat.rust?(path)
+      end
+      private_class_method :write_formatted
+
       # Like `call`, for callers that build content by writing to an IO. Yields a sibling
       # temp file, then renames it into place only if the bytes differ. Returns whether it wrote.
       def block(path, &)
         record_touch(path)
         tmp = "#{path}.tmp-#{Process.pid}-#{rand(1_000_000)}"
         begin
-          File.open(tmp, "w", &)
+          write_formatted(tmp, path, &)
           changed = !(File.exist?(path) && FileUtils.compare_file(tmp, path))
           FileUtils.mv(tmp, path) if changed
           changed

data/lib/hecks/rust_format.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Hecks
+  # Runs generated Rust through rustfmt, so a generator writes what `cargo fmt --check` accepts.
+  #
+  # Every generator that writes a `.rs` file formats its text here before comparing it with the tree
+  # or writing it, so a drift check and a write see the same bytes. The edition is pinned in the
+  # call, not read from a `rustfmt.toml`, because a generator may run from any directory.
+  module RustFormat
+    # Raised when the rustfmt program cannot be found.
+    class Missing < StandardError; end
+
+    # Raised when rustfmt fails for a reason that is not the text: a toolchain that will not
+    # install, say. Falling back to the unformatted text would write the wrong bytes without a word.
+    class Failed < StandardError; end
+
+    EDITION = "2021"
+
+    # The most passes `call` makes; a text still changing after them keeps the last result.
+    PASSES = 3
+
+    module_function
+
+    # @param path [String] where the text will be written
+    # @return [Boolean] whether the path is Rust source
+    def rust?(path)
+      path.to_s.end_with?(".rs")
+    end
+
+    # Formats one Rust source text.
+    #
+    # Text rustfmt cannot parse is returned as it came, with a warning on stderr: the compiler will
+    # name the real fault, and a generator should not be the thing that hides it. Any other failure
+    # of rustfmt raises, since the text is not the problem.
+    #
+    # @param text [String] Rust source
+    # @return [String] the same source as rustfmt lays it out
+    # @raise [Missing] when rustfmt is not installed
+    # @raise [Failed] when rustfmt fails for a reason other than the text
+    def call(text)
+      PASSES.times do
+        formatted = pass(text)
+        return formatted if formatted == text
+
+        text = formatted
+      end
+      text
+    end
+
+    # One rustfmt run. rustfmt does not always reach a fixed point in one pass, so `call` repeats it
+    # until the text stops changing, as a later `cargo fmt --check` would have it.
+    #
+    # @param text [String] Rust source
+    # @return [String] the source after one pass, or unchanged when rustfmt cannot parse it
+    # @raise [Failed] when rustfmt fails for a reason other than the text
+    def pass(text)
+      out, err, status = Open3.capture3("rustfmt", "--edition", EDITION, "--emit", "stdout", stdin_data: text)
+      return out if status.success?
+      raise Failed, "rustfmt failed: #{err.lines.first&.strip}" unless err.include?("<stdin>")
+
+      warn "hecks: rustfmt could not format generated Rust, leaving it as generated: #{err.lines.first&.strip}"
+      text
+    rescue Errno::ENOENT
+      raise Missing, "rustfmt is not installed: generated Rust is formatted with it; run `rustup component add rustfmt`"
+    end
+
+    # Formats the Rust texts of a path-to-text map and leaves the others alone.
+    #
+    # @param content [Hash{String => String}] absolute path to text
+    # @return [Hash{String => String}] the same map with each `.rs` text formatted
+    def files(content)
+      content.to_h { |path, text| [path, rust?(path) ? call(text) : text] }
+    end
+  end
+end