adam_web_ui/

build.rs

//! Parses adam-lang source into a live [`adam_lang::ParsedSheet`], formatting any failure as a
//! diagnostic instead of a bare error.

use crate::labels::{Labels, Renderer, format_adam_error, labels_from_cell_names};
use adam_lang::{AdamParser, ParsedSheet, TypeRegistry};

/// The result of parsing and building a sheet from adam-lang source.
///
/// `sheet_labels` is `None` only on parse failure. A successful parse that
/// then fails to propagate still returns the built sheet and labels alongside
/// the formatted error, matching how [`crate::SheetInspector`] already tolerates
/// propagate failures during cell edits.
pub struct BuildOutcome {
    /// The built [`ParsedSheet`] and its UI labels, if parsing succeeded.
    pub sheet_labels: Option<(ParsedSheet, Labels)>,
    /// A formatted rustc-style diagnostic, if parsing or propagation failed.
    pub error: Option<String>,
}

/// Builds a [`cel_parser::OpLookup`] with the CEL standard and Euclid libraries installed, so every
/// adam-lang source [`build_sheet`] parses has the same function set (`min`, `max`, `clamp`,
/// etc.) available.
///
/// Every source parsed through this function therefore has `cel-std` installed — a source
/// that deliberately relies on the standard library being *absent* cannot use this function
/// or [`build_sheet`]; construct an `AdamParser` directly with an empty `OpLookup` instead.
///
/// - Complexity: O(s²) in the number of installed signatures.
///
/// # Examples
/// ```
/// let lookup = adam_web_ui::build::op_lookup();
/// assert!(lookup.record_schema("Rect").is_some());
/// ```
pub fn op_lookup() -> cel_parser::OpLookup {
    let mut lookup = cel_parser::OpLookup::new();
    cel_std::install(&mut lookup);
    cel_euclid::install(&mut lookup);
    lookup
}

/// Builds the matching scalar and Euclid cell-type environment.
///
/// - Complexity: O(t) in the number of registered types.
///
/// # Examples
/// ```
/// let types = adam_web_ui::build::type_registry();
/// assert!(types.get("Rect").is_some());
/// ```
pub fn type_registry() -> TypeRegistry {
    let mut types = TypeRegistry::new();
    cel_euclid::register_adam_types(&mut types);
    types
}

/// Parses `source` as adam-lang, builds a `Sheet` and `Labels`, and propagates
/// once so initial derived values are populated. `file_name` is used only to
/// build diagnostic headers (e.g. `--> begin/examples/toy_example.adm2:8:11`),
/// not to locate `source` itself. `renderer` controls how a diagnostic is
/// formatted — pass [`Renderer::styled`] for a real terminal or [`Renderer::plain`]
/// for a context that can't display ANSI colors (e.g. a browser `<pre>` element).
///
/// - Complexity: O(n) in the length of `source` plus the cost of one `propagate()`.
pub fn build_sheet(source: &str, file_name: &str, renderer: &Renderer) -> BuildOutcome {
    let mut parser = AdamParser::new(type_registry(), op_lookup());
    let mut parsed = match parser.parse_str(source) {
        Ok(p) => p,
        Err(e) => {
            let msg = e.format_rustc_style(source, file_name, 1, renderer);
            return BuildOutcome {
                sheet_labels: None,
                error: Some(msg),
            };
        }
    };
    let labels = labels_from_cell_names(&parsed.sheet, &parsed.cell_names);
    match parsed.propagate() {
        Ok(()) => {
            parsed.clear_changed();
            BuildOutcome {
                sheet_labels: Some((parsed, labels)),
                error: None,
            }
        }
        Err(e) => {
            let msg = format_adam_error(&e, &parsed, source, file_name, renderer);
            BuildOutcome {
                sheet_labels: Some((parsed, labels)),
                error: Some(msg),
            }
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    /// The opted-in host builds registered fields, members, and typed closures.
    #[test]
    fn geometry_sheet_builds_in_opted_in_host() {
        let outcome = build_sheet(
            "sheet s { out x := (|p: Point2D| p.x)(Point2D { y: 2.0, x: 1.0 }); out n := min(3.0, 4.0); }",
            "geometry.adm2",
            &Renderer::plain(),
        );
        assert!(outcome.error.is_none(), "{:?}", outcome.error);
        let (parsed, _) = outcome.sheet_labels.unwrap();
        assert_eq!(*parsed.read::<f64>(parsed.cell_names["x"].0).unwrap(), 1.0);
        for actual in [
            include_str!("../../cel-euclid/examples/crop_straighten.adm2"),
            include_str!("../../cel-euclid/examples/pan_zoom.adm2"),
        ] {
            let outcome = build_sheet(actual, "geometry.adm2", &Renderer::plain());
            assert!(outcome.error.is_none(), "{:?}", outcome.error);
        }
    }

    const VALID_SOURCE: &str = r#"
        sheet s {
            cell a: f64 = 2.0;
            cell b: f64 = 3.0;
            cell c: f64;
            relationship {
                c := a * b;
                a := c / b;
                b := c / a;
            }
        }
    "#;

    #[test]
    fn build_sheet_valid_source_succeeds_with_no_error() {
        let outcome = build_sheet(VALID_SOURCE, "test.adm2", &Renderer::styled());
        assert!(outcome.sheet_labels.is_some());
        assert!(outcome.error.is_none());
    }

    #[test]
    fn build_sheet_parse_error_has_no_sheet_and_formatted_message() {
        let outcome = build_sheet("sheet s { cell x }", "test.adm2", &Renderer::styled());
        assert!(outcome.sheet_labels.is_none());
        let msg = outcome.error.expect("expected a parse error message");
        assert!(msg.contains("error"), "{msg}");
    }

    #[test]
    fn build_sheet_runtime_error_still_returns_sheet_and_message() {
        let source = "sheet s { cell x: i32 = 0; cell y: i32; relationship { y := 10i32 / x; } }";
        let outcome = build_sheet(source, "test.adm2", &Renderer::styled());
        assert!(
            outcome.sheet_labels.is_some(),
            "sheet should still be built after a propagate error"
        );
        assert!(outcome.error.is_some());
    }

    #[test]
    fn build_sheet_plain_renderer_parse_error_has_no_ansi_escape_codes() {
        let outcome = build_sheet("sheet s { cell x }", "test.adm2", &Renderer::plain());
        let msg = outcome.error.expect("expected a parse error message");
        assert!(
            !msg.contains('\u{1b}'),
            "expected no ANSI escapes, got: {msg}"
        );
    }

    #[test]
    fn build_sheet_plain_renderer_runtime_error_has_no_ansi_escape_codes() {
        let source = "sheet s { cell x: i32 = 0; cell y: i32; relationship { y := 10i32 / x; } }";
        let outcome = build_sheet(source, "test.adm2", &Renderer::plain());
        let msg = outcome.error.expect("expected a propagate error message");
        assert!(
            !msg.contains('\u{1b}'),
            "expected no ANSI escapes, got: {msg}"
        );
    }

    #[test]
    fn build_sheet_cycle_names_both_relationships_bindings_in_the_backtrace() {
        // Two relationships forming an algebraic loop with no external source for
        // either cell: `x` needs `y` and `y` needs `x`, so `propagate` can't pick a
        // valid method assignment and returns a multi-span `Error::Cycle` backtrace
        // naming both bindings.
        let source = "sheet s { cell x: i32 = 0; cell y: i32 = 0; \
            relationship { x := y + 1i32; } relationship { y := x + 1i32; } }";
        let outcome = build_sheet(source, "test.adm2", &Renderer::plain());
        assert!(
            outcome.sheet_labels.is_some(),
            "sheet should still be built after a propagate error"
        );
        let msg = outcome.error.expect("expected a cycle error message");
        assert!(msg.contains("x :=") && msg.contains("y :="), "{msg}");
    }
}