bat-cli 0.34.0

//! Which contracts talk to which, on one frame.
//!
//! The question this answers is the one a reader cannot get from reading functions: a function
//! calls here and there, and after forty of them you still do not know that three different
//! contracts write to the same one, or that a contract you thought was a leaf is wired into
//! five others at construction. `deploy` shows one entry point in full depth; this shows the
//! system's shape and nothing else.
//!
//! An edge is a RELATION, not a count. One call is a relation; forty calls are the same
//! relation, and how many there are is a question for the entry point's own diagram. What the
//! edge does carry is its KIND — an ordinary call, an address fixed at construction, or a
//! binding nobody has resolved yet — because those are three different facts about the system.

use std::collections::{BTreeMap, BTreeSet};

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::matches_ignore;
use crate::batbelt::evm::types::EvmParam;
use crate::batbelt::evm::miro::EvmMiroError;
use crate::batbelt::miro::client::{ArrowEnd, ConnectorStroke, ConnectorStyle, MiroClient};
use crate::batbelt::miro::layout::{GraphLayout, PlacedNode};

pub struct MapOptions {
    /// Write a PNG of the map here instead of drawing it, so a layout can be judged without
    /// a board. Every change to how the arrows run used to cost a deployment to look at.
    pub preview: Option<String>,
    /// Print the relations and stop, touching no board.
    pub dry_run: bool,
    /// Draw only this contract's frame — "what does X talk to", on its own.
    ///
    /// The map is one frame per top caller, and most readings are about one of them. Drawing
    /// the whole block to look at one contract costs the board a dozen frames nobody asked for.
    pub contract: Option<String>,
    /// List which contracts are the hierarchy's two ends and stop, touching no board.
    ///
    /// The top callers are the frames the map has; the foundations are what everything else
    /// needs in order to exist. Both are read off the relations, and neither is something the
    /// auditor can get by reading the file tree.
    pub hierarchy: bool,
    /// Contracts to draw filled for this run, on top of the ones `bat-cli mark` recorded.
    pub mark: Vec<String>,
    /// Draw a leaf for EVERY method called on an outside box, reads included.
    ///
    /// By default only the ones that can change something: a `view` leaf says nothing left and
    /// nothing changed, and seventeen `balanceOf` boxes crowd out the one `safeTransfer` that
    /// matters. The flag is for reading a boundary in full.
    pub all_methods: bool,
    /// Leave out the contracts with no source in this repository.
    ///
    /// They are drawn by default. They used to be a text panel on the grounds that giving
    /// somebody else's token the same shape as the code under review is misleading — but what
    /// the audit actually asks is "what does this thing touch that I cannot read", and a name
    /// in a list beside the picture is not an answer to that. They are boxes now, grey ones,
    /// and the flag is for the rare read where only this repository matters.
    pub no_boundaries: bool,
    /// Print each frame as an indented tree of what it draws, and stop.
    ///
    /// The picture in words. A preview PNG cannot carry the names at map scale, so this is the
    /// only way to check that a leaf has the children it should without opening the board.
    pub tree: bool,
}

/// What kind of relation one contract has with another.
///
/// Ordered by how sure we are of it, which is also the order they are drawn in: a call the
/// scan pinned, then an address fixed at construction, then a binding that is still a guess.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub enum Relation {
    /// A call whose target this scan pinned to one contract.
    Calls,
    /// `new X(...)`: this contract DEPLOYS that one. A fact nothing else on the map carries —
    /// a factory is why its product exists at all, and the address came from here rather than
    /// from a constructor argument.
    Creates,
    /// An address this contract fixes when it is built — `immutable vault = …` in a
    /// constructor. It is a relation even if no call to it survived the pruning: it says the
    /// two are wired together.
    WiresAtConstruction,
    /// A call on an interface with more than one implementer and no `bat-cli resolve` for it.
    /// Drawn dashed: there IS a relation here, and its far end is not known.
    Unresolved,
    /// A call leaving the audited code: a contract with no source in this repository.
    Boundary,
    /// Every call from one to the other is a READ — `view` or `pure`. The relation is real and
    /// nothing moves across it, so the map draws the box and stops there: what the far contract
    /// does on its own is not something this caller can set off.
    Reads,
}

impl Relation {
    fn label(self) -> &'static str {
        match self {
            Self::Calls => "calls",
            Self::Creates => "creates",
            Self::WiresAtConstruction => "wires at construction",
            Self::Unresolved => "unresolved binding",
            Self::Boundary => "leaves the code",
            Self::Reads => "reads",
        }
    }
}

/// `from` → `to`, and what kind of relation it is. One per pair and kind, never one per call.
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
pub struct Edge {
    pub from: String,
    pub to: String,
    pub relation: Relation,
}

pub async fn run(options: MapOptions) -> Result<(), EvmMiroError> {
    // Timed out loud. "It takes a while" is not something to guess about: each phase says how
    // long it took, so the next question is about a number instead of a feeling.
    let started = std::time::Instant::now();
    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 mut phase = started;
    let metadata = EvmBatMetadata::read_metadata().change_context(EvmMiroError)?;
    mark("reading the metadata", &mut phase);
    // A scan from before the `vendored` flag marks nothing as vendored, so `lib/` — forge-std,
    // OpenZeppelin, the test harnesses — is "in scope" and the map is a map of the test
    // framework. That is not a map with a few extra boxes; it is the wrong picture, and the
    // only honest answer is to stop and say what to run.
    if let Some(count) = predates_vendored(&metadata) {
        return Err(Report::new(EvmMiroError).attach_printable(format!(
            "this scan predates the `vendored` flag: {count} contract(s) under lib/ are marked \
             as in scope — run `bat-cli sonar` to rescan before drawing the map"
        )));
    }
    // The hierarchy, and nothing else: which contracts the map makes a frame for, and which
    // ones everything else needs in order to exist. Answered from the relations, before any
    // layout, because it is a question about the system and not about a picture.
    if options.hierarchy {
        for line in hierarchy(&relations(&metadata), options.no_boundaries) {
            println!("{line}");
        }
        return Ok(());
    }
    let mut prepared = prepare(&metadata, &options)?;
    // One contract's frame, when that is what was asked for. Named rather than silently
    // ignored: a flag that matches nothing and draws everything is worse than an error.
    if let Some(wanted) = options.contract.as_deref() {
        prepared.keep_only(wanted)?;
    }
    let edges = prepared.edges.clone();
    mark("working out the relations, laying out and rendering", &mut phase);

    // The picture in words, and nothing else: the report's lists answer other questions, and a
    // tree with four screens of preamble above it is a tree nobody reads to the end.
    if options.tree {
        for line in prepared.tree() {
            println!("{line}");
        }
        prepared.discard();
        return Ok(());
    }

    for line in report(&edges) {
        println!("{line}");
    }
    // An interface declared in this repository that nothing in scope says it implements is
    // drawn as the outside — which is right for `IMirrorFactory` and wrong for an
    // `IListingLaunchpad` that `ListingDesk` implements without `is`. The source cannot tell
    // the two apart; the auditor can, and the line says how to record it.
    let undeclared = undeclared_interfaces(&metadata);
    if !undeclared.is_empty() {
        println!();
        println!(
            "{} interface(s) of this repository nothing in scope declares to implement — \
             treated as outside the code:",
            undeclared.len()
        );
        for name in &undeclared {
            println!("  {name:<28} if a contract here implements it: bat-cli resolve {name} <Contract>");
        }
    }
    // Calls the scan could not type as a contract are not on the map, and a map that leaves
    // something out without saying so is a map the reader trusts more than it deserves.
    let alone = unconnected(&metadata, &prepared.edges);
    if !alone.is_empty() {
        println!();
        println!(
            "{} deployable contract(s) with no relation at all — in the strip at the right, \
             apart from the diagram:",
            alone.len()
        );
        for name in &alone {
            println!("  {name}");
        }
    }
    let created_elsewhere = vendored_creations(&metadata);
    if !created_elsewhere.is_empty() {
        println!();
        println!(
            "{} `new` of code this repository does not own — not drawn:",
            created_elsewhere.len()
        );
        for line in &created_elsewhere {
            println!("  {line}");
        }
    }
    // The handover: every call site whose party the code cannot name, where it is written and
    // the key that records the answer. A reader (or an assistant reading the code) traces the
    // value once; the map draws it from then on like any other party.
    if !prepared.unnamed.is_empty() {
        println!();
        println!(
            "{} call site(s) handing an address the code cannot name ({} of them with a key to \
             record) — trace one and record it:",
            prepared.unnamed.len(),
            prepared.unnamed.iter().filter(|party| party.key.is_some()).count()
        );
        for party in &prepared.unnamed {
            println!("  {}", located(party));
            match &party.key {
                Some(key) => println!(
                    "      {}({}) → bat-cli resolve {key} <Contract>",
                    party.call, party.argument
                ),
                None => println!(
                    "      {}({}) — the scan did not record the expression; open the line",
                    party.call, party.argument
                ),
            }
        }
    }
    let untyped = untyped_receivers(&metadata);
    if !untyped.is_empty() {
        println!();
        println!(
            "{} call(s) whose receiver the scan could not type as a contract — not drawn:",
            untyped.len()
        );
        for line in &untyped {
            println!("  {line}");
        }
    }
    println!();
    for line in prepared.estimate() {
        println!("  {line}");
    }
    let calls = prepared.calls;

    if let Some(path) = options.preview.as_deref() {
        preview(&prepared, path)?;
    }
    if options.dry_run {
        prepared.discard();
        return Ok(());
    }

    let client = MiroClient::new_refreshed().await.change_context(EvmMiroError)?;
    mark("opening the Miro session", &mut phase);
    let board = client.list_frames().await.change_context(EvmMiroError)?;
    mark(&format!("reading the board ({} frames)", board.len()), &mut phase);
    // To the LEFT of everything. The deployments march rightwards, so a map put on that side
    // ends up wedged between two groups it has nothing to do with, and stays there as the
    // board grows. The left edge is the one side nothing else claims.
    //
    // Nothing is replaced: a second `map` is a second frame, and where it belongs on the board
    // is the auditor's call, not this tool's.
    let obstacles: Vec<crate::batbelt::miro::layout::Rect> = board
        .iter()
        .map(|frame| crate::batbelt::miro::layout::Rect {
            x: frame.x,
            y: frame.y,
            width: frame.width,
            height: frame.height,
        })
        .collect();
    // Measured first, because opening on the left means knowing how wide the thing is.

    let (left, top) =
        crate::batbelt::miro::layout::ColumnLayout::new().open_left(&obstacles, prepared.width);
    let outcome = draw(&client, prepared, left, top).await;
    mark("drawing it", &mut phase);

    // What was drawn goes into the registry, and the clusters get their cards — both only for
    // a FULL map: `--contract` draws one frame, and rewriting every cluster's cards from it
    // would leave each cluster pointing at the one frame that happened to be redrawn.
    if let Ok(drawn) = outcome.as_ref() {
        let whole_map = options.contract.is_none();
        match record_map(drawn.clone(), whole_map, &client).await {
            Ok(cards) if whole_map => {
                println!("    {} {cards} card(s) on the clusters", "✓".green())
            }
            Ok(_) => {}
            // The picture is on the board either way; a registry that could not be written is
            // worth a line, not a failed command.
            Err(report) => println!(
                "    {} the map is drawn, but the registry was not updated: {}",
                "note:".yellow(),
                report.current_context()
            ),
        }
        mark("recording it", &mut phase);
    }

    let (retries, waits) = client.stats();
    println!(
        "    {:>6.1}s  in total  ({} API call(s), {retries} retr(ies), {waits} budget wait(s))",
        started.elapsed().as_secs_f64(),
        calls.total()
    );
    outcome.map(|_| ())
}

/// What a card is: how far above the cluster's label it sits, and how big.
///
/// Above the shape, because the shape is the group's anchor — read from the board every run,
/// since the auditor moves it — and because the column under it is where the deployments go.
/// Sized to be read at the zoom where a whole group fits, which is the only zoom anybody looks
/// at a cluster's heading from. The first try was 2 600 × 260 with 90-point text — legible with
/// the board at 100%, a chip at any useful distance, next to a name shape 1 200 units tall.
const CARD_HEIGHT: f64 = 560.0;
const CARD_WIDTH: f64 = 4_600.0;
const CARD_GAP: f64 = 200.0;
const CARD_FONT: usize = 180;
const CARD_FILL: &str = "#ffffff";
/// The one colour on the board that means "go there".
const CARD_BORDER: &str = "#1a73e8";
/// At most this many cards over one cluster; past it the last one counts the rest.
const MAX_CARDS: usize = 4;

/// Record what the map drew, and give every cluster a card per frame that shows its contract.
///
/// Returns how many cards were created.
///
/// Three rules the auditor set, and they are the whole design:
/// - a card per FRAME, because the frame is where the hierarchy is read — parents and children
///   are in the picture, so the card only has to take you there;
/// - the cluster must NOT depend on the map: no record, no cards, no error;
/// - a redrawn map replaces its own cards rather than stacking new ones on the old.
async fn record_map(
    frames: Vec<crate::batbelt::evm::metadata::bat_metadata::MapFrameRef>,
    whole_map: bool,
    client: &MiroClient,
) -> Result<usize, EvmMiroError> {
    use crate::batbelt::evm::metadata::bat_metadata::{MapCardRef, MapFrameRef};

    let mut metadata = EvmBatMetadata::read_metadata().change_context(EvmMiroError)?;
    if !whole_map {
        // One frame redrawn: keep it in the registry by its root, and leave the cards alone —
        // they describe a map this run did not replace.
        let mut kept: Vec<MapFrameRef> = metadata
            .miro
            .map
            .iter()
            .filter(|old| !frames.iter().any(|new| new.root == old.root))
            .cloned()
            .collect();
        kept.extend(frames);
        metadata.miro.map = kept;
        metadata.save_metadata().change_context(EvmMiroError)?;
        return Ok(0);
    }

    // The cards this tool put up last time, gone before new ones go up: a card pointing at a
    // frame that no longer exists is worse than no card, and they would otherwise stack.
    //
    // Found on the BOARD and not only in the registry. The registry is a convenience and it can
    // be lost — a binary that did not know the `miro.map` field rewrote `BatMetadata.json`
    // without it, and the next run drew a second set of cards on top of the first, which is
    // exactly what the auditor saw. A card carries its own signature in its text, so the board
    // can always be asked.
    let mut stale: Vec<String> = metadata
        .miro
        .map
        .iter()
        .flat_map(|frame| frame.cards.iter().map(|card| card.item_id.clone()))
        .collect();
    if let Ok(loose) = client.list_loose_shapes().await {
        stale.extend(
            loose
                .into_iter()
                .filter(|(_, content)| is_map_card(content))
                .map(|(id, _)| id),
        );
    }
    stale.sort();
    stale.dedup();
    let mut removing = tokio::task::JoinSet::new();
    for id in stale {
        let client = client.clone();
        removing.spawn(async move { client.delete_item(&id).await });
    }
    while removing.join_next().await.is_some() {}

    // Where each cluster's cards go: above its label shape, which is read from the board
    // because the auditor drags groups around. Every geometry asked for at once.
    let columns: Vec<(String, String)> = metadata
        .miro
        .auto
        .columns
        .iter()
        .filter(|column| !column.label_id.is_empty())
        .map(|column| (column.contract.clone(), column.label_id.clone()))
        .collect();
    let made = draw_cards(&columns, &frames, client).await;
    metadata.miro.map = frames
        .into_iter()
        .map(|mut frame| {
            frame.cards = made
                .iter()
                .filter(|(_, root, _)| *root == frame.root)
                .map(|(contract, _, id)| MapCardRef {
                    contract: contract.clone(),
                    item_id: id.clone(),
                })
                .collect();
            frame
        })
        .collect();
    metadata.save_metadata().change_context(EvmMiroError)?;
    Ok(made.len())
}

/// Put one card per frame over each of these clusters, and say which card is whose.
///
/// Returns `(cluster contract, frame root, item id)` per card made. Everything it can ask for
/// at once it asks for at once: the geometries in one wave, the cards in batches of twenty.
async fn draw_cards(
    columns: &[(String, String)],
    frames: &[crate::batbelt::evm::metadata::bat_metadata::MapFrameRef],
    client: &MiroClient,
) -> Vec<(String, String, String)> {
    let mut asking = tokio::task::JoinSet::new();
    for (contract, label_id) in columns {
        let client = client.clone();
        let (contract, label_id) = (contract.clone(), label_id.clone());
        asking.spawn(async move { (contract, client.item_geometry(&label_id).await) });
    }
    let mut anchors: BTreeMap<String, (f64, f64)> = BTreeMap::new();
    while let Some(Ok((contract, geometry))) = asking.join_next().await {
        if let Some((x, y, _, height)) = geometry {
            anchors.insert(contract, (x, y - height / 2.0));
        }
    }

    struct Planned {
        contract: String,
        root: String,
        item: serde_json::Value,
    }
    let mut planned: Vec<Planned> = Vec::new();
    for (contract, (centre, top)) in &anchors {
        let showing = frames_showing(frames, contract);
        if showing.is_empty() {
            continue;
        }
        let drawn = showing.len().min(MAX_CARDS);
        let span = drawn as f64 * CARD_WIDTH + (drawn as f64 - 1.0) * CARD_GAP;
        for (index, frame) in showing.iter().take(MAX_CARDS).enumerate() {
            let x = centre - span / 2.0 + CARD_WIDTH / 2.0 + index as f64 * (CARD_WIDTH + CARD_GAP);
            let y = top - CARD_GAP - CARD_HEIGHT / 2.0;
            // The words carry the fact, the anchor carries the jump. A map can be deleted and
            // the card still says which frame showed this contract — `linkedTo` is not
            // reachable from the REST API, so the link has always been an `<a href>` in the
            // text (see CLAUDE.md).
            let left = showing.len().saturating_sub(MAX_CARDS);
            let text = if index + 1 == MAX_CARDS && left > 0 {
                format!("map · {} (+{left} more)", frame.root)
            } else {
                format!("map · {}", frame.root)
            };
            planned.push(Planned {
                contract: contract.clone(),
                root: frame.root.clone(),
                item: MiroClient::link_card_item(
                    &text,
                    &client.frame_url(&frame.frame_id),
                    x,
                    y,
                    CARD_WIDTH,
                    CARD_HEIGHT,
                    CARD_FONT,
                    CARD_FILL,
                    CARD_BORDER,
                ),
            });
        }
    }

    const BATCH: usize = 20;
    let mut making = tokio::task::JoinSet::new();
    for chunk in planned.chunks(BATCH) {
        let client = client.clone();
        let keys: Vec<(String, String)> = chunk
            .iter()
            .map(|card| (card.contract.clone(), card.root.clone()))
            .collect();
        let items: Vec<serde_json::Value> = chunk.iter().map(|card| card.item.clone()).collect();
        making.spawn(async move { (keys, client.create_items_bulk(items).await) });
    }
    let mut made: Vec<(String, String, String)> = Vec::new();
    while let Some(joined) = making.join_next().await {
        if let Ok((keys, Ok(ids))) = joined {
            for ((contract, root), id) in keys.into_iter().zip(ids) {
                made.push((contract, root, id));
            }
        }
    }
    made
}

/// Is this loose shape one of the map's cards?
///
/// Its own signature and nothing looser: the `map · ` prefix the card is written with AND a link
/// to a frame. A shape an auditor wrote by hand does not carry both, and deleting one of theirs
/// would be unforgivable — this is the only place this tool removes something it is not holding
/// an id for.
fn is_map_card(content: &str) -> bool {
    content.contains("map · ") && content.contains("moveToWidget=")
}

/// The frames that draw this contract — the ones its cluster gets a card for.
fn frames_showing<'a>(
    frames: &'a [crate::batbelt::evm::metadata::bat_metadata::MapFrameRef],
    contract: &str,
) -> Vec<&'a crate::batbelt::evm::metadata::bat_metadata::MapFrameRef> {
    frames
        .iter()
        .filter(|frame| frame.contracts.iter().any(|name| name == contract))
        .collect()
}

/// Give ONE cluster its cards, from the map already in the registry.
///
/// Called by `deploy` when a group is drawn, because a cluster deployed after the map had no
/// way to get them: `map` draws the cards, and when it last ran this column did not exist.
/// Treasury's group went up with none.
///
/// Silent and harmless when there is no map: a cluster must never depend on one.
pub async fn cards_for(contract: &str, client: &MiroClient) -> Result<usize, EvmMiroError> {
    use crate::batbelt::evm::metadata::bat_metadata::MapCardRef;

    let mut metadata = EvmBatMetadata::read_metadata().change_context(EvmMiroError)?;
    if metadata.miro.map.is_empty() {
        return Ok(0);
    }
    let Some(label_id) = metadata
        .miro
        .auto
        .columns
        .iter()
        .find(|column| column.contract == contract)
        .map(|column| column.label_id.clone())
        .filter(|id| !id.is_empty())
    else {
        return Ok(0);
    };

    // This cluster's own old cards, and only its own: another column's are none of this
    // deployment's business.
    let mut removing = tokio::task::JoinSet::new();
    for frame in &metadata.miro.map {
        for card in frame.cards.iter().filter(|card| card.contract == contract) {
            let (client, id) = (client.clone(), card.item_id.clone());
            removing.spawn(async move { client.delete_item(&id).await });
        }
    }
    while removing.join_next().await.is_some() {}

    let frames = metadata.miro.map.clone();
    let made = draw_cards(&[(contract.to_string(), label_id)], &frames, client).await;
    for frame in &mut metadata.miro.map {
        frame.cards.retain(|card| card.contract != contract);
        frame.cards.extend(
            made.iter()
                .filter(|(_, root, _)| root == &frame.root)
                .map(|(contract, _, id)| MapCardRef {
                    contract: contract.clone(),
                    item_id: id.clone(),
                }),
        );
    }
    metadata.save_metadata().change_context(EvmMiroError)?;
    Ok(made.len())
}

/// Repaint the boxes of the map already on the board, so changing which contracts stand out
/// costs no frames.
///
/// `bat-cli map` never replaces: a redraw would leave another generation of frames for the
/// auditor to delete, and the only thing that changed is a fill. The frames are in the registry;
/// their boxes are found by the name they carry, which is the same trick the cards use.
///
/// Contracts only. An outside leaf and a method leaf are not marked — the reader's list is of
/// contracts, and those boxes carry their interface's colour on the border, which this does not
/// touch.
pub async fn repaint(client: &MiroClient) -> Result<(usize, usize), EvmMiroError> {
    let metadata = EvmBatMetadata::read_metadata().change_context(EvmMiroError)?;
    if metadata.miro.map.is_empty() {
        return Err(Report::new(EvmMiroError)
            .attach_printable("no map recorded for this project")
            .attach(crate::Suggestion("draw one first: `bat-cli map`".to_string())));
    }
    let marked: BTreeSet<&str> = metadata
        .marked_contracts
        .iter()
        .map(String::as_str)
        .collect();

    // Every frame's boxes at once, each paired with the contracts THAT frame draws — which the
    // registry already knows. Only those are repainted: an interface's box carries its colour
    // too (as a fill on a map drawn before 0.33, as a border after), and a repaint that painted
    // every box it could name would wipe it.
    let mut asking = tokio::task::JoinSet::new();
    for frame in &metadata.miro.map {
        let (client, id) = (client.clone(), frame.frame_id.clone());
        let contracts: BTreeSet<String> = frame.contracts.iter().cloned().collect();
        asking.spawn(async move { (contracts, client.shapes_in_frame(&id).await) });
    }
    let mut boxes: Vec<(String, String)> = Vec::new();
    while let Some(joined) = asking.join_next().await {
        if let Ok((contracts, Ok(found))) = joined {
            boxes.extend(found.into_iter().filter(|(_, content)| {
                shape_name(content).is_some_and(|name| contracts.contains(&name))
            }));
        }
    }

    // What each one should be, from its WORDS: a box says the contract it stands for, and a
    // contract is marked or it is not. An interface leaf is left alone — its border carries its
    // colour and its text is the interface's name, which is not in the reader's list anyway.
    let mut painting = tokio::task::JoinSet::new();
    let mut touched = 0usize;
    for (id, content) in &boxes {
        let Some(name) = shape_name(content) else { continue };
        let fill = if marked.contains(name.as_str()) { MARK_FILL } else { BOX_FILL };
        touched += 1;
        let (client, id) = (client.clone(), id.clone());
        painting.spawn(async move { client.recolour_shape(&id, fill).await });
    }
    let mut repainted = 0usize;
    while let Some(joined) = painting.join_next().await {
        if matches!(joined, Ok(Ok(()))) {
            repainted += 1;
        }
    }
    Ok((repainted, touched))
}

/// The plain name a box's HTML carries: `<p><b>YieldRouter</b></p>` → `YieldRouter`.
fn shape_name(content: &str) -> Option<String> {
    let text: String = {
        let mut out = String::new();
        let mut inside_tag = false;
        for ch in content.chars() {
            match ch {
                '<' => inside_tag = true,
                '>' => inside_tag = false,
                _ if !inside_tag => out.push(ch),
                _ => {}
            }
        }
        out.trim().to_string()
    };
    if text.is_empty() {
        return None;
    }
    // An ACCOUNT is never filled, however the reader's list reads: it is an address, not code,
    // and a fresh map draws it the same way. Left alone, like a legend row.
    if text.ends_with("(address)") {
        return None;
    }
    // A party box says the role before the entity — `to: StakerDistributor` — and it stands for
    // that contract exactly as the contract's own box does. Without this, marking a contract
    // painted its box and left its four party copies white, while a redrawn map painted all
    // five.
    let name = text.split_once(ROLE_MARK).map(|(_, entity)| entity).unwrap_or(&text).trim();
    // A legend row, a strip heading or a method leaf is not a contract: a contract's box carries
    // exactly its name, and anything with a space left in it is one of the others.
    (!name.is_empty() && !name.contains(' ')).then(|| name.to_string())
}

/// Size of a contract's box, and the room left around the drawing.
/// Sized for the NAME, not for a frame: a box that fits `StakingQuoteOracle` at a readable
/// size and no more. The first version gave every contract a 2600×700 box with 72-point text
/// in it, so the map was mostly empty box and the arrows between them were hairlines.
const NODE_HEIGHT: f64 = 320.0;
/// What a box that is NOT this repository's code takes: half the height, half the type, and
/// padding to match — see `node_height`.
const OUTSIDE_HEIGHT: f64 = 160.0;
const OUTSIDE_FONT: usize = 60;
const OUTSIDE_CHAR: f64 = 35.0;
const OUTSIDE_PAD: f64 = 80.0;
const NODE_FONT: usize = 120;
/// Roughly the width one character takes at that font, plus room on both sides.
const NODE_CHAR: f64 = 70.0;
const NODE_PAD: f64 = 160.0;
const MAP_MARGIN: f64 = 600.0;
/// Thick enough to read at the zoom where the whole map fits, which is the only zoom it is
/// for. Miro refuses anything from 24 up.
const EDGE_WIDTH: &str = "16";
/// The invisible square a leg lands on, as the deploy sizes it.
const MARKER_SIZE: f64 = 8.0;

/// The one colour an arrow has.
///
/// Colour used to carry two things at once — what KIND of relation, and how SURE the scan
/// was — and four hues for five kinds was one too many to tell apart at the zoom where the
/// whole map fits, which is the only zoom it is for. The kind is the stroke now (`stroke_of`),
/// and colour is kept for the one thing worth a colour: an arrow that runs backwards.
const EDGE_COLOUR: &str = "#1a1a1a";
/// A cycle. Two contracts that each depend on the other is where re-entrancy and ordering
/// bugs live, so the arrow that closes the loop is the one mark on the map that is itself a
/// finding candidate — and it gets the only colour.
const CYCLE_COLOUR: &str = "#f24726";
/// `new X(...)`: this contract DEPLOYED that one, which is a different fact from calling it —
/// the address exists because of this line. It carried the word "creates" on the leg; a colour
/// says the same thing with nothing to read.
///
/// Yellow. A dark green read as a black line at the zoom where a whole frame fits, and a bright
/// one was still lost among the ordinary calls — the colour only earns its place if it is seen
/// before the line it is drawn on.
const CREATES_COLOUR: &str = "#fac710";
const BOX_FILL: &str = "#ffffff";
const BOX_BORDER: &str = "#1a1a1a";

/// A box that is NOT this repository's code, drawn only under `--with-boundaries`: grey, so
/// a token nobody here can read is never mistaken for a contract they can.
const OUTSIDE_FILL: &str = "#e6e6e6";

/// The background of a contract the reader asked to see (`bat-cli mark`).
///
/// A strong, warm fill: it has to be found before anything else on the frame, which is the whole
/// request. Nothing else on the map uses it — the interfaces' tints are pale and the repeated
/// contracts use borders.
const MARK_FILL: &str = "#ffe066";

/// One fill per INTERFACE, per frame.
///
/// Every caller gets its own copy of what it calls outside, which is what keeps the arrows
/// short — but then four boxes reading `IERC20` are four boxes, and nothing says they are the
/// same thing. A colour does: within a frame, every copy of one interface carries one fill and
/// no two interfaces carry the same. Per FRAME and not per map, because a reader compares what
/// is in front of them; across frames the name is the identity.
///
/// Light tints on purpose — the name is read off the box, so the fill sits under black text
/// without competing with the arrows.
/// Saturated, because these are a BORDER and a NAME now, not a fill.
///
/// They started as pale tints for a filled box, which is what they were good at; once the fill
/// went to the marked contracts and the interfaces moved to a dotted border with their name in
/// colour, the same tints became a label nobody could read against white.
const OUTSIDE_FILLS: &[&str] = &[
    "#1a73e8", "#c2185b", "#00897b", "#e8710a", "#6a1b9a", "#00838f", "#5d4037", "#827717",
    "#2e7d32", "#ad1457", "#283593", "#4e342e",
];

/// One border per CONTRACT that this frame draws more than once.
///
/// A frame is a tree, so a contract reached two ways is two boxes — which is what keeps the
/// arrows short, and leaves the reader with two boxes reading `Treasury` and nothing saying they
/// are the same address. The interfaces answer that with their fill; a contract cannot use the
/// fill too, or the two codes collide on a box that is both. So: a contract drawn ONCE keeps the
/// plain border, and one drawn twice or more takes a colour of its own, carried by every copy.
///
/// Saturated, because a 4-unit border has to carry the colour on its own — and neither green nor
/// red, which already mean `creates` and `a cycle` on the arrows.
/// How thick a border is drawn, plain and coloured.
///
/// A coloured border is a SIGNAL, and at 4 units it was invisible at the zoom where a whole
/// frame fits — which is the only zoom the map is read at. The plain one stays thin, because a
/// black border that thick reads as weight rather than as an edge. Miro's ceiling is 24.
const BORDER_WIDTH: usize = 4;
const REPEAT_BORDER_WIDTH: usize = 23;

const REPEAT_BORDERS: &[&str] = &[
    "#1a73e8", "#a259ff", "#00897b", "#e8710a", "#c2185b", "#5d4037", "#1a237e", "#827717",
];
/// The strip's own boxes: present, apart, and visibly not part of the diagram.
const STRIP_FILL: &str = "#f4f4f4";
/// Vertical distance between two arrows meeting the same side of one box. Five arrows into
/// one contract used to land on one point of its border and read as one.
const ANCHOR_PITCH: f64 = 40.0;
/// Kept clear at the top and bottom of a box's side, so no arrow grazes a corner.
const ANCHOR_INSET: f64 = 40.0;

/// The id of the strip's heading, which is a box like the others and must never be confused
/// with a contract that happens to carry that name.
const STRIP_HEADING: &str = "\u{0}not connected in scope";
/// Length of the sample leg beside a legend row.
const LEGEND_SAMPLE: f64 = 700.0;
/// How far under the lowest box a cycle's corridor runs, and how far apart two of them sit.
const CYCLE_GAP: f64 = 240.0;
const CYCLE_PITCH: f64 = 160.0;

/// How far under its box a contract's leaves sit, which is the room the arrows into them need.
const BADGE_GAP: f64 = 30.0;
/// The height a leaf's row takes under its caller, used when a frame is measured.
const BADGE_HEIGHT: f64 = 150.0;

fn node_width(id: &str) -> f64 {
    // Measured from the TEXT the box actually carries, not from its id: a method leaf is sized
    // for `safeTransfer()` and not for the `IERC20` its id starts with, which is how a leaf ended
    // up narrower or wider than its own words.
    let text = box_text(id);
    if is_outside(id) && destination_of(id).is_none() {
        return text.chars().count() as f64 * OUTSIDE_CHAR + OUTSIDE_PAD * 2.0;
    }
    text.chars().count() as f64 * NODE_CHAR + NODE_PAD * 2.0
}

/// The box an outside leaf gets: half the height, half the type.
///
/// They are the most numerous boxes on a frame — every caller carries its own copy — and the
/// least important: a reader does not scan for `IERC20` from across the board, they read it once
/// they have found the contract that calls it. At the contracts' own size they were most of the
/// frame's area.
fn node_height(id: &str) -> f64 {
    if is_outside(id) && destination_of(id).is_none() {
        OUTSIDE_HEIGHT
    } else {
        NODE_HEIGHT
    }
}

fn node_font(id: &str) -> usize {
    if is_outside(id) && destination_of(id).is_none() {
        OUTSIDE_FONT
    } else {
        NODE_FONT
    }
}

/// How a kind of relation is drawn: its stroke, and — where one word earns its cost — a
/// caption on the leg that carries the head. Three strokes a reader can tell apart at any
/// zoom: solid is a fact, dashed is a question, dotted is wiring nobody calls through.
fn stroke_of(relation: Relation) -> (ConnectorStroke, Option<&'static str>) {
    match relation {
        Relation::Calls => (ConnectorStroke::Solid, None),
        // No caption: a word hung on a leg is a word to read, and `new X(...)` is rare enough
        // that a colour of its own carries it. Green, which nothing else on the map uses.
        Relation::Creates => (ConnectorStroke::Solid, None),
        // Only ever drawn for a pair that is wired and NOT called — a call outranks it — so
        // the word marks the odd case worth a second look.
        Relation::WiresAtConstruction => (ConnectorStroke::Dotted, Some("wired")),
        Relation::Unresolved => (ConnectorStroke::Dashed, Some("?")),
        // The grey box at the far end already says it is outside; the arrow is a call.
        Relation::Boundary => (ConnectorStroke::Solid, None),
        // Dotted like the other relation nothing flows through, and captioned because dotted
        // alone would read as `wired`.
        Relation::Reads => (ConnectorStroke::Dotted, Some("reads")),
    }
}

/// The style of one arrow: its relation's stroke in the one colour, or red when it runs
/// backwards.
fn style_of(relation: Relation, backwards: bool) -> ConnectorStyle {
    let (stroke, caption) = stroke_of(relation);
    let colour = match (backwards, relation) {
        (true, _) => CYCLE_COLOUR,
        (false, Relation::Creates) => CREATES_COLOUR,
        (false, _) => EDGE_COLOUR,
    };
    ConnectorStyle {
        stroke_color: colour.to_string(),
        stroke_width: EDGE_WIDTH.to_string(),
        stroke,
        caption: caption.map(str::to_string),
        arrow: ArrowEnd::End,
    }
}

/// What a legend row shows beside its words.
#[derive(Debug, Clone)]
enum Sample {
    /// A short leg in this style: two markers and one connector, like any arrow.
    Leg(ConnectorStyle),
    /// A box with this fill, border and border style, like any box.
    Box { fill: &'static str, border: &'static str, style: &'static str },
}

/// One row of the legend: a box with the words, and beside it the thing the words name.
///
/// The old legend was five boxes each FILLED with its relation's colour, which made sense
/// while colour was the code. With one colour and three strokes a filled box says nothing;
/// the sample is a real leg in the real style, so the reader matches a line to a line.
#[derive(Debug, Clone)]
struct LegendRow {
    text: &'static str,
    sample: Sample,
    /// Frame-local centre of the words' box, and its width.
    x: f64,
    y: f64,
    width: f64,
    /// The sample's two ends, for a `Leg`; the words' own box doubles as the sample for a
    /// `Box` row.
    sample_from: (f64, f64),
    sample_to: (f64, f64),
}

/// The legend, placed: one row per thing a reader can see on the map, in the frame's
/// top-left corner above the first column.
fn legend_rows() -> Vec<LegendRow> {
    let rows: [(&'static str, Sample); 10] = [
        ("calls", Sample::Leg(style_of(Relation::Calls, false))),
        ("yellow: creates it — `new X(...)`", Sample::Leg(style_of(Relation::Creates, false))),
        ("wired at construction, never called", Sample::Leg(style_of(Relation::WiresAtConstruction, false))),
        ("unresolved binding — a question", Sample::Leg(style_of(Relation::Unresolved, false))),
        ("runs backwards — a cycle", Sample::Leg(style_of(Relation::Calls, true))),
        // Every box on a map is this repository's code now: what leaves it is the grey line
        // under a box, and a contract with a frame of its own is a card.
        ("dotted, named in colour: no source here", Sample::Box { fill: BOX_FILL, border: OUTSIDE_FILLS[0], style: "dotted" }),
        ("filled: a contract you marked to see", Sample::Box { fill: MARK_FILL, border: BOX_BORDER, style: "normal" }),
        ("coloured border: the same contract, drawn twice", Sample::Box { fill: BOX_FILL, border: REPEAT_BORDERS[0], style: "normal" }),
        ("dotted `reads`: every call that way is a view — nothing moves, nothing follows", Sample::Leg(style_of(Relation::Reads, false))),
        ("dashed: an address only the deploy script names — `bat-cli resolve C.var X`", Sample::Box { fill: BOX_FILL, border: BOX_BORDER, style: "dashed" }),
    ];
    rows.into_iter()
        .enumerate()
        .map(|(index, (text, sample))| {
            let width = node_width(text);
            let left = MAP_MARGIN / 2.0;
            let y = MAP_MARGIN / 2.0 + index as f64 * (NODE_HEIGHT + 60.0);
            let (sample_from, sample_to) = match sample {
                Sample::Leg(_) => ((left + width + 100.0, y), (left + width + 100.0 + LEGEND_SAMPLE, y)),
                Sample::Box { .. } => ((left, y), (left + width, y)),
            };
            LegendRow { text, sample, x: left + width / 2.0, y, width, sample_from, sample_to }
        })
        .collect()
}

/// One legend row per thing on the map — pinned by a test to `legend_rows()`, because the
/// layout reserves this many rows of height above the first column.
const LEGEND_ROWS: usize = 10;

/// One arrow as it will be drawn: which relation it is (if any — the legend's samples are
/// arrows too), its markers and legs, and its style.
pub(crate) struct RoutedArrow {
    /// Index into the drawn edges; `None` for a legend sample.
    pub(crate) edge: Option<usize>,
    pub(crate) plan: crate::batbelt::evm::miro::auto_deploy::PlannedLaneArrow,
    pub(crate) style: ConnectorStyle,
}

/// Where every arrow meets its boxes, and where it runs in between: lanes, corridors and
/// legs, decided with nothing on the board.
///
/// In `prepare` and not in `draw`, because the call count comes from here — an arrow that
/// skips `s` columns is `2s + 2` markers and `2s + 3` legs, and an estimate that assumes one
/// lane per arrow is an estimate that lies the moment the picture needs a corridor.
fn route_arrows(edges: &[Edge], layout: &GraphLayout, with_legend: bool) -> Vec<RoutedArrow> {
    use crate::batbelt::evm::miro::auto_deploy::{plan_lane_chain, LaneEnd, LaneSide, PlannedLaneArrow};
    use crate::batbelt::miro::client::RelativeAnchor;
    use crate::batbelt::miro::layout::{assign_lanes, LANE_PITCH};

    struct Forward<'a> {
        index: usize,
        edge: &'a Edge,
        from: &'a PlacedNode,
        to: &'a PlacedNode,
        /// The gutters crossed, caller's side first.
        gutters: Vec<usize>,
        /// The corridor heights, in the same order: the first is the column beside the caller.
        corridors: Vec<f64>,
    }

    let mut forward: Vec<Forward> = Vec::new();
    let mut backwards: Vec<(usize, &Edge, &PlacedNode, &PlacedNode)> = Vec::new();
    for (index, edge) in edges.iter().enumerate() {
        let (Some(from), Some(to)) = (layout.node(&edge.from), layout.node(&edge.to)) else {
            continue;
        };
        if to.layer <= from.layer {
            // A cycle: the layout had to reverse it, and it runs back towards the frame's own
            // contract. Drawn red, box to box, routed by Miro — the one arrow allowed to look
            // different is the one that is a finding. It used to be dropped here without a word.
            backwards.push((index, edge, from, to));
            continue;
        }
        // The corridors, CALLER FIRST — which is now the order `insert_bend_points` produces,
        // because the caller is the one in the lower layer. Walking them the other way round
        // put every arrow that skipped two columns through the wrong column's corridor at the
        // wrong height, which is to say through the boxes.
        let corridors: Vec<f64> = layout
            .routes
            .get(index)
            .map(|bends| bends.iter().map(|(_, y)| *y).collect())
            .unwrap_or_default();
        let gutters: Vec<usize> = (from.layer..to.layer).collect();
        forward.push(Forward { index, edge, from, to, gutters, corridors });
    }

    // Where each arrow meets its two boxes. Every arrow used to leave from the caller's
    // mid-height and land on the callee's, so five arrows into one contract were one point
    // on its border. Spread along the side instead, in the order they head off: an arrow
    // going up leaves from the upper part of the side, one going down from the lower, so none
    // crosses another in the first hundred units of its life.
    let spread = |mut ends: Vec<(usize, f64)>, height: f64| -> BTreeMap<usize, f64> {
        ends.sort_by(|a, b| {
            a.1.partial_cmp(&b.1)
                .unwrap_or(std::cmp::Ordering::Equal)
                .then(a.0.cmp(&b.0))
        });
        let count = ends.len();
        let step = if count > 1 {
            // The BOX's own height, not a constant: an outside leaf is half as tall, and five
            // arrows spread over a contract's height would have left its border.
            ANCHOR_PITCH.min((height - 2.0 * ANCHOR_INSET).max(0.0) / (count - 1) as f64)
        } else {
            0.0
        };
        ends.into_iter()
            .enumerate()
            .map(|(rank, (index, _))| (index, (rank as f64 - (count as f64 - 1.0) / 2.0) * step))
            .collect()
    };
    let mut leaving: BTreeMap<&str, (f64, Vec<(usize, f64)>)> = BTreeMap::new();
    let mut landing: BTreeMap<&str, (f64, Vec<(usize, f64)>)> = BTreeMap::new();
    for arrow in &forward {
        let heads_to = arrow.corridors.first().copied().unwrap_or(arrow.to.y);
        let comes_from = arrow.corridors.last().copied().unwrap_or(arrow.from.y);
        leaving
            .entry(arrow.from.id.as_str())
            .or_insert_with(|| (arrow.from.height, Vec::new()))
            .1
            .push((arrow.index, heads_to));
        landing
            .entry(arrow.to.id.as_str())
            .or_insert_with(|| (arrow.to.height, Vec::new()))
            .1
            .push((arrow.index, comes_from));
    }
    let mut start_offset: BTreeMap<usize, f64> = BTreeMap::new();
    for (height, ends) in leaving.into_values() {
        start_offset.extend(spread(ends, height));
    }
    let mut end_offset: BTreeMap<usize, f64> = BTreeMap::new();
    for (height, ends) in landing.into_values() {
        end_offset.extend(spread(ends, height));
    }

    // Which gutters each arrow crosses, and the y it enters and leaves each one at.
    let mut crossing: BTreeMap<usize, Vec<((usize, usize), f64, f64)>> = BTreeMap::new();
    for arrow in &forward {
        let start_y = arrow.from.y + start_offset.get(&arrow.index).copied().unwrap_or(0.0);
        let end_y = arrow.to.y + end_offset.get(&arrow.index).copied().unwrap_or(0.0);
        let mut enters = start_y;
        for (step, gutter) in arrow.gutters.iter().enumerate() {
            let leaves = arrow.corridors.get(step).copied().unwrap_or(end_y);
            crossing
                .entry(*gutter)
                .or_default()
                .push(((arrow.index, step), enters, leaves));
            enters = leaves;
        }
    }

    // The lane grid, per gutter: every arrow crossing it on one grid measured from the callee
    // column's edge, ordered so two arrows that need not cross do not.
    let mut lane_of: BTreeMap<(usize, usize), f64> = BTreeMap::new();
    for (gutter, arrows) in &crossing {
        let near = layout
            .nodes
            .iter()
            .filter(|node| node.layer == *gutter)
            .map(|node| node.x + node.width / 2.0)
            .fold(f64::MIN, f64::max);
        let far = layout
            .nodes
            .iter()
            .filter(|node| node.layer == gutter + 1)
            .map(|node| node.x - node.width / 2.0)
            .fold(f64::MAX, f64::min);
        // Unchanged by the flip: a gutter still runs between column `g` and column `g + 1`,
        // and a lane is still measured from the left of the two.

        if !near.is_finite() || !far.is_finite() {
            continue;
        }
        for (key, x) in assign_lanes(arrows, near, far, LANE_PITCH) {
            lane_of.insert(key, x);
        }
    }

    let mut planned: Vec<RoutedArrow> = Vec::new();
    for arrow in &forward {
        let lanes: Vec<f64> = arrow
            .gutters
            .iter()
            .enumerate()
            .filter_map(|(step, _)| lane_of.get(&(arrow.index, step)).copied())
            .collect();
        if lanes.is_empty() {
            continue;
        }
        let start_y = arrow.from.y + start_offset.get(&arrow.index).copied().unwrap_or(0.0);
        let end_y = arrow.to.y + end_offset.get(&arrow.index).copied().unwrap_or(0.0);
        planned.push(RoutedArrow {
            edge: Some(arrow.index),
            plan: plan_lane_chain(
                &LaneEnd::Point { x: arrow.from.x + arrow.from.width / 2.0, y: start_y },
                &LaneEnd::Point { x: arrow.to.x - arrow.to.width / 2.0, y: end_y },
                &lanes,
                &arrow.corridors,
            ),
            style: style_of(arrow.edge.relation, false),
        });
    }
    // A cycle goes back the SHORT way: out of the caller's left, one row down, across to the
    // lane outside the callee's column, up, and in at the callee's left.
    //
    // Two versions came before it. Miro's own routing drew it through the middle of the frame
    // and over two boxes. Sending it under the WHOLE diagram cleared the boxes and drew a lap
    // of the entire frame — it left the top-left box, crossed the full width twice and the full
    // height once, to reach a contract two rows above. The corridor only has to clear the
    // caller's own row, and the lane outside the callee's column is empty by construction.
    for (rank, (index, edge, from, to)) in backwards.into_iter().enumerate() {
        // Just under the caller's row, inside the gutter the layout already leaves there
        // (`gutter_y` is one and a half boxes), so nothing is crossed and nothing moves.
        let corridor = from.y + from.height / 2.0 + CYCLE_GAP + rank as f64 * CYCLE_PITCH;
        let anchor = RelativeAnchor::new(0.5, 0.5);
        // Out of the LEFT, because the callee is to the left: leaving right meant crossing the
        // caller's own column before turning round.
        let down_x = from.x - from.width / 2.0 - CYCLE_GAP;
        let up_x = to.x - to.width / 2.0 - CYCLE_GAP;
        planned.push(RoutedArrow {
            edge: Some(index),
            plan: PlannedLaneArrow {
                points: vec![
                    (from.x - from.width / 2.0, from.y),
                    (down_x, from.y),
                    (down_x, corridor),
                    (up_x, corridor),
                    (up_x, to.y),
                    (to.x - to.width / 2.0, to.y),
                ],
                legs: vec![
                    (LaneSide::Marker(0), anchor, LaneSide::Marker(1), anchor, false),
                    (LaneSide::Marker(1), anchor, LaneSide::Marker(2), anchor, false),
                    (LaneSide::Marker(2), anchor, LaneSide::Marker(3), anchor, false),
                    (LaneSide::Marker(3), anchor, LaneSide::Marker(4), anchor, false),
                    (LaneSide::Marker(4), anchor, LaneSide::Marker(5), anchor, true),
                ],
            },
            style: style_of(edge.relation, true),
        });
    }
    // The legend's samples are arrows like any other, so they are counted, drawn and
    // previewed by the same code — a legend drawn by its own path is a legend that drifts.
    // Only on the legend's own frame: appended to every frame, they drew five loose strokes
    // over the top-left corner of each contract's diagram.
    for row in legend_rows().into_iter().filter(|_| with_legend) {
        let Sample::Leg(style) = row.sample else { continue };
        planned.push(RoutedArrow {
            edge: None,
            plan: PlannedLaneArrow {
                points: vec![row.sample_from, row.sample_to],
                legs: vec![(
                    LaneSide::Marker(0),
                    RelativeAnchor::new(1.0, 0.5),
                    LaneSide::Marker(1),
                    RelativeAnchor::new(0.0, 0.5),
                    true,
                )],
            },
            style,
        });
    }

    // Every arrow, with its zero-length legs collapsed — see `tighten`.
    planned
        .into_iter()
        .map(|arrow| RoutedArrow { plan: tighten(arrow.plan), ..arrow })
        .collect()
}

/// Drop the zero-length legs of a planned arrow, and the markers they would have joined.
///
/// A lane chain places two markers per gutter — where the arrow enters it and where it leaves.
/// When the arrow runs level, those two are the same point, and two markers at identical
/// coordinates come back from the bulk endpoint as ONE item; Miro then refuses the connector
/// with `"The startitem id and enditem id cannot be the same"`. Four relations of a real board
/// were lost that way, silently until the failure learned to quote the API.
///
/// Merging them is also the right picture: a leg of no length is a leg nobody can see.
fn tighten(
    plan: crate::batbelt::evm::miro::auto_deploy::PlannedLaneArrow,
) -> crate::batbelt::evm::miro::auto_deploy::PlannedLaneArrow {
    use crate::batbelt::evm::miro::auto_deploy::{LaneSide, PlannedLaneArrow};

    let same = |a: (f64, f64), b: (f64, f64)| (a.0 - b.0).abs() < 0.5 && (a.1 - b.1).abs() < 0.5;
    // Each old marker keeps its own new index, unless an EARLIER one already sits on that point.
    let mut points: Vec<(f64, f64)> = Vec::new();
    let mut moved: Vec<usize> = Vec::new();
    for point in &plan.points {
        match points.iter().position(|kept| same(*kept, *point)) {
            Some(index) => moved.push(index),
            None => {
                points.push(*point);
                moved.push(points.len() - 1);
            }
        }
    }
    let at = |side: &LaneSide| match side {
        LaneSide::Marker(index) => LaneSide::Marker(moved.get(*index).copied().unwrap_or(*index)),
        LaneSide::Item(id) => LaneSide::Item(id.clone()),
    };
    let mut legs: Vec<_> = plan
        .legs
        .iter()
        .map(|(from, from_anchor, to, to_anchor, head)| {
            (at(from), *from_anchor, at(to), *to_anchor, *head)
        })
        .filter(|(from, _, to, _, _)| match (from, to) {
            (LaneSide::Marker(a), LaneSide::Marker(b)) => a != b,
            _ => true,
        })
        .collect();
    // The head rides on the last leg: dropping the one that carried it would leave an arrow
    // with no point on it.
    if !legs.is_empty() && !legs.iter().any(|leg| leg.4) {
        let last = legs.len() - 1;
        legs[last].4 = true;
    }
    PlannedLaneArrow { points, legs }
}

/// Draw the planned map into a local PNG: every frame's border and title, its boxes, and every
/// leg of every arrow exactly where the board would put them.
///
/// It is the same plan the drawing transcribes, so what this shows is what would be drawn —
/// which is the point. Judging a layout by deploying it costs a minute and a board full of
/// frames nobody wants.
pub fn preview(prepared: &PreparedMap, path: &str) -> Result<(), EvmMiroError> {
    use crate::batbelt::evm::miro::auto_deploy::LaneSide;
    use image::{Rgba, RgbaImage};

    let scale = (2_600.0 / prepared.width).min(1.0);
    let width = (prepared.width * scale).round().max(1.0) as u32;
    let height = (prepared.height * scale).round().max(1.0) as u32;
    let mut canvas = RgbaImage::from_pixel(width, height, Rgba([250, 250, 250, 255]));

    for frame in &prepared.frames {
        // Frame-local, exactly as Miro reads a child item's position, plus where the frame sits
        // in the block.
        let at = |x: f64, y: f64| {
            (
                ((frame.left + x) * scale) as i64,
                ((frame.top + y) * scale) as i64,
            )
        };
        let border = parse_colour(BOX_BORDER);
        let (frame_left, frame_top) = at(0.0, 0.0);
        let (frame_right, frame_bottom) = at(frame.width, frame.height);
        for (from, to) in [
            ((frame_left, frame_top), (frame_right, frame_top)),
            ((frame_right, frame_top), (frame_right, frame_bottom)),
            ((frame_right, frame_bottom), (frame_left, frame_bottom)),
            ((frame_left, frame_bottom), (frame_left, frame_top)),
        ] {
            draw_stroke(&mut canvas, from, to, border, ConnectorStroke::Solid);
        }

        // Every box with the fill and border the board will give it — what a box IS and what it
        // DOES are the two things a reader takes from it before reading its name, so the preview
        // has to show them or it is previewing a different picture.
        let mut boxes: Vec<(f64, f64, f64, f64, &str, &str, usize)> = Vec::new();
        for node in &frame.layout.nodes {
            let (repeat_border, thickness) = frame.border_of(&node.id);
            let (fill, outside_border, _) = frame.paint_of(&node.id, &prepared.marked);
            // A repeated contract's own colour outranks the plain border; an outside leaf has
            // no repeat colour, so its interface colour is what shows.
            let border = if repeat_border == BOX_BORDER { outside_border } else { repeat_border };
            boxes.push((node.x, node.y, node.width, node.height, fill, border, thickness));
        }
        for node in &frame.strip {
            boxes.push((node.x, node.y, node.width, node.height, STRIP_FILL, BOX_BORDER, BORDER_WIDTH));
        }
        if frame.is_legend() {
            for row in legend_rows() {
                let (fill, border) = match row.sample {
                    Sample::Leg(_) => (BOX_FILL, BOX_BORDER),
                    Sample::Box { fill, border, .. } => (fill, border),
                };
                let thickness = if border == BOX_BORDER { BORDER_WIDTH } else { REPEAT_BORDER_WIDTH };
                boxes.push((row.x, row.y, row.width, NODE_HEIGHT, fill, border, thickness));
            }
        }
        for (x, y, box_width, box_height, fill, box_border, thickness) in boxes {
            let (left, top) = at(x - box_width / 2.0, y - box_height / 2.0);
            let (right, bottom) = at(x + box_width / 2.0, y + box_height / 2.0);
            fill_rect(&mut canvas, (left, top), (right, bottom), parse_colour(fill));
            let edge = parse_colour(box_border);
            // Drawn as nested rectangles, one per unit of thickness at this scale, so a border
            // the board draws thick is thick in the preview too — otherwise the preview answers
            // a question about the picture that the picture answers differently.
            let rings = ((thickness as f64 * scale).round() as i64).max(1);
            for ring in 0..rings {
                for (from, to) in [
                    ((left + ring, top + ring), (right - ring, top + ring)),
                    ((right - ring, top + ring), (right - ring, bottom - ring)),
                    ((right - ring, bottom - ring), (left + ring, bottom - ring)),
                    ((left + ring, bottom - ring), (left + ring, top + ring)),
                ] {
                    draw_stroke(&mut canvas, from, to, edge, ConnectorStroke::Solid);
                }
            }
        }

        // Every leg of every arrow, in its stroke and colour, from the markers the plan places.
        for arrow in &frame.arrows {
            let colour = parse_colour(&arrow.style.stroke_color);
            for (from, _, to, _, _) in &arrow.plan.legs {
                let point = |side: &LaneSide| match side {
                    LaneSide::Marker(index) => arrow.plan.points.get(*index).copied(),
                    LaneSide::Item(_) => None,
                };
                let (Some((from_x, from_y)), Some((to_x, to_y))) = (point(from), point(to)) else {
                    continue;
                };
                draw_stroke(&mut canvas, at(from_x, from_y), at(to_x, to_y), colour, arrow.style.stroke);
            }
        }
    }

    canvas
        .save(path)
        .map_err(|error| {
            Report::new(EvmMiroError).attach_printable(format!("cannot write {path}: {error}"))
        })?;
    println!("  preview written to {}", path.bold());
    Ok(())
}

/// A line in one of the three strokes, so the preview tells a question from a fact the way
/// the board will. Lengths are in pixels of the scaled canvas: a dash long enough to read as
/// a dash at a sixth of board scale, a dot that is not a dash.
fn draw_stroke(
    canvas: &mut image::RgbaImage,
    from: (i64, i64),
    to: (i64, i64),
    colour: image::Rgba<u8>,
    stroke: ConnectorStroke,
) {
    let (on, off) = match stroke {
        ConnectorStroke::Solid => (usize::MAX, 0),
        ConnectorStroke::Dashed => (12, 8),
        ConnectorStroke::Dotted => (3, 6),
    };
    let mut walked = 0usize;
    for (x, y) in bresenham(from, to) {
        if walked % (on.saturating_add(off)) < on {
            for dy in -1..=1 {
                for dx in -1..=1 {
                    let (px, py) = (x + dx, y + dy);
                    if px >= 0 && py >= 0 && (px as u32) < canvas.width() && (py as u32) < canvas.height() {
                        canvas.put_pixel(px as u32, py as u32, colour);
                    }
                }
            }
        }
        walked += 1;
    }
}

/// Every pixel of the line from `from` to `to`, in order.
fn bresenham(from: (i64, i64), to: (i64, i64)) -> Vec<(i64, i64)> {
    let mut pixels = Vec::new();
    let (mut x, mut y) = from;
    let dx = (to.0 - x).abs();
    let dy = -(to.1 - y).abs();
    let step_x = if x < to.0 { 1 } else { -1 };
    let step_y = if y < to.1 { 1 } else { -1 };
    let mut error = dx + dy;
    loop {
        pixels.push((x, y));
        if x == to.0 && y == to.1 {
            break;
        }
        let double = 2 * error;
        if double >= dy {
            error += dy;
            x += step_x;
        }
        if double <= dx {
            error += dx;
            y += step_y;
        }
    }
    pixels
}

fn fill_rect(canvas: &mut image::RgbaImage, top_left: (i64, i64), bottom_right: (i64, i64), colour: image::Rgba<u8>) {
    for y in top_left.1.max(0)..bottom_right.1.min(canvas.height() as i64) {
        for x in top_left.0.max(0)..bottom_right.0.min(canvas.width() as i64) {
            canvas.put_pixel(x as u32, y as u32, colour);
        }
    }
}

/// `#rrggbb` as a pixel. A colour this tool did not write is not worth failing over, so an
/// unparseable one is drawn grey.
fn parse_colour(hex: &str) -> image::Rgba<u8> {
    let channel = |range: std::ops::Range<usize>| {
        hex.get(range)
            .and_then(|part| u8::from_str_radix(part, 16).ok())
            .unwrap_or(128)
    };
    image::Rgba([channel(1..3), channel(3..5), channel(5..7), 255])
}

/// Measure the map. Local: no client, no board, no renders.
///
/// One frame per top caller, plus a small frame for the legend and whatever is connected to
/// nothing — see `partition_frames`. The frames are packed into a block here, in frame-local
/// coordinates, so the only thing the board decides is where that block starts.
pub fn prepare(metadata: &EvmBatMetadata, options: &MapOptions) -> Result<PreparedMap, EvmMiroError> {
    let all = relations(metadata);
    // The reader's own list, from the registry and from this run's flag. Names only: what it
    // means — an audit's scope, a subsystem — is theirs, and bat stays agnostic.
    let marked: BTreeSet<String> = metadata
        .marked_contracts
        .iter()
        .cloned()
        .chain(options.mark.iter().cloned())
        .collect();

    let mut edges = drawn_edges(&all, options.no_boundaries);
    let (leaves, unnamed) = method_leaves(metadata, &edges, options.all_methods);
    edges.extend(leaves);
    if edges.is_empty() {
        return Err(Report::new(EvmMiroError)
            .attach_printable("no relations between contracts — run `bat-cli sonar` first"));
    }


    let mut frames: Vec<PreparedFrame> = partition_frames(&edges)
        .into_iter()
        .map(|plan| {
            // No localizing: a frame is a tree, so nothing inside it is shared and nothing can
            // cross. The crossing count is still reported, as the certificate that it stays so.
            let mine = plan.edges;
            let layout = layout_tree(&plan.root, &mine);
            let arrows = route_arrows(&mine, &layout, false);
            // Tall enough for what the arrows actually use: a cycle's corridor runs under the
            // lowest box, and a frame measured from the boxes alone would cut it off.
            let used = arrows
                .iter()
                .flat_map(|arrow| arrow.plan.points.iter())
                .map(|(_, y)| *y)
                .fold(0.0_f64, f64::max);
            PreparedFrame {
                title: frame_title(&plan.root),
                root: plan.root.clone(),
                fills: PreparedFrame::outside_fills(&mine),
                borders: PreparedFrame::repeat_borders(&mine),
                width: layout.frame_width,
                height: layout.frame_height.max(used + MAP_MARGIN),
                crossings: layout.crossings,
                edges: mine,
                layout,
                arrows,
                strip: Vec::new(),
                left: 0.0,
                top: 0.0,
            }
        })
        .collect();
    // The legend FIRST: it is the frame a reader opens to learn how to read the others, so it
    // takes the top-left of the block and is the first one created. It used to be appended, so
    // it landed wherever the packing had room — usually last, at the bottom right.
    frames.insert(0, legend_frame(&unconnected(metadata, &edges)));
    pack_frames(&mut frames);

    let width = frames
        .iter()
        .map(|frame| frame.left + frame.width)
        .fold(0.0_f64, f64::max);
    let height = frames
        .iter()
        .map(|frame| frame.top + frame.height)
        .fold(0.0_f64, f64::max);
    let calls = ApiCalls {
        frames: frames.len(),
        boxes: frames
            .iter()
            .map(|frame| frame.layout.nodes.len() + frame.boxes_of_its_own())
            .sum(),
        markers: frames
            .iter()
            .flat_map(|frame| frame.arrows.iter())
            .map(|arrow| arrow.plan.points.len())
            .sum(),
        connectors: frames
            .iter()
            .flat_map(|frame| frame.arrows.iter())
            .map(|arrow| arrow.plan.legs.len())
            .sum(),
    };

    Ok(PreparedMap { edges, frames, marked, width, height, calls, unnamed })
}

/// A frame's title: whose frame it is. One phrasing, used by the title, by `--contract` and by
/// the card that points at it, so the three can never drift apart.
fn frame_title(root: &str) -> String {
    format!("map: what {root} talks to")
}

/// The legend, and the contracts no relation touches, on a frame of their own.
///
/// One copy for the whole map rather than one per frame: seven rows repeated on every frame is
/// seven rows of noise per frame, and the reader needs them once.
fn legend_frame(alone: &[String]) -> PreparedFrame {
    let rows = legend_rows();
    let mut strip = strip_of(alone, rows.last().map(|row| row.y).unwrap_or(0.0) + NODE_HEIGHT * 2.0);
    let width = rows
        .iter()
        .map(|row| row.x + row.width / 2.0 + LEGEND_SAMPLE + MAP_MARGIN)
        .chain(strip.iter().map(|node| node.x + node.width / 2.0 + MAP_MARGIN))
        .fold(0.0_f64, f64::max);
    let height = rows
        .iter()
        .map(|row| row.y)
        .chain(strip.iter().map(|node| node.y))
        .fold(0.0_f64, f64::max)
        + NODE_HEIGHT / 2.0
        + MAP_MARGIN;
    // Its samples are arrows like any other, drawn and previewed by the same code.
    let arrows = route_arrows(&[], &crate::batbelt::miro::layout::GraphLayout {
        nodes: Vec::new(),
        routes: Vec::new(),
        back_edges: Vec::new(),
        bbox_width: 0.0,
        bbox_height: 0.0,
        frame_width: width,
        frame_height: height,
        crossings: 0,
    }, true);
    strip.shrink_to_fit();
    PreparedFrame {
        title: "map: legend".to_string(),
        root: String::new(),
        fills: BTreeMap::new(),
        borders: BTreeMap::new(),
        edges: Vec::new(),
        layout: crate::batbelt::miro::layout::GraphLayout {
            nodes: Vec::new(),
            routes: Vec::new(),
            back_edges: Vec::new(),
            bbox_width: width,
            bbox_height: height,
            frame_width: width,
            frame_height: height,
            crossings: 0,
        },
        arrows,
        strip,
        width,
        height,
        crossings: 0,
        left: 0.0,
        top: 0.0,
    }
}

/// Place the frames in rows, left to right, wrapping at a width that keeps the block roughly
/// as wide as it is tall.
///
/// Miro refuses a frame that overlaps another with a 500, so this is not cosmetic. Rows rather
/// than one long line because a map of eight frames in a row is a map nobody can see at once —
/// the whole reason there are frames at all.
fn pack_frames(frames: &mut [PreparedFrame]) {
    let area: f64 = frames.iter().map(|frame| frame.width * frame.height).sum();
    let widest = frames.iter().map(|frame| frame.width).fold(0.0_f64, f64::max);
    // Two of the widest frames side by side, at least: `sqrt(area)` alone is the width of the
    // single widest frame whenever one frame dominates, which lays every other frame out in a
    // column one frame wide and makes the block a mile tall.
    let target = area.sqrt().max(widest * 2.0 + MAP_MARGIN);
    let (mut x, mut y, mut row_height) = (0.0_f64, 0.0_f64, 0.0_f64);
    for frame in frames.iter_mut() {
        if x > 0.0 && x + frame.width > target {
            x = 0.0;
            y += row_height + MAP_MARGIN;
            row_height = 0.0;
        }
        frame.left = x;
        frame.top = y;
        x += frame.width + MAP_MARGIN;
        row_height = row_height.max(frame.height);
    }
}

/// The strip's boxes: a heading, then one box per unconnected contract, stacked in a column
/// under the legend's rows.
fn strip_of(names: &[String], top: f64) -> Vec<PlacedNode> {
    if names.is_empty() {
        return Vec::new();
    }
    let heading = strip_heading_text();
    let width = names
        .iter()
        .map(|name| node_width(name))
        .fold(node_width(heading), f64::max);
    std::iter::once(STRIP_HEADING.to_string())
        .chain(names.iter().cloned())
        .enumerate()
        .map(|(row, id)| PlacedNode {
            id,
            layer: 0,
            x: MAP_MARGIN / 2.0 + width / 2.0,
            y: top + row as f64 * (NODE_HEIGHT + 60.0),
            width,
            height: NODE_HEIGHT,
        })
        .collect()
}

/// The words on the strip's heading box.
fn strip_heading_text() -> &'static str {
    STRIP_HEADING.trim_start_matches('\u{0}')
}

/// The words a box carries: a contract's name, or the strip's heading.
fn box_text(id: &str) -> String {
    if id == STRIP_HEADING {
        return strip_heading_text().to_string();
    }
    // A destination says WHO, and nothing else: the method it came from is the box beside it.
    if let Some(to) = destination_of(id) {
        // An address nobody has named reads as one. Without the word the box looked like a
        // contract called `yieldSink`, and the reader went looking for its source.
        // The mark is on the whole name, so it comes off before the variable is read out.
        let (to, unnamed) = match to.strip_suffix(ADDRESS_MARK) {
            Some(point) => (point, true),
            None => (to, false),
        };
        let to = match to.split_once(VARIABLE_MARK) {
            // The variable first, because that is what tells one deployment from another; the
            // contract after it, because that is the code to open.
            Some((variable, held)) => format!("{variable} ({held})"),
            None => to.to_string(),
        };
        return match unnamed {
            true => format!("{to} (address)"),
            false => to,
        };
    }
    // A box that names the variable holding it: `opexTreasury (Treasury)`, one of five
    // deployments of one contract.
    if let Some((variable, held)) = original_of(id).split_once(VARIABLE_MARK) {
        return format!("{variable} ({held})");
    }
    // A method leaf says the METHOD, written as Solidity writes one: `vault()`, not `vault`.
    // Without the parentheses a getter's box reads as a destination — `ICLPoolManager → vault`
    // looked like a second contract rather than the call that asks for its address.
    match method_of(id) {
        // `call{value}` already says it is a call; `call{value}()` reads like a method named
        // after an option block.
        Some(method) if method.ends_with('}') => method.to_string(),
        Some(method) => format!("{method}()"),
        None => original_of(id).to_string(),
    }
}
/// The deployable contracts that have no relation at all, and so no box.
///
/// A contract nothing calls and that calls nothing is not a contract the map can place — but
/// it IS part of the system, and a map that simply omits it is a map the reader trusts more
/// than it deserves. Listed in the report instead.
pub fn unconnected(metadata: &EvmBatMetadata, edges: &[Edge]) -> Vec<String> {
    use crate::batbelt::evm::types::EvmContractType;
    let drawn: BTreeSet<&str> = edges
        .iter()
        .flat_map(|edge| [edge.from.as_str(), edge.to.as_str()])
        .collect();
    metadata
        .contracts
        .iter()
        .filter(|contract| {
            !contract.vendored
                && matches!(contract.contract_type, EvmContractType::Contract)
                && !drawn.contains(contract.name.as_str())
        })
        .map(|contract| contract.name.clone())
        .collect()
}

/// `new X(...)` of code this repository does not own.
///
/// A factory that deploys somebody else's contract is worth a line even though the thing it
/// deploys gets no box: it is still the system creating an address at runtime.
pub fn vendored_creations(metadata: &EvmBatMetadata) -> Vec<String> {
    let mut found: BTreeSet<String> = BTreeSet::new();
    for contract in metadata.contracts.iter().filter(|c| !c.vendored) {
        for function in &contract.functions {
            for callee in callees_of(metadata, &function.metadata_id) {
                let Some(name) = callee.strip_suffix(".constructor") else {
                    continue;
                };
                let vendored = metadata
                    .contract_in_scope(name, &contract.file_path)
                    .map(|target| target.vendored)
                    .unwrap_or(true);
                if vendored {
                    found.insert(format!("{}.{} creates {name}", contract.name, function.name));
                }
            }
        }
    }
    found.into_iter().collect()
}

/// Everything the drawing needs, measured, with nothing on the board yet.
///
/// The same split `storage` and `effects` have, and for the same two reasons: a frame has to be
/// created at its final size, and a failure must leave nothing half-drawn. It also lets
/// `--dry-run` say what a real run would cost, because the call count is arithmetic over this
/// value and not something only the drawing knows.
pub struct PreparedMap {
    /// Every relation, before any frame copied one: what the terminal reports.
    edges: Vec<Edge>,
    /// The contracts the reader asked to see (`bat-cli mark`), drawn with a filled background.
    marked: BTreeSet<String>,
    /// One per top caller, plus the legend's. Their `left`/`top` are inside the block.
    frames: Vec<PreparedFrame>,
    pub width: f64,
    pub height: f64,
    pub calls: ApiCalls,
    /// The call-site arguments the map could not turn into an entity: where to look, and the
    /// key that records the answer. Reported, never guessed.
    pub unnamed: Vec<UnnamedParty>,
}

/// One frame of the map: what one contract talks to, laid out on its own.
pub struct PreparedFrame {
    title: String,
    /// The contract this frame is about — the tree's root, which a cycle's frame cannot get
    /// from the edges because every member of a cycle is pointed at.
    root: String,
    /// This frame's relations, with the copies `localize` made — not the map's.
    edges: Vec<Edge>,
    layout: GraphLayout,
    arrows: Vec<RoutedArrow>,
    /// One fill per interface drawn here, so every copy of one interface looks like the others
    /// and no two interfaces look alike.
    fills: BTreeMap<String, &'static str>,
    /// One border per contract drawn here MORE THAN ONCE, so its copies read as one address.
    borders: BTreeMap<String, &'static str>,
    /// Only the legend frame has these: the contracts no relation touches.
    strip: Vec<PlacedNode>,
    width: f64,
    height: f64,
    /// Arrow pairs that still cross after localizing — the certificate, printed per frame so a
    /// change to the layout is judged by a number instead of by looking at a PNG.
    crossings: usize,
    /// Inside the block, before the board says where the block starts.
    left: f64,
    top: f64,
}

impl PreparedFrame {
    /// Whose frame this is, read back off its title.
    fn root(&self) -> &str {
        self.title
            .strip_prefix("map: what ")
            .and_then(|rest| rest.strip_suffix(" talks to"))
            .unwrap_or(&self.title)
    }

    /// Every contract drawn here, by its real name and once: a frame draws a contract twice on
    /// purpose, and for "where is this shown" the two copies are one frame.
    fn contracts_shown(&self) -> Vec<String> {
        let mut names: BTreeSet<&str> = BTreeSet::new();
        for node in &self.layout.nodes {
            if !is_outside(&node.id) {
                names.insert(original_of(&node.id));
            }
        }
        names.into_iter().map(str::to_string).collect()
    }

    /// One fill per interface this frame draws, by the order the names sort in — so the same
    /// frame drawn twice gives the same colours, and two interfaces never share one.
    fn outside_fills(edges: &[Edge]) -> BTreeMap<String, &'static str> {
        let names: BTreeSet<&str> = edges
            .iter()
            .filter(|edge| is_outside(&edge.to))
            .map(|edge| original_of(&edge.to))
            .collect();
        names
            .into_iter()
            .enumerate()
            .map(|(index, name)| {
                // Past the palette, grey: a ninth colour nobody can tell from the first is
                // worse than a box that plainly says "outside and not colour-coded".
                // Past the palette, BLACK. It used to fall back to a pale grey, which was a
                // fill colour and became an invisible label the moment this channel turned into
                // a border and a name: `IWrappedHype` was the ninth interface of a frame and
                // could not be read at all. A plain black dotted box still says "outside"; it
                // just does not say which one by colour.
                (name.to_string(), OUTSIDE_FILLS.get(index).copied().unwrap_or(BOX_BORDER))
            })
            .collect()
    }

    /// One border per contract this frame draws more than once, by the order the names sort in.
    fn repeat_borders(edges: &[Edge]) -> BTreeMap<String, &'static str> {
        // Count the distinct BOXES per contract: `Treasury` and `Treasury#2` are two, while two
        // arrows into the same box are one.
        let mut boxes: BTreeMap<&str, BTreeSet<&str>> = BTreeMap::new();
        for edge in edges {
            for id in [edge.from.as_str(), edge.to.as_str()] {
                // A DESTINATION is an entity drawn here like any other, and it is the box most
                // often repeated — `StakingFeeConverter` as a party under four different
                // methods. Its id starts with the interface the call went through, so reading
                // the name off the front counted them all as copies of `IERC20` and coloured
                // none of them.
                if !is_outside(id) || destination_of(id).is_some() {
                    boxes.entry(drawn_entity(id)).or_default().insert(id);
                }
            }
        }
        boxes
            .into_iter()
            .filter(|(_, copies)| copies.len() > 1)
            .enumerate()
            .filter_map(|(index, (name, _))| {
                // Past the palette, the plain border: a ninth colour nobody can tell from the
                // first says less than saying nothing.
                REPEAT_BORDERS.get(index).map(|colour| (name.to_string(), *colour))
            })
            .collect()
    }

    /// The border a box of this frame gets, and how thick: its contract's own colour, drawn
    /// thick enough to read at the zoom where the frame fits, when that contract is drawn here
    /// more than once — and the plain thin one otherwise.
    fn border_of(&self, id: &str) -> (&'static str, usize) {
        if is_outside(id) {
            return (BOX_BORDER, BORDER_WIDTH);
        }
        match self.borders.get(drawn_entity(id)) {
            Some(colour) => (colour, REPEAT_BORDER_WIDTH),
            None => (BOX_BORDER, BORDER_WIDTH),
        }
    }

    /// How a box is painted: its fill, its text colour and whether its border is dotted.
    ///
    /// Three channels, one meaning each, and the loudest goes to what the reader asked for:
    ///
    /// - a MARKED contract gets the FILL, because a background is what carries at the zoom where
    ///   a whole frame fits — a border does not, which the cards and the repeat borders both
    ///   proved;
    /// - an OUTSIDE leaf gives up the fill and takes a dotted border with its name in the
    ///   interface's colour: it is read once the reader has found the contract that calls it, so
    ///   it can afford the quieter channel, and the coloured text still ties its copies together;
    /// - a contract drawn TWICE keeps its solid coloured border (see `border_of`).
    fn paint_of(&self, id: &str, marked: &BTreeSet<String>) -> (&'static str, &'static str, &'static str) {
        // A destination is an ENTITY, not a type the caller declared: it is drawn like a
        // contract, in black, at a contract's size. The one it carries an address for and
        // nobody has named is dashed — the map's own stroke for a question.
        if let Some(to) = destination_of(id) {
            if to.ends_with(ADDRESS_MARK) {
                return (BOX_FILL, BOX_BORDER, "dashed");
            }
            if marked.contains(entity_named(to)) {
                return (MARK_FILL, BOX_BORDER, "normal");
            }
            return (BOX_FILL, BOX_BORDER, "normal");
        }
        if is_outside(id) {
            let colour = self.fills.get(original_of(id)).copied().unwrap_or(BOX_BORDER);
            return (BOX_FILL, colour, "dotted");
        }
        if marked.contains(original_of(id)) {
            return (MARK_FILL, BOX_BORDER, "normal");
        }
        (BOX_FILL, BOX_BORDER, "normal")
    }

    /// Boxes this frame draws that are not its laid-out contracts: the legend's rows and the
    /// strip.
    fn boxes_of_its_own(&self) -> usize {
        self.strip.len() + if self.is_legend() { LEGEND_ROWS } else { 0 }
    }

    /// Is this the legend's frame? It carries no relations of its own.
    fn is_legend(&self) -> bool {
        self.edges.is_empty()
    }
}

impl PreparedMap {
    /// How many drawn relations run against the hierarchy — the red arrows.
    fn backwards(&self) -> usize {
        self.frames
            .iter()
            .flat_map(|frame| frame.arrows.iter())
            .filter(|arrow| arrow.edge.is_some() && arrow.style.stroke_color == CYCLE_COLOUR)
            .count()
    }

    /// Keep only the frame of one contract, and the legend.
    ///
    /// The frames were all measured, which costs nothing but arithmetic; what is expensive is
    /// drawing them, and that is what this prevents. The block is repacked, so a single frame
    /// opens where a single frame belongs rather than in the corner of a block-sized hole.
    pub fn keep_only(&mut self, contract: &str) -> Result<(), EvmMiroError> {
        let wanted = frame_title(contract);
        if !self.frames.iter().any(|frame| frame.title == wanted) {
            let known: Vec<&str> = self
                .frames
                .iter()
                .filter(|frame| !frame.is_legend())
                .filter_map(|frame| frame.title.strip_prefix("map: what "))
                .filter_map(|rest| rest.strip_suffix(" talks to"))
                .collect();
            return Err(Report::new(EvmMiroError)
                .attach_printable(format!("no frame for `{contract}`: it is not a top caller"))
                .attach_printable(format!("the map has frames for: {}", known.join(", "))));
        }
        self.frames.retain(|frame| frame.title == wanted || frame.is_legend());
        pack_frames(&mut self.frames);
        self.width = self.frames.iter().map(|frame| frame.left + frame.width).fold(0.0, f64::max);
        self.height = self.frames.iter().map(|frame| frame.top + frame.height).fold(0.0, f64::max);
        self.calls = ApiCalls {
            frames: self.frames.len(),
            boxes: self
                .frames
                .iter()
                .map(|frame| frame.layout.nodes.len() + frame.boxes_of_its_own())
                .sum(),
            markers: self
                .frames
                .iter()
                .flat_map(|frame| frame.arrows.iter())
                .map(|arrow| arrow.plan.points.len())
                .sum(),
            connectors: self
                .frames
                .iter()
                .flat_map(|frame| frame.arrows.iter())
                .map(|arrow| arrow.plan.legs.len())
                .sum(),
        };
        Ok(())
    }

    /// Nothing is rendered any more, so there is nothing to throw away — kept so a dry run and
    /// a failure path read the same as the deploy's.
    pub fn discard(&self) {}

    /// What a real run would cost, in the terminal, before it costs it.
    /// Every frame as an indented TREE of what it draws: the picture, in words.
    ///
    /// A preview PNG cannot carry the names — a map is thirty thousand board units wide and a
    /// name comes out three pixels tall — so the only way to check that a leaf has the children
    /// it should is to read them. This is that reading: one line per box, indented under the box
    /// that points at it, with what the arrow means when it is not a plain call.
    pub fn tree(&self) -> Vec<String> {
        let mut lines = Vec::new();
        for frame in &self.frames {
            if frame.is_legend() {
                continue;
            }
            lines.push(String::new());
            lines.push(frame.title.clone());
            let mut children: BTreeMap<&str, Vec<&Edge>> = BTreeMap::new();
            for edge in &frame.edges {
                children.entry(edge.from.as_str()).or_default().push(edge);
            }
            let mut walked: BTreeSet<&str> = BTreeSet::new();
            let mut stack: Vec<(&str, usize, Option<Relation>)> =
                vec![(frame.root.as_str(), 0, None)];
            while let Some((id, depth, relation)) = stack.pop() {
                let note = match relation {
                    Some(Relation::Creates) => "  (creates)",
                    // Not "never called": value reaches it as a PARTY of somebody else's
                    // call — `AscendLaunchpad` pays six treasuries it never calls a method on.
                    Some(Relation::WiresAtConstruction) => "  (wired at construction)",
                    Some(Relation::Unresolved) => "  (unresolved binding)",
                    // The tree stops under a read, and without the word it read as an ordinary
                    // call whose callee happens to do nothing.
                    Some(Relation::Reads) => "  (reads)",
                    _ => "",
                };
                // A back edge closes a cycle: printed where it lands, said so, and not
                // followed, or the walk would never end.
                let seen = !walked.insert(id);
                let note = match seen {
                    true => "  (again — a cycle)",
                    false => note,
                };
                lines.push(format!("{:indent$}{}{note}", "", box_text(id), indent = depth * 2 + 2));
                if seen {
                    continue;
                }
                let mut below = children.get(id).cloned().unwrap_or_default();
                below.sort_by(|a, b| b.to.cmp(&a.to));
                for edge in below {
                    stack.push((edge.to.as_str(), depth + 1, Some(edge.relation)));
                }
            }
        }
        lines
    }

    pub fn estimate(&self) -> Vec<String> {
        let mut lines = vec![format!(
            "{} frame(s), {} box(es), {} relation(s) ({} backwards), {} crossing(s) left",
            self.frames.len(),
            self.calls.boxes,
            self.edges.len(),
            self.backwards(),
            self.frames.iter().map(|frame| frame.crossings).sum::<usize>(),
        )];
        // Per frame, because "which frame is still a mesh" is the question a total cannot
        // answer, and the only one worth asking of a map that has been redrawn five times.
        for frame in &self.frames {
            if frame.is_legend() {
                continue;
            }
            lines.push(format!(
                "  {:<46} {} box(es), {} relation(s), {} crossing(s)",
                frame.title,
                frame.layout.nodes.len(),
                frame.edges.len(),
                frame.crossings
            ));
        }
        lines.push(format!(
            "block: {} × {} board units — API calls: {} frames + {} boxes + {} markers + {} connectors = {}",
            self.width.round(),
            self.height.round(),
            self.calls.frames,
            self.calls.boxes,
            self.calls.markers,
            self.calls.connectors,
            self.calls.total()
        ));
        lines.push(format!(
            "       {:.1}s at Miro's ceiling of 16.7 writes a second, if nothing else limits it",
            self.calls.seconds_at_the_ceiling()
        ));
        lines.push("placement: needs the board, which a dry run does not read".to_string());
        lines
    }
}

/// What a real run will ask of Miro, counted before it asks.
#[derive(Debug, Clone, Copy, Default, PartialEq)]
pub struct ApiCalls {
    pub frames: usize,
    pub boxes: usize,
    pub markers: usize,
    pub connectors: usize,
}

impl ApiCalls {
    pub fn total(&self) -> usize {
        self.frames + self.boxes + self.markers + self.connectors
    }

    /// How long that many writes take at Miro's own ceiling.
    ///
    /// The budget is 100 000 credits a minute and a level-2 write costs 100, so 16.7 writes a
    /// second is the wall nothing gets past — the deploy measured 16.2 with 24 permits and no
    /// retries, which is that wall. Anything slower than this estimate is latency or an error,
    /// and that is what makes the number worth printing.
    pub fn seconds_at_the_ceiling(&self) -> f64 {
        self.total() as f64 / 16.7
    }
}

/// The two ends of the hierarchy, as lines for the terminal.
///
/// A TOP CALLER is a contract nothing in scope depends on: where a reader starts, and what the
/// map makes a frame for. A FOUNDATION is one that depends on nothing: what has to exist before
/// any of the others, which is the order the board reads left to right.
///
/// Neither is in the file tree, and neither is a guess — both fall straight out of the
/// relations.
pub fn hierarchy(all: &[Edge], no_boundaries: bool) -> Vec<String> {
    // The TOP CALLERS are read off the same edges the map frames, so the list and the frames
    // cannot disagree: a contract whose only relation leaves the repository is still a contract
    // nothing in scope depends on, and it still gets a frame.
    let framed = drawn_edges(all, no_boundaries);
    // The FOUNDATIONS are read off this repository's own relations: what leaves the code is a
    // leaf of whoever calls it, never a rung of the hierarchy, and listing `IERC20` as
    // something "everything else needs" said nothing true about the system.
    let edges: Vec<Edge> = all
        .iter()
        .filter(|edge| edge.relation != Relation::Boundary)
        .cloned()
        .collect();
    let names: BTreeSet<&str> = edges
        .iter()
        .flat_map(|edge| [held_entity(&edge.from), held_entity(&edge.to)])
        .collect();
    // By ENTITY, like the frames: `vault%AscendYieldVault` is the vault, and reading these off
    // the raw ids made every contract reached only through a variable look like a top caller.
    let called: BTreeSet<&str> = edges.iter().map(|edge| held_entity(&edge.to)).collect();
    let calls: BTreeSet<&str> = edges.iter().map(|edge| held_entity(&edge.from)).collect();
    let out = |name: &str| edges.iter().filter(|edge| held_entity(&edge.from) == name).count();
    let into = |name: &str| edges.iter().filter(|edge| held_entity(&edge.to) == name).count();

    let framed_names: BTreeSet<&str> = framed.iter().map(|edge| held_entity(&edge.from)).collect();
    let framed_called: BTreeSet<&str> = framed.iter().map(|edge| held_entity(&edge.to)).collect();
    let mut tops: Vec<&str> = framed_names
        .iter()
        .copied()
        .filter(|name| !framed_called.contains(name))
        .collect();
    tops.sort_by(|a, b| out(b).cmp(&out(a)).then(a.cmp(b)));
    let mut foundations: Vec<&str> = names.iter().copied().filter(|n| !calls.contains(n)).collect();
    foundations.sort_by(|a, b| into(b).cmp(&into(a)).then(a.cmp(b)));

    let mut lines = vec![format!(
        "{} top caller(s) — nothing in scope depends on them, and the map gives each one a frame:",
        tops.len()
    )];
    for name in &tops {
        lines.push(format!("  {name:<28} talks to {} contract(s)   bat-cli map --contract {name}", out(name)));
    }
    lines.push(String::new());
    lines.push(format!(
        "{} foundation(s) — they depend on nothing, so they exist before the rest:",
        foundations.len()
    ));
    for name in &foundations {
        lines.push(format!("  {name:<28} {} contract(s) depend on it", into(name)));
    }
    lines
}

/// Split the whole graph into one frame per TOP CALLER, the way a deployment is one frame per
/// entry point.
///
/// Sixteen contracts and twenty relations on one frame is a mesh whichever way it is laid out,
/// and no amount of colour fixes it: the reader cannot follow a single arrow. The entry-point
/// diagrams hit this years ago and the answer there (`docs/diagram-deploy-design.md` §4) was to
/// partition and REPEAT — a callee drawn in two frames is drawn twice on purpose, because a
/// repeated box is cheap and a crossing arrow is not.
///
/// A top caller is a contract nothing in scope depends on: the place a reader starts. Its
/// frame holds everything it reaches, so the frame answers one question — "what does this
/// contract talk to" — and a contract everyone uses appears in each frame that uses it.
///
/// Anything left over (a cycle nothing points into) gets a frame of its own rather than being
/// dropped, picked by the contract with the most relations.
fn partition_frames(edges: &[Edge]) -> Vec<FramePlan> {
    let names: BTreeSet<&str> = edges
        .iter()
        .flat_map(|edge| [edge.from.as_str(), edge.to.as_str()])
        .collect();
    // By ENTITY: `vault%AscendYieldVault` is the vault, so the vault is not a contract nothing
    // points at, and it does not deserve a frame of its own. Reading this off the ids turned six
    // frames into thirteen the moment a box could be named after the variable holding it.
    let called: BTreeSet<&str> = edges.iter().map(|edge| held_entity(&edge.to)).collect();
    let out_degree = |name: &str| edges.iter().filter(|edge| edge.from == name).count();
    let mut roots: Vec<String> = names
        .iter()
        .copied()
        .filter(|name| !called.contains(held_entity(name)))
        .map(str::to_string)
        .collect();
    // Deterministic, and the busiest first so the frame a reader opens first says the most.
    roots.sort_by(|a, b| out_degree(b).cmp(&out_degree(a)).then(a.cmp(b)));

    let mut frames: Vec<FramePlan> = Vec::new();
    let mut covered: BTreeSet<(String, String)> = BTreeSet::new();
    let mut plan = |root: &str, frames: &mut Vec<FramePlan>, covered: &mut BTreeSet<(String, String)>| {
        let mine = unfold(root, edges);
        for edge in &mine {
            covered.insert((
                held_entity(original_of(&edge.from)).to_string(),
                held_entity(original_of(&edge.to)).to_string(),
            ));
        }
        if !mine.is_empty() {
            frames.push(FramePlan { root: root.to_string(), edges: mine });
        }
    };
    for root in &roots {
        plan(root, &mut frames, &mut covered);
    }
    // A cycle with nothing above it has no top caller, and is every bit as much part of the
    // system: it gets a frame of its own rather than being dropped. `StakingFeeConverter` is
    // one — `StakingFeeTreasury` calls back into it, so nothing in scope sits above it.
    let mut tried: BTreeSet<String> = roots.iter().cloned().collect();
    // Compared by ORIGINAL name on both ends, because a drawn edge carries the id of a copy
    // (`IERC20@YieldRouter`, `Treasury#2`) and the raw relation carries the name. Comparing the
    // two made every call that leaves the repository look undrawn, and every contract that
    // makes one became a root of its own: fourteen frames for five systems.
    while let Some(orphan) = edges
        .iter()
        .filter(|edge| {
            !covered.contains(&(
                held_entity(original_of(&edge.from)).to_string(),
                held_entity(original_of(&edge.to)).to_string(),
            ))
        })
        .map(|edge| held_entity(&edge.from).to_string())
        // Every contract whose own relations are still undrawn is a candidate, and already
        // being somebody's root disqualifies it, or the loop re-roots the same contract for
        // ever. Among the rest the root is THE ONE THAT CALLS THE MOST, not the first one the
        // relations happen to list: a cycle has no top caller, so some member has to be picked,
        // and the member with the most outgoing relations is the one whose frame tells the most
        // of the story. Ties go to the name, so the same system always draws the same frames.
        .filter(|name| !tried.contains(name))
        .max_by(|a, b| out_degree(a).cmp(&out_degree(b)).then_with(|| b.cmp(a)))
    {
        tried.insert(orphan.clone());
        plan(&orphan, &mut frames, &mut covered);
    }
    frames
}

/// A frame is a TREE: everything its contract reaches, with anything shared DRAWN AGAIN rather
/// than pointed at from two places.
///
/// The rule this replaced cut a contract two frames both reached into a frame of its own and
/// left a card behind. It optimised the right thing — no box drawn twice — and the wrong goal:
/// `ListingDesk` is an intermediate contract, not a system worth opening on its own, and a
/// reader asking what `AscendCtoRegistry` does was sent through three frames to find out. Fewer
/// frames, each self-contained, is worth more than fewer boxes.
///
/// Unfolding a shared graph into a tree is also what makes a frame readable with no localizing
/// machinery at all: nothing is shared, so nothing can cross. It can in principle blow up — a
/// diamond is drawn twice, a diamond of diamonds four times — so it is bounded. On the systems
/// this is pointed at today (16 contracts, 20 relations) it does not come close; when it does,
/// that is the moment to start recycling a box, which is intense logic for a problem nobody has.
fn unfold(root: &str, edges: &[Edge]) -> Vec<Edge> {
    /// Enough for any audit this has been pointed at, and a wall rather than a hang.
    const MAX_BOXES: usize = 400;

    let mut drawn: Vec<Edge> = Vec::new();
    let mut copies: BTreeMap<String, usize> = [(root.to_string(), 1)].into_iter().collect();
    // (name, the id of the copy being expanded): the path from the root, which is what tells a
    // cycle from a share — a node already on the path is a loop, one seen anywhere else is not.
    let mut path: Vec<(String, String)> = vec![(root.to_string(), root.to_string())];
    // An explicit stack of (depth, which child is next), because the recursion depth here is the
    // audit's own call depth and a frame is not worth a blown stack.
    let mut stack: Vec<(usize, usize)> = vec![(0, 0)];

    while let Some((depth, next)) = stack.pop() {
        let (name, id) = path[depth].clone();
        // What a box calls is a property of the CONTRACT, and a box may be named after the
        // variable holding it — `opexTreasury%Treasury` calls whatever `Treasury` calls. The
        // caller's own copy of an outside box (`IERC20@YieldRouter`) keeps its id: its children
        // are that caller's methods and nobody else's.
        let from = held_entity(&name);
        // A DESTINATION is a leaf: it says where this call's value went, and the box it names
        // has its own place on the map. Expanding it drew `StakerDistributor`'s whole subtree
        // under an `approve()` leaf.
        let outgoing: Vec<&Edge> = match destination_of(&name).is_some() {
            true => Vec::new(),
            false => edges.iter().filter(|edge| edge.from == from).collect(),
        };
        let Some(edge) = outgoing.get(next) else {
            path.truncate(depth + 1);
            continue;
        };
        stack.push((depth, next + 1));
        // A DESTINATION is a leaf that says who this call pays, not a step in the walk: it
        // never closes a cycle. Treated as one, `approve()`'s party came out as the ancestor's
        // box — `StakingFeeConverter (again — a cycle)` — with the role it fills thrown away.
        let continues = destination_of(&edge.to).is_none();
        if let Some((_, ancestor)) = path
            .iter()
            .take(depth + 1)
            .find(|(on_path, _)| continues && held_entity(on_path) == held_entity(&edge.to))
        {
            // Back to something this path came through: a cycle, drawn as the one red arrow
            // rather than unfolded for ever.
            drawn.push(Edge { from: id, to: ancestor.clone(), relation: edge.relation });
            continue;
        }
        if copies.values().sum::<usize>() >= MAX_BOXES {
            continue;
        }
        let seen = copies.entry(edge.to.clone()).or_insert(0);
        *seen += 1;
        let child = if *seen == 1 {
            edge.to.clone()
        } else {
            format!("{}{COPY_MARK}{}", edge.to, seen)
        };
        drawn.push(Edge { from: id, to: child.clone(), relation: edge.relation });
        // A READ is where the walk stops. The relation is real — this contract asks that one a
        // question — but nothing the far contract does on its own follows from it, and hanging
        // its whole subtree here drew a graph the caller cannot set off. `YieldRouter` reaches
        // `AscendLaunchpad` through two getters and was given the launchpad's every branch.
        // A READ and a WIRING both say the two are connected and neither says this contract
        // sets the other one off. Drawing the far contract's whole subtree under either was a
        // graph of things that cannot happen from here.
        if matches!(edge.relation, Relation::Reads | Relation::WiresAtConstruction) {
            path.truncate(depth + 1);
            continue;
        }
        path.truncate(depth + 1);
        path.push((edge.to.clone(), child));
        stack.push((depth + 1, 0));
    }
    drawn
}

/// One frame before it is laid out: whose frame it is, what it draws, and which of its boxes
/// are cards standing for a frame of their own.
#[derive(Debug)]
pub struct FramePlan {
    root: String,
    edges: Vec<Edge>,
}

/// A contract drawn more than once in one frame: `Treasury#2` is a second box for `Treasury`.
const COPY_MARK: char = '#';
/// A box for something OUTSIDE the repository, private to the contract that calls it:
/// `IERC20@YieldRouter` is `YieldRouter`'s own copy of `IERC20`.
const OUTSIDE_MARK: char = '@';

/// The original a box stands for, which is its own name unless it is a copy.
fn original_of(id: &str) -> &str {
    id.split([COPY_MARK, OUTSIDE_MARK]).next().unwrap_or(id)
}

/// The entity a box stands for: a destination's party, or the contract a copy copies.
/// The box's own name without the variable in front of it: `opexTreasury%Treasury` is
/// `Treasury`, and `IERC20@YieldRouter` is left alone — that `@` says whose copy it is, which
/// is part of the box's identity, not of the contract's.
fn held_entity(id: &str) -> &str {
    id.split_once(VARIABLE_MARK).map(|(_, held)| held).unwrap_or(id)
}

fn drawn_entity(id: &str) -> &str {
    match destination_of(id) {
        Some(destination) => entity_named(destination),
        None => {
            let original = original_of(id);
            original.split_once(VARIABLE_MARK).map(|(_, held)| held).unwrap_or(original)
        }
    }
}

/// Is this box something with no source in this repository?
fn is_outside(id: &str) -> bool {
    id.contains(OUTSIDE_MARK)
}

/// What separates an outside box from the METHOD called on it: `IERC20@YieldRouter::safeTransfer`.
const METHOD_MARK: &str = "::";
/// And what separates that method from WHO it hands the value to:
/// `IERC20@YieldRouter::safeTransfer=>burnSink`.
const DESTINATION_MARK: &str = "=>";

/// The method this box stands for, when it is one.
fn method_of(id: &str) -> Option<&str> {
    id.split_once(METHOD_MARK)
        // `IListingLaunchpad@X::collect#3` is the THIRD copy of that leaf, and a box reading
        // `collect#3` tells the reader about our bookkeeping instead of about the method.
        .map(|(_, method)| method.split(COPY_MARK).next().unwrap_or(method))
        .map(|method| method.split(DESTINATION_MARK).next().unwrap_or(method))
}

/// A destination the deploy script decides and the code never names: `=>yieldSink~` is the
/// ADDRESS that variable holds, not a contract. Marked so the box can say so — an unnamed
/// address drawn like a contract is a contract the reader will go looking for.
const ADDRESS_MARK: char = '~';

/// How the scan writes a ternary argument: `recipient|burnSink`, one party per branch.
use crate::batbelt::evm::parser::call_resolver::TERNARY_MARK;

/// Who the value goes to, when this box is a destination.
fn destination_of(id: &str) -> Option<&str> {
    id.split_once(DESTINATION_MARK)
        .map(|(_, to)| to.split(COPY_MARK).next().unwrap_or(to))
}

/// The box a native-value transfer gets: the EVM's own, with no interface and no code to read.
const NATIVE_BOX: &str = "native HYPE";

/// And the box for a low-level call with no value: `router.call(data)`, where the method is in
/// the payload and the only thing the code says is who it goes to.
const LOW_LEVEL_BOX: &str = "low-level call";

/// What separates the VARIABLE that holds an address from the contract at it:
/// `to: opexTreasury (Treasury)`. One contract, several deployments, and the variable is the
/// only thing that tells them apart.
const VARIABLE_MARK: char = '%';

/// What separates the PARAMETER a party fills from the party itself: `to: StakerDistributor`.
const ROLE_MARK: &str = ": ";

/// The entity a destination names, without the role it fills or the address mark.
fn entity_named(destination: &str) -> &str {
    let entity = destination
        .split_once(ROLE_MARK)
        .map(|(_, entity)| entity)
        .unwrap_or(destination);
    // `opexTreasury%Treasury` stands for `Treasury`: that is what the reader's list names and
    // what every copy of it shares.
    let entity = entity.strip_suffix(ADDRESS_MARK).unwrap_or(entity);
    entity.split_once(VARIABLE_MARK).map(|(_, held)| held).unwrap_or(entity)
}

/// Is this box a destination whose entity nobody has named yet — a bare state `address`?
fn is_wiring_point(id: &str) -> bool {
    destination_of(id).is_some_and(|to| to.ends_with(ADDRESS_MARK))
}

/// The PARTIES a call hands an address to, resolved to the entities they name.
///
/// General, and about every method rather than about transfers: a parameter whose type is an
/// address or a contract is another party in that interaction, whoever declared the method. The
/// declaration says which parameters those are; the call site says what was passed; and only
/// what resolves to an ENTITY is drawn — `msg.sender` is whoever called, a bare parameter is a
/// name from another function, and neither is a contract this map can place.
///
/// Two places hold the declaration, and the second is why `safeTransfer` works at all:
/// - the type itself, its bases, or whoever implements it — arguments line up one to one;
/// - a library bound with `using X for Y`, where the receiver is the FIRST parameter, so the
///   call site's argument `i` is parameter `i + 1`. `token.safeTransfer(to, amount)` is sugar
///   for `SafeERC20.safeTransfer(token, to, amount)`, and without that shift the recipient would
///   be read as the token.
fn parties_of(
    metadata: &EvmBatMetadata,
    caller: &ContractMetadata,
    function: &crate::batbelt::evm::metadata::bat_metadata::FunctionMetadata,
    type_name: &str,
    method: &str,
    arguments: &[String],
) -> (Vec<String>, Vec<UnnamedParty>) {
    let Some((params, offset)) = declaration_of(metadata, caller, type_name, method) else {
        return (Vec::new(), Vec::new());
    };
    let mut parties = Vec::new();
    let mut unnamed = Vec::new();
    for (role, argument) in addressed_arguments(metadata, params, offset, arguments) {
        let param = EvmParam { name: role, type_name: String::new(), storage_location: None };
        let argument = &argument;
        // A ternary is TWO possible parties and the transaction picks one, so each branch is
        // its own question and its own box. `recipient|burnSink` is not a name.
        for argument in argument.trim().split(TERNARY_MARK) {
            let argument = argument.trim();
            // The scan writes `…` where the expression was too compound to record. There is no
            // key for it and no name to trace from here — it is reported as a line to open,
            // not as a question with a blank to fill.
            let recorded = argument != "…";
            match entity_of(metadata, caller, &function.name, argument) {
                // One answer may name SEVERAL contracts — a function called from two places
                // with two destinations — and each of them is a party.
                Some(entity) => {
                    for named in entity.split(',').map(str::trim).filter(|name| !name.is_empty()) {
                        // A state address already carries the mark from `entity_of`; marking it
                        // again drew `POOL~ (address)`, with the bookkeeping in the box.
                        let named = named.strip_suffix(ADDRESS_MARK).unwrap_or(named);
                        // WHICH parameter it fills. `transferFrom(from, to, amount)` hands two
                        // addresses to two different roles, and two boxes with only the names
                        // in them do not say which is paying and which is being paid. An
                        // interface that declares no parameter names says nothing here either,
                        // and then the box keeps the entity alone.
                        let role = match param.name.trim() {
                            "" => String::new(),
                            name => format!("{name}{ROLE_MARK}"),
                        };
                        // An answer that is not a contract of this repository is an ACCOUNT —
                        // the launch creator, the caller, a multisig. Named, and drawn as the
                        // address it is: dashed, not as code somebody can go and read.
                        let held = named.split_once(VARIABLE_MARK).map(|(_, h)| h).unwrap_or(named);
                        let account = !metadata.contracts.iter().any(|c| c.name == held)
                            && !named.starts_with("address(")
                            && !named.starts_with("payable(");
                        let party = match account {
                            true => format!("{role}{named}{ADDRESS_MARK}"),
                            false => format!("{role}{named}"),
                        };
                        if !parties.contains(&party) {
                            parties.push(party);
                        }
                    }
                }
                // A party the map cannot place vanished silently, and an audit cannot discard a
                // party it was never shown. Reported instead, with the key that answers it.
                None => unnamed.push(UnnamedParty {
                    contract: caller.name.clone(),
                    file: caller.file_path.clone(),
                    function: function.name.clone(),
                    line: function.line,
                    end_line: function.end_line,
                    call: format!("{type_name}.{method}"),
                    argument: argument.to_string(),
                    key: recorded
                        .then(|| format!("{}.{}.{argument}", caller.name, function.name)),
                }),
            }
        }
    }
    (parties, unnamed)
}

/// Where a call site is, as `src/YieldRouter.sol:142  YieldRouter.pay`.
///
/// The scan records a function's line range but not a call's line, and the reader has to open
/// the file either way — so the line is looked up HERE, within the function's own lines, by the
/// method name. When the file is not where the metadata says, or the call is written in a shape
/// this does not match, the function's own line is printed: a worse answer, never a wrong one.
fn located(party: &UnnamedParty) -> String {
    let method = party.call.rsplit('.').next().unwrap_or_default();
    let line = call_line(&party.file, party.line, party.end_line, method).unwrap_or(party.line);
    format!("{}:{line}  {}.{}", party.file, party.contract, party.function)
}

/// The line a method is called on, inside a function, read from the file itself.
fn call_line(file: &str, from: usize, to: usize, method: &str) -> Option<usize> {
    let source = std::fs::read_to_string(file).ok()?;
    let needle = format!(".{method}(");
    source
        .lines()
        .enumerate()
        .skip(from.saturating_sub(1))
        .take(to.saturating_sub(from) + 1)
        .find(|(_, line)| line.contains(&needle))
        .map(|(index, _)| index + 1)
}

/// One call-site argument the map could not turn into an entity: where it is written, what it
/// says, and the key `bat-cli resolve` takes to answer it.
///
/// This is the whole handover. bat says where to look and stops guessing; a reader (or an
/// assistant reading the code) traces the value and records what it found; the map then draws
/// it like any other party. Nothing here is inferred from a name.
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
pub struct UnnamedParty {
    pub contract: String,
    pub file: String,
    pub function: String,
    /// The function's own lines, which bound the search for the call's line.
    pub line: usize,
    pub end_line: usize,
    /// The call it is an argument of, as `IERC20.transfer`.
    pub call: String,
    /// The argument as the source writes it: `msg.sender`, `to`, `recipient`.
    pub argument: String,
    /// What to pass to `bat-cli resolve <KEY> <CONTRACT>` — `None` when the scan could not
    /// write the argument's expression down, and there is nothing to key on.
    pub key: Option<String>,
}

/// Every argument that hands over an address, with the role it fills.
///
/// Two shapes. A parameter whose own type is an address or a contract — `transfer(to, amount)`.
/// And a STRUCT parameter, which is where an address hides from a signature:
/// `exactInput(ExactInputParams(path, address(this), deadline, …))` declares no address and
/// hands one over all the same. The struct's declaration says which of its fields are
/// addresses, and the construction says what was passed, so the two line up by position and the
/// role reads `params.recipient`.
fn addressed_arguments(
    metadata: &EvmBatMetadata,
    params: &[EvmParam],
    offset: usize,
    arguments: &[String],
) -> Vec<(String, String)> {
    let mut found = Vec::new();
    for (index, argument) in arguments.iter().enumerate() {
        let Some(param) = params.get(index + offset) else {
            continue;
        };
        if is_address_like(metadata, &param.type_name) {
            found.push((param.name.clone(), argument.clone()));
            continue;
        }
        let Some(fields) = struct_fields(metadata, &param.type_name) else {
            continue;
        };
        let Some(built) = construction_arguments(argument) else {
            continue;
        };
        for (field, inner) in fields.iter().zip(built) {
            if is_address_like(metadata, &field.type_name) {
                found.push((format!("{}.{}", param.name, field.name), inner));
            }
        }
    }
    found
}

/// The fields of the struct this type names, wherever it is declared.
fn struct_fields<'a>(metadata: &'a EvmBatMetadata, type_name: &str) -> Option<&'a [EvmParam]> {
    let clean = type_name.trim().trim_end_matches("[]");
    // `IStakingSwapRouter.ExactInputParams` names its owner; `ExactInputParams` alone does not.
    let (owner, name) = match clean.split_once('.') {
        Some((owner, name)) => (Some(owner), name),
        None => (None, clean),
    };
    metadata
        .contracts
        .iter()
        .filter(|contract| owner.is_none_or(|owner| contract.name == owner))
        .flat_map(|contract| contract.structs.iter())
        .find(|declared| declared.name == name)
        .map(|declared| declared.fields.as_slice())
}

/// The arguments of a struct construction, as the scan wrote them: `Name(a, b, c)` → the three.
///
/// Split at the commas of the OUTER list only, so a nested construction or a call stays whole.
fn construction_arguments(argument: &str) -> Option<Vec<String>> {
    let inner = argument.trim().strip_suffix(')')?;
    let (_, inner) = inner.split_once('(')?;
    let mut out = Vec::new();
    let mut depth = 0usize;
    let mut current = String::new();
    for character in inner.chars() {
        match character {
            '(' | '[' => {
                depth += 1;
                current.push(character);
            }
            ')' | ']' => {
                depth = depth.saturating_sub(1);
                current.push(character);
            }
            ',' if depth == 0 => out.push(std::mem::take(&mut current).trim().to_string()),
            _ => current.push(character),
        }
    }
    let last = current.trim().to_string();
    if !last.is_empty() {
        out.push(last);
    }
    Some(out)
}

/// Is this type an address — plainly, or because it names a contract or an interface?
fn is_address_like(metadata: &EvmBatMetadata, type_name: &str) -> bool {
    let clean = type_name.trim().trim_end_matches("[]");
    clean == "address"
        || clean == "address payable"
        || metadata.contracts.iter().any(|contract| contract.name == clean)
}

/// The parameters of `method` as declared, and how far the call site's arguments are shifted.
fn declaration_of<'a>(
    metadata: &'a EvmBatMetadata,
    caller: &ContractMetadata,
    type_name: &str,
    method: &str,
) -> Option<(&'a [crate::batbelt::evm::types::EvmParam], usize)> {
    let family = type_family(metadata, type_name);
    // The declaration that NAMES its parameters, where there is one: a vendored `IERC20` may
    // write `approve(address, uint256)` and another copy `approve(address spender, uint256
    // value)`, and the box is the poorer for picking the first. Falls back to any declaration.
    let declarations = || {
        metadata
            .contracts
            .iter()
            .filter(|contract| family.contains(contract.name.as_str()))
            .flat_map(|contract| contract.functions.iter())
            .filter(|function| function.name == method)
    };
    let declared = declarations()
        .find(|function| function.params.iter().all(|param| !param.name.trim().is_empty()))
        .or_else(|| declarations().next());
    if let Some(function) = declared {
        return Some((function.params.as_slice(), 0));
    }
    // Attached by `using X for Y`: the receiver is the library's first parameter. The same
    // preference for a declaration that NAMES its parameters, so the box can say which role
    // each party fills.
    let attached = || {
        metadata
            .contracts
            .iter()
            .filter(|contract| caller.using_libraries.iter().any(|lib| lib == &contract.name))
            .flat_map(|contract| contract.functions.iter())
            .filter(|function| function.name == method && !function.params.is_empty())
    };
    attached()
        .find(|function| function.params.iter().all(|param| !param.name.trim().is_empty()))
        .or_else(|| attached().next())
        .map(|function| (function.params.as_slice(), 1))
}

/// Every contract this one INHERITS from, transitively and in scope.
///
/// A base's functions are this contract's: `StakingFeeTreasury is Treasury` has `sweep`, and
/// `sweep` moves its whole balance. The scan records a function under the contract that
/// DECLARES it, so without this a child showed only what it declared itself and the treasuries
/// came out with no way to pay anything out.
fn inherited(metadata: &EvmBatMetadata, contract: &ContractMetadata) -> Vec<String> {
    let mut found: Vec<String> = Vec::new();
    let mut walking: Vec<String> = contract.base_contracts.clone();
    while let Some(base) = walking.pop() {
        if found.contains(&base) || base == contract.name {
            continue;
        }
        if let Some(declared) = metadata
            .contracts
            .iter()
            .find(|candidate| !candidate.vendored && candidate.name == base)
        {
            walking.extend(declared.base_contracts.iter().cloned());
        }
        found.push(base);
    }
    found
}

/// The methods this call's own body invokes on `msg.sender` — the ones that come back here.
///
/// Read off the declaration the call lands on, the same family `declaration_of` walks, and only
/// where there is a BODY to read: an interface declares `lock(bytes)` and says nothing, while
/// the implementation (vendored or not) says `ILockCallback(msg.sender).lockAcquired(data)`.
fn calls_back(
    metadata: &EvmBatMetadata,
    caller: &ContractMetadata,
    type_name: &str,
    method: &str,
) -> Vec<String> {
    let family = type_family(metadata, type_name);
    let mut found: Vec<String> = Vec::new();
    for contract in metadata.contracts.iter().filter(|c| family.contains(c.name.as_str())) {
        for function in contract.functions.iter().filter(|f| f.name == method) {
            for back in &function.callbacks {
                if !found.contains(back) {
                    found.push(back.clone());
                }
            }
        }
    }
    // The caller has to be able to receive it; a contract that does not declare the callback
    // never gets called back, whatever the callee does with some other `msg.sender`.
    found.retain(|back| {
        caller.functions.iter().any(|f| f.name == *back)
            || caller.base_contracts.iter().any(|base| {
                metadata
                    .contracts
                    .iter()
                    .any(|c| c.name == *base && c.functions.iter().any(|f| f.name == *back))
            })
    });
    found
}

/// The call a library WRAPPER really makes, with the arguments of the call site substituted in.
///
/// `token.safeTransfer(to, amount)` is sugar for `SafeERC20.safeTransfer(token, to, amount)`, and
/// that function's body is `abi.encodeCall(token.transfer, (to, value))` — so what crosses the
/// boundary is `transfer`, and `safeTransfer` is how this code decides to make it. A box reading
/// `IERC20 → safeTransfer()` names a method that interface does not have.
///
/// Returns the real method and its arguments, both as the call site would have written them:
/// the wrapper's parameters are replaced by what was passed. `to` is parameter 1 of the library,
/// so it is argument 0 of the call site; `value` is parameter 2, argument 1.
///
/// `None` when this is not a wrapper, when its body makes no call on the receiver, or when it
/// makes more than one — `forceApprove` calls `approve` twice, which is one relation, but a
/// wrapper that calls two DIFFERENT methods is not something to flatten into one box.
fn unwrap_library_call(
    metadata: &EvmBatMetadata,
    caller: &ContractMetadata,
    method: &str,
    arguments: &[String],
) -> Option<(String, Vec<String>)> {
    let wrapper = metadata
        .contracts
        .iter()
        .filter(|contract| caller.using_libraries.iter().any(|lib| lib == &contract.name))
        .flat_map(|contract| contract.functions.iter())
        .find(|function| function.name == method && !function.params.is_empty())?;

    // The receiver is the wrapper's first parameter: every call its body makes ON that name is a
    // call on the thing the caller wrote.
    let receiver = wrapper.params.first()?.name.clone();
    let inner: Vec<_> = wrapper
        .unknown_external_calls
        .iter()
        .filter(|call| call.receiver == receiver)
        .collect();
    let (first, rest) = inner.split_first()?;
    if rest.iter().any(|call| call.method != first.method) {
        return None;
    }

    // The wrapper's parameters, in order, as the call site filled them: parameter `i + 1` holds
    // argument `i`.
    let filled: BTreeMap<&str, &str> = wrapper
        .params
        .iter()
        .skip(1)
        .zip(arguments.iter())
        .map(|(param, argument)| (param.name.as_str(), argument.as_str()))
        .collect();
    let substituted = first
        .arguments
        .iter()
        .map(|written| {
            filled
                .get(written.as_str())
                .map(|argument| argument.to_string())
                .unwrap_or_else(|| written.clone())
        })
        .collect();
    Some((first.method.clone(), substituted))
}

/// A type, everything it inherits from, and everything that declares it as a base./// A type, everything it inherits from, and everything that declares it as a base.
fn type_family<'a>(metadata: &'a EvmBatMetadata, type_name: &'a str) -> BTreeSet<&'a str> {
    let mut family: BTreeSet<&str> = [type_name].into_iter().collect();
    let mut walking = vec![type_name];
    while let Some(name) = walking.pop() {
        for contract in metadata.contracts.iter().filter(|c| c.name == name) {
            for base in &contract.base_contracts {
                if family.insert(base.as_str()) {
                    walking.push(base.as_str());
                }
            }
        }
    }
    for contract in metadata.contracts.iter() {
        if contract.base_contracts.iter().any(|base| base == type_name) {
            family.insert(contract.name.as_str());
        }
    }
    family
}

/// Which ENTITY an argument names, when it names one at all.
///
/// `this` is the contract doing the calling — the one thing here the language settles on its
/// own. A state variable typed as a contract or an interface names that. Anything else —
/// `msg.sender`, a parameter, a local computed elsewhere — is an address this map cannot place,
/// and is left undrawn rather than guessed at.
fn entity_of(
    metadata: &EvmBatMetadata,
    caller: &ContractMetadata,
    function: &str,
    argument: &str,
) -> Option<String> {
    let name = argument.trim();
    if name == "this" {
        return Some(caller.name.clone());
    }
    // `address(0)` is an entity and a famous one — value sent there is burnt. It is written
    // down in full, so there is nothing to trace and nothing to ask: it is its own name.
    if name.starts_with("address(") || name.starts_with("payable(") {
        return Some(name.to_string());
    }
    // What somebody RECORDED outranks the declared type: `treasury` is declared `Treasury` and
    // holds a `StakingFeeTreasury` in this deployment, which only a reader can say. The
    // VARIABLE stays in front of it — `treasury` and `stakerYieldTreasury` are two
    // `StakingFeeTreasury`s, one per converter, and an answer that drops the name merged two
    // addresses into one box.
    if let Some(recorded) = wired_to(metadata, caller, name) {
        let answer = elsewhere(metadata, &recorded);
        let holds = caller.state_variables.iter().any(|state| state.name == name);
        return Some(match holds && !answer.contains(VARIABLE_MARK) && !answer.contains(',') {
            true => format!("{name}{VARIABLE_MARK}{answer}"),
            false => answer,
        });
    }
    let Some(variable) = caller.state_variables.iter().find(|variable| variable.name == name)
    else {
        // Not state: a parameter, `msg.sender`, a local assigned elsewhere. Static analysis is
        // done here — the value comes from the caller, one transaction at a time — but a READER
        // can trace it, and once they have, it is a fact about this call site and belongs
        // written down: `bat-cli resolve <Contract>.<function>.<argument> <Contract>`.
        return wired_at(metadata, caller, function, name);
    };
    match classify_type(metadata, Some(caller.name.as_str()), &variable.type_name) {
        // WHICH one. `AscendLaunchpad` holds five `Treasury`s — `treasury`, `ecosystemTreasury`,
        // `kntqTreasury`, `opexTreasury`, `stakerYieldTreasury` — and they are five deployed
        // addresses, not one. Named by the type alone the five transfers out of
        // `_routeProtocolFees` came out as five identical boxes. The variable is the identity;
        // the contract stays on the box because it is what the reader opens.
        TypeTarget::Contract(entity) => Some(format!("{name}{VARIABLE_MARK}{entity}")),
        // An interface nobody in scope implements is still an entity — the box the map already
        // draws for what leaves the repository.
        TypeTarget::Outside(entity) => Some(entity),
        // Several candidates, or not a contract at all. A plain `address` held in STATE is
        // still a party, and a fixed one: `feeSink` is decided once, at deployment, and never
        // changes. The code never says WHICH contract it is — only the deploy script does — so
        // the box carries the variable's name and says that much, which is the difference
        // between "value leaves here, to this wiring point" and silence. `bat-cli resolve`
        // turns it into a named contract when somebody can say so.
        TypeTarget::Open(_) | TypeTarget::NotAContract => {
            let plain = variable.type_name.trim();
            if plain != "address" && plain != "address payable" {
                return None;
            }
            // Nobody has said what this slot holds — `bat-cli resolve YieldRouter.burnSink
            // BurnSink` is the only way that fact can get here, since the compiler sees twenty
            // bytes written by a deploy script — so the box says the variable and says it is
            // an address.
            Some(format!("{name}{ADDRESS_MARK}"))
        }
    }
}

/// What the `wiring` table says this state address holds, if anybody has said.
///
/// Keyed by the contract that HOLDS the variable, which is what makes it unambiguous — two
/// contracts with a `vault` each are two entries. A variable declared in a base is looked up
/// under the base as well, so the fact is recorded once where it is written.
fn wired_to(metadata: &EvmBatMetadata, caller: &ContractMetadata, variable: &str) -> Option<String> {
    std::iter::once(caller.name.as_str())
        .chain(caller.base_contracts.iter().map(String::as_str))
        .find_map(|holder| metadata.wiring.get(&format!("{holder}.{variable}")))
        .cloned()
}

/// Does calling this library function send native value, and which argument says where to?
///
/// A library has no address: its code runs in the caller, so a low-level `call` in its body is
/// the CALLER paying out. Solmate's `safeTransferETH` is one, written entirely in assembly, and
/// `Treasury.sweep` moves its whole balance through it. The destination is the function's first
/// `address` parameter, which the call site fills.
fn sends_native(metadata: &EvmBatMetadata, type_name: &str, method: &str) -> Option<usize> {
    use crate::batbelt::evm::types::EvmContractType;
    let library = metadata.contracts.iter().find(|contract| {
        contract.name == type_name && contract.contract_type == EvmContractType::Library
    })?;
    let declared = library.functions.iter().find(|function| function.name == method)?;
    let low_level = declared.unknown_external_calls.iter().any(|call| {
        matches!(call.method.trim_end_matches("{value}"), "call" | "delegatecall")
    });
    if !low_level {
        return None;
    }
    // A library that acts on a TOKEN is not sending native value, whatever its body does:
    // solmate writes `safeTransfer(ERC20 token, …)` in assembly too, and that is the token's
    // own transfer — drawn on the token's box by `through_library`. Native value is the one
    // whose first parameter is the address itself.
    let first = declared.params.first()?;
    matches!(first.type_name.trim(), "address" | "address payable").then_some(0)
}

/// The type a LIBRARY function acts on: its first parameter, which is the receiver `using X for
/// Y` would have made explicit. `None` when this is not a library call by name.
///
/// A plain `address` first parameter means native value — `safeTransferETH(to, amount)` — and
/// the caller draws that in its own box, so it is not re-aimed here.
fn through_library(metadata: &EvmBatMetadata, type_name: &str, method: &str) -> Option<String> {
    use crate::batbelt::evm::types::EvmContractType;
    let library = metadata
        .contracts
        .iter()
        .find(|contract| contract.name == type_name && contract.contract_type == EvmContractType::Library)?;
    let first = library
        .functions
        .iter()
        .find(|function| function.name == method)?
        .params
        .first()?;
    let acts_on = first.type_name.trim();
    match acts_on == "address" || acts_on == "address payable" {
        true => None,
        false => Some(acts_on.to_string()),
    }
}

/// Where a call's arguments are decided, and what they are there.
///
/// A contract's own function decides them itself: one site, the arguments as written. A
/// LIBRARY's function does not — its parameters are filled by each host, so `VaultPay.pay(vault,
/// …)` is as many sites as there are calls to it, and the library's parameter names are
/// substituted by what that host passed. The reader is then pointed at the host's line, which
/// is where the answer can be traced, and an answer recorded for one host never leaks to
/// another.
type CallSite<'a> = (
    &'a ContractMetadata,
    &'a crate::batbelt::evm::metadata::bat_metadata::FunctionMetadata,
    Vec<String>,
);

fn call_sites<'a>(
    host: &'a ContractMetadata,
    source: &'a ContractMetadata,
    function: &'a crate::batbelt::evm::metadata::bat_metadata::FunctionMetadata,
    arguments: &[String],
) -> Vec<CallSite<'a>> {
    if source.name == host.name {
        return vec![(host, function, arguments.to_vec())];
    }
    let declared: Vec<&str> = source
        .functions
        .iter()
        .find(|declared| declared.name == function.name)
        .map(|declared| declared.params.iter().map(|param| param.name.as_str()).collect())
        .unwrap_or_default();
    let mut sites = Vec::new();
    for caller in &host.functions {
        for call in &caller.unknown_external_calls {
            if call.method != function.name {
                continue;
            }
            let filled: Vec<String> = arguments
                .iter()
                .map(|argument| {
                    match declared.iter().position(|param| *param == argument.as_str()) {
                        // `using X for Y` passes the receiver as the first parameter, so the
                        // call site's argument `i` is the library's parameter `i + 1`.
                        Some(0) => call.receiver.clone(),
                        Some(index) => call
                            .arguments
                            .get(index - 1)
                            .cloned()
                            .unwrap_or_else(|| argument.clone()),
                        None => argument.clone(),
                    }
                })
                .collect();
            sites.push((host, caller, filled));
        }
    }
    // Nobody in this host calls it directly — `VaultPay.pay` is called by `VaultPay.buyExactIn`
    // — so the arguments stand as the library writes them and they are read in the LIBRARY's
    // context. Reading them in the host's would be worse than useless: `VaultPay.pay`'s own
    // parameter `vault` would resolve against `YieldRouter.vault`, a different contract that
    // happens to share the name.
    if sites.is_empty() {
        sites.push((source, function, arguments.to_vec()));
    }
    sites
}

/// A recorded answer, as a party: `ListingDesk.listingTreasury` names that contract's variable,
/// so the box reads like every other one holding that address (`listingTreasury (Treasury)`).
/// Anything else is taken as written — a contract's name, or an account the reader named.
fn elsewhere(metadata: &EvmBatMetadata, recorded: &str) -> String {
    recorded
        .split(',')
        .map(str::trim)
        .map(|answer| {
            let Some((owner, variable)) = answer.split_once('.') else {
                return answer.to_string();
            };
            let held = metadata
                .contracts
                .iter()
                .filter(|contract| contract.name == owner)
                .flat_map(|contract| contract.state_variables.iter())
                .find(|state| state.name == variable);
            match held {
                Some(state) => format!("{variable}{VARIABLE_MARK}{}", state.type_name.trim()),
                None => answer.to_string(),
            }
        })
        .collect::<Vec<_>>()
        .join(",")
}

/// What the `wiring` table says about ONE call site's argument: `YieldRouter.pay.to`.
///
/// The key carries the function, because the answer is about that call and not about the name:
/// `to` in one function is not `to` in another, and a bare name would bind both.
fn wired_at(
    metadata: &EvmBatMetadata,
    caller: &ContractMetadata,
    function: &str,
    argument: &str,
) -> Option<String> {
    metadata
        .wiring
        .get(&format!("{}.{function}.{argument}", caller.name))
        .map(|recorded| elsewhere(metadata, recorded))
}

/// Lay a frame out as a TREE: each contract at the height of the children it talks to.
///
/// The layered engine packs every column from the top, which is right when a column holds
/// unrelated boxes — and wrong here. A frame IS a tree now, and packing from the top put a
/// contract's own callees level with somebody else's: following one arrow meant scrolling up
/// and down a frame whose answer was two boxes apart. Reingold–Tilford instead: leaves take the
/// next free row, a parent sits at the middle of its children, so a box is always beside the
/// boxes it points at.
///
/// It costs what the deploy rejected it for — a parent's band is its whole subtree, so a light
/// sibling after a heavy one starts low. On a map that is cheap: the boxes are a name each, and
/// the outside leaves are half-height.
///
/// Every edge of a tree joins adjacent columns, so there are no bend points and nothing to
/// route through a corridor; crossings are 0 by construction, which the certificate still
/// reports rather than assumes.
fn layout_tree(root: &str, edges: &[Edge]) -> GraphLayout {
    /// Between two boxes stacked in the same column.
    const ROW_GAP: f64 = 220.0;
    /// Between one column and the next: room for the arrows' lanes.
    const COLUMN_GAP: f64 = 900.0;

    // The tree: the first arrow into a box is the one that owns it. Anything else is a back
    // edge — `unfold` only emits one when it reaches a box already on the path — and takes no
    // part in the placement.
    let mut children: BTreeMap<&str, Vec<&str>> = BTreeMap::new();
    let mut parented: BTreeSet<&str> = BTreeSet::new();
    let mut order: Vec<&str> = Vec::new();
    for edge in edges {
        for id in [edge.from.as_str(), edge.to.as_str()] {
            if !order.contains(&id) {
                order.push(id);
            }
        }
    }
    for edge in edges {
        // Never the root: the frame of a cycle has an arrow back INTO its own root, and taking
        // that one for the tree made the root somebody's child — so no box was left without a
        // parent, the layout found no root at all, and the whole frame came out empty. It
        // reached the board as a titled frame with nothing in it.
        if edge.to == root || parented.contains(edge.to.as_str()) {
            continue;
        }
        parented.insert(edge.to.as_str());
        children.entry(edge.from.as_str()).or_default().push(edge.to.as_str());
    }
    let Some(root) = order.iter().copied().find(|id| *id == root).or_else(|| {
        // The caller's root is normally one of the boxes; if it somehow is not, anything
        // without a parent will do before drawing nothing at all.
        order.iter().copied().find(|id| !parented.contains(id))
    }) else {
        return GraphLayout {
            nodes: Vec::new(),
            routes: vec![Vec::new(); edges.len()],
            back_edges: Vec::new(),
            bbox_width: 0.0,
            bbox_height: 0.0,
            frame_width: MAP_MARGIN * 2.0,
            frame_height: MAP_MARGIN * 2.0,
            crossings: 0,
        };
    };

    // Depth per box, and the widest box of each depth: a column is as wide as its widest name.
    let mut depth: BTreeMap<&str, usize> = BTreeMap::new();
    let mut stack = vec![(root, 0usize)];
    while let Some((id, at)) = stack.pop() {
        depth.insert(id, at);
        for child in children.get(id).into_iter().flatten() {
            stack.push((child, at + 1));
        }
    }
    let deepest = depth.values().copied().max().unwrap_or(0);
    let mut column_width = vec![0.0_f64; deepest + 1];
    for (id, at) in &depth {
        column_width[*at] = column_width[*at].max(node_width(id));
    }
    let mut column_x = vec![0.0_f64; deepest + 1];
    let mut left = MAP_MARGIN;
    for (at, width) in column_width.iter().enumerate() {
        column_x[at] = left + width / 2.0;
        left += width + COLUMN_GAP;
    }

    // Rows: a leaf takes the next one, a parent the middle of its children. Explicit stack, two
    // passes per node (down, then up), because the depth here is the audit's own call depth.
    let mut y: BTreeMap<&str, f64> = BTreeMap::new();
    let mut cursor = MAP_MARGIN;
    let mut walk: Vec<(&str, bool)> = vec![(root, false)];
    while let Some((id, done)) = walk.pop() {
        let mine = children.get(id).cloned().unwrap_or_default();
        if mine.is_empty() {
            y.insert(id, cursor + node_height(id) / 2.0);
            cursor += node_height(id) + ROW_GAP;
            continue;
        }
        if done {
            let first = y.get(mine.first().expect("checked")).copied().unwrap_or(cursor);
            let last = y.get(mine.last().expect("checked")).copied().unwrap_or(cursor);
            y.insert(id, (first + last) / 2.0);
            continue;
        }
        walk.push((id, true));
        for child in mine.iter().rev() {
            walk.push((child, false));
        }
    }

    let nodes: Vec<PlacedNode> = order
        .iter()
        .filter_map(|id| {
            Some(PlacedNode {
                id: id.to_string(),
                layer: *depth.get(id)?,
                x: column_x[*depth.get(id)?],
                y: *y.get(id)?,
                width: node_width(id),
                height: node_height(id),
            })
        })
        .collect();
    let width = nodes
        .iter()
        .map(|node| node.x + node.width / 2.0)
        .fold(0.0_f64, f64::max)
        + MAP_MARGIN;
    let height = nodes
        .iter()
        .map(|node| node.y + node.height / 2.0)
        .fold(0.0_f64, f64::max)
        + MAP_MARGIN;
    GraphLayout {
        nodes,
        routes: vec![Vec::new(); edges.len()],
        back_edges: Vec::new(),
        bbox_width: width - MAP_MARGIN * 2.0,
        bbox_height: height - MAP_MARGIN * 2.0,
        frame_width: width,
        frame_height: height,
        crossings: 0,
    }
}

/// Lay the map out: one box per contract, the deploy's own engine, callers above callees.
///
/// Pure, and done before anything is placed, because where the map goes on the board depends
/// on how wide it is — it opens to the LEFT of everything, and that edge can only be found
/// once the width is known.
/// The edges that get a box and an arrow, with what leaves the repository given a box of its
/// own — one PER CALLER.
///
/// A call out of the code is a call, and an audit's question about it ("what does this touch
/// that I cannot read") deserves an arrow like any other. What it must not be is a SHARED node:
/// `IERC20` is reached by seven contracts, and one box for all of them pulled seven long arrows
/// across the frame and was, alone, the busiest thing on the map. So every caller gets its own
/// copy, which is §5's localize taken to the end — an outside box has no chain under it, so a
/// copy costs one box and saves a crossing every time.
fn drawn_edges(edges: &[Edge], no_boundaries: bool) -> Vec<Edge> {
    edges
        .iter()
        .filter(|edge| !no_boundaries || edge.relation != Relation::Boundary)
        .map(|edge| match edge.relation {
            Relation::Boundary => Edge {
                from: edge.from.clone(),
                to: format!("{}{OUTSIDE_MARK}{}", edge.to, edge.from),
                relation: edge.relation,
            },
            _ => edge.clone(),
        })
        .collect()
}

/// Does this method of that type only READ?
///
/// Read from the DECLARATION, never from a vocabulary of names: `view`/`pure` is the one thing
/// the language itself guarantees, it holds in any protocol, and the scan already has it —
/// interfaces under `lib/` are scanned with their functions like anything else.
///
/// Unknown counts as "no". If the type is declared nowhere this scan can see, a boundary that
/// might move value is drawn rather than hidden: an audit can discard a box, it cannot discard a
/// transfer it was never shown.
fn reads_only(metadata: &EvmBatMetadata, type_name: &str, method: &str) -> bool {
    use crate::batbelt::evm::types::EvmMutability;
    // The type itself, and whoever declares it as a base. An interface in this repository often
    // declares only part of its surface — `IListingLaunchpad` declares five methods and the code
    // calls `poolCreator`, which is written with `view` in the contract that implements it. Same
    // rule, wider search, and still the language's own word rather than a guess at a name.
    // The type, everything it INHERITS from (transitively), and everything that declares it as
    // a base. `ICLPoolManager` declares eleven methods and `vault` is not one of them — it comes
    // from the interface it extends, and a getter drawn as if it moved value is exactly the
    // noise this filter exists to remove.
    let mut family: BTreeSet<&str> = [type_name].into_iter().collect();
    let mut walking = vec![type_name];
    while let Some(name) = walking.pop() {
        for contract in metadata.contracts.iter().filter(|c| c.name == name) {
            for base in &contract.base_contracts {
                if family.insert(base.as_str()) {
                    walking.push(base.as_str());
                }
            }
        }
    }
    let declares = |contract: &ContractMetadata| {
        family.contains(contract.name.as_str())
            || contract.base_contracts.iter().any(|base| base == type_name)
    };
    metadata
        .contracts
        .iter()
        .filter(|contract| declares(contract))
        .flat_map(|contract| contract.functions.iter())
        .filter(|function| function.name == method)
        .map(|function| matches!(function.mutability, EvmMutability::View | EvmMutability::Pure))
        // Several declarations of one name (a vendored copy and ours, an interface and its
        // implementer): a single one that writes is enough to keep the leaf.
        .reduce(|a, b| a && b)
        // Searching for the NAME in unrelated contracts was the other candidate and it is a
        // guess: `poolCreator` is `view` on `IAscendLaunchpad` while the call is typed
        // `IListingLaunchpad`, which declares no such thing. What settles that is the auditor
        // resolving the interface (`bat-cli resolve`), not this function picking a declaration
        // that looks similar. Until then the leaf is drawn.
        .unwrap_or(false)
}

/// A leaf under each outside box: the METHODS this caller actually calls on it.
///
/// A box reading `IERC20` says the code touches a token; `IERC20 → safeTransfer` says value
/// leaves here, and `IERC20 → balanceOf` says nothing leaves at all. That difference is most of
/// what an audit wants from a boundary, and the scan already records it — the map was throwing
/// it away. Thirteen interfaces in ascend, 44 distinct (interface, method) pairs, but a single
/// caller's copy carries only the two or three methods IT calls.
///
/// Attached to the CALLER'S OWN copy of the interface, so the methods never pool on one shared
/// box, which is the thing that made a shared `IERC20` the busiest node on the map.
fn method_leaves(
    metadata: &EvmBatMetadata,
    drawn: &[Edge],
    all_methods: bool,
) -> (Vec<Edge>, Vec<UnnamedParty>) {
    // Which outside boxes exist, by (caller, interface) — the methods are hung on those and on
    // nothing else, so folding (`hosts`) and the ignore list are respected without repeating
    // their rules here.
    let boxes: BTreeSet<(&str, &str)> = drawn
        .iter()
        .filter(|edge| edge.relation == Relation::Boundary)
        .map(|edge| (edge.from.as_str(), original_of(&edge.to)))
        .collect();

    // A library's code runs as the contract that uses it, and the relations already say so —
    // the method leaves did not. `VaultPay.buyExactIn` calls `pm.swap` and `vault.sync`, and
    // because the library's own box is folded away, those leaves were dropped: the
    // `ICLPoolManager` box under `YieldRouter` came out with no methods at all.
    let hosted = hosts(metadata);
    let mut found: BTreeSet<Edge> = BTreeSet::new();
    let mut unnamed: BTreeSet<UnnamedParty> = BTreeSet::new();
    for contract in metadata.contracts.iter().filter(|c| !c.vendored) {
        let running: Vec<&ContractMetadata> = std::iter::once(contract)
            .chain(
                hosted
                    .get(&contract.name)
                    .into_iter()
                    .flatten()
                    .chain(inherited(metadata, contract).iter())
                    .filter_map(|name| {
                        metadata.contracts.iter().find(|c| !c.vendored && c.name == *name)
                    }),
            )
            .collect();
        // `source` declares the function — its state and its name are what an answer is keyed
        // by; `contract` is the box the leaf hangs under.
        for (source, function) in running
            .iter()
            .flat_map(|source| source.functions.iter().map(move |function| (*source, function)))
        {
            let calls = function
                .unknown_external_calls
                .iter()
                .map(|call| {
                    // A library wrapper is drawn as the call it actually makes: what crosses the
                    // boundary is `transfer`, not the `safeTransfer` that decides to make it —
                    // and `IERC20` has no `safeTransfer` to show.
                    let (method, arguments) =
                        unwrap_library_call(metadata, source, &call.method, &call.arguments)
                            .unwrap_or_else(|| (call.method.clone(), call.arguments.clone()));
                    // A LIBRARY's parameters are filled by whoever calls it, and each host
                    // fills them differently: `VaultPay.buyExactIn(…, to)` takes
                    // `l.receiver` from the router and `d.devBuyRecipient` from the launchpad.
                    // Resolving the library's own parameter names made one set of destinations
                    // and hung it on every host — the router's `take()` showed the launchpad's
                    // recipients and the launchpad showed the router's.
                    let mut parties = Vec::new();
                    let mut gaps = Vec::new();
                    for (whose, at, arguments) in
                        call_sites(contract, source, function, &arguments)
                    {
                        let (found, missing) = parties_of(
                            metadata,
                            whose,
                            at,
                            &call.inferred_type,
                            &method,
                            &arguments,
                        );
                        for party in found {
                            if !parties.contains(&party) {
                                parties.push(party);
                            }
                        }
                        gaps.extend(missing);
                    }
                    (call.inferred_type.clone(), method, parties, gaps)
                })
                .chain(function.unresolved_calls.iter().map(|call| {
                    (call.inferred_type.clone(), call.method.clone(), Vec::new(), Vec::new())
                }));
            for (type_name, method, parties, gaps) in calls {
                if type_name.is_empty() || method.is_empty() {
                    continue;
                }
                // A library call by name is drawn as what it DOES to its first argument:
                // `SafeTransferLib.safeTransfer(ERC20(token), to, amount)` is a transfer on
                // that token, and `safeTransferETH(to, amount)` is native value leaving. The
                // library itself is no box — its code runs here — so without this the call had
                // nowhere to land.
                let type_name = through_library(metadata, &type_name, &method)
                    .unwrap_or_else(|| type_name.clone());
                let TypeTarget::Outside(outside) =
                    classify_type(metadata, Some(contract.name.as_str()), &type_name)
                else {
                    continue;
                };
                if !boxes.contains(&(contract.name.as_str(), outside.as_str())) {
                    continue;
                }
                if !all_methods && reads_only(metadata, &outside, &method) {
                    continue;
                }
                // `IStakingSwapRouter.ExactInputParams(path, …)` is a STRUCT, written with the
                // interface that declares it in front — it is not a call on that interface and
                // it never crossed anything. The scan records the struct, so this is read off
                // the declaration rather than guessed from the capital letter.
                if declares_struct(metadata, &outside, &method) {
                    continue;
                }
                let leaf = format!("{outside}{OUTSIDE_MARK}{}", contract.name);
                let method_leaf = format!("{leaf}{METHOD_MARK}{method}");
                found.insert(Edge {
                    from: leaf.clone(),
                    to: method_leaf.clone(),
                    relation: Relation::Boundary,
                });
                // And the other PARTIES of that call: every address it is handed that names a
                // contract. A map that says `safeTransfer` says half of it; this is the half
                // that tells an audit where the value went.
                for party in &parties {
                    found.insert(Edge {
                        from: method_leaf.clone(),
                        to: format!("{method_leaf}{DESTINATION_MARK}{party}"),
                        relation: Relation::Boundary,
                    });
                }
                // Only the gaps of a call that IS drawn: a report about a box nobody can see is
                // a report about nothing.
                unnamed.extend(gaps);
                // And the control that comes BACK. A method whose body calls on `msg.sender`
                // calls its caller: `Vault.lock` ends in `ILockCallback(msg.sender)
                // .lockAcquired(data)`, so `lock()` hands the thread back here. Nothing in the
                // signature says it — `lock(bytes)` — and it is a fact about the code, not a
                // guess from a name.
                for back in calls_back(metadata, source, &type_name, &method) {
                    found.insert(Edge {
                        from: method_leaf.clone(),
                        to: format!(
                            "{method_leaf}{DESTINATION_MARK}calls back {back}{ROLE_MARK}{}",
                            contract.name
                        ),
                        relation: Relation::Boundary,
                    });
                }
            }
            // Native HYPE leaving the contract: `to.call{value: amount}("")`. There is no
            // interface and no method name here — the EVM's own transfer is the whole call —
            // so it gets a boundary box of its own, with the receiver as its party. It used to
            // be reported as an untyped receiver and drawn nowhere, which is how the one leg of
            // `StakerDistributor._pay` that moves native value stayed invisible.
            for call in &function.unknown_external_calls {
                // A library that ends in a low-level call moves value from WHOEVER calls it,
                // and says so only in assembly: `SafeTransferLib.safeTransferETH(to, amount)`
                // is `Treasury.sweep` paying out, with nothing in the signature to show for it.
                // Its first address parameter is where the value goes, filled by this call.
                let through = sends_native(metadata, &call.inferred_type, &call.method);
                let sends_value = call.method.ends_with("{value}") || through.is_some();
                let low_level = matches!(
                    call.method.trim_end_matches("{value}"),
                    "call" | "delegatecall"
                );
                if !(sends_value || low_level) || call.receiver == "assembly" {
                    continue;
                }
                // Whose address the value goes to: the receiver of a low-level call, or the
                // argument that filled the library's address parameter.
                let receiver = match through {
                    Some(at) => match call.arguments.get(at) {
                        Some(argument) => argument.clone(),
                        None => continue,
                    },
                    None => call.receiver.clone(),
                };
                // Value makes it a transfer of native HYPE; without value it is a call into
                // whatever that address is — `router.call(data)` in an aggregator, which is as
                // much a boundary as any interface and was drawn nowhere.
                let box_name = match sends_value {
                    true => NATIVE_BOX,
                    false => LOW_LEVEL_BOX,
                };
                let leaf = format!("{box_name}{OUTSIDE_MARK}{}", contract.name);
                let method_leaf = format!("{leaf}{METHOD_MARK}{}", call.method);
                found.insert(Edge {
                    from: contract.name.clone(),
                    to: leaf.clone(),
                    relation: Relation::Boundary,
                });
                found.insert(Edge {
                    from: leaf.clone(),
                    to: method_leaf.clone(),
                    relation: Relation::Boundary,
                });
                match entity_of(metadata, source, &function.name, &receiver) {
                    Some(entity) => {
                        // The cast at the call site names what is being paid, where the
                        // variable's own type is a bare `address`: `IKinetiqStaking(
                        // stakingManager).stake{value: v}()` pays a staking manager.
                        let entity = match (&call.inferred_type, entity.ends_with(ADDRESS_MARK)) {
                            (cast, true) if !cast.is_empty() => {
                                format!("{}{VARIABLE_MARK}{cast}", entity.trim_end_matches(ADDRESS_MARK))
                            }
                            _ => entity,
                        };
                        for named in entity.split(',').map(str::trim).filter(|n| !n.is_empty()) {
                            // The same rule as any other party: the mark goes on the whole
                            // name, and whether it is an account is a question about the
                            // CONTRACT, not about the variable in front of it. Marking the
                            // variable form drew `distributor (StakerDistributor~)`.
                            let named = named.strip_suffix(ADDRESS_MARK).unwrap_or(named);
                            let held = held_entity(named);
                            let account = !metadata.contracts.iter().any(|c| c.name == held)
                                && !named.starts_with("address(")
                                && !named.starts_with("payable(");
                            let party = match account {
                                true => format!("to{ROLE_MARK}{named}{ADDRESS_MARK}"),
                                false => format!("to{ROLE_MARK}{named}"),
                            };
                            found.insert(Edge {
                                from: method_leaf.clone(),
                                to: format!("{method_leaf}{DESTINATION_MARK}{party}"),
                                relation: Relation::Boundary,
                            });
                        }
                    }
                    None => {
                        unnamed.insert(UnnamedParty {
                            contract: source.name.clone(),
                            file: source.file_path.clone(),
                            function: function.name.clone(),
                            line: function.line,
                            end_line: function.end_line,
                            call: format!("{box_name}.{}", call.method),
                            argument: receiver.clone(),
                            key: Some(format!(
                                "{}.{}.{receiver}",
                                source.name, function.name
                            )),
                        });
                    }
                }
            }
        }
    }
    (found.into_iter().collect(), unnamed.into_iter().collect())
}

fn layout_map(edges: &[Edge]) -> crate::batbelt::miro::layout::GraphLayout {
    use crate::batbelt::miro::layout::{layout_graph, LayoutConfig, LayoutEdge, LayoutNode};

    let mut names: Vec<String> = edges
        .iter()
        .flat_map(|edge| [edge.from.clone(), edge.to.clone()])
        .collect();
    names.sort();
    names.dedup();
    let nodes: Vec<LayoutNode> = names
        .iter()
        .map(|name| LayoutNode {
            id: name.clone(),
            width: node_width(name),
            height: node_height(name),
        })
        .collect();
    // The frame's own contract first, and the chain growing rightwards from it.
    //
    // The edges used to be fed REVERSED, so that the contract everything needs — `Treasury` —
    // landed leftmost and the deployment order read left to right. That was the right rule for
    // one frame of the whole system. It is the wrong one now that a frame is one contract's
    // story: its subject ended up at the far RIGHT, every arrow ran right to left, and the
    // reader started at the end. The hierarchy of the system is answered by `--hierarchy` and
    // by which contracts have a frame at all, not by where a box sits inside one.
    let laid_edges: Vec<LayoutEdge> = edges
        .iter()
        .map(|edge| LayoutEdge {
            from: edge.from.clone(),
            to: edge.to.clone(),
            from_line_fraction: 0.5,
        })
        .collect();

    // The root is the frame's own contract: what nothing here calls.
    let called: BTreeSet<&str> = edges.iter().map(|edge| edge.to.as_str()).collect();
    let root = names
        .iter()
        .find(|name| !called.contains(name.as_str()))
        .cloned()
        .unwrap_or_else(|| names[0].clone());

    // Laid out TWICE, and the second time is the point. The first tells us which column each
    // contract lands in; from that we can count how many arrows cross each gutter, and a
    // gutter has to be wide enough to hold them all a full pitch apart. Squeezing the lanes
    // instead is how a picture stops saying which arrow is which — so the gutter widens and
    // the layout is asked again. It is pure, so asking twice costs nothing but arithmetic, and
    // the second answer differs only in x.
    let config = |gutter_x: f64| LayoutConfig {
        padding_x: MAP_MARGIN,
        // No room reserved for a legend: it has a frame of its own now, and reserving its
        // height here left every contract's frame opening with a screen of nothing.
        padding_y: MAP_MARGIN,
        gutter_x,
        // Boxes of a map are a name each, a fraction of the height of a screenshot, so the
        // deploy's gap between them leaves six rows crammed into the top of the frame while
        // every arrow queues through the same strip of middle. Spread vertically, an arrow has
        // room to travel at its own height.
        gutter_y: NODE_HEIGHT * 1.5,
        ..Default::default()
    };
    let first = layout_graph(&root, &nodes, &laid_edges, config(LayoutConfig::default().gutter_x));
    let busiest = busiest_gutter(edges, &first);
    let wanted = crate::batbelt::miro::layout::gutter_for(busiest);
    let mut layout = if wanted <= LayoutConfig::default().gutter_x {
        first
    } else {
        layout_graph(&root, &nodes, &laid_edges, config(wanted))
    };
    order_hub_column(&mut layout, edges);
    layout
}

/// Put the most-called contracts of the first column in the MIDDLE of it, and the rest
/// outwards from there.
///
/// The first column is what calls nothing in scope: the contracts everything else depends on.
/// The barycentre sweep orders it to cut crossings between the first two columns, which is
/// the right rule everywhere else — but the thing a reader asks of this column is "which one
/// does everybody write to", and the answer should be where the eye lands first. A hub in the
/// middle also takes its arrows from above and below, half each, instead of all of them
/// running the height of the frame to reach a box the sweep left at the top.
///
/// Only the first column, and only by swapping the y's it already has: every box is one
/// height, so the slots are interchangeable and nothing else in the layout moves.
fn order_hub_column(layout: &mut GraphLayout, edges: &[Edge]) {
    // Column 0 is the frame's own contract now — one box — so this returns immediately on a
    // map and stays only for the case of a frame whose root is a cycle with several entries.

    let mut incoming: BTreeMap<&str, usize> = BTreeMap::new();
    for edge in edges {
        *incoming.entry(edge.to.as_str()).or_default() += 1;
    }
    let mut members: Vec<usize> = (0..layout.nodes.len())
        .filter(|&index| layout.nodes[index].layer == 0)
        .collect();
    if members.len() < 2 {
        return;
    }
    let mut slots: Vec<f64> = members.iter().map(|&index| layout.nodes[index].y).collect();
    slots.sort_by(|a, b| a.partial_cmp(b).unwrap_or(std::cmp::Ordering::Equal));
    // Most called first, then by name so two equally popular contracts always come out the
    // same way round.
    members.sort_by(|&a, &b| {
        let calls = |index: usize| incoming.get(layout.nodes[index].id.as_str()).copied().unwrap_or(0);
        calls(b).cmp(&calls(a)).then_with(|| layout.nodes[a].id.cmp(&layout.nodes[b].id))
    });
    for (rank, index) in members.into_iter().enumerate() {
        layout.nodes[index].y = slots[centre_out(rank, slots.len())];
    }
}

/// The slot the `rank`-th item takes when `count` slots are filled from the middle outwards:
/// the middle, then one below, one above, two below, two above.
fn centre_out(rank: usize, count: usize) -> usize {
    let middle = (count - 1) / 2;
    let distance = (rank + 1) / 2;
    if rank % 2 == 1 {
        (middle + distance).min(count - 1)
    } else {
        middle.saturating_sub(distance)
    }
}

/// How many arrows cross the busiest gutter.
///
/// An edge between columns `a` and `b` passes through every gutter between them, so a gutter's
/// load is not "the edges that end here" — that undercount is what let twelve arrows share a
/// gutter sized for one.
fn busiest_gutter(edges: &[Edge], layout: &crate::batbelt::miro::layout::GraphLayout) -> usize {
    let mut per_gutter: BTreeMap<usize, usize> = BTreeMap::new();
    for edge in edges {
        let (Some(from), Some(to)) = (layout.node(&edge.from), layout.node(&edge.to)) else {
            continue;
        };
        let (low, high) = (from.layer.min(to.layer), from.layer.max(to.layer));
        for gutter in low..high {
            *per_gutter.entry(gutter).or_default() += 1;
        }
    }
    per_gutter.into_values().max().unwrap_or(0)
}

/// Put the map on the board: every frame, then every box and marker, then every leg.
async fn draw(
    client: &MiroClient,
    prepared: PreparedMap,
    left: f64,
    top: f64,
) -> Result<Vec<crate::batbelt::evm::metadata::bat_metadata::MapFrameRef>, EvmMiroError> {
    use crate::batbelt::evm::miro::auto_deploy::LaneSide;
    use crate::batbelt::miro::MiroError;

    // The frames first and together: everything else is a child of one of them, and a frame is
    // the one thing here nothing can be issued before.
    let mut frames_wave: tokio::task::JoinSet<(usize, String, std::result::Result<String, Report<MiroError>>)> =
        tokio::task::JoinSet::new();
    for (index, frame) in prepared.frames.iter().enumerate() {
        let client = client.clone();
        let title = frame.title.clone();
        let (x, y) = (
            left + frame.left + frame.width / 2.0,
            top + frame.top + frame.height / 2.0,
        );
        let (width, height) = (frame.width, frame.height);
        frames_wave.spawn(async move {
            let made = client.create_frame(&title, x, y, width, height, None).await;
            (index, title, made)
        });
    }
    let mut frame_ids: BTreeMap<usize, String> = BTreeMap::new();
    let mut failures: Vec<String> = Vec::new();
    while let Some(joined) = frames_wave.join_next().await {
        match joined {
            Ok((index, _, Ok(id))) => {
                frame_ids.insert(index, id);
            }
            Ok((_, title, Err(report))) => {
                failures.push(format!("frame {title}: {}", why(&report)))
            }
            Err(error) => failures.push(format!("a frame: {error}")),
        }
    }
    if frame_ids.is_empty() {
        return Err(Report::new(EvmMiroError)
            .attach_printable("not one frame of the map could be created")
            .attach_printable(failures.join("; ")));
    }

    // ONE wave for everything whose only reference is a frame: the boxes, the badges, the
    // legend's rows, the strip and every marker of every arrow. A marker's position came from
    // the plan, not from a box's id, so nothing about it waits on a box.
    //
    // And sent in BATCHES of twenty, which is the part that matters. One item per request, 226
    // requests at 48 in flight, took 75 seconds against a budget that allows 16.7 writes a
    // second — so the wall was never the budget, it was waiting for a round trip per item.
    // Miro's bulk endpoint takes twenty items a call; connectors it does not take, so the legs
    // below still go one by one.
    enum Made {
        Boxes(usize),
        Markers(Vec<(usize, usize, usize)>, Vec<String>),
    }
    type Outcome = (String, std::result::Result<Made, Report<MiroError>>);
    let mut wave: tokio::task::JoinSet<Outcome> = tokio::task::JoinSet::new();
    /// Miro's limit for one bulk call.
    const BATCH: usize = 20;
    // Every item of every frame, in one list, so a batch is full even when a frame holds three
    // boxes: batching per frame would have sent eight half-empty calls.
    let mut plain: Vec<(String, serde_json::Value)> = Vec::new();
    let mut marker_items: Vec<((usize, usize, usize), serde_json::Value)> = Vec::new();

    for (index, frame) in prepared.frames.iter().enumerate() {
        let Some(frame_id) = frame_ids.get(&index) else {
            continue;
        };
        type Box<'a> = (String, String, f64, f64, f64, f64, usize, &'a str, &'a str, usize, &'a str, &'a str);
        let mut boxes: Vec<Box> = Vec::new();
        if frame.is_legend() {
            for row in legend_rows() {
                let (fill, border, style) = match row.sample {
                    Sample::Leg(_) => (BOX_FILL, BOX_BORDER, "normal"),
                    Sample::Box { fill, border, style } => (fill, border, style),
                };
                // The legend's own sample of a repeated contract has to look like one.
                let thickness = if border == BOX_BORDER { BORDER_WIDTH } else { REPEAT_BORDER_WIDTH };
                boxes.push((
                    format!("legend: {}", row.text),
                    row.text.to_string(),
                    row.x,
                    row.y,
                    row.width,
                    NODE_HEIGHT,
                    NODE_FONT,
                    fill,
                    border,
                    thickness,
                    BOX_BORDER,
                    style,
                ));
            }
        }
        for node in &frame.layout.nodes {
            let (repeat_border, thickness) = frame.border_of(&node.id);
            let (fill, colour, style) = frame.paint_of(&node.id, &prepared.marked);
            let border = if repeat_border == BOX_BORDER { colour } else { repeat_border };
            boxes.push((
                format!("box {}", box_text(&node.id)),
                box_text(&node.id).to_string(),
                node.x,
                node.y,
                node.width,
                node.height,
                node_font(&node.id),
                fill,
                border,
                thickness,
                // The name carries the interface's colour; a contract's stays black.
                if is_outside(&node.id) && destination_of(&node.id).is_none() { colour } else { BOX_BORDER },
                style,
            ));
        }
        for node in &frame.strip {
            boxes.push((
                format!("strip: {}", box_text(&node.id)),
                box_text(&node.id).to_string(),
                node.x,
                node.y,
                node.width,
                node.height,
                NODE_FONT,
                STRIP_FILL,
                BOX_BORDER,
                BORDER_WIDTH,
                BOX_BORDER,
                "normal",
            ));
        }
        for (what, text, x, y, width, height, font, fill, border, thickness, text_colour, style) in boxes {
            plain.push((
                what,
                MiroClient::label_item(
                    &text,
                    x,
                    y,
                    width,
                    height,
                    font,
                    fill,
                    border,
                    thickness,
                    text_colour,
                    style,
                    frame_id,
                ),
            ));
        }
        for (arrow_index, arrow) in frame.arrows.iter().enumerate() {
            for (point, (x, y)) in arrow.plan.points.iter().enumerate() {
                marker_items.push((
                    (index, arrow_index, point),
                    MiroClient::marker_item(*x, *y, MARKER_SIZE, frame_id),
                ));
            }
        }
    }

    for batch in plain.chunks(BATCH) {
        let client = client.clone();
        // Named by its first item: a batch that fails has to say what is missing, and listing
        // twenty names in one line says nothing a reader can use.
        let what = format!("a batch of {} item(s) from {}", batch.len(), batch[0].0);
        let items: Vec<serde_json::Value> = batch.iter().map(|(_, item)| item.clone()).collect();
        let count = items.len();
        wave.spawn(async move {
            let made = client.create_items_bulk(items).await.map(|_| Made::Boxes(count));
            (what, made)
        });
    }
    for batch in marker_items.chunks(BATCH) {
        let client = client.clone();
        let what = format!("a batch of {} marker(s)", batch.len());
        let keys: Vec<(usize, usize, usize)> = batch.iter().map(|(key, _)| *key).collect();
        let items: Vec<serde_json::Value> = batch.iter().map(|(_, item)| item.clone()).collect();
        wave.spawn(async move {
            let made = client
                .create_items_bulk(items)
                .await
                .map(|ids| Made::Markers(keys, ids));
            (what, made)
        });
    }

    // Every task is awaited, whatever happens to any of them. Returning on the first failure
    // aborts the requests still in flight: items get created that nothing reports, and the
    // frames' URLs are never printed, so the auditor is left with a half-drawn board and no
    // idea what is on it. A failure costs its own item and is named.
    let mut markers: BTreeMap<(usize, usize, usize), String> = BTreeMap::new();
    let mut boxes_made = 0usize;
    while let Some(joined) = wave.join_next().await {
        match joined {
            Ok((_, Ok(Made::Boxes(count)))) => boxes_made += count,
            Ok((what, Ok(Made::Markers(keys, ids)))) => {
                // The bulk endpoint answers in the order it was sent, which is what lets a
                // marker be found again by the leg that lands on it. If it ever does not, the
                // legs of those arrows are named as skipped rather than drawn somewhere wrong.
                if ids.len() != keys.len() {
                    failures.push(format!("{what}: {} item(s) back for {} sent", ids.len(), keys.len()));
                }
                for (key, id) in keys.into_iter().zip(ids) {
                    markers.insert(key, id);
                }
            }
            Ok((what, Err(report))) => failures.push(format!("{what}: {}", why(&report))),
            Err(error) => failures.push(format!("a task: {error}")),
        }
    }
    println!(
        "    {} {} frame(s), {boxes_made} box(es), {} marker(s)",
        "✓".green(),
        frame_ids.len(),
        markers.len()
    );

    // Then every leg of every arrow, together: each one's two ends already exist. The caption
    // rides on the leg that carries the head, and on that one only — a word on every leg of a
    // five-leg chain is five words.
    let mut legs_wave = tokio::task::JoinSet::new();
    let mut skipped: Vec<String> = Vec::new();
    for (index, frame) in prepared.frames.iter().enumerate() {
        if !frame_ids.contains_key(&index) {
            continue;
        }
        for (arrow_index, arrow) in frame.arrows.iter().enumerate() {
            for (from_side, from_anchor, to_side, to_anchor, head) in &arrow.plan.legs {
                let resolve = |side: &LaneSide| match side {
                    LaneSide::Marker(point) => markers.get(&(index, arrow_index, *point)).cloned(),
                    LaneSide::Item(id) => Some(id.clone()),
                };
                let (Some(from_id), Some(to_id)) = (resolve(from_side), resolve(to_side)) else {
                    // Its marker failed, so this leg has nowhere to land. Named rather than
                    // dropped: a missing arrow the reader is not told about is a map that lies.
                    skipped.push(format!("{}: a leg whose marker failed", arrow_name(frame, arrow)));
                    continue;
                };
                let mut leg = arrow.style.clone();
                leg.arrow = if *head { ArrowEnd::End } else { ArrowEnd::None };
                if !*head {
                    leg.caption = None;
                }
                let (from_anchor, to_anchor) = (*from_anchor, *to_anchor);
                let what = arrow_name(frame, arrow);
                let client = client.clone();
                legs_wave.spawn(async move {
                    let made = client
                        // STRAIGHT, not elbowed. Every leg of a map's arrow is already
                        // horizontal or vertical — the chain is planned that way — so `elbowed`
                        // handed a segment we had already computed to Miro's own router, which
                        // added its own elbows on top and drew a staircase where a line was
                        // asked for. The deploy keeps `elbowed`, where a leg can be diagonal
                        // and a straight one would cut across a screenshot.
                        .create_connector_shaped(
                            &from_id, from_anchor, &to_id, to_anchor, leg, "straight",
                        )
                        .await;
                    (what, made)
                });
            }
        }
    }
    let mut legs = 0usize;
    while let Some(joined) = legs_wave.join_next().await {
        match joined {
            Ok((_, Ok(_))) => legs += 1,
            Ok((what, Err(report))) => failures.push(format!("leg of {what}: {}", why(&report))),
            Err(error) => failures.push(format!("a leg: {error}")),
        }
    }
    for line in skipped.iter().chain(failures.iter()) {
        println!("    {} {line}", "skipped:".yellow());
    }
    println!(
        "    {} {} relation(s) drawn, {legs} leg(s)",
        "✓".green(),
        prepared
            .frames
            .iter()
            .flat_map(|frame| frame.arrows.iter())
            .filter(|arrow| arrow.edge.is_some())
            .count()
    );
    // One URL per frame, named: the whole point of several frames is that the auditor goes to
    // the one contract they are reading about.
    for (index, frame) in prepared.frames.iter().enumerate() {
        if let Some(id) = frame_ids.get(&index) {
            println!("  {:<46} {}", frame.title, client.frame_url(id).blue());
        }
    }
    // What was drawn, for the registry: which frame shows which contracts. A cluster cannot
    // point at the map without it, and the ids live nowhere else once this run ends.
    let drawn_frames: Vec<crate::batbelt::evm::metadata::bat_metadata::MapFrameRef> = prepared
        .frames
        .iter()
        .enumerate()
        .filter(|(_, frame)| !frame.is_legend())
        .filter_map(|(index, frame)| {
            Some(crate::batbelt::evm::metadata::bat_metadata::MapFrameRef {
                root: frame.root().to_string(),
                frame_id: frame_ids.get(&index)?.clone(),
                contracts: frame.contracts_shown(),
                cards: Vec::new(),
            })
        })
        .collect();
    if !failures.is_empty() {
        return Err(Report::new(EvmMiroError).attach_printable(format!(
            "{} item(s) of this map could not be drawn — the frames above have the rest",
            failures.len()
        )));
    }
    Ok(drawn_frames)
}

/// Why a call failed, in one line: the attachments the client hung on the report — which is
/// where the HTTP status and Miro's own message live.
///
/// Printing `current_context()` alone printed "Miro error" and nothing else, which told the
/// reader a thing failed and not one fact about why. The body is already carried; it was simply
/// never shown.
fn why(report: &Report<crate::batbelt::miro::MiroError>) -> String {
    let detail: Vec<String> = report
        .frames()
        .filter_map(|frame| frame.downcast_ref::<String>().map(|line| line.trim().to_string()))
        .collect();
    if detail.is_empty() {
        report.current_context().to_string()
    } else {
        detail.join(" — ")
    }
}

/// What an arrow is, for a message about it.
fn arrow_name(frame: &PreparedFrame, arrow: &RoutedArrow) -> String {
    match arrow.edge.and_then(|index| frame.edges.get(index)) {
        Some(edge) => format!("{} → {}", box_text(&edge.from), box_text(&edge.to)),
        None => "a legend sample".to_string(),
    }
}

/// Every relation between contracts, one per pair and kind — the outside included.
///
/// What LEAVES the repository is always worked out, because the panel beside the diagram is
/// made of it; whether it also gets a box is `drawn_edges`'s decision and the auditor's flag.
///
/// Three sources, which is the point: a call the scan pinned by type, a binding it refused to
/// pin, and the addresses a constructor fixes. The third is the one an auditor cannot get by
/// reading a call graph at all — a contract can be wired to another it never calls in the
/// paths that survived pruning, and that wiring is still a fact about the system.
pub fn relations(metadata: &EvmBatMetadata) -> Vec<Edge> {
    let in_scope: BTreeSet<&str> = metadata
        .contracts
        .iter()
        .filter(|contract| !contract.vendored)
        .map(|contract| contract.name.as_str())
        .collect();
    let ignored = |name: &str, path: &str| {
        metadata
            .ignored_contracts
            .iter()
            .any(|pattern| matches_ignore(pattern, name, path))
    };

    let hosted_by = hosts(metadata);
    // A library or an abstract base is not a node: its code runs as the contract that uses it,
    // which is what `hosts` works out. It is not a destination either — calling `MathLib.wad`
    // executes in the CALLER's address, so an arrow to it would be an arrow a contract draws
    // to itself.
    let folded: BTreeSet<&str> = metadata
        .contracts
        .iter()
        .filter(|contract| {
            !contract.vendored
                && matches!(
                    contract.contract_type,
                    crate::batbelt::evm::types::EvmContractType::Library
                        | crate::batbelt::evm::types::EvmContractType::Abstract
                )
        })
        .map(|contract| contract.name.as_str())
        .collect();

    let mut found: BTreeSet<Edge> = BTreeSet::new();
    for contract in metadata.contracts.iter().filter(|c| !c.vendored) {
        if ignored(&contract.name, &contract.file_path) || folded.contains(contract.name.as_str())
        {
            continue;
        }
        let mut record = |to: &str, relation: Relation| {
            // A contract talking to itself is not a relation worth a line on a map: it is what
            // the contract's own deployment shows. Neither is a call into a library, which is
            // the same thing said differently — that code runs here.
            //
            // An ignored contract is not a destination either. The auditor declared it out of
            // the audit, and `ignored` used to be read only for the contract an edge leaves
            // FROM — so a contract nobody was going to look at still took a box and an arrow
            // the moment somebody called it.
            // `opexTreasury%Treasury` is a deployment of `Treasury`: what is folded, ignored or
            // the caller itself is a question about the contract, never about which copy.
            let entity = to.split_once(VARIABLE_MARK).map(|(_, held)| held).unwrap_or(to);
            // A call written as a cast — `StakingQuoteOracle(oracle_).quoteAsset()` in a
            // constructor — names no variable, and drawing it beside `oracle (StakingQuoteOracle)`
            // is two boxes for one address. When the contract holds exactly ONE variable of that
            // type, that is which one it is; holding several (five `Treasury`s) it stays the
            // plain type, because then the code really does not say.
            // Only for this repository's own contracts: a boundary box is the TYPE the caller
            // sees (`IERC20`, `ERC20`), one copy per caller, and naming it after a variable
            // would say which deployment we cannot know.
            let singular: Option<&str> = match to.contains(VARIABLE_MARK) || !in_scope.contains(entity) {
                true => None,
                false => {
                    // By what the type MEANS, not by how it is written: `IAscendLaunchpad
                    // launchpad` holds an `AscendLaunchpad`, and comparing the raw names drew
                    // the wiring as `launchpad (AscendLaunchpad)` and the call as a second,
                    // plain `AscendLaunchpad` box in the same frame.
                    let mut held = contract.state_variables.iter().filter(|state| {
                        matches!(
                            classify_type(metadata, Some(contract.name.as_str()), &state.type_name),
                            TypeTarget::Contract(ref held) if held == entity
                        )
                    });
                    held.next().filter(|_| held.next().is_none()).map(|state| state.name.as_str())
                }
            };
            // And the variable only sticks to a DEPLOYABLE contract of this repository. An
            // interface or a vendored type is a boundary box, drawn once per caller with its
            // methods hanging off it (`IStakingSwapRouter@YieldRouter`); renaming it after the
            // variable broke that pairing and the methods lost their box.
            let deployable = metadata.contracts.iter().any(|c| {
                !c.vendored
                    && c.name == entity
                    && c.contract_type == crate::batbelt::evm::types::EvmContractType::Contract
            });
            let to = &match (deployable, singular) {
                (false, _) => entity.to_string(),
                (true, Some(variable)) => format!("{variable}{VARIABLE_MARK}{entity}"),
                (true, None) => to.to_string(),
            };
            if entity.is_empty()
                || entity == contract.name
                || folded.contains(entity)
                || ignored(entity, "")
            {
                return;
            }
            found.insert(Edge {
                from: contract.name.clone(),
                to: to.to_string(),
                relation,
            });
        };

        // One rule for every kind of relation: what the type NAME means at runtime decides
        // where the arrow lands, and `with_boundaries` only decides whether an arrow that
        // leaves the code is drawn at all.
        let aim = |type_name: &str, relation: Relation| -> Option<(String, Relation)> {
            // `opexTreasury%Treasury`: which deployment, and of what. The type decides where the
            // arrow lands; the variable only survives when the answer is that type itself.
            let (held_by, type_name) = match type_name.split_once(VARIABLE_MARK) {
                Some((variable, held)) => (Some(variable), held),
                None => (None, type_name),
            };
            match classify_type(metadata, Some(contract.name.as_str()), type_name) {
                TypeTarget::Contract(target) => Some((
                    match held_by {
                        Some(variable) if target == type_name => {
                            format!("{variable}{VARIABLE_MARK}{target}")
                        }
                        _ => target,
                    },
                    relation,
                )),
                TypeTarget::Open(name) => Some((name, Relation::Unresolved)),
                // The outside is always KNOWN — it is what the panel is made of — and the
                // flag decides only whether it also gets a box in the diagram. Dropping it
                // here is how the panel came out empty without the flag.
                TypeTarget::Outside(name) => Some((name, Relation::Boundary)),
                TypeTarget::NotAContract => None,
            }
        };

        // What this contract's code IS: itself, plus every library and abstract base whose
        // functions run as it. A library has no address and no state — its call leaves the
        // host's address — so drawing it as a node invents an actor that does not exist. The
        // folding lives HERE and nowhere else: the entry-point graph still draws every
        // library function as its own screenshot, which is what the auditor reads there.
        let mut sources: Vec<&ContractMetadata> = vec![contract];
        sources.extend(
            hosted_by
                .get(contract.name.as_str())
                .into_iter()
                .flatten()
                .chain(inherited(metadata, contract).iter())
                .filter_map(|name| {
                    metadata
                        .contract_in_scope(name, &contract.file_path)
                        .or_else(|| metadata.contracts.iter().find(|c| &c.name == name))
                }),
        );

        for function in sources.iter().flat_map(|source| source.functions.iter()) {
            // `new X(...)`, which the scan records as a callee named `X.constructor`. Resolved
            // through the CALLER's file, never by name alone: `lib/` holds three `ProxyAdmin`s
            // and the import graph is what says which one this is.
            for created in created_by(metadata, contract, function) {
                record(&created, Relation::Creates);
            }
            // WHICH deployment the call goes to, when the receiver is a state variable:
            // `listingDesk.collect()` is a call on the address `listingDesk` holds, which is
            // the box its creation already drew. Without this the same deployment got two
            // boxes — one named by its variable, one by its type.
            let held_by = |receiver: &str| -> Option<&str> {
                let name = receiver.trim();
                contract
                    .state_variables
                    .iter()
                    .find(|state| state.name == name)
                    .map(|state| state.name.as_str())
            };
            for call in &function.resolved_calls {
                if in_scope.contains(call.contract.as_str()) {
                    // A call that only READS is a relation that sets nothing off. `YieldRouter`
                    // reaches `AscendLaunchpad` through `poolManager()` and `emaSqrtPrice()`
                    // and nothing else — and the frame hung the launchpad's whole mutating
                    // subtree under that arrow, a graph the router cannot trigger.
                    let kind = match reads_only(metadata, &call.contract, &call.method) {
                        true => Relation::Reads,
                        false => Relation::Calls,
                    };
                    let to = match held_by(&call.receiver) {
                        Some(variable) => format!("{variable}{VARIABLE_MARK}{}", call.contract),
                        None => call.contract.clone(),
                    };
                    record(&to, kind);
                }
            }
            let typed = function
                .unresolved_calls
                .iter()
                .map(|call| (call.receiver.as_str(), call.inferred_type.as_str(), call.method.as_str()))
                .chain(function.unknown_external_calls.iter().map(|call| {
                    (call.receiver.as_str(), call.inferred_type.as_str(), call.method.as_str())
                }));
            for (receiver, type_name, method) in typed {
                // A library call by name is a call on its first parameter — the receiver
                // `using X for Y` would have made explicit. Classified as the library itself it
                // was folded or ignored away, and with it went `Treasury.sweep`'s token leg.
                let aimed_type = through_library(metadata, type_name, method);
                let type_name = aimed_type.as_deref().unwrap_or(type_name);
                let kind = match reads_only(metadata, type_name, method) {
                    true => Relation::Reads,
                    false => Relation::Calls,
                };
                let aimed = match held_by(receiver) {
                    Some(variable) => format!("{variable}{VARIABLE_MARK}{type_name}"),
                    None => type_name.to_string(),
                };
                if let Some((to, relation)) = aim(&aimed, kind) {
                    // `aim` keeps the relation it was given unless the far end is unresolved or
                    // outside, which are facts about the TARGET and outrank how it was reached.
                    record(&to, relation);
                }
            }
        }

        for wired in sources.iter().flat_map(|source| wired_at_construction(source, &metadata.wiring)) {
            if let Some((to, relation)) = aim(&wired, Relation::WiresAtConstruction) {
                record(&to, relation);
            }
        }
    }

    // One arrow per pair — two between the same boxes is the noise this map exists to avoid —
    // and the one kept is the one that SAYS THE MOST.
    //
    // `creates` outranks `calls`: that an address exists because of this line is the rare fact,
    // and it is the one nothing else on the board shows. That it also calls what it made is
    // taken for granted — `AscendYieldVault` both creates `YieldExitReserve` in `_checkpoint`
    // and calls it, and the map used to draw only the call, which read as two contracts that
    // happened to find each other.
    //
    // Below that, what a scan is SURER of wins: a call it pinned over wiring it inferred, and
    // either over a binding it could not pin at all.
    let rank = |relation: Relation| match relation {
        Relation::Creates => 0,
        Relation::Calls => 1,
        // A read outranks the wiring: `YieldRouter` holds the vault AND asks it for the rate,
        // and "wired, never called" was the wrong half of that — it says nobody calls, while
        // the code calls twice. One call that CHANGES something still outranks both.
        Relation::Reads => 2,
        Relation::WiresAtConstruction => 3,
        Relation::Unresolved => 4,
        Relation::Boundary => 5,
    };
    let mut best: BTreeMap<(String, String), Relation> = BTreeMap::new();
    for edge in found {
        best.entry((edge.from.clone(), edge.to.clone()))
            .and_modify(|existing| {
                if rank(edge.relation) < rank(*existing) {
                    *existing = edge.relation;
                }
            })
            .or_insert(edge.relation);
    }
    best.into_iter()
        .map(|((from, to), relation)| Edge { from, to, relation })
        .collect()
}

/// Which deployable contracts a library's or an abstract base's code runs as.
///
/// A library has no address: its call leaves the host contract's address, so on a map of who
/// talks to whom the library is not a party. `hosts` answers "whose code is this", from the
/// `Lib.fn` callees the scan recorded and from inheritance, iterated to a FIXPOINT so a
/// library reached only through another library still reaches the contract at the end of the
/// chain.
///
/// Returns host name → the libraries and bases it hosts.
fn hosts(metadata: &EvmBatMetadata) -> BTreeMap<String, BTreeSet<String>> {
    use crate::batbelt::evm::types::EvmContractType;

    let folded: BTreeMap<&str, &ContractMetadata> = metadata
        .contracts
        .iter()
        .filter(|contract| {
            !contract.vendored
                && matches!(
                    contract.contract_type,
                    EvmContractType::Library | EvmContractType::Abstract
                )
        })
        .map(|contract| (contract.name.as_str(), contract))
        .collect();
    if folded.is_empty() {
        return BTreeMap::new();
    }

    // Who uses what, one hop: a contract uses a library when it calls `Lib.fn`, and a base
    // when it declares it.
    let mut uses: BTreeMap<String, BTreeSet<String>> = BTreeMap::new();
    for contract in metadata.contracts.iter().filter(|c| !c.vendored) {
        let mut used: BTreeSet<String> = contract
            .base_contracts
            .iter()
            .filter(|base| folded.contains_key(base.as_str()))
            .cloned()
            .collect();
        // `using VaultPay for IVault` is the other way a contract runs a library's code, and
        // the call site reads `poolVault.buyExactIn(…)` — no `VaultPay.` anywhere for the
        // callee scan to find. Without this, `VaultPay`'s `pm.swap` and `vault.sync` belonged
        // to nobody and the `ICLPoolManager` box under `YieldRouter` came out with no methods.
        used.extend(
            contract
                .using_libraries
                .iter()
                .filter(|library| folded.contains_key(library.as_str()))
                .cloned(),
        );
        for function in &contract.functions {
            for callee in callees_of(metadata, &function.metadata_id) {
                if let Some((receiver, _)) = callee.split_once('.') {
                    if folded.contains_key(receiver) {
                        used.insert(receiver.to_string());
                    }
                }
            }
        }
        uses.insert(contract.name.clone(), used);
    }

    // To a fixpoint: a host inherits what its libraries use. Bounded by the number of
    // contracts, because each pass can only add, and a pass that adds nothing is the end.
    let mut hosted: BTreeMap<String, BTreeSet<String>> = uses
        .iter()
        .filter(|(name, _)| !folded.contains_key(name.as_str()))
        .map(|(name, used)| (name.clone(), used.clone()))
        .collect();
    for _ in 0..metadata.contracts.len().max(1) {
        let mut grew = false;
        for set in hosted.values_mut() {
            let reached: BTreeSet<String> = set
                .iter()
                .filter_map(|library| uses.get(library))
                .flatten()
                .cloned()
                .collect();
            for name in reached {
                grew |= set.insert(name);
            }
        }
        if !grew {
            break;
        }
    }
    hosted
}

/// The callee names the scan recorded for one function, as written (`Lib.fn`, `X.constructor`).
fn callees_of<'a>(metadata: &'a EvmBatMetadata, function_id: &str) -> &'a [String] {
    metadata
        .function_dependencies
        .iter()
        .find(|dependency| dependency.function_metadata_id == function_id)
        .map(|dependency| dependency.callees.as_slice())
        .unwrap_or(&[])
}

/// The deployable contracts one function creates with `new X(...)`.
///
/// The scan writes those as a callee named `X.constructor`. `X` is resolved through the
/// CALLER's file — `lib/` vendors three `ProxyAdmin`s, and the import graph is the only thing
/// that says which one a name means here. A `new` of vendored or unknown code is not a
/// relation on this map; it is listed with the untyped receivers instead.
fn created_by(
    metadata: &EvmBatMetadata,
    caller: &ContractMetadata,
    function: &crate::batbelt::evm::metadata::bat_metadata::FunctionMetadata,
) -> Vec<String> {
    // WHERE each one was put. `AscendLaunchpad`'s constructor runs `new Treasury(owner_)` five
    // times into five variables: five addresses, and keyed by the type alone the map drew one
    // arrow to one box. The variable names the box — the same box its transfers point at, so
    // this costs the board nothing it was not already drawing.
    callees_of(metadata, &function.metadata_id)
        .iter()
        .filter_map(|callee| callee.strip_suffix(".constructor"))
        .filter_map(|name| metadata.contract_in_scope(name, &caller.file_path))
        .filter(|target| !target.vendored)
        .flat_map(|target| {
            let variables: Vec<&str> = function
                .creations
                .iter()
                .filter(|(variable, created)| {
                    created == &target.name
                        && caller.state_variables.iter().any(|state| state.name == *variable)
                })
                .map(|(variable, _)| variable.as_str())
                .collect();
            match variables.is_empty() {
                // Not stored in state: a local, a return value. Nothing names it but its type.
                true => vec![target.name.clone()],
                false => variables
                    .into_iter()
                    .map(|variable| format!("{variable}{VARIABLE_MARK}{}", target.name))
                    .collect(),
            }
        })
        .collect()
}

/// The contracts whose address this one fixes when it is built.
///
/// An `immutable` of a contract type, or a state variable of one assigned in the constructor,
/// is the system's wiring written down: `YieldRouter` holds `vault`, `venue`, `oracle` and
/// `distributor` from the moment it exists. The type is the relation — what the variable is
/// called tells you nothing a map can draw.
fn wired_at_construction(
    contract: &ContractMetadata,
    wiring: &std::collections::HashMap<String, String>,
) -> Vec<String> {
    let constructor_writes: BTreeSet<&str> = contract
        .functions
        .iter()
        .filter(|function| function.is_constructor)
        .flat_map(|function| function.storage_writes.iter())
        .map(|write| write.split(['.', '[']).next().unwrap_or(write))
        .collect();

    contract
        .state_variables
        .iter()
        .filter(|variable| {
            // Fixed at construction: an immutable (which can be assigned nowhere else) or a
            // variable the constructor assigns.
            variable.is_immutable || constructor_writes.contains(variable.name.as_str())
        })
        // The raw type, which `classify_type` then reads: an interface collapses into its
        // implementer, a struct or an `address` is not a relation at all. Deciding that here
        // by the first letter being a capital is what let `Limits` and `CurveStep[]` onto
        // the map as contracts.
        // The variable comes along: `opexTreasury` and `kntqTreasury` are two addresses of one
        // type, and the wiring arrow has to land on the same box its creation did instead of
        // adding a generic `Treasury` beside the six named ones. `aim` drops the variable
        // again when the TYPE is what decides the far end (an interface collapsing into its
        // implementer, a struct that is no relation at all).
        .map(|variable| {
            // A recorded answer outranks the declared type here as well: `treasury` is declared
            // `Treasury` and holds a `StakingFeeTreasury` in this deployment.
            let held = wiring
                .get(&format!("{}.{}", contract.name, variable.name))
                .map(String::as_str)
                .unwrap_or(variable.type_name.trim());
            format!("{}{VARIABLE_MARK}{held}", variable.name)
        })
        .collect()
}

/// What a type name stands for on the map.
#[derive(Debug, Clone, PartialEq, Eq)]
enum TypeTarget {
    /// A deployable contract in scope — the box an arrow can land on.
    Contract(String),
    /// An interface with several deployable implementers and no resolution: a relation whose
    /// far end is a question for the auditor, never a guess.
    Open(String),
    /// Code that is not in this repository: an interface nothing in scope implements, or an
    /// instance of somebody else's contract (`ERC20 mirror`) held by address.
    Outside(String),
    /// A struct, an enum, a type alias, a mapping, or nothing at all — not a relation.
    NotAContract,
}

/// What a type NAME means at runtime. An interface is not a thing on the board: it is the
/// shape of a call, and the contract at the other end is what the reader is looking for.
/// `IAscendLaunchpad` and `AscendLaunchpad` were two boxes for one contract, which made the
/// system look bigger than it is and left the reader deciding which of the two to believe.
///
/// Collapsed when the answer is a FACT: a resolution the auditor recorded, or exactly one
/// DEPLOYABLE contract in scope declaring the interface as a base. Only deployable ones
/// count, because `IListingLaunchpad is IAscendLaunchpad` also "declares it as a base" and an
/// interface extending an interface was enough to make the count two and block the collapse.
/// Several deployable implementers and no resolution stays open — that is a question, and the
/// map says so.
///
/// An interface is IN SCOPE — the scan stores it like any other contract — and that is why
/// "is it in scope" cannot be the question here: answering yes for `IAscendLaunchpad` is how
/// the map drew the interface beside the contract that implements it. And a VENDORED contract
/// used as a type is not collapsible either: `ERC20 mirror` is an instance of somebody else's
/// token at another address, and the fact that `AscendCoreToken is ERC20` says nothing about
/// which token `mirror` is. Folding it into its in-scope child made a real boundary vanish as
/// a self-call.
fn classify_type(metadata: &EvmBatMetadata, scope: Option<&str>, type_name: &str) -> TypeTarget {
    use crate::batbelt::evm::types::EvmContractType;

    let Some(name) = contract_type_name(type_name) else {
        return TypeTarget::NotAContract;
    };
    let copies: Vec<&ContractMetadata> =
        metadata.contracts.iter().filter(|c| c.name == name).collect();
    if copies.is_empty() {
        return TypeTarget::NotAContract;
    }
    // Reading the kind off ANY copy is enough: three vendored `IERC20`s are all interfaces.
    // What matters is whether some copy is in scope and what kind of thing the name is.
    let is_interface = copies
        .iter()
        .any(|c| c.contract_type == EvmContractType::Interface);
    let in_scope = copies.iter().find(|c| !c.vendored);
    let deployable_in_scope = in_scope
        .is_some_and(|c| c.contract_type == EvmContractType::Contract);

    if deployable_in_scope {
        return TypeTarget::Contract(name.to_string());
    }
    if let Some(recorded) = metadata.resolution_for(scope, name) {
        if metadata.contracts.iter().any(|c| !c.vendored && c.name == *recorded) {
            return TypeTarget::Contract(recorded.clone());
        }
    }
    // Collapsible: an interface (wherever it lives) or an abstract contract of this project.
    // A vendored abstract or concrete contract is neither — it is an address of their code.
    let collapsible = is_interface
        || in_scope.is_some_and(|c| c.contract_type == EvmContractType::Abstract);
    if !collapsible {
        return TypeTarget::Outside(name.to_string());
    }
    let mut implementers = metadata
        .contracts
        .iter()
        .filter(|c| !c.vendored && c.contract_type == EvmContractType::Contract)
        .filter(|c| c.base_contracts.iter().any(|base| base == name));
    match (implementers.next(), implementers.next()) {
        (Some(only), None) => TypeTarget::Contract(only.name.clone()),
        (Some(_), Some(_)) => TypeTarget::Open(name.to_string()),
        (None, _) if is_interface => TypeTarget::Outside(name.to_string()),
        // An abstract contract of this project that nothing deployable derives from: there is
        // no box for it and no outside either, so it is a question.
        (None, _) => TypeTarget::Open(name.to_string()),
    }
}

/// The contract name a declared type can stand for, or `None` when the type cannot name a
/// contract at all: a mapping, an elementary type, or nothing.
///
/// `CurveStep[]` is an array of whatever `CurveStep` is, so the brackets are stripped; a
/// `mapping(Id => PendingUint192)` is storage, not an address, and is never a relation.
fn contract_type_name(type_name: &str) -> Option<&str> {
    let mut name = type_name.trim();
    if name.is_empty() || name.starts_with("mapping(") {
        return None;
    }
    while let Some(open) = name.rfind('[') {
        if !name.ends_with(']') {
            break;
        }
        name = name[..open].trim_end();
    }
    // `uint256`, `address`, `bytes32`: a contract name starts with a capital.
    name.chars()
        .next()
        .filter(|first| first.is_ascii_uppercase())
        .map(|_| name)
}

/// Calls whose receiver the scan could not type as a contract — an empty type, a struct
/// field it could not follow — one line each, so the report can say what the map leaves out.
pub fn untyped_receivers(metadata: &EvmBatMetadata) -> Vec<String> {
    let mut lines: BTreeSet<String> = BTreeSet::new();
    for contract in metadata.contracts.iter().filter(|c| !c.vendored) {
        for function in &contract.functions {
            let calls = function
                .unresolved_calls
                .iter()
                .map(|call| (&call.receiver, &call.method, &call.inferred_type))
                .chain(
                    function
                        .unknown_external_calls
                        .iter()
                        .map(|call| (&call.receiver, &call.method, &call.inferred_type)),
                );
            for (receiver, method, inferred_type) in calls {
                // A call on a value type or a library runs HERE: `PoolId.unwrap(id)` is a cast
                // the compiler erases and `LaunchpadKey.keyOf(...)` is this contract's own code
                // by another name. Neither crosses anything, so neither is a receiver the scan
                // failed to type — listing them asked the reader to resolve a non-question.
                if runs_locally(metadata, receiver) {
                    continue;
                }
                // A native-value call IS drawn now, in its own boundary box with the receiver
                // as its party — reporting it as something the map left out is a lie.
                if (method.ends_with("{value}")
                    || matches!(method.as_str(), "call" | "delegatecall"))
                    && receiver != "assembly"
                {
                    continue;
                }
                // A call on a STRUCT or a mapping entry cannot leave this contract: it is a
                // library attached with `using … for`, running here. `pendingCap[].update` is
                // not a receiver the scan failed to type — it is not a receiver at all.
                if holds_no_code(metadata, inferred_type) {
                    continue;
                }
                if classify_type(metadata, Some(contract.name.as_str()), inferred_type) == TypeTarget::NotAContract {
                    let shown = if inferred_type.is_empty() {
                        "untyped".to_string()
                    } else {
                        inferred_type.clone()
                    };
                    lines.insert(format!(
                        "{}.{}: {receiver}.{method} ({shown})",
                        contract.name, function.name
                    ));
                }
            }
        }
    }
    lines.into_iter().collect()
}

/// Is `name` a struct this type declares — so `Type.name(…)` is building one, not calling?
fn declares_struct(metadata: &EvmBatMetadata, type_name: &str, name: &str) -> bool {
    use crate::batbelt::evm::types::EvmFileItemKind;
    metadata.file_items.iter().any(|item| {
        item.kind == EvmFileItemKind::Struct
            && item.name == name
            && item.owner == type_name
    })
}

/// Is this type a value rather than an address: a struct, an enum, a mapping, a value type?
///
/// A call on one of those is a library attached with `using … for`, which runs in the calling
/// contract. There is nothing to type and nothing to resolve.
fn holds_no_code(metadata: &EvmBatMetadata, type_name: &str) -> bool {
    use crate::batbelt::evm::types::EvmFileItemKind;
    let clean = type_name.trim().trim_end_matches("[]");
    if clean.is_empty() {
        return false;
    }
    if clean.starts_with("mapping(") {
        return true;
    }
    metadata.file_items.iter().any(|item| {
        item.name == clean
            && matches!(
                item.kind,
                EvmFileItemKind::Struct | EvmFileItemKind::Enum | EvmFileItemKind::TypeAlias
            )
    })
}

/// Does a call on this receiver run in the calling contract?
///
/// Two shapes, one answer. A user-defined value type (`type PoolId is bytes32`) only ever
/// carries `wrap`/`unwrap` and whatever `using … for` attaches, and all of it is erased at
/// compile time. A LIBRARY's code runs as the contract that calls it — which the map already
/// knows, since it folds libraries into their callers rather than drawing them.
fn runs_locally(metadata: &EvmBatMetadata, receiver: &str) -> bool {
    use crate::batbelt::evm::types::{EvmContractType, EvmFileItemKind};
    let name = receiver.trim();
    metadata
        .file_items
        .iter()
        .any(|item| item.name == name && item.kind == EvmFileItemKind::TypeAlias)
        || metadata
            .contracts
            .iter()
            .any(|c| c.name == name && c.contract_type == EvmContractType::Library)
}

/// Interfaces of this repository that some in-scope contract calls or holds, and that no
/// deployable contract declares as a base and no resolution binds.
///
/// Each one is classified as the outside, and for most of them that is the truth — an
/// interface file in `src/interfaces/` describing a protocol deployed elsewhere. But a contract
/// may implement an interface without `is IFace`, and then the map has just drawn a call into
/// this project's own code as a call out of it. Listing them is the difference between a
/// wrong map and a map with a question on it.
pub fn undeclared_interfaces(metadata: &EvmBatMetadata) -> Vec<String> {
    use crate::batbelt::evm::types::EvmContractType;
    let own_interfaces: BTreeSet<&str> = metadata
        .contracts
        .iter()
        .filter(|c| !c.vendored && c.contract_type == EvmContractType::Interface)
        .map(|c| c.name.as_str())
        .collect();
    let mut found: BTreeSet<String> = BTreeSet::new();
    for contract in metadata.contracts.iter().filter(|c| !c.vendored) {
        let referenced = contract
            .functions
            .iter()
            .flat_map(|function| {
                function
                    .unresolved_calls
                    .iter()
                    .map(|call| call.inferred_type.clone())
                    .chain(
                        function
                            .unknown_external_calls
                            .iter()
                            .map(|call| call.inferred_type.clone()),
                    )
            })
            .chain(wired_at_construction(contract, &metadata.wiring));
        for type_name in referenced {
            if let TypeTarget::Outside(name) =
                classify_type(metadata, Some(contract.name.as_str()), &type_name)
            {
                if own_interfaces.contains(name.as_str()) {
                    found.insert(name);
                }
            }
        }
    }
    found.into_iter().collect()
}

/// How many contracts a scan without the `vendored` flag left in scope under `lib/`, or
/// `None` when the scan knows what is vendored.
///
/// The flag was added after the first scans shipped, and `serde(default)` reads its absence
/// as "nothing is vendored" — which is also, exactly, what a project with no dependencies
/// looks like. The two are told apart by the paths: a contract under a `lib/` segment with
/// `vendored == false` can only come from a scan that never set the flag.
pub fn predates_vendored(metadata: &EvmBatMetadata) -> Option<usize> {
    if metadata.contracts.iter().any(|contract| contract.vendored) {
        return None;
    }
    let under_lib = metadata
        .contracts
        .iter()
        .filter(|contract| {
            contract
                .file_path
                .split('/')
                .any(|segment| segment == "lib")
        })
        .count();
    (under_lib > 0).then_some(under_lib)
}

/// The relations as lines, grouped by the contract they leave from.
pub fn report(edges: &[Edge]) -> Vec<String> {
    let mut lines = vec![
        format!(
            "{} relation(s) between contracts — one per pair, whatever the number of calls",
            edges.len()
        ),
        String::new(),
    ];
    let mut current = String::new();
    for edge in edges {
        if edge.from != current {
            current = edge.from.clone();
            lines.push(current.clone());
        }
        // The terminal shows the id, minus the bookkeeping: `=>feeSink~` is an address, and
        // the tilde is how the drawing knows, not something to read.
        let to = edge.to.replace(ADDRESS_MARK, "");
        lines.push(format!("  → {:<28} {}", to, edge.relation.label()));
    }

    // Who the system turns around: the contracts most things point at.
    let mut incoming: BTreeMap<&str, usize> = BTreeMap::new();
    for edge in edges {
        *incoming.entry(edge.to.as_str()).or_default() += 1;
    }
    let mut ranked: Vec<(&str, usize)> = incoming.into_iter().collect();
    ranked.sort_by(|a, b| b.1.cmp(&a.1).then(a.0.cmp(b.0)));
    lines.push(String::new());
    lines.push("reached by the most contracts:".to_string());
    for (name, count) in ranked.iter().take(5) {
        lines.push(format!("  {name:<28} {count} contract(s) talk to it"));
    }
    lines
}

#[cfg(test)]
mod map_test {
    use super::{drawn_edges, Edge, Relation};

    /// A pair that both calls and is wired is ONE edge: the call, which is the stronger fact.
    #[test]
    fn the_stronger_relation_wins_a_pair() {
        assert!(Relation::Calls < Relation::WiresAtConstruction);
        assert!(Relation::WiresAtConstruction < Relation::Unresolved);
    }

    /// Edges sort by their source, which is what makes the report read as one block per
    /// contract.
    #[test]
    fn edges_group_by_their_source() {
        let mut edges = vec![
            Edge { from: "B".into(), to: "C".into(), relation: Relation::Calls },
            Edge { from: "A".into(), to: "C".into(), relation: Relation::Calls },
            Edge { from: "A".into(), to: "B".into(), relation: Relation::Calls },
        ];
        edges.sort();
        assert_eq!(edges[0].from, "A");
        assert_eq!(edges[0].to, "B");
        assert_eq!(edges[2].from, "B");
    }

    use super::{classify_type, predates_vendored, relations, undeclared_interfaces, TypeTarget};
    use crate::batbelt::evm::metadata::bat_metadata::{
        ContractMetadata, EvmBatMetadata, FunctionDependency, FunctionMetadata, UnresolvedCall,
    };
    use crate::batbelt::evm::types::{
        EvmContractType, EvmFileItem, EvmFileItemKind, EvmMutability, EvmVisibility,
        StorageVariable,
    };

    fn contract(
        name: &str,
        kind: EvmContractType,
        bases: &[&str],
        vendored: bool,
    ) -> ContractMetadata {
        ContractMetadata {
            metadata_id: name.to_string(),
            name: name.to_string(),
            using_libraries: Vec::new(),
            file_path: format!("./{}/{name}.sol", if vendored { "lib/dep/src" } else { "src" }),
            contract_type: kind,
            base_contracts: bases.iter().map(|b| b.to_string()).collect(),
            functions: Vec::new(),
            state_variables: Vec::new(),
            structs: Vec::new(),
            events: Vec::new(),
            modifiers: Vec::new(),
            line: 1,
            vendored,
        }
    }

    /// A function making one call on a receiver of the given interface type.
    fn calling(inferred_type: &str) -> FunctionMetadata {
        FunctionMetadata {
            metadata_id: format!("f_{inferred_type}"),
            name: "poke".to_string(),
            contract_name: String::new(),
            visibility: EvmVisibility::External,
            mutability: EvmMutability::NonPayable,
            modifiers: Vec::new(),
            params: Vec::new(),
            returns: Vec::new(),
            line: 1,
            end_line: 2,
            is_constructor: false,
            is_stub: false,
            storage_writes: Vec::new(),
            storage_write_sites: Vec::new(),
            unresolved_calls: vec![UnresolvedCall {
                receiver: "target".to_string(),
                method: "poke".to_string(),
                inferred_type: inferred_type.to_string(),
                candidates: Vec::new(),
                assigned_in: Vec::new(),
            }],
            unknown_external_calls: Vec::new(),
            resolved_calls: Vec::new(),
            callbacks: Vec::new(),
            creations: Vec::new(),
        }
    }

    fn immutable(type_name: &str) -> StorageVariable {
        StorageVariable {
            name: type_name.to_lowercase(),
            type_name: type_name.to_string(),
            visibility: EvmVisibility::Internal,
            is_constant: false,
            is_immutable: true,
            line: 3,
        }
    }

    fn pairs(edges: &[Edge]) -> Vec<(String, String, Relation)> {
        edges
            .iter()
            .map(|edge| (edge.from.clone(), edge.to.clone(), edge.relation))
            .collect()
    }

    /// A pair that is both CREATED and called keeps the creation. One arrow per pair, and the
    /// one kept is the one that says the most: that an address exists because of this line is
    /// the rare fact and the one nothing else on the board shows. `AscendYieldVault` creates
    /// `YieldExitReserve` in `_checkpoint` and calls it, and the map used to draw only the
    /// call, which read as two contracts that happened to find each other.
    #[test]
    fn a_created_and_called_pair_keeps_the_creation() {
        let mut vault = contract("AscendYieldVault", EvmContractType::Contract, &[], false);
        vault.functions.push(calling("YieldExitReserve"));
        let maker = vault.functions[0].metadata_id.clone();
        let metadata = EvmBatMetadata {
            contracts: vec![
                vault,
                contract("YieldExitReserve", EvmContractType::Contract, &[], false),
            ],
            function_dependencies: vec![FunctionDependency {
                function_metadata_id: maker,
                callees: vec!["YieldExitReserve.constructor".to_string()],
            }],
            ..Default::default()
        };
        assert_eq!(
            pairs(&relations(&metadata)),
            vec![(
                "AscendYieldVault".to_string(),
                "YieldExitReserve".to_string(),
                Relation::Creates
            )]
        );
    }

    /// `IListingLaunchpad is IAscendLaunchpad` declares the interface as a base too, and
    /// counting it made two implementers out of one: the collapse was blocked and the
    /// interface was drawn beside the contract that implements it. Only a deployable
    /// contract implements anything.
    #[test]
    fn an_interface_extending_an_interface_does_not_block_the_collapse() {
        let mut caller = contract("AscendCtoReceiver", EvmContractType::Contract, &[], false);
        caller.functions.push(calling("IAscendLaunchpad"));
        let metadata = EvmBatMetadata {
            contracts: vec![
                caller,
                contract("AscendLaunchpad", EvmContractType::Contract, &["IAscendLaunchpad"], false),
                contract("IAscendLaunchpad", EvmContractType::Interface, &[], false),
                contract("IListingLaunchpad", EvmContractType::Interface, &["IAscendLaunchpad"], false),
            ],
            ..Default::default()
        };
        assert_eq!(
            classify_type(&metadata, None, "IAscendLaunchpad"),
            TypeTarget::Contract("AscendLaunchpad".to_string())
        );
        assert_eq!(
            pairs(&relations(&metadata)),
            vec![("AscendCtoReceiver".to_string(), "AscendLaunchpad".to_string(), Relation::Calls)]
        );
    }

    /// Two deployable implementers and no resolution is a question, drawn as one.
    #[test]
    fn two_deployable_implementers_stay_an_open_question() {
        let mut caller = contract("Router", EvmContractType::Contract, &[], false);
        caller.functions.push(calling("IVault"));
        let metadata = EvmBatMetadata {
            contracts: vec![
                caller,
                contract("IVault", EvmContractType::Interface, &[], false),
                contract("VaultA", EvmContractType::Contract, &["IVault"], false),
                contract("VaultB", EvmContractType::Contract, &["IVault"], false),
            ],
            ..Default::default()
        };
        assert_eq!(classify_type(&metadata, None, "IVault"), TypeTarget::Open("IVault".to_string()));
        assert_eq!(
            pairs(&drawn_edges(&relations(&metadata), false)),
            vec![("Router".to_string(), "IVault".to_string(), Relation::Unresolved)]
        );
    }

    /// `Limits limits`, `CurveStep[] steps` and a mapping are state, not relations. They got
    /// onto the map because "starts with a capital letter" was the whole test for a contract.
    #[test]
    fn a_struct_typed_immutable_is_not_a_relation() {
        let mut vault = contract("AscendYieldVault", EvmContractType::Contract, &[], false);
        vault.state_variables.extend([
            immutable("Limits"),
            immutable("CurveStep[]"),
            immutable("mapping(Id => PendingUint192)"),
            immutable("PriceFeed"),
        ]);
        let metadata = EvmBatMetadata {
            contracts: vec![vault, contract("PriceFeed", EvmContractType::Contract, &[], false)],
            file_items: vec![EvmFileItem {
                name: "Limits".to_string(),
                kind: EvmFileItemKind::Struct,
                file_path: "./src/AscendYieldVault.sol".to_string(),
                line: 5,
                end_line: 9,
                vendored: false,
                owner: "AscendYieldVault".to_string(),
            }],
            ..Default::default()
        };
        assert_eq!(classify_type(&metadata, None, "Limits"), TypeTarget::NotAContract);
        assert_eq!(classify_type(&metadata, None, "CurveStep[]"), TypeTarget::NotAContract);
        assert_eq!(classify_type(&metadata, None, "mapping(Id => PendingUint192)"), TypeTarget::NotAContract);
        // With boundaries on, which is where the structs used to leak through as "outside".
        assert_eq!(
            pairs(&relations(&metadata)),
            // The variable comes with it: two feeds of one type are two addresses.
            vec![(
                "AscendYieldVault".to_string(),
                "pricefeed%PriceFeed".to_string(),
                Relation::WiresAtConstruction
            )]
        );
    }

    /// `ERC20 mirror` is an instance of somebody else's token at another address, and
    /// `AscendCoreToken is ERC20` says nothing about which token. The derives-from rule used
    /// to fold it into `AscendCoreToken` itself, where the self-call filter dropped it: a real
    /// boundary, gone without a word. A vendored contract type is the outside, never a box.
    #[test]
    fn a_vendored_contract_type_is_the_outside_not_its_in_scope_child() {
        let mut token = contract("AscendCoreToken", EvmContractType::Contract, &["ERC20"], false);
        token.state_variables.push(immutable("ERC20"));
        let metadata = EvmBatMetadata {
            contracts: vec![token, contract("ERC20", EvmContractType::Abstract, &["IERC20"], true)],
            ..Default::default()
        };
        assert_eq!(classify_type(&metadata, None, "ERC20"), TypeTarget::Outside("ERC20".to_string()));
        assert_eq!(
            pairs(&relations(&metadata)),
            vec![("AscendCoreToken".to_string(), "ERC20".to_string(), Relation::Boundary)]
        );
        // Drawn, as a leaf of its own caller: `ERC20@AscendCoreToken` is that contract's own
        // copy, so no two callers share a box for it.
        let drawn = drawn_edges(&relations(&metadata), false);
        assert_eq!(drawn.len(), 1);
        assert_eq!(drawn[0].to, "ERC20@AscendCoreToken");
        assert_eq!(super::box_text(&drawn[0].to), "ERC20");
        assert!(drawn_edges(&relations(&metadata), true).is_empty(), "--no-boundaries draws none");
    }

    /// An in-scope ABSTRACT contract used as a type still collapses into the one deployable
    /// contract that derives from it — that is this project's code, with an address.
    #[test]
    fn an_in_scope_abstract_type_collapses_into_its_deployable_child() {
        let metadata = EvmBatMetadata {
            contracts: vec![
                contract("BaseVault", EvmContractType::Abstract, &[], false),
                contract("Vault", EvmContractType::Contract, &["BaseVault"], false),
            ],
            ..Default::default()
        };
        assert_eq!(classify_type(&metadata, None, "BaseVault"), TypeTarget::Contract("Vault".to_string()));
    }

    /// An interface of this repository that nothing declares to implement is the outside by
    /// the rule — and may be a contract implementing it without `is`. The map cannot know,
    /// so it names the interface and the command that settles it; a recorded resolution
    /// settles it.
    #[test]
    fn an_own_interface_nothing_declares_is_named_as_a_question() {
        let mut caller = contract("AscendCtoReceiver", EvmContractType::Contract, &[], false);
        caller.functions.push(calling("IListingLaunchpad"));
        let mut metadata = EvmBatMetadata {
            contracts: vec![
                caller,
                contract("ListingDesk", EvmContractType::Contract, &["ReentrancyGuard"], false),
                contract("IListingLaunchpad", EvmContractType::Interface, &[], false),
                // A vendored interface nothing implements is the outside with no question.
                contract("IMirrorFactory", EvmContractType::Interface, &[], true),
            ],
            ..Default::default()
        };
        metadata.contracts[0].functions.push(calling("IMirrorFactory"));
        assert_eq!(undeclared_interfaces(&metadata), vec!["IListingLaunchpad".to_string()]);

        metadata
            .resolutions
            .insert("IListingLaunchpad".to_string(), "ListingDesk".to_string());
        assert!(undeclared_interfaces(&metadata).is_empty());
        assert!(pairs(&drawn_edges(&relations(&metadata), false)).contains(&(
            "AscendCtoReceiver".to_string(),
            "ListingDesk".to_string(),
            Relation::Calls
        )));
    }

    /// A scan from before the flag marks nothing vendored and still has `lib/` in it. That is
    /// a map of forge-std, and the tool refuses rather than draws it.
    #[test]
    fn a_scan_before_the_vendored_flag_is_refused() {
        let mut stale = EvmBatMetadata {
            contracts: vec![
                contract("Vault", EvmContractType::Contract, &[], false),
                contract("Test", EvmContractType::Abstract, &[], false),
            ],
            ..Default::default()
        };
        stale.contracts[1].file_path = "./lib/forge-std/src/Test.sol".to_string();
        assert_eq!(predates_vendored(&stale), Some(1));

        // The same paths with the flag set is a scan that knows.
        let mut current = stale.clone();
        current.contracts[1].vendored = true;
        assert_eq!(predates_vendored(&current), None);

        // And a project with no `lib/` at all legitimately has nothing vendored.
        let bare = EvmBatMetadata {
            contracts: vec![contract("Vault", EvmContractType::Contract, &[], false)],
            ..Default::default()
        };
        assert_eq!(predates_vendored(&bare), None);
    }
}

#[cfg(test)]
mod folding_test {
    use super::{hosts, Relation};
    use crate::batbelt::evm::metadata::bat_metadata::{
        ContractMetadata, EvmBatMetadata, FunctionDependency,
    };
    use crate::batbelt::evm::types::EvmContractType;

    /// The map only ever reads a handful of fields; the rest of a scanned contract is noise
    /// here, and writing it out would hide what each test is actually about.
    fn contract(name: &str, kind: EvmContractType, bases: &[&str]) -> ContractMetadata {
        let mut built: ContractMetadata =
            serde_json::from_str(&format!(
                r#"{{"metadata_id":"{name}","name":"{name}","file_path":"./src/{name}.sol",
                    "contract_type":"{kind:?}","base_contracts":[],"functions":[],
                    "state_variables":[],"events":[],"modifiers":[],"line":1}}"#
            ))
            .expect("fixture parses");
        built.base_contracts = bases.iter().map(|base| base.to_string()).collect();
        built
    }

    fn with_function(mut contract: ContractMetadata, id: &str) -> ContractMetadata {
        let function = serde_json::from_str(&format!(
            r#"{{"metadata_id":"{id}","name":"f","contract_name":"{}","visibility":"Internal",
                "mutability":"NonPayable","modifiers":[],"params":[],"returns":[],"line":1,
                "end_line":2,"is_constructor":false}}"#,
            contract.name
        ))
        .expect("fixture parses");
        contract.functions.push(function);
        contract
    }

    fn metadata(contracts: Vec<ContractMetadata>, deps: Vec<(&str, &str)>) -> EvmBatMetadata {
        let mut built: EvmBatMetadata = serde_json::from_str(
            r#"{"contracts":[],"entry_points":[],"function_dependencies":[],"interfaces":[],
                "file_items":[]}"#,
        )
        .expect("an empty scan");
        built.contracts = contracts;
        built.function_dependencies = deps
            .into_iter()
            .map(|(id, callee)| FunctionDependency {
                function_metadata_id: id.to_string(),
                callees: vec![callee.to_string()],
            })
            .collect();
        built
    }

    /// A library used by one contract is that contract's code, and `hosts` says so.
    #[test]
    fn a_library_is_hosted_by_the_contract_that_uses_it() {
        let built = metadata(
            vec![
                with_function(contract("Vault", EvmContractType::Contract, &[]), "vault_f"),
                contract("MathLib", EvmContractType::Library, &[]),
            ],
            vec![("vault_f", "MathLib.wadMul")],
        );
        let hosted = hosts(&built);
        assert!(hosted["Vault"].contains("MathLib"));
        assert!(!hosted.contains_key("MathLib"), "a library hosts nobody");
    }

    /// A library reached only through another library still reaches the contract at the end:
    /// the fixpoint is what makes `FLAMMStore` → `FLAMMFlowLib` → `FLAMM` work.
    #[test]
    fn hosting_is_transitive() {
        let built = metadata(
            vec![
                with_function(contract("FLAMM", EvmContractType::Contract, &[]), "flamm_f"),
                with_function(contract("FlowLib", EvmContractType::Library, &[]), "flow_f"),
                contract("StoreLib", EvmContractType::Library, &[]),
            ],
            vec![("flamm_f", "FlowLib.run"), ("flow_f", "StoreLib.read")],
        );
        let hosted = hosts(&built);
        assert!(hosted["FLAMM"].contains("FlowLib"));
        assert!(hosted["FLAMM"].contains("StoreLib"), "reached through FlowLib");
    }

    /// An abstract base folds the same way, through inheritance.
    #[test]
    fn an_abstract_base_is_hosted_by_what_inherits_it() {
        let built = metadata(
            vec![
                contract("Router", EvmContractType::Contract, &["Pausable"]),
                contract("Pausable", EvmContractType::Abstract, &[]),
            ],
            vec![],
        );
        assert!(hosts(&built)["Router"].contains("Pausable"));
    }

}

#[cfg(test)]
mod report_test {
    use super::{hierarchy, Edge, Relation};

    fn edge(from: &str, to: &str, relation: Relation) -> Edge {
        Edge { from: from.to_string(), to: to.to_string(), relation }
    }

    /// The hierarchy names both ends and nothing in between: a top caller is what the map
    /// frames, a foundation is what everything else needs in order to exist.
    #[test]
    fn the_hierarchy_names_the_tops_and_the_foundations() {
        let edges = vec![
            edge("Launchpad", "Desk", Relation::Calls),
            edge("Desk", "Treasury", Relation::Calls),
            edge("Router", "Treasury", Relation::Calls),
        ];
        let lines = hierarchy(&edges, false);
        let tops: Vec<&String> = lines
            .iter()
            .take_while(|line| !line.is_empty())
            .filter(|line| line.starts_with("  "))
            .collect();
        assert_eq!(tops.len(), 2, "Launchpad and Router: {tops:?}");
        assert!(tops.iter().all(|line| line.contains("Launchpad") || line.contains("Router")));
        let foundations: Vec<&String> = lines
            .iter()
            .skip_while(|line| !line.is_empty())
            .filter(|line| line.starts_with("  "))
            .collect();
        assert_eq!(foundations.len(), 1, "only Treasury depends on nothing: {foundations:?}");
        assert!(foundations[0].contains("Treasury") && foundations[0].contains('2'));
    }

    /// The hierarchy is about this repository's contracts: what leaves the code is a badge,
    /// never a rung of the hierarchy, whichever way the flag is set.
    #[test]
    fn the_outside_is_never_part_of_the_hierarchy() {
        let edges = vec![
            edge("Vault", "IERC20", Relation::Boundary),
            edge("Vault", "Oracle", Relation::Calls),
        ];
        for no_boundaries in [true, false] {
            assert!(hierarchy(&edges, no_boundaries).iter().all(|line| !line.contains("IERC20")));
        }
        assert!(hierarchy(&edges, false).iter().any(|line| line.contains("Oracle")));
    }
}

#[cfg(test)]
mod visual_test {
    use super::{
        centre_out, legend_rows, order_hub_column, route_arrows, strip_of, style_of, Edge,
        Relation, Sample, CYCLE_COLOUR, EDGE_COLOUR, LEGEND_ROWS, NODE_HEIGHT, STRIP_HEADING,
    };
    use crate::batbelt::evm::miro::auto_deploy::LaneSide;
    use crate::batbelt::miro::client::ConnectorStroke;
    use crate::batbelt::miro::layout::{GraphLayout, PlacedNode};

    fn edge(from: &str, to: &str, relation: Relation) -> Edge {
        Edge { from: from.to_string(), to: to.to_string(), relation }
    }

    fn node(id: &str, layer: usize, x: f64, y: f64) -> PlacedNode {
        PlacedNode { id: id.to_string(), layer, x, y, width: 1_000.0, height: NODE_HEIGHT }
    }

    /// A layout as `layout_graph` would hand it back: columns 1 000 wide at a 2 000 pitch,
    /// every route listed from the CALLEE's column outwards.
    fn layout(nodes: Vec<PlacedNode>, routes: Vec<Vec<(f64, f64)>>) -> GraphLayout {
        GraphLayout {
            nodes,
            routes,
            back_edges: Vec::new(),
            bbox_width: 8_000.0,
            bbox_height: 4_000.0,
            frame_width: 9_200.0,
            frame_height: 5_200.0,
            crossings: 0,
        }
    }

    /// The legs of one arrow as point-to-point segments.
    fn segments(arrow: &super::RoutedArrow) -> Vec<((f64, f64), (f64, f64))> {
        arrow
            .plan
            .legs
            .iter()
            .filter_map(|(from, _, to, _, _)| {
                let at = |side: &LaneSide| match side {
                    LaneSide::Marker(index) => arrow.plan.points.get(*index).copied(),
                    LaneSide::Item(_) => None,
                };
                Some((at(from)?, at(to)?))
            })
            .collect()
    }

    /// The layout bends an edge from the callee's column outwards, and the chain is drawn from
    /// the caller: consumed as listed, an arrow skipping two columns ran its corridor legs at
    /// the wrong columns' heights — through the boxes. The corridor beside the caller comes
    /// first.
    #[test]
    fn corridors_are_walked_from_the_callers_side() {
        let laid = layout(
            // The caller is column 0 — its frame's own contract — and the chain grows right.
            vec![node("Caller", 0, 500.0, 3_000.0), node("Callee", 3, 6_500.0, 1_000.0)],
            // Column 1's corridor at y = 2 400, column 2's at y = 1 700: caller-first order.
            vec![vec![(2_000.0, 2_400.0), (4_000.0, 1_700.0)]],
        );
        let routed = route_arrows(&[edge("Caller", "Callee", Relation::Calls)], &laid, false);
        let arrow = routed.iter().find(|arrow| arrow.edge == Some(0)).expect("the arrow");
        let legs = segments(arrow);
        // Leg 1 leaves the caller; leg 2 runs up the first lane to the FIRST corridor the
        // arrow meets, which is the column beside the caller.
        let first_drop = legs[1];
        assert_eq!(first_drop.0 .1, 3_000.0, "from the caller's row: {legs:?}");
        assert_eq!(first_drop.1 .1, 2_400.0, "to the corridor of the column beside the caller: {legs:?}");
        // Two skipped columns: at most 2s + 2 markers and 2s + 3 legs — fewer when two of them
        // land on the same point, which `tighten` collapses rather than asking Miro to draw a
        // connector from an item to itself.
        assert!(arrow.plan.points.len() <= 6 + 2, "{:?}", arrow.plan.points);
        assert!(arrow.plan.legs.len() <= 7);
        assert!(arrow.plan.legs.last().expect("a leg").4, "the last leg still carries the head");
    }

    /// Five arrows into one contract used to meet its border at one point. They land spread
    /// along the side, in the order they arrive from, so none crosses another at the box.
    #[test]
    fn arrows_meeting_one_box_are_spread_along_its_side() {
        let laid = layout(
            vec![
                node("Top", 0, 500.0, 500.0),
                node("Mid", 0, 500.0, 2_000.0),
                node("Low", 0, 500.0, 3_500.0),
                node("Hub", 1, 2_500.0, 2_000.0),
            ],
            vec![Vec::new(), Vec::new(), Vec::new()],
        );
        let edges = [
            edge("Low", "Hub", Relation::Calls),
            edge("Top", "Hub", Relation::Calls),
            edge("Mid", "Hub", Relation::Calls),
        ];
        let routed = route_arrows(&edges, &laid, false);
        let landing = |index: usize| {
            let arrow = routed.iter().find(|arrow| arrow.edge == Some(index)).expect("drawn");
            segments(arrow).last().expect("the head leg").1 .1
        };
        let (low, top, mid) = (landing(0), landing(1), landing(2));
        assert!(top < mid && mid < low, "landings follow where the arrows come from: {top} {mid} {low}");
        assert!((low - top) <= NODE_HEIGHT - 2.0 * super::ANCHOR_INSET, "and stay on the box's side");
        assert_eq!(mid, 2_000.0, "the middle one lands on the middle");
    }

    /// The first column is ordered by how many contracts point at each box, from the middle
    /// outwards: the hub in the middle, where its arrows split above and below it.
    #[test]
    fn the_hub_column_puts_the_most_called_in_the_middle() {
        let mut laid = layout(
            vec![
                node("A", 0, 500.0, 500.0),
                node("B", 0, 500.0, 1_000.0),
                node("Hub", 0, 500.0, 1_500.0),
                node("D", 0, 500.0, 2_000.0),
                node("E", 0, 500.0, 2_500.0),
                node("Caller", 1, 2_500.0, 500.0),
            ],
            Vec::new(),
        );
        let edges = [
            edge("Caller", "A", Relation::Calls),
            edge("Caller", "E", Relation::Calls),
            edge("Caller", "E", Relation::Creates),
            edge("Caller", "Hub", Relation::Calls),
        ];
        // E is reached by two relations, Hub by one, A by one, B and D by none.
        order_hub_column(&mut laid, &edges);
        let y = |id: &str| laid.nodes.iter().find(|node| node.id == id).expect(id).y;
        assert_eq!(y("E"), 1_500.0, "the most called takes the middle slot");
        assert_eq!(y("Caller"), 500.0, "other columns are untouched");
        let mut ys: Vec<f64> = ["A", "B", "Hub", "D", "E"].iter().map(|id| y(id)).collect();
        ys.sort_by(|a, b| a.partial_cmp(b).unwrap());
        assert_eq!(ys, vec![500.0, 1_000.0, 1_500.0, 2_000.0, 2_500.0], "the same slots, reassigned");
    }

    #[test]
    fn centre_out_fills_the_middle_then_alternates() {
        let order: Vec<usize> = (0..5).map(|rank| centre_out(rank, 5)).collect();
        assert_eq!(order, vec![2, 3, 1, 4, 0]);
        let order: Vec<usize> = (0..4).map(|rank| centre_out(rank, 4)).collect();
        assert_eq!(order, vec![1, 2, 0, 3]);
    }

    /// One colour for the relations a reader walks, three strokes to tell them apart, and the
    /// two colours that mean something: red for an arrow that runs backwards, green for one
    /// that DEPLOYED the contract at its head. Neither carries a word any more.
    #[test]
    fn one_colour_three_strokes_and_a_colour_where_it_means_something() {
        for relation in [Relation::Calls, Relation::WiresAtConstruction, Relation::Unresolved] {
            assert_eq!(style_of(relation, false).stroke_color, EDGE_COLOUR);
        }
        assert_eq!(style_of(Relation::Creates, false).stroke_color, super::CREATES_COLOUR);
        assert_eq!(style_of(Relation::Creates, false).caption, None, "the colour replaced the word");
        assert_eq!(style_of(Relation::Calls, false).stroke, ConnectorStroke::Solid);
        assert_eq!(style_of(Relation::Unresolved, false).stroke, ConnectorStroke::Dashed);
        assert_eq!(style_of(Relation::Unresolved, false).caption.as_deref(), Some("?"));
        assert_eq!(style_of(Relation::WiresAtConstruction, false).stroke, ConnectorStroke::Dotted);
        assert_eq!(style_of(Relation::Calls, true).stroke_color, CYCLE_COLOUR);
    }

    /// A cycle — the layout had to reverse it — is drawn red, by us and not by Miro, and the
    /// short way round: out of the caller's left, one row down, across, up and in. It used to
    /// be dropped without a word, then drawn through the boxes, then sent on a lap of the whole
    /// frame to reach a contract two rows above.
    #[test]
    fn a_backwards_arrow_is_drawn_red_box_to_box() {
        let laid = layout(
            vec![node("Left", 0, 500.0, 1_000.0), node("Right", 1, 2_500.0, 1_000.0)],
            vec![Vec::new(), Vec::new()],
        );
        let edges = [
            // Left → Right is the flow; Right → Left runs back against it and is the cycle.
            edge("Left", "Right", Relation::Calls),
            edge("Right", "Left", Relation::Calls),
        ];
        let routed = route_arrows(&edges, &laid, false);
        let back = routed.iter().find(|arrow| arrow.edge == Some(1)).expect("the cycle is drawn");
        assert_eq!(back.style.stroke_color, CYCLE_COLOUR);
        let legs = segments(back);
        // Down out of the caller, left under every box, up into the callee: three legs, the
        // head on the last. Routed by us and not by Miro, which drew it through the middle of
        // the frame and across every other arrow.
        assert_eq!(legs.len(), 5);
        let row_bottom = 1_000.0 + NODE_HEIGHT / 2.0;
        assert_eq!(legs[0].0, (2_000.0, 1_000.0), "out of Right's LEFT side, towards the callee");
        assert!(legs[0].1 .0 < 2_000.0, "into the lane beside it: {legs:?}");
        assert!(legs[1].1 .1 > row_bottom, "down just past its own row, not past the frame");
        assert_eq!(legs[2].0 .1, legs[2].1 .1, "along the corridor");
        assert!(legs[3].1 .0 < 0.0, "up outside the callee's column");
        assert_eq!(legs[4].1, (0.0, 1_000.0), "and into Left's left side");
        assert!(back.plan.legs[..4].iter().all(|leg| !leg.4), "no head before the end");
        assert!(back.plan.legs[4].4, "the last leg carries the head");
    }

    /// The legend is drawn by the same code as the map: its samples are arrows, so they are
    /// counted and previewed with the rest, and the layout reserves exactly its rows.
    #[test]
    fn the_legend_is_rows_of_real_samples() {
        let rows = legend_rows();
        assert_eq!(rows.len(), LEGEND_ROWS);
        let legs = rows.iter().filter(|row| matches!(row.sample, Sample::Leg(_))).count();
        let laid = layout(vec![node("A", 0, 500.0, 1_000.0), node("B", 1, 2_500.0, 1_000.0)], vec![Vec::new()]);
        let routed = route_arrows(&[edge("B", "A", Relation::Calls)], &laid, true);
        assert_eq!(routed.iter().filter(|arrow| arrow.edge.is_none()).count(), legs);
        assert!(rows.iter().any(|row| matches!(row.sample, Sample::Leg(ref style) if style.stroke_color == CYCLE_COLOUR)));
    }

    /// The strip stacks under the legend's rows, heading first — present on the picture, and
    /// apart from the diagrams.
    #[test]
    fn the_strip_stacks_under_the_legend() {
        let strip = strip_of(&["Alone".to_string(), "Proxy".to_string()], 4_000.0);
        assert_eq!(strip.len(), 3);
        assert_eq!(strip[0].id, STRIP_HEADING);
        assert_eq!(strip[0].y, 4_000.0);
        assert!(strip[1].y > strip[0].y && strip[2].y > strip[1].y);
        assert!(strip_of(&[], 4_000.0).is_empty());
    }
}

#[cfg(test)]
mod framing_test {
    use super::{original_of, partition_frames, unfold, BTreeMap, Edge, Relation};

    fn edge(from: &str, to: &str) -> Edge {
        Edge { from: from.to_string(), to: to.to_string(), relation: Relation::Calls }
    }

    /// One frame per top caller, each holding everything that caller reaches. A contract two
    /// of them use is in both — repeated on purpose, the way a screenshot is repeated in two
    /// deployment frames, because a copy is cheap and a crossing arrow is not.
    #[test]
    fn a_frame_per_top_caller_repeats_what_they_share() {
        let edges = vec![edge("Launchpad", "Treasury"), edge("Router", "Treasury")];
        let frames = partition_frames(&edges);
        assert_eq!(frames.len(), 2);
        assert!(frames.iter().any(|plan| plan.root == "Launchpad"));
        assert!(frames.iter().any(|plan| plan.root == "Router"));
        assert!(
            frames.iter().all(|plan| plan.edges.len() == 1 && plan.edges[0].to == "Treasury"),
            "Treasury is drawn in both frames"
        );
    }

    /// A frame holds the whole chain under its top, not only what it calls directly.
    #[test]
    fn a_frame_holds_everything_its_top_reaches() {
        let edges = vec![edge("Launchpad", "Desk"), edge("Desk", "Treasury")];
        let frames = partition_frames(&edges);
        assert_eq!(frames.len(), 1);
        assert_eq!(frames[0].root, "Launchpad");
        assert_eq!(frames[0].edges.len(), 2);
    }

    /// A cycle nothing points into has no top caller, and is still every bit as much a part of
    /// the system — it gets a frame rather than being dropped.
    #[test]
    fn a_cycle_with_nothing_above_it_still_gets_a_frame() {
        let edges = vec![edge("A", "B"), edge("B", "A")];
        let frames = partition_frames(&edges);
        assert_eq!(frames.len(), 1, "one frame, not none: {frames:?}");
        assert_eq!(frames[0].edges.len(), 2, "both relations drawn");
    }

    /// The tree the frame draws has no crossings — which is the certificate, printed per frame,
    /// and not something anyone has to judge from a picture.
    #[test]
    fn the_tree_a_frame_draws_has_no_crossings() {
        let edges = vec![
            edge("Top", "Middle"),
            edge("Top", "Shared"),
            edge("Middle", "Shared"),
            edge("Top", "Other"),
            edge("Other", "Shared"),
        ];
        assert_eq!(super::layout_map(&unfold("Top", &edges)).crossings, 0);
    }

    /// A frame is self-contained: everything its contract reaches is IN it, and a contract two
    /// branches both reach is drawn twice rather than lifted into a frame of its own. Fewer
    /// frames, each answering one question, beats fewer boxes.
    #[test]
    fn a_frame_holds_its_whole_tree_and_repeats_what_is_shared() {
        let edges = vec![
            edge("Registry", "Receiver"),
            edge("Receiver", "Desk"),
            edge("Registry", "Desk"),
            edge("Desk", "Treasury"),
        ];
        let frames = partition_frames(&edges);
        assert_eq!(frames.len(), 1, "one top caller, one frame: {frames:?}");
        let mine = &frames[0].edges;
        // Desk is reached two ways, so it is drawn twice — and `Treasury` under each of them.
        let desks: Vec<&str> = mine
            .iter()
            .map(|edge| edge.to.as_str())
            .filter(|to| original_of(to) == "Desk")
            .collect();
        assert_eq!(desks.len(), 2, "Desk is drawn once per branch that reaches it: {mine:?}");
        assert_ne!(desks[0], desks[1], "and the two are different boxes");
        assert_eq!(
            mine.iter().filter(|edge| original_of(&edge.to) == "Treasury").count(),
            2,
            "its own chain comes with each copy"
        );
    }

    /// Nothing is shared inside a frame, which is what makes it a tree: every box has exactly
    /// one arrow into it.
    #[test]
    fn a_frame_is_a_tree() {
        let edges = vec![
            edge("Top", "Middle"),
            edge("Top", "Shared"),
            edge("Middle", "Shared"),
            edge("Shared", "Leaf"),
        ];
        let mine = unfold("Top", &edges);
        let mut into: BTreeMap<&str, usize> = BTreeMap::new();
        for edge in &mine {
            *into.entry(edge.to.as_str()).or_default() += 1;
        }
        assert!(into.values().all(|count| *count == 1), "one arrow into each box: {into:?}");
    }

    /// A cycle has no top caller, so one of its members has to be the frame's root — and it is
    /// the one that CALLS THE MOST, not whichever the relations happen to list first.
    #[test]
    fn the_root_of_a_cycle_is_the_member_that_calls_the_most() {
        let edges = vec![
            // `Quiet` comes first alphabetically and calls one; `Busy` calls three. The frame
            // belongs to `Busy`, whose story is the longer one.
            edge("Quiet", "Busy"),
            edge("Busy", "Quiet"),
            edge("Busy", "LeafOne"),
            edge("Busy", "LeafTwo"),
        ];
        let frames = partition_frames(&edges);
        assert_eq!(frames.len(), 1, "one cycle, one frame: {frames:?}");
        assert_eq!(frames[0].root, "Busy");
        assert_eq!(frames[0].edges.len(), 4, "and it draws every relation of the cycle");
    }

    /// A cycle is NOT unfolded for ever: the arrow goes back to the copy this path came
    /// through, which is the one red arrow on the frame.
    #[test]
    fn a_cycle_points_back_instead_of_unfolding() {
        let edges = vec![edge("A", "B"), edge("B", "C"), edge("C", "A")];
        let mine = unfold("A", &edges);
        assert_eq!(mine.len(), 3, "three relations, drawn once each: {mine:?}");
        let back = mine.iter().find(|edge| edge.to == "A").expect("the arrow home");
        assert_eq!(back.from, "C");
    }

    /// What leaves the repository is drawn — and every caller gets its OWN copy of it. One
    /// shared `IERC20` pulled an arrow from each of its seven callers across the whole frame;
    /// an outside box has no chain under it, so a copy costs one box and saves a crossing.
    #[test]
    fn every_caller_gets_its_own_copy_of_what_is_outside() {
        let all = vec![
            Edge { from: "Vault".into(), to: "IERC20".into(), relation: Relation::Boundary },
            Edge { from: "Router".into(), to: "IERC20".into(), relation: Relation::Boundary },
            edge("Vault", "Oracle"),
        ];
        let drawn = super::drawn_edges(&all, false);
        let outside: Vec<&str> = drawn
            .iter()
            .filter(|edge| edge.relation == Relation::Boundary)
            .map(|edge| edge.to.as_str())
            .collect();
        assert_eq!(outside, vec!["IERC20@Vault", "IERC20@Router"], "never one shared box");
        for id in outside {
            assert_eq!(original_of(id), "IERC20", "and both read as IERC20");
            assert!(super::is_outside(id));
        }
        assert!(
            super::drawn_edges(&all, true).iter().all(|edge| edge.to == "Oracle"),
            "--no-boundaries leaves them out altogether"
        );
    }

    /// Within a frame, every copy of one interface carries ONE colour and no two interfaces
    /// carry the same: the copies are what keep the arrows short, the colour is what says the
    /// four boxes reading `IERC20` are one thing.
    #[test]
    fn one_colour_per_interface_and_never_two_the_same() {
        let all = vec![
            Edge { from: "Vault".into(), to: "IERC20".into(), relation: Relation::Boundary },
            Edge { from: "Router".into(), to: "IERC20".into(), relation: Relation::Boundary },
            Edge { from: "Vault".into(), to: "IVault".into(), relation: Relation::Boundary },
            edge("Vault", "Oracle"),
        ];
        let drawn = super::drawn_edges(&all, false);
        let fills = super::PreparedFrame::outside_fills(&drawn);
        assert_eq!(fills.len(), 2, "one entry per interface, not per copy: {fills:?}");
        assert_ne!(fills["IERC20"], fills["IVault"], "two interfaces never share a colour");
        // Both copies of IERC20 resolve to the same fill, whichever caller they belong to.
        assert_eq!(fills[original_of("IERC20@Vault")], fills[original_of("IERC20@Router")]);
    }

    /// A frame is laid out as a TREE: a parent sits at the middle of its children and one column
    /// to their left, so a box is always beside the boxes it points at. Packed from the top
    /// instead, a contract's callees sat level with somebody else's and following one arrow
    /// meant scrolling a frame whose answer was two boxes apart.
    #[test]
    fn a_parent_sits_beside_its_own_children() {
        let edges = vec![
            edge("Root", "First"),
            edge("Root", "Second"),
            edge("Second", "Deep"),
            edge("Second", "Deeper"),
        ];
        let layout = super::layout_tree("Root", &edges);
        let at = |id: &str| layout.node(id).cloned().expect(id);
        assert_eq!(at("Root").layer, 0);
        assert_eq!(at("Second").layer, 1);
        assert_eq!(at("Deep").layer, 2, "a column per depth");
        assert!(at("Root").x < at("Second").x && at("Second").x < at("Deep").x, "left to right");
        // Each parent at the middle of its own children, which is what puts it beside them.
        let middle = |a: f64, b: f64| (a + b) / 2.0;
        assert!((at("Second").y - middle(at("Deep").y, at("Deeper").y)).abs() < 1.0);
        assert!((at("Root").y - middle(at("First").y, at("Second").y)).abs() < 1.0);
        assert_eq!(layout.crossings, 0, "a tidy tree cannot cross");
    }

    /// The frame of a CYCLE still draws its boxes: its root is the one the caller names, not
    /// "whatever has no parent" — in a cycle the root is itself somebody's callee, so that rule
    /// found no root and the frame reached the board titled and empty.
    #[test]
    fn the_frame_of_a_cycle_is_not_empty() {
        let edges = vec![
            edge("Converter", "Treasury"),
            edge("Treasury", "Converter"),
            edge("Converter", "Oracle"),
        ];
        let mine = unfold("Converter", &edges);
        let layout = super::layout_tree("Converter", &mine);
        assert_eq!(layout.nodes.len(), 3, "every box is placed: {:?}", layout.nodes);
        assert_eq!(layout.node("Converter").expect("the root").layer, 0);
        assert!(layout.frame_width > 0.0 && layout.frame_height > 0.0);
    }

    /// A contract drawn twice in one frame carries its own border colour on both copies, so the
    /// two boxes read as one address; a contract drawn once keeps the plain border, because a
    /// colour that means nothing is a colour to decode.
    #[test]
    fn a_contract_drawn_twice_gets_a_border_of_its_own() {
        let edges = vec![
            edge("Registry", "Receiver"),
            edge("Registry", "Desk"),
            edge("Receiver", "Desk"),
        ];
        let mine = unfold("Registry", &edges);
        let borders = super::PreparedFrame::repeat_borders(&mine);
        assert_eq!(borders.len(), 1, "only Desk is drawn twice: {borders:?}");
        let desk = borders["Desk"];
        assert_ne!(desk, super::BOX_BORDER);
        // Both copies carry it, and `Receiver`, drawn once, does not.
        let frame = super::PreparedFrame {
            title: String::new(),
            root: String::new(),
            edges: mine.clone(),
            layout: super::layout_map(&mine),
            arrows: Vec::new(),
            fills: BTreeMap::new(),
            borders,
            strip: Vec::new(),
            width: 0.0,
            height: 0.0,
            crossings: 0,
            left: 0.0,
            top: 0.0,
        };
        assert_eq!(frame.border_of("Desk"), (desk, super::REPEAT_BORDER_WIDTH));
        assert_eq!(frame.border_of("Desk#2"), (desk, super::REPEAT_BORDER_WIDTH));
        assert_eq!(frame.border_of("Receiver"), (super::BOX_BORDER, super::BORDER_WIDTH));
        assert!(
            super::REPEAT_BORDER_WIDTH > super::BORDER_WIDTH,
            "a colour nobody can see at the frame's zoom is not a signal"
        );
    }

    /// A copy is a second box for the same contract, and reads as that contract.
    #[test]
    fn a_copy_carries_its_originals_name() {
        assert_eq!(original_of("Treasury#2"), "Treasury");
        assert_eq!(original_of("Treasury"), "Treasury");
        assert_eq!(super::box_text("Treasury#3"), "Treasury");
    }
}

#[cfg(test)]
mod failure_message_test {
    use crate::batbelt::miro::MiroError;
    use error_stack::Report;

    /// A failed item says WHY: the HTTP status and Miro's own words, which the client already
    /// attaches. Printing the context alone printed "Miro error" and nothing a reader can act on.
    #[test]
    fn a_failure_carries_the_api_s_own_words() {
        let report = Report::new(MiroError)
            .attach_printable("create_connector: HTTP 400 Bad Request: {\"message\":\"too close\"}".to_string());
        let line = super::why(&report);
        assert!(line.contains("400"), "{line}");
        assert!(line.contains("too close"), "{line}");
    }

    /// Nothing attached, nothing invented: the context is still better than an empty line.
    #[test]
    fn a_bare_failure_still_says_something() {
        assert_eq!(super::why(&Report::new(MiroError)), MiroError.to_string());
    }
}

#[cfg(test)]
mod marker_test {
    use super::{layout_tree, route_arrows, Edge, Relation};

    /// No two markers of one arrow land on the same point.
    ///
    /// Miro refuses a connector whose two ends are the same item — `"The startitem id and
    /// enditem id cannot be the same"` — and two markers at identical coordinates come back
    /// from the bulk endpoint as one item, so an arrow that plans a zero-length leg is an arrow
    /// that cannot be drawn. It cost four relations on a real board.
    #[test]
    fn no_leg_of_an_arrow_is_zero_length() {
        let edges = vec![Edge {
            from: "AscendFeeController".into(),
            to: "ICLPoolManager@AscendFeeController".into(),
            relation: Relation::Boundary,
        }];
        let layout = layout_tree("AscendFeeController", &edges);
        for arrow in route_arrows(&edges, &layout, false) {
            for (index, point) in arrow.plan.points.iter().enumerate() {
                for other in arrow.plan.points.iter().skip(index + 1) {
                    assert!(
                        (point.0 - other.0).abs() > 0.5 || (point.1 - other.1).abs() > 0.5,
                        "two markers on {point:?}: {:?}",
                        arrow.plan.points
                    );
                }
            }
        }
    }
}

#[cfg(test)]
mod card_test {
    use super::{CARD_GAP, CARD_WIDTH, MAX_CARDS};
    use crate::batbelt::miro::client::MiroClient;

    /// The cards of one cluster are centred on its shape and evenly spread, so three of them
    /// read as one row belonging to one column rather than as three loose chips.
    fn placed(count: usize, centre: f64) -> Vec<f64> {
        let drawn = count.min(MAX_CARDS);
        let span = drawn as f64 * CARD_WIDTH + (drawn as f64 - 1.0) * CARD_GAP;
        (0..drawn)
            .map(|index| centre - span / 2.0 + CARD_WIDTH / 2.0 + index as f64 * (CARD_WIDTH + CARD_GAP))
            .collect()
    }

    #[test]
    fn cards_are_centred_on_the_cluster_and_evenly_spread() {
        let centre = 10_000.0;
        let one = placed(1, centre);
        assert_eq!(one, vec![centre], "a single card sits on the centre");
        let three = placed(3, centre);
        assert_eq!(three.len(), 3);
        let middle = (three[0] + three[2]) / 2.0;
        assert!((middle - centre).abs() < 1.0, "the row is centred: {three:?}");
        assert!(
            ((three[1] - three[0]) - (three[2] - three[1])).abs() < 1.0,
            "evenly spread: {three:?}"
        );
        assert!((three[1] - three[0]) >= CARD_WIDTH, "and never overlapping");
    }

    /// Past the cap the row stops growing: a cluster is not a place to list twelve frames.
    #[test]
    fn a_cluster_never_carries_more_than_the_cap() {
        assert_eq!(placed(12, 0.0).len(), MAX_CARDS);
    }

    /// The card carries the frame's URL as an anchor INSIDE its text, because Miro's REST API
    /// rejects `linkedTo` — and the words name the frame, so a deleted map leaves a card that
    /// still says something true.
    #[test]
    fn a_card_carries_the_link_in_its_words() {
        let item = MiroClient::link_card_item(
            "map · YieldRouter",
            "https://miro.com/app/board/x=/?moveToWidget=123",
            0.0,
            0.0,
            100.0,
            50.0,
            90,
            "#ffffff",
            "#1a73e8",
        );
        let content = item["data"]["content"].as_str().expect("the words");
        assert!(content.contains("moveToWidget=123"), "{content}");
        assert!(content.contains("YieldRouter"), "{content}");
        assert!(item["parent"].is_null(), "a card sits on the board, not inside a frame");
    }
}

#[cfg(test)]
mod cards_for_test {
    use super::frames_showing;
    use crate::batbelt::evm::metadata::bat_metadata::MapFrameRef;

    fn frame(root: &str, contracts: &[&str]) -> MapFrameRef {
        MapFrameRef {
            root: root.to_string(),
            frame_id: format!("id-{root}"),
            contracts: contracts.iter().map(|name| name.to_string()).collect(),
            cards: Vec::new(),
        }
    }

    /// A cluster is carded for every frame that DRAWS its contract, not only for the frame
    /// named after it: `Treasury` is a leaf of three other systems and has no frame of its own.
    #[test]
    fn a_cluster_is_carded_for_every_frame_that_draws_it() {
        let frames = [
            frame("YieldRouter", &["YieldRouter", "AscendLaunchpad", "Treasury"]),
            frame("AscendCtoRegistry", &["AscendCtoRegistry", "Treasury"]),
            frame("ReferralPot", &["ReferralPot"]),
        ];
        let roots: Vec<&str> = frames_showing(&frames, "Treasury")
            .iter()
            .map(|frame| frame.root.as_str())
            .collect();
        assert_eq!(roots, vec!["YieldRouter", "AscendCtoRegistry"]);
        assert!(frames_showing(&frames, "BurnSink").is_empty(), "nothing drawn, nothing to point at");
    }
}

#[cfg(test)]
mod stale_card_test {
    use super::is_map_card;
    use crate::batbelt::miro::client::MiroClient;

    /// A card is recognised on the board by its OWN signature, so a lost registry cannot leave
    /// one behind: the prefix it is written with and the link it carries, both.
    #[test]
    fn a_card_is_recognised_by_what_it_says() {
        let card = MiroClient::link_card_item(
            "map · YieldRouter",
            "https://miro.com/app/board/x=/?moveToWidget=123",
            0.0,
            0.0,
            10.0,
            10.0,
            90,
            "#ffffff",
            "#1a73e8",
        );
        assert!(is_map_card(card["data"]["content"].as_str().expect("the words")));
    }

    /// Nothing else is touched. This is the only place the tool deletes an item it holds no id
    /// for, so the test is the guard: a note of the auditor's that merely mentions the map, or
    /// a link of theirs to a frame, is NOT a card.
    #[test]
    fn nothing_the_auditor_wrote_is_mistaken_for_one() {
        assert!(!is_map_card("<p>map · YieldRouter</p>"), "a label with no link");
        assert!(
            !is_map_card("<p><a href=\"https://miro.com/app/board/x=/?moveToWidget=9\">ir al mapa</a></p>"),
            "a link of their own, without the prefix"
        );
        assert!(!is_map_card("<p>revisar el map de nuevo</p>"));
    }
}

#[cfg(test)]
mod method_leaf_test {
    use super::{box_text, method_of, original_of, METHOD_MARK, OUTSIDE_MARK};

    /// A method leaf says the METHOD; which interface it belongs to is the box it hangs from,
    /// and its colour is still the interface's, so the three levels read as one chain:
    /// `YieldRouter → IERC20 → safeTransfer`.
    #[test]
    fn a_method_leaf_reads_as_its_method_and_keeps_its_interfaces_identity() {
        let leaf = format!("IERC20{OUTSIDE_MARK}YieldRouter{METHOD_MARK}safeTransfer");
        assert_eq!(box_text(&leaf), "safeTransfer()", "written as Solidity writes a call");
        assert_eq!(original_of(&leaf), "IERC20", "the colour is the interface's");
        assert!(super::is_outside(&leaf), "and it is still outside the repository");
        assert_eq!(method_of(&leaf), Some("safeTransfer"));
    }

    /// A COPY of a method leaf still says the method: `collect#3` is our bookkeeping, not
    /// something the reader asked about.
    #[test]
    fn a_copied_method_leaf_still_says_the_method() {
        let leaf = format!("IListing{OUTSIDE_MARK}Desk{METHOD_MARK}collect#3");
        assert_eq!(box_text(&leaf), "collect()");
        assert_eq!(original_of(&leaf), "IListing");
    }

    /// An ordinary box is not a method leaf.
    #[test]
    fn a_contract_box_has_no_method() {
        assert_eq!(method_of("Treasury"), None);
        assert_eq!(box_text("Treasury#2"), "Treasury");
        assert_eq!(box_text(&format!("IERC20{OUTSIDE_MARK}YieldRouter")), "IERC20");
    }
}

#[cfg(test)]
mod mark_test {
    use super::{PreparedFrame, BOX_BORDER, BOX_FILL, MARK_FILL, OUTSIDE_MARK};
    use std::collections::{BTreeMap, BTreeSet};

    fn frame(fills: BTreeMap<String, &'static str>) -> PreparedFrame {
        PreparedFrame {
            title: String::new(),
            root: String::new(),
            edges: Vec::new(),
            layout: super::layout_tree("x", &[]),
            arrows: Vec::new(),
            fills,
            borders: BTreeMap::new(),
            strip: Vec::new(),
            width: 0.0,
            height: 0.0,
            crossings: 0,
            left: 0.0,
            top: 0.0,
        }
    }

    /// Three channels, one meaning each. A marked contract takes the FILL, because a background
    /// is what carries at the zoom where a whole frame fits; an interface gives the fill up and
    /// takes a dotted border with its name in its own colour; everything else stays plain.
    #[test]
    fn a_marked_contract_is_filled_and_an_interface_is_dotted() {
        let fills: BTreeMap<String, &'static str> = [("IERC20".to_string(), "#d9ecff")].into();
        let frame = frame(fills);
        let marked: BTreeSet<String> = ["YieldRouter".to_string()].into();

        assert_eq!(frame.paint_of("YieldRouter", &marked), (MARK_FILL, BOX_BORDER, "normal"));
        assert_eq!(frame.paint_of("Treasury", &marked), (BOX_FILL, BOX_BORDER, "normal"));
        assert_eq!(
            frame.paint_of(&format!("IERC20{OUTSIDE_MARK}YieldRouter"), &marked),
            (BOX_FILL, "#d9ecff", "dotted"),
            "the fill is free for the marks; the interface keeps its colour on the border"
        );
    }

    /// A copy of a marked contract is marked too: the reader asked for the contract, not for one
    /// of its boxes.
    #[test]
    fn every_copy_of_a_marked_contract_is_filled() {
        let frame = frame(BTreeMap::new());
        let marked: BTreeSet<String> = ["Treasury".to_string()].into();
        assert_eq!(frame.paint_of("Treasury#3", &marked).0, MARK_FILL);
    }
}

#[cfg(test)]
mod repaint_test {
    use super::shape_name;

    /// A box's words are its contract's name, so the repaint knows what each one stands for
    /// without an id per box in the registry.
    #[test]
    fn a_box_says_which_contract_it_is() {
        assert_eq!(shape_name("<p><b>YieldRouter</b></p>").as_deref(), Some("YieldRouter"));
        assert_eq!(shape_name("<p><b>IERC20</b></p>").as_deref(), Some("IERC20"));
    }

    /// Everything that is not a contract box is left alone: the legend's rows, the strip's
    /// heading and a method leaf all carry words no contract has.
    #[test]
    fn nothing_else_is_repainted() {
        assert_eq!(shape_name("<p><b>not connected in scope</b></p>"), None);
        assert_eq!(shape_name("<p><b>filled: a contract you marked to see</b></p>"), None);
        assert_eq!(shape_name("<p></p>"), None);
        // A party box stands for its contract, so `mark --apply` paints it like the contract's
        // own box; an account is never filled, exactly as a redrawn map leaves it.
        assert_eq!(
            shape_name("<p><b>to: StakerDistributor</b></p>").as_deref(),
            Some("StakerDistributor")
        );
        assert_eq!(shape_name("<p><b>to: the claimant (address)</b></p>"), None);

    }
}

#[cfg(test)]
mod reads_only_test {
    use super::reads_only;
    use crate::batbelt::evm::metadata::bat_metadata::{ContractMetadata, EvmBatMetadata, FunctionMetadata};
    use crate::batbelt::evm::types::{EvmContractType, EvmMutability, EvmVisibility};

    fn function(name: &str, mutability: EvmMutability) -> FunctionMetadata {
        FunctionMetadata {
            metadata_id: name.to_string(),
            name: name.to_string(),
            contract_name: String::new(),
            visibility: EvmVisibility::External,
            mutability,
            modifiers: Vec::new(),
            params: Vec::new(),
            returns: Vec::new(),
            line: 1,
            end_line: 2,
            is_constructor: false,
            is_stub: false,
            storage_writes: Vec::new(),
            storage_write_sites: Vec::new(),
            unresolved_calls: Vec::new(),
            unknown_external_calls: Vec::new(),
            resolved_calls: Vec::new(),
            callbacks: Vec::new(),
            creations: Vec::new(),
        }
    }

    fn contract(name: &str, bases: &[&str], functions: Vec<FunctionMetadata>) -> ContractMetadata {
        ContractMetadata {
            metadata_id: name.to_string(),
            name: name.to_string(),
            using_libraries: Vec::new(),
            file_path: format!("src/{name}.sol"),
            contract_type: EvmContractType::Interface,
            base_contracts: bases.iter().map(|b| b.to_string()).collect(),
            functions,
            state_variables: Vec::new(),
            structs: Vec::new(),
            events: Vec::new(),
            modifiers: Vec::new(),
            line: 1,
            vendored: false,
        }
    }

    /// The language's own word decides, not a vocabulary of names: `view`/`pure` is a read,
    /// anything else can move value and keeps its leaf. Seventeen `balanceOf` boxes were
    /// crowding out the one `safeTransfer` that matters.
    #[test]
    fn a_view_is_a_read_and_the_rest_is_not() {
        let metadata = EvmBatMetadata {
            contracts: vec![contract(
                "IERC20",
                &[],
                vec![
                    function("balanceOf", EvmMutability::View),
                    function("transfer", EvmMutability::NonPayable),
                ],
            )],
            ..Default::default()
        };
        assert!(reads_only(&metadata, "IERC20", "balanceOf"));
        assert!(!reads_only(&metadata, "IERC20", "transfer"));
    }

    /// An interface that declares only part of its surface is answered by whoever implements
    /// it: same rule, wider search.
    #[test]
    fn an_implementers_declaration_counts() {
        let metadata = EvmBatMetadata {
            contracts: vec![
                contract("IListing", &[], Vec::new()),
                contract("Listing", &["IListing"], vec![function("poolCreator", EvmMutability::View)]),
            ],
            ..Default::default()
        };
        assert!(reads_only(&metadata, "IListing", "poolCreator"));
    }

    /// Nothing declares it: the leaf is DRAWN. An audit can discard a box it does not need; it
    /// cannot discard a transfer it was never shown. Guessing by name among unrelated contracts
    /// is what `bat-cli resolve` exists to replace.
    #[test]
    fn what_cannot_be_decided_is_drawn() {
        let metadata = EvmBatMetadata {
            contracts: vec![contract(
                "Unrelated",
                &[],
                vec![function("poolCreator", EvmMutability::View)],
            )],
            ..Default::default()
        };
        assert!(!reads_only(&metadata, "IListing", "poolCreator"));
    }

    /// One writer among several declarations of a name keeps the leaf.
    #[test]
    fn one_writer_is_enough_to_keep_it() {
        let metadata = EvmBatMetadata {
            contracts: vec![
                contract("IVault", &[], vec![function("pay", EvmMutability::View)]),
                contract("Vault", &["IVault"], vec![function("pay", EvmMutability::NonPayable)]),
            ],
            ..Default::default()
        };
        assert!(!reads_only(&metadata, "IVault", "pay"));
    }
}

#[cfg(test)]
mod inherited_mutability_test {
    use super::reads_only;
    use crate::batbelt::evm::metadata::bat_metadata::{ContractMetadata, EvmBatMetadata, FunctionMetadata};
    use crate::batbelt::evm::types::{EvmContractType, EvmMutability, EvmVisibility};

    fn function(name: &str, mutability: EvmMutability) -> FunctionMetadata {
        FunctionMetadata {
            metadata_id: name.to_string(),
            name: name.to_string(),
            contract_name: String::new(),
            visibility: EvmVisibility::External,
            mutability,
            modifiers: Vec::new(),
            params: Vec::new(),
            returns: Vec::new(),
            line: 1,
            end_line: 2,
            is_constructor: false,
            is_stub: false,
            storage_writes: Vec::new(),
            storage_write_sites: Vec::new(),
            unresolved_calls: Vec::new(),
            unknown_external_calls: Vec::new(),
            resolved_calls: Vec::new(),
            callbacks: Vec::new(),
            creations: Vec::new(),
        }
    }

    fn interface(name: &str, bases: &[&str], functions: Vec<FunctionMetadata>) -> ContractMetadata {
        ContractMetadata {
            metadata_id: name.to_string(),
            name: name.to_string(),
            using_libraries: Vec::new(),
            file_path: format!("lib/{name}.sol"),
            contract_type: EvmContractType::Interface,
            base_contracts: bases.iter().map(|b| b.to_string()).collect(),
            functions,
            state_variables: Vec::new(),
            structs: Vec::new(),
            events: Vec::new(),
            modifiers: Vec::new(),
            line: 1,
            vendored: true,
        }
    }

    /// A method INHERITED by the type is answered by the base that declares it, however deep.
    /// `ICLPoolManager` declares eleven methods and `vault` is not one of them: it comes from the
    /// interface it extends, and a getter drawn as if it moved value is the noise this filter
    /// exists to remove.
    #[test]
    fn a_getter_inherited_from_a_base_interface_is_still_a_read() {
        let metadata = EvmBatMetadata {
            contracts: vec![
                interface("ICLPoolManager", &["IPoolManager"], vec![function("swap", EvmMutability::NonPayable)]),
                interface("IPoolManager", &["IProtocolFees"], Vec::new()),
                interface("IProtocolFees", &[], vec![function("vault", EvmMutability::View)]),
            ],
            ..Default::default()
        };
        assert!(reads_only(&metadata, "ICLPoolManager", "vault"), "two levels up");
        assert!(!reads_only(&metadata, "ICLPoolManager", "swap"));
    }
}

#[cfg(test)]
mod address_box_test {
    use super::{
        box_text, is_wiring_point, node_height, ADDRESS_MARK, DESTINATION_MARK, METHOD_MARK,
        NODE_HEIGHT, OUTSIDE_MARK,
    };

    /// A destination is an entity, and an entity nobody has named is an ADDRESS. Drawn with the
    /// interface leaves' half-height dotted box it read as one more interface, and `yieldSink`
    /// sent the reader looking for a contract by that name.
    #[test]
    fn an_unnamed_destination_says_it_is_an_address() {
        let leaf = format!("IERC20{OUTSIDE_MARK}Vault{METHOD_MARK}transfer");
        let point = format!("{leaf}{DESTINATION_MARK}yieldSink{ADDRESS_MARK}");
        let named = format!("{leaf}{DESTINATION_MARK}BurnSink");

        assert_eq!(box_text(&point), "yieldSink (address)");
        assert_eq!(box_text(&named), "BurnSink");
        assert!(is_wiring_point(&point));
        assert!(!is_wiring_point(&named));
        // And both are contract-sized: a party is read from across the frame.
        assert_eq!(node_height(&point), NODE_HEIGHT);
        assert_eq!(node_height(&named), NODE_HEIGHT);
    }
}

#[cfg(test)]
mod node_width_test {
    use super::{node_width, METHOD_MARK, OUTSIDE_MARK};

    /// A box is as wide as the words it carries. A method leaf's id starts with its interface's
    /// name, and sizing by the id made `safeTransfer()` as narrow as `IERC20`.
    #[test]
    fn a_box_is_sized_by_what_it_says() {
        let short = format!("IERC20{OUTSIDE_MARK}Vault{METHOD_MARK}pay");
        let long = format!("IERC20{OUTSIDE_MARK}Vault{METHOD_MARK}safeTransferFrom");
        assert!(node_width(&long) > node_width(&short), "a longer method, a wider box");

        // And a copy is as wide as the original: `Treasury#2` carries `Treasury`.
        assert_eq!(node_width("Treasury#2"), node_width("Treasury"));
    }
}

#[cfg(test)]
mod parties_test {
    use super::{entity_of, is_address_like};
    use crate::batbelt::evm::metadata::bat_metadata::{ContractMetadata, EvmBatMetadata};
    use crate::batbelt::evm::types::{EvmContractType, EvmVisibility, StorageVariable};

    fn variable(name: &str, type_name: &str) -> StorageVariable {
        StorageVariable {
            name: name.to_string(),
            type_name: type_name.to_string(),
            visibility: EvmVisibility::Public,
            is_constant: false,
            is_immutable: true,
            line: 1,
        }
    }

    fn stub(name: &str) -> crate::batbelt::evm::metadata::bat_metadata::FunctionMetadata {
        use crate::batbelt::evm::types::EvmMutability;
        crate::batbelt::evm::metadata::bat_metadata::FunctionMetadata {
            metadata_id: name.to_string(),
            name: name.to_string(),
            contract_name: String::new(),
            visibility: EvmVisibility::External,
            mutability: EvmMutability::NonPayable,
            params: Vec::new(),
            returns: Vec::new(),
            modifiers: Vec::new(),
            line: 1,
            end_line: 2,
            is_constructor: false,
            is_stub: true,
            storage_writes: Vec::new(),
            storage_write_sites: Vec::new(),
            unresolved_calls: Vec::new(),
            unknown_external_calls: Vec::new(),
            resolved_calls: Vec::new(),
            callbacks: Vec::new(),
            creations: Vec::new(),
        }
    }

    fn contract(name: &str, variables: Vec<StorageVariable>) -> 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: variables,
            structs: Vec::new(),
            events: Vec::new(),
            modifiers: Vec::new(),
            line: 1,
            vendored: false,
        }
    }

    /// Three outcomes, and the middle one is the point: an argument that names a contract draws
    /// that contract, a plain `address` held in STATE draws its own name — it is a fixed party,
    /// decided at deployment and never changed, even though the code never says which contract
    /// it is — and anything else draws nothing.
    #[test]
    fn an_argument_is_a_contract_a_wiring_point_or_nothing() {
        let metadata = EvmBatMetadata {
            contracts: vec![
                contract(
                    "YieldRouter",
                    vec![
                        variable("burnSink", "address"),
                        variable("vault", "AscendYieldVault"),
                    ],
                ),
                contract("AscendYieldVault", Vec::new()),
            ],
            ..Default::default()
        };
        let router = &metadata.contracts[0];

        // The VARIABLE that holds it, then the contract: a caller with two vaults has two
        // addresses, and the type alone would draw one box for both.
        assert_eq!(
            entity_of(&metadata, router, "pay", "vault").as_deref(),
            Some("vault%AscendYieldVault")
        );
        assert_eq!(
            entity_of(&metadata, router, "pay", "burnSink").as_deref(),
            Some("burnSink~"),
            "a fixed party the code cannot name — marked as the address it is"
        );
        assert_eq!(entity_of(&metadata, router, "pay", "this").as_deref(), Some("YieldRouter"));
        // Whoever called this time is not a party of the system.
        assert_eq!(entity_of(&metadata, router, "pay", "msg.sender"), None);
        assert_eq!(entity_of(&metadata, router, "pay", "recipient"), None, "a parameter is not one");
    }

    /// The one fact the code can never hold: which contract a state `address` was wired to at
    /// deployment. Once somebody records it, the box is that contract and stops being an
    /// address — and it is keyed by the HOLDER, so another contract's `burnSink` is untouched.
    #[test]
    fn a_recorded_wiring_turns_an_address_into_the_entity_it_holds() {
        let metadata = EvmBatMetadata {
            contracts: vec![
                contract("YieldRouter", vec![variable("burnSink", "address")]),
                contract("ReferralPot", vec![variable("burnSink", "address")]),
                contract("BurnSink", Vec::new()),
            ],
            wiring: std::collections::HashMap::from([(
                "YieldRouter.burnSink".to_string(),
                "BurnSink".to_string(),
            )]),
            ..Default::default()
        };
        // The variable stays in front of the answer: two slots of one type are two addresses.
        assert_eq!(
            entity_of(&metadata, &metadata.contracts[0], "pay", "burnSink").as_deref(),
            Some("burnSink%BurnSink")
        );
        assert_eq!(
            entity_of(&metadata, &metadata.contracts[1], "pay", "burnSink").as_deref(),
            Some("burnSink~"),
            "another contract's variable of the same name is still unnamed"
        );
    }

    /// A call site's own answer. `to` is whatever the caller passed, which no analysis can
    /// settle — but a reader who traced it can, and the key carries the FUNCTION, so the same
    /// name in another function is a separate question.
    #[test]
    fn a_recorded_call_site_names_the_party_the_caller_passes() {
        let metadata = EvmBatMetadata {
            contracts: vec![contract("StakerDistributor", Vec::new()), contract("Treasury", Vec::new())],
            wiring: std::collections::HashMap::from([(
                "StakerDistributor._pay.to".to_string(),
                "Treasury".to_string(),
            )]),
            ..Default::default()
        };
        let distributor = &metadata.contracts[0];
        assert_eq!(entity_of(&metadata, distributor, "_pay", "to").as_deref(), Some("Treasury"));
        assert_eq!(
            entity_of(&metadata, distributor, "refund", "to"),
            None,
            "another function's `to` is another question"
        );
    }

    /// Which parameter a party fills. `transferFrom(from, to, amount)` hands addresses to two
    /// different roles, and two boxes carrying only names do not say which one pays.
    #[test]
    fn a_party_says_which_parameter_it_fills() {
        use super::{parties_of, ADDRESS_MARK};
        use crate::batbelt::evm::types::{EvmMutability, EvmParam};
        let mut token = contract("IERC20", Vec::new());
        token.contract_type = EvmContractType::Interface;
        token.functions = vec![crate::batbelt::evm::metadata::bat_metadata::FunctionMetadata {
            metadata_id: "f".to_string(),
            name: "transferFrom".to_string(),
            contract_name: "IERC20".to_string(),
            visibility: EvmVisibility::External,
            mutability: EvmMutability::NonPayable,
            params: vec![
                EvmParam { name: "from".to_string(), type_name: "address".to_string(), storage_location: None },
                EvmParam { name: "to".to_string(), type_name: "address".to_string(), storage_location: None },
                EvmParam { name: "amount".to_string(), type_name: "uint256".to_string(), storage_location: None },
            ],
            returns: Vec::new(),
            modifiers: Vec::new(),
            line: 1,
            end_line: 2,
            is_constructor: false,
            is_stub: true,
            storage_writes: Vec::new(),
            storage_write_sites: Vec::new(),
            unresolved_calls: Vec::new(),
            unknown_external_calls: Vec::new(),
            resolved_calls: Vec::new(),
            callbacks: Vec::new(),
            creations: Vec::new(),
        }];
        let mut caller = contract("Vault", vec![variable("treasury", "Treasury")]);
        caller.functions = vec![token.functions[0].clone()];
        let metadata = EvmBatMetadata {
            contracts: vec![caller.clone(), token, contract("Treasury", Vec::new())],
            wiring: std::collections::HashMap::from([
                ("Vault.pull.payer".to_string(), "a staker".to_string()),
            ]),
            ..Default::default()
        };
        let mut pull = metadata.contracts[0].functions[0].clone();
        pull.name = "pull".to_string();
        let (parties, unnamed) = parties_of(
            &metadata,
            &metadata.contracts[0],
            &pull,
            "IERC20",
            "transferFrom",
            &["payer".to_string(), "treasury".to_string()],
        );
        assert!(unnamed.is_empty(), "both arguments answered: {unnamed:?}");
        assert_eq!(parties[0], format!("from: a staker{ADDRESS_MARK}"));
        assert_eq!(parties[1], "to: treasury%Treasury");
    }

    /// A struct is where an address hides from a signature: `exactInput(ExactInputParams(path,
    /// address(this), …))` declares no address and hands one over. Three call sites in ascend,
    /// and not one of them was drawn or even reported.
    #[test]
    fn an_address_inside_a_struct_is_still_a_party() {
        use super::addressed_arguments;
        use crate::batbelt::evm::types::{EvmParam, EvmStruct};
        let mut router = contract("IStakingSwapRouter", Vec::new());
        router.structs = vec![EvmStruct {
            name: "ExactInputParams".to_string(),
            fields: vec![
                EvmParam { name: "path".to_string(), type_name: "bytes".to_string(), storage_location: None },
                EvmParam { name: "recipient".to_string(), type_name: "address".to_string(), storage_location: None },
                EvmParam { name: "amount".to_string(), type_name: "uint256".to_string(), storage_location: None },
            ],
        }];
        let metadata = EvmBatMetadata { contracts: vec![router], ..Default::default() };
        let params = [EvmParam {
            name: "params".to_string(),
            type_name: "IStakingSwapRouter.ExactInputParams".to_string(),
            storage_location: None,
        }];
        let found = addressed_arguments(
            &metadata,
            &params,
            0,
            &["ExactInputParams(paths[], this, amount)".to_string()],
        );
        assert_eq!(found, vec![("params.recipient".to_string(), "this".to_string())]);
    }

    /// The control that comes back. `lock(bytes)` says nothing; the body it lands on says
    /// `ILockCallback(msg.sender).lockAcquired(data)`, so the caller is called back — and only
    /// a caller that declares the callback can receive one.
    #[test]
    fn a_callee_that_calls_msg_sender_calls_its_caller_back() {
        use super::calls_back;
        let mut vault = contract("IVault", Vec::new());
        vault.contract_type = EvmContractType::Interface;
        let mut lock = stub("lock");
        lock.callbacks = vec!["lockAcquired".to_string()];
        vault.functions = vec![lock];
        let mut router = contract("YieldRouter", Vec::new());
        router.functions = vec![stub("lockAcquired")];
        let deaf = contract("ReferralPot", Vec::new());
        let metadata = EvmBatMetadata {
            contracts: vec![vault, router.clone(), deaf.clone()],
            ..Default::default()
        };
        assert_eq!(calls_back(&metadata, &router, "IVault", "lock"), vec!["lockAcquired".to_string()]);
        assert!(
            calls_back(&metadata, &deaf, "IVault", "lock").is_empty(),
            "a caller with no `lockAcquired` never receives one"
        );
    }

    /// Five deployments of one contract are five boxes, told apart by the variable that holds
    /// each one. `AscendLaunchpad` pays five `Treasury`s in `_routeProtocolFees`, and with the
    /// type alone on the box the reader cannot tell which one got what.
    #[test]
    fn two_variables_of_one_type_are_two_boxes() {
        use super::{box_text, entity_named};
        let launchpad = contract(
            "AscendLaunchpad",
            vec![variable("opexTreasury", "Treasury"), variable("kntqTreasury", "Treasury")],
        );
        let metadata = EvmBatMetadata {
            contracts: vec![launchpad, contract("Treasury", Vec::new())],
            ..Default::default()
        };
        let opex = entity_of(&metadata, &metadata.contracts[0], "_route", "opexTreasury").unwrap();
        let kntq = entity_of(&metadata, &metadata.contracts[0], "_route", "kntqTreasury").unwrap();
        assert_ne!(opex, kntq);
        assert_eq!(
            box_text(&format!("IERC20@AscendLaunchpad::safeTransfer=>to: {opex}")),
            "to: opexTreasury (Treasury)"
        );
        // And both still stand for `Treasury`, so `bat-cli mark Treasury` paints the pair.
        assert_eq!(entity_named(&format!("to: {kntq}")), "Treasury");
    }

    /// A library's parameters are filled by whoever calls it, and each host fills them
    /// differently: `VaultPay.buyExactIn(…, to)` takes `l.receiver` from the router and
    /// `d.devBuyRecipient` from the launchpad. One set of destinations hung on every host made
    /// the router's `take()` show the launchpad's recipients and the launchpad show the
    /// router's.
    #[test]
    fn a_librarys_destinations_are_its_call_sites_own() {
        use super::call_sites;
        use crate::batbelt::evm::metadata::bat_metadata::ExternalUnknownCall;
        use crate::batbelt::evm::types::EvmParam;
        let mut library = contract("VaultPay", Vec::new());
        library.contract_type = EvmContractType::Library;
        let mut buy = stub("buyExactIn");
        buy.params = vec![
            EvmParam { name: "vault".to_string(), type_name: "IVault".to_string(), storage_location: None },
            EvmParam { name: "to".to_string(), type_name: "address".to_string(), storage_location: None },
        ];
        library.functions = vec![buy.clone()];

        let mut host = contract("YieldRouter", Vec::new());
        let mut locked = stub("lockAcquired");
        locked.unknown_external_calls = vec![ExternalUnknownCall {
            receiver: "poolVault".to_string(),
            method: "buyExactIn".to_string(),
            inferred_type: "IVault".to_string(),
            arguments: vec!["l.receiver".to_string()],
        }];
        host.functions = vec![locked];

        // The library's internal call hands `to` on; the host's call site decides what that is.
        let sites = call_sites(&host, &library, &buy, &["to".to_string()]);
        assert_eq!(sites.len(), 1);
        assert_eq!(sites[0].0.name, "YieldRouter", "resolved where the argument is written");
        assert_eq!(sites[0].1.name, "lockAcquired", "and the reader is sent to that line");
        assert_eq!(sites[0].2, vec!["l.receiver".to_string()]);

        // Reached through another function of the library itself: nothing is substituted and
        // the names stay the LIBRARY's, because `VaultPay.pay`'s own `vault` is not
        // `YieldRouter.vault`.
        let orphan = contract("ReferralPot", Vec::new());
        let sites = call_sites(&orphan, &library, &buy, &["to".to_string()]);
        assert_eq!(sites[0].0.name, "VaultPay");
        assert_eq!(sites[0].2, vec!["to".to_string()]);
    }

    /// A state address is marked once, by `entity_of`. Marked twice, the box read
    /// `POOL~ (address)` — the map's own bookkeeping, printed for the reader.
    #[test]
    fn a_wiring_point_carries_one_address_mark() {
        use super::{parties_of, ADDRESS_MARK};
        use crate::batbelt::evm::types::{EvmMutability, EvmParam};
        let mut token = contract("IERC20", Vec::new());
        token.contract_type = EvmContractType::Interface;
        let mut transfer = stub("safeTransfer");
        transfer.params = vec![EvmParam {
            name: "to".to_string(),
            type_name: "address".to_string(),
            storage_location: None,
        }];
        transfer.mutability = EvmMutability::NonPayable;
        token.functions = vec![transfer];
        let caller = contract("Account", vec![variable("POOL", "address")]);
        let metadata = EvmBatMetadata { contracts: vec![caller.clone(), token], ..Default::default() };
        let (parties, _) = parties_of(
            &metadata,
            &metadata.contracts[0],
            &stub("repay"),
            "IERC20",
            "safeTransfer",
            &["POOL".to_string()],
        );
        assert_eq!(parties, vec![format!("to: POOL{ADDRESS_MARK}")]);
    }

    /// An answer that names no contract of this repository is an ACCOUNT — a creator, a
    /// multisig, whoever called. It is still an answer, and it is still drawn; what it must not
    /// do is look like code somebody can open.
    #[test]
    fn an_answer_that_is_not_a_contract_is_drawn_as_an_account() {
        let metadata = EvmBatMetadata {
            contracts: vec![contract("Desk", Vec::new())],
            wiring: std::collections::HashMap::from([
                ("Desk.enroll.creator".to_string(), "the launch creator".to_string()),
            ]),
            ..Default::default()
        };
        assert_eq!(
            entity_of(&metadata, &metadata.contracts[0], "enroll", "creator").as_deref(),
            Some("the launch creator")
        );
    }

    /// The zero address is a destination like any other: value sent there is burnt, and the
    /// argument says so in full. Asking the reader to resolve `address(0)` is asking them to
    /// name what is already named.
    #[test]
    fn the_zero_address_is_its_own_name() {
        let metadata = EvmBatMetadata {
            contracts: vec![contract("ListingDesk", Vec::new())],
            ..Default::default()
        };
        assert_eq!(
            entity_of(&metadata, &metadata.contracts[0], "_stop", "address(0)").as_deref(),
            Some("address(0)")
        );
    }

    /// A binding for ONE caller. `lib/` vendors three `IVault`s; a global resolution answers
    /// for every one of them, so the specific entry has to win where it exists and leave the
    /// rest asking.
    #[test]
    fn a_scoped_resolution_beats_the_global_one() {
        let metadata = EvmBatMetadata {
            resolutions: std::collections::HashMap::from([
                ("IVault".to_string(), "AscendYieldVault".to_string()),
                ("YieldRouter:IVault".to_string(), "CLVault".to_string()),
            ]),
            ..Default::default()
        };
        assert_eq!(
            metadata.resolution_for(Some("YieldRouter"), "IVault").map(String::as_str),
            Some("CLVault")
        );
        assert_eq!(
            metadata.resolution_for(Some("ReferralPot"), "IVault").map(String::as_str),
            Some("AscendYieldVault"),
            "another caller still reads the global binding"
        );
        assert_eq!(metadata.resolution_for(None, "IVault").map(String::as_str), Some("AscendYieldVault"));
    }

    /// One key, several contracts: a function reached from two places with two destinations is
    /// two parties, and recording one of them would hide the other.
    #[test]
    fn a_recorded_answer_may_name_several_contracts() {
        let metadata = EvmBatMetadata {
            contracts: vec![
                contract("Router", vec![variable("sink", "address")]),
                contract("BurnSink", Vec::new()),
                contract("Treasury", Vec::new()),
            ],
            wiring: std::collections::HashMap::from([(
                "Router.sink".to_string(),
                "BurnSink, Treasury".to_string(),
            )]),
            ..Default::default()
        };
        assert_eq!(
            entity_of(&metadata, &metadata.contracts[0], "pay", "sink").as_deref(),
            Some("BurnSink,Treasury")
        );
    }

    /// Which parameters are parties: the ones whose type is an address, plainly or because it
    /// names a contract.
    #[test]
    fn a_party_is_an_address_or_a_contract() {
        let metadata = EvmBatMetadata {
            contracts: vec![contract("Treasury", Vec::new())],
            ..Default::default()
        };
        assert!(is_address_like(&metadata, "address"));
        assert!(is_address_like(&metadata, "address payable"));
        assert!(is_address_like(&metadata, "Treasury"));
        assert!(!is_address_like(&metadata, "uint256"));
        assert!(!is_address_like(&metadata, "bytes"));
    }
}

#[cfg(test)]
mod wrapper_test {
    use super::unwrap_library_call;
    use crate::batbelt::evm::metadata::bat_metadata::{
        ContractMetadata, EvmBatMetadata, ExternalUnknownCall, FunctionMetadata,
    };
    use crate::batbelt::evm::types::{EvmContractType, EvmMutability, EvmParam, EvmVisibility};

    fn param(name: &str, type_name: &str) -> EvmParam {
        EvmParam {
            name: name.to_string(),
            type_name: type_name.to_string(),
            storage_location: None,
        }
    }

    fn wrapper(name: &str, params: Vec<EvmParam>, inner: Vec<ExternalUnknownCall>) -> FunctionMetadata {
        FunctionMetadata {
            metadata_id: name.to_string(),
            name: name.to_string(),
            contract_name: "SafeERC20".to_string(),
            visibility: EvmVisibility::Internal,
            mutability: EvmMutability::NonPayable,
            modifiers: Vec::new(),
            params,
            returns: Vec::new(),
            line: 1,
            end_line: 2,
            is_constructor: false,
            is_stub: false,
            storage_writes: Vec::new(),
            storage_write_sites: Vec::new(),
            unresolved_calls: Vec::new(),
            unknown_external_calls: inner,
            resolved_calls: Vec::new(),
            callbacks: Vec::new(),
            creations: Vec::new(),
        }
    }

    fn inner(receiver: &str, method: &str, arguments: &[&str]) -> ExternalUnknownCall {
        ExternalUnknownCall {
            receiver: receiver.to_string(),
            method: method.to_string(),
            inferred_type: "IERC20".to_string(),
            arguments: arguments.iter().map(|a| a.to_string()).collect(),
        }
    }

    fn two(library: ContractMetadata, caller: ContractMetadata) -> EvmBatMetadata {
        EvmBatMetadata {
            contracts: vec![library, caller],
            ..Default::default()
        }
    }

    fn contract(name: &str, using: &[&str], functions: Vec<FunctionMetadata>) -> ContractMetadata {
        ContractMetadata {
            metadata_id: name.to_string(),
            name: name.to_string(),
            using_libraries: using.iter().map(|u| u.to_string()).collect(),
            file_path: format!("src/{name}.sol"),
            contract_type: EvmContractType::Contract,
            base_contracts: Vec::new(),
            functions,
            state_variables: Vec::new(),
            structs: Vec::new(),
            events: Vec::new(),
            modifiers: Vec::new(),
            line: 1,
            vendored: false,
        }
    }

    /// A wrapper is drawn as the call it actually makes, with the call site's arguments put in
    /// the wrapper's parameters: `token.safeTransfer(burnSink, amount)` is a `transfer` to
    /// `burnSink`. `IERC20` has no `safeTransfer` to show — it comes from `using SafeERC20`.
    #[test]
    fn a_wrapper_is_drawn_as_the_call_it_makes() {
        let library = contract(
            "SafeERC20",
            &[],
            vec![wrapper(
                "safeTransfer",
                vec![param("token", "IERC20"), param("to", "address"), param("value", "uint256")],
                vec![inner("token", "transfer", &["to", "value"])],
            )],
        );
        let caller = contract("YieldRouter", &["SafeERC20"], Vec::new());
        let metadata = two(library, caller);
        let found = unwrap_library_call(
            &metadata,
            &metadata.contracts[1],
            "safeTransfer",
            &["burnSink".to_string(), "amount".to_string()],
        );
        assert_eq!(
            found,
            Some(("transfer".to_string(), vec!["burnSink".to_string(), "amount".to_string()]))
        );
    }

    /// Calling the same method twice is still one relation — `forceApprove` approves zero and
    /// then the value — but a wrapper that calls two DIFFERENT methods is not flattened into one
    /// box.
    #[test]
    fn one_method_twice_is_fine_and_two_methods_are_not() {
        let twice = contract(
            "SafeERC20",
            &[],
            vec![wrapper(
                "forceApprove",
                vec![param("token", "IERC20"), param("spender", "address"), param("value", "uint256")],
                vec![
                    inner("token", "approve", &["spender", "value"]),
                    inner("token", "approve", &["spender", "0"]),
                ],
            )],
        );
        let caller = contract("YieldRouter", &["SafeERC20"], Vec::new());
        let metadata = two(twice, caller);
        assert_eq!(
            unwrap_library_call(
                &metadata,
                &metadata.contracts[1],
                "forceApprove",
                &["venue".to_string(), "amount".to_string()]
            )
            .map(|(method, _)| method),
            Some("approve".to_string())
        );

        let mixed = contract(
            "Odd",
            &[],
            vec![wrapper(
                "doBoth",
                vec![param("token", "IERC20"), param("to", "address")],
                vec![inner("token", "approve", &["to"]), inner("token", "transfer", &["to"])],
            )],
        );
        let caller = contract("YieldRouter", &["Odd"], Vec::new());
        let metadata = two(mixed, caller);
        assert_eq!(
            unwrap_library_call(&metadata, &metadata.contracts[1], "doBoth", &["x".to_string()]),
            None,
            "two different methods are not one box"
        );
    }

    /// A method of the type itself is not a wrapper and is left alone.
    #[test]
    fn a_plain_call_is_not_unwrapped() {
        let caller = contract("YieldRouter", &["SafeERC20"], Vec::new());
        let metadata = two(contract("SafeERC20", &[], Vec::new()), caller);
        assert_eq!(
            unwrap_library_call(&metadata, &metadata.contracts[1], "transfer", &[]),
            None
        );
    }
}