blockworx/schema/

raise.rs

//! The write direction of the round trip (phase 7, D9): the folded document
//! back as the on-disk schema structs, feeding the emitter ([`super::encode`])
//! that already agrees with the parser — one format authority.
//!
//! `raise` is also the document's *canonical form*. Minted uuids collapse to
//! generated string ids over a deterministic order (blocks depth-first from
//! `top`, siblings by position; pins by boundary slot), so two documents that
//! raise identically are the same diagram — which is what the round-trip
//! tests assert, and why the output is stable under refactors.
//!
//! Deliberately lossy, in both directions' favor: asset ids are re-derived
//! from content (a hand-written `"art.svg"` comes back as `"<hash>.svg"`),
//! and port bodies are always written explicitly rather than re-omitted when
//! they match the auto-placement — omission is a read-side reconstruction,
//! and re-running it on export would move geometry the user never touched.

use ahash::HashMap;
use base64::Engine as _;
use blockworx_doc::{
    block_model::{Asset, Block, Icon, Label, Pin},
    document::Document,
    geometry::{GridPoint, GridRect},
    id::{BlockId, PinId, RouteId},
    rev::RevKind,
    values::{LabelSide, PinSide},
};

use crate::edit::lower::{
    accent_from_role, artwork_rect, schema_label_side, schema_pin_dir, schema_pin_side,
};
use crate::schema::loc::format_loc;
use crate::schema::model as schema;

/// The generated spellings, both namespaces: `"b<N>"` per block in canonical
/// order, `"p<N>"` per pin within its owner.
struct Names {
    blocks: HashMap<BlockId, String>,
    pins: HashMap<PinId, (BlockId, String)>,
}

/// The whole document, canonically ordered and named. The inverse of
/// [`super::lower::lower`] up to minted identity.
pub fn raise<R: RevKind>(doc: &Document<R>) -> schema::Document {
    let order = block_order(doc);
    let pins = pins_by_owner(doc);
    let names = Names {
        blocks: order
            .iter()
            .enumerate()
            .map(|(i, &(id, _))| (id, format!("b{i}")))
            .collect(),
        pins: pins
            .iter()
            .flat_map(|(&owner, pins)| {
                pins.iter()
                    .enumerate()
                    .map(move |(i, &(id, _))| (id, (owner, format!("p{}", i + 1))))
            })
            .collect(),
    };

    let mut assets = AssetIds::default();
    let blocks: Vec<schema::Block> = order
        .iter()
        .map(|&entry| {
            raise_block(
                doc,
                entry,
                &names,
                pins.get(&entry.0).map_or(&[][..], Vec::as_slice),
                &mut assets,
            )
        })
        .collect();

    let name = doc.title_block().name.as_ref();
    let top = names
        .blocks
        .get(doc.title_block().top.as_ref())
        .or_else(|| order.first().and_then(|(id, _)| names.blocks.get(id)))
        .cloned()
        .unwrap_or_default();
    schema::Document {
        version: schema::CURRENT_VERSION,
        name: (!name.is_empty()).then(|| name.clone()),
        top,
        blocks,
        assets: assets.assets,
    }
}

/// Serialize `doc` as KDL text — the whole export path in one call.
pub fn to_kdl<R: RevKind>(doc: &Document<R>) -> String {
    raise(doc).to_kdl()
}

/// Siblings sort by position, then id as the total-order tiebreak for
/// coincident blocks — file order is not document state (draw order is
/// derived), so the exporter owns it and keeps it deterministic.
fn position_key(rect: &GridRect, id: BlockId) -> (i32, i32, BlockId) {
    (rect.top_left.y, rect.top_left.x, id)
}

/// Depth-first from the top block, then any unreachable stragglers — so the
/// top block is `b0` and a child always follows its parent, matching how the
/// files are written by hand.
fn block_order<R: RevKind>(doc: &Document<R>) -> Vec<(BlockId, &Block)> {
    let live: Vec<(BlockId, &Block)> = doc
        .blocks()
        .filter(|(_, live)| live.is_alive())
        .map(|(id, live)| (id, live.as_ref()))
        .collect();
    let mut children: HashMap<BlockId, Vec<(BlockId, &Block)>> = HashMap::default();
    for &(id, block) in &live {
        children
            .entry(*block.parent.as_ref())
            .or_default()
            .push((id, block));
    }
    for siblings in children.values_mut() {
        siblings.sort_by_key(|(id, block)| position_key(block.rect.as_ref(), *id));
    }

    let mut order: Vec<(BlockId, &Block)> = Vec::with_capacity(live.len());
    let mut stack: Vec<(BlockId, &Block)> = Vec::new();
    let top = *doc.title_block().top.as_ref();
    stack.extend(live.iter().find(|&&(id, _)| id == top));
    while let Some(entry) = stack.pop() {
        order.push(entry);
        if let Some(kids) = children.get(&entry.0) {
            stack.extend(kids.iter().rev());
        }
    }
    let mut stragglers: Vec<(BlockId, &Block)> = live
        .iter()
        .filter(|(id, _)| !order.iter().any(|(seen, _)| seen == id))
        .copied()
        .collect();
    stragglers.sort_by_key(|(id, block)| position_key(block.rect.as_ref(), *id));
    // A straggler root brings its own subtree in the same depth-first order
    // the top's got.
    for root in stragglers {
        stack.push(root);
        while let Some(entry) = stack.pop() {
            if order.iter().any(|(seen, _)| *seen == entry.0) {
                continue;
            }
            order.push(entry);
            if let Some(kids) = children.get(&entry.0) {
                stack.extend(kids.iter().rev());
            }
        }
    }
    order
}

fn pins_by_owner<R: RevKind>(doc: &Document<R>) -> HashMap<BlockId, Vec<(PinId, &Pin)>> {
    let mut pins: HashMap<BlockId, Vec<(PinId, &Pin)>> = HashMap::default();
    for (id, live) in doc.pins().filter(|(_, live)| live.is_alive()) {
        let pin = live.as_ref();
        pins.entry(*pin.owner.as_ref()).or_default().push((id, pin));
    }
    for owned in pins.values_mut() {
        owned.sort_by_key(|(id, pin)| {
            let slot = *pin.slot.as_ref();
            (
                match slot.side {
                    PinSide::West => 0_u8,
                    PinSide::East => 1,
                },
                slot.offset,
                *id,
            )
        });
    }
    pins
}

fn raise_block<R: RevKind>(
    doc: &Document<R>,
    (id, block): (BlockId, &Block),
    names: &Names,
    pins: &[(PinId, &Pin)],
    assets: &mut AssetIds,
) -> schema::Block {
    let rect = *block.rect.as_ref();

    let mut children: Vec<(GridRect, BlockId)> = doc
        .blocks()
        .filter(|(_, live)| live.is_alive())
        .filter(|(_, live)| *live.as_ref().parent.as_ref() == id)
        .map(|(kid, live)| (*live.as_ref().rect.as_ref(), kid))
        .collect();
    children.sort_by_key(|&(rect, kid)| position_key(&rect, kid));

    let mut texts: Vec<(GridPoint, schema::Text)> = doc
        .texts()
        .filter(|(_, live)| live.is_alive())
        .map(|(_, live)| live.as_ref())
        .filter(|text| *text.owner.as_ref() == id)
        .map(|text| {
            let pos = *text.pos.as_ref();
            (
                pos,
                schema::Text {
                    text: text.text.as_ref().clone(),
                    x: pos.x,
                    y: pos.y,
                    role: accent_from_role(*text.role.as_ref()),
                },
            )
        })
        .collect();
    texts.sort_by(|(a, ta), (b, tb)| (a.y, a.x, &ta.text).cmp(&(b.y, b.x, &tb.text)));

    let mut comments: Vec<schema::Comment> = doc
        .comments()
        .filter(|(_, live)| live.is_alive())
        .map(|(_, live)| live.as_ref())
        .filter(|comment| *comment.owner.as_ref() == id)
        .map(|comment| {
            let rect = *comment.rect.as_ref();
            schema::Comment {
                x: rect.top_left.x,
                y: rect.top_left.y,
                w: rect.size.w,
                h: rect.size.h,
                role: accent_from_role(*comment.role.as_ref()),
                title: raise_label(&comment.title, LabelSide::Bottom),
            }
        })
        .collect();
    comments.sort_by_key(|c| (c.y, c.x, c.w, c.h));

    let mut images: Vec<schema::Image> = doc
        .images()
        .filter(|(_, live)| live.is_alive())
        .map(|(_, live)| live.as_ref())
        .filter(|image| *image.owner.as_ref() == id)
        .filter_map(|image| {
            let asset = assets.id_for(doc, *image.asset.as_ref())?;
            Some(placement(asset, *image.rect.as_ref()))
        })
        .collect();
    images.sort_by(|a, b| {
        a.y.total_cmp(&b.y)
            .then(a.x.total_cmp(&b.x))
            .then(a.asset.cmp(&b.asset))
    });

    let icon = block.icon.as_ref();
    let icon = (*icon != Icon::default())
        .then(|| Some(placement(assets.id_for(doc, icon.asset)?, icon.rect)))
        .flatten();

    schema::Block {
        id: names.blocks[&id].clone(),
        x: rect.top_left.x,
        y: rect.top_left.y,
        w: rect.size.w,
        h: rect.size.h,
        role: accent_from_role(*block.role.as_ref()),
        locked: *block.locked.as_ref(),
        title: raise_label(&block.title, LabelSide::Bottom),
        type_label: raise_label(&block.type_label, LabelSide::Top),
        pins: pins
            .iter()
            .map(|&(pin_id, pin)| raise_pin(pin_id, pin, names))
            .collect(),
        routes: raise_routes(doc, id, names),
        texts: texts.into_iter().map(|(_, text)| text).collect(),
        comments,
        images,
        icon,
        children: children
            .into_iter()
            .map(|(_, kid)| names.blocks[&kid].clone())
            .collect(),
    }
}

fn raise_pin(id: PinId, pin: &Pin, names: &Names) -> schema::Pin {
    let slot = *pin.slot.as_ref();
    let rect = *pin.rect.as_ref();
    schema::Pin {
        id: names.pins[&id].1.clone(),
        name: pin.name.as_ref().clone(),
        type_label: pin.type_name.as_ref().clone(),
        tag: pin.tag.as_ref().clone(),
        tag_hidden: *pin.tag_hidden.as_ref(),
        loc: Some(format_loc(schema_pin_side(slot.side), slot.offset)),
        x: Some(rect.top_left.x),
        y: Some(rect.top_left.y),
        w: Some(rect.size.w),
        dir: schema_pin_dir(*pin.dir.as_ref()),
        // Stub and port-pin accents are derived from route roles (swap D2)
        // and are never document state, so they are never exported.
        pin_accent: None,
        port_accent: accent_from_role(*pin.port_accent.as_ref()),
        port_pin_accent: None,
        fliplr: *pin.flip_lr.as_ref(),
    }
}

fn raise_routes<R: RevKind>(
    doc: &Document<R>,
    owner: BlockId,
    names: &Names,
) -> Vec<schema::Route> {
    let spell = |pin: PinId| -> Option<String> {
        let (pin_owner, name) = names.pins.get(&pin)?;
        Some(if *pin_owner == owner {
            name.clone()
        } else {
            format!("{}:{name}", names.blocks.get(pin_owner)?)
        })
    };
    let mut labels: HashMap<RouteId, Vec<f32>> = HashMap::default();
    for (_, live) in doc.route_labels().filter(|(_, live)| live.is_alive()) {
        let label = live.as_ref();
        labels
            .entry(*label.owner.as_ref())
            .or_default()
            .push((*label.pos.as_ref()).into());
    }

    let mut routes: Vec<schema::Route> = doc
        .routes()
        .filter(|(_, live)| live.is_alive())
        .filter(|(_, live)| *live.as_ref().owner.as_ref() == owner)
        .filter_map(|(id, live)| {
            let route = live.as_ref();
            let (Some(from), Some(to)) = (spell(route.from), spell(route.to)) else {
                // Unreachable through the fold (it refuses a route whose
                // endpoint is absent), so worth a loud note if it happens.
                tracing::warn!("not exporting a route with an unresolvable endpoint");
                return None;
            };
            let mut positions = labels.remove(&id).unwrap_or_default();
            positions.sort_by(|a, b| a.total_cmp(b));
            Some(schema::Route {
                name: route.name.as_ref().clone(),
                from,
                to,
                role: accent_from_role(*route.role.as_ref()),
                waypoints: route
                    .waypoints
                    .as_ref()
                    .iter()
                    .map(|w| schema::Waypoint {
                        x: w.pos.x,
                        y: w.pos.y,
                        locked: w.locked,
                    })
                    .collect(),
                labels: positions,
            })
        })
        .collect();
    routes.sort_by(|a, b| (&a.from, &a.to, &a.name).cmp(&(&b.from, &b.to, &b.name)));
    routes
}

/// A label namespace back as the schema's optional label. Collapses in two
/// steps mirroring the loader's fallbacks: a side equal to the per-kind
/// fallback is omitted, and a label all of whose fields are at their
/// omitted-state values is not written at all.
fn raise_label(label: &Label, fallback: LabelSide) -> Option<schema::Label> {
    let name = label.name.as_ref();
    let side = *label.side.as_ref();
    let offset: f32 = (*label.offset.as_ref()).into();
    let hidden = *label.hidden.as_ref();
    if name.is_empty() && side == fallback && offset == 0.0 && !hidden {
        return None;
    }
    Some(schema::Label {
        name: name.clone(),
        side: (side != fallback).then(|| schema_label_side(side)),
        offset,
        hidden,
    })
}

fn placement(asset: String, rect: blockworx_doc::geometry::ScreenRect) -> schema::Image {
    let rect = artwork_rect(rect);
    schema::Image {
        asset,
        x: rect.min.x,
        y: rect.min.y,
        w: rect.width(),
        h: rect.height(),
    }
}

/// Payloads keyed by their content hash, named content-derived
/// (`"<hash16>.<ext>"`) exactly as the legacy writer named them — equal
/// images get equal ids in every document, and an unrelated edit never
/// renumbers anything.
#[derive(Default)]
struct AssetIds {
    ids: Vec<(blockworx_doc::hash::AssetHash, String)>,
    assets: Vec<schema::Asset>,
}

impl AssetIds {
    /// The id naming `hash`, minting (and recording the payload) on first
    /// sight. `None` where the document holds a placement but not the bytes
    /// it names — the fold ought to bar that, so it is worth a loud note.
    fn id_for<R: RevKind>(
        &mut self,
        doc: &Document<R>,
        hash: blockworx_doc::hash::AssetHash,
    ) -> Option<String> {
        if let Some((_, id)) = self.ids.iter().find(|(seen, _)| *seen == hash) {
            return Some(id.clone());
        }
        let Some(asset) = doc.asset(&hash) else {
            tracing::warn!("not exporting a placement of {hash}: the document holds no payload");
            return None;
        };
        let (bytes, ext, image) = match asset {
            Asset::Svg(bytes) => (
                &**bytes,
                "svg",
                schema::ImageData::Svg(String::from_utf8_lossy(bytes).into_owned()),
            ),
            Asset::Png(bytes) => (
                &**bytes,
                "png",
                schema::ImageData::Png(base64::engine::general_purpose::STANDARD.encode(bytes)),
            ),
        };
        let id = format!("{}.{ext}", &blake3::hash(bytes).to_hex()[..16]);
        self.assets.push(schema::Asset {
            id: id.clone(),
            image,
        });
        self.ids.push((hash, id.clone()));
        Some(id)
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::schema::lower::lower;
    use blockworx_doc::rev::Confirmed;

    /// `lower`'s own everything-in-one-file fixture, round-tripped here.
    const RICH: &str = crate::schema::lower::tests::RICH;

    fn folded(src: &str) -> Document<Confirmed> {
        let parsed = schema::Document::parse_kdl(src, "raise").expect("the fixture parses");
        let lowered = lower(&parsed, "raise");
        let mut doc = Document::<Confirmed>::default();
        for commit in &lowered.commits {
            doc = doc.try_apply(commit).expect("the lowered commit folds");
        }
        doc
    }

    fn block_named<'a>(doc: &'a schema::Document, title: &str) -> &'a schema::Block {
        doc.blocks
            .iter()
            .find(|b| b.title.as_ref().is_some_and(|t| t.name == title))
            .unwrap_or_else(|| panic!("no raised block titled {title:?}"))
    }

    /// The projection carries every stored field back out — spot-checked
    /// against the fixture's own values so a field `raise` dropped cannot
    /// hide behind the round trip's symmetry.
    #[test]
    fn the_rich_fixture_raises_with_its_fields_intact() {
        let raised = raise(&folded(RICH));

        assert_eq!(raised.version, schema::CURRENT_VERSION);
        assert_eq!(raised.name.as_deref(), Some("bridge"));

        let sheet = block_named(&raised, "sheet");
        assert_eq!(raised.top, sheet.id, "the top pointer survives");
        assert_eq!((sheet.x, sheet.y, sheet.w, sheet.h), (0, 0, 30, 20));
        let title = sheet.title.as_ref().expect("the sheet keeps its title");
        assert_eq!(
            (title.side, title.offset, title.hidden),
            (Some(crate::schema::enums::LabelSide::Center), 1.5, true),
        );

        let core = block_named(&raised, "core");
        assert_eq!(sheet.children, vec![core.id.clone()], "nesting survives");
        assert_eq!(core.role, Some(3));
        assert!(core.locked);
        assert_eq!(
            core.type_label.as_ref().map(|t| (t.name.as_str(), t.side)),
            Some(("Add", None)),
            "a type label at its per-kind default side omits the side",
        );

        let pin = |block: &schema::Block, name: &str| -> schema::Pin {
            block
                .pins
                .iter()
                .find(|p| p.name == name)
                .unwrap_or_else(|| panic!("no raised pin named {name:?}"))
                .clone()
        };
        let input = pin(sheet, "in");
        assert_eq!(input.loc.as_deref(), Some("w0"));
        assert_eq!(input.dir, Some(crate::schema::enums::PinType::Input));
        assert_eq!((input.tag.as_str(), input.tag_hidden), ("A", true));
        assert_eq!(input.port_accent, Some(2));
        assert!(input.fliplr);
        assert!(
            input.x.is_some() && input.w.is_some(),
            "an omitted port body exports explicitly once reconstructed",
        );
        let output = pin(sheet, "out");
        assert_eq!((output.x, output.y, output.w), (Some(4), Some(6), Some(5)));
        assert_eq!(output.type_label, "bit");
        assert_eq!(
            pin(core, "a").dir,
            None,
            "an in-out pin omits `dir`, the spelling that reads back as in-out",
        );

        let route = {
            assert_eq!(sheet.routes.len(), 1, "the dangling route stayed dropped");
            &sheet.routes[0]
        };
        assert_eq!(route.name, "net");
        assert_eq!(route.role, Some(1));
        assert_eq!(
            route.from,
            pin(sheet, "in").id,
            "an own-block anchor is bare"
        );
        assert_eq!(
            route.to,
            format!("{}:{}", core.id, pin(core, "a").id),
            "a child anchor is qualified",
        );
        assert_eq!(
            route.waypoints,
            vec![
                schema::Waypoint {
                    x: 12,
                    y: 35,
                    locked: false
                },
                schema::Waypoint {
                    x: 2,
                    y: 41,
                    locked: true
                },
            ],
        );
        assert_eq!(route.labels, vec![7.5]);

        assert_eq!(sheet.texts.len(), 1);
        assert_eq!(
            (sheet.texts[0].x, sheet.texts[0].y, sheet.texts[0].role),
            (10, 5, Some(1)),
        );
        assert_eq!(sheet.comments.len(), 1);
        assert_eq!(
            sheet.comments[0].title.as_ref().map(|t| t.name.as_str()),
            Some("group"),
        );

        assert_eq!(raised.assets.len(), 1, "one payload for two placements");
        let asset = &raised.assets[0];
        assert_eq!(
            asset.id,
            format!("{}.svg", &blake3::hash(b"<svg/>").to_hex()[..16]),
            "the id is content-derived, replacing the file's own spelling",
        );
        assert_eq!(sheet.images.len(), 1);
        assert_eq!(sheet.images[0].asset, asset.id);
        assert_eq!(
            sheet.icon.as_ref().map(|icon| icon.asset.as_str()),
            Some(asset.id.as_str()),
        );
        assert_ne!(
            (sheet.images[0].x, sheet.images[0].y),
            (
                sheet.icon.as_ref().unwrap().x,
                sheet.icon.as_ref().unwrap().y
            ),
            "the two placements keep their own boxes",
        );
    }

    /// The round trip: raised text, read back through the real pipeline,
    /// raises identically. `raise` is canonical (deterministic ids and
    /// order), so equality of raised forms is equality of diagrams.
    #[test]
    fn parse_lower_fold_raise_is_identity_on_the_raised_form() {
        let raised = raise(&folded(RICH));
        let round_tripped = raise(&folded(&raised.to_kdl()));
        assert_eq!(round_tripped, raised);
    }

    /// The canonical form really is canonical: the same diagram spelled
    /// with different ids, in a different order, raises to the same text.
    #[test]
    fn raising_normalizes_ids_and_order() {
        const REORDERED: &str = r#"
            name "bridge"
            top "b7"

            block "b3" x=6 y=6 w=8 h=5 {
                title "core"
                pin "p9" "a" loc="w1"
            }

            block "b7" x=0 y=0 w=30 h=20 {
                title "sheet"
                pin "p4" "out" loc="e3" x=4 y=6 w=5
                pin "p2" "in" loc="w0"
                route "p2" "b3:p9" name="net"
                children "b3"
            }
        "#;
        const CANONICAL: &str = r#"
            name "bridge"
            top "b0"

            block "b0" x=0 y=0 w=30 h=20 {
                title "sheet"
                pin "p1" "in" loc="w0"
                pin "p2" "out" loc="e3" x=4 y=6 w=5
                route "p1" "b1:p1" name="net"
                children "b1"
            }

            block "b1" x=6 y=6 w=8 h=5 {
                title "core"
                pin "p1" "a" loc="w1"
            }
        "#;
        assert_eq!(
            raise(&folded(REORDERED)).to_kdl(),
            raise(&folded(CANONICAL)).to_kdl(),
        );
    }

    /// The degenerate export: nothing to say, but still a well-formed
    /// document shape (an empty block list and an empty top pointer).
    #[test]
    fn an_empty_document_raises_empty() {
        let raised = raise(&Document::<Confirmed>::default());
        assert_eq!(raised.blocks, vec![]);
        assert_eq!(raised.top, "");
        assert_eq!(raised.name, None);
    }
}