@skmtc/core 0.28.7 → 0.30.1

package/script/parse/v3-2/securitySchemes/toSecuritySchemes.js

@@ -0,0 +1,189 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toSecuritySchemesV3 = void 0;
+const SecurityScheme_js_1 = require("../../../oas/securitySchemes/SecurityScheme.js");
+const v = __importStar(require("valibot"));
+const security_scheme_types_js_1 = require("../../../oas/securitySchemes/security-scheme-types.js");
+const toRefV31_js_1 = require("../ref/toRefV31.js");
+const refFns_js_1 = require("../../../helpers/refFns.js");
+const tryParseAt_js_1 = require("../../../context/tryParseAt.js");
+const toSpecificationExtensionsV3_js_1 = require("../specificationExtensions/toSpecificationExtensionsV3.js");
+// The shared schemas are the 3.0/3.1 shape; these add the 3.2 fields.
+const deprecatedField = v.optional(v.boolean());
+const httpSecuritySchemeData = v.object({
+    ...security_scheme_types_js_1.oasHttpSecuritySchemeData.entries,
+    deprecated: deprecatedField
+});
+const apiKeySecuritySchemeData = v.object({
+    ...security_scheme_types_js_1.oasApiKeySecuritySchemeData.entries,
+    deprecated: deprecatedField
+});
+const deviceAuthorizationOAuth2FlowData = v.object({
+    deviceAuthorizationUrl: v.string(),
+    tokenUrl: v.string(),
+    refreshUrl: v.optional(v.string()),
+    scopes: v.optional(v.record(v.string(), v.string()))
+});
+const oAuth2FlowsData = v.object({
+    ...security_scheme_types_js_1.oasOAuth2FlowsData.entries,
+    deviceAuthorization: v.optional(deviceAuthorizationOAuth2FlowData)
+});
+const oAuth2SecuritySchemeData = v.object({
+    ...security_scheme_types_js_1.oasOAuth2SecuritySchemeData.entries,
+    deprecated: deprecatedField,
+    oauth2MetadataUrl: v.optional(v.string()),
+    flows: oAuth2FlowsData
+});
+const openIdSecuritySchemeData = v.object({
+    ...security_scheme_types_js_1.oasOpenIdSecuritySchemeData.entries,
+    deprecated: deprecatedField
+});
+const toSecuritySchemesV3 = ({ securitySchemes, stackTrail, context }) => {
+    if (!securitySchemes) {
+        return undefined;
+    }
+    const output = {};
+    for (const [key, value] of Object.entries(securitySchemes)) {
+        // Isolate per scheme: a single malformed security scheme is logged and
+        // skipped, the rest of the record continues (parity with toSchemasV3).
+        const parsed = (0, tryParseAt_js_1.tryParseAt)({
+            stackTrail,
+            key,
+            context,
+            type: 'INVALID_SECURITY_SCHEME',
+            parent: value,
+            fn: st => toSecuritySchemeV3({ securityScheme: value, stackTrail: st, context })
+        });
+        if (parsed !== undefined) {
+            output[key] = parsed;
+        }
+    }
+    return output;
+};
+exports.toSecuritySchemesV3 = toSecuritySchemesV3;
+/**
+ * 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)));
+    (0, toSpecificationExtensionsV3_js_1.toSpecificationExtensionsV3)({ skipped, parent: value, parentType, stackTrail, context });
+};
+const toSecuritySchemeV3 = ({ securityScheme, stackTrail, context }) => {
+    if ((0, refFns_js_1.isRef)(securityScheme)) {
+        return (0, toRefV31_js_1.toRefV31)({ ref: securityScheme, refType: 'securityScheme', stackTrail, context });
+    }
+    switch (securityScheme.type) {
+        case 'http': {
+            const { description, deprecated, scheme, bearerFormat } = v.parse(httpSecuritySchemeData, securityScheme);
+            logSkippedKeys({
+                value: securityScheme,
+                known: httpSecuritySchemeData.entries,
+                parentType: 'securityScheme:http',
+                stackTrail,
+                context
+            });
+            return new SecurityScheme_js_1.OasHttpSecurityScheme({
+                description,
+                deprecated,
+                scheme,
+                bearerFormat
+            });
+        }
+        case 'apiKey': {
+            const { in: location, description, deprecated, name } = v.parse(apiKeySecuritySchemeData, securityScheme);
+            logSkippedKeys({
+                value: securityScheme,
+                known: apiKeySecuritySchemeData.entries,
+                parentType: 'securityScheme:apiKey',
+                stackTrail,
+                context
+            });
+            return new SecurityScheme_js_1.OasApiKeySecurityScheme({
+                description,
+                deprecated,
+                name,
+                in: location
+            });
+        }
+        case 'oauth2': {
+            const { flows, description, deprecated, oauth2MetadataUrl } = v.parse(oAuth2SecuritySchemeData, securityScheme);
+            logSkippedKeys({
+                value: securityScheme,
+                known: oAuth2SecuritySchemeData.entries,
+                parentType: 'securityScheme:oauth2',
+                stackTrail,
+                context
+            });
+            stackTrail.trace('flows', st => logSkippedKeys({
+                value: securityScheme.flows,
+                known: oAuth2FlowsData.entries,
+                parentType: 'oauthFlows',
+                stackTrail: st,
+                context
+            }));
+            return new SecurityScheme_js_1.OasOAuth2SecurityScheme({
+                description,
+                deprecated,
+                oauth2MetadataUrl,
+                flows
+            });
+        }
+        case 'openIdConnect': {
+            const { description, deprecated, openIdConnectUrl } = v.parse(openIdSecuritySchemeData, securityScheme);
+            logSkippedKeys({
+                value: securityScheme,
+                known: openIdSecuritySchemeData.entries,
+                parentType: 'securityScheme:openIdConnect',
+                stackTrail,
+                context
+            });
+            return new SecurityScheme_js_1.OasOpenIdSecurityScheme({
+                description,
+                deprecated,
+                openIdConnectUrl
+            });
+        }
+        default: {
+            // Exhaustive over the discriminated union: a value reaching here has a
+            // `type` outside the OpenAPI set. `tryParseAt` isolates the throw to
+            // this one scheme.
+            const _exhaustiveCheck = securityScheme;
+            throw new Error(`Unknown security scheme type: ${JSON.stringify(_exhaustiveCheck)}`);
+        }
+    }
+};

package/script/parse/v3-2/server/toServerV3.d.ts

@@ -0,0 +1,26 @@
+import type { ParseContextType } from '../../../context/parseTypes.js';
+import type { OpenAPIV3 } from 'openapi-types';
+import { OasServer } from '../../../oas/server/Server.js';
+import type { StackTrail } from '../../../context/StackTrail.js';
+/** A 3.2 Server Object: the 3.0 shape plus `name`. */
+export type ServerObjectV32 = OpenAPIV3.ServerObject & {
+    name?: string;
+};
+export type ToServersV3Args = {
+    servers: ServerObjectV32[];
+    stackTrail: StackTrail;
+    context: ParseContextType;
+};
+export declare const toServersV3: ({ servers, stackTrail, context }: ToServersV3Args) => OasServer[];
+export type ToOptionalServersV3Args = {
+    servers: ServerObjectV32[] | undefined;
+    stackTrail: StackTrail;
+    context: ParseContextType;
+};
+export declare const toOptionalServersV3: ({ servers, stackTrail, context }: ToOptionalServersV3Args) => OasServer[] | undefined;
+export type ToServerV3Args = {
+    server: ServerObjectV32;
+    stackTrail: StackTrail;
+    context: ParseContextType;
+};
+export declare const toServerV3: ({ server, stackTrail, context }: ToServerV3Args) => OasServer;

package/script/parse/v3-2/server/toServerV3.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toServerV3 = exports.toOptionalServersV3 = exports.toServersV3 = void 0;
+const Server_js_1 = require("../../../oas/server/Server.js");
+const toSpecificationExtensionsV3_js_1 = require("../specificationExtensions/toSpecificationExtensionsV3.js");
+const toServerVariableV3_js_1 = require("../serverVariable/toServerVariableV3.js");
+const toServersV3 = ({ servers, stackTrail, context }) => {
+    return servers.map((server, index) => {
+        return stackTrail.trace(server.url ?? index, st => (0, exports.toServerV3)({ server, stackTrail: st, context }));
+    });
+};
+exports.toServersV3 = toServersV3;
+const toOptionalServersV3 = ({ servers, stackTrail, context }) => {
+    if (!servers) {
+        return undefined;
+    }
+    return (0, exports.toServersV3)({ servers, stackTrail, context });
+};
+exports.toOptionalServersV3 = toOptionalServersV3;
+const toServerV3 = ({ server, stackTrail, context }) => {
+    const { description, name, url, variables, ...skipped } = server;
+    const extensionFields = (0, toSpecificationExtensionsV3_js_1.toSpecificationExtensionsV3)({
+        skipped,
+        parent: server,
+        context,
+        stackTrail,
+        parentType: 'server'
+    });
+    return new Server_js_1.OasServer({
+        description,
+        name,
+        url,
+        variables: (0, toServerVariableV3_js_1.toOptionalServerVariablesV3)({ serverVariables: variables, stackTrail, context }),
+        extensionFields
+    });
+};
+exports.toServerV3 = toServerV3;

package/script/parse/v3-2/serverVariable/toServerVariableV3.d.ts

@@ -0,0 +1,22 @@
+import type { ParseContextType } from '../../../context/parseTypes.js';
+import type { OpenAPIV3 } from 'openapi-types';
+import { OasServerVariable } from '../../../oas/serverVariable/ServerVariable.js';
+import type { StackTrail } from '../../../context/StackTrail.js';
+export type ToServerVariablesV3Args = {
+    serverVariables: Record<string, OpenAPIV3.ServerVariableObject>;
+    stackTrail: StackTrail;
+    context: ParseContextType;
+};
+export declare const toServerVariablesV3: ({ serverVariables, stackTrail, context }: ToServerVariablesV3Args) => Record<string, OasServerVariable>;
+export type ToOptionalServerVariablesV3Args = {
+    serverVariables: Record<string, OpenAPIV3.ServerVariableObject> | undefined;
+    stackTrail: StackTrail;
+    context: ParseContextType;
+};
+export declare const toOptionalServerVariablesV3: ({ serverVariables, stackTrail, context }: ToOptionalServerVariablesV3Args) => Record<string, OasServerVariable> | undefined;
+export type ToServerVariableV3Args = {
+    serverVariable: OpenAPIV3.ServerVariableObject;
+    stackTrail: StackTrail;
+    context: ParseContextType;
+};
+export declare const toServerVariableV3: ({ serverVariable, stackTrail, context }: ToServerVariableV3Args) => OasServerVariable;

package/script/parse/v3-2/serverVariable/toServerVariableV3.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toServerVariableV3 = exports.toOptionalServerVariablesV3 = exports.toServerVariablesV3 = void 0;
+const toSpecificationExtensionsV3_js_1 = require("../specificationExtensions/toSpecificationExtensionsV3.js");
+const ServerVariable_js_1 = require("../../../oas/serverVariable/ServerVariable.js");
+const toServerVariablesV3 = ({ serverVariables, stackTrail, context }) => {
+    return Object.fromEntries(Object.entries(serverVariables).map(([key, serverVariable]) => [
+        key,
+        (0, exports.toServerVariableV3)({ serverVariable, stackTrail, context })
+    ]));
+};
+exports.toServerVariablesV3 = toServerVariablesV3;
+const toOptionalServerVariablesV3 = ({ serverVariables, stackTrail, context }) => {
+    if (!serverVariables) {
+        return undefined;
+    }
+    return (0, exports.toServerVariablesV3)({ serverVariables, stackTrail, context });
+};
+exports.toOptionalServerVariablesV3 = toOptionalServerVariablesV3;
+const toServerVariableV3 = ({ serverVariable, stackTrail, context }) => {
+    const { description, default: defaultValue, enum: enums, ...skipped } = serverVariable;
+    const extensionFields = (0, toSpecificationExtensionsV3_js_1.toSpecificationExtensionsV3)({
+        skipped,
+        parent: serverVariable,
+        context,
+        stackTrail,
+        parentType: 'serverVariable'
+    });
+    return new ServerVariable_js_1.OasServerVariable({
+        description,
+        default: defaultValue,
+        enums,
+        extensionFields
+    });
+};
+exports.toServerVariableV3 = toServerVariableV3;

package/script/parse/v3-2/specificationExtensions/toSpecificationExtensionsV3.d.ts

@@ -0,0 +1,14 @@
+import type { ParseContextType } from '../../../context/parseTypes.js';
+import type { StackTrail } from '../../../context/StackTrail.js';
+export type ToSpecificationExtensionsV3Args = {
+    skipped: Record<string, unknown>;
+    parent: unknown;
+    parentType: string;
+    stackTrail: StackTrail;
+    context: ParseContextType;
+};
+export declare const toSpecificationExtensionsV3: ({ skipped: s, parent, parentType, stackTrail, context }: ToSpecificationExtensionsV3Args) => Record<string, unknown> | undefined;
+export declare const extractExtensions: (item: Record<string, unknown>) => {
+    skipped: Record<string, unknown> | undefined;
+    extensionFields: Record<string, unknown> | undefined;
+};

package/script/parse/v3-2/specificationExtensions/toSpecificationExtensionsV3.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractExtensions = exports.toSpecificationExtensionsV3 = void 0;
+const isEmpty_js_1 = require("../../../helpers/isEmpty.js");
+const toSpecificationExtensionsV3 = ({ skipped: s, parent, parentType, stackTrail, context }) => {
+    const { skipped, extensionFields } = (0, exports.extractExtensions)(s);
+    if (skipped) {
+        context.logSkippedFields({ skipped, parent, stackTrail, parentType });
+    }
+    return extensionFields;
+};
+exports.toSpecificationExtensionsV3 = toSpecificationExtensionsV3;
+const extractExtensions = (item) => {
+    const entries = Object.entries(item);
+    const skipped = {};
+    const extensionFields = {};
+    for (const [key, value] of entries) {
+        if (!key.startsWith('x-')) {
+            skipped[key] = value;
+        }
+        else {
+            extensionFields[key] = value;
+        }
+    }
+    return {
+        skipped: (0, isEmpty_js_1.isEmpty)(skipped) ? undefined : skipped,
+        extensionFields: (0, isEmpty_js_1.isEmpty)(extensionFields) ? undefined : extensionFields
+    };
+};
+exports.extractExtensions = extractExtensions;

package/script/parse/v3-2/string/toString.d.ts

@@ -0,0 +1,146 @@
+import type { OpenAPIV3 } from 'openapi-types';
+import type { ParseContextType } from '../../../context/parseTypes.js';
+import { OasString } from '../../../oas/string/String.js';
+import type { StackTrail } from '../../../context/StackTrail.js';
+/**
+ * Arguments for transforming an OpenAPI string schema into OAS representation.
+ */
+export type ToStringArgs = {
+    /** The OpenAPI v3 schema object to transform (must be type 'string') */
+    value: OpenAPIV3.SchemaObject;
+    /** The stack trail for tracing */
+    stackTrail: StackTrail;
+    /** Parse context providing utilities and tracing capabilities */
+    context: ParseContextType;
+};
+/**
+ * Transforms an OpenAPI v3 string schema object into an internal OAS string representation.
+ *
+ * This function processes OpenAPI string schemas by extracting and parsing nullable values,
+ * examples, enumerations, and default values. It handles the complete transformation from
+ * raw OpenAPI JSON to the SKMTC internal string representation with proper validation
+ * of string formats and constraints.
+ *
+ * The transformation follows a pipeline approach:
+ * 1. Parse nullable flag and extract base value
+ * 2. Parse example values with nullable support
+ * 3. Parse enumeration constraints
+ * 4. Parse default values
+ * 5. Create final OasString instance with format validation
+ *
+ * @param args - Transformation arguments
+ * @param args.context - Parse context providing utilities and tracing
+ * @param args.value - The OpenAPI v3 string schema object to transform
+ * @returns Transformed OAS string object with parsed properties
+ *
+ * @example Basic string transformation
+ * ```typescript
+ * import { toString } from '@skmtc/core';
+ *
+ * const openApiString = {
+ *   type: 'string',
+ *   format: 'email',
+ *   maxLength: 255,
+ *   pattern: '^[\\w.-]+@[\\w.-]+\\.[a-zA-Z]{2,}$'
+ * };
+ *
+ * const oasString = toString({
+ *   context: parseContext,
+ *   value: openApiString
+ * });
+ *
+ * console.log(oasString.format); // 'email'
+ * console.log(oasString.maxLength); // 255
+ * ```
+ *
+ * @example String with nullable and enums
+ * ```typescript
+ * const statusString = {
+ *   type: 'string',
+ *   nullable: true,
+ *   enum: ['active', 'inactive', 'pending', null],
+ *   default: 'active',
+ *   example: 'pending'
+ * };
+ *
+ * const oasString = toString({
+ *   context: parseContext,
+ *   value: statusString
+ * });
+ *
+ * console.log(oasString.nullable); // true
+ * console.log(oasString.enums); // ['active', 'inactive', 'pending', null]
+ * ```
+ */
+export declare const toString: ({ context, value, stackTrail }: ToStringArgs) => OasString;
+type ToParsedStringArgs<Nullable extends boolean | undefined> = {
+    value: Omit<OpenAPIV3.SchemaObject, 'nullable' | 'example' | 'enums' | 'default'>;
+    context: ParseContextType;
+    nullable: Nullable;
+    example: Nullable extends true ? string | null | undefined : string | undefined;
+    enums: Nullable extends true ? (string | null)[] | undefined : string[] | undefined;
+    defaultValue: Nullable extends true ? string | null | undefined : string | undefined;
+    stackTrail: StackTrail;
+};
+/**
+ * Creates an OAS string instance from pre-parsed string schema components.
+ *
+ * This function is the final step in the string transformation pipeline, taking
+ * already-parsed nullable, example, enum, and default values and combining them
+ * with the remaining string properties to create the complete OasString instance.
+ *
+ * The function handles format validation against known OpenAPI string formats,
+ * length constraints parsing, pattern validation, and specification extension
+ * processing. It logs warnings for unrecognized formats while still preserving
+ * them in the output.
+ *
+ * @template Nullable - Boolean type indicating if the string can be null
+ * @param args - Pre-parsed string components
+ * @param args.context - Parse context for tracing and issue logging
+ * @param args.nullable - Parsed nullable flag
+ * @param args.example - Parsed example value (type-safe with nullable)
+ * @param args.enums - Parsed enumeration constraints (type-safe with nullable)
+ * @param args.defaultValue - Parsed default value (type-safe with nullable)
+ * @param args.value - OpenAPI string object without parsed fields
+ * @returns Complete OAS string instance with all properties and validation
+ *
+ * @example Date-time string with validation
+ * ```typescript
+ * const dateTimeString = toParsedString({
+ *   context: parseContext,
+ *   nullable: false,
+ *   example: '2023-12-25T10:00:00Z',
+ *   enums: undefined,
+ *   defaultValue: undefined,
+ *   value: {
+ *     type: 'string',
+ *     format: 'date-time',
+ *     title: 'Event Date',
+ *     description: 'When the event occurs'
+ *   }
+ * });
+ *
+ * console.log(dateTimeString.format); // 'date-time'
+ * ```
+ *
+ * @example String with custom format (generates warning)
+ * ```typescript
+ * const customFormatString = toParsedString({
+ *   context: parseContext,
+ *   nullable: false,
+ *   example: 'ABC123',
+ *   enums: undefined,
+ *   defaultValue: undefined,
+ *   value: {
+ *     type: 'string',
+ *     format: 'custom-id', // Unknown format, will log warning
+ *     pattern: '^[A-Z]{3}[0-9]{3}$'
+ *   }
+ * });
+ *
+ * // Logs: "Unexpected format: custom-id"
+ * console.log(customFormatString.format); // 'custom-id' (still preserved)
+ * ```
+ */
+export declare const toParsedString: <Nullable extends boolean | undefined>({ context, nullable, example, enums, defaultValue, value, stackTrail }: ToParsedStringArgs<Nullable>) => OasString<Nullable>;
+export {};