bun-ready 0.2.3 → 0.2.5

package/README.md

@@ -23,7 +23,7 @@ bun-ready scan .
 
 ## Usage
 ```bash
-bun-ready scan <path> [--format md|json] [--out <file>] [--no-install] [--no-test] [--verbose]
+bun-ready scan <path> [--format md|json] [--out <file>] [--no-install] [--no-test] [--verbose] [--detailed]
 ```
 
 ## Examples:
@@ -32,6 +32,7 @@ bun-ready scan .
 bun-ready scan . --out bun-ready.md
 bun-ready scan ./packages/api --format json
 bun-ready scan . --no-install --no-test
+bun-ready scan . --detailed
 ```
 
 ## Exit codes
@@ -71,6 +72,7 @@ You can create a `bun-ready.config.json` file in your repository root to customi
 | `ignoreFindings` | Array of finding IDs to ignore | `[]` |
 | `nativeAddonAllowlist` | Packages to exclude from native addon checks | `[]` |
 | `failOn` | When to return non-zero exit code | `"red"` |
+| `detailed` | Enable detailed package usage analysis | `false` |
 
 ### New CLI Flags
 
@@ -80,10 +82,68 @@ You can create a `bun-ready.config.json` file in your repository root to customi
 - `all`: Scan root and all workspace packages (default)
 
 `--fail-on green|yellow|red`
-- Controls when bun-ready exits with a failure code
-- `green`: Fail on anything not green (exit 3)
-- `yellow`: Fail on red only (exit 3), yellow passes (exit 0)
-- `red`: Default behavior - green=0, yellow=2, red=3
+ - Controls when bun-ready exits with a failure code
+ - `green`: Fail on anything not green (exit 3)
+ - `yellow`: Fail on red only (exit 3), yellow passes (exit 0)
+ - `red`: Default behavior - green=0, yellow=2, red=3
+
+`--detailed`
+ - Enables detailed package usage analysis
+ - Shows which packages are used in which files
+ - Provides file-by-file breakdown of imports
+ - Output is written to `bun-ready-detailed.md` instead of `bun-ready.md`
+ - Requires scanning of all `.ts`, `.js`, `.tsx`, `.jsx` files in the project
+ - **Note:** This operation is slower as it needs to read and parse all source files
+
+## Detailed Reports
+
+When using the `--detailed` flag, bun-ready provides comprehensive package usage information:
+
+### What it analyzes:
+- All source files with extensions: `.ts`, `.js`, `.tsx`, `.jsx`, `.mts`, `.mjs`
+- Import patterns supported:
+  - ES6 imports: `import ... from 'package-name'`
+  - Namespace imports: `import * as name from 'package-name'`
+  - Dynamic imports: `import('package-name')`
+  - CommonJS requires: `require('package-name')`
+- Local imports (starting with `./` or `../`) are ignored
+- Skips `node_modules` and hidden directories
+
+### Output format:
+
+The detailed report shows:
+1. **Package Summary** - Total files analyzed and packages used
+2. **Per-package usage** - For each package in your dependencies:
+   - How many files import it
+   - List of all file paths where it's used
+3. **Regular findings** - All migration risk findings from standard analysis
+
+### Example:
+```bash
+bun-ready scan . --detailed
+```
+
+This generates `bun-ready-detailed.md` with sections like:
+
+```markdown
+### @nestjs/common (15 files)
+- src/main.ts
+- src/app.module.ts
+- src/auth/auth.service.ts
+...
+```
+
+### Configuration:
+
+You can also enable detailed reports via config file:
+
+```json
+{
+  "detailed": true
+}
+```
+
+When `detailed` is set in config, it acts as if `--detailed` was passed, unless overridden by CLI flags.
 
 ## How Scoring Works
 

package/dist/cli.js

@@ -87,14 +87,14 @@ var init_bun_check = __esm(() => {
 });
 
 // src/cli.ts
-import { promises as fs3 } from "node:fs";
-import path5 from "node:path";
+import { promises as fs4 } from "node:fs";
+import path6 from "node:path";
 
 // src/analyze.ts
 init_spawn();
-import path4 from "node:path";
+import path5 from "node:path";
 import os from "node:os";
-import { promises as fs2 } from "node:fs";
+import { promises as fs3 } from "node:fs";
 
 // src/util.ts
 import { promises as fs } from "node:fs";
@@ -488,6 +488,173 @@ var summarizeSeverity = (findings, installOk, testOk) => {
     sev = "red";
   return sev;
 };
+var calculatePackageStats = (pkg, findings) => {
+  const dependencies = pkg.dependencies || {};
+  const devDependencies = pkg.devDependencies || {};
+  const riskyPackageNames = new Set;
+  for (const finding of findings) {
+    for (const detail of finding.details) {
+      const match = detail.match(/^([a-zA-Z0-9_@\/\.\-]+)/);
+      if (match && match[1]) {
+        const fullPkg = match[1];
+        const pkgName = fullPkg.split(/[@:]/)[0];
+        if (pkgName) {
+          riskyPackageNames.add(pkgName);
+        }
+      }
+    }
+  }
+  let cleanDependencies = 0;
+  let riskyDependencies = 0;
+  let cleanDevDependencies = 0;
+  let riskyDevDependencies = 0;
+  for (const depName of Object.keys(dependencies)) {
+    if (riskyPackageNames.has(depName)) {
+      riskyDependencies++;
+    } else {
+      cleanDependencies++;
+    }
+  }
+  for (const depName of Object.keys(devDependencies)) {
+    if (riskyPackageNames.has(depName)) {
+      riskyDevDependencies++;
+    } else {
+      cleanDevDependencies++;
+    }
+  }
+  return {
+    totalDependencies: Object.keys(dependencies).length,
+    totalDevDependencies: Object.keys(devDependencies).length,
+    cleanDependencies,
+    cleanDevDependencies,
+    riskyDependencies,
+    riskyDevDependencies
+  };
+};
+var calculateFindingsSummary = (findings) => {
+  let green = 0;
+  let yellow = 0;
+  let red = 0;
+  for (const finding of findings) {
+    if (finding.severity === "green") {
+      green++;
+    } else if (finding.severity === "yellow") {
+      yellow++;
+    } else if (finding.severity === "red") {
+      red++;
+    }
+  }
+  return {
+    green,
+    yellow,
+    red,
+    total: green + yellow + red
+  };
+};
+
+// src/usage_analyzer.ts
+import { promises as fs2 } from "node:fs";
+import path2 from "node:path";
+var SUPPORTED_EXTENSIONS = [".ts", ".js", ".tsx", ".jsx", ".mts", ".mjs"];
+var IMPORT_PATTERNS = [
+  /import\s+(?:\{[^}]*\}|\*\s+as\s+\w+|\w+)\s+from\s+['"]([^./][^'"]*)['"]/g,
+  /import\s*\(\s*['"]([^./][^'"]*)['"]\s*\)/g,
+  /require\s*\(\s*['"]([^./][^'"]*)['"]\s*\)/g
+];
+function extractPackageNames(content) {
+  const packageSet = new Set;
+  for (const pattern of IMPORT_PATTERNS) {
+    let match;
+    while ((match = pattern.exec(content)) !== null) {
+      const packageName = match[1];
+      if (packageName) {
+        packageSet.add(packageName);
+      }
+    }
+  }
+  return Array.from(packageSet);
+}
+async function findSourceFiles(dirPath) {
+  const files = [];
+  let entries;
+  try {
+    entries = await fs2.readdir(dirPath, { withFileTypes: true });
+  } catch (error) {
+    return files;
+  }
+  for (const entry of entries) {
+    const fullPath = path2.join(dirPath, entry.name);
+    if (entry.name === "node_modules" || entry.name.startsWith(".")) {
+      continue;
+    }
+    if (entry.isDirectory()) {
+      const subFiles = await findSourceFiles(fullPath);
+      files.push(...subFiles);
+    } else if (entry.isFile()) {
+      const ext = path2.extname(entry.name);
+      if (SUPPORTED_EXTENSIONS.includes(ext)) {
+        files.push(fullPath);
+      }
+    }
+  }
+  return files;
+}
+function getAllPackageNames(pkg) {
+  const packageNames = new Set;
+  if (pkg.dependencies) {
+    Object.keys(pkg.dependencies).forEach((name) => packageNames.add(name));
+  }
+  if (pkg.devDependencies) {
+    Object.keys(pkg.devDependencies).forEach((name) => packageNames.add(name));
+  }
+  if (pkg.optionalDependencies) {
+    Object.keys(pkg.optionalDependencies).forEach((name) => packageNames.add(name));
+  }
+  return packageNames;
+}
+var analyzePackageUsageAsync = async (pkg, packagePath, includeDetails = true) => {
+  const packageNames = getAllPackageNames(pkg);
+  const totalPackages = packageNames.size;
+  const sourceFiles = await findSourceFiles(packagePath);
+  const analyzedFiles = sourceFiles.length;
+  const usageByPackage = new Map;
+  for (const pkgName of packageNames) {
+    usageByPackage.set(pkgName, {
+      packageName: pkgName,
+      fileCount: 0,
+      filePaths: []
+    });
+  }
+  for (const filePath of sourceFiles) {
+    try {
+      const content = await fs2.readFile(filePath, "utf-8");
+      const importedPackages = extractPackageNames(content);
+      for (const importedPkg of importedPackages) {
+        const usage = usageByPackage.get(importedPkg);
+        if (usage) {
+          usage.fileCount++;
+          if (includeDetails) {
+            const relativePath = path2.relative(packagePath, filePath);
+            usage.filePaths.push(relativePath);
+          }
+          usageByPackage.set(importedPkg, usage);
+        }
+      }
+    } catch (error) {
+      continue;
+    }
+  }
+  if (includeDetails) {
+    for (const usage of usageByPackage.values()) {
+      usage.filePaths.sort();
+    }
+  }
+  return {
+    totalPackages,
+    analyzedFiles,
+    usageByPackage
+  };
+};
 
 // src/bun_logs.ts
 function parseInstallLogs(logs) {
@@ -543,11 +710,11 @@ function parseInstallLogs(logs) {
 }
 
 // src/workspaces.ts
-import path2 from "node:path";
+import path3 from "node:path";
 import fsSync from "node:fs";
-function globMatch(pattern, path3) {
+function globMatch(pattern, path4) {
   const patternParts = pattern.split("/");
-  const pathParts = path3.split("/");
+  const pathParts = path4.split("/");
   let patternIdx = 0;
   let pathIdx = 0;
   while (patternIdx < patternParts.length && pathIdx < pathParts.length) {
@@ -585,16 +752,16 @@ function discoverFromWorkspaces(rootPath, workspaces) {
   const patterns = Array.isArray(workspaces) ? workspaces : workspaces.packages;
   const packages = [];
   for (const pattern of patterns) {
-    const patternPath = path2.resolve(rootPath, pattern);
+    const patternPath = path3.resolve(rootPath, pattern);
     if (pattern.includes("/*") && !pattern.includes("/**")) {
       try {
-        const baseDir = path2.dirname(patternPath);
-        const patternName = path2.basename(patternPath);
+        const baseDir = path3.dirname(patternPath);
+        const patternName = path3.basename(patternPath);
         const entries = fsSync.readdirSync(baseDir, { withFileTypes: true });
         for (const entry of entries) {
           if (entry.isDirectory() && globMatch(patternName, entry.name)) {
-            const packagePath = path2.join(baseDir, entry.name);
-            const pkgJsonPath = path2.join(packagePath, "package.json");
+            const packagePath = path3.join(baseDir, entry.name);
+            const pkgJsonPath = path3.join(packagePath, "package.json");
             if (fileExistsSync(pkgJsonPath)) {
               packages.push(packagePath);
             }
@@ -615,7 +782,7 @@ function fileExistsSync(filePath) {
 }
 async function discoverWorkspaces(rootPath) {
   const packages = [];
-  const rootPkgJson = path2.join(rootPath, "package.json");
+  const rootPkgJson = path3.join(rootPath, "package.json");
   if (!await fileExists(rootPkgJson)) {
     return packages;
   }
@@ -629,7 +796,7 @@ async function discoverWorkspaces(rootPath) {
   }
   const packagePaths = discoverFromWorkspaces(rootPath, workspaces);
   for (const pkgPath of packagePaths) {
-    const pkgJsonPath = path2.join(pkgPath, "package.json");
+    const pkgJsonPath = path3.join(pkgPath, "package.json");
     try {
       const pkg = await readJsonFile(pkgJsonPath);
       if (pkg.name) {
@@ -647,7 +814,7 @@ async function discoverWorkspaces(rootPath) {
   return packages;
 }
 async function hasWorkspaces(rootPath) {
-  const rootPkgJson = path2.join(rootPath, "package.json");
+  const rootPkgJson = path3.join(rootPath, "package.json");
   if (!await fileExists(rootPkgJson)) {
     return false;
   }
@@ -656,10 +823,10 @@ async function hasWorkspaces(rootPath) {
 }
 
 // src/config.ts
-import path3 from "node:path";
+import path4 from "node:path";
 var CONFIG_FILE_NAME = "bun-ready.config.json";
 async function readConfig(rootPath) {
-  const configPath = path3.join(rootPath, CONFIG_FILE_NAME);
+  const configPath = path4.join(rootPath, CONFIG_FILE_NAME);
   if (!await fileExists(configPath)) {
     return null;
   }
@@ -703,13 +870,16 @@ function validateConfig(config) {
       result.failOn = cfg.failOn;
     }
   }
+  if (typeof cfg.detailed === "boolean") {
+    result.detailed = cfg.detailed;
+  }
   if (Object.keys(result).length === 0) {
     return null;
   }
   return result;
 }
 function mergeConfigWithOpts(config, opts) {
-  if (!config && !opts.failOn) {
+  if (!config && !opts.failOn && opts.detailed === undefined) {
     return null;
   }
   const result = {
@@ -718,29 +888,32 @@ function mergeConfigWithOpts(config, opts) {
   if (opts.failOn) {
     result.failOn = opts.failOn;
   }
+  if (opts.detailed !== undefined) {
+    result.detailed = opts.detailed;
+  }
   return Object.keys(result).length > 0 ? result : null;
 }
 
 // src/analyze.ts
 async function readRepoInfo(packagePath) {
-  const packageJsonPath = path4.join(packagePath, "package.json");
+  const packageJsonPath = path5.join(packagePath, "package.json");
   const pkg = await readJsonFile(packageJsonPath);
   const scripts = pkg.scripts ?? {};
   const dependencies = pkg.dependencies ?? {};
   const devDependencies = pkg.devDependencies ?? {};
   const optionalDependencies = pkg.optionalDependencies ?? {};
   const lockfiles = {
-    bunLock: await fileExists(path4.join(packagePath, "bun.lock")),
-    bunLockb: await fileExists(path4.join(packagePath, "bun.lockb")),
-    npmLock: await fileExists(path4.join(packagePath, "package-lock.json")),
-    yarnLock: await fileExists(path4.join(packagePath, "yarn.lock")),
-    pnpmLock: await fileExists(path4.join(packagePath, "pnpm-lock.yaml"))
+    bunLock: await fileExists(path5.join(packagePath, "bun.lock")),
+    bunLockb: await fileExists(path5.join(packagePath, "bun.lockb")),
+    npmLock: await fileExists(path5.join(packagePath, "package-lock.json")),
+    yarnLock: await fileExists(path5.join(packagePath, "yarn.lock")),
+    pnpmLock: await fileExists(path5.join(packagePath, "pnpm-lock.yaml"))
   };
   return { pkg, scripts, dependencies, devDependencies, optionalDependencies, lockfiles };
 }
 async function copyIfExists(from, to) {
   try {
-    await fs2.copyFile(from, to);
+    await fs3.copyFile(from, to);
   } catch {
     return;
   }
@@ -758,21 +931,21 @@ async function runBunInstallDryRun(packagePath) {
       skipReason
     };
   }
-  const base = await fs2.mkdtemp(path4.join(os.tmpdir(), "bun-ready-"));
+  const base = await fs3.mkdtemp(path5.join(os.tmpdir(), "bun-ready-"));
   const cleanup = async () => {
     try {
-      await fs2.rm(base, { recursive: true, force: true });
+      await fs3.rm(base, { recursive: true, force: true });
     } catch {
       return;
     }
   };
   try {
-    await copyIfExists(path4.join(packagePath, "package.json"), path4.join(base, "package.json"));
-    await copyIfExists(path4.join(packagePath, "bun.lock"), path4.join(base, "bun.lock"));
-    await copyIfExists(path4.join(packagePath, "bun.lockb"), path4.join(base, "bun.lockb"));
-    await copyIfExists(path4.join(packagePath, "package-lock.json"), path4.join(base, "package-lock.json"));
-    await copyIfExists(path4.join(packagePath, "yarn.lock"), path4.join(base, "yarn.lock"));
-    await copyIfExists(path4.join(packagePath, "pnpm-lock.yaml"), path4.join(base, "pnpm-lock.yaml"));
+    await copyIfExists(path5.join(packagePath, "package.json"), path5.join(base, "package.json"));
+    await copyIfExists(path5.join(packagePath, "bun.lock"), path5.join(base, "bun.lock"));
+    await copyIfExists(path5.join(packagePath, "bun.lockb"), path5.join(base, "bun.lockb"));
+    await copyIfExists(path5.join(packagePath, "package-lock.json"), path5.join(base, "package-lock.json"));
+    await copyIfExists(path5.join(packagePath, "yarn.lock"), path5.join(base, "yarn.lock"));
+    await copyIfExists(path5.join(packagePath, "pnpm-lock.yaml"), path5.join(base, "pnpm-lock.yaml"));
     const res = await exec("bun", ["install", "--dry-run"], base);
     const combined = [...res.stdout ? res.stdout.split(`
 `) : [], ...res.stderr ? res.stderr.split(`
@@ -818,7 +991,7 @@ function filterFindings(findings, config) {
 }
 async function analyzeSinglePackage(packagePath, opts, config, pkgName) {
   const info = await readRepoInfo(packagePath);
-  const name = pkgName || info.pkg.name || path4.basename(packagePath);
+  const name = pkgName || info.pkg.name || path5.basename(packagePath);
   let findings = [
     ...detectLockfileSignals({ packageJsonPath: packagePath, lockfiles: info.lockfiles, scripts: info.scripts, dependencies: info.dependencies, devDependencies: info.devDependencies, optionalDependencies: info.optionalDependencies, hasWorkspaces: false, packageJson: info.pkg }),
     ...detectScriptRisks({ packageJsonPath: packagePath, lockfiles: info.lockfiles, scripts: info.scripts, dependencies: info.dependencies, devDependencies: info.devDependencies, optionalDependencies: info.optionalDependencies, hasWorkspaces: false, packageJson: info.pkg }),
@@ -877,13 +1050,22 @@ async function analyzeSinglePackage(packagePath, opts, config, pkgName) {
     testOk = testResult.ok;
   }
   const severity = summarizeSeverity(findings, installOk, testOk);
+  const stats = calculatePackageStats(info.pkg, findings);
+  const findingsSummary = calculateFindingsSummary(findings);
+  let packageUsage;
+  if (opts.detailed) {
+    try {
+      const usage = await analyzePackageUsageAsync(info.pkg, packagePath, true);
+      packageUsage = usage;
+    } catch (error) {}
+  }
   const summaryLines = [];
   summaryLines.push(`Lockfiles: ${info.lockfiles.bunLock || info.lockfiles.bunLockb ? "bun" : "non-bun or missing"}`);
   summaryLines.push(`Lifecycle scripts: ${Object.keys(info.scripts).some((k) => ["postinstall", "prepare", "preinstall", "install"].includes(k)) ? "present" : "none"}`);
   summaryLines.push(`Native addon risk: ${findings.some((f) => f.id === "deps.native_addons") ? "yes" : "no"}`);
   summaryLines.push(`bun install dry-run: ${install ? install.ok ? "ok" : "failed" : "skipped"}`);
   summaryLines.push(`bun test: ${test ? test.ok ? "ok" : "failed" : "skipped"}`);
-  return {
+  const result = {
     name,
     path: packagePath,
     severity,
@@ -895,8 +1077,14 @@ async function analyzeSinglePackage(packagePath, opts, config, pkgName) {
     dependencies: info.dependencies,
     devDependencies: info.devDependencies,
     optionalDependencies: info.optionalDependencies,
-    lockfiles: info.lockfiles
+    lockfiles: info.lockfiles,
+    stats,
+    findingsSummary
   };
+  if (packageUsage !== undefined) {
+    result.packageUsage = packageUsage;
+  }
+  return result;
 }
 function aggregateSeverity(packages, overallSeverity) {
   if (overallSeverity === "red")
@@ -915,7 +1103,7 @@ function aggregateSeverity(packages, overallSeverity) {
 }
 async function analyzeRepoOverall(opts) {
   const repoPath = normalizeRepoPath(opts.repoPath);
-  const packageJsonPath = path4.join(repoPath, "package.json");
+  const packageJsonPath = path5.join(repoPath, "package.json");
   const hasPkg = await fileExists(packageJsonPath);
   const config = await readConfig(repoPath);
   if (!hasPkg) {
@@ -1029,6 +1217,27 @@ var badge = (s) => {
     return "\uD83D\uDFE1 YELLOW";
   return "\uD83D\uDD34 RED";
 };
+var getReadinessMessage = (severity, hasRedFindings) => {
+  if (severity === "green" && !hasRedFindings) {
+    return "✅ Вітаю, ви готові до переходу на Bun!";
+  }
+  if (severity === "yellow") {
+    return "⚠️ Нажаль ви не готові до переходу на Bun, але це можливо з деякими змінами";
+  }
+  return "❌ Нажаль ви не готові до переходу на Bun через критичні проблеми";
+};
+var formatFindingsTable = (summary) => {
+  const lines = [];
+  lines.push(`## Findings Summary`);
+  lines.push(`| Status | Count |`);
+  lines.push(`|--------|-------|`);
+  lines.push(`| \uD83D\uDFE2 Green | ${summary.green} |`);
+  lines.push(`| \uD83D\uDFE1 Yellow | ${summary.yellow} |`);
+  lines.push(`| \uD83D\uDD34 Red | ${summary.red} |`);
+  lines.push(`| **Total** | **${summary.total}** |`);
+  return lines.join(`
+`);
+};
 var getTopFindings = (pkg, count = 3) => {
   const sorted = [...pkg.findings].sort((a, b) => {
     const severityOrder = { red: 0, yellow: 1, green: 2 };
@@ -1041,14 +1250,44 @@ var getTopFindings = (pkg, count = 3) => {
 };
 var packageRow = (pkg) => {
   const name = pkg.name;
-  const path5 = pkg.path.replace(/\\/g, "/");
+  const path6 = pkg.path.replace(/\\/g, "/");
   const severity = badge(pkg.severity);
   const topFindings = getTopFindings(pkg, 2).join(", ") || "No issues";
-  return `| ${name} | \`${path5}\` | ${severity} | ${topFindings} |`;
+  return `| ${name} | \`${path6}\` | ${severity} | ${topFindings} |`;
+};
+var formatPackageStats = (pkg) => {
+  const lines = [];
+  if (pkg.stats) {
+    lines.push(`- Total dependencies: ${pkg.stats.totalDependencies}`);
+    lines.push(`- Total devDependencies: ${pkg.stats.totalDevDependencies}`);
+    lines.push(`- Clean dependencies: ${pkg.stats.cleanDependencies}`);
+    lines.push(`- Clean devDependencies: ${pkg.stats.cleanDevDependencies}`);
+    lines.push(`- Dependencies with findings: ${pkg.stats.riskyDependencies}`);
+    lines.push(`- DevDependencies with findings: ${pkg.stats.riskyDevDependencies}`);
+  }
+  if (pkg.packageUsage) {
+    lines.push(`- **Total files analyzed**: ${pkg.packageUsage.analyzedFiles}`);
+    const usedPackages = Array.from(pkg.packageUsage.usageByPackage.values()).filter((u) => u.fileCount > 0).length;
+    lines.push(`- **Packages used in code**: ${usedPackages}`);
+  }
+  return lines;
 };
 function renderMarkdown(r) {
   const lines = [];
-  lines.push(`# bun-ready report`);
+  const bunVersion = process.version;
+  const hasRedFindings = r.findings.some((f) => f.severity === "red");
+  const readinessMessage = getReadinessMessage(r.severity, hasRedFindings);
+  lines.push(`# bun-ready report - Tested with Bun ${bunVersion}`);
+  lines.push(``);
+  lines.push(readinessMessage);
+  lines.push(``);
+  const rootFindingsSummary = {
+    green: r.findings.filter((f) => f.severity === "green").length,
+    yellow: r.findings.filter((f) => f.severity === "yellow").length,
+    red: r.findings.filter((f) => f.severity === "red").length,
+    total: r.findings.length
+  };
+  lines.push(formatFindingsTable(rootFindingsSummary));
   lines.push(``);
   lines.push(`**Overall:** ${badge(r.severity)}`);
   lines.push(``);
@@ -1127,6 +1366,13 @@ function renderMarkdown(r) {
     }
     lines.push(``);
   }
+  const rootPkgForStats = r.packages?.find((p) => p.path === r.repo.packageJsonPath);
+  if (rootPkgForStats && rootPkgForStats.stats) {
+    lines.push(`## Package Summary`);
+    for (const l of formatPackageStats(rootPkgForStats))
+      lines.push(l);
+    lines.push(``);
+  }
   lines.push(`## Root Findings`);
   if (r.findings.length === 0) {
     lines.push(`No findings for root package.`);
@@ -1157,6 +1403,12 @@ function renderMarkdown(r) {
       for (const l of pkg.summaryLines)
         lines.push(`- ${l}`);
       lines.push(``);
+      if (pkg.stats) {
+        lines.push(`**Package Summary**`);
+        for (const l of formatPackageStats(pkg))
+          lines.push(l);
+        lines.push(``);
+      }
       if (pkg.install) {
         lines.push(`**bun install (dry-run):** ${pkg.install.ok ? "ok" : "failed"}`);
         if (pkg.install.logs.length > 0 && pkg.install.logs.length < 10) {
@@ -1202,6 +1454,90 @@ function renderMarkdown(r) {
   return lines.join(`
 `);
 }
+var renderDetailedReport = (r) => {
+  const lines = [];
+  const bunVersion = process.version;
+  const hasRedFindings = r.findings.some((f) => f.severity === "red");
+  const readinessMessage = getReadinessMessage(r.severity, hasRedFindings);
+  lines.push(`# bun-ready detailed report - Tested with Bun ${bunVersion}`);
+  lines.push(``);
+  lines.push(readinessMessage);
+  lines.push(``);
+  const rootFindingsSummary = {
+    green: r.findings.filter((f) => f.severity === "green").length,
+    yellow: r.findings.filter((f) => f.severity === "yellow").length,
+    red: r.findings.filter((f) => f.severity === "red").length,
+    total: r.findings.length
+  };
+  lines.push(formatFindingsTable(rootFindingsSummary));
+  lines.push(``);
+  lines.push(`**Overall:** ${badge(r.severity)}`);
+  lines.push(``);
+  lines.push(`## Detailed Package Usage`);
+  lines.push(``);
+  let hasUsageInfo = false;
+  if (r.packages && r.packages.length > 0) {
+    const sortedPackages = stableSort(r.packages, (p) => p.name);
+    for (const pkg of sortedPackages) {
+      if (!pkg.packageUsage)
+        continue;
+      hasUsageInfo = true;
+      lines.push(`### ${pkg.name}`);
+      lines.push(``);
+      lines.push(`**Total files analyzed:** ${pkg.packageUsage.analyzedFiles}`);
+      lines.push(`**Total packages:** ${pkg.packageUsage.totalPackages}`);
+      lines.push(``);
+      const sortedUsage = Array.from(pkg.packageUsage.usageByPackage.values()).filter((u) => u.fileCount > 0).sort((a, b) => b.fileCount - a.fileCount);
+      if (sortedUsage.length === 0) {
+        lines.push(`No package usage detected in source files.`);
+        lines.push(``);
+        continue;
+      }
+      for (const usage of sortedUsage) {
+        const depVersion = pkg.dependencies[usage.packageName] || pkg.devDependencies[usage.packageName] || "";
+        const versionStr = depVersion ? `@${depVersion}` : "";
+        lines.push(`#### ${usage.packageName}${versionStr} (${usage.fileCount} file${usage.fileCount !== 1 ? "s" : ""})`);
+        lines.push(``);
+        if (usage.filePaths.length > 0) {
+          for (const filePath of usage.filePaths) {
+            lines.push(`- ${filePath}`);
+          }
+        } else {
+          lines.push(`- No file paths collected`);
+        }
+        lines.push(``);
+      }
+    }
+  }
+  if (!hasUsageInfo) {
+    lines.push(`No package usage information available. Run with --detailed flag to enable usage analysis.`);
+    lines.push(``);
+  }
+  lines.push(`---`);
+  lines.push(``);
+  lines.push(`## Root Findings`);
+  if (r.findings.length === 0) {
+    lines.push(`No findings for root package.`);
+  } else {
+    const findings = stableSort(r.findings, (f) => `${f.severity}:${f.id}`);
+    for (const f of findings) {
+      lines.push(`### ${f.title} (${badge(f.severity)})`);
+      lines.push(``);
+      for (const d of f.details)
+        lines.push(`- ${d}`);
+      if (f.hints.length > 0) {
+        lines.push(``);
+        lines.push(`**Hints:**`);
+        for (const h of f.hints)
+          lines.push(`- ${h}`);
+      }
+      lines.push(``);
+    }
+  }
+  lines.push(``);
+  return lines.join(`
+`);
+};
 
 // src/report_json.ts
 function renderJson(r) {
@@ -1214,7 +1550,7 @@ var usage = () => {
     "bun-ready",
     "",
     "Usage:",
-    "  bun-ready scan <path> [--format md|json] [--out <file>] [--no-install] [--no-test] [--verbose] [--scope root|packages|all] [--fail-on green|yellow|red]",
+    "  bun-ready scan <path> [--format md|json] [--out <file>] [--no-install] [--no-test] [--verbose] [--detailed] [--scope root|packages|all] [--fail-on green|yellow|red]",
     "",
     "Options:",
     "  --format md|json       Output format (default: md)",
@@ -1222,6 +1558,7 @@ var usage = () => {
     "  --no-install           Skip bun install --dry-run",
     "  --no-test             Skip bun test",
     "  --verbose              Show detailed output",
+    "  --detailed            Show detailed package usage report with file paths",
     "  --scope root|packages|all  Scan scope for monorepos (default: all)",
     "  --fail-on green|yellow|red  Fail policy (default: red)",
     "",
@@ -1246,6 +1583,7 @@ var parseArgs = (argv) => {
         runInstall: true,
         runTest: true,
         verbose: false,
+        detailed: false,
         scope: "all"
       }
     };
@@ -1256,6 +1594,7 @@ var parseArgs = (argv) => {
   let runInstall = true;
   let runTest = true;
   let verbose = false;
+  let detailed = false;
   let scope = "all";
   let failOn;
   for (let i = 2;i < args.length; i++) {
@@ -1284,6 +1623,10 @@ var parseArgs = (argv) => {
       verbose = true;
       continue;
     }
+    if (a === "--detailed") {
+      detailed = true;
+      continue;
+    }
     if (a === "--scope") {
       const v = args[i + 1] ?? "";
       if (v === "root" || v === "packages" || v === "all")
@@ -1306,6 +1649,7 @@ var parseArgs = (argv) => {
     runInstall,
     runTest,
     verbose,
+    detailed,
     scope
   };
   if (failOn !== undefined) {
@@ -1347,7 +1691,14 @@ var main = async () => {
 `);
     process.exit(1);
   }
-  const config = await mergeConfigWithOpts(null, opts);
+  const configOpts = {};
+  if (opts.failOn !== undefined) {
+    configOpts.failOn = opts.failOn;
+  }
+  if (opts.detailed !== undefined) {
+    configOpts.detailed = opts.detailed;
+  }
+  const config = await mergeConfigWithOpts(null, configOpts);
   const scanOpts = {
     repoPath: opts.repoPath,
     format: opts.format,
@@ -1376,10 +1727,10 @@ ${skipWarnings.map((w) => `  - ${w}`).join(`
 `);
     }
   }
-  const out = opts.format === "json" ? renderJson(res) : renderMarkdown(res);
-  const target = opts.outFile ?? (opts.format === "json" ? "bun-ready.json" : "bun-ready.md");
-  const resolved = path5.resolve(process.cwd(), target);
-  await fs3.writeFile(resolved, out, "utf8");
+  const out = opts.format === "json" ? renderJson(res) : opts.detailed ? renderDetailedReport(res) : renderMarkdown(res);
+  const target = opts.outFile ?? (opts.format === "json" ? "bun-ready.json" : opts.detailed ? "bun-ready-detailed.md" : "bun-ready.md");
+  const resolved = path6.resolve(process.cwd(), target);
+  await fs4.writeFile(resolved, out, "utf8");
   process.stdout.write(`Wrote ${opts.format.toUpperCase()} report to ${resolved}
 `);
   process.exit(exitCode(res.severity, config?.failOn || opts.failOn));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bun-ready",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "CLI that estimates how painful migrating a Node.js repo to Bun might be. Generates a green/yellow/red Markdown report with reasons.",
   "author": "Pas7 Studio",
   "license": "Apache-2.0",