@skmtc/core 0.0.806 → 0.0.808

package/esm/types/Results.js

@@ -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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skmtc/core",
-  "version": "0.0.806",
+  "version": "0.0.808",
   "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"}

package/script/types/EnrichmentRequest.js

@@ -1,3 +1,56 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * @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
+ */
 require("../_dnt.polyfills.js");

package/script/types/GeneratorKeys.d.ts

@@ -1,3 +1,67 @@
+/**
+ * @fileoverview Generator Key System for SKMTC Core
+ *
+ * This module provides a comprehensive type-safe key system for identifying and
+ * organizing generated content within the SKMTC pipeline. Generator keys provide
+ * unique identification for operations, models, and other generated artifacts,
+ * ensuring proper organization and preventing collisions.
+ *
+ * The key system uses branded types to ensure type safety and provides utilities
+ * for creating, parsing, and manipulating keys throughout the generation process.
+ *
+ * ## Key Features
+ *
+ * - **Type Safety**: Branded types prevent mixing different kinds of keys
+ * - **Unique Identification**: Composite keys ensure global uniqueness
+ * - **Parsing Utilities**: Safe extraction of components from composite keys
+ * - **Generator Organization**: Clear mapping between generators and their artifacts
+ * - **Reference Integration**: Seamless integration with OpenAPI reference system
+ *
+ * @example Creating operation generator keys
+ * ```typescript
+ * import { toOperationGeneratorKey, parseOperationGeneratorKey } from '@skmtc/core/GeneratorKeys';
+ *
+ * // Create a key for a GET /users operation in api-client generator
+ * const key = toOperationGeneratorKey({
+ *   generatorId: 'api-client',
+ *   path: '/users',
+ *   method: 'GET'
+ * });
+ *
+ * // Parse the key back into components
+ * const parsed = parseOperationGeneratorKey(key);
+ * console.log(parsed); // { generatorId: 'api-client', path: '/users', method: 'GET' }
+ * ```
+ *
+ * @example Working with model keys
+ * ```typescript
+ * import { toModelGeneratorKey } from '@skmtc/core/GeneratorKeys';
+ *
+ * const modelKey = toModelGeneratorKey({
+ *   generatorId: 'typescript-models',
+ *   refName: 'User' as RefName
+ * });
+ * ```
+ *
+ * @example Type-safe key handling
+ * ```typescript
+ * import type { OperationGeneratorKey, ModelGeneratorKey } from '@skmtc/core/GeneratorKeys';
+ *
+ * function handleOperationKey(key: OperationGeneratorKey) {
+ *   // TypeScript ensures this is specifically an operation key
+ *   const parsed = parseOperationGeneratorKey(key);
+ *   return `Processing ${parsed.method} ${parsed.path}`;
+ * }
+ *
+ * function handleModelKey(key: ModelGeneratorKey) {
+ *   // TypeScript ensures this is specifically a model key
+ *   const parsed = parseModelGeneratorKey(key);
+ *   return `Processing model ${parsed.refName}`;
+ * }
+ * ```
+ *
+ * @module GeneratorKeys
+ */
 import "../_dnt.polyfills.js";
 import type { OasOperation } from '../oas/operation/Operation.js';
 import type { Brand } from './Brand.js';

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

@@ -1 +1 @@
-{"version":3,"file":"GeneratorKeys.d.ts","sourceRoot":"","sources":["../../src/types/GeneratorKeys.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAA;AACjE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AACvC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAC3C,OAAO,EAAE,KAAK,MAAM,EAAY,MAAM,aAAa,CAAA;AAEnD;;;GAGG;AACH,MAAM,MAAM,0BAA0B,GAAG,GAAG,MAAM,IAAI,MAAM,IAAI,MAAM,EAAE,CAAA;AAExE;;;GAGG;AACH,MAAM,MAAM,sBAAsB,GAAG,GAAG,MAAM,IAAI,MAAM,EAAE,CAAA;AAE1D;;;;;;GAMG;AACH,MAAM,MAAM,qBAAqB,GAAG,KAAK,CACvC,0BAA0B,EAC1B,uBAAuB,CACxB,CAAA;AAED;;;;;;GAMG;AACH,MAAM,MAAM,iBAAiB,GAAG,KAAK,CACnC,sBAAsB,EACtB,mBAAmB,CACpB,CAAA;AAED;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GAAG,KAAK,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAA;AAEhE;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,MAAM,YAAY,GACpB,qBAAqB,GACrB,iBAAiB,GACjB,gBAAgB,CAAA;AAEpB;;;;;GAKG;AACH,KAAK,2BAA2B,GAC5B;IACE,0CAA0C;IAC1C,WAAW,EAAE,MAAM,CAAA;IACnB,qCAAqC;IACrC,IAAI,EAAE,MAAM,CAAA;IACZ,kBAAkB;IAClB,MAAM,EAAE,MAAM,CAAA;CACf,GACD;IACE,0CAA0C;IAC1C,WAAW,EAAE,MAAM,CAAA;IACnB,0DAA0D;IAC1D,SAAS,EAAE,YAAY,CAAA;CACxB,CAAA;AAEL;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,eAAO,MAAM,uBAAuB,GAAI,0BAGrC,2BAA2B,KAAG,qBAMhC,CAAA;AAED;;GAEG;AACH,KAAK,uBAAuB,GAAG;IAC7B,0CAA0C;IAC1C,WAAW,EAAE,MAAM,CAAA;IACnB,yCAAyC;IACzC,OAAO,EAAE,OAAO,CAAA;CACjB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,mBAAmB,GAAI,0BAGjC,uBAAuB,KAAG,iBAI5B,CAAA;AAED;;GAEG;AACH,KAAK,sBAAsB,GAAG;IAC5B,0CAA0C;IAC1C,WAAW,EAAE,MAAM,CAAA;CACpB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,kBAAkB,GAAI,iBAEhC,sBAAsB,KAAG,gBAI3B,CAAA;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,cAAc,GAAI,KAAK,OAAO,KAAG,GAAG,IAAI,YAMpD,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,uBAAuB,GAClC,KAAK,OAAO,KACX,GAAG,IAAI,qBA0BT,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,mBAAmB,GAAI,KAAK,OAAO,KAAG,GAAG,IAAI,iBAsBzD,CAAA;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,kBAAkB,GAAI,KAAK,OAAO,KAAG,GAAG,IAAI,gBAMxD,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,aAAa,GAAI,cAAc,YAAY,KAAG,MAU1D,CAAA;AAED;;;;;;GAMG;AACH,MAAM,MAAM,kBAAkB,GAC1B;IACE,iDAAiD;IACjD,IAAI,EAAE,WAAW,CAAA;IACjB,2BAA2B;IAC3B,WAAW,EAAE,MAAM,CAAA;IACnB,eAAe;IACf,IAAI,EAAE,MAAM,CAAA;IACZ,kBAAkB;IAClB,MAAM,EAAE,MAAM,CAAA;CACf,GACD;IACE,6CAA6C;IAC7C,IAAI,EAAE,OAAO,CAAA;IACb,2BAA2B;IAC3B,WAAW,EAAE,MAAM,CAAA;IACnB,4BAA4B;IAC5B,OAAO,EAAE,MAAM,CAAA;CAChB,GACD;IACE,4CAA4C;IAC5C,IAAI,EAAE,gBAAgB,CAAA;IACtB,2BAA2B;IAC3B,WAAW,EAAE,MAAM,CAAA;CACpB,CAAA;AAEL;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,eAAO,MAAM,gBAAgB,GAC3B,cAAc,YAAY,KACzB,kBAYF,CAAA"}
+{"version":3,"file":"GeneratorKeys.d.ts","sourceRoot":"","sources":["../../src/types/GeneratorKeys.ts"],"names":[],"mappings":"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"}

package/script/types/GeneratorKeys.js

@@ -1,6 +1,70 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.fromGeneratorKey = exports.toGeneratorId = exports.isGeneratorOnlyKey = exports.isModelGeneratorKey = exports.isOperationGeneratorKey = exports.isGeneratorKey = exports.toGeneratorOnlyKey = exports.toModelGeneratorKey = exports.toOperationGeneratorKey = void 0;
+/**
+ * @fileoverview Generator Key System for SKMTC Core
+ *
+ * This module provides a comprehensive type-safe key system for identifying and
+ * organizing generated content within the SKMTC pipeline. Generator keys provide
+ * unique identification for operations, models, and other generated artifacts,
+ * ensuring proper organization and preventing collisions.
+ *
+ * The key system uses branded types to ensure type safety and provides utilities
+ * for creating, parsing, and manipulating keys throughout the generation process.
+ *
+ * ## Key Features
+ *
+ * - **Type Safety**: Branded types prevent mixing different kinds of keys
+ * - **Unique Identification**: Composite keys ensure global uniqueness
+ * - **Parsing Utilities**: Safe extraction of components from composite keys
+ * - **Generator Organization**: Clear mapping between generators and their artifacts
+ * - **Reference Integration**: Seamless integration with OpenAPI reference system
+ *
+ * @example Creating operation generator keys
+ * ```typescript
+ * import { toOperationGeneratorKey, parseOperationGeneratorKey } from '@skmtc/core/GeneratorKeys';
+ *
+ * // Create a key for a GET /users operation in api-client generator
+ * const key = toOperationGeneratorKey({
+ *   generatorId: 'api-client',
+ *   path: '/users',
+ *   method: 'GET'
+ * });
+ *
+ * // Parse the key back into components
+ * const parsed = parseOperationGeneratorKey(key);
+ * console.log(parsed); // { generatorId: 'api-client', path: '/users', method: 'GET' }
+ * ```
+ *
+ * @example Working with model keys
+ * ```typescript
+ * import { toModelGeneratorKey } from '@skmtc/core/GeneratorKeys';
+ *
+ * const modelKey = toModelGeneratorKey({
+ *   generatorId: 'typescript-models',
+ *   refName: 'User' as RefName
+ * });
+ * ```
+ *
+ * @example Type-safe key handling
+ * ```typescript
+ * import type { OperationGeneratorKey, ModelGeneratorKey } from '@skmtc/core/GeneratorKeys';
+ *
+ * function handleOperationKey(key: OperationGeneratorKey) {
+ *   // TypeScript ensures this is specifically an operation key
+ *   const parsed = parseOperationGeneratorKey(key);
+ *   return `Processing ${parsed.method} ${parsed.path}`;
+ * }
+ *
+ * function handleModelKey(key: ModelGeneratorKey) {
+ *   // TypeScript ensures this is specifically a model key
+ *   const parsed = parseModelGeneratorKey(key);
+ *   return `Processing model ${parsed.refName}`;
+ * }
+ * ```
+ *
+ * @module GeneratorKeys
+ */
 require("../_dnt.polyfills.js");
 const Method_js_1 = require("./Method.js");
 /**

package/script/types/Manifest.d.ts

@@ -1,3 +1,75 @@
+/**
+ * @fileoverview Generation Manifest System for SKMTC Core
+ *
+ * This module provides comprehensive manifest generation for tracking and organizing
+ * all artifacts produced during the SKMTC code generation process. The manifest
+ * system captures metadata about generated files, including size metrics, locations,
+ * preview information, and generation statistics.
+ *
+ * Manifests serve as a complete inventory of generated content, enabling tools,
+ * IDEs, and other systems to understand what was generated and how to interact
+ * with the generated code.
+ *
+ * ## Key Features
+ *
+ * - **File Tracking**: Complete inventory of all generated files with metrics
+ * - **Size Analytics**: Line counts, character counts, and size statistics
+ * - **Preview Integration**: Rich preview metadata for UI generation
+ * - **Generation Stats**: Detailed metrics about the generation process
+ * - **Type Safety**: Comprehensive validation with Valibot schemas
+ *
+ * @example Creating a manifest entry
+ * ```typescript
+ * import type { ManifestEntry } from '@skmtc/core/Manifest';
+ *
+ * const entry: ManifestEntry = {
+ *   lines: 150,
+ *   characters: 4200,
+ *   destinationPath: './src/generated/UserApi.ts'
+ * };
+ * ```
+ *
+ * @example Processing manifest content
+ * ```typescript
+ * import type { ManifestContent } from '@skmtc/core/Manifest';
+ *
+ * const manifest: ManifestContent = {
+ *   files: {
+ *     'UserApi.ts': {
+ *       lines: 150,
+ *       characters: 4200,
+ *       destinationPath: './src/generated/UserApi.ts'
+ *     }
+ *   },
+ *   stats: {
+ *     totalFiles: 1,
+ *     totalLines: 150,
+ *     totalCharacters: 4200,
+ *     generatedAt: new Date().toISOString()
+ *   },
+ *   previews: [],
+ *   mappings: []
+ * };
+ * ```
+ *
+ * @example Using manifest for tooling
+ * ```typescript
+ * function analyzeGeneration(manifest: ManifestContent) {
+ *   const fileCount = Object.keys(manifest.files).length;
+ *   const totalSize = Object.values(manifest.files)
+ *     .reduce((sum, file) => sum + file.characters, 0);
+ *
+ *   console.log(`Generated ${fileCount} files with ${totalSize} characters`);
+ *
+ *   // Process previews for UI generation
+ *   manifest.previews.forEach(preview => {
+ *     console.log(`Preview available: ${preview.title}`);
+ *   });
+ * }
+ * ```
+ *
+ * @module Manifest
+ */
 import "../_dnt.polyfills.js";
 import { type ResultsItem } from './Results.js';
 import { type Preview, type Mapping } from './Preview.js';

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

@@ -1 +1 @@
-{"version":3,"file":"Manifest.d.ts","sourceRoot":"","sources":["../../src/types/Manifest.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAC9B,OAAO,EAAe,KAAK,WAAW,EAAE,MAAM,cAAc,CAAA;AAC5D,OAAO,EAAW,KAAK,OAAO,EAAE,KAAK,OAAO,EAAW,MAAM,cAAc,CAAA;AAC3E,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAE5B,MAAM,MAAM,aAAa,GAAG;IAC1B,KAAK,EAAE,MAAM,CAAA;IACb,UAAU,EAAE,MAAM,CAAA;IAClB,eAAe,EAAE,MAAM,CAAA;CACxB,CAAA;AAED,eAAO,MAAM,aAAa,EAAE,CAAC,CAAC,aAAa,CAAC,aAAa,CAIvD,CAAA;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EAAE,MAAM,CAAA;IACZ,UAAU,EAAE,MAAM,CAAA;CACnB,CAAA;AAED,eAAO,MAAM,WAAW,EAAE,CAAC,CAAC,aAAa,CAAC,WAAW,CAGnD,CAAA;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,YAAY,EAAE,MAAM,CAAA;IACpB,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAA;IACpC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;IACjD,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;IAClD,OAAO,EAAE,WAAW,CAAA;IACpB,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,MAAM,CAAA;CACd,CAAA;AAED,eAAO,MAAM,eAAe,EAAE,CAAC,CAAC,aAAa,CAAC,eAAe,CAW3D,CAAA"}
+{"version":3,"file":"Manifest.d.ts","sourceRoot":"","sources":["../../src/types/Manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuEG;AACH,OAAO,sBAAsB,CAAC;AAG9B,OAAO,EAAe,KAAK,WAAW,EAAE,MAAM,cAAc,CAAA;AAC5D,OAAO,EAAW,KAAK,OAAO,EAAE,KAAK,OAAO,EAAW,MAAM,cAAc,CAAA;AAC3E,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAE5B,MAAM,MAAM,aAAa,GAAG;IAC1B,KAAK,EAAE,MAAM,CAAA;IACb,UAAU,EAAE,MAAM,CAAA;IAClB,eAAe,EAAE,MAAM,CAAA;CACxB,CAAA;AAED,eAAO,MAAM,aAAa,EAAE,CAAC,CAAC,aAAa,CAAC,aAAa,CAIvD,CAAA;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EAAE,MAAM,CAAA;IACZ,UAAU,EAAE,MAAM,CAAA;CACnB,CAAA;AAED,eAAO,MAAM,WAAW,EAAE,CAAC,CAAC,aAAa,CAAC,WAAW,CAGnD,CAAA;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,YAAY,EAAE,MAAM,CAAA;IACpB,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAA;IACpC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;IACjD,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;IAClD,OAAO,EAAE,WAAW,CAAA;IACpB,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,MAAM,CAAA;CACd,CAAA;AAED,eAAO,MAAM,eAAe,EAAE,CAAC,CAAC,aAAa,CAAC,eAAe,CAW3D,CAAA"}