Use path-prefixed field tags to configure complex fields

[vearutop]

This PR takes a different approach to #124 to have a coherent solution.

	type My struct {
		List1 []string       `json:"l1" items.title:"List 1" items.enum:"abc,def"`
		Map1  map[string]int `json:"m1" additionalProperties.title:"Map 1" additionalProperties.enum:"1,2,3"`
	}

[github-actions]

Lines Of Code

Language	Files	Lines	Code	Comments	Blanks	Complexity	Bytes
Go	7	2459 (+71)	1685 (+58)	274 (-1)	500 (+14)	654 (+26)	59.4K (+1.8K)
Go (gen)	1	973	699	100	174	112	23.4K (-3B)
Go (gen) (test)	1	107	84	1	22	0	41.2K (+16B)
Go (test)	13	4234 (+43)	3153 (+39)	311	770 (+4)	51	107.5K (+1.3K)
Markdown	4	332 (+11)	266 (+9)	0	66 (+2)	0	14.8K (+485B)
YAML	6	445 (-4)	371 (-4)	35	39	0	14.5K (-80B)

[github-actions]

Go API Changes

# summary
Inferred base version: v0.3.76
Suggested version: v0.4.0

[github-actions]

Unit Test Coverage

total: (statements) 79.8%
changed lines: (statements) 87.1%, coverage is less than 90.0%, consider testing the changes more thoroughly

Coverage of changed lines

File	Function	Coverage
Total		87.1%
reflect.go		87.1%
reflect.go:129	checkSchemaSetup	100.0%
reflect.go:1057	walkProperties	100.0%
reflect.go:1418	reflectEnum	100.0%
reflect.go:1440	loadFromField	100.0%
reflect.go:831	kindSwitch	90.5%
reflect.go:1467	inferType	52.1%

Coverage diff with base branch

File	Function	Base Coverage	Current Coverage
Total		79.9%	79.8% (-0.1%)
reflect.go	inferType	no function	60.0%
reflect.go	kindSwitch	88.5%	88.6% (+0.1%)
reflect.go	walkProperties	84.5%	85.2% (+0.7%)

[github-actions]

Benchmark Result

Benchmark diff with base branch

name                        old time/op    new time/op    delta
Schema_UnmarshalJSON_raw-4    59.5µs ± 5%    58.3µs ± 0%   ~     (p=0.151 n=5+5)
Schema_UnmarshalJSON-4         462µs ± 0%     465µs ± 1%   ~     (p=0.151 n=5+5)
Schema_MarshalJSON_raw-4      39.0µs ± 2%    39.2µs ± 1%   ~     (p=0.151 n=5+5)
Schema_MarshalJSON-4           186µs ± 1%     188µs ± 1%   ~     (p=0.222 n=5+5)

name                        old alloc/op   new alloc/op   delta
Schema_UnmarshalJSON_raw-4    31.3kB ± 0%    31.3kB ± 0%   ~     (all equal)
Schema_UnmarshalJSON-4         180kB ± 0%     180kB ± 0%   ~     (all equal)
Schema_MarshalJSON_raw-4      14.6kB ± 0%    14.6kB ± 0%   ~     (p=0.333 n=5+4)
Schema_MarshalJSON-4          53.9kB ± 0%    53.9kB ± 0%   ~     (p=0.286 n=5+5)

name                        old allocs/op  new allocs/op  delta
Schema_UnmarshalJSON_raw-4       460 ± 0%       460 ± 0%   ~     (all equal)
Schema_UnmarshalJSON-4         1.85k ± 0%     1.85k ± 0%   ~     (all equal)
Schema_MarshalJSON_raw-4         370 ± 0%       370 ± 0%   ~     (all equal)
Schema_MarshalJSON-4             468 ± 0%       468 ± 0%   ~     (all equal)

Benchmark result

name                        time/op
Schema_UnmarshalJSON_raw-4  58.3µs ± 0%
Schema_UnmarshalJSON-4       465µs ± 1%
Schema_MarshalJSON_raw-4    39.2µs ± 1%
Schema_MarshalJSON-4         188µs ± 1%

name                        alloc/op
Schema_UnmarshalJSON_raw-4  31.3kB ± 0%
Schema_UnmarshalJSON-4       180kB ± 0%
Schema_MarshalJSON_raw-4    14.6kB ± 0%
Schema_MarshalJSON-4        53.9kB ± 0%

name                        allocs/op
Schema_UnmarshalJSON_raw-4     460 ± 0%
Schema_UnmarshalJSON-4       1.85k ± 0%
Schema_MarshalJSON_raw-4       370 ± 0%
Schema_MarshalJSON-4           468 ± 0%

[llamapreview]

Auto Pull Request Review from LlamaPReview

1. Overview

1.1 Core Changes

• Primary purpose and scope: Enable path-prefixed field tags for configuring complex nested structures in JSON Schema generation
• Key components modified: Reflect context handling, enum parsing, array/map reflection logic
• Cross-component impacts: Schema generation, tag processing, validation rules
• Business value alignment: Enhances API contract precision and validation capabilities

1.2 Technical Architecture

• System design modifications: Added hierarchical tag prefix tracking in reflection context
• Component interaction changes: Modified schema population flow for nested structures
• Integration points impact: Affects all schema generation using struct tags
• Dependency changes: Updated swaggest/refl to v1.4.0

2. Critical Findings

2.1 Must Fix (P0🔴)

No critical blocking issues found

2.2 Should Fix (P1🟡)

Issue: Silent enum value parsing failures

• Analysis Confidence: High
• Impact: Invalid enum values in tags may produce incorrect schemas
• Suggested Solution: Add error handling with explicit validation

Issue: Fragile type detection via string prefix matching

• Analysis Confidence: Medium
• Impact: Potential incorrect type handling for custom aliases
• Suggested Solution: Use direct reflect.Kind comparisons

2.3 Consider (P2🟢)

Area: Concurrency safety in reflection context

• Analysis Confidence: Medium
• Improvement Opportunity: Prevent race conditions in concurrent usage

Area: Documentation expansion

• Analysis Confidence: High
• Improvement Opportunity: Clarify multi-level nesting and type expectations

2.4 Summary of Action Items

1. Address enum parsing error handling (P1 - immediate)
2. Improve type detection robustness (P1 - 1-2 days)
3. Add nesting depth validation (P2 - follow-up)

3. Technical Analysis

3.1 Code Logic Analysis

📁 reflect.go - array handling

• Submitted PR Code:

    prevTagPrefix := rc.parentTagPrefix
    defer func() { rc.parentTagPrefix = prevTagPrefix }()
    rc.parentTagPrefix += "items."

• Analysis:
  • Manages nested context effectively through defer cleanup
  • Potential memory growth in deep recursion scenarios
  • Missing depth validation could lead to stack overflow
• LlamaPReview Suggested Improvements:

    const maxPrefixDepth = 20
    if strings.Count(rc.parentTagPrefix, ".") > maxPrefixDepth {
        return errors.New("max nesting depth exceeded")
    }

• Improvement rationale:
  • Prevents memory exhaustion in pathological cases
  • Adds safety boundary for complex schemas

📁 reflect.go - enum type detection

• Submitted PR Code:

    switch {
    case strings.HasPrefix(fv.Kind().String(), "int"):
        // Parse as integer

• Analysis:
  • Fragile string matching for type detection
  • Fails with custom type aliases (e.g., type MyInt int)
  • Potential incorrect parsing of unsigned types
• LlamaPReview Suggested Improvements:

    switch fv.Kind() {
    case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64:
        // Integer handling
    case reflect.Uint, reflect.Uint8, ...:
        // Unsigned handling

• Improvement rationale:
  • Robust type handling for all numeric kinds
  • Supports custom type aliases through direct kind checks

4. Overall Evaluation

• Technical assessment: Well-structured implementation with careful nested context management
• Business impact: Significant improvement in schema customization capabilities
• Risk evaluation: Low risk for existing users, medium risk for new features without P1 fixes
• Notable positive aspects: Comprehensive test coverage, maintainable prefix tracking
• Implementation quality: Good overall with minor reliability improvements needed
• Final recommendation: Request Changes (Address P1 issues first)

---

💡 LlamaPReview Community
Have feedback on this AI Code review tool? Join our GitHub Discussions to share your thoughts and help shape the future of LlamaPReview.