typia 13.2.0 → 14.0.0

package/native/core/factories/MetadataCommentTagFactory.go

@@ -196,6 +196,34 @@ func (metadataCommentTagFactoryNamespace) Get(props struct {
   return output
 }
 
+// metadataCommentTagFactory_PARSER maps a JSDoc tag name to the tag records it
+// produces. Each record's `Validate` is the runtime check the transform splices
+// into the emitted validator, and it must spell the same check as the matching
+// declaration in `packages/interface/src/tags` -- the two are one constraint.
+//
+// # WHEN A RECORD MAY NAME A RUNTIME HELPER
+//
+// A `Validate` may write `$importInternal("x")`, here or in the matching
+// declaration, only under the rule below.
+//
+// That call makes the emitted validator `require("typia/lib/internal/_x")`. The
+// type-tag half of each constraint is declared in `@typia/interface`, which
+// `typia` depends on through a caret range, and a caret only floats upward. So
+// inside one major an older `typia` installs a newer `@typia/interface` and
+// emits an import its own runtime never published; that is #2330, and it is why
+// #2336 and #2339 reverted these very templates to inline expressions.
+//
+// The rule: a template may name only a helper that every `typia` inside the
+// caret range already ships. `isTypeInt8` and its siblings satisfy it --
+// `@typia/interface` 13.0.0 named them and `typia` 13.0.0 shipped them. The
+// four this file and `Type.ts` now name do not: `_stringLength`, `_isMultipleOf`
+// (both first published in 13.1.19), `_isTypeInt64Bigint`, and
+// `_isTypeUint64Bigint` (13.1.19). They are safe only because the release that
+// carries them is a major, where the caret cannot reach a `typia` that predates
+// them. A minor or patch release of this tree reopens #2330.
+//
+// Nothing here can enforce that; the release version is the maintainer's, and a
+// campaign pull request never assigns one. This comment is the record.
 var metadataCommentTagFactory_PARSER = map[string]metadataCommentTagFactory_parser{
   "items": func(props struct {
     Report func(msg string) any
@@ -268,6 +296,12 @@ var metadataCommentTagFactory_PARSER = map[string]metadataCommentTagFactory_pars
     Report func(msg string) any
     Value  string
   }) metadataCommentTagFactory_TagRecord {
+    // `@multipleOf` and `MultipleOf<N>` are two spellings of one constraint, so
+    // the number arm divides exact decimals through the same helper the type tag
+    // names. `%` would divide the binary doubles that are actually stored, which
+    // 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")
   },
   "format": func(props struct {
@@ -291,6 +325,13 @@ var metadataCommentTagFactory_PARSER = map[string]metadataCommentTagFactory_pars
     Value  string
   }) metadataCommentTagFactory_TagRecord {
     value := metadataCommentTagFactory_parse_number(props)
+    // `@length`, `@minLength`, and `@maxLength` measure through the same helper
+    // `MinLength<N>` and `MaxLength<N>` name, because the JSDoc spelling and the
+    // type-tag spelling of one constraint must never mean different things.
+    // `$input.length` counts UTF-16 code units, while the `minLength` and
+    // `maxLength` keywords these tags emit count characters, so one astral
+    // character would measure 2 against a schema that measures 1.
+    // `_stringLength` first shipped in 13.1.19; see the doc comment above.
     return metadataCommentTagFactory_TagRecord{"string": {
       {Name: "MinLength<" + props.Value + ">", Target: "string", Kind: "minLength", Value: value, Validate: props.Value + " <= $importInternal(\"_stringLength\")($input)", Exclusive: metadataCommentTagFactory_exclusive("minLength"), Schema: map[string]any{"minLength": value}},
       {Name: "MaxLength<" + props.Value + ">", Target: "string", Kind: "maxLength", Value: value, Validate: "$importInternal(\"_stringLength\")($input) <= " + props.Value, Exclusive: metadataCommentTagFactory_exclusive("maxLength"), Schema: map[string]any{"maxLength": value}},
@@ -407,10 +448,20 @@ func metadataCommentTagFactory_parse_type(props struct {
     "number": {{Name: "Type<" + strconv.Quote(value) + ">", Target: "number", Kind: "type", Value: value, Validate: validate, Exclusive: metadataCommentTagFactory_exclusive("type"), Schema: numberSchema}},
   }
   if value == "int64" || value == "uint64" {
-    // The bigint form used to emit `true` for int64 and a lower bound only for
-    // uint64, so `bigint & Type<"int64">` -- the spelling the documentation
-    // recommends -- certified any magnitude at all. Both now delegate to the
-    // helper that holds the exact inclusive bound a bigint can represent.
+    // `@type int64` and `bigint & Type<"int64">` are two spellings of one
+    // constraint, so both delegate to the helper that holds the exact inclusive
+    // bound. The bigint form used to emit `true` for int64 and a lower bound
+    // only for uint64, which certified any magnitude at all -- and
+    // `typia.protobuf.encode` then truncated the value to 64 bits, so a
+    // certified value came back different.
+    //
+    // The bound has to live in a helper rather than an inline literal here
+    // because it is only exact as a string: `BigInt(9223372036854775807)` rounds
+    // its `number` literal to 2**63 before BigInt ever parses it.
+    //
+    // See the `metadataCommentTagFactory_PARSER` doc comment: naming a helper
+    // here is safe only under a major bump, and `_isTypeInt64Bigint` /
+    // `_isTypeUint64Bigint` first shipped in 13.1.19.
     bigintValidate := "$importInternal(\"isTypeUint64Bigint\")($input)"
     if value == "int64" {
       bigintValidate = "$importInternal(\"isTypeInt64Bigint\")($input)"
@@ -437,7 +488,7 @@ func metadataCommentTagFactory_numeric(props struct {
     "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: int64(*integer), Validate: bigintValidate, Exclusive: exclusive, Schema: map[string]any{kind: number}}}
+    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}}}
   }
   return record
 }
@@ -458,7 +509,7 @@ func metadataCommentTagFactory_parse_integer(props struct {
   Report   func(msg string) any
   Unsigned bool
   Value    string
-}) *int {
+}) *int64 {
   parsedAny := metadataCommentTagFactory_parse_number(struct {
     Report func(msg string) any
     Value  string
@@ -475,10 +526,43 @@ func metadataCommentTagFactory_parse_integer(props struct {
     props.Report("invalid unsigned integer")
     return nil
   }
-  value := int(parsed)
+  // A float64 outside the destination range converts by an
+  // implementation-defined rule, not by wrapping: on amd64 both `1e19` and
+  // `-1e19` become -9223372036854775808, so a magnitude and its negation
+  // collapse to the same wrong number. Reject instead, because a tag whose value
+  // cannot be carried is a tag whose meaning is already lost.
+  if parsed < metadataCommentTagFactory_INT64_MINIMUM || parsed >= metadataCommentTagFactory_INT64_EXCLUSIVE_MAXIMUM {
+    props.Report("integer out of range")
+    return nil
+  }
+  value := int64(parsed)
   return &value
 }
 
+// The int64 range as float64 bounds.
+//
+// int64 rather than int, because `int` is 32 bits on the 32-bit platforms ttsc
+// publishes a binary for (`@ttsc/linux-arm`). Bounding by `int` would make the
+// same `@minimum 3000000000` on a `bigint` compile on x64 and either be rejected
+// or silently converted out of range on arm, and the value is already widened to
+// int64 at its only numeric use. Bounding by int64 is what the tag means on
+// every platform.
+//
+// The maximum is exclusive and spelled 2**63 rather than math.MaxInt64, because
+// the inclusive form does not survive the comparison. An untyped constant
+// 9223372036854775807.0 rounds to 2**63 once it meets a float64 operand, so
+// `parsed > max` compares 2**63 against 2**63 and lets the one value through
+// that int64 cannot hold. A strict `>=` against 2**63 is exact instead: no
+// float64 lies between 2**63 - 1024 and 2**63, so rejecting from 2**63 up
+// rejects exactly the magnitudes int64 cannot represent.
+//
+// The minimum needs no such care -- -2**63 is math.MinInt64 and is exactly
+// representable as a float64.
+const (
+  metadataCommentTagFactory_INT64_MINIMUM           = -9223372036854775808.0
+  metadataCommentTagFactory_INT64_EXCLUSIVE_MAXIMUM = 9223372036854775808.0
+)
+
 func metadataCommentTagFactory_includes(values []string, target string) bool {
   for _, value := range values {
     if value == target {