@skmtc/core 0.0.783 → 0.0.785

package/esm/dsl/operation/OperationBase.d.ts

@@ -12,17 +12,192 @@ import type { RefName } from '../../types/RefName.js';
 import { OasSchema } from '../../oas/schema/Schema.js';
 import { OasRef } from '../../oas/ref/Ref.js';
 import { OasVoid } from '../../oas/void/Void.js';
+/**
+ * Constructor arguments for {@link OperationBase}.
+ *
+ * @template EnrichmentType - Optional type for custom enrichment data
+ */
 export type OperationBaseArgs<EnrichmentType = undefined> = {
+    /** The generation context providing access to the processing pipeline */
     context: GenerateContext;
+    /** Content settings including export path and enrichment configuration */
     settings: ContentSettings<EnrichmentType>;
+    /** Unique identifier for this generator type */
     generatorKey: GeneratorKey;
+    /** The OpenAPI operation being processed */
     operation: OasOperation;
 };
+/**
+ * Base class for operation generators in the SKMTC DSL system.
+ *
+ * `OperationBase` extends {@link ContentBase} to provide specialized functionality for
+ * generating code from OpenAPI operations. It offers type-safe methods for inserting
+ * related operations and models, managing complex operation dependencies, and handling
+ * enrichments specific to API operations.
+ *
+ * This class serves as the foundation for creating custom operation generators that
+ * transform OpenAPI operations into various code artifacts like API clients, server
+ * handlers, validation middleware, or documentation.
+ *
+ * ## Key Features
+ *
+ * - **Operation Insertion**: Insert related operations with automatic dependency tracking
+ * - **Model Integration**: Seamlessly insert related models from operation schemas
+ * - **Schema Normalization**: Handle complex request/response schema references
+ * - **Export Management**: Control which operations are exported from generated files
+ * - **Enrichment Support**: Extend functionality with operation-specific enrichment data
+ * - **Type Safety**: Full TypeScript support with generic enrichment types
+ *
+ * @template EnrichmentType - Optional type for custom enrichment data
+ *
+ * @example Basic API client generator
+ * ```typescript
+ * import { OperationBase, Definition } from '@skmtc/core';
+ *
+ * class ApiClientMethod extends OperationBase {
+ *   toDefinition(): Definition {
+ *     const { method, path, operationId } = this.operation;
+ *
+ *     return new Definition({
+ *       name: operationId || `${method}${this.pascalCasePath()}`,
+ *       content: `async ${operationId}(${this.generateParameters()}) {
+ *         return this.request('${method}', '${path}', ${this.generateRequestBody()});
+ *       }`
+ *     });
+ *   }
+ * }
+ * ```
+ *
+ * @example With request/response models
+ * ```typescript
+ * class TypedApiMethod extends OperationBase {
+ *   toDefinition(): Definition {
+ *     const operation = this.operation;
+ *
+ *     // Generate request model if needed
+ *     let requestType = 'void';
+ *     if (operation.requestBody?.content?.['application/json']?.schema) {
+ *       const requestModel = this.insertNormalizedModel(
+ *         new RequestModel({ ... }),
+ *         {
+ *           schema: operation.requestBody.content['application/json'].schema,
+ *           fallbackName: `${operation.operationId}Request`
+ *         }
+ *       );
+ *       requestType = requestModel.value;
+ *     }
+ *
+ *     // Generate response model
+ *     const responseSchema = operation.responses?.['200']?.content?.['application/json']?.schema;
+ *     const responseModel = this.insertNormalizedModel(
+ *       new ResponseModel({ ... }),
+ *       { schema: responseSchema, fallbackName: `${operation.operationId}Response` }
+ *     );
+ *
+ *     return new Definition({
+ *       name: operation.operationId,
+ *       content: `async ${operation.operationId}(data: ${requestType}): Promise<${responseModel.value}> {
+ *         return this.request('${operation.method}', '${operation.path}', data);
+ *       }`
+ *     });
+ *   }
+ * }
+ * ```
+ *
+ * @example With enrichments
+ * ```typescript
+ * type AuthEnrichment = {
+ *   requiresAuth: boolean;
+ *   permissions: string[];
+ * };
+ *
+ * class SecuredApiMethod extends OperationBase<AuthEnrichment> {
+ *   toDefinition(): Definition {
+ *     const enrichment = this.settings.enrichment;
+ *     const requiresAuth = enrichment?.requiresAuth ?? false;
+ *
+ *     const authCheck = requiresAuth
+ *       ? 'this.checkAuth();'
+ *       : '';
+ *
+ *     return new Definition({
+ *       name: this.operation.operationId,
+ *       content: `async ${this.operation.operationId}() {
+ *         ${authCheck}
+ *         return this.request('${this.operation.method}', '${this.operation.path}');
+ *       }`
+ *     });
+ *   }
+ * }
+ * ```
+ */
 export declare class OperationBase<EnrichmentType = undefined> extends ContentBase {
+    /** Content settings including export path and enrichment configuration */
     settings: ContentSettings<EnrichmentType>;
+    /** The OpenAPI operation being processed */
     operation: OasOperation;
+    /** Generator key identifying this generator type */
     generatorKey: GeneratorKey;
+    /**
+     * Creates a new OperationBase instance.
+     *
+     * @param args - Operation generator configuration
+     * @param args.context - The generation context providing pipeline access
+     * @param args.settings - Content settings with export path and enrichments
+     * @param args.generatorKey - Unique identifier for this generator type
+     * @param args.operation - The OpenAPI operation being processed
+     *
+     * @example
+     * ```typescript
+     * const operation = new OperationBase({
+     *   context: generateContext,
+     *   settings: {
+     *     exportPath: './src/api.ts',
+     *     enrichment: customEnrichments
+     *   },
+     *   generatorKey: 'api-client',
+     *   operation: oasOperation
+     * });
+     * ```
+     */
     constructor({ context, generatorKey, settings, operation }: OperationBaseArgs<EnrichmentType>);
+    /**
+     * Inserts a related operation with forced generation.
+     *
+     * This method adds a related operation to the current generation context, ensuring
+     * it will be generated regardless of whether it already exists. This is useful for
+     * operations that depend on other operations or need to generate helper operations.
+     *
+     * @template V - Type of generated value returned by the insertable
+     * @template EnrichmentType - Type of enrichment data for the insertable
+     * @param insertable - The operation generator to insert
+     * @param operation - The OpenAPI operation to process
+     * @param options - Insertion options
+     * @param options.noExport - Whether to skip exporting the inserted operation
+     * @returns Inserted operation reference with generated value
+     *
+     * @example Inserting helper operations
+     * ```typescript
+     * class CrudApiClient extends OperationBase {
+     *   toDefinition(): Definition {
+     *     // Insert a related validation operation
+     *     const validator = this.insertOperation(
+     *       new ValidationOperation({ ... }),
+     *       this.operation,
+     *       { noExport: true }
+     *     );
+     *
+     *     return new Definition({
+     *       name: this.operation.operationId,
+     *       content: `async ${this.operation.operationId}(data: any) {
+     *         ${validator.value}(data);
+     *         return this.request('${this.operation.method}', '${this.operation.path}', data);
+     *       }`
+     *     });
+     *   }
+     * }
+     * ```
+     */
     insertOperation<V extends GeneratedValue, EnrichmentType = undefined>(insertable: OperationInsertable<V, EnrichmentType>, operation: OasOperation, options?: Pick<InsertOperationOptions<'force'>, 'noExport'>): Inserted<V, 'force', EnrichmentType>;
     insertModel<V extends GeneratedValue, EnrichmentType = undefined>(insertable: ModelInsertable<V, EnrichmentType>, refName: RefName, options?: Pick<InsertModelOptions<'force'>, 'noExport'>): Inserted<V, 'force', EnrichmentType>;
     insertNormalizedModel<V extends GeneratedValue, Schema extends OasSchema | OasRef<'schema'> | OasVoid, EnrichmentType = undefined>(insertable: ModelInsertable<V, EnrichmentType>, { schema, fallbackName }: Omit<InsertNormalisedModelArgs<Schema>, 'destinationPath'>, options?: Pick<InsertModelOptions<'force'>, 'noExport'>): InsertNormalisedModelReturn<V, Schema>;

package/esm/dsl/operation/OperationBase.d.ts.map

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

package/esm/dsl/operation/OperationBase.js

@@ -1,19 +1,148 @@
 import { ContentBase } from '../ContentBase.js';
+/**
+ * Base class for operation generators in the SKMTC DSL system.
+ *
+ * `OperationBase` extends {@link ContentBase} to provide specialized functionality for
+ * generating code from OpenAPI operations. It offers type-safe methods for inserting
+ * related operations and models, managing complex operation dependencies, and handling
+ * enrichments specific to API operations.
+ *
+ * This class serves as the foundation for creating custom operation generators that
+ * transform OpenAPI operations into various code artifacts like API clients, server
+ * handlers, validation middleware, or documentation.
+ *
+ * ## Key Features
+ *
+ * - **Operation Insertion**: Insert related operations with automatic dependency tracking
+ * - **Model Integration**: Seamlessly insert related models from operation schemas
+ * - **Schema Normalization**: Handle complex request/response schema references
+ * - **Export Management**: Control which operations are exported from generated files
+ * - **Enrichment Support**: Extend functionality with operation-specific enrichment data
+ * - **Type Safety**: Full TypeScript support with generic enrichment types
+ *
+ * @template EnrichmentType - Optional type for custom enrichment data
+ *
+ * @example Basic API client generator
+ * ```typescript
+ * import { OperationBase, Definition } from '@skmtc/core';
+ *
+ * class ApiClientMethod extends OperationBase {
+ *   toDefinition(): Definition {
+ *     const { method, path, operationId } = this.operation;
+ *
+ *     return new Definition({
+ *       name: operationId || `${method}${this.pascalCasePath()}`,
+ *       content: `async ${operationId}(${this.generateParameters()}) {
+ *         return this.request('${method}', '${path}', ${this.generateRequestBody()});
+ *       }`
+ *     });
+ *   }
+ * }
+ * ```
+ *
+ * @example With request/response models
+ * ```typescript
+ * class TypedApiMethod extends OperationBase {
+ *   toDefinition(): Definition {
+ *     const operation = this.operation;
+ *
+ *     // Generate request model if needed
+ *     let requestType = 'void';
+ *     if (operation.requestBody?.content?.['application/json']?.schema) {
+ *       const requestModel = this.insertNormalizedModel(
+ *         new RequestModel({ ... }),
+ *         {
+ *           schema: operation.requestBody.content['application/json'].schema,
+ *           fallbackName: `${operation.operationId}Request`
+ *         }
+ *       );
+ *       requestType = requestModel.value;
+ *     }
+ *
+ *     // Generate response model
+ *     const responseSchema = operation.responses?.['200']?.content?.['application/json']?.schema;
+ *     const responseModel = this.insertNormalizedModel(
+ *       new ResponseModel({ ... }),
+ *       { schema: responseSchema, fallbackName: `${operation.operationId}Response` }
+ *     );
+ *
+ *     return new Definition({
+ *       name: operation.operationId,
+ *       content: `async ${operation.operationId}(data: ${requestType}): Promise<${responseModel.value}> {
+ *         return this.request('${operation.method}', '${operation.path}', data);
+ *       }`
+ *     });
+ *   }
+ * }
+ * ```
+ *
+ * @example With enrichments
+ * ```typescript
+ * type AuthEnrichment = {
+ *   requiresAuth: boolean;
+ *   permissions: string[];
+ * };
+ *
+ * class SecuredApiMethod extends OperationBase<AuthEnrichment> {
+ *   toDefinition(): Definition {
+ *     const enrichment = this.settings.enrichment;
+ *     const requiresAuth = enrichment?.requiresAuth ?? false;
+ *
+ *     const authCheck = requiresAuth
+ *       ? 'this.checkAuth();'
+ *       : '';
+ *
+ *     return new Definition({
+ *       name: this.operation.operationId,
+ *       content: `async ${this.operation.operationId}() {
+ *         ${authCheck}
+ *         return this.request('${this.operation.method}', '${this.operation.path}');
+ *       }`
+ *     });
+ *   }
+ * }
+ * ```
+ */
 export class OperationBase extends ContentBase {
+    /**
+     * Creates a new OperationBase instance.
+     *
+     * @param args - Operation generator configuration
+     * @param args.context - The generation context providing pipeline access
+     * @param args.settings - Content settings with export path and enrichments
+     * @param args.generatorKey - Unique identifier for this generator type
+     * @param args.operation - The OpenAPI operation being processed
+     *
+     * @example
+     * ```typescript
+     * const operation = new OperationBase({
+     *   context: generateContext,
+     *   settings: {
+     *     exportPath: './src/api.ts',
+     *     enrichment: customEnrichments
+     *   },
+     *   generatorKey: 'api-client',
+     *   operation: oasOperation
+     * });
+     * ```
+     */
     constructor({ context, generatorKey, settings, operation }) {
         super({ context });
+        /** Content settings including export path and enrichment configuration */
         Object.defineProperty(this, "settings", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /** The OpenAPI operation being processed */
         Object.defineProperty(this, "operation", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /** Generator key identifying this generator type */
         Object.defineProperty(this, "generatorKey", {
             enumerable: true,
             configurable: true,
@@ -24,6 +153,43 @@ export class OperationBase extends ContentBase {
         this.operation = operation;
         this.settings = settings;
     }
+    /**
+     * Inserts a related operation with forced generation.
+     *
+     * This method adds a related operation to the current generation context, ensuring
+     * it will be generated regardless of whether it already exists. This is useful for
+     * operations that depend on other operations or need to generate helper operations.
+     *
+     * @template V - Type of generated value returned by the insertable
+     * @template EnrichmentType - Type of enrichment data for the insertable
+     * @param insertable - The operation generator to insert
+     * @param operation - The OpenAPI operation to process
+     * @param options - Insertion options
+     * @param options.noExport - Whether to skip exporting the inserted operation
+     * @returns Inserted operation reference with generated value
+     *
+     * @example Inserting helper operations
+     * ```typescript
+     * class CrudApiClient extends OperationBase {
+     *   toDefinition(): Definition {
+     *     // Insert a related validation operation
+     *     const validator = this.insertOperation(
+     *       new ValidationOperation({ ... }),
+     *       this.operation,
+     *       { noExport: true }
+     *     );
+     *
+     *     return new Definition({
+     *       name: this.operation.operationId,
+     *       content: `async ${this.operation.operationId}(data: any) {
+     *         ${validator.value}(data);
+     *         return this.request('${this.operation.method}', '${this.operation.path}', data);
+     *       }`
+     *     });
+     *   }
+     * }
+     * ```
+     */
     insertOperation(insertable, operation, options = {}) {
         return this.context.insertOperation(insertable, operation, {
             generation: 'force',

package/package.json

@@ -1,6 +1,10 @@
 {
   "name": "@skmtc/core",
-  "version": "0.0.783",
+  "version": "0.0.785",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/skmtc/skmtc.git"
+  },
   "main": "./script/mod.js",
   "module": "./esm/mod.js",
   "exports": {

package/script/dsl/File.d.ts

@@ -1,24 +1,232 @@
 import type { Definition } from './Definition.js';
 import type { ClientSettings, ModulePackage } from '../types/Settings.js';
+/**
+ * Constructor arguments for {@link File}.
+ */
 type FileArgs = {
+    /** The file path for the generated file */
     path: string;
+    /** Client settings containing package configuration */
     settings: ClientSettings | undefined;
 };
+/**
+ * Represents a TypeScript file in the SKMTC DSL system.
+ *
+ * The `File` class is a core component for generating TypeScript files with proper
+ * import management, re-exports, and content organization. It automatically handles
+ * module resolution, import optimization, and package-aware path normalization.
+ *
+ * ## Key Features
+ *
+ * - **Import Management**: Automatically tracks and organizes imports from other modules
+ * - **Re-export Handling**: Supports re-exporting symbols from other modules
+ * - **Package Awareness**: Handles module packages for complex project structures
+ * - **Definition Tracking**: Manages code definitions and their relationships
+ * - **Path Normalization**: Automatically resolves paths based on package configuration
+ *
+ * @example Basic file creation
+ * ```typescript
+ * import { File } from '@skmtc/core';
+ *
+ * const file = new File({
+ *   path: './src/models/User.ts',
+ *   settings: clientSettings
+ * });
+ *
+ * // Add imports
+ * file.imports.set('./types', new Set(['BaseModel', 'Validator']));
+ *
+ * // Add definitions
+ * file.definitions.set('User', userInterface);
+ *
+ * // Generate file content
+ * const content = file.toString();
+ * console.log(content);
+ * // import { BaseModel, Validator } from './types'
+ * //
+ * // export interface User extends BaseModel {
+ * //   id: string;
+ * //   name: string;
+ * // }
+ * ```
+ *
+ * @example With package configuration
+ * ```typescript
+ * const file = new File({
+ *   path: './packages/client/src/api.ts',
+ *   settings: {
+ *     packages: [
+ *       {
+ *         rootPath: './packages/types',
+ *         moduleName: '@myorg/types'
+ *       }
+ *     ]
+ *   }
+ * });
+ *
+ * // Import from another package
+ * file.imports.set('./packages/types/models', new Set(['User']));
+ *
+ * // Will generate: import { User } from '@myorg/types/models'
+ * ```
+ *
+ * @example Re-exports
+ * ```typescript
+ * const file = new File({
+ *   path: './src/index.ts',
+ *   settings: clientSettings
+ * });
+ *
+ * // Add re-exports
+ * file.reExports.set('./models', {
+ *   'type': new Set(['User', 'Product']),
+ *   'const': new Set(['DEFAULT_CONFIG'])
+ * });
+ *
+ * // Will generate:
+ * // export type { User, Product } from './models'
+ * // export { DEFAULT_CONFIG } from './models'
+ * ```
+ */
 export declare class File {
+    /** The file type, always 'ts' for TypeScript files */
     fileType: 'ts';
+    /** The file path for this generated file */
     path: string;
+    /** Map of module paths to re-exported symbols organized by export type */
     reExports: Map<string, Record<string, Set<string>>>;
+    /** Map of module paths to imported symbols */
     imports: Map<string, Set<string>>;
+    /** Map of definition names to their Definition objects */
     definitions: Map<string, Definition>;
+    /** Package configuration for path resolution */
     packages: ModulePackage[] | undefined;
+    /**
+     * Creates a new File instance.
+     *
+     * @param args - File configuration
+     * @param args.path - The output path for this file
+     * @param args.settings - Client settings containing package configuration
+     *
+     * @example
+     * ```typescript
+     * const file = new File({
+     *   path: './src/generated/models.ts',
+     *   settings: {
+     *     packages: [
+     *       { rootPath: './packages/shared', moduleName: '@company/shared' }
+     *     ]
+     *   }
+     * });
+     * ```
+     */
     constructor({ path, settings }: FileArgs);
+    /**
+     * Generates the complete TypeScript file content.
+     *
+     * This method orchestrates the rendering of all file components in the correct order:
+     * re-exports first, then imports, and finally definitions. It automatically handles
+     * module path normalization based on package configuration and filters out empty sections.
+     *
+     * @returns The complete TypeScript file content as a string
+     *
+     * @example Basic file generation
+     * ```typescript
+     * const file = new File({ path: './api.ts', settings: undefined });
+     *
+     * // Add some imports and definitions
+     * file.imports.set('./types', new Set(['User', 'Product']));
+     * file.definitions.set('ApiClient', someDefinition);
+     *
+     * const content = file.toString();
+     * console.log(content);
+     * // import { User, Product } from './types'
+     * //
+     * // export class ApiClient {
+     * //   // ... definition content
+     * // }
+     * ```
+     *
+     * @example With re-exports
+     * ```typescript
+     * const file = new File({ path: './index.ts', settings: undefined });
+     *
+     * file.reExports.set('./models', {
+     *   'type': new Set(['User', 'Product']),
+     *   'const': new Set(['DEFAULT_CONFIG'])
+     * });
+     *
+     * const content = file.toString();
+     * console.log(content);
+     * // export type { User, Product } from './models'
+     * // export { DEFAULT_CONFIG } from './models'
+     * ```
+     */
     toString(): string;
 }
+/**
+ * Arguments for the {@link normaliseModuleName} function.
+ */
 export type NormaliseModuleNameArgs = {
+    /** The path of the file that will contain the import/export */
     destinationPath: string;
+    /** The original path being imported/exported from */
     exportPath: string;
+    /** Package configuration for path resolution */
     packages: ModulePackage[] | undefined;
 };
+/**
+ * Normalizes module import/export paths based on package configuration.
+ *
+ * This function handles path resolution for complex project structures with multiple
+ * packages. It converts file system paths to appropriate module names based on:
+ * - Whether the destination and export paths are in the same package
+ * - Package-specific module naming conventions
+ * - Root path truncation for intra-package imports
+ *
+ * @param args - Path normalization arguments
+ * @param args.destinationPath - The path of the file that will contain the import/export
+ * @param args.exportPath - The original path being imported/exported from
+ * @param args.packages - Package configuration for path resolution (defaults to empty array)
+ * @returns The normalized module name to use in import/export statements
+ *
+ * @throws {Error} When a matching package is found but has no moduleName configured
+ *
+ * @example Cross-package import
+ * ```typescript
+ * const normalized = normaliseModuleName({
+ *   destinationPath: './packages/client/src/api.ts',
+ *   exportPath: './packages/types/models/User.ts',
+ *   packages: [
+ *     { rootPath: './packages/types', moduleName: '@company/types' },
+ *     { rootPath: './packages/client', moduleName: '@company/client' }
+ *   ]
+ * });
+ * console.log(normalized); // '@company/types'
+ * ```
+ *
+ * @example Intra-package import (same package)
+ * ```typescript
+ * const normalized = normaliseModuleName({
+ *   destinationPath: './packages/types/src/index.ts',
+ *   exportPath: './packages/types/models/User.ts',
+ *   packages: [
+ *     { rootPath: './packages/types', moduleName: '@company/types' }
+ *   ]
+ * });
+ * console.log(normalized); // '@/models/User.ts' (truncates root path)
+ * ```
+ *
+ * @example No package match (returns original path)
+ * ```typescript
+ * const normalized = normaliseModuleName({
+ *   destinationPath: './src/index.ts',
+ *   exportPath: './src/utils.ts',
+ *   packages: []
+ * });
+ * console.log(normalized); // './src/utils.ts'
+ * ```
+ */
 export declare const normaliseModuleName: ({ destinationPath, exportPath, packages }: NormaliseModuleNameArgs) => string;
 export {};
 //# sourceMappingURL=File.d.ts.map

package/script/dsl/File.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"File.d.ts","sourceRoot":"","sources":["../../src/dsl/File.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AACjD,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AAEzE,KAAK,QAAQ,GAAG;IACd,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,cAAc,GAAG,SAAS,CAAA;CACrC,CAAA;AAED,qBAAa,IAAI;IACf,QAAQ,EAAE,IAAI,CAAO;IACrB,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAA;IACnD,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAA;IACjC,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAA;IACpC,QAAQ,EAAE,aAAa,EAAE,GAAG,SAAS,CAAA;gBAEzB,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,QAAQ;IAQxC,QAAQ,IAAI,MAAM;CAkCnB;AAED,MAAM,MAAM,uBAAuB,GAAG;IACpC,eAAe,EAAE,MAAM,CAAA;IACvB,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,aAAa,EAAE,GAAG,SAAS,CAAA;CACtC,CAAA;AAED,eAAO,MAAM,mBAAmB,GAAI,2CAIjC,uBAAuB,WAqBzB,CAAA"}
+{"version":3,"file":"File.d.ts","sourceRoot":"","sources":["../../src/dsl/File.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AACjD,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AAEzE;;GAEG;AACH,KAAK,QAAQ,GAAG;IACd,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAA;IACZ,uDAAuD;IACvD,QAAQ,EAAE,cAAc,GAAG,SAAS,CAAA;CACrC,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8EG;AACH,qBAAa,IAAI;IACf,sDAAsD;IACtD,QAAQ,EAAE,IAAI,CAAO;IAErB,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAA;IAEZ,0EAA0E;IAC1E,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAA;IAEnD,8CAA8C;IAC9C,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAA;IAEjC,0DAA0D;IAC1D,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAA;IAEpC,gDAAgD;IAChD,QAAQ,EAAE,aAAa,EAAE,GAAG,SAAS,CAAA;IAErC;;;;;;;;;;;;;;;;;;OAkBG;gBACS,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,QAAQ;IAQxC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAwCG;IACH,QAAQ,IAAI,MAAM;CAkCnB;AAED;;GAEG;AACH,MAAM,MAAM,uBAAuB,GAAG;IACpC,+DAA+D;IAC/D,eAAe,EAAE,MAAM,CAAA;IACvB,qDAAqD;IACrD,UAAU,EAAE,MAAM,CAAA;IAClB,gDAAgD;IAChD,QAAQ,EAAE,aAAa,EAAE,GAAG,SAAS,CAAA;CACtC,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,eAAO,MAAM,mBAAmB,GAAI,2CAIjC,uBAAuB,KAAG,MAqB5B,CAAA"}