Add additional documentation (open-policy-agent#256)

downloader/detect_oci.go

@@ -9,6 +9,7 @@ import (
 // them into URLs that the OCI getter can understand.
 type OCIDetector struct{}
 
+// Detect will detect if the source is an OCI registry
 func (d *OCIDetector) Detect(src, _ string) (string, bool, error) {
 	if len(src) == 0 {
 		return "", false, nil
@@ -17,7 +18,7 @@ func (d *OCIDetector) Detect(src, _ string) (string, bool, error) {
 	if strings.Contains(src, "azurecr.io/") || strings.Contains(src, "127.0.0.1:5000") {
 		url, err := d.detectHTTP(src)
 		if err != nil {
-			return "", false, err
+			return "", false, fmt.Errorf("detect http: %w", err)
 		}
 
 		return url, true, nil
@@ -27,7 +28,6 @@ func (d *OCIDetector) Detect(src, _ string) (string, bool, error) {
 }
 
 func (d *OCIDetector) detectHTTP(src string) (string, error) {
-	// Check validity of url and tag with :latest if no tag is available
 	parts := strings.Split(src, "/")
 	if len(parts) < 2 {
 		return "", fmt.Errorf(

downloader/downloader.go

@@ -3,7 +3,6 @@ package downloader
 import (
 	"context"
 
-	"github.com/containerd/containerd/log"
 	getter "github.com/hashicorp/go-getter"
 )
 
@@ -32,7 +31,6 @@ var getters = map[string]getter.Getter{
 func Download(ctx context.Context, dst string, urls []string) error {
 	opts := []getter.ClientOption{}
 	for _, url := range urls {
-		log.G(ctx).Debugf("Initializing go-getter client with url %v and dst %v", url, dst)
 		client := &getter.Client{
 			Ctx:       ctx,
 			Src:       url,

downloader/get_oci.go

@@ -7,21 +7,23 @@ import (
 	"net/url"
 	"os"
 
-	"github.com/containerd/containerd/log"
 	auth "github.com/deislabs/oras/pkg/auth/docker"
 	"github.com/deislabs/oras/pkg/content"
 	"github.com/deislabs/oras/pkg/oras"
 	getter "github.com/hashicorp/go-getter"
 )
 
+// OCIGetter is responsible for handling OCI repositories
 type OCIGetter struct {
 	client *getter.Client
 }
 
+// ClientMode returns the client mode directory
 func (g *OCIGetter) ClientMode(u *url.URL) (getter.ClientMode, error) {
 	return getter.ClientModeDir, nil
 }
 
+// Get gets the repository as the specified url
 func (g *OCIGetter) Get(path string, u *url.URL) error {
 	ctx := g.Context()
 
@@ -48,7 +50,6 @@ func (g *OCIGetter) Get(path string, u *url.URL) error {
 	defer fileStore.Close()
 
 	repository := u.Host + u.Path
-	log.G(ctx).Infof("Downloading: %s\n", repository)
 	_, _, err = oras.Pull(ctx, resolver, repository, fileStore)
 	if err != nil {
 		return fmt.Errorf("pulling policy: %w", err)
@@ -57,12 +58,13 @@ func (g *OCIGetter) Get(path string, u *url.URL) error {
 	return nil
 }
 
+// GetFile is currently a NOOP
 func (g *OCIGetter) GetFile(dst string, u *url.URL) error {
-	// NOOP for now
 	return nil
 }
 
-//These methods are normally handled by the base getter in go-getter but
+// SetClient sets the client for the OCIGetter
+// NOTE: These methods are normally handled by the base getter in go-getter but
 // the base getter is not exported
 func (g *OCIGetter) SetClient(c *getter.Client) { g.client = c }
 

go.mod

@@ -7,7 +7,7 @@ require (
 	github.com/BurntSushi/toml v0.3.1
 	github.com/KeisukeYamashita/go-vcl v0.4.0
 	github.com/basgys/goxml2json v1.1.0
-	github.com/containerd/containerd v1.3.2
+	github.com/containerd/containerd v1.3.2 // indirect
 	github.com/deislabs/oras v0.8.0
 	github.com/ghodss/yaml v1.0.0
 	github.com/go-akka/configuration v0.0.0-20190919102339-a31c845c4b1b

internal/commands/output.go

@@ -30,55 +30,55 @@ func ValidOutputs() []string {
 }
 
 // GetOutputManager returns the OutputManager based on the user input
-func GetOutputManager(outFmt string, color bool) OutputManager {
-	switch outFmt {
+func GetOutputManager(outputFormat string, color bool) OutputManager {
+	switch outputFormat {
 	case outputSTD:
-		return NewDefaultStdOutputManager(color)
+		return NewDefaultStandardOutputManager(color)
 	case outputJSON:
 		return NewDefaultJSONOutputManager()
 	case outputTAP:
 		return NewDefaultTAPOutputManager()
 	case outputTable:
 		return NewDefaultTableOutputManager()
 	default:
-		return NewDefaultStdOutputManager(color)
+		return NewDefaultStandardOutputManager(color)
 	}
 }
 
-// OutputManager controls how results of the `ccheck` evaluation will be recorded
-// and reported to the end user.
+// OutputManager controls how results of an evaluation will be recorded and reported to the end user
 type OutputManager interface {
 	Put(cr CheckResult) error
 	Flush() error
 }
 
-type stdOutputManager struct {
+// StandardOutputManager writes to stdout
+type StandardOutputManager struct {
 	logger  *log.Logger
 	color   aurora.Aurora
 	results []CheckResult
 }
 
-// NewDefaultStdOutputManager instantiates a new instance of stdOutputManager
-// using the default logger.
-func NewDefaultStdOutputManager(color bool) *stdOutputManager {
-	return NewStdOutputManager(log.New(os.Stdout, "", 0), color)
+// NewDefaultStandardOutputManager creates a new StandardOutputManager using the default logger
+func NewDefaultStandardOutputManager(color bool) *StandardOutputManager {
+	return NewStandardOutputManager(log.New(os.Stdout, "", 0), color)
 }
 
-// NewStdOutputManager constructs an instance of stdOutputManager given a
-// logger instance.
-func NewStdOutputManager(l *log.Logger, color bool) *stdOutputManager {
-	return &stdOutputManager{
+// NewStandardOutputManager creates a new StandardOutputManager given a logger instance
+func NewStandardOutputManager(l *log.Logger, color bool) *StandardOutputManager {
+	return &StandardOutputManager{
 		logger: l,
 		color:  aurora.NewAurora(color),
 	}
 }
 
-func (s *stdOutputManager) Put(cr CheckResult) error {
+// Put puts the result of the check to the manager in the managers buffer
+func (s *StandardOutputManager) Put(cr CheckResult) error {
 	s.results = append(s.results, cr)
 	return nil
 }
 
-func (s *stdOutputManager) Flush() error {
+// Flush writes the contents of the managers buffer to the console
+func (s *StandardOutputManager) Flush() error {
 	var totalPolicies int
 	var totalFailures int
 	var totalWarnings int
@@ -148,25 +148,25 @@ type jsonCheckResult struct {
 	Successes []jsonResult `json:"successes"`
 }
 
-// jsonOutputManager reports `conftest` results to `stdout` as a json array..
-type jsonOutputManager struct {
+// JSONOutputManager formats its output to JSON
+type JSONOutputManager struct {
 	logger *log.Logger
 	data   []jsonCheckResult
 }
 
-func NewDefaultJSONOutputManager() *jsonOutputManager {
+// NewDefaultJSONOutputManager creates a new JSONOutputManager using the default logger
+func NewDefaultJSONOutputManager() *JSONOutputManager {
 	return NewJSONOutputManager(log.New(os.Stdout, "", 0))
 }
 
-func NewJSONOutputManager(l *log.Logger) *jsonOutputManager {
-	return &jsonOutputManager{
+// NewJSONOutputManager creates a new JSONOutputManager with a given logger instance
+func NewJSONOutputManager(l *log.Logger) *JSONOutputManager {
+	return &JSONOutputManager{
 		logger: l,
 	}
 }
 
 func errsToStrings(errs []error) []string {
-	// we explicitly use an empty slice here to ensure that this field will not be
-	// null in json
 	res := []string{}
 	for _, err := range errs {
 		res = append(res, err.Error())
@@ -175,7 +175,8 @@ func errsToStrings(errs []error) []string {
 	return res
 }
 
-func (j *jsonOutputManager) Put(cr CheckResult) error {
+// Put puts the result of the check to the manager in the managers buffer
+func (j *JSONOutputManager) Put(cr CheckResult) error {
 	if cr.FileName == "-" {
 		cr.FileName = ""
 	}
@@ -237,7 +238,8 @@ func (j *jsonOutputManager) Put(cr CheckResult) error {
 	return nil
 }
 
-func (j *jsonOutputManager) Flush() error {
+// Flush writes the contents of the managers buffer to the console
+func (j *JSONOutputManager) Flush() error {
 	b, err := json.Marshal(j.data)
 	if err != nil {
 		return err
@@ -253,25 +255,25 @@ func (j *jsonOutputManager) Flush() error {
 	return nil
 }
 
-type tapOutputManager struct {
+// TAPOutputManager formats its output in TAP format
+type TAPOutputManager struct {
 	logger *log.Logger
 }
 
-// NewDefaultTAPOutputManager instantiates a new instance of tapOutputManager
-// using the default logger.
-func NewDefaultTAPOutputManager() *tapOutputManager {
+// NewDefaultTAPOutputManager creates a new TAPOutputManager using the default logger
+func NewDefaultTAPOutputManager() *TAPOutputManager {
 	return NewTAPOutputManager(log.New(os.Stdout, "", 0))
 }
 
-// NewTAPOutputManager constructs an instance of stdOutputManager given a
-// logger instance.
-func NewTAPOutputManager(l *log.Logger) *tapOutputManager {
-	return &tapOutputManager{
+// NewTAPOutputManager creates a new TAPOutputManager with a given logger instance
+func NewTAPOutputManager(l *log.Logger) *TAPOutputManager {
+	return &TAPOutputManager{
 		logger: l,
 	}
 }
 
-func (s *tapOutputManager) Put(cr CheckResult) error {
+// Put puts the result of the check to the manager in the managers buffer
+func (t *TAPOutputManager) Put(cr CheckResult) error {
 	var indicator string
 	if cr.FileName == "-" {
 		indicator = " - "
@@ -280,31 +282,31 @@ func (s *tapOutputManager) Put(cr CheckResult) error {
 	}
 
 	printResults := func(r Result, prefix string, counter int) {
-		s.logger.Print(prefix, counter, indicator, r.Message)
+		t.logger.Print(prefix, counter, indicator, r.Message)
 		if len(r.Traces) > 0 {
-			s.logger.Print("# Traces")
-			for j, t := range r.Traces {
-				s.logger.Print("trace ", counter, j+1, indicator, t.Error())
+			t.logger.Print("# Traces")
+			for j, trace := range r.Traces {
+				t.logger.Print("trace ", counter, j+1, indicator, trace.Error())
 			}
 		}
 	}
 
 	issues := len(cr.Failures) + len(cr.Warnings) + len(cr.Successes)
 	if issues > 0 {
-		s.logger.Print(fmt.Sprintf("1..%d", issues))
+		t.logger.Print(fmt.Sprintf("1..%d", issues))
 		for i, r := range cr.Failures {
 			printResults(r, "not ok ", i+1)
 
 		}
 		if len(cr.Warnings) > 0 {
-			s.logger.Print("# Warnings")
+			t.logger.Print("# Warnings")
 			for i, r := range cr.Warnings {
 				counter := i + 1 + len(cr.Failures)
 				printResults(r, "not ok ", counter)
 			}
 		}
 		if len(cr.Successes) > 0 {
-			s.logger.Print("# Successes")
+			t.logger.Print("# Successes")
 			for i, r := range cr.Successes {
 				counter := i + 1 + len(cr.Failures) + len(cr.Warnings)
 				printResults(r, "ok ", counter)
@@ -315,36 +317,38 @@ func (s *tapOutputManager) Put(cr CheckResult) error {
 	return nil
 }
 
-func (s *tapOutputManager) Flush() error {
+// Flush is currently a NOOP
+func (t *TAPOutputManager) Flush() error {
 	return nil
 }
 
-type tableOutputManager struct {
+// TableOutputManager formats its output in a table
+type TableOutputManager struct {
 	table *table.Table
 }
 
-// NewDefaultTableOutputManager instantiates a new instance of tableOutputManager
-func NewDefaultTableOutputManager() *tableOutputManager {
+// NewDefaultTableOutputManager creates a new TableOutputManager using standard out
+func NewDefaultTableOutputManager() *TableOutputManager {
 	return NewTableOutputManager(os.Stdout)
 }
 
-// NewTableOutputManager constructs an instance of tableOutputManager given a
-// io.Writer.
-func NewTableOutputManager(w io.Writer) *tableOutputManager {
+// NewTableOutputManager creates a new TableOutputManager with a given Writer
+func NewTableOutputManager(w io.Writer) *TableOutputManager {
 	table := table.NewWriter(w)
 	table.SetHeader([]string{"result", "file", "message"})
-	return &tableOutputManager{
+	return &TableOutputManager{
 		table: table,
 	}
 }
 
-func (s *tableOutputManager) Put(cr CheckResult) error {
+// Put puts the result of the check to the manager in the managers buffer
+func (t *TableOutputManager) Put(cr CheckResult) error {
 	printResults := func(r Result, prefix string, filename string) {
 		d := []string{prefix, filename, r.Error()}
-		s.table.Append(d)
-		for _, t := range r.Traces {
-			dt := []string{"trace", filename, t.Error()}
-			s.table.Append(dt)
+		t.table.Append(d)
+		for _, trace := range r.Traces {
+			dt := []string{"trace", filename, trace.Error()}
+			t.table.Append(dt)
 		}
 	}
 
@@ -363,9 +367,11 @@ func (s *tableOutputManager) Put(cr CheckResult) error {
 	return nil
 }
 
-func (s *tableOutputManager) Flush() error {
-	if s.table.NumLines() > 0 {
-		s.table.Render()
+// Flush writes the contents of the managers buffer to the console
+func (t *TableOutputManager) Flush() error {
+	if t.table.NumLines() > 0 {
+		t.table.Render()
 	}
+
 	return nil
 }

internal/commands/output_test.go

@@ -60,7 +60,7 @@ func Test_stdOutputManager_put(t *testing.T) {
 	for _, tt := range tests {
 		t.Run(tt.msg, func(t *testing.T) {
 			buf := new(bytes.Buffer)
-			s := NewStdOutputManager(log.New(buf, "", 0), false)
+			s := NewStandardOutputManager(log.New(buf, "", 0), false)
 
 			if err := s.Put(tt.args.cr); err != nil {
 				t.Fatalf("put output: %v", err)
@@ -233,7 +233,7 @@ func TestSupportedOutputManagers(t *testing.T) {
 		{
 			name:          "std output should exist",
 			outputFormat:  outputSTD,
-			outputManager: NewDefaultStdOutputManager(true),
+			outputManager: NewDefaultStandardOutputManager(true),
 		},
 		{
 			name:          "json output should exist",
@@ -253,7 +253,7 @@ func TestSupportedOutputManagers(t *testing.T) {
 		{
 			name:          "default output should exist",
 			outputFormat:  "somedefault",
-			outputManager: NewDefaultStdOutputManager(true),
+			outputManager: NewDefaultStandardOutputManager(true),
 		},
 	} {
 		outputManager := GetOutputManager(testunit.outputFormat, true)