typia 15.0.0 → 15.1.0

package/native/core/context/transformer_error_formatting_test.go

@@ -4,10 +4,10 @@
 package context
 
 import (
-	"strings"
-	"testing"
+  "strings"
+  "testing"
 
-	schemametadata "github.com/samchon/typia/packages/typia/native/core/schemas/metadata"
+  schemametadata "github.com/samchon/typia/packages/typia/native/core/schemas/metadata"
 )
 
 // TestTransformerErrorFormatting covers metadata error rendering.
@@ -21,80 +21,85 @@ import (
 // 2. Render object property, dynamic-key, parameter, and return diagnostics.
 // 3. Exercise JSON fallback formatting for unmarshalable values.
 // 4. Verify identifier path validation for edge names.
+//
+// @evidence contracts/testing.md#behavioral-verification Transformer errors are rendered from direct errors and metadata factory errors; the message text, required fragments, null rendering of unmarshalable values and variable-path classification are checked.
+// @evidence contracts/testing.md#independent-expectations Authored errors and the expected fragments follow the documented diagnostic format.
+// @evidence contracts/testing.md#distinguishing-cases Direct errors, factory errors, unmarshalable values and path segments each flip a formatting branch.
+// @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 the formatter on constructed errors with no checker, filesystem fixture or process.
 func TestTransformerErrorFormatting(t *testing.T) {
-	err := NewTransformerError(TransformerError_IProps{
-		Code:    "typia.test",
-		Message: "message",
-	})
-	if err.Error() != "message" {
-		t.Fatalf("direct error message mismatch: %s", err.Error())
-	}
+  err := NewTransformerError(TransformerError_IProps{
+    Code:    "typia.test",
+    Message: "message",
+  })
+  if err.Error() != "message" {
+    t.Fatalf("direct error message mismatch: %s", err.Error())
+  }
 
-	object := schemametadata.MetadataObjectType{Name: "IObject"}
-	formatted := TransformerError_from(struct {
-		Code   string
-		Errors []TransformerError_MetadataFactory_IError
-	}{
-		Code: "typia.fixture",
-		Errors: []TransformerError_MetadataFactory_IError{
-			{
-				Name: "string",
-				Explore: TransformerError_MetadataFactory_IExplore{
-					Object:   &object,
-					Property: "validName",
-				},
-				Messages: []string{"valid property"},
-			},
-			{
-				Name: "number",
-				Explore: TransformerError_MetadataFactory_IExplore{
-					Object:   &object,
-					Property: "invalid-name",
-				},
-				Messages: []string{"quoted property"},
-			},
-			{
-				Name: "dynamic",
-				Explore: TransformerError_MetadataFactory_IExplore{
-					Object:   &object,
-					Property: map[string]any{"key": true},
-				},
-				Messages: []string{"dynamic key"},
-			},
-			{
-				Name: "parameter",
-				Explore: TransformerError_MetadataFactory_IExplore{
-					Parameter: map[string]any{"index": 0},
-				},
-				Messages: []string{"parameter message"},
-			},
-			{
-				Name: "output",
-				Explore: TransformerError_MetadataFactory_IExplore{
-					Output: true,
-				},
-				Messages: []string{"return message"},
-			},
-		},
-	})
-	text := formatted.Error()
-	for _, part := range []string{
-		"IObject.validName: string",
-		"IObject[\"invalid-name\"]: number",
-		"IObject[key]: dynamic",
-		"(parameter: {\"index\":0})",
-		"(return type)",
-	} {
-		if !strings.Contains(text, part) {
-			t.Fatalf("formatted transformer error missing %q:\n%s", part, text)
-		}
-	}
-	if transformerError_json(func() {}) != "null" {
-		t.Fatal("unmarshalable values should render as null")
-	}
-	for _, name := range []string{"", "1bad", "bad-name"} {
-		if transformerError_variable(name) {
-			t.Fatalf("%q should not be a variable path segment", name)
-		}
-	}
+  object := schemametadata.MetadataObjectType{Name: "IObject"}
+  formatted := TransformerError_from(struct {
+    Code   string
+    Errors []TransformerError_MetadataFactory_IError
+  }{
+    Code: "typia.fixture",
+    Errors: []TransformerError_MetadataFactory_IError{
+      {
+        Name: "string",
+        Explore: TransformerError_MetadataFactory_IExplore{
+          Object:   &object,
+          Property: "validName",
+        },
+        Messages: []string{"valid property"},
+      },
+      {
+        Name: "number",
+        Explore: TransformerError_MetadataFactory_IExplore{
+          Object:   &object,
+          Property: "invalid-name",
+        },
+        Messages: []string{"quoted property"},
+      },
+      {
+        Name: "dynamic",
+        Explore: TransformerError_MetadataFactory_IExplore{
+          Object:   &object,
+          Property: map[string]any{"key": true},
+        },
+        Messages: []string{"dynamic key"},
+      },
+      {
+        Name: "parameter",
+        Explore: TransformerError_MetadataFactory_IExplore{
+          Parameter: map[string]any{"index": 0},
+        },
+        Messages: []string{"parameter message"},
+      },
+      {
+        Name: "output",
+        Explore: TransformerError_MetadataFactory_IExplore{
+          Output: true,
+        },
+        Messages: []string{"return message"},
+      },
+    },
+  })
+  text := formatted.Error()
+  for _, part := range []string{
+    "IObject.validName: string",
+    "IObject[\"invalid-name\"]: number",
+    "IObject[key]: dynamic",
+    "(parameter: {\"index\":0})",
+    "(return type)",
+  } {
+    if !strings.Contains(text, part) {
+      t.Fatalf("formatted transformer error missing %q:\n%s", part, text)
+    }
+  }
+  if transformerError_json(func() {}) != "null" {
+    t.Fatal("unmarshalable values should render as null")
+  }
+  for _, name := range []string{"", "1bad", "bad-name"} {
+    if transformerError_variable(name) {
+      t.Fatalf("%q should not be a variable path segment", name)
+    }
+  }
 }

package/native/core/factories/CommentFactory.go

@@ -10,7 +10,15 @@ type commentFactoryNamespace struct{}
 
 var CommentFactory = commentFactoryNamespace{}
 
+// CommentFactory_SymbolDisplayPart is one piece of a documentation comment; Merge
+// joins the text of the pieces and normalizes CRLF to LF.
+//
+// @evidence contracts/common.md#principled-implementation A comment is a sequence of display parts whose texts concatenate to the comment, which is the representation the checker's documentation API uses; the record keeps only the text because Merge needs nothing else.
+// @evidence contracts/common.md#clear-and-simple-design One field; the factory method that consumes it is a stateless merge.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A data record.
+// @evidence contracts/common.md#meaningful-documentation The doc states what a part is and what Merge does with it.
 type CommentFactory_SymbolDisplayPart struct {
+  // Text contributes verbatim text, apart from Merge's CRLF normalization.
   Text string
 }
 

package/native/core/factories/ExpressionFactory.go

@@ -19,36 +19,137 @@ type expressionFactoryNamespace struct{}
 
 var ExpressionFactory = expressionFactoryNamespace{}
 
+// ExpressionFactory_IsObjectProps selects the checks of an object test on Input:
+// whether null and arrays are excluded.
+//
+// @evidence contracts/common.md#principled-implementation The object test is built from the input expression and two switches, so the same builder yields `typeof x === "object"` with or without the null and array exclusions that a caller's type allows.
+// @evidence contracts/common.md#clear-and-simple-design A three-field argument record for IsObject.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A data record.
+// @evidence contracts/common.md#meaningful-documentation The doc states the two switches.
 type ExpressionFactory_IsObjectProps struct {
-  CheckNull  bool
+  // CheckNull excludes null from JavaScript's object category.
+  CheckNull bool
+
+  // CheckArray excludes arrays from JavaScript's object category.
   CheckArray bool
-  Input      *shimast.Expression
+
+  // Input is the expression tested; the generated checks may evaluate it more
+  // than once, so callers provide a stable reference.
+  Input *shimast.Expression
 }
 
+// ExpressionFactory_CurryingProps builds successive unary calls of Function.
+// Empty Arguments builds a single call with no arguments.
+//
+// @evidence contracts/common.md#principled-implementation The first argument calls Function and each remaining argument calls the previous result, representing successive unary application; an empty list requests one zero-argument call.
+// @evidence contracts/common.md#clear-and-simple-design A two-field argument record for Currying.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A data record.
+// @evidence contracts/common.md#meaningful-documentation The doc states both fields.
 type ExpressionFactory_CurryingProps struct {
-  Function  *shimast.Expression
+  // Function is the expression called first.
+  Function *shimast.Expression
+
+  // Arguments is applied one element per successive call, in slice order.
   Arguments []*shimast.Expression
 }
 
+// ExpressionFactory_TranspileProps configures a parsed expression template.
+// The first statement must be an expression statement; later statements are
+// ignored. Transpile panics if that first statement is absent or has another
+// kind. The returned builder substitutes $input and recognized import calls.
+//
+// @evidence contracts/common.md#principled-implementation Transpile parses a script into an expression once and substitutes the caller's input, so it needs the script text and an importer for references that the script makes to internal helpers.
+// @evidence contracts/common.md#clear-and-simple-design A two-field argument record for Transpile.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A data record.
+// @evidence contracts/common.md#meaningful-documentation The doc states both fields.
 type ExpressionFactory_TranspileProps struct {
+  // Importer resolves recognized $import calls; nil leaves them unchanged.
   Importer ExpressionFactory_Importer
-  Script   string
+
+  // Script supplies the first expression statement used as the template.
+  Script string
 }
 
+// ExpressionFactory_Importer is the part of the import programmer that expression
+// helpers need: references to internal helpers and to named, namespace and
+// default imports.
+//
+// @evidence contracts/common.md#principled-implementation Expression helpers reference internal helpers and imports only through four calls, so the interface lists exactly those and any importer, including the ImportProgrammer, satisfies it without a dependency cycle.
+// @evidence contracts/common.md#clear-and-simple-design A four-method interface that the importer implements; the aliases below it keep the argument types owned by the context package.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A declaration only.
+// @evidence contracts/common.md#meaningful-documentation The doc states that it is the importer's slice that expressions use.
 type ExpressionFactory_Importer interface {
+  // Internal returns the reference to an internal runtime helper and registers its import.
+  //
+  // @evidence contracts/common.md#principled-implementation Internal helpers are the generated code's only dependency on typia's runtime, so the importer must register every one it hands out, and the method name and the doc state that.
+  // @evidence contracts/common.md#clear-and-simple-design One method on a four-method interface.
+  // @evidence contracts/common.md#prohibited-implementation-shortcuts A declaration only.
+  // @evidence contracts/common.md#meaningful-documentation The comment states the reference and the registration.
   Internal(name string) *shimast.Node
+
+  // Instance returns the reference to a named export of a file and registers the import.
+  //
+  // @evidence contracts/common.md#principled-implementation A named export is identified by file and name, and the importer records the request so the import statement is emitted once.
+  // @evidence contracts/common.md#clear-and-simple-design One method on a four-method interface.
+  // @evidence contracts/common.md#prohibited-implementation-shortcuts A declaration only.
+  // @evidence contracts/common.md#meaningful-documentation The comment states the reference and the registration.
   Instance(props ExpressionFactory_IInstance) *shimast.Node
+
+  // Namespace returns the reference to a file's namespace import and registers the import.
+  //
+  // @evidence contracts/common.md#principled-implementation A namespace import is identified by file and name, and the importer records the request so the import statement is emitted once.
+  // @evidence contracts/common.md#clear-and-simple-design One method on a four-method interface.
+  // @evidence contracts/common.md#prohibited-implementation-shortcuts A declaration only.
+  // @evidence contracts/common.md#meaningful-documentation The comment states the reference and the registration.
   Namespace(props ExpressionFactory_INamespace) *shimast.Node
+
+  // Default returns the reference to a file's default import and registers the import.
+  //
+  // @evidence contracts/common.md#principled-implementation A default import is identified by file and local name, and the importer records the request so the import statement is emitted once.
+  // @evidence contracts/common.md#clear-and-simple-design One method on a four-method interface.
+  // @evidence contracts/common.md#prohibited-implementation-shortcuts A declaration only.
+  // @evidence contracts/common.md#meaningful-documentation The comment states the reference and the registration.
   Default(props ExpressionFactory_IDefault) *shimast.Node
 }
 
 // ImportProgrammer owns these import argument shapes in core/context. This
 // package only aliases them so expression helpers do not duplicate the contract.
+//
+// @evidence contracts/common.md#principled-implementation The alias names the importer's default import request, so this package repeats no field list.
+// @evidence contracts/common.md#clear-and-simple-design A type alias to the context package's record.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A declaration only.
+// @evidence contracts/common.md#meaningful-documentation The comment states that the context package owns the shape.
 type ExpressionFactory_IDefault = nativecontext.ImportProgrammer_IDefault
+
+// ExpressionFactory_IInstance is the importer's named-import request, aliased so
+// this package does not repeat the contract.
+//
+// @evidence contracts/common.md#principled-implementation The alias names the importer's named-import request.
+// @evidence contracts/common.md#clear-and-simple-design A type alias to the context package's record.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A declaration only.
+// @evidence contracts/common.md#meaningful-documentation The doc states that the context package owns the shape.
 type ExpressionFactory_IInstance = nativecontext.ImportProgrammer_IInstance
+
+// ExpressionFactory_INamespace is the importer's namespace-import request,
+// aliased so this package does not repeat the contract.
+//
+// @evidence contracts/common.md#principled-implementation The alias names the importer's namespace-import request.
+// @evidence contracts/common.md#clear-and-simple-design A type alias to the context package's record.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A declaration only.
+// @evidence contracts/common.md#meaningful-documentation The doc states that the context package owns the shape.
 type ExpressionFactory_INamespace = nativecontext.ImportProgrammer_INamespace
 
+// ExpressionFactory_GetEscapedTextProps holds the expression whose escaped text
+// is wanted.
+//
+// @evidence contracts/common.md#principled-implementation GetEscapedText returns the text of an identifier or string literal and otherwise the name of the expression, so a single input expression is the whole argument.
+// @evidence contracts/common.md#clear-and-simple-design A one-field argument record.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A data record.
+// @evidence contracts/common.md#meaningful-documentation The doc states the field.
 type ExpressionFactory_GetEscapedTextProps struct {
+  // Input is an identifier or string literal whose text is returned directly,
+  // or another expression whose name is delegated to IdentifierFactory. Nil
+  // returns the empty string.
   Input *shimast.Expression
 }
 
@@ -57,7 +158,22 @@ var expressionFactory_factory = shimast.NewNodeFactory(shimast.NodeFactoryHooks{
 func (expressionFactoryNamespace) Number(value any, emit ...*shimprinter.EmitContext) *shimast.Node {
   f := nativecontext.EmitFactoryOf(expressionFactory_factory, emit...)
   text, numeric := expressionFactory_number_text(value)
-  if numeric < 0 {
+  // Go spells the non-finite floats `NaN`, `+Inf`, and `-Inf`. Only the first
+  // happens to be JavaScript; `+Inf` evaluates an undeclared `Inf` and throws a
+  // ReferenceError when the emitted function first runs (samchon/typia#2452).
+  // Spell them as the globals, as TypeScript's own factory does.
+  if math.IsNaN(numeric) {
+    return f.NewIdentifier("NaN")
+  }
+  if math.IsInf(numeric, 0) {
+    if numeric < 0 {
+      return f.NewPrefixUnaryExpression(shimast.KindMinusToken, f.NewIdentifier("Infinity"))
+    }
+    return f.NewIdentifier("Infinity")
+  }
+  // Negative zero takes the same negation as every negative value; its text
+  // `-0` is not a numeric literal on its own.
+  if numeric < 0 || (numeric == 0 && math.Signbit(numeric)) {
     return f.NewPrefixUnaryExpression(
       shimast.KindMinusToken,
       f.NewNumericLiteral(expressionFactory_number_abs_text(numeric), shimast.TokenFlagsNone),

package/native/core/factories/FormatCheatSheet.go

@@ -52,7 +52,7 @@ var FormatCheatSheet = map[string]string{
   "ipv6":                  `/^((([0-9a-f]{1,4}:){7}([0-9a-f]{1,4}|:))|(([0-9a-f]{1,4}:){6}(:[0-9a-f]{1,4}|((25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3})|:))|(([0-9a-f]{1,4}:){5}(((:[0-9a-f]{1,4}){1,2})|:((25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3})|:))|(([0-9a-f]{1,4}:){4}(((:[0-9a-f]{1,4}){1,3})|((:[0-9a-f]{1,4})?:((25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}))|:))|(([0-9a-f]{1,4}:){3}(((:[0-9a-f]{1,4}){1,4})|((:[0-9a-f]{1,4}){0,2}:((25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}))|:))|(([0-9a-f]{1,4}:){2}(((:[0-9a-f]{1,4}){1,5})|((:[0-9a-f]{1,4}){0,3}:((25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}))|:))|(([0-9a-f]{1,4}:){1}(((:[0-9a-f]{1,4}){1,6})|((:[0-9a-f]{1,4}){0,4}:((25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}))|:))|(:(((:[0-9a-f]{1,4}){1,7})|((:[0-9a-f]{1,4}){0,5}:((25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}))|:)))$/i.test($input)`,
   "uri":                   "/\\/|:/.test($input) && /^(?:[a-z][a-z0-9+\\-.]*:)(?:\\/?\\/(?:(?:[a-z0-9\\-._~!$&'()*+,;=:]|%[0-9a-f]{2})*@)?(?:\\[(?:(?:(?:(?:[0-9a-f]{1,4}:){6}|::(?:[0-9a-f]{1,4}:){5}|(?:[0-9a-f]{1,4})?::(?:[0-9a-f]{1,4}:){4}|(?:(?:[0-9a-f]{1,4}:){0,1}[0-9a-f]{1,4})?::(?:[0-9a-f]{1,4}:){3}|(?:(?:[0-9a-f]{1,4}:){0,2}[0-9a-f]{1,4})?::(?:[0-9a-f]{1,4}:){2}|(?:(?:[0-9a-f]{1,4}:){0,3}[0-9a-f]{1,4})?::[0-9a-f]{1,4}:|(?:(?:[0-9a-f]{1,4}:){0,4}[0-9a-f]{1,4})?::)(?:[0-9a-f]{1,4}:[0-9a-f]{1,4}|(?:(?:25[0-5]|2[0-4]\\d|[01]?\\d\\d?)\\.){3}(?:25[0-5]|2[0-4]\\d|[01]?\\d\\d?))|(?:(?:[0-9a-f]{1,4}:){0,5}[0-9a-f]{1,4})?::[0-9a-f]{1,4}|(?:(?:[0-9a-f]{1,4}:){0,6}[0-9a-f]{1,4})?::)|[Vv][0-9a-f]+\\.[a-z0-9\\-._~!$&'()*+,;=:]+)\\]|(?:(?:25[0-5]|2[0-4]\\d|[01]?\\d\\d?)\\.){3}(?:25[0-5]|2[0-4]\\d|[01]?\\d\\d?)|(?:[a-z0-9\\-._~!$&'()*+,;=]|%[0-9a-f]{2})*)(?::\\d*)?(?:\\/(?:[a-z0-9\\-._~!$&'()*+,;=:@]|%[0-9a-f]{2})*)*|\\/(?:(?:[a-z0-9\\-._~!$&'()*+,;=:@]|%[0-9a-f]{2})+(?:\\/(?:[a-z0-9\\-._~!$&'()*+,;=:@]|%[0-9a-f]{2})*)*)?|(?:[a-z0-9\\-._~!$&'()*+,;=:@]|%[0-9a-f]{2})+(?:\\/(?:[a-z0-9\\-._~!$&'()*+,;=:@]|%[0-9a-f]{2})*)*)(?:\\?(?:[a-z0-9\\-._~!$&'()*+,;=:@/?]|%[0-9a-f]{2})*)?(?:#(?:[a-z0-9\\-._~!$&'()*+,;=:@/?]|%[0-9a-f]{2})*)?$/i.test($input)",
   "uri-reference":         "/^(?:(?:[a-z][a-z0-9+\\-.]*:)?(?:\\/?\\/(?:(?:[a-z0-9\\-._~!$&'()*+,;=:]|%[0-9a-f]{2})*@)?(?:\\[(?:(?:(?:(?:[0-9a-f]{1,4}:){6}|::(?:[0-9a-f]{1,4}:){5}|(?:[0-9a-f]{1,4})?::(?:[0-9a-f]{1,4}:){4}|(?:(?:[0-9a-f]{1,4}:){0,1}[0-9a-f]{1,4})?::(?:[0-9a-f]{1,4}:){3}|(?:(?:[0-9a-f]{1,4}:){0,2}[0-9a-f]{1,4})?::(?:[0-9a-f]{1,4}:){2}|(?:(?:[0-9a-f]{1,4}:){0,3}[0-9a-f]{1,4})?::[0-9a-f]{1,4}:|(?:(?:[0-9a-f]{1,4}:){0,4}[0-9a-f]{1,4})?::)(?:[0-9a-f]{1,4}:[0-9a-f]{1,4}|(?:(?:25[0-5]|2[0-4]\\d|[01]?\\d\\d?)\\.){3}(?:25[0-5]|2[0-4]\\d|[01]?\\d\\d?))|(?:(?:[0-9a-f]{1,4}:){0,5}[0-9a-f]{1,4})?::[0-9a-f]{1,4}|(?:(?:[0-9a-f]{1,4}:){0,6}[0-9a-f]{1,4})?::)|[Vv][0-9a-f]+\\.[a-z0-9\\-._~!$&'()*+,;=:]+)\\]|(?:(?:25[0-5]|2[0-4]\\d|[01]?\\d\\d?)\\.){3}(?:25[0-5]|2[0-4]\\d|[01]?\\d\\d?)|(?:[a-z0-9\\-._~!$&'()*+,;=]|%[0-9a-f]{2})*)(?::\\d*)?(?:\\/(?:[a-z0-9\\-._~!$&'()*+,;=:@]|%[0-9a-f]{2})*)*|\\/(?:(?:[a-z0-9\\-._~!$&'()*+,;=:@]|%[0-9a-f]{2})+(?:\\/(?:[a-z0-9\\-._~!$&'()*+,;=:@]|%[0-9a-f]{2})*)*)?)?|(?:[a-z][a-z0-9+\\-.]*:)(?:[a-z0-9\\-._~!$&'()*+,;=:@]|%[0-9a-f]{2})+(?:\\/(?:[a-z0-9\\-._~!$&'()*+,;=:@]|%[0-9a-f]{2})*)*|(?:[a-z0-9\\-._~!$&'()*+,;=@]|%[0-9a-f]{2})+(?:\\/(?:[a-z0-9\\-._~!$&'()*+,;=:@]|%[0-9a-f]{2})*)*)(?:\\?(?:[a-z0-9\\-._~!$&'()*+,;=:@/?]|%[0-9a-f]{2})*)?(?:#(?:[a-z0-9\\-._~!$&'()*+,;=:@/?]|%[0-9a-f]{2})*)?$/i.test($input)",
-  "uri-template":          "/^(?:(?:[^\\x00-\\x20\"'<>%\\\\^`{|}]|%[0-9a-f]{2})|\\{[+#./;?&=,!@|]?(?:[a-z0-9_]|%[0-9a-f]{2})+(?::[1-9][0-9]{0,3}|\\*)?(?:,(?:[a-z0-9_]|%[0-9a-f]{2})+(?::[1-9][0-9]{0,3}|\\*)?)*\\})*$/i.test($input)",
+  "uri-template":          "/^(?:(?:[^\\x00-\\x20\"'<>%\\\\^`{|}]|%[0-9a-f]{2})|\\{[+#./;?&=,!@|]?(?:[a-z0-9_]|%[0-9a-f]{2})(?:\\.?(?:[a-z0-9_]|%[0-9a-f]{2}))*(?::[1-9][0-9]{0,3}|\\*)?(?:,(?:[a-z0-9_]|%[0-9a-f]{2})(?:\\.?(?:[a-z0-9_]|%[0-9a-f]{2}))*(?::[1-9][0-9]{0,3}|\\*)?)*\\})*$/i.test($input)",
   "url":                   "/^(?:https?|ftp):\\/\\/(?:[^\\s/?#@]+(?::[^\\s/?#@]*)?@)?(?:(?!(?:10|127)(?:\\.\\d{1,3}){3})(?!(?:169\\.254|192\\.168)(?:\\.\\d{1,3}){2})(?!172\\.(?:1[6-9]|2\\d|3[0-1])(?:\\.\\d{1,3}){2})(?:[1-9]\\d?|1\\d\\d|2[01]\\d|22[0-3])(?:\\.(?:1?\\d{1,2}|2[0-4]\\d|25[0-5])){2}(?:\\.(?:[1-9]\\d?|1\\d\\d|2[0-4]\\d|25[0-4]))|(?=.{1,253}(?::\\d{2,5})?(?:\\/[^\\s]*)?$)(?:[a-z0-9\\u00a1-\\uffff](?:[-a-z0-9\\u00a1-\\uffff]{0,61}[a-z0-9\\u00a1-\\uffff])?\\.)+(?:[a-z\\u00a1-\\uffff](?:[-a-z0-9\\u00a1-\\uffff]{0,61}[a-z0-9\\u00a1-\\uffff])))(?::\\d{2,5})?(?:\\/[^\\s]*)?$/iu.test($input)",
   "date-time":             `(() => { const match = /^([0-9]{4})-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])[Tt]((?:[01][0-9]|2[0-3])):([0-5][0-9]):([0-5][0-9]|60)(?:\.[0-9]+)?(?:[Zz]|([+-])((?:[01][0-9]|2[0-3])):([0-5][0-9]))$/.exec($input); if (match === null) return false; const year = Number(match[1]); const month = Number(match[2]); const day = Number(match[3]); if (day > [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31][month - 1] + (month === 2 && (year % 400 === 0 || (year % 4 === 0 && year % 100 !== 0)) ? 1 : 0)) return false; if (match[6] !== "60") return true; const instant = new Date(0); instant.setUTCFullYear(year, month - 1, day); instant.setUTCHours(Number(match[4]), Number(match[5]), 0, 0); const offset = match[7] === undefined ? 0 : (match[7] === "+" ? 1 : -1) * (Number(match[8]) * 60 + Number(match[9])); instant.setUTCMinutes(instant.getUTCMinutes() - offset); return instant.getUTCHours() === 23 && instant.getUTCMinutes() === 59 && ((instant.getUTCMonth() === 5 && instant.getUTCDate() === 30) || (instant.getUTCMonth() === 11 && instant.getUTCDate() === 31)); })()`,
   "date":                  `(() => { const match = /^([0-9]{4})-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])$/.exec($input); if (match === null) return false; const year = Number(match[1]); const month = Number(match[2]); const day = Number(match[3]); return day <= [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31][month - 1] + (month === 2 && (year % 400 === 0 || (year % 4 === 0 && year % 100 !== 0)) ? 1 : 0); })()`,

package/native/core/factories/JsonMetadataFactory.go

@@ -10,16 +10,41 @@ type jsonMetadataFactoryNamespace struct{}
 
 var JsonMetadataFactory = jsonMetadataFactoryNamespace{}
 
+// JsonMetadataFactory_IProps describes one JSON analysis: the typia method name
+// for diagnostics, the checker and type, and a validator of the metadata.
+//
+// @evidence contracts/common.md#principled-implementation A JSON analysis needs the method name for diagnostic codes, the checker and type to analyze and a validator that adds the call-specific rules to the shared JSON validation.
+// @evidence contracts/common.md#clear-and-simple-design A four-field argument record for Analyze.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A data record.
+// @evidence contracts/common.md#meaningful-documentation The doc states what each field is for.
 type JsonMetadataFactory_IProps struct {
-  Method   string
-  Checker  *nativechecker.Checker
-  Type     *nativechecker.Type
+  // Method identifies the invoking typia API in transformation diagnostics.
+  Method string
+
+  // Checker resolves the Type within the current compiler program.
+  Checker *nativechecker.Checker
+
+  // Type is the root TypeScript type to analyze for JSON representation.
+  Type *nativechecker.Type
+
+  // Validate adds consumer-specific checks after the shared JSON checks.
+  // Nil adds no checks.
   Validate MetadataFactory_Validator
 }
 
+// JsonMetadataFactory_IOutput is the analyzed metadata and the collection of
+// named types it refers to.
+//
+// @evidence contracts/common.md#principled-implementation The analysis returns both the root schema and the collection of named types that it refers to, because the schema refers to components by name.
+// @evidence contracts/common.md#clear-and-simple-design A two-field result record.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A data record.
+// @evidence contracts/common.md#meaningful-documentation The doc states both parts.
 type JsonMetadataFactory_IOutput struct {
+  // Collection owns named components referenced by Metadata.
   Collection *schemametadata.MetadataCollection
-  Metadata   *schemametadata.MetadataSchema
+
+  // Metadata is the validated root schema, sharing its named components.
+  Metadata *schemametadata.MetadataSchema
 }
 
 func (jsonMetadataFactoryNamespace) Analyze(props JsonMetadataFactory_IProps) JsonMetadataFactory_IOutput {

package/native/core/factories/LiteralFactory.go

@@ -24,9 +24,19 @@ var LiteralFactory = literalFactoryNamespace{}
 // most schema builders mean by it, so a real `null`, such as the value of
 // `tags.Example<null>`, needs its own marker to survive into the emitted
 // literal and into encoding/json output (samchon/typia#2403).
+//
+// @evidence contracts/common.md#principled-implementation Object writers skip a Go nil as absent, so a real JSON null, such as the value of `tags.Example<null>`, needs a distinct marker value, and its MarshalJSON writes `null`, which keeps it in the emitted literal and in encoding/json output.
+// @evidence contracts/common.md#clear-and-simple-design An empty struct whose zero value is the marker.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The marker is a value type in the writer's contract and nothing is patched.
+// @evidence contracts/common.md#meaningful-documentation The doc explains why the marker exists and cites the issue.
 type LiteralFactory_Null struct{}
 
 // MarshalJSON writes the marker as JSON `null`.
+//
+// @evidence contracts/common.md#principled-implementation Returns the four bytes `null`, which is the JSON spelling of the marker, and never fails.
+// @evidence contracts/common.md#clear-and-simple-design One method.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A constant result.
+// @evidence contracts/common.md#meaningful-documentation The doc states what it writes.
 func (LiteralFactory_Null) MarshalJSON() ([]byte, error) {
   return []byte("null"), nil
 }
@@ -37,8 +47,16 @@ func (LiteralFactory_Null) MarshalJSON() ([]byte, error) {
 // semantically meaningful, such as `components.schemas` (schema-name keyed),
 // which the legacy TS implementation emitted in discovery order. Keys not
 // present in Values, and values that are nil-like, are skipped.
+//
+// @evidence contracts/common.md#principled-implementation A Go map has no iteration order, so an object whose property order matters, such as component schemas in discovery order, carries its keys in a slice and its values in a map; keys without a value and nil-like values are skipped, which matches how the writer treats absent properties.
+// @evidence contracts/common.md#clear-and-simple-design A two-field record read by the literal writer and by MarshalJSON.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Order is explicit data and not recovered from sorting.
+// @evidence contracts/common.md#meaningful-documentation The doc states the ordering and skipping rules.
 type LiteralFactory_OrderedObject struct {
-  Keys   []string
+  // Keys specifies emission order; missing and nil-like values are omitted.
+  Keys []string
+
+  // Values supplies entries by key; entries absent from Keys are not emitted.
   Values map[string]any
 }
 
@@ -48,6 +66,11 @@ type LiteralFactory_OrderedObject struct {
 // fields. Downstream tools marshal schema metadata containing these objects
 // (e.g. nestia's SDK transform), and the raw {Keys, Values} shape corrupted
 // their output.
+//
+// @evidence contracts/common.md#principled-implementation The object is written as a plain JSON object in key order with the skipped entries omitted, using the standard encoder for keys and values, so tools that marshal schema metadata see the object the printer sees and not the raw record fields.
+// @evidence contracts/common.md#clear-and-simple-design One method that writes braces, keys and values around the standard encoder.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts It uses encoding/json for every key and value and no string splicing of values.
+// @evidence contracts/common.md#meaningful-documentation The doc states the output shape and why the raw record must not be serialized.
 func (obj LiteralFactory_OrderedObject) MarshalJSON() ([]byte, error) {
   buffer := bytes.Buffer{}
   buffer.WriteByte('{')