@skmtc/core 0.0.787 → 0.0.789

package/script/context/GenerateContext.d.ts

@@ -114,6 +114,101 @@ type GenerateResult = {
     previews: Record<string, Record<string, Preview>>;
     mappings: Record<string, Record<string, Mapping>>;
 };
+/**
+ * The generation context for the second phase of the SKMTC transformation pipeline.
+ *
+ * `GenerateContext` manages the transformation of parsed OAS (OpenAPI Schema) objects
+ * into code artifacts using pluggable generators. It provides APIs for model and operation
+ * generation, file management, dependency tracking, and artifact registration.
+ *
+ * ## Key Responsibilities
+ *
+ * - **Generator Orchestration**: Executes pluggable model and operation generators
+ * - **Schema Processing**: Provides utilities for working with OAS schemas and references
+ * - **File Management**: Handles file creation, imports, exports, and dependencies
+ * - **Artifact Registration**: Collects generated definitions and files for rendering
+ * - **Type System Integration**: Bridges OAS types with generator-specific type systems
+ * - **Settings Management**: Handles skipping logic and client customizations
+ *
+ * ## Generator Integration
+ *
+ * The context works with two main types of generators:
+ * - **Model Generators**: Transform schema definitions into type definitions
+ * - **Operation Generators**: Transform API operations into client functions
+ *
+ * @example Basic usage in a model generator
+ * ```typescript
+ * import { ModelBase } from '@skmtc/core';
+ *
+ * class TypeScriptInterface extends ModelBase {
+ *   generate(): Definition {
+ *     const schema = this.context.getSchema(this.refName);
+ *
+ *     return new Definition({
+ *       context: this.context,
+ *       identifier: Identifier.createType(this.refName),
+ *       description: schema.description,
+ *       value: {
+ *         generatorKey: this.generatorKey,
+ *         content: this.generateInterfaceBody(schema)
+ *       }
+ *     });
+ *   }
+ * }
+ * ```
+ *
+ * @example Operation generator usage
+ * ```typescript
+ * class ApiClientGenerator extends OperationBase {
+ *   generate(): Definition {
+ *     const operation = this.context.getOperation(this.path, this.method);
+ *
+ *     const functionName = this.context.createOperationName(this.path, this.method);
+ *
+ *     return new Definition({
+ *       context: this.context,
+ *       identifier: Identifier.createVariable(functionName),
+ *       value: {
+ *         generatorKey: this.generatorKey,
+ *         content: this.generateClientFunction(operation)
+ *       }
+ *     });
+ *   }
+ * }
+ * ```
+ *
+ * @example Schema and type system integration
+ * ```typescript
+ * class MyGenerator extends ModelBase {
+ *   generate(): Definition {
+ *     const schema = this.context.getSchema(this.refName);
+ *
+ *     // Transform schema using type system
+ *     const typeOutput = this.context.transformSchema(schema, {
+ *       stringType: 'string',
+ *       numberType: 'number',
+ *       arrayType: (items) => `Array<${items}>`
+ *     });
+ *
+ *     // Register dependencies
+ *     if (schema.hasReferences()) {
+ *       this.context.addImportsToFile('./models/types.ts', {
+ *         './common': ['BaseModel']
+ *       });
+ *     }
+ *
+ *     return new Definition({
+ *       context: this.context,
+ *       identifier: Identifier.createType(this.refName),
+ *       value: {
+ *         generatorKey: this.generatorKey,
+ *         content: typeOutput.content
+ *       }
+ *     });
+ *   }
+ * }
+ * ```
+ */
 export declare class GenerateContext {
     #private;
     oasDocument: OasDocument;

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

@@ -1 +1 @@
-{"version":3,"file":"GenerateContext.d.ts","sourceRoot":"","sources":["../../src/context/GenerateContext.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"GenerateContext.d.ts","sourceRoot":"","sources":["../../src/context/GenerateContext.ts"],"names":[],"mappings":"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"}

package/script/context/GenerateContext.js

@@ -62,6 +62,101 @@ const File_js_1 = require("../dsl/File.js");
 const JsonFile_js_1 = require("../dsl/JsonFile.js");
 const tiny_invariant_1 = __importDefault(require("tiny-invariant"));
 const ts_pattern_1 = require("ts-pattern");
+/**
+ * The generation context for the second phase of the SKMTC transformation pipeline.
+ *
+ * `GenerateContext` manages the transformation of parsed OAS (OpenAPI Schema) objects
+ * into code artifacts using pluggable generators. It provides APIs for model and operation
+ * generation, file management, dependency tracking, and artifact registration.
+ *
+ * ## Key Responsibilities
+ *
+ * - **Generator Orchestration**: Executes pluggable model and operation generators
+ * - **Schema Processing**: Provides utilities for working with OAS schemas and references
+ * - **File Management**: Handles file creation, imports, exports, and dependencies
+ * - **Artifact Registration**: Collects generated definitions and files for rendering
+ * - **Type System Integration**: Bridges OAS types with generator-specific type systems
+ * - **Settings Management**: Handles skipping logic and client customizations
+ *
+ * ## Generator Integration
+ *
+ * The context works with two main types of generators:
+ * - **Model Generators**: Transform schema definitions into type definitions
+ * - **Operation Generators**: Transform API operations into client functions
+ *
+ * @example Basic usage in a model generator
+ * ```typescript
+ * import { ModelBase } from '@skmtc/core';
+ *
+ * class TypeScriptInterface extends ModelBase {
+ *   generate(): Definition {
+ *     const schema = this.context.getSchema(this.refName);
+ *
+ *     return new Definition({
+ *       context: this.context,
+ *       identifier: Identifier.createType(this.refName),
+ *       description: schema.description,
+ *       value: {
+ *         generatorKey: this.generatorKey,
+ *         content: this.generateInterfaceBody(schema)
+ *       }
+ *     });
+ *   }
+ * }
+ * ```
+ *
+ * @example Operation generator usage
+ * ```typescript
+ * class ApiClientGenerator extends OperationBase {
+ *   generate(): Definition {
+ *     const operation = this.context.getOperation(this.path, this.method);
+ *
+ *     const functionName = this.context.createOperationName(this.path, this.method);
+ *
+ *     return new Definition({
+ *       context: this.context,
+ *       identifier: Identifier.createVariable(functionName),
+ *       value: {
+ *         generatorKey: this.generatorKey,
+ *         content: this.generateClientFunction(operation)
+ *       }
+ *     });
+ *   }
+ * }
+ * ```
+ *
+ * @example Schema and type system integration
+ * ```typescript
+ * class MyGenerator extends ModelBase {
+ *   generate(): Definition {
+ *     const schema = this.context.getSchema(this.refName);
+ *
+ *     // Transform schema using type system
+ *     const typeOutput = this.context.transformSchema(schema, {
+ *       stringType: 'string',
+ *       numberType: 'number',
+ *       arrayType: (items) => `Array<${items}>`
+ *     });
+ *
+ *     // Register dependencies
+ *     if (schema.hasReferences()) {
+ *       this.context.addImportsToFile('./models/types.ts', {
+ *         './common': ['BaseModel']
+ *       });
+ *     }
+ *
+ *     return new Definition({
+ *       context: this.context,
+ *       identifier: Identifier.createType(this.refName),
+ *       value: {
+ *         generatorKey: this.generatorKey,
+ *         content: typeOutput.content
+ *       }
+ *     });
+ *   }
+ * }
+ * ```
+ */
 class GenerateContext {
     constructor({ oasDocument, settings, logger, captureCurrentResult, stackTrail, toGeneratorConfigMap }) {
         _GenerateContext_instances.add(this);

package/script/context/ParseContext.d.ts

@@ -5,62 +5,240 @@ import type * as log from '../deps/jsr.io/@std/log/0.224.14/mod.js';
 import type { StackTrail } from './StackTrail.js';
 import * as v from 'valibot';
 import type { IssueType } from './types.js';
+/**
+ * Constructor arguments for {@link ParseContext}.
+ */
 type ConstructorArgs = {
+    /** The OpenAPI v3 document to parse */
     documentObject: OpenAPIV3.Document;
+    /** Logger instance for debug information */
     logger: log.Logger;
+    /** Stack trail for distributed tracing */
     stackTrail: StackTrail;
+    /** Whether to suppress console output */
     silent: boolean;
 };
+/**
+ * Return type for the parse operation.
+ */
 export type ParseReturn = {
+    /** The parsed OAS document */
     oasDocument: OasDocument;
+    /** Array of parsing issues encountered */
     issues: ParseIssue[];
 };
+/**
+ * Base type for parse warning messages.
+ */
 type ParseWarningBase = {
+    /** Issue severity level */
     level: 'warning';
+    /** Warning message */
     message: string;
 };
+/**
+ * Base type for parse error messages.
+ */
 type ParseErrorBase = {
+    /** Issue severity level */
     level: 'error';
+    /** The error that occurred */
     error: Error;
 };
+/**
+ * Base union type for parse issues.
+ */
 type ParseIssueBase = ParseErrorBase | ParseWarningBase;
+/**
+ * Arguments for logging issues with a specific key.
+ */
 export type LogIssueArgs = ParseIssueBase & {
+    /** The key where the issue occurred */
     key: string;
+    /** The parent object containing the issue */
     parent: unknown;
+    /** The type of issue for categorization */
     type: IssueType;
 };
+/**
+ * Arguments for logging issues without a specific key.
+ */
 export type LogIssueNoKeyArgs = ParseIssueBase & {
+    /** The parent object containing the issue */
     parent: unknown;
+    /** The type of issue for categorization */
     type: IssueType;
 };
+/**
+ * Arguments for provisional parsing with validation.
+ */
 export type ProvisionalParseArgs<T> = {
+    /** The key being parsed */
     key: string;
+    /** The value to validate */
     value: unknown;
+    /** The parent object context */
     parent: unknown;
+    /** Valibot schema for validation */
     schema: v.GenericSchema<T>;
+    /** Function to generate error messages */
     toMessage: (value: unknown) => string;
+    /** The type of issue for categorization */
     type: IssueType;
 };
+/**
+ * Arguments for logging skipped values during parsing.
+ */
 export type LogSkippedValuesArgs = {
+    /** Record of skipped key-value pairs */
     skipped: Record<string, unknown>;
+    /** The parent object context */
     parent: unknown;
+    /** String description of the parent type */
     parentType: string;
 };
+/**
+ * Represents a parsing error with location context.
+ */
 export type ParseError = {
+    /** Error severity level */
     level: 'error';
+    /** The error that occurred */
     error: Error;
+    /** Location string where the error occurred */
     location: string;
+    /** The parent object context */
     parent: unknown;
+    /** The type of issue for categorization */
     type: IssueType;
 };
+/**
+ * Represents a parsing warning with location context.
+ */
 export type ParseWarning = {
+    /** Warning severity level */
     level: 'warning';
+    /** Warning message */
     message: string;
+    /** Location string where the warning occurred */
     location: string;
+    /** The parent object context */
     parent: unknown;
+    /** The type of issue for categorization */
     type: IssueType;
 };
+/**
+ * Union type for all parsing issues.
+ */
 export type ParseIssue = ParseError | ParseWarning;
+/**
+ * The parsing context for the first phase of the SKMTC transformation pipeline.
+ *
+ * `ParseContext` is responsible for converting OpenAPI v3 JSON documents into
+ * the internal OAS (OpenAPI Schema) object representation used by SKMTC. It
+ * provides comprehensive error handling, validation, and issue tracking during
+ * the parsing process.
+ *
+ * This context handles the complex task of transforming external OpenAPI
+ * specifications into type-safe internal representations while maintaining
+ * detailed information about any parsing issues or inconsistencies found.
+ *
+ * ## Key Features
+ *
+ * - **JSON to OAS Conversion**: Transforms OpenAPI JSON into typed OAS objects
+ * - **Validation & Error Handling**: Comprehensive validation with detailed error reporting
+ * - **Issue Tracking**: Collects warnings and errors with precise location information
+ * - **Reference Management**: Handles complex reference resolution and tracking
+ * - **Logging Integration**: Provides detailed logging and tracing capabilities
+ * - **Silent Mode**: Can suppress console output while maintaining error collection
+ *
+ * @example Basic parsing usage
+ * ```typescript
+ * import { ParseContext } from '@skmtc/core';
+ *
+ * const parseContext = new ParseContext({
+ *   documentObject: openApiJsonDocument,
+ *   logger: myLogger,
+ *   stackTrail: traceStack,
+ *   silent: false
+ * });
+ *
+ * const oasDocument = parseContext.parse();
+ *
+ * // Check for parsing issues
+ * if (parseContext.issues.length > 0) {
+ *   console.log('Parsing issues found:');
+ *   parseContext.issues.forEach(issue => {
+ *     console.log(`${issue.level}: ${issue.location} - ${issue.message || issue.error?.message}`);
+ *   });
+ * }
+ *
+ * // Use the parsed document
+ * console.log('Parsed schemas:', Object.keys(oasDocument.components?.schemas || {}));
+ * ```
+ *
+ * @example Error handling during parsing
+ * ```typescript
+ * const parseContext = new ParseContext({
+ *   documentObject: malformedOpenApiDoc,
+ *   logger: logger,
+ *   stackTrail: stack,
+ *   silent: true
+ * });
+ *
+ * try {
+ *   const parsed = parseContext.parse();
+ *
+ *   // Separate errors from warnings
+ *   const errors = parseContext.issues.filter(issue => issue.level === 'error');
+ *   const warnings = parseContext.issues.filter(issue => issue.level === 'warning');
+ *
+ *   if (errors.length > 0) {
+ *     console.error(`${errors.length} parsing errors found`);
+ *     errors.forEach(error => {
+ *       console.error(`Error at ${error.location}: ${error.error.message}`);
+ *     });
+ *   }
+ *
+ *   if (warnings.length > 0) {
+ *     console.warn(`${warnings.length} parsing warnings found`);
+ *     warnings.forEach(warning => {
+ *       console.warn(`Warning at ${warning.location}: ${warning.message}`);
+ *     });
+ *   }
+ * } catch (error) {
+ *   console.error('Critical parsing failure:', error);
+ * }
+ * ```
+ *
+ * @example Integration with CoreContext
+ * ```typescript
+ * // Typically used within CoreContext.parse()
+ * class CustomCoreContext extends CoreContext {
+ *   parseWithCustomValidation(document: OpenAPIV3.Document) {
+ *     const parseContext = new ParseContext({
+ *       documentObject: document,
+ *       logger: this.logger,
+ *       stackTrail: this.stackTrail,
+ *       silent: this.silent
+ *     });
+ *
+ *     const parsed = parseContext.parse();
+ *
+ *     // Custom post-processing based on issues
+ *     const criticalErrors = parseContext.issues.filter(issue =>
+ *       issue.level === 'error' && issue.type === 'schema-validation'
+ *     );
+ *
+ *     if (criticalErrors.length > 0) {
+ *       throw new Error(`Schema validation failed: ${criticalErrors.length} critical errors`);
+ *     }
+ *
+ *     return parsed;
+ *   }
+ * }
+ * ```
+ */
 export declare class ParseContext {
     #private;
     documentObject: OpenAPIV3.Document;

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

@@ -1 +1 @@
-{"version":3,"file":"ParseContext.d.ts","sourceRoot":"","sources":["../../src/context/ParseContext.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ParseContext.d.ts","sourceRoot":"","sources":["../../src/context/ParseContext.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAG9C,OAAO,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAA;AACzD,OAAO,KAAK,KAAK,GAAG,MAAM,yCAAyC,CAAA;AACnE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAEjD,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAC5B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAE3C;;GAEG;AACH,KAAK,eAAe,GAAG;IACrB,uCAAuC;IACvC,cAAc,EAAE,SAAS,CAAC,QAAQ,CAAA;IAClC,4CAA4C;IAC5C,MAAM,EAAE,GAAG,CAAC,MAAM,CAAA;IAClB,0CAA0C;IAC1C,UAAU,EAAE,UAAU,CAAA;IACtB,yCAAyC;IACzC,MAAM,EAAE,OAAO,CAAA;CAChB,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,8BAA8B;IAC9B,WAAW,EAAE,WAAW,CAAA;IACxB,0CAA0C;IAC1C,MAAM,EAAE,UAAU,EAAE,CAAA;CACrB,CAAA;AAED;;GAEG;AACH,KAAK,gBAAgB,GAAG;IACtB,2BAA2B;IAC3B,KAAK,EAAE,SAAS,CAAA;IAChB,sBAAsB;IACtB,OAAO,EAAE,MAAM,CAAA;CAChB,CAAA;AAED;;GAEG;AACH,KAAK,cAAc,GAAG;IACpB,2BAA2B;IAC3B,KAAK,EAAE,OAAO,CAAA;IACd,8BAA8B;IAC9B,KAAK,EAAE,KAAK,CAAA;CACb,CAAA;AAED;;GAEG;AACH,KAAK,cAAc,GAAG,cAAc,GAAG,gBAAgB,CAAA;AAEvD;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,cAAc,GAAG;IAC1C,uCAAuC;IACvC,GAAG,EAAE,MAAM,CAAA;IACX,6CAA6C;IAC7C,MAAM,EAAE,OAAO,CAAA;IACf,2CAA2C;IAC3C,IAAI,EAAE,SAAS,CAAA;CAChB,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG,cAAc,GAAG;IAC/C,6CAA6C;IAC7C,MAAM,EAAE,OAAO,CAAA;IACf,2CAA2C;IAC3C,IAAI,EAAE,SAAS,CAAA;CAChB,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,oBAAoB,CAAC,CAAC,IAAI;IACpC,2BAA2B;IAC3B,GAAG,EAAE,MAAM,CAAA;IACX,4BAA4B;IAC5B,KAAK,EAAE,OAAO,CAAA;IACd,gCAAgC;IAChC,MAAM,EAAE,OAAO,CAAA;IACf,oCAAoC;IACpC,MAAM,EAAE,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAA;IAC1B,0CAA0C;IAC1C,SAAS,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,MAAM,CAAA;IACrC,2CAA2C;IAC3C,IAAI,EAAE,SAAS,CAAA;CAChB,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,wCAAwC;IACxC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAChC,gCAAgC;IAChC,MAAM,EAAE,OAAO,CAAA;IACf,4CAA4C;IAC5C,UAAU,EAAE,MAAM,CAAA;CACnB,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,2BAA2B;IAC3B,KAAK,EAAE,OAAO,CAAA;IACd,8BAA8B;IAC9B,KAAK,EAAE,KAAK,CAAA;IACZ,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,CAAA;IAChB,gCAAgC;IAChC,MAAM,EAAE,OAAO,CAAA;IACf,2CAA2C;IAC3C,IAAI,EAAE,SAAS,CAAA;CAChB,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,6BAA6B;IAC7B,KAAK,EAAE,SAAS,CAAA;IAChB,sBAAsB;IACtB,OAAO,EAAE,MAAM,CAAA;IACf,iDAAiD;IACjD,QAAQ,EAAE,MAAM,CAAA;IAChB,gCAAgC;IAChC,MAAM,EAAE,OAAO,CAAA;IACf,2CAA2C;IAC3C,IAAI,EAAE,SAAS,CAAA;CAChB,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,YAAY,CAAA;AAElD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2GG;AACH,qBAAa,YAAY;;IACvB,cAAc,EAAE,SAAS,CAAC,QAAQ,CAAA;IAClC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAA;IAClB,WAAW,EAAE,WAAW,CAAA;IACxB,UAAU,EAAE,UAAU,CAAA;IACtB,MAAM,EAAE,UAAU,EAAE,CAAA;IACpB,MAAM,EAAE,OAAO,CAAA;gBAGH,EAAE,cAAc,EAAE,MAAM,EAAE,UAAU,EAAE,MAAa,EAAE,EAAE,eAAe;IAWlF,KAAK,IAAI,WAAW;IAWpB,kBAAkB;IAoBlB,WAAW,CAAC,UAAU,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM;IAMhD,gBAAgB,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS;IAQvD,KAAK,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC;IAIlD,gBAAgB,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,EAAE,oBAAoB;IAYtE,gBAAgB,CAAC,CAAC,EAAE,EAClB,GAAG,EACH,KAAK,EACL,MAAM,EACN,MAAM,EACN,SAAS,EACT,IAAI,EACL,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,SAAS;IAgB1C,QAAQ,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,KAAK,EAAE,EAAE,YAAY;IAItD,aAAa,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,KAAK,EAAE,EAAE,iBAAiB;CAqB5D;AAED,eAAO,MAAM,WAAW,GAAI,QAAQ,MAAM,KAAG,SAAS,CAAC,QAMtD,CAAA"}

package/script/context/ParseContext.js

@@ -52,6 +52,114 @@ const toDocumentFieldsV3_js_1 = require("../oas/document/toDocumentFieldsV3.js")
 const Document_js_1 = require("../oas/document/Document.js");
 const tracer_js_1 = require("../helpers/tracer.js");
 const v = __importStar(require("valibot"));
+/**
+ * The parsing context for the first phase of the SKMTC transformation pipeline.
+ *
+ * `ParseContext` is responsible for converting OpenAPI v3 JSON documents into
+ * the internal OAS (OpenAPI Schema) object representation used by SKMTC. It
+ * provides comprehensive error handling, validation, and issue tracking during
+ * the parsing process.
+ *
+ * This context handles the complex task of transforming external OpenAPI
+ * specifications into type-safe internal representations while maintaining
+ * detailed information about any parsing issues or inconsistencies found.
+ *
+ * ## Key Features
+ *
+ * - **JSON to OAS Conversion**: Transforms OpenAPI JSON into typed OAS objects
+ * - **Validation & Error Handling**: Comprehensive validation with detailed error reporting
+ * - **Issue Tracking**: Collects warnings and errors with precise location information
+ * - **Reference Management**: Handles complex reference resolution and tracking
+ * - **Logging Integration**: Provides detailed logging and tracing capabilities
+ * - **Silent Mode**: Can suppress console output while maintaining error collection
+ *
+ * @example Basic parsing usage
+ * ```typescript
+ * import { ParseContext } from '@skmtc/core';
+ *
+ * const parseContext = new ParseContext({
+ *   documentObject: openApiJsonDocument,
+ *   logger: myLogger,
+ *   stackTrail: traceStack,
+ *   silent: false
+ * });
+ *
+ * const oasDocument = parseContext.parse();
+ *
+ * // Check for parsing issues
+ * if (parseContext.issues.length > 0) {
+ *   console.log('Parsing issues found:');
+ *   parseContext.issues.forEach(issue => {
+ *     console.log(`${issue.level}: ${issue.location} - ${issue.message || issue.error?.message}`);
+ *   });
+ * }
+ *
+ * // Use the parsed document
+ * console.log('Parsed schemas:', Object.keys(oasDocument.components?.schemas || {}));
+ * ```
+ *
+ * @example Error handling during parsing
+ * ```typescript
+ * const parseContext = new ParseContext({
+ *   documentObject: malformedOpenApiDoc,
+ *   logger: logger,
+ *   stackTrail: stack,
+ *   silent: true
+ * });
+ *
+ * try {
+ *   const parsed = parseContext.parse();
+ *
+ *   // Separate errors from warnings
+ *   const errors = parseContext.issues.filter(issue => issue.level === 'error');
+ *   const warnings = parseContext.issues.filter(issue => issue.level === 'warning');
+ *
+ *   if (errors.length > 0) {
+ *     console.error(`${errors.length} parsing errors found`);
+ *     errors.forEach(error => {
+ *       console.error(`Error at ${error.location}: ${error.error.message}`);
+ *     });
+ *   }
+ *
+ *   if (warnings.length > 0) {
+ *     console.warn(`${warnings.length} parsing warnings found`);
+ *     warnings.forEach(warning => {
+ *       console.warn(`Warning at ${warning.location}: ${warning.message}`);
+ *     });
+ *   }
+ * } catch (error) {
+ *   console.error('Critical parsing failure:', error);
+ * }
+ * ```
+ *
+ * @example Integration with CoreContext
+ * ```typescript
+ * // Typically used within CoreContext.parse()
+ * class CustomCoreContext extends CoreContext {
+ *   parseWithCustomValidation(document: OpenAPIV3.Document) {
+ *     const parseContext = new ParseContext({
+ *       documentObject: document,
+ *       logger: this.logger,
+ *       stackTrail: this.stackTrail,
+ *       silent: this.silent
+ *     });
+ *
+ *     const parsed = parseContext.parse();
+ *
+ *     // Custom post-processing based on issues
+ *     const criticalErrors = parseContext.issues.filter(issue =>
+ *       issue.level === 'error' && issue.type === 'schema-validation'
+ *     );
+ *
+ *     if (criticalErrors.length > 0) {
+ *       throw new Error(`Schema validation failed: ${criticalErrors.length} critical errors`);
+ *     }
+ *
+ *     return parsed;
+ *   }
+ * }
+ * ```
+ */
 class ParseContext {
     constructor({ documentObject, logger, stackTrail, silent = true }) {
         Object.defineProperty(this, "documentObject", {