git 4.3.2 → 5.0.0.beta.2

data/lib/git/parsers/fsck.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require 'git/fsck_object'
+require 'git/fsck_result'
+
+module Git
+  module Parsers
+    # Parser for git fsck command output
+    #
+    # Handles parsing of `git fsck` output into structured data objects
+    # for dangling, missing, unreachable objects, warnings, roots, and tagged objects.
+    #
+    # ## Design Note: Namespace Organization
+    #
+    # This parser creates and returns {Git::FsckObject} and {Git::FsckResult}
+    # 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
+    # - **Result classes are public API** - returned by commands and used
+    #   throughout the codebase
+    # - **FsckObject and FsckResult represent operation outcomes** - they describe
+    #   repository integrity status, not parsing details
+    #
+    # Keeping these classes at `Git::` improves discoverability and correctly
+    # reflects their role as public types rather than parser internals.
+    #
+    # @api private
+    #
+    module Fsck
+      # Pattern matcher for dangling/missing/unreachable object lines
+      # Matches lines like:
+      #   dangling commit abc123...
+      #   missing blob def456...
+      #   unreachable tree 789abc... (name)
+      OBJECT_PATTERN = /\A(dangling|missing|unreachable) (\w+) ([0-9a-f]{40})(?: \((.+)\))?\z/
+
+      # Pattern matcher for warning lines
+      # Matches lines like:
+      #   warning in commit abc123...: message here
+      WARNING_PATTERN = /\Awarning in (\w+) ([0-9a-f]{40}): (.+)\z/
+
+      # Pattern matcher for root commit lines
+      # Matches lines like:
+      #   root abc123...
+      ROOT_PATTERN = /\Aroot ([0-9a-f]{40})\z/
+
+      # Pattern matcher for tagged object lines
+      # Matches lines like:
+      #   tagged commit abc123... (tagname) in def456...
+      TAGGED_PATTERN = /\Atagged (\w+) ([0-9a-f]{40}) \((.+)\) in ([0-9a-f]{40})\z/
+
+      module_function
+
+      # Parse git fsck output into a FsckResult object
+      #
+      # @example
+      #   FsckParser.parse("dangling commit abc123...\nmissing blob def456...\n")
+      #   # => #<Git::FsckResult dangling: [...], missing: [...]>
+      #
+      # @param stdout [String] output from git fsck command
+      # @return [Git::FsckResult] the parsed result
+      #
+      def parse(stdout)
+        result = { dangling: [], missing: [], unreachable: [], warnings: [], root: [], tagged: [] }
+        stdout.each_line { |line| parse_line(line.strip, result) }
+        Git::FsckResult.new(**result)
+      end
+
+      # Parse a single line of fsck output
+      #
+      # @param line [String] a line of output
+      # @param result [Hash] the result hash to populate
+      # @return [Boolean] true if the line was parsed
+      #
+      def parse_line(line, result)
+        parse_object_line(line, result) ||
+          parse_warning_line(line, result) ||
+          parse_root_line(line, result) ||
+          parse_tagged_line(line, result)
+      end
+
+      # Parse a dangling/missing/unreachable object line
+      #
+      # @param line [String] a line of output
+      # @param result [Hash] the result hash to populate
+      # @return [Boolean] true if the line was parsed
+      #
+      def parse_object_line(line, result)
+        return unless (match = OBJECT_PATTERN.match(line))
+
+        result[match[1].to_sym] << Git::FsckObject.new(type: match[2].to_sym, oid: match[3], name: match[4])
+      end
+
+      # Parse a warning line
+      #
+      # @param line [String] a line of output
+      # @param result [Hash] the result hash to populate
+      # @return [Boolean] true if the line was parsed
+      #
+      def parse_warning_line(line, result)
+        return unless (match = WARNING_PATTERN.match(line))
+
+        result[:warnings] << Git::FsckObject.new(type: match[1].to_sym, oid: match[2], message: match[3])
+      end
+
+      # Parse a root line
+      #
+      # @param line [String] a line of output
+      # @param result [Hash] the result hash to populate
+      # @return [Boolean] true if the line was parsed
+      #
+      def parse_root_line(line, result)
+        return unless (match = ROOT_PATTERN.match(line))
+
+        result[:root] << Git::FsckObject.new(type: :commit, oid: match[1])
+      end
+
+      # Parse a tagged line
+      #
+      # @param line [String] a line of output
+      # @param result [Hash] the result hash to populate
+      # @return [Boolean] true if the line was parsed
+      #
+      def parse_tagged_line(line, result)
+        return unless (match = TAGGED_PATTERN.match(line))
+
+        result[:tagged] << Git::FsckObject.new(type: match[1].to_sym, oid: match[2], name: match[3])
+      end
+    end
+  end
+end

data/lib/git/parsers/grep.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Git
+  module Parsers
+    # Parser for `git grep` output
+    #
+    # Provides a class method that transforms raw `git grep --null` output into a
+    # structured Hash consumed by the `Git::Repository::ObjectOperations` facade.
+    #
+    # This parser is a pure text transformer with no exit-status logic. The
+    # calling facade is responsible for interpreting the command's exit status
+    # before delegating output parsing to this class.
+    #
+    # @api private
+    #
+    module Grep
+      module_function
+
+      # Parse `git grep --line-number --null --no-color` output into a match hash
+      #
+      # With `--null`, git separates the path and line number fields with NUL
+      # bytes: `treeish:filename\0linenum\0text\n`. This keeps filenames that
+      # contain `:<digits>:` from being confused with the line-number delimiter.
+      #
+      # @param output [String] raw output from `git grep --null --line-number`
+      #
+      # @return [Hash<String, Array<Array(Integer, String)>>] hash mapping
+      #   `"treeish:filename"` keys to arrays of `[line_number, text]` pairs
+      #
+      # @api private
+      #
+      def parse(output)
+        output.each_line.with_object(Hash.new { |h, k| h[k] = [] }) do |line, hsh|
+          filename, line_num, text = line.chomp.split("\0", 3)
+          next unless text && line_num&.match?(/\A\d+\z/)
+
+          hsh[filename] << [line_num.to_i, text]
+        end
+      end
+    end
+  end
+end

data/lib/git/parsers/ls_remote.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Git
+  module Parsers
+    # Parser for `git ls-remote` command output
+    #
+    # @api private
+    #
+    module LsRemote
+      module_function
+
+      # Parse `git ls-remote` stdout lines into a structured Hash
+      #
+      # @param lines [Array<String>] the individual stdout lines
+      #
+      # @return [Hash{String => Hash}] a map of ref type to ref data
+      #
+      #   The structure differs by key:
+      #
+      #   - `"head"` maps directly to `{ ref: String, sha: String }`
+      #   - Other keys (e.g. `"branches"`, `"tags"`) map to
+      #     `{ name => { ref: String, sha: String } }`
+      #
+      def parse_output(lines)
+        lines.each_with_object(Hash.new { |h, k| h[k] = {} }) do |line, hsh|
+          type, name, value = parse_line(line)
+          if name
+            hsh[type][name] = value
+          else
+            hsh[type].update(value)
+          end
+        end
+      end
+
+      # Parse a single `git ls-remote` output line
+      #
+      # @param line [String] a single line from ls-remote stdout
+      #
+      # @return [Array(String, String|nil, Hash)] `[type, name, value]` where
+      #   `value` is `{ ref: String, sha: String }`
+      #
+      # @raise [Git::UnexpectedResultError] if the line is not in `<sha>\t<ref>` format
+      #
+      def parse_line(line)
+        unless line.include?("\t") && line.match?(/\A[0-9a-f]{4,}\t/)
+          raise Git::UnexpectedResultError, "Unexpected ls-remote output line: #{line.inspect}"
+        end
+
+        sha, info = line.split("\t", 2)
+        ref, type, name = info.split('/', 3)
+
+        type ||= 'head'
+        type = 'branches' if type == 'heads'
+
+        value = { ref: ref, sha: sha }
+
+        [type, name, value]
+      end
+
+      # Parse `git ls-remote --symref <repo> HEAD` output into a branch name
+      #
+      # @param output [String] command stdout
+      #
+      # @return [String] the default branch name
+      #
+      # @raise [Git::UnexpectedResultError] when the branch cannot be determined
+      #
+      def parse_default_branch(output)
+        match_data = output.match(%r{^ref: refs/remotes/[^/]+/(?<default_branch>[^\t]+)\t})
+        return match_data[:default_branch] if match_data
+
+        match_data = output.match(%r{^ref: refs/heads/(?<default_branch>[^\t]+)\tHEAD$})
+        return match_data[:default_branch] if match_data
+
+        raise Git::UnexpectedResultError, 'Unable to determine the default branch'
+      end
+    end
+  end
+end

data/lib/git/parsers/ls_tree.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require 'git/escaped_path'
+
+module Git
+  module Parsers
+    # Parser for `git ls-tree` output
+    #
+    # Provides a class method that transforms raw `git ls-tree` output into a
+    # structured Hash consumed by the `Git::Repository::ObjectOperations` facade.
+    #
+    # @api private
+    #
+    module LsTree
+      module_function
+
+      # Parse `git ls-tree` output into a type-keyed hash of entries
+      #
+      # Each line of output is expected in the format produced by
+      # `git ls-tree`: `<mode> <type> <sha>\t<file>`.
+      #
+      # @param output [String] raw stdout from `git ls-tree`
+      #
+      # @return [Hash<String, Hash<String, Hash>>] hash keyed by object type
+      #   (`'blob'`, `'tree'`, `'commit'`), then by filename, holding
+      #   `:mode` and `:sha` values
+      #
+      # @api private
+      #
+      def parse(output)
+        data = { 'blob' => {}, 'tree' => {}, 'commit' => {} }
+        output.split("\n").each do |line|
+          info, filenm = line.split("\t", 2)
+          filenm = unescape_path(filenm) if filenm
+          mode, type, entry_sha = info.split
+          data[type][filenm] = { mode: mode, sha: entry_sha }
+        end
+        data
+      end
+
+      # Converts a git-quoted path back to its original form
+      #
+      # @param path [String] the path, possibly git-quoted
+      #
+      # @return [String] the unquoted path
+      #
+      # @api private
+      #
+      def unescape_path(path)
+        if path.start_with?('"') && path.end_with?('"')
+          Git::EscapedPath.new(path[1..-2]).unescape
+        else
+          path
+        end
+      end
+    end
+  end
+end

data/lib/git/parsers/stash.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+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)
+      # %cn = committer name
+      # %ce = committer email
+      # %cI = committer date (ISO 8601 format)
+      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
+        OID = 0
+        SHORT_OID = 1
+        REFLOG = 2
+        MESSAGE = 3
+        AUTHOR_NAME = 4
+        AUTHOR_EMAIL = 5
+        AUTHOR_DATE = 6
+        COMMITTER_NAME = 7
+        COMMITTER_EMAIL = 8
+        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_attrs(parts)).merge(committer_attrs(parts))
+      end
+
+      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
+
+      def author_attrs(parts)
+        {
+          author_name: parts[Fields::AUTHOR_NAME], author_email: parts[Fields::AUTHOR_EMAIL],
+          author_date: parts[Fields::AUTHOR_DATE]
+        }
+      end
+
+      def committer_attrs(parts)
+        {
+          committer_name: parts[Fields::COMMITTER_NAME], committer_email: parts[Fields::COMMITTER_EMAIL],
+          committer_date: parts[Fields::COMMITTER_DATE]
+        }
+      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