Remove just one enum (#1096)

# Problem

This is my proposal for fixing #1107 . I've only done it for one stdlib function, `tangentialArcTo` -- if y'all like it, I'll apply this idea to the rest of the stdlib.

Previously, if users want to put a tag on the arc, the function's parameters change type.

```
// Tag missing: first param is array
tangentialArcTo([x, y], %)
// Tag present: first param is object
tangentialArcTo({to: [x, y], tag: "myTag"}, %)
```

# Solution

My proposal in #1006 is that KCL should have optional values. This means we can change the stdlib `tangentialArcTo` function to use them. In this PR, the calls are now like

```
// Tag missing: first param is array
tangentialArcTo([x, y], %)
// Tag present: first param is array still, but we now pass a tag at the end.
tangentialArcTo([x, y], %, "myTag")
```

This adds an "option" type to KCL typesystem, but it's not really revealed to users (no KCL types are revealed to users right now, they write untyped code and only interact with types when they get type errors upon executing programs). Also adds a None type, which is the default case of the Optional enum.

src/wasm-lib/derive-docs/Cargo.toml

@@ -14,8 +14,10 @@ proc-macro = true
 
 [dependencies]
 convert_case = "0.6.0"
+once_cell = "1.18.0"
 proc-macro2 = "1"
 quote = "1"
+regex = "1.10"
 serde = { version = "1.0.193", features = ["derive"] }
 serde_tokenstream = "0.2"
 syn = { version = "2.0.39", features = ["full"] }

src/wasm-lib/derive-docs/src/lib.rs

@@ -1,15 +1,11 @@
-// Copyright 2023 Oxide Computer Company
-
-//! This package defines macro attributes associated with HTTP handlers. These
-//! attributes are used both to define an HTTP API and to generate an OpenAPI
-//! Spec (OAS) v3 document that describes the API.
-
 // Clippy's style advice is definitely valuable, but not worth the trouble for
 // automated enforcement.
 #![allow(clippy::style)]
 
 use convert_case::Casing;
+use once_cell::sync::Lazy;
 use quote::{format_ident, quote, quote_spanned, ToTokens};
+use regex::Regex;
 use serde::Deserialize;
 use serde_tokenstream::{from_tokenstream, Error};
 use syn::{
@@ -209,6 +205,18 @@ fn do_stdlib_inner(
             quote! {
                Vec<#ty_ident>
             }
+        } else if ty_string.starts_with("Option<") {
+            let ty_string = ty_string.trim_start_matches("Option<").trim_end_matches('>');
+            let ty_ident = format_ident!("{}", ty_string);
+            quote! {
+               Option<#ty_ident>
+            }
+        } else if let Some((inner_array_type, num)) = parse_array_type(&ty_string) {
+            let ty_string = inner_array_type.to_owned();
+            let ty_ident = format_ident!("{}", ty_string);
+            quote! {
+               [#ty_ident; #num]
+            }
         } else if ty_string.starts_with("Box<") {
             let ty_string = ty_string.trim_start_matches("Box<").trim_end_matches('>');
             let ty_ident = format_ident!("{}", ty_string);
@@ -222,10 +230,13 @@ fn do_stdlib_inner(
             }
         };
 
-        let ty_string = clean_type(&ty_string);
+        let ty_string = rust_type_to_openapi_type(&ty_string);
 
         if ty_string != "Args" {
-            let schema = if ty_ident.to_string().starts_with("Vec < ") {
+            let schema = if ty_ident.to_string().starts_with("Vec < ")
+                || ty_ident.to_string().starts_with("Option <")
+                || ty_ident.to_string().starts_with('[')
+            {
                 quote! {
                    <#ty_ident>::json_schema(&mut generator)
                 }
@@ -263,7 +274,7 @@ fn do_stdlib_inner(
             ret_ty_string.trim().to_string()
         };
         let ret_ty_ident = format_ident!("{}", ret_ty_string);
-        let ret_ty_string = clean_type(&ret_ty_string);
+        let ret_ty_string = rust_type_to_openapi_type(&ret_ty_string);
         quote! {
             Some(#docs_crate::StdLibFnArg {
                 name: "".to_string(),
@@ -488,15 +499,22 @@ impl Parse for ItemFnForSignature {
     }
 }
 
-fn clean_type(t: &str) -> String {
+fn rust_type_to_openapi_type(t: &str) -> String {
     let mut t = t.to_string();
     // Turn vecs into arrays.
+    // TODO: handle nested types
     if t.starts_with("Vec<") {
         t = t.replace("Vec<", "[").replace('>', "]");
     }
     if t.starts_with("Box<") {
         t = t.replace("Box<", "").replace('>', "");
     }
+    if t.starts_with("Option<") {
+        t = t.replace("Option<", "").replace('>', "");
+    }
+    if let Some((inner_type, _length)) = parse_array_type(&t) {
+        t = format!("[{inner_type}]")
+    }
 
     if t == "f64" {
         return "number".to_string();
@@ -507,6 +525,14 @@ fn clean_type(t: &str) -> String {
     }
 }
 
+fn parse_array_type(type_name: &str) -> Option<(&str, usize)> {
+    static RE: Lazy<Regex> = Lazy::new(|| Regex::new(r"\[([a-zA-Z0-9<>]+); ?(\d+)\]").unwrap());
+    let cap = RE.captures(type_name)?;
+    let inner_type = cap.get(1)?;
+    let length = cap.get(2)?.as_str().parse().ok()?;
+    Some((inner_type.as_str(), length))
+}
+
 #[cfg(test)]
 mod tests {
 
@@ -514,6 +540,19 @@ mod tests {
 
     use super::*;
 
+    #[test]
+    fn test_get_inner_array_type() {
+        for (expected, input) in [
+            (Some(("f64", 2)), "[f64;2]"),
+            (Some(("String", 2)), "[String; 2]"),
+            (Some(("Option<String>", 12)), "[Option<String>;12]"),
+            (Some(("Option<String>", 12)), "[Option<String>; 12]"),
+        ] {
+            let actual = parse_array_type(input);
+            assert_eq!(actual, expected);
+        }
+    }
+
     #[test]
     fn test_stdlib_line_to() {
         let (item, errors) = do_stdlib(
@@ -608,4 +647,46 @@ mod tests {
         assert!(errors.is_empty());
         expectorate::assert_contents("tests/box.gen", &openapitor::types::get_text_fmt(&item).unwrap());
     }
+
+    #[test]
+    fn test_stdlib_option() {
+        let (item, errors) = do_stdlib(
+            quote! {
+                name = "show",
+            },
+            quote! {
+                fn inner_show(
+                    /// The args to do shit to.
+                    args: Option<f64>
+                ) -> Box<f64> {
+                    args
+                }
+            },
+        )
+        .unwrap();
+
+        assert!(errors.is_empty());
+        expectorate::assert_contents("tests/option.gen", &openapitor::types::get_text_fmt(&item).unwrap());
+    }
+
+    #[test]
+    fn test_stdlib_array() {
+        let (item, errors) = do_stdlib(
+            quote! {
+                name = "show",
+            },
+            quote! {
+                fn inner_show(
+                    /// The args to do shit to.
+                    args: [f64; 2]
+                ) -> Box<f64> {
+                    args
+                }
+            },
+        )
+        .unwrap();
+
+        assert!(errors.is_empty());
+        expectorate::assert_contents("tests/array.gen", &openapitor::types::get_text_fmt(&item).unwrap());
+    }
 }

src/wasm-lib/derive-docs/tests/array.gen

@@ -0,0 +1,82 @@
+#[allow(non_camel_case_types, missing_docs)]
+#[doc = "Std lib function: show"]
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, schemars :: JsonSchema, ts_rs :: TS)]
+#[ts(export)]
+pub(crate) struct Show {}
+
+#[allow(non_upper_case_globals, missing_docs)]
+#[doc = "Std lib function: show"]
+pub(crate) const Show: Show = Show {};
+fn boxed_show(
+    args: crate::std::Args,
+) -> std::pin::Pin<
+    Box<
+        dyn std::future::Future<
+            Output = anyhow::Result<crate::executor::MemoryItem, crate::errors::KclError>,
+        >,
+    >,
+> {
+    Box::pin(show(args))
+}
+
+impl crate::docs::StdLibFn for Show {
+    fn name(&self) -> String {
+        "show".to_string()
+    }
+
+    fn summary(&self) -> String {
+        "".to_string()
+    }
+
+    fn description(&self) -> String {
+        "".to_string()
+    }
+
+    fn tags(&self) -> Vec<String> {
+        vec![]
+    }
+
+    fn args(&self) -> Vec<crate::docs::StdLibFnArg> {
+        let mut settings = schemars::gen::SchemaSettings::openapi3();
+        settings.inline_subschemas = true;
+        let mut generator = schemars::gen::SchemaGenerator::new(settings);
+        vec![crate::docs::StdLibFnArg {
+            name: "args".to_string(),
+            type_: "[number]".to_string(),
+            schema: <[f64; 2usize]>::json_schema(&mut generator),
+            required: true,
+        }]
+    }
+
+    fn return_value(&self) -> Option<crate::docs::StdLibFnArg> {
+        let mut settings = schemars::gen::SchemaSettings::openapi3();
+        settings.inline_subschemas = true;
+        let mut generator = schemars::gen::SchemaGenerator::new(settings);
+        Some(crate::docs::StdLibFnArg {
+            name: "".to_string(),
+            type_: "number".to_string(),
+            schema: f64::json_schema(&mut generator),
+            required: true,
+        })
+    }
+
+    fn unpublished(&self) -> bool {
+        false
+    }
+
+    fn deprecated(&self) -> bool {
+        false
+    }
+
+    fn std_lib_fn(&self) -> crate::std::StdFn {
+        boxed_show
+    }
+
+    fn clone_box(&self) -> Box<dyn crate::docs::StdLibFn> {
+        Box::new(self.clone())
+    }
+}
+
+fn inner_show(#[doc = r" The args to do shit to."] args: [f64; 2]) -> Box<f64> {
+    args
+}

src/wasm-lib/derive-docs/tests/option.gen

@@ -0,0 +1,82 @@
+#[allow(non_camel_case_types, missing_docs)]
+#[doc = "Std lib function: show"]
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, schemars :: JsonSchema, ts_rs :: TS)]
+#[ts(export)]
+pub(crate) struct Show {}
+
+#[allow(non_upper_case_globals, missing_docs)]
+#[doc = "Std lib function: show"]
+pub(crate) const Show: Show = Show {};
+fn boxed_show(
+    args: crate::std::Args,
+) -> std::pin::Pin<
+    Box<
+        dyn std::future::Future<
+            Output = anyhow::Result<crate::executor::MemoryItem, crate::errors::KclError>,
+        >,
+    >,
+> {
+    Box::pin(show(args))
+}
+
+impl crate::docs::StdLibFn for Show {
+    fn name(&self) -> String {
+        "show".to_string()
+    }
+
+    fn summary(&self) -> String {
+        "".to_string()
+    }
+
+    fn description(&self) -> String {
+        "".to_string()
+    }
+
+    fn tags(&self) -> Vec<String> {
+        vec![]
+    }
+
+    fn args(&self) -> Vec<crate::docs::StdLibFnArg> {
+        let mut settings = schemars::gen::SchemaSettings::openapi3();
+        settings.inline_subschemas = true;
+        let mut generator = schemars::gen::SchemaGenerator::new(settings);
+        vec![crate::docs::StdLibFnArg {
+            name: "args".to_string(),
+            type_: "number".to_string(),
+            schema: <Option<f64>>::json_schema(&mut generator),
+            required: true,
+        }]
+    }
+
+    fn return_value(&self) -> Option<crate::docs::StdLibFnArg> {
+        let mut settings = schemars::gen::SchemaSettings::openapi3();
+        settings.inline_subschemas = true;
+        let mut generator = schemars::gen::SchemaGenerator::new(settings);
+        Some(crate::docs::StdLibFnArg {
+            name: "".to_string(),
+            type_: "number".to_string(),
+            schema: f64::json_schema(&mut generator),
+            required: true,
+        })
+    }
+
+    fn unpublished(&self) -> bool {
+        false
+    }
+
+    fn deprecated(&self) -> bool {
+        false
+    }
+
+    fn std_lib_fn(&self) -> crate::std::StdFn {
+        boxed_show
+    }
+
+    fn clone_box(&self) -> Box<dyn crate::docs::StdLibFn> {
+        Box::new(self.clone())
+    }
+}
+
+fn inner_show(#[doc = r" The args to do shit to."] args: Option<f64>) -> Box<f64> {
+    args
+}