@skmtc/core 0.0.793 → 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/tracer.d.ts

@@ -1,4 +1,128 @@
 import type { Logger } from '../deps/jsr.io/@std/log/0.224.14/logger.js';
 import type { StackTrail } from '../context/StackTrail.js';
+/**
+ * Executes a function with distributed tracing support and stack trail management.
+ *
+ * This utility function provides distributed tracing capabilities for the SKMTC
+ * generation pipeline. It manages stack trail tokens that help track execution
+ * context across complex nested operations, making debugging and performance
+ * analysis much easier.
+ *
+ * The tracer ensures proper cleanup of stack trail tokens even if the wrapped
+ * function throws an error, maintaining the integrity of the tracing system.
+ * This is essential for accurate debugging and performance monitoring in
+ * complex code generation scenarios.
+ *
+ * @template T - The return type of the traced function
+ * @param stackTrail - The stack trail instance for tracking execution context
+ * @param token - Token(s) to identify this execution step in traces
+ * @param fn - The function to execute with tracing
+ * @param log - Logger instance for error reporting
+ * @returns The result of the wrapped function execution
+ *
+ * @throws Re-throws any error from the wrapped function after cleanup
+ *
+ * @example Basic tracing usage
+ * ```typescript
+ * import { tracer } from '@skmtc/core';
+ *
+ * class ModelGenerator {
+ *   generateModel(stackTrail: StackTrail, logger: Logger) {
+ *     return tracer(stackTrail, 'generate-model', () => {
+ *       // Complex model generation logic here
+ *       return this.createModelDefinition();
+ *     }, logger);
+ *   }
+ * }
+ * ```
+ *
+ * @example Nested tracing
+ * ```typescript
+ * class ComplexProcessor {
+ *   processSchema(stackTrail: StackTrail, logger: Logger) {
+ *     return tracer(stackTrail, 'process-schema', () => {
+ *       const parsed = tracer(stackTrail, 'parse', () => {
+ *         return this.parseSchema();
+ *       }, logger);
+ *
+ *       const validated = tracer(stackTrail, 'validate', () => {
+ *         return this.validateSchema(parsed);
+ *       }, logger);
+ *
+ *       return tracer(stackTrail, 'transform', () => {
+ *         return this.transformSchema(validated);
+ *       }, logger);
+ *     }, logger);
+ *   }
+ * }
+ *
+ * // Stack trail will show: ['process-schema', 'parse'] -> ['process-schema', 'validate'] -> ['process-schema', 'transform']
+ * ```
+ *
+ * @example Multiple token tracing
+ * ```typescript
+ * const result = tracer(
+ *   stackTrail,
+ *   ['file-generation', 'models.ts'], // Multiple tokens for detailed context
+ *   () => {
+ *     return generateModelsFile();
+ *   },
+ *   logger
+ * );
+ * ```
+ *
+ * @example Error handling with tracing
+ * ```typescript
+ * class SafeGenerator {
+ *   generateWithTracing(stackTrail: StackTrail, logger: Logger) {
+ *     try {
+ *       return tracer(stackTrail, 'risky-operation', () => {
+ *         // This might throw an error
+ *         return this.complexGeneration();
+ *       }, logger);
+ *     } catch (error) {
+ *       // Stack trail is automatically cleaned up
+ *       logger.error(`Generation failed: ${error.message}`);
+ *       return this.fallbackGeneration();
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @example Performance monitoring
+ * ```typescript
+ * class PerformanceAwareGenerator {
+ *   timedGeneration(stackTrail: StackTrail, logger: Logger) {
+ *     const startTime = Date.now();
+ *
+ *     const result = tracer(stackTrail, 'timed-generation', () => {
+ *       return this.heavyComputation();
+ *     }, logger);
+ *
+ *     const duration = Date.now() - startTime;
+ *     logger.info(`Generation completed in ${duration}ms`);
+ *
+ *     return result;
+ *   }
+ * }
+ * ```
+ *
+ * @example Integration with context classes
+ * ```typescript
+ * // Typically used within context classes like this:
+ * class GenerateContext {
+ *   trace<T>(token: string | string[], fn: () => T): T {
+ *     return tracer(this.stackTrail, token, fn, this.logger);
+ *   }
+ *
+ *   processModel(schema: OasSchema) {
+ *     return this.trace(['model', schema.type], () => {
+ *       // Model processing logic
+ *       return this.createModel(schema);
+ *     });
+ *   }
+ * }
+ * ```
+ */
 export declare const tracer: <T>(stackTrail: StackTrail, token: string | string[], fn: () => T, log: Logger) => T;
 //# sourceMappingURL=tracer.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"tracer.d.ts","sourceRoot":"","sources":["../../src/helpers/tracer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,4CAA4C,CAAA;AACxE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAA;AAE1D,eAAO,MAAM,MAAM,GAAI,CAAC,EACtB,YAAY,UAAU,EACtB,OAAO,MAAM,GAAG,MAAM,EAAE,EACxB,IAAI,MAAM,CAAC,EACX,KAAK,MAAM,MAgBZ,CAAA"}
+{"version":3,"file":"tracer.d.ts","sourceRoot":"","sources":["../../src/helpers/tracer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,4CAA4C,CAAA;AACxE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAA;AAE1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2HG;AACH,eAAO,MAAM,MAAM,GAAI,CAAC,EACtB,YAAY,UAAU,EACtB,OAAO,MAAM,GAAG,MAAM,EAAE,EACxB,IAAI,MAAM,CAAC,EACX,KAAK,MAAM,MAgBZ,CAAA"}