Add in an assert family of functions (#3132)

* Add in an `assert` family of functions

This will check values at runtime, allowing for users to ensure computed
values do not violate static constraints.

Signed-off-by: Paul R. Tagliamonte <paul@zoo.dev>

e2e/playwright/flow-tests.spec.ts

@@ -1064,7 +1064,7 @@ test.describe('Editor tests', () => {
       await page.keyboard.type('const sketch001 = start')
 
       // expect there to be six auto complete options
-      await expect(page.locator('.cm-completionLabel')).toHaveCount(6)
+      await expect(page.locator('.cm-completionLabel')).toHaveCount(8)
       // this makes sure we can accept a completion with click
       await page.getByText('startSketchOn').click()
       await page.keyboard.type("'XZ'")

src/wasm-lib/kcl/src/std/args.rs

@@ -125,6 +125,10 @@ impl Args {
         }))
     }
 
+    pub(crate) fn make_null_user_val(&self) -> Result<MemoryItem, KclError> {
+        self.make_user_val_from_json(serde_json::Value::Null)
+    }
+
     pub(crate) fn make_user_val_from_i64(&self, n: i64) -> Result<MemoryItem, KclError> {
         self.make_user_val_from_json(serde_json::Value::Number(serde_json::Number::from(n)))
     }

src/wasm-lib/kcl/src/std/assert.rs

@@ -0,0 +1,121 @@
+//! Standard library assert functions.
+
+use anyhow::Result;
+use derive_docs::stdlib;
+use schemars::JsonSchema;
+
+use crate::{
+    errors::{KclError, KclErrorDetails},
+    executor::MemoryItem,
+    std::Args,
+};
+
+async fn _assert(value: bool, message: &str, args: &Args) -> Result<(), KclError> {
+    if !value {
+        return Err(KclError::Type(KclErrorDetails {
+            message: format!("assert failed: {}", message),
+            source_ranges: vec![args.source_range],
+        }));
+    }
+    Ok(())
+}
+
+/// Check that the provided value is true, or raise a [KclError]
+/// with the provided description.
+pub async fn assert(args: Args) -> Result<MemoryItem, KclError> {
+    let (data, description): (bool, String) = args.get_data()?;
+    inner_assert(data, &description, &args).await?;
+    args.make_null_user_val()
+}
+
+/// Check a value at runtime, and raise an error if the argument provided
+/// is false.
+///
+/// ```no_run
+/// const myVar = true
+/// assert(myVar, "should always be true")
+/// ```
+#[stdlib {
+    name = "assert",
+}]
+async fn inner_assert(data: bool, message: &str, args: &Args) -> Result<(), KclError> {
+    _assert(data, message, args).await
+}
+
+pub async fn assert_lt(args: Args) -> Result<MemoryItem, KclError> {
+    let (left, right, description): (f64, f64, String) = args.get_data()?;
+    inner_assert_lt(left, right, &description, &args).await?;
+    args.make_null_user_val()
+}
+
+/// Check that a numerical value is less than to another at runtime,
+/// otherwise raise an error.
+///
+/// ```no_run
+/// assertLessThan(1, 2, "1 is less than 2")
+/// ```
+#[stdlib {
+    name = "assertLessThan",
+}]
+async fn inner_assert_lt(left: f64, right: f64, message: &str, args: &Args) -> Result<(), KclError> {
+    _assert(left < right, message, args).await
+}
+
+pub async fn assert_gt(args: Args) -> Result<MemoryItem, KclError> {
+    let (left, right, description): (f64, f64, String) = args.get_data()?;
+    inner_assert_gt(left, right, &description, &args).await?;
+    args.make_null_user_val()
+}
+
+/// Check that a numerical value is greater than another at runtime,
+/// otherwise raise an error.
+///
+/// ```no_run
+/// assertGreaterThan(2, 1, "2 is greater than 1")
+/// ```
+#[stdlib {
+    name = "assertGreaterThan",
+}]
+async fn inner_assert_gt(left: f64, right: f64, message: &str, args: &Args) -> Result<(), KclError> {
+    _assert(left > right, message, args).await
+}
+
+pub async fn assert_lte(args: Args) -> Result<MemoryItem, KclError> {
+    let (left, right, description): (f64, f64, String) = args.get_data()?;
+    inner_assert_lte(left, right, &description, &args).await?;
+    args.make_null_user_val()
+}
+
+/// Check that a numerical value is less than or equal to another at runtime,
+/// otherwise raise an error.
+///
+/// ```no_run
+/// assertLessThanOrEq(1, 2, "1 is less than 2")
+/// assertLessThanOrEq(1, 1, "1 is equal to 1")
+/// ```
+#[stdlib {
+    name = "assertLessThanOrEq",
+}]
+async fn inner_assert_lte(left: f64, right: f64, message: &str, args: &Args) -> Result<(), KclError> {
+    _assert(left <= right, message, args).await
+}
+
+pub async fn assert_gte(args: Args) -> Result<MemoryItem, KclError> {
+    let (left, right, description): (f64, f64, String) = args.get_data()?;
+    inner_assert_gte(left, right, &description, &args).await?;
+    args.make_null_user_val()
+}
+
+/// Check that a numerical value is greater than or equal to another at runtime,
+/// otherwise raise an error.
+///
+/// ```no_run
+/// assertGreaterThanOrEq(2, 1, "2 is greater than 1")
+/// assertGreaterThanOrEq(1, 1, "1 is equal to 1")
+/// ```
+#[stdlib {
+    name = "assertGreaterThanOrEq",
+}]
+async fn inner_assert_gte(left: f64, right: f64, message: &str, args: &Args) -> Result<(), KclError> {
+    _assert(left >= right, message, args).await
+}

src/wasm-lib/kcl/src/std/mod.rs

@@ -1,6 +1,7 @@
 //! Functions implemented for language execution.
 
 pub mod args;
+pub mod assert;
 pub mod chamfer;
 pub mod convert;
 pub mod extrude;
@@ -118,6 +119,11 @@ lazy_static! {
         Box::new(crate::std::math::Ln),
         Box::new(crate::std::math::ToDegrees),
         Box::new(crate::std::math::ToRadians),
+        Box::new(crate::std::assert::Assert),
+        Box::new(crate::std::assert::AssertLessThan),
+        Box::new(crate::std::assert::AssertGreaterThan),
+        Box::new(crate::std::assert::AssertLessThanOrEq),
+        Box::new(crate::std::assert::AssertGreaterThanOrEq),
     ];
 }