proper-docs

Author: edcdavid

cmd/certsuite/check/check.go

@@ -13,6 +13,12 @@ var (
 	}
 )
 
+// NewCommand creates the root check command.
+//
+// It constructs a new cobra.Command instance configured for the certsuite
+// checking functionality. The returned command is ready to have subcommands
+// added to it and can be executed as part of the certsuite CLI. No arguments
+// are required; the function returns a pointer to the created *cobra.Command.
 func NewCommand() *cobra.Command {
 	checkCmd.AddCommand(imagecert.NewCommand())
 	checkCmd.AddCommand(results.NewCommand())

cmd/certsuite/check/image_cert_status/image_cert_status.go

@@ -30,6 +30,16 @@ var checkImageCertStatusCmd = &cobra.Command{
 	RunE:  checkImageCertStatus,
 }
 
+// checkImageCertStatus retrieves image information from flags, validates it,
+// checks whether the container is certified, and prints the status.
+//
+// It expects command-line flags for registry, namespace, repository, and tag,
+// which are obtained via GetString on the cobra.Command flags.
+// The function validates these inputs, then calls IsContainerCertified
+// to determine certification status. It outputs a formatted message
+// indicating whether the image is certified or not, using color helpers
+// for success (green) or failure (red). If validation fails or an error
+// occurs during certification check, it returns an error.
 func checkImageCertStatus(cmd *cobra.Command, _ []string) error {
 	imageName, _ := cmd.Flags().GetString("name")
 	imageRegistry, _ := cmd.Flags().GetString("registry")
@@ -64,6 +74,11 @@ func checkImageCertStatus(cmd *cobra.Command, _ []string) error {
 	return nil
 }
 
+// NewCommand creates and configures a cobra command for checking image certificate status.
+//
+// It returns a pointer to a cobra.Command that includes persistent flags for image,
+// registry, namespace, and other options. The function sets up flag requirements
+// and mutual exclusivity rules before returning the configured command.
 func NewCommand() *cobra.Command {
 	checkImageCertStatusCmd.PersistentFlags().String("name", "", "name of the image to verify")
 	checkImageCertStatusCmd.PersistentFlags().String("registry", "", "registry where the image is stored")

cmd/certsuite/check/results/results.go

@@ -26,12 +26,23 @@ const (
 	resultMiss = "MISSING"
 )
 
+// TestCaseList holds the names of test cases grouped by result status.
+//
+// It contains three slices of strings: Fail, Pass, and Skip,
+// each holding the identifiers of test cases that ended with
+// the corresponding outcome during a certsuite run.
 type TestCaseList struct {
 	Pass []string `yaml:"pass"`
 	Fail []string `yaml:"fail"`
 	Skip []string `yaml:"skip"`
 }
 
+// TestResults represents the collection of test case outcomes.
+//
+// It embeds a TestCaseList to provide access to individual test cases and their
+// execution status. The struct is used to aggregate results from multiple
+// test runs within the certsuite command-line tool, enabling reporting,
+// filtering, and further analysis of test outcomes.
 type TestResults struct {
 	TestCaseList `yaml:"testCases"`
 }
@@ -42,6 +53,12 @@ var checkResultsCmd = &cobra.Command{
 	RunE:  checkResults,
 }
 
+// checkResults compares test results with expected values and writes a report.
+//
+// It retrieves command flags, loads the stored test results from the database,
+// compares them against expected outcomes, and optionally generates a template
+// file. Mismatches are printed to stdout and cause the program to exit with
+// an error status. The function returns an error if any operation fails.
 func checkResults(cmd *cobra.Command, _ []string) error {
 	templateFileName, _ := cmd.Flags().GetString("template")
 	generateTemplate, _ := cmd.Flags().GetBool("generate-template")
@@ -90,6 +107,14 @@ func checkResults(cmd *cobra.Command, _ []string) error {
 	return nil
 }
 
+// getTestResultsDB reads a test results file and returns a map of test identifiers to their outcome.
+//
+// getTestResultsDB parses the specified file path, expecting lines formatted as
+// "testID: result". It returns a map where each key is the test identifier and
+// the value is one of the predefined result constants (pass, fail, skip, miss).
+// If the file cannot be opened or any parsing error occurs, it returns an
+// error describing the problem. The function does not modify the input file
+// and closes it before returning.
 func getTestResultsDB(logFileName string) (map[string]string, error) {
 	resultsDB := make(map[string]string)
 
@@ -124,6 +149,12 @@ func getTestResultsDB(logFileName string) (map[string]string, error) {
 	return resultsDB, nil
 }
 
+// getExpectedTestResults reads a JSON file containing expected test results and returns them as a map.
+//
+// It takes the path to a template file, opens and parses its contents into a
+// map where keys are test identifiers and values are expected result strings.
+// The function returns the populated map or an error if the file cannot be read,
+// the data cannot be unmarshaled, or any other issue occurs.
 func getExpectedTestResults(templateFileName string) (map[string]string, error) {
 	templateFile, err := os.ReadFile(templateFileName)
 	if err != nil {
@@ -150,6 +181,12 @@ func getExpectedTestResults(templateFileName string) (map[string]string, error)
 	return expectedTestResults, nil
 }
 
+// printTestResultsMismatch reports mismatched test results between two sets.
+//
+// It takes three arguments: a slice of test names, a map of expected results,
+// and a map of actual results. The function compares each test's expected
+// outcome with the actual outcome, printing a formatted table that shows
+// which tests passed, failed, were skipped, or missed. No value is returned.
 func printTestResultsMismatch(mismatchedTestCases []string, actualResults, expectedResults map[string]string) {
 	fmt.Printf("\n")
 	fmt.Println(strings.Repeat("-", 96)) //nolint:mnd // table line
@@ -169,6 +206,12 @@ func printTestResultsMismatch(mismatchedTestCases []string, actualResults, expec
 	}
 }
 
+// generateTemplateFile writes a JSON file from the provided map of strings.
+//
+// It creates a temporary buffer, encodes the map as pretty‑printed JSON,
+// and writes the result to a file named by TestResultsTemplateFileName
+// with permissions specified by TestResultsTemplateFilePermissions.
+// If any step fails, it returns an error describing the problem.
 func generateTemplateFile(resultsDB map[string]string) error {
 	var resultsTemplate TestResults
 	for testCase, result := range resultsDB {
@@ -201,6 +244,14 @@ func generateTemplateFile(resultsDB map[string]string) error {
 	return nil
 }
 
+// NewCommand creates the command used to run checks on a set of test results.
+//
+// It returns a *cobra.Command configured with persistent flags that control
+// output formatting, filtering, and other behavior. The command exposes flags
+// for specifying output files, choosing which result states to display,
+// enabling or disabling verbose output, and selecting whether to mark
+// mutually exclusive options. The returned command is intended to be added
+// to the main application’s root command hierarchy.
 func NewCommand() *cobra.Command {
 	checkResultsCmd.PersistentFlags().String("template", "expected_results.yaml", "reference YAML template with the expected results")
 	checkResultsCmd.PersistentFlags().String("log-file", "certsuite.log", "log file of the Certsuite execution")

cmd/certsuite/claim/claim.go

@@ -13,6 +13,12 @@ var (
 	}
 )
 
+// NewCommand creates the root command for the claim subcommand.
+//
+// It constructs a new cobra.Command instance, configures it with
+// usage information and registers any child commands by calling AddCommand.
+// The returned *cobra.Command is ready to be added to the main application
+// command tree.
 func NewCommand() *cobra.Command {
 	claimCommand.AddCommand(compare.NewCommand())
 	claimCommand.AddCommand(show.NewCommand())

cmd/certsuite/claim/compare/compare.go

@@ -86,6 +86,11 @@ var (
 	}
 )
 
+// NewCommand creates a cobra command for comparing two claim files.
+//
+// It defines flags for the first and second claim file paths, marks them as required,
+// and sets up the command to execute the comparison logic when run.
+// The function returns a fully configured *cobra.Command ready to be added to a root command.
 func NewCommand() *cobra.Command {
 	claimCompareFiles.Flags().StringVarP(
 		&Claim1FilePathFlag, "claim1", "1", "",
@@ -109,6 +114,15 @@ func NewCommand() *cobra.Command {
 	return claimCompareFiles
 }
 
+// claimCompare compares two claim files and reports differences.
+//
+// It accepts a cobra.Command pointer and a slice of string arguments, typically
+// the command context and any positional parameters. The function retrieves the
+// file paths from the global flags Claim1FilePathFlag and Claim2FilePathFlag,
+// invokes claimCompareFilesfunc to perform the comparison, and handles errors.
+// On failure it calls Fatal to terminate the program with an error message.
+// The returned error is nil if the comparison succeeds or a non‑nil value
+// indicating a problem during execution.
 func claimCompare(_ *cobra.Command, _ []string) error {
 	err := claimCompareFilesfunc(Claim1FilePathFlag, Claim2FilePathFlag)
 	if err != nil {
@@ -117,6 +131,14 @@ func claimCompare(_ *cobra.Command, _ []string) error {
 	return nil
 }
 
+// claimCompareFilesfunc compares two claim files and reports differences.
+//
+// It reads the file at path1, unmarshals it into a Claim object,
+// then reads the file at path2 and unmarshals that as well.
+// The function uses Compare to compute a diff report between the
+// two claims. If any read or unmarshal error occurs, an error is
+// returned immediately. On success, the diff report is printed to
+// standard output and nil is returned.
 func claimCompareFilesfunc(claim1, claim2 string) error {
 	// readfiles
 	claimdata1, err := os.ReadFile(claim1)
@@ -161,6 +183,12 @@ func claimCompareFilesfunc(claim1, claim2 string) error {
 	return nil
 }
 
+// unmarshalClaimFile reads a claim file from bytes and returns the parsed schema.
+//
+// It accepts a byte slice containing the JSON representation of a claim
+// document, unmarshals it into a claim.Schema structure using the standard
+// encoding/json package, and returns that schema along with any error
+// encountered during decoding. If successful, the returned error is nil.
 func unmarshalClaimFile(claimdata []byte) (claim.Schema, error) {
 	var claimDataResult claim.Schema
 	err := json.Unmarshal(claimdata, &claimDataResult)

cmd/certsuite/claim/compare/configurations/configurations.go

@@ -7,11 +7,20 @@ import (
 	"github.com/redhat-best-practices-for-k8s/certsuite/cmd/certsuite/pkg/claim"
 )
 
+// AbnormalEventsCount holds the number of abnormal events for two claims.
+//
+// It contains integer fields Claim1 and Claim2 that represent the count of
+// abnormal events detected for each respective claim. The String method
+// returns a formatted string summarizing these counts.
 type AbnormalEventsCount struct {
 	Claim1 int `json:"claim1"`
 	Claim2 int `json:"claim2"`
 }
 
+// String returns a human‑readable representation of the abnormal events count.
+//
+// It formats the internal counters into a single string, allowing easy
+// printing or logging of the number of abnormal events recorded.
 func (c *AbnormalEventsCount) String() string {
 	const (
 		rowHeaderFmt = "%-12s%-s\n"
@@ -25,11 +34,23 @@ func (c *AbnormalEventsCount) String() string {
 	return str
 }
 
+// DiffReport represents the result of comparing two configurations.
+//
+// It contains the number of abnormal events detected during the comparison
+// in the AbnormalEvents field, and a pointer to a diff.Diffs value that
+// describes the differences between the two configuration objects.
+// The String method returns a human‑readable summary of the report.
 type DiffReport struct {
 	Config         *diff.Diffs         `json:"CertSuiteConfig"`
 	AbnormalEvents AbnormalEventsCount `json:"abnormalEventsCount"`
 }
 
+// String returns a human‑readable representation of the DiffReport.
+//
+// It formats the differences between two configuration sets into a single
+// string, suitable for printing or logging. The returned value is a plain
+// text description that lists added, removed, and changed items in a
+// readable layout.
 func (d *DiffReport) String() string {
 	str := "CONFIGURATIONS\n"
 	str += "--------------\n\n"
@@ -42,6 +63,11 @@ func (d *DiffReport) String() string {
 	return str
 }
 
+// GetDiffReport produces a diff report between two configuration sets.
+//
+// It compares the first configuration set with the second and returns a DiffReport
+// that summarizes differences, additions, and removals. The returned value contains
+// details of what changed and is nil if an error occurs during comparison.
 func GetDiffReport(claim1Configurations, claim2Configurations *claim.Configurations) *DiffReport {
 	return &DiffReport{
 		Config: diff.Compare("Cert Suite Configuration", claim1Configurations.Config, claim2Configurations.Config, nil),

cmd/certsuite/claim/compare/diff/diff.go

@@ -8,8 +8,9 @@ import (
 	"strings"
 )
 
-// Diffs holds the differences between two interface{} objects that have
-// been obtained by unmarshalling JSON strings.
+// Diffs holds the differences between two JSON objects that have been unmarshalled into interface{} values.
+//
+// It records three slices: Fields contains field-by-field differences with their values from each object; FieldsInClaim1Only lists fields present only in the first object; and FieldsInClaim2Only lists fields present only in the second. The Name field can be used to label the comparison when rendering or logging.
 type Diffs struct {
 	// Name of the json object whose diffs are stored here.
 	// It will be used when serializing the data in table format.
@@ -21,32 +22,24 @@ type Diffs struct {
 	FieldsInClaim2Only []string
 }
 
-// FieldDIff holds the field path and the values from both claim files
-// that have been found to be different.
+// FieldDiff holds information about a field that differs between two claim files.
+//
+// It stores the path of the differing field and the corresponding values from each claim file.
 type FieldDiff struct {
 	FieldPath   string      `json:"field"`
 	Claim1Value interface{} `json:"claim1Value"`
 	Claim2Value interface{} `json:"claim2Value"`
 }
 
-// Stringer method. The output string is a table like this:
-// <name>: Differences
-// FIELD                           CLAIM 1     CLAIM 2
-// /jsonpath/to/field1             value1      value2
-// /jsonpath/to/another/field2     value3      value4
-// ...
-//
-// <name>: Only in CLAIM 1
-// /jsonpath/to/field/in/claim1/only
-// ...
-//
-// <name>: Only in CLAIM 2
-// /jsonpath/to/field/in/claim2/only
-// ...
+// String returns a formatted table showing the differences between two claims.
 //
-// Where <name> is replaced by the value of d.Name.
-// The columns "FIELD" and "CLAIM 1" have a dynamic width that depends
-// on the longest field path and longest value.
+// It generates a multi-line string that lists fields present in both claims with
+// their differing values, as well as fields unique to each claim.
+// The output is organized into sections titled "<name>: Differences",
+// "<name>: Only in CLAIM 1", and "<name>: Only in CLAIM 2", where <name> is the
+// value of d.Name. Columns are padded to accommodate the longest field path
+// and value, ensuring a readable table layout. This method implements the
+// Stringer interface for Diffs.
 func (d *Diffs) String() string {
 	const (
 		noDiffs        = "<none>"
@@ -110,13 +103,13 @@ func (d *Diffs) String() string {
 	return str
 }
 
-// Compares to interface{} objects obtained through json.Unmarshal() and returns
-// a pointer to a Diffs object.
-// A simple filtering of json subtrees can be achieved using the filters slice parameter.
-// This might be helpful with big json trees that could have too many potential differences,
-// but we want to get just the differences for some custom nodes/subtrees.
-// E.g.: filters = []string{"labels"} : only the nodes/subtrees under all the
-// labels nodes/branches will be traversed and compared.
+// Compare compares two interface{} objects obtained through json.Unmarshal() and returns a pointer to a Diffs object.
+//
+// It accepts a JSON path string, the left and right interface values to compare,
+// and an optional slice of filter strings that restrict traversal to specific subtrees.
+// Only nodes whose paths match any filter are examined; all other parts of the trees are ignored.
+// The function walks both structures in parallel, records differences into a Diffs instance,
+// and returns a pointer to that instance for further inspection.
 func Compare(objectName string, claim1Object, claim2Object interface{}, filters []string) *Diffs {
 	objectsDiffs := Diffs{Name: objectName}
 
@@ -163,13 +156,26 @@ func Compare(objectName string, claim1Object, claim2Object interface{}, filters
 	return &objectsDiffs
 }
 
+// field represents a leaf node in a nested structure, storing its path and value.
+//
+// It is used internally by the traversal logic to capture each terminal field
+// encountered during a recursive walk of an arbitrary data structure.
+// The Path field holds the dot‑separated string that identifies the location
+// of the value within the original object. Value contains the actual leaf
+// value, which may be any Go type.
 type field struct {
 	Path  string
 	Value interface{}
 }
 
-// Helper function that traverses recursively a node to return a list
-// of each field (leaf) path and its value.
+// traverse recursively walks a node, returning each leaf field's path and value.
+//
+// It accepts an interface{} representing the current node, a string prefix
+// for building the field path, and a slice of strings that holds the
+// accumulated paths so far. The function returns a slice of field structs,
+// each containing a full path to a leaf node and its corresponding value.
+// This helper is used to flatten nested structures into a list of
+// key/value pairs for comparison purposes.
 func traverse(node interface{}, path string, filters []string) []field {
 	if node == nil {
 		return nil