timonel 3.1.1 → 3.1.2

package/dist/lib/rutter.js

@@ -8,9 +8,20 @@ import { KarpenterResources } from './resources/cloud/aws/karpenterResources.js'
 import { isHelmExpression, isHelmConstruct } from './utils/helmControlStructures.js';
 import { dumpHelmAwareYaml, preprocessHelmConstructs } from './utils/helmYamlSerializer.js';
 import { generateHelpersTemplate } from './utils/helmHelpers.js';
+/**
+ * Constants for error messages
+ */
 const UNKNOWN_ERROR_MESSAGE = 'Unknown error';
+/**
+ * Rutter class with modular architecture
+ * Provides a clean API while delegating to specialized resource providers
+ * Maintains full backward compatibility with the original Rutter class
+ *
+ * @since 2.8.0+
+ */
 export class Rutter {
     constructor(props) {
+        // CDK8s infrastructure
         this.assets = [];
         this.defaultValues = props.defaultValues ?? {};
         this.envValues = props.envValues ?? {};
@@ -23,54 +34,256 @@ export class Rutter {
             namespace: props.namespace,
             operation: 'chart_initialization',
         });
-        this.app = new App();
-        this.chart = new Chart(this.app, props.meta.name, {
+        // Compose with a caller-owned construct tree when one is supplied. Otherwise
+        // Timonel owns an internal App solely as the root for this chart.
+        const scope = props.scope ?? new App();
+        this.chart = new Chart(scope, props.meta.name, {
             ...props.chartProps,
             ...(props.namespace ? { namespace: props.namespace } : {}),
         });
         this.awsResources = new AWSResources(this.chart);
         this.karpenterResources = new KarpenterResources(this.chart);
-        const originalToSynthArray = this.toSynthArray.bind(this);
-        this['toSynthArray'] = (..._args) => {
-            if (!this.props.policyEngine) {
-                return this.toSynthArraySync();
-            }
-            return originalToSynthArray();
-        };
     }
+    // AWS Resources
+    /**
+     * Creates an AWS EBS StorageClass
+     * @param spec - EBS StorageClass specification
+     * @returns Created StorageClass ApiObject
+     *
+     * @example
+     * ```typescript
+     * rutter.addAWSEBSStorageClass({
+     *   name: 'fast-ebs',
+     *   volumeType: 'gp3',
+     *   encrypted: true,
+     *   allowVolumeExpansion: true
+     * });
+     * ```
+     *
+     * @since 2.8.0+
+     */
     addAWSEBSStorageClass(spec) {
         return this.awsResources.addEBSStorageClass(spec);
     }
+    /**
+     * Creates an AWS EFS StorageClass
+     * @param spec - EFS StorageClass specification
+     * @returns Created StorageClass ApiObject
+     *
+     * @example
+     * ```typescript
+     * rutter.addAWSEFSStorageClass({
+     *   name: 'efs-storage',
+     *   fileSystemId: 'fs-12345678',
+     *   directoryPerms: '0755'
+     * });
+     * ```
+     *
+     * @since 2.8.0+
+     */
     addAWSEFSStorageClass(spec) {
         return this.awsResources.addEFSStorageClass(spec);
     }
+    /**
+     * Creates an AWS IRSA ServiceAccount
+     * @param spec - IRSA ServiceAccount specification
+     * @returns Created cdk8s-plus ServiceAccount
+     *
+     * @example
+     * ```typescript
+     * rutter.addAWSIRSAServiceAccount({
+     *   name: 'my-service-account',
+     *   roleArn: 'arn:aws:iam::ACCOUNT_ID:role/MyRole'
+     * });
+     * ```
+     *
+     * @since 2.8.0+
+     */
     addAWSIRSAServiceAccount(spec) {
         return this.awsResources.addIRSAServiceAccount(spec);
     }
+    /**
+     * Creates an AWS ALB Ingress
+     * @param spec - ALB Ingress specification
+     * @returns Created cdk8s-plus Ingress
+     *
+     * @example
+     * ```typescript
+     * rutter.addAWSALBIngress({
+     *   name: 'web-ingress',
+     *   rules: [{
+     *     paths: [{
+     *       path: '/',
+     *       pathType: 'Prefix',
+     *       backend: { service: { name: 'web-service', port: { number: 80 } } }
+     *     }]
+     *   }],
+     *   scheme: 'internet-facing'
+     * });
+     * ```
+     *
+     * @since 2.8.0+
+     */
     addAWSALBIngress(spec) {
         return this.awsResources.addALBIngress(spec);
     }
+    // AWS Karpenter Resources
+    /**
+     * Creates a Karpenter NodePool resource
+     * @param spec - NodePool specification
+     * @returns Created NodePool ApiObject
+     *
+     * @example
+     * ```typescript
+     * rutter.addKarpenterNodePool({
+     *   name: 'default-nodepool',
+     *   template: {
+     *     spec: {
+     *       nodeClassRef: {
+     *         apiVersion: 'karpenter.k8s.aws/v1beta1',
+     *         kind: 'EC2NodeClass',
+     *         name: 'default'
+     *       }
+     *     }
+     *   }
+     * });
+     * ```
+     *
+     * @since 2.8.0+
+     */
     addKarpenterNodePool(spec) {
         return this.karpenterResources.addKarpenterNodePool(spec);
     }
+    /**
+     * Creates a Karpenter NodeClaim resource
+     * @param spec - NodeClaim specification
+     * @returns Created NodeClaim ApiObject
+     *
+     * @example
+     * ```typescript
+     * rutter.addKarpenterNodeClaim({
+     *   name: 'my-node-claim',
+     *   nodeClassRef: {
+     *     apiVersion: 'karpenter.k8s.aws/v1beta1',
+     *     kind: 'EC2NodeClass',
+     *     name: 'default'
+     *   }
+     * });
+     * ```
+     *
+     * @since 2.8.0+
+     */
     addKarpenterNodeClaim(spec) {
         return this.karpenterResources.addKarpenterNodeClaim(spec);
     }
+    /**
+     * Creates a Karpenter EC2NodeClass resource
+     * @param spec - EC2NodeClass specification
+     * @returns Created EC2NodeClass ApiObject
+     *
+     * @example
+     * ```typescript
+     * rutter.addKarpenterEC2NodeClass({
+     *   name: 'default',
+     *   amiFamily: 'AL2',
+     *   subnetSelectorTerms: [{ tags: { 'karpenter.sh/discovery': 'my-cluster' } }],
+     *   securityGroupSelectorTerms: [{ tags: { 'karpenter.sh/discovery': 'my-cluster' } }]
+     * });
+     * ```
+     *
+     * @since 2.8.0+
+     */
     addKarpenterEC2NodeClass(spec) {
         return this.karpenterResources.addKarpenterEC2NodeClass(spec);
     }
+    /**
+     * Creates a Karpenter NodePool with optimized disruption settings for cost efficiency
+     * @param spec - NodePool specification with disruption optimization
+     * @returns Created NodePool ApiObject
+     *
+     * @example
+     * ```typescript
+     * rutter.addKarpenterNodePoolWithDisruption({
+     *   name: 'cost-optimized',
+     *   nodeClassRef: {
+     *     apiVersion: 'karpenter.k8s.aws/v1beta1',
+     *     kind: 'EC2NodeClass',
+     *     name: 'default'
+     *   },
+     *   consolidationPolicy: 'WhenEmptyOrUnderutilized',
+     *   consolidateAfter: '30s',
+     *   expireAfter: '24h',
+     *   disruptionBudgets: [
+     *     { nodes: '20%' },
+     *     { nodes: '0', schedule: '0 9 * * 1-5', duration: '8h' }
+     *   ]
+     * });
+     * ```
+     *
+     * @since 2.8.0+
+     */
     addKarpenterNodePoolWithDisruption(spec) {
         return this.karpenterResources.addKarpenterNodePoolWithDisruption(spec);
     }
+    /**
+     * Creates a Karpenter NodePool with scheduling constraints and priorities
+     * @param spec - NodePool specification with scheduling optimization
+     * @returns Created NodePool ApiObject
+     *
+     * @example
+     * ```typescript
+     * rutter.addKarpenterNodePoolWithScheduling({
+     *   name: 'gpu-workloads',
+     *   nodeClassRef: {
+     *     apiVersion: 'karpenter.k8s.aws/v1beta1',
+     *     kind: 'EC2NodeClass',
+     *     name: 'gpu-nodeclass'
+     *   },
+     *   requirements: [
+     *     { key: 'node.kubernetes.io/instance-type', operator: 'In', values: ['g4dn.xlarge', 'g4dn.2xlarge'] }
+     *   ],
+     *   taints: [
+     *     { key: 'nvidia.com/gpu', effect: 'NoSchedule' }
+     *   ],
+     *   terminationGracePeriod: '60s',
+     *   weight: 100
+     * });
+     * ```
+     *
+     * @since 2.8.0+
+     */
     addKarpenterNodePoolWithScheduling(spec) {
         return this.karpenterResources.addKarpenterNodePoolWithScheduling(spec);
     }
+    // AWS ECR ServiceAccount
+    /**
+     * Creates a ServiceAccount with ECR access annotations
+     * @param spec - ECR ServiceAccount specification
+     * @returns Created cdk8s-plus ServiceAccount
+     *
+     * @example
+     * ```typescript
+     * rutter.addAWSECRServiceAccount({
+     *   name: 'ecr-service-account',
+     *   roleArn: 'arn:aws:iam::ACCOUNT_ID:role/ECRAccessRole'
+     * });
+     * ```
+     *
+     * @since 2.8.0+
+     */
     addAWSECRServiceAccount(spec) {
         return this.awsResources.addECRServiceAccount(spec);
     }
+    /**
+     * Implements the object and deprecated raw-YAML overloads.
+     * @param yamlOrObject - Kubernetes manifest object or raw YAML compatibility input
+     * @param id - Unique cdk8s construct identifier
+     * @returns The created cdk8s ApiObject
+     */
     addManifest(yamlOrObject, id) {
         let manifestObject;
         if (typeof yamlOrObject === 'string') {
+            // Parse YAML string to object
             try {
                 manifestObject = parse(yamlOrObject);
             }
@@ -82,53 +295,145 @@ export class Rutter {
             }
         }
         else if (typeof yamlOrObject === 'object' && yamlOrObject !== null) {
+            // Use object directly
             manifestObject = yamlOrObject;
         }
         else {
             throw new Error('addManifest() requires either a YAML string or an object');
         }
+        // Validate basic Kubernetes manifest structure
         this.validateManifestStructure(manifestObject);
+        // IMPORTANT: Pre-process HelmConstructs BEFORE creating ApiObject
+        // This ensures that field-level conditionals are detected and transformed
+        // into __fieldConditionalTemplate_* fields that can be preserved during cdk8s serialization
         const preprocessedManifest = preprocessHelmConstructs(manifestObject);
+        // Create CDK8S ApiObject from the manifest
+        // ApiObjectProps has an index signature [key: string]: any, which allows
+        // passing additional fields like data, stringData, spec, etc.
+        // We validate that required fields exist, then safely construct the props
         const apiObjectProps = {
             apiVersion: preprocessedManifest.apiVersion,
             kind: preprocessedManifest.kind,
             metadata: preprocessedManifest.metadata,
-            ...preprocessedManifest,
+            ...preprocessedManifest, // Spread remaining fields (spec, data, stringData, etc.)
         };
         return new ApiObject(this.chart, id, apiObjectProps);
     }
+    /**
+     * Adds a template manifest to the chart with custom YAML content that preserves Helm expressions.
+     * This method allows you to provide raw YAML with Helm templates without serialization issues.
+     *
+     * @param yamlTemplate - The YAML template string with Helm expressions
+     * @param id - Unique identifier for the manifest
+     * @returns A compatibility placeholder that is excluded from synthesized output
+     * @deprecated Raw YAML templates bypass TypeScript resource typing. Prefer typed
+     * cdk8s/cdk8s-plus constructs through `getChart()` and ValuesRef for Helm values.
+     * This method is planned for removal in the next major release.
+     */
     addTemplateManifest(yamlTemplate, id) {
+        // Store the template as an asset that will be processed during write
         const templateAsset = {
             id,
             yaml: yamlTemplate,
             target: 'templates',
         };
         this.assets.push(templateAsset);
-        return new ApiObject(this.chart, id, {
+        // Preserve the historical return type without leaking the compatibility
+        // placeholder into generated charts.
+        return new ApiObject(this.chart, `${id}-placeholder`, {
             apiVersion: 'v1',
             kind: 'ConfigMap',
-            metadata: { name: id },
+            metadata: {
+                name: id,
+                annotations: {
+                    'timonel.sh/placeholder': 'true',
+                    'timonel.sh/deprecated-raw-template': 'true',
+                },
+            },
         });
     }
+    /**
+     * Adds a Kubernetes manifest wrapped in a Helm conditional using programmatic template generation
+     *
+     * This method creates a manifest that will only be rendered if the specified
+     * condition evaluates to true. The condition is checked against .Values in Helm.
+     *
+     * **Key improvements in v2.9.2:**
+     * - Uses programmatic Helm template generation instead of JavaScript interpolation
+     * - Eliminates Handlebars dependency for conditional manifests
+     * - Leverages the include() function from helm.ts for proper Helm syntax
+     * - Provides better type safety and eliminates double interpolation issues
+     * - Maintains backward compatibility with existing condition syntax
+     *
+     * @param manifestObject - JavaScript object representing the Kubernetes manifest
+     * @param condition - Helm condition path (e.g., 'enabled', 'feature.enabled')
+     *                   Can also be a full Helm expression like '{{ .Values.enabled }}'
+     * @param id - Unique identifier for the manifest
+     * @returns ApiObject instance for CDK8S compatibility
+     *
+     * @example
+     * ```typescript
+     * // Simple boolean condition
+     * rutter.addConditionalManifest(
+     *   {
+     *     apiVersion: 'v1',
+     *     kind: 'Namespace',
+     *     metadata: { name: 'my-namespace' }
+     *   },
+     *   'createNamespace',
+     *   'namespace'
+     * );
+     *
+     * // Nested condition with complex logic
+     * rutter.addConditionalManifest(
+     *   {
+     *     apiVersion: 'v1',
+     *     kind: 'ConfigMap',
+     *     metadata: { name: 'app-config' },
+     *     data: {
+     *       config: '{{ .Values.config }}',
+     *       environment: '{{ .Values.environment }}'
+     *     }
+     *   },
+     *   'features.configMap.enabled',
+     *   'app-config'
+     * );
+     * ```
+     *
+     * @throws {Error} When condition is invalid or manifest structure is malformed
+     * @since 2.8.4
+     * @since 2.9.2 Enhanced with programmatic Helm template generation for better reliability
+     */
     addConditionalManifest(manifestObject, condition, id) {
+        // Validate condition path
         if (!condition || typeof condition !== 'string') {
             throw new Error('Condition must be a non-empty string');
         }
+        // Validate basic Kubernetes manifest structure
         this.validateManifestStructure(manifestObject);
+        // Handle condition - if it's already a Helm expression, use it directly
+        // Otherwise, treat it as a path and wrap it with .Values.
         let helmCondition;
         if (condition.startsWith('{{') && condition.endsWith('}}')) {
+            // Already a Helm expression, extract the inner part and use as-is
             helmCondition = condition.slice(2, -2).trim();
         }
         else {
+            // Plain path, wrap with .Values.
             helmCondition = `.Values.${condition}`;
         }
         try {
+            // Convert the manifest to YAML with Helm-aware serialization
             const yamlContent = dumpHelmAwareYaml(manifestObject, {
+                // Preserve formatting and minimize line wrapping
                 lineWidth: 0,
             });
+            // Create programmatic Helm conditional template using proper syntax
+            // This eliminates JavaScript interpolation and uses native Helm templating
             const conditionalYaml = `{{- if ${helmCondition} }}
 ${yamlContent.trim()}
 {{- end }}`;
+            // Store the manifest as a conditional asset that will be processed during write
             const conditionalAsset = {
                 id,
                 yaml: conditionalYaml,
@@ -142,6 +447,8 @@ ${yamlContent.trim()}
             wrappedError.cause = cause;
             throw wrappedError;
         }
+        // Create a placeholder CDK8S ApiObject for consistency, but mark it as conditional
+        // so it doesn't get processed as a separate asset
         return new ApiObject(this.chart, `${id}-placeholder`, {
             apiVersion: manifestObject['apiVersion'],
             kind: manifestObject['kind'],
@@ -150,12 +457,18 @@ ${yamlContent.trim()}
                 annotations: {
                     ...(manifestObject['metadata']?.['annotations'] || {}),
                     'timonel.sh/conditional': condition,
-                    'timonel.sh/placeholder': 'true',
+                    'timonel.sh/placeholder': 'true', // Mark as placeholder to exclude from synthesis
                 },
             },
             spec: manifestObject['spec'],
         });
     }
+    /**
+     * Validates the structure of a Kubernetes manifest object
+     * @param manifest - The manifest object to validate
+     * @private
+     * @since 2.8.0+
+     */
     validateManifestStructure(manifest) {
         if (!manifest.apiVersion) {
             this.logger.error('Validation failed: Missing apiVersion', {
@@ -186,36 +499,90 @@ ${yamlContent.trim()}
             });
             throw new Error('Manifest metadata must have a name');
         }
+        // Validate metadata.name - must be string, HelmExpression, or HelmConstruct
         const name = manifest['metadata']?.['name'];
         if (typeof name !== 'string' && !isHelmExpression(name) && !isHelmConstruct(name)) {
             const actualType = Array.isArray(name) ? 'array' : name === null ? 'null' : typeof name;
             throw new Error(`Manifest metadata.name must be a string, HelmExpression, or HelmConstruct. Got ${actualType}`);
         }
     }
+    /**
+     * Returns stable logical identifiers for all synthesized ApiObjects, including
+     * those nested inside cdk8s-plus resources.
+     */
+    getSynthesizedApiObjectIds() {
+        return this.chart.node
+            .findAll()
+            .filter((construct) => construct instanceof ApiObject && !construct.node.id.endsWith('-placeholder'))
+            .map((apiObject) => {
+            const owner = apiObject.node.scope;
+            if (apiObject.node.id === 'Resource' && owner && owner !== this.chart) {
+                return owner.node.id;
+            }
+            return apiObject.node.id;
+        });
+    }
+    /**
+     * Returns the underlying cdk8s Chart so consumers can attach fully typed
+     * cdk8s/cdk8s-plus constructs directly to Timonel's synthesis tree.
+     *
+     * @returns The cdk8s Chart owned by this Rutter instance
+     */
+    getChart() {
+        return this.chart;
+    }
+    /**
+     * Gets chart metadata
+     * @returns Chart metadata
+     *
+     * @since 2.8.0+
+     */
     getMeta() {
         return { ...this.meta };
     }
+    /**
+     * Gets default values
+     * @returns Default values object
+     *
+     * @since 1.0.0
+     */
     getDefaultValues() {
         return { ...this.defaultValues };
     }
+    /**
+     * Gets environment-specific values
+     * @returns Environment values object
+     *
+     * @since 1.0.0
+     */
     getEnvValues() {
         return { ...this.envValues };
     }
+    /**
+     * Gets all assets (CRDs, etc.)
+     * @returns Array of assets
+     *
+     * @since 1.0.0
+     */
     getAssets() {
         return [...this.assets];
     }
+    /**
+     * Converts the chart to SynthAsset array for HelmChartWriter
+     * @returns Array of synthesized assets
+     *
+     * @since 2.8.0+
+     */
     async toSynthArray() {
         const timer = this.logger.time('chart_synthesis');
         this.logger.debug('Starting chart synthesis', {
             chartName: this.meta.name,
             operation: 'synthesis_start',
         });
-        const apiObjectIds = [];
-        for (const child of this.chart.node.children) {
-            if (child instanceof ApiObject && !child.node.id.endsWith('-placeholder')) {
-                apiObjectIds.push(child.node.id);
-            }
-        }
+        // Get ApiObject IDs before synthesis, including ApiObjects nested inside
+        // cdk8s-plus constructs while excluding compatibility placeholders.
+        const apiObjectIds = this.getSynthesizedApiObjectIds();
+        // Use cdk8s Testing.synth to obtain manifest objects, but filter out placeholders
         const allManifestObjs = Testing.synth(this.chart);
         const manifestObjs = allManifestObjs.filter((obj) => {
             if (obj && typeof obj === 'object') {
@@ -231,6 +598,7 @@ ${yamlContent.trim()}
             apiObjectCount: apiObjectIds.length,
             operation: 'manifest_processing',
         });
+        // Optional policy validation BEFORE enrichment to allow policies to control label injection
         if (this.props.policyEngine) {
             this.logger.debug('Starting policy validation before enrichment', {
                 chartName: this.meta.name,
@@ -248,6 +616,7 @@ ${yamlContent.trim()}
                     });
                     throw new Error(`Policy validation failed: ${errorMessage}`);
                 }
+                // Log warnings but continue
                 if (validationResult.warnings.length > 0) {
                     this.logger.warn('Policy validation warnings', {
                         chartName: this.meta.name,
@@ -276,7 +645,12 @@ ${yamlContent.trim()}
                 throw error;
             }
         }
+        // Enforce common labels best-practice on all rendered objects
+        // IMPORTANT: Also pre-process HelmConstructs AFTER Testing.synth serializes the objects
+        // This ensures that field-level conditionals are detected and transformed
+        // even though cdk8s may have removed the original HelmConstruct structure
         const enriched = manifestObjs.map((obj) => {
+            // First, pre-process HelmConstructs to detect field-level conditionals
             const preprocessed = preprocessHelmConstructs(obj);
             if (preprocessed && typeof preprocessed === 'object') {
                 const o = preprocessed;
@@ -291,8 +665,10 @@ ${yamlContent.trim()}
                     'app.kubernetes.io/managed-by': '{{ .Release.Service }}',
                     'app.kubernetes.io/part-of': '{{ .Chart.Name }}',
                 };
+                // Apply defaults only if not already set
                 for (const [key, value] of Object.entries(defaults)) {
                     if (!(key in labels)) {
+                        // eslint-disable-next-line security/detect-object-injection -- Safe: controlled label assignment
                         labels[key] = value;
                     }
                 }
@@ -301,6 +677,7 @@ ${yamlContent.trim()}
         });
         const synthAssets = [];
         if (this.props.singleManifestFile) {
+            // Combine all resources into single manifest
             const combinedYaml = enriched
                 .map((obj) => dumpHelmAwareYaml(obj).trim())
                 .filter(Boolean)
@@ -309,15 +686,19 @@ ${yamlContent.trim()}
             synthAssets.push({ id: manifestId, yaml: combinedYaml, target: 'templates' });
         }
         else {
+            // Create separate files for each resource (default behavior)
             enriched.forEach((obj, index) => {
+                // eslint-disable-next-line security/detect-object-injection
                 const apiObjectId = apiObjectIds[index];
                 const manifestId = apiObjectId || `manifest-${index + 1}`;
                 const yaml = dumpHelmAwareYaml(obj).trim();
                 if (yaml) {
+                    // Use descriptive name from ApiObject ID if available, otherwise fallback to generic name
                     synthAssets.push({ id: manifestId, yaml, target: 'templates' });
                 }
             });
         }
+        // Add any additional assets (CRDs, etc.)
         this.assets.forEach((asset) => {
             synthAssets.push({
                 id: asset.id,
@@ -331,10 +712,18 @@ ${yamlContent.trim()}
             additionalAssets: this.assets.length,
             operation: 'synthesis_complete',
         });
-        timer();
+        timer(); // Complete timing measurement
         return synthAssets;
     }
+    /**
+     * Synchronous version of toSynthArray for backward compatibility
+     * @returns Array of synthesized assets
+     * @deprecated Use toSynthArray() instead for proper async handling
+     * @since 2.8.0+
+     */
     toSynthArraySync() {
+        // For backward compatibility, we need to handle the case where no policy engine is used
+        // In this case, we can run synchronously
         if (this.props.policyEngine) {
             throw new Error('toSynthArraySync() cannot be used with policy engine. Use toSynthArray() instead.');
         }
@@ -343,12 +732,10 @@ ${yamlContent.trim()}
             chartName: this.meta.name,
             operation: 'synthesis_start_sync',
         });
-        const apiObjectIds = [];
-        for (const child of this.chart.node.children) {
-            if (child instanceof ApiObject && !child.node.id.endsWith('-placeholder')) {
-                apiObjectIds.push(child.node.id);
-            }
-        }
+        // Get ApiObject IDs before synthesis, including ApiObjects nested inside
+        // cdk8s-plus constructs while excluding compatibility placeholders.
+        const apiObjectIds = this.getSynthesizedApiObjectIds();
+        // Use cdk8s Testing.synth to obtain manifest objects, but filter out placeholders
         const allManifestObjs = Testing.synth(this.chart);
         const manifestObjs = allManifestObjs.filter((obj) => {
             if (obj && typeof obj === 'object') {
@@ -364,7 +751,9 @@ ${yamlContent.trim()}
             apiObjectCount: apiObjectIds.length,
             operation: 'manifest_processing_sync',
         });
+        // Enforce common labels best-practice on all rendered objects
         const enriched = manifestObjs.map((obj) => {
+            // First, pre-process HelmConstructs to detect field-level conditionals
             const preprocessed = preprocessHelmConstructs(obj);
             if (preprocessed && typeof preprocessed === 'object') {
                 const o = preprocessed;
@@ -379,8 +768,10 @@ ${yamlContent.trim()}
                     'app.kubernetes.io/managed-by': '{{ .Release.Service }}',
                     'app.kubernetes.io/part-of': '{{ .Chart.Name }}',
                 };
+                // Apply defaults only if not already set
                 for (const [key, value] of Object.entries(defaults)) {
                     if (!(key in labels)) {
+                        // eslint-disable-next-line security/detect-object-injection -- Safe: controlled label assignment
                         labels[key] = value;
                     }
                 }
@@ -389,6 +780,7 @@ ${yamlContent.trim()}
         });
         const synthAssets = [];
         if (this.props.singleManifestFile) {
+            // Combine all resources into single manifest
             const combinedYaml = enriched
                 .map((obj) => dumpHelmAwareYaml(obj).trim())
                 .filter(Boolean)
@@ -397,15 +789,19 @@ ${yamlContent.trim()}
             synthAssets.push({ id: manifestId, yaml: combinedYaml, target: 'templates' });
         }
         else {
+            // Create separate files for each resource (default behavior)
             enriched.forEach((obj, index) => {
+                // eslint-disable-next-line security/detect-object-injection
                 const apiObjectId = apiObjectIds[index];
                 const manifestId = apiObjectId || `manifest-${index + 1}`;
                 const yaml = dumpHelmAwareYaml(obj).trim();
                 if (yaml) {
+                    // Use descriptive name from ApiObject ID if available, otherwise fallback to generic name
                     synthAssets.push({ id: manifestId, yaml, target: 'templates' });
                 }
             });
         }
+        // Add any additional assets (CRDs, etc.)
         this.assets.forEach((asset) => {
             synthAssets.push({
                 id: asset.id,
@@ -419,9 +815,15 @@ ${yamlContent.trim()}
             additionalAssets: this.assets.length,
             operation: 'synthesis_complete_sync',
         });
-        timer();
+        timer(); // Complete timing measurement
         return synthAssets;
     }
+    /**
+     * Formats policy validation errors into a readable error message
+     * @param result - Policy validation result
+     * @returns Formatted error message
+     * @private
+     */
     formatPolicyErrors(result) {
         const errorMessages = [];
         if (result.violations && result.violations.length > 0) {
@@ -446,6 +848,12 @@ ${yamlContent.trim()}
         }
         return errorMessages.join('\n');
     }
+    /**
+     * Writes the Helm chart to the specified output directory
+     * @param outDir - Output directory path
+     *
+     * @since 1.0.0
+     */
     async write(outDir) {
         const timer = this.logger.time('chart_write');
         this.logger.info('Starting chart write operation', {
@@ -453,6 +861,7 @@ ${yamlContent.trim()}
             outputDirectory: outDir,
             operation: 'chart_write_start',
         });
+        // Generate helpers template
         let helpersContent;
         if (this.props.helpersTpl) {
             if (typeof this.props.helpersTpl === 'string') {
@@ -470,6 +879,7 @@ ${helper.template}
             }
         }
         else {
+            // Auto-generate standard helpers
             helpersContent = generateHelpersTemplate(this.props.cloudProvider);
         }
         const synthAssets = await this.toSynthArray();
@@ -492,7 +902,8 @@ ${helper.template}
             outputDirectory: outDir,
             operation: 'chart_write_complete',
         });
-        timer();
+        timer(); // Complete timing measurement
     }
 }
+// Constants for labels
 Rutter.HELPER_NAME = 'chart.name';