@skmtc/core 0.0.799 → 0.0.802

package/script/context/GenerateContext.js

@@ -255,6 +255,13 @@ class GenerateContext {
             mappings: __classPrivateFieldGet(this, _GenerateContext_mappings, "f")
         };
     }
+    /**
+     * Executes a function within a traced context for debugging and monitoring.
+     *
+     * @param token - Trace identifier or path segments
+     * @param fn - Function to execute within the trace context
+     * @returns The result of the traced function execution
+     */
     trace(token, fn) {
         return (0, tracer_js_1.tracer)(this.stackTrail, token, fn, this.logger);
     }
@@ -283,7 +290,12 @@ class GenerateContext {
             noExport
         });
     }
-    /** @experimental */
+    /**
+     * Registers JSON content for output to a file.
+     *
+     * @experimental This method is experimental and may change in future versions
+     * @param args - Registration arguments with destination path and JSON content
+     */
     registerJson({ destinationPath, json }) {
         const currentFile = __classPrivateFieldGet(this, _GenerateContext_instances, "m", _GenerateContext_getFile).call(this, destinationPath);
         (0, tiny_invariant_1.default)(currentFile instanceof JsonFile_js_1.JsonFile, `File at "${destinationPath}" is not a "JsonFile" type`);
@@ -363,6 +375,14 @@ class GenerateContext {
         });
         return new Inserted_js_1.Inserted({ settings, definition });
     }
+    /**
+     * Inserts a normalized model definition into the generation context.
+     *
+     * @param insertable - Model insertable configuration with prototype and transform functions
+     * @param schema - OAS schema, reference, or void type to generate model from
+     * @param options - Insertion options including generation type and destination
+     * @returns Inserted model instance with settings and definition
+     */
     insertNormalisedModel(insertable, { schema, fallbackName, destinationPath }, { noExport = false } = {}) {
         if (schema.isRef()) {
             const { definition } = this.insertModel(insertable, schema.toRefName(), {

package/script/context/ParseContext.d.ts

@@ -30,7 +30,7 @@ export type ParseReturn = {
 /**
  * Base type for parse warning messages.
  */
-type ParseWarningBase = {
+export type ParseWarningBase = {
     /** Issue severity level */
     level: 'warning';
     /** Warning message */
@@ -39,7 +39,7 @@ type ParseWarningBase = {
 /**
  * Base type for parse error messages.
  */
-type ParseErrorBase = {
+export type ParseErrorBase = {
     /** Issue severity level */
     level: 'error';
     /** The error that occurred */
@@ -48,7 +48,7 @@ type ParseErrorBase = {
 /**
  * Base union type for parse issues.
  */
-type ParseIssueBase = ParseErrorBase | ParseWarningBase;
+export type ParseIssueBase = ParseErrorBase | ParseWarningBase;
 /**
  * Arguments for logging issues with a specific key.
  */
@@ -253,17 +253,78 @@ export declare class ParseContext {
     issues: ParseIssue[];
     /** Whether to suppress console output during parsing */
     silent: boolean;
+    /**
+     * Creates a new ParseContext instance for the parsing phase.
+     *
+     * @param args - Constructor arguments including document object, logger, and options
+     */
     constructor({ documentObject, logger, stackTrail, silent }: ConstructorArgs);
+    /**
+     * Parses the OpenAPI v3 document and returns the internal OAS document representation.
+     *
+     * @returns Parsed OAS document with all components and operations
+     */
     parse(): OasDocument;
+    /**
+     * Removes items from the parsed document that encountered errors during parsing.
+     */
     removeErroredItems(): void;
+    /**
+     * Registers a reference ($ref) with its associated stack trail for error tracking.
+     *
+     * @param stackTrail - Current processing context stack trail
+     * @param $ref - OpenAPI reference string to register
+     */
     registerRef(stackTrail: StackTrail, $ref: string): void;
+    /**
+     * Registers an error that occurred while processing a reference.
+     *
+     * @param error - Error that occurred during reference processing
+     * @param $ref - Reference string that caused the error (if available)
+     */
     registerRefError(error: Error, $ref: string | undefined): void;
+    /**
+     * Executes a function within a traced context for debugging and monitoring.
+     *
+     * @param token - Trace identifier or path segments
+     * @param fn - Function to execute within the trace context
+     * @returns The result of the traced function execution
+     */
     trace<T>(token: string | string[], fn: () => T): T;
+    /**
+     * Logs warnings for fields that were skipped during parsing.
+     *
+     * @param args - Arguments containing skipped fields and parent context
+     */
     logSkippedFields({ skipped, parent, parentType }: LogSkippedValuesArgs): void;
+    /**
+     * Attempts to parse a value with optional error handling and logging.
+     *
+     * @param args - Parsing arguments including schema and error handling
+     * @returns Parsed value or undefined if parsing fails
+     */
     provisionalParse<T>({ key, value, parent, schema, toMessage, type }: ProvisionalParseArgs<T>): T | undefined;
+    /**
+     * Logs a parsing issue with associated key context.
+     *
+     * @param args - Issue arguments including key, parent object, and issue details
+     */
     logIssue({ key, parent, type, ...issue }: LogIssueArgs): void;
+    /**
+     * Logs a parsing issue without specific key context.
+     *
+     * @param args - Issue arguments including parent object and issue details
+     */
     logIssueNoKey({ parent, type, ...issue }: LogIssueNoKeyArgs): void;
 }
+/**
+ * Parses an OpenAPI v3 schema from string format (JSON or YAML).
+ *
+ * Automatically detects the format based on content and parses accordingly.
+ *
+ * @param schema - Schema string in JSON or YAML format
+ * @returns Parsed OpenAPI v3 document object
+ */
 export declare const parseSchema: (schema: string) => OpenAPIV3.Document;
 export {};
 //# sourceMappingURL=ParseContext.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"ParseContext.d.ts","sourceRoot":"","sources":["../../src/context/ParseContext.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ParseContext.d.ts","sourceRoot":"","sources":["../../src/context/ParseContext.ts"],"names":[],"mappings":"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"}

package/script/context/ParseContext.js

@@ -161,6 +161,11 @@ const v = __importStar(require("valibot"));
  * ```
  */
 class ParseContext {
+    /**
+     * Creates a new ParseContext instance for the parsing phase.
+     *
+     * @param args - Constructor arguments including document object, logger, and options
+     */
     constructor({ documentObject, logger, stackTrail, silent = true }) {
         /** The original OpenAPI v3 document being parsed */
         Object.defineProperty(this, "documentObject", {
@@ -215,6 +220,11 @@ class ParseContext {
         __classPrivateFieldSet(this, _ParseContext_refStackTrails, {}, "f");
         __classPrivateFieldSet(this, _ParseContext_refErrors, {}, "f");
     }
+    /**
+     * Parses the OpenAPI v3 document and returns the internal OAS document representation.
+     *
+     * @returns Parsed OAS document with all components and operations
+     */
     parse() {
         this.oasDocument.fields = (0, toDocumentFieldsV3_js_1.toDocumentFieldsV3)({
             documentObject: this.documentObject,
@@ -223,6 +233,9 @@ class ParseContext {
         this.removeErroredItems();
         return this.oasDocument;
     }
+    /**
+     * Removes items from the parsed document that encountered errors during parsing.
+     */
     removeErroredItems() {
         Object.entries(__classPrivateFieldGet(this, _ParseContext_refErrors, "f")).forEach(([$ref, errors]) => {
             errors.forEach(error => {
@@ -241,19 +254,43 @@ class ParseContext {
             });
         });
     }
+    /**
+     * Registers a reference ($ref) with its associated stack trail for error tracking.
+     *
+     * @param stackTrail - Current processing context stack trail
+     * @param $ref - OpenAPI reference string to register
+     */
     registerRef(stackTrail, $ref) {
         const refStackTrails = __classPrivateFieldGet(this, _ParseContext_refStackTrails, "f")[$ref];
         refStackTrails ? refStackTrails.push(stackTrail) : (__classPrivateFieldGet(this, _ParseContext_refStackTrails, "f")[$ref] = [stackTrail]);
     }
+    /**
+     * Registers an error that occurred while processing a reference.
+     *
+     * @param error - Error that occurred during reference processing
+     * @param $ref - Reference string that caused the error (if available)
+     */
     registerRefError(error, $ref) {
         if ($ref) {
             const refErrors = __classPrivateFieldGet(this, _ParseContext_refErrors, "f")[$ref];
             refErrors ? refErrors.push(error) : (__classPrivateFieldGet(this, _ParseContext_refErrors, "f")[$ref] = [error]);
         }
     }
+    /**
+     * Executes a function within a traced context for debugging and monitoring.
+     *
+     * @param token - Trace identifier or path segments
+     * @param fn - Function to execute within the trace context
+     * @returns The result of the traced function execution
+     */
     trace(token, fn) {
         return (0, tracer_js_1.tracer)(this.stackTrail, token, fn, this.logger);
     }
+    /**
+     * Logs warnings for fields that were skipped during parsing.
+     *
+     * @param args - Arguments containing skipped fields and parent context
+     */
     logSkippedFields({ skipped, parent, parentType }) {
         Object.keys(skipped).forEach(key => {
             this.logIssue({
@@ -265,6 +302,12 @@ class ParseContext {
             });
         });
     }
+    /**
+     * Attempts to parse a value with optional error handling and logging.
+     *
+     * @param args - Parsing arguments including schema and error handling
+     * @returns Parsed value or undefined if parsing fails
+     */
     provisionalParse({ key, value, parent, schema, toMessage, type }) {
         const parsed = v.safeParse(v.optional(schema), value);
         if (parsed.success) {
@@ -278,9 +321,19 @@ class ParseContext {
             type
         });
     }
+    /**
+     * Logs a parsing issue with associated key context.
+     *
+     * @param args - Issue arguments including key, parent object, and issue details
+     */
     logIssue({ key, parent, type, ...issue }) {
         this.trace(key, () => this.logIssueNoKey({ parent, type, ...issue }));
     }
+    /**
+     * Logs a parsing issue without specific key context.
+     *
+     * @param args - Issue arguments including parent object and issue details
+     */
     logIssueNoKey({ parent, type, ...issue }) {
         if (issue.level === 'error') {
             this.registerRefError(issue.error, this.stackTrail.toStackRef());
@@ -303,6 +356,14 @@ class ParseContext {
 }
 exports.ParseContext = ParseContext;
 _ParseContext_refStackTrails = new WeakMap(), _ParseContext_refErrors = new WeakMap();
+/**
+ * Parses an OpenAPI v3 schema from string format (JSON or YAML).
+ *
+ * Automatically detects the format based on content and parses accordingly.
+ *
+ * @param schema - Schema string in JSON or YAML format
+ * @returns Parsed OpenAPI v3 document object
+ */
 const parseSchema = (schema) => {
     if (schema.trimStart().startsWith('{')) {
         return JSON.parse(schema);

package/script/context/RenderContext.d.ts

@@ -150,7 +150,7 @@ type ConstructorArgs = {
  *       prettierConfig: this.prettierConfig,
  *       basePath: this.settings?.basePath,
  *       stackTrail: this.stackTrail,
- *       logger: this.logger,
+ *       logger: this.#logger,
  *       captureCurrentResult: this.captureCurrentResult.bind(this)
  *     });
  *
@@ -210,17 +210,166 @@ type ConstructorArgs = {
  */
 export declare class RenderContext {
     #private;
+    /** 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>>;
+    /** Base path for resolving file paths */
     basePath: string | undefined;
-    logger: log.Logger;
+    /** Function to capture result status */
     captureCurrentResult: (result: ResultType) => void;
+    /**
+     * 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 }: ConstructorArgs);
+    /**
+     * 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`);
+     * });
+     * ```
+     */
     render(): Promise<Omit<RenderResult, 'results'>>;
+    /**
+     * 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);
+     * ```
+     */
     collate(): Promise<FilesRenderResult>;
+    /**
+     * 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<T>(token: string | string[], fn: () => T): T;
+    /**
+     * 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: string): File | JsonFile;
+    /**
+     * 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 }: PickArgs): Definition | undefined;
 }
 export {};

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

@@ -1 +1 @@
-{"version":3,"file":"RenderContext.d.ts","sourceRoot":"","sources":["../../src/context/RenderContext.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"RenderContext.d.ts","sourceRoot":"","sources":["../../src/context/RenderContext.ts"],"names":[],"mappings":"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"}