feat: Define manifest objects examples in code (#477)

## Motivation

We're currently lacking in examples for our `v1alpha` objects.
This PR covers that hole by adding utilities for generating these
examples and verifying them.

## Release Notes

Added extended examples to the `v1alpha` objects with different
configuration variants.

Author: nieomylnieja

Makefile

@@ -107,9 +107,9 @@ check/format:
 	$(call _print_check_step,Checking if files are formatted)
 	./scripts/check-formatting.sh
 
-.PHONY: generate generate/code generate/diagrams
+.PHONY: generate generate/code generate/examples generate/plantuml
 ## Auto generate files.
-generate: generate/code generate/plantuml
+generate: generate/code generate/examples generate/plantuml
 
 ## Generate Golang code.
 generate/code:
@@ -119,6 +119,11 @@ generate/code:
 	go generate ./... ./docs/mock_example
 	${MAKE} format/go
 
+## Generate examples from code.
+generate/examples:
+	echo "Generating examples..."
+	go run internal/cmd/examplegen/main.go
+
 PLANTUML_JAR_URL := https://sourceforge.net/projects/plantuml/files/plantuml.jar/download
 PLANTUML_JAR :=  $(BIN_DIR)/plantuml.jar
 DIAGRAMS_PATH ?= .

cspell.yaml

@@ -17,6 +17,7 @@ ignoreRegExpList:
   - /nolint.*/g
   - /nosec.*/g
   - /(errors|fmt|assert|require)\.[^\(]+/g
+  - /access(key)?id.*/ig
 ignorePaths:
   - sdk/test_data
   - .golangci.yml
@@ -30,7 +31,13 @@ ignorePaths:
   - "**/test_data/**"
   - "docs/mock_example/mocks/*"
 words:
+  - 00u2y4e4atkzaYkXP4x8
+  - CONNECTIONFAILURES
+  - CONNECTIONSESTABLISHED
+  - CONNECTIONSUCCESSES
+  - DzpxcSRh
   - MAXRTT
+  - TIMEMAX
   - aggs
   - alertmethod
   - alertpolicy
@@ -61,6 +68,7 @@ words:
   - dynatrace
   - endef
   - enduml
+  - examplegen
   - fatalf
   - gobin
   - gofile
@@ -72,6 +80,7 @@ words:
   - goreleaser
   - gosec
   - govulncheck
+  - group-Q72HorLyjjCc
   - groupmy
   - hrdu
   - httpurls
@@ -103,6 +112,7 @@ words:
   - opentsdb
   - opsgenie
   - pagerduty
+  - pathutils
   - plantuml
   - preconfigured
   - promql

internal/cmd/docgen/go_doc.go

@@ -15,7 +15,7 @@ import (
 
 	"golang.org/x/exp/maps"
 
-	"github.com/nobl9/nobl9-go/internal/testutils"
+	"github.com/nobl9/nobl9-go/internal/pathutils"
 )
 
 const moduleRootPath = "github.com/nobl9/nobl9-go"
@@ -32,7 +32,7 @@ func (t goTypeDoc) PkgPath() string {
 }
 
 func parseGoDocs() map[string]goTypeDoc {
-	root := testutils.FindModuleRoot()
+	root := pathutils.FindModuleRoot()
 	objectsDirectory := filepath.Join(root, "manifest")
 	directories, err := listDirectories(objectsDirectory)
 	if err != nil {

internal/cmd/docgen/object_doc.go

@@ -7,7 +7,7 @@ import (
 	"reflect"
 	"strings"
 
-	"github.com/nobl9/nobl9-go/internal/testutils"
+	"github.com/nobl9/nobl9-go/internal/pathutils"
 	"github.com/nobl9/nobl9-go/manifest"
 )
 
@@ -27,7 +27,7 @@ func generateObjectDocs(objectNames []string) []*ObjectDoc {
 		}
 	}
 
-	rootPath := testutils.FindModuleRoot()
+	rootPath := pathutils.FindModuleRoot()
 	// Generate object properties based on reflection.
 	for _, object := range objects {
 		mapper := newObjectMapper()

internal/cmd/examplegen/main.go

@@ -0,0 +1,153 @@
+package main
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+
+	"github.com/goccy/go-yaml"
+
+	v1alphaExamples "github.com/nobl9/nobl9-go/internal/manifest/v1alpha/examples"
+	"github.com/nobl9/nobl9-go/internal/pathutils"
+	"github.com/nobl9/nobl9-go/manifest"
+	"github.com/nobl9/nobl9-go/sdk"
+)
+
+type examplesGeneratorConfig struct {
+	Examples []v1alphaExamples.Example
+	Path     string
+	Comments yaml.CommentMap
+}
+
+const manifestPath = "manifest"
+
+func main() {
+	rootPath := pathutils.FindModuleRoot()
+	configs := getV1alphaExamplesConfigs()
+	for _, config := range configs {
+		examples := make([]any, 0, len(config.Examples))
+		for _, variant := range config.Examples {
+			examples = append(examples, variant.GetObject())
+		}
+		config.Path = filepath.Join(rootPath, config.Path)
+		var input any
+		if len(examples) == 1 {
+			input = examples[0]
+		} else {
+			input = examples
+		}
+		if err := writeExamples(input, config.Path, config.Comments); err != nil {
+			panic(err.Error())
+		}
+	}
+}
+
+func getV1alphaExamplesConfigs() []examplesGeneratorConfig {
+	basePath := filepath.Join(manifestPath, "v1alpha")
+	// Non-standard examples.
+	configs := []examplesGeneratorConfig{
+		{
+			Examples: v1alphaExamples.Labels(),
+			Path:     filepath.Join(basePath, "labels_examples.yaml"),
+		},
+		{
+			Examples: v1alphaExamples.MetadataAnnotations(),
+			Path:     filepath.Join(basePath, "metadata_annotations_examples.yaml"),
+		},
+	}
+	// Standard examples.
+	allExamples := [][]v1alphaExamples.Example{
+		v1alphaExamples.Project(),
+		v1alphaExamples.Service(),
+		v1alphaExamples.AlertMethod(),
+		v1alphaExamples.SLO(),
+		v1alphaExamples.Agent(),
+		v1alphaExamples.Direct(),
+		v1alphaExamples.AlertPolicy(),
+		v1alphaExamples.AlertSilence(),
+		v1alphaExamples.Annotation(),
+		v1alphaExamples.BudgetAdjustment(),
+		v1alphaExamples.DataExport(),
+		v1alphaExamples.RoleBinding(),
+	}
+	for _, examples := range allExamples {
+		object := examples[0].GetObject().(manifest.Object)
+		basePath := filepath.Join(
+			manifestPath,
+			object.GetVersion().VersionString(),
+			object.GetKind().ToLower(),
+		)
+		grouped := groupBy(examples, func(e v1alphaExamples.Example) string { return e.GetVariant() })
+		// If we don't have any variants, we can write all examples into examples.yaml file.
+		if len(grouped) == 1 {
+			configs = append(configs, examplesGeneratorConfig{
+				Examples: examples,
+				Path:     filepath.Join(basePath, "examples.yaml"),
+			})
+			continue
+		}
+		for variant, examples := range grouped {
+			config := examplesGeneratorConfig{
+				Examples: examples,
+				Path:     filepath.Join(basePath, "examples", strings.ReplaceAll(strings.ToLower(variant), " ", "-")+".yaml"),
+				Comments: make(yaml.CommentMap),
+			}
+			if len(examples) == 1 {
+				configs = append(configs, config)
+				continue
+			}
+			if examples[0].GetSubVariant() != "" {
+				sort.Slice(examples, func(i, j int) bool {
+					return examples[i].GetSubVariant() < examples[j].GetSubVariant()
+				})
+			}
+			for i, example := range examples {
+				comments := example.GetYAMLComments()
+				if len(comments) == 0 {
+					continue
+				}
+				for i := range comments {
+					comments[i] = " " + comments[i]
+				}
+				config.Comments[fmt.Sprintf("$[%d]", i)] = []*yaml.Comment{yaml.HeadComment(comments...)}
+			}
+			configs = append(configs, config)
+		}
+	}
+	return configs
+}
+
+func writeExamples(v any, path string, comments yaml.CommentMap) error {
+	if err := os.MkdirAll(filepath.Dir(path), 0o700); err != nil {
+		return err
+	}
+	// #nosec G304
+	file, err := os.Create(path)
+	if err != nil {
+		return err
+	}
+	defer func() { _ = file.Close() }()
+	if object, ok := v.(manifest.Object); ok {
+		return sdk.EncodeObject(object, file, manifest.ObjectFormatYAML)
+	}
+	opts := []yaml.EncodeOption{
+		yaml.Indent(2),
+		yaml.UseLiteralStyleIfMultiline(true),
+	}
+	if len(comments) > 0 {
+		opts = append(opts, yaml.WithComment(comments))
+	}
+	enc := yaml.NewEncoder(file, opts...)
+	return enc.Encode(v)
+}
+
+func groupBy[K comparable, V any](s []V, key func(V) K) map[K][]V {
+	m := make(map[K][]V)
+	for _, v := range s {
+		k := key(v)
+		m[k] = append(m[k], v)
+	}
+	return m
+}

internal/manifest/objects_test.go

@@ -8,7 +8,7 @@ import (
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 
-	"github.com/nobl9/nobl9-go/internal/testutils"
+	"github.com/nobl9/nobl9-go/internal/pathutils"
 	"github.com/nobl9/nobl9-go/manifest"
 	v1alphaParser "github.com/nobl9/nobl9-go/manifest/v1alpha/parser"
 	"github.com/nobl9/nobl9-go/sdk"
@@ -20,7 +20,7 @@ func TestMain(m *testing.M) {
 }
 
 func TestObjectExamples(t *testing.T) {
-	moduleRoot := testutils.FindModuleRoot()
+	moduleRoot := pathutils.FindModuleRoot()
 	objects, err := sdk.ReadObjects(context.Background(), filepath.Join(moduleRoot, "manifest/**/example*.yaml"))
 	require.NoError(t, err)
 	assert.Greater(t, len(objects), 0, "no object examples found")