Refactor code to take into account optional fields

Refactor code so we are not passing in values and only using the defaults from the module config

Show parent field if there are no child fields to show

We want to show the labels field (among others) in the markdown table if
so that it is part of the documentation rather than showing all the
preset labels as individual fields in the docs.

Signed-off-by: Luke Mallon (Nalum) <luke@mallon.ie>

Update schema with +nodoc tags and copy to blueprint starter module

Hide certain fields

This change brings the output more inline with the definition

Update output to remove default column

Commit updated test data

Signed-off-by: Luke Mallon (Nalum) <luke@mallon.ie>

Update nodoc behaviour

Signed-off-by: Luke Mallon (Nalum) <luke@mallon.ie>

Update structure to accomodate nodoc

Signed-off-by: Luke Mallon (Nalum) <luke@mallon.ie>

Merge branch 'main' into module-md-optional-fields

Author: nalum

blueprints/starter/README.md

@@ -30,6 +30,7 @@ import (
 
 	// Reference is the image address computed from repository, tag and digest
 	// in the format [REPOSITORY]:[TAG]@[DIGEST].
+	// +nodoc
 	reference: string
 
 	if digest != "" && tag != "" {

blueprints/starter/cue.mod/pkg/timoni.sh/core/v1alpha1/image.cue

@@ -43,13 +43,17 @@ import "strings"
 
 	// Standard Kubernetes labels: app name, version and managed-by.
 	labels: {
-		(#StdLabelName):      name
-		(#StdLabelVersion):   #Version
+		// +nodoc
+		(#StdLabelName): name
+		// +nodoc
+		(#StdLabelVersion): #Version
+		// +nodoc
 		(#StdLabelManagedBy): "timoni"
 	}
 
 	// LabelSelector selects Pods based on the app.kubernetes.io/name label.
 	#LabelSelector: #Labels & {
+		// +nodoc
 		(#StdLabelName): name
 	}
 
@@ -74,6 +78,7 @@ import "strings"
 	namespace: #Meta.namespace
 
 	labels: #Meta.labels
+	// +nodoc
 	labels: (#StdLabelComponent): #Component
 
 	annotations?: #Annotations
@@ -84,8 +89,10 @@ import "strings"
 	// LabelSelector selects Pods based on the app.kubernetes.io/name
 	// and app.kubernetes.io/component labels.
 	#LabelSelector: #Labels & {
+		// +nodoc
 		(#StdLabelComponent): #Component
-		(#StdLabelName):      #Meta.name
+		// +nodoc
+		(#StdLabelName): #Meta.name
 	}
 }
 
@@ -104,6 +111,7 @@ import "strings"
 	name: #Meta.name + "-" + #Component
 
 	labels: #Meta.labels
+	// +nodoc
 	labels: (#StdLabelComponent): #Component
 
 	annotations?: #Annotations
@@ -114,7 +122,9 @@ import "strings"
 	// LabelSelector selects Pods based on the app.kubernetes.io/name
 	// and app.kubernetes.io/component labels.
 	#LabelSelector: #Labels & {
+		// +nodoc
 		(#StdLabelComponent): #Component
-		(#StdLabelName):      #Meta.name
+		// +nodoc
+		(#StdLabelName): #Meta.name
 	}
 }

blueprints/starter/cue.mod/pkg/timoni.sh/core/v1alpha1/metadata.cue

@@ -15,5 +15,8 @@ package v1alpha1
 	labels: #Labels
 
 	// Standard Kubernetes label: app name.
-	labels: (#StdLabelName): #Name
+	labels: {
+		// +nodoc
+		(#StdLabelName): #Name
+	}
 }

blueprints/starter/cue.mod/pkg/timoni.sh/core/v1alpha1/selector.cue

@@ -21,9 +21,11 @@ import (
 	let minMajor = strconv.Atoi(strings.Split(#Minimum, ".")[0])
 	let minMinor = strconv.Atoi(strings.Split(#Minimum, ".")[1])
 
+	// +nodoc
 	major: int & >=minMajor
 	major: strconv.Atoi(strings.Split(#Version, ".")[0])
 
+	// +nodoc
 	minor: int & >=minMinor
 	minor: strconv.Atoi(strings.Split(#Version, ".")[1])
 }

blueprints/starter/cue.mod/pkg/timoni.sh/core/v1alpha1/semver.cue

@@ -9,13 +9,16 @@ import (
 #Config: {
 	// The kubeVersion is a required field, set at apply-time
 	// via timoni.cue by querying the user's Kubernetes API.
+	// +nodoc
 	kubeVersion!: string
 	// Using the kubeVersion you can enforce a minimum Kubernetes minor version.
 	// By default, the minimum Kubernetes version is set to 1.20.
+	// +nodoc
 	clusterVersion: timoniv1.#SemVer & {#Version: kubeVersion, #Minimum: "1.20.0"}
 
 	// The moduleVersion is set from the user-supplied module version.
 	// This field is used for the `app.kubernetes.io/version` label.
+	// +nodoc
 	moduleVersion!: string
 
 	// The Kubernetes metadata common to all resources.

blueprints/starter/templates/config.cue

@@ -124,17 +124,16 @@ func runConfigShowModCmd(cmd *cobra.Command, args []string) error {
 		return fmt.Errorf("build failed: %w", err)
 	}
 
-	buildResult, err := builder.Build()
+	_, err = builder.Build()
 	if err != nil {
 		return describeErr(f.GetModuleRoot(), "validation failed", err)
 	}
-
-	rows, err := builder.GetConfigDoc(buildResult)
+	rows, err := builder.GetConfigDoc()
 	if err != nil {
 		return describeErr(f.GetModuleRoot(), "failed to get config structure", err)
 	}
 
-	header := []string{"Key", "Type", "Default", "Description"}
+	header := []string{"Key", "Type", "Description"}
 
 	if configShowModArgs.output == "" {
 		printMarkDownTable(rootCmd.OutOrStdout(), header, rows)
@@ -166,7 +165,6 @@ func writeFile(readFile string, header []string, rows [][]string, f fetcher.Fetc
 	if err != nil {
 		if errors.Is(err, fs.ErrNotExist) {
 			inputFile, err = os.Create(readFile)
-
 			if err != nil {
 				return "", describeErr(f.GetModuleRoot(), "Unable to create the temporary output file", err)
 			}

cmd/timoni/mod_show_config.go

@@ -41,15 +41,15 @@ timoni -n module delete module
 
 ## Configuration
 
-| KEY                          | TYPE     | DEFAULT                                                                     | DESCRIPTION                                                                                                                                                                                                                                   |
-|------------------------------|----------|-----------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `client: enabled:`           | `bool`   | `true`                                                                      |                                                                                                                                                                                                                                               |
-| `client: image: repository:` | `string` | `"cgr.dev/chainguard/timoni"`                                               | Repository is the address of a container registry repository. An image repository is made up of slash-separated name components, optionally prefixed by a registry hostname and port in the format [HOST[:PORT_NUMBER]/]PATH.                 |
-| `client: image: tag:`        | `string` | `"latest-dev"`                                                              | Tag identifies an image in the repository. A tag name may contain lowercase and uppercase characters, digits, underscores, periods and dashes. A tag name may not start with a period or a dash and may contain a maximum of 128 characters.  |
-| `client: image: digest:`     | `string` | `"sha256:b49fbaac0eedc22c1cfcd26684707179cccbed0df205171bae3e1bae61326a10"` | Digest uniquely and immutably identifies an image in the repository. Spec: https://github.com/opencontainers/image-spec/blob/main/descriptor.md#digests.                                                                                      |
-| `client: image: pullPolicy:` | `string` | `"IfNotPresent"`                                                            | PullPolicy defines the pull policy for the image. By default, it is set to IfNotPresent.                                                                                                                                                      |
-| `server: enabled:`           | `bool`   | `true`                                                                      |                                                                                                                                                                                                                                               |
-| `domain:`                    | `string` | `"example.internal"`                                                        |                                                                                                                                                                                                                                               |
-| `globals: enabled:`          | `bool`   | `false`                                                                     |                                                                                                                                                                                                                                               |
-| `team:`                      | `string` | `"test"`                                                                    |                                                                                                                                                                                                                                               |
+| KEY                          | TYPE                                                                                   | DESCRIPTION                                                                                                                                                                                                                                   |
+|------------------------------|----------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `client: enabled:`           | `*true \| bool`                                                                        |                                                                                                                                                                                                                                               |
+| `client: image: repository:` | `*"cgr.dev/chainguard/timoni" \| string`                                               | Repository is the address of a container registry repository. An image repository is made up of slash-separated name components, optionally prefixed by a registry hostname and port in the format [HOST[:PORT_NUMBER]/]PATH.                 |
+| `client: image: tag:`        | `*"latest-dev" \| strings.MaxRunes(128)`                                               | Tag identifies an image in the repository. A tag name may contain lowercase and uppercase characters, digits, underscores, periods and dashes. A tag name may not start with a period or a dash and may contain a maximum of 128 characters.  |
+| `client: image: digest:`     | `*"sha256:b49fbaac0eedc22c1cfcd26684707179cccbed0df205171bae3e1bae61326a10" \| string` | Digest uniquely and immutably identifies an image in the repository. Spec: https://github.com/opencontainers/image-spec/blob/main/descriptor.md#digests.                                                                                      |
+| `client: image: pullPolicy:` | `*"IfNotPresent" \| "Always" \| "Never"`                                               | PullPolicy defines the pull policy for the image. By default, it is set to IfNotPresent.                                                                                                                                                      |
+| `server: enabled:`           | `*true \| bool`                                                                        |                                                                                                                                                                                                                                               |
+| `domain:`                    | `*"example.internal" \| string`                                                        |                                                                                                                                                                                                                                               |
+| `globals: enabled:`          | `*false \| bool`                                                                       |                                                                                                                                                                                                                                               |
+| `team:`                      | `"test"`                                                                               |                                                                                                                                                                                                                                               |
 

cmd/timoni/testdata/module/README.md

@@ -23,25 +23,21 @@ import (
 		"app.kubernetes.io/team": team
 	}
 
-	// +nodoc
 	client: {
 		enabled: *true | bool
 
-		// +nodoc
 		image: timoniv1.#Image & {
 			repository: *"cgr.dev/chainguard/timoni" | string
 			tag:        *"latest-dev" | string
 			digest:     *"sha256:b49fbaac0eedc22c1cfcd26684707179cccbed0df205171bae3e1bae61326a10" | string
 		}
 	}
 
-	// +nodoc
 	server: {
 		enabled: *true | bool
 	}
 	domain: *"example.internal" | string
 
-	// +nodoc
 	globals: {
 		enabled: *false | bool
 	}

cmd/timoni/testdata/module/templates/config.cue

@@ -0,0 +1,189 @@
+/*
+Copyright 2023 Stefan Prodan
+
+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 engine
+
+import (
+	"errors"
+	"fmt"
+	"regexp"
+	"strings"
+
+	"cuelang.org/go/cue"
+	"cuelang.org/go/cue/ast"
+	"cuelang.org/go/cue/load"
+
+	apiv1 "github.com/stefanprodan/timoni/api/v1alpha1"
+)
+
+// GetConfigDoc extracts the config structure from the module.
+func (b *ModuleBuilder) GetConfigDoc() ([][]string, error) {
+	var value cue.Value
+
+	cfg := &load.Config{
+		ModuleRoot: b.moduleRoot,
+		Package:    b.pkgName,
+		Dir:        b.pkgPath,
+		DataFiles:  true,
+		Tags: []string{
+			"name=" + b.name,
+			"namespace=" + b.namespace,
+		},
+		TagVars: map[string]load.TagVar{
+			"moduleVersion": {
+				Func: func() (ast.Expr, error) {
+					return ast.NewString(b.moduleVersion), nil
+				},
+			},
+			"kubeVersion": {
+				Func: func() (ast.Expr, error) {
+					return ast.NewString(b.kubeVersion), nil
+				},
+			},
+		},
+	}
+
+	modInstances := load.Instances([]string{}, cfg)
+	if len(modInstances) == 0 {
+		return nil, errors.New("no instances found")
+	}
+
+	modInstance := modInstances[0]
+	if modInstance.Err != nil {
+		return nil, fmt.Errorf("instance error: %w", modInstance.Err)
+	}
+
+	value = b.ctx.BuildInstance(modInstance)
+	if value.Err() != nil {
+		return nil, value.Err()
+	}
+
+	cfgValues := value.LookupPath(cue.ParsePath(apiv1.ConfigValuesSelector.String()))
+	if cfgValues.Err() != nil {
+		return nil, fmt.Errorf("lookup %s failed: %w", apiv1.ConfigValuesSelector, cfgValues.Err())
+	}
+
+	rows, err := iterateFields(cfgValues)
+	if err != nil {
+		return nil, err
+	}
+
+	return rows, nil
+}
+
+func iterateFields(v cue.Value) ([][]string, error) {
+	var rows [][]string
+
+	fields, err := v.Fields(
+		cue.Optional(true),
+		cue.Concrete(true),
+		cue.Docs(true),
+	)
+	if err != nil {
+		return nil, fmt.Errorf("Cue Fields Error: %w", err)
+	}
+
+	for fields.Next() {
+		v := fields.Value()
+		_, noDoc := hasNoDoc(v)
+
+		if noDoc {
+			continue
+		}
+
+		// We are chekcing if the field is a struct and not optional and is concrete before we iterate through it
+		// this allows for definition of default values as full structs without generating output for each
+		// field in the struct where it doesn't make sense e.g.
+		//
+		// - annotations?: {[string]: string}
+		// - affinity: corev1.Affinity | *{nodeAffinity: requiredDuringSchedulingIgnoredDuringExecution: nodeSelectorTerms: [...]}
+		if v.IncompleteKind() == cue.StructKind && !fields.IsOptional() && v.IsConcrete() {
+			//if _, ok := v.Default(); v.IncompleteKind() == cue.StructKind && !fields.IsOptional() && ok {
+			// Assume we want to use the field
+			useField := true
+			iRows, err := iterateFields(v)
+
+			if err != nil {
+				return nil, err
+			}
+
+			for _, row := range iRows {
+				if len(row) > 0 {
+					// If we have a row with more than 0 elements, we don't want to use the field and should use the child rows instead
+					useField = false
+					rows = append(rows, row)
+				}
+			}
+
+			if useField {
+				rows = append(rows, getField(v))
+			}
+		} else {
+			rows = append(rows, getField(v))
+		}
+	}
+
+	return rows, nil
+}
+
+func hasNoDoc(v cue.Value) (string, bool) {
+	var noDoc bool
+	var doc string
+
+	for _, d := range v.Doc() {
+		if line := len(d.List) - 1; line >= 0 {
+			switch d.List[line].Text {
+			case "// +nodoc":
+				noDoc = true
+				break
+			}
+		}
+
+		doc += d.Text()
+		doc = strings.ReplaceAll(doc, "\n", " ")
+		doc = strings.ReplaceAll(doc, "+required", "")
+		doc = strings.ReplaceAll(doc, "+optional", "")
+	}
+
+	return doc, noDoc
+}
+
+func getField(v cue.Value) []string {
+	var row []string
+	labelDomain := regexp.MustCompile(`^([a-zA-Z0-9-_.]+)?(".+")?$`)
+	doc, noDoc := hasNoDoc(v)
+
+	if !noDoc {
+		fieldType := strings.ReplaceAll(fmt.Sprintf("%v", v), "\n", "")
+		fieldType = strings.ReplaceAll(fieldType, "|", "\\|")
+		fieldType = strings.ReplaceAll(fieldType, "\":", "\": ")
+		fieldType = strings.ReplaceAll(fieldType, "\":[", "\": [")
+		fieldType = strings.ReplaceAll(fieldType, "},", "}, ")
+
+		if len(fieldType) == 0 {
+			fieldType = " "
+		}
+
+		field := strings.Replace(v.Path().String(), "timoni.instance.config.", "", 1)
+		match := labelDomain.FindStringSubmatch(field)
+
+		row = append(row, fmt.Sprintf("`%s:`", strings.ReplaceAll(match[1], ".", ": ")+match[2]))
+		row = append(row, fmt.Sprintf("`%s`", fieldType))
+		row = append(row, fmt.Sprintf("%s", doc))
+	}
+
+	return row
+}