slipway 0.1.0

data/lib/slipway/rollback.rb

@@ -0,0 +1,236 @@
+# frozen_string_literal: true
+
+require_relative 'command_line'
+require_relative 'drift'
+require_relative 'git'
+require_relative 'outcome'
+require_relative 'paths'
+require_relative 'rollout_history'
+
+module Slipway
+  # Moves a project's branch to a revision of its rollout history and holds the project there
+  # with spec.revision, as kubectl rollout undo rewrites a Deployment's template to an earlier
+  # revision. The manifest is written only once git has moved the branch.
+  class Rollback
+    # Where the branch is and where the chosen revision is, as the checks saw them. `distance`
+    # counts the commits the move drops (ahead) or gains (behind).
+    Step = Data.define(:project, :status, :head, :revision, :distance) do
+      def back? = distance.ahead.positive?
+
+      def forward? = !back? && distance.behind.positive?
+
+      def count = back? ? distance.ahead : distance.behind
+    end
+
+    # A check that failed, turned into the project's skipped line.
+    class Refused < StandardError
+      attr_reader :reason, :values
+
+      def initialize(reason, values)
+        @reason = reason
+        @values = values
+        super(reason)
+      end
+    end
+
+    ROLLED_BACK = 'rolled back'
+    ACTION = Git::Repository::ROLLBACK_ACTION
+    ABBREV = Git::Porcelain::ABBREVIATION
+    HELD = 'held there by spec.revision'
+    NOT_PINNED = 'NotPinned'
+    # Each leaves the branch and the manifest as they were. A conflict and an operation in progress
+    # stop sync too, and read as diff and sync word them.
+    REFUSALS = {
+      'Conflicted' => Drift::BLOCKERS.fetch('Conflicted'),
+      'Detached' => 'HEAD is detached at %<head>s; undo moves only a checked-out branch',
+      'Unborn' => 'no commits yet; nothing to roll back',
+      'NoUpstream' => '%<branch>s tracks no upstream; undo drops only commits an upstream holds',
+      'Gone' => 'upstream %<upstream>s no longer exists; undo drops only commits an upstream holds',
+      'InProgress' => Drift::BLOCKERS.fetch('InProgress'),
+      'NoHistory' => 'no rollout history found for %<branch>s',
+      'NoPrevious' => 'no last revision to roll back to',
+      'UnknownRevision' => 'unable to find specified revision %<number>d in history',
+      'RevisionNotFound' => 'commit %<commit>s of revision %<number>d is not in this repository',
+      'Diverged' => 'revision %<number>d is not on the history of %<branch>s; undo moves a branch only along it',
+      'LocalCommits' => '%<branch>s has commits that are not on %<upstream>s; undo would drop them',
+      'Dirty' => '%<changes>s; undo moves a branch back only without staged changes, and forward only without ' \
+                 'staged or unstaged changes',
+      'OffUpstream' => 'revision %<number>d is not on %<upstream>s; undo moves a branch forward only along its upstream'
+    }.freeze
+    # Git's own refusals, worded for a move either way.
+    RELAYED = {
+      'WouldLoseChanges' => 'the move would overwrite local changes; commit or move them and run undo again',
+      'WouldOverwrite' => 'the move would overwrite untracked or ignored files; move them and run undo again'
+    }.freeze
+    KEEPS_LOCKS = 'undo never removes a lock'
+    # Plain status hides an ignored file, and the move refuses one in its way.
+    COMMANDS = { 'Conflicted' => %w[status], 'Detached' => %w[status], 'Gone' => %w[branch -vv],
+                 'InProgress' => %w[status], 'LocalCommits' => %w[log --oneline @{upstream}..HEAD],
+                 'Dirty' => %w[status], 'WouldLoseChanges' => %w[status],
+                 'WouldOverwrite' => %w[status --ignored] }.freeze
+
+    # `group` is the one a command without -n selects, so the unpin command can leave it out; nil
+    # when -n was typed, so the unpin command names the group.
+    def initialize(runtime, dry_run:, group:)
+      @runtime = runtime
+      @dry_run = dry_run
+      @group = group
+    end
+
+    # `number` is a revision the history lists; nil or 0 is the one before the current one.
+    def undo(project, number: nil)
+      inspection = @runtime.inspector.examine(project)
+      return Outcome.unreadable(project, inspection) if inspection.error
+
+      ready(inspection)
+      step = plan(inspection, number)
+      @dry_run ? settled(step) : act(step)
+    rescue Refused => e
+      skipped(project, e.reason, format(REFUSALS.fetch(e.reason), **e.values))
+    end
+
+    private
+
+    # The checks sync makes before it moves a branch, less the one for local changes, which
+    # depends on the direction of the move.
+    def ready(inspection)
+      status = inspection.status
+      refuse('Conflicted', paths: unmerged(status.conflicted)) if status.conflicted.positive?
+      refuse('Detached', head: status.head) if status.detached?
+      refuse('Unborn') if status.unborn?
+      refuse('NoUpstream', branch: status.branch) if status.upstream.nil?
+      refuse('Gone', upstream: status.upstream) if status.upstream_gone?
+      operation = @runtime.git.in_progress(path(inspection.project))
+      refuse('InProgress', operation:) if operation
+    end
+
+    def plan(inspection, number)
+      project = inspection.project
+      status = inspection.status
+      head = inspection.commit.sha
+      history = RolloutHistory.new(@runtime.git.reflog(path(project), status.branch))
+      revision = target(history, head, number, status.branch)
+      distance = @runtime.git.distance(path(project), revision.sha, tracking: true)
+      refuse('RevisionNotFound', commit: short(revision.sha), number: revision.number) if distance.nil?
+      Step.new(project:, status:, head:, revision:, distance:).tap { check(it) }
+    end
+
+    def target(history, head, number, branch)
+      revision = number.to_i.zero? ? history.previous(head) : history.revision(number)
+      return revision if revision
+
+      refuse('NoHistory', branch:) if history.empty?
+      number.to_i.zero? ? refuse('NoPrevious') : refuse('UnknownRevision', number:)
+    end
+
+    # A move back must not drop a commit only this repository holds, nor a staged change, since
+    # reset --keep resets every index entry; git itself refuses one that would lose an unstaged
+    # change. A move forward is a fast-forward and needs what sync's fast-forward needs.
+    def check(step)
+      status = step.status
+      values = { number: step.revision.number, branch: status.branch, upstream: status.upstream }
+      back_ready(step, values) if step.back?
+      forward_ready(step, values) if step.forward?
+    end
+
+    def back_ready(step, values)
+      status = step.status
+      refuse('Diverged', **values) if step.distance.behind.positive?
+      refuse('LocalCommits', **values) if status.ahead.to_i.positive?
+      refuse('Dirty', changes: "#{status.staged} staged") if status.staged.positive?
+    end
+
+    def forward_ready(step, values)
+      status = step.status
+      changes = { 'staged' => status.staged, 'unstaged' => status.unstaged }
+                .filter_map { |kind, number| "#{number} #{kind}" if number.positive? }
+      refuse('Dirty', changes: changes.join(', ')) unless changes.empty?
+      refuse('OffUpstream', **values) if step.distance.off_upstream.to_i.positive?
+    end
+
+    def act(step)
+      held(step, move(step))
+    rescue Git::Blocked => e
+      relayed(step.project, e)
+    rescue Git::Error => e
+      Outcome.failure(step.project, e)
+    end
+
+    def move(step)
+      path = path(step.project)
+      sha = step.revision.sha
+      if step.back? then @runtime.git.roll_back(path, to: sha)
+      elsif step.forward? then @runtime.git.fast_forward(path, onto: sha, reflog_action: ACTION)
+      end
+    end
+
+    # The branch has moved by now, so a manifest that cannot be written says how to hold it there:
+    # the same command with the revision named finds nothing to move and only writes the pin.
+    def held(step, move)
+      from = move&.from || step.head
+      count = move&.count || 0
+      pin(step)
+      settled(step, from:, count:)
+    rescue Error => e
+      Outcome.new(project: step.project, word: Outcome::FAILED, reason: NOT_PINNED,
+                  details: [position(step, from, count), unpinned(step, e)])
+    end
+
+    def unpinned(step, error)
+      retry_command = "#{RolloutHistory.command('undo', step.project, @group)} --to-revision=#{step.revision.number}"
+      "spec.revision was not written: #{error.message}; run '#{retry_command}' to hold it there"
+    end
+
+    def pin(step)
+      project = step.project
+      sha = step.revision.sha
+      @runtime.store.save(project.with(revision: sha)) unless project.revision == sha
+    end
+
+    def settled(step, from: step.head, count: step.count)
+      project = step.project
+      changed = count.positive? || project.revision != step.revision.sha
+      Outcome.new(project:, word: changed ? ROLLED_BACK : Outcome::UNCHANGED,
+                  details: ["#{position(step, from, count)}; #{HELD}", following(project, step.status)])
+    end
+
+    def position(step, from, count)
+      revision = step.revision
+      branch = step.status.branch
+      target = short(revision.sha)
+      return "#{branch} is already at #{target} (revision #{revision.number})" if count.zero?
+
+      way = step.back? ? 'back' : 'forward'
+      "#{branch} #{short(from)}..#{target} (#{commits(count)} #{way} to revision #{revision.number})"
+    end
+
+    def following(project, status)
+      "'#{RolloutHistory.command('unpin', project, @group)}' follows #{status.upstream} again"
+    end
+
+    def relayed(project, error)
+      reason = error.reason
+      detail = RELAYED.fetch(reason) do
+        message = error.message.delete_prefix("#{error.path}: ")
+        reason == 'Busy' ? "#{message}; #{KEEPS_LOCKS}" : message
+      end
+      skipped(project, reason, detail)
+    end
+
+    def skipped(project, reason, detail)
+      words = COMMANDS[reason]
+      Outcome.new(project:, word: Outcome::SKIPPED, reason:,
+                  details: [detail, words && CommandLine.git(project, *words)].compact)
+    end
+
+    def refuse(reason, **values) = raise(Refused.new(reason, values))
+
+    def unmerged(count) = count == 1 ? '1 unmerged path' : "#{count} unmerged paths"
+
+    def commits(count) = count == 1 ? '1 commit' : "#{count} commits"
+
+    def short(sha) = sha[0, ABBREV]
+
+    def path(project) = Paths.expand(project.path, home: @runtime.paths.home)
+  end
+end

data/lib/slipway/rollout_history.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require_relative 'git'
+require_relative 'resources'
+
+module Slipway
+  # The revisions of a branch, read from the moves slipway left in its reflog. Git keeps the
+  # history, so slipway stores none of its own.
+  class RolloutHistory
+    # Every move slipway makes runs with GIT_REFLOG_ACTION set to "slipway <action>", and git
+    # writes "<action>: <what it did>".
+    ACTION = /\Aslipway ([^:]+):/
+    SYNC = 'sync'
+    UNDO = 'rollout undo'
+
+    # A commit the branch pointed at just before or just after a move slipway made. `action` names
+    # that move ("sync", "rollout undo"), or is nil for where the branch stood before slipway moved
+    # it; `from` is the commit the move started from, nil when the reflog no longer holds it.
+    Revision = Data.define(:number, :sha, :time, :action, :from)
+
+    # The rollout command that acts on `project`. It names the project's group unless that is
+    # `group`, the one a command typed without -n selects.
+    def self.command(verb, project, group)
+      command = "slipway rollout #{verb} #{Resources::PROJECTS.singular}/#{project.name}"
+      project.group == group ? command : "#{command} -n #{project.group}"
+    end
+
+    attr_reader :revisions
+
+    # `entries` are Git::ReflogEntry values, newest first as git lists them. Revisions count from
+    # the oldest entry git still keeps.
+    def initialize(entries)
+      @revisions = []
+      [nil, *entries.reverse].each_cons(2) { |before, entry| record(entry, before) }
+      @revisions.freeze
+    end
+
+    def empty? = revisions.empty?
+
+    def revision(number) = revisions.find { it.number == number }
+
+    # The revision before the current one. A HEAD at the newest revision makes that one the
+    # current; a HEAD that moved on without slipway makes the newest the one before.
+    def previous(head)
+      newest = revisions.last
+      newest&.sha == head ? revisions[-2] : newest
+    end
+
+    # The revision an undo returned to: the newest earlier one at the same commit.
+    def undone_to(revision) = revisions.first(revision.number - 1).reverse.find { it.sha == revision.sha }
+
+    # The newest revision at `sha`, the one spec.revision holds.
+    def pinned(sha) = revisions.reverse.find { it.sha == sha }
+
+    private
+
+    def record(entry, before)
+      action = entry.subject[ACTION, 1]
+      return unless action
+
+      add(before, nil, nil) if before && @revisions.last&.sha != before.sha
+      add(entry, action, before&.sha)
+    end
+
+    def add(entry, action, from)
+      @revisions << Revision.new(number: @revisions.size + 1, sha: entry.sha, time: entry.time, action:, from:)
+    end
+  end
+end

data/lib/slipway/runtime.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require_relative 'paths'
+require_relative 'settings'
+require_relative 'store'
+require_relative 'git'
+require_relative 'inspector'
+
+module Slipway
+  # Tests build one with fakes and a temporary store instead of calling build.
+  class Runtime
+    CONFIG_FLAG = '--config'
+    CONFIG_INLINE = "#{CONFIG_FLAG}=".freeze
+
+    attr_reader :settings, :paths, :store, :git, :inspector, :clock, :env
+
+    def self.build(context, opts)
+      paths = Paths.new(context.env, config: opts[:config])
+      settings = Settings.load(paths, env: context.env, flags: opts.slice(:color, :group))
+      clock = -> { Time.now.utc }
+      # The variable outranks the file, so a transport added to the file would change nothing.
+      protocols_source = settings.variables.fetch('protocols') { %("protocols" in #{settings.path}) }
+      git = Git::Repository.new(network_timeout: settings.network_timeout, protocols: settings.protocols,
+                                protocols_source:)
+      new(settings:, paths:, store: Store.new(root: paths.data_home, clock:), git:,
+          inspector: Inspector.new(git:, clock:, home: paths.home), clock:, env: context.env)
+    end
+
+    # Read before the command line is parsed, so a `--color` typed later still outranks it.
+    # A broken file yields no defaults; the command that runs next raises the same error with
+    # its exit status.
+    def self.color_defaults(context, argv)
+      paths = Paths.new(context.env, config: config_flag(argv))
+      settings = Settings.load(paths, env: context.env)
+      [settings.color, settings.theme]
+    rescue Settings::Error
+      [nil, nil]
+    end
+
+    def self.config_flag(argv)
+      words = argv.take_while { it != '--' }
+      words.each_with_index do |word, index|
+        return words[index + 1] if word == CONFIG_FLAG
+        return word.delete_prefix(CONFIG_INLINE) if word.start_with?(CONFIG_INLINE)
+      end
+      nil
+    end
+    private_class_method :config_flag
+
+    def initialize(settings:, paths:, store:, git:, inspector:, clock:, env:)
+      @settings = settings
+      @paths = paths
+      @store = store
+      @git = git
+      @inspector = inspector
+      @clock = clock
+      @env = env
+    end
+
+    def group_for(opts) = opts[:group] || settings.group
+
+    # Leaves the environment out so a debugging print never dumps every variable of the process.
+    def inspect = "#<#{self.class.name} data_home=#{store.root.inspect} settings=#{settings.to_h.inspect}>"
+  end
+end

data/lib/slipway/scanner.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require_relative 'error'
+
+module Slipway
+  # Finds the git repositories at and under a directory.
+  class Scanner
+    # `problems` holds a Problem for each directory that could not be read.
+    Result = Data.define(:repositories, :problems)
+    # `detail` is the system's reason alone, so the caller names the path the way it shows paths.
+    Problem = Data.define(:path, :detail)
+
+    DEFAULT_DEPTH = 1
+    MAX_DEPTH = 8
+    GIT_ENTRY = '.git'
+
+    # `root` is an absolute path; `depth` counts the levels under it that are searched.
+    def self.scan(root, depth: DEFAULT_DEPTH)
+      raise Error, "#{root}: no such directory" unless File.directory?(root)
+
+      new.walk(root, depth)
+    end
+
+    def initialize
+      @repositories = []
+      @problems = []
+    end
+
+    def walk(root, depth)
+      visit(root, depth)
+      Result.new(repositories: @repositories, problems: @problems)
+    end
+
+    private
+
+    # A .git file marks a linked worktree or a submodule, so any entry counts. Nothing under a
+    # repository is searched: nested checkouts and vendored trees belong to it.
+    def visit(directory, depth)
+      return @repositories << directory if File.exist?(File.join(directory, GIT_ENTRY))
+      return if depth.zero?
+
+      subdirectories(directory).each { visit(it, depth - 1) }
+    end
+
+    # A symbolic link is never followed, so the search stays under the root and cannot loop.
+    def subdirectories(directory)
+      paths = Dir.children(directory).sort.map { File.join(directory, it) }
+      paths.select { File.directory?(it) && !File.symlink?(it) }
+    rescue SystemCallError => e
+      @problems << Problem.new(path: directory, detail: e.message.sub(Error::SYSTEM_SUFFIX, ''))
+      []
+    end
+  end
+end

data/lib/slipway/schema.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require_relative 'names'
+require_relative 'labels'
+require_relative 'resources'
+require_relative 'git/branch_name'
+require_relative 'git/url'
+
+module Slipway
+  # The fields of each kind of manifest. The manifest reader takes its closed set of fields, their
+  # defaults and the words of its refusals from here, and the README table of a project's spec is
+  # held to it.
+  module Schema
+    STRING = 'string'
+    BOOLEAN = 'boolean'
+    OBJECT = 'Object'
+    LABEL_MAP = 'map[string]string'
+    # What a refusal says a value of each type has to be.
+    NOUNS = { STRING => 'a string', BOOLEAN => 'a boolean', OBJECT => 'a mapping', LABEL_MAP => 'a mapping' }.freeze
+
+    # `type` is the word kubectl explain prints between angle brackets. `rule` completes a sentence
+    # that starts with the field, the way a refusal quotes it; `enum` closes the field to a set of
+    # words and makes the rule when none is given. An object's `fields` are its children in the
+    # order a manifest writes them, and the object is required when one of them is.
+    Field = Data.define(:name, :type, :description, :required, :default, :enum, :rule, :fields) do
+      def initialize(name:, type:, description:, required: false, default: nil, enum: nil, rule: nil, fields: [])
+        super(name:, type:, description:, required: required || fields.any?(&:required), default:, enum:,
+              rule: rule || (enum && "must be #{enum.join(' or ')}"), fields:)
+      end
+
+      def field(name) = fields.find { it.name == name }
+
+      # nil when a name on the way is not a field.
+      def dig(*names) = names.reduce(self) { |field, name| field&.field(name) }
+
+      # The description followed by the rule as a sentence of its own.
+      def meaning = [description, rule && "#{rule[0].upcase}#{rule[1..]}."].compact.join(' ')
+    end
+
+    NAME_RULE = "must be #{Names::RULE}".freeze
+    LABELS_FIELD = Field.new(name: 'labels', type: LABEL_MAP,
+                             description: 'Key and value pairs that a label selector (-l) matches.',
+                             rule: "keys must be #{Labels::KEY_RULE}; values must be #{Labels::VALUE_RULE}")
+    TIMESTAMP_FIELD = Field.new(name: 'creationTimestamp', type: STRING, rule: 'must be an RFC 3339 timestamp',
+                                description: 'When the resource was created, in UTC. slipway sets it on ' \
+                                             'creation; written by hand, it has to be quoted.')
+    KIND_DESCRIPTION = 'The kind of resource the manifest describes.'
+    private_constant :NAME_RULE, :LABELS_FIELD, :TIMESTAMP_FIELD, :KIND_DESCRIPTION
+
+    PROJECT = Field.new(
+      name: Resources::PROJECTS.title, type: OBJECT,
+      description: 'A registered git repository: where it is on this machine and where it is expected to be, as ' \
+                   'the remote, the branch and a commit to hold it at.',
+      fields: [
+        Field.new(name: 'kind', type: STRING, required: true, enum: [Resources::PROJECTS.title],
+                  description: KIND_DESCRIPTION),
+        Field.new(
+          name: 'metadata', type: OBJECT,
+          description: 'Identifies the project: its name and group, its labels, and when it was created.',
+          fields: [
+            Field.new(name: 'name', type: STRING, required: true, rule: NAME_RULE,
+                      description: 'The name of the project, unique within its group.'),
+            Field.new(name: 'group', type: STRING, rule: NAME_RULE,
+                      description: 'The group the project belongs to; every group but default has to be created ' \
+                                   'first. When it is left out, the project goes to the group in effect: -n, then ' \
+                                   'SLIPWAY_GROUP, then the group key, then default.'),
+            LABELS_FIELD, TIMESTAMP_FIELD
+          ]
+        ),
+        Field.new(
+          name: 'spec', type: OBJECT, description: 'Where the repository is, and the state it is expected to be in.',
+          fields: [
+            Field.new(name: 'path', type: STRING, required: true, rule: 'must not be empty',
+                      description: 'The directory of the repository: an absolute path, or one starting with ~/, ' \
+                                   'which is expanded against HOME when used so that the manifest means the same ' \
+                                   'on every machine. A relative path is reported as Missing.'),
+            Field.new(name: 'description', type: STRING, description: 'What the project is, in free text.'),
+            Field.new(name: 'remote', type: STRING, rule: "must be #{Git::Url::RULE}",
+                      description: 'The URL the origin remote is expected to have; diff reports another one as ' \
+                                   'Remote drift, and no command changes a remote. A password, or any user name ' \
+                                   'over http and https, where it often carries a token, is refused; use a ' \
+                                   'credential helper.'),
+            Field.new(name: 'branch', type: STRING, rule: "must be #{Git::BranchName::RULE}",
+                      description: 'The branch expected to be checked out; diff reports another one as Branch ' \
+                                   'drift, and no command switches branches.'),
+            Field.new(name: 'revision', type: STRING,
+                      rule: 'must be a full object name, 40 or 64 lowercase hexadecimal characters',
+                      description: 'The commit the project is held at, named in full because an abbreviation can ' \
+                                   'become ambiguous. sync fast-forwards the branch up to it instead of the ' \
+                                   'upstream, never past it and never back to it. rollout undo writes it and ' \
+                                   'rollout unpin removes it.'),
+            Field.new(name: 'syncPolicy', type: STRING, enum: SyncPolicy::ALL, default: SyncPolicy::FAST_FORWARD,
+                      description: 'What sync may do to the repository: FastForward lets it fast-forward the ' \
+                                   'checked-out branch, and FetchOnly lets it fetch only.'),
+            Field.new(name: 'paused', type: BOOLEAN, default: false,
+                      description: 'When true, fetch and sync leave the project alone: they report it as ' \
+                                   'paused and run no git command there. rollout pause sets it and rollout ' \
+                                   'resume removes it.')
+          ]
+        )
+      ]
+    )
+
+    GROUP = Field.new(
+      name: Resources::GROUPS.title, type: OBJECT,
+      description: 'A namespace that holds projects, the way a Kubernetes namespace holds pods. Deleting a group ' \
+                   'removes the registrations of its projects.',
+      fields: [
+        Field.new(name: 'kind', type: STRING, required: true, enum: [Resources::GROUPS.title],
+                  description: KIND_DESCRIPTION),
+        Field.new(
+          name: 'metadata', type: OBJECT,
+          description: 'Identifies the group: its name, its labels, and when it was created.',
+          fields: [
+            Field.new(name: 'name', type: STRING, required: true, rule: NAME_RULE,
+                      description: 'The name of the group, unique in the registry.'),
+            LABELS_FIELD, TIMESTAMP_FIELD
+          ]
+        ),
+        Field.new(name: 'spec', type: OBJECT, description: 'What the group is for.',
+                  fields: [Field.new(name: 'description', type: STRING,
+                                     description: 'What the group holds, in free text.')])
+      ]
+    )
+
+    KINDS = [PROJECT, GROUP].to_h { [it.name, it] }.freeze
+  end
+end