helm-env-delta 1.6.0 → 1.7.1

package/README.md

@@ -48,7 +48,7 @@ HelmEnvDelta (`hed`) automates environment synchronization for GitOps workflows
 
 📊 **Multiple Reports** - Console, HTML (visual), and JSON (CI/CD) output formats.
 
-🔍 **Discovery Tools** - Preview files (`--list-files`), inspect config (`--show-config`), validate with warnings.
+🔍 **Discovery Tools** - Preview files (`--list-files`), inspect config (`--show-config`), validate with comprehensive warnings including unused pattern detection.
 
 💡 **Smart Suggestions** - Heuristic analysis (`--suggest`) detects patterns and recommends transforms and stop rules automatically. Control sensitivity with `--suggest-threshold`.
 
@@ -374,7 +374,26 @@ skipPath:
     - 'resources.limits'
 ```
 
-**Use cases:** Namespaces, replicas, resource limits, secrets, URLs.
+#### Filter Expressions (Skip by Name)
+
+Skip specific array items by property value using filter syntax:
+
+```yaml
+skipPath:
+  '**/*.yaml':
+    - 'env[name=SECRET_KEY]' # Skip item where name=SECRET_KEY
+    - 'env[name=INTERNAL_TOKEN].value' # Skip nested field in matching item
+    - 'containers[name=sidecar]' # Skip entire sidecar container
+    - 'spec.containers[name=app].env[name=DEBUG]' # Nested filters
+```
+
+**Syntax:**
+
+- `array[prop=value]` - Match items where property equals value
+- `array[prop="value with spaces"]` - Quoted values for special characters
+- Combine with wildcards: `containers[name=app].env[*].value`
+
+**Use cases:** Namespaces, replicas, resource limits, secrets, URLs, environment-specific array items.
 
 ---
 
@@ -610,23 +629,23 @@ hed --config <file> [options]  # Short alias
 
 ### Options
 
-| 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                     |
+| Flag                        | Description                                        |
+| --------------------------- | -------------------------------------------------- |
+| `--config <path>`           | **Required** - Configuration file                  |
+| `--validate`                | Validate config and pattern usage (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
 
@@ -730,7 +749,7 @@ git push origin main
 
 ✅ **Flexibility** - Per-file patterns. Config inheritance. Regex transforms.
 
-✅ **Reliability** - 787 tests, 84% coverage. Battle-tested.
+✅ **Reliability** - 917 tests, 84% coverage. Battle-tested.
 
 ---
 
@@ -824,6 +843,57 @@ env:
 
 ---
 
+### 🔍 Pattern Usage Validation
+
+HelmEnvDelta validates that your configuration patterns actually match files and exist in your YAML structure. This helps catch typos, outdated patterns, and misconfigured rules early.
+
+**Run validation:**
+
+```bash
+helm-env-delta --config config.yaml --validate
+```
+
+**What gets validated:**
+
+1. **exclude patterns** - Warns if pattern matches no files
+2. **skipPath patterns** - Two-level validation:
+   - Glob pattern must match at least one file
+   - JSONPath must exist in at least one matched file
+   - Filter expressions `[prop=value]` validated against actual array items
+3. **stopRules patterns** - Two-level validation:
+   - Glob pattern must match at least one file
+   - JSONPath (if specified) must exist in at least one matched file
+
+**Example output:**
+
+```
+✓ Configuration is valid
+
+⚠️  Pattern Usage Warnings (non-fatal):
+
+  • Exclude pattern 'test/**/*.yaml' matches no files
+  • skipPath pattern 'legacy/*.yaml' matches no files
+  • skipPath JSONPath 'microservice.replicaCountX' not found in any matched files (Pattern: svc/**/values.yaml, matches 50 file(s))
+  • stopRules glob pattern 'helm-charts/**/*.yaml' matches no files (3 rule(s) defined)
+  • stopRules JSONPath 'spec.replicas' not found in any matched files (Rule type: numeric, matches 5 file(s))
+```
+
+**Validation phases:**
+
+- **Phase 1 (Static)**: Validates config syntax, checks for inefficient patterns, duplicates, conflicts
+- **Phase 2 (File-Based)**: Loads files and validates all patterns actually match and paths exist
+
+**When to use:**
+
+- After updating configuration
+- When patterns stop working as expected
+- To verify config file patterns after file reorganization
+- As part of CI/CD pre-flight checks
+
+**Important:** Warnings are non-fatal and don't block execution. They help you catch potential issues but won't stop your workflow.
+
+---
+
 ### 🔀 Deep Merge
 
 Preserves destination values for skipped paths.
@@ -880,6 +950,8 @@ spec:
 # ✅ Correct
 - 'spec.replicas' # No prefix
 - 'env[*].name' # Array wildcard
+- 'env[name=DEBUG]' # Filter by property value
+- 'containers[name=app].env[name=SECRET]' # Nested filters
 ```
 
 ---

package/dist/configMerger.d.ts

@@ -5,6 +5,7 @@ declare const ConfigMergerErrorClass: {
         readonly code?: string;
         readonly path?: string;
         readonly cause?: Error;
+        readonly hints?: string[];
         name: string;
         message: string;
         stack?: string;

package/dist/configMerger.js

@@ -41,6 +41,7 @@ const node_fs_1 = require("node:fs");
 const node_path_1 = __importDefault(require("node:path"));
 const YAML = __importStar(require("yaml"));
 const configFile_1 = require("./configFile");
+const constants_1 = require("./constants");
 const errors_1 = require("./utils/errors");
 const ConfigMergerErrorClass = (0, errors_1.createErrorClass)('Config Merger Error', {
     CIRCULAR_DEPENDENCY: 'Circular dependency detected in extends chain',
@@ -69,7 +70,6 @@ class ConfigMergerError extends ConfigMergerErrorClass {
 }
 exports.ConfigMergerError = ConfigMergerError;
 exports.isConfigMergerError = (0, errors_1.createErrorTypeGuard)(ConfigMergerError);
-const MAX_EXTENDS_DEPTH = 5;
 const mergeConfigs = (parent, child) => {
     const merged = {};
     if (child.source !== undefined)
@@ -143,14 +143,14 @@ const mergePerFileRecords = (parent, child) => {
     return merged;
 };
 const resolveConfigWithExtends = (configPath, visited = new Set(), depth = 0, logger) => {
-    if (depth > MAX_EXTENDS_DEPTH) {
-        const depthError = new ConfigMergerError('Extends chain exceeds maximum depth of 5', {
+    if (depth > constants_1.MAX_CONFIG_EXTENDS_DEPTH) {
+        const depthError = new ConfigMergerError(`Extends chain exceeds maximum depth of ${constants_1.MAX_CONFIG_EXTENDS_DEPTH}`, {
             code: 'MAX_DEPTH_EXCEEDED',
             path: configPath,
             depth
         });
         depthError.message += '\n\n  Hint: Simplify your config inheritance:';
-        depthError.message += '\n    - Maximum depth is 5 levels';
+        depthError.message += `\n    - Maximum depth is ${constants_1.MAX_CONFIG_EXTENDS_DEPTH} levels`;
         depthError.message += `\n    - Current depth: ${depth}`;
         depthError.message += '\n    - Consider consolidating base configs';
         throw depthError;

package/dist/configWarnings.d.ts

@@ -1,2 +1,6 @@
 import type { FinalConfig } from './configFile';
-export declare const validateConfigWarnings: (config: FinalConfig) => string[];
+export interface WarningResult {
+    warnings: string[];
+    hasWarnings: boolean;
+}
+export declare const validateConfigWarnings: (config: FinalConfig) => WarningResult;

package/dist/configWarnings.js

@@ -24,6 +24,9 @@ const validateConfigWarnings = (config) => {
         for (const [pattern, rules] of Object.entries(config.transforms))
             if ((rules.content?.length ?? 0) === 0 && (rules.filename?.length ?? 0) === 0)
                 warnings.push(`Transform pattern '${pattern}' has empty content and filename arrays (will have no effect)`);
-    return warnings;
+    return {
+        warnings,
+        hasWarnings: warnings.length > 0
+    };
 };
 exports.validateConfigWarnings = validateConfigWarnings;

package/dist/consoleDiffReporter.js

@@ -6,12 +6,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.showConsoleDiff = void 0;
 const chalk_1 = __importDefault(require("chalk"));
 const yaml_1 = __importDefault(require("yaml"));
-const arrayDiffer_1 = require("./arrayDiffer");
 const fileDiff_1 = require("./fileDiff");
-const deepEqual_1 = require("./utils/deepEqual");
+const arrayDiffProcessor_1 = require("./utils/arrayDiffProcessor");
 const diffGenerator_1 = require("./utils/diffGenerator");
 const fileType_1 = require("./utils/fileType");
-const jsonPath_1 = require("./utils/jsonPath");
 const serialization_1 = require("./utils/serialization");
 const colorizeUnifiedDiff = (diff) => {
     return diff
@@ -41,29 +39,28 @@ const formatDeletedFiles = (files) => {
     const fileList = files.map((file) => chalk_1.default.red(`  - ${file}`)).join('\n');
     return `${header}\n${fileList}\n`;
 };
-const formatArrayDiff = (sourceArray, destinationArray) => {
-    const diff = (0, arrayDiffer_1.diffArrays)(sourceArray, destinationArray);
+const formatArrayDiff = (change) => {
     let output = '';
-    if (diff.removed.length > 0) {
-        output += chalk_1.default.red.bold(`\n  Removed (${diff.removed.length}):\n`);
-        for (const item of diff.removed) {
+    if (change.removed.length > 0) {
+        output += chalk_1.default.red.bold(`\n  Removed (${change.removed.length}):\n`);
+        for (const item of change.removed) {
             const yaml = yaml_1.default.stringify(item, { indent: 4 });
             const lines = yaml.split('\n').filter((l) => l.trim());
             output += lines.map((l) => chalk_1.default.red(`    - ${l}`)).join('\n');
             output += '\n';
         }
     }
-    if (diff.added.length > 0) {
-        output += chalk_1.default.green.bold(`\n  Added (${diff.added.length}):\n`);
-        for (const item of diff.added) {
+    if (change.added.length > 0) {
+        output += chalk_1.default.green.bold(`\n  Added (${change.added.length}):\n`);
+        for (const item of change.added) {
             const yaml = yaml_1.default.stringify(item, { indent: 4 });
             const lines = yaml.split('\n').filter((l) => l.trim());
             output += lines.map((l) => chalk_1.default.green(`    + ${l}`)).join('\n');
             output += '\n';
         }
     }
-    if (diff.unchanged.length > 0)
-        output += chalk_1.default.gray(`\n  Unchanged: ${diff.unchanged.length} items\n`);
+    if (change.unchanged.length > 0)
+        output += chalk_1.default.gray(`\n  Unchanged: ${change.unchanged.length} items\n`);
     return output;
 };
 const formatChangedFile = (file, config) => {
@@ -86,8 +83,8 @@ ${skipPathInfo}
 ${colorizedDiff}
 `;
     }
-    const hasArraysInFile = (0, arrayDiffer_1.hasArrays)(file.rawParsedSource) || (0, arrayDiffer_1.hasArrays)(file.rawParsedDest);
-    if (!hasArraysInFile) {
+    const arrayInfo = (0, arrayDiffProcessor_1.detectArrayChanges)(file);
+    if (!arrayInfo.hasArrays) {
         const destinationContent = (0, serialization_1.serializeForDiff)(file.processedDestContent, true);
         const sourceContent = (0, serialization_1.serializeForDiff)(file.processedSourceContent, true);
         const unifiedDiff = (0, diffGenerator_1.generateUnifiedDiff)(file.path, destinationContent, sourceContent);
@@ -106,30 +103,12 @@ ${colorizedDiff}
     const unifiedDiff = (0, diffGenerator_1.generateUnifiedDiff)(file.path, destinationContent, sourceContent);
     const colorizedDiff = colorizeUnifiedDiff(unifiedDiff);
     output += `\n${colorizedDiff}\n`;
-    const arrayPaths = (0, arrayDiffer_1.findArrayPaths)(file.rawParsedSource);
-    const hasArrayChanges = arrayPaths.some((path) => {
-        const sourceArray = (0, jsonPath_1.getValueAtPath)(file.rawParsedSource, path);
-        const destinationArray = (0, jsonPath_1.getValueAtPath)(file.rawParsedDest, path);
-        if (!Array.isArray(sourceArray) || !Array.isArray(destinationArray))
-            return false;
-        return !(0, deepEqual_1.deepEqual)((0, serialization_1.normalizeForComparison)(sourceArray), (0, serialization_1.normalizeForComparison)(destinationArray));
-    });
-    if (hasArrayChanges) {
+    if (arrayInfo.hasChanges) {
         output += chalk_1.default.cyan.bold('\nArray-specific details:\n');
-        for (const path of arrayPaths) {
-            const pathString = path.join('.');
-            const sourceArray = (0, jsonPath_1.getValueAtPath)(file.rawParsedSource, path);
-            const destinationArray = (0, jsonPath_1.getValueAtPath)(file.rawParsedDest, path);
-            if (!Array.isArray(sourceArray))
-                continue;
-            if (!Array.isArray(destinationArray))
-                continue;
-            const normalizedSource = (0, serialization_1.normalizeForComparison)(sourceArray);
-            const normalizedDestination = (0, serialization_1.normalizeForComparison)(destinationArray);
-            if ((0, deepEqual_1.deepEqual)(normalizedSource, normalizedDestination))
-                continue;
+        for (const change of arrayInfo.changes) {
+            const pathString = change.path.join('.');
             output += chalk_1.default.cyan(`\n  ${pathString}:\n`);
-            output += formatArrayDiff(normalizedSource, normalizedDestination);
+            output += formatArrayDiff(change);
         }
     }
     return output;

package/dist/constants.d.ts

@@ -0,0 +1,5 @@
+export declare const SYNC_CONFIRMATION_DELAY_MS = 2000;
+export declare const YAML_LINE_WIDTH_UNLIMITED = 0;
+export declare const YAML_DEFAULT_INDENT = 2;
+export declare const MAX_CONFIG_EXTENDS_DEPTH = 5;
+export declare const SEMVER_STRICT_PATTERN: RegExp;

package/dist/constants.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SEMVER_STRICT_PATTERN = exports.MAX_CONFIG_EXTENDS_DEPTH = exports.YAML_DEFAULT_INDENT = exports.YAML_LINE_WIDTH_UNLIMITED = exports.SYNC_CONFIRMATION_DELAY_MS = void 0;
+exports.SYNC_CONFIRMATION_DELAY_MS = 2000;
+exports.YAML_LINE_WIDTH_UNLIMITED = 0;
+exports.YAML_DEFAULT_INDENT = 2;
+exports.MAX_CONFIG_EXTENDS_DEPTH = 5;
+exports.SEMVER_STRICT_PATTERN = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;

package/dist/fileDiff.d.ts

@@ -1,4 +1,4 @@
-import { Config } from './configFile';
+import { Config, TransformConfig } from './configFile';
 import { FileMap } from './fileLoader';
 export interface FileDiffResult {
     addedFiles: string[];
@@ -8,6 +8,7 @@ export interface FileDiffResult {
 }
 export interface ChangedFile {
     path: string;
+    originalPath?: string;
     sourceContent: string;
     destinationContent: string;
     processedSourceContent: unknown;
@@ -20,12 +21,20 @@ export interface ChangedFile {
     parsedSource?: unknown;
     parsedDest?: unknown;
 }
+export interface ProcessYamlOptions {
+    filePath: string;
+    sourceContent: string;
+    destinationContent: string;
+    skipPath?: Record<string, string[]>;
+    transforms?: TransformConfig;
+}
 declare const FileDiffErrorClass: {
     new (message: string, options?: import("./utils/errors").ErrorOptions): {
         [key: string]: unknown;
         readonly code?: string;
         readonly path?: string;
         readonly cause?: Error;
+        readonly hints?: string[];
         name: string;
         message: string;
         stack?: string;
@@ -38,5 +47,5 @@ export declare class FileDiffError extends FileDiffErrorClass {
 }
 export declare const isFileDiffError: (error: unknown) => error is FileDiffError;
 export declare const getSkipPathsForFile: (filePath: string, skipPath?: Record<string, string[]>) => string[];
-export declare const computeFileDiff: (sourceFiles: FileMap, destinationFiles: FileMap, config: Config, logger?: import("./logger").Logger) => FileDiffResult;
+export declare const computeFileDiff: (sourceFiles: FileMap, destinationFiles: FileMap, config: Config, logger?: import("./logger").Logger, originalPaths?: Map<string, string>) => FileDiffResult;
 export {};

package/dist/fileDiff.js

@@ -41,6 +41,30 @@ const deleteJsonPathRecursive = (object, parts, index) => {
     const currentPart = parts[index];
     if (!currentPart)
         return;
+    if ((0, jsonPath_1.isFilterSegment)(currentPart)) {
+        if (!Array.isArray(object))
+            return;
+        const filter = (0, jsonPath_1.parseFilterSegment)(currentPart);
+        if (!filter)
+            return;
+        if (index === parts.length - 1)
+            for (let index_ = object.length - 1; index_ >= 0; index_--) {
+                const item = object[index_];
+                if (item && typeof item === 'object') {
+                    const itemValue = item[filter.property];
+                    if (String(itemValue) === filter.value)
+                        object.splice(index_, 1);
+                }
+            }
+        else
+            for (const item of object)
+                if (item && typeof item === 'object') {
+                    const itemValue = item[filter.property];
+                    if (String(itemValue) === filter.value)
+                        deleteJsonPathRecursive(item, parts, index + 1);
+                }
+        return;
+    }
     if (index === parts.length - 1) {
         if (currentPart === '*' && Array.isArray(object))
             object.length = 0;
@@ -80,7 +104,8 @@ const getSkipPathsForFile = (filePath, skipPath) => {
     return pathsToSkip;
 };
 exports.getSkipPathsForFile = getSkipPathsForFile;
-const processYamlFile = (filePath, sourceContent, destinationContent, skipPath, transforms) => {
+const processYamlFile = (options) => {
+    const { filePath, sourceContent, destinationContent, skipPath, transforms } = options;
     let sourceParsed;
     let destinationParsed;
     try {
@@ -141,18 +166,28 @@ const processYamlFile = (filePath, sourceContent, destinationContent, skipPath,
         parsedDest: destinationParsed
     };
 };
-const processChangedFiles = (sourceFiles, destinationFiles, skipPath, transforms) => {
+const processChangedFiles = (sourceFiles, destinationFiles, skipPath, transforms, originalPaths) => {
     const changedFiles = [];
     const unchangedFiles = [];
     for (const [path, sourceContent] of sourceFiles.entries()) {
         if (!destinationFiles.has(path))
             continue;
         const destinationContent = destinationFiles.get(path);
+        const originalPath = originalPaths?.get(path);
         const isYaml = (0, fileType_1.isYamlFile)(path);
         if (isYaml) {
-            const changed = processYamlFile(path, sourceContent, destinationContent, skipPath, transforms);
-            if (changed)
+            const changed = processYamlFile({
+                filePath: path,
+                sourceContent,
+                destinationContent,
+                skipPath,
+                transforms
+            });
+            if (changed) {
+                if (originalPath)
+                    changed.originalPath = originalPath;
                 changedFiles.push(changed);
+            }
             else
                 unchangedFiles.push(path);
         }
@@ -161,6 +196,7 @@ const processChangedFiles = (sourceFiles, destinationFiles, skipPath, transforms
         else
             changedFiles.push({
                 path,
+                originalPath,
                 sourceContent,
                 destinationContent: destinationContent,
                 processedSourceContent: sourceContent,
@@ -172,7 +208,7 @@ const processChangedFiles = (sourceFiles, destinationFiles, skipPath, transforms
     }
     return { changedFiles, unchangedFiles };
 };
-const computeFileDiff = (sourceFiles, destinationFiles, config, logger) => {
+const computeFileDiff = (sourceFiles, destinationFiles, config, logger, originalPaths) => {
     if (logger?.shouldShow('debug')) {
         logger.debug('Computing file differences:');
         logger.debug(`  Source files: ${sourceFiles.size}`);
@@ -186,7 +222,7 @@ const computeFileDiff = (sourceFiles, destinationFiles, config, logger) => {
     }
     const addedFiles = detectAddedFiles(sourceFiles, destinationFiles);
     const deletedFiles = config.prune ? detectDeletedFiles(sourceFiles, destinationFiles) : [];
-    const { changedFiles, unchangedFiles } = processChangedFiles(sourceFiles, destinationFiles, config.skipPath, config.transforms);
+    const { changedFiles, unchangedFiles } = processChangedFiles(sourceFiles, destinationFiles, config.skipPath, config.transforms, originalPaths);
     return { addedFiles, deletedFiles, changedFiles, unchangedFiles };
 };
 exports.computeFileDiff = computeFileDiff;

package/dist/fileLoader.d.ts

@@ -6,12 +6,17 @@ export interface FileLoaderOptions {
     transforms?: TransformConfig;
 }
 export type FileMap = Map<string, string>;
+export interface FileLoaderResult {
+    fileMap: FileMap;
+    originalPaths: Map<string, string>;
+}
 declare const FileLoaderErrorClass: {
     new (message: string, options?: import("./utils/errors").ErrorOptions): {
         [key: string]: unknown;
         readonly code?: string;
         readonly path?: string;
         readonly cause?: Error;
+        readonly hints?: string[];
         name: string;
         message: string;
         stack?: string;
@@ -23,5 +28,5 @@ declare const FileLoaderErrorClass: {
 export declare class FileLoaderError extends FileLoaderErrorClass {
 }
 export declare const isFileLoaderError: (error: unknown) => error is FileLoaderError;
-export declare const loadFiles: (options: FileLoaderOptions, logger?: import("./logger").Logger) => Promise<FileMap>;
+export declare const loadFiles: (options: FileLoaderOptions, logger?: import("./logger").Logger) => Promise<FileLoaderResult>;
 export {};

package/dist/fileLoader.js

@@ -162,20 +162,20 @@ const loadFiles = async (options, logger) => {
         logger.debug(`  Matched: ${files.length} file(s)`);
     }
     const fileMap = await readFilesIntoMap(absoluteBaseDirectory, files);
-    const transformedMap = options.transforms ? (0, filenameTransformer_1.transformFilenameMap)(fileMap, options.transforms) : fileMap;
+    const transformResult = (0, filenameTransformer_1.transformFilenameMap)(fileMap, options.transforms);
     if (options.transforms && logger?.shouldShow('debug')) {
-        logger.debug(`Filename transforms applied: ${fileMap.size} → ${transformedMap.size} files`);
+        logger.debug(`Filename transforms applied: ${fileMap.size} → ${transformResult.fileMap.size} files`);
         let exampleCount = 0;
-        for (const [transformed, content] of transformedMap.entries()) {
-            const original = [...fileMap.entries()].find(([_key, c]) => c === content)?.[0];
-            if (original && original !== transformed) {
-                logger.debug(`  ${original} → ${transformed}`);
-                exampleCount++;
-                if (exampleCount >= 3)
-                    break;
-            }
+        for (const [transformedPath, originalPath] of transformResult.originalPaths.entries()) {
+            logger.debug(`  ${originalPath} → ${transformedPath}`);
+            exampleCount++;
+            if (exampleCount >= 3)
+                break;
         }
     }
-    return sortMapByKeys(transformedMap);
+    return {
+        fileMap: sortMapByKeys(transformResult.fileMap),
+        originalPaths: transformResult.originalPaths
+    };
 };
 exports.loadFiles = loadFiles;

package/dist/fileUpdater.d.ts

@@ -1,5 +1,5 @@
 import { Config } from './configFile';
-import { FileDiffResult } from './fileDiff';
+import { ChangedFile, FileDiffResult } from './fileDiff';
 import { FileMap } from './fileLoader';
 import { Logger } from './logger';
 export interface FileUpdateError {
@@ -7,12 +7,30 @@ export interface FileUpdateError {
     path: string;
     error: Error;
 }
+export interface FileOperationOptions {
+    relativePath: string;
+    content: string;
+    absoluteDestinationDirectory: string;
+    config: Config;
+    dryRun: boolean;
+    skipFormat: boolean;
+    logger: Logger;
+}
+export interface UpdateFileOptions {
+    changedFile: ChangedFile;
+    absoluteDestinationDirectory: string;
+    config: Config;
+    dryRun: boolean;
+    skipFormat: boolean;
+    logger: Logger;
+}
 declare const FileUpdaterErrorClass: {
     new (message: string, options?: import("./utils/errors").ErrorOptions): {
         [key: string]: unknown;
         readonly code?: string;
         readonly path?: string;
         readonly cause?: Error;
+        readonly hints?: string[];
         name: string;
         message: string;
         stack?: string;