@skmtc/core 0.0.796 → 0.0.798

package/esm/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/esm/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/esm/app/validate.js

@@ -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 const checkProjectName = (name) => {
     if (name.length < 2) {

package/esm/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/esm/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/esm/context/CoreContext.js

@@ -278,11 +278,67 @@ export 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 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);
     }
@@ -354,6 +410,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 }
+ * }
+ * ```
+ */
 export function skmtcFormatter({ logRecord, stackTrail }) {
     return JSON.stringify({
         stackTrail,

package/esm/context/GenerateContext.d.ts

@@ -30,76 +30,231 @@ type ConstructorArgs = {
     captureCurrentResult: (result: ResultType) => void;
     toGeneratorConfigMap: <EnrichmentType = undefined>() => GeneratorsMapContainer<EnrichmentType>;
 };
+/**
+ * Arguments for picking a specific export from a generator module.
+ *
+ * Used to select and configure specific exports from generator modules
+ * during the artifact generation process.
+ */
 export type PickArgs = {
+    /** The name of the export to pick from the generator module */
     name: string;
+    /** The file path where the export should be made available */
     exportPath: string;
 };
+/**
+ * Arguments for registering a JSON file in the generation context.
+ *
+ * Used to register JSON configuration files, manifests, or other JSON
+ * data that should be included in the generated output artifacts.
+ */
 export type RegisterJsonArgs = {
+    /** The destination file path where the JSON should be written */
     destinationPath: string;
+    /** The JSON object to write to the file */
     json: Record<string, unknown>;
 };
+/**
+ * Arguments for applying package imports to a generated file.
+ *
+ * Used to configure import statements and dependencies when generating
+ * code files that need to reference external packages or modules.
+ */
 export type ApplyPackageImportsArgs = {
+    /** The destination file path where imports should be applied */
     destinationPath: string;
+    /** The export path for the module being imported */
     exportPath: string;
 };
+/**
+ * Base arguments for registering generated content in the generation context.
+ *
+ * Provides the fundamental configuration options for registering imports,
+ * re-exports, and definitions that will be included in generated files.
+ */
 export type BaseRegisterArgs = {
+    /** Import statements to include, organized by module path */
     imports?: Record<string, ImportNameArg[]>;
+    /** Re-export statements to include, organized by module path */
     reExports?: Record<string, Identifier[]>;
+    /** Definition objects to include in the generated content */
     definitions?: (Definition | undefined)[];
 };
+/**
+ * Arguments for registering generated content with a specific destination.
+ *
+ * Extends BaseRegisterArgs to include a destination path, allowing content
+ * to be registered and associated with a specific output file location.
+ */
 export type RegisterArgs = {
+    /** Import statements to include, organized by module path */
     imports?: Record<string, ImportNameArg[]>;
+    /** Re-export statements to include, organized by module path */
     reExports?: Record<string, Identifier[]>;
+    /** Definition objects to include in the generated content */
     definitions?: (Definition | undefined)[];
+    /** The destination file path where the content should be registered */
     destinationPath: string;
 };
+/**
+ * Arguments for creating and registering a definition from a schema.
+ *
+ * Used to transform OpenAPI schema objects into code definitions and
+ * register them in the generation context for output file creation.
+ *
+ * @template Schema - The schema type extending SchemaType
+ */
 export type CreateAndRegisterDefinition<Schema extends SchemaType> = {
+    /** The OpenAPI schema to transform into a definition */
     schema: Schema;
+    /** The identifier for the generated definition */
     identifier: Identifier;
+    /** The destination file path where the definition should be registered */
     destinationPath: string;
+    /** Function to transform the schema into a generated value */
     schemaToValueFn: SchemaToValueFn;
+    /** Optional root reference name for the schema */
     rootRef?: RefName;
+    /** Whether to exclude this definition from exports */
     noExport?: boolean;
 };
+/**
+ * Arguments for defining and registering a value in the generation context.
+ *
+ * Used to create definitions from pre-generated values and register them
+ * in the generation context for inclusion in output files.
+ *
+ * @template V - The generated value type extending GeneratedValue
+ */
 export type DefineAndRegisterArgs<V extends GeneratedValue> = {
+    /** The identifier for the definition */
     identifier: Identifier;
+    /** The generated value to define */
     value: V;
+    /** The destination file path where the definition should be registered */
     destinationPath: string;
+    /** Whether to exclude this definition from exports */
     noExport?: boolean;
 };
+/**
+ * Arguments for retrieving operation-specific settings.
+ *
+ * Used to get generator-specific configuration for a particular
+ * OpenAPI operation based on its path and HTTP method.
+ */
 export type GetOperationSettingsArgs = {
+    /** The ID of the generator requesting settings */
     generatorId: string;
+    /** The API path for the operation */
     path: string;
+    /** The HTTP method for the operation */
     method: Method;
 };
+/**
+ * Arguments for adding render dependencies for an operation.
+ *
+ * Used to specify additional dependencies that should be included
+ * when rendering code for a specific OpenAPI operation.
+ */
 export type AddRenderDependencyArgs = {
+    /** The ID of the generator adding dependencies */
     generatorId: string;
+    /** The OpenAPI operation requiring dependencies */
     operation: OasOperation;
+    /** Array of dependency names or paths to include */
     dependencies: string[];
 };
+/**
+ * Arguments for retrieving model-specific settings.
+ *
+ * Used to get generator-specific configuration for a particular
+ * OpenAPI model based on its reference name.
+ */
 export type ToModelSettingsArgs = {
+    /** The ID of the generator requesting model settings */
     generatorId: string;
+    /** The reference name of the model */
     refName: RefName;
 };
+/**
+ * Options for inserting an operation into the generation context.
+ *
+ * Configures how an OpenAPI operation should be processed and
+ * included in the generated code output.
+ *
+ * @template T - The generation type extending GenerationType
+ */
 export type InsertOperationOptions<T extends GenerationType> = {
+    /** Whether to exclude this operation from exports */
     noExport?: boolean;
+    /** The type of generation to apply */
     generation?: T;
+    /** Custom destination path for the operation */
     destinationPath?: string;
 };
+/**
+ * Arguments for inserting a normalized model into the generation context.
+ *
+ * Used to process and register OpenAPI schema objects as normalized
+ * model definitions with fallback naming when schema names are unavailable.
+ *
+ * @template Schema - The schema type (OasSchema, OasRef, or OasVoid)
+ */
 export type InsertNormalisedModelArgs<Schema extends OasSchema | OasRef<'schema'> | OasVoid> = {
+    /** Fallback name to use if the schema doesn't have a name */
     fallbackName: string;
+    /** The OpenAPI schema to normalize and insert */
     schema: Schema;
+    /** The destination file path for the model */
     destinationPath: string;
 };
+/**
+ * Options for inserting a normalized model.
+ *
+ * Configures how a normalized model should be processed and
+ * included in the generated code output.
+ */
 export type InsertNormalisedModelOptions = {
+    /** Whether to exclude this model from exports */
     noExport?: boolean;
 };
+/**
+ * Return type for inserting a normalized model.
+ *
+ * Provides type-safe return values based on the schema type being processed.
+ * Returns different Definition types depending on whether the schema is a
+ * reference or a concrete schema.
+ *
+ * @template V - The generated value type
+ * @template Schema - The schema type being processed
+ */
 export type InsertNormalisedModelReturn<V extends GeneratedValue, Schema extends OasSchema | OasRef<'schema'> | OasVoid> = Schema extends OasRef<'schema'> ? Definition<V> : Definition<TypeSystemOutput<SchemaToNonRef<Schema>['type']>>;
+/**
+ * Options for inserting a model into the generation context.
+ *
+ * Configures how a model should be processed and included in
+ * the generated code output.
+ *
+ * @template T - The generation type extending GenerationType
+ */
 export type InsertModelOptions<T extends GenerationType> = {
+    /** Whether to exclude this model from exports */
     noExport?: boolean;
+    /** The type of generation to apply */
     generation?: T;
+    /** Custom destination path for the model */
     destinationPath?: string;
 };
+/**
+ * Return type for insert operations in the generation context.
+ *
+ * Represents the result of inserting content into the generation
+ * context, providing type-safe access to the inserted content.
+ *
+ * @template V - The generated value type
+ * @template T - The generation type
+ * @template EnrichmentType - The enrichment data type
+ */
 export type InsertReturn<V extends GeneratedValue, T extends GenerationType, EnrichmentType> = Inserted<V, T, EnrichmentType>;
 type ToOperationSettingsArgs<V, EnrichmentType = undefined> = {
     operation: OasOperation;
@@ -211,12 +366,19 @@ type GenerateResult = {
  */
 export declare class GenerateContext {
     #private;
+    /** The parsed OpenAPI document being processed */
     oasDocument: OasDocument;
+    /** Client settings for customization (optional) */
     settings: ClientSettings | undefined;
+    /** Logger instance for tracking generation progress */
     logger: log.Logger;
+    /** Function to capture processing results at current stack position */
     captureCurrentResult: (result: ResultType) => void;
+    /** Function that returns the generator configuration map */
     toGeneratorConfigMap: <EnrichmentType = undefined>() => GeneratorsMapContainer<EnrichmentType>;
+    /** Stack trail for tracking current processing context */
     stackTrail: StackTrail;
+    /** Tracking model nesting depth to prevent infinite recursion */
     modelDepth: Record<string, number>;
     constructor({ oasDocument, settings, logger, captureCurrentResult, stackTrail, toGeneratorConfigMap }: ConstructorArgs);
     /**
@@ -316,11 +478,29 @@ type ToOperationSourceArgs = {
     operation: OasOperation;
     generatorId: string;
 };
+/**
+ * Creates an OperationSource from an operation and generator ID.
+ *
+ * Transforms operation and generator information into a source descriptor
+ * that can be used for tracking operation origins in the generation pipeline.
+ *
+ * @param args - Arguments containing operation and generator ID
+ * @returns OperationSource descriptor for the operation
+ */
 export declare const toOperationSource: ({ operation, generatorId }: ToOperationSourceArgs) => OperationSource;
 type ToModelSourceArgs = {
     refName: RefName;
     generatorId: string;
 };
+/**
+ * Creates a ModelSource from a reference name and generator ID.
+ *
+ * Transforms model reference and generator information into a source descriptor
+ * that can be used for tracking model origins in the generation pipeline.
+ *
+ * @param args - Arguments containing reference name and generator ID
+ * @returns ModelSource descriptor for the model
+ */
 export declare const toModelSource: ({ refName, generatorId }: ToModelSourceArgs) => ModelSource;
 export {};
 //# sourceMappingURL=GenerateContext.d.ts.map