Merge pull request #2679 from robnester-rh/EC-1374

feat(report): add documentation link to report

Author: robnester-rh

features/__snapshots__/validate_image.snap

@@ -1991,6 +1991,7 @@ Results:
   Title: Allow rule
   Description: This rule will never fail
 
+For more information about policy issues, see the policy documentation: https://conforma.dev/docs/policy/
 
 ---
 [future failure is a deny when using effective-date flag:stdout - 1]
@@ -4834,6 +4835,7 @@ Results:
   ImageRef: ${REGISTRY}/acceptance/image@sha256:${REGISTRY_acceptance/image:latest_DIGEST}
   Reason: Fails always
 
+For more information about policy issues, see the policy documentation: https://conforma.dev/docs/policy/
 
 ---
 

internal/applicationsnapshot/__snapshots__/report_test.snap

@@ -155,5 +155,6 @@ Results:
 ✓ [Success] success-2
   ImageRef: registry.io/repository/component-4:tag
 
+For more information about policy issues, see the policy documentation: https://conforma.dev/docs/policy/
 
 ---

internal/applicationsnapshot/report_test.go

@@ -24,6 +24,7 @@ import (
 	_ "embed"
 	"encoding/json"
 	"fmt"
+	"strings"
 	"testing"
 	"time"
 
@@ -998,3 +999,178 @@ func createTestPolicy(t *testing.T, ctx context.Context) policy.Policy {
 	assert.NoError(t, err)
 	return p
 }
+
+func Test_DocumentationLink_OnlySuccesses(t *testing.T) {
+	// Test case: Only successes - should NOT show documentation link
+	r := Report{
+		ShowSuccesses: true,
+		Components: []Component{
+			{
+				Successes: []evaluator.Result{
+					{
+						Metadata: map[string]interface{}{
+							"code": "success.policy",
+						},
+						Message: "Policy passed successfully",
+					},
+				},
+				SuccessCount: 1,
+			},
+		},
+	}
+
+	output, err := generateTextReport(&r)
+	require.NoError(t, err)
+
+	outputStr := string(output)
+	hasDocLink := strings.Contains(outputStr, "https://conforma.dev/docs/policy/")
+
+	assert.False(t, hasDocLink, "Documentation link should NOT appear when there are only successes")
+}
+
+func Test_DocumentationLink_OnlyWarnings(t *testing.T) {
+	// Test case: Only warnings - should show documentation link
+	r := Report{
+		Components: []Component{
+			{
+				Warnings: []evaluator.Result{
+					{
+						Metadata: map[string]interface{}{
+							"code": "warning.policy",
+						},
+						Message: "Policy warning message",
+					},
+				},
+			},
+		},
+	}
+
+	output, err := generateTextReport(&r)
+	require.NoError(t, err)
+
+	outputStr := string(output)
+	hasDocLink := strings.Contains(outputStr, "https://conforma.dev/docs/policy/")
+
+	assert.True(t, hasDocLink, "Documentation link should appear when there are warnings")
+	assert.Contains(t, outputStr, "For more information about policy issues", "Should contain the documentation link message")
+}
+
+func Test_DocumentationLink_OnlyFailures(t *testing.T) {
+	// Test case: Only failures - should show documentation link
+	r := Report{
+		Components: []Component{
+			{
+				Violations: []evaluator.Result{
+					{
+						Metadata: map[string]interface{}{
+							"code": "failure.policy",
+						},
+						Message: "Policy violation message",
+					},
+				},
+			},
+		},
+	}
+
+	output, err := generateTextReport(&r)
+	require.NoError(t, err)
+
+	outputStr := string(output)
+	hasDocLink := strings.Contains(outputStr, "https://conforma.dev/docs/policy/")
+
+	assert.True(t, hasDocLink, "Documentation link should appear when there are failures")
+	assert.Contains(t, outputStr, "For more information about policy issues", "Should contain the documentation link message")
+}
+
+func Test_DocumentationLink_WarningsAndFailures(t *testing.T) {
+	// Test case: Both warnings and failures - should show documentation link
+	r := Report{
+		Components: []Component{
+			{
+				Violations: []evaluator.Result{
+					{
+						Metadata: map[string]interface{}{
+							"code": "failure.policy",
+						},
+						Message: "Policy violation message",
+					},
+				},
+				Warnings: []evaluator.Result{
+					{
+						Metadata: map[string]interface{}{
+							"code": "warning.policy",
+						},
+						Message: "Policy warning message",
+					},
+				},
+			},
+		},
+	}
+
+	output, err := generateTextReport(&r)
+	require.NoError(t, err)
+
+	outputStr := string(output)
+	hasDocLink := strings.Contains(outputStr, "https://conforma.dev/docs/policy/")
+
+	assert.True(t, hasDocLink, "Documentation link should appear when there are both warnings and failures")
+	assert.Contains(t, outputStr, "For more information about policy issues", "Should contain the documentation link message")
+}
+
+func Test_DocumentationLink_MultipleComponents(t *testing.T) {
+	// Test case: Multiple components with mixed results - should show documentation link
+	r := Report{
+		ShowSuccesses: true,
+		Components: []Component{
+			{
+				// Component 1: Only successes
+				Successes: []evaluator.Result{
+					{
+						Metadata: map[string]interface{}{"code": "success1.policy"},
+						Message:  "Success in component 1",
+					},
+				},
+				SuccessCount: 1,
+			},
+			{
+				// Component 2: Has warnings (should trigger the link)
+				Warnings: []evaluator.Result{
+					{
+						Metadata: map[string]interface{}{"code": "warning1.policy"},
+						Message:  "Warning in component 2",
+					},
+				},
+				Successes: []evaluator.Result{
+					{
+						Metadata: map[string]interface{}{"code": "success2.policy"},
+						Message:  "Success in component 2",
+					},
+				},
+				SuccessCount: 1,
+			},
+		},
+	}
+
+	output, err := generateTextReport(&r)
+	require.NoError(t, err)
+
+	outputStr := string(output)
+	hasDocLink := strings.Contains(outputStr, "https://conforma.dev/docs/policy/")
+
+	assert.True(t, hasDocLink, "Documentation link should appear when any component has warnings or failures")
+}
+
+func Test_DocumentationLink_EmptyReport(t *testing.T) {
+	// Test case: Empty report - should NOT show documentation link
+	r := Report{
+		Components: []Component{},
+	}
+
+	output, err := generateTextReport(&r)
+	require.NoError(t, err)
+
+	outputStr := string(output)
+	hasDocLink := strings.Contains(outputStr, "https://conforma.dev/docs/policy/")
+
+	assert.False(t, hasDocLink, "Documentation link should NOT appear for empty reports")
+}

internal/applicationsnapshot/templates/text_report.tmpl

@@ -21,3 +21,7 @@ Results:{{ nl -}}
   {{- template "_results.tmpl" (toMap "Components" $c "Type" "Success") -}}
 {{- end -}}
 {{- end -}}
+
+{{- if or (gt $t.Failures 0) (gt $t.Warnings 0) -}}
+For more information about policy issues, see the policy documentation: https://conforma.dev/docs/policy/{{ nl -}}
+{{- end -}}

internal/opa/rule/rule.go

@@ -222,7 +222,7 @@ func documentationUrl(a *ast.AnnotationsRef) string {
 
 	// This makes assumptions about the way we publish policy docs for
 	// policies defined in https://github.com/conforma/policy/
-	// to https://conforma.dev/docs/policy/index.html . We should figure
+	// to https://conforma.dev/docs/policy/ . We should figure
 	// out a way for the documentationUrl to be configurable, perhaps by using
 	// some additional package annotations. To make matters even worse, we're now
 	// hard coding "release_policy" in the URL, which is guaranteed wrong for