typia 15.0.0 → 15.1.0

package/native/core/factories/internal/metadata/iterate_metadata_intersection.go

@@ -9,6 +9,18 @@ import (
   schemametadata "github.com/samchon/typia/packages/typia/native/core/schemas/metadata"
 )
 
+// Iterate_metadata_intersection resolves an intersection type.
+//
+// Plain object intersections are left to the object merge. Otherwise each member
+// is analyzed, type tag objects are separated, phantom brands and call-only arms
+// are dropped and exactly one base member must remain, which is analyzed again
+// with the tags attached. Anything else is reported as a nonsensible
+// intersection.
+//
+// @evidence contracts/common.md#principled-implementation A union-distribution reduction and a plain-object test come first, because an intersection of plain objects is merged by the object path. Otherwise every member is analyzed on the collection after taking a registry snapshot, with trial errors captured; type tag objects are separated, a call-signature-only arm is dropped when something else survives, phantom brands (optional or symbol-keyed members only) are dropped, and exactly one single-bucket base must remain, which is analyzed alone with the tags attached to its constants, atomics, templates, arrays, objects, natives, sets or maps; any other combination is an error. Restoring the snapshot rolls back registry maps, order lists, counters and caches; existing named definitions remain shared and are not a deep transaction.
+// @evidence contracts/common.md#clear-and-simple-design One long function that lists the decision steps in order and delegates classification to private helpers (brand and signature tests, never detection, literal disjointness, tag analysis, identity gates); the helpers are private because only this iterator and the explorer need them.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Each rejection reports the exact intersection, and the brand and signature rules are structural; the long inline comments record the cases that a simpler rule would break.
+// @evidence contracts/common.md#meaningful-documentation The doc states the order of steps, and the helpers carry comments with the reasons and issue references.
 func Iterate_metadata_intersection(props IMetadataIteratorProps) bool {
   if props.Intersected == true {
     return false
@@ -131,7 +143,7 @@ func Iterate_metadata_intersection(props IMetadataIteratorProps) bool {
   // removable" guard below exists to refuse an intersection of nothing but
   // brands, and an arm such as `Record<never, never>` is vacuously a phantom
   // brand, so counting signatures as removable would turn
-  // `call & Record<never, never>` — which the interface spelling accepts — into a
+  // `call & Record<never, never>` ??which the interface spelling accepts ??into a
   // rejection.
   if len(metadatas) > 1 {
     kept := make([]*schemametadata.MetadataSchema, 0, len(metadatas))
@@ -157,7 +169,7 @@ func Iterate_metadata_intersection(props IMetadataIteratorProps) bool {
       metadatas = kept
       indexes = keptIndexes
     } else if len(kept) == 0 {
-      // Every arm was signatures only — an overload set, a call-and-construct
+      // Every arm was signatures only ??an overload set, a call-and-construct
       // pair, or two constructors. That is a member-free callable, which is what
       // the interface spelling of the same type produces, so this iterator has
       // nothing to merge and hands the type back rather than refusing it.
@@ -187,9 +199,9 @@ func Iterate_metadata_intersection(props IMetadataIteratorProps) bool {
     }
   }
   // After phantom brands are dropped, exactly one single-bucket base member must
-  // survive (`string & Brand` → string). Two genuine non-object members
-  // (`string[] & number[]`, `A[] & [t…]`, `T1 & T2`, …) — or a multi-bucket
-  // survivor — is an intersection of constraint carriers, a misuse with no sound
+  // survive (`string & Brand` ??string). Two genuine non-object members
+  // (`string[] & number[]`, `A[] & [t??`, `T1 & T2`, ?? ??or a multi-bucket
+  // survivor ??is an intersection of constraint carriers, a misuse with no sound
   // merge, so it stays nonsensible. This subsumes the per-candidate-kind check
   // below, which therefore always collapses to a single candidate.
   if len(metadatas) != 1 || metadatas[0].Size() != 1 {
@@ -319,7 +331,7 @@ func Iterate_metadata_intersection(props IMetadataIteratorProps) bool {
   explore.Escaped = false
   // Re-explore the surviving base alone (`Intersected: true` short-circuits the
   // intersection handler at the top of this function). TypeScript flattens nested
-  // intersections — `(A & B) & C` is presented as a single `types: [A, B, C]` — so
+  // intersections ??`(A & B) & C` is presented as a single `types: [A, B, C]` ??so
   // `Types()[index]` is always an atomic member, never itself an intersection that
   // would re-enter and leave `props.Metadata` empty.
   Iterate_metadata(IMetadataIteratorProps{
@@ -347,7 +359,7 @@ func Iterate_metadata_intersection(props IMetadataIteratorProps) bool {
 //
 // `((v: number) => string) & { label: string }` and
 // `interface T { (v: number): string; label: string }` are the same type, and
-// only the first reaches this function — the second is one object carrying a
+// only the first reaches this function ??the second is one object carrying a
 // call signature. Without this the first was refused as a nonsensible
 // intersection while the second was accepted, so the answer depended on the
 // spelling (samchon/typia#2276).
@@ -373,16 +385,15 @@ func iterate_metadata_intersection_is_call_signature_only(m *schemametadata.Meta
 // The single-survivor guard lives in the caller: when EVERY member is a plain
 // object, the entry point routes to the object-merge path before this runs, so
 // a required-literal property of a genuine `A & B` object merge is never dropped
-// here — only brands intersected with a primitive/array/template/native are.
+// here ??only brands intersected with a primitive/array/template/native are.
 //
 // A member is removable when it is a single non-recursive object bucket whose
 // every property is phantom: optional, or symbol-keyed. Those two are the only
-// unambiguously phantom markers — an optional property need not be present, and
+// unambiguously phantom markers ??an optional property need not be present, and
 // a symbol-keyed property is never observable on a JSON value. Any required
 // string-keyed property (literal or not) might be real data, so it keeps the
 // intersection nonsensible rather than silently dropping a declared constraint.
 
-
 func iterate_metadata_intersection_is_removable_brand(m *schemametadata.MetadataSchema) bool {
   if m == nil || m.Size() != 1 || len(m.Objects) != 1 {
     return false
@@ -573,7 +584,7 @@ func iterate_metadata_intersection_is_removable_object_constraint(
     // A symbol-keyed member is never observable on a JSON value (the canonical
     // nominal brand), so it is phantom and removable. typia's own tag is handled
     // as a constraint, not stripped here; any required string-keyed property might
-    // be real data — both keep the object as a constraint, not a removable brand.
+    // be real data ??both keep the object as a constraint, not a removable brand.
     if iterate_metadata_intersection_is_symbol_name(symbol.Name) {
       continue
     }

package/native/core/factories/internal/metadata/iterate_metadata_intersection_brand_coverage_test.go

@@ -21,6 +21,11 @@ import (
 //  1. Drive the symbol-key predicate across every case.
 //  2. Drive the per-property phantom predicate (optional / symbol / required).
 //  3. Drive the removable-brand object predicate end to end.
+//
+// @evidence contracts/testing.md#behavioral-verification The phantom-brand predicates run on nil, symbol-keyed, optional, required literal and required non-literal properties and objects; each Fatal names the accepted or rejected shape.
+// @evidence contracts/testing.md#independent-expectations A marker is phantom only when every property is optional or symbol-keyed; shapes and verdicts are authored from that rule.
+// @evidence contracts/testing.md#distinguishing-cases Eighteen assertions give positives and one-axis negatives for key kind, requiredness and object shape.
+// @evidence contracts/testing.md#execution-ownership The typia_native_internal Go command (go -C packages/typia/test test -tags typia_native_internal ../native/...) runs this same-package Test function in process. The tagged test calls pure predicates on constructed metadata with no program load or process.
 func TestIterateMetadataIntersectionBrandCoverage(t *testing.T) {
   atomic := func(typ string) *schemametadata.MetadataSchema {
     m := schemametadata.MetadataSchema_initialize()

package/native/core/factories/internal/metadata/iterate_metadata_intersection_coverage_test.go

@@ -4,9 +4,9 @@
 package metadata
 
 import (
-	"testing"
+  "testing"
 
-	schemametadata "github.com/samchon/typia/packages/typia/native/core/schemas/metadata"
+  schemametadata "github.com/samchon/typia/packages/typia/native/core/schemas/metadata"
 )
 
 // TestIterateMetadataIntersectionCoverage exercises intersection tag helpers.
@@ -20,87 +20,92 @@ import (
 // 2. Reject nil, empty, required, and incomplete tag object shapes.
 // 3. Verify analyzer dispatch with and without a registered tag analyzer.
 // 4. Restore the package analyzer after the scenario.
+//
+// @evidence contracts/testing.md#behavioral-verification The typia.tag shape predicates run on a complete tag object, nil, empty, required and incomplete shapes, and the analyzer hook runs with nil.
+// @evidence contracts/testing.md#independent-expectations The exact wrapper and nested tag structure is the authored specification of an acceptable tag object.
+// @evidence contracts/testing.md#distinguishing-cases One accepted shape and four rejected shapes; the analyzer-props checks are presence checks.
+// @evidence contracts/testing.md#execution-ownership The typia_native_internal Go command (go -C packages/typia/test test -tags typia_native_internal ../native/...) runs this same-package Test function in process. The tagged test calls pure predicates on constructed metadata with no program load or process.
 func TestIterateMetadataIntersectionCoverage(t *testing.T) {
-	literal := func(value string) *schemametadata.MetadataSchema {
-		meta := schemametadata.MetadataSchema_initialize()
-		meta.Constants = append(meta.Constants, schemametadata.MetadataConstant_create(schemametadata.MetadataConstant{
-			Type: "string",
-			Values: []*schemametadata.MetadataConstantValue{
-				schemametadata.MetadataConstantValue_create(schemametadata.MetadataConstantValue{Value: value}),
-			},
-		}))
-		return meta
-	}
-	tagObject := func(keys ...string) *schemametadata.MetadataObjectType {
-		properties := make([]*schemametadata.MetadataProperty, 0, len(keys))
-		for _, key := range keys {
-			properties = append(properties, schemametadata.MetadataProperty_create(schemametadata.MetadataProperty{
-				Key:   literal(key),
-				Value: literal(key + "-value"),
-			}))
-		}
-		return schemametadata.MetadataObjectType_create(schemametadata.MetadataObjectType{
-			Name:       "Tag",
-			Properties: properties,
-		})
-	}
-	wrapper := func(value *schemametadata.MetadataSchema) *schemametadata.MetadataObjectType {
-		return schemametadata.MetadataObjectType_create(schemametadata.MetadataObjectType{
-			Name: "Wrapper",
-			Properties: []*schemametadata.MetadataProperty{
-				schemametadata.MetadataProperty_create(schemametadata.MetadataProperty{
-					Key:   literal("typia.tag"),
-					Value: value,
-				}),
-			},
-		})
-	}
-	value := schemametadata.MetadataSchema_initialize()
-	value.Required = false
-	value.Objects = append(value.Objects, schemametadata.MetadataObject_create(schemametadata.MetadataObject{
-		Type: tagObject("target", "kind", "value"),
-	}))
-	if !iterate_metadata_intersection_is_type_tag(wrapper(value)) {
-		t.Fatal("complete typia tag object should be recognized")
-	}
-	if iterate_metadata_intersection_is_type_tag(nil) ||
-		iterate_metadata_intersection_is_type_tag(schemametadata.MetadataObjectType_create(schemametadata.MetadataObjectType{Name: "Empty"})) {
-		t.Fatal("nil and empty objects should not be recognized as type tags")
-	}
-	required := schemametadata.MetadataSchema_initialize()
-	required.Objects = append(required.Objects, schemametadata.MetadataObject_create(schemametadata.MetadataObject{
-		Type: tagObject("target", "kind", "value"),
-	}))
-	incomplete := schemametadata.MetadataSchema_initialize()
-	incomplete.Required = false
-	incomplete.Objects = append(incomplete.Objects, schemametadata.MetadataObject_create(schemametadata.MetadataObject{
-		Type: tagObject("target", "kind"),
-	}))
-	if iterate_metadata_intersection_is_type_tag(wrapper(required)) ||
-		iterate_metadata_intersection_is_type_tag(wrapper(incomplete)) {
-		t.Fatal("required or incomplete tag objects should be rejected")
-	}
+  literal := func(value string) *schemametadata.MetadataSchema {
+    meta := schemametadata.MetadataSchema_initialize()
+    meta.Constants = append(meta.Constants, schemametadata.MetadataConstant_create(schemametadata.MetadataConstant{
+      Type: "string",
+      Values: []*schemametadata.MetadataConstantValue{
+        schemametadata.MetadataConstantValue_create(schemametadata.MetadataConstantValue{Value: value}),
+      },
+    }))
+    return meta
+  }
+  tagObject := func(keys ...string) *schemametadata.MetadataObjectType {
+    properties := make([]*schemametadata.MetadataProperty, 0, len(keys))
+    for _, key := range keys {
+      properties = append(properties, schemametadata.MetadataProperty_create(schemametadata.MetadataProperty{
+        Key:   literal(key),
+        Value: literal(key + "-value"),
+      }))
+    }
+    return schemametadata.MetadataObjectType_create(schemametadata.MetadataObjectType{
+      Name:       "Tag",
+      Properties: properties,
+    })
+  }
+  wrapper := func(value *schemametadata.MetadataSchema) *schemametadata.MetadataObjectType {
+    return schemametadata.MetadataObjectType_create(schemametadata.MetadataObjectType{
+      Name: "Wrapper",
+      Properties: []*schemametadata.MetadataProperty{
+        schemametadata.MetadataProperty_create(schemametadata.MetadataProperty{
+          Key:   literal("typia.tag"),
+          Value: value,
+        }),
+      },
+    })
+  }
+  value := schemametadata.MetadataSchema_initialize()
+  value.Required = false
+  value.Objects = append(value.Objects, schemametadata.MetadataObject_create(schemametadata.MetadataObject{
+    Type: tagObject("target", "kind", "value"),
+  }))
+  if !iterate_metadata_intersection_is_type_tag(wrapper(value)) {
+    t.Fatal("complete typia tag object should be recognized")
+  }
+  if iterate_metadata_intersection_is_type_tag(nil) ||
+    iterate_metadata_intersection_is_type_tag(schemametadata.MetadataObjectType_create(schemametadata.MetadataObjectType{Name: "Empty"})) {
+    t.Fatal("nil and empty objects should not be recognized as type tags")
+  }
+  required := schemametadata.MetadataSchema_initialize()
+  required.Objects = append(required.Objects, schemametadata.MetadataObject_create(schemametadata.MetadataObject{
+    Type: tagObject("target", "kind", "value"),
+  }))
+  incomplete := schemametadata.MetadataSchema_initialize()
+  incomplete.Required = false
+  incomplete.Objects = append(incomplete.Objects, schemametadata.MetadataObject_create(schemametadata.MetadataObject{
+    Type: tagObject("target", "kind"),
+  }))
+  if iterate_metadata_intersection_is_type_tag(wrapper(required)) ||
+    iterate_metadata_intersection_is_type_tag(wrapper(incomplete)) {
+    t.Fatal("required or incomplete tag objects should be rejected")
+  }
 
-	previous := MetadataTypeTagAnalyzer
-	defer func() {
-		MetadataTypeTagAnalyzer = previous
-	}()
-	MetadataTypeTagAnalyzer = nil
-	if tags := iterate_metadata_intersection_analyze_type_tags(IMetadataIteratorProps{}, []*schemametadata.MetadataObjectType{tagObject("target", "kind", "value")}, map[string]string{"string": "string"}); len(tags) != 0 {
-		t.Fatalf("nil analyzer should return no tags: %+v", tags)
-	}
-	MetadataTypeTagAnalyzer = func(props struct {
-		Errors  *[]MetadataFactory_IError
-		Type    string
-		Objects []*schemametadata.MetadataObjectType
-		Explore MetadataFactory_IExplore
-	}) []schemametadata.IMetadataTypeTag {
-		if props.Type != "string" || len(props.Objects) != 1 {
-			t.Fatalf("unexpected analyzer props: %+v", props)
-		}
-		return []schemametadata.IMetadataTypeTag{{Name: "Format<uuid>"}}
-	}
-	if tags := iterate_metadata_intersection_analyze_type_tags(IMetadataIteratorProps{}, []*schemametadata.MetadataObjectType{tagObject("target", "kind", "value")}, map[string]string{"string": "string"}); len(tags) != 1 {
-		t.Fatalf("registered analyzer should return one tag: %+v", tags)
-	}
+  previous := MetadataTypeTagAnalyzer
+  defer func() {
+    MetadataTypeTagAnalyzer = previous
+  }()
+  MetadataTypeTagAnalyzer = nil
+  if tags := iterate_metadata_intersection_analyze_type_tags(IMetadataIteratorProps{}, []*schemametadata.MetadataObjectType{tagObject("target", "kind", "value")}, map[string]string{"string": "string"}); len(tags) != 0 {
+    t.Fatalf("nil analyzer should return no tags: %+v", tags)
+  }
+  MetadataTypeTagAnalyzer = func(props struct {
+    Errors  *[]MetadataFactory_IError
+    Type    string
+    Objects []*schemametadata.MetadataObjectType
+    Explore MetadataFactory_IExplore
+  }) []schemametadata.IMetadataTypeTag {
+    if props.Type != "string" || len(props.Objects) != 1 {
+      t.Fatalf("unexpected analyzer props: %+v", props)
+    }
+    return []schemametadata.IMetadataTypeTag{{Name: "Format<uuid>"}}
+  }
+  if tags := iterate_metadata_intersection_analyze_type_tags(IMetadataIteratorProps{}, []*schemametadata.MetadataObjectType{tagObject("target", "kind", "value")}, map[string]string{"string": "string"}); len(tags) != 1 {
+    t.Fatalf("registered analyzer should return one tag: %+v", tags)
+  }
 }

package/native/core/factories/internal/metadata/iterate_metadata_intersection_shareable_name_test.go

@@ -2,6 +2,10 @@ package metadata
 
 import "testing"
 
+// @evidence contracts/testing.md#behavioral-verification The shareable-name predicate is called on a named interface, anonymous object literals, an intersection rendering and a TypeLiteral name; each verdict is compared.
+// @evidence contracts/testing.md#independent-expectations Only named types can be shared across intersection members; the four names and verdicts are authored.
+// @evidence contracts/testing.md#distinguishing-cases One shareable name against three structural names.
+// @evidence contracts/testing.md#execution-ownership The canonical native Go command (pnpm test:go:native) runs this same-package Test function in process. It calls the private predicate directly in the same package with no program load or process.
 func TestIterateMetadataIntersectionShareableNameRejectsStructuralIntersections(t *testing.T) {
   cases := []struct {
     name      string

package/native/core/factories/internal/metadata/iterate_metadata_map.go

@@ -2,6 +2,13 @@ package metadata
 
 import schemametadata "github.com/samchon/typia/packages/typia/native/core/schemas/metadata"
 
+// Iterate_metadata_map records the runtime global `Map` type with its key and
+// value metadata. A same-named user declaration is not treated as a Map.
+//
+// @evidence contracts/common.md#principled-implementation Only a type whose symbol is the runtime global `Map` with two type arguments is a map, so a package or user declaration with the same name falls through to the object path; key and value are explored separately, and an existing map entry of the same display name is replaced.
+// @evidence contracts/common.md#clear-and-simple-design One function over the shared provenance test.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The identity check is the cited provenance gate and no name is trusted by itself.
+// @evidence contracts/common.md#meaningful-documentation The doc states the provenance rule.
 func Iterate_metadata_map(props IMetadataIteratorProps) bool {
   if props.Checker == nil || props.Type == nil {
     return false

package/native/core/factories/internal/metadata/iterate_metadata_native.go

@@ -7,6 +7,16 @@ import (
   schemametadata "github.com/samchon/typia/packages/typia/native/core/schemas/metadata"
 )
 
+// Iterate_metadata_native records a built-in class such as Date, a typed array,
+// Blob, File or WeakMap as a native entry.
+//
+// The type must resolve to the runtime-provided symbol of that name, so a package
+// or user declaration with the same name is analyzed structurally instead.
+//
+// @evidence contracts/common.md#principled-implementation The type's symbol-derived name is normalized for lookup and accepted only through the runtime-provenance identity gate, so a same-named user class remains structural. WeakMap and WeakSet use the same global provenance gate and retain only native identity, not their generic arguments; this iterator does not enforce generic arity.
+// @evidence contracts/common.md#clear-and-simple-design One function with the provenance gate in a helper and a static table of the supported natives.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Qualifier stripping only restores the lookup and the identity gate still decides, as the comment says.
+// @evidence contracts/common.md#meaningful-documentation The doc states the gate and the table.
 func Iterate_metadata_native(props IMetadataIteratorProps) bool {
   var symbol *nativeast.Symbol
   name := ""
@@ -41,7 +51,7 @@ func Iterate_metadata_native(props IMetadataIteratorProps) bool {
   for _, generic := range iterate_metadata_native_generics {
     if name == generic.Name || strings.HasPrefix(name, generic.Name+"<") {
       // Use the same runtime-provenance identity gate for WeakMap/WeakSet. The
-      // `+"<"` arity guard (#2181) and generic metadata remain unchanged.
+      // Generic arguments are erased from this native-identity representation.
       if !metadata_symbol_is_runtime_global_type(props.Checker, symbol, generic.Name) {
         return false
       }

package/native/core/factories/internal/metadata/iterate_metadata_object.go

@@ -5,6 +5,14 @@ import (
   schemametadata "github.com/samchon/typia/packages/typia/native/core/schemas/metadata"
 )
 
+// Iterate_metadata_object records an object type as an object entry. Unless
+// ensure is true, only object types, intersections and the `object` keyword are
+// accepted.
+//
+// @evidence contracts/common.md#principled-implementation Object types, intersections and the `object` keyword are objects, and the entry is emplaced once and recorded once per name in the schema; the optional ensure argument bypasses the type test for callers that already know the type is an object.
+// @evidence contracts/common.md#clear-and-simple-design One function over the emplace service with a variadic flag.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The variadic ensure is an explicit caller decision.
+// @evidence contracts/common.md#meaningful-documentation The doc states what is accepted.
 func Iterate_metadata_object(props IMetadataIteratorProps, ensure ...bool) bool {
   ensured := false
   if len(ensure) != 0 {

package/native/core/factories/internal/metadata/iterate_metadata_set.go

@@ -2,6 +2,13 @@ package metadata
 
 import schemametadata "github.com/samchon/typia/packages/typia/native/core/schemas/metadata"
 
+// Iterate_metadata_set records the runtime global `Set` type with its element
+// metadata. A same-named user declaration is not treated as a Set.
+//
+// @evidence contracts/common.md#principled-implementation Only a type whose symbol is the runtime global `Set` with one type argument is a set, with the same provenance gate as Map; the element is explored and an existing entry with the same element name is kept.
+// @evidence contracts/common.md#clear-and-simple-design One function over the shared provenance test.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The identity check is the cited gate.
+// @evidence contracts/common.md#meaningful-documentation The doc states the provenance rule.
 func Iterate_metadata_set(props IMetadataIteratorProps) bool {
   if props.Checker == nil || props.Type == nil {
     return false

package/native/core/factories/internal/metadata/iterate_metadata_sort.go

@@ -9,6 +9,17 @@ import (
   schemametadata "github.com/samchon/typia/packages/typia/native/core/schemas/metadata"
 )
 
+// Iterate_metadata_sort orders buckets reached from the root and the
+// collection's array, tuple and object-property schemas.
+//
+// Objects use equal key signatures, arrays and tuples use covering-first
+// comparisons, strings use lexical order and numbers use numeric order. Bigint
+// constants use their decimal text's lexical order. Booleans place false first.
+//
+// @evidence contracts/common.md#principled-implementation The visitor uses object key signatures, covering-first array/tuple comparisons, lexical string/bigint text and numeric number comparisons, plus false-first boolean ordering. It visits each directly traversed schema once and records multi-object union identities; named array/tuple/object contents are visited from collection roots. These comparisons do not define a total order over alternatives or promise narrower-first dispatch.
+// @evidence contracts/common.md#clear-and-simple-design One function with a recursive visitor, a coverage comparator for objects with a key cache, and a numeric conversion helper.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Object keys and schema coverage are structural heuristics, not fixture names or predicate evaluation. Constant ordering follows the represented primitive value/text; bigint text order is not a numeric magnitude guarantee.
+// @evidence contracts/common.md#meaningful-documentation The doc states what is ordered and the stable sort limit is explained here.
 func Iterate_metadata_sort(props struct {
   Collection *schemametadata.MetadataCollection
   Metadata   *schemametadata.MetadataSchema

package/native/core/factories/internal/metadata/iterate_metadata_template.go

@@ -5,6 +5,13 @@ import (
   schemametadata "github.com/samchon/typia/packages/typia/native/core/schemas/metadata"
 )
 
+// Iterate_metadata_template records a template literal type as a template whose
+// row alternates literal text and the metadata of the embedded types.
+//
+// @evidence contracts/common.md#principled-implementation A template literal type is a sequence of texts and type slots, so the row alternates a literal text schema, for each non-empty text, and the explored schema of the type in the slot after it.
+// @evidence contracts/common.md#clear-and-simple-design One function over the checker's template accessors.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The structure is the language's.
+// @evidence contracts/common.md#meaningful-documentation The doc states the row layout.
 func Iterate_metadata_template(props IMetadataIteratorProps) bool {
   if props.Type == nil || props.Type.Flags()&nativechecker.TypeFlagsTemplateLiteral == 0 {
     return false

package/native/core/factories/internal/metadata/iterate_metadata_tuple.go

@@ -5,6 +5,13 @@ import (
   schemametadata "github.com/samchon/typia/packages/typia/native/core/schemas/metadata"
 )
 
+// Iterate_metadata_tuple records a tuple type as a tuple entry, once per distinct
+// tuple type.
+//
+// @evidence contracts/common.md#principled-implementation A tuple type is emplaced once and recorded once per name in the schema, with its element analysis done by the emplace function.
+// @evidence contracts/common.md#clear-and-simple-design One function over the emplace service.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The iterator uses the checker's IsTupleType predicate before emplacement, not a textual type name.
+// @evidence contracts/common.md#meaningful-documentation The doc states the once-per-name rule.
 func Iterate_metadata_tuple(props IMetadataIteratorProps) bool {
   if props.Checker == nil || nativechecker.IsTupleType(props.Type) == false {
     return false

package/native/core/factories/internal/metadata/iterate_metadata_union.go

@@ -1,5 +1,15 @@
 package metadata
 
+// Iterate_metadata_union records every member of a union type into the same
+// schema.
+//
+// When all members of a non-empty union contribute nothing, the schema is marked
+// not required so that it describes `never`, except when the union carries null.
+//
+// @evidence contracts/common.md#principled-implementation Each member of a union is iterated into the same schema in the unioned and prunable states, so buckets accumulate; when every member of a non-empty union contributes nothing and the schema is neither any nor nullable, it is marked not required, which renders as `never`, because an empty schema would accept every value; a null member is excluded because the union would then still need to reject undefined.
+// @evidence contracts/common.md#clear-and-simple-design One function that loops over the members and applies one final rule.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The never rule is derived from the schema's own size and flags and the comment explains the case it fixes.
+// @evidence contracts/common.md#meaningful-documentation The doc states the accumulation and the never rule.
 func Iterate_metadata_union(props IMetadataIteratorProps) bool {
   if props.Type == nil || props.Type.IsUnion() == false {
     return false

package/native/core/factories/internal/metadata/js_doc_link_text_test.go

@@ -25,6 +25,11 @@ import (
 // inside a JSDoc tag.
 // 2. Reflect the property's description and tags through the metadata helpers.
 // 3. Assert the visible text and punctuation are preserved deterministically.
+//
+// @evidence contracts/testing.md#behavioral-verification JSDoc is parsed from source and the link renderer returns descriptions and tags with qualified targets, labels, call suffixes, URLs and tag comments; a nil link renders empty.
+// @evidence contracts/testing.md#independent-expectations Authored JSDoc text defines the visible output; expected strings are literals.
+// @evidence contracts/testing.md#distinguishing-cases Qualified and labeled links, URL links and tag comments are separate rows with a nil control.
+// @evidence contracts/testing.md#execution-ownership The typia_native_internal Go command (go -C packages/typia/test test -tags typia_native_internal ../native/...) runs this same-package Test function in process. The tagged test parses an in-memory source with the typescript-go parser and calls the renderer, with no filesystem fixture or process.
 func TestJsDocLinkText(t *testing.T) {
   file := nativeparser.ParseSourceFile(
     nativeast.SourceFileParseOptions{FileName: filepath.ToSlash(filepath.Join(t.TempDir(), "links.ts"))},

package/native/core/factories/internal/metadata/js_doc_parameter_name_reads_qualified_name_test.go

@@ -4,12 +4,12 @@
 package metadata
 
 import (
-	"path/filepath"
-	"testing"
+  "path/filepath"
+  "testing"
 
-	nativeast "github.com/microsoft/typescript-go/shim/ast"
-	nativecore "github.com/microsoft/typescript-go/shim/core"
-	nativeparser "github.com/microsoft/typescript-go/shim/parser"
+  nativeast "github.com/microsoft/typescript-go/shim/ast"
+  nativecore "github.com/microsoft/typescript-go/shim/core"
+  nativeparser "github.com/microsoft/typescript-go/shim/parser"
 )
 
 // TestJSDocParameterNameReadsQualifiedName verifies dotted JSDoc parameter names.
@@ -23,33 +23,38 @@ import (
 // 2. Walk the parsed JSDoc tags.
 // 3. Read each parameter name through the metadata helper.
 // 4. Assert the dotted name is returned without a panic.
+//
+// @evidence contracts/testing.md#behavioral-verification A dotted @param name in an interface member is parsed and the discovered parameter comment must include the qualified name without a panic.
+// @evidence contracts/testing.md#independent-expectations The source span of the authored comment is the expectation.
+// @evidence contracts/testing.md#distinguishing-cases One qualified name; simple names are exercised by other metadata tests.
+// @evidence contracts/testing.md#execution-ownership The typia_native_internal Go command (go -C packages/typia/test test -tags typia_native_internal ../native/...) runs this same-package Test function in process. The tagged test parses in-memory source with the typescript-go parser, with no filesystem fixture or process.
 func TestJSDocParameterNameReadsQualifiedName(t *testing.T) {
-	file := nativeparser.ParseSourceFile(
-		nativeast.SourceFileParseOptions{FileName: filepath.ToSlash(filepath.Join(t.TempDir(), "qualified.ts"))},
-		`interface Box {
+  file := nativeparser.ParseSourceFile(
+    nativeast.SourceFileParseOptions{FileName: filepath.ToSlash(filepath.Join(t.TempDir(), "qualified.ts"))},
+    `interface Box {
   /**
    * @param input.value nested value
    */
   field: string;
 }
 `,
-		nativecore.ScriptKindTS,
-	)
-	member := file.Statements.Nodes[0].AsInterfaceDeclaration().Members.Nodes[0]
+    nativecore.ScriptKindTS,
+  )
+  member := file.Statements.Nodes[0].AsInterfaceDeclaration().Members.Nodes[0]
 
-	found := false
-	for _, jsdoc := range member.JSDoc(nil) {
-		doc := jsdoc.AsJSDoc()
-		if doc == nil || doc.Tags == nil {
-			continue
-		}
-		for _, tag := range doc.Tags.Nodes {
-			if metadata_js_doc_parameter_name(tag) == "input.value" {
-				found = true
-			}
-		}
-	}
-	if found == false {
-		t.Fatal("qualified JSDoc parameter name was not discovered")
-	}
+  found := false
+  for _, jsdoc := range member.JSDoc(nil) {
+    doc := jsdoc.AsJSDoc()
+    if doc == nil || doc.Tags == nil {
+      continue
+    }
+    for _, tag := range doc.Tags.Nodes {
+      if metadata_js_doc_parameter_name(tag) == "input.value" {
+        found = true
+      }
+    }
+  }
+  if found == false {
+    t.Fatal("qualified JSDoc parameter name was not discovered")
+  }
 }