mini_build/

source.rs

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

use crate::change::{Broadcaster, ChangeEvent, ChangeType};
use crate::css::{self, CssOptions, CssTool};
use crate::js::{self, JsOptions, JsTool};

/// Routes source-folder file changes to the pipeline that turns them into served output.
///
/// The watcher layer runs over *source folders only*. The designated output dir is never
/// watched and never a trigger: every pipeline below writes its own output, and a pipeline
/// that listened to its own output would re-trigger itself forever (the feedback-loop bug
/// this design fixes). Instead, after a build finishes, the pipeline broadcasts the reload
/// event for the output it wrote, so the browser still hot-swaps/reloads.
///
/// CSS and JS are each independently configured via an optional `(tool, options)` pair.
/// `options.bundle()` selects between two disjoint modes per language: bundle (a single
/// discovered/entry-driven output, rebuilt in full on any relevant change) or per-file
/// (every source file mirrored independently into the output dir).
///
/// `asset_folders` are a third, simpler kind of source: every file under one (any
/// extension, no transformation) is mirrored byte-identical into the output dir,
/// preserving its path relative to the asset folder — for hand-authored static files
/// (`index.html`, images) that should live outside the served/output dir as source,
/// same separation the CSS/JS pipelines already have, without needing a CSS/JS tool.
pub struct SourcePipeline {
    source_folders: Vec<PathBuf>,
    bundle_roots: Vec<PathBuf>,
    asset_folders: Vec<PathBuf>,
    output_dir: PathBuf,
    css_tool: Option<(CssTool, CssOptions)>,
    js_tool: Option<(JsTool, JsOptions)>,
    prune_output: bool,
    broadcaster: Broadcaster,
}

impl SourcePipeline {
    #[allow(clippy::too_many_arguments)]
    pub fn new(
        source_folders: Vec<PathBuf>,
        bundle_roots: Vec<PathBuf>,
        asset_folders: Vec<PathBuf>,
        output_dir: PathBuf,
        css_tool: Option<(CssTool, CssOptions)>,
        js_tool: Option<(JsTool, JsOptions)>,
        prune_output: bool,
        broadcaster: Broadcaster,
    ) -> Self {
        SourcePipeline {
            source_folders,
            bundle_roots,
            asset_folders,
            output_dir,
            css_tool,
            js_tool,
            prune_output,
            broadcaster,
        }
    }

    /// Rebuild every enabled output once, then prune stale output if configured.
    ///
    /// Runs at server startup. Never during live-reload — see [`Self::prune_stale_output`].
    pub fn full_build(&self) -> Result<(), SourceError> {
        let css_written = self.build_css_bundle()?;
        self.build_js_bundle()?;
        self.build_all_per_file()?;
        self.build_all_assets()?;

        if self.prune_output {
            self.prune_stale_output(css_written.as_deref())?;
        }

        Ok(())
    }

    /// Handle a single change event for `path` (which must be under a watched source
    /// folder or import root), rebuilding output as needed and broadcasting the reload
    /// event for whatever was written.
    pub fn process_change(&self, path: &Path, change_type: &ChangeType) -> Result<(), SourceError> {
        // Asset folders own any extension, so this check runs before the CSS/JS
        // dispatch below (which only fires for `ChangeType::Css`/`Script`) — an
        // asset folder file with one of those extensions is still a plain copy, not
        // a CSS/JS build input.
        if let Some(folder) = self.containing_asset_folder(path) {
            let output = self.mirror_output(folder, path)?;
            copy_asset(path, &output)?;
            self.broadcast_change(&output);
            return Ok(());
        }

        if change_type == &ChangeType::Css && self.is_input(path) {
            if let Some((_, options)) = &self.css_tool {
                let written = if options.is_bundle() {
                    self.build_css_bundle()?
                } else {
                    self.rebuild_css_file(path)?
                };
                if let Some(output) = written {
                    self.broadcast_change(&output);
                }
                return Ok(());
            }
        }

        if change_type == &ChangeType::Script && self.is_input(path) {
            if let Some((_, options)) = &self.js_tool {
                let written = if options.is_bundle() {
                    self.build_js_bundle()?
                } else {
                    self.rebuild_js_file(path)?
                };
                if let Some(output) = written {
                    self.broadcast_change(&output);
                }
                return Ok(());
            }
        }

        // No pipeline owns this file kind. Re-broadcast only genuine watched-input
        // changes so the client reloads and re-fetches whatever external builder produced
        // the output. The watcher never watches the output dir, so the ONLY paths that
        // reach here without being under a watched root are this pipeline's own broadcast
        // echoes (e.g. a rebuilt bundle) — re-broadcasting those would make the pipeline
        // loop on its own output forever, flooding the SSE stream (the `_mr` cycling bug).
        if self.is_input(path) {
            self.broadcaster.broadcast(ChangeEvent {
                path: path.to_path_buf(),
                change_type: change_type.clone(),
            });
        }
        Ok(())
    }

    /// Rebuild the single CSS bundle from every source folder, if CSS bundle mode is
    /// configured. Returns the output path it wrote, or `None` when bundle mode isn't
    /// configured or no CSS sources exist (nothing to produce).
    fn build_css_bundle(&self) -> Result<Option<PathBuf>, SourceError> {
        let Some((css_tool, options)) = &self.css_tool else {
            return Ok(None);
        };
        if !options.is_bundle() || !self.has_css_sources() {
            return Ok(None);
        }

        let output = self.output_dir.join(options.output_file_name());
        css::build_css_bundle(*css_tool, options, &self.source_folders, &output)
            .map_err(SourceError::Css)?;

        Ok(Some(output))
    }

    /// Rebuild the JS bundle from its configured entry point, if JS bundle mode is
    /// configured. Returns the output path it wrote, or `None` when bundle mode isn't
    /// configured.
    fn build_js_bundle(&self) -> Result<Option<PathBuf>, SourceError> {
        let Some((js_tool, options)) = &self.js_tool else {
            return Ok(None);
        };
        let (true, Some(entry)) = (options.is_bundle(), options.entry()) else {
            return Ok(None);
        };

        let name = options.output_file_name().unwrap_or("bundle.js");
        let output = self.output_dir.join(name);
        js::build_js_bundle(*js_tool, options, entry, &output).map_err(SourceError::Js)?;

        Ok(Some(output))
    }

    /// Process every file under every source folder through whichever per-file (i.e.
    /// non-bundle) pipeline claims its extension. Bundle-mode CSS/JS is handled
    /// separately by [`Self::build_css_bundle`]/[`Self::build_js_bundle`].
    /// Build every per-file-mode source, batching tool invocations rather than spawning
    /// one process per file.
    ///
    /// Sources are collected first and built after, which is the whole point: a process
    /// spawn costs roughly nineteen milliseconds against about five of actual
    /// transformation, so the number of invocations — not the number of files — is what a
    /// build's wall clock tracks.
    fn build_all_per_file(&self) -> Result<(), SourceError> {
        let mut css_pairs: Vec<(PathBuf, PathBuf)> = Vec::new();
        let mut js_pairs: Vec<(PathBuf, PathBuf)> = Vec::new();

        for folder in &self.source_folders {
            let files = list_files(folder).map_err(SourceError::Io)?;
            for file in files {
                if is_css(&file) {
                    if let Some((_, options)) = &self.css_tool {
                        if !options.is_bundle() {
                            let output = self.mirror_output(folder, &file)?;
                            css_pairs.push((file, output));
                        }
                    }
                } else if is_script(&file) {
                    if let Some((_, options)) = &self.js_tool {
                        if !options.is_bundle() {
                            let output = self.mirror_output(folder, &file)?;
                            js_pairs.push((file, output));
                        }
                    }
                }
            }
        }

        if let Some((css_tool, options)) = &self.css_tool {
            css::build_css_files(*css_tool, options, &css_pairs).map_err(SourceError::Css)?;
        }
        if let Some((js_tool, options)) = &self.js_tool {
            js::build_js_files(*js_tool, options, &js_pairs).map_err(SourceError::Js)?;
        }

        Ok(())
    }

    /// Rebuild a single changed CSS file into its mirrored output path (per-file mode
    /// only — bundle mode always rebuilds the whole bundle via [`Self::build_css_bundle`]).
    fn rebuild_css_file(&self, source: &Path) -> Result<Option<PathBuf>, SourceError> {
        let Some(folder) = self.containing_source_folder(source) else {
            return Ok(None);
        };
        if !is_css(source) {
            return Ok(None);
        }
        let Some((css_tool, options)) = &self.css_tool else {
            return Ok(None);
        };

        let output = self.mirror_output(folder, source)?;
        css::build_css_file(*css_tool, options, source, &output).map_err(SourceError::Css)?;
        Ok(Some(output))
    }

    /// Rebuild a single changed JS file into its mirrored output path (per-file mode
    /// only — bundle mode always rebuilds the whole bundle via [`Self::build_js_bundle`]).
    fn rebuild_js_file(&self, source: &Path) -> Result<Option<PathBuf>, SourceError> {
        let Some(folder) = self.containing_source_folder(source) else {
            return Ok(None);
        };
        if !is_script(source) {
            return Ok(None);
        }
        let Some((js_tool, options)) = &self.js_tool else {
            return Ok(None);
        };

        let output = self.mirror_output(folder, source)?;
        js::build_js_file(*js_tool, options, source, &output).map_err(SourceError::Js)?;
        Ok(Some(output))
    }

    /// Mirror every file under every asset folder into the output dir, byte-identical,
    /// preserving each file's path relative to its asset folder.
    fn build_all_assets(&self) -> Result<(), SourceError> {
        for folder in &self.asset_folders {
            let files = list_files(folder).map_err(SourceError::Io)?;
            for file in files {
                let output = self.mirror_output(folder, &file)?;
                copy_asset(&file, &output)?;
            }
        }
        Ok(())
    }

    /// The asset folder containing `path`, if any.
    fn containing_asset_folder(&self, path: &Path) -> Option<&PathBuf> {
        self.asset_folders
            .iter()
            .find(|folder| path.starts_with(folder))
    }

    /// The output path for `source`, mirroring its path relative to `folder` under the
    /// output dir.
    fn mirror_output(&self, folder: &Path, source: &Path) -> Result<PathBuf, SourceError> {
        let relative = source
            .strip_prefix(folder)
            .map_err(|_| SourceError::NotUnderSource(source.to_path_buf()))?;
        Ok(self.output_dir.join(relative))
    }

    /// Broadcast a reload event for `output`, deriving its change type from the output's
    /// own extension so the browser hot-swaps/reloads exactly as it would for that file.
    fn broadcast_change(&self, output: &Path) {
        self.broadcaster.broadcast(ChangeEvent {
            path: output.to_path_buf(),
            change_type: ChangeType::from_path(output),
        });
    }

    /// True when `path` lives under any watched root (a source folder, a CSS `@import`
    /// root, or an asset folder). These are the only paths the watcher emits, so an
    /// event whose path fails this check must be the pipeline's own output echo and
    /// must not be re-broadcast.
    fn is_input(&self, path: &Path) -> bool {
        self.source_folders
            .iter()
            .chain(self.bundle_roots.iter())
            .chain(self.asset_folders.iter())
            .any(|root| path.starts_with(root))
    }

    /// The source folder containing `path`, if any.
    fn containing_source_folder(&self, path: &Path) -> Option<&PathBuf> {
        self.source_folders
            .iter()
            .find(|folder| path.starts_with(folder))
    }

    /// True when at least one `.css` file exists under the source folders.
    fn has_css_sources(&self) -> bool {
        for folder in &self.source_folders {
            if walk_dir(folder).any(|path| is_css(&path)) {
                return true;
            }
        }
        false
    }

    /// The CSS bundle's output path, if CSS bundle mode is configured.
    fn css_bundle_output_path(&self) -> Option<PathBuf> {
        let (_, options) = self.css_tool.as_ref()?;
        if !options.is_bundle() {
            return None;
        }
        Some(self.output_dir.join(options.output_file_name()))
    }

    /// Remove stale output at build time, never during live-reload.
    ///
    /// The only output this server can own *by identity* is the CSS bundle file — a single
    /// exact path that no hand-written file shares. If bundling is enabled but no CSS
    /// sources remain, the leftover bundle is removed. Per-file outputs are deliberately
    /// NOT auto-pruned: their mirrored paths can coincide with hand-written files, and
    /// deleting files the server doesn't own is a surprise (A1) the caller can't opt into
    /// by accident.
    fn prune_stale_output(&self, css_written: Option<&Path>) -> Result<(), SourceError> {
        let Some(bundle) = self.css_bundle_output_path() else {
            return Ok(());
        };

        let wrote_bundle = css_written.is_some_and(|written| written == bundle);
        if wrote_bundle {
            return Ok(());
        }

        if std::fs::metadata(&bundle).is_err() {
            return Ok(());
        }

        std::fs::remove_file(&bundle).map_err(SourceError::Io)?;
        eprintln!("pruned stale css bundle output: {}", bundle.display());
        Ok(())
    }
}

/// Why [`SourcePipeline`] could not produce output for a change or build.
#[derive(Debug)]
pub enum SourceError {
    /// The CSS tool step failed.
    Css(css::CssError),
    /// The JS tool step failed.
    Js(js::JsError),
    /// A filesystem operation failed.
    Io(std::io::Error),
    /// A changed path was not under the source folder claimed to contain it.
    NotUnderSource(PathBuf),
}

impl std::fmt::Display for SourceError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            SourceError::Css(e) => write!(f, "css tool step failed: {e}"),
            SourceError::Js(e) => write!(f, "js tool step failed: {e}"),
            SourceError::Io(e) => write!(f, "io error: {e}"),
            SourceError::NotUnderSource(p) => {
                write!(f, "path not under any source folder: {}", p.display())
            }
        }
    }
}

impl std::error::Error for SourceError {}

/// True if `path` names a CSS file (by extension).
fn is_css(path: &Path) -> bool {
    path.extension().and_then(|e| e.to_str()) == Some("css")
}

/// True if `path` names a script the tool accepts (`js`/`mjs`).
fn is_script(path: &Path) -> bool {
    matches!(
        path.extension().and_then(|e| e.to_str()),
        Some("js" | "mjs")
    )
}

/// Copy `source` to `output` byte-identical, creating `output`'s parent directory if
/// needed — the flat-mirror operation asset folders use, with no transformation.
fn copy_asset(source: &Path, output: &Path) -> Result<(), SourceError> {
    if let Some(parent) = output.parent() {
        std::fs::create_dir_all(parent).map_err(SourceError::Io)?;
    }
    std::fs::copy(source, output).map_err(SourceError::Io)?;
    Ok(())
}

/// Recursively list every file under `dir`.
///
/// Bounded by the filesystem: `walk_dir` pushes directories onto a stack and terminates
/// when none remain — a directory tree is finite, so this loop always ends.
fn list_files(dir: &Path) -> std::io::Result<Vec<PathBuf>> {
    let mut files = Vec::new();
    let mut dirs = vec![dir.to_path_buf()];

    while let Some(current) = dirs.pop() {
        for entry in std::fs::read_dir(&current)? {
            let entry = entry?;
            let path = entry.path();
            if entry.file_type()?.is_dir() {
                dirs.push(path);
            } else {
                files.push(path);
            }
        }
    }

    Ok(files)
}

/// Synchronously walk `dir` and yield every file path. Used by the cheap existence check
/// in [`SourcePipeline::has_css_sources`] (runs at build boundaries, not per request).
fn walk_dir(dir: &Path) -> impl Iterator<Item = PathBuf> {
    let mut dirs = vec![dir.to_path_buf()];
    std::iter::from_fn(move || {
        while let Some(current) = dirs.pop() {
            let Ok(entries) = std::fs::read_dir(&current) else {
                continue;
            };
            for entry in entries.flatten() {
                let path = entry.path();
                if entry.file_type().is_ok_and(|t| t.is_dir()) {
                    dirs.push(path);
                } else {
                    return Some(path);
                }
            }
        }
        None
    })
}

#[cfg(test)]
#[path = "../tests/unit/source.rs"]
mod tests;