# Codebase Asset Optimizer

> Professional CLI tool for optimizing and managing assets in codebases. Never increase file sizes again!

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Private Repository](https://img.shields.io/badge/Repository-Private-red.svg)](https://github.com/vladgrecu/codebase-asset-optimizer)

## 🎯 Features

- **Smart Size Detection**: Only optimizes assets if it reduces file size
- **Unused Asset Detection**: Find and safely remove unused images/videos
- **Automatic Reference Updates**: Updates all code references when optimizing assets
- **Multiple Optimization Strategies**: WebP for images, efficient codecs for videos
- **Backup & Restore**: Safe operations with automatic backup creation
- **Cross-Platform**: Works on Windows, macOS, and Linux
- **CLI & Programmatic API**: Use as a command-line tool or integrate into your build process

## 🚀 Quick Start

### Installation

```bash
# Install as dev dependency (recommended)
npm install --save-dev codebase-asset-optimizer

# Or install globally for system-wide usage
npm install -g codebase-asset-optimizer

# Or clone the private repository (access required)
git clone https://github.com/vladgrecu/codebase-asset-optimizer.git
cd codebase-asset-optimizer
npm install && npm run build
```

### Why Dev Dependency?

This tool is designed to be a **development dependency** because:

- 🔧 **Build-time optimization**: Runs during development and build processes, not at runtime
- 📦 **Smaller production bundles**: Keeps your production `node_modules` lean
- 🚀 **CI/CD integration**: Perfect for build pipelines and automated optimization
- 💡 **Development workflow**: Used for asset analysis and optimization during development

```bash
# ✅ Recommended - Install as dev dependency
npm install --save-dev codebase-asset-optimizer

# ❌ Not recommended - Runtime dependency
npm install codebase-asset-optimizer
```

### Setup npm Scripts

After installation, you can add convenient npm scripts to your `package.json` in several ways:

#### Option 1: Interactive Setup (Recommended)
```bash
npx codebase-asset-optimizer setup
```

#### Option 2: Automatic (during fresh install)
```bash
npm install --save-dev codebase-asset-optimizer
# 🎉 Thank you for installing Codebase Asset Optimizer!
# 📦 Found package.json: package.json
# 💡 For future projects, install as dev dependency:
#    npm install --save-dev codebase-asset-optimizer
# 🚀 Would you like to add convenient npm scripts to your package.json?
#    npm run optimize:assets      # Optimize all assets
#    npm run optimize:assets:dry  # Preview optimizations (safe)
#    npm run audit:assets         # Analyze optimization opportunities
#    npm run clean:assets         # Remove unused assets
#    npm run assets:interactive   # Interactive optimization mode
```

#### Option 3: Manual Setup
If automatic setup doesn't work, manually add these scripts to your `package.json`:

```json
{
  "scripts": {
    "optimize:assets": "npx codebase-asset-optimizer optimize",
    "optimize:assets:dry": "npx codebase-asset-optimizer optimize --dry-run",
    "audit:assets": "npx codebase-asset-optimizer audit",
    "clean:assets": "npx codebase-asset-optimizer clean",
    "assets:interactive": "npx codebase-asset-optimizer interactive"
  }
}
```

After setup, you can use convenient npm scripts:

```bash
# Quick start - see what can be optimized
npm run audit:assets

# Preview optimizations (safe, no changes made)
npm run optimize:assets:dry

# Optimize all assets (only if size reduction achieved)
npm run optimize:assets

# Interactive mode with guided steps
npm run assets:interactive
```

### Manual Usage

```bash
# Use directly with npx (primary command)
npx codebase-asset-optimizer audit
npx codebase-asset-optimizer optimize
npx codebase-asset-optimizer clean

# Alternative short commands (for convenience)
npx asset-optimizer audit
npx optimize-assets

# Or if installed globally
codebase-asset-optimizer --help
```

### Basic Usage

```bash
# Audit your project for optimization opportunities
codebase-asset-optimizer audit

# Preview what would be optimized (dry run)
codebase-asset-optimizer optimize --dry-run

# Optimize all assets (only if size reduction is achieved)
codebase-asset-optimizer optimize

# Remove unused assets
codebase-asset-optimizer clean

# Interactive mode with guided options
codebase-asset-optimizer interactive
```

## 📊 What It Does

### Asset Optimization

- **Images**: Converts to WebP format with smart quality settings
- **Videos**: Re-encodes to WebM/MP4 with optimal compression
- **GIF Preservation**: GIF files are intentionally left unchanged to preserve animations
- **Size Verification**: Only keeps optimized versions if they're actually smaller
- **Reference Updates**: Automatically updates all imports/references in your codebase

### Unused Asset Detection

- **Smart Scanning**: Searches through all source files for asset references
- **Pattern Matching**: Finds direct imports, dynamic references, and path-based usage
- **Safe Removal**: Creates backups before removing any files

### Professional Features

- **Backup System**: Automatic backup creation with restore capabilities
- **Progress Reporting**: Real-time feedback with detailed statistics
- **Error Handling**: Robust error handling with helpful messages
- **Dry Run Mode**: Preview changes before applying them
- **npm Integration**: Automatic setup of convenient npm scripts during installation
- **Interactive Mode**: User-friendly guided optimization process

## 🛠️ CLI Commands

### `audit`

Analyze your project to find unused and optimizable assets.

```bash
codebase-asset-optimizer audit [options]

Options:
  -d, --dir <directory>     Project directory (default: current)
  -p, --public <directory>  Public/assets directory
  -s, --source <directory>  Source code directory
  -v, --verbose            Verbose output
```

### `optimize`

Optimize assets to efficient formats (only if size reduction is achieved).

```bash
codebase-asset-optimizer optimize [options]

Options:
  -d, --dir <directory>     Project directory (default: current)
  -p, --public <directory>  Public/assets directory
  -s, --source <directory>  Source code directory
  --no-backup              Skip creating backup
  -y, --yes                Skip confirmation prompts
  --dry-run                Show what would be optimized
  -v, --verbose            Verbose output
```

### `clean`

Remove unused assets safely.

```bash
codebase-asset-optimizer clean [options]

Options:
  -d, --dir <directory>     Project directory (default: current)
  -p, --public <directory>  Public/assets directory
  -s, --source <directory>  Source code directory
  --no-backup              Skip creating backup
  -y, --yes                Skip confirmation prompts
  --dry-run                Show what would be removed
  -v, --verbose            Verbose output
```

### `interactive`

Launch interactive mode with guided options.

```bash
codebase-asset-optimizer interactive [options]

Options:
  -d, --dir <directory>     Project directory (default: current)
  -p, --public <directory>  Public/assets directory
  -s, --source <directory>  Source code directory
```

## 📝 Programmatic API

Use the optimizer programmatically in your build scripts:

```typescript
import { AssetOptimizer, createDefaultConfig } from "codebase-asset-optimizer";

async function optimizeAssets() {
  // Create configuration
  const config = createDefaultConfig("/path/to/project");

  // Create optimizer instance
  const optimizer = new AssetOptimizer(config);

  // Run audit
  const results = await optimizer.audit();
  console.log(`Found ${results.optimizableAssets.length} optimizable assets`);

  // Optimize assets (with backup)
  const stats = await optimizer.optimizeAssets(true);
  console.log(
    `Optimized ${stats.optimized} assets, saved ${stats.sizeBefore - stats.sizeAfter} bytes`
  );

  // Remove unused assets
  if (results.unusedAssets.length > 0) {
    const cleanupResults = await optimizer.removeUnusedAssets(true);
    console.log(`Removed ${cleanupResults.removed} unused assets`);
  }
}

optimizeAssets().catch(console.error);
```

## ⚙️ Configuration

The tool automatically detects your project structure, but you can customize it:

```typescript
import { createDefaultConfig } from "codebase-asset-optimizer";

const config = createDefaultConfig("/path/to/project");

// Customize settings
config.optimization.images.quality = 90;
config.optimization.images.maxWidth = 1920;
config.optimization.videos.targetFormats = ["webm"];
config.largeFileThreshold = 1024 * 1024; // 1MB

// Image optimization settings
config.optimization.images = {
  targetFormat: "webp",
  quality: 85,
  maxWidth: 2048,
  maxHeight: 2048,
  onlyIfSmaller: true, // Critical: only optimize if it reduces size
};

// Video optimization settings
config.optimization.videos = {
  targetFormats: ["webm", "mp4"],
  quality: "medium",
  maxWidth: 1920,
  maxHeight: 1080,
  onlyIfSmaller: true, // Critical: only optimize if it reduces size
};
```

## 🔧 Requirements

- **Node.js**: 16.0.0 or higher
- **Sharp**: Automatically installed for image optimization
- **FFmpeg**: Required for video optimization (auto-detected or install manually)

### Installing FFmpeg

**macOS:**

```bash
brew install ffmpeg
```

**Ubuntu/Debian:**

```bash
sudo apt-get install ffmpeg
```

**Windows:**
Download from [https://ffmpeg.org/download.html](https://ffmpeg.org/download.html)

## 📊 Example Output

```
🔍 Starting Asset Audit

📁 Discovering assets...
   Found 156 image/video assets (22.1 MB)
🔎 Checking asset usage...
   Processed 156/156 assets
🎯 Identifying optimization opportunities...
   Found 134 assets that can be optimized
📊 Generating report...

📈 ASSET AUDIT RESULTS
==================================================
Total Assets: 156 (22.1 MB)

📊 BY TYPE:
Images: 149 total (145 used, 4 unused)
Videos: 7 total (7 used, 0 unused)

💾 USAGE:
Used: 152 (21.98 MB)
Unused: 4 (117.05 KB)

🎯 OPTIMIZATION:
Optimizable: 134 (20.85 MB)
  - Images → WebP: 134
  - Videos → efficient: 0

🚀 Starting optimization...
   🔄 Optimizing: playground-banner.png
     ✓ 1.54 MB → 39.83 KB (97% smaller)
   🔄 Optimizing: hero-image.jpg
     ✓ 856 KB → 312 KB (64% smaller)
   ...

✅ Optimization complete!
   Assets processed: 134
   Successfully optimized: 127
   Total savings: 8.2 MB (39% reduction)
   Duration: 23.4s
```

## 🧪 Testing & Development

### Test Project

A comprehensive test project is included for validation and development:

```bash
# Navigate to test project
cd test-project

# Run interactive optimization
npm run test:optimizer

# Reset to original state after testing
npm run reset

# View asset statistics
npm run stats
```

The test project includes:

- **67 assets** (65 images + 2 videos)
- **8 source files** with various reference patterns
- **Multiple frameworks** (HTML, CSS, React, Vue, Markdown)
- **Reset functionality** to restore original state

### Reset Functionality

After testing optimizations, easily reset the test project:

```bash
# Automatic reset (uses backup or git)
npm run reset

# Manual backup creation
npm run backup:create

# Check restoration status
npm run stats
```

The reset script automatically:

- Restores assets from the most recent backup
- Reverts all source code references to original extensions  
- Cleans up optimization artifacts and reports
- Verifies complete restoration

## 🏗️ Project Structure Support

The tool automatically detects common project structures:

- **Public directories**: `public`, `assets`, `static`, `dist/public`
- **Source directories**: `src`, `app`, `lib`, `source`
- **File types**: Images (PNG, JPG, WebP, SVG), Videos (MP4, WebM, MOV)

## 🛡️ Safety Features

- **Backup Creation**: Automatic backups before any destructive operations
- **Size Verification**: Never increases file sizes through optimization
- **Dry Run Mode**: Preview changes before applying them
- **Error Recovery**: Detailed error messages and graceful failure handling
- **Reference Integrity**: Automatically updates all code references

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## 📄 License

MIT © [Vlad Grecu](https://github.com/vladgrecu)

## 🆘 Support

- 📚 [Documentation](https://github.com/vladgrecu/codebase-asset-optimizer#readme)
- 🐛 [Issue Tracker](https://github.com/vladgrecu/codebase-asset-optimizer/issues)
- 💬 [Discussions](https://github.com/vladgrecu/codebase-asset-optimizer/discussions)

---

<p align="center">
  <strong>Made with ❤️ for developers who care about performance</strong>
</p>