@nestia/sdk 12.0.0-dev.20260520.1 → 12.0.0-dev.20260521.2

package/native/sdk/register.go

@@ -0,0 +1,130 @@
+package sdk
+
+import (
+	"fmt"
+	"strings"
+
+	shimast "github.com/microsoft/typescript-go/shim/ast"
+	"github.com/samchon/ttsc/packages/ttsc/driver"
+)
+
+// sdkMetadataNamespace is the import alias the injected decorator references.
+const sdkMetadataNamespace = "__OperationMetadata"
+
+// init registers the SDK metadata transform with the ttsc driver.
+//
+// ttsc classifies this package (name != "main") as a linked transform and
+// statically links it into the `@nestia/core` host binary — but only for
+// projects that depend on `@nestia/sdk`. A project depending on `@nestia/core`
+// alone never links, compiles, or ships any of this code. When linked, this
+// `init()` runs before the host's `main`; the driver then invokes
+// `ApplyProgram` once per build, after the host's own typia + core passes.
+func init() {
+	driver.RegisterPlugin(linkedPlugin{})
+}
+
+type linkedPlugin struct{}
+
+// ApplyProgram injects the `@OperationMetadata("<json>")` decorator that the
+// SDK / Swagger / e2e generators read at runtime, plus the namespace import it
+// references.
+//
+// Insertion is done with synthesized AST nodes (NodeFlagsSynthesized): ttsc's
+// emit prints those structurally, without slicing the original source text, so
+// no source-text rewrite is needed. The metadata is carried as a single JSON
+// string literal — the `OperationMetadata` decorator `JSON.parse`s it — which
+// keeps the constructed AST to one literal node instead of a deep object tree.
+func (linkedPlugin) ApplyProgram(prog *driver.Program, _ driver.PluginContext) error {
+	sites, diags := collectNestiaSDKSites(prog)
+	if len(diags) > 0 {
+		messages := make([]string, 0, len(diags))
+		for _, diag := range diags {
+			messages = append(messages, diag.String(""))
+		}
+		return fmt.Errorf("%s", strings.Join(messages, "\n"))
+	}
+	if len(sites) == 0 {
+		return nil
+	}
+	factory := shimast.NewNodeFactory(shimast.NodeFactoryHooks{})
+	touched := map[*shimast.SourceFile]bool{}
+	for _, site := range sites {
+		if site.Method == nil || site.File == nil {
+			continue
+		}
+		injectOperationMetadataDecorator(factory, site.Method, site.Metadata)
+		touched[site.File] = true
+	}
+	for file := range touched {
+		injectOperationMetadataImport(factory, file)
+	}
+	return nil
+}
+
+func synthesized(node *shimast.Node) *shimast.Node {
+	if node != nil {
+		node.Flags |= shimast.NodeFlagsSynthesized
+	}
+	return node
+}
+
+// injectOperationMetadataDecorator prepends a synthesized
+// `@__OperationMetadata.OperationMetadata("<json>")` decorator to a controller
+// method. Every site is a method that already carries `@nestia/core`
+// decorators, so its modifier list is non-nil and can be mutated in place.
+func injectOperationMetadataDecorator(
+	factory *shimast.NodeFactory,
+	method *shimast.Node,
+	metadataJSON string,
+) {
+	modifiers := method.Modifiers()
+	if modifiers == nil {
+		return
+	}
+	namespaceID := synthesized(factory.NewIdentifier(sdkMetadataNamespace))
+	memberID := synthesized(factory.NewIdentifier("OperationMetadata"))
+	access := synthesized(factory.NewPropertyAccessExpression(
+		namespaceID,
+		nil,
+		memberID,
+		shimast.NodeFlagsNone,
+	))
+	namespaceID.Parent = access
+	memberID.Parent = access
+	argument := synthesized(factory.NewStringLiteral(metadataJSON, shimast.TokenFlagsNone))
+	call := synthesized(factory.NewCallExpression(
+		access,
+		nil,
+		nil,
+		factory.NewNodeList([]*shimast.Node{argument}),
+		shimast.NodeFlagsNone,
+	))
+	access.Parent = call
+	argument.Parent = call
+	decorator := synthesized(factory.NewDecorator(call))
+	call.Parent = decorator
+	decorator.Parent = method
+	modifiers.Nodes = append([]*shimast.Node{decorator}, modifiers.Nodes...)
+}
+
+// injectOperationMetadataImport prepends a synthesized
+// `import * as __OperationMetadata from "@nestia/sdk"` to a touched file.
+func injectOperationMetadataImport(
+	factory *shimast.NodeFactory,
+	file *shimast.SourceFile,
+) {
+	if file == nil || file.Statements == nil {
+		return
+	}
+	namespaceID := synthesized(factory.NewIdentifier(sdkMetadataNamespace))
+	namespace := synthesized(factory.NewNamespaceImport(namespaceID))
+	namespaceID.Parent = namespace
+	clause := synthesized(factory.NewImportClause(shimast.KindUnknown, nil, namespace))
+	namespace.Parent = clause
+	specifier := synthesized(factory.NewStringLiteral("@nestia/sdk", shimast.TokenFlagsNone))
+	declaration := synthesized(factory.NewImportDeclaration(nil, clause, specifier, nil))
+	clause.Parent = declaration
+	specifier.Parent = declaration
+	declaration.Parent = file.AsNode()
+	file.Statements.Nodes = append([]*shimast.Node{declaration}, file.Statements.Nodes...)
+}

package/native/sdk/sdk.go

@@ -0,0 +1,17 @@
+// Package sdk implements the `@nestia/sdk` ttsc transform plugin: it injects
+// the `@OperationMetadata({...})` decorator the SDK / Swagger / e2e generators
+// read at runtime. It is a separate plugin from `@nestia/core` so that a
+// project depending only on `@nestia/core` never compiles this code — see
+// `packages/core/native/transform` for the shared transform infrastructure
+// this package imports.
+package sdk
+
+import (
+	"io"
+	"os"
+)
+
+var (
+	stdout io.Writer = os.Stdout
+	stderr io.Writer = os.Stderr
+)

package/native/sdk/sdk_metadata_json.go

@@ -0,0 +1,327 @@
+package sdk
+
+import schemametadata "github.com/samchon/typia/packages/typia/native/core/schemas/metadata"
+
+func nestiaSDKMetadataComponentsLiteral(
+	components schemametadata.IMetadataComponents,
+) map[string]any {
+	return map[string]any{
+		"objects": nestiaSDKMetadataObjectTypes(components.Objects),
+		"aliases": nestiaSDKMetadataAliasTypes(components.Aliases),
+		"arrays":  nestiaSDKMetadataArrayTypes(components.Arrays),
+		"tuples":  nestiaSDKMetadataTupleTypes(components.Tuples),
+	}
+}
+
+func nestiaSDKMetadataSchemaLiteral(meta *schemametadata.IMetadataSchema) any {
+	if meta == nil {
+		return nestiaSDKLiteralNull
+	}
+	return map[string]any{
+		"any":       meta.Any,
+		"required":  meta.Required,
+		"optional":  meta.Optional,
+		"nullable":  meta.Nullable,
+		"functions": nestiaSDKMetadataFunctions(meta.Functions),
+		"atomics":   nestiaSDKMetadataAtomics(meta.Atomics),
+		"constants": nestiaSDKMetadataConstants(meta.Constants),
+		"templates": nestiaSDKMetadataTemplates(meta.Templates),
+		"escaped":   nestiaSDKMetadataEscaped(meta.Escaped),
+		"rest":      nestiaSDKMetadataSchemaLiteral(meta.Rest),
+		"arrays":    nestiaSDKMetadataReferences(meta.Arrays),
+		"tuples":    nestiaSDKMetadataReferences(meta.Tuples),
+		"objects":   nestiaSDKMetadataReferences(meta.Objects),
+		"aliases":   nestiaSDKMetadataReferences(meta.Aliases),
+		"natives":   nestiaSDKMetadataReferences(meta.Natives),
+		"sets":      nestiaSDKMetadataSets(meta.Sets),
+		"maps":      nestiaSDKMetadataMaps(meta.Maps),
+	}
+}
+
+func nestiaSDKMetadataFunctions(
+	input []*schemametadata.IMetadataSchema_IFunction,
+) []any {
+	output := []any{}
+	for _, fn := range input {
+		if fn == nil {
+			continue
+		}
+		output = append(output, map[string]any{
+			"parameters": nestiaSDKMetadataParameters(fn.Parameters),
+			"output":     nestiaSDKMetadataSchemaLiteral(fn.Output),
+			"async":      fn.Async,
+		})
+	}
+	return output
+}
+
+func nestiaSDKMetadataParameters(
+	input []*schemametadata.IMetadataSchema_IParameter,
+) []any {
+	output := []any{}
+	for _, param := range input {
+		if param == nil {
+			continue
+		}
+		output = append(output, map[string]any{
+			"name":        param.Name,
+			"type":        nestiaSDKMetadataSchemaLiteral(param.Type),
+			"description": nestiaSDKOptionalString(param.Description),
+			"jsDocTags":   nestiaSDKJSDocTags(param.JsDocTags),
+		})
+	}
+	return output
+}
+
+func nestiaSDKMetadataAtomics(
+	input []schemametadata.IMetadataSchema_IAtomic,
+) []any {
+	output := []any{}
+	for _, atomic := range input {
+		output = append(output, map[string]any{
+			"type": atomic.Type,
+			"tags": nestiaSDKMetadataTagMatrix(atomic.Tags),
+		})
+	}
+	return output
+}
+
+func nestiaSDKMetadataConstants(
+	input []schemametadata.IMetadataSchema_IConstant,
+) []any {
+	output := []any{}
+	for _, constant := range input {
+		values := []any{}
+		for _, value := range constant.Values {
+			values = append(values, map[string]any{
+				"value":       value.Value,
+				"tags":        nestiaSDKMetadataTagMatrix(value.Tags),
+				"description": nestiaSDKOptionalString(value.Description),
+				"jsDocTags":   nestiaSDKJSDocTags(value.JsDocTags),
+			})
+		}
+		output = append(output, map[string]any{
+			"type":   constant.Type,
+			"values": values,
+		})
+	}
+	return output
+}
+
+func nestiaSDKMetadataTemplates(
+	input []schemametadata.IMetadataSchema_ITemplate,
+) []any {
+	output := []any{}
+	for _, template := range input {
+		row := []any{}
+		for _, child := range template.Row {
+			row = append(row, nestiaSDKMetadataSchemaLiteral(child))
+		}
+		output = append(output, map[string]any{
+			"row":  row,
+			"tags": nestiaSDKMetadataTagMatrix(template.Tags),
+		})
+	}
+	return output
+}
+
+func nestiaSDKMetadataEscaped(
+	input *schemametadata.IMetadataSchema_IEscaped,
+) any {
+	if input == nil {
+		return nestiaSDKLiteralNull
+	}
+	return map[string]any{
+		"original": nestiaSDKMetadataSchemaLiteral(input.Original),
+		"returns":  nestiaSDKMetadataSchemaLiteral(input.Returns),
+	}
+}
+
+func nestiaSDKMetadataReferences(
+	input []schemametadata.IMetadataSchema_IReference,
+) []any {
+	output := []any{}
+	for _, ref := range input {
+		output = append(output, map[string]any{
+			"name": ref.Name,
+			"tags": nestiaSDKMetadataTagMatrix(ref.Tags),
+		})
+	}
+	return output
+}
+
+func nestiaSDKMetadataSets(input []schemametadata.IMetadataSchema_ISet) []any {
+	output := []any{}
+	for _, set := range input {
+		output = append(output, map[string]any{
+			"value": nestiaSDKMetadataSchemaLiteral(set.Value),
+			"tags":  nestiaSDKMetadataTagMatrix(set.Tags),
+		})
+	}
+	return output
+}
+
+func nestiaSDKMetadataMaps(input []schemametadata.IMetadataSchema_IMap) []any {
+	output := []any{}
+	for _, entry := range input {
+		output = append(output, map[string]any{
+			"key":   nestiaSDKMetadataSchemaLiteral(entry.Key),
+			"value": nestiaSDKMetadataSchemaLiteral(entry.Value),
+			"tags":  nestiaSDKMetadataTagMatrix(entry.Tags),
+		})
+	}
+	return output
+}
+
+func nestiaSDKMetadataObjectTypes(
+	input []schemametadata.IMetadataSchema_IObjectType,
+) []any {
+	output := []any{}
+	for _, object := range input {
+		properties := []any{}
+		for _, property := range object.Properties {
+			if property == nil {
+				continue
+			}
+			properties = append(properties, map[string]any{
+				"key":         nestiaSDKMetadataSchemaLiteral(property.Key),
+				"value":       nestiaSDKMetadataSchemaLiteral(property.Value),
+				"description": nestiaSDKOptionalString(property.Description),
+				"jsDocTags":   nestiaSDKJSDocTags(property.JsDocTags),
+				"mutability":  nestiaSDKOptionalString(property.Mutability),
+			})
+		}
+		output = append(output, map[string]any{
+			"name":        object.Name,
+			"properties":  properties,
+			"description": nestiaSDKOptionalString(object.Description),
+			"jsDocTags":   nestiaSDKJSDocTags(object.JsDocTags),
+			"index":       object.Index,
+			"recursive":   object.Recursive,
+			"nullables":   nestiaSDKBoolArray(object.Nullables),
+		})
+	}
+	return output
+}
+
+func nestiaSDKMetadataAliasTypes(
+	input []schemametadata.IMetadataSchema_IAliasType,
+) []any {
+	output := []any{}
+	for _, alias := range input {
+		output = append(output, map[string]any{
+			"name":        alias.Name,
+			"value":       nestiaSDKMetadataSchemaLiteral(alias.Value),
+			"description": nestiaSDKOptionalString(alias.Description),
+			"jsDocTags":   nestiaSDKJSDocTags(alias.JsDocTags),
+			"recursive":   alias.Recursive,
+			"nullables":   nestiaSDKBoolArray(alias.Nullables),
+		})
+	}
+	return output
+}
+
+func nestiaSDKMetadataArrayTypes(
+	input []schemametadata.IMetadataSchema_IArrayType,
+) []any {
+	output := []any{}
+	for _, array := range input {
+		output = append(output, map[string]any{
+			"name":      array.Name,
+			"value":     nestiaSDKMetadataSchemaLiteral(array.Value),
+			"nullables": nestiaSDKBoolArray(array.Nullables),
+			"recursive": array.Recursive,
+			"index":     nestiaSDKOptionalInt(array.Index),
+		})
+	}
+	return output
+}
+
+func nestiaSDKMetadataTupleTypes(
+	input []schemametadata.IMetadataSchema_ITupleType,
+) []any {
+	output := []any{}
+	for _, tuple := range input {
+		elements := []any{}
+		for _, elem := range tuple.Elements {
+			elements = append(elements, nestiaSDKMetadataSchemaLiteral(elem))
+		}
+		output = append(output, map[string]any{
+			"name":      tuple.Name,
+			"elements":  elements,
+			"index":     nestiaSDKOptionalInt(tuple.Index),
+			"recursive": tuple.Recursive,
+			"nullables": nestiaSDKBoolArray(tuple.Nullables),
+		})
+	}
+	return output
+}
+
+func nestiaSDKMetadataTagMatrix(
+	input [][]schemametadata.IMetadataTypeTag,
+) []any {
+	output := []any{}
+	for _, row := range input {
+		items := []any{}
+		for _, tag := range row {
+			items = append(items, nestiaSDKMetadataTypeTag(tag))
+		}
+		output = append(output, items)
+	}
+	return output
+}
+
+func nestiaSDKMetadataTypeTag(tag schemametadata.IMetadataTypeTag) map[string]any {
+	output := map[string]any{
+		"target":    tag.Target,
+		"name":      tag.Name,
+		"kind":      tag.Kind,
+		"exclusive": tag.Exclusive,
+		"value":     tag.Value,
+		"schema":    tag.Schema,
+	}
+	if tag.Validate != "" {
+		output["validate"] = tag.Validate
+	}
+	return output
+}
+
+func nestiaSDKJSDocTags(input []schemametadata.IJsDocTagInfo) []any {
+	output := []any{}
+	for _, tag := range input {
+		text := []any{}
+		for _, item := range tag.Text {
+			text = append(text, map[string]any{
+				"text": item.Text,
+				"kind": item.Kind,
+			})
+		}
+		output = append(output, map[string]any{
+			"name": tag.Name,
+			"text": text,
+		})
+	}
+	return output
+}
+
+func nestiaSDKBoolArray(input []bool) []any {
+	output := []any{}
+	for _, value := range input {
+		output = append(output, value)
+	}
+	return output
+}
+
+func nestiaSDKOptionalString(input *string) any {
+	if input == nil {
+		return nestiaSDKLiteralNull
+	}
+	return *input
+}
+
+func nestiaSDKOptionalInt(input *int) any {
+	if input == nil {
+		return nestiaSDKLiteralNull
+	}
+	return *input
+}