@skmtc/core 0.0.782 → 0.0.785

package/script/dsl/ContentBase.js

@@ -1,20 +1,98 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ContentBase = void 0;
+/**
+ * Base class for all content generators in the SKMTC DSL system.
+ *
+ * `ContentBase` provides the foundation for creating custom generators that transform
+ * OpenAPI Schema (OAS) objects into code artifacts. It handles registration with the
+ * generation context, skipping logic, and provides access to the pipeline's utilities.
+ *
+ * ## Generator Lifecycle
+ *
+ * 1. **Construction**: Initialize with context and optional generator key
+ * 2. **Registration**: Call {@link register} to add artifacts to the pipeline
+ * 3. **Generation**: Implement custom logic using context utilities
+ * 4. **Rendering**: Artifacts are automatically rendered by the pipeline
+ *
+ * @example Basic generator
+ * ```typescript
+ * import { ContentBase } from '@skmtc/core';
+ *
+ * class MyModelGenerator extends ContentBase {
+ *   generate() {
+ *     // Skip if not needed
+ *     if (this.shouldSkip()) return;
+ *
+ *     // Access OAS objects through context
+ *     const schemas = this.context.oasDocument.components.schemas;
+ *
+ *     for (const [name, schema] of Object.entries(schemas)) {
+ *       if (schema.isRef()) continue;
+ *
+ *       const file = new File({
+ *         context: this.context,
+ *         path: `./models/${name}.ts`,
+ *         content: this.generateModelContent(schema)
+ *       });
+ *
+ *       // Register the file for rendering
+ *       this.register({ file });
+ *     }
+ *   }
+ *
+ *   private generateModelContent(schema: OasObject): string {
+ *     // Custom model generation logic
+ *     return `export interface ${schema.name} { ... }`;
+ *   }
+ * }
+ * ```
+ *
+ * @example Generator with skipping logic
+ * ```typescript
+ * class ConditionalGenerator extends ContentBase {
+ *   generate() {
+ *     // Check if generation should be skipped
+ *     if (this.shouldSkipBasedOnSettings()) {
+ *       this.skip('Disabled in settings');
+ *       return;
+ *     }
+ *
+ *     // Continue with generation...
+ *     const file = this.createOutputFile();
+ *     this.register({ file });
+ *   }
+ *
+ *   private shouldSkipBasedOnSettings(): boolean {
+ *     return this.context.settings?.skip?.models?.includes('MyModel') ?? false;
+ *   }
+ * }
+ * ```
+ */
 class ContentBase {
+    /**
+     * Creates a new ContentBase instance.
+     *
+     * @param args - Construction arguments
+     * @param args.context - The generation context
+     * @param args.generatorKey - Optional generator key
+     */
     constructor({ context, generatorKey }) {
+        /** The generation context providing access to OAS objects and utilities */
         Object.defineProperty(this, "context", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /** Whether this generator has been skipped */
         Object.defineProperty(this, "skipped", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: false
         });
+        /** Optional generator key for identification and tracking */
         Object.defineProperty(this, "generatorKey", {
             enumerable: true,
             configurable: true,
@@ -24,6 +102,38 @@ class ContentBase {
         this.context = context;
         this.generatorKey = generatorKey;
     }
+    /**
+     * Registers generated artifacts with the rendering pipeline.
+     *
+     * This method is called by generator implementations to add files,
+     * JSON artifacts, or other content to the generation output.
+     *
+     * @param args - The artifacts to register
+     * @param args.file - Optional file to register
+     * @param args.jsonFile - Optional JSON file to register
+     *
+     * @example Registering a file
+     * ```typescript
+     * const file = new File({
+     *   context: this.context,
+     *   path: './output.ts',
+     *   content: 'export const value = 42;'
+     * });
+     *
+     * this.register({ file });
+     * ```
+     *
+     * @example Registering JSON data
+     * ```typescript
+     * const jsonFile = new JsonFile({
+     *   context: this.context,
+     *   path: './config.json',
+     *   data: { version: '1.0.0', features: ['api'] }
+     * });
+     *
+     * this.register({ jsonFile });
+     * ```
+     */
     register(args) {
         this.context.register(args);
     }

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"}

package/script/dsl/File.js

@@ -2,38 +2,142 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.normaliseModuleName = exports.File = void 0;
 const Import_js_1 = require("./Import.js");
+/**
+ * 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'
+ * ```
+ */
 class File {
+    /**
+     * 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 }) {
+        /** The file type, always 'ts' for TypeScript files */
         Object.defineProperty(this, "fileType", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: 'ts'
         });
+        /** The file path for this generated file */
         Object.defineProperty(this, "path", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /** Map of module paths to re-exported symbols organized by export type */
         Object.defineProperty(this, "reExports", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /** Map of module paths to imported symbols */
         Object.defineProperty(this, "imports", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /** Map of definition names to their Definition objects */
         Object.defineProperty(this, "definitions", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /** Package configuration for path resolution */
         Object.defineProperty(this, "packages", {
             enumerable: true,
             configurable: true,
@@ -46,6 +150,47 @@ class File {
         this.definitions = new Map();
         this.packages = settings?.packages;
     }
+    /**
+     * 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() {
         const reExports = Array.from(this.reExports.entries()).flatMap(([module, entityTypes]) => {
             const updatedModuleName = (0, exports.normaliseModuleName)({
@@ -76,6 +221,58 @@ class File {
     }
 }
 exports.File = File;
+/**
+ * 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'
+ * ```
+ */
 const normaliseModuleName = ({ destinationPath, exportPath, packages = [] }) => {
     const matchingModule = packages.find(packageModule => {
         return exportPath.startsWith(packageModule.rootPath);