bmad-elsabro 1.0.0

package/tools/flattener/main.ts

@@ -0,0 +1,262 @@
+import { Command } from 'commander';
+import fs from 'fs-extra';
+import path from 'node:path';
+import process from 'node:process';
+
+// Modularized components
+import { findProjectRoot } from './projectRoot.js';
+import { promptYesNo, promptPath } from './prompts.js';
+import { discoverFiles, filterFiles, aggregateFileContents } from './files.js';
+import { generateXMLOutput } from './xml.js';
+import { calculateStatistics } from './stats.js';
+
+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: { input: string; output: string }) => {
+    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 (stats.depthDistribution && Array.isArray(stats.depthDistribution) && stats.depthDistribution.length > 0) {
+          console.log('\n📁 Depth Distribution:');
+          const topDepth = stats.depthDistribution.slice(0, 5);
+          for (const d of topDepth) {
+            console.log(`   Depth ${d.depth}: ${d.count} files`);
+          }
+          if (stats.depthDistribution.length > 5) {
+            console.log(`   … and ${stats.depthDistribution.length - 5} more depth levels`);
+          }
+        }
+
+        if (stats.longestPaths && Array.isArray(stats.longestPaths) && stats.longestPaths.length > 0) {
+          console.log('\n📏 Longest Paths:');
+          const topLongest = stats.longestPaths.slice(0, 5);
+          for (const l of topLongest) {
+            console.log(`   ${l.path} (${l.length} chars)`);
+          }
+        }
+
+        if (stats.temporal) {
+          const t = stats.temporal;
+          console.log('\n⏰ Temporal Analysis:');
+          if (t.hasTimestamps) {
+            if (typeof t.newest === 'string') {
+              console.log(`   Newest: ${t.newest}`);
+            }
+            if (typeof t.oldest === 'string') {
+              console.log(`   Oldest: ${t.oldest}`);
+            }
+            if (typeof t.last30Days === 'number') {
+              console.log(`   Files modified in last 30 days: ${t.last30Days}`);
+            }
+          } else {
+            console.log('   (No file timestamps available)');
+          }
+        }
+
+        if (stats.quality) {
+          const q = stats.quality;
+          console.log('\n🔍 Quality Signals:');
+          if (typeof q.largeFiles === 'number') {
+            console.log(`   Large files (>${q.largeThreshold?.toLocaleString() || 'N/A'} B): ${q.largeFiles}`);
+          }
+          if (typeof q.veryLongLines === 'number') {
+            console.log(`   Files with very long lines (>300 chars): ${q.veryLongLines}`);
+          }
+          if (typeof q.noNewlineAtEnd === 'number') {
+            console.log(`   Files missing newline at end: ${q.noNewlineAtEnd}`);
+          }
+        }
+
+        if (
+          stats.duplicateCandidates &&
+          Array.isArray(stats.duplicateCandidates) &&
+          stats.duplicateCandidates.length > 0
+        ) {
+          console.log('\n🔁 Duplicate Candidates (by size):');
+          const topDup = stats.duplicateCandidates.slice(0, 3);
+          for (const d of topDup) {
+            console.log(`   ${d.count} files of size ${d.size.toLocaleString()} bytes`);
+            if (Array.isArray(d.files)) {
+              for (const f of d.files.slice(0, 2)) {
+                console.log(`      - ${f}`);
+              }
+              if (d.files.length > 2) {
+                console.log(`      … and ${d.files.length - 2} more`);
+              }
+            }
+          }
+        }
+
+        if (typeof stats.compressibilityRatio === 'string') {
+          console.log(`\n📦 Estimated Compressibility: ${stats.compressibilityRatio}`);
+        }
+
+        if (stats.git) {
+          const g = stats.git;
+          console.log('\n🌿 Git Information:');
+          if (typeof g.trackedCount === 'number') {
+            console.log(`   Tracked files: ${g.trackedCount}`);
+          }
+          if (typeof g.untrackedCount === 'number') {
+            console.log(`   Untracked files: ${g.untrackedCount}`);
+          }
+          if (typeof g.trackedLarge === 'number' && g.trackedLarge > 0) {
+            console.log(`   Large tracked files: ${g.trackedLarge}`);
+          }
+        }
+
+        if (stats.largestFiles && Array.isArray(stats.largestFiles) && stats.largestFiles.length > 0) {
+          console.log('\n📊 Largest Files:');
+          const topLargest = stats.largestFiles.slice(0, 5);
+          for (const l of topLargest) {
+            const pct = stats.totalBytes ? (l.size / stats.totalBytes) * 100 : 0;
+            console.log(`   ${l.path}: ${l.size.toLocaleString()} bytes (${pct.toFixed(2)}%)`);
+          }
+          if (stats.largestFiles.length > 5) {
+            console.log(`   … and ${stats.largestFiles.length - 5} more files`);
+          }
+        }
+
+        // Write markdown report
+        if (stats.markdownReport) {
+          const reportPath = outputPath.replace(/\.xml$/, '-report.md');
+          await fs.writeFile(reportPath, stats.markdownReport, 'utf8');
+          console.log(`\n✅ Detailed markdown report written to: ${reportPath}`);
+        }
+      }
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      console.error(`❌ Error: ${errorMessage}`);
+      process.exit(1);
+    }
+  });
+
+program.parse();

package/tools/flattener/projectRoot.js

@@ -0,0 +1,201 @@
+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 };

package/tools/flattener/prompts.js

@@ -0,0 +1,44 @@
+const os = require('node:os');
+const path = require('node:path');
+const readline = require('node:readline');
+const process = require('node:process');
+
+function expandHome(p) {
+  if (!p) return p;
+  if (p.startsWith('~')) return path.join(os.homedir(), p.slice(1));
+  return p;
+}
+
+function createRl() {
+  return readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+}
+
+function promptQuestion(question) {
+  return new Promise((resolve) => {
+    const rl = createRl();
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer);
+    });
+  });
+}
+
+async function promptYesNo(question, defaultYes = true) {
+  const suffix = defaultYes ? ' [Y/n] ' : ' [y/N] ';
+  const ans = (await promptQuestion(`${question}${suffix}`)).trim().toLowerCase();
+  if (!ans) return defaultYes;
+  if (['y', 'yes'].includes(ans)) return true;
+  if (['n', 'no'].includes(ans)) return false;
+  return promptYesNo(question, defaultYes);
+}
+
+async function promptPath(question, defaultValue) {
+  const prompt = `${question}${defaultValue ? ` (default: ${defaultValue})` : ''}: `;
+  const ans = (await promptQuestion(prompt)).trim();
+  return expandHome(ans || defaultValue);
+}
+
+module.exports = { promptYesNo, promptPath, promptQuestion, expandHome };