voom 0.14.1

Fast, safe, parallel build-artifact pruning across every major language ecosystem
Documentation
//! The footer: what the run reclaimed, where the time went, and what it could not say.
//!
//! Split out of the renderer when it crossed the module cap, along the seam the human report
//! already has — the artifact table above and the summary below it answer different questions and
//! share nothing but the gutter.

use std::collections::BTreeMap;
use std::io;

use humansize::{DECIMAL, format_size};
use owo_colors::{OwoColorize, Style};

use super::table::GUTTER;
use super::{HumanOptions, MAX_ECOSYSTEMS_NAMED, UNANCHORED, palette};
use crate::delete::Outcome;
use crate::report::RunResult;

/// What was reclaimed, per ecosystem, biggest first.
///
/// A `$HOME` sweep prints a line per artifact and there is no honest way to print fewer: the
/// report is the only record of a destructive act (ADR 0006), so eliding removals is not on the
/// table. What the footer can do is say what the list adds up to, which makes the shape of a
/// 174-line run legible without reading all of it.
///
/// Sorted by bytes because the question this answers is where the space went; the id breaks
/// ties so two runs over an unchanged tree still render identically.
pub(super) fn reclaimed_by_ecosystem(result: &RunResult) -> Vec<(&'static str, usize, u64)> {
    let mut totals: BTreeMap<&'static str, (usize, u64)> = BTreeMap::new();
    for entry in &result.entries {
        let bytes = entry.reclaimed_bytes();
        if bytes == 0 && !entry.outcome.is_reclaimed() {
            continue;
        }
        let slot = totals.entry(entry.ecosystem().unwrap_or(UNANCHORED)).or_default();
        // Counted only when the artifact is actually gone, and totalled whether or not — which
        // is exactly how the headline splits `reclaimed` from `bytes`. Reading the same accessor
        // is what stops the two from drifting apart again.
        if entry.outcome.is_reclaimed() {
            slot.0 += 1;
        }
        slot.1 += bytes;
    }
    let mut rows: Vec<_> = totals
        .into_iter()
        .map(|(id, (count, bytes))| (id, count, bytes))
        .collect();
    rows.sort_by(|left, right| right.2.cmp(&left.2).then_with(|| left.0.cmp(right.0)));
    rows
}

/// The breakdown line, or `None` when there is only one ecosystem and it would repeat the
/// headline it sits under.
pub(super) fn ecosystem_summary(result: &RunResult) -> Option<String> {
    let rows = reclaimed_by_ecosystem(result);
    if rows.len() < 2 {
        return None;
    }
    let named: Vec<String> = rows
        .iter()
        .take(MAX_ECOSYSTEMS_NAMED)
        .map(|(id, count, bytes)| format!("{id} {} ({count})", format_size(*bytes, DECIMAL)))
        .collect();
    let line = named.join(", ");
    match rows.len().saturating_sub(MAX_ECOSYSTEMS_NAMED) {
        0 => Some(line),
        hidden => Some(format!("{line}, +{hidden} more")),
    }
}

/// Bytes left behind by every partial removal in the run.
fn remaining_bytes(result: &RunResult) -> u64 {
    result
        .entries
        .iter()
        .filter_map(|entry| match &entry.outcome {
            Outcome::PartiallyRemoved { remaining, .. } => Some(*remaining),
            _ => None,
        })
        .sum()
}

/// The plural of `noun` for `count`. Every noun the footer uses takes a plain `s`.
fn plural(count: usize, noun: &str) -> String {
    if count == 1 {
        noun.to_owned()
    } else {
        format!("{noun}s")
    }
}

pub(super) fn write_footer(
    result: &RunResult,
    options: HumanOptions,
    wrote_body: bool,
    out: &mut impl io::Write,
) -> io::Result<()> {
    if wrote_body {
        writeln!(out)?;
    }
    write_headline(result, out)?;
    write_breakdown(result, out)?;
    write_skipped_and_inaccessible(result, options, out)?;
    write_removal_notices(result, out)?;
    write_failure_notices(result, out)?;
    if result.dry_run {
        writeln!(out, "{}", "Dry run — nothing was removed.".style(palette::quiet()))?;
    }
    Ok(())
}

/// One gutter-indented footer line in `style`.
fn write_line(out: &mut impl io::Write, text: &str, style: Style) -> io::Result<()> {
    writeln!(out, "{GUTTER}{}", text.style(style))
}

fn write_headline(result: &RunResult, out: &mut impl io::Write) -> io::Result<()> {
    let totals = result.totals();
    let verb = if result.dry_run { "reclaimable" } else { "reclaimed" };
    writeln!(
        out,
        "{} {}, {} {verb} in {:.2?}",
        totals.reclaimed.bold(),
        plural(totals.reclaimed, "artifact"),
        format_size(totals.bytes, DECIMAL).bold(),
        result.timings.total
    )
}

fn write_breakdown(result: &RunResult, out: &mut impl io::Write) -> io::Result<()> {
    write_line(out, &stage_breakdown(result), palette::quiet())?;
    if let Some(summary) = ecosystem_summary(result) {
        write_line(out, &summary, palette::quiet())?;
    }
    Ok(())
}

// Totals of different kinds get their own lines. On the one line they used to share, the
// number that matters — what was reclaimed — was the hardest of the four to find.
fn write_skipped_and_inaccessible(
    result: &RunResult,
    options: HumanOptions,
    out: &mut impl io::Write,
) -> io::Result<()> {
    let totals = result.totals();
    if totals.skipped > 0 {
        let text = format!("{} {} skipped", totals.skipped, plural(totals.skipped, "candidate"));
        write!(out, "{GUTTER}{}", text.style(palette::quiet()))?;
        if options.verbose {
            writeln!(out)?;
        } else {
            writeln!(out, "{GUTTER}{}", "--verbose for why".style(palette::quiet()))?;
        }
    }
    let inaccessible = result.failures.iter().filter(|failure| failure.inaccessible).count();
    if inaccessible > 0 {
        // One line, never a list: macOS protects a hundred-odd directories under `~/Library`
        // that no user action can open, and each is a line nobody can act on. `-v` lists them.
        let text = format!(
            "{inaccessible} {} inaccessible (permission denied){}",
            if inaccessible == 1 { "directory" } else { "directories" },
            if options.verbose {
                ""
            } else {
                " — --verbose lists them"
            },
        );
        write_line(out, &text, palette::quiet())?;
    }
    Ok(())
}

/// The lines about how the removals that succeeded were carried out.
fn write_removal_notices(result: &RunResult, out: &mut impl io::Write) -> io::Result<()> {
    let totals = result.totals();
    if totals.detached > 0 {
        // The headline counts these as reclaimed, and they are gone from the tree; the space is
        // not back until the reaper has freed them, and that is the reader's to know.
        let text = format!(
            "{} {} detached into the trash — the space returns as the background reaper frees them (`voom reap` waits)",
            totals.detached,
            plural(totals.detached, "artifact"),
        );
        write_line(out, &text, palette::quiet())?;
    }
    if totals.refused > 0 {
        let text = format!(
            "{} {} refused by a safety rail",
            totals.refused,
            plural(totals.refused, "artifact")
        );
        write_line(out, &text, palette::refused())?;
    }
    Ok(())
}

/// The lines about artifacts that were not, or not fully, removed or measured.
fn write_failure_notices(result: &RunResult, out: &mut impl io::Write) -> io::Result<()> {
    let totals = result.totals();
    if totals.unmeasured > 0 {
        // The one number in this footer that is knowingly wrong, said out loud. Everything else
        // here is exact; presenting a lower bound in the same typeface without a word would make
        // the whole footer less trustworthy, not more.
        let text = format!(
            "{} {} could not be measured in full — a directory inside could not be read, so the total is a lower bound",
            totals.unmeasured,
            plural(totals.unmeasured, "artifact"),
        );
        write_line(out, &text, palette::failed())?;
    }
    if totals.dependencies > 0 {
        // Named outright rather than left inside the headline: ADR 0001 promised these would
        // never be removed, and its amendment made them reachable only by explicit opt-in. A
        // run that took one owes the reader the sentence.
        let noun = if totals.dependencies == 1 {
            "directory"
        } else {
            "directories"
        };
        let text = format!(
            "{} of them {} a dependency {noun} — a re-download, not build output",
            totals.dependencies,
            if totals.dependencies == 1 { "is" } else { "are" },
        );
        write_line(out, &text, palette::refused())?;
    }
    if totals.partial > 0 {
        // "counted above" is the whole point of the line: without it a reader who sees an
        // artifact still on disk has no way to know whether its bytes made it into the total.
        let text = format!(
            "{} {} partly removed: {} freed and counted above, {}",
            totals.partial,
            plural(totals.partial, "artifact"),
            format_size(totals.partial_bytes, DECIMAL),
            super::remaining_words(remaining_bytes(result)),
        );
        write_line(out, &text, palette::partial())?;
    }
    if totals.failed > 0 {
        let text = format!(
            "{} {} could not be removed",
            totals.failed,
            plural(totals.failed, "artifact")
        );
        write_line(out, &text, palette::failed())?;
    }
    Ok(())
}

/// Where the run's time actually went, stage by stage.
///
/// One number cannot be acted on: a sweep that spends nine seconds walking wants a different
/// fix from one that spends nine seconds sizing, and voom's headline claim is about how long it
/// takes. The stages are ADR 0001's pipeline, measured where each is called.
///
/// They deliberately do not sum to the headline. The residue — loading configuration,
/// normalizing roots, building the worker pool — is real but is not something a reader can do
/// anything about, and a footer line nobody can act on is noise.
fn stage_breakdown(result: &RunResult) -> String {
    let timings = &result.timings;
    format!(
        "scan {:.2?} · policy {:.2?} · size {:.2?} · {} {:.2?}{}",
        timings.scan,
        timings.policy,
        timings.size,
        // Under `--dry-run` the stage still runs — it is the same pipeline with the final step
        // withheld — so the number is real and near zero rather than absent. Naming it
        // "withheld" stops a reader reading that near-zero as a fast deletion.
        if result.dry_run { "withheld" } else { "delete" },
        timings.delete,
        // Only when it ran. A stage that was switched off is not a stage that took no time, and
        // printing `git 0ns` on every run of a machine without git says nothing.
        if timings.git.is_zero() {
            String::new()
        } else {
            format!(" · git {:.2?}", timings.git)
        },
    )
}