@nestia/sdk 14.0.1 → 14.0.2

package/lib/utils/SdkInputFilter.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Separates authored TypeScript inputs from files owned by SDK generation.
+ *
+ * Each filter owns one output directory. Installed bundle metadata is shared;
+ * output-specific native paths are never stored in the process-wide cache.
+ *
+ * @evidence contracts/common.md#principled-implementation Source extensions are checked before generated functional descendants and exact bundled output files are excluded. Native identities and path.relative distinguish descendants from prefix-sharing siblings.
+ * @evidence contracts/common.md#clear-and-simple-design One filter factory separates source selection from controller compilation; its private helpers own bundle metadata and filesystem identity.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Exclusions come from the actual installed bundle and the generated functional directory, without fixture names or a cached caller output.
+ * @evidence contracts/common.md#meaningful-documentation The comment states filter ownership and the cache's output-independent content.
+ * @evidence contracts/portability.md#os-neutral-implementation Native real paths resolve existing ancestors and path.relative judges directory containment; neither OS names nor lowercasing assume a volume's case or link policy.
+ * efficient algorithms: Successful installed bundle entries are scanned once and each filter builds its exclusion roots once; a candidate resolves one identity and compares at most the bundle entry count plus functional root, with no recursive source scan here.
+ * reuse equivalent work: Concurrent filters share installed bundle names and kinds; a failed metadata read clears the promise so a later request can retry. Output-specific resolved roots belong to each factory call, so another output cannot reuse the first caller's paths.
+ * bound retention and release resources: The one metadata promise retains only the fixed installed bundle population. Output roots live in the returned filter closure and are released with its source-discovery call; there is no growing per-output registry.
+ */
+export declare namespace SdkInputFilter {
+    /**
+     * Creates the source predicate for one configuration's output, or an
+     * extension-only predicate when no SDK output is configured.
+     *
+     * @evidence contracts/common.md#principled-implementation The predicate accepts regular TypeScript source names, excludes descendants of this output's functional directory and the bundle's exact file/directory identities, and leaves same-named authored files outside that output eligible.
+     * @evidence contracts/common.md#clear-and-simple-design Output roots are prepared before discovery and captured in one returned predicate, so compilation never owns these path-selection rules.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Every configuration resolves its own output; no first-call output, substring containment or operating-system case guess substitutes for filesystem identity.
+     * @evidence contracts/common.md#meaningful-documentation The comment documents both output-bound and extension-only modes.
+     * @evidence contracts/portability.md#os-neutral-implementation The nearest existing ancestor carries actual case/link identity and nonexistent suffixes retain their native spelling; path.relative rejects sibling and cross-root locations without protocol-path comparisons.
+     * efficient algorithms: Factory preparation is linear in installed bundle entries and each predicate call scans those prepared roots after one candidate identity resolution. It reuses the discovery traversal rather than walking inputs again.
+     * reuse equivalent work: Output-independent metadata comes from one shared in-flight or successful promise; rejection clears it for retry, while each output-specific root array is computed for its own factory call and is not shared across incompatible configurations.
+     * bound retention and release resources: The predicate retains only this configuration's fixed exclusion roots and no candidate history; once SourceFinder finishes, that closure has no persistent owner.
+     */
+    const create: (output: string | undefined) => Promise<(location: string) => Promise<boolean>>;
+}

package/lib/utils/SdkInputFilter.js

@@ -0,0 +1,115 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SdkInputFilter = void 0;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const SdkBundlePath_1 = require("./SdkBundlePath");
+const SourceFinder_1 = require("./SourceFinder");
+/**
+ * Separates authored TypeScript inputs from files owned by SDK generation.
+ *
+ * Each filter owns one output directory. Installed bundle metadata is shared;
+ * output-specific native paths are never stored in the process-wide cache.
+ *
+ * @evidence contracts/common.md#principled-implementation Source extensions are checked before generated functional descendants and exact bundled output files are excluded. Native identities and path.relative distinguish descendants from prefix-sharing siblings.
+ * @evidence contracts/common.md#clear-and-simple-design One filter factory separates source selection from controller compilation; its private helpers own bundle metadata and filesystem identity.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Exclusions come from the actual installed bundle and the generated functional directory, without fixture names or a cached caller output.
+ * @evidence contracts/common.md#meaningful-documentation The comment states filter ownership and the cache's output-independent content.
+ * @evidence contracts/portability.md#os-neutral-implementation Native real paths resolve existing ancestors and path.relative judges directory containment; neither OS names nor lowercasing assume a volume's case or link policy.
+ * efficient algorithms: Successful installed bundle entries are scanned once and each filter builds its exclusion roots once; a candidate resolves one identity and compares at most the bundle entry count plus functional root, with no recursive source scan here.
+ * reuse equivalent work: Concurrent filters share installed bundle names and kinds; a failed metadata read clears the promise so a later request can retry. Output-specific resolved roots belong to each factory call, so another output cannot reuse the first caller's paths.
+ * bound retention and release resources: The one metadata promise retains only the fixed installed bundle population. Output roots live in the returned filter closure and are released with its source-discovery call; there is no growing per-output registry.
+ */
+var SdkInputFilter;
+(function (SdkInputFilter) {
+    /**
+     * Creates the source predicate for one configuration's output, or an
+     * extension-only predicate when no SDK output is configured.
+     *
+     * @evidence contracts/common.md#principled-implementation The predicate accepts regular TypeScript source names, excludes descendants of this output's functional directory and the bundle's exact file/directory identities, and leaves same-named authored files outside that output eligible.
+     * @evidence contracts/common.md#clear-and-simple-design Output roots are prepared before discovery and captured in one returned predicate, so compilation never owns these path-selection rules.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Every configuration resolves its own output; no first-call output, substring containment or operating-system case guess substitutes for filesystem identity.
+     * @evidence contracts/common.md#meaningful-documentation The comment documents both output-bound and extension-only modes.
+     * @evidence contracts/portability.md#os-neutral-implementation The nearest existing ancestor carries actual case/link identity and nonexistent suffixes retain their native spelling; path.relative rejects sibling and cross-root locations without protocol-path comparisons.
+     * efficient algorithms: Factory preparation is linear in installed bundle entries and each predicate call scans those prepared roots after one candidate identity resolution. It reuses the discovery traversal rather than walking inputs again.
+     * reuse equivalent work: Output-independent metadata comes from one shared in-flight or successful promise; rejection clears it for retry, while each output-specific root array is computed for its own factory call and is not shared across incompatible configurations.
+     * bound retention and release resources: The predicate retains only this configuration's fixed exclusion roots and no candidate history; once SourceFinder finishes, that closure has no persistent owner.
+     */
+    SdkInputFilter.create = (output) => __awaiter(this, void 0, void 0, function* () {
+        if (output === undefined)
+            return (location) => __awaiter(this, void 0, void 0, function* () { return SourceFinder_1.SourceFinder.isTypeScriptSource(location); });
+        const excluded = [
+            {
+                location: identity(path_1.default.resolve(output, "functional")),
+                directory: true,
+            },
+            ...(yield bundle()).map((asset) => ({
+                location: identity(path_1.default.resolve(output, asset.name)),
+                directory: asset.directory,
+            })),
+        ];
+        return (location) => __awaiter(this, void 0, void 0, function* () {
+            if (SourceFinder_1.SourceFinder.isTypeScriptSource(location) === false)
+                return false;
+            const file = identity(location);
+            return excluded.every((entry) => entry.directory
+                ? within(entry.location, file) === false
+                : entry.location !== file);
+        });
+    });
+})(SdkInputFilter || (exports.SdkInputFilter = SdkInputFilter = {}));
+let bundlePromise;
+const bundle = () => {
+    if (bundlePromise === undefined)
+        bundlePromise = (() => __awaiter(void 0, void 0, void 0, function* () {
+            return Promise.all((yield fs_1.default.promises.readdir(SdkBundlePath_1.SDK_BUNDLE_PATH, { withFileTypes: true })).map((entry) => __awaiter(void 0, void 0, void 0, function* () {
+                return ({
+                    name: entry.name,
+                    directory: entry.isSymbolicLink()
+                        ? (yield fs_1.default.promises.stat(path_1.default.join(SdkBundlePath_1.SDK_BUNDLE_PATH, entry.name))).isDirectory()
+                        : entry.isDirectory(),
+                });
+            })));
+        }))().catch((error) => {
+            bundlePromise = undefined;
+            throw error;
+        });
+    return bundlePromise;
+};
+const within = (directory, location) => {
+    const relative = path_1.default.relative(directory, location);
+    return (relative === "" ||
+        (path_1.default.isAbsolute(relative) === false &&
+            relative !== ".." &&
+            relative.startsWith(`..${path_1.default.sep}`) === false));
+};
+const identity = (location) => {
+    const rest = [];
+    for (let current = path_1.default.resolve(location);;) {
+        try {
+            return path_1.default.join(fs_1.default.realpathSync.native(current), ...rest.reverse());
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+            const parent = path_1.default.dirname(current);
+            if (parent === current)
+                throw error;
+            rest.push(path_1.default.basename(current));
+            current = parent;
+        }
+    }
+};
+//# sourceMappingURL=SdkInputFilter.js.map

package/lib/utils/SdkInputFilter.js.map

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

package/lib/utils/SourceFinder.d.ts

@@ -1,9 +1,28 @@
+/**
+ * Finds source files by path, directory, or glob.
+ *
+ * @evidence contracts/common.md#principled-implementation Each pattern is resolved to files or directories, directories are walked, the filter is applied to files, and the excluded set is subtracted.
+ * @evidence contracts/common.md#clear-and-simple-design Three public functions and private walkers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The filter is the caller's.
+ * @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, and accepted files are keyed by filesystem real path while returned locations retain their discovered spelling, so include and exclude aliases identify the same file.
+ */
 export declare namespace SourceFinder {
     interface IProps {
         exclude?: string[];
         include: string[];
         filter: (location: string) => Promise<boolean>;
     }
+    /**
+     * Returns the files matched by the include patterns and not by the exclude
+     * patterns and accepted by the filter.
+     *
+     * @evidence contracts/common.md#principled-implementation Every pattern is expanded, existing paths remain literal, and only regular files accepted by the filter enter either collection; the exclusion runs the same collection removing instead of adding.
+     * @evidence contracts/common.md#clear-and-simple-design One function that runs the collection twice.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The result follows the patterns and the filter.
+     * @evidence contracts/common.md#meaningful-documentation The comment states the result.
+     * @evidence contracts/portability.md#os-neutral-implementation It composes the include and exclude collections over native absolute paths and returns them as `path.resolve` spelled them. A directory is walked through `stat`, which follows links; each include or exclude collection keeps a real-path set, so a linked directory is entered once and a link back to an ancestor is skipped.
+     */
     export const find: (props: IProps) => Promise<string[]>;
     /**
      * Files and directories a path or glob pattern names.
@@ -13,8 +32,24 @@ export declare namespace SourceFinder {
      * a pattern, the longest existing ancestor is the literal base and only the
      * rest is globbed, with `/` separators, since glob reads a Windows backslash
      * as an escape.
+     *
+     * @evidence contracts/common.md#principled-implementation The wildcard part is matched below the part of the path that exists, and a base that does not exist matches nothing.
+     * @evidence contracts/common.md#clear-and-simple-design One function.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts It follows the filesystem.
+     * @evidence contracts/common.md#meaningful-documentation The comment states the two cases.
+     * @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, the remainder is rewritten from `path.sep` to `/`, and the matches are resolved against that base, so a drive letter or a UNC root never enters the pattern.
      */
     export const expand: (pattern: string) => Promise<string[]>;
+    /**
+     * Reports whether a file is a TypeScript source: an extension of `ts`, `mts`,
+     * or `cts` that is not a declaration file.
+     *
+     * @evidence contracts/common.md#principled-implementation The check is on the lower-cased name, and declaration files are excluded because they hold no runtime code.
+     * @evidence contracts/common.md#clear-and-simple-design One expression.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts It is by extension.
+     * @evidence contracts/common.md#meaningful-documentation The comment states the accepted extensions.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation The function judges the spelling of a name the caller supplies and opens no path, so it owns no filesystem or process decision; extensions are compared lower-cased on every platform by design.
+     */
     export const isTypeScriptSource: (file: string) => boolean;
     export {};
 }

package/lib/utils/SourceFinder.js

@@ -16,38 +16,58 @@ 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 Each pattern is resolved to files or directories, directories are walked, the filter is applied to files, and the excluded set is subtracted.
+ * @evidence contracts/common.md#clear-and-simple-design Three public functions and private walkers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The filter is the caller's.
+ * @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, and accepted files are keyed by filesystem real path while returned locations retain their discovered spelling, so include and exclude aliases identify the same file.
+ */
 var SourceFinder;
 (function (SourceFinder) {
+    /**
+     * Returns the files matched by the include patterns and not by the exclude
+     * patterns and accepted by the filter.
+     *
+     * @evidence contracts/common.md#principled-implementation Every pattern is expanded, existing paths remain literal, and only regular files accepted by the filter enter either collection; the exclusion runs the same collection removing instead of adding.
+     * @evidence contracts/common.md#clear-and-simple-design One function that runs the collection twice.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The result follows the patterns and the filter.
+     * @evidence contracts/common.md#meaningful-documentation The comment states the result.
+     * @evidence contracts/portability.md#os-neutral-implementation It composes the include and exclude collections over native absolute paths and returns them as `path.resolve` spelled them. A directory is walked through `stat`, which follows links; each include or exclude collection keeps a real-path set, so a linked directory is entered once and a link back to an ancestor is skipped.
+     */
     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) {
-            if (_Is_file(pattern)) {
-                closure(path_1.default.resolve(pattern));
-                continue;
-            }
             for (const file of yield SourceFinder.expand(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() && (yield 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() && (yield filter(next)))
                 closure(next);
         }
@@ -60,6 +80,12 @@ var SourceFinder;
      * a pattern, the longest existing ancestor is the literal base and only the
      * rest is globbed, with `/` separators, since glob reads a Windows backslash
      * as an escape.
+     *
+     * @evidence contracts/common.md#principled-implementation The wildcard part is matched below the part of the path that exists, and a base that does not exist matches nothing.
+     * @evidence contracts/common.md#clear-and-simple-design One function.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts It follows the filesystem.
+     * @evidence contracts/common.md#meaningful-documentation The comment states the two cases.
+     * @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, the remainder is rewritten from `path.sep` to `/`, and the matches are resolved against that base, so a drive letter or a UNC root never enters the pattern.
      */
     SourceFinder.expand = (pattern) => __awaiter(this, void 0, void 0, function* () {
         const absolute = path_1.default.resolve(pattern);
@@ -79,7 +105,16 @@ var SourceFinder;
         const matches = yield (0, glob_1.glob)(rest, { cwd: base });
         return matches.map((str) => path_1.default.resolve(base, str));
     });
-    const _Is_file = (pattern) => SourceFinder.isTypeScriptSource(pattern) && fs_1.default.existsSync(pattern);
+    /**
+     * Reports whether a file is a TypeScript source: an extension of `ts`, `mts`,
+     * or `cts` that is not a declaration file.
+     *
+     * @evidence contracts/common.md#principled-implementation The check is on the lower-cased name, and declaration files are excluded because they hold no runtime code.
+     * @evidence contracts/common.md#clear-and-simple-design One expression.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts It is by extension.
+     * @evidence contracts/common.md#meaningful-documentation The comment states the accepted extensions.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation The function judges the spelling of a name the caller supplies and opens no path, so it owns no filesystem or process decision; extensions are compared lower-cased on every platform by design.
+     */
     SourceFinder.isTypeScriptSource = (file) => {
         const lower = file.toLowerCase();
         return (/\.(?:[cm]?ts)$/.test(lower) &&

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/StringUtil.d.ts

@@ -1,5 +1,42 @@
+/**
+ * String helpers of the SDK generator.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace holds capitalization, duplicate escaping, and the recognition of anonymous type names.
+ * @evidence contracts/common.md#clear-and-simple-design Five small functions.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The markers are the spellings typia uses for anonymous types.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ * efficient algorithms: The namespace groups string operations; each function owns its scan or duplicate lookup.
+ * reuse equivalent work: The namespace coordinates no shared computation.
+ * bound retention and release resources: The namespace owns no input-dependent retained state or handles.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation StringUtil transforms declaration names and textual content; separators in accessor names are language syntax rather than native filesystem separators.
+ */
 export declare namespace StringUtil {
+    /**
+     * Upper-cases the first character and lower-cases the rest.
+     *
+     * @evidence contracts/common.md#principled-implementation The first character is transformed alone and the rest is lower-cased.
+     * @evidence contracts/common.md#clear-and-simple-design One expression.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts It applies to every input.
+     * @evidence contracts/common.md#meaningful-documentation The comment states the rule.
+     * efficient algorithms: Case conversion and copying process the input characters once with proportional returned string storage.
+     * reuse equivalent work: Case conversion coordinates no shared requests.
+     * bound retention and release resources: The returned string belongs to the caller; this operation retains no state or handles.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation StringUtil.capitalize transforms declaration names and textual content; separators in accessor names are language syntax rather than native filesystem separators.
+     */
     const capitalize: (text: string) => string;
+    /**
+     * Returns the name with underscores prefixed until it is not in the list of
+     * names to keep clear of.
+     *
+     * @evidence contracts/common.md#principled-implementation The recursion adds one underscore at a time, so the result is the shortest such name.
+     * @evidence contracts/common.md#clear-and-simple-design One curried function.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The rule is generic.
+     * @evidence contracts/common.md#meaningful-documentation The comment states the result.
+     * efficient algorithms: Each occupied candidate scans the supplied keep list and adds one underscore; the number of recursive candidates is bounded by distinct occupied spellings in that list, with string comparison and copying costs proportional to candidate lengths.
+     * reuse equivalent work: The caller supplies the current keep list; this operation coordinates no shared computation between calls.
+     * bound retention and release resources: The closure retains only the caller's keep list for its own lifetime and owns no history, handles or tasks.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation StringUtil.escapeDuplicate transforms declaration names and textual content; separators in accessor names are language syntax rather than native filesystem separators.
+     */
     const escapeDuplicate: (keep: string[]) => (change: string) => string;
     /**
      * The marker names typia gives a type that has no identity of its own: an
@@ -12,12 +49,41 @@ export declare namespace StringUtil {
      * whether its name collided. Three call sites carried their own copy of this
      * list, only one of them learned the `-` spelling, and the two that did not
      * declared and referenced modules that do not exist.
+     *
+     * @evidence contracts/common.md#principled-implementation The names `__type` and `__object` and their dotted or dashed forms are the anonymous markers, so the predicate is a list of those spellings.
+     * @evidence contracts/common.md#clear-and-simple-design One expression.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The list is the shared definition that the generators use.
+     * @evidence contracts/common.md#meaningful-documentation The comment states the markers.
+     * efficient algorithms: A fixed number of equalities and constant-length prefix checks inspect each name without graph traversal or input-dependent state.
+     * reuse equivalent work: This predicate coordinates no shared computation.
+     * bound retention and release resources: This predicate retains no input or handles.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation StringUtil.isAnonymous transforms declaration names and textual content; separators in accessor names are language syntax rather than native filesystem separators.
      */
     const isAnonymous: (str: string) => boolean;
+    /**
+     * Reports whether a type name is implicit: the name `object`, an anonymous
+     * name, or a readonly tuple.
+     *
+     * @evidence contracts/common.md#principled-implementation It extends the anonymous test with the two other names that cannot be referenced.
+     * @evidence contracts/common.md#clear-and-simple-design One expression over `isAnonymous`.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts It shares the anonymous list.
+     * @evidence contracts/common.md#meaningful-documentation The comment states the cases.
+     * efficient algorithms: Fixed name checks and one substring search take at most linear time in the name's length, without allocating a graph or cache.
+     * reuse equivalent work: This predicate coordinates no shared computation.
+     * bound retention and release resources: This predicate retains no input or handles.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation StringUtil.isImplicit transforms declaration names and textual content; separators in accessor names are language syntax rather than native filesystem separators.
+     */
     const isImplicit: (str: string) => boolean;
     /**
-     * Split a typia metadata name into the accessor path a generated SDK declares
-     * it under.
+     * Splits a metadata name into legal TypeScript declaration accessors.
+     *
+     * Component keys remain unchanged: this conversion owns only the cloned
+     * declaration, reference and import spelling. Identifier code points survive;
+     * other code points are written as hexadecimal identifier fragments. Reserved
+     * binding and intrinsic type names receive an underscore. The route
+     * dictionary compares these same accessors when separating unequal component
+     * definitions, including a source name which already contains an escaped
+     * fragment.
      *
      * Typia separates a qualified name with `.` and a _duplicated_ name from its
      * disambiguating counter with a trailing `-o<counter>`
@@ -32,6 +98,15 @@ export declare namespace StringUtil {
      * guessing at the name is what the new separator makes possible -- `-` cannot
      * occur in a qualified name, so unlike the old spelling this cannot be
      * confused with one.
+     *
+     * @evidence contracts/common.md#principled-implementation The historical trailing duplicate marker and namespace dots are interpreted before each segment is encoded under Unicode IdentifierStart/IdentifierPart and strict binding/type-name restrictions. All clone declarations, references, imports and collision slots consume this same spelling; raw metadata component keys are not rewritten.
+     * @evidence contracts/common.md#clear-and-simple-design One accessor operation delegates segment encoding to a private helper with language-defined reserved names.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Encoding depends on identifier grammar, not a DTO or consumer name; the existing semantic collision partition separates unequal definitions whose accessors coincide.
+     * @evidence contracts/common.md#meaningful-documentation The comment distinguishes raw component keys from TypeScript accessors and explains Unicode encoding, reserved bindings and duplicate compatibility.
+     * efficient algorithms: Each name and its code points are scanned once, with output space proportional to the encoded spelling; reserved-name lookup uses a fixed set.
+     * reuse equivalent work: This pure conversion coordinates no completed or in-flight work across consumers; its callers own graph and dictionary reuse.
+     * bound retention and release resources: The fixed grammar set has no input-dependent history; temporary accessor strings belong to the caller and no handles or tasks are retained.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation StringUtil.accessorsOf transforms declaration names and textual content; separators in accessor names are language syntax rather than native filesystem separators.
      */
     const accessorsOf: (name: string) => string[];
 }