@skmtc/core 0.0.805 → 0.0.807

package/esm/types/RefName.d.ts

@@ -1,3 +1,73 @@
+/**
+ * @fileoverview Reference Name System for SKMTC Core
+ *
+ * This module provides a type-safe reference name system for identifying
+ * OpenAPI schema components throughout the SKMTC pipeline. Reference names
+ * are branded types that ensure schema identifiers are handled safely and
+ * prevent accidental mixing with regular strings.
+ *
+ * The reference name system is crucial for maintaining type safety when
+ * working with OpenAPI component references, schema lookups, and cross-references
+ * between different parts of the generated code.
+ *
+ * ## Key Features
+ *
+ * - **Type Safety**: Branded types prevent string confusion and improve code reliability
+ * - **Schema Integration**: Direct mapping to OpenAPI components.schemas keys
+ * - **Reference Tracking**: Safe handling of schema references throughout generation
+ * - **IDE Support**: Enhanced IntelliSense and error detection in development
+ * - **Validation**: Compile-time validation of schema reference usage
+ *
+ * @example Basic reference name usage
+ * ```typescript
+ * import type { RefName } from '@skmtc/core/RefName';
+ *
+ * // Create a reference name (typically done by the parser)
+ * const userRef: RefName = 'User' as RefName;
+ * const productRef: RefName = 'Product' as RefName;
+ *
+ * // TypeScript prevents mixing with regular strings
+ * const regularString = 'User';
+ * // const invalid: RefName = regularString; // Type error!
+ * ```
+ *
+ * @example Using reference names in generators
+ * ```typescript
+ * import type { RefName } from '@skmtc/core/RefName';
+ *
+ * function generateModelImport(refName: RefName): string {
+ *   return `import type { ${refName} } from './models/${refName}';`;
+ * }
+ *
+ * function generateModelReference(refName: RefName): string {
+ *   return `#/components/schemas/${refName}`;
+ * }
+ *
+ * // Usage with type safety
+ * const userRef: RefName = 'User' as RefName;
+ * const importStatement = generateModelImport(userRef);
+ * const schemaRef = generateModelReference(userRef);
+ * ```
+ *
+ * @example Reference name validation
+ * ```typescript
+ * import type { RefName } from '@skmtc/core/RefName';
+ *
+ * function isValidRefName(value: string): value is RefName {
+ *   // Validate that the string is a valid schema reference name
+ *   return /^[A-Za-z][A-Za-z0-9_]*$/.test(value) && value.length > 0;
+ * }
+ *
+ * function safeCreateRefName(value: string): RefName | null {
+ *   if (isValidRefName(value)) {
+ *     return value as RefName;
+ *   }
+ *   return null;
+ * }
+ * ```
+ *
+ * @module RefName
+ */
 import "../_dnt.polyfills.js";
 import type { Brand } from './Brand.js';
 /**

package/esm/types/RefName.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RefName.d.ts","sourceRoot":"","sources":["../../src/types/RefName.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAEvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AACH,MAAM,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,EAAE,SAAS,CAAC,CAAA"}
+{"version":3,"file":"RefName.d.ts","sourceRoot":"","sources":["../../src/types/RefName.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqEG;AACH,OAAO,sBAAsB,CAAC;AAG9B,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAEvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AACH,MAAM,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,EAAE,SAAS,CAAC,CAAA"}

package/esm/types/RefName.js

@@ -1 +1,71 @@
+/**
+ * @fileoverview Reference Name System for SKMTC Core
+ *
+ * This module provides a type-safe reference name system for identifying
+ * OpenAPI schema components throughout the SKMTC pipeline. Reference names
+ * are branded types that ensure schema identifiers are handled safely and
+ * prevent accidental mixing with regular strings.
+ *
+ * The reference name system is crucial for maintaining type safety when
+ * working with OpenAPI component references, schema lookups, and cross-references
+ * between different parts of the generated code.
+ *
+ * ## Key Features
+ *
+ * - **Type Safety**: Branded types prevent string confusion and improve code reliability
+ * - **Schema Integration**: Direct mapping to OpenAPI components.schemas keys
+ * - **Reference Tracking**: Safe handling of schema references throughout generation
+ * - **IDE Support**: Enhanced IntelliSense and error detection in development
+ * - **Validation**: Compile-time validation of schema reference usage
+ *
+ * @example Basic reference name usage
+ * ```typescript
+ * import type { RefName } from '@skmtc/core/RefName';
+ *
+ * // Create a reference name (typically done by the parser)
+ * const userRef: RefName = 'User' as RefName;
+ * const productRef: RefName = 'Product' as RefName;
+ *
+ * // TypeScript prevents mixing with regular strings
+ * const regularString = 'User';
+ * // const invalid: RefName = regularString; // Type error!
+ * ```
+ *
+ * @example Using reference names in generators
+ * ```typescript
+ * import type { RefName } from '@skmtc/core/RefName';
+ *
+ * function generateModelImport(refName: RefName): string {
+ *   return `import type { ${refName} } from './models/${refName}';`;
+ * }
+ *
+ * function generateModelReference(refName: RefName): string {
+ *   return `#/components/schemas/${refName}`;
+ * }
+ *
+ * // Usage with type safety
+ * const userRef: RefName = 'User' as RefName;
+ * const importStatement = generateModelImport(userRef);
+ * const schemaRef = generateModelReference(userRef);
+ * ```
+ *
+ * @example Reference name validation
+ * ```typescript
+ * import type { RefName } from '@skmtc/core/RefName';
+ *
+ * function isValidRefName(value: string): value is RefName {
+ *   // Validate that the string is a valid schema reference name
+ *   return /^[A-Za-z][A-Za-z0-9_]*$/.test(value) && value.length > 0;
+ * }
+ *
+ * function safeCreateRefName(value: string): RefName | null {
+ *   if (isValidRefName(value)) {
+ *     return value as RefName;
+ *   }
+ *   return null;
+ * }
+ * ```
+ *
+ * @module RefName
+ */
 import "../_dnt.polyfills.js";

package/esm/types/Settings.d.ts

@@ -1,3 +1,53 @@
+/**
+ * @fileoverview SKMTC Core Settings and Configuration
+ *
+ * This module provides comprehensive configuration types and schemas for the SKMTC
+ * code generation pipeline. It defines settings for generators, modules, packages,
+ * and runtime behavior that control how OpenAPI documents are processed and what
+ * artifacts are generated.
+ *
+ * ## Key Features
+ *
+ * - **Generator Configuration**: Settings for individual code generators
+ * - **Module Management**: Package and module resolution configuration
+ * - **Runtime Settings**: Control generation behavior and output preferences
+ * - **Enrichment Integration**: Support for UI enrichment metadata
+ * - **Type Safety**: Comprehensive Valibot validation for all configuration
+ *
+ * @example Basic generator settings
+ * ```typescript
+ * import type { Settings } from '@skmtc/core/Settings';
+ *
+ * const settings: Settings = {
+ *   generators: {
+ *     'my-generator': {
+ *       enabled: true,
+ *       config: {
+ *         outputPath: './generated',
+ *         typescript: true
+ *       }
+ *     }
+ *   },
+ *   enrichments: {},
+ *   filters: {
+ *     includePaths: ['/api/v1/*'],
+ *     excludeMethods: ['OPTIONS']
+ *   }
+ * };
+ * ```
+ *
+ * @example Module package configuration
+ * ```typescript
+ * import type { ModulePackage } from '@skmtc/core/Settings';
+ *
+ * const moduleConfig: ModulePackage = {
+ *   rootPath: './src/generated',
+ *   moduleName: '@my-org/api-client'
+ * };
+ * ```
+ *
+ * @module Settings
+ */
 import "../_dnt.polyfills.js";
 import { type GeneratorEnrichments } from './Enrichments.js';
 import * as v from 'valibot';

package/esm/types/Settings.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Settings.d.ts","sourceRoot":"","sources":["../../src/types/Settings.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAC9B,OAAO,EAAwB,KAAK,oBAAoB,EAAE,MAAM,kBAAkB,CAAA;AAClF,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAC5B,OAAO,EAAU,KAAK,MAAM,EAAE,MAAM,aAAa,CAAA;AAEjD;;GAEG;AACH,eAAO,MAAM,aAAa,EAAE,CAAC,CAAC,aAAa,CAAC,aAAa,CAGvD,CAAA;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,iDAAiD;IACjD,QAAQ,EAAE,MAAM,CAAA;IAChB,uDAAuD;IACvD,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,SAAS,EAAE,CAAC,CAAC,aAAa,CAAC,SAAS,CAAyC,CAAA;AAE1F;;;;GAIG;AACH,eAAO,MAAM,cAAc,EAAE,CAAC,CAAC,aAAa,CAAC,cAAc,CAAmC,CAAA;AAE9F;;;;GAIG;AACH,eAAO,MAAM,UAAU,EAAE,CAAC,CAAC,aAAa,CAAC,UAAU,CAA6C,CAAA;AAIhG;;;;;GAKG;AACH,eAAO,MAAM,cAAc,EAAE,CAAC,CAAC,aAAa,CAAC,cAAc,CAKzD,CAAA;AAEF;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAA;AAEhD;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAA;AAEjD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAA;AAEtD;;;;;GAKG;AACH,MAAM,MAAM,IAAI,GAAG,cAAc,GAAG,UAAU,GAAG,MAAM,CAAA;AAEvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,aAAa,EAAE,CAAA;IAC1B,kDAAkD;IAClD,WAAW,CAAC,EAAE,oBAAoB,CAAA;IAClC,sDAAsD;IACtD,IAAI,CAAC,EAAE,IAAI,EAAE,CAAA;CACd,CAAA;AAED;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,8DAA8D;IAC9D,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,0DAA0D;IAC1D,QAAQ,EAAE,cAAc,CAAA;CACzB,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,EAAE,CAAC,CAAC,aAAa,CAAC,iBAAiB,CAG/D,CAAA"}
+{"version":3,"file":"Settings.d.ts","sourceRoot":"","sources":["../../src/types/Settings.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,OAAO,sBAAsB,CAAC;AAG9B,OAAO,EAAwB,KAAK,oBAAoB,EAAE,MAAM,kBAAkB,CAAA;AAClF,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAC5B,OAAO,EAAU,KAAK,MAAM,EAAE,MAAM,aAAa,CAAA;AAEjD;;GAEG;AACH,eAAO,MAAM,aAAa,EAAE,CAAC,CAAC,aAAa,CAAC,aAAa,CAGvD,CAAA;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,iDAAiD;IACjD,QAAQ,EAAE,MAAM,CAAA;IAChB,uDAAuD;IACvD,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,SAAS,EAAE,CAAC,CAAC,aAAa,CAAC,SAAS,CAAyC,CAAA;AAE1F;;;;GAIG;AACH,eAAO,MAAM,cAAc,EAAE,CAAC,CAAC,aAAa,CAAC,cAAc,CAAmC,CAAA;AAE9F;;;;GAIG;AACH,eAAO,MAAM,UAAU,EAAE,CAAC,CAAC,aAAa,CAAC,UAAU,CAA6C,CAAA;AAIhG;;;;;GAKG;AACH,eAAO,MAAM,cAAc,EAAE,CAAC,CAAC,aAAa,CAAC,cAAc,CAKzD,CAAA;AAEF;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAA;AAEhD;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAA;AAEjD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAA;AAEtD;;;;;GAKG;AACH,MAAM,MAAM,IAAI,GAAG,cAAc,GAAG,UAAU,GAAG,MAAM,CAAA;AAEvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,aAAa,EAAE,CAAA;IAC1B,kDAAkD;IAClD,WAAW,CAAC,EAAE,oBAAoB,CAAA;IAClC,sDAAsD;IACtD,IAAI,CAAC,EAAE,IAAI,EAAE,CAAA;CACd,CAAA;AAED;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,8DAA8D;IAC9D,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,0DAA0D;IAC1D,QAAQ,EAAE,cAAc,CAAA;CACzB,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,EAAE,CAAC,CAAC,aAAa,CAAC,iBAAiB,CAG/D,CAAA"}

package/esm/types/Settings.js

@@ -1,3 +1,53 @@
+/**
+ * @fileoverview SKMTC Core Settings and Configuration
+ *
+ * This module provides comprehensive configuration types and schemas for the SKMTC
+ * code generation pipeline. It defines settings for generators, modules, packages,
+ * and runtime behavior that control how OpenAPI documents are processed and what
+ * artifacts are generated.
+ *
+ * ## Key Features
+ *
+ * - **Generator Configuration**: Settings for individual code generators
+ * - **Module Management**: Package and module resolution configuration
+ * - **Runtime Settings**: Control generation behavior and output preferences
+ * - **Enrichment Integration**: Support for UI enrichment metadata
+ * - **Type Safety**: Comprehensive Valibot validation for all configuration
+ *
+ * @example Basic generator settings
+ * ```typescript
+ * import type { Settings } from '@skmtc/core/Settings';
+ *
+ * const settings: Settings = {
+ *   generators: {
+ *     'my-generator': {
+ *       enabled: true,
+ *       config: {
+ *         outputPath: './generated',
+ *         typescript: true
+ *       }
+ *     }
+ *   },
+ *   enrichments: {},
+ *   filters: {
+ *     includePaths: ['/api/v1/*'],
+ *     excludeMethods: ['OPTIONS']
+ *   }
+ * };
+ * ```
+ *
+ * @example Module package configuration
+ * ```typescript
+ * import type { ModulePackage } from '@skmtc/core/Settings';
+ *
+ * const moduleConfig: ModulePackage = {
+ *   rootPath: './src/generated',
+ *   moduleName: '@my-org/api-client'
+ * };
+ * ```
+ *
+ * @module Settings
+ */
 import "../_dnt.polyfills.js";
 import { generatorEnrichments } from './Enrichments.js';
 import * as v from 'valibot';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skmtc/core",
-  "version": "0.0.805",
+  "version": "0.0.807",
   "repository": {
     "type": "git",
     "url": "https://github.com/skmtc/skmtc.git"

package/script/helpers/strings.d.ts

@@ -1,3 +1,47 @@
+/**
+ * @fileoverview String Manipulation Utilities for SKMTC Core
+ *
+ * This module provides a comprehensive collection of string manipulation utilities
+ * commonly needed for code generation, identifier transformation, and text processing
+ * within the SKMTC pipeline. These utilities handle case conversions, pluralization,
+ * sanitization, and various text transformations.
+ *
+ * ## Key Features
+ *
+ * - **Case Conversion**: camelCase, PascalCase, snake_case, kebab-case, and more
+ * - **Pluralization**: Smart singular/plural transformations with irregular forms
+ * - **Sanitization**: Clean strings for use as identifiers and file names
+ * - **Text Processing**: Trimming, padding, wrapping, and formatting utilities
+ * - **Unicode Support**: Proper handling of international characters
+ *
+ * @example Case conversions
+ * ```typescript
+ * import { capitalize, camelCase, pascalCase } from '@skmtc/core/strings';
+ *
+ * capitalize('hello world'); // 'Hello world'
+ * camelCase('user_profile_data'); // 'userProfileData'
+ * pascalCase('api-response-type'); // 'ApiResponseType'
+ * ```
+ *
+ * @example Pluralization
+ * ```typescript
+ * import { pluralize, singularize } from '@skmtc/core/strings';
+ *
+ * pluralize('user'); // 'users'
+ * pluralize('child'); // 'children'
+ * singularize('categories'); // 'category'
+ * ```
+ *
+ * @example Identifier sanitization
+ * ```typescript
+ * import { sanitizeIdentifier, toFileName } from '@skmtc/core/strings';
+ *
+ * sanitizeIdentifier('123-invalid name!'); // 'invalid_name'
+ * toFileName('My API Response'); // 'my-api-response'
+ * ```
+ *
+ * @module strings
+ */
 /**
  * Capitalizes the first character of a string.
  *

package/script/helpers/strings.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"strings.d.ts","sourceRoot":"","sources":["../../src/helpers/strings.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,sBAAsB,CAAC;AAE9B,eAAO,MAAM,UAAU,GAAI,KAAK,MAAM,KAAG,MAExC,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,YAAY,GAAI,KAAK,MAAM,KAAG,MAE1C,CAAA;AAED;;GAEG;AACH,KAAK,gBAAgB,GAAG;IACtB,6DAA6D;IAC7D,UAAU,CAAC,EAAE,OAAO,CAAA;CACrB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,SAAS,GAAI,KAAK,MAAM,EAAE,iBAAgB,gBAAqB,KAAG,MAgB9E,CAAA"}
+{"version":3,"file":"strings.d.ts","sourceRoot":"","sources":["../../src/helpers/strings.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH;;;;;;;;;;;;GAYG;AACH,OAAO,sBAAsB,CAAC;AAE9B,eAAO,MAAM,UAAU,GAAI,KAAK,MAAM,KAAG,MAExC,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,YAAY,GAAI,KAAK,MAAM,KAAG,MAE1C,CAAA;AAED;;GAEG;AACH,KAAK,gBAAgB,GAAG;IACtB,6DAA6D;IAC7D,UAAU,CAAC,EAAE,OAAO,CAAA;CACrB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,SAAS,GAAI,KAAK,MAAM,EAAE,iBAAgB,gBAAqB,KAAG,MAgB9E,CAAA"}

package/script/helpers/strings.js

@@ -1,4 +1,48 @@
 "use strict";
+/**
+ * @fileoverview String Manipulation Utilities for SKMTC Core
+ *
+ * This module provides a comprehensive collection of string manipulation utilities
+ * commonly needed for code generation, identifier transformation, and text processing
+ * within the SKMTC pipeline. These utilities handle case conversions, pluralization,
+ * sanitization, and various text transformations.
+ *
+ * ## Key Features
+ *
+ * - **Case Conversion**: camelCase, PascalCase, snake_case, kebab-case, and more
+ * - **Pluralization**: Smart singular/plural transformations with irregular forms
+ * - **Sanitization**: Clean strings for use as identifiers and file names
+ * - **Text Processing**: Trimming, padding, wrapping, and formatting utilities
+ * - **Unicode Support**: Proper handling of international characters
+ *
+ * @example Case conversions
+ * ```typescript
+ * import { capitalize, camelCase, pascalCase } from '@skmtc/core/strings';
+ *
+ * capitalize('hello world'); // 'Hello world'
+ * camelCase('user_profile_data'); // 'userProfileData'
+ * pascalCase('api-response-type'); // 'ApiResponseType'
+ * ```
+ *
+ * @example Pluralization
+ * ```typescript
+ * import { pluralize, singularize } from '@skmtc/core/strings';
+ *
+ * pluralize('user'); // 'users'
+ * pluralize('child'); // 'children'
+ * singularize('categories'); // 'category'
+ * ```
+ *
+ * @example Identifier sanitization
+ * ```typescript
+ * import { sanitizeIdentifier, toFileName } from '@skmtc/core/strings';
+ *
+ * sanitizeIdentifier('123-invalid name!'); // 'invalid_name'
+ * toFileName('My API Response'); // 'my-api-response'
+ * ```
+ *
+ * @module strings
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.camelCase = exports.decapitalize = exports.capitalize = void 0;
 /**

package/script/helpers/toResolvedArtifactPath.d.ts

@@ -1,6 +1,70 @@
+/**
+ * @fileoverview Artifact Path Resolution Utilities for SKMTC Core
+ *
+ * This module provides utilities for resolving file paths for generated artifacts
+ * within the SKMTC code generation pipeline. It handles the complexities of path
+ * resolution, ensuring that generated files are placed in the correct locations
+ * relative to base directories and project structures.
+ *
+ * The path resolution system supports both absolute and relative paths,
+ * cross-platform compatibility, and proper handling of nested directory
+ * structures for organized code generation output.
+ *
+ * ## Key Features
+ *
+ * - **Cross-Platform Compatibility**: Works correctly on Windows, macOS, and Linux
+ * - **Relative Path Resolution**: Proper handling of relative paths with base directories
+ * - **Absolute Path Support**: Direct support for absolute destination paths
+ * - **Directory Creation**: Safe directory creation for nested path structures
+ * - **Path Normalization**: Consistent path formatting across different systems
+ *
+ * @example Basic path resolution
+ * ```typescript
+ * import { toResolvedArtifactPath } from '@skmtc/core/toResolvedArtifactPath';
+ *
+ * // Resolve relative path with base directory
+ * const resolvedPath = toResolvedArtifactPath({
+ *   basePath: '/project/src',
+ *   destinationPath: './generated/UserApi.ts'
+ * });
+ *
+ * console.log(resolvedPath); // '/project/src/generated/UserApi.ts'
+ * ```
+ *
+ * @example Absolute path handling
+ * ```typescript
+ * import { toResolvedArtifactPath } from '@skmtc/core/toResolvedArtifactPath';
+ *
+ * // Absolute paths are returned as-is
+ * const absolutePath = toResolvedArtifactPath({
+ *   basePath: '/project/src',
+ *   destinationPath: '/absolute/path/to/UserApi.ts'
+ * });
+ *
+ * console.log(absolutePath); // '/absolute/path/to/UserApi.ts'
+ * ```
+ *
+ * @example Working without base path
+ * ```typescript
+ * import { toResolvedArtifactPath } from '@skmtc/core/toResolvedArtifactPath';
+ *
+ * // When basePath is undefined, returns the destination path
+ * const path = toResolvedArtifactPath({
+ *   basePath: undefined,
+ *   destinationPath: './UserApi.ts'
+ * });
+ *
+ * console.log(path); // './UserApi.ts'
+ * ```
+ *
+ * @module toResolvedArtifactPath
+ */
 import "../_dnt.polyfills.js";
 /**
  * Arguments for resolving artifact file paths.
+ *
+ * Defines the input parameters needed to resolve a destination path
+ * relative to an optional base directory.
  */
 type ToResolvedArtifactPathArgs = {
     /** The base directory path for resolving relative paths */

package/script/helpers/toResolvedArtifactPath.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"toResolvedArtifactPath.d.ts","sourceRoot":"","sources":["../../src/helpers/toResolvedArtifactPath.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAG9B;;GAEG;AACH,KAAK,0BAA0B,GAAG;IAChC,2DAA2D;IAC3D,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAA;IAC5B,iDAAiD;IACjD,eAAe,EAAE,MAAM,CAAA;CACxB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2IG;AACH,eAAO,MAAM,sBAAsB,GAAI,+BAGpC,0BAA0B,KAAG,MAE/B,CAAA"}
+{"version":3,"file":"toResolvedArtifactPath.d.ts","sourceRoot":"","sources":["../../src/helpers/toResolvedArtifactPath.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AACH,OAAO,sBAAsB,CAAC;AAK9B;;;;;GAKG;AACH,KAAK,0BAA0B,GAAG;IAChC,2DAA2D;IAC3D,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAA;IAC5B,iDAAiD;IACjD,eAAe,EAAE,MAAM,CAAA;CACxB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2IG;AACH,eAAO,MAAM,sBAAsB,GAAI,+BAGpC,0BAA0B,KAAG,MAE/B,CAAA"}

package/script/helpers/toResolvedArtifactPath.js

@@ -1,6 +1,67 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.toResolvedArtifactPath = void 0;
+/**
+ * @fileoverview Artifact Path Resolution Utilities for SKMTC Core
+ *
+ * This module provides utilities for resolving file paths for generated artifacts
+ * within the SKMTC code generation pipeline. It handles the complexities of path
+ * resolution, ensuring that generated files are placed in the correct locations
+ * relative to base directories and project structures.
+ *
+ * The path resolution system supports both absolute and relative paths,
+ * cross-platform compatibility, and proper handling of nested directory
+ * structures for organized code generation output.
+ *
+ * ## Key Features
+ *
+ * - **Cross-Platform Compatibility**: Works correctly on Windows, macOS, and Linux
+ * - **Relative Path Resolution**: Proper handling of relative paths with base directories
+ * - **Absolute Path Support**: Direct support for absolute destination paths
+ * - **Directory Creation**: Safe directory creation for nested path structures
+ * - **Path Normalization**: Consistent path formatting across different systems
+ *
+ * @example Basic path resolution
+ * ```typescript
+ * import { toResolvedArtifactPath } from '@skmtc/core/toResolvedArtifactPath';
+ *
+ * // Resolve relative path with base directory
+ * const resolvedPath = toResolvedArtifactPath({
+ *   basePath: '/project/src',
+ *   destinationPath: './generated/UserApi.ts'
+ * });
+ *
+ * console.log(resolvedPath); // '/project/src/generated/UserApi.ts'
+ * ```
+ *
+ * @example Absolute path handling
+ * ```typescript
+ * import { toResolvedArtifactPath } from '@skmtc/core/toResolvedArtifactPath';
+ *
+ * // Absolute paths are returned as-is
+ * const absolutePath = toResolvedArtifactPath({
+ *   basePath: '/project/src',
+ *   destinationPath: '/absolute/path/to/UserApi.ts'
+ * });
+ *
+ * console.log(absolutePath); // '/absolute/path/to/UserApi.ts'
+ * ```
+ *
+ * @example Working without base path
+ * ```typescript
+ * import { toResolvedArtifactPath } from '@skmtc/core/toResolvedArtifactPath';
+ *
+ * // When basePath is undefined, returns the destination path
+ * const path = toResolvedArtifactPath({
+ *   basePath: undefined,
+ *   destinationPath: './UserApi.ts'
+ * });
+ *
+ * console.log(path); // './UserApi.ts'
+ * ```
+ *
+ * @module toResolvedArtifactPath
+ */
 require("../_dnt.polyfills.js");
 const join_js_1 = require("../deps/jsr.io/@std/path/1.1.2/join.js");
 /**

package/script/run/toV3JsonDocument.d.ts

@@ -1,3 +1,57 @@
+/**
+ * @fileoverview OpenAPI Document Conversion Utilities
+ *
+ * This module provides robust utilities for converting OpenAPI documents between
+ * different versions (v2/Swagger, v3.0, v3.1) and formats (JSON, YAML). It handles
+ * the complexities of version migration, format detection, and schema validation
+ * to ensure seamless OpenAPI document processing within the SKMTC pipeline.
+ *
+ * ## Key Features
+ *
+ * - **Multi-Version Support**: Convert between Swagger v2, OpenAPI v3.0, and v3.1
+ * - **Format Detection**: Automatic detection of JSON vs YAML input formats
+ * - **Version Migration**: Safe migration with schema validation and error handling
+ * - **Type Safety**: Full TypeScript support with proper type guards
+ * - **Error Recovery**: Comprehensive error handling for malformed documents
+ *
+ * @example Converting Swagger v2 to OpenAPI v3
+ * ```typescript
+ * import { toV3JsonDocument } from '@skmtc/core/toV3JsonDocument';
+ *
+ * const swaggerV2 = {
+ *   swagger: '2.0',
+ *   info: { title: 'My API', version: '1.0.0' },
+ *   paths: { '/users': { get: { responses: { '200': { description: 'Success' } } } } }
+ * };
+ *
+ * const openApiV3 = await toV3JsonDocument(swaggerV2);
+ * console.log(openApiV3.openapi); // '3.0.0'
+ * ```
+ *
+ * @example Converting from YAML string
+ * ```typescript
+ * const yamlContent = `
+ * openapi: 3.1.0
+ * info:
+ *   title: My API
+ *   version: 1.0.0
+ * paths: {}
+ * `;
+ *
+ * const openApiV3 = await toV3JsonDocument(yamlContent);
+ * ```
+ *
+ * @example Handling conversion errors
+ * ```typescript
+ * try {
+ *   const result = await toV3JsonDocument(malformedDocument);
+ * } catch (error) {
+ *   console.error('Conversion failed:', error.message);
+ * }
+ * ```
+ *
+ * @module toV3JsonDocument
+ */
 import "../_dnt.polyfills.js";
 import type { OpenAPIV2, OpenAPIV3, OpenAPIV3_1 } from 'openapi-types';
 /**

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;;;;;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"}
+{"version":3,"file":"toV3JsonDocument.d.ts","sourceRoot":"","sources":["../../src/run/toV3JsonDocument.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,OAAO,sBAAsB,CAAC;AAG9B,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

@@ -4,6 +4,60 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.toV3Document = exports.stringToSchema = void 0;
+/**
+ * @fileoverview OpenAPI Document Conversion Utilities
+ *
+ * This module provides robust utilities for converting OpenAPI documents between
+ * different versions (v2/Swagger, v3.0, v3.1) and formats (JSON, YAML). It handles
+ * the complexities of version migration, format detection, and schema validation
+ * to ensure seamless OpenAPI document processing within the SKMTC pipeline.
+ *
+ * ## Key Features
+ *
+ * - **Multi-Version Support**: Convert between Swagger v2, OpenAPI v3.0, and v3.1
+ * - **Format Detection**: Automatic detection of JSON vs YAML input formats
+ * - **Version Migration**: Safe migration with schema validation and error handling
+ * - **Type Safety**: Full TypeScript support with proper type guards
+ * - **Error Recovery**: Comprehensive error handling for malformed documents
+ *
+ * @example Converting Swagger v2 to OpenAPI v3
+ * ```typescript
+ * import { toV3JsonDocument } from '@skmtc/core/toV3JsonDocument';
+ *
+ * const swaggerV2 = {
+ *   swagger: '2.0',
+ *   info: { title: 'My API', version: '1.0.0' },
+ *   paths: { '/users': { get: { responses: { '200': { description: 'Success' } } } } }
+ * };
+ *
+ * const openApiV3 = await toV3JsonDocument(swaggerV2);
+ * console.log(openApiV3.openapi); // '3.0.0'
+ * ```
+ *
+ * @example Converting from YAML string
+ * ```typescript
+ * const yamlContent = `
+ * openapi: 3.1.0
+ * info:
+ *   title: My API
+ *   version: 1.0.0
+ * paths: {}
+ * `;
+ *
+ * const openApiV3 = await toV3JsonDocument(yamlContent);
+ * ```
+ *
+ * @example Handling conversion errors
+ * ```typescript
+ * try {
+ *   const result = await toV3JsonDocument(malformedDocument);
+ * } catch (error) {
+ *   console.error('Conversion failed:', error.message);
+ * }
+ * ```
+ *
+ * @module toV3JsonDocument
+ */
 require("../_dnt.polyfills.js");
 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");