dr_talon 0.1.0

data/lib/dr_talon/deps/dependency.rb

@@ -0,0 +1,238 @@
+# frozen_string_literal: true
+
+require "digest"
+require "tmpdir"
+require "uri"
+
+module DrTalon
+  module Deps
+    # Where sources fetch from; tests swap in local fakes.
+    Context = Data.define(:http, :git, :github_url, :codeload_url) do
+      def self.default
+        new(http: DrTalon::HTTP.new, git: Git.new, github_url: "https://github.com", codeload_url: "https://codeload.github.com")
+      end
+    end
+
+    # One entry in +dependencies.rb+: where it comes from and where it's
+    # vendored inside the game directory.
+    class Dependency
+      VENDOR = "vendor"
+
+      # @return [String] short name, used by `talon add/remove/update`
+      attr_reader :name
+      # @return [String] game-relative path the files are written to
+      attr_reader :destination
+      # @return [String, nil] requested branch, tag or commit
+      attr_reader :ref
+      # @return [Integer, nil] line in dependencies.rb that declared it
+      attr_reader :line
+
+      # @param name [String, nil] defaults to {#default_name}
+      # @param destination [String, nil] defaults to vendor/NAME
+      def initialize(name: nil, destination: nil, ref: nil, line: nil)
+        @ref = ref&.to_s
+        @line = line
+        @destination = destination&.to_s || "#{VENDOR}/#{name || default_name}"
+        @name = (name || (destination ? File.basename(@destination) : default_name)).to_s
+        validate_destination!
+      end
+
+      # @return [String] the lock key, in Foodchain's format where one exists
+      def key
+        raise NotImplementedError
+      end
+
+      # @return [Boolean] whether {#resolve} pins a version (path deps don't)
+      def lockable?
+        true
+      end
+
+      # The commit (or content digest) to install for the current {#ref}.
+      #
+      # @param context [Context]
+      # @return [String, nil]
+      def resolve(context)
+        raise NotImplementedError
+      end
+
+      # Writes the dependency's files for +commit+ to +target+.
+      #
+      # @param context [Context]
+      # @param commit [String, nil]
+      # @param target [String] absolute path; doesn't exist yet
+      # @return [void]
+      def fetch(context, commit, target)
+        raise NotImplementedError
+      end
+
+      # @return [String] e.g. "github:asimmons91/talon (lib)"
+      def to_s
+        key
+      end
+
+      private
+
+      def default_name
+        raise NotImplementedError
+      end
+
+      def validate_destination!
+        parts = @destination.split("/")
+        return if parts.first == VENDOR && parts.size > 1 && !parts.include?("..") && !parts.include?("") &&
+          !@destination.start_with?("/")
+
+        raise ManifestError, "Dependency destination #{@destination.inspect} must be inside #{VENDOR}/, " \
+          "e.g. #{VENDOR}/#{File.basename(@destination)}. talon replaces it on install."
+      end
+
+      def subpath_name(subpath, fallback)
+        base = File.basename(subpath.to_s)
+        (subpath.to_s.empty? || !base.include?(".")) ? fallback : base
+      end
+    end
+
+    # A path inside a GitHub repository, downloaded as a tarball of the
+    # resolved commit.
+    class GitHubDependency < Dependency
+      attr_reader :owner, :repo, :subpath
+
+      def initialize(owner, repo, subpath: nil, **options)
+        @owner = owner.to_s
+        @repo = repo.to_s
+        @subpath = subpath.to_s.delete_prefix("/").delete_suffix("/")
+        super(**options)
+      end
+
+      def key
+        ["github:#{owner}/#{repo}", (subpath unless subpath.empty?)].compact.join("/")
+      end
+
+      def resolve(context)
+        context.git.resolve("#{context.github_url}/#{owner}/#{repo}.git", ref)
+      end
+
+      def fetch(context, commit, target)
+        data = context.http.get("#{context.codeload_url}/#{owner}/#{repo}/tar.gz/#{commit}")
+        Dir.mktmpdir("talon-github") do |dir|
+          Tree.untar(data, dir)
+          Tree.copy_subpath(dir, subpath, target)
+        end
+      end
+
+      private
+
+      def default_name
+        subpath_name(subpath, repo)
+      end
+    end
+
+    # A path inside any git repository, fetched with the git CLI.
+    class GitDependency < Dependency
+      attr_reader :url, :subpath
+
+      def initialize(url, subpath: nil, **options)
+        @url = url.to_s
+        @subpath = subpath.to_s.delete_prefix("/").delete_suffix("/")
+        super(**options)
+      end
+
+      def key
+        subpath.empty? ? "git:#{url}" : "git:#{url}?path=#{subpath}"
+      end
+
+      def resolve(context)
+        context.git.resolve(url, ref)
+      end
+
+      def fetch(context, commit, target)
+        Dir.mktmpdir("talon-git") do |dir|
+          checkout = File.join(dir, "repo")
+          context.git.checkout(url, commit, checkout)
+          Tree.copy_subpath(checkout, subpath, target)
+        end
+      end
+
+      private
+
+      def default_name
+        subpath_name(subpath, File.basename(url.chomp("/"), ".git"))
+      end
+    end
+
+    # A single file downloaded from a URL, pinned by its SHA-256.
+    class URLDependency < Dependency
+      attr_reader :url
+
+      def initialize(url, **options)
+        @url = url.to_s
+        super(**options)
+      end
+
+      def key
+        url
+      end
+
+      def resolve(context)
+        @body = context.http.get(url)
+        "sha256:#{Digest::SHA256.hexdigest(@body)}"
+      end
+
+      def fetch(context, commit, target)
+        body = @body || context.http.get(url)
+        digest = "sha256:#{Digest::SHA256.hexdigest(body)}"
+        if commit && digest != commit
+          raise FetchError, "#{url} has changed since it was locked. Run `talon update #{name}` to accept the new version."
+        end
+
+        FileUtils.mkdir_p(File.dirname(target))
+        File.binwrite(target, body)
+      end
+
+      private
+
+      def default_name
+        File.basename(URI(url).path)
+      rescue URI::InvalidURIError
+        raise ManifestError, "Invalid URL: #{url}"
+      end
+    end
+
+    # A local file or directory, copied on every install. For developing a
+    # library alongside a game.
+    class PathDependency < Dependency
+      attr_reader :path
+
+      # @param path [String] as written in dependencies.rb
+      # @param base [String] what a relative +path+ is relative to
+      def initialize(path, base:, **options)
+        @path = path.to_s
+        @absolute = File.expand_path(@path, base)
+        super(**options)
+      end
+
+      def key
+        "path:#{path}"
+      end
+
+      def lockable?
+        false
+      end
+
+      def resolve(_context)
+        nil
+      end
+
+      def fetch(_context, _commit, target)
+        raise FetchError, "#{@absolute} doesn't exist." unless File.exist?(@absolute)
+
+        Tree.copy_subpath(@absolute, "", target)
+      end
+
+      private
+
+      def default_name
+        File.basename(@path.chomp("/"))
+      end
+    end
+  end
+end

data/lib/dr_talon/deps/git.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "open3"
+
+module DrTalon
+  module Deps
+    # Runs the git CLI, for resolving refs and fetching git dependencies.
+    class Git
+      FULL_SHA = /\A\h{40}\z/
+
+      # Resolves +ref+ (a branch, tag or full commit SHA; nil for the default
+      # branch) to a commit SHA without cloning.
+      #
+      # @param url [String]
+      # @param ref [String, nil]
+      # @return [String]
+      # @raise [FetchError]
+      def resolve(url, ref)
+        return ref.downcase if ref&.match?(FULL_SHA)
+
+        refs = ls_remote(url).to_h { |line| line.split("\t", 2).reverse }
+        candidates =
+          if ref.nil?
+            ["HEAD"]
+          else
+            ["refs/tags/#{ref}^{}", "refs/tags/#{ref}", "refs/heads/#{ref}"]
+          end
+        sha = candidates.filter_map { |name| refs[name] }.first
+        return sha if sha
+
+        hint = ref&.match?(/\A\h{4,39}\z/) ? " Abbreviated SHAs aren't supported; use all 40 characters." : ""
+        raise FetchError, "#{url} has no branch or tag named #{ref.inspect}.#{hint}"
+      end
+
+      # Checks out +commit+ of +url+ into +dir+ (which must not exist).
+      #
+      # @return [void]
+      # @raise [FetchError]
+      def checkout(url, commit, dir)
+        run("init", "--quiet", dir)
+        run("-C", dir, "fetch", "--quiet", "--depth", "1", url, commit)
+        run("-C", dir, "-c", "advice.detachedHead=false", "checkout", "--quiet", "FETCH_HEAD")
+      rescue FetchError
+        # Some servers don't allow fetching an arbitrary commit; fall back to a
+        # full clone.
+        FileUtils.rm_rf(dir)
+        run("clone", "--quiet", "--no-checkout", url, dir)
+        run("-C", dir, "-c", "advice.detachedHead=false", "checkout", "--quiet", commit)
+      end
+
+      private
+
+      def ls_remote(url)
+        run("ls-remote", url).lines(chomp: true)
+      end
+
+      def run(*args)
+        out, err, status = Open3.capture3("git", *args)
+        # git's first line says what went wrong; the rest is generic advice.
+        raise FetchError, "git #{args.first} failed: #{err.lines.map(&:strip).find { |l| !l.empty? }}" unless status.success?
+
+        out
+      rescue Errno::ENOENT
+        raise FetchError, "git isn't installed; it's needed for git and GitHub dependencies."
+      end
+    end
+  end
+end

data/lib/dr_talon/deps/installer.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "tmpdir"
+
+module DrTalon
+  module Deps
+    # Brings vendored files in line with +dependencies.rb+ and its locks.
+    #
+    # - Locked dependencies install their locked commit; new ones, ones whose
+    #   ref or destination changed, and ones being updated are resolved again.
+    # - Vendored files are replaced only when they're unchanged since talon
+    #   wrote them (or identical to what would be written); otherwise the
+    #   install stops unless +force+.
+    # - Dependencies removed from the manifest have their files deleted.
+    # - Locks are written even when a later dependency fails, so finished work
+    #   isn't reported as modified next time.
+    class Installer
+      # @!attribute [r] name
+      #   @return [String]
+      # @!attribute [r] action
+      #   @return [Symbol] +:installed+, +:updated+, +:unchanged+, +:restored+
+      #     (local changes replaced with --force), +:removed+ or +:kept+
+      #     (removed from the manifest but locally modified)
+      # @!attribute [r] dependency
+      #   @return [Dependency, nil] nil for removals
+      # @!attribute [r] commit
+      #   @return [String, nil]
+      # @!attribute [r] previous
+      #   @return [String, nil] the commit before an update
+      Change = Data.define(:name, :action, :dependency, :commit, :previous)
+
+      # @param project [Project]
+      # @param context [Context]
+      # @param force [Boolean] overwrite or delete locally modified vendored files
+      def initialize(project, context: Context.default, force: false)
+        @project = project
+        @context = context
+        @force = force
+      end
+
+      # @param update [Array<String>, true, nil] names to re-resolve, or true for all
+      # @return [Array<Change>]
+      # @raise [ModifiedError] if vendored files were edited and +force+ is off
+      # @raise [Error] if +update+ names an unknown dependency
+      def install(update: nil)
+        manifest = Manifest.for(@project)
+        check_update_names!(manifest, update)
+        previous = manifest.locks.to_h { |lock| [lock.key, lock] }
+        written = {}
+        changes = []
+
+        begin
+          manifest.dependencies.each do |dependency|
+            lock, change = install_dependency(dependency, previous[dependency.key], updating?(dependency, update))
+            written[dependency.key] = lock
+            changes << change
+          end
+
+          (previous.keys - manifest.dependencies.map(&:key)).each do |key|
+            changes << remove(previous[key])
+            previous.delete(key)
+          end
+        ensure
+          # Keep locks for anything not reached (including removals not done
+          # yet), so a failure doesn't forget them.
+          unreached = previous.reject { |key, _| written.key?(key) }
+          manifest.write_locks(written.values + unreached.values) if manifest.exist? || written.any?
+        end
+
+        changes
+      end
+
+      # @return [Array<Hash>] +dependency+, +locked+ and +latest+ commits of
+      #   dependencies whose source has moved on
+      def outdated
+        manifest = Manifest.for(@project)
+        locks = manifest.locks.to_h { |lock| [lock.key, lock] }
+
+        manifest.dependencies.select(&:lockable?).filter_map do |dependency|
+          locked = locks[dependency.key]&.commit
+          latest = dependency.resolve(@context)
+          {dependency: dependency, locked: locked, latest: latest} if locked != latest
+        end
+      end
+
+      # Vendored dependencies whose files no longer match their locks.
+      #
+      # @return [Array<Hash>] +dependency+ and +problem+ (+:missing+,
+      #   +:modified+ or +:unlocked+)
+      def problems
+        manifest = Manifest.for(@project)
+        locks = manifest.locks.to_h { |lock| [lock.key, lock] }
+
+        manifest.dependencies.filter_map do |dependency|
+          lock = locks[dependency.key]
+          checksum = Tree.checksum(game_path(dependency.destination))
+          problem =
+            if lock.nil? || lock.destination != dependency.destination then :unlocked
+            elsif checksum.nil? then :missing
+            elsif checksum != lock.checksum then :modified
+            end
+          {dependency: dependency, problem: problem} if problem
+        end
+      end
+
+      private
+
+      def check_update_names!(manifest, update)
+        return unless update.is_a?(Array)
+
+        unknown = update.reject { |name| manifest.find(name) }
+        raise Error, "Unknown dependenc#{(unknown.size == 1) ? "y" : "ies"}: #{unknown.join(", ")}" if unknown.any?
+      end
+
+      def updating?(dependency, update)
+        update == true || (update.is_a?(Array) && update.any? { |name| [dependency.name, dependency.key].include?(name) })
+      end
+
+      def install_dependency(dependency, lock, updating)
+        reusable = lock && !updating && dependency.lockable? &&
+          lock.ref == dependency.ref && lock.destination == dependency.destination
+        target = game_path(dependency.destination)
+        current = Tree.checksum(target)
+
+        if reusable && current && current == lock.checksum
+          return [lock, change(dependency, :unchanged, lock.commit)]
+        end
+
+        commit = reusable ? lock.commit : dependency.resolve(@context)
+        managed = lock && lock.destination == dependency.destination
+
+        staged_checksum = stage(dependency, commit) do |staged|
+          checksum = Tree.checksum(staged)
+          if current && current != checksum && (!managed || current != lock.checksum) && !@force
+            raise ModifiedError, "#{relative(target)} has changes talon didn't make. " \
+              "Move them aside, or pass --force to replace them with #{dependency.name}."
+          end
+
+          replace(target, staged) unless current == checksum
+          checksum
+        end
+
+        remove_path(game_path(lock.destination)) if lock && lock.destination != dependency.destination
+
+        new_lock = Lock.new(key: dependency.key, ref: dependency.ref, destination: dependency.destination,
+          commit: commit, checksum: staged_checksum)
+        action =
+          if lock.nil? || current.nil? then :installed
+          elsif lock.commit != commit then :updated
+          elsif current == staged_checksum then :unchanged
+          elsif dependency.lockable? then :restored
+          else :updated
+          end
+        [new_lock, change(dependency, action, commit, lock&.commit)]
+      end
+
+      def remove(lock)
+        target = game_path(lock.destination)
+        current = Tree.checksum(target)
+        if current && current != lock.checksum && !@force
+          return Change.new(name: File.basename(lock.destination), action: :kept, dependency: nil, commit: nil, previous: nil)
+        end
+
+        remove_path(target)
+        Change.new(name: File.basename(lock.destination), action: :removed, dependency: nil, commit: nil, previous: lock.commit)
+      end
+
+      def change(dependency, action, commit, previous = nil)
+        Change.new(name: dependency.name, action: action, dependency: dependency, commit: commit, previous: previous)
+      end
+
+      # Fetches into a scratch directory on the project's filesystem and
+      # yields the fetched path.
+      def stage(dependency, commit)
+        scratch = @project.path(".talon")
+        FileUtils.mkdir_p(scratch)
+        Dir.mktmpdir("deps-", scratch) do |dir|
+          staged = File.join(dir, File.basename(dependency.destination))
+          dependency.fetch(@context, commit, staged)
+          yield staged
+        end
+      end
+
+      def replace(target, staged)
+        FileUtils.rm_rf(target)
+        FileUtils.mkdir_p(File.dirname(target))
+        File.rename(staged, target)
+      end
+
+      def remove_path(path)
+        FileUtils.rm_rf(path)
+        # Tidy up an emptied vendor/ (but never the game directory itself).
+        dir = File.dirname(path)
+        Dir.rmdir(dir) if dir != @project.game_dir && File.directory?(dir) && Dir.empty?(dir)
+      end
+
+      def game_path(relative)
+        File.join(@project.game_dir, relative)
+      end
+
+      def relative(path)
+        path.delete_prefix("#{@project.root}/")
+      end
+    end
+  end
+end