mac-disk-scanner

A professional macOS disk space analyzer and cleanup tool built with Tauri, Rust, and React

A high-performance desktop application for macOS that helps you identify and manage space-consuming files and directories. Built with modern web technologies and native Rust performance.

✨ Key Features

🔍 Intelligent Disk Scanning

• Recursive Directory Analysis: Deep scan any directory to find large files and folders
• Real-time Progress Tracking: Live updates with estimated time remaining (ETA)
• Performance Optimized: Single-pass streaming traversal with bounded top-K retention and efficient metadata reuse
• Progressive Scan Status: Progress events show discovery and processing phases, and matching previews appear during the scan before final results are committed

⚡ Smart Filtering

• Size Threshold: Set minimum file size to filter out small items
• Result Limits: Control the number of results displayed
• Timeout Protection: Prevent long-running scans with configurable timeouts
• Depth Control: Automatic depth limiting for system protection

🛡️ Safety Features

• System Directory Protection: Automatically blocks deletion of critical macOS system directories (/system, /library, /usr, etc.)
• Confirmation Dialogs: All deletions require explicit user confirmation
• Path Validation: Backend validates all file paths before operations
• Error Handling: Comprehensive error reporting with user-friendly messages

💻 Modern UI/UX

• Clean Interface: Beautiful React + Tailwind CSS interface
• Fixed-Height Lists: Scrollable result tables with sticky headers
• Type Information: File types and modified dates displayed
• Action Controls: Quick delete buttons with visual feedback
• Clear Scan Stats: Separates total scanned size, matched item counts, and displayed result count

📐 Data Contract

The scan result contract uses explicit size fields across Rust and TypeScript:

• sizeLogical: logical file content size from metadata.len()
• sizeDisk: disk usage from metadata.blocks() * 512, falling back to logical size when block data is unavailable
• totalSizeLogical / totalSizeDisk: total bytes scanned for the requested root
• filesFound / directoriesFound: matched items before display truncation
• resultCount: number of items returned to the frontend for display

🛠️ Technology Stack

Frontend

• React 18 with TypeScript
• Vite for fast development and builds
• Tailwind CSS for styling
• Lucide React for icons

Backend

• Rust for native performance
• Tauri 2.0 for desktop framework
• Walkdir for directory traversal
• Lru for caching
• Tokio for async operations

Development

• pnpm for package management
• TypeScript for type safety
• ES Modules for modern JavaScript

📊 Performance Features

The scanner includes sophisticated performance optimizations:

1. Streaming Traversal: Processes each WalkDir entry once instead of buffering the full tree before sizing
2. Bounded File Retention: When limit is set, only the current top-K matching files are retained in memory
3. Efficient Metadata Reading: Single metadata read per file, avoiding duplicate calls
4. Incremental Directory Aggregation: Parent directory sizes are accumulated during traversal
5. Progress Logging: Debug logs and progress events track traversal and final result assembly
6. Performance Metrics: Detailed timing for metadata reads, aggregation, and sorting

🚀 Development

Setup

pnpm install

Dev Mode

pnpm tauri dev

Build

pnpm tauri build

📁 Project Structure

mac_disk/
├── src/                    # React frontend
│   ├── App.tsx            # Main application
│   ├── components/        # React components
│   │   ├── Scanner.tsx    # Scanning UI
│   │   ├── FileList.tsx   # Results display
│   │   └── ConfirmDialog.tsx # Delete confirmation
│   └── types.ts          # TypeScript definitions
├── src-tauri/             # Rust backend
│   ├── src/
│   │   ├── lib.rs        # Tauri setup
│   │   ├── commands.rs   # Command handlers
│   │   └── scanner.rs    # Core scanning logic
│   └── Cargo.toml        # Rust dependencies

🎯 Use Cases

• Disk Cleanup: Identify largest files taking up space
• System Maintenance: Monitor disk usage patterns
• Development: Find temporary files and build artifacts
• Backup Planning: Understand data distribution before backups
• Troubleshooting: Diagnose disk space issues

🔒 Security

• Path Validation: All paths are validated before file operations
• System Protection: Critical macOS directories are protected
• User Confirmation: Deletions require explicit approval
• Error Handling: Graceful failure with informative messages

💡 Future Enhancements

• Real-time progress percentage display
• Cancel functionality for long-running scans
• Incremental results display during scanning
• Caching mechanism for frequently accessed directories
• Export results to CSV/JSON
• File type statistics and charts
• Sorting and filtering capabilities

📝 License

MIT License - feel free to use and modify for your projects.

---

Built with ❤️ using Tauri, Rust, and React for macOS

This description provides a comprehensive overview highlighting the key features, technology stack, security considerations, and development aspects of the mac-disk-scanner project. It's suitable for use as a GitHub repository description, README file, or project documentation introduction.