Module effects

debtmap

Module effects 

Source
Expand description

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:

§Writer Effect for Telemetry (Spec 002)

The telemetry submodule provides the Writer Effect pattern for collecting analysis telemetry without threading state through function parameters:

ⓘ
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:

ⓘ
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):

ⓘ
fn analyze(ast: &Ast, config: &Config) -> Metrics {
    calculate_complexity(ast, &config.thresholds)
}

After (Reader pattern):

ⓘ
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

§Example: Using Effects

ⓘ
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

ⓘ
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-exports§

pub use combinators::filter_effect;
pub use combinators::filter_map_effect;
pub use combinators::first;
pub use combinators::fold_effect;
pub use combinators::par_traverse_effect;
pub use combinators::second;
pub use combinators::sequence_effects;
pub use combinators::traverse_effect;
pub use combinators::zip_effect;
pub use io::file_exists_effect;
pub use io::is_dir_effect;
pub use io::is_file_effect;
pub use io::read_file_bytes_effect;
pub use io::read_file_effect;
pub use io::write_file_effect;

Modules§

combinators
Effect combinators for composing analysis operations.
io
File I/O effects for the analysis pipeline.
progress
Progress effects and combinators for composable progress reporting.
sink
Sink Effect for Report Streaming
telemetry
Writer Effect for Analysis Telemetry
validation
Expanded validation patterns using stillwater’s predicate combinators.

Structs§

SharedFn
A wrapper type that makes a shared function callable via Fn traits.

Functions§

ask_env
Query the entire environment.
asks_config
Query config through closure - the core Reader pattern primitive.
asks_entropy
Query entropy config section.
asks_scoring
Query scoring weights config section.
asks_thresholds
Query thresholds config section.
combine_validations
Combine multiple validations, accumulating all errors.
effect_fail
Create an effect from an error.
effect_from_fn
Create an effect from a synchronous function.
effect_pure
Create an effect from a pure value (no I/O).
get_retry_config
Get the effective retry config from a DebtmapConfig.
is_retry_enabled
Check if retries are enabled in the given config.
local_with_config
Run an effect with a temporarily modified config.
run_effect
Run an effect and convert the result to anyhow::Result for backwards compatibility.
run_effect_async
Run an effect asynchronously.
run_effect_with_env
Run an effect with a custom environment.
run_validation
Convert a Validation result to anyhow::Result for backwards compatibility.
validation_failure
Create a failed validation result with a single error.
validation_failures
Create a failed validation result with multiple errors.
validation_map
Map a function over a validation’s success value.
validation_success
Create a successful validation result.
with_retry
Wrap an effect with retry logic using the configured policy.
with_retry_from_env
Wrap an effect with retry logic, using the retry config from environment.

Type Aliases§

AnalysisEffect
Effect type for debtmap analysis operations.
AnalysisErrors
Error collection type for validation accumulation.
AnalysisValidation
Validation type for debtmap validations.