helm-env-delta 1.5.0 → 1.6.0

package/README.md

@@ -50,6 +50,8 @@ HelmEnvDelta (`hed`) automates environment synchronization for GitOps workflows
 
 🔍 **Discovery Tools** - Preview files (`--list-files`), inspect config (`--show-config`), validate with warnings.
 
+💡 **Smart Suggestions** - Heuristic analysis (`--suggest`) detects patterns and recommends transforms and stop rules automatically. Control sensitivity with `--suggest-threshold`.
+
 🛡️ **Safety First** - Pre-execution summary, first-run tips, improved error messages with helpful examples.
 
 ⚡ **High Performance** - 45-60% faster than alternatives with intelligent caching and parallel processing.
@@ -107,6 +109,17 @@ helm-env-delta --config config.yaml
 helm-env-delta --config config.yaml --diff-html
 ```
 
+### 5️⃣ Get Smart Suggestions (Optional)
+
+```bash
+helm-env-delta --config config.yaml --suggest
+
+# Control suggestion sensitivity (0-1, default: 0.3)
+helm-env-delta --config config.yaml --suggest --suggest-threshold 0.7
+```
+
+Analyzes differences and suggests transforms and stop rules automatically with configurable confidence filtering.
+
 **Done!** All files synced, production values preserved, changes validated.
 
 ---
@@ -241,6 +254,92 @@ helm-env-delta --config example/5-external-files/config.yaml --dry-run --diff
 
 ---
 
+## 💡 Smart Configuration Suggestions (Heuristic)
+
+The `--suggest` flag uses heuristic analysis to examine differences between environments and automatically recommend configuration updates. This intelligent pattern detection helps bootstrap your config by discovering repeated changes and potential safety rules.
+
+### How It Works
+
+```bash
+helm-env-delta --config config.yaml --suggest
+
+# Control suggestion sensitivity (higher threshold = fewer, higher-confidence suggestions)
+helm-env-delta --config config.yaml --suggest --suggest-threshold 0.7
+```
+
+**How heuristic analysis works:**
+
+- 🔍 Intelligently detects repeated value changes across files
+- 🎯 Suggests transform patterns (regex find/replace) based on semantic patterns
+- 🛡️ Recommends stop rules for safety validation using pattern recognition
+- 📊 Provides confidence scores and occurrence counts for each suggestion
+- 🎛️ **NEW:** Configurable threshold filters suggestions by confidence level (0-1)
+- 📝 Outputs copy-paste ready YAML configuration
+- ✨ **Enhanced noise filtering:**
+  - Ignores UUIDs, timestamps, single-character changes
+  - Filters antonym pairs (enable/disable, true/false, on/off)
+  - Filters regex special characters (unless semantic keywords present)
+  - Filters version-number-only changes (service-v1 → service-v2)
+  - Allows semantic patterns even with special chars (db.uat.com → db.prod.com)
+
+### Example Output
+
+```yaml
+# Suggested Transforms
+transforms:
+  '**/*.yaml':
+    content:
+      - find: 'uat-cluster'
+        replace: 'prod-cluster'
+        # Confidence: 95% (42 occurrences across 12 files)
+
+# Suggested Stop Rules
+stopRules:
+  '**/*.yaml':
+    - type: 'semverMajorUpgrade'
+      path: 'image.tag'
+      # Detected version changes: v1.2.3 → v2.0.0
+```
+
+### When to Use
+
+- 🚀 **First-time setup**: Let heuristics discover patterns automatically instead of manual analysis
+- 🔄 **Config refinement**: Find missing transforms or stop rules through smart detection
+- 📚 **Learning tool**: Understand what's changing between environments
+- ⚡ **Quick start**: Bootstrap configuration from existing files using intelligent pattern matching
+- 🧠 **Pattern discovery**: Leverage heuristic algorithms to identify semantic transformations (uat→prod, staging→production)
+- 🎯 **Confidence tuning**: Adjust threshold to balance between finding all patterns vs. high-confidence only
+
+**Confidence threshold control:**
+
+```bash
+# More suggestions (lower threshold = less strict)
+helm-env-delta --config config.yaml --suggest --suggest-threshold 0.2
+
+# Default balance (standard heuristics, threshold: 0.3)
+helm-env-delta --config config.yaml --suggest
+
+# Only high-confidence (higher threshold = more strict)
+helm-env-delta --config config.yaml --suggest --suggest-threshold 0.8
+```
+
+**Workflow:**
+
+```bash
+# 1. Get suggestions (optionally with custom threshold)
+helm-env-delta --config config.yaml --suggest --suggest-threshold 0.5 > suggestions.yaml
+
+# 2. Review and copy relevant sections to config.yaml
+
+# 3. Test with dry-run
+helm-env-delta --config config.yaml --dry-run --diff
+
+# 4. Execute
+helm-env-delta --config config.yaml
+```
+
+---
+
 ## ⚙️ Configuration Reference
 
 ### 🎯 Core Settings
@@ -511,21 +610,23 @@ hed --config <file> [options]  # Short alias
 
 ### Options
 
-| Flag              | Description                                      |
-| ----------------- | ------------------------------------------------ |
-| `--config <path>` | **Required** - Configuration file                |
-| `--validate`      | Validate config and exit (shows warnings)        |
-| `--dry-run`       | Preview changes without writing files            |
-| `--force`         | Override stop rules                              |
-| `--diff`          | Show console diff                                |
-| `--diff-html`     | Generate HTML report (opens in browser)          |
-| `--diff-json`     | Output JSON to stdout (pipe to jq)               |
-| `--list-files`    | List source/destination files without processing |
-| `--show-config`   | Display resolved config after inheritance        |
-| `--skip-format`   | Skip YAML formatting                             |
-| `--no-color`      | Disable colored output (CI/accessibility)        |
-| `--verbose`       | Show detailed debug info                         |
-| `--quiet`         | Suppress output except errors                    |
+| Flag                        | Description                                       |
+| --------------------------- | ------------------------------------------------- |
+| `--config <path>`           | **Required** - Configuration file                 |
+| `--validate`                | Validate config and exit (shows warnings)         |
+| `--suggest`                 | Analyze differences and suggest config updates    |
+| `--suggest-threshold <0-1>` | Minimum confidence for suggestions (default: 0.3) |
+| `--dry-run`                 | Preview changes without writing files             |
+| `--force`                   | Override stop rules                               |
+| `--diff`                    | Show console diff                                 |
+| `--diff-html`               | Generate HTML report (opens in browser)           |
+| `--diff-json`               | Output JSON to stdout (pipe to jq)                |
+| `--list-files`              | List source/destination files without processing  |
+| `--show-config`             | Display resolved config after inheritance         |
+| `--skip-format`             | Skip YAML formatting                              |
+| `--no-color`                | Disable colored output (CI/accessibility)         |
+| `--verbose`                 | Show detailed debug info                          |
+| `--quiet`                   | Suppress output except errors                     |
 
 ### Examples
 
@@ -533,6 +634,12 @@ hed --config <file> [options]  # Short alias
 # Validate configuration (shows warnings)
 hed --config config.yaml --validate
 
+# Get smart configuration suggestions
+hed --config config.yaml --suggest
+
+# Get only high-confidence suggestions
+hed --config config.yaml --suggest --suggest-threshold 0.7
+
 # Preview files that will be synced
 hed --config config.yaml --list-files
 

package/dist/commandLine.d.ts

@@ -12,5 +12,7 @@ export type SyncCommand = {
     listFiles: boolean;
     showConfig: boolean;
     noColor: boolean;
+    suggest: boolean;
+    suggestThreshold: number;
 };
 export declare const parseCommandLine: (argv?: string[]) => SyncCommand;

package/dist/commandLine.js

@@ -22,6 +22,8 @@ const parseCommandLine = (argv) => {
         .option('--validate', 'Validate configuration file and exit', false)
         .option('--list-files', 'List files that would be synced without processing diffs', false)
         .option('--show-config', 'Display resolved configuration after inheritance and exit', false)
+        .option('--suggest', 'Analyze differences and suggest transforms and stop rules', false)
+        .option('--suggest-threshold <number>', 'Minimum confidence for suggestions (0-1, default: 0.3)', '0.3')
         .option('--no-color', 'Disable colored output')
         .option('--verbose', 'Show detailed debug information', false)
         .option('--quiet', 'Suppress all output except critical errors', false)
@@ -30,6 +32,9 @@ Examples:
   # Preview changes before syncing
   $ helm-env-delta --config config.yaml --dry-run --diff
 
+  # Get configuration suggestions
+  $ helm-env-delta --config config.yaml --suggest
+
   # Sync with HTML diff report
   $ helm-env-delta --config config.yaml --diff-html
 
@@ -48,6 +53,11 @@ Documentation: https://github.com/balazscsaba2006/helm-env-delta
         console.error('Error: --verbose and --quiet flags are mutually exclusive');
         process.exit(1);
     }
+    const threshold = Number.parseFloat(options['suggestThreshold']);
+    if (Number.isNaN(threshold) || threshold < 0 || threshold > 1) {
+        console.error('Error: --suggest-threshold must be a number between 0 and 1');
+        process.exit(1);
+    }
     return {
         config: options['config'],
         dryRun: options['dryRun'],
@@ -61,7 +71,9 @@ Documentation: https://github.com/balazscsaba2006/helm-env-delta
         showConfig: options['showConfig'],
         noColor: !options['color'],
         verbose: options['verbose'],
-        quiet: options['quiet']
+        quiet: options['quiet'],
+        suggest: options['suggest'],
+        suggestThreshold: threshold
     };
 };
 exports.parseCommandLine = parseCommandLine;

package/dist/fileDiff.d.ts

@@ -14,6 +14,7 @@ export interface ChangedFile {
     processedDestContent: unknown;
     rawParsedSource: unknown;
     rawParsedDest: unknown;
+    skipPaths: string[];
     normalizedSource?: unknown;
     normalizedDest?: unknown;
     parsedSource?: unknown;

package/dist/fileDiff.js

@@ -134,6 +134,7 @@ const processYamlFile = (filePath, sourceContent, destinationContent, skipPath,
         processedDestContent: normalizedDestination,
         rawParsedSource: sourceFiltered,
         rawParsedDest: destinationFiltered,
+        skipPaths: pathsToSkip,
         normalizedSource,
         normalizedDest: normalizedDestination,
         parsedSource: sourceParsed,
@@ -165,7 +166,8 @@ const processChangedFiles = (sourceFiles, destinationFiles, skipPath, transforms
                 processedSourceContent: sourceContent,
                 processedDestContent: destinationContent,
                 rawParsedSource: sourceContent,
-                rawParsedDest: destinationContent
+                rawParsedDest: destinationContent,
+                skipPaths: []
             });
     }
     return { changedFiles, unchangedFiles };

package/dist/index.js

@@ -55,6 +55,7 @@ const htmlReporter_1 = require("./htmlReporter");
 const jsonReporter_1 = require("./jsonReporter");
 const logger_1 = require("./logger");
 const stopRulesValidator_1 = require("./stopRulesValidator");
+const suggestionEngine_1 = require("./suggestionEngine");
 const collisionDetector_1 = require("./utils/collisionDetector");
 const filenameTransformer_1 = require("./utils/filenameTransformer");
 const versionChecker_1 = require("./utils/versionChecker");
@@ -147,6 +148,29 @@ const main = async () => {
         logger.log(`  Changed files: ${diffResult.changedFiles.length}`);
         logger.log(`  Unchanged files: ${diffResult.unchangedFiles.length}`);
     }
+    if (command.suggest) {
+        logger.log('\n' + (0, consoleFormatter_1.formatProgressMessage)('Analyzing differences for suggestions...', 'info'));
+        try {
+            const suggestions = (0, suggestionEngine_1.analyzeDifferencesForSuggestions)(diffResult, config, command.suggestThreshold);
+            const yaml = (0, suggestionEngine_1.formatSuggestionsAsYaml)(suggestions);
+            console.log(chalk_1.default.cyan('\n💡 Suggested Configuration:\n'));
+            console.log(yaml);
+            if (suggestions.metadata.changedFiles === 0)
+                console.log(chalk_1.default.yellow('\nℹ️  No changes detected. Files are already in sync.'));
+            else {
+                console.log(chalk_1.default.dim('\n---'));
+                console.log(chalk_1.default.dim('💡 Tip: Copy relevant sections to your config.yaml and test with --dry-run'));
+            }
+            return;
+        }
+        catch (error) {
+            if ((0, suggestionEngine_1.isSuggestionEngineError)(error)) {
+                logger.error('\nFailed to generate suggestions: ' + error.message, 'critical');
+                process.exit(1);
+            }
+            throw error;
+        }
+    }
     const configFileDirectory = node_path_1.default.dirname(node_path_1.default.resolve(command.config));
     const validationResult = (0, stopRulesValidator_1.validateStopRules)(diffResult, config.stopRules, configFileDirectory, logger);
     if (validationResult.violations.length > 0)
@@ -204,6 +228,8 @@ const main = async () => {
             console.error(error.message);
         else if ((0, jsonReporter_1.isJsonReporterError)(error))
             console.error(error.message);
+        else if ((0, suggestionEngine_1.isSuggestionEngineError)(error))
+            console.error(error.message);
         else if (error instanceof Error)
             console.error('Unexpected error:', error.message);
         else

package/dist/suggestionEngine.d.ts

@@ -0,0 +1,51 @@
+import { Config, StopRule } from './configFile';
+import { FileDiffResult } from './fileDiff';
+export interface ValuePair {
+    oldValue: string;
+    targetValue: string;
+    path: string;
+}
+export interface TransformSuggestion {
+    find: string;
+    replace: string;
+    confidence: number;
+    occurrences: number;
+    affectedFiles: string[];
+    examples: ValuePair[];
+}
+export interface StopRuleSuggestion {
+    rule: StopRule;
+    confidence: number;
+    reason: string;
+    affectedPaths: string[];
+    affectedFiles: string[];
+}
+export interface SuggestionResult {
+    transforms: Map<string, TransformSuggestion[]>;
+    stopRules: Map<string, StopRuleSuggestion[]>;
+    metadata: {
+        filesAnalyzed: number;
+        changedFiles: number;
+        timestamp: string;
+    };
+}
+declare const SuggestionEngineErrorClass: {
+    new (message: string, options?: import("./utils/errors").ErrorOptions): {
+        [key: string]: unknown;
+        readonly code?: string;
+        readonly path?: string;
+        readonly cause?: Error;
+        name: string;
+        message: string;
+        stack?: string;
+    };
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+};
+export declare class SuggestionEngineError extends SuggestionEngineErrorClass {
+}
+export declare const isSuggestionEngineError: (error: unknown) => error is SuggestionEngineError;
+export declare const analyzeDifferencesForSuggestions: (diffResult: FileDiffResult, config: Config, confidenceThreshold?: number) => SuggestionResult;
+export declare const formatSuggestionsAsYaml: (result: SuggestionResult) => string;
+export {};