bmad-method 6.0.0-Beta.5 → 6.0.0-Beta.7

package/tools/flattener/main.js

@@ -1,483 +0,0 @@
-const { Command } = require('commander');
-const fs = require('fs-extra');
-const path = require('node:path');
-const process = require('node:process');
-
-// Modularized components
-const { findProjectRoot } = require('./projectRoot.js');
-const { promptYesNo, promptPath } = require('./prompts.js');
-const { discoverFiles, filterFiles, aggregateFileContents } = require('./files.js');
-const { generateXMLOutput } = require('./xml.js');
-const { calculateStatistics } = require('./stats.js');
-
-/**
- * Recursively discover all files in a directory
- * @param {string} rootDir - The root directory to scan
- * @returns {Promise<string[]>} Array of file paths
- */
-
-/**
- * Parse .gitignore file and return ignore patterns
- * @param {string} gitignorePath - Path to .gitignore file
- * @returns {Promise<string[]>} Array of ignore patterns
- */
-
-/**
- * Check if a file is binary using file command and heuristics
- * @param {string} filePath - Path to the file
- * @returns {Promise<boolean>} True if file is binary
- */
-
-/**
- * Read and aggregate content from text files
- * @param {string[]} files - Array of file paths
- * @param {string} rootDir - The root directory
- * @param {Object} spinner - Optional spinner instance for progress display
- * @returns {Promise<Object>} Object containing file contents and metadata
- */
-
-/**
- * Generate XML output with aggregated file contents using streaming
- * @param {Object} aggregatedContent - The aggregated content object
- * @param {string} outputPath - The output file path
- * @returns {Promise<void>} Promise that resolves when writing is complete
- */
-
-/**
- * Calculate statistics for the processed files
- * @param {Object} aggregatedContent - The aggregated content object
- * @param {number} xmlFileSize - The size of the generated XML file in bytes
- * @returns {Object} Statistics object
- */
-
-/**
- * Filter files based on .gitignore patterns
- * @param {string[]} files - Array of file paths
- * @param {string} rootDir - The root directory
- * @returns {Promise<string[]>} Filtered array of file paths
- */
-
-/**
- * Attempt to find the project root by walking up from startDir
- * Looks for common project markers like .git, package.json, pyproject.toml, etc.
- * @param {string} startDir
- * @returns {Promise<string|null>} project root directory or null if not found
- */
-
-const program = new Command();
-
-program
-  .name('bmad-flatten')
-  .description('BMad-Method codebase flattener tool')
-  .version('1.0.0')
-  .option('-i, --input <path>', 'Input directory to flatten', process.cwd())
-  .option('-o, --output <path>', 'Output file path', 'flattened-codebase.xml')
-  .action(async (options) => {
-    let inputDir = path.resolve(options.input);
-    let outputPath = path.resolve(options.output);
-
-    // Detect if user explicitly provided -i/--input or -o/--output
-    const argv = process.argv.slice(2);
-    const userSpecifiedInput = argv.some((a) => a === '-i' || a === '--input' || a.startsWith('--input='));
-    const userSpecifiedOutput = argv.some((a) => a === '-o' || a === '--output' || a.startsWith('--output='));
-    const noPathArguments = !userSpecifiedInput && !userSpecifiedOutput;
-
-    if (noPathArguments) {
-      const detectedRoot = await findProjectRoot(process.cwd());
-      const suggestedOutput = detectedRoot ? path.join(detectedRoot, 'flattened-codebase.xml') : path.resolve('flattened-codebase.xml');
-
-      if (detectedRoot) {
-        const useDefaults = await promptYesNo(
-          `Detected project root at "${detectedRoot}". Use it as input and write output to "${suggestedOutput}"?`,
-          true,
-        );
-        if (useDefaults) {
-          inputDir = detectedRoot;
-          outputPath = suggestedOutput;
-        } else {
-          inputDir = await promptPath('Enter input directory path', process.cwd());
-          outputPath = await promptPath('Enter output file path', path.join(inputDir, 'flattened-codebase.xml'));
-        }
-      } else {
-        console.log('Could not auto-detect a project root.');
-        inputDir = await promptPath('Enter input directory path', process.cwd());
-        outputPath = await promptPath('Enter output file path', path.join(inputDir, 'flattened-codebase.xml'));
-      }
-    }
-
-    // Ensure output directory exists
-    await fs.ensureDir(path.dirname(outputPath));
-
-    try {
-      // Verify input directory exists
-      if (!(await fs.pathExists(inputDir))) {
-        console.error(`❌ Error: Input directory does not exist: ${inputDir}`);
-        process.exit(1);
-      }
-
-      // Import ora dynamically
-      const { default: ora } = await import('ora');
-
-      // Start file discovery with spinner
-      const discoverySpinner = ora('🔍 Discovering files...').start();
-      const files = await discoverFiles(inputDir);
-      const filteredFiles = await filterFiles(files, inputDir);
-      discoverySpinner.succeed(`📁 Found ${filteredFiles.length} files to include`);
-
-      // Process files with progress tracking
-      console.log('Reading file contents');
-      const processingSpinner = ora('📄 Processing files...').start();
-      const aggregatedContent = await aggregateFileContents(filteredFiles, inputDir, processingSpinner);
-      processingSpinner.succeed(`✅ Processed ${aggregatedContent.processedFiles}/${filteredFiles.length} files`);
-      if (aggregatedContent.errors.length > 0) {
-        console.log(`Errors: ${aggregatedContent.errors.length}`);
-      }
-
-      // Generate XML output using streaming
-      const xmlSpinner = ora('🔧 Generating XML output...').start();
-      await generateXMLOutput(aggregatedContent, outputPath);
-      xmlSpinner.succeed('📝 XML generation completed');
-
-      // Calculate and display statistics
-      const outputStats = await fs.stat(outputPath);
-      const stats = await calculateStatistics(aggregatedContent, outputStats.size, inputDir);
-
-      // Display completion summary
-      console.log('\n📊 Completion Summary:');
-      console.log(`✅ Successfully processed ${filteredFiles.length} files into ${path.basename(outputPath)}`);
-      console.log(`📁 Output file: ${outputPath}`);
-      console.log(`📏 Total source size: ${stats.totalSize}`);
-      console.log(`📄 Generated XML size: ${stats.xmlSize}`);
-      console.log(`📝 Total lines of code: ${stats.totalLines.toLocaleString()}`);
-      console.log(`🔢 Estimated tokens: ${stats.estimatedTokens}`);
-      console.log(`📊 File breakdown: ${stats.textFiles} text, ${stats.binaryFiles} binary, ${stats.errorFiles} errors\n`);
-
-      // Ask user if they want detailed stats + markdown report
-      const generateDetailed = await promptYesNo('Generate detailed stats (console + markdown) now?', true);
-
-      if (generateDetailed) {
-        // Additional detailed stats
-        console.log('\n📈 Size Percentiles:');
-        console.log(
-          `   Avg: ${Math.round(stats.avgFileSize).toLocaleString()} B, Median: ${Math.round(
-            stats.medianFileSize,
-          ).toLocaleString()} B, p90: ${stats.p90.toLocaleString()} B, p95: ${stats.p95.toLocaleString()} B, p99: ${stats.p99.toLocaleString()} B`,
-        );
-
-        if (Array.isArray(stats.histogram) && stats.histogram.length > 0) {
-          console.log('\n🧮 Size Histogram:');
-          for (const b of stats.histogram.slice(0, 2)) {
-            console.log(`   ${b.label}: ${b.count} files, ${b.bytes.toLocaleString()} bytes`);
-          }
-          if (stats.histogram.length > 2) {
-            console.log(`   … and ${stats.histogram.length - 2} more buckets`);
-          }
-        }
-
-        if (Array.isArray(stats.byExtension) && stats.byExtension.length > 0) {
-          const topExt = stats.byExtension.slice(0, 2);
-          console.log('\n📦 Top Extensions:');
-          for (const e of topExt) {
-            const pct = stats.totalBytes ? (e.bytes / stats.totalBytes) * 100 : 0;
-            console.log(`   ${e.ext}: ${e.count} files, ${e.bytes.toLocaleString()} bytes (${pct.toFixed(2)}%)`);
-          }
-          if (stats.byExtension.length > 2) {
-            console.log(`   … and ${stats.byExtension.length - 2} more extensions`);
-          }
-        }
-
-        if (Array.isArray(stats.byDirectory) && stats.byDirectory.length > 0) {
-          const topDir = stats.byDirectory.slice(0, 2);
-          console.log('\n📂 Top Directories:');
-          for (const d of topDir) {
-            const pct = stats.totalBytes ? (d.bytes / stats.totalBytes) * 100 : 0;
-            console.log(`   ${d.dir}: ${d.count} files, ${d.bytes.toLocaleString()} bytes (${pct.toFixed(2)}%)`);
-          }
-          if (stats.byDirectory.length > 2) {
-            console.log(`   … and ${stats.byDirectory.length - 2} more directories`);
-          }
-        }
-
-        if (Array.isArray(stats.depthDistribution) && stats.depthDistribution.length > 0) {
-          console.log('\n🌳 Depth Distribution:');
-          const dd = stats.depthDistribution.slice(0, 2);
-          let line = '   ' + dd.map((d) => `${d.depth}:${d.count}`).join('  ');
-          if (stats.depthDistribution.length > 2) {
-            line += `  … +${stats.depthDistribution.length - 2} more`;
-          }
-          console.log(line);
-        }
-
-        if (Array.isArray(stats.longestPaths) && stats.longestPaths.length > 0) {
-          console.log('\n🧵 Longest Paths:');
-          for (const p of stats.longestPaths.slice(0, 2)) {
-            console.log(`   ${p.path} (${p.length} chars, ${p.size.toLocaleString()} bytes)`);
-          }
-          if (stats.longestPaths.length > 2) {
-            console.log(`   … and ${stats.longestPaths.length - 2} more paths`);
-          }
-        }
-
-        if (stats.temporal) {
-          console.log('\n⏱️ Temporal:');
-          if (stats.temporal.oldest) {
-            console.log(`   Oldest: ${stats.temporal.oldest.path} (${stats.temporal.oldest.mtime})`);
-          }
-          if (stats.temporal.newest) {
-            console.log(`   Newest: ${stats.temporal.newest.path} (${stats.temporal.newest.mtime})`);
-          }
-          if (Array.isArray(stats.temporal.ageBuckets)) {
-            console.log('   Age buckets:');
-            for (const b of stats.temporal.ageBuckets.slice(0, 2)) {
-              console.log(`     ${b.label}: ${b.count} files, ${b.bytes.toLocaleString()} bytes`);
-            }
-            if (stats.temporal.ageBuckets.length > 2) {
-              console.log(`     … and ${stats.temporal.ageBuckets.length - 2} more buckets`);
-            }
-          }
-        }
-
-        if (stats.quality) {
-          console.log('\n✅ Quality Signals:');
-          console.log(`   Zero-byte files: ${stats.quality.zeroByteFiles}`);
-          console.log(`   Empty text files: ${stats.quality.emptyTextFiles}`);
-          console.log(`   Hidden files: ${stats.quality.hiddenFiles}`);
-          console.log(`   Symlinks: ${stats.quality.symlinks}`);
-          console.log(
-            `   Large files (>= ${(stats.quality.largeThreshold / (1024 * 1024)).toFixed(0)} MB): ${stats.quality.largeFilesCount}`,
-          );
-          console.log(`   Suspiciously large files (>= 100 MB): ${stats.quality.suspiciousLargeFilesCount}`);
-        }
-
-        if (Array.isArray(stats.duplicateCandidates) && stats.duplicateCandidates.length > 0) {
-          console.log('\n🧬 Duplicate Candidates:');
-          for (const d of stats.duplicateCandidates.slice(0, 2)) {
-            console.log(`   ${d.reason}: ${d.count} files @ ${d.size.toLocaleString()} bytes`);
-          }
-          if (stats.duplicateCandidates.length > 2) {
-            console.log(`   … and ${stats.duplicateCandidates.length - 2} more groups`);
-          }
-        }
-
-        if (typeof stats.compressibilityRatio === 'number') {
-          console.log(`\n🗜️ Compressibility ratio (sampled): ${(stats.compressibilityRatio * 100).toFixed(2)}%`);
-        }
-
-        if (stats.git && stats.git.isRepo) {
-          console.log('\n🔧 Git:');
-          console.log(`   Tracked: ${stats.git.trackedCount} files, ${stats.git.trackedBytes.toLocaleString()} bytes`);
-          console.log(`   Untracked: ${stats.git.untrackedCount} files, ${stats.git.untrackedBytes.toLocaleString()} bytes`);
-          if (Array.isArray(stats.git.lfsCandidates) && stats.git.lfsCandidates.length > 0) {
-            console.log('   LFS candidates (top 2):');
-            for (const f of stats.git.lfsCandidates.slice(0, 2)) {
-              console.log(`     ${f.path} (${f.size.toLocaleString()} bytes)`);
-            }
-            if (stats.git.lfsCandidates.length > 2) {
-              console.log(`     … and ${stats.git.lfsCandidates.length - 2} more`);
-            }
-          }
-        }
-
-        if (Array.isArray(stats.largestFiles) && stats.largestFiles.length > 0) {
-          console.log('\n📚 Largest Files (top 2):');
-          for (const f of stats.largestFiles.slice(0, 2)) {
-            // Show LOC for text files when available; omit ext and mtime
-            let locStr = '';
-            if (!f.isBinary && Array.isArray(aggregatedContent?.textFiles)) {
-              const tf = aggregatedContent.textFiles.find((t) => t.path === f.path);
-              if (tf && typeof tf.lines === 'number') {
-                locStr = `, LOC: ${tf.lines.toLocaleString()}`;
-              }
-            }
-            console.log(`   ${f.path} – ${f.sizeFormatted} (${f.percentOfTotal.toFixed(2)}%)${locStr}`);
-          }
-          if (stats.largestFiles.length > 2) {
-            console.log(`   … and ${stats.largestFiles.length - 2} more files`);
-          }
-        }
-
-        // Write a comprehensive markdown report next to the XML
-        {
-          const mdPath = outputPath.endsWith('.xml') ? outputPath.replace(/\.xml$/i, '.stats.md') : outputPath + '.stats.md';
-          try {
-            const pct = (num, den) => (den ? (num / den) * 100 : 0);
-            const md = [];
-            md.push(
-              `# 🧾 Flatten Stats for ${path.basename(outputPath)}`,
-              '',
-              '## 📊 Summary',
-              `- Total source size: ${stats.totalSize}`,
-              `- Generated XML size: ${stats.xmlSize}`,
-              `- Total lines of code: ${stats.totalLines.toLocaleString()}`,
-              `- Estimated tokens: ${stats.estimatedTokens}`,
-              `- File breakdown: ${stats.textFiles} text, ${stats.binaryFiles} binary, ${stats.errorFiles} errors`,
-              '',
-              '## 📈 Size Percentiles',
-              `Avg: ${Math.round(stats.avgFileSize).toLocaleString()} B, Median: ${Math.round(
-                stats.medianFileSize,
-              ).toLocaleString()} B, p90: ${stats.p90.toLocaleString()} B, p95: ${stats.p95.toLocaleString()} B, p99: ${stats.p99.toLocaleString()} B`,
-              '',
-            );
-
-            // Histogram
-            if (Array.isArray(stats.histogram) && stats.histogram.length > 0) {
-              md.push('## 🧮 Size Histogram', '| Bucket | Files | Bytes |', '| --- | ---: | ---: |');
-              for (const b of stats.histogram) {
-                md.push(`| ${b.label} | ${b.count} | ${b.bytes.toLocaleString()} |`);
-              }
-              md.push('');
-            }
-
-            // Top Extensions
-            if (Array.isArray(stats.byExtension) && stats.byExtension.length > 0) {
-              md.push('## 📦 Top Extensions by Bytes (Top 20)', '| Ext | Files | Bytes | % of total |', '| --- | ---: | ---: | ---: |');
-              for (const e of stats.byExtension.slice(0, 20)) {
-                const p = pct(e.bytes, stats.totalBytes);
-                md.push(`| ${e.ext} | ${e.count} | ${e.bytes.toLocaleString()} | ${p.toFixed(2)}% |`);
-              }
-              md.push('');
-            }
-
-            // Top Directories
-            if (Array.isArray(stats.byDirectory) && stats.byDirectory.length > 0) {
-              md.push(
-                '## 📂 Top Directories by Bytes (Top 20)',
-                '| Directory | Files | Bytes | % of total |',
-                '| --- | ---: | ---: | ---: |',
-              );
-              for (const d of stats.byDirectory.slice(0, 20)) {
-                const p = pct(d.bytes, stats.totalBytes);
-                md.push(`| ${d.dir} | ${d.count} | ${d.bytes.toLocaleString()} | ${p.toFixed(2)}% |`);
-              }
-              md.push('');
-            }
-
-            // Depth distribution
-            if (Array.isArray(stats.depthDistribution) && stats.depthDistribution.length > 0) {
-              md.push('## 🌳 Depth Distribution', '| Depth | Count |', '| ---: | ---: |');
-              for (const d of stats.depthDistribution) {
-                md.push(`| ${d.depth} | ${d.count} |`);
-              }
-              md.push('');
-            }
-
-            // Longest paths
-            if (Array.isArray(stats.longestPaths) && stats.longestPaths.length > 0) {
-              md.push('## 🧵 Longest Paths (Top 25)', '| Path | Length | Bytes |', '| --- | ---: | ---: |');
-              for (const pth of stats.longestPaths) {
-                md.push(`| ${pth.path} | ${pth.length} | ${pth.size.toLocaleString()} |`);
-              }
-              md.push('');
-            }
-
-            // Temporal
-            if (stats.temporal) {
-              md.push('## ⏱️ Temporal');
-              if (stats.temporal.oldest) {
-                md.push(`- Oldest: ${stats.temporal.oldest.path} (${stats.temporal.oldest.mtime})`);
-              }
-              if (stats.temporal.newest) {
-                md.push(`- Newest: ${stats.temporal.newest.path} (${stats.temporal.newest.mtime})`);
-              }
-              if (Array.isArray(stats.temporal.ageBuckets)) {
-                md.push('', '| Age | Files | Bytes |', '| --- | ---: | ---: |');
-                for (const b of stats.temporal.ageBuckets) {
-                  md.push(`| ${b.label} | ${b.count} | ${b.bytes.toLocaleString()} |`);
-                }
-              }
-              md.push('');
-            }
-
-            // Quality signals
-            if (stats.quality) {
-              md.push(
-                '## ✅ Quality Signals',
-                `- Zero-byte files: ${stats.quality.zeroByteFiles}`,
-                `- Empty text files: ${stats.quality.emptyTextFiles}`,
-                `- Hidden files: ${stats.quality.hiddenFiles}`,
-                `- Symlinks: ${stats.quality.symlinks}`,
-                `- Large files (>= ${(stats.quality.largeThreshold / (1024 * 1024)).toFixed(0)} MB): ${stats.quality.largeFilesCount}`,
-                `- Suspiciously large files (>= 100 MB): ${stats.quality.suspiciousLargeFilesCount}`,
-                '',
-              );
-            }
-
-            // Duplicates
-            if (Array.isArray(stats.duplicateCandidates) && stats.duplicateCandidates.length > 0) {
-              md.push('## 🧬 Duplicate Candidates', '| Reason | Files | Size (bytes) |', '| --- | ---: | ---: |');
-              for (const d of stats.duplicateCandidates) {
-                md.push(`| ${d.reason} | ${d.count} | ${d.size.toLocaleString()} |`);
-              }
-              md.push('', '### 🧬 Duplicate Groups Details');
-              let dupIndex = 1;
-              for (const d of stats.duplicateCandidates) {
-                md.push(`#### Group ${dupIndex}: ${d.count} files @ ${d.size.toLocaleString()} bytes (${d.reason})`);
-                if (Array.isArray(d.files) && d.files.length > 0) {
-                  for (const fp of d.files) {
-                    md.push(`- ${fp}`);
-                  }
-                } else {
-                  md.push('- (file list unavailable)');
-                }
-                md.push('');
-                dupIndex++;
-              }
-              md.push('');
-            }
-
-            // Compressibility
-            if (typeof stats.compressibilityRatio === 'number') {
-              md.push('## 🗜️ Compressibility', `Sampled compressibility ratio: ${(stats.compressibilityRatio * 100).toFixed(2)}%`, '');
-            }
-
-            // Git
-            if (stats.git && stats.git.isRepo) {
-              md.push(
-                '## 🔧 Git',
-                `- Tracked: ${stats.git.trackedCount} files, ${stats.git.trackedBytes.toLocaleString()} bytes`,
-                `- Untracked: ${stats.git.untrackedCount} files, ${stats.git.untrackedBytes.toLocaleString()} bytes`,
-              );
-              if (Array.isArray(stats.git.lfsCandidates) && stats.git.lfsCandidates.length > 0) {
-                md.push('', '### 📦 LFS Candidates (Top 20)', '| Path | Bytes |', '| --- | ---: |');
-                for (const f of stats.git.lfsCandidates.slice(0, 20)) {
-                  md.push(`| ${f.path} | ${f.size.toLocaleString()} |`);
-                }
-              }
-              md.push('');
-            }
-
-            // Largest Files
-            if (Array.isArray(stats.largestFiles) && stats.largestFiles.length > 0) {
-              md.push('## 📚 Largest Files (Top 50)', '| Path | Size | % of total | LOC |', '| --- | ---: | ---: | ---: |');
-              for (const f of stats.largestFiles) {
-                let loc = '';
-                if (!f.isBinary && Array.isArray(aggregatedContent?.textFiles)) {
-                  const tf = aggregatedContent.textFiles.find((t) => t.path === f.path);
-                  if (tf && typeof tf.lines === 'number') {
-                    loc = tf.lines.toLocaleString();
-                  }
-                }
-                md.push(`| ${f.path} | ${f.sizeFormatted} | ${f.percentOfTotal.toFixed(2)}% | ${loc} |`);
-              }
-              md.push('');
-            }
-
-            await fs.writeFile(mdPath, md.join('\n'));
-            console.log(`\n🧾 Detailed stats report written to: ${mdPath}`);
-          } catch (error) {
-            console.warn(`⚠️ Failed to write stats markdown: ${error.message}`);
-          }
-        }
-      }
-    } catch (error) {
-      console.error('❌ Critical error:', error.message);
-      console.error('An unexpected error occurred.');
-      process.exit(1);
-    }
-  });
-
-if (require.main === module) {
-  program.parse();
-}
-
-module.exports = program;

package/tools/flattener/projectRoot.js

@@ -1,201 +0,0 @@
-const fs = require('fs-extra');
-const path = require('node:path');
-
-// Deno/Node compatibility: explicitly import process
-const process = require('node:process');
-const { execFile } = require('node:child_process');
-const { promisify } = require('node:util');
-const execFileAsync = promisify(execFile);
-
-// Simple memoization across calls (keyed by realpath of startDir)
-const _cache = new Map();
-
-async function _tryRun(cmd, args, cwd, timeoutMs = 500) {
-  try {
-    const { stdout } = await execFileAsync(cmd, args, {
-      cwd,
-      timeout: timeoutMs,
-      windowsHide: true,
-      maxBuffer: 1024 * 1024,
-    });
-    const out = String(stdout || '').trim();
-    return out || null;
-  } catch {
-    return null;
-  }
-}
-
-async function _detectVcsTopLevel(startDir) {
-  // Run common VCS root queries in parallel; ignore failures
-  const gitP = _tryRun('git', ['rev-parse', '--show-toplevel'], startDir);
-  const hgP = _tryRun('hg', ['root'], startDir);
-  const svnP = (async () => {
-    const show = await _tryRun('svn', ['info', '--show-item', 'wc-root'], startDir);
-    if (show) return show;
-    const info = await _tryRun('svn', ['info'], startDir);
-    if (info) {
-      const line = info.split(/\r?\n/).find((l) => l.toLowerCase().startsWith('working copy root path:'));
-      if (line) return line.split(':').slice(1).join(':').trim();
-    }
-    return null;
-  })();
-  const [git, hg, svn] = await Promise.all([gitP, hgP, svnP]);
-  return git || hg || svn || null;
-}
-
-/**
- * Attempt to find the project root by walking up from startDir.
- * Uses a robust, prioritized set of ecosystem markers (VCS > workspaces/monorepo > lock/build > language config).
- * Also recognizes package.json with "workspaces" as a workspace root.
- * You can augment markers via env PROJECT_ROOT_MARKERS as a comma-separated list of file/dir names.
- * @param {string} startDir
- * @returns {Promise<string|null>} project root directory or null if not found
- */
-async function findProjectRoot(startDir) {
-  try {
-    // Resolve symlinks for robustness (e.g., when invoked from a symlinked path)
-    let dir = path.resolve(startDir);
-    try {
-      dir = await fs.realpath(dir);
-    } catch {
-      // ignore if realpath fails; continue with resolved path
-    }
-    const startKey = dir; // preserve starting point for caching
-    if (_cache.has(startKey)) return _cache.get(startKey);
-    const fsRoot = path.parse(dir).root;
-
-    // Helper to safely check for existence
-    const exists = (p) => fs.pathExists(p);
-
-    // Build checks: an array of { makePath: (dir) => string, weight }
-    const checks = [];
-
-    const add = (rel, weight) => {
-      const makePath = (d) => (Array.isArray(rel) ? path.join(d, ...rel) : path.join(d, rel));
-      checks.push({ makePath, weight });
-    };
-
-    // Highest priority: explicit sentinel markers
-    add('.project-root', 110);
-    add('.workspace-root', 110);
-    add('.repo-root', 110);
-
-    // Highest priority: VCS roots
-    add('.git', 100);
-    add('.hg', 95);
-    add('.svn', 95);
-
-    // Monorepo/workspace indicators
-    add('pnpm-workspace.yaml', 90);
-    add('lerna.json', 90);
-    add('turbo.json', 90);
-    add('nx.json', 90);
-    add('rush.json', 90);
-    add('go.work', 90);
-    add('WORKSPACE', 90);
-    add('WORKSPACE.bazel', 90);
-    add('MODULE.bazel', 90);
-    add('pants.toml', 90);
-
-    // Lockfiles and package-manager/top-level locks
-    add('yarn.lock', 85);
-    add('pnpm-lock.yaml', 85);
-    add('package-lock.json', 85);
-    add('bun.lockb', 85);
-    add('Cargo.lock', 85);
-    add('composer.lock', 85);
-    add('poetry.lock', 85);
-    add('Pipfile.lock', 85);
-    add('Gemfile.lock', 85);
-
-    // Build-system root indicators
-    add('settings.gradle', 80);
-    add('settings.gradle.kts', 80);
-    add('gradlew', 80);
-    add('pom.xml', 80);
-    add('build.sbt', 80);
-    add(['project', 'build.properties'], 80);
-
-    // Language/project config markers
-    add('deno.json', 75);
-    add('deno.jsonc', 75);
-    add('pyproject.toml', 75);
-    add('Pipfile', 75);
-    add('requirements.txt', 75);
-    add('go.mod', 75);
-    add('Cargo.toml', 75);
-    add('composer.json', 75);
-    add('mix.exs', 75);
-    add('Gemfile', 75);
-    add('CMakeLists.txt', 75);
-    add('stack.yaml', 75);
-    add('cabal.project', 75);
-    add('rebar.config', 75);
-    add('pubspec.yaml', 75);
-    add('flake.nix', 75);
-    add('shell.nix', 75);
-    add('default.nix', 75);
-    add('.tool-versions', 75);
-    add('package.json', 74); // generic Node project (lower than lockfiles/workspaces)
-
-    // Changesets
-    add(['.changeset', 'config.json'], 70);
-    add('.changeset', 70);
-
-    // Custom markers via env (comma-separated names)
-    if (process.env.PROJECT_ROOT_MARKERS) {
-      for (const name of process.env.PROJECT_ROOT_MARKERS.split(',')
-        .map((s) => s.trim())
-        .filter(Boolean)) {
-        add(name, 72);
-      }
-    }
-
-    /** Check for package.json with "workspaces" */
-    const hasWorkspacePackageJson = async (d) => {
-      const pkgPath = path.join(d, 'package.json');
-      if (!(await exists(pkgPath))) return false;
-      try {
-        const raw = await fs.readFile(pkgPath, 'utf8');
-        const pkg = JSON.parse(raw);
-        return Boolean(pkg && pkg.workspaces);
-      } catch {
-        return false;
-      }
-    };
-
-    let best = null; // { dir, weight }
-
-    // Try to detect VCS toplevel once up-front; treat as authoritative slightly above .git marker
-    const vcsTop = await _detectVcsTopLevel(dir);
-    if (vcsTop) {
-      best = { dir: vcsTop, weight: 101 };
-    }
-
-    while (true) {
-      // Special check: package.json with "workspaces"
-      if ((await hasWorkspacePackageJson(dir)) && (!best || 90 >= best.weight)) best = { dir, weight: 90 };
-
-      // Evaluate all other checks in parallel
-      const results = await Promise.all(checks.map(async (c) => ({ c, ok: await exists(c.makePath(dir)) })));
-
-      for (const { c, ok } of results) {
-        if (!ok) continue;
-        if (!best || c.weight >= best.weight) {
-          best = { dir, weight: c.weight };
-        }
-      }
-
-      if (dir === fsRoot) break;
-      dir = path.dirname(dir);
-    }
-
-    const out = best ? best.dir : null;
-    _cache.set(startKey, out);
-    return out;
-  } catch {
-    return null;
-  }
-}
-
-module.exports = { findProjectRoot };