DSA-Rustlings TUI

DSA-Rustlings is a terminal application for practicing data structures and algorithms in Rust. It combines a track browser, exercise stories, an inline code editor, a test runner, hints, solution viewing, and local progress tracking.

The current curriculum contains 19 tracks and 411 exercises. Exercise files are starter stubs: tests are expected to fail until the user implements the required functions.

Quick Start

git clone git@github.com:boniface/dsa-rustlings.git
cd dsa-rustlings
cargo run

For a release build:

cargo build --release
./target/release/dsa-rustlings

Current Features

• Track browser shown at launch
• Exercise browser within each track
• Story view for exercise context and completion criteria
• Inline Rust editor with basic syntax highlighting
• Test runner on F2
• Result panel with PASS and FAILED status labels
• Hints with F1
• Solution view with Ctrl+L
• Solution comparison with Ctrl+K
• Formatting with Ctrl+F
• Local progress, streaks, and achievements
• Reset menu for current exercise, current track, or all progress

Navigation

Track Browser

Up/Down  Select track
Enter    Open selected track
?        Help
q        Quit

Exercise Browser

Up/Down  Select exercise
Enter    Open selected exercise
Esc      Return to tracks
F2       Run tests for selected exercise
r        Reset menu
?        Help
q        Quit

Story View

Up/Down  Scroll story
PgUp     Scroll up by page
PgDn     Scroll down by page
Enter    Open code
F3       Toggle story/code
Esc      Return to exercises
?        Help

Code Editor

Fresh starter code:

After running tests with failures:

F3       Toggle story/code
Up/Down  Move cursor
Tab      Insert 4 spaces
Enter    Insert newline
Ctrl+S   Save code
Ctrl+F   Format code
Ctrl+K   Check against solution
Ctrl+L   View solution
F2       Run tests
F1       Show hint

Solution View

Esc      Return to code
Up/Down  Scroll solution
Ctrl+K   Check against solution

Exit Confirmation

Curriculum

Track	Exercises
Warm Up	3
Data Structures	35
Sorting Algorithms	35
Searching Algorithms	20
Graph Algorithms	30
Dynamic Programming	27
String Algorithms	25
Mathematics	82
Bit Manipulation	17
Backtracking	10
General & Greedy	16
Ciphers & Cryptography	25
Hashing & Checksums	8
Compression Algorithms	7
Computational Geometry	12
Conversions & Unit Transforms	25
Machine Learning	20
Big Integer & Financial Algorithms	13
Signal Analysis	1
Total	411

Most generated algorithm exercises are based on topics and reference implementations from TheAlgorithms/Rust. Reference implementations are kept in solution.rs; the editable exercise.rs files are stubs.

Exercise Layout

Each exercise directory normally contains:

exercise.rs   Editable starter file
original.rs   Reset source when available
solution.rs   Reference solution
story.rs      Exercise context, requirements, and completion criteria

The exercise runner compiles and tests the selected exercise.rs. A fresh exercise should compile, then fail its tests until the implementation is completed.

Development Commands

make help          # List make targets
make dev           # Run the application
make test          # Run tests
make fmt           # Format code
make check         # Format check, tests, and lint command
make coverage      # Run llvm-cov with the coverage gate

Manual equivalents:

cargo run
cargo test
cargo fmt --all
cargo clippy --all-targets

To check that all exercise test crates compile without running every failing starter test:

cargo test --manifest-path exercises/Cargo.toml --no-run

To run one exercise directly:

cargo test --manifest-path exercises/Cargo.toml --test 01_array_operations

Project Structure

dsa-rustlings/
|-- src/
|   |-- main.rs
|   |-- config/
|   |-- engine/
|   `-- tui/
|-- exercises/
|   |-- Cargo.toml
|   |-- manifest.yaml
|   `-- categories/
|-- tests/
|-- docs/
`-- scripts/

Adding or Updating Exercises

1. Add or update the track entry in exercises/manifest.yaml.
2. Add or update the track manifest under exercises/categories/<track>/manifest.yaml.
3. Add an exercise directory with exercise.rs, solution.rs, story.rs, and original.rs where applicable.
4. Ensure exercise.rs is a starter stub and initially fails its tests.
5. Run cargo test --manifest-path exercises/Cargo.toml --no-run.
6. Run cargo test.

Requirements

• Rust toolchain with edition 2024 support
• A terminal emulator with standard keyboard input support
• rustfmt for formatting

Documentation

• Quick Start
• Architecture
• Distribution
• Release Checklist

License

• Code and documentation: MIT License
• Exercise reference material: see exercises/THIRD_PARTY_NOTICES.md

Acknowledgments

• Rustlings
• Ratatui
• TheAlgorithms/Rust