@skmtc/core 0.0.800 → 0.0.802

package/esm/context/RenderContext.js

@@ -9,7 +9,7 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
     if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
     return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
 };
-var _RenderContext_prettierConfig, _RenderContext_stackTrail;
+var _RenderContext_prettierConfig, _RenderContext_logger, _RenderContext_stackTrail;
 import * as Sentry from '@sentry/node';
 import invariant from 'tiny-invariant';
 import { normalize } from '../deps/jsr.io/@std/path/1.1.2/normalize.js';
@@ -138,7 +138,7 @@ import * as prettier from 'prettier';
  *       prettierConfig: this.prettierConfig,
  *       basePath: this.settings?.basePath,
  *       stackTrail: this.stackTrail,
- *       logger: this.logger,
+ *       logger: this.#logger,
  *       captureCurrentResult: this.captureCurrentResult.bind(this)
  *     });
  *
@@ -197,39 +197,50 @@ import * as prettier from 'prettier';
  * ```
  */
 export class RenderContext {
+    /**
+     * Creates a new RenderContext instance with the specified configuration.
+     *
+     * Initializes the rendering context with files to render, preview data,
+     * formatting configuration, and logging/tracing infrastructure.
+     *
+     * @param args - Constructor arguments containing all required configuration
+     */
     constructor({ files, previews, mappings, prettierConfig, basePath, logger, stackTrail, captureCurrentResult }) {
+        /** Map of generated files to render */
         Object.defineProperty(this, "files", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /** Preview data for generated content */
         Object.defineProperty(this, "previews", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /** Mapping data for file relationships */
         Object.defineProperty(this, "mappings", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /** Optional Prettier configuration for code formatting */
         _RenderContext_prettierConfig.set(this, void 0);
+        /** Base path for resolving file paths */
         Object.defineProperty(this, "basePath", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
-        Object.defineProperty(this, "logger", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
+        /** Logger instance for debug information */
+        _RenderContext_logger.set(this, void 0);
+        /** Stack trail for distributed tracing */
         _RenderContext_stackTrail.set(this, void 0);
+        /** Function to capture result status */
         Object.defineProperty(this, "captureCurrentResult", {
             enumerable: true,
             configurable: true,
@@ -241,10 +252,44 @@ export class RenderContext {
         this.mappings = mappings;
         __classPrivateFieldSet(this, _RenderContext_prettierConfig, prettierConfig, "f");
         this.basePath = basePath;
-        this.logger = logger;
+        __classPrivateFieldSet(this, _RenderContext_logger, logger, "f");
         __classPrivateFieldSet(this, _RenderContext_stackTrail, stackTrail, "f");
         this.captureCurrentResult = captureCurrentResult;
     }
+    /**
+     * Renders all files in the context to their final formatted form.
+     *
+     * This is the main rendering method that orchestrates the collation and
+     * formatting of all generated files. It processes files through Prettier
+     * formatting (if configured), resolves paths, and produces the final
+     * artifacts ready for writing to the filesystem.
+     *
+     * The method is wrapped in Sentry tracing spans for performance monitoring
+     * and includes both collation and artifact preparation phases.
+     *
+     * @returns Promise resolving to render result containing artifacts, file metadata, previews, and mappings
+     *
+     * @example
+     * ```typescript
+     * const renderContext = new RenderContext({
+     *   files: generatedFiles,
+     *   previews: previewData,
+     *   mappings: mappingData,
+     *   prettierConfig: { semi: false, singleQuote: true },
+     *   basePath: './src/generated',
+     *   stackTrail: traceStack,
+     *   logger: logger,
+     *   captureCurrentResult: resultHandler
+     * });
+     *
+     * const result = await renderContext.render();
+     *
+     * // Access rendered files
+     * Object.entries(result.artifacts).forEach(([path, content]) => {
+     *   console.log(`Rendered ${path}: ${result.files[path].lines} lines`);
+     * });
+     * ```
+     */
     async render() {
         return await Sentry.startSpan({ name: 'Render artifacts' }, async () => {
             const result = await Sentry.startSpan({ name: 'Collate content' }, async () => {
@@ -259,6 +304,33 @@ export class RenderContext {
             return rendered;
         });
     }
+    /**
+     * Collates all files in the context into a unified render result.
+     *
+     * This method processes each file in the context through the rendering pipeline,
+     * applying Prettier formatting and path resolution. It coordinates the parallel
+     * processing of all files and aggregates the results into a single output structure.
+     *
+     * The collation process includes:
+     * - File content rendering with optional Prettier formatting
+     * - Path resolution using base path configuration
+     * - Metadata calculation (line count, character count)
+     * - Result aggregation into artifacts and file metadata maps
+     *
+     * @returns Promise resolving to collated files with artifacts and metadata
+     *
+     * @example
+     * ```typescript
+     * const collated = await renderContext.collate();
+     *
+     * // Access rendered file content
+     * console.log(collated.artifacts['/path/to/file.ts']);
+     *
+     * // Access file metadata
+     * console.log(collated.files['/path/to/file.ts'].lines);
+     * console.log(collated.files['/path/to/file.ts'].characters);
+     * ```
+     */
     async collate() {
         const fileEntries = Array.from(this.files.entries());
         const fileObjectPromises = fileEntries
@@ -290,22 +362,124 @@ export class RenderContext {
         }
         return output;
     }
+    /**
+     * Executes a function within a tracing context for performance monitoring.
+     *
+     * This method wraps function execution with distributed tracing capabilities,
+     * allowing performance monitoring and debugging of the rendering pipeline.
+     * It integrates with the stack trail to provide hierarchical tracing.
+     *
+     * @template T - The return type of the traced function
+     * @param token - Trace identifier (string or array of strings)
+     * @param fn - Function to execute within the trace context
+     * @returns The result of executing the traced function
+     *
+     * @example
+     * ```typescript
+     * const result = renderContext.trace('format-file', () => {
+     *   return prettier.format(content, prettierConfig);
+     * });
+     *
+     * // With hierarchical tracing
+     * const result = renderContext.trace(['render', 'format'], () => {
+     *   return complexFormattingOperation();
+     * });
+     * ```
+     */
     trace(token, fn) {
-        return tracer(__classPrivateFieldGet(this, _RenderContext_stackTrail, "f"), token, fn, this.logger);
+        return tracer(__classPrivateFieldGet(this, _RenderContext_stackTrail, "f"), token, fn, __classPrivateFieldGet(this, _RenderContext_logger, "f"));
     }
+    /**
+     * Retrieves a file from the context by its normalized path.
+     *
+     * This method looks up a file in the context's file map using path normalization
+     * to ensure consistent path resolution. It validates that the requested file
+     * exists and throws an error if not found.
+     *
+     * @param filePath - The file path to retrieve (will be normalized)
+     * @returns The File or JsonFile instance
+     * @throws {Error} When the file is not found in the context
+     *
+     * @example
+     * ```typescript
+     * const file = renderContext.getFile('./src/models/User.ts');
+     * console.log(file.toString()); // Access file content
+     *
+     * // Works with various path formats
+     * const sameFile = renderContext.getFile('src/models/User.ts');
+     * const alsoSameFile = renderContext.getFile('/absolute/path/src/models/User.ts');
+     * ```
+     */
     getFile(filePath) {
         const normalisedPath = normalize(filePath);
         const currentFile = this.files.get(normalisedPath);
         invariant(currentFile, `File not found during render phase: ${normalisedPath}`);
         return currentFile;
     }
+    /**
+     * Picks a specific definition from a file in the context.
+     *
+     * This method retrieves a named definition (type, interface, etc.) from
+     * a specific file in the context. It validates that the target file is
+     * a File type (not JsonFile) and returns the requested definition if found.
+     *
+     * @param args - Object containing the definition name and export path
+     * @param args.name - The name of the definition to retrieve
+     * @param args.exportPath - The path to the file containing the definition
+     * @returns The Definition instance if found, undefined otherwise
+     * @throws {Error} When the file is not found or is not a File type
+     *
+     * @example
+     * ```typescript
+     * const userDefinition = renderContext.pick({
+     *   name: 'User',
+     *   exportPath: './src/models/User.ts'
+     * });
+     *
+     * if (userDefinition) {
+     *   console.log(userDefinition.identifier); // Access definition details
+     * }
+     *
+     * // Pick interface definition
+     * const apiInterface = renderContext.pick({
+     *   name: 'ApiResponse',
+     *   exportPath: './src/types/api.ts'
+     * });
+     * ```
+     */
     pick({ name, exportPath }) {
         const file = this.getFile(exportPath);
         invariant(file instanceof File, `File at "${exportPath}" is not a "File" type`);
         return file.definitions.get(name);
     }
 }
-_RenderContext_prettierConfig = new WeakMap(), _RenderContext_stackTrail = new WeakMap();
+_RenderContext_prettierConfig = new WeakMap(), _RenderContext_logger = new WeakMap(), _RenderContext_stackTrail = new WeakMap();
+/**
+ * Renders a single file with formatting and metadata calculation.
+ *
+ * This function processes a single file through the rendering pipeline,
+ * applying Prettier formatting if configured and calculating file metadata
+ * such as line count and character count. It resolves the final path using
+ * the base path configuration.
+ *
+ * @param args - File rendering arguments
+ * @returns Promise resolving to a FileObject with content and metadata
+ *
+ * @example
+ * ```typescript
+ * const fileObject = await renderFile({
+ *   content: 'const x = 1;',
+ *   destinationPath: 'utils.ts',
+ *   basePath: './src',
+ *   prettierConfig: { semi: false }
+ * });
+ *
+ * console.log(fileObject.path); // './src/utils.ts'
+ * console.log(fileObject.content); // 'const x = 1' (formatted)
+ * console.log(fileObject.lines); // 1
+ * console.log(fileObject.characters); // 11
+ * ```
+ */
 const renderFile = async ({ content, destinationPath, basePath, prettierConfig }) => {
     const path = toResolvedArtifactPath({ basePath, destinationPath });
     const formatted = prettierConfig

package/esm/context/types.d.ts

@@ -3,24 +3,54 @@ import type { ManifestEntry } from '../types/Manifest.js';
 import type { Mapping, Preview } from '../types/Preview.js';
 import type { ResultsItem } from '../types/Results.js';
 import type { OpenAPIV2, OpenAPIV3, OpenAPIV3_1 } from 'openapi-types';
+/**
+ * Type representing the three phases of the SKMTC pipeline.
+ */
 export type PhaseType = 'parse' | 'generate' | 'render';
+/**
+ * Options for retrieving files from the context.
+ */
 export type GetFileOptions = {
+    /** Whether to throw an error if the file is not found */
     throwIfNotFound?: boolean;
 };
+/**
+ * Arguments for adding a generator key to the context.
+ */
 export type AddGeneratorKeyArgs = {
+    /** The generator key to add */
     generatorKey: GeneratorKey;
 };
+/**
+ * Result of rendering files in the context.
+ */
 export type FilesRenderResult = {
+    /** Map of file paths to rendered content */
     artifacts: Record<string, string>;
+    /** Map of file paths to metadata */
     files: Record<string, ManifestEntry>;
 };
+/**
+ * Complete result of the rendering phase including all generated content and metadata.
+ */
 export type RenderResult = {
+    /** Map of file paths to rendered content */
     artifacts: Record<string, string>;
+    /** Map of file paths to metadata */
     files: Record<string, ManifestEntry>;
+    /** Preview data for generated content */
     previews: Record<string, Record<string, Preview>>;
+    /** Mapping data for file relationships */
     mappings: Record<string, Record<string, Mapping>>;
+    /** Hierarchical results tracking */
     results: ResultsItem;
 };
+/**
+ * Union type representing any supported OpenAPI document version.
+ */
 export type AnyOasDocument = OpenAPIV2.Document | OpenAPIV3.Document | OpenAPIV3_1.Document;
+/**
+ * Types of issues that can be encountered during OpenAPI schema parsing.
+ */
 export type IssueType = 'UNEXPECTED_PROPERTY' | 'MISSING_OBJECT_TYPE' | 'MISSING_STRING_TYPE' | 'MISSING_ARRAY_TYPE' | 'MISSING_BOOLEAN_TYPE' | 'INVALID_EXAMPLE' | 'INVALID_ENUM' | 'INVALID_DEFAULT' | 'INVALID_NULLABLE' | 'UNEXPECTED_FORMAT' | 'INVALID_RESPONSE' | 'INVALID_FORMAT' | 'INVALID_OPERATION' | 'INVALID_SCHEMA' | 'INVALID_PARAMETER' | 'INVALID_DEPENDENCY_REF';
 //# sourceMappingURL=types.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/context/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAA;AAC7D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AACzD,OAAO,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAC3D,OAAO,KAAK,EAAc,WAAW,EAAE,MAAM,qBAAqB,CAAA;AAClE,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAEtE,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,UAAU,GAAG,QAAQ,CAAA;AAEvD,MAAM,MAAM,cAAc,GAAG;IAC3B,eAAe,CAAC,EAAE,OAAO,CAAA;CAC1B,CAAA;AAED,MAAM,MAAM,mBAAmB,GAAG;IAChC,YAAY,EAAE,YAAY,CAAA;CAC3B,CAAA;AAED,MAAM,MAAM,iBAAiB,GAAG;IAC9B,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACjC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAA;CACrC,CAAA;AAED,MAAM,MAAM,YAAY,GAAG;IACzB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACjC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAA;IACpC,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,OAAO,EAAE,WAAW,CAAA;CACrB,CAAA;AAED,MAAM,MAAM,cAAc,GAAG,SAAS,CAAC,QAAQ,GAAG,SAAS,CAAC,QAAQ,GAAG,WAAW,CAAC,QAAQ,CAAA;AAE3F,MAAM,MAAM,SAAS,GACjB,qBAAqB,GACrB,qBAAqB,GACrB,qBAAqB,GACrB,oBAAoB,GACpB,sBAAsB,GACtB,iBAAiB,GACjB,cAAc,GACd,iBAAiB,GACjB,kBAAkB,GAClB,mBAAmB,GACnB,kBAAkB,GAClB,gBAAgB,GAChB,mBAAmB,GACnB,gBAAgB,GAChB,mBAAmB,GACnB,wBAAwB,CAAA"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/context/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAA;AAC7D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AACzD,OAAO,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAC3D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AACtD,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAEtE;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,UAAU,GAAG,QAAQ,CAAA;AAEvD;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,yDAAyD;IACzD,eAAe,CAAC,EAAE,OAAO,CAAA;CAC1B,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,+BAA+B;IAC/B,YAAY,EAAE,YAAY,CAAA;CAC3B,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,4CAA4C;IAC5C,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACjC,oCAAoC;IACpC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAA;CACrC,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,4CAA4C;IAC5C,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACjC,oCAAoC;IACpC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAA;IACpC,yCAAyC;IACzC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;IACjD,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;IACjD,oCAAoC;IACpC,OAAO,EAAE,WAAW,CAAA;CACrB,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,SAAS,CAAC,QAAQ,GAAG,SAAS,CAAC,QAAQ,GAAG,WAAW,CAAC,QAAQ,CAAA;AAE3F;;GAEG;AACH,MAAM,MAAM,SAAS,GACjB,qBAAqB,GACrB,qBAAqB,GACrB,qBAAqB,GACrB,oBAAoB,GACpB,sBAAsB,GACtB,iBAAiB,GACjB,cAAc,GACd,iBAAiB,GACjB,kBAAkB,GAClB,mBAAmB,GACnB,kBAAkB,GAClB,gBAAgB,GAChB,mBAAmB,GACnB,gBAAgB,GAChB,mBAAmB,GACnB,wBAAwB,CAAA"}

package/esm/dsl/model/ModelBase.d.ts

@@ -8,7 +8,7 @@ import { ContentBase } from '../ContentBase.js';
 import type { Inserted } from '../Inserted.js';
 import type { OasSchema } from '../../oas/schema/Schema.js';
 import type { OasRef } from '../../oas/ref/Ref.js';
-import { OasVoid } from '../../oas/void/Void.js';
+import type { OasVoid } from '../../oas/void/Void.js';
 /**
  * Constructor arguments for {@link ModelBase}.
  *

package/esm/dsl/model/ModelBase.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ModelBase.d.ts","sourceRoot":"","sources":["../../../src/dsl/model/ModelBase.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gBAAgB,EAChB,eAAe,EACf,kBAAkB,EAClB,yBAAyB,EACzB,2BAA2B,EAC5B,MAAM,kCAAkC,CAAA;AACzC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAA;AACnE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAA;AAChE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAA;AACrD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAC5D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AACjD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAC/C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAC9C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAA;AAC3D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAA;AAGlD,OAAO,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAA;AAEhD;;;;GAIG;AACH,MAAM,MAAM,aAAa,CAAC,cAAc,GAAG,SAAS,IAAI;IACtD,yEAAyE;IACzE,OAAO,EAAE,eAAe,CAAA;IACxB,0EAA0E;IAC1E,QAAQ,EAAE,eAAe,CAAC,cAAc,CAAC,CAAA;IACzC,gDAAgD;IAChD,YAAY,EAAE,YAAY,CAAA;IAC1B,mDAAmD;IACnD,OAAO,EAAE,OAAO,CAAA;CACjB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuFG;AACH,qBAAa,SAAS,CAAC,cAAc,GAAG,SAAS,CAAE,SAAQ,WAAW;IACpE,0EAA0E;IAC1E,QAAQ,EAAE,eAAe,CAAC,cAAc,CAAC,CAAA;IAEzC,mDAAmD;IACnD,OAAO,EAAE,OAAO,CAAA;IAEhB,oDAAoD;IAC3C,YAAY,EAAE,YAAY,CAAA;IAEnC;;;;;;;;;;;;;;;;;;;;;OAqBG;gBACS,EAAE,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,OAAO,EAAE,EAAE,aAAa,CAAC,cAAc,CAAC;IAQvF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAoCG;IACH,WAAW,CAAC,CAAC,SAAS,cAAc,EAAE,cAAc,GAAG,SAAS,EAC9D,UAAU,EAAE,eAAe,CAAC,CAAC,EAAE,cAAc,CAAC,EAC9C,OAAO,EAAE,OAAO,EAChB,OAAO,GAAE,IAAI,CAAC,kBAAkB,CAAC,OAAO,CAAC,EAAE,UAAU,CAAM,GAC1D,QAAQ,CAAC,CAAC,EAAE,OAAO,EAAE,cAAc,CAAC;IAQvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAwDG;IACH,qBAAqB,CACnB,CAAC,SAAS,cAAc,EACxB,MAAM,SAAS,SAAS,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,OAAO,EACrD,cAAc,GAAG,SAAS,EAE1B,UAAU,EAAE,eAAe,CAAC,CAAC,EAAE,cAAc,CAAC,EAC9C,EAAE,MAAM,EAAE,YAAY,EAAE,EAAE,IAAI,CAAC,yBAAyB,CAAC,MAAM,CAAC,EAAE,iBAAiB,CAAC,EACpF,OAAO,GAAE,IAAI,CAAC,kBAAkB,CAAC,OAAO,CAAC,EAAE,UAAU,CAAM,GAC1D,2BAA2B,CAAC,CAAC,EAAE,MAAM,CAAC;IAYzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAwCG;IACM,QAAQ,CAAC,IAAI,EAAE,gBAAgB,GAAG,IAAI;CAMhD"}
+{"version":3,"file":"ModelBase.d.ts","sourceRoot":"","sources":["../../../src/dsl/model/ModelBase.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gBAAgB,EAChB,eAAe,EACf,kBAAkB,EAClB,yBAAyB,EACzB,2BAA2B,EAC5B,MAAM,kCAAkC,CAAA;AACzC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAA;AACnE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAA;AAChE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAA;AACrD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAC5D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AACjD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAC/C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAC9C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAA;AAC3D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAA;AAClD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAA;AAErD;;;;GAIG;AACH,MAAM,MAAM,aAAa,CAAC,cAAc,GAAG,SAAS,IAAI;IACtD,yEAAyE;IACzE,OAAO,EAAE,eAAe,CAAA;IACxB,0EAA0E;IAC1E,QAAQ,EAAE,eAAe,CAAC,cAAc,CAAC,CAAA;IACzC,gDAAgD;IAChD,YAAY,EAAE,YAAY,CAAA;IAC1B,mDAAmD;IACnD,OAAO,EAAE,OAAO,CAAA;CACjB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuFG;AACH,qBAAa,SAAS,CAAC,cAAc,GAAG,SAAS,CAAE,SAAQ,WAAW;IACpE,0EAA0E;IAC1E,QAAQ,EAAE,eAAe,CAAC,cAAc,CAAC,CAAA;IAEzC,mDAAmD;IACnD,OAAO,EAAE,OAAO,CAAA;IAEhB,oDAAoD;IAC3C,YAAY,EAAE,YAAY,CAAA;IAEnC;;;;;;;;;;;;;;;;;;;;;OAqBG;gBACS,EAAE,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,OAAO,EAAE,EAAE,aAAa,CAAC,cAAc,CAAC;IAQvF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAoCG;IACH,WAAW,CAAC,CAAC,SAAS,cAAc,EAAE,cAAc,GAAG,SAAS,EAC9D,UAAU,EAAE,eAAe,CAAC,CAAC,EAAE,cAAc,CAAC,EAC9C,OAAO,EAAE,OAAO,EAChB,OAAO,GAAE,IAAI,CAAC,kBAAkB,CAAC,OAAO,CAAC,EAAE,UAAU,CAAM,GAC1D,QAAQ,CAAC,CAAC,EAAE,OAAO,EAAE,cAAc,CAAC;IAQvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAwDG;IACH,qBAAqB,CACnB,CAAC,SAAS,cAAc,EACxB,MAAM,SAAS,SAAS,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,OAAO,EACrD,cAAc,GAAG,SAAS,EAE1B,UAAU,EAAE,eAAe,CAAC,CAAC,EAAE,cAAc,CAAC,EAC9C,EAAE,MAAM,EAAE,YAAY,EAAE,EAAE,IAAI,CAAC,yBAAyB,CAAC,MAAM,CAAC,EAAE,iBAAiB,CAAC,EACpF,OAAO,GAAE,IAAI,CAAC,kBAAkB,CAAC,OAAO,CAAC,EAAE,UAAU,CAAM,GAC1D,2BAA2B,CAAC,CAAC,EAAE,MAAM,CAAC;IAYzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAwCG;IACM,QAAQ,CAAC,IAAI,EAAE,gBAAgB,GAAG,IAAI;CAMhD"}

package/esm/dsl/model/ModelDriver.d.ts

@@ -13,18 +13,80 @@ type CreateModelArgs<V extends GeneratedValue, T extends GenerationType, Enrichm
     rootRef?: RefName;
     noExport?: boolean;
 };
+/**
+ * Driver class responsible for managing model generation lifecycle.
+ *
+ * @template V - The generated value type
+ * @template T - The generation type
+ * @template EnrichmentType - Optional enrichment type
+ */
 export declare class ModelDriver<V extends GeneratedValue, T extends GenerationType, EnrichmentType> {
+    /** The generation context */
     context: GenerateContext;
+    /** The insertable model configuration */
     insertable: ModelInsertable<V, EnrichmentType>;
+    /** Reference name for the model */
     refName: RefName;
+    /** Content settings for the model */
     settings: ContentSettings<EnrichmentType>;
+    /** Optional destination path for the generated file */
     destinationPath?: string;
+    /** The generated definition */
     definition: GeneratedDefinition<V, T>;
+    /** Optional root reference name */
     rootRef?: RefName;
+    /** Whether to skip export declaration */
     noExport?: boolean;
+    /**
+     * Creates a new ModelDriver instance.
+     *
+     * @param args - Constructor arguments
+     * @param args.context - Generation context
+     * @param args.insertable - Model insertable configuration
+     * @param args.refName - Reference name for the model
+     * @param args.generation - Optional generation type
+     * @param args.destinationPath - Optional destination path
+     * @param args.rootRef - Optional root reference name
+     * @param args.noExport - Whether to skip export declaration
+     */
     constructor({ context, insertable, refName, generation, destinationPath, rootRef, noExport }: CreateModelArgs<V, T, EnrichmentType>);
+    /**
+     * Applies generation configuration to create the model definition.
+     *
+     * This method handles the core generation logic, including identifier resolution,
+     * export path management, and import registration for cross-file dependencies.
+     *
+     * @template T - The generation type
+     * @param args - Apply configuration arguments
+     * @param args.generation - Optional generation type (unused currently)
+     * @param args.destinationPath - Optional destination path for imports
+     * @returns Generated definition for the model
+     */
     private apply;
+    /**
+     * Retrieves or creates a definition for the model.
+     *
+     * This method first checks for cached definitions to avoid duplicate generation,
+     * then creates a new definition if none exists. It handles the complete model
+     * transformation process including schema resolution and value generation.
+     *
+     * @param args - Definition retrieval arguments
+     * @param args.identifier - The identifier for the definition
+     * @param args.exportPath - The export path for the definition
+     * @returns Model definition instance
+     */
     private getDefinition;
+    /**
+     * Type guard to verify a definition matches the expected generated value type.
+     *
+     * This method performs type narrowing to ensure a cached definition is compatible
+     * with the current generation requirements, including export path validation.
+     *
+     * @template V - The expected generated value type
+     * @param definition - The definition to verify (may be undefined)
+     * @param exportPath - Expected export path for validation
+     * @returns True if definition matches expected type and constraints
+     */
     private affirmDefinition;
 }
 export {};

package/esm/dsl/model/ModelDriver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ModelDriver.d.ts","sourceRoot":"","sources":["../../../src/dsl/model/ModelDriver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AACjD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAA;AACvE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAI5D,OAAO,KAAK,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAA;AACxF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAA;AACnE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAA;AAGrD,KAAK,eAAe,CAAC,CAAC,SAAS,cAAc,EAAE,CAAC,SAAS,cAAc,EAAE,cAAc,IAAI;IACzF,OAAO,EAAE,eAAe,CAAA;IACxB,UAAU,EAAE,eAAe,CAAC,CAAC,EAAE,cAAc,CAAC,CAAA;IAC9C,OAAO,EAAE,OAAO,CAAA;IAChB,UAAU,CAAC,EAAE,CAAC,CAAA;IACd,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB,CAAA;AAYD,qBAAa,WAAW,CAAC,CAAC,SAAS,cAAc,EAAE,CAAC,SAAS,cAAc,EAAE,cAAc;IACzF,OAAO,EAAE,eAAe,CAAA;IACxB,UAAU,EAAE,eAAe,CAAC,CAAC,EAAE,cAAc,CAAC,CAAA;IAC9C,OAAO,EAAE,OAAO,CAAA;IAChB,QAAQ,EAAE,eAAe,CAAC,cAAc,CAAC,CAAA;IACzC,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,UAAU,EAAE,mBAAmB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;IACrC,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAA;gBACN,EACV,OAAO,EACP,UAAU,EACV,OAAO,EACP,UAAU,EACV,eAAe,EACf,OAAO,EACP,QAAQ,EACT,EAAE,eAAe,CAAC,CAAC,EAAE,CAAC,EAAE,cAAc,CAAC;IAgBxC,OAAO,CAAC,KAAK;IAuBb,OAAO,CAAC,aAAa;IA2CrB,OAAO,CAAC,gBAAgB;CAqBzB"}
+{"version":3,"file":"ModelDriver.d.ts","sourceRoot":"","sources":["../../../src/dsl/model/ModelDriver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AACjD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAA;AACvE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAI5D,OAAO,KAAK,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAA;AACxF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAA;AACnE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAA;AAGrD,KAAK,eAAe,CAAC,CAAC,SAAS,cAAc,EAAE,CAAC,SAAS,cAAc,EAAE,cAAc,IAAI;IACzF,OAAO,EAAE,eAAe,CAAA;IACxB,UAAU,EAAE,eAAe,CAAC,CAAC,EAAE,cAAc,CAAC,CAAA;IAC9C,OAAO,EAAE,OAAO,CAAA;IAChB,UAAU,CAAC,EAAE,CAAC,CAAA;IACd,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB,CAAA;AAYD;;;;;;GAMG;AACH,qBAAa,WAAW,CAAC,CAAC,SAAS,cAAc,EAAE,CAAC,SAAS,cAAc,EAAE,cAAc;IACzF,6BAA6B;IAC7B,OAAO,EAAE,eAAe,CAAA;IACxB,yCAAyC;IACzC,UAAU,EAAE,eAAe,CAAC,CAAC,EAAE,cAAc,CAAC,CAAA;IAC9C,mCAAmC;IACnC,OAAO,EAAE,OAAO,CAAA;IAChB,qCAAqC;IACrC,QAAQ,EAAE,eAAe,CAAC,cAAc,CAAC,CAAA;IACzC,uDAAuD;IACvD,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,+BAA+B;IAC/B,UAAU,EAAE,mBAAmB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;IACrC,mCAAmC;IACnC,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,yCAAyC;IACzC,QAAQ,CAAC,EAAE,OAAO,CAAA;IAElB;;;;;;;;;;;OAWG;gBACS,EACV,OAAO,EACP,UAAU,EACV,OAAO,EACP,UAAU,EACV,eAAe,EACf,OAAO,EACP,QAAQ,EACT,EAAE,eAAe,CAAC,CAAC,EAAE,CAAC,EAAE,cAAc,CAAC;IAgBxC;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,KAAK;IAuBb;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,aAAa;IA2CrB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,gBAAgB;CAqBzB"}

package/esm/dsl/model/ModelDriver.js

@@ -1,50 +1,77 @@
 import { normalize } from '../../deps/jsr.io/@std/path/1.1.2/normalize.js';
 import { Definition } from '../Definition.js';
 import { toModelGeneratorKey } from '../../types/GeneratorKeys.js';
+/**
+ * Driver class responsible for managing model generation lifecycle.
+ *
+ * @template V - The generated value type
+ * @template T - The generation type
+ * @template EnrichmentType - Optional enrichment type
+ */
 export class ModelDriver {
+    /**
+     * Creates a new ModelDriver instance.
+     *
+     * @param args - Constructor arguments
+     * @param args.context - Generation context
+     * @param args.insertable - Model insertable configuration
+     * @param args.refName - Reference name for the model
+     * @param args.generation - Optional generation type
+     * @param args.destinationPath - Optional destination path
+     * @param args.rootRef - Optional root reference name
+     * @param args.noExport - Whether to skip export declaration
+     */
     constructor({ context, insertable, refName, generation, destinationPath, rootRef, noExport }) {
+        /** The generation context */
         Object.defineProperty(this, "context", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /** The insertable model configuration */
         Object.defineProperty(this, "insertable", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /** Reference name for the model */
         Object.defineProperty(this, "refName", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /** Content settings for the model */
         Object.defineProperty(this, "settings", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /** Optional destination path for the generated file */
         Object.defineProperty(this, "destinationPath", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /** The generated definition */
         Object.defineProperty(this, "definition", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /** Optional root reference name */
         Object.defineProperty(this, "rootRef", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /** Whether to skip export declaration */
         Object.defineProperty(this, "noExport", {
             enumerable: true,
             configurable: true,
@@ -62,7 +89,19 @@ export class ModelDriver {
         this.definition = this.apply({ generation, destinationPath });
         this.context.modelDepth[`${insertable.id}:${refName}`] = 0;
     }
-    apply({ generation, destinationPath } = {}) {
+    /**
+     * Applies generation configuration to create the model definition.
+     *
+     * This method handles the core generation logic, including identifier resolution,
+     * export path management, and import registration for cross-file dependencies.
+     *
+     * @template T - The generation type
+     * @param args - Apply configuration arguments
+     * @param args.generation - Optional generation type (unused currently)
+     * @param args.destinationPath - Optional destination path for imports
+     * @returns Generated definition for the model
+     */
+    apply({ generation: _generation, destinationPath } = {}) {
         const { identifier, exportPath } = this.settings;
         // Everything is selected (for now)
         // if (/*!selected && */ generation !== 'force') {
@@ -77,6 +116,18 @@ export class ModelDriver {
         }
         return definition;
     }
+    /**
+     * Retrieves or creates a definition for the model.
+     *
+     * This method first checks for cached definitions to avoid duplicate generation,
+     * then creates a new definition if none exists. It handles the complete model
+     * transformation process including schema resolution and value generation.
+     *
+     * @param args - Definition retrieval arguments
+     * @param args.identifier - The identifier for the definition
+     * @param args.exportPath - The export path for the definition
+     * @returns Model definition instance
+     */
     getDefinition({ identifier, exportPath }) {
         const cachedDefinition = this.context.findDefinition({
             name: identifier.name,
@@ -112,6 +163,17 @@ export class ModelDriver {
         });
         return definition;
     }
+    /**
+     * Type guard to verify a definition matches the expected generated value type.
+     *
+     * This method performs type narrowing to ensure a cached definition is compatible
+     * with the current generation requirements, including export path validation.
+     *
+     * @template V - The expected generated value type
+     * @param definition - The definition to verify (may be undefined)
+     * @param exportPath - Expected export path for validation
+     * @returns True if definition matches expected type and constraints
+     */
     affirmDefinition(definition, exportPath) {
         if (!definition) {
             return false;