@skmtc/core 0.0.806 → 0.0.807

package/esm/types/Method.js

@@ -1,3 +1,70 @@
+/**
+ * @fileoverview HTTP Method System for SKMTC Core
+ *
+ * This module provides comprehensive HTTP method definitions and utilities for
+ * handling OpenAPI operations. It includes type-safe method definitions,
+ * validation utilities, and constants for all HTTP methods supported by
+ * the OpenAPI v3 specification.
+ *
+ * The module ensures type safety when working with HTTP methods throughout
+ * the SKMTC pipeline and provides utilities for method validation and processing.
+ *
+ * ## Key Features
+ *
+ * - **Complete Method Support**: All HTTP methods from OpenAPI v3 specification
+ * - **Type Safety**: Branded types and type guards for method handling
+ * - **Validation**: Runtime validation with Valibot integration
+ * - **Case Handling**: Proper case normalization for method strings
+ * - **Specification Compliance**: Full adherence to OpenAPI v3 method definitions
+ *
+ * @example Working with HTTP methods
+ * ```typescript
+ * import { Method, isMethod, methodValues } from '@skmtc/core/Method';
+ *
+ * // Type-safe method handling
+ * const method: Method = 'GET';
+ *
+ * // Validate unknown method strings
+ * const userInput = 'post';
+ * if (isMethod(userInput)) {
+ *   console.log(`Valid method: ${userInput}`); // TypeScript knows it's a Method
+ * }
+ *
+ * // List all supported methods
+ * console.log('Supported methods:', methodValues);
+ * ```
+ *
+ * @example Method validation in generators
+ * ```typescript
+ * import { isMethod, Method } from '@skmtc/core/Method';
+ *
+ * function processOperation(path: string, method: string, operation: any) {
+ *   if (!isMethod(method)) {
+ *     throw new Error(`Unsupported HTTP method: ${method}`);
+ *   }
+ *
+ *   // TypeScript now knows method is of type Method
+ *   return generateOperationCode(path, method, operation);
+ * }
+ * ```
+ *
+ * @example Case-insensitive method handling
+ * ```typescript
+ * import { normalizeMethod, isMethod } from '@skmtc/core/Method';
+ *
+ * function handleMethodString(methodStr: string) {
+ *   const normalized = methodStr.toLowerCase();
+ *
+ *   if (isMethod(normalized)) {
+ *     return processValidMethod(normalized);
+ *   } else {
+ *     throw new Error(`Invalid method: ${methodStr}`);
+ *   }
+ * }
+ * ```
+ *
+ * @module Method
+ */
 import "../_dnt.polyfills.js";
 import * as v from 'valibot';
 /**
@@ -5,6 +72,7 @@ import * as v from 'valibot';
  *
  * This constant array includes all HTTP methods that can be used
  * in OpenAPI path operations, as defined by the OpenAPI specification.
+ * All methods are in lowercase to match OpenAPI conventions.
  */
 export const methodValues = [
     'get',

package/esm/types/Preview.d.ts

@@ -1,3 +1,78 @@
+/**
+ * @fileoverview Preview and Mapping System for SKMTC Core
+ *
+ * This module provides comprehensive types and utilities for creating preview
+ * interfaces and mapping configurations for generated code. The preview system
+ * enables interactive demonstrations of generated APIs, forms, tables, and
+ * other UI components within development tools and documentation.
+ *
+ * The mapping system provides metadata about how OpenAPI operations and models
+ * translate to generated code, enabling rich tooling experiences and
+ * reverse-engineering capabilities.
+ *
+ * ## Key Features
+ *
+ * - **Interactive Previews**: Rich preview interfaces for generated components
+ * - **Source Mapping**: Traceability from generated code back to OpenAPI sources
+ * - **UI Grouping**: Organized grouping of related UI components (forms, tables, inputs)
+ * - **Generator Integration**: Deep integration with the generator pipeline
+ * - **Type Safety**: Comprehensive validation and type safety throughout
+ *
+ * @example Creating operation previews
+ * ```typescript
+ * import type { PreviewModule, OperationSource } from '@skmtc/core/Preview';
+ *
+ * const operationSource: OperationSource = {
+ *   type: 'operation',
+ *   generatorId: 'react-forms',
+ *   operationPath: '/users',
+ *   operationMethod: 'POST'
+ * };
+ *
+ * const preview: PreviewModule = {
+ *   title: 'Create User Form',
+ *   description: 'Interactive form for creating new users',
+ *   group: 'forms',
+ *   source: operationSource,
+ *   moduleName: 'CreateUserForm',
+ *   exportName: 'default'
+ * };
+ * ```
+ *
+ * @example Creating model previews
+ * ```typescript
+ * import type { PreviewModule, ModelSource } from '@skmtc/core/Preview';
+ *
+ * const modelSource: ModelSource = {
+ *   type: 'model',
+ *   generatorId: 'typescript-types',
+ *   refName: 'User'
+ * };
+ *
+ * const preview: PreviewModule = {
+ *   title: 'User Type Definition',
+ *   description: 'TypeScript interface for User model',
+ *   group: 'tables',
+ *   source: modelSource,
+ *   moduleName: 'UserTypes',
+ *   exportName: 'User'
+ * };
+ * ```
+ *
+ * @example Working with mappings
+ * ```typescript
+ * import type { MappingModule } from '@skmtc/core/Preview';
+ *
+ * const mapping: MappingModule = {
+ *   source: operationSource,
+ *   moduleName: 'UserApi',
+ *   exportName: 'createUser',
+ *   generatedPath: './src/generated/UserApi.ts'
+ * };
+ * ```
+ *
+ * @module Preview
+ */
 import "../_dnt.polyfills.js";
 import { type Method } from './Method.js';
 import * as v from 'valibot';

package/esm/types/Preview.d.ts.map

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

package/esm/types/Preview.js

@@ -1,3 +1,78 @@
+/**
+ * @fileoverview Preview and Mapping System for SKMTC Core
+ *
+ * This module provides comprehensive types and utilities for creating preview
+ * interfaces and mapping configurations for generated code. The preview system
+ * enables interactive demonstrations of generated APIs, forms, tables, and
+ * other UI components within development tools and documentation.
+ *
+ * The mapping system provides metadata about how OpenAPI operations and models
+ * translate to generated code, enabling rich tooling experiences and
+ * reverse-engineering capabilities.
+ *
+ * ## Key Features
+ *
+ * - **Interactive Previews**: Rich preview interfaces for generated components
+ * - **Source Mapping**: Traceability from generated code back to OpenAPI sources
+ * - **UI Grouping**: Organized grouping of related UI components (forms, tables, inputs)
+ * - **Generator Integration**: Deep integration with the generator pipeline
+ * - **Type Safety**: Comprehensive validation and type safety throughout
+ *
+ * @example Creating operation previews
+ * ```typescript
+ * import type { PreviewModule, OperationSource } from '@skmtc/core/Preview';
+ *
+ * const operationSource: OperationSource = {
+ *   type: 'operation',
+ *   generatorId: 'react-forms',
+ *   operationPath: '/users',
+ *   operationMethod: 'POST'
+ * };
+ *
+ * const preview: PreviewModule = {
+ *   title: 'Create User Form',
+ *   description: 'Interactive form for creating new users',
+ *   group: 'forms',
+ *   source: operationSource,
+ *   moduleName: 'CreateUserForm',
+ *   exportName: 'default'
+ * };
+ * ```
+ *
+ * @example Creating model previews
+ * ```typescript
+ * import type { PreviewModule, ModelSource } from '@skmtc/core/Preview';
+ *
+ * const modelSource: ModelSource = {
+ *   type: 'model',
+ *   generatorId: 'typescript-types',
+ *   refName: 'User'
+ * };
+ *
+ * const preview: PreviewModule = {
+ *   title: 'User Type Definition',
+ *   description: 'TypeScript interface for User model',
+ *   group: 'tables',
+ *   source: modelSource,
+ *   moduleName: 'UserTypes',
+ *   exportName: 'User'
+ * };
+ * ```
+ *
+ * @example Working with mappings
+ * ```typescript
+ * import type { MappingModule } from '@skmtc/core/Preview';
+ *
+ * const mapping: MappingModule = {
+ *   source: operationSource,
+ *   moduleName: 'UserApi',
+ *   exportName: 'createUser',
+ *   generatedPath: './src/generated/UserApi.ts'
+ * };
+ * ```
+ *
+ * @module Preview
+ */
 import "../_dnt.polyfills.js";
 import { method } from './Method.js';
 import * as v from 'valibot';

package/esm/types/RefName.d.ts

@@ -1,3 +1,73 @@
+/**
+ * @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
+ */
 import "../_dnt.polyfills.js";
 import type { Brand } from './Brand.js';
 /**

package/esm/types/RefName.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RefName.d.ts","sourceRoot":"","sources":["../../src/types/RefName.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAEvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AACH,MAAM,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,EAAE,SAAS,CAAC,CAAA"}
+{"version":3,"file":"RefName.d.ts","sourceRoot":"","sources":["../../src/types/RefName.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqEG;AACH,OAAO,sBAAsB,CAAC;AAG9B,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAEvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AACH,MAAM,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,EAAE,SAAS,CAAC,CAAA"}

package/esm/types/RefName.js

@@ -1 +1,71 @@
+/**
+ * @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
+ */
 import "../_dnt.polyfills.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skmtc/core",
-  "version": "0.0.806",
+  "version": "0.0.807",
   "repository": {
     "type": "git",
     "url": "https://github.com/skmtc/skmtc.git"

package/script/helpers/toResolvedArtifactPath.d.ts

@@ -1,6 +1,70 @@
+/**
+ * @fileoverview Artifact Path Resolution Utilities for SKMTC Core
+ *
+ * This module provides utilities for resolving file paths for generated artifacts
+ * within the SKMTC code generation pipeline. It handles the complexities of path
+ * resolution, ensuring that generated files are placed in the correct locations
+ * relative to base directories and project structures.
+ *
+ * The path resolution system supports both absolute and relative paths,
+ * cross-platform compatibility, and proper handling of nested directory
+ * structures for organized code generation output.
+ *
+ * ## Key Features
+ *
+ * - **Cross-Platform Compatibility**: Works correctly on Windows, macOS, and Linux
+ * - **Relative Path Resolution**: Proper handling of relative paths with base directories
+ * - **Absolute Path Support**: Direct support for absolute destination paths
+ * - **Directory Creation**: Safe directory creation for nested path structures
+ * - **Path Normalization**: Consistent path formatting across different systems
+ *
+ * @example Basic path resolution
+ * ```typescript
+ * import { toResolvedArtifactPath } from '@skmtc/core/toResolvedArtifactPath';
+ *
+ * // Resolve relative path with base directory
+ * const resolvedPath = toResolvedArtifactPath({
+ *   basePath: '/project/src',
+ *   destinationPath: './generated/UserApi.ts'
+ * });
+ *
+ * console.log(resolvedPath); // '/project/src/generated/UserApi.ts'
+ * ```
+ *
+ * @example Absolute path handling
+ * ```typescript
+ * import { toResolvedArtifactPath } from '@skmtc/core/toResolvedArtifactPath';
+ *
+ * // Absolute paths are returned as-is
+ * const absolutePath = toResolvedArtifactPath({
+ *   basePath: '/project/src',
+ *   destinationPath: '/absolute/path/to/UserApi.ts'
+ * });
+ *
+ * console.log(absolutePath); // '/absolute/path/to/UserApi.ts'
+ * ```
+ *
+ * @example Working without base path
+ * ```typescript
+ * import { toResolvedArtifactPath } from '@skmtc/core/toResolvedArtifactPath';
+ *
+ * // When basePath is undefined, returns the destination path
+ * const path = toResolvedArtifactPath({
+ *   basePath: undefined,
+ *   destinationPath: './UserApi.ts'
+ * });
+ *
+ * console.log(path); // './UserApi.ts'
+ * ```
+ *
+ * @module toResolvedArtifactPath
+ */
 import "../_dnt.polyfills.js";
 /**
  * Arguments for resolving artifact file paths.
+ *
+ * Defines the input parameters needed to resolve a destination path
+ * relative to an optional base directory.
  */
 type ToResolvedArtifactPathArgs = {
     /** The base directory path for resolving relative paths */

package/script/helpers/toResolvedArtifactPath.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"toResolvedArtifactPath.d.ts","sourceRoot":"","sources":["../../src/helpers/toResolvedArtifactPath.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAG9B;;GAEG;AACH,KAAK,0BAA0B,GAAG;IAChC,2DAA2D;IAC3D,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAA;IAC5B,iDAAiD;IACjD,eAAe,EAAE,MAAM,CAAA;CACxB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2IG;AACH,eAAO,MAAM,sBAAsB,GAAI,+BAGpC,0BAA0B,KAAG,MAE/B,CAAA"}
+{"version":3,"file":"toResolvedArtifactPath.d.ts","sourceRoot":"","sources":["../../src/helpers/toResolvedArtifactPath.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AACH,OAAO,sBAAsB,CAAC;AAK9B;;;;;GAKG;AACH,KAAK,0BAA0B,GAAG;IAChC,2DAA2D;IAC3D,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAA;IAC5B,iDAAiD;IACjD,eAAe,EAAE,MAAM,CAAA;CACxB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2IG;AACH,eAAO,MAAM,sBAAsB,GAAI,+BAGpC,0BAA0B,KAAG,MAE/B,CAAA"}

package/script/helpers/toResolvedArtifactPath.js

@@ -1,6 +1,67 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.toResolvedArtifactPath = void 0;
+/**
+ * @fileoverview Artifact Path Resolution Utilities for SKMTC Core
+ *
+ * This module provides utilities for resolving file paths for generated artifacts
+ * within the SKMTC code generation pipeline. It handles the complexities of path
+ * resolution, ensuring that generated files are placed in the correct locations
+ * relative to base directories and project structures.
+ *
+ * The path resolution system supports both absolute and relative paths,
+ * cross-platform compatibility, and proper handling of nested directory
+ * structures for organized code generation output.
+ *
+ * ## Key Features
+ *
+ * - **Cross-Platform Compatibility**: Works correctly on Windows, macOS, and Linux
+ * - **Relative Path Resolution**: Proper handling of relative paths with base directories
+ * - **Absolute Path Support**: Direct support for absolute destination paths
+ * - **Directory Creation**: Safe directory creation for nested path structures
+ * - **Path Normalization**: Consistent path formatting across different systems
+ *
+ * @example Basic path resolution
+ * ```typescript
+ * import { toResolvedArtifactPath } from '@skmtc/core/toResolvedArtifactPath';
+ *
+ * // Resolve relative path with base directory
+ * const resolvedPath = toResolvedArtifactPath({
+ *   basePath: '/project/src',
+ *   destinationPath: './generated/UserApi.ts'
+ * });
+ *
+ * console.log(resolvedPath); // '/project/src/generated/UserApi.ts'
+ * ```
+ *
+ * @example Absolute path handling
+ * ```typescript
+ * import { toResolvedArtifactPath } from '@skmtc/core/toResolvedArtifactPath';
+ *
+ * // Absolute paths are returned as-is
+ * const absolutePath = toResolvedArtifactPath({
+ *   basePath: '/project/src',
+ *   destinationPath: '/absolute/path/to/UserApi.ts'
+ * });
+ *
+ * console.log(absolutePath); // '/absolute/path/to/UserApi.ts'
+ * ```
+ *
+ * @example Working without base path
+ * ```typescript
+ * import { toResolvedArtifactPath } from '@skmtc/core/toResolvedArtifactPath';
+ *
+ * // When basePath is undefined, returns the destination path
+ * const path = toResolvedArtifactPath({
+ *   basePath: undefined,
+ *   destinationPath: './UserApi.ts'
+ * });
+ *
+ * console.log(path); // './UserApi.ts'
+ * ```
+ *
+ * @module toResolvedArtifactPath
+ */
 require("../_dnt.polyfills.js");
 const join_js_1 = require("../deps/jsr.io/@std/path/1.1.2/join.js");
 /**

package/script/types/EnrichmentRequest.d.ts

@@ -1,5 +1,67 @@
+/**
+ * @fileoverview Enrichment Request System for SKMTC Core
+ *
+ * This module provides types for handling enrichment requests within the SKMTC
+ * code generation pipeline. Enrichment requests allow generators to request
+ * additional metadata and context about operations, schemas, and other OpenAPI
+ * elements to enhance code generation with richer functionality.
+ *
+ * The enrichment system enables generators to ask for specific data transformations,
+ * UI component configurations, validation rules, and other metadata that can be
+ * applied during the generation process to create more sophisticated output.
+ *
+ * ## Key Features
+ *
+ * - **Type-Safe Requests**: Generic typing ensures enrichment data matches expected schema
+ * - **Flexible Content**: Support for any content type that needs enrichment
+ * - **Schema Validation**: Valibot integration for runtime validation of enrichment data
+ * - **Generator Integration**: Seamless integration with the generator pipeline
+ *
+ * @example Creating an enrichment request
+ * ```typescript
+ * import { EnrichmentRequest } from '@skmtc/core/EnrichmentRequest';
+ * import * as v from 'valibot';
+ *
+ * const formEnrichmentSchema = v.object({
+ *   title: v.string(),
+ *   fields: v.array(v.object({
+ *     name: v.string(),
+ *     type: v.string(),
+ *     required: v.boolean()
+ *   }))
+ * });
+ *
+ * const request: EnrichmentRequest<typeof formEnrichmentSchema> = {
+ *   prompt: 'Generate form metadata for user registration',
+ *   enrichmentSchema: formEnrichmentSchema,
+ *   content: JSON.stringify({ operationId: 'createUser', method: 'POST' })
+ * };
+ * ```
+ *
+ * @example Processing enrichment in generators
+ * ```typescript
+ * function processEnrichment<T>(request: EnrichmentRequest<T>) {
+ *   // Validate the enrichment data against the schema
+ *   const enrichmentData = v.parse(request.enrichmentSchema, someData);
+ *
+ *   // Use the enrichment data to enhance generation
+ *   return generateEnhancedContent(request.content, enrichmentData);
+ * }
+ * ```
+ *
+ * @module EnrichmentRequest
+ */
 import "../_dnt.polyfills.js";
 import type * as v from 'valibot';
+/**
+ * Represents a request for enrichment data during code generation.
+ *
+ * Enrichment requests allow generators to specify what additional metadata
+ * they need for generating enhanced code artifacts. The request includes
+ * a schema for validation and the content that needs enrichment.
+ *
+ * @template EnrichmentType - The type of enrichment data being requested
+ */
 export type EnrichmentRequest<EnrichmentType = undefined> = {
     prompt: string;
     enrichmentSchema: v.BaseSchema<EnrichmentType, EnrichmentType, v.BaseIssue<unknown>>;

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

@@ -1 +1 @@
-{"version":3,"file":"EnrichmentRequest.d.ts","sourceRoot":"","sources":["../../src/types/EnrichmentRequest.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAC9B,OAAO,KAAK,KAAK,CAAC,MAAM,SAAS,CAAA;AAEjC,MAAM,MAAM,iBAAiB,CAAC,cAAc,GAAG,SAAS,IAAI;IAC1D,MAAM,EAAE,MAAM,CAAA;IACd,gBAAgB,EAAE,CAAC,CAAC,UAAU,CAAC,cAAc,EAAE,cAAc,EAAE,CAAC,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAA;IACpF,OAAO,EAAE,MAAM,CAAA;CAChB,CAAA"}
+{"version":3,"file":"EnrichmentRequest.d.ts","sourceRoot":"","sources":["../../src/types/EnrichmentRequest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH,OAAO,sBAAsB,CAAC;AAG9B,OAAO,KAAK,KAAK,CAAC,MAAM,SAAS,CAAA;AAEjC;;;;;;;;GAQG;AACH,MAAM,MAAM,iBAAiB,CAAC,cAAc,GAAG,SAAS,IAAI;IAC1D,MAAM,EAAE,MAAM,CAAA;IACd,gBAAgB,EAAE,CAAC,CAAC,UAAU,CAAC,cAAc,EAAE,cAAc,EAAE,CAAC,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAA;IACpF,OAAO,EAAE,MAAM,CAAA;CAChB,CAAA"}