@skmtc/core 0.0.793 → 0.0.795

package/script/context/StackTrail.js

@@ -15,23 +15,190 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.StackTrail = void 0;
 require("../_dnt.polyfills.js");
 const Components_js_1 = require("../oas/components/Components.js");
+/**
+ * Represents a stack-based trail for tracking document traversal in OpenAPI processing.
+ *
+ * The `StackTrail` class maintains a stack of string frames that represent the current
+ * path through an OpenAPI document structure. It's used throughout the SKMTC pipeline
+ * for tracking context during parsing, generating, and debugging schema processing.
+ *
+ * This class is essential for error reporting, debugging, and maintaining context
+ * when processing nested OpenAPI structures like schemas, operations, and components.
+ *
+ * ## Key Features
+ *
+ * - **Path Tracking**: Maintains a trail of traversed document elements
+ * - **Context Preservation**: Preserves parsing context for error reporting
+ * - **Stack Operations**: Supports push, pop, clone, and manipulation operations
+ * - **Reference Resolution**: Can generate OpenAPI reference strings from trails
+ * - **Serialization**: Supports string serialization and parsing for persistence
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { StackTrail } from '@skmtc/core';
+ *
+ * // Start with empty trail
+ * const trail = new StackTrail();
+ *
+ * // Build a path through document structure
+ * trail.append('components')
+ *      .append('schemas')
+ *      .append('User')
+ *      .append('properties')
+ *      .append('name');
+ *
+ * console.log(trail.toString()); // 'components:schemas:User:properties:name'
+ * ```
+ *
+ * @example Schema reference generation
+ * ```typescript
+ * const schemaTrail = new StackTrail(['components', 'schemas', 'User']);
+ * const ref = schemaTrail.toStackRef();
+ * console.log(ref); // '#/components/schemas/User'
+ * ```
+ *
+ * @example Error context tracking
+ * ```typescript
+ * class SchemaProcessor {
+ *   processSchema(schema: OasSchema, trail: StackTrail) {
+ *     try {
+ *       // Process schema logic
+ *       return this.transformSchema(schema);
+ *     } catch (error) {
+ *       throw new Error(`Error at ${trail.toString()}: ${error.message}`);
+ *       // Error at components:schemas:User:properties:email: Invalid format
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @example Cloning and manipulation
+ * ```typescript
+ * const baseTrail = new StackTrail(['components', 'schemas']);
+ *
+ * // Clone for processing different schemas
+ * const userTrail = baseTrail.clone().append('User');
+ * const productTrail = baseTrail.clone().append('Product');
+ *
+ * console.log(userTrail.toString());    // 'components:schemas:User'
+ * console.log(productTrail.toString()); // 'components:schemas:Product'
+ * console.log(baseTrail.toString());    // 'components:schemas' (unchanged)
+ * ```
+ */
 class StackTrail {
+    /**
+     * Creates a new StackTrail instance.
+     *
+     * @param stack - Initial stack frames (defaults to empty array)
+     *
+     * @example
+     * ```typescript
+     * // Empty trail
+     * const trail1 = new StackTrail();
+     *
+     * // Pre-populated trail
+     * const trail2 = new StackTrail(['components', 'schemas', 'User']);
+     * ```
+     */
     constructor(stack = []) {
+        /** Internal stack of traversal frames */
         _StackTrail_stack.set(this, void 0);
         __classPrivateFieldSet(this, _StackTrail_stack, stack, "f");
     }
+    /**
+     * Creates a shallow copy of the stack trail.
+     *
+     * @returns A new StackTrail instance with copied frames
+     *
+     * @example
+     * ```typescript
+     * const original = new StackTrail(['components', 'schemas']);
+     * const copy = original.clone();
+     *
+     * copy.append('User');
+     * console.log(original.toString()); // 'components:schemas'
+     * console.log(copy.toString());     // 'components:schemas:User'
+     * ```
+     */
     clone() {
         return new StackTrail([...__classPrivateFieldGet(this, _StackTrail_stack, "f")]);
     }
+    /**
+     * Creates a new trail from a slice of the current trail.
+     *
+     * @param start - Starting index (inclusive)
+     * @param end - Ending index (exclusive, optional)
+     * @returns A new StackTrail with sliced frames
+     *
+     * @example
+     * ```typescript
+     * const trail = new StackTrail(['a', 'b', 'c', 'd', 'e']);
+     *
+     * const slice1 = trail.slice(1, 3);
+     * console.log(slice1.toString()); // 'b:c'
+     *
+     * const slice2 = trail.slice(2);
+     * console.log(slice2.toString()); // 'c:d:e'
+     * ```
+     */
     slice(start, end) {
         return new StackTrail(__classPrivateFieldGet(this, _StackTrail_stack, "f").slice(start, end));
     }
+    /**
+     * Checks if all specified frames exist in the trail.
+     *
+     * @param frames - Array of frames to check for
+     * @returns True if all frames are present in the trail
+     *
+     * @example
+     * ```typescript
+     * const trail = new StackTrail(['components', 'schemas', 'User', 'properties']);
+     *
+     * console.log(trail.includes(['schemas', 'User'])); // true
+     * console.log(trail.includes(['schemas', 'Product'])); // false
+     * console.log(trail.includes(['components'])); // true
+     * ```
+     */
     includes(frames) {
         return frames.every(frame => __classPrivateFieldGet(this, _StackTrail_stack, "f").includes(frame));
     }
+    /**
+     * Gets a copy of the current stack frames.
+     *
+     * @returns Array of stack frames in order
+     *
+     * @example
+     * ```typescript
+     * const trail = new StackTrail(['components', 'schemas', 'User']);
+     * const frames = trail.stackTrail;
+     * console.log(frames); // ['components', 'schemas', 'User']
+     * ```
+     */
     get stackTrail() {
         return __classPrivateFieldGet(this, _StackTrail_stack, "f");
     }
+    /**
+     * Appends frame(s) to the end of the trail.
+     *
+     * @param frame - Single frame string or array of frames to append
+     * @returns This StackTrail instance for chaining
+     *
+     * @throws {Error} When frame is not a string or string array
+     *
+     * @example Single frame
+     * ```typescript
+     * const trail = new StackTrail(['components']);
+     * trail.append('schemas').append('User');
+     * console.log(trail.toString()); // 'components:schemas:User'
+     * ```
+     *
+     * @example Multiple frames
+     * ```typescript
+     * const trail = new StackTrail();
+     * trail.append(['components', 'schemas', 'User']);
+     * console.log(trail.toString()); // 'components:schemas:User'
+     * ```
+     */
     append(frame) {
         if (typeof frame === 'string') {
             __classPrivateFieldGet(this, _StackTrail_stack, "f").push(frame);
@@ -43,6 +210,22 @@ class StackTrail {
         }
         throw new Error(`Unexpected stack frame: ${frame}`);
     }
+    /**
+     * Gets the parent name of a property frame.
+     *
+     * This method is specifically designed to find parent object names
+     * for property trails in schema processing.
+     *
+     * @param frame - The frame name to find the parent of
+     * @returns Parent name if found, undefined otherwise
+     *
+     * @example
+     * ```typescript
+     * const trail = new StackTrail(['components', 'schemas', 'User', 'properties', 'email']);
+     * const parent = trail.getParentOf('email');
+     * console.log(parent); // 'User'
+     * ```
+     */
     getParentOf(frame) {
         const lastItemIndex = this.stackTrail.length - 1;
         if (this.stackTrail?.[lastItemIndex] === frame &&
@@ -51,6 +234,28 @@ class StackTrail {
             return typeof parentName === 'string' ? parentName : undefined;
         }
     }
+    /**
+     * Converts the trail to an OpenAPI reference string if applicable.
+     *
+     * Only trails that represent valid OpenAPI component references
+     * (starting with 'components') can be converted to reference strings.
+     *
+     * @returns OpenAPI reference string or undefined if not a valid reference trail
+     *
+     * @example Valid reference trail
+     * ```typescript
+     * const trail = new StackTrail(['components', 'schemas', 'User']);
+     * const ref = trail.toStackRef();
+     * console.log(ref); // '#/components/schemas/User'
+     * ```
+     *
+     * @example Invalid trail
+     * ```typescript
+     * const trail = new StackTrail(['paths', '/users', 'get']);
+     * const ref = trail.toStackRef();
+     * console.log(ref); // undefined
+     * ```
+     */
     toStackRef() {
         const [first, second, third] = this.stackTrail;
         if (first !== 'components') {
@@ -64,6 +269,29 @@ class StackTrail {
         }
         return `#/${first}/${second}/${third}`;
     }
+    /**
+     * Removes frame(s) from the end of the trail.
+     *
+     * @param frame - Single frame string or array of frames to remove
+     * @returns This StackTrail instance for chaining
+     *
+     * @throws {Error} When trying to remove a frame that doesn't match the last frame
+     * @throws {Error} When frame is not a string or string array
+     *
+     * @example Single frame removal
+     * ```typescript
+     * const trail = new StackTrail(['components', 'schemas', 'User', 'properties']);
+     * trail.remove('properties');
+     * console.log(trail.toString()); // 'components:schemas:User'
+     * ```
+     *
+     * @example Multiple frame removal
+     * ```typescript
+     * const trail = new StackTrail(['components', 'schemas', 'User', 'properties', 'name']);
+     * trail.remove(['name', 'properties']);
+     * console.log(trail.toString()); // 'components:schemas:User'
+     * ```
+     */
     remove(frame) {
         if (typeof frame === 'string') {
             const lastItem = __classPrivateFieldGet(this, _StackTrail_stack, "f")[__classPrivateFieldGet(this, _StackTrail_stack, "f").length - 1];
@@ -79,9 +307,42 @@ class StackTrail {
         }
         throw new Error(`Unexpected stack frame: ${frame}`);
     }
+    /**
+     * Joins multiple stacks or strings into a single colon-separated string.
+     *
+     * @param stacks - Array of StackTrail instances or strings to join
+     * @returns Joined string with colon separators
+     *
+     * @example
+     * ```typescript
+     * const trail1 = new StackTrail(['components', 'schemas']);
+     * const trail2 = new StackTrail(['User', 'properties']);
+     *
+     * const joined = StackTrail.join(trail1, 'separator', trail2);
+     * console.log(joined); // 'components:schemas:separator:User:properties'
+     * ```
+     */
     static join(...stacks) {
         return stacks.map(stack => stack.toString()).join(':');
     }
+    /**
+     * Parses a colon-separated string into a StackTrail instance.
+     *
+     * @param value - Colon-separated string to parse
+     * @returns New StackTrail instance
+     *
+     * @throws {Error} When the string contains empty tokens
+     *
+     * @example
+     * ```typescript
+     * const trail = StackTrail.parse('components:schemas:User:properties:name');
+     * console.log(trail.stackTrail); // ['components', 'schemas', 'User', 'properties', 'name']
+     *
+     * // Handles escaped colons
+     * const escapedTrail = StackTrail.parse('components:schemas:User%3AType');
+     * console.log(escapedTrail.stackTrail); // ['components', 'schemas', 'User:Type']
+     * ```
+     */
     static parse(value) {
         const stack = value.split(':').map(item => {
             if (!item) {
@@ -91,9 +352,42 @@ class StackTrail {
         });
         return new StackTrail(stack);
     }
+    /**
+     * Converts the trail to JSON representation.
+     *
+     * Used for serialization in JSON contexts. Returns the same
+     * as toString() method.
+     *
+     * @returns String representation of the trail
+     *
+     * @example
+     * ```typescript
+     * const trail = new StackTrail(['components', 'schemas', 'User']);
+     * const json = JSON.stringify({ path: trail });
+     * console.log(json); // '{"path":"components:schemas:User"}'
+     * ```
+     */
     toJSON() {
         return this.toString();
     }
+    /**
+     * Converts the trail to a colon-separated string representation.
+     *
+     * Colons within frame names are escaped as '%3A' to avoid conflicts
+     * with the separator character.
+     *
+     * @returns String representation of the trail
+     *
+     * @example
+     * ```typescript
+     * const trail = new StackTrail(['components', 'schemas', 'User']);
+     * console.log(trail.toString()); // 'components:schemas:User'
+     *
+     * // With colon in frame name
+     * const trailWithColon = new StackTrail(['components', 'schemas', 'User:Type']);
+     * console.log(trailWithColon.toString()); // 'components:schemas:User%3AType'
+     * ```
+     */
     toString() {
         return __classPrivateFieldGet(this, _StackTrail_stack, "f")
             .map(item => {

package/script/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/script/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"}