@skmtc/core 0.0.782 → 0.0.785

package/esm/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/esm/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/esm/dsl/File.js

@@ -1,36 +1,140 @@
 import { Import } from './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'
+ * ```
+ */
 export 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,
@@ -43,6 +147,47 @@ export 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 = normaliseModuleName({
@@ -72,6 +217,58 @@ export class File {
             .join('\n\n');
     }
 }
+/**
+ * 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 const normaliseModuleName = ({ destinationPath, exportPath, packages = [] }) => {
     const matchingModule = packages.find(packageModule => {
         return exportPath.startsWith(packageModule.rootPath);