dry-cli-ui 0.6.0 → 0.7.0

data/lib/dry/cli/ui/flags.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require "dry/cli"
+
+module Dry
+  class CLI
+    module UI
+      # The reserved flags: options that mean the same thing in every CLI built on this gem.
+      #
+      # | Flag | Long                  | Meaning                                                    |
+      # | ---- | --------------------- | ---------------------------------------------------------- |
+      # | `-n` | `--dry-run`           | change nothing, print what would happen                    |
+      # | `-y` | `--yes`               | skip every interactive prompt                              |
+      # | `-o` | `--output [FILE]`     | write the command's report to FILE, in colour              |
+      # | `-l` | `--log [FILE]`        | log to FILE through SemanticLogger                         |
+      # | `-L` | `--log-level LEVEL`   | debug, info, warn, error or fatal (info by default)        |
+      # |      | `--log-format FORMAT` | standard (the default), json, or another SemanticLogger formatter |
+      #
+      # Extend a command class with it and name the flags it takes. `:log` brings `-L` and
+      # `--log-format` with it. The options reach `call` as `dry_run:`, `yes:`, `output:`, `log:`,
+      # `log_level:` and `log_format:`; hand them to {Console#with_flags}, or to {Console#output},
+      # {Console#logging} and {Console#confirm} one at a time.
+      #
+      # dry-cli gives every string option a required value, so on its own it rejects a bare `-o`.
+      # Loading this module prepends {Hook} onto `Dry::CLI`, which rewrites a bare `-o`,
+      # `--output`, `-l` or `--log` into an empty value (see {.arguments}) for the commands that
+      # extend this module, and nothing else. An empty value means "the default file".
+      #
+      # @example
+      #   class Export < Dry::CLI::Command
+      #     include Dry::CLI::UI
+      #     extend Dry::CLI::UI::Flags
+      #
+      #     flags :dry_run, :yes, :output, :log
+      #   end
+      module Flags
+        # Every option each reserved flag declares, as arguments to dry-cli's `option`.
+        OPTIONS = {
+          dry_run: {
+            dry_run: { type: :flag, default: false, aliases: ["-n"], desc: "Change nothing; print what would happen" }
+          },
+          yes: {
+            yes: { type: :flag, default: false, aliases: ["-y"], desc: "Answer yes to every prompt" }
+          },
+          output: {
+            output: { aliases: ["-o"], desc: "Write the report to FILE: log/ by default, - for STDOUT" }
+          },
+          log: {
+            log: { aliases: ["-l"], desc: "Log to FILE: log/ by default, - for STDOUT" },
+            log_level: { aliases: ["-L"], default: "info", values: %w[debug info warn error fatal],
+                         desc: "Log level" },
+            log_format: { default: "standard", desc: "Log format: standard, json, or another SemanticLogger formatter" }
+          }
+        }.freeze
+
+        # The reserved flags that take an optional file.
+        OPTIONAL_VALUES = %i[output log].freeze
+
+        # The switches {.arguments} rewrites unless told otherwise.
+        SWITCHES = %w[-o --output -l --log].freeze
+
+        # Gives a bare switch an empty value, so that dry-cli, which requires one, accepts it.
+        #
+        # A switch is bare when it is last, or when the next argument starts with `-` and is not
+        # exactly `-`. `-o=x`, `--output=x`, `-ox`, `-o x` and `-o -` are left alone, as is
+        # everything after `--`.
+        #
+        # @example
+        #   Dry::CLI::UI::Flags.arguments(%w[export -o --verbose])  # => ["export", "-o", "", "--verbose"]
+        #
+        # @param argv [Array<String>] the command line
+        # @param switches [Array<String>] the switches that take an optional value
+        # @return [Array<String>] a new array; argv is not changed
+        def self.arguments(argv, switches: SWITCHES)
+          ended = false
+          argv.each_with_index.flat_map do |token, index|
+            ended ||= token == "--"
+            bare = !ended && switches.include?(token) && bare_before?(argv[index + 1])
+            bare ? [token, ""] : [token]
+          end
+        end
+
+        # Whether a switch followed by this argument has no value.
+        #
+        # @param following [String, nil] the next argument, nil at the end of the line
+        # @return [Boolean]
+        def self.bare_before?(following)
+          following.nil? || (following.start_with?("-") && following != "-")
+        end
+        private_class_method :bare_before?
+
+        # The switches of a command's options that take an optional file, as typed on a command
+        # line: `--output` and each of its aliases, and the same for `--log`.
+        #
+        # @param command [Class] a command class extended with this module
+        # @return [Array<String>]
+        def self.switches(command)
+          command.options.select { OPTIONAL_VALUES.include?(it.name.to_sym) }.flat_map do |option|
+            names = [option.name.to_s.tr("_", "-"), *option.aliases.map { it.delete_prefix("-").delete_prefix("-") }]
+            names.map { it.size == 1 ? "-#{it}" : "--#{it}" }
+          end
+        end
+
+        # Declares reserved flags as options of this command.
+        #
+        # @param names [Array<Symbol>] any of `:dry_run`, `:yes`, `:output` and `:log`
+        # @return [Array<Symbol>] the names
+        # @raise [ArgumentError] when a name is not a reserved flag; nothing is declared
+        def flags(*names)
+          unknown = names - OPTIONS.keys
+          raise ArgumentError, "unknown flag #{unknown.map(&:inspect).join(', ')}, expected any of #{OPTIONS.keys}" if unknown.any?
+
+          names.each { |name| OPTIONS.fetch(name).each { |option_name, settings| option(option_name, settings) } }
+          names
+        end
+
+        # Prepended onto `Dry::CLI` when {Flags} loads. It rewrites the arguments of a command that
+        # extends {Flags} with {Flags.arguments}, and records on a command that includes {UI} the
+        # names it was called by, which name its default report and log files.
+        #
+        # @api private
+        module Hook
+          private
+
+          # @param command [Class, Dry::CLI::Command] the command dry-cli resolved
+          # @param arguments [Array<String>] the arguments after the command's names
+          # @param names [Array<String>] the names the command was called by
+          # @return [Array(Dry::CLI::Command, Hash)] the command to call and its arguments
+          def parse(command, arguments, names)
+            klass = command.is_a?(Class) ? command : command.class
+            arguments = Flags.arguments(arguments, switches: Flags.switches(klass)) if klass.is_a?(Flags)
+            result = super
+            instance, = result
+            instance.instance_variable_set(:@ui_command_names, names) if instance.is_a?(UI)
+            result
+          end
+        end
+
+        CLI.prepend(Hook)
+      end
+    end
+  end
+end

data/lib/dry/cli/ui/invocation.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Dry
+  class CLI
+    module UI
+      # How a command was run, as far as naming its report and log files goes: the program, the
+      # command's names, when the process started, and where.
+      #
+      # @!attribute [r] executable
+      #   @return [String] the program's basename, e.g. `law-cli`
+      # @!attribute [r] action
+      #   @return [String, nil] the command's names joined with `-`, e.g. `generate-text`; nil for a
+      #     CLI that is a single command
+      # @!attribute [r] name
+      #   @return [String] what the command's logger is called, usually its class name
+      # @!attribute [r] started_at
+      #   @return [Time] when the process started; stamps the report's file name
+      # @!attribute [r] directory
+      #   @return [String] the directory the command runs in
+      Invocation = ::Data.define(:executable, :action, :name, :started_at, :directory) do
+        # Describes a command: by the names dry-cli resolved it by, when {Flags::Hook} recorded
+        # them, and otherwise by its class name.
+        #
+        # @param command [Object, nil] the command, or nil for none
+        # @param program [String] the program's path
+        # @param started_at [Time]
+        # @param directory [String]
+        # @return [Invocation]
+        def self.for(command = nil, program: $PROGRAM_NAME, started_at: UI.started_at, directory: Dir.pwd)
+          executable = File.basename(program)
+          class_name = command.class.name unless command.nil?
+          new(executable: executable, action: action(command, class_name), name: class_name || executable,
+              started_at: started_at, directory: directory)
+        end
+
+        # The names the command was called by, else the last part of its class name, dasherized.
+        #
+        # @param command [Object, nil]
+        # @param class_name [String, nil]
+        # @return [String, nil]
+        def self.action(command, class_name)
+          names = command.instance_variable_get(:@ui_command_names)
+          return names.join("-") if names
+          return if class_name.nil?
+
+          class_name.split("::").last.gsub(/([a-z\d])([A-Z])/, '\1-\2').downcase
+        end
+        private_class_method :action
+
+        # The nearest directory up from `directory` that holds `.git`, else `directory` itself.
+        #
+        # @param directory [String]
+        # @return [String]
+        def self.root(directory)
+          start = Pathname(directory).expand_path
+          (start.ascend.find { it.join(".git").exist? } || start).to_s
+        end
+
+        # The program and the action, joined with `-`: `law-cli-generate-text`.
+        #
+        # @return [String]
+        def basename
+          [executable, action].reject { it.nil? || it.empty? }.join("-")
+        end
+
+        # Where `-o` writes. Creates the file's directory when it is missing.
+        #
+        # @param value [String, nil] what `-o` was given: nil without `-o`, `-` for STDOUT, an
+        #   empty string for the default name, or a path
+        # @return [String, nil] the path, or nil for the command's own output
+        def report_path(value)
+          stamp = started_at.strftime("%Y-%m-%d.%H%M%S")
+          file(value, "#{basename}.#{stamp}.log") unless value.nil? || value == "-"
+        end
+
+        # Where `-l` logs. Creates the file's directory when it is missing.
+        #
+        # @param value [String, nil] what `-l` was given: nil without `-l`, `-` for STDOUT, an
+        #   empty string for the default name, or a path
+        # @return [String, nil] the path, `-` for STDOUT, or nil for no log
+        def log_path(value)
+          value.nil? || value == "-" ? value : file(value, "#{basename}.log")
+        end
+
+        private
+
+        # @param value [String] a path, or empty for the default
+        # @param default [String] the default file name, under `log/` at the repository root
+        # @return [String]
+        def file(value, default)
+          path = value.empty? ? File.join(Invocation.root(directory), "log", default) : File.expand_path(value, directory)
+          FileUtils.mkdir_p(File.dirname(path))
+          path
+        end
+      end
+    end
+  end
+end

data/lib/dry/cli/ui/logging.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+require "semantic_logger"
+
+module Dry
+  class CLI
+    module UI
+      # SemanticLogger set up from the reserved `-l`, `-L` and `--log-format` flags, for as long as
+      # a block runs. See {Console#logging}.
+      #
+      # At level `debug` it also records, for every exception raised while the block runs, the
+      # local variables of each frame on the stack where it was raised. {Console#log_exception}
+      # logs them with the exception. Recording them costs time, which is why it happens at
+      # `debug` only.
+      class Logging
+        # The levels `-L` takes.
+        LEVELS = %w[debug info warn error fatal].freeze
+
+        # Formats named differently here than in SemanticLogger.
+        FORMATS = { "standard" => :default }.freeze
+
+        # The most characters of a local variable's `inspect` kept.
+        INSPECT_LIMIT = 200
+
+        # The most frames whose local variables are kept for one exception.
+        FRAME_LIMIT = 25
+
+        # Frames in this gem's own files, which are left out of what is recorded.
+        OWN_FILES = "#{File.expand_path(__dir__)}/".freeze
+
+        # Local variables recorded for each exception, keyed by the exception.
+        LOCALS = ::ObjectSpace::WeakMap.new
+
+        class << self
+          # Checks a level name.
+          #
+          # @param name [String, Symbol]
+          # @return [Symbol]
+          # @raise [ArgumentError] when it is not one of {LEVELS}
+          def level(name)
+            return name.to_sym if LEVELS.include?(name.to_s)
+
+            raise ArgumentError, "unknown log level #{name.to_s.inspect}, expected one of #{LEVELS.join(', ')}"
+          end
+
+          # Builds a SemanticLogger formatter from its name: `standard` for SemanticLogger's default,
+          # one line per entry, or the name of any formatter SemanticLogger has, such as `json`,
+          # `color` or `logfmt`.
+          #
+          # @param name [String, Symbol]
+          # @return [#call] the formatter
+          # @raise [ArgumentError] when SemanticLogger has no formatter of that name
+          def formatter(name)
+            SemanticLogger::Formatters.factory(FORMATS.fetch(name.to_s) { name.to_s.to_sym })
+          rescue ArgumentError
+            raise ArgumentError, "unknown log format #{name.to_s.inspect}, expected one of #{formats.join(', ')}", cause: nil
+          end
+
+          # @return [Array<String>] the names {.formatter} takes
+          def formats
+            names = (SemanticLogger::Formatters.constants - [:Base]).map do |constant|
+              constant.to_s.gsub(/([a-z\d])([A-Z])/, '\1_\2').downcase
+            end
+            (FORMATS.keys + names - FORMATS.values.map(&:to_s)).sort
+          end
+
+          # A SemanticLogger logger.
+          #
+          # @param name [String]
+          # @return [SemanticLogger::Logger]
+          def logger(name)
+            SemanticLogger[name]
+          end
+
+          # The local variables recorded for an exception raised while logging at `debug`.
+          #
+          # @param exception [Exception]
+          # @return [Array<Hash{Symbol => Object}>, nil] one entry per frame, innermost first, each
+          #   with its `frame` and `locals`; nil when nothing was recorded
+          def locals(exception)
+            LOCALS[exception]
+          end
+
+          # Records the local variables of the frames on the stack, for an exception being raised.
+          # Keeps what was recorded where the exception was first raised.
+          #
+          # @param exception [Exception]
+          # @return [void]
+          def record(exception)
+            return if LOCALS.key?(exception) || Thread.current[:dry_cli_ui_recording]
+
+            Thread.current[:dry_cli_ui_recording] = true
+            begin
+              LOCALS[exception] = frames(binding.callers)
+            ensure
+              Thread.current[:dry_cli_ui_recording] = nil
+            end
+          end
+
+          private
+
+          # @param bindings [Array<Binding>] the stack, innermost first
+          # @return [Array<Hash{Symbol => Object}>]
+          def frames(bindings)
+            bindings.reject { it.source_location.first.start_with?(OWN_FILES) }.filter_map do |frame|
+              names = frame.local_variables
+              next if names.empty?
+
+              { frame: frame.source_location.join(":"), locals: names.to_h { [it, describe(frame.local_variable_get(it))] } }
+            end.first(FRAME_LIMIT)
+          end
+
+          # @param value [Object]
+          # @return [String] its `inspect`, cut to {INSPECT_LIMIT} characters
+          def describe(value)
+            text = value.inspect
+            text.length > INSPECT_LIMIT ? "#{text[0, INSPECT_LIMIT]}..." : text
+          rescue StandardError => e
+            "#<#{e.class} from inspect>"
+          end
+        end
+
+        # @param target [String, nil] a file, `-` for `io`, or nil for no log
+        # @param io [IO] where `-` logs
+        # @param level [String, Symbol] one of {LEVELS}
+        # @param format [String, Symbol] see {.formatter}
+        # @raise [ArgumentError] for an unknown level or format
+        def initialize(target, io:, level:, format:)
+          @target = target
+          @io = io
+          @level = Logging.level(level)
+          @formatter = Logging.formatter(format)
+        end
+
+        # Adds the appender, sets the level, and runs the block. Afterwards flushes and removes the
+        # appender and puts the level back.
+        #
+        # @yield
+        # @return [Object] whatever the block returns
+        def run(&)
+          return yield if target.nil?
+
+          start
+          yield
+        ensure
+          stop
+        end
+
+        private
+
+        # @return [String, nil]
+        attr_reader :target
+
+        # @return [IO]
+        attr_reader :io
+
+        # @return [Symbol]
+        attr_reader :level
+
+        # @return [#call]
+        attr_reader :formatter
+
+        # @return [void]
+        def start
+          destination = target == "-" ? { io: io } : { file_name: target }
+          @appender = SemanticLogger.add_appender(**destination, formatter: formatter)
+          @previous_level = SemanticLogger.default_level
+          SemanticLogger.default_level = level
+          trace if level == :debug
+        end
+
+        # @return [void]
+        def trace
+          require "binding_of_caller"
+          @trace = TracePoint.new(:raise) { |point| Logging.record(point.raised_exception) }
+          @trace.enable
+        end
+
+        # @return [void]
+        def stop
+          return unless @appender
+
+          @trace&.disable
+          SemanticLogger.flush
+          SemanticLogger.remove_appender(@appender)
+          SemanticLogger.default_level = @previous_level
+          @appender = nil
+        end
+      end
+    end
+  end
+end

data/lib/dry/cli/ui/report.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "delegate"
+
+module Dry
+  class CLI
+    module UI
+      # A file a command writes its report to, through `-o`. It behaves as the file it wraps, and
+      # answers `color?` with true, so a {Terminal} on it writes colour although it is no TTY.
+      class Report < ::SimpleDelegator
+        # @return [Boolean] always true: a report is written in colour
+        def color? = true
+      end
+    end
+  end
+end

data/lib/dry/cli/ui/reporting.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module Dry
+  class CLI
+    module UI
+      # The part of {Console} behind the reserved `-o`, `-l`, `-L` and `--log-format` flags (see
+      # {Flags}): where a command's report goes, and how it logs.
+      module Reporting
+        # Sends what the block writes to `out` to the file `-o` named. Tables, boxes and statuses at
+        # `info` and `success` land there, in colour; spinners, bars, prompts and warnings stay on
+        # `err`. The block is given the IO the report goes to, for writing to it directly.
+        #
+        # The file's last line says when it was closed, and a line on `err` says where it is.
+        #
+        # @example
+        #   ui.output(output) do |io|
+        #     ui.table(rows, header: %w[Rule Count])
+        #     io.puts "#{rows.size} rules"
+        #   end
+        #
+        # @param value [String, nil] what `-o` was given: nil without `-o` and `-` for STDOUT, both
+        #   meaning the command's own `out`; an empty string for
+        #   `log/<executable>-<action>.<YYYY-MM-DD>.<HHMMSS>.log` at the repository root, stamped
+        #   with the time the process started; or a path
+        # @yieldparam io [IO] where the report goes
+        # @return [Object] whatever the block returns
+        # @raise [ArgumentError] without a block
+        def output(value = nil, &)
+          raise ArgumentError, "output needs a block" unless block_given?
+
+          path = invocation.report_path(value)
+          return yield(out.io) if path.nil?
+
+          begin
+            File.open(path, "w") { |file| write_report(Report.new(file), &) }
+          ensure
+            notice = "Report written to #{Pathname(path).relative_path_from(invocation.directory)}"
+            err.puts(Widgets::Status.line(err, Theme.level(:info), notice))
+          end
+        end
+
+        # Logs through SemanticLogger to the file `-l` named while the block runs, then flushes and
+        # removes the appender. At level `debug` it records the local variables of every frame an
+        # exception is raised through, for {#log_exception}.
+        #
+        # @example
+        #   ui.logging(log, level: log_level, format: log_format) do
+        #     ui.logger.info("Importing", count: rules.size)
+        #   end
+        #
+        # @param value [String, nil] what `-l` was given: nil for no log; `-` for the command's own
+        #   `out`; an empty string for `log/<executable>-<action>.log` at the repository root; or a
+        #   path
+        # @param level [String, Symbol] `debug`, `info`, `warn`, `error` or `fatal`
+        # @param format [String, Symbol] `standard`, `json`, or another SemanticLogger formatter
+        # @return [Object] whatever the block returns
+        # @raise [ArgumentError] without a block, or for an unknown level or format
+        def logging(value, level: "info", format: "standard", &)
+          raise ArgumentError, "logging needs a block" unless block_given?
+
+          Logging.new(invocation.log_path(value), io: out.io, level: level, format: format).run(&)
+        end
+
+        # Applies the reserved flags a command was called with: {#logging} around {#output}. Takes
+        # the whole options hash `call` receives and ignores what it does not use.
+        #
+        # @example
+        #   def call(**options)
+        #     ui.with_flags(**options) { |io| ui.table(rows) }
+        #   end
+        #
+        # @param output [String, nil] see {#output}
+        # @param log [String, nil] see {#logging}
+        # @param log_level [String, Symbol]
+        # @param log_format [String, Symbol]
+        # @yieldparam io [IO] where the report goes
+        # @return [Object] whatever the block returns
+        # @raise [ArgumentError] without a block, or for an unknown level or format
+        def with_flags(output: nil, log: nil, log_level: "info", log_format: "standard", **, &)
+          raise ArgumentError, "with_flags needs a block" unless block_given?
+
+          logging(log, level: log_level, format: log_format) { self.output(output, &) }
+        end
+
+        # The command's SemanticLogger logger, named after the command's class. It writes nothing
+        # until {#logging} adds an appender.
+        #
+        # @return [SemanticLogger::Logger]
+        def logger
+          @logger ||= Logging.logger(invocation.name)
+        end
+
+        # Logs an exception with its backtrace and, when it was raised while logging at `debug`,
+        # the local variables of each frame it was raised through, as the payload's `locals`.
+        #
+        # @example
+        #   rescue => e
+        #     ui.log_exception(e, "Import failed")
+        #
+        # @param exception [Exception]
+        # @param message [String, nil] the exception's message by default
+        # @param level [String, Symbol]
+        # @return [nil]
+        # @raise [ArgumentError] for an unknown level
+        def log_exception(exception, message = nil, level: :error)
+          locals = Logging.locals(exception)
+          logger.public_send(Logging.level(level), message || exception.message, locals && { locals: locals }, exception)
+          nil
+        end
+
+        private
+
+        # @return [Invocation] how the command was run; describes no command when none was given
+        def invocation
+          @invocation ||= Invocation.for
+        end
+
+        # Points `out` at a report while the block runs, then ends the report with the time.
+        #
+        # @param report [Report]
+        # @yieldparam report [Report]
+        # @return [Object] whatever the block returns
+        def write_report(report)
+          previous = @out
+          @out = previous.to(report)
+          yield report
+        ensure
+          @out = previous
+          report.puts("Closed at #{Time.now.strftime('%Y-%m-%d %H:%M:%S %z')}")
+        end
+      end
+    end
+  end
+end

data/lib/dry/cli/ui/terminal.rb

@@ -89,13 +89,30 @@ module Dry
           tty? && env["TERM"] != "dumb"
         end
 
-        # Whether to emit ANSI colour codes.
+        # Whether to emit ANSI colour codes: on an animated terminal, or on a stream that asks for
+        # colour by answering `color?` with true, such as a {Report}; never under `NO_COLOR`.
         #
         # @return [Boolean]
         def color?
           return color unless color.nil?
 
-          animated? && env["NO_COLOR"].to_s.empty?
+          (animated? || (io.respond_to?(:color?) && io.color?)) && env["NO_COLOR"].to_s.empty?
+        end
+
+        # A terminal like this one, writing to another stream, and never animated: what a
+        # command's report goes to.
+        #
+        # @param io [IO]
+        # @return [Terminal]
+        def to(io)
+          Terminal.new(io, env: env, color: color, animate: false, width: @width)
+        end
+
+        # Leaves out the environment, which can hold secrets, from what a debug log records.
+        #
+        # @return [String]
+        def inspect
+          "#<#{self.class} io=#{io.inspect}>"
         end
 
         # @return [Integer] columns available

data/lib/dry/cli/ui/version.rb

@@ -11,7 +11,7 @@ module Dry
     # Presentation helpers for Dry::CLI commands.
     module UI
       # The gem version.
-      VERSION = "0.6.0"
+      VERSION = "0.7.0"
     end
   end
 end

data/lib/dry/cli/ui/widgets/legend.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Dry
+  class CLI
+    module UI
+      module Widgets
+        # The line that says what each colour of a progress bar means:
+        #
+        #   Color Mapping: [ red: errors and invalid files | yellow: relevant but auxiliary | green: forms ]
+        #
+        # With colour, each label is drawn on its colour's background instead
+        # of naming it. The colours are the configured ones:
+        # {Configuration#bar_failed_color}, {Configuration#bar_aux_color} and
+        # {Configuration#bar_color}.
+        module Legend
+          # Each label's keyword, and the setting its colour comes from, in
+          # the order a bar draws them.
+          SETTINGS = { failed: :bar_failed_color, aux: :bar_aux_color, ok: :bar_color }.freeze
+
+          # @param terminal [Terminal]
+          # @param config [Configuration]
+          # @param labels [Hash{Symbol => #to_s, nil}] keyed as {SETTINGS};
+          #   a nil label is left out
+          # @return [String] the line, without a newline
+          # @raise [ArgumentError] when every label is nil
+          def self.line(terminal, config, labels)
+            entries = SETTINGS.filter_map { |key, setting| [labels[key].to_s, config.public_send(setting)] unless labels[key].nil? }
+            raise ArgumentError, "legend needs at least one of #{SETTINGS.keys.map { "#{it}:" }.join(', ')}" if entries.empty?
+
+            shown = entries.map { |label, style| terminal.color? ? swatch(terminal.pastel, label, style) : "#{style || 'plain'}: #{label}" }
+            "Color Mapping: [ #{shown.join(' | ')} ]"
+          end
+
+          # @param pastel [Pastel::Delegator]
+          # @param label [String]
+          # @param style [Symbol, nil]
+          # @return [String] the label, padded, in black on the style's
+          #   background; on the style itself when it has no background form
+          def self.swatch(pastel, label, style)
+            background = :"on_#{style}"
+            styles = Configuration::STYLES.include?(background) ? [:black, background] : [style].compact
+            pastel.decorate(" #{label} ", *styles)
+          end
+        end
+      end
+    end
+  end
+end