slipway 0.1.0

data/lib/slipway/cli/globals.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative 'registry'
+require_relative 'style'
+
+module Slipway
+  module CLI
+    # The Runner reads help, version and color from the parsed values by these keys, so a
+    # registry passes ALL, or .all, as its globals.
+    module Globals
+      # No default: a nil value tells a handler the flag was not typed, so SLIPWAY_COLOR and the
+      # config file can still decide. The Runner falls back to auto on its own.
+      COLOR = Option.new(long: 'color', argument: 'WHEN', optional: true, implicit: 'always', enum: Style::MODES,
+                         description: 'When to use color in the output; a bare --color means always.')
+      GROUP = Option.new(long: 'group', short: 'n', argument: 'NAME', description: 'The group scope for this request.')
+      CONFIG = Option.new(long: 'config', argument: 'PATH', description: 'Path to the configuration file.')
+      HELP = Option.new(long: 'help', short: 'h', description: 'Print help and exit.')
+      VERSION = Option.new(long: 'version', short: 'V', description: 'Print the version and exit.')
+
+      ALL = [COLOR, GROUP, CONFIG, HELP, VERSION].freeze
+
+      def self.all(group_completer:)
+        ALL.map { it.equal?(GROUP) ? it.with(completer: group_completer) : it }.freeze
+      end
+    end
+  end
+end

data/lib/slipway/cli/help_renderer.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module Slipway
+  module CLI
+    # Alignment is computed on plain text and color applied afterwards, so ANSI escapes
+    # never skew columns.
+    class HelpRenderer
+      COMMAND_COLUMN = 16
+      FLAG_COLUMN = 30
+      GAP = '   '
+      INDENT = '  '
+      FLAGS = '[flags]'
+      # Width of "-x, ", so long-only options line up with the long form of short ones.
+      SHORT_PREFIX = ' ' * 4
+
+      def initialize(registry, style)
+        @registry = registry
+        @style = style
+      end
+
+      def root
+        join([
+               @registry.root.description,
+               *command_sections(@registry.root),
+               option_section('Options', @registry.globals),
+               usage("#{@registry.program} #{FLAGS} COMMAND [ARGS...]"),
+               command_trailer([])
+             ])
+      end
+
+      def command(command, path)
+        join([
+               command.description,
+               *command.glossaries.map { glossary(it) },
+               exit_statuses(command.exit_statuses),
+               examples(command.examples),
+               *command_sections(command),
+               option_section('Options', command.options),
+               usage(command_usage(command, path)),
+               trailer(command, path)
+             ])
+      end
+
+      private
+
+      def join(sections) = "#{sections.compact.join("\n\n")}\n"
+
+      def header(text) = @style.paint(:help_header, "#{text}:")
+
+      def command_sections(command)
+        command.sections.map do |section, commands|
+          width = [COMMAND_COLUMN, *commands.map { it.name.size + GAP.size }].max
+          rows = commands.map { "#{INDENT}#{it.name.ljust(width)}#{it.summary}" }
+          "#{header(section)}\n#{rows.join("\n")}"
+        end
+      end
+
+      def exit_statuses(statuses)
+        return nil if statuses.empty?
+
+        "#{header('Exit Status')}\n#{terms(statuses)}"
+      end
+
+      def glossary(glossary)
+        intro = glossary.intro && "#{INDENT}#{glossary.intro}\n\n"
+        "#{header(glossary.title)}\n#{intro}#{terms(glossary.entries)}"
+      end
+
+      def terms(entries)
+        width = entries.keys.map { it.size + GAP.size }.max
+        entries.map { |term, meaning| "#{INDENT}#{term.ljust(width)}#{meaning}" }.join("\n")
+      end
+
+      def examples(examples)
+        return nil if examples.empty?
+
+        blocks = examples.map do |example|
+          "#{INDENT}#{@style.paint(:help_comment, "# #{example.comment}")}\n#{INDENT}#{shell_line(example.command)}"
+        end
+        "#{header('Examples')}\n#{blocks.join("\n\n")}"
+      end
+
+      def shell_line(command)
+        program, *words = "#{@registry.program} #{command}".split
+        painted = words.map { it.start_with?('-') ? @style.paint(:help_flag, it) : it }
+        [@style.paint(:help_command, program), *painted].join(' ')
+      end
+
+      def option_section(title, options)
+        return nil if options.empty?
+
+        labels = options.map { padded_label(it) }
+        width = [labels.map(&:size).max, FLAG_COLUMN].min
+        rows = options.zip(labels).map { |option, label| option_row(option, label, width) }
+        "#{header(title)}\n#{rows.join("\n")}"
+      end
+
+      def padded_label(option) = option.short ? option.label : "#{SHORT_PREFIX}#{option.label}"
+
+      def option_row(option, label, width)
+        painted = paint_label(label)
+        text = option.description_parts.join(' ')
+        return "#{INDENT}#{painted}\n#{INDENT}#{' ' * width}#{GAP}#{text}" if label.size > width
+
+        "#{INDENT}#{painted}#{' ' * (width - label.size)}#{GAP}#{text}"
+      end
+
+      # The padding of a long-only label stays outside the escape sequence.
+      def paint_label(label)
+        stripped = label.lstrip
+        "#{label[0, label.size - stripped.size]}#{@style.paint(:help_flag, stripped)}"
+      end
+
+      def usage(line) = "#{header('Usage')}\n#{INDENT}#{line}"
+
+      # Required options come before the positionals, as kubectl writes `apply -f FILENAME`;
+      # `[flags]` is always there because the global options apply to every command.
+      def command_usage(command, path)
+        required = command.options.select(&:required).map { "#{it.switches.first} #{it.argument}" }
+        [@registry.program, *path, *required, command.usage_args, FLAGS].reject(&:empty?).join(' ')
+      end
+
+      def trailer(command, path)
+        lines = []
+        lines << command_trailer(path) if command.group?
+        lines << %(Use "#{@registry.program} --help" for a list of global options (applies to all commands).)
+        lines.join("\n")
+      end
+
+      def command_trailer(path)
+        %(Use "#{[@registry.program, *path].join(' ')} <command> --help" for more information about a given command.)
+      end
+    end
+  end
+end

data/lib/slipway/cli/manpage.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+module Slipway
+  module CLI
+    module Roff
+      BULLET = /\A\s*\*\s+/
+
+      module_function
+
+      # Backslashes become \e and hyphens \- so options stay searchable; a line that would
+      # start with a control character is neutralized with \&.
+      def text(value)
+        value.to_s.gsub('\\', '\e').gsub('-', '\-').sub(/\A(?=[.'])/) { '\&' }
+      end
+
+      def argument(value)
+        escaped = text(value).gsub('"', '\(dq')
+        escaped.include?(' ') ? %("#{escaped}") : escaped
+      end
+
+      def heading(title) = ".SH #{argument(title)}"
+
+      def subheading(title) = ".SS #{argument(title)}"
+
+      def bold(value) = "\\fB#{text(value)}\\fR"
+
+      def italic(value) = "\\fI#{text(value)}\\fR"
+
+      # The first paragraph follows the heading directly, since .PP right after .SH is a lint
+      # error. Leading spaces, which the terminal help keeps, are dropped because roff would
+      # break the line on them.
+      def paragraphs(value)
+        value.to_s.split(/\n{2,}/).flat_map.with_index do |paragraph, index|
+          lines = paragraph.lines(chomp: true).flat_map { line(it) }
+          index.zero? || lines.first.start_with?('.IP') ? lines : ['.PP', *lines]
+        end
+      end
+
+      def line(value)
+        return [text(value.lstrip)] unless BULLET.match?(value)
+
+        ['.IP \(bu 2', text(value.sub(BULLET, ''))]
+      end
+
+      # `indent` is in ens.
+      def tagged(label, description, indent: nil) = [indent ? ".TP #{indent}" : '.TP', label, *paragraphs(description)]
+
+      def reference(name) = ".BR #{text(name)} (1)"
+    end
+
+    # The date is passed in so the output is reproducible.
+    class Manpage
+      SECTION = '1'
+      # `source` fills the fourth .TH field. The root page's ENVIRONMENT, FILES, CONFIGURATION and
+      # EXIT STATUS sections come from the caller, each a Hash of a variable, a path, a config
+      # file key or a status to its meaning, because what they describe belongs to the program; an
+      # empty Hash leaves its section out.
+      def initialize(registry, date:, source: nil, environment: {}, files: {}, configuration: {}, exit_statuses: {})
+        @registry = registry
+        @date = date
+        @source = source || "#{registry.program} #{registry.version}"
+        @environment = environment
+        @files = files
+        @configuration = configuration
+        @exit_statuses = exit_statuses
+      end
+
+      def pages
+        paths.to_h { |path| [file_name(path), page(path)] }
+      end
+
+      def page(path)
+        command, = @registry.resolve(path)
+        lines = path.empty? ? root_page(command) : command_page(command, path)
+        "#{lines.join("\n")}\n"
+      end
+
+      private
+
+      def paths(command = @registry.root, path = [])
+        [path, *command.visible_subcommands.flat_map { paths(it, [*path, it.name]) }]
+      end
+
+      def file_name(path) = "#{page_name(path)}.#{SECTION}"
+
+      def page_name(path) = [@registry.program, *path].join('-')
+
+      # The .TH fields are quoted verbatim: an escaped date is one mandoc cannot parse.
+      def header(path)
+        manual = "#{@registry.program.capitalize} Manual"
+        fields = [page_name(path).upcase, SECTION, @date, @source, manual].map { %("#{it.gsub('"', '\\(dq')}") }
+        [%(.\\" Generated by #{@registry.program} #{@registry.version}. Do not edit.), ".TH #{fields.join(' ')}"]
+      end
+
+      def root_page(root)
+        [
+          *header([]),
+          *name_section([], @registry.description.delete_suffix('.')),
+          *root_synopsis,
+          '.SH DESCRIPTION', *Roff.paragraphs(root.description),
+          *commands_section(root),
+          *options_section(@registry.globals),
+          *tagged_section('ENVIRONMENT', @environment),
+          *tagged_section('FILES', @files, label: Roff.method(:italic)),
+          *tagged_section('CONFIGURATION', @configuration),
+          *tagged_section('EXIT STATUS', @exit_statuses), *own_exit_statuses,
+          *see_also(paths.drop(1))
+        ]
+      end
+
+      def command_page(command, path)
+        [
+          *header(path),
+          *name_section(path, command.summary),
+          *synopsis(command, path),
+          '.SH DESCRIPTION', *Roff.paragraphs(command.description),
+          *commands_section(command),
+          *options_section(command.options),
+          *command.glossaries.flat_map { glossary_section(it) },
+          *tagged_section('EXIT STATUS', command.exit_statuses),
+          *examples_section(command.examples),
+          *see_also(related(command, path))
+        ]
+      end
+
+      def root_synopsis
+        ['.SH SYNOPSIS', ".SY #{Roff.argument(@registry.program)}", '.RI [ flags ]', '.I COMMAND', '.RI [ ARGS... ]\\&',
+         '.YS']
+      end
+
+      def name_section(path, summary)
+        ['.SH NAME', "#{Roff.text(page_name(path))} \\- #{Roff.text(summary)}"]
+      end
+
+      def synopsis(command, path)
+        ['.SH SYNOPSIS', ".SY #{Roff.argument([@registry.program, *path].join(' '))}", *synopsis_args(command), '.YS']
+      end
+
+      def synopsis_args(command)
+        required = command.options.select(&:required)
+        options = required.flat_map { [".B #{Roff.text(it.switches.first)}", ".I #{it.argument}"] }
+        [*options, *positional_args(command), '.RI [ flags ]']
+      end
+
+      def positional_args(command)
+        return ['.I COMMAND'] if command.group?
+        return [".I #{Roff.argument(command.usage)}\\&"] if command.usage
+
+        command.positionals.map { positional_arg(it) }
+      end
+
+      # Both forms end with \& so a trailing period is not read as the end of a sentence.
+      def positional_arg(positional)
+        token = Roff.text(positional.variadic ? "#{positional.name}..." : positional.name)
+        positional.required ? ".I #{token}\\&" : ".RI [ #{token} ]\\&"
+      end
+
+      def commands_section(command)
+        sections = command.sections
+        return [] if sections.empty?
+
+        width = command.visible_subcommands.map { it.name.size }.max + 2
+        entries = sections.flat_map do |section, commands|
+          heading = sections.size > 1 ? [Roff.subheading(section)] : []
+          heading + commands.flat_map { Roff.tagged(Roff.bold(it.name), it.summary, indent: width) }
+        end
+        ['.SH COMMANDS', *entries]
+      end
+
+      def options_section(options)
+        return [] if options.empty?
+
+        ['.SH OPTIONS', *options.flat_map { Roff.tagged(option_label(it), it.description_parts.join(' ')) }]
+      end
+
+      def option_label(option)
+        switches = option.switches.map { Roff.bold(it) }.join(', ')
+        return switches if option.flag?
+
+        argument = Roff.italic(option.argument)
+        option.optional ? "#{switches}[=#{argument}]" : "#{switches} #{argument}"
+      end
+
+      def examples_section(examples)
+        return [] if examples.empty?
+
+        blocks = examples.map do |example|
+          ['.EX', Roff.text("# #{example.comment}"), Roff.text("#{@registry.program} #{example.command}"), '.EE']
+        end
+        ['.SH EXAMPLES', *blocks.flat_map.with_index { |block, index| index.zero? ? block : ['.PP', *block] }]
+      end
+
+      def tagged_section(title, entries, label: Roff.method(:bold))
+        return [] if entries.empty?
+
+        [Roff.heading(title), *entries.flat_map { |key, meaning| Roff.tagged(label.call(key), meaning) }]
+      end
+
+      def glossary_section(glossary)
+        intro = glossary.intro ? Roff.paragraphs(glossary.intro) : []
+        [Roff.heading(glossary.title.upcase), *intro,
+         *glossary.entries.flat_map { |term, meaning| Roff.tagged(Roff.bold(term), meaning) }]
+      end
+
+      # A script author reads the root page for the exit statuses, so it names the pages that add
+      # to them.
+      def own_exit_statuses
+        pages = paths.drop(1).select { @registry.resolve(it).first.exit_statuses.any? }
+        return [] if pages.empty? || @exit_statuses.empty?
+
+        ['.PP', 'The pages of these commands list their own statuses:',
+         pages.map { Roff.reference(page_name(it)) }.join(",\n")]
+      end
+
+      # A command page points back at the root page and, when nested, at its group page; a group
+      # page also names the pages of its commands.
+      def related(command, path)
+        [[], *(path.size > 1 ? [path[0...-1]] : []), *command.visible_subcommands.map { [*path, it.name] }]
+      end
+
+      def see_also(paths)
+        [Roff.heading('SEE ALSO'), paths.map { Roff.reference(page_name(it)) }.join(",\n")]
+      end
+    end
+  end
+end

data/lib/slipway/cli/parser.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require 'optparse'
+
+module Slipway
+  module CLI
+    class Parser
+      def initialize(options, values)
+        @options = options
+        @values = values
+      end
+
+      # Stops at the first non-option word: `slipway [GLOBALS] VERB ...`.
+      def order!(argv) = parser.order!(argv)
+
+      # Interleaves options and positionals: `slipway get projects -o json alpha`.
+      def permute!(argv) = parser.permute!(argv)
+
+      def defaults
+        @options.each { |opt| @values[opt.key] = opt.default unless @values.key?(opt.key) }
+        @values
+      end
+
+      private
+
+      def parser
+        @parser ||= OptionParser.new do |o|
+          o.require_exact = true
+          drop_officious_completion(o)
+          @options.each do |opt|
+            o.on(*opt.switch_spec) { |raw| @values[opt.key] = opt.accept(@values[opt.key], raw) }
+          end
+        end
+      end
+
+      # OptionParser registers `--*-completion-bash=WORD` and `--*-completion-zsh` on every
+      # parser; both print to $stdout and call `exit` mid-parse, which bypasses the Context
+      # and the exit-code contract. `--help` and `--version` are shadowed by the registry's
+      # own switches; these two have no registry counterpart, so they go.
+      def drop_officious_completion(parser)
+        parser.base.long.delete_if { |name, _| name.start_with?('*-') }
+      end
+    end
+  end
+end

data/lib/slipway/cli/registry.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+module Slipway
+  module CLI
+    SECTION_ORDER = ['Basic Commands', 'Repository Commands', 'Settings Commands', 'Other Commands'].freeze
+
+    # `long` has no dashes, and a nil `argument` makes a boolean flag. An `optional` option
+    # takes its value only attached (--long=VALUE) and stores `implicit` when it is omitted.
+    # `completer` is called with the positional words typed so far and the word being completed;
+    # see Completer for what it returns.
+    Option = Data.define(:long, :short, :argument, :enum, :default, :description,
+                         :repeatable, :required, :optional, :implicit, :completer) do
+      def initialize(long:, description:, short: nil, argument: nil, enum: nil, default: nil,
+                     repeatable: false, required: false, optional: false, implicit: nil, completer: nil)
+        super
+      end
+
+      def key = long.tr('-', '_').to_sym
+
+      def flag? = argument.nil?
+
+      def switches = [short && "-#{short}", "--#{long}"].compact
+
+      def switch_spec
+        long_spec = if flag? then "--#{long}"
+                    elsif optional then "--#{long}[=#{argument}]"
+                    else "--#{long} #{argument}"
+                    end
+        [short && "-#{short}", long_spec].compact
+      end
+
+      def label
+        text = switches.join(', ')
+        return text if flag?
+
+        optional ? "#{text}[=#{argument}]" : "#{text} #{argument}"
+      end
+
+      def description_parts
+        parts = [description]
+        parts << "One of: #{enum.join(', ')}." if enum
+        parts << "(default #{default.inspect})" unless default.nil? || default == false
+        parts << '(required)' if required
+        parts
+      end
+
+      def accept(current, raw)
+        return true if flag?
+        return implicit if optional && raw.nil?
+        return Array(current) << raw if repeatable
+
+        raw
+      end
+
+      def candidates(given = [], current = '') = enum || completer&.call(given, current) || []
+    end
+
+    Positional = Data.define(:name, :required, :variadic, :enum, :completer) do
+      def initialize(name:, required: true, variadic: false, enum: nil, completer: nil)
+        super
+      end
+
+      def usage
+        token = variadic ? "#{name}..." : name
+        required ? token : "[#{token}]"
+      end
+
+      def candidates(given = [], current = '') = enum || completer&.call(given, current) || []
+    end
+
+    # `command` omits the program name; help and man pages prepend it.
+    Example = Data.define(:comment, :command)
+
+    # A titled list of terms and what each means, such as the columns or the result words a command
+    # prints. `intro` is a paragraph printed above the terms.
+    Glossary = Data.define(:title, :intro, :entries) do
+      def initialize(title:, entries:, intro: nil) = super
+    end
+
+    # `handler` responds to call(context, args, opts). A `raw` command receives argv untouched,
+    # with no option parsing, which is what the completion endpoint needs. `usage` replaces
+    # the positional list in the Usage line when the accepted forms cannot be read off them.
+    # `exit_statuses` maps each status to its meaning, for a command whose statuses differ from
+    # the ones every command shares. `glossaries` are the Glossary sections help prints under the
+    # description and the man page renders after the options.
+    Command = Data.define(:name, :aliases, :summary, :description, :section, :examples, :positionals, :options,
+                          :subcommands, :hidden, :raw, :handler, :usage, :exit_statuses, :glossaries) do
+      def initialize(name:, summary:, description: nil, aliases: [], section: 'Available Commands', examples: [],
+                     positionals: [], options: [], subcommands: [], hidden: false, raw: false, handler: nil,
+                     usage: nil, exit_statuses: {}, glossaries: [])
+        super(name:, summary:, description: description || summary, aliases:, section:, examples:,
+              positionals:, options:, subcommands:, hidden:, raw:, handler:, usage:, exit_statuses:, glossaries:)
+      end
+
+      def group? = !subcommands.empty?
+
+      def names = [name, *aliases]
+
+      def find(word) = subcommands.find { it.names.include?(word) }
+
+      def visible_subcommands = subcommands.reject(&:hidden)
+
+      def sections
+        visible_subcommands.group_by(&:section).sort_by.with_index do |(name, _), seen|
+          [SECTION_ORDER.index(name) || SECTION_ORDER.size, seen]
+        end
+      end
+
+      def positional_at(index) = positionals[index] || (positionals.last if positionals.last&.variadic)
+
+      def min_args = positionals.count(&:required)
+
+      def max_args = positionals.last&.variadic ? nil : positionals.size
+
+      def usage_args
+        return 'COMMAND' if group?
+
+        usage || positionals.map(&:usage).join(' ')
+      end
+    end
+
+    # The single source of truth for help, man pages, completion and dispatch.
+    class Registry
+      attr_reader :program, :version, :description, :globals, :root
+
+      # `long_description` replaces `description` on the root help and man page. A Hash
+      # `builtins` is passed on as options to the man builtin.
+      def initialize(program:, version:, description:, globals:, commands:, long_description: nil, builtins: true)
+        @program = program
+        @version = version
+        @description = description
+        @globals = globals
+        extra = builtins ? Builtins.all(program:, version:, resolve: -> { self }, **man_options(builtins)) : []
+        @root = Command.new(name: program, summary: description, description: long_description,
+                            subcommands: commands + extra)
+      end
+
+      def resolve(words)
+        words.reduce([root, []]) do |(command, path), word|
+          nxt = command.find(word)
+          raise UsageError.new(unknown_command(word, path), hint: run_hint(path)) unless nxt
+
+          [nxt, [*path, word]]
+        end
+      end
+
+      def unknown_command(word, path)
+        message = "unknown command #{word.inspect} for #{[program, *path].join(' ').inspect}"
+        with_guesses(message, word, resolve(path).first.visible_subcommands.flat_map(&:names))
+      end
+
+      # OptionParser attaches "Did you mean?" only on its abbreviation-completing path, which
+      # require_exact disables, so suggestions for long switches come from the registry.
+      def unknown_option(word, options)
+        name = word.sub(/=.*/, '')
+        message = "unknown flag: #{name}"
+        return message unless name.start_with?('--')
+
+        with_guesses(message, name, options.map { "--#{it.long}" })
+      end
+
+      # kubectl words the hint for an unknown command with Run and every other one with See.
+      def help_hint(path) = "See '#{[program, *path, '--help'].join(' ')}' for usage."
+
+      def run_hint(path) = "Run '#{[program, *path, '--help'].join(' ')}' for usage."
+
+      private
+
+      def man_options(builtins) = builtins == true ? {} : builtins
+
+      def with_guesses(message, word, dictionary)
+        guesses = Suggest.similar(word, dictionary)
+        return message if guesses.empty?
+
+        "#{message}\n\nDid you mean this?\n#{guesses.map { "\t#{it}" }.join("\n")}\n\n"
+      end
+    end
+
+    # Cobra's rule for "Did you mean this?".
+    module Suggest
+      DISTANCE = 2
+
+      def self.similar(word, dictionary)
+        dictionary.select do |candidate|
+          DidYouMean::Levenshtein.distance(word, candidate) <= DISTANCE ||
+            candidate.start_with?(word) || word.start_with?(candidate)
+        end
+      end
+    end
+  end
+end