slipway 0.1.0

data/lib/slipway/paths.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Slipway
+  # Follows the XDG Base Directory Specification. Reads only the environment Hash it is
+  # given, so tests never touch ENV.
+  class Paths
+    CONFIG_VARIABLE = 'SLIPWAY_CONFIG'
+    DATA_HOME_VARIABLE = 'SLIPWAY_DATA_HOME'
+    HOME_VARIABLE = 'HOME'
+    XDG_CONFIG_HOME_VARIABLE = 'XDG_CONFIG_HOME'
+    XDG_DATA_HOME_VARIABLE = 'XDG_DATA_HOME'
+    APP = 'slipway'
+    CONFIG_FILE = 'config.yaml'
+    MAN_SECTION = File.join('man', 'man1').freeze
+    TILDE = %r{\A~(?=/|\z)}
+
+    XDG_DEFAULTS = {
+      XDG_CONFIG_HOME_VARIABLE => '.config',
+      XDG_DATA_HOME_VARIABLE => File.join('.local', 'share')
+    }.freeze
+
+    # Only a bare `~` or `~/` is expanded; `~user` forms and relative paths stay as written.
+    def self.expand(value, home:) = value&.sub(TILDE, home)
+
+    def initialize(env, config: nil)
+      @env = env
+      @config_flag = present(config)
+    end
+
+    def home = present(@env[HOME_VARIABLE]) || Dir.home
+
+    def config_file
+      @config_flag || expand(present(@env[CONFIG_VARIABLE])) ||
+        File.join(xdg(XDG_CONFIG_HOME_VARIABLE), APP, CONFIG_FILE)
+    end
+
+    # A missing explicit file is an error, a missing default is not.
+    def config_explicit? = !(@config_flag || present(@env[CONFIG_VARIABLE])).nil?
+
+    def data_home = expand(present(@env[DATA_HOME_VARIABLE])) || File.join(xdg(XDG_DATA_HOME_VARIABLE), APP)
+
+    def man_install_dir = File.join(xdg(XDG_DATA_HOME_VARIABLE), MAN_SECTION)
+
+    # The one user directory man-db searches on its own, when ~/.local/bin is on PATH.
+    def man_db_dir = File.join(home, XDG_DEFAULTS.fetch(XDG_DATA_HOME_VARIABLE), MAN_SECTION)
+
+    private
+
+    # The specification says an unset or empty variable takes its default and a relative
+    # path is invalid and ignored.
+    def xdg(name)
+      value = present(@env[name])
+      return value if value && File.absolute_path?(value)
+
+      File.join(home, XDG_DEFAULTS.fetch(name))
+    end
+
+    def present(value)
+      value unless value.nil? || value.empty?
+    end
+
+    # A leading ~ refers to the HOME the environment names, not the one Ruby started with.
+    def expand(value) = self.class.expand(value, home:)
+  end
+end

data/lib/slipway/plan.rb

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+require 'shellwords'
+require_relative 'command_line'
+require_relative 'drift'
+require_relative 'git'
+require_relative 'resources'
+
+module Slipway
+  # What differs between a project and its manifest, and what sync would do about it, read from
+  # one Inspection. It runs no git and reads no file, so every verb that shows drift reads the
+  # same answer.
+  module Plan
+    # `actions` is the drift sync resolves, `reports` the drift it leaves as it is, and `skips`
+    # the blockers that stop it. A Behind action moves the branch onto its upstream and a
+    # Revision action onto the pinned revision.
+    Result = Data.define(:actions, :skips, :reports) do
+      def items = [*(actions + reports).sort_by { Drift::TYPES.index(it.type) }, *skips]
+
+      def fast_forward? = actions.any? { Drift::MOVES.include?(it.type) }
+
+      def to_revision? = actions.any? { it.type == Drift::REVISION }
+
+      def converged? = items.empty?
+    end
+
+    def self.for(inspection) = Planner.new(inspection).result
+
+    class Planner
+      ABBREVIATION = Git::Porcelain::ABBREVIATION
+      FAST_FORWARD = 'sync will fast-forward'
+      FETCH_ONLY = "syncPolicy is #{SyncPolicy::FETCH_ONLY}".freeze
+      PAUSED = 'the project is paused'
+      KEEPS_REMOTE = 'sync never changes a remote'
+
+      def initialize(inspection)
+        @inspection = inspection
+        @project = inspection.project
+        @status = inspection.status
+      end
+
+      def result
+        return unreadable(@inspection.error) if @inspection.error
+
+        declared = [remote, branch].compact
+        @project.revision ? pinned(declared) : following(declared)
+      end
+
+      private
+
+      def outcome(actions: [], skips: [], reports: []) = Result.new(actions:, skips:, reports:)
+
+      # A paused or FetchOnly project is never moved, so nothing can block it.
+      def following(declared)
+        held = hold
+        return outcome(reports: [*declared, *behind(held)]) if held
+
+        position = unfollowable
+        return outcome(reports: declared, skips: [position]) if position
+        return outcome(reports: declared) unless behind?
+
+        blocker = upstream_obstacle
+        return outcome(reports: [*declared, *behind], skips: [blocker]) if blocker
+
+        outcome(actions: behind(FAST_FORWARD), reports: declared)
+      end
+
+      # The pinned revision replaces the upstream as where the branch should be. Sync moves the
+      # branch forward to it and never back: a move back is not a fast-forward.
+      def pinned(declared)
+        return outcome(reports: declared) if @inspection.at_pin?
+
+        held = hold
+        return outcome(reports: [*declared, revision(held)]) if held
+
+        blocker = unfollowable || pin_obstacle
+        return outcome(reports: [*declared, revision], skips: [blocker]) if blocker
+
+        outcome(actions: [revision(FAST_FORWARD)], reports: declared)
+      end
+
+      def hold
+        return PAUSED if @project.paused
+
+        FETCH_ONLY if @project.sync_policy == SyncPolicy::FETCH_ONLY
+      end
+
+      def behind? = @status.behind.to_i.positive?
+
+      def behind(consequence = nil)
+        return [] unless behind?
+
+        message = "#{count(@status.behind, 'commit')} behind #{@status.upstream}"
+        [Drift::Item.new(type: Drift::BEHIND, message: [message, consequence].compact.join('; '))]
+      end
+
+      # Without a branch that tracks an upstream that still exists, nothing says where the branch
+      # should be; a pinned branch needs one too, since the fast-forward checks it the same way.
+      def unfollowable
+        upstream = @status.upstream
+        return Drift.blocker('Detached', head: @status.head, command: git('status')) if @status.detached?
+        return Drift.blocker('Unborn') if @status.unborn?
+        return Drift.blocker('Gone', upstream:, command: git('branch', '-vv')) if @status.upstream_gone?
+
+        no_upstream if upstream.nil?
+      end
+
+      def upstream_obstacle = local_changes || (diverged if @status.ahead.to_i.positive?) || in_progress
+
+      def pin_obstacle = unreachable_pin || local_changes || in_progress
+
+      # HEAD past the pin, or on another line of history, would have to move back to reach it. A
+      # pin the upstream lacks, or was not compared with, could be on any branch or fork the
+      # repository has fetched, and a manifest must not move a branch there.
+      def unreachable_pin
+        pin = short(@project.revision)
+        distance = @inspection.pin
+        return Drift.blocker('RevisionNotFound', revision: pin) if distance.nil?
+        return past_revision(pin) if distance.ahead.positive?
+        return if distance.off_upstream&.zero?
+
+        Drift.blocker('OffUpstream', revision: pin, upstream: @status.upstream,
+                                     command: git('log', '--oneline', "@{upstream}..#{pin}"))
+      end
+
+      def past_revision(pin)
+        Drift.blocker('PastRevision', branch: @status.branch, command: git('log', '--oneline', "#{pin}..HEAD"))
+      end
+
+      def local_changes
+        return conflicted if @status.conflicted.positive?
+
+        dirty if @status.staged.positive? || @status.unstaged.positive?
+      end
+
+      # The operation in progress is known only for a project that would otherwise fast-forward,
+      # so it is checked last.
+      def in_progress
+        operation = @inspection.operation
+        Drift.blocker('InProgress', operation:, command: git('status')) if operation
+      end
+
+      def unreadable(error)
+        case error
+        when Git::RelativePath then outcome(reports: [missing(reason(error), clone: false)])
+        when Git::MissingPath then outcome(reports: [missing("no directory at #{@project.path}")])
+        when Git::NotARepository then outcome(skips: [Drift.blocker('NotARepo', path: @project.path)])
+        when Git::UnsafeRepository
+          outcome(skips: [Drift.blocker('Unsafe', reason: reason(error), command: error.command)])
+        else outcome(skips: [Drift.blocker('Unknown', reason: reason(error))])
+        end
+      end
+
+      def missing(message, clone: true)
+        url = @project.remote
+        command = "git clone -- #{Shellwords.escape(url)} #{CommandLine.path(@project.path)}" if clone && url
+        Drift::Item.new(type: Drift::MISSING, message:, command:)
+      end
+
+      def remote
+        wanted = @project.remote
+        actual = @inspection.remote
+        return if wanted.nil? || actual == wanted
+
+        url = Shellwords.escape(wanted)
+        if actual.nil?
+          return Drift::Item.new(type: Drift::REMOTE, message: "no origin, manifest says #{wanted}; #{KEEPS_REMOTE}",
+                                 command: git('remote', 'add', 'origin', url))
+        end
+
+        Drift::Item.new(type: Drift::REMOTE, message: "origin is #{actual}, manifest says #{wanted}; #{KEEPS_REMOTE}",
+                        command: git('remote', 'set-url', 'origin', url))
+      end
+
+      def branch
+        wanted = @project.branch
+        actual = @status.branch
+        return if wanted.nil? || actual == wanted
+
+        head = actual ? "HEAD is on #{actual}" : 'HEAD is detached'
+        Drift::Item.new(type: Drift::BRANCH, message: "#{head}, manifest says #{wanted}; sync never switches branches",
+                        command: git('switch', Shellwords.escape(wanted)))
+      end
+
+      def revision(consequence = nil)
+        sha = @inspection.commit&.sha
+        head = sha ? "HEAD is at #{short(sha)}" : 'HEAD has no commits'
+        message = ["#{head}, manifest pins #{short(@project.revision)}", consequence].compact.join('; ')
+        Drift::Item.new(type: Drift::REVISION, message:)
+      end
+
+      # The command names origin, so it is offered only when origin exists, and only for a branch
+      # name that cannot reach the shell as anything but a word.
+      def no_upstream
+        name = @status.branch
+        if @inspection.remote && Git::BranchName.valid?(name)
+          command = git('branch', "--set-upstream-to=origin/#{name}")
+        end
+        Drift.blocker('NoUpstream', branch: name, command:)
+      end
+
+      def conflicted
+        Drift.blocker('Conflicted', paths: count(@status.conflicted, 'unmerged path'), command: git('status'))
+      end
+
+      def dirty
+        changes = { 'staged' => @status.staged, 'unstaged' => @status.unstaged }
+                  .filter_map { |kind, number| "#{number} #{kind}" if number.positive? }.join(', ')
+        Drift.blocker('Dirty', changes:, command: git('status'))
+      end
+
+      def diverged
+        Drift.blocker('Diverged', ahead: @status.ahead, behind: @status.behind, upstream: @status.upstream,
+                                  command: git('log', '--oneline', '--left-right', 'HEAD...@{upstream}'))
+      end
+
+      def count(number, noun) = "#{number} #{noun}#{'s' unless number == 1}"
+
+      def short(sha) = sha[0, ABBREVIATION]
+
+      def reason(error) = error.message.delete_prefix("#{error.path}: ")
+
+      def git(*words) = CommandLine.git(@project, *words)
+    end
+    private_constant :Planner
+  end
+end

data/lib/slipway/pool.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Slipway
+  # Runs one block per item on at most `workers` threads; results come back in input order,
+  # whatever order the items finish in.
+  #
+  # However a call ends early (an exception from an item, an interrupt, a consumer that raises),
+  # the workers are killed and waited for before the exception leaves it: killing a thread runs
+  # its ensure blocks, which is how Git::Runner sends TERM to a git still running. An exception
+  # from an item is re-raised on the calling thread as soon as it is seen, without waiting for
+  # the other items, because callers turn the failures they expect into results and anything
+  # else is a bug or a fatal condition.
+  class Pool
+    attr_reader :workers
+
+    def initialize(workers:)
+      raise ArgumentError, "workers must be a positive Integer, not #{workers.inspect}" unless positive?(workers)
+
+      @workers = workers
+    end
+
+    def map(items, &work)
+      results = []
+      each_ordered(items, work) { results << it }
+      results
+    end
+
+    # Yields each result on the calling thread as soon as every earlier item is done, so a
+    # caller that prints one line per item streams them in input order.
+    def each_ordered(items, work, &)
+      threads = []
+      begin
+        jobs = Queue.new
+        items.each_with_index { |item, index| jobs << [index, item] }
+        jobs.close
+        done = Queue.new
+        # An interrupt between Thread.new and the append would leave a worker that stop never sees.
+        Thread.handle_interrupt(Exception => :never) do
+          [@workers, items.size].min.times { threads << worker(jobs, done, work) }
+        end
+        deliver(items.size, done, &)
+      ensure
+        stop(threads)
+      end
+    end
+
+    private
+
+    def positive?(workers) = workers.is_a?(Integer) && workers.positive?
+
+    # A worker pushes itself when it ends, so the caller joins one that died of an exception,
+    # which re-raises it once, instead of waiting for a result that never comes.
+    def worker(jobs, done, work)
+      Thread.new do
+        Thread.current.report_on_exception = false
+        # A thread inherits its creator's interrupt mask; without lifting it, an exception sent
+        # with Thread#raise would wait until the worker ends.
+        Thread.handle_interrupt(Exception => :immediate) do
+          while (job = jobs.pop)
+            index, item = job
+            done << [index, work.call(item)]
+          end
+        end
+      ensure
+        done << Thread.current
+      end
+    end
+
+    def deliver(count, done)
+      pending = {}
+      delivered = 0
+      while delivered < count
+        message = done.pop
+        if message.is_a?(Thread)
+          message.join
+        else
+          pending.store(*message)
+        end
+        while pending.key?(delivered)
+          yield pending.delete(delivered)
+          delivered += 1
+        end
+      end
+    end
+
+    # A worker that died of an exception has nothing left to wait for, and joining it would
+    # raise that exception again over the one already leaving the call. An interrupt between
+    # two kills would leave the rest running, so the kills are masked.
+    def stop(threads)
+      Thread.handle_interrupt(Exception => :never) { threads.each(&:kill) }
+      threads.each { it.join unless it.status.nil? }
+    end
+  end
+end

data/lib/slipway/resources.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require_relative 'error'
+
+module Slipway
+  # The values of spec.syncPolicy, capitalized as Kubernetes enums are (imagePullPolicy: IfNotPresent).
+  module SyncPolicy
+    FAST_FORWARD = 'FastForward'
+    FETCH_ONLY = 'FetchOnly'
+    ALL = [FAST_FORWARD, FETCH_ONLY].freeze
+  end
+
+  # A registered git repository.
+  Project = Data.define(:name, :group, :labels, :created_at, :path, :description, :remote, :branch, :revision,
+                        :sync_policy, :paused) do
+    def initialize(name:, path:, group: 'default', labels: {}, created_at: nil, description: nil, remote: nil,
+                   branch: nil, revision: nil, sync_policy: SyncPolicy::FAST_FORWARD, paused: false)
+      super
+    end
+
+    def kind = 'Project'
+
+    # Key order here is the order written to disk.
+    def to_manifest
+      metadata = { 'name' => name, 'group' => group, 'labels' => labels.sort.to_h,
+                   'creationTimestamp' => Resources.timestamp(created_at) }.compact
+      { 'kind' => kind, 'metadata' => metadata, 'spec' => spec }
+    end
+
+    def with_labels(labels) = with(labels:)
+
+    private
+
+    # A field at its default is left out, so a manifest written before the field existed is
+    # written back byte for byte and apply reads it as unchanged.
+    def spec
+      { 'path' => path, 'description' => description, 'remote' => remote, 'branch' => branch,
+        'revision' => revision, 'syncPolicy' => (sync_policy unless sync_policy == SyncPolicy::FAST_FORWARD),
+        'paused' => (true if paused) }.compact
+    end
+  end
+
+  Group = Data.define(:name, :labels, :created_at, :description) do
+    def initialize(name:, labels: {}, created_at: nil, description: nil)
+      super
+    end
+
+    def kind = 'Group'
+
+    # Key order here is the order written to disk.
+    def to_manifest
+      metadata = { 'name' => name, 'labels' => labels.sort.to_h,
+                   'creationTimestamp' => Resources.timestamp(created_at) }.compact
+      { 'kind' => kind, 'metadata' => metadata, 'spec' => { 'description' => description }.compact }
+    end
+
+    def with_labels(labels) = with(labels:)
+  end
+
+  module Resources
+    Kind = Data.define(:plural, :singular, :aliases, :klass) do
+      def names = [plural, singular, *aliases]
+
+      # Case-insensitive, like kubectl.
+      def match?(word) = names.include?(word.downcase)
+
+      # Projects live inside a group the way pods live inside a namespace.
+      def namespaced? = klass == Project
+
+      def title = singular.capitalize
+    end
+
+    PROJECTS = Kind.new(plural: 'projects', singular: 'project', aliases: %w[proj], klass: Project)
+    GROUPS = Kind.new(plural: 'groups', singular: 'group', aliases: [], klass: Group)
+    KINDS = [PROJECTS, GROUPS].freeze
+    # Created on first use.
+    DEFAULT_GROUP = 'default'
+
+    def self.resolve(word)
+      KINDS.find { it.match?(word) } ||
+        raise(Error, "unknown resource type #{word.inspect} (known types: #{KINDS.map(&:plural).join(', ')})")
+    end
+
+    def self.of(resource)
+      KINDS.find { resource.is_a?(it.klass) } || raise(ArgumentError, "not a resource: #{resource.inspect}")
+    end
+
+    # RFC 3339 in UTC with second precision, the form creationTimestamp takes on disk.
+    def self.timestamp(time) = time&.getutc&.iso8601
+  end
+end