dialecto-rails 0.1.0

data/lib/dialecto_rails/scan/cli.rb

@@ -0,0 +1,339 @@
+require "json"
+require "optparse"
+require_relative "../errors"
+require_relative "../config"
+require_relative "git"
+require_relative "worktree"
+require_relative "catalogs"
+require_relative "envelope"
+require_relative "client"
+
+module DialectoRails
+  module Scan
+    # `dialecto-rails scan | usages | check | doctor | version`.
+    # `run` returns the exit code: 0 ok, 1 findings, 2 can't start, 3 refused, 4 retryable.
+    class Cli
+      COMMANDS = %w[scan doctor version help].freeze
+      TOKEN_SHAPE = /\Adlk_[A-Za-z0-9_-]{43}\z/
+
+      def self.run(argv, env: ENV, out: $stdout, err: $stderr, root: Dir.pwd, client: nil, input: $stdin)
+        new(argv, env: env, out: out, err: err, root: root, client: client, input: input).run
+      end
+
+      def initialize(argv, env:, out:, err:, root:, client: nil, input: $stdin)
+        @argv = argv.dup
+        @env = env
+        @out = out
+        @err = err
+        @in = input
+        @root = root
+        @client_factory = client || ->(config) { Client.new(config, log: ->(line) { @err.puts(line) }) }
+        @flags = {}
+      end
+
+      def run
+        command = @argv.shift || "help"
+        case command
+        when "scan" then scan
+        when "doctor" then doctor
+        when "usages" then usages
+        when "check" then check
+        when "parse-check" then parse_check
+        when "version", "--version" then @out.puts("dialecto-rails #{VERSION}") || 0
+        when "help", "--help", "-h" then help
+        else
+          @err.puts("Unknown command #{command.inspect}.")
+          help(@err)
+          2
+        end
+      rescue Error => e
+        @err.puts(e.message)
+        @err.puts(e.backtrace.first(8)) if @flags[:debug]
+        e.exit_code
+      end
+
+      private
+
+      def help(io = @out)
+        io.puts <<~HELP
+          dialecto-rails #{VERSION}
+
+            dialecto-rails scan [--branch NAME] [--sha SHA] [--usages] [--require-usages] [--worktree] [--dry-run] [--debug]
+            dialecto-rails usages [--summary] [--sha SHA] [--worktree] [--out FILE]
+            dialecto-rails check [--sha SHA] [--worktree]
+            dialecto-rails parse-check [--root DIR]   (relative paths on standard input)
+            dialecto-rails doctor
+            dialecto-rails version
+
+          Settings come from the environment: DIALECTO_SCAN_TOKEN, DIALECTO_PROJECT (the project's number),
+          DIALECTO_URL, DIALECTO_CATALOG_PATHS, DIALECTO_USAGES, DIALECTO_DEFAULT_BRANCH.
+        HELP
+        0
+      end
+
+      def parse_flags
+        OptionParser.new do |opts|
+          opts.on("--branch NAME") { |value| @flags[:branch] = value }
+          opts.on("--sha SHA") { |value| @flags[:sha] = value }
+          opts.on("--usages") { @flags[:usages] = true }
+          opts.on("--require-usages") { @flags[:require_usages] = true }
+          opts.on("--worktree") { @flags[:worktree] = true }
+          opts.on("--root DIR") { |value| @flags[:root] = value }
+          opts.on("--summary") { @flags[:summary] = true }
+          opts.on("--out FILE") { |value| @flags[:out] = value }
+          opts.on("--dry-run") { @flags[:dry_run] = true }
+          opts.on("--debug") { @flags[:debug] = true }
+        end.parse!(@argv)
+      rescue OptionParser::ParseError => e
+        raise ConfigError, e.message
+      end
+
+      def config
+        @config ||= Config.new({usages: (true if @flags[:usages])}.compact, @env)
+      end
+
+      ## scan
+
+      def scan
+        parse_flags
+        require_settings!
+        git = Git.new(@root)
+        raise ConfigError, "#{@root} isn't inside a git repository." unless git.repository?
+
+        sha = @flags[:sha] || git.head_sha
+        branch = @flags[:branch] || current_branch(git)
+        client = @client_factory.call(config)
+
+        unless @flags[:dry_run] || scanned_branch?(client, git, branch)
+          @out.puts("Dialecto doesn't scan the branch #{branch}; nothing sent.")
+          write_outputs("outcome" => "skipped")
+          return 0
+        end
+
+        # `--worktree` reads the folder as it is, dirty files included: a testing escape hatch, never what a PR is made from.
+        reader = @flags[:worktree] ? Worktree.new(@root) : git
+        @err.puts("Reading the working tree, not commit #{sha[0, 8]}: a pull request from this scan would carry these bytes.") if @flags[:worktree]
+        usages = usage_scan(reader, sha)
+        envelope = Envelope.build(git: reader, catalogs: Catalogs.new(config.catalog_paths), sha: sha, branch: branch,
+          usages: usages)
+
+        if @flags[:dry_run]
+          counts = envelope.counts
+          @out.puts("Dry run: #{counts[:files]} catalog files at #{sha[0, 8]} on #{branch}" \
+                    "#{counts[:records] ? ", #{counts[:records]} usage records" : ""}; nothing sent.")
+          return 0
+        end
+
+        report(client.post_scan(envelope.body))
+        write_outputs("files" => envelope.counts[:files], "records" => envelope.counts[:records])
+        0
+      end
+
+      # GitHub Actions step outputs, when the runner offers the file. Values come partly from the
+      # server's answer, so only a plain word is written: a newline would add outputs of its own.
+      def write_outputs(values)
+        path = @env["GITHUB_OUTPUT"].to_s
+        return if path.empty?
+
+        File.open(path, "a") do |file|
+          values.each { |name, value| file.puts("#{name}=#{value}") if value.to_s.match?(/\A[\w.-]+\z/) }
+        end
+      end
+
+      def require_settings!
+        raise ConfigError, "Set DIALECTO_SCAN_TOKEN to the project's scan token (Settings → Scan token)." unless config.scan_token
+        unless config.project&.match?(/\A\d+\z/)
+          raise ConfigError, "Set DIALECTO_PROJECT to the project's number, the <number> in its Dialecto " \
+                             "URL /repos/<number>#{config.project ? " (got #{config.project.inspect})" : ""}."
+        end
+        problem = config.url_problem
+        raise ConfigError, problem if problem
+      end
+
+      def current_branch(git)
+        head_ref = @env["GITHUB_HEAD_REF"].to_s
+        return head_ref unless head_ref.empty?
+
+        ref = @env["GITHUB_REF_NAME"].to_s
+        return ref if @env["GITHUB_REF_TYPE"] == "branch" && !ref.empty?
+
+        git.branch || raise(ConfigError, "HEAD is detached: pass --branch NAME.")
+      end
+
+      # The default branch is always scanned; others when the scan mode is `all`, they are tracked, or they
+      # match the project's regex (the rule of the generated workflow and `Branches.scans_branch?`).
+      def scanned_branch?(client, git, branch)
+        default = config.default_branch || git.default_branch
+        return true if branch == default
+
+        settings = client.scan_config
+        return true if settings["scan_mode"] == "all"
+        return true if Array(settings["tracked_branches"]).include?(branch)
+
+        regex = settings["branch_regex"].to_s
+        return true if !regex.empty? && Regexp.new(regex).match?(branch)
+
+        # Without a known default branch a refusal here would skip the branch that matters most.
+        default.nil?
+      rescue RegexpError
+        false
+      end
+
+      ## usages and check
+
+      # Runs the usage scan for these two commands, which need no token and send nothing.
+      # `--worktree` reads the folder as it is, which needs no git repository.
+      def local_scan
+        parse_flags
+        reader, sha = scan_source
+
+        begin
+          require_relative "../usages/scanner"
+        rescue LoadError => e
+          raise ConfigError, "The usage scan needs the prism gem (#{e.message.lines.first.to_s.strip}); gem install prism."
+        end
+        scanner = DialectoRails::Usages::Scanner.new(git: reader, sha: sha, config: config)
+        [scanner.call, scanner.catalog]
+      end
+
+      def scan_source
+        return [Worktree.new(@root), @flags[:sha] || "worktree"] if @flags[:worktree]
+
+        git = Git.new(@root)
+        raise ConfigError, "#{@root} isn't inside a git repository." unless git.repository?
+
+        [git, @flags[:sha] || git.head_sha]
+      end
+
+      ## parse-check
+
+      # Reads relative paths, one per line, from standard input and checks that each still parses with the gem's
+      # own readers (`--root DIR`, default the current folder). For the rename check; it sends nothing.
+      def parse_check
+        parse_flags
+        begin
+          require_relative "../usages/parse_check"
+        rescue LoadError => e
+          raise ConfigError, "The parse check needs the prism gem (#{e.message.lines.first.to_s.strip}); gem install prism."
+        end
+        root = @flags[:root] || @root
+        files = @in.each_line.map(&:chomp).reject(&:empty?).map { |path| [path, File.binread(File.join(root, path))] }
+        result = DialectoRails::Usages::ParseCheck.call(files)
+        result[:failures].each { |failure| @out.puts("FAIL #{failure.path}:#{failure.line} #{failure.message}") }
+        @out.puts("checked #{result[:checked]}, skipped #{result[:skipped]}, failed #{result[:failures].length}")
+        result[:failures].empty? ? 0 : 1
+      end
+
+      def usages
+        require_relative "../usages/summary"
+        envelope, catalog = local_scan
+        @out.puts(DialectoRails::Usages::Summary.new(envelope, catalog.keys.to_a).render)
+        File.write(@flags[:out], JSON.pretty_generate(envelope)) if @flags[:out]
+        0
+      end
+
+      def check
+        require_relative "../usages/check"
+        envelope, catalog = local_scan
+        check = DialectoRails::Usages::Check.new(envelope, catalog)
+        check.findings.each do |finding|
+          @out.puts("#{finding.warning ? "warning" : "error"} #{finding.file}:#{finding.line} #{finding.code}: #{finding.message}")
+        end
+        @out.puts("No findings.") if check.findings.empty?
+        check.failed? ? 1 : 0
+      end
+
+      def usage_scan(git, sha)
+        return nil unless config.usages?
+
+        require_relative "../usages/scanner"
+        DialectoRails::Usages::Scanner.new(git: git, sha: sha, config: config).call
+      rescue LoadError
+        usages_unavailable("the usage scan isn't available in this build")
+      rescue Error
+        raise
+      rescue => e
+        usages_unavailable("the usage scan failed (#{e.class}: #{e.message})")
+      end
+
+      def usages_unavailable(reason)
+        raise ConfigError, "#{reason}; usages are required (--require-usages)." if @flags[:require_usages] || config.require_usages?
+
+        @err.puts("Sending the catalogs without call sites: #{reason}. Renames stay unavailable until a scan carries them.")
+        nil
+      end
+
+      def report(answer)
+        outcome = answer["outcome"]
+        write_outputs("scan-id" => answer["scan_id"], "outcome" => outcome)
+        if outcome == "idempotent"
+          @out.puts("Already scanned (scan #{answer["scan_id"]}); nothing changed.")
+        else
+          counts = answer["counts"] || {}
+          @out.puts("Scan #{answer["scan_id"]} ingested: " \
+                    "#{counts.map { |name, value| "#{value} #{name}" }.join(", ")}.")
+        end
+        Array(answer["skipped"]).each do |file|
+          @out.puts("  skipped #{file["path"]}: #{file["message"] || file["reason"]}")
+        end
+      end
+
+      ## doctor
+
+      def doctor
+        parse_flags
+        git = Git.new(@root)
+        checks = []
+        checks << ["Ruby #{RUBY_VERSION}", RUBY_VERSION >= "3.2", "Dialecto's Rails SDK needs Ruby 3.2 or newer."]
+        checks << ["git repository", git.repository?, "Run it inside the project's git checkout."]
+        remote = git.repository? ? git.remote_url : nil
+        checks << ["origin remote #{remote || "(none)"}", !remote.to_s.empty?, "Add an origin remote: `git remote add origin <url>`."]
+        checks << ["catalog files at HEAD", catalogs_present?(git), "No file matches #{config.catalog_paths.join(", ")}: set DIALECTO_CATALOG_PATHS."]
+        token = config.scan_token
+        checks << ["scan token set", !token.nil?, "Set DIALECTO_SCAN_TOKEN (Settings → Scan token)."]
+        checks << ["scan token shape", token.nil? || token.match?(TOKEN_SHAPE), "The token should look like dlk_ followed by 43 characters; copy it exactly as Dialecto showed it."]
+        checks << ["project #{config.project || "(unset)"}", !!config.project&.match?(/\A\d+\z/), "Set DIALECTO_PROJECT to the project's number."]
+        checks << ["url #{config.url}", config.url_problem.nil?, config.url_problem.to_s]
+        checks << parsers_check
+        checks << server_check(token) if token && config.project&.match?(/\A\d+\z/) && config.url_problem.nil?
+
+        checks.each { |label, ok, fix| @out.puts("#{ok ? "ok  " : "FAIL"} #{label}#{ok ? "" : "\n     #{fix}"}") }
+        worker_warning
+        checks.all? { |_label, ok, _fix| ok } ? 0 : 2
+      end
+
+      # The in-context editor keeps its drafts and markers in memory, one copy per worker process.
+      def worker_warning
+        workers = @env["WEB_CONCURRENCY"].to_i
+        return unless workers > 1
+
+        @out.puts("warn WEB_CONCURRENCY=#{workers}\n     The in-context editor holds its state per process; with several workers a draft may " \
+                  "vanish on the next request. Run the development server with one worker (the Rails default).")
+      end
+
+      def catalogs_present?(git)
+        return false unless git.repository?
+
+        catalogs = Catalogs.new(config.catalog_paths)
+        git.entries(git.head_sha).any? { |entry| catalogs.match?(entry.path) }
+      rescue Error
+        false
+      end
+
+      def parsers_check
+        require "prism"
+        ["prism #{Prism::VERSION}", true, ""]
+      rescue LoadError
+        ["prism", false, "Install it: gem install prism."]
+      end
+
+      def server_check(_token)
+        client = @client_factory.call(config)
+        client.scan_config
+        ["Dialecto accepts the token", true, ""]
+      rescue RefusedError, RetryableError => e
+        ["Dialecto accepts the token", false, e.message]
+      end
+    end
+  end
+end

data/lib/dialecto_rails/scan/client.rb

@@ -0,0 +1,117 @@
+require "json"
+require "net/http"
+require "openssl"
+require "uri"
+
+module DialectoRails
+  module Scan
+    # Talks to a Dialecto server under the project's scan token (docs/ingestion-api.md). Expected failures
+    # are `RefusedError` (fix the pipeline) or `RetryableError` (wait and rerun); the token never appears
+    # in a message.
+    class Client
+      Response = Struct.new(:status, :body, keyword_init: true)
+
+      RETRY_DELAYS = [1, 4, 16].freeze
+      MAX_RETRY_AFTER = 60
+      NETWORK_ERRORS = [
+        Timeout::Error, Errno::ECONNREFUSED, Errno::ECONNRESET, Errno::EHOSTUNREACH, Errno::ENETUNREACH,
+        Errno::EPIPE, SocketError, EOFError, OpenSSL::SSL::SSLError
+      ].freeze
+
+      def initialize(config, sleeper: Kernel.method(:sleep), jitter: -> { rand * 0.25 }, log: nil)
+        @config = config
+        @sleeper = sleeper
+        @jitter = jitter
+        @log = log
+      end
+
+      # `{scan_mode, branch_regex, tracked_branches}`.
+      def scan_config
+        JSON.parse(request(Net::HTTP::Get, "scan-config", nil).body)
+      rescue JSON::ParserError
+        raise RetryableError, "Dialecto's scan-config answer isn't JSON; try again in a moment."
+      end
+
+      # The server's answer to a scan: `{"scan_id", "outcome", "counts"?, "skipped"}`, with the HTTP status.
+      def post_scan(body)
+        response = request(Net::HTTP::Post, "scans", body)
+        parsed = begin
+          JSON.parse(response.body)
+        rescue JSON::ParserError
+          {}
+        end
+        parsed.merge("status" => response.status)
+      end
+
+      private
+
+      def request(klass, tail, body)
+        uri = URI.parse("#{@config.url}/api/repos/#{@config.project}/#{tail}")
+        attempts = 0
+        loop do
+          result = attempt(klass, uri, body)
+          return result if result.is_a?(Response)
+
+          attempts += 1
+          delay = RETRY_DELAYS[attempts - 1]
+          raise RetryableError, result if delay.nil?
+
+          wait = [delay, @retry_after.to_i].max + @jitter.call
+          @retry_after = nil
+          @log&.call("Dialecto answered #{result}; retrying in #{wait.round(1)}s (#{attempts}/#{RETRY_DELAYS.length})")
+          @sleeper.call(wait)
+        end
+      end
+
+      # A Response when the server gave a final answer; otherwise a String saying why it can be retried.
+      def attempt(klass, uri, body)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        http.open_timeout = 10
+        http.read_timeout = 60
+        req = klass.new(uri.request_uri)
+        req["Authorization"] = "Bearer #{@config.scan_token}"
+        req["Accept"] = "application/json"
+        req["User-Agent"] = "dialecto-rails/#{VERSION}"
+        if body
+          req["Content-Type"] = "application/json"
+          req.body = body
+        end
+
+        res = http.start { |connection| connection.request(req) }
+        classify(res)
+      rescue *NETWORK_ERRORS => e
+        "a network error (#{e.class.name.split("::").last})"
+      end
+
+      def classify(res)
+        status = res.code.to_i
+        return Response.new(status: status, body: res.body.to_s) if status.between?(200, 299)
+
+        # A redirect (the apex domain answers 301) is not an ingest; following it would resend the token.
+        if status.between?(300, 399)
+          raise RefusedError, "HTTP #{status} to #{res["location"] || "(no Location)"}: check DIALECTO_URL"
+        end
+
+        if status == 429 || status >= 500
+          retry_after = res["retry-after"].to_i
+          @retry_after = [retry_after, MAX_RETRY_AFTER].min if retry_after.positive?
+          return "HTTP #{status}"
+        end
+
+        raise RefusedError, refusal(status, res.body.to_s)
+      end
+
+      def refusal(status, raw)
+        data = begin
+          JSON.parse(raw)
+        rescue JSON::ParserError
+          {}
+        end
+        message = data["message"] || data["error"] || "HTTP #{status}"
+        code = data["error"] && data["message"] ? " (#{data["error"]})" : ""
+        "#{message}#{code}"
+      end
+    end
+  end
+end

data/lib/dialecto_rails/scan/envelope.rb

@@ -0,0 +1,100 @@
+require "digest"
+require "json"
+
+module DialectoRails
+  module Scan
+    # The scan request body (docs/ingestion-api.md): the committed catalog files verbatim, the commit
+    # and branch they were read at, and a checksum that makes a re-run a no-op.
+    class Envelope
+      MB = 1024 * 1024
+      MAX_FILES = 1_000
+      MAX_FILE_BYTES = 5 * MB
+      MAX_CATALOG_BYTES = 10 * MB
+      MAX_BODY_BYTES = 20 * MB
+
+      attr_reader :payload, :files
+
+      # `usages` is the usage scan's envelope (a Hash) or nil.
+      def self.build(git:, catalogs:, sha:, branch:, usages: nil)
+        new(git, catalogs, sha, branch, usages).tap(&:validate!)
+      end
+
+      def initialize(git, catalogs, sha, branch, usages)
+        @git = git
+        @sha = sha
+        @branch = branch
+        @usages = usages
+        @files = git.entries(sha).select { |entry| catalogs.match?(entry.path) }.sort_by(&:path)
+      end
+
+      def validate!
+        raise ConfigError, no_files_message if files.empty?
+        check_limits!
+        @payload = build_payload
+        body = JSON.generate(@payload)
+        return if body.bytesize <= MAX_BODY_BYTES
+
+        raise ConfigError, "The scan is #{format_mb(body.bytesize)} MB; Dialecto takes #{MAX_BODY_BYTES / MB} MB. " \
+                           "Narrow DIALECTO_CATALOG_PATHS, or send fewer usage records."
+      end
+
+      def body = JSON.generate(payload)
+
+      def counts = {files: files.length, records: @usages ? @usages["usages"].length : nil}
+
+      private
+
+      def build_payload
+        templates = files.map do |entry|
+          content = @git.blob(entry.blob).force_encoding(Encoding::UTF_8)
+          unless content.valid_encoding?
+            raise ConfigError, "#{entry.path} isn't valid UTF-8, so it can't be sent as text. Dialecto " \
+                               "reads UTF-8 catalogs: re-save the file as UTF-8 or leave it out of DIALECTO_CATALOG_PATHS."
+          end
+          {path: entry.path, content: content}
+        end
+
+        payload = {gitSha: @sha, gitBranch: @branch, checksum: checksum, templates: templates}
+        payload[:railsUsages] = @usages if @usages
+        payload
+      end
+
+      def check_limits!
+        if files.length > MAX_FILES
+          raise ConfigError, "#{delimit(files.length)} catalog files match; Dialecto takes #{delimit(MAX_FILES)}. " \
+                             "Narrow DIALECTO_CATALOG_PATHS (for example to the source locale and the languages you translate)."
+        end
+
+        big = files.find { |entry| entry.size > MAX_FILE_BYTES }
+        if big
+          raise ConfigError, "#{big.path} is #{format_mb(big.size)} MB; Dialecto takes #{MAX_FILE_BYTES / MB} MB a file."
+        end
+
+        total = files.sum(&:size)
+        return if total <= MAX_CATALOG_BYTES
+
+        raise ConfigError, "The catalogs are #{format_mb(total)} MB; Dialecto takes #{MAX_CATALOG_BYTES / MB} MB. " \
+                           "Narrow DIALECTO_CATALOG_PATHS."
+      end
+
+      # The commit, the branch and each sent file's blob id, plus the usage records, so a code-only change
+      # with unchanged catalogs is a new scan, a re-run is a no-op and a revert is a new scan.
+      def checksum
+        digest = Digest::SHA256.new
+        digest << "dialecto-rails/1\n#{@sha}\n#{@branch}\n"
+        files.each { |entry| digest << "#{@git.respond_to?(:blob_id) ? @git.blob_id(entry.blob) : entry.blob} #{entry.path}\n" }
+        digest << "usages:#{Digest::SHA256.hexdigest(JSON.generate(@usages))}\n" if @usages
+        digest.hexdigest
+      end
+
+      def no_files_message
+        "No file at #{@sha[0, 8]} matches the catalog paths. Dialecto reads the files your project's " \
+          "settings name; set DIALECTO_CATALOG_PATHS to match them (default config/locales/**/*.yml)."
+      end
+
+      def format_mb(bytes) = format("%.1f", bytes.to_f / MB)
+
+      def delimit(number) = number.to_s.reverse.scan(/\d{1,3}/).join(",").reverse
+    end
+  end
+end

data/lib/dialecto_rails/scan/git.rb

@@ -0,0 +1,68 @@
+require "open3"
+
+module DialectoRails
+  module Scan
+    # Reads a repository through `git`, with an argument array (no shell). The scanner reads the committed
+    # state at a sha, never the working tree, because that is what pull requests are made against.
+    class Git
+      Entry = Struct.new(:path, :blob, :size, keyword_init: true)
+
+      TIMEOUT = 30
+
+      def initialize(root = Dir.pwd)
+        @root = root
+      end
+
+      def repository?
+        run("rev-parse", "--is-inside-work-tree", chomp: true) == "true"
+      rescue ConfigError
+        false
+      end
+
+      def head_sha = run("rev-parse", "HEAD", chomp: true)
+
+      # The current branch name, or nil on a detached HEAD.
+      def branch
+        name = run("rev-parse", "--abbrev-ref", "HEAD", chomp: true)
+        name == "HEAD" ? nil : name
+      end
+
+      # The remote's default branch, or nil when `origin/HEAD` isn't set.
+      def default_branch
+        ref = run("symbolic-ref", "--short", "refs/remotes/origin/HEAD", chomp: true, allow_failure: true)
+        ref&.sub(%r{\Aorigin/}, "")
+      end
+
+      def remote_url = run("remote", "get-url", "origin", chomp: true, allow_failure: true)
+
+      # Every blob under `sha`: path, blob id and size. Symlinks and submodules are left out.
+      def entries(sha)
+        raw = run("ls-tree", "-r", "-z", "-l", sha)
+        raw.split("\0").filter_map do |line|
+          meta, path = line.split("\t", 2)
+          mode, type, blob, size = meta.split(" ")
+          next unless type == "blob" && mode != "120000" && path
+
+          Entry.new(path: path.dup.force_encoding(Encoding::UTF_8), blob: blob, size: size.to_i)
+        end
+      end
+
+      def blob(id) = run("cat-file", "blob", id)
+
+      private
+
+      def run(*args, chomp: false, allow_failure: false)
+        out, err, status = Open3.capture3("git", "-C", @root, *args, binmode: true)
+        unless status.success?
+          return nil if allow_failure
+
+          raise ConfigError, "git #{args.first} failed: #{err.to_s.strip.lines.first.to_s.strip}"
+        end
+
+        chomp ? out.strip : out
+      rescue Errno::ENOENT
+        raise ConfigError, "git isn't installed or isn't on the PATH"
+      end
+    end
+  end
+end

data/lib/dialecto_rails/scan/worktree.rb

@@ -0,0 +1,41 @@
+require "digest"
+require "find"
+require_relative "git"
+
+module DialectoRails
+  module Scan
+    # The `Git` reading interface over a plain folder: for `scan --worktree` (a testing escape hatch that sends
+    # what is on disk, not what is committed), and for sparse, blobless clones (the corpus), where `git
+    # cat-file` would fetch every missing blob from the network. Blob ids are git's, so the scan checksum still
+    # follows the bytes.
+    class Worktree
+      Entry = Git::Entry
+      SKIPPED = %w[.git node_modules].freeze
+
+      def initialize(root)
+        @root = root
+        @paths = {}
+      end
+
+      def entries(_sha = nil)
+        found = []
+        Find.find(@root) do |path|
+          if SKIPPED.include?(File.basename(path)) then Find.prune
+          elsif File.file?(path) && !File.symlink?(path)
+            size = File.size(path)
+            found << Entry.new(path: path.delete_prefix("#{@root}/"), blob: path, size: size)
+          end
+        end
+        found.sort_by(&:path)
+      end
+
+      # The id is the file's path here; `blob_id` gives git's id for the bytes, for the checksum.
+      def blob(id) = File.binread(id)
+
+      def blob_id(id)
+        bytes = File.binread(id)
+        Digest::SHA1.hexdigest("blob #{bytes.bytesize}\0".b + bytes)
+      end
+    end
+  end
+end