hecks 2.9.0 → 3.0.0

data/lib/hecks/tools/hoist_local_givens.rb

@@ -0,0 +1,246 @@
+# frozen_string_literal: true
+
+require_relative "../tools"
+
+module Hecks
+  module Tools
+    # Hoists `given`s that two or more commands under one owner repeat verbatim into a single
+    # owner-level `given`, leaving bare references behind. Single-owner groups in example domains
+    # only.
+    #
+    # It is not a `Hecks::Codemod::Runner`: hoisting adds an owner-level precondition, so the
+    # exported IR cannot stay byte-identical. The invariant checked instead is each command's
+    # effective rules.
+    #
+    # The `given` is inserted right after the owner's opening line: `command` calls are deferred
+    # to `drain_pending!`, so the position of `given` inside the owner does not matter (ADR 0028).
+    #
+    #   hecks hoist_local_givens [--dry-run]
+    module HoistLocalGivens
+      # One rule several commands of an owner repeat.
+      Candidate = Struct.new(:description, :canonical, :owner, :locations, keyword_init: true)
+
+      module_function
+
+      # Rewrites every example domain that has a candidate, and prints one line for each.
+      #
+      # @param argv [Array<String>] `--dry-run` to restore every file after the rewrite is checked
+      # @param root [String] the checkout (unused: the examples come from `Codemod`)
+      # @return [Integer] 0
+      def main(argv, root: Tools::ROOT)
+        _ = root
+        require "hecks"
+        require "hecks/codemod"
+        require "hecks/query_ir"
+        dry_run = argv.include?("--dry-run")
+
+        results = Hecks::Codemod::EXAMPLE_ROOTS.filter_map do |domain_dir|
+          bluebook_files = Dir.glob(File.join(domain_dir, "bluebook", "*.bluebook"))
+          next if bluebook_files.empty?
+
+          run_files(bluebook_files, dry_run: dry_run)
+        end
+
+        report(results, dry_run)
+        0
+      end
+
+      # @param results [Array<Hash>] one outcome for each example domain
+      # @param dry_run [Boolean] whether nothing was kept
+      # @return [void]
+      def report(results, dry_run)
+        label = ->(c) { "#{c.owner}##{c.description.inspect} (#{c.locations.size} locations)" }
+
+        puts "== results (#{dry_run ? 'DRY RUN — nothing written' : 'applied'}) =="
+        results.each do |r|
+          case r[:status]
+          when :clean   then puts "clean (no candidates): #{r[:file]}"
+          when :applied then puts "APPLIED  #{r[:file]}: #{r[:candidates].map(&label).join(', ')}"
+          when :skipped then puts "SKIPPED  #{r[:file]} (#{r[:reason]}): #{r[:candidates].map(&label).join(', ')}"
+          end
+        end
+      end
+
+      # Grouped by owner as well as description: identical rules recur across unrelated
+      # aggregates, and a cross-owner match must not block hoisting the single-owner ones.
+      #
+      # @param registry [Object] the booted bluebooks
+      # @return [Array<Candidate>] the rules to hoist
+      def find_candidates(registry)
+        Hecks::QueryIR.collect_rules(registry)
+                      .select { |r| r.kind == "given" }
+                      .group_by { |r| [r.description, r.canonical, Hecks::QueryIR.owner_of(r.location)] }
+                      .filter_map do |(description, canonical, owner), rules|
+          next if rules.size < 2
+          # An owner-level "(declared)" rule is already hoisted for this owner.
+          next if rules.any? { |r| r.location.end_with?(" (declared)") }
+
+          Candidate.new(description: description, canonical: canonical, owner: owner,
+                        locations: rules.map(&:location))
+        end
+      end
+
+      # The owner's own window: its opening line to the next `end` at the same indentation.
+      # `collect_rules` yields a dotted owner ("Account.LedgerEntry") but the source spells the
+      # bare name, so the last segment is matched; a name that is not unique in the file is
+      # skipped.
+      #
+      # @param text [String] a bluebook's source
+      # @param owner [String] the owner's dotted name
+      # @return [Array(MatchData, Integer), nil] the opening line's match and the closing offset
+      def owner_window(text, owner)
+        bare_name = owner.split(".").last
+        open_re = /^([ \t]*)(?:aggregate|entity)\s+"#{Regexp.escape(bare_name)}"\s+do\n/
+        return nil if text.scan(open_re).size != 1
+
+        open_match = text.match(open_re)
+        indent = open_match[1]
+        close_at = text.index(/^#{indent}end\n/, open_match.end(0))
+        return nil unless close_at
+
+        [open_match, close_at]
+      end
+
+      # Nested entity blocks are carved out of the scan: an entity may declare a `given` with the
+      # same description but a different predicate.
+      #
+      # @param window [String] the owner's source
+      # @return [Array<Array(String, Boolean)>] each stretch of source, and whether it is nested
+      def strip_nested_entities(window)
+        entity_re = /^([ \t]*)entity\s+"[^"]+"\s+do\n/
+        segments  = []
+        pos = 0
+
+        while (m = window.match(entity_re, pos))
+          end_match = window.match(/^#{m[1]}end\n/, m.end(0))
+          break unless end_match
+
+          segments << [window[pos...m.begin(0)], false]
+          segments << [window[m.begin(0)...end_match.end(0)], true]
+          pos = end_match.end(0)
+        end
+        segments << [window[pos..], false]
+        segments
+      end
+
+      # A match needs the predicate to equal the candidate's canonical, not just the description:
+      # the same words can carry a different rule (`disputed_by.status` vs
+      # `account.customer.status`).
+      #
+      # @param predicate_src [String] a `given`'s block source
+      # @param candidate [Candidate] the rule being hoisted
+      # @return [Boolean] whether it is the same rule
+      def matching_occurrence?(predicate_src, candidate)
+        predicate_src.strip == candidate.canonical
+      end
+
+      # @param description [String] a `given`'s description
+      # @return [Regexp] the line that declares it with a block
+      def desc_pattern_for(description)
+        /^([ \t]*)given\(#{Regexp.escape(description.inspect)}\)\s*\{([^\n}]*)\}\n/
+      end
+
+      # @param text [String] a bluebook's source
+      # @param candidate [Candidate] the rule to hoist
+      # @return [Array(String, Boolean)] the new source and whether the rule was hoisted
+      def apply_candidate(text, candidate)
+        bounds = owner_window(text, candidate.owner)
+        return [text, false] unless bounds
+
+        open_match, close_at = bounds
+        window   = text[open_match.end(0)...close_at]
+        segments = strip_nested_entities(window)
+        pattern  = desc_pattern_for(candidate.description)
+
+        outside_matches = segments.flat_map { |seg, nested| nested ? [] : seg.scan(pattern) }
+                                  .select { |_, predicate_src| matching_occurrence?(predicate_src, candidate) }
+        return [text, false] if outside_matches.size < 2
+
+        # Indent one level inside the owner, not as deep as the occurrence in a command block.
+        child_indent = "#{open_match[1]}  "
+        new_given_line = "#{child_indent}given(#{candidate.description.inspect}) { #{candidate.canonical} }\n"
+
+        bare_window = segments.map do |seg, nested|
+          next seg if nested
+
+          seg.gsub(pattern) do
+            indent = Regexp.last_match(1)
+            predicate_src = Regexp.last_match(2)
+            if matching_occurrence?(predicate_src, candidate)
+              "#{indent}given(#{candidate.description.inspect})\n"
+            else
+              Regexp.last_match(0)
+            end
+          end
+        end.join
+
+        new_text = text[0...open_match.end(0)] + new_given_line + bare_window + text[close_at..]
+        [new_text, true]
+      end
+
+      # Every command's effective rule set (block-declared or referenced) must be unchanged.
+      # Owner-level "(declared)" entries are excluded: they are what is meant to differ.
+      #
+      # @param registry [Object] the booted bluebooks
+      # @return [Hash{String => Array}] each command's rules, by location
+      def command_rule_map(registry)
+        Hecks::QueryIR.collect_rules(registry)
+                      .reject { |r| r.location.end_with?(" (declared)") }
+                      .group_by(&:location)
+                      .transform_values { |rules| rules.map { |r| [r.kind, r.description, r.canonical] }.sort }
+      end
+
+      # Kept in one method: `originals` and `before_rules` must be captured before any candidate
+      # is applied, and splitting would mean threading that snapshot through parameters.
+      #
+      # @param files [Array<String>] one example domain's bluebook files
+      # @param dry_run [Boolean] whether to judge the edit in memory and write nothing
+      # @return [Hash] `file`, `status` (`:clean`, `:applied`, `:skipped`), and the candidates
+      # rubocop:disable-next Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+      def run_files(files, dry_run:)
+        files = files.sort
+        originals = files.to_h { |file| [file, File.read(file)] }
+        before_rules = command_rule_map(Hecks::Codemod.load_bluebook(files))
+        candidates = find_candidates(Hecks::Codemod.load_bluebook(files))
+        result_path = files.one? ? files.first : File.dirname(files.first)
+
+        return { file: result_path, status: :clean } if candidates.empty?
+
+        texts = originals.transform_values(&:dup)
+        applied = []
+        candidates.each do |c|
+          target = files.find { |file| apply_candidate(texts[file], c).last }
+          next unless target
+
+          text, changed = apply_candidate(texts[target], c)
+          texts[target] = text
+          applied << c if changed
+        end
+
+        if applied.empty?
+          return { file: result_path, status: :skipped,
+                   reason: "no candidate matched its own source text", candidates: [] }
+        end
+
+        texts.each { |file, text| Hecks::Codemod.stage(file, text, dry_run: dry_run) }
+        after_rules, error = Hecks::Codemod.safely do
+          command_rule_map(Hecks::Codemod.load_bluebook(files))
+        end
+        if dry_run || after_rules != before_rules
+          originals.each { |file, text| Hecks::Codemod.unstage(file, text, dry_run: dry_run) }
+        end
+
+        if after_rules == before_rules
+          { file: result_path, status: :applied, candidates: applied }
+        else
+          reason = if error
+                     "reboot raised after edit (#{error}) — reverted"
+                   else
+                     "a command's own effective rule set changed after edit — reverted"
+                   end
+          { file: result_path, status: :skipped, reason: reason, candidates: applied }
+        end
+      end
+    end
+  end
+end

data/lib/hecks/tools/journal_compaction.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require "hecks"
+require_relative "../tools"
+
+module Hecks
+  module Tools
+    # Compacts a Postgres- or Sqlite-backed aggregate's journal: deletes entries already projected
+    # into its own aggregate table (its own `checkpoint`), so a `:refresh` projection rebuild never
+    # needs them. A `:strict` projection catch-up refuses loudly on its own if it is ever behind
+    # what this deletes (see `Ports::Projection::Worker#catch_up!`).
+    #
+    #   hecks compact <domain> [aggregate_name ...]           # dry run
+    #   hecks compact <domain> [aggregate_name ...] --force   # apply
+    module JournalCompaction
+      module_function
+
+      # Reports, or with `--force` applies, the compaction of each matching aggregate's journal.
+      #
+      # @param argv [Array<String>] the domain directory, aggregate names and `--force`
+      # @param root [String] unused: the domain is read from the path given
+      # @return [Integer] 0, or 1 when the domain directory does not exist
+      def main(argv, **)
+        argv = argv.dup
+        force = argv.delete("--force")
+        domain = argv.shift
+        if domain.nil? || !Dir.exist?(domain)
+          warn "hecks compact: no such domain #{domain.inspect}"
+          warn "usage: hecks compact <domain> [aggregate_name ...] [--force]"
+          return 1
+        end
+        wanted = argv.dup
+
+        registry = Hecks.boot(domain).registry
+        candidates = candidates(registry, wanted)
+        if candidates.empty?
+          puts "hecks compact: no Postgres/Sqlite-backed aggregate matched " \
+               "#{wanted.empty? ? '(any)' : wanted.inspect} in #{domain}"
+          return 0
+        end
+
+        candidates.each { |candidate| compact_candidate(candidate, force: force) }
+        0
+      end
+
+      # @param registry [Hecks::Runtime::Registry] the booted registry
+      # @param wanted [Array<String>] aggregate names, or empty for every aggregate
+      # @return [Array<Hash>] each compactable aggregate and its adapter
+      def candidates(registry, wanted)
+        registry.bluebooks.each_with_object([]) do |(domain_name, bluebook), all|
+          bluebook.aggregates.each do |aggregate|
+            next unless wanted.empty? || wanted.include?(aggregate.hecks_name) || wanted.include?(aggregate.storage_name)
+
+            repository = registry.repository(domain_name, aggregate)
+            next unless repository.is_a?(Hecks::Ports::Persistence::AppendOnly)
+
+            adapter = repository.adapter
+            next unless adapter.respond_to?(:compact_entries!) && adapter.respond_to?(:checkpoint)
+
+            all << { aggregate: aggregate, adapter: adapter }
+          end
+        end
+      end
+
+      # @return [void]
+      def compact_candidate(candidate, force:)
+        aggregate = candidate[:aggregate]
+        adapter   = candidate[:adapter]
+        through   = adapter.checkpoint
+
+        if through <= adapter.compacted_through
+          puts "SKIP #{aggregate.storage_name}: nothing new to compact (already compacted through #{through})"
+          return
+        end
+
+        unless force
+          puts "DRY RUN #{aggregate.storage_name}: would delete journal entries through sequence " \
+               "#{through} (compacted_through is currently #{adapter.compacted_through}); current " \
+               "state (#{adapter.count} records) is unaffected. Re-run with --force to apply."
+          return
+        end
+
+        removed = adapter.compact_entries!(through: through)
+        puts "COMPACTED #{aggregate.storage_name}: deleted #{removed} journal entries through " \
+             "sequence #{through}; #{adapter.count} records preserved"
+      end
+    end
+  end
+end

data/lib/hecks/tools/oidc_manifests.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "hecks"
+require_relative "../tools"
+
+module Hecks
+  module Tools
+    # Projects each domain's OIDC client and scope manifest (`Hecks::Projections::OIDC`) into an
+    # `oidc.json` beside the domain.
+    #
+    # A domain that has no bluebook is skipped and one that cannot be projected is reported, so a
+    # sweep over the whole checkout carries on past either. `hecks deploy project_oidc` loads
+    # `bundler/setup` first, which pins the `json` gem: newer releases pretty-print an empty array
+    # as `[\n\n]`, a diff spec/oidc_manifest_spec.rb would report as drift.
+    module OidcManifests
+      # Directories that hold a `.hecksagon` but are never domains.
+      NOT_DOMAINS = %r{\A(rust|deploy|tmp|coverage)/}
+
+      module_function
+
+      # Projects the manifests and prints one line for each domain.
+      #
+      # @param argv [Array<String>] domain directories, relative to `root`; every domain of the
+      #   checkout when empty
+      # @param root [String] the checkout
+      # @return [Integer] 0
+      def main(argv, root: Tools::ROOT)
+        wanted = argv.empty? ? domains(root) : argv.map { |path| path.delete_prefix("#{root}/").chomp("/") }
+        wanted.each { |path| project(root, path) }
+        0
+      end
+
+      # Every `.hecksagon` names a domain root; rust/, deploy/, tmp/ and coverage/ are never
+      # domains.
+      #
+      # @param root [String] the checkout
+      # @return [Array<String>] the domain directories, relative to `root`, sorted
+      def domains(root)
+        folder = Hecks::Adapters::Folder.new
+        Dir.glob(File.join(root, "**/*.hecksagon"))
+           .map { |path| folder.domain_root(File.dirname(path)) }
+           .compact
+           .map { |path| path.delete_prefix("#{root}/") }
+           .grep_v(NOT_DOMAINS)
+           .uniq.sort
+      end
+
+      # @param root [String] the checkout
+      # @param path [String] a domain directory, relative to `root`
+      # @return [void]
+      def project(root, path)
+        runtime = Hecks.boot(File.join(root, path), install_doors: false)
+        name    = runtime.registry.bluebooks.keys.first
+
+        unless name
+          warn "  #{path}: no bluebook found — skipped"
+          return
+        end
+
+        bluebook = runtime.registry.bluebook(name)
+        out      = File.join(root, path, "oidc.json")
+
+        Hecks::Projector.write(Hecks::Projector.call(:oidc, bluebook: bluebook), out)
+        puts "  #{path}/oidc.json  <-  #{name}"
+      rescue StandardError => e
+        warn "  #{path}: cannot project — #{e.message.lines.first.strip}"
+      end
+    end
+  end
+end

data/lib/hecks/tools/query_ir_run.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require_relative "../tools"
+
+module Hecks
+  module Tools
+    # Structured queries against the language's own IR: construct diffs, duplicate rules, impact.
+    # A thin front end over `Hecks::QueryIR`, which `hecks serve_query_ir_mcp` shares; needs no
+    # Postgres.
+    #
+    #   hecks query_ir constructs [Name ...]
+    #   hecks query_ir duplicates [--meta] [domain_dir ...]
+    #   hecks query_ir impact Name field     (advisory, not a gate)
+    module QueryIrRun
+      USAGE = <<~USAGE
+        Usage:
+          hecks query_ir constructs [Name ...]
+          hecks query_ir duplicates [--meta] [domain_dir ...]
+          hecks query_ir impact Name field
+      USAGE
+
+      module_function
+
+      # Prints the answer to one query.
+      #
+      # @param argv [Array<String>] `constructs`, `duplicates` or `impact`, then its arguments
+      # @param root [String] the checkout (unused: the queries read the loaded language)
+      # @return [Integer] 0, or 1 when the arguments are refused
+      def main(argv, root: Tools::ROOT)
+        _ = root
+        require "hecks"
+        require "hecks/query_ir"
+        args = argv.dup
+        case args.shift
+        when "constructs" then constructs(args)
+        when "duplicates" then duplicates(args)
+        when "impact"     then impact(args)
+        else
+          warn USAGE
+          1
+        end
+      end
+
+      # @param args [Array<String>] construct names, none for all
+      # @return [Integer] the exit status
+      def constructs(args)
+        puts Hecks::QueryIR.format_constructs(Hecks::QueryIR.constructs(args))
+        0
+      rescue ArgumentError => e
+        warn e.message
+        1
+      end
+
+      # @param args [Array<String>] `--meta` and domain directories
+      # @return [Integer] the exit status
+      def duplicates(args)
+        use_meta = args.delete("--meta") || args.empty?
+        domains  = args.empty? ? nil : args
+
+        puts Hecks::QueryIR.format_duplicates(Hecks::QueryIR.duplicates(domains: domains, include_meta: use_meta))
+        0
+      end
+
+      # @param args [Array<String>] a construct's name and a field's
+      # @return [Integer] the exit status
+      def impact(args)
+        name, field = args
+        unless name && field
+          warn "usage: hecks query_ir impact Name field"
+          return 1
+        end
+
+        puts Hecks::QueryIR.format_impact_preview(Hecks::QueryIR.impact_preview(name, field))
+        0
+      rescue ArgumentError => e
+        warn e.message
+        1
+      end
+    end
+  end
+end

data/lib/hecks/tools/regeneration_run.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "open3"
+require "tmpdir"
+require_relative "../tools"
+require_relative "../corpus"
+
+module Hecks
+  module Tools
+    # Regenerates every corpus domain's committed Rust output with `hecks project_rust`, or checks
+    # that the committed output is what a regeneration would write.
+    #
+    # The domain list comes from `Hecks::Corpus.rust_regen_order`, never a hand-kept list. The
+    # order is fixed (sorted by relative path): domains that share governance/, identity/,
+    # Cargo.toml and generated/mod.rs stamp them with whichever ran last, so it must not flap. If
+    # the domain set or the sort rule changes, re-run and commit the output; never hand-edit stamps.
+    #
+    #   hecks regenerate_corpus         # discover, regenerate, print the plan
+    #   hecks regenerate_corpus --check # regenerate into a scratch crate; fail on any difference
+    #
+    # `--check` never writes the working tree: it runs beside the parallel suite.
+    module RegenerationRun
+      module_function
+
+      # Regenerates the corpus, or checks it.
+      #
+      # @param argv [Array<String>] `--check` to project into a scratch crate and compare
+      # @param root [String] the checkout
+      # @return [Integer] 0, or 1 when a check finds a difference
+      # @raise [SystemExit] when no corpus domain is found or a domain fails to regenerate
+      def main(argv, root: Tools::ROOT)
+        Dir.chdir(root) do
+          domains = plan(root)
+          # A check projects into a scratch copy of the crate; the forked children inherit
+          # HECKS_RUST_DIR.
+          scratch = argv.include?("--check") && scratch_crate(root)
+          saved = ENV.fetch("HECKS_RUST_DIR", nil)
+          ENV["HECKS_RUST_DIR"] = scratch if scratch
+          begin
+            begin
+              regenerate(domains)
+            ensure
+              saved ? ENV["HECKS_RUST_DIR"] = saved : ENV.delete("HECKS_RUST_DIR")
+            end
+            scratch ? verdict(scratch) : 0
+          ensure
+            FileUtils.rm_rf(scratch) if scratch
+          end
+        end
+      end
+
+      # `meta` is never in the list: `Hecks::Corpus::RUST_ELSEWHERE` routes it to the check that
+      # owns it instead.
+      #
+      # @param root [String] the checkout
+      # @return [Array<String>] the domains to regenerate, relative to `root`, in run order
+      # @raise [SystemExit] when there are none
+      def plan(root)
+        domains = Hecks::Corpus.rust_regen_order.map { |domain| domain.dir.delete_prefix("#{root}/") }
+
+        if domains.empty?
+          abort "hecks regenerate_corpus: discovered ZERO domains with committed rust/src/generated/ " \
+                "output in Hecks::Corpus — that almost certainly means this script is running from the " \
+                "wrong directory, or something upstream deleted rust/src/generated/ entirely. Refusing " \
+                "to silently treat that as \"nothing to regenerate.\""
+        end
+
+        puts "hecks regenerate_corpus: regenerating #{domains.size} domain(s), in this fixed order:"
+        domains.each { |d| puts "  #{d}" }
+        puts
+        domains
+      end
+
+      # Builds the memoized grammar registry once and forks for each domain, one at a time and in
+      # order, because the shared outputs depend on which domain ran last.
+      #
+      # @param domains [Array<String>] the domains, in run order
+      # @return [void]
+      def regenerate(domains)
+        require "hecks"
+        require "hecks/bluebook/meta_validator"
+        require "hecks/rust_build"
+        Hecks::Bluebook::MetaValidator.grammar_registry
+        domains.each { |domain| project_rust_in_fork(domain) }
+      end
+
+      # Forks so the child inherits the memoized grammar registry instead of rebuilding it. The
+      # child's output goes through a pipe and is printed here, so it reaches whoever captures this
+      # process's stdout.
+      #
+      # @param domain [String] the domain, relative to the checkout
+      # @return [void]
+      # @raise [SystemExit] when the child fails
+      def project_rust_in_fork(domain)
+        puts "== hecks project_rust #{domain} =="
+        reader, writer = IO.pipe
+        pid = fork { run_child(reader, writer, domain) }
+        writer.close
+        $stdout.write(reader.read)
+        reader.close
+        _, status = Process.wait2(pid)
+        abort "hecks regenerate_corpus: hecks project_rust #{domain} failed (#{status.inspect})" unless status.success?
+        puts
+      end
+
+      # @param reader [IO] the parent's end of the pipe, closed here
+      # @param writer [IO] the child's end, which becomes its stdout and stderr
+      # @param domain [String] the domain
+      # @return [void] never returns: the child leaves without the parent's exit handlers
+      def run_child(reader, writer, domain)
+        reader.close
+        # The real descriptors, not the globals: a caller may have swapped those for a buffer.
+        STDOUT.reopen(writer) # rubocop:disable Style/GlobalStdStream
+        STDERR.reopen(writer) # rubocop:disable Style/GlobalStdStream
+        $stdout = STDOUT
+        $stderr = STDERR
+        status = begin
+          Hecks::RustBuild.run("project_rust", [domain], out: STDOUT, err: STDERR) # rubocop:disable Style/GlobalStdStream
+        rescue SystemExit => e
+          e.status
+        rescue StandardError => e
+          warn "#{e.class}: #{e.message}"
+          1
+        end
+        $stdout.flush
+        exit!(status)
+      end
+
+      # A scratch crate: copies of the generated tree and Cargo.toml, all `hecks project_rust`
+      # writes.
+      #
+      # @param root [String] the checkout
+      # @return [String] the scratch directory
+      def scratch_crate(root)
+        scratch = Dir.mktmpdir("regen-codegen-check")
+        FileUtils.mkdir_p(File.join(scratch, "src"))
+        FileUtils.cp_r(File.join(root, "rust/src/generated"), File.join(scratch, "src/generated"))
+        FileUtils.cp(File.join(root, "rust/Cargo.toml"), scratch)
+        scratch
+      end
+
+      # The gate: the scratch projection must match the generated sources and Cargo.toml on disk.
+      #
+      # @param scratch [String] the scratch crate, removed here
+      # @return [Integer] 0 when it matches, 1 after printing the difference
+      def verdict(scratch)
+        same = matches_scratch?(scratch)
+        FileUtils.rm_rf(scratch)
+        same ? 0 : 1
+      end
+
+      # @param scratch [String] the scratch crate
+      # @return [Boolean] whether it matches the tree, printing `git diff` output when it does not
+      def matches_scratch?(scratch)
+        pairs = [["rust/src/generated", File.join(scratch, "src/generated")],
+                 ["rust/Cargo.toml", File.join(scratch, "Cargo.toml")]]
+        pairs.map do |on_disk, projected|
+          out, status = Open3.capture2e("git", "diff", "--no-index", "--exit-code", "--", on_disk, projected)
+          print out
+          status.success?
+        end.all?
+      end
+    end
+  end
+end