@nestia/sdk 13.0.4 → 14.0.1

package/native/sdk/sdk_transform.go

@@ -1,12 +1,16 @@
 package sdk
 
 import (
+	"encoding"
 	"encoding/json"
 	"fmt"
+	"math"
 	"os"
 	"path/filepath"
+	"reflect"
 	"regexp"
 	"sort"
+	"strconv"
 	"strings"
 
 	shimast "github.com/microsoft/typescript-go/shim/ast"
@@ -40,9 +44,10 @@ type nestiaSDKContext struct {
 }
 
 type nestiaSDKSchemaCacheKey struct {
-	Type   *shimchecker.Type
-	Text   string
-	Escape bool
+	Type       *shimchecker.Type
+	Text       string
+	Escape     bool
+	Properties bool
 }
 
 func newNestiaSDKContext(prog *driver.Program) *nestiaSDKContext {
@@ -148,7 +153,16 @@ func nestiaSDKMetadataText(context *nestiaSDKContext, file *shimast.SourceFile,
 		for index, param := range methodDecl.Parameters.Nodes {
 			typ := prog.Checker.GetTypeAtLocation(param)
 			name := nestiaSDKParameterName(param)
-			response := nestiaSDKResponse(context, imports, typ, nestiaSDKParameterTypeNode(param))
+			response := nestiaSDKResponse(context, imports, typ, nestiaSDKParameterTypeNode(param), true)
+			if ref, refs, err := nestiaSDKWebSocketParameterType(context, param); err != nil {
+				return "", err
+			} else if ref != nil {
+				response["type"] = ref
+				response["imports"] = refs
+			}
+			if err := nestiaSDKWebSocketHeaderError(context.prog, param, typ); err != nil {
+				return "", err
+			}
 			parameters = append(parameters, map[string]any{
 				"name":        name,
 				"index":       index,
@@ -166,7 +180,7 @@ func nestiaSDKMetadataText(context *nestiaSDKContext, file *shimast.SourceFile,
 	exceptions := nestiaSDKExceptionResponses(context, imports, method)
 	metadata := map[string]any{
 		"parameters":  parameters,
-		"success":     nestiaSDKResponse(context, imports, returnType, returnTypeNode),
+		"success":     nestiaSDKResponse(context, imports, returnType, returnTypeNode, false),
 		"exceptions":  exceptions,
 		"description": nestiaSDKNullableString(doc.Description),
 		"jsDocTags":   doc.Tags,
@@ -177,7 +191,7 @@ func nestiaSDKMetadataText(context *nestiaSDKContext, file *shimast.SourceFile,
 const nestiaSDKLiteralNull = "__NESTIA_LITERAL_NULL__"
 
 func nestiaSDKMetadataLiteralText(metadata map[string]any) (string, error) {
-	data, err := json.Marshal(metadata)
+	data, err := json.Marshal(nestiaSDKFiniteLiteral(metadata))
 	if err != nil {
 		return "", err
 	}
@@ -186,6 +200,88 @@ func nestiaSDKMetadataLiteralText(metadata map[string]any) (string, error) {
 	return text, nil
 }
 
+// nestiaSDKFiniteLiteral copies a metadata value for encoding/json, writing
+// every non-finite number as null, the way JavaScript's `JSON.stringify` does.
+//
+// typia hands over NaN and ±Infinity wherever a type or a comment spells one: a
+// numeric literal type such as `1e999`, a type tag argument such as
+// `tags.Minimum<1e999>`, and a JSDoc `@x-` extension whose text parses as
+// a float, which `NaN`, `Infinity`, and `inf` all do. encoding/json
+// refuses those values, so one of them anywhere in the types a route reaches
+// used to abort the whole metadata pass. The metadata is marshaled only here,
+// so walking it here gives every value, baked schema and metadata literal
+// alike, the same rule.
+//
+// The walk rebuilds maps, slices, and typia's ordered objects, whose
+// MarshalJSON would otherwise marshal a non-finite member itself. A null is
+// written as typia's explicit `LiteralFactory_Null` marker rather than a Go
+// nil, because an ordered object drops a nil member instead of printing it,
+// while `JSON.stringify({ a: NaN })` keeps the key. Any other value that
+// marshals itself is left as it is.
+func nestiaSDKFiniteLiteral(input any) any {
+	switch value := input.(type) {
+	case nil:
+		return nil
+	case nativefactories.LiteralFactory_OrderedObject:
+		return nestiaSDKFiniteOrderedLiteral(value)
+	case *nativefactories.LiteralFactory_OrderedObject:
+		if value == nil {
+			return value
+		}
+		return nestiaSDKFiniteOrderedLiteral(*value)
+	case json.Marshaler, encoding.TextMarshaler:
+		return value
+	}
+	reflected := reflect.ValueOf(input)
+	switch reflected.Kind() {
+	case reflect.Float32, reflect.Float64:
+		// by kind, because the checker's numbers are typescript-go's named
+		// `jsnum.Number`, not a plain float64
+		if number := reflected.Float(); math.IsNaN(number) || math.IsInf(number, 0) {
+			return nativefactories.LiteralFactory_Null{}
+		}
+		return input
+	case reflect.Map:
+		if reflected.IsNil() || reflected.Type().Key().Kind() != reflect.String {
+			return input
+		}
+		output := make(map[string]any, reflected.Len())
+		iterator := reflected.MapRange()
+		for iterator.Next() {
+			output[iterator.Key().String()] = nestiaSDKFiniteLiteral(iterator.Value().Interface())
+		}
+		return output
+	case reflect.Slice, reflect.Array:
+		if (reflected.Kind() == reflect.Slice && reflected.IsNil()) || reflected.Type().Elem().Kind() == reflect.Uint8 {
+			return input
+		}
+		output := make([]any, reflected.Len())
+		for i := range output {
+			output[i] = nestiaSDKFiniteLiteral(reflected.Index(i).Interface())
+		}
+		return output
+	case reflect.Pointer, reflect.Interface:
+		if reflected.IsNil() {
+			return input
+		}
+		return nestiaSDKFiniteLiteral(reflected.Elem().Interface())
+	}
+	return input
+}
+
+func nestiaSDKFiniteOrderedLiteral(
+	input nativefactories.LiteralFactory_OrderedObject,
+) nativefactories.LiteralFactory_OrderedObject {
+	output := nativefactories.LiteralFactory_OrderedObject{
+		Keys:   input.Keys,
+		Values: make(map[string]any, len(input.Values)),
+	}
+	for key, value := range input.Values {
+		output.Values[key] = nestiaSDKFiniteLiteral(value)
+	}
+	return output
+}
+
 type nestiaSDKJSDoc struct {
 	Description string
 	Tags        []any
@@ -205,34 +301,83 @@ func nestiaSDKMethodJSDoc(file *shimast.SourceFile, method *shimast.Node) nestia
 	if comment == "" {
 		return doc
 	}
+	// A tag runs until the next one, and each line loses the comment's margin
+	// as TypeScript takes it off: the `*`, then the indentation up to the
+	// column the text began at. That is the description's first line, the
+	// text after a tag's name, a `@param` description past the parameter's
+	// name, a `@returns` one past its type, or, when the tag's text starts on
+	// the next line, the tag itself, so an `@example` keeps its code's
+	// indentation while a wrapped `@param` description does not.
 	description := []string{}
-	inTags := false
+	descriptionMargin := -1
+	var tag *nestiaSDKPendingTag
+	flush := func() {
+		if tag == nil {
+			return
+		}
+		body := strings.TrimLeft(strings.Join(tag.lines, "\n"), "\n")
+		body = strings.TrimRight(body, " \t\n")
+		if tag.name == "param" {
+			param, desc := nestiaSDKParseParamTag(body)
+			doc.Tags = append(doc.Tags, nestiaSDKJSDocParamTag(param, desc))
+			if param != "" {
+				doc.Params[param] = desc
+			}
+		} else {
+			if nestiaSDKIsReturnTag(tag.name) {
+				// TypeScript's text leaves out a type the tag declares
+				body = strings.TrimLeft(body[nestiaSDKReturnTypeEnd(body):], "\n")
+			}
+			doc.Tags = append(doc.Tags, nestiaSDKJSDocTag(tag.name, body))
+		}
+		tag = nil
+	}
 	for _, line := range strings.Split(comment, "\n") {
-		text := strings.TrimSpace(line)
-		text = strings.TrimPrefix(text, "*")
-		text = strings.TrimSpace(text)
-		if text == "" {
-			if inTags == false && len(description) != 0 {
-				description = append(description, "")
+		rest := strings.TrimLeft(line, " \t")
+		rest = strings.TrimPrefix(rest, "*")
+		rest = strings.TrimRight(rest, " \t\r")
+		trimmed := strings.TrimSpace(rest)
+		if strings.HasPrefix(trimmed, "@") {
+			flush()
+			name, body := nestiaSDKParseJSDocTag(trimmed)
+			margin := nestiaSDKJSDocIndent(rest)
+			// where the text begins in the body: a `@param` description after
+			// the parameter's name, a `@returns` one after its type
+			text := 0
+			if name == "param" {
+				_, text = nestiaSDKParamTagName(body)
+			} else if nestiaSDKIsReturnTag(name) {
+				text = nestiaSDKReturnTypeEnd(body)
 			}
+			if text < len(body) {
+				after := trimmed[1+len(name):]
+				margin += 1 + len(name) + len(after) - len(strings.TrimLeft(after, " \t")) + text
+			}
+			tag = &nestiaSDKPendingTag{name: name, lines: []string{body}, margin: margin}
 			continue
 		}
-		if strings.HasPrefix(text, "@") {
-			inTags = true
-			name, body := nestiaSDKParseJSDocTag(text)
-			doc.Tags = append(doc.Tags, nestiaSDKJSDocTag(name, body))
-			if name == "param" {
-				param, desc := nestiaSDKParseParamTag(body)
-				if param != "" {
-					doc.Params[param] = desc
-				}
+		if tag != nil {
+			tag.lines = append(tag.lines, nestiaSDKJSDocOutdent(rest, tag.margin))
+			continue
+		}
+		if trimmed == "" {
+			if len(description) != 0 {
+				description = append(description, "")
 			}
 			continue
 		}
-		if inTags == false {
-			description = append(description, text)
+		if descriptionMargin == -1 {
+			// text on the opening `/**` line has no `*` to measure from, so the
+			// lines after it keep the usual `* ` margin
+			if strings.HasPrefix(strings.TrimLeft(line, " \t"), "*") {
+				descriptionMargin = nestiaSDKJSDocIndent(rest)
+			} else {
+				descriptionMargin = 1
+			}
 		}
+		description = append(description, nestiaSDKJSDocOutdent(rest, descriptionMargin))
 	}
+	flush()
 	doc.Description = strings.TrimSpace(strings.Join(description, "\n"))
 	return doc
 }
@@ -288,14 +433,108 @@ func nestiaSDKParseJSDocTag(text string) (string, string) {
 	return name, body
 }
 
+// nestiaSDKPendingTag is a JSDoc tag whose text may continue on the next
+// lines.
+type nestiaSDKPendingTag struct {
+	name   string
+	lines  []string
+	margin int
+}
+
+// nestiaSDKJSDocIndent counts the spaces and tabs a JSDoc line starts with.
+func nestiaSDKJSDocIndent(line string) int {
+	return len(line) - len(strings.TrimLeft(line, " \t"))
+}
+
+// nestiaSDKJSDocOutdent takes up to margin spaces and tabs off a JSDoc line.
+func nestiaSDKJSDocOutdent(line string, margin int) string {
+	indent := nestiaSDKJSDocIndent(line)
+	if indent > margin {
+		indent = margin
+	}
+	return line[indent:]
+}
+
+// nestiaSDKParseParamTag splits a `@param` body into the parameter's name and
+// its description, as TypeScript does. A description that starts on the next
+// line keeps the indentation its margin leaves it.
 func nestiaSDKParseParamTag(body string) (string, string) {
-	parts := strings.Fields(body)
-	if len(parts) == 0 {
-		return "", ""
+	param, text := nestiaSDKParamTagName(body)
+	return param, strings.TrimLeft(body[text:], "\n")
+}
+
+// nestiaSDKParamTagName reads the parameter a `@param` body names, as
+// TypeScript does: a leading `{Type}` is not the name, and an optional
+// parameter's brackets and default, `[name=value]`, are not part of it. It
+// also returns where the description begins, past the spaces after the name.
+func nestiaSDKParamTagName(body string) (string, int) {
+	offset := nestiaSDKSkipBlank(body, 0, true)
+	if end := nestiaSDKClosing(body, offset, '{', '}'); end != -1 {
+		offset = nestiaSDKSkipBlank(body, end+1, true)
+	}
+	name := ""
+	if end := nestiaSDKClosing(body, offset, '[', ']'); end != -1 {
+		// the bracket that closes the first, past any in a default value
+		name = body[offset+1 : end]
+		if equal := strings.Index(name, "="); equal != -1 {
+			name = name[:equal]
+		}
+		name = strings.TrimSpace(name)
+		offset = end + 1
+	} else {
+		start := offset
+		for offset < len(body) && strings.IndexByte(" \t\n", body[offset]) == -1 {
+			offset++
+		}
+		name = body[start:offset]
+	}
+	return name, nestiaSDKSkipBlank(body, offset, false)
+}
+
+// nestiaSDKIsReturnTag tells a `@returns` tag, which TypeScript also reads as
+// `@return`.
+func nestiaSDKIsReturnTag(name string) bool {
+	return name == "returns" || name == "return"
+}
+
+// nestiaSDKReturnTypeEnd returns where a `@returns` body's text begins past a
+// leading `{Type}`, which TypeScript reads as the type rather than the text,
+// and the spaces after it; 0 without a type.
+func nestiaSDKReturnTypeEnd(body string) int {
+	if end := nestiaSDKClosing(body, nestiaSDKSkipBlank(body, 0, true), '{', '}'); end != -1 {
+		return nestiaSDKSkipBlank(body, end+1, false)
 	}
-	param := parts[0]
-	desc := strings.TrimSpace(strings.TrimPrefix(body, param))
-	return param, desc
+	return 0
+}
+
+// nestiaSDKClosing finds the bracket closing the one text opens at start, or
+// -1 when text opens none there or never closes it.
+func nestiaSDKClosing(text string, start int, open byte, close byte) int {
+	if start >= len(text) || text[start] != open {
+		return -1
+	}
+	depth := 0
+	for i := start; i < len(text); i++ {
+		if text[i] == open {
+			depth++
+		} else if text[i] == close {
+			depth--
+			if depth == 0 {
+				return i
+			}
+		}
+	}
+	return -1
+}
+
+// nestiaSDKSkipBlank moves offset past spaces and tabs, and line breaks too
+// when newline is set.
+func nestiaSDKSkipBlank(text string, offset int, newline bool) int {
+	for offset < len(text) &&
+		(text[offset] == ' ' || text[offset] == '\t' || (newline && text[offset] == '\n')) {
+		offset++
+	}
+	return offset
 }
 
 func nestiaSDKJSDocTag(name string, text string) map[string]any {
@@ -315,6 +554,33 @@ func nestiaSDKJSDocTag(name string, text string) map[string]any {
 	}
 }
 
+// nestiaSDKJSDocParamTag writes a `@param` tag the way TypeScript's
+// `JSDocTagInfo` does, which the SDK generators read: the parameter's name
+// as its own `parameterName` part, then a space and the description. Written
+// as one text part, the name could not be matched, so a WebSocket route lost
+// every `@param` line and the generators' tag fallbacks never applied.
+func nestiaSDKJSDocParamTag(param string, desc string) map[string]any {
+	if param == "" {
+		return nestiaSDKJSDocTag("param", "")
+	}
+	text := []any{
+		map[string]any{
+			"text": param,
+			"kind": "parameterName",
+		},
+	}
+	if desc != "" {
+		text = append(text,
+			map[string]any{"text": " ", "kind": "space"},
+			map[string]any{"text": desc, "kind": "text"},
+		)
+	}
+	return map[string]any{
+		"name": "param",
+		"text": text,
+	}
+}
+
 func nestiaSDKNullableString(value string) any {
 	value = strings.TrimSpace(value)
 	if value == "" {
@@ -335,7 +601,7 @@ func nestiaSDKExceptionResponses(
 		if exception == nil {
 			continue
 		}
-		responses = append(responses, nestiaSDKResponse(context, imports, exception.Type, exception.Node))
+		responses = append(responses, nestiaSDKResponse(context, imports, exception.Type, exception.Node, false))
 	}
 	return responses
 }
@@ -354,7 +620,9 @@ func nestiaSDKTypedExceptionInfo(prog *driver.Program, decorator *shimast.Node)
 		return nil
 	}
 	call := expression.AsCallExpression()
-	segments := transform.NestiaCoreExpressionSegments(call.Expression)
+	// by the export the import binds, as the runtime registers an aliased
+	// `TypedException` too; a lexical name lost it, misaligning the exceptions
+	segments := transform.NestiaCoreCanonicalDecoratorSegments(decorator)
 	if len(segments) == 0 || segments[len(segments)-1] != "TypedException" {
 		return nil
 	}
@@ -538,11 +806,16 @@ func nestiaSDKImportLiteral(imp nestiaSDKImportInfo, prefixes map[string]bool) m
 	return output
 }
 
+// nestiaSDKResponse reflects one route input or output. `parameter` marks a
+// method parameter: the Swagger generator reads query and headers parameters
+// from the resolved schema and may decompose their object into one OpenAPI
+// parameter per property, so only that schema bakes the property schemas.
 func nestiaSDKResponse(
 	context *nestiaSDKContext,
 	imports []nestiaSDKImportInfo,
 	typ *shimchecker.Type,
 	typeNode *shimast.Node,
+	parameter bool,
 ) map[string]any {
 	prog := context.prog
 	refType, refImports := nestiaSDKReflectType(prog, imports, typ, typeNode)
@@ -552,17 +825,18 @@ func nestiaSDKResponse(
 	return map[string]any{
 		"type":      refType,
 		"imports":   refImports,
-		"primitive": nestiaSDKSchemaPipe(context, typ, typeNode, true),
-		"resolved":  nestiaSDKSchemaPipe(context, typ, typeNode, false),
+		"primitive": nestiaSDKSchemaPipe(context, typ, typeNode, true, false),
+		"resolved":  nestiaSDKSchemaPipe(context, typ, typeNode, false, parameter),
 	}
 }
 
-func nestiaSDKSchemaPipe(context *nestiaSDKContext, typ *shimchecker.Type, typeNode *shimast.Node, escape bool) any {
+func nestiaSDKSchemaPipe(context *nestiaSDKContext, typ *shimchecker.Type, typeNode *shimast.Node, escape bool, properties bool) any {
 	prog := context.prog
 	key := nestiaSDKSchemaCacheKey{
-		Type:   typ,
-		Text:   nestiaSDKTypeNodeText(typeNode),
-		Escape: escape,
+		Type:       typ,
+		Text:       nestiaSDKTypeNodeText(typeNode),
+		Escape:     escape,
+		Properties: properties,
 	}
 	if cached, ok := context.schemaCache[key]; ok {
 		context.schemaHits++
@@ -617,15 +891,20 @@ func nestiaSDKSchemaPipe(context *nestiaSDKContext, typ *shimchecker.Type, typeN
 	// and omit the field — the sdk generator falls back to its own derived
 	// schema path. This must never mask a real bug, so re-raise anything we
 	// don't recognize as a transformer error from the typia runtime.
-	if baked := nestiaSDKTryBakeJsonSchema(prog, typeNode, result.Data); baked != nil {
+	if baked := nestiaSDKTryBakeJsonSchema(prog, typeNode, result.Data, properties); baked != nil {
 		metadataLiteral["jsonSchema"] = baked
 	}
+	data := map[string]any{
+		"components": nestiaSDKMetadataComponentsLiteral(nestiaSDKVisitedMetadataComponents(context.collection, result.Data)),
+		"metadata":   metadataLiteral,
+	}
+	if properties {
+		// a route parameter's HTTP rule verdicts, from its own analysis
+		data["http"] = nestiaSDKHttpRules(prog.Checker, typ)
+	}
 	value := map[string]any{
 		"success": true,
-		"data": map[string]any{
-			"components": nestiaSDKMetadataComponentsLiteral(nestiaSDKVisitedMetadataComponents(context.collection, result.Data)),
-			"metadata":   metadataLiteral,
-		},
+		"data":    data,
 	}
 	context.schemaCache[key] = value
 	return value
@@ -636,10 +915,15 @@ func nestiaSDKSchemaPipe(context *nestiaSDKContext, typ *shimchecker.Type, typeN
 // when typia signals the metadata has no JSON-schema representation (e.g.
 // `void` returns, function-only types) — the JS-side reader handles missing
 // `jsonSchema` fields. Any other panic is re-raised so real bugs surface.
+//
+// With `properties`, the literal also carries the schema of each property of
+// the metadata's first object type, for the Swagger generator to decompose into
+// individual parameters (see `nestiaSDKPropertySchemas`).
 func nestiaSDKTryBakeJsonSchema(
 	prog *driver.Program,
 	typeNode *shimast.Node,
 	metadata *schemametadata.MetadataSchema,
+	properties bool,
 ) (baked map[string]any) {
 	defer func() {
 		if r := recover(); r != nil {
@@ -660,6 +944,12 @@ func nestiaSDKTryBakeJsonSchema(
 	if len(collection.Schemas) == 0 {
 		return nil
 	}
+	// Baked before the components are flattened: the property schemas share
+	// the parent's components, so any component they reach must be included.
+	var propertySchemas map[string]any
+	if properties && collection.Components != nil {
+		propertySchemas = nestiaSDKPropertySchemas(metadata, collection.Components)
+	}
 	// `iterate.OpenApi_IComponents` has no JSON tags on its Schemas field,
 	// so default Go marshaling would emit `"Schemas"` (capital). The JS
 	// side reads `components.schemas`, so flatten to a plain map here.
@@ -667,19 +957,236 @@ func nestiaSDKTryBakeJsonSchema(
 	if collection.Components != nil && collection.Components.Schemas != nil {
 		schemasLiteral := map[string]any{}
 		for key, val := range collection.Components.Schemas {
-			schemasLiteral[key] = map[string]any(val)
+			schemasLiteral[key] = nestiaSDKJsonSchemaLiteral(val)
 		}
 		componentsLiteral["schemas"] = schemasLiteral
 	}
 	baked = map[string]any{
 		"version":    collection.Version,
 		"components": componentsLiteral,
-		"schema":     map[string]any(collection.Schemas[0]),
+		"schema":     nestiaSDKJsonSchemaLiteral(collection.Schemas[0]),
+	}
+	if propertySchemas != nil {
+		baked["properties"] = propertySchemas
 	}
 	nestiaSDKMarkReadonlyArrayJsonSchema(prog, typeNode, baked)
 	return baked
 }
 
+// nestiaSDKPropertySchemas bakes the schema of each property of the metadata's
+// first object type, keyed by property name, for a decomposed query or headers
+// parameter. It is the property schema typia's object writer produces, minus
+// the fields the OpenAPI parameter carries in its own members: typia merges the
+// property's title, description, and deprecation into that schema, plus
+// readOnly, which has no meaning for a request parameter. What remains is the
+// value schema, written by typia's `Json_schema_station` exactly as
+// `WriteSchemas` writes one metadata but against the parent's components, so a
+// named type the value reaches resolves to the component the parent already
+// carries, and the property's `x-` JSDoc extensions.
+//
+// Only properties typia's object schema describes are baked: a property must
+// have a literal key and no `@hidden`, `@ignore`, or `@internal` tag (the
+// filter `json_schema_object` applies), and a value with no JSON form
+// (function-only or `never`) yields no schema. Skipping them here also keeps
+// their types out of the shared components.
+func nestiaSDKPropertySchemas(
+	metadata *schemametadata.MetadataSchema,
+	components *nativeiterate.OpenApi_IComponents,
+) map[string]any {
+	if len(metadata.Objects) == 0 || metadata.Objects[0].Type == nil {
+		return nil
+	}
+	output := map[string]any{}
+	for _, property := range metadata.Objects[0].Type.Properties {
+		if property == nil || property.Key == nil || property.Value == nil {
+			continue
+		}
+		key := property.Key.GetSoleLiteral()
+		if key == nil || nestiaSDKHasJSDocTag(property.JsDocTags, "hidden", "ignore", "internal") {
+			continue
+		}
+		schema := nativeiterate.Json_schema_station(nativeiterate.Json_schema_station_props{
+			BlockNever: true,
+			Components: components,
+			Attribute:  nativeiterate.JsonSchema{},
+			Metadata:   property.Value,
+		})
+		if schema == nil {
+			continue
+		}
+		nestiaSDKJsDocExtensions(schema, property.JsDocTags)
+		output[*key] = nestiaSDKJsonSchemaLiteral(schema)
+	}
+	return output
+}
+
+// nestiaSDKJsDocExtensions writes a property's `x-` JSDoc tags into its schema
+// the way typia's object writer does (`json_schema_jsDocTags`, unexported):
+// the first text part, trimmed, read as a boolean, a number, null, or else a
+// string.
+func nestiaSDKJsDocExtensions(schema nativeiterate.JsonSchema, tags []schemametadata.IJsDocTagInfo) {
+	for _, tag := range tags {
+		if strings.HasPrefix(tag.Name, "x-") == false {
+			continue
+		}
+		for _, text := range tag.Text {
+			if text.Kind != "text" {
+				continue
+			}
+			value := strings.ReplaceAll(strings.TrimSpace(text.Text), "\r\n", "\n")
+			if value == "true" || value == "false" {
+				schema[tag.Name] = value == "true"
+			} else if number, err := strconv.ParseFloat(value, 64); err == nil {
+				schema[tag.Name] = number
+			} else if value == "null" {
+				schema[tag.Name] = nil
+			} else {
+				schema[tag.Name] = value
+			}
+			break
+		}
+	}
+}
+
+func nestiaSDKHasJSDocTag(tags []schemametadata.IJsDocTagInfo, names ...string) bool {
+	for _, tag := range tags {
+		for _, name := range names {
+			if tag.Name == name {
+				return true
+			}
+		}
+	}
+	return false
+}
+
+// nestiaSDKJsonSchemaLiteral prepares one typia JSON schema for the
+// encoding/json serialization of the SDK metadata, dropping the members typia
+// leaves absent.
+//
+// typia's schema writer stores a Go nil for an absent member: a constant with
+// no `@title` gets a nil *string title and description, and `any` gets a nil
+// type. typia's own literal printer skips nil object members, but encoding/json
+// prints them as null, which JSON Schema rejects for those keywords. A nil
+// cannot be dropped everywhere, though: in an instance-valued keyword (`const`,
+// `default`, `enum`, `example`, `examples`) or a vendor extension it can be a
+// real null. typia marks the nulls a type declares, such as
+// `tags.Example<null>`, with `LiteralFactory_Null`, which is no nil and
+// marshals as null, but a JSDoc `@x-foo null` still reaches the schema as a
+// bare nil, from typia's object writer and from nestiaSDKJsDocExtensions alike.
+//
+// So the walk follows JSON Schema structure: it drops a nil member of a schema
+// object, recurses through the applicator keywords into subschemas, and leaves
+// every other value, instance data included, as it is.
+func nestiaSDKJsonSchemaLiteral(input any) any {
+	reflected := reflect.ValueOf(input)
+	if reflected.Kind() != reflect.Map || reflected.Type().Key().Kind() != reflect.String {
+		return input // a boolean schema, or a value that is no schema object
+	}
+	output := make(map[string]any, reflected.Len())
+	iterator := reflected.MapRange()
+	for iterator.Next() {
+		key := iterator.Key().String()
+		member := iterator.Value().Interface()
+		if nestiaSDKJsonSchemaInstanceKeyword(key) {
+			output[key] = member
+		} else if nestiaSDKIsNilLike(member) == false {
+			output[key] = nestiaSDKJsonSchemaMember(key, member)
+		}
+	}
+	return output
+}
+
+// nestiaSDKJsonSchemaMember recurses into the subschemas a JSON Schema 2020-12
+// applicator keyword holds, and returns any other keyword value unchanged.
+func nestiaSDKJsonSchemaMember(key string, member any) any {
+	switch key {
+	case "items", "additionalItems", "additionalProperties", "unevaluatedItems",
+		"unevaluatedProperties", "contains", "propertyNames", "not", "if", "then",
+		"else", "contentSchema":
+		return nestiaSDKJsonSchemaLiteral(member)
+	case "allOf", "anyOf", "oneOf", "prefixItems":
+		reflected := reflect.ValueOf(member)
+		if reflected.Kind() != reflect.Slice && reflected.Kind() != reflect.Array {
+			return member
+		}
+		output := make([]any, reflected.Len())
+		for i := range output {
+			output[i] = nestiaSDKJsonSchemaLiteral(reflected.Index(i).Interface())
+		}
+		return output
+	case "properties", "patternProperties", "dependentSchemas", "$defs", "definitions":
+		return nestiaSDKJsonSchemaNamedLiteral(member)
+	}
+	return member
+}
+
+// nestiaSDKJsonSchemaNamedLiteral normalizes each schema of a name-keyed schema
+// map, such as `properties`, keeping the order of typia's ordered objects.
+func nestiaSDKJsonSchemaNamedLiteral(input any) any {
+	switch value := input.(type) {
+	case nativefactories.LiteralFactory_OrderedObject:
+		return nestiaSDKJsonSchemaOrderedLiteral(value)
+	case *nativefactories.LiteralFactory_OrderedObject:
+		if value == nil {
+			return nil
+		}
+		return nestiaSDKJsonSchemaOrderedLiteral(*value)
+	}
+	reflected := reflect.ValueOf(input)
+	if reflected.Kind() != reflect.Map || reflected.Type().Key().Kind() != reflect.String {
+		return input
+	}
+	output := make(map[string]any, reflected.Len())
+	iterator := reflected.MapRange()
+	for iterator.Next() {
+		output[iterator.Key().String()] = nestiaSDKJsonSchemaLiteral(iterator.Value().Interface())
+	}
+	return output
+}
+
+func nestiaSDKJsonSchemaOrderedLiteral(
+	input nativefactories.LiteralFactory_OrderedObject,
+) nativefactories.LiteralFactory_OrderedObject {
+	output := nativefactories.LiteralFactory_OrderedObject{
+		Keys:   make([]string, 0, len(input.Keys)),
+		Values: make(map[string]any, len(input.Keys)),
+	}
+	for _, key := range input.Keys {
+		value, ok := input.Values[key]
+		if ok == false || nestiaSDKIsNilLike(value) {
+			continue
+		}
+		output.Keys = append(output.Keys, key)
+		output.Values[key] = nestiaSDKJsonSchemaLiteral(value)
+	}
+	return output
+}
+
+// nestiaSDKJsonSchemaInstanceKeyword reports a keyword whose value is JSON
+// instance data, where null is a legitimate value: the instance keywords of
+// JSON Schema and OpenAPI, and `x-` vendor extensions.
+func nestiaSDKJsonSchemaInstanceKeyword(key string) bool {
+	switch key {
+	case "const", "default", "enum", "example", "examples":
+		return true
+	}
+	return strings.HasPrefix(key, "x-")
+}
+
+// nestiaSDKIsNilLike mirrors typia's `literalFactory_isNilLike`.
+func nestiaSDKIsNilLike(value any) bool {
+	if value == nil {
+		return true
+	}
+	reflected := reflect.ValueOf(value)
+	switch reflected.Kind() {
+	case reflect.Chan, reflect.Func, reflect.Interface, reflect.Map, reflect.Pointer, reflect.Slice:
+		return reflected.IsNil()
+	default:
+		return false
+	}
+}
+
 func nestiaSDKMarkReadonlyArrayJsonSchema(prog *driver.Program, typeNode *shimast.Node, baked map[string]any) {
 	components, _ := baked["components"].(map[string]any)
 	schemas, _ := components["schemas"].(map[string]any)
@@ -1505,18 +2012,261 @@ func nestiaSDKParentClassName(node *shimast.Node) string {
 	return ""
 }
 
+// nestiaSDKMethodName names a decorated method's site. The contributor visits
+// every decorated method of the program, controller or not, and a computed
+// name such as `[key]` has no identifier: it reads as its literal key when it
+// has one, and as its source otherwise. The metadata still reaches the method,
+// because a decorator attaches it under the key the runtime computes.
 func nestiaSDKMethodName(node *shimast.Node) string {
 	if node == nil || node.Name() == nil {
 		return ""
 	}
-	return strings.Trim(node.Name().Text(), "\"'")
+	name := node.Name()
+	if name.Kind == shimast.KindComputedPropertyName {
+		switch expression := name.AsComputedPropertyName().Expression; expression.Kind {
+		case shimast.KindStringLiteral, shimast.KindNumericLiteral, shimast.KindNoSubstitutionTemplateLiteral:
+			return expression.Text()
+		}
+	}
+	return strings.Trim(shimast.NodeText(name), "\"'")
+}
+
+// nestiaSDKWebSocketHeaderError reports a WebSocket route whose handshake
+// header the generated SDK cannot carry: the header type of an
+// @WebSocketRoute.Acceptor() (its first type argument) or the type of an
+// @WebSocketRoute.Header() parameter must be an object type or undefined,
+// because the SDK function sends it as connection.headers, which @nestia/fetcher
+// types `IConnection<Headers extends object | undefined>`. tgrid itself leaves
+// the header unconstrained, so a null or primitive header serves, yet its SDK
+// would not compile.
+func nestiaSDKWebSocketHeaderError(
+	prog *driver.Program,
+	param *shimast.Node,
+	typ *shimchecker.Type,
+) error {
+	category := transform.NestiaCoreWebSocketParameterCategory(prog, param)
+	var header *shimchecker.Type
+	switch category {
+	case "Acceptor":
+		// only tgrid's acceptor has a header; the transform already rejects any
+		// other type, and asking a non-reference type for its type arguments
+		// would fault the checker
+		if _, name := transform.NestiaCoreWebSocketTypeReference(prog, nestiaSDKParameterTypeNode(param)); name != "WebSocketAcceptor" {
+			return nil
+		}
+		if typ == nil || typ.Flags()&shimchecker.TypeFlagsObject == 0 || typ.ObjectFlags()&shimchecker.ObjectFlagsReference == 0 {
+			return nil
+		}
+		if args := shimchecker.Checker_getTypeArguments(prog.Checker, typ); len(args) != 0 {
+			header = args[0]
+		}
+	case "Header":
+		header = typ
+	default:
+		return nil
+	}
+	if header == nil || nestiaSDKIsConnectionHeader(header) {
+		return nil
+	}
+	return fmt.Errorf(
+		"@WebSocketRoute.%s() parameter %q has the header type %q, which the SDK cannot send: it carries the handshake header as connection.headers, which must be an object type or undefined. Use an object type, or undefined for no header.",
+		category,
+		nestiaSDKParameterName(param),
+		prog.Checker.TypeToString(header),
+	)
+}
+
+// nestiaSDKIsConnectionHeader reports whether typ is assignable to
+// `object | undefined`, the constraint of IConnection's Headers: any, never,
+// undefined, an object type, or a union of them; an intersection only when
+// every member is an object type, so `string & {}` stays a string.
+func nestiaSDKIsConnectionHeader(typ *shimchecker.Type) bool {
+	flags := typ.Flags()
+	if flags&(shimchecker.TypeFlagsAny|shimchecker.TypeFlagsNever|shimchecker.TypeFlagsUndefined|shimchecker.TypeFlagsObject|shimchecker.TypeFlagsNonPrimitive) != 0 {
+		return true
+	}
+	if flags&shimchecker.TypeFlagsUnion != 0 {
+		for _, elem := range typ.AsUnionOrIntersectionType().Types() {
+			if nestiaSDKIsConnectionHeader(elem) == false {
+				return false
+			}
+		}
+		return true
+	}
+	if flags&shimchecker.TypeFlagsIntersection != 0 {
+		for _, elem := range typ.AsUnionOrIntersectionType().Types() {
+			if elem.Flags()&(shimchecker.TypeFlagsObject|shimchecker.TypeFlagsNonPrimitive) == 0 {
+				return false
+			}
+		}
+		return true
+	}
+	return false
+}
+
+// nestiaSDKWebSocketParameterType reflects an @WebSocketRoute.Acceptor() or
+// .Driver() parameter annotated through a type alias or an import type as the
+// tgrid reference it spells, such as `WebSocketAcceptor<Header, Provider,
+// Listener>`, because the generated client needs those type arguments. Each
+// argument is reflected in the file that writes it, and one naming a type
+// parameter of a generic alias is replaced by what the annotation passes for
+// it. It returns nil for an annotation writing the tgrid reference itself as a
+// type reference, and an error for an alias using its type parameter inside an
+// argument, such as `IRoom<P>`, which no written node spells.
+func nestiaSDKWebSocketParameterType(
+	context *nestiaSDKContext,
+	param *shimast.Node,
+) (map[string]any, []any, error) {
+	category := transform.NestiaCoreWebSocketParameterCategory(context.prog, param)
+	switch category {
+	case "Acceptor", "Driver":
+	default:
+		return nil, nil, nil
+	}
+	chain, name := transform.NestiaCoreWebSocketTypeReference(context.prog, nestiaSDKParameterTypeNode(param))
+	// the annotation's own reflection serves a tgrid reference written as a
+	// plain type reference, but reflects an import type without its arguments
+	if len(chain) == 0 || (len(chain) == 1 && chain[0].Kind == shimast.KindTypeReference) {
+		return nil, nil, nil
+	}
+	args := []any{}
+	groups := [][]any{}
+	if target := chain[len(chain)-1].TypeArgumentList(); target != nil {
+		for _, node := range target.Nodes {
+			argument := nestiaSDKWebSocketTypeArgument(context.prog, chain, node)
+			if argument == nil {
+				return nil, nil, fmt.Errorf(
+					"@WebSocketRoute.%s() parameter %q is typed by a type alias whose %s type argument %q uses a type parameter of the alias inside it, which the SDK cannot write. Pass each type parameter as a whole type argument, or write the %s type directly.",
+					category,
+					nestiaSDKParameterName(param),
+					name,
+					nestiaSDKTypeNodeText(node),
+					name,
+				)
+			}
+			imports := context.imports(shimast.GetSourceFileOfNode(argument))
+			arg, refs, ok := nestiaSDKReflectTypeNode(context.prog, imports, argument)
+			if ok == false {
+				text := nestiaSDKTypeNodeText(argument)
+				arg = map[string]any{"name": text}
+				refs = nestiaSDKReflectImports(text, imports)
+			}
+			args = append(args, arg)
+			groups = append(groups, refs)
+		}
+	}
+	refs := nestiaSDKMergeImportLiterals(groups...)
+	if refs == nil {
+		refs = []any{}
+	}
+	return map[string]any{
+		"name":          name,
+		"typeArguments": args,
+	}, refs, nil
+}
+
+// nestiaSDKWebSocketTypeArgument follows a type argument of the last reference
+// in chain back through the aliases while it names a type parameter of the
+// alias it is written in, to what the reference before passes for it or else
+// to the parameter's default. It returns nil when the argument uses such a
+// type parameter any other way, which no written node spells.
+func nestiaSDKWebSocketTypeArgument(prog *driver.Program, chain []*shimast.Node, node *shimast.Node) *shimast.Node {
+	for level := len(chain) - 1; level > 0; {
+		alias := nestiaSDKEnclosingTypeAlias(chain[level])
+		if alias == nil {
+			return nil
+		}
+		parameters := alias.AsTypeAliasDeclaration().TypeParameters
+		index := nestiaSDKTypeParameterIndex(prog, parameters, node)
+		if index == -1 {
+			if nestiaSDKUsesAliasTypeParameter(prog, node) {
+				return nil
+			}
+			return node
+		}
+		// the reference naming the alias, a type reference or an import type
+		reference := chain[level-1].TypeArgumentList()
+		if reference != nil && index < len(reference.Nodes) {
+			node = reference.Nodes[index]
+			level--
+			continue
+		}
+		// a default may name an earlier parameter of the same alias
+		node = parameters.Nodes[index].AsTypeParameterDeclaration().DefaultType
+		if node == nil {
+			return nil
+		}
+	}
+	return node
+}
+
+func nestiaSDKEnclosingTypeAlias(node *shimast.Node) *shimast.Node {
+	for parent := node.Parent; parent != nil; parent = parent.Parent {
+		if parent.Kind == shimast.KindTypeAliasDeclaration {
+			return parent
+		}
+	}
+	return nil
+}
+
+// nestiaSDKTypeParameterIndex is the position of the type parameter node names
+// by itself, such as `P` or `(P)`, among parameters, or -1.
+func nestiaSDKTypeParameterIndex(prog *driver.Program, parameters *shimast.NodeList, node *shimast.Node) int {
+	for node != nil && node.Kind == shimast.KindParenthesizedType {
+		node = node.AsParenthesizedTypeNode().Type
+	}
+	if parameters == nil || node == nil || node.Kind != shimast.KindTypeReference {
+		return -1
+	}
+	if arguments := node.AsTypeReferenceNode().TypeArguments; arguments != nil && len(arguments.Nodes) != 0 {
+		return -1
+	}
+	symbol := prog.Checker.GetSymbolAtLocation(node.AsTypeReferenceNode().TypeName)
+	if symbol == nil || symbol.Flags&shimast.SymbolFlagsTypeParameter == 0 {
+		return -1
+	}
+	for index, parameter := range parameters.Nodes {
+		for _, declaration := range symbol.Declarations {
+			if declaration == parameter {
+				return index
+			}
+		}
+	}
+	return -1
+}
+
+// nestiaSDKUsesAliasTypeParameter reports whether node refers to a type
+// parameter a type alias declares anywhere inside it.
+func nestiaSDKUsesAliasTypeParameter(prog *driver.Program, node *shimast.Node) bool {
+	if node == nil {
+		return false
+	}
+	if node.Kind == shimast.KindTypeReference {
+		symbol := prog.Checker.GetSymbolAtLocation(node.AsTypeReferenceNode().TypeName)
+		if symbol != nil && symbol.Flags&shimast.SymbolFlagsTypeParameter != 0 {
+			for _, declaration := range symbol.Declarations {
+				if declaration != nil && declaration.Parent != nil && declaration.Parent.Kind == shimast.KindTypeAliasDeclaration {
+					return true
+				}
+			}
+		}
+	}
+	found := false
+	node.ForEachChild(func(child *shimast.Node) bool {
+		found = nestiaSDKUsesAliasTypeParameter(prog, child)
+		return found
+	})
+	return found
 }
 
+// nestiaSDKParameterName reads a parameter's identifier, or "" for a
+// destructuring pattern such as `{ organizationId }`, which declares no name
+// the SDK could reuse; the SDK names such a parameter after its role.
 func nestiaSDKParameterName(node *shimast.Node) string {
-	if node == nil || node.Name() == nil {
+	if node == nil || node.Name() == nil || node.Name().Kind != shimast.KindIdentifier {
 		return ""
 	}
-	return strings.Trim(node.Name().Text(), "\"'")
+	return node.Name().Text()
 }
 func nestiaSDKParameterTypeNode(node *shimast.Node) *shimast.Node {
 	if node != nil && node.AsParameterDeclaration() != nil {
@@ -1640,7 +2390,9 @@ type sdkOperationMetadataInsertResult struct {
 func nestiaSDKDiagnostic(site nestiaSDKSite, message string) transform.Diagnostic {
 	line, column := 0, 0
 	if site.File != nil && site.Method != nil {
-		if pos := site.Method.Pos(); pos >= 0 {
+		// the first token's position: Pos() starts at the leading trivia, the
+		// previous line's end and any JSDoc
+		if pos := shimscanner.GetTokenPosOfNode(site.Method, site.File, false); pos >= 0 {
 			l, c := shimscanner.GetECMALineAndByteOffsetOfPosition(site.File, pos)
 			line, column = l+1, c+1
 		}