fallow_api/runtime/

mod.rs

//! Programmatic runtime entry points that avoid depending on `fallow-cli`.

use std::path::{Path, PathBuf};

use fallow_config::{FallowConfig, HealthConfig, ProductionConfig};
use fallow_engine::{
    dead_code::DeadCodeAnalysisArtifacts,
    duplicates::DuplicationReport,
    project_config::{ProductionFlags, ProductionModes},
    session::AnalysisSession,
};
use fallow_output::{HealthGrouping, HealthReport};
use fallow_types::output_format::OutputFormat;
use fallow_types::workspace::WorkspaceDiagnostic;
use rustc_hash::FxHashSet;

mod audit;
mod combined;
mod dead_code;
mod decision_surface;
mod duplication;
mod feature_flags;
mod mutation;
mod similar_code;
mod trace;
mod type_aware_config;

pub use crate::runtime_output::{
    ArchitectureOutput, ArchitectureProgrammaticOutput, AuditProgrammaticKeySnapshot,
    AuditProgrammaticOutput, BoundaryViolationsOutput, BoundaryViolationsProgrammaticOutput,
    CircularDependenciesOutput, CircularDependenciesProgrammaticOutput, CombinedProgrammaticOutput,
    DeadCodeOutput, DeadCodeProgrammaticOutput, DecisionSurfaceProgrammaticOutput,
    DuplicationOutput, DuplicationProgrammaticOutput, FeatureFlagsOutput,
    FeatureFlagsProgrammaticOutput, HealthJsonReportInput, HealthProgrammaticOutput,
    TraceClassMemberOutput, TraceCloneOutput, TraceCloneProgrammaticOutput, TraceDependencyOutput,
    TraceDependencyProgrammaticOutput, TraceErrorOutput, TraceErrorProgrammaticOutput,
    TraceExportOutput, TraceExportProgrammaticOutput, TraceExportTargetOutput, TraceFileOutput,
    TraceFileProgrammaticOutput, TraceImportPathOutput, TraceImportPathProgrammaticOutput,
    serialize_health_report_json,
};
pub use audit::{AUDIT_CONFIG_BASELINE_UNSUPPORTED, run_audit};
pub use combined::run_combined;
pub use dead_code::{
    run_architecture, run_boundary_violations, run_circular_dependencies, run_dead_code,
    run_dead_code_with_baseline,
};
pub use decision_surface::run_decision_surface;
pub use duplication::run_duplication;
pub use feature_flags::run_feature_flags;
pub use mutation::{plan_mutation, run_mutation};
pub use similar_code::{
    inspect_similar_code, parse_similar_code_candidate_snapshot, review_similar_code,
    run_similar_code, select_similar_code_candidate_snapshot,
};
pub use trace::{
    TraceCloneBenchmarkResult, benchmark_trace_clone_compact_json,
    benchmark_trace_graph_family_compact_json, run_trace_clone, run_trace_dependency,
    run_trace_error, run_trace_export, run_trace_file, run_trace_import_path,
};
pub use type_aware_config::TYPE_AWARE_CONFIG_UNSUPPORTED;

use crate::{
    ComplexityOptions, ProgrammaticError,
    analysis_context::{
        ProgrammaticAnalysisContext, resolve_programmatic_analysis_context,
        workspace_roots_for_session,
    },
    derive_complexity_options,
    next_steps::{audit_changed_applicable, setup_pointer_applicable, suggestions_enabled},
};

type ProgrammaticResult<T> = Result<T, ProgrammaticError>;

pub(super) fn resolve_effective_production_modes(
    resolved: &ProgrammaticAnalysisContext,
    dead_code_override: Option<bool>,
    health_override: Option<bool>,
    dupes_override: Option<bool>,
) -> ProgrammaticResult<ProductionModes> {
    let config = load_context_production_config(resolved)?;
    Ok(ProductionFlags {
        global: resolved.production_override(),
        dead_code: dead_code_override,
        health: health_override,
        dupes: dupes_override,
    }
    .effective_modes(config))
}

fn load_context_production_config(
    resolved: &ProgrammaticAnalysisContext,
) -> ProgrammaticResult<ProductionConfig> {
    let loaded = load_config_file(
        resolved.root(),
        resolved.config_path().as_deref(),
        resolved.allow_remote_extends(),
    )?;
    Ok(loaded.map_or_else(ProductionConfig::default, |config| config.production))
}

/// Load the `health` section of the project config for adapters that layer
/// config-sourced coverage inputs before building options (the MCP typed
/// route; see [`crate::coverage`]). The root and config path resolve exactly
/// as they do for the analysis itself. Returns `None` when the project has no
/// config file.
///
/// # Errors
///
/// Returns the analysis-context errors for an invalid root or config path,
/// and `FALLOW_CONFIG_LOAD_FAILED` when the config cannot be loaded.
pub fn load_health_config(
    options: &crate::AnalysisOptions,
) -> ProgrammaticResult<Option<HealthConfig>> {
    let root = crate::analysis_context::resolve_analysis_root(options.root.as_deref())?;
    crate::analysis_context::validate_analysis_config_path(options.config_path.as_deref())?;
    let loaded = load_config_file(
        &root,
        options.config_path.as_deref(),
        options.allow_remote_extends,
    )?;
    Ok(loaded.map(|config| config.health))
}

fn load_config_file(
    root: &Path,
    config_path: Option<&Path>,
    allow_remote_extends: bool,
) -> ProgrammaticResult<Option<FallowConfig>> {
    let load_options = fallow_config::ConfigLoadOptions {
        allow_remote_extends,
    };
    if let Some(path) = config_path {
        return FallowConfig::load_with_options(path, load_options)
            .map(Some)
            .map_err(|err| config_load_error(format!("failed to load config: {err:#}")));
    }
    FallowConfig::find_and_load_with_options(root, load_options)
        .map(|found| found.map(|(config, _)| config))
        .map_err(|err| config_load_error(format!("failed to load config: {err}")))
}

fn config_load_error(message: String) -> ProgrammaticError {
    ProgrammaticError::new(message, 2)
        .with_code("FALLOW_CONFIG_LOAD_FAILED")
        .with_context("analysis.configPath")
}

pub(super) fn health_may_consume_dead_code_artifacts(
    options: &ComplexityOptions,
    config: &fallow_config::ResolvedConfig,
) -> bool {
    let sections = derive_complexity_options(options);
    let max_crap = options.max_crap.unwrap_or(config.health.max_crap);
    sections.file_scores
        || sections.coverage_gaps
        || sections.hotspots
        || sections.targets
        || sections.force_full
        || max_crap > 0.0
}

pub(super) fn health_may_consume_duplication_report(options: &ComplexityOptions) -> bool {
    let sections = derive_complexity_options(options);
    sections.score || sections.targets
}

/// Runtime probes used by programmatic health output assembly.
///
/// Concrete runners supply environment and project facts while the stable
/// command strings and output ordering remain owned by `fallow-output`.
pub struct ProgrammaticHealthNextStepFacts {
    /// False when `FALLOW_SUGGESTIONS=off`; suppresses all steps.
    pub suggestions_enabled: bool,
    /// Offer the guided-setup pointer because no fallow config exists yet.
    pub offer_setup: bool,
    /// Local impact digest counters, when a digest is available.
    pub impact_digest: Option<fallow_output::ImpactDigestCounts>,
    /// Offer `fallow audit` because the working tree has changed files.
    pub audit_changed: bool,
}

/// API-owned health analysis payload returned by programmatic runners.
///
/// The engine owns execution, but this type is the public runner contract so
/// embedders do not have to construct or depend on engine result structs.
pub struct ProgrammaticHealthAnalysis {
    /// Typed health report produced by the engine.
    pub report: HealthReport,
    /// Grouped findings when a grouping mode was requested.
    pub grouping: Option<HealthGrouping>,
    /// Resolved analysis root the report paths are relative to.
    pub root: PathBuf,
    /// Analysis wall time.
    pub elapsed: std::time::Duration,
}

impl ProgrammaticHealthAnalysis {
    fn from_engine<GroupResolver>(
        analysis: fallow_engine::health::HealthAnalysisResult<GroupResolver>,
    ) -> Self {
        Self {
            root: analysis.config.root,
            report: analysis.report,
            grouping: analysis.grouping,
            elapsed: analysis.elapsed,
        }
    }
}

/// Health runner output shared by API, NAPI, and alternate runners.
///
/// Runtime-only presentation probes stay explicit so the API boundary, not the
/// concrete runner, owns the final programmatic report assembly.
pub struct ProgrammaticHealthRun {
    /// Engine analysis payload.
    pub analysis: ProgrammaticHealthAnalysis,
    /// Non-fatal per-file diagnostics collected during the workspace walk.
    pub workspace_diagnostics: Vec<WorkspaceDiagnostic>,
    /// Environment and project facts that drive next-step suggestions.
    pub next_step_facts: ProgrammaticHealthNextStepFacts,
    /// Analysis run id stamped into telemetry metadata when present.
    pub telemetry_analysis_run_id: Option<String>,
    /// What became of the narrowing requests the run received.
    pub request_outcomes: Option<fallow_output::RequestOutcomes>,
}

/// Runner boundary for programmatic health.
///
/// This keeps embedders on the typed API contract while still allowing tests
/// and host integrations to provide a custom health runner.
pub trait ProgrammaticHealthRunner {
    /// Run health analysis for public programmatic options.
    ///
    /// # Errors
    ///
    /// Returns a structured programmatic error when the concrete runner cannot
    /// resolve options or complete health analysis.
    fn run_programmatic_health(
        &self,
        options: &ComplexityOptions,
    ) -> Result<ProgrammaticHealthRun, ProgrammaticError>;
}

/// Default health runner backed directly by `fallow-engine`.
///
/// This runs the command-neutral health pipeline through the engine health
/// runner without touching the CLI crate: the programmatic
/// path never groups (`--group-by`), never drives the runtime coverage sidecar,
/// and never records CLI telemetry, so the runner hooks are inert. This is
/// the default runner for NAPI and Rust embedders.
#[derive(Debug, Clone, Copy, Default)]
pub struct EngineHealthRunner;

impl ProgrammaticHealthRunner for EngineHealthRunner {
    fn run_programmatic_health(
        &self,
        options: &ComplexityOptions,
    ) -> Result<ProgrammaticHealthRun, ProgrammaticError> {
        let resolved = resolve_programmatic_analysis_context(&options.analysis)?;
        resolved.install(|| run_programmatic_health_on_engine(&resolved, options))
    }
}

fn run_programmatic_health_on_engine(
    resolved: &ProgrammaticAnalysisContext,
    options: &ComplexityOptions,
) -> ProgrammaticResult<ProgrammaticHealthRun> {
    let health_options = derive_programmatic_health_execution_options(resolved, options);
    let loaded = fallow_engine::health::UngroupedHealthSession::load(&health_options)
        .map_err(|error| programmatic_health_error("health", error))?;
    let workspace_roots = workspace_roots_for_session(resolved, loaded.workspaces())?;
    let result = loaded
        .run(&health_options, workspace_roots)
        .map_err(|error| programmatic_health_error("health", error))?;
    resolved.record_changed_since_from_runner(result.changed_files_analyzed.as_deref());

    Ok(programmatic_health_run_from_engine_result(
        result,
        resolved.request_outcomes(),
    ))
}

fn programmatic_health_run_from_engine_result<GroupResolver>(
    result: fallow_engine::health::HealthAnalysisResult<GroupResolver>,
    request_outcomes: Option<fallow_output::RequestOutcomes>,
) -> ProgrammaticHealthRun {
    let root = result.config.root.clone();
    let next_step_facts = ProgrammaticHealthNextStepFacts {
        suggestions_enabled: suggestions_enabled(),
        offer_setup: setup_pointer_applicable(&root),
        impact_digest: None,
        audit_changed: audit_changed_applicable(&root),
    };
    ProgrammaticHealthRun {
        workspace_diagnostics: result.workspace_diagnostics.clone(),
        analysis: ProgrammaticHealthAnalysis::from_engine(result.without_group_resolver()),
        next_step_facts,
        telemetry_analysis_run_id: None,
        request_outcomes,
    }
}

#[cfg(test)]
pub(super) fn run_health_with_session(
    options: &ComplexityOptions,
    resolved: &ProgrammaticAnalysisContext,
    session: &AnalysisSession,
    changed_files: Option<&FxHashSet<PathBuf>>,
) -> ProgrammaticResult<HealthProgrammaticOutput> {
    run_health_with_session_artifacts(options, resolved, session, changed_files, None, None)
}

pub(super) fn run_health_with_session_artifacts(
    options: &ComplexityOptions,
    resolved: &ProgrammaticAnalysisContext,
    session: &AnalysisSession,
    changed_files: Option<&FxHashSet<PathBuf>>,
    pre_computed_analysis: Option<DeadCodeAnalysisArtifacts>,
    pre_computed_duplication: Option<DuplicationReport>,
) -> ProgrammaticResult<HealthProgrammaticOutput> {
    crate::validate_complexity_options(options)?;
    let health_options = derive_programmatic_health_execution_options(resolved, options);
    let workspace_roots = workspace_roots_for_session(resolved, session.workspaces())?;
    let result = fallow_engine::health::run_ungrouped_health_with_session_artifacts(
        &health_options,
        workspace_roots,
        session,
        changed_files.map(|files| files.iter().cloned().collect()),
        pre_computed_analysis,
        pre_computed_duplication,
    )
    .map_err(|error| programmatic_health_error("health", error))?;
    resolved.record_changed_since_from_runner(result.changed_files_analyzed.as_deref());

    Ok(assemble_health_programmatic_output(
        options,
        programmatic_health_run_from_engine_result(result, resolved.request_outcomes()),
    ))
}

fn programmatic_health_error(
    command: &str,
    error: fallow_engine::health::HealthError,
) -> ProgrammaticError {
    let (message, exit_code) = match error {
        fallow_engine::health::HealthError::Message { message, exit_code } => (message, exit_code),
        fallow_engine::health::HealthError::Printed(exit_code) => {
            (format!("{command} failed"), exit_code)
        }
    };
    let code = format!(
        "FALLOW_{}_FAILED",
        command.replace('-', "_").to_ascii_uppercase()
    );
    ProgrammaticError::new(message, exit_code)
        .with_code(code)
        .with_context(format!("fallow {command}"))
        .with_help(format!(
            "Re-run `fallow {command} --format json --quiet` in the target project for CLI diagnostics"
        ))
}

/// Run programmatic health / complexity through the engine-backed runner.
///
/// # Errors
///
/// Returns a structured programmatic error for invalid options or analysis
/// failures.
pub fn run_health(options: &ComplexityOptions) -> ProgrammaticResult<HealthProgrammaticOutput> {
    run_health_with_runner(options, &EngineHealthRunner)
}

#[must_use]
fn derive_programmatic_health_execution_options<'a>(
    resolved: &'a ProgrammaticAnalysisContext,
    options: &'a ComplexityOptions,
) -> fallow_engine::health::HealthExecutionOptions<'a> {
    let run = crate::derive_complexity_run_options(options);

    fallow_engine::health::HealthExecutionOptions {
        root: resolved.root(),
        config_path: resolved.config_path(),
        output: OutputFormat::Human,
        no_cache: resolved.no_cache(),
        threads: resolved.threads(),
        quiet: true,
        complexity_breakdown: run.complexity_breakdown,
        thresholds: crate::thresholds_to_engine(run.thresholds),
        top: run.top,
        sort: crate::complexity_sort_to_engine(run.sort),
        production: resolved.production_override().unwrap_or(false),
        production_override: resolved.production_override(),
        allow_remote_extends: resolved.allow_remote_extends(),
        changed_since: resolved.changed_since(),
        diff_index: resolved.diff_index(),
        use_shared_diff_index: false,
        workspace: resolved.workspace(),
        changed_workspaces: resolved.changed_workspaces(),
        baseline: None,
        save_baseline: None,
        baseline_mode: fallow_engine::baseline::HealthBaselineMode::Count,
        baseline_mode_explicit: false,
        complexity: run.sections.complexity,
        file_scores: run.sections.file_scores,
        coverage_gaps: run.sections.coverage_gaps,
        config_activates_coverage_gaps: !run.sections.any_section,
        hotspots: run.sections.hotspots,
        ownership: run.sections.ownership,
        targets: run.sections.targets,
        css: run.css,
        css_deep: run.css_deep,
        force_full: run.sections.force_full,
        score_only_output: run.sections.score_only_output,
        enforce_coverage_gap_gate: true,
        effort: run.effort.map(crate::target_effort_to_output),
        score: run.sections.score,
        gates: fallow_engine::health::HealthGateOptions::default(),
        since: run.since,
        min_commits: run.min_commits,
        explain: resolved.explain_enabled(),
        summary: false,
        save_snapshot: None,
        trend: false,
        coverage_inputs: crate::coverage_inputs_to_engine(run.coverage_inputs),
        performance: false,
        runtime_coverage: None,
        churn_file: None,
        analysis_identity: fallow_types::semantic::SemanticAnalysisIdentity::default(),
        group_by: None,
        group_filter: None,
        trend_from: None,
        scope: None,
        ownership_emails: run
            .ownership_emails
            .map(crate::ownership_email_mode_to_config),
    }
}

/// Run programmatic health / complexity and return typed API output.
///
/// The runner is a seam for tests and hosts. [`EngineHealthRunner`] is the
/// default. The runner supplies typed analysis and runtime facts. This API
/// crate owns the final programmatic report assembly.
///
/// # Errors
///
/// Returns a structured programmatic error for invalid options or runner
/// failures. When no section is selected and the environment or
/// `typeAware.enabled` turns on type-aware analysis that the options leave
/// off, it returns [`TYPE_AWARE_CONFIG_UNSUPPORTED`].
pub fn run_complexity_with_runner(
    options: &ComplexityOptions,
    runner: &impl ProgrammaticHealthRunner,
) -> ProgrammaticResult<HealthProgrammaticOutput> {
    crate::validate_complexity_options(options)?;
    reject_health_config_type_aware(options)?;
    run_validated_complexity(options, runner)
}

/// The health section of `fallow audit`. Audit resolves type-aware analysis
/// with its own precedence, so the `fallow health` check does not apply.
pub(super) fn run_health_for_audit(
    options: &ComplexityOptions,
) -> ProgrammaticResult<HealthProgrammaticOutput> {
    crate::validate_complexity_options(options)?;
    run_validated_complexity(options, &EngineHealthRunner)
}

/// `fallow health` runs type coupling from config only when no section is
/// selected (`health_type_coupling_is_default_section` in the CLI).
fn reject_health_config_type_aware(options: &ComplexityOptions) -> ProgrammaticResult<()> {
    if options.css || crate::derive_complexity_options(options).any_section {
        return Ok(());
    }
    let root = crate::analysis_context::resolve_analysis_root(options.analysis.root.as_deref())?;
    crate::analysis_context::validate_analysis_config_path(
        options.analysis.config_path.as_deref(),
    )?;
    type_aware_config::reject_config_type_aware_at(
        &options.analysis.type_aware,
        type_aware_config::ConfigLocation {
            root: &root,
            config_path: options.analysis.config_path.as_deref(),
            allow_remote_extends: options.analysis.allow_remote_extends,
        },
        type_aware_config::TypeAwareCommand::Analysis,
    )
}

fn run_validated_complexity(
    options: &ComplexityOptions,
    runner: &impl ProgrammaticHealthRunner,
) -> ProgrammaticResult<HealthProgrammaticOutput> {
    crate::analysis_context::ensure_options_not_cancelled(&options.analysis, "health analysis")?;
    Ok(assemble_health_programmatic_output(
        options,
        runner.run_programmatic_health(options)?,
    ))
}

fn assemble_health_programmatic_output(
    options: &ComplexityOptions,
    run: ProgrammaticHealthRun,
) -> HealthProgrammaticOutput {
    let ProgrammaticHealthRun {
        analysis,
        workspace_diagnostics,
        next_step_facts,
        telemetry_analysis_run_id,
        request_outcomes,
    } = run;
    let root = analysis.root.clone();
    let next_steps =
        fallow_output::build_health_next_steps(fallow_output::build_health_next_steps_input(
            &analysis.report,
            next_step_facts.suggestions_enabled,
            next_step_facts.offer_setup,
            next_step_facts.impact_digest,
            next_step_facts.audit_changed,
            None,
        ));
    HealthProgrammaticOutput {
        report: analysis.report,
        grouping: analysis.grouping,
        root,
        elapsed: analysis.elapsed,
        explain: options.analysis.explain,
        workspace_diagnostics,
        next_steps,
        telemetry_analysis_run_id,
        request_outcomes,
    }
}

/// Alias for [`run_complexity_with_runner`] with a product-oriented name.
///
/// # Errors
///
/// Returns the same structured errors as [`run_complexity_with_runner`].
pub fn run_health_with_runner(
    options: &ComplexityOptions,
    runner: &impl ProgrammaticHealthRunner,
) -> ProgrammaticResult<HealthProgrammaticOutput> {
    run_complexity_with_runner(options, runner)
}

#[cfg(test)]
mod cancellation_tests;
#[cfg(test)]
mod tests;