@skmtc/core 0.0.795 → 0.0.797

package/script/oas/_helpers/parseFormat.js

@@ -35,6 +35,144 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseFormat = void 0;
 const v = __importStar(require("valibot"));
+/**
+ * Parses and validates OpenAPI schema format values with type safety.
+ *
+ * This function extracts and validates format specifiers from OpenAPI schema objects,
+ * ensuring they conform to expected format types for the given schema. Invalid format
+ * values are removed and logged as warnings through the parse context.
+ *
+ * The format property provides additional semantic information about the expected
+ * structure of string values (like 'email', 'date-time', 'uuid', etc.) and numeric
+ * precision (like 'float', 'double' for numbers, 'int32', 'int64' for integers).
+ *
+ * @template T - The expected type of the format value (usually string)
+ * @template Value - The OpenAPI schema object type
+ *
+ * @param args - Parsing configuration
+ * @returns Parsed format data with the validated format and cleaned schema
+ *
+ * @example String format parsing
+ * ```typescript
+ * import { parseFormat } from '@skmtc/core/oas/_helpers';
+ * import * as v from 'valibot';
+ *
+ * const result = parseFormat({
+ *   value: {
+ *     type: 'string',
+ *     format: 'email',
+ *     maxLength: 100
+ *   },
+ *   valibotSchema: v.string(),
+ *   context: parseContext
+ * });
+ *
+ * console.log(result.format); // 'email'
+ * console.log(result.value);  // { type: 'string', maxLength: 100 }
+ * ```
+ *
+ * @example Date-time format
+ * ```typescript
+ * const result = parseFormat({
+ *   value: {
+ *     type: 'string',
+ *     format: 'date-time',
+ *     description: 'ISO 8601 timestamp'
+ *   },
+ *   valibotSchema: v.string(),
+ *   context: parseContext
+ * });
+ *
+ * console.log(result.format); // 'date-time'
+ * // Can be used to generate Date objects in TypeScript
+ * ```
+ *
+ * @example Number precision formats
+ * ```typescript
+ * const result = parseFormat({
+ *   value: {
+ *     type: 'number',
+ *     format: 'float',
+ *     minimum: 0
+ *   },
+ *   valibotSchema: v.string(), // Format is always a string
+ *   context: parseContext
+ * });
+ *
+ * console.log(result.format); // 'float'
+ * // Indicates single-precision floating-point
+ * ```
+ *
+ * @example Integer format specifiers
+ * ```typescript
+ * const result = parseFormat({
+ *   value: {
+ *     type: 'integer',
+ *     format: 'int64',
+ *     description: 'Large integer ID'
+ *   },
+ *   valibotSchema: v.string(),
+ *   context: parseContext
+ * });
+ *
+ * console.log(result.format); // 'int64'
+ * // Indicates 64-bit signed integer
+ * ```
+ *
+ * @example Invalid format handling
+ * ```typescript
+ * const result = parseFormat({
+ *   value: {
+ *     type: 'string',
+ *     format: 123, // Invalid - should be string
+ *     pattern: '^[a-z]+$'
+ *   } as any,
+ *   valibotSchema: v.string(),
+ *   context: parseContext
+ * });
+ *
+ * console.log(result.format); // undefined (invalid format removed)
+ * console.log(result.value);  // { type: 'string', pattern: '^[a-z]+$' }
+ * // Context will log a warning about the invalid format
+ * ```
+ *
+ * @example Missing format (undefined)
+ * ```typescript
+ * const result = parseFormat({
+ *   value: {
+ *     type: 'string',
+ *     minLength: 1,
+ *     maxLength: 50
+ *   },
+ *   valibotSchema: v.string(),
+ *   context: parseContext
+ * });
+ *
+ * console.log(result.format); // undefined (no format specified)
+ * console.log(result.value);  // { type: 'string', minLength: 1, maxLength: 50 }
+ * ```
+ *
+ * @example Common string formats
+ * ```typescript
+ * // Standard OpenAPI string formats:
+ * // - 'date': full-date as defined by RFC3339
+ * // - 'date-time': date-time as defined by RFC3339
+ * // - 'time': time as defined by RFC3339
+ * // - 'email': email address as defined by RFC5322
+ * // - 'uri': URI as defined by RFC3986
+ * // - 'uuid': UUID as defined by RFC4122
+ * // - 'binary': binary data (base64 encoded)
+ * // - 'byte': base64 encoded characters
+ * // - 'password': hint for UI to obscure input
+ *
+ * const emailFormat = parseFormat({
+ *   value: { type: 'string', format: 'email' },
+ *   valibotSchema: v.string(),
+ *   context
+ * });
+ * // Can generate validation: v.pipe(v.string(), v.email())
+ * ```
+ */
 const parseFormat = ({ value, valibotSchema, context }) => {
     const { format, ...rest } = value;
     const parsedFormat = context.provisionalParse({

package/script/oas/_helpers/parseNullable.d.ts

@@ -1,12 +1,139 @@
 import type { OpenAPIV3 } from 'openapi-types';
 import type { ParseContext } from '../../context/ParseContext.js';
+/**
+ * Arguments for parsing the nullable property from OpenAPI schemas.
+ *
+ * @template Value - The OpenAPI schema object type
+ */
 export type ParseNullableArgs<Value extends OpenAPIV3.SchemaObject> = {
+    /** The OpenAPI schema object containing the nullable property */
     value: Value;
+    /** Parse context for error handling */
     context: ParseContext;
 };
+/**
+ * Return type for parsed nullable data.
+ *
+ * @template Value - The OpenAPI schema object type
+ */
 export type ParseNullableReturn<Value extends OpenAPIV3.SchemaObject> = {
+    /** The validated nullable flag (true, false, or undefined) */
     nullable: boolean | undefined;
+    /** The schema object without the nullable property */
     value: Omit<Value, 'nullable'>;
 };
+/**
+ * Parses and validates the nullable property from OpenAPI schema objects.
+ *
+ * This function extracts and validates the `nullable` property from OpenAPI
+ * schema objects, ensuring it's a valid boolean value. Invalid nullable values
+ * are removed and logged as warnings through the parse context.
+ *
+ * The nullable property determines whether a schema value can be null in addition
+ * to its primary type, which affects type generation and validation logic.
+ *
+ * @template Value - The OpenAPI schema object type
+ *
+ * @param args - Parsing configuration
+ * @returns Parsed nullable data with the validated flag and cleaned schema
+ *
+ * @example Valid nullable property
+ * ```typescript
+ * import { parseNullable } from '@skmtc/core/oas/_helpers';
+ *
+ * const result = parseNullable({
+ *   value: {
+ *     type: 'string',
+ *     nullable: true,
+ *     description: 'An optional string that can be null'
+ *   },
+ *   context: parseContext
+ * });
+ *
+ * console.log(result.nullable); // true
+ * console.log(result.value);    // { type: 'string', description: 'An optional string that can be null' }
+ * ```
+ *
+ * @example Explicitly non-nullable
+ * ```typescript
+ * const result = parseNullable({
+ *   value: {
+ *     type: 'number',
+ *     nullable: false,
+ *     minimum: 0
+ *   },
+ *   context: parseContext
+ * });
+ *
+ * console.log(result.nullable); // false
+ * console.log(result.value);    // { type: 'number', minimum: 0 }
+ * ```
+ *
+ * @example Missing nullable property (undefined)
+ * ```typescript
+ * const result = parseNullable({
+ *   value: {
+ *     type: 'string',
+ *     format: 'email'
+ *   },
+ *   context: parseContext
+ * });
+ *
+ * console.log(result.nullable); // undefined (property not present)
+ * console.log(result.value);    // { type: 'string', format: 'email' }
+ * ```
+ *
+ * @example Invalid nullable value
+ * ```typescript
+ * const result = parseNullable({
+ *   value: {
+ *     type: 'boolean',
+ *     nullable: 'yes', // Invalid - should be boolean
+ *     description: 'A flag'
+ *   } as any,
+ *   context: parseContext
+ * });
+ *
+ * console.log(result.nullable); // undefined (invalid value removed)
+ * console.log(result.value);    // { type: 'boolean', description: 'A flag' }
+ * // Context will log a warning about the invalid nullable value
+ * ```
+ *
+ * @example Usage in type generation
+ * ```typescript
+ * function generateTypeScript(schema: OpenAPIV3.SchemaObject) {
+ *   const { nullable, value } = parseNullable({ value: schema, context });
+ *
+ *   const baseType = generateBaseType(value);
+ *   const nullableType = nullable ? ` | null` : '';
+ *
+ *   return `${baseType}${nullableType}`;
+ * }
+ *
+ * // Examples:
+ * // nullable: true  -> 'string | null'
+ * // nullable: false -> 'string'
+ * // nullable: undefined -> 'string' (default behavior)
+ * ```
+ *
+ * @example Complex schema with nullable
+ * ```typescript
+ * const result = parseNullable({
+ *   value: {
+ *     type: 'object',
+ *     properties: {
+ *       name: { type: 'string' },
+ *       age: { type: 'number' }
+ *     },
+ *     required: ['name'],
+ *     nullable: true // The entire object can be null
+ *   },
+ *   context: parseContext
+ * });
+ *
+ * console.log(result.nullable); // true
+ * // Generated type might be: { name: string; age?: number } | null
+ * ```
+ */
 export declare const parseNullable: <Value extends OpenAPIV3.SchemaObject>({ value, context }: ParseNullableArgs<Value>) => ParseNullableReturn<Value>;
 //# sourceMappingURL=parseNullable.d.ts.map

package/script/oas/_helpers/parseNullable.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parseNullable.d.ts","sourceRoot":"","sources":["../../../src/oas/_helpers/parseNullable.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAC9C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAA;AAGjE,MAAM,MAAM,iBAAiB,CAAC,KAAK,SAAS,SAAS,CAAC,YAAY,IAAI;IACpE,KAAK,EAAE,KAAK,CAAA;IACZ,OAAO,EAAE,YAAY,CAAA;CACtB,CAAA;AAED,MAAM,MAAM,mBAAmB,CAAC,KAAK,SAAS,SAAS,CAAC,YAAY,IAAI;IACtE,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAA;IAC7B,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,UAAU,CAAC,CAAA;CAC/B,CAAA;AAED,eAAO,MAAM,aAAa,GAAI,KAAK,SAAS,SAAS,CAAC,YAAY,EAAE,oBAGjE,iBAAiB,CAAC,KAAK,CAAC,KAAG,mBAAmB,CAAC,KAAK,CAgBtD,CAAA"}
+{"version":3,"file":"parseNullable.d.ts","sourceRoot":"","sources":["../../../src/oas/_helpers/parseNullable.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAC9C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAA;AAGjE;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,CAAC,KAAK,SAAS,SAAS,CAAC,YAAY,IAAI;IACpE,iEAAiE;IACjE,KAAK,EAAE,KAAK,CAAA;IACZ,uCAAuC;IACvC,OAAO,EAAE,YAAY,CAAA;CACtB,CAAA;AAED;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,CAAC,KAAK,SAAS,SAAS,CAAC,YAAY,IAAI;IACtE,8DAA8D;IAC9D,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAA;IAC7B,sDAAsD;IACtD,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,UAAU,CAAC,CAAA;CAC/B,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgHG;AACH,eAAO,MAAM,aAAa,GAAI,KAAK,SAAS,SAAS,CAAC,YAAY,EAAE,oBAGjE,iBAAiB,CAAC,KAAK,CAAC,KAAG,mBAAmB,CAAC,KAAK,CAgBtD,CAAA"}

package/script/oas/_helpers/parseNullable.js

@@ -35,6 +35,119 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseNullable = void 0;
 const v = __importStar(require("valibot"));
+/**
+ * Parses and validates the nullable property from OpenAPI schema objects.
+ *
+ * This function extracts and validates the `nullable` property from OpenAPI
+ * schema objects, ensuring it's a valid boolean value. Invalid nullable values
+ * are removed and logged as warnings through the parse context.
+ *
+ * The nullable property determines whether a schema value can be null in addition
+ * to its primary type, which affects type generation and validation logic.
+ *
+ * @template Value - The OpenAPI schema object type
+ *
+ * @param args - Parsing configuration
+ * @returns Parsed nullable data with the validated flag and cleaned schema
+ *
+ * @example Valid nullable property
+ * ```typescript
+ * import { parseNullable } from '@skmtc/core/oas/_helpers';
+ *
+ * const result = parseNullable({
+ *   value: {
+ *     type: 'string',
+ *     nullable: true,
+ *     description: 'An optional string that can be null'
+ *   },
+ *   context: parseContext
+ * });
+ *
+ * console.log(result.nullable); // true
+ * console.log(result.value);    // { type: 'string', description: 'An optional string that can be null' }
+ * ```
+ *
+ * @example Explicitly non-nullable
+ * ```typescript
+ * const result = parseNullable({
+ *   value: {
+ *     type: 'number',
+ *     nullable: false,
+ *     minimum: 0
+ *   },
+ *   context: parseContext
+ * });
+ *
+ * console.log(result.nullable); // false
+ * console.log(result.value);    // { type: 'number', minimum: 0 }
+ * ```
+ *
+ * @example Missing nullable property (undefined)
+ * ```typescript
+ * const result = parseNullable({
+ *   value: {
+ *     type: 'string',
+ *     format: 'email'
+ *   },
+ *   context: parseContext
+ * });
+ *
+ * console.log(result.nullable); // undefined (property not present)
+ * console.log(result.value);    // { type: 'string', format: 'email' }
+ * ```
+ *
+ * @example Invalid nullable value
+ * ```typescript
+ * const result = parseNullable({
+ *   value: {
+ *     type: 'boolean',
+ *     nullable: 'yes', // Invalid - should be boolean
+ *     description: 'A flag'
+ *   } as any,
+ *   context: parseContext
+ * });
+ *
+ * console.log(result.nullable); // undefined (invalid value removed)
+ * console.log(result.value);    // { type: 'boolean', description: 'A flag' }
+ * // Context will log a warning about the invalid nullable value
+ * ```
+ *
+ * @example Usage in type generation
+ * ```typescript
+ * function generateTypeScript(schema: OpenAPIV3.SchemaObject) {
+ *   const { nullable, value } = parseNullable({ value: schema, context });
+ *
+ *   const baseType = generateBaseType(value);
+ *   const nullableType = nullable ? ` | null` : '';
+ *
+ *   return `${baseType}${nullableType}`;
+ * }
+ *
+ * // Examples:
+ * // nullable: true  -> 'string | null'
+ * // nullable: false -> 'string'
+ * // nullable: undefined -> 'string' (default behavior)
+ * ```
+ *
+ * @example Complex schema with nullable
+ * ```typescript
+ * const result = parseNullable({
+ *   value: {
+ *     type: 'object',
+ *     properties: {
+ *       name: { type: 'string' },
+ *       age: { type: 'number' }
+ *     },
+ *     required: ['name'],
+ *     nullable: true // The entire object can be null
+ *   },
+ *   context: parseContext
+ * });
+ *
+ * console.log(result.nullable); // true
+ * // Generated type might be: { name: string; age?: number } | null
+ * ```
+ */
 const parseNullable = ({ value, context }) => {
     const { nullable, ...rest } = value;
     const parsedNullable = context.provisionalParse({

package/script/run/toV3JsonDocument.d.ts

@@ -1,7 +1,97 @@
 import "../_dnt.polyfills.js";
 import type { OpenAPIV2, OpenAPIV3, OpenAPIV3_1 } from 'openapi-types';
+/**
+ * Union type representing any supported OpenAPI document version.
+ *
+ * SKMTC supports processing OpenAPI/Swagger documents from version 2.0 through 3.1,
+ * automatically converting them to OpenAPI 3.0 format for internal processing.
+ */
 type AnyOasDocument = OpenAPIV2.Document | OpenAPIV3.Document | OpenAPIV3_1.Document;
+/**
+ * Parses a string into an OpenAPI document object.
+ *
+ * Automatically detects whether the input string is JSON or YAML format based on
+ * the content, then parses it into an OpenAPI document object. Supports all
+ * OpenAPI versions (2.0, 3.0.x, 3.1.x).
+ *
+ * @param schema - The OpenAPI document as a JSON or YAML string
+ * @returns Parsed OpenAPI document object
+ *
+ * @example Parsing JSON OpenAPI document
+ * ```typescript
+ * const jsonSchema = `{
+ *   "openapi": "3.0.0",
+ *   "info": { "title": "My API", "version": "1.0.0" },
+ *   "paths": {}
+ * }`;
+ * const document = stringToSchema(jsonSchema);
+ * console.log(document.info.title); // "My API"
+ * ```
+ *
+ * @example Parsing YAML OpenAPI document
+ * ```typescript
+ * const yamlSchema = `
+ * openapi: 3.0.0
+ * info:
+ *   title: My API
+ *   version: 1.0.0
+ * paths: {}
+ * `;
+ * const document = stringToSchema(yamlSchema);
+ * console.log(document.info.title); // "My API"
+ * ```
+ *
+ * @throws {SyntaxError} If the JSON is malformed
+ * @throws {Error} If the YAML is malformed
+ */
 export declare const stringToSchema: (schema: string) => AnyOasDocument;
+/**
+ * Converts any OpenAPI document version to OpenAPI 3.0 format.
+ *
+ * SKMTC processes all documents using OpenAPI 3.0 as the internal format.
+ * This function handles version detection and conversion from:
+ * - OpenAPI 3.0.x (returned as-is)
+ * - OpenAPI 3.1.x (downgraded to 3.0 with allOf transformations)
+ * - Swagger 2.0 (upgraded to OpenAPI 3.0)
+ *
+ * @param schema - The OpenAPI document to convert
+ * @returns Promise resolving to an OpenAPI 3.0 document
+ *
+ * @example Converting OpenAPI 3.1 to 3.0
+ * ```typescript
+ * const openapi31Doc = {
+ *   openapi: "3.1.0",
+ *   info: { title: "My API", version: "1.0.0" },
+ *   paths: {}
+ * };
+ * const v3Doc = await toV3Document(openapi31Doc);
+ * console.log(v3Doc.openapi); // "3.0.3" (converted)
+ * ```
+ *
+ * @example Converting Swagger 2.0 to OpenAPI 3.0
+ * ```typescript
+ * const swagger2Doc = {
+ *   swagger: "2.0",
+ *   info: { title: "My API", version: "1.0.0" },
+ *   paths: {}
+ * };
+ * const v3Doc = await toV3Document(swagger2Doc);
+ * console.log(v3Doc.openapi); // "3.0.0" (converted)
+ * ```
+ *
+ * @example OpenAPI 3.0 passthrough
+ * ```typescript
+ * const openapi30Doc = {
+ *   openapi: "3.0.2",
+ *   info: { title: "My API", version: "1.0.0" },
+ *   paths: {}
+ * };
+ * const v3Doc = await toV3Document(openapi30Doc);
+ * console.log(v3Doc === openapi30Doc); // true (same object)
+ * ```
+ *
+ * @throws {Error} If the document version is not recognized or supported
+ */
 export declare const toV3Document: (schema: AnyOasDocument) => Promise<OpenAPIV3.Document>;
 export {};
 //# sourceMappingURL=toV3JsonDocument.d.ts.map

package/script/run/toV3JsonDocument.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"toV3JsonDocument.d.ts","sourceRoot":"","sources":["../../src/run/toV3JsonDocument.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAUtE,KAAK,cAAc,GAAG,SAAS,CAAC,QAAQ,GAAG,SAAS,CAAC,QAAQ,GAAG,WAAW,CAAC,QAAQ,CAAA;AAEpF,eAAO,MAAM,cAAc,GAAI,QAAQ,MAAM,KAAG,cAM/C,CAAA;AAED,eAAO,MAAM,YAAY,GAAU,QAAQ,cAAc,KAAG,OAAO,CAAC,SAAS,CAAC,QAAQ,CA0BrF,CAAA"}
+{"version":3,"file":"toV3JsonDocument.d.ts","sourceRoot":"","sources":["../../src/run/toV3JsonDocument.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAUtE;;;;;GAKG;AACH,KAAK,cAAc,GAAG,SAAS,CAAC,QAAQ,GAAG,SAAS,CAAC,QAAQ,GAAG,WAAW,CAAC,QAAQ,CAAA;AAEpF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,eAAO,MAAM,cAAc,GAAI,QAAQ,MAAM,KAAG,cAM/C,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,eAAO,MAAM,YAAY,GAAU,QAAQ,cAAc,KAAG,OAAO,CAAC,SAAS,CAAC,QAAQ,CA0BrF,CAAA"}

package/script/run/toV3JsonDocument.js

@@ -9,6 +9,43 @@ const parse_js_1 = require("../deps/jsr.io/@std/yaml/1.0.9/parse.js");
 const openapi_down_convert_1 = require("@apiture/openapi-down-convert");
 const ts_pattern_1 = require("ts-pattern");
 const swagger2openapi_1 = __importDefault(require("swagger2openapi"));
+/**
+ * Parses a string into an OpenAPI document object.
+ *
+ * Automatically detects whether the input string is JSON or YAML format based on
+ * the content, then parses it into an OpenAPI document object. Supports all
+ * OpenAPI versions (2.0, 3.0.x, 3.1.x).
+ *
+ * @param schema - The OpenAPI document as a JSON or YAML string
+ * @returns Parsed OpenAPI document object
+ *
+ * @example Parsing JSON OpenAPI document
+ * ```typescript
+ * const jsonSchema = `{
+ *   "openapi": "3.0.0",
+ *   "info": { "title": "My API", "version": "1.0.0" },
+ *   "paths": {}
+ * }`;
+ * const document = stringToSchema(jsonSchema);
+ * console.log(document.info.title); // "My API"
+ * ```
+ *
+ * @example Parsing YAML OpenAPI document
+ * ```typescript
+ * const yamlSchema = `
+ * openapi: 3.0.0
+ * info:
+ *   title: My API
+ *   version: 1.0.0
+ * paths: {}
+ * `;
+ * const document = stringToSchema(yamlSchema);
+ * console.log(document.info.title); // "My API"
+ * ```
+ *
+ * @throws {SyntaxError} If the JSON is malformed
+ * @throws {Error} If the YAML is malformed
+ */
 const stringToSchema = (schema) => {
     if (schema.trimStart().startsWith('{')) {
         return JSON.parse(schema);
@@ -18,6 +55,53 @@ const stringToSchema = (schema) => {
     }
 };
 exports.stringToSchema = stringToSchema;
+/**
+ * Converts any OpenAPI document version to OpenAPI 3.0 format.
+ *
+ * SKMTC processes all documents using OpenAPI 3.0 as the internal format.
+ * This function handles version detection and conversion from:
+ * - OpenAPI 3.0.x (returned as-is)
+ * - OpenAPI 3.1.x (downgraded to 3.0 with allOf transformations)
+ * - Swagger 2.0 (upgraded to OpenAPI 3.0)
+ *
+ * @param schema - The OpenAPI document to convert
+ * @returns Promise resolving to an OpenAPI 3.0 document
+ *
+ * @example Converting OpenAPI 3.1 to 3.0
+ * ```typescript
+ * const openapi31Doc = {
+ *   openapi: "3.1.0",
+ *   info: { title: "My API", version: "1.0.0" },
+ *   paths: {}
+ * };
+ * const v3Doc = await toV3Document(openapi31Doc);
+ * console.log(v3Doc.openapi); // "3.0.3" (converted)
+ * ```
+ *
+ * @example Converting Swagger 2.0 to OpenAPI 3.0
+ * ```typescript
+ * const swagger2Doc = {
+ *   swagger: "2.0",
+ *   info: { title: "My API", version: "1.0.0" },
+ *   paths: {}
+ * };
+ * const v3Doc = await toV3Document(swagger2Doc);
+ * console.log(v3Doc.openapi); // "3.0.0" (converted)
+ * ```
+ *
+ * @example OpenAPI 3.0 passthrough
+ * ```typescript
+ * const openapi30Doc = {
+ *   openapi: "3.0.2",
+ *   info: { title: "My API", version: "1.0.0" },
+ *   paths: {}
+ * };
+ * const v3Doc = await toV3Document(openapi30Doc);
+ * console.log(v3Doc === openapi30Doc); // true (same object)
+ * ```
+ *
+ * @throws {Error} If the document version is not recognized or supported
+ */
 const toV3Document = async (schema) => {
     return await (0, ts_pattern_1.match)(schema)
         .with({ openapi: ts_pattern_1.P.string.startsWith('3.0') }, doc => doc)