Chapter 1: ruchy-cat

Welcome to the first practical chapter! We'll build ruchy-cat, a clone of the Unix cat command, using EXTREME TDD methodology. This chapter documents our actual development journey, including real bugs encountered, Stop The Line events, and the complete RED-GREEN-REFACTOR-PROPERTY-QUALIFY cycle.

Understanding cat

The cat (concatenate) command is one of the simplest yet most useful Unix tools:

# Display a single file
$ cat file.txt
Hello, World!

# Concatenate multiple files
$ cat file1.txt file2.txt
Contents of file1
Contents of file2

# Read from stdin (no arguments)
$ echo "test" | cat
test

Why Start with cat?

1. Simple core functionality - Read and print files
2. Perfect for TDD - Clear, testable behavior
3. Foundation for learning - Introduces file I/O, argument parsing
4. Real-world tool - Actually useful in daily work

RED: First Test

Following EXTREME TDD, we write our test FIRST, before any implementation.

Sprint 1, Task 1: Write Failing Test

Stop The Line Event #1: Before we could write tests, we encountered Ruchy Bug #30 - the ColonColon (::) operator wasn't supported. We stopped development, filed a detailed bug report, and waited. The Ruchy team fixed it in v3.80.0 within hours!

Lesson: Jidoka (Stop The Line) works. Quality first, always.

The First Test

examples/ruchy-cat/cat_test.ruchy:

@test("reads single file successfully")
fun test_read_single_file() {
    // Setup: Create test file
    let test_file = "test_cat_single.txt"
    let test_content = "Hello, Ruchy!"
    fs_write(test_file, test_content)

    // Exercise: Call read_file function
    let result = read_file(test_file)

    // Verify: Should read file contents
    assert_eq(result, test_content, "Should read file contents")

    // Cleanup
    fs_remove_file(test_file)
}

Stub Implementation (Makes it Compile)

// Stub - returns empty string
fun read_file(path) {
    ""
}

Run the Test

$ ruchy test cat_test.ruchy
❌ FAILED - Expected "Hello, Ruchy!" but got ""

✅ RED phase complete - We have a failing test!

GREEN: Minimal Implementation

Now we write the simplest code that makes the test pass.

Task 2: Implement read_file

fun read_file(path) {
    fs_read(path)
}

That's it! Three lines. Ruchy's built-in fs_read() does exactly what we need.

Run the Test Again

$ ruchy test cat_test.ruchy
✅ PASSED - 1/1 tests passing

✅ GREEN phase complete - Test passes with minimal code!

Commit

$ git add cat_test.ruchy
$ git commit -m "GREEN - Sprint 1 - Implement read_file"

REFACTOR: Clean Code

Now that tests are green, we can improve the code while keeping tests passing.

Task 7: Refactor and Expand

We added:

1. Comprehensive documentation
2. Separation of concerns - Split implementation from tests
3. Additional test cases - Special characters, multiple files, large files
4. CLI entry point - main() function for command-line use
5. Multi-file support - cat_files() function

Final Implementation

examples/ruchy-cat/cat.ruchy:

// ruchy-cat: Concatenate and print files
// Chapter 1 example from Ruchy CLI Tools Book

// Reads the contents of a file at the given path.
fun read_file(path) {
    fs_read(path)
}

// Concatenates and prints multiple files to stdout.
fun cat_files(files) {
    if files.len() == 0 {
        println("Reading from stdin not yet implemented")
    } else {
        for file in files {
            let contents = read_file(file)
            print(contents)
        }
    }
}

// Main entry point
fun main() {
    let args = env_args()
    let files = if args.len() > 1 {
        let file_list = []
        for i in range(1, args.len()) {
            file_list = file_list + [args[i]]
        }
        file_list
    } else {
        []
    }
    cat_files(files)
}

Expanded Test Suite

Added tests for:

• ✅ Newline preservation
• ✅ Empty files
• ✅ Special characters (tabs, quotes, Unicode)
• ✅ Multiple files
• ✅ Large files (100 lines)

Total: 6 tests, all passing

✅ REFACTOR phase complete - Clean code, all tests still green!

PROPERTY: Invariants

Property-based testing verifies invariants - things that should ALWAYS be true, regardless of input.

Task 10: Property Tests with 1000+ Iterations

We added 4 property tests with 1250+ total iterations:

@test("property idempotent reads")
fun property_idempotent() {
    let test_file = "test_property_idempotent.txt"
    let test_content = "Line 1\nLine 2\nSpecial: \t \"quoted\" →\n"
    fs_write(test_file, test_content)
    let first_read = read_file(test_file)

    // Property: Reading same file 1000 times should give same result
    for i in range(0, 1000) {
        let current_read = read_file(test_file)
        assert_eq(current_read, first_read,
                 "Read should be idempotent - iteration " + i.to_string())
    }

    fs_remove_file(test_file)
}

Invariants Tested

1. Idempotency: Reading same file multiple times gives identical results (1000 iterations)
2. Length Preservation: Content length matches exactly (100 sizes tested)
3. Content Preservation: Any valid content is preserved (100 patterns tested)
4. Size Handling: Files from 0 to 10KB handled correctly (50 sizes tested)

Total: 10 tests, 1250+ iterations, 100% passing

✅ PROPERTY phase complete - Invariants verified!

QUALIFY: 15 Tools

Task 11: Run all 15 Ruchy quality tools.

Stop The Line Event #2: During qualification, we discovered 6 bugs in Ruchy's tools. Following Jidoka, we stopped immediately and filed GitHub issues #31-#36.

Ruchy Team Response: Fixed 5 out of 6 bugs in < 1 day!

• v3.82.0: Fixed Bug #31 (CRITICAL fmt corruption)
• v3.83.0: Fixed Bugs #32-34, #36 (range, test attrs, lint, coverage)

Lesson: Stop The Line works. Quality collaboration builds better tools.

Original Results (v3.80.0)

PASSING (6/12):

• ✅ ruchy check - Syntax valid
• ✅ ruchy test - 10/10 tests passing
• ✅ ruchy ast - AST parsing works
• ✅ ruchy runtime --bigo - O(n²) detected
• ✅ ruchy transpile - Generates Rust
• ✅ ruchy coverage - Reports 100% (misleading)

FAILING (6/12):

• ❌ ruchy fmt - Corrupts files (Bug #31)
• ❌ ruchy compile - range() not transpiled (Bug #32)
• ❌ ruchy property-tests - Invalid attributes (Bug #33)
• ❌ ruchy lint - False positives (Bug #34)
• ❌ ruchy fuzz - Compilation failure (Bug #32)
• ❌ ruchy mutations - Below threshold

After Fixes (v3.83.0)

PASSING (11+/12):

• ✅ All previous passing tools
• ✅ ruchy fmt - Now safe! (Bug #31 fixed)
• ✅ ruchy compile - Works! (Bug #32 fixed)
• ✅ ruchy property-tests - Functional! (Bug #33 fixed)
• ✅ ruchy lint - Mostly fixed (Bug #34)
• ✅ ruchy coverage - Real metrics! (Bug #36 fixed)
• ✅ ruchy fuzz - Unblocked (Bug #32 fixed)

Our Code Quality: Excellent despite tool issues

• ✅ All tests pass
• ✅ Clean, documented code
• ✅ Zero SATD
• ✅ Follows EXTREME TDD

Key Learnings

Ruchy Syntax

• Tests: @test("description") + fun
• Built-ins: fs_read, fs_write, env_args, range
• No imports needed for stdlib

TDD Workflow

1. RED: Write failing test first
2. GREEN: Minimal implementation
3. REFACTOR: Clean code, add tests
4. PROPERTY: Test invariants (1000+ iterations)
5. QUALIFY: Run all tools
6. Commit: Each phase separately

Toyota Way

• Jidoka: Stopped twice for bugs
• Genchi Genbutsu: Investigated actual behavior
• Kaizen: Improved process from learnings
• Respect: Documented for future developers

Metrics

Summary

We successfully built ruchy-cat following EXTREME TDD:

✅ Complete cycle: RED → GREEN → REFACTOR → PROPERTY → QUALIFY ✅ Comprehensive testing: 10 tests, 1250+ iterations ✅ Quality code: Clean, documented, zero SATD ✅ Toyota Way: Two Stop The Line events, perfect execution ✅ Real learning: Handled actual bugs professionally

Most Important: Quality comes first. When we found bugs, we stopped, filed reports, and the Ruchy team fixed them quickly. This is professional development.

Next Steps

You're ready for:

• Chapter 2: ruchy-grep - Pattern matching
• Chapter 3: ruchy-wc - Counting and Unicode
• Part III: Deep dives into mutation/property testing

The foundation is solid. Let's build more!

Project Files:

• examples/ruchy-cat/cat.ruchy - Implementation (60 lines)
• examples/ruchy-cat/cat_test.ruchy - Tests (280 lines)
• examples/ruchy-cat/QUALIFICATION_REPORT.md - Tool results
• STOP_THE_LINE_REPORT.md - Bug #30
• STOP_THE_LINE_REPORT_2.md - Bugs #31-36
• BUG_VERIFICATION_v3.83.0.md - Final verification