@skmtc/core 0.0.788 → 0.0.790

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

package/esm/context/ParseContext.js

@@ -16,6 +16,114 @@ import { toDocumentFieldsV3 } from '../oas/document/toDocumentFieldsV3.js';
 import { OasDocument } from '../oas/document/Document.js';
 import { tracer } from '../helpers/tracer.js';
 import * as v from '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;
+ *   }
+ * }
+ * ```
+ */
 export class ParseContext {
     constructor({ documentObject, logger, stackTrail, silent = true }) {
         Object.defineProperty(this, "documentObject", {

package/esm/context/RenderContext.d.ts

@@ -8,16 +8,206 @@ import type * as log from '../deps/jsr.io/@std/log/0.224.14/mod.js';
 import { File } from '../dsl/File.js';
 import type { Preview, Mapping } from '../types/Preview.js';
 import type { JsonFile } from '../dsl/JsonFile.js';
+/**
+ * Constructor arguments for {@link RenderContext}.
+ */
 type ConstructorArgs = {
+    /** Map of generated files to render */
     files: Map<string, File | JsonFile>;
+    /** Preview data for generated content */
     previews: Record<string, Record<string, Preview>>;
+    /** Mapping data for file relationships */
     mappings: Record<string, Record<string, Mapping>>;
+    /** Optional Prettier configuration for code formatting */
     prettierConfig?: PrettierConfigType;
+    /** Base path for resolving file paths */
     basePath: string | undefined;
+    /** Stack trail for distributed tracing */
     stackTrail: StackTrail;
+    /** Logger instance for debug information */
     logger: log.Logger;
+    /** Function to capture result status */
     captureCurrentResult: (result: ResultType) => void;
 };
+/**
+ * The rendering context for the final phase of the SKMTC transformation pipeline.
+ *
+ * `RenderContext` is responsible for taking the generated artifacts from the generation
+ * phase and rendering them into their final form with proper formatting, path resolution,
+ * and file preparation. It handles code formatting via Prettier, path normalization,
+ * and produces the final artifacts ready for writing to the filesystem.
+ *
+ * This context represents the culmination of the three-phase SKMTC pipeline, transforming
+ * generator outputs into production-ready code files with proper formatting and structure.
+ *
+ * ## Key Features
+ *
+ * - **Code Formatting**: Automatic Prettier formatting for generated TypeScript/JavaScript code
+ * - **Path Resolution**: Intelligent path resolution with base path support
+ * - **Content Collation**: Combines all generated content into organized file structures
+ * - **Metadata Generation**: Tracks file statistics (lines, characters) and relationships
+ * - **Error Tracking**: Comprehensive error handling with Sentry integration
+ * - **Performance Monitoring**: Built-in tracing and performance measurement
+ *
+ * @example Basic rendering usage
+ * ```typescript
+ * import { RenderContext } from '@skmtc/core';
+ *
+ * const renderContext = new RenderContext({
+ *   files: generatedFiles,
+ *   previews: previewData,
+ *   mappings: mappingData,
+ *   prettierConfig: {
+ *     semi: false,
+ *     singleQuote: true,
+ *     trailingComma: 'all'
+ *   },
+ *   basePath: './src/generated',
+ *   stackTrail: traceStack,
+ *   logger: myLogger,
+ *   captureCurrentResult: (result) => console.log(result)
+ * });
+ *
+ * const rendered = await renderContext.render();
+ *
+ * // Access rendered files
+ * Object.entries(rendered.artifacts).forEach(([path, content]) => {
+ *   console.log(`Rendered ${path}: ${rendered.files[path].lines} lines`);
+ *   // Write to filesystem
+ *   await Deno.writeTextFile(path, content);
+ * });
+ * ```
+ *
+ * @example With custom Prettier configuration
+ * ```typescript
+ * const renderContext = new RenderContext({
+ *   files: generatedFiles,
+ *   previews: {},
+ *   mappings: {},
+ *   prettierConfig: {
+ *     parser: 'typescript',
+ *     printWidth: 120,
+ *     tabWidth: 2,
+ *     semi: true,
+ *     singleQuote: true,
+ *     trailingComma: 'es5',
+ *     bracketSpacing: true,
+ *     arrowParens: 'avoid'
+ *   },
+ *   basePath: './packages/api-client/src',
+ *   stackTrail: stack,
+ *   logger: logger,
+ *   captureCurrentResult: resultHandler
+ * });
+ *
+ * const result = await renderContext.render();
+ *
+ * // All TypeScript files are automatically formatted
+ * console.log('Formatted files:', Object.keys(result.artifacts).length);
+ * ```
+ *
+ * @example Processing render results
+ * ```typescript
+ * const rendered = await renderContext.render();
+ *
+ * // Analyze file statistics
+ * const totalLines = Object.values(rendered.files)
+ *   .reduce((sum, file) => sum + file.lines, 0);
+ * const totalChars = Object.values(rendered.files)
+ *   .reduce((sum, file) => sum + file.characters, 0);
+ *
+ * console.log(`Generated ${Object.keys(rendered.artifacts).length} files`);
+ * console.log(`Total lines: ${totalLines}`);
+ * console.log(`Total characters: ${totalChars}`);
+ *
+ * // Check for large files
+ * const largeFiles = Object.entries(rendered.files)
+ *   .filter(([_, metadata]) => metadata.lines > 1000)
+ *   .map(([path, metadata]) => ({ path, lines: metadata.lines }));
+ *
+ * if (largeFiles.length > 0) {
+ *   console.log('Large files detected:', largeFiles);
+ * }
+ *
+ * // Access preview and mapping data
+ * console.log('Previews available:', Object.keys(rendered.previews));
+ * console.log('Mappings available:', Object.keys(rendered.mappings));
+ * ```
+ *
+ * @example Integration with CoreContext
+ * ```typescript
+ * // Typically used within CoreContext.toArtifacts()
+ * class CustomCoreContext extends CoreContext {
+ *   async renderWithPostProcessing(
+ *     files: Map<string, File | JsonFile>,
+ *     previews: Record<string, Record<string, Preview>>,
+ *     mappings: Record<string, Record<string, Mapping>>
+ *   ) {
+ *     const renderContext = new RenderContext({
+ *       files,
+ *       previews,
+ *       mappings,
+ *       prettierConfig: this.prettierConfig,
+ *       basePath: this.settings?.basePath,
+ *       stackTrail: this.stackTrail,
+ *       logger: this.logger,
+ *       captureCurrentResult: this.captureCurrentResult.bind(this)
+ *     });
+ *
+ *     const rendered = await renderContext.render();
+ *
+ *     // Post-process rendered files
+ *     const processedArtifacts: Record<string, string> = {};
+ *
+ *     for (const [path, content] of Object.entries(rendered.artifacts)) {
+ *       // Add file headers, license notices, etc.
+ *       const processedContent = this.addFileHeader(content, path);
+ *       processedArtifacts[path] = processedContent;
+ *     }
+ *
+ *     return {
+ *       ...rendered,
+ *       artifacts: processedArtifacts
+ *     };
+ *   }
+ * }
+ * ```
+ *
+ * @example Error handling during rendering
+ * ```typescript
+ * try {
+ *   const renderContext = new RenderContext({
+ *     files: generatedFiles,
+ *     previews: {},
+ *     mappings: {},
+ *     prettierConfig: prettierConfig,
+ *     basePath: './invalid-path', // This might cause issues
+ *     stackTrail: stack,
+ *     logger: logger,
+ *     captureCurrentResult: (result) => {
+ *       if (result === 'error') {
+ *         console.error('Render error detected');
+ *       }
+ *     }
+ *   });
+ *
+ *   const result = await renderContext.render();
+ *
+ *   // Check if any files failed to render
+ *   const failedFiles = Object.entries(result.files)
+ *     .filter(([path, metadata]) => metadata.lines === 0)
+ *     .map(([path]) => path);
+ *
+ *   if (failedFiles.length > 0) {
+ *     console.warn('Files with no content:', failedFiles);
+ *   }
+ *
+ * } catch (error) {
+ *   console.error('Render operation failed:', error);
+ *   // Sentry automatically captures the error
+ * }
+ * ```
+ */
 export declare class RenderContext {
     #private;
     files: Map<string, File | JsonFile>;

package/esm/context/RenderContext.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RenderContext.d.ts","sourceRoot":"","sources":["../../src/context/RenderContext.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAA;AAEpE,OAAO,KAAK,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAEjE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AACtD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAA;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAA;AAGrD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AACjD,OAAO,KAAK,KAAK,GAAG,MAAM,yCAAyC,CAAA;AACnE,OAAO,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAA;AACrC,OAAO,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAE3D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAElD,KAAK,eAAe,GAAG;IACrB,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,IAAI,GAAG,QAAQ,CAAC,CAAA;IACnC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;IACjD,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;IACjD,cAAc,CAAC,EAAE,kBAAkB,CAAA;IACnC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAA;IAC5B,UAAU,EAAE,UAAU,CAAA;IACtB,MAAM,EAAE,GAAG,CAAC,MAAM,CAAA;IAClB,oBAAoB,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,IAAI,CAAA;CACnD,CAAA;AAsBD,qBAAa,aAAa;;IACxB,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,IAAI,GAAG,QAAQ,CAAC,CAAA;IACnC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;IACjD,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;IAEjD,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAA;IAC5B,MAAM,EAAE,GAAG,CAAC,MAAM,CAAA;IAElB,oBAAoB,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,IAAI,CAAA;gBACtC,EACV,KAAK,EACL,QAAQ,EACR,QAAQ,EACR,cAAc,EACd,QAAQ,EACR,MAAM,EACN,UAAU,EACV,oBAAoB,EACrB,EAAE,eAAe;IAWZ,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,YAAY,EAAE,SAAS,CAAC,CAAC;IAiBhD,OAAO,IAAI,OAAO,CAAC,iBAAiB,CAAC;IAuC3C,KAAK,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC;IAIlD,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,QAAQ;IAU1C,IAAI,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,EAAE,QAAQ,GAAG,UAAU,GAAG,SAAS;CAO7D"}
+{"version":3,"file":"RenderContext.d.ts","sourceRoot":"","sources":["../../src/context/RenderContext.ts"],"names":[],"mappings":"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"}