fallow_api/

runtime_output.rs

//! Typed programmatic runtime outputs and shared output-contract serializers.

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

pub use fallow_output::HEALTH_SCHEMA_VERSION;
use fallow_output::{
    CheckOutput, DupesOutput, FeatureFlagFinding, FeatureFlagsOutput as FeatureFlagsOutputContract,
    GroupByMode, HealthGroup, HealthGrouping, HealthJsonOutputInput, HealthOutputInput,
    HealthReport, health_meta,
};
use fallow_types::output::NextStep;
use fallow_types::output_dead_code::{
    BoundaryCallViolationFinding, BoundaryCoverageViolationFinding, BoundaryViolationFinding,
    CircularDependencyFinding,
};
use fallow_types::results::AnalysisResults;
use fallow_types::workspace::WorkspaceDiagnostic;
use rustc_hash::FxHashSet;

use crate::{AuditAttribution, AuditSummary, AuditVerdict};
use crate::{CloneFamilyFinding, CloneGroupFinding, DupesReportPayload, DuplicationGroup};

/// Concrete dead-code output contract returned by typed programmatic runs.
pub type DeadCodeOutput = CheckOutput;

/// Concrete circular-dependency output contract returned by typed runs.
pub type CircularDependenciesOutput = CheckOutput;

/// Concrete boundary-family output contract returned by typed runs.
pub type BoundaryViolationsOutput = CheckOutput;

/// Concrete `fallow architecture` output contract returned by typed runs.
pub type ArchitectureOutput = CheckOutput;

/// Concrete duplication output contract returned by typed programmatic runs.
pub type DuplicationOutput = DupesOutput<DupesReportPayload, DuplicationGroup>;

/// Concrete feature-flag output contract returned by typed programmatic runs.
pub type FeatureFlagsOutput = FeatureFlagsOutputContract;

/// Concrete export trace output returned by typed programmatic runs.
pub type TraceExportOutput = fallow_types::trace::ExportTrace;

/// Concrete class / enum / store member trace output (the `trace_export`
/// fallback when the name is a member rather than a top-level export). See
/// issue #1744.
pub type TraceClassMemberOutput = fallow_types::trace::ClassMemberTrace;

/// The `trace_export` target: either a top-level export or (fallback) a class /
/// enum / store member declared on one. Serialized untagged so the export shape
/// stays byte-identical to the historical contract and the member shape matches
/// the CLI's member trace; consumers distinguish by the presence of
/// `export_name` (export) vs `member_name` / `owner_export` (member).
#[derive(Debug, serde::Serialize)]
#[serde(untagged)]
pub enum TraceExportTargetOutput {
    /// A top-level export trace.
    Export(TraceExportOutput),
    /// A class / enum / store member trace.
    Member(TraceClassMemberOutput),
}

/// Concrete file trace output returned by typed programmatic runs.
pub type TraceFileOutput = fallow_types::trace::FileTrace;

/// Concrete dependency trace output returned by typed programmatic runs.
pub type TraceDependencyOutput = fallow_types::trace::DependencyTrace;

/// Concrete import-path trace output returned by typed programmatic runs.
pub type TraceImportPathOutput = fallow_types::trace::ImportPathTrace;

/// Concrete duplicate-code trace output returned by typed programmatic runs.
pub type TraceCloneOutput = fallow_types::trace::CloneTrace;

/// Concrete stack-trace resolution returned by typed programmatic runs.
pub type TraceErrorOutput = fallow_types::trace_error::ErrorTrace;

/// Inputs for serializing health JSON output through the API boundary.
pub struct HealthJsonReportInput<'a> {
    /// Every gate this run evaluated, absent when it evaluated none. The
    /// programmatic route runs no CLI-layer gate and leaves this `None`.
    pub gate_outcomes: Option<fallow_output::GateOutcomes>,
    /// Every narrowing or shaping request this run received, absent when it
    /// was asked for nothing. The programmatic route resolves no CLI flag and
    /// leaves this `None`; an entry whose `status` is not `applied` means the
    /// report is wider than what was asked for.
    pub request_outcomes: Option<fallow_output::RequestOutcomes>,
    /// Typed health report to serialize.
    pub report: HealthReport,
    /// Project root; its prefix is stripped from every path in the output.
    pub root: &'a Path,
    /// Analysis wall time, emitted as `elapsed_ms`.
    pub elapsed: std::time::Duration,
    /// Emit explain metadata under `meta`.
    pub explain: bool,
    /// Type-aware pass metadata merged into `meta` even when `explain` is
    /// off.
    pub type_aware: Option<fallow_types::envelope::TypeAwareMeta>,
    /// Grouping axis recorded as `grouped_by`; `None` when ungrouped.
    pub grouped_by: Option<GroupByMode>,
    /// Precomputed group buckets matching `grouped_by`.
    pub groups: Option<Vec<HealthGroup>>,
    /// The `--group` selector patterns, when the run kept only some groups.
    pub group_filter: Option<Vec<String>>,
    /// Non-fatal per-file diagnostics collected during the workspace walk.
    pub workspace_diagnostics: Vec<WorkspaceDiagnostic>,
    /// Suggested follow-up commands for the consumer.
    pub next_steps: Vec<NextStep>,
    /// Analysis run id stamped into telemetry metadata when present.
    pub telemetry_analysis_run_id: Option<&'a str>,
}

/// Typed programmatic combined output before JSON serialization.
#[derive(Debug, Clone)]
pub struct CombinedProgrammaticOutput {
    /// Dead-code section; `None` when the run skipped it.
    pub dead_code: Option<DeadCodeProgrammaticOutput>,
    /// Duplication section; `None` when the run skipped it.
    pub duplication: Option<DuplicationProgrammaticOutput>,
    /// Health section; `None` when the run skipped it.
    pub health: Option<HealthProgrammaticOutput>,
    /// Project root used when serializing stable JSON paths.
    pub root: PathBuf,
    /// Total wall time across sections, emitted as the root `elapsed_ms`.
    pub elapsed: std::time::Duration,
    /// Emit per-section explain metadata when serialized.
    pub explain: bool,
    /// Suggested follow-up commands for the consumer.
    pub next_steps: Vec<NextStep>,
    /// 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, emitted at the
    /// envelope root as `request_outcomes`, the only carrier on the combined
    /// envelope.
    pub request_outcomes: Option<fallow_output::RequestOutcomes>,
}

/// Typed programmatic dead-code output before JSON serialization.
///
/// This is the API boundary embedders should use when they need access to the
/// typed engine/output result. Protocol surfaces serialize it explicitly at
/// their JSON boundary.
#[derive(Debug, Clone)]
pub struct DeadCodeProgrammaticOutput {
    /// Typed dead-code envelope produced by the run.
    pub output: DeadCodeOutput,
    /// Project root used when serializing stable JSON paths.
    pub root: PathBuf,
    /// Whether duplicate-export findings can be auto-fixed through config;
    /// propagated onto their fix actions when serialized.
    pub config_fixable: bool,
    /// Analysis run id stamped into telemetry metadata when present.
    pub telemetry_analysis_run_id: Option<String>,
}

impl DeadCodeProgrammaticOutput {
    /// Full typed dead-code issue arrays retained by this run.
    #[must_use]
    pub fn results(&self) -> &AnalysisResults {
        &self.output.results
    }

    /// Project-relative root used when serializing stable JSON paths.
    #[must_use]
    pub fn root(&self) -> &Path {
        &self.root
    }
}

/// Typed programmatic circular-dependency output before JSON serialization.
///
/// The wire envelope stays the dead-code/check contract, but the Rust API
/// surface is family-specific so embedders do not have to treat this as a
/// generic dead-code run.
#[derive(Debug, Clone)]
pub struct CircularDependenciesProgrammaticOutput {
    /// Typed check envelope scoped to circular-dependency findings.
    pub output: CircularDependenciesOutput,
    /// Project root used when serializing stable JSON paths.
    pub root: PathBuf,
    /// Analysis run id stamped into telemetry metadata when present.
    pub telemetry_analysis_run_id: Option<String>,
}

impl CircularDependenciesProgrammaticOutput {
    /// Full typed issue arrays retained by this family run.
    #[must_use]
    pub fn results(&self) -> &AnalysisResults {
        &self.output.results
    }

    /// The circular dependency findings retained by this family run.
    #[must_use]
    pub fn circular_dependencies(&self) -> &[CircularDependencyFinding] {
        &self.output.results.circular_dependencies
    }
}

impl From<DeadCodeProgrammaticOutput> for CircularDependenciesProgrammaticOutput {
    fn from(value: DeadCodeProgrammaticOutput) -> Self {
        Self {
            output: value.output,
            root: value.root,
            telemetry_analysis_run_id: value.telemetry_analysis_run_id,
        }
    }
}

/// Typed programmatic `fallow architecture` output before JSON serialization.
///
/// The body is the dead-code body. The JSON envelope has
/// `kind: "architecture"` and its own `schema_version`.
#[derive(Debug, Clone)]
pub struct ArchitectureProgrammaticOutput {
    /// Typed check envelope scoped to the architecture findings.
    pub output: ArchitectureOutput,
    /// Project root used when serializing stable JSON paths.
    pub root: PathBuf,
    /// Analysis run id stamped into telemetry metadata when present.
    pub telemetry_analysis_run_id: Option<String>,
}

impl ArchitectureProgrammaticOutput {
    /// Full typed issue arrays retained by this run.
    #[must_use]
    pub fn results(&self) -> &AnalysisResults {
        &self.output.results
    }
}

impl From<DeadCodeProgrammaticOutput> for ArchitectureProgrammaticOutput {
    fn from(value: DeadCodeProgrammaticOutput) -> Self {
        Self {
            output: value.output,
            root: value.root,
            telemetry_analysis_run_id: value.telemetry_analysis_run_id,
        }
    }
}

/// Typed programmatic boundary-family output before JSON serialization.
///
/// This covers banned imports, boundary coverage, and forbidden call findings
/// while preserving the stable dead-code/check JSON envelope.
#[derive(Debug, Clone)]
pub struct BoundaryViolationsProgrammaticOutput {
    /// Typed check envelope scoped to boundary-family findings.
    pub output: BoundaryViolationsOutput,
    /// Project root used when serializing stable JSON paths.
    pub root: PathBuf,
    /// Analysis run id stamped into telemetry metadata when present.
    pub telemetry_analysis_run_id: Option<String>,
}

impl BoundaryViolationsProgrammaticOutput {
    /// Full typed issue arrays retained by this family run.
    #[must_use]
    pub fn results(&self) -> &AnalysisResults {
        &self.output.results
    }

    /// Banned import boundary findings retained by this family run.
    #[must_use]
    pub fn boundary_violations(&self) -> &[BoundaryViolationFinding] {
        &self.output.results.boundary_violations
    }

    /// Boundary coverage findings retained by this family run.
    #[must_use]
    pub fn boundary_coverage_violations(&self) -> &[BoundaryCoverageViolationFinding] {
        &self.output.results.boundary_coverage_violations
    }

    /// Forbidden call findings retained by this family run.
    #[must_use]
    pub fn boundary_call_violations(&self) -> &[BoundaryCallViolationFinding] {
        &self.output.results.boundary_call_violations
    }
}

impl From<DeadCodeProgrammaticOutput> for BoundaryViolationsProgrammaticOutput {
    fn from(value: DeadCodeProgrammaticOutput) -> Self {
        Self {
            output: value.output,
            root: value.root,
            telemetry_analysis_run_id: value.telemetry_analysis_run_id,
        }
    }
}

/// Typed programmatic duplication output before JSON serialization.
#[derive(Debug, Clone)]
pub struct DuplicationProgrammaticOutput {
    /// Typed duplication envelope produced by the run.
    pub output: DuplicationOutput,
    /// Project root used when serializing stable JSON paths.
    pub root: PathBuf,
    /// Maximum allowed duplication percentage from the resolved config;
    /// 0 disables the percentage gate.
    pub threshold: f64,
    /// Analysis run id stamped into telemetry metadata when present.
    pub telemetry_analysis_run_id: Option<String>,
}

impl DuplicationProgrammaticOutput {
    /// Typed duplication report payload retained by this run.
    #[must_use]
    pub const fn report(&self) -> &DupesReportPayload {
        &self.output.report
    }

    /// Clone groups retained by this run, with typed actions and fingerprints.
    #[must_use]
    pub fn clone_groups(&self) -> &[CloneGroupFinding] {
        &self.output.report.clone_groups
    }

    /// Clone families retained by this run, with nested typed clone groups.
    #[must_use]
    pub fn clone_families(&self) -> &[CloneFamilyFinding] {
        &self.output.report.clone_families
    }

    /// Grouped duplication buckets when a grouping mode was used.
    #[must_use]
    pub fn groups(&self) -> Option<&[DuplicationGroup]> {
        self.output.groups.as_deref()
    }
}

/// Typed programmatic feature-flag output before JSON serialization.
#[derive(Debug, Clone)]
pub struct FeatureFlagsProgrammaticOutput {
    /// Typed feature-flag envelope produced by the run.
    pub output: FeatureFlagsOutput,
    /// Analysis run id stamped into telemetry metadata when present.
    pub telemetry_analysis_run_id: Option<String>,
}

impl FeatureFlagsProgrammaticOutput {
    /// Feature flag findings retained by this run.
    #[must_use]
    pub fn feature_flags(&self) -> &[FeatureFlagFinding] {
        &self.output.feature_flags
    }

    /// Number of feature flags retained by this run after scoping and limits.
    #[must_use]
    pub const fn total_flags(&self) -> usize {
        self.output.total_flags
    }
}

/// Typed programmatic export-trace output before JSON serialization. Carries
/// either an export trace or (fallback) a class / enum / store member trace.
#[derive(Debug)]
pub struct TraceExportProgrammaticOutput {
    /// Typed export-or-member trace produced by the run.
    pub output: TraceExportTargetOutput,
}

impl TraceExportProgrammaticOutput {
    /// Typed export-or-member trace retained by this run.
    #[must_use]
    pub const fn trace(&self) -> &TraceExportTargetOutput {
        &self.output
    }

    /// The export trace, when the target resolved to a top-level export.
    #[must_use]
    pub const fn as_export(&self) -> Option<&TraceExportOutput> {
        match &self.output {
            TraceExportTargetOutput::Export(export) => Some(export),
            TraceExportTargetOutput::Member(_) => None,
        }
    }

    /// The member trace, when the target resolved to a class / enum / store
    /// member (the `trace_export` fallback, issue #1744).
    #[must_use]
    pub const fn as_member(&self) -> Option<&TraceClassMemberOutput> {
        match &self.output {
            TraceExportTargetOutput::Member(member) => Some(member),
            TraceExportTargetOutput::Export(_) => None,
        }
    }
}

/// Typed programmatic file-trace output before JSON serialization.
#[derive(Debug)]
pub struct TraceFileProgrammaticOutput {
    /// Typed file trace produced by the run.
    pub output: TraceFileOutput,
}

impl TraceFileProgrammaticOutput {
    /// Typed file trace retained by this run.
    #[must_use]
    pub const fn trace(&self) -> &TraceFileOutput {
        &self.output
    }
}

/// Typed programmatic import-path-trace output before JSON serialization.
#[derive(Debug)]
pub struct TraceImportPathProgrammaticOutput {
    /// Typed import-path trace produced by the run.
    pub output: TraceImportPathOutput,
}

impl TraceImportPathProgrammaticOutput {
    /// Typed import-path trace retained by this run.
    #[must_use]
    pub const fn trace(&self) -> &TraceImportPathOutput {
        &self.output
    }
}

/// Typed programmatic dependency-trace output before JSON serialization.
#[derive(Debug)]
pub struct TraceDependencyProgrammaticOutput {
    /// Typed dependency trace produced by the run.
    pub output: TraceDependencyOutput,
}

impl TraceDependencyProgrammaticOutput {
    /// Typed dependency trace retained by this run.
    #[must_use]
    pub const fn trace(&self) -> &TraceDependencyOutput {
        &self.output
    }
}

/// Typed programmatic stack-trace resolution before JSON serialization.
#[derive(Debug)]
pub struct TraceErrorProgrammaticOutput {
    /// Typed stack-trace resolution produced by the run.
    pub output: TraceErrorOutput,
}

impl TraceErrorProgrammaticOutput {
    /// Typed stack-trace resolution retained by this run.
    #[must_use]
    pub const fn trace(&self) -> &TraceErrorOutput {
        &self.output
    }
}

/// Typed programmatic duplicate-code trace output before JSON serialization.
#[derive(Debug)]
pub struct TraceCloneProgrammaticOutput {
    /// Typed clone trace produced by the run.
    pub output: TraceCloneOutput,
}

impl TraceCloneProgrammaticOutput {
    /// Typed clone trace retained by this run.
    #[must_use]
    pub const fn trace(&self) -> &TraceCloneOutput {
        &self.output
    }
}

/// Typed programmatic health / complexity output before JSON serialization.
#[derive(Debug, Clone)]
pub struct HealthProgrammaticOutput {
    /// Typed health report produced by the run.
    pub report: HealthReport,
    /// Grouped findings when a grouping mode was requested.
    pub grouping: Option<HealthGrouping>,
    /// Project root used when serializing stable JSON paths.
    pub root: PathBuf,
    /// Analysis wall time, emitted as `elapsed_ms` when serialized.
    pub elapsed: std::time::Duration,
    /// Emit explain metadata when serialized.
    pub explain: bool,
    /// Non-fatal per-file diagnostics collected during the workspace walk.
    pub workspace_diagnostics: Vec<WorkspaceDiagnostic>,
    /// Suggested follow-up commands for the consumer.
    pub next_steps: Vec<NextStep>,
    /// 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, emitted as the
    /// envelope's `request_outcomes`.
    pub request_outcomes: Option<fallow_output::RequestOutcomes>,
}

/// Typed programmatic audit output before JSON serialization.
#[derive(Debug, Clone)]
pub struct AuditProgrammaticOutput {
    /// Overall audit verdict.
    pub verdict: AuditVerdict,
    /// Per-category issue counts.
    pub summary: AuditSummary,
    /// New-vs-inherited counts and the configured gate.
    pub attribution: AuditAttribution,
    /// Number of changed files the audit analyzed.
    pub changed_files_count: usize,
    /// Git revision the audit compared against.
    pub base_ref: String,
    /// Human-readable description of how the base was chosen.
    pub base_description: Option<String>,
    /// Commit SHA of the analyzed head, when known.
    pub head_sha: Option<String>,
    /// Audit wall time, emitted as `elapsed_ms` when serialized.
    pub elapsed: std::time::Duration,
    /// Always `None` on the typed route. A skipped base means that the head
    /// keys stand in for the base, so every finding is inherited. It does not
    /// mean that no attribution ran.
    pub base_snapshot_skipped: Option<bool>,
    /// Attribution key sets of the base run, scoped to the changed files and
    /// the pre-rename paths, with the rename remap and the dependency scope
    /// applied. When the head run stands in for the base, it holds the head
    /// keys. `None` when the gate needs no base or when the changeset is
    /// empty.
    pub base_snapshot: Option<AuditProgrammaticKeySnapshot>,
    /// Dead-code section; `None` when the audit skipped it.
    pub dead_code: Option<DeadCodeProgrammaticOutput>,
    /// Duplication section; `None` when the audit skipped it.
    pub duplication: Option<DuplicationProgrammaticOutput>,
    /// Complexity (health) section; `None` when the audit skipped it.
    pub complexity: Option<HealthProgrammaticOutput>,
    /// Diff-risk findings. Every one is introduced by the change.
    pub diff_risk: fallow_output::DiffRiskReport,
    /// Suggested follow-up commands for the consumer.
    pub next_steps: Vec<NextStep>,
    /// Analysis run id stamped into telemetry metadata when present.
    pub telemetry_analysis_run_id: Option<String>,
}

/// Stable audit key snapshot used to classify introduced vs inherited findings.
#[derive(Debug, Clone, Default)]
pub struct AuditProgrammaticKeySnapshot {
    /// Base-run dead-code attribution keys.
    pub dead_code: FxHashSet<String>,
    /// Base-run complexity attribution keys.
    pub health: FxHashSet<String>,
    /// Base-run duplication group attribution keys.
    pub dupes: FxHashSet<String>,
}

/// Typed programmatic decision-surface output before JSON serialization.
#[derive(Debug, Clone)]
pub struct DecisionSurfaceProgrammaticOutput {
    /// Typed decision surface produced by the run.
    pub surface: fallow_output::DecisionSurface,
    /// Analysis wall time, emitted as `elapsed_ms` when serialized.
    pub elapsed: std::time::Duration,
    /// Analysis run id stamped into telemetry metadata when present.
    pub telemetry_analysis_run_id: Option<String>,
}

/// Serialize a health / complexity report into the stable JSON output contract.
///
/// # Errors
///
/// Returns a serde error when the report cannot be converted to JSON.
pub fn serialize_health_report_json(
    input: HealthJsonReportInput<'_>,
) -> Result<serde_json::Value, serde_json::Error> {
    let root_prefix = format!("{}/", input.root.display());
    let meta = match (input.explain, input.type_aware) {
        (false, None) => None,
        (true, None) => Some(health_meta()),
        (false, Some(type_aware)) => Some(fallow_types::envelope::Meta {
            type_aware: Some(type_aware),
            ..fallow_types::envelope::Meta::default()
        }),
        (true, Some(type_aware)) => {
            let mut meta = health_meta();
            meta.type_aware = Some(type_aware);
            Some(meta)
        }
    };
    fallow_output::serialize_health_json_output(HealthJsonOutputInput {
        output: HealthOutputInput {
            gate_outcomes: input.gate_outcomes,
            request_outcomes: input.request_outcomes,
            schema_version: HEALTH_SCHEMA_VERSION,
            version: env!("CARGO_PKG_VERSION").to_string(),
            elapsed: input.elapsed,
            report: input.report,
            grouped_by: input.grouped_by,
            groups: input.groups,
            group_filter: input.group_filter,
            meta,
            workspace_diagnostics: input.workspace_diagnostics,
            next_steps: input.next_steps,
        },
        root_prefix: Some(&root_prefix),
        analysis_run_id: input.telemetry_analysis_run_id,
    })
}