@skmtc/core 0.0.807 → 0.0.809

package/script/oas/string/string-types.js

@@ -38,8 +38,34 @@ const v = __importStar(require("valibot"));
 /**
  * Valibot enum schema for valid OpenAPI string format values.
  *
- * Defines the standard string formats supported by OpenAPI v3,
- * including date/time formats, network formats, and encoding formats.
+ * This schema validates that string format values conform to the OpenAPI v3
+ * specification's standard format identifiers. It includes date/time formats,
+ * network address formats, and encoding formats that provide semantic meaning
+ * for string validation and UI generation.
+ *
+ * @example Validating string formats
+ * ```typescript
+ * import { stringFormat } from '@skmtc/core/oas/string';
+ * import * as v from 'valibot';
+ *
+ * const validFormat = v.parse(stringFormat, 'email'); // 'email'
+ * const invalidFormat = v.parse(stringFormat, 'invalid'); // Throws ValiError
+ * ```
+ *
+ * @example Using in schema validation
+ * ```typescript
+ * const schema = {
+ *   type: 'string',
+ *   format: 'email',
+ *   description: 'User email address'
+ * };
+ *
+ * // Validate the format field
+ * if (schema.format) {
+ *   const validatedFormat = v.parse(stringFormat, schema.format);
+ *   console.log(`Valid format: ${validatedFormat}`);
+ * }
+ * ```
  */
 exports.stringFormat = v.enum({
     'date-time': 'date-time',
@@ -60,8 +86,54 @@ exports.stringFormat = v.enum({
 /**
  * Valibot schema for validating OpenAPI string data objects.
  *
- * Validates string schema objects including length constraints,
- * pattern validation, format specifiers, and enumeration values.
+ * This comprehensive schema validates OpenAPI string schemas according to the
+ * OpenAPI v3 specification, including all standard properties like length
+ * constraints, pattern validation, format specifiers, enumeration values,
+ * and metadata fields. Used throughout the SKMTC pipeline for runtime
+ * validation of string schema definitions.
+ *
+ * @example Validating a basic string schema
+ * ```typescript
+ * import { oasStringData } from '@skmtc/core/oas/string';
+ * import * as v from 'valibot';
+ *
+ * const schema = {
+ *   type: 'string',
+ *   description: 'User name',
+ *   minLength: 1,
+ *   maxLength: 100,
+ *   pattern: '^[a-zA-Z\\s]+$'
+ * };
+ *
+ * const validated = v.parse(oasStringData, schema);
+ * console.log(validated.minLength); // 1
+ * ```
+ *
+ * @example Validating formatted strings
+ * ```typescript
+ * const emailSchema = {
+ *   type: 'string',
+ *   format: 'email',
+ *   title: 'Email Address',
+ *   example: 'user@example.com'
+ * };
+ *
+ * const result = v.parse(oasStringData, emailSchema);
+ * console.log(result.format); // 'email'
+ * ```
+ *
+ * @example Validating enumerated strings
+ * ```typescript
+ * const statusSchema = {
+ *   type: 'string',
+ *   enum: ['pending', 'approved', 'rejected'],
+ *   default: 'pending',
+ *   description: 'Application status'
+ * };
+ *
+ * const validated = v.parse(oasStringData, statusSchema);
+ * console.log(validated.enum); // ['pending', 'approved', 'rejected']
+ * ```
  */
 exports.oasStringData = v.object({
     type: v.literal('string'),

package/script/types/ModuleExport.d.ts

@@ -1,8 +1,138 @@
 import "../_dnt.polyfills.js";
 import * as v from 'valibot';
+/**
+ * Valibot schema for validating module export configuration objects.
+ *
+ * This schema validates module export structures used throughout the SKMTC
+ * code generation pipeline. Module exports define how generated code modules
+ * are exposed and imported, specifying both the export name and the file path
+ * where the export can be found.
+ *
+ * @example Validating a basic module export
+ * ```typescript
+ * import { moduleExport } from '@skmtc/core/types';
+ * import * as v from 'valibot';
+ *
+ * const config = {
+ *   exportName: 'UserApi',
+ *   exportPath: './generated/UserApi.ts'
+ * };
+ *
+ * const validated = v.parse(moduleExport, config);
+ * console.log(validated.exportName); // 'UserApi'
+ * ```
+ *
+ * @example Validating multiple exports
+ * ```typescript
+ * const exports = [
+ *   { exportName: 'createUser', exportPath: './api/users.ts' },
+ *   { exportName: 'updateUser', exportPath: './api/users.ts' },
+ *   { exportName: 'UserModel', exportPath: './models/User.ts' }
+ * ];
+ *
+ * exports.forEach(exp => {
+ *   const validated = v.parse(moduleExport, exp);
+ *   console.log(`Export: ${validated.exportName} from ${validated.exportPath}`);
+ * });
+ * ```
+ */
 export declare const moduleExport: v.GenericSchema<ModuleExport>;
+/**
+ * Configuration object for module exports in the SKMTC pipeline.
+ *
+ * This type defines the structure for describing how generated code modules
+ * should be exported and made available for import. It's used throughout
+ * the SKMTC system for organizing generated code, managing dependencies,
+ * and creating proper import/export relationships between generated files.
+ *
+ * ## Usage in SKMTC Pipeline
+ *
+ * This type is used by:
+ * - Code generators to define export configurations
+ * - File processors to organize generated modules
+ * - Import managers to resolve module dependencies
+ * - Build systems to understand code structure
+ *
+ * @example Basic module export definition
+ * ```typescript
+ * import type { ModuleExport } from '@skmtc/core/types';
+ *
+ * const apiExport: ModuleExport = {
+ *   exportName: 'UserApiClient',
+ *   exportPath: './generated/api/UserApiClient.ts'
+ * };
+ *
+ * console.log(`Import ${apiExport.exportName} from '${apiExport.exportPath}'`);
+ * // Import UserApiClient from './generated/api/UserApiClient.ts'
+ * ```
+ *
+ * @example Function export configuration
+ * ```typescript
+ * const functionExport: ModuleExport = {
+ *   exportName: 'validateUserData',
+ *   exportPath: './generated/validators/userValidation.ts'
+ * };
+ *
+ * // Used to generate: export { validateUserData } from './generated/validators/userValidation.ts'
+ * ```
+ *
+ * @example Type export configuration
+ * ```typescript
+ * const typeExport: ModuleExport = {
+ *   exportName: 'UserType',
+ *   exportPath: './generated/types/User.ts'
+ * };
+ *
+ * // Used to generate: export type { UserType } from './generated/types/User.ts'
+ * ```
+ *
+ * @example Multiple exports from same file
+ * ```typescript
+ * const userModuleExports: ModuleExport[] = [
+ *   {
+ *     exportName: 'User',
+ *     exportPath: './generated/models/User.ts'
+ *   },
+ *   {
+ *     exportName: 'UserValidator',
+ *     exportPath: './generated/models/User.ts'
+ *   },
+ *   {
+ *     exportName: 'createUser',
+ *     exportPath: './generated/models/User.ts'
+ *   }
+ * ];
+ *
+ * // All exports reference the same file but different symbols
+ * ```
+ *
+ * @example Integration with build systems
+ * ```typescript
+ * class ModuleRegistry {
+ *   private exports: ModuleExport[] = [];
+ *
+ *   addExport(moduleExport: ModuleExport) {
+ *     this.exports.push(moduleExport);
+ *   }
+ *
+ *   generateIndexFile(): string {
+ *     return this.exports
+ *       .map(exp => `export { ${exp.exportName} } from '${exp.exportPath}';`)
+ *       .join('\n');
+ *   }
+ * }
+ *
+ * const registry = new ModuleRegistry();
+ * registry.addExport({
+ *   exportName: 'ApiClient',
+ *   exportPath: './api/client.ts'
+ * });
+ * ```
+ */
 export type ModuleExport = {
+    /** The name of the symbol being exported (function, class, type, etc.) */
     exportName: string;
+    /** The file path where the export can be found */
     exportPath: string;
 };
 //# sourceMappingURL=ModuleExport.d.ts.map

package/script/types/ModuleExport.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ModuleExport.d.ts","sourceRoot":"","sources":["../../src/types/ModuleExport.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAC9B,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAE5B,eAAO,MAAM,YAAY,EAAE,CAAC,CAAC,aAAa,CAAC,YAAY,CAGrD,CAAA;AAEF,MAAM,MAAM,YAAY,GAAG;IACzB,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,EAAE,MAAM,CAAA;CACnB,CAAA"}
+{"version":3,"file":"ModuleExport.d.ts","sourceRoot":"","sources":["../../src/types/ModuleExport.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAC9B,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAE5B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,eAAO,MAAM,YAAY,EAAE,CAAC,CAAC,aAAa,CAAC,YAAY,CAGrD,CAAA;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2FG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,0EAA0E;IAC1E,UAAU,EAAE,MAAM,CAAA;IAClB,kDAAkD;IAClD,UAAU,EAAE,MAAM,CAAA;CACnB,CAAA"}

package/script/types/ModuleExport.js

@@ -36,6 +36,42 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.moduleExport = void 0;
 require("../_dnt.polyfills.js");
 const v = __importStar(require("valibot"));
+/**
+ * Valibot schema for validating module export configuration objects.
+ *
+ * This schema validates module export structures used throughout the SKMTC
+ * code generation pipeline. Module exports define how generated code modules
+ * are exposed and imported, specifying both the export name and the file path
+ * where the export can be found.
+ *
+ * @example Validating a basic module export
+ * ```typescript
+ * import { moduleExport } from '@skmtc/core/types';
+ * import * as v from 'valibot';
+ *
+ * const config = {
+ *   exportName: 'UserApi',
+ *   exportPath: './generated/UserApi.ts'
+ * };
+ *
+ * const validated = v.parse(moduleExport, config);
+ * console.log(validated.exportName); // 'UserApi'
+ * ```
+ *
+ * @example Validating multiple exports
+ * ```typescript
+ * const exports = [
+ *   { exportName: 'createUser', exportPath: './api/users.ts' },
+ *   { exportName: 'updateUser', exportPath: './api/users.ts' },
+ *   { exportName: 'UserModel', exportPath: './models/User.ts' }
+ * ];
+ *
+ * exports.forEach(exp => {
+ *   const validated = v.parse(moduleExport, exp);
+ *   console.log(`Export: ${validated.exportName} from ${validated.exportPath}`);
+ * });
+ * ```
+ */
 exports.moduleExport = v.object({
     exportName: v.string(),
     exportPath: v.string()

package/script/types/PrettierConfig.d.ts

@@ -1,3 +1,77 @@
+/**
+ * @fileoverview Prettier Configuration System for SKMTC Core
+ *
+ * This module provides comprehensive type definitions and validation schemas for
+ * Prettier code formatting configuration within the SKMTC code generation pipeline.
+ * It ensures that generated code is properly formatted according to specified
+ * formatting rules and style guidelines.
+ *
+ * The Prettier configuration system supports all standard Prettier options,
+ * enabling fine-tuned control over code formatting for different output targets
+ * and project requirements.
+ *
+ * ## Key Features
+ *
+ * - **Complete Option Coverage**: All Prettier configuration options supported
+ * - **Type Safety**: Full TypeScript typing and Valibot validation
+ * - **Flexible Configuration**: Optional settings with sensible defaults
+ * - **Multi-Language Support**: Formatting options for JavaScript, TypeScript, JSX, HTML, and more
+ * - **Integration Ready**: Direct integration with the SKMTC rendering pipeline
+ *
+ * @example Basic Prettier configuration
+ * ```typescript
+ * import type { PrettierConfigType } from '@skmtc/core/PrettierConfig';
+ *
+ * const config: PrettierConfigType = {
+ *   printWidth: 100,
+ *   tabWidth: 2,
+ *   useTabs: false,
+ *   semi: true,
+ *   singleQuote: true,
+ *   trailingComma: 'es5'
+ * };
+ * ```
+ *
+ * @example TypeScript and JSX formatting
+ * ```typescript
+ * import type { PrettierConfigType } from '@skmtc/core/PrettierConfig';
+ *
+ * const tsConfig: PrettierConfigType = {
+ *   printWidth: 120,
+ *   tabWidth: 2,
+ *   semi: true,
+ *   singleQuote: true,
+ *   jsxSingleQuote: true,
+ *   bracketSameLine: false,
+ *   arrowParens: 'avoid'
+ * };
+ * ```
+ *
+ * @example Validation usage
+ * ```typescript
+ * import { prettierConfigType, PrettierConfigType } from '@skmtc/core/PrettierConfig';
+ * import * as v from 'valibot';
+ *
+ * function validatePrettierConfig(config: unknown): PrettierConfigType {
+ *   return v.parse(prettierConfigType, config);
+ * }
+ *
+ * const userConfig = {
+ *   printWidth: 80,
+ *   singleQuote: true,
+ *   invalidOption: 'test' // This would cause validation error
+ * };
+ *
+ * try {
+ *   const validConfig = validatePrettierConfig(userConfig);
+ *   console.log('Valid configuration:', validConfig);
+ * } catch (error) {
+ *   console.error('Invalid Prettier configuration:', error);
+ * }
+ * ```
+ *
+ * @module PrettierConfig
+ */
 import "../_dnt.polyfills.js";
 import * as v from 'valibot';
 export type PrettierConfigType = {

package/script/types/PrettierConfig.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PrettierConfig.d.ts","sourceRoot":"","sources":["../../src/types/PrettierConfig.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAC9B,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAE5B,MAAM,MAAM,kBAAkB,GAAG;IAC/B,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,UAAU,CAAC,EAAE,WAAW,GAAG,YAAY,GAAG,UAAU,CAAA;IACpD,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB,aAAa,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,KAAK,CAAA;IACtC,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB,kBAAkB,CAAC,EAAE,OAAO,CAAA;IAC5B,WAAW,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAA;IAChC,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,SAAS,CAAC,EAAE,QAAQ,GAAG,OAAO,GAAG,UAAU,CAAA;IAC3C,yBAAyB,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,QAAQ,CAAA;IACvD,uBAAuB,CAAC,EAAE,OAAO,CAAA;IACjC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAAA;IACzC,0BAA0B,CAAC,EAAE,MAAM,GAAG,KAAK,CAAA;IAC3C,sBAAsB,CAAC,EAAE,OAAO,CAAA;CACjC,CAAA;AAED,eAAO,MAAM,kBAAkB,EAAE,CAAC,CAAC,aAAa,CAAC,kBAAkB,CA6BjE,CAAA"}
+{"version":3,"file":"PrettierConfig.d.ts","sourceRoot":"","sources":["../../src/types/PrettierConfig.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyEG;AACH,OAAO,sBAAsB,CAAC;AAG9B,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAE5B,MAAM,MAAM,kBAAkB,GAAG;IAC/B,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,UAAU,CAAC,EAAE,WAAW,GAAG,YAAY,GAAG,UAAU,CAAA;IACpD,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB,aAAa,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,KAAK,CAAA;IACtC,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB,kBAAkB,CAAC,EAAE,OAAO,CAAA;IAC5B,WAAW,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAA;IAChC,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,SAAS,CAAC,EAAE,QAAQ,GAAG,OAAO,GAAG,UAAU,CAAA;IAC3C,yBAAyB,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,QAAQ,CAAA;IACvD,uBAAuB,CAAC,EAAE,OAAO,CAAA;IACjC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAAA;IACzC,0BAA0B,CAAC,EAAE,MAAM,GAAG,KAAK,CAAA;IAC3C,sBAAsB,CAAC,EAAE,OAAO,CAAA;CACjC,CAAA;AAED,eAAO,MAAM,kBAAkB,EAAE,CAAC,CAAC,aAAa,CAAC,kBAAkB,CA6BjE,CAAA"}

package/script/types/PrettierConfig.js

@@ -34,6 +34,80 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.prettierConfigType = void 0;
+/**
+ * @fileoverview Prettier Configuration System for SKMTC Core
+ *
+ * This module provides comprehensive type definitions and validation schemas for
+ * Prettier code formatting configuration within the SKMTC code generation pipeline.
+ * It ensures that generated code is properly formatted according to specified
+ * formatting rules and style guidelines.
+ *
+ * The Prettier configuration system supports all standard Prettier options,
+ * enabling fine-tuned control over code formatting for different output targets
+ * and project requirements.
+ *
+ * ## Key Features
+ *
+ * - **Complete Option Coverage**: All Prettier configuration options supported
+ * - **Type Safety**: Full TypeScript typing and Valibot validation
+ * - **Flexible Configuration**: Optional settings with sensible defaults
+ * - **Multi-Language Support**: Formatting options for JavaScript, TypeScript, JSX, HTML, and more
+ * - **Integration Ready**: Direct integration with the SKMTC rendering pipeline
+ *
+ * @example Basic Prettier configuration
+ * ```typescript
+ * import type { PrettierConfigType } from '@skmtc/core/PrettierConfig';
+ *
+ * const config: PrettierConfigType = {
+ *   printWidth: 100,
+ *   tabWidth: 2,
+ *   useTabs: false,
+ *   semi: true,
+ *   singleQuote: true,
+ *   trailingComma: 'es5'
+ * };
+ * ```
+ *
+ * @example TypeScript and JSX formatting
+ * ```typescript
+ * import type { PrettierConfigType } from '@skmtc/core/PrettierConfig';
+ *
+ * const tsConfig: PrettierConfigType = {
+ *   printWidth: 120,
+ *   tabWidth: 2,
+ *   semi: true,
+ *   singleQuote: true,
+ *   jsxSingleQuote: true,
+ *   bracketSameLine: false,
+ *   arrowParens: 'avoid'
+ * };
+ * ```
+ *
+ * @example Validation usage
+ * ```typescript
+ * import { prettierConfigType, PrettierConfigType } from '@skmtc/core/PrettierConfig';
+ * import * as v from 'valibot';
+ *
+ * function validatePrettierConfig(config: unknown): PrettierConfigType {
+ *   return v.parse(prettierConfigType, config);
+ * }
+ *
+ * const userConfig = {
+ *   printWidth: 80,
+ *   singleQuote: true,
+ *   invalidOption: 'test' // This would cause validation error
+ * };
+ *
+ * try {
+ *   const validConfig = validatePrettierConfig(userConfig);
+ *   console.log('Valid configuration:', validConfig);
+ * } catch (error) {
+ *   console.error('Invalid Prettier configuration:', error);
+ * }
+ * ```
+ *
+ * @module PrettierConfig
+ */
 require("../_dnt.polyfills.js");
 const v = __importStar(require("valibot"));
 exports.prettierConfigType = v.object({

package/script/types/Results.d.ts

@@ -1,3 +1,100 @@
+/**
+ * @fileoverview Results and Status Tracking System for SKMTC Core
+ *
+ * This module provides comprehensive result tracking and status management for
+ * the SKMTC code generation pipeline. It includes hierarchical result structures,
+ * type-safe status definitions, and validation schemas for tracking the outcomes
+ * of parsing, generation, and rendering operations.
+ *
+ * The results system enables detailed reporting and error handling throughout
+ * the pipeline, supporting nested result structures for complex operations
+ * and comprehensive status categorization.
+ *
+ * ## Key Features
+ *
+ * - **Hierarchical Results**: Nested result structures for complex operations
+ * - **Status Categories**: Complete coverage of operation outcomes (success, warning, error, etc.)
+ * - **Type Safety**: Full TypeScript typing with Valibot validation
+ * - **Recursive Support**: Lazy evaluation for deeply nested result structures
+ * - **Pipeline Integration**: Direct integration with SKMTC processing contexts
+ *
+ * @example Basic result tracking
+ * ```typescript
+ * import type { ResultType, ResultsItem } from '@skmtc/core/Results';
+ *
+ * const operationResult: ResultType = 'success';
+ * const errorResult: ResultType = 'error';
+ *
+ * const results: ResultsItem = {
+ *   parsing: 'success',
+ *   generation: 'warning',
+ *   rendering: 'success'
+ * };
+ * ```
+ *
+ * @example Hierarchical result structures
+ * ```typescript
+ * import type { ResultsItem } from '@skmtc/core/Results';
+ *
+ * const complexResults: ResultsItem = {
+ *   parsing: {
+ *     schemas: 'success',
+ *     operations: {
+ *       userApi: 'success',
+ *       productApi: 'warning',
+ *       orderApi: 'error'
+ *     }
+ *   },
+ *   generation: [
+ *     { models: 'success' },
+ *     { services: 'warning' },
+ *     null // Skipped operation
+ *   ]
+ * };
+ * ```
+ *
+ * @example Result validation
+ * ```typescript
+ * import { resultsItem, resultType, ResultsItem } from '@skmtc/core/Results';
+ * import * as v from 'valibot';
+ *
+ * function validateResults(data: unknown): ResultsItem {
+ *   return v.parse(resultsItem, data);
+ * }
+ *
+ * function validateResultType(status: unknown): ResultType {
+ *   return v.parse(resultType, status);
+ * }
+ *
+ * // Usage
+ * const results = validateResults({
+ *   operation: 'success',
+ *   nested: {
+ *     subOperation: 'warning'
+ *   }
+ * });
+ * ```
+ *
+ * @example Error filtering
+ * ```typescript
+ * import type { ResultType, WarningError } from '@skmtc/core/Results';
+ *
+ * function hasIssues(result: ResultType): result is WarningError {
+ *   return result === 'warning' || result === 'error';
+ * }
+ *
+ * function processResults(results: Record<string, ResultType>) {
+ *   const issues = Object.entries(results)
+ *     .filter(([, status]) => hasIssues(status));
+ *
+ *   if (issues.length > 0) {
+ *     console.log('Operations with issues:', issues);
+ *   }
+ * }
+ * ```
+ *
+ * @module Results
+ */
 import "../_dnt.polyfills.js";
 import * as v from 'valibot';
 /**

package/script/types/Results.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Results.d.ts","sourceRoot":"","sources":["../../src/types/Results.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAC9B,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAE5B;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,GAAG,cAAc,CAAA;AAErF;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,OAAO,CAAA;AAE9C;;;;;GAKG;AACH,eAAO,MAAM,UAAU,EAAE,CAAC,CAAC,aAAa,CAAC,UAAU,CAMjD,CAAA;AAEF;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B,+DAA+D;IAC/D,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,WAAW,GAAG,KAAK,CAAC,WAAW,GAAG,IAAI,CAAC,CAAA;CACpE;AAED;;;;;GAKG;AACH,eAAO,MAAM,WAAW,EAAE,CAAC,CAAC,aAAa,CAAC,WAAW,CAGpD,CAAA"}
+{"version":3,"file":"Results.d.ts","sourceRoot":"","sources":["../../src/types/Results.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgGG;AACH,OAAO,sBAAsB,CAAC;AAG9B,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAE5B;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,GAAG,cAAc,CAAA;AAErF;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,OAAO,CAAA;AAE9C;;;;;GAKG;AACH,eAAO,MAAM,UAAU,EAAE,CAAC,CAAC,aAAa,CAAC,UAAU,CAMjD,CAAA;AAEF;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B,+DAA+D;IAC/D,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,WAAW,GAAG,KAAK,CAAC,WAAW,GAAG,IAAI,CAAC,CAAA;CACpE;AAED;;;;;GAKG;AACH,eAAO,MAAM,WAAW,EAAE,CAAC,CAAC,aAAa,CAAC,WAAW,CAGpD,CAAA"}

package/script/types/Results.js

@@ -34,6 +34,103 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resultsItem = exports.resultType = void 0;
+/**
+ * @fileoverview Results and Status Tracking System for SKMTC Core
+ *
+ * This module provides comprehensive result tracking and status management for
+ * the SKMTC code generation pipeline. It includes hierarchical result structures,
+ * type-safe status definitions, and validation schemas for tracking the outcomes
+ * of parsing, generation, and rendering operations.
+ *
+ * The results system enables detailed reporting and error handling throughout
+ * the pipeline, supporting nested result structures for complex operations
+ * and comprehensive status categorization.
+ *
+ * ## Key Features
+ *
+ * - **Hierarchical Results**: Nested result structures for complex operations
+ * - **Status Categories**: Complete coverage of operation outcomes (success, warning, error, etc.)
+ * - **Type Safety**: Full TypeScript typing with Valibot validation
+ * - **Recursive Support**: Lazy evaluation for deeply nested result structures
+ * - **Pipeline Integration**: Direct integration with SKMTC processing contexts
+ *
+ * @example Basic result tracking
+ * ```typescript
+ * import type { ResultType, ResultsItem } from '@skmtc/core/Results';
+ *
+ * const operationResult: ResultType = 'success';
+ * const errorResult: ResultType = 'error';
+ *
+ * const results: ResultsItem = {
+ *   parsing: 'success',
+ *   generation: 'warning',
+ *   rendering: 'success'
+ * };
+ * ```
+ *
+ * @example Hierarchical result structures
+ * ```typescript
+ * import type { ResultsItem } from '@skmtc/core/Results';
+ *
+ * const complexResults: ResultsItem = {
+ *   parsing: {
+ *     schemas: 'success',
+ *     operations: {
+ *       userApi: 'success',
+ *       productApi: 'warning',
+ *       orderApi: 'error'
+ *     }
+ *   },
+ *   generation: [
+ *     { models: 'success' },
+ *     { services: 'warning' },
+ *     null // Skipped operation
+ *   ]
+ * };
+ * ```
+ *
+ * @example Result validation
+ * ```typescript
+ * import { resultsItem, resultType, ResultsItem } from '@skmtc/core/Results';
+ * import * as v from 'valibot';
+ *
+ * function validateResults(data: unknown): ResultsItem {
+ *   return v.parse(resultsItem, data);
+ * }
+ *
+ * function validateResultType(status: unknown): ResultType {
+ *   return v.parse(resultType, status);
+ * }
+ *
+ * // Usage
+ * const results = validateResults({
+ *   operation: 'success',
+ *   nested: {
+ *     subOperation: 'warning'
+ *   }
+ * });
+ * ```
+ *
+ * @example Error filtering
+ * ```typescript
+ * import type { ResultType, WarningError } from '@skmtc/core/Results';
+ *
+ * function hasIssues(result: ResultType): result is WarningError {
+ *   return result === 'warning' || result === 'error';
+ * }
+ *
+ * function processResults(results: Record<string, ResultType>) {
+ *   const issues = Object.entries(results)
+ *     .filter(([, status]) => hasIssues(status));
+ *
+ *   if (issues.length > 0) {
+ *     console.log('Operations with issues:', issues);
+ *   }
+ * }
+ * ```
+ *
+ * @module Results
+ */
 require("../_dnt.polyfills.js");
 const v = __importStar(require("valibot"));
 /**