braid 1.1.5 → 1.1.8

data/lib/braid/mirror.rb

@@ -1,21 +1,27 @@
+# typed: strict
 module Braid
   class Mirror
+    extend T::Sig
+
     # Since Braid 1.1.0, the attributes are written to .braids.json in this
     # canonical order.  For now, the order is chosen to match what Braid 1.0.22
     # produced for newly added mirrors.
-    ATTRIBUTES = %w(url branch path tag revision)
+    ATTRIBUTES = T.let(%w(url branch path tag revision), T::Array[String])
 
     class UnknownType < BraidError
+      sig {returns(String)}
       def message
         "unknown type: #{super}"
       end
     end
     class PathRequired < BraidError
+      sig {returns(String)}
       def message
         'path is required'
       end
     end
     class NoTagAndBranch < BraidError
+      sig {returns(String)}
       def message
         'can not specify both tag and branch configuration'
       end
@@ -23,11 +29,19 @@ module Braid
 
     include Operations::VersionControl
 
-    attr_reader :path, :attributes
+    sig {returns(String)}
+    attr_reader :path
+
+    # It's going to take significant refactoring to be able to give this a type.
+    sig {returns(T::Hash[String, T.untyped])}
+    attr_reader :attributes
+
+    BreakingChangeCallback = T.type_alias { T.proc.params(arg0: String).void }
 
+    sig {params(path: String, attributes: T::Hash[String, T.untyped], breaking_change_cb: BreakingChangeCallback).void}
     def initialize(path, attributes = {}, breaking_change_cb = DUMMY_BREAKING_CHANGE_CB)
-      @path       = path.sub(/\/$/, '')
-      @attributes = attributes.dup
+      @path       = T.let(path.sub(/\/$/, ''), String)
+      @attributes = T.let(attributes.dup, T::Hash[String, T.untyped])
 
       # Not that it's terribly important to check for such an old feature.  This
       # is mainly to demonstrate the RemoveMirrorDueToBreakingChange mechanism
@@ -65,13 +79,14 @@ DESC
       @attributes.delete('squashed')
     end
 
+    sig {params(url: String, options: T.untyped).returns(Mirror)}
     def self.new_from_options(url, options = {})
       url    = url.sub(/\/$/, '')
 
       raise NoTagAndBranch if options['tag'] && options['branch']
 
       tag = options['tag']
-      branch = options['branch'] || (tag.nil? ? 'master' : nil)
+      branch = options['branch']
 
       path = (options['path'] || extract_path_from_url(url, options['remote_path'])).sub(/\/$/, '')
       raise PathRequired unless path
@@ -82,14 +97,17 @@ DESC
       self.new(path, attributes)
     end
 
+    sig {params(comparison: Mirror).returns(T::Boolean)}
     def ==(comparison)
       path == comparison.path && attributes == comparison.attributes
     end
 
+    sig {returns(T::Boolean)}
     def locked?
       branch.nil? && tag.nil?
     end
 
+    sig {params(commit: String).returns(T::Boolean)}
     def merged?(commit)
       # tip from spearce in #git:
       # `test z$(git merge-base A B) = z$(git rev-parse --verify A)`
@@ -97,6 +115,9 @@ DESC
       !!base_revision && git.merge_base(commit, base_revision) == commit
     end
 
+    # We'll probably call the return type something like
+    # Braid::Operations::Git::TreeItem.
+    sig {params(revision: String).returns(T.untyped)}
     def upstream_item_for_revision(revision)
       git.get_tree_item(revision, self.remote_path)
     end
@@ -106,6 +127,7 @@ DESC
     # user-specified arguments.  Having the caller run "git diff" is convenient
     # for now but violates encapsulation a little; we may have to reorganize the
     # code in order to add features.
+    sig {params(user_args: T::Array[String]).returns(T::Array[String])}
     def diff_args(user_args = [])
       upstream_item = upstream_item_for_revision(base_revision)
 
@@ -139,7 +161,7 @@ DESC
         # before we add the basenames.
         return [
           '--relative=' + path,
-          '--src-prefix=a/' + File.basename(remote_path),
+          '--src-prefix=a/' + File.basename(T.must(remote_path)),
           '--dst-prefix=b/' + File.basename(path),
           base_tree,
           # user_args may contain options, which must come before paths.
@@ -156,6 +178,7 @@ DESC
     end
 
     # Precondition: the remote for this mirror is set up.
+    sig {returns(String)}
     def diff
       fetch_base_revision_if_missing
       git.diff(diff_args)
@@ -166,6 +189,7 @@ DESC
     # (https://github.com/cristibalan/braid/issues/71).  Mitigate this for
     # `braid diff` and other commands that need the diff by skipping the fetch
     # if the base revision is already present in the repository.
+    sig {void}
     def fetch_base_revision_if_missing
       begin
         # Without ^{commit}, this will happily pass back an object hash even if
@@ -176,74 +200,133 @@ DESC
       end
     end
 
+    sig {void}
     def fetch
       git_cache.fetch(url) if cached?
       git.fetch(remote)
     end
 
+    sig {returns(T::Boolean)}
     def cached?
       git.remote_url(remote) == cached_url
     end
 
+    sig {returns(String)}
     def base_revision
-      if revision
+      # Avoid a Sorbet "unreachable code" error.
+      # TODO (typing): Is the revision expected to be non-nil nowadays?  Can we
+      # just remove the `inferred_revision` code path now?
+      nilable_revision = T.let(revision, T.nilable(String))
+      if nilable_revision
         git.rev_parse(revision)
       else
         inferred_revision
       end
     end
 
+    sig {returns(String)}
     def local_ref
       return "#{self.remote}/#{self.branch}" unless self.branch.nil?
       return "tags/#{self.tag}" unless self.tag.nil?
-      self.revision
+      # TODO (typing): Remove this `T.must` if we make `revision` non-nilable.
+      T.must(self.revision)
     end
 
+    # FIXME: The return value is bogus if this mirror has neither a branch nor a
+    # tag.  It looks like this leads to a real bug affecting `braid push` when
+    # `--branch` is specified.  File the bug or just fix it.
+    sig {returns(String)}
     def remote_ref
       self.branch.nil? ? "+refs/tags/#{self.tag}" : "+refs/heads/#{self.branch}"
     end
 
+    # Accessors for all the attributes listed in `ATTRIBUTES` and stored in
+    # `self.attributes`.  Most of the accessors use the same names as the
+    # underlying attributes.  The exception is the `path` attribute, whose
+    # accessor is named `remote_path` to avoid a conflict with the `path`
+    # accessor for the local path.
+    #
+    # TODO: Can we reduce this boilerplate and still type the accessors
+    # statically?  If we move the config attributes to instance variables of the
+    # Mirror object, then we can use `attr_accessor`, but we'd have to somehow
+    # accommodate existing call sites that access `self.attributes` as a whole.
+
+    sig {returns(String)}
+    def url
+      self.attributes['url']
+    end
+
+    sig {params(new_value: String).void}
+    def url=(new_value)
+      self.attributes['url'] = new_value
+    end
+
+    sig {returns(T.nilable(String))}
+    def branch
+      self.attributes['branch']
+    end
+
+    sig {params(new_value: T.nilable(String)).void}
+    def branch=(new_value)
+      self.attributes['branch'] = new_value
+    end
+
+    sig {returns(T.nilable(String))}
     def remote_path
       self.attributes['path']
     end
 
+    sig {params(remote_path: T.nilable(String)).void}
     def remote_path=(remote_path)
       self.attributes['path'] = remote_path
     end
 
+    sig {returns(T.nilable(String))}
+    def tag
+      self.attributes['tag']
+    end
+
+    sig {params(new_value: T.nilable(String)).void}
+    def tag=(new_value)
+      self.attributes['tag'] = new_value
+    end
+
+    # The revision may be nil in the middle of `braid add`.
+    # TODO (typing): Look into restructuring `braid add` to avoid this?
+    sig {returns(T.nilable(String))}
+    def revision
+      self.attributes['revision']
+    end
+
+    sig {params(new_value: String).void}
+    def revision=(new_value)
+      self.attributes['revision'] = new_value
+    end
+
+    sig {returns(String)}
     def cached_url
       git_cache.path(url)
     end
 
+    sig {returns(String)}
     def remote
       "#{branch || tag || 'revision'}/braid/#{path}".gsub(/\/\./, '/_')
     end
 
     private
 
-    DUMMY_BREAKING_CHANGE_CB = lambda { |desc|
+    DUMMY_BREAKING_CHANGE_CB = T.let(lambda { |desc|
       raise InternalError, 'Instantiated a mirror using an unsupported ' +
         'feature outside of configuration loading.'
-    }
-
-    def method_missing(name, *args)
-      if ATTRIBUTES.find { |attribute| name.to_s =~ /^(#{attribute})(=)?$/ }
-        if $2
-          attributes[$1] = args[0]
-        else
-          attributes[$1]
-        end
-      else
-        raise NameError, "unknown attribute `#{name}'"
-      end
-    end
+    }, BreakingChangeCallback)
 
+    sig {returns(T.nilable(String))}
     def inferred_revision
       local_commits = git.rev_list('HEAD', "-- #{path}").split("\n")
       remote_hashes = git.rev_list("--pretty=format:\"%T\"", remote).split('commit ').map do |chunk|
         chunk.split("\n", 2).map { |value| value.strip }
       end
-      hash          = nil
+      hash          = T.let(nil, T.nilable(String))
       local_commits.each do |local_commit|
         local_tree = git.tree_hash(path, local_commit)
         match = remote_hashes.find { |_, remote_tree| local_tree == remote_tree }
@@ -255,12 +338,16 @@ DESC
       hash
     end
 
+    # TODO (typing): Return should not be nilable
+    sig {params(url: String, remote_path: T.nilable(String)).returns(T.nilable(String))}
     def self.extract_path_from_url(url, remote_path)
       if remote_path
         return File.basename(remote_path)
       end
 
-      return nil unless url
+      # Avoid a Sorbet "unreachable code" error.
+      # TODO (typing): Fix this properly.  Probably just remove this line?
+      return nil unless T.let(url, T.nilable(String))
       name = File.basename(url)
 
       if File.extname(name) == '.git'

data/lib/braid/operations.rb

@@ -1,3 +1,5 @@
+# typed: true
+
 require 'singleton'
 require 'rubygems'
 require 'tempfile'
@@ -56,12 +58,12 @@ module Braid
       include Singleton
 
       def self.command;
-        name.split('::').last.downcase;
+        T.unsafe(name).split('::').last.downcase;
       end
 
       # hax!
       def version
-        status, out, err = exec!("#{self.class.command} --version")
+        _, out, _ = exec!("#{self.class.command} --version")
         out.sub(/^.* version/, '').strip.sub(/ .*$/, '').strip
       end
 
@@ -89,6 +91,9 @@ module Braid
       end
 
       def method_missing(name, *args)
+        # We have to use this rather than `T.unsafe` because `invoke` is
+        # private.  See https://sorbet.org/docs/type-assertions#tbind.
+        T.bind(self, T.untyped)
         invoke(name, *args)
       end
 
@@ -138,12 +143,7 @@ module Braid
       # 'MERGE_MSG'), taking into account worktree configuration.  The returned
       # path may be absolute or relative to the current working directory.
       def repo_file_path(path)
-        if require_version('2.5')  # support for --git-path
-          invoke(:rev_parse, '--git-path', path)
-        else
-          # Git < 2.5 doesn't support linked worktrees anyway.
-          File.join(invoke(:rev_parse, '--git-dir'), path)
-        end
+        invoke(:rev_parse, '--git-path', path)
       end
 
       # If the current directory is not inside a git repository at all, this
@@ -166,6 +166,7 @@ module Braid
 
       def commit(message, *args)
         cmd = 'git commit --no-verify'
+        message_file = nil
         if message # allow nil
           message_file = Tempfile.new('braid_commit')
           message_file.print("Braid: #{message}")
@@ -272,7 +273,7 @@ module Braid
         if path.nil? || path == ''
           tree
         else
-          m = /^([^ ]*) ([^ ]*) ([^\t]*)\t.*$/.match(invoke(:ls_tree, tree, path))
+          m = T.must(/^([^ ]*) ([^ ]*) ([^\t]*)\t.*$/.match(invoke(:ls_tree, tree, path)))
           mode = m[1]
           type = m[2]
           hash = m[3]
@@ -292,16 +293,16 @@ module Braid
       # file).
       def add_item_to_index(item, path, update_worktree)
         if item.is_a?(BlobWithMode)
-          # Our minimum git version is 1.6.0 and the new --cacheinfo syntax
-          # wasn't added until 2.0.0.
-          invoke(:update_index, '--add', '--cacheinfo', item.mode, item.hash, path)
+          invoke(:update_index, '--add', '--cacheinfo', "#{item.mode},#{item.hash},#{path}")
           if update_worktree
             # XXX If this fails, we've already updated the index.
             invoke(:checkout_index, path)
           end
         else
-          # Yes, if path == '', "git read-tree --prefix=/" works. :/
-          invoke(:read_tree, "--prefix=#{path}/", update_worktree ? '-u' : '-i', item)
+          # According to
+          # https://lore.kernel.org/git/e48a281a4d3db0a04c0609fcb8658e4fcc797210.1646166271.git.gitgitgadget@gmail.com/,
+          # `--prefix=` is valid if the path is empty.
+          invoke(:read_tree, "--prefix=#{path}", update_worktree ? '-u' : '-i', item)
         end
       end
 
@@ -368,7 +369,7 @@ module Braid
       end
 
       def status_clean?
-        status, out, err = exec('git status')
+        _, out, _ = exec('git status')
         !out.split("\n").grep(/nothing to commit/).empty?
       end
 
@@ -381,12 +382,13 @@ module Braid
       end
 
       def branch
-        status, out, err = exec!("git branch | grep '*'")
+        _, out, _ = exec!("git branch | grep '*'")
         out[2..-1]
       end
 
       def clone(*args)
         # overrides builtin
+        T.bind(self, T.untyped)  # Ditto the comment in `method_missing`.
         invoke(:clone, *args)
       end
 
@@ -404,11 +406,11 @@ module Braid
         dir = path(url)
 
         # remove local cache if it was created with --no-checkout
-        if File.exists?("#{dir}/.git")
+        if File.exist?("#{dir}/.git")
           FileUtils.rm_r(dir)
         end
 
-        if File.exists?(dir)
+        if File.exist?(dir)
           Dir.chdir(dir) do
             git.fetch
           end

data/lib/braid/operations_lite.rb

@@ -1,9 +1,27 @@
+# typed: strict
+
+require 'braid/sorbet/setup'
+
 # One helper that is shared with the integration test harness and has no
 # dependencies on the rest of Braid.
 module Braid
   module Operations
+    extend T::Sig
+
     # Want to use https://github.com/thoughtbot/climate_control ?
-    def self.with_modified_environment(dict)
+    #
+    # We have to declare the `&blk` parameter in order to reference it in the
+    # type annotation, even though the body doesn't use it.  This causes the
+    # block to be converted to a proc at runtime, which has some performance
+    # cost (probably not important in the context of Braid).  TODO: Find a way
+    # to avoid the performance cost?  File a Sorbet enhancement request?
+    sig {
+      type_parameters(:R).params(
+        dict: T::Hash[String, String],
+        blk: T.proc.returns(T.type_parameter(:R))
+      ).returns(T.type_parameter(:R))
+    }
+    def self.with_modified_environment(dict, &blk)
       orig_dict = {}
       dict.each { |name, value|
         orig_dict[name] = ENV[name]

data/lib/braid/sorbet/fake_runtime.rb

@@ -0,0 +1,75 @@
+# typed: ignore
+
+# This file contains a fake implementation of the subset of `sorbet-runtime`
+# used by Braid that performs no runtime checks.  See the "Type checking"
+# section of development.md for background.
+
+require 'singleton'
+
+# Create our fake module at `Braid::T` so that if someone loads Braid into the
+# same Ruby interpreter as other code that needs the real sorbet-runtime, we
+# don't break the other code.  (We don't officially support loading Braid as a
+# library, but we may as well go ahead and put this infrastructure in place.)
+# Code in the `Braid` module still uses normal references to `T`, so the Sorbet
+# static analyzer (which doesn't read this file) doesn't see anything out of the
+# ordinary, but those references resolve to `Braid::T` at runtime according to
+# Ruby's constant lookup rules.
+module Braid
+  module T
+
+    module Sig
+      def sig; end
+    end
+    def self.let(value, type)
+      value
+    end
+
+    # NOTICE: Like everything else in the fake Sorbet runtime (e.g., `sig`),
+    # these do not actually perform runtime checks.  Currently, if you want a
+    # runtime check, you have to implement it yourself.  We considered defining
+    # wrapper functions with different names to make this clearer, but then we'd
+    # lose the extra static checks that Sorbet performs on direct calls to
+    # `T.cast` and `T.must`.
+    def self.cast(value, type)
+      value
+    end
+    def self.must(value)
+      value
+    end
+    def self.unsafe(value)
+      value
+    end
+    def self.bind(value, type); end
+
+    class FakeType
+      include Singleton
+    end
+    FAKE_TYPE = FakeType.instance
+
+    def self.type_alias
+      FAKE_TYPE
+    end
+
+    def self.nilable(type)
+      FAKE_TYPE
+    end
+    def self.untyped
+      FAKE_TYPE
+    end
+    def self.noreturn
+      FAKE_TYPE
+    end
+    Boolean = FAKE_TYPE
+    module Array
+      def self.[](type)
+        FAKE_TYPE
+      end
+    end
+    module Hash
+      def self.[](key_type, value_type)
+        FAKE_TYPE
+      end
+    end
+
+  end
+end

data/lib/braid/sorbet/setup.rb

@@ -0,0 +1,18 @@
+# typed: strict
+
+# Code to set up the Sorbet runtime and Sorbet-related utilities used throughout
+# the Braid code.  Called by `lib/braid.rb` and `lib/braid/operations_lite.rb`
+# before any other Braid code is loaded.
+
+env_use_sorbet_runtime = ENV['BRAID_USE_SORBET_RUNTIME']
+if env_use_sorbet_runtime == '1'
+  require 'sorbet-runtime'
+elsif [nil, '0'].include?(env_use_sorbet_runtime)
+  require 'braid/sorbet/fake_runtime'
+else
+  puts <<-MSG
+Braid: Error: BRAID_USE_SORBET_RUNTIME environment variable has invalid
+value #{env_use_sorbet_runtime.inspect}; it must be "1", "0", or unset.
+MSG
+  exit(1)
+end

data/lib/braid/version.rb

@@ -1,3 +1,6 @@
+# Ditto the comment in `check_gem.rb` regarding the `typed` sigil.
+# typed: false
+
 module Braid
-  VERSION = '1.1.5'.freeze
+  VERSION = '1.1.8'.freeze
 end

data/lib/braid.rb

@@ -1,46 +1,65 @@
+# typed: strict
+
+require 'braid/sorbet/setup'
 require 'braid/version'
 
 module Braid
+  extend T::Sig
+
   OLD_CONFIG_FILE      = '.braids'
   CONFIG_FILE          = '.braids.json'
 
   # See the background in the "Supported environments" section of README.md.
   #
   # The newest Git feature that Braid is currently known to rely on is
-  # `receive.denyCurrentBranch = updateInstead` (in
-  # spec/integration/push_spec.rb), which was added in Git 2.3.0 (in 2015).  It
+  # `git ls-remote --symref`, which was added in Git 2.8.0 (in 2016).  It
   # doesn't seem worth even a small amount of work to remove that dependency and
   # support even older versions of Git.  So set that as the declared requirement
   # for now.  In general, a reasonable approach might be to try to support the
   # oldest version of Git in current "long-term support" versions of popular OS
   # distributions.
-  REQUIRED_GIT_VERSION = '2.3.0'
+  REQUIRED_GIT_VERSION = '2.8.0'
 
+  @verbose = T.let(false, T::Boolean)
+
+  sig {returns(T::Boolean)}
   def self.verbose
     !!@verbose
   end
 
+  # TODO (typing): One would think `new_value` shouldn't be nilable, but
+  # apparently `lib/braid/main.rb` passes nil sometimes. Is that easy to fix?
+  # (Ditto with `self.force=` below.)
+  sig {params(new_value: T.nilable(T::Boolean)).void}
   def self.verbose=(new_value)
     @verbose = !!new_value
   end
 
+  @force = T.let(false, T::Boolean)
+
+  sig {returns(T::Boolean)}
   def self.force
     !!@force
   end
 
+  sig {params(new_value: T.nilable(T::Boolean)).void}
   def self.force=(new_value)
     @force = !!new_value
   end
 
+  sig {returns(T::Boolean)}
   def self.use_local_cache
     [nil, 'true', '1'].include?(ENV['BRAID_USE_LOCAL_CACHE'])
   end
 
+  sig {returns(String)}
   def self.local_cache_dir
     File.expand_path(ENV['BRAID_LOCAL_CACHE_DIR'] || "#{ENV['HOME']}/.braid/cache")
   end
 
   class BraidError < StandardError
+    extend T::Sig
+    sig {returns(String)}
     def message
       value = super
       value if value != self.class.name
@@ -48,6 +67,7 @@ module Braid
   end
 
   class InternalError < BraidError
+    sig {returns(String)}
     def message
       "internal error: #{super}"
     end