git 4.3.2 → 5.0.0.beta.2

data/lib/git/parsers/tag.rb

@@ -0,0 +1,257 @@
+# frozen_string_literal: true
+
+require 'git/tag_info'
+require 'git/tag_delete_result'
+require 'git/tag_delete_failure'
+
+module Git
+  module Parsers
+    # Parser for git tag command output
+    #
+    # Handles parsing of `git tag --list` and `git tag --delete` output
+    # into structured data objects.
+    #
+    # @note Known limitation: If a tag message contains the field delimiter
+    #   character (\x1f, ASCII unit separator), it will be preserved correctly
+    #   since the message is the last field. However, messages are rarely crafted
+    #   with non-printable control characters.
+    #
+    # ## Design Note: Namespace Organization
+    #
+    # This parser creates and returns {Git::TagInfo} and {Git::TagDeleteResult}
+    # 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
+    #   (tags 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 Tag
+      # Delimiter for separating fields in git tag --format output
+      # Field separator used in custom format output
+      # Using the ASCII unit separator (US, 0x1F / "\x1f"), a non-printable character,
+      # minimizes the chance of collisions with tag names or messages and remains
+      # safe to pass through Process.spawn and shell argument boundaries.
+      FIELD_DELIMITER = "\x1f"
+
+      # Delimiter for separating records (tags) in output
+      # Using the ASCII record separator (RS, 0x1E / "\x1e") to delimit complete tag records.
+      # This allows multi-line messages (which contain newlines) to be parsed correctly
+      # since we split by record separator first, then by field delimiter.
+      RECORD_DELIMITER = "\x1e"
+
+      # Number of fields expected in the parsed output
+      FIELD_COUNT = 8
+
+      # Format string for git tag --format
+      #
+      # Fields:
+      # - %(refname:short) - tag name
+      # - %(objectname) - SHA of the tag object (for annotated) or commit (for lightweight)
+      # - %(*objectname) - Dereferenced SHA (commit ID for annotated tags, empty for lightweight)
+      # - %(objecttype) - 'tag' for annotated tags, target object type (commit/tree/blob/etc.) for lightweight tags
+      # - %(taggername) - tagger name (empty for lightweight tags)
+      # - %(taggeremail) - tagger email (empty for lightweight tags)
+      # - %(taggerdate:iso8601-strict) - tagger date in strict ISO 8601 format
+      # - %(contents) - full tag message (can be multi-line)
+      #
+      # Each tag record is terminated by the RECORD_DELIMITER to allow multi-line messages.
+      FORMAT_STRING = [
+        '%(refname:short)',
+        '%(objectname)',
+        '%(*objectname)',
+        '%(objecttype)',
+        '%(taggername)',
+        '%(taggeremail)',
+        '%(taggerdate:iso8601-strict)',
+        '%(contents)'
+      ].join(FIELD_DELIMITER) + RECORD_DELIMITER
+
+      # Regex to parse successful deletion lines from stdout
+      # Matches: Deleted tag 'tagname' (was abc123)
+      DELETED_TAG_REGEX = /^Deleted tag '([^']+)'/
+
+      # Regex to parse error messages from stderr
+      # Matches: error: tag 'tagname' not found.
+      ERROR_TAG_REGEX = /^error: tag '([^']+)'(.*)$/
+
+      module_function
+
+      # Parse git tag --list output into TagInfo objects
+      #
+      # @example
+      #   TagParser.parse_list("v1.0.0\x1f...\x1e\n")
+      #   # => [#<Git::TagInfo name: "v1.0.0", ...>]
+      #
+      # @param stdout [String] output from git tag --list --format=...
+      # @return [Array<Git::TagInfo>] parsed tag information
+      #
+      # @raise [Git::UnexpectedResultError] if any record has unexpected format
+      #
+      def parse_list(stdout)
+        # Split by record separator
+        # Each record may have a leading newline from the previous record's %(contents) output
+        # Use lstrip to remove leading whitespace (which includes the newline) from each record
+        records = stdout.split(RECORD_DELIMITER).map(&:lstrip).reject(&:empty?)
+        records.map.with_index { |record, index| parse_tag_record(record, index, records) }
+      end
+
+      # Parse a single formatted tag record
+      #
+      # The record format is:
+      #   name<FS>sha<FS>deref<FS>objecttype<FS>tagger_name<FS>tagger_email<FS>tagger_date<FS>message
+      # where <FS> is the unit separator character ("\x1f").
+      #
+      # For lightweight tags, Git emits empty strings for the tagger fields and message;
+      # these are converted to nil by {#parse_optional_field} and {#parse_message}.
+      #
+      # @param record [String] a single tag record from git tag --format output
+      # @param index [Integer] record index for error reporting
+      # @param all_records [Array<String>] all output records for error messages
+      # @return [Git::TagInfo] tag info with all fields populated
+      #
+      # @raise [Git::UnexpectedResultError] if record format is unexpected
+      #
+      def parse_tag_record(record, index, all_records)
+        parts = record.split(FIELD_DELIMITER, FIELD_COUNT)
+
+        unless parts.length == FIELD_COUNT
+          raise Git::UnexpectedResultError, unexpected_tag_record_error(all_records, record, index)
+        end
+
+        build_tag_info(parts)
+      end
+
+      # Build a TagInfo object from parsed parts
+      #
+      # @param parts [Array<String>] the parsed format fields
+      # @return [Git::TagInfo]
+      #
+      # @note For annotated tags:
+      #   - oid = %(objectname) (the tag object's ID)
+      #   - target_oid = %(*objectname) (the dereferenced commit ID)
+      #
+      # @note For lightweight tags:
+      #   - oid = nil (lightweight tags are not objects)
+      #   - target_oid = %(objectname) (the commit ID)
+      #
+      def build_tag_info(parts)
+        oid, target_oid = resolve_oids(parts[3], parts[1], parts[2])
+        build_tag_info_object(parts, oid, target_oid)
+      end
+
+      def resolve_oids(objecttype, objectname, dereferenced)
+        objecttype == 'tag' ? [objectname, dereferenced] : [nil, objectname]
+      end
+
+      def build_tag_info_object(parts, oid, target_oid)
+        Git::TagInfo.new(
+          name: parts[0], oid: oid, target_oid: target_oid, objecttype: parts[3],
+          tagger_name: parse_optional_field(parts[4]), tagger_email: parse_optional_field(parts[5]),
+          tagger_date: parse_optional_field(parts[6]), message: parse_message(parts[3], parts[7])
+        )
+      end
+
+      # Parse an optional field, returning nil if empty
+      #
+      # @param value [String] the field value
+      # @return [String, nil] the value or nil if empty
+      #
+      def parse_optional_field(value)
+        value.empty? ? nil : value
+      end
+
+      # Parse message field, returning nil for lightweight tags or empty messages
+      # Strips trailing newlines that git adds to %(contents) output
+      #
+      # @param objecttype [String] the object type ('tag' or 'commit')
+      # @param message [String] the raw message field
+      # @return [String, nil] the message or nil
+      #
+      def parse_message(objecttype, message)
+        stripped = message.chomp
+        objecttype == 'tag' && !stripped.empty? ? stripped : nil
+      end
+
+      # Parse deleted tag names from stdout
+      #
+      # @example
+      #   TagParser.parse_deleted_tags("Deleted tag 'v1.0.0' (was abc123)\n")
+      #   # => ["v1.0.0"]
+      #
+      # @param stdout [String] command stdout
+      # @return [Array<String>] names of successfully deleted tags
+      #
+      def parse_deleted_tags(stdout)
+        stdout.scan(DELETED_TAG_REGEX).flatten
+      end
+
+      # Parse error messages from stderr into a map
+      #
+      # @example
+      #   TagParser.parse_error_messages("error: tag 'missing' not found.\n")
+      #   # => {"missing" => "error: tag 'missing' not found."}
+      #
+      # @param stderr [String] command stderr
+      # @return [Hash<String, String>] map of tag name to error message
+      #
+      def parse_error_messages(stderr)
+        stderr.each_line.with_object({}) do |line, hash|
+          match = line.match(ERROR_TAG_REGEX)
+          hash[match[1]] = line.strip if match
+        end
+      end
+
+      # Build the TagDeleteResult from parsed data
+      #
+      # @param requested_names [Array<String>] originally requested tag names
+      # @param existing_tags [Hash<String, Git::TagInfo>] tags that existed before delete
+      # @param deleted_names [Array<String>] names confirmed deleted in stdout
+      # @param error_map [Hash<String, String>] map of tag name to error message
+      # @return [Git::TagDeleteResult] the result object
+      #
+      def build_delete_result(requested_names, existing_tags, deleted_names, error_map)
+        deleted = deleted_names.filter_map { |name| existing_tags[name] }
+
+        not_deleted = (requested_names - deleted_names).map do |name|
+          error_message = error_map[name] || "tag '#{name}' could not be deleted"
+          Git::TagDeleteFailure.new(name: name, error_message: error_message)
+        end
+
+        Git::TagDeleteResult.new(deleted: deleted, not_deleted: not_deleted)
+      end
+
+      # Generate error message for unexpected tag record format
+      #
+      # @param records [Array<String>] all output records
+      # @param record [String] the problematic record
+      # @param index [Integer] the record index
+      # @return [String] formatted error message
+      #
+      def unexpected_tag_record_error(records, record, index)
+        format_str = FORMAT_STRING.gsub(FIELD_DELIMITER, '<FS>').gsub(RECORD_DELIMITER, '<RS>')
+        <<~ERROR
+          Unexpected record in output from `git tag --list --format=#{format_str}`, at index #{index}
+
+          Expected #{FIELD_COUNT} fields separated by '\\x1f' (unit separator), got #{record.split(FIELD_DELIMITER, -1).length}
+
+          Full output:
+            #{records.join("\n  ")}
+
+          Record at index #{index}:
+            "#{record}"
+        ERROR
+      end
+    end
+  end
+end

data/lib/git/remote.rb

@@ -1,39 +1,150 @@
 # frozen_string_literal: true
 
+require 'git/branch'
+require 'git/branch_info'
+
 module Git
   # A remote in a Git repository
+  #
+  # Remote objects provide access to remote metadata and operations like fetch,
+  # merge, and remove. They should be obtained via `Git::Repository#remote`,
+  # not constructed directly.
+  #
+  # @example Getting a remote
+  #   git = Git.open('.')
+  #   remote = git.remote('origin')
+  #   remote.fetch
+  #
+  # @api public
+  #
   class Remote
-    attr_accessor :name, :url, :fetch_opts
+    # The name of this remote (e.g. `'origin'`)
+    #
+    # @return [String] the remote name
+    #
+    attr_accessor :name
+
+    # The URL of this remote
+    #
+    # @return [String, nil] the remote URL
+    #
+    attr_accessor :url
 
+    # The fetch refspec for this remote
+    #
+    # @return [String, nil] the fetch options string
+    #
+    attr_accessor :fetch_opts
+
+    # Initialize a new Remote object
+    #
+    # @param base [Git::Repository] the git repository
+    #
+    # @param name [String] the remote name (e.g. `'origin'`)
+    #
+    # @note Use `Git::Repository#remote` instead of constructing directly
+    #
+    # @api private
+    #
     def initialize(base, name)
       @base = base
-      config = @base.lib.config_remote(name)
+      config = remote_repository.config_remote(name)
       @name = name
       @url = config['url']
       @fetch_opts = config['fetch']
     end
 
+    # Fetches from this remote
+    #
+    # @example Fetch from origin
+    #   git.remote('origin').fetch
+    #
+    # @param opts [Hash] fetch options (see `Git::Repository#fetch`)
+    #
+    # @return [String] git's stdout from the fetch
+    #
+    # @raise [Git::FailedError] if git exits with a non-zero exit status
+    #
     def fetch(opts = {})
-      @base.fetch(@name, opts)
+      remote_repository.fetch(@name, opts)
     end
 
-    # merge this remote locally
-    def merge(branch = @base.current_branch)
+    # Merges this remote into the given (or current) local branch
+    #
+    # @example Merge origin/main into the current branch
+    #   git.remote('origin').merge('main')
+    #
+    # @param branch [String] the local branch to merge into (defaults to current branch)
+    #
+    # @return [String] git's stdout from the merge
+    #
+    # @raise [Git::FailedError] if git exits with a non-zero exit status
+    #
+    def merge(branch = nil)
+      branch ||= remote_repository.current_branch
       remote_tracking_branch = "#{@name}/#{branch}"
-      @base.merge(remote_tracking_branch)
+      remote_repository.merge(remote_tracking_branch)
     end
 
-    def branch(branch = @base.current_branch)
+    # Returns a {Git::Branch} object for the given branch on this remote
+    #
+    # @example Get the remote-tracking branch object
+    #   git.remote('origin').branch('main')  #=> #<Git::Branch 'origin/main'>
+    #
+    # @param branch [String] the branch name on this remote (defaults to current branch)
+    #
+    # @return [Git::Branch] a branch object representing `<remote>/<branch>`
+    #
+    def branch(branch = nil)
+      branch ||= remote_repository.current_branch
       remote_tracking_branch = "#{@name}/#{branch}"
-      Git::Branch.new(@base, remote_tracking_branch)
+      branch_info = build_branch_info(remote_tracking_branch)
+      Git::Branch.new(@base, branch_info)
     end
 
+    # Removes this remote from the repository
+    #
+    # @example Remove the upstream remote
+    #   git.remote('upstream').remove
+    #
+    # @return [Git::CommandLineResult] the result of `git remote remove`
+    #
+    # @raise [Git::FailedError] if git exits with a non-zero exit status
+    #
     def remove
-      @base.lib.remote_remove(@name)
+      remote_repository.remote_remove(@name)
     end
 
+    # Returns the name of this remote as a string
+    #
+    # @example Get the remote name as a string
+    #   git.remote('origin').to_s  #=> 'origin'
+    #
+    # @return [String] the remote name
+    #
     def to_s
       @name
     end
+
+    private
+
+    # @return [Git::Repository]
+    #
+    # @api private
+    #
+    def remote_repository
+      @base
+    end
+
+    def build_branch_info(refname)
+      Git::BranchInfo.new(
+        refname: refname,
+        target_oid: nil,
+        current: false,
+        worktree: false,
+        symref: nil,
+        upstream: nil
+      )
+    end
   end
 end