@skmtc/core 0.0.789 → 0.0.790

package/esm/oas/boolean/Boolean.js

@@ -1,6 +1,135 @@
 import "../../_dnt.polyfills.js";
 /**
- * Object representing a boolean in the OpenAPI Specification.
+ * Represents a boolean schema in the OpenAPI Specification.
+ *
+ * The `OasBoolean` class handles boolean data types in OpenAPI schemas, supporting
+ * both simple true/false values and more complex boolean schemas with constraints,
+ * enumerations, and nullable types. This class provides type-safe boolean handling
+ * with optional null value support through generic typing.
+ *
+ * ## Key Features
+ *
+ * - **Type Safety**: Generic nullable type support with proper TypeScript inference
+ * - **Enum Support**: Constrain boolean values to specific true/false combinations
+ * - **Null Handling**: Optional null value support for nullable boolean types
+ * - **Validation**: Default values and example validation
+ * - **JSON Schema**: Converts to standard JSON Schema format for validation
+ * - **Documentation**: Rich metadata support for API documentation
+ *
+ * @template Nullable - Whether the boolean value itself can be null
+ *
+ * @example Basic boolean schema
+ * ```typescript
+ * import { OasBoolean } from '@skmtc/core';
+ *
+ * const isActiveSchema = new OasBoolean({
+ *   title: 'Active Status',
+ *   description: 'Whether the user account is active',
+ *   default: true,
+ *   example: true
+ * });
+ *
+ * // This represents: boolean with default true
+ * ```
+ *
+ * @example Nullable boolean schema
+ * ```typescript
+ * const nullableFlag = new OasBoolean<true>({
+ *   title: 'Optional Flag',
+ *   description: 'An optional boolean flag that can be null',
+ *   nullable: true,
+ *   default: null,
+ *   example: true
+ * });
+ *
+ * // This represents: boolean | null
+ * ```
+ *
+ * @example Boolean with enum constraints
+ * ```typescript
+ * const strictBoolean = new OasBoolean({
+ *   title: 'Confirmation',
+ *   description: 'Must explicitly be true to confirm action',
+ *   enums: [true], // Only true is allowed
+ *   example: true
+ * });
+ *
+ * // This only accepts true, effectively making it required
+ * ```
+ *
+ * @example Boolean with null in enum
+ * ```typescript
+ * const triStateBoolean = new OasBoolean<true>({
+ *   title: 'Approval Status',
+ *   description: 'Approval can be true (approved), false (denied), or null (pending)',
+ *   nullable: true,
+ *   enums: [true, false, null],
+ *   default: null,
+ *   example: null
+ * });
+ *
+ * // This represents: true | false | null (tri-state logic)
+ * ```
+ *
+ * @example Feature flag schema
+ * ```typescript
+ * const featureFlag = new OasBoolean({
+ *   title: 'Feature Enabled',
+ *   description: 'Whether the new feature is enabled for this user',
+ *   default: false,
+ *   example: false
+ * });
+ *
+ * // Used in configuration objects
+ * const userConfig = new OasObject({
+ *   properties: {
+ *     darkMode: featureFlag,
+ *     notifications: featureFlag,
+ *     betaFeatures: featureFlag
+ *   }
+ * });
+ * ```
+ *
+ * @example Consent and agreement booleans
+ * ```typescript
+ * const consentSchema = new OasBoolean({
+ *   title: 'Terms Accepted',
+ *   description: 'User has accepted the terms and conditions',
+ *   enums: [true], // Must be true to be valid
+ *   example: true
+ * });
+ *
+ * const privacyConsent = new OasBoolean({
+ *   title: 'Privacy Policy Accepted',
+ *   description: 'User has accepted the privacy policy',
+ *   default: false,
+ *   example: true
+ * });
+ *
+ * // Used in registration forms where consent is required
+ * ```
+ *
+ * @example Optional settings with nullable booleans
+ * ```typescript
+ * const userPreferences = new OasObject({
+ *   properties: {
+ *     emailNotifications: new OasBoolean<true>({
+ *       title: 'Email Notifications',
+ *       description: 'Enable email notifications (null means use default)',
+ *       nullable: true,
+ *       default: null
+ *     }),
+ *     smsNotifications: new OasBoolean<true>({
+ *       title: 'SMS Notifications',
+ *       description: 'Enable SMS notifications (null means not set)',
+ *       nullable: true,
+ *       default: null
+ *     })
+ *   }
+ * });
+ *
+ * // Allows: { emailNotifications: true, smsNotifications: null }
+ * ```
  */
 export class OasBoolean {
     constructor(fields = {}) {

package/esm/oas/parameter/Parameter.d.ts

@@ -6,21 +6,181 @@ import type { OasExample } from '../example/Example.js';
 import type { OasSchema } from '../schema/Schema.js';
 import type { ToJsonSchemaOptions } from '../schema/Schema.js';
 import type { OpenAPIV3 } from 'openapi-types';
+/**
+ * Constructor fields for {@link OasParameter}.
+ */
 export type ParameterFields = {
+    /** The name of the parameter */
     name: string;
+    /** The location of the parameter (path, query, header, cookie) */
     location: OasParameterLocation;
+    /** A brief description of the parameter */
     description?: string | undefined;
+    /** Determines whether this parameter is mandatory */
     required?: boolean | undefined;
+    /** Specifies that the parameter is deprecated */
     deprecated?: boolean | undefined;
+    /** Whether to allow empty values for the parameter */
     allowEmptyValue?: boolean | undefined;
+    /** Whether reserved characters are allowed in the parameter value */
     allowReserved?: boolean | undefined;
+    /** The schema defining the parameter's data type */
     schema?: OasSchema | OasRef<'schema'> | undefined;
+    /** Example values for the parameter */
     examples?: Record<string, OasExample | OasRef<'example'>> | undefined;
+    /** Media type definitions for the parameter content */
     content?: Record<string, OasMediaType> | undefined;
+    /** The serialization style for the parameter */
     style: OasParameterStyle;
+    /** Whether to explode parameter values */
     explode: boolean;
+    /** Custom extension fields (x-* properties) */
     extensionFields?: Record<string, unknown>;
 };
+/**
+ * Represents a Parameter Object in the OpenAPI Specification.
+ *
+ * The `OasParameter` class encapsulates the definition of a single operation parameter,
+ * including its location, data type, validation rules, and serialization behavior.
+ * Parameters can be located in the path, query string, headers, or cookies.
+ *
+ * This class provides comprehensive support for parameter validation, serialization
+ * styles, and complex data types through schema definitions or content specifications.
+ *
+ * ## Key Features
+ *
+ * - **Location Support**: Path, query, header, and cookie parameters
+ * - **Schema Validation**: Comprehensive data type validation through schemas
+ * - **Serialization Styles**: Various parameter serialization formats
+ * - **Content Types**: Support for complex parameter content with media types
+ * - **Examples & Documentation**: Parameter examples and descriptive documentation
+ * - **Advanced Options**: Empty values, reserved characters, and explode behavior
+ *
+ * @example Basic path parameter
+ * ```typescript
+ * import { OasParameter, OasString } from '@skmtc/core';
+ *
+ * const userIdParam = new OasParameter({
+ *   name: 'userId',
+ *   location: 'path',
+ *   description: 'Unique identifier for the user',
+ *   required: true,
+ *   schema: new OasString({
+ *     pattern: '^[0-9a-f]{24}$',
+ *     example: '507f1f77bcf86cd799439011'
+ *   }),
+ *   style: 'simple',
+ *   explode: false
+ * });
+ *
+ * // Used in path: /users/{userId}
+ * ```
+ *
+ * @example Query parameter with validation
+ * ```typescript
+ * const pageSizeParam = new OasParameter({
+ *   name: 'pageSize',
+ *   location: 'query',
+ *   description: 'Number of items to return per page',
+ *   required: false,
+ *   schema: new OasInteger({
+ *     minimum: 1,
+ *     maximum: 100,
+ *     default: 20
+ *   }),
+ *   style: 'form',
+ *   explode: true,
+ *   examples: {
+ *     small: new OasExample({ value: 10 }),
+ *     medium: new OasExample({ value: 25 }),
+ *     large: new OasExample({ value: 50 })
+ *   }
+ * });
+ *
+ * // Used in query: ?pageSize=20
+ * ```
+ *
+ * @example Header parameter
+ * ```typescript
+ * const authHeaderParam = new OasParameter({
+ *   name: 'Authorization',
+ *   location: 'header',
+ *   description: 'Bearer token for authentication',
+ *   required: true,
+ *   schema: new OasString({
+ *     pattern: '^Bearer [A-Za-z0-9+/=]+$',
+ *     example: 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
+ *   }),
+ *   style: 'simple',
+ *   explode: false
+ * });
+ * ```
+ *
+ * @example Complex parameter with content
+ * ```typescript
+ * const filterParam = new OasParameter({
+ *   name: 'filter',
+ *   location: 'query',
+ *   description: 'Complex filter object',
+ *   required: false,
+ *   content: {
+ *     'application/json': new OasMediaType({
+ *       schema: new OasObject({
+ *         properties: {
+ *           category: new OasString(),
+ *           priceRange: new OasObject({
+ *             properties: {
+ *               min: new OasNumber(),
+ *               max: new OasNumber()
+ *             }
+ *           })
+ *         }
+ *       })
+ *     })
+ *   },
+ *   style: 'deepObject',
+ *   explode: true
+ * });
+ *
+ * // Used as: ?filter[category]=electronics&filter[priceRange][min]=100
+ * ```
+ *
+ * @example Array parameter with explode
+ * ```typescript
+ * const tagsParam = new OasParameter({
+ *   name: 'tags',
+ *   location: 'query',
+ *   description: 'Filter by multiple tags',
+ *   required: false,
+ *   schema: new OasArray({
+ *     items: new OasString(),
+ *     minItems: 1,
+ *     maxItems: 10
+ *   }),
+ *   style: 'form',
+ *   explode: true // Results in: ?tags=tech&tags=api&tags=rest
+ * });
+ *
+ * // Without explode: ?tags=tech,api,rest
+ * // With explode: ?tags=tech&tags=api&tags=rest
+ * ```
+ *
+ * @example Cookie parameter
+ * ```typescript
+ * const sessionParam = new OasParameter({
+ *   name: 'sessionId',
+ *   location: 'cookie',
+ *   description: 'Session identifier cookie',
+ *   required: false,
+ *   schema: new OasString({
+ *     minLength: 32,
+ *     maxLength: 128
+ *   }),
+ *   style: 'form',
+ *   explode: false
+ * });
+ * ```
+ */
 export declare class OasParameter {
     oasType: 'parameter';
     name: string;

package/esm/oas/parameter/Parameter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Parameter.d.ts","sourceRoot":"","sources":["../../../src/oas/parameter/Parameter.ts"],"names":[],"mappings":"AAAA,OAAO,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAA;AACnF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAA;AAC7D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAA;AAC3C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAA;AACvD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AACpD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AAC9D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAK9C,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,oBAAoB,CAAA;IAC9B,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAChC,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IAC9B,UAAU,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IAChC,eAAe,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IACrC,aAAa,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IACnC,MAAM,CAAC,EAAE,SAAS,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,SAAS,CAAA;IACjD,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC,GAAG,SAAS,CAAA;IACrE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,GAAG,SAAS,CAAA;IAClD,KAAK,EAAE,iBAAiB,CAAA;IACxB,OAAO,EAAE,OAAO,CAAA;IAChB,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC1C,CAAA;AAED,qBAAa,YAAY;IACvB,OAAO,EAAE,WAAW,CAAc;IAClC,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,oBAAoB,CAAA;IAC9B,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAChC,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IAC9B,UAAU,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IAChC,eAAe,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IACrC,aAAa,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IACnC,MAAM,CAAC,EAAE,SAAS,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,SAAS,CAAA;IACjD,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC,GAAG,SAAS,CAAA;IACrE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,GAAG,SAAS,CAAA;IAClD,KAAK,EAAE,iBAAiB,CAAA;IACxB,OAAO,EAAE,OAAO,CAAA;IAChB,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAA;gBACxC,MAAM,EAAE,eAAe;IAkBnC,KAAK,IAAI,IAAI,IAAI,MAAM,CAAC,WAAW,CAAC;IAIpC,OAAO,IAAI,YAAY;IAIvB,WAAW,IAAI,YAAY;IAI3B,QAAQ,CAAC,SAAS,GAAE,MAA2B,GAAG,SAAS,GAAG,MAAM,CAAC,QAAQ,CAAC;IAc9E,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,SAAS,CAAC,eAAe;CAuBtE"}
+{"version":3,"file":"Parameter.d.ts","sourceRoot":"","sources":["../../../src/oas/parameter/Parameter.ts"],"names":[],"mappings":"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"}

package/esm/oas/parameter/Parameter.js

@@ -1,4 +1,148 @@
 import "../../_dnt.polyfills.js";
+/**
+ * Represents a Parameter Object in the OpenAPI Specification.
+ *
+ * The `OasParameter` class encapsulates the definition of a single operation parameter,
+ * including its location, data type, validation rules, and serialization behavior.
+ * Parameters can be located in the path, query string, headers, or cookies.
+ *
+ * This class provides comprehensive support for parameter validation, serialization
+ * styles, and complex data types through schema definitions or content specifications.
+ *
+ * ## Key Features
+ *
+ * - **Location Support**: Path, query, header, and cookie parameters
+ * - **Schema Validation**: Comprehensive data type validation through schemas
+ * - **Serialization Styles**: Various parameter serialization formats
+ * - **Content Types**: Support for complex parameter content with media types
+ * - **Examples & Documentation**: Parameter examples and descriptive documentation
+ * - **Advanced Options**: Empty values, reserved characters, and explode behavior
+ *
+ * @example Basic path parameter
+ * ```typescript
+ * import { OasParameter, OasString } from '@skmtc/core';
+ *
+ * const userIdParam = new OasParameter({
+ *   name: 'userId',
+ *   location: 'path',
+ *   description: 'Unique identifier for the user',
+ *   required: true,
+ *   schema: new OasString({
+ *     pattern: '^[0-9a-f]{24}$',
+ *     example: '507f1f77bcf86cd799439011'
+ *   }),
+ *   style: 'simple',
+ *   explode: false
+ * });
+ *
+ * // Used in path: /users/{userId}
+ * ```
+ *
+ * @example Query parameter with validation
+ * ```typescript
+ * const pageSizeParam = new OasParameter({
+ *   name: 'pageSize',
+ *   location: 'query',
+ *   description: 'Number of items to return per page',
+ *   required: false,
+ *   schema: new OasInteger({
+ *     minimum: 1,
+ *     maximum: 100,
+ *     default: 20
+ *   }),
+ *   style: 'form',
+ *   explode: true,
+ *   examples: {
+ *     small: new OasExample({ value: 10 }),
+ *     medium: new OasExample({ value: 25 }),
+ *     large: new OasExample({ value: 50 })
+ *   }
+ * });
+ *
+ * // Used in query: ?pageSize=20
+ * ```
+ *
+ * @example Header parameter
+ * ```typescript
+ * const authHeaderParam = new OasParameter({
+ *   name: 'Authorization',
+ *   location: 'header',
+ *   description: 'Bearer token for authentication',
+ *   required: true,
+ *   schema: new OasString({
+ *     pattern: '^Bearer [A-Za-z0-9+/=]+$',
+ *     example: 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
+ *   }),
+ *   style: 'simple',
+ *   explode: false
+ * });
+ * ```
+ *
+ * @example Complex parameter with content
+ * ```typescript
+ * const filterParam = new OasParameter({
+ *   name: 'filter',
+ *   location: 'query',
+ *   description: 'Complex filter object',
+ *   required: false,
+ *   content: {
+ *     'application/json': new OasMediaType({
+ *       schema: new OasObject({
+ *         properties: {
+ *           category: new OasString(),
+ *           priceRange: new OasObject({
+ *             properties: {
+ *               min: new OasNumber(),
+ *               max: new OasNumber()
+ *             }
+ *           })
+ *         }
+ *       })
+ *     })
+ *   },
+ *   style: 'deepObject',
+ *   explode: true
+ * });
+ *
+ * // Used as: ?filter[category]=electronics&filter[priceRange][min]=100
+ * ```
+ *
+ * @example Array parameter with explode
+ * ```typescript
+ * const tagsParam = new OasParameter({
+ *   name: 'tags',
+ *   location: 'query',
+ *   description: 'Filter by multiple tags',
+ *   required: false,
+ *   schema: new OasArray({
+ *     items: new OasString(),
+ *     minItems: 1,
+ *     maxItems: 10
+ *   }),
+ *   style: 'form',
+ *   explode: true // Results in: ?tags=tech&tags=api&tags=rest
+ * });
+ *
+ * // Without explode: ?tags=tech,api,rest
+ * // With explode: ?tags=tech&tags=api&tags=rest
+ * ```
+ *
+ * @example Cookie parameter
+ * ```typescript
+ * const sessionParam = new OasParameter({
+ *   name: 'sessionId',
+ *   location: 'cookie',
+ *   description: 'Session identifier cookie',
+ *   required: false,
+ *   schema: new OasString({
+ *     minLength: 32,
+ *     maxLength: 128
+ *   }),
+ *   style: 'form',
+ *   explode: false
+ * });
+ * ```
+ */
 export class OasParameter {
     constructor(fields) {
         Object.defineProperty(this, "oasType", {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skmtc/core",
-  "version": "0.0.789",
+  "version": "0.0.790",
   "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>;