git 1.19.1 → 5.5.0

data/lib/git/parsers/stash.rb

@@ -0,0 +1,292 @@
+# frozen_string_literal: true
+
+require 'time'
+
+require 'git/author_info'
+require 'git/stash_info'
+
+module Git
+  module Parsers
+    # Parser for git stash command output
+    #
+    # Handles parsing of `git stash list` output into structured data objects.
+    #
+    # @note Known limitation: If a stash message contains the field separator
+    #   character (\x1f, ASCII unit separator), parsing will fail or produce
+    #   incorrect results. This is extremely rare in practice since \x1f is a
+    #   non-printable control character.
+    #
+    # ## Design Note: Namespace Organization
+    #
+    # This parser creates and returns {Git::StashInfo} 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 classes are public API** - returned by commands and used throughout
+    #   the codebase
+    # - **Info classes are domain entities** - represent core git concepts
+    #   (stashes as data)
+    #
+    # Keeping Info classes at `Git::` improves discoverability and correctly
+    # reflects their role as public types rather than parser internals.
+    #
+    # @api private
+    #
+    module Stash
+      # Field separator used in custom format output
+      # Using a non-printable unit separator (US, 0x1F) to avoid collisions with
+      # stash messages and author/committer fields, while still working with
+      # Process.spawn (which doesn't allow NUL bytes in arguments)
+      FIELD_SEPARATOR = "\x1f"
+
+      # Custom format for git stash list that extracts all available metadata
+      # %H  = full commit SHA
+      # %h  = abbreviated commit SHA
+      # %gd = reflog selector (stash@\\{n})
+      # %gs = reflog subject (the stash message)
+      # %an = author name
+      # %ae = author email
+      # %aI = author date (ISO 8601 format, parsed into a Time)
+      # %cn = committer name
+      # %ce = committer email
+      # %cI = committer date (ISO 8601 format, parsed into a Time)
+      STASH_FORMAT = [
+        '%H',  # 0: full SHA
+        '%h',  # 1: short SHA
+        '%gd', # 2: reflog selector
+        '%gs', # 3: reflog subject (message)
+        '%an', # 4: author name
+        '%ae', # 5: author email
+        '%aI', # 6: author date
+        '%cn', # 7: committer name
+        '%ce', # 8: committer email
+        '%cI'  # 9: committer date
+      ].join(FIELD_SEPARATOR)
+
+      # Number of fields expected in the parsed output
+      FIELD_COUNT = 10
+
+      # Field indices for parsed output
+      module Fields
+        # Index of the full object ID (`%H`) field
+        OID = 0
+
+        # Index of the abbreviated object ID (`%h`) field
+        SHORT_OID = 1
+
+        # Index of the reflog selector (`%gd`) field
+        REFLOG = 2
+
+        # Index of the reflog subject (`%gs`) field
+        MESSAGE = 3
+
+        # Index of the author name (`%an`) field
+        AUTHOR_NAME = 4
+
+        # Index of the author email (`%ae`) field
+        AUTHOR_EMAIL = 5
+
+        # Index of the author date (`%aI`) field
+        AUTHOR_DATE = 6
+
+        # Index of the committer name (`%cn`) field
+        COMMITTER_NAME = 7
+
+        # Index of the committer email (`%ce`) field
+        COMMITTER_EMAIL = 8
+
+        # Index of the committer date (`%cI`) field
+        COMMITTER_DATE = 9
+      end
+
+      # Pattern to extract branch from standard stash messages
+      # Matches "WIP on <branch>:" or "On <branch>:" at the start
+      BRANCH_PATTERN = /^(?:WIP on|On)\s+([^:]+):/
+
+      module_function
+
+      # Parse git stash list output into StashInfo objects
+      #
+      # @example
+      #   StashParser.parse_list("abc123\x1fabc\x1fstash@\\{0}\x1fWIP on main: msg\x1f...\n")
+      #   # => [#<Git::StashInfo index: 0, ...>]
+      #
+      # @param stdout [String] output from git stash list --format=...
+      #
+      # @return [Array<Git::StashInfo>] parsed stash information
+      #
+      # @raise [Git::UnexpectedResultError] if stash output cannot be parsed
+      #
+      def parse_list(stdout)
+        lines = stdout.split("\n")
+        lines.each_with_index.map { |line, idx| parse_stash_line(line, idx, lines) }
+      end
+
+      # Parse a single stash list line into a StashInfo object
+      #
+      # @param line [String] a line from git stash list output (custom format)
+      #
+      # @param expected_index [Integer] the expected stash index for validation
+      #
+      # @param all_lines [Array<String>] all output lines (for error messages)
+      #
+      # @return [Git::StashInfo] parsed stash info
+      #
+      # @raise [Git::UnexpectedResultError] if line format is unexpected
+      #
+      def parse_stash_line(line, expected_index, all_lines)
+        parts = line.split(FIELD_SEPARATOR, FIELD_COUNT)
+        return build_stash_info(parts, expected_index) if parts.length == FIELD_COUNT
+
+        raise Git::UnexpectedResultError, unexpected_stash_line_error(all_lines, line, expected_index)
+      end
+
+      # Build a StashInfo from parsed format parts
+      #
+      # @param parts [Array<String>] the parsed format fields
+      #
+      # @param expected_index [Integer] fallback index if not parseable from reflog
+      #
+      # @return [Git::StashInfo]
+      #
+      def build_stash_info(parts, expected_index)
+        index = extract_index(parts[Fields::REFLOG]) || expected_index
+
+        Git::StashInfo.new(**stash_info_attrs(parts, index))
+      end
+
+      # Build StashInfo attributes hash from parsed parts
+      #
+      # @param parts [Array<String>] the parsed format fields
+      #
+      # @param index [Integer] the resolved stash index
+      #
+      # @return [Hash] attributes for StashInfo.new
+      #
+      def stash_info_attrs(parts, index)
+        core_attrs(parts, index).merge(author: author_info(parts), committer: committer_info(parts))
+      end
+
+      # Build core StashInfo attributes from parsed fields
+      #
+      # @param parts [Array<String>] the parsed format fields
+      #
+      # @param index [Integer] the resolved stash index
+      #
+      # @return [Hash<Symbol, Object>] core attributes for StashInfo.new
+      #
+      def core_attrs(parts, index)
+        {
+          index: index, name: parts[Fields::REFLOG], oid: parts[Fields::OID],
+          short_oid: parts[Fields::SHORT_OID], branch: extract_branch(parts[Fields::MESSAGE]),
+          message: parts[Fields::MESSAGE]
+        }
+      end
+
+      # Build the author identity from the parsed fields
+      #
+      # @param parts [Array<String>] the parsed format fields
+      #
+      # @return [Git::AuthorInfo] the stash author; its `date` is a `Time`
+      #
+      def author_info(parts)
+        build_author_info(parts[Fields::AUTHOR_NAME], parts[Fields::AUTHOR_EMAIL], parts[Fields::AUTHOR_DATE])
+      end
+
+      # Build the committer identity from the parsed fields
+      #
+      # @param parts [Array<String>] the parsed format fields
+      #
+      # @return [Git::AuthorInfo] the stash committer; its `date` is a `Time`
+      #
+      def committer_info(parts)
+        build_author_info(
+          parts[Fields::COMMITTER_NAME], parts[Fields::COMMITTER_EMAIL], parts[Fields::COMMITTER_DATE]
+        )
+      end
+
+      # Build a Git::AuthorInfo from identity fields
+      #
+      # The date is parsed with `Time.iso8601`, so the UTC offset git emits for
+      # `%aI` and `%cI` is preserved in the resulting `Time`.
+      #
+      # @param name [String] the `%an` or `%cn` field
+      #
+      # @param email [String] the `%ae` or `%ce` field
+      #
+      # @param date [String] the `%aI` or `%cI` field in ISO 8601 format
+      #
+      # @return [Git::AuthorInfo] the identity with `date` as a `Time`
+      #
+      # @raise [Git::UnexpectedResultError] if the date is not a valid ISO 8601 date
+      #
+      def build_author_info(name, email, date)
+        Git::AuthorInfo.new(name: name, email: email, date: parse_date(date))
+      end
+
+      # Parse a `%aI` or `%cI` field into a Time
+      #
+      # @param date [String] the date field in ISO 8601 format
+      #
+      # @return [Time] the parsed time, preserving the UTC offset
+      #
+      # @raise [Git::UnexpectedResultError] if the field is not a valid ISO 8601 date
+      #
+      def parse_date(date)
+        Time.iso8601(date)
+      rescue ArgumentError => e
+        raise Git::UnexpectedResultError,
+              "Unexpected date #{date.inspect} in output from `git stash list`: #{e.message}"
+      end
+
+      # Extract the stash index from a reflog selector
+      #
+      # @param reflog_selector [String] e.g., "stash@\\{0}"
+      #
+      # @return [Integer, nil] the index or nil if not found
+      #
+      def extract_index(reflog_selector)
+        match = reflog_selector&.match(/stash@\{(\d+)\}/)
+        match ? match[1].to_i : nil
+      end
+
+      # Extract the branch name from a stash message
+      #
+      # @param message [String] the stash message
+      #
+      # @return [String, nil] the branch name or nil for custom messages
+      #
+      def extract_branch(message)
+        match = BRANCH_PATTERN.match(message)
+        match ? match[1] : nil
+      end
+
+      # Generate error message for unexpected stash line format
+      #
+      # @param lines [Array<String>] all output lines
+      #
+      # @param line [String] the problematic line
+      #
+      # @param index [Integer] the stash index
+      #
+      # @return [String] formatted error message
+      #
+      def unexpected_stash_line_error(lines, line, index)
+        format_str = STASH_FORMAT.gsub(FIELD_SEPARATOR, '<FS>')
+        <<~ERROR
+          Unexpected line in output from `git stash list --format=#{format_str}`, at index #{index}
+
+          Expected #{FIELD_COUNT} fields separated by '\\x1f' (unit separator), got #{line.split(FIELD_SEPARATOR, -1).length}
+
+          Full output:
+            #{lines.join("\n  ")}
+
+          Line at index #{index}:
+            "#{line}"
+        ERROR
+      end
+    end
+  end
+end

data/lib/git/parsers/status.rb

@@ -0,0 +1,251 @@
+# frozen_string_literal: true
+
+require 'git/errors'
+require 'git/status_file_info'
+
+module Git
+  module Parsers
+    # Parser for `git status --porcelain=v2 -z` output
+    #
+    # Builds one {Git::StatusFileInfo} per entry. With `-z` every entry is
+    # NUL-terminated and paths are emitted verbatim (no quoting), so a path may
+    # contain spaces but never a NUL. The original path of a rename or copy
+    # entry is the NUL-terminated token that follows the entry.
+    #
+    # Every entry type of the porcelain v2 format is handled: `1` (ordinary),
+    # `2` (rename or copy), `u` (unmerged), `?` (untracked), and `!` (ignored).
+    # `#` header lines, emitted with `--branch` or `--show-stash`, are skipped.
+    #
+    # {Git::StatusFileInfo} lives at the top-level `Git::` namespace rather than
+    # within `Git::Parsers::` because it is public API returned to callers,
+    # while this parser is infrastructure.
+    #
+    # @example Parse the output of `git status --porcelain=v2 -z`
+    #   Git::Parsers::Status.parse("? new.txt\0")
+    #   #=> [#<data Git::StatusFileInfo path="new.txt", index_status="?", ...>]
+    #
+    # @see https://git-scm.com/docs/git-status#_porcelain_format_version_2
+    #
+    # @api private
+    #
+    module Status
+      # Separator between entries (and between a rename entry and its original path)
+      ENTRY_SEPARATOR = "\0"
+
+      # Separator between the fields of one entry
+      FIELD_SEPARATOR = / /
+
+      # First character of an ordinary (changed, added, or deleted) entry
+      ORDINARY_ENTRY = '1'
+
+      # First character of a rename or copy entry
+      RENAMED_ENTRY = '2'
+
+      # First character of an unmerged entry
+      UNMERGED_ENTRY = 'u'
+
+      # First character of an untracked entry
+      UNTRACKED_ENTRY = '?'
+
+      # First character of an ignored entry
+      IGNORED_ENTRY = '!'
+
+      # First character of a header line
+      HEADER_LINE = '#'
+
+      # Field count of an ordinary entry: `1 <XY> <sub> <mH> <mI> <mW> <hH> <hI> <path>`
+      ORDINARY_FIELD_COUNT = 9
+
+      # Field count of a rename or copy entry, which adds `<X><score>` before the path
+      RENAMED_FIELD_COUNT = 10
+
+      # Field count of an unmerged entry: `u <XY> <sub> <m1> <m2> <m3> <mW> <h1> <h2> <h3> <path>`
+      UNMERGED_FIELD_COUNT = 11
+
+      # Field count of an untracked or ignored entry: `? <path>` or `! <path>`
+      PATH_ONLY_FIELD_COUNT = 2
+
+      # Every {Git::StatusFileInfo} member set to `nil`, for entries that lack a field
+      #
+      # @return [Hash{Symbol => nil}]
+      #
+      EMPTY_MEMBERS = Git::StatusFileInfo.members.to_h { |member| [member, nil] }.freeze
+
+      module_function
+
+      # Parse `git status --porcelain=v2 -z` output into StatusFileInfo objects
+      #
+      # @example Parse two entries
+      #   Git::Parsers::Status.parse(
+      #     "1 .M N... 100644 100644 100644 #{sha} #{sha} lib/foo.rb\0? new.txt\0"
+      #   ).map(&:path) #=> ["lib/foo.rb", "new.txt"]
+      #
+      # @param stdout [String] the NUL-separated output of `git status --porcelain=v2 -z`
+      #
+      # @return [Array<Git::StatusFileInfo>] one entry per reported path, in git's order
+      #
+      # @raise [Git::UnexpectedResultError] if an entry does not match the porcelain v2 format
+      #
+      def parse(stdout)
+        tokens = stdout.split(ENTRY_SEPARATOR)
+        files = []
+        until tokens.empty?
+          entry = tokens.shift
+          files << parse_entry(entry, tokens) unless entry.start_with?(HEADER_LINE)
+        end
+        files
+      end
+
+      # Parse one entry, consuming its original path from `tokens` for renames and copies
+      #
+      # @param entry [String] the entry line without its NUL terminator
+      #
+      # @param tokens [Array<String>] the entries that follow; a rename or copy
+      #   entry's original path is shifted off the front
+      #
+      # @return [Git::StatusFileInfo] the parsed entry
+      #
+      # @raise [Git::UnexpectedResultError] if the entry type is not recognized
+      #
+      def parse_entry(entry, tokens)
+        case entry[0]
+        when ORDINARY_ENTRY then parse_ordinary(entry)
+        when RENAMED_ENTRY then parse_renamed(entry, tokens.shift)
+        when UNMERGED_ENTRY then parse_unmerged(entry)
+        when UNTRACKED_ENTRY, IGNORED_ENTRY then parse_path_only(entry)
+        else raise Git::UnexpectedResultError, unexpected_entry_error(entry)
+        end
+      end
+
+      # Parse an ordinary (`1`) entry
+      #
+      # @param entry [String] the entry line
+      #
+      # @return [Git::StatusFileInfo] the parsed entry
+      #
+      # @raise [Git::UnexpectedResultError] if the entry does not have nine fields
+      #
+      def parse_ordinary(entry)
+        _type, xy, submodule, mode_head, mode_index, mode_worktree, sha_head, sha_index, path =
+          split_fields(entry, ORDINARY_FIELD_COUNT)
+        build_file_info(xy, path:, submodule:, mode_head:, mode_index:, mode_worktree:, sha_head:, sha_index:)
+      end
+
+      # Parse a rename or copy (`2`) entry
+      #
+      # @param entry [String] the entry line
+      #
+      # @param original_path [String, nil] the NUL-terminated token that followed
+      #   the entry, or `nil` when the output ended
+      #
+      # @return [Git::StatusFileInfo] the parsed entry
+      #
+      # @raise [Git::UnexpectedResultError] if the entry does not have ten fields
+      #   or the original path is missing
+      #
+      def parse_renamed(entry, original_path)
+        _type, xy, submodule, mode_head, mode_index, mode_worktree, sha_head, sha_index, score, path =
+          split_fields(entry, RENAMED_FIELD_COUNT)
+        raise Git::UnexpectedResultError, unexpected_entry_error(entry) if original_path.nil?
+
+        build_file_info(
+          xy,
+          path:, submodule:, mode_head:, mode_index:, mode_worktree:, sha_head:, sha_index:,
+          original_path:, rename_score: score[1..].to_i
+        )
+      end
+
+      # Parse an unmerged (`u`) entry
+      #
+      # @param entry [String] the entry line
+      #
+      # @return [Git::StatusFileInfo] the parsed entry with its stage data in
+      #   `unmerged_stages`
+      #
+      # @raise [Git::UnexpectedResultError] if the entry does not have eleven fields
+      #
+      def parse_unmerged(entry)
+        _type, xy, submodule, mode1, mode2, mode3, mode_worktree, sha1, sha2, sha3, path =
+          split_fields(entry, UNMERGED_FIELD_COUNT)
+        stages = unmerged_stages([mode1, mode2, mode3], [sha1, sha2, sha3])
+        build_file_info(xy, path:, submodule:, mode_worktree:, unmerged_stages: stages)
+      end
+
+      # Parse an untracked (`?`) or ignored (`!`) entry
+      #
+      # The entry's single status character is used for both status positions,
+      # matching the `??` and `!!` codes of the short format.
+      #
+      # @param entry [String] the entry line
+      #
+      # @return [Git::StatusFileInfo] the parsed entry with `nil` metadata
+      #
+      # @raise [Git::UnexpectedResultError] if the entry does not have two fields
+      #
+      def parse_path_only(entry)
+        type, path = split_fields(entry, PATH_ONLY_FIELD_COUNT)
+        build_file_info(type * 2, path: path)
+      end
+
+      # Split an entry into exactly `count` fields, the last of which is the path
+      #
+      # The path may contain spaces, so the split is limited to `count` fields.
+      #
+      # @param entry [String] the entry line
+      #
+      # @param count [Integer] the number of fields the entry type has
+      #
+      # @return [Array<String>] the fields
+      #
+      # @raise [Git::UnexpectedResultError] if the entry has fewer fields
+      #
+      def split_fields(entry, count)
+        fields = entry.split(FIELD_SEPARATOR, count)
+        return fields if fields.length == count
+
+        raise Git::UnexpectedResultError, unexpected_entry_error(entry)
+      end
+
+      # Build the frozen stage hash of an unmerged entry
+      #
+      # @param modes [Array<String>] the stage 1, 2, and 3 modes
+      #
+      # @param shas [Array<String>] the stage 1, 2, and 3 object names
+      #
+      # @return [Hash{Integer => Hash{Symbol => String}}] frozen `\\{ mode:, sha: }`
+      #   hashes keyed by stage number
+      #
+      def unmerged_stages(modes, shas)
+        modes.zip(shas).each_with_index.to_h do |(mode, sha), index|
+          [index + 1, { mode: mode, sha: sha }.freeze]
+        end.freeze
+      end
+
+      # Build a {Git::StatusFileInfo}, defaulting every member not given to `nil`
+      #
+      # @param statuses [String] the two status characters, `X` then `Y`
+      #
+      # @param members [Hash{Symbol => Object}] the members that the entry provides
+      #
+      # @option members [String] :path the repository-relative path
+      #
+      # @return [Git::StatusFileInfo] the value object
+      #
+      def build_file_info(statuses, **members)
+        Git::StatusFileInfo.new(
+          **EMPTY_MEMBERS, index_status: statuses[0], worktree_status: statuses[1], **members
+        )
+      end
+
+      # Generate the error message for an entry that does not match the format
+      #
+      # @param entry [String] the offending entry line
+      #
+      # @return [String] the message
+      #
+      def unexpected_entry_error(entry)
+        "Unexpected entry in output from `git status --porcelain=v2 -z`: #{entry.inspect}"
+      end
+    end
+  end
+end