git 1.19.1 → 5.5.0

data/lib/git/parsers/branch.rb

@@ -0,0 +1,240 @@
+# frozen_string_literal: true
+
+require 'git/branch_info'
+require 'git/branch_delete_result'
+require 'git/branch_delete_failure'
+
+module Git
+  # Internal parsers that translate raw git command output into structured Ruby objects.
+  #
+  # @api private
+  #
+  module Parsers
+    # Parser for git branch command output
+    #
+    # Handles parsing of `git branch --list` and `git branch --delete` output
+    # into structured data objects.
+    #
+    # ## Design Note: Namespace Organization
+    #
+    # This parser creates and returns {Git::BranchInfo} and {Git::BranchDeleteResult}
+    # objects, which live at the top-level `Git::` namespace rather than within
+    # `Git::Parsers::`. This is intentional:
+    #
+    # - **Parsers are infrastructure** - marked `@api private`, users shouldn't
+    #   interact with them directly
+    # - **Info/Result classes are public API** - returned by commands and used
+    #   throughout the codebase
+    # - **Info classes are domain entities** - represent core git concepts
+    #   (branches as data)
+    # - **Result classes are operation outcomes** - represent command results,
+    #   not parsing details
+    #
+    # Keeping Info/Result classes at `Git::` improves discoverability and correctly
+    # reflects their role as public types rather than parser internals.
+    #
+    # @api private
+    #
+    module Branch
+      # Format string for git branch --format
+      #
+      # Fields (null-delimited):
+      # 1. refname      - full ref name (e.g., refs/heads/main, refs/remotes/origin/main)
+      # 2. objectname  - full SHA of the commit the branch points to
+      # 3. HEAD         - '*' if current branch, empty otherwise
+      # 4. worktreepath - path if checked out in another worktree, empty otherwise
+      # 5. symref       - target ref if symbolic reference, empty otherwise
+      # 6. upstream     - full upstream ref (e.g., refs/remotes/origin/main), empty if none
+      #
+      # Null bytes (%00) are used as field delimiters so that worktree paths
+      # containing special characters (including '|') parse correctly.
+      #
+      FORMAT_STRING = '%(refname)%00%(objectname)%00%(HEAD)%00%(worktreepath)%00%(symref)%00%(upstream)'
+
+      # Delimiter used in format output
+      FIELD_DELIMITER = "\0"
+
+      # Regex to parse successful deletion lines from stdout
+      # Matches: Deleted branch branchname (was abc123).
+      # Matches: Deleted remote-tracking branch origin/branchname (was abc123).
+      # Uses non-greedy match to capture branch names containing spaces
+      DELETED_BRANCH_REGEX = /^Deleted (?:remote-tracking )?branch (.+?) \(was/
+
+      # Regex to parse error messages from stderr
+      # Matches: error: branch 'branchname' not found.
+      ERROR_BRANCH_REGEX = /^error: branch '([^']+)'(.*)$/
+
+      module_function
+
+      # Parse git branch --list output into BranchInfo objects
+      #
+      # @example Parse NUL-delimited branch list output
+      #   Git::Parsers::Branch.parse_list(
+      #     "refs/heads/main\0abc1234\0*\0\0\0\n" \
+      #     "refs/heads/feature\0def5678\0\0\0\0\n"
+      #   )
+      #   # => [#<data Git::BranchInfo refname="refs/heads/main", ...>,
+      #   #     #<data Git::BranchInfo refname="refs/heads/feature", ...>]
+      #
+      # @param stdout [String] output from git branch --list --format=...
+      #
+      # @param remote_names [Array<String>] configured remote names used to resolve
+      #   remote-tracking refs with slash-containing remote names
+      #
+      # @return [Array<Git::BranchInfo>] parsed branch information
+      #
+      def parse_list(stdout, remote_names: [])
+        stdout.split("\n").filter_map { |line| parse_branch_line(line, remote_names: remote_names) }
+      end
+
+      # Parse a single formatted branch line
+      #
+      # @param line [String] the line to parse (NUL-delimited fields)
+      #
+      # @param remote_names [Array<String>] configured remote names used to resolve
+      #   remote-tracking refs with slash-containing remote names
+      #
+      # @return [Git::BranchInfo, nil] branch info object, or nil if line should be skipped
+      #
+      def parse_branch_line(line, remote_names: [])
+        fields = line.split(FIELD_DELIMITER, 6)
+
+        return nil if non_branch_entry?(fields[0])
+
+        build_branch_info(fields, remote_names: remote_names)
+      end
+
+      # Build a BranchInfo from parsed fields
+      #
+      # @param fields [Array<String>] the parsed fields:
+      #   [refname, objectname, head, worktreepath, symref, upstream]
+      #
+      # @param remote_names [Array<String>] configured remote names used to resolve
+      #   remote-tracking refs with slash-containing remote names
+      #
+      # @return [Git::BranchInfo] the branch info object
+      #
+      def build_branch_info(fields, remote_names: [])
+        raw_refname, objectname, head, worktreepath, symref, upstream = fields
+        Git::BranchInfo.new(
+          refname: raw_refname,
+          target_oid: presence(objectname),
+          current: head == '*',
+          worktree_path: head == '*' ? nil : presence(worktreepath),
+          symref: presence(symref),
+          upstream: build_upstream_info(upstream),
+          remote_name: resolve_remote_name(raw_refname, remote_names)
+        )
+      end
+
+      # Resolve a remote-tracking refname to a configured remote name
+      #
+      # @param refname [String] the branch refname to inspect
+      #
+      # @param remote_names [Array<String>] configured remote names
+      #
+      # @return [String, nil] the resolved remote name, or nil for local branches
+      #
+      def resolve_remote_name(refname, remote_names)
+        remote_path = refname[%r{\A(?:refs/)?remotes/(.+)\z}, 1]
+        return nil if remote_path.nil?
+
+        configured_remote_name = remote_names
+                                 .select { |remote_name| remote_path.start_with?("#{remote_name}/") }
+                                 .max_by(&:length)
+
+        configured_remote_name || Git::BranchInfo.fallback_remote_name(refname)
+      end
+
+      # Check if the refname represents a detached HEAD state or non-branch entry
+      #
+      # Git outputs special entries for detached HEAD and non-branch states:
+      # - "(HEAD detached at <ref>)" when in detached HEAD state
+      # - "(not a branch)" for non-branch entries
+      #
+      # @param refname [String] the refname to check
+      #
+      # @return [Boolean] true if this is a non-branch entry
+      #
+      def non_branch_entry?(refname)
+        refname.match?(/^\(HEAD detached/) || refname.match?(/^\(not a branch\)/)
+      end
+
+      # Return the raw upstream refname string, or nil if empty
+      #
+      # @param upstream_ref [String, nil] the upstream ref (e.g., 'refs/remotes/origin/main')
+      #
+      # @return [String, nil] the raw upstream refname, or nil
+      #
+      def build_upstream_info(upstream_ref)
+        return nil if upstream_ref.nil? || upstream_ref.empty?
+
+        upstream_ref
+      end
+
+      # Return value if non-empty, nil otherwise
+      #
+      # @param value [String, nil] the value to check
+      #
+      # @return [String, nil] the value or nil
+      #
+      def presence(value)
+        value.nil? || value.empty? ? nil : value
+      end
+
+      # Parse deleted branch names from stdout
+      #
+      # @example
+      #   BranchParser.parse_deleted_branches("Deleted branch feature (was abc123).\n")
+      #   # => ["feature"]
+      #
+      # @param stdout [String] command stdout
+      #
+      # @return [Array<String>] names of successfully deleted branches
+      #
+      def parse_deleted_branches(stdout)
+        stdout.scan(DELETED_BRANCH_REGEX).flatten
+      end
+
+      # Parse error messages from stderr into a map
+      #
+      # @example
+      #   BranchParser.parse_error_messages("error: branch 'missing' not found.\n")
+      #   # => {"missing" => "error: branch 'missing' not found."}
+      #
+      # @param stderr [String] command stderr
+      #
+      # @return [Hash<String, String>] map of branch name to error message
+      #
+      def parse_error_messages(stderr)
+        stderr.each_line.with_object({}) do |line, hash|
+          match = line.match(ERROR_BRANCH_REGEX)
+          hash[match[1]] = line.strip if match
+        end
+      end
+
+      # Build the BranchDeleteResult from parsed data
+      #
+      # @param requested_names [Array<String>] originally requested branch names
+      #
+      # @param existing_branches [Hash<String, Git::BranchInfo>] branches that existed before delete
+      #
+      # @param deleted_names [Array<String>] names confirmed deleted in stdout
+      #
+      # @param error_map [Hash<String, String>] map of branch name to error message
+      #
+      # @return [Git::BranchDeleteResult] the result object
+      #
+      def build_delete_result(requested_names, existing_branches, deleted_names, error_map)
+        deleted = deleted_names.filter_map { |name| existing_branches[name] }
+
+        not_deleted = (requested_names - deleted_names).map do |name|
+          error_message = error_map[name] || "branch '#{name}' could not be deleted"
+          Git::BranchDeleteFailure.new(name: name, error_message: error_message)
+        end
+
+        Git::BranchDeleteResult.new(deleted: deleted, not_deleted: not_deleted)
+      end
+    end
+  end
+end

data/lib/git/parsers/cat_file.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Git
+  module Parsers
+    # Parser for `git cat-file` commit and tag output
+    #
+    # Provides class methods that transform raw `git cat-file` output lines into
+    # structured Hash objects consumed by the `Git::Repository::ObjectOperations`
+    # facade.
+    #
+    # @api private
+    #
+    module CatFile
+      module_function
+
+      # Matches a single `git cat-file` header line
+      #
+      # @api private
+      #
+      CAT_FILE_HEADER_LINE = /\A(?<key>\w+) (?<value>.*)\z/
+
+      # Parse `git cat-file commit` output into a structured Hash
+      #
+      # @param lines [Array<String>] mutable cat-file output lines, consumed
+      #   in place during header parsing
+      #
+      # @param sha [String] the object name passed by the caller
+      #
+      # @return [Hash] commit data hash with string keys
+      #
+      # @api private
+      #
+      def parse_commit(lines, sha)
+        headers = parse_commit_headers(lines)
+        message = "#{lines.join("\n")}\n"
+        { 'sha' => sha, 'message' => message }.merge(headers)
+      end
+
+      # Parse `git cat-file tag` output into a structured Hash
+      #
+      # @param lines [Array<String>] mutable cat-file output lines, consumed
+      #   in place during header parsing; remaining lines become the message
+      #
+      # @param name [String] the tag name passed by the caller
+      #
+      # @return [Hash] tag data hash with string keys
+      #
+      # @api private
+      #
+      def parse_tag(lines, name)
+        hsh = { 'name' => name }
+        each_header(lines) { |key, value| hsh[key] = value }
+        hsh['message'] = "#{lines.join("\n")}\n"
+        hsh
+      end
+
+      # Extracts and returns commit headers from the front of `lines`
+      #
+      # Mutates `lines` in place, consuming header lines and the blank
+      # separator line. After the call `lines` contains only message lines.
+      #
+      # @param lines [Array<String>] mutable cat-file output lines
+      #
+      # @return [Hash] parsed header key/value pairs; `parent` is always
+      #   an Array
+      #
+      # @api private
+      #
+      def parse_commit_headers(lines)
+        headers = { 'parent' => [] }
+        each_header(lines) do |key, value|
+          if key == 'parent'
+            headers['parent'] << value
+          else
+            headers[key] = value
+          end
+        end
+        headers
+      end
+
+      # Yields parsed header key/value pairs from `git cat-file` output lines
+      #
+      # Consumes header lines from the front of `lines` until a blank line is
+      # encountered. Continuation lines that begin with a space are folded
+      # into the previous header value using newline separators.
+      #
+      # @param lines [Array<String>] mutable output lines from a cat-file response
+      #
+      # @return [void]
+      #
+      # @yield [key, value] each parsed header pair
+      #
+      # @yieldparam key [String] header field name
+      #
+      # @yieldparam value [String] unfolded header value text
+      #
+      # @yieldreturn [void]
+      #
+      # @api private
+      #
+      def each_header(lines)
+        while (line = lines.shift) && (match = CAT_FILE_HEADER_LINE.match(line))
+          key = match[:key]
+          value_lines = [match[:value]]
+          value_lines << lines.shift.lstrip while lines.first&.start_with?(' ')
+          yield key, value_lines.join("\n")
+        end
+      end
+    end
+  end
+end

data/lib/git/parsers/config_entry.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require 'git/config_entry_info'
+
+module Git
+  module Parsers
+    # Parser for `git config` output
+    #
+    # Each public method corresponds to a different `git config` sub-command
+    # variant and handles the specific output format that variant produces.
+    # Most variants are called with `--show-scope --show-origin --null`;
+    # `parse_urlmatch` handles the `--get-urlmatch` format where `--show-origin`
+    # is unsupported and therefore absent.
+    #
+    # @api private
+    #
+    module ConfigEntry
+      module_function
+
+      # Parse `git config --get --show-scope --show-origin --null` output
+      #
+      # Output format (per entry): `scope\0origin\0value\0`
+      #
+      # The key name is absent from `--get` output and must be supplied by the
+      # caller.
+      #
+      # @param key [String] the config key name that was queried
+      #
+      # @param output [String] raw stdout from the command
+      #
+      # @return [Git::ConfigEntryInfo, nil] the parsed entry, or `nil` when not found
+      #
+      def parse_get(key, output)
+        return nil if output.empty?
+
+        scope, origin, value = output.split("\0", -1)
+        Git::ConfigEntryInfo.new(scope: scope, origin: origin, key: key, value: value)
+      end
+
+      # Parse `git config --get-all --show-scope --show-origin --null` output
+      #
+      # Output format (per entry): `scope\0origin\0value\0`
+      #
+      # The key name is absent from `--get-all` output and must be supplied by
+      # the caller. Multiple entries appear back-to-back in the same string.
+      #
+      # @param key [String] the config key name that was queried
+      #
+      # @param output [String] raw stdout from the command
+      #
+      # @return [Array<Git::ConfigEntryInfo>] the parsed entries
+      #
+      def parse_get_all(key, output)
+        return [] if output.empty?
+
+        tokens = output.split("\0", -1)
+        tokens.pop if tokens.last == ''
+        tokens.each_slice(3).map do |scope, origin, value|
+          Git::ConfigEntryInfo.new(scope: scope, origin: origin, key: key, value: value)
+        end
+      end
+
+      # Parse `git config --list --show-scope --show-origin --null` output
+      #
+      # Also handles `--get-regexp` output, which shares the same format.
+      #
+      # Output format (per entry): `scope\0origin\0key\nvalue\0`
+      #
+      # Multiple entries appear back-to-back in the same string.
+      #
+      # @param output [String] raw stdout from the command
+      #
+      # @return [Array<Git::ConfigEntryInfo>] the parsed entries
+      #
+      def parse_list(output)
+        return [] if output.empty?
+
+        tokens = output.split("\0", -1)
+        tokens.pop if tokens.last == ''
+        tokens.each_slice(3).map do |scope, origin, key_value|
+          key, value = key_value.split("\n", 2)
+          Git::ConfigEntryInfo.new(scope: scope, origin: origin, key: key, value: value || '')
+        end
+      end
+
+      # Parse `git config --get-urlmatch --show-scope --null` output
+      #
+      # Handles the two-field-per-entry format produced by `--get-urlmatch` when
+      # `--show-scope` is used but `--show-origin` is not (git does not support
+      # `--show-origin` with `--get-urlmatch`).
+      #
+      # Output format (per entry): `scope\0key\nvalue\0`
+      #
+      # @param output [String] raw stdout from the command
+      #
+      # @return [Array<Git::ConfigEntryInfo>] the parsed entries; `origin` is `nil` for each
+      #
+      def parse_urlmatch(output)
+        return [] if output.empty?
+
+        tokens = output.split("\0", -1)
+        tokens.pop if tokens.last == ''
+        tokens.each_slice(2).map do |scope, key_value|
+          key, value = key_value.split("\n", 2)
+          Git::ConfigEntryInfo.new(scope: scope, origin: nil, key: key, value: value || '')
+        end
+      end
+    end
+  end
+end