@skmtc/core 0.0.782 → 0.0.783

package/esm/context/CoreContext.d.ts

@@ -34,14 +34,189 @@ type ToArtifactsArgs = {
     prettier?: PrettierConfigType;
     silent: boolean;
 };
+/**
+ * The main orchestration class for the SKMTC transformation pipeline.
+ *
+ * `CoreContext` manages the three-phase process of transforming OpenAPI v3 documents
+ * into code artifacts. It coordinates parsing, generation, and rendering phases while
+ * providing logging, tracing, and error handling capabilities.
+ *
+ * ## Pipeline Phases
+ *
+ * 1. **Parse Phase**: Uses {@link ParseContext} to convert OpenAPI JSON into OAS objects
+ * 2. **Generate Phase**: Uses {@link GenerateContext} to transform OAS objects with generators
+ * 3. **Render Phase**: Uses {@link RenderContext} to format and prepare final artifacts
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { CoreContext } from '@skmtc/core';
+ *
+ * const context = new CoreContext({
+ *   spanId: 'user-api-generation',
+ *   logsPath: './logs',
+ *   silent: false
+ * });
+ *
+ * const result = await context.toArtifacts({
+ *   documentObject: openApiDoc,
+ *   settings: clientSettings,
+ *   toGeneratorConfigMap: () => generators,
+ *   prettier: prettierConfig,
+ *   silent: false
+ * });
+ * ```
+ *
+ * @example Using individual phases
+ * ```typescript
+ * const context = new CoreContext({
+ *   spanId: 'custom-pipeline',
+ *   silent: true
+ * });
+ *
+ * // Parse phase only
+ * const { oasDocument } = context.parse(openApiDoc);
+ *
+ * // Then use document for custom processing
+ * console.log('Parsed schemas:', Object.keys(oasDocument.components.schemas));
+ * ```
+ */
 export declare class CoreContext {
     #private;
+    /** Logger instance for the context */
     logger: log.Logger;
+    /** Whether to suppress console output */
     silent: boolean;
+    /**
+     * Creates a new CoreContext instance.
+     *
+     * @param args - Configuration for the context
+     * @param args.spanId - Unique identifier for this transformation span
+     * @param args.logsPath - Optional directory path for log files
+     * @param args.silent - Whether to suppress console output
+     *
+     * @example
+     * ```typescript
+     * // Basic context with console logging
+     * const context = new CoreContext({
+     *   spanId: 'my-generation',
+     *   silent: false
+     * });
+     *
+     * // Context with file logging
+     * const context = new CoreContext({
+     *   spanId: 'batch-job-123',
+     *   logsPath: './logs/generation',
+     *   silent: true
+     * });
+     * ```
+     */
     constructor({ spanId, logsPath, silent }: CoreContextArgs);
+    /**
+     * Parses an OpenAPI v3 document into internal OAS objects.
+     *
+     * This method executes only the parse phase of the pipeline, converting
+     * the raw OpenAPI JSON into structured OAS objects that can be used for
+     * generation or custom processing.
+     *
+     * @param documentObject - The OpenAPI v3 document to parse
+     * @returns An object containing the parsed OAS document
+     *
+     * @example
+     * ```typescript
+     * import { CoreContext } from '@skmtc/core';
+     *
+     * const context = new CoreContext({
+     *   spanId: 'parse-only',
+     *   silent: true
+     * });
+     *
+     * const { oasDocument } = context.parse(openApiDoc);
+     *
+     * // Access parsed components
+     * console.log('Models:', Object.keys(oasDocument.components.schemas));
+     * console.log('Paths:', Object.keys(oasDocument.paths));
+     *
+     * // Use for custom processing
+     * const userModel = oasDocument.components.schemas['User'];
+     * if (userModel && !userModel.isRef()) {
+     *   console.log('User properties:', Object.keys(userModel.properties));
+     * }
+     * ```
+     */
     parse(documentObject: OpenAPIV3.Document): {
         oasDocument: OasDocument;
     };
+    /**
+     * Executes the complete transformation pipeline to generate code artifacts.
+     *
+     * This method orchestrates all three phases:
+     * 1. **Parse**: Convert OpenAPI document to OAS objects
+     * 2. **Generate**: Transform OAS objects using generators
+     * 3. **Render**: Format and prepare final artifacts
+     *
+     * The result includes both the generated code files and comprehensive metadata
+     * about the generation process, including file mappings, previews, and results.
+     *
+     * @param args - Configuration for the artifact generation
+     * @param args.documentObject - The OpenAPI v3 document to process
+     * @param args.settings - Client settings for customization
+     * @param args.toGeneratorConfigMap - Function returning generator configuration
+     * @param args.prettier - Optional Prettier configuration for code formatting
+     * @param args.silent - Whether to suppress console output during generation
+     * @returns Promise resolving to rendered artifacts and metadata
+     *
+     * @example Complete pipeline
+     * ```typescript
+     * const context = new CoreContext({
+     *   spanId: 'api-client-gen',
+     *   silent: false
+     * });
+     *
+     * const result = await context.toArtifacts({
+     *   documentObject: openApiDoc,
+     *   settings: {
+     *     basePath: './src/api',
+     *     skip: {
+     *       models: ['Internal*'],
+     *       operations: {
+     *         '/health': ['get'],
+     *         '/debug/**': ['*']
+     *       }
+     *     }
+     *   },
+     *   toGeneratorConfigMap: () => ({
+     *     models: {
+     *       generator: MyModelGenerator,
+     *       settings: { includeValidation: true }
+     *     },
+     *     operations: {
+     *       generator: MyOperationGenerator,
+     *       settings: { generateTypes: true }
+     *     }
+     *   }),
+     *   prettier: {
+     *     semi: false,
+     *     singleQuote: true,
+     *     trailingComma: 'all'
+     *   },
+     *   silent: false
+     * });
+     *
+     * // Access generated artifacts
+     * console.log('Generated files:', Object.keys(result.artifacts));
+     *
+     * // Write to filesystem
+     * for (const [path, content] of Object.entries(result.artifacts)) {
+     *   await Deno.writeTextFile(path, content);
+     * }
+     *
+     * // Access metadata
+     * console.log('Generation results:', result.results);
+     * console.log('File mappings:', result.files);
+     * ```
+     *
+     * @throws Will throw an error if any phase of the pipeline fails
+     */
     toArtifacts({ documentObject, settings, toGeneratorConfigMap, prettier }: ToArtifactsArgs): Promise<RenderResult>;
     trace<T>(token: string | string[], fn: () => T): T;
     captureCurrentResult(result: ResultType): void;

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

@@ -1 +1 @@
-{"version":3,"file":"CoreContext.d.ts","sourceRoot":"","sources":["../../src/context/CoreContext.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAClD,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAChD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAA;AACpE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAA;AAC9D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAC1D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAA;AACrD,OAAO,KAAK,GAAG,MAAM,yCAAyC,CAAA;AAQ9D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAA;AAEvE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAE9C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAE9C,MAAM,MAAM,UAAU,GAAG;IACvB,IAAI,EAAE,OAAO,CAAA;IACb,OAAO,EAAE,YAAY,CAAA;CACtB,CAAA;AAED,MAAM,MAAM,aAAa,GAAG;IAC1B,IAAI,EAAE,UAAU,CAAA;IAChB,OAAO,EAAE,eAAe,CAAA;CACzB,CAAA;AAED,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EAAE,QAAQ,CAAA;IACd,OAAO,EAAE,aAAa,CAAA;CACvB,CAAA;AAED,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG,aAAa,GAAG,WAAW,CAAA;AAQrE,KAAK,eAAe,GAAG;IACrB,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,OAAO,CAAA;CAChB,CAAA;AAUD,KAAK,eAAe,GAAG;IACrB,cAAc,EAAE,SAAS,CAAC,QAAQ,CAAA;IAClC,QAAQ,EAAE,cAAc,GAAG,SAAS,CAAA;IACpC,oBAAoB,EAAE,CAAC,cAAc,GAAG,SAAS,OAAO,sBAAsB,CAAC,cAAc,CAAC,CAAA;IAC9F,QAAQ,CAAC,EAAE,kBAAkB,CAAA;IAC7B,MAAM,EAAE,OAAO,CAAA;CAChB,CAAA;AAOD,qBAAa,WAAW;;IACtB,MAAM,EAAE,GAAG,CAAC,MAAM,CAAA;IAIlB,MAAM,EAAE,OAAO,CAAA;gBACH,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,eAAe;IAmDzD,KAAK,CAAC,cAAc,EAAE,SAAS,CAAC,QAAQ,GAAG;QAAE,WAAW,EAAE,WAAW,CAAA;KAAE;IAUjE,WAAW,CAAC,EAAE,cAAc,EAAE,QAAQ,EAAE,oBAAoB,EAAE,QAAQ,EAAE,EAAE,eAAe,GAAG,OAAO,CAAC,YAAY,CAAC;IA2DvH,KAAK,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC;IAkClD,oBAAoB,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI;CAkB/C;AAED,MAAM,MAAM,iBAAiB,GAAG;IAC9B,SAAS,EAAE,GAAG,CAAC,SAAS,CAAA;IACxB,UAAU,EAAE,MAAM,CAAA;CACnB,CAAA;AAED,wBAAgB,cAAc,CAAC,EAAE,SAAS,EAAE,UAAU,EAAE,EAAE,iBAAiB,GAAG,MAAM,CAQnF"}
+{"version":3,"file":"CoreContext.d.ts","sourceRoot":"","sources":["../../src/context/CoreContext.ts"],"names":[],"mappings":"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"}

package/esm/context/CoreContext.js

@@ -20,18 +20,93 @@ import { tracer } from '../helpers/tracer.js';
 import { ResultsLog } from '../helpers/ResultsLog.js';
 import * as Sentry from '@sentry/node';
 import { join } from '../deps/jsr.io/@std/path/1.1.2/join.js';
+/**
+ * The main orchestration class for the SKMTC transformation pipeline.
+ *
+ * `CoreContext` manages the three-phase process of transforming OpenAPI v3 documents
+ * into code artifacts. It coordinates parsing, generation, and rendering phases while
+ * providing logging, tracing, and error handling capabilities.
+ *
+ * ## Pipeline Phases
+ *
+ * 1. **Parse Phase**: Uses {@link ParseContext} to convert OpenAPI JSON into OAS objects
+ * 2. **Generate Phase**: Uses {@link GenerateContext} to transform OAS objects with generators
+ * 3. **Render Phase**: Uses {@link RenderContext} to format and prepare final artifacts
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { CoreContext } from '@skmtc/core';
+ *
+ * const context = new CoreContext({
+ *   spanId: 'user-api-generation',
+ *   logsPath: './logs',
+ *   silent: false
+ * });
+ *
+ * const result = await context.toArtifacts({
+ *   documentObject: openApiDoc,
+ *   settings: clientSettings,
+ *   toGeneratorConfigMap: () => generators,
+ *   prettier: prettierConfig,
+ *   silent: false
+ * });
+ * ```
+ *
+ * @example Using individual phases
+ * ```typescript
+ * const context = new CoreContext({
+ *   spanId: 'custom-pipeline',
+ *   silent: true
+ * });
+ *
+ * // Parse phase only
+ * const { oasDocument } = context.parse(openApiDoc);
+ *
+ * // Then use document for custom processing
+ * console.log('Parsed schemas:', Object.keys(oasDocument.components.schemas));
+ * ```
+ */
 export class CoreContext {
+    /**
+     * Creates a new CoreContext instance.
+     *
+     * @param args - Configuration for the context
+     * @param args.spanId - Unique identifier for this transformation span
+     * @param args.logsPath - Optional directory path for log files
+     * @param args.silent - Whether to suppress console output
+     *
+     * @example
+     * ```typescript
+     * // Basic context with console logging
+     * const context = new CoreContext({
+     *   spanId: 'my-generation',
+     *   silent: false
+     * });
+     *
+     * // Context with file logging
+     * const context = new CoreContext({
+     *   spanId: 'batch-job-123',
+     *   logsPath: './logs/generation',
+     *   silent: true
+     * });
+     * ```
+     */
     constructor({ spanId, logsPath, silent }) {
         _CoreContext_instances.add(this);
+        /** Logger instance for the context */
         Object.defineProperty(this, "logger", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /** Current execution phase for pipeline tracking */
         _CoreContext_phase.set(this, void 0);
+        /** Results log for tracking generation outcomes */
         _CoreContext_results.set(this, void 0);
+        /** Stack trail for distributed tracing */
         _CoreContext_stackTrail.set(this, void 0);
+        /** Whether to suppress console output */
         Object.defineProperty(this, "silent", {
             enumerable: true,
             configurable: true,
@@ -43,6 +118,38 @@ export class CoreContext {
         this.logger = __classPrivateFieldGet(this, _CoreContext_instances, "m", _CoreContext_setupLogger).call(this, { spanId, logsPath });
         this.silent = silent;
     }
+    /**
+     * Parses an OpenAPI v3 document into internal OAS objects.
+     *
+     * This method executes only the parse phase of the pipeline, converting
+     * the raw OpenAPI JSON into structured OAS objects that can be used for
+     * generation or custom processing.
+     *
+     * @param documentObject - The OpenAPI v3 document to parse
+     * @returns An object containing the parsed OAS document
+     *
+     * @example
+     * ```typescript
+     * import { CoreContext } from '@skmtc/core';
+     *
+     * const context = new CoreContext({
+     *   spanId: 'parse-only',
+     *   silent: true
+     * });
+     *
+     * const { oasDocument } = context.parse(openApiDoc);
+     *
+     * // Access parsed components
+     * console.log('Models:', Object.keys(oasDocument.components.schemas));
+     * console.log('Paths:', Object.keys(oasDocument.paths));
+     *
+     * // Use for custom processing
+     * const userModel = oasDocument.components.schemas['User'];
+     * if (userModel && !userModel.isRef()) {
+     *   console.log('User properties:', Object.keys(userModel.properties));
+     * }
+     * ```
+     */
     parse(documentObject) {
         __classPrivateFieldSet(this, _CoreContext_phase, __classPrivateFieldGet(this, _CoreContext_instances, "m", _CoreContext_setupParsePhase).call(this, documentObject), "f");
         const oasDocument = __classPrivateFieldGet(this, _CoreContext_phase, "f").context.parse();
@@ -50,6 +157,77 @@ export class CoreContext {
             oasDocument
         };
     }
+    /**
+     * Executes the complete transformation pipeline to generate code artifacts.
+     *
+     * This method orchestrates all three phases:
+     * 1. **Parse**: Convert OpenAPI document to OAS objects
+     * 2. **Generate**: Transform OAS objects using generators
+     * 3. **Render**: Format and prepare final artifacts
+     *
+     * The result includes both the generated code files and comprehensive metadata
+     * about the generation process, including file mappings, previews, and results.
+     *
+     * @param args - Configuration for the artifact generation
+     * @param args.documentObject - The OpenAPI v3 document to process
+     * @param args.settings - Client settings for customization
+     * @param args.toGeneratorConfigMap - Function returning generator configuration
+     * @param args.prettier - Optional Prettier configuration for code formatting
+     * @param args.silent - Whether to suppress console output during generation
+     * @returns Promise resolving to rendered artifacts and metadata
+     *
+     * @example Complete pipeline
+     * ```typescript
+     * const context = new CoreContext({
+     *   spanId: 'api-client-gen',
+     *   silent: false
+     * });
+     *
+     * const result = await context.toArtifacts({
+     *   documentObject: openApiDoc,
+     *   settings: {
+     *     basePath: './src/api',
+     *     skip: {
+     *       models: ['Internal*'],
+     *       operations: {
+     *         '/health': ['get'],
+     *         '/debug/**': ['*']
+     *       }
+     *     }
+     *   },
+     *   toGeneratorConfigMap: () => ({
+     *     models: {
+     *       generator: MyModelGenerator,
+     *       settings: { includeValidation: true }
+     *     },
+     *     operations: {
+     *       generator: MyOperationGenerator,
+     *       settings: { generateTypes: true }
+     *     }
+     *   }),
+     *   prettier: {
+     *     semi: false,
+     *     singleQuote: true,
+     *     trailingComma: 'all'
+     *   },
+     *   silent: false
+     * });
+     *
+     * // Access generated artifacts
+     * console.log('Generated files:', Object.keys(result.artifacts));
+     *
+     * // Write to filesystem
+     * for (const [path, content] of Object.entries(result.artifacts)) {
+     *   await Deno.writeTextFile(path, content);
+     * }
+     *
+     * // Access metadata
+     * console.log('Generation results:', result.results);
+     * console.log('File mappings:', result.files);
+     * ```
+     *
+     * @throws Will throw an error if any phase of the pipeline fails
+     */
     async toArtifacts({ documentObject, settings, toGeneratorConfigMap, prettier }) {
         try {
             const oasDocument = this.trace('parse', () => {

package/esm/dsl/ContentBase.d.ts

@@ -1,15 +1,130 @@
 import type { GenerateContext } from '../context/GenerateContext.js';
 import type { RegisterArgs } from '../context/GenerateContext.js';
 import type { GeneratorKey } from '../types/GeneratorKeys.js';
+/**
+ * Constructor arguments for {@link ContentBase}.
+ */
 type ContentBaseArgs = {
+    /** The generation context providing OAS objects and utilities */
     context: GenerateContext;
+    /** Optional generator key for tracking and identification */
     generatorKey?: GeneratorKey;
 };
+/**
+ * Base class for all content generators in the SKMTC DSL system.
+ *
+ * `ContentBase` provides the foundation for creating custom generators that transform
+ * OpenAPI Schema (OAS) objects into code artifacts. It handles registration with the
+ * generation context, skipping logic, and provides access to the pipeline's utilities.
+ *
+ * ## Generator Lifecycle
+ *
+ * 1. **Construction**: Initialize with context and optional generator key
+ * 2. **Registration**: Call {@link register} to add artifacts to the pipeline
+ * 3. **Generation**: Implement custom logic using context utilities
+ * 4. **Rendering**: Artifacts are automatically rendered by the pipeline
+ *
+ * @example Basic generator
+ * ```typescript
+ * import { ContentBase } from '@skmtc/core';
+ *
+ * class MyModelGenerator extends ContentBase {
+ *   generate() {
+ *     // Skip if not needed
+ *     if (this.shouldSkip()) return;
+ *
+ *     // Access OAS objects through context
+ *     const schemas = this.context.oasDocument.components.schemas;
+ *
+ *     for (const [name, schema] of Object.entries(schemas)) {
+ *       if (schema.isRef()) continue;
+ *
+ *       const file = new File({
+ *         context: this.context,
+ *         path: `./models/${name}.ts`,
+ *         content: this.generateModelContent(schema)
+ *       });
+ *
+ *       // Register the file for rendering
+ *       this.register({ file });
+ *     }
+ *   }
+ *
+ *   private generateModelContent(schema: OasObject): string {
+ *     // Custom model generation logic
+ *     return `export interface ${schema.name} { ... }`;
+ *   }
+ * }
+ * ```
+ *
+ * @example Generator with skipping logic
+ * ```typescript
+ * class ConditionalGenerator extends ContentBase {
+ *   generate() {
+ *     // Check if generation should be skipped
+ *     if (this.shouldSkipBasedOnSettings()) {
+ *       this.skip('Disabled in settings');
+ *       return;
+ *     }
+ *
+ *     // Continue with generation...
+ *     const file = this.createOutputFile();
+ *     this.register({ file });
+ *   }
+ *
+ *   private shouldSkipBasedOnSettings(): boolean {
+ *     return this.context.settings?.skip?.models?.includes('MyModel') ?? false;
+ *   }
+ * }
+ * ```
+ */
 export declare class ContentBase {
+    /** The generation context providing access to OAS objects and utilities */
     context: GenerateContext;
+    /** Whether this generator has been skipped */
     skipped: boolean;
+    /** Optional generator key for identification and tracking */
     generatorKey: GeneratorKey | undefined;
+    /**
+     * Creates a new ContentBase instance.
+     *
+     * @param args - Construction arguments
+     * @param args.context - The generation context
+     * @param args.generatorKey - Optional generator key
+     */
     constructor({ context, generatorKey }: ContentBaseArgs);
+    /**
+     * Registers generated artifacts with the rendering pipeline.
+     *
+     * This method is called by generator implementations to add files,
+     * JSON artifacts, or other content to the generation output.
+     *
+     * @param args - The artifacts to register
+     * @param args.file - Optional file to register
+     * @param args.jsonFile - Optional JSON file to register
+     *
+     * @example Registering a file
+     * ```typescript
+     * const file = new File({
+     *   context: this.context,
+     *   path: './output.ts',
+     *   content: 'export const value = 42;'
+     * });
+     *
+     * this.register({ file });
+     * ```
+     *
+     * @example Registering JSON data
+     * ```typescript
+     * const jsonFile = new JsonFile({
+     *   context: this.context,
+     *   path: './config.json',
+     *   data: { version: '1.0.0', features: ['api'] }
+     * });
+     *
+     * this.register({ jsonFile });
+     * ```
+     */
     register(args: RegisterArgs): void;
 }
 export {};

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

@@ -1 +1 @@
-{"version":3,"file":"ContentBase.d.ts","sourceRoot":"","sources":["../../src/dsl/ContentBase.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAA;AACpE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAA;AACjE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAA;AAE7D,KAAK,eAAe,GAAG;IACrB,OAAO,EAAE,eAAe,CAAA;IACxB,YAAY,CAAC,EAAE,YAAY,CAAA;CAC5B,CAAA;AAED,qBAAa,WAAW;IACtB,OAAO,EAAE,eAAe,CAAA;IACxB,OAAO,EAAE,OAAO,CAAQ;IACxB,YAAY,EAAE,YAAY,GAAG,SAAS,CAAA;gBAE1B,EAAE,OAAO,EAAE,YAAY,EAAE,EAAE,eAAe;IAKtD,QAAQ,CAAC,IAAI,EAAE,YAAY;CAG5B"}
+{"version":3,"file":"ContentBase.d.ts","sourceRoot":"","sources":["../../src/dsl/ContentBase.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAA;AACpE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAA;AACjE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAA;AAE7D;;GAEG;AACH,KAAK,eAAe,GAAG;IACrB,iEAAiE;IACjE,OAAO,EAAE,eAAe,CAAA;IACxB,6DAA6D;IAC7D,YAAY,CAAC,EAAE,YAAY,CAAA;CAC5B,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmEG;AACH,qBAAa,WAAW;IACtB,2EAA2E;IAC3E,OAAO,EAAE,eAAe,CAAA;IAExB,8CAA8C;IAC9C,OAAO,EAAE,OAAO,CAAQ;IAExB,6DAA6D;IAC7D,YAAY,EAAE,YAAY,GAAG,SAAS,CAAA;IAEtC;;;;;;OAMG;gBACS,EAAE,OAAO,EAAE,YAAY,EAAE,EAAE,eAAe;IAKtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACH,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI;CAGnC"}

package/esm/dsl/ContentBase.js

@@ -1,17 +1,95 @@
+/**
+ * Base class for all content generators in the SKMTC DSL system.
+ *
+ * `ContentBase` provides the foundation for creating custom generators that transform
+ * OpenAPI Schema (OAS) objects into code artifacts. It handles registration with the
+ * generation context, skipping logic, and provides access to the pipeline's utilities.
+ *
+ * ## Generator Lifecycle
+ *
+ * 1. **Construction**: Initialize with context and optional generator key
+ * 2. **Registration**: Call {@link register} to add artifacts to the pipeline
+ * 3. **Generation**: Implement custom logic using context utilities
+ * 4. **Rendering**: Artifacts are automatically rendered by the pipeline
+ *
+ * @example Basic generator
+ * ```typescript
+ * import { ContentBase } from '@skmtc/core';
+ *
+ * class MyModelGenerator extends ContentBase {
+ *   generate() {
+ *     // Skip if not needed
+ *     if (this.shouldSkip()) return;
+ *
+ *     // Access OAS objects through context
+ *     const schemas = this.context.oasDocument.components.schemas;
+ *
+ *     for (const [name, schema] of Object.entries(schemas)) {
+ *       if (schema.isRef()) continue;
+ *
+ *       const file = new File({
+ *         context: this.context,
+ *         path: `./models/${name}.ts`,
+ *         content: this.generateModelContent(schema)
+ *       });
+ *
+ *       // Register the file for rendering
+ *       this.register({ file });
+ *     }
+ *   }
+ *
+ *   private generateModelContent(schema: OasObject): string {
+ *     // Custom model generation logic
+ *     return `export interface ${schema.name} { ... }`;
+ *   }
+ * }
+ * ```
+ *
+ * @example Generator with skipping logic
+ * ```typescript
+ * class ConditionalGenerator extends ContentBase {
+ *   generate() {
+ *     // Check if generation should be skipped
+ *     if (this.shouldSkipBasedOnSettings()) {
+ *       this.skip('Disabled in settings');
+ *       return;
+ *     }
+ *
+ *     // Continue with generation...
+ *     const file = this.createOutputFile();
+ *     this.register({ file });
+ *   }
+ *
+ *   private shouldSkipBasedOnSettings(): boolean {
+ *     return this.context.settings?.skip?.models?.includes('MyModel') ?? false;
+ *   }
+ * }
+ * ```
+ */
 export class ContentBase {
+    /**
+     * Creates a new ContentBase instance.
+     *
+     * @param args - Construction arguments
+     * @param args.context - The generation context
+     * @param args.generatorKey - Optional generator key
+     */
     constructor({ context, generatorKey }) {
+        /** The generation context providing access to OAS objects and utilities */
         Object.defineProperty(this, "context", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /** Whether this generator has been skipped */
         Object.defineProperty(this, "skipped", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: false
         });
+        /** Optional generator key for identification and tracking */
         Object.defineProperty(this, "generatorKey", {
             enumerable: true,
             configurable: true,
@@ -21,6 +99,38 @@ export class ContentBase {
         this.context = context;
         this.generatorKey = generatorKey;
     }
+    /**
+     * Registers generated artifacts with the rendering pipeline.
+     *
+     * This method is called by generator implementations to add files,
+     * JSON artifacts, or other content to the generation output.
+     *
+     * @param args - The artifacts to register
+     * @param args.file - Optional file to register
+     * @param args.jsonFile - Optional JSON file to register
+     *
+     * @example Registering a file
+     * ```typescript
+     * const file = new File({
+     *   context: this.context,
+     *   path: './output.ts',
+     *   content: 'export const value = 42;'
+     * });
+     *
+     * this.register({ file });
+     * ```
+     *
+     * @example Registering JSON data
+     * ```typescript
+     * const jsonFile = new JsonFile({
+     *   context: this.context,
+     *   path: './config.json',
+     *   data: { version: '1.0.0', features: ['api'] }
+     * });
+     *
+     * this.register({ jsonFile });
+     * ```
+     */
     register(args) {
         this.context.register(args);
     }