output: Add the gitlab output.

This adds a new output format, `gitlab`, which produces [Code Quality
reports](https://docs.gitlab.com/ee/ci/testing/code_quality.html#code-quality-report-format)
for GitLab. This allows GitLab CI jobs to annotate which files need formatting.
Without this, a CI job can only fail, leaving the user to sieve through the
logs to find out which files they need to format.

Author: octo

docs/output.md

@@ -31,4 +31,39 @@ Example:
 x.yaml: formatting difference found
 y.yaml: formatting difference found
 z.yaml: formatting difference found
-```
+```
+
+## `gitlab`
+
+Generates a [GitLab Code Quality report](https://docs.gitlab.com/ee/ci/testing/code_quality.html#code-quality-report-format).
+
+Example:
+
+```json
+[
+  {
+    "description": "Not formatted correctly, run yamlfmt to resolve.",
+    "check_name": "yamlfmt",
+    "fingerprint": "c1dddeed9a8423b815cef59434fe3dea90d946016c8f71ecbd7eb46c528c0179",
+    "severity": "major",
+    "location": {
+      "path": ".gitlab-ci.yml"
+    }
+  },
+]
+```
+
+To use in a GitLab CI pipeline, first write the Code Quality report to a file, then upload the file as a Code Quality artifact.
+Abbreviated example:
+
+```yaml
+yamlfmt:
+  script:
+    - yamlfmt -dry -output_format gitlab . >yamlfmt-report
+  artifacts:
+    when: always
+    reports:
+      codequality: yamlfmt-report
+```
+
+With `-quiet`, the GitLab format will omit unnecessary whitespace to produce a more compact output.

engine/output.go

@@ -15,16 +15,21 @@
 package engine
 
 import (
+	"encoding/json"
 	"fmt"
+	"slices"
+	"strings"
 
 	"github.com/google/yamlfmt"
+	"github.com/google/yamlfmt/internal/gitlab"
 )
 
 type EngineOutputFormat string
 
 const (
 	EngineOutputDefault   EngineOutputFormat = "default"
 	EngineOutputSingeLine EngineOutputFormat = "line"
+	EngineOutputGitlab    EngineOutputFormat = "gitlab"
 )
 
 func getEngineOutput(t EngineOutputFormat, operation yamlfmt.Operation, files yamlfmt.FileDiffs, quiet bool) (fmt.Stringer, error) {
@@ -33,6 +38,9 @@ func getEngineOutput(t EngineOutputFormat, operation yamlfmt.Operation, files ya
 		return engineOutput{Operation: operation, Files: files, Quiet: quiet}, nil
 	case EngineOutputSingeLine:
 		return engineOutputSingleLine{Operation: operation, Files: files, Quiet: quiet}, nil
+	case EngineOutputGitlab:
+		return engineOutputGitlab{Operation: operation, Files: files, Compact: quiet}, nil
+
 	}
 	return nil, fmt.Errorf("unknown output type: %s", t)
 }
@@ -85,3 +93,39 @@ func (eosl engineOutputSingleLine) String() string {
 	}
 	return msg
 }
+
+type engineOutputGitlab struct {
+	Operation yamlfmt.Operation
+	Files     yamlfmt.FileDiffs
+	Compact   bool
+}
+
+func (eo engineOutputGitlab) String() string {
+	var findings []gitlab.CodeQuality
+
+	for _, file := range eo.Files {
+		if cq, ok := gitlab.NewCodeQuality(*file); ok {
+			findings = append(findings, cq)
+		}
+	}
+
+	if len(findings) == 0 {
+		return ""
+	}
+
+	slices.SortFunc(findings, func(a, b gitlab.CodeQuality) int {
+		return strings.Compare(a.Path, b.Path)
+	})
+
+	var b strings.Builder
+	enc := json.NewEncoder(&b)
+
+	if !eo.Compact {
+		enc.SetIndent("", "  ")
+	}
+
+	if err := enc.Encode(findings); err != nil {
+		panic(err)
+	}
+	return b.String()
+}

internal/gitlab/codequality.go

@@ -0,0 +1,117 @@
+// Package gitlab generates GitLab Code Quality reports.
+package gitlab
+
+import (
+	"crypto/sha256"
+	"encoding/json"
+	"fmt"
+
+	"github.com/google/yamlfmt"
+)
+
+// CodeQuality represents a single code quality finding.
+//
+// Documentation: https://docs.gitlab.com/ee/ci/testing/code_quality.html#code-quality-report-format
+type CodeQuality struct {
+	Description string
+	Name        string
+	Fingerprint string
+	Severity    Severity
+	Path        string
+}
+
+// NewCodeQuality creates a new CodeQuality object from a yamlfmt.FileDiff.
+//
+// If the file did not change, i.e. the diff is empty, an empty struct and false is returned.
+func NewCodeQuality(diff yamlfmt.FileDiff) (CodeQuality, bool) {
+	if !diff.Diff.Changed() {
+		return CodeQuality{}, false
+	}
+
+	return CodeQuality{
+		Description: "Not formatted correctly, run yamlfmt to resolve.",
+		Name:        "yamlfmt",
+		Fingerprint: fingerprint(diff),
+		Severity:    Major,
+		Path:        diff.Path,
+	}, true
+}
+
+// Marshals a CodeQuality object into JSON.
+func (cq CodeQuality) MarshalJSON() ([]byte, error) {
+	data, err := json.Marshal(wrap(cq))
+	if err != nil {
+		return nil, fmt.Errorf("json.Marshal: %w", err)
+	}
+
+	return data, nil
+}
+
+// UnmarshalJSON unmarshals JSON into a CodeQuality object.
+func (cq *CodeQuality) UnmarshalJSON(data []byte) error {
+	var ext codeQuality
+	if err := json.Unmarshal(data, &ext); err != nil {
+		return fmt.Errorf("json.Unmarshal: %w", err)
+	}
+
+	*cq = unwrap(ext)
+
+	return nil
+}
+
+// codeQuality is the external representation of CodeQuality.
+// It is needed to add custom JSON marshaling and unmarshaling logic.
+type codeQuality struct {
+	Description string   `json:"description,omitempty"`
+	Name        string   `json:"check_name,omitempty"`
+	Fingerprint string   `json:"fingerprint,omitempty"`
+	Severity    Severity `json:"severity,omitempty"`
+	Location    location `json:"location,omitempty"`
+}
+
+type location struct {
+	Path string `json:"path,omitempty"`
+}
+
+func wrap(cq CodeQuality) codeQuality {
+	return codeQuality{
+		Description: cq.Description,
+		Name:        cq.Name,
+		Fingerprint: cq.Fingerprint,
+		Severity:    cq.Severity,
+		Location: location{
+			Path: cq.Path,
+		},
+	}
+}
+
+func unwrap(cq codeQuality) CodeQuality {
+	return CodeQuality{
+		Description: cq.Description,
+		Name:        cq.Name,
+		Fingerprint: cq.Fingerprint,
+		Severity:    cq.Severity,
+		Path:        cq.Location.Path,
+	}
+}
+
+// fingerprint returns a 256-bit SHA256 hash of the original unformatted file.
+// This is used to uniquely identify a code quality finding.
+func fingerprint(diff yamlfmt.FileDiff) string {
+	hash := sha256.New()
+
+	fmt.Fprint(hash, diff.Diff.Original)
+
+	return fmt.Sprintf("%x", hash.Sum(nil)) //nolint:perfsprint
+}
+
+// Severity is the severity of a code quality finding.
+type Severity string
+
+const (
+	Info     Severity = "info"
+	Minor    Severity = "minor"
+	Major    Severity = "major"
+	Critical Severity = "critical"
+	Blocker  Severity = "blocker"
+)

internal/gitlab/codequality_test.go

@@ -0,0 +1,81 @@
+package gitlab_test
+
+import (
+	"encoding/json"
+	"testing"
+
+	"github.com/google/go-cmp/cmp"
+	"github.com/google/yamlfmt"
+	"github.com/google/yamlfmt/internal/gitlab"
+)
+
+func TestCodeQuality(t *testing.T) {
+	t.Parallel()
+
+	cases := []struct {
+		name            string
+		diff            yamlfmt.FileDiff
+		wantOK          bool
+		wantFingerprint string
+	}{
+		{
+			name: "no diff",
+			diff: yamlfmt.FileDiff{
+				Path: "testcase/no_diff.yaml",
+				Diff: &yamlfmt.FormatDiff{
+					Original:  "a: b",
+					Formatted: "a: b",
+				},
+			},
+			wantOK: false,
+		},
+		{
+			name: "with diff",
+			diff: yamlfmt.FileDiff{
+				Path: "testcase/with_diff.yaml",
+				Diff: &yamlfmt.FormatDiff{
+					Original:  "a:   b",
+					Formatted: "a: b",
+				},
+			},
+			wantOK: true,
+			// SHA256 of diff.Diff.Original
+			wantFingerprint: "05088f1c296b4fd999a1efe48e4addd0f962a8569afbacc84c44630d47f09330",
+		},
+	}
+
+	for _, tc := range cases {
+		// copy tc to avoid capturing an aliased loop variable in a Goroutine.
+		tc := tc
+
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			got, gotOK := gitlab.NewCodeQuality(tc.diff)
+			if gotOK != tc.wantOK {
+				t.Fatalf("NewCodeQuality() = (%#v, %v), want (*, %v)", got, gotOK, tc.wantOK)
+			}
+			if !gotOK {
+				return
+			}
+
+			if tc.wantFingerprint != "" && tc.wantFingerprint != got.Fingerprint {
+				t.Fatalf("NewCodeQuality().Fingerprint = %q, want %q", got.Fingerprint, tc.wantFingerprint)
+			}
+
+			data, err := json.Marshal(got)
+			if err != nil {
+				t.Fatal(err)
+			}
+
+			var gotUnmarshal gitlab.CodeQuality
+			if err := json.Unmarshal(data, &gotUnmarshal); err != nil {
+				t.Fatal(err)
+			}
+
+			if diff := cmp.Diff(got, gotUnmarshal); diff != "" {
+				t.Errorf("json.Marshal() and json.Unmarshal() mismatch (-got +want):\n%s", diff)
+			}
+		})
+	}
+}