@skmtc/core 0.29.0 → 0.31.0

package/esm/parse/v3-1/operation/toOperationsV3.js

@@ -3,7 +3,7 @@ import { toResponsesV3 } from '../response/toResponseV3.js';
 import { toParameterListV3 } from '../parameter/toParameterV3.js';
 import { OasOperation } from '../../../oas/operation/Operation.js';
 import { toPathItemV3 } from '../pathItem/toPathItemV3.js';
-import { methodValues } from '../../../types/Method.js';
+import { toPathItemMethod } from '../methods.js';
 import { toSpecificationExtensionsV3 } from '../specificationExtensions/toSpecificationExtensionsV3.js';
 import { toSecurityRequirementsV3 } from '../securityRequirement/toSecurityRequirement.js';
 import { isEmpty } from '../../../helpers/isEmpty.js';
@@ -57,14 +57,14 @@ export const toOperationsV3 = ({ paths, stackTrail, context }) => {
                 return [];
             }
             const cleaned = Object.entries(pathItem).reduce(({ rest, methodObject }, [key, operation]) => {
-                const isMethod = methodValues.includes(key);
-                if (isMethod) {
-                    const { [key]: _deleted, ...remaining } = rest;
+                const method = toPathItemMethod(key);
+                if (method) {
+                    const { [method]: _deleted, ...remaining } = rest;
                     return {
                         rest: remaining,
                         methodObject: {
                             ...methodObject,
-                            [key]: operation
+                            [method]: operation
                         }
                     };
                 }

package/esm/parse/v3-1/parameter/toParameterV3.d.ts

@@ -1,9 +1,10 @@
 import type { ParseContextType } from '../../../context/parseTypes.js';
-import { type OasParameterLocation } from '../../../oas/parameter/parameter-types.js';
+import type { OasParameterLocation } from '../../../oas/parameter/parameter-types.js';
 import type { OpenAPIV3 } from 'openapi-types';
 import { OasParameter } from '../../../oas/parameter/Parameter.js';
 import type { OasRef } from '../../../oas/ref/Ref.js';
 import type { StackTrail } from '../../../context/StackTrail.js';
+type ParameterLocation = Exclude<OasParameterLocation, 'querystring'>;
 export type ToParameterListV3Args = {
     parameters: (OpenAPIV3.ParameterObject | OpenAPIV3.ReferenceObject)[] | undefined;
     stackTrail: StackTrail;
@@ -29,7 +30,7 @@ export type ToParameterV3Args = {
 };
 export type ToStyleArgs = {
     style: string | undefined;
-    location: OasParameterLocation;
+    location: ParameterLocation;
     stackTrail: StackTrail;
 };
 export type ToExplodeArgs = {
@@ -37,3 +38,4 @@ export type ToExplodeArgs = {
     style: string | undefined;
     stackTrail: StackTrail;
 };
+export {};

package/esm/parse/v3-1/parameter/toParameterV3.js

@@ -1,6 +1,5 @@
 import { tryParseAt } from '../../../context/tryParseAt.js';
 import { isRef } from '../../../helpers/refFns.js';
-import { oasParameterLocation, oasParameterStyle } from '../../../oas/parameter/parameter-types.js';
 import { toExamplesV3 } from '../example/toExamplesV3.js';
 import { toRefV31 } from '../ref/toRefV31.js';
 import { toOptionalSchemaV3 } from '../schema/toSchemasV3.js';
@@ -8,6 +7,21 @@ import { toOptionalMediaTypeItemsV3 } from '../mediaType/toMediaTypeItemV3.js';
 import { OasParameter } from '../../../oas/parameter/Parameter.js';
 import { toSpecificationExtensionsV3 } from '../specificationExtensions/toSpecificationExtensionsV3.js';
 import * as v from 'valibot';
+const parameterLocation = v.enum({
+    query: 'query',
+    header: 'header',
+    path: 'path',
+    cookie: 'cookie'
+});
+const parameterStyle = v.enum({
+    matrix: 'matrix',
+    label: 'label',
+    form: 'form',
+    simple: 'simple',
+    spaceDelimited: 'spaceDelimited',
+    pipeDelimited: 'pipeDelimited',
+    deepObject: 'deepObject'
+});
 export const toParameterListV3 = ({ parameters, stackTrail, context }) => {
     if (!parameters) {
         return undefined;
@@ -52,7 +66,7 @@ const toParameterV3 = ({ parameter, stackTrail, context }) => {
         stackTrail,
         parentType: 'parameter'
     });
-    const parsedLocation = v.parse(oasParameterLocation, location);
+    const parsedLocation = v.parse(parameterLocation, location);
     if (parsedLocation === 'path' && !required) {
         console.warn(`Path parameters must be required`);
     }
@@ -82,7 +96,7 @@ const toParameterV3 = ({ parameter, stackTrail, context }) => {
     return context.withStackTrail(stackTrail, () => new OasParameter(fields, context));
 };
 const toStyle = ({ style, location, stackTrail }) => {
-    const parsed = v.parse(v.optional(oasParameterStyle), style);
+    const parsed = v.parse(v.optional(parameterStyle), style);
     if (parsed !== undefined) {
         return parsed;
     }

package/esm/parse/v3-1/requestBody/toRequestBodiesV3.js

@@ -3,6 +3,7 @@ import { toRefV31 } from '../ref/toRefV31.js';
 import { toMediaTypeItemsV3 } from '../mediaType/toMediaTypeItemV3.js';
 import { OasRequestBody } from '../../../oas/requestBody/RequestBody.js';
 import { toSpecificationExtensionsV3 } from '../specificationExtensions/toSpecificationExtensionsV3.js';
+import { logBodyMediaTypes } from '../../logBodyMediaTypes.js';
 export const toRequestBodyV3 = ({ requestBody, stackTrail, context }) => {
     if (!requestBody) {
         return undefined;
@@ -26,7 +27,9 @@ export const toRequestBodyV3 = ({ requestBody, stackTrail, context }) => {
         required,
         extensionFields
     };
-    return context.withStackTrail(stackTrail, () => new OasRequestBody(fields, context));
+    const parsed = context.withStackTrail(stackTrail, () => new OasRequestBody(fields, context));
+    logBodyMediaTypes({ content: fields.content, stackTrail, context });
+    return parsed;
 };
 export const toRequestBodiesV3 = ({ requestBodies, stackTrail, context }) => {
     if (!requestBodies) {

package/esm/parse/v3-1/response/toResponseV3.js

@@ -6,6 +6,7 @@ import { toOptionalMediaTypeItemsV3 } from '../mediaType/toMediaTypeItemV3.js';
 import { OasResponse } from '../../../oas/response/Response.js';
 import { toSpecificationExtensionsV3 } from '../specificationExtensions/toSpecificationExtensionsV3.js';
 import { tryParseAt } from '../../../context/tryParseAt.js';
+import { logBodyMediaTypes } from '../../logBodyMediaTypes.js';
 export const toResponsesV3 = ({ responses, stackTrail, context }) => {
     const output = {};
     const entries = Object.entries(responses);
@@ -45,11 +46,13 @@ export const toResponseV3 = ({ response, stackTrail, context }) => {
     const parsedHeaders = stackTrail.trace('headers', st => toHeadersV3({ headers, stackTrail: st, context }));
     const parsedLinks = stackTrail.trace('links', st => toLinksV3({ links, stackTrail: st, context }));
     const parsedContent = stackTrail.trace('content', st => toOptionalMediaTypeItemsV3({ content, stackTrail: st, context }));
-    return context.withStackTrail(stackTrail, () => new OasResponse({
+    const parsed = context.withStackTrail(stackTrail, () => new OasResponse({
         description,
         headers: parsedHeaders,
         links: parsedLinks,
         content: parsedContent,
         extensionFields
     }, context));
+    logBodyMediaTypes({ content: parsedContent, stackTrail, context });
+    return parsed;
 };

package/esm/parse/v3-1/securitySchemes/toSecuritySchemes.js

@@ -1,10 +1,10 @@
 import { OasHttpSecurityScheme, OasApiKeySecurityScheme, OasOAuth2SecurityScheme, OasOpenIdSecurityScheme } from '../../../oas/securitySchemes/SecurityScheme.js';
 import * as v from 'valibot';
-import { oasApiKeySecuritySchemeData, oasHttpSecuritySchemeData, oasOAuth2SecuritySchemeData, oasOpenIdSecuritySchemeData } from '../../../oas/securitySchemes/security-scheme-types.js';
+import { oasApiKeySecuritySchemeData, oasHttpSecuritySchemeData, oasOAuth2FlowsData, oasOAuth2SecuritySchemeData, oasOpenIdSecuritySchemeData } from '../../../oas/securitySchemes/security-scheme-types.js';
 import { toRefV31 } from '../ref/toRefV31.js';
 import { isRef } from '../../../helpers/refFns.js';
-import { isEmpty } from '../../../helpers/isEmpty.js';
 import { tryParseAt } from '../../../context/tryParseAt.js';
+import { toSpecificationExtensionsV3 } from '../specificationExtensions/toSpecificationExtensionsV3.js';
 export const toSecuritySchemesV3 = ({ securitySchemes, stackTrail, context }) => {
     if (!securitySchemes) {
         return undefined;
@@ -27,21 +27,29 @@ export const toSecuritySchemesV3 = ({ securitySchemes, stackTrail, context }) =>
     }
     return output;
 };
+/**
+ * Log the keys of `value` that `known` does not name as skipped fields.
+ * `v.parse` on a `v.object` schema strips unknown keys, so they are read
+ * off the raw object. `x-` extensions are not logged.
+ */
+const logSkippedKeys = ({ value, known, parentType, stackTrail, context }) => {
+    const skipped = Object.fromEntries(Object.entries(value).filter(([key]) => !Object.hasOwn(known, key)));
+    toSpecificationExtensionsV3({ skipped, parent: value, parentType, stackTrail, context });
+};
 const toSecuritySchemeV3 = ({ securityScheme, stackTrail, context }) => {
     if (isRef(securityScheme)) {
         return toRefV31({ ref: securityScheme, refType: 'securityScheme', stackTrail, context });
     }
     switch (securityScheme.type) {
         case 'http': {
-            const { type: _type, description, scheme, bearerFormat, ...skipped } = v.parse(oasHttpSecuritySchemeData, securityScheme);
-            if (!isEmpty(skipped)) {
-                context.logSkippedFields({
-                    skipped,
-                    parent: securityScheme,
-                    stackTrail,
-                    parentType: 'securityScheme:http'
-                });
-            }
+            const { description, scheme, bearerFormat } = v.parse(oasHttpSecuritySchemeData, securityScheme);
+            logSkippedKeys({
+                value: securityScheme,
+                known: oasHttpSecuritySchemeData.entries,
+                parentType: 'securityScheme:http',
+                stackTrail,
+                context
+            });
             return new OasHttpSecurityScheme({
                 description,
                 scheme,
@@ -49,15 +57,14 @@ const toSecuritySchemeV3 = ({ securityScheme, stackTrail, context }) => {
             });
         }
         case 'apiKey': {
-            const { type: _type, in: location, description, name, ...skipped } = v.parse(oasApiKeySecuritySchemeData, securityScheme);
-            if (!isEmpty(skipped)) {
-                context.logSkippedFields({
-                    skipped,
-                    parent: securityScheme,
-                    stackTrail,
-                    parentType: 'securityScheme:apiKey'
-                });
-            }
+            const { in: location, description, name } = v.parse(oasApiKeySecuritySchemeData, securityScheme);
+            logSkippedKeys({
+                value: securityScheme,
+                known: oasApiKeySecuritySchemeData.entries,
+                parentType: 'securityScheme:apiKey',
+                stackTrail,
+                context
+            });
             return new OasApiKeySecurityScheme({
                 description,
                 name,
@@ -65,30 +72,35 @@ const toSecuritySchemeV3 = ({ securityScheme, stackTrail, context }) => {
             });
         }
         case 'oauth2': {
-            const { type: _type, flows, description, ...skipped } = v.parse(oasOAuth2SecuritySchemeData, securityScheme);
-            if (!isEmpty(skipped)) {
-                context.logSkippedFields({
-                    skipped,
-                    parent: securityScheme,
-                    stackTrail,
-                    parentType: 'securityScheme:oauth2'
-                });
-            }
+            const { flows, description } = v.parse(oasOAuth2SecuritySchemeData, securityScheme);
+            logSkippedKeys({
+                value: securityScheme,
+                known: oasOAuth2SecuritySchemeData.entries,
+                parentType: 'securityScheme:oauth2',
+                stackTrail,
+                context
+            });
+            stackTrail.trace('flows', st => logSkippedKeys({
+                value: securityScheme.flows,
+                known: oasOAuth2FlowsData.entries,
+                parentType: 'oauthFlows',
+                stackTrail: st,
+                context
+            }));
             return new OasOAuth2SecurityScheme({
                 description,
                 flows
             });
         }
         case 'openIdConnect': {
-            const { type: _type, description, openIdConnectUrl, ...skipped } = v.parse(oasOpenIdSecuritySchemeData, securityScheme);
-            if (!isEmpty(skipped)) {
-                context.logSkippedFields({
-                    skipped,
-                    parent: securityScheme,
-                    stackTrail,
-                    parentType: 'securityScheme:openIdConnect'
-                });
-            }
+            const { description, openIdConnectUrl } = v.parse(oasOpenIdSecuritySchemeData, securityScheme);
+            logSkippedKeys({
+                value: securityScheme,
+                known: oasOpenIdSecuritySchemeData.entries,
+                parentType: 'securityScheme:openIdConnect',
+                stackTrail,
+                context
+            });
             return new OasOpenIdSecurityScheme({
                 description,
                 openIdConnectUrl

package/esm/parse/v3-1/webhook/toWebhooksV3.js

@@ -3,7 +3,7 @@ import { toResponsesV3 } from '../response/toResponseV3.js';
 import { toParameterListV3 } from '../parameter/toParameterV3.js';
 import { OasWebhook } from '../../../oas/webhook/Webhook.js';
 import { toPathItemV3 } from '../pathItem/toPathItemV3.js';
-import { methodValues } from '../../../types/Method.js';
+import { toPathItemMethod } from '../methods.js';
 import { toSpecificationExtensionsV3 } from '../specificationExtensions/toSpecificationExtensionsV3.js';
 import { toSecurityRequirementsV3 } from '../securityRequirement/toSecurityRequirement.js';
 import { isEmpty } from '../../../helpers/isEmpty.js';
@@ -69,14 +69,14 @@ export const toWebhooksV3 = ({ webhooks, stackTrail, context }) => {
                 return [];
             }
             const cleaned = Object.entries(pathItem).reduce(({ rest, methodObject }, [key, operation]) => {
-                const isMethod = methodValues.includes(key);
-                if (isMethod) {
-                    const { [key]: _deleted, ...remaining } = rest;
+                const method = toPathItemMethod(key);
+                if (method) {
+                    const { [method]: _deleted, ...remaining } = rest;
                     return {
                         rest: remaining,
                         methodObject: {
                             ...methodObject,
-                            [key]: operation
+                            [method]: operation
                         }
                     };
                 }

package/esm/parse/v3-2/_helpers/parseDefault.d.ts

@@ -0,0 +1,43 @@
+import type { ParseContextType } from '../../../context/parseTypes.js';
+import type { StackTrail } from '../../../context/StackTrail.js';
+/**
+ * Arguments for parsing the `default` property from OpenAPI schemas.
+ *
+ * @template Value - The narrowed type a valid (non-null) default holds
+ */
+export type ParseDefaultArgs<Value> = {
+    /** The raw `default` value extracted from the schema */
+    value: unknown;
+    /** The parsed nullable flag — `null` is only a valid default when this is `true` */
+    nullable: boolean | undefined;
+    /** The surrounding schema object, used as the issue location's parent */
+    parent: unknown;
+    /** Type guard narrowing an acceptable non-null default to `Value` */
+    check: (item: unknown) => item is Value;
+    /** Builds the warning message for a rejected default */
+    toMessage: (item: unknown) => string;
+    /** Parse context for logging issues */
+    context: ParseContextType;
+    /** Stack trail for tracking the current parsing location */
+    stackTrail: StackTrail;
+};
+/**
+ * Parses and validates the `default` property of an OpenAPI scalar/structural
+ * schema, applying the nullable-conditional rule shared by `example`, `enum`,
+ * and `default`:
+ *
+ * - `undefined` → `undefined` (no default present)
+ * - `null` → kept only when `nullable` is `true`; otherwise rejected
+ * - a value passing `check` → kept
+ * - anything else → logged as an `INVALID_DEFAULT` warning and dropped
+ *
+ * This mirrors the OpenAPI 3.0 rule that a `default` MUST conform to the
+ * schema's type, where `nullable: true` widens that type to include `null`.
+ * The function is fail-open: an invalid default is stripped and recorded as a
+ * `ParseIssue`, never thrown.
+ *
+ * @template Value - The narrowed type a valid default holds
+ * @param args - Parsing configuration
+ * @returns The validated default (`Value`), `null` (nullable), or `undefined`
+ */
+export declare const parseDefault: <Value>({ value, nullable, parent, context, check, toMessage, stackTrail }: ParseDefaultArgs<Value>) => Value | null | undefined;

package/esm/parse/v3-2/_helpers/parseDefault.js

@@ -0,0 +1,39 @@
+/**
+ * Parses and validates the `default` property of an OpenAPI scalar/structural
+ * schema, applying the nullable-conditional rule shared by `example`, `enum`,
+ * and `default`:
+ *
+ * - `undefined` → `undefined` (no default present)
+ * - `null` → kept only when `nullable` is `true`; otherwise rejected
+ * - a value passing `check` → kept
+ * - anything else → logged as an `INVALID_DEFAULT` warning and dropped
+ *
+ * This mirrors the OpenAPI 3.0 rule that a `default` MUST conform to the
+ * schema's type, where `nullable: true` widens that type to include `null`.
+ * The function is fail-open: an invalid default is stripped and recorded as a
+ * `ParseIssue`, never thrown.
+ *
+ * @template Value - The narrowed type a valid default holds
+ * @param args - Parsing configuration
+ * @returns The validated default (`Value`), `null` (nullable), or `undefined`
+ */
+export const parseDefault = ({ value, nullable, parent, context, check, toMessage, stackTrail }) => {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (nullable && value === null) {
+        return null;
+    }
+    if (!check(value)) {
+        context.logIssue({
+            key: 'default',
+            level: 'warning',
+            message: toMessage(value),
+            parent,
+            stackTrail,
+            type: 'INVALID_DEFAULT'
+        });
+        return undefined;
+    }
+    return value;
+};

package/esm/parse/v3-2/_helpers/parseEnum.d.ts

@@ -0,0 +1,13 @@
+import type { ParseContextType } from '../../../context/parseTypes.js';
+import type { StackTrail } from '../../../context/StackTrail.js';
+type ParseEnumArgs = {
+    value: unknown;
+    nullable: boolean | undefined;
+    parent: unknown;
+    check: (item: unknown) => boolean;
+    toMessage: (item: unknown) => string;
+    context: ParseContextType;
+    stackTrail: StackTrail;
+};
+export declare const parseEnum: ({ value, nullable, parent, context, check, toMessage, stackTrail }: ParseEnumArgs) => any[] | undefined;
+export {};

package/esm/parse/v3-2/_helpers/parseEnum.js

@@ -0,0 +1,23 @@
+export const parseEnum = ({ value, nullable, parent, context, check, toMessage, stackTrail }) => {
+    if (Array.isArray(value)) {
+        for (const item of value) {
+            if (nullable && item === null) {
+                continue;
+            }
+            if (check(item)) {
+                continue;
+            }
+            context.logIssue({
+                key: 'enum',
+                level: 'warning',
+                message: toMessage(item),
+                parent,
+                stackTrail,
+                type: 'INVALID_ENUM'
+            });
+            return undefined;
+        }
+        return value;
+    }
+    return undefined;
+};

package/esm/parse/v3-2/_helpers/parseExample.d.ts

@@ -0,0 +1,41 @@
+import type { ParseContextType } from '../../../context/parseTypes.js';
+import type { StackTrail } from '../../../context/StackTrail.js';
+/**
+ * Arguments for parsing the `example` property from OpenAPI schemas.
+ *
+ * @template Value - The narrowed type a valid (non-null) example holds
+ */
+export type ParseExampleArgs<Value> = {
+    /** The raw `example` value extracted from the schema */
+    value: unknown;
+    /** The parsed nullable flag — `null` is only a valid example when this is `true` */
+    nullable: boolean | undefined;
+    /** The surrounding schema object, used as the issue location's parent */
+    parent: unknown;
+    /** Type guard narrowing an acceptable non-null example to `Value` */
+    check: (item: unknown) => item is Value;
+    /** Builds the warning message for a rejected example */
+    toMessage: (item: unknown) => string;
+    /** Parse context for logging issues */
+    context: ParseContextType;
+    /** Stack trail for tracking the current parsing location */
+    stackTrail: StackTrail;
+};
+/**
+ * Parses and validates the `example` property of an OpenAPI scalar/structural
+ * schema, applying the nullable-conditional rule shared by `example`, `enum`,
+ * and `default`:
+ *
+ * - `undefined` → `undefined` (no example present)
+ * - `null` → kept only when `nullable` is `true`; otherwise rejected
+ * - a value passing `check` → kept
+ * - anything else → logged as an `INVALID_EXAMPLE` warning and dropped
+ *
+ * The function is fail-open: an invalid example is stripped and recorded as a
+ * `ParseIssue`, never thrown.
+ *
+ * @template Value - The narrowed type a valid example holds
+ * @param args - Parsing configuration
+ * @returns The validated example (`Value`), `null` (nullable), or `undefined`
+ */
+export declare const parseExample: <Value>({ value, nullable, parent, context, check, toMessage, stackTrail }: ParseExampleArgs<Value>) => Value | null | undefined;

package/esm/parse/v3-2/_helpers/parseExample.js

@@ -0,0 +1,37 @@
+/**
+ * Parses and validates the `example` property of an OpenAPI scalar/structural
+ * schema, applying the nullable-conditional rule shared by `example`, `enum`,
+ * and `default`:
+ *
+ * - `undefined` → `undefined` (no example present)
+ * - `null` → kept only when `nullable` is `true`; otherwise rejected
+ * - a value passing `check` → kept
+ * - anything else → logged as an `INVALID_EXAMPLE` warning and dropped
+ *
+ * The function is fail-open: an invalid example is stripped and recorded as a
+ * `ParseIssue`, never thrown.
+ *
+ * @template Value - The narrowed type a valid example holds
+ * @param args - Parsing configuration
+ * @returns The validated example (`Value`), `null` (nullable), or `undefined`
+ */
+export const parseExample = ({ value, nullable, parent, context, check, toMessage, stackTrail }) => {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (nullable && value === null) {
+        return null;
+    }
+    if (!check(value)) {
+        context.logIssue({
+            key: 'example',
+            level: 'warning',
+            message: toMessage(value),
+            parent,
+            stackTrail,
+            type: 'INVALID_EXAMPLE'
+        });
+        return undefined;
+    }
+    return value;
+};

package/esm/parse/v3-2/_helpers/parseNullable.d.ts

@@ -0,0 +1,141 @@
+import type { OpenAPIV3 } from 'openapi-types';
+import type { ParseContextType } from '../../../context/parseTypes.js';
+import type { StackTrail } from '../../../context/StackTrail.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;
+    /** Stack trail for tracking current parsing context */
+    stackTrail: StackTrail;
+    /** Parse context for error handling */
+    context: ParseContextType;
+};
+/**
+ * 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, stackTrail, context }: ParseNullableArgs<Value>) => ParseNullableReturn<Value>;