File_Stats_Rs

A lightweight and fast command-line file system scanner written in Rust. It recursively traverses a directory, collects statistics about files and folders, and can output results either as a human-readable summary or as structured JSON.

---

Features

• 🔍 Recursive directory traversal using walkdir
• 📊 File statistics: total file count, directory count, and cumulative size
• 🗂️ Extension breakdown: ranked list of the most common file extensions, by count or by size
• 🔎 Search filter: include only files whose names match a given substring
• 🚫 Ignore list: skip specific directories or file names entirely
• 📏 Depth limit: restrict traversal to a maximum directory depth via --max-depth
• 📦 Sort by size: rank extensions by cumulative disk usage via --sort-size
• 🖨️ JSON output: machine-readable output via --json
• 🎨 Colored terminal output using colored

---

Installation

Prerequisites

• Rust (stable, edition 2021 or later)

Build from source

git clone https://github.com/your-username/File_Stats_Rs.git
cd File_Stats_Rs
cargo build --release

The compiled binary will be available at ./target/release/cli.

---

Usage

cli [OPTIONS] <PATH>

Arguments

Argument	Description
<PATH>	Root path to scan (file or directory)

Options

Option	Short	Description
--search <PATTERN>	-s	Only include files whose name contains <PATTERN>
--ignore <NAME>	-i	Skip entries named <NAME> (repeatable)
--max-depth <N>		Limit traversal to <N> levels deep (must be at least 1)
--sort-size [N]		Show top N extensions ranked by cumulative size in MB (defaults to 5 if omitted)
--json		Output results as pretty-printed JSON instead of plain text
--help	-h	Print help information
--version	-V	Print version information

---

Examples

Scan a directory with a summary:

cli ./my_project

Search for files containing "config" in their name:

cli ./my_project --search config

Ignore multiple directories:

cli ./my_project --ignore node_modules --ignore .git --ignore target

Limit traversal depth to 2 levels:

cli ./my_project --max-depth 2

Show top 5 extensions by cumulative size:

cli ./my_project --sort-size

Show top 10 extensions by cumulative size:

cli ./my_project --sort-size 10

Output results as JSON:

cli ./my_project --json

Combine options:

cli ./my_project --search test --ignore target --max-depth 3 --json

---

Output

Human-readable (default, sorted by count)

Scanned directory: ./my_project
Scanned directory: ./my_project/src
...

--- Summary ---
Total files: 42
Total directories: 8
Total size: 1.23 MB

Top 5 extensions by COUNT :
  .rs: 30
  .toml: 4
  .md: 3
  .json: 3
  .lock: 2

Human-readable (--sort-size)

--- Summary ---
Total files: 42
Total directories: 8
Total size: 1.23 MB

Top 5 extensions by SIZE :
  .rs: 0.98 MB
  .json: 0.15 MB
  .md: 0.06 MB
  .toml: 0.02 MB
  .lock: 0.01 MB

JSON (--json)

{
  "total_files": 42,
  "total_dirs": 8,
  "total_size": 1234567,
  "extension_counts": {
    "rs": [30, 980000],
    "toml": [4, 20000],
    "md": [3, 60000],
    "json": [3, 150000],
    "lock": [2, 10000]
  }
}

Note: total_size is expressed in bytes in JSON output. Each entry in extension_counts is a [count, total_bytes] tuple.

---

Project Structure

File_Stats_Rs/
├── src/
│   ├── main.rs       # Entry point: argument parsing, directory traversal, output
│   └── lib.rs        # Cli and FileStats definitions
├── tests/
│   └── tests.rs      # Integration tests
├── Cargo.toml
└── README.md

---

Dependencies

Crate	Purpose
clap	Command-line argument parsing
walkdir	Recursive directory traversal
serde	Serialization framework
serde_json	JSON serialization
colored	Terminal color output
tempfile	Temporary files/directories for testing

---

Running Tests

cargo test

The test suite covers:

• File stat accumulation (counts, sizes, extensions)
• Case-insensitive extension normalization (.RS → rs)
• Extension-less file handling (e.g., LICENSE)
• Directory counter independence from file counters
• Top-N extension sorting and ranking by count
• Top-N extension sorting and ranking by cumulative size
• --max-depth traversal limiting at various depths
• Mixed file and directory scenarios

---

License

This project is licensed under the MIT License.