@skmtc/core 0.0.806 → 0.0.808

package/script/types/RefName.js

@@ -1,3 +1,73 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * @fileoverview Reference Name System for SKMTC Core
+ *
+ * This module provides a type-safe reference name system for identifying
+ * OpenAPI schema components throughout the SKMTC pipeline. Reference names
+ * are branded types that ensure schema identifiers are handled safely and
+ * prevent accidental mixing with regular strings.
+ *
+ * The reference name system is crucial for maintaining type safety when
+ * working with OpenAPI component references, schema lookups, and cross-references
+ * between different parts of the generated code.
+ *
+ * ## Key Features
+ *
+ * - **Type Safety**: Branded types prevent string confusion and improve code reliability
+ * - **Schema Integration**: Direct mapping to OpenAPI components.schemas keys
+ * - **Reference Tracking**: Safe handling of schema references throughout generation
+ * - **IDE Support**: Enhanced IntelliSense and error detection in development
+ * - **Validation**: Compile-time validation of schema reference usage
+ *
+ * @example Basic reference name usage
+ * ```typescript
+ * import type { RefName } from '@skmtc/core/RefName';
+ *
+ * // Create a reference name (typically done by the parser)
+ * const userRef: RefName = 'User' as RefName;
+ * const productRef: RefName = 'Product' as RefName;
+ *
+ * // TypeScript prevents mixing with regular strings
+ * const regularString = 'User';
+ * // const invalid: RefName = regularString; // Type error!
+ * ```
+ *
+ * @example Using reference names in generators
+ * ```typescript
+ * import type { RefName } from '@skmtc/core/RefName';
+ *
+ * function generateModelImport(refName: RefName): string {
+ *   return `import type { ${refName} } from './models/${refName}';`;
+ * }
+ *
+ * function generateModelReference(refName: RefName): string {
+ *   return `#/components/schemas/${refName}`;
+ * }
+ *
+ * // Usage with type safety
+ * const userRef: RefName = 'User' as RefName;
+ * const importStatement = generateModelImport(userRef);
+ * const schemaRef = generateModelReference(userRef);
+ * ```
+ *
+ * @example Reference name validation
+ * ```typescript
+ * import type { RefName } from '@skmtc/core/RefName';
+ *
+ * function isValidRefName(value: string): value is RefName {
+ *   // Validate that the string is a valid schema reference name
+ *   return /^[A-Za-z][A-Za-z0-9_]*$/.test(value) && value.length > 0;
+ * }
+ *
+ * function safeCreateRefName(value: string): RefName | null {
+ *   if (isValidRefName(value)) {
+ *     return value as RefName;
+ *   }
+ *   return null;
+ * }
+ * ```
+ *
+ * @module RefName
+ */
 require("../_dnt.polyfills.js");

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"));
 /**