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 | Purpose | Default | | ------------------------- | ------------------------------------------------------------------- | ---------------- | | theme | UI theme: "light", "dark", or "system" | "system" | | showhiddenfiles | Whether the scanner should include hidden files/directories | false | | autoexpandlimit | Auto-expand dirs whose total file count ≤ this value after scan | 100 | | maxfilesize_preview | Size threshold (bytes) before preview/export refuses to read a file | 1048576 (1MiB) | | export_format | Default format for reports: "markdown", "html", "text" | "markdown" | | exportincludestats | Default setting for including stats in reports | true | | exportincludecontents | 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 maxfilesize_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:

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

📜 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.