Merge pull request #3173 from dheerajodha/EC-1603

feat: Add --show-policy-docs-link flag (default: false)

Author: dheerajodha

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,

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,14 +211,14 @@ 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
 			}
 
 			utils.SetColorEnabled(data.noColor, data.forceColor)
 
-			p := format.NewTargetParser(input.Text, format.Options{ShowSuccesses: showSuccesses, ShowWarnings: showWarnings}, cmd.OutOrStdout(), utils.FS(cmd.Context()))
+			p := format.NewTargetParser(input.Text, format.Options{ShowSuccesses: showSuccesses, ShowWarnings: showWarnings, ShowPolicyDocsLink: showPolicyDocsLink}, cmd.OutOrStdout(), utils.FS(cmd.Context()))
 			if err := report.WriteAll(data.output, p); err != nil {
 				return err
 			}

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
 }

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 {
@@ -1425,8 +1431,9 @@ func determineStatusFromReport(report VSAReport, display ComponentResultsDisplay
 // captureFallbackText captures the text output from a fallback report
 func captureFallbackText(fallbackReport *applicationsnapshot.Report, fs afero.Fs) (string, error) {
 	formatOpts := format.Options{
-		ShowSuccesses: fallbackReport.ShowSuccesses,
-		ShowWarnings:  fallbackReport.ShowWarnings,
+		ShowSuccesses:      fallbackReport.ShowSuccesses,
+		ShowWarnings:       fallbackReport.ShowWarnings,
+		ShowPolicyDocsLink: fallbackReport.ShowPolicyDocsLink,
 	}
 	var fallbackBuf strings.Builder
 	fallbackWriter := &stringWriter{&fallbackBuf}

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{})

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)
 

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)

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)

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)

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)