Fix detecting @field annotations outside YAML nodes and support emptyobject type

Signed-off-by: Andrei Kvapil <kvapss@gmail.com>

Author: kvaps

internal/readme/readme.go

@@ -162,6 +162,43 @@ func parseMetadataComments(path string) (*Meta, error) {
 	// build param-name → type alias map
 	aliasMap := buildAliasMap(allParams)
 
+	seen := map[fieldKey]struct{}{}
+	addField := func(parent, name, typ, desc string) {
+		if parent == "" || name == "" {
+			return
+		}
+		if real, ok := aliasMap[parent]; ok {
+			parent = real
+		}
+		k := fieldKey{parent: parent, name: name}
+		if _, dup := seen[k]; dup {
+			return
+		}
+		typeFields[parent] = append(typeFields[parent], FieldMeta{
+			ParentTypeName: parent,
+			Name:           name,
+			Type:           typ,
+			Description:    desc,
+		})
+		seen[k] = struct{}{}
+	}
+
+	// collect from raw lines
+	for _, line := range lines {
+		if m := fieldRe.FindStringSubmatch(strings.TrimSpace(line)); m != nil {
+			qual := m[1]
+			typ := m[2]
+			desc := m[3]
+
+			rootType, field := qual, ""
+			if strings.Contains(qual, ".") {
+				parts := strings.SplitN(qual, ".", 2)
+				rootType, field = parts[0], parts[1]
+			}
+			addField(rootType, field, typ, desc)
+		}
+	}
+
 	// ───────────── second pass: traverse YAML & @field ─────────────
 	var walk func(node *yaml.Node, path []string)
 	walk = func(node *yaml.Node, path []string) {
@@ -406,9 +443,22 @@ func normalizeType(t string) string {
 		t = t[:idx]
 	}
 
-	// if underlying base is primitive, preserve it verbatim
+	// normalize emptyobject for display
+	if t == aliasEmptyObject {
+		return "object"
+	}
+	if t == "*"+aliasEmptyObject {
+		return "*object"
+	}
+
+	// if underlying base is primitive, preserve it verbatim (after emptyobject normalization above)
 	base := deriveTypeName(t)
 	if isPrimitive(base) {
+		// show emptyobject as object in composite forms too
+		if base == aliasEmptyObject {
+			// handle map/array already below; for bare it's handled above
+			return strings.ReplaceAll(t, aliasEmptyObject, "object")
+		}
 		return t
 	}
 
@@ -418,11 +468,19 @@ func normalizeType(t string) string {
 		if !isPrimitive(base) {
 			return "[]object"
 		}
+		// []emptyobject -> []object
+		if base == aliasEmptyObject {
+			return "[]object"
+		}
 		return "[]" + base
 	}
 
 	// Handle map types
 	if strings.HasPrefix(t, "map[") {
+		// map[string]emptyobject -> map[string]object
+		if deriveTypeName(t) == aliasEmptyObject {
+			return "map[string]object"
+		}
 		return "map[string]object"
 	}
 
@@ -431,13 +489,13 @@ func normalizeType(t string) string {
 		if !isPrimitive(base) && !strings.HasPrefix(base, "[]") && !strings.HasPrefix(base, "map[") {
 			return "*object"
 		}
+		// *emptyobject already handled above
 		return t
 	}
 
 	if !isPrimitive(t) && !strings.HasPrefix(t, "[]") && !strings.HasPrefix(t, "map[") {
 		return "object"
 	}
-
 	return t
 }
 
@@ -485,6 +543,11 @@ func valueString(raw interface{}, exists bool, t string) string {
 	}
 }
 
+type fieldKey struct {
+	parent string
+	name   string
+}
+
 func isPrimitive(t string) bool {
 	base := strings.TrimPrefix(t, "*")
 	if isStringFormat(base) {
@@ -493,7 +556,7 @@ func isPrimitive(t string) bool {
 	switch base {
 	case "string", "bool", "int", "int32", "int64",
 		"float32", "float64",
-		aliasQuantity, aliasDuration, aliasTime, aliasObject:
+		aliasQuantity, aliasDuration, aliasTime, aliasObject, aliasEmptyObject:
 		return true
 	default:
 		return false

internal/readme/readme_test.go

@@ -582,3 +582,52 @@ config:
 
 	require.NoError(t, validateValues(params, typeFields, vals))
 }
+
+func TestSourceUploadSchemaFromTopBlock(t *testing.T) {
+	yamlContent := `
+## @section Common parameters
+## @param source {source} The source image location used to create a disk
+## @field source.image {*uploadImage} Use image by name
+## @field uploadImage.name {string} Name of the image to use
+## @field source.upload {*emptyobject} Upload local image
+## @field source.http {*uploadHTTP} Download image from an HTTP source
+## @field uploadHTTP.url {string} URL to download the image
+
+source: {}
+
+## @param optical {bool} Defines if disk should be considered optical
+optical: false
+
+## @param storage {quantity} The size of the disk allocated for the virtual machine
+## @param storageClass {string} StorageClass used to store the data
+storage: 5Gi
+storageClass: replicated
+`
+	path := writeTempFile(t, yamlContent)
+	defer os.Remove(path)
+
+	vals, err := createValuesObject(path)
+	require.NoError(t, err)
+
+	meta, err := parseMetadataComments(path)
+	require.NoError(t, err)
+
+	var params []ParamMeta
+	for _, s := range meta.Sections {
+		params = append(params, s.Parameters...)
+	}
+
+	// validate should pass: 'source' type schema is known
+	require.NoError(t, validateValues(params, typeFields, vals))
+
+	// rendered table should show object for emptyobject and nested fields
+	table := renderTableFromValues(t, yamlContent)
+	require.Contains(t, table, "`source`")
+	require.Contains(t, table, "`{}`")
+	require.Contains(t, table, "`source.image`")
+	require.Contains(t, table, "`source.upload`") // emptyobject displayed as object
+	require.Contains(t, table, "`source.http`")
+	// normalizeType for emptyobject
+	require.NotContains(t, table, "`emptyobject`")
+	require.Contains(t, table, "`object`")
+}