@skmtc/core 0.0.795 → 0.0.797

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,108 @@ 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 = {
+    /** The Deno log record containing log level, message, and metadata */
     logRecord: log.LogRecord;
+    /** 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":"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"}

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,

package/script/context/ResultsHandler.d.ts

@@ -3,17 +3,169 @@ import type { LogRecord } from '../deps/jsr.io/@std/log/0.224.14/logger.js';
 import { BaseHandler } from '../deps/jsr.io/@std/log/0.224.14/base_handler.js';
 import type { BaseHandlerOptions } from '../deps/jsr.io/@std/log/0.224.14/base_handler.js';
 import type { CoreContext } from './CoreContext.js';
+/**
+ * Configuration options for the {@link ResultsHandler}.
+ */
 export interface ResultsHandlerOptions extends BaseHandlerOptions {
+    /** The CoreContext instance to capture results to */
     context: CoreContext;
 }
+/**
+ * Custom log handler that captures warning and error results for SKMTC processing.
+ *
+ * The `ResultsHandler` extends Deno's standard library BaseHandler to provide
+ * specialized logging behavior for the SKMTC pipeline. It integrates with the
+ * CoreContext to capture warnings and errors as structured results that can be
+ * analyzed and reported after processing completes.
+ *
+ * This handler ensures that important processing issues are captured and stored
+ * in the context's results system rather than just being logged to the console.
+ *
+ * ## Key Features
+ *
+ * - **Result Capture**: Automatically captures WARN and ERROR logs as results
+ * - **Immediate Flushing**: Critical errors trigger immediate flush
+ * - **Lifecycle Management**: Proper setup and cleanup with event handlers
+ * - **Context Integration**: Seamlessly integrates with CoreContext results system
+ *
+ * @example Setting up the handler
+ * ```typescript
+ * import { getLogger } from '@std/log';
+ * import { ResultsHandler, CoreContext } from '@skmtc/core';
+ *
+ * const context = new CoreContext({
+ *   // ... context options
+ * });
+ *
+ * const handler = new ResultsHandler('WARN', {
+ *   context: context,
+ *   formatter: '[{levelName}] {msg}'
+ * });
+ *
+ * const logger = getLogger();
+ * logger.addHandler(handler);
+ *
+ * // Now warnings and errors will be captured as results
+ * logger.warning('Schema validation issue detected');
+ * logger.error('Failed to process operation');
+ * ```
+ *
+ * @example Integration in pipeline
+ * ```typescript
+ * class ProcessingPipeline {
+ *   async process(document: OasDocument) {
+ *     const context = new CoreContext(options);
+ *
+ *     // Set up results handler
+ *     const handler = new ResultsHandler('WARN', { context });
+ *     const logger = getLogger();
+ *     logger.addHandler(handler);
+ *
+ *     try {
+ *       const result = await this.processDocument(document, context);
+ *
+ *       // Check captured results
+ *       if (context.results.hasWarnings()) {
+ *         console.log('Processing completed with warnings');
+ *       }
+ *
+ *       return result;
+ *     } finally {
+ *       handler.destroy();
+ *     }
+ *   }
+ * }
+ * ```
+ */
 export declare class ResultsHandler extends BaseHandler {
     #private;
+    /** The CoreContext instance for capturing results */
     context: CoreContext;
+    /**
+     * Creates a new ResultsHandler instance.
+     *
+     * @param levelName - The minimum log level to handle
+     * @param options - Handler configuration including CoreContext
+     *
+     * @example
+     * ```typescript
+     * const context = new CoreContext(contextOptions);
+     * const handler = new ResultsHandler('WARN', {
+     *   context,
+     *   formatter: '[{levelName}] {msg}'
+     * });
+     * ```
+     */
     constructor(levelName: LevelName, options: ResultsHandlerOptions);
+    /**
+     * Sets up the handler with event listeners.
+     *
+     * Registers cleanup callbacks for process termination to ensure
+     * proper resource cleanup and result flushing.
+     *
+     * @override
+     */
     setup(): void;
+    /**
+     * Handles incoming log records.
+     *
+     * Processes log records through the base handler and triggers
+     * immediate flushing for critical errors above ERROR level.
+     *
+     * @param logRecord - The log record to handle
+     *
+     * @override
+     */
     handle(logRecord: LogRecord): void;
+    /**
+     * Captures log messages as results in the context.
+     *
+     * Converts log level names to result types and captures them
+     * in the associated CoreContext for later analysis.
+     *
+     * @param levelName - The log level name ('WARN' or 'ERROR')
+     *
+     * @throws {Error} When an unsupported log level is provided
+     *
+     * @example
+     * ```typescript
+     * // This is called automatically by the logging system
+     * handler.log('WARN'); // Captures as 'warning' result
+     * handler.log('ERROR'); // Captures as 'error' result
+     * ```
+     */
     log(levelName: string): void;
+    /**
+     * Flushes any buffered content.
+     *
+     * This implementation resets the internal buffer. Override
+     * this method in subclasses to implement custom flushing behavior.
+     *
+     * @override
+     */
     flush(): void;
+    /**
+     * Destroys the handler and cleans up resources.
+     *
+     * Flushes any remaining content and removes event listeners
+     * to prevent memory leaks.
+     *
+     * @override
+     *
+     * @example
+     * ```typescript
+     * const handler = new ResultsHandler('WARN', { context });
+     *
+     * try {
+     *   // Use handler
+     *   logger.addHandler(handler);
+     *   await processDocument();
+     * } finally {
+     *   // Always clean up
+     *   handler.destroy();
+     * }
+     * ```
+     */
     destroy(): void;
 }
 //# sourceMappingURL=ResultsHandler.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"ResultsHandler.d.ts","sourceRoot":"","sources":["../../src/context/ResultsHandler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAAa,MAAM,4CAA4C,CAAA;AACtF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,4CAA4C,CAAA;AAC3E,OAAO,EAAE,WAAW,EAAE,MAAM,kDAAkD,CAAA;AAC9E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kDAAkD,CAAA;AAC1F,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAGnD,MAAM,WAAW,qBAAsB,SAAQ,kBAAkB;IAC/D,OAAO,EAAE,WAAW,CAAA;CACrB;AAED,qBAAa,cAAe,SAAQ,WAAW;;IAC7C,OAAO,EAAE,WAAW,CAAA;gBAMR,SAAS,EAAE,SAAS,EAAE,OAAO,EAAE,qBAAqB;IAMvD,KAAK;IAML,MAAM,CAAC,SAAS,EAAE,SAAS;IASpC,GAAG,CAAC,SAAS,EAAE,MAAM;IAWrB,KAAK;IAMI,OAAO;CAKjB"}
+{"version":3,"file":"ResultsHandler.d.ts","sourceRoot":"","sources":["../../src/context/ResultsHandler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAAa,MAAM,4CAA4C,CAAA;AACtF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,4CAA4C,CAAA;AAC3E,OAAO,EAAE,WAAW,EAAE,MAAM,kDAAkD,CAAA;AAC9E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kDAAkD,CAAA;AAC1F,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAGnD;;GAEG;AACH,MAAM,WAAW,qBAAsB,SAAQ,kBAAkB;IAC/D,qDAAqD;IACrD,OAAO,EAAE,WAAW,CAAA;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkEG;AACH,qBAAa,cAAe,SAAQ,WAAW;;IAC7C,qDAAqD;IACrD,OAAO,EAAE,WAAW,CAAA;IAOpB;;;;;;;;;;;;;;OAcG;gBACS,SAAS,EAAE,SAAS,EAAE,OAAO,EAAE,qBAAqB;IAMhE;;;;;;;OAOG;IACM,KAAK;IAMd;;;;;;;;;OASG;IACM,MAAM,CAAC,SAAS,EAAE,SAAS;IASpC;;;;;;;;;;;;;;;;OAgBG;IACH,GAAG,CAAC,SAAS,EAAE,MAAM;IAWrB;;;;;;;OAOG;IACH,KAAK;IAWL;;;;;;;;;;;;;;;;;;;;;OAqBG;IACM,OAAO;CAKjB"}