@skmtc/core 0.0.796 → 0.0.797

package/esm/app/validate.d.ts

@@ -1,3 +1,35 @@
+/**
+ * Validates a project name against SKMTC naming conventions.
+ *
+ * Ensures project names follow standard naming patterns suitable for package
+ * managers and file systems. Names must be lowercase, contain only letters,
+ * numbers, and hyphens, with specific length and format requirements.
+ *
+ * @param name - The project name to validate
+ * @returns An error message string if validation fails, undefined if valid
+ *
+ * @example Valid project names
+ * ```typescript
+ * checkProjectName('my-api-client'); // undefined (valid)
+ * checkProjectName('user-service');  // undefined (valid)
+ * checkProjectName('api2');          // undefined (valid)
+ * ```
+ *
+ * @example Invalid project names
+ * ```typescript
+ * checkProjectName('A');             // 'Name must be at least 2 characters long'
+ * checkProjectName('My-API-Client'); // 'Name must only contain lowercase letters, numbers and hyphens'
+ * checkProjectName('-api-client');   // 'Name cannot start with a hyphen'
+ * checkProjectName('api-client-');   // 'Name cannot end with a hyphen'
+ * ```
+ *
+ * @example Validation rules
+ * - Minimum length: 2 characters
+ * - Maximum length: 20 characters
+ * - Allowed characters: a-z, 0-9, hyphens (-)
+ * - Cannot start or end with hyphen
+ * - Must be lowercase only
+ */
 import "../_dnt.polyfills.js";
 export declare const checkProjectName: (name: string) => string | undefined;
 //# sourceMappingURL=validate.d.ts.map

package/esm/app/validate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/app/validate.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAC9B,eAAO,MAAM,gBAAgB,GAAI,MAAM,MAAM,KAAG,MAAM,GAAG,SAoBxD,CAAA"}
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/app/validate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,OAAO,sBAAsB,CAAC;AAE9B,eAAO,MAAM,gBAAgB,GAAI,MAAM,MAAM,KAAG,MAAM,GAAG,SAoBxD,CAAA"}

package/esm/app/validate.js

@@ -1,3 +1,35 @@
+/**
+ * Validates a project name against SKMTC naming conventions.
+ *
+ * Ensures project names follow standard naming patterns suitable for package
+ * managers and file systems. Names must be lowercase, contain only letters,
+ * numbers, and hyphens, with specific length and format requirements.
+ *
+ * @param name - The project name to validate
+ * @returns An error message string if validation fails, undefined if valid
+ *
+ * @example Valid project names
+ * ```typescript
+ * checkProjectName('my-api-client'); // undefined (valid)
+ * checkProjectName('user-service');  // undefined (valid)
+ * checkProjectName('api2');          // undefined (valid)
+ * ```
+ *
+ * @example Invalid project names
+ * ```typescript
+ * checkProjectName('A');             // 'Name must be at least 2 characters long'
+ * checkProjectName('My-API-Client'); // 'Name must only contain lowercase letters, numbers and hyphens'
+ * checkProjectName('-api-client');   // 'Name cannot start with a hyphen'
+ * checkProjectName('api-client-');   // 'Name cannot end with a hyphen'
+ * ```
+ *
+ * @example Validation rules
+ * - Minimum length: 2 characters
+ * - Maximum length: 20 characters
+ * - Allowed characters: a-z, 0-9, hyphens (-)
+ * - Cannot start or end with hyphen
+ * - Must be lowercase only
+ */
 import "../_dnt.polyfills.js";
 export const checkProjectName = (name) => {
     if (name.length < 2) {

package/esm/context/CoreContext.d.ts

@@ -9,29 +9,70 @@ import * as log from '../deps/jsr.io/@std/log/0.224.14/mod.js';
 import type { GeneratorsMapContainer } from '../types/GeneratorType.js';
 import type { OpenAPIV3 } from 'openapi-types';
 import type { RenderResult } from './types.js';
+/**
+ * Represents the parse phase of the SKMTC pipeline.
+ *
+ * The parse phase converts OpenAPI v3 JSON documents into internal OAS objects,
+ * handling schema validation, reference resolution, and data transformation.
+ */
 export type ParsePhase = {
+    /** Identifies this as the parse phase */
     type: 'parse';
+    /** The parse context containing parsed document and utilities */
     context: ParseContext;
 };
+/**
+ * Represents the generate phase of the SKMTC pipeline.
+ *
+ * The generate phase transforms parsed OAS objects into generator-specific artifacts,
+ * applying templates, handling references, and preparing output files.
+ */
 export type GeneratePhase = {
+    /** Identifies this as the generate phase */
     type: 'generate';
+    /** The generate context for artifact creation and processing */
     context: GenerateContext;
 };
+/**
+ * Represents the render phase of the SKMTC pipeline.
+ *
+ * The render phase takes generator artifacts and renders them to formatted files,
+ * applying code formatting, file system operations, and final output generation.
+ */
 export type RenderPhase = {
+    /** Identifies this as the render phase */
     type: 'render';
+    /** The render context for file output and formatting */
     context: RenderContext;
 };
+/**
+ * Union type representing any phase of the SKMTC pipeline execution.
+ *
+ * Each execution phase contains its type identifier and associated context,
+ * allowing for type-safe phase handling and context access throughout the pipeline.
+ */
 export type ExecutionPhase = ParsePhase | GeneratePhase | RenderPhase;
 type CoreContextArgs = {
     spanId: string;
     logsPath?: string;
     silent: boolean;
 };
-type ToArtifactsArgs = {
+/**
+ * Arguments for the `toArtifacts` method of CoreContext.
+ *
+ * Contains all the necessary configuration for transforming an OpenAPI document
+ * into code artifacts through the SKMTC pipeline.
+ */
+export type ToArtifactsArgs = {
+    /** The OpenAPI v3 document to process */
     documentObject: OpenAPIV3.Document;
+    /** Client settings for customization (optional) */
     settings: ClientSettings | undefined;
+    /** Function that returns the generator configuration map */
     toGeneratorConfigMap: <EnrichmentType = undefined>() => GeneratorsMapContainer<EnrichmentType>;
+    /** Prettier configuration for code formatting (optional) */
     prettier?: PrettierConfigType;
+    /** Whether to suppress console output */
     silent: boolean;
 };
 /**
@@ -218,13 +259,108 @@ export declare class CoreContext {
      * @throws Will throw an error if any phase of the pipeline fails
      */
     toArtifacts({ documentObject, settings, toGeneratorConfigMap, prettier }: ToArtifactsArgs): Promise<RenderResult>;
+    /**
+     * Executes a function with distributed tracing and logging.
+     *
+     * This method wraps function execution with tracing capabilities, updating the
+     * stack trail for context tracking and logging execution details. It's used
+     * throughout the SKMTC pipeline to maintain execution context and debugging information.
+     *
+     * @template T - The return type of the traced function
+     * @param token - Single token or array of tokens to add to the trace stack
+     * @param fn - The function to execute within the trace context
+     * @returns The result of executing the traced function
+     *
+     * @example Single token tracing
+     * ```typescript
+     * const result = context.trace('parse-schema', () => {
+     *   // Schema parsing logic here
+     *   return parsedSchema;
+     * });
+     * ```
+     *
+     * @example Multiple token tracing (nested context)
+     * ```typescript
+     * const result = context.trace(['components', 'schemas', 'User'], () => {
+     *   // Process User schema
+     *   return processedUserSchema;
+     * });
+     * ```
+     */
     trace<T>(token: string | string[], fn: () => T): T;
+    /**
+     * Captures a result at the current execution position in the stack trail.
+     *
+     * This method records processing results (success, warning, error, etc.) at the
+     * current location in the document traversal stack. Results are associated with
+     * the current stack trail position, enabling detailed error reporting and
+     * debugging of OpenAPI processing issues.
+     *
+     * @param result - The type of result to capture (success, warning, error, etc.)
+     *
+     * @example Capturing a warning result
+     * ```typescript
+     * context.captureCurrentResult('warning');
+     * // Result captured at current stack position like: "components.schemas.User.properties.email"
+     * ```
+     *
+     * @example Usage during schema processing
+     * ```typescript
+     * context.trace(['components', 'schemas', 'User'], () => {
+     *   try {
+     *     processUserSchema();
+     *     context.captureCurrentResult('success');
+     *   } catch (error) {
+     *     context.captureCurrentResult('error');
+     *   }
+     * });
+     * ```
+     */
     captureCurrentResult(result: ResultType): void;
 }
+/**
+ * Arguments for the SKMTC JSON log formatter.
+ *
+ * Contains the log record and stack trail information needed to format
+ * structured JSON log entries for the SKMTC processing pipeline.
+ */
 export type JsonFormatterArgs = {
+    /** The Deno log record containing log level, message, and metadata */
     logRecord: log.LogRecord;
+    /** String representation of the current stack trail position */
     stackTrail: string;
 };
+/**
+ * Custom JSON formatter for SKMTC log entries.
+ *
+ * Formats log records into structured JSON that includes stack trail context,
+ * making it easier to trace execution and debug issues in the SKMTC pipeline.
+ * The formatter flattens log arguments and includes execution context.
+ *
+ * @param args - Formatter arguments containing log record and stack trail
+ * @returns Formatted JSON string for the log entry
+ *
+ * @example Usage in logger setup
+ * ```typescript
+ * const handler = new ConsoleHandler("DEBUG", {
+ *   formatter: (logRecord) => skmtcFormatter({
+ *     logRecord,
+ *     stackTrail: context.stackTrail.toString()
+ *   })
+ * });
+ * ```
+ *
+ * @example Output format
+ * ```json
+ * {
+ *   "stackTrail": "components.schemas.User.properties.email",
+ *   "level": "INFO",
+ *   "datetime": 1645123456789,
+ *   "message": "Processing email property",
+ *   "args": { "format": "email", "required": true }
+ * }
+ * ```
+ */
 export declare function skmtcFormatter({ logRecord, stackTrail }: JsonFormatterArgs): string;
 export {};
 //# sourceMappingURL=CoreContext.d.ts.map

package/esm/context/CoreContext.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CoreContext.d.ts","sourceRoot":"","sources":["../../src/context/CoreContext.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"CoreContext.d.ts","sourceRoot":"","sources":["../../src/context/CoreContext.ts"],"names":[],"mappings":"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"}

package/esm/context/CoreContext.js

@@ -278,11 +278,67 @@ export class CoreContext {
             });
         }
     }
+    /**
+     * Executes a function with distributed tracing and logging.
+     *
+     * This method wraps function execution with tracing capabilities, updating the
+     * stack trail for context tracking and logging execution details. It's used
+     * throughout the SKMTC pipeline to maintain execution context and debugging information.
+     *
+     * @template T - The return type of the traced function
+     * @param token - Single token or array of tokens to add to the trace stack
+     * @param fn - The function to execute within the trace context
+     * @returns The result of executing the traced function
+     *
+     * @example Single token tracing
+     * ```typescript
+     * const result = context.trace('parse-schema', () => {
+     *   // Schema parsing logic here
+     *   return parsedSchema;
+     * });
+     * ```
+     *
+     * @example Multiple token tracing (nested context)
+     * ```typescript
+     * const result = context.trace(['components', 'schemas', 'User'], () => {
+     *   // Process User schema
+     *   return processedUserSchema;
+     * });
+     * ```
+     */
     trace(token, fn) {
         console.log('trace', token);
         this.logger.info('trace', token);
         return tracer(__classPrivateFieldGet(this, _CoreContext_stackTrail, "f"), token, fn, this.logger);
     }
+    /**
+     * Captures a result at the current execution position in the stack trail.
+     *
+     * This method records processing results (success, warning, error, etc.) at the
+     * current location in the document traversal stack. Results are associated with
+     * the current stack trail position, enabling detailed error reporting and
+     * debugging of OpenAPI processing issues.
+     *
+     * @param result - The type of result to capture (success, warning, error, etc.)
+     *
+     * @example Capturing a warning result
+     * ```typescript
+     * context.captureCurrentResult('warning');
+     * // Result captured at current stack position like: "components.schemas.User.properties.email"
+     * ```
+     *
+     * @example Usage during schema processing
+     * ```typescript
+     * context.trace(['components', 'schemas', 'User'], () => {
+     *   try {
+     *     processUserSchema();
+     *     context.captureCurrentResult('success');
+     *   } catch (error) {
+     *     context.captureCurrentResult('error');
+     *   }
+     * });
+     * ```
+     */
     captureCurrentResult(result) {
         __classPrivateFieldGet(this, _CoreContext_results, "f").capture(__classPrivateFieldGet(this, _CoreContext_stackTrail, "f").toString(), result);
     }
@@ -354,6 +410,37 @@ _CoreContext_phase = new WeakMap(), _CoreContext_results = new WeakMap(), _CoreC
     });
     return { type: 'render', context: renderContext };
 };
+/**
+ * Custom JSON formatter for SKMTC log entries.
+ *
+ * Formats log records into structured JSON that includes stack trail context,
+ * making it easier to trace execution and debug issues in the SKMTC pipeline.
+ * The formatter flattens log arguments and includes execution context.
+ *
+ * @param args - Formatter arguments containing log record and stack trail
+ * @returns Formatted JSON string for the log entry
+ *
+ * @example Usage in logger setup
+ * ```typescript
+ * const handler = new ConsoleHandler("DEBUG", {
+ *   formatter: (logRecord) => skmtcFormatter({
+ *     logRecord,
+ *     stackTrail: context.stackTrail.toString()
+ *   })
+ * });
+ * ```
+ *
+ * @example Output format
+ * ```json
+ * {
+ *   "stackTrail": "components.schemas.User.properties.email",
+ *   "level": "INFO",
+ *   "datetime": 1645123456789,
+ *   "message": "Processing email property",
+ *   "args": { "format": "email", "required": true }
+ * }
+ * ```
+ */
 export function skmtcFormatter({ logRecord, stackTrail }) {
     return JSON.stringify({
         stackTrail,

package/esm/dsl/constants.d.ts

@@ -1,2 +1,30 @@
+/**
+ * Marker constant representing an empty or unset value in the SKMTC DSL system.
+ *
+ * This constant is used throughout the DSL to represent placeholders, empty
+ * templates, or uninitialized content. It provides a consistent way to identify
+ * empty states that need to be handled during code generation.
+ *
+ * @example Usage in templates
+ * ```typescript
+ * import { EMPTY } from '@skmtc/core';
+ *
+ * const template = someCondition ? 'actual content' : EMPTY;
+ *
+ * if (template === EMPTY) {
+ *   // Handle empty state
+ *   console.log('No content to generate');
+ * }
+ * ```
+ *
+ * @example DSL content generation
+ * ```typescript
+ * const content = new List([
+ *   'import { User } from "./types";',
+ *   someFeature ? 'import { Admin } from "./admin";' : EMPTY,
+ *   'export { User };'
+ * ]).filter(line => line !== EMPTY);
+ * ```
+ */
 export declare const EMPTY = "__EMPTY__";
 //# sourceMappingURL=constants.d.ts.map

package/esm/dsl/constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/dsl/constants.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,KAAK,cAAc,CAAA"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/dsl/constants.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,KAAK,cAAc,CAAA"}

package/esm/dsl/constants.js

@@ -1 +1,29 @@
+/**
+ * Marker constant representing an empty or unset value in the SKMTC DSL system.
+ *
+ * This constant is used throughout the DSL to represent placeholders, empty
+ * templates, or uninitialized content. It provides a consistent way to identify
+ * empty states that need to be handled during code generation.
+ *
+ * @example Usage in templates
+ * ```typescript
+ * import { EMPTY } from '@skmtc/core';
+ *
+ * const template = someCondition ? 'actual content' : EMPTY;
+ *
+ * if (template === EMPTY) {
+ *   // Handle empty state
+ *   console.log('No content to generate');
+ * }
+ * ```
+ *
+ * @example DSL content generation
+ * ```typescript
+ * const content = new List([
+ *   'import { User } from "./types";',
+ *   someFeature ? 'import { Admin } from "./admin";' : EMPTY,
+ *   'export { User };'
+ * ]).filter(line => line !== EMPTY);
+ * ```
+ */
 export const EMPTY = '__EMPTY__';

package/esm/oas/_helpers/parseDefault.d.ts

@@ -1,16 +1,164 @@
 import type { OpenAPIV3 } from 'openapi-types';
 import type { ParseContext } from '../../context/ParseContext.js';
 import * as v from 'valibot';
+/**
+ * Arguments for parsing OpenAPI schema default values.
+ *
+ * @template T - The expected type of the default value
+ * @template Nullable - Whether the schema allows null values
+ * @template Value - The OpenAPI schema object type
+ */
 type ParseDefaultArgs<T, Nullable extends boolean | undefined, Value extends OpenAPIV3.SchemaObject> = {
+    /** The OpenAPI schema object without nullable, example, and enum properties */
     value: Omit<Value, 'nullable' | 'example' | 'enum'>;
+    /** Whether the schema allows null values */
     nullable: Nullable;
+    /** Valibot schema for validating the default value */
     valibotSchema: v.GenericSchema<T>;
+    /** Parse context for error handling */
     context: ParseContext;
 };
+/**
+ * Return type for parsed default value data.
+ *
+ * @template T - The expected type of the default value
+ * @template Nullable - Whether the schema allows null values
+ * @template Value - The OpenAPI schema object type
+ */
 type ParseDefaultReturn<T, Nullable extends boolean | undefined, Value extends OpenAPIV3.SchemaObject> = {
+    /** The parsed and validated default value */
     default: Nullable extends true ? T | null | undefined : T | undefined;
+    /** The schema object with all processed properties removed */
     value: Omit<Value, 'nullable' | 'example' | 'enum' | 'default'>;
 };
+/**
+ * Parses and validates OpenAPI schema default values with type safety.
+ *
+ * This function extracts and validates default values from OpenAPI schema objects,
+ * ensuring they conform to the expected type and handling nullable schemas correctly.
+ * Invalid default values are removed and logged as warnings through the parse context.
+ *
+ * The function provides full type safety, with the return type reflecting whether
+ * null values are allowed based on the nullable parameter. This ensures that
+ * generated code maintains proper type constraints for default values.
+ *
+ * @template T - The expected type of the default value
+ * @template Nullable - Whether the schema allows null as a default
+ * @template Value - The OpenAPI schema object type
+ *
+ * @param args - Parsing configuration
+ * @returns Parsed default data with the validated default value and cleaned schema
+ *
+ * @example Basic string default parsing
+ * ```typescript
+ * import { parseDefault } from '@skmtc/core/oas/_helpers';
+ * import * as v from 'valibot';
+ *
+ * const result = parseDefault({
+ *   value: {
+ *     type: 'string',
+ *     default: 'hello world',
+ *     minLength: 5
+ *   },
+ *   nullable: false,
+ *   valibotSchema: v.string(),
+ *   context: parseContext
+ * });
+ *
+ * console.log(result.default); // 'hello world'
+ * console.log(result.value);   // { type: 'string', minLength: 5 }
+ * ```
+ *
+ * @example Nullable default value
+ * ```typescript
+ * const result = parseDefault({
+ *   value: {
+ *     type: 'string',
+ *     default: null,
+ *     format: 'email'
+ *   },
+ *   nullable: true,
+ *   valibotSchema: v.string(),
+ *   context: parseContext
+ * });
+ *
+ * console.log(result.default); // null (valid for nullable schema)
+ * // Type: string | null | undefined
+ * ```
+ *
+ * @example Number default with constraints
+ * ```typescript
+ * const result = parseDefault({
+ *   value: {
+ *     type: 'number',
+ *     default: 42,
+ *     minimum: 0,
+ *     maximum: 100
+ *   },
+ *   nullable: false,
+ *   valibotSchema: v.number(),
+ *   context: parseContext
+ * });
+ *
+ * console.log(result.default); // 42
+ * console.log(result.value);   // { type: 'number', minimum: 0, maximum: 100 }
+ * ```
+ *
+ * @example Invalid default handling
+ * ```typescript
+ * const result = parseDefault({
+ *   value: {
+ *     type: 'boolean',
+ *     default: 'not a boolean', // Invalid default
+ *     description: 'A boolean flag'
+ *   },
+ *   nullable: false,
+ *   valibotSchema: v.boolean(),
+ *   context: parseContext
+ * });
+ *
+ * console.log(result.default); // undefined (invalid default removed)
+ * // Context will log a warning about the invalid default
+ * ```
+ *
+ * @example Array default value
+ * ```typescript
+ * const result = parseDefault({
+ *   value: {
+ *     type: 'array',
+ *     items: { type: 'string' },
+ *     default: ['item1', 'item2']
+ *   },
+ *   nullable: false,
+ *   valibotSchema: v.array(v.string()),
+ *   context: parseContext
+ * });
+ *
+ * console.log(result.default); // ['item1', 'item2']
+ * ```
+ *
+ * @example Object default value
+ * ```typescript
+ * const result = parseDefault({
+ *   value: {
+ *     type: 'object',
+ *     properties: {
+ *       name: { type: 'string' },
+ *       age: { type: 'number' }
+ *     },
+ *     default: { name: 'John', age: 30 }
+ *   },
+ *   nullable: false,
+ *   valibotSchema: v.object({
+ *     name: v.string(),
+ *     age: v.number()
+ *   }),
+ *   context: parseContext
+ * });
+ *
+ * console.log(result.default); // { name: 'John', age: 30 }
+ * ```
+ */
 export declare const parseDefault: <T, Nullable extends boolean | undefined, Value extends OpenAPIV3.SchemaObject>({ value, nullable, valibotSchema, context }: ParseDefaultArgs<T, Nullable, Value>) => ParseDefaultReturn<T, Nullable, Value>;
 export {};
 //# sourceMappingURL=parseDefault.d.ts.map

package/esm/oas/_helpers/parseDefault.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parseDefault.d.ts","sourceRoot":"","sources":["../../../src/oas/_helpers/parseDefault.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAC9C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAA;AACjE,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAE5B,KAAK,gBAAgB,CACnB,CAAC,EACD,QAAQ,SAAS,OAAO,GAAG,SAAS,EACpC,KAAK,SAAS,SAAS,CAAC,YAAY,IAClC;IACF,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,SAAS,GAAG,MAAM,CAAC,CAAA;IACnD,QAAQ,EAAE,QAAQ,CAAA;IAClB,aAAa,EAAE,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAA;IACjC,OAAO,EAAE,YAAY,CAAA;CACtB,CAAA;AAED,KAAK,kBAAkB,CACrB,CAAC,EACD,QAAQ,SAAS,OAAO,GAAG,SAAS,EACpC,KAAK,SAAS,SAAS,CAAC,YAAY,IAClC;IACF,OAAO,EAAE,QAAQ,SAAS,IAAI,GAAG,CAAC,GAAG,IAAI,GAAG,SAAS,GAAG,CAAC,GAAG,SAAS,CAAA;IACrE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAAC,CAAA;CAChE,CAAA;AAED,eAAO,MAAM,YAAY,GACvB,CAAC,EACD,QAAQ,SAAS,OAAO,GAAG,SAAS,EACpC,KAAK,SAAS,SAAS,CAAC,YAAY,EACpC,6CAKC,gBAAgB,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,KAAG,kBAAkB,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,CAgB9E,CAAA"}
+{"version":3,"file":"parseDefault.d.ts","sourceRoot":"","sources":["../../../src/oas/_helpers/parseDefault.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAC9C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAA;AACjE,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAE5B;;;;;;GAMG;AACH,KAAK,gBAAgB,CACnB,CAAC,EACD,QAAQ,SAAS,OAAO,GAAG,SAAS,EACpC,KAAK,SAAS,SAAS,CAAC,YAAY,IAClC;IACF,+EAA+E;IAC/E,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,SAAS,GAAG,MAAM,CAAC,CAAA;IACnD,4CAA4C;IAC5C,QAAQ,EAAE,QAAQ,CAAA;IAClB,sDAAsD;IACtD,aAAa,EAAE,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAA;IACjC,uCAAuC;IACvC,OAAO,EAAE,YAAY,CAAA;CACtB,CAAA;AAED;;;;;;GAMG;AACH,KAAK,kBAAkB,CACrB,CAAC,EACD,QAAQ,SAAS,OAAO,GAAG,SAAS,EACpC,KAAK,SAAS,SAAS,CAAC,YAAY,IAClC;IACF,6CAA6C;IAC7C,OAAO,EAAE,QAAQ,SAAS,IAAI,GAAG,CAAC,GAAG,IAAI,GAAG,SAAS,GAAG,CAAC,GAAG,SAAS,CAAA;IACrE,8DAA8D;IAC9D,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAAC,CAAA;CAChE,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+HG;AACH,eAAO,MAAM,YAAY,GACvB,CAAC,EACD,QAAQ,SAAS,OAAO,GAAG,SAAS,EACpC,KAAK,SAAS,SAAS,CAAC,YAAY,EACpC,6CAKC,gBAAgB,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,KAAG,kBAAkB,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,CAgB9E,CAAA"}