@nestia/sdk 14.0.0 → 14.0.2

package/src/utils/MapUtil.ts

@@ -1,14 +1,79 @@
+/**
+ * Helpers for maps.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace holds the get-or-create helper.
+ * @evidence contracts/common.md#clear-and-simple-design One function.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a plain helper.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation MapUtil reads or initializes caller-supplied map entries; it neither interprets keys as native path identities nor owns a process boundary.
+ */
 export namespace MapUtil {
+  /**
+   * Returns the value of a key, creating and storing it when the key is absent.
+   *
+   * Presence is tested with `has`, so a stored falsy value is not created
+   * again. The dictionary may be a `Map` or a `WeakMap`, so a cache keyed by
+   * object identity can leave its entries to the garbage collector.
+   *
+   * @evidence contracts/common.md#principled-implementation The generator runs once per key and its result is stored as it is, in any dictionary with the three members it uses, so the retention of the entries stays the choice of the caller's dictionary.
+   * @evidence contracts/common.md#clear-and-simple-design One check, one call, and one store.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The stored value is returned unchanged.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the presence rule.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation MapUtil.take reads or initializes caller-supplied map entries; it neither interprets keys as native path identities nor owns a process boundary.
+   */
   export function take<Key, T>(
-    dict: Map<Key, T>,
+    dict: IDictionary<Key, T>,
     key: Key,
     generator: () => T,
   ): T {
-    const oldbie: T | undefined = dict.get(key);
-    if (oldbie) return oldbie;
+    if (dict.has(key)) return dict.get(key) as T;
 
     const value: T = generator();
     dict.set(key, value);
     return value;
   }
+
+  /**
+   * The members of a `Map` or a `WeakMap` that {@link take} reads and writes.
+   *
+   * @evidence contracts/common.md#principled-implementation The three members are the presence test, the read and the store that the get-or-create rule needs, and both `Map` and `WeakMap` provide them with these signatures.
+   * @evidence contracts/common.md#clear-and-simple-design A structural type of three members, so no wrapper or second helper is needed for a weakly keyed cache.
+   * @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 dictionaries it admits and the operations it needs.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation MapUtil.IDictionary reads or initializes caller-supplied map entries; it neither interprets keys as native path identities nor owns a process boundary.
+   */
+  export interface IDictionary<Key, T> {
+    /**
+     * Whether the key is present, including a key whose value is `undefined`.
+     *
+     * @evidence contracts/common.md#principled-implementation Presence is a separate question from the stored value, which is what lets a stored falsy value count as present.
+     * @evidence contracts/common.md#clear-and-simple-design One member with the signature that `Map` and `WeakMap` share.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a signature and adds no runtime behavior.
+     * @evidence contracts/common.md#meaningful-documentation The comment states what the member answers or does for {@link take}.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation MapUtil.IDictionary.has reads or initializes caller-supplied map entries; it neither interprets keys as native path identities nor owns a process boundary.
+     */
+    has(key: Key): boolean;
+
+    /**
+     * The value stored for the key, or `undefined` when it is absent.
+     *
+     * @evidence contracts/common.md#principled-implementation The read is only made after a presence test, so `undefined` here always means a stored value.
+     * @evidence contracts/common.md#clear-and-simple-design One member with the signature that `Map` and `WeakMap` share.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a signature and adds no runtime behavior.
+     * @evidence contracts/common.md#meaningful-documentation The comment states what the member answers or does for {@link take}.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation MapUtil.IDictionary.get reads or initializes caller-supplied map entries; it neither interprets keys as native path identities nor owns a process boundary.
+     */
+    get(key: Key): T | undefined;
+
+    /**
+     * Stores the value for the key; the result is ignored.
+     *
+     * @evidence contracts/common.md#principled-implementation The store is the one effect of the get-or-create rule, and the return type is not read because `Map.set` and `WeakMap.set` return different receivers.
+     * @evidence contracts/common.md#clear-and-simple-design One member with the signature that `Map` and `WeakMap` share.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a signature and adds no runtime behavior.
+     * @evidence contracts/common.md#meaningful-documentation The comment states what the member answers or does for {@link take}.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation MapUtil.IDictionary.set reads or initializes caller-supplied map entries; it neither interprets keys as native path identities nor owns a process boundary.
+     */
+    set(key: Key, value: T): unknown;
+  }
 }

package/src/utils/PathUtil.ts

@@ -1,10 +1,48 @@
+import path from "path";
+import { fileURLToPath } from "url";
+
+/**
+ * Helpers for route paths used as accessors, and for source file locations.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace turns a path into accessor names and a source location into a plain path.
+ * @evidence contracts/common.md#clear-and-simple-design Two functions.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts They are plain helpers.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ * @evidence contracts/portability.md#os-neutral-implementation Route accessor spelling uses protocol slashes, while source file URLs are decoded with Node fileURLToPath before native separators are rendered as forward slashes. These operations do not infer filesystem identity or case policy from spelling.
+ */
 export namespace PathUtil {
+  /**
+   * Returns the accessor segments of a path: the segments that are not empty
+   * and not parameters, with dashes and dots replaced by underscores.
+   *
+   * @evidence contracts/common.md#principled-implementation Parameters do not name a namespace and the replaced characters are not valid in an identifier.
+   * @evidence contracts/common.md#clear-and-simple-design One pipeline.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The rule applies to every path.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation This function processes route URL segments rather than native filesystem paths or identities.
+   */
   export const accessors = (path: string) =>
     path
       .split("/")
       .filter((str) => str.length && str[0] !== ":")
       .map(normalize);
 
+  /**
+   * Returns the plain path of a source location: a `file:` URL is decoded to
+   * the path it names, with forward slashes, and any other text is returned as
+   * it is.
+   *
+   * @evidence contracts/common.md#principled-implementation A file URL is percent-encoded, so a path with a space or a non-ASCII character reads back only through the URL decoder, and the platform separator is replaced so the result is the same on every platform.
+   * @evidence contracts/common.md#clear-and-simple-design One conditional over the standard decoder.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Only a `file:` location is decoded; a plain path is never altered.
+   * @evidence contracts/common.md#meaningful-documentation The comment states both inputs and the separator.
+   * @evidence contracts/portability.md#os-neutral-implementation Node fileURLToPath handles platform-specific drive and UNC URL forms and percent decoding. The resulting native separators are rendered as forward slashes for source-location metadata; plain paths keep their original spelling and no filesystem identity comparison is attempted.
+   */
+  export const location = (str: string): string =>
+    str.startsWith("file:")
+      ? fileURLToPath(str).split(path.sep).join("/")
+      : str;
+
   const normalize = (str: string) =>
     str.split("-").join("_").split(".").join("_");
 }

package/src/utils/SdkBundlePath.ts

@@ -0,0 +1,11 @@
+import path from "path";
+
+/** The installed API bundle shared by SDK emission and source exclusion. */
+export const SDK_BUNDLE_PATH: string = path.join(
+  __dirname,
+  "..",
+  "..",
+  "assets",
+  "bundle",
+  "api",
+);

package/src/utils/SdkInputFilter.ts

@@ -0,0 +1,108 @@
+import fs from "fs";
+import path from "path";
+
+import { SDK_BUNDLE_PATH } from "./SdkBundlePath";
+import { SourceFinder } from "./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.
+ */
+export 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.
+   */
+  export const create = async (
+    output: string | undefined,
+  ): Promise<(location: string) => Promise<boolean>> => {
+    if (output === undefined)
+      return async (location) => SourceFinder.isTypeScriptSource(location);
+    const excluded = [
+      {
+        location: identity(path.resolve(output, "functional")),
+        directory: true,
+      },
+      ...(await bundle()).map((asset) => ({
+        location: identity(path.resolve(output, asset.name)),
+        directory: asset.directory,
+      })),
+    ];
+    return async (location) => {
+      if (SourceFinder.isTypeScriptSource(location) === false) return false;
+      const file = identity(location);
+      return excluded.every((entry) =>
+        entry.directory
+          ? within(entry.location, file) === false
+          : entry.location !== file,
+      );
+    };
+  };
+}
+
+let bundlePromise: Promise<{ name: string; directory: boolean }[]> | undefined;
+const bundle = (): Promise<{ name: string; directory: boolean }[]> => {
+  if (bundlePromise === undefined)
+    bundlePromise = (async () =>
+      Promise.all(
+        (
+          await fs.promises.readdir(SDK_BUNDLE_PATH, { withFileTypes: true })
+        ).map(async (entry) => ({
+          name: entry.name,
+          directory: entry.isSymbolicLink()
+            ? (
+                await fs.promises.stat(path.join(SDK_BUNDLE_PATH, entry.name))
+              ).isDirectory()
+            : entry.isDirectory(),
+        })),
+      ))().catch((error) => {
+      bundlePromise = undefined;
+      throw error;
+    });
+  return bundlePromise;
+};
+
+const within = (directory: string, location: string): boolean => {
+  const relative = path.relative(directory, location);
+  return (
+    relative === "" ||
+    (path.isAbsolute(relative) === false &&
+      relative !== ".." &&
+      relative.startsWith(`..${path.sep}`) === false)
+  );
+};
+
+const identity = (location: string): string => {
+  const rest: string[] = [];
+  for (let current = path.resolve(location); ; ) {
+    try {
+      return path.join(fs.realpathSync.native(current), ...rest.reverse());
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+      const parent = path.dirname(current);
+      if (parent === current) throw error;
+      rest.push(path.basename(current));
+      current = parent;
+    }
+  }
+};

package/src/utils/SourceFinder.ts

@@ -2,6 +2,15 @@ import fs from "fs";
 import { glob } from "glob";
 import path from "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.
+ */
 export namespace SourceFinder {
   interface IProps {
     exclude?: string[];
@@ -9,29 +18,40 @@ export namespace SourceFinder {
     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 = async (props: IProps): Promise<string[]> => {
-    const dict: Set<string> = new Set();
+    const dict: Map<string, string> = new Map();
 
-    await emplace(props.filter)(props.include)((str) => dict.add(str));
+    await emplace(props.filter)(props.include)((str) =>
+      dict.set(fs.realpathSync.native(str), str),
+    );
     if (props.exclude?.length)
-      await emplace(props.filter)(props.exclude)((str) => dict.delete(str));
+      await emplace(props.filter)(props.exclude)((str) =>
+        dict.delete(fs.realpathSync.native(str)),
+      );
 
-    return [...dict];
+    return [...dict.values()];
   };
 
   const emplace =
     (filter: (file: string) => Promise<boolean>) =>
     (input: string[]) =>
     async (closure: (location: string) => void): Promise<void> => {
+      const visited: Set<string> = new Set();
       for (const pattern of input) {
-        if (_Is_file(pattern)) {
-          closure(path.resolve(pattern));
-          continue;
-        }
-        for (const file of await _Glob(pattern)) {
+        for (const file of await expand(pattern)) {
           const stats: fs.Stats = await fs.promises.stat(file);
           if (stats.isDirectory() === true)
-            await iterate(filter)(closure)(file);
+            await iterate(filter)(closure)(file, visited);
           else if (stats.isFile() && (await filter(file))) closure(file);
         }
       }
@@ -40,25 +60,63 @@ export namespace SourceFinder {
   const iterate =
     (filter: (location: string) => Promise<boolean>) =>
     (closure: (location: string) => void) =>
-    async (location: string): Promise<void> => {
+    async (location: string, visited: Set<string>): Promise<void> => {
+      const identity: string = await fs.promises.realpath(location);
+      if (visited.has(identity)) return;
+      visited.add(identity);
       const directory: string[] = await fs.promises.readdir(location);
       for (const file of directory) {
         const next: string = path.resolve(`${location}/${file}`);
         const stats: fs.Stats = await fs.promises.stat(next);
 
-        if (stats.isDirectory() === true) await iterate(filter)(closure)(next);
+        if (stats.isDirectory() === true)
+          await iterate(filter)(closure)(next, visited);
         else if (stats.isFile() && (await filter(next))) closure(next);
       }
     };
 
-  const _Glob = async (pattern: string): Promise<string[]> => {
-    const matches = await glob(pattern);
-    return matches.map((str) => path.resolve(str));
+  /**
+   * Files and directories a path or glob pattern names.
+   *
+   * An existing path is taken literally, whatever characters it holds, as a
+   * directory such as `app [v2]` would otherwise read as a character class. For
+   * 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 = async (pattern: string): Promise<string[]> => {
+    const absolute: string = path.resolve(pattern);
+    if (fs.existsSync(absolute)) return [absolute];
+    let base: string = absolute;
+    while (fs.existsSync(base) === false) {
+      const parent: string = path.dirname(base);
+      if (parent === base) return [];
+      base = parent;
+    }
+    const rest: string = path
+      .relative(base, absolute)
+      .split(path.sep)
+      .join("/");
+    const matches: string[] = await glob(rest, { cwd: base });
+    return matches.map((str) => path.resolve(base, str));
   };
 
-  const _Is_file = (pattern: string): boolean =>
-    isTypeScriptSource(pattern) && fs.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.
+   */
   export const isTypeScriptSource = (file: string): boolean => {
     const lower: string = file.toLowerCase();
     return (

package/src/utils/StringUtil.ts

@@ -1,7 +1,44 @@
+/**
+ * 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 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.
+   */
   export const capitalize = (text: string): string =>
     text.charAt(0).toUpperCase() + text.slice(1).toLowerCase();
 
+  /**
+   * 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.
+   */
   export const escapeDuplicate =
     (keep: string[]) =>
     (change: string): string =>
@@ -18,6 +55,15 @@ export 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.
    */
   export const isAnonymous = (str: string): boolean =>
     str === "__type" ||
@@ -27,12 +73,32 @@ export namespace StringUtil {
     str.startsWith("__type-") ||
     str.startsWith("__object-");
 
+  /**
+   * 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.
+   */
   export const isImplicit = (str: string) =>
     str === "object" || isAnonymous(str) || str.includes("readonly [");
 
   /**
-   * 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>`
@@ -47,11 +113,122 @@ export 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.
    */
   export const accessorsOf = (name: string): string[] => {
     const duplicated: RegExpMatchArray | null = name.match(/^(.+)-o(\d+)$/);
-    return duplicated === null
-      ? name.split(".")
-      : [...duplicated[1]!.split("."), `o${duplicated[2]!}`];
+    return (
+      duplicated === null
+        ? name.split(".")
+        : [...duplicated[1]!.split("."), `o${duplicated[2]!}`]
+    ).map((segment, index, accessors) =>
+      identifier(segment, index === 0, index === accessors.length - 1),
+    );
+  };
+
+  // Unicode IdentifierStart/IdentifierPart additionally admit $ and _, and
+  // IdentifierPart admits the two joining controls. Iterate code points so a
+  // supplementary letter is kept whole and an isolated surrogate is encoded.
+  const identifier = (
+    segment: string,
+    root: boolean,
+    leaf: boolean,
+  ): string => {
+    const fragments: string[] = [];
+    for (const point of segment) {
+      const valid = (
+        fragments.length === 0 ? identifierStart : identifierPart
+      ).test(point);
+      fragments.push(
+        valid
+          ? point
+          : `_x${point.codePointAt(0)!.toString(16).toUpperCase()}_`,
+      );
+    }
+    const output = fragments.join("");
+    if (output.length === 0) return "_";
+    return reserved.has(output) ||
+      (root && output === "await") ||
+      ((root || leaf) && typeNames.has(output))
+      ? `_${output}`
+      : output;
   };
+
+  const identifierStart = /^[$_\p{ID_Start}]$/u;
+  const identifierPart = /^[$_\u200C\u200D\p{ID_Continue}]$/u;
+
+  // ECMAScript strict/module bindings and names TypeScript reserves for its
+  // intrinsic types. Contextual labels such as type, async and readonly remain
+  // ordinary identifiers here.
+  const reserved = new Set([
+    "break",
+    "case",
+    "catch",
+    "class",
+    "const",
+    "continue",
+    "debugger",
+    "default",
+    "delete",
+    "do",
+    "else",
+    "enum",
+    "export",
+    "extends",
+    "false",
+    "finally",
+    "for",
+    "function",
+    "if",
+    "import",
+    "in",
+    "instanceof",
+    "new",
+    "null",
+    "return",
+    "super",
+    "switch",
+    "this",
+    "throw",
+    "true",
+    "try",
+    "typeof",
+    "var",
+    "void",
+    "while",
+    "with",
+    "implements",
+    "interface",
+    "let",
+    "package",
+    "private",
+    "protected",
+    "public",
+    "static",
+    "yield",
+  ]);
+
+  // These names are forbidden for type aliases and imported bindings, but a
+  // nested namespace can use them. Await likewise remains legal inside a
+  // namespace, whose scope is distinct from the surrounding external module.
+  const typeNames = new Set([
+    "any",
+    "unknown",
+    "never",
+    "number",
+    "bigint",
+    "boolean",
+    "string",
+    "symbol",
+    "object",
+    "undefined",
+  ]);
 }