@nestia/sdk 14.0.1 → 14.0.3

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 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,13 +60,17 @@ 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);
       }
     };
@@ -59,6 +83,12 @@ export 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 = async (pattern: string): Promise<string[]> => {
     const absolute: string = path.resolve(pattern);
@@ -77,9 +107,16 @@ export namespace SourceFinder {
     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",
+  ]);
 }

package/src/utils/TemporaryDirectory.ts

@@ -0,0 +1,108 @@
+import fs from "fs";
+import path from "path";
+
+/**
+ * Owns unique temporary directories created by this SDK process.
+ *
+ * Shared parent directories are never registered for deletion. Configuration
+ * modules and runtime modules use the same registry and termination hook, so
+ * one process cannot sweep another process's live compiler inputs.
+ *
+ * @evidence contracts/common.md#principled-implementation Only mkdtemp results created by this process enter the registry; cleanup visits those exact directories and leaves shared parents and sibling processes' directories alone.
+ * @evidence contracts/common.md#clear-and-simple-design Creation and explicit release share one private registry and one exit/signal hook for configuration and runtime materialization.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Ownership is established by creation rather than a directory-name pattern, process ID guess or sweeping the entire project cache.
+ * @evidence contracts/common.md#meaningful-documentation The comment defines ownership, shared-parent preservation and why both compiler paths use one registry.
+ * @evidence contracts/portability.md#os-neutral-implementation Node fs/path operations create and remove native paths. The shared hook sweeps all registered directories before re-raising a termination signal; abrupt OS termination can bypass JavaScript cleanup.
+ * efficient algorithms: Set membership and registration are constant-time on average; a termination sweep visits each retained directory once and removal costs the owned subtree's filesystem entries. Shared parents are never scanned.
+ * reuse equivalent work: Configuration and runtime materializers share the same registry and once-installed exit/signal hooks. Each child has distinct contents and ownership, so allocations and deletions themselves are not substituted by a cached path.
+ * bound retention and release resources: The registry retains one path per unreleased materialization; explicit release forgets it and process termination sweeps the remainder. Failed removals are reported and cause a failing exit rather than hiding them.
+ */
+export namespace TemporaryDirectory {
+  /**
+   * Creates and registers an owned child under a possibly shared parent.
+   *
+   * @evidence contracts/common.md#principled-implementation mkdir establishes the parent and mkdtemp creates an exclusive child before its path is registered, so concurrent processes never acquire ownership of the same directory.
+   * @evidence contracts/common.md#clear-and-simple-design The function creates one child and registers the shared cleanup hook once.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The random child is allocated by the filesystem; no shared parent is eligible for cleanup and existing signal listeners do not suppress this registration.
+   * @evidence contracts/common.md#meaningful-documentation The comment states that the returned child is owned and its parent may be shared.
+   * @evidence contracts/portability.md#os-neutral-implementation Node mkdir/mkdtemp and path.join operate on filesystem paths supplied by the materializers; no URL spelling, separator literal or OS-specific shell creates the child. Signal delivery remains best effort under abrupt termination.
+   * efficient algorithms: The function makes one filesystem allocation and one average constant-time Set insertion; parent creation follows its path depth, and the fixed termination hooks are installed only on the first allocation.
+   * reuse equivalent work: All create calls reuse the one cleanup-hook registration. Directory allocations cannot be shared because each compiler materialization needs independent mutable contents and deletion ownership.
+   * bound retention and release resources: Each returned child transfers its contents to the caller while its path remains registered until explicit remove or process termination. Retention grows with unreleased materializations; process exit bounds the registry lifetime but a long-running process has no independent byte/count limit.
+   */
+  export const create = (parent: string, prefix: string): string => {
+    fs.mkdirSync(parent, { recursive: true });
+    const directory: string = fs.mkdtempSync(path.join(parent, prefix));
+    owned.add(directory);
+    if (!registered) {
+      registered = true;
+      process.once("exit", sweep);
+      for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"] as const)
+        process.once(signal, () => {
+          sweep();
+          process.kill(process.pid, signal);
+        });
+    }
+    return directory;
+  };
+
+  /**
+   * Releases a registered child early; an unowned path is rejected.
+   *
+   * @evidence contracts/common.md#principled-implementation Registry membership is required before recursive removal, and ownership is forgotten only after removal succeeds; an arbitrary or already released path cannot be deleted through this operation.
+   * @evidence contracts/common.md#clear-and-simple-design One membership guard, one removal and one registry deletion own explicit release.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It never broadens the requested deletion to the parent and does not swallow filesystem errors.
+   * @evidence contracts/common.md#meaningful-documentation The comment identifies early release and rejection of unowned paths.
+   * @evidence contracts/portability.md#os-neutral-implementation The returned native path is an ownership token checked by exact Set membership before Node recursive removal; alternate spellings are rejected rather than guessing filesystem case identity or invoking a platform shell.
+   * efficient algorithms: One average constant-time ownership lookup/deletion surrounds removal proportional to that child's filesystem subtree; siblings and shared parents are neither enumerated nor removed.
+   * reuse equivalent work: A deletion is a one-time ownership-consuming effect, not a reusable computation. Explicit releases unregister children so the shared termination sweep does not repeat their removals.
+   * bound retention and release resources: Successful removal releases contents and registry identity together; a failed removal retains ownership for later cleanup and propagates the error. Termination cleanup attempts other retained children and reports failures.
+   */
+  export const remove = (directory: string): void => {
+    if (!owned.has(directory))
+      throw new Error(`Unowned temporary directory: ${directory}`);
+    fs.rmSync(directory, { recursive: true, force: true });
+    owned.delete(directory);
+  };
+
+  /**
+   * Releases all materializations owned by a completed disposable generation.
+   *
+   * Every child is attempted even when another removal fails; failed ownership
+   * remains registered for the termination hook to attempt again.
+   *
+   * @evidence contracts/common.md#principled-implementation The snapshot contains only registered mkdtemp results and remove checks ownership again; all children are attempted and aggregate failure prevents reporting successful cleanup.
+   * @evidence contracts/common.md#clear-and-simple-design One loop delegates deletion to the existing ownership-consuming operation and collects only removal errors.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Shared parents and foreign directories never enter this cleanup, and a failed removal is retained and reported rather than forgotten.
+   * @evidence contracts/common.md#meaningful-documentation The comment states generation-end release, continuation after a failed deletion and retained ownership for termination cleanup.
+   * @evidence contracts/portability.md#os-neutral-implementation The existing native fs/path removal operation handles each exact registered directory; no shell or platform-dependent signal is needed for explicit generation completion.
+   * efficient algorithms: The loop visits each currently owned child once and stores only failed removals; filesystem cost follows their subtrees rather than the shared parent contents.
+   * reuse equivalent work: Explicit disposal consumes ownership, so the later shared exit hook sees no successfully released child and cannot repeat equivalent removals.
+   * bound retention and release resources: Successful completion releases every owned directory and registry entry before the worker reports its result. Failed entries remain owned and an AggregateError propagates the unresolved cleanup.
+   */
+  export const dispose = (): void => {
+    const errors: unknown[] = [];
+    for (const directory of [...owned])
+      try {
+        remove(directory);
+      } catch (error) {
+        errors.push(error);
+      }
+    if (errors.length)
+      throw new AggregateError(errors, "SDK temporary cleanup failed.");
+  };
+}
+
+const owned: Set<string> = new Set();
+let registered = false;
+const sweep = (): void => {
+  for (const directory of owned)
+    try {
+      TemporaryDirectory.remove(directory);
+    } catch (error) {
+      process.stderr.write(
+        `Failed to remove SDK temporary directory: ${String(error)}\n`,
+      );
+      process.exitCode = 1;
+    }
+};

package/src/utils/TsConfigReader.ts

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