repoScanner 0.3.0b11.dev0

repoScanner is a lightweight repository analysis tool for developers.

• Quickly understand your codebase structure, dependencies, and metrics with a single command.
• Built for developers with the intent of saving time and peace-of-mind

What It Does

• Directory Analysis: Scan total files, lines of code, average file size, and directory structure.
• Dependency Detection: Extract Python imports and C/C++ includes for each file.
• Language Breakdown: Group files by recognized language or extension.
• Summary and Raw Reporting: Choose a compact summary or detailed file-by-file dependency output.
• JSON Export: Generate a machine-readable report for every scan invocation.
• Native File Utilities: Optional vendor/libcvault support accelerates directory scanning, file sorting, search, byte totals, and line counts.
• Transparent Fallback: When the native helper is unavailable, repoScanner uses Python's os.walk and standard-library utilities.

Current Version

The current development version is 0.3.0b10.dev26, generated from the repository's Git history. The package metadata declares the release line as 0.3.0b10 with a development suffix.

Features

Reporting Modes

• Stats mode (default): High-level repository summary.
• Raw mode (--raw or --dev): Detailed, file-by-file dependency output.
• Nerd mode (--nerd): Alias for stats mode.

Key Metrics

• Total files, bytes, and lines of code.
• Average file size and average lines per file.
• Largest files by line count and by byte size.
• Dependency totals, most-dependent file, and average dependencies per file.
• Language distribution by extension.
• Directory counts, extension counts, and maximum path depth.

Runtime Dependencies

• The normal Python runtime uses only the Python Standard Library.
• The optional native helper is bundled as the vendor/libcvault submodule.
• repoScan/scanner/libcvault_wrapper.py loads the helper once per root path and caches the scan result.
• The native helper is not required for the core scan, summary, raw, or JSON-report commands.
• Building the helper requires a C++ compiler, Python development headers, and pybind11.

Benchmarks

These numbers are obtained by testing the commands using hyperfine on my own repository called velocache.

Modes using libcvault

Direct Python vs. Shell Wrapper(reposcan)

Requirements

• Python 3.12+ (tested on Ubuntu 24.04 LTS)

  The code uses only Python standard libraries and should be compatible with Python 3.10+, but has been officially tested on Python 3.12.

Quick Install

Install directly from PyPI for end users:

pip install repoScanner

Run:

reposcan <path> [--stats|--raw|--dev|--nerd|--sort|--max|--search <filename>|--lc <filename>|--tbytes|--help|--bench]

The scan and utility commands use the same argument parser. Options may appear before or after the path. The --bench command runs the bundled benchmark suite instead of scanning a repository.

reposcan <path> --stats
reposcan <path> --raw
reposcan <path> --dev                 # alias for --raw
reposcan <path> --nerd                # alias for --stats
reposcan <path> --sort                # files sorted by byte size
reposcan <path> --max                 # largest file and its byte size
reposcan <path> --search <filename>   # matching file name and its byte size
reposcan <path> --lc <filename>       # line count for a file
reposcan <path> --tbytes              # total bytes for the scanned tree
reposcan <path> --help                # show CLI help

Every normal scan or utility invocation also writes output/report.json. The benchmark command does not write this report. The native libcvault implementation sorts files by byte size in ascending order, while the Python fallback currently sorts them in descending order.

Build Instructions

1. Setup

• Clone the repository

  git clone https://github.com/tecnolgd/repoScanner.git
  

• Navigate to the directory

  cd repoScanner
  

• Optional: Fetch bundled native helper(libcvault)

  git submodule update --init --recursive vendor/libcvault
  

  • git submodule init registers the submodule in your local repo configuration.
  • git submodule update --init also clones and checks out the correct commit for the submodule.

The repository may contain a prebuilt binary such as libcvault.cpython-312-x86_64-linux-gnu.so. Distribution packages should prefer wheels for the target platforms rather than committing platform-specific .so files.

2. Tool Execution/Run

The easiest way to use repoScanner is with the provided shell script wrapper:

./reposcan <path> [--stats|--raw|--dev|--nerd|--sort|--max|--search <filename>|--lc <filename>|--tbytes|--help|--bench]

Quick start:

./reposcan .                       # stats mode
./reposcan /path/to/repo --raw     # detailed developer output
./reposcan /path/to/repo --bench   # benchmark harness
./reposcan /path/to/repo --sort    # files sorted by byte size, largest first

3. Output

• Terminal output is printed according to the selected mode.
• A JSON report is always written to output/report.json for normal scans and utility commands.
• The JSON report contains the UTC generation timestamp and the normalized metrics returned by generate_metrics.
• The output directory is created automatically when needed.

Supported Languages

Detects and maps 40+ extensions to human-readable names, including:

• Systems: C, C++, Rust, Go, Zig, Swift
• Web: HTML, CSS, JavaScript, TypeScript, PHP
• Data: JSON, YAML, TOML, SQL, XML
• Scripting: Python, Ruby, Lua, Shell, PowerShell and many more. (Unrecognized extensions fall back to their raw string format).

Documentation

• Architecture
• Usage
• Testing
• Roadmap

Contributing

Contributors

A huge thanks to the developers contributing to repoScanner.

• @Ghraven
• @AzarAI-TOP
• @Benjamin Ayiovh
• @faizan-7890

License

MIT