blockworx_doc/fixtures/

scale.rs

//! An N×N scale-test scene: a sheet wrapping a square grid of identical
//! `Add` blocks, fully wired, with no pin left dangling.
//!
//! `cargo xtask autogen scale N out.json` serializes what this builds, and
//! the editor's test fixtures lower the same [`Document`] in-process, so the
//! file on disk and the scene under test are one scene.

use crate::{
    block_model::{Block, Label, Pin, Route},
    commit::CommitBuilder,
    document::{Document, TitleBlockUpdate},
    geometry::{GridPoint, GridRect, GridSize, PinSlot},
    id::{Allocator, BlockId, PinId},
    opcode::{Crud, OpCodes},
    values::{LabelSide, PinDir, PinSide},
};

/// Grid spacing in grid units: each block is [`BLOCK`] wide/tall and columns/rows
/// are placed on a [`PITCH`] lattice, leaving a gap for wires to route through.
const BLOCK: i32 = 8;
const PITCH: i32 = 16;
const MARGIN: i32 = 12;
/// A boundary port body, in cells. Wide enough for its name, two cells tall so
/// the anchor (one cell down from the top) sits inside it.
const PORT_W: i32 = 4;
const PORT_H: i32 = 2;

/// The four pins every grid block carries: two west inputs, two east
/// outputs. Named once so the wiring and the emitter cannot disagree about
/// which is which.
struct GridPins {
    b0: PinId,
    b1: PinId,
    s: PinId,
    c: PinId,
}

/// Every id the grid uses, minted in the order the file numbers them: the
/// sheet, then the grid blocks row-major; the sheet's boundary ports, then
/// each grid block's four.
struct Scale {
    ids: Allocator,
    n: usize,
    sheet: BlockId,
    grid: Vec<BlockId>,
    inputs: Vec<PinId>,
    outputs: Vec<PinId>,
    pins: Vec<GridPins>,
}

impl Scale {
    fn new(n: usize) -> Self {
        let mut ids = Allocator::default();
        let sheet = ids.mint();
        let grid: Vec<BlockId> = (0..n * n).map(|_| ids.mint()).collect();
        let inputs: Vec<PinId> = (0..n).map(|_| ids.mint()).collect();
        let outputs: Vec<PinId> = (0..n).map(|_| ids.mint()).collect();
        let pins: Vec<GridPins> = (0..n * n)
            .map(|_| GridPins {
                b0: ids.mint(),
                b1: ids.mint(),
                s: ids.mint(),
                c: ids.mint(),
            })
            .collect();
        Self {
            ids,
            n,
            sheet,
            grid,
            inputs,
            outputs,
            pins,
        }
    }

    fn at(&self, i: usize, j: usize) -> &GridPins {
        &self.pins[i * self.n + j]
    }
}

/// The N×N scene as a folded document.
///
/// # Panics
/// Never: every op creates an entity under an id this run minted, which is
/// exactly what the fold accepts.
#[must_use]
#[expect(clippy::expect_used)]
pub fn build_scale(n: usize) -> Document {
    let mut scale = Scale::new(n);
    let mut builder = CommitBuilder::new(format!("Generated a {n}×{n} scale grid"));
    let span = (n as i32 - 1) * PITCH + BLOCK;

    builder.push(OpCodes::Block(
        scale.sheet,
        Crud::Create(Block {
            rect: cells(-MARGIN, -MARGIN, span + 2 * MARGIN, span + 2 * MARGIN),
            title: title(&format!("scale_{n}x{n}")),
            ..Block::default()
        }),
    ));
    for i in 0..n {
        for j in 0..n {
            builder.push(OpCodes::Block(
                scale.grid[i * n + j],
                Crud::Create(Block {
                    parent: scale.sheet,
                    rect: cells(j as i32 * PITCH, i as i32 * PITCH, BLOCK, BLOCK),
                    title: title(&format!("block_{i}_{j}")),
                    type_label: Label {
                        name: "Add".to_owned(),
                        ..Label::default()
                    },
                    ..Block::default()
                }),
            ));
        }
    }
    builder.push(OpCodes::Document(TitleBlockUpdate::Top(scale.sheet)));

    // The sheet block wraps the whole grid: its west edge carries the
    // `in_*` ports, its east edge the `out_*` ports, and it owns every wire.
    for (i, &id) in scale.inputs.iter().enumerate() {
        builder.push(
            port(id, scale.sheet, &format!("in_{i}"), west(i), PinDir::Input)
                .in_body(port_body(-MARGIN + 3, i))
                .op(),
        );
    }
    for (i, &id) in scale.outputs.iter().enumerate() {
        builder.push(
            port(
                id,
                scale.sheet,
                &format!("out_{i}"),
                east(i),
                PinDir::Output,
            )
            .in_body(port_body(span + MARGIN - 3 - PORT_W, i))
            .op(),
        );
    }
    for index in 0..n * n {
        let owner = scale.grid[index];
        let pins = &scale.pins[index];
        builder.push(port(pins.b0, owner, "b0", west(0), PinDir::Input).op());
        builder.push(port(pins.b1, owner, "b1", west(1), PinDir::Input).op());
        builder.push(port(pins.s, owner, "s", east(0), PinDir::Output).op());
        builder.push(port(pins.c, owner, "c", east(1), PinDir::Output).op());
    }

    for (from, to, name) in wiring(&scale) {
        builder.push(OpCodes::Route(
            scale.ids.mint(),
            Crud::Create(Route {
                owner: scale.sheet,
                name: name.to_owned(),
                from,
                to,
                ..Route::default()
            }),
        ));
    }

    let commit = builder.seal().expect("the grid emits at least one op");
    Document::default()
        .try_apply(&commit)
        .expect("the generated grid folds")
}

/// Every wire, as the pins it joins. The scheme leaves no pin dangling:
///   - `in_i`     → block(i,0).b0  and  block((i+1)%N,0).b1   (column-0 inputs)
///   - block.s    → right neighbour's b0 and b1               (horizontal chain)
///   - last col s → `out_i`                                   (sheet outputs)
///   - block.c    → block-below.b1 (wrapping)                 (vertical carry)
fn wiring(scale: &Scale) -> Vec<(PinId, PinId, &'static str)> {
    let n = scale.n;
    let mut wires = Vec::new();
    // Sheet inputs feed column 0. `in_i` drives this row's b0 and the next
    // row's b1, so every column-0 input is covered.
    for i in 0..n {
        wires.push((scale.inputs[i], scale.at(i, 0).b0, "in"));
        wires.push((scale.inputs[i], scale.at((i + 1) % n, 0).b1, "in"));
    }
    // Horizontal sum chain: each block's `s` drives both inputs of its right
    // neighbour.
    for i in 0..n {
        for j in 0..n - 1 {
            let src = scale.at(i, j).s;
            wires.push((src, scale.at(i, j + 1).b0, "sum"));
            wires.push((src, scale.at(i, j + 1).b1, "sum"));
        }
    }
    // Last column drains its `s` into the matching sheet output.
    for i in 0..n {
        wires.push((scale.at(i, n - 1).s, scale.outputs[i], "out"));
    }
    // Vertical carry chain covers every `c` output (and the wrap keeps the
    // last row's carries wired), giving each `c` a home.
    for i in 0..n {
        for j in 0..n {
            wires.push((scale.at(i, j).c, scale.at((i + 1) % n, j).b1, "carry"));
        }
    }
    wires
}

/// A pin to create. `slot` places it on its block-as-child; `body` places the
/// same pin inside the block's own interior view, where the scope draws it as a
/// free-standing port. The two are independent, and the default body is the
/// trap: every boundary port left at it stacks at the origin, and the wires
/// anchored there start from inside whatever block sits over that spot.
struct PinSpec<'a> {
    id: PinId,
    owner: BlockId,
    name: &'a str,
    slot: PinSlot,
    dir: PinDir,
    body: GridRect,
}

impl PinSpec<'_> {
    /// Place the port body, for a pin some scope draws as a boundary port.
    fn in_body(mut self, body: GridRect) -> Self {
        self.body = body;
        self
    }

    fn op(self) -> OpCodes {
        OpCodes::Pin(
            self.id,
            Crud::Create(Pin {
                owner: self.owner,
                name: self.name.to_owned(),
                type_name: "bit".to_owned(),
                slot: self.slot,
                dir: self.dir,
                rect: self.body,
                ..Pin::default()
            }),
        )
    }
}

fn port(id: PinId, owner: BlockId, name: &str, slot: PinSlot, dir: PinDir) -> PinSpec<'_> {
    PinSpec {
        id,
        owner,
        name,
        slot,
        dir,
        body: GridRect::default(),
    }
}

/// A boundary port's body, on the sheet's west or east margin and level with
/// the grid row it serves, so its wire leaves along that row instead of
/// crossing the sheet to reach it.
fn port_body(margin_x: i32, row: usize) -> GridRect {
    cells(margin_x, row as i32 * PITCH, PORT_W, PORT_H)
}

fn west(offset: usize) -> PinSlot {
    PinSlot {
        side: PinSide::West,
        offset: offset as u32,
    }
}

fn east(offset: usize) -> PinSlot {
    PinSlot {
        side: PinSide::East,
        offset: offset as u32,
    }
}

fn title(name: &str) -> Label {
    Label {
        name: name.to_owned(),
        side: LabelSide::Bottom,
        ..Label::default()
    }
}

fn cells(x: i32, y: i32, w: i32, h: i32) -> GridRect {
    GridRect {
        top_left: GridPoint { x, y },
        size: GridSize {
            w: w.unsigned_abs(),
            h: h.unsigned_abs(),
        },
    }
}