feat: Add --show-policy-docs-link flag for validation output

dheerajodha · claude · dheerajodha · commit 32c950148a84 · 2026-03-25T19:56:15.000+05:30
Give users control over policy documentation links in validation reports. Defaults to false to keep demo output clean—production CI can opt in with --show-policy-docs-link=true when they want the help link. Why default to false? Your colleague nailed it: "for demos it's better if the default is false, otherwise every example needs to include the flag." Nobody wants documentation URLs cluttering their quick validation examples. Implementation: - Added persistent flag on parent validate command (all subcommands inherit) - Flag controls display of https://conforma.dev/docs/policy/ link - Link only appears when violations/warnings exist - Updated tests to properly initialize flags - Report structures updated to pass flag through Usage: # Default - clean output for demos ec validate image --image <img> --policy <policy> # Opt-in for production/CI ec validate image --image <img> --policy <policy> --show-policy-docs-link=true Note: Snapshot updates will be handled in a separate PR to keep this focused. resolves: EC-1603 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
diff --git a/cmd/validate/image.go b/cmd/validate/image.go
@@ -338,6 +338,7 @@ func validateImageCmd(validate imageValidationFunc) *cobra.Command {
 
 			showSuccesses, _ := cmd.Flags().GetBool("show-successes")
 			showWarnings, _ := cmd.Flags().GetBool("show-warnings")
+			showPolicyDocsLink, _ := cmd.Flags().GetBool("show-policy-docs-link")
 
 			// worker is responsible for processing one component at a time from the jobs channel,
 			// and for emitting a corresponding result for the component on the results channel.
@@ -429,13 +430,14 @@ func validateImageCmd(validate imageValidationFunc) *cobra.Command {
 			}
 
 			reportData := validate_utils.ReportData{
-				Snapshot:      data.snapshot,
-				Components:    components,
-				Policy:        data.policy,
-				PolicyInputs:  manyPolicyInput,
-				Expansion:     data.expansion,
-				ShowSuccesses: showSuccesses,
-				ShowWarnings:  showWarnings,
+				Snapshot:           data.snapshot,
+				Components:         components,
+				Policy:             data.policy,
+				PolicyInputs:       manyPolicyInput,
+				Expansion:          data.expansion,
+				ShowSuccesses:      showSuccesses,
+				ShowWarnings:       showWarnings,
+				ShowPolicyDocsLink: showPolicyDocsLink,
 			}
 			outputOpts := validate_utils.ReportOutputOptions{
 				Output:     data.output,
diff --git a/cmd/validate/input.go b/cmd/validate/input.go
@@ -121,6 +121,7 @@ func validateInputCmd(validate InputValidationFunc) *cobra.Command {
 
 			showSuccesses, _ := cmd.Flags().GetBool("show-successes")
 			showWarnings, _ := cmd.Flags().GetBool("show-warnings")
+			showPolicyDocsLink, _ := cmd.Flags().GetBool("show-policy-docs-link")
 
 			// Set numWorkers to the value from our flag. The default is 5.
 			numWorkers := data.workers
@@ -210,7 +211,7 @@ func validateInputCmd(validate InputValidationFunc) *cobra.Command {
 				return inputs[i].FilePath > inputs[j].FilePath
 			})
 
-			report, err := input.NewReport(inputs, data.policy, manyPolicyInput, showSuccesses, showWarnings)
+			report, err := input.NewReport(inputs, data.policy, manyPolicyInput, showSuccesses, showWarnings, showPolicyDocsLink)
 			if err != nil {
 				return err
 			}
diff --git a/cmd/validate/validate.go b/cmd/validate/validate.go
@@ -45,5 +45,6 @@ func NewValidateCmd() *cobra.Command {
 	}
 	validateCmd.PersistentFlags().Bool("show-successes", false, "")
 	validateCmd.PersistentFlags().Bool("show-warnings", true, "")
+	validateCmd.PersistentFlags().Bool("show-policy-docs-link", false, "Show link to policy documentation in output when there are violations or warnings")
 	return validateCmd
 }
diff --git a/cmd/validate/vsa.go b/cmd/validate/vsa.go
@@ -126,8 +126,9 @@ type validateVSAData struct {
 	workers int // Number of worker threads for parallel processing
 
 	// Output formatting options
-	noColor    bool // Disable color output
-	forceColor bool // Force color output
+	noColor            bool // Disable color output
+	forceColor         bool // Force color output
+	showPolicyDocsLink bool // Show policy docs link in output
 
 	// Internal state
 	policySpec ecapi.EnterpriseContractPolicySpec
@@ -266,6 +267,9 @@ func runValidateVSA(cmd *cobra.Command, data *validateVSAData, args []string) er
 	// Set color support based on flags
 	utils.SetColorEnabled(data.noColor, data.forceColor)
 
+	// Get show-policy-docs-link flag value
+	data.showPolicyDocsLink, _ = cmd.Flags().GetBool("show-policy-docs-link")
+
 	// Parse VSA expiration
 	if err := parseVSAExpiration(data); err != nil {
 		return err
@@ -1095,13 +1099,14 @@ func buildFallbackReportData(fallbackResults []validate_utils.Result, vsaData *v
 	}
 
 	return validate_utils.ReportData{
-		Snapshot:      vsaData.images,
-		Components:    components,
-		Policy:        vsaData.fallbackContext.FallbackPolicy,
-		PolicyInputs:  manyPolicyInput,
-		Expansion:     nil,
-		ShowSuccesses: false,
-		ShowWarnings:  true,
+		Snapshot:           vsaData.images,
+		Components:         components,
+		Policy:             vsaData.fallbackContext.FallbackPolicy,
+		PolicyInputs:       manyPolicyInput,
+		Expansion:          nil,
+		ShowSuccesses:      false,
+		ShowWarnings:       true,
+		ShowPolicyDocsLink: vsaData.showPolicyDocsLink,
 	}, nil
 }
 
@@ -1121,6 +1126,7 @@ func createFallbackReport(allData AllSectionsData, vsaData *validateVSAData) (*a
 		reportData.PolicyInputs,
 		reportData.ShowSuccesses,
 		reportData.ShowWarnings,
+		reportData.ShowPolicyDocsLink,
 		reportData.Expansion,
 	)
 	if err != nil {
diff --git a/cmd/validate/vsa_test.go b/cmd/validate/vsa_test.go
@@ -1034,6 +1034,8 @@ func TestValidateSingleVSA(t *testing.T) {
 			ctx := context.Background()
 			cmd := &cobra.Command{}
 			cmd.SetContext(ctx)
+			// Add the persistent flag that runValidateVSA expects
+			cmd.Flags().Bool("show-policy-docs-link", false, "")
 
 			// Use the unified runValidateVSA function which handles both single and snapshot cases
 			err := runValidateVSA(cmd, tt.data, tt.args)
@@ -1132,6 +1134,8 @@ func TestValidateSnapshotVSAs(t *testing.T) {
 			ctx := context.Background()
 			cmd := &cobra.Command{}
 			cmd.SetContext(ctx)
+			// Add the persistent flag that runValidateVSA expects
+			cmd.Flags().Bool("show-policy-docs-link", false, "")
 
 			// Use the unified runValidateVSA function which handles both single and snapshot cases
 			err := runValidateVSA(cmd, tt.data, []string{})
diff --git a/docs/modules/ROOT/pages/ec_validate.adoc b/docs/modules/ROOT/pages/ec_validate.adoc
@@ -5,6 +5,7 @@ Validate conformance with the provided policies
 == Options
 
 -h, --help:: help for validate (Default: false)
+--show-policy-docs-link:: Show link to policy documentation in output when there are violations or warnings (Default: false)
 --show-successes::  (Default: false)
 --show-warnings::  (Default: true)
 
diff --git a/docs/modules/ROOT/pages/ec_validate_image.adoc b/docs/modules/ROOT/pages/ec_validate_image.adoc
@@ -172,6 +172,7 @@ JSON of the "spec" or a reference to a Kubernetes object [<namespace>/]<name>
 --retry-jitter:: randomness factor for backoff calculation (0.0-1.0) (Default: 0.1)
 --retry-max-retry:: maximum number of retry attempts (Default: 3)
 --retry-max-wait:: maximum wait time between retries (Default: 3s)
+--show-policy-docs-link:: Show link to policy documentation in output when there are violations or warnings (Default: false)
 --show-successes::  (Default: false)
 --show-warnings::  (Default: true)
 --timeout:: max overall execution duration (Default: 5m0s)
diff --git a/docs/modules/ROOT/pages/ec_validate_input.adoc b/docs/modules/ROOT/pages/ec_validate_input.adoc
@@ -76,6 +76,7 @@ mark (?) sign, for example: --output text=output.txt?show-successes=false
 --retry-jitter:: randomness factor for backoff calculation (0.0-1.0) (Default: 0.1)
 --retry-max-retry:: maximum number of retry attempts (Default: 3)
 --retry-max-wait:: maximum wait time between retries (Default: 3s)
+--show-policy-docs-link:: Show link to policy documentation in output when there are violations or warnings (Default: false)
 --show-successes::  (Default: false)
 --show-warnings::  (Default: true)
 --timeout:: max overall execution duration (Default: 5m0s)
diff --git a/docs/modules/ROOT/pages/ec_validate_policy.adoc b/docs/modules/ROOT/pages/ec_validate_policy.adoc
@@ -37,6 +37,7 @@ ec validate policy --policy-configuration github.com/org/repo/policy.yaml
 --retry-jitter:: randomness factor for backoff calculation (0.0-1.0) (Default: 0.1)
 --retry-max-retry:: maximum number of retry attempts (Default: 3)
 --retry-max-wait:: maximum wait time between retries (Default: 3s)
+--show-policy-docs-link:: Show link to policy documentation in output when there are violations or warnings (Default: false)
 --show-successes::  (Default: false)
 --show-warnings::  (Default: true)
 --timeout:: max overall execution duration (Default: 5m0s)
diff --git a/docs/modules/ROOT/pages/ec_validate_vsa.adoc b/docs/modules/ROOT/pages/ec_validate_vsa.adoc
@@ -60,6 +60,7 @@ mark (?) sign, for example: --output text=output.txt?show-successes=false
 --retry-jitter:: randomness factor for backoff calculation (0.0-1.0) (Default: 0.1)
 --retry-max-retry:: maximum number of retry attempts (Default: 3)
 --retry-max-wait:: maximum wait time between retries (Default: 3s)
+--show-policy-docs-link:: Show link to policy documentation in output when there are violations or warnings (Default: false)
 --show-successes::  (Default: false)
 --show-warnings::  (Default: true)
 --timeout:: max overall execution duration (Default: 5m0s)
diff --git a/internal/applicationsnapshot/report.go b/internal/applicationsnapshot/report.go
@@ -50,19 +50,20 @@ type Component struct {
 }
 
 type Report struct {
-	Success       bool `json:"success"`
-	created       time.Time
-	Snapshot      string                           `json:"snapshot,omitempty"`
-	Components    []Component                      `json:"components"`
-	Key           string                           `json:"key"`
-	Policy        ecc.EnterpriseContractPolicySpec `json:"policy"`
-	EcVersion     string                           `json:"ec-version"`
-	Data          any                              `json:"-"`
-	EffectiveTime time.Time                        `json:"effective-time"`
-	PolicyInput   [][]byte                         `json:"-"`
-	ShowSuccesses bool                             `json:"-"`
-	ShowWarnings  bool                             `json:"-"`
-	Expansion     *ExpansionInfo                   `json:"-"`
+	Success            bool `json:"success"`
+	created            time.Time
+	Snapshot           string                           `json:"snapshot,omitempty"`
+	Components         []Component                      `json:"components"`
+	Key                string                           `json:"key"`
+	Policy             ecc.EnterpriseContractPolicySpec `json:"policy"`
+	EcVersion          string                           `json:"ec-version"`
+	Data               any                              `json:"-"`
+	EffectiveTime      time.Time                        `json:"effective-time"`
+	PolicyInput        [][]byte                         `json:"-"`
+	ShowSuccesses      bool                             `json:"-"`
+	ShowWarnings       bool                             `json:"-"`
+	ShowPolicyDocsLink bool                             `json:"-"`
+	Expansion          *ExpansionInfo                   `json:"-"`
 }
 
 type summary struct {
@@ -128,7 +129,7 @@ var OutputFormats = []string{
 
 // WriteReport returns a new instance of Report representing the state of
 // components from the snapshot.
-func NewReport(snapshot string, components []Component, policy policy.Policy, policyInput [][]byte, showSuccesses bool, showWarnings bool, expansion *ExpansionInfo) (Report, error) {
+func NewReport(snapshot string, components []Component, policy policy.Policy, policyInput [][]byte, showSuccesses bool, showWarnings bool, showPolicyDocsLink bool, expansion *ExpansionInfo) (Report, error) {
 	success := true
 
 	// Set the report success, remains true if all components are successful
@@ -149,18 +150,19 @@ func NewReport(snapshot string, components []Component, policy policy.Policy, po
 	info, _ := version.ComputeInfo()
 
 	return Report{
-		Snapshot:      snapshot,
-		Success:       success,
-		Components:    components,
-		created:       time.Now().UTC(),
-		Key:           string(key),
-		Policy:        policy.Spec(),
-		EcVersion:     info.Version,
-		PolicyInput:   policyInput,
-		EffectiveTime: policy.EffectiveTime().UTC(),
-		ShowSuccesses: showSuccesses,
-		ShowWarnings:  showWarnings,
-		Expansion:     expansion,
+		Snapshot:           snapshot,
+		Success:            success,
+		Components:         components,
+		created:            time.Now().UTC(),
+		Key:                string(key),
+		Policy:             policy.Spec(),
+		EcVersion:          info.Version,
+		PolicyInput:        policyInput,
+		EffectiveTime:      policy.EffectiveTime().UTC(),
+		ShowSuccesses:      showSuccesses,
+		ShowWarnings:       showWarnings,
+		ShowPolicyDocsLink: showPolicyDocsLink,
+		Expansion:          expansion,
 	}, nil
 }
 
diff --git a/internal/applicationsnapshot/report_test.go b/internal/applicationsnapshot/report_test.go
@@ -52,7 +52,7 @@ func Test_ReportJson(t *testing.T) {
 
 	ctx := context.Background()
 	testPolicy := createTestPolicy(t, ctx)
-	report, err := NewReport("snappy", components, testPolicy, nil, true, true, nil)
+	report, err := NewReport("snappy", components, testPolicy, nil, true, true, true, nil)
 	assert.NoError(t, err)
 
 	testEffectiveTime := testPolicy.EffectiveTime().UTC().Format(time.RFC3339Nano)
@@ -110,7 +110,7 @@ func Test_ReportYaml(t *testing.T) {
 
 	ctx := context.Background()
 	testPolicy := createTestPolicy(t, ctx)
-	report, err := NewReport("snappy", components, testPolicy, nil, true, true, nil)
+	report, err := NewReport("snappy", components, testPolicy, nil, true, true, true, nil)
 	assert.NoError(t, err)
 
 	testEffectiveTime := testPolicy.EffectiveTime().UTC().Format(time.RFC3339Nano)
@@ -257,7 +257,7 @@ func Test_GenerateMarkdownSummary(t *testing.T) {
 	for _, c := range cases {
 		t.Run(c.name, func(t *testing.T) {
 			ctx := context.Background()
-			report, err := NewReport(c.snapshot, c.components, createTestPolicy(t, ctx), nil, true, true, nil)
+			report, err := NewReport(c.snapshot, c.components, createTestPolicy(t, ctx), nil, true, true, true, nil)
 			assert.NoError(t, err)
 			report.created = time.Unix(0, 0).UTC()
 
@@ -504,7 +504,7 @@ func Test_ReportSummary(t *testing.T) {
 	for _, tc := range tests {
 		t.Run(fmt.Sprintf("NewReport=%s", tc.name), func(t *testing.T) {
 			ctx := context.Background()
-			report, err := NewReport(tc.snapshot, []Component{tc.input}, createTestPolicy(t, ctx), nil, true, true, nil)
+			report, err := NewReport(tc.snapshot, []Component{tc.input}, createTestPolicy(t, ctx), nil, true, true, true, nil)
 			assert.NoError(t, err)
 			assert.Equal(t, tc.want, report.toSummary())
 		})
@@ -641,7 +641,7 @@ func Test_ReportAppstudio(t *testing.T) {
 			assert.NoError(t, err)
 
 			ctx := context.Background()
-			report, err := NewReport(c.snapshot, c.components, createTestPolicy(t, ctx), nil, true, true, nil)
+			report, err := NewReport(c.snapshot, c.components, createTestPolicy(t, ctx), nil, true, true, true, nil)
 			assert.NoError(t, err)
 			assert.False(t, report.created.IsZero())
 			assert.Equal(t, c.success, report.Success)
@@ -789,7 +789,7 @@ func Test_ReportHACBS(t *testing.T) {
 			assert.NoError(t, err)
 
 			ctx := context.Background()
-			report, err := NewReport(c.snapshot, c.components, createTestPolicy(t, ctx), nil, true, true, nil)
+			report, err := NewReport(c.snapshot, c.components, createTestPolicy(t, ctx), nil, true, true, true, nil)
 			assert.NoError(t, err)
 			assert.False(t, report.created.IsZero())
 			assert.Equal(t, c.success, report.Success)
@@ -821,7 +821,7 @@ func Test_ReportPolicyInput(t *testing.T) {
 	}
 
 	ctx := context.Background()
-	report, err := NewReport("snapshot", nil, createTestPolicy(t, ctx), policyInput, true, true, nil)
+	report, err := NewReport("snapshot", nil, createTestPolicy(t, ctx), policyInput, true, true, true, nil)
 	require.NoError(t, err)
 
 	p := format.NewTargetParser(JSON, format.Options{}, defaultWriter, fs)
@@ -890,8 +890,9 @@ func Test_TextReport(t *testing.T) {
 	}{
 		{"nothing", Report{}},
 		{"bunch", Report{
-			ShowSuccesses: true,
-			ShowWarnings:  true,
+			ShowSuccesses:      true,
+			ShowWarnings:       true,
+			ShowPolicyDocsLink: true,
 			Components: []Component{
 				{
 					SnapshotComponent: app.SnapshotComponent{
@@ -1032,7 +1033,8 @@ func Test_DocumentationLink_OnlySuccesses(t *testing.T) {
 func Test_DocumentationLink_OnlyWarnings(t *testing.T) {
 	// Test case: Only warnings - should show documentation link
 	r := Report{
-		ShowWarnings: true,
+		ShowWarnings:       true,
+		ShowPolicyDocsLink: true,
 		Components: []Component{
 			{
 				Warnings: []evaluator.Result{
@@ -1060,6 +1062,7 @@ func Test_DocumentationLink_OnlyWarnings(t *testing.T) {
 func Test_DocumentationLink_OnlyFailures(t *testing.T) {
 	// Test case: Only failures - should show documentation link
 	r := Report{
+		ShowPolicyDocsLink: true,
 		Components: []Component{
 			{
 				Violations: []evaluator.Result{
@@ -1087,6 +1090,7 @@ func Test_DocumentationLink_OnlyFailures(t *testing.T) {
 func Test_DocumentationLink_WarningsAndFailures(t *testing.T) {
 	// Test case: Both warnings and failures - should show documentation link
 	r := Report{
+		ShowPolicyDocsLink: true,
 		Components: []Component{
 			{
 				Violations: []evaluator.Result{
@@ -1122,8 +1126,9 @@ func Test_DocumentationLink_WarningsAndFailures(t *testing.T) {
 func Test_DocumentationLink_MultipleComponents(t *testing.T) {
 	// Test case: Multiple components with mixed results - should show documentation link
 	r := Report{
-		ShowSuccesses: true,
-		ShowWarnings:  true,
+		ShowSuccesses:      true,
+		ShowWarnings:       true,
+		ShowPolicyDocsLink: true,
 		Components: []Component{
 			{
 				// Component 1: Only successes
@@ -1345,12 +1350,12 @@ func Test_NewReport_ShowWarningsParameter(t *testing.T) {
 	}
 
 	// Test with showWarnings=true
-	report1, err := NewReport("test", components, testPolicy, nil, false, true, nil)
+	report1, err := NewReport("test", components, testPolicy, nil, false, true, true, nil)
 	require.NoError(t, err)
 	assert.True(t, report1.ShowWarnings, "ShowWarnings should be true when passed as true")
 
 	// Test with showWarnings=false
-	report2, err := NewReport("test", components, testPolicy, nil, false, false, nil)
+	report2, err := NewReport("test", components, testPolicy, nil, false, false, true, nil)
 	require.NoError(t, err)
 	assert.False(t, report2.ShowWarnings, "ShowWarnings should be false when passed as false")
 }
diff --git a/internal/input/report.go b/internal/input/report.go
diff --git a/internal/input/report_test.go b/internal/input/report_test.go
diff --git a/internal/validate/report.go b/internal/validate/report.go

Original file line number	Diff line number	Diff line change
`@@ -45,5 +45,6 @@ func NewValidateCmd() *cobra.Command {`
`45`	`45`	`}`
`46`	`46`	`validateCmd.PersistentFlags().Bool("show-successes", false, "")`
`47`	`47`	`validateCmd.PersistentFlags().Bool("show-warnings", true, "")`
	`48`	`+ validateCmd.PersistentFlags().Bool("show-policy-docs-link", false, "Show link to policy documentation in output when there are violations or warnings")`
`48`	`49`	`return validateCmd`
`49`	`50`	`}`