timonel 3.1.1 → 3.1.2

package/dist/lib/utils/helmHelpers/index.js

@@ -1,3 +1,8 @@
+/**
+ * @fileoverview Main index file for Helm helpers with organized exports and helper management functions
+ * @since 2.11.0
+ */
+// Export all helper categories
 export { ENV_HELPERS } from './envHelpers.js';
 export { GITOPS_HELPERS } from './gitopsHelpers.js';
 export { OBSERVABILITY_HELPERS } from './observabilityHelpers.js';
@@ -6,23 +11,49 @@ import { ENV_HELPERS } from './envHelpers.js';
 import { GITOPS_HELPERS } from './gitopsHelpers.js';
 import { OBSERVABILITY_HELPERS } from './observabilityHelpers.js';
 import { VALIDATION_HELPERS } from './validationHelpers.js';
+/**
+ * Performance-optimized helper management using Map for O(1) lookups
+ * @since 2.11.0
+ */
 const HELPER_CATEGORIES = new Map([
     ['env', ENV_HELPERS],
     ['gitops', GITOPS_HELPERS],
     ['observability', OBSERVABILITY_HELPERS],
     ['validation', VALIDATION_HELPERS],
 ]);
+/**
+ * Cached helper compilation for better performance
+ * @since 2.11.0
+ */
 const COMPILED_HELPERS_CACHE = new Map();
+/**
+ * Performance-optimized helper lookup with O(1) time complexity
+ * @param category - Helper category to retrieve
+ * @returns Array of helper definitions for the specified category
+ * @throws {Error} If category is unknown
+ * @since 2.11.0
+ */
 export function getNewHelpersByCategory(category) {
     const helpers = HELPER_CATEGORIES.get(category);
     if (!helpers) {
         throw new Error(`Unknown helper category: ${category}`);
     }
-    return [...helpers];
+    return [...helpers]; // Return copy to prevent mutations
 }
+/**
+ * Get all available new helper categories
+ * @returns Array of available helper categories
+ * @since 2.11.0
+ */
 export function getAvailableHelperCategories() {
     return Array.from(HELPER_CATEGORIES.keys());
 }
+/**
+ * Get helpers for multiple categories
+ * @param categories - Array of categories to retrieve
+ * @returns Combined array of helper definitions
+ * @since 2.11.0
+ */
 export function getHelpersByCategories(categories) {
     const helpers = [];
     for (const category of categories) {
@@ -30,6 +61,12 @@ export function getHelpersByCategories(categories) {
     }
     return helpers;
 }
+/**
+ * Get helpers based on options configuration
+ * @param options - Configuration options for helper inclusion
+ * @returns Array of helper definitions based on options
+ * @since 2.11.0
+ */
 export function getHelpersByOptions(options) {
     const helpers = [];
     if (options.includeEnv) {
@@ -46,6 +83,12 @@ export function getHelpersByOptions(options) {
     }
     return helpers;
 }
+/**
+ * Converts helper definitions to Helm template format
+ * @param helpers - Array of helper definitions
+ * @returns Formatted Helm template string
+ * @since 2.11.0
+ */
 export function formatNewHelpers(helpers) {
     return helpers
         .map((helper) => `{{/*
@@ -56,6 +99,13 @@ ${helper.template}
 {{- end }}`)
         .join('\n\n');
 }
+/**
+ * Generates complete _helpers.tpl content with new helpers
+ * @param options - Configuration options for helper inclusion
+ * @param customHelpers - Additional custom helpers
+ * @returns Complete helpers template content
+ * @since 2.11.0
+ */
 export function generateNewHelpersTemplate(options, customHelpers) {
     const helpers = [];
     if (options) {
@@ -66,6 +116,13 @@ export function generateNewHelpersTemplate(options, customHelpers) {
     }
     return formatNewHelpers(helpers);
 }
+/**
+ * Cached helper compilation for better performance
+ * @param options - Configuration options for helper inclusion
+ * @param customHelpers - Additional custom helpers
+ * @returns Complete helpers template content from cache or newly generated
+ * @since 2.11.0
+ */
 export function getCachedNewHelpersTemplate(options, customHelpers) {
     const cacheKey = JSON.stringify({ options, customHelpers });
     if (COMPILED_HELPERS_CACHE.has(cacheKey)) {
@@ -75,9 +132,22 @@ export function getCachedNewHelpersTemplate(options, customHelpers) {
     COMPILED_HELPERS_CACHE.set(cacheKey, template);
     return template;
 }
+/**
+ * Creates a custom helper definition
+ * @param name - Helper name
+ * @param template - Helper template content
+ * @returns Helper definition object
+ * @since 2.11.0
+ */
 export function createNewHelper(name, template) {
     return { name, template };
 }
+/**
+ * Validates helper names for Helm compatibility
+ * @param helpers - Array of helper definitions to validate
+ * @throws {Error} If any helper has an invalid name
+ * @since 2.11.0
+ */
 export function validateHelperNames(helpers) {
     const namePattern = /^[a-zA-Z][a-zA-Z0-9._-]*$/;
     const duplicates = new Set();
@@ -97,10 +167,24 @@ export function validateHelperNames(helpers) {
         throw new Error(`Duplicate helper names found: ${Array.from(duplicates).join(', ')}`);
     }
 }
+/**
+ * Filters helpers by name pattern
+ * @param helpers - Array of helper definitions to filter
+ * @param pattern - RegExp pattern to match against helper names
+ * @returns Filtered array of helper definitions
+ * @since 2.11.0
+ */
 export function filterHelpersByPattern(helpers, pattern) {
     return helpers.filter((helper) => pattern.test(helper.name));
 }
+/**
+ * Gets helper statistics for analysis
+ * @param helpers - Array of helper definitions to analyze
+ * @returns Statistics about the helpers
+ * @since 2.11.0
+ */
 export function getHelperStatistics(helpers) {
+    // Use Map to avoid security issues with object injection
     const categoryMap = new Map();
     let totalTemplateLength = 0;
     let longestHelper = '';

package/dist/lib/utils/helmHelpers/observabilityHelpers.d.ts

@@ -1,2 +1,15 @@
+/**
+ * @fileoverview Observability helpers for Helm templates including monitoring, tracing, and logging
+ * @since 2.11.0
+ */
 import type { HelperDefinition } from './types.js';
+/**
+ * Observability helpers for monitoring, tracing, and logging
+ *
+ * These helpers provide comprehensive observability patterns for modern cloud-native applications.
+ * They support Prometheus monitoring, distributed tracing, structured logging, and health checks
+ * following industry best practices for production workloads.
+ *
+ * @since 2.11.0
+ */
 export declare const OBSERVABILITY_HELPERS: HelperDefinition[];

package/dist/lib/utils/helmHelpers/observabilityHelpers.js

@@ -1,3 +1,16 @@
+/**
+ * @fileoverview Observability helpers for Helm templates including monitoring, tracing, and logging
+ * @since 2.11.0
+ */
+/**
+ * Observability helpers for monitoring, tracing, and logging
+ *
+ * These helpers provide comprehensive observability patterns for modern cloud-native applications.
+ * They support Prometheus monitoring, distributed tracing, structured logging, and health checks
+ * following industry best practices for production workloads.
+ *
+ * @since 2.11.0
+ */
 export const OBSERVABILITY_HELPERS = [
     {
         name: 'monitoring.serviceMonitor',

package/dist/lib/utils/helmHelpers/types.d.ts

@@ -1,9 +1,32 @@
+/**
+ * @fileoverview Base types and interfaces for Helm helpers
+ * @since 2.11.0
+ */
+/**
+ * Helper definition for Helm templates
+ * @interface HelperDefinition
+ * @since 2.8.0+
+ */
 export interface HelperDefinition {
+    /** Helper name (without quotes or hyphens) */
     name: string;
+    /** Helper template content */
     template: string;
 }
+/**
+ * Helper categories for organization and filtering
+ * @since 2.11.0
+ */
 export type HelperCategory = 'standard' | 'fileAccess' | 'templateFunction' | 'sprig' | 'kubernetes' | 'aws' | 'env' | 'gitops' | 'observability' | 'validation';
+/**
+ * Cloud provider types for helper selection
+ * @since 2.11.0
+ */
 export type CloudProvider = 'aws' | 'azure' | 'gcp';
+/**
+ * Options for helper inclusion and configuration
+ * @since 2.11.0
+ */
 export interface HelperOptions {
     includeFileAccess?: boolean;
     includeTemplateFunction?: boolean;

package/dist/lib/utils/helmHelpers/types.js

@@ -1 +1,5 @@
+/**
+ * @fileoverview Base types and interfaces for Helm helpers
+ * @since 2.11.0
+ */
 export {};

package/dist/lib/utils/helmHelpers/validationHelpers.d.ts

@@ -1,2 +1,15 @@
+/**
+ * @fileoverview Validation helpers for Helm templates with type safety and format validation
+ * @since 2.11.0
+ */
 import type { HelperDefinition } from './types.js';
+/**
+ * Validation helpers for type safety and format validation
+ *
+ * These helpers provide comprehensive validation for common data types and formats
+ * used in Kubernetes and cloud-native applications. They follow security best practices
+ * and provide clear error messages for debugging and troubleshooting.
+ *
+ * @since 2.11.0
+ */
 export declare const VALIDATION_HELPERS: HelperDefinition[];

package/dist/lib/utils/helmHelpers/validationHelpers.js

@@ -1,3 +1,16 @@
+/**
+ * @fileoverview Validation helpers for Helm templates with type safety and format validation
+ * @since 2.11.0
+ */
+/**
+ * Validation helpers for type safety and format validation
+ *
+ * These helpers provide comprehensive validation for common data types and formats
+ * used in Kubernetes and cloud-native applications. They follow security best practices
+ * and provide clear error messages for debugging and troubleshooting.
+ *
+ * @since 2.11.0
+ */
 export const VALIDATION_HELPERS = [
     {
         name: 'validation.semver',

package/dist/lib/utils/helmHelpers.d.ts

@@ -1,12 +1,53 @@
+/**
+ * @fileoverview Helm chart helpers and templates
+ * @since 2.8.0+
+ */
 import type { HelperDefinition } from './helmHelpers/types.js';
 export type { HelperDefinition } from './helmHelpers/types.js';
+/**
+ * Standard Helm chart helpers following best practices
+ * @since 2.8.0+
+ */
 export declare const STANDARD_HELPERS: HelperDefinition[];
+/**
+ * File access helpers using Helm .Files object
+ * @since 2.8.4+
+ */
 export declare const FILE_ACCESS_HELPERS: HelperDefinition[];
+/**
+ * Advanced template function helpers
+ * @since 2.8.4+
+ */
 export declare const TEMPLATE_FUNCTION_HELPERS: HelperDefinition[];
+/**
+ * Sprig library function helpers for common use cases
+ * @since 2.8.4+
+ */
 export declare const SPRIG_HELPERS: HelperDefinition[];
+/**
+ * Kubernetes-specific helpers for common patterns
+ * @since 2.8.4+
+ */
 export declare const KUBERNETES_HELPERS: HelperDefinition[];
+/**
+ * AWS-specific Helm helpers
+ * @since 2.8.0+
+ */
 export declare const AWS_HELPERS: HelperDefinition[];
+/**
+ * Converts helper definitions to Helm template format
+ * @param helpers - Array of helper definitions
+ * @returns Formatted Helm template string
+ * @since 2.8.0+
+ */
 export declare function formatHelpers(helpers: HelperDefinition[]): string;
+/**
+ * Gets default helpers based on cloud provider and feature flags
+ * @param cloudProvider - Target cloud provider
+ * @param options - Configuration options for helper inclusion
+ * @returns Combined standard and cloud-specific helpers
+ * @since 2.8.4+
+ */
 export declare function getDefaultHelpers(cloudProvider?: 'aws', options?: {
     includeFileAccess?: boolean;
     includeTemplateFunction?: boolean;
@@ -17,6 +58,14 @@ export declare function getDefaultHelpers(cloudProvider?: 'aws', options?: {
     includeObservability?: boolean;
     includeValidation?: boolean;
 }): HelperDefinition[];
+/**
+ * Generates complete _helpers.tpl content
+ * @param cloudProvider - Optional cloud provider for specific helpers
+ * @param customHelpers - Additional custom helpers
+ * @param options - Configuration options for helper inclusion
+ * @returns Complete helpers template content
+ * @since 2.8.4+
+ */
 export declare function generateHelpersTemplate(cloudProvider?: 'aws', customHelpers?: HelperDefinition[], options?: {
     includeFileAccess?: boolean;
     includeTemplateFunction?: boolean;
@@ -27,7 +76,20 @@ export declare function generateHelpersTemplate(cloudProvider?: 'aws', customHel
     includeObservability?: boolean;
     includeValidation?: boolean;
 }): string;
+/**
+ * Gets helpers for specific categories
+ * @param category - Helper category to retrieve
+ * @returns Array of helper definitions for the specified category
+ * @since 2.8.4+
+ */
 export declare function getHelpersByCategory(category: 'standard' | 'fileAccess' | 'templateFunction' | 'sprig' | 'kubernetes' | 'aws' | 'env' | 'gitops' | 'observability' | 'validation'): HelperDefinition[];
+/**
+ * Creates a custom helper definition
+ * @param name - Helper name
+ * @param template - Helper template content
+ * @returns Helper definition object
+ * @since 2.8.4+
+ */
 export declare function createHelper(name: string, template: string): HelperDefinition;
 export { getNewHelpersByCategory, getAvailableHelperCategories, getHelpersByCategories, getHelpersByOptions, formatNewHelpers, generateNewHelpersTemplate, getCachedNewHelpersTemplate, createNewHelper, validateHelperNames, filterHelpersByPattern, getHelperStatistics, } from './helmHelpers/index.js';
 export { ENV_HELPERS, GITOPS_HELPERS, OBSERVABILITY_HELPERS, VALIDATION_HELPERS, } from './helmHelpers/index.js';

package/dist/lib/utils/helmHelpers.js

@@ -1,4 +1,13 @@
+/**
+ * @fileoverview Helm chart helpers and templates
+ * @since 2.8.0+
+ */
+// Import new helper categories
 import { ENV_HELPERS, GITOPS_HELPERS, OBSERVABILITY_HELPERS, VALIDATION_HELPERS, getNewHelpersByCategory, } from './helmHelpers/index.js';
+/**
+ * Standard Helm chart helpers following best practices
+ * @since 2.8.0+
+ */
 export const STANDARD_HELPERS = [
     {
         name: 'chart.name',
@@ -36,6 +45,10 @@ app.kubernetes.io/managed-by: {{ .Release.Service }}`,
 app.kubernetes.io/instance: {{ .Release.Name }}`,
     },
 ];
+/**
+ * File access helpers using Helm .Files object
+ * @since 2.8.4+
+ */
 export const FILE_ACCESS_HELPERS = [
     {
         name: 'files.configFromFile',
@@ -75,6 +88,10 @@ false
 {{- end -}}`,
     },
 ];
+/**
+ * Advanced template function helpers
+ * @since 2.8.4+
+ */
 export const TEMPLATE_FUNCTION_HELPERS = [
     {
         name: 'template.render',
@@ -104,6 +121,10 @@ export const TEMPLATE_FUNCTION_HELPERS = [
 {{- end -}}`,
     },
 ];
+/**
+ * Sprig library function helpers for common use cases
+ * @since 2.8.4+
+ */
 export const SPRIG_HELPERS = [
     {
         name: 'string.camelCase',
@@ -157,6 +178,10 @@ export const SPRIG_HELPERS = [
 {{- $date | date $format }}`,
     },
 ];
+/**
+ * Kubernetes-specific helpers for common patterns
+ * @since 2.8.4+
+ */
 export const KUBERNETES_HELPERS = [
     {
         name: 'k8s.imagePullPolicy',
@@ -228,6 +253,10 @@ failureThreshold: {{ $probe.failureThreshold | default 3 }}
 {{- end }}`,
     },
 ];
+/**
+ * AWS-specific Helm helpers
+ * @since 2.8.0+
+ */
 export const AWS_HELPERS = [
     {
         name: 'aws.region',
@@ -259,9 +288,16 @@ export const AWS_HELPERS = [
 {{- printf "arn:aws:secretsmanager:%s:%s:secret:%s" $region (include "aws.accountId" .) $secretName }}`,
     },
 ];
+/**
+ * Converts helper definitions to Helm template format
+ * @param helpers - Array of helper definitions
+ * @returns Formatted Helm template string
+ * @since 2.8.0+
+ */
 export function formatHelpers(helpers) {
     return helpers
         .map((helper) => {
+        // Validate helper has required properties
         if (!helper.name || typeof helper.name !== 'string') {
             throw new Error('Helper must have a valid name property');
         }
@@ -277,37 +313,61 @@ ${helper.template}
     })
         .join('\n\n');
 }
+/**
+ * Gets default helpers based on cloud provider and feature flags
+ * @param cloudProvider - Target cloud provider
+ * @param options - Configuration options for helper inclusion
+ * @returns Combined standard and cloud-specific helpers
+ * @since 2.8.4+
+ */
 export function getDefaultHelpers(cloudProvider, options) {
     const helpers = [...STANDARD_HELPERS];
+    // Add file access helpers by default
     if (options?.includeFileAccess !== false) {
         helpers.push(...FILE_ACCESS_HELPERS);
     }
+    // Add template function helpers by default
     if (options?.includeTemplateFunction !== false) {
         helpers.push(...TEMPLATE_FUNCTION_HELPERS);
     }
+    // Add Sprig helpers by default
     if (options?.includeSprig !== false) {
         helpers.push(...SPRIG_HELPERS);
     }
+    // Add Kubernetes helpers by default
     if (options?.includeKubernetes !== false) {
         helpers.push(...KUBERNETES_HELPERS);
     }
+    // Add environment and configuration helpers
     if (options?.includeEnv !== false) {
         helpers.push(...ENV_HELPERS);
     }
+    // Add GitOps and CI/CD helpers
     if (options?.includeGitops !== false) {
         helpers.push(...GITOPS_HELPERS);
     }
+    // Add observability helpers
     if (options?.includeObservability !== false) {
         helpers.push(...OBSERVABILITY_HELPERS);
     }
+    // Add validation helpers
     if (options?.includeValidation !== false) {
         helpers.push(...VALIDATION_HELPERS);
     }
+    // Add cloud-specific helpers
     if (cloudProvider === 'aws') {
         helpers.push(...AWS_HELPERS);
     }
     return helpers;
 }
+/**
+ * Generates complete _helpers.tpl content
+ * @param cloudProvider - Optional cloud provider for specific helpers
+ * @param customHelpers - Additional custom helpers
+ * @param options - Configuration options for helper inclusion
+ * @returns Complete helpers template content
+ * @since 2.8.4+
+ */
 export function generateHelpersTemplate(cloudProvider, customHelpers, options) {
     const helpers = getDefaultHelpers(cloudProvider, options);
     if (customHelpers) {
@@ -315,10 +375,18 @@ export function generateHelpersTemplate(cloudProvider, customHelpers, options) {
     }
     return formatHelpers(helpers);
 }
+/**
+ * Gets helpers for specific categories
+ * @param category - Helper category to retrieve
+ * @returns Array of helper definitions for the specified category
+ * @since 2.8.4+
+ */
 export function getHelpersByCategory(category) {
+    // Handle new categories with imported helpers
     if (['env', 'gitops', 'observability', 'validation'].includes(category)) {
         return getNewHelpersByCategory(category);
     }
+    // Handle existing categories
     switch (category) {
         case 'standard':
             return [...STANDARD_HELPERS];
@@ -336,8 +404,17 @@ export function getHelpersByCategory(category) {
             return [];
     }
 }
+/**
+ * Creates a custom helper definition
+ * @param name - Helper name
+ * @param template - Helper template content
+ * @returns Helper definition object
+ * @since 2.8.4+
+ */
 export function createHelper(name, template) {
     return { name, template };
 }
+// Re-export new helper functions for convenience
 export { getNewHelpersByCategory, getAvailableHelperCategories, getHelpersByCategories, getHelpersByOptions, formatNewHelpers, generateNewHelpersTemplate, getCachedNewHelpersTemplate, createNewHelper, validateHelperNames, filterHelpersByPattern, getHelperStatistics, } from './helmHelpers/index.js';
+// Export the new helper constants for direct access
 export { ENV_HELPERS, GITOPS_HELPERS, OBSERVABILITY_HELPERS, VALIDATION_HELPERS, } from './helmHelpers/index.js';

package/dist/lib/utils/helmYamlSerializer.d.ts

@@ -1,14 +1,53 @@
+/**
+ * Pre-process an object to convert HelmConstruct instances to HelmExpression
+ * This allows the yaml library to serialize them correctly
+ */
 export declare function preprocessHelmConstructs(obj: unknown): unknown;
+/**
+ * Main method to serialize an object to YAML with Helm template awareness.
+ * Uses 'yaml' library to natively handle Helm expressions by forcing QUOTE_DOUBLE style.
+ *
+ * @param obj Input object to serialize.
+ * @param options Options (lineWidth, etc.) - partially supported mapping from legacy options.
+ * @returns Helm-aware YAML string.
+ * @since 2.11.0
+ * @since 2.13.1 Refactored to use 'yaml' library
+ * @since 2.14.0 Added HelmConstruct pre-processing
+ */
 export declare function dumpHelmAwareYaml(obj: unknown, options?: {
     lineWidth?: number;
 }): string;
+/**
+ * Post-processes YAML string to transform field-level conditionals
+ * This function should be called after dumpHelmAwareYaml to transform
+ * __fieldConditionalContent markers into the correct Helm template format.
+ *
+ * @param yaml YAML string that may contain __fieldConditionalContent markers
+ * @returns YAML string with field-level conditionals properly formatted
+ * @since 2.14.0
+ */
 export declare function postProcessFieldConditionals(yaml: string): string;
+/**
+ * Legacy compatible stringify method.
+ * @param obj Object to serialize.
+ * @param options Options.
+ * @returns YAML string.
+ * @since 2.11.0
+ */
 export declare function stringify(obj: unknown, options?: {
     lineWidth?: number;
     doubleQuotedAsJSON?: boolean;
     simpleKeys?: boolean;
 }): string;
+/**
+ * Helm expression types for pattern matching
+ * @since 2.11.0
+ */
 type HelmExpressionType = 'block' | 'nested' | 'comment' | 'action-trimmed' | 'raw' | 'include-context' | 'generic';
+/**
+ * Interface to report validation errors of Helm YAML content.
+ * @since 2.11.0
+ */
 export interface HelmValidationError {
     type: 'syntax' | 'semantic' | 'reference' | 'type';
     message: string;
@@ -17,6 +56,10 @@ export interface HelmValidationError {
     expression?: string;
     suggestion?: string;
 }
+/**
+ * Result of Helm YAML validation process.
+ * @since 2.11.0
+ */
 export interface HelmValidationResult {
     isValid: boolean;
     errors: HelmValidationError[];
@@ -27,7 +70,26 @@ export interface HelmValidationResult {
         complexity: number;
     };
 }
+/**
+ * Validate YAML string with Helm template expressions.
+ * - Parses Helm expressions from the string,
+ * - Performs balanced parentheses and quote checks,
+ * - Collects syntax errors, semantic warnings,
+ * - Provides statistics including complexity.
+ *
+ * @param yaml YAML content string to validate.
+ * @returns Validation result with errors, warnings, and stats.
+ * @since 2.11.0
+ * @since 2.14.0 Restored full validation functionality
+ */
 export declare function validateHelmYaml(yaml: string): HelmValidationResult;
+/**
+ * Internal helper to parse Helm expressions with line and column positions.
+ * Supports advanced expression types and range matching.
+ * @param content YAML string content.
+ * @returns List of detected Helm expressions with positional info.
+ * @since 2.11.0
+ */
 export declare function parseHelmExpressions(content: string): Array<{
     type: HelmExpressionType;
     expression: string;
@@ -36,7 +98,22 @@ export declare function parseHelmExpressions(content: string): Array<{
     endLine: number;
     endCol: number;
 }>;
+/**
+ * Detect Helm template expressions using Timonel's parser.
+ * @param str - YAML/template content to inspect
+ * @returns Detected expression descriptors
+ */
 export declare function detectHelmExpressions(str: string): unknown[];
+/**
+ * Preprocess Helm marker objects before YAML serialization.
+ * @param obj - Value tree containing Helm constructs or ValuesRef proxies
+ * @returns Serializer-ready value tree
+ */
 export declare function preprocessHelmExpressions(obj: unknown): unknown;
+/**
+ * Preserve the historical post-processing compatibility hook.
+ * @param yaml - YAML content to return unchanged
+ * @returns The original YAML content
+ */
 export declare function postProcessHelmExpressions(yaml: string): string;
 export {};