bat-cli 0.32.0

//! One frame per contract: where its storage actually lives, and who moves it.
//!
//! A contract's source says what it declares. It does not say what it *occupies* — the slots
//! a base contract took before it, which two variables share a slot, or that the dozen
//! `immutable`s reading like state are in the bytecode and occupy nothing. `YieldRouter`
//! declares four mutable variables and its slots 0, 1 and 2 belong to `TwoStepOwned` and to
//! the reentrancy guard.
//!
//! The slot numbers are **not computed here**. Packing, dynamic types, inherited layout and
//! ERC-7201 base-slot hashing are a week of work and wrong at the edges, and every Foundry
//! repo already ships the answer: `forge inspect <C> storage-layout --json`. This consumes it
//! and draws it next to the code it belongs to.
//!
//! What this tool adds on top of `forge` is the two things it cannot know: which source line
//! each slot is declared on, and which functions write it.

use colored::Colorize;
use error_stack::{Report, Result, ResultExt};

use crate::batbelt::evm::metadata::bat_metadata::{ContractMetadata, EvmBatMetadata};
use crate::batbelt::evm::miro::auto_deploy::{beside_cluster, below_everything, REFERENCE_FONT};
use crate::batbelt::evm::miro::EvmMiroError;
use crate::batbelt::miro::client::{ArrowEnd, ConnectorStroke, ConnectorStyle, MiroClient};
use crate::batbelt::path::BatFolder;
use crate::batbelt::silicon;

/// Gap between two columns, and the margin around them, in board units.
/// Bounds for the gutter the arrows run through, and for the margin around the two captures.
/// Both are sized from the content — see `layout::breathing_room`.
const GUTTER_MIN: f64 = 300.0;
const GUTTER_MAX: f64 = 600.0;
const MARGIN_MIN: f64 = 120.0;
const MARGIN_MAX: f64 = 400.0;

pub struct StorageOptions {
    /// The contract whose storage to draw.
    pub contract: String,
    /// Print the table and stop, touching no board.
    pub dry_run: bool,
    /// Where to put the frame's RIGHT edge and its top, when the caller has already decided.
    ///
    /// A deploy opening a contract's column wants this layout immediately to the left of that
    /// column's first cluster. Left out — the standalone command — the frame finds its own
    /// spot beside the contract's cluster or below everything, and a column's own layout is
    /// not disturbed by it.
    pub anchor: Option<(f64, f64)>,
}

/// One entry of `forge`'s layout: a variable that occupies storage.
///
/// Serializable because it is cached in `BatMetadata.json`: asking the compiler costs a full
/// build when Foundry's own cache is cold, and the layout of source that does not change does
/// not change either.
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub(crate) struct Slot {
    pub(crate) slot: String,
    pub(crate) offset: u64,
    pub(crate) label: String,
    pub(crate) type_label: String,
    pub(crate) bytes: u64,
    /// The contract that DECLARED it. NOT forge's `contract` field, which names the
    /// compilation unit — it says `YieldRouter` for a slot `TwoStepOwned` declares, which is
    /// the one thing this column exists to tell you. Resolved from the metadata instead.
    pub(crate) declared_by: String,
    /// Where that declaration is, when it was found: its file and line.
    pub(crate) declared_at: Option<(String, usize)>,
}

/// A variable that reads like state and occupies no slot.
#[derive(Debug, Clone)]
struct Unstored {
    name: String,
    type_name: String,
    kind: &'static str,
    line: usize,
}

/// A function that writes one of the slots, and where.
#[derive(Debug, Clone)]
struct Writer {
    slot_label: String,
    function: String,
    path: String,
    line: usize,
    /// The lvalue as written, which is the field when the write goes through a pointer.
    lvalue: String,
}

pub async fn run(options: StorageOptions) -> Result<Option<String>, EvmMiroError> {
    // Timed out loud, like `map`: "it took a while" is not something to guess about.
    let started = std::time::Instant::now();
    let mut phase = started;
    let mut mark = |what: &str, since: &mut std::time::Instant| {
        println!("    {:>6.1}s  {what}", since.elapsed().as_secs_f64());
        *since = std::time::Instant::now();
    };
    let metadata = EvmBatMetadata::read_metadata().change_context(EvmMiroError)?;
    mark("reading the metadata", &mut phase);
    let prepared = prepare(&metadata, &options.contract)?;
    mark("the layout, forge and the two captures", &mut phase);
    for line in prepared.table.iter().chain(prepared.sidebar.iter()) {
        println!("{line}");
    }
    if options.dry_run {
        prepared.discard();
        return Ok(None);
    }

    let client = MiroClient::new_refreshed().await.change_context(EvmMiroError)?;
    mark("opening the Miro session", &mut phase);
    let (left, top) = match options.anchor {
        // The caller fixed it: this layout belongs to a group whose anchor is already placed,
        // and no scan of the board is needed to know where it goes.
        Some(spot) => spot,
        // On its own: beside this contract's cluster when it has one, below everything when
        // it does not. This is the ONLY path that has to read the board, and on a board of
        // hundreds of frames that read is the slowest thing the command does.
        None => {
            let board_frames = client.list_frames().await.change_context(EvmMiroError)?;
            match beside_cluster(
                &metadata,
                &prepared.contract,
                &board_frames,
                prepared.width,
                prepared.height,
            ) {
                Some((x, y)) => (x - prepared.width / 2.0, y - prepared.height / 2.0),
                None => below_everything(&board_frames),
            }
        }
    };

    mark("deciding where it goes", &mut phase);
    let drawn = draw(prepared, &client, left, top).await.map(Some);
    mark("drawing it", &mut phase);
    println!("    {:>6.1}s  in total", started.elapsed().as_secs_f64());
    drawn
}

/// Everything a storage frame needs, measured and rendered, with nothing on the board yet.
///
/// The split is what lets a deploy know how wide this frame will be BEFORE it draws anything:
/// a contract's group is anchored on a label as wide as its first row, and the row cannot be
/// measured if half of it only exists once it has been uploaded. It is also what makes "no
/// half-drawn group" true — if `forge` has no layout for this contract, that is known here,
/// before the first API call.
pub(crate) struct PreparedStorage {
    contract: String,
    /// Whose declarations the capture shows: this contract, or the base its slots come from.
    drawn_from: String,
    slots: Vec<Slot>,
    slot_rows: Vec<usize>,
    table: Vec<String>,
    sidebar: Vec<String>,
    declaration_line: usize,
    declarations: Vec<String>,
    table_png: Rendered,
    code_png: Rendered,
    /// Margin around the captures and gutter between them, both sized from the content.
    margin: f64,
    gutter: f64,
    /// How far down the table sits, so it hangs where its arrows point.
    table_offset: f64,
    pub(crate) width: f64,
    pub(crate) height: f64,
}

impl PreparedStorage {
    /// Throw away the renders without drawing them — a dry run, or a group that failed
    /// somewhere else before anything was uploaded.
    pub(crate) fn discard(&self) {
        let _ = std::fs::remove_file(&self.table_png.png_path);
        let _ = std::fs::remove_file(&self.code_png.png_path);
    }
}

/// How far down the table hangs so that its rows sit level with the lines they point at.
///
/// `travel` is, per arrow, how far its line is below its row when the table is at the top. One
/// offset serves every row, and the one that minimises the total vertical travel of a set of
/// arrows is the MEDIAN — not the mean, which a single slot declared far from the others drags,
/// and that is exactly the case here: one inherited-looking declaration among six adjacent ones.
/// Never negative: the table is not pushed above the frame to chase a row.
fn aligning_offset(mut travel: Vec<f64>) -> f64 {
    travel.sort_by(|a, b| a.partial_cmp(b).unwrap_or(std::cmp::Ordering::Equal));
    travel.get(travel.len() / 2).copied().unwrap_or(0.0).max(0.0)
}

/// Measure and render a contract's storage frame. Local: no client, no board.
pub(crate) fn prepare(
    metadata: &EvmBatMetadata,
    contract_name: &str,
) -> Result<PreparedStorage, EvmMiroError> {
    let contract = pick_contract(metadata, contract_name)?;

    let mut slots = forge_layout(&contract.name)?;
    attribute(metadata, contract, &mut slots);
    if slots.is_empty() {
        println!(
            "  {} {} occupies no storage slot at all",
            "note:".yellow(),
            contract.name
        );
    }
    let unstored = unstored_variables(metadata, contract);
    let writers = writers_of(metadata, contract, &slots);
    let (table, slot_rows) = slot_table(&contract.name, &slots, &writers);
    let sidebar = sidebar(&contract.name, &unstored);

    BatFolder::Figures.create_folder().change_context(EvmMiroError)?;
    let destination = BatFolder::Figures.get_path(true).change_context(EvmMiroError)?;

    // WHOSE declarations get captured. Normally the contract's own — but a thin wrapper over a
    // base (`contract Treasury is TwoStepOwned`) declares nothing and still has real slots, and
    // refusing to draw it made the whole group undeployable: a group is drawn whole or not at
    // all, so one missing capture took an owner-gated entry point with it.
    //
    // The slot TABLE already resolves an inherited slot to the contract that declares it, with
    // its file and line. The capture simply had nowhere else to look. So when this contract
    // declares nothing, the block drawn is the one of the base that declares its slots — the
    // one declaring the most of them, with the rest still named in the table.
    let declaring = declaring_contract(metadata, contract, &slots);
    let drawn_from = declaring.as_ref().unwrap_or(&contract.name).clone();
    let file_path = match &declaring {
        Some(base) => metadata
            .contracts
            .iter()
            .find(|other| &other.name == base)
            .map(|other| other.file_path.clone())
            .unwrap_or_else(|| contract.file_path.clone()),
        None => contract.file_path.clone(),
    };
    let source = std::fs::read_to_string(&file_path)
        .change_context(EvmMiroError)
        .attach_printable_lazy(|| format!("cannot read {file_path}"))?;
    let all: Vec<String> = source.lines().map(|line| line.to_string()).collect();
    // The DECLARATION BLOCK, not the file: from the contract's first state variable to its
    // last, whole and uncut. Rendering the file instead would be a 900-line image to point
    // seven arrows into, and the lines between the declarations are kept because they are
    // the comments that say what each one is for.
    let declares = metadata
        .contracts
        .iter()
        .find(|other| other.name == drawn_from)
        .unwrap_or(contract);
    let (first, last) = declaration_span(declares, all.len()).ok_or_else(|| {
        Report::new(EvmMiroError)
            .attach_printable(format!(
                "{} occupies no storage slot and declares no state variable, here or in a \
                 base, so there is no declaration block to draw beside its slot table",
                contract.name
            ))
            .attach(crate::Suggestion(
                "deploy a contract that holds state, or read this one's bases instead".to_string(),
            ))
    })?;
    if declaring.is_some() {
        println!(
            "  {} {} declares no state of its own — the block drawn is {}'s",
            "note:".yellow(),
            contract.name,
            drawn_from
        );
    }
    let declarations: Vec<String> = all[first - 1..last].to_vec();

    let table_png = render(
        &table,
        &destination,
        &format!("storage_{}_table", contract.name),
        0,
        &[],
    )?;
    let code_png = render(
        &declarations,
        &destination,
        &format!("storage_{}_code", contract.name),
        // The gutter carries the REAL file lines, so a number on the board is a number in
        // the editor. silicon numbers the FIRST rendered line with this value, so it is the
        // span's first line and not the one before it.
        first,
        &unstored_marks(&unstored),
    )?;

    // Two columns, not three. What occupies no slot used to be a list beside the code; it is
    // now marked ON the code, which is where the reader already is — a third column saying
    // the same thing is a second place to look.
    // Sized from the content: a fixed 400 around a four-line capture is half the frame in
    // air, which is what made a small deployment read as three mostly-empty boxes.
    let tallest = code_png.height.max(table_png.height);
    let margin = crate::batbelt::miro::layout::breathing_room(tallest, MARGIN_MIN, MARGIN_MAX);
    // Wide enough for every arrow to have a lane of its own at the full pitch. Sized from the
    // content alone, thirteen arrows shared six hundred units and the bundle in the middle was
    // unreadable — the gutter is where the arrows live, so what has to fit in it is what
    // decides how wide it is.
    let lanes = slots
        .iter()
        .filter(|slot| {
            slot.declared_by == drawn_from
                && slot
                    .declared_at
                    .as_ref()
                    .is_some_and(|(_, line)| (first..first + declarations.len()).contains(line))
        })
        .count();
    let gutter = crate::batbelt::miro::layout::breathing_room(
        code_png.width + table_png.width,
        GUTTER_MIN,
        GUTTER_MAX,
    )
    .max(crate::batbelt::miro::layout::gutter_for(lanes));

    // The table hangs where its arrows point, not at the top — and "where they point" is each
    // ROW against its own declaration, not the block against the block.
    //
    // Pinned to the top, every arrow ran from the bottom of a 176-line capture up to a table
    // that ended long before. Centring the table on the mean of the lines it describes fixed
    // the direction and not the shape: in `YieldRouter` the seven declarations sit in the last
    // six lines of a hundred-line capture, so the whole table was dragged to the bottom of the
    // frame and the arrows still ran as long diagonals.
    //
    // What makes an arrow short is its own row being level with its own line. One offset has
    // to serve every row, so take the one that minimises the total vertical travel: the MEDIAN
    // of (line − row). The median and not the mean, because one slot declared far from the
    // others is exactly the case the mean gets dragged by.
    let geometry = silicon::line_geometry(Some(REFERENCE_FONT));
    let drawn_span = first..first + declarations.len();
    let mut travel: Vec<f64> = slots
        .iter()
        .enumerate()
        .filter_map(|(index, slot)| {
            let (_, line) = slot.declared_at.as_ref()?;
            if slot.declared_by != drawn_from || !drawn_span.contains(line) {
                return None;
            }
            let row = *slot_rows.get(index)?;
            let line_y =
                code_png.height * geometry.line_center_fraction(line - first, code_png.height as u32);
            let row_y =
                table_png.height * geometry.line_center_fraction(row, table_png.height as u32);
            Some(line_y - row_y)
        })
        .collect();
    let table_offset = aligning_offset(travel);

    let width = code_png.width + gutter + table_png.width + margin * 2.0;
    let height = tallest.max(table_offset + table_png.height) + margin * 2.0;

    Ok(PreparedStorage {
        contract: contract.name.clone(),
        slots,
        slot_rows,
        table,
        sidebar,
        declaration_line: first,
        declarations,
        table_png,
        code_png,
        margin,
        gutter,
        table_offset,
        drawn_from,
        width,
        height,
    })
}

/// The contract this name means, refusing to guess.
///
/// `lib/` vendors several copies of the same library, so a name is not an identity (see
/// CLAUDE.md). With no caller to resolve against, the honest move is to prefer the ones in
/// scope and, when the name still names several, stop and list them.
fn pick_contract<'a>(
    metadata: &'a EvmBatMetadata,
    wanted: &str,
) -> Result<&'a ContractMetadata, EvmMiroError> {
    let matches: Vec<&ContractMetadata> = metadata
        .contracts
        .iter()
        .filter(|contract| contract.name == wanted && !contract.vendored)
        .collect();
    match matches.len() {
        1 => Ok(matches[0]),
        0 => Err(Report::new(EvmMiroError).attach_printable(format!(
            "no in-scope contract called `{wanted}`; run `bat-cli sonar` if the scan is stale"
        ))),
        _ => Err(Report::new(EvmMiroError).attach_printable(format!(
            "`{wanted}` names {} contracts in scope:\n    {}",
            matches.len(),
            matches
                .iter()
                .map(|contract| contract.file_path.clone())
                .collect::<Vec<_>>()
                .join("\n    ")
        ))),
    }
}

/// The layout `forge` computes, as it computes it.
///
/// Shelling out rather than reimplementing: the compiler owns the answer, and a second
/// implementation of slot assignment would only be a way to be wrong differently.
/// Does this `forge inspect` failure mean the ARTIFACT has no layout, rather than the contract
/// having none or not compiling?
///
/// The distinction is the whole message: one is a cache to rebuild, the other is code to fix,
/// and a contract that occupies no slot does not fail at all — it answers with an empty layout.
fn is_stale_artifact(stderr: &str) -> bool {
    stderr.contains("storage layout missing")
}

fn forge_layout(contract: &str) -> Result<Vec<Slot>, EvmMiroError> {
    // Asked once per contract, then remembered. `forge inspect` answers in about a second
    // against a warm Foundry cache and compiles the whole project against a cold one — minutes,
    // in the middle of a deploy, with nothing printed while it runs.
    //
    // The layout is a pure function of the source, and audited source does not change: that is
    // what makes a cache honest here. `--refresh-layout` throws it away for the case the
    // assumption breaks, which is the auditor's call and not a guess this makes for them.
    if let Some(cached) = cached_layout(contract) {
        return Ok(cached);
    }
    let slots = ask_forge(contract)?;
    remember_layout(contract, &slots);
    Ok(slots)
}

/// The layout this project already has for `contract`, if it was asked for before.
fn cached_layout(contract: &str) -> Option<Vec<Slot>> {
    let metadata = EvmBatMetadata::read_metadata().ok()?;
    metadata
        .storage_layouts
        .iter()
        .find(|entry| entry.contract == contract)
        .map(|entry| entry.slots.clone())
}

/// Keep it for the next run. Best effort: a layout that could not be written is a slower next
/// deploy, never a wrong one.
fn remember_layout(contract: &str, slots: &[Slot]) {
    use crate::batbelt::evm::metadata::bat_metadata::StorageLayoutCache;
    let entry = StorageLayoutCache {
        contract: contract.to_string(),
        slots: slots.to_vec(),
    };
    let _ = EvmBatMetadata::update_metadata(move |m| {
        m.storage_layouts.retain(|existing| existing.contract != entry.contract);
        m.storage_layouts.push(entry.clone());
    });
}

/// Throw the remembered layouts away, so the next run asks the compiler again.
pub fn forget_layouts() -> Result<usize, EvmMiroError> {
    let mut count = 0;
    EvmBatMetadata::update_metadata(|m| {
        count = m.storage_layouts.len();
        m.storage_layouts.clear();
    })
    .change_context(EvmMiroError)?;
    Ok(count)
}

fn ask_forge(contract: &str) -> Result<Vec<Slot>, EvmMiroError> {
    let output = std::process::Command::new("forge")
        .args(["inspect", contract, "storage-layout", "--json"])
        .output()
        .map_err(|error| {
            Report::new(EvmMiroError)
                .attach_printable(format!(
                    "could not run `forge inspect {contract} storage-layout --json`: {error}"
                ))
                .attach(crate::Suggestion(
                    "install Foundry, or run this from the Foundry root where `forge` works"
                        .to_string(),
                ))
        })?;
    if !output.status.success() {
        let stderr = String::from_utf8_lossy(&output.stderr);
        // Three different things fail here and they need three different answers, so the
        // failure SAYS which one it is instead of being retried into silence. A tool that
        // quietly recompiles is a tool that decides for the auditor; what the auditor (or
        // the assistant driving this) needs is the cause and the command that fixes it.
        let report = Report::new(EvmMiroError);
        return Err(if is_stale_artifact(&stderr) {
            report
                .attach_printable(format!(
                    "no storage layout for {contract}: its COMPILED ARTIFACT carries none. \
This is Foundry's cache, not a contract without storage — a contract that occupies no slot \
answers with an EMPTY layout, and this one did not answer at all."
                ))
                .attach(crate::Suggestion(format!(
                    "rebuild the artifact and deploy again: `forge build --force`, or ask \
without touching the cache: `forge inspect {contract} storage-layout --json --no-cache`"
                )))
        } else {
            report
                .attach_printable(format!(
                    "`forge inspect {contract} storage-layout --json` failed:\n{}",
                    stderr.trim()
                ))
                .attach(crate::Suggestion(
                    "the layout comes from the compiler, so the contract has to compile: run \
`forge build`, fix what it reports, and deploy again"
                        .to_string(),
                ))
        });
    }

    let value: serde_json::Value = serde_json::from_slice(&output.stdout)
        .map_err(|error| {
            Report::new(EvmMiroError)
                .attach_printable(format!("forge printed something that is not JSON: {error}"))
        })?;
    let types = &value["types"];
    let mut slots = Vec::new();
    for entry in value["storage"].as_array().into_iter().flatten() {
        let type_key = entry["type"].as_str().unwrap_or_default();
        let described = &types[type_key];
        slots.push(Slot {
            slot: entry["slot"].as_str().unwrap_or_default().to_string(),
            offset: entry["offset"].as_u64().unwrap_or_default(),
            label: entry["label"].as_str().unwrap_or_default().to_string(),
            type_label: described["label"]
                .as_str()
                .unwrap_or(type_key)
                .to_string(),
            bytes: described["numberOfBytes"]
                .as_str()
                .and_then(|n| n.parse().ok())
                .or_else(|| described["numberOfBytes"].as_u64())
                .unwrap_or_default(),
            declared_by: String::new(),
            declared_at: None,
        });
    }
    Ok(slots)
}

/// Say which contract of the chain declares each slot, and where.
///
/// This is the column the source cannot give you: `YieldRouter`'s first three slots belong
/// to `TwoStepOwned` and to the reentrancy guard, and nothing in its own file says so.
fn attribute(metadata: &EvmBatMetadata, contract: &ContractMetadata, slots: &mut [Slot]) {
    let chain = chain_of(metadata, contract);
    for slot in slots.iter_mut() {
        let found = chain.iter().find_map(|source| {
            source
                .state_variables
                .iter()
                .find(|variable| variable.name == slot.label)
                .map(|variable| (source, variable))
        });
        match found {
            Some((source, variable)) => {
                slot.declared_by = source.name.clone();
                slot.declared_at = Some((source.file_path.clone(), variable.line));
            }
            // Left blank rather than guessed: a slot the scan cannot place is a slot whose
            // declaring contract we do not know, and saying "this contract" would be wrong.
            None => slot.declared_by = "?".to_string(),
        }
    }
}

/// The `constant`s and `immutable`s of this contract and its bases.
///
/// They are in the frame on purpose: they read exactly like state in the source and occupy
/// nothing, and that is a thing to know before reasoning about an upgrade or a proxy.
fn unstored_variables(metadata: &EvmBatMetadata, contract: &ContractMetadata) -> Vec<Unstored> {
    let mut out = Vec::new();
    for source in chain_of(metadata, contract) {
        for variable in &source.state_variables {
            let kind = match (variable.is_constant, variable.is_immutable) {
                (true, _) => "constant",
                (_, true) => "immutable",
                _ => continue,
            };
            out.push(Unstored {
                name: variable.name.clone(),
                type_name: variable.type_name.clone(),
                kind,
                line: variable.line,
            });
        }
    }
    out
}

/// This contract and every base it inherits from, as far as the names resolve.
fn chain_of<'a>(
    metadata: &'a EvmBatMetadata,
    contract: &'a ContractMetadata,
) -> Vec<&'a ContractMetadata> {
    let mut out = vec![contract];
    let mut pending: Vec<String> = contract.base_contracts.clone();
    let mut seen: std::collections::HashSet<String> = std::collections::HashSet::new();
    seen.insert(contract.name.clone());
    while let Some(name) = pending.pop() {
        if !seen.insert(name.clone()) {
            continue;
        }
        // A base is resolved from the SAME file's import graph where one is available, since
        // a bare name is not an identity across `lib/`.
        let Some(base) = metadata
            .contract_in_scope(&name, &contract.file_path)
            .or_else(|| metadata.contracts.iter().find(|c| c.name == name))
        else {
            continue;
        };
        pending.extend(base.base_contracts.clone());
        out.push(base);
    }
    out
}

/// Every function of this contract or its bases that writes one of these slots.
///
/// Matched on the ROOT of the lvalue: `standing[id].lastRise` is a write to `standing`. A
/// write rooted at a storage POINTER local (`r.status`, where `r` was bound by
/// `Request storage r = requests[id]`) does not name a slot and is left out rather than
/// guessed at — that is the one gap, and it is named in the frame instead of hidden.
fn writers_of(
    metadata: &EvmBatMetadata,
    contract: &ContractMetadata,
    slots: &[Slot],
) -> Vec<Writer> {
    let labels: std::collections::HashSet<&str> =
        slots.iter().map(|slot| slot.label.as_str()).collect();
    let mut out = Vec::new();
    for source in chain_of(metadata, contract) {
        for function in &source.functions {
            for site in &function.storage_write_sites {
                let root = site
                    .name
                    .split(['.', '['])
                    .next()
                    .unwrap_or(&site.name)
                    .to_string();
                if !labels.contains(root.as_str()) {
                    continue;
                }
                out.push(Writer {
                    slot_label: root,
                    function: format!("{}.{}", source.name, function.name),
                    path: prettify(&source.file_path),
                    line: site.line,
                    lvalue: site.name.clone(),
                });
            }
        }
    }
    out.sort_by(|a, b| {
        (&a.slot_label, &a.function, a.line).cmp(&(&b.slot_label, &b.function, b.line))
    });
    out.dedup_by(|a, b| a.slot_label == b.slot_label && a.line == b.line && a.path == b.path);
    out
}

/// The slot table: one row per entry, in slot order, with that slot's writers under it.
///
/// The writers live HERE rather than in a column of their own, because "who moves this slot"
/// is a question about the slot — read on its own the list was a second index to cross-check
/// against the first. Two entries on one slot stay two rows with the same number, which is
/// what packing looks like.
///
/// Returns the lines and, for each slot, the ROW its header landed on, so an arrow can be
/// aimed at it: once the writers are interleaved, the n-th slot is no longer the n-th line.
fn slot_table(contract: &str, slots: &[Slot], writers: &[Writer]) -> (Vec<String>, Vec<usize>) {
    let mut lines = vec![
        format!("{contract} — storage layout ({} slot entries)", slots.len()),
        "from `forge inspect`; a repeated slot number is packing".to_string(),
        "beside it: a purple name is a constant, a red one an immutable — neither holds a slot"
            .to_string(),
        String::new(),
    ];
    let mut rows = Vec::new();
    if slots.is_empty() {
        lines.push("  this contract occupies no storage".to_string());
        return (lines, rows);
    }

    for slot in slots {
        let mine: Vec<&Writer> = writers
            .iter()
            .filter(|writer| writer.slot_label == slot.label)
            .collect();
        // The `[]` is kept when the writes go through an index: `paths[quote] = …` and
        // `paths = …` are not the same statement.
        let indexed = mine.iter().any(|writer| writer.lvalue.contains('['));
        // What the row does NOT carry any more: the size in bytes (the type says it), the
        // number of writers (they are listed right underneath) and the file and line of the
        // declaration (the arrow points at it, and the writers carry the path). Every one of
        // those pushed the end of the row — where the arrow leaves from — further away from
        // the name the arrow is about. What is left is the one thing nothing else says: that
        // a slot came from a BASE, and from which.
        let inherited = if slot.declared_by != contract && !slot.declared_by.is_empty() {
            format!(" ({})", slot.declared_by)
        } else {
            String::new()
        };
        // A blank line between groups: a slot and the functions that write it are one
        // block, and without the gap seven blocks read as one list.
        if !rows.is_empty() {
            lines.push(String::new());
        }
        rows.push(lines.len());
        // Read as a declaration — `address owner` — not as a padded table. Columns put the
        // type a tab-stop away from the name it belongs to, and the gap is where the eye
        // loses which variable it is on.
        lines.push(format!(
            "  slot {:>3}+{}  {} {}{}",
            slot.slot,
            slot.offset,
            slot.type_label,
            format!("{}{}", slot.label, if indexed { "[]" } else { "" }),
            inherited,
        ));
        // One row per FUNCTION, with its writes nested under it. A function that writes a
        // struct's fields five times was five rows repeating its name, and the name is the
        // thing being looked up.
        let mut by_function: Vec<(&str, Vec<&Writer>)> = Vec::new();
        for writer in &mine {
            match by_function.last_mut() {
                Some((name, group)) if *name == writer.function => group.push(writer),
                _ => by_function.push((&writer.function, vec![writer])),
            }
        }
        let widest = mine.iter().map(|writer| writer.lvalue.len()).max().unwrap_or(0);
        let last = by_function.len().saturating_sub(1);
        for (index, (function, written)) in by_function.iter().enumerate() {
            // The same tree connectors `effects` draws with, for the same reason: the elbow
            // says which rows hang off this slot and the last one closes the group, so a
            // long table reads as groups instead of as one list with repeated indentation.
            let elbow = if index == last { "└─" } else { "├─" };
            lines.push(format!("      {elbow} {function}"));
            // The vertical carries on while this slot still has functions to come.
            let stem = if index == last { "  " } else { "│ " };
            for writer in written {
                // The lvalue WHOLE, root included: `.principalIndex` under a row that says
                // `_state` made the reader join the two halves themselves, and a bare field
                // name is not something you can search the file for.
                lines.push(format!(
                    "      {stem}     {:<widest$}  {}:{}",
                    writer.lvalue, writer.path, writer.line
                ));
            }
        }
    }
    (lines, rows)
}

/// The second column: what reads like state and occupies no slot.
///
/// In the frame on purpose. A `constant` and an `immutable` are declared among the state
/// variables, look like them in every way, and are in the bytecode — which is what decides
/// whether an upgrade can change them.
fn sidebar(contract: &str, unstored: &[Unstored]) -> Vec<String> {
    let mut lines = vec![
        format!("{contract} — in the bytecode, not in storage ({})", unstored.len()),
        "declared among the state variables; occupies no slot".to_string(),
        String::new(),
    ];
    if unstored.is_empty() {
        lines.push("    none".to_string());
    }
    for variable in unstored {
        lines.push(format!(
            "    {:<10} {:<28} {:<24} L{}",
            variable.kind, variable.name, variable.type_name, variable.line
        ));
    }
    lines
}

fn prettify(path: &str) -> String {
    crate::batbelt::path::prettify_source_code_path(path).unwrap_or_else(|_| path.to_string())
}

/// Put the two columns on the board, with an arrow from every slot row to the line that
/// declares it, with the frame's top-left at `(left, top)`.
///
/// The arrow is the point: a table of slots and a file of code are two things to hold in
/// your head at once, and the board is where they stop being two.
pub(crate) async fn draw(
    prepared: PreparedStorage,
    client: &MiroClient,
    left: f64,
    top: f64,
) -> Result<String, EvmMiroError> {
    let PreparedStorage {
        contract,
        drawn_from,
        slots,
        slot_rows,
        table,
        declaration_line: first,
        declarations,
        table_png,
        code_png,
        margin,
        gutter,
        table_offset,
        width: frame_width,
        height: frame_height,
        ..
    } = prepared;

    // The CODE goes first and the table second. The arrows then run right to left and land
    // just past the end of each declaration, instead of arriving at the far left edge of a
    // wide block and leaving the reader to find which line they meant.
    let columns = [&code_png, &table_png];
    let frame_id = client
        .create_frame(
            &format!("storage: {contract}"),
            left + frame_width / 2.0,
            top + frame_height / 2.0,
            frame_width,
            frame_height,
            None,
        )
        .await
        .change_context(EvmMiroError)?;

    // Both captures at once. They are independent — the frame fixed where each one goes —
    // and uploading an image is the slowest thing this function does, so waiting for the
    // first before starting the second is pure latency, the same reasoning that made the
    // deploy fill its frames several at a time.
    let mut cursor = margin;
    let mut uploading = tokio::task::JoinSet::new();
    let mut placed: Vec<f64> = Vec::new();
    for (index, column) in columns.into_iter().enumerate() {
        // The code at the top, the table level with the lines it points at.
        let top = margin + if index == 0 { 0.0 } else { table_offset };
        let (x, y) = (cursor + column.width / 2.0, top + column.height / 2.0);
        placed.push(cursor);
        cursor += column.width + gutter;
        let client = client.clone();
        let frame_id = frame_id.clone();
        let png = column.png_path.clone();
        let label = contract.clone();
        let width = column.width;
        uploading.spawn(async move {
            let item = client
                .create_image_in_frame(&png, &frame_id, &label, x, y, width)
                .await;
            let _ = std::fs::remove_file(&png);
            item
        });
    }
    while let Some(joined) = uploading.join_next().await {
        joined
            .map_err(|error| Report::new(EvmMiroError).attach_printable(error.to_string()))?
            .change_context(EvmMiroError)?;
    }
    println!("    {} {} column(s) uploaded", "✓".green(), columns.len());

    let code_left = placed[0];
    let table_left = placed[1];
    let code_right = code_left + code_png.width;
    let geometry = silicon::line_geometry(Some(REFERENCE_FONT));

    // Which slots can be pointed at: the ones this file declares. A slot a base declares
    // lives in another file, which this frame does not draw, so it gets no arrow rather than
    // one landing on the wrong line.
    let drawn_span = first..first + declarations.len();
    let aimed: Vec<(usize, &Slot, usize)> = slots
        .iter()
        .enumerate()
        .filter_map(|(index, slot)| {
            // Declared by THIS contract, on a line this capture actually shows. A slot a
            // base declares lives in another file, and a line outside the span is a line the
            // arrow would land beside rather than on.
            let (_, line) = slot.declared_at.as_ref()?;
            (slot.declared_by == drawn_from && drawn_span.contains(line)).then_some((index, slot, *line))
        })
        .collect();

    // Each arrow through a LANE of its own, drawn by the deploy's own `draw_lane_arrow`:
    // three straight legs, nothing left for Miro to route. The lanes are ordered the way the
    // deploy orders them — the arrow that ENDS lowest takes the lane furthest out — so
    // arrows that need not cross do not.
    let mut aimed: Vec<(usize, usize)> = aimed
        .iter()
        .filter_map(|(index, _, declared_line)| Some((*slot_rows.get(*index)?, *declared_line)))
        .collect();
    aimed.sort_by(|a, b| a.1.cmp(&b.1));

    // NOT `margin`: that one is the frame's, and shadowing it here made every arrow's y be
    // computed from the lane's inset instead — the arrows landed a line off their own row.
    let lane_gutter = (table_left - code_right).max(1.0);
    let lane_inset = 100.0_f64.min(lane_gutter / 4.0);
    let usable = (lane_gutter - 2.0 * lane_inset).max(0.0);
    let pitch = if aimed.len() > 1 {
        usable / (aimed.len() - 1) as f64
    } else {
        0.0
    };

    // Every arrow at once. Each is four markers and three connectors, so thirteen slots is
    // more than ninety calls in a row — the same queue the deploy stopped waiting on.
    // Planned first, then drawn in two batches. `draw_lane_arrow` makes five round trips that
    // each wait for the last, so thirteen slots were sixty-five calls in single file — which
    // is what made a big contract's layout take a visible while. A marker depends on nothing
    // but the frame and a leg on its own two markers, so the whole set goes up as
    // markers-then-connectors.
    use crate::batbelt::evm::miro::auto_deploy::{plan_lane_arrow, LaneEnd, LaneSide};
    let mut planned: Vec<(crate::batbelt::evm::miro::auto_deploy::PlannedLaneArrow, ConnectorStyle)> =
        Vec::new();
    let drawn = aimed.len();
    for (order, (row, declared_line)) in aimed.iter().enumerate() {
        // The same arithmetic the deploy anchors a call site with: the line's centre as a
        // fraction of the PNG's real height, so the shadow and the padding are accounted for
        // by the renderer rather than guessed at here.
        let row_y = margin
            + table_offset
            + table_png.height * geometry.line_center_fraction(*row, table_png.height as u32);
        let code_y = margin
            + code_png.height
                * geometry.line_center_fraction(declared_line - first, code_png.height as u32);

        // The row is LEFT of the lane, so the arrow leaves from the start of its text, not the
        // end: leaving from the end meant the first leg ran back across the row and struck its
        // own words through. The head still lands past the last character of the declaration,
        // which is the end the reader is looking for.
        let row_start = table_left
            + silicon::line_end_x(Some(REFERENCE_FONT), false, table.len(), 0, "") as f64;
        let declaration_end = code_left
            + silicon::line_end_x(
                Some(REFERENCE_FONT),
                true,
                declarations.len(),
                first,
                &declarations[declared_line - first],
            ) as f64;
        // Running right to left, the arrow whose declaration sits LOWEST takes the lane
        // nearest the table: every arrow below another then stops short of that one's lane
        // instead of crossing it. The deploy's rule, mirrored, because the direction is.
        let lane_x = code_right + lane_inset + order as f64 * pitch;
        planned.push((
            plan_lane_arrow(
                &LaneEnd::Point { x: row_start, y: row_y },
                // The head lands on the DECLARATION, because that is what the row is pointing
                // at — the deploy's arrows land on the call line for the same reason.
                &LaneEnd::Point { x: declaration_end, y: code_y },
                lane_x,
            ),
            ConnectorStyle {
                stroke_color: silicon::BAT_PALETTE[order % silicon::BAT_PALETTE.len()].to_string(),
                stroke_width: "8".to_string(),
                // Past the palette the colour repeats, so the STROKE changes with it: the
                // second time round is dashed and the third dotted. Two arrows of one colour
                // are two arrows a reader has to tell apart by following them, which is the
                // one thing a colour was there to save.
                stroke: match order / silicon::BAT_PALETTE.len() {
                    0 => ConnectorStroke::Solid,
                    1 => ConnectorStroke::Dashed,
                    _ => ConnectorStroke::Dotted,
                },
                caption: None,
                arrow: ArrowEnd::End,
            },
        ));
    }

    let mut drawing = tokio::task::JoinSet::new();
    for (index, (arrow, _)) in planned.iter().enumerate() {
        for (point, (x, y)) in arrow.points.iter().enumerate() {
            let client = client.clone();
            let frame_id = frame_id.clone();
            let (x, y) = (*x, *y);
            drawing.spawn(async move {
                client
                    .create_anchor_marker(&frame_id, x, y, 8.0)
                    .await
                    .map(|id| (index, point, id))
            });
        }
    }
    let mut markers: std::collections::BTreeMap<(usize, usize), String> =
        std::collections::BTreeMap::new();
    while let Some(joined) = drawing.join_next().await {
        let (index, point, id) = joined
            .map_err(|error| Report::new(EvmMiroError).attach_printable(error.to_string()))?
            .change_context(EvmMiroError)?;
        markers.insert((index, point), id);
    }

    for (index, (arrow, style)) in planned.iter().enumerate() {
        for (from_side, from_anchor, to_side, to_anchor, head) in &arrow.legs {
            let resolve = |side: &LaneSide| match side {
                LaneSide::Marker(point) => markers.get(&(index, *point)).cloned(),
                LaneSide::Item(id) => Some(id.clone()),
            };
            let (Some(from_id), Some(to_id)) = (resolve(from_side), resolve(to_side)) else {
                continue;
            };
            let mut leg = style.clone();
            leg.arrow = if *head { ArrowEnd::End } else { ArrowEnd::None };
            let (from_anchor, to_anchor) = (*from_anchor, *to_anchor);
            let client = client.clone();
            drawing.spawn(async move {
                client
                    .create_connector(&from_id, from_anchor, &to_id, to_anchor, leg)
                    .await
                    .map(|id| (0usize, 0usize, id))
            });
        }
    }
    while let Some(joined) = drawing.join_next().await {
        joined
            .map_err(|error| Report::new(EvmMiroError).attach_printable(error.to_string()))?
            .change_context(EvmMiroError)?;
    }
    println!("    {} {drawn} slot(s) pointed at their declaration", "✓".green());
    println!("  {}", client.frame_url(&frame_id).blue());
    Ok(frame_id)
}


/// One rendered column.
pub(crate) struct Rendered {
    pub(crate) png_path: String,
    pub(crate) width: f64,
    pub(crate) height: f64,
}

/// Whose declaration block to draw, when the contract has none of its own.
///
/// `None` means "this contract's" — the normal case. `Some(base)` is a thin wrapper such as
/// `contract Treasury is TwoStepOwned`: no state of its own, two real slots, and a group that
/// could not be deployed at all because the capture had nowhere to look. The base chosen is the
/// one that declares the MOST of this contract's slots; any other base's slots stay named in the
/// table, which has always resolved them by file and line.
fn declaring_contract(
    metadata: &EvmBatMetadata,
    contract: &ContractMetadata,
    slots: &[Slot],
) -> Option<String> {
    if !contract.state_variables.is_empty() {
        return None;
    }
    let mut count: std::collections::BTreeMap<&str, usize> = std::collections::BTreeMap::new();
    for slot in slots {
        if slot.declared_by.is_empty() || slot.declared_by == "?" || slot.declared_by == contract.name
        {
            continue;
        }
        // Only a base we can actually read: a slot declared in `lib/` has a file, and drawing
        // somebody else's vendored source as this contract's declarations is not the answer.
        if metadata
            .contracts
            .iter()
            .any(|other| other.name == slot.declared_by && !other.vendored)
        {
            *count.entry(slot.declared_by.as_str()).or_default() += 1;
        }
    }
    // Most slots first, then by name so the same contract always draws the same base.
    count
        .into_iter()
        .max_by(|a, b| a.1.cmp(&b.1).then_with(|| b.0.cmp(a.0)))
        .map(|(name, _)| name.to_string())
}

/// The lines this contract's own declarations span, 1-based and inclusive.
fn declaration_span(contract: &ContractMetadata, file_lines: usize) -> Option<(usize, usize)> {
    let first = contract
        .state_variables
        .iter()
        .map(|variable| variable.line)
        .min()?;
    let last = contract
        .state_variables
        .iter()
        .map(|variable| variable.line)
        .max()?;
    (first <= file_lines).then(|| (first.max(1), last.min(file_lines)))
}

/// Mark every `constant` and `immutable` where it is declared: purple for a constant, red
/// for an immutable.
///
/// Both are in the bytecode and occupy no slot, and the difference between them is when they
/// are fixed — a constant at compile time, an immutable by the constructor. Marking them in
/// the code is what makes the slot table complete without a third column: a declaration with
/// no mark is a declaration that holds a slot.
fn unstored_marks(unstored: &[Unstored]) -> Vec<silicon::TracedName> {
    use silicon::{TraceKind, TracedName};
    // Looked up BY COLOUR, not by a hard-coded index: the palette's order is a decision
    // about which hue a function reaches first, and it has already been changed once — which
    // silently turned every immutable green here. A background rather than a rule, because
    // what is being said is a property of the name, not its register.
    let index_of = |hex: &str| {
        silicon::TRACE_COLORS
            .iter()
            .position(|colour| *colour == hex)
            .unwrap_or(0)
    };
    let immutable = index_of("#ff6e6e");
    let constant = index_of("#d6acff");
    unstored
        .iter()
        .map(|variable| TracedName {
            name: variable.name.clone(),
            kind: TraceKind::Parameter,
            color: if variable.kind == "constant" { constant } else { immutable },
            dotted: false,
        })
        .collect()
}

pub(crate) fn render(
    lines: &[String],
    destination: &str,
    name: &str,
    line_offset: usize,
    traced: &[silicon::TracedName],
) -> Result<Rendered, EvmMiroError> {
    let png_path = silicon::create_figure_tracing(
        &lines.join("\n"),
        destination,
        // `.sol` so the declarations are highlighted as Solidity. The table keeps `.txt`,
        // which silicon falls back to Rust for — which is fine as long as every line PARSES:
        // a type cut short with an ellipsis left an unbalanced `(`, and the highlighter
        // stopped colouring from there on, so two rows of one table looked like two kinds of
        // thing. Nothing in this table is cut any more.
        &format!("{name}.{}", if line_offset > 0 { "sol" } else { "txt" }),
        line_offset,
        Some(REFERENCE_FONT),
        line_offset > 0,
        traced,
    );
    let (width, height) = image::image_dimensions(&png_path).change_context(EvmMiroError)?;
    Ok(Rendered {
        png_path,
        width: width as f64,
        height: height as f64,
    })
}

#[cfg(test)]
mod layout_failure_test {
    use super::is_stale_artifact;

    /// Foundry's own words for a cached artifact compiled without the layout.
    #[test]
    fn a_missing_layout_in_the_artifact_is_a_cache_problem() {
        assert!(is_stale_artifact(
            "Error: storage layout missing from artifact; this could be a spurious caching \
             issue, consider running `forge clean`"
        ));
    }

    /// A compiler error is NOT that, and must not be reported as one: the fix is different.
    #[test]
    fn a_compiler_error_is_not_a_cache_problem() {
        assert!(!is_stale_artifact(
            "Error: Compiler run failed:\nError (7576): Undeclared identifier."
        ));
    }
}

#[cfg(test)]
mod storage_test {
    use super::*;

    fn slot(label: &str, slot: &str, offset: u64, declared_by: &str) -> Slot {
        Slot {
            slot: slot.to_string(),
            offset,
            label: label.to_string(),
            type_label: "address".to_string(),
            bytes: 20,
            declared_by: declared_by.to_string(),
            declared_at: Some(("src/C.sol".to_string(), 7)),
        }
    }

    /// Two entries on one slot stay two rows: that repetition IS the packing.
    #[test]
    fn packing_is_two_rows_with_one_slot_number() {
        let slots = vec![slot("a", "0", 0, "C"), slot("b", "0", 20, "C")];
        let (table, rows) = slot_table("C", &slots, &[]);
        assert_eq!(rows.len(), 2, "one row per entry, both on slot 0");
        assert!(table.iter().any(|line| line.contains("slot   0+0")));
        assert!(table.iter().any(|line| line.contains("slot   0+20")));
    }

    /// A slot nothing writes has no rows under it.
    #[test]
    fn a_slot_with_no_writer_says_so() {
        let (table, _) = slot_table("C", &[slot("a", "0", 0, "C")], &[]);
        // Nothing writes it, so nothing hangs off its row — the row is the whole group.
        assert_eq!(table.iter().filter(|line| line.contains("├─") || line.contains("└─")).count(), 0);
    }

}

#[cfg(test)]
mod arrow_anchor_test {
    use crate::batbelt::silicon;

    /// The y of a row is measured from the FRAME's margin, not from the lane's inset.
    ///
    /// The two used to be called the same thing, and once the frame's margin stopped being a
    /// constant the inner one shadowed it: every arrow was computed from 100 units instead of
    /// the frame's own margin and landed a line off its row. The arithmetic is one line, so
    /// what this test really pins is that the two numbers are different numbers.
    #[test]
    fn a_row_is_anchored_from_the_frames_margin() {
        let geometry = silicon::line_geometry(Some(32));
        let png_height = 1_000u32;
        let margin = 120.0;
        let lane_inset = 100.0;
        let row = 3usize;
        let from_margin =
            margin + png_height as f64 * geometry.line_center_fraction(row, png_height);
        let from_inset =
            lane_inset + png_height as f64 * geometry.line_center_fraction(row, png_height);
        assert_ne!(from_margin, from_inset);
        assert_eq!(from_margin - from_inset, margin - lane_inset);
    }
}

#[cfg(test)]
mod arrow_stroke_test {
    use crate::batbelt::miro::client::ConnectorStroke;
    use crate::batbelt::silicon;

    /// The stroke a slot's arrow is drawn with, by its position in the order.
    fn stroke_for(order: usize) -> ConnectorStroke {
        match order / silicon::BAT_PALETTE.len() {
            0 => ConnectorStroke::Solid,
            1 => ConnectorStroke::Dashed,
            _ => ConnectorStroke::Dotted,
        }
    }

    /// A contract with more slots than the palette has colours gets the colour back — and when
    /// it does, the stroke changes, so the two arrows sharing a hue are still two arrows.
    #[test]
    fn a_repeated_colour_comes_with_a_different_stroke() {
        let palette = silicon::BAT_PALETTE.len();
        assert_eq!(stroke_for(0), ConnectorStroke::Solid);
        assert_eq!(stroke_for(palette - 1), ConnectorStroke::Solid);
        assert_eq!(stroke_for(palette), ConnectorStroke::Dashed);
        assert_eq!(stroke_for(palette * 2), ConnectorStroke::Dotted);
        // The colour genuinely repeats at that point, which is what the stroke is for.
        assert_eq!(
            silicon::BAT_PALETTE[0],
            silicon::BAT_PALETTE[palette % silicon::BAT_PALETTE.len()]
        );
    }
}

#[cfg(test)]
mod table_offset_test {
    use super::aligning_offset;

    /// The table hangs where its ROWS are level with their own lines, which is the offset that
    /// minimises the arrows' total vertical travel: the median of (line − row).
    #[test]
    fn the_table_hangs_where_its_rows_meet_their_lines() {
        // Six slots whose lines sit 2 000 below their rows, and one inherited-looking one far
        // above. The median keeps the six level; the mean would be dragged by the one.
        let mut travel = vec![2_000.0; 6];
        travel.push(-4_000.0);
        let mean = travel.iter().sum::<f64>() / travel.len() as f64;
        let offset = aligning_offset(travel);
        assert_eq!(offset, 2_000.0, "the six are level with their lines");
        assert!(offset > mean, "and the outlier does not drag it: mean was {mean}");
    }

    /// Never above the frame: a row whose line sits higher than the table can reach is a short
    /// arrow upwards, not a table hanging off the top of its own frame.
    #[test]
    fn the_table_is_never_pushed_above_the_frame() {
        assert_eq!(aligning_offset(vec![-500.0, -900.0]), 0.0);
        assert_eq!(aligning_offset(Vec::new()), 0.0, "nothing to point at, nothing to align");
    }
}

#[cfg(test)]
mod inherited_declarations_test {
    use super::{declaring_contract, Slot};
    use crate::batbelt::evm::metadata::bat_metadata::{ContractMetadata, EvmBatMetadata};
    use crate::batbelt::evm::types::EvmContractType;

    fn contract(name: &str, vendored: bool, declares: usize) -> ContractMetadata {
        ContractMetadata {
            metadata_id: name.to_string(),
            name: name.to_string(),
            using_libraries: Vec::new(),
            file_path: format!("src/{name}.sol"),
            contract_type: EvmContractType::Contract,
            base_contracts: Vec::new(),
            functions: Vec::new(),
            state_variables: (0..declares)
                .map(|index| crate::batbelt::evm::types::StorageVariable {
                    name: format!("var{index}"),
                    type_name: "uint256".to_string(),
                    visibility: crate::batbelt::evm::types::EvmVisibility::Public,
                    is_constant: false,
                    is_immutable: false,
                    line: 10 + index,
                })
                .collect(),
            events: Vec::new(),
            modifiers: Vec::new(),
            line: 1,
            vendored,
        }
    }

    fn slot(declared_by: &str) -> Slot {
        Slot {
            slot: "0".to_string(),
            offset: 0,
            label: "owner".to_string(),
            type_label: "address".to_string(),
            bytes: 20,
            declared_by: declared_by.to_string(),
            declared_at: Some((format!("src/{declared_by}.sol"), 38)),
        }
    }

    /// A contract that declares nothing itself draws the block of the base its slots come from.
    /// Refusing instead made the whole group undeployable — `Treasury is TwoStepOwned` has two
    /// real slots and an owner-gated entry point, and neither could be drawn.
    #[test]
    fn a_wrapper_draws_its_bases_declarations() {
        let metadata = EvmBatMetadata {
            contracts: vec![contract("Treasury", false, 0), contract("TwoStepOwned", false, 2)],
            ..Default::default()
        };
        let slots = [slot("TwoStepOwned"), slot("TwoStepOwned")];
        let treasury = &metadata.contracts[0];
        assert_eq!(
            declaring_contract(&metadata, treasury, &slots),
            Some("TwoStepOwned".to_string())
        );
    }

    /// A contract with state of its own always draws its own block, whatever it inherits.
    #[test]
    fn a_contract_with_state_draws_its_own() {
        let metadata = EvmBatMetadata {
            contracts: vec![contract("YieldRouter", false, 3), contract("TwoStepOwned", false, 2)],
            ..Default::default()
        };
        assert_eq!(
            declaring_contract(&metadata, &metadata.contracts[0], &[slot("TwoStepOwned")]),
            None
        );
    }

    /// A base this repository does not own is not drawn as somebody's declarations: its source
    /// is vendored, and a group is not the place to read `lib/`.
    #[test]
    fn a_vendored_base_is_not_drawn() {
        let metadata = EvmBatMetadata {
            contracts: vec![contract("Thin", false, 0), contract("ReentrancyGuard", true, 1)],
            ..Default::default()
        };
        assert_eq!(
            declaring_contract(&metadata, &metadata.contracts[0], &[slot("ReentrancyGuard")]),
            None
        );
    }

    /// Several bases: the one declaring the most slots is drawn, and the rest stay named in the
    /// table, which has always resolved an inherited slot by file and line.
    #[test]
    fn the_base_with_the_most_slots_wins() {
        let metadata = EvmBatMetadata {
            contracts: vec![
                contract("Thin", false, 0),
                contract("Owned", false, 1),
                contract("Pausable", false, 2),
            ],
            ..Default::default()
        };
        let slots = [slot("Owned"), slot("Pausable"), slot("Pausable")];
        assert_eq!(
            declaring_contract(&metadata, &metadata.contracts[0], &slots),
            Some("Pausable".to_string())
        );
    }
}

#[cfg(test)]
mod layout_cache_test {
    use super::Slot;

    /// A cached slot survives the round trip whole. The cache is what the diagram is drawn
    /// from, so a field lost in serialisation is a slot drawn wrong — and `declared_by` and
    /// `declared_at` are exactly the two the compiler does NOT give us, resolved from the
    /// metadata and impossible to recover from `forge` alone.
    #[test]
    fn a_cached_slot_keeps_everything_the_drawing_needs() {
        let slot = Slot {
            slot: "3".to_string(),
            offset: 12,
            label: "pendingOwner".to_string(),
            type_label: "address".to_string(),
            bytes: 20,
            declared_by: "TwoStepOwned".to_string(),
            declared_at: Some(("src/base/TwoStepOwned.sol".to_string(), 39)),
        };
        let json = serde_json::to_string(&slot).expect("writes");
        let back: Slot = serde_json::from_str(&json).expect("reads");
        assert_eq!(back.slot, slot.slot);
        assert_eq!(back.offset, slot.offset);
        assert_eq!(back.label, slot.label);
        assert_eq!(back.type_label, slot.type_label);
        assert_eq!(back.bytes, slot.bytes);
        assert_eq!(back.declared_by, slot.declared_by);
        assert_eq!(back.declared_at, slot.declared_at);
    }
}