Skip to content

Commit abd7986

Browse files
robnester-rhrobnester-rh
committed
feat(report): add documentation link to report
This commit adds a documentation link to text reports when there are policy warnings or failures in an effort to help users find more information about resolving issues. The link appears at the end of text reports with the message: "For more information about policy issues, see the policy documentation: https://conforma.dev/docs/policy/index.html" This message is shown when: - There are warnings - There are failures - There are both warnings and failures REF: EC-1374 Signed-off-by: Rob Nester <rnester@redhat.com>
1 parent 7bc924d commit abd7986

File tree

5 files changed

+184
-1
lines changed

5 files changed

+184
-1
lines changed

‎features/__snapshots__/validate_image.snap‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1991,6 +1991,7 @@ Results:
19911991
Title: Allow rule
19921992
Description: This rule will never fail
19931993

1994+
For more information about policy issues, see the policy documentation: https://conforma.dev/docs/policy/
19941995

19951996
---
19961997
[future failure is a deny when using effective-date flag:stdout - 1]
@@ -4834,6 +4835,7 @@ Results:
48344835
ImageRef: ${REGISTRY}/acceptance/image@sha256:${REGISTRY_acceptance/image:latest_DIGEST}
48354836
Reason: Fails always
48364837

4838+
For more information about policy issues, see the policy documentation: https://conforma.dev/docs/policy/
48374839

48384840
---
48394841

‎internal/applicationsnapshot/__snapshots__/report_test.snap‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -155,5 +155,6 @@ Results:
155155
✓ [Success] success-2
156156
ImageRef: registry.io/repository/component-4:tag
157157

158+
For more information about policy issues, see the policy documentation: https://conforma.dev/docs/policy/
158159

159160
---

‎internal/applicationsnapshot/report_test.go‎

Lines changed: 176 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ import (
2424
_ "embed"
2525
"encoding/json"
2626
"fmt"
27+
"strings"
2728
"testing"
2829
"time"
2930

@@ -998,3 +999,178 @@ func createTestPolicy(t *testing.T, ctx context.Context) policy.Policy {
998999
assert.NoError(t, err)
9991000
return p
10001001
}
1002+
1003+
func Test_DocumentationLink_OnlySuccesses(t *testing.T) {
1004+
// Test case: Only successes - should NOT show documentation link
1005+
r := Report{
1006+
ShowSuccesses: true,
1007+
Components: []Component{
1008+
{
1009+
Successes: []evaluator.Result{
1010+
{
1011+
Metadata: map[string]interface{}{
1012+
"code": "success.policy",
1013+
},
1014+
Message: "Policy passed successfully",
1015+
},
1016+
},
1017+
SuccessCount: 1,
1018+
},
1019+
},
1020+
}
1021+
1022+
output, err := generateTextReport(&r)
1023+
require.NoError(t, err)
1024+
1025+
outputStr := string(output)
1026+
hasDocLink := strings.Contains(outputStr, "https://conforma.dev/docs/policy/")
1027+
1028+
assert.False(t, hasDocLink, "Documentation link should NOT appear when there are only successes")
1029+
}
1030+
1031+
func Test_DocumentationLink_OnlyWarnings(t *testing.T) {
1032+
// Test case: Only warnings - should show documentation link
1033+
r := Report{
1034+
Components: []Component{
1035+
{
1036+
Warnings: []evaluator.Result{
1037+
{
1038+
Metadata: map[string]interface{}{
1039+
"code": "warning.policy",
1040+
},
1041+
Message: "Policy warning message",
1042+
},
1043+
},
1044+
},
1045+
},
1046+
}
1047+
1048+
output, err := generateTextReport(&r)
1049+
require.NoError(t, err)
1050+
1051+
outputStr := string(output)
1052+
hasDocLink := strings.Contains(outputStr, "https://conforma.dev/docs/policy/")
1053+
1054+
assert.True(t, hasDocLink, "Documentation link should appear when there are warnings")
1055+
assert.Contains(t, outputStr, "For more information about policy issues", "Should contain the documentation link message")
1056+
}
1057+
1058+
func Test_DocumentationLink_OnlyFailures(t *testing.T) {
1059+
// Test case: Only failures - should show documentation link
1060+
r := Report{
1061+
Components: []Component{
1062+
{
1063+
Violations: []evaluator.Result{
1064+
{
1065+
Metadata: map[string]interface{}{
1066+
"code": "failure.policy",
1067+
},
1068+
Message: "Policy violation message",
1069+
},
1070+
},
1071+
},
1072+
},
1073+
}
1074+
1075+
output, err := generateTextReport(&r)
1076+
require.NoError(t, err)
1077+
1078+
outputStr := string(output)
1079+
hasDocLink := strings.Contains(outputStr, "https://conforma.dev/docs/policy/")
1080+
1081+
assert.True(t, hasDocLink, "Documentation link should appear when there are failures")
1082+
assert.Contains(t, outputStr, "For more information about policy issues", "Should contain the documentation link message")
1083+
}
1084+
1085+
func Test_DocumentationLink_WarningsAndFailures(t *testing.T) {
1086+
// Test case: Both warnings and failures - should show documentation link
1087+
r := Report{
1088+
Components: []Component{
1089+
{
1090+
Violations: []evaluator.Result{
1091+
{
1092+
Metadata: map[string]interface{}{
1093+
"code": "failure.policy",
1094+
},
1095+
Message: "Policy violation message",
1096+
},
1097+
},
1098+
Warnings: []evaluator.Result{
1099+
{
1100+
Metadata: map[string]interface{}{
1101+
"code": "warning.policy",
1102+
},
1103+
Message: "Policy warning message",
1104+
},
1105+
},
1106+
},
1107+
},
1108+
}
1109+
1110+
output, err := generateTextReport(&r)
1111+
require.NoError(t, err)
1112+
1113+
outputStr := string(output)
1114+
hasDocLink := strings.Contains(outputStr, "https://conforma.dev/docs/policy/")
1115+
1116+
assert.True(t, hasDocLink, "Documentation link should appear when there are both warnings and failures")
1117+
assert.Contains(t, outputStr, "For more information about policy issues", "Should contain the documentation link message")
1118+
}
1119+
1120+
func Test_DocumentationLink_MultipleComponents(t *testing.T) {
1121+
// Test case: Multiple components with mixed results - should show documentation link
1122+
r := Report{
1123+
ShowSuccesses: true,
1124+
Components: []Component{
1125+
{
1126+
// Component 1: Only successes
1127+
Successes: []evaluator.Result{
1128+
{
1129+
Metadata: map[string]interface{}{"code": "success1.policy"},
1130+
Message: "Success in component 1",
1131+
},
1132+
},
1133+
SuccessCount: 1,
1134+
},
1135+
{
1136+
// Component 2: Has warnings (should trigger the link)
1137+
Warnings: []evaluator.Result{
1138+
{
1139+
Metadata: map[string]interface{}{"code": "warning1.policy"},
1140+
Message: "Warning in component 2",
1141+
},
1142+
},
1143+
Successes: []evaluator.Result{
1144+
{
1145+
Metadata: map[string]interface{}{"code": "success2.policy"},
1146+
Message: "Success in component 2",
1147+
},
1148+
},
1149+
SuccessCount: 1,
1150+
},
1151+
},
1152+
}
1153+
1154+
output, err := generateTextReport(&r)
1155+
require.NoError(t, err)
1156+
1157+
outputStr := string(output)
1158+
hasDocLink := strings.Contains(outputStr, "https://conforma.dev/docs/policy/")
1159+
1160+
assert.True(t, hasDocLink, "Documentation link should appear when any component has warnings or failures")
1161+
}
1162+
1163+
func Test_DocumentationLink_EmptyReport(t *testing.T) {
1164+
// Test case: Empty report - should NOT show documentation link
1165+
r := Report{
1166+
Components: []Component{},
1167+
}
1168+
1169+
output, err := generateTextReport(&r)
1170+
require.NoError(t, err)
1171+
1172+
outputStr := string(output)
1173+
hasDocLink := strings.Contains(outputStr, "https://conforma.dev/docs/policy/")
1174+
1175+
assert.False(t, hasDocLink, "Documentation link should NOT appear for empty reports")
1176+
}

‎internal/applicationsnapshot/templates/text_report.tmpl‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,3 +21,7 @@ Results:{{ nl -}}
2121
{{- template "_results.tmpl" (toMap "Components" $c "Type" "Success") -}}
2222
{{- end -}}
2323
{{- end -}}
24+
25+
{{- if or (gt $t.Failures 0) (gt $t.Warnings 0) -}}
26+
For more information about policy issues, see the policy documentation: https://conforma.dev/docs/policy/{{ nl -}}
27+
{{- end -}}

‎internal/opa/rule/rule.go‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -222,7 +222,7 @@ func documentationUrl(a *ast.AnnotationsRef) string {
222222

223223
// This makes assumptions about the way we publish policy docs for
224224
// policies defined in https://github.com/conforma/policy/
225-
// to https://conforma.dev/docs/policy/index.html . We should figure
225+
// to https://conforma.dev/docs/policy/ . We should figure
226226
// out a way for the documentationUrl to be configurable, perhaps by using
227227
// some additional package annotations. To make matters even worse, we're now
228228
// hard coding "release_policy" in the URL, which is guaranteed wrong for

0 commit comments

Comments
 (0)