@skmtc/core 0.0.792 → 0.0.793

package/script/helpers/generationStats.d.ts

@@ -1,26 +1,312 @@
 import "../_dnt.polyfills.js";
 import type { ManifestContent } from '../types/Manifest.js';
 import type { ResultsItem, ResultType } from '../types/Results.js';
+/**
+ * Arguments for generating comprehensive statistics from the build manifest and artifacts.
+ */
 type GenerationStatsArgs = {
+    /** The generation manifest containing build metadata and results */
     manifest: ManifestContent;
+    /** Generated artifacts as a map of file paths to content */
     artifacts: Record<string, string>;
 };
-export declare const toGenerationStats: ({ manifest, artifacts }: GenerationStatsArgs) => {
+/**
+ * Comprehensive generation statistics extracted from build artifacts and manifest.
+ */
+export type GenerationStats = {
+    /** Total number of GPT tokens in generated content */
     tokens: number;
+    /** Total number of lines generated */
     lines: number;
+    /** Total generation time in milliseconds */
     totalTime: number;
+    /** Error paths organized as nested arrays */
     errors: string[][];
+    /** Total number of generated files */
     files: number;
 };
+/**
+ * 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 declare const toGenerationStats: ({ manifest, artifacts }: GenerationStatsArgs) => GenerationStats;
+/**
+ * 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 declare const toManifestTokens: (artifacts: Record<string, string>) => number;
+/**
+ * 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 declare const toManifestLines: (manifest: ManifestContent) => number;
+/**
+ * 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 declare const toTotalTime: (manifest: ManifestContent) => number;
+/**
+ * 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 declare const toManifestErrors: (results: ManifestContent["results"]) => string[][];
+/**
+ * Arguments for recursively checking results for error conditions.
+ */
 type CheckResultArgs = {
+    /** Current path segments being traversed */
     path: string[];
+    /** The result value to check (can be nested) */
     result: ResultsItem | (ResultsItem | null)[] | ResultType;
+    /** Array to accumulate error paths (mutated) */
     errors: string[][];
 };
+/**
+ * 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 declare const checkResult: ({ path, result, errors }: CheckResultArgs) => void;
 export {};
 //# sourceMappingURL=generationStats.d.ts.map

package/script/helpers/generationStats.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generationStats.d.ts","sourceRoot":"","sources":["../../src/helpers/generationStats.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAC3D,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAA;AAIlE,KAAK,mBAAmB,GAAG;IACzB,QAAQ,EAAE,eAAe,CAAA;IACzB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAClC,CAAA;AACD,eAAO,MAAM,iBAAiB,GAAI,yBAAyB,mBAAmB,KAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,EAAE,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAcrK,CAAA;AAED,eAAO,MAAM,gBAAgB,GAAI,WAAW,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAAG,MAOpE,CAAA;AAED,eAAO,MAAM,eAAe,GAAI,UAAU,eAAe,KAAG,MAO3D,CAAA;AAED,eAAO,MAAM,WAAW,GAAI,UAAU,eAAe,KAAG,MAIvD,CAAA;AAED,eAAO,MAAM,gBAAgB,GAAI,SAAS,eAAe,CAAC,SAAS,CAAC,KAAG,MAAM,EAAE,EAQ9E,CAAA;AAED,KAAK,eAAe,GAAG;IACrB,IAAI,EAAE,MAAM,EAAE,CAAA;IACd,MAAM,EAAE,WAAW,GAAG,CAAC,WAAW,GAAG,IAAI,CAAC,EAAE,GAAG,UAAU,CAAA;IACzD,MAAM,EAAE,MAAM,EAAE,EAAE,CAAA;CACnB,CAAA;AAED,eAAO,MAAM,WAAW,GAAI,0BAA0B,eAAe,KAAG,IA0BvE,CAAA"}
+{"version":3,"file":"generationStats.d.ts","sourceRoot":"","sources":["../../src/helpers/generationStats.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAC3D,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAA;AAIlE;;GAEG;AACH,KAAK,mBAAmB,GAAG;IACzB,oEAAoE;IACpE,QAAQ,EAAE,eAAe,CAAA;IACzB,4DAA4D;IAC5D,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAClC,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,sDAAsD;IACtD,MAAM,EAAE,MAAM,CAAA;IACd,sCAAsC;IACtC,KAAK,EAAE,MAAM,CAAA;IACb,4CAA4C;IAC5C,SAAS,EAAE,MAAM,CAAA;IACjB,6CAA6C;IAC7C,MAAM,EAAE,MAAM,EAAE,EAAE,CAAA;IAClB,sCAAsC;IACtC,KAAK,EAAE,MAAM,CAAA;CACd,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqGG;AACH,eAAO,MAAM,iBAAiB,GAAI,yBAAyB,mBAAmB,KAAG,eAchF,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,gBAAgB,GAAI,WAAW,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAAG,MAOpE,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,eAAe,GAAI,UAAU,eAAe,KAAG,MAO3D,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,WAAW,GAAI,UAAU,eAAe,KAAG,MAIvD,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,gBAAgB,GAAI,SAAS,eAAe,CAAC,SAAS,CAAC,KAAG,MAAM,EAAE,EAQ9E,CAAA;AAED;;GAEG;AACH,KAAK,eAAe,GAAG;IACrB,4CAA4C;IAC5C,IAAI,EAAE,MAAM,EAAE,CAAA;IACd,gDAAgD;IAChD,MAAM,EAAE,WAAW,GAAG,CAAC,WAAW,GAAG,IAAI,CAAC,EAAE,GAAG,UAAU,CAAA;IACzD,gDAAgD;IAChD,MAAM,EAAE,MAAM,EAAE,EAAE,CAAA;CACnB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AACH,eAAO,MAAM,WAAW,GAAI,0BAA0B,eAAe,KAAG,IA0BvE,CAAA"}

package/script/helpers/generationStats.js

@@ -4,6 +4,108 @@ exports.checkResult = exports.toManifestErrors = exports.toTotalTime = exports.t
 require("../_dnt.polyfills.js");
 const ts_pattern_1 = require("ts-pattern");
 const gpt_tokenizer_1 = require("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();
+ * }
+ * ```
+ */
 const toGenerationStats = ({ manifest, artifacts }) => {
     const tokens = (0, exports.toManifestTokens)(artifacts);
     const lines = (0, exports.toManifestLines)(manifest);
@@ -19,21 +121,121 @@ const toGenerationStats = ({ manifest, artifacts }) => {
     };
 };
 exports.toGenerationStats = toGenerationStats;
+/**
+ * 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
+ * ```
+ */
 const toManifestTokens = (artifacts) => {
     const { tokens } = Object.values(artifacts).reduce((acc, artifact) => ({ tokens: acc.tokens + (0, gpt_tokenizer_1.countTokens)(artifact) }), { tokens: 0 });
     return tokens;
 };
 exports.toManifestTokens = toManifestTokens;
+/**
+ * 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
+ * ```
+ */
 const toManifestLines = (manifest) => {
     const { lines } = Object.values(manifest.files).reduce((acc, file) => ({ lines: acc.lines + file.lines }), { lines: 0 });
     return lines;
 };
 exports.toManifestLines = toManifestLines;
+/**
+ * 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"
+ * ```
+ */
 const toTotalTime = (manifest) => {
     const totalTime = manifest.endAt - manifest.startAt;
     return totalTime;
 };
 exports.toTotalTime = toTotalTime;
+/**
+ * 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"
+ * ```
+ */
 const toManifestErrors = (results) => {
     const errors = [];
     Object.entries(results).map(([path, result]) => {
@@ -42,6 +244,70 @@ const toManifestErrors = (results) => {
     return errors;
 };
 exports.toManifestErrors = toManifestErrors;
+/**
+ * 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
+ * ```
+ */
 const checkResult = ({ path, result, errors }) => {
     (0, ts_pattern_1.match)(result)
         .with(ts_pattern_1.P.array(), matchedResult => {

package/script/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/script/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"}