@skmtc/core 0.0.792 → 0.0.794

package/esm/helpers/ResultsLog.d.ts

@@ -1,8 +1,201 @@
 import type { ResultsItem, ResultType } from '../types/Results.js';
+/**
+ * Manages and organizes generation results with intelligent prioritization.
+ *
+ * `ResultsLog` tracks the outcomes of code generation operations, maintaining
+ * a hierarchical structure of results organized by stack trail paths. It implements
+ * intelligent result prioritization, ensuring that more severe results (errors)
+ * take precedence over less severe ones (success, warnings) when multiple results
+ * exist for the same path.
+ *
+ * The class is designed to work with the SKMTC tracing system, using stack trail
+ * identifiers to organize results in a meaningful hierarchical structure that
+ * reflects the execution flow of the generation process.
+ *
+ * ## Key Features
+ *
+ * - **Result Prioritization**: Automatically prioritizes more severe results
+ * - **Hierarchical Organization**: Organizes results by stack trail paths
+ * - **Tree Structure**: Converts flat result logs into nested tree structures
+ * - **Duplicate Handling**: Prevents less severe results from overwriting more severe ones
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { ResultsLog } from '@skmtc/core';
+ *
+ * const resultsLog = new ResultsLog();
+ *
+ * // Capture results from different parts of generation
+ * resultsLog.capture('models:User', 'success');
+ * resultsLog.capture('models:Product', 'error');
+ * resultsLog.capture('types:Status', 'success');
+ *
+ * // Convert to hierarchical structure
+ * const tree = resultsLog.toTree();
+ * console.log(tree);
+ * // {
+ * //   models: {
+ * //     User: 'success',
+ * //     Product: 'error'
+ * //   },
+ * //   types: {
+ * //     Status: 'success'
+ * //   }
+ * // }
+ * ```
+ *
+ * @example Result prioritization
+ * ```typescript
+ * const resultsLog = new ResultsLog();
+ *
+ * // First capture a success
+ * resultsLog.capture('api:createUser', 'success');
+ *
+ * // Later encounter an error at the same path
+ * resultsLog.capture('api:createUser', 'error');
+ *
+ * // Error takes precedence
+ * const tree = resultsLog.toTree();
+ * console.log(tree.api.createUser); // 'error'
+ *
+ * // But success won't overwrite error
+ * resultsLog.capture('api:createUser', 'success');
+ * console.log(resultsLog.toTree().api.createUser); // Still 'error'
+ * ```
+ *
+ * @example Complex nested paths
+ * ```typescript
+ * const resultsLog = new ResultsLog();
+ *
+ * resultsLog.capture('generation:models:User:properties:name', 'success');
+ * resultsLog.capture('generation:models:User:properties:email', 'warning');
+ * resultsLog.capture('generation:models:Product:validation', 'error');
+ * resultsLog.capture('generation:operations:createUser', 'success');
+ *
+ * const tree = resultsLog.toTree();
+ * console.log(tree);
+ * // {
+ * //   generation: {
+ * //     models: {
+ * //       User: {
+ * //         properties: {
+ * //           name: 'success',
+ * //           email: 'warning'
+ * //         }
+ * //       },
+ * //       Product: {
+ * //         validation: 'error'
+ * //       }
+ * //     },
+ * //     operations: {
+ * //       createUser: 'success'
+ * //     }
+ * //   }
+ * // }
+ * ```
+ *
+ * @example Integration with tracing
+ * ```typescript
+ * class TrackedGenerator {
+ *   private resultsLog = new ResultsLog();
+ *
+ *   generateModel(name: string, schema: OasSchema) {
+ *     const stackPath = `models:${name}`;
+ *
+ *     try {
+ *       const model = this.processSchema(schema);
+ *       this.resultsLog.capture(stackPath, 'success');
+ *       return model;
+ *     } catch (error) {
+ *       this.resultsLog.capture(stackPath, 'error');
+ *       throw error;
+ *     }
+ *   }
+ *
+ *   generateOperation(operationId: string, operation: OasOperation) {
+ *     const stackPath = `operations:${operationId}`;
+ *
+ *     if (!this.supportsOperation(operation)) {
+ *       this.resultsLog.capture(stackPath, 'notSupported');
+ *       return null;
+ *     }
+ *
+ *     const result = this.processOperation(operation);
+ *     this.resultsLog.capture(stackPath, 'success');
+ *     return result;
+ *   }
+ *
+ *   getResults(): ResultsItem {
+ *     return this.resultsLog.toTree();
+ *   }
+ * }
+ * ```
+ */
 export declare class ResultsLog {
     #private;
+    /**
+     * Creates a new ResultsLog instance.
+     *
+     * Initializes an empty results tracking system ready to capture
+     * generation outcomes from various parts of the pipeline.
+     */
     constructor();
+    /**
+     * Captures a generation result for a specific stack trail path.
+     *
+     * This method records the outcome of a generation operation, using intelligent
+     * prioritization to ensure that more severe results take precedence over less
+     * severe ones. For example, an error result will not be overwritten by a
+     * success result, but a success can be overwritten by an error.
+     *
+     * @param stackTrail - Colon-separated path identifying the operation location
+     * @param result - The result type to capture (error, warning, success, etc.)
+     *
+     * @example
+     * ```typescript
+     * const resultsLog = new ResultsLog();
+     *
+     * // Capture various results
+     * resultsLog.capture('models:User:properties:email', 'success');
+     * resultsLog.capture('models:User:validation', 'warning');
+     * resultsLog.capture('operations:createUser', 'error');
+     * ```
+     */
     capture(stackTrail: string, result: ResultType): void;
+    /**
+     * Converts the flat results structure into a hierarchical tree.
+     *
+     * This method transforms the internal flat storage (using colon-separated paths)
+     * into a nested object structure that reflects the hierarchy of generation
+     * operations. This makes it easier to understand and process results in
+     * a structured way.
+     *
+     * @returns Nested object structure representing the results hierarchy
+     *
+     * @example
+     * ```typescript
+     * const resultsLog = new ResultsLog();
+     * resultsLog.capture('api:models:User', 'success');
+     * resultsLog.capture('api:operations:getUser', 'error');
+     * resultsLog.capture('types:Status', 'success');
+     *
+     * const tree = resultsLog.toTree();
+     * console.log(tree);
+     * // {
+     * //   api: {
+     * //     models: {
+     * //       User: 'success'
+     * //     },
+     * //     operations: {
+     * //       getUser: 'error'
+     * //     }
+     * //   },
+     * //   types: {
+     * //     Status: 'success'
+     * //   }
+     * // }
+     * ```
+     */
     toTree(): ResultsItem;
 }
 //# sourceMappingURL=ResultsLog.d.ts.map

package/esm/helpers/ResultsLog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ResultsLog.d.ts","sourceRoot":"","sources":["../../src/helpers/ResultsLog.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAA;AAElE,qBAAa,UAAU;;;IAOrB,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU;IAc9C,MAAM,IAAI,WAAW;CAWtB"}
+{"version":3,"file":"ResultsLog.d.ts","sourceRoot":"","sources":["../../src/helpers/ResultsLog.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAA;AAElE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmIG;AACH,qBAAa,UAAU;;IAGrB;;;;;OAKG;;IAKH;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU;IA8B9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH,MAAM,IAAI,WAAW;CAWtB"}

package/esm/helpers/ResultsLog.js

@@ -11,17 +11,210 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
 };
 var _ResultsLog_instances, _ResultsLog_results, _ResultsLog_incomingResultIsWorse;
 import { set } from 'lodash-es';
+/**
+ * Manages and organizes generation results with intelligent prioritization.
+ *
+ * `ResultsLog` tracks the outcomes of code generation operations, maintaining
+ * a hierarchical structure of results organized by stack trail paths. It implements
+ * intelligent result prioritization, ensuring that more severe results (errors)
+ * take precedence over less severe ones (success, warnings) when multiple results
+ * exist for the same path.
+ *
+ * The class is designed to work with the SKMTC tracing system, using stack trail
+ * identifiers to organize results in a meaningful hierarchical structure that
+ * reflects the execution flow of the generation process.
+ *
+ * ## Key Features
+ *
+ * - **Result Prioritization**: Automatically prioritizes more severe results
+ * - **Hierarchical Organization**: Organizes results by stack trail paths
+ * - **Tree Structure**: Converts flat result logs into nested tree structures
+ * - **Duplicate Handling**: Prevents less severe results from overwriting more severe ones
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { ResultsLog } from '@skmtc/core';
+ *
+ * const resultsLog = new ResultsLog();
+ *
+ * // Capture results from different parts of generation
+ * resultsLog.capture('models:User', 'success');
+ * resultsLog.capture('models:Product', 'error');
+ * resultsLog.capture('types:Status', 'success');
+ *
+ * // Convert to hierarchical structure
+ * const tree = resultsLog.toTree();
+ * console.log(tree);
+ * // {
+ * //   models: {
+ * //     User: 'success',
+ * //     Product: 'error'
+ * //   },
+ * //   types: {
+ * //     Status: 'success'
+ * //   }
+ * // }
+ * ```
+ *
+ * @example Result prioritization
+ * ```typescript
+ * const resultsLog = new ResultsLog();
+ *
+ * // First capture a success
+ * resultsLog.capture('api:createUser', 'success');
+ *
+ * // Later encounter an error at the same path
+ * resultsLog.capture('api:createUser', 'error');
+ *
+ * // Error takes precedence
+ * const tree = resultsLog.toTree();
+ * console.log(tree.api.createUser); // 'error'
+ *
+ * // But success won't overwrite error
+ * resultsLog.capture('api:createUser', 'success');
+ * console.log(resultsLog.toTree().api.createUser); // Still 'error'
+ * ```
+ *
+ * @example Complex nested paths
+ * ```typescript
+ * const resultsLog = new ResultsLog();
+ *
+ * resultsLog.capture('generation:models:User:properties:name', 'success');
+ * resultsLog.capture('generation:models:User:properties:email', 'warning');
+ * resultsLog.capture('generation:models:Product:validation', 'error');
+ * resultsLog.capture('generation:operations:createUser', 'success');
+ *
+ * const tree = resultsLog.toTree();
+ * console.log(tree);
+ * // {
+ * //   generation: {
+ * //     models: {
+ * //       User: {
+ * //         properties: {
+ * //           name: 'success',
+ * //           email: 'warning'
+ * //         }
+ * //       },
+ * //       Product: {
+ * //         validation: 'error'
+ * //       }
+ * //     },
+ * //     operations: {
+ * //       createUser: 'success'
+ * //     }
+ * //   }
+ * // }
+ * ```
+ *
+ * @example Integration with tracing
+ * ```typescript
+ * class TrackedGenerator {
+ *   private resultsLog = new ResultsLog();
+ *
+ *   generateModel(name: string, schema: OasSchema) {
+ *     const stackPath = `models:${name}`;
+ *
+ *     try {
+ *       const model = this.processSchema(schema);
+ *       this.resultsLog.capture(stackPath, 'success');
+ *       return model;
+ *     } catch (error) {
+ *       this.resultsLog.capture(stackPath, 'error');
+ *       throw error;
+ *     }
+ *   }
+ *
+ *   generateOperation(operationId: string, operation: OasOperation) {
+ *     const stackPath = `operations:${operationId}`;
+ *
+ *     if (!this.supportsOperation(operation)) {
+ *       this.resultsLog.capture(stackPath, 'notSupported');
+ *       return null;
+ *     }
+ *
+ *     const result = this.processOperation(operation);
+ *     this.resultsLog.capture(stackPath, 'success');
+ *     return result;
+ *   }
+ *
+ *   getResults(): ResultsItem {
+ *     return this.resultsLog.toTree();
+ *   }
+ * }
+ * ```
+ */
 export class ResultsLog {
+    /**
+     * Creates a new ResultsLog instance.
+     *
+     * Initializes an empty results tracking system ready to capture
+     * generation outcomes from various parts of the pipeline.
+     */
     constructor() {
         _ResultsLog_instances.add(this);
         _ResultsLog_results.set(this, void 0);
         __classPrivateFieldSet(this, _ResultsLog_results, {}, "f");
     }
+    /**
+     * Captures a generation result for a specific stack trail path.
+     *
+     * This method records the outcome of a generation operation, using intelligent
+     * prioritization to ensure that more severe results take precedence over less
+     * severe ones. For example, an error result will not be overwritten by a
+     * success result, but a success can be overwritten by an error.
+     *
+     * @param stackTrail - Colon-separated path identifying the operation location
+     * @param result - The result type to capture (error, warning, success, etc.)
+     *
+     * @example
+     * ```typescript
+     * const resultsLog = new ResultsLog();
+     *
+     * // Capture various results
+     * resultsLog.capture('models:User:properties:email', 'success');
+     * resultsLog.capture('models:User:validation', 'warning');
+     * resultsLog.capture('operations:createUser', 'error');
+     * ```
+     */
     capture(stackTrail, result) {
         if (__classPrivateFieldGet(this, _ResultsLog_instances, "m", _ResultsLog_incomingResultIsWorse).call(this, __classPrivateFieldGet(this, _ResultsLog_results, "f")[stackTrail], result)) {
             __classPrivateFieldGet(this, _ResultsLog_results, "f")[stackTrail] = result;
         }
     }
+    /**
+     * Converts the flat results structure into a hierarchical tree.
+     *
+     * This method transforms the internal flat storage (using colon-separated paths)
+     * into a nested object structure that reflects the hierarchy of generation
+     * operations. This makes it easier to understand and process results in
+     * a structured way.
+     *
+     * @returns Nested object structure representing the results hierarchy
+     *
+     * @example
+     * ```typescript
+     * const resultsLog = new ResultsLog();
+     * resultsLog.capture('api:models:User', 'success');
+     * resultsLog.capture('api:operations:getUser', 'error');
+     * resultsLog.capture('types:Status', 'success');
+     *
+     * const tree = resultsLog.toTree();
+     * console.log(tree);
+     * // {
+     * //   api: {
+     * //     models: {
+     * //       User: 'success'
+     * //     },
+     * //     operations: {
+     * //       getUser: 'error'
+     * //     }
+     * //   },
+     * //   types: {
+     * //     Status: 'success'
+     * //   }
+     * // }
+     * ```
+     */
     toTree() {
         const tree = {};
         Object.entries(__classPrivateFieldGet(this, _ResultsLog_results, "f")).forEach(([key, value]) => {
@@ -37,6 +230,26 @@ _ResultsLog_results = new WeakMap(), _ResultsLog_instances = new WeakSet(), _Res
     }
     return resultRankings[current] < resultRankings[incoming];
 };
+/**
+ * Priority rankings for different result types.
+ *
+ * This mapping defines the severity hierarchy used by the ResultsLog to determine
+ * which results should take precedence when multiple results are captured for the
+ * same path. Higher numbers indicate higher severity/priority.
+ *
+ * The ranking system ensures that critical issues (errors) are never masked by
+ * less important results (success), while still allowing for proper escalation
+ * when more severe conditions are encountered.
+ *
+ * @example Ranking hierarchy (high to low priority)
+ * ```
+ * error (50)       - Critical failures that prevent generation
+ * warning (40)     - Issues that allow generation but need attention
+ * success (30)     - Normal successful completion
+ * skipped (20)     - Operations that were intentionally bypassed
+ * notSupported (10) - Features not yet implemented
+ * ```
+ */
 const resultRankings = {
     error: 50,
     warning: 40,

package/esm/helpers/collateExamples.d.ts

@@ -1,10 +1,160 @@
 import "../_dnt.polyfills.js";
 import type { OasRef } from '../oas/ref/Ref.js';
 import type { OasSchema } from '../oas/schema/Schema.js';
+/**
+ * Arguments for collating examples from OpenAPI schemas.
+ */
 type CollatedExampleArgs = {
+    /** The OpenAPI schema or reference to extract examples from */
     objectSchema: OasSchema | OasRef<'schema'> | undefined;
+    /** Current recursion depth (used to prevent infinite loops) */
     depth: number;
 };
+/**
+ * Recursively collates and builds example values from OpenAPI schemas.
+ *
+ * This function traverses OpenAPI schema structures and generates comprehensive
+ * example values based on the schema definitions and any explicit examples provided.
+ * It handles complex nested structures including objects, arrays, unions, and
+ * references while preventing infinite recursion through depth limiting.
+ *
+ * The function prioritizes explicit examples when available and falls back to
+ * generating examples from nested schemas. It's particularly useful for creating
+ * realistic test data, API documentation examples, and mock responses.
+ *
+ * @param args - Configuration for example collation
+ * @param args.objectSchema - The schema to extract examples from
+ * @param args.depth - Current recursion depth (prevents infinite loops)
+ * @returns Collated example value matching the schema structure, or undefined if no examples
+ *
+ * @throws {Error} When recursion depth exceeds 15 levels (prevents stack overflow)
+ *
+ * @example Basic schema examples
+ * ```typescript
+ * import { collateExamples } from '@skmtc/core';
+ *
+ * // String schema with example
+ * const stringSchema = new OasString({ example: 'john.doe@example.com' });
+ * const example = collateExamples({ objectSchema: stringSchema, depth: 0 });
+ * console.log(example); // 'john.doe@example.com'
+ *
+ * // Number schema with example
+ * const numberSchema = new OasNumber({ example: 42 });
+ * const numExample = collateExamples({ objectSchema: numberSchema, depth: 0 });
+ * console.log(numExample); // 42
+ * ```
+ *
+ * @example Object schema examples
+ * ```typescript
+ * // Object schema with nested properties
+ * const userSchema = new OasObject({
+ *   properties: {
+ *     id: new OasInteger({ example: 123 }),
+ *     name: new OasString({ example: 'John Doe' }),
+ *     email: new OasString({ example: 'john@example.com' }),
+ *     age: new OasInteger({ example: 30 })
+ *   }
+ * });
+ *
+ * const userExample = collateExamples({ objectSchema: userSchema, depth: 0 });
+ * console.log(userExample);
+ * // {
+ * //   id: 123,
+ * //   name: 'John Doe',
+ * //   email: 'john@example.com',
+ * //   age: 30
+ * // }
+ * ```
+ *
+ * @example Array schema examples
+ * ```typescript
+ * // Array of objects
+ * const usersArraySchema = new OasArray({
+ *   items: new OasObject({
+ *     properties: {
+ *       id: new OasInteger({ example: 1 }),
+ *       name: new OasString({ example: 'Jane Smith' })
+ *     }
+ *   })
+ * });
+ *
+ * const arrayExample = collateExamples({ objectSchema: usersArraySchema, depth: 0 });
+ * console.log(arrayExample);
+ * // [
+ * //   {
+ * //     id: 1,
+ * //     name: 'Jane Smith'
+ * //   }
+ * // ]
+ * ```
+ *
+ * @example Union schema examples
+ * ```typescript
+ * // Union of string and number
+ * const unionSchema = new OasUnion({
+ *   members: [
+ *     new OasString({ example: 'text-value' }),
+ *     new OasNumber({ example: 99 })
+ *   ]
+ * });
+ *
+ * const unionExample = collateExamples({ objectSchema: unionSchema, depth: 0 });
+ * console.log(unionExample); // 'text-value' (first member with example)
+ * ```
+ *
+ * @example Reference resolution
+ * ```typescript
+ * // Schema with reference to another schema
+ * const addressRef = new OasRef({
+ *   $ref: '#/components/schemas/Address',
+ *   resolve: () => new OasObject({
+ *     properties: {
+ *       street: new OasString({ example: '123 Main St' }),
+ *       city: new OasString({ example: 'Springfield' })
+ *     }
+ *   })
+ * });
+ *
+ * const refExample = collateExamples({ objectSchema: addressRef, depth: 0 });
+ * console.log(refExample);
+ * // {
+ * //   street: '123 Main St',
+ * //   city: 'Springfield'
+ * // }
+ * ```
+ *
+ * @example Depth limiting and error handling
+ * ```typescript
+ * // Deep nesting detection
+ * try {
+ *   const deepExample = collateExamples({ objectSchema: someSchema, depth: 16 });
+ * } catch (error) {
+ *   console.error('Depth limit exceeded:', error.message); // 'Depth limit reached'
+ * }
+ *
+ * // Handling missing schemas
+ * const emptyExample = collateExamples({ objectSchema: undefined, depth: 0 });
+ * console.log(emptyExample); // undefined
+ * ```
+ *
+ * @example Using in API documentation generation
+ * ```typescript
+ * class ApiDocGenerator {
+ *   generateExampleResponse(responseSchema: OasSchema) {
+ *     const example = collateExamples({ objectSchema: responseSchema, depth: 0 });
+ *
+ *     if (example) {
+ *       return {
+ *         description: 'Example response',
+ *         value: example
+ *       };
+ *     }
+ *
+ *     return { description: 'No example available' };
+ *   }
+ * }
+ * ```
+ */
 export declare const collateExamples: ({ objectSchema, depth }: CollatedExampleArgs) => unknown;
 export {};
 //# sourceMappingURL=collateExamples.d.ts.map

package/esm/helpers/collateExamples.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"collateExamples.d.ts","sourceRoot":"","sources":["../../src/helpers/collateExamples.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAC/C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAA;AAIxD,KAAK,mBAAmB,GAAG;IACzB,YAAY,EAAE,SAAS,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,SAAS,CAAA;IACtD,KAAK,EAAE,MAAM,CAAA;CACd,CAAA;AAED,eAAO,MAAM,eAAe,GAAI,yBAAyB,mBAAmB,KAAG,OAwE9E,CAAA"}
+{"version":3,"file":"collateExamples.d.ts","sourceRoot":"","sources":["../../src/helpers/collateExamples.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAC/C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAA;AAIxD;;GAEG;AACH,KAAK,mBAAmB,GAAG;IACzB,+DAA+D;IAC/D,YAAY,EAAE,SAAS,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,SAAS,CAAA;IACtD,+DAA+D;IAC/D,KAAK,EAAE,MAAM,CAAA;CACd,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgJG;AACH,eAAO,MAAM,eAAe,GAAI,yBAAyB,mBAAmB,KAAG,OAwE9E,CAAA"}