1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
//! Effect type aliases and helpers for debtmap analysis.
//!
//! This module provides type aliases that integrate stillwater's effect system
//! with debtmap's environment and error types. Using these aliases:
//!
//! - Reduces boilerplate in function signatures
//! - Centralizes the environment and error types
//! - Makes it easy to refactor if types change
//!
//! # Effect vs Validation
//!
//! - **Effect**: Represents a computation that may perform I/O and may fail.
//! Use for operations like reading files or loading coverage data.
//!
//! - **Validation**: Represents a validation check that accumulates ALL errors
//! instead of failing at the first one. Use for configuration validation,
//! input checking, and anywhere you want comprehensive error reporting.
//!
//! # Reader Pattern (Spec 199)
//!
//! This module also provides **Reader pattern** helpers using stillwater 0.11.0's
//! zero-cost `ask`, `asks`, and `local` primitives. The Reader pattern eliminates
//! config parameter threading by making configuration available through the
//! environment.
//!
//! # Progress Effects (Spec 262)
//!
//! The [`progress`] submodule provides combinators for composable progress reporting:
//!
//! - [`progress::with_stage`]: Wrap an effect with stage tracking
//! - [`progress::traverse_with_progress`]: Sequential traversal with progress
//! - [`progress::par_traverse_with_progress`]: Parallel traversal with atomic progress
//! - [`progress::report_progress`]: Direct progress reporting effect
//!
//! # Writer Effect for Telemetry (Spec 002)
//!
//! The [`telemetry`] submodule provides the Writer Effect pattern for collecting
//! analysis telemetry without threading state through function parameters:
//!
//! - [`telemetry::AnalysisEvent`]: Events emitted during analysis
//! - [`telemetry::AnalysisMetrics`]: Collection of events with Monoid accumulation
//! - [`telemetry::AnalysisSummary`]: Aggregated summary statistics
//! - [`telemetry::tell_event`]: Emit a single telemetry event
//! - [`telemetry::tell_events`]: Emit multiple telemetry events
//!
//! ```rust,ignore
//! use debtmap::effects::telemetry::{tell_event, AnalysisEvent, AnalysisMetrics};
//! use stillwater::WriterEffectExt;
//!
//! // Emit telemetry alongside computation
//! let effect = tell_event(AnalysisEvent::file_started(path.clone()))
//! .and_then(|_| do_analysis(path))
//! .tap_tell(|result| AnalysisMetrics::event(
//! AnalysisEvent::file_completed(path, result.duration_ms)
//! ));
//!
//! // Collect all events
//! let (result, metrics) = effect.run_writer(&env).await;
//! let summary: AnalysisSummary = metrics.into();
//! ```
//!
//! # Sink Effect for Report Streaming (Spec 003)
//!
//! The [`sink`] submodule provides the Sink Effect pattern for streaming analysis
//! reports with O(1) memory overhead:
//!
//! - [`sink::ReportLine`]: Report line types (JSON, text, header, separator)
//! - [`sink::emit_report_line`]: Emit a single report line
//! - [`sink::emit_json_line`]: Emit a JSON Lines formatted line
//! - [`sink::run_with_file_sink`]: Execute with file output
//! - [`sink::run_with_stdout_sink`]: Execute with stdout output
//!
//! ```rust,ignore
//! use debtmap::effects::sink::{emit_header, emit_json_line, run_with_file_sink};
//! use stillwater::effect::sink::prelude::*;
//!
//! // Stream results as they're generated
//! let effect = emit_header::<AnalysisError, ()>("Analysis Results")
//! .and_then(|_| emit_json_line(&file_metrics));
//!
//! // Execute with file sink - constant memory
//! run_with_file_sink(effect, output_path, &()).await?;
//! ```
//!
//! ## Reader Pattern Benefits
//!
//! **Before (parameter threading):**
//! ```rust,ignore
//! fn analyze(ast: &Ast, config: &Config) -> Metrics {
//! calculate_complexity(ast, &config.thresholds)
//! }
//! ```
//!
//! **After (Reader pattern):**
//! ```rust,ignore
//! use debtmap::effects::asks_config;
//!
//! fn analyze_effect<Env>(ast: Ast) -> impl Effect<...>
//! where Env: AnalysisEnv + Clone + Send + Sync
//! {
//! asks_config(move |config| calculate_complexity(&ast, &config.thresholds))
//! }
//! ```
//!
//! ## Available Reader Helpers
//!
//! - [`asks_config`]: Access the full config via closure
//! - [`asks_thresholds`]: Access thresholds config section
//! - [`asks_scoring`]: Access scoring weights config section
//! - [`asks_entropy`]: Access entropy config section
//! - [`local_with_config`]: Run effect with modified config (temporary override)
//!
//! # Example: Using Effects
//!
//! ```rust,ignore
//! use debtmap::effects::AnalysisEffect;
//! use debtmap::env::AnalysisEnv;
//! use stillwater::Effect;
//!
//! fn read_source(path: PathBuf) -> AnalysisEffect<String> {
//! Effect::from_fn(move |env: &dyn AnalysisEnv| {
//! env.file_system()
//! .read_to_string(&path)
//! .map_err(Into::into)
//! })
//! }
//! ```
//!
//! # Example: Using Progress Effects
//!
//! ```rust,ignore
//! use debtmap::effects::progress::{with_stage, traverse_with_progress};
//!
//! fn analyze_files(files: Vec<PathBuf>) -> AnalysisEffect<Vec<FileMetrics>> {
//! with_stage("Analysis", traverse_with_progress(
//! files,
//! "File Processing",
//! |path| analyze_file_effect(path)
//! ))
//! }
//! ```
// Re-export everything from core
pub use *;
// Re-export key functions from submodules for convenience
pub use ;
pub use ;