@aramassa/ai-rules 0.3.5 → 0.4.2

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAqjBA;;GAEG;AACH,wBAAsB,wBAAwB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,MAAY,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAyBpG"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AA+qBA;;GAEG;AACH,wBAAsB,wBAAwB,CAC5C,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,MAAY,GACpB,OAAO,CAAC,MAAM,EAAE,CAAC,CA4BnB"}

package/dist/cli.js

@@ -17904,7 +17904,7 @@ class ContentTracker {
      * Generates a hash for the given content
      */
     generateContentHash(content) {
-        return createHash('sha256').update(content.trim()).digest('hex');
+        return createHash("sha256").update(content.trim()).digest("hex");
     }
     /**
      * Checks if the same content has already been written to the file
@@ -17949,7 +17949,7 @@ function findPackageRoot() {
     let dir = path.dirname(currentFile);
     // Walk up directory tree looking for package.json
     while (dir !== path.dirname(dir)) {
-        const packageJsonPath = path.join(dir, 'package.json');
+        const packageJsonPath = path.join(dir, "package.json");
         try {
             // Use synchronous check since this is initialization
             fsSync.accessSync(packageJsonPath);
@@ -17973,17 +17973,49 @@ function resolveDefaultSrcDir(providedSrc) {
     }
     // Find package root and return artifact/ directory
     const packageRoot = findPackageRoot();
-    return path.join(packageRoot, 'artifact');
+    return path.join(packageRoot, "artifact");
 }
 /**
- * Resolves source directory for a recipe item following priority order:
+ * Resolves source directory for a recipe item following priority order (Issue #197):
  * 1. CLI --src option (highest priority)
- * 2. Recipe item src field (medium priority)
- * 3. Import-level src field (medium priority)
+ * 2. Import-level src field (overrides item-level src)
+ * 3. Recipe item src field (lower priority - resolved relative to recipe file or import src)
  * 4. Default package artifact/ directory (lowest priority)
  */
-function resolveItemSrcDir(cliSrc, itemSrc, importSrc) {
-    return cliSrc || itemSrc || importSrc || resolveDefaultSrcDir();
+function resolveItemSrcDir(cliSrc, itemSrc, importSrc, recipePath) {
+    if (cliSrc) {
+        return cliSrc;
+    }
+    // Per Issue #197: import-level src should override item-level src
+    if (importSrc) {
+        // If itemSrc is specified and relative, resolve it relative to importSrc
+        if (itemSrc && !path.isAbsolute(itemSrc)) {
+            // If importSrc is absolute, resolve itemSrc relative to it
+            if (path.isAbsolute(importSrc)) {
+                return path.resolve(importSrc, itemSrc);
+            }
+            // If importSrc is also relative, we need to resolve it first
+            if (recipePath) {
+                const resolvedImportSrc = path.resolve(path.dirname(recipePath), importSrc);
+                return path.resolve(resolvedImportSrc, itemSrc);
+            }
+        }
+        // Use importSrc as-is (either no itemSrc, or itemSrc is absolute and ignored)
+        return importSrc;
+    }
+    if (itemSrc) {
+        // If itemSrc is absolute, use it as-is
+        if (path.isAbsolute(itemSrc)) {
+            return itemSrc;
+        }
+        // If itemSrc is relative and we have a recipe path, resolve relative to recipe file directory
+        if (recipePath) {
+            return path.resolve(path.dirname(recipePath), itemSrc);
+        }
+        // Fallback to current working directory (existing behavior)
+        return itemSrc;
+    }
+    return resolveDefaultSrcDir();
 }
 /**
  * Resolves output path with baseDir support following priority order:
@@ -17995,7 +18027,7 @@ function resolveItemSrcDir(cliSrc, itemSrc, importSrc) {
 function resolveOutputPath(itemOut, cliBaseDir, importBaseDir, recipeBaseDir, recipePath) {
     // Check if the itemOut contains environment variables or tilde - if so, try to expand
     let processedItemOut = itemOut;
-    if (itemOut.includes('$') || itemOut.startsWith('~')) {
+    if (itemOut.includes("$") || itemOut.startsWith("~")) {
         try {
             processedItemOut = resolvePath(itemOut);
             // If expansion resulted in an absolute path, use it as-is (ignore baseDir)
@@ -18021,10 +18053,10 @@ function resolveOutputPath(itemOut, cliBaseDir, importBaseDir, recipeBaseDir, re
     }
     // Existing behavior: resolve relative to recipe file directory or current directory
     // For preset files (located in presets/ directory), resolve relative to project root instead
-    let baseDirectory = '.';
+    let baseDirectory = ".";
     if (recipePath) {
         const packageRoot = findPackageRoot();
-        const presetsDir = path.join(packageRoot, 'presets');
+        const presetsDir = path.join(packageRoot, "presets");
         // If the recipe is in the presets directory, use project root as base
         if (path.dirname(recipePath) === presetsDir) {
             baseDirectory = process.cwd();
@@ -18038,10 +18070,10 @@ function resolveOutputPath(itemOut, cliBaseDir, importBaseDir, recipeBaseDir, re
 }
 function resolveRecipePath(recipePath) {
     // If recipe starts with ':', resolve to package preset
-    if (recipePath.startsWith(':')) {
+    if (recipePath.startsWith(":")) {
         const presetName = recipePath.slice(1); // Remove the ':'
         const packageRoot = findPackageRoot();
-        return path.join(packageRoot, 'presets', `${presetName}.yaml`);
+        return path.join(packageRoot, "presets", `${presetName}.yaml`);
     }
     // Otherwise, use the path as-is
     return recipePath;
@@ -18061,8 +18093,8 @@ async function validateRecipeFilesExist(recipePaths) {
         }
     }
     if (missingFiles.length > 0) {
-        const errorMessages = missingFiles.map(file => {
-            if (file.startsWith(':')) {
+        const errorMessages = missingFiles.map((file) => {
+            if (file.startsWith(":")) {
                 const presetName = file.slice(1);
                 return `Preset ':${presetName}' not found. Use 'ai-rules presets' to list available presets.`;
             }
@@ -18074,7 +18106,7 @@ async function validateRecipeFilesExist(recipePaths) {
             throw new Error(errorMessages[0]);
         }
         else {
-            throw new Error(`Multiple recipe files not found:\n${errorMessages.join('\n')}`);
+            throw new Error(`Multiple recipe files not found:\n${errorMessages.join("\n")}`);
         }
     }
 }
@@ -18083,7 +18115,7 @@ async function validateRecipeFilesExist(recipePaths) {
  */
 function resolveImportPath(importPath, currentRecipePath) {
     // If import starts with ':', resolve to package preset
-    if (importPath.startsWith(':')) {
+    if (importPath.startsWith(":")) {
         return resolveRecipePath(importPath);
     }
     // Otherwise, resolve relative to current recipe file directory
@@ -18109,8 +18141,8 @@ async function expandRecipeImports(items, currentPath, debugLogger, visited = ne
             // Check for circular imports
             if (visited.has(resolvedImportPath)) {
                 const visitedArray = Array.from(visited);
-                debugLogger?.log(`Circular import detected in path: ${visitedArray.join(' -> ')} -> ${resolvedImportPath}`);
-                throw new Error(`Circular import detected: ${visitedArray.join(' -> ')} -> ${resolvedImportPath}`);
+                debugLogger?.log(`Circular import detected in path: ${visitedArray.join(" -> ")} -> ${resolvedImportPath}`);
+                throw new Error(`Circular import detected: ${visitedArray.join(" -> ")} -> ${resolvedImportPath}`);
             }
             // Check for duplicate imports and skip if already imported
             if (imported.has(resolvedImportPath)) {
@@ -18152,18 +18184,25 @@ async function expandRecipeImports(items, currentPath, debugLogger, visited = ne
                 const expandedImported = await expandRecipeImports(importData.recipe, resolvedImportPath, debugLogger, newVisited, imported, depth + 1);
                 debugLogger?.timeEnd(`Expanding nested imports in: ${resolvedImportPath}`);
                 debugLogger?.log(`Nested expansion yielded ${expandedImported.length} items`);
-                // Apply import-level configurations to all expanded items
+                // Apply import-level configurations to all expanded items  
+                expandedImported.forEach((expandedItem) => {
+                    // Ensure _recipePath is set for proper path resolution
+                    if (!expandedItem._recipePath) {
+                        expandedItem._recipePath = resolvedImportPath;
+                        debugLogger?.log(`Tagged item '${expandedItem.title || expandedItem.out || "untitled"}' with recipe path: ${resolvedImportPath}`);
+                    }
+                });
                 if (importLevelBaseDir || importLevelSrc || importLevelVariables) {
-                    expandedImported.forEach(expandedItem => {
+                    expandedImported.forEach((expandedItem) => {
                         // Apply baseDir if specified (only if not already set to preserve nested import priority)
                         if (importLevelBaseDir && !expandedItem._importBaseDir) {
                             expandedItem._importBaseDir = importLevelBaseDir;
-                            debugLogger?.log(`Tagged item '${expandedItem.title || expandedItem.out || 'untitled'}' with import baseDir: ${importLevelBaseDir}`);
+                            debugLogger?.log(`Tagged item '${expandedItem.title || expandedItem.out || "untitled"}' with import baseDir: ${importLevelBaseDir}`);
                         }
                         // Apply src if specified (only if not already set to preserve nested import priority)
                         if (importLevelSrc && !expandedItem._importSrc) {
                             expandedItem._importSrc = importLevelSrc;
-                            debugLogger?.log(`Tagged item '${expandedItem.title || expandedItem.out || 'untitled'}' with import src: ${importLevelSrc}`);
+                            debugLogger?.log(`Tagged item '${expandedItem.title || expandedItem.out || "untitled"}' with import src: ${importLevelSrc}`);
                         }
                         // Apply variables if specified (merge with existing variables, with import-level taking priority)
                         if (importLevelVariables) {
@@ -18174,10 +18213,10 @@ async function expandRecipeImports(items, currentPath, debugLogger, visited = ne
                                 // Merge variables, with import-level taking priority over nested imports
                                 expandedItem._importVariables = {
                                     ...expandedItem._importVariables,
-                                    ...importLevelVariables
+                                    ...importLevelVariables,
                                 };
                             }
-                            debugLogger?.log(`Tagged item '${expandedItem.title || expandedItem.out || 'untitled'}' with import variables:`, expandedItem._importVariables);
+                            debugLogger?.log(`Tagged item '${expandedItem.title || expandedItem.out || "untitled"}' with import variables:`, expandedItem._importVariables);
                         }
                     });
                 }
@@ -18188,10 +18227,10 @@ async function expandRecipeImports(items, currentPath, debugLogger, visited = ne
                 // Remove from imported set if there was an error to allow retry
                 imported.delete(resolvedImportPath);
                 debugLogger?.log(`Error processing import ${resolvedImportPath}:`, error);
-                if (item.import.startsWith(':')) {
+                if (item.import.startsWith(":")) {
                     const presetName = item.import.slice(1);
                     // Only treat ENOENT errors as "preset not found"
-                    if (error instanceof Error && error.message.includes('ENOENT')) {
+                    if (error instanceof Error && error.message.includes("ENOENT")) {
                         throw new Error(`Preset ':${presetName}' not found. Use 'ai-rules presets' to list available presets.`);
                     }
                     // For other errors, add context but preserve the original error message
@@ -18200,7 +18239,7 @@ async function expandRecipeImports(items, currentPath, debugLogger, visited = ne
                     }
                     throw error;
                 }
-                if (error instanceof Error && error.message.includes('ENOENT')) {
+                if (error instanceof Error && error.message.includes("ENOENT")) {
                     throw new Error(`Import file '${item.import}' not found (resolved to: ${resolvedImportPath})`);
                 }
                 throw error;
@@ -18208,8 +18247,13 @@ async function expandRecipeImports(items, currentPath, debugLogger, visited = ne
         }
         else {
             // This is a regular recipe item
-            debugLogger?.log(`Adding regular recipe item: ${item.title || 'untitled'}`);
-            expanded.push(item);
+            debugLogger?.log(`Adding regular recipe item: ${item.title || "untitled"}`);
+            // Tag the item with the recipe path it originated from
+            const taggedItem = { ...item };
+            if (!taggedItem._recipePath) {
+                taggedItem._recipePath = currentPath;
+            }
+            expanded.push(taggedItem);
         }
     }
     debugLogger?.log(`Import expansion complete: ${expanded.length} total items after processing`);
@@ -18221,42 +18265,43 @@ async function expandRecipeImports(items, currentPath, debugLogger, visited = ne
 function setupProgram() {
     const program = new Command();
     program
-        .name('ai-rules')
-        .description('CLI for extracting and analyzing markdown files')
-        .version('0.0.1');
+        .name("ai-rules")
+        .description("CLI for extracting and analyzing markdown files")
+        .version("0.0.1");
     // Extract command
     program
-        .command('extract')
-        .description('Extract and merge markdown files')
-        .option('--src <path>', 'Source directory')
-        .option('--out <path>', 'Output file')
-        .option('--type <types>', 'Filter by type (comma-separated)')
-        .option('--language <languages>', 'Filter by language (comma-separated)')
-        .option('--attr <attributes>', 'Filter by attributes (comma-separated)')
-        .option('--title <title>', 'Title for the output')
-        .option('--mode <mode>', 'Write mode: append, prepend, overwrite', 'overwrite')
-        .option('--recipe <path>', 'Recipe file path or package preset (e.g., :typescript). Can be specified multiple times or comma-separated.', collectRecipeOptions, [])
-        .option('--base-dir <path>', 'Base directory for output files (supports ~ and environment variable expansion)')
-        .option('--vars <variables>', 'Template variables in key=value format (comma-separated)')
-        .option('--env-file <path>', 'Path to .env file for template variables')
-        .option('--debug', 'Enable debug logging')
-        .option('--verbose', 'Enable verbose logging (alias for --debug)')
+        .command("extract")
+        .description("Extract and merge markdown files")
+        .option("--src <path>", "Source directory")
+        .option("--out <path>", "Output file")
+        .option("--type <types>", "Filter by type (comma-separated)")
+        .option("--language <languages>", "Filter by language (comma-separated)")
+        .option("--attr <attributes>", "Filter by attributes (comma-separated)")
+        .option("--title <title>", "Title for the output")
+        .option("--mode <mode>", "Write mode: append, prepend, overwrite", "overwrite")
+        .option("--recipe <path>", "Recipe file path or package preset (e.g., :typescript). Can be specified multiple times or comma-separated.", collectRecipeOptions, [])
+        .option("--base-dir <path>", "Base directory for output files (supports ~ and environment variable expansion)")
+        .option("--vars <variables>", "Template variables in key=value format (comma-separated)")
+        .option("--env-file <path>", "Path to .env file for template variables")
+        .option("--debug", "Enable debug logging")
+        .option("--verbose", "Enable verbose logging (alias for --debug)")
+        .option("--dry-run", "Preview input/output files without writing")
         .action(async (options) => {
         await handleExtractCommand(options);
     });
-    // Stats command  
+    // Stats command
     program
-        .command('stats')
-        .description('Generate statistics from markdown files')
-        .option('--src <path>', 'Source directory')
-        .option('--variables', 'Show available template variables')
+        .command("stats")
+        .description("Generate statistics from markdown files")
+        .option("--src <path>", "Source directory")
+        .option("--variables", "Show available template variables")
         .action(async (options) => {
         await handleStatsCommand(options);
     });
     // Presets command
     program
-        .command('presets')
-        .description('List available package presets')
+        .command("presets")
+        .description("List available package presets")
         .action(async () => {
         await listPresets();
     });
@@ -18276,7 +18321,8 @@ async function findYamlFilesRecursively(dir, baseDir = dir) {
                 const subFiles = await findYamlFilesRecursively(fullPath, baseDir);
                 yamlFiles.push(...subFiles);
             }
-            else if (item.isFile() && (item.name.endsWith('.yaml') || item.name.endsWith('.yml'))) {
+            else if (item.isFile() &&
+                (item.name.endsWith(".yaml") || item.name.endsWith(".yml"))) {
                 // Get relative path from base directory
                 const relativePath = path.relative(baseDir, fullPath);
                 yamlFiles.push(relativePath);
@@ -18294,25 +18340,25 @@ async function findYamlFilesRecursively(dir, baseDir = dir) {
  */
 async function listPresets() {
     const packageRoot = findPackageRoot();
-    const presetsDir = path.join(packageRoot, 'presets');
+    const presetsDir = path.join(packageRoot, "presets");
     try {
         const yamlFiles = await findYamlFilesRecursively(presetsDir);
         if (yamlFiles.length === 0) {
             // eslint-disable-next-line no-console
-            console.log('No presets found in package.');
+            console.log("No presets found in package.");
             return;
         }
         // eslint-disable-next-line no-console
-        console.log('Available presets:');
-        yamlFiles.forEach(file => {
-            const presetName = file.replace(/\.(yaml|yml)$/, '');
+        console.log("Available presets:");
+        yamlFiles.forEach((file) => {
+            const presetName = file.replace(/\.(yaml|yml)$/, "");
             // eslint-disable-next-line no-console
             console.log(`  :${presetName}`);
         });
     }
     catch (error) {
         // eslint-disable-next-line no-console
-        console.log('No presets directory found in package.');
+        console.log("No presets directory found in package.");
     }
 }
 /**
@@ -18320,23 +18366,26 @@ async function listPresets() {
  */
 function collectRecipeOptions(value, previous) {
     // Split comma-separated values and add to the accumulated array
-    const newValues = value.split(',').map(v => v.trim()).filter(v => v.length > 0);
+    const newValues = value
+        .split(",")
+        .map((v) => v.trim())
+        .filter((v) => v.length > 0);
     return previous.concat(newValues);
 }
 /**
  * Parses comma-separated values into array
  */
 function parseCommaSeparated(value) {
-    return value ? value.split(',') : undefined;
+    return value ? value.split(",") : undefined;
 }
 /**
  * Validates and converts mode string to WriteMode enum
  */
 function parseWriteMode(mode) {
     const modeMap = {
-        'append': WriteMode.APPEND,
-        'prepend': WriteMode.PREPEND,
-        'overwrite': WriteMode.OVERWRITE
+        append: WriteMode.APPEND,
+        prepend: WriteMode.PREPEND,
+        overwrite: WriteMode.OVERWRITE,
     };
     return modeMap[mode] || WriteMode.OVERWRITE;
 }
@@ -18351,10 +18400,10 @@ function convertFiltersToAttrFilters(filters) {
         if (Array.isArray(value)) {
             // For array values, join with pipe (|) to indicate OR logic
             // This needs to be handled specially in the filter logic
-            const joinedValues = value.join('|');
+            const joinedValues = value.join("|");
             attrFilters.push(`${key}=${joinedValues}`);
         }
-        else if (typeof value === 'string') {
+        else if (typeof value === "string") {
             // For string values, create single filter entry
             attrFilters.push(`${key}=${value}`);
         }
@@ -18364,54 +18413,204 @@ function convertFiltersToAttrFilters(filters) {
 /**
  * Common logic for loading and filtering markdown files
  */
+/**
+ * Displays dry-run preview for recipe processing
+ */
+async function displayRecipeDryRunPreview(recipePath, recipeData, expandedRecipe, baseOptions, debugLogger, cliBaseDir, cliOutFile, cliSrc) {
+    console.log("=== Recipe Dry-Run Preview ===\n");
+    const presetName = recipePath.startsWith(":") ? recipePath : undefined;
+    if (presetName) {
+        console.log(`📦 Recipe: ${presetName} (${expandedRecipe.length} steps)`);
+    }
+    else {
+        console.log(`📦 Recipe: ${recipePath} (${expandedRecipe.length} steps)`);
+    }
+    const recipeBaseDir = recipeData.config?.baseDir;
+    let totalInputFiles = 0;
+    let totalIncludedFiles = 0;
+    let totalExcludedFiles = 0;
+    const outputFiles = [];
+    for (const [index, item] of expandedRecipe.entries()) {
+        console.log(`\nStep ${index + 1}: ${item.title || `Untitled Step ${index + 1}`}`);
+        // Resolve paths and options for this item
+        const itemOut = cliOutFile || item.out || baseOptions.outFile;
+        const outputFile = resolveOutputPath(itemOut, cliBaseDir, item._importBaseDir, recipeBaseDir, resolveRecipePath(recipePath));
+        const itemTypes = item.type
+            ? parseCommaSeparated(item.type)
+            : baseOptions.types;
+        const itemLanguages = item.language
+            ? parseCommaSeparated(item.language)
+            : baseOptions.languages;
+        let combinedAttrFilters = [...baseOptions.attrFilters];
+        if (item.filters) {
+            const itemAttrFilters = convertFiltersToAttrFilters(item.filters);
+            combinedAttrFilters = combinedAttrFilters.concat(itemAttrFilters);
+        }
+        const itemSrcDir = resolveItemSrcDir(cliSrc, item.src, item._importSrc, item._recipePath);
+        console.log(`   📂 Source: ${itemSrcDir}`);
+        console.log(`   🔍 Filters: type=${itemTypes?.join(",") || "(none)"}, language=${itemLanguages?.join(",") || "(none)"}`);
+        if (combinedAttrFilters.length > 0) {
+            console.log(`             attributes=${combinedAttrFilters.join(", ")}`);
+        }
+        try {
+            const { allFiles, filteredFiles } = await loadAndFilterFilesWithDetails(itemSrcDir, itemTypes, itemLanguages, combinedAttrFilters, debugLogger);
+            totalInputFiles += allFiles.length;
+            totalIncludedFiles += filteredFiles.length;
+            totalExcludedFiles += allFiles.length - filteredFiles.length;
+            console.log(`\n   📄 Input Files Analysis:`);
+            if (filteredFiles.length > 0) {
+                console.log(`      ✓ INCLUDED (${filteredFiles.length} files):`);
+                filteredFiles.forEach((file) => {
+                    console.log(`        - ${file.path}`);
+                });
+            }
+            const excludedFiles = allFiles.filter((f) => !filteredFiles.includes(f));
+            // Note: Individual excluded files are not displayed to keep output concise
+            // Only the count is shown in the summary below
+            console.log(`\n   📝 Output: ${outputFile}`);
+            if (!outputFiles.includes(outputFile)) {
+                outputFiles.push(outputFile);
+            }
+        }
+        catch (error) {
+            console.log(`   ❌ Error scanning files: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    console.log(`\n📈 Overall Summary:`);
+    console.log(`   - Total steps: ${expandedRecipe.length}`);
+    console.log(`   - Total input files: ${totalInputFiles} (${totalIncludedFiles} included, ${totalExcludedFiles} excluded)`);
+    console.log(`   - Total output files: ${outputFiles.length}`);
+    console.log(`\n⚠️  Dry-run mode: No files will be written`);
+}
+/**
+ * Formats file size in a human-readable format
+ */
+function formatFileSize(sizeInBytes) {
+    if (sizeInBytes < 1024)
+        return `${sizeInBytes}B`;
+    if (sizeInBytes < 1024 * 1024)
+        return `${(sizeInBytes / 1024).toFixed(1)}KB`;
+    return `${(sizeInBytes / (1024 * 1024)).toFixed(1)}MB`;
+}
+/**
+ * Displays dry-run preview for single extraction
+ */
+function displayDryRunPreview(srcDir, outFile, allFiles, filteredFiles, types, languages, attrFilters = [], verbose = false) {
+    console.log("=== Extract Command Dry-Run Preview ===\n");
+    console.log(`📂 Source Directory: ${srcDir}`);
+    console.log("🔍 Filters Applied:");
+    console.log(`   - Type: ${types?.length ? types.join(", ") : "(none)"}`);
+    console.log(`   - Language: ${languages?.length ? languages.join(", ") : "(none)"}`);
+    console.log(`   - Attributes: ${attrFilters.length ? attrFilters.join(", ") : "(none)"}\n`);
+    console.log("📄 Input Files Analysis:");
+    if (filteredFiles.length > 0) {
+        console.log(`   ✓ INCLUDED (${filteredFiles.length} files):`);
+        filteredFiles.forEach((file) => {
+            const attrs = Object.entries(file.attrs)
+                .filter(([key]) => key !== "content")
+                .map(([key, value]) => `${key}: ${Array.isArray(value) ? value.join(",") : value}`)
+                .join(", ");
+            console.log(`     - ${file.path}`);
+            if (verbose && attrs) {
+                console.log(`       → ${attrs}`);
+            }
+            else if (attrs) {
+                console.log(`       → ${attrs}`);
+            }
+        });
+    }
+    const excludedFiles = allFiles.filter((f) => !filteredFiles.includes(f));
+    // Note: Individual excluded files are not displayed to keep output concise
+    // Only the count is shown in the summary below
+    const totalSize = filteredFiles.reduce((sum, f) => sum + f.content.length, 0);
+    console.log(`\n📈 Processing Summary:`);
+    console.log(`   - Total files scanned: ${allFiles.length}`);
+    console.log(`   - Files matching filters: ${filteredFiles.length}`);
+    console.log(`   - Files excluded: ${excludedFiles.length}`);
+    console.log(`\n📝 Output Files:`);
+    console.log(`   → ${outFile}`);
+    console.log(`     └─ Will merge ${filteredFiles.length} input files (estimated size: ~${formatFileSize(totalSize)})`);
+    console.log(`\n⚠️  Dry-run mode: No files will be written`);
+}
 async function loadAndFilterFiles(srcDir, types, languages, attrFilters = [], debugLogger) {
     debugLogger?.log(`Starting file scan in directory: ${srcDir}`);
-    debugLogger?.time('MarkdownFileScanner.parseMarkdownFiles');
+    debugLogger?.time("MarkdownFileScanner.parseMarkdownFiles");
     const files = await MarkdownFileScanner.parseMarkdownFiles(srcDir);
-    debugLogger?.timeEnd('MarkdownFileScanner.parseMarkdownFiles');
+    debugLogger?.timeEnd("MarkdownFileScanner.parseMarkdownFiles");
     debugLogger?.log(`Total markdown files found: ${files.length}`);
     if (debugLogger?.isEnabled) {
-        debugLogger.log('Files discovered:');
+        debugLogger.log("Files discovered:");
         files.forEach((file, index) => {
             debugLogger.log(`  ${index + 1}. ${file.path}`);
             debugLogger.log(`     Frontmatter attributes:`, Object.keys(file.attrs));
         });
     }
-    debugLogger?.time('File filtering');
+    debugLogger?.time("File filtering");
     const filtered = filterFiles(files, { types, languages, attrFilters });
-    debugLogger?.timeEnd('File filtering');
+    debugLogger?.timeEnd("File filtering");
     debugLogger?.log(`Files after filtering: ${filtered.length}`);
     if (debugLogger?.isEnabled && filtered.length !== files.length) {
         const excludedCount = files.length - filtered.length;
         debugLogger.log(`Excluded ${excludedCount} files due to filtering`);
-        const excludedFiles = files.filter(f => !filtered.includes(f));
-        excludedFiles.forEach(file => {
+        const excludedFiles = files.filter((f) => !filtered.includes(f));
+        excludedFiles.forEach((file) => {
             debugLogger.log(`  Excluded: ${file.path} (attributes: ${JSON.stringify(file.attrs)})`);
         });
     }
     return filtered;
 }
+/**
+ * Extended version of loadAndFilterFiles that returns both all files and filtered files
+ * Used for dry-run mode to show exclusion details
+ */
+async function loadAndFilterFilesWithDetails(srcDir, types, languages, attrFilters = [], debugLogger) {
+    debugLogger?.log(`Starting file scan in directory: ${srcDir}`);
+    debugLogger?.time("MarkdownFileScanner.parseMarkdownFiles");
+    const files = await MarkdownFileScanner.parseMarkdownFiles(srcDir);
+    debugLogger?.timeEnd("MarkdownFileScanner.parseMarkdownFiles");
+    debugLogger?.log(`Total markdown files found: ${files.length}`);
+    if (debugLogger?.isEnabled) {
+        debugLogger.log("Files discovered:");
+        files.forEach((file, index) => {
+            debugLogger.log(`  ${index + 1}. ${file.path}`);
+            debugLogger.log(`     Frontmatter attributes:`, Object.keys(file.attrs));
+        });
+    }
+    debugLogger?.time("File filtering");
+    const filtered = filterFiles(files, { types, languages, attrFilters });
+    debugLogger?.timeEnd("File filtering");
+    debugLogger?.log(`Files after filtering: ${filtered.length}`);
+    if (debugLogger?.isEnabled && filtered.length !== files.length) {
+        const excludedCount = files.length - filtered.length;
+        debugLogger.log(`Excluded ${excludedCount} files due to filtering`);
+        const excludedFiles = files.filter((f) => !filtered.includes(f));
+        excludedFiles.forEach((file) => {
+            debugLogger.log(`  Excluded: ${file.path} (attributes: ${JSON.stringify(file.attrs)})`);
+        });
+    }
+    return { allFiles: files, filteredFiles: filtered };
+}
 /**
  * Handles content mode processing (append/prepend/overwrite)
  */
 async function processContentWithMode(outFile, newContent, mode, debugLogger) {
     debugLogger?.log(`Processing content with mode: ${mode} for file: ${outFile}`);
     if (mode === WriteMode.OVERWRITE) {
-        debugLogger?.log('Using overwrite mode - returning new content as-is');
+        debugLogger?.log("Using overwrite mode - returning new content as-is");
         return newContent;
     }
     try {
         const existing = await fs.readFile(resolvePath(outFile), "utf-8");
         debugLogger?.log(`Existing file found with ${existing.length} characters`);
         if (mode === WriteMode.APPEND) {
-            debugLogger?.log('Appending new content to existing content');
+            debugLogger?.log("Appending new content to existing content");
             const needsNewline = !/\n\s*$/.test(existing);
             return needsNewline
                 ? `${existing}\n\n${newContent}`
                 : `${existing}\n${newContent}`;
         }
         else if (mode === WriteMode.PREPEND) {
-            debugLogger?.log('Prepending new content to existing content');
+            debugLogger?.log("Prepending new content to existing content");
             const needsNewline = !/\n\s*$/.test(newContent);
             return needsNewline
                 ? `${newContent}\n\n${existing}`
@@ -18420,7 +18619,7 @@ async function processContentWithMode(outFile, newContent, mode, debugLogger) {
     }
     catch (error) {
         debugLogger?.log(`No existing file found or error reading file:`, error);
-        debugLogger?.log('Proceeding with new content only');
+        debugLogger?.log("Proceeding with new content only");
     }
     return newContent;
 }
@@ -18430,7 +18629,7 @@ async function processContentWithMode(outFile, newContent, mode, debugLogger) {
 function applyTemplateToObject(obj, templateOptions, templateEngine) {
     const result = {};
     for (const [key, value] of Object.entries(obj)) {
-        if (typeof value === 'string') {
+        if (typeof value === "string") {
             // Apply template processing to string values
             if (templateEngine.hasTemplateVariables(value)) {
                 result[key] = templateEngine.renderTemplate(value, templateOptions);
@@ -18441,11 +18640,11 @@ function applyTemplateToObject(obj, templateOptions, templateEngine) {
         }
         else if (Array.isArray(value)) {
             // Process array elements
-            result[key] = value.map(item => typeof item === 'string' && templateEngine.hasTemplateVariables(item)
+            result[key] = value.map((item) => typeof item === "string" && templateEngine.hasTemplateVariables(item)
                 ? templateEngine.renderTemplate(item, templateOptions)
                 : item);
         }
-        else if (value && typeof value === 'object') {
+        else if (value && typeof value === "object") {
             // Recursively process nested objects
             result[key] = applyTemplateToObject(value, templateOptions, templateEngine);
         }
@@ -18458,68 +18657,81 @@ function applyTemplateToObject(obj, templateOptions, templateEngine) {
 }
 async function processSingle(options, debugLogger) {
     CliOptionValidator.validateExtractOptions(options);
-    const { srcDir, outFile, types, languages, attrFilters, title, mode, attr, vars, envFile } = options;
+    const { srcDir, outFile, types, languages, attrFilters, title, mode, attr, vars, envFile, dryRun, } = options;
     // Resolve template variables first
     const templateEngine = new TemplateEngine();
     const variableResolver = new VariableResolver();
     let resolvedVariables = {};
     // Always resolve variables - even if no CLI variables are provided,
     // we still need to check for required variables and use environment variables
-    debugLogger.time('Variable resolution');
-    debugLogger.log('Resolving template variables', { vars, envFile });
+    debugLogger.time("Variable resolution");
+    debugLogger.log("Resolving template variables", { vars, envFile });
     try {
-        const cliVariables = vars ? VariableResolver.parseCliVariables(vars) : undefined;
+        const cliVariables = vars
+            ? VariableResolver.parseCliVariables(vars)
+            : undefined;
         resolvedVariables = await variableResolver.resolveVariables({
             cliVariables,
             envFile,
-            environmentVariables: true
+            environmentVariables: true,
         });
-        debugLogger.log('Resolved variables:', Object.keys(resolvedVariables));
+        debugLogger.log("Resolved variables:", Object.keys(resolvedVariables));
     }
     catch (error) {
         throw new Error(`Template variable resolution failed: ${error instanceof Error ? error.message : String(error)}`);
     }
-    debugLogger.timeEnd('Variable resolution');
-    debugLogger.time('File scanning and filtering');
+    debugLogger.timeEnd("Variable resolution");
+    debugLogger.time("File scanning and filtering");
     debugLogger.log(`Scanning directory: ${srcDir}`);
-    debugLogger.log('Applied filters:', { types, languages, attrFilters });
+    debugLogger.log("Applied filters:", { types, languages, attrFilters });
+    // In dry-run mode, we need both all files and filtered files to show exclusion details
+    if (dryRun) {
+        const { allFiles, filteredFiles } = await loadAndFilterFilesWithDetails(srcDir, types, languages, attrFilters, debugLogger);
+        debugLogger.timeEnd("File scanning and filtering");
+        debugLogger.log(`Found ${filteredFiles.length} files after filtering`);
+        // Check if verbose mode is enabled (via debug flag)
+        const verbose = debugLogger.isEnabled;
+        // Display dry-run preview and exit
+        displayDryRunPreview(srcDir, outFile, allFiles, filteredFiles, types, languages, attrFilters, verbose);
+        return;
+    }
     const filtered = await loadAndFilterFiles(srcDir, types, languages, attrFilters, debugLogger);
-    debugLogger.timeEnd('File scanning and filtering');
+    debugLogger.timeEnd("File scanning and filtering");
     debugLogger.log(`Found ${filtered.length} files after filtering`);
-    debugLogger.time('Content merging');
+    debugLogger.time("Content merging");
     let merged = filtered.map((f) => f.content.trim()).join("\n\n");
     // Always create templateOptions with strict mode enabled
     const templateOptions = {
         variables: resolvedVariables,
-        strictMode: true
+        strictMode: true,
     };
     // Pre-validate required variables before processing
     if (templateEngine.hasTemplateVariables(merged)) {
-        debugLogger.time('Required variable validation');
+        debugLogger.time("Required variable validation");
         const requiredVars = templateEngine.extractRequiredVariables(merged);
-        debugLogger.log('Found required variables:', requiredVars);
+        debugLogger.log("Found required variables:", requiredVars);
         if (requiredVars.length > 0) {
             try {
                 templateEngine.validateRequiredVariables(merged, resolvedVariables);
-                debugLogger.log('All required variables are satisfied');
+                debugLogger.log("All required variables are satisfied");
             }
             catch (error) {
-                debugLogger.log('Required variable validation failed');
+                debugLogger.log("Required variable validation failed");
                 throw error;
             }
         }
-        debugLogger.timeEnd('Required variable validation');
-        debugLogger.time('Template processing');
-        debugLogger.log('Applying template processing to merged content');
+        debugLogger.timeEnd("Required variable validation");
+        debugLogger.time("Template processing");
+        debugLogger.log("Applying template processing to merged content");
         merged = templateEngine.renderTemplate(merged, templateOptions);
-        debugLogger.timeEnd('Template processing');
+        debugLogger.timeEnd("Template processing");
     }
     const contentWithTitle = title ? `# ${title}\n\n${merged}` : merged;
-    debugLogger.timeEnd('Content merging');
+    debugLogger.timeEnd("Content merging");
     debugLogger.log(`Generated content size: ${contentWithTitle.length} characters`);
-    debugLogger.time('Content mode processing');
+    debugLogger.time("Content mode processing");
     const finalContent = await processContentWithMode(outFile, contentWithTitle, mode, debugLogger);
-    debugLogger.timeEnd('Content mode processing');
+    debugLogger.timeEnd("Content mode processing");
     const resolved = resolvePath(outFile);
     const writer = new MarkdownWriter();
     debugLogger.log(`Writing to output file: ${resolved}`);
@@ -18527,21 +18739,21 @@ async function processSingle(options, debugLogger) {
     let frontMatter = attr ? { ...attr } : {};
     // Apply template processing to front matter if needed
     if (Object.keys(frontMatter).length > 0) {
-        debugLogger.log('Applying template processing to front matter');
+        debugLogger.log("Applying template processing to front matter");
         frontMatter = applyTemplateToObject(frontMatter, templateOptions, templateEngine);
     }
-    debugLogger.log('Front matter to add:', frontMatter);
-    debugLogger.time('File writing');
+    debugLogger.log("Front matter to add:", frontMatter);
+    debugLogger.time("File writing");
     // Write file with or without front matter
     if (Object.keys(frontMatter).length > 0) {
         await writer.writeMarkdownFileWithFrontMatter(resolved, finalContent, frontMatter);
-        debugLogger.log('File written with front matter');
+        debugLogger.log("File written with front matter");
     }
     else {
         await writer.writeMarkdownFile(resolved, finalContent);
-        debugLogger.log('File written without front matter');
+        debugLogger.log("File written without front matter");
     }
-    debugLogger.timeEnd('File writing');
+    debugLogger.timeEnd("File writing");
     // eslint-disable-next-line no-console
     console.log(`Extracted ${filtered.length} files to ${outFile}`);
 }
@@ -18599,7 +18811,7 @@ async function displayVariables(srcDir) {
                 variableMap.set(variable.name, {
                     required: variable.required,
                     defaultValue: variable.defaultValue,
-                    sources: new Set([file.path])
+                    sources: new Set([file.path]),
                 });
             }
         }
@@ -18608,32 +18820,32 @@ async function displayVariables(srcDir) {
     for (const [name, info] of variableMap.entries()) {
         allVariables.push({
             variable: name,
-            required: info.required ? 'Yes' : 'No',
-            defaultValue: info.defaultValue ?? '(none)',
-            sources: Array.from(info.sources)
+            required: info.required ? "Yes" : "No",
+            defaultValue: info.defaultValue ?? "(none)",
+            sources: Array.from(info.sources),
         });
     }
     if (allVariables.length === 0) {
         // eslint-disable-next-line no-console
-        console.log('No template variables found in source files.');
+        console.log("No template variables found in source files.");
         // eslint-disable-next-line no-console
-        console.log('\nTemplate variables use the syntax ${VAR:default} for optional variables and !{VAR} for required variables.');
+        console.log("\nTemplate variables use the syntax ${VAR:default} for optional variables and !{VAR} for required variables.");
         return;
     }
     // eslint-disable-next-line no-console
-    console.log('Template variables found in source files:\n');
+    console.log("Template variables found in source files:\n");
     // Calculate column widths with reasonable limits
-    const maxVariableLength = Math.max(8, Math.min(30, ...allVariables.map(v => v.variable.length)));
+    const maxVariableLength = Math.max(8, Math.min(30, ...allVariables.map((v) => v.variable.length)));
     const maxRequiredLength = 8; // "Required" header length
-    const maxDefaultLength = Math.max(12, Math.min(30, ...allVariables.map(v => v.defaultValue.length)));
+    const maxDefaultLength = Math.max(12, Math.min(30, ...allVariables.map((v) => v.defaultValue.length)));
     // Header
-    const variableHeader = 'Variable'.padEnd(maxVariableLength);
-    const requiredHeader = 'Required'.padEnd(maxRequiredLength);
-    const defaultHeader = 'Default'.padEnd(maxDefaultLength);
+    const variableHeader = "Variable".padEnd(maxVariableLength);
+    const requiredHeader = "Required".padEnd(maxRequiredLength);
+    const defaultHeader = "Default".padEnd(maxDefaultLength);
     // eslint-disable-next-line no-console
     console.log(`${variableHeader} | ${requiredHeader} | ${defaultHeader}`);
     // eslint-disable-next-line no-console
-    console.log('-'.repeat(maxVariableLength + maxRequiredLength + maxDefaultLength + 6));
+    console.log("-".repeat(maxVariableLength + maxRequiredLength + maxDefaultLength + 6));
     // Sort by variable name for consistent output
     allVariables.sort((a, b) => a.variable.localeCompare(b.variable));
     // Data rows
@@ -18645,7 +18857,7 @@ async function displayVariables(srcDir) {
         console.log(`${variableCol} | ${requiredCol} | ${defaultCol}`);
     });
     // eslint-disable-next-line no-console
-    console.log('\nNote: Template variables use ${VAR:default} syntax for optional variables and !{VAR} for required variables.');
+    console.log("\nNote: Template variables use ${VAR:default} syntax for optional variables and !{VAR} for required variables.");
 }
 /**
  * Handles the extract command with options parsing
@@ -18653,7 +18865,7 @@ async function displayVariables(srcDir) {
 async function handleExtractCommand(options) {
     const isDebugMode = Boolean(options.debug || options.verbose);
     const debugLogger = new DebugLogger(isDebugMode);
-    debugLogger.log('Starting extract command with options:', {
+    debugLogger.log("Starting extract command with options:", {
         src: options.src,
         out: options.out,
         type: options.type,
@@ -18662,21 +18874,22 @@ async function handleExtractCommand(options) {
         title: options.title,
         mode: options.mode,
         recipeCount: options.recipe?.length || 0,
-        debug: isDebugMode
+        debug: isDebugMode,
     });
     const extractOptions = {
         srcDir: resolveDefaultSrcDir(options.src),
-        outFile: options.out || './out/instruction.md',
+        outFile: options.out || "./out/instruction.md",
         types: parseCommaSeparated(options.type),
         languages: parseCommaSeparated(options.language),
         attrFilters: parseCommaSeparated(options.attr) || [],
         title: options.title,
-        mode: parseWriteMode(options.mode || 'overwrite'),
+        mode: parseWriteMode(options.mode || "overwrite"),
         debug: isDebugMode,
         vars: options.vars,
         envFile: options.envFile,
+        dryRun: options.dryRun,
     };
-    debugLogger.log('Resolved extract options:', extractOptions);
+    debugLogger.log("Resolved extract options:", extractOptions);
     if (options.recipe && options.recipe.length > 0) {
         debugLogger.log(`Processing ${options.recipe.length} recipe(s):`, options.recipe);
         // Validate all recipe files exist before processing starts
@@ -18691,7 +18904,7 @@ async function handleExtractCommand(options) {
         }
     }
     else {
-        debugLogger.log('Processing single extraction without recipe');
+        debugLogger.log("Processing single extraction without recipe");
         // For single extraction, apply baseDir to outFile if provided
         if (options.baseDir) {
             extractOptions.outFile = resolveOutputPath(extractOptions.outFile, options.baseDir, undefined, undefined, undefined);
@@ -18736,10 +18949,10 @@ async function processMultipleRecipes(recipePaths, baseOptions, debugLogger, cli
  * Reads template files and extracts frontmatter for inheritance
  */
 async function loadTemplateFrontmatter(srcDir, types, languages, attrFilters, debugLogger) {
-    debugLogger?.log('Loading template frontmatter for inheritance');
+    debugLogger?.log("Loading template frontmatter for inheritance");
     const templateFiles = await loadAndFilterFiles(srcDir, types, languages, attrFilters, debugLogger);
     debugLogger?.log(`Found ${templateFiles.length} template files for frontmatter inheritance`);
-    return templateFiles.map(file => file.attrs);
+    return templateFiles.map((file) => file.attrs);
 }
 /**
  * Merges frontmatter values from multiple templates according to merge rules:
@@ -18749,8 +18962,8 @@ async function loadTemplateFrontmatter(srcDir, types, languages, attrFilters, de
  */
 function mergeTemplateFrontmatterValues(templateFrontmatters, fieldName) {
     const values = templateFrontmatters
-        .map(fm => fm[fieldName])
-        .filter(val => val !== undefined && val !== null);
+        .map((fm) => fm[fieldName])
+        .filter((val) => val !== undefined && val !== null);
     if (values.length === 0) {
         return undefined;
     }
@@ -18758,12 +18971,15 @@ function mergeTemplateFrontmatterValues(templateFrontmatters, fieldName) {
         return values[0];
     }
     // Check if all values are strings
-    if (values.every(val => typeof val === 'string')) {
+    if (values.every((val) => typeof val === "string")) {
         // Split each string by newlines, flatten, remove duplicates while preserving order
         const allLines = [];
         const seen = new Set();
         for (const value of values) {
-            const lines = value.split('\n').map(line => line.trim()).filter(line => line.length > 0);
+            const lines = value
+                .split("\n")
+                .map((line) => line.trim())
+                .filter((line) => line.length > 0);
             for (const line of lines) {
                 if (!seen.has(line)) {
                     seen.add(line);
@@ -18771,10 +18987,10 @@ function mergeTemplateFrontmatterValues(templateFrontmatters, fieldName) {
                 }
             }
         }
-        return allLines.join('\n');
+        return allLines.join("\n");
     }
     // Check if all values are arrays
-    if (values.every(val => Array.isArray(val))) {
+    if (values.every((val) => Array.isArray(val))) {
         return values.flat();
     }
     // For objects and mixed types, use the last value
@@ -18784,14 +19000,14 @@ function mergeTemplateFrontmatterValues(templateFrontmatters, fieldName) {
  * Processes @ syntax in frontmatter to inherit from template files
  */
 async function processFrontmatterInheritance(frontmatter, srcDir, types, languages, attrFilters, debugLogger) {
-    if (!frontmatter || typeof frontmatter !== 'object') {
+    if (!frontmatter || typeof frontmatter !== "object") {
         return {};
     }
     const result = {};
     const inheritanceFields = [];
     // Separate inheritance fields (@ syntax) from regular fields
     for (const [key, value] of Object.entries(frontmatter)) {
-        if (key.startsWith('@') && value === true) {
+        if (key.startsWith("@") && value === true) {
             inheritanceFields.push(key.slice(1)); // Remove @ prefix
             debugLogger?.log(`Found inheritance field: ${key} -> ${key.slice(1)}`);
         }
@@ -18801,14 +19017,14 @@ async function processFrontmatterInheritance(frontmatter, srcDir, types, languag
     }
     // If no inheritance fields, return as-is
     if (inheritanceFields.length === 0) {
-        debugLogger?.log('No frontmatter inheritance fields found');
+        debugLogger?.log("No frontmatter inheritance fields found");
         return result;
     }
     debugLogger?.log(`Processing ${inheritanceFields.length} inheritance fields:`, inheritanceFields);
     // Load template frontmatters
     const templateFrontmatters = await loadTemplateFrontmatter(srcDir, types, languages, attrFilters, debugLogger);
     if (templateFrontmatters.length === 0) {
-        debugLogger?.log('No template files found for inheritance');
+        debugLogger?.log("No template files found for inheritance");
         return result;
     }
     // Process each inheritance field
@@ -18822,7 +19038,7 @@ async function processFrontmatterInheritance(frontmatter, srcDir, types, languag
             debugLogger?.log(`No value found for inherited field ${fieldName} in templates`);
         }
     }
-    debugLogger?.log('Frontmatter after inheritance processing:', Object.keys(result));
+    debugLogger?.log("Frontmatter after inheritance processing:", Object.keys(result));
     return result;
 }
 /**
@@ -18832,45 +19048,50 @@ async function processRecipe(recipePath, baseOptions, contentTracker, debugLogge
     const resolvedPath = resolveRecipePath(recipePath);
     debugLogger?.log(`Processing recipe at path: ${resolvedPath}`);
     try {
-        debugLogger?.time('Recipe file reading and parsing');
+        debugLogger?.time("Recipe file reading and parsing");
         const content = await fs.readFile(resolvedPath, "utf-8");
         const data = YAML.parse(content);
-        debugLogger?.timeEnd('Recipe file reading and parsing');
+        debugLogger?.timeEnd("Recipe file reading and parsing");
         if (!Array.isArray(data?.recipe)) {
             throw new Error("Invalid recipe file: 'recipe' array not found");
         }
         // Validate recipe structure and show warnings
-        debugLogger?.time('Recipe validation');
+        debugLogger?.time("Recipe validation");
         try {
             const validator = await getRecipeValidator();
             const validationResult = validator.validateRecipe(data);
             // Always log validation warnings to help users improve their recipes
             if (validationResult.warnings.length > 0) {
                 console.warn(`\nRecipe validation warnings for '${recipePath}':`);
-                validationResult.warnings.forEach(warning => {
+                validationResult.warnings.forEach((warning) => {
                     console.warn(`  ${warning}`);
                 });
-                console.warn('  These warnings do not prevent recipe execution but may indicate configuration issues.\n');
+                console.warn("  These warnings do not prevent recipe execution but may indicate configuration issues.\n");
             }
             // Log errors but don't fail (maintain backward compatibility)
             if (validationResult.errors.length > 0) {
-                debugLogger?.log('Recipe validation errors (non-blocking):', validationResult.errors);
+                debugLogger?.log("Recipe validation errors (non-blocking):", validationResult.errors);
             }
         }
         catch (validationError) {
             // Don't fail recipe processing if validation fails
-            debugLogger?.log('Recipe validation failed:', validationError);
+            debugLogger?.log("Recipe validation failed:", validationError);
         }
-        debugLogger?.timeEnd('Recipe validation');
+        debugLogger?.timeEnd("Recipe validation");
         debugLogger?.log(`Recipe contains ${data.recipe.length} items`);
         // Read recipe config for baseDir
         const recipeBaseDir = data.config?.baseDir;
-        debugLogger?.log('Recipe config:', { baseDir: recipeBaseDir });
+        debugLogger?.log("Recipe config:", { baseDir: recipeBaseDir });
         // Expand any imports in the recipe
-        debugLogger?.time('Recipe import expansion');
+        debugLogger?.time("Recipe import expansion");
         const expandedRecipe = await expandRecipeImports(data.recipe, resolvedPath, debugLogger);
-        debugLogger?.timeEnd('Recipe import expansion');
+        debugLogger?.timeEnd("Recipe import expansion");
         debugLogger?.log(`After import expansion: ${expandedRecipe.length} items`);
+        // If dry-run mode, display preview and exit
+        if (baseOptions.dryRun) {
+            await displayRecipeDryRunPreview(recipePath, data, expandedRecipe, baseOptions, debugLogger, cliBaseDir, cliOutFile, cliSrc);
+            return;
+        }
         // Initialize local tracker if not provided (for single recipe mode)
         const localTracker = contentTracker || new ContentTracker();
         for (const [index, item] of expandedRecipe.entries()) {
@@ -18879,7 +19100,7 @@ async function processRecipe(recipePath, baseOptions, contentTracker, debugLogge
                 out: item.out,
                 type: item.type,
                 language: item.language,
-                mode: item.mode
+                mode: item.mode,
             });
             // Priority: CLI --out option > recipe item.out > baseOptions.outFile default
             const itemOut = cliOutFile || item.out || baseOptions.outFile;
@@ -18890,12 +19111,14 @@ async function processRecipe(recipePath, baseOptions, contentTracker, debugLogge
                 fallback: baseOptions.outFile,
                 cliBaseDir,
                 importBaseDir: item._importBaseDir,
-                recipeBaseDir
+                recipeBaseDir,
             });
             // Generate the content that would be written to check for duplicates
-            const { srcDir, types, languages, attrFilters, title, attr, vars, envFile } = baseOptions;
+            const { srcDir, types, languages, attrFilters, title, attr, vars, envFile, } = baseOptions;
             const itemTypes = item.type ? parseCommaSeparated(item.type) : types;
-            const itemLanguages = item.language ? parseCommaSeparated(item.language) : languages;
+            const itemLanguages = item.language
+                ? parseCommaSeparated(item.language)
+                : languages;
             const itemTitle = item.title || title;
             // Combine base attrFilters with item-specific filters
             let combinedAttrFilters = [...attrFilters];
@@ -18909,43 +19132,52 @@ async function processRecipe(recipePath, baseOptions, contentTracker, debugLogge
                 itemLanguages,
                 combinedAttrFilters,
                 baseAttrFilters: attrFilters,
-                itemFilters: item.filters || 'none'
+                itemFilters: item.filters || "none",
             });
             // Resolve template variables for this item (merge import variables, recipe item variables, and CLI variables)
             let itemVars = vars;
             if (item.variables || item._importVariables) {
-                const cliVariables = vars ? VariableResolver.parseCliVariables(vars) : {};
+                const cliVariables = vars
+                    ? VariableResolver.parseCliVariables(vars)
+                    : {};
                 const importVariables = item._importVariables || {};
                 const itemVariables = item.variables || {};
                 // Merge with priority: CLI > item > import
-                const mergedVariables = { ...importVariables, ...itemVariables, ...cliVariables };
+                const mergedVariables = {
+                    ...importVariables,
+                    ...itemVariables,
+                    ...cliVariables,
+                };
                 itemVars = Object.entries(mergedVariables)
                     .map(([key, value]) => `${key}=${value}`)
-                    .join(',');
+                    .join(",");
                 debugLogger?.log(`Merged variables for item ${index + 1}:`, {
                     importVariables,
                     itemVariables,
                     cliVariables,
-                    merged: mergedVariables
+                    merged: mergedVariables,
                 });
             }
             // Resolve source directory for this item with priority: CLI --src > item.src > import.src > default
-            const itemSrcDir = resolveItemSrcDir(cliSrc, item.src, item._importSrc);
+            const itemSrcDir = resolveItemSrcDir(cliSrc, item.src, item._importSrc, item._recipePath);
             debugLogger?.log(`Resolved source directory for item ${index + 1}:`, {
                 cliSrc,
                 itemSrc: item.src,
                 importSrc: item._importSrc,
-                resolved: itemSrcDir
+                recipePath: item._recipePath,
+                resolved: itemSrcDir,
             });
             debugLogger?.time(`Content generation for item ${index + 1}`);
             const filtered = await loadAndFilterFiles(itemSrcDir, itemTypes, itemLanguages, combinedAttrFilters, debugLogger);
             const merged = filtered.map((f) => f.content.trim()).join("\n\n");
-            const contentWithTitle = itemTitle ? `# ${itemTitle}\n\n${merged}` : merged;
+            const contentWithTitle = itemTitle
+                ? `# ${itemTitle}\n\n${merged}`
+                : merged;
             debugLogger?.timeEnd(`Content generation for item ${index + 1}`);
             // Check if this exact content has already been written to this file
-            debugLogger?.time('Duplicate content check');
+            debugLogger?.time("Duplicate content check");
             const isDuplicate = localTracker.hasContent(outputFile, contentWithTitle);
-            debugLogger?.timeEnd('Duplicate content check');
+            debugLogger?.timeEnd("Duplicate content check");
             if (isDuplicate) {
                 debugLogger?.log(`Skipping duplicate content for ${outputFile}`);
                 // eslint-disable-next-line no-console
@@ -18983,6 +19215,7 @@ async function processRecipe(recipePath, baseOptions, contentTracker, debugLogge
                 debug: baseOptions.debug,
                 vars: itemVars,
                 envFile: envFile,
+                dryRun: baseOptions.dryRun,
             };
             debugLogger?.time(`Processing single extraction for item ${index + 1}`);
             await processSingle(options, debugLogger || new DebugLogger(false));
@@ -18993,11 +19226,11 @@ async function processRecipe(recipePath, baseOptions, contentTracker, debugLogge
         }
     }
     catch (error) {
-        if (recipePath.startsWith(':')) {
+        if (recipePath.startsWith(":")) {
             const presetName = recipePath.slice(1);
             debugLogger?.log(`Error processing preset ${presetName}:`, error);
             // Only treat ENOENT errors as "preset not found"
-            if (error instanceof Error && error.message.includes('ENOENT')) {
+            if (error instanceof Error && error.message.includes("ENOENT")) {
                 throw new Error(`Preset ':${presetName}' not found. Use 'ai-rules presets' to list available presets.`);
             }
             // For other errors (like variable validation), add context but preserve the original error

package/dist/optionValidator.d.ts

@@ -15,6 +15,7 @@ export interface ExtractOptions {
     debug?: boolean;
     vars?: string;
     envFile?: string;
+    dryRun?: boolean;
 }
 export interface StatsOptions {
     srcDir: string;

package/dist/optionValidator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"optionValidator.d.ts","sourceRoot":"","sources":["../src/optionValidator.ts"],"names":[],"mappings":"AAAA,oBAAY,SAAS;IACnB,MAAM,WAAW;IACjB,OAAO,YAAY;IACnB,SAAS,cAAc;CACxB;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,SAAS,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,cAAc,CAIpC;WAEY,sBAAsB,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI;WAYrD,oBAAoB,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI;CAKhE"}
+{"version":3,"file":"optionValidator.d.ts","sourceRoot":"","sources":["../src/optionValidator.ts"],"names":[],"mappings":"AAAA,oBAAY,SAAS;IACnB,MAAM,WAAW;IACjB,OAAO,YAAY;IACnB,SAAS,cAAc;CACxB;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,SAAS,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,cAAc,CAIpC;WAEY,sBAAsB,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI;WAYrD,oBAAoB,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI;CAKhE"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aramassa/ai-rules",
-  "version": "0.3.5",
+  "version": "0.4.2",
   "description": "This repository collects guidelines and instructions for developing AI agents. It contains documents covering communication rules, coding standards, testing strategies, and general operational practices.",
   "workspaces": [
     "packages/extract",