@skmtc/core 0.0.796 → 0.0.798

package/esm/types/Results.d.ts

@@ -1,10 +1,42 @@
 import "../_dnt.polyfills.js";
 import * as v from 'valibot';
+/**
+ * Type representing the possible outcomes of SKMTC processing operations.
+ *
+ * Used throughout the SKMTC pipeline to track and categorize the results
+ * of parsing, generation, and rendering operations.
+ */
 export type ResultType = 'success' | 'warning' | 'error' | 'skipped' | 'notSupported';
+/**
+ * Type representing result types that indicate issues or problems.
+ *
+ * Used for filtering and handling results that require attention,
+ * excluding successful, skipped, or unsupported operations.
+ */
 export type WarningError = 'warning' | 'error';
+/**
+ * Valibot schema for validating ResultType values.
+ *
+ * Used for runtime validation of result type values throughout
+ * the SKMTC pipeline to ensure type safety and data integrity.
+ */
 export declare const resultType: v.GenericSchema<ResultType>;
+/**
+ * Interface representing a hierarchical results structure.
+ *
+ * Allows for nested result tracking where each key can contain
+ * a result type, another results item (for nesting), or an array
+ * of results items for collections.
+ */
 export interface ResultsItem {
+    /** Dynamic key-value pairs for hierarchical result tracking */
     [key: string]: ResultType | ResultsItem | Array<ResultsItem | null>;
 }
+/**
+ * Valibot schema for validating ResultsItem structures.
+ *
+ * Uses lazy evaluation to handle recursive result item validation,
+ * supporting nested hierarchical result structures.
+ */
 export declare const resultsItem: v.GenericSchema<ResultsItem>;
 //# sourceMappingURL=Results.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"Results.d.ts","sourceRoot":"","sources":["../../src/types/Results.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAC9B,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAE5B,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,GAAG,cAAc,CAAA;AAErF,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,OAAO,CAAA;AAE9C,eAAO,MAAM,UAAU,EAAE,CAAC,CAAC,aAAa,CAAC,UAAU,CAMjD,CAAA;AAEF,MAAM,WAAW,WAAW;IAC1B,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,WAAW,GAAG,KAAK,CAAC,WAAW,GAAG,IAAI,CAAC,CAAA;CACpE;AAED,eAAO,MAAM,WAAW,EAAE,CAAC,CAAC,aAAa,CAAC,WAAW,CAGpD,CAAA"}
+{"version":3,"file":"Results.d.ts","sourceRoot":"","sources":["../../src/types/Results.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAC9B,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAE5B;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,GAAG,cAAc,CAAA;AAErF;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,OAAO,CAAA;AAE9C;;;;;GAKG;AACH,eAAO,MAAM,UAAU,EAAE,CAAC,CAAC,aAAa,CAAC,UAAU,CAMjD,CAAA;AAEF;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B,+DAA+D;IAC/D,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,WAAW,GAAG,KAAK,CAAC,WAAW,GAAG,IAAI,CAAC,CAAA;CACpE;AAED;;;;;GAKG;AACH,eAAO,MAAM,WAAW,EAAE,CAAC,CAAC,aAAa,CAAC,WAAW,CAGpD,CAAA"}

package/esm/types/Results.js

@@ -1,5 +1,11 @@
 import "../_dnt.polyfills.js";
 import * as v from 'valibot';
+/**
+ * Valibot schema for validating ResultType values.
+ *
+ * Used for runtime validation of result type values throughout
+ * the SKMTC pipeline to ensure type safety and data integrity.
+ */
 export const resultType = v.union([
     v.literal('success'),
     v.literal('warning'),
@@ -7,4 +13,10 @@ export const resultType = v.union([
     v.literal('skipped'),
     v.literal('notSupported')
 ]);
+/**
+ * Valibot schema for validating ResultsItem structures.
+ *
+ * Uses lazy evaluation to handle recursive result item validation,
+ * supporting nested hierarchical result structures.
+ */
 export const resultsItem = v.record(v.string(), v.lazy(() => v.union([resultsItem, resultType, v.array(v.lazy(() => resultsItem))])));

package/package.json

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

package/script/app/validate.d.ts

@@ -1,3 +1,35 @@
+/**
+ * Validates a project name against SKMTC naming conventions.
+ *
+ * Ensures project names follow standard naming patterns suitable for package
+ * managers and file systems. Names must be lowercase, contain only letters,
+ * numbers, and hyphens, with specific length and format requirements.
+ *
+ * @param name - The project name to validate
+ * @returns An error message string if validation fails, undefined if valid
+ *
+ * @example Valid project names
+ * ```typescript
+ * checkProjectName('my-api-client'); // undefined (valid)
+ * checkProjectName('user-service');  // undefined (valid)
+ * checkProjectName('api2');          // undefined (valid)
+ * ```
+ *
+ * @example Invalid project names
+ * ```typescript
+ * checkProjectName('A');             // 'Name must be at least 2 characters long'
+ * checkProjectName('My-API-Client'); // 'Name must only contain lowercase letters, numbers and hyphens'
+ * checkProjectName('-api-client');   // 'Name cannot start with a hyphen'
+ * checkProjectName('api-client-');   // 'Name cannot end with a hyphen'
+ * ```
+ *
+ * @example Validation rules
+ * - Minimum length: 2 characters
+ * - Maximum length: 20 characters
+ * - Allowed characters: a-z, 0-9, hyphens (-)
+ * - Cannot start or end with hyphen
+ * - Must be lowercase only
+ */
 import "../_dnt.polyfills.js";
 export declare const checkProjectName: (name: string) => string | undefined;
 //# sourceMappingURL=validate.d.ts.map

package/script/app/validate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/app/validate.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAC9B,eAAO,MAAM,gBAAgB,GAAI,MAAM,MAAM,KAAG,MAAM,GAAG,SAoBxD,CAAA"}
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/app/validate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,OAAO,sBAAsB,CAAC;AAE9B,eAAO,MAAM,gBAAgB,GAAI,MAAM,MAAM,KAAG,MAAM,GAAG,SAoBxD,CAAA"}

package/script/app/validate.js

@@ -1,6 +1,38 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.checkProjectName = void 0;
+/**
+ * Validates a project name against SKMTC naming conventions.
+ *
+ * Ensures project names follow standard naming patterns suitable for package
+ * managers and file systems. Names must be lowercase, contain only letters,
+ * numbers, and hyphens, with specific length and format requirements.
+ *
+ * @param name - The project name to validate
+ * @returns An error message string if validation fails, undefined if valid
+ *
+ * @example Valid project names
+ * ```typescript
+ * checkProjectName('my-api-client'); // undefined (valid)
+ * checkProjectName('user-service');  // undefined (valid)
+ * checkProjectName('api2');          // undefined (valid)
+ * ```
+ *
+ * @example Invalid project names
+ * ```typescript
+ * checkProjectName('A');             // 'Name must be at least 2 characters long'
+ * checkProjectName('My-API-Client'); // 'Name must only contain lowercase letters, numbers and hyphens'
+ * checkProjectName('-api-client');   // 'Name cannot start with a hyphen'
+ * checkProjectName('api-client-');   // 'Name cannot end with a hyphen'
+ * ```
+ *
+ * @example Validation rules
+ * - Minimum length: 2 characters
+ * - Maximum length: 20 characters
+ * - Allowed characters: a-z, 0-9, hyphens (-)
+ * - Cannot start or end with hyphen
+ * - Must be lowercase only
+ */
 require("../_dnt.polyfills.js");
 const checkProjectName = (name) => {
     if (name.length < 2) {

package/script/context/CoreContext.d.ts

@@ -9,29 +9,70 @@ import * as log from '../deps/jsr.io/@std/log/0.224.14/mod.js';
 import type { GeneratorsMapContainer } from '../types/GeneratorType.js';
 import type { OpenAPIV3 } from 'openapi-types';
 import type { RenderResult } from './types.js';
+/**
+ * Represents the parse phase of the SKMTC pipeline.
+ *
+ * The parse phase converts OpenAPI v3 JSON documents into internal OAS objects,
+ * handling schema validation, reference resolution, and data transformation.
+ */
 export type ParsePhase = {
+    /** Identifies this as the parse phase */
     type: 'parse';
+    /** The parse context containing parsed document and utilities */
     context: ParseContext;
 };
+/**
+ * Represents the generate phase of the SKMTC pipeline.
+ *
+ * The generate phase transforms parsed OAS objects into generator-specific artifacts,
+ * applying templates, handling references, and preparing output files.
+ */
 export type GeneratePhase = {
+    /** Identifies this as the generate phase */
     type: 'generate';
+    /** The generate context for artifact creation and processing */
     context: GenerateContext;
 };
+/**
+ * Represents the render phase of the SKMTC pipeline.
+ *
+ * The render phase takes generator artifacts and renders them to formatted files,
+ * applying code formatting, file system operations, and final output generation.
+ */
 export type RenderPhase = {
+    /** Identifies this as the render phase */
     type: 'render';
+    /** The render context for file output and formatting */
     context: RenderContext;
 };
+/**
+ * Union type representing any phase of the SKMTC pipeline execution.
+ *
+ * Each execution phase contains its type identifier and associated context,
+ * allowing for type-safe phase handling and context access throughout the pipeline.
+ */
 export type ExecutionPhase = ParsePhase | GeneratePhase | RenderPhase;
 type CoreContextArgs = {
     spanId: string;
     logsPath?: string;
     silent: boolean;
 };
-type ToArtifactsArgs = {
+/**
+ * Arguments for the `toArtifacts` method of CoreContext.
+ *
+ * Contains all the necessary configuration for transforming an OpenAPI document
+ * into code artifacts through the SKMTC pipeline.
+ */
+export type ToArtifactsArgs = {
+    /** The OpenAPI v3 document to process */
     documentObject: OpenAPIV3.Document;
+    /** Client settings for customization (optional) */
     settings: ClientSettings | undefined;
+    /** Function that returns the generator configuration map */
     toGeneratorConfigMap: <EnrichmentType = undefined>() => GeneratorsMapContainer<EnrichmentType>;
+    /** Prettier configuration for code formatting (optional) */
     prettier?: PrettierConfigType;
+    /** Whether to suppress console output */
     silent: boolean;
 };
 /**
@@ -218,13 +259,117 @@ export declare class CoreContext {
      * @throws Will throw an error if any phase of the pipeline fails
      */
     toArtifacts({ documentObject, settings, toGeneratorConfigMap, prettier }: ToArtifactsArgs): Promise<RenderResult>;
+    /**
+     * Executes a function with distributed tracing and logging.
+     *
+     * This method wraps function execution with tracing capabilities, updating the
+     * stack trail for context tracking and logging execution details. It's used
+     * throughout the SKMTC pipeline to maintain execution context and debugging information.
+     *
+     * @template T - The return type of the traced function
+     * @param token - Single token or array of tokens to add to the trace stack
+     * @param fn - The function to execute within the trace context
+     * @returns The result of executing the traced function
+     *
+     * @example Single token tracing
+     * ```typescript
+     * const result = context.trace('parse-schema', () => {
+     *   // Schema parsing logic here
+     *   return parsedSchema;
+     * });
+     * ```
+     *
+     * @example Multiple token tracing (nested context)
+     * ```typescript
+     * const result = context.trace(['components', 'schemas', 'User'], () => {
+     *   // Process User schema
+     *   return processedUserSchema;
+     * });
+     * ```
+     */
     trace<T>(token: string | string[], fn: () => T): T;
+    /**
+     * Captures a result at the current execution position in the stack trail.
+     *
+     * This method records processing results (success, warning, error, etc.) at the
+     * current location in the document traversal stack. Results are associated with
+     * the current stack trail position, enabling detailed error reporting and
+     * debugging of OpenAPI processing issues.
+     *
+     * @param result - The type of result to capture (success, warning, error, etc.)
+     *
+     * @example Capturing a warning result
+     * ```typescript
+     * context.captureCurrentResult('warning');
+     * // Result captured at current stack position like: "components.schemas.User.properties.email"
+     * ```
+     *
+     * @example Usage during schema processing
+     * ```typescript
+     * context.trace(['components', 'schemas', 'User'], () => {
+     *   try {
+     *     processUserSchema();
+     *     context.captureCurrentResult('success');
+     *   } catch (error) {
+     *     context.captureCurrentResult('error');
+     *   }
+     * });
+     * ```
+     */
     captureCurrentResult(result: ResultType): void;
 }
+/**
+ * Arguments for the SKMTC JSON log formatter.
+ *
+ * Contains the log record and stack trail information needed to format
+ * structured JSON log entries for the SKMTC processing pipeline.
+ */
 export type JsonFormatterArgs = {
-    logRecord: log.LogRecord;
+    /** The Deno log record containing log level, message, and metadata */
+    logRecord: {
+        /** The log level name */
+        levelName: string;
+        /** The timestamp when the log was created */
+        datetime: Date;
+        /** The log message */
+        msg: string;
+        /** Additional log arguments */
+        args: unknown[];
+    };
+    /** String representation of the current stack trail position */
     stackTrail: string;
 };
+/**
+ * Custom JSON formatter for SKMTC log entries.
+ *
+ * Formats log records into structured JSON that includes stack trail context,
+ * making it easier to trace execution and debug issues in the SKMTC pipeline.
+ * The formatter flattens log arguments and includes execution context.
+ *
+ * @param args - Formatter arguments containing log record and stack trail
+ * @returns Formatted JSON string for the log entry
+ *
+ * @example Usage in logger setup
+ * ```typescript
+ * const handler = new ConsoleHandler("DEBUG", {
+ *   formatter: (logRecord) => skmtcFormatter({
+ *     logRecord,
+ *     stackTrail: context.stackTrail.toString()
+ *   })
+ * });
+ * ```
+ *
+ * @example Output format
+ * ```json
+ * {
+ *   "stackTrail": "components.schemas.User.properties.email",
+ *   "level": "INFO",
+ *   "datetime": 1645123456789,
+ *   "message": "Processing email property",
+ *   "args": { "format": "email", "required": true }
+ * }
+ * ```
+ */
 export declare function skmtcFormatter({ logRecord, stackTrail }: JsonFormatterArgs): string;
 export {};
 //# sourceMappingURL=CoreContext.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"CoreContext.d.ts","sourceRoot":"","sources":["../../src/context/CoreContext.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"CoreContext.d.ts","sourceRoot":"","sources":["../../src/context/CoreContext.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAClD,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAChD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAA;AACpE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAA;AAC9D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAC1D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAA;AACrD,OAAO,KAAK,GAAG,MAAM,yCAAyC,CAAA;AAQ9D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAA;AAEvE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAE9C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAE9C;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,yCAAyC;IACzC,IAAI,EAAE,OAAO,CAAA;IACb,iEAAiE;IACjE,OAAO,EAAE,YAAY,CAAA;CACtB,CAAA;AAED;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,4CAA4C;IAC5C,IAAI,EAAE,UAAU,CAAA;IAChB,gEAAgE;IAChE,OAAO,EAAE,eAAe,CAAA;CACzB,CAAA;AAED;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,0CAA0C;IAC1C,IAAI,EAAE,QAAQ,CAAA;IACd,wDAAwD;IACxD,OAAO,EAAE,aAAa,CAAA;CACvB,CAAA;AAED;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG,aAAa,GAAG,WAAW,CAAA;AAQrE,KAAK,eAAe,GAAG;IACrB,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,OAAO,CAAA;CAChB,CAAA;AAUD;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,yCAAyC;IACzC,cAAc,EAAE,SAAS,CAAC,QAAQ,CAAA;IAClC,mDAAmD;IACnD,QAAQ,EAAE,cAAc,GAAG,SAAS,CAAA;IACpC,4DAA4D;IAC5D,oBAAoB,EAAE,CAAC,cAAc,GAAG,SAAS,OAAO,sBAAsB,CAAC,cAAc,CAAC,CAAA;IAC9F,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,kBAAkB,CAAA;IAC7B,yCAAyC;IACzC,MAAM,EAAE,OAAO,CAAA;CAChB,CAAA;AAOD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,qBAAa,WAAW;;IACtB,sCAAsC;IACtC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAA;IAWlB,yCAAyC;IACzC,MAAM,EAAE,OAAO,CAAA;IAEf;;;;;;;;;;;;;;;;;;;;;;;OAuBG;gBACS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,eAAe;IAmDzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACH,KAAK,CAAC,cAAc,EAAE,SAAS,CAAC,QAAQ,GAAG;QAAE,WAAW,EAAE,WAAW,CAAA;KAAE;IAUvE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAsEG;IACG,WAAW,CAAC,EAAE,cAAc,EAAE,QAAQ,EAAE,oBAAoB,EAAE,QAAQ,EAAE,EAAE,eAAe,GAAG,OAAO,CAAC,YAAY,CAAC;IA2DvH;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,KAAK,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC;IAkClD;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,oBAAoB,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI;CAkB/C;AAED;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,sEAAsE;IACtE,SAAS,EAAE;QACT,yBAAyB;QACzB,SAAS,EAAE,MAAM,CAAA;QACjB,6CAA6C;QAC7C,QAAQ,EAAE,IAAI,CAAA;QACd,sBAAsB;QACtB,GAAG,EAAE,MAAM,CAAA;QACX,+BAA+B;QAC/B,IAAI,EAAE,OAAO,EAAE,CAAA;KAChB,CAAA;IACD,gEAAgE;IAChE,UAAU,EAAE,MAAM,CAAA;CACnB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,cAAc,CAAC,EAAE,SAAS,EAAE,UAAU,EAAE,EAAE,iBAAiB,GAAG,MAAM,CAQnF"}

package/script/context/CoreContext.js

@@ -315,11 +315,67 @@ class CoreContext {
             });
         }
     }
+    /**
+     * Executes a function with distributed tracing and logging.
+     *
+     * This method wraps function execution with tracing capabilities, updating the
+     * stack trail for context tracking and logging execution details. It's used
+     * throughout the SKMTC pipeline to maintain execution context and debugging information.
+     *
+     * @template T - The return type of the traced function
+     * @param token - Single token or array of tokens to add to the trace stack
+     * @param fn - The function to execute within the trace context
+     * @returns The result of executing the traced function
+     *
+     * @example Single token tracing
+     * ```typescript
+     * const result = context.trace('parse-schema', () => {
+     *   // Schema parsing logic here
+     *   return parsedSchema;
+     * });
+     * ```
+     *
+     * @example Multiple token tracing (nested context)
+     * ```typescript
+     * const result = context.trace(['components', 'schemas', 'User'], () => {
+     *   // Process User schema
+     *   return processedUserSchema;
+     * });
+     * ```
+     */
     trace(token, fn) {
         console.log('trace', token);
         this.logger.info('trace', token);
         return (0, tracer_js_1.tracer)(__classPrivateFieldGet(this, _CoreContext_stackTrail, "f"), token, fn, this.logger);
     }
+    /**
+     * Captures a result at the current execution position in the stack trail.
+     *
+     * This method records processing results (success, warning, error, etc.) at the
+     * current location in the document traversal stack. Results are associated with
+     * the current stack trail position, enabling detailed error reporting and
+     * debugging of OpenAPI processing issues.
+     *
+     * @param result - The type of result to capture (success, warning, error, etc.)
+     *
+     * @example Capturing a warning result
+     * ```typescript
+     * context.captureCurrentResult('warning');
+     * // Result captured at current stack position like: "components.schemas.User.properties.email"
+     * ```
+     *
+     * @example Usage during schema processing
+     * ```typescript
+     * context.trace(['components', 'schemas', 'User'], () => {
+     *   try {
+     *     processUserSchema();
+     *     context.captureCurrentResult('success');
+     *   } catch (error) {
+     *     context.captureCurrentResult('error');
+     *   }
+     * });
+     * ```
+     */
     captureCurrentResult(result) {
         __classPrivateFieldGet(this, _CoreContext_results, "f").capture(__classPrivateFieldGet(this, _CoreContext_stackTrail, "f").toString(), result);
     }
@@ -392,6 +448,37 @@ _CoreContext_phase = new WeakMap(), _CoreContext_results = new WeakMap(), _CoreC
     });
     return { type: 'render', context: renderContext };
 };
+/**
+ * Custom JSON formatter for SKMTC log entries.
+ *
+ * Formats log records into structured JSON that includes stack trail context,
+ * making it easier to trace execution and debug issues in the SKMTC pipeline.
+ * The formatter flattens log arguments and includes execution context.
+ *
+ * @param args - Formatter arguments containing log record and stack trail
+ * @returns Formatted JSON string for the log entry
+ *
+ * @example Usage in logger setup
+ * ```typescript
+ * const handler = new ConsoleHandler("DEBUG", {
+ *   formatter: (logRecord) => skmtcFormatter({
+ *     logRecord,
+ *     stackTrail: context.stackTrail.toString()
+ *   })
+ * });
+ * ```
+ *
+ * @example Output format
+ * ```json
+ * {
+ *   "stackTrail": "components.schemas.User.properties.email",
+ *   "level": "INFO",
+ *   "datetime": 1645123456789,
+ *   "message": "Processing email property",
+ *   "args": { "format": "email", "required": true }
+ * }
+ * ```
+ */
 function skmtcFormatter({ logRecord, stackTrail }) {
     return JSON.stringify({
         stackTrail,