slipway 0.1.0

data/lib/slipway/git/runner.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+module Slipway
+  module Git
+    # The one place that spawns git.
+    class Runner
+      Result = Data.define(:status, :out, :err) do
+        def success? = status.zero?
+      end
+
+      DEFAULT_BINARY = 'git'
+      DEFAULT_TIMEOUT = 10.0
+      # Git deletes its lock files when TERM arrives, and KILL cannot be caught: a git killed
+      # while it updates refs would leave locks that fail every later command that moves them.
+      TERM_GRACE = 1.0
+      # Shell convention for a process ended by a signal: 128 plus the signal number.
+      SIGNAL_STATUS_BASE = 128
+      CEILING_VARIABLE = 'GIT_CEILING_DIRECTORIES'
+      PROTOCOL_VARIABLE = 'GIT_ALLOW_PROTOCOL'
+      # Absolute, so no program named false earlier on PATH stands in for it; macOS has only
+      # /usr/bin/false.
+      FALSE_PROGRAMS = %w[/usr/bin/false /bin/false].freeze
+
+      # LC_ALL=C keeps messages parseable; prompts and optional index writes are disabled; every
+      # repository-selecting variable is unset so an inherited GIT_DIR cannot redirect a query.
+      ENVIRONMENT = {
+        'LC_ALL' => 'C',
+        'LANGUAGE' => nil,
+        'GIT_TERMINAL_PROMPT' => '0',
+        'GIT_OPTIONAL_LOCKS' => '0',
+        'GIT_PAGER' => 'cat',
+        'GIT_DIR' => nil,
+        'GIT_WORK_TREE' => nil,
+        'GIT_INDEX_FILE' => nil,
+        'GIT_NAMESPACE' => nil,
+        'GIT_OBJECT_DIRECTORY' => nil,
+        'GIT_ALTERNATE_OBJECT_DIRECTORIES' => nil
+      }.freeze
+
+      # A path that names no program still fails the prompt, which is all the askpass is for.
+      def self.false_program(candidates = FALSE_PROGRAMS) = candidates.find { File.executable?(it) } || candidates.first
+
+      FALSE_PROGRAM = false_program
+
+      # Every credential or host key question is answered by false, so git and ssh fail at once
+      # instead of waiting on a prompt nobody sees. SSH_ASKPASS_REQUIRE=force (OpenSSH 8.4 and
+      # later) sends every ssh prompt to the askpass, with or without DISPLAY, so ssh never reads
+      # /dev/tty.
+      NETWORK_ENVIRONMENT = {
+        'GIT_ASKPASS' => FALSE_PROGRAM,
+        'SSH_ASKPASS' => FALSE_PROGRAM,
+        'SSH_ASKPASS_REQUIRE' => 'force'
+      }.freeze
+
+      # No gc or maintenance started on the user's behalf, and no bundle download from a URL the
+      # server advertises.
+      NETWORK_CONFIG = %w[-c gc.auto=0 -c maintenance.auto=false -c transfer.bundleURI=false].freeze
+
+      # GIT_ALLOW_PROTOCOL refuses every transport it does not list, including file and ext.
+      def self.network_environment(protocols) = NETWORK_ENVIRONMENT.merge(PROTOCOL_VARIABLE => protocols.join(':'))
+
+      attr_reader :binary, :timeout
+
+      def initialize(binary: DEFAULT_BINARY, timeout: DEFAULT_TIMEOUT)
+        @binary = binary
+        @timeout = timeout
+      end
+
+      # Returns a Result whatever git's exit status is. Raises NotInstalled when the binary
+      # cannot be started and Timeout when `timeout` seconds pass. `env` adds variables to the
+      # child; it cannot change the ones ENVIRONMENT pins.
+      # A git still running when the block unwinds for any other reason, such as an
+      # interrupt, is killed with its process group instead of outliving the command.
+      def run(path, *, timeout: @timeout, env: {})
+        require 'open3'
+        directory = File.expand_path(path)
+        # Open3 spawns git before this block's ensure is armed, so an interrupt or a Thread#kill
+        # (not an Exception, hence Object) landing in between would leave it running; both are
+        # held until the block runs.
+        Thread.handle_interrupt(Object => :never) do
+          Open3.popen3(environment(directory, env), @binary, '-C', directory, *, pgroup: true) do |stdin, *pipes, wait|
+            stdin.close
+            readers = pipes.map { reader(it) }
+            Thread.handle_interrupt(Object => :immediate) { collect(wait, readers, directory, timeout) }
+          ensure
+            reap(wait, Array(readers))
+          end
+        end
+      rescue Errno::ENOENT
+        raise NotInstalled.new(directory, binary: @binary)
+      end
+
+      private
+
+      # A helper git started can hold a pipe open after git exits, so the deadline covers the
+      # pipes too.
+      def collect(wait, readers, directory, timeout)
+        unless settled?([wait, *readers], timeout)
+          stop(wait, readers)
+          raise Timeout.new(directory, seconds: timeout)
+        end
+        out, err = readers.map { scrub(it.value) }
+        Result.new(status: exit_status(wait.value), out:, err:)
+      end
+
+      # Discovery must not climb above the registered directory, or a subdirectory of some
+      # other repository would report that repository's state. Git compares real paths, so
+      # the ceiling is the real parent.
+      def environment(directory, extra)
+        extra.merge(ENVIRONMENT, CEILING_VARIABLE => File.dirname(realpath(directory)))
+      end
+
+      def realpath(directory)
+        File.realpath(directory)
+      rescue SystemCallError
+        directory
+      end
+
+      # Drains one pipe on its own thread so a chatty command cannot deadlock on a full buffer.
+      # A new thread inherits the interrupts run holds; the read lets them in again so stop can
+      # kill it. Its result is only taken through value, which re-raises, so a reader whose pipe
+      # is closed under it stays quiet instead of printing a thread trace.
+      def reader(io)
+        io.binmode
+        Thread.new do
+          Thread.current.report_on_exception = false
+          Thread.handle_interrupt(Object => :immediate) { io.read }
+        end
+      end
+
+      def settled?(threads, timeout)
+        deadline = clock + timeout
+        threads.all? { it.join([deadline - clock, 0].max) }
+      end
+
+      def clock = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+      # This runs with interrupts held, and the thread Open3 waits for git on inherited that
+      # mask, so neither another interrupt nor process exit can end them while git lives.
+      def reap(wait, readers)
+        stop(wait, readers) if wait.alive? || readers.any?(&:alive?)
+      end
+
+      # KILL follows as soon as git exits or the grace ends, so a helper that ignores TERM dies
+      # even when git has already exited. The readers are stopped, not drained: a helper that left
+      # the group can hold a pipe open forever.
+      def stop(wait, readers)
+        signal(wait, 'TERM')
+        wait.join(TERM_GRACE)
+        signal(wait, 'KILL')
+        wait.join
+        readers.each { it.kill.join }
+      end
+
+      # macOS answers EPERM, not ESRCH, when every process left in the group has exited but is
+      # not yet reaped. git runs as this user, so either answer means nothing is left to signal,
+      # and raising would replace the interrupt, kill or timeout that is ending the run.
+      def signal(wait, name)
+        Process.kill(name, -wait.pid)
+      rescue Errno::ESRCH, Errno::EPERM
+        nil
+      end
+
+      def exit_status(process)
+        process.exitstatus || (SIGNAL_STATUS_BASE + process.termsig)
+      end
+
+      # Paths in git output are raw bytes; invalid sequences become U+FFFD so every consumer
+      # gets a valid UTF-8 string.
+      def scrub(bytes)
+        bytes.force_encoding(Encoding::UTF_8).scrub
+      end
+    end
+  end
+end

data/lib/slipway/git/status.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module Slipway
+  module Git
+    Status = Data.define(:branch, :head, :upstream, :ahead, :behind, :upstream_gone,
+                         :staged, :unstaged, :untracked, :conflicted, :stashes) do
+      # Parses the output of `git status --porcelain=v2 --branch --show-stash -z`.
+      def self.parse(text) = Porcelain.new.parse(text)
+
+      def initialize(head:, branch: 'main', upstream: nil, ahead: nil, behind: nil, upstream_gone: false,
+                     staged: 0, unstaged: 0, untracked: 0, conflicted: 0, stashes: 0)
+        super
+      end
+
+      def detached? = branch.nil?
+
+      def unborn? = head.nil?
+
+      def upstream_gone? = upstream_gone
+
+      def tracking? = !detached? && !upstream.nil? && !upstream_gone?
+
+      # Stashes do not count.
+      def clean? = staged.zero? && unstaged.zero? && untracked.zero? && conflicted.zero?
+    end
+
+    class Porcelain
+      INITIAL = '(initial)'
+      DETACHED = '(detached)'
+      # Porcelain prints the full object id; the table shows what `git log --oneline` would.
+      ABBREVIATION = 7
+      UNCHANGED = '.'
+
+      def initialize
+        @branch = nil
+        @head = nil
+        @upstream = nil
+        @ahead = nil
+        @behind = nil
+        @position_seen = false
+        @stashes = 0
+        @counts = Hash.new(0)
+      end
+
+      def parse(text)
+        records = text.split("\0")
+        until records.empty?
+          record = records.shift
+          # A rename or copy record is followed by the original path as its own field.
+          records.shift if record.start_with?('2 ')
+          consume(record)
+        end
+        status
+      end
+
+      private
+
+      def status
+        Status.new(branch: @branch, head: @head, upstream: @upstream, ahead: @ahead, behind: @behind,
+                   # git omits branch.ab when the upstream is set but its ref is gone.
+                   upstream_gone: !@upstream.nil? && !@position_seen,
+                   staged: @counts[:staged], unstaged: @counts[:unstaged],
+                   untracked: @counts[:untracked], conflicted: @counts[:conflicted], stashes: @stashes)
+      end
+
+      def consume(record)
+        case record
+        when /\A# / then header(record)
+        when /\A[12] / then change(record[2], record[3])
+        when /\Au / then @counts[:conflicted] += 1
+        when /\A\? / then @counts[:untracked] += 1
+        end
+      end
+
+      def header(record)
+        key, value = record.delete_prefix('# ').split(' ', 2)
+        if key == 'stash'
+          @stashes = Integer(value)
+        elsif key.start_with?('branch.')
+          branch(key.delete_prefix('branch.'), value)
+        end
+      end
+
+      def branch(field, value)
+        case field
+        when 'oid' then @head = value[0, ABBREVIATION] unless value == INITIAL
+        when 'head' then @branch = value unless value == DETACHED
+        when 'upstream' then @upstream = value
+        when 'ab' then position(value)
+        end
+      end
+
+      # `+<ahead> -<behind>`; git prints `+? -?` when it was told not to count.
+      def position(value)
+        @position_seen = true
+        @ahead, @behind = value.split.map { count(it) }
+      end
+
+      def count(token)
+        digits = token.delete_prefix('+').delete_prefix('-')
+        digits == '?' ? nil : Integer(digits)
+      end
+
+      def change(index, worktree)
+        @counts[:staged] += 1 unless index == UNCHANGED
+        @counts[:unstaged] += 1 unless worktree == UNCHANGED
+      end
+    end
+  end
+end

data/lib/slipway/git/url.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require_relative '../error'
+
+module Slipway
+  module Git
+    # Remote URLs: the forms slipway accepts (validate!, valid?) and the masking of credentials
+    # in any text that may quote one (redact).
+    module Url
+      # Callers decide whether the URL came from the command line or a file.
+      class Invalid < Slipway::Error; end
+
+      # The userinfo runs to the last "@" before the authority ends, so a password holding a raw
+      # "@" is covered whole.
+      USERINFO = %r{(?<scheme>[A-Za-z][A-Za-z0-9+.-]*)://(?<userinfo>[^\s/?#]+)@}
+      # Over http a token is often sent as the user name, so the whole userinfo is secret there,
+      # and in a scheme that carries http, such as git+https or persistent-https.
+      WHOLE_USERINFO = /(?:\A|[+-])https?\z/i
+      LEADING_USERINFO = /\A#{USERINFO}/
+      MASK = '***'
+
+      MAX = 2048
+      TEXT = /\A[^\p{C}\p{Z}]+\z/
+      HOST = /[A-Za-z0-9][A-Za-z0-9.-]*/
+      USER = /[A-Za-z0-9_][A-Za-z0-9._-]*/
+      # git reads "<name>::" as a transport helper and "<name>://" as a URL, so an scp-like path
+      # starting with either is not a path.
+      FORMS = [
+        %r{\A(?:ssh|https?|git)://(?:#{USER}@)?#{HOST}(?::\d{1,5})?/},
+        %r{\Afile://(?:#{HOST})?/},
+        %r{\A(?:#{USER}@)?#{HOST}:(?!:|//).}
+      ].freeze
+      # git takes "user:secret@host:path" as the host "user", but whoever reads it sees a password.
+      SCP_PASSWORD = %r{\A[^/@]*:(?!//)[^@]*@}
+      # A password holding "/", "?", "#" or whitespace ends the userinfo early for #redact and
+      # makes the remote invalid, so it is caught only once the remote is refused. A token before
+      # the "@" has no ":" to tell it from a user name, so a refused remote with an "@" past its
+      # scheme is never quoted.
+      URL_PASSWORD = %r{\A[A-Za-z][A-Za-z0-9+.-]*://[^@:/]*:.*@}m
+      AFTER_SCHEME_AT = %r{://[^@]*@}
+      RULE = 'scheme://host/path with scheme ssh, https, http, git or file, or [user@]host:path, where the ' \
+             'host is letters, digits, dots and dashes starting with a letter or digit; at most 2048 characters, ' \
+             'without whitespace or control characters'
+      CREDENTIALS = 'must not embed credentials; use a credential helper'
+
+      # `text` is free text, such as a line of git's stderr: only scheme://userinfo@ URLs change,
+      # so scp-like addresses (git@host:path) and e-mail addresses stay as they are.
+      def self.redact(text)
+        text.gsub(USERINFO) do
+          match = Regexp.last_match
+          "#{match[:scheme]}://#{mask(match[:scheme], match[:userinfo])}@"
+        end
+      end
+
+      # Drops what #redact would mask, so a remote read from a clone keeps its address and a
+      # credential helper supplies what was dropped.
+      def self.without_credentials(url)
+        url.sub(LEADING_USERINFO) do
+          match = Regexp.last_match
+          user = WHOLE_USERINFO.match?(match[:scheme]) ? '' : match[:userinfo].partition(':').first
+          user.empty? ? "#{match[:scheme]}://" : "#{match[:scheme]}://#{user}@"
+        end
+      end
+
+      # A remote is accepted only when #redact would leave it as it is, so describe, json and
+      # yaml can print it whole. The command line may label UTF-8 bytes as US-ASCII in the C
+      # locale, so the value is read, and returned, as UTF-8.
+      def self.validate!(url, field:)
+        text = url.dup.force_encoding(Encoding::UTF_8)
+        shown = text.scrub
+        raise Invalid, "#{field} #{CREDENTIALS}" if credentials?(shown)
+        return text if valid?(text)
+        raise Invalid, "#{field} #{CREDENTIALS}" if URL_PASSWORD.match?(shown)
+
+        quoted = AFTER_SCHEME_AT.match?(shown) ? field : shown.inspect
+        raise Invalid, "#{quoted} is not a valid remote URL: #{RULE}"
+      end
+
+      def self.mask(scheme, userinfo)
+        return MASK if WHOLE_USERINFO.match?(scheme)
+
+        user, colon, = userinfo.partition(':')
+        colon.empty? ? userinfo : "#{user}:#{MASK}"
+      end
+
+      def self.credentials?(text) = redact(text) != text || SCP_PASSWORD.match?(text)
+
+      def self.valid?(text)
+        text.valid_encoding? && text.size <= MAX && TEXT.match?(text) && FORMS.any? { it.match?(text) }
+      end
+
+      private_class_method :mask, :credentials?, :valid?
+    end
+  end
+end

data/lib/slipway/git.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative 'git/errors'
+require_relative 'git/url'
+require_relative 'git/branch_name'
+require_relative 'git/runner'
+require_relative 'git/status'
+require_relative 'git/commit'
+require_relative 'git/fetch_result'
+require_relative 'git/fast_forward'
+require_relative 'git/distance'
+require_relative 'git/reflog'
+require_relative 'git/move_back'
+require_relative 'git/repository'
+require_relative 'git/fake'
+
+module Slipway
+  module Git
+  end
+end

data/lib/slipway/inspector.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require_relative 'git'
+require_relative 'paths'
+require_relative 'plan'
+require_relative 'pool'
+require_relative 'state'
+
+module Slipway
+  # `status`, `commit` and `remote` are nil when git could not answer; `error` then holds the
+  # Git error and `state` its word. `fetched_at` is nil then too, and for a repository no fetch
+  # has reached. `operation` is the merge, rebase or other operation in progress, asked only of a
+  # project the plan would fast-forward. `pin` is how far HEAD is from spec.revision, a
+  # Git::Distance or nil when the repository lacks that commit, asked only of a pinned project
+  # whose HEAD is elsewhere.
+  Inspection = Data.define(:project, :status, :commit, :remote, :fetched_at, :state, :error, :operation, :pin) do
+    def initialize(operation: nil, pin: nil, **) = super
+
+    # A pin may name an annotated tag, which git peels to the commit it tags, so HEAD is also at
+    # the pin when git counts no commit between them.
+    def at_pin?
+      return false if commit.nil? || project.revision.nil?
+
+      commit.sha == project.revision || (!pin.nil? && pin.ahead.zero? && pin.behind.zero?)
+    end
+
+    def self.failed(project, error)
+      new(project:, status: nil, commit: nil, remote: nil, fetched_at: nil, state: State.for_error(error), error:)
+    end
+  end
+
+  # A leading ~ in a project path is `home`, the HOME of the environment the command runs in,
+  # so a manifest written as ~/dev/x means the same thing whoever runs it.
+  class Inspector
+    # One warning per distinct reason a project came back Unknown: the message without its
+    # path, so twenty projects without git raise one line.
+    Batch = Data.define(:inspections, :warnings)
+
+    DEFAULT_WORKERS = 8
+    UNKNOWN = 'Unknown'
+
+    def initialize(git:, clock:, home: Dir.home, workers: DEFAULT_WORKERS)
+      @git = git
+      @clock = clock
+      @home = home
+      @pool = Pool.new(workers:)
+    end
+
+    def workers = @pool.workers
+
+    # A relative path has no directory to be relative to and a path that is not a directory
+    # needs no git; both are Missing. Any other failure, git's or not, becomes the
+    # Inspection's error rather than escaping the worker.
+    def examine(project)
+      path = Paths.expand(project.path, home: @home)
+      return Inspection.failed(project, Git::RelativePath.new(path)) unless File.absolute_path?(path)
+      return Inspection.failed(project, Git::MissingPath.new(path)) unless File.directory?(path)
+
+      with_operation(with_pin(Inspection.new(project:, **query(path), error: nil), path), path)
+    rescue Git::Error => e
+      Inspection.failed(project, e)
+    rescue StandardError => e
+      Inspection.failed(project, Git::Error.new(path, "git could not be read: #{e.class}: #{e.message}"))
+    end
+
+    def examine_all(projects)
+      results = @pool.map(projects) { examine(it) }.freeze
+      Batch.new(inspections: results, warnings: collect_warnings(results))
+    end
+
+    private
+
+    def query(path)
+      status = @git.status(path)
+      commit = status.unborn? ? nil : @git.last_commit(path)
+      { status:, commit:, remote: @git.remote_url(path), fetched_at: @git.fetched_at(path),
+        state: State.derive(status) }
+    end
+
+    # One more spawn, paid only by a pinned project whose HEAD is not the pinned commit, and a
+    # second when HEAD is behind the pin on a branch whose upstream exists.
+    def with_pin(inspection, path)
+      revision = inspection.project.revision
+      sha = inspection.commit&.sha
+      return inspection if revision.nil? || sha.nil? || sha == revision
+
+      inspection.with(pin: @git.distance(path, revision, tracking: inspection.status.tracking?))
+    end
+
+    # One more spawn, paid only by a project that would otherwise be fast-forwarded.
+    def with_operation(inspection, path)
+      return inspection unless Plan.for(inspection).fast_forward?
+
+      inspection.with(operation: @git.in_progress(path))
+    end
+
+    def collect_warnings(results)
+      results.select { it.state == UNKNOWN }.map { reason(it.error) }.uniq.freeze
+    end
+
+    def reason(error) = error.message.delete_prefix("#{error.path}: ")
+  end
+end

data/lib/slipway/labels.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require_relative 'cli/errors'
+
+module Slipway
+  # Label keys and values as Kubernetes defines them.
+  module Labels
+    # Callers decide whether the label came from the command line or a file.
+    class Invalid < Error; end
+
+    NAME = /\A[A-Za-z0-9]([-A-Za-z0-9_.]*[A-Za-z0-9])?\z/
+    PREFIX = /\A[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*\z/
+    MAX_NAME = 63
+    MAX_PREFIX = 253
+    KEY_RULE = 'letters, digits, dashes, underscores and dots, starting and ending with a letter or digit, ' \
+               'at most 63 characters, with an optional DNS subdomain prefix and a slash'
+    VALUE_RULE = 'empty, or letters, digits, dashes, underscores and dots, starting and ending with a letter ' \
+                 'or digit, at most 63 characters'
+
+    def self.valid_key?(key)
+      return false unless key.is_a?(String)
+
+      case key.split('/', -1)
+      in [name] then valid_name?(name)
+      in [prefix, name] then valid_prefix?(prefix) && valid_name?(name)
+      else false
+      end
+    end
+
+    def self.valid_value?(value) = value.is_a?(String) && (value.empty? || valid_name?(value))
+
+    def self.validate_key!(key)
+      return key if valid_key?(key)
+
+      raise Invalid, "#{key.inspect} is not a valid label key: #{KEY_RULE}"
+    end
+
+    def self.validate_value!(value)
+      return value if valid_value?(value)
+
+      raise Invalid, "#{value.inspect} is not a valid label value: #{VALUE_RULE}"
+    end
+
+    def self.validate!(labels)
+      labels.each do |key, value|
+        validate_key!(key)
+        validate_value!(value)
+      end
+    end
+
+    def self.parse_pairs(words)
+      words.each_with_object({}) do |word, pairs|
+        key, value = split_pair(word, 'KEY=VALUE')
+        duplicate!(key) if pairs.key?(key)
+        pairs[key] = value
+      end
+    end
+
+    # KEY=VALUE sets a label and KEY- removes one; returns [sets, removals].
+    def self.parse_changes(words)
+      sets = {}
+      removals = []
+      words.each do |word|
+        if removal?(word)
+          removals << removal_key(word, removals)
+        else
+          key, value = split_pair(word, 'KEY=VALUE or KEY-')
+          duplicate!(key) if sets.key?(key)
+          sets[key] = value
+        end
+      end
+      reject_overlap(sets, removals)
+    end
+
+    # The form kubectl prints labels in.
+    def self.format(labels)
+      return nil if labels.empty?
+
+      labels.sort.map { |key, value| "#{key}=#{value}" }.join(',')
+    end
+
+    def self.valid_name?(name) = name.length <= MAX_NAME && NAME.match?(name)
+
+    def self.valid_prefix?(prefix) = prefix.length <= MAX_PREFIX && PREFIX.match?(prefix)
+
+    def self.split_pair(word, expected)
+      key, value = word.split('=', 2)
+      raise CLI::UsageError, "invalid label #{word.inspect}: expected #{expected}" if value.nil?
+
+      as_usage_error do
+        validate_key!(key)
+        validate_value!(value)
+      end
+      [key, value]
+    end
+
+    def self.removal?(word) = word.end_with?('-') && !word.include?('=')
+
+    def self.removal_key(word, removals)
+      key = as_usage_error { validate_key!(word.delete_suffix('-')) }
+      duplicate!(key) if removals.include?(key)
+      key
+    end
+
+    def self.duplicate!(key)
+      raise CLI::UsageError, "label #{key.inspect} is given more than once"
+    end
+
+    def self.reject_overlap(sets, removals)
+      overlap = sets.keys & removals
+      return [sets, removals] if overlap.empty?
+
+      raise CLI::UsageError, "label #{overlap.first.inspect} cannot be both set and removed"
+    end
+
+    # Label words come from the command line, so a bad key or value is a usage error there.
+    def self.as_usage_error
+      yield
+    rescue Invalid => e
+      raise CLI::UsageError, e.message
+    end
+
+    private_class_method :valid_name?, :valid_prefix?, :split_pair, :removal?, :removal_key, :duplicate!,
+                         :reject_overlap, :as_usage_error
+  end
+end