@nestia/sdk 14.0.1 → 14.0.3

package/src/analyses/ConfigAnalyzer.ts

@@ -6,20 +6,49 @@ import { Module } from "@nestjs/core/injector/module";
 import fs from "fs";
 import getFunctionLocation from "get-function-location";
 import path from "path";
-import { HashMap, Pair, Singleton } from "tstl";
+import { HashMap } from "tstl";
 import { pathToFileURL } from "url";
 
 import { INestiaConfig } from "../INestiaConfig";
-import { SdkGenerator } from "../generates/SdkGenerator";
 import { INestiaSdkInput } from "../structures/INestiaSdkInput";
-import { ArrayUtil } from "../utils/ArrayUtil";
 import { EmittedJavaScriptPatcher } from "../utils/EmittedJavaScriptPatcher";
 import { MapUtil } from "../utils/MapUtil";
+import { PathUtil } from "../utils/PathUtil";
+import { SdkInputFilter } from "../utils/SdkInputFilter";
 import { SourceFinder } from "../utils/SourceFinder";
+import { TemporaryDirectory } from "../utils/TemporaryDirectory";
 import { TsConfigReader } from "../utils/TsConfigReader";
 import { TtscExecutor } from "../utils/TtscExecutor";
 
+/**
+ * Finds the controllers a configuration names, either by compiling and
+ * importing sources or by reading a running application.
+ *
+ * @evidence contracts/common.md#principled-implementation Sources are compiled once through ttsc into a temporary directory, imported, and the exports that carry the Nest `path` metadata are the controllers; an application is read from its module container; results are memoized per configuration object in a weakly keyed map, so a configuration the watcher reloads releases its entry with the object.
+ * @evidence contracts/common.md#clear-and-simple-design Two public functions and a private runtime compiler; the output-specific bundle filter comes from SdkInputFilter and configuration/runtime materializations share the owned-child cleanup registry.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The generated SDK's own files are excluded from the input by the bundle list of the SDK, not by name, and the container is read through internals, as noted at `application`.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ * efficient algorithms: Discovery traverses candidate files once, compiles one runtime project and inspects every exported value; work scales with source/compiler input and export population. Application input instead traverses container controllers and resolves each unique class location.
+ * reuse equivalent work: The promise cache shares concurrent and completed analyses for the same config object. It assumes that object, its input sources and application state remain unchanged during its lifetime; callers must supply a fresh config object after changes. Bundle exclusion shares only installed asset descriptions and derives native/realpath roots separately for each output; distinct outputs never reuse one captured prefix.
+ * bound retention and release resources: The weakly keyed input map does not retain released config objects, but emitted directories are registered until owned generation cleanup or process exit. Imported CommonJS/ESM modules remain in the hosting Node loader; direct programmatic callers have no per-generation unload guarantee. CLI watch generations isolate this state in a short-lived child.
+ * @evidence contracts/portability.md#os-neutral-implementation Source/controller identity is obtained from Node path/file-URL conversion, module resolution and native fs. Compiler projects use explicit cwd and native paths; emitted module imports use file URLs. Route prefix/version spelling is kept as protocol text, not treated as filesystem identity.
+ */
 export namespace ConfigAnalyzer {
+  /**
+   * Returns the analyzed input of a configuration: the controllers with their
+   * files and the global prefix and versioning options.
+   *
+   * The result is cached per configuration object.
+   *
+   * @evidence contracts/common.md#principled-implementation A function input is asked for the application and read as a running app; otherwise the matched TypeScript sources are compiled and imported, and the memo stores the promise so concurrent callers share one compilation.
+   * @evidence contracts/common.md#clear-and-simple-design One function delegating to `application` or to the runtime compiler.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The cache is keyed by the identity of the configuration object, so a different or reloaded configuration object is never served another's result; one object keeps its first result, which is the contract of a configuration that is not mutated between generations.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the two input forms and the caching.
+   * efficient algorithms: Discovery traverses candidate files once, compiles one runtime project and inspects every exported value; work scales with source/compiler input and export population. Application input instead traverses container controllers and resolves each unique class location.
+   * reuse equivalent work: The promise cache shares concurrent and completed analyses for the same config object. It assumes that object, its input sources and application state remain unchanged during its lifetime; callers must supply a fresh config object after changes. Bundle exclusion shares only installed asset descriptions and derives native/realpath roots separately for each output; distinct outputs never reuse one captured prefix.
+   * bound retention and release resources: The weakly keyed input map does not retain released config objects, but emitted directories are registered until owned generation cleanup or process exit. Imported CommonJS/ESM modules remain in the hosting Node loader; direct programmatic callers have no per-generation unload guarantee. CLI watch generations isolate this state in a short-lived child.
+   * @evidence contracts/portability.md#os-neutral-implementation Source/controller identity is obtained from Node path/file-URL conversion, module resolution and native fs. Compiler projects use explicit cwd and native paths; emitted module imports use file URLs. Route prefix/version spelling is kept as protocol text, not treated as filesystem identity.
+   */
   export const input = async (
     config: INestiaConfig,
   ): Promise<INestiaSdkInput> => {
@@ -37,7 +66,7 @@ export namespace ConfigAnalyzer {
           typeof config.input === "object" && !Array.isArray(config.input)
             ? (config.input.exclude ?? [])
             : [],
-        filter: filter(config),
+        filter: await SdkInputFilter.create(config.output),
       });
       const runtime: RuntimeCompiler = await RuntimeCompiler.compile(sources);
       const controllers: INestiaSdkInput.IController[] = [];
@@ -62,6 +91,19 @@ export namespace ConfigAnalyzer {
     });
   };
 
+  /**
+   * Reads the controllers, the global prefix, and the versioning options of a
+   * running NestJS application.
+   *
+   * @evidence contracts/common.md#principled-implementation The controllers come from the module container with their module paths, their files from the location of each class, decoded from the `file:` URL, and the prefix and versioning options from the application's configuration.
+   * @evidence contracts/common.md#clear-and-simple-design One function.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts NestJS exposes no public accessor for the container or the configuration, so the function reads `app.container` and `app.config`; this is the one foreign-internal read of the package and stays a stated limit.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what is read.
+   * efficient algorithms: The container is traversed once and a hash map groups each class with its module prefixes, so location lookup occurs once per unique controller class.
+   * reuse equivalent work: This invocation computes its own result and coordinates no completed or in-flight computation across requests.
+   * bound retention and release resources: The invocation retains local module/controller collections until it returns. The running application and its controllers remain caller-owned; this reader neither starts nor closes the app.
+   * @evidence contracts/portability.md#os-neutral-implementation Source/controller identity is obtained from Node path/file-URL conversion, module resolution and native fs. Compiler projects use explicit cwd and native paths; emitted module imports use file URLs. Route prefix/version spelling is kept as protocol text, not treated as filesystem identity.
+   */
   export const application = async (
     app: INestApplication,
   ): Promise<INestiaSdkInput> => {
@@ -88,7 +130,7 @@ export namespace ConfigAnalyzer {
       const file: string | null =
         (await getFunctionLocation(it.first))?.source ?? null;
       if (file === null) continue;
-      const location: string = normalize_file(file);
+      const location: string = PathUtil.location(file);
       if (location.length === 0) continue;
       controllers.push({
         class: it.first,
@@ -120,7 +162,7 @@ export namespace ConfigAnalyzer {
     };
   };
 }
-const memory = new Map<INestiaConfig, Promise<INestiaSdkInput>>();
+const memory = new WeakMap<INestiaConfig, Promise<INestiaSdkInput>>();
 class RuntimeCompiler {
   private constructor(
     private readonly cwd: string,
@@ -135,31 +177,28 @@ class RuntimeCompiler {
       ".nestia",
       "runtime",
     );
-    await fs.promises.mkdir(runtimeRoot, { recursive: true });
-    ensureRuntimeCleanup(runtimeRoot);
-    const outDir: string = await fs.promises.mkdtemp(
-      path.join(runtimeRoot, "run-"),
-    );
-    const project: string = path.join(
-      cwd,
-      `.nestia.runtime.${process.pid}.${Date.now()}.json`,
-    );
-    const relative = (file: string): string =>
-      path.relative(cwd, file).split("\\").join("/");
+    const outDir: string = TemporaryDirectory.create(runtimeRoot, "run-");
+    // Compiler materializations belong below node_modules with their emitted
+    // output. A project file in cwd is itself a watched JSON input and would
+    // schedule another generation when this compilation creates/removes it.
+    const project: string = path.join(outDir, "tsconfig.json");
     await fs.promises.writeFile(
       project,
       JSON.stringify(
         {
-          extends: normalizeProjectPath(process.env.NESTIA_PROJECT),
+          extends: path.resolve(
+            cwd,
+            process.env.NESTIA_PROJECT ?? "tsconfig.json",
+          ),
           compilerOptions: {
             noEmit: false,
             noUnusedLocals: false,
             noUnusedParameters: false,
             outDir,
             plugins: await runtimePlugins(cwd),
-            rootDir: ".",
+            rootDir: cwd,
           },
-          include: sources.map(relative),
+          include: sources.map((file) => path.resolve(cwd, file)),
         },
         null,
         2,
@@ -195,42 +234,6 @@ class RuntimeCompiler {
   }
 }
 
-const RUNTIME_ROOTS: Set<string> = new Set();
-let RUNTIME_CLEANUP_REGISTERED: boolean = false;
-
-const ensureRuntimeCleanup = (runtimeRoot: string): void => {
-  RUNTIME_ROOTS.add(runtimeRoot);
-  if (RUNTIME_CLEANUP_REGISTERED === true) return;
-  RUNTIME_CLEANUP_REGISTERED = true;
-  const sweep = (): void => {
-    for (const location of RUNTIME_ROOTS)
-      fs.rmSync(location, { force: true, recursive: true });
-  };
-  process.once("exit", sweep);
-  // process.once("exit", …) does not fire on SIGINT/SIGTERM. Without these
-  // handlers a Ctrl-C during codegen leaves `run-*` mkdtemp directories
-  // behind under node_modules/.nestia/runtime/ until a subsequent clean exit.
-  // The module-level RUNTIME_CLEANUP_REGISTERED flag above guards against
-  // re-entrancy within this module; we deliberately do NOT gate on
-  // `process.listenerCount(signal) > 0` because NestiaConfigLoader's parallel
-  // sweep registers first, and that gate would skip our registration —
-  // leaving RUNTIME_ROOTS unswept on Ctrl-C while config-loader cleans up.
-  // Windows note: `process.kill(pid, "SIGINT")` calls TerminateProcess
-  // rather than re-raising through the listener queue, so the handler
-  // cascade documented above only holds on POSIX. On Windows, whichever
-  // module registers FIRST runs its sweep and the second is skipped —
-  // RUNTIME_ROOTS cleanup is best-effort there. SIGHUP is a no-op for
-  // most common code paths on Windows (Node fires it on console-close
-  // and exits within seconds).
-  const onSignal = (signal: NodeJS.Signals): void => {
-    sweep();
-    process.kill(process.pid, signal);
-  };
-  for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"] as const) {
-    process.once(signal, onSignal);
-  }
-};
-
 type RuntimePlugin = Record<string, unknown> & { transform?: unknown };
 
 const sdkTransformEnv = (): NodeJS.ProcessEnv =>
@@ -298,47 +301,7 @@ const normalizeProjectPath = (project: string | undefined): string => {
   return path.isAbsolute(next) || next.startsWith(".") ? next : `./${next}`;
 };
 
-const normalize_file = (str: string) =>
-  str.substring(
-    str.startsWith("file:///")
-      ? process.cwd()[0] === "/"
-        ? 7
-        : 8
-      : str.startsWith("file://")
-        ? 7
-        : 0,
-  );
-
-const filter =
-  (config: INestiaConfig) =>
-  async (location: string): Promise<boolean> =>
-    SourceFinder.isTypeScriptSource(location) &&
-    (config.output === undefined ||
-      (location.indexOf(path.join(config.output, "functional")) === -1 &&
-        (await (
-          await bundler.get(config.output)
-        )(location))) === false);
-
 const dynamicImport: (specifier: string) => Promise<any> = Function(
   "specifier",
   "return import(specifier);",
 ) as (specifier: string) => Promise<any>;
-
-const bundler = new Singleton(async (output: string) => {
-  const assets: string[] = await fs.promises.readdir(SdkGenerator.BUNDLE_PATH);
-  const tuples: Pair<string, boolean>[] = await ArrayUtil.asyncMap(
-    assets,
-    async (file) => {
-      const relative: string = path.join(output, file);
-      const location: string = path.join(SdkGenerator.BUNDLE_PATH, file);
-      const stats: fs.Stats = await fs.promises.stat(location);
-      return new Pair(relative, stats.isDirectory());
-    },
-  );
-  return async (file: string): Promise<boolean> => {
-    for (const it of tuples)
-      if (it.second === false && file === it.first) return true;
-      else if (it.second === true && file.indexOf(it.first) === 0) return true;
-    return false;
-  };
-});

package/src/analyses/ImportAnalyzer.ts

@@ -1,6 +1,15 @@
 import { IReflectImport } from "../structures/IReflectImport";
 import { MapUtil } from "../utils/MapUtil";
 
+/**
+ * Helpers for the import lists of routes.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace merges the imports collected for one route and keeps a removal notice for the old analysis entry.
+ * @evidence contracts/common.md#clear-and-simple-design Two functions.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The merge is generic.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation ImportAnalyzer analyzes reflected route metadata; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+ */
 export namespace ImportAnalyzer {
   /**
    * @deprecated Removed in the Go-migration cycle. Import metadata is now
@@ -10,6 +19,11 @@ export namespace ImportAnalyzer {
    *   `ts.SourceFile` to derive imports should read the metadata delivered
    *   through `Reflect.getMetadata("nestia/OperationMetadata", …)` instead. See
    *   `packages/core/MIGRATION.md`.
+   * @evidence contracts/common.md#principled-implementation The function exists only to give an actionable error to a caller of the removed API, and always throws.
+   * @evidence contracts/common.md#clear-and-simple-design One statement.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It reports the removal instead of failing later with a missing function.
+   * @evidence contracts/common.md#meaningful-documentation The comment names the replacement.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation ImportAnalyzer.analyze analyzes reflected route metadata; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
    */
   export const analyze = (): never => {
     throw new Error(
@@ -19,6 +33,17 @@ export namespace ImportAnalyzer {
     );
   };
 
+  /**
+   * Merges import records by file: namespace imports and default imports are
+   * deduplicated and sorted, and the named elements of every import of a file
+   * are combined with their aliases.
+   *
+   * @evidence contracts/common.md#principled-implementation Imports are grouped by file, each group emits its namespace imports, default imports, and one element list with an alias map for renamed elements, so the same file is imported once per kind.
+   * @evidence contracts/common.md#clear-and-simple-design One function over one group merger.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The merge follows the import records, with no file special-cased.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the grouping and the merging.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation ImportAnalyzer.merge analyzes reflected route metadata; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const merge = (imports: IReflectImport[]): IReflectImport[] => {
     // group by files
     const fileGroups: Map<string, IReflectImport[]> = new Map();

package/src/analyses/ParameterNameAnalyzer.ts

@@ -2,7 +2,25 @@ import { NamingConvention } from "@typia/utils";
 
 import { StringUtil } from "../utils/StringUtil";
 
+/**
+ * Gives names to parameters that declare none, such as destructured ones.
+ *
+ * @evidence contracts/common.md#principled-implementation A missing name is derived from the field, camel-cased when it is not an identifier, or from the category, and then made unique against the names already taken.
+ * @evidence contracts/common.md#clear-and-simple-design One function, one record type, and one private candidate rule.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The rule is generic.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation ParameterNameAnalyzer analyzes reflected route metadata; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+ */
 export namespace ParameterNameAnalyzer {
+  /**
+   * A parameter to name: its current name, its category, and an optional field.
+   *
+   * @evidence contracts/common.md#principled-implementation The three members are the inputs of the naming rule.
+   * @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 and the meaning of its members.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation ParameterNameAnalyzer.IParameter analyzes reflected route metadata; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export interface IParameter {
     name: string;
     category: string;
@@ -20,6 +38,12 @@ export namespace ParameterNameAnalyzer {
    * dropped in camel case, otherwise its category, such as `body` or `query`.
    * The name yields to every other parameter's, which are the user's and are
    * kept.
+   *
+   * @evidence contracts/common.md#principled-implementation The names in use are collected first, and each new name is escaped against them with underscores and added, so the result has no duplicates.
+   * @evidence contracts/common.md#clear-and-simple-design One function.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Existing names are never changed.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the rule.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation ParameterNameAnalyzer.name analyzes reflected route metadata; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
    */
   export const name = <T extends IParameter>(parameters: T[]): T[] => {
     const taken: string[] = parameters

package/src/analyses/PathAnalyzer.ts

@@ -1,11 +1,27 @@
 import { RequestMethod } from "@nestjs/common";
 import { Token, parse } from "path-to-regexp";
 
+/**
+ * Helpers for route paths: joining, prefixing, and reading their parameters the
+ * way the router does.
+ *
+ * @evidence contracts/common.md#principled-implementation Paths are parsed by `path-to-regexp` after Fastify colon escapes are converted, so the parameters and literals are those the server reads.
+ * @evidence contracts/common.md#clear-and-simple-design Several small functions over one tokenizer and one parser.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The router's own grammar decides, and no path is special-cased.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation PathAnalyzer interprets router protocol paths; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+ */
 export namespace PathAnalyzer {
   /**
    * The route paths joined as the router joins them: one `/` between them, and
    * none doubled. A route path is router syntax, never a file path, so a
    * backslash stays the escape of the character after it (`items\\:batchGet`).
+   *
+   * @evidence contracts/common.md#principled-implementation The parts are joined, split on slashes, and empty segments are dropped, so any number of slashes at the boundaries collapses.
+   * @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 result form.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation PathAnalyzer.join interprets router protocol paths; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
    */
   export const join = (...args: string[]) =>
     "/" +
@@ -15,6 +31,16 @@ export namespace PathAnalyzer {
       .filter((str) => str.length !== 0)
       .join("/");
 
+  /**
+   * Joins a path with the global prefix, unless the route is excluded from the
+   * prefix.
+   *
+   * @evidence contracts/common.md#principled-implementation The exclusion list is matched by method and by exact path or pattern, as NestJS does, and an excluded route is joined with an empty prefix.
+   * @evidence contracts/common.md#clear-and-simple-design One function delegating the exclusion test to a private helper.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The exclusion rule is NestJS's.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the exclusion.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation PathAnalyzer.joinWithGlobalPrefix interprets router protocol paths; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const joinWithGlobalPrefix = (props: {
     globalPrefix: string;
     exclude: IGlobalPrefixExclude[] | undefined;
@@ -33,20 +59,15 @@ export namespace PathAnalyzer {
       props.path,
     );
 
-  export const escape = (str: string): string | null => {
-    const args = _Parse(str);
-    if (args === null) return null;
-    return (
-      "/" +
-      args
-        .map((arg) => (arg.type === "param" ? `:${arg.value}` : arg.value))
-        .join("/")
-    );
-  };
-
   /**
    * Whether a route path holds a wildcard: a `*` not escaped as the literal
    * character (`\\*`), which a route path may hold since #1713.
+   *
+   * @evidence contracts/common.md#principled-implementation A star preceded by a backslash is a literal, so the test looks for a star at the start or after a non-backslash character.
+   * @evidence contracts/common.md#clear-and-simple-design One regular expression.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It follows the router's escaping rule.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the escaped case.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation PathAnalyzer.wildcard interprets router protocol paths; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
    */
   export const wildcard = (str: string): boolean => /(^|[^\\])\*/.test(str);
 
@@ -56,6 +77,12 @@ export namespace PathAnalyzer {
    * and `/range/:from-:to` holds two parameters parted by `-`. Every generator
    * that writes a path with its parameters filled in reads it from here, never
    * by splitting the text at `:` or `/`. `null` for a path it cannot parse.
+   *
+   * @evidence contracts/common.md#principled-implementation Tokens come from `path-to-regexp`, so text next to a parameter in one segment, such as `/files/:id.json`, is kept in place, adjacent literals merge, and an unnamed parameter makes the path unreadable.
+   * @evidence contracts/common.md#clear-and-simple-design One function over the tokenizer.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The grammar is the router's.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the result and why generators use it.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation PathAnalyzer.segments interprets router protocol paths; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
    */
   export const segments = (str: string): ISegment[] | null => {
     const tokens: Token[] | null = _Tokenize(str);
@@ -81,6 +108,12 @@ export namespace PathAnalyzer {
   /**
    * The path in OpenAPI's template syntax, each parameter written `{name}`:
    * `/files/:id.json` is `/files/{id}.json`.
+   *
+   * @evidence contracts/common.md#principled-implementation The segments are joined with literals verbatim and parameters in braces.
+   * @evidence contracts/common.md#clear-and-simple-design One expression over `segments`.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It uses the same segmenter as the SDK generator.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the fallback.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation PathAnalyzer.toOpenApi interprets router protocol paths; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
    */
   export const toOpenApi = (str: string): string => {
     const list: ISegment[] | null = segments(str);
@@ -91,10 +124,29 @@ export namespace PathAnalyzer {
           .join("");
   };
 
+  /**
+   * A segment of a path: literal text or a named parameter.
+   *
+   * @evidence contracts/common.md#principled-implementation The union is discriminated by `type`, so a consumer handles each case once.
+   * @evidence contracts/common.md#clear-and-simple-design A two-member 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 two cases.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation PathAnalyzer.ISegment interprets router protocol paths; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export type ISegment =
     | { type: "literal"; value: string }
     | { type: "param"; name: string };
 
+  /**
+   * Returns the names of the parameters of a path, or `null` when the path
+   * cannot be parsed.
+   *
+   * @evidence contracts/common.md#principled-implementation The parsed arguments are filtered to the parameters, and an empty parameter name makes the path unreadable.
+   * @evidence contracts/common.md#clear-and-simple-design One filter over the private parser.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The grammar is the router's.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation PathAnalyzer.parameters interprets router protocol paths; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const parameters = (str: string): string[] | null => {
     const args = _Parse(str);
     if (args === null) return null;

package/src/analyses/ReflectControllerAnalyzer.ts

@@ -18,7 +18,26 @@ import { ReflectMcpOperationAnalyzer } from "./ReflectMcpOperationAnalyzer";
 import { ReflectMetadataAnalyzer } from "./ReflectMetadataAnalyzer";
 import { ReflectWebSocketOperationAnalyzer } from "./ReflectWebSocketOperationAnalyzer";
 
+/**
+ * Reflects a NestJS controller class into an operation list.
+ *
+ * @evidence contracts/common.md#principled-implementation A controller is recognized by Nest's own path, host, and scope metadata, its methods are visited along the prototype chain with a subclass method hiding an inherited one, and each method is classified as MCP, WebSocket, or HTTP.
+ * @evidence contracts/common.md#clear-and-simple-design One public function and one prototype walker.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The recognition uses the metadata Nest writes, and no class name is special-cased.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation ReflectControllerAnalyzer analyzes reflected route metadata; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+ */
 export namespace ReflectControllerAnalyzer {
+  /**
+   * The input of the controller analysis: the project, the controller, and a
+   * set of visited functions.
+   *
+   * @evidence contracts/common.md#principled-implementation The record holds what one analysis needs and the shared error lists live in the project.
+   * @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 and the meaning of its members.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation ReflectControllerAnalyzer.IProps analyzes reflected route metadata; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export interface IProps {
     project: Omit<INestiaProject, "config">;
     controller: INestiaSdkInput.IController;
@@ -27,6 +46,19 @@ export namespace ReflectControllerAnalyzer {
   /* ---------------------------------------------------------
     CONTROLLER
   --------------------------------------------------------- */
+  /**
+   * Returns the reflected controller with its operations, or `null` for a class
+   * that is not a controller.
+   *
+   * Wildcard controller paths are dropped with a warning, and methods marked
+   * `@ignore` are skipped.
+   *
+   * @evidence contracts/common.md#principled-implementation The metadata keys of the class decide whether it is a controller, every own and inherited method with operation metadata is offered to the MCP, WebSocket, and HTTP analyzers in that order, and the first analyzer that accepts it owns it.
+   * @evidence contracts/common.md#clear-and-simple-design One function.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The order of the analyzers is fixed by the mutual exclusion of the decorators.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the null result, the warning, and the ignore tag.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation ReflectControllerAnalyzer.analyze analyzes reflected route metadata; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const analyze = (props: IProps): IReflectController | null => {
     // MUST BE TYPE OF A CREATOR WHO HAS THE CONSTRUCTOR
     if (

package/src/analyses/ReflectHttpOperationAnalyzer.ts

@@ -16,7 +16,26 @@ import { ReflectHttpOperationParameterAnalyzer } from "./ReflectHttpOperationPar
 import { ReflectHttpOperationResponseAnalyzer } from "./ReflectHttpOperationResponseAnalyzer";
 import { ReflectMetadataAnalyzer } from "./ReflectMetadataAnalyzer";
 
+/**
+ * Reflects an HTTP route method into an operation.
+ *
+ * @evidence contracts/common.md#principled-implementation The method, the path list, the parameters, the success response, the exceptions, the imports, the security, and the extensions are composed from Nest's metadata and the compile-time metadata, and the path parameters of the decorator are checked against the parameter decorators.
+ * @evidence contracts/common.md#clear-and-simple-design One public function over the parameter, response, and exception analyzers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The checks follow the decorators and no route is special-cased.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation ReflectHttpOperationAnalyzer analyzes reflected route metadata; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+ */
 export namespace ReflectHttpOperationAnalyzer {
+  /**
+   * The input of the HTTP operation analysis: the project, the controller, the
+   * method, and its compile-time metadata.
+   *
+   * @evidence contracts/common.md#principled-implementation The record holds the reflected function and the metadata the transform attached to it.
+   * @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 and the meaning of its members.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation ReflectHttpOperationAnalyzer.IProps analyzes reflected route metadata; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export interface IProps {
     project: Omit<INestiaProject, "config"> &
       Partial<Pick<INestiaProject, "config">>;
@@ -25,6 +44,16 @@ export namespace ReflectHttpOperationAnalyzer {
     name: string;
     metadata: IOperationMetadata;
   }
+  /**
+   * Returns the reflected HTTP operation, or `null` when the method is not a
+   * route or has errors, which are pushed to the project.
+   *
+   * @evidence contracts/common.md#principled-implementation A method is a route when it has Nest's path and method metadata; `ALL` is treated as POST and OPTIONS is skipped; a mismatch between the path parameters and the parameter decorators is an error.
+   * @evidence contracts/common.md#clear-and-simple-design One function that collects errors and returns nothing when there is one.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The rules follow the HTTP semantics of the decorators.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the null result and the collected errors.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation ReflectHttpOperationAnalyzer.analyze analyzes reflected route metadata; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const analyze = (props: IProps): IReflectHttpOperation | null => {
     if (
       ArrayUtil.has(
@@ -49,9 +78,8 @@ export namespace ReflectHttpOperationAnalyzer {
         functionName: props.name,
         errors,
       });
-    const success: IReflectHttpOperationSuccess | null = (() => {
-      const localErrors: IReflectOperationError[] = [];
-      const success = ReflectHttpOperationResponseAnalyzer.analyze({
+    const success: IReflectHttpOperationSuccess | null =
+      ReflectHttpOperationResponseAnalyzer.analyze({
         controller: props.controller,
         function: props.function,
         functionName: props.name,
@@ -59,12 +87,6 @@ export namespace ReflectHttpOperationAnalyzer {
         metadata: props.metadata,
         errors,
       });
-      if (localErrors.length) {
-        errors.push(...localErrors);
-        return null;
-      }
-      return success;
-    })();
     if (errors.length) {
       props.project.errors.push(...errors);
       return null;
@@ -135,7 +157,7 @@ export namespace ReflectHttpOperationAnalyzer {
         // LIST UP PARAMETERS
         const binded: string[] | null = PathAnalyzer.parameters(location);
         if (binded === null) {
-          props.project.errors.push({
+          errors.push({
             file: props.controller.file,
             class: props.controller.class.name,
             function: props.name,

package/src/analyses/ReflectHttpOperationExceptionAnalyzer.ts

@@ -6,7 +6,26 @@ import { IReflectController } from "../structures/IReflectController";
 import { IReflectHttpOperationException } from "../structures/IReflectHttpOperationException";
 import { IReflectOperationError } from "../structures/IReflectOperationError";
 
+/**
+ * Reflects the `@TypedException` declarations of a method.
+ *
+ * @evidence contracts/common.md#principled-implementation The declarations are read in declaration order and matched by position with the exception types the transform recorded.
+ * @evidence contracts/common.md#clear-and-simple-design One public function.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The matching is by position because both lists are produced in declaration order.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation ReflectHttpOperationExceptionAnalyzer analyzes reflected route metadata; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+ */
 export namespace ReflectHttpOperationExceptionAnalyzer {
+  /**
+   * The input of the exception analysis: the controller, the method, its name,
+   * the HTTP method, the metadata, and the error list.
+   *
+   * @evidence contracts/common.md#principled-implementation The record holds what the analysis needs.
+   * @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 and the meaning of its members.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation ReflectHttpOperationExceptionAnalyzer.IContext analyzes reflected route metadata; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export interface IContext {
     controller: IReflectController;
     function: Function;
@@ -15,6 +34,18 @@ export namespace ReflectHttpOperationExceptionAnalyzer {
     metadata: IOperationMetadata;
     errors: IReflectOperationError[];
   }
+  /**
+   * Returns the exceptions of a method by status.
+   *
+   * A declaration without a matching type, or with an unreadable one, is an
+   * error.
+   *
+   * @evidence contracts/common.md#principled-implementation Decorators apply bottom-up, so the metadata array is reversed to declaration order before it is paired with the transform's exception list, and the result is keyed by status, so the last declaration of a status wins.
+   * @evidence contracts/common.md#clear-and-simple-design One function.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The pairing follows the documented order, and every mismatch is reported.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the matching and the errors.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation ReflectHttpOperationExceptionAnalyzer.analyze analyzes reflected route metadata; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const analyze = (
     ctx: IContext,
   ): Record<string, IReflectHttpOperationException> => {