Implement enum + documentation

# Conflicts:
#	docs/static/schema.json

docs/static/schema.json

@@ -632,33 +632,47 @@
           "struct-literal": {
             "title": "Match struct literal expressions",
             "markdownDescription": "The `struct-literal` join point matches struct literal expressions that create an instance of the named struct. In case of `match` being equal to `value-only` or `any`, the matched node will be of type `CompositeLit`, and in case of being `pointer-only`, it will be of type `UnaryExpr` (the node itself will be available in the `{{ .X }}` field). If `field` is specified, it only matches the value explicitly associated to the named field.\n\nWhen using `match: any`, the struct literal may have its address immediately taken (`&SomeType{/*...*/}`), and associated advice must be carefully designed to avoid breaking this (for example, wrapping it in an immediately-invoked function expression makes it impossible to take the value's address without first assigning it to a variable).",
-            "type": "object",
-            "required": ["type"],
-            "properties": {
-              "type": {
-                "description": "The fully qualified type name of the struct to match.",
-                "$ref": "#/$defs/go/qualified-identifier"
-              },
-              "field": {
-                "description": "Only match struct literal expressions that include the specified field name.",
-                "$ref": "#/$defs/go/identifier"
+            "oneOf": [
+              {
+                "type": "object",
+                "required": ["type", "field"],
+                "properties": {
+                  "type": {
+                    "description": "The fully qualified type name of the struct to match.",
+                    "$ref": "#/$defs/go/qualified-identifier"
+                  },
+                  "field": {
+                    "description": "Only match struct literal expressions that include the specified field name.",
+                    "$ref": "#/$defs/go/identifier"
+                  }
+                },
+                "additionalProperties": false
               },
-              "match": {
-                "description": "The struct literal expression style to match (value-only, pointer-only or any)",
-                "type": "string",
-                "enum": ["value-only", "pointer-only", "any"],
-                "default": "any"
+              {
+                "type": "object",
+                "required": ["type"],
+                "properties": {
+                  "type": {
+                    "description": "The fully qualified type name of the struct to match.",
+                    "$ref": "#/$defs/go/qualified-identifier"
+                  },
+                  "match": {
+                    "description": "The struct literal expression style to match (value-only, pointer-only or any)",
+                    "type": "string",
+                    "enum": ["value-only", "pointer-only", "any"],
+                    "default": "any"
+                  }
+                },
+                "additionalProperties": false
               }
-            },
-            "additionalProperties": false
+            ]
           }
         },
         "examples": [
           {
             "struct-literal": {
               "type": "net/http.Server",
-              "field": "Handler",
-              "match": "any"
+              "field": "Handler"
             }
           },
           {

internal/injector/aspect/join/struct.go

@@ -60,16 +60,41 @@ func (s *structDefinition) RenderHTML() string {
 	return fmt.Sprintf(`<div class="flex join-point struct-definition"><span class="type">Definition of</span>%s</div>`, s.typeName.RenderHTML())
 }
 
-type structLiteral struct {
-	typeName TypeName
-	field    string
-	match    string
-}
+type (
+	StructLiteralMatch int
+	structLiteral      struct {
+		typeName TypeName
+		field    string
+		match    StructLiteralMatch
+	}
+)
 
-func StructLiteral(typeName TypeName, field string, match string) *structLiteral {
+const (
+	// StructLiteralMatchAny matches struct literals regardless of whether they are pointer or value.
+	// [StructLiteral] join points specified with this match type may match [*dst.CompositeLit] or
+	// [*dst.UnaryExpr] nodes.
+	StructLiteralMatchAny StructLiteralMatch = iota
+	// StructLiteralMatchValueOnly matches struct literals that are not pointers. [StructLiteral] join
+	// points specified with this match type only ever match [*dst.CompositeLit] nodes.
+	StructLiteralMatchValueOnly
+	// StructLiteralMatchPointerOnly matches struct literals that are pointers. [StructLiteral] join
+	// points specified with this match type only ever match [*dst.UnaryExpr] nodes.
+	StructLiteralMatchPointerOnly
+)
+
+// StructLiteralField matches a specific field in struct literals of the designated type.
+func StructLiteralField(typeName TypeName, field string) *structLiteral {
 	return &structLiteral{
 		typeName: typeName,
 		field:    field,
+	}
+}
+
+// StructLiteral matches struct literal expressions of the designated type, filtered by the
+// specified match type.
+func StructLiteral(typeName TypeName, match StructLiteralMatch) *structLiteral {
+	return &structLiteral{
+		typeName: typeName,
 		match:    match,
 	}
 }
@@ -84,15 +109,15 @@ func (s *structLiteral) ImpliesImported() []string {
 func (s *structLiteral) Matches(ctx context.AspectContext) bool {
 	if s.field == "" {
 		switch s.match {
-		case "pointer-only":
+		case StructLiteralMatchPointerOnly:
 			// match only if the current node is equal to & and the underlying node matches
 			// the struct literal we are looking for
 			if expr, ok := ctx.Node().(*dst.UnaryExpr); ok && expr.Op == token.AND {
 				return s.matchesLiteral(expr.X)
 			}
 			return false
 
-		case "value-only":
+		case StructLiteralMatchValueOnly:
 			// do not match if the parent is equal to &
 			if parent := ctx.Parent(); parent != nil {
 				if expr, ok := parent.Node().(*dst.UnaryExpr); ok && expr.Op == token.AND {
@@ -132,7 +157,10 @@ func (s *structLiteral) matchesLiteral(node dst.Node) bool {
 }
 
 func (s *structLiteral) AsCode() jen.Code {
-	return jen.Qual(pkgPath, "StructLiteral").Call(s.typeName.AsCode(), jen.Lit(s.field), jen.Lit(s.match))
+	if s.field != "" {
+		return jen.Qual(pkgPath, "StructLiteralField").Call(s.typeName.AsCode(), jen.Lit(s.field))
+	}
+	return jen.Qual(pkgPath, "StructLiteral").Call(s.typeName.AsCode(), s.match.asCode())
 }
 
 func (s *structLiteral) RenderHTML() string {
@@ -152,6 +180,19 @@ func (s *structLiteral) RenderHTML() string {
 		buf.WriteString("\n      </code>\n")
 		buf.WriteString("    </li>\n")
 		buf.WriteString("  </ul>\n")
+	} else if s.match != StructLiteralMatchAny {
+		buf.WriteString("  <ul>\n")
+		buf.WriteString("    <li class=\"flex\">\n")
+		buf.WriteString("      <span class=\"type\">Only as</span>\n")
+		buf.WriteString("      <code>\n")
+		if s.match == StructLiteralMatchValueOnly {
+			buf.WriteString("value\n")
+		} else {
+			buf.WriteString("pointer\n")
+		}
+		buf.WriteString("      </code>\n")
+		buf.WriteString("    </li>\n")
+		buf.WriteString("  </ul>\n")
 	}
 	buf.WriteString("</div>\n")
 
@@ -179,7 +220,7 @@ func init() {
 		var spec struct {
 			Type  string
 			Field string
-			Match string
+			Match StructLiteralMatch
 		}
 		if err := node.Decode(&spec); err != nil {
 			return nil, err
@@ -189,9 +230,64 @@ func init() {
 		if err != nil {
 			return nil, err
 		}
-		if spec.Match == "" {
-			spec.Match = "any"
+
+		if spec.Field != "" {
+			if spec.Match != StructLiteralMatchAny {
+				return nil, fmt.Errorf("struct-literal.field is not allowed with struct-literal.match: %s", spec.Match)
+			}
+			return StructLiteralField(tn, spec.Field), nil
 		}
-		return StructLiteral(tn, spec.Field, spec.Match), nil
+
+		return StructLiteral(tn, spec.Match), nil
+	}
+}
+
+var _ yaml.Unmarshaler = (*StructLiteralMatch)(nil)
+
+func (s *StructLiteralMatch) UnmarshalYAML(node *yaml.Node) error {
+	var name string
+	if err := node.Decode(&name); err != nil {
+		return err
+	}
+
+	switch name {
+	case "any":
+		*s = StructLiteralMatchAny
+	case "value-only":
+		*s = StructLiteralMatchValueOnly
+	case "pointer-only":
+		*s = StructLiteralMatchPointerOnly
+	default:
+		return fmt.Errorf("invalid struct-literal.match value: %q", name)
+	}
+
+	return nil
+}
+
+func (s StructLiteralMatch) String() string {
+	switch s {
+	case StructLiteralMatchAny:
+		return "any"
+	case StructLiteralMatchValueOnly:
+		return "value-only"
+	case StructLiteralMatchPointerOnly:
+		return "pointer-only"
+	default:
+		panic(fmt.Errorf("invalid StructLiteralMatch(%d)", int(s)))
+	}
+}
+
+func (s StructLiteralMatch) asCode() jen.Code {
+	var constName string
+	switch s {
+	case StructLiteralMatchAny:
+		constName = "StructLiteralMatchAny"
+	case StructLiteralMatchValueOnly:
+		constName = "StructLiteralMatchValueOnly"
+	case StructLiteralMatchPointerOnly:
+		constName = "StructLiteralMatchPointerOnly"
+	default:
+		panic(fmt.Errorf("invalid StructLiteralMatch(%d)", int(s)))
 	}
+	return jen.Qual(pkgPath, constName)
 }

internal/injector/builtin/generator/schema.go

@@ -124,9 +124,9 @@ func documentSchemaInstance(schema *jsonschema.Schema, path string) error {
 	if len(schema.Examples) > 0 {
 		fmt.Fprintln(file, "## Examples")
 		fmt.Fprintln(file)
-		for _, ex := range schema.Examples {
+		for idx, ex := range schema.Examples {
 			if err := schema.Validate(ex); err != nil {
-				return fmt.Errorf("invalid example: %w", err)
+				return fmt.Errorf("invalid example (index %d): %w", idx, err)
 			}
 
 			yml, err := yaml.Marshal(ex)