@conduit-client/model 3.10.0 → 3.12.0

package/dist/types/v1/parser/__tests__/test-utils.d.ts

@@ -10,6 +10,7 @@ import { SourcePositionMap } from '../swagger/source-position-map';
 import { SwaggerAPI } from '../swagger/SwaggerAPI';
 import { AmfEndPoint } from '../amf/endpoints/amf-endpoint';
 import { API, Server } from '../../api';
+import type SwaggerParser from '@apidevtools/swagger-parser';
 export type ParserKind = 'amf' | 'swagger';
 type ClassOfConstructor<T> = T extends new () => infer R ? R : never;
 /**
@@ -37,6 +38,7 @@ type TestSwaggerOAS<T extends Record<string, new () => amf.AnyShape>, E extends
     document: OpenAPIV3.Document;
     sourceUrl: URL;
     positionMap: SourcePositionMap;
+    $refs: SwaggerParser.$Refs;
 } & {
     [P in keyof T]: OpenAPIV3.SchemaObject;
 } & {

package/dist/types/v1/parser/swagger/SwaggerAPI.d.ts

@@ -6,6 +6,7 @@ import type { API, EndPoint, Server } from '../../api';
 import type { ReadOnlyTypeRegistry, TypeRegistry } from '../../types';
 import type { OpenAPIV3 } from 'openapi-types';
 import type { NamedFeatureFlagsService } from '@conduit-client/service-feature-flags/v1';
+import type SwaggerParser from '@apidevtools/swagger-parser';
 export declare const V1_VERSION = "1.0.0";
 export declare const ANONYMOUS_TYPE_NAME = "<anonymous>";
 export declare class SwaggerAPI implements API {
@@ -14,6 +15,7 @@ export declare class SwaggerAPI implements API {
     private services;
     private fileParserLogger;
     private positionMap;
+    private $refs;
     typeRegistry?: TypeRegistry<SwaggerType>;
     _endpoints?: EndPoint[];
     _servers?: Server[];
@@ -25,13 +27,27 @@ export declare class SwaggerAPI implements API {
     private parsedNamespace?;
     private defaultedNamespace;
     serviceOverrides?: ResolvedServiceOverrides;
-    constructor(document: OpenAPIV3.Document, sourceUrl: URL, services: NamedLoggerService & NamedFeatureFlagsService, fileParserLogger: FileParserLogger, positionMap: SourcePositionMap);
+    constructor(document: OpenAPIV3.Document, sourceUrl: URL, services: NamedLoggerService & NamedFeatureFlagsService, fileParserLogger: FileParserLogger, positionMap: SourcePositionMap, $refs: SwaggerParser.$Refs);
     /**
      * Get the source position for a given JSON path in the OpenAPI document.
      * @param jsonPath - The JSON path (e.g., "paths//users/get" or "components/schemas/User")
      * @returns The position if found, undefined otherwise
      */
     getPosition(jsonPath: string): Position | undefined;
+    /**
+     * Find the position of a $ref declaration by its target value.
+     * @param refValue - The $ref target string (e.g., "./schemas/User.yaml#/TypeThatDoesNotExist")
+     * @returns The position where the $ref is declared, if found
+     */
+    getRefPosition(refValue: string): Position | undefined;
+    /**
+     * Resolve a $ref target path with respect to the directory of the source.
+     * This is particularly necessary for relative paths since this.$refs.get() resolves
+     * paths relative to the root file and not the ref source file.
+     * @param refPath - The $ref target path (e.g., "./schemas/User.yaml#/User")
+     * @returns The path from where the $ref is declared (e.g, "file:///path/to/source/./schemas/User.yaml#/User")
+     */
+    resolveRefTargetPath(refTarget: string): any;
     private build;
     private buildEndpoints;
     private buildServers;

package/dist/types/v1/parser/swagger/parser.d.ts

@@ -1,3 +1,4 @@
+import SwaggerParser from '@apidevtools/swagger-parser';
 import { SwaggerAPI } from './SwaggerAPI';
 import { SourcePositionMap } from './source-position-map';
 import type { OpenAPIV3 } from 'openapi-types';
@@ -6,6 +7,7 @@ import type { NamedFeatureFlagsService } from '@conduit-client/service-feature-f
 export interface ParsedSwaggerDocument {
     document: OpenAPIV3.Document;
     positionMap: SourcePositionMap;
+    $refs: SwaggerParser.$Refs;
 }
 /**
  * Parse and validate an OpenAPI document using swagger-parser

package/dist/types/v1/parser/swagger/source-position-map.d.ts

@@ -20,6 +20,11 @@ export declare class SourcePositionMap {
      * @param jsonPath - The JSON path (e.g., "paths//users/get" or "components/schemas/User")
      */
     get(jsonPath: string): Position | undefined;
+    /**
+     * Get the position for a given $ref path
+     * @param refPath - The $ref path (e.g., "./schemas/User.yaml#/User")
+     */
+    getRef(refPath: string): Position | undefined;
     /**
      * Set the position for a given JSON path
      */

package/dist/types/v1/parser/swagger/swagger-utils.d.ts

@@ -6,7 +6,8 @@ export type OpenAPISchema = OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject;
  * Works with any OpenAPI object type that could be a reference
  */
 export declare function isReferenceObject<T>(obj: T | OpenAPIV3.ReferenceObject): obj is OpenAPIV3.ReferenceObject;
-export declare function isSchemaObject(schema: OpenAPISchema): schema is OpenAPIV3.SchemaObject;
+export declare function isSchemaObject(obj: unknown): obj is OpenAPIV3.SchemaObject;
+export declare function isOpenAPISchema(obj: unknown): obj is OpenAPISchema;
 export declare function isArraySchema(schema: OpenAPIV3.SchemaObject): boolean;
 export declare function isObjectSchema(schema: OpenAPIV3.SchemaObject): boolean;
 export declare function isScalarSchema(schema: OpenAPIV3.SchemaObject): boolean;
@@ -23,7 +24,10 @@ export declare function hasDiscriminator(schema: OpenAPIV3.SchemaObject): boolea
 export declare function mapScalarType(schema: OpenAPIV3.SchemaObject): ScalarType['type'];
 /**
  * Extracts the type name from a $ref string
- * e.g., "#/components/schemas/User" -> "User"
+ * Handles both internal refs and external file refs:
+ * - "#/components/schemas/User" -> "User"
+ * - "./schemas/User.yaml#/User" -> "User"
+ * - "../../path/to/File.yaml#TypeName" -> "TypeName"
  */
 export declare function getRefTypeName(ref: string): string;
 /**
@@ -35,3 +39,13 @@ export declare function coerceValueByType(value: unknown, type: ScalarType['type
  * Throws an error if non-scalar values (objects/arrays) are found.
  */
 export declare function getEnumValues(schema: OpenAPIV3.SchemaObject, schemaName?: string): Array<string | number | boolean | null>;
+export declare function isReferencePath(obj: OpenAPIV3.PathItemObject): obj is OpenAPIV3.PathItemObject & {
+    $ref: string;
+};
+/**
+ * Extracts root-level schemas from a file.
+ * External schema files may define schemas at the root level (not under components/schemas).
+ * This function identifies such schemas by excluding known OpenAPI document properties
+ * and checking for schema-specific properties.
+ */
+export declare function extractRootLevelSchemas(file: OpenAPIV3.Document): Record<string, OpenAPISchema>;

package/dist/v1/index.js

@@ -13523,6 +13523,12 @@ class SwaggerNilTypeImpl extends SwaggerBaseType {
 function isReferenceObject(obj) {
   return obj !== null && typeof obj === "object" && "$ref" in obj;
 }
+function isSchemaObject(obj) {
+  return obj !== null && typeof obj === "object" && !("$ref" in obj) && ("type" in obj || "properties" in obj || "allOf" in obj || "anyOf" in obj || "oneOf" in obj || "items" in obj);
+}
+function isOpenAPISchema(obj) {
+  return isSchemaObject(obj) || isReferenceObject(obj);
+}
 function isArraySchema(schema2) {
   return schema2.type === "array";
 }
@@ -13597,6 +13603,14 @@ function mapScalarType(schema2) {
   }
 }
 function getRefTypeName(ref) {
+  const hashIndex = ref.lastIndexOf("#");
+  if (hashIndex !== -1) {
+    const fragment = ref.substring(hashIndex + 1);
+    const parts2 = fragment.split("/").filter((p) => p !== "");
+    if (parts2.length > 0) {
+      return parts2[parts2.length - 1];
+    }
+  }
   const parts = ref.split("/");
   return parts[parts.length - 1];
 }
@@ -13614,6 +13628,28 @@ function getEnumValues(schema2, schemaName) {
     );
   });
 }
+const OPENAPI_DOCUMENT_PROPERTIES = /* @__PURE__ */ new Set([
+  "openapi",
+  "info",
+  "servers",
+  "paths",
+  "components",
+  "security",
+  "tags",
+  "externalDocs",
+  "webhooks",
+  "jsonSchemaDialect"
+]);
+function extractRootLevelSchemas(file) {
+  const schemas2 = {};
+  for (const [key, value] of Object.entries(file)) {
+    if (OPENAPI_DOCUMENT_PROPERTIES.has(key) || key.startsWith("x-")) continue;
+    if (isOpenAPISchema(value)) {
+      schemas2[key] = value;
+    }
+  }
+  return schemas2;
+}
 class SwaggerEnumerableScalarType extends SwaggerBaseType {
   typeResolve() {
     if (this.schema.enum && this.schema.enum.length > 0) {
@@ -13901,6 +13937,12 @@ class SwaggerRefTypeImpl extends SwaggerBaseType {
     };
     this.resolved = false;
     this.refString = this.schema.$ref || "";
+    if (this.schemaPosition.line === 0 && this.schemaPosition.column === 0 && this.refString && this.api) {
+      const refPosition = this.api.getRefPosition(this.refString);
+      if (refPosition) {
+        this.schemaPosition = refPosition;
+      }
+    }
   }
   typeResolve() {
     if (this.refString) {
@@ -13912,7 +13954,7 @@ class SwaggerRefTypeImpl extends SwaggerBaseType {
         inheritedType.resolve();
         this.$ref = inheritedType;
       } else {
-        const errorMessage = `Failed to resolve $ref: ${typeName}`;
+        const errorMessage = `Failed to resolve $ref: ${this.refString}`;
         this.fileParserLogger.error(this.schemaPosition, errorMessage);
         throw new Error(errorMessage);
       }
@@ -14204,10 +14246,14 @@ ${message}`);
       headers: {}
     };
     const parameters = this.operation.parameters || [];
-    for (const param of parameters) {
-      if (isReferenceObject(param)) continue;
+    for (let param of parameters) {
+      if (isReferenceObject(param)) {
+        param = this.endpoint.api.resolveRefTargetPath(
+          param.$ref
+        );
+      }
       const paramType = this.swaggerTypeFactory(
-        {},
+        this.endpoint.api,
         param.schema || { type: "string" },
         void 0,
         this.typeRegistry,
@@ -14236,12 +14282,17 @@ ${message}`);
       }
     }
     if (this.operation.requestBody) {
-      const requestBody = isReferenceObject(this.operation.requestBody) ? void 0 : this.operation.requestBody;
+      let requestBody = this.operation.requestBody;
+      if (isReferenceObject(requestBody)) {
+        requestBody = this.endpoint.api.resolveRefTargetPath(
+          requestBody.$ref
+        );
+      }
       if (requestBody == null ? void 0 : requestBody.content) {
         for (const [mediaType, content] of Object.entries(requestBody.content)) {
           if (content.schema) {
             const dataType = this.swaggerTypeFactory(
-              {},
+              this.endpoint.api,
               content.schema,
               void 0,
               this.typeRegistry,
@@ -14263,18 +14314,28 @@ ${message}`);
   buildResponses() {
     const responses = [];
     const opResponses = this.operation.responses || {};
-    for (const [statusCode, responseObj] of Object.entries(opResponses)) {
-      if (isReferenceObject(responseObj)) continue;
+    for (const [statusCode, opResponse] of Object.entries(opResponses)) {
+      let responseObj = opResponse;
+      if (isReferenceObject(responseObj)) {
+        responseObj = this.endpoint.api.resolveRefTargetPath(
+          responseObj.$ref
+        );
+      }
       const response = {
         statusCode,
         payloads: [],
         headers: {}
       };
       if (responseObj.headers) {
-        for (const [headerName, headerObj] of Object.entries(responseObj.headers)) {
-          if (isReferenceObject(headerObj)) continue;
+        for (const [headerName, headerValue] of Object.entries(responseObj.headers)) {
+          let headerObj = headerValue;
+          if (isReferenceObject(headerObj)) {
+            headerObj = this.endpoint.api.resolveRefTargetPath(
+              headerObj.$ref
+            );
+          }
           const headerType = this.swaggerTypeFactory(
-            {},
+            this.endpoint.api,
             headerObj.schema || { type: "string" },
             void 0,
             this.typeRegistry,
@@ -14292,7 +14353,7 @@ ${message}`);
         for (const [mediaType, content] of Object.entries(responseObj.content)) {
           if (content.schema) {
             const dataType = this.swaggerTypeFactory(
-              {},
+              this.endpoint.api,
               content.schema,
               void 0,
               this.typeRegistry,
@@ -14623,8 +14684,10 @@ class SwaggerBaseEndpoint {
     this.path = pathStr;
     this.uriParameters = {};
     const parameters = pathItem.parameters || [];
-    for (const param of parameters) {
-      if (isReferenceObject(param)) continue;
+    for (let param of parameters) {
+      if (isReferenceObject(param)) {
+        param = api.resolveRefTargetPath(param.$ref);
+      }
       if (param.in !== "path") continue;
       const paramType = swaggerTypeFactory2(
         api,
@@ -14761,12 +14824,13 @@ const oneStoreExtensionsSchema = z.object({
   }).strict()
 });
 class SwaggerAPI {
-  constructor(document, sourceUrl, services, fileParserLogger, positionMap) {
+  constructor(document, sourceUrl, services, fileParserLogger, positionMap, $refs) {
     this.document = document;
     this.sourceUrl = sourceUrl;
     this.services = services;
     this.fileParserLogger = fileParserLogger;
     this.positionMap = positionMap;
+    this.$refs = $refs;
     this.built = false;
     const urlPath = sourceUrl.pathname;
     this.defaultedNamespace = path.parse(urlPath).name;
@@ -14782,6 +14846,41 @@ class SwaggerAPI {
   getPosition(jsonPath) {
     return this.positionMap.get(jsonPath);
   }
+  /**
+   * Find the position of a $ref declaration by its target value.
+   * @param refValue - The $ref target string (e.g., "./schemas/User.yaml#/TypeThatDoesNotExist")
+   * @returns The position where the $ref is declared, if found
+   */
+  getRefPosition(refValue) {
+    const result = this.positionMap.findRefPosition(refValue);
+    return result == null ? void 0 : result.position;
+  }
+  /**
+   * Resolve a $ref target path with respect to the directory of the source.
+   * This is particularly necessary for relative paths since this.$refs.get() resolves
+   * paths relative to the root file and not the ref source file.
+   * @param refPath - The $ref target path (e.g., "./schemas/User.yaml#/User")
+   * @returns The path from where the $ref is declared (e.g, "file:///path/to/source/./schemas/User.yaml#/User")
+   */
+  resolveRefTargetPath(refTarget) {
+    var _a;
+    const hashIndex = refTarget.indexOf("#");
+    const refTargetFilePath = hashIndex === -1 ? refTarget : refTarget.substring(0, hashIndex);
+    let resolvedPath;
+    if (!refTargetFilePath) {
+      resolvedPath = refTarget;
+    } else if (/^(https?|file):\/\//.test(refTargetFilePath)) {
+      resolvedPath = refTargetFilePath;
+    } else {
+      const refSourceFilePath = (_a = this.positionMap.getRef(refTarget)) == null ? void 0 : _a.filePath;
+      if (!refSourceFilePath) {
+        throw new Error(`Failed to resolve $ref: ${refTarget}`);
+      }
+      const refSourceBasePath = path.dirname(refSourceFilePath);
+      resolvedPath = path.join(refSourceBasePath, refTarget);
+    }
+    return this.$refs.get(resolvedPath);
+  }
   build() {
     if (!this.built) {
       this.built = true;
@@ -14792,9 +14891,14 @@ class SwaggerAPI {
     }
   }
   buildEndpoints() {
-    const paths = this.document.paths || {};
-    this._endpoints = Object.entries(paths).map(([pathStr, pathItem]) => {
+    var _a;
+    const paths = ((_a = this.$refs.values()[this.sourceUrl.toString()]) == null ? void 0 : _a.paths) || {};
+    this._endpoints = Object.entries(paths).map(([pathStr, pathValue]) => {
+      let pathItem = pathValue;
       if (!pathItem) return void 0;
+      if (isReferenceObject(pathItem)) {
+        pathItem = this.resolveRefTargetPath(pathItem.$ref);
+      }
       return swaggerEndpointFactory(
         pathStr,
         pathItem,
@@ -14839,10 +14943,17 @@ servers:
     });
   }
   buildTypes() {
-    var _a;
     this.services.logger.debug("SwaggerAPI - Building the type registry");
     const typeRegistry = this.typeRegistry = new BaseTypeRegistry();
-    const schemas2 = ((_a = this.document.components) == null ? void 0 : _a.schemas) || {};
+    const schemas2 = Object.values(this.$refs.values()).reduce(
+      (acc, file) => {
+        var _a;
+        const componentSchemas = ((_a = file.components) == null ? void 0 : _a.schemas) ?? {};
+        const rootSchemas = extractRootLevelSchemas(file);
+        return { ...acc, ...componentSchemas, ...rootSchemas };
+      },
+      {}
+    );
     for (const [name, schema2] of Object.entries(schemas2)) {
       this.services.logger.debug(`SwaggerAPI - Building Swagger Type for ${name}`);
       const swaggerType = swaggerTypeFactory(
@@ -14942,6 +15053,13 @@ class SourcePositionMap {
   get(jsonPath) {
     return this.positions.get(jsonPath);
   }
+  /**
+   * Get the position for a given $ref path
+   * @param refPath - The $ref path (e.g., "./schemas/User.yaml#/User")
+   */
+  getRef(refPath) {
+    return this.refTargets.get(refPath);
+  }
   /**
    * Set the position for a given JSON path
    */
@@ -15105,7 +15223,9 @@ function findRefPositionInCache(targetPath, token) {
 async function parseSwaggerDocument(source, logger) {
   const sourceUrl = source.toString();
   try {
-    const api = await SwaggerParser.bundle(sourceUrl, PARSER_OPTIONS);
+    const parser = new SwaggerParser();
+    const api = await parser.parse(sourceUrl, PARSER_OPTIONS);
+    const $refs = await parser.resolve(sourceUrl, PARSER_OPTIONS);
     const positionMap = new SourcePositionMap();
     for (const [fileUrl, filePositionMap] of positionMapCache) {
       positionMap.merge(filePositionMap, fileUrl);
@@ -15118,7 +15238,8 @@ async function parseSwaggerDocument(source, logger) {
     }
     return {
       document: api,
-      positionMap
+      positionMap,
+      $refs
     };
   } catch (error) {
     if (error instanceof MissingPointerError) {
@@ -15170,8 +15291,8 @@ async function parseSwaggerDocument(source, logger) {
   }
 }
 async function parseUrl(source, services, fileParserLogger) {
-  const { document, positionMap } = await parseSwaggerDocument(source, fileParserLogger);
-  const api = new SwaggerAPI(document, source, services, fileParserLogger, positionMap);
+  const { document, positionMap, $refs } = await parseSwaggerDocument(source, fileParserLogger);
+  const api = new SwaggerAPI(document, source, services, fileParserLogger, positionMap, $refs);
   api.validate();
   return api;
 }