dr_talon 0.1.0

data/lib/dr_talon/deps/manifest.rb

@@ -0,0 +1,220 @@
+# frozen_string_literal: true
+
+module DrTalon
+  module Deps
+    # One pinned dependency, stored as a tab-separated line below +__END__+:
+    #
+    #   key  ref  destination  commit  checksum
+    #
+    # +ref+ and +commit+ are "-" when absent; +checksum+ covers the vendored
+    # files so local edits can be detected.
+    Lock = Data.define(:key, :ref, :destination, :commit, :checksum) do
+      def self.parse(line)
+        fields = line.split("\t").map { |field| (field == "-") ? nil : field }
+        new(*fields) if fields.size == members.size
+      end
+
+      def to_line
+        to_a.map { |field| field || "-" }.join("\t")
+      end
+
+      def to_a
+        [key, ref, destination, commit, checksum]
+      end
+    end
+
+    # +dependencies.rb+ in the game directory: a Ruby DSL above +__END__+,
+    # owned by the user, and lock lines below it, owned by talon. The DSL is
+    # compatible with Foodchain's (+github :owner, :repo, "path", destination:+).
+    class Manifest
+      FILE = "dependencies.rb"
+      SEPARATOR = /^__END__\r?\n?/
+      LOCK_HEADER = <<~TEXT
+        # The lines below pin the versions of your installed dependencies.
+        # Managed by `talon install` / `talon update`; do not edit by hand.
+      TEXT
+
+      # @return [String]
+      attr_reader :path
+      # @return [String] everything above __END__
+      attr_reader :config
+      # @return [Array<Dependency>]
+      attr_reader :dependencies
+      # @return [Array<Lock>]
+      attr_reader :locks
+      # @return [Boolean] whether the lock section had Foodchain's ETag lines
+      attr_reader :foodchain_locks
+
+      # @param project [Project]
+      # @return [Manifest]
+      def self.for(project)
+        new(File.join(project.game_dir, FILE))
+      end
+
+      # @param path [String] need not exist yet
+      # @raise [ManifestError] if the DSL is invalid
+      def initialize(path)
+        @path = path
+        content = File.file?(path) ? File.read(path) : ""
+        config, separator, locks = content.partition(SEPARATOR)
+        @config = config
+        @had_separator = !separator.empty?
+        @locks, @foodchain_locks = parse_locks(locks)
+        @dependencies = DSL.evaluate(config, path)
+      end
+
+      # @return [Boolean]
+      def exist?
+        File.file?(path)
+      end
+
+      # @param name [String] a dependency's name or key
+      # @return [Dependency, nil]
+      def find(name)
+        dependencies.find { |dependency| dependency.name == name || dependency.key == name }
+      end
+
+      # Rewrites the lock section, keeping everything above __END__ as is.
+      #
+      # @param locks [Array<Lock>]
+      # @return [void]
+      def write_locks(locks)
+        @locks = locks.sort_by(&:key)
+        body = [config.rstrip, "", "__END__", "", LOCK_HEADER, *@locks.map(&:to_line)].join("\n")
+        File.write(path, body.sub(/\A\n+/, "") + "\n")
+      end
+
+      # Appends a declaration to the DSL section and checks it parses.
+      #
+      # @param line [String]
+      # @return [void]
+      # @raise [ManifestError] (leaving the file unchanged) if it doesn't
+      def add(line)
+        update_config(config.rstrip.then { |c| c.empty? ? "#{line}\n" : "#{c}\n#{line}\n" })
+      end
+
+      # Deletes +dependency+'s declaration from the DSL section.
+      #
+      # @param dependency [Dependency]
+      # @return [void]
+      # @raise [ManifestError] if the declaration spans several lines
+      def remove(dependency)
+        lines = config.lines
+        index = dependency.line && dependency.line - 1
+        text = index && lines[index]
+        declares = text && DSL::METHODS.any? { |method| text.lstrip.start_with?("#{method} ", "#{method}(") }
+        continues = text&.rstrip&.end_with?(",", "\\", "(")
+        unless declares && !continues
+          raise ManifestError, "Can't remove #{dependency.name} automatically; edit #{FILE} by hand."
+        end
+
+        lines.delete_at(index)
+        update_config(lines.join)
+      end
+
+      private
+
+      # Validates before writing, so a bad edit leaves the file alone.
+      def update_config(new_config)
+        @dependencies = DSL.evaluate(new_config, path)
+        @config = new_config
+        write_locks(locks)
+      end
+
+      # Foodchain's two-column ETag lines can't be reused; they're dropped and
+      # the dependencies re-resolved.
+      def parse_locks(text)
+        lines = text.lines(chomp: true).reject { |line| line.strip.empty? || line.start_with?("#") }
+        locks = lines.filter_map { |line| Lock.parse(line) }
+        [locks, locks.size < lines.size]
+      end
+    end
+
+    # Evaluates the DSL section of +dependencies.rb+.
+    class DSL
+      METHODS = %w[github git url path].freeze
+
+      # @param source [String]
+      # @param file [String] for line numbers in errors
+      # @return [Array<Dependency>]
+      # @raise [ManifestError]
+      def self.evaluate(source, file)
+        dsl = new(file)
+        dsl.instance_eval(source, file, 1)
+        dsl.dependencies
+      rescue ManifestError
+        raise
+      rescue ScriptError, StandardError => e
+        location = e.backtrace_locations&.find { |l| l.path == file }&.lineno
+        raise ManifestError, "#{File.basename(file)}#{":#{location}" if location}: #{e.message}"
+      end
+
+      attr_reader :dependencies
+
+      def initialize(file)
+        @file = file
+        @dependencies = []
+      end
+
+      # Foodchain files start with `require "vendor/foodchain"`; requires
+      # don't mean anything to talon.
+      def require(*)
+        nil
+      end
+
+      # github "owner/repo", path: "lib", ref: "v1.0", as: "name"
+      # github :owner, :repo, "lib", ref: "v1.0", destination: "vendor/name"  (Foodchain)
+      def github(*args, path: nil, ref: nil, as: nil, destination: nil)
+        owner, repo, positional_path =
+          case args.size
+          when 1 then [*args.first.to_s.split("/", 2), nil]
+          when 2, 3 then args
+          else raise ArgumentError, "github expects \"owner/repo\" or owner, repo[, path]"
+          end
+        raise ArgumentError, "github needs \"owner/repo\"" if owner.to_s.empty? || repo.to_s.empty?
+
+        add(GitHubDependency, owner, repo, subpath: path || positional_path, ref: ref, as: as, destination: destination)
+      end
+
+      # git "https://host/repo.git", path: "lib", ref: "main", as: "name"
+      def git(url, path: nil, ref: nil, as: nil, destination: nil)
+        add(GitDependency, url, subpath: path, ref: ref, as: as, destination: destination)
+      end
+
+      # url "https://example.com/tween.rb", as: "tween.rb"
+      def url(url, as: nil, destination: nil)
+        add(URLDependency, url, as: as, destination: destination)
+      end
+
+      # path "../my_library/lib", as: "my_library"
+      def path(dir, as: nil, destination: nil)
+        add(PathDependency, dir, base: File.dirname(@file), as: as, destination: destination)
+      end
+
+      private
+
+      def caller_line
+        caller_locations.find { |location| location.path == @file }&.lineno
+      end
+
+      def add(klass, *args, as:, destination:, **options)
+        line = caller_line
+        dependency = begin
+          klass.new(*args, name: as&.to_s, destination: destination&.to_s, line: line, **options)
+        rescue ManifestError => e
+          raise ManifestError, "#{File.basename(@file)}:#{line}: #{e.message}"
+        end
+
+        [[:name, "name"], [:key, "source"], [:destination, "destination"]].each do |attribute, label|
+          clash = @dependencies.find { |other| other.public_send(attribute) == dependency.public_send(attribute) }
+          next unless clash
+
+          raise ManifestError, "#{File.basename(@file)}:#{line}: #{dependency.name} has the same #{label} " \
+            "as #{clash.name} (line #{clash.line}). Use as: to give one a different name."
+        end
+        @dependencies << dependency
+        dependency
+      end
+    end
+  end
+end

data/lib/dr_talon/deps/tree.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "digest"
+require "fileutils"
+require "rubygems/package"
+require "stringio"
+require "zlib"
+
+module DrTalon
+  module Deps
+    # File tree helpers: checksums of vendored files, copying a subpath out of
+    # a source tree, and unpacking tarballs.
+    module Tree
+      module_function
+
+      # A digest of a file or directory's contents and executable bits, so
+      # local edits to vendored files can be detected.
+      #
+      # @param path [String]
+      # @return [String, nil] "sha256:<hex>", or nil if +path+ doesn't exist
+      def checksum(path)
+        return nil unless File.exist?(path)
+        return "sha256:#{Digest::SHA256.file(path).hexdigest}" if File.file?(path)
+
+        digest = Digest::SHA256.new
+        Dir.glob("**/*", File::FNM_DOTMATCH, base: path).sort.each do |relative|
+          full = File.join(path, relative)
+          next unless File.file?(full)
+
+          digest << relative << "\0" << (File.executable?(full) ? "x" : "-") << Digest::SHA256.file(full).hexdigest << "\n"
+        end
+        "sha256:#{digest.hexdigest}"
+      end
+
+      # Copies +subpath+ of +root+ (a file or directory, or all of +root+ when
+      # empty) to +target+, skipping .git and symlinks.
+      #
+      # @return [void]
+      # @raise [FetchError] if +subpath+ doesn't exist
+      def copy_subpath(root, subpath, target)
+        source = subpath.to_s.empty? ? root : File.join(root, subpath)
+        raise FetchError, "#{subpath} doesn't exist in the dependency." unless File.exist?(source)
+
+        if File.file?(source)
+          FileUtils.mkdir_p(File.dirname(target))
+          FileUtils.cp(source, target, preserve: true)
+          return
+        end
+
+        Dir.glob("**/*", File::FNM_DOTMATCH, base: source).sort.each do |relative|
+          next if relative.split("/").include?(".git") || File.basename(relative).match?(/\A\.\.?\z/)
+
+          from = File.join(source, relative)
+          to = File.join(target, relative)
+          if File.symlink?(from)
+            next
+          elsif File.directory?(from)
+            FileUtils.mkdir_p(to)
+          else
+            FileUtils.mkdir_p(File.dirname(to))
+            FileUtils.cp(from, to, preserve: true)
+          end
+        end
+        FileUtils.mkdir_p(target)
+      end
+
+      # Unpacks a .tar.gz into +dir+, dropping the single top-level directory
+      # GitHub wraps archives in. Skips links and anything that would land
+      # outside +dir+.
+      #
+      # @param data [String] gzipped tar bytes
+      # @param dir [String]
+      # @return [void]
+      def untar(data, dir, strip: 1)
+        Zlib::GzipReader.wrap(StringIO.new(data)) do |gzip|
+          Gem::Package::TarReader.new(gzip) do |tar|
+            tar.each do |entry|
+              parts = entry.full_name.split("/").reject(&:empty?).drop(strip)
+              next if parts.empty? || parts.include?("..")
+
+              target = File.join(dir, *parts)
+              if entry.directory?
+                FileUtils.mkdir_p(target)
+              elsif entry.file?
+                FileUtils.mkdir_p(File.dirname(target))
+                File.binwrite(target, entry.read.to_s)
+                File.chmod(entry.header.mode & 0o755 | 0o600, target)
+              end
+            end
+          end
+        end
+      rescue Zlib::Error, Gem::Package::TarInvalidError => e
+        raise FetchError, "Couldn't unpack the archive: #{e.message}"
+      end
+    end
+  end
+end

data/lib/dr_talon/deps.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module DrTalon
+  # DragonRuby dependencies: declared in +dependencies.rb+ in the game
+  # directory, vendored into +vendor/+, locked below +__END__+.
+  module Deps
+    # Downloading or resolving a dependency failed.
+    class FetchError < Error; end
+
+    # +dependencies.rb+ is invalid.
+    class ManifestError < Error; end
+
+    # Vendored files were changed outside talon.
+    class ModifiedError < Error; end
+
+    # Parses a `talon add` source: github:owner/repo, git:URL, url:URL or
+    # path:DIR.
+    #
+    # @return [Array(Symbol, String)] the DSL method and its first argument
+    # @raise [Error]
+    def self.parse_source(source)
+      kind, value = source.to_s.split(":", 2)
+      if %w[github git url path].include?(kind) && !value.to_s.empty?
+        return [kind.to_sym, value] unless kind == "github" && !value.match?(%r{\A[\w.-]+/[\w.-]+\z})
+      end
+
+      raise Error, "Unknown source #{source.inspect}. Use github:owner/repo, git:URL, url:URL or path:DIR."
+    end
+
+    # A dependencies.rb line for `talon add`.
+    #
+    # @return [String]
+    def self.declaration(kind, value, path: nil, ref: nil, as: nil)
+      options = {path: path, ref: ref, as: as}.compact
+      options.delete(:path) if kind == :url || kind == :path
+      options.delete(:ref) if kind == :url || kind == :path
+      [%(#{kind} #{value.inspect}), *options.map { |key, val| "#{key}: #{val.inspect}" }].join(", ")
+    end
+
+    # The line to require a vendored dependency from game code.
+    #
+    # @param project [Project]
+    # @param dependency [Dependency]
+    # @return [String, nil]
+    def self.require_hint(project, dependency)
+      target = File.join(project.game_dir, dependency.destination)
+      return %(require "#{dependency.destination}") if File.file?(target)
+      return nil unless File.directory?(target)
+
+      base = dependency.name.delete_suffix(".rb").tr("-", "_")
+      entry = ["#{base}.rb", "lib/#{base}.rb", "main.rb"].find { |candidate| File.file?(File.join(target, candidate)) }
+      entry ||= Dir.glob("*.rb", base: target).min
+      entry && %(require "#{dependency.destination}/#{entry}")
+    end
+  end
+end
+
+require_relative "deps/git"
+require_relative "deps/tree"
+require_relative "deps/dependency"
+require_relative "deps/manifest"
+require_relative "deps/installer"

data/lib/dr_talon/doctor.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+module DrTalon
+  # Health checks for a project, reported by +talon doctor+.
+  class Doctor
+    # @!attribute [r] status
+    #   @return [Symbol] +:ok+, +:warning+ or +:error+
+    # @!attribute [r] message
+    #   @return [String]
+    Check = Data.define(:status, :message)
+
+    # Values DragonRuby ships in +game_metadata.txt+ that must be changed
+    # before publishing.
+    METADATA_PLACEHOLDERS = {
+      "devid" => "your_itchio_username",
+      "devtitle" => "Your Itch.io Display Name",
+      "gameid" => "your_itchio_game_id",
+      "gametitle" => "Your Game Title"
+    }.freeze
+
+    # Publishing fields in +game_metadata.txt+ that are missing, commented out
+    # (as DragonRuby ships them) or still DragonRuby's placeholder.
+    #
+    # @param project [Project]
+    # @return [Array<String>, nil] nil when there's no metadata file
+    def self.unset_metadata(project)
+      path = File.join(project.game_dir, "metadata", "game_metadata.txt")
+      return nil unless File.file?(path)
+
+      values = File.readlines(path, chomp: true).filter_map do |line|
+        line.strip.split("=", 2) if !line.lstrip.start_with?("#") && line.include?("=")
+      end.to_h
+
+      METADATA_PLACEHOLDERS.select { |key, placeholder| values[key].nil? || values[key] == placeholder }.keys
+    end
+
+    # @param project [Project]
+    # @param store [Engine::Store]
+    # @param host_platform [String]
+    def initialize(project, store, host_platform: Engine.host_platform)
+      @project = project
+      @store = store
+      @host_platform = host_platform
+      @materializer = Engine::Materializer.new(project)
+    end
+
+    # @return [Array<Check>]
+    def checks
+      @checks = []
+      check_game
+      check_engine
+      check_dependencies
+      check_metadata
+      @checks
+    end
+
+    private
+
+    def ok(message) = @checks << Check.new(status: :ok, message: message)
+
+    def warning(message) = @checks << Check.new(status: :warning, message: message)
+
+    def error(message) = @checks << Check.new(status: :error, message: message)
+
+    def check_game
+      layout = @project.layout
+      if layout
+        ok "Game found in #{(layout == :full) ? "mygame/" : "the project root"} (#{layout.to_s.tr("_", "-")} layout)"
+      else
+        error "No mygame/app/main.rb or app/main.rb found"
+      end
+    end
+
+    def check_engine
+      pin = begin
+        @project.pin
+      rescue Error => e
+        return error(e.message)
+      end
+      return error("No #{Project::PIN_FILE}. Pin an engine with `talon engine use VERSION`.") unless pin
+
+      expected = expected_engine(pin)
+      return unless expected
+
+      manifest = begin
+        @materializer.manifest
+      rescue Error => e
+        return error(e.message)
+      end
+
+      if manifest.nil?
+        error "#{expected.id} isn't installed in the project. Run `talon engine use`."
+      elsif manifest.engine != expected.id
+        error "The project has #{manifest.engine} installed but #{Project::PIN_FILE} pins #{pin}. Run `talon engine use`."
+      else
+        check_installed_files(manifest)
+      end
+    end
+
+    def expected_engine(pin)
+      spec = Engine::Spec.new(version: pin.version, tier: pin.tier, platform: @host_platform)
+      installation = @store.find(spec)
+      ok "#{Project::PIN_FILE} pins #{pin}; #{installation.id} is cached"
+      installation
+    rescue Engine::NotFound
+      error "#{Project::PIN_FILE} pins #{pin}, but no matching #{@host_platform} engine is cached. " \
+        "Import it with `talon engine import <zip>`."
+      nil
+    rescue Engine::Ambiguous => e
+      error e.message
+      nil
+    end
+
+    def check_installed_files(manifest)
+      missing = manifest.files.reject { |relative| File.exist?(@project.path(relative)) }
+      if missing.any?
+        count = (missing.size == 1) ? "1 engine file is" : "#{missing.size} engine files are"
+        return error("#{count} missing (e.g. #{missing.first}). Run `talon engine use`.")
+      end
+
+      binary = %w[dragonruby dragonruby.exe].map { |name| @project.path(name) }.find { |path| File.file?(path) }
+      if binary.nil?
+        error "No dragonruby binary in the project root"
+      elsif !File.executable?(binary)
+        error "#{File.basename(binary)} isn't executable"
+      else
+        ok "#{manifest.engine} is installed (#{manifest.files.size} files)"
+      end
+    end
+
+    def check_dependencies
+      manifest = Deps::Manifest.for(@project)
+      return unless manifest.exist?
+
+      count = manifest.dependencies.size
+      problems = Deps::Installer.new(@project).problems
+      problems.each do |entry|
+        dependency = entry[:dependency]
+        case entry[:problem]
+        when :unlocked then error "#{dependency.name} isn't installed or locked yet. Run `talon install`."
+        when :missing then error "#{dependency.name} is locked but #{dependency.destination} is missing. Run `talon install`."
+        when :modified then warning "#{dependency.destination} has local changes; `talon install --force` restores it"
+        end
+      end
+      ok "#{count} dependenc#{(count == 1) ? "y" : "ies"} installed" if problems.empty?
+    rescue Error => e
+      error e.message
+    end
+
+    def check_metadata
+      unset = self.class.unset_metadata(@project)
+      if unset.nil?
+        warning("No metadata/game_metadata.txt; it's needed to publish") if @project.layout == :full
+      elsif unset.empty?
+        ok "game_metadata.txt is filled in"
+      else
+        warning "game_metadata.txt doesn't set #{unset.join(", ")} yet (needed to publish)"
+      end
+    end
+  end
+end