📂 dir-analysis-tool

A powerful, feature-rich command-line tool for comprehensive directory analysis

✨ Features

• 📊 Comprehensive Directory Analysis - Get detailed insights into directory structure, file counts, and sizes
• 🗂️ Smart File Classification - Automatically categorize files by type (images, videos, documents, audio, code, archives)
• 🚨 Large File Detection - Identify files consuming significant disk space
• 🔄 Duplicate File Detection - Find and analyze duplicate files to reclaim storage
• 📈 Interactive Mode - Explore directories with an intuitive interactive interface
• 🌳 Tree View Visualization - Display directory structure in a beautiful tree format
• 📊 HTML Reports - Generate rich HTML reports with charts and visualizations
• 📄 Multiple Export Formats - Export results to JSON, CSV, or HTML
• ⚡ Real-time Progress Tracking - Monitor analysis progress with visual progress bars
• 👀 Watch Mode - Monitor directory changes in real-time
• 🎯 Advanced Filtering - Filter files by size, date, patterns, and more
• ⚙️ Configurable - Customize analysis with configuration files
• 🚀 High Performance - Optimized for speed and memory efficiency
• 🌍 Cross-platform - Works on Windows, macOS, and Linux

🚀 Installation

Global Installation (Recommended)

npm install -g dir-analysis-tool

Local Installation

npm install dir-analysis-tool

📖 Usage

Basic Usage

Analyze current directory:

dir-analysis-tool

Analyze specific directory:

dir-analysis-tool /path/to/directory

Command Line Options

dir-analysis-tool [directory] [options]

Core Options

• -p, --path <path> - Target directory to analyze (default: current directory)
• -r, --recursive - Recursively analyze nested directories (default: true)
• --no-recursive - Disable recursive analysis
• -j, --json - Output results in JSON format
• -t, --types - Show file type classification summary (default: true)
• --no-types - Hide file type classification

Advanced Analysis

• -l, --large-files [threshold] - Detect large files (default: 100MB)
• -d, --duplicates - Enable duplicate file detection
• --empty-files - Detect and show empty files
• --top-n <number> - Show top N largest files (default: 10)
• --tree - Display results in tree view format

Filtering Options

• -e, --exclude <patterns...> - Exclude file patterns or directories
• --max-depth <depth> - Maximum directory depth to scan
• --min-size <size> - Filter files by minimum size (bytes)
• --max-size <size> - Filter files by maximum size (bytes)
• --date-from <date> - Filter files modified after this date (YYYY-MM-DD)
• --date-to <date> - Filter files modified before this date (YYYY-MM-DD)

Export Options

• --csv [filename] - Export results to CSV file
• --csv-large [filename] - Export large files to CSV
• --csv-duplicates [filename] - Export duplicates to CSV
• --html [filename] - Generate HTML report with charts

Interactive & Monitoring

• -i, --interactive - Start interactive mode
• -w, --watch - Watch mode - monitor directory changes
• --progress - Show progress bar during analysis (default: true)
• --no-progress - Disable progress bar

Configuration

• -c, --config [path] - Load configuration from file

🎯 Examples

Basic Analysis

# Analyze current directory with file type classification
dir-analysis-tool

# Analyze specific directory
dir-analysis-tool ~/Documents

# Get JSON output
dir-analysis-tool --json ~/Downloads

Advanced Analysis

# Find large files over 50MB and duplicates
dir-analysis-tool --large-files 52428800 --duplicates ~/Pictures

# Show tree view with top 20 largest files
dir-analysis-tool --tree --top-n 20 /var/log

# Analyze with filters
dir-analysis-tool --min-size 1048576 --max-depth 3 --exclude "*.tmp" "cache*"

Export and Reports

# Generate HTML report
dir-analysis-tool --html report.html ~/Projects

# Export to CSV files
dir-analysis-tool --csv analysis.csv --csv-large large-files.csv --duplicates

# Export duplicates analysis
dir-analysis-tool --duplicates --csv-duplicates duplicates.csv

Interactive Mode

# Start interactive explorer
dir-analysis-tool --interactive

# Watch directory for changes
dir-analysis-tool --watch ~/Downloads

📋 Interactive Mode

Launch interactive mode for a guided analysis experience:

dir-analysis-tool -i

Interactive mode features:

• 🔍 Guided Analysis - Step-by-step directory analysis
• 📁 Directory Navigation - Easy directory switching
• 📊 Multiple Views - Switch between different result views
• 💾 Export Options - Export results in various formats
• ⚙️ Advanced Settings - Configure analysis options
• 🔄 Directory Comparison - Compare multiple directories

⚙️ Configuration

Create a configuration file to customize default behavior:

.dir-analyzer.json or dir-analyzer.config.json

{
  "excludePatterns": ["node_modules", ".git", "*.tmp"],
  "largeSizeThreshold": 104857600,
  "enableDuplicateDetection": false,
  "enableProgressBar": true,
  "outputFormat": "table",
  "maxDepth": -1,
  "topN": 10,
  "showEmptyFiles": false
}

The tool automatically searches for configuration files in the current directory and parent directories.

📊 Output Formats

Console Output

Rich, colorized console output with:

• 📂 Directory summary
• 📊 File type breakdown
• 🚨 Large files list
• 🔄 Duplicate file groups
• 🌳 Tree view (optional)

JSON Output

{
  "path": "/Users/example/Documents",
  "totalSizeBytes": 1048576000,
  "totalSizeMB": 1000,
  "folders": 150,
  "files": 2500,
  "types": {
    "images": 450,
    "documents": 800,
    "code": 300,
    "other": 950
  },
  "largeFiles": [...],
  "duplicateGroups": [...]
}

HTML Reports

Generate beautiful HTML reports with:

• 📊 Interactive charts
• 📈 Size distribution graphs
• 🗂️ File type breakdowns
• 📋 Detailed file listings
• 🎨 Modern, responsive design

CSV Export

Export data to CSV for further analysis in spreadsheet applications.

🔧 API Usage

Use programmatically in your Node.js applications:

import { DirectoryAnalyzer } from 'dir-analysis-tool';

const analyzer = new DirectoryAnalyzer();

const result = await analyzer.analyze({
  path: '/path/to/analyze',
  recursive: true,
  excludePatterns: ['node_modules'],
  largeSizeThreshold: 100 * 1024 * 1024, // 100MB
  enableDuplicateDetection: true,
  topN: 10
});

console.log(result);

🎯 Use Cases

• 🧹 Disk Cleanup - Identify large files and duplicates consuming disk space
• 📊 Project Analysis - Analyze project structure and file distributions
• 🔍 Storage Audit - Understand storage usage patterns
• 📈 Capacity Planning - Monitor directory growth over time
• 🚀 Performance Optimization - Identify bottlenecks in file systems
• 📋 Documentation - Generate reports for system documentation
• 🔄 Backup Planning - Identify important files and directories

🛠️ Requirements

• Node.js >= 18.0.0
• npm or pnpm or yarn
• Operating System: Windows, macOS, or Linux