@nestia/sdk 14.0.1 → 14.0.2

package/src/analyses/TypedHttpRouteAnalyzer.ts

@@ -18,34 +18,40 @@ import { ITypedHttpRoute } from "../structures/ITypedHttpRoute";
 import { ITypedHttpRouteException } from "../structures/ITypedHttpRouteException";
 import { ITypedHttpRouteParameter } from "../structures/ITypedHttpRouteParameter";
 import { ITypedHttpRouteSuccess } from "../structures/ITypedHttpRouteSuccess";
+import { ITypedMcpRoute } from "../structures/ITypedMcpRoute";
 import { PathUtil } from "../utils/PathUtil";
+import { StringUtil } from "../utils/StringUtil";
 
+/**
+ * Turns reflected HTTP operations into typed routes, one per path, and builds
+ * the shared dictionary of the JSON components HTTP and MCP routes use.
+ *
+ * @evidence contracts/common.md#principled-implementation Each operation's metadata is resolved against its own components and validated by the policy of its position, the routes carry the typed parameters, the success response, and the exceptions, and the dictionary of the routes is built after component names that collide with different definitions are renamed per controller.
+ * @evidence contracts/common.md#clear-and-simple-design Two public functions and private collectors for the component rename.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The rename mutates only component definitions owned by analysis; consumers emit resolved structural types rather than modifying foreign cache fields or replacing names in strings.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ * efficient algorithms: This namespace groups operations; analyze and routeDictionary own the algorithms.
+ * reuse equivalent work: The namespace itself coordinates no completed or in-flight work.
+ * bound retention and release resources: The namespace owns no cache, handle or running task.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation TypedHttpRouteAnalyzer 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 TypedHttpRouteAnalyzer {
-  export const dictionary = (
-    controllers: IReflectController[],
-  ): IMetadataDictionary => {
-    const individual: IMetadataComponents[] = [];
-    for (const c of controllers)
-      for (const o of c.operations) {
-        if (o.protocol !== "http") continue;
-        if (o.success) individual.push(o.success.components);
-        for (const p of o.parameters) individual.push(p.components);
-        for (const e of Object.values(o.exceptions))
-          individual.push(e.components);
-      }
-    const components: MetadataComponents = MetadataComponents.from({
-      objects: uniqueComponents(individual.flatMap((c) => c.objects)),
-      arrays: uniqueComponents(individual.flatMap((c) => c.arrays)),
-      tuples: uniqueComponents(individual.flatMap((c) => c.tuples)),
-      aliases: uniqueComponents(individual.flatMap((c) => c.aliases)),
-    });
-    return components.dictionary;
-  };
-
+  /**
+   * Returns the typed routes of one operation, one per path, or none when the
+   * metadata violates a policy; the violations are pushed to the errors.
+   *
+   * @evidence contracts/common.md#principled-implementation Each metadata is resolved against its own components and validated with the policy of its position (JSON, query, header, or text), the `@setHeader` and `@assignHeaders` tags become header directives, and the route splits the parameters by category.
+   * @evidence contracts/common.md#clear-and-simple-design One function.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The policies come from the validators of the package.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the result and the errors.
+   * efficient algorithms: Each supplied parameter and exception is cast once, policy validation belongs to MetadataFactory, and route splitting maps only the supplied paths.
+   * reuse equivalent work: Independently supplied operation metadata and position-specific validation have no shared completed or in-flight request.
+   * bound retention and release resources: Metadata dictionaries and local diagnostics belong to this synchronous operation and its returned routes; no process, handle or persistent history is retained.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation TypedHttpRouteAnalyzer.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: {
     controller: IReflectController;
     errors: IReflectOperationError[];
-    dictionary: IMetadataDictionary;
     operation: IReflectHttpOperation;
     paths: string[];
   }): ITypedHttpRoute[] => {
@@ -57,7 +63,6 @@ export namespace TypedHttpRouteAnalyzer {
         validate?: MetadataFactory.Validator;
       },
       from: string,
-      escape: boolean,
     ): MetadataSchema => {
       const components: MetadataComponents = MetadataComponents.from(
         next.components,
@@ -70,12 +75,6 @@ export namespace TypedHttpRouteAnalyzer {
         next.validate === undefined
           ? []
           : MetadataFactory.validate({
-              options: {
-                escape,
-                constant: true,
-                absorb: true,
-                validate: next.validate,
-              },
               functor: next.validate,
               metadata,
             });
@@ -111,28 +110,18 @@ export namespace TypedHttpRouteAnalyzer {
           example: value.example,
           examples: value.examples,
           type: value.type,
-          metadata: cast(value, `exception (status: ${key})`, true),
+          metadata: cast(value, `exception (status: ${key})`),
         },
       ]),
     );
     const parameters: ITypedHttpRouteParameter[] =
       props.operation.parameters.map((p) => ({
         ...p,
-        metadata: cast(
-          p,
-          `parameter (name: ${JSON.stringify(p.name)})`,
-          p.category === "body" &&
-            (p.contentType === "application/json" || p.encrypted === true),
-        ),
+        metadata: cast(p, `parameter (name: ${JSON.stringify(p.name)})`),
       }));
     const success: ITypedHttpRouteSuccess = {
       ...props.operation.success,
-      metadata: cast(
-        props.operation.success,
-        "success",
-        props.operation.success.encrypted ||
-          props.operation.success.contentType === "application/json",
-      ),
+      metadata: cast(props.operation.success, "success"),
       setHeaders: props.operation.jsDocTags
         .filter(
           (t) =>
@@ -193,8 +182,21 @@ export namespace TypedHttpRouteAnalyzer {
     );
   };
 
+  /**
+   * Returns the dictionary of the components the routes actually use, after
+   * renaming components whose names collide with different definitions.
+   *
+   * @evidence contracts/common.md#principled-implementation Objects, aliases and recursive arrays/tuples share their emitted accessor-path slots, while finite and object-mediated collections remain kind-specific inline groups. Different semantic classes in one slot receive unique controller-qualified names, and the emitted dictionary follows escaped returns rather than original-only toJSON declarations.
+   * @evidence contracts/common.md#clear-and-simple-design One function over private collectors.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Finite partition refinement preserves semantic discriminators and user payloads while component edges reference equivalence classes. Only actual component ordinals are omitted; no foreign name cache or generated text is rewritten.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the result and the rename.
+   * efficient algorithms: Each refinement round encodes each distinct component body with constant-sized component edges. The partition only splits and stabilizes within the distinct component count, avoiding exponential expansion of shared DAGs.
+   * reuse equivalent work: One local partition compares all routes together, reuses graph node colors for shared children and supplies all collision groups; equivalent same-slot definitions reuse one emitted representative.
+   * bound retention and release resources: Collected nodes, partitions and visited sets are local to this synchronous call and are released with it; the returned dictionary retains only its reachable emitted representatives.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation TypedHttpRouteAnalyzer.routeDictionary 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 routeDictionary = (
-    routes: Array<ITypedHttpRoute>,
+    routes: Array<ITypedHttpRoute | ITypedMcpRoute>,
   ): IMetadataDictionary => {
     renameDuplicateComponents(routes);
     const dictionary: IMetadataDictionary = {
@@ -203,20 +205,9 @@ export namespace TypedHttpRouteAnalyzer {
       arrays: new Map(),
       tuples: new Map(),
     };
-    for (const route of routes) {
-      for (const p of [
-        ...route.pathParameters,
-        ...route.queryParameters,
-        ...route.headerParameters,
-        ...(route.queryObject ? [route.queryObject] : []),
-        ...(route.body ? [route.body] : []),
-        ...(route.headerObject ? [route.headerObject] : []),
-      ])
-        enrollMetadata(dictionary, p.metadata);
-      for (const e of Object.values(route.exceptions))
-        enrollMetadata(dictionary, e.metadata);
-      enrollMetadata(dictionary, route.success.metadata);
-    }
+    for (const route of routes)
+      for (const metadata of routeMetadatas(route))
+        enrollMetadata(dictionary, metadata);
     return dictionary;
   };
 }
@@ -230,21 +221,51 @@ type ComponentType =
 
 interface IComponentEntry {
   kind: ComponentKind;
-  route: ITypedHttpRoute;
+  route: ITypedHttpRoute | ITypedMcpRoute;
   signature: string;
   type: ComponentType;
 }
 
-const renameDuplicateComponents = (routes: ITypedHttpRoute[]): void => {
+const renameDuplicateComponents = (
+  routes: Array<ITypedHttpRoute | ITypedMcpRoute>,
+): void => {
   const entries: IComponentEntry[] = [];
   for (const route of routes)
     for (const metadata of routeMetadatas(route))
       collectComponentEntries(entries, route, metadata);
+  // Original toJSON definitions participate in semantic comparison but do not
+  // become emitted declarations unless another route uses them directly.
+  const comparisonEntries: IComponentEntry[] = [];
+  for (const route of routes)
+    for (const metadata of routeMetadatas(route))
+      collectComponentEntries(
+        comparisonEntries,
+        route,
+        metadata,
+        createCollectVisited(),
+        true,
+      );
+  const signatures = componentSignatures(comparisonEntries);
+  for (const entry of entries) entry.signature = signatures.get(entry.type)!;
 
-  const used: Set<string> = new Set(entries.map((e) => e.type!.name));
+  const used: Set<string> = new Set(
+    entries.map((e) => StringUtil.accessorsOf(e.type.name).join(".")),
+  );
   const groups: Map<string, IComponentEntry[]> = new Map();
   for (const entry of entries) {
-    const key: string = `${entry.kind}:${entry.type!.name}`;
+    // Named recursive collections also need a declaration to break cycles.
+    // Ordinary arrays and tuples remain inline forms without their own slot.
+    const slot =
+      entry.kind === "objects" ||
+      entry.kind === "aliases" ||
+      entry.type.recursive
+        ? "declarations"
+        : entry.kind;
+    const name =
+      slot === "declarations"
+        ? StringUtil.accessorsOf(entry.type.name).join(".")
+        : entry.type.name;
+    const key: string = `${slot}:${name}`;
     const group: IComponentEntry[] | undefined = groups.get(key);
     if (group === undefined) groups.set(key, [entry]);
     else group.push(entry);
@@ -267,55 +288,100 @@ const renameDuplicateComponents = (routes: ITypedHttpRoute[]): void => {
             `${prefix}.${oldName}`,
           );
           renamed.set(entry.signature, name);
-          used.add(name);
+          used.add(StringUtil.accessorsOf(name).join("."));
           return name;
         })();
       (entry.type as { name: string }).name = next;
     }
   }
-  for (const route of routes)
-    for (const metadata of routeMetadatas(route))
-      clearMetadataNameCache(metadata);
 };
 
-const routeMetadatas = (route: ITypedHttpRoute): MetadataSchema[] => [
-  ...[
-    ...route.pathParameters,
-    ...route.queryParameters,
-    ...route.headerParameters,
-    ...(route.queryObject ? [route.queryObject] : []),
-    ...(route.body ? [route.body] : []),
-    ...(route.headerObject ? [route.headerObject] : []),
-  ].map((p) => p.metadata),
-  ...Object.values(route.exceptions).map((e) => e.metadata),
-  route.success.metadata,
-];
+const routeMetadatas = (
+  route: ITypedHttpRoute | ITypedMcpRoute,
+): MetadataSchema[] =>
+  route.protocol === "mcp"
+    ? [route.inputMetadata, route.outputMetadata].filter(
+        (m): m is MetadataSchema => m !== undefined,
+      )
+    : [
+        ...[
+          ...route.pathParameters,
+          ...route.queryParameters,
+          ...route.headerParameters,
+          ...(route.queryObject ? [route.queryObject] : []),
+          ...(route.body ? [route.body] : []),
+          ...(route.headerObject ? [route.headerObject] : []),
+        ].map((p) => p.metadata),
+        ...Object.values(route.exceptions).map((e) => e.metadata),
+        route.success.metadata,
+      ];
 
 const collectComponentEntries = (
   entries: IComponentEntry[],
-  route: ITypedHttpRoute,
+  route: ITypedHttpRoute | ITypedMcpRoute,
   metadata: MetadataSchema,
   visited: ICollectVisited = createCollectVisited(),
+  includeOriginal: boolean = false,
 ): void => {
   if (visited.schemas.has(metadata)) return;
   visited.schemas.add(metadata);
 
   if (metadata.rest !== null)
-    collectComponentEntries(entries, route, metadata.rest, visited);
+    collectComponentEntries(
+      entries,
+      route,
+      metadata.rest,
+      visited,
+      includeOriginal,
+    );
   if (metadata.escaped !== null) {
-    collectComponentEntries(entries, route, metadata.escaped.original, visited);
-    collectComponentEntries(entries, route, metadata.escaped.returns, visited);
+    if (includeOriginal)
+      collectComponentEntries(
+        entries,
+        route,
+        metadata.escaped.original,
+        visited,
+        includeOriginal,
+      );
+    collectComponentEntries(
+      entries,
+      route,
+      metadata.escaped.returns,
+      visited,
+      includeOriginal,
+    );
   }
+  for (const template of metadata.templates)
+    for (const elem of template.row ?? template)
+      collectComponentEntries(entries, route, elem, visited, includeOriginal);
   for (const func of metadata.functions) {
     for (const p of func.parameters)
-      collectComponentEntries(entries, route, p.type, visited);
-    collectComponentEntries(entries, route, func.output, visited);
+      collectComponentEntries(entries, route, p.type, visited, includeOriginal);
+    collectComponentEntries(
+      entries,
+      route,
+      func.output,
+      visited,
+      includeOriginal,
+    );
   }
   for (const set of metadata.sets)
-    collectComponentEntries(entries, route, set.value, visited);
+    collectComponentEntries(
+      entries,
+      route,
+      set.value,
+      visited,
+      includeOriginal,
+    );
   for (const map of metadata.maps) {
-    collectComponentEntries(entries, route, map.key, visited);
-    collectComponentEntries(entries, route, map.value, visited);
+    collectComponentEntries(entries, route, map.key, visited, includeOriginal);
+    collectComponentEntries(
+      entries,
+      route,
+      map.value,
+      visited,
+      includeOriginal,
+    );
   }
   for (const array of metadata.arrays)
     if (visited.arrays.has(array.type as MetadataArrayType) === false) {
@@ -328,6 +394,7 @@ const collectComponentEntries = (
         route,
         (array.type as MetadataArrayType as MetadataArrayType).value,
         visited,
+        includeOriginal,
       );
     }
   for (const tuple of metadata.tuples)
@@ -338,7 +405,7 @@ const collectComponentEntries = (
       );
       for (const elem of (tuple.type as MetadataTupleType as MetadataTupleType)
         .elements)
-        collectComponentEntries(entries, route, elem, visited);
+        collectComponentEntries(entries, route, elem, visited, includeOriginal);
     }
   for (const alias of metadata.aliases)
     if (visited.aliases.has(alias.type as MetadataAliasType) === false) {
@@ -351,6 +418,7 @@ const collectComponentEntries = (
         route,
         (alias.type as MetadataAliasType as MetadataAliasType).value,
         visited,
+        includeOriginal,
       );
     }
   for (const obj of metadata.objects)
@@ -361,31 +429,96 @@ const collectComponentEntries = (
       );
       for (const p of (obj.type as MetadataObjectType as MetadataObjectType)
         .properties) {
-        collectComponentEntries(entries, route, p.key, visited);
-        collectComponentEntries(entries, route, p.value, visited);
+        collectComponentEntries(
+          entries,
+          route,
+          p.key,
+          visited,
+          includeOriginal,
+        );
+        collectComponentEntries(
+          entries,
+          route,
+          p.value,
+          visited,
+          includeOriginal,
+        );
       }
     }
 };
 
 const componentEntry = <T extends ComponentType>(
-  route: ITypedHttpRoute,
+  route: ITypedHttpRoute | ITypedMcpRoute,
   kind: ComponentKind,
   type: T,
 ): IComponentEntry => ({
   kind,
   route,
-  signature: componentSignature(type),
+  signature: "",
   type,
 });
 
-const componentSignature = (type: ComponentType): string =>
-  JSON.stringify(type, (key, value) =>
-    // `type` is the resolved back-reference attached by
-    // `MetadataSchema.from`; it closes a cycle on recursive schemas.
-    // `index` carries the per-route ordinal and is not part of the
-    // component's identity.
-    key === "index" || key === "type" ? undefined : value,
-  );
+/**
+ * Refines a finite component graph until no semantic equivalence class splits.
+ * Component edges carry class numbers, so shared children are never expanded as
+ * trees. Ordinary payloads retain separate object/array representations. Each
+ * round preserves the previous partition and can only split its classes; at
+ * most the number of distinct components rounds are necessary.
+ */
+const componentSignatures = (
+  entries: IComponentEntry[],
+): Map<ComponentType, string> => {
+  const kinds = new Map<ComponentType, ComponentKind>();
+  for (const entry of entries) kinds.set(entry.type, entry.kind);
+  const nodes = [...kinds.keys()];
+  let colors = new Map(nodes.map((node) => [node, 0]));
+  let classes = nodes.length ? 1 : 0;
+  while (nodes.length) {
+    const intern = new Map<string, number>();
+    const next = new Map<ComponentType, number>();
+    for (const node of nodes) {
+      const ancestors = new WeakMap<object, number>();
+      let depth = 0;
+      const encode = (value: unknown, root = false): unknown => {
+        if (value === null || typeof value !== "object") return value;
+        if (!root && kinds.has(value as ComponentType))
+          return ["component", colors.get(value as ComponentType)];
+        const position = ancestors.get(value);
+        if (position !== undefined) return ["payload-cycle", position];
+        ancestors.set(value, depth++);
+        const result = Array.isArray(value)
+          ? ["array", value.map((child) => encode(child))]
+          : [
+              "object",
+              Object.entries(value)
+                .filter(
+                  ([key, child]) =>
+                    child !== undefined && !(root && key === "index"),
+                )
+                .map(([key, child]) => [key, encode(child)]),
+            ];
+        ancestors.delete(value);
+        --depth;
+        return result;
+      };
+      const signature = JSON.stringify([
+        colors.get(node),
+        kinds.get(node),
+        encode(node, true),
+      ]);
+      let color = intern.get(signature);
+      if (color === undefined) {
+        color = intern.size;
+        intern.set(signature, color);
+      }
+      next.set(node, color);
+    }
+    colors = next;
+    if (intern.size === classes) break;
+    classes = intern.size;
+  }
+  return new Map(nodes.map((node) => [node, String(colors.get(node))]));
+};
 
 const normalizeComponentNamespace = (name: string): string => {
   const next: string = name.replace(/[^A-Za-z0-9_$]/g, "_");
@@ -393,63 +526,9 @@ const normalizeComponentNamespace = (name: string): string => {
 };
 
 const escapeComponentName = (used: Set<string>, name: string): string =>
-  used.has(name) ? escapeComponentName(used, `_${name}`) : name;
-
-const clearMetadataNameCache = (
-  metadata: MetadataSchema,
-  visited: WeakSet<MetadataSchema> = new WeakSet(),
-): void => {
-  if (visited.has(metadata)) return;
-  visited.add(metadata);
-  (metadata as unknown as { name_?: string }).name_ = undefined;
-
-  if (metadata.rest !== null) clearMetadataNameCache(metadata.rest, visited);
-  if (metadata.escaped !== null) {
-    clearMetadataNameCache(metadata.escaped.original, visited);
-    clearMetadataNameCache(metadata.escaped.returns, visited);
-  }
-  for (const func of metadata.functions) {
-    for (const p of func.parameters) clearMetadataNameCache(p.type, visited);
-    clearMetadataNameCache(func.output, visited);
-  }
-  for (const set of metadata.sets) {
-    (set as unknown as { name_?: string }).name_ = undefined;
-    clearMetadataNameCache(set.value, visited);
-  }
-  for (const map of metadata.maps) {
-    (map as unknown as { name_?: string }).name_ = undefined;
-    clearMetadataNameCache(map.key, visited);
-    clearMetadataNameCache(map.value, visited);
-  }
-  for (const array of metadata.arrays) {
-    (array as unknown as { name_?: string }).name_ = undefined;
-    clearMetadataNameCache(
-      (array.type as MetadataArrayType as MetadataArrayType).value,
-      visited,
-    );
-  }
-  for (const tuple of metadata.tuples) {
-    (tuple as unknown as { name_?: string }).name_ = undefined;
-    for (const elem of (tuple.type as MetadataTupleType as MetadataTupleType)
-      .elements)
-      clearMetadataNameCache(elem, visited);
-  }
-  for (const alias of metadata.aliases) {
-    (alias as unknown as { name_?: string }).name_ = undefined;
-    clearMetadataNameCache(
-      (alias.type as MetadataAliasType as MetadataAliasType).value,
-      visited,
-    );
-  }
-  for (const obj of metadata.objects) {
-    (obj as unknown as { name_?: string }).name_ = undefined;
-    for (const p of (obj.type as MetadataObjectType as MetadataObjectType)
-      .properties) {
-      clearMetadataNameCache(p.key, visited);
-      clearMetadataNameCache(p.value, visited);
-    }
-  }
-};
+  used.has(StringUtil.accessorsOf(name).join("."))
+    ? escapeComponentName(used, `_${name}`)
+    : name;
 
 interface ICollectVisited {
   aliases: WeakSet<MetadataAliasType>;
@@ -467,27 +546,6 @@ const createCollectVisited = (): ICollectVisited => ({
   tuples: new WeakSet<MetadataTupleType>(),
 });
 
-const uniqueComponents = <T extends { name: string }>(input: T[]): T[] => {
-  const dict: Record<string, T> = {};
-  for (const elem of input) {
-    const oldbie: T | undefined = dict[elem.name];
-    if (oldbie === undefined) dict[elem.name] = elem;
-    else if (
-      elem.name.includes(".") ||
-      componentScore(oldbie) < componentScore(elem)
-    )
-      dict[elem.name] = elem;
-  }
-  return Object.values(dict);
-};
-
-const componentScore = (input: unknown): number =>
-  JSON.stringify(input, (key, value) =>
-    // Resolved-reference back-edges close cycles on recursive schemas;
-    // skip them when scoring component "richness".
-    key === "type" ? undefined : value,
-  ).length;
-
 const enrollMetadata = (
   dictionary: IMetadataDictionary,
   metadata: MetadataSchema,
@@ -499,9 +557,11 @@ const enrollMetadata = (
   if (metadata.rest !== null)
     enrollMetadata(dictionary, metadata.rest, visited);
   if (metadata.escaped !== null) {
-    enrollMetadata(dictionary, metadata.escaped.original, visited);
     enrollMetadata(dictionary, metadata.escaped.returns, visited);
   }
+  for (const template of metadata.templates)
+    for (const elem of template.row ?? template)
+      enrollMetadata(dictionary, elem, visited);
   for (const func of metadata.functions) {
     for (const p of func.parameters)
       enrollMetadata(dictionary, p.type, visited);
@@ -551,17 +611,13 @@ const enroll = <
   dict: Map<string, T>,
   elem: T,
 ): boolean => {
+  // Collision refinement established equivalence for every remaining same-name
+  // entry in this kind; selecting another representative cannot add meaning.
   const oldbie: T | undefined = dict.get(elem.name);
   if (oldbie === elem) return false;
   if (oldbie === undefined) {
     dict.set(elem.name, elem);
     return true;
-  } else if (
-    elem.name.includes(".") ||
-    componentScore(oldbie) < componentScore(elem)
-  ) {
-    dict.set(elem.name, elem);
-    return true;
   }
   return false;
 };