cache-lens 0.1.0

A static analyzer that detects cache-unfriendly Array-of-Structures (AoS) usage in Rust and suggests Structure-of-Arrays (SoA) refactors.
use std::io::IsTerminal;

use crate::model::{Finding, Severity};

const RESET: &str = "\x1b[0m";
const BOLD: &str = "\x1b[1m";
const DIM: &str = "\x1b[2m";
const RED: &str = "\x1b[31m";
const YELLOW: &str = "\x1b[33m";
const GREEN: &str = "\x1b[32m";
const CYAN: &str = "\x1b[36m";

fn c(enabled: bool, code: &str, text: &str) -> String {
    if enabled {
        format!("{code}{text}{RESET}")
    } else {
        text.to_string()
    }
}

pub fn print_human_report(findings: &[Finding], files_scanned: usize) {
    let color = std::io::stdout().is_terminal();

    if findings.is_empty() {
        println!(
            "{}",
            c(
                color,
                GREEN,
                &format!(
                    "cache-lens: no AoS cache-locality issues found across {files_scanned} file(s)."
                )
            )
        );
        return;
    }

    println!(
        "{}",
        c(
            color,
            BOLD,
            &format!(
                "cache-lens found {} potential AoS\u{2192}SoA opportunit{} across {} file(s):",
                findings.len(),
                if findings.len() == 1 { "y" } else { "ies" },
                files_scanned
            )
        )
    );
    println!();

    for finding in findings {
        let sev_color = if finding.severity == Severity::High {
            RED
        } else {
            YELLOW
        };
        println!("{}", c(color, DIM, &"\u{2500}".repeat(78)));
        println!(
            "{} {}:{}",
            c(color, sev_color, &format!("[{}]", finding.severity)),
            finding.file,
            finding.line
        );
        println!(
            "  {}",
            c(
                color,
                BOLD,
                &format!(
                    "struct `{}` ({} fields, defined at line {}) in loop `{}`",
                    finding.struct_name,
                    finding.total_fields,
                    finding.struct_def_line,
                    finding.loop_kind
                )
            )
        );
        println!(
            "  Loop variable `{}` over `{}` \u{2014} {}/{} fields touched (~{:.0}% of the struct's bytes are actually used per iteration)",
            finding.loop_var,
            finding.collection_expr,
            finding.hot_fields.len(),
            finding.total_fields,
            finding.byte_ratio * 100.0
        );
        println!();

        println!("  {}", c(color, GREEN, "Hot fields (touched in the loop):"));
        for hf in &finding.hot_fields {
            println!(
                "    {} {:<14} {:<12} {} read(s), {} write(s), ~{}B",
                c(color, GREEN, "\u{2713}"),
                hf.name,
                hf.ty,
                hf.reads,
                hf.writes,
                hf.approx_size_bytes
            );
        }
        println!();

        println!(
            "  {}",
            c(
                color,
                RED,
                "Cold fields (never touched \u{2014} dead weight on every cache line):"
            )
        );
        for cf in &finding.cold_fields {
            println!(
                "    {} {:<14} {:<12} ~{}B",
                c(color, RED, "\u{2717}"),
                cf.name,
                cf.ty,
                cf.approx_size_bytes
            );
        }
        println!();

        println!(
            "  {}",
            c(
                color,
                CYAN,
                "Suggested refactor \u{2014} Structure of Arrays:"
            )
        );
        for line in finding.soa_suggestion.lines() {
            println!("    {line}");
        }
        println!();

        println!(
            "  {}",
            c(
                color,
                DIM,
                "Alternative \u{2014} let the `soa-derive` crate generate the container:"
            )
        );
        for line in finding.soa_derive_suggestion.lines() {
            println!("    {line}");
        }
        println!();
    }

    println!("{}", c(color, DIM, &"\u{2500}".repeat(78)));
    let high = findings
        .iter()
        .filter(|f| f.severity == Severity::High)
        .count();
    let medium = findings.len() - high;
    println!(
        "cache-lens: {} finding(s) ({} high, {} medium) across {} file(s) scanned.",
        findings.len(),
        high,
        medium,
        files_scanned
    );
}