imgui 1.0.0

data/generator/emitter.rb

@@ -0,0 +1,317 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+require "yaml"
+
+require_relative "type_mapper"
+
+module ImGuiRuby
+  module Generator
+    class Emitter
+      GENERATED_HEADER = <<~RUBY.freeze
+        # frozen_string_literal: true
+
+        # This file is generated by `rake generate`. Do not edit it manually.
+      RUBY
+
+      def initialize(
+        metadata_dir:,
+        output_dir:,
+        overrides_path:,
+        dependency_metadata_dirs: [],
+        public_module: "ImGui",
+        public_enum_prefix: nil,
+        predeclare_structs: false,
+        implementation_prefixes: nil
+      )
+        @metadata_dir = metadata_dir
+        @output_dir = output_dir
+        @public_module = public_module
+        @public_enum_prefix = public_enum_prefix
+        @predeclare_structs = predeclare_structs
+        @overrides = YAML.safe_load_file(overrides_path, aliases: false) || {}
+        @definitions = read_json("definitions.json")
+        implementation_path = File.join(@metadata_dir, "impl_definitions.json")
+        if File.file?(implementation_path)
+          implementations = JSON.parse(File.read(implementation_path))
+          if implementation_prefixes
+            implementations.select! do |name, _definitions|
+              implementation_prefixes.any? { |prefix| name.start_with?(prefix) }
+            end
+          end
+          @definitions = @definitions.merge(implementations)
+        end
+        @types = read_json("structs_and_enums.json")
+        @typedefs = read_json("typedefs_dict.json")
+        @structs = @types.fetch("structs")
+        vector_layout = @types.fetch("templated_structs", {})["ImVector"]
+        @structs["ImVector"] = vector_layout if vector_layout
+        @enums = @types.fetch("enums")
+        @early_struct_names = @predeclare_structs ? callback_value_struct_names : []
+        dependency_structs, dependency_enums, dependency_typedefs = dependency_types(dependency_metadata_dirs)
+        @mapper = TypeMapper.new(
+          typedefs: dependency_typedefs.merge(@typedefs),
+          structs: dependency_structs.merge(@structs),
+          enum_types: (dependency_enums.keys + @enums.keys).map { |name| name.delete_suffix("_") },
+          struct_references: dependency_structs.reject { |name, _members| @structs.key?(name) }.to_h do |name, _members|
+            [name, "ImGui::Native::#{name}"]
+          end
+        )
+      end
+
+      def generate!
+        FileUtils.mkdir_p(@output_dir)
+        write("typedefs.rb", emit_typedefs)
+        write("enums.rb", emit_enums)
+        write("structs.rb", emit_structs)
+        write("functions.rb", emit_functions)
+      end
+
+      private
+
+      def emit_typedefs
+        declarations = @typedefs.filter_map do |name, c_type|
+          next if @structs.key?(name) || c_type.start_with?("struct ")
+
+          callback = callback_signature(c_type)
+          if callback
+            arguments = callback.fetch(:arguments).map { |argument| @mapper.ffi_type(argument) }
+            "    callback :#{name}, [#{arguments.join(", ")}], #{@mapper.ffi_type(callback.fetch(:result))}"
+          else
+            "    typedef #{@mapper.typedef_type(c_type)}, :#{name}"
+          end
+        end
+
+        predeclarations = if @predeclare_structs
+                            @structs.keys.sort.map { |name| "    class #{name} < FFI::Struct; end" }
+                          else
+                            []
+                          end
+        early_layouts = @early_struct_names.filter_map do |name|
+          format_struct_layout(name, @structs.fetch(name))
+        end
+        wrap_native((predeclarations + early_layouts + declarations).join("\n"))
+      end
+
+      def emit_enums
+        native_constants = []
+        public_modules = []
+
+        @enums.sort.each do |enum_name, values|
+          values.each do |value|
+            native_constants << "    #{value.fetch("name")} = #{value.fetch("calc_value")}"
+          end
+
+          public_name = public_enum_name(enum_name)
+          prefix = enum_name.end_with?("_") ? enum_name : "#{enum_name}_"
+          constants = values.map do |value|
+            name = ruby_constant_name(value.fetch("name").delete_prefix(prefix))
+            "    #{name} = #{native_constant_reference}::#{value.fetch("name")}"
+          end
+          public_modules << "  module #{public_name}\n#{constants.join("\n")}\n  end"
+        end
+
+        return core_enum_module(native_constants, public_modules) if @public_module == "ImGui"
+
+        <<~RUBY
+          #{GENERATED_HEADER}
+
+          module ImGui
+            module Native
+          #{native_constants.join("\n")}
+            end
+          end
+
+          module #{@public_module}
+          #{public_modules.join("\n\n")}
+          end
+        RUBY
+      end
+
+      def callback_signature(c_type)
+        match = c_type.match(/\A(.+?)\s*\(\*\)\((.*)\);?\z/)
+        return unless match
+
+        arguments = match[2] == "void" || match[2].empty? ? [] : match[2].split(",").map do |argument|
+          argument.strip.sub(/\s+[a-zA-Z_]\w*\z/, "")
+        end
+        { result: match[1].strip, arguments: arguments }
+      end
+
+      def core_enum_module(native_constants, public_modules)
+        <<~RUBY
+          #{GENERATED_HEADER}
+
+          module ImGui
+            module Native
+          #{native_constants.join("\n")}
+            end
+
+          #{public_modules.join("\n\n")}
+          end
+        RUBY
+      end
+
+      def emit_structs
+        declarations = @structs.keys.sort.map { |name| "    class #{name} < FFI::Struct; end" }
+        layouts = ordered_structs.filter_map do |name, members|
+          next if @early_struct_names.include?(name)
+
+          format_struct_layout(name, members)
+        end
+
+        wrap_native((declarations + [""] + layouts).join("\n"))
+      end
+
+      def emit_functions
+        skipped = Array(@overrides["skip"])
+        renames = @overrides.fetch("rename", {})
+        declarations = @definitions.values.flatten.filter_map do |definition|
+          name = definition["ov_cimguiname"] || definition.fetch("cimguiname")
+          next if definition["skipped"] || definition["templated"] || definition["isvararg"] || skipped.include?(name)
+
+          arguments = Array(definition["argsT"]).map do |argument|
+            @mapper.ffi_type(argument.fetch("type"))
+          end
+          return_type = definition.fetch("ret") do
+            definition["constructor"] ? "#{definition.fetch("stname")}*" : "void"
+          end
+          result = @mapper.ffi_type(return_type)
+          ruby_name = renames.fetch(name, name)
+          if ruby_name == name
+            "    attach_function :#{name}, [#{arguments.join(", ")}], #{result}"
+          else
+            "    attach_function :#{ruby_name}, :#{name}, [#{arguments.join(", ")}], #{result}"
+          end
+        end
+
+        wrap_native(declarations.sort.join("\n"))
+      end
+
+      def public_enum_name(enum_name)
+        name = enum_name.delete_suffix("_")
+        return name.delete_prefix(@public_enum_prefix) if @public_enum_prefix
+
+        name.sub(/\AImGui/, "").sub(/\AIm/, "")
+      end
+
+      def native_constant_reference
+        @public_module == "ImGui" ? "Native" : "ImGui::Native"
+      end
+
+      def ruby_constant_name(name)
+        clean_name = name.sub(/\A_+/, "").gsub(/[^a-zA-Z0-9_]/, "_")
+        clean_name = "Num#{clean_name}" if clean_name.match?(/\A\d/)
+        clean_name.empty? ? "Value" : clean_name
+      end
+
+      def struct_fields(members)
+        anonymous_index = 0
+        previous_bitfield_type = nil
+
+        members.flat_map do |member|
+          if member["bitfield"]
+            type = @mapper.ffi_type(member.fetch("type"))
+            next [] if type == previous_bitfield_type
+
+            previous_bitfield_type = type
+            anonymous_index += 1
+            next ["_bitfield_#{anonymous_index}".inspect, type]
+          end
+
+          previous_bitfield_type = nil
+          name = member.fetch("name")
+          if name.empty?
+            anonymous_index += 1
+            name = "_anonymous_#{anonymous_index}"
+          end
+          [name.inspect, @mapper.ffi_type(member.fetch("type"), member: member)]
+        end
+      end
+
+      def format_struct_layout(name, members)
+        fields = struct_fields(members)
+        return if fields.empty?
+
+        formatted = fields.each_slice(2).map { |field, type| "        #{field}, #{type}" }.join(",\n")
+        "    #{name}.layout(\n#{formatted}\n    )"
+      end
+
+      def callback_value_struct_names
+        @typedefs.values.filter_map do |c_type|
+          signature = callback_signature(c_type)
+          next unless signature
+
+          types = [signature.fetch(:result), *signature.fetch(:arguments)]
+          types.find do |type|
+            bare = type.gsub(/\bconst\b|\bstruct\b/, "").strip
+            @structs.key?(bare)
+          end&.then do |type|
+            type.gsub(/\bconst\b|\bstruct\b/, "").strip
+          end
+        end.uniq.sort
+      end
+
+      def ordered_structs
+        ordered = []
+        state = {}
+        visit = lambda do |name|
+          return if state[name] == :done
+          return if state[name] == :visiting
+
+          state[name] = :visiting
+          @structs.fetch(name).each do |member|
+            dependency = by_value_struct_name(member.fetch("type"))
+            visit.call(dependency) if dependency
+          end
+          state[name] = :done
+          ordered << [name, @structs.fetch(name)]
+        end
+        @structs.keys.sort.each { |name| visit.call(name) }
+        ordered
+      end
+
+      def by_value_struct_name(c_type)
+        type = c_type.gsub(/\bconst\b|\bstruct\b/, "").gsub(/\[[^\]]+\]/, "").strip
+        return if type.include?("*") || type.include?("&")
+
+        return type if @structs.key?(type)
+
+        template_base = type.split("_").first
+        @structs.key?(template_base) ? template_base : nil
+      end
+
+      def wrap_native(body)
+        <<~RUBY
+          #{GENERATED_HEADER}
+
+          module ImGui
+            module Native
+          #{body}
+            end
+          end
+        RUBY
+      end
+
+      def read_json(filename)
+        JSON.parse(File.read(File.join(@metadata_dir, filename)))
+      end
+
+      def write(filename, content)
+        File.write(File.join(@output_dir, filename), content)
+      end
+
+      def dependency_types(metadata_dirs)
+        metadata_dirs.each_with_object([{}, {}, {}]) do |directory, (structs, enums, typedefs)|
+          types = JSON.parse(File.read(File.join(directory, "structs_and_enums.json")))
+          structs.merge!(types.fetch("structs"))
+          vector_layout = types.fetch("templated_structs", {})["ImVector"]
+          structs["ImVector"] = vector_layout if vector_layout
+          enums.merge!(types.fetch("enums"))
+          typedefs.merge!(JSON.parse(File.read(File.join(directory, "typedefs_dict.json"))))
+        end
+      end
+    end
+  end
+end

data/generator/generate.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "optparse"
+
+require_relative "emitter"
+require_relative "api_emitter"
+
+root = File.expand_path("..", __dir__)
+options = {
+  metadata: File.join(root, "tmp", "vendor", "cimgui", "generator", "output"),
+  output: File.join(root, "lib", "imgui", "native"),
+  overrides: File.join(__dir__, "overrides.yml")
+}
+
+OptionParser.new do |parser|
+  parser.banner = "Usage: ruby generator/generate.rb [options]"
+  parser.on("--metadata DIR", "cimgui generator/output directory") { |value| options[:metadata] = value }
+  parser.on("--output DIR", "generated Ruby output directory") { |value| options[:output] = value }
+  parser.on("--overrides FILE", "generation overrides YAML") { |value| options[:overrides] = value }
+end.parse!
+
+ImGuiRuby::Generator::Emitter.new(
+  metadata_dir: options.fetch(:metadata),
+  output_dir: options.fetch(:output),
+  overrides_path: options.fetch(:overrides),
+  implementation_prefixes: %w[ImGui_ImplGlfw_ ImGui_ImplOpenGL3_ ImGui_ImplSDL3_]
+).generate!
+
+ImGuiRuby::Generator::ApiEmitter.new(
+  metadata_dir: options.fetch(:metadata),
+  output_path: File.join(root, "lib", "imgui", "api_generated.rb"),
+  overrides_path: options.fetch(:overrides)
+).generate!
+
+plot_metadata = File.join(root, "tmp", "vendor", "cimplot", "generator", "output")
+if File.directory?(plot_metadata)
+  ImGuiRuby::Generator::Emitter.new(
+    metadata_dir: plot_metadata,
+    output_dir: File.join(root, "lib", "imgui", "plot", "native"),
+    overrides_path: options.fetch(:overrides),
+    dependency_metadata_dirs: [options.fetch(:metadata)],
+    public_module: "ImPlot",
+    public_enum_prefix: "ImPlot",
+    predeclare_structs: true
+  ).generate!
+end

data/generator/native-dependencies.yml

@@ -0,0 +1,88 @@
+---
+schema: 1
+sources:
+  cimgui:
+    repository: https://github.com/cimgui/cimgui.git
+    ref: docking_inter
+    revision: 140d107be52cf2cfe66aa2cb859fd8e07f9f6bf5
+    checksum: sha256:3a63513f59a355493c1faaa77667ac4f513754b9a622aa15b25ebd524c4d3e54
+    destination: cimgui
+    files:
+      - LICENSE
+      - cimconfig.h
+      - cimgui.cpp
+      - cimgui.h
+      - cimgui_impl.cpp
+      - cimgui_impl.h
+      - generator/output/definitions.json
+      - generator/output/impl_definitions.json
+      - generator/output/structs_and_enums.json
+      - generator/output/typedefs_dict.json
+  imgui:
+    repository: https://github.com/ocornut/imgui.git
+    revision: 126d004f9e1eef062bf4b044b3b2faaf58d48c51
+    checksum: sha256:dd1328bdf2f47e9f664a73996fbba2d85b23b926641964a2553b08a8e00cb30b
+    parent:
+      source: cimgui
+      path: imgui
+    destination: cimgui/imgui
+    files:
+      - LICENSE.txt
+      - "*.cpp"
+      - "*.h"
+      - backends/imgui_impl_glfw.cpp
+      - backends/imgui_impl_glfw.h
+      - backends/imgui_impl_opengl3.cpp
+      - backends/imgui_impl_opengl3.h
+      - backends/imgui_impl_opengl3_loader.h
+      - backends/imgui_impl_sdl3.cpp
+      - backends/imgui_impl_sdl3.h
+      - backends/imgui_impl_wgpu.cpp
+      - backends/imgui_impl_wgpu.h
+      - examples/libs/glfw/include/GLFW/*.h
+  cimplot:
+    repository: https://github.com/cimgui/cimplot.git
+    ref: master
+    revision: 381ed68cc0688f16d027d67edc3bc060afa4dde9
+    checksum: sha256:50bdbdef021bf080d189c14a11916c6c068fafeab661d780bf422a56a610faa0
+    destination: cimplot
+    files:
+      - LICENSE
+      - cimplot.cpp
+      - cimplot.h
+      - generator/output/definitions.json
+      - generator/output/structs_and_enums.json
+      - generator/output/typedefs_dict.json
+  implot:
+    repository: https://github.com/epezent/implot.git
+    revision: 47522f47054d33178e7defa780042bd2a06b09f9
+    checksum: sha256:88d83afafceb919b4171b3308716188d34116b32811f6eba0e9df7d9cfad42dc
+    parent:
+      source: cimplot
+      path: implot
+    destination: cimplot/implot
+    files:
+      - LICENSE
+      - implot.cpp
+      - implot_demo.cpp
+      - implot.h
+      - implot_internal.h
+      - implot_items.cpp
+  sdl:
+    repository: https://github.com/libsdl-org/SDL.git
+    ref: release-3.2.x
+    revision: f6864924f76e1a0b4abaefc76ae2ed22b1a8916e
+    checksum: sha256:843dafeeb13f7ce22130cf234a6ca48d40a43bb19d7f56851419fc9aee1c8165
+    destination: sdl
+    files:
+      - LICENSE.txt
+      - include/SDL3/*.h
+  webgpu:
+    repository: https://github.com/webgpu-native/webgpu-headers.git
+    ref: main
+    revision: bac520839ff5ed2e2b648ed540bd9ec45edbccbc
+    checksum: sha256:22f9cfe67c2da486351eea6f0504a4aa80e3b17c1d42ea7b0929eb2247b8b81b
+    destination: webgpu
+    files:
+      - LICENSE
+      - webgpu.h

data/generator/native_dependency_lock.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "digest"
+require "yaml"
+
+module ImGuiRuby
+  class NativeDependencyLock
+    class VerificationError < StandardError; end
+
+    REVISION_PATTERN = /\A[0-9a-f]{40}\z/
+    CHECKSUM_PATTERN = /\Asha256:[0-9a-f]{64}\z/
+
+    attr_reader :sources
+
+    def initialize(path)
+      @path = path
+      @manifest = YAML.safe_load_file(path, aliases: false)
+      @sources = @manifest.fetch("sources")
+    end
+
+    def validate!
+      raise VerificationError, "unsupported manifest" unless @manifest["schema"] == 1
+
+      @sources.each do |name, source|
+        raise VerificationError, "#{name}: invalid revision" unless REVISION_PATTERN.match?(source.fetch("revision"))
+        raise VerificationError, "#{name}: invalid checksum" unless CHECKSUM_PATTERN.match?(source.fetch("checksum"))
+      end
+    end
+
+    def files(name, source, root)
+      base = File.join(root, source.fetch("destination"))
+      source.fetch("files").flat_map do |pattern|
+        matches = Dir.glob(File.join(base, pattern)).select { |path| File.file?(path) }
+        raise VerificationError, "#{name}: #{pattern} did not match a file" if matches.empty?
+
+        matches
+      end
+    end
+
+    def verify_checksum!(name, source, root)
+      return if source.fetch("checksum") == checksum(name, source, root)
+
+      raise VerificationError, "#{name}: checksum mismatch"
+    end
+
+    def checksums(root)
+      @sources.to_h { |name, source| [name, checksum(name, source, root)] }
+    end
+
+    def verify_checksums!(checksums)
+      @sources.each do |name, source|
+        next if source.fetch("checksum") == checksums.fetch(name)
+
+        raise VerificationError, "#{name}: downloaded content checksum mismatch"
+      end
+    end
+
+    def update!(resolved, checksums)
+      resolved.each do |name, data|
+        source = @sources.fetch(name)
+        source["revision"] = data.fetch(:revision)
+        source["checksum"] = checksums.fetch(name)
+      end
+      File.write(@path, YAML.dump(@manifest))
+    end
+
+    private
+
+    def checksum(name, source, root)
+      base = File.join(root, source.fetch("destination"))
+      digest = Digest::SHA256.new
+      files(name, source, root).sort.each do |path|
+        digest << path.delete_prefix("#{base}/") << "\0" << File.binread(path) << "\0"
+      end
+      "sha256:#{digest.hexdigest}"
+    end
+  end
+end

data/generator/native_dependency_snapshot.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "open3"
+require "tmpdir"
+
+require_relative "native_dependency_lock"
+
+module ImGuiRuby
+  class NativeDependencySnapshot
+    ROOT = File.expand_path("..", __dir__)
+    MANIFEST_PATH = File.join(__dir__, "native-dependencies.yml")
+    CACHE_ROOT = File.join(ROOT, "tmp", "vendor")
+    REVISION_PATTERN = NativeDependencyLock::REVISION_PATTERN
+    VerificationError = NativeDependencyLock::VerificationError
+
+    def initialize
+      @lock = NativeDependencyLock.new(MANIFEST_PATH)
+      @sources = @lock.sources
+    end
+
+    def fetch!
+      unless File.directory?(CACHE_ROOT)
+        warn "Native dependency cache is missing; fetching pinned revisions."
+        return refresh!
+      end
+
+      verify!
+    rescue VerificationError => error
+      warn "Native dependency cache is unavailable: #{error.message}"
+      refresh!
+    end
+
+    def verify!
+      @lock.validate!
+      expected_files = @sources.flat_map do |name, source|
+        @lock.verify_checksum!(name, source, CACHE_ROOT)
+        @lock.files(name, source, CACHE_ROOT)
+      end.uniq
+      actual_files = all_files(CACHE_ROOT)
+      unexpected = actual_files - expected_files
+      raise VerificationError, "unexpected files:\n#{relative_list(unexpected)}" unless unexpected.empty?
+
+      puts "Verified #{@sources.length} native dependency snapshots (#{actual_files.length} files)."
+    end
+
+    def refresh!(latest: false)
+      resolved = {}
+      FileUtils.mkdir_p(File.dirname(CACHE_ROOT))
+
+      Dir.mktmpdir("native-dependencies-", File.dirname(CACHE_ROOT)) do |temporary_root|
+        snapshot_root = File.join(temporary_root, "vendor")
+        checkout_root = File.join(temporary_root, "checkouts")
+        populate_snapshot!(snapshot_root, checkout_root, resolved, latest:)
+        checksums = @lock.checksums(snapshot_root)
+        @lock.verify_checksums!(checksums) unless latest
+        replace_snapshot!(snapshot_root)
+        @lock.update!(resolved, checksums) if latest
+      end
+
+      verify!
+    end
+
+    def checkout_source!(name, destination)
+      source = @sources.fetch(name) { raise "unknown native dependency: #{name}" }
+      path = File.expand_path(destination, ROOT)
+      raise "checkout destination already exists: #{path}" if File.exist?(path)
+
+      checkout!(source.fetch("repository"), source.fetch("revision"), path)
+      puts "Checked out #{name} at #{source.fetch('revision')} to #{relative(path)}."
+    end
+
+    private
+
+    def populate_snapshot!(snapshot_root, checkout_root, resolved, latest:)
+      @sources.each do |name, source|
+        revision = revision_for(name, source, resolved, latest:)
+        checkout = File.join(checkout_root, name)
+        checkout!(source.fetch("repository"), revision, checkout)
+        resolved[name] = { revision:, checkout: }
+        copy_files!(name, source, checkout, snapshot_root)
+      end
+    end
+
+    def revision_for(name, source, resolved, latest:)
+      return source.fetch("revision") unless latest
+      return remote_revision!(source) unless source["parent"]
+
+      parent = source.fetch("parent")
+      checkout = resolved.fetch(parent.fetch("source")).fetch(:checkout)
+      revision = run("git", "-C", checkout, "rev-parse", "HEAD:#{parent.fetch('path')}").strip
+      raise "#{name}: parent did not resolve to a commit" unless REVISION_PATTERN.match?(revision)
+
+      revision
+    end
+
+    def remote_revision!(source)
+      ref = source.fetch("ref")
+      output = run("git", "ls-remote", source.fetch("repository"), "refs/heads/#{ref}", "refs/tags/#{ref}")
+      revision = output.lines.first&.split&.first
+      raise "could not resolve #{source.fetch('repository')} #{ref}" unless REVISION_PATTERN.match?(revision)
+
+      revision
+    end
+
+    def checkout!(repository, revision, destination)
+      FileUtils.mkdir_p(destination)
+      run("git", "-C", destination, "init", "--quiet")
+      run("git", "-C", destination, "config", "core.autocrlf", "false")
+      run("git", "-C", destination, "config", "core.eol", "lf")
+      run("git", "-C", destination, "remote", "add", "origin", repository)
+      run("git", "-C", destination, "fetch", "--quiet", "--depth", "1", "origin", revision)
+      run("git", "-C", destination, "checkout", "--quiet", "--detach", "FETCH_HEAD")
+    end
+
+    def copy_files!(name, source, checkout, snapshot_root)
+      source.fetch("files").each do |pattern|
+        matches = Dir.glob(File.join(checkout, pattern)).select { |path| File.file?(path) }
+        raise "#{name}: #{pattern} did not match upstream" if matches.empty?
+
+        matches.each do |path|
+          destination = File.join(snapshot_root, source.fetch("destination"), path.delete_prefix("#{checkout}/"))
+          FileUtils.mkdir_p(File.dirname(destination))
+          FileUtils.cp(path, destination)
+        end
+      end
+    end
+
+    def replace_snapshot!(snapshot_root)
+      previous_root = "#{CACHE_ROOT}.previous"
+      FileUtils.rm_rf(previous_root)
+      FileUtils.mv(CACHE_ROOT, previous_root) if File.exist?(CACHE_ROOT)
+      FileUtils.mv(snapshot_root, CACHE_ROOT)
+      FileUtils.rm_rf(previous_root)
+    rescue StandardError
+      FileUtils.mv(previous_root, CACHE_ROOT) if File.exist?(previous_root) && !File.exist?(CACHE_ROOT)
+      raise
+    end
+
+    def all_files(root)
+      Dir.glob(File.join(root, "**", "*"), File::FNM_DOTMATCH).select { |path| File.file?(path) }
+    end
+
+    def run(*command)
+      output, error, status = Open3.capture3(*command, chdir: ROOT)
+      return output if status.success?
+
+      raise "command failed (#{command.join(' ')}):\n#{error}"
+    end
+
+    def relative(path)
+      path.delete_prefix("#{ROOT}/")
+    end
+
+    def relative_list(paths)
+      paths.map { |path| relative(path) }.sort.join("\n")
+    end
+  end
+end