@skmtc/core 0.0.782 → 0.0.785

package/esm/typescript/List.js

@@ -1,24 +1,130 @@
 import { match } from 'ts-pattern';
+/**
+ * A powerful utility class for building formatted lists of stringable items.
+ *
+ * The `List` class is a core component of the SKMTC DSL system, providing type-safe
+ * construction of formatted lists with customizable separators and bookends. It's
+ * extensively used throughout the codebase for generating code constructs like
+ * function parameters, object properties, array literals, and more.
+ *
+ * ## Type Safety
+ *
+ * The class uses TypeScript's generic system to provide compile-time guarantees
+ * about the list structure, separator, and bookend styles. This enables rich
+ * type inference and helps prevent formatting errors.
+ *
+ * ## Common Patterns
+ *
+ * - **Objects**: `List.toObject()` creates `{key: value, ...}` structures
+ * - **Arrays**: `List.toArray()` creates `[item, item, ...]` structures
+ * - **Parameters**: `List.toParams()` creates `(param, param, ...)` structures
+ * - **Lines**: `List.toLines()` creates newline-separated content
+ *
+ * @template Values - Array of stringable values
+ * @template Separator - String used to separate items
+ * @template Bookends - Style of bookends ('[]', '{}', '()', '<>', 'none')
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { List } from '@skmtc/core';
+ *
+ * // Create a comma-separated list
+ * const items = new List(['apple', 'banana', 'cherry']);
+ * console.log(items.toString()); // "apple, banana, cherry"
+ *
+ * // Create an array-style list
+ * const array = new List(['a', 'b', 'c'], { bookends: '[]' });
+ * console.log(array.toString()); // "[a, b, c]"
+ *
+ * // Create an object-style list
+ * const obj = new List(['x: 1', 'y: 2'], { bookends: '{}' });
+ * console.log(obj.toString()); // "{x: 1, y: 2}"
+ * ```
+ *
+ * @example Using type aliases
+ * ```typescript
+ * // Type-safe array construction
+ * const params: ListParams<string> = List.toParams(['id', 'name', 'email']);
+ * console.log(params.toString()); // "(id, name, email)"
+ *
+ * // Object properties with filtering
+ * const props = List.toObject(['title', undefined, 'author'], { skipEmpty: true });
+ * console.log(props.toString()); // "{title, author}"
+ *
+ * // Line-separated content
+ * const lines = List.toLines(['import React from "react"', 'import { useState } from "react"']);
+ * console.log(lines.toString());
+ * // import React from "react"
+ * // import { useState } from "react"
+ * ```
+ *
+ * @example Advanced usage with builders
+ * ```typescript
+ * // Function signature generation
+ * const signature = List.toParams([
+ *   'id: string',
+ *   'options?: RequestOptions',
+ *   'callback?: (result: T) => void'
+ * ]);
+ *
+ * // Interface properties
+ * const interfaceProps = List.toObject([
+ *   'readonly id: string',
+ *   'name: string',
+ *   'createdAt: Date',
+ *   'updatedAt?: Date'
+ * ]);
+ *
+ * console.log(`interface User ${interfaceProps}`);
+ * // interface User {readonly id: string, name: string, createdAt: Date, updatedAt?: Date}
+ * ```
+ */
 export class List {
+    /**
+     * Creates a new List instance.
+     *
+     * @param values - Array of values (undefined values are automatically filtered out)
+     * @param options - Configuration options
+     * @param options.separator - String to use between items (default: ', ')
+     * @param options.bookends - Style of bookends to wrap the list (default: 'none')
+     * @param options.skipEmpty - Whether to return empty string for empty lists (default: false)
+     *
+     * @example
+     * ```typescript
+     * // Basic list with default comma separator
+     * const basic = new List(['a', 'b', 'c']);
+     *
+     * // Custom separator and bookends
+     * const custom = new List(['x', 'y', 'z'], {
+     *   separator: ' | ',
+     *   bookends: '[]',
+     *   skipEmpty: true
+     * });
+     * ```
+     */
     constructor(values, { separator, bookends, skipEmpty } = {}) {
+        /** The array of values in this list */
         Object.defineProperty(this, "values", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /** The separator string used between items */
         Object.defineProperty(this, "separator", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /** The bookend style for wrapping the list */
         Object.defineProperty(this, "bookends", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /** Whether to skip rendering when the list is empty */
         Object.defineProperty(this, "skipEmpty", {
             enumerable: true,
             configurable: true,

package/package.json

@@ -1,6 +1,10 @@
 {
   "name": "@skmtc/core",
-  "version": "0.0.782",
+  "version": "0.0.785",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/skmtc/skmtc.git"
+  },
   "main": "./script/mod.js",
   "module": "./esm/mod.js",
   "exports": {

package/script/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/script/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/script/context/CoreContext.js

@@ -57,18 +57,93 @@ const tracer_js_1 = require("../helpers/tracer.js");
 const ResultsLog_js_1 = require("../helpers/ResultsLog.js");
 const Sentry = __importStar(require("@sentry/node"));
 const join_js_1 = require("../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));
+ * ```
+ */
 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,
@@ -80,6 +155,38 @@ 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();
@@ -87,6 +194,77 @@ 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/script/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/script/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"}