gras 1.0.2

A Genetic Programming framework for Neural Architecture Search in Rust
Documentation
//! Markdown rendering for topologies — includes nodes table, edge list,
//! ASCII wiring diagram, and Mermaid flowchart.

use super::ascii::{AsciiNode, edge_list, render_wire_diagram};
use super::mermaid::topology_mermaid;
use crate::graph::network::Network;
use crate::graph::node::NodeKind;
use crate::graph::topology::Topology;

/// Markdown rendering of a [`Topology`]: header, merged nodes/network table,
/// edge list, and the visual wiring diagram in a code block.
/// When a built [`Network`] is provided, the nodes table includes linear dims
/// and source wiring (merged topology + network view).
///
/// Deliberately stamp-free: the header only identifies the topology — it does
/// not claim a fitness or rank. Scores live in the CSV; this is a structural
/// view you generate for any individual you choose.
pub fn topology_markdown(graph: &Topology, net: Option<&Network>) -> String {
    let mut out = String::new();

    // Header
    out.push_str(&format!("# Topology #{}\n\n", graph.id));

    // Summary
    let hidden_range: Vec<usize> = graph.nodes.iter().filter_map(|n| n.hidden_dim).collect();
    let hidden_info = if hidden_range.is_empty() {
        "hidden 8".to_string()
    } else {
        let min = *hidden_range.iter().min().unwrap();
        let max = *hidden_range.iter().max().unwrap();
        if min == max {
            format!("hidden {min}")
        } else {
            format!("hidden {min}–{max}")
        }
    };
    out.push_str(&format!(
        "**{} nodes** · **{} wires** · input {} → {} → output {}\n\n",
        graph.nodes.len(),
        graph.connections.len(),
        graph
            .options
            .input_dim
            .map(|x| x.to_string())
            .unwrap_or_else(|| "?".into()),
        hidden_info,
        graph
            .options
            .output_dim
            .map(|x| x.to_string())
            .unwrap_or_else(|| "?".into()),
    ));

    // ── Nodes table (merged topology + network layer info) ──
    out.push_str("## Nodes\n\n");
    if let Some(net) = net {
        // Full table: ID, Kind, In, Out, Linear, Activation, Combine, Std, Sources
        out.push_str("| ID | Kind | In | Out | Linear | Activation | Combine | Std | Sources |\n");
        out.push_str("|----|------|----|-----|--------|------------|---------|-----|---------|\n");
        let node_sources = super::graph_utils::build_node_sources(
            &net.connections,
            &net.nodes.iter().map(|n| n.num_inputs).collect::<Vec<_>>(),
        );
        for (i, node) in graph.nodes.iter().enumerate() {
            let kind = match node.kind {
                NodeKind::Input => "Input",
                NodeKind::Hidden => "Hidden",
                NodeKind::Output => "Output",
            };
            let act = node.activation;
            let combine = node.combine_op.map_or("—".into(), |op| format!("{op}"));
            let std = node.standardize.map_or("—".into(), |s| format!("{s}"));
            let (in_dim, out_dim) = graph.node_dims().get(i).copied().unwrap_or((0, 0));
            let marker = if i == net.output_node { " " } else { "" };
            let sources: Vec<String> = node_sources[i]
                .iter()
                .flatten()
                .map(|p| format!("n{}_o{}", p.node, p.index))
                .collect();
            let src_str = if sources.is_empty() {
                "*".into()
            } else {
                sources.join(", ")
            };
            out.push_str(&format!(
                "| {id} {kind}{marker} | {kind} | {ni} | {no} | {in_dim} → {out_dim} | {act} | {combine} | {std} | {src_str} |\n",
                id = i,
                ni = node.num_inputs,
                no = node.num_outputs,
            ));
        }
    } else {
        // Topology-only table: no linear dims or sources
        out.push_str("| ID | Kind | In | Out | Activation | Combine | Std | Dims |\n");
        out.push_str("|----|------|----|-----|------------|---------|-----|------|\n");
        for (node_id, node) in graph.nodes.iter().enumerate() {
            let kind = match node.kind {
                NodeKind::Input => "Input",
                NodeKind::Hidden => "Hidden",
                NodeKind::Output => "Output",
            };
            let act = node.activation;
            let combine = node.combine_op.map_or("—".into(), |op| format!("{op}"));
            let std = node.standardize.map_or("—".into(), |s| format!("{s}"));
            let (in_dim, out_dim) = graph.node_dims().get(node_id).copied().unwrap_or((0, 0));
            out.push_str(&format!(
                "| {id} | {kind} | {ni} | {no} | {act} | {combine} | {std} | {in_dim}→{out_dim} |\n",
                id = node.id,
                ni = node.num_inputs,
                no = node.num_outputs,
            ));
        }
    }
    out.push('\n');

    // ── Edge list with distance markers ──
    out.push_str("## Edges\n\n");
    out.push_str("```text\n");
    out.push_str(&edge_list(graph));
    out.push_str("```\n\n");

    // ── Wiring diagram (with out dims) ──
    out.push_str("## Wiring diagram\n\n");
    out.push_str("```text\n");
    let node_dims = graph.node_dims();
    let nodes: Vec<AsciiNode> = graph
        .nodes
        .iter()
        .enumerate()
        .map(|(i, n)| AsciiNode {
            id: n.id,
            kind: n.kind,
            num_inputs: n.num_inputs,
            num_outputs: n.num_outputs,
            out_dim: node_dims.get(i).map(|&(_, out)| out),
        })
        .collect();
    out.push_str(&render_wire_diagram(&nodes, &graph.connections));
    out.push_str("```\n");
    out.push_str("\n> **Legend**:\n");
    out.push_str("> - I=input  H=hidden  O=output\n");
    out.push_str("> - 0i/4o = input ports / output ports\n");
    out.push_str("> - ->dim = output dimension\n");
    out.push_str("> - ▶ connected output  ◀ connected input  * orphaned port\n");

    // Mermaid flowchart
    out.push_str("\n## Graph\n\n");
    out.push_str(&topology_mermaid(graph));

    // ── Legend — plain-words reasoning guide for every visual above ──
    // Each visual channel (border, wire, label) encodes one structural
    // fact; the legend says which, so a reader never has to guess.
    out.push_str("\n## How to read this\n\n");
    out.push_str("| You see | It means | How to reason about it |\n");
    out.push_str("|---|---|---|");
    out.push_str("\n| **Box border thickness** | the node's `hidden_dim` | A thick border = that node carries a lot of information (wide layer). Thin = narrow layer. Compare borders *within this one net* — they are scaled to this net's min→max dim, not a global scale. |");
    out.push_str("\n| **Wire thickness** | hop distance of the connection | A thick wire skips far (e.g. H1 → out, jumping over intermediate layers) — a long-range shortcut. Thin wires connect neighbors. Skip-heavy nets mix features from different depths; neighbor-only nets process locally, layer by layer. |");
    out.push_str("\n| **Box label** | `H<id> <activation> <dim>` | The node's id, its activation function, and its width. E.g. `H3 gelu 48` = hidden node 3, GELU, 48 units. |");
    out.push_str("\n| **`in <n>` / `out <n>`** | dataset shape | Fixed by the problem: number of features in, classes out. |");
    out.push_str("\n| **Nodes table → `Sources`** | which outputs feed each node | `n1_o2, n3_o0` = this node reads output 2 of node 1 and output 0 of node 3. Empty (`*`) = orphaned port (nothing connects there). |");
    out.push_str("\n| **Nodes table → `Combine`** | how a node merges its inputs | `Mean`/`Min`/`Max` — what happens when several wires arrive at one box. |");
    out.push_str("\n| **Nodes table → `Std`** | per-node standardization | Whether inputs are normalized before combining. |");
    out.push_str("\n| **Edge list → `<<<<`** | long jump | Same fact as thick wires, in text form: this connection skips over nodes. |");
    out.push_str("\n| **Wiring diagram → `▶ ◀ *`** | port connection state | ▶ = this output is wired somewhere, ◀ = this input receives something, * = orphaned (unused port — often harmless, sometimes a search artifact). |");
    out.push_str("\n");

    out
}