ralph_workflow/
lib.rs

1// DO NOT CHANGE LINTING POLICY UNLESS THE USER SPECIFICALLY ASKS TO, YOU MUST REFACTOR EVEN IF IT TAKES YOU LONG TIME
2//
3// Note: unsafe_code is not denied in lib.rs because the library requires unsafe blocks for
4// legitimate POSIX operations (fcntl, kill, setpgid, etc.) with proper safety documentation.
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)]
10#![deny(clippy::all)]
11#![deny(
12    // No explicit iterator loops when a more idiomatic form exists
13    clippy::explicit_iter_loop,
14    clippy::explicit_into_iter_loop,
15    // NOTE: Many lints are not denied because this is a complex workflow library
16    // that uses performance-critical code patterns and has extensive test code.
17    // This is documented in the lint policy exception table.
18    clippy::dbg_macro,
19    // Push toward combinators instead of hand-written control flow
20    clippy::manual_map,
21    clippy::manual_filter,
22    clippy::manual_find,
23    clippy::manual_filter_map,
24    clippy::manual_flatten,
25    clippy::needless_collect
26)]
27//! Ralph workflow library for AI agent orchestration.
28//!
29//! This crate provides the core functionality for the `ralph` CLI binary,
30//! implementing a reducer-based architecture for orchestrating AI coding agents
31//! through development and review cycles.
32//!
33//! # Quick Start
34//!
35//! Ralph is primarily a CLI binary. For library use (integration testing):
36//!
37//! ```toml
38//! [dev-dependencies]
39//! ralph-workflow = { version = "0.6", features = ["test-utils"] }
40//! ```
41//!
42//! # Architecture
43//!
44//! Ralph uses an **event-sourced reducer architecture**. The core state machine
45//! follows the pattern:
46//!
47//! ```text
48//! State → Orchestrator → Effect → Handler → Event → Reducer → State
49//! ```
50//!
51//! | Component | Pure? | Role |
52//! |-----------|-------|------|
53//! | [`reducer::PipelineState`] | Yes | Immutable progress snapshot, doubles as checkpoint |
54//! | [`reducer::reduce`] | Yes | `(State, Event) → State` |
55//! | [`reducer::determine_next_effect`] | Yes | `State → Effect` |
56//! | [`reducer::EffectHandler`] | No | Executes effects, produces events |
57//!
58//! Business logic lives in reducers (pure). I/O lives in handlers (impure).
59//!
60//! ## Two Effect Layers
61//!
62//! Ralph has two distinct effect types for different pipeline stages:
63//!
64//! | Layer | Module | When | Filesystem Access |
65//! |-------|--------|------|-------------------|
66//! | `AppEffect` | [`app`] | Before repo root known | `std::fs` directly |
67//! | `Effect` | [`reducer`] | After repo root known | Via [`workspace::Workspace`] |
68//!
69//! These layers must never mix: `AppEffect` cannot use `Workspace`, and `Effect`
70//! cannot use `std::fs` directly.
71//!
72//! # I/O Abstractions
73//!
74//! All I/O is abstracted through traits for testability:
75//!
76//! - [`workspace::Workspace`] - Filesystem operations
77//!   - Production: [`workspace::WorkspaceFs`]
78//!   - Tests: `MemoryWorkspace` (with `test-utils` feature)
79//! - [`ProcessExecutor`] - Process spawning
80//!   - Production: [`RealProcessExecutor`]
81//!   - Tests: `MockProcessExecutor` (with `test-utils` feature)
82//!
83//! # Feature Flags
84//!
85//! - `monitoring` (default) - Enable streaming metrics and debugging APIs
86//! - `test-utils` - Enable test utilities (`MockProcessExecutor`, `MemoryWorkspace`, etc.)
87//! - `hardened-resume` (default) - Enable checkpoint file state capture for recovery
88//!
89//! # Key Modules
90//!
91//! **Core Architecture:**
92//! - [`reducer`] - Core state machine with pure reducers and effect handlers
93//! - [`app`] - CLI layer operating before repo root is known (`AppEffect`)
94//! - [`phases`] - Pipeline phase implementations (planning, development, review, commit)
95//!
96//! **I/O Abstractions:**
97//! - [`workspace`] - Filesystem abstraction (`WorkspaceFs` production, `MemoryWorkspace` testing)
98//! - [`executor`] - Process execution abstraction for agent spawning
99//!
100//! **Agent Infrastructure:**
101//! - [`agents`] - Agent configuration, registry, and CCS (Claude Code Switch) support
102//! - [`json_parser`] - NDJSON streaming parsers for Claude, Codex, Gemini, `OpenCode`
103//! - [`prompts`] - Template system for agent prompts
104//!
105//! **Supporting:**
106//! - [`git_helpers`] - Git operations using libgit2 (no CLI dependency)
107//! - [`checkpoint`] - Pipeline state persistence for `--resume` support
108//! - [`config`] - Configuration loading and verbosity levels
109//!
110//! # Error Handling
111//!
112//! Most functions return `anyhow::Result` for flexible error handling with context.
113//! Use `.context()` to add context to errors as they propagate.
114
115pub mod agents;
116pub mod app;
117pub mod banner;
118pub mod checkpoint;
119pub mod cli;
120pub mod cloud;
121pub mod common;
122pub mod config;
123pub mod diagnostics;
124pub mod executor;
125pub mod exit_pause;
126pub mod files;
127pub mod git_helpers;
128pub mod guidelines;
129pub mod interrupt;
130pub mod json_parser;
131pub mod language_detector;
132pub mod logger;
133pub mod logging;
134pub mod monitoring;
135pub mod phases;
136pub mod pipeline;
137pub mod platform;
138pub mod prompts;
139pub mod reducer;
140pub mod rendering;
141pub mod review_metrics;
142pub mod templates;
143pub mod workspace;
144
145// Benchmarks module - contains public baselines used by integration tests.
146// Benchmark *tests* inside the module remain `#[cfg(test)]`.
147pub mod benchmarks;
148
149// Re-export XML extraction and validation functions for use in integration tests.
150// These functions parse and validate XML output from agent responses (plan, issues, fix results).
151pub use files::llm_output_extraction::extract_development_result_xml;
152pub use files::llm_output_extraction::extract_fix_result_xml;
153pub use files::llm_output_extraction::extract_issues_xml;
154pub use files::llm_output_extraction::validate_continuation_development_result_xml;
155pub use files::llm_output_extraction::validate_development_result_xml;
156pub use files::llm_output_extraction::validate_fix_result_xml;
157pub use files::llm_output_extraction::validate_issues_xml;
158pub use files::llm_output_extraction::validate_plan_xml;
159pub use files::llm_output_extraction::validate_xml_against_xsd;
160
161// Re-export process executor types for dependency injection.
162// See [`executor`] module for documentation.
163pub use executor::{
164    AgentChild, AgentChildHandle, AgentCommandResult, AgentSpawnConfig, ChildProcessInfo,
165    ProcessExecutor, ProcessOutput, RealAgentChild, RealProcessExecutor,
166};
167
168// Re-export mock executor for test-utils feature.
169// Use MockProcessExecutor to control process behavior in integration tests.
170#[cfg(any(test, feature = "test-utils"))]
171pub use executor::{MockAgentChild, MockProcessExecutor};
ralph_workflow/lib.rs

ralph_workflow/
lib.rs
