feat(gitparse): track ref sources

'Hidden' refs, such as 'refs/pull/1004/head' may cause confusion if reported upon. GitHub, for example, will display a banner saying that the commit doesn't belong to the repository.
This parse the output of 'git log --source' and converts it to a human-readable format, IF the ref is 'hidden'.

hack/snifftest/main.go

@@ -197,15 +197,16 @@ func main() {
 					SkipBinaries: true,
 					SkipArchives: false,
 					Concurrency:  runtime.NumCPU(),
-					SourceMetadataFunc: func(file, email, commit, timestamp, repository string, line int64) *source_metadatapb.MetaData {
+					SourceMetadataFunc: func(repository, commit, ref, email, timestamp, file string, line int64) *source_metadatapb.MetaData {
 						return &source_metadatapb.MetaData{
 							Data: &source_metadatapb.MetaData_Git{
 								Git: &source_metadatapb.Git{
+									Repository: repository,
 									Commit:     commit,
-									File:       file,
+									CommitRef:  ref,
 									Email:      email,
-									Repository: repository,
 									Timestamp:  timestamp,
+									File:       file,
 								},
 							},
 						}

pkg/gitparse/gitparse.go

@@ -108,7 +108,9 @@ func (d *Diff) finalize() error { return d.contentWriter.CloseForWriting() }
 
 // Commit contains commit header info and diffs.
 type Commit struct {
-	Hash      string
+	Hash string
+	// The source of a commit, if it doesn't exist in the repository's history.
+	Source    string
 	Author    string
 	Committer string
 	Date      time.Time
@@ -230,13 +232,16 @@ func (c *Parser) RepoPath(ctx context.Context, source string, head string, abbre
 		"--date=format:%a %b %d %H:%M:%S %Y %z",
 		"--pretty=fuller", // https://git-scm.com/docs/git-log#_pretty_formats
 		"--notes",         // https://git-scm.com/docs/git-log#Documentation/git-log.txt---notesltrefgt
+		"--source",        // https://git-scm.com/docs/git-log#Documentation/git-log.txt---source
 	}
 	if abbreviatedLog {
+		// https://git-scm.com/docs/git-log#Documentation/git-log.txt---diff-filterACDMRTUXB82308203
 		args = append(args, "--diff-filter=AM")
 	}
 	if head != "" {
 		args = append(args, head)
 	} else {
+		// https://git-scm.com/docs/git-log#Documentation/git-log.txt---all
 		args = append(args, "--all")
 	}
 	for _, glob := range excludedGlobs {
@@ -323,10 +328,9 @@ func (c *Parser) FromReader(ctx context.Context, stdOut io.Reader, diffChan chan
 	outReader := bufio.NewReader(stdOut)
 	var (
 		currentCommit *Commit
-
-		totalLogSize int
+		totalLogSize  int
+		latestState   = Initial
 	)
-	var latestState = Initial
 
 	diff := func(c *Commit, opts ...diffOption) *Diff {
 		opts = append(opts, withCustomContentWriter(bufferwriter.New()))
@@ -386,10 +390,18 @@ func (c *Parser) FromReader(ctx context.Context, stdOut io.Reader, diffChan chan
 			// Create a new currentDiff and currentCommit
 			currentCommit = &Commit{Message: strings.Builder{}}
 			currentDiff = diff(currentCommit)
-			// Check that the commit line contains a hash and set it.
-			if len(line) >= 47 {
-				currentCommit.Hash = string(line[7:47])
+
+			hash, ref := parseCommitLine(line)
+			if hash == nil || ref == nil {
+				ctx.Logger().Error(
+					fmt.Errorf(`expected line to match 'commit <hash> <ref>', got "%s"`, line),
+					"Failed to parse CommitLine")
+				latestState = ParseFailure
+				continue
 			}
+
+			currentCommit.Hash = string(hash)
+			currentCommit.Source = parseSourceRef(ref)
 		case isMergeLine(isStaged, latestState, line):
 			latestState = MergeLine
 		case isAuthorLine(isStaged, latestState, line):
@@ -605,6 +617,49 @@ func isCommitLine(isStaged bool, latestState ParseState, line []byte) bool {
 	return false
 }
 
+func parseCommitLine(line []byte) (hash []byte, ref []byte) {
+	// Check that the commit line contains a 40-character hash and set it.
+	// `commit e5575cd6f2d21d3a1a604287c7bf4a7eab2266e0\n`
+	if len(line) >= 47 {
+		hash = line[7:47]
+	}
+
+	// Check if the commit line includes branch references.
+	// `commit 2dbbb28727c7c2954438666dafba57bb8c714d3b refs/heads/fix/github-enterprise-gist\n`
+	if len(line) > 48 {
+		ref = line[48 : len(line)-1]
+	}
+
+	return
+}
+
+// ParseCommitSource s
+// https://git-scm.com/docs/git-log#Documentation/git-log.txt---source
+func parseSourceRef(ref []byte) string {
+	// Remove the `refs/heads/thog` prefix.
+	// (We don't care about refs without this prefix.)
+	ref, ok := bytes.CutPrefix(ref, []byte("refs/heads/thog/"))
+	if !ok {
+		return ""
+	}
+
+	// Handle GitHub pull requests.
+	// e.g., `pr/238/head` or `pr/1234/merge`
+	if after, ok := bytes.CutPrefix(ref, []byte("pr/")); ok {
+		prNumber := after[:bytes.Index(after, []byte("/"))]
+		return "Pull request #" + string(prNumber)
+	}
+
+	// Handle GitLab merge requests
+	// e.g., `mr/238/head` or `mr/1234/merge`
+	if after, ok := bytes.CutPrefix(ref, []byte("mr/")); ok {
+		mrNumber := after[:bytes.Index(after, []byte("/"))]
+		return "Merge request #" + string(mrNumber)
+	}
+
+	return ""
+}
+
 // Author: Bill Rich <[email protected]>
 func isAuthorLine(isStaged bool, latestState ParseState, line []byte) bool {
 	if isStaged || !(latestState == CommitLine || latestState == MergeLine) {

pkg/gitparse/gitparse_test.go

@@ -703,6 +703,45 @@ func TestLineChecksNoStaged(t *testing.T) {
 	}
 }
 
+func Test_parseCommitLine(t *testing.T) {
+	cases := map[string][]string{
+		"commit 198c63cb8212a99cc4352bc72f25e5444a786291 refs/heads/main\n":                       {"198c63cb8212a99cc4352bc72f25e5444a786291", "refs/heads/main"},
+		"commit e76dfb98ab9001daa869191b6aebe8cf4cd3b22a refs/remotes/origin/debug/aws-logging\n": {"e76dfb98ab9001daa869191b6aebe8cf4cd3b22a", "refs/remotes/origin/debug/aws-logging"},
+	}
+
+	for line, expected := range cases {
+		hash, ref := parseCommitLine([]byte(line))
+		if string(hash) != expected[0] {
+			t.Errorf("Expected: %s, Got: %s", expected[0], hash)
+		}
+		if string(ref) != expected[1] {
+			t.Errorf("Expected: %s, Got: %s", expected[1], ref)
+		}
+	}
+}
+
+func Test_parseSourceRef(t *testing.T) {
+	cases := map[string]string{
+		"refs/heads/master": "",
+		"refs/tags/v3.0.5":  "",
+		// refs/merge-requests/33/head
+		"refs/heads/thog/mr/33/head": "Merge request #33",
+		// refs/merge-requests/19/merge
+		"refs/heads/thog/mr/19/merge": "Merge request #19",
+		// refs/pull/980/head
+		"refs/heads/thog/pr/980/head": "Pull request #980",
+		// refs/pull/1644/merge
+		"refs/heads/thog/pr/1644/merge": "Pull request #1644",
+	}
+
+	for line, expected := range cases {
+		source := parseSourceRef([]byte(line))
+		if source != expected {
+			t.Errorf("Expected: %s, Got: %s", expected, source)
+		}
+	}
+}
+
 func TestBinaryPathParse(t *testing.T) {
 	cases := map[string]string{
 		"Binary files a/trufflehog_3.42.0_linux_arm64.tar.gz and /dev/null differ\n":                                                                                         "",