Share host-aware completion across runtimes

crates/decodal-wasm/src/host_value.rs

@@ -0,0 +1,228 @@
+use decodal::{CompareOp, Constraint, HostValue, LiteralValue, PrimitiveType};
+use serde_json::{Map, Value};
+
+pub(crate) fn from_json(value: &Value) -> Result<HostValue, String> {
+    match value {
+        Value::Null => Err(String::from("null is not a Decodal host value")),
+        Value::Bool(value) => Ok(HostValue::bool(*value)),
+        Value::Number(value) => number(value),
+        Value::String(value) => Ok(HostValue::string(value)),
+        Value::Array(items) => items
+            .iter()
+            .enumerate()
+            .map(|(index, value)| {
+                from_json(value).map_err(|error| format!("array item {index}: {error}"))
+            })
+            .collect::<Result<Vec<_>, _>>()
+            .map(HostValue::array),
+        Value::Object(fields) => object(fields),
+    }
+}
+
+fn number(value: &serde_json::Number) -> Result<HostValue, String> {
+    if let Some(value) = value.as_i64() {
+        return Ok(HostValue::int(value));
+    }
+    if let Some(value) = value.as_u64() {
+        return i64::try_from(value)
+            .map(HostValue::int)
+            .map_err(|_| String::from("integer host value is outside the signed 64-bit range"));
+    }
+    value
+        .as_f64()
+        .filter(|value| value.is_finite())
+        .map(HostValue::float)
+        .ok_or_else(|| String::from("invalid numeric host value"))
+}
+
+fn object(fields: &Map<String, Value>) -> Result<HostValue, String> {
+    let Some(descriptor) = fields.get("$decodal") else {
+        return fields
+            .iter()
+            .map(|(name, value)| {
+                from_json(value)
+                    .map(|value| (name.clone(), value))
+                    .map_err(|error| format!("field `{name}`: {error}"))
+            })
+            .collect::<Result<Vec<_>, _>>()
+            .map(HostValue::object);
+    };
+
+    let descriptor = descriptor
+        .as_str()
+        .ok_or_else(|| String::from("`$decodal` must be a descriptor name"))?;
+    let constraints = parse_constraints(fields.get("constraints"))?;
+    let default = fields
+        .get("default")
+        .map(from_json)
+        .transpose()?
+        .map(Box::new);
+
+    match descriptor {
+        "String" | "Int" | "Float" | "Bool" => {
+            let primitive = match descriptor {
+                "String" => PrimitiveType::String,
+                "Int" => PrimitiveType::Int,
+                "Float" => PrimitiveType::Float,
+                "Bool" => PrimitiveType::Bool,
+                _ => unreachable!(),
+            };
+            let mut all_constraints = vec![Constraint::Type(primitive)];
+            all_constraints.extend(constraints);
+            Ok(HostValue::Abstract {
+                constraints: all_constraints,
+                default,
+            })
+        }
+        "Array" => {
+            let item = fields
+                .get("item")
+                .ok_or_else(|| String::from("Array descriptor requires `item`"))?;
+            Ok(HostValue::ArrayConstraint {
+                item: Box::new(from_json(item)?),
+                constraints,
+                default,
+            })
+        }
+        "Abstract" => Ok(HostValue::Abstract {
+            constraints,
+            default,
+        }),
+        name => Err(format!("unknown Decodal host descriptor `{name}`")),
+    }
+}
+
+fn parse_constraints(value: Option<&Value>) -> Result<Vec<Constraint>, String> {
+    let Some(value) = value else {
+        return Ok(Vec::new());
+    };
+    let items = value
+        .as_array()
+        .ok_or_else(|| String::from("`constraints` must be an array"))?;
+    items
+        .iter()
+        .enumerate()
+        .map(|(index, value)| {
+            parse_constraint(value).map_err(|error| format!("constraint {index}: {error}"))
+        })
+        .collect()
+}
+
+fn parse_constraint(value: &Value) -> Result<Constraint, String> {
+    let fields = value
+        .as_object()
+        .ok_or_else(|| String::from("constraint must be an object"))?;
+    let kind = required_string(fields, "kind")?;
+    match kind {
+        "type" => match required_string(fields, "value")? {
+            "String" => Ok(Constraint::Type(PrimitiveType::String)),
+            "Int" => Ok(Constraint::Type(PrimitiveType::Int)),
+            "Float" => Ok(Constraint::Type(PrimitiveType::Float)),
+            "Bool" => Ok(Constraint::Type(PrimitiveType::Bool)),
+            value => Err(format!("unknown primitive type `{value}`")),
+        },
+        "compare" => {
+            let operation = match required_string(fields, "op")? {
+                ">" => CompareOp::Gt,
+                ">=" => CompareOp::Gte,
+                "<" => CompareOp::Lt,
+                "<=" => CompareOp::Lte,
+                operation => return Err(format!("unknown comparison operator `{operation}`")),
+            };
+            let value = fields
+                .get("value")
+                .ok_or_else(|| String::from("compare constraint requires `value`"))?;
+            Ok(Constraint::Compare(operation, literal(value)?))
+        }
+        "regex" => Ok(Constraint::Regex(
+            required_string(fields, "value")?.to_owned(),
+        )),
+        "predicate" => Ok(Constraint::BuiltinPredicate(
+            required_string(fields, "value")?.to_owned(),
+        )),
+        kind => Err(format!("unknown constraint kind `{kind}`")),
+    }
+}
+
+fn literal(value: &Value) -> Result<LiteralValue, String> {
+    match value {
+        Value::String(value) => Ok(LiteralValue::String(value.clone())),
+        Value::Bool(value) => Ok(LiteralValue::Bool(*value)),
+        Value::Number(value) => match number(value)? {
+            HostValue::Int(value) => Ok(LiteralValue::Int(value)),
+            HostValue::Float(value) => Ok(LiteralValue::Float(value)),
+            _ => unreachable!(),
+        },
+        _ => Err(String::from("comparison value must be a primitive literal")),
+    }
+}
+
+fn required_string<'a>(fields: &'a Map<String, Value>, name: &str) -> Result<&'a str, String> {
+    fields
+        .get(name)
+        .and_then(Value::as_str)
+        .ok_or_else(|| format!("constraint requires string `{name}`"))
+}
+
+#[cfg(test)]
+mod tests {
+    use decodal::{Constraint, HostValue, LiteralValue, PrimitiveType};
+
+    use super::from_json;
+
+    #[test]
+    fn converts_plain_js_shaped_values() {
+        let value = serde_json::json!({
+            "frontmatter": { "draft": false },
+            "body": "# Hello",
+        });
+        assert_eq!(
+            from_json(&value).unwrap(),
+            HostValue::object([
+                ("body", HostValue::string("# Hello")),
+                (
+                    "frontmatter",
+                    HostValue::object([("draft", HostValue::bool(false))]),
+                ),
+            ])
+        );
+    }
+
+    #[test]
+    fn converts_schema_descriptors() {
+        let value = serde_json::json!({
+            "$decodal": "Array",
+            "item": {
+                "$decodal": "Int",
+                "constraints": [{ "kind": "compare", "op": ">", "value": 0 }],
+            },
+            "default": [1, 2],
+        });
+        assert_eq!(
+            from_json(&value).unwrap(),
+            HostValue::ArrayConstraint {
+                item: Box::new(HostValue::Abstract {
+                    constraints: vec![
+                        Constraint::Type(PrimitiveType::Int),
+                        Constraint::Compare(decodal::CompareOp::Gt, LiteralValue::Int(0)),
+                    ],
+                    default: None,
+                }),
+                constraints: Vec::new(),
+                default: Some(Box::new(HostValue::array([
+                    HostValue::int(1),
+                    HostValue::int(2),
+                ]))),
+            }
+        );
+    }
+
+    #[test]
+    fn rejects_null_values() {
+        assert!(
+            from_json(&serde_json::Value::Null)
+                .unwrap_err()
+                .contains("null")
+        );
+    }
+}

crates/decodal-wasm/src/lib.rs

@@ -1,25 +1,67 @@
-use std::collections::BTreeMap;
-
-use decodal::{
-    Data, Diagnostic, DiagnosticKind, EmptyLoader, Engine, ImportLoader, LoadedImport,
-    LoadedSource, SourceId, Span, format_diagnostic_with,
-};
+#[cfg(target_arch = "wasm32")]
+use decodal::HostEnvironment;
+use decodal::{Data, EmptyLoader, Engine, SourceId, format_diagnostic_with};
+#[cfg(target_arch = "wasm32")]
+use decodal_language_service::{CompletionKind, LanguageService};
 use wasm_bindgen::prelude::*;
 
+#[cfg(any(target_arch = "wasm32", test))]
+mod host_value;
+#[cfg(target_arch = "wasm32")]
+mod web_environment;
+
+#[cfg(target_arch = "wasm32")]
+use web_environment::JsEnvironment;
+
+/// Evaluates one standalone Decodal source with no host globals or imports.
 #[wasm_bindgen]
 pub fn evaluate(source: &str) -> String {
     encode_result(evaluate_inner(source))
 }
 
-#[wasm_bindgen(js_name = evaluateProject)]
-pub fn evaluate_project(entry: &str, files_json: &str) -> String {
-    encode_result(evaluate_project_inner(entry, files_json))
+/// A browser-facing language service configured entirely by its JavaScript host.
+///
+/// The host owns globals, import loading, and import completion. This keeps
+/// filesystem, network, and virtual-project policy outside the WASM package.
+#[cfg(target_arch = "wasm32")]
+#[wasm_bindgen(js_name = DecodalLanguageService)]
+pub struct WebLanguageService {
+    environment: JsEnvironment,
+}
+
+#[cfg(target_arch = "wasm32")]
+#[wasm_bindgen(js_class = DecodalLanguageService)]
+impl WebLanguageService {
+    #[wasm_bindgen(constructor)]
+    pub fn new(options: JsValue) -> Result<WebLanguageService, JsValue> {
+        Ok(Self {
+            environment: JsEnvironment::from_options(options)?,
+        })
+    }
+
+    /// Evaluates a source using the injected globals and import loader.
+    pub fn evaluate(&self, key: &str, name: &str, source: &str) -> String {
+        encode_result(evaluate_with_environment(
+            &self.environment,
+            key,
+            name,
+            source,
+        ))
+    }
+
+    /// Completes a source using the same injected environment as evaluation.
+    ///
+    /// Positions and returned ranges are UTF-16 offsets, matching browser
+    /// editors and the Language Server Protocol.
+    pub fn complete(&self, key: &str, source: &str, position: usize, explicit: bool) -> String {
+        encode_completion(&self.environment, key, source, position, explicit)
+    }
 }
 
 fn encode_result(result: Result<String, String>) -> String {
     match result {
-        Ok(output) => format!("{{\"ok\":true,\"output\":{}}}", json_string(&output)),
-        Err(error) => format!("{{\"ok\":false,\"error\":{}}}", json_string(&error)),
+        Ok(output) => serde_json::json!({ "ok": true, "output": output }).to_string(),
+        Err(error) => serde_json::json!({ "ok": false, "error": error }).to_string(),
     }
 }
 
@@ -40,103 +82,106 @@ fn evaluate_inner(source: &str) -> Result<String, String> {
     Ok(format_data(&data, 0))
 }
 
-fn evaluate_project_inner(entry: &str, files_json: &str) -> Result<String, String> {
-    let raw_files: BTreeMap<String, String> = serde_json::from_str(files_json)
-        .map_err(|error| format!("failed to read playground files: {error}"))?;
-    let mut files = BTreeMap::new();
-    for (path, source) in raw_files {
-        let path = normalize_path(&path).ok_or_else(|| format!("invalid file path `{path}`"))?;
-        files.insert(path, source);
-    }
-
-    let entry = normalize_path(entry).ok_or_else(|| format!("invalid entry path `{entry}`"))?;
-    let source = files
-        .get(&entry)
-        .cloned()
-        .ok_or_else(|| format!("entry file `{entry}` was not found"))?;
-
-    let mut engine = Engine::new(VirtualLoader { files });
-    let module = match engine.add_root_source(entry.clone(), entry.clone(), &source) {
+#[cfg(target_arch = "wasm32")]
+fn evaluate_with_environment(
+    environment: &JsEnvironment,
+    key: &str,
+    name: &str,
+    source: &str,
+) -> Result<String, String> {
+    let mut engine = environment
+        .create_engine()
+        .map_err(|diagnostic| diagnostic.message)?;
+    let module = match engine.add_root_source(key, name, source) {
         Ok(module) => module,
-        Err(error) => return Err(format_diagnostic_with_root(&error, &entry)),
+        Err(diagnostic) => return Err(engine.format_diagnostic(&diagnostic)),
     };
     let value = match engine.eval_module(module) {
         Ok(value) => value,
-        Err(error) => return Err(engine.format_diagnostic(&error)),
+        Err(diagnostic) => return Err(engine.format_diagnostic(&diagnostic)),
     };
     let data = match engine.materialize(&value) {
         Ok(data) => data,
-        Err(error) => return Err(engine.format_diagnostic(&error)),
+        Err(diagnostic) => return Err(engine.format_diagnostic(&diagnostic)),
     };
     Ok(format_data(&data, 0))
 }
 
-#[derive(Debug, Clone)]
-struct VirtualLoader {
-    files: BTreeMap<String, String>,
-}
-
-impl ImportLoader for VirtualLoader {
-    fn load(
-        &mut self,
-        current_key: Option<&str>,
-        specifier: &str,
-    ) -> decodal::Result<LoadedImport> {
-        let key = resolve_import(current_key, specifier).ok_or_else(|| {
-            Diagnostic::new(
-                DiagnosticKind::Import,
-                Span::default(),
-                format!("invalid import path `{specifier}`"),
-            )
-        })?;
-        let source = self.files.get(&key).cloned().ok_or_else(|| {
-            Diagnostic::new(
-                DiagnosticKind::Import,
-                Span::default(),
-                format!("import `{specifier}` resolved to `{key}`, but that file does not exist"),
-            )
-        })?;
-        Ok(LoadedImport::Source(LoadedSource {
-            key: key.clone(),
-            name: key,
-            source,
-        }))
-    }
-}
-
-fn resolve_import(current_key: Option<&str>, specifier: &str) -> Option<String> {
-    if specifier.starts_with('/') {
-        return normalize_path(specifier);
-    }
-
-    let mut base = String::new();
-    if let Some(current_key) = current_key {
-        if let Some((parent, _file)) = current_key.rsplit_once('/') {
-            base.push_str(parent);
-            base.push('/');
+#[cfg(target_arch = "wasm32")]
+fn encode_completion(
+    environment: &JsEnvironment,
+    key: &str,
+    source: &str,
+    position: usize,
+    explicit: bool,
+) -> String {
+    let byte_position = utf16_offset_to_byte(source, position);
+    let service = LanguageService::new(environment);
+    let completion = match service.complete(key, source, byte_position, explicit) {
+        Ok(completion) => completion,
+        Err(diagnostic) => {
+            return serde_json::json!({
+                "ok": false,
+                "error": diagnostic.message,
+            })
+            .to_string();
         }
-    }
-    base.push_str(specifier);
-    normalize_path(&base)
+    };
+    let completion = completion.map(|completion| {
+        let from = byte_offset_to_utf16(source, completion.from);
+        let options = completion
+            .items
+            .into_iter()
+            .map(|item| {
+                serde_json::json!({
+                    "label": item.label,
+                    "kind": completion_kind_name(item.kind),
+                    "detail": item.detail,
+                    "priority": item.priority,
+                })
+            })
+            .collect::<Vec<_>>();
+        serde_json::json!({ "from": from, "options": options })
+    });
+    serde_json::json!({ "ok": true, "completion": completion }).to_string()
 }
 
-fn normalize_path(path: &str) -> Option<String> {
-    let mut parts = Vec::new();
-    let normalized = path.replace('\\', "/");
-    for part in normalized.split('/') {
-        match part {
-            "" | "." => {}
-            ".." => {
-                parts.pop()?;
-            }
-            part => parts.push(part),
+#[cfg(target_arch = "wasm32")]
+fn completion_kind_name(kind: CompletionKind) -> &'static str {
+    match kind {
+        CompletionKind::Keyword => "keyword",
+        CompletionKind::Constant => "constant",
+        CompletionKind::Type => "type",
+        CompletionKind::Variable => "variable",
+        CompletionKind::Namespace => "namespace",
+        CompletionKind::Property => "property",
+        CompletionKind::File => "file",
+    }
+}
+
+#[cfg(any(target_arch = "wasm32", test))]
+fn utf16_offset_to_byte(source: &str, offset: usize) -> usize {
+    let mut utf16 = 0usize;
+    for (byte, ch) in source.char_indices() {
+        if utf16 >= offset {
+            return byte;
         }
+        let next = utf16 + ch.len_utf16();
+        if next > offset {
+            return byte;
+        }
+        utf16 = next;
     }
-    if parts.is_empty() {
-        None
-    } else {
-        Some(parts.join("/"))
+    source.len()
+}
+
+#[cfg(any(target_arch = "wasm32", test))]
+fn byte_offset_to_utf16(source: &str, mut offset: usize) -> usize {
+    offset = offset.min(source.len());
+    while !source.is_char_boundary(offset) {
+        offset = offset.saturating_sub(1);
     }
+    source[..offset].encode_utf16().count()
 }
 
 fn format_diagnostic_with_root(diagnostic: &decodal::Diagnostic, root_name: &str) -> String {
@@ -191,66 +236,28 @@ fn format_data(data: &Data, indent: usize) -> String {
 }
 
 fn json_string(value: &str) -> String {
-    let mut out = String::from("\"");
-    for ch in value.chars() {
-        match ch {
-            '"' => out.push_str("\\\""),
-            '\\' => out.push_str("\\\\"),
-            '\n' => out.push_str("\\n"),
-            '\r' => out.push_str("\\r"),
-            '\t' => out.push_str("\\t"),
-            ch if ch.is_control() => {
-                use core::fmt::Write;
-                let _ = write!(out, "\\u{:04x}", ch as u32);
-            }
-            ch => out.push(ch),
-        }
-    }
-    out.push('"');
-    out
+    serde_json::to_string(value).expect("strings are always JSON-serializable")
 }
 
 #[cfg(test)]
 mod tests {
-    use super::{evaluate_project_inner, normalize_path, resolve_import};
+    use super::{byte_offset_to_utf16, evaluate_inner, utf16_offset_to_byte};
 
     #[test]
-    fn normalizes_virtual_paths() {
+    fn evaluates_standalone_sources() {
         assert_eq!(
-            normalize_path("/schemas/../main.dcdl"),
-            Some("main.dcdl".into())
-        );
-        assert_eq!(normalize_path("../main.dcdl"), None);
-    }
-
-    #[test]
-    fn resolves_imports_relative_to_current_file() {
-        assert_eq!(
-            resolve_import(Some("schemas/service.dcdl"), "./types.dcdl"),
-            Some("schemas/types.dcdl".into())
+            evaluate_inner("value = 1;").unwrap(),
+            "{\n  \"value\": 1\n}"
         );
     }
 
     #[test]
-    fn evaluates_project_imports() {
-        let files = r#"{
-            "main.dcdl":"let dep = import \"./schemas/service.dcdl\"; in dep.Service & { port = 9443; }",
-            "schemas/service.dcdl":"Service = { name = String default \"api\"; port = Int & > 443 default 8443; }"
-        }"#;
-        let output = evaluate_project_inner("main.dcdl", files).unwrap();
-        assert!(output.contains("\"port\": 9443"));
-    }
-
-    #[test]
-    fn project_diagnostics_use_virtual_file_names() {
-        let files = r#"{
-            "main.dcdl":"let dep = import \"./schemas/service.dcdl\"; in dep.Service & { port = 80; }",
-            "schemas/service.dcdl":"Service = { port = Int & > 443 default 8443; }"
-        }"#;
-        let error = evaluate_project_inner("main.dcdl", files).unwrap_err();
-        assert!(error.contains("main.dcdl:"));
-        assert!(error.contains("schemas/service.dcdl:"));
-        assert!(!error.contains("source 0:"));
-        assert!(!error.contains("source 1:"));
+    fn converts_web_utf16_offsets() {
+        let source = "a😀β";
+        assert_eq!(utf16_offset_to_byte(source, 0), 0);
+        assert_eq!(utf16_offset_to_byte(source, 1), 1);
+        assert_eq!(utf16_offset_to_byte(source, 3), 5);
+        assert_eq!(byte_offset_to_utf16(source, 5), 3);
+        assert_eq!(byte_offset_to_utf16(source, source.len()), 4);
     }
 }

crates/decodal-wasm/src/web_environment.rs

@@ -0,0 +1,209 @@
+use std::collections::BTreeMap;
+
+use decodal::{
+    Diagnostic, DiagnosticKind, Engine, HostEnvironment, HostValue, ImportCandidate, ImportLoader,
+    LoadedImport, Span,
+};
+use js_sys::{Function, Reflect};
+use serde_json::Value;
+use wasm_bindgen::{JsCast, JsValue};
+
+use crate::host_value;
+
+pub(crate) struct JsEnvironment {
+    globals: BTreeMap<String, HostValue>,
+    load_import: Option<Function>,
+    complete_import: Option<Function>,
+}
+
+impl JsEnvironment {
+    pub(crate) fn from_options(options: JsValue) -> Result<Self, JsValue> {
+        if !options.is_null() && !options.is_undefined() && !options.is_object() {
+            return Err(JsValue::from_str(
+                "DecodalLanguageService options must be an object",
+            ));
+        }
+
+        let globals = property(&options, "globals")?;
+        let globals = if globals.is_null() || globals.is_undefined() {
+            BTreeMap::new()
+        } else {
+            let globals: Value = serde_wasm_bindgen::from_value(globals).map_err(|error| {
+                JsValue::from_str(&format!("failed to read `globals`: {error}"))
+            })?;
+            let globals = globals.as_object().ok_or_else(|| {
+                JsValue::from_str("DecodalLanguageService `globals` must be an object")
+            })?;
+            globals
+                .iter()
+                .map(|(name, value)| {
+                    host_value::from_json(value)
+                        .map(|value| (name.clone(), value))
+                        .map_err(|error| {
+                            JsValue::from_str(&format!("invalid global `{name}`: {error}"))
+                        })
+                })
+                .collect::<Result<BTreeMap<_, _>, _>>()?
+        };
+
+        Ok(Self {
+            globals,
+            load_import: optional_function(&options, "loadImport")?,
+            complete_import: optional_function(&options, "completeImport")?,
+        })
+    }
+}
+
+impl HostEnvironment for JsEnvironment {
+    type Loader = JsLoader;
+
+    fn create_loader(&self) -> Self::Loader {
+        JsLoader {
+            load_import: self.load_import.clone(),
+            complete_import: self.complete_import.clone(),
+        }
+    }
+
+    fn configure_engine(&self, engine: &mut Engine<Self::Loader>) -> decodal::Result<()> {
+        for (name, value) in &self.globals {
+            engine.bind_global(name, value.clone())?;
+        }
+        Ok(())
+    }
+}
+
+pub(crate) struct JsLoader {
+    load_import: Option<Function>,
+    complete_import: Option<Function>,
+}
+
+impl ImportLoader for JsLoader {
+    fn load(
+        &mut self,
+        current_key: Option<&str>,
+        specifier: &str,
+    ) -> decodal::Result<LoadedImport> {
+        let callback = self.load_import.as_ref().ok_or_else(|| {
+            import_error(format!(
+                "no JavaScript `loadImport` callback is configured for `{specifier}`"
+            ))
+        })?;
+        let current_key = current_key.map(JsValue::from_str).unwrap_or(JsValue::NULL);
+        let specifier = JsValue::from_str(specifier);
+        let loaded = callback
+            .call2(&JsValue::UNDEFINED, &current_key, &specifier)
+            .map_err(|error| import_error(js_error_message(error)))?;
+        let loaded: Value = serde_wasm_bindgen::from_value(loaded)
+            .map_err(|error| import_error(format!("invalid `loadImport` result: {error}")))?;
+        loaded_import(&loaded).map_err(import_error)
+    }
+
+    fn complete_import(
+        &mut self,
+        current_key: Option<&str>,
+        prefix: &str,
+    ) -> decodal::Result<Vec<ImportCandidate>> {
+        let Some(callback) = &self.complete_import else {
+            return Ok(Vec::new());
+        };
+        let current_key = current_key.map(JsValue::from_str).unwrap_or(JsValue::NULL);
+        let prefix = JsValue::from_str(prefix);
+        let candidates = callback
+            .call2(&JsValue::UNDEFINED, &current_key, &prefix)
+            .map_err(|error| import_error(js_error_message(error)))?;
+        let candidates: Value = serde_wasm_bindgen::from_value(candidates)
+            .map_err(|error| import_error(format!("invalid `completeImport` result: {error}")))?;
+        import_candidates(&candidates).map_err(import_error)
+    }
+}
+
+fn loaded_import(value: &Value) -> Result<LoadedImport, String> {
+    let fields = value
+        .as_object()
+        .ok_or_else(|| String::from("`loadImport` must return an object"))?;
+    let kind = string_field(fields, "kind")?;
+    let key = string_field(fields, "key")?;
+    match kind {
+        "source" => {
+            let source = string_field(fields, "source")?;
+            let name = fields.get("name").and_then(Value::as_str).unwrap_or(key);
+            Ok(LoadedImport::source(key, name, source))
+        }
+        "value" => {
+            let value = fields
+                .get("value")
+                .ok_or_else(|| String::from("value import requires `value`"))?;
+            let value = host_value::from_json(value)
+                .map_err(|error| format!("invalid imported value: {error}"))?;
+            Ok(LoadedImport::value(key, value))
+        }
+        kind => Err(format!("unknown `loadImport` result kind `{kind}`")),
+    }
+}
+
+fn import_candidates(value: &Value) -> Result<Vec<ImportCandidate>, String> {
+    value
+        .as_array()
+        .ok_or_else(|| String::from("`completeImport` must return an array"))?
+        .iter()
+        .enumerate()
+        .map(|(index, value)| match value {
+            Value::String(specifier) => Ok(ImportCandidate::new(specifier)),
+            Value::Object(fields) => {
+                let mut candidate = ImportCandidate::new(string_field(fields, "specifier")?);
+                if let Some(detail) = fields.get("detail") {
+                    let detail = detail.as_str().ok_or_else(|| {
+                        format!("import candidate {index} `detail` must be a string")
+                    })?;
+                    candidate = candidate.with_detail(detail);
+                }
+                Ok(candidate)
+            }
+            _ => Err(format!(
+                "import candidate {index} must be a string or object"
+            )),
+        })
+        .collect()
+}
+
+fn string_field<'a>(
+    fields: &'a serde_json::Map<String, Value>,
+    name: &str,
+) -> Result<&'a str, String> {
+    fields
+        .get(name)
+        .and_then(Value::as_str)
+        .ok_or_else(|| format!("`loadImport` result requires string `{name}`"))
+}
+
+fn property(options: &JsValue, name: &str) -> Result<JsValue, JsValue> {
+    if options.is_null() || options.is_undefined() {
+        return Ok(JsValue::UNDEFINED);
+    }
+    Reflect::get(options, &JsValue::from_str(name))
+}
+
+fn optional_function(options: &JsValue, name: &str) -> Result<Option<Function>, JsValue> {
+    let value = property(options, name)?;
+    if value.is_null() || value.is_undefined() {
+        return Ok(None);
+    }
+    value
+        .dyn_into::<Function>()
+        .map(Some)
+        .map_err(|_| JsValue::from_str(&format!("`{name}` must be a function")))
+}
+
+fn js_error_message(value: JsValue) -> String {
+    if let Some(message) = value.as_string() {
+        return message;
+    }
+    Reflect::get(&value, &JsValue::from_str("message"))
+        .ok()
+        .and_then(|message| message.as_string())
+        .unwrap_or_else(|| String::from("JavaScript import callback failed"))
+}
+
+fn import_error(message: impl Into<String>) -> Diagnostic {
+    Diagnostic::new(DiagnosticKind::Import, Span::default(), message)
+}