//! The generation engine: [`GenContext`], [`Pass`], [`Pipeline`], [`Snapshot`]
//! (spec §4.6).
//!
//! This is the keystone contract every concrete pass (Tasks 7–11) consumes. The
//! shape of the data flow is:
//!
//! - A [`Pipeline`] is a recipe: a canvas size plus an ordered list of passes.
//! - [`Pipeline::run`] builds a fresh [`GenContext`] (an all-[`Tile::Wall`] grid
//!   and empty regions/graph/blackboard), then applies each [`Pass`] in order,
//!   mutating the shared context.
//! - The final context is packaged into a [`crate::map::Map`] — the library's
//!   sole output.
//!
//! ## RNG isolation is owned here, not by passes (spec §4.6, §7)
//!
//! [`Pipeline::run`] creates one root [`Rng`] from the seed and, for each pass,
//! derives a **dedicated** child stream via [`Rng::fork`] keyed by
//! `"<pass name>#<occurrence>"`, where `occurrence` is a *per-name* counter the
//! run loop maintains. Each pass receives only its own `&mut Rng` and never sees
//! a shared one.
//!
//! Because [`Rng::fork`] depends only on `(seed, key)` — not on draw history —
//! this makes determinism-under-pipeline-edits **structural**: in pipelines
//! `[A, B]` and `[A, X, B]`, both `A` and `B` still key to `A#0` / `B#0`, so they
//! receive identical streams regardless of the inserted `X`. Inserting or
//! reordering a pass never reshuffles another pass's randomness.
//!
//! ## `run` and `run_with_snapshots` cannot diverge (spec §7)
//!
//! Both public entry points delegate to the single private
//! [`Pipeline::run_inner`], so the generation path is literally shared. The only
//! difference is whether a [`Snapshot`] is cloned out after each pass — snapshot
//! capture only *reads* context state and never touches the RNG, so the
//! resulting [`Map`] is identical for a given seed with or without snapshots.

use crate::blackboard::Blackboard;
use crate::geometry::{Point, Rect};
use crate::grid::Grid;
use crate::map::{Map, Tile};
use crate::region::{ConnGraph, Edge, Region, RegionId, RegionKind};
use crate::rng::Rng;
use std::collections::HashMap;

/// The mutable working state threaded through every [`Pass`] (spec §4.6).
///
/// A pass reads and writes these fields directly — they are the only channel
/// through which passes communicate (passes never call each other). The starting
/// state for a run is an all-[`Tile::Wall`] grid with empty regions, graph, and
/// blackboard; each pass carves tiles, appends regions, adds edges, or stashes
/// scratch data on the [`Blackboard`].
pub struct GenContext {
    /// The terrain layer being carved. Starts entirely [`Tile::Wall`].
    pub tiles: Grid<Tile>,
    /// The semantic regions discovered/created so far, indexed by [`RegionId`].
    pub regions: Vec<Region>,
    /// The region connectivity graph (edges added by connector passes).
    pub graph: ConnGraph,
    /// Named typed scratch slots for cross-pass data that isn't tiles/regions.
    pub blackboard: Blackboard,
}

impl GenContext {
    /// Appends a new region and returns its [`RegionId`].
    ///
    /// The id is assigned as `RegionId(self.regions.len())` *before* the push, so
    /// it equals the region's index in [`regions`](GenContext::regions). Regions
    /// are append-only — never removed or reordered — which preserves the
    /// id-as-index invariant (Task 5 / [`RegionId`]) that edges and lookups rely
    /// on.
    pub fn add_region(&mut self, kind: RegionKind, bounds: Rect, cells: Vec<Point>) -> RegionId {
        let id = RegionId(self.regions.len());
        self.regions.push(Region {
            id,
            kind,
            bounds,
            cells,
        });
        id
    }
}

/// A single generation step (spec §4.6).
///
/// Implementors are small, focused transforms (partition, carve, connect, place)
/// that mutate the shared [`GenContext`]. The contract is deliberately tight:
///
/// - [`name`](Pass::name) is the pass's stable identity. The pipeline uses it to
///   key this pass's dedicated RNG sub-stream (`"<name>#<occurrence>"`), so two
///   distinct pass *kinds* should return distinct names.
/// - [`apply`](Pass::apply) takes `&self`: a pass's configuration is immutable
///   during a run. The pipeline — not the pass — tracks how many times a given
///   name has occurred, so the same config can appear twice and still get
///   distinct, stable streams. A pass draws all its randomness from the `rng`
///   it is handed and from no other source.
pub trait Pass {
    /// This pass's stable name, used to key its dedicated RNG sub-stream.
    fn name(&self) -> &str;

    /// Applies this pass to `ctx`, drawing any randomness from `rng`.
    ///
    /// `rng` is a sub-stream dedicated to this pass occurrence; a pass must not
    /// reach for any other source of randomness if the run is to stay
    /// deterministic.
    fn apply(&self, ctx: &mut GenContext, rng: &mut Rng);
}

/// A point-in-time capture of generation state, taken *after* a pass runs
/// (spec §4.6).
///
/// Snapshots feed a visualization scrubber that steps through generation. Each
/// captures the tiles **and** the region bounds + graph edges, so passes that
/// don't change tiles (partition, connect) are still visible as state changes.
/// Snapshotting only clones context state — it never advances the RNG — so
/// collecting snapshots cannot alter the final [`Map`].
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct Snapshot {
    /// The name of the pass that produced this state (its [`Pass::name`]).
    pub label: String,
    /// The tile grid as it stood just after the pass ran.
    pub tiles: Grid<Tile>,
    /// The regions as they stood just after the pass ran.
    pub regions: Vec<Region>,
    /// The connectivity edges as they stood just after the pass ran.
    pub edges: Vec<Edge>,
}

/// A generation recipe: a canvas size plus an ordered list of passes.
///
/// Build one with [`Pipeline::new`] and chain passes with the
/// [`then`](Pipeline::then) builder, then produce a map with
/// [`run`](Pipeline::run) (or [`run_with_snapshots`](Pipeline::run_with_snapshots)
/// for the viz scrubber). The pipeline owns the canvas dimensions: `run` builds
/// the initial all-[`Tile::Wall`] grid at that size.
pub struct Pipeline {
    /// Canvas width in cells.
    width: u32,
    /// Canvas height in cells.
    height: u32,
    /// The passes to apply, in order.
    passes: Vec<Box<dyn Pass>>,
}

impl Pipeline {
    /// Creates an empty pipeline for a `width` × `height` canvas.
    ///
    /// Add passes with [`then`](Pipeline::then).
    pub fn new(width: u32, height: u32) -> Self {
        Pipeline {
            width,
            height,
            passes: Vec::new(),
        }
    }

    /// Appends `pass` and returns the pipeline, for fluent chaining.
    ///
    /// `'static` is required because the pass is boxed and stored; any owned
    /// pass value (including one capturing `Rc<RefCell<_>>` for test
    /// observation) satisfies it. The pipeline is single-threaded, so no `Send`
    /// bound is needed.
    pub fn then(mut self, pass: impl Pass + 'static) -> Self {
        self.passes.push(Box::new(pass));
        self
    }

    /// Runs the pipeline for `seed`, returning the generated [`Map`].
    ///
    /// Builds a fresh [`GenContext`], applies each pass in order with its own
    /// forked RNG sub-stream, and packages the result. Equivalent to
    /// [`run_with_snapshots`](Pipeline::run_with_snapshots) minus the snapshots,
    /// and guaranteed to produce an identical map (both share
    /// [`run_inner`](Pipeline::run_inner)).
    pub fn run(&self, seed: u64) -> Map {
        let (map, _snapshots) = self.run_inner(seed, false);
        map
    }

    /// Runs the pipeline for `seed`, returning the [`Map`] **and** a [`Snapshot`]
    /// captured after each pass (in pass order).
    ///
    /// The returned map is byte-identical to [`run`](Pipeline::run) for the same
    /// seed — snapshot capture only reads context state and never touches the
    /// RNG. The snapshot count equals the number of passes.
    pub fn run_with_snapshots(&self, seed: u64) -> (Map, Vec<Snapshot>) {
        self.run_inner(seed, true)
    }

    /// The single shared generation path behind both public entry points.
    ///
    /// When `collect` is `true`, a [`Snapshot`] is cloned out after each pass;
    /// otherwise the returned snapshot vec is empty. Crucially, the RNG forking
    /// and pass application are identical in both modes, so the resulting [`Map`]
    /// cannot diverge between `run` and `run_with_snapshots` (spec §7).
    fn run_inner(&self, seed: u64, collect: bool) -> (Map, Vec<Snapshot>) {
        // Fresh context: solid-wall canvas, nothing else.
        let mut ctx = GenContext {
            tiles: Grid::new(self.width, self.height, Tile::Wall),
            regions: Vec::new(),
            graph: ConnGraph::new(),
            blackboard: Blackboard::new(),
        };

        // The root stream all per-pass sub-streams fork from.
        let root = Rng::from_seed(seed);
        // Per-NAME occurrence counter: two passes sharing a name get `name#0`,
        // `name#1`, … — distinct, stable streams. A *different* name keeps its
        // own count, so inserting a pass never shifts another's occurrence.
        let mut occurrences: HashMap<&str, u32> = HashMap::new();

        let mut snapshots = Vec::new();

        for pass in &self.passes {
            let name = pass.name();
            // Read-then-increment this name's occurrence counter.
            let occurrence = occurrences.entry(name).or_insert(0);
            let key = format!("{}#{}", name, *occurrence);
            *occurrence += 1;

            // Hand the pass *only* its own dedicated sub-stream.
            let mut rng = root.fork(&key);
            pass.apply(&mut ctx, &mut rng);

            if collect {
                // Read-only capture of post-pass state. Does not touch `rng`.
                snapshots.push(Snapshot {
                    label: name.to_string(),
                    tiles: ctx.tiles.clone(),
                    regions: ctx.regions.clone(),
                    edges: ctx.graph.edges().to_vec(),
                });
            }
        }

        let map = Map {
            tiles: ctx.tiles,
            regions: ctx.regions,
            graph: ctx.graph,
            seed,
            width: self.width,
            height: self.height,
        };
        (map, snapshots)
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::cell::RefCell;
    use std::rc::Rc;

    /// A trivial pass that fills the entire grid with [`Tile::Floor`]. Draws no
    /// randomness.
    struct FillFloor;
    impl Pass for FillFloor {
        fn name(&self) -> &str {
            "FillFloor"
        }
        fn apply(&self, ctx: &mut GenContext, _rng: &mut Rng) {
            let (w, h) = (ctx.tiles.width() as i32, ctx.tiles.height() as i32);
            for y in 0..h {
                for x in 0..w {
                    ctx.tiles.set(Point::new(x, y), Tile::Floor);
                }
            }
        }
    }

    /// A pass that records its first `range` draw into a shared cell, so a test
    /// can observe the sub-stream it was given despite `apply(&self)` and `run`
    /// returning only a `Map`. `name` is configurable so we can build same-named
    /// and differently-named instances.
    struct RecordDraw {
        name: String,
        sink: Rc<RefCell<Vec<i32>>>,
    }
    impl Pass for RecordDraw {
        fn name(&self) -> &str {
            &self.name
        }
        fn apply(&self, _ctx: &mut GenContext, rng: &mut Rng) {
            let v = rng.range(0, 1_000_000);
            self.sink.borrow_mut().push(v);
        }
    }

    /// A no-draw pass that does not touch the RNG or the context — used to verify
    /// that inserting it between two passes doesn't shift their streams.
    struct NoOp;
    impl Pass for NoOp {
        fn name(&self) -> &str {
            "NoOp"
        }
        fn apply(&self, _ctx: &mut GenContext, _rng: &mut Rng) {}
    }

    /// `add_region` assigns sequential ids equal to the region's index.
    #[test]
    fn add_region_assigns_index_as_id() {
        let mut ctx = GenContext {
            tiles: Grid::new(4, 4, Tile::Wall),
            regions: Vec::new(),
            graph: ConnGraph::new(),
            blackboard: Blackboard::new(),
        };
        let a = ctx.add_region(RegionKind::Room, Rect::new(0, 0, 2, 2), vec![]);
        let b = ctx.add_region(RegionKind::Corridor, Rect::new(2, 0, 1, 4), vec![]);
        assert_eq!(a, RegionId(0));
        assert_eq!(b, RegionId(1));
        assert_eq!(ctx.regions[0].id, RegionId(0));
        assert_eq!(ctx.regions[1].id, RegionId(1));
    }

    /// A trivial fill pass produces the expected grid and a `Map` with matching
    /// seed and dimensions.
    #[test]
    fn trivial_fill_floor_pass() {
        let map = Pipeline::new(3, 2).then(FillFloor).run(0x1234);

        assert_eq!(map.seed, 0x1234);
        assert_eq!((map.width, map.height), (3, 2));
        // Every cell is Floor.
        assert!(map.tiles.iter().all(|(_, &t)| t == Tile::Floor));
    }

    /// Same seed → equal maps.
    #[test]
    fn run_is_deterministic() {
        let build = || Pipeline::new(8, 8).then(FillFloor);
        let a = build().run(777);
        let b = build().run(777);
        assert_eq!(a, b);
    }

    /// `run` and `run_with_snapshots` produce equal maps; one snapshot per pass.
    #[test]
    fn snapshots_match_run_and_count_passes() {
        let build = || {
            Pipeline::new(6, 6)
                .then(FillFloor)
                .then(NoOp)
                .then(FillFloor)
        };
        let plain = build().run(2024);
        let (snapped, snapshots) = build().run_with_snapshots(2024);

        assert_eq!(plain, snapped, "snapshotting must not change the map");
        assert_eq!(snapshots.len(), 3, "one snapshot per pass");
        assert_eq!(snapshots[0].label, "FillFloor");
        assert_eq!(snapshots[1].label, "NoOp");
        assert_eq!(snapshots[2].label, "FillFloor");
    }

    /// RNG isolation: inserting a pass `X` between `A` and `B` does not change
    /// the streams `A` and `B` receive. We compare the first draws of `A` and
    /// `B` across pipelines `[A, B]` and `[A, X, B]`.
    #[test]
    fn inserting_a_pass_does_not_reshuffle_others() {
        let seed = 0xFEED_FACE;

        // Pipeline [A, B].
        let a_sink1 = Rc::new(RefCell::new(Vec::new()));
        let b_sink1 = Rc::new(RefCell::new(Vec::new()));
        Pipeline::new(4, 4)
            .then(RecordDraw {
                name: "A".to_string(),
                sink: a_sink1.clone(),
            })
            .then(RecordDraw {
                name: "B".to_string(),
                sink: b_sink1.clone(),
            })
            .run(seed);

        // Pipeline [A, X, B] — X draws then discards (proving it's about keying,
        // not draw history).
        let a_sink2 = Rc::new(RefCell::new(Vec::new()));
        let b_sink2 = Rc::new(RefCell::new(Vec::new()));
        let x_sink = Rc::new(RefCell::new(Vec::new()));
        Pipeline::new(4, 4)
            .then(RecordDraw {
                name: "A".to_string(),
                sink: a_sink2.clone(),
            })
            .then(RecordDraw {
                name: "X".to_string(),
                sink: x_sink.clone(),
            })
            .then(RecordDraw {
                name: "B".to_string(),
                sink: b_sink2.clone(),
            })
            .run(seed);

        assert_eq!(
            a_sink1.borrow().as_slice(),
            a_sink2.borrow().as_slice(),
            "A's stream must be unchanged by inserting X"
        );
        assert_eq!(
            b_sink1.borrow().as_slice(),
            b_sink2.borrow().as_slice(),
            "B's stream must be unchanged by inserting X"
        );
    }

    /// Occurrence keying: two instances of the same-named pass receive different
    /// sub-streams (`name#0` vs `name#1`), so their recorded draws differ.
    #[test]
    fn same_name_instances_get_distinct_streams() {
        let sink = Rc::new(RefCell::new(Vec::new()));
        Pipeline::new(4, 4)
            .then(RecordDraw {
                name: "Dup".to_string(),
                sink: sink.clone(),
            })
            .then(RecordDraw {
                name: "Dup".to_string(),
                sink: sink.clone(),
            })
            .run(123);

        let draws = sink.borrow();
        assert_eq!(draws.len(), 2);
        assert_ne!(
            draws[0], draws[1],
            "occurrence #0 and #1 must draw from distinct streams"
        );
    }
}