@darrenjcoxon/vibeoptimise 1.0.0

package/README.md

@@ -0,0 +1,122 @@
+# 🚀 VibeOptimise
+
+**The ultimate codebase optimisation scanner for AI-assisted development.**
+
+Scan your codebase for dead code, duplication, circular dependencies, bundle bloat, inefficient queries, and more — then get an AI-actionable `OPTIMISE.md` for Claude Code, Cursor, or any AI agent to fix everything.
+
+> **By the creator of [Vibeguard](https://www.npmjs.com/package/@darrenjcoxon/vibeguard)** — the security scanner for vibe coders.
+
+## Quick Start
+
+```bash
+npx @darrenjcoxon/vibeoptimise
+```
+
+That's it. Run it from the root of any JS/TS project.
+
+## What It Scans
+
+VibeOptimise runs **10 parallel scanners** that cover every dimension of codebase efficiency:
+
+| # | Scanner | What It Finds | Tool |
+|---|---------|---------------|------|
+| 1 | **Knip** | Unused files, exports, dependencies, types | [knip](https://knip.dev) |
+| 2 | **JSCPD** | Copy/pasted code blocks across the codebase | [jscpd](https://jscpd.dev) |
+| 3 | **Madge** | Circular dependencies & orphaned modules | [madge](https://github.com/pahen/madge) |
+| 4 | **Depcheck** | Unused & missing npm packages | [depcheck](https://github.com/depcheck/depcheck) |
+| 5 | **BundlePhobia** | Heavy deps with lighter alternatives | [bundlephobia](https://bundlephobia.com) |
+| 6 | **ESLint Perf** | Import cycles, barrel file bloat, unused imports | [eslint](https://eslint.org) |
+| 7 | **Source Map Explorer** | Bundle composition analysis | [source-map-explorer](https://github.com/danvk/source-map-explorer) |
+| 8 | **Regex Safety** | ReDoS-vulnerable patterns & catastrophic backtracking | Built-in |
+| 9 | **CSS Efficiency** | Unused CSS, duplicate selectors, !important overuse | Built-in |
+| 10 | **Query Efficiency** | N+1 patterns, unbounded queries, overfetching | Built-in |
+
+## Output: OPTIMISE.md
+
+The report is structured for AI agents to work through systematically:
+
+```markdown
+# OPTIMISE.md — Codebase Optimisation Report
+
+## 🔴 Critical — Immediate Performance Impact
+- Circular dependencies causing bundle bloat
+- ReDoS-vulnerable regex patterns
+- N+1 query patterns
+
+## 🟠 High — Significant Optimisation Opportunities
+- Unused dependencies (12 packages, ~45MB savings)
+- Unbounded database queries
+
+## 🟡 Medium — Recommended Improvements
+- Duplicated code blocks (with file pairs + line ranges)
+- Heavy deps with lighter alternatives
+
+## 🔵 Low — Nice to Have
+- Unused exports, console.log statements
+- CSS shorthand opportunities
+```
+
+## Usage
+
+```bash
+# Scan current directory
+npx @darrenjcoxon/vibeoptimise
+
+# Scan a specific project
+npx @darrenjcoxon/vibeoptimise /path/to/project
+
+# Quiet mode — just generate the report
+npx @darrenjcoxon/vibeoptimise --quiet
+
+# JSON output (for CI/CD integration)
+npx @darrenjcoxon/vibeoptimise --json
+
+# Include test files in analysis
+npx @darrenjcoxon/vibeoptimise --include-tests
+
+# Exclude specific patterns
+npx @darrenjcoxon/vibeoptimise --exclude "legacy/**" "vendor/**"
+```
+
+## AI Agent Workflow
+
+1. Run `npx @darrenjcoxon/vibeoptimise`
+2. Feed `OPTIMISE.md` to your AI agent
+3. Tell it: *"Read OPTIMISE.md and implement all fixes, starting from Critical"*
+4. Re-run VibeOptimise to verify improvements
+
+Works with **Claude Code**, **Cursor**, **GitHub Copilot**, **Windsurf**, and any AI coding assistant.
+
+## CI/CD Integration
+
+VibeOptimise exits with code 1 when critical or high findings exist — perfect for CI quality gates:
+
+```yaml
+# GitHub Actions
+- name: Check codebase optimisation
+  run: npx @darrenjcoxon/vibeoptimise --quiet
+```
+
+## ORM Support
+
+The Query Efficiency scanner understands:
+- **Supabase** — `.from()` without `.select()` or `.limit()`
+- **Prisma** — Unbounded `findMany()`, deeply nested includes
+- **Drizzle** — Queries without `.limit()`
+- **Mongoose** — `find({})` without limit, missing `.lean()`
+- **Raw SQL** — `SELECT *`, missing `LIMIT`
+
+## Companion Tool: Vibeguard
+
+Use VibeOptimise alongside [Vibeguard](https://www.npmjs.com/package/@darrenjcoxon/vibeguard) for complete coverage:
+
+```bash
+npx @darrenjcoxon/vibeguard      # Security scanning → FIXES.md
+npx @darrenjcoxon/vibeoptimise   # Optimisation scanning → OPTIMISE.md
+```
+
+## License
+
+MIT — Free for everyone. Built for the vibe coding community. 🤙
+
+**Made by [Darren Coxon](https://github.com/darrenjcoxon)**

package/dist/cli.d.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+/**
+ * VibeOptimise CLI
+ *
+ * Usage:
+ *   npx @darrenjcoxon/vibeoptimise          # Scan current directory
+ *   npx @darrenjcoxon/vibeoptimise /path    # Scan specific directory
+ *   npx @darrenjcoxon/vibeoptimise --help   # Show help
+ */
+export {};

package/dist/cli.js

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+/**
+ * VibeOptimise CLI
+ *
+ * Usage:
+ *   npx @darrenjcoxon/vibeoptimise          # Scan current directory
+ *   npx @darrenjcoxon/vibeoptimise /path    # Scan specific directory
+ *   npx @darrenjcoxon/vibeoptimise --help   # Show help
+ */
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { resolve } from 'path';
+import { existsSync } from 'fs';
+import { Orchestrator } from './orchestrator.js';
+import { Reporter } from './reporter.js';
+const program = new Command();
+program
+    .name('vibeoptimise')
+    .description('🚀 The ultimate codebase optimisation scanner — find dead code, duplication, circular deps, bundle bloat & more')
+    .version('1.0.0')
+    .argument('[directory]', 'Directory to scan (default: current directory)', '.')
+    .option('-q, --quiet', 'Minimal output — just generate OPTIMISE.md')
+    .option('-v, --verbose', 'Show detailed scanner output')
+    .option('--include-tests', 'Include test files in analysis')
+    .option('--include-css', 'Force CSS scanning even if no CSS files detected')
+    .option('--include-bundle', 'Force bundle analysis (requires build output)')
+    .option('--json', 'Output results as JSON instead of OPTIMISE.md')
+    .option('--no-report', 'Skip generating OPTIMISE.md file')
+    .option('-e, --exclude <patterns...>', 'Additional glob patterns to exclude')
+    .action(async (directory, opts) => {
+    try {
+        const targetDir = resolve(directory);
+        if (!existsSync(targetDir)) {
+            console.error(chalk.red(`\n  ✖ Directory not found: ${targetDir}\n`));
+            process.exit(1);
+        }
+        const options = {
+            targetDir,
+            quiet: opts.quiet || false,
+            verbose: opts.verbose || false,
+            includeTests: opts.includeTests || false,
+            includeCss: opts.includeCss || false,
+            includeBundle: opts.includeBundle || false,
+            exclude: opts.exclude || [],
+        };
+        // Run the orchestrator
+        const orchestrator = new Orchestrator();
+        const report = await orchestrator.run(options);
+        // Output results
+        if (opts.json) {
+            console.log(JSON.stringify(report, null, 2));
+        }
+        else if (opts.report !== false) {
+            const reporter = new Reporter();
+            const outputPath = reporter.generateOptimiseMd(report, targetDir);
+            console.log('');
+            console.log(chalk.green.bold(`  📄 OPTIMISE.md generated → ${outputPath}`));
+            console.log('');
+            console.log(chalk.cyan('  Next steps:'));
+            console.log(chalk.gray('  1. Feed OPTIMISE.md to your AI agent (Claude Code, Cursor, etc.)'));
+            console.log(chalk.gray('  2. Ask it to "Read OPTIMISE.md and implement all fixes"'));
+            console.log(chalk.gray('  3. Re-run vibeoptimise to verify the improvements'));
+            console.log('');
+        }
+        // Exit with error code if critical or high findings exist
+        const hasBlocking = report.summary.critical > 0 || report.summary.high > 0;
+        if (hasBlocking && !opts.quiet) {
+            console.log(chalk.yellow('  ⚠ Exiting with code 1 due to high/critical findings'));
+            console.log(chalk.gray('  Use this in CI to block merges with optimisation debt'));
+            console.log('');
+        }
+        process.exit(hasBlocking ? 1 : 0);
+    }
+    catch (err) {
+        console.error(chalk.red(`\n  ✖ Fatal error: ${err.message}\n`));
+        if (opts.verbose)
+            console.error(err.stack);
+        process.exit(2);
+    }
+});
+program.parse();

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * VibeOptimise — The Ultimate Codebase Optimisation Scanner
+ *
+ * 10 parallel scanners that find every inefficiency in your codebase
+ * and generate OPTIMISE.md for AI agents to fix everything.
+ *
+ * @module @darrenjcoxon/vibeoptimise
+ */
+export { Orchestrator } from './orchestrator.js';
+export { Reporter } from './reporter.js';
+export { getAllScanners } from './scanners/index.js';
+export * from './types.js';
+export { KnipScanner, JscpdScanner, MadgeScanner, DepcheckScanner, BundlePhobiaScanner, EslintPerfScanner, SourceMapExplorerScanner, RegexSafetyScanner, CssEfficiencyScanner, QueryEfficiencyScanner, } from './scanners/index.js';

package/dist/index.js

@@ -0,0 +1,14 @@
+/**
+ * VibeOptimise — The Ultimate Codebase Optimisation Scanner
+ *
+ * 10 parallel scanners that find every inefficiency in your codebase
+ * and generate OPTIMISE.md for AI agents to fix everything.
+ *
+ * @module @darrenjcoxon/vibeoptimise
+ */
+export { Orchestrator } from './orchestrator.js';
+export { Reporter } from './reporter.js';
+export { getAllScanners } from './scanners/index.js';
+export * from './types.js';
+// Export individual scanners for selective use
+export { KnipScanner, JscpdScanner, MadgeScanner, DepcheckScanner, BundlePhobiaScanner, EslintPerfScanner, SourceMapExplorerScanner, RegexSafetyScanner, CssEfficiencyScanner, QueryEfficiencyScanner, } from './scanners/index.js';

package/dist/orchestrator.d.ts

@@ -0,0 +1,16 @@
+/**
+ * VibeOptimise Orchestrator
+ *
+ * Manages parallel execution of all 10 scanners, aggregates results,
+ * and produces the final OptimiseReport.
+ */
+import { Scanner, ScanOptions, OptimiseReport } from './types.js';
+export declare class Orchestrator {
+    private scanners;
+    constructor(scanners?: Scanner[]);
+    run(options: ScanOptions): Promise<OptimiseReport>;
+    private deduplicateFindings;
+    private buildReport;
+    private calculateSavings;
+    private printSummary;
+}

package/dist/orchestrator.js

@@ -0,0 +1,201 @@
+/**
+ * VibeOptimise Orchestrator
+ *
+ * Manages parallel execution of all 10 scanners, aggregates results,
+ * and produces the final OptimiseReport.
+ */
+import chalk from 'chalk';
+import ora from 'ora';
+import { SEVERITY_WEIGHTS } from './types.js';
+import { getAllScanners } from './scanners/index.js';
+export class Orchestrator {
+    scanners;
+    constructor(scanners) {
+        this.scanners = scanners || getAllScanners();
+    }
+    async run(options) {
+        const start = Date.now();
+        const results = [];
+        if (!options.quiet) {
+            console.log('');
+            console.log(chalk.cyan.bold('  🚀 VibeOptimise — Codebase Optimisation Scanner'));
+            console.log(chalk.gray(`  Scanning: ${options.targetDir}`));
+            console.log('');
+        }
+        // Phase 1: Check availability
+        const spinner = ora({ text: 'Checking scanner availability...', color: 'cyan' }).start();
+        const availability = [];
+        for (const scanner of this.scanners) {
+            const available = await scanner.isAvailable();
+            availability.push({ scanner, available });
+        }
+        spinner.stop();
+        if (!options.quiet) {
+            for (const { scanner, available } of availability) {
+                const icon = available ? chalk.green('✔') : chalk.yellow('○');
+                const status = available ? '' : chalk.gray(' (skipped)');
+                console.log(`   ${icon} ${scanner.name}${status}`);
+            }
+            console.log('');
+        }
+        // Phase 2: Run available scanners in parallel
+        const availableScanners = availability
+            .filter(a => a.available)
+            .map(a => a.scanner);
+        if (availableScanners.length === 0) {
+            console.log(chalk.red('  ✖ No scanners available. Install dependencies and try again.'));
+            return this.buildReport(options, results, Date.now() - start, availability);
+        }
+        const scanSpinner = ora({
+            text: `Running ${availableScanners.length} scanners in parallel...`,
+            color: 'cyan',
+        }).start();
+        const scanPromises = availableScanners.map(async (scanner) => {
+            try {
+                const result = await scanner.scan(options.targetDir, options);
+                return result;
+            }
+            catch (err) {
+                return {
+                    scanner: scanner.name,
+                    findings: [],
+                    summary: `Error: ${err.message}`,
+                    duration: 0,
+                    error: err.message,
+                };
+            }
+        });
+        const scanResults = await Promise.allSettled(scanPromises);
+        for (const result of scanResults) {
+            if (result.status === 'fulfilled') {
+                results.push(result.value);
+            }
+            else {
+                results.push({
+                    scanner: 'Unknown',
+                    findings: [],
+                    summary: `Failed: ${result.reason}`,
+                    duration: 0,
+                    error: String(result.reason),
+                });
+            }
+        }
+        scanSpinner.stop();
+        // Phase 3: Deduplicate findings across scanners
+        const deduped = this.deduplicateFindings(results);
+        // Phase 4: Sort findings by severity
+        for (const result of deduped) {
+            result.findings.sort((a, b) => {
+                const weightDiff = SEVERITY_WEIGHTS[b.severity] - SEVERITY_WEIGHTS[a.severity];
+                if (weightDiff !== 0)
+                    return weightDiff;
+                return (a.file || '').localeCompare(b.file || '');
+            });
+        }
+        const report = this.buildReport(options, deduped, Date.now() - start, availability);
+        // Phase 5: Print summary
+        if (!options.quiet) {
+            this.printSummary(report);
+        }
+        return report;
+    }
+    deduplicateFindings(results) {
+        // Knip and Depcheck both find unused dependencies — deduplicate
+        const seenDeps = new Set();
+        for (const result of results) {
+            if (result.scanner === 'Knip') {
+                for (const finding of result.findings) {
+                    if (finding.title.startsWith('Unused dependency:') || finding.title.startsWith('Unused devDependency:')) {
+                        const depName = finding.title.split(': ')[1];
+                        seenDeps.add(depName);
+                    }
+                }
+            }
+        }
+        // Remove Depcheck findings that Knip already caught
+        for (const result of results) {
+            if (result.scanner === 'Depcheck') {
+                result.findings = result.findings.filter(finding => {
+                    if (finding.title.startsWith('Unused dependency:') || finding.title.startsWith('Unused devDependency:')) {
+                        const depName = finding.title.split(': ')[1];
+                        return !seenDeps.has(depName);
+                    }
+                    return true;
+                });
+            }
+        }
+        return results;
+    }
+    buildReport(options, results, duration, availability) {
+        const allFindings = results.flatMap(r => r.findings);
+        const summary = {
+            totalFindings: allFindings.length,
+            critical: allFindings.filter(f => f.severity === 'critical').length,
+            high: allFindings.filter(f => f.severity === 'high').length,
+            medium: allFindings.filter(f => f.severity === 'medium').length,
+            low: allFindings.filter(f => f.severity === 'low').length,
+            info: allFindings.filter(f => f.severity === 'info').length,
+            estimatedSavings: this.calculateSavings(allFindings),
+            scannersPassed: availability.filter(a => a.available).length,
+            scannersSkipped: availability.filter(a => !a.available).length,
+            scannersFailed: results.filter(r => r.error).length,
+        };
+        return {
+            version: '1.0.0',
+            timestamp: new Date().toISOString(),
+            targetDir: options.targetDir,
+            duration,
+            scanners: results,
+            summary,
+        };
+    }
+    calculateSavings(findings) {
+        const parts = [];
+        const unusedFiles = findings.filter(f => f.title?.startsWith('Unused file')).length;
+        if (unusedFiles > 0)
+            parts.push(`${unusedFiles} dead files`);
+        const unusedDeps = findings.filter(f => f.title?.startsWith('Unused dependency')).length;
+        if (unusedDeps > 0)
+            parts.push(`${unusedDeps} unused packages`);
+        const duplication = findings.filter(f => f.category === 'duplication').length;
+        if (duplication > 0)
+            parts.push(`${duplication} duplication blocks`);
+        const circular = findings.filter(f => f.title?.startsWith('Circular')).length;
+        if (circular > 0)
+            parts.push(`${circular} circular deps`);
+        return parts.length > 0 ? parts.join(', ') : 'Codebase is clean';
+    }
+    printSummary(report) {
+        const { summary } = report;
+        console.log('');
+        console.log(chalk.cyan.bold('  ━━━ Results ━━━'));
+        console.log('');
+        if (summary.totalFindings === 0) {
+            console.log(chalk.green.bold('  ✅ Codebase is optimised — no issues found!'));
+        }
+        else {
+            if (summary.critical > 0)
+                console.log(`   🔴 Critical: ${chalk.red.bold(String(summary.critical))}`);
+            if (summary.high > 0)
+                console.log(`   🟠 High:     ${chalk.yellow.bold(String(summary.high))}`);
+            if (summary.medium > 0)
+                console.log(`   🟡 Medium:   ${chalk.yellow(String(summary.medium))}`);
+            if (summary.low > 0)
+                console.log(`   🔵 Low:      ${chalk.blue(String(summary.low))}`);
+            if (summary.info > 0)
+                console.log(`   ⚪ Info:     ${chalk.gray(String(summary.info))}`);
+            console.log(`   ─────────────`);
+            console.log(`   Total:      ${chalk.bold(String(summary.totalFindings))}`);
+        }
+        console.log('');
+        console.log(chalk.gray(`  Scanned in ${(report.duration / 1000).toFixed(1)}s with ${summary.scannersPassed}/10 scanners`));
+        // Per-scanner breakdown
+        console.log('');
+        for (const scanner of report.scanners) {
+            const count = scanner.findings.length;
+            const icon = scanner.error ? chalk.red('✖') : count === 0 ? chalk.green('✔') : chalk.yellow('⚠');
+            console.log(`   ${icon} ${scanner.scanner}: ${scanner.summary}`);
+        }
+        console.log('');
+    }
+}

package/dist/reporter.d.ts

@@ -0,0 +1,15 @@
+/**
+ * VibeOptimise Reporter
+ *
+ * Generates OPTIMISE.md — an AI-actionable report that Claude Code,
+ * Cursor, or any AI agent can use to automatically fix optimisation issues.
+ *
+ * Follows the Vibeguard FIXES.md pattern with clear severity separation.
+ */
+import { OptimiseReport } from './types.js';
+export declare class Reporter {
+    generateOptimiseMd(report: OptimiseReport, outputDir: string): string;
+    private buildMarkdown;
+    private renderFinding;
+    private formatCategoryName;
+}

package/dist/reporter.js

@@ -0,0 +1,140 @@
+/**
+ * VibeOptimise Reporter
+ *
+ * Generates OPTIMISE.md — an AI-actionable report that Claude Code,
+ * Cursor, or any AI agent can use to automatically fix optimisation issues.
+ *
+ * Follows the Vibeguard FIXES.md pattern with clear severity separation.
+ */
+import { writeFileSync } from 'fs';
+import { join } from 'path';
+import { CATEGORY_ICONS } from './types.js';
+export class Reporter {
+    generateOptimiseMd(report, outputDir) {
+        const outputPath = join(outputDir, 'OPTIMISE.md');
+        const content = this.buildMarkdown(report);
+        writeFileSync(outputPath, content, 'utf-8');
+        return outputPath;
+    }
+    buildMarkdown(report) {
+        const { summary, scanners } = report;
+        const allFindings = scanners.flatMap(s => s.findings);
+        const lines = [];
+        // Header
+        lines.push('# OPTIMISE.md — Codebase Optimisation Report');
+        lines.push('');
+        lines.push(`> Generated by [VibeOptimise](https://www.npmjs.com/package/@darrenjcoxon/vibeoptimise) v${report.version}`);
+        lines.push(`> Scanned: ${report.targetDir}`);
+        lines.push(`> Date: ${new Date(report.timestamp).toLocaleString()}`);
+        lines.push(`> Duration: ${(report.duration / 1000).toFixed(1)}s`);
+        lines.push('');
+        // AI Agent Instructions
+        lines.push('## Instructions for AI Agents');
+        lines.push('');
+        lines.push('This file contains actionable optimisation findings for your codebase.');
+        lines.push('Work through each section in order of priority (Critical → High → Medium → Low).');
+        lines.push('Each finding includes the file, line number, and specific fix to apply.');
+        lines.push('After making changes, re-run `npx @darrenjcoxon/vibeoptimise` to verify fixes.');
+        lines.push('');
+        // Summary
+        lines.push('## Summary');
+        lines.push('');
+        lines.push(`| Severity | Count |`);
+        lines.push(`|----------|-------|`);
+        if (summary.critical > 0)
+            lines.push(`| 🔴 Critical | ${summary.critical} |`);
+        if (summary.high > 0)
+            lines.push(`| 🟠 High | ${summary.high} |`);
+        if (summary.medium > 0)
+            lines.push(`| 🟡 Medium | ${summary.medium} |`);
+        if (summary.low > 0)
+            lines.push(`| 🔵 Low | ${summary.low} |`);
+        if (summary.info > 0)
+            lines.push(`| ⚪ Info | ${summary.info} |`);
+        lines.push(`| **Total** | **${summary.totalFindings}** |`);
+        lines.push('');
+        if (summary.totalFindings === 0) {
+            lines.push('✅ **Codebase is optimised — no issues found!**');
+            lines.push('');
+            return lines.join('\n');
+        }
+        // Group findings by severity, then by category
+        const severityOrder = ['critical', 'high', 'medium', 'low', 'info'];
+        const severityLabels = {
+            critical: '🔴 Critical — Immediate Performance Impact',
+            high: '🟠 High — Significant Optimisation Opportunities',
+            medium: '🟡 Medium — Recommended Improvements',
+            low: '🔵 Low — Nice to Have',
+            info: '⚪ Info — Informational',
+        };
+        for (const severity of severityOrder) {
+            const findings = allFindings.filter(f => f.severity === severity);
+            if (findings.length === 0)
+                continue;
+            lines.push(`---`);
+            lines.push('');
+            lines.push(`## ${severityLabels[severity]}`);
+            lines.push('');
+            // Group by category within severity
+            const categories = [...new Set(findings.map(f => f.category))];
+            for (const category of categories) {
+                const catFindings = findings.filter(f => f.category === category);
+                const icon = CATEGORY_ICONS[category] || '📋';
+                lines.push(`### ${icon} ${this.formatCategoryName(category)} (${catFindings.length})`);
+                lines.push('');
+                for (const finding of catFindings) {
+                    this.renderFinding(finding, lines);
+                }
+            }
+        }
+        // Scanner Results Summary
+        lines.push('---');
+        lines.push('');
+        lines.push('## Scanner Results');
+        lines.push('');
+        lines.push('| Scanner | Findings | Duration | Status |');
+        lines.push('|---------|----------|----------|--------|');
+        for (const scanner of scanners) {
+            const status = scanner.error ? '❌ Error' : scanner.findings.length === 0 ? '✅ Clean' : `⚠️ ${scanner.findings.length} issues`;
+            const duration = `${(scanner.duration / 1000).toFixed(1)}s`;
+            lines.push(`| ${scanner.scanner} | ${scanner.findings.length} | ${duration} | ${status} |`);
+        }
+        lines.push('');
+        // Footer
+        lines.push('---');
+        lines.push('');
+        lines.push('*Generated by VibeOptimise — The ultimate codebase optimisation scanner*');
+        lines.push('*Run `npx @darrenjcoxon/vibeoptimise` to re-scan after fixes*');
+        lines.push('');
+        return lines.join('\n');
+    }
+    renderFinding(finding, lines) {
+        const location = finding.file
+            ? finding.line
+                ? `\`${finding.file}:${finding.line}\``
+                : `\`${finding.file}\``
+            : '';
+        lines.push(`#### ${finding.title}`);
+        lines.push('');
+        if (location)
+            lines.push(`**Location:** ${location}`);
+        if (finding.relatedFiles && finding.relatedFiles.length > 0) {
+            lines.push(`**Related files:** ${finding.relatedFiles.map(f => `\`${f}\``).join(', ')}`);
+        }
+        lines.push('');
+        lines.push(`**Issue:** ${finding.description}`);
+        lines.push('');
+        lines.push(`**Fix:** ${finding.suggestion}`);
+        lines.push('');
+        if (finding.estimatedImpact) {
+            lines.push(`**Impact:** ${finding.estimatedImpact}`);
+            lines.push('');
+        }
+    }
+    formatCategoryName(category) {
+        return category
+            .split('-')
+            .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+            .join(' ');
+    }
+}

package/dist/scanners/bundlephobia.d.ts

@@ -0,0 +1,19 @@
+/**
+ * BundlePhobia Scanner — Dependency Weight Analysis
+ *
+ * Checks every dependency's bundle size impact and suggests lighter alternatives.
+ * Uses the BundlePhobia API to get minified + gzipped sizes.
+ *
+ * Tool: bundlephobia API (https://bundlephobia.com/api)
+ * Output: JSON API responses
+ */
+import { Scanner, ScannerResult, ScanOptions } from '../types.js';
+export declare class BundlePhobiaScanner implements Scanner {
+    name: string;
+    description: string;
+    category: "bundle-size";
+    isAvailable(): Promise<boolean>;
+    scan(targetDir: string, options: ScanOptions): Promise<ScannerResult>;
+    private checkBundleSizes;
+    private findDuplicatePackages;
+}