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
@@ -91,6 +100,7 @@ words:
   - mockgen
   - mprofile
   - msgf
+  - mstats
   - msteams
   - ningxia
   - nobl
@@ -103,6 +113,7 @@ words:
   - opentsdb
   - opsgenie
   - pagerduty
+  - pathutils
   - plantuml
   - preconfigured
   - promql

go.mod

@@ -6,8 +6,9 @@ require (
 	github.com/BurntSushi/toml v1.4.0
 	github.com/MicahParks/jwkset v0.5.18
 	github.com/MicahParks/keyfunc/v3 v3.3.3
-	github.com/aws/aws-sdk-go v1.54.15
+	github.com/aws/aws-sdk-go v1.54.17
 	github.com/bmatcuk/doublestar/v4 v4.6.1
+	github.com/goccy/go-yaml v1.11.3
 	github.com/golang-jwt/jwt/v5 v5.2.1
 	github.com/hashicorp/go-retryablehttp v0.7.7
 	github.com/nobl9/go-yaml v1.0.1

go.sum

@@ -4,8 +4,8 @@ github.com/MicahParks/jwkset v0.5.18 h1:WLdyMngF7rCrnstQxA7mpRoxeaWqGzPM/0z40PJU
 github.com/MicahParks/jwkset v0.5.18/go.mod h1:q8ptTGn/Z9c4MwbcfeCDssADeVQb3Pk7PnVxrvi+2QY=
 github.com/MicahParks/keyfunc/v3 v3.3.3 h1:c6j9oSu1YUo0k//KwF1miIQlEMtqNlj7XBFLB8jtEmY=
 github.com/MicahParks/keyfunc/v3 v3.3.3/go.mod h1:f/UMyXdKfkZzmBeBFUeYk+zu066J1Fcl48f7Wnl5Z48=
-github.com/aws/aws-sdk-go v1.54.15 h1:ErgCEVbzuSfuZl9nR+g8FFnzjgeJ/AqAGOEWn6tgAHo=
-github.com/aws/aws-sdk-go v1.54.15/go.mod h1:eRwEWoyTWFMVYVQzKMNHWP5/RV4xIUGMQfXQHfHkpNU=
+github.com/aws/aws-sdk-go v1.54.17 h1:ZV/qwcCIhMHgsJ6iXXPVYI0s1MdLT+5LW28ClzCUPeI=
+github.com/aws/aws-sdk-go v1.54.17/go.mod h1:eRwEWoyTWFMVYVQzKMNHWP5/RV4xIUGMQfXQHfHkpNU=
 github.com/bmatcuk/doublestar/v4 v4.6.1 h1:FH9SifrbvJhnlQpztAx++wlkk70QBf0iBWDwNy7PA4I=
 github.com/bmatcuk/doublestar/v4 v4.6.1/go.mod h1:xBQ8jztBU6kakFMg+8WGxn0c6z1fTSPVIjEY1Wr7jzc=
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
@@ -19,6 +19,8 @@ github.com/go-playground/universal-translator v0.17.0 h1:icxd5fm+REJzpZx7ZfpaD87
 github.com/go-playground/universal-translator v0.17.0/go.mod h1:UkSxE5sNxxRwHyU+Scu5vgOQjsIJAF8j9muTVoKLVtA=
 github.com/go-playground/validator/v10 v10.4.1 h1:pH2c5ADXtd66mxoE0Zm9SUhxE20r7aM3F26W0hOn+GE=
 github.com/go-playground/validator/v10 v10.4.1/go.mod h1:nlOn6nFhuKACm19sB/8EGNn9GlaMV7XkbRSipzJ0Ii4=
+github.com/goccy/go-yaml v1.11.3 h1:B3W9IdWbvrUu2OYQGwvU1nZtvMQJPBKgBUuweJjLj6I=
+github.com/goccy/go-yaml v1.11.3/go.mod h1:wKnAMd44+9JAAnGQpWVEgBzGt3YuTaQ4uXoHvE4m7WU=
 github.com/golang-jwt/jwt/v5 v5.2.1 h1:OuVbFODueb089Lh128TAcimifWaLhJwVflnrgM17wHk=
 github.com/golang-jwt/jwt/v5 v5.2.1/go.mod h1:pqrtFR0X4osieyHYxtmOUWsAWrfe1Q5UVIyoH402zdk=
 github.com/google/go-cmp v0.6.0 h1:ofyhxvXcZhMsU5ulbFiLKl/XBFqE1GSq7atu8tAmTRI=

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,152 @@
+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() })
+		for variant, examples := range grouped {
+			var path string
+			if len(grouped) == 1 {
+				// If we don't have any variants, we can write all examples into examples.yaml file.
+				path = filepath.Join(basePath, "examples.yaml")
+			} else {
+				path = filepath.Join(basePath, "examples", strings.ReplaceAll(strings.ToLower(variant), " ", "-")+".yaml")
+			}
+			config := examplesGeneratorConfig{
+				Examples: examples,
+				Path:     path,
+				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")