@nestia/sdk 14.0.1 → 14.0.2

package/src/generates/internal/SdkWebSocketCloneProgrammer.ts

@@ -1,9 +1,32 @@
+import { parse } from "@babel/parser";
 import fs from "fs";
 import path from "path";
 
 import { ITypedApplication } from "../../structures/ITypedApplication";
 
+/**
+ * Copies the declarations a WebSocket route's types come from into the
+ * `structures` directory.
+ *
+ * @evidence contracts/common.md#principled-implementation A WebSocket route refers to types by import, so the declaration and the declarations it uses are copied as text from the source files, not rebuilt from metadata.
+ * @evidence contracts/common.md#clear-and-simple-design One public function with syntax-tree helpers for declarations and imports.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The TypeScript syntax parser determines declaration and import boundaries, including automatic semicolon insertion; a package file or a name declared differently in two files is never copied.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+ * @evidence contracts/portability.md#os-neutral-implementation Source candidates use Node path.resolve/join and fs.stat/readFile; outputs use recursive mkdir and UTF-8 writes. Retained relative imports are rebased with native path.relative and rendered with module separators; cross-volume absolute paths remain absolute. Supported source candidates currently include .ts/.tsx/.d.ts rather than .mts/.cts.
+ */
 export namespace SdkWebSocketCloneProgrammer {
+  /**
+   * Copies named project-local declarations imported by WebSocket routes, and
+   * returns the identities successfully cloned. Default and namespace imports
+   * remain source imports; a missing source or conflicting output name is not
+   * reported as cloned.
+   *
+   * @evidence contracts/common.md#principled-implementation Named imports are followed by resolved source/name identity; pending entries break recursive dependency cycles, written entries reuse completed copies, and missing or conflicting declarations return false. External, default and namespace bindings remain imports rather than reconstructed declarations.
+   * @evidence contracts/common.md#clear-and-simple-design One loop over the routes' imports.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Only the imports that resolved to a source file are reported.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidence contracts/portability.md#os-neutral-implementation Source lookup uses native fs.stat and path operations and rejects dependency paths by a node_modules component. The output uses the configured native directory; cache keys retain resolved pathname spelling rather than claiming canonical case or symlink identity.
+   */
   export const write = async (app: ITypedApplication): Promise<Set<string>> => {
     const ctx: IContext = {
       output: `${app.project.config.output}/structures`,
@@ -35,7 +58,7 @@ export namespace SdkWebSocketCloneProgrammer {
       ctx.visited.set(key, "pending");
 
       const text: string = await fs.promises.readFile(location, "utf8");
-      const declarations: string[] = getDeclarations(text, name);
+      const declarations: string[] = getDeclarations(text, name, location);
       if (declarations.length === 0) {
         ctx.visited.set(key, "missing");
         return false;
@@ -77,13 +100,14 @@ export namespace SdkWebSocketCloneProgrammer {
         if (imports.includes(line) === false) imports.push(line);
       };
 
-      for (const imp of getImports(props.source)) {
+      for (const imp of getImports(props.source, props.location)) {
         const relative: boolean = imp.specifier.startsWith(".");
+        const retained: Set<string> = new Set();
         for (const elem of imp.elements) {
-          if (uses(props.body, elem.local) === false) continue;
+          if (uses(props.body, elem.local, props.location) === false) continue;
 
           if (relative === false) {
-            add(imp.text);
+            retained.add(elem.local);
             continue;
           }
 
@@ -92,7 +116,7 @@ export namespace SdkWebSocketCloneProgrammer {
             imp.specifier,
           );
           if ((await clone(ctx)(sourceFile, elem.imported)) === false) {
-            add(imp.text);
+            retained.add(elem.local);
             continue;
           }
           add(
@@ -100,12 +124,22 @@ export namespace SdkWebSocketCloneProgrammer {
           );
         }
         for (const name of [imp.default, imp.namespace])
-          if (name !== null && uses(props.body, name)) add(imp.text);
+          if (name !== null && uses(props.body, name, props.location))
+            retained.add(name);
+        if (retained.size !== 0) {
+          const specifier: string = relative
+            ? relativeImport(
+                ctx.output,
+                path.resolve(path.dirname(props.location), imp.specifier),
+              )
+            : imp.specifier;
+          add(retainedImport(imp, retained, specifier));
+        }
       }
 
-      for (const name of getExportedNames(props.source)) {
+      for (const name of getExportedNames(props.source, props.location)) {
         if (name === null || name === props.target) continue;
-        if (uses(props.body, name) === false) continue;
+        if (uses(props.body, name, props.location) === false) continue;
         if ((await clone(ctx)(props.location, name)) === true)
           add(`import type { ${name} } from "./${name}";`);
       }
@@ -139,158 +173,163 @@ export namespace SdkWebSocketCloneProgrammer {
     return file;
   };
 
-  const getDeclarations = (source: string, name: string): string[] => {
-    const output: string[] = [];
-    const searchable: string = maskTrivia(source);
-    const regex: RegExp = declarationRegex(name);
-    for (const match of searchable.matchAll(regex)) {
-      if (isTopLevel(searchable, match.index!) === false) continue;
-      const end: number = declarationEnd(searchable, match.index!, match[1]!);
-      if (end !== -1) output.push(source.slice(match.index!, end).trim());
+  const syntax = (source: string, filename: string) => {
+    const options = {
+      sourceType: "module",
+      sourceFilename: filename,
+    } as const;
+    const dialect = (decorators: "decorators-legacy" | "decorators") =>
+      parse(source, {
+        ...options,
+        plugins: [
+          decorators,
+          "decoratorAutoAccessors",
+          ["typescript", { dts: /\.d\.[cm]?ts$/.test(filename) }],
+          ...(filename.endsWith(".tsx") ? (["jsx"] as const) : []),
+        ],
+      }).program;
+    // Nest parameter decorators use the legacy dialect. Standard decorators
+    // also permit placement after export; retry that strict grammar without
+    // enabling error recovery or accepting a partial syntax tree.
+    try {
+      return dialect("decorators-legacy");
+    } catch {
+      return dialect("decorators");
     }
-    return output;
   };
 
-  const getExportedNames = (source: string): string[] => {
-    const searchable: string = maskTrivia(source);
-    return Array.from(
-      searchable.matchAll(declarationRegex("[A-Za-z_$][\\w$]*")),
+  const exportedName = (
+    statement: ReturnType<typeof syntax>["body"][number],
+  ): string | null => {
+    if (statement.type !== "ExportNamedDeclaration") return null;
+    const declaration = statement.declaration;
+    if (
+      declaration === null ||
+      declaration === undefined ||
+      !("id" in declaration)
     )
-      .filter((match) => isTopLevel(searchable, match.index!))
-      .map((match) => match[2]!);
+      return null;
+    return declaration.id?.type === "Identifier" ? declaration.id.name : null;
   };
 
-  const declarationRegex = (name: string): RegExp =>
-    new RegExp(
-      `export\\s+(?:declare\\s+)?(interface|type|enum|namespace|class)\\s+(${name})\\b`,
-      "g",
-    );
-
-  const declarationEnd = (
+  const getDeclarations = (
     source: string,
-    start: number,
-    kind: string,
-  ): number => {
-    let depth: number = 0;
-    let block: boolean = false;
-    for (let i = start; i < source.length; ++i) {
-      const ch: string = source[i]!;
-      if (ch === "{") {
-        ++depth;
-        block = true;
-      } else if (ch === "}") {
-        --depth;
-        if (kind !== "type" && block && depth === 0) return i + 1;
-      } else if (ch === ";" && block === false && depth === 0) return i + 1;
-      else if (ch === ";" && kind === "type" && depth === 0) return i + 1;
+    name: string,
+    filename: string,
+  ): string[] =>
+    syntax(source, filename)
+      .body.filter((statement) => exportedName(statement) === name)
+      .map((statement) => source.slice(statement.start!, statement.end!));
+
+  const getExportedNames = (source: string, filename: string): string[] =>
+    syntax(source, filename)
+      .body.map(exportedName)
+      .filter((name): name is string => name !== null);
+
+  const getImports = (source: string, filename: string): IImport[] =>
+    syntax(source, filename)
+      .body.filter((statement) => statement.type === "ImportDeclaration")
+      .map((statement) => ({
+        node: statement,
+        text: source.slice(statement.start!, statement.end!),
+        specifier: statement.source.value,
+        default:
+          statement.specifiers.find(
+            (specifier) => specifier.type === "ImportDefaultSpecifier",
+          )?.local.name ?? null,
+        namespace:
+          statement.specifiers.find(
+            (specifier) => specifier.type === "ImportNamespaceSpecifier",
+          )?.local.name ?? null,
+        elements: statement.specifiers
+          .filter((specifier) => specifier.type === "ImportSpecifier")
+          .map((specifier) => ({
+            imported:
+              specifier.imported.type === "Identifier"
+                ? specifier.imported.name
+                : specifier.imported.value,
+            local: specifier.local.name,
+          })),
+      }));
+
+  /** Rebuilds only retained bindings, preserving their authored type modifiers. */
+  const retainedImport = (
+    imp: IImport,
+    retained: Set<string>,
+    specifier: string,
+  ): string => {
+    const clauses: string[] = [];
+    const named: string[] = [];
+    for (const binding of imp.node.specifiers) {
+      if (!retained.has(binding.local.name)) continue;
+      if (binding.type === "ImportDefaultSpecifier")
+        clauses.push(binding.local.name);
+      else if (binding.type === "ImportNamespaceSpecifier")
+        clauses.push(`* as ${binding.local.name}`);
+      else
+        named.push(
+          imp.text.slice(
+            binding.start! - imp.node.start!,
+            binding.end! - imp.node.start!,
+          ),
+        );
     }
-    return -1;
+    if (named.length) clauses.push(`{ ${named.join(", ")} }`);
+    const suffix: string = imp.text.slice(
+      imp.node.source.end! - imp.node.start!,
+    );
+    return `import${imp.node.importKind === "type" ? " type" : ""} ${clauses.join(", ")} from ${JSON.stringify(specifier)}${suffix}`;
   };
 
-  const isTopLevel = (source: string, index: number): boolean => {
-    let depth: number = 0;
-    for (let i = 0; i < index; ++i) {
-      const ch: string = source[i]!;
-      if (ch === "{") ++depth;
-      else if (ch === "}") --depth;
-    }
-    return depth === 0;
+  /** Module spelling from a copied declaration to its original source import. */
+  const relativeImport = (output: string, source: string): string => {
+    const native: string = path.relative(output, source);
+    const relative: string = native.split(path.sep).join("/");
+    return path.isAbsolute(native) || relative.startsWith(".")
+      ? relative
+      : `./${relative}`;
   };
 
-  const maskTrivia = (source: string): string => {
-    const out: string[] = source.split("");
-    const mask = (index: number): void => {
-      if (out[index] !== "\n" && out[index] !== "\r") out[index] = " ";
+  const uses = (body: string, name: string, filename: string): boolean => {
+    const visit = (value: unknown): boolean => {
+      if (value === null || typeof value !== "object") return false;
+      if (Array.isArray(value)) return value.some(visit);
+      const node = value as Record<string, unknown>;
+      if (node.type === "Identifier" && node.name === name) return true;
+      return Object.entries(node).some(
+        ([key, child]) =>
+          key !== "comments" &&
+          key !== "leadingComments" &&
+          key !== "trailingComments" &&
+          key !== "innerComments" &&
+          key !== "loc" &&
+          visit(child),
+      );
     };
-
-    let quote: string | null = null;
-    let escaped: boolean = false;
-    for (let i = 0; i < out.length; ++i) {
-      const ch: string = source[i]!;
-      const next: string | undefined = source[i + 1];
-      if (quote !== null) {
-        mask(i);
-        if (escaped) escaped = false;
-        else if (ch === "\\") escaped = true;
-        else if (ch === quote) quote = null;
-      } else if (ch === "/" && next === "/") {
-        mask(i++);
-        for (; i < out.length && source[i] !== "\n"; ++i) mask(i);
-        --i;
-      } else if (ch === "/" && next === "*") {
-        mask(i++);
-        mask(i);
-        for (++i; i < out.length; ++i) {
-          const current: string = source[i]!;
-          const following: string | undefined = source[i + 1];
-          mask(i);
-          if (current === "*" && following === "/") {
-            mask(++i);
-            break;
-          }
-        }
-      } else if (ch === '"' || ch === "'" || ch === "`") {
-        quote = ch;
-        mask(i);
-      }
-    }
-    return out.join("");
+    return visit(syntax(body, filename));
   };
 
-  const getImports = (source: string): IImport[] =>
-    Array.from(
-      source.matchAll(/import\s+([\s\S]*?)\s+from\s+["']([^"']+)["'];?/g),
-    ).map((match) => {
-      const clause: string = match[1]!.trim();
-      const specifier: string = match[2]!;
-      return {
-        text: match[0]!.trim(),
-        specifier,
-        default: defaultImportName(clause),
-        namespace: namespaceImportName(clause),
-        elements: namedImportElements(clause),
-      };
-    });
-
-  const defaultImportName = (clause: string): string | null => {
-    const first: string = clause
-      .split(",")[0]!
-      .trim()
-      .replace(/^type\s+/, "");
-    return first.length && first.startsWith("{") === false ? first : null;
-  };
-
-  const namespaceImportName = (clause: string): string | null => {
-    const match: RegExpMatchArray | null = clause.match(/\*\s+as\s+(\w+)/);
-    return match?.[1] ?? null;
-  };
-
-  const namedImportElements = (clause: string): IImportElement[] => {
-    const match: RegExpMatchArray | null = clause.match(/\{([\s\S]*?)\}/);
-    if (match === null) return [];
-    return match[1]!
-      .split(",")
-      .map((part) => part.trim().replace(/^type\s+/, ""))
-      .filter((part) => part.length)
-      .map((part) => {
-        const pieces: string[] = part.split(/\s+as\s+/);
-        const imported: string = pieces[0]!.trim();
-        return {
-          imported,
-          local: (pieces[1] ?? imported).trim(),
-        };
-      });
-  };
-
-  const uses = (body: string, name: string): boolean =>
-    new RegExp(`\\b${escapeRegExp(name)}\\b`).test(body);
-
-  const escapeRegExp = (str: string): string =>
-    str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-
+  /**
+   * Returns the key of an import: its file and name.
+   *
+   * @evidence contracts/common.md#principled-implementation The pair identifies one imported declaration.
+   * @evidence contracts/common.md#clear-and-simple-design One template.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The key is the same wherever it is built.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation importKey combines the supplied source identity and declaration name without opening a path or resolving filesystem identity; its caller owns source resolution.
+   */
   export const importKey = (file: string, name: string): string =>
     `${file}#${name}`;
 
+  /**
+   * Reports whether a path lies under a `node_modules` directory.
+   *
+   * @evidence contracts/common.md#principled-implementation The path is resolved and split on both separators, so it holds on every platform.
+   * @evidence contracts/common.md#clear-and-simple-design One expression.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts A package's declaration is never copied.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidence contracts/portability.md#os-neutral-implementation path.resolve produces a native absolute spelling and splitting accepts both native separator forms. The literal node_modules component classifies installation layout; it does not inspect symlink targets or assert a volume's case equivalence.
+   */
   export const isNodeModulesPath = (file: string): boolean =>
     path
       .resolve(file)
@@ -307,6 +346,10 @@ interface IContext {
 type CloneStatus = "pending" | "written" | "missing";
 
 interface IImport {
+  node: Extract<
+    ReturnType<typeof parse>["program"]["body"][number],
+    { type: "ImportDeclaration" }
+  >;
   text: string;
   specifier: string;
   default: string | null;

package/src/generates/internal/SdkWebSocketNamespaceProgrammer.ts

@@ -19,7 +19,26 @@ import { SdkAliasCollection } from "./SdkAliasCollection";
 import { SdkPathTemplate } from "./SdkPathTemplate";
 import { SdkWebSocketParameterProgrammer } from "./SdkWebSocketParameterProgrammer";
 
+/**
+ * Writes the namespace of a WebSocket route.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace holds the route's connection types and its path builder.
+ * @evidence contracts/common.md#clear-and-simple-design One public function and two writers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The parts follow the route.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkWebSocketNamespaceProgrammer composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+ */
 export namespace SdkWebSocketNamespaceProgrammer {
+  /**
+   * Returns the namespace of a WebSocket route: its `Header`, `Query`,
+   * `Provider`, and `Listener` types and its `path`.
+   *
+   * @evidence contracts/common.md#principled-implementation Output, Header, Provider and Listener are always declared; Query requires a query parameter and Props requires keyword mode. A decorated header or driver supplies its type ahead of the acceptor's corresponding type argument.
+   * @evidence contracts/common.md#clear-and-simple-design One declaration composed of the writers.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The members follow the route.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkWebSocketNamespaceProgrammer.write composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const write =
     (project: INestiaProject) =>
     (importer: ImportDictionary) =>

package/src/generates/internal/SdkWebSocketParameterProgrammer.ts

@@ -11,7 +11,25 @@ import { ITypedWebSocketRouteParameter } from "../../structures/ITypedWebSocketR
 import { StringUtil } from "../../utils/StringUtil";
 import { SdkAliasCollection } from "./SdkAliasCollection";
 
+/**
+ * The parameters of a WebSocket route's SDK function.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace decides the identifiers, lists the entries, and writes the declarations, as the HTTP one does.
+ * @evidence contracts/common.md#clear-and-simple-design Several small functions.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The identifiers are decided once.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkWebSocketParameterProgrammer composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+ */
 export namespace SdkWebSocketParameterProgrammer {
+  /**
+   * One parameter of a WebSocket route: its key and its type.
+   *
+   * @evidence contracts/common.md#principled-implementation The record is what a declaration needs.
+   * @evidence contracts/common.md#clear-and-simple-design A two-member record.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkWebSocketParameterProgrammer.IEntry composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export interface IEntry {
     key: string;
     type: TypeNode;
@@ -27,6 +45,12 @@ export namespace SdkWebSocketParameterProgrammer {
    * carry the query object and the provider, so they yield to a path parameter
    * of the same name instead of repeating it. A `props` key shadows nothing, so
    * it yields to nothing else.
+   *
+   * @evidence contracts/common.md#principled-implementation One decision serves the two scopes.
+   * @evidence contracts/common.md#clear-and-simple-design A record of names and two lookups.
+   * @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 declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkWebSocketParameterProgrammer.INames composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
    */
   export interface INames {
     connection: string;
@@ -42,13 +66,38 @@ export namespace SdkWebSocketParameterProgrammer {
     value: string;
     elem: string;
 
-    /** Local identifier of a path parameter in positional mode. */
+    /**
+     * Local identifier of a path parameter in positional mode.
+     *
+     * @evidence contracts/common.md#principled-implementation A path parameter keeps its name unless the SDK cannot change the name it collides with.
+     * @evidence contracts/common.md#clear-and-simple-design One lookup.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts It reads the decision.
+     * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkWebSocketParameterProgrammer.INames.parameter composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+     */
     parameter: (p: ITypedWebSocketRouteParameter.IParam) => string;
 
-    /** Reads a parameter, or one of `query` and `provider`, by its key. */
+    /**
+     * Reads a parameter, or one of `query` and `provider`, by its key.
+     *
+     * @evidence contracts/common.md#principled-implementation The read follows the mode of the function.
+     * @evidence contracts/common.md#clear-and-simple-design One lookup.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts It reads the decision.
+     * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkWebSocketParameterProgrammer.INames.access composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+     */
     access: (key: string) => Expression;
   }
 
+  /**
+   * Decides the identifiers of a WebSocket route's function and `path()` once.
+   *
+   * @evidence contracts/common.md#principled-implementation The fixed names each scope references are collected, and `query` and `provider` yield to a path parameter of the same name.
+   * @evidence contracts/common.md#clear-and-simple-design One function over the scope sets.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Only shadowed names are renamed.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkWebSocketParameterProgrammer.getNames composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const getNames = (props: {
     project: INestiaProject;
     route: ITypedWebSocketRoute;
@@ -133,6 +182,16 @@ export namespace SdkWebSocketParameterProgrammer {
     };
   };
 
+  /**
+   * Returns the entries of a WebSocket route: its path parameters, its query,
+   * and its provider.
+   *
+   * @evidence contracts/common.md#principled-implementation The query exists only when the route has one, and the provider is included only when the caller requests it.
+   * @evidence contracts/common.md#clear-and-simple-design One list.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The order is the call order.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkWebSocketParameterProgrammer.getEntries composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const getEntries = (props: {
     project: INestiaProject;
     route: ITypedWebSocketRoute;
@@ -165,6 +224,16 @@ export namespace SdkWebSocketParameterProgrammer {
     ];
   };
 
+  /**
+   * Returns the parameter declarations of a WebSocket route's function: `props`
+   * in keyword mode, and one positional parameter per entry otherwise.
+   *
+   * @evidence contracts/common.md#principled-implementation The names come from `getNames`.
+   * @evidence contracts/common.md#clear-and-simple-design One function of two modes.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The two modes share the entries.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkWebSocketParameterProgrammer.getParameterDeclarations composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const getParameterDeclarations = (props: {
     project: INestiaProject;
     route: ITypedWebSocketRoute;
@@ -207,6 +276,16 @@ export namespace SdkWebSocketParameterProgrammer {
     );
   };
 
+  /**
+   * Reports whether the route's path holds no parameter, so `path()` takes
+   * none.
+   *
+   * @evidence contracts/common.md#principled-implementation The route has no path parameter and no query.
+   * @evidence contracts/common.md#clear-and-simple-design One expression.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It reads the route.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkWebSocketParameterProgrammer.isPathEmpty composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const isPathEmpty = (route: ITypedWebSocketRoute): boolean =>
     route.pathParameters.length === 0 && route.query === null;
 }

package/src/generates/internal/SdkWebSocketRouteProgrammer.ts

@@ -16,7 +16,25 @@ import { SdkImportWizard } from "./SdkImportWizard";
 import { SdkWebSocketNamespaceProgrammer } from "./SdkWebSocketNamespaceProgrammer";
 import { SdkWebSocketParameterProgrammer } from "./SdkWebSocketParameterProgrammer";
 
+/**
+ * Writes a WebSocket route into the SDK: its function and its namespace.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace prints the async function that opens the connection with `tgrid`.
+ * @evidence contracts/common.md#clear-and-simple-design One public function and the writers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The identifiers are decided by the parameter programmer.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkWebSocketRouteProgrammer composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+ */
 export namespace SdkWebSocketRouteProgrammer {
+  /**
+   * Returns the function and the namespace of a WebSocket route.
+   *
+   * @evidence contracts/common.md#principled-implementation The two nodes are composed together so they share names.
+   * @evidence contracts/common.md#clear-and-simple-design One function.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The shape follows the route.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkWebSocketRouteProgrammer.write composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const write =
     (project: INestiaProject) =>
     (importer: ImportDictionary) =>