@skmtc/core 0.0.789 → 0.0.791

package/esm/oas/void/Void.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Void.d.ts","sourceRoot":"","sources":["../../../src/oas/void/Void.ts"],"names":[],"mappings":"AAAA,OAAO,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAA;AAE3C,MAAM,MAAM,UAAU,GAAG;IACvB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB,CAAA;AAED;;;;GAIG;AACH,qBAAa,OAAO;IAClB;;;OAGG;IACH,OAAO,EAAG,QAAQ,CAAS;IAC3B;;OAEG;IACH,IAAI,EAAG,MAAM,CAAS;IACtB;;OAEG;IACH,KAAK,EAAE,MAAM,GAAG,SAAS,CAAA;IACzB;;OAEG;IACH,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;gBAEnB,MAAM,GAAE,UAAe;IAKnC,MAAM,CAAC,KAAK,IAAI,OAAO;IAIvB,KAAK,IAAI,IAAI,IAAI,MAAM,CAAC,QAAQ,CAAC;IAIjC,OAAO,IAAI,OAAO;IAIlB,WAAW,IAAI,OAAO;CAGvB"}
+{"version":3,"file":"Void.d.ts","sourceRoot":"","sources":["../../../src/oas/void/Void.ts"],"names":[],"mappings":"AAAA,OAAO,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAA;AAE3C;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,yCAAyC;IACzC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,gDAAgD;IAChD,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8HG;AACH,qBAAa,OAAO;IAClB;;;OAGG;IACH,OAAO,EAAG,QAAQ,CAAS;IAC3B;;OAEG;IACH,IAAI,EAAG,MAAM,CAAS;IACtB;;OAEG;IACH,KAAK,EAAE,MAAM,GAAG,SAAS,CAAA;IACzB;;OAEG;IACH,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;gBAEnB,MAAM,GAAE,UAAe;IAKnC,MAAM,CAAC,KAAK,IAAI,OAAO;IAIvB,KAAK,IAAI,IAAI,IAAI,MAAM,CAAC,QAAQ,CAAC;IAIjC,OAAO,IAAI,OAAO;IAIlB,WAAW,IAAI,OAAO;CAGvB"}

package/esm/oas/void/Void.js

@@ -1,8 +1,130 @@
 import "../../_dnt.polyfills.js";
 /**
- * Object representing a void type in the OpenAPI Specification.
- * It is used to describe an absence of a value such as when no
- * content is returned by an operation.
+ * Represents a void (empty) schema in the OpenAPI Specification.
+ *
+ * The `OasVoid` class represents the absence of a value or content, commonly used
+ * in scenarios where operations don't return any content (like HTTP 204 No Content
+ * responses), optional properties that might not be present, or fallback cases
+ * in schema processing where no specific type is defined.
+ *
+ * This class serves as a type-safe representation of "nothing" in the OpenAPI
+ * type system, enabling proper handling of void responses and empty schemas
+ * throughout the SKMTC pipeline.
+ *
+ * ## Key Features
+ *
+ * - **Empty Content Representation**: Models operations that return no content
+ * - **Type Safety**: Provides a concrete type for void/empty scenarios
+ * - **Schema Processing**: Handles missing or undefined schema definitions
+ * - **Factory Pattern**: Convenient `empty()` static method for common usage
+ * - **Pipeline Integration**: Works seamlessly with the SKMTC processing pipeline
+ *
+ * @example Basic void schema for empty responses
+ * ```typescript
+ * import { OasVoid } from '@skmtc/core';
+ *
+ * const emptyResponse = new OasVoid({
+ *   title: 'No Content',
+ *   description: 'Operation completed successfully with no response body'
+ * });
+ *
+ * // Used for HTTP 204 No Content responses
+ * ```
+ *
+ * @example Using the empty factory method
+ * ```typescript
+ * const voidSchema = OasVoid.empty();
+ *
+ * // Equivalent to new OasVoid({})
+ * // Commonly used as a fallback or placeholder
+ * ```
+ *
+ * @example In operation responses
+ * ```typescript
+ * const deleteOperation = new OasOperation({
+ *   path: '/users/{id}',
+ *   method: 'delete',
+ *   responses: {
+ *     '204': new OasResponse({
+ *       description: 'User deleted successfully',
+ *       content: {
+ *         // No content for successful deletion
+ *       }
+ *     }),
+ *     '404': new OasResponse({
+ *       description: 'User not found'
+ *     })
+ *   }
+ * });
+ *
+ * // The void response indicates successful deletion with no return value
+ * ```
+ *
+ * @example As a schema fallback
+ * ```typescript
+ * function processSchema(schema: OasSchema | undefined): OasSchema {
+ *   if (!schema) {
+ *     return OasVoid.empty(); // Fallback for missing schemas
+ *   }
+ *   return schema;
+ * }
+ *
+ * // Ensures type safety even when schemas are missing
+ * ```
+ *
+ * @example In optional object properties
+ * ```typescript
+ * const userProfile = new OasObject({
+ *   properties: {
+ *     name: new OasString({ description: 'User name' }),
+ *     avatar: new OasString({
+ *       description: 'Avatar URL',
+ *       nullable: true
+ *     }),
+ *     // Some properties might be processed as void if not defined
+ *     metadata: processOptionalSchema(rawSchema.metadata) // might return OasVoid
+ *   }
+ * });
+ * ```
+ *
+ * @example HTTP operations with void responses
+ * ```typescript
+ * // Common HTTP operations that return void/empty content:
+ *
+ * // DELETE - Resource removal
+ * const deleteResponse = new OasVoid({
+ *   title: 'Deletion Successful',
+ *   description: 'Resource was successfully deleted'
+ * });
+ *
+ * // PUT - Update with no response body
+ * const updateResponse = new OasVoid({
+ *   title: 'Update Successful',
+ *   description: 'Resource was successfully updated'
+ * });
+ *
+ * // POST - Action with no return value
+ * const actionResponse = new OasVoid({
+ *   title: 'Action Completed',
+ *   description: 'Action was successfully performed'
+ * });
+ * ```
+ *
+ * @example In code generation
+ * ```typescript
+ * class TypeScriptGenerator extends ModelBase {
+ *   generateType(schema: OasSchema): string {
+ *     if (schema.type === 'void') {
+ *       return 'void'; // TypeScript void type
+ *     }
+ *     // Handle other types...
+ *     return 'unknown';
+ *   }
+ * }
+ *
+ * // Generates:
+ * // async function deleteUser(id: string): Promise<void>
+ * ```
  */
 export class OasVoid {
     constructor(fields = {}) {

package/package.json

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

package/script/context/RenderContext.d.ts

@@ -8,16 +8,206 @@ import type * as log from '../deps/jsr.io/@std/log/0.224.14/mod.js';
 import { File } from '../dsl/File.js';
 import type { Preview, Mapping } from '../types/Preview.js';
 import type { JsonFile } from '../dsl/JsonFile.js';
+/**
+ * Constructor arguments for {@link RenderContext}.
+ */
 type ConstructorArgs = {
+    /** Map of generated files to render */
     files: Map<string, File | JsonFile>;
+    /** Preview data for generated content */
     previews: Record<string, Record<string, Preview>>;
+    /** Mapping data for file relationships */
     mappings: Record<string, Record<string, Mapping>>;
+    /** Optional Prettier configuration for code formatting */
     prettierConfig?: PrettierConfigType;
+    /** Base path for resolving file paths */
     basePath: string | undefined;
+    /** Stack trail for distributed tracing */
     stackTrail: StackTrail;
+    /** Logger instance for debug information */
     logger: log.Logger;
+    /** Function to capture result status */
     captureCurrentResult: (result: ResultType) => void;
 };
+/**
+ * The rendering context for the final phase of the SKMTC transformation pipeline.
+ *
+ * `RenderContext` is responsible for taking the generated artifacts from the generation
+ * phase and rendering them into their final form with proper formatting, path resolution,
+ * and file preparation. It handles code formatting via Prettier, path normalization,
+ * and produces the final artifacts ready for writing to the filesystem.
+ *
+ * This context represents the culmination of the three-phase SKMTC pipeline, transforming
+ * generator outputs into production-ready code files with proper formatting and structure.
+ *
+ * ## Key Features
+ *
+ * - **Code Formatting**: Automatic Prettier formatting for generated TypeScript/JavaScript code
+ * - **Path Resolution**: Intelligent path resolution with base path support
+ * - **Content Collation**: Combines all generated content into organized file structures
+ * - **Metadata Generation**: Tracks file statistics (lines, characters) and relationships
+ * - **Error Tracking**: Comprehensive error handling with Sentry integration
+ * - **Performance Monitoring**: Built-in tracing and performance measurement
+ *
+ * @example Basic rendering usage
+ * ```typescript
+ * import { RenderContext } from '@skmtc/core';
+ *
+ * const renderContext = new RenderContext({
+ *   files: generatedFiles,
+ *   previews: previewData,
+ *   mappings: mappingData,
+ *   prettierConfig: {
+ *     semi: false,
+ *     singleQuote: true,
+ *     trailingComma: 'all'
+ *   },
+ *   basePath: './src/generated',
+ *   stackTrail: traceStack,
+ *   logger: myLogger,
+ *   captureCurrentResult: (result) => console.log(result)
+ * });
+ *
+ * const rendered = await renderContext.render();
+ *
+ * // Access rendered files
+ * Object.entries(rendered.artifacts).forEach(([path, content]) => {
+ *   console.log(`Rendered ${path}: ${rendered.files[path].lines} lines`);
+ *   // Write to filesystem
+ *   await Deno.writeTextFile(path, content);
+ * });
+ * ```
+ *
+ * @example With custom Prettier configuration
+ * ```typescript
+ * const renderContext = new RenderContext({
+ *   files: generatedFiles,
+ *   previews: {},
+ *   mappings: {},
+ *   prettierConfig: {
+ *     parser: 'typescript',
+ *     printWidth: 120,
+ *     tabWidth: 2,
+ *     semi: true,
+ *     singleQuote: true,
+ *     trailingComma: 'es5',
+ *     bracketSpacing: true,
+ *     arrowParens: 'avoid'
+ *   },
+ *   basePath: './packages/api-client/src',
+ *   stackTrail: stack,
+ *   logger: logger,
+ *   captureCurrentResult: resultHandler
+ * });
+ *
+ * const result = await renderContext.render();
+ *
+ * // All TypeScript files are automatically formatted
+ * console.log('Formatted files:', Object.keys(result.artifacts).length);
+ * ```
+ *
+ * @example Processing render results
+ * ```typescript
+ * const rendered = await renderContext.render();
+ *
+ * // Analyze file statistics
+ * const totalLines = Object.values(rendered.files)
+ *   .reduce((sum, file) => sum + file.lines, 0);
+ * const totalChars = Object.values(rendered.files)
+ *   .reduce((sum, file) => sum + file.characters, 0);
+ *
+ * console.log(`Generated ${Object.keys(rendered.artifacts).length} files`);
+ * console.log(`Total lines: ${totalLines}`);
+ * console.log(`Total characters: ${totalChars}`);
+ *
+ * // Check for large files
+ * const largeFiles = Object.entries(rendered.files)
+ *   .filter(([_, metadata]) => metadata.lines > 1000)
+ *   .map(([path, metadata]) => ({ path, lines: metadata.lines }));
+ *
+ * if (largeFiles.length > 0) {
+ *   console.log('Large files detected:', largeFiles);
+ * }
+ *
+ * // Access preview and mapping data
+ * console.log('Previews available:', Object.keys(rendered.previews));
+ * console.log('Mappings available:', Object.keys(rendered.mappings));
+ * ```
+ *
+ * @example Integration with CoreContext
+ * ```typescript
+ * // Typically used within CoreContext.toArtifacts()
+ * class CustomCoreContext extends CoreContext {
+ *   async renderWithPostProcessing(
+ *     files: Map<string, File | JsonFile>,
+ *     previews: Record<string, Record<string, Preview>>,
+ *     mappings: Record<string, Record<string, Mapping>>
+ *   ) {
+ *     const renderContext = new RenderContext({
+ *       files,
+ *       previews,
+ *       mappings,
+ *       prettierConfig: this.prettierConfig,
+ *       basePath: this.settings?.basePath,
+ *       stackTrail: this.stackTrail,
+ *       logger: this.logger,
+ *       captureCurrentResult: this.captureCurrentResult.bind(this)
+ *     });
+ *
+ *     const rendered = await renderContext.render();
+ *
+ *     // Post-process rendered files
+ *     const processedArtifacts: Record<string, string> = {};
+ *
+ *     for (const [path, content] of Object.entries(rendered.artifacts)) {
+ *       // Add file headers, license notices, etc.
+ *       const processedContent = this.addFileHeader(content, path);
+ *       processedArtifacts[path] = processedContent;
+ *     }
+ *
+ *     return {
+ *       ...rendered,
+ *       artifacts: processedArtifacts
+ *     };
+ *   }
+ * }
+ * ```
+ *
+ * @example Error handling during rendering
+ * ```typescript
+ * try {
+ *   const renderContext = new RenderContext({
+ *     files: generatedFiles,
+ *     previews: {},
+ *     mappings: {},
+ *     prettierConfig: prettierConfig,
+ *     basePath: './invalid-path', // This might cause issues
+ *     stackTrail: stack,
+ *     logger: logger,
+ *     captureCurrentResult: (result) => {
+ *       if (result === 'error') {
+ *         console.error('Render error detected');
+ *       }
+ *     }
+ *   });
+ *
+ *   const result = await renderContext.render();
+ *
+ *   // Check if any files failed to render
+ *   const failedFiles = Object.entries(result.files)
+ *     .filter(([path, metadata]) => metadata.lines === 0)
+ *     .map(([path]) => path);
+ *
+ *   if (failedFiles.length > 0) {
+ *     console.warn('Files with no content:', failedFiles);
+ *   }
+ *
+ * } catch (error) {
+ *   console.error('Render operation failed:', error);
+ *   // Sentry automatically captures the error
+ * }
+ * ```
+ */
 export declare class RenderContext {
     #private;
     files: Map<string, File | JsonFile>;

package/script/context/RenderContext.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RenderContext.d.ts","sourceRoot":"","sources":["../../src/context/RenderContext.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAA;AAEpE,OAAO,KAAK,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAEjE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AACtD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAA;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAA;AAGrD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AACjD,OAAO,KAAK,KAAK,GAAG,MAAM,yCAAyC,CAAA;AACnE,OAAO,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAA;AACrC,OAAO,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAE3D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAElD,KAAK,eAAe,GAAG;IACrB,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,IAAI,GAAG,QAAQ,CAAC,CAAA;IACnC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;IACjD,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;IACjD,cAAc,CAAC,EAAE,kBAAkB,CAAA;IACnC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAA;IAC5B,UAAU,EAAE,UAAU,CAAA;IACtB,MAAM,EAAE,GAAG,CAAC,MAAM,CAAA;IAClB,oBAAoB,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,IAAI,CAAA;CACnD,CAAA;AAsBD,qBAAa,aAAa;;IACxB,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,IAAI,GAAG,QAAQ,CAAC,CAAA;IACnC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;IACjD,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;IAEjD,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAA;IAC5B,MAAM,EAAE,GAAG,CAAC,MAAM,CAAA;IAElB,oBAAoB,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,IAAI,CAAA;gBACtC,EACV,KAAK,EACL,QAAQ,EACR,QAAQ,EACR,cAAc,EACd,QAAQ,EACR,MAAM,EACN,UAAU,EACV,oBAAoB,EACrB,EAAE,eAAe;IAWZ,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,YAAY,EAAE,SAAS,CAAC,CAAC;IAiBhD,OAAO,IAAI,OAAO,CAAC,iBAAiB,CAAC;IAuC3C,KAAK,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC;IAIlD,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,QAAQ;IAU1C,IAAI,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,EAAE,QAAQ,GAAG,UAAU,GAAG,SAAS;CAO7D"}
+{"version":3,"file":"RenderContext.d.ts","sourceRoot":"","sources":["../../src/context/RenderContext.ts"],"names":[],"mappings":"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"}

package/script/context/RenderContext.js

@@ -56,6 +56,185 @@ const toResolvedArtifactPath_js_1 = require("../helpers/toResolvedArtifactPath.j
 const tracer_js_1 = require("../helpers/tracer.js");
 const File_js_1 = require("../dsl/File.js");
 const prettier = __importStar(require("prettier"));
+/**
+ * The rendering context for the final phase of the SKMTC transformation pipeline.
+ *
+ * `RenderContext` is responsible for taking the generated artifacts from the generation
+ * phase and rendering them into their final form with proper formatting, path resolution,
+ * and file preparation. It handles code formatting via Prettier, path normalization,
+ * and produces the final artifacts ready for writing to the filesystem.
+ *
+ * This context represents the culmination of the three-phase SKMTC pipeline, transforming
+ * generator outputs into production-ready code files with proper formatting and structure.
+ *
+ * ## Key Features
+ *
+ * - **Code Formatting**: Automatic Prettier formatting for generated TypeScript/JavaScript code
+ * - **Path Resolution**: Intelligent path resolution with base path support
+ * - **Content Collation**: Combines all generated content into organized file structures
+ * - **Metadata Generation**: Tracks file statistics (lines, characters) and relationships
+ * - **Error Tracking**: Comprehensive error handling with Sentry integration
+ * - **Performance Monitoring**: Built-in tracing and performance measurement
+ *
+ * @example Basic rendering usage
+ * ```typescript
+ * import { RenderContext } from '@skmtc/core';
+ *
+ * const renderContext = new RenderContext({
+ *   files: generatedFiles,
+ *   previews: previewData,
+ *   mappings: mappingData,
+ *   prettierConfig: {
+ *     semi: false,
+ *     singleQuote: true,
+ *     trailingComma: 'all'
+ *   },
+ *   basePath: './src/generated',
+ *   stackTrail: traceStack,
+ *   logger: myLogger,
+ *   captureCurrentResult: (result) => console.log(result)
+ * });
+ *
+ * const rendered = await renderContext.render();
+ *
+ * // Access rendered files
+ * Object.entries(rendered.artifacts).forEach(([path, content]) => {
+ *   console.log(`Rendered ${path}: ${rendered.files[path].lines} lines`);
+ *   // Write to filesystem
+ *   await Deno.writeTextFile(path, content);
+ * });
+ * ```
+ *
+ * @example With custom Prettier configuration
+ * ```typescript
+ * const renderContext = new RenderContext({
+ *   files: generatedFiles,
+ *   previews: {},
+ *   mappings: {},
+ *   prettierConfig: {
+ *     parser: 'typescript',
+ *     printWidth: 120,
+ *     tabWidth: 2,
+ *     semi: true,
+ *     singleQuote: true,
+ *     trailingComma: 'es5',
+ *     bracketSpacing: true,
+ *     arrowParens: 'avoid'
+ *   },
+ *   basePath: './packages/api-client/src',
+ *   stackTrail: stack,
+ *   logger: logger,
+ *   captureCurrentResult: resultHandler
+ * });
+ *
+ * const result = await renderContext.render();
+ *
+ * // All TypeScript files are automatically formatted
+ * console.log('Formatted files:', Object.keys(result.artifacts).length);
+ * ```
+ *
+ * @example Processing render results
+ * ```typescript
+ * const rendered = await renderContext.render();
+ *
+ * // Analyze file statistics
+ * const totalLines = Object.values(rendered.files)
+ *   .reduce((sum, file) => sum + file.lines, 0);
+ * const totalChars = Object.values(rendered.files)
+ *   .reduce((sum, file) => sum + file.characters, 0);
+ *
+ * console.log(`Generated ${Object.keys(rendered.artifacts).length} files`);
+ * console.log(`Total lines: ${totalLines}`);
+ * console.log(`Total characters: ${totalChars}`);
+ *
+ * // Check for large files
+ * const largeFiles = Object.entries(rendered.files)
+ *   .filter(([_, metadata]) => metadata.lines > 1000)
+ *   .map(([path, metadata]) => ({ path, lines: metadata.lines }));
+ *
+ * if (largeFiles.length > 0) {
+ *   console.log('Large files detected:', largeFiles);
+ * }
+ *
+ * // Access preview and mapping data
+ * console.log('Previews available:', Object.keys(rendered.previews));
+ * console.log('Mappings available:', Object.keys(rendered.mappings));
+ * ```
+ *
+ * @example Integration with CoreContext
+ * ```typescript
+ * // Typically used within CoreContext.toArtifacts()
+ * class CustomCoreContext extends CoreContext {
+ *   async renderWithPostProcessing(
+ *     files: Map<string, File | JsonFile>,
+ *     previews: Record<string, Record<string, Preview>>,
+ *     mappings: Record<string, Record<string, Mapping>>
+ *   ) {
+ *     const renderContext = new RenderContext({
+ *       files,
+ *       previews,
+ *       mappings,
+ *       prettierConfig: this.prettierConfig,
+ *       basePath: this.settings?.basePath,
+ *       stackTrail: this.stackTrail,
+ *       logger: this.logger,
+ *       captureCurrentResult: this.captureCurrentResult.bind(this)
+ *     });
+ *
+ *     const rendered = await renderContext.render();
+ *
+ *     // Post-process rendered files
+ *     const processedArtifacts: Record<string, string> = {};
+ *
+ *     for (const [path, content] of Object.entries(rendered.artifacts)) {
+ *       // Add file headers, license notices, etc.
+ *       const processedContent = this.addFileHeader(content, path);
+ *       processedArtifacts[path] = processedContent;
+ *     }
+ *
+ *     return {
+ *       ...rendered,
+ *       artifacts: processedArtifacts
+ *     };
+ *   }
+ * }
+ * ```
+ *
+ * @example Error handling during rendering
+ * ```typescript
+ * try {
+ *   const renderContext = new RenderContext({
+ *     files: generatedFiles,
+ *     previews: {},
+ *     mappings: {},
+ *     prettierConfig: prettierConfig,
+ *     basePath: './invalid-path', // This might cause issues
+ *     stackTrail: stack,
+ *     logger: logger,
+ *     captureCurrentResult: (result) => {
+ *       if (result === 'error') {
+ *         console.error('Render error detected');
+ *       }
+ *     }
+ *   });
+ *
+ *   const result = await renderContext.render();
+ *
+ *   // Check if any files failed to render
+ *   const failedFiles = Object.entries(result.files)
+ *     .filter(([path, metadata]) => metadata.lines === 0)
+ *     .map(([path]) => path);
+ *
+ *   if (failedFiles.length > 0) {
+ *     console.warn('Files with no content:', failedFiles);
+ *   }
+ *
+ * } catch (error) {
+ *   console.error('Render operation failed:', error);
+ *   // Sentry automatically captures the error
+ * }
+ * ```
+ */
 class RenderContext {
     constructor({ files, previews, mappings, prettierConfig, basePath, logger, stackTrail, captureCurrentResult }) {
         Object.defineProperty(this, "files", {