yuno-proofreader 0.1.0

data/lib/yuno/proofreader/cli/init_command.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Yuno
+  module Proofreader
+    # The command that starts the settings file of a site: init.
+    module InitCommand
+      EXAMPLE = File.expand_path("../../../../proofreader.example.yml", __dir__)
+      SWITCHES = %w[template yes offline].freeze
+      VALUES = %w[website business audience tone sitemap].freeze
+      LISTS = %w[language note skip-path rule ignore-term difference].freeze
+      HEADER = ["Settings of yuno-proofreader, written by `yuno-proofreader init`.",
+                "Every setting is explained in the template: run `yuno-proofreader init --template`.",
+                "`yuno-proofreader settings` shows what an audit still needs."].freeze
+
+      private
+
+      def init(args)
+        flags = Flags.parse(args, switches: SWITCHES, values: VALUES, lists: LISTS)
+        problem = init_problem(flags)
+        return usage_error(problem) if problem
+
+        init_flow(flags)
+        0
+      end
+
+      def init_problem(flags) = flags.problem || ("Too many arguments for init" if flags.rest.size > 1)
+
+      # Without --template the interview runs. With --template and no file name the template is only shown, and
+      # with a file name it is written there.
+      def init_flow(flags)
+        path = flags.rest.first
+        return init_interview(path || CLI::DEFAULT_SITE_FILE, flags) unless flags.switches.key?("template")
+
+        path ? init_template(path) : print_template
+      end
+
+      # With no file name the template is only shown, so it can be read, or saved with a redirect.
+      def print_template = @out.write(example_text)
+
+      def init_template(path)
+        create_file(path, example_text)
+        @out.puts "Wrote #{path}. It is a template: every value that starts with [FILL IN] is for you to replace.",
+                  "Then run: yuno-proofreader settings #{path}"
+      end
+
+      def init_interview(path, flags)
+        ensure_free(path)
+        interview = Init::Interview.new(flags:, ask: Init::Ask.new(input: @input, out: @out),
+                                        web: Init::Web.new(http: http_client), out: @out,
+                                        offline: flags.switches.key?("offline"), yes: flags.switches.key?("yes"))
+        settings = interview.call
+        site = Site.from_hash(settings)
+        create_file(path, SettingsFile.render(settings, header: HEADER))
+        init_lines(path, site).each { |line| @out.puts line }
+      end
+
+      def ensure_free(path) = (raise ConfigError, taken_message(path) if File.exist?(path))
+
+      def taken_message(path)
+        "#{path} already exists, so it was left as it is. Delete it first, or choose another name: " \
+          "yuno-proofreader init NAME.yml"
+      end
+
+      # Writes the file, and never over one that is already there.
+      def create_file(path, text)
+        File.open(path, File::WRONLY | File::CREAT | File::EXCL) { |file| file.write(text) }
+      rescue Errno::EEXIST
+        raise ConfigError, taken_message(path)
+      rescue SystemCallError => e
+        raise ConfigError, "Could not write #{path}: #{e.message}"
+      end
+
+      def example_text
+        File.read(EXAMPLE)
+      rescue SystemCallError
+        raise Error, "The template settings file is missing from this installation (#{EXAMPLE})."
+      end
+
+      # ---- what is printed afterwards ----
+
+      def init_lines(path, site)
+        problems = Array(site.audit_problems)
+        suffix = path == CLI::DEFAULT_SITE_FILE ? "" : " #{path}"
+        ["", "Wrote #{path}.", *readiness(problems), "", "Outside this file you also need:", *environment_lines, "",
+         "Next:", *next_steps(suffix)]
+      end
+
+      def readiness(problems)
+        return ["It is ready for an audit."] if problems.empty?
+
+        ["Before an audit can run, this is still missing:", *problems.map { |problem| "  - #{problem}" }]
+      end
+
+      def environment_lines
+        keys = Llm::Providers.ids.map { |id| [Llm::Providers.resolve(id).api_key_env, "the API key of #{id}"] }
+        lines = [["SPREADSHEET_ID", "the id of your Google Sheet"], *keys].map do |name, meaning|
+          environment_line(name, meaning)
+        end
+        [*lines, "  Put them in a .env file in this folder, or export them.",
+         "  Google credentials: see the README, section \"Connecting to Google\""]
+      end
+
+      def environment_line(name, meaning)
+        state = @env[name].to_s.strip.empty? ? "not set" : "set"
+        "  #{name.ljust(18)} #{state.ljust(8)} (#{meaning})"
+      end
+
+      def next_steps(suffix)
+        ["  yuno-proofreader prepare#{suffix}         creates the tabs in your Google Sheet",
+         "  yuno-proofreader pages import#{suffix}    adds your pages to the sheet",
+         "  yuno-proofreader analyze#{suffix}         ranks the pages by importance",
+         "  yuno-proofreader audit --next#{suffix}    audits the most important page that is due"]
+      end
+    end
+  end
+end

data/lib/yuno/proofreader/cli/model_commands.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Yuno
+  module Proofreader
+    # The command that works with the model provider: models.
+    module ModelCommands
+      private
+
+      def models(args)
+        file, problem = single_file(args, "models")
+        return usage_error(problem) if problem
+
+        site = Site.load(file)
+        provider = Llm.provider_for(site, env: @env, transport: @llm_transport)
+        selection = Llm.models_for(site, provider.class)
+        used = selection.names.map { |name| provider.normalize(name) }
+        print_models(provider, provider.models, used, selection.source)
+        0
+      end
+
+      def print_models(provider, available, used, source)
+        @out.puts "Models your #{provider.class.id} key can use for text generation:"
+        available.each { |name| @out.puts "  #{name}#{'  (in use)' if used.include?(name)}" }
+        origin = source == :settings ? "from your settings" : "built-in default"
+        @out.puts "", "In use (#{origin}): #{used.join(', ')}"
+        missing = used - available
+        return if missing.empty?
+
+        @out.puts "Not available to this key: #{missing.join(', ')}. A model that fails is skipped, " \
+                  "so set models in proofreader.yml to the ones you want."
+      end
+    end
+  end
+end

data/lib/yuno/proofreader/cli/queue_commands.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Yuno
+  module Proofreader
+    # The commands that decide which page to audit next: queue, and the batch form of audit (audit --next).
+    module QueueCommands
+      MAX_COUNT = 500
+      COUNT_FLAG = /\A--count(=|\z)/
+
+      private
+
+      def queue(args)
+        count, remaining, problem = take_count(args)
+        return usage_error(problem) if problem
+
+        options, rest, unknown = split_args(remaining, %w[all])
+        problem = queue_args_problem(rest, unknown)
+        return usage_error(problem) if problem
+
+        site = Site.load(rest.first || CLI::DEFAULT_SITE_FILE)
+        picks = agenda_for(site, store_for(site))
+        report = Audit::AgendaReport.new(picks, shown: count || Audit::AgendaReport::SHOWN,
+                                                everything: options.key?("all"))
+        show_lines(report.lines)
+      end
+
+      def queue_args_problem(rest, unknown)
+        return "Unknown option: #{unknown.first}" unless unknown.empty?
+
+        "Too many arguments for queue" if rest.size > 1
+      end
+
+      # Takes --count=N or --count N out of the arguments. Returns the number, the other arguments and a problem.
+      def take_count(args)
+        remaining = args.dup
+        index = remaining.index { |arg| arg.match?(COUNT_FLAG) }
+        return [nil, remaining, nil] unless index
+
+        flag = remaining.delete_at(index)
+        number = Integer((flag[/\A--count=(.*)\z/, 1] || remaining.delete_at(index)).to_s, 10, exception: false)
+        return [number, remaining, nil] if number&.between?(1, MAX_COUNT)
+
+        [nil, remaining, "--count needs a whole number from 1 to #{MAX_COUNT}"]
+      end
+
+      def agenda_for(site, store)
+        Audit::Agenda.call(records: store.pages, cadence: site.cadence, now: Time.now.utc)
+      end
+
+      def show_lines(lines)
+        lines.each { |line| @out.puts line }
+        0
+      end
+
+      # The model clients are built first, so a missing API key stops the command before anything is read.
+      def audit_batch(site, options, count)
+        store = store_for(site)
+        runner = audit_runner(site, store)
+        picks = agenda_for(site, store)
+        pool = options.key?("include-not-due") ? picks : picks.select(&:due?)
+        chosen = pool.first(count || 1)
+        if chosen.empty?
+          log.info("nothing is due", pages: picks.size)
+          return show_lines(Audit::AgendaReport.new(picks).lines)
+        end
+
+        run_batch(runner, store, chosen, picks, options)
+      end
+
+      def run_batch(runner, store, chosen, picks, options)
+        batch = Audit::Batch.new(runner:, store:, progress: ->(message) { @out.puts message }, log:)
+        dry_run = options.key?("dry-run")
+        outcome = batch.call(chosen, dry_run:, force: options.key?("force"))
+        still_due = [picks.count(&:due?) - outcome.entries.size, 0].max
+        log_batch(outcome, still_due:, dry_run:)
+        show_lines(Audit::BatchReport.new(outcome, dry_run:, still_due:, verbose: options.key?("verbose")).lines)
+        outcome.stopped ? 1 : 0
+      end
+
+      def log_batch(outcome, still_due:, dry_run:)
+        statuses = outcome.entries.map(&:status).tally
+        calls = outcome.entries.filter_map(&:result).flat_map(&:calls)
+        log.info("batch finished", pages: outcome.entries.size, audited: statuses.fetch(:audited, 0),
+                                   skipped: statuses.fetch(:skipped, 0), failed: statuses.fetch(:failed, 0),
+                                   still_due:, dry_run:, stopped: outcome.stopped, **Llm::Usage.of(calls))
+      end
+    end
+  end
+end

data/lib/yuno/proofreader/cli/sheet_commands.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Yuno
+  module Proofreader
+    # The commands that work with the Google Sheet: prepare and pages import.
+    module SheetCommands
+      private
+
+      def prepare(args)
+        file, problem = single_file(args, "prepare")
+        return usage_error(problem) if problem
+
+        store_for(Site.load(file)).prepare.each { |line| @out.puts line }
+        0
+      end
+
+      def pages(args)
+        action, *rest = args
+        return usage_error("Unknown pages command: #{action.inspect}. Try: pages import") unless action == "import"
+
+        file, problem = single_file(rest, "pages import")
+        return usage_error(problem) if problem
+
+        import_pages(Site.load(file))
+      end
+
+      def import_pages(site)
+        loaded = Sitemap::Loader.call(site, http_client)
+        return refuse_import(site, loaded) unless loaded.pairing.resolved?
+
+        result = Sitemap::Importer.call(loaded.pairing, store_for(site), site)
+        print_import(result, loaded.warnings)
+        0
+      end
+
+      def refuse_import(site, loaded)
+        Sitemap::Report.new(site, loaded).lines.each { |line| @out.puts line }
+        @out.puts "", "Nothing was written to the sheet."
+        1
+      end
+
+      def print_import(result, warnings)
+        @out.puts "Added #{result.added} pages to the Pages tab (#{result.existing} were already there)."
+        if result.gone.positive?
+          @out.puts "#{result.gone} pages in the sheet are no longer in the sitemap and were left alone."
+        end
+        return if warnings.empty?
+
+        @out.puts "", "Warnings:", *warnings.map { |warning| "  - #{warning}" }
+      end
+
+      def store_for(site)
+        @store || Store::Sheets.connect(Config.from_env(@env), site)
+      end
+    end
+  end
+end

data/lib/yuno/proofreader/cli.rb

@@ -0,0 +1,218 @@
+# frozen_string_literal: true
+
+module Yuno
+  module Proofreader
+    # Command-line entry point: parses arguments and returns an exit code.
+    class CLI
+      include SheetCommands
+      include ModelCommands
+      include AuditCommands
+      include AnalysisCommands
+      include InitCommand
+      prepend CommandLog
+      include QueueCommands
+
+      DEFAULT_SITE_FILE = "proofreader.yml"
+      STATE_LABELS = { set: "set", empty: "not set", placeholder: "still the [FILL IN] example text" }.freeze
+      COMMANDS = {
+        "help" => :help, "-h" => :help, "--help" => :help,
+        "version" => :version, "-v" => :version, "--version" => :version,
+        "doctor" => :doctor, "sitemap" => :sitemap, "fetch" => :fetch, "settings" => :settings,
+        "models" => :models, "prepare" => :prepare, "pages" => :pages, "prompt" => :prompt,
+        "analyze" => :analyze, "init" => :init, "queue" => :queue, "audit" => :audit
+      }.freeze
+      USAGE = <<~TEXT
+        Usage: yuno-proofreader <command>
+
+        Commands:
+          sitemap [FILE] [--all]   Read the sitemap of the site described in FILE (default: proofreader.yml)
+                                   and show how its pages were paired by language
+          fetch PAGE [FILE] [--html=LANG]
+                                   Download all language versions of one page and show how the tool sees them.
+                                   PAGE is a name from `sitemap --all`, or any address of the page
+          prepare [FILE]           Create the tabs the tool needs in your Google Sheet (safe to run again)
+          pages import [FILE]      Add the pages of the sitemap to the Pages tab of the sheet
+          models [FILE]            List the models your API key can use for text generation, and which are in use
+          init [FILE] [OPTIONS]    Ask about your site and write a settings file (default proofreader.yml).
+                                   --template shows the full commented template, or with a FILE writes it there.
+                                   For scripts: --website, --language CODE[:PREFIX], --note CODE=TEXT, --business,
+                                   --audience, --tone, --sitemap, --skip-path, --rule, --ignore-term, --difference.
+                                   --yes accepts what was detected, --offline makes no request. Does not overwrite a file
+          audit PAGE [FILE] [--dry-run] [--force] [--verbose]
+                                   Audit one page: ask the model, compare the findings with the suggestions in the
+                                   sheet and update the sheet. --dry-run writes nothing (the model is still called
+                                   and costs the same), --force audits a page that has not changed, --verbose
+                                   lists everything that was decided
+          audit --next [FILE] [--count=N] [--include-not-due] [--dry-run] [--force] [--verbose]
+                                   Audit the pages that are due, the most important first (default 1 page)
+          queue [FILE] [--count=N] [--all]
+                                   Show which pages are due for an audit and why. Calls no model and fetches no page
+          analyze [FILE] [--dry-run] [--no-ai] [--reuse-ai]
+                                   Rank every page by importance and write it to the Pages tab. --dry-run writes
+                                   nothing, --no-ai skips the models, --reuse-ai takes their judgement from the
+                                   last run instead of asking again
+          settings [FILE]          Show which settings that describe your site are filled in, and whether an
+                                   audit can start
+          doctor                   Check that the required environment variables are set
+          version                  Print the version
+          help                     Show this help
+      TEXT
+
+      def self.run(argv, **) = new(**).run(argv)
+
+      def initialize(out: $stdout, err: $stderr, env: ENV, client: nil, store: nil, llm_transport: nil,
+                     input: $stdin)
+        @out = out
+        @err = err
+        @env = env
+        @http_client = client
+        @store = store
+        @llm_transport = llm_transport
+        @input = input
+      end
+
+      # Returns the exit code: 0 success, 1 runtime or configuration error, 2 usage error.
+      def run(argv)
+        command, *args = argv
+        return help if command.nil?
+
+        action = COMMANDS[command]
+        return usage_error("Unknown command: #{command}") unless action
+
+        send(action, args)
+      rescue Error => e
+        @err.puts "Error: #{e.message}"
+        1
+      end
+
+      private
+
+      def help(_args = nil)
+        @out.puts USAGE
+        0
+      end
+
+      def version(_args = nil)
+        @out.puts "yuno-proofreader #{VERSION}"
+        0
+      end
+
+      def doctor(_args = nil)
+        config = Config.from_env(@env)
+        @out.puts "Configuration looks complete."
+        @out.puts config.inspect
+        0
+      end
+
+      def sitemap(args)
+        options, rest, unknown = split_args(args, %w[all])
+        return usage_error("Unknown option: #{unknown.first}") unless unknown.empty?
+        return usage_error("Too many arguments for sitemap") if rest.size > 1
+
+        site = Site.load(rest.first || DEFAULT_SITE_FILE)
+        result = Sitemap::Loader.call(site, http_client)
+        Sitemap::Report.new(site, result).lines(all: options.key?("all")).each { |line| @out.puts line }
+        result.pairing.resolved? ? 0 : 1
+      end
+
+      def fetch(args)
+        options, rest, unknown = split_args(args, %w[html])
+        problem = fetch_args_problem(options, rest, unknown)
+        return usage_error(problem) if problem
+
+        site = Site.load(rest[1] || DEFAULT_SITE_FILE)
+        language = options["html"]
+        return usage_error("Unknown language for --html: #{language}") if language && !site.languages.include?(language)
+
+        show_page(site, rest.first, language)
+      end
+
+      def fetch_args_problem(options, rest, unknown)
+        return "Unknown option: #{unknown.first}" unless unknown.empty?
+        return "--html needs a language, for example --html=de" if options["html"] == true
+        return "fetch needs a page name or address" if rest.empty?
+
+        "Too many arguments for fetch" if rest.size > 2
+      end
+
+      def settings(args)
+        file, problem = single_file(args, "settings")
+        return usage_error(problem) if problem
+
+        site = Site.load(file)
+        settings_lines(site, file).each { |line| @out.puts line }
+        site.audit_problems.empty? ? 0 : 1
+      end
+
+      def settings_lines(site, file)
+        shown = site.prefixes.map { |code, prefix| prefix.empty? ? code : "#{code} (#{prefix})" }.join(", ")
+        problems = site.audit_problems
+        [
+          "Settings file: #{file}", "Website: #{site.website}", "Languages: #{shown}, default #{site.default_language}",
+          "", *site.states.map { |name, state| "  #{name.ljust(26)}#{STATE_LABELS.fetch(state)}" }, "",
+          problems.empty? ? "Ready for an audit." : "Not ready for an audit (sitemap and fetch do not need this):",
+          *problems.map { |problem| "  - #{problem}" }
+        ]
+      end
+
+      def show_page(site, query, language)
+        page = find_page(Sitemap::Loader.call(site, http_client).pairing, query)
+        fetched = Pages::Fetcher.new(site, http_client).fetch(page)
+        Pages::Report.new(fetched).lines.each { |line| @out.puts line }
+        print_html(fetched, language) if language
+        fetched.complete? ? 0 : 1
+      end
+
+      def find_page(pairing, query)
+        unless pairing.resolved?
+          raise Error, "The pages could not be paired. Run the sitemap command and fix what it reports."
+        end
+
+        pairing.pages.find { |page| page.name == query || page.urls.value?(query) } ||
+          raise(Error, "No page named #{query.inspect}. List the names with: yuno-proofreader sitemap --all")
+      end
+
+      def print_html(fetched, language)
+        snapshot = fetched.snapshot(language)
+        return @err.puts("No #{language} version to show.") unless snapshot&.ok?
+
+        @out.puts "", "--- trimmed HTML (#{language}) ---", snapshot.html
+      end
+
+      # Splits options (--name or --name=value) from positional arguments.
+      def split_args(args, known)
+        flags, positional = args.partition { |arg| arg.start_with?("-") }
+        options = {}
+        unknown = []
+        flags.each do |flag|
+          key, value = flag.sub(/\A-+/, "").split("=", 2)
+          if known.include?(key)
+            options[key] = value || true
+          else
+            unknown << flag
+          end
+        end
+        [options, positional, unknown]
+      end
+
+      # One optional settings file and nothing else. Returns [path, nil], or [nil, what is wrong].
+      def single_file(args, command)
+        flags, rest = args.partition { |arg| arg.start_with?("-") }
+        return [nil, "Unknown option: #{flags.first}"] unless flags.empty?
+        return [nil, "Too many arguments for #{command}"] if rest.size > 1
+
+        [rest.first || DEFAULT_SITE_FILE, nil]
+      end
+
+      def http_client
+        @http_client ||= Http::Client.new
+      end
+
+      def usage_error(message)
+        @err.puts message
+        @err.puts USAGE
+        2
+      end
+    end
+  end
+end

data/lib/yuno/proofreader/config.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Yuno
+  module Proofreader
+    # Settings that come from the environment: ids, never site content. The key of a model provider is not
+    # here: each provider names its own variable, and it is read when the provider is used. LOG_LEVEL is
+    # checked here too, so doctor can show it, and Log does the reading.
+    class Config < Data.define(:spreadsheet_id, :log_level)
+      REQUIRED = %w[SPREADSHEET_ID].freeze
+      LOG_LEVELS = %w[debug info warn error].freeze
+
+      def self.from_env(env = ENV)
+        missing = REQUIRED.select { |name| env[name].to_s.strip.empty? }
+        raise ConfigError, "Missing environment variables: #{missing.join(', ')}" unless missing.empty?
+
+        new(spreadsheet_id: env["SPREADSHEET_ID"].strip, log_level: Log.level_from(env["LOG_LEVEL"]))
+      end
+
+      def inspect
+        "#<#{self.class.name} spreadsheet_id=#{spreadsheet_id.inspect} log_level=#{log_level}>"
+      end
+      alias to_s inspect
+    end
+  end
+end

data/lib/yuno/proofreader/context.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Yuno
+  module Proofreader
+    # What the model should know about the site, read from the settings file and sent with every page.
+    # Everything is optional, except that the audit needs a business description.
+    class Context < Data.define(:business, :audience, :tone, :rules, :ignore_terms, :intentional_differences)
+      TEXTS = %w[business audience tone].freeze
+      LISTS = %w[rules ignore_terms intentional_differences].freeze
+      KEYS = (TEXTS + LISTS).freeze
+      PLACEHOLDER = /\[fill in\]/i
+      MAX_TEXT = 500
+      MAX_ITEM = 200
+      MAX_ITEMS = 50
+
+      def self.from_hash(raw)
+        texts = TEXTS.to_h { |key| [key.to_sym, text(raw[key], key, MAX_TEXT)] }
+        lists = LISTS.to_h { |key| [key.to_sym, list(raw[key], key)] }
+        new(**texts, **lists)
+      end
+
+      def self.placeholder?(value) = value.to_s.match?(PLACEHOLDER)
+
+      # :set, :empty (nothing given) or :placeholder (the [FILL IN] example text is still there).
+      def self.state_of(value)
+        items = Array(value)
+        return :empty if items.all?(&:empty?)
+
+        items.any? { |item| placeholder?(item) } ? :placeholder : :set
+      end
+
+      # One piece of text, trimmed. Nothing at all becomes an empty string.
+      def self.text(value, label, max)
+        raise ConfigError, "Site: #{label} must be plain text" if value.is_a?(Hash) || value.is_a?(Array)
+
+        cleaned = value.to_s.strip
+        raise ConfigError, "Site: #{label} is longer than #{max} characters" if cleaned.length > max
+
+        cleaned
+      end
+
+      # A list of texts. A single text counts as a list of one. Blank and repeated entries are dropped.
+      def self.list(value, label)
+        items = Array(value).map { |item| text(item, "an entry of #{label}", MAX_ITEM) }.reject(&:empty?).uniq
+        raise ConfigError, "Site: #{label} has more than #{MAX_ITEMS} entries" if items.size > MAX_ITEMS
+
+        items
+      end
+
+      def states
+        to_h.transform_keys(&:to_s).transform_values { |value| self.class.state_of(value) }
+      end
+    end
+  end
+end

data/lib/yuno/proofreader/env_file.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Yuno
+  module Proofreader
+    # Reads the settings that live outside proofreader.yml (API keys, the id of the sheet, Google credentials) from
+    # a .env file, so they do not have to be typed into the shell. A variable that is already set wins over the file
+    module EnvFile
+      DEFAULT = ".env"
+      CHOICE = "PROOFREADER_ENV_FILE"
+      LINE = /\A(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)\z/
+      DOUBLE = /\A"((?:[^"\\]|\\.)*)"\s*(?:#.*)?\z/
+      SINGLE = /\A'([^']*)'\s*(?:#.*)?\z/
+      ESCAPES = { "n" => "\n", "t" => "\t" }.freeze
+
+      # path: the file. names: the variables it set. skipped: the numbers of the lines that were not NAME=VALUE.
+      # loose: whether other users can read the file.
+      Loaded = Data.define(:path, :names, :skipped, :loose) do
+        def warnings = [skipped_warning, loose_warning].compact
+
+        def skipped_warning
+          return if skipped.empty?
+
+          "Ignored #{skipped.size} line(s) of #{path} that are not NAME=VALUE (line #{skipped.first(5).join(', ')})."
+        end
+
+        def loose_warning = ("#{path} can be read by other users. Run: chmod 600 #{path}" if loose)
+      end
+
+      module_function
+
+      # Loads the file into env without replacing what is already set. Returns what was loaded, or nil when there
+      # is no file to load. A file named in PROOFREADER_ENV_FILE that does not exist is an error.
+      def load(env = ENV, path: nil)
+        chosen = path || env[CHOICE].to_s.strip
+        file = chosen.empty? ? DEFAULT : chosen
+        unless File.file?(file)
+          raise ConfigError, "#{CHOICE} points to #{file}, which is not a file." unless chosen.empty?
+
+          return
+        end
+
+        pairs, skipped = parse(File.read(file))
+        names = pairs.keys.select { |name| env[name].to_s.empty? }
+        names.each { |name| env[name] = pairs[name] }
+        Loaded.new(path: file, names:, skipped:, loose: loose?(file))
+      end
+
+      # [the NAME=VALUE pairs, the numbers of the lines that were neither a pair, empty nor a comment]
+      def parse(text)
+        pairs = {}
+        skipped = []
+        text.each_line.with_index(1) do |raw, number|
+          line = raw.strip
+          next if line.empty? || line.start_with?("#")
+
+          match = LINE.match(line)
+          match ? pairs[match[1]] = value_of(match[2]) : skipped << number
+        end
+        [pairs, skipped]
+      end
+
+      def value_of(raw)
+        text = raw.strip
+        if (match = DOUBLE.match(text)) then unescape(match[1])
+        elsif (match = SINGLE.match(text)) then match[1]
+        else text.sub(/\s+#.*\z/, "")
+        end
+      end
+
+      def unescape(text) = text.gsub(/\\(.)/) { ESCAPES.fetch(Regexp.last_match(1), Regexp.last_match(1)) }
+
+      # Whether other users can read the file. Not checked where there are no unix permissions.
+      def loose?(file) = File::ALT_SEPARATOR.nil? && File.stat(file).mode.anybits?(0o077)
+    end
+  end
+end