@skmtc/core 0.0.792 → 0.0.794

package/esm/helpers/generationStats.js

@@ -1,6 +1,108 @@
 import "../_dnt.polyfills.js";
 import { match, P } from 'ts-pattern';
 import { countTokens } from 'gpt-tokenizer';
+/**
+ * Generates comprehensive statistics about the code generation process.
+ *
+ * This function analyzes the generation manifest and produced artifacts to create
+ * detailed statistics including token counts, lines of code, timing information,
+ * error tracking, and file counts. It's used for performance monitoring, debugging,
+ * and reporting on generation runs.
+ *
+ * The function combines multiple analysis methods to provide a complete picture
+ * of the generation process, including tokenization analysis for cost estimation,
+ * error path extraction for debugging, and timing analysis for performance optimization.
+ *
+ * @param args - Generation analysis configuration
+ * @param args.manifest - The generation manifest with metadata and results
+ * @param args.artifacts - Map of file paths to generated content
+ * @returns Comprehensive generation statistics object
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { toGenerationStats } from '@skmtc/core';
+ *
+ * const stats = toGenerationStats({
+ *   manifest: {
+ *     startAt: 1672531200000,
+ *     endAt: 1672531245000,
+ *     files: {
+ *       './models.ts': { lines: 150, characters: 4500 },
+ *       './types.ts': { lines: 80, characters: 2100 }
+ *     },
+ *     results: { }
+ *   },
+ *   artifacts: {
+ *     './models.ts': 'export interface User { id: string; name: string; }',
+ *     './types.ts': 'export type Status = "active" | "inactive";'
+ *   }
+ * });
+ *
+ * console.log(stats);
+ * // {
+ * //   tokens: 250,
+ * //   lines: 230,
+ * //   totalTime: 45000,
+ * //   errors: [],
+ * //   files: 2
+ * // }
+ * ```
+ *
+ * @example Performance monitoring
+ * ```typescript
+ * class GenerationMonitor {
+ *   analyzeGeneration(manifest: ManifestContent, artifacts: Record<string, string>) {
+ *     const stats = toGenerationStats({ manifest, artifacts });
+ *
+ *     console.log(`Generation completed in ${stats.totalTime}ms`);
+ *     console.log(`Generated ${stats.files} files with ${stats.lines} lines`);
+ *     console.log(`Token usage: ${stats.tokens} tokens`);
+ *
+ *     if (stats.errors.length > 0) {
+ *       console.warn(`Found ${stats.errors.length} errors:`);
+ *       stats.errors.forEach((errorPath, index) => {
+ *         console.warn(`  ${index + 1}. ${errorPath.join(' -> ')}`);
+ *       });
+ *     }
+ *
+ *     return stats;
+ *   }
+ * }
+ * ```
+ *
+ * @example Cost estimation
+ * ```typescript
+ * function estimateGenerationCost(stats: GenerationStats): number {
+ *   const tokensPerDollar = 1000000; // Example rate
+ *   const estimatedCost = stats.tokens / tokensPerDollar;
+ *
+ *   console.log(`Estimated cost: $${estimatedCost.toFixed(4)}`);
+ *   console.log(`Efficiency: ${stats.lines / stats.tokens} lines per token`);
+ *
+ *   return estimatedCost;
+ * }
+ * ```
+ *
+ * @example Build reporting
+ * ```typescript
+ * function generateBuildReport(stats: GenerationStats): string {
+ *   const efficiency = stats.totalTime / stats.files;
+ *   const successRate = ((stats.files - stats.errors.length) / stats.files * 100).toFixed(1);
+ *
+ *   return `
+ * Build Report:
+ * -----------
+ * Files Generated: ${stats.files}
+ * Total Lines: ${stats.lines.toLocaleString()}
+ * Token Count: ${stats.tokens.toLocaleString()}
+ * Generation Time: ${(stats.totalTime / 1000).toFixed(2)}s
+ * Average per File: ${efficiency.toFixed(0)}ms
+ * Success Rate: ${successRate}%
+ * Errors: ${stats.errors.length}
+ *   `.trim();
+ * }
+ * ```
+ */
 export const toGenerationStats = ({ manifest, artifacts }) => {
     const tokens = toManifestTokens(artifacts);
     const lines = toManifestLines(manifest);
@@ -15,18 +117,118 @@ export const toGenerationStats = ({ manifest, artifacts }) => {
         files
     };
 };
+/**
+ * Calculates the total number of GPT tokens in all generated artifacts.
+ *
+ * This function uses GPT tokenization to count the total number of tokens
+ * across all generated code artifacts. This is useful for cost estimation
+ * when using token-based pricing models and for understanding the size
+ * and complexity of generated content.
+ *
+ * @param artifacts - Map of file paths to generated content strings
+ * @returns Total number of GPT tokens across all artifacts
+ *
+ * @example
+ * ```typescript
+ * const artifacts = {
+ *   './models.ts': 'export interface User { id: string; name: string; }',
+ *   './types.ts': 'export type Status = "active" | "inactive";'
+ * };
+ *
+ * const tokens = toManifestTokens(artifacts);
+ * console.log(tokens); // e.g., 24 tokens
+ * ```
+ */
 export const toManifestTokens = (artifacts) => {
     const { tokens } = Object.values(artifacts).reduce((acc, artifact) => ({ tokens: acc.tokens + countTokens(artifact) }), { tokens: 0 });
     return tokens;
 };
+/**
+ * Calculates the total number of lines across all generated files.
+ *
+ * This function sums up the line counts from the manifest's file metadata
+ * to provide the total lines of code generated. This metric is useful
+ * for understanding the scale of code generation and tracking productivity.
+ *
+ * @param manifest - The generation manifest containing file metadata
+ * @returns Total number of lines across all generated files
+ *
+ * @example
+ * ```typescript
+ * const manifest = {
+ *   files: {
+ *     './models.ts': { lines: 150, characters: 4500 },
+ *     './types.ts': { lines: 80, characters: 2100 }
+ *   },
+ *   // ... other manifest properties
+ * };
+ *
+ * const lines = toManifestLines(manifest);
+ * console.log(lines); // 230
+ * ```
+ */
 export const toManifestLines = (manifest) => {
     const { lines } = Object.values(manifest.files).reduce((acc, file) => ({ lines: acc.lines + file.lines }), { lines: 0 });
     return lines;
 };
+/**
+ * Calculates the total generation time from the manifest timestamps.
+ *
+ * This function computes the duration of the generation process by
+ * calculating the difference between the end and start timestamps
+ * recorded in the manifest. The result is in milliseconds.
+ *
+ * @param manifest - The generation manifest with timing information
+ * @returns Total generation time in milliseconds
+ *
+ * @example
+ * ```typescript
+ * const manifest = {
+ *   startAt: 1672531200000, // January 1, 2023 00:00:00 GMT
+ *   endAt: 1672531245000,   // January 1, 2023 00:00:45 GMT
+ *   // ... other manifest properties
+ * };
+ *
+ * const duration = toTotalTime(manifest);
+ * console.log(duration); // 45000 (45 seconds)
+ * console.log(`${duration / 1000}s`); // "45s"
+ * ```
+ */
 export const toTotalTime = (manifest) => {
     const totalTime = manifest.endAt - manifest.startAt;
     return totalTime;
 };
+/**
+ * Extracts and organizes error paths from the manifest results.
+ *
+ * This function recursively traverses the results structure in the manifest
+ * to identify all error conditions and their associated file paths. Errors
+ * are returned as arrays of path segments, making it easy to understand
+ * the location and context of each error.
+ *
+ * @param results - The results object from the generation manifest
+ * @returns Array of error paths, each represented as an array of path segments
+ *
+ * @example
+ * ```typescript
+ * const results = {
+ *   'models.ts': {
+ *     'User': 'success',
+ *     'Product': 'error'
+ *   },
+ *   'types.ts': 'success'
+ * };
+ *
+ * const errors = toManifestErrors(results);
+ * console.log(errors); // [['models.ts', 'Product']]
+ *
+ * // Display errors in readable format
+ * errors.forEach(errorPath => {
+ *   console.log(`Error at: ${errorPath.join(' -> ')}`);
+ * });
+ * // Output: "Error at: models.ts -> Product"
+ * ```
+ */
 export const toManifestErrors = (results) => {
     const errors = [];
     Object.entries(results).map(([path, result]) => {
@@ -34,6 +236,70 @@ export const toManifestErrors = (results) => {
     });
     return errors;
 };
+/**
+ * Recursively checks results structure for error conditions and collects error paths.
+ *
+ * This function traverses the complex nested structure of generation results,
+ * identifying error conditions at any level and recording their full path context.
+ * It handles arrays, objects, strings, and null values, building a comprehensive
+ * map of all errors that occurred during generation.
+ *
+ * The function mutates the errors array parameter, accumulating error paths
+ * as it traverses the results structure. This approach is used for performance
+ * when processing large result sets.
+ *
+ * @param args - Arguments for result checking
+ * @param args.path - Current path segments being traversed
+ * @param args.result - The result value to check for errors
+ * @param args.errors - Array to accumulate error paths (mutated by function)
+ *
+ * @example Simple error detection
+ * ```typescript
+ * const errors: string[][] = [];
+ *
+ * checkResult({
+ *   path: ['models.ts'],
+ *   result: 'error',
+ *   errors
+ * });
+ *
+ * console.log(errors); // [['models.ts']]
+ * ```
+ *
+ * @example Nested structure error detection
+ * ```typescript
+ * const errors: string[][] = [];
+ * const nestedResult = {
+ *   'User': 'success',
+ *   'Product': {
+ *     'validation': 'error',
+ *     'generation': 'success'
+ *   }
+ * };
+ *
+ * checkResult({
+ *   path: ['models.ts'],
+ *   result: nestedResult,
+ *   errors
+ * });
+ *
+ * console.log(errors); // [['models.ts', 'Product', 'validation']]
+ * ```
+ *
+ * @example Array handling
+ * ```typescript
+ * const errors: string[][] = [];
+ * const arrayResult = ['success', null, 'error', 'success'];
+ *
+ * checkResult({
+ *   path: ['batch'],
+ *   result: arrayResult,
+ *   errors
+ * });
+ *
+ * console.log(errors); // [['batch']] - for the 'error' item
+ * ```
+ */
 export const checkResult = ({ path, result, errors }) => {
     match(result)
         .with(P.array(), matchedResult => {

package/esm/helpers/isEmpty.d.ts

@@ -1,3 +1,65 @@
+/**
+ * Checks whether a record/object is empty (has no enumerable properties).
+ *
+ * This utility function determines if an object contains any enumerable properties
+ * by checking the length of its keys array. It's commonly used throughout the
+ * SKMTC codebase to validate whether generated objects, configurations, or
+ * other data structures contain meaningful content.
+ *
+ * @param value - The record/object to check for emptiness
+ * @returns `true` if the object has no enumerable properties, `false` otherwise
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { isEmpty } from '@skmtc/core';
+ *
+ * console.log(isEmpty({})); // true
+ * console.log(isEmpty({ name: 'John' })); // false
+ * console.log(isEmpty({ a: undefined })); // false (undefined is still a property)
+ * ```
+ *
+ * @example In conditional logic
+ * ```typescript
+ * const userPreferences = loadUserPreferences();
+ *
+ * if (isEmpty(userPreferences)) {
+ *   // Apply default settings
+ *   applyDefaults();
+ * } else {
+ *   // Use user's custom settings
+ *   applyUserSettings(userPreferences);
+ * }
+ * ```
+ *
+ * @example Filtering collections
+ * ```typescript
+ * const configurations = [
+ *   { api: 'v1', settings: {} },
+ *   { api: 'v2', settings: { timeout: 5000 } },
+ *   { api: 'v3', settings: {} }
+ * ];
+ *
+ * const validConfigs = configurations.filter(config => !isEmpty(config.settings));
+ * console.log(validConfigs); // [{ api: 'v2', settings: { timeout: 5000 } }]
+ * ```
+ *
+ * @example Code generation usage
+ * ```typescript
+ * class Generator {
+ *   generateInterface(properties: Record<string, string>) {
+ *     if (isEmpty(properties)) {
+ *       return 'interface EmptyInterface {}';
+ *     }
+ *
+ *     const props = Object.entries(properties)
+ *       .map(([name, type]) => `  ${name}: ${type};`)
+ *       .join('\n');
+ *
+ *     return `interface GeneratedInterface {\n${props}\n}`;
+ *   }
+ * }
+ * ```
+ */
 import "../_dnt.polyfills.js";
 export declare const isEmpty: (value: Record<string, any>) => boolean;
 //# sourceMappingURL=isEmpty.d.ts.map

package/esm/helpers/isEmpty.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"isEmpty.d.ts","sourceRoot":"","sources":["../../src/helpers/isEmpty.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAC9B,eAAO,MAAM,OAAO,GAAI,OAAO,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KAAG,OAEpD,CAAA"}
+{"version":3,"file":"isEmpty.d.ts","sourceRoot":"","sources":["../../src/helpers/isEmpty.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AACH,OAAO,sBAAsB,CAAC;AAE9B,eAAO,MAAM,OAAO,GAAI,OAAO,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KAAG,OAEpD,CAAA"}

package/esm/helpers/isEmpty.js

@@ -1,3 +1,65 @@
+/**
+ * Checks whether a record/object is empty (has no enumerable properties).
+ *
+ * This utility function determines if an object contains any enumerable properties
+ * by checking the length of its keys array. It's commonly used throughout the
+ * SKMTC codebase to validate whether generated objects, configurations, or
+ * other data structures contain meaningful content.
+ *
+ * @param value - The record/object to check for emptiness
+ * @returns `true` if the object has no enumerable properties, `false` otherwise
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { isEmpty } from '@skmtc/core';
+ *
+ * console.log(isEmpty({})); // true
+ * console.log(isEmpty({ name: 'John' })); // false
+ * console.log(isEmpty({ a: undefined })); // false (undefined is still a property)
+ * ```
+ *
+ * @example In conditional logic
+ * ```typescript
+ * const userPreferences = loadUserPreferences();
+ *
+ * if (isEmpty(userPreferences)) {
+ *   // Apply default settings
+ *   applyDefaults();
+ * } else {
+ *   // Use user's custom settings
+ *   applyUserSettings(userPreferences);
+ * }
+ * ```
+ *
+ * @example Filtering collections
+ * ```typescript
+ * const configurations = [
+ *   { api: 'v1', settings: {} },
+ *   { api: 'v2', settings: { timeout: 5000 } },
+ *   { api: 'v3', settings: {} }
+ * ];
+ *
+ * const validConfigs = configurations.filter(config => !isEmpty(config.settings));
+ * console.log(validConfigs); // [{ api: 'v2', settings: { timeout: 5000 } }]
+ * ```
+ *
+ * @example Code generation usage
+ * ```typescript
+ * class Generator {
+ *   generateInterface(properties: Record<string, string>) {
+ *     if (isEmpty(properties)) {
+ *       return 'interface EmptyInterface {}';
+ *     }
+ *
+ *     const props = Object.entries(properties)
+ *       .map(([name, type]) => `  ${name}: ${type};`)
+ *       .join('\n');
+ *
+ *     return `interface GeneratedInterface {\n${props}\n}`;
+ *   }
+ * }
+ * ```
+ */
 import "../_dnt.polyfills.js";
 export const isEmpty = (value) => {
     return Object.keys(value).length === 0;

package/esm/helpers/isImported.d.ts

@@ -1,2 +1,82 @@
+/**
+ * Determines whether two file paths represent different locations (import required).
+ *
+ * This utility function normalizes two file paths and compares them to determine
+ * if they represent different files. It's used throughout the SKMTC system to
+ * decide when import statements are needed - if two paths are different, an
+ * import is required to access symbols from one file in another.
+ *
+ * The function handles path normalization to ensure consistent comparisons
+ * across different operating systems and path formats (handling './' vs absolute
+ * paths, different separators, etc.).
+ *
+ * @param pathOne - The first file path to compare
+ * @param pathTwo - The second file path to compare
+ * @returns `true` if the paths are different (import needed), `false` if they're the same file
+ *
+ * @example Basic path comparison
+ * ```typescript
+ * import { isImported } from '@skmtc/core';
+ *
+ * // Same file, no import needed
+ * console.log(isImported('./src/user.ts', './src/user.ts')); // false
+ *
+ * // Different files, import needed
+ * console.log(isImported('./src/user.ts', './src/product.ts')); // true
+ * ```
+ *
+ * @example Path normalization handling
+ * ```typescript
+ * // These all represent the same file after normalization
+ * console.log(isImported('./src/user.ts', 'src/user.ts')); // false
+ * console.log(isImported('src/./user.ts', 'src/user.ts')); // false
+ * console.log(isImported('src/models/../user.ts', 'src/user.ts')); // false
+ * ```
+ *
+ * @example Usage in import decision logic
+ * ```typescript
+ * class FileGenerator {
+ *   addImportIfNeeded(
+ *     sourceFile: string,
+ *     targetFile: string,
+ *     importName: string
+ *   ) {
+ *     if (isImported(sourceFile, targetFile)) {
+ *       // Files are different, add import
+ *       this.addImport(sourceFile, targetFile, importName);
+ *       console.log(`Added import: ${importName} from ${targetFile}`);
+ *     } else {
+ *       // Same file, no import needed
+ *       console.log(`No import needed - same file: ${sourceFile}`);
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @example Cross-platform path handling
+ * ```typescript
+ * // Works consistently across platforms
+ * const windowsPath = 'src\\models\\user.ts';
+ * const unixPath = 'src/models/user.ts';
+ *
+ * console.log(isImported(windowsPath, unixPath)); // false (same file)
+ * ```
+ *
+ * @example In generator context
+ * ```typescript
+ * class ModelGenerator {
+ *   generateModel(modelPath: string, referencePath: string) {
+ *     const definition = this.createModelDefinition();
+ *
+ *     if (isImported(modelPath, referencePath)) {
+ *       // Need to import the referenced model
+ *       definition.addImport(referencePath, 'ReferencedModel');
+ *     }
+ *
+ *     return definition;
+ *   }
+ * }
+ * ```
+ */
 export declare const isImported: (pathOne: string, pathTwo: string) => boolean;
 //# sourceMappingURL=isImported.d.ts.map

package/esm/helpers/isImported.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"isImported.d.ts","sourceRoot":"","sources":["../../src/helpers/isImported.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,UAAU,GAAI,SAAS,MAAM,EAAE,SAAS,MAAM,KAAG,OAE7D,CAAA"}
+{"version":3,"file":"isImported.d.ts","sourceRoot":"","sources":["../../src/helpers/isImported.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+EG;AACH,eAAO,MAAM,UAAU,GAAI,SAAS,MAAM,EAAE,SAAS,MAAM,KAAG,OAE7D,CAAA"}

package/esm/helpers/isImported.js

@@ -1,4 +1,84 @@
 import { normalize } from '../deps/jsr.io/@std/path/1.1.2/normalize.js';
+/**
+ * Determines whether two file paths represent different locations (import required).
+ *
+ * This utility function normalizes two file paths and compares them to determine
+ * if they represent different files. It's used throughout the SKMTC system to
+ * decide when import statements are needed - if two paths are different, an
+ * import is required to access symbols from one file in another.
+ *
+ * The function handles path normalization to ensure consistent comparisons
+ * across different operating systems and path formats (handling './' vs absolute
+ * paths, different separators, etc.).
+ *
+ * @param pathOne - The first file path to compare
+ * @param pathTwo - The second file path to compare
+ * @returns `true` if the paths are different (import needed), `false` if they're the same file
+ *
+ * @example Basic path comparison
+ * ```typescript
+ * import { isImported } from '@skmtc/core';
+ *
+ * // Same file, no import needed
+ * console.log(isImported('./src/user.ts', './src/user.ts')); // false
+ *
+ * // Different files, import needed
+ * console.log(isImported('./src/user.ts', './src/product.ts')); // true
+ * ```
+ *
+ * @example Path normalization handling
+ * ```typescript
+ * // These all represent the same file after normalization
+ * console.log(isImported('./src/user.ts', 'src/user.ts')); // false
+ * console.log(isImported('src/./user.ts', 'src/user.ts')); // false
+ * console.log(isImported('src/models/../user.ts', 'src/user.ts')); // false
+ * ```
+ *
+ * @example Usage in import decision logic
+ * ```typescript
+ * class FileGenerator {
+ *   addImportIfNeeded(
+ *     sourceFile: string,
+ *     targetFile: string,
+ *     importName: string
+ *   ) {
+ *     if (isImported(sourceFile, targetFile)) {
+ *       // Files are different, add import
+ *       this.addImport(sourceFile, targetFile, importName);
+ *       console.log(`Added import: ${importName} from ${targetFile}`);
+ *     } else {
+ *       // Same file, no import needed
+ *       console.log(`No import needed - same file: ${sourceFile}`);
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @example Cross-platform path handling
+ * ```typescript
+ * // Works consistently across platforms
+ * const windowsPath = 'src\\models\\user.ts';
+ * const unixPath = 'src/models/user.ts';
+ *
+ * console.log(isImported(windowsPath, unixPath)); // false (same file)
+ * ```
+ *
+ * @example In generator context
+ * ```typescript
+ * class ModelGenerator {
+ *   generateModel(modelPath: string, referencePath: string) {
+ *     const definition = this.createModelDefinition();
+ *
+ *     if (isImported(modelPath, referencePath)) {
+ *       // Need to import the referenced model
+ *       definition.addImport(referencePath, 'ReferencedModel');
+ *     }
+ *
+ *     return definition;
+ *   }
+ * }
+ * ```
+ */
 export const isImported = (pathOne, pathTwo) => {
     return normalize(pathOne) !== normalize(pathTwo);
 };