✨ Feature [experimental]: The Scorecard Dependencydiff CLI (Version 0 Part 1)

e2e/dependencydiff_test.go

@@ -30,6 +30,7 @@ const (
 	head    = "1989568f93e484f6a86f8b276b170e3d6962ce12"
 )
 
+// TODO (#2087): More e2e tests and a potnetial refactoring needed for the func getScorecardCheckResults.
 var _ = Describe("E2E TEST:"+dependencydiff.Depdiff, func() {
 	Context("E2E TEST:Validating use of the dependency-diff API", func() {
 		It("Should return a slice of dependency-diff checking results", func() {

options/depdiff_flags.go

@@ -0,0 +1,57 @@
+// Copyright 2022 Security Scorecard Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// Package options implements Scorecard options.
+package options
+
+import (
+	"github.com/spf13/cobra"
+)
+
+const (
+	// FlagBase is the flag name for specifying a dependency-diff base.
+	FlagBase = "base"
+
+	// FlagHead is the flag name for specifying a dependency-diff head.
+	FlagHead = "head"
+
+	// FlagChangeTypes is the flag name for specifying the change type for
+	// which dependency-diff surfaces the scorecard check results.
+	FlagChangeTypes = "change-types"
+)
+
+// AddDepdiffFlags adds flags to the dependency-diff cobra command.
+func (depOptions *DependencydiffOptions) AddDepdiffFlags(cmd *cobra.Command) {
+	cmd.Flags().StringVar(
+		&depOptions.Base,
+		FlagBase,
+		depOptions.Base,
+		`The base code branch name or the base commitSHA to check. Valid input examples: 
+		main (using a branch name), SHA_VALUE_1 (using a commitSHA)`,
+	)
+	cmd.Flags().StringVar(
+		&depOptions.Head,
+		FlagHead,
+		depOptions.Head,
+		`The head code branch name or the head commitSHA to check. Valid input examples: 
+		dev (using a branch name), SHA_VALUE_2 (using a commitSHA)`,
+	)
+	cmd.Flags().StringSliceVar(
+		&depOptions.ChangeTypes,
+		FlagChangeTypes,
+		depOptions.ChangeTypes,
+		`A list of dependency change types for surfacing the scorecard results. Possible values include: added,removed.
+		If not specified, by default, it will surface scorecard results for both added and removed dependencies.`,
+	)
+}

options/depdiff_options.go

@@ -0,0 +1,92 @@
+// Copyright 2022 Security Scorecard Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// Package options implements Scorecard options.
+package options
+
+import (
+	"errors"
+	"fmt"
+)
+
+// DependencydiffOptions define common options for configuring scorecard dependency-diff.
+type DependencydiffOptions struct {
+	// Base is the base branch name reference or the base commitSHA.
+	Base string
+
+	// Head is the head branch name reference or the head commitSHA.
+	Head string
+
+	// ChangeTypes is an array of dependency change types for specifying what change types the dependency-diff
+	// will surface the scorecard results for.
+	// This is not a required option and can be nullable. If null, we will surface the scorecard results
+	// for all types of dependencies.
+	ChangeTypes []string
+}
+
+var (
+	errBaseIsEmpty       = errors.New("base should be non-empty")
+	errHeadIsEmpty       = errors.New("head should be non-empty")
+	errInvalidChangeType = errors.New("invalid change type")
+)
+
+// NewDepdiff creates a new instance of `DependencydiffOptions`.
+func NewDepdiff() *DependencydiffOptions {
+	depdiffOpts := &DependencydiffOptions{}
+	// No need to do the env.Parse() for a dependency-diff option since there
+	// are no struct env tags for now.
+	return depdiffOpts
+}
+
+// Validate validates scorecard dependency-diff configuration options.
+func (depOptions *DependencydiffOptions) Validate() error {
+	var errs []error
+	// Validate `base` is non-empty.
+	if depOptions.Base == "" {
+		errs = append(
+			errs,
+			errBaseIsEmpty,
+		)
+	}
+	// Validate `head` is non-empty.
+	if depOptions.Head == "" {
+		errs = append(
+			errs,
+			errHeadIsEmpty,
+		)
+	}
+	// ChangeTypes can be null, but users must give valid types if this param is specified.
+	if len(depOptions.ChangeTypes) != 0 {
+		for _, ct := range depOptions.ChangeTypes {
+			if !isChangeTypeValid(ct) {
+				errs = append(
+					errs,
+					errInvalidChangeType,
+				)
+			}
+		}
+	}
+	if len(errs) != 0 {
+		return fmt.Errorf(
+			"%w: %+v",
+			errValidate,
+			errs,
+		)
+	}
+	return nil
+}
+
+func isChangeTypeValid(ct string) bool {
+	return ct == "added" || ct == "removed"
+}

options/flags.go

@@ -67,9 +67,9 @@ type Command interface {
 	AddFlags(cmd *cobra.Command)
 }
 
-// AddFlags adds this options' flags to the cobra command.
+// AddFlags adds this options' flags to the root scorecard cobra command.
 func (o *Options) AddFlags(cmd *cobra.Command) {
-	cmd.Flags().StringVar(
+	cmd.PersistentFlags().StringVar(
 		&o.Repo,
 		FlagRepo,
 		o.Repo,
@@ -136,7 +136,7 @@ func (o *Options) AddFlags(cmd *cobra.Command) {
 	for checkName := range checks.GetAll() {
 		checkNames = append(checkNames, checkName)
 	}
-	cmd.Flags().StringSliceVar(
+	cmd.PersistentFlags().StringSliceVar(
 		&o.ChecksToRun,
 		FlagChecks,
 		o.ChecksToRun,

options/options.go

@@ -20,8 +20,6 @@ import (
 	"fmt"
 	"os"
 
-	"github.com/caarlos0/env/v6"
-
 	"github.com/ossf/scorecard/v4/clients"
 	"github.com/ossf/scorecard/v4/log"
 )
@@ -44,8 +42,9 @@ type Options struct {
 	ShowDetails bool
 
 	// Feature flags.
-	EnableSarif       bool `env:"ENABLE_SARIF"`
-	EnableScorecardV6 bool `env:"SCORECARD_V6"`
+	EnableSarif                 bool `env:"ENABLE_SARIF"`
+	EnableScorecardV6           bool `env:"SCORECARD_V6"`
+	EnableScorecardExperimental bool `env:"SCORECARD_EXPERIMENTAL"`
 }
 
 // New creates a new instance of `Options`.
@@ -93,6 +92,9 @@ const (
 	// EnvVarScorecardV6 is the environment variable which enables scorecard v6
 	// options.
 	EnvVarScorecardV6 = "SCORECARD_V6"
+	// EnvVarScorecardExperimental is the environment variable which enables
+	// scorecard experimental features.
+	EnvVarScorecardExperimental = "SCORECARD_EXPERIMENTAL"
 )
 
 var (
@@ -106,8 +108,9 @@ var (
 	errRepoOptionMustBeSet    = errors.New(
 		"exactly one of `repo`, `npm`, `pypi`, `rubygems` or `local` must be set",
 	)
-	errSARIFNotSupported = errors.New("SARIF format is not supported yet")
-	errValidate          = errors.New("some options could not be validated")
+	errSARIFNotSupported    = errors.New("SARIF format is not supported yet")
+	errValidate             = errors.New("some options could not be validated")
+	errExperimentalDisabled = errors.New("scorecard experimental features are disabled")
 )
 
 // Validate validates scorecard configuration options.
@@ -215,3 +218,16 @@ func validateFormat(format string) bool {
 		return false
 	}
 }
+
+// ValidateExperimental returns true if SCORECARD_EXPERIMENTAL was specified in options or via
+// environment variable.
+func (o *Options) ValidateExperimental() error {
+	_, enabled := os.LookupEnv(EnvVarScorecardExperimental)
+	if !(o.EnableScorecardExperimental || enabled) {
+		return fmt.Errorf(
+			"cannot use this feature: %w",
+			errExperimentalDisabled,
+		)
+	}
+	return nil
+}