typia 15.0.0 → 15.1.0

package/native/core/factories/MetadataCommentTagFactory.go

@@ -2,10 +2,12 @@ package factories
 
 import (
   "math"
+  "math/big"
   "strconv"
   "strings"
 
   schemametadata "github.com/samchon/typia/packages/typia/native/core/schemas/metadata"
+  nativeutils "github.com/samchon/typia/packages/typia/native/core/utils"
 )
 
 type metadataCommentTagFactoryNamespace struct{}
@@ -51,6 +53,22 @@ func (metadataCommentTagFactoryNamespace) Analyze(props struct {
       continue
     }
     for key, value := range tagger {
+      // An empty arm names a target the tag's value cannot be stated for; see
+      // metadataCommentTagFactory_bigint. It is an error only where that target
+      // occurs, and the other arms still apply to theirs.
+      if value != nil && len(value) == 0 {
+        for _, atomic := range props.Metadata.Atomics {
+          if atomic.Type == key {
+            text := ""
+            if len(tag.Text) != 0 {
+              text = tag.Text[0].Text
+            }
+            report(key + " value " + strings.TrimSpace(text) + " is not an int64 integer that a number represents exactly")
+            break
+          }
+        }
+        continue
+      }
       filtered := []schemametadata.IMetadataTypeTag{}
       for _, elem := range value {
         filtered = append(filtered, elem)
@@ -230,37 +248,37 @@ var metadataCommentTagFactory_PARSER = map[string]metadataCommentTagFactory_pars
     Report func(msg string) any
     Value  string
   }) metadataCommentTagFactory_TagRecord {
-    value := metadataCommentTagFactory_parse_integer(struct {
+    value := metadataCommentTagFactory_value(metadataCommentTagFactory_parse_integer(struct {
       Report   func(msg string) any
       Unsigned bool
       Value    string
-    }{Report: props.Report, Value: props.Value, Unsigned: true})
+    }{Report: props.Report, Value: props.Value, Unsigned: true}))
     return metadataCommentTagFactory_TagRecord{"array": {
-      {Name: "MinItems<" + props.Value + ">", Target: "array", Kind: "minItems", Value: value, Validate: props.Value + " <= $input.length", Exclusive: metadataCommentTagFactory_exclusive("minItems"), Schema: map[string]any{"minItems": value}},
-      {Name: "MaxItems<" + props.Value + ">", Target: "array", Kind: "maxItems", Value: value, Validate: "$input.length <= " + props.Value, Exclusive: metadataCommentTagFactory_exclusive("maxItems"), Schema: map[string]any{"maxItems": value}},
+      {Name: "MinItems<" + props.Value + ">", Target: "array", Kind: "minItems", Value: value, Validate: metadataCommentTagFactory_splice(props.Value) + " <= $input.length", Exclusive: metadataCommentTagFactory_exclusive("minItems"), Schema: map[string]any{"minItems": value}},
+      {Name: "MaxItems<" + props.Value + ">", Target: "array", Kind: "maxItems", Value: value, Validate: "$input.length <= " + metadataCommentTagFactory_splice(props.Value), Exclusive: metadataCommentTagFactory_exclusive("maxItems"), Schema: map[string]any{"maxItems": value}},
     }}
   },
   "minItems": func(props struct {
     Report func(msg string) any
     Value  string
   }) metadataCommentTagFactory_TagRecord {
-    value := metadataCommentTagFactory_parse_integer(struct {
+    value := metadataCommentTagFactory_value(metadataCommentTagFactory_parse_integer(struct {
       Report   func(msg string) any
       Unsigned bool
       Value    string
-    }{Report: props.Report, Value: props.Value, Unsigned: true})
-    return metadataCommentTagFactory_TagRecord{"array": {{Name: "MinItems<" + props.Value + ">", Target: "array", Kind: "minItems", Value: value, Validate: props.Value + " <= $input.length", Exclusive: metadataCommentTagFactory_exclusive("minItems"), Schema: map[string]any{"minItems": value}}}}
+    }{Report: props.Report, Value: props.Value, Unsigned: true}))
+    return metadataCommentTagFactory_TagRecord{"array": {{Name: "MinItems<" + props.Value + ">", Target: "array", Kind: "minItems", Value: value, Validate: metadataCommentTagFactory_splice(props.Value) + " <= $input.length", Exclusive: metadataCommentTagFactory_exclusive("minItems"), Schema: map[string]any{"minItems": value}}}}
   },
   "maxItems": func(props struct {
     Report func(msg string) any
     Value  string
   }) metadataCommentTagFactory_TagRecord {
-    value := metadataCommentTagFactory_parse_integer(struct {
+    value := metadataCommentTagFactory_value(metadataCommentTagFactory_parse_integer(struct {
       Report   func(msg string) any
       Unsigned bool
       Value    string
-    }{Report: props.Report, Value: props.Value, Unsigned: true})
-    return metadataCommentTagFactory_TagRecord{"array": {{Name: "MaxItems<" + props.Value + ">", Target: "array", Kind: "maxItems", Value: value, Validate: "$input.length <= " + props.Value, Exclusive: metadataCommentTagFactory_exclusive("maxItems"), Schema: map[string]any{"maxItems": value}}}}
+    }{Report: props.Report, Value: props.Value, Unsigned: true}))
+    return metadataCommentTagFactory_TagRecord{"array": {{Name: "MaxItems<" + props.Value + ">", Target: "array", Kind: "maxItems", Value: value, Validate: "$input.length <= " + metadataCommentTagFactory_splice(props.Value), Exclusive: metadataCommentTagFactory_exclusive("maxItems"), Schema: map[string]any{"maxItems": value}}}}
   },
   "uniqueItems": func(props struct {
     Report func(msg string) any
@@ -273,25 +291,25 @@ var metadataCommentTagFactory_PARSER = map[string]metadataCommentTagFactory_pars
     Report func(msg string) any
     Value  string
   }) metadataCommentTagFactory_TagRecord {
-    return metadataCommentTagFactory_numeric(props, "Minimum", "minimum", props.Value+" <= $input", props.Value+" <= $input")
+    return metadataCommentTagFactory_numeric(props, "Minimum", "minimum", metadataCommentTagFactory_splice(props.Value)+" <= $input", metadataCommentTagFactory_splice_integer(props.Value)+" <= $input")
   },
   "maximum": func(props struct {
     Report func(msg string) any
     Value  string
   }) metadataCommentTagFactory_TagRecord {
-    return metadataCommentTagFactory_numeric(props, "Maximum", "maximum", "$input <= "+props.Value, "$input <= "+props.Value)
+    return metadataCommentTagFactory_numeric(props, "Maximum", "maximum", "$input <= "+metadataCommentTagFactory_splice(props.Value), "$input <= "+metadataCommentTagFactory_splice_integer(props.Value))
   },
   "exclusiveMinimum": func(props struct {
     Report func(msg string) any
     Value  string
   }) metadataCommentTagFactory_TagRecord {
-    return metadataCommentTagFactory_numeric(props, "ExclusiveMinimum", "exclusiveMinimum", props.Value+" < $input", props.Value+" < $input")
+    return metadataCommentTagFactory_numeric(props, "ExclusiveMinimum", "exclusiveMinimum", metadataCommentTagFactory_splice(props.Value)+" < $input", metadataCommentTagFactory_splice_integer(props.Value)+" < $input")
   },
   "exclusiveMaximum": func(props struct {
     Report func(msg string) any
     Value  string
   }) metadataCommentTagFactory_TagRecord {
-    return metadataCommentTagFactory_numeric(props, "ExclusiveMaximum", "exclusiveMaximum", "$input < "+props.Value, "$input < "+props.Value)
+    return metadataCommentTagFactory_numeric(props, "ExclusiveMaximum", "exclusiveMaximum", "$input < "+metadataCommentTagFactory_splice(props.Value), "$input < "+metadataCommentTagFactory_splice_integer(props.Value))
   },
   "multipleOf": func(props struct {
     Report func(msg string) any
@@ -303,7 +321,7 @@ var metadataCommentTagFactory_PARSER = map[string]metadataCommentTagFactory_pars
     // answers a different question than the `multipleOf` keyword this tag emits.
     // The bigint arm needs no helper: a bigint remainder is already exact.
     // `_isMultipleOf` first shipped in 13.1.19; see the doc comment above.
-    return metadataCommentTagFactory_numeric(props, "MultipleOf", "multipleOf", "$importInternal(\"_isMultipleOf\")($input, "+props.Value+")", "$input % "+props.Value+"n === 0n")
+    return metadataCommentTagFactory_numeric(props, "MultipleOf", "multipleOf", "$importInternal(\"_isMultipleOf\")($input, "+metadataCommentTagFactory_splice(props.Value)+")", "$input % "+metadataCommentTagFactory_splice_integer(props.Value)+"n === 0n")
   },
   "format": func(props struct {
     Report func(msg string) any
@@ -335,8 +353,8 @@ var metadataCommentTagFactory_PARSER = map[string]metadataCommentTagFactory_pars
     // The comparison helpers keep that code-point walk but stop when the
     // declared boundary already determines the answer.
     return metadataCommentTagFactory_TagRecord{"string": {
-      {Name: "MinLength<" + props.Value + ">", Target: "string", Kind: "minLength", Value: value, Validate: "$importInternal(\"_stringLengthGte\")($input, " + props.Value + ")", Exclusive: metadataCommentTagFactory_exclusive("minLength"), Schema: map[string]any{"minLength": value}},
-      {Name: "MaxLength<" + props.Value + ">", Target: "string", Kind: "maxLength", Value: value, Validate: "$importInternal(\"_stringLengthLte\")($input, " + props.Value + ")", Exclusive: metadataCommentTagFactory_exclusive("maxLength"), Schema: map[string]any{"maxLength": value}},
+      {Name: "MinLength<" + props.Value + ">", Target: "string", Kind: "minLength", Value: value, Validate: "$importInternal(\"_stringLengthGte\")($input, " + metadataCommentTagFactory_splice(props.Value) + ")", Exclusive: metadataCommentTagFactory_exclusive("minLength"), Schema: map[string]any{"minLength": value}},
+      {Name: "MaxLength<" + props.Value + ">", Target: "string", Kind: "maxLength", Value: value, Validate: "$importInternal(\"_stringLengthLte\")($input, " + metadataCommentTagFactory_splice(props.Value) + ")", Exclusive: metadataCommentTagFactory_exclusive("maxLength"), Schema: map[string]any{"maxLength": value}},
     }}
   },
   "minLength": func(props struct {
@@ -344,14 +362,14 @@ var metadataCommentTagFactory_PARSER = map[string]metadataCommentTagFactory_pars
     Value  string
   }) metadataCommentTagFactory_TagRecord {
     value := metadataCommentTagFactory_parse_number(props)
-    return metadataCommentTagFactory_TagRecord{"string": {{Name: "MinLength<" + props.Value + ">", Target: "string", Kind: "minLength", Value: value, Validate: "$importInternal(\"_stringLengthGte\")($input, " + props.Value + ")", Exclusive: metadataCommentTagFactory_exclusive("minLength"), Schema: map[string]any{"minLength": value}}}}
+    return metadataCommentTagFactory_TagRecord{"string": {{Name: "MinLength<" + props.Value + ">", Target: "string", Kind: "minLength", Value: value, Validate: "$importInternal(\"_stringLengthGte\")($input, " + metadataCommentTagFactory_splice(props.Value) + ")", Exclusive: metadataCommentTagFactory_exclusive("minLength"), Schema: map[string]any{"minLength": value}}}}
   },
   "maxLength": func(props struct {
     Report func(msg string) any
     Value  string
   }) metadataCommentTagFactory_TagRecord {
     value := metadataCommentTagFactory_parse_number(props)
-    return metadataCommentTagFactory_TagRecord{"string": {{Name: "MaxLength<" + props.Value + ">", Target: "string", Kind: "maxLength", Value: value, Validate: "$importInternal(\"_stringLengthLte\")($input, " + props.Value + ")", Exclusive: metadataCommentTagFactory_exclusive("maxLength"), Schema: map[string]any{"maxLength": value}}}}
+    return metadataCommentTagFactory_TagRecord{"string": {{Name: "MaxLength<" + props.Value + ">", Target: "string", Kind: "maxLength", Value: value, Validate: "$importInternal(\"_stringLengthLte\")($input, " + metadataCommentTagFactory_splice(props.Value) + ")", Exclusive: metadataCommentTagFactory_exclusive("maxLength"), Schema: map[string]any{"maxLength": value}}}}
   },
 }
 
@@ -480,31 +498,161 @@ func metadataCommentTagFactory_numeric(props struct {
   Value  string
 }, name string, kind string, numberValidate string, bigintValidate string) metadataCommentTagFactory_TagRecord {
   number := metadataCommentTagFactory_parse_number(props)
-  integer := metadataCommentTagFactory_parse_integer(struct {
-    Report   func(msg string) any
-    Unsigned bool
-    Value    string
-  }{Report: func(string) any { return nil }, Value: props.Value, Unsigned: false})
+  if number == nil {
+    // Reported as an invalid or non-finite number already; a record would only
+    // add "requires number type" on a bigint property, which is not the fault.
+    return metadataCommentTagFactory_TagRecord{}
+  }
   exclusive := metadataCommentTagFactory_exclusive(kind)
   record := metadataCommentTagFactory_TagRecord{
     "number": {{Name: name + "<" + props.Value + ">", Target: "number", Kind: kind, Value: number, Validate: numberValidate, Exclusive: exclusive, Schema: map[string]any{kind: number}}},
   }
-  if integer != nil {
-    record["bigint"] = []schemametadata.IMetadataTypeTag{{Name: name + "<" + props.Value + "n>", Target: "bigint", Kind: kind, Value: *integer, Validate: bigintValidate, Exclusive: exclusive, Schema: map[string]any{kind: number}}}
+  integer, numeric, ok := metadataCommentTagFactory_bigint(props.Value)
+  if ok {
+    record["bigint"] = []schemametadata.IMetadataTypeTag{{Name: name + "<" + props.Value + "n>", Target: "bigint", Kind: kind, Value: integer, Validate: bigintValidate, Exclusive: exclusive, Schema: map[string]any{kind: number}}}
+  } else if numeric {
+    // An empty arm: the value bounds a bigint, but not with any value this tag
+    // can state. `Analyze` reports it where a bigint occurs, so the bigint part
+    // of a `number | bigint` property is never left unconstrained silently.
+    record["bigint"] = []schemametadata.IMetadataTypeTag{}
   }
   return record
 }
 
+// metadataCommentTagFactory_bigint reads a numeric tag's value for its bigint
+// arm.
+//
+// Consumers of that arm hold the value as a double: the bound validators splice
+// a number literal, and the schema `random` draws from is numeric. The written
+// integer survives them only when a double represents it exactly, so that is
+// what the arm admits, within the int64 range its value is carried in
+// (samchon/typia#2352). Reading any integer through a double instead enforced
+// `@minimum 9007199254740993` as 9007199254740992, and let `random` generate
+// values the exact `@multipleOf` check rejects (samchon/typia#2457).
+//
+// numeric reports whether the text writes a finite number at all. One that is
+// no such integer -- `1.5`, `5.0000000000000001`, `9007199254740993`, or
+// `1e-1000001` -- is a bigint bound the tag cannot state, while text that is no
+// finite number has already been reported by the number arm.
+func metadataCommentTagFactory_bigint(text string) (value int64, numeric bool, ok bool) {
+  if reading := nativeutils.NumberUtil.Read(text); reading.Numeric == false || reading.Finite == false {
+    return 0, false, false
+  }
+  integer, exact := metadataCommentTagFactory_integer(text)
+  if exact == false || integer.IsInt64() == false {
+    return 0, true, false
+  }
+  if _, accuracy := new(big.Float).SetInt(integer).Float64(); accuracy != big.Exact {
+    return 0, true, false
+  }
+  return integer.Int64(), true, true
+}
+
+// metadataCommentTagFactory_integer is the integer a finite numeric text
+// writes exactly, if it writes one whose double lies within the int64 range. A
+// few integers just below -2^63 round to it and pass; the bigint record checks
+// the integer itself.
+//
+// Its double, which `NumberUtil.Read` rounds correctly, settles most texts
+// without expanding them. A non-integer double comes only from a non-integer
+// text, and a zero from a text with a non-zero digit is the underflow of a
+// non-integer. A double at 2^63 or above, or below -2^63, is refused too: the
+// int64 texts that round up to 2^63 (from 9223372036854775296) are no doubles,
+// so no bigint record could hold them anyway. `big.Rat` expands only what
+// remains, so a short text such as `@minimum 1e-1000000` costs nothing, on any
+// target.
+func metadataCommentTagFactory_integer(text string) (*big.Int, bool) {
+  reading := nativeutils.NumberUtil.Read(text)
+  if reading.Numeric == false ||
+    reading.Finite == false ||
+    reading.Value != math.Trunc(reading.Value) ||
+    reading.Value < metadataCommentTagFactory_INT64_MINIMUM ||
+    reading.Value >= metadataCommentTagFactory_INT64_EXCLUSIVE_MAXIMUM {
+    return nil, false
+  }
+  if reading.Value == 0 {
+    // A zero writes zero only when no digit before its exponent is non-zero;
+    // otherwise it underflowed. A radix zero has no `e`, being all zeros.
+    mantissa := text
+    if index := strings.IndexAny(text, "eE"); index != -1 {
+      mantissa = text[:index]
+    }
+    if strings.ContainsAny(mantissa, "123456789") {
+      return nil, false
+    }
+    return big.NewInt(0), true
+  }
+  rational, ok := nativeutils.NumberUtil.Rational(text)
+  if ok == false || rational.IsInt() == false {
+    return nil, false
+  }
+  return rational.Num(), true
+}
+
+// metadataCommentTagFactory_value unwraps a parsed count into the record's
+// value and schema. Storing the pointer itself let every consumer that formats
+// a value print an address: strict LLM schemas described `@minItems 2` as
+// `@minItems 0xc000012345`.
+func metadataCommentTagFactory_value(value *int64) any {
+  if value == nil {
+    return nil
+  }
+  return *value
+}
+
 func metadataCommentTagFactory_parse_number(props struct {
   Report func(msg string) any
   Value  string
 }) any {
-  parsed, err := strconv.ParseFloat(props.Value, 64)
-  if err != nil || math.IsNaN(parsed) {
+  reading := nativeutils.NumberUtil.Read(props.Value)
+  if reading.Numeric == false {
     props.Report("invalid number")
     return nil
   }
-  return parsed
+  // A JSON Schema keyword such as `minimum` must be a JSON number, and JSON has
+  // no spelling for an infinity (samchon/typia#2452).
+  if reading.Finite == false {
+    props.Report("non-finite number")
+    return nil
+  }
+  return reading.Value
+}
+
+// metadataCommentTagFactory_splice respells a numeric tag value for the
+// validator the record splices it into (`16 <= $input`, `$input % 1000n`).
+//
+// The spliced text has to be JavaScript for the value the tag was read as, in
+// both the number and the bigint target. The source spelling need not be:
+// `0x10` happens to be, but `1e3`, `1.0`, `+5`, and `007` are integers whose
+// bigint splice (`1e3n`, `1.0n`, `+5n`, `007n`) is no valid BigInt expression
+// (samchon/typia#2442). An integer spelling keeps its digits as written, so the
+// splice never rounds where the source did not: `Number()` would read
+// `9007199254740993` as ...992, while the bigint `@multipleOf` check appends
+// `n` to the digits and compares exactly.
+// Text that does not read as a finite number is passed through; the parser
+// reports it and nothing is emitted.
+func metadataCommentTagFactory_splice(value string) string {
+  if integer, ok := nativeutils.NumberUtil.Integer(value); ok {
+    return integer.String()
+  }
+  if reading := nativeutils.NumberUtil.Read(value); reading.Numeric && reading.Finite {
+    return nativeutils.NumberUtil.String(reading.Value)
+  }
+  return value
+}
+
+// metadataCommentTagFactory_splice_integer respells a tag value for a bigint
+// validator: the exact digits of the integer the text writes, whatever its
+// spelling, for every value a bigint record holds. `1.152921504606846976e18`
+// writes 2^60, while its double spells 1152921504606847000, which spliced
+// before an `n` would check a different integer (samchon/typia#2457). Text
+// that writes no integer has no bigint record, and falls back to the number
+// splice.
+func metadataCommentTagFactory_splice_integer(value string) string {
+  if integer, ok := metadataCommentTagFactory_integer(value); ok {
+    return integer.String()
+  }
+  return metadataCommentTagFactory_splice(value)
 }
 
 func metadataCommentTagFactory_parse_integer(props struct {

package/native/core/factories/MetadataFactory.go

@@ -49,27 +49,81 @@ func init() {
   }
 }
 
+// MetadataFactory_Validator checks one metadata node during analysis and returns
+// the reasons it is unsupported, or none.
+//
+// @evidence contracts/common.md#principled-implementation A validator receives the node, its location and the top schema and returns reasons as strings, so it can be written without knowing the analysis internals and an empty result means the node is acceptable.
+// @evidence contracts/common.md#clear-and-simple-design A function type used by the options and the JSON factory.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A declaration only.
+// @evidence contracts/common.md#meaningful-documentation The doc states the inputs and the empty-result meaning.
 type MetadataFactory_Validator = func(props struct {
   Metadata *schemametadata.MetadataSchema
   Explore  MetadataFactory_IExplore
   Top      *schemametadata.MetadataSchema
 }) []string
 
+// MetadataFactory_IOptions is the option record of the metadata analysis.
+//
+// @evidence contracts/common.md#principled-implementation The alias names the option record that the metadata package owns.
+// @evidence contracts/common.md#clear-and-simple-design A type alias to the metadata package's record.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A declaration only.
+// @evidence contracts/common.md#meaningful-documentation The doc states what the record configures.
 type MetadataFactory_IOptions = nativemetadata.MetadataFactory_IOptions
+
+// MetadataFactory_IExplore locates the node that is being analyzed.
+//
+// @evidence contracts/common.md#principled-implementation The alias names the location record that the metadata package owns.
+// @evidence contracts/common.md#clear-and-simple-design A type alias to the metadata package's record.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A declaration only.
+// @evidence contracts/common.md#meaningful-documentation The doc states what the record locates.
 type MetadataFactory_IExplore = nativemetadata.MetadataFactory_IExplore
+
+// MetadataFactory_IError is one analysis failure with its location and reasons.
+//
+// @evidence contracts/common.md#principled-implementation The alias names the error record that the metadata package owns.
+// @evidence contracts/common.md#clear-and-simple-design A type alias to the metadata package's record.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A declaration only.
+// @evidence contracts/common.md#meaningful-documentation The doc states what the record holds.
 type MetadataFactory_IError = nativemetadata.MetadataFactory_IError
 
+// MetadataFactory_IProps is the input of an analysis: checker, options, the
+// collection to fill and the type.
+//
+// @evidence contracts/common.md#principled-implementation An analysis needs the checker, the options, the collection that receives named types and the type, which is all the shared analyzer reads.
+// @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 lists the inputs.
 type MetadataFactory_IProps struct {
-  Checker    *nativechecker.Checker
-  Options    MetadataFactory_IOptions
+  // Checker resolves Type and its reachable compiler types.
+  Checker *nativechecker.Checker
+
+  // Options selects the shape analysis and optional validation hooks.
+  Options MetadataFactory_IOptions
+
+  // Components is the per-analysis registry filled with shared named types.
   Components *schemametadata.MetadataCollection
-  Type       *nativechecker.Type
+
+  // Type is the root type to explore.
+  Type *nativechecker.Type
 }
 
+// MetadataFactory_ValidationPipe is the analysis result: Success, the metadata
+// on success or the errors collected on failure. Analyze leaves Data nil on
+// failure and Errors empty on success.
+//
+// @evidence contracts/common.md#principled-implementation The result carries a success flag, the schema and the errors, so a caller can report every error and not only the first.
+// @evidence contracts/common.md#clear-and-simple-design A three-field result record.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A data record.
+// @evidence contracts/common.md#meaningful-documentation The doc states the three parts.
 type MetadataFactory_ValidationPipe struct {
+  // Success selects whether Data or Errors carries the analysis result.
   Success bool
-  Data    *schemametadata.MetadataSchema
-  Errors  []MetadataFactory_IError
+
+  // Data is the root schema on success; Analyze leaves it nil on failure.
+  Data *schemametadata.MetadataSchema
+
+  // Errors contains all collected analysis/validation failures on failure.
+  Errors []MetadataFactory_IError
 }
 
 func (metadataFactoryNamespace) Analyze(props MetadataFactory_IProps) MetadataFactory_ValidationPipe {

package/native/core/factories/ProtobufFactory.go

@@ -16,16 +16,29 @@ type protobufFactoryNamespace struct{}
 
 var ProtobufFactory = protobufFactoryNamespace{}
 
+// ProtobufFactory_IProps is the input of a protobuf metadata analysis. Method is
+// the whole typia API name as it appears in diagnostics.
+//
+// @evidence contracts/common.md#principled-implementation The analysis needs the checker, the collection and the type, and the method is the complete API name because it becomes the diagnostic code verbatim, which the field comment explains.
+// @evidence contracts/common.md#clear-and-simple-design A four-field argument record for Metadata.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A data record.
+// @evidence contracts/common.md#meaningful-documentation The doc and the field comment state the full-name rule.
 type ProtobufFactory_IProps struct {
   // Method is the fully qualified typia API the call site invoked, exactly as
   // it must appear in the diagnostic code (`typia.protobuf.encode`). It is the
   // sole source of that code: composing the code here from a shorter spelling
   // let the encode and decode programmers, which already pass the whole call
   // accessor, report `typia.protobuf.typia.protobuf.encode`.
-  Method     string
-  Checker    *shimchecker.Checker
+  Method string
+
+  // Checker resolves the Type in the current compiler program.
+  Checker *shimchecker.Checker
+
+  // Components receives named analysis entries and protobuf property layouts.
   Components *schemametadata.MetadataCollection
-  Type       *shimchecker.Type
+
+  // Type is the root type, required to be a sole static object by validation.
+  Type *shimchecker.Type
 }
 
 func (protobufFactoryNamespace) Metadata(props ProtobufFactory_IProps) *schemametadata.MetadataSchema {
@@ -281,7 +294,7 @@ func protobufFactory_emplaceBigint(output map[string]nativeprotobuf.IProtobufPro
         break
       }
     }
-    output[init] = &nativeprotobuf.IProtobufPropertyType_IBigint{
+    output[value] = &nativeprotobuf.IProtobufPropertyType_IBigint{
       IProtobufSchema_IBigint: nativeprotobuf.IProtobufSchema_IBigint{Type: "bigint", Name: value},
       Index:                   protobufFactory_getSequence(row),
     }

package/native/core/factories/StatementFactory.go

@@ -10,20 +10,53 @@ type statementFactoryNamespace struct{}
 
 var StatementFactory = statementFactoryNamespace{}
 
+// StatementFactory_MutProps names a mutable variable with an optional type and
+// initializer.
+//
+// @evidence contracts/common.md#principled-implementation A mutable variable declaration needs a name and optionally a type and an initializer, and with neither it is typed any.
+// @evidence contracts/common.md#clear-and-simple-design A three-field argument record for Mut.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A data record.
+// @evidence contracts/common.md#meaningful-documentation The doc states the optional parts.
 type StatementFactory_MutProps struct {
-  Name        string
-  Type        *shimast.TypeNode
+  // Name is the identifier bound by the generated let statement.
+  Name string
+
+  // Type is optional; without it or an initializer the builder inserts any.
+  Type *shimast.TypeNode
+
+  // Initializer is optional and otherwise supplies inference for an omitted Type.
   Initializer *shimast.Expression
 }
 
+// StatementFactory_ConstantProps names a constant with an optional type and its
+// value.
+//
+// @evidence contracts/common.md#principled-implementation A constant declaration needs a name, an optional type and the value.
+// @evidence contracts/common.md#clear-and-simple-design A three-field argument record for Constant.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A data record.
+// @evidence contracts/common.md#meaningful-documentation The doc states the fields.
 type StatementFactory_ConstantProps struct {
-  Name  string
-  Type  *shimast.TypeNode
+  // Name is the identifier bound by the generated const statement.
+  Name string
+
+  // Type is omitted to let the compiler infer it from Value.
+  Type *shimast.TypeNode
+
+  // Value supplies the initializer required by ordinary executable const use.
   Value *shimast.Expression
 }
 
+// StatementFactory_EntryProps names the two bindings of the `[key, value]` array pattern of an entry declaration.
+//
+// @evidence contracts/common.md#principled-implementation An entry declaration destructures a `[key, value]` pair, so the two binding names are the whole argument.
+// @evidence contracts/common.md#clear-and-simple-design A two-field argument record for Entry.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A data record.
+// @evidence contracts/common.md#meaningful-documentation The doc states the two bindings.
 type StatementFactory_EntryProps struct {
-  Key   string
+  // Key names the first binding of the array pattern.
+  Key string
+
+  // Value names the second binding of the array pattern.
   Value string
 }
 

package/native/core/factories/TemplateFactory.go

@@ -12,8 +12,18 @@ type templateFactoryNamespace struct{}
 
 var TemplateFactory = templateFactoryNamespace{}
 
+// TemplateFactory_IIterator is the running state of a template build: the literal
+// text gathered for the current literal segment and the next expression index.
+//
+// @evidence contracts/common.md#principled-implementation Generate alternates literal segments and expressions; gather replaces Value with the current consecutive string-literal segment and advances Index to its following expression or the end.
+// @evidence contracts/common.md#clear-and-simple-design A two-field record shared by the generate and gather functions.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A data record.
+// @evidence contracts/common.md#meaningful-documentation The doc states the two fields.
 type TemplateFactory_IIterator struct {
+  // Value is the current consecutive string-literal segment, replaced by gather.
   Value string
+
+  // Index is the next unconsumed expression position, or the input length.
   Index int
 }
 

package/native/core/factories/TypeFactory.go

@@ -13,16 +13,44 @@ type typeFactoryNamespace struct{}
 
 var TypeFactory = typeFactoryNamespace{}
 
+// TypeFactory_GetReturnTypeOfClassMethodProps names a method of a class type
+// whose return type is wanted.
+//
+// @evidence contracts/common.md#principled-implementation Finding a method's return type needs the checker, the class type and the method name.
+// @evidence contracts/common.md#clear-and-simple-design A three-field argument record.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A data record.
+// @evidence contracts/common.md#meaningful-documentation The doc states what it names.
 type TypeFactory_GetReturnTypeOfClassMethodProps struct {
-  Checker  *shimchecker.Checker
-  Class    *shimchecker.Type
+  // Checker resolves the property and its first call signature; nil yields nil.
+  Checker *shimchecker.Checker
+
+  // Class is the type containing the named property; nil yields nil.
+  Class *shimchecker.Type
+
+  // Function names the property whose first call signature supplies the return
+  // type. Missing properties or call signatures yield nil.
   Function string
 }
 
+// TypeFactory_GetFullNameProps selects the type or symbol whose full name is
+// wanted. A non-nil Type and Checker are required even with an explicit Symbol.
+// AliasTypeArguments is retained for compatibility and is currently not read.
+//
+// @evidence contracts/common.md#principled-implementation The checker and type provide the name fallback and reference type arguments; an explicit symbol overrides the type's symbol. AliasTypeArguments preserves the input shape but the current builder does not consult it.
+// @evidence contracts/common.md#clear-and-simple-design A four-field argument record.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A data record.
+// @evidence contracts/common.md#meaningful-documentation The doc states the selection and the switch.
 type TypeFactory_GetFullNameProps struct {
-  Checker            *shimchecker.Checker
-  Type               *shimchecker.Type
-  Symbol             *shimast.Symbol
+  // Checker renders unnamed types and resolves reference type arguments.
+  Checker *shimchecker.Checker
+
+  // Type supplies the type to name; nil causes the empty result.
+  Type *shimchecker.Type
+
+  // Symbol overrides Type.Symbol when non-nil; it does not replace Type.
+  Symbol *shimast.Symbol
+
+  // AliasTypeArguments is retained but currently has no effect on naming.
   AliasTypeArguments *bool
 }