@nestia/sdk 14.0.0 → 14.0.2

package/lib/utils/TsConfigReader.js

@@ -15,24 +15,76 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.TsConfigReader = void 0;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
+/**
+ * Reads a tsconfig with its `extends` chain without the compiler API.
+ *
+ * Later bases override earlier bases, including shared ancestors. Circular
+ * inheritance rejects rather than returning a partial configuration.
+ *
+ * @evidence contracts/common.md#principled-implementation The file is read as JSON with comments and trailing commas removed, each base is resolved and merged before the file itself, active ancestors reject cycles, and the relative `typeRoots` of each file are resolved against that file's own directory, as the compiler resolves them, before the merge forgets where they came from.
+ * @evidence contracts/common.md#clear-and-simple-design One public function with private parsing and resolution helpers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts It reads the files the compiler reads.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ * @evidence contracts/portability.md#os-neutral-implementation Files are read as UTF-8 through `fs`, a leading byte order mark is dropped, relative bases and `typeRoots` are resolved with `path.resolve` against the directory of the file that names them, and package bases go through Node module resolution from that directory. Resolved native path spellings key the per-read cache and active-ancestor set. Relative bases and option paths retain the directory of the requested config rather than being rebased onto a symlink target.
+ * efficient algorithms: Each distinct resolved configuration is parsed and merged once per read. Every extends edge contributes its already-merged options in declared order; work scales with input bytes, edges and the option records being combined rather than repeated traversal of shared ancestry.
+ * reuse equivalent work: A read owns a cache of completed results keyed by resolved config pathname. It shares the same base across branches only within that read, and a later read observes edits rather than retaining stale configuration state.
+ * bound retention and release resources: The active-ancestor set and completed-config map belong to one read. Active entries leave in finally, and the map is released when the returned read promise settles; no process-wide cache or open file handle survives.
+ */
 var TsConfigReader;
 (function (TsConfigReader) {
-    TsConfigReader.read = (file) => __awaiter(this, void 0, void 0, function* () { return merge(file, new Set()); });
-    const merge = (file, visited) => __awaiter(this, void 0, void 0, function* () {
+    /**
+     * Returns the merged tsconfig of a file: bases first, later files override
+     * earlier ones, and compiler options are merged by key. The `typeRoots` of a
+     * file are returned absolute, resolved against the directory of the file that
+     * wrote them.
+     *
+     * @evidence contracts/common.md#principled-implementation Relative bases are resolved from the file's directory and package bases through module resolution, a base that cannot be found is skipped, and completed base configurations are reused by resolved pathname, and only a revisit to an active ancestor is a rejected cycle. A shared base contributes its full inherited values to every branch, so later extends entries override earlier ones even in a diamond.
+     * @evidence contracts/common.md#clear-and-simple-design One function delegating the merge.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The comment stripper and the trailing-comma remover are one-pass scanners that track strings, so a slash or a comma inside a string value is kept; the files are read as the compiler reads them, apart from the stated limit that only `typeRoots` is rebased and the other path-valued options keep their written form.
+     * @evidence contracts/common.md#meaningful-documentation The comment states the merge order.
+     * @evidence contracts/portability.md#os-neutral-implementation The `typeRoots` of the result are absolute native paths, but every other path-valued option keeps its written form relative to the directory of the file that wrote it, so a caller must not read such an option as relative to its own directory.
+     * efficient algorithms: One per-read completed map avoids re-reading and recursively merging shared ancestors, while each direct base's option record is combined in order to preserve last-base precedence.
+     * reuse equivalent work: Completed ancestors share their parsed and merged values within this request. Each call starts fresh state because files can change between generations.
+     * bound retention and release resources: The call allocates its own ancestor set and result map and retains neither globally. Each recursive active entry is removed in finally, including parse and resolution failures.
+     */
+    TsConfigReader.read = (file) => __awaiter(this, void 0, void 0, function* () { return merge(file, new Set(), new Map()); });
+    const merge = (file, active, completed) => __awaiter(this, void 0, void 0, function* () {
         const location = path_1.default.resolve(file);
-        if (visited.has(location))
-            return {};
-        visited.add(location);
-        const current = parse(yield fs_1.default.promises.readFile(location, "utf8"));
-        const bases = [];
-        for (const parent of asArray(current.extends)) {
-            const next = resolveExtends(parent, path_1.default.dirname(location));
-            if (next !== null)
-                bases.push(yield merge(next, visited));
+        if (active.has(location))
+            throw new Error(`Circular tsconfig extends: ${location}`);
+        const cached = completed.get(location);
+        if (cached !== undefined)
+            return cached;
+        active.add(location);
+        try {
+            const current = rebase(parse(yield fs_1.default.promises.readFile(location, "utf8")), path_1.default.dirname(location));
+            const bases = [];
+            for (const parent of asArray(current.extends)) {
+                const next = resolveExtends(parent, path_1.default.dirname(location));
+                if (next !== null)
+                    bases.push(yield merge(next, active, completed));
+            }
+            const result = [...bases, current].reduce((acc, elem) => { var _a, _b; return (Object.assign(Object.assign(Object.assign({}, acc), elem), { compilerOptions: Object.assign(Object.assign({}, ((_a = acc.compilerOptions) !== null && _a !== void 0 ? _a : {})), ((_b = elem.compilerOptions) !== null && _b !== void 0 ? _b : {})) })); }, {});
+            completed.set(location, result);
+            return result;
+        }
+        finally {
+            active.delete(location);
         }
-        return [...bases, current].reduce((acc, elem) => { var _a, _b; return (Object.assign(Object.assign(Object.assign({}, acc), elem), { compilerOptions: Object.assign(Object.assign({}, ((_a = acc.compilerOptions) !== null && _a !== void 0 ? _a : {})), ((_b = elem.compilerOptions) !== null && _b !== void 0 ? _b : {})) })); }, {});
     });
-    const parse = (text) => JSON.parse(stripTrailingCommas(stripJsonComments(text)));
+    // The compiler reads a relative path of a config against the directory of the
+    // file that wrote it, and the merged result no longer says which file that
+    // was, so `typeRoots`, the one path-valued option a caller forwards to another
+    // project, is made absolute here.
+    const rebase = (config, directory) => {
+        var _a;
+        const typeRoots = (_a = config.compilerOptions) === null || _a === void 0 ? void 0 : _a.typeRoots;
+        if (Array.isArray(typeRoots) === false)
+            return config;
+        return Object.assign(Object.assign({}, config), { compilerOptions: Object.assign(Object.assign({}, config.compilerOptions), { typeRoots: typeRoots.map((root) => typeof root === "string" ? path_1.default.resolve(directory, root) : root) }) });
+    };
+    // A byte order mark, which editors on some platforms write, is no JSON.
+    const parse = (text) => JSON.parse(stripTrailingCommas(stripJsonComments(text.charCodeAt(0) === 0xfeff ? text.slice(1) : text)));
     const asArray = (value) => value === undefined ? [] : Array.isArray(value) ? value : [value];
     const resolveExtends = (specifier, cwd) => {
         const candidates = (base) => {
@@ -99,6 +151,38 @@ var TsConfigReader;
         }
         return output;
     };
-    const stripTrailingCommas = (input) => input.replace(/,\s*([}\]])/g, "$1");
+    // a comma followed, past whitespace, by a closing brace or bracket, outside
+    // every string, so that the text of a value is never changed
+    const stripTrailingCommas = (input) => {
+        let output = "";
+        let string = false;
+        let escaped = false;
+        for (let i = 0; i < input.length; ++i) {
+            const ch = input[i];
+            if (string !== false) {
+                output += ch;
+                if (escaped)
+                    escaped = false;
+                else if (ch === "\\")
+                    escaped = true;
+                else if (ch === string)
+                    string = false;
+            }
+            else if (ch === '"' || ch === "'") {
+                string = ch;
+                output += ch;
+            }
+            else if (ch === ",") {
+                let next = i + 1;
+                while (next < input.length && /\s/.test(input[next]))
+                    ++next;
+                if (input[next] !== "}" && input[next] !== "]")
+                    output += ch;
+            }
+            else
+                output += ch;
+        }
+        return output;
+    };
 })(TsConfigReader || (exports.TsConfigReader = TsConfigReader = {}));
 //# sourceMappingURL=TsConfigReader.js.map

package/lib/utils/TsConfigReader.js.map

@@ -1 +1 @@
-{"version":3,"file":"TsConfigReader.js","sourceRoot":"","sources":["../../src/utils/TsConfigReader.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"TsConfigReader.js","sourceRoot":"","sources":["../../src/utils/TsConfigReader.ts"],"names":[],"mappings":"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"}

package/lib/utils/TtscExecutor.d.ts

@@ -1,9 +1,31 @@
 import cp from "child_process";
+/**
+ * Runs the `ttsc` compiler of the project.
+ *
+ * @evidence contracts/common.md#principled-implementation The binary is found from the project's own `ttsc` package, with the SDK's dependency as a fallback, and is run with the current Node.
+ * @evidence contracts/common.md#clear-and-simple-design One function and a resolution cache.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The binary comes from the package manifest, not a fixed path.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ * @evidence contracts/portability.md#os-neutral-implementation The compiler runs as a child of the current Node executable (`process.execPath`) on the JavaScript entry that the package manifest's `bin` names, found through Node module resolution from the project directory, so no platform shim (`.cmd`, `.ps1` or shell script) and no `PATH` lookup is involved. Arguments are an array, never a command line, and the entry path is joined with `path.join` and checked with `existsSync`.
+ */
 export declare namespace TtscExecutor {
+    /**
+     * Compiles a project with `ttsc` and returns captured output, or null when
+     * the selected stdio does not pipe standard output.
+     *
+     * The cache directory of the environment is passed on, and a non-zero exit
+     * throws.
+     *
+     * @evidence contracts/common.md#principled-implementation The command is run with an argument array and the current Node executable, so no shell or platform shim is involved.
+     * @evidence contracts/common.md#clear-and-simple-design One function.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The environment is extended, not replaced.
+     * @evidence contracts/common.md#meaningful-documentation The comment states the arguments and the failure.
+     * @evidence contracts/portability.md#os-neutral-implementation The working directory and the environment are explicit. Standard output is piped by default with a 64 MiB buffer; callers may select another stdio mode. A non-zero exit surfaces as Node's process error carrying `status` and available captured output.
+     */
     const run: (props: {
         cwd: string;
         env?: NodeJS.ProcessEnv;
         project: string;
         stdio?: cp.StdioOptions;
-    }) => Buffer;
+    }) => Buffer | null;
 }

package/lib/utils/TtscExecutor.js

@@ -7,8 +7,30 @@ exports.TtscExecutor = void 0;
 const child_process_1 = __importDefault(require("child_process"));
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
+/**
+ * Runs the `ttsc` compiler of the project.
+ *
+ * @evidence contracts/common.md#principled-implementation The binary is found from the project's own `ttsc` package, with the SDK's dependency as a fallback, and is run with the current Node.
+ * @evidence contracts/common.md#clear-and-simple-design One function and a resolution cache.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The binary comes from the package manifest, not a fixed path.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ * @evidence contracts/portability.md#os-neutral-implementation The compiler runs as a child of the current Node executable (`process.execPath`) on the JavaScript entry that the package manifest's `bin` names, found through Node module resolution from the project directory, so no platform shim (`.cmd`, `.ps1` or shell script) and no `PATH` lookup is involved. Arguments are an array, never a command line, and the entry path is joined with `path.join` and checked with `existsSync`.
+ */
 var TtscExecutor;
 (function (TtscExecutor) {
+    /**
+     * Compiles a project with `ttsc` and returns captured output, or null when
+     * the selected stdio does not pipe standard output.
+     *
+     * The cache directory of the environment is passed on, and a non-zero exit
+     * throws.
+     *
+     * @evidence contracts/common.md#principled-implementation The command is run with an argument array and the current Node executable, so no shell or platform shim is involved.
+     * @evidence contracts/common.md#clear-and-simple-design One function.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The environment is extended, not replaced.
+     * @evidence contracts/common.md#meaningful-documentation The comment states the arguments and the failure.
+     * @evidence contracts/portability.md#os-neutral-implementation The working directory and the environment are explicit. Standard output is piped by default with a 64 MiB buffer; callers may select another stdio mode. A non-zero exit surfaces as Node's process error carrying `status` and available captured output.
+     */
     TtscExecutor.run = (props) => {
         var _a;
         const args = [bin(props.cwd), "-p", props.project];

package/lib/utils/TtscExecutor.js.map

@@ -1 +1 @@
-{"version":3,"file":"TtscExecutor.js","sourceRoot":"","sources":["../../src/utils/TtscExecutor.ts"],"names":[],"mappings":";;;;;;AAAA,kEAA+B;AAC/B,4CAAoB;AACpB,gDAAwB;AAExB,IAAiB,YAAY,CA+D5B;AA/DD,WAAiB,YAAY;IACd,gBAAG,GAAG,CAAC,KAKnB,EAAU,EAAE;;QACX,MAAM,IAAI,GAAa,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;QAC7D,IAAI,OAAO,CAAC,GAAG,CAAC,cAAc,KAAK,SAAS;YAC1C,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;QACvD,OAAO,uBAAE,CAAC,YAAY,CAAC,OAAO,CAAC,QAAQ,EAAE,IAAI,EAAE;YAC7C,GAAG,EAAE,KAAK,CAAC,GAAG;YACd,GAAG,kCACE,OAAO,CAAC,GAAG,GACX,KAAK,CAAC,GAAG,CACb;YACD,KAAK,QAAE,KAAK,CAAC,KAAK,mCAAI,MAAM;YAC5B,SAAS,EAAE,EAAE,GAAG,IAAI,GAAG,IAAI;SAC5B,CAAC,CAAC;IACL,CAAC,CAAC;IAEF,MAAM,IAAI,GAAwB,IAAI,GAAG,EAAE,CAAC;IAE5C,MAAM,GAAG,GAAG,CAAC,GAAW,EAAU,EAAE;;QAClC,MAAM,MAAM,GAAuB,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACjD,IAAI,MAAM,KAAK,SAAS;YAAE,OAAO,MAAM,CAAC;QAExC,sEAAsE;QACtE,oEAAoE;QACpE,wCAAwC;QACxC,IAAI,QAAgB,CAAC;QACrB,IAAI,CAAC;YACH,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,mBAAmB,EAAE,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACpE,CAAC;mBAAO,CAAC;YACP,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,mBAAmB,CAAC,CAAC;QAClD,CAAC;QACD,MAAM,SAAS,GAAW,cAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QACjD,MAAM,IAAI,GAA8C,IAAI,CAAC,KAAK,CAChE,YAAE,CAAC,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,CAClC,CAAC;QACF,MAAM,QAAQ,GACZ,OAAO,IAAI,CAAC,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,MAAA,IAAI,CAAC,GAAG,0CAAE,IAAI,CAAC;QAC3D,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,MAAM,IAAI,GACR,OAAO,IAAI,CAAC,GAAG,KAAK,QAAQ,IAAI,IAAI,CAAC,GAAG,KAAK,IAAI;gBAC/C,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;gBAClC,CAAC,CAAC,QAAQ,CAAC;YACf,MAAM,IAAI,KAAK,CACb,sDAAsD;gBACpD,0BAA0B,IAAI,IAAI;gBAClC,6CAA6C,CAChD,CAAC;QACJ,CAAC;QAED,MAAM,QAAQ,GAAW,cAAI,CAAC,IAAI,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;QACxD,IAAI,CAAC,YAAE,CAAC,UAAU,CAAC,QAAQ,CAAC;YAC1B,MAAM,IAAI,KAAK,CACb,+BAA+B,QAAQ,KAAK;gBAC1C,6CAA6C,CAChD,CAAC;QACJ,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;QACxB,OAAO,QAAQ,CAAC;IAClB,CAAC,CAAC;AACJ,CAAC,EA/DgB,YAAY,aAAZ,YAAY,GAAZ,YAAY,QA+D5B"}
+{"version":3,"file":"TtscExecutor.js","sourceRoot":"","sources":["../../src/utils/TtscExecutor.ts"],"names":[],"mappings":";;;;;;AAAA,kEAA+B;AAC/B,4CAAoB;AACpB,gDAAwB;AAExB;;;;;;;;GAQG;AACH,IAAiB,YAAY,CA4E5B;AA5ED,WAAiB,YAAY;IAC3B;;;;;;;;;;;;OAYG;IACU,gBAAG,GAAG,CAAC,KAKnB,EAAiB,EAAE;;QAClB,MAAM,IAAI,GAAa,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;QAC7D,IAAI,OAAO,CAAC,GAAG,CAAC,cAAc,KAAK,SAAS;YAC1C,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;QACvD,OAAO,uBAAE,CAAC,YAAY,CAAC,OAAO,CAAC,QAAQ,EAAE,IAAI,EAAE;YAC7C,GAAG,EAAE,KAAK,CAAC,GAAG;YACd,GAAG,kCACE,OAAO,CAAC,GAAG,GACX,KAAK,CAAC,GAAG,CACb;YACD,KAAK,QAAE,KAAK,CAAC,KAAK,mCAAI,MAAM;YAC5B,SAAS,EAAE,EAAE,GAAG,IAAI,GAAG,IAAI;SAC5B,CAAC,CAAC;IACL,CAAC,CAAC;IAEF,MAAM,IAAI,GAAwB,IAAI,GAAG,EAAE,CAAC;IAE5C,MAAM,GAAG,GAAG,CAAC,GAAW,EAAU,EAAE;;QAClC,MAAM,MAAM,GAAuB,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACjD,IAAI,MAAM,KAAK,SAAS;YAAE,OAAO,MAAM,CAAC;QAExC,sEAAsE;QACtE,oEAAoE;QACpE,wCAAwC;QACxC,IAAI,QAAgB,CAAC;QACrB,IAAI,CAAC;YACH,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,mBAAmB,EAAE,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACpE,CAAC;mBAAO,CAAC;YACP,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,mBAAmB,CAAC,CAAC;QAClD,CAAC;QACD,MAAM,SAAS,GAAW,cAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QACjD,MAAM,IAAI,GAA8C,IAAI,CAAC,KAAK,CAChE,YAAE,CAAC,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,CAClC,CAAC;QACF,MAAM,QAAQ,GACZ,OAAO,IAAI,CAAC,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,MAAA,IAAI,CAAC,GAAG,0CAAE,IAAI,CAAC;QAC3D,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,MAAM,IAAI,GACR,OAAO,IAAI,CAAC,GAAG,KAAK,QAAQ,IAAI,IAAI,CAAC,GAAG,KAAK,IAAI;gBAC/C,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;gBAClC,CAAC,CAAC,QAAQ,CAAC;YACf,MAAM,IAAI,KAAK,CACb,sDAAsD;gBACpD,0BAA0B,IAAI,IAAI;gBAClC,6CAA6C,CAChD,CAAC;QACJ,CAAC;QAED,MAAM,QAAQ,GAAW,cAAI,CAAC,IAAI,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;QACxD,IAAI,CAAC,YAAE,CAAC,UAAU,CAAC,QAAQ,CAAC;YAC1B,MAAM,IAAI,KAAK,CACb,+BAA+B,QAAQ,KAAK;gBAC1C,6CAA6C,CAChD,CAAC;QACJ,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;QACxB,OAAO,QAAQ,CAAC;IAClB,CAAC,CAAC;AACJ,CAAC,EA5EgB,YAAY,aAAZ,YAAY,GAAZ,YAAY,QA4E5B"}

package/lib/utils/VersioningStrategy.d.ts

@@ -1,6 +1,43 @@
 import { VERSION_NEUTRAL, VersionValue } from "@nestjs/common/interfaces";
 import { INestiaProject } from "../structures/INestiaProject";
+/**
+ * Resolves the URI versions of a controller method as NestJS does.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace turns version metadata and the default version into path segments.
+ * @evidence contracts/common.md#clear-and-simple-design Two functions.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The precedence is NestJS's.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation VersioningStrategy maps Nest version metadata to URI segments, which are protocol spelling rather than native file paths.
+ */
 export declare namespace VersioningStrategy {
-    const cast: (value: VersionValue | undefined) => Array<string | typeof VERSION_NEUTRAL>;
-    const merge: (project: Omit<INestiaProject, "config">) => (values: Array<string | typeof VERSION_NEUTRAL>) => string[];
+    /**
+     * Casts version metadata to a list: absence stays absent and a single value
+     * is a one-element list.
+     *
+     * @evidence contracts/common.md#principled-implementation A single version becomes a list while absence stays distinct from an explicit empty list, which registers no paths rather than inheriting other versions.
+     * @evidence contracts/common.md#clear-and-simple-design One conditional.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts It adds nothing.
+     * @evidence contracts/common.md#meaningful-documentation The comment states the cases.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation VersioningStrategy.cast maps Nest version metadata to URI segments, which are protocol spelling rather than native file paths.
+     */
+    const cast: (value: VersionValue | undefined) => Array<string | typeof VERSION_NEUTRAL> | undefined;
+    /**
+     * Version path segments of a route, resolved as NestJS resolves them: the
+     * method's versions, else the controller's, else the default version, and no
+     * version at all is the unversioned path.
+     *
+     * The controller's and the method's versions were joined, so a method
+     * overriding its controller's version was also described at the controller's,
+     * and a route with no version and no default got no path at all (#1735).
+     *
+     * @evidence contracts/common.md#principled-implementation The first present method, controller or default list wins, including an empty list that registers no paths. Duplicates are removed, neutral and absent versions have no segment, and with versioning off the only segment is empty.
+     * @evidence contracts/common.md#clear-and-simple-design One curried function.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The precedence is NestJS's.
+     * @evidence contracts/common.md#meaningful-documentation The comment states the precedence.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation VersioningStrategy.merge maps Nest version metadata to URI segments, which are protocol spelling rather than native file paths.
+     */
+    const merge: (project: Omit<INestiaProject, "config">) => (props: {
+        controller: Array<string | typeof VERSION_NEUTRAL> | undefined;
+        method: Array<string | typeof VERSION_NEUTRAL> | undefined;
+    }) => string[];
 }

package/lib/utils/VersioningStrategy.js

@@ -1,22 +1,55 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VersioningStrategy = void 0;
+/**
+ * Resolves the URI versions of a controller method as NestJS does.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace turns version metadata and the default version into path segments.
+ * @evidence contracts/common.md#clear-and-simple-design Two functions.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The precedence is NestJS's.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation VersioningStrategy maps Nest version metadata to URI segments, which are protocol spelling rather than native file paths.
+ */
 var VersioningStrategy;
 (function (VersioningStrategy) {
-    VersioningStrategy.cast = (value) => value === undefined ? [] : Array.isArray(value) ? value : [value];
-    VersioningStrategy.merge = (project) => (values) => {
-        var _a;
-        if (project.input.versioning === undefined)
+    /**
+     * Casts version metadata to a list: absence stays absent and a single value
+     * is a one-element list.
+     *
+     * @evidence contracts/common.md#principled-implementation A single version becomes a list while absence stays distinct from an explicit empty list, which registers no paths rather than inheriting other versions.
+     * @evidence contracts/common.md#clear-and-simple-design One conditional.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts It adds nothing.
+     * @evidence contracts/common.md#meaningful-documentation The comment states the cases.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation VersioningStrategy.cast maps Nest version metadata to URI segments, which are protocol spelling rather than native file paths.
+     */
+    VersioningStrategy.cast = (value) => value === undefined ? undefined : Array.isArray(value) ? value : [value];
+    /**
+     * Version path segments of a route, resolved as NestJS resolves them: the
+     * method's versions, else the controller's, else the default version, and no
+     * version at all is the unversioned path.
+     *
+     * The controller's and the method's versions were joined, so a method
+     * overriding its controller's version was also described at the controller's,
+     * and a route with no version and no default got no path at all (#1735).
+     *
+     * @evidence contracts/common.md#principled-implementation The first present method, controller or default list wins, including an empty list that registers no paths. Duplicates are removed, neutral and absent versions have no segment, and with versioning off the only segment is empty.
+     * @evidence contracts/common.md#clear-and-simple-design One curried function.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The precedence is NestJS's.
+     * @evidence contracts/common.md#meaningful-documentation The comment states the precedence.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation VersioningStrategy.merge maps Nest version metadata to URI segments, which are protocol spelling rather than native file paths.
+     */
+    VersioningStrategy.merge = (project) => (props) => {
+        var _a, _b;
+        const versioning = project.input.versioning;
+        if (versioning === undefined)
             return [""];
-        const set = new Set(values);
-        const array = set.size === 0
-            ? VersioningStrategy.cast((_a = project.input.versioning) === null || _a === void 0 ? void 0 : _a.defaultVersion)
-            : Array.from(set);
-        return !!(array === null || array === void 0 ? void 0 : array.length)
-            ? array.map((x) => typeof x === "symbol"
-                ? ""
-                : `${project.input.versioning.prefix}${x}`)
-            : [];
+        const chosen = (_b = (_a = props.method) !== null && _a !== void 0 ? _a : props.controller) !== null && _b !== void 0 ? _b : VersioningStrategy.cast(versioning.defaultVersion);
+        if (chosen === undefined)
+            return [""];
+        const unique = [
+            ...new Set(chosen),
+        ];
+        return unique.map((x) => typeof x === "symbol" ? "" : `${versioning.prefix}${x}`);
     };
 })(VersioningStrategy || (exports.VersioningStrategy = VersioningStrategy = {}));
 //# sourceMappingURL=VersioningStrategy.js.map

package/lib/utils/VersioningStrategy.js.map

@@ -1 +1 @@
-{"version":3,"file":"VersioningStrategy.js","sourceRoot":"","sources":["../../src/utils/VersioningStrategy.ts"],"names":[],"mappings":";;;AAIA,IAAiB,kBAAkB,CAuBlC;AAvBD,WAAiB,kBAAkB;IACpB,uBAAI,GAAG,CAClB,KAA+B,EACS,EAAE,CAC1C,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IAEvD,wBAAK,GAChB,CAAC,OAAuC,EAAE,EAAE,CAC5C,CAAC,MAA8C,EAAY,EAAE;;QAC3D,IAAI,OAAO,CAAC,KAAK,CAAC,UAAU,KAAK,SAAS;YAAE,OAAO,CAAC,EAAE,CAAC,CAAC;QACxD,MAAM,GAAG,GAAyC,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC;QAClE,MAAM,KAAK,GACT,GAAG,CAAC,IAAI,KAAK,CAAC;YACZ,CAAC,CAAC,uBAAI,CAAC,MAAA,OAAO,CAAC,KAAK,CAAC,UAAU,0CAAE,cAAc,CAAC;YAChD,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACtB,OAAO,CAAC,EAAC,KAAK,aAAL,KAAK,uBAAL,KAAK,CAAE,MAAM,CAAA;YACpB,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CACd,OAAO,CAAC,KAAK,QAAQ;gBACnB,CAAC,CAAC,EAAE;gBACJ,CAAC,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,UAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAC9C;YACH,CAAC,CAAC,EAAE,CAAC;IACT,CAAC,CAAC;AACN,CAAC,EAvBgB,kBAAkB,aAAlB,kBAAkB,GAAlB,kBAAkB,QAuBlC"}
+{"version":3,"file":"VersioningStrategy.js","sourceRoot":"","sources":["../../src/utils/VersioningStrategy.ts"],"names":[],"mappings":";;;AAIA;;;;;;;;GAQG;AACH,IAAiB,kBAAkB,CAiDlC;AAjDD,WAAiB,kBAAkB;IACjC;;;;;;;;;OASG;IACU,uBAAI,GAAG,CAClB,KAA+B,EACqB,EAAE,CACtD,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IAE3E;;;;;;;;;;;;;;OAcG;IACU,wBAAK,GAChB,CAAC,OAAuC,EAAE,EAAE,CAC5C,CAAC,KAGA,EAAY,EAAE;;QACb,MAAM,UAAU,GAAG,OAAO,CAAC,KAAK,CAAC,UAAU,CAAC;QAC5C,IAAI,UAAU,KAAK,SAAS;YAAE,OAAO,CAAC,EAAE,CAAC,CAAC;QAC1C,MAAM,MAAM,eACV,KAAK,CAAC,MAAM,mCAAI,KAAK,CAAC,UAAU,mCAAI,uBAAI,CAAC,UAAU,CAAC,cAAc,CAAC,CAAC;QACtE,IAAI,MAAM,KAAK,SAAS;YAAE,OAAO,CAAC,EAAE,CAAC,CAAC;QACtC,MAAM,MAAM,GAA2C;YACrD,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC;SACnB,CAAC;QACF,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CACtB,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CACxD,CAAC;IACJ,CAAC,CAAC;AACN,CAAC,EAjDgB,kBAAkB,aAAlB,kBAAkB,GAAlB,kBAAkB,QAiDlC"}

package/lib/validators/TextPlainValidator.d.ts

@@ -1,5 +1,24 @@
 import { MetadataSchema } from "../internal/legacy";
+/**
+ * Validates that a type can be a `text/plain` body or response.
+ *
+ * @evidence contracts/common.md#principled-implementation A plain text body is a string, so the type may hold only string forms.
+ * @evidence contracts/common.md#clear-and-simple-design One function.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The rule follows the content type.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation TextPlainValidator checks the metadata union accepted for a text/plain payload; it owns no native filesystem or executable representation.
+ */
 export declare namespace TextPlainValidator {
+    /**
+     * Returns an error message unless every member of the metadata is a string, a
+     * string constant, a string template, or the native String.
+     *
+     * @evidence contracts/common.md#principled-implementation The number of string forms is counted and compared with the size of the metadata, so any other form makes the counts differ, and an empty type is also refused.
+     * @evidence contracts/common.md#clear-and-simple-design One function.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The count is exact and no type is special-cased.
+     * @evidence contracts/common.md#meaningful-documentation The comment states the accepted forms.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation TextPlainValidator.validate checks the metadata union accepted for a text/plain payload; it owns no native filesystem or executable representation.
+     */
     const validate: (props: {
         metadata: MetadataSchema;
     }) => string[];

package/lib/validators/TextPlainValidator.js

@@ -2,8 +2,27 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TextPlainValidator = void 0;
 const legacy_1 = require("../internal/legacy");
+/**
+ * Validates that a type can be a `text/plain` body or response.
+ *
+ * @evidence contracts/common.md#principled-implementation A plain text body is a string, so the type may hold only string forms.
+ * @evidence contracts/common.md#clear-and-simple-design One function.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The rule follows the content type.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation TextPlainValidator checks the metadata union accepted for a text/plain payload; it owns no native filesystem or executable representation.
+ */
 var TextPlainValidator;
 (function (TextPlainValidator) {
+    /**
+     * Returns an error message unless every member of the metadata is a string, a
+     * string constant, a string template, or the native String.
+     *
+     * @evidence contracts/common.md#principled-implementation The number of string forms is counted and compared with the size of the metadata, so any other form makes the counts differ, and an empty type is also refused.
+     * @evidence contracts/common.md#clear-and-simple-design One function.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The count is exact and no type is special-cased.
+     * @evidence contracts/common.md#meaningful-documentation The comment states the accepted forms.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation TextPlainValidator.validate checks the metadata union accepted for a text/plain payload; it owns no native filesystem or executable representation.
+     */
     TextPlainValidator.validate = (props) => {
         const expected = props.metadata.atomics.filter((a) => a.type === "string").length +
             props.metadata.constants

package/lib/validators/TextPlainValidator.js.map

@@ -1 +1 @@
-{"version":3,"file":"TextPlainValidator.js","sourceRoot":"","sources":["../../src/validators/TextPlainValidator.ts"],"names":[],"mappings":";;;AAAA,+CAA4D;AAE5D,IAAiB,kBAAkB,CAclC;AAdD,WAAiB,kBAAkB;IACpB,2BAAQ,GAAG,CAAC,KAAmC,EAAY,EAAE;QACxE,MAAM,QAAQ,GACZ,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,MAAM;YAChE,KAAK,CAAC,QAAQ,CAAC,SAAS;iBACrB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC;iBAClC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC;iBAC3B,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAC7B,KAAK,CAAC,QAAQ,CAAC,SAAS,CAAC,MAAM;YAC/B,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,MAAM,CAAC;QACnE,IAAI,IAAA,eAAM,EAAC,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,IAAA,eAAM,EAAC,KAAK,CAAC,QAAQ,CAAC,KAAK,QAAQ;YACrE,OAAO,CAAC,+DAA+D,CAAC,CAAC;QAC3E,OAAO,EAAE,CAAC;IACZ,CAAC,CAAC;AACJ,CAAC,EAdgB,kBAAkB,aAAlB,kBAAkB,GAAlB,kBAAkB,QAclC"}
+{"version":3,"file":"TextPlainValidator.js","sourceRoot":"","sources":["../../src/validators/TextPlainValidator.ts"],"names":[],"mappings":";;;AAAA,+CAA4D;AAE5D;;;;;;;;GAQG;AACH,IAAiB,kBAAkB,CAwBlC;AAxBD,WAAiB,kBAAkB;IACjC;;;;;;;;;OASG;IACU,2BAAQ,GAAG,CAAC,KAAmC,EAAY,EAAE;QACxE,MAAM,QAAQ,GACZ,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,MAAM;YAChE,KAAK,CAAC,QAAQ,CAAC,SAAS;iBACrB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC;iBAClC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC;iBAC3B,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAC7B,KAAK,CAAC,QAAQ,CAAC,SAAS,CAAC,MAAM;YAC/B,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,MAAM,CAAC;QACnE,IAAI,IAAA,eAAM,EAAC,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,IAAA,eAAM,EAAC,KAAK,CAAC,QAAQ,CAAC,KAAK,QAAQ;YACrE,OAAO,CAAC,+DAA+D,CAAC,CAAC;QAC3E,OAAO,EAAE,CAAC;IACZ,CAAC,CAAC;AACJ,CAAC,EAxBgB,kBAAkB,aAAlB,kBAAkB,GAAlB,kBAAkB,QAwBlC"}

package/native/go.mod

@@ -9,7 +9,7 @@ require (
 	github.com/microsoft/typescript-go/shim/scanner v0.0.0
 	github.com/samchon/nestia/packages/core/native v0.0.0
 	github.com/samchon/ttsc/packages/ttsc v0.0.0
-	github.com/samchon/typia/packages/typia/native v0.0.0-20260818045905-f692fd63a846
+	github.com/samchon/typia/packages/typia/native v0.0.0-20260926142025-755176823ba3
 )
 
 require (

package/native/go.sum

@@ -38,8 +38,8 @@ github.com/samchon/ttsc/packages/ttsc/shim/vfs/cachedvfs v0.0.0-20260820075544-3
 github.com/samchon/ttsc/packages/ttsc/shim/vfs/cachedvfs v0.0.0-20260820075544-3fe6b732f888/go.mod h1:XS3LhXkn5xadyRe3tW+9+suW/7gh7dPdL43Q+s/lUDo=
 github.com/samchon/ttsc/packages/ttsc/shim/vfs/osvfs v0.0.0-20260820075544-3fe6b732f888 h1:ihiKD2OhuYc7Dngxw3uFYbVoiA/xuPwwQoUakB59E40=
 github.com/samchon/ttsc/packages/ttsc/shim/vfs/osvfs v0.0.0-20260820075544-3fe6b732f888/go.mod h1:otX+qw8aZLNCoBmCwMAn53Nw0RQTPzSoId3DxmE67So=
-github.com/samchon/typia/packages/typia/native v0.0.0-20260818045905-f692fd63a846 h1:x9xL0zn2AqPf19lTp8dNal+Ia3cIu0uYnyXlY4mo3QI=
-github.com/samchon/typia/packages/typia/native v0.0.0-20260818045905-f692fd63a846/go.mod h1:pUTSG5IZxw8Hohle//RsDXnE+8ZhAus7mPDKFqzvZnk=
+github.com/samchon/typia/packages/typia/native v0.0.0-20260926142025-755176823ba3 h1:XtRIf6wvDuSHLsphMXiB3lm6p0/2sxHMfc6FMjI5LLA=
+github.com/samchon/typia/packages/typia/native v0.0.0-20260926142025-755176823ba3/go.mod h1:pUTSG5IZxw8Hohle//RsDXnE+8ZhAus7mPDKFqzvZnk=
 github.com/zeebo/assert v1.3.0 h1:g7C04CbJuIDKNPFHmsk4hwZDO5O+kntRxzaUoNXj+IQ=
 github.com/zeebo/assert v1.3.0/go.mod h1:Pq9JiuJQpG8JLJdtkwrJESF0Foym2/D9XMU5ciN/wJ0=
 github.com/zeebo/xxh3 v1.1.0 h1:s7DLGDK45Dyfg7++yxI0khrfwq9661w9EN78eP/UZVs=

package/native/sdk/register.go

@@ -90,6 +90,15 @@ func (linkedPlugin) ApplyProgram(prog *driver.Program, _ driver.PluginContext) e
 // alongside the typia and core transforms, exactly as the typia build command
 // wires `nativetransform.Transform`. A site-collection failure is returned as
 // diagnostics; the returned transform is nil when there are no sites.
+//
+// @evidence contracts/common.md#principled-implementation Decorated class-method sites are collected once for the program, and the returned transform maps each original method to its synthetic counterpart so the decorator lands on the printed node; collection failures return diagnostics and no sites return nil. Private reflection helpers use TypeReference/TypeQuery roles and checker aliases for authored imports, declaration sources for free types, and IsLibFile for actual libraries; locally bound TypeParameter symbols have no module import identity. Async aliases use the checker-resolved payload and TypeToTypeNode to apply generic defaults and substitutions after shared declaration-based Promise/Observable classification; type operators retain valid source or projected syntax and parenthesized operands preserve generic arguments. Only fixed language keywords are excluded by spelling. Readonly array and tuple schema markers follow actual checker numeric-index immutability and tuple target flags; substituted object properties, ordered schema dictionaries, nested and inferred types retain those facts without classifying authored alias names. Metadata nulls use the explicit upstream JSON null marker, so authored strings remain strings without encoded-text substitution. The shared private tag serializer omits a schema member when upstream analysis supplies nil for an absent or undefined optional schema, while preserving explicit empty objects and null instance leaves inside populated schema objects.
+// @evidence contracts/common.md#clear-and-simple-design Site collection and one per-file closure share file grouping and the module specifier. Private import reflection centralizes reference traversal, authored binding selection and declaration fallback so the reflected type forms use one policy. Checker-generated alias payload nodes carry identifier symbols separately because they have no authored source span; the public printer supplies their text. All raw tag matrices share one serialization boundary, keeping optional tag representation separate from JSON Schema baking.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The shared module specifier binds one generated alias without controller special cases. Import decisions use semantic AST roles, checker bindings and actual library identity rather than regex matches in literals, built-in-name whitelists or fixture/path spelling. Alias projection uses the supported checker and printer APIs without reparsing or mutating foreign behavior. Optional-schema omission depends on the analyzed nil value, never tag names, fixture paths or a TypeScript-writer compensation; invalid top-level null and scalar schemas remain upstream analyzer errors.
+// @evidence contracts/common.md#meaningful-documentation The public comment explains injected metadata, original-to-synthetic mapping and nil/diagnostic results. Private helper comments explain reference roles, shadowable library names, declaration fallback, annotation-local binders, checker projection and type-operator syntax; these details remain documented at their implementation owners. The private tag serializer explains why absence cannot become JSON null and why empty objects and nested null content stay intact.
+// @evidence contracts/portability.md#os-neutral-implementation File grouping converts both collected paths and emitted source names through filepath.ToSlash; it preserves the compiler's filename identity without guessing volume case policy. The contributor receives an existing compiler program and launches no shell. Declaration-package ownership uses the shared SourceFilePackageName ancestor walk through that program's filesystem, retaining its overlay observations and native filepath operations.
+// @evidence contracts/performance.md#efficient-algorithms Site analysis visits the program once; grouping costs O(S) for S sites plus filename lengths. Each participating emitted file is traversed once to index original method identities, followed by O(Sf) injections for its sites. The method index avoids a separate AST traversal for every route.
+// @evidence contracts/performance.md#reuse-equivalent-work The returned closure shares the collected metadata and file grouping across file emissions of this program. A new EmitTransform invocation recollects against its supplied program; these AST identities cannot safely be reused for another compilation.
+// @evidence contracts/performance.md#bound-retention-and-release-resources The closure retains the site's AST nodes and metadata strings for its compiler emission lifetime. Each per-file method index becomes unreachable after that file returns; there are no process-global program caches, file handles or background tasks in this operation.
 func EmitTransform(prog *driver.Program) (driver.PluginTransform, []transform.Diagnostic) {
 	sites, diagnostics := collectNestiaSDKSites(prog)
 	if len(diagnostics) > 0 {
@@ -181,8 +190,9 @@ func synthesized(node *shimast.Node) *shimast.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.
+// method. Site collection visits decorated class methods, including methods
+// outside Nest controllers; their existing modifier lists carry the decorators
+// and can be extended in place. Runtime controller analysis selects routes.
 func injectOperationMetadataDecorator(
 	factory *shimast.NodeFactory,
 	method *shimast.Node,