@skmtc/core 0.0.796 → 0.0.797

package/esm/run/toV3JsonDocument.js

@@ -3,6 +3,43 @@ import { parse as parseYaml } from '../deps/jsr.io/@std/yaml/1.0.9/parse.js';
 import { Converter as ThreeOneToThreeZeroConverter } from '@apiture/openapi-down-convert';
 import { match, P } from 'ts-pattern';
 import converter from 'swagger2openapi';
+/**
+ * Parses a string into an OpenAPI document object.
+ *
+ * Automatically detects whether the input string is JSON or YAML format based on
+ * the content, then parses it into an OpenAPI document object. Supports all
+ * OpenAPI versions (2.0, 3.0.x, 3.1.x).
+ *
+ * @param schema - The OpenAPI document as a JSON or YAML string
+ * @returns Parsed OpenAPI document object
+ *
+ * @example Parsing JSON OpenAPI document
+ * ```typescript
+ * const jsonSchema = `{
+ *   "openapi": "3.0.0",
+ *   "info": { "title": "My API", "version": "1.0.0" },
+ *   "paths": {}
+ * }`;
+ * const document = stringToSchema(jsonSchema);
+ * console.log(document.info.title); // "My API"
+ * ```
+ *
+ * @example Parsing YAML OpenAPI document
+ * ```typescript
+ * const yamlSchema = `
+ * openapi: 3.0.0
+ * info:
+ *   title: My API
+ *   version: 1.0.0
+ * paths: {}
+ * `;
+ * const document = stringToSchema(yamlSchema);
+ * console.log(document.info.title); // "My API"
+ * ```
+ *
+ * @throws {SyntaxError} If the JSON is malformed
+ * @throws {Error} If the YAML is malformed
+ */
 export const stringToSchema = (schema) => {
     if (schema.trimStart().startsWith('{')) {
         return JSON.parse(schema);
@@ -11,6 +48,53 @@ export const stringToSchema = (schema) => {
         return parseYaml(schema);
     }
 };
+/**
+ * Converts any OpenAPI document version to OpenAPI 3.0 format.
+ *
+ * SKMTC processes all documents using OpenAPI 3.0 as the internal format.
+ * This function handles version detection and conversion from:
+ * - OpenAPI 3.0.x (returned as-is)
+ * - OpenAPI 3.1.x (downgraded to 3.0 with allOf transformations)
+ * - Swagger 2.0 (upgraded to OpenAPI 3.0)
+ *
+ * @param schema - The OpenAPI document to convert
+ * @returns Promise resolving to an OpenAPI 3.0 document
+ *
+ * @example Converting OpenAPI 3.1 to 3.0
+ * ```typescript
+ * const openapi31Doc = {
+ *   openapi: "3.1.0",
+ *   info: { title: "My API", version: "1.0.0" },
+ *   paths: {}
+ * };
+ * const v3Doc = await toV3Document(openapi31Doc);
+ * console.log(v3Doc.openapi); // "3.0.3" (converted)
+ * ```
+ *
+ * @example Converting Swagger 2.0 to OpenAPI 3.0
+ * ```typescript
+ * const swagger2Doc = {
+ *   swagger: "2.0",
+ *   info: { title: "My API", version: "1.0.0" },
+ *   paths: {}
+ * };
+ * const v3Doc = await toV3Document(swagger2Doc);
+ * console.log(v3Doc.openapi); // "3.0.0" (converted)
+ * ```
+ *
+ * @example OpenAPI 3.0 passthrough
+ * ```typescript
+ * const openapi30Doc = {
+ *   openapi: "3.0.2",
+ *   info: { title: "My API", version: "1.0.0" },
+ *   paths: {}
+ * };
+ * const v3Doc = await toV3Document(openapi30Doc);
+ * console.log(v3Doc === openapi30Doc); // true (same object)
+ * ```
+ *
+ * @throws {Error} If the document version is not recognized or supported
+ */
 export const toV3Document = async (schema) => {
     return await match(schema)
         .with({ openapi: P.string.startsWith('3.0') }, doc => doc)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skmtc/core",
-  "version": "0.0.796",
+  "version": "0.0.797",
   "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,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/dsl/constants.d.ts

@@ -1,2 +1,30 @@
+/**
+ * Marker constant representing an empty or unset value in the SKMTC DSL system.
+ *
+ * This constant is used throughout the DSL to represent placeholders, empty
+ * templates, or uninitialized content. It provides a consistent way to identify
+ * empty states that need to be handled during code generation.
+ *
+ * @example Usage in templates
+ * ```typescript
+ * import { EMPTY } from '@skmtc/core';
+ *
+ * const template = someCondition ? 'actual content' : EMPTY;
+ *
+ * if (template === EMPTY) {
+ *   // Handle empty state
+ *   console.log('No content to generate');
+ * }
+ * ```
+ *
+ * @example DSL content generation
+ * ```typescript
+ * const content = new List([
+ *   'import { User } from "./types";',
+ *   someFeature ? 'import { Admin } from "./admin";' : EMPTY,
+ *   'export { User };'
+ * ]).filter(line => line !== EMPTY);
+ * ```
+ */
 export declare const EMPTY = "__EMPTY__";
 //# sourceMappingURL=constants.d.ts.map

package/script/dsl/constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/dsl/constants.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,KAAK,cAAc,CAAA"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/dsl/constants.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,KAAK,cAAc,CAAA"}

package/script/dsl/constants.js

@@ -1,4 +1,32 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.EMPTY = void 0;
+/**
+ * Marker constant representing an empty or unset value in the SKMTC DSL system.
+ *
+ * This constant is used throughout the DSL to represent placeholders, empty
+ * templates, or uninitialized content. It provides a consistent way to identify
+ * empty states that need to be handled during code generation.
+ *
+ * @example Usage in templates
+ * ```typescript
+ * import { EMPTY } from '@skmtc/core';
+ *
+ * const template = someCondition ? 'actual content' : EMPTY;
+ *
+ * if (template === EMPTY) {
+ *   // Handle empty state
+ *   console.log('No content to generate');
+ * }
+ * ```
+ *
+ * @example DSL content generation
+ * ```typescript
+ * const content = new List([
+ *   'import { User } from "./types";',
+ *   someFeature ? 'import { Admin } from "./admin";' : EMPTY,
+ *   'export { User };'
+ * ]).filter(line => line !== EMPTY);
+ * ```
+ */
 exports.EMPTY = '__EMPTY__';