@nestia/sdk 14.0.0 → 14.0.2

package/src/structures/ITypedApplication.ts

@@ -4,6 +4,16 @@ import { ITypedHttpRoute } from "./ITypedHttpRoute";
 import { ITypedMcpRoute } from "./ITypedMcpRoute";
 import { ITypedWebSocketRoute } from "./ITypedWebSocketRoute";
 
+/**
+ * The typed application: the project, the metadata dictionary, and the typed
+ * routes.
+ *
+ * @evidence contracts/common.md#principled-implementation The record is the input of every generator.
+ * @evidence contracts/common.md#clear-and-simple-design A flat record with no behavior.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what the type describes; its members are named for their meaning.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation ITypedApplication describes protocol or type metadata; any embedded import/source record preserves the identity supplied by its owner. This declaration defines no native path conversion or process boundary.
+ */
 export interface ITypedApplication {
   project: INestiaProject;
   collection: IMetadataDictionary;

package/src/structures/ITypedHttpRoute.ts

@@ -6,10 +6,28 @@ import { ITypedHttpRouteException } from "./ITypedHttpRouteException";
 import { ITypedHttpRouteParameter } from "./ITypedHttpRouteParameter";
 import { ITypedHttpRouteSuccess } from "./ITypedHttpRouteSuccess";
 
+/**
+ * A typed HTTP route: one path of an operation with its parameters split by
+ * kind, its success, its exceptions, and its documentation.
+ *
+ * @evidence contracts/common.md#principled-implementation The reflected operation is expanded per path and its parameters are classified for the generators.
+ * @evidence contracts/common.md#clear-and-simple-design A flat record with no behavior.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what the type describes; its members are named for their meaning.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation ITypedHttpRoute describes protocol or type metadata; any embedded import/source record preserves the identity supplied by its owner. This declaration defines no native path conversion or process boundary.
+ */
 export interface ITypedHttpRoute {
   protocol: "http";
   function: Function;
   controller: IReflectController;
+  /**
+   * Property key of the controller method.
+   *
+   * {@link name} is the SDK function's name, which the accessor analysis
+   * renames: a reserved word such as `delete` becomes `_delete`. Metadata the
+   * method's decorators define, and what names the method, read this key.
+   */
+  key: string;
   name: string;
   method: string;
   path: string;

package/src/structures/ITypedHttpRouteException.ts

@@ -1,12 +1,25 @@
+import { OpenApi } from "@typia/interface";
+
 import { MetadataSchema } from "../internal/legacy";
 import { IReflectType } from "./IReflectType";
 
+/**
+ * A typed exception: its status, description, examples, type, and resolved
+ * metadata.
+ *
+ * @evidence contracts/common.md#principled-implementation The resolved metadata is what the SDK and the Swagger generators print.
+ * @evidence contracts/common.md#clear-and-simple-design A flat record with no behavior.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what the type describes; its members are named for their meaning.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation ITypedHttpRouteException describes protocol or type metadata; any embedded import/source record preserves the identity supplied by its owner. This declaration defines no native path conversion or process boundary.
+ */
 export interface ITypedHttpRouteException {
   // BASIC PROPERTIES
   status: number | "2XX" | "3XX" | "4XX" | "5XX";
   description: string | null;
   example: any;
-  examples: Record<string, any>;
+  /** Named examples, as OpenAPI Example Objects. */
+  examples: Record<string, OpenApi.IExample>;
 
   // REFLECTED PROPERTIES
   type: IReflectType;

package/src/structures/ITypedHttpRouteParameter.ts

@@ -1,14 +1,33 @@
+import { OpenApi } from "@typia/interface";
 import { IJsDocTagInfo } from "typia";
 
 import { MetadataSchema } from "../internal/legacy";
 import { IReflectType } from "./IReflectType";
 
+/**
+ * A typed parameter of a route: a body, headers, a path parameter, or a query.
+ *
+ * @evidence contracts/common.md#principled-implementation The union is discriminated by `category`, and each member carries the resolved metadata.
+ * @evidence contracts/common.md#clear-and-simple-design A union of four records.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what the type describes; its members are named for their meaning.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation ITypedHttpRouteParameter describes protocol or type metadata; any embedded import/source record preserves the identity supplied by its owner. This declaration defines no native path conversion or process boundary.
+ */
 export type ITypedHttpRouteParameter =
   | ITypedHttpRouteParameter.IBody
   | ITypedHttpRouteParameter.IHeaders
   | ITypedHttpRouteParameter.IPath
   | ITypedHttpRouteParameter.IQuery;
 export namespace ITypedHttpRouteParameter {
+  /**
+   * The typed form of a body parameter.
+   *
+   * @evidence contracts/common.md#principled-implementation The record extends the shared base with the members its category adds.
+   * @evidence contracts/common.md#clear-and-simple-design A record extending the shared base.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the type describes; its members are named for their meaning.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation ITypedHttpRouteParameter.IBody describes protocol or type metadata; any embedded import/source record preserves the identity supplied by its owner. This declaration defines no native path conversion or process boundary.
+   */
   export interface IBody extends IBase<"body"> {
     contentType:
       | "application/json"
@@ -17,12 +36,39 @@ export namespace ITypedHttpRouteParameter {
       | "text/plain";
     encrypted: boolean;
   }
+  /**
+   * The typed form of a headers parameter.
+   *
+   * @evidence contracts/common.md#principled-implementation The record extends the shared base with the members its category adds.
+   * @evidence contracts/common.md#clear-and-simple-design A record extending the shared base.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the type describes; its members are named for their meaning.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation ITypedHttpRouteParameter.IHeaders describes protocol or type metadata; any embedded import/source record preserves the identity supplied by its owner. This declaration defines no native path conversion or process boundary.
+   */
   export interface IHeaders extends IBase<"headers"> {
     field: string | null;
   }
+  /**
+   * The typed form of a path parameter parameter.
+   *
+   * @evidence contracts/common.md#principled-implementation The record extends the shared base with the members its category adds.
+   * @evidence contracts/common.md#clear-and-simple-design A record extending the shared base.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the type describes; its members are named for their meaning.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation ITypedHttpRouteParameter.IPath describes protocol or type metadata; any embedded import/source record preserves the identity supplied by its owner. This declaration defines no native path conversion or process boundary.
+   */
   export interface IPath extends IBase<"param"> {
     field: string;
   }
+  /**
+   * The typed form of a query parameter.
+   *
+   * @evidence contracts/common.md#principled-implementation The record extends the shared base with the members its category adds.
+   * @evidence contracts/common.md#clear-and-simple-design A record extending the shared base.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the type describes; its members are named for their meaning.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation ITypedHttpRouteParameter.IQuery describes protocol or type metadata; any embedded import/source record preserves the identity supplied by its owner. This declaration defines no native path conversion or process boundary.
+   */
   export interface IQuery extends IBase<"query"> {
     field: string | null;
   }
@@ -34,7 +80,8 @@ export namespace ITypedHttpRouteParameter {
     type: IReflectType;
     metadata: MetadataSchema;
     example?: any;
-    examples?: Record<string, any>;
+    /** Named examples, as OpenAPI Example Objects. */
+    examples?: Record<string, OpenApi.IExample>;
     description: string | null;
     jsDocTags: IJsDocTagInfo[];
   }

package/src/structures/ITypedHttpRouteSuccess.ts

@@ -1,7 +1,19 @@
+import { OpenApi } from "@typia/interface";
+
 import { MetadataSchema } from "../internal/legacy";
 import { HttpResponseContentTypeUtil } from "../utils/HttpResponseContentTypeUtil";
 import { IReflectType } from "./IReflectType";
 
+/**
+ * A typed success response: its type, status, content type, binary and
+ * encrypted flags, metadata, examples, and header directives.
+ *
+ * @evidence contracts/common.md#principled-implementation The header directives are the `@setHeader` and `@assignHeaders` tags, which the SDK function applies to the connection.
+ * @evidence contracts/common.md#clear-and-simple-design A flat record with no behavior.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what the type describes; its members are named for their meaning.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation ITypedHttpRouteSuccess describes protocol or type metadata; any embedded import/source record preserves the identity supplied by its owner. This declaration defines no native path conversion or process boundary.
+ */
 export interface ITypedHttpRouteSuccess {
   type: IReflectType;
   status: number | null;
@@ -10,7 +22,8 @@ export interface ITypedHttpRouteSuccess {
   encrypted: boolean;
   metadata: MetadataSchema;
   example?: any;
-  examples?: Record<string, any>;
+  /** Named examples, as OpenAPI Example Objects. */
+  examples?: Record<string, OpenApi.IExample>;
   setHeaders: Array<
     | { type: "setter"; source: string; target?: string }
     | { type: "assigner"; source: string }

package/src/structures/ITypedMcpRoute.ts

@@ -1,5 +1,6 @@
 import { IJsDocTagInfo } from "typia";
 
+import { MetadataSchema } from "../internal/legacy";
 import { IReflectController } from "./IReflectController";
 import { IReflectImport } from "./IReflectImport";
 import { IReflectMcpOperation } from "./IReflectMcpOperation";
@@ -12,6 +13,12 @@ import { IReflectType } from "./IReflectType";
  * Carries everything the SDK generator needs to emit a typed client function:
  * the controller reference, accessor path, typia-derived input schema, and
  * input/output type info.
+ *
+ * @evidence contracts/common.md#principled-implementation The record is the tool operation in the form the SDK generator reads.
+ * @evidence contracts/common.md#clear-and-simple-design A flat record with no behavior.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what the type describes; its members are named for their meaning.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation ITypedMcpRoute describes protocol or type metadata; any embedded import/source record preserves the identity supplied by its owner. This declaration defines no native path conversion or process boundary.
  */
 export interface ITypedMcpRoute {
   protocol: "mcp";
@@ -24,6 +31,11 @@ export interface ITypedMcpRoute {
   function: Function;
   input: IReflectMcpOperationParameter | null;
   returnType: IReflectType | null;
+  /** Resolved JSON wire graphs used by structural DTO cloning. */
+  inputMetadata?: MetadataSchema;
+
+  /** Absent when source-only analysis was requested without cloning. */
+  outputMetadata?: MetadataSchema;
   inputSchema: object;
   outputSchema: object | null;
   annotations: IReflectMcpOperation.IAnnotations | null;

package/src/structures/ITypedWebSocketRoute.ts

@@ -5,9 +5,27 @@ import { IReflectController } from "./IReflectController";
 import { IReflectImport } from "./IReflectImport";
 import { ITypedWebSocketRouteParameter } from "./ITypedWebSocketRouteParameter";
 
+/**
+ * A typed WebSocket route: one path with its acceptor, header, path parameters,
+ * query, and driver separated.
+ *
+ * @evidence contracts/common.md#principled-implementation The reflected operation is expanded per path and its parameters are classified.
+ * @evidence contracts/common.md#clear-and-simple-design A flat record with no behavior.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what the type describes; its members are named for their meaning.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation ITypedWebSocketRoute describes protocol or type metadata; any embedded import/source record preserves the identity supplied by its owner. This declaration defines no native path conversion or process boundary.
+ */
 export interface ITypedWebSocketRoute {
   protocol: "websocket";
   controller: IReflectController;
+  /**
+   * Property key of the controller method.
+   *
+   * {@link name} is the SDK function's name, which the accessor analysis
+   * renames: a reserved word such as `delete` becomes `_delete`. Metadata the
+   * method's decorators define, and what names the method, read this key.
+   */
+  key: string;
   name: string;
   path: string;
   accessor: string[];

package/src/transform.ts

@@ -11,6 +11,12 @@ import type { ITtscPlugin, ITtscPluginFactoryContext } from "ttsc";
  * contributor — but only for projects that actually depend on `@nestia/sdk`. A
  * project depending on `@nestia/core` alone never links, compiles, or ships any
  * of this SDK transform code.
+ *
+ * @evidence contracts/common.md#principled-implementation The package root is resolved through `@nestia/sdk/package.json` from the consumer's project, so the source path is the installed package's, not a workspace layout, and the descriptor returns only a name and a source directory.
+ * @evidence contracts/common.md#clear-and-simple-design One function returning two properties; the transform itself is native.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The resolution goes through the package manifest, as the development rules require, and nothing is patched.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what the descriptor returns.
+ * @evidence contracts/portability.md#os-neutral-implementation createRequire anchors package resolution to the consumer project's package.json; Node resolution yields the installed manifest's native pathname and path.dirname/path.resolve derive the contributor source without a workspace-specific separator or shell lookup.
  */
 export default function createTtscPlugin(
   context: ITtscPluginFactoryContext,

package/src/utils/ArrayUtil.ts

@@ -1,10 +1,39 @@
+/**
+ * Array helpers of the SDK generator.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace holds a membership test and a sequential asynchronous map.
+ * @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.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation ArrayUtil operates on caller-supplied arrays and promises without resolving file identity or launching a process; callback boundaries remain the caller's responsibility.
+ */
 export namespace ArrayUtil {
+  /**
+   * Reports whether the array contains every one of the items.
+   *
+   * Membership uses `includes`, so an `undefined` or `NaN` item is found when
+   * the array holds it.
+   *
+   * @evidence contracts/common.md#principled-implementation `Array.prototype.includes` compares by SameValueZero and the result is the conjunction over the items.
+   * @evidence contracts/common.md#clear-and-simple-design One `every` over `includes`.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts No item is special-cased.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the conjunction and the comparison.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation ArrayUtil.has operates on caller-supplied arrays and promises without resolving file identity or launching a process; callback boundaries remain the caller's responsibility.
+   */
   export function has<T>(array: T[], ...items: T[]): boolean {
-    return items.every(
-      (elem) => array.find((org) => org === elem) !== undefined,
-    );
+    return items.every((item) => array.includes(item));
   }
 
+  /**
+   * Maps the elements with an asynchronous function, one after another, and
+   * returns the results in order.
+   *
+   * @evidence contracts/common.md#principled-implementation Each call is awaited before the next starts, so the order of the results is the order of the elements and a rejection stops the mapping.
+   * @evidence contracts/common.md#clear-and-simple-design One loop.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts No element is skipped or retried.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the sequential order.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation ArrayUtil.asyncMap operates on caller-supplied arrays and promises without resolving file identity or launching a process; callback boundaries remain the caller's responsibility.
+   */
   export async function asyncMap<X, Y>(
     array: X[],
     closure: (input: X) => Promise<Y>,
@@ -13,14 +42,4 @@ export namespace ArrayUtil {
     for (const elem of array) ret.push(await closure(elem));
     return ret;
   }
-
-  export async function asyncFilter<T>(
-    array: T[],
-    closure: (input: T) => Promise<boolean>,
-  ): Promise<T[]> {
-    const ret: T[] = [];
-    for (const elem of array)
-      if ((await closure(elem)) === true) ret.push(elem);
-    return ret;
-  }
 }

package/src/utils/EmittedJavaScriptPatcher.ts

@@ -1,14 +1,34 @@
+import { parse } from "@babel/parser";
 import fs from "fs";
 import path from "path";
 
+/**
+ * Patches JavaScript emitted into a temporary directory so that it loads as
+ * CommonJS.
+ *
+ * @evidence contracts/common.md#principled-implementation A compiler can keep `import.meta.url` in CommonJS output, and Node then detects the file as ESM before `require()` loads it, so the token is replaced by an expression that gives the same URL.
+ * @evidence contracts/common.md#clear-and-simple-design One public function collects emitted files and a JavaScript parser identifies import.meta.url expressions by their syntax nodes; source slices retain all unrelated text.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The patch changes only the temporary emit. The parser reads JavaScript grammar, so regular expressions after control-flow statements and property names resembling import.meta.url remain untouched; no previous-token approximation substitutes for parsing.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ * @evidence contracts/portability.md#os-neutral-implementation Entries are listed with `readdir` and joined with `path.join`; only regular `.js` and `.cjs` files, named case-insensitively, are read and rewritten as UTF-8, and symbolic links and other entry kinds are left alone. The replacement derives the file URL with `url.pathToFileURL(__filename)`, the platform's own conversion, so drive letters, UNC paths and percent-encoding follow the rules of `import.meta.url`. The text outside the token, line endings included, is preserved.
+ */
 export namespace EmittedJavaScriptPatcher {
+  /**
+   * Replaces every `import.meta.url` in the `.js` and `.cjs` files under a
+   * directory with `require("url").pathToFileURL(__filename).href`.
+   *
+   * @evidence contracts/common.md#principled-implementation The parser selects only a non-computed url property whose object is the import.meta meta-property, including spaced expressions and template substitutions. Literal and comment text is never an expression node, and the replacement derives the executing CommonJS file URL.
+   * @evidence contracts/common.md#clear-and-simple-design One function collects files and delegates expression detection to the JavaScript grammar parser.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It patches only files that contain the token.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the replacement and the scope.
+   * @evidence contracts/portability.md#os-neutral-implementation Files are read and rewritten concurrently without locking, one pending operation per file, so the caller must be the only writer of the directory, as it is for its own temporary emit.
+   */
   export const importMetaUrl = async (root: string): Promise<void> => {
     const files: string[] = await collect(root);
     await Promise.all(files.map(patch));
   };
 }
 
-const TARGET = "import.meta.url";
 // TypeScript can preserve this token even in CommonJS output. Node 24 then
 // syntax-detects the temporary `.js` file as ESM before require() can load it.
 const REPLACEMENT = 'require("url").pathToFileURL(__filename).href';
@@ -30,59 +50,62 @@ const collect = async (location: string): Promise<string[]> => {
 
 const patch = async (file: string): Promise<void> => {
   const before: string = await fs.promises.readFile(file, "utf8");
-  if (before.includes(TARGET) === false) return;
+  if (before.includes("import") === false) return;
 
   const after: string = replaceImportMetaUrl(before);
   if (after !== before) await fs.promises.writeFile(file, after, "utf8");
 };
 
+// Parse module expressions without imposing module strictness: TypeScript may preserve
+// import.meta in otherwise CommonJS output. Top-level return is valid inside
+// Node's CommonJS wrapper. The parser, rather than token context guesses, owns
+// the distinction between regular expressions, divisions and property names.
 const replaceImportMetaUrl = (input: string): string => {
-  let output: string = "";
-  let cursor: number = 0;
-  for (let i = 0; i < input.length; ) {
-    if (isTarget(input, i)) {
-      output += input.slice(cursor, i);
-      output += REPLACEMENT;
-      i += TARGET.length;
-      cursor = i;
-      continue;
+  const root = parse(input, {
+    sourceType: "module",
+    strictMode: false,
+    attachComment: false,
+    allowImportExportEverywhere: true,
+    allowReturnOutsideFunction: true,
+    allowAwaitOutsideFunction: true,
+  });
+  const spans: Array<{ start: number; end: number }> = [];
+  const pending: Array<{
+    type: string;
+    start?: number | null;
+    end?: number | null;
+  }> = [root];
+  while (pending.length !== 0) {
+    const node = pending.pop()! as Record<string, any>;
+    if (
+      node.type === "MemberExpression" &&
+      node.computed === false &&
+      node.property?.type === "Identifier" &&
+      node.property.name === "url" &&
+      node.object?.type === "MetaProperty" &&
+      node.object.meta.name === "import" &&
+      node.object.property.name === "meta"
+    )
+      spans.push({ start: node.start, end: node.end });
+    for (const value of Object.values(node)) {
+      if (Array.isArray(value)) {
+        for (const child of value)
+          if (child && typeof child.type === "string") pending.push(child);
+      } else if (
+        value &&
+        typeof value === "object" &&
+        typeof value.type === "string"
+      )
+        pending.push(value);
     }
-
-    const ch: string = input[i]!;
-    const next: string | undefined = input[i + 1];
-    if (ch === '"' || ch === "'") i = skipQuoted(input, i, ch);
-    else if (ch === "/" && next === "/") i = skipLineComment(input, i);
-    else if (ch === "/" && next === "*") i = skipBlockComment(input, i);
-    else ++i;
   }
-  return output + input.slice(cursor);
-};
-
-const isTarget = (input: string, index: number): boolean =>
-  input.startsWith(TARGET, index) &&
-  isBoundary(input[index - 1]) &&
-  isBoundary(input[index + TARGET.length]);
-
-const isBoundary = (ch: string | undefined): boolean =>
-  ch === undefined || /[^A-Za-z0-9_$]/.test(ch);
-
-const skipQuoted = (input: string, index: number, quote: string): number => {
-  let escaped: boolean = false;
-  for (let i = index + 1; i < input.length; ++i) {
-    const ch: string = input[i]!;
-    if (escaped) escaped = false;
-    else if (ch === "\\") escaped = true;
-    else if (ch === quote) return i + 1;
+  spans.sort((a, b) => a.start - b.start);
+  const pieces: string[] = [];
+  let cursor = 0;
+  for (const span of spans) {
+    pieces.push(input.slice(cursor, span.start), REPLACEMENT);
+    cursor = span.end;
   }
-  return input.length;
-};
-
-const skipLineComment = (input: string, index: number): number => {
-  const found: number = input.indexOf("\n", index + 2);
-  return found === -1 ? input.length : found + 1;
-};
-
-const skipBlockComment = (input: string, index: number): number => {
-  const found: number = input.indexOf("*/", index + 2);
-  return found === -1 ? input.length : found + 2;
+  pieces.push(input.slice(cursor));
+  return pieces.join("");
 };

package/src/utils/FileRetriever.ts

@@ -1,7 +1,26 @@
 import fs from "fs";
 import path from "path";
 
+/**
+ * Finds a file or a directory by name, in a directory and up to three parents.
+ *
+ * @evidence contracts/common.md#principled-implementation The search checks a directory and then goes to its parent, at most three levels up, which is where a project's own files are expected.
+ * @evidence contracts/common.md#clear-and-simple-design Two curried functions with the same recursion.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The limit is a fixed search depth, not a file name.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ * @evidence contracts/portability.md#os-neutral-implementation Names are joined to directories with `path.join` and tested with `existsSync`, so the volume decides what a name matches and under which case policy. The parent is `path.join(dir, "..")`, which stays at a filesystem root, and the depth counter bounds the climb, so no drive letter or separator test is needed. Directories are returned as joined, not canonicalized, so equal locations reached through links or a different case may compare unequal.
+ */
 export namespace FileRetriever {
+  /**
+   * Returns the nearest directory, from the given one up to three parents, that
+   * contains an entry with the name, or `null`.
+   *
+   * @evidence contracts/common.md#principled-implementation The recursion is bounded by the depth counter, so it terminates at the filesystem root as well.
+   * @evidence contracts/common.md#clear-and-simple-design One function.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The bound is explicit.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the result.
+   * @evidence contracts/portability.md#os-neutral-implementation The result is the directory as the caller spelled it joined with `..` steps; the existence test of the named entry alone decides, under the filesystem's own case policy.
+   */
   export const directory =
     (name: string) =>
     (dir: string, depth: number = 0): string | null => {
@@ -11,6 +30,16 @@ export namespace FileRetriever {
       return directory(name)(path.join(dir, ".."), depth + 1);
     };
 
+  /**
+   * Returns the path of the nearest existing entry with the name, from the
+   * given directory up to three parents, or `null`.
+   *
+   * @evidence contracts/common.md#principled-implementation The recursion is bounded by the depth counter.
+   * @evidence contracts/common.md#clear-and-simple-design One function.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The bound is explicit.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the result.
+   * @evidence contracts/portability.md#os-neutral-implementation The result is the native path of the entry as joined, found by the filesystem's own existence test and not canonicalized.
+   */
   export const file =
     (name: string) =>
     (directory: string, depth: number = 0): string | null => {

package/src/utils/HttpResponseContentTypeUtil.ts

@@ -1,4 +1,23 @@
+/**
+ * Classifies the content type of a response.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace decides which content types the SDK supports and which are binary.
+ * @evidence contracts/common.md#clear-and-simple-design One type and two predicates.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The list is media types, not routes.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation HttpResponseContentTypeUtil classifies HTTP response metadata and MIME types, which have protocol semantics independent of the native filesystem.
+ */
 export namespace HttpResponseContentTypeUtil {
+  /**
+   * A response content type: JSON, text, urlencoded, another string, or `null`
+   * for no body.
+   *
+   * @evidence contracts/common.md#principled-implementation The union keeps the common types visible while allowing any other string.
+   * @evidence contracts/common.md#clear-and-simple-design One union.
+   * @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 cases.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation HttpResponseContentTypeUtil.Response classifies HTTP response metadata and MIME types, which have protocol semantics independent of the native filesystem.
+   */
   export type Response =
     | "application/json"
     | "text/plain"
@@ -6,6 +25,16 @@ export namespace HttpResponseContentTypeUtil {
     | (string & {})
     | null;
 
+  /**
+   * Reports whether the SDK supports the content type: none, JSON, plain text,
+   * urlencoded, or a binary type.
+   *
+   * @evidence contracts/common.md#principled-implementation The content type is compared exactly for the three text types and by the binary rule otherwise.
+   * @evidence contracts/common.md#clear-and-simple-design One expression.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The list is the supported set.
+   * @evidence contracts/common.md#meaningful-documentation The comment lists the supported types.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation HttpResponseContentTypeUtil.isSupported classifies HTTP response metadata and MIME types, which have protocol semantics independent of the native filesystem.
+   */
   export const isSupported = (input: string | null): input is Response =>
     input === null ||
     input === "application/json" ||
@@ -13,6 +42,18 @@ export namespace HttpResponseContentTypeUtil {
     input === "application/x-www-form-urlencoded" ||
     isBinary(input);
 
+  /**
+   * Reports whether the content type is binary: an image, video, or audio type,
+   * an octet stream, or a PDF.
+   *
+   * Parameters and case are ignored.
+   *
+   * @evidence contracts/common.md#principled-implementation The type is the text before the first `;`, trimmed and lower-cased, as HTTP defines a media type.
+   * @evidence contracts/common.md#clear-and-simple-design One predicate.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The rule is a list of media types.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the binary types and the normalization.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation HttpResponseContentTypeUtil.isBinary classifies HTTP response metadata and MIME types, which have protocol semantics independent of the native filesystem.
+   */
   export const isBinary = (
     input: string | null | undefined,
   ): input is string => {