hecks 4.0.0 → 6.0.0

data/lib/hecks/rust_build/wasm.rb

@@ -3,6 +3,7 @@
 require "fileutils"
 require_relative "../rust_build"
 require_relative "project_rust"
+require_relative "command_schemas"
 
 module Hecks
   module RustBuild
@@ -15,7 +16,7 @@ module Hecks
     # `wasmtime run rust/dist/<domain>.wasm < script.json`, and the domain's `ir.json` beside it,
     # which `rust/host` reads at runtime. `HECKS_RUST_DIR` names the workspace to build in and
     # `CARGO_TARGET_DIR` where build output goes, beside the workspace by default.
-    # `HECKS_WASM_PROFILE=dev` builds without `--release`: a much faster compile, for tests that
+    # `--profile=dev` builds without `--release`: a much faster compile, for tests that
     # only run the module, not for one that ships.
     module Wasm
       # The Cargo target the module is built for.
@@ -26,25 +27,43 @@ module Hecks
 
       module_function
 
-      # @param argv [Array<String>] the domain's directory
+      # @param argv [Array<String>] the domain's directory, then an optional `--profile=release|dev`
       # @return [Integer] the exit status
-      # @raise [Failure] when the target is not installed or a step fails
+      # @raise [Failure] when the target is not installed, the profile is unknown or a step fails
       def call(argv)
-        domain = argv.first or raise Failure, "usage: hecks build_wasm <domain>"
+        domain = argv.find { |arg| !arg.start_with?("--") } or raise Failure, "usage: hecks build_wasm <domain>"
+        name = profile_name(argv)
+        profile(name)
 
         require_target!
         rust_dir = RustBuild.rust_dir
         scratch = scratch_copy(rust_dir)
         regenerate(scratch, domain)
-        compile(scratch)
-        publish(scratch, rust_dir, File.basename(domain))
+        compile(scratch, name)
+        publish(scratch, rust_dir, File.basename(domain), name)
         0
       end
 
+      # @param argv [Array<String>] the tool's arguments
+      # @return [String] the `--profile=<name>` value, `release` when none is named
+      def profile_name(argv)
+        argv.filter_map { |arg| arg.delete_prefix("--profile=") if arg.start_with?("--profile=") }.last || "release"
+      end
+
       def regenerate(scratch, domain)
         puts "== regenerating #{scratch}/src/generated/ for #{domain} =="
-        status = RustBuild.with_env("HECKS_RUST_DIR" => scratch) { ProjectRust.call([domain]) }
+        status = RustBuild.in_workspace(scratch) { ProjectRust.call([domain]) }
         raise Failure, "project_rust failed for #{domain}" unless status.zero?
+
+        write_schemas(scratch, domain)
+      end
+
+      # The command schemas go into the scratch copy only: they are a build output for the host to
+      # serve, not part of the generated corpus the drift check holds to the tree.
+      def write_schemas(scratch, domain)
+        loader = ProjectRust::DomainLoader.new(domain).call
+        CommandSchemas.write(loader.registry.bluebook(loader.domain_name),
+                             File.join(scratch, "src", "generated", File.basename(domain)))
       end
 
       def require_target!
@@ -62,40 +81,40 @@ module Hecks
       # Built in a scratch copy because generating rewrites `Cargo.toml` and `src/generated/`,
       # which would dirty tracked files in a checkout.
       def scratch_copy(rust_dir, name = "project_wasm")
-        scratch = if ENV.key?("HECKS_RUST_DIR")
+        scratch = if RustBuild.explicit_workspace?
                     File.join(rust_dir, "scratch", name)
                   else
                     File.join(ROOT, "tmp", name, "rust")
                   end
         FileUtils.rm_rf(scratch)
         FileUtils.mkdir_p(scratch)
-        %w[Cargo.toml Cargo.lock src].each { |entry| FileUtils.cp_r(File.join(rust_dir, entry), scratch) }
+        %w[Cargo.toml Cargo.lock src expr].each { |entry| FileUtils.cp_r(File.join(rust_dir, entry), scratch) }
         scratch
       end
 
       # `rustup run`, not bare `cargo`: a `cargo` earlier on PATH may never have seen
       # `rustup target add` and fail with "can't find crate for `std`".
-      def compile(scratch)
-        flags = profile.fetch(:flags)
+      def compile(scratch, profile_name = "release")
+        flags = profile(profile_name).fetch(:flags)
         puts "== cargo build #{flags.join(" ")} --target #{TARGET} =="
         target_dir = ENV.fetch("CARGO_TARGET_DIR", File.join(RustBuild.rust_dir, "target"))
         RustBuild.command!("rustup", "run", "stable", "cargo", "build", *flags, "--target", TARGET,
                            chdir: scratch, env: { "CARGO_TARGET_DIR" => target_dir })
       end
 
-      # @return [Hash] the flags and directory of the profile `HECKS_WASM_PROFILE` names
+      # @param name [String] `release` or `dev`
+      # @return [Hash] the flags and directory of the profile
       # @raise [Failure] when the name is not `release` or `dev`
-      def profile
-        name = ENV.fetch("HECKS_WASM_PROFILE", "release")
-        PROFILES.fetch(name) { raise Failure, "HECKS_WASM_PROFILE=#{name} is not release or dev" }
+      def profile(name = "release")
+        PROFILES.fetch(name) { raise Failure, "--profile=#{name} is not release or dev" }
       end
 
-      def publish(scratch, rust_dir, name)
+      def publish(scratch, rust_dir, name, profile_name = "release")
         dist = File.join(rust_dir, "dist")
         FileUtils.mkdir_p(dist)
         target_dir = ENV.fetch("CARGO_TARGET_DIR", File.join(rust_dir, "target"))
         out = File.join(dist, "#{name}.wasm")
-        FileUtils.cp(File.join(target_dir, TARGET, profile.fetch(:dir), "rust.wasm"), out)
+        FileUtils.cp(File.join(target_dir, TARGET, profile(profile_name).fetch(:dir), "rust.wasm"), out)
         puts "wrote #{out}"
         puts %(run it: wasmtime run #{out} < script.json)
         publish_sidecar(scratch, dist, name)
@@ -107,6 +126,16 @@ module Hecks
 
         FileUtils.cp(sidecar, File.join(dist, "#{name}.ir.json"))
         puts "wrote #{File.join(dist, "#{name}.ir.json")}"
+        publish_schemas(scratch, dist, name)
+      end
+
+      # The command schemas beside the IR, which the host serves at a command's `?schema=1`.
+      def publish_schemas(scratch, dist, name)
+        schemas = File.join(scratch, "src", "generated", name, "schemas.json")
+        return unless File.exist?(schemas)
+
+        FileUtils.cp(schemas, File.join(dist, "#{name}.schemas.json"))
+        puts "wrote #{File.join(dist, "#{name}.schemas.json")}"
       end
     end
   end

data/lib/hecks/rust_build/wasm_browser.rb

@@ -19,6 +19,12 @@ module Hecks
       # The Cargo target the module is built for.
       TARGET = "wasm32-unknown-unknown"
 
+      # The exact wasm-bindgen pin in a Cargo manifest, capturing the version.
+      BINDGEN_PIN = /^wasm-bindgen = "=(.+)"/
+
+      # A dotted version number, as `wasm-bindgen --version` prints it.
+      VERSION_NUMBER = /[\d.]+/
+
       module_function
 
       # @param argv [Array<String>] the domain's directory
@@ -66,9 +72,9 @@ module Hecks
       # The wasm-bindgen CLI must match the crate version pinned in `rust/web/Cargo.toml`; a
       # mismatch fails only when the CLI runs, so the pin is read back, not hardcoded.
       def require_cli!(web_dir)
-        pinned = File.read(File.join(web_dir, "Cargo.toml"))[/^wasm-bindgen = "=(.+)"/, 1] or
+        pinned = File.read(File.join(web_dir, "Cargo.toml"))[BINDGEN_PIN, 1] or
           raise Failure, "rust/web/Cargo.toml: couldn't find a pinned (\"=x.y.z\") wasm-bindgen version"
-        installed = `wasm-bindgen --version 2>/dev/null`[/[\d.]+/]
+        installed = `wasm-bindgen --version 2>/dev/null`[VERSION_NUMBER]
         return if installed == pinned
 
         raise Failure, <<~MSG

data/lib/hecks/rust_build.rb

@@ -43,11 +43,36 @@ module Hecks
     LOCK = Hecks::Adapters::ConsoleCapture::LOCK
     private_constant :LOCK
 
+    # The fiber-local key holding the workspace `in_workspace` chose.
+    WORKSPACE_KEY = :hecks_rust_build_workspace
+    private_constant :WORKSPACE_KEY
+
     class << self
-      # The workspace tools build in: `HECKS_RUST_DIR`, or the gem's own `rust/`.
+      # The workspace tools build in: the one `in_workspace` names, else `HECKS_RUST_DIR`, else the
+      # gem's own `rust/`.
       #
       # @return [String] the directory
-      def rust_dir = ENV.fetch("HECKS_RUST_DIR", File.join(ROOT, "rust"))
+      def rust_dir = workspace || ENV.fetch("HECKS_RUST_DIR", File.join(ROOT, "rust"))
+
+      # Whether a caller chose the workspace, by `in_workspace` or by `HECKS_RUST_DIR`, rather than
+      # the gem's own `rust/` being the default.
+      #
+      # @return [Boolean]
+      def explicit_workspace? = !workspace.nil? || ENV.key?("HECKS_RUST_DIR")
+
+      # Builds in `dir` for the block. A tool run in this process, or in a process forked from
+      # it, reads the workspace from here, so no environment variable carries it.
+      #
+      # @param dir [String] the workspace
+      # @yield the work to do in it
+      # @return [Object] the block's value
+      def in_workspace(dir)
+        saved = workspace
+        Thread.current[WORKSPACE_KEY] = dir
+        yield
+      ensure
+        Thread.current[WORKSPACE_KEY] = saved
+      end
 
       # Runs a tool with the given environment, writing to the given streams.
       #
@@ -129,6 +154,8 @@ module Hecks
 
       private
 
+      def workspace = Thread.current[WORKSPACE_KEY]
+
       def with_streams(out, err)
         saved = [$stdout, $stderr]
         $stdout = out

data/lib/hecks/sentence_form.rb

@@ -0,0 +1,212 @@
+require "digest"
+require "fileutils"
+require "open3"
+require_relative "cache_dir"
+
+module Hecks
+  # A `.bluebook` written as plain sentences (its first line is `Domain: <name>`) rather than in
+  # the Ruby form. The Rust parser is the one reader of the sentences: it renders them as the
+  # Ruby-shaped text that declares the same bluebook, and Ruby evaluates that text under the
+  # sentence file's own path, so the registry records the file the author wrote.
+  module SentenceForm
+    # The repository root, where the parser's build lands under `rust/parser/target/`.
+    ROOT = File.expand_path("../..", __dir__).freeze
+
+    # The line a sentence-form file opens with, after any blank or comment lines.
+    DOMAIN_LINE = /\A\s*Domain:/
+
+    # The first line of a tool's output, without its newline.
+    FIRST_LINE = /\A[^\n]*/
+
+    # A `Hecks.bluebook "Name"` header line, or a `Domain: name` line, capturing the bluebook's
+    # name.
+    BLUEBOOK_HEADER = /\A\s*(?:Hecks\.bluebook\s+"([^"]+)"|Domain:\s*(\S.*?)\s*\z)/
+
+    # Raised when no `hecks-parse` binary can be found.
+    class ParserMissing < StandardError; end
+
+    # Raised when the parser refuses a sentence file; the message is its diagnostic.
+    class Refused < StandardError; end
+
+    module_function
+
+    # @param path [String] a `.bluebook` file
+    # @return [Boolean] whether the file is written as sentences
+    def sentences?(path)
+      first = File.foreach(path).find { |line| !line.strip.empty? && !line.lstrip.start_with?("#") }
+      !first.nil? && first.match?(DOMAIN_LINE)
+    end
+
+    # @param path [String] a bluebook file, in either form
+    # @return [String, nil] the bluebook name its header declares; a `Domain:` line is read as
+    #   the words capitalised and joined, as the parser reads it
+    def declaration_name(path)
+      File.foreach(path) do |line|
+        next unless line =~ BLUEBOOK_HEADER
+
+        return Regexp.last_match(1) || capitalised(Regexp.last_match(2))
+      end
+      nil
+    end
+
+    # @param words [String] the words of a `Domain:` line
+    # @return [String] each word capitalised and the words joined, as the parser reads them
+    def capitalised(words) = words.split.map { |word| word[0].upcase + word[1..] }.join
+
+    # @param text [String] a tool's error output
+    # @return [String] its first line, without the newline
+    def first_line(text) = text.to_s[FIRST_LINE]
+
+    # The Ruby-shaped text of a sentence-form file.
+    #
+    # @param path [String] a sentence-form `.bluebook`
+    # @return [String] Ruby source declaring the same bluebook
+    # @raise [ParserMissing] if `hecks-parse` is not built
+    # @raise [Refused] if the sentences are not ones the parser knows
+    def ruby_text(path)
+      declaration = declaration_name(path) or raise Refused, "#{path}: no `Domain:` line to name the bluebook"
+      out, err, status = Open3.capture3(binary, "render", "--bluebook", declaration, path)
+      raise Refused, first_line(err) unless status.success?
+
+      out
+    end
+
+    # The extension of an examples file: sentences saying who does what to the domain and what
+    # follows, which the behaviors runner runs.
+    EXAMPLES_EXTENSION = ".examples".freeze
+
+    # The first line of an examples file, naming the bluebook the examples are about.
+    EXAMPLES_LINE = /\A\s*Examples for:\s*(\S.*?)\s*\z/
+
+    # @param path [String] a file the behaviors runner was asked to run
+    # @return [Boolean] whether it is an examples file, not a `.behaviors` file
+    def examples?(path) = path.to_s.end_with?(EXAMPLES_EXTENSION)
+
+    # The `.behaviors` text that runs an examples file against its bluebook.
+    #
+    # The bluebook's files are the `.bluebook` beside the examples file with the same stem or, when
+    # there is none, every `.bluebook` there (or in a `bluebook/` folder there) that declares the
+    # bluebook the examples are about.
+    #
+    # @param path [String] an examples file
+    # @return [String] `.behaviors` source
+    # @raise [ParserMissing] if `hecks-parse` is not built
+    # @raise [Refused] if no bluebook file is found or the examples are not ones the parser accepts
+    def behaviors_text(path)
+      declaration = examples_bluebook(path)
+      files = bluebook_files(path, declaration)
+      raise Refused, "#{path}: no .bluebook beside it declares #{declaration}" if files.empty?
+
+      wiring = behaviors_hecksagon(path)
+      also = wiring ? ["--also", wiring] : []
+      out, err, status = Open3.capture3(binary, "examples", "--bluebook", declaration, "--examples", path, *also, *files)
+      raise Refused, first_line(err) unless status.success?
+
+      out
+    end
+
+    # Writes the `.behaviors` text of an examples file where the runner can load it.
+    #
+    # @param path [String] an examples file
+    # @return [String] the generated `.behaviors` file's path
+    def write_behaviors(path)
+      text = behaviors_text(path)
+      dir = CacheDir.path("sentence_form")
+      FileUtils.mkdir_p(dir)
+      generated = File.join(dir, "#{File.basename(path, EXAMPLES_EXTENSION)}-#{Digest::SHA256.hexdigest(text)[0, 16]}.behaviors")
+      File.write(generated, text) unless File.exist?(generated)
+      generated
+    end
+
+    # The Memory-bound hecksagon that answers a bluebook's asks while its examples run: the
+    # `<name>_behaviors.hecksagon` beside the examples file, as Pizzas keeps one beside its own.
+    #
+    # @param path [String] an examples file
+    # @return [String, nil] its absolute path, or nil when there is none
+    def behaviors_hecksagon(path)
+      wiring = File.join(File.dirname(File.expand_path(path)), "#{File.basename(path, EXAMPLES_EXTENSION)}_behaviors.hecksagon")
+      wiring if File.file?(wiring)
+    end
+
+    # @return [String] the bluebook an examples file's first line names, capitalised and joined
+    def examples_bluebook(path)
+      line = File.foreach(path).find { |text| text.match?(EXAMPLES_LINE) }
+      raise Refused, "#{path}: no `Examples for: <bluebook>` line" unless line
+
+      line.match(EXAMPLES_LINE)[1].split.map { |word| word[0].upcase + word[1..] }.join
+    end
+
+    # @return [Array<String>] absolute paths of the `.bluebook` files the examples are about
+    def bluebook_files(path, declaration)
+      dir = File.dirname(File.expand_path(path))
+      same_stem = File.join(dir, "#{File.basename(path, EXAMPLES_EXTENSION)}.bluebook")
+      return [same_stem] if File.file?(same_stem)
+
+      Dir.glob([File.join(dir, "*.bluebook"), File.join(dir, "bluebook", "*.bluebook")])
+         .select { |file| declaration_name(file) == declaration }
+    end
+
+    # Loads a bluebook file in whichever form it is written: sentences through the parser, anything
+    # else as Ruby. Every place that reads a `.bluebook` goes through here, so no boot path accepts
+    # one form and refuses the other.
+    #
+    # @param path [String] a bluebook file, or any other Ruby file
+    # @return [void]
+    def load_file(path)
+      sentences = path.end_with?(".bluebook") && File.file?(path) && sentences?(path)
+      sentences ? load(path) : Kernel.load(path)
+    end
+
+    # Declares the bluebook a sentence-form file holds, in the registry now current.
+    #
+    # The Ruby text is loaded from a file of its own, because a predicate's source is recovered
+    # from the file it was written in; the registry then records the sentence file as the
+    # bluebook's source, not the generated one.
+    #
+    # @param path [String] a sentence-form `.bluebook`
+    # @return [void]
+    def load(path)
+      generated = write_generated(path, ruby_text(path))
+      Kernel.load(generated)
+      point_sources_at(generated, path)
+    end
+
+    # Makes the registry record the sentence file `path` as the source of what `generated` declared.
+    #
+    # @param generated [String] the rendered file that was loaded
+    # @param path [String] the sentence file it came from
+    # @return [void]
+    def point_sources_at(generated, path)
+      registry = Hecks.current_registry
+      registry.bluebook_sources.each_value do |paths|
+        paths.map! { |source| source == generated ? path : source }
+      end
+    end
+
+    # Writes rendered text where Ruby can load it, named by what the text holds so an unchanged
+    # file is written once.
+    #
+    # @param path [String] the sentence file the text was rendered from
+    # @param text [String] the rendered Ruby text
+    # @return [String] the generated file's path
+    def write_generated(path, text)
+      dir = CacheDir.path("sentence_form")
+      FileUtils.mkdir_p(dir)
+      generated = File.join(dir, "#{File.basename(path, ".bluebook")}-#{Digest::SHA256.hexdigest(text)[0, 16]}.bluebook")
+      File.write(generated, text) unless File.exist?(generated)
+      generated
+    end
+
+    # @return [String] the path to `hecks-parse`: `HECKS_PARSE_BIN`, then the release or debug
+    #   build under `rust/parser/target/`, then one on the `PATH`
+    # @raise [ParserMissing] if none exists
+    def binary
+      candidates = [ENV.fetch("HECKS_PARSE_BIN", nil)] +
+                   %w[release debug].map { |profile| File.join(ROOT, "rust/parser/target/#{profile}/hecks-parse") } +
+                   ENV.fetch("PATH", "").split(File::PATH_SEPARATOR).map { |dir| File.join(dir, "hecks-parse") }
+      candidates.compact.find { |path| File.executable?(path) && !File.directory?(path) } or
+        raise ParserMissing, "hecks-parse is not built — run `cargo build --release " \
+                             "--manifest-path rust/parser/Cargo.toml`, or set HECKS_PARSE_BIN"
+    end
+  end
+end

data/lib/hecks/served_options.rb

@@ -1,4 +1,5 @@
 require "rack"
+require_relative "naming"
 
 module Hecks
   # What a domain's world file says it is served by: each `served_by("Adapter") { ... }` line
@@ -48,6 +49,6 @@ module Hecks
       env.fetch(name) { raise ArgumentError, "#{entry[:adapter]}: environment variable #{name} is not set" }
     end
 
-    def snake(name) = name.to_s.gsub(/([a-z\d])([A-Z])/, '\1_\2').downcase
+    def snake(name) = name.to_s.gsub(Naming::CAMEL_BOUNDARY, '\1_\2').downcase
   end
 end

data/lib/hecks/shape_ledger.rb

@@ -0,0 +1,149 @@
+require "fileutils"
+require "json"
+require "hecks"
+
+module Hecks
+  # The committed record of each bluebook's storage shape, held against the shapes the bluebooks
+  # have now, so a shape cannot change without the translation edge that carries a database across.
+  #
+  # A database that holds an era refuses a newer shape no edge leads to. The check that catches
+  # that at a boot only runs against a real database, which specs and gates do not use, so this one
+  # reads nothing but the loaded bluebooks and the committed edges: it needs no database.
+  #
+  # @example
+  #   ShapeLedger.check("lib/hecks/hecks")  # => "15 bluebook shapes, each the one the ledger holds"
+  module ShapeLedger
+    # The ledger file, beside the bluebooks it records.
+    FILE = "shapes.json".freeze
+
+    # The length of the label a translation edge names a shape by.
+    LABEL = 6
+
+    # What a problem line tells the reader to do.
+    REWRITE = "rewrite the ledger with `hecks conformance_run.check_shape_ledger --confirm --wait`".freeze
+
+    # Raised with every problem found, or when the ledger cannot be rewritten.
+    class Failure < StandardError; end
+
+    module_function
+
+    # Compares the ledger with the shapes of the bluebooks under a directory.
+    #
+    # @param directory [String] the domain directory whose bluebooks the ledger records
+    # @param confirm [Boolean] rewrite the ledger when every moved shape has an edge
+    # @param additive [Boolean] with `confirm`, write the empty edge for each shape that moved with
+    #   none, on the operator's word that the change only adds; the mint audits every edge against
+    #   the records it migrates and refuses one that would lose data
+    # @return [String] the clean verdict, or what was written
+    # @raise [Failure] with each problem
+    def check(directory, confirm: false, additive: false)
+      registry = Hecks.describe(directory).registry
+      shapes = shapes_of(registry)
+      edges = edges_of(registry)
+      path = File.join(directory, FILE)
+      confirm ? rewrite(path, shapes, edges, directory, additive) : verdict(path, shapes, edges)
+    end
+
+    # @param registry [Runtime::Registry] the loaded bluebooks
+    # @return [Hash{String => String}] each bluebook's storage-shape hash, by name
+    def shapes_of(registry)
+      registry.bluebooks.to_h { |name, bluebook| [name, Runtime::StorageShape.mint_hash(bluebook)] }
+    end
+
+    # @param registry [Runtime::Registry] the loaded bluebooks
+    # @return [Hash{String => Array<Array(String, String)>}] each bluebook's edges as `[from, to]`
+    def edges_of(registry)
+      registry.translations.group_by(&:domain).transform_values { |edges| pairs(edges) }
+    end
+
+    def pairs(edges) = edges.map { |edge| [edge.from, edge.to] }
+
+    def label(hash) = hash.to_s[0, LABEL]
+
+    # @return [Boolean] whether a chain of edges leads from one label to another
+    def reachable?(from, to, edges)
+      seen = [from]
+      queue = [from]
+      queue.concat(next_labels(queue.shift, edges, seen)) until queue.empty? || seen.include?(to)
+      seen.include?(to)
+    end
+
+    def next_labels(at, edges, seen)
+      fresh = edges.filter_map { |from, to| to if from == at && !seen.include?(to) }
+      seen.concat(fresh)
+      fresh
+    end
+
+    def verdict(path, shapes, edges)
+      problems = problems(read(path), shapes, edges)
+      raise Failure, problems.join("\n") unless problems.empty?
+
+      "#{shapes.size} bluebook shapes, each the one the ledger holds"
+    end
+
+    # @return [Array<String>] one line per bluebook whose shape disagrees with the ledger
+    def problems(ledger, shapes, edges)
+      moved = shapes.filter_map { |name, now| problem(name, ledger[name], now, edges.fetch(name, [])) }
+      moved + (ledger.keys - shapes.keys).map { |name| "#{name}: in the ledger but no longer loaded; #{REWRITE}" }
+    end
+
+    def problem(name, held, now, edges)
+      return "#{name}: not in the ledger (shape #{label(now)}); #{REWRITE}" unless held
+      return nil if label(held) == label(now)
+
+      change = "#{name}: the shape moved #{label(held)} -> #{label(now)}"
+      return "#{change}, and an edge covers it; #{REWRITE}" if reachable?(label(held), label(now), edges)
+
+      "#{change} with no translation edge from #{label(held)}; #{edge_advice(name, label(held), label(now))}"
+    end
+
+    # What to commit: the empty edge covers a change that only adds, and a change that renames or
+    # reshapes data needs the rules the scaffold writes from the database that holds the eras.
+    def edge_advice(name, from, now)
+      edge = %(Hecks.data_translation "#{name}", from: "#{from}", to: "#{now}" do end)
+      "for a change that only adds, commit this edge under translations/ (as 2-#{now}.bluebook): #{edge}. " \
+        "Data that is renamed or reshaped needs rules: `hecks query era.scaffold_translation " \
+        "domain.value=<directory>` writes them, reading the eras from the database the domain's " \
+        "own world names. A change that only adds is settled in one step " \
+        "by `hecks conformance_run.check_shape_ledger --confirm --additive --wait`"
+    end
+
+    def rewrite(path, shapes, edges, directory, additive)
+      ledger = read(path)
+      written = additive ? write_edges(directory, uncovered_moves(ledger, shapes, edges)) : []
+      uncovered = additive ? [] : problems(ledger, shapes, edges).reject { |line| line.include?(REWRITE) }
+      raise Failure, uncovered.join("\n") unless uncovered.empty?
+
+      File.write(path, "#{JSON.pretty_generate(shapes.sort.to_h)}\n")
+      "wrote #{shapes.size} bluebook shapes to #{path}#{edges_note(written)}"
+    end
+
+    def edges_note(written) = written.empty? ? "" : " and #{written.size} empty edge(s): #{written.join(", ")}"
+
+    # @return [Array<Array(String, String, String)>] `[bluebook, from, to]` for each shape that
+    #   moved
+    #   with no chain of edges leading to it
+    def uncovered_moves(ledger, shapes, edges)
+      shapes.filter_map do |name, now|
+        held = ledger[name]
+        next unless held && label(held) != label(now)
+        next if reachable?(label(held), label(now), edges.fetch(name, []))
+
+        [name, label(held), label(now)]
+      end
+    end
+
+    # @return [Array<String>] the paths of the empty edges written
+    def write_edges(directory, moves)
+      FileUtils.mkdir_p(File.join(directory, "translations"))
+      moves.map do |name, from, now|
+        path = File.join(directory, "translations", "2-#{now}.bluebook")
+        File.write(path, %(Hecks.data_translation "#{name}", from: "#{from}", to: "#{now}" do\nend\n))
+        path
+      end
+    end
+
+    # @return [Hash{String => String}] the ledger, empty when there is none yet
+    def read(path) = File.exist?(path) ? JSON.parse(File.read(path)) : {}
+  end
+end