@nestia/sdk 14.0.0 → 14.0.2

package/src/analyses/AccessorAnalyzer.ts

@@ -6,7 +6,33 @@ import { ITypedWebSocketRoute } from "../structures/ITypedWebSocketRoute";
 
 type AnyRoute = ITypedHttpRoute | ITypedWebSocketRoute | ITypedMcpRoute;
 
+/**
+ * Assigns each route the accessor path under which the generated SDK exposes
+ * it.
+ *
+ * @evidence contracts/common.md#principled-implementation The accessors are shrunk where a name repeats, escaped into valid unique identifiers, shrunk again, and each route is renamed to its last accessor segment.
+ * @evidence contracts/common.md#clear-and-simple-design One public function over three private passes.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The passes follow the accessor structure and no route or controller name is special-cased.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ * efficient algorithms: For R routes of at most D accessor segments, the prefix maps avoid repeated route-to-route searches. Prefix slicing and joining costs O(R D²) character work before collision escapes; collisions add probes and longer names. Two shrink passes are required around escaping because escaping changes the names being shrunk.
+ * reuse equivalent work: This invocation computes its own result and coordinates no completed or in-flight computation across requests.
+ * bound retention and release resources: This operation owns only invocation-local values, with no retained cache, handle or background task.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation AccessorAnalyzer 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 AccessorAnalyzer {
+  /**
+   * Rewrites the accessor of every route in place so that accessors are valid,
+   * unique, and as short as they can be.
+   *
+   * @evidence contracts/common.md#principled-implementation Segments that repeat their parent are removed when no sibling shares the parent, non-identifier characters become underscores, a segment that collides with an existing accessor gets an underscore prefix, and the route name becomes the last segment.
+   * @evidence contracts/common.md#clear-and-simple-design One function that runs the passes in a fixed order.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The rules apply to every route, and reserved names are computed from the routes themselves.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the passes and the in-place rewrite.
+   * efficient algorithms: For R routes of at most D accessor segments, the prefix maps avoid repeated route-to-route searches. Prefix slicing and joining costs O(R D²) character work before collision escapes; collisions add probes and longer names. Two shrink passes are required around escaping because escaping changes the names being shrunk.
+   * reuse equivalent work: This invocation computes its own result and coordinates no completed or in-flight computation across requests.
+   * bound retention and release resources: This operation owns only invocation-local values, with no retained cache, handle or background task.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation AccessorAnalyzer.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 = (routes: Array<AnyRoute>) => {
     shrink(routes);
     variable(routes);

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,
@@ -111,16 +153,16 @@ export namespace ConfigAnalyzer {
         versioning === undefined || versioning.type !== VersioningType.URI
           ? undefined
           : {
+              // as NestJS's RoutePathFactory.getVersionPrefix(): `false` is no
+              // prefix at all, and only an absent one is the default "v"
               prefix:
-                versioning.prefix === undefined || versioning.prefix === false
-                  ? "v"
-                  : versioning.prefix,
+                versioning.prefix === false ? "" : (versioning.prefix ?? "v"),
               defaultVersion: versioning.defaultVersion,
             },
     };
   };
 }
-const memory = new Map<INestiaConfig, Promise<INestiaSdkInput>>();
+const memory = new WeakMap<INestiaConfig, Promise<INestiaSdkInput>>();
 class RuntimeCompiler {
   private constructor(
     private readonly cwd: string,
@@ -135,11 +177,7 @@ 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 outDir: string = TemporaryDirectory.create(runtimeRoot, "run-");
     const project: string = path.join(
       cwd,
       `.nestia.runtime.${process.pid}.${Date.now()}.json`,
@@ -195,42 +233,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 +300,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

@@ -0,0 +1,75 @@
+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;
+    field?: string | null;
+  }
+
+  /**
+   * Names every parameter that declares no name of its own.
+   *
+   * A destructured parameter, `@TypedBody() { title }: IBody`, binds names but
+   * is not one, so the SDK's metadata carries it with an empty name. Its source
+   * text is no identifier the SDK could declare, and passing it as one would
+   * send `{ title }` alone. It is named after what it carries instead: its
+   * field when that is an identifier, or reads as one with its separators
+   * 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
+      .map((p) => p.name)
+      .filter((name) => name.length !== 0);
+    return parameters.map((p) => {
+      if (p.name.length !== 0) return p;
+      const name: string = StringUtil.escapeDuplicate(taken)(candidate(p));
+      taken.push(name);
+      return { ...p, name };
+    });
+  };
+
+  const candidate = (p: IParameter): string => {
+    if (p.field !== undefined && p.field !== null && p.field.length !== 0) {
+      if (NamingConvention.variable(p.field)) return p.field;
+      // `x-tenant` as `xTenant`
+      const camel: string = p.field
+        .split(/[^A-Za-z0-9_$]+/)
+        .filter((word) => word.length !== 0)
+        .map((word, i) =>
+          i === 0 ? word : word.charAt(0).toUpperCase() + word.slice(1),
+        )
+        .join("");
+      if (NamingConvention.variable(camel)) return camel;
+    }
+    return p.category;
+  };
+}

package/src/analyses/PathAnalyzer.ts

@@ -1,17 +1,46 @@
 import { RequestMethod } from "@nestjs/common";
-import path from "path";
 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[]) =>
     "/" +
-    _Trim(
-      path
-        .join(...args.filter((s) => !!s.length))
-        .split("\\")
-        .join("/"),
-    );
+    args
+      .join("/")
+      .split("/")
+      .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;
@@ -30,31 +59,115 @@ 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);
+
+  /**
+   * The literal text and parameters of a path, in order, as path-to-regexp
+   * reads it: `/files/:id.json` is `/files/`, the parameter `id`, then `.json`,
+   * 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);
+    if (tokens === null) return null;
+    const output: ISegment[] = [];
+    const literal = (value: string): void => {
+      if (value.length === 0) return;
+      const last: ISegment | undefined = output[output.length - 1];
+      if (last?.type === "literal") last.value += value;
+      else output.push({ type: "literal", value });
+    };
+    for (const token of tokens)
+      if (typeof token === "string") literal(token);
+      else if (typeof token.name === "number") return null;
+      else {
+        literal(token.prefix);
+        output.push({ type: "param", name: token.name });
+        literal(token.suffix);
+      }
+    return output;
+  };
+
+  /**
+   * 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);
+    return list === null
+      ? str
+      : list
+          .map((s) => (s.type === "literal" ? s.value : `{${s.name}}`))
+          .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;
     return args.filter((arg) => arg.type === "param").map((arg) => arg.value);
   };
 
+  /**
+   * The route's tokens, its literal text unescaped. Both routers' spellings of
+   * a literal colon are read: path-to-regexp's (Express) `\\:`, and
+   * find-my-way's (Fastify) `::`, which path-to-regexp would reject.
+   */
+  function _Tokenize(str: string): Token[] | null {
+    try {
+      return parse(fromFastifyColons(join(str)));
+    } catch {
+      return null;
+    }
+  }
+
   function _Parse(str: string): IArgument[] | null {
-    const tokens: Token[] | null = (() => {
-      try {
-        return parse(path.join(str).split("\\").join("/"));
-      } catch {
-        return null;
-      }
-    })();
+    const tokens: Token[] | null = _Tokenize(str);
     if (tokens === null) return null;
 
     const output: IArgument[] = [];
@@ -128,3 +241,34 @@ const REQUEST_METHODS: Record<string, RequestMethod> = {
   POST: RequestMethod.POST,
   PUT: RequestMethod.PUT,
 };
+
+/**
+ * A route with find-my-way's (Fastify) literal colon `::` spelled as
+ * path-to-regexp's `\:`. find-my-way reads `::` as a colon in static text
+ * alone: after a parameter it is part of the parameter's name, so it is left as
+ * is there, and path-to-regexp then rejects the route, as no parameter of that
+ * name is what the handler reads.
+ *
+ * @internal
+ */
+const fromFastifyColons = (route: string): string => {
+  let output: string = "";
+  for (let i: number = 0; i < route.length; ) {
+    if (route[i] === "\\") {
+      output += route.slice(i, i + 2);
+      i += 2;
+    } else if (route.startsWith("::", i)) {
+      output += "\\:";
+      i += 2;
+    } else if (route[i] === ":") {
+      const name: string = /^:[A-Za-z0-9_$]*/.exec(route.slice(i))![0];
+      output += name;
+      i += name.length;
+      if (route.startsWith("::", i)) {
+        output += "::";
+        i += 2;
+      }
+    } else output += route[i++];
+  }
+  return output;
+};