Codebase Viewer

Codebase Viewer is a cross-platform desktop application—written entirely in Rust—that lets you scan, explore, and document large codebases with millisecond-level responsiveness. The UI is built with egui via eframe, giving you a native-feeling window on Windows, macOS, Linux, and the web (web support experimental).

✨ Key Features

Capability	Details
Blazing-fast scans	Parallel directory walking powered by the ignore crate’s WalkBuilder, which respects .gitignore, global Git excludes, hidden-file masks, and uses multiple threads.
Live tree UI	Immediate-mode GUI rendered by egui/eframe; every file appears as soon as it’s discovered, even while the scan is still running. File icons based on type.
Selective exports	Keep the full directory context but choose exactly which files’ contents go into HTML, Markdown, or plain-text reports—ideal for LLM ingestion or documentation.
Syntax-highlighted preview	On-the-fly colouring courtesy of syntect, using Sublime-Text grammars. Supports common text file types.
Image preview	Preview common image formats (PNG, JPG, GIF, BMP, ICO, TIFF) directly within the app.
SVG preview	Preview Scalable Vector Graphics (.svg) files using the resvg crate.
Native dialogs & theme awareness	File/dir pickers via rfd and automatic light/dark detection via dark-light.
Cross-thread messaging	Non-blocking updates sent through crossbeam-channel for MPMC performance, keeping the UI responsive during scans and report generation.
Human-readable sizes	Byte counts formatted with humansize.
Config persistence	Settings stored in the OS-native config directory obtained with dirs-next.
Selection persistence	Save and load the checked state of files/directories to a JSON file.

🚀 Quick Start

# 1. Clone and build in release mode
git clone https://github.com/noahbclarkson/codebase_viewer.git
cd codebase_viewer
cargo run --release

# 2. Open a project
File ▸ Open Directory …   # or use the recent-projects list

# 3. Explore & select
– Navigate the tree using mouse or keyboard
– Use the search bar (Ctrl+F) to filter
– Tick files/dirs you want included in reports/exports

# 4. Generate documentation
File ▸ Generate Report …
Choose Markdown / HTML / Text, select options, and hit **Generate**

System requirements: Any modern OS with Rust 1.77+ installed. The app utilizes multiple threads for scanning via Rayon and ignore.

🔧 Configuration

A JSON config (config.json) is auto-saved to the standard user configuration directory:

• Linux: $HOME/.config/codebase_viewer/
• Windows: %APPDATA%\codebase_viewer\
• macOS: ~/Library/Application Support/codebase_viewer/

Key fields:

Key	Purpose	Default
theme	UI theme: "light", "dark", or "system"	"system"
show_hidden_files	Whether the scanner should include hidden files/directories	false
auto_expand_limit	Auto-expand dirs whose total file count ≤ this value after scan	100
max_file_size_preview	Size threshold (bytes) before preview/export refuses to read a file	1048576 (1MiB)
export_format	Default format for reports: "markdown", "html", "text"	"markdown"
export_include_stats	Default setting for including stats in reports	true
export_include_contents	Default setting for including file contents in reports	true
recent_projects	List of recently opened directory paths (up to 10)	[]

🏗️ Architecture Overview

src/
├── app.rs        # Top-level eframe::App state and logic orchestrator
├── config.rs     # Handles loading/saving AppConfig (serde + dirs-next)
├── external.rs   # Utility for opening paths in external apps (open crate)
├── fs/           # File system operations
│   ├── file_info.rs # Metadata struct for files/dirs
│   ├── scanner.rs   # Background directory scanner (ignore crate)
│   └── stats.rs     # Statistics collection during scan (ScanStats)
├── model.rs      # Core data structures (FileNode, FileId, Check state)
├── preview.rs    # Content preview generation (syntect, image crate)
├── report/       # Report generation logic
│   ├── generator.rs # Core report data collection and dispatch
│   ├── html.rs      # HTML report formatter
│   ├── markdown.rs  # Markdown report formatter
│   └── text.rs      # Plain text report formatter
├── selection.rs  # Saving/loading tree selection state to JSON
├── task.rs       # Enums for background task messages (ScanMessage, TaskMessage)
└── ui/           # egui UI modules
    ├── dialogs.rs     # Preferences, Report Options, About, Shortcuts windows
    ├── menu_bar.rs    # Top menu bar drawing logic
    ├── preview_panel.rs # Right panel for file content preview
    ├── status_bar.rs  # Bottom status bar drawing logic
    └── tree_panel.rs  # Left panel with file tree view and search

• Long-running tasks (directory scanning, report generation) happen in background threads (std::thread, rayon).
• UI updates are driven by messages received via crossbeam-channel, ensuring the GUI remains responsive (target 60 fps).
• Directory scanning respects .gitignore and other standard ignore files via the ignore crate.
• Reports include the full directory structure for context, followed by the selected subtree and optionally file contents.

🖼️ Screenshots

---

---

🛠️ Development

# Format code
cargo fmt --all

# Lint code (strict)
cargo clippy --all-targets --all-features -- -D warnings

# Run tests
cargo test --all-features

# Run in debug mode (with hot-reload where applicable)
cargo run

# Run optimized release build
cargo run --release

Performance tips

• Always build with --release for optimal performance, especially for the scanner.
• On very large repositories, uncheck "Include file contents" in the report dialog if you only need the structure and stats.
• The max_file_size_preview setting in Preferences can prevent attempts to load huge files into the preview panel.

Limitations / Known Issues

• Previewing PDF files is not currently supported.
• Web assembly (wasm) builds may work but are not actively tested or supported for v0.1.0.

🤝 Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository.
2. Create a new branch (git checkout -b feature/my-new-feature or bugfix/issue-number).
3. Make your changes. Ensure code is formatted (cargo fmt) and passes lints (cargo clippy -- -D warnings).
4. Add tests for new functionality if applicable.
5. Commit your changes with descriptive messages.
6. Push to your branch (git push origin feature/my-new-feature).
7. Open a Pull Request against the main branch of the original repository. Explain the purpose and scope of your changes.

Please also refer to CONTRIBUTING.md for more detailed guidelines.

📜 License

This project is dual-licensed under either the MIT License or the Apache License, Version 2.0, at your option. See the LICENSE-MIT and LICENSE-APACHE files for details.

---

This project demonstrates building a responsive, native-feeling desktop application using the Rust GUI ecosystem, primarily egui/eframe.