typia 15.0.1 → 15.1.0

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

@@ -4,13 +4,14 @@
 package metadata
 
 import (
-	"path/filepath"
-	"testing"
+  "path/filepath"
+  "reflect"
+  "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"
-	schemametadata "github.com/samchon/typia/packages/typia/native/core/schemas/metadata"
+  nativeast "github.com/microsoft/typescript-go/shim/ast"
+  nativecore "github.com/microsoft/typescript-go/shim/core"
+  nativeparser "github.com/microsoft/typescript-go/shim/parser"
+  schemametadata "github.com/samchon/typia/packages/typia/native/core/schemas/metadata"
 )
 
 // TestCommentTagsCoverage exercises metadata comment tag application.
@@ -24,112 +25,130 @@ import (
 // 3. Exercise analyzer error reporting and idempotent object tagging.
 // 4. Parse JSDoc AST nodes and cover type-expression/comment fallback helpers.
 // 5. Cover nil object and nil analyzer fallbacks.
+//
+// @evidence contracts/testing.md#behavioral-verification The comment-tag dispatcher calls a test analyzer on constructed property metadata. Exactly one callback, its property/location inputs, each exact test tag and one propagated error are asserted, and a repeated call must leave the callback count unchanged. Parsed JSDoc presence and nil-helper fallbacks are also checked; the real analyzer's parsing semantics are not exercised here.
+// @evidence contracts/testing.md#independent-expectations Authored callback inputs and marker tags establish the dispatch and once-only contract independently of the dispatcher. The test analyzer deliberately supplies tag/error outputs, so those outputs do not establish real comment-tag parsing; that belongs to factory tests.
+// @evidence contracts/testing.md#distinguishing-cases Every tag bucket, repeated application and parsing are exercised once; this test has few negatives.
+// @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 internal helpers with constructed metadata and an installed analyzer; it needs no program load or process.
 func TestCommentTagsCoverage(t *testing.T) {
-	oldAnalyzer := MetadataCommentTagAnalyzer
-	MetadataCommentTagAnalyzer = func(props struct {
-		Errors   *[]MetadataFactory_IError
-		Metadata *schemametadata.MetadataSchema
-		Tags     []schemametadata.IJsDocTagInfo
-		Explore  MetadataFactory_IExplore
-	}) {
-		if props.Metadata == nil {
-			return
-		}
-		tag := schemametadata.IMetadataTypeTag{Name: "testTag"}
-		for _, atomic := range props.Metadata.Atomics {
-			atomic.Tags = append(atomic.Tags, []schemametadata.IMetadataTypeTag{tag})
-		}
-		for _, array := range props.Metadata.Arrays {
-			array.Tags = append(array.Tags, []schemametadata.IMetadataTypeTag{tag})
-		}
-		if props.Errors != nil {
-			*props.Errors = append(*props.Errors, MetadataFactory_IError{
-				Name: "comment tag(s)",
-				Explore: MetadataFactory_IExplore{
-					Object:   props.Explore.Object,
-					Property: props.Explore.Property,
-				},
-				Messages: []string{"test analyzer error"},
-			})
-		}
-	}
-	defer func() {
-		MetadataCommentTagAnalyzer = oldAnalyzer
-	}()
-	value := schemametadata.MetadataSchema_initialize()
-	value.Atomics = append(value.Atomics,
-		schemametadata.MetadataAtomic_create(schemametadata.MetadataAtomic{Type: "string"}),
-		schemametadata.MetadataAtomic_create(schemametadata.MetadataAtomic{Type: "number"}),
-		schemametadata.MetadataAtomic_create(schemametadata.MetadataAtomic{Type: "bigint"}),
-	)
-	value.Arrays = append(value.Arrays, schemametadata.MetadataArray_create(schemametadata.MetadataArray{
-		Type: schemametadata.MetadataArrayType_create(schemametadata.MetadataArrayType{
-			Name:      "string[]",
-			Value:     schemametadata.MetadataSchema_initialize(),
-			Nullables: []bool{},
-		}),
-	}))
-	property := schemametadata.MetadataProperty_create(schemametadata.MetadataProperty{
-		Key:   commentTagsLiteral("field"),
-		Value: value,
-		JsDocTags: []schemametadata.IJsDocTagInfo{
-			commentTagsText("type", "{uint64}"),
-			commentTagsText("format", "dateTime"),
-			commentTagsText("pattern", "^[a-z]+$"),
-			commentTagsText("length", "3"),
-			commentTagsText("minLength", "1"),
-			commentTagsText("maxLength", "5"),
-			commentTagsText("items", "2"),
-			commentTagsText("minItems", "1"),
-			commentTagsText("maxItems", "4"),
-			{Name: "uniqueItems"},
-			commentTagsText("minimum", "1.5"),
-			commentTagsText("maximum", "9"),
-			commentTagsText("exclusiveMinimum", "0"),
-			commentTagsText("exclusiveMaximum", "10"),
-			commentTagsText("multipleOf", "2"),
-			{Name: "format"},
-		},
-	})
-	object := schemametadata.MetadataObjectType_create(schemametadata.MetadataObjectType{
-		Name:       "CommentTagged",
-		Properties: []*schemametadata.MetadataProperty{nil, property},
-	})
-	errors := []MetadataFactory_IError{}
-	Iterate_metadata_comment_tags(struct {
-		Errors *[]MetadataFactory_IError
-		Object *schemametadata.MetadataObjectType
-	}{Errors: &errors, Object: object})
-	if len(value.Atomics[0].Tags) == 0 ||
-		len(value.Atomics[1].Tags) == 0 ||
-		len(value.Atomics[2].Tags) == 0 ||
-		len(value.Arrays[0].Tags) == 0 ||
-		len(errors) == 0 {
-		t.Fatal("comment tags were not applied to every metadata bucket")
-	}
-	before := len(value.Atomics[0].Tags[0])
-	Iterate_metadata_comment_tags(struct {
-		Errors *[]MetadataFactory_IError
-		Object *schemametadata.MetadataObjectType
-	}{Errors: &errors, Object: object})
-	if len(value.Atomics[0].Tags[0]) != before {
-		t.Fatal("comment tags should not be applied twice to the same object")
-	}
-	Iterate_metadata_comment_tags(struct {
-		Errors *[]MetadataFactory_IError
-		Object *schemametadata.MetadataObjectType
-	}{Errors: &errors})
-	MetadataCommentTagAnalyzer = nil
-	Iterate_metadata_comment_tags(struct {
-		Errors *[]MetadataFactory_IError
-		Object *schemametadata.MetadataObjectType
-	}{Errors: &errors, Object: schemametadata.MetadataObjectType_create(schemametadata.MetadataObjectType{
-		Name:       "NoAnalyzer",
-		Properties: []*schemametadata.MetadataProperty{property},
-	})})
-	file := nativeparser.ParseSourceFile(
-		nativeast.SourceFileParseOptions{FileName: filepath.ToSlash(filepath.Join(t.TempDir(), "comment.ts"))},
-		`interface Box {
+  oldAnalyzer := MetadataCommentTagAnalyzer
+  calls := 0
+  var analyzedMetadata *schemametadata.MetadataSchema
+  var analyzedObject *schemametadata.MetadataObjectType
+  var analyzedProperty any
+  var analyzedTags []schemametadata.IJsDocTagInfo
+  MetadataCommentTagAnalyzer = func(props struct {
+    Errors   *[]MetadataFactory_IError
+    Metadata *schemametadata.MetadataSchema
+    Tags     []schemametadata.IJsDocTagInfo
+    Explore  MetadataFactory_IExplore
+  }) {
+    calls++
+    analyzedMetadata = props.Metadata
+    analyzedObject = props.Explore.Object
+    analyzedProperty = props.Explore.Property
+    analyzedTags = props.Tags
+    if props.Metadata == nil {
+      return
+    }
+    tag := schemametadata.IMetadataTypeTag{Name: "testTag"}
+    for _, atomic := range props.Metadata.Atomics {
+      atomic.Tags = append(atomic.Tags, []schemametadata.IMetadataTypeTag{tag})
+    }
+    for _, array := range props.Metadata.Arrays {
+      array.Tags = append(array.Tags, []schemametadata.IMetadataTypeTag{tag})
+    }
+    if props.Errors != nil {
+      *props.Errors = append(*props.Errors, MetadataFactory_IError{
+        Name: "comment tag(s)",
+        Explore: MetadataFactory_IExplore{
+          Object:   props.Explore.Object,
+          Property: props.Explore.Property,
+        },
+        Messages: []string{"test analyzer error"},
+      })
+    }
+  }
+  defer func() {
+    MetadataCommentTagAnalyzer = oldAnalyzer
+  }()
+  value := schemametadata.MetadataSchema_initialize()
+  value.Atomics = append(value.Atomics,
+    schemametadata.MetadataAtomic_create(schemametadata.MetadataAtomic{Type: "string"}),
+    schemametadata.MetadataAtomic_create(schemametadata.MetadataAtomic{Type: "number"}),
+    schemametadata.MetadataAtomic_create(schemametadata.MetadataAtomic{Type: "bigint"}),
+  )
+  value.Arrays = append(value.Arrays, schemametadata.MetadataArray_create(schemametadata.MetadataArray{
+    Type: schemametadata.MetadataArrayType_create(schemametadata.MetadataArrayType{
+      Name:      "string[]",
+      Value:     schemametadata.MetadataSchema_initialize(),
+      Nullables: []bool{},
+    }),
+  }))
+  property := schemametadata.MetadataProperty_create(schemametadata.MetadataProperty{
+    Key:   commentTagsLiteral("field"),
+    Value: value,
+    JsDocTags: []schemametadata.IJsDocTagInfo{
+      commentTagsText("type", "{uint64}"),
+      commentTagsText("format", "dateTime"),
+      commentTagsText("pattern", "^[a-z]+$"),
+      commentTagsText("length", "3"),
+      commentTagsText("minLength", "1"),
+      commentTagsText("maxLength", "5"),
+      commentTagsText("items", "2"),
+      commentTagsText("minItems", "1"),
+      commentTagsText("maxItems", "4"),
+      {Name: "uniqueItems"},
+      commentTagsText("minimum", "1.5"),
+      commentTagsText("maximum", "9"),
+      commentTagsText("exclusiveMinimum", "0"),
+      commentTagsText("exclusiveMaximum", "10"),
+      commentTagsText("multipleOf", "2"),
+      {Name: "format"},
+    },
+  })
+  object := schemametadata.MetadataObjectType_create(schemametadata.MetadataObjectType{
+    Name:       "CommentTagged",
+    Properties: []*schemametadata.MetadataProperty{nil, property},
+  })
+  errors := []MetadataFactory_IError{}
+  Iterate_metadata_comment_tags(struct {
+    Errors *[]MetadataFactory_IError
+    Object *schemametadata.MetadataObjectType
+  }{Errors: &errors, Object: object})
+  if calls != 1 || analyzedMetadata != value || analyzedObject != object || analyzedProperty != property || !reflect.DeepEqual(analyzedTags, property.JsDocTags) {
+    t.Fatal("comment-tag dispatch did not preserve the property and its location")
+  }
+  for _, rows := range [][][]schemametadata.IMetadataTypeTag{value.Atomics[0].Tags, value.Atomics[1].Tags, value.Atomics[2].Tags, value.Arrays[0].Tags} {
+    if len(rows) != 1 || len(rows[0]) != 1 || rows[0][0].Name != "testTag" {
+      t.Fatal("comment-tag dispatch did not retain the analyzer's single marker tag")
+    }
+  }
+  if len(errors) != 1 || errors[0].Name != "comment tag(s)" || errors[0].Explore.Object != object || errors[0].Explore.Property != property || len(errors[0].Messages) != 1 || errors[0].Messages[0] != "test analyzer error" {
+    t.Fatal("comment-tag dispatch did not propagate the analyzer error")
+  }
+  Iterate_metadata_comment_tags(struct {
+    Errors *[]MetadataFactory_IError
+    Object *schemametadata.MetadataObjectType
+  }{Errors: &errors, Object: object})
+  if calls != 1 {
+    t.Fatal("comment tags should not be applied twice to the same object")
+  }
+  Iterate_metadata_comment_tags(struct {
+    Errors *[]MetadataFactory_IError
+    Object *schemametadata.MetadataObjectType
+  }{Errors: &errors})
+  MetadataCommentTagAnalyzer = nil
+  Iterate_metadata_comment_tags(struct {
+    Errors *[]MetadataFactory_IError
+    Object *schemametadata.MetadataObjectType
+  }{Errors: &errors, Object: schemametadata.MetadataObjectType_create(schemametadata.MetadataObjectType{
+    Name:       "NoAnalyzer",
+    Properties: []*schemametadata.MetadataProperty{property},
+  })})
+  file := nativeparser.ParseSourceFile(
+    nativeast.SourceFileParseOptions{FileName: filepath.ToSlash(filepath.Join(t.TempDir(), "comment.ts"))},
+    `interface Box {
   /**
    * box description
    * @type {string}
@@ -138,47 +157,47 @@ func TestCommentTagsCoverage(t *testing.T) {
   field: string;
 }
 `,
-		nativecore.ScriptKindTS,
-	)
-	member := file.Statements.Nodes[0].AsInterfaceDeclaration().Members.Nodes[0]
-	symbol := &nativeast.Symbol{
-		Name:             "field",
-		ValueDeclaration: member,
-		Declarations:     []*nativeast.Node{member},
-	}
-	if len(metadata_node_js_doc_tags(symbol)) == 0 || metadata_node_description(symbol) == nil {
-		t.Fatal("parsed JSDoc tags and description should be discovered")
-	}
-	for _, jsdoc := range member.JSDoc(nil) {
-		doc := jsdoc.AsJSDoc()
-		if doc == nil || doc.Tags == nil {
-			continue
-		}
-		for _, tag := range doc.Tags.Nodes {
-			_ = metadata_js_doc_type_expression_text(tag)
-			_ = metadata_js_doc_parameter_name(tag)
-		}
-	}
-	if metadata_js_doc_type_expression_text(nil) != "" ||
-		metadata_js_doc_comment_text(nil) != "" {
-		t.Fatal("nil JSDoc helpers should return empty text")
-	}
+    nativecore.ScriptKindTS,
+  )
+  member := file.Statements.Nodes[0].AsInterfaceDeclaration().Members.Nodes[0]
+  symbol := &nativeast.Symbol{
+    Name:             "field",
+    ValueDeclaration: member,
+    Declarations:     []*nativeast.Node{member},
+  }
+  if len(metadata_node_js_doc_tags(symbol)) == 0 || metadata_node_description(symbol) == nil {
+    t.Fatal("parsed JSDoc tags and description should be discovered")
+  }
+  for _, jsdoc := range member.JSDoc(nil) {
+    doc := jsdoc.AsJSDoc()
+    if doc == nil || doc.Tags == nil {
+      continue
+    }
+    for _, tag := range doc.Tags.Nodes {
+      _ = metadata_js_doc_type_expression_text(tag)
+      _ = metadata_js_doc_parameter_name(tag)
+    }
+  }
+  if metadata_js_doc_type_expression_text(nil) != "" ||
+    metadata_js_doc_comment_text(nil) != "" {
+    t.Fatal("nil JSDoc helpers should return empty text")
+  }
 }
 
 func commentTagsText(name string, text string) schemametadata.IJsDocTagInfo {
-	return schemametadata.IJsDocTagInfo{
-		Name: name,
-		Text: []schemametadata.IJsDocTagInfo_IText{{Kind: "text", Text: text}},
-	}
+  return schemametadata.IJsDocTagInfo{
+    Name: name,
+    Text: []schemametadata.IJsDocTagInfo_IText{{Kind: "text", Text: text}},
+  }
 }
 
 func commentTagsLiteral(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
+  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
 }

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

@@ -1,7 +1,20 @@
 package metadata
 
-import schemametadata "github.com/samchon/typia/packages/typia/native/core/schemas/metadata"
+import (
+  "reflect"
 
+  schemametadata "github.com/samchon/typia/packages/typia/native/core/schemas/metadata"
+)
+
+// Emend_metadata_atomics removes constants that an atomic of the same type
+// already covers without validation requirements and folds a boolean constant
+// of both values into one boolean. An unconstrained string atomic also removes
+// template alternatives.
+//
+// @evidence contracts/common.md#principled-implementation A constant of a type that an atomic of the same type already covers is redundant and is removed, and a boolean constant set with both values is replaced by a boolean atomic, keeping both alternatives if the two values carry different tags; this normalizes unions such as `string | "a"` and `true | false`.
+// @evidence contracts/common.md#clear-and-simple-design One function over the metadata's constants and atomics, applied by the explorer to the schema and its escaped halves.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The rules follow set inclusion of values and no consumer type is involved.
+// @evidence contracts/common.md#meaningful-documentation The doc states both rewrites.
 func Emend_metadata_atomics(meta *schemametadata.MetadataSchema) {
   for _, atomic := range meta.Atomics {
     if is_not_pure(atomic) {
@@ -41,6 +54,20 @@ func Emend_metadata_atomics(meta *schemametadata.MetadataSchema) {
       if len(temp.Values) != 0 && temp.Values[0] != nil {
         tags = temp.Values[0].Tags
       }
+      // `true` and `false` fold into one boolean; when they carry different
+      // tags (`(true & A) | (false & B)`), keep both alternatives instead of
+      // silently dropping the second
+      if len(temp.Values) == 2 && temp.Values[0] != nil && temp.Values[1] != nil &&
+        reflect.DeepEqual(temp.Values[0].Tags, temp.Values[1].Tags) == false {
+        tags = [][]schemametadata.IMetadataTypeTag{}
+        for _, value := range temp.Values {
+          // a literal without tags is an alternative that states nothing
+          if len(value.Tags) == 0 {
+            tags = append(tags, []schemametadata.IMetadataTypeTag{})
+          }
+          tags = append(tags, value.Tags...)
+        }
+      }
       meta.Atomics = append(meta.Atomics, schemametadata.MetadataAtomic_create(schemametadata.MetadataAtomic{
         Type: "boolean",
         Tags: tags,

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

@@ -2,6 +2,14 @@ package metadata
 
 import schemametadata "github.com/samchon/typia/packages/typia/native/core/schemas/metadata"
 
+// Emplace_metadata_alias returns the collection's alias entry for the type,
+// recording a new one with its documentation and the analyzed target; a known one
+// only records another nullability.
+//
+// @evidence contracts/common.md#principled-implementation An alias is stored once per type in the collection and a repeat only records another nullability, so a recursive or shared alias is analyzed once; the first time its documentation is read from the alias symbol, skipping default-library declarations, and its target type is explored with the aliased state so the target is not wrapped in the same alias again.
+// @evidence contracts/common.md#clear-and-simple-design One function over the collection's emplace service, which returns whether the entry is new.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Library aliases do not leak their documentation, as the comment states.
+// @evidence contracts/common.md#meaningful-documentation The doc states the once-per-type rule and the documentation source.
 func Emplace_metadata_alias(props IMetadataIteratorProps) *schemametadata.MetadataAliasType {
   symbol := props.Type.Symbol()
   if typeName := nativechecker_type_name_symbol(props.Type); typeName != nil {
@@ -10,15 +18,14 @@ func Emplace_metadata_alias(props IMetadataIteratorProps) *schemametadata.Metada
   alias, newbie, closure := props.Components.EmplaceAlias(
     props.Checker,
     props.Type,
-    symbol,
   )
   metadata_array_util_add_bool(&alias.Nullables, props.Metadata.Nullable)
   if newbie == false {
     return alias
   }
 
-  // The MetadataCollection layer stubs description / tags (the AST JSDoc helpers
-  // live in this factory package), so fill them here from the alias symbol. The
+  // The collection creates the entry without documentation (the AST JSDoc
+  // helpers live in this factory package), so fill it here from the alias symbol. The
   // type-level readers skip default-library declarations, so a standard-library
   // alias such as `NonNullable<...>` does not leak its own JSDoc.
   alias.Description = metadata_node_type_description(symbol)

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

@@ -5,11 +5,28 @@ import (
   schemametadata "github.com/samchon/typia/packages/typia/native/core/schemas/metadata"
 )
 
+// Emplace_metadata_array_type_IProps is the iterator state plus the array type to
+// record.
+//
+// @evidence contracts/common.md#principled-implementation The iterator state is embedded and the array type to record is added, because the entry is keyed by the type and its element is read from it.
+// @evidence contracts/common.md#clear-and-simple-design An embedded record and one field.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A data record.
+// @evidence contracts/common.md#meaningful-documentation The doc states the composition.
 type Emplace_metadata_array_type_IProps struct {
+  // IMetadataIteratorProps retains the encountered type used as collection key.
   IMetadataIteratorProps
+
+  // Array is the resolved array/base type from which element arguments are read.
   Array *nativechecker.Type
 }
 
+// Emplace_metadata_array_type returns the collection's entry for the array type,
+// analyzing its element type the first time it is seen.
+//
+// @evidence contracts/common.md#principled-implementation The encountered props.Type is stored once in the collection, including subclasses whose resolved Array base differs; repeats record nullability. The element comes from Array's first checker type argument when available, otherwise Array itself, and is explored with aliased and escaped states cleared.
+// @evidence contracts/common.md#clear-and-simple-design One function over the collection's emplace service.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The element is taken from the checker's type arguments, not from the source text.
+// @evidence contracts/common.md#meaningful-documentation The doc states the once-per-type rule and the element source.
 func Emplace_metadata_array_type(props Emplace_metadata_array_type_IProps) *schemametadata.MetadataArrayType {
   array, newbie, setValue := props.Components.EmplaceArray(
     props.Checker,

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

@@ -8,6 +8,17 @@ import (
   schemametadata "github.com/samchon/typia/packages/typia/native/core/schemas/metadata"
 )
 
+// Emplace_metadata_object returns the collection's entry for the object type,
+// building its properties the first time it is seen.
+//
+// It records documentation, the declaring file and class facts, skips members
+// that have no JSON form, analyzes every property and index signature and
+// delegates to the intersection merge when the type is an intersection.
+//
+// @evidence contracts/common.md#principled-implementation The collection registers an object before exploring its members, preserving recursive identity. First sight fills type documentation and available source/class facts. The modifier/symbol/member-kind filter depends on Functional, Methods and StrictObjectMembers: methods can be retained explicitly and strict mode diagnoses unsupported members. Visible properties and supported index domains become key/value schemas, while eligible disjoint plain-object intersections share parent objects and copy property roots. Heritage dependency reporting includes otherwise empty bases.
+// @evidence contracts/common.md#clear-and-simple-design One long function that holds the member filter as a closure and delegates heritage touching, privacy detection, symbol-name tests and property creation to private helpers; the length reflects the many member kinds a TypeScript object can have.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The member filter is by symbol and modifier kinds, with the symbol rule referencing the cited issue, and no property name is special-cased.
+// @evidence contracts/common.md#meaningful-documentation Long comments explain each rule at its place; the exported function has its own doc.
 func Emplace_metadata_object(props IMetadataIteratorProps) *schemametadata.MetadataObjectType {
   obj, newbie := props.Components.Emplace(props.Checker, props.Type)
   metadata_array_util_add_bool(&obj.Nullables, props.Metadata.Nullable)
@@ -30,7 +41,7 @@ func Emplace_metadata_object(props IMetadataIteratorProps) *schemametadata.Metad
     obj.Description = metadata_node_type_description(symbol)
     obj.JsDocTags = metadata_node_type_js_doc_tags(symbol)
 
-    // Capture the declaring source file (named declarations only) so
+    // Capture the first symbol declaration's source file when locatable so
     // plain.classify can value-import a cross-module class it reconstructs.
     // Additive: other features ignore obj.Source.
     if sym := props.Type.Symbol(); sym != nil && len(sym.Declarations) != 0 {

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

@@ -5,6 +5,16 @@ import (
   schemametadata "github.com/samchon/typia/packages/typia/native/core/schemas/metadata"
 )
 
+// Emplace_metadata_tuple returns the collection's entry for the tuple type,
+// analyzing its elements the first time it is seen.
+//
+// Optional elements are marked optional, a trailing rest element is wrapped in a
+// rest schema, and a rest element elsewhere is reported as unsupported.
+//
+// @evidence contracts/common.md#principled-implementation A tuple type is stored once and its element types are the checker's type arguments, each explored in a nested state; an optional element is marked optional, a rest element in the last position is wrapped in a schema with the Rest field, and a rest element anywhere else is reported because the programmers address elements by leading position.
+// @evidence contracts/common.md#clear-and-simple-design One function over the collection's emplace service with a closure that receives the elements.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The unsupported position is rejected with a message and not compiled into wrong checks, as the comment records.
+// @evidence contracts/common.md#meaningful-documentation The doc states the optional and rest rules.
 func Emplace_metadata_tuple(props IMetadataIteratorProps) *schemametadata.MetadataTupleType {
   tuple, newbie, closure := props.Components.EmplaceTuple(
     props.Checker,

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

@@ -5,18 +5,57 @@ import (
   schemametadata "github.com/samchon/typia/packages/typia/native/core/schemas/metadata"
 )
 
+// Explore_metadata_IProps is the input of one exploration: options, checker, the
+// collection, the error sink, the type, the location and the Intersected, NoCache
+// and Prunable flags.
+//
+// @evidence contracts/common.md#principled-implementation An exploration needs the options, checker, collection, error sink, type and location plus three flags, NoCache to bypass the cache, Intersected for the inside of an intersection and Prunable for never pruning.
+// @evidence contracts/common.md#clear-and-simple-design One flat record.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A data record.
+// @evidence contracts/common.md#meaningful-documentation The doc lists the inputs.
 type Explore_metadata_IProps struct {
-  Options     MetadataFactory_IOptions
-  Checker     *nativechecker.Checker
-  Components  *schemametadata.MetadataCollection
-  Errors      *[]MetadataFactory_IError
-  Type        *nativechecker.Type
-  Explore     MetadataFactory_IExplore
+  // Options supplies the analysis shape and hooks; member options stay fixed
+  // within the collection.
+  Options MetadataFactory_IOptions
+
+  // Checker resolves Type in the collection's compiler program.
+  Checker *nativechecker.Checker
+
+  // Components owns named entries and cached schemas for this analysis.
+  Components *schemametadata.MetadataCollection
+
+  // Errors is the optional append-only sink; added errors prevent cache storage.
+  Errors *[]MetadataFactory_IError
+
+  // Type is explored into a fresh schema; nil returns the initialized schema.
+  Type *nativechecker.Type
+
+  // Explore supplies the diagnostic location and shape-state flags.
+  Explore MetadataFactory_IExplore
+
+  // Intersected suppresses nested intersection handling and disables cache use.
   Intersected bool
-  NoCache     bool
-  Prunable    bool
+
+  // NoCache bypasses lookup and storage for exploratory analysis.
+  NoCache bool
+
+  // Prunable permits impossible intersection branches to contribute no values.
+  Prunable bool
 }
 
+// Explore_metadata analyzes a type into a new metadata schema.
+//
+// A result is cached in the collection by type and by the options that change
+// it, but only outside an intersected descent and when this exploration adds no
+// error. Plain-object intersection types are also eligible. One collection is
+// used for one checker/program and fixed Methods/StrictObjectMembers options;
+// the key does not encode every option or location. Atomics are emended after
+// the iterators ran.
+//
+// @evidence contracts/common.md#principled-implementation A fresh schema is filled by Iterate_metadata and emended. Eligible results are cloned through the collection cache keyed by type, Escape/Absorb/Constant/Functional and Top/Aliased/Escaped/Output. Intersected descent, NoCache and explorations adding errors bypass storage; plain-object intersections can be cached. The collection is local to one checker/program and fixed member options, and the key does not encode Prunable or complete location identities.
+// @evidence contracts/common.md#clear-and-simple-design One function with the cache lookup before and the cache store after the iteration.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Cache entries are analysis-local cloned schemas, not foreign checker mutations. NoCache and Intersected explicitly bypass reuse; member options must stay fixed within the collection. Prunable is not represented by the current key, so the key alone does not establish equivalence across pruning contexts.
+// @evidence contracts/common.md#meaningful-documentation The doc states the cache conditions.
 func Explore_metadata(props Explore_metadata_IProps) *schemametadata.MetadataSchema {
   plainObjectIntersection := false
   if props.Checker != nil && props.Type != nil && props.Type.IsIntersection() {
@@ -48,7 +87,7 @@ func Explore_metadata(props Explore_metadata_IProps) *schemametadata.MetadataSch
   if props.Errors != nil {
     errorCount = len(*props.Errors)
   }
-  metadata := schemametadata.MetadataSchema_initialize(props.Explore.Escaped)
+  metadata := schemametadata.MetadataSchema_initialize()
   if props.Type == nil {
     return metadata
   }

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

@@ -5,6 +5,18 @@ import (
   schemametadata "github.com/samchon/typia/packages/typia/native/core/schemas/metadata"
 )
 
+// Iterate_metadata fills a metadata schema from a type by trying the iterators in
+// a fixed order until one accepts it.
+//
+// Aliases, intersections, unions and escapes come first, then any, null and
+// undefined-like types, functions, constants, templates, atomics, tuples, arrays,
+// natives, maps, sets and finally objects. A type parameter is reported as an
+// error.
+//
+// @evidence contracts/common.md#principled-implementation The chain tries each iterator in a fixed order and stops at the first that accepts: alias, intersection, union and escape first so wrappers are expanded before their contents, then special types, functions, constants, templates, atomics, tuples, arrays, natives, maps, sets and objects, with object last as the catch-all; an unresolved type parameter is an error. Every type that the analysis reads passes through the first dependency touch, so the transform host learns every declaration file consulted.
+// @evidence contracts/common.md#clear-and-simple-design One function that is the dispatcher, with each iterator owning one type kind; adding a kind means adding an iterator and a position in the order.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The order is explicit and documented here, not left to side effects; the dependency touch is one call at the entry, not a patch of the checker.
+// @evidence contracts/common.md#meaningful-documentation The doc lists the order and the comment explains the dependency touch.
 func Iterate_metadata(props IMetadataIteratorProps) {
   if props.Type == nil {
     return

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

@@ -6,6 +6,14 @@ import (
   schemametadata "github.com/samchon/typia/packages/typia/native/core/schemas/metadata"
 )
 
+// Iterate_metadata_alias records a type alias as a named alias entry instead of
+// expanding it. It reports false when the Absorb option is on and for a type that
+// is not declared by a type alias.
+//
+// @evidence contracts/common.md#principled-implementation A type declared by a type alias is recorded as an alias entry that refers to the emplaced alias type, so recursive and shared aliases keep their names in the schema; it declines when Absorb is on, which analyzes the structure inside an intersection, and for any type not declared by a type alias.
+// @evidence contracts/common.md#clear-and-simple-design One function over the shared emplace service; the symbol lookup is a small private wrapper.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The test is the declaration kind of the alias symbol and no alias name is listed.
+// @evidence contracts/common.md#meaningful-documentation The doc states both declines.
 func Iterate_metadata_alias(props IMetadataIteratorProps) bool {
   if props.Options.Absorb != false {
     return false

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

@@ -5,6 +5,13 @@ import (
   schemametadata "github.com/samchon/typia/packages/typia/native/core/schemas/metadata"
 )
 
+// Iterate_metadata_array records an array type, or a class or interface that
+// extends an array, as an array entry. It reports false for any other type.
+//
+// @evidence contracts/common.md#principled-implementation The checker's array test accepts array types, and a class or interface that extends an array is found by walking its base types with a memo table so cycles end; the array type is emplaced and recorded once per name in the schema.
+// @evidence contracts/common.md#clear-and-simple-design One function and a private recursive finder.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The array identity comes from the checker, not from the type's text.
+// @evidence contracts/common.md#meaningful-documentation The doc states the extended-array case.
 func Iterate_metadata_array(props IMetadataIteratorProps) bool {
   var array *nativechecker.Type
   if props.Checker != nil && nativechecker.Checker_isArrayType(props.Checker, props.Type) {