@nestia/sdk 14.0.1 → 14.0.3

package/lib/analyses/TypedMcpRouteAnalyzer.js

@@ -1,28 +1,160 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TypedMcpRouteAnalyzer = void 0;
+const legacy_1 = require("../internal/legacy");
+/**
+ * Turns a reflected MCP operation into a typed route.
+ *
+ * @evidence contracts/common.md#principled-implementation An MCP tool is one route whose accessor is `mcp` and the tool name with non-identifier characters replaced.
+ * @evidence contracts/common.md#clear-and-simple-design One function.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The accessor rule is generic.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ * efficient algorithms: The namespace groups declarations; analyze owns graph conversion.
+ * reuse equivalent work: The namespace coordinates no computation.
+ * bound retention and release resources: The namespace owns no retained state or handles.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation TypedMcpRouteAnalyzer analyzes reflected route metadata; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+ */
 var TypedMcpRouteAnalyzer;
 (function (TypedMcpRouteAnalyzer) {
-    TypedMcpRouteAnalyzer.analyze = (props) => { var _a; return [
-        {
-            protocol: "mcp",
-            controller: props.controller,
-            name: props.operation.name,
-            toolName: props.operation.toolName,
-            title: props.operation.title,
-            toolDescription: props.operation.toolDescription,
-            accessor: accessor(props.operation.toolName),
-            function: props.operation.function,
-            input: (_a = props.operation.parameters[0]) !== null && _a !== void 0 ? _a : null,
-            returnType: props.operation.returnType,
-            inputSchema: props.operation.inputSchema,
-            outputSchema: props.operation.outputSchema,
-            annotations: props.operation.annotations,
-            imports: props.operation.imports,
-            description: props.operation.description,
-            jsDocTags: props.operation.jsDocTags,
-        },
-    ]; };
+    /**
+     * Returns the typed route of an MCP tool: its names, schemas, input
+     * parameter, return type, and imports. Clone mode resolves a private copy of
+     * the native JSON graph and reports missing or unresolved components.
+     *
+     * @evidence contracts/common.md#principled-implementation Native primitive pipes describe the same JSON wire values the MCP adaptor serializes. Clone requests require these graphs; source-only routes preserve their declared types and imports.
+     * @evidence contracts/common.md#clear-and-simple-design One conversion resolves the input and output against their own components and reports clone metadata failures at the route.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Native JSON pipes are resolved through the shared metadata adapter; source binding names never select a clone exception and native records remain unchanged.
+     * @evidence contracts/common.md#meaningful-documentation The comment states the result.
+     * efficient algorithms: Clone mode copies each supplied graph payload once, indexes its components and visits each schema and component target once to check reference closure. Work scales with graph vertices, edges and annotation payload; no compiler or type analysis is repeated.
+     * reuse equivalent work: Input and output pipes have independent native component identities, and this operation retains no completed or in-flight request to share across analyses.
+     * bound retention and release resources: Resolution copies and visited sets belong to one synchronous conversion; the returned route retains its reachable graphs, and no global cache, process or handle is created.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation TypedMcpRouteAnalyzer.analyze analyzes reflected route metadata; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+     */
+    TypedMcpRouteAnalyzer.analyze = (props) => {
+        const errors = [];
+        const cast = (pipe, position) => {
+            if (props.clone !== true)
+                return undefined;
+            if (pipe === undefined) {
+                errors.push(`Missing native JSON metadata for MCP ${position}.`);
+                return undefined;
+            }
+            if (pipe.success === false) {
+                errors.push(...pipe.errors);
+                return undefined;
+            }
+            try {
+                const data = structuredClone(pipe.data);
+                const components = legacy_1.MetadataComponents.from(data.components);
+                const metadata = legacy_1.MetadataSchema.from(data.metadata, components.dictionary);
+                const visited = new WeakSet();
+                const inspect = (value) => {
+                    var _a;
+                    if (visited.has(value))
+                        return;
+                    visited.add(value);
+                    for (const kind of [
+                        "objects",
+                        "aliases",
+                        "arrays",
+                        "tuples",
+                    ]) {
+                        if (!Array.isArray(value[kind]))
+                            throw new Error(`Missing ${kind} metadata.`);
+                        for (const reference of value[kind]) {
+                            const target = reference.type;
+                            if (target === undefined)
+                                throw new Error(`Unresolved ${kind} component ${reference.name}.`);
+                            if (visited.has(target))
+                                continue;
+                            visited.add(target);
+                            if (kind === "objects")
+                                for (const property of target
+                                    .properties) {
+                                    inspect(property.key);
+                                    inspect(property.value);
+                                }
+                            else if (kind === "tuples")
+                                for (const element of target.elements)
+                                    inspect(element);
+                            else
+                                inspect(target.value);
+                        }
+                    }
+                    if (value.rest)
+                        inspect(value.rest);
+                    if (value.escaped) {
+                        inspect(value.escaped.original);
+                        inspect(value.escaped.returns);
+                    }
+                    for (const template of value.templates)
+                        for (const element of (_a = template.row) !== null && _a !== void 0 ? _a : template)
+                            inspect(element);
+                    for (const set of value.sets)
+                        inspect(set.value);
+                    for (const map of value.maps) {
+                        inspect(map.key);
+                        inspect(map.value);
+                    }
+                    for (const fn of value.functions) {
+                        for (const parameter of fn.parameters)
+                            inspect(parameter.type);
+                        inspect(fn.output);
+                    }
+                };
+                if (!Array.isArray(metadata.objects))
+                    throw new Error("Missing schema metadata.");
+                inspect(metadata);
+                return metadata;
+            }
+            catch (error) {
+                errors.push(`Invalid native JSON metadata for MCP ${position}: ${String(error)}`);
+                return undefined;
+            }
+        };
+        const inputMetadata = props.operation.parameters[0]
+            ? cast(props.operation.parameters[0].metadata, "input")
+            : undefined;
+        const outputMetadata = cast(props.operation.returnMetadata, "output");
+        if (errors.length) {
+            const failure = {
+                file: props.controller.file,
+                class: props.controller.class.name,
+                function: props.operation.name,
+                from: props.operation.name,
+                contents: errors,
+            };
+            if (props.errors === undefined)
+                throw new Error(errors
+                    .map((e) => (typeof e === "string" ? e : e.messages.join("; ")))
+                    .join("\n"));
+            props.errors.push(failure);
+            return [];
+        }
+        return [
+            {
+                protocol: "mcp",
+                controller: props.controller,
+                name: props.operation.name,
+                toolName: props.operation.toolName,
+                title: props.operation.title,
+                toolDescription: props.operation.toolDescription,
+                accessor: accessor(props.operation.toolName),
+                function: props.operation.function,
+                input: props.operation.parameters[0]
+                    ? Object.assign(Object.assign({}, props.operation.parameters[0]), { type: Object.assign({}, props.operation.parameters[0].type) }) : null,
+                returnType: props.operation.returnType,
+                inputMetadata,
+                outputMetadata,
+                inputSchema: props.operation.inputSchema,
+                outputSchema: props.operation.outputSchema,
+                annotations: props.operation.annotations,
+                imports: props.operation.imports,
+                description: props.operation.description,
+                jsDocTags: props.operation.jsDocTags,
+            },
+        ];
+    };
     const accessor = (toolName) => {
         const safe = toolName.replace(/[^A-Za-z0-9_$]/g, "_");
         return ["mcp", safe];

package/lib/analyses/TypedMcpRouteAnalyzer.js.map

@@ -1 +1 @@
-{"version":3,"file":"TypedMcpRouteAnalyzer.js","sourceRoot":"","sources":["../../src/analyses/TypedMcpRouteAnalyzer.ts"],"names":[],"mappings":";;;AAIA,IAAiB,qBAAqB,CA6BrC;AA7BD,WAAiB,qBAAqB;IACvB,6BAAO,GAAG,CAAC,KAGvB,EAAoB,EAAE,kBAAC;QACtB;YACE,QAAQ,EAAE,KAAK;YACf,UAAU,EAAE,KAAK,CAAC,UAAU;YAC5B,IAAI,EAAE,KAAK,CAAC,SAAS,CAAC,IAAI;YAC1B,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC,QAAQ;YAClC,KAAK,EAAE,KAAK,CAAC,SAAS,CAAC,KAAK;YAC5B,eAAe,EAAE,KAAK,CAAC,SAAS,CAAC,eAAe;YAChD,QAAQ,EAAE,QAAQ,CAAC,KAAK,CAAC,SAAS,CAAC,QAAQ,CAAC;YAC5C,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC,QAAQ;YAClC,KAAK,QAAE,KAAK,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC,CAAC,mCAAI,IAAI;YAC5C,UAAU,EAAE,KAAK,CAAC,SAAS,CAAC,UAAU;YACtC,WAAW,EAAE,KAAK,CAAC,SAAS,CAAC,WAAW;YACxC,YAAY,EAAE,KAAK,CAAC,SAAS,CAAC,YAAY;YAC1C,WAAW,EAAE,KAAK,CAAC,SAAS,CAAC,WAAW;YACxC,OAAO,EAAE,KAAK,CAAC,SAAS,CAAC,OAAO;YAChC,WAAW,EAAE,KAAK,CAAC,SAAS,CAAC,WAAW;YACxC,SAAS,EAAE,KAAK,CAAC,SAAS,CAAC,SAAS;SACrC;KACF,GAAA,CAAC;IAEF,MAAM,QAAQ,GAAG,CAAC,QAAgB,EAAY,EAAE;QAC9C,MAAM,IAAI,GAAG,QAAQ,CAAC,OAAO,CAAC,iBAAiB,EAAE,GAAG,CAAC,CAAC;QACtD,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IACvB,CAAC,CAAC;AACJ,CAAC,EA7BgB,qBAAqB,aAArB,qBAAqB,GAArB,qBAAqB,QA6BrC"}
+{"version":3,"file":"TypedMcpRouteAnalyzer.js","sourceRoot":"","sources":["../../src/analyses/TypedMcpRouteAnalyzer.ts"],"names":[],"mappings":"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"}

package/lib/analyses/TypedWebSocketRouteAnalyzer.d.ts

@@ -1,7 +1,26 @@
 import { IReflectController } from "../structures/IReflectController";
 import { IReflectWebSocketOperation } from "../structures/IReflectWebSocketOperation";
 import { ITypedWebSocketRoute } from "../structures/ITypedWebSocketRoute";
+/**
+ * Turns a reflected WebSocket operation into typed routes, one per path.
+ *
+ * @evidence contracts/common.md#principled-implementation Each path gets an accessor from its segments and the method name, and the parameters are split by category.
+ * @evidence contracts/common.md#clear-and-simple-design One function.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The accessor rule is generic.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation TypedWebSocketRouteAnalyzer analyzes reflected route metadata; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+ */
 export declare namespace TypedWebSocketRouteAnalyzer {
+    /**
+     * Returns one typed WebSocket route per path, with the header, path
+     * parameters, query, acceptor, and driver separated.
+     *
+     * @evidence contracts/common.md#principled-implementation The parameters are filtered by category, the acceptor is required by the reflection, and the accessor combines the path segments and the method name.
+     * @evidence contracts/common.md#clear-and-simple-design One mapping.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts It only reorganizes reflected data.
+     * @evidence contracts/common.md#meaningful-documentation The comment states the result.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation TypedWebSocketRouteAnalyzer.analyze analyzes reflected route metadata; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+     */
     const analyze: (props: {
         controller: IReflectController;
         operation: IReflectWebSocketOperation;

package/lib/analyses/TypedWebSocketRouteAnalyzer.js

@@ -2,8 +2,27 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TypedWebSocketRouteAnalyzer = void 0;
 const PathUtil_1 = require("../utils/PathUtil");
+/**
+ * Turns a reflected WebSocket operation into typed routes, one per path.
+ *
+ * @evidence contracts/common.md#principled-implementation Each path gets an accessor from its segments and the method name, and the parameters are split by category.
+ * @evidence contracts/common.md#clear-and-simple-design One function.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The accessor rule is generic.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation TypedWebSocketRouteAnalyzer analyzes reflected route metadata; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+ */
 var TypedWebSocketRouteAnalyzer;
 (function (TypedWebSocketRouteAnalyzer) {
+    /**
+     * Returns one typed WebSocket route per path, with the header, path
+     * parameters, query, acceptor, and driver separated.
+     *
+     * @evidence contracts/common.md#principled-implementation The parameters are filtered by category, the acceptor is required by the reflection, and the accessor combines the path segments and the method name.
+     * @evidence contracts/common.md#clear-and-simple-design One mapping.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts It only reorganizes reflected data.
+     * @evidence contracts/common.md#meaningful-documentation The comment states the result.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation TypedWebSocketRouteAnalyzer.analyze analyzes reflected route metadata; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+     */
     TypedWebSocketRouteAnalyzer.analyze = (props) => props.paths.map((path) => { var _a, _b, _c; return (Object.assign(Object.assign({}, props.operation), { controller: props.controller, key: props.operation.name, path, accessor: [...PathUtil_1.PathUtil.accessors(path), props.operation.name], header: (_a = props.operation.parameters.filter((p) => p.category === "header")[0]) !== null && _a !== void 0 ? _a : null, pathParameters: props.operation.parameters.filter((p) => p.category === "param"), query: (_b = props.operation.parameters.filter((p) => p.category === "query")[0]) !== null && _b !== void 0 ? _b : null, acceptor: props.operation.parameters.filter((p) => p.category === "acceptor")[0], driver: (_c = props.operation.parameters.filter((p) => p.category === "driver")[0]) !== null && _c !== void 0 ? _c : null })); });
 })(TypedWebSocketRouteAnalyzer || (exports.TypedWebSocketRouteAnalyzer = TypedWebSocketRouteAnalyzer = {}));
 //# sourceMappingURL=TypedWebSocketRouteAnalyzer.js.map

package/lib/analyses/TypedWebSocketRouteAnalyzer.js.map

@@ -1 +1 @@
-{"version":3,"file":"TypedWebSocketRouteAnalyzer.js","sourceRoot":"","sources":["../../src/analyses/TypedWebSocketRouteAnalyzer.ts"],"names":[],"mappings":";;;AAGA,gDAA6C;AAE7C,IAAiB,2BAA2B,CA4B3C;AA5BD,WAAiB,2BAA2B;IAC7B,mCAAO,GAAG,CAAC,KAIvB,EAA0B,EAAE,CAC3B,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,0BAAC,iCACrB,KAAK,CAAC,SAAS,KAClB,UAAU,EAAE,KAAK,CAAC,UAAU,EAC5B,GAAG,EAAE,KAAK,CAAC,SAAS,CAAC,IAAI,EACzB,IAAI,EACJ,QAAQ,EAAE,CAAC,GAAG,mBAAQ,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,EAC7D,MAAM,QACJ,KAAK,CAAC,SAAS,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,mCACpE,IAAI,EACN,cAAc,EAAE,KAAK,CAAC,SAAS,CAAC,UAAU,CAAC,MAAM,CAC/C,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,OAAO,CAC9B,EACD,KAAK,QACH,KAAK,CAAC,SAAS,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC,mCACnE,IAAI,EACN,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC,UAAU,CAAC,MAAM,CACzC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,UAAU,CACjC,CAAC,CAAC,CAAE,EACL,MAAM,QACJ,KAAK,CAAC,SAAS,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,mCACpE,IAAI,IACN,GAAA,CAAC,CAAC;AACR,CAAC,EA5BgB,2BAA2B,aAA3B,2BAA2B,GAA3B,2BAA2B,QA4B3C"}
+{"version":3,"file":"TypedWebSocketRouteAnalyzer.js","sourceRoot":"","sources":["../../src/analyses/TypedWebSocketRouteAnalyzer.ts"],"names":[],"mappings":";;;AAGA,gDAA6C;AAE7C;;;;;;;;GAQG;AACH,IAAiB,2BAA2B,CAsC3C;AAtCD,WAAiB,2BAA2B;IAC1C;;;;;;;;;OASG;IACU,mCAAO,GAAG,CAAC,KAIvB,EAA0B,EAAE,CAC3B,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,0BAAC,iCACrB,KAAK,CAAC,SAAS,KAClB,UAAU,EAAE,KAAK,CAAC,UAAU,EAC5B,GAAG,EAAE,KAAK,CAAC,SAAS,CAAC,IAAI,EACzB,IAAI,EACJ,QAAQ,EAAE,CAAC,GAAG,mBAAQ,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,EAC7D,MAAM,QACJ,KAAK,CAAC,SAAS,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,mCACpE,IAAI,EACN,cAAc,EAAE,KAAK,CAAC,SAAS,CAAC,UAAU,CAAC,MAAM,CAC/C,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,OAAO,CAC9B,EACD,KAAK,QACH,KAAK,CAAC,SAAS,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC,mCACnE,IAAI,EACN,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC,UAAU,CAAC,MAAM,CACzC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,UAAU,CACjC,CAAC,CAAC,CAAE,EACL,MAAM,QACJ,KAAK,CAAC,SAAS,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,mCACpE,IAAI,IACN,GAAA,CAAC,CAAC;AACR,CAAC,EAtCgB,2BAA2B,aAA3B,2BAA2B,GAA3B,2BAA2B,QAsC3C"}

package/lib/decorators/OperationMetadata.d.ts

@@ -8,5 +8,11 @@ import { IOperationMetadata } from "../structures/IOperationMetadata";
  * object literal — keeping the constructed node tree minimal. The string is
  * parsed once here at module-evaluation time. A pre-parsed `IOperationMetadata`
  * object is still accepted for hand-written or test usage.
+ *
+ * @evidence contracts/common.md#principled-implementation The metadata is defined on the class prototype and property key, from an object or its JSON text, which is the key the reflection analyzers look up.
+ * @evidence contracts/common.md#clear-and-simple-design One decorator that parses when given text and defines one metadata entry.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts It only records what the transform computed and does not alter the method.
+ * @evidence contracts/common.md#meaningful-documentation The comment states who emits and who reads the metadata.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation OperationMetadata attaches metadata through Reflect.defineMetadata; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
  */
 export declare function OperationMetadata(metadata: IOperationMetadata | string): MethodDecorator;

package/lib/decorators/OperationMetadata.js

@@ -10,6 +10,12 @@ exports.OperationMetadata = OperationMetadata;
  * object literal — keeping the constructed node tree minimal. The string is
  * parsed once here at module-evaluation time. A pre-parsed `IOperationMetadata`
  * object is still accepted for hand-written or test usage.
+ *
+ * @evidence contracts/common.md#principled-implementation The metadata is defined on the class prototype and property key, from an object or its JSON text, which is the key the reflection analyzers look up.
+ * @evidence contracts/common.md#clear-and-simple-design One decorator that parses when given text and defines one metadata entry.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts It only records what the transform computed and does not alter the method.
+ * @evidence contracts/common.md#meaningful-documentation The comment states who emits and who reads the metadata.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation OperationMetadata attaches metadata through Reflect.defineMetadata; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
  */
 function OperationMetadata(metadata) {
     const parsed = typeof metadata === "string"

package/lib/decorators/OperationMetadata.js.map

@@ -1 +1 @@
-{"version":3,"file":"OperationMetadata.js","sourceRoot":"","sources":["../../src/decorators/OperationMetadata.ts"],"names":[],"mappings":";;;AAEA;;;;;;;;;GASG;AACH,2BACE,QAAqC;IAErC,MAAM,MAAM,GACV,OAAO,QAAQ,KAAK,QAAQ;QAC1B,CAAC,CAAE,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAwB;QAC9C,CAAC,CAAC,QAAQ,CAAC;IACf,OAAO,SAAS,iBAAiB,CAAC,MAAM,EAAE,WAAW,EAAE,UAAU;QAC/D,OAAO,CAAC,cAAc,CACpB,0BAA0B,EAC1B,MAAM,EACN,MAAM,EACN,WAAW,CACZ,CAAC;QACF,OAAO,UAAU,CAAC;IACpB,CAAC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"OperationMetadata.js","sourceRoot":"","sources":["../../src/decorators/OperationMetadata.ts"],"names":[],"mappings":";;;AAEA;;;;;;;;;;;;;;;GAeG;AACH,2BACE,QAAqC;IAErC,MAAM,MAAM,GACV,OAAO,QAAQ,KAAK,QAAQ;QAC1B,CAAC,CAAE,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAwB;QAC9C,CAAC,CAAC,QAAQ,CAAC;IACf,OAAO,SAAS,iBAAiB,CAAC,MAAM,EAAE,WAAW,EAAE,UAAU;QAC/D,OAAO,CAAC,cAAc,CACpB,0BAA0B,EAC1B,MAAM,EACN,MAAM,EACN,WAAW,CACZ,CAAC;QACF,OAAO,UAAU,CAAC;IACpB,CAAC,CAAC;AACJ,CAAC"}

package/lib/executable/internal/CommandParser.d.ts

@@ -1,3 +1,22 @@
+/**
+ * Parses the command-line flags of the `nestia` command.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace reads `--key value` pairs from an argument list.
+ * @evidence contracts/common.md#clear-and-simple-design One function.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a plain parser.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation CommandParser parses supplied argument strings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+ */
 export declare namespace CommandParser {
+    /**
+     * Returns the `--key value` pairs of an argument list as an object; a flag
+     * without a value, or followed by another flag, is left out.
+     *
+     * @evidence contracts/common.md#principled-implementation Each argument that starts with two dashes is a key, and the next argument is its value only when it exists and is not itself a flag.
+     * @evidence contracts/common.md#clear-and-simple-design One loop.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts It applies to every argument.
+     * @evidence contracts/common.md#meaningful-documentation The comment states the omitted flags.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation CommandParser.parse parses supplied argument strings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+     */
     function parse(argList: string[]): Record<string, string>;
 }

package/lib/executable/internal/CommandParser.js

@@ -1,8 +1,27 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CommandParser = void 0;
+/**
+ * Parses the command-line flags of the `nestia` command.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace reads `--key value` pairs from an argument list.
+ * @evidence contracts/common.md#clear-and-simple-design One function.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a plain parser.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation CommandParser parses supplied argument strings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+ */
 var CommandParser;
 (function (CommandParser) {
+    /**
+     * Returns the `--key value` pairs of an argument list as an object; a flag
+     * without a value, or followed by another flag, is left out.
+     *
+     * @evidence contracts/common.md#principled-implementation Each argument that starts with two dashes is a key, and the next argument is its value only when it exists and is not itself a flag.
+     * @evidence contracts/common.md#clear-and-simple-design One loop.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts It applies to every argument.
+     * @evidence contracts/common.md#meaningful-documentation The comment states the omitted flags.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation CommandParser.parse parses supplied argument strings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+     */
     function parse(argList) {
         const output = {};
         argList.forEach((arg, i) => {

package/lib/executable/internal/CommandParser.js.map

@@ -1 +1 @@
-{"version":3,"file":"CommandParser.js","sourceRoot":"","sources":["../../../src/executable/internal/CommandParser.ts"],"names":[],"mappings":";;;AAAA,IAAiB,aAAa,CAc7B;AAdD,WAAiB,aAAa;IAC5B,SAAgB,KAAK,CAAC,OAAiB;QACrC,MAAM,MAAM,GAA2B,EAAE,CAAC;QAC1C,OAAO,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE;YACzB,IAAI,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,KAAK,KAAK;gBAAE,OAAO;YAE3C,MAAM,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YACzB,MAAM,KAAK,GAAuB,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;YACjD,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC;gBAAE,OAAO;YAE1D,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;QACtB,CAAC,CAAC,CAAC;QACH,OAAO,MAAM,CAAC;IAChB,CAAC;IAZe,cAAA,KAAK,QAYpB,CAAA;AACH,CAAC,EAdgB,aAAa,aAAb,aAAa,GAAb,aAAa,QAc7B"}
+{"version":3,"file":"CommandParser.js","sourceRoot":"","sources":["../../../src/executable/internal/CommandParser.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;GAQG;AACH,IAAiB,aAAa,CAwB7B;AAxBD,WAAiB,aAAa;IAC5B;;;;;;;;;OASG;IACH,SAAgB,KAAK,CAAC,OAAiB;QACrC,MAAM,MAAM,GAA2B,EAAE,CAAC;QAC1C,OAAO,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE;YACzB,IAAI,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,KAAK,KAAK;gBAAE,OAAO;YAE3C,MAAM,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YACzB,MAAM,KAAK,GAAuB,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;YACjD,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC;gBAAE,OAAO;YAE1D,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;QACtB,CAAC,CAAC,CAAC;QACH,OAAO,MAAM,CAAC;IAChB,CAAC;IAZe,cAAA,KAAK,QAYpB,CAAA;AACH,CAAC,EAxBgB,aAAa,aAAb,aAAa,GAAb,aAAa,QAwB7B"}

package/lib/executable/internal/NestiaConfigLoader.d.ts

@@ -1,10 +1,66 @@
 import { INestiaConfig } from "../../INestiaConfig";
+/**
+ * Loads the TypeScript configuration of a project and its `nestia.config.ts`.
+ *
+ * @evidence contracts/common.md#principled-implementation The project file is found and merged with its `extends` chain, and the configuration is compiled through ttsc with the nestia plugin into a temporary directory, imported, and validated by type checks of the input, the scalar options and the swagger options; the swagger `info`, `servers`, `security` and `tags` values are passed on unchecked.
+ * @evidence contracts/common.md#clear-and-simple-design Two public functions with private helpers for the temporary roots, the plugin list, and the validation.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Only this process's unique materializations are removed on exit and handled termination signals; shared cache parents and other processes' children remain, and a compile error is reported with the compiler output.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ * efficient algorithms: Project inheritance delegates one per-read traversal to TsConfigReader; configuration loading compiles one wrapper project, patches emitted JavaScript once and validates each returned config.
+ * reuse equivalent work: This invocation computes its own result and coordinates no completed or in-flight computation across requests.
+ * bound retention and release resources: Wrapper project directories are removed in finally after compilation. Emitted output remains owned by the temporary registry until generation cleanup or process termination; imported module loader entries live in that process. A CLI watch child ends after each generation, whereas direct callers retain loaded exports and have no module-unload guarantee.
+ * @evidence contracts/portability.md#os-neutral-implementation Native project and materialization paths use path resolution/joining and Node fs/module resolution. The ttsc executor represents platform-specific executables at its process boundary; emitted ESM imports use pathToFileURL, and filename extensions preserve .mts/.cts module format.
+ */
 export declare namespace NestiaConfigLoader {
+    /**
+     * The compiler options of a project as the loader reads them: the raw
+     * `compilerOptions` object.
+     *
+     * @evidence contracts/common.md#principled-implementation The record wraps the raw options so callers can read them without a compiler API.
+     * @evidence contracts/common.md#clear-and-simple-design A one-member record.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+     * @evidence contracts/common.md#meaningful-documentation The comment states what the type describes and the meaning of its members.
+     * efficient algorithms: The compiler-options record represents parsed values and selects no algorithm.
+     * reuse equivalent work: This record coordinates no configuration loads or shared producers.
+     * bound retention and release resources: This record owns neither materialization cleanup nor compiler tasks.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation The raw compiler option record performs no native path resolution or process launch; its loader owns those boundaries.
+     */
     interface ICompilerOptions {
         raw: {
             compilerOptions?: Record<string, any>;
         };
     }
+    /**
+     * Returns the merged compiler options of the project file, following its
+     * `extends` chain.
+     *
+     * It throws when the file cannot be found.
+     *
+     * @evidence contracts/common.md#principled-implementation The file is searched upward from the working directory when the name is relative, and `TsConfigReader` merges the chain, so the options are those the compiler would use.
+     * @evidence contracts/common.md#clear-and-simple-design One function delegating the reading.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts It reads what the compiler reads.
+     * @evidence contracts/common.md#meaningful-documentation The comment states the result and the error.
+     * efficient algorithms: Upward project search visits each ancestor directory once, and TsConfigReader shares repeated ancestors inside one read.
+     * reuse equivalent work: This invocation computes its own result and coordinates no completed or in-flight computation across requests.
+     * bound retention and release resources: This operation owns only invocation-local values, with no retained cache, handle or background task.
+     * @evidence contracts/portability.md#os-neutral-implementation Native project and materialization paths use path resolution/joining and Node fs/module resolution. The ttsc executor represents platform-specific executables at its process boundary; emitted ESM imports use pathToFileURL, and filename extensions preserve .mts/.cts module format.
+     */
     const compilerOptions: (project: string) => Promise<ICompilerOptions>;
+    /**
+     * Returns the configurations exported by a `nestia.config.ts`, validated.
+     *
+     * The file is compiled through ttsc with the nestia plugin into a temporary
+     * directory and imported; a missing file, a compile error, or an invalid
+     * field is an error.
+     *
+     * @evidence contracts/common.md#principled-implementation The wrapper project extends the user's project with emit forced on and declarations off, the typia plugin disabled and the nestia one enabled, the emitted file is patched for `import.meta.url`, and the exported value is checked for its input, scalar options and swagger options, so a malformed one is rejected before generation, while the OpenAPI `info`, `servers`, `security` and `tags` values are not inspected here.
+     * @evidence contracts/common.md#clear-and-simple-design One function over private helpers for compilation, extraction, and validation.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The shared registry removes only owned children on exit and handled termination signals, and the checks follow the `INestiaConfig` contract.
+     * @evidence contracts/common.md#meaningful-documentation The comment states the compile step and the errors.
+     * efficient algorithms: Each invocation compiles one wrapper project, traverses its emitted JavaScript once and validates each returned config and option field.
+     * reuse equivalent work: This invocation computes its own result and coordinates no completed or in-flight computation across requests.
+     * bound retention and release resources: Wrapper project directories are removed in finally after compilation. Emitted output remains owned by the temporary registry until generation cleanup or process termination; imported module loader entries live in that process. A CLI watch child ends after each generation, whereas direct callers retain loaded exports and have no module-unload guarantee.
+     * @evidence contracts/portability.md#os-neutral-implementation Native project and materialization paths use path resolution/joining and Node fs/module resolution. The ttsc executor represents platform-specific executables at its process boundary; emitted ESM imports use pathToFileURL, and filename extensions preserve .mts/.cts module format.
+     */
     const configurations: (file: string, compilerOptions: Record<string, any>) => Promise<INestiaConfig[]>;
 }

package/lib/executable/internal/NestiaConfigLoader.js

@@ -18,10 +18,38 @@ const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const url_1 = require("url");
 const EmittedJavaScriptPatcher_1 = require("../../utils/EmittedJavaScriptPatcher");
+const TemporaryDirectory_1 = require("../../utils/TemporaryDirectory");
 const TsConfigReader_1 = require("../../utils/TsConfigReader");
 const TtscExecutor_1 = require("../../utils/TtscExecutor");
+/**
+ * Loads the TypeScript configuration of a project and its `nestia.config.ts`.
+ *
+ * @evidence contracts/common.md#principled-implementation The project file is found and merged with its `extends` chain, and the configuration is compiled through ttsc with the nestia plugin into a temporary directory, imported, and validated by type checks of the input, the scalar options and the swagger options; the swagger `info`, `servers`, `security` and `tags` values are passed on unchecked.
+ * @evidence contracts/common.md#clear-and-simple-design Two public functions with private helpers for the temporary roots, the plugin list, and the validation.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Only this process's unique materializations are removed on exit and handled termination signals; shared cache parents and other processes' children remain, and a compile error is reported with the compiler output.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ * efficient algorithms: Project inheritance delegates one per-read traversal to TsConfigReader; configuration loading compiles one wrapper project, patches emitted JavaScript once and validates each returned config.
+ * reuse equivalent work: This invocation computes its own result and coordinates no completed or in-flight computation across requests.
+ * bound retention and release resources: Wrapper project directories are removed in finally after compilation. Emitted output remains owned by the temporary registry until generation cleanup or process termination; imported module loader entries live in that process. A CLI watch child ends after each generation, whereas direct callers retain loaded exports and have no module-unload guarantee.
+ * @evidence contracts/portability.md#os-neutral-implementation Native project and materialization paths use path resolution/joining and Node fs/module resolution. The ttsc executor represents platform-specific executables at its process boundary; emitted ESM imports use pathToFileURL, and filename extensions preserve .mts/.cts module format.
+ */
 var NestiaConfigLoader;
 (function (NestiaConfigLoader) {
+    /**
+     * Returns the merged compiler options of the project file, following its
+     * `extends` chain.
+     *
+     * It throws when the file cannot be found.
+     *
+     * @evidence contracts/common.md#principled-implementation The file is searched upward from the working directory when the name is relative, and `TsConfigReader` merges the chain, so the options are those the compiler would use.
+     * @evidence contracts/common.md#clear-and-simple-design One function delegating the reading.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts It reads what the compiler reads.
+     * @evidence contracts/common.md#meaningful-documentation The comment states the result and the error.
+     * efficient algorithms: Upward project search visits each ancestor directory once, and TsConfigReader shares repeated ancestors inside one read.
+     * reuse equivalent work: This invocation computes its own result and coordinates no completed or in-flight computation across requests.
+     * bound retention and release resources: This operation owns only invocation-local values, with no retained cache, handle or background task.
+     * @evidence contracts/portability.md#os-neutral-implementation Native project and materialization paths use path resolution/joining and Node fs/module resolution. The ttsc executor represents platform-specific executables at its process boundary; emitted ESM imports use pathToFileURL, and filename extensions preserve .mts/.cts module format.
+     */
     NestiaConfigLoader.compilerOptions = (project) => __awaiter(this, void 0, void 0, function* () {
         const configFileName = findConfigFile(process.cwd(), project);
         if (!configFileName)
@@ -35,6 +63,22 @@ var NestiaConfigLoader;
             },
         };
     });
+    /**
+     * Returns the configurations exported by a `nestia.config.ts`, validated.
+     *
+     * The file is compiled through ttsc with the nestia plugin into a temporary
+     * directory and imported; a missing file, a compile error, or an invalid
+     * field is an error.
+     *
+     * @evidence contracts/common.md#principled-implementation The wrapper project extends the user's project with emit forced on and declarations off, the typia plugin disabled and the nestia one enabled, the emitted file is patched for `import.meta.url`, and the exported value is checked for its input, scalar options and swagger options, so a malformed one is rejected before generation, while the OpenAPI `info`, `servers`, `security` and `tags` values are not inspected here.
+     * @evidence contracts/common.md#clear-and-simple-design One function over private helpers for compilation, extraction, and validation.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The shared registry removes only owned children on exit and handled termination signals, and the checks follow the `INestiaConfig` contract.
+     * @evidence contracts/common.md#meaningful-documentation The comment states the compile step and the errors.
+     * efficient algorithms: Each invocation compiles one wrapper project, traverses its emitted JavaScript once and validates each returned config and option field.
+     * reuse equivalent work: This invocation computes its own result and coordinates no completed or in-flight computation across requests.
+     * bound retention and release resources: Wrapper project directories are removed in finally after compilation. Emitted output remains owned by the temporary registry until generation cleanup or process termination; imported module loader entries live in that process. A CLI watch child ends after each generation, whereas direct callers retain loaded exports and have no module-unload guarantee.
+     * @evidence contracts/portability.md#os-neutral-implementation Native project and materialization paths use path resolution/joining and Node fs/module resolution. The ttsc executor represents platform-specific executables at its process boundary; emitted ESM imports use pathToFileURL, and filename extensions preserve .mts/.cts module format.
+     */
     NestiaConfigLoader.configurations = (file, compilerOptions) => __awaiter(this, void 0, void 0, function* () {
         if (fs_1.default.existsSync(path_1.default.resolve(file)) === false)
             throw new Error(`Unable to find "${file}" file.`);
@@ -52,8 +96,6 @@ var NestiaConfigLoader;
             : [instance];
         return assertConfigurations(file, configurations);
     });
-    const MATERIALIZED_ROOTS = new Set();
-    let CLEANUP_REGISTERED = false;
     const materializeConfiguration = (props) => __awaiter(this, void 0, void 0, function* () {
         var _a, _b;
         const configFile = path_1.default.resolve(props.file);
@@ -62,8 +104,8 @@ var NestiaConfigLoader;
         if (projectFile === undefined)
             throw new Error(`unable to find "${project}" file.`);
         const projectRoot = path_1.default.dirname(path_1.default.resolve(projectFile));
-        const wrapperRoot = fs_1.default.mkdtempSync(path_1.default.join(ensureMaterializedRoot(projectRoot), "tsconfig-"));
-        const outputRoot = fs_1.default.mkdtempSync(path_1.default.join(ensureMaterializedRoot(projectRoot), "run-"));
+        const wrapperRoot = TemporaryDirectory_1.TemporaryDirectory.create(materializedRoot(projectRoot), "tsconfig-");
+        const outputRoot = TemporaryDirectory_1.TemporaryDirectory.create(materializedRoot(projectRoot), "run-");
         const wrapperFile = path_1.default.join(wrapperRoot, "tsconfig.json");
         const wrapperConfig = {
             extends: projectFile,
@@ -94,7 +136,7 @@ var NestiaConfigLoader;
                 : `failed to compile "${props.file}" through ttsc (exit code ${status !== null && status !== void 0 ? status : "unknown"}). Run \`npx ttsc -p ${projectFile}\` to see the underlying diagnostics.`, { cause });
         }
         finally {
-            fs_1.default.rmSync(wrapperRoot, { force: true, recursive: true });
+            TemporaryDirectory_1.TemporaryDirectory.remove(wrapperRoot);
         }
         yield EmittedJavaScriptPatcher_1.EmittedJavaScriptPatcher.importMetaUrl(outputRoot);
         const configKey = emittedJavaScriptKey(projectRoot, configFile);
@@ -103,43 +145,7 @@ var NestiaConfigLoader;
             throw new Error(`failed to materialize "${props.file}" through ttsc native transform.`);
         return next;
     });
-    const ensureMaterializedRoot = (projectRoot) => {
-        const root = path_1.default.join(projectRoot, "node_modules", ".nestia", "config-loader");
-        fs_1.default.mkdirSync(root, { recursive: true });
-        MATERIALIZED_ROOTS.add(root);
-        if (CLEANUP_REGISTERED === false) {
-            CLEANUP_REGISTERED = true;
-            const sweep = () => {
-                for (const location of MATERIALIZED_ROOTS)
-                    fs_1.default.rmSync(location, { force: true, recursive: true });
-            };
-            process.once("exit", sweep);
-            // process.once("exit", …) does not fire on SIGINT/SIGTERM. Without
-            // these handlers a Ctrl-C during codegen leaves `run-*` and
-            // `tsconfig-*` mkdtempSync directories behind under
-            // node_modules/.nestia/config-loader/ until a subsequent clean exit.
-            // The module-level CLEANUP_REGISTERED flag above guards against
-            // re-entrancy within this module; we deliberately do NOT gate on
-            // `process.listenerCount(signal) > 0` because the parallel sweep in
-            // `ConfigAnalyzer.ensureRuntimeCleanup` (or any user-app SIGINT
-            // handler) could register first, and that gate would skip our
-            // registration — leaving MATERIALIZED_ROOTS unswept on Ctrl-C.
-            // Windows note: `process.kill(pid, "SIGINT")` calls TerminateProcess
-            // rather than re-raising; whichever module registers FIRST runs its
-            // sweep, the second is skipped, RUNTIME/MATERIALIZED cleanup is
-            // best-effort on Windows. SIGHUP is a no-op for most common code
-            // paths on Windows (Node fires it on console-close and exits within
-            // seconds).
-            const onSignal = (signal) => {
-                sweep();
-                process.kill(process.pid, signal);
-            };
-            for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) {
-                process.once(signal, onSignal);
-            }
-        }
-        return root;
-    };
+    const materializedRoot = (projectRoot) => path_1.default.join(projectRoot, "node_modules", ".nestia", "config-loader");
     const emittedJavaScriptKey = (projectRoot, file) => {
         const relative = path_1.default.relative(projectRoot, file);
         const extension = path_1.default.extname(relative).toLowerCase();