@skmtc/core 0.0.794 → 0.0.796

package/script/context/ResultsHandler.js

@@ -10,25 +10,143 @@ exports.ResultsHandler = void 0;
 const levels_js_1 = require("../deps/jsr.io/@std/log/0.224.14/levels.js");
 const base_handler_js_1 = require("../deps/jsr.io/@std/log/0.224.14/base_handler.js");
 const ts_pattern_1 = require("ts-pattern");
+/**
+ * Custom log handler that captures warning and error results for SKMTC processing.
+ *
+ * The `ResultsHandler` extends Deno's standard library BaseHandler to provide
+ * specialized logging behavior for the SKMTC pipeline. It integrates with the
+ * CoreContext to capture warnings and errors as structured results that can be
+ * analyzed and reported after processing completes.
+ *
+ * This handler ensures that important processing issues are captured and stored
+ * in the context's results system rather than just being logged to the console.
+ *
+ * ## Key Features
+ *
+ * - **Result Capture**: Automatically captures WARN and ERROR logs as results
+ * - **Immediate Flushing**: Critical errors trigger immediate flush
+ * - **Lifecycle Management**: Proper setup and cleanup with event handlers
+ * - **Context Integration**: Seamlessly integrates with CoreContext results system
+ *
+ * @example Setting up the handler
+ * ```typescript
+ * import { getLogger } from '@std/log';
+ * import { ResultsHandler, CoreContext } from '@skmtc/core';
+ *
+ * const context = new CoreContext({
+ *   // ... context options
+ * });
+ *
+ * const handler = new ResultsHandler('WARN', {
+ *   context: context,
+ *   formatter: '[{levelName}] {msg}'
+ * });
+ *
+ * const logger = getLogger();
+ * logger.addHandler(handler);
+ *
+ * // Now warnings and errors will be captured as results
+ * logger.warning('Schema validation issue detected');
+ * logger.error('Failed to process operation');
+ * ```
+ *
+ * @example Integration in pipeline
+ * ```typescript
+ * class ProcessingPipeline {
+ *   async process(document: OasDocument) {
+ *     const context = new CoreContext(options);
+ *
+ *     // Set up results handler
+ *     const handler = new ResultsHandler('WARN', { context });
+ *     const logger = getLogger();
+ *     logger.addHandler(handler);
+ *
+ *     try {
+ *       const result = await this.processDocument(document, context);
+ *
+ *       // Check captured results
+ *       if (context.results.hasWarnings()) {
+ *         console.log('Processing completed with warnings');
+ *       }
+ *
+ *       return result;
+ *     } finally {
+ *       handler.destroy();
+ *     }
+ *   }
+ * }
+ * ```
+ */
 class ResultsHandler extends base_handler_js_1.BaseHandler {
+    /**
+     * Creates a new ResultsHandler instance.
+     *
+     * @param levelName - The minimum log level to handle
+     * @param options - Handler configuration including CoreContext
+     *
+     * @example
+     * ```typescript
+     * const context = new CoreContext(contextOptions);
+     * const handler = new ResultsHandler('WARN', {
+     *   context,
+     *   formatter: '[{levelName}] {msg}'
+     * });
+     * ```
+     */
     constructor(levelName, options) {
         super(levelName, options);
         _ResultsHandler_instances.add(this);
+        /** The CoreContext instance for capturing results */
         Object.defineProperty(this, "context", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /** Bound callback for cleanup on process unload */
         _ResultsHandler_unloadCallback.set(this, (() => {
             this.destroy();
-        }).bind(this));
+        }).bind(this)
+        /**
+         * Creates a new ResultsHandler instance.
+         *
+         * @param levelName - The minimum log level to handle
+         * @param options - Handler configuration including CoreContext
+         *
+         * @example
+         * ```typescript
+         * const context = new CoreContext(contextOptions);
+         * const handler = new ResultsHandler('WARN', {
+         *   context,
+         *   formatter: '[{levelName}] {msg}'
+         * });
+         * ```
+         */
+        );
         this.context = options.context;
     }
+    /**
+     * Sets up the handler with event listeners.
+     *
+     * Registers cleanup callbacks for process termination to ensure
+     * proper resource cleanup and result flushing.
+     *
+     * @override
+     */
     setup() {
         __classPrivateFieldGet(this, _ResultsHandler_instances, "m", _ResultsHandler_resetBuffer).call(this);
         addEventListener('unload', __classPrivateFieldGet(this, _ResultsHandler_unloadCallback, "f"));
     }
+    /**
+     * Handles incoming log records.
+     *
+     * Processes log records through the base handler and triggers
+     * immediate flushing for critical errors above ERROR level.
+     *
+     * @param logRecord - The log record to handle
+     *
+     * @override
+     */
     handle(logRecord) {
         super.handle(logRecord);
         // Immediately flush if log level is higher than ERROR
@@ -36,6 +154,23 @@ class ResultsHandler extends base_handler_js_1.BaseHandler {
             this.flush();
         }
     }
+    /**
+     * Captures log messages as results in the context.
+     *
+     * Converts log level names to result types and captures them
+     * in the associated CoreContext for later analysis.
+     *
+     * @param levelName - The log level name ('WARN' or 'ERROR')
+     *
+     * @throws {Error} When an unsupported log level is provided
+     *
+     * @example
+     * ```typescript
+     * // This is called automatically by the logging system
+     * handler.log('WARN'); // Captures as 'warning' result
+     * handler.log('ERROR'); // Captures as 'error' result
+     * ```
+     */
     log(levelName) {
         this.context.captureCurrentResult((0, ts_pattern_1.match)(levelName)
             .with('WARN', () => 'warning')
@@ -44,9 +179,39 @@ class ResultsHandler extends base_handler_js_1.BaseHandler {
             throw new Error(`Unexpected log level name: ${levelName}`);
         }));
     }
+    /**
+     * Flushes any buffered content.
+     *
+     * This implementation resets the internal buffer. Override
+     * this method in subclasses to implement custom flushing behavior.
+     *
+     * @override
+     */
     flush() {
         __classPrivateFieldGet(this, _ResultsHandler_instances, "m", _ResultsHandler_resetBuffer).call(this);
     }
+    /**
+     * Destroys the handler and cleans up resources.
+     *
+     * Flushes any remaining content and removes event listeners
+     * to prevent memory leaks.
+     *
+     * @override
+     *
+     * @example
+     * ```typescript
+     * const handler = new ResultsHandler('WARN', { context });
+     *
+     * try {
+     *   // Use handler
+     *   logger.addHandler(handler);
+     *   await processDocument();
+     * } finally {
+     *   // Always clean up
+     *   handler.destroy();
+     * }
+     * ```
+     */
     destroy() {
         this.flush();
         removeEventListener('unload', __classPrivateFieldGet(this, _ResultsHandler_unloadCallback, "f"));

package/script/context/StackTrail.d.ts

@@ -1,18 +1,311 @@
 import "../_dnt.polyfills.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)
+ * ```
+ */
 export declare class StackTrail {
     #private;
+    /**
+     * 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?: string[]);
+    /**
+     * 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(): StackTrail;
+    /**
+     * 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: number, end?: number): StackTrail;
+    /**
+     * 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: string[]): boolean;
+    /**
+     * 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(): string[];
+    /**
+     * 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: string | string[]): StackTrail;
+    /**
+     * 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: string): string | 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(): string | undefined;
+    /**
+     * 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: string | string[]): StackTrail;
+    /**
+     * 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: (StackTrail | string)[]): string;
+    /**
+     * 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: string): StackTrail;
+    /**
+     * 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(): string;
+    /**
+     * 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(): string;
 }
 //# sourceMappingURL=StackTrail.d.ts.map

package/script/context/StackTrail.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"StackTrail.d.ts","sourceRoot":"","sources":["../../src/context/StackTrail.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAG9B,qBAAa,UAAU;;gBAGT,KAAK,GAAE,MAAM,EAAO;IAIhC,KAAK,IAAI,UAAU;IAInB,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,UAAU;IAI9C,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO;IAInC,IAAI,UAAU,IAAI,MAAM,EAAE,CAEzB;IAED,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,UAAU;IAgB5C,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAW9C,UAAU,IAAI,MAAM,GAAG,SAAS;IAkBhC,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,UAAU;IAsB5C,MAAM,CAAC,IAAI,CAAC,GAAG,MAAM,EAAE,CAAC,UAAU,GAAG,MAAM,CAAC,EAAE,GAAG,MAAM;IAIvD,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU;IAYvC,MAAM,IAAI,MAAM;IAIhB,QAAQ,IAAI,MAAM;CAOnB"}
+{"version":3,"file":"StackTrail.d.ts","sourceRoot":"","sources":["../../src/context/StackTrail.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAG9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqEG;AACH,qBAAa,UAAU;;IAIrB;;;;;;;;;;;;;OAaG;gBACS,KAAK,GAAE,MAAM,EAAO;IAIhC;;;;;;;;;;;;;;OAcG;IACH,KAAK,IAAI,UAAU;IAInB;;;;;;;;;;;;;;;;;OAiBG;IACH,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,UAAU;IAI9C;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO;IAInC;;;;;;;;;;;OAWG;IACH,IAAI,UAAU,IAAI,MAAM,EAAE,CAEzB;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,UAAU;IAgB5C;;;;;;;;;;;;;;;OAeG;IACH,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAW9C;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,UAAU,IAAI,MAAM,GAAG,SAAS;IAkBhC;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,UAAU;IAsB5C;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,IAAI,CAAC,GAAG,MAAM,EAAE,CAAC,UAAU,GAAG,MAAM,CAAC,EAAE,GAAG,MAAM;IAIvD;;;;;;;;;;;;;;;;;OAiBG;IACH,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU;IAYvC;;;;;;;;;;;;;;OAcG;IACH,MAAM,IAAI,MAAM;IAIhB;;;;;;;;;;;;;;;;;OAiBG;IACH,QAAQ,IAAI,MAAM;CAOnB"}