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

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)

features/validate_image.feature

@@ -437,7 +437,7 @@ Feature: evaluate enterprise contract
       ]
     }
     """
-    When ec command is run with "validate image --image ${REGISTRY}/acceptance/image --policy acceptance/ec-policy --rekor-url ${REKOR} --public-key ${known_PUBLIC_KEY} --info --show-successes --output text=${TMPDIR}/output.txt --color --output json"
+    When ec command is run with "validate image --image ${REGISTRY}/acceptance/image --policy acceptance/ec-policy --rekor-url ${REKOR} --public-key ${known_PUBLIC_KEY} --info --show-successes --show-policy-docs-link --output text=${TMPDIR}/output.txt --color --output json"
     Then the exit status should be 1
     Then the output should match the snapshot
     # Throw in some test coverage for `--output text` here
@@ -1319,7 +1319,7 @@ Feature: evaluate enterprise contract
       ]
     }
     """
-    When ec command is run with "validate image --image ${REGISTRY}/acceptance/image --policy acceptance/ec-policy --rekor-url ${REKOR} --public-key ${known_PUBLIC_KEY} --output text?show-successes=false --output json=${TMPDIR}/output.json --show-successes"
+    When ec command is run with "validate image --image ${REGISTRY}/acceptance/image --policy acceptance/ec-policy --rekor-url ${REKOR} --public-key ${known_PUBLIC_KEY} --show-policy-docs-link --output text?show-successes=false --output json=${TMPDIR}/output.json --show-successes"
     Then the exit status should be 1
      And the output should match the snapshot
      And the "${TMPDIR}/output.json" file should match the snapshot

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
 }
 
@@ -264,6 +266,7 @@ func (r *Report) toSummary() summary {
 func (r *Report) applyOptions(opts format.Options) {
 	r.ShowSuccesses = opts.ShowSuccesses
 	r.ShowWarnings = opts.ShowWarnings
+	r.ShowPolicyDocsLink = opts.ShowPolicyDocsLink
 }
 
 // condensedMsg reduces repetitive error messages.