braid 1.1.9 → 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)
@@ -353,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

data/lib/braid/operations.rb

@@ -10,26 +10,18 @@ module Braid
 
   module Operations
     class ShellExecutionError < BraidError
-      # TODO (typing): Should this be nilable?
-      sig {returns(T.nilable(String))}
+      sig {returns(String)}
       attr_reader :err, :out
 
-      sig {params(err: T.nilable(String), out: T.nilable(String)).void}
-      def initialize(err = nil, out = nil)
+      sig {params(err: String, out: String).void}
+      def initialize(err, out)
         @err = err
         @out = out
       end
 
       sig {returns(String)}
       def message
-        first_line = @err.to_s.split("\n").first
-        # Currently, first_line can be nil if @err was empty, but Sorbet thinks
-        # that the `message` method of an Exception should always return non-nil
-        # (although override checking isn't enforced as of this writing), so
-        # handle nil here.  This seems ad-hoc but better than putting in a
-        # `T.must` that we know has a risk of being wrong.  Hopefully this will
-        # be fixed better in https://github.com/cristibalan/braid/issues/90.
-        first_line.nil? ? '' : first_line
+        @err
       end
     end
     class VersionTooLow < BraidError
@@ -201,7 +193,9 @@ module Braid
       ObjectID = T.type_alias { String }
 
       # A string containing an expression that can be evaluated to an object ID
-      # by `git rev-parse`.  Ditto the remark about lack of enforcement.
+      # by `git rev-parse`.  This type is enforced even less than `ObjectID` (in
+      # some cases, we apply it directly to user input without validation), but
+      # it still serves to document our intent.
       ObjectExpr = T.type_alias { String } 
 
       # Get the physical path to a file in the git repository (e.g.,
@@ -252,7 +246,7 @@ module Braid
         elsif out.match(/nothing.* to commit/)
           false
         else
-          raise ShellExecutionError, err
+          raise ShellExecutionError.new(err, out)
         end
       end
 
@@ -364,7 +358,7 @@ module Braid
             # This can happen if the user runs `braid add` with a `--path` that
             # doesn't exist.  TODO: Make the error message more user-friendly in
             # that case.
-            raise ShellExecutionError, 'No tree item exists at the given path'
+            raise BraidError, 'No tree item exists at the given path'
           end
           mode = T.must(m[1])
           type = T.must(m[2])
@@ -374,7 +368,7 @@ module Braid
           elsif type == 'blob'
             return BlobWithMode.new(hash, mode)
           else
-            raise ShellExecutionError, 'Tree item is not a tree or a blob'
+            raise BraidError, 'Tree item is not a tree or a blob'
           end
         end
       end

data/lib/braid/operations_lite.rb

@@ -22,7 +22,7 @@ module Braid
       ).returns(T.type_parameter(:R))
     }
     def self.with_modified_environment(dict, &blk)
-      orig_dict = {}
+      orig_dict = T.let({}, T::Hash[String, T.nilable(String)])
       dict.each { |name, value|
         orig_dict[name] = ENV[name]
         ENV[name] = value

data/lib/braid/sorbet/fake_runtime.rb

@@ -74,5 +74,24 @@ module Braid
       end
     end
 
+    class Struct
+      def initialize(**kwargs)
+        # The fake runtime isn't obliged to validate the property names or
+        # types.
+        #
+        # Note: If the caller passed a hash of keyword arguments, Ruby will copy
+        # it, so we don't need to copy `kwargs` again here to avoid aliasing.
+        @attrs = kwargs
+      end
+
+      def self.prop(prop_name, prop_type)
+        define_method(prop_name) {
+          @attrs[prop_name]
+        }
+        define_method(:"#{prop_name}=") { |new_value|
+          @attrs[prop_name] = new_value
+        }
+      end
+    end
   end
 end

data/lib/braid/version.rb

@@ -2,5 +2,5 @@
 # typed: false
 
 module Braid
-  VERSION = '1.1.9'.freeze
+  VERSION = '1.1.10'.freeze
 end

data/lib/braid.rb

@@ -27,10 +27,7 @@ module Braid
     !!@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}
+  sig {params(new_value: T::Boolean).void}
   def self.verbose=(new_value)
     @verbose = !!new_value
   end
@@ -42,7 +39,7 @@ module Braid
     !!@force
   end
 
-  sig {params(new_value: T.nilable(T::Boolean)).void}
+  sig {params(new_value: T::Boolean).void}
   def self.force=(new_value)
     @force = !!new_value
   end
@@ -59,11 +56,6 @@ module Braid
 
   class BraidError < StandardError
     extend T::Sig
-    sig {returns(String)}
-    def message
-      value = super
-      value if value != self.class.name
-    end
   end
 
   class InternalError < BraidError