timonel 3.1.1 → 3.1.2

package/dist/lib/umbrellaRutter.d.ts

@@ -1,26 +1,101 @@
+/**
+ * @fileoverview UmbrellaRutter class for managing Helm umbrella charts with multiple subcharts
+ * @since 2.8.0+
+ */
 import type { HelmChartMeta } from './helmChartWriter.js';
 import type { Rutter } from './rutter.js';
 import { type TimonelLogger } from './utils/logger.js';
+/**
+ * Configuration for a subchart within an umbrella chart
+ *
+ * @since 2.8.0+
+ */
 export interface SubchartSpec {
+    /** Name of the subchart */
     name: string;
+    /** Rutter instance that generates the subchart */
     rutter: Rutter;
+    /** Version of the subchart (optional) */
     version?: string;
+    /** Helm condition for enabling/disabling the subchart */
     condition?: string;
+    /** Tags for grouping subcharts */
     tags?: string[];
+    /** Repository URL for the subchart */
     repository?: string;
 }
+/**
+ * Configuration properties for UmbrellaRutter
+ *
+ * @since 2.8.0+
+ */
 export interface UmbrellaRutterProps {
+    /** Metadata for the umbrella chart */
     meta: HelmChartMeta;
+    /** Array of subchart specifications */
     subcharts: SubchartSpec[];
+    /** Default values for the umbrella chart */
     defaultValues?: Record<string, unknown>;
+    /**
+     * Custom logger instance
+     * @since 2.13.0
+     */
     logger?: TimonelLogger;
+    /** Environment-specific values */
     envValues?: Record<string, Record<string, unknown>>;
 }
+/**
+ * UmbrellaRutter manages multiple Rutter instances as subcharts
+ * to create Helm umbrella charts with dependencies.
+ *
+ * @example
+ * ```typescript
+ * const umbrella = new UmbrellaRutter({
+ *   meta: { name: 'my-app', version: '1.0.0' },
+ *   subcharts: [
+ *     { name: 'frontend', rutter: frontendChart },
+ *     { name: 'backend', rutter: backendChart }
+ *   ]
+ * });
+ *
+ * umbrella.write('./my-app');
+ * ```
+ *
+ * @since 2.8.0+
+ */
 export declare class UmbrellaRutter {
     private readonly props;
     private readonly logger;
+    /**
+     * Creates a new UmbrellaRutter instance
+     *
+     * @param props - Configuration properties for the umbrella chart
+     * @throws {Error} If chart metadata is invalid
+     *
+     * @since 2.8.0+
+     */
     constructor(props: UmbrellaRutterProps);
     private validateMetadata;
+    /**
+     * Write the umbrella chart with all subcharts to the output directory
+     *
+     * Creates the complete umbrella chart structure including:
+     * - Parent Chart.yaml with dependencies
+     * - Parent values.yaml with global and subchart values
+     * - Individual subchart directories under charts/
+     * - NOTES.txt template
+     *
+     * @param outDir - Output directory path for the umbrella chart
+     * @returns Promise that resolves when the chart is written
+     * @throws {Error} If output directory path is invalid
+     *
+     * @example
+     * ```typescript
+     * await umbrella.write('./dist/my-umbrella-chart');
+     * ```
+     *
+     * @since 2.8.0+
+     */
     write(outDir: string): Promise<void>;
     private writeParentChart;
     private writeParentValues;

package/dist/lib/umbrellaRutter.js

@@ -1,9 +1,40 @@
+/**
+ * @fileoverview UmbrellaRutter class for managing Helm umbrella charts with multiple subcharts
+ * @since 2.8.0+
+ */
 import { writeFileSync, mkdirSync } from 'fs';
 import { join } from 'path';
 import { createLogger } from './utils/logger.js';
 import { SecurityUtils } from './security.js';
 import { dumpHelmAwareYaml } from './utils/helmYamlSerializer.js';
+/**
+ * UmbrellaRutter manages multiple Rutter instances as subcharts
+ * to create Helm umbrella charts with dependencies.
+ *
+ * @example
+ * ```typescript
+ * const umbrella = new UmbrellaRutter({
+ *   meta: { name: 'my-app', version: '1.0.0' },
+ *   subcharts: [
+ *     { name: 'frontend', rutter: frontendChart },
+ *     { name: 'backend', rutter: backendChart }
+ *   ]
+ * });
+ *
+ * umbrella.write('./my-app');
+ * ```
+ *
+ * @since 2.8.0+
+ */
 export class UmbrellaRutter {
+    /**
+     * Creates a new UmbrellaRutter instance
+     *
+     * @param props - Configuration properties for the umbrella chart
+     * @throws {Error} If chart metadata is invalid
+     *
+     * @since 2.8.0+
+     */
     constructor(props) {
         this.logger = props.logger ?? createLogger('umbrella-rutter');
         this.logger.info('Initializing umbrella chart', {
@@ -11,39 +42,75 @@ export class UmbrellaRutter {
             version: props.meta.version,
             subchartsCount: props.subcharts.length,
         });
+        // Validate chart metadata
         this.validateMetadata(props.meta);
         this.props = props;
     }
     validateMetadata(meta) {
+        // Validate chart name follows Helm conventions
+        // eslint-disable-next-line security/detect-unsafe-regex -- Safe regex for chart name validation
         if (!/^[a-z0-9]([-a-z0-9]*[a-z0-9])?$/.test(meta.name)) {
             throw new Error('Chart name must contain only lowercase letters, numbers, and dashes');
         }
+        // Validate semantic versioning
+        // eslint-disable-next-line security/detect-unsafe-regex -- Safe regex for semver validation
         if (!/^\d+\.\d+\.\d+(-[a-zA-Z0-9.-]+)?(\+[a-zA-Z0-9.-]+)?$/.test(meta.version)) {
             throw new Error('Chart version must follow semantic versioning (e.g., 1.0.0)');
         }
     }
+    /**
+     * Write the umbrella chart with all subcharts to the output directory
+     *
+     * Creates the complete umbrella chart structure including:
+     * - Parent Chart.yaml with dependencies
+     * - Parent values.yaml with global and subchart values
+     * - Individual subchart directories under charts/
+     * - NOTES.txt template
+     *
+     * @param outDir - Output directory path for the umbrella chart
+     * @returns Promise that resolves when the chart is written
+     * @throws {Error} If output directory path is invalid
+     *
+     * @example
+     * ```typescript
+     * await umbrella.write('./dist/my-umbrella-chart');
+     * ```
+     *
+     * @since 2.8.0+
+     */
     async write(outDir) {
+        // Validate output directory path
         const validatedOutDir = SecurityUtils.validatePath(outDir, process.cwd(), {
             allowAbsolute: true,
         });
+        // Create output directory structure
+        // eslint-disable-next-line security/detect-non-literal-fs-filename -- validated path
         mkdirSync(validatedOutDir, { recursive: true });
         const chartsDir = SecurityUtils.validatePath(join(validatedOutDir, 'charts'), process.cwd(), {
             allowAbsolute: true,
         });
+        // eslint-disable-next-line security/detect-non-literal-fs-filename -- validated path
         mkdirSync(chartsDir, { recursive: true });
+        // Write each subchart to charts/ directory
         for (const subchart of this.props.subcharts) {
+            // Validate subchart name using centralized validation
             if (!SecurityUtils.isValidSubchartName(subchart.name)) {
                 throw new Error(`Invalid subchart name: ${SecurityUtils.sanitizeLogMessage(subchart.name)}`);
             }
-            const sanitizedName = subchart.name;
+            const sanitizedName = subchart.name; // Already validated by SecurityUtils
             const subchartDir = SecurityUtils.validatePath(join(validatedOutDir, 'charts', sanitizedName), process.cwd(), { allowAbsolute: true });
             await subchart.rutter.write(subchartDir);
         }
+        // Generate parent Chart.yaml with dependencies
         this.writeParentChart(validatedOutDir);
+        // Generate parent values.yaml
         this.writeParentValues(validatedOutDir);
+        // Generate empty templates directory (umbrella charts typically don't have templates)
         const templatesDir = SecurityUtils.validatePath(join(validatedOutDir, 'templates'), process.cwd(), { allowAbsolute: true });
+        // eslint-disable-next-line security/detect-non-literal-fs-filename -- validated path
         mkdirSync(templatesDir, { recursive: true });
         const notesPath = SecurityUtils.validatePath(join(validatedOutDir, 'templates', 'NOTES.txt'), process.cwd(), { allowAbsolute: true });
+        // eslint-disable-next-line security/detect-non-literal-fs-filename -- validated path
         writeFileSync(notesPath, this.generateNotesTemplate());
     }
     writeParentChart(outDir) {
@@ -59,6 +126,7 @@ export class UmbrellaRutter {
             sources: this.props.meta.sources,
             maintainers: this.props.meta.maintainers,
             dependencies: this.props.subcharts.map((subchart) => {
+                // Subchart name already validated in write() method
                 return {
                     name: subchart.name,
                     version: subchart.version || '0.1.0',
@@ -71,13 +139,17 @@ export class UmbrellaRutter {
         const chartYamlPath = SecurityUtils.validatePath(join(outDir, 'Chart.yaml'), process.cwd(), {
             allowAbsolute: true,
         });
+        // eslint-disable-next-line security/detect-non-literal-fs-filename -- validated path
         writeFileSync(chartYamlPath, dumpHelmAwareYaml(chartYaml));
     }
     writeParentValues(outDir) {
         const values = {
+            // Global values that can be shared across subcharts
             global: {},
+            // Individual subchart values
             ...this.props.defaultValues,
         };
+        // Add subchart-specific value sections
         for (const subchart of this.props.subcharts) {
             if (!(subchart.name in values)) {
                 values[subchart.name] = {
@@ -88,12 +160,16 @@ export class UmbrellaRutter {
         const valuesYamlPath = SecurityUtils.validatePath(join(outDir, 'values.yaml'), process.cwd(), {
             allowAbsolute: true,
         });
+        // eslint-disable-next-line security/detect-non-literal-fs-filename -- validated path
         writeFileSync(valuesYamlPath, dumpHelmAwareYaml(values));
+        // Write environment-specific values files
         if (this.props.envValues) {
             for (const [env, envVals] of Object.entries(this.props.envValues)) {
+                // Use centralized environment name sanitization
                 const sanitizedEnv = SecurityUtils.sanitizeEnvironmentName(env);
                 const envValues = this.deepMerge(values, envVals);
                 const envValuesPath = SecurityUtils.validatePath(join(outDir, `values-${sanitizedEnv}.yaml`), process.cwd(), { allowAbsolute: true });
+                // eslint-disable-next-line security/detect-non-literal-fs-filename -- validated path
                 writeFileSync(envValuesPath, dumpHelmAwareYaml(envValues));
             }
         }
@@ -102,9 +178,13 @@ export class UmbrellaRutter {
         const result = { ...target };
         for (const [key, value] of Object.entries(source)) {
             if (value && typeof value === 'object' && !Array.isArray(value)) {
-                result[key] = this.deepMerge(result[key] || {}, value);
+                // eslint-disable-next-line security/detect-object-injection -- Safe object property access in deep merge
+                result[key] = this.deepMerge(
+                // eslint-disable-next-line security/detect-object-injection -- Safe object property access in deep merge
+                result[key] || {}, value);
             }
             else {
+                // eslint-disable-next-line security/detect-object-injection -- Safe object property access in deep merge
                 result[key] = value;
             }
         }

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

@@ -1,3 +1,6 @@
+/**
+ * Environment variable configuration
+ */
 export interface EnvVarConfig {
     name: string;
     type: 'value' | 'secret';
@@ -5,15 +8,61 @@ export interface EnvVarConfig {
     defaultValue?: string;
     secretName?: string;
 }
+/**
+ * Options for loading environment variables
+ */
 export interface LoadEnvVarsOptions {
     configPath?: string;
     defaultScope?: string;
     fallbackConfig?: EnvVarConfig[];
 }
+/**
+ * Load environment variables from YAML or JSON file
+ *
+ * @param options - Configuration options
+ * @returns Array of environment variable configurations
+ *
+ * @example
+ * ```typescript
+ * const envVars = loadEnvVarsConfig({
+ *   configPath: './env-config.yaml',
+ *   defaultScope: 'global.env'
+ * });
+ * ```
+ */
 export declare function loadEnvVarsConfig(options?: LoadEnvVarsOptions): EnvVarConfig[];
+/**
+ * Generate Kubernetes environment variables from configuration
+ *
+ * @param config - Array of environment variable configurations
+ * @param options - Generation options
+ * @returns Array of Kubernetes env var objects
+ *
+ * @example
+ * ```typescript
+ * const envVars = generateEnvVars(config, { defaultScope: 'global.env' });
+ * ```
+ */
 export declare function generateEnvVars(config: EnvVarConfig[], options?: {
     defaultScope?: string;
 }): Array<Record<string, unknown>>;
+/**
+ * Convenience function to load and generate env vars in one step
+ *
+ * @param options - Combined load and generate options
+ * @returns Array of Kubernetes env var objects
+ *
+ * @example
+ * ```typescript
+ * const envVars = loadAndGenerateEnvVars({
+ *   configPath: './env-config.yaml',
+ *   defaultScope: 'global.env',
+ *   fallbackConfig: [
+ *     { name: 'VERSION', type: 'value', defaultValue: '1.0.0' }
+ *   ]
+ * });
+ * ```
+ */
 export declare function loadAndGenerateEnvVars(options?: LoadEnvVarsOptions & {
     defaultScope?: string;
 }): Array<Record<string, unknown>>;

package/dist/lib/utils/envVarsLoader.js

@@ -3,35 +3,70 @@ import { join } from 'path';
 import { parse as parseYaml } from 'yaml';
 import { SecurityUtils } from '../security.js';
 import { createHelmExpression } from './helmControlStructures.js';
+/**
+ * Load environment variables from YAML or JSON file
+ *
+ * @param options - Configuration options
+ * @returns Array of environment variable configurations
+ *
+ * @example
+ * ```typescript
+ * const envVars = loadEnvVarsConfig({
+ *   configPath: './env-config.yaml',
+ *   defaultScope: 'global.env'
+ * });
+ * ```
+ */
 export function loadEnvVarsConfig(options = {}) {
     const { configPath, fallbackConfig = [] } = options;
     try {
+        // If specific path provided, use it
         if (configPath) {
             const validatedConfigPath = SecurityUtils.validatePath(configPath, process.cwd(), {
                 allowAbsolute: true,
             });
+            // eslint-disable-next-line security/detect-non-literal-fs-filename -- validated path
             if (existsSync(validatedConfigPath)) {
+                // eslint-disable-next-line security/detect-non-literal-fs-filename -- validated path
                 const data = readFileSync(validatedConfigPath, 'utf-8');
                 return validatedConfigPath.endsWith('.yaml') || validatedConfigPath.endsWith('.yml')
                     ? parseYaml(data)
                     : JSON.parse(data);
             }
         }
+        // Try default locations
         const yamlPath = SecurityUtils.validatePath(join(process.cwd(), 'env-config.yaml'), process.cwd(), { allowAbsolute: true });
+        // eslint-disable-next-line security/detect-non-literal-fs-filename -- validated path
         if (existsSync(yamlPath)) {
+            // eslint-disable-next-line security/detect-non-literal-fs-filename -- validated path
             const data = readFileSync(yamlPath, 'utf-8');
             return parseYaml(data);
         }
         const jsonPath = SecurityUtils.validatePath(join(process.cwd(), 'env-config.json'), process.cwd(), { allowAbsolute: true });
+        // eslint-disable-next-line security/detect-non-literal-fs-filename -- validated path
         if (existsSync(jsonPath)) {
+            // eslint-disable-next-line security/detect-non-literal-fs-filename -- validated path
             const data = readFileSync(jsonPath, 'utf-8');
             return JSON.parse(data);
         }
     }
     catch {
+        // Fall through to fallback
     }
     return fallbackConfig;
 }
+/**
+ * Generate Kubernetes environment variables from configuration
+ *
+ * @param config - Array of environment variable configurations
+ * @param options - Generation options
+ * @returns Array of Kubernetes env var objects
+ *
+ * @example
+ * ```typescript
+ * const envVars = generateEnvVars(config, { defaultScope: 'global.env' });
+ * ```
+ */
 export function generateEnvVars(config, options = {}) {
     const { defaultScope = 'global.env' } = options;
     return config.map((item) => {
@@ -43,6 +78,7 @@ export function generateEnvVars(config, options = {}) {
             };
         }
         else {
+            // Secret reference
             return {
                 name: item.name,
                 valueFrom: {
@@ -56,6 +92,23 @@ export function generateEnvVars(config, options = {}) {
         }
     });
 }
+/**
+ * Convenience function to load and generate env vars in one step
+ *
+ * @param options - Combined load and generate options
+ * @returns Array of Kubernetes env var objects
+ *
+ * @example
+ * ```typescript
+ * const envVars = loadAndGenerateEnvVars({
+ *   configPath: './env-config.yaml',
+ *   defaultScope: 'global.env',
+ *   fallbackConfig: [
+ *     { name: 'VERSION', type: 'value', defaultValue: '1.0.0' }
+ *   ]
+ * });
+ * ```
+ */
 export function loadAndGenerateEnvVars(options = {}) {
     const config = loadEnvVarsConfig(options);
     const genOptions = options.defaultScope ? { defaultScope: options.defaultScope } : {};

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

@@ -1,3 +1,20 @@
+/**
+ * @fileoverview Helm construct serialization utilities
+ * Converts HelmConstruct objects into Helm template syntax
+ * @since 2.14.0
+ */
 import type { HelmConstruct, HelmContent } from './helmControlStructures.js';
+/**
+ * Serialize a HelmConstruct object into Helm template syntax
+ * @param construct The HelmConstruct to serialize
+ * @param indent Current indentation level
+ * @returns Helm template string
+ */
 export declare function serializeHelmConstruct(construct: HelmConstruct, indent?: number): string;
+/**
+ * Serialize HelmContent (which can be primitives, objects, arrays, or HelmConstructs)
+ * @param content The content to serialize
+ * @param indent Current indentation level
+ * @returns Serialized string
+ */
 export declare function serializeHelmContent(content: HelmContent, indent?: number): string;

package/dist/lib/utils/helmConstructSerializer.js

@@ -1,4 +1,15 @@
+/**
+ * @fileoverview Helm construct serialization utilities
+ * Converts HelmConstruct objects into Helm template syntax
+ * @since 2.14.0
+ */
 import { isHelmConstruct } from './helmControlStructures.js';
+/**
+ * Serialize a HelmConstruct object into Helm template syntax
+ * @param construct The HelmConstruct to serialize
+ * @param indent Current indentation level
+ * @returns Helm template string
+ */
 export function serializeHelmConstruct(construct, indent = 0) {
     const trimLeft = construct.options?.trimLeft ?? true;
     const trimRight = construct.options?.trimRight ?? true;
@@ -20,17 +31,26 @@ export function serializeHelmConstruct(construct, indent = 0) {
             throw new Error(`Unknown Helm construct type: ${construct.type}`);
     }
 }
+/**
+ * Serialize HelmContent (which can be primitives, objects, arrays, or HelmConstructs)
+ * @param content The content to serialize
+ * @param indent Current indentation level
+ * @returns Serialized string
+ */
 export function serializeHelmContent(content, indent = 0) {
     const indentStr = '  '.repeat(indent);
+    // Handle HelmConstruct
     if (isHelmConstruct(content)) {
         return serializeHelmConstruct(content, indent);
     }
+    // Handle primitives
     if (content === null || content === undefined) {
         return '';
     }
     if (typeof content === 'string' || typeof content === 'number' || typeof content === 'boolean') {
         return String(content);
     }
+    // Handle arrays
     if (Array.isArray(content)) {
         return content
             .map((item) => {
@@ -41,6 +61,7 @@ export function serializeHelmContent(content, indent = 0) {
         })
             .join('\n');
     }
+    // Handle objects (convert to YAML)
     if (typeof content === 'object') {
         const lines = [];
         for (const [key, value] of Object.entries(content)) {
@@ -52,6 +73,7 @@ export function serializeHelmContent(content, indent = 0) {
                 lines.push(serializeHelmContent(value, indent + 1));
             }
             else {
+                // Generic Object Injection Sink /* eslint-disable-next-line security/detect-object-injection */
                 lines.push(`${indentStr}${key}: ${value}`);
             }
         }