ralph_workflow/
lib.rs

1// DO NOT CHANGE THESE CLIPPY SETTINGS, YOU MUST REFACTOR INSTEAD, EVEN IF IT TAKES YOU 100 YEARS
2// Note: unsafe_code is not denied in lib.rs because the library requires unsafe blocks for
3// legitimate POSIX operations (fcntl, kill, setpgid, etc.) with proper safety documentation.
4// The binary target (main.rs) denies unsafe_code since it should contain no unsafe operations.
5//
6// Note: clippy::cargo is not enabled because it flags transitive dependency version conflicts
7// (e.g., bitflags 1.3.2 from inotify vs 2.10.0 from other crates) which are ecosystem-level
8// issues outside our control and don't reflect code quality problems.
9#![deny(warnings, clippy::all, clippy::pedantic, clippy::nursery)]
10//! Ralph workflow library for AI agent orchestration.
11//!
12//! This crate provides the core functionality for the `ralph` CLI binary,
13//! implementing a reducer-based architecture for orchestrating AI coding agents
14//! through development and review cycles.
15//!
16//! # Quick Start
17//!
18//! Ralph is primarily a CLI binary. For library use (integration testing):
19//!
20//! ```toml
21//! [dev-dependencies]
22//! ralph-workflow = { version = "0.6", features = ["test-utils"] }
23//! ```
24//!
25//! # Architecture
26//!
27//! Ralph uses an **event-sourced reducer architecture**. The core state machine
28//! follows the pattern:
29//!
30//! ```text
31//! State → Orchestrator → Effect → Handler → Event → Reducer → State
32//! ```
33//!
34//! | Component | Pure? | Role |
35//! |-----------|-------|------|
36//! | [`reducer::PipelineState`] | Yes | Immutable progress snapshot, doubles as checkpoint |
37//! | [`reducer::reduce`] | Yes | `(State, Event) → State` |
38//! | [`reducer::determine_next_effect`] | Yes | `State → Effect` |
39//! | [`reducer::EffectHandler`] | No | Executes effects, produces events |
40//!
41//! Business logic lives in reducers (pure). I/O lives in handlers (impure).
42//!
43//! ## Two Effect Layers
44//!
45//! Ralph has two distinct effect types for different pipeline stages:
46//!
47//! | Layer | Module | When | Filesystem Access |
48//! |-------|--------|------|-------------------|
49//! | `AppEffect` | [`app`] | Before repo root known | `std::fs` directly |
50//! | `Effect` | [`reducer`] | After repo root known | Via [`workspace::Workspace`] |
51//!
52//! These layers must never mix: `AppEffect` cannot use `Workspace`, and `Effect`
53//! cannot use `std::fs` directly.
54//!
55//! # I/O Abstractions
56//!
57//! All I/O is abstracted through traits for testability:
58//!
59//! - [`workspace::Workspace`] - Filesystem operations
60//!   - Production: [`workspace::WorkspaceFs`]
61//!   - Tests: `MemoryWorkspace` (with `test-utils` feature)
62//! - [`ProcessExecutor`] - Process spawning
63//!   - Production: [`RealProcessExecutor`]
64//!   - Tests: `MockProcessExecutor` (with `test-utils` feature)
65//!
66//! # Feature Flags
67//!
68//! - `monitoring` (default) - Enable streaming metrics and debugging APIs
69//! - `test-utils` - Enable test utilities (`MockProcessExecutor`, `MemoryWorkspace`, etc.)
70//! - `hardened-resume` (default) - Enable checkpoint file state capture for recovery
71//!
72//! # Key Modules
73//!
74//! **Core Architecture:**
75//! - [`reducer`] - Core state machine with pure reducers and effect handlers
76//! - [`app`] - CLI layer operating before repo root is known (`AppEffect`)
77//! - [`phases`] - Pipeline phase implementations (planning, development, review, commit)
78//!
79//! **I/O Abstractions:**
80//! - [`workspace`] - Filesystem abstraction (`WorkspaceFs` production, `MemoryWorkspace` testing)
81//! - [`executor`] - Process execution abstraction for agent spawning
82//!
83//! **Agent Infrastructure:**
84//! - [`agents`] - Agent configuration, registry, and CCS (Claude Code Switch) support
85//! - [`json_parser`] - NDJSON streaming parsers for Claude, Codex, Gemini, `OpenCode`
86//! - [`prompts`] - Template system for agent prompts
87//!
88//! **Supporting:**
89//! - [`git_helpers`] - Git operations using libgit2 (no CLI dependency)
90//! - [`checkpoint`] - Pipeline state persistence for `--resume` support
91//! - [`config`] - Configuration loading and verbosity levels
92//!
93//! # Error Handling
94//!
95//! Most functions return `anyhow::Result` for flexible error handling with context.
96//! Use `.context()` to add context to errors as they propagate.
97
98pub mod agents;
99pub mod app;
100pub mod banner;
101pub mod checkpoint;
102pub mod cli;
103pub mod cloud;
104pub mod common;
105pub mod config;
106pub mod diagnostics;
107pub mod executor;
108pub mod exit_pause;
109pub mod files;
110pub mod git_helpers;
111pub mod guidelines;
112pub mod interrupt;
113pub mod json_parser;
114pub mod language_detector;
115pub mod logger;
116pub mod logging;
117pub mod monitoring;
118pub mod phases;
119pub mod pipeline;
120pub mod platform;
121pub mod prompts;
122pub mod reducer;
123pub mod rendering;
124pub mod review_metrics;
125pub mod templates;
126pub mod workspace;
127
128// Benchmarks module - contains public baselines used by integration tests.
129// Benchmark *tests* inside the module remain `#[cfg(test)]`.
130pub mod benchmarks;
131
132// Re-export XML extraction and validation functions for use in integration tests.
133// These functions parse and validate XML output from agent responses (plan, issues, fix results).
134pub use files::llm_output_extraction::extract_development_result_xml;
135pub use files::llm_output_extraction::extract_fix_result_xml;
136pub use files::llm_output_extraction::extract_issues_xml;
137pub use files::llm_output_extraction::validate_development_result_xml;
138pub use files::llm_output_extraction::validate_fix_result_xml;
139pub use files::llm_output_extraction::validate_issues_xml;
140
141// Re-export process executor types for dependency injection.
142// See [`executor`] module for documentation.
143pub use executor::{
144    AgentChild, AgentChildHandle, AgentCommandResult, AgentSpawnConfig, ProcessExecutor,
145    ProcessOutput, RealAgentChild, RealProcessExecutor,
146};
147
148// Re-export mock executor for test-utils feature.
149// Use MockProcessExecutor to control process behavior in integration tests.
150#[cfg(any(test, feature = "test-utils"))]
151pub use executor::{MockAgentChild, MockProcessExecutor};
ralph_workflow/lib.rs

ralph_workflow/
lib.rs
