dependabot-common 0.384.0 → 0.386.0

data/lib/dependabot/pull_request_creator/branch_name_template.rb

@@ -0,0 +1,138 @@
+# typed: strong
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+require "dependabot/errors"
+require "dependabot/pull_request_creator"
+
+module Dependabot
+  class PullRequestCreator
+    class BranchNameTemplate
+      extend T::Sig
+
+      class Error < Dependabot::DependabotError; end
+
+      SOLO_PLACEHOLDERS = T.let(
+        %w(prefix package_manager directory target_branch dependency version name).freeze,
+        T::Array[String]
+      )
+      GROUP_PLACEHOLDERS = T.let(
+        %w(prefix package_manager directory target_branch group_name name).freeze,
+        T::Array[String]
+      )
+      MULTI_ECO_PLACEHOLDERS = T.let(
+        %w(prefix target_branch group_name name).freeze,
+        T::Array[String]
+      )
+
+      # ---------------------------------------------------------------
+      # 1. validate_template(template, strategy:)
+      #    Ensures every {token} is allowed for the given strategy,
+      #    brackets are well-formed, and no forbidden placeholders used.
+      # ---------------------------------------------------------------
+      sig { params(template: String, strategy: Symbol).returns(T::Boolean) }
+      def self.validate_template(template, strategy:) # rubocop:disable Naming/PredicateMethod
+        raise Error, "Template must be a non-empty string." if template.empty?
+
+        allowed = allowed_placeholders(strategy)
+        messages = collect_template_errors(template, allowed, strategy)
+
+        raise Error, "#{messages.join("\n")}\nAllowed: #{allowed.map { |v| "{#{v}}" }.join(', ')}" if messages.any?
+
+        true
+      end
+
+      sig { params(strategy: Symbol).returns(T::Array[String]) }
+      def self.allowed_placeholders(strategy)
+        case strategy
+        when :solo then SOLO_PLACEHOLDERS
+        when :group then GROUP_PLACEHOLDERS
+        when :multi_ecosystem then MULTI_ECO_PLACEHOLDERS
+        else
+          raise Error, "Unknown strategy: #{strategy}"
+        end
+      end
+
+      sig { params(template: String, allowed: T::Array[String], strategy: Symbol).returns(T::Array[String]) }
+      def self.collect_template_errors(template, allowed, strategy)
+        used = template.scan(/\{(\w+)\}/).flatten
+        unknown = used.uniq.reject { |t| allowed.include?(t) }
+        unknown -= ["package_manager"] if strategy == :multi_ecosystem && used.include?("package_manager")
+        malformed = template.gsub(/\{\w+\}/, "").match?(/[{}]/)
+
+        messages = T.let([], T::Array[String])
+        messages << "Unknown placeholder(s): #{unknown.map { |v| "{#{v}}" }.join(', ')}" unless unknown.empty?
+        messages << "Malformed or unclosed braces detected." if malformed
+
+        if strategy == :multi_ecosystem && used.include?("package_manager")
+          messages << "{package_manager} is not available for multi-ecosystem groups (spans multiple ecosystems)."
+        end
+
+        messages
+      end
+
+      # ---------------------------------------------------------------
+      # 2. validate_ref_name(name)
+      #    Validates the final branch name against Git ref rules.
+      # ---------------------------------------------------------------
+      sig { params(name: String).returns(T::Boolean) }
+      def self.validate_ref_name(name) # rubocop:disable Naming/PredicateMethod
+        illegal = %r{
+          [\x00-\x1F\x7F\ ~^:?*\[\\] |
+          \.\.                         |
+          @\{                          |
+          //                           |
+          /\.                          |
+          \A/                          |
+          /\z                          |
+          \.lock\z                     |
+          \A-                          |
+          \.\z                         |
+          \A@\z
+        }x
+
+        raise Error, "Resolved branch name \"#{name}\" is not a valid Git ref." if name.match?(illegal)
+
+        true
+      end
+
+      # ---------------------------------------------------------------
+      # 3. render(template, vars, strategy:, digest: nil)
+      #    Full pipeline: validate template -> substitute -> append digest
+      #    -> validate ref.
+      # ---------------------------------------------------------------
+      sig do
+        params(
+          template: String,
+          vars: T::Hash[String, String],
+          strategy: Symbol,
+          digest: T.nilable(String)
+        ).returns(String)
+      end
+      def self.render(template, vars, strategy:, digest: nil)
+        validate_template(template, strategy: strategy)
+
+        # Substitute placeholders
+        name = template.gsub(/\{(\w+)\}/) do
+          key = T.must(Regexp.last_match(1))
+          raise Error, "Missing value for placeholder \"{#{key}}\"." unless vars.key?(key)
+
+          T.must(vars[key])
+        end
+
+        # Auto-append digest for Group/MultiEcosystem
+        name = "#{name}-#{digest}" if digest && strategy != :solo
+
+        # Collapse empty path segments (e.g. {target_branch} when nil) and strip edge slashes
+        name = name.squeeze("/").gsub(%r{\A/|/\z}, "")
+        raise Error, "Resolved branch name is empty." if name.empty?
+
+        # Validate git ref after all transformations
+        validate_ref_name(name)
+
+        name
+      end
+    end
+  end
+end

data/lib/dependabot/pull_request_creator/branch_namer/base.rb

@@ -4,6 +4,8 @@
 require "digest"
 require "sorbet-runtime"
 
+require "dependabot/pull_request_creator/branch_name_template"
+
 module Dependabot
   class PullRequestCreator
     class BranchNamer
@@ -28,6 +30,15 @@ module Dependabot
         sig { returns(T.nilable(Integer)) }
         attr_reader :max_length
 
+        sig { returns(T.nilable(String)) }
+        attr_reader :word_separator
+
+        sig { returns(T.nilable(String)) }
+        attr_reader :branch_name_case
+
+        sig { returns(T.nilable(String)) }
+        attr_reader :template
+
         sig do
           params(
             dependencies: T::Array[Dependency],
@@ -35,7 +46,10 @@ module Dependabot
             target_branch: T.nilable(String),
             separator: String,
             prefix: String,
-            max_length: T.nilable(Integer)
+            max_length: T.nilable(Integer),
+            word_separator: T.nilable(String),
+            branch_name_case: T.nilable(String),
+            template: T.nilable(String)
           )
             .void
         end
@@ -45,7 +59,10 @@ module Dependabot
           target_branch:,
           separator: "/",
           prefix: "dependabot",
-          max_length: nil
+          max_length: nil,
+          word_separator: nil,
+          branch_name_case: nil,
+          template: nil
         )
           @dependencies      = dependencies
           @files             = files
@@ -53,6 +70,9 @@ module Dependabot
           @separator         = separator
           @prefix            = prefix
           @max_length        = max_length
+          @word_separator    = word_separator
+          @branch_name_case  = branch_name_case
+          @template          = template
         end
 
         sig { overridable.returns(String) }
@@ -62,6 +82,25 @@ module Dependabot
 
         private
 
+        sig do
+          params(
+            vars: T::Hash[String, String],
+            strategy: Symbol,
+            digest: T.nilable(String)
+          ).returns(String)
+        end
+        def render_from_template(vars:, strategy:, digest: nil)
+          rendered = BranchNameTemplate.render(
+            T.must(template),
+            vars,
+            strategy: strategy,
+            digest: digest
+          )
+
+          # Apply post-processing (separator, word_separator, case) and max-length
+          sanitize_branch_name(rendered)
+        end
+
         sig { params(ref_name: String).returns(String) }
         def sanitize_branch_name(ref_name)
           # General git ref validation
@@ -70,6 +109,27 @@ module Dependabot
           # Some users need branch names without slashes
           sanitized_name = sanitized_name.gsub("/", separator)
 
+          # Apply word_separator and case transformation only to content after the prefix,
+          # preserving the user-configured prefix as-is.
+          if word_separator || branch_name_case
+            prefix_with_sep = "#{prefix}#{separator}"
+            prefix_part = sanitized_name.start_with?(prefix_with_sep) ? prefix_with_sep : ""
+            content = sanitized_name.delete_prefix(prefix_with_sep)
+
+            # Replace underscores with word_separator in the content after prefix
+            content = content.gsub("_", T.must(word_separator)) if word_separator
+
+            # Apply case transformation to content after prefix
+            case branch_name_case
+            when "lower"
+              content = content.downcase
+            when "upper"
+              content = content.upcase
+            end
+
+            sanitized_name = "#{prefix_part}#{content}"
+          end
+
           # Shorten the ref in case users refs have length limits
           branch_name_max_length = max_length
           if branch_name_max_length && (sanitized_name.length > branch_name_max_length)

data/lib/dependabot/pull_request_creator/branch_namer/dependency_group_strategy.rb

@@ -19,7 +19,10 @@ module Dependabot
             includes_security_fixes: T::Boolean,
             separator: String,
             prefix: String,
-            max_length: T.nilable(Integer)
+            max_length: T.nilable(Integer),
+            word_separator: T.nilable(String),
+            branch_name_case: T.nilable(String),
+            template: T.nilable(String)
           )
             .void
         end
@@ -31,7 +34,10 @@ module Dependabot
           includes_security_fixes:,
           separator: "/",
           prefix: "dependabot",
-          max_length: nil
+          max_length: nil,
+          word_separator: nil,
+          branch_name_case: nil,
+          template: nil
         )
           super(
             dependencies: dependencies,
@@ -40,6 +46,9 @@ module Dependabot
             separator: separator,
             prefix: prefix,
             max_length: max_length,
+            word_separator: word_separator,
+            branch_name_case: branch_name_case,
+            template: template,
           )
 
           @dependency_group = dependency_group
@@ -48,6 +57,14 @@ module Dependabot
 
         sig { override.returns(String) }
         def new_branch_name
+          if template
+            return render_from_template(
+              vars: template_vars,
+              strategy: :group,
+              digest: dependency_digest
+            )
+          end
+
           sanitize_branch_name(File.join(prefixes, group_name_with_dependency_digest))
         end
 
@@ -56,6 +73,24 @@ module Dependabot
         sig { returns(Dependabot::DependencyGroup) }
         attr_reader :dependency_group
 
+        sig { returns(T::Hash[String, String]) }
+        def template_vars
+          directory_part = (directory || "/").sub(%r{^/}, "")
+          directory_part = "root" if directory_part.empty?
+
+          group_name = sanitize_ref(dependency_group.name.tr(" ", "-"))
+
+          vars = {
+            "prefix" => prefix,
+            "package_manager" => package_manager,
+            "directory" => directory_part,
+            "group_name" => group_name,
+            "name" => group_name,
+            "target_branch" => target_branch || ""
+          }
+          vars
+        end
+
         sig { returns(T::Array[String]) }
         def prefixes
           [

data/lib/dependabot/pull_request_creator/branch_namer/multi_ecosystem_strategy.rb

@@ -19,7 +19,10 @@ module Dependabot
             multi_ecosystem_name: String,
             separator: String,
             prefix: String,
-            max_length: T.nilable(Integer)
+            max_length: T.nilable(Integer),
+            word_separator: T.nilable(String),
+            branch_name_case: T.nilable(String),
+            template: T.nilable(String)
           )
             .void
         end
@@ -31,7 +34,10 @@ module Dependabot
           multi_ecosystem_name:,
           separator: "/",
           prefix: "dependabot",
-          max_length: nil
+          max_length: nil,
+          word_separator: nil,
+          branch_name_case: nil,
+          template: nil
         )
           super(
             dependencies: dependencies,
@@ -40,6 +46,9 @@ module Dependabot
             separator: separator,
             prefix: prefix,
             max_length: max_length,
+            word_separator: word_separator,
+            branch_name_case: branch_name_case,
+            template: template,
           )
 
           @multi_ecosystem_name = multi_ecosystem_name
@@ -48,6 +57,14 @@ module Dependabot
 
         sig { override.returns(String) }
         def new_branch_name
+          if template
+            return render_from_template(
+              vars: template_vars,
+              strategy: :multi_ecosystem,
+              digest: dependency_digest
+            )
+          end
+
           sanitize_branch_name(File.join(prefixes, group_name_with_dependency_digest))
         end
 
@@ -56,6 +73,19 @@ module Dependabot
         sig { returns(String) }
         attr_reader :multi_ecosystem_name
 
+        sig { returns(T::Hash[String, String]) }
+        def template_vars
+          multi_name = sanitize_ref(multi_ecosystem_name.tr(" ", "-"))
+
+          vars = {
+            "prefix" => prefix,
+            "group_name" => multi_name,
+            "name" => multi_name,
+            "target_branch" => target_branch || ""
+          }
+          vars
+        end
+
         sig { returns(T::Array[String]) }
         def prefixes
           [

data/lib/dependabot/pull_request_creator/branch_namer/solo_strategy.rb

@@ -15,26 +15,18 @@ module Dependabot
 
         sig { override.returns(String) }
         def new_branch_name
+          if template
+            return render_from_template(
+              vars: template_vars,
+              strategy: :solo
+            )
+          end
+
           return short_branch_name if branch_name_might_be_long?
 
           @name ||=
             T.let(
-              begin
-                dependency_name_part =
-                  if dependencies.count > 1 && updating_a_property?
-                    property_name
-                  elsif dependencies.count > 1 && updating_a_dependency_set?
-                    dependency_set.fetch(:group)
-                  else
-                    dependencies
-                      .map(&:name)
-                      .join("-and-")
-                      .tr(":[]", "-")
-                      .tr("@", "")
-                  end
-
-                "#{dependency_name_part}-#{branch_version_suffix}"
-              end,
+              "#{template_dependency_name}-#{branch_version_suffix}",
               T.nilable(String)
             )
 
@@ -53,6 +45,40 @@ module Dependabot
           ].compact
         end
 
+        sig { returns(T::Hash[String, String]) }
+        def template_vars
+          dep_name = template_dependency_name
+          version = branch_version_suffix || ""
+
+          vars = {
+            "prefix" => prefix,
+            "package_manager" => package_manager,
+            "directory" => sanitized_directory,
+            "dependency" => dep_name,
+            "version" => version,
+            "name" => "#{dep_name}-#{version}",
+            "target_branch" => target_branch || ""
+          }
+          vars
+        end
+
+        sig { returns(String) }
+        def template_dependency_name
+          if dependencies.count > 1 && updating_a_property?
+            property_name
+          elsif dependencies.count > 1 && updating_a_dependency_set?
+            dependency_set.fetch(:group)
+          else
+            dependencies.map(&:name).join("-and-").tr(":[]", "-").tr("@", "")
+          end
+        end
+
+        sig { returns(String) }
+        def sanitized_directory
+          dir = (files.first&.directory&.tr(" ", "-") || "/").sub(%r{^/}, "")
+          dir.empty? ? "root" : dir
+        end
+
         sig { returns(String) }
         def package_manager
           T.must(dependencies.first).package_manager

data/lib/dependabot/pull_request_creator/branch_namer.rb

@@ -9,6 +9,7 @@ require "dependabot/pull_request_creator"
 require "dependabot/pull_request_creator/branch_namer/solo_strategy"
 require "dependabot/pull_request_creator/branch_namer/dependency_group_strategy"
 require "dependabot/pull_request_creator/branch_namer/multi_ecosystem_strategy"
+require "dependabot/pull_request_creator/branch_name_template"
 
 module Dependabot
   class PullRequestCreator
@@ -33,6 +34,15 @@ module Dependabot
       sig { returns(T.nilable(Integer)) }
       attr_reader :max_length
 
+      sig { returns(T.nilable(String)) }
+      attr_reader :word_separator
+
+      sig { returns(T.nilable(String)) }
+      attr_reader :branch_name_case
+
+      sig { returns(T.nilable(String)) }
+      attr_reader :template
+
       sig { returns(T.nilable(Dependabot::DependencyGroup)) }
       attr_reader :dependency_group
 
@@ -51,6 +61,9 @@ module Dependabot
           separator: String,
           prefix: String,
           max_length: T.nilable(Integer),
+          word_separator: T.nilable(String),
+          branch_name_case: T.nilable(String),
+          template: T.nilable(String),
           includes_security_fixes: T::Boolean,
           multi_ecosystem_name: T.nilable(String)
         )
@@ -64,6 +77,9 @@ module Dependabot
         separator: "/",
         prefix: "dependabot",
         max_length: nil,
+        word_separator: nil,
+        branch_name_case: nil,
+        template: nil,
         includes_security_fixes: false,
         multi_ecosystem_name: nil
       )
@@ -74,6 +90,9 @@ module Dependabot
         @separator     = separator
         @prefix        = prefix
         @max_length    = max_length
+        @word_separator = word_separator
+        @branch_name_case = branch_name_case
+        @template = template
         @includes_security_fixes = includes_security_fixes
         @multi_ecosystem_name = multi_ecosystem_name
       end
@@ -109,6 +128,9 @@ module Dependabot
           separator: separator,
           prefix: prefix,
           max_length: max_length,
+          word_separator: word_separator,
+          branch_name_case: branch_name_case,
+          template: template,
           multi_ecosystem_name: T.must(multi_ecosystem_name)
         )
       end
@@ -121,7 +143,10 @@ module Dependabot
           target_branch: target_branch,
           separator: separator,
           prefix: prefix,
-          max_length: max_length
+          max_length: max_length,
+          word_separator: word_separator,
+          branch_name_case: branch_name_case,
+          template: template
         )
       end
 
@@ -135,7 +160,10 @@ module Dependabot
           includes_security_fixes: includes_security_fixes,
           separator: separator,
           prefix: prefix,
-          max_length: max_length
+          max_length: max_length,
+          word_separator: word_separator,
+          branch_name_case: branch_name_case,
+          template: template
         )
       end
     end

data/lib/dependabot/pull_request_creator/message_builder.rb

@@ -45,10 +45,10 @@ module Dependabot
       sig { returns(T.nilable(String)) }
       attr_reader :pr_message_footer
 
-      sig { returns(T.nilable(T::Hash[Symbol, T.untyped])) }
+      sig { returns(T.nilable(T::Hash[Symbol, T.anything])) }
       attr_reader :commit_message_options
 
-      sig { returns(T::Hash[String, T.untyped]) }
+      sig { returns(T::Hash[String, T::Array[T::Hash[String, String]]]) }
       attr_reader :vulnerabilities_fixed
 
       sig { returns(T.nilable(String)) }
@@ -79,8 +79,8 @@ module Dependabot
           credentials: T::Array[Dependabot::Credential],
           pr_message_header: T.nilable(String),
           pr_message_footer: T.nilable(String),
-          commit_message_options: T.nilable(T::Hash[Symbol, T.untyped]),
-          vulnerabilities_fixed: T::Hash[String, T.untyped],
+          commit_message_options: T.nilable(T::Hash[Symbol, T.anything]),
+          vulnerabilities_fixed: T::Hash[String, T::Array[T::Hash[String, String]]],
           github_redirection_service: T.nilable(String),
           dependency_group: T.nilable(Dependabot::DependencyGroup),
           pr_message_max_length: T.nilable(Integer),
@@ -379,7 +379,7 @@ module Dependabot
 
       sig { returns(T.nilable(String)) }
       def custom_trailers
-        trailers = commit_message_options&.dig(:trailers)
+        trailers = T.cast(commit_message_options&.dig(:trailers), T.nilable(Object))
         return if trailers.nil?
         raise("Commit trailers must be a Hash object") unless trailers.is_a?(Hash)
 
@@ -395,7 +395,7 @@ module Dependabot
 
       sig { returns(T.nilable(String)) }
       def signoff_message
-        signoff_details = commit_message_options&.dig(:signoff_details)
+        signoff_details = T.cast(commit_message_options&.dig(:signoff_details), T.nilable(Object))
         return unless signoff_details.is_a?(Hash)
         return unless signoff_details[:name] && signoff_details[:email]
 
@@ -404,7 +404,7 @@ module Dependabot
 
       sig { returns(T.nilable(String)) }
       def on_behalf_of_message
-        signoff_details = commit_message_options&.dig(:signoff_details)
+        signoff_details = T.cast(commit_message_options&.dig(:signoff_details), T.nilable(Object))
         return unless signoff_details.is_a?(Hash)
         return unless signoff_details[:org_name] && signoff_details[:org_email]