ssg 0.0.44

// Copyright © 2023 - 2026 Static Site Generator (SSG). All rights reserved.
// SPDX-License-Identifier: Apache-2.0 OR MIT

//! Dev-server glue (issue #526) — wires [`EventWatcher`] → [`DepGraph`]
//! → [`HmrBroadcaster`] into one loop.
//!
//! Lifted out of `bin/dev.rs` so each policy decision (classify a change,
//! pick the HMR frame type, resolve invalidated outputs) is unit-testable
//! without spawning threads or binding a port.
//!
//! ```text
//!   FS event   ──▶ ChangeBatch ──▶ process_batch ──▶ HmrMessage ──▶ tabs
//!     (notify)        (debounced)    (DepGraph)        (broadcaster)
//! ```
//!
//! See [`process_batch`] for the policy table and [`run_dev_loop`] for
//! the integration point.

use std::path::{Path, PathBuf};

use crate::core_group::depgraph::DepGraph;
use crate::server_group::event_watch::{ChangeBatch, EventWatcher};
use crate::server_group::hmr::{HmrBroadcaster, HmrMessage};
use crate::server_group::watch::{classify_change, ChangeKind};

/// Outcome of processing one debounced batch — the frame (if any) the
/// caller should broadcast and the page paths invalidated by the batch
/// (used by the rebuild step).
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct BatchOutcome {
    /// The HMR frame to push to every connected tab. `None` if every
    /// path in the batch was classified [`ChangeKind::Other`] (e.g.
    /// editor backup, build artefact under the watched root).
    pub frame: Option<HmrMessage>,
    /// Page output paths the dep graph says were invalidated. These
    /// drive the rebuild scope.
    pub invalidated_outputs: Vec<PathBuf>,
}

/// Policy table: turn a [`ChangeBatch`] + a [`DepGraph`] into the right
/// HMR frame.
///
/// Rules:
/// * **All CSS** → `hmr-css` (AC2) — list every changed `.css` path.
/// * **Markdown / HTML content (no templates)** → `hmr-html` (AC3) —
///   list invalidated output URLs from the dep graph.
/// * **Template touched** → `hmr-html` if the dep graph resolves
///   affected pages (AC4); falls back to `reload` if no pages are
///   linked (e.g. a brand-new template).
/// * **Mixed CSS + content** → `reload` to keep the protocol simple.
/// * **All other** (data, fonts, images that aren't fingerprinted) →
///   `reload` so the user always sees the latest build.
///
/// # Examples
///
/// ```rust
/// use ssg::dev_server::process_batch;
/// use ssg::depgraph::DepGraph;
/// use ssg::event_watch::ChangeBatch;
/// use std::path::Path;
///
/// let batch = ChangeBatch { paths: vec![] };
/// let outcome = process_batch(&batch, &DepGraph::new(), Path::new("build"));
/// assert!(outcome.frame.is_none());
/// ```
#[must_use]
pub fn process_batch(
    batch: &ChangeBatch,
    graph: &DepGraph,
    output_dir: &Path,
) -> BatchOutcome {
    if batch.is_empty() {
        return BatchOutcome {
            frame: None,
            invalidated_outputs: Vec::new(),
        };
    }

    let mut css_paths: Vec<String> = Vec::new();
    let mut content_or_template = false;
    let mut other = false;

    for path in &batch.paths {
        match classify_change(path) {
            ChangeKind::Css => {
                css_paths.push(path.to_string_lossy().into_owned());
            }
            ChangeKind::Content | ChangeKind::Template => {
                content_or_template = true;
            }
            ChangeKind::Other => {
                other = true;
            }
        }
    }

    let outputs = graph.invalidated_outputs(&batch.paths);
    let url_paths: Vec<String> = outputs
        .iter()
        .map(|p| output_to_url(p, output_dir))
        .collect();

    let frame = match (!css_paths.is_empty(), content_or_template, other) {
        // CSS only (no content/template/other) → hmr-css.
        (true, false, false) => Some(HmrMessage::css(css_paths)),
        // Pure content/template change (no CSS, no other) → hmr-html
        // with the dep-graph-resolved page list. If the graph has no
        // edges yet, the URL list is empty — fall back to reload.
        (false, true, false) => {
            if url_paths.is_empty() {
                Some(HmrMessage::reload())
            } else {
                Some(HmrMessage::html(url_paths))
            }
        }
        // Anything mixed, or only "other" → full reload.
        _ => Some(HmrMessage::reload()),
    };

    BatchOutcome {
        frame,
        invalidated_outputs: outputs,
    }
}

/// Convert an output filesystem path (e.g. `build/blog/foo/index.html`)
/// into the URL the browser tab is loaded at (`/blog/foo/`).
///
/// Strips the `output_dir` prefix and the trailing `index.html` so
/// directory-style URLs match the path the browser is sitting at.
///
/// # Examples
///
/// ```rust
/// use ssg::dev_server::output_to_url;
/// use std::path::Path;
///
/// let url = output_to_url(Path::new("build/blog/foo/index.html"), Path::new("build"));
/// assert_eq!(url, "/blog/foo/");
/// ```
#[must_use]
pub fn output_to_url(output: &Path, output_dir: &Path) -> String {
    let rel = output.strip_prefix(output_dir).unwrap_or(output);
    let mut s = rel.to_string_lossy().replace('\\', "/");
    // Strip trailing index.html to match clean URLs.
    for trailing in ["index.html", "index.htm"] {
        if let Some(stripped) = s.strip_suffix(trailing) {
            s = stripped.to_string();
            break;
        }
    }
    if !s.starts_with('/') {
        s.insert(0, '/');
    }
    s
}

/// Pumps debounced batches off `watcher` and broadcasts each frame.
///
/// The closure `rebuild` is called once per batch with the invalidated
/// output list so callers can plug in the incremental pipeline.
///
/// Returns the number of batches processed before the watcher closed,
/// which is useful for tests that inject a finite event stream.
///
/// # Examples
///
/// ```ignore
/// // Requires a real EventWatcher + HmrBroadcaster bound to a port,
/// // which a doctest sandbox can't safely set up. See the `dev` binary
/// // (`src/bin/dev.rs`) for a runnable wiring.
/// use ssg::dev_server::run_dev_loop;
/// ```
pub fn run_dev_loop<F: FnMut(&[PathBuf])>(
    watcher: &EventWatcher,
    graph: &DepGraph,
    broadcaster: &HmrBroadcaster,
    output_dir: &Path,
    mut rebuild: F,
) -> usize {
    let mut processed = 0usize;
    while let Some(batch) = watcher.recv() {
        let outcome = process_batch(&batch, graph, output_dir);
        rebuild(&outcome.invalidated_outputs);
        if let Some(frame) = outcome.frame {
            let _ = broadcaster.broadcast(&frame);
        }
        processed += 1;
    }
    processed
}

#[cfg(test)]
#[allow(clippy::unwrap_used, clippy::expect_used)]
mod tests {
    use super::*;

    fn pb(s: &str) -> PathBuf {
        PathBuf::from(s)
    }

    #[test]
    fn empty_batch_yields_no_frame() {
        let batch = ChangeBatch { paths: vec![] };
        let graph = DepGraph::new();
        let out = process_batch(&batch, &graph, Path::new("build"));
        assert!(out.frame.is_none());
        assert!(out.invalidated_outputs.is_empty());
    }

    #[test]
    fn pure_css_batch_yields_hmr_css_frame() {
        let batch = ChangeBatch {
            paths: vec![pb("assets/style.css")],
        };
        let graph = DepGraph::new();
        let out = process_batch(&batch, &graph, Path::new("build"));
        let frame = out.frame.expect("frame");
        let json = frame.to_json();
        assert!(json.contains("hmr-css"));
        assert!(json.contains("assets/style.css"));
    }

    #[test]
    fn pure_content_batch_without_graph_falls_back_to_reload() {
        // No edges in the graph => empty invalidated list => reload.
        let batch = ChangeBatch {
            paths: vec![pb("content/blog/foo.md")],
        };
        let graph = DepGraph::new();
        let out = process_batch(&batch, &graph, Path::new("build"));
        let json = out.frame.unwrap().to_json();
        assert!(json.contains("\"type\":\"reload\""));
    }

    #[test]
    fn mixed_css_and_content_batch_yields_reload() {
        let batch = ChangeBatch {
            paths: vec![pb("assets/style.css"), pb("content/foo.md")],
        };
        let graph = DepGraph::new();
        let out = process_batch(&batch, &graph, Path::new("build"));
        assert!(out.frame.unwrap().to_json().contains("reload"));
    }

    #[test]
    fn other_only_batch_yields_reload() {
        let batch = ChangeBatch {
            paths: vec![pb("data/config.json")],
        };
        let graph = DepGraph::new();
        let out = process_batch(&batch, &graph, Path::new("build"));
        assert!(out.frame.unwrap().to_json().contains("reload"));
    }

    #[test]
    fn output_to_url_strips_index_html_and_prefix() {
        let out = pb("build/blog/foo/index.html");
        let url = output_to_url(&out, Path::new("build"));
        assert_eq!(url, "/blog/foo/");
    }

    #[test]
    fn output_to_url_keeps_non_index_files() {
        let out = pb("build/feed.xml");
        let url = output_to_url(&out, Path::new("build"));
        assert_eq!(url, "/feed.xml");
    }

    #[test]
    fn output_to_url_handles_root_index() {
        let out = pb("build/index.html");
        let url = output_to_url(&out, Path::new("build"));
        assert_eq!(url, "/");
    }

    #[test]
    fn output_to_url_normalises_backslashes() {
        let out = pb("build\\blog\\index.html");
        // strip_prefix won't match because backslashes aren't a path
        // separator on Unix. Use a path that strip_prefix accepts.
        let url = output_to_url(&out, Path::new("build"));
        // The function still normalises any embedded backslashes.
        assert!(url.starts_with('/'));
        assert!(!url.contains('\\'));
    }
}