@nestia/core 14.0.1 → 14.0.2

package/lib/utils/SourceFinder.d.ts

@@ -1,4 +1,26 @@
+/**
+ * Finds source files by path, directory, or glob.
+ *
+ * @evidence contracts/common.md#principled-implementation The finder resolves each pattern to existing files or directories, walks directories, applies the caller's filter to files only, and subtracts the excluded set, so the result is the included files minus the excluded ones.
+ * @evidence contracts/common.md#clear-and-simple-design One public function and private walkers; the caller supplies the filter.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts It contains no file names; extensions come from the caller's filter.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ * @evidence contracts/portability.md#os-neutral-implementation The finder turns each pattern into an absolute native path with `path.resolve` and asks the filesystem itself, through `existsSync`, `stat` and `readdir`, whether a path exists and what it is, so the volume's own case policy and links apply. Only the part of a pattern below its longest existing ancestor is globbed, rewritten from the native separator to `/` because glob reads a Windows backslash as an escape. Remaining assumptions: the case policy of wildcard matching is glob's own platform default and not a probe of the volume, accepted files are keyed by filesystem real path while returned locations retain their discovered spelling, and directory links are followed once per real path in each include or exclude collection, so aliases and cycles do not repeat a traversal.
+ */
 export declare namespace SourceFinder {
+    /**
+     * Returns the files matched by the include patterns and not by the exclude
+     * patterns.
+     *
+     * A pattern may name a file, a directory that is walked recursively, or a
+     * glob. Only files accepted by the filter are returned.
+     *
+     * @evidence contracts/common.md#principled-implementation A pattern that exists on disk is used as a path; otherwise its longest existing ancestor becomes the base of a glob search, so a pattern with wildcards is matched below the part of the path that exists, and a base that does not exist matches nothing; accepted file identities use filesystem real paths, so includes and exclusions agree across links and case aliases while output retains a discovered native spelling.
+     * @evidence contracts/common.md#clear-and-simple-design One function that runs the same collection twice, once adding and once removing.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The result follows the patterns and the filter, with no fixed directory.
+     * @evidence contracts/common.md#meaningful-documentation The comment states the pattern forms and the filtering.
+     * @evidence contracts/portability.md#os-neutral-implementation An existing path is used literally, so no character glob reads specially is interpreted. Otherwise the nearest existing ancestor, found with `existsSync` and `dirname` until the filesystem root, is the glob's working directory and the matches are resolved against it, so a drive letter or a UNC root never enters the pattern.
+     */
     const find: (props: IProps) => Promise<string[]>;
 }
 interface IProps {

package/lib/utils/SourceFinder.js

@@ -16,34 +16,61 @@ exports.SourceFinder = void 0;
 const fs_1 = __importDefault(require("fs"));
 const glob_1 = require("glob");
 const path_1 = __importDefault(require("path"));
+/**
+ * Finds source files by path, directory, or glob.
+ *
+ * @evidence contracts/common.md#principled-implementation The finder resolves each pattern to existing files or directories, walks directories, applies the caller's filter to files only, and subtracts the excluded set, so the result is the included files minus the excluded ones.
+ * @evidence contracts/common.md#clear-and-simple-design One public function and private walkers; the caller supplies the filter.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts It contains no file names; extensions come from the caller's filter.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ * @evidence contracts/portability.md#os-neutral-implementation The finder turns each pattern into an absolute native path with `path.resolve` and asks the filesystem itself, through `existsSync`, `stat` and `readdir`, whether a path exists and what it is, so the volume's own case policy and links apply. Only the part of a pattern below its longest existing ancestor is globbed, rewritten from the native separator to `/` because glob reads a Windows backslash as an escape. Remaining assumptions: the case policy of wildcard matching is glob's own platform default and not a probe of the volume, accepted files are keyed by filesystem real path while returned locations retain their discovered spelling, and directory links are followed once per real path in each include or exclude collection, so aliases and cycles do not repeat a traversal.
+ */
 var SourceFinder;
 (function (SourceFinder) {
+    /**
+     * Returns the files matched by the include patterns and not by the exclude
+     * patterns.
+     *
+     * A pattern may name a file, a directory that is walked recursively, or a
+     * glob. Only files accepted by the filter are returned.
+     *
+     * @evidence contracts/common.md#principled-implementation A pattern that exists on disk is used as a path; otherwise its longest existing ancestor becomes the base of a glob search, so a pattern with wildcards is matched below the part of the path that exists, and a base that does not exist matches nothing; accepted file identities use filesystem real paths, so includes and exclusions agree across links and case aliases while output retains a discovered native spelling.
+     * @evidence contracts/common.md#clear-and-simple-design One function that runs the same collection twice, once adding and once removing.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The result follows the patterns and the filter, with no fixed directory.
+     * @evidence contracts/common.md#meaningful-documentation The comment states the pattern forms and the filtering.
+     * @evidence contracts/portability.md#os-neutral-implementation An existing path is used literally, so no character glob reads specially is interpreted. Otherwise the nearest existing ancestor, found with `existsSync` and `dirname` until the filesystem root, is the glob's working directory and the matches are resolved against it, so a drive letter or a UNC root never enters the pattern.
+     */
     SourceFinder.find = (props) => __awaiter(this, void 0, void 0, function* () {
         var _a;
-        const dict = new Set();
-        yield emplace(props.filter)(props.include)((str) => dict.add(str));
+        const dict = new Map();
+        yield emplace(props.filter)(props.include)((str) => dict.set(fs_1.default.realpathSync.native(str), str));
         if ((_a = props.exclude) === null || _a === void 0 ? void 0 : _a.length)
-            yield emplace(props.filter)(props.exclude)((str) => dict.delete(str));
-        return [...dict];
+            yield emplace(props.filter)(props.exclude)((str) => dict.delete(fs_1.default.realpathSync.native(str)));
+        return [...dict.values()];
     });
     const emplace = (filter) => (input) => (closure) => __awaiter(this, void 0, void 0, function* () {
+        const visited = new Set();
         for (const pattern of input) {
             for (const file of yield _Glob(pattern)) {
                 const stats = yield fs_1.default.promises.stat(file);
                 if (stats.isDirectory() === true)
-                    yield iterate(filter)(closure)(file);
+                    yield iterate(filter)(closure)(file, visited);
                 else if (stats.isFile() && filter(file))
                     closure(file);
             }
         }
     });
-    const iterate = (filter) => (closure) => (location) => __awaiter(this, void 0, void 0, function* () {
+    const iterate = (filter) => (closure) => (location, visited) => __awaiter(this, void 0, void 0, function* () {
+        const identity = yield fs_1.default.promises.realpath(location);
+        if (visited.has(identity))
+            return;
+        visited.add(identity);
         const directory = yield fs_1.default.promises.readdir(location);
         for (const file of directory) {
             const next = path_1.default.resolve(`${location}/${file}`);
             const stats = yield fs_1.default.promises.stat(next);
             if (stats.isDirectory() === true)
-                yield iterate(filter)(closure)(next);
+                yield iterate(filter)(closure)(next, visited);
             else if (stats.isFile() && filter(next))
                 closure(next);
         }

package/lib/utils/SourceFinder.js.map

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

package/lib/utils/VersioningStrategy.d.ts

@@ -1,14 +1,49 @@
 import { VERSION_NEUTRAL, VersionValue } from "@nestjs/common/interfaces";
+/**
+ * Resolves the URI versions of a controller method the way NestJS does.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace turns the version metadata of a controller and a method, with the default version of the application, into the version path segments, following NestJS's precedence.
+ * @evidence contracts/common.md#clear-and-simple-design Two functions and one configuration type.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The precedence follows NestJS; no version string is special-cased.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Version precedence and prefix concatenation produce HTTP URI segments and never resolve native filesystem paths.
+ */
 export declare namespace VersioningStrategy {
+    /**
+     * The URI versioning options the adapter reads: the prefix and the default
+     * version.
+     *
+     * @evidence contracts/common.md#principled-implementation The two fields are what NestJS's URI versioning uses to build a version segment.
+     * @evidence contracts/common.md#clear-and-simple-design A two-field 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 names the two fields.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation Version precedence and prefix concatenation produce HTTP URI segments and never resolve native filesystem paths.
+     */
     interface IConfig {
         prefix: string;
         defaultVersion?: VersionValue;
     }
-    const cast: (value: VersionValue | undefined) => Array<string | typeof VERSION_NEUTRAL>;
+    /**
+     * Casts version metadata to a list: a missing value stays absent and a single
+     * value is a one-element list.
+     *
+     * @evidence contracts/common.md#principled-implementation One version becomes a list while absence and an explicit empty list remain distinct, because Nest treats an empty version list as no registered paths rather than inherited versions.
+     * @evidence contracts/common.md#clear-and-simple-design One conditional expression.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts It adds nothing to the values.
+     * @evidence contracts/common.md#meaningful-documentation The comment states the three cases.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation Version precedence and prefix concatenation produce HTTP URI segments and never resolve native filesystem 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 (#1735).
+     *
+     * @evidence contracts/common.md#principled-implementation The first present method, controller or default version list wins, including an empty list that registers no paths. Duplicates are dropped, a neutral version maps to no segment, and absent metadata also maps to no segment; with versioning off the only path has no version.
+     * @evidence contracts/common.md#clear-and-simple-design One function returning the segments, curried on the configuration so a caller can compute the segments per method.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The precedence is NestJS's, and no version is special-cased.
+     * @evidence contracts/common.md#meaningful-documentation The comment states the precedence and the neutral version rule.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation Version precedence and prefix concatenation produce HTTP URI segments and never resolve native filesystem paths.
      */
     const merge: (config: IConfig | undefined) => (props: {
         controller: Array<string | typeof VERSION_NEUTRAL> | undefined;

package/lib/utils/VersioningStrategy.js

@@ -1,29 +1,50 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VersioningStrategy = void 0;
+/**
+ * Resolves the URI versions of a controller method the way NestJS does.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace turns the version metadata of a controller and a method, with the default version of the application, into the version path segments, following NestJS's precedence.
+ * @evidence contracts/common.md#clear-and-simple-design Two functions and one configuration type.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The precedence follows NestJS; no version string is special-cased.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Version precedence and prefix concatenation produce HTTP URI segments and never resolve native filesystem paths.
+ */
 var VersioningStrategy;
 (function (VersioningStrategy) {
-    VersioningStrategy.cast = (value) => value === undefined ? [] : Array.isArray(value) ? value : [value];
+    /**
+     * Casts version metadata to a list: a missing value stays absent and a single
+     * value is a one-element list.
+     *
+     * @evidence contracts/common.md#principled-implementation One version becomes a list while absence and an explicit empty list remain distinct, because Nest treats an empty version list as no registered paths rather than inherited versions.
+     * @evidence contracts/common.md#clear-and-simple-design One conditional expression.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts It adds nothing to the values.
+     * @evidence contracts/common.md#meaningful-documentation The comment states the three cases.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation Version precedence and prefix concatenation produce HTTP URI segments and never resolve native filesystem 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 (#1735).
+     *
+     * @evidence contracts/common.md#principled-implementation The first present method, controller or default version list wins, including an empty list that registers no paths. Duplicates are dropped, a neutral version maps to no segment, and absent metadata also maps to no segment; with versioning off the only path has no version.
+     * @evidence contracts/common.md#clear-and-simple-design One function returning the segments, curried on the configuration so a caller can compute the segments per method.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The precedence is NestJS's, and no version is special-cased.
+     * @evidence contracts/common.md#meaningful-documentation The comment states the precedence and the neutral version rule.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation Version precedence and prefix concatenation produce HTTP URI segments and never resolve native filesystem paths.
      */
     VersioningStrategy.merge = (config) => (props) => {
         var _a, _b;
         if (config === undefined)
             return [""];
-        const chosen = ((_a = props.method) === null || _a === void 0 ? void 0 : _a.length)
-            ? props.method
-            : ((_b = props.controller) === null || _b === void 0 ? void 0 : _b.length)
-                ? props.controller
-                : VersioningStrategy.cast(config.defaultVersion);
+        const chosen = (_b = (_a = props.method) !== null && _a !== void 0 ? _a : props.controller) !== null && _b !== void 0 ? _b : VersioningStrategy.cast(config.defaultVersion);
+        if (chosen === undefined)
+            return [""];
         const unique = [
             ...new Set(chosen),
         ];
-        return unique.length
-            ? unique.map((x) => typeof x === "symbol" ? "" : `${config.prefix}${x}`)
-            : [""];
+        return unique.map((x) => typeof x === "symbol" ? "" : `${config.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":";;;AAEA,IAAiB,kBAAkB,CAsClC;AAtCD,WAAiB,kBAAkB;IAMpB,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;IAEpE;;;;OAIG;IACU,wBAAK,GAChB,CAAC,MAA2B,EAAE,EAAE,CAChC,CAAC,KAGA,EAAY,EAAE;;QACb,IAAI,MAAM,KAAK,SAAS;YAAE,OAAO,CAAC,EAAE,CAAC,CAAC;QACtC,MAAM,MAAM,GAA2C,CAAA,MAAA,KAAK,CAAC,MAAM,0CAC/D,MAAM;YACR,CAAC,CAAC,KAAK,CAAC,MAAM;YACd,CAAC,CAAC,CAAA,MAAA,KAAK,CAAC,UAAU,0CAAE,MAAM;gBACxB,CAAC,CAAC,KAAK,CAAC,UAAU;gBAClB,CAAC,CAAC,uBAAI,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC;QAClC,MAAM,MAAM,GAA2C;YACrD,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC;SACnB,CAAC;QACF,OAAO,MAAM,CAAC,MAAM;YAClB,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CACf,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CACpD;YACH,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACX,CAAC,CAAC;AACN,CAAC,EAtCgB,kBAAkB,aAAlB,kBAAkB,GAAlB,kBAAkB,QAsClC"}
+{"version":3,"file":"VersioningStrategy.js","sourceRoot":"","sources":["../../src/utils/VersioningStrategy.ts"],"names":[],"mappings":";;;AAEA;;;;;;;;GAQG;AACH,IAAiB,kBAAkB,CA2DlC;AA3DD,WAAiB,kBAAkB;IAgBjC;;;;;;;;;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;;;;;;;;;;OAUG;IACU,wBAAK,GAChB,CAAC,MAA2B,EAAE,EAAE,CAChC,CAAC,KAGA,EAAY,EAAE;;QACb,IAAI,MAAM,KAAK,SAAS;YAAE,OAAO,CAAC,EAAE,CAAC,CAAC;QACtC,MAAM,MAAM,eACV,KAAK,CAAC,MAAM,mCAAI,KAAK,CAAC,UAAU,mCAAI,uBAAI,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC;QAClE,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,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CACpD,CAAC;IACJ,CAAC,CAAC;AACN,CAAC,EA3DgB,kBAAkB,aAAlB,kBAAkB,GAAlB,kBAAkB,QA2DlC"}

package/native/go.mod

@@ -10,7 +10,7 @@ require (
 	github.com/microsoft/typescript-go/shim/printer v0.0.0
 	github.com/microsoft/typescript-go/shim/scanner v0.0.0
 	github.com/samchon/ttsc/packages/ttsc v0.0.0
-	github.com/samchon/typia/packages/typia/native v0.0.0-20260922081121-78124b0523b4
+	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-20260922081121-78124b0523b4 h1:ZL20GliY1kZk/PYHwJX+n5cp8ljx8YToGP1wWFtaOYs=
-github.com/samchon/typia/packages/typia/native v0.0.0-20260922081121-78124b0523b4/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/plugin/plan.go

@@ -14,6 +14,16 @@ const (
 	TypiaTransform      = "typia/lib/transform"
 )
 
+// Entry is one plugin of the ordered list that ttsc hands to the host: its name, stage, the `transform` specifier of its configuration, and the whole configuration.
+//
+// @evidence contracts/common.md#principled-implementation The fields are the parts of the payload that classification and option reading need, with the transform specifier lifted out of the configuration map once so every later comparison reads a string.
+// @evidence contracts/common.md#clear-and-simple-design A plain record with no behavior; the two methods answer questions about it.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts It carries the payload as given, and no plugin name or option is special-cased here.
+// @evidence contracts/common.md#meaningful-documentation The comment names the fields and where the value comes from.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation Plugin specifiers are module identifiers and configuration is decoded data, not native file identity.
+// @evidenceExclude contracts/performance.md#efficient-algorithms This record defines data rather than choosing a processing algorithm.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work This record does not coordinate computations across consumers.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The parsed entry stores configuration but does not own its consumers lifetimes.
 type Entry struct {
 	Name      string
 	Stage     string
@@ -21,6 +31,16 @@ type Entry struct {
 	Config    map[string]any
 }
 
+// Plan is the parsed plugin list: the entries in order and one flag for each plugin family present.
+//
+// @evidence contracts/common.md#principled-implementation The three flags are computed once by `ParsePlan` from the classification of every entry, so the callers ask a boolean instead of rescanning the list.
+// @evidence contracts/common.md#clear-and-simple-design A record of three flags and the ordered entries, with one derived accessor.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts It holds parsed data only, and the flags follow from the entries.
+// @evidence contracts/common.md#meaningful-documentation The comment states what each part of the plan means.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation The ordered plugin list and family flags contain no native paths or process handles.
+// @evidenceExclude contracts/performance.md#efficient-algorithms This record defines data rather than choosing a processing algorithm.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work This record does not coordinate computations across consumers.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The plan stores parsed entries; the command owns their lifetime.
 type Plan struct {
 	Core    bool
 	SDK     bool
@@ -28,12 +48,31 @@ type Plan struct {
 	Entries []Entry
 }
 
+// UsesNestia reports whether the plan contains a `@nestia/core` or a `@nestia/sdk` entry, that is, whether any nestia rewrite is wanted.
+//
+// @evidence contracts/common.md#principled-implementation The result is the disjunction of the two family flags, which is exactly the condition under which the nestia passes run.
+// @evidence contracts/common.md#clear-and-simple-design A one-line accessor over two fields, so the condition has one definition.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts It reads the flags and nothing else.
+// @evidence contracts/common.md#meaningful-documentation The comment states the condition.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation The family-flag predicate reads only booleans.
+// @evidence contracts/performance.md#efficient-algorithms Reading two family flags takes constant work and allocates no collection.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work This operation does not coordinate equivalent requests; its result is derived from the supplied value or the current command and compiler program.
+// @evidence contracts/performance.md#bound-retention-and-release-resources No state survives the boolean result.
 func (p Plan) UsesNestia() bool {
 	return p.Core || p.SDK
 }
 
 // Kind reports which plugin family an entry belongs to: "core", "sdk", "typia",
 // or "" when it is none of them.
+//
+// @evidence contracts/common.md#principled-implementation The family is decided by the entry name or by the `transform` specifier compared with the known published specifiers, so an entry written under either spelling of the plugin is recognized, and any other entry is not a family member.
+// @evidence contracts/common.md#clear-and-simple-design A one-line method over the private classifier, so one function owns the naming rules.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The names are the published package specifiers, which are contract constants, and no consumer or path is special-cased.
+// @evidence contracts/common.md#meaningful-documentation The comment lists the four possible results.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation Classification compares published module specifiers, not native paths.
+// @evidence contracts/performance.md#efficient-algorithms Classification trims and compares the name and transform strings, linear in their bytes.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work This operation does not coordinate equivalent requests; its result is derived from the supplied value or the current command and compiler program.
+// @evidence contracts/performance.md#bound-retention-and-release-resources Only temporary trimmed strings are used; no registry entry is retained.
 func (e Entry) Kind() string {
 	return classify(e)
 }
@@ -41,6 +80,15 @@ func (e Entry) Kind() string {
 // BoolConfig reads a boolean option from an entry's resolved plugin config. The
 // second result distinguishes an option explicitly set to false from one that is
 // absent, which the tri-state options depend on.
+//
+// @evidence contracts/common.md#principled-implementation A boolean read from the configuration returns its value and a presence flag, so an option explicitly set to false is distinct from an absent one, which the tri-state options need; a non-boolean value reads as absent.
+// @evidence contracts/common.md#clear-and-simple-design One map lookup and one type assertion.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts It reads only the configuration of the entry it is called on.
+// @evidence contracts/common.md#meaningful-documentation The comment states why the second result exists.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation The lookup reads an in-memory JSON option map.
+// @evidence contracts/performance.md#efficient-algorithms One map lookup and type assertion use expected constant work.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work This operation does not coordinate equivalent requests; its result is derived from the supplied value or the current command and compiler program.
+// @evidence contracts/performance.md#bound-retention-and-release-resources The lookup retains no state or handle.
 func (e Entry) BoolConfig(key string) (bool, bool) {
 	if e.Config == nil {
 		return false, false
@@ -49,13 +97,25 @@ func (e Entry) BoolConfig(key string) (bool, bool) {
 	return value, ok
 }
 
+// ParsePlan parses the ordered plugin payload that ttsc passes as `--plugins-json`.
+//
+// An empty payload is an empty plan. A payload that is not a JSON list of plugin objects is an error naming the flag. JSON null is not an empty list, and a null list entry is not a plugin object. An entry without a stage is a `transform` stage entry.
+//
+// @evidence contracts/common.md#principled-implementation The standard JSON decoder checks the list and object field types. A nil decoded list identifies JSON null rather than an empty array; pointer elements retain null entries for explicit rejection. Each object keeps its order, defaults its stage, supplies its transform string and contributes its classified family flag. A rejected list returns a zero plan even when a prior element was valid.
+// @evidence contracts/common.md#clear-and-simple-design One function that decodes, normalizes, and classifies; the string reading and the classification are private helpers.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The defaults are the ttsc protocol's, and the function trusts the payload only as far as decoding it.
+// @evidence contracts/common.md#meaningful-documentation The comment states the accepted payloads, the error, and the stage default.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation The command payload is a JSON string; plugin transform specifiers remain module identifiers rather than native paths.
+// @evidence contracts/performance.md#efficient-algorithms Decoding is linear in payload bytes and one classification is performed per entry; the output holds one entry per plugin.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work This operation does not coordinate equivalent requests; its result is derived from the supplied value or the current command and compiler program.
+// @evidence contracts/performance.md#bound-retention-and-release-resources Decoded maps and the result list belong to the returned plan and become reclaimable with its caller.
 func ParsePlan(payload string) (Plan, error) {
 	payload = strings.TrimSpace(payload)
 	if payload == "" {
 		return Plan{}, nil
 	}
 
-	var raws []struct {
+	var raws []*struct {
 		Name   string         `json:"name"`
 		Stage  string         `json:"stage"`
 		Config map[string]any `json:"config"`
@@ -63,11 +123,17 @@ func ParsePlan(payload string) (Plan, error) {
 	if err := json.Unmarshal([]byte(payload), &raws); err != nil {
 		return Plan{}, fmt.Errorf("parse plugins-json: %w", err)
 	}
+	if raws == nil {
+		return Plan{}, fmt.Errorf("parse plugins-json: expected a JSON list of plugin objects")
+	}
 
 	plan := Plan{
 		Entries: make([]Entry, 0, len(raws)),
 	}
-	for _, raw := range raws {
+	for index, raw := range raws {
+		if raw == nil {
+			return Plan{}, fmt.Errorf("parse plugins-json: entry %d must be a JSON object", index)
+		}
 		stage := raw.Stage
 		if stage == "" {
 			stage = "transform"

package/native/transform/ast.go

@@ -10,6 +10,15 @@ import (
 // (method, parameter, ...). Empty when the node has no name. A name that is no
 // identifier, a destructured parameter's `{ a }` or a computed method name's
 // `[key]`, reads as its source, since typescript-go's `Text()` panics on it.
+//
+// @evidence contracts/common.md#principled-implementation The identifier text is read through the shim's `NodeText` so that a destructured parameter or a computed method name, whose `Text()` panics in the compiler port, reads as its source, and the quotes of a string-literal name are trimmed.
+// @evidence contracts/common.md#clear-and-simple-design One function with a nil check, one call, and one trim.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts It handles the node kinds the compiler API defines, with no fixture names.
+// @evidence contracts/common.md#meaningful-documentation The comment states the empty result, the source fallback for non-identifiers, and the reason.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation The compiler node name is source text, not a filesystem path.
+// @evidence contracts/performance.md#efficient-algorithms Reading NodeText and trimming quote characters cost at most the name text length.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work This operation does not coordinate equivalent requests; its result is derived from the supplied value or the current command and compiler program.
+// @evidence contracts/performance.md#bound-retention-and-release-resources The returned string borrows or contains source text; the helper retains no node globally.
 func NodeName(node *shimast.Node) string {
 	if node == nil || node.Name() == nil {
 		return ""
@@ -17,7 +26,16 @@ func NodeName(node *shimast.Node) string {
 	return strings.Trim(shimast.NodeText(node.Name()), "\"'")
 }
 
-// NodeText returns the verbatim source slice spanned by a node.
+// NodeText returns the source slice spanned by a node with surrounding whitespace removed.
+//
+// @evidence contracts/common.md#principled-implementation The node's position range is applied to the source text of its file after a bounds check, and the slice is trimmed, so a synthesized node or a range outside the source returns an empty string instead of panicking.
+// @evidence contracts/common.md#clear-and-simple-design One function over the source text accessor.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts It reads the text of the file the node belongs to and adds nothing to it.
+// @evidence contracts/common.md#meaningful-documentation The comment identifies the source range and whitespace trimming.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation Source text and node byte offsets are compiler data rather than native filesystem access.
+// @evidence contracts/performance.md#efficient-algorithms Bounds checks are constant work and TrimSpace scans at most the selected source range.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work This operation does not coordinate equivalent requests; its result is derived from the supplied value or the current command and compiler program.
+// @evidence contracts/performance.md#bound-retention-and-release-resources The returned source substring can keep its source string alive until the caller releases it; no global state or handle is acquired.
 func NodeText(node *shimast.Node) string {
 	if node == nil {
 		return ""

package/native/transform/build.go

@@ -2,17 +2,16 @@ package transform
 
 import (
 	"context"
-	"encoding/json"
 	"flag"
 	"fmt"
 	"io"
 	"os"
 	"path/filepath"
-	"sync"
 	"time"
 
 	shimcompiler "github.com/microsoft/typescript-go/shim/compiler"
 	"github.com/samchon/nestia/packages/core/native/plugin"
+	"github.com/samchon/nestia/packages/core/native/transform/buildoutput"
 	"github.com/samchon/ttsc/packages/ttsc/driver"
 	typiaadapter "github.com/samchon/typia/packages/typia/native/adapter"
 )
@@ -117,18 +116,14 @@ func runBuild(args []string) int {
 	defer prog.Close()
 	releaseTypiaRegistries := registerTypiaDefaultLibraryClassifier(prog)
 	defer releaseTypiaRegistries()
-	if !*quiet {
-		fmt.Fprintf(
-			stdout,
-			"// ttsc-nestia build: tsconfig=%s cwd=%s core=%v sdk=%v typia=%v emit=%v\n",
-			*tsconfigPath,
-			cwd,
-			plan.Core,
-			plan.SDK,
-			plan.Typia,
-			shouldEmit,
-		)
-	}
+	publication := buildoutput.New(buildoutput.Options{
+		TSConfig: *tsconfigPath, CWD: cwd, Manifest: *manifestPath,
+		Core: plan.Core, SDK: plan.SDK, Typia: plan.Typia,
+		Emit: shouldEmit, Quiet: *quiet,
+	}, stdout, driver.DefaultWriteFile)
+	// Publication owns all generated bytes until actual diagnostics accept them.
+	// Every earlier return terminates this session without committing its buffer.
+	defer publication.Finish(false)
 
 	// AST-integration emit: typia's per-file transformer and @nestia/core's own
 	// per-file transformer both run inside tsgo's emit pipeline (sharing the
@@ -141,7 +136,13 @@ func runBuild(args []string) int {
 	if profile {
 		started = time.Now()
 	}
-	newPathsRewriter(prog).applyAll(prog.SourceFiles())
+	// Path remapping serves published output, not type analysis. The private
+	// ForceEmit program used by noEmit has not run semantic diagnostics, so its
+	// checker still resolves imports lazily. Changing those imports to output
+	// paths would make it look for JavaScript files that do not exist.
+	if shouldEmit {
+		newPathsRewriter(prog).applyAll(prog.SourceFiles())
+	}
 	profileBuildStep(profile, "paths-rewrite", started)
 
 	typiaTransform := nestiaTypiaNodeTransform(prog, readTypiaPluginOptions(plan), addDiagnostic)
@@ -160,20 +161,9 @@ func runBuild(args []string) int {
 	}
 	transforms := append([]driver.PluginTransform{typiaTransform, coreTransform}, contributorTransforms...)
 
-	emitted := []string{}
-	pending := []buildPendingOutput{}
-	var writeMu sync.Mutex
 	writeFile := shimcompiler.WriteFile(func(fileName, text string, data *shimcompiler.WriteFileData) error {
 		_ = data
-		if shouldEmit {
-			// TypeScript-Go emits declarations in parallel. Serialize the shared
-			// slices so buffering cannot lose an artifact or race while the
-			// declaration workers call this callback concurrently.
-			writeMu.Lock()
-			defer writeMu.Unlock()
-			emitted = append(emitted, fileName)
-			pending = append(pending, buildPendingOutput{FileName: fileName, Text: text})
-		}
+		publication.Write(fileName, text)
 		return nil
 	})
 
@@ -215,41 +205,15 @@ func runBuild(args []string) int {
 	if emitHasError {
 		return 3
 	}
-	if shouldEmit {
-		for _, output := range pending {
-			if err := driver.DefaultWriteFile(output.FileName, output.Text); err != nil {
-				fmt.Fprintf(stderr, "ttsc-nestia build: emit write failed: %v\n", err)
-				return 3
-			}
-		}
-		if *manifestPath != "" {
-			data, err := json.Marshal(emitted)
-			if err != nil {
-				fmt.Fprintf(stderr, "ttsc-nestia build: manifest marshal failed: %v\n", err)
-				return 3
-			}
-			if err := os.MkdirAll(filepath.Dir(*manifestPath), 0o755); err != nil {
-				fmt.Fprintf(stderr, "ttsc-nestia build: manifest mkdir failed: %v\n", err)
-				return 3
-			}
-			if err := os.WriteFile(*manifestPath, data, 0o644); err != nil {
-				fmt.Fprintf(stderr, "ttsc-nestia build: manifest write failed: %v\n", err)
-				return 3
-			}
-		}
-		if !*quiet {
-			fmt.Fprintf(stdout, "// ttsc-nestia build: emitted=%d files\n", len(emitted))
-		}
+	if err := publication.Finish(true); err != nil {
+		fmt.Fprintf(stderr, "ttsc-nestia build: %v\n", err)
+		return 3
 	}
+
 	profileBuildStep(profile, "total", totalStarted)
 	return 0
 }
 
-type buildPendingOutput struct {
-	FileName string
-	Text     string
-}
-
 // emitDeclarations runs tsgo's standard declaration emitter for the program.
 // tsgo's MarkLinkedReferences pass can nil-panic on some cross-module reference
 // shapes (e.g. a nestia.config.ts that calls NestFactory.create, compiled by the
@@ -275,6 +239,16 @@ func runCheck(args []string) int {
 	return runBuild(append([]string{"--noEmit"}, args...))
 }
 
+// Diagnostic is one transform error: its file, line and column when known, its code, and its message.
+//
+// @evidence contracts/common.md#principled-implementation The record carries what the diagnostic line and the compiler envelope need, and a zero line marks a diagnostic without a position.
+// @evidence contracts/common.md#clear-and-simple-design A five-field record with one formatting method.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The values come from the transforms that report them.
+// @evidence contracts/common.md#meaningful-documentation The comment names the fields and the meaning of an absent position.
+// @evidence contracts/portability.md#os-neutral-implementation File holds the compiler supplied native source path; formatting delegates native relative-path conversion to filepath.Rel instead of treating it as a URL.
+// @evidenceExclude contracts/performance.md#efficient-algorithms This record defines data rather than choosing a processing algorithm.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work This record does not coordinate computations across consumers.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources A diagnostic record stores a path and message; the reporting command owns the collection lifetime.
 type Diagnostic struct {
 	File    string
 	Line    int
@@ -283,6 +257,16 @@ type Diagnostic struct {
 	Message string
 }
 
+// String formats the diagnostic as `file:line:column - error TS(code): message`, with the file made relative to `cwd` when possible, and without the position when the line is unknown.
+//
+// @evidence contracts/common.md#principled-implementation The path is made relative with `filepath.Rel` and the position part is printed only for a positive line, which is the same shape as every other nestia and typia diagnostic.
+// @evidence contracts/common.md#clear-and-simple-design One function with two format strings.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The shape is the protocol that ttsc reads from stderr, not a test-specific format.
+// @evidence contracts/common.md#meaningful-documentation The comment states the two formats and the relative path rule.
+// @evidence contracts/portability.md#os-neutral-implementation filepath.Rel represents native path differences, including cross-volume failure which keeps the original path. The position format is diagnostic protocol text.
+// @evidence contracts/performance.md#efficient-algorithms Relative path calculation and formatting are linear in path and message bytes.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work This operation does not coordinate equivalent requests; its result is derived from the supplied value or the current command and compiler program.
+// @evidence contracts/performance.md#bound-retention-and-release-resources Only the formatted string is returned; no file or writer is opened.
 func (d Diagnostic) String(cwd string) string {
 	file := d.File
 	if rel, err := filepath.Rel(cwd, file); err == nil {
@@ -294,6 +278,16 @@ func (d Diagnostic) String(cwd string) string {
 	return fmt.Sprintf("%s - error TS(%s): %s", file, d.Code, d.Message)
 }
 
+// WriteTypiaTransformDiagnostics writes each diagnostic on its own line to the writer, with files relative to `cwd`.
+//
+// @evidence contracts/common.md#principled-implementation Each diagnostic is written by its own `String`, one per line in the given order, so the output is the concatenation of the formatted diagnostics.
+// @evidence contracts/common.md#clear-and-simple-design One loop over one formatter.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts It writes what it is given, without filtering or reordering.
+// @evidence contracts/common.md#meaningful-documentation The comment states the format and the ordering.
+// @evidence contracts/portability.md#os-neutral-implementation Each diagnostic uses filepath.Rel for native paths and writes through io.Writer; no shell or executable spelling is assembled.
+// @evidence contracts/performance.md#efficient-algorithms Each diagnostic is formatted and written once; work is linear in diagnostic count and total text bytes.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work This operation does not coordinate equivalent requests; its result is derived from the supplied value or the current command and compiler program.
+// @evidence contracts/performance.md#bound-retention-and-release-resources The writer is caller-owned and remains open; the function retains no diagnostic collection after returning.
 func WriteTypiaTransformDiagnostics(out io.Writer, diagnostics []Diagnostic, cwd string) {
 	for _, diag := range diagnostics {
 		fmt.Fprintln(out, diag.String(cwd))