braid 1.1.8 → 1.1.10

data/lib/braid/commands/upgrade_config.rb

@@ -1,12 +1,26 @@
-# typed: true
+# typed: strict
 module Braid
   module Commands
     class UpgradeConfig < Command
+      class Options < T::Struct
+        prop :dry_run, T::Boolean
+        prop :allow_breaking_changes, T::Boolean
+      end
+
+      sig {params(options: Options).void}
+      def initialize(options)
+        @options = options
+      end
+
+      private
+
+      sig {returns(Config::ConfigMode)}
       def config_mode
         Config::MODE_UPGRADE
       end
 
-      def run(options)
+      sig {void}
+      def run_internal
         # Config loading in MODE_UPGRADE will bail out only if the config
         # version is too new.
 
@@ -38,11 +52,11 @@ The following breaking changes will occur:
 MSG
         end
 
-        if options['dry_run']
+        if @options.dry_run
           puts <<-MSG
 Run 'braid upgrade-config#{config.breaking_change_descs.empty? ? '' : ' --allow-breaking-changes'}' to perform the upgrade.
 MSG
-        elsif !config.breaking_change_descs.empty? && !options['allow_breaking_changes']
+        elsif !config.breaking_change_descs.empty? && !@options.allow_breaking_changes
           raise BraidError, 'You must pass --allow-breaking-changes to accept the breaking changes.'
         else
           config.write_db

data/lib/braid/config.rb

@@ -1,4 +1,4 @@
-# typed: true
+# typed: strict
 require 'yaml'
 require 'json'
 require 'yaml/store'
@@ -84,20 +84,29 @@ module Braid
     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]
-      @mode            = options['mode']             || MODE_MAY_WRITE
+    sig {params(config_file: String, old_config_files: T::Array[String], mode: ConfigMode).void}
+    def initialize(config_file: CONFIG_FILE, old_config_files: [OLD_CONFIG_FILE], mode: MODE_MAY_WRITE)
+      @config_file     = config_file
+      old_config_files = old_config_files
+      @mode            = mode
 
       data = load_config(@config_file, old_config_files)
-      @config_existed = !data.nil?
+      @config_existed = T.let(!data.nil?, T::Boolean)
       if !@config_existed
-        @config_version = CURRENT_CONFIG_VERSION
-        @db = {}
+        @config_version = T.let(CURRENT_CONFIG_VERSION, Integer)
+        @db = T.let({}, T::Hash[String, Mirror::MirrorAttributes])
       elsif data['config_version'].is_a?(Numeric)
         @config_version = data['config_version']
+        # WARNING (typing): In general, slapping a type annotation on the loaded
+        # data without validating its structure could be misleading as we work
+        # on the rest of the code.  In the worst case, it might lead us to
+        # delete useful sanity checks because they trigger Sorbet unreachable
+        # code errors.  As of this writing (2024-08-04), we have nothing to lose
+        # because we don't attempt to defend against malformed data anyway, and
+        # there's a benefit to having the type information available.  If we add
+        # any validation, consider whether the annotations should be changed to
+        # verify that we did the validation correctly, e.g., by starting with a
+        # type like `T.anything` instead of `T.untyped`.
         @db = data['mirrors']
       else
         # Before config versioning (Braid < 1.1.0)
@@ -115,7 +124,7 @@ MSG
       end
 
       # In all modes, instantiate all mirrors to scan for breaking changes.
-      @breaking_change_descs = []
+      @breaking_change_descs = T.let([], T::Array[String])
       paths_to_delete = []
       @db.each do |path, attributes|
         begin
@@ -163,7 +172,7 @@ MSG
 
     end
 
-    sig {params(url: String, options: T.untyped).returns(Mirror)}
+    sig {params(url: String, options: Mirror::Options).returns(Mirror)}
     def add_from_options(url, options)
       mirror = Mirror.new_from_options(url, options)
 
@@ -171,7 +180,7 @@ MSG
       mirror
     end
 
-    sig {returns(T::Array[Mirror])}
+    sig {returns(T::Array[String])}
     def mirrors
       @db.keys
     end
@@ -213,11 +222,12 @@ MSG
     # Public for upgrade-config command only.
     sig {void}
     def write_db
-      new_db = {}
+      new_db = T.let({}, T::Hash[String, Mirror::MirrorAttributes])
       @db.keys.sort.each do |key|
-        new_db[key] = {}
+        attrs = T.must(@db[key])
+        new_db[key] = new_attrs = {}
         Braid::Mirror::ATTRIBUTES.each do |k|
-          new_db[key][k] = @db[key][k] if @db[key].has_key?(k)
+          new_attrs[k] = attrs[k] if attrs.has_key?(k)
         end
       end
       new_data = {
@@ -237,7 +247,7 @@ MSG
       (old_config_files + [config_file]).each do |file|
         next unless File.exist?(file)
         begin
-          store = T.let(YAML::Store, T.untyped).new(file)
+          store = T.unsafe(YAML::Store).new(file)
           data = {}
           store.transaction(true) do
             store.roots.each do |path|
@@ -258,7 +268,7 @@ MSG
       @db[mirror.path] = clean_attributes(mirror.attributes)
     end
 
-    sig {params(hash: T::Hash[String, T.untyped]).returns(T::Hash[String, T.untyped])}
+    sig {params(hash: Mirror::MirrorAttributes).returns(Mirror::MirrorAttributes)}
     def clean_attributes(hash)
       hash.reject { |_, v| v.nil? }
     end

data/lib/braid/main.rb

@@ -1,3 +1,11 @@
+# `typed: strict` doesn't seem worth the trouble for this file at this time:
+# there's not much for us to actually annotate, and it would take a crazy hack
+# to avoid a Sorbet error on the `@argv` references because Sorbet doesn't seem
+# to honor `T.bind` for instance variables (TODO: file a Sorbet bug about
+# that?).  Finding an approach to meaningfully check our code that uses the
+# `main` DSL is a bigger project that we may or may not undertake later.
+# ~ Matt 2024-08-04
+#
 # typed: true
 
 require 'braid'
@@ -31,8 +39,8 @@ T.unsafe(Main).run {
   # The "main" library doesn't provide a way to do this??
   def check_no_extra_args!
     if @argv.length > 0
-      Braid::Command.handle_error(
-        Braid::BraidError.new('Extra argument(s) passed to command.'))
+      Command.handle_error(
+        BraidError.new('Extra argument(s) passed to command.'))
     end
   end
 
@@ -61,7 +69,7 @@ T.unsafe(Main).run {
     run {
       check_no_extra_args!
       Braid.verbose = verbose
-      Braid::Command.run(:Add, url, {'path' => local_path, 'branch' => branch, 'tag' => tag, 'revision' => revision, 'remote_path' => path})
+      Commands::Add.new(url, Mirror::Options.new(path: local_path, branch: branch, tag: tag, revision: revision, remote_path: path)).run
     }
   }
 
@@ -86,15 +94,15 @@ T.unsafe(Main).run {
 
     run {
       check_no_extra_args!
-      options = {
-        'branch' => branch,
-        'tag' => tag,
-        'revision' => revision,
-        'head' => head,
-        'keep' => keep
-      }
+      options = Commands::Update::Options.new(
+        branch: branch,
+        tag: tag,
+        revision: revision,
+        head: head,
+        keep: keep
+      )
       Braid.verbose = verbose
-      Braid::Command.run(:Update, local_path, options)
+      Commands::Update.new(local_path, options).run
     }
   }
 
@@ -115,11 +123,11 @@ T.unsafe(Main).run {
 
     run {
       check_no_extra_args!
-      options = {
-        :keep => keep
-      }
+      options = Commands::Remove::Options.new(
+        keep: keep
+      )
       Braid.verbose = verbose
-      Braid::Command.run(:Remove, local_path, options)
+      Commands::Remove.new(local_path, options).run
     }
   }
 
@@ -141,12 +149,12 @@ T.unsafe(Main).run {
       if @argv.length > 0 && @argv[0] == '--'
         @argv.shift
       end
-      options = {
-        'keep' => keep,
-        'git_diff_args' => @argv
-      }
+      options = Commands::Diff::Options.new(
+        keep: keep,
+        git_diff_args: @argv
+      )
       Braid.verbose = verbose
-      Braid::Command.run(:Diff, local_path, options)
+      Commands::Diff.new(local_path, options).run
     }
   }
 
@@ -159,12 +167,12 @@ T.unsafe(Main).run {
 
     run {
       check_no_extra_args!
-      options = {
-        'keep' => keep,
-        'branch' => branch
-      }
+      options = Commands::Push::Options.new(
+        keep: keep,
+        branch: branch
+      )
       Braid.verbose = verbose
-      Braid::Command.run(:Push, local_path, options)
+      Commands::Push.new(local_path, options).run
     }
   }
 
@@ -179,7 +187,7 @@ T.unsafe(Main).run {
       check_no_extra_args!
       Braid.verbose = verbose
       Braid.force = force
-      Braid::Command.run(:Setup, local_path)
+      Commands::Setup.new(local_path).run
     }
   }
 
@@ -188,7 +196,7 @@ T.unsafe(Main).run {
 
     run {
       check_no_extra_args!
-      puts "braid #{Braid::VERSION}"
+      puts "braid #{VERSION}"
     }
   }
 
@@ -200,7 +208,7 @@ T.unsafe(Main).run {
     run {
       check_no_extra_args!
       Braid.verbose = verbose
-      Braid::Command.run(:Status, local_path)
+      Commands::Status.new(local_path).run
     }
   }
 
@@ -220,6 +228,7 @@ T.unsafe(Main).run {
       optional
       desc 'Explain the consequences of the upgrade without performing it.'
       attr :dry_run
+      default false
     }
 
     option('allow-breaking-changes') {
@@ -228,16 +237,17 @@ T.unsafe(Main).run {
         Perform the upgrade even if it involves breaking changes.
       DESC
       attr :allow_breaking_changes
+      default false
     }
 
     run {
       check_no_extra_args!
-      options = {
-        'dry_run' => dry_run,
-        'allow_breaking_changes' => allow_breaking_changes
-      }
+      options = Commands::UpgradeConfig::Options.new(
+        dry_run: dry_run,
+        allow_breaking_changes: allow_breaking_changes
+      )
       Braid.verbose = verbose
-      Braid::Command.run(:UpgradeConfig, options)
+      Commands::UpgradeConfig.new(options).run
     }
   }
 
@@ -301,6 +311,7 @@ T.unsafe(Main).run {
       optional
       desc 'unused option'
       attr
+      default false
     }
   }
 
@@ -309,6 +320,7 @@ T.unsafe(Main).run {
       optional
       desc 'log shell commands'
       attr
+      default false
     }
   }
 
@@ -317,6 +329,7 @@ T.unsafe(Main).run {
       optional
       desc 'force'
       attr
+      default false
     }
   }
 
@@ -325,6 +338,7 @@ T.unsafe(Main).run {
       optional
       desc 'do not remove the remote'
       attr
+      default false
     }
   }
 

data/lib/braid/mirror.rb

@@ -14,12 +14,6 @@ module Braid
         "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
@@ -32,16 +26,21 @@ module Braid
     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])}
+    # It's going to take significant refactoring to be able to give
+    # `MirrorAttributes` a type.  Encapsulating the `T.untyped` in a type alias
+    # makes it easier to search for all the distinct root causes of untypedness
+    # in the code.
+    MirrorAttributes = T.type_alias { T::Hash[String, T.untyped] }
+
+    sig {returns(MirrorAttributes)}
     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}
+    sig {params(path: String, attributes: MirrorAttributes, breaking_change_cb: BreakingChangeCallback).void}
     def initialize(path, attributes = {}, breaking_change_cb = DUMMY_BREAKING_CHANGE_CB)
       @path       = T.let(path.sub(/\/$/, ''), String)
-      @attributes = T.let(attributes.dup, T::Hash[String, T.untyped])
+      @attributes = T.let(attributes.dup, MirrorAttributes)
 
       # Not that it's terribly important to check for such an old feature.  This
       # is mainly to demonstrate the RemoveMirrorDueToBreakingChange mechanism
@@ -79,19 +78,39 @@ DESC
       @attributes.delete('squashed')
     end
 
-    sig {params(url: String, options: T.untyped).returns(Mirror)}
-    def self.new_from_options(url, options = {})
+    # `Mirror::Options` doubles as the options struct for the `add` command, so
+    # some properties are meaningful only in that context.  TODO: Maybe the code
+    # could be organized in a better way.
+    class Options < T::Struct
+      prop :tag, T.nilable(String)
+      prop :branch, T.nilable(String)
+      # NOTE: Used only by the `add` command; ignored by
+      # `Mirror::new_from_options`.
+      prop :revision, T.nilable(Operations::Git::ObjectExpr)
+      prop :path, T.nilable(String)
+      prop :remote_path, T.nilable(String)
+    end
+
+    sig {params(url: String, options: Options).returns(Mirror)}
+    def self.new_from_options(url, options = Options.new)
       url    = url.sub(/\/$/, '')
+      # TODO: Ensure `url` is absolute?  The user is probably more likely to
+      # move the downstream repository by itself than to move it along with the
+      # vendor repository.  And we definitely don't want to use relative URLs in
+      # the cache.
 
-      raise NoTagAndBranch if options['tag'] && options['branch']
+      raise NoTagAndBranch if options.tag && options.branch
 
-      tag = options['tag']
-      branch = options['branch']
+      tag = options.tag
+      branch = options.branch
 
-      path = (options['path'] || extract_path_from_url(url, options['remote_path'])).sub(/\/$/, '')
-      raise PathRequired unless path
+      path = (options.path || extract_path_from_url(url, options.remote_path)).sub(/\/$/, '')
+      # TODO: Check that `path` is a valid relative path and not something like
+      # '.' or ''.  Some of these pathological cases will cause Braid to bail
+      # out later when something else fails, but it would be better to check up
+      # front.
 
-      remote_path = options['remote_path']
+      remote_path = options.remote_path
 
       attributes = {'url' => url, 'branch' => branch, 'path' => remote_path, 'tag' => tag}
       self.new(path, attributes)
@@ -107,7 +126,7 @@ DESC
       branch.nil? && tag.nil?
     end
 
-    sig {params(commit: String).returns(T::Boolean)}
+    sig {params(commit: Operations::Git::ObjectExpr).returns(T::Boolean)}
     def merged?(commit)
       # tip from spearce in #git:
       # `test z$(git merge-base A B) = z$(git rev-parse --verify A)`
@@ -115,9 +134,7 @@ 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)}
+    sig {params(revision: String).returns(Operations::Git::TreeItem)}
     def upstream_item_for_revision(revision)
       git.get_tree_item(revision, self.remote_path)
     end
@@ -211,16 +228,28 @@ DESC
       git.remote_url(remote) == cached_url
     end
 
-    sig {returns(String)}
+    sig {returns(Operations::Git::ObjectID)}
     def base_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)
+      # TODO (typing): We think `revision` should always be non-nil here these
+      # days and we can completely drop the `inferred_revision` code, but we're
+      # waiting for a better time to actually make this runtime behavior change
+      # and accept any risk of breakage
+      # (https://github.com/cristibalan/braid/pull/105/files#r857150464).
+      #
+      # Temporary variable
+      # (https://sorbet.org/docs/flow-sensitive#limitations-of-flow-sensitivity)
+      revision1 = revision
+      if revision1
+        git.rev_parse(revision1)
       else
-        inferred_revision
+        # NOTE: Given that `inferred_revision` does appear to return nil on one
+        # code path, using this `T.must` and giving `base_revision` a
+        # non-nilable return type presents a theoretical risk of leading us to
+        # make changes to callers that break things at runtime.  But we judge
+        # this a lesser evil than making the return type nilable and changing
+        # all callers to type-check successfully with that when we hope to
+        # revert the change soon anyway.
+        T.must(inferred_revision)
       end
     end
 
@@ -310,7 +339,12 @@ DESC
 
     sig {returns(String)}
     def remote
-      "#{branch || tag || 'revision'}/braid/#{path}".gsub(/\/\./, '/_')
+      # Ensure that we replace any characters in the mirror path that might be
+      # problematic in a Git ref name.  Theoretically, this may introduce
+      # collisions between mirrors, but we don't expect that to be much of a
+      # problem because Braid doesn't keep remotes by default after a command
+      # exits.
+      "#{branch || tag || 'revision'}_braid_#{path}".gsub(/[^-A-Za-z0-9]/, '_')
     end
 
     private
@@ -322,8 +356,8 @@ DESC
 
     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|
+      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          = T.let(nil, T.nilable(String))
@@ -338,24 +372,16 @@ DESC
       hash
     end
 
-    # TODO (typing): Return should not be nilable
-    sig {params(url: String, remote_path: T.nilable(String)).returns(T.nilable(String))}
+    sig {params(url: String, remote_path: T.nilable(String)).returns(String)}
     def self.extract_path_from_url(url, remote_path)
       if remote_path
         return File.basename(remote_path)
       end
 
-      # 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'
-        # strip .git
-        name[0..-5]
-      else
-        name
-      end
+      # strip .git if present
+      name.delete_suffix('.git')
     end
   end
 end