@skmtc/core 0.0.782 → 0.0.783

package/script/mod.d.ts

@@ -1,3 +1,69 @@
+/**
+ * @module SKMTC Core
+ *
+ * SKMTC (Schema Kit Mapping & Type Conversion) is a powerful TypeScript/Deno library
+ * for processing OpenAPI v3 documents and generating code artifacts. It provides a
+ * comprehensive three-phase pipeline for parsing, generating, and rendering OpenAPI
+ * schemas into various output formats.
+ *
+ * ## Quick Start
+ *
+ * ```typescript
+ * import { toArtifacts } from '@skmtc/core';
+ *
+ * const result = await toArtifacts({
+ *   traceId: 'my-trace',
+ *   spanId: 'my-span',
+ *   documentObject: openApiDoc,
+ *   settings: clientSettings,
+ *   toGeneratorConfigMap: () => generatorMap,
+ *   startAt: Date.now(),
+ *   silent: false
+ * });
+ *
+ * console.log(result.artifacts); // Generated code files
+ * console.log(result.manifest);  // Generation metadata
+ * ```
+ *
+ * ## Architecture
+ *
+ * The library follows a three-phase pipeline:
+ * - **Parse Phase**: Converts OpenAPI v3 JSON into internal OAS objects
+ * - **Generate Phase**: Transforms OAS objects into generator artifacts
+ * - **Render Phase**: Renders artifacts to formatted files
+ *
+ * ## Key Components
+ *
+ * - {@link CoreContext} - Main orchestration class for the pipeline
+ * - {@link toArtifacts} - Primary transformation function
+ * - {@link ContentBase} - Base class for creating generators
+ * - {@link ModelBase} and {@link OperationBase} - DSL building blocks
+ * - {@link List} - Powerful string manipulation and code generation utility
+ *
+ * ## Type System
+ *
+ * The library provides comprehensive TypeScript types for OpenAPI schemas,
+ * generator configurations, and output artifacts. All major types are
+ * validated using Valibot schemas for runtime safety.
+ *
+ * @example Basic Usage
+ * ```typescript
+ * import { CoreContext } from '@skmtc/core';
+ *
+ * const context = new CoreContext({
+ *   spanId: 'my-span',
+ *   silent: false
+ * });
+ *
+ * const result = await context.toArtifacts({
+ *   documentObject: myOpenApiDoc,
+ *   settings: mySettings,
+ *   toGeneratorConfigMap: () => myGenerators,
+ *   prettier: prettierConfig,
+ *   silent: false
+ * });
+ * ```
+ */
 import "./_dnt.polyfills.js";
 export * from './app/validate.js';
 export * from './context/CoreContext.js';

package/script/mod.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../src/mod.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAC7B,cAAc,mBAAmB,CAAA;AACjC,cAAc,0BAA0B,CAAA;AACxC,cAAc,8BAA8B,CAAA;AAC5C,cAAc,2BAA2B,CAAA;AACzC,cAAc,oBAAoB,CAAA;AAClC,cAAc,sBAAsB,CAAA;AACpC,cAAc,0BAA0B,CAAA;AACxC,cAAc,qBAAqB,CAAA;AACnC,cAAc,qBAAqB,CAAA;AACnC,cAAc,6BAA6B,CAAA;AAC3C,cAAc,qBAAqB,CAAA;AACnC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,mBAAmB,CAAA;AACjC,cAAc,0BAA0B,CAAA;AACxC,cAAc,4BAA4B,CAAA;AAC1C,cAAc,4BAA4B,CAAA;AAC1C,cAAc,6BAA6B,CAAA;AAC3C,cAAc,sBAAsB,CAAA;AACpC,cAAc,kCAAkC,CAAA;AAChD,cAAc,oCAAoC,CAAA;AAClD,cAAc,oCAAoC,CAAA;AAClD,cAAc,qCAAqC,CAAA;AACnD,cAAc,0BAA0B,CAAA;AACxC,cAAc,qBAAqB,CAAA;AACnC,cAAc,8BAA8B,CAAA;AAC5C,cAAc,2BAA2B,CAAA;AACzC,cAAc,8BAA8B,CAAA;AAC5C,cAAc,sBAAsB,CAAA;AACpC,cAAc,yBAAyB,CAAA;AACvC,cAAc,qBAAqB,CAAA;AACnC,cAAc,qBAAqB,CAAA;AACnC,cAAc,sBAAsB,CAAA;AACpC,cAAc,8BAA8B,CAAA;AAC5C,cAAc,qCAAqC,CAAA;AACnD,cAAc,sBAAsB,CAAA;AACpC,cAAc,0BAA0B,CAAA;AACxC,cAAc,gCAAgC,CAAA;AAC9C,cAAc,sCAAsC,CAAA;AACpD,cAAc,4BAA4B,CAAA;AAC1C,cAAc,oBAAoB,CAAA;AAClC,cAAc,0BAA0B,CAAA;AACxC,cAAc,wBAAwB,CAAA;AACtC,cAAc,wBAAwB,CAAA;AACtC,cAAc,8BAA8B,CAAA;AAC5C,cAAc,8BAA8B,CAAA;AAC5C,cAAc,kBAAkB,CAAA;AAChC,cAAc,kCAAkC,CAAA;AAChD,cAAc,4BAA4B,CAAA;AAC1C,cAAc,wBAAwB,CAAA;AACtC,cAAc,wBAAwB,CAAA;AACtC,cAAc,kBAAkB,CAAA;AAChC,cAAc,sBAAsB,CAAA;AACpC,cAAc,0BAA0B,CAAA;AACxC,cAAc,oBAAoB,CAAA;AAClC,cAAc,sBAAsB,CAAA;AACpC,cAAc,2BAA2B,CAAA;AACzC,cAAc,wBAAwB,CAAA;AACtC,cAAc,qBAAqB,CAAA;AACnC,cAAc,8BAA8B,CAAA;AAC5C,cAAc,wBAAwB,CAAA;AACtC,cAAc,2BAA2B,CAAA;AACzC,cAAc,0BAA0B,CAAA;AACxC,cAAc,0BAA0B,CAAA;AACxC,cAAc,qBAAqB,CAAA;AACnC,cAAc,mBAAmB,CAAA;AACjC,cAAc,sBAAsB,CAAA;AACpC,cAAc,yBAAyB,CAAA;AACvC,cAAc,2BAA2B,CAAA;AACzC,cAAc,oBAAoB,CAAA;AAClC,cAAc,oBAAoB,CAAA;AAClC,cAAc,qBAAqB,CAAA;AACnC,cAAc,uBAAuB,CAAA;AACrC,cAAc,mCAAmC,CAAA;AACjD,cAAc,6BAA6B,CAAA;AAC3C,cAAc,2BAA2B,CAAA;AACzC,cAAc,sBAAsB,CAAA;AACpC,cAAc,4BAA4B,CAAA;AAC1C,cAAc,uCAAuC,CAAA;AACrD,cAAc,gCAAgC,CAAA;AAC9C,cAAc,8BAA8B,CAAA;AAC5C,cAAc,iCAAiC,CAAA"}
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../src/mod.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiEG;AACH,OAAO,qBAAqB,CAAC;AAG7B,cAAc,mBAAmB,CAAA;AACjC,cAAc,0BAA0B,CAAA;AACxC,cAAc,8BAA8B,CAAA;AAC5C,cAAc,2BAA2B,CAAA;AACzC,cAAc,oBAAoB,CAAA;AAClC,cAAc,sBAAsB,CAAA;AACpC,cAAc,0BAA0B,CAAA;AACxC,cAAc,qBAAqB,CAAA;AACnC,cAAc,qBAAqB,CAAA;AACnC,cAAc,6BAA6B,CAAA;AAC3C,cAAc,qBAAqB,CAAA;AACnC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,mBAAmB,CAAA;AACjC,cAAc,0BAA0B,CAAA;AACxC,cAAc,4BAA4B,CAAA;AAC1C,cAAc,4BAA4B,CAAA;AAC1C,cAAc,6BAA6B,CAAA;AAC3C,cAAc,sBAAsB,CAAA;AACpC,cAAc,kCAAkC,CAAA;AAChD,cAAc,oCAAoC,CAAA;AAClD,cAAc,oCAAoC,CAAA;AAClD,cAAc,qCAAqC,CAAA;AACnD,cAAc,0BAA0B,CAAA;AACxC,cAAc,qBAAqB,CAAA;AACnC,cAAc,8BAA8B,CAAA;AAC5C,cAAc,2BAA2B,CAAA;AACzC,cAAc,8BAA8B,CAAA;AAC5C,cAAc,sBAAsB,CAAA;AACpC,cAAc,yBAAyB,CAAA;AACvC,cAAc,qBAAqB,CAAA;AACnC,cAAc,qBAAqB,CAAA;AACnC,cAAc,sBAAsB,CAAA;AACpC,cAAc,8BAA8B,CAAA;AAC5C,cAAc,qCAAqC,CAAA;AACnD,cAAc,sBAAsB,CAAA;AACpC,cAAc,0BAA0B,CAAA;AACxC,cAAc,gCAAgC,CAAA;AAC9C,cAAc,sCAAsC,CAAA;AACpD,cAAc,4BAA4B,CAAA;AAC1C,cAAc,oBAAoB,CAAA;AAClC,cAAc,0BAA0B,CAAA;AACxC,cAAc,wBAAwB,CAAA;AACtC,cAAc,wBAAwB,CAAA;AACtC,cAAc,8BAA8B,CAAA;AAC5C,cAAc,8BAA8B,CAAA;AAC5C,cAAc,kBAAkB,CAAA;AAChC,cAAc,kCAAkC,CAAA;AAChD,cAAc,4BAA4B,CAAA;AAC1C,cAAc,wBAAwB,CAAA;AACtC,cAAc,wBAAwB,CAAA;AACtC,cAAc,kBAAkB,CAAA;AAChC,cAAc,sBAAsB,CAAA;AACpC,cAAc,0BAA0B,CAAA;AACxC,cAAc,oBAAoB,CAAA;AAClC,cAAc,sBAAsB,CAAA;AACpC,cAAc,2BAA2B,CAAA;AACzC,cAAc,wBAAwB,CAAA;AACtC,cAAc,qBAAqB,CAAA;AACnC,cAAc,8BAA8B,CAAA;AAC5C,cAAc,wBAAwB,CAAA;AACtC,cAAc,2BAA2B,CAAA;AACzC,cAAc,0BAA0B,CAAA;AACxC,cAAc,0BAA0B,CAAA;AACxC,cAAc,qBAAqB,CAAA;AACnC,cAAc,mBAAmB,CAAA;AACjC,cAAc,sBAAsB,CAAA;AACpC,cAAc,yBAAyB,CAAA;AACvC,cAAc,2BAA2B,CAAA;AACzC,cAAc,oBAAoB,CAAA;AAClC,cAAc,oBAAoB,CAAA;AAClC,cAAc,qBAAqB,CAAA;AACnC,cAAc,uBAAuB,CAAA;AACrC,cAAc,mCAAmC,CAAA;AACjD,cAAc,6BAA6B,CAAA;AAC3C,cAAc,2BAA2B,CAAA;AACzC,cAAc,sBAAsB,CAAA;AACpC,cAAc,4BAA4B,CAAA;AAC1C,cAAc,uCAAuC,CAAA;AACrD,cAAc,gCAAgC,CAAA;AAC9C,cAAc,8BAA8B,CAAA;AAC5C,cAAc,iCAAiC,CAAA"}

package/script/mod.js

@@ -14,6 +14,72 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * @module SKMTC Core
+ *
+ * SKMTC (Schema Kit Mapping & Type Conversion) is a powerful TypeScript/Deno library
+ * for processing OpenAPI v3 documents and generating code artifacts. It provides a
+ * comprehensive three-phase pipeline for parsing, generating, and rendering OpenAPI
+ * schemas into various output formats.
+ *
+ * ## Quick Start
+ *
+ * ```typescript
+ * import { toArtifacts } from '@skmtc/core';
+ *
+ * const result = await toArtifacts({
+ *   traceId: 'my-trace',
+ *   spanId: 'my-span',
+ *   documentObject: openApiDoc,
+ *   settings: clientSettings,
+ *   toGeneratorConfigMap: () => generatorMap,
+ *   startAt: Date.now(),
+ *   silent: false
+ * });
+ *
+ * console.log(result.artifacts); // Generated code files
+ * console.log(result.manifest);  // Generation metadata
+ * ```
+ *
+ * ## Architecture
+ *
+ * The library follows a three-phase pipeline:
+ * - **Parse Phase**: Converts OpenAPI v3 JSON into internal OAS objects
+ * - **Generate Phase**: Transforms OAS objects into generator artifacts
+ * - **Render Phase**: Renders artifacts to formatted files
+ *
+ * ## Key Components
+ *
+ * - {@link CoreContext} - Main orchestration class for the pipeline
+ * - {@link toArtifacts} - Primary transformation function
+ * - {@link ContentBase} - Base class for creating generators
+ * - {@link ModelBase} and {@link OperationBase} - DSL building blocks
+ * - {@link List} - Powerful string manipulation and code generation utility
+ *
+ * ## Type System
+ *
+ * The library provides comprehensive TypeScript types for OpenAPI schemas,
+ * generator configurations, and output artifacts. All major types are
+ * validated using Valibot schemas for runtime safety.
+ *
+ * @example Basic Usage
+ * ```typescript
+ * import { CoreContext } from '@skmtc/core';
+ *
+ * const context = new CoreContext({
+ *   spanId: 'my-span',
+ *   silent: false
+ * });
+ *
+ * const result = await context.toArtifacts({
+ *   documentObject: myOpenApiDoc,
+ *   settings: mySettings,
+ *   toGeneratorConfigMap: () => myGenerators,
+ *   prettier: prettierConfig,
+ *   silent: false
+ * });
+ * ```
+ */
 require("./_dnt.polyfills.js");
 __exportStar(require("./app/validate.js"), exports);
 __exportStar(require("./context/CoreContext.js"), exports);

package/script/run/toArtifacts.d.ts

@@ -3,17 +3,131 @@ import type { PrettierConfigType } from '../types/PrettierConfig.js';
 import type { ManifestContent } from '../types/Manifest.js';
 import type { GeneratorsMapContainer } from '../types/GeneratorType.js';
 import type { OpenAPIV3 } from 'openapi-types';
+/**
+ * Arguments for the {@link toArtifacts} transformation function.
+ *
+ * @example
+ * ```typescript
+ * const args: TransformArgs = {
+ *   traceId: 'api-generation-v1',
+ *   spanId: 'user-api-span',
+ *   documentObject: openApiDocument,
+ *   settings: {
+ *     basePath: './generated',
+ *     skip: { models: ['InternalModel'] }
+ *   },
+ *   toGeneratorConfigMap: () => myGeneratorMap,
+ *   startAt: Date.now(),
+ *   silent: false
+ * };
+ * ```
+ */
 type TransformArgs = {
+    /** Unique identifier for the transformation trace */
     traceId: string;
+    /** Unique identifier for this transformation span */
     spanId: string;
+    /** The OpenAPI v3 document to process */
     documentObject: OpenAPIV3.Document;
+    /** Client settings for customizing generation behavior */
     settings: ClientSettings | undefined;
+    /** Optional Prettier configuration for code formatting */
     prettier?: PrettierConfigType;
+    /** Optional path for writing log files */
     logsPath?: string;
+    /** Function that returns the generator configuration map */
     toGeneratorConfigMap: <EnrichmentType = undefined>() => GeneratorsMapContainer<EnrichmentType>;
+    /** Timestamp when transformation started */
     startAt: number;
+    /** Whether to suppress console output during generation */
     silent: boolean;
 };
+/**
+ * Transforms an OpenAPI v3 document into generated code artifacts and metadata.
+ *
+ * This is the primary function for the SKMTC transformation pipeline. It orchestrates
+ * the three-phase process of parsing OpenAPI documents, generating code artifacts,
+ * and rendering them to formatted files.
+ *
+ * The function creates a {@link CoreContext} instance and executes the full pipeline:
+ * 1. **Parse**: Converts the OpenAPI document into internal OAS objects
+ * 2. **Generate**: Transforms OAS objects using the provided generator configuration
+ * 3. **Render**: Formats and prepares the final code artifacts
+ *
+ * @param args - Configuration for the transformation process
+ * @returns A promise resolving to the generated artifacts and manifest
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { toArtifacts } from '@skmtc/core';
+ *
+ * const result = await toArtifacts({
+ *   traceId: 'my-api-generation',
+ *   spanId: 'user-service',
+ *   documentObject: myOpenApiDoc,
+ *   settings: {
+ *     basePath: './src/generated',
+ *     skip: {
+ *       models: ['InternalModel', 'DebugInfo'],
+ *       operations: {
+ *         '/internal/**': ['get', 'post']
+ *       }
+ *     }
+ *   },
+ *   toGeneratorConfigMap: () => ({
+ *     models: modelGenerator,
+ *     operations: operationGenerator
+ *   }),
+ *   startAt: Date.now(),
+ *   silent: false
+ * });
+ *
+ * // Access generated files
+ * Object.entries(result.artifacts).forEach(([path, content]) => {
+ *   console.log(`Generated: ${path}`);
+ *   await Deno.writeTextFile(path, content);
+ * });
+ *
+ * // Access generation metadata
+ * console.log(`Generated ${Object.keys(result.manifest.files).length} files`);
+ * console.log(`Generation took ${result.manifest.endAt - result.manifest.startAt}ms`);
+ * ```
+ *
+ * @example With Prettier formatting
+ * ```typescript
+ * const result = await toArtifacts({
+ *   traceId: 'formatted-generation',
+ *   spanId: 'api-client',
+ *   documentObject: openApiDoc,
+ *   settings: clientSettings,
+ *   prettier: {
+ *     semi: true,
+ *     singleQuote: true,
+ *     trailingComma: 'es5'
+ *   },
+ *   toGeneratorConfigMap: () => generatorMap,
+ *   startAt: Date.now(),
+ *   silent: true
+ * });
+ * ```
+ *
+ * @example Error handling
+ * ```typescript
+ * try {
+ *   const result = await toArtifacts(transformArgs);
+ *
+ *   // Check for generation errors in the results
+ *   const hasErrors = Object.values(result.manifest.results)
+ *     .some(result => result === 'error');
+ *
+ *   if (hasErrors) {
+ *     console.warn('Generation completed with errors');
+ *   }
+ * } catch (error) {
+ *   console.error('Transformation failed:', error);
+ * }
+ * ```
+ */
 export declare const toArtifacts: ({ traceId, spanId, documentObject, settings, prettier, toGeneratorConfigMap, logsPath, startAt, silent }: TransformArgs) => Promise<{
     artifacts: Record<string, string>;
     manifest: ManifestContent;

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

@@ -1 +1 @@
-{"version":3,"file":"toArtifacts.d.ts","sourceRoot":"","sources":["../../src/run/toArtifacts.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAC1D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAA;AAEpE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAC3D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAA;AACvE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAC9C,KAAK,aAAa,GAAG;IACnB,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,MAAM,CAAA;IACd,cAAc,EAAE,SAAS,CAAC,QAAQ,CAAA;IAClC,QAAQ,EAAE,cAAc,GAAG,SAAS,CAAA;IACpC,QAAQ,CAAC,EAAE,kBAAkB,CAAA;IAC7B,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,oBAAoB,EAAE,CAAC,cAAc,GAAG,SAAS,OAAO,sBAAsB,CAAC,cAAc,CAAC,CAAA;IAC9F,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,OAAO,CAAA;CAChB,CAAA;AAED,eAAO,MAAM,WAAW,GAAU,0GAU/B,aAAa,KAAG,OAAO,CAAC;IAAE,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,QAAQ,EAAE,eAAe,CAAA;CAAE,CAyB1F,CAAA"}
+{"version":3,"file":"toArtifacts.d.ts","sourceRoot":"","sources":["../../src/run/toArtifacts.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAC1D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAA;AAEpE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAC3D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAA;AACvE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAE9C;;;;;;;;;;;;;;;;;;GAkBG;AACH,KAAK,aAAa,GAAG;IACnB,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAA;IACf,qDAAqD;IACrD,MAAM,EAAE,MAAM,CAAA;IACd,yCAAyC;IACzC,cAAc,EAAE,SAAS,CAAC,QAAQ,CAAA;IAClC,0DAA0D;IAC1D,QAAQ,EAAE,cAAc,GAAG,SAAS,CAAA;IACpC,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,kBAAkB,CAAA;IAC7B,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,4DAA4D;IAC5D,oBAAoB,EAAE,CAAC,cAAc,GAAG,SAAS,OAAO,sBAAsB,CAAC,cAAc,CAAC,CAAA;IAC9F,4CAA4C;IAC5C,OAAO,EAAE,MAAM,CAAA;IACf,2DAA2D;IAC3D,MAAM,EAAE,OAAO,CAAA;CAChB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqFG;AACH,eAAO,MAAM,WAAW,GAAU,0GAU/B,aAAa,KAAG,OAAO,CAAC;IAAE,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,QAAQ,EAAE,eAAe,CAAA;CAAE,CAyB1F,CAAA"}

package/script/run/toArtifacts.js

@@ -36,6 +36,92 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.toArtifacts = void 0;
 const dntShim = __importStar(require("../_dnt.shims.js"));
 const CoreContext_js_1 = require("../context/CoreContext.js");
+/**
+ * Transforms an OpenAPI v3 document into generated code artifacts and metadata.
+ *
+ * This is the primary function for the SKMTC transformation pipeline. It orchestrates
+ * the three-phase process of parsing OpenAPI documents, generating code artifacts,
+ * and rendering them to formatted files.
+ *
+ * The function creates a {@link CoreContext} instance and executes the full pipeline:
+ * 1. **Parse**: Converts the OpenAPI document into internal OAS objects
+ * 2. **Generate**: Transforms OAS objects using the provided generator configuration
+ * 3. **Render**: Formats and prepares the final code artifacts
+ *
+ * @param args - Configuration for the transformation process
+ * @returns A promise resolving to the generated artifacts and manifest
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { toArtifacts } from '@skmtc/core';
+ *
+ * const result = await toArtifacts({
+ *   traceId: 'my-api-generation',
+ *   spanId: 'user-service',
+ *   documentObject: myOpenApiDoc,
+ *   settings: {
+ *     basePath: './src/generated',
+ *     skip: {
+ *       models: ['InternalModel', 'DebugInfo'],
+ *       operations: {
+ *         '/internal/**': ['get', 'post']
+ *       }
+ *     }
+ *   },
+ *   toGeneratorConfigMap: () => ({
+ *     models: modelGenerator,
+ *     operations: operationGenerator
+ *   }),
+ *   startAt: Date.now(),
+ *   silent: false
+ * });
+ *
+ * // Access generated files
+ * Object.entries(result.artifacts).forEach(([path, content]) => {
+ *   console.log(`Generated: ${path}`);
+ *   await Deno.writeTextFile(path, content);
+ * });
+ *
+ * // Access generation metadata
+ * console.log(`Generated ${Object.keys(result.manifest.files).length} files`);
+ * console.log(`Generation took ${result.manifest.endAt - result.manifest.startAt}ms`);
+ * ```
+ *
+ * @example With Prettier formatting
+ * ```typescript
+ * const result = await toArtifacts({
+ *   traceId: 'formatted-generation',
+ *   spanId: 'api-client',
+ *   documentObject: openApiDoc,
+ *   settings: clientSettings,
+ *   prettier: {
+ *     semi: true,
+ *     singleQuote: true,
+ *     trailingComma: 'es5'
+ *   },
+ *   toGeneratorConfigMap: () => generatorMap,
+ *   startAt: Date.now(),
+ *   silent: true
+ * });
+ * ```
+ *
+ * @example Error handling
+ * ```typescript
+ * try {
+ *   const result = await toArtifacts(transformArgs);
+ *
+ *   // Check for generation errors in the results
+ *   const hasErrors = Object.values(result.manifest.results)
+ *     .some(result => result === 'error');
+ *
+ *   if (hasErrors) {
+ *     console.warn('Generation completed with errors');
+ *   }
+ * } catch (error) {
+ *   console.error('Transformation failed:', error);
+ * }
+ * ```
+ */
 const toArtifacts = async ({ traceId, spanId, documentObject, settings, prettier, toGeneratorConfigMap, logsPath, startAt, silent }) => {
     const context = new CoreContext_js_1.CoreContext({ spanId, logsPath, silent });
     const { artifacts, files, previews, results, mappings } = await context.toArtifacts({

package/script/types/Settings.d.ts

@@ -2,23 +2,152 @@ import "../_dnt.polyfills.js";
 import { type GeneratorEnrichments } from './Enrichments.js';
 import * as v from 'valibot';
 import { type Method } from './Method.js';
+/**
+ * Valibot schema for {@link ModulePackage}.
+ */
 export declare const modulePackage: v.GenericSchema<ModulePackage>;
+/**
+ * Configuration for a module package in the generation output.
+ *
+ * Module packages allow organizing generated code into separate npm packages
+ * or modules with custom root paths and naming conventions.
+ *
+ * @example
+ * ```typescript
+ * const packages: ModulePackage[] = [
+ *   {
+ *     rootPath: './packages/api-client',
+ *     moduleName: '@myorg/api-client'
+ *   },
+ *   {
+ *     rootPath: './packages/types',
+ *     moduleName: '@myorg/api-types'
+ *   }
+ * ];
+ * ```
+ */
 export type ModulePackage = {
+    /** The root file system path for this package */
     rootPath: string;
+    /** Optional module name for package.json or imports */
     moduleName?: string;
 };
 export declare const skipPaths: v.GenericSchema<SkipPaths>;
 export declare const skipOperations: v.GenericSchema<SkipOperations>;
 export declare const skipModels: v.GenericSchema<SkipModels>;
 export declare const clientSettings: v.GenericSchema<ClientSettings>;
+/**
+ * Configuration for skipping specific HTTP methods on API paths.
+ *
+ * Maps path patterns to arrays of HTTP methods that should be excluded
+ * from generation.
+ *
+ * @example
+ * ```typescript
+ * const skipPaths: SkipPaths = {
+ *   '/admin/**': ['get', 'post'],
+ *   '/debug': ['*']  // Skip all methods
+ * };
+ * ```
+ */
 export type SkipPaths = Record<string, Method[]>;
+/**
+ * Configuration for skipping model generation by generator type.
+ *
+ * Maps generator keys to arrays of model names that should be excluded.
+ *
+ * @example
+ * ```typescript
+ * const skipModels: SkipModels = {
+ *   'typescript-models': ['InternalModel', 'DebugInfo'],
+ *   'validation': ['TempModel*']  // Supports glob patterns
+ * };
+ * ```
+ */
 export type SkipModels = Record<string, string[]>;
+/**
+ * Configuration for skipping operation generation by generator type.
+ *
+ * Maps generator keys to {@link SkipPaths} configurations for excluding
+ * specific operations from generation.
+ *
+ * @example
+ * ```typescript
+ * const skipOperations: SkipOperations = {
+ *   'api-client': {
+ *     '/internal/**': ['*'],
+ *     '/admin': ['delete']
+ *   }
+ * };
+ * ```
+ */
 export type SkipOperations = Record<string, SkipPaths>;
+/**
+ * Union type representing different skip configurations.
+ *
+ * Can be either operation-specific skipping, model-specific skipping,
+ * or a simple string pattern for broad exclusions.
+ */
 export type Skip = SkipOperations | SkipModels | string;
+/**
+ * Main configuration object for SKMTC client settings.
+ *
+ * Controls various aspects of code generation including output paths,
+ * package organization, enrichments, and selective skipping of content.
+ *
+ * @example Basic configuration
+ * ```typescript
+ * const settings: ClientSettings = {
+ *   basePath: './src/generated',
+ *   skip: [
+ *     'InternalModel',  // Skip specific model
+ *     {
+ *       'api-client': {
+ *         '/admin/**': ['*']  // Skip all admin operations
+ *       }
+ *     }
+ *   ]
+ * };
+ * ```
+ *
+ * @example Advanced configuration with packages
+ * ```typescript
+ * const settings: ClientSettings = {
+ *   basePath: './generated',
+ *   packages: [
+ *     {
+ *       rootPath: './packages/client',
+ *       moduleName: '@company/api-client'
+ *     },
+ *     {
+ *       rootPath: './packages/types',
+ *       moduleName: '@company/api-types'
+ *     }
+ *   ],
+ *   enrichments: {
+ *     models: customModelEnrichments,
+ *     operations: customOperationEnrichments
+ *   },
+ *   skip: [
+ *     {
+ *       'models': ['Internal*', 'Debug*'],
+ *       'operations': {
+ *         '/health': ['get'],
+ *         '/metrics/**': ['*']
+ *       }
+ *     }
+ *   ]
+ * };
+ * ```
+ */
 export type ClientSettings = {
+    /** Base output path for generated files */
     basePath?: string;
+    /** Array of module package configurations */
     packages?: ModulePackage[];
+    /** Custom enrichments for extending generation */
     enrichments?: GeneratorEnrichments;
+    /** Array of skip configurations to exclude content */
     skip?: Skip[];
 };
 export type SkmtcClientConfig = {

package/script/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,eAAO,MAAM,aAAa,EAAE,CAAC,CAAC,aAAa,CAAC,aAAa,CAGvD,CAAA;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,EAAE,MAAM,CAAA;IAChB,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB,CAAA;AAED,eAAO,MAAM,SAAS,EAAE,CAAC,CAAC,aAAa,CAAC,SAAS,CAAyC,CAAA;AAE1F,eAAO,MAAM,cAAc,EAAE,CAAC,CAAC,aAAa,CAAC,cAAc,CAAmC,CAAA;AAE9F,eAAO,MAAM,UAAU,EAAE,CAAC,CAAC,aAAa,CAAC,UAAU,CAA6C,CAAA;AAIhG,eAAO,MAAM,cAAc,EAAE,CAAC,CAAC,aAAa,CAAC,cAAc,CAKzD,CAAA;AAEF,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAA;AAEhD,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAA;AAEjD,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAA;AAEtD,MAAM,MAAM,IAAI,GAAG,cAAc,GAAG,UAAU,GAAG,MAAM,CAAA;AAEvD,MAAM,MAAM,cAAc,GAAG;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,QAAQ,CAAC,EAAE,aAAa,EAAE,CAAA;IAC1B,WAAW,CAAC,EAAE,oBAAoB,CAAA;IAClC,IAAI,CAAC,EAAE,IAAI,EAAE,CAAA;CACd,CAAA;AAED,MAAM,MAAM,iBAAiB,GAAG;IAC9B,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,QAAQ,EAAE,cAAc,CAAA;CACzB,CAAA;AAED,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,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,eAAO,MAAM,SAAS,EAAE,CAAC,CAAC,aAAa,CAAC,SAAS,CAAyC,CAAA;AAE1F,eAAO,MAAM,cAAc,EAAE,CAAC,CAAC,aAAa,CAAC,cAAc,CAAmC,CAAA;AAE9F,eAAO,MAAM,UAAU,EAAE,CAAC,CAAC,aAAa,CAAC,UAAU,CAA6C,CAAA;AAIhG,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,MAAM,MAAM,iBAAiB,GAAG;IAC9B,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,QAAQ,EAAE,cAAc,CAAA;CACzB,CAAA;AAED,eAAO,MAAM,iBAAiB,EAAE,CAAC,CAAC,aAAa,CAAC,iBAAiB,CAG/D,CAAA"}

package/script/types/Settings.js

@@ -38,6 +38,9 @@ require("../_dnt.polyfills.js");
 const Enrichments_js_1 = require("./Enrichments.js");
 const v = __importStar(require("valibot"));
 const Method_js_1 = require("./Method.js");
+/**
+ * Valibot schema for {@link ModulePackage}.
+ */
 exports.modulePackage = v.object({
     rootPath: v.string(),
     moduleName: v.optional(v.string())