Repo Doctor

Repo Doctor is an offline repository integrity and structure checker written in Rust. It performs static, rule-based checks on project directories and generates a detailed PDF report summarizing code hygiene, language-specific structural integrity, and overall project health without relying on external compilers, linters, or network calls.

Features

• Language-Agnostic Hygiene Checks: Verifies required files (README, LICENSE, .gitignore, CI configuration), detects empty directories, flags unusually large files (>5 MB), checks for filename case collisions, and detects missing trailing newlines or trailing whitespace.
• C++ Checks: Validates brace {} and parenthesis () balance, checks for #pragma once or include guards in header files, detects unmatched .cpp files, and checks for build files (CMakeLists.txt or Makefile).
• Rust Checks: Verifies Cargo.toml and Cargo.lock presence, checks brace balance, and detects dangling mod declarations in root modules against disk.
• Java Checks: Matches package declarations against folder paths, verifies public class/interface/enum names against file names, checks brace balance, and verifies build file presence (pom.xml or build.gradle).
• Web Checks (HTML, CSS, JS, TS, JSX, TSX): Performs void-element aware HTML tag balance checks, resolves relative link/asset targets, checks CSS brace balance, and verifies JS/TS module import resolution on disk.
• Offline PDF Generation: Generates structured PDF reports complete with score breakdowns, summary tables, and severity charts using built-in Helvetica fonts.

Installation

Prerequisites

• Rust (2021 edition) and cargo installed.

Build from Source

git clone https://github.com/irongopher75/CheckYourRepo.git
cd CheckYourRepo
cargo build --release

The compiled binary will be available at ./target/release/repo-doctor.

Usage

Scanning a Repository

To scan a directory and generate a PDF report:

repo-doctor scan [PATH] [OPTIONS]

Options

• [PATH]: Path to the repository or project directory to scan (defaults to current directory .).
• -o, --output <FILE>: Path for the generated PDF report (default: repo-doctor-report.pdf).
• -e, --exclude <GLOB>: Additional glob patterns to exclude from scanning (can be specified multiple times).

Examples

Scan current directory and output to default report location:

repo-doctor scan

Scan a specific project directory with custom output path and exclusions:

repo-doctor scan /path/to/project --output project-health.pdf --exclude "docs/*" --exclude "*.tmp"

Health Scoring System

Overall repository score and category scores are calculated out of 100 based on detected issue penalties:

Score = max(0, 100 - (0.5 * Info + 2.0 * Warning + 5.0 * Error))

• Info (0.5 point penalty): Informational observations such as missing Cargo.lock for binary crates or unpaired C++ source files.
• Warning (2.0 point penalty): Non-critical structural deficiencies such as missing header guards or trailing whitespace.
• Error (5.0 point penalty): Critical issues such as mismatched Java package declarations, broken HTML links, or unbalanced syntax braces.

Project Structure

repo-doctor/
├── Cargo.toml
├── src/
│   ├── main.rs              # CLI interface and program orchestration
│   ├── scanner.rs           # Directory walker respecting gitignore & exclude patterns
│   ├── issue.rs             # Issue, Severity, and Category definitions
│   ├── checks/
│   │   ├── mod.rs           # Check execution entry point
│   │   ├── hygiene.rs       # General repository hygiene rules
│   │   ├── cpp.rs           # C++ static integrity rules
│   │   ├── rust_lang.rs     # Rust module & cargo checks
│   │   ├── java.rs          # Java package & class name checks
│   │   └── web.rs           # Web syntax and import resolution checks
│   └── report/
│       ├── mod.rs           # Score aggregation and category summaries
│       └── pdf.rs           # PDF document generator using printpdf
└── tests/
    └── checks_test.rs       # Integrated test suite

License

This project is licensed under the MIT License - see the LICENSE file for details.