braid 1.1.6 → 1.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4ecb4234a451a2abc3ce39492543d198319a5aefe034caf7cbf377a3994aa463
-  data.tar.gz: 716777da7ce4fb5b72213838390d009b5046b0331ffdfbb8dea32fe3267e312d
+  metadata.gz: ad14f6dd7a5d428c5796bbd19039aae6e59f5803d93da3889fe0a92a8afd032b
+  data.tar.gz: 9d6bcfd73c5a306f853e6b9653edda5aff6a7bbd3541b6ab644bd7b96bc510e6
 SHA512:
-  metadata.gz: 52664d57908b3758ff9ae3807727435e74267dda1a66d442ea19316c5f9b2e5b33ab475f6eb73765924a1a6eb0b220b4fe11e7ba18fd5d03c5bfb88e2b5bfec2
-  data.tar.gz: 23b66af4bc7bd0db3e94449c6342439897f5fc38fd8d0f6c5661a2cbe1c0de0b97ef43b6caf501954eb1ee5b80c306b466d7ea61f0d4a4cd268116b8aad65802
+  metadata.gz: 817cd08525921352f103a81f05b6c550e8eaff62fb647c04d0ecb746e6ed425a78ef1bea4a477786675c406b0e23982f36a52eea205278a3b25ccee6e64ecdf5
+  data.tar.gz: 76d9e62b1d58a437a8eae77f879b5a66ec6a30cda270d267cc458e621a3f1560fa192f5cc435b5e718c9f093691464d458b049d2e236864d0faea6e801c89629

data/exe/braid

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+
+# I haven't found a clean way to get Sorbet to check this file since the name
+# doesn't end in `.rb`.  (If I add `--file bin/braid` to `sorbet/config`, then
+# the Sorbet language server doesn't support using Watchman.)  So move all the
+# interesting code to `lib/braid/main.rb` and leave this as a launcher that
+# doesn't have any code worth type checking. ~ Matt 2022-04-02
+
+require_relative '../lib/braid/check_gem'
+
+require 'braid/main'

data/lib/braid/check_gem.rb

@@ -0,0 +1,58 @@
+# Braid has several entry points that run code from Ruby gems (either Braid
+# itself or dependencies such as Sorbet) and expect to get the correct versions
+# (either the same copy of Braid or versions of dependencies consistent with the
+# gemspec or Gemfile, as applicable).  This currently applies to the following
+# entry points:
+#
+# - The Braid CLI launcher: `exe/braid`
+# - The Braid test suite under `spec`
+# - The Rakefile: Has a target to run the Sorbet type checker and wants the
+#   correct version for the current version of Braid.
+#
+# If these entry points are invoked without first activating the correct gems,
+# then other globally installed versions might be used by default, leading to
+# unintended behavior.  So we have each of these entry points check that a Braid
+# gem is active in the current Ruby interpreter _and_ the entry point is part of
+# that same Braid gem.  If so, we can assume that the correct versions of
+# dependencies are active as well.
+#
+# To implement the check, the entry point file loads its corresponding copy of
+# check_gem.rb via `require_relative`, and that copy of check_gem.rb checks that
+# it is part of the active Braid gem.  Note that loading check_gem.rb via
+# `require 'lib/braid/check_gem'` would defeat the purpose, since it would
+# activate whatever Braid gem is visible and then check that that gem's copy of
+# check_gem.rb is part of the active Braid gem (which it would always be), not
+# whether the _caller_ is part of the active Braid gem.
+#
+# Common means of activating the correct gems before invoking an entry point
+# include:
+#
+# - Bundler: Used when developing Braid itself and possibly by some projects
+#   that use Braid.  It modifies the environment so that every Ruby subprocess
+#   activates the gems from the Gemfile.lock.
+# - A wrapper for `exe/braid` generated by `gem install --wrappers`.
+#
+# Note that we don't have every `.rb` file that is part of Braid load
+# check_gem.rb: that would be too invasive and only helps in the case where a
+# user manually added Braid's `lib` dir to the load path, which is a mistake
+# that a reasonable user is much less likely to make than just running an entry
+# point without the proper setup.
+#
+# TODO: Is there a more standard way to do this check?  One would think it would
+# be potentially applicable to any Ruby project, though maybe most don't care as
+# much as we do about catching the problem up front.
+
+braid_spec = Gem.loaded_specs['braid']
+if braid_spec.nil? || __FILE__ != braid_spec.gem_dir + '/lib/braid/check_gem.rb'
+  STDERR.puts <<-MSG
+Error: The RubyGems environment is not set up correctly for Braid.
+- If you're using a copy of Braid installed globally via 'gem install' or
+  similar, use the 'braid' wrapper script (which is typically installed at a
+  location like ~/.gem/ruby/bin/braid depending on your environment) instead of
+  running 'exe/braid' directly.
+- If you're using a copy of Braid managed by Bundler (including when developing
+  Braid itself), prepend 'bundle exec' to your command or use a binstub
+  generated by 'bundle binstubs'.
+MSG
+  exit(1)
+end

data/lib/braid/command.rb

@@ -1,5 +1,8 @@
+# typed: true
 module Braid
   class Command
+    extend T::Sig
+
     class InvalidRevision < BraidError
     end
 
@@ -23,10 +26,12 @@ module Braid
       exit(1)
     end
 
+    sig {params(str: String).void}
     def self.msg(str)
       puts "Braid: #{str}"
     end
 
+    sig {params(str: String).void}
     def msg(str)
       self.class.msg(str)
     end
@@ -35,16 +40,19 @@ module Braid
       @config ||= Config.new({'mode' => config_mode})
     end
 
+    sig {returns(T::Boolean)}
     def verbose?
       Braid.verbose
     end
 
+    sig {returns(T::Boolean)}
     def force?
       Braid.force
     end
 
     private
 
+    sig {returns(Config::ConfigMode)}
     def config_mode
       Config::MODE_MAY_WRITE
     end
@@ -63,14 +71,17 @@ module Braid
       git.remote_rm(mirror.remote) unless options['keep']
     end
 
+    sig {returns(T::Boolean)}
     def use_local_cache?
       Braid.use_local_cache
     end
 
+    sig {void}
     def self.verify_git_version!
       git.require_version!(REQUIRED_GIT_VERSION)
     end
 
+    sig {void}
     def self.check_working_dir!
       # If we aren't in a git repository at all, git.is_inside_worktree will
       # propagate a "fatal: Not a git repository" ShellException.
@@ -82,6 +93,7 @@ module Braid
       end
     end
 
+    sig {void}
     def bail_on_local_changes!
       git.ensure_clean!
     end
@@ -100,6 +112,7 @@ module Braid
       end
     end
 
+    sig {void}
     def add_config_file
       git.rm(OLD_CONFIG_FILE) if File.exist?(OLD_CONFIG_FILE)
       git.add(CONFIG_FILE)

data/lib/braid/commands/diff.rb

@@ -35,7 +35,7 @@ module Braid
 
         # XXX: Warn if the user specifies file paths that are outside the
         # mirror?  Currently, they just won't match anything.
-        git.diff_to_stdout(*mirror.diff_args(*options['git_diff_args']))
+        git.diff_to_stdout(*mirror.diff_args(options['git_diff_args']))
 
         clear_remote(mirror, options)
       end

data/lib/braid/config.rb

@@ -1,3 +1,4 @@
+# typed: true
 require 'yaml'
 require 'json'
 require 'yaml/store'
@@ -48,6 +49,10 @@ require 'yaml/store'
 
 module Braid
   class Config
+    extend T::Sig
+
+    # TODO (typing): Migrate to T::Enum?
+    ConfigMode = T.type_alias { Integer }
 
     MODE_UPGRADE = 1
     MODE_READ_ONLY = 2
@@ -56,11 +61,13 @@ module Braid
     CURRENT_CONFIG_VERSION = 1
 
     class PathAlreadyInUse < BraidError
+      sig {returns(String)}
       def message
         "path already in use: #{super}"
       end
     end
     class MirrorDoesNotExist < BraidError
+      sig {returns(String)}
       def message
         "mirror does not exist: #{super}"
       end
@@ -70,9 +77,15 @@ module Braid
     end
 
     # For upgrade-config command only.  XXX: Ideally would be immutable.
-    attr_reader :config_version, :config_existed, :breaking_change_descs
+    sig {returns(Integer)}
+    attr_reader :config_version
+    sig {returns(T::Boolean)}
+    attr_reader :config_existed
+    sig {returns(T::Array[String])}
+    attr_reader :breaking_change_descs
 
     # options: config_file, old_config_files, mode
+    sig {params(options: T.untyped).void}
     def initialize(options = {})
       @config_file     = options['config_file']      || CONFIG_FILE
       old_config_files = options['old_config_files'] || [OLD_CONFIG_FILE]
@@ -150,6 +163,7 @@ MSG
 
     end
 
+    sig {params(url: String, options: T.untyped).returns(Mirror)}
     def add_from_options(url, options)
       mirror = Mirror.new_from_options(url, options)
 
@@ -157,33 +171,39 @@ MSG
       mirror
     end
 
+    sig {returns(T::Array[Mirror])}
     def mirrors
       @db.keys
     end
 
+    sig {params(path: String).returns(T.nilable(Mirror))}
     def get(path)
       key = path.to_s.sub(/\/$/, '')
       attributes = @db[key]
       attributes ? Mirror.new(path, attributes) : nil
     end
 
+    sig {params(path: String).returns(Mirror)}
     def get!(path)
       mirror = get(path)
       raise MirrorDoesNotExist, path unless mirror
       mirror
     end
 
+    sig {params(mirror: Mirror).void}
     def add(mirror)
       raise PathAlreadyInUse, mirror.path if get(mirror.path)
       write_mirror(mirror)
       write_db
     end
 
+    sig {params(mirror: Mirror).void}
     def remove(mirror)
       @db.delete(mirror.path)
       write_db
     end
 
+    sig {params(mirror: Mirror).void}
     def update(mirror)
       raise MirrorDoesNotExist, mirror.path unless get(mirror.path)
       write_mirror(mirror)
@@ -191,6 +211,7 @@ MSG
     end
 
     # Public for upgrade-config command only.
+    sig {void}
     def write_db
       new_db = {}
       @db.keys.sort.each do |key|
@@ -211,11 +232,12 @@ MSG
 
     private
 
+    sig {params(config_file: String, old_config_files: T::Array[String]).returns(T.untyped)}
     def load_config(config_file, old_config_files)
       (old_config_files + [config_file]).each do |file|
         next unless File.exist?(file)
         begin
-          store = YAML::Store.new(file)
+          store = T.let(YAML::Store, T.untyped).new(file)
           data = {}
           store.transaction(true) do
             store.roots.each do |path|
@@ -228,15 +250,17 @@ MSG
           return data if data
         end
       end
-      return nil
+      nil
     end
 
+    sig {params(mirror: Mirror).void}
     def write_mirror(mirror)
       @db[mirror.path] = clean_attributes(mirror.attributes)
     end
 
+    sig {params(hash: T::Hash[String, T.untyped]).returns(T::Hash[String, T.untyped])}
     def clean_attributes(hash)
-      hash.reject { |k, v| v.nil? }
+      hash.reject { |_, v| v.nil? }
     end
   end
 end

data/{bin/braid → lib/braid/main.rb}

@@ -1,18 +1,3 @@
-#!/usr/bin/env ruby
-
-# Duplicated from Braid::Command.run. :(
-def die(msg)
-  puts "Braid: Error: #{msg}"
-  exit(1)
-end
-
-# If we assume Ruby >= 2.0, we can use __dir__.
-libdir = File.expand_path(File.dirname(File.realpath(__FILE__)) + '/../lib')
-unless File.exists?(libdir)
-  # Don't silently fall back to a different globally installed copy of Braid!
-  die "Cannot find Braid's 'lib' directory."
-end
-$LOAD_PATH.unshift(libdir)
 require 'braid'
 
 require 'rubygems'
@@ -138,7 +123,7 @@ Main {
 
     mixin :optional_local_path, :option_verbose, :option_keep_remote
 
-    synopsis (Main::Usage.default_synopsis(self) + ' [-- git_diff_arg*]')
+    synopsis(Main::Usage.default_synopsis(self) + ' [-- git_diff_arg*]')
 
     run {
       if @argv.length > 0 && @argv[0] == '--'

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,6 +79,7 @@ DESC
       @attributes.delete('squashed')
     end
 
+    sig {params(url: String, options: T.untyped).returns(Mirror)}
     def self.new_from_options(url, options = {})
       url    = url.sub(/\/$/, '')
 
@@ -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

@@ -61,7 +61,7 @@ module Braid
 
       # hax!
       def version
-        status, out, err = exec!("#{self.class.command} --version")
+        _, out, _ = exec!("#{self.class.command} --version")
         out.sub(/^.* version/, '').strip.sub(/ .*$/, '').strip
       end
 
@@ -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}")
@@ -303,7 +304,7 @@ module Braid
           # According to
           # https://lore.kernel.org/git/e48a281a4d3db0a04c0609fcb8658e4fcc797210.1646166271.git.gitgitgadget@gmail.com/,
           # `--prefix=` is valid if the path is empty.
-          res = invoke(:read_tree, "--prefix=#{path}", update_worktree ? '-u' : '-i', item)
+          invoke(:read_tree, "--prefix=#{path}", update_worktree ? '-u' : '-i', item)
         end
       end
 
@@ -370,7 +371,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
 
@@ -383,7 +384,7 @@ module Braid
       end
 
       def branch
-        status, out, err = exec!("git branch | grep '*'")
+        _, out, _ = exec!("git branch | grep '*'")
         out[2..-1]
       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]