ruchy-book GEMINI.md

Gemini Project Context

This document provides context for the Gemini AI assistant to understand the Ruchy Book project.

Project Overview

This project is the official book for the Ruchy programming language, developed with a strict Test-Driven Development (TDD) methodology. All code examples are first written as tests and verified before being included in the documentation. The book is built using mdbook.

The core philosophy is: "Test first, document what works, never promise what doesn't exist."

Technology Stack

• Ruchy (ruchy): The programming language being documented. The project is pinned to a specific version of the ruchy compiler.
• mdBook (mdbook): A utility to create books from Markdown files. Used to build the final HTML version of the book.
• Rust: The integration test suite that validates all Ruchy code examples is written in Rust. Cargo.toml defines the testing dependencies.
• Deno: Used for scripting various development and workflow tasks, such as extracting examples, running tests, and generating reports. Configuration is in deno.json.

Development Workflow

The development process is centered around make and deno tasks.

Key Commands

• Run all tests:

  make test
  

• Build the book:

  mdbook build
  

• Serve the book locally:

  mdbook serve
  

• Run lint checks:

  make dogfood-quick
  

• Run Deno-based scripts:

  deno task <task_name>
  

  (e.g., deno task test-oneliners, deno task extract-examples)

TDD Process for New Content

1. Write a test: Add a new .ruchy file in the tests/ directory.
2. Verify the test: Run the test to ensure it works as expected.
3. Document the feature: Add the explanation and code to a Markdown file in src/.
4. Validate: Run make validate to ensure all checks pass.

Project Structure

• src/: Contains the Markdown source files for the book's chapters.
• tests/: Contains the Ruchy code examples, which double as integration tests.
• book/: The output directory for the built book (generated by mdbook).
• scripts/: Deno scripts for automation (testing, linting, reports).
• book.toml: mdbook configuration file.
• Cargo.toml: Rust project file for the test harness.
• deno.json: Deno configuration and task definitions.
• Makefile: Defines the main entry points for development tasks.
• INTEGRATION.md: The single source of truth for project status, test results, and quality metrics.