@skmtc/core 0.0.796 → 0.0.798

package/script/oas/securitySchemes/security-scheme-types.d.ts

@@ -1,55 +1,118 @@
 import * as v from 'valibot';
+/**
+ * Data type for HTTP authentication security schemes.
+ *
+ * Represents HTTP authentication mechanisms like Basic, Bearer,
+ * and other HTTP authentication schemes as defined in RFC 7235.
+ */
 export type OasHttpSecuritySchemeData = {
+    /** Security scheme type identifier */
     type: 'http';
+    /** Human-readable description of the security scheme */
     description?: string;
+    /** HTTP authorization scheme (e.g., 'basic', 'bearer') */
     scheme: string;
+    /** Format hint for bearer tokens (e.g., 'JWT') */
     bearerFormat?: string;
 };
+/**
+ * Valibot schema for validating HTTP security scheme data.
+ */
 export declare const oasHttpSecuritySchemeData: v.ObjectSchema<{
     readonly type: v.LiteralSchema<"http", undefined>;
     readonly description: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
     readonly scheme: v.StringSchema<undefined>;
     readonly bearerFormat: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
 }, undefined>;
+/**
+ * Data type for API key authentication security schemes.
+ *
+ * Represents API key authentication where the key is passed
+ * via header, query parameter, or cookie.
+ */
 export type OasApiKeySecuritySchemeData = {
+    /** Security scheme type identifier */
     type: 'apiKey';
+    /** Human-readable description of the security scheme */
     description?: string;
+    /** Name of the header, query parameter, or cookie */
     name: string;
+    /** Location where the API key should be sent */
     in: 'header' | 'query' | 'cookie';
 };
+/**
+ * Valibot schema for validating API key security scheme data.
+ */
 export declare const oasApiKeySecuritySchemeData: v.ObjectSchema<{
     readonly type: v.LiteralSchema<"apiKey", undefined>;
     readonly description: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
     readonly name: v.StringSchema<undefined>;
     readonly in: v.UnionSchema<[v.LiteralSchema<"header", undefined>, v.LiteralSchema<"query", undefined>, v.LiteralSchema<"cookie", undefined>], undefined>;
 }, undefined>;
+/**
+ * Data type for OAuth2 implicit flow configuration.
+ *
+ * Represents the implicit OAuth2 flow where tokens are obtained
+ * directly from the authorization endpoint without client authentication.
+ */
 export type OasImplicitOAuth2FlowData = {
+    /** URL for the OAuth2 authorization endpoint */
     authorizationUrl: string;
+    /** Optional URL for token refresh */
     refreshUrl: string | undefined;
+    /** Available scopes mapped to their descriptions */
     scopes: Record<string, string>;
 };
+/**
+ * Valibot schema for validating OAuth2 implicit flow data.
+ */
 export declare const oasImplicitOAuth2FlowData: v.ObjectSchema<{
     readonly authorizationUrl: v.StringSchema<undefined>;
     readonly refreshUrl: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
     readonly scopes: v.RecordSchema<v.StringSchema<undefined>, v.StringSchema<undefined>, undefined>;
 }, undefined>;
+/**
+ * Data type for OAuth2 authorization code flow configuration.
+ *
+ * Represents the authorization code OAuth2 flow, the most secure
+ * flow suitable for server-side applications with client authentication.
+ */
 export type OasAuthorizationCodeOAuth2FlowData = {
+    /** URL for the OAuth2 authorization endpoint */
     authorizationUrl: string;
+    /** URL for the OAuth2 token endpoint */
     tokenUrl: string;
+    /** Optional URL for token refresh */
     refreshUrl: string | undefined;
+    /** Available scopes mapped to their descriptions */
     scopes: Record<string, string>;
 };
+/**
+ * Valibot schema for validating OAuth2 authorization code flow data.
+ */
 export declare const oasAuthorizationCodeOAuth2FlowData: v.ObjectSchema<{
     readonly authorizationUrl: v.StringSchema<undefined>;
     readonly tokenUrl: v.StringSchema<undefined>;
     readonly refreshUrl: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
     readonly scopes: v.RecordSchema<v.StringSchema<undefined>, v.StringSchema<undefined>, undefined>;
 }, undefined>;
+/**
+ * Data type for OAuth2 client credentials flow configuration.
+ *
+ * Represents the client credentials OAuth2 flow used for
+ * server-to-server authentication without user involvement.
+ */
 export type OasClientCredentialsOAuth2FlowData = {
+    /** URL for the OAuth2 token endpoint */
     tokenUrl: string;
+    /** Optional URL for token refresh */
     refreshUrl: string | undefined;
+    /** Available scopes mapped to their descriptions */
     scopes: Record<string, string>;
 };
+/**
+ * Valibot schema for validating OAuth2 client credentials flow data.
+ */
 export declare const oasClientCredentialsOAuth2FlowData: v.ObjectSchema<{
     readonly tokenUrl: v.StringSchema<undefined>;
     readonly refreshUrl: v.OptionalSchema<v.StringSchema<undefined>, undefined>;

package/script/oas/securitySchemes/security-scheme-types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"security-scheme-types.d.ts","sourceRoot":"","sources":["../../../src/oas/securitySchemes/security-scheme-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAE5B,MAAM,MAAM,yBAAyB,GAAG;IACtC,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,MAAM,EAAE,MAAM,CAAA;IACd,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB,CAAA;AAED,eAAO,MAAM,yBAAyB;;;;;aAKpC,CAAA;AAEF,MAAM,MAAM,2BAA2B,GAAG;IACxC,IAAI,EAAE,QAAQ,CAAA;IACd,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,IAAI,EAAE,MAAM,CAAA;IACZ,EAAE,EAAE,QAAQ,GAAG,OAAO,GAAG,QAAQ,CAAA;CAClC,CAAA;AAED,eAAO,MAAM,2BAA2B;;;;;aAKtC,CAAA;AAEF,MAAM,MAAM,yBAAyB,GAAG;IACtC,gBAAgB,EAAE,MAAM,CAAA;IACxB,UAAU,EAAE,MAAM,GAAG,SAAS,CAAA;IAC9B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAC/B,CAAA;AAED,eAAO,MAAM,yBAAyB;;;;aAIpC,CAAA;AAEF,MAAM,MAAM,kCAAkC,GAAG;IAC/C,gBAAgB,EAAE,MAAM,CAAA;IACxB,QAAQ,EAAE,MAAM,CAAA;IAChB,UAAU,EAAE,MAAM,GAAG,SAAS,CAAA;IAC9B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAC/B,CAAA;AAED,eAAO,MAAM,kCAAkC;;;;;aAK7C,CAAA;AAEF,MAAM,MAAM,kCAAkC,GAAG;IAC/C,QAAQ,EAAE,MAAM,CAAA;IAChB,UAAU,EAAE,MAAM,GAAG,SAAS,CAAA;IAC9B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAC/B,CAAA;AAED,eAAO,MAAM,kCAAkC;;;;aAI7C,CAAA;AAEF,MAAM,MAAM,yBAAyB,GAAG;IACtC,QAAQ,EAAE,MAAM,CAAA;IAChB,UAAU,EAAE,MAAM,GAAG,SAAS,CAAA;IAC9B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAC/B,CAAA;AAED,eAAO,MAAM,yBAAyB;;;;aAIpC,CAAA;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,iBAAiB,CAAC,EAAE,kCAAkC,CAAA;IACtD,iBAAiB,CAAC,EAAE,kCAAkC,CAAA;IACtD,QAAQ,CAAC,EAAE,yBAAyB,CAAA;IACpC,QAAQ,CAAC,EAAE,yBAAyB,CAAA;CACrC,CAAA;AAED,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;aAK7B,CAAA;AAEF,MAAM,MAAM,2BAA2B,GAAG;IACxC,IAAI,EAAE,QAAQ,CAAA;IACd,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,KAAK,EAAE,kBAAkB,CAAA;CAC1B,CAAA;AAED,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;;;;;;;;;;;aAItC,CAAA;AAEF,MAAM,MAAM,2BAA2B,GAAG;IACxC,IAAI,EAAE,eAAe,CAAA;IACrB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,gBAAgB,EAAE,MAAM,CAAA;CACzB,CAAA;AAED,eAAO,MAAM,2BAA2B;;;;aAItC,CAAA;AAEF,MAAM,MAAM,qBAAqB,GAC7B,yBAAyB,GACzB,2BAA2B,GAC3B,2BAA2B,GAC3B,2BAA2B,CAAA;AAE/B,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;0BAKhC,CAAA"}
+{"version":3,"file":"security-scheme-types.d.ts","sourceRoot":"","sources":["../../../src/oas/securitySchemes/security-scheme-types.ts"],"names":[],"mappings":"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"}

package/script/oas/securitySchemes/security-scheme-types.js

@@ -35,29 +35,44 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.oasSecuritySchemeData = exports.oasOpenIdSecuritySchemeData = exports.oasOAuth2SecuritySchemeData = exports.oasOAuth2FlowsData = exports.oasPasswordOAuth2FlowData = exports.oasClientCredentialsOAuth2FlowData = exports.oasAuthorizationCodeOAuth2FlowData = exports.oasImplicitOAuth2FlowData = exports.oasApiKeySecuritySchemeData = exports.oasHttpSecuritySchemeData = void 0;
 const v = __importStar(require("valibot"));
+/**
+ * Valibot schema for validating HTTP security scheme data.
+ */
 exports.oasHttpSecuritySchemeData = v.object({
     type: v.literal('http'),
     description: v.optional(v.string()),
     scheme: v.string(),
     bearerFormat: v.optional(v.string())
 });
+/**
+ * Valibot schema for validating API key security scheme data.
+ */
 exports.oasApiKeySecuritySchemeData = v.object({
     type: v.literal('apiKey'),
     description: v.optional(v.string()),
     name: v.string(),
     in: v.union([v.literal('header'), v.literal('query'), v.literal('cookie')])
 });
+/**
+ * Valibot schema for validating OAuth2 implicit flow data.
+ */
 exports.oasImplicitOAuth2FlowData = v.object({
     authorizationUrl: v.string(),
     refreshUrl: v.optional(v.string()),
     scopes: v.record(v.string(), v.string())
 });
+/**
+ * Valibot schema for validating OAuth2 authorization code flow data.
+ */
 exports.oasAuthorizationCodeOAuth2FlowData = v.object({
     authorizationUrl: v.string(),
     tokenUrl: v.string(),
     refreshUrl: v.optional(v.string()),
     scopes: v.record(v.string(), v.string())
 });
+/**
+ * Valibot schema for validating OAuth2 client credentials flow data.
+ */
 exports.oasClientCredentialsOAuth2FlowData = v.object({
     tokenUrl: v.string(),
     refreshUrl: v.optional(v.string()),

package/script/run/toV3JsonDocument.d.ts

@@ -1,7 +1,97 @@
 import "../_dnt.polyfills.js";
 import type { OpenAPIV2, OpenAPIV3, OpenAPIV3_1 } from 'openapi-types';
+/**
+ * Union type representing any supported OpenAPI document version.
+ *
+ * SKMTC supports processing OpenAPI/Swagger documents from version 2.0 through 3.1,
+ * automatically converting them to OpenAPI 3.0 format for internal processing.
+ */
 type AnyOasDocument = OpenAPIV2.Document | OpenAPIV3.Document | OpenAPIV3_1.Document;
+/**
+ * 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 declare const stringToSchema: (schema: string) => AnyOasDocument;
+/**
+ * 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 declare const toV3Document: (schema: AnyOasDocument) => Promise<OpenAPIV3.Document>;
 export {};
 //# sourceMappingURL=toV3JsonDocument.d.ts.map

package/script/run/toV3JsonDocument.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"toV3JsonDocument.d.ts","sourceRoot":"","sources":["../../src/run/toV3JsonDocument.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAUtE,KAAK,cAAc,GAAG,SAAS,CAAC,QAAQ,GAAG,SAAS,CAAC,QAAQ,GAAG,WAAW,CAAC,QAAQ,CAAA;AAEpF,eAAO,MAAM,cAAc,GAAI,QAAQ,MAAM,KAAG,cAM/C,CAAA;AAED,eAAO,MAAM,YAAY,GAAU,QAAQ,cAAc,KAAG,OAAO,CAAC,SAAS,CAAC,QAAQ,CA0BrF,CAAA"}
+{"version":3,"file":"toV3JsonDocument.d.ts","sourceRoot":"","sources":["../../src/run/toV3JsonDocument.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAUtE;;;;;GAKG;AACH,KAAK,cAAc,GAAG,SAAS,CAAC,QAAQ,GAAG,SAAS,CAAC,QAAQ,GAAG,WAAW,CAAC,QAAQ,CAAA;AAEpF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,eAAO,MAAM,cAAc,GAAI,QAAQ,MAAM,KAAG,cAM/C,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,eAAO,MAAM,YAAY,GAAU,QAAQ,cAAc,KAAG,OAAO,CAAC,SAAS,CAAC,QAAQ,CA0BrF,CAAA"}

package/script/run/toV3JsonDocument.js

@@ -9,6 +9,43 @@ const parse_js_1 = require("../deps/jsr.io/@std/yaml/1.0.9/parse.js");
 const openapi_down_convert_1 = require("@apiture/openapi-down-convert");
 const ts_pattern_1 = require("ts-pattern");
 const swagger2openapi_1 = __importDefault(require("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
+ */
 const stringToSchema = (schema) => {
     if (schema.trimStart().startsWith('{')) {
         return JSON.parse(schema);
@@ -18,6 +55,53 @@ const stringToSchema = (schema) => {
     }
 };
 exports.stringToSchema = stringToSchema;
+/**
+ * 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
+ */
 const toV3Document = async (schema) => {
     return await (0, ts_pattern_1.match)(schema)
         .with({ openapi: ts_pattern_1.P.string.startsWith('3.0') }, doc => doc)

package/script/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/script/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/script/types/Results.js

@@ -36,6 +36,12 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.resultsItem = exports.resultType = void 0;
 require("../_dnt.polyfills.js");
 const v = __importStar(require("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.
+ */
 exports.resultType = v.union([
     v.literal('success'),
     v.literal('warning'),
@@ -43,4 +49,10 @@ exports.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.
+ */
 exports.resultsItem = v.record(v.string(), v.lazy(() => v.union([exports.resultsItem, exports.resultType, v.array(v.lazy(() => exports.resultsItem))])));