Improve converter diagnostic output (#6549)

* Improve converter diagnostic output by including a Footer and removing lower
  level diagnostics when a configuration fails to generate.

Signed-off-by: erikbaranowski <[email protected]>

---------

Signed-off-by: erikbaranowski <[email protected]>

CHANGELOG.md

@@ -16,6 +16,9 @@ Main (unreleased)
 
 - Add support for importing directories as single module to `import.git`. (@wildum)
 
+- Improve converter diagnostic output by including a Footer and removing lower
+  level diagnostics when a configuration fails to generate. (@erikbaranowski)
+
 ### Features
 
 - Added a new CLI flag `--stability.level` which defines the minimum stability
@@ -51,7 +54,6 @@ v0.40.2 (2024-03-05)
 
 - Fix an issue where Loki could reject a batch of logs when structured metadata feature is used. (@thampiotr)
 
-=======
 - Fix a duplicate metrics registration panic when recreating static
   mode metric instance's write handler. (@rfratto, @hainenber)
 

internal/converter/diag/diagnostics.go

@@ -46,12 +46,12 @@ func (ds Diagnostics) Error() string {
 	return sb.String()
 }
 
-func (ds Diagnostics) GenerateReport(writer io.Writer, reportType string) error {
+func (ds Diagnostics) GenerateReport(writer io.Writer, reportType string, bypassErrors bool) error {
 	switch reportType {
 	case Text:
-		return generateTextReport(writer, ds)
+		return generateTextReport(writer, ds, bypassErrors)
 	default:
-		return fmt.Errorf("Invalid diagnostic report type %q", reportType)
+		return fmt.Errorf("invalid diagnostic report type %q", reportType)
 	}
 }
 
@@ -66,3 +66,12 @@ func (ds *Diagnostics) RemoveDiagsBySeverity(severity Severity) {
 
 	*ds = newDiags
 }
+
+func (ds *Diagnostics) HasSeverityLevel(severity Severity) bool {
+	for _, diag := range *ds {
+		if diag.Severity == severity {
+			return true
+		}
+	}
+	return false
+}

internal/converter/diag/report.go

@@ -6,14 +6,47 @@ import (
 
 const Text = ".txt"
 
-// generateTextReport generates a text report for the diagnostics.
-func generateTextReport(writer io.Writer, ds Diagnostics) error {
-	content := ds.Error()
+const criticalErrorFooter = `
+
+A configuration file was not generated due to critical issues. Refer to the critical messages for more information.`
+
+const errorFooter = `
+
+A configuration file was not generated due to errors. Refer to the error messages for more information.
+
+You can bypass the errors by using the --bypass-errors flag. Bypassing errors isn't recommended for production environments.`
+
+const successFooter = `
 
+A configuration file was generated successfully.`
+
+// generateTextReport generates a text report for the diagnostics.
+func generateTextReport(writer io.Writer, ds Diagnostics, bypassErrors bool) error {
+	content := getContent(ds, bypassErrors)
 	_, err := writer.Write([]byte(content))
 	if err != nil {
 		return err
 	}
 
 	return nil
 }
+
+// getContent returns the formatted content for the report based on the diagnostics and bypassErrors.
+func getContent(ds Diagnostics, bypassErrors bool) string {
+	var content string
+	switch {
+	case ds.HasSeverityLevel(SeverityLevelCritical):
+		content = criticalErrorFooter
+		ds.RemoveDiagsBySeverity(SeverityLevelInfo)
+		ds.RemoveDiagsBySeverity(SeverityLevelWarn)
+		ds.RemoveDiagsBySeverity(SeverityLevelError)
+	case ds.HasSeverityLevel(SeverityLevelError) && !bypassErrors:
+		content = errorFooter
+		ds.RemoveDiagsBySeverity(SeverityLevelInfo)
+		ds.RemoveDiagsBySeverity(SeverityLevelWarn)
+	default:
+		content = successFooter
+	}
+
+	return ds.Error() + content
+}

internal/converter/diag/report_test.go

@@ -0,0 +1,81 @@
+package diag
+
+import (
+	"bytes"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestDiagReporting(t *testing.T) {
+	var (
+		criticalDiagnostic = Diagnostic{
+			Severity: SeverityLevelCritical,
+			Summary:  "this is a critical diag",
+		}
+		errorDiagnostic = Diagnostic{
+			Severity: SeverityLevelError,
+			Summary:  "this is an error diag",
+		}
+		warnDiagnostic = Diagnostic{
+			Severity: SeverityLevelWarn,
+			Summary:  "this is a warn diag",
+		}
+		infoDiagnostic = Diagnostic{
+			Severity: SeverityLevelInfo,
+			Summary:  "this is an info diag",
+		}
+	)
+
+	tt := []struct {
+		name            string
+		diags           Diagnostics
+		bypassErrors    bool
+		expectedMessage string
+	}{
+		{
+			name:            "Empty",
+			diags:           Diagnostics{},
+			expectedMessage: successFooter,
+		},
+		{
+			name:            "Critical",
+			diags:           Diagnostics{criticalDiagnostic, errorDiagnostic, warnDiagnostic, infoDiagnostic},
+			expectedMessage: `(Critical) this is a critical diag` + criticalErrorFooter,
+		},
+		{
+			name:            "Error",
+			diags:           Diagnostics{errorDiagnostic, warnDiagnostic, infoDiagnostic},
+			expectedMessage: `(Error) this is an error diag` + errorFooter,
+		},
+		{
+			name:         "Bypass Error",
+			diags:        Diagnostics{errorDiagnostic, warnDiagnostic, infoDiagnostic},
+			bypassErrors: true,
+			expectedMessage: `(Error) this is an error diag
+(Warning) this is a warn diag
+(Info) this is an info diag` + successFooter,
+		},
+		{
+			name:  "Warn",
+			diags: Diagnostics{warnDiagnostic, infoDiagnostic},
+			expectedMessage: `(Warning) this is a warn diag
+(Info) this is an info diag` + successFooter,
+		},
+		{
+			name:            "Info",
+			diags:           Diagnostics{infoDiagnostic},
+			expectedMessage: `(Info) this is an info diag` + successFooter,
+		},
+	}
+
+	for _, tc := range tt {
+		t.Run(tc.name, func(t *testing.T) {
+			var buf bytes.Buffer
+			err := generateTextReport(&buf, tc.diags, tc.bypassErrors)
+			require.NoError(t, err)
+
+			require.Equal(t, tc.expectedMessage, buf.String())
+		})
+	}
+}

internal/flowmode/cmd_convert.go

@@ -163,7 +163,7 @@ func generateConvertReport(diags convert_diag.Diagnostics, fc *flowConvert) erro
 		}
 		defer file.Close()
 
-		return diags.GenerateReport(file, convert_diag.Text)
+		return diags.GenerateReport(file, convert_diag.Text, fc.bypassErrors)
 	}
 
 	return nil