rdf_parsers/jsonld/

convert.rs

use std::collections::HashMap;
use std::future::Future;
use std::ops::Range;
use std::pin::Pin;

use rowan::SyntaxNode;

use crate::Spanned;
use crate::model::*;

use super::parser::{Lang, SyntaxKind};

type Node = SyntaxNode<Lang>;

// RDF/XSD constants
const RDF_TYPE: &str = "http://www.w3.org/1999/02/22-rdf-syntax-ns#type";
const RDF_FIRST: &str = "http://www.w3.org/1999/02/22-rdf-syntax-ns#first";
const RDF_REST: &str = "http://www.w3.org/1999/02/22-rdf-syntax-ns#rest";
const RDF_NIL: &str = "http://www.w3.org/1999/02/22-rdf-syntax-ns#nil";
const RDF_JSON: &str = "http://www.w3.org/1999/02/22-rdf-syntax-ns#JSON";
const XSD_STRING: &str = "http://www.w3.org/2001/XMLSchema#string";
const XSD_INTEGER: &str = "http://www.w3.org/2001/XMLSchema#integer";
const XSD_DOUBLE: &str = "http://www.w3.org/2001/XMLSchema#double";
const XSD_BOOLEAN: &str = "http://www.w3.org/2001/XMLSchema#boolean";

// ── Intermediate JSON-LD value representation ─────────────────────────────────

#[derive(Debug, Clone)]
pub enum JsonLdVal {
    /// Object carries its span so we can pass it as the triple span for nodes.
    /// Each member is `(key, key_span, val_span, value)` where `key_span` is
    /// the byte range of the key string token and `val_span` is the byte range
    /// of the value token/node in the source, enabling accurate predicate and
    /// object source-mapping.
    Object(
        Vec<(String, Range<usize>, Range<usize>, JsonLdVal)>,
        Range<usize>,
    ),
    Array(Vec<(JsonLdVal, Range<usize>)>),
    Str(String),
    Number(String),
    Bool(bool),
    Null,
    Invalid,
}

impl JsonLdVal {
    /// Look up a key inside an `Object`, returning the value or `None`.
    pub fn get(&self, key: &str) -> Option<&JsonLdVal> {
        if let JsonLdVal::Object(members, _) = self {
            members
                .iter()
                .find(|(k, _, _, _)| k == key)
                .map(|(_, _, _, v)| v)
        } else {
            None
        }
    }

    /// Return the contained string if this is a `Str` variant.
    pub fn as_str(&self) -> Option<&str> {
        if let JsonLdVal::Str(s) = self {
            Some(s.as_str())
        } else {
            None
        }
    }

    /// Return the contained bool if this is a `Bool` variant.
    pub fn as_bool(&self) -> Option<bool> {
        if let JsonLdVal::Bool(b) = self {
            Some(*b)
        } else {
            None
        }
    }

    /// Return the member slice if this is an `Object`.
    /// Each element is `(key, key_span, val_span, value)`.
    pub fn as_object(&self) -> Option<&[(String, Range<usize>, Range<usize>, JsonLdVal)]> {
        if let JsonLdVal::Object(members, _) = self {
            Some(members.as_slice())
        } else {
            None
        }
    }

    /// Return the item slice if this is an `Array`.
    /// Each element is `(value, span)`.
    pub fn as_array(&self) -> Option<&[(JsonLdVal, Range<usize>)]> {
        if let JsonLdVal::Array(items) = self {
            Some(items.as_slice())
        } else {
            None
        }
    }
}

// ── Context types ─────────────────────────────────────────────────────────────

#[derive(Debug, Clone, Default)]
pub struct TermDefinition {
    pub iri: Option<String>,
    pub type_mapping: Option<String>,
    pub language: Option<String>,
    pub container: Option<String>,
    pub reverse: bool,
}

/// The active context built up from all `@context` entries encountered during
/// JSON-LD processing.  Returned alongside the [`Turtle`] triples by
/// [`convert`] and [`convert_with_loader`].
#[derive(Debug, Clone, Default)]
pub struct ActiveContext {
    pub base: Option<String>,
    pub vocab: Option<String>,
    pub language: Option<String>,
    pub terms: HashMap<String, TermDefinition>,
}

// ── Context loader hook ───────────────────────────────────────────────────────

/// Hook for fetching remote JSON-LD context documents asynchronously.
///
/// Implement this trait to support `@context` values that are URLs.  The
/// `load` method receives the URL and should return the raw JSON-LD document
/// content as a string, or `None` if the document cannot be fetched.
///
/// # Example (sync wrapper)
/// ```rust,ignore
/// struct MyLoader;
/// impl ContextLoader for MyLoader {
///     fn load<'a>(&'a self, url: &'a str) -> Pin<Box<dyn Future<Output = Option<String>> + 'a>> {
///         Box::pin(async move { Some(fetch_remote(url).await) })
///     }
/// }
/// ```
pub trait ContextLoader {
    fn load<'a>(&'a mut self, url: &'a str) -> Pin<Box<dyn Future<Output = Option<String>> + 'a>>;

    /// Fetch and parse a remote JSON-LD context document, returning its parsed
    /// value.  The default implementation calls [`load`](Self::load) and parses
    /// the result; override this to add caching of parsed values.
    fn load_val<'a>(
        &'a mut self,
        url: &'a str,
    ) -> Pin<Box<dyn Future<Output = Option<JsonLdVal>> + 'a>> {
        Box::pin(async move {
            let content = self.load(url).await?;
            parse_jsonld_for_context(&content)
        })
    }
}

/// A no-op `ContextLoader` that never resolves remote contexts.
pub struct NoopContextLoader;

impl ContextLoader for NoopContextLoader {
    fn load<'a>(&'a mut self, _url: &'a str) -> Pin<Box<dyn Future<Output = Option<String>> + 'a>> {
        Box::pin(std::future::ready(None))
    }
}

// ── Convert state ─────────────────────────────────────────────────────────────

struct ConvertState {
    blank_counter: usize,
    triples: Vec<Spanned<Triple>>,
    prefixes: Vec<Spanned<TurtlePrefix>>,
    /// Accumulates every term/base/vocab/language defined anywhere in the
    /// document's `@context` entries (later definitions override earlier ones).
    accumulated_context: ActiveContext,
    /// The base IRI passed by the caller (document URL).  Stored so that
    /// `into_turtle` can populate `Turtle::set_base` without re-deriving it.
    initial_base: Option<String>,
}

impl ConvertState {
    fn new(initial_base: Option<String>) -> Self {
        Self {
            blank_counter: 0,
            triples: Vec::new(),
            prefixes: Vec::new(),
            accumulated_context: ActiveContext::default(),
            initial_base,
        }
    }

    fn register_prefix(
        &mut self,
        term: &str,
        iri: &str,
        term_span: Range<usize>,
        val_span: Range<usize>,
    ) {
        // Overwrite any existing definition for this prefix (last definition wins,
        // matching JSON-LD context-array merging semantics).
        self.prefixes.retain(|p| p.value().prefix.value() != term);
        let full_span = term_span.start..val_span.end;
        self.prefixes.push(Spanned(
            TurtlePrefix {
                span: full_span.clone(),
                prefix: Spanned(term.to_string(), term_span),
                value: Spanned(NamedNode::Full(iri.to_string(), val_span.start), val_span),
            },
            full_span,
        ));
    }

    fn fresh_blank(&mut self, offset: usize) -> Term {
        let id = self.blank_counter;
        self.blank_counter += 1;
        Term::BlankNode(BlankNode::Named(format!("b{}", id), offset))
    }

    fn add_triple(
        &mut self,
        subject: (Term, Range<usize>),
        predicate: (Term, Range<usize>),
        object: (Term, Range<usize>),
        graph: Option<(Term, Range<usize>)>,
        span: Range<usize>,
    ) {
        let s = span.clone();
        self.triples.push(Spanned(
            Triple {
                subject: Spanned(subject.0, subject.1),
                po: vec![Spanned(
                    PO {
                        predicate: Spanned(predicate.0, predicate.1),
                        object: vec![Spanned(object.0, object.1)],
                    },
                    s.clone(),
                )],
                graph: graph.map(|g| Spanned(g.0, g.1)),
            },
            s,
        ));
    }

    fn named(iri: &str) -> Term {
        Term::NamedNode(NamedNode::Full(iri.to_string(), 0))
    }

    fn into_turtle(self) -> (Turtle, ActiveContext) {
        // If the document declared an explicit @base, represent it as the
        // syntactic Turtle base directive.  `accumulated_context.base` is only
        // written when `@base` is encountered in a `@context` object, so it
        // never reflects the caller-supplied `initial_base`.
        let turtle_base = self.accumulated_context.base.as_deref().map(|iri| {
            let nn = NamedNode::Full(iri.to_string(), 0);
            Spanned(Base(0..0, Spanned(nn, 0..0)), 0..0)
        });
        let mut turtle = Turtle::new(turtle_base, self.prefixes, self.triples);
        turtle.set_base = self.initial_base;
        (turtle, self.accumulated_context)
    }
}

// ── CST helpers ───────────────────────────────────────────────────────────────

fn text_range(node: &Node) -> Range<usize> {
    let r = node.text_range();
    r.start().into()..r.end().into()
}

fn child(node: &Node, kind: SyntaxKind) -> Option<Node> {
    node.children().find(|c| c.kind() == kind)
}

fn children(node: &Node, kind: SyntaxKind) -> impl Iterator<Item = Node> {
    node.children().filter(move |c| c.kind() == kind)
}

/// Extract the unquoted, unescaped string content from a `JsonString` node.
///
/// The A* parser wraps every matched terminal in a terminal wrapper node of the
/// same `SyntaxKind`.  So a `JsonString` producing-rule node contains one child
/// node (e.g., `AtId` or `StringToken`), which in turn contains the raw token.
/// This function peeks through that extra level to retrieve the token text.
fn extract_json_string(node: &Node) -> Option<String> {
    // `JsonString` has one child node: the terminal wrapper (AtId, StringToken, …).
    let terminal_wrapper = node.children().next()?;
    let tok = terminal_wrapper
        .children_with_tokens()
        .filter_map(|e| e.into_token())
        .find(|t| !matches!(t.kind(), SyntaxKind::WhiteSpace | SyntaxKind::Comment))?;
    let text = tok.text();
    if text.starts_with('"') && text.ends_with('"') && text.len() >= 2 {
        Some(unescape_json_string(&text[1..text.len() - 1]))
    } else {
        None
    }
}

/// Extract the text of a token from inside a terminal wrapper node.
fn terminal_text(wrapper: &Node) -> Option<String> {
    wrapper
        .children_with_tokens()
        .filter_map(|e| e.into_token())
        .find(|t| !matches!(t.kind(), SyntaxKind::WhiteSpace | SyntaxKind::Comment))
        .map(|t| t.text().to_string())
}

fn unescape_json_string(s: &str) -> String {
    let mut result = String::with_capacity(s.len());
    let mut chars = s.chars();
    while let Some(c) = chars.next() {
        if c == '\\' {
            match chars.next() {
                Some('"') => result.push('"'),
                Some('\\') => result.push('\\'),
                Some('/') => result.push('/'),
                Some('b') => result.push('\x08'),
                Some('f') => result.push('\x0C'),
                Some('n') => result.push('\n'),
                Some('r') => result.push('\r'),
                Some('t') => result.push('\t'),
                Some('u') => {
                    let hex: String = chars.by_ref().take(4).collect();
                    if let Ok(n) = u32::from_str_radix(&hex, 16) {
                        if let Some(c) = char::from_u32(n) {
                            result.push(c);
                        }
                    }
                }
                Some(other) => {
                    result.push('\\');
                    result.push(other);
                }
                None => result.push('\\'),
            }
        } else {
            result.push(c);
        }
    }
    result
}

// ── CST → JsonLdVal ───────────────────────────────────────────────────────────

fn cst_to_value(node: &Node) -> Option<JsonLdVal> {
    let span = text_range(node);
    match node.kind() {
        SyntaxKind::JsonValue => {
            // Non-terminal alternatives: JsonObject, JsonArray, JsonString.
            if let Some(obj) = child(node, SyntaxKind::JsonObject) {
                return cst_to_value(&obj);
            }
            if let Some(arr) = child(node, SyntaxKind::JsonArray) {
                return cst_to_value(&arr);
            }
            if let Some(js) = child(node, SyntaxKind::JsonString) {
                return cst_to_value(&js);
            }
            // Terminal alternatives: JSON_NUMBER, 'true', 'false', 'null'.
            // The A* wraps each matched terminal in a terminal wrapper node of the
            // same SyntaxKind, so they appear as child *nodes* of JsonValue.
            if let Some(num_node) = child(node, SyntaxKind::JsonNumber) {
                if let Some(text) = terminal_text(&num_node) {
                    return Some(JsonLdVal::Number(text));
                }
            }
            if child(node, SyntaxKind::TrueLit).is_some() {
                return Some(JsonLdVal::Bool(true));
            }
            if child(node, SyntaxKind::FalseLit).is_some() {
                return Some(JsonLdVal::Bool(false));
            }
            if child(node, SyntaxKind::NullLit).is_some() {
                return Some(JsonLdVal::Null);
            }
            None
        }
        SyntaxKind::JsonObject => {
            let mut members = Vec::new();
            // JsonObject ::= '{' memberList? '}'
            // Members live inside a MemberList child, not directly in JsonObject.
            let member_nodes: Vec<Node> = if let Some(ml) = child(node, SyntaxKind::MemberList) {
                children(&ml, SyntaxKind::Member).collect()
            } else {
                Vec::new()
            };
            for member in member_nodes {
                let Some(key_node) = child(&member, SyntaxKind::JsonString) else {
                    continue;
                };
                let Some(key) = extract_json_string(&key_node) else {
                    continue;
                };
                let key_span = text_range(&key_node);
                let Some(val_node) = child(&member, SyntaxKind::JsonValue) else {
                    continue;
                };
                let val_span = text_range(&val_node);
                let val = cst_to_value(&val_node).unwrap_or(JsonLdVal::Invalid);
                members.push((key, key_span, val_span, val));
            }
            Some(JsonLdVal::Object(members, span))
        }
        SyntaxKind::JsonArray => {
            let items = if let Some(vl) = child(node, SyntaxKind::ValueList) {
                children(&vl, SyntaxKind::JsonValue)
                    .filter_map(|v| {
                        let span = text_range(&v);
                        cst_to_value(&v).map(|val| (val, span))
                    })
                    .collect()
            } else {
                Vec::new()
            };
            Some(JsonLdVal::Array(items))
        }
        SyntaxKind::JsonString => {
            let s = extract_json_string(node)?;
            Some(JsonLdVal::Str(s))
        }
        _ => None,
    }
}

// ── Context processing ────────────────────────────────────────────────────────

/// Process a JSON-LD `@context` value and return the updated active context.
///
/// This is a boxed future because it is recursively called for arrays of
/// contexts and for remote contexts loaded via the `loader`.
fn process_context<'a>(
    mut active: ActiveContext,
    ctx_val: JsonLdVal,
    loader: &'a mut dyn ContextLoader,
    state: &'a mut ConvertState,
) -> Pin<Box<dyn Future<Output = ActiveContext> + 'a>> {
    Box::pin(async move {
        match ctx_val {
            JsonLdVal::Null => {
                active = ActiveContext::default();
            }
            JsonLdVal::Str(ref url) => {
                // Resolve the context URL against the active base (from an
                // earlier @base entry) or, if none, against the caller-supplied
                // initial base IRI.  Absolute URLs pass through unchanged.
                let base = active.base.clone().or_else(|| state.initial_base.clone());
                let resolved_url = resolve_iri(&base, url);
                if let Some(remote_ctx) = loader.load_val(&resolved_url).await {
                    active = process_context(active, remote_ctx, loader, state).await;
                }
            }
            JsonLdVal::Array(items) => {
                for (item, _) in items {
                    active = process_context(active, item, loader, state).await;
                }
            }
            JsonLdVal::Object(members, _) => {
                for (key, key_span, val_span, val) in members {
                    match key.as_str() {
                        "@base" => match &val {
                            JsonLdVal::Str(s) if s.is_empty() => active.base = None,
                            JsonLdVal::Str(s) => {
                                let resolved = resolve_iri(&active.base, s);
                                active.base = Some(resolved.clone());
                                state.accumulated_context.base = Some(resolved);
                            }
                            JsonLdVal::Null => active.base = None,
                            _ => {}
                        },
                        "@vocab" => match val {
                            JsonLdVal::Str(s) => {
                                state.accumulated_context.vocab = Some(s.clone());
                                active.vocab = Some(s);
                            }
                            JsonLdVal::Null => active.vocab = None,
                            _ => {}
                        },
                        "@language" => match val {
                            JsonLdVal::Str(s) => {
                                state.accumulated_context.language = Some(s.clone());
                                active.language = Some(s);
                            }
                            JsonLdVal::Null => active.language = None,
                            _ => {}
                        },
                        // TODO: @version, @import, @propagate, @protected, @direction
                        k if !k.starts_with('@') => {
                            // Extract inner type-scoped @context before borrowing val.
                            let scoped_ctx = if let JsonLdVal::Object(ref members, _) = val {
                                members
                                    .iter()
                                    .find(|(k, _, _, _)| k == "@context")
                                    .map(|(_, _, _, v)| v.clone())
                            } else {
                                None
                            };

                            if let Some(def) = process_term_definition(&active, k, &val) {
                                if let (Some(iri), false) = (&def.iri, def.reverse) {
                                    state.register_prefix(
                                        k,
                                        iri,
                                        key_span.clone(),
                                        val_span.clone(),
                                    );
                                }
                                state
                                    .accumulated_context
                                    .terms
                                    .insert(k.to_string(), def.clone());
                                active.terms.insert(k.to_string(), def);
                            } else {
                                active.terms.remove(k);
                            }

                            // Flatten type-scoped context into the active context so
                            // that parameter names like `originalUrlExtractor` resolve
                            // to their full IRIs for completion and hover.
                            if let Some(scoped) = scoped_ctx {
                                active = process_context(active, scoped, loader, state).await;
                            }
                        }
                        _ => {}
                    }
                }
            }
            _ => {}
        }
        active
    })
}

fn process_term_definition(
    active: &ActiveContext,
    term: &str,
    val: &JsonLdVal,
) -> Option<TermDefinition> {
    match val {
        JsonLdVal::Null => None,
        JsonLdVal::Str(s) => {
            let iri = expand_iri(active, s, true, false);
            Some(TermDefinition {
                iri,
                ..Default::default()
            })
        }
        JsonLdVal::Object(members, _) => {
            let mut def = TermDefinition::default();
            let map: HashMap<&str, &JsonLdVal> =
                members.iter().map(|(k, _, _, v)| (k.as_str(), v)).collect();

            // @reverse takes priority over @id for the IRI
            if let Some(rev_val) = map.get("@reverse") {
                if let JsonLdVal::Str(s) = rev_val {
                    def.iri = expand_iri(active, s, true, false);
                    def.reverse = true;
                }
            } else if let Some(id_val) = map.get("@id") {
                match id_val {
                    JsonLdVal::Str(s) => def.iri = expand_iri(active, s, true, false),
                    JsonLdVal::Null => def.iri = None,
                    _ => {}
                }
            } else {
                def.iri = expand_iri(active, term, true, false);
            }

            if let Some(JsonLdVal::Str(s)) = map.get("@type") {
                def.type_mapping = Some(s.clone());
            }
            if let Some(lang_val) = map.get("@language") {
                match lang_val {
                    JsonLdVal::Str(s) => def.language = Some(s.clone()),
                    JsonLdVal::Null => def.language = None,
                    _ => {}
                }
            }
            if let Some(JsonLdVal::Str(s)) = map.get("@container") {
                def.container = Some(s.clone());
            }

            Some(def)
        }
        _ => Some(TermDefinition {
            iri: None,
            ..Default::default()
        }),
    }
}

/// Parse a JSON string and return the full `JsonLdVal` tree with source spans.
///
/// Unlike [`parse_jsonld_for_context`], this returns the entire document — including
/// the `@context` entry — making it suitable for span extraction over component and
/// config files where caller code needs the precise byte ranges of `@id` values.
pub fn parse_json(content: &str) -> Option<JsonLdVal> {
    use super::parser::{Rule, SyntaxKind as SK};
    let rule = Rule::new(SK::JsonldDoc);
    let (parse, _) = crate::parse(rule, content);
    let root = parse.syntax::<Lang>();
    let json_val_node = root.children().find(|c| c.kind() == SK::JsonValue)?;
    cst_to_value(&json_val_node)
}

/// Parse a JSON-LD string (fetched from a remote URL) and return the value
/// that should be used as a context.  If the document has a top-level
/// `@context`, return that; otherwise return the whole document.
pub fn parse_jsonld_for_context(content: &str) -> Option<JsonLdVal> {
    use super::parser::{Rule, SyntaxKind as SK};
    let rule = Rule::new(SK::JsonldDoc);
    let (parse, _) = crate::parse(rule, content);
    let root = parse.syntax::<Lang>();
    // jsonldDoc ::= jsonValue; the JsonValue is a direct child of ROOT.
    let json_val_node = root.children().find(|c| c.kind() == SK::JsonValue)?;
    let val = cst_to_value(&json_val_node)?;
    // If the document contains @context at the top level, return that.
    if let JsonLdVal::Object(members, _) = &val {
        if let Some((_, _, _, ctx)) = members.iter().find(|(k, _, _, _)| k == "@context") {
            return Some(ctx.clone());
        }
    }
    Some(val)
}

// ── IRI expansion ─────────────────────────────────────────────────────────────

fn expand_iri(
    active: &ActiveContext,
    value: &str,
    vocab: bool,
    document_relative: bool,
) -> Option<String> {
    if value.is_empty() {
        if document_relative {
            return active.base.clone();
        }
        return None;
    }

    // Keywords pass through as-is
    if value.starts_with('@') {
        return Some(value.to_string());
    }

    // Term definition lookup (vocab=true: term names expand via active context)
    if vocab {
        if let Some(def) = active.terms.get(value) {
            if let Some(iri) = &def.iri {
                // Recursively expand the stored IRI in case it was stored unexpanded
                // (e.g., the prefix term was defined later in the same context object).
                // Use vocab=false to avoid re-entering term lookup and causing cycles.
                if iri == value {
                    return Some(iri.clone());
                }
                return expand_iri(active, iri, false, false);
            }
        }
    }

    // Compact IRI: contains ':' → split into prefix:suffix
    if let Some(pos) = value.find(':') {
        if pos > 0 {
            let prefix = &value[..pos];
            let suffix = &value[pos + 1..];

            // Already absolute (has scheme like http://) or blank node
            if suffix.starts_with("//") || prefix == "_" {
                return Some(value.to_string());
            }

            // Look up prefix in the active context
            if let Some(def) = active.terms.get(prefix) {
                if let Some(iri) = &def.iri {
                    return expand_iri(
                        active,
                        &format!("{}{}", iri, suffix),
                        vocab,
                        document_relative,
                    );
                }
            }

            // Unknown prefix — treat as an absolute IRI
            return Some(value.to_string());
        }
    }

    // Vocab-relative expansion
    if vocab {
        if let Some(vocab_iri) = &active.vocab {
            return Some(format!("{}{}", vocab_iri, value));
        }
    }

    // Document-relative resolution
    if document_relative {
        if let Some(base) = &active.base {
            return Some(resolve_iri(&Some(base.clone()), value));
        }
    }

    Some(value.to_string())
}

fn resolve_iri(base: &Option<String>, reference: &str) -> String {
    // Fast path: reference is already absolute.
    if let Some(base_str) = base {
        if let Ok(base_iri) = oxiri::Iri::parse(base_str.as_str()) {
            if let Ok(resolved) = base_iri.resolve(reference) {
                return resolved.to_string();
            }
        }
    }
    // No base or resolution failed — return the reference unchanged.
    reference.to_string()
}

// ── Document processing ───────────────────────────────────────────────────────

/// Top-level: process one JSON-LD value (document or item in a top-level array).
///
/// Boxed because it is directly self-recursive for top-level arrays.
fn process_document<'a>(
    state: &'a mut ConvertState,
    active: &'a ActiveContext,
    loader: &'a mut dyn ContextLoader,
    val: &'a JsonLdVal,
) -> Pin<Box<dyn Future<Output = ()> + 'a>> {
    Box::pin(async move {
        match val {
            JsonLdVal::Object(members, span) => {
                process_node(state, active, loader, members, span, None).await;
            }
            JsonLdVal::Array(items) => {
                for (item, _) in items {
                    process_document(state, active, loader, item).await;
                }
            }
            _ => {}
        }
    })
}

/// Process a JSON-LD value in the context of a named graph.
///
/// Boxed because it is directly self-recursive for arrays and mutually
/// recursive with [`process_node`].
fn process_document_with_graph<'a>(
    state: &'a mut ConvertState,
    active: &'a ActiveContext,
    loader: &'a mut dyn ContextLoader,
    val: &'a JsonLdVal,
    graph: Option<(&'a Term, &'a Range<usize>)>,
) -> Pin<Box<dyn Future<Output = ()> + 'a>> {
    Box::pin(async move {
        match val {
            JsonLdVal::Object(members, span) => {
                process_node(state, active, loader, members, span, graph).await;
            }
            JsonLdVal::Array(items) => {
                for (item, _) in items {
                    process_document_with_graph(state, active, loader, item, graph).await;
                }
            }
            _ => {}
        }
    })
}

type MemberMap<'a> = HashMap<&'a str, (&'a Range<usize>, &'a JsonLdVal, &'a Range<usize>)>;
/// Process a JSON-LD node object.  Returns the subject term if the node can
/// serve as an object in another triple (e.g., a nested node).
///
/// Boxed because it is mutually recursive with `process_document_with_graph`
/// and transitively recursive through `collect_objects` → `value_to_rdf`.
fn process_node<'a>(
    state: &'a mut ConvertState,
    active: &'a ActiveContext,
    loader: &'a mut dyn ContextLoader,
    members: &'a [(String, Range<usize>, Range<usize>, JsonLdVal)],
    span: &'a Range<usize>,
    graph: Option<(&'a Term, &'a Range<usize>)>,
) -> Pin<Box<dyn Future<Output = Option<Term>> + 'a>> {
    Box::pin(async move {
        let map: MemberMap<'_> = members
            .iter()
            .map(|(k, k_span, v_span, v)| (k.as_str(), (k_span, v, v_span)))
            .collect();

        // Value object — return as a literal, generate no subject-based triples
        if map.contains_key("@value") {
            return process_value_object(active, &map, span);
        }

        // List object
        if let Some(list_val) = map.get("@list") {
            let owned;
            let items: &[(JsonLdVal, Range<usize>)] = match list_val.1 {
                JsonLdVal::Array(items) => items.as_slice(),
                other => {
                    owned = [((*other).clone(), span.clone())];
                    &owned
                }
            };
            return Some(process_list(state, active, loader, items, span, graph).await);
        }

        // Set object — process contents but return nothing as a subject
        if let Some(set_val) = map.get("@set") {
            if let JsonLdVal::Array(items) = set_val.1 {
                for (item, _) in items {
                    process_document_with_graph(state, active, loader, item, graph).await;
                }
            }
            return None;
        }

        // Update active context if @context present in this node
        let updated;
        let active: &ActiveContext = if let Some(ctx_val) = map.get("@context") {
            updated = process_context(active.clone(), ctx_val.1.clone(), loader, state).await;
            &updated
        } else {
            active
        };

        // Determine the subject
        let id_val_span: Range<usize> = members
            .iter()
            .find(|(k, _, _, _)| k == "@id")
            .map(|(_, _, vs, _)| vs.clone())
            .unwrap_or_else(|| span.start..span.start);
        let subject: Term = if let Some(id_val) = map.get("@id") {
            match id_val.1 {
                JsonLdVal::Str(s) => match expand_iri(active, s, false, true) {
                    Some(iri) if iri.starts_with("_:") => {
                        Term::BlankNode(BlankNode::Named(iri[2..].to_string(), id_val_span.start))
                    }
                    Some(iri) => {
                        Term::NamedNode(named_from_source(active, s, iri, id_val_span.start, false))
                    }
                    None => state.fresh_blank(id_val_span.start),
                },
                _ => state.fresh_blank(id_val_span.start),
            }
        } else {
            state.fresh_blank(span.start)
        };

        // @type → rdf:type triples
        if let Some(type_val) = map.get("@type") {
            for (type_str, type_span) in collect_strings_spanned(type_val.1, type_val.2) {
                if let Some(iri) = expand_iri(active, &type_str, true, true) {
                    let obj =
                        term_or_blank_from_source(active, &type_str, iri, type_span.start, true);
                    state.add_triple(
                        (subject.clone(), id_val_span.clone()),
                        (ConvertState::named(RDF_TYPE), type_val.0.clone()), // TODO, why doesn't the map have the
                        // spans?
                        (obj, type_span),
                        graph.map(|(a, b)| (a.clone(), b.clone())),
                        span.clone(),
                    );
                }
            }
        }

        // @graph → named graph containing nested nodes
        if let Some(graph_val) = map.get("@graph") {
            let named_graph = subject.clone();
            match graph_val.1 {
                JsonLdVal::Array(items) => {
                    for (item, _) in items {
                        process_document_with_graph(
                            state,
                            active,
                            loader,
                            item,
                            Some((&named_graph, graph_val.2)),
                        )
                        .await;
                    }
                }
                JsonLdVal::Object(m, s) => {
                    process_node(
                        state,
                        active,
                        loader,
                        m,
                        s,
                        Some((&named_graph, graph_val.2)),
                    )
                    .await;
                }
                _ => {}
            }
        }

        // @reverse → reverse-property triples (object becomes subject)
        if let Some(rev_val) = map.get("@reverse") {
            if let JsonLdVal::Object(rev_members, _) = rev_val.1 {
                for (prop, prop_span, val_span, val) in rev_members {
                    if prop.starts_with('@') {
                        continue;
                    }
                    if let Some(pred_iri) = expand_iri(active, prop, true, false) {
                        let pred = Term::NamedNode(named_from_source(
                            active,
                            prop,
                            pred_iri,
                            prop_span.start,
                            true,
                        ));
                        let objects =
                            collect_objects(state, active, loader, val, val_span, graph, None)
                                .await;
                        for (obj, obj_span) in objects {
                            // Subject and object are swapped for reverse properties
                            state.add_triple(
                                (obj, obj_span.clone()),
                                (pred.clone(), prop_span.clone()),
                                (subject.clone(), id_val_span.clone()),
                                graph.map(|(a, b)| (a.clone(), b.clone())),
                                span.clone(),
                            );
                        }
                    }
                }
            }
        }

        // @included → additional node objects (processed in default graph)
        if let Some(included_val) = map.get("@included") {
            match included_val.1 {
                JsonLdVal::Array(items) => {
                    for (item, _) in items {
                        process_document(state, active, loader, item).await;
                    }
                }
                JsonLdVal::Object(m, s) => {
                    process_node(state, active, loader, m, s, None).await;
                }
                _ => {}
            }
        }

        // Regular properties
        for (key, key_span, val_span, val) in members {
            match key.as_str() {
                "@context" | "@id" | "@type" | "@graph" | "@reverse" | "@included" | "@nest" => {
                    continue;
                }
                k if k.starts_with('@') => continue,
                _ => {}
            }

            // Handle @nest: the value must be an object whose properties are promoted
            // TODO: full @nest support — for now we skip nested containers

            let pred_iri = match expand_iri(active, key, true, false) {
                Some(iri) if !iri.starts_with('@') => iri,
                _ => continue,
            };

            let term_def = active.terms.get(key.as_str());
            let objects =
                collect_objects(state, active, loader, val, val_span, graph, term_def).await;
            if objects.is_empty() {
                continue;
            }
            let s = span.clone();
            state.triples.push(Spanned(
                Triple {
                    subject: Spanned(subject.clone(), id_val_span.clone()),
                    po: vec![Spanned(
                        PO {
                            predicate: Spanned(
                                Term::NamedNode(named_from_source(
                                    active,
                                    key,
                                    pred_iri,
                                    key_span.start,
                                    true,
                                )),
                                key_span.clone(),
                            ),
                            object: objects
                                .into_iter()
                                .map(|(o, o_span)| Spanned(o, o_span))
                                .collect(),
                        },
                        key_span.clone(),
                    )],
                    graph: graph.map(|g| Spanned(g.0.clone(), g.1.clone())),
                },
                s,
            ));
        }

        Some(subject)
    })
}

// ── Value helpers ─────────────────────────────────────────────────────────────

fn collect_strings(val: &JsonLdVal) -> Vec<String> {
    match val {
        JsonLdVal::Str(s) => vec![s.clone()],
        JsonLdVal::Array(items) => items
            .iter()
            .filter_map(|(i, _)| {
                if let JsonLdVal::Str(s) = i {
                    Some(s.clone())
                } else {
                    None
                }
            })
            .collect(),
        _ => vec![],
    }
}

/// Like [`collect_strings`], but keeps each string's own source span.
///
/// For a single scalar the `fallback` span (the whole value) is used; for an
/// array each element carries its own span.  This matters for highlighting:
/// using the whole-array span for every `@type` entry makes the entire `[...]`
/// render as one token, wiping the per-element coloring.
fn collect_strings_spanned(
    val: &JsonLdVal,
    fallback: &Range<usize>,
) -> Vec<(String, Range<usize>)> {
    match val {
        JsonLdVal::Str(s) => vec![(s.clone(), fallback.clone())],
        JsonLdVal::Array(items) => items
            .iter()
            .filter_map(|(i, span)| {
                if let JsonLdVal::Str(s) = i {
                    Some((s.clone(), span.clone()))
                } else {
                    None
                }
            })
            .collect(),
        _ => vec![],
    }
}

/// Collect zero or more RDF terms from a JSON-LD value.
///
/// Boxed because it is directly self-recursive for arrays.
fn collect_objects<'a>(
    state: &'a mut ConvertState,
    active: &'a ActiveContext,
    loader: &'a mut dyn ContextLoader,
    val: &'a JsonLdVal,
    span: &'a Range<usize>,
    graph: Option<(&'a Term, &'a Range<usize>)>,
    term_def: Option<&'a TermDefinition>,
) -> Pin<Box<dyn Future<Output = Vec<(Term, Range<usize>)>> + 'a>> {
    Box::pin(async move {
        match val {
            JsonLdVal::Array(items) => {
                let mut result = Vec::new();
                for (item, item_span) in items {
                    let mut sub =
                        collect_objects(state, active, loader, item, item_span, graph, term_def)
                            .await;
                    result.append(&mut sub);
                }
                result
            }
            _ => value_to_rdf(state, active, loader, val, span, graph, term_def)
                .await
                .into_iter()
                .map(|t| (t, span.clone()))
                .collect(),
        }
    })
}

/// Map a single JSON-LD value to zero or one RDF term.
///
/// This is a plain `async fn` (not boxed) because it is not directly
/// self-recursive — the only cycle is through the boxed `process_node` and
/// `process_list` calls.
async fn value_to_rdf<'a>(
    state: &'a mut ConvertState,
    active: &'a ActiveContext,
    loader: &'a mut dyn ContextLoader,
    val: &'a JsonLdVal,
    span: &'a Range<usize>,
    graph: Option<(&'a Term, &'a Range<usize>)>,
    term_def: Option<&'a TermDefinition>,
) -> Option<Term> {
    match val {
        JsonLdVal::Object(members, obj_span) => {
            let map: MemberMap<'_> = members
                .iter()
                .map(|(k, k_span, v_span, v)| (k.as_str(), (k_span, v, v_span)))
                .collect();
            if map.contains_key("@value") {
                return process_value_object(active, &map, obj_span);
            }
            if let Some(list_val) = map.get("@list") {
                let owned;
                let items: &[(JsonLdVal, Range<usize>)] = match list_val.1 {
                    JsonLdVal::Array(items) => items.as_slice(),
                    other => {
                        owned = [((*other).clone(), obj_span.clone())];
                        &owned
                    }
                };
                return Some(process_list(state, active, loader, items, obj_span, graph).await);
            }
            process_node(state, active, loader, members, obj_span, graph).await
        }

        JsonLdVal::Str(s) => {
            if let Some(def) = term_def {
                match def.type_mapping.as_deref() {
                    Some("@id") => {
                        return expand_iri(active, s, false, true).map(|iri| {
                            term_or_blank_from_source(active, s, iri, span.start, false)
                        });
                    }
                    Some("@vocab") => {
                        return expand_iri(active, s, true, false).map(|iri| {
                            Term::NamedNode(named_from_source(active, s, iri, span.start, true))
                        });
                    }
                    Some(ty) if !ty.starts_with('@') => {
                        let ty_owned = ty.to_string();
                        if let Some(ty_iri) = expand_iri(active, &ty_owned, true, false) {
                            return Some(Term::Literal(Literal::RDF(RDFLiteral {
                                value: s.clone(),
                                quote_style: StringStyle::Double,
                                lang: None,
                                ty: Some(Spanned(
                                    named_from_source(active, ty, ty_iri, 0, true),
                                    0..0,
                                )),
                                idx: span.start,
                                len: span.len(),
                            })));
                        }
                    }
                    _ => {}
                }
                if let Some(lang) = &def.language {
                    return Some(Term::Literal(Literal::RDF(RDFLiteral {
                        value: s.clone(),
                        quote_style: StringStyle::Double,
                        lang: Some(Spanned(lang.clone(), 0..0)),
                        ty: None,
                        idx: span.start,
                        len: span.len(),
                    })));
                }
            }
            // Default: plain string, inheriting the context default language if set
            let lang = active.language.clone().map(|l| Spanned(l, 0..0));
            let ty = if lang.is_none() {
                Some(Spanned(NamedNode::Full(XSD_STRING.to_string(), 0), 0..0))
            } else {
                None
            };
            Some(Term::Literal(Literal::RDF(RDFLiteral {
                value: s.clone(),
                quote_style: StringStyle::Double,
                lang,
                ty,
                idx: span.start,
                len: span.len(),
            })))
        }

        JsonLdVal::Number(n) => {
            let type_iri = if n.contains('.') || n.to_lowercase().contains('e') {
                XSD_DOUBLE
            } else {
                XSD_INTEGER
            };
            Some(Term::Literal(Literal::RDF(RDFLiteral {
                value: n.clone(),
                quote_style: StringStyle::Double,
                lang: None,
                ty: Some(Spanned(NamedNode::Full(type_iri.to_string(), 0), 0..0)),
                idx: span.start,
                len: span.len(),
            })))
        }

        JsonLdVal::Bool(b) => Some(Term::Literal(Literal::RDF(RDFLiteral {
            value: if *b { "true" } else { "false" }.to_string(),
            quote_style: StringStyle::Double,
            lang: None,
            ty: Some(Spanned(NamedNode::Full(XSD_BOOLEAN.to_string(), 0), 0..0)),
            idx: span.start,
            len: span.len(),
        }))),

        JsonLdVal::Invalid => Some(Term::Invalid),
        JsonLdVal::Null => None,

        // Arrays must be handled by collect_objects, not here
        JsonLdVal::Array(_) => None,
    }
}

fn process_value_object(
    active: &ActiveContext,
    map: &MemberMap<'_>,
    span: &Range<usize>,
) -> Option<Term> {
    let value = map.get("@value")?;
    let lang_val = map.get("@language");
    let type_val = map.get("@type");

    let (value_str, is_complex) = match value.1 {
        JsonLdVal::Str(s) => (s.clone(), false),
        JsonLdVal::Bool(b) => (if *b { "true" } else { "false" }.to_string(), false),
        JsonLdVal::Number(n) => (n.clone(), false),
        other => (json_serialize(other), true),
    };

    let type_str = type_val.and_then(|t| {
        if let JsonLdVal::Str(s) = t.1 {
            Some(s.as_str())
        } else {
            None
        }
    });

    // @type: @json or complex value → rdf:JSON literal
    if type_str == Some("@json") || is_complex {
        return Some(Term::Literal(Literal::RDF(RDFLiteral {
            value: value_str,
            quote_style: StringStyle::Double,
            lang: None,
            ty: Some(Spanned(NamedNode::Full(RDF_JSON.to_string(), 0), 0..0)),
            idx: span.start,
            len: span.len(),
        })));
    }

    // Language-tagged string
    let lang_tag = lang_val.and_then(|l| {
        if let JsonLdVal::Str(s) = l.1 {
            Some((s.as_str(), l.2.clone()))
        } else {
            None
        }
    });
    if let Some((lt, lt_span)) = lang_tag {
        return Some(Term::Literal(Literal::RDF(RDFLiteral {
            value: value_str,
            quote_style: StringStyle::Double,
            lang: Some(Spanned(lt.to_string(), lt_span)),
            ty: None,
            idx: span.start,
            len: span.len(),
        })));
    }

    // Explicit @type
    if let Some(ty) = type_str {
        let ty_owned = ty.to_string();
        let ty_span = type_val.map(|t| t.2.clone()).unwrap_or(0..0);
        let ty_node = expand_iri(active, &ty_owned, true, false).map(|iri| {
            let start = ty_span.start;
            Spanned(named_from_source(active, ty, iri, start, true), ty_span)
        });
        return Some(Term::Literal(Literal::RDF(RDFLiteral {
            value: value_str,
            quote_style: StringStyle::Double,
            lang: None,
            ty: ty_node,
            idx: span.start,
            len: span.len(),
        })));
    }

    // Infer type from the JSON value kind
    let (inferred_ty, inferred_lang) = match value.1 {
        JsonLdVal::Bool(_) => (Some(XSD_BOOLEAN), None),
        JsonLdVal::Number(n) => {
            if n.contains('.') || n.to_lowercase().contains('e') {
                (Some(XSD_DOUBLE), None)
            } else {
                (Some(XSD_INTEGER), None)
            }
        }
        _ => {
            if let Some(lang) = &active.language {
                (None, Some(lang.clone()))
            } else {
                (Some(XSD_STRING), None)
            }
        }
    };

    Some(Term::Literal(Literal::RDF(RDFLiteral {
        value: value_str,
        quote_style: StringStyle::Double,
        lang: inferred_lang.map(|l| Spanned(l, 0..0)),
        ty: inferred_ty.map(|s| Spanned(NamedNode::Full(s.to_string(), 0), 0..0)),
        idx: span.start,
        len: span.len(),
    })))
}

/// Build an `rdf:first`/`rdf:rest` list and return the head node.
///
/// Boxed because it is mutually recursive with `value_to_rdf` (which may
/// call `process_list` again for nested `@list` values).
fn process_list<'a>(
    state: &'a mut ConvertState,
    active: &'a ActiveContext,
    loader: &'a mut dyn ContextLoader,
    items: &'a [(JsonLdVal, Range<usize>)],
    span: &'a Range<usize>,
    graph: Option<(&'a Term, &'a Range<usize>)>,
) -> Pin<Box<dyn Future<Output = Term> + 'a>> {
    Box::pin(async move {
        if items.is_empty() {
            return ConvertState::named(RDF_NIL);
        }
        // Build the linked list in reverse
        let mut rest = ConvertState::named(RDF_NIL);
        for (item, item_span) in items.iter().rev() {
            let first_term = value_to_rdf(state, active, loader, item, item_span, graph, None)
                .await
                .unwrap_or(Term::Invalid);
            let node = state.fresh_blank(item_span.start);
            state.add_triple(
                (node.clone(), item_span.start..item_span.start),
                (ConvertState::named(RDF_FIRST), 0..0),
                (first_term, item_span.clone()),
                clone_graph(graph),
                item_span.clone(),
            );
            state.add_triple(
                (node.clone(), item_span.start..item_span.start),
                (ConvertState::named(RDF_REST), 0..0),
                (rest, item_span.start..item_span.start),
                clone_graph(graph),
                span.clone(),
            );
            rest = node;
        }
        rest
    })
}

fn clone_graph(g: Option<(&'_ Term, &'_ Range<usize>)>) -> Option<(Term, Range<usize>)> {
    g.map(|g| (g.0.clone(), g.1.clone()))
}

/// Build a `NamedNode` for an IRI that appears in the source as `source` and
/// expands (via the active context) to `expanded`.
///
/// Compact IRIs (`prefix:local`) and terms that look like compact IRIs are kept
/// in `Prefixed` form so JSON-LD output stays faithful to the source and
/// consistent with the syntactic parsers (Turtle/TriG/SPARQL/N3). The
/// context-computed absolute IRI is carried in `computed` so downstream
/// consumers use it directly rather than re-expanding `prefix`/`value` — JSON-LD
/// expansion (whole-term precedence, scoped contexts, `@vocab`) is not
/// equivalent to plain prefix substitution. Absolute IRIs, blank-node-style
/// values, unknown prefixes, and bare/`@vocab` terms have no prefix form and
/// stay `Full`.
///
/// `vocab` mirrors the flag used for the corresponding `expand_iri` call so the
/// prefix/value split matches how the value was actually resolved.
fn named_from_source(
    active: &ActiveContext,
    source: &str,
    expanded: String,
    offset: usize,
    vocab: bool,
) -> NamedNode {
    // A registered term that itself looks like a compact IRI (`foaf:name`) takes
    // whole-term precedence under `@vocab` resolution: keep the whole source as
    // the lookup key so it re-resolves the same way JSON-LD did.
    if vocab && source.contains(':') && active.terms.contains_key(source) {
        return NamedNode::Prefixed {
            prefix: source.to_string(),
            value: String::new(),
            idx: offset,
            computed: Some(expanded),
        };
    }

    // Genuine compact IRI: `prefix:local` where `prefix` maps to a namespace.
    if let Some(pos) = source.find(':') {
        if pos > 0 {
            let prefix = &source[..pos];
            let suffix = &source[pos + 1..];
            let known_prefix = active
                .terms
                .get(prefix)
                .and_then(|d| d.iri.as_ref())
                .is_some();
            if !suffix.starts_with("//") && prefix != "_" && known_prefix {
                return NamedNode::Prefixed {
                    prefix: prefix.to_string(),
                    value: suffix.to_string(),
                    idx: offset,
                    computed: Some(expanded),
                };
            }
        }
    }

    NamedNode::Full(expanded, offset)
}

/// Resolve an expanded IRI to a blank node (`_:…`) or a named node, preserving
/// compact/prefixed source form for the latter via [`named_from_source`].
/// `source` is the pre-expansion text, `expanded` its context expansion.
fn term_or_blank_from_source(
    active: &ActiveContext,
    source: &str,
    expanded: String,
    offset: usize,
    vocab: bool,
) -> Term {
    if expanded.starts_with("_:") {
        Term::BlankNode(BlankNode::Named(expanded[2..].to_string(), offset))
    } else {
        Term::NamedNode(named_from_source(active, source, expanded, offset, vocab))
    }
}

fn json_serialize(val: &JsonLdVal) -> String {
    match val {
        JsonLdVal::Object(members, _) => {
            let pairs: Vec<String> = members
                .iter()
                .map(|(k, _, _, v)| format!("\"{}\":{}", json_escape(k), json_serialize(v)))
                .collect();
            format!("{{{}}}", pairs.join(","))
        }
        JsonLdVal::Array(items) => {
            let elems: Vec<String> = items.iter().map(|(item, _)| json_serialize(item)).collect();
            format!("[{}]", elems.join(","))
        }
        JsonLdVal::Str(s) => format!("\"{}\"", json_escape(s)),
        JsonLdVal::Number(n) => n.clone(),
        JsonLdVal::Bool(b) => {
            if *b {
                "true".to_string()
            } else {
                "false".to_string()
            }
        }
        JsonLdVal::Invalid => "invalid".to_string(),
        JsonLdVal::Null => "null".to_string(),
    }
}

fn json_escape(s: &str) -> String {
    s.replace('\\', "\\\\").replace('"', "\\\"")
}

// ── Public API ────────────────────────────────────────────────────────────────

/// Convert a parsed JSON-LD CST to RDF triples.
///
/// `base_iri` sets the initial base IRI for resolving relative IRIs.  When the
/// document was fetched from a URL, pass that URL here.  An explicit `@base` in
/// the document's `@context` will override this value.
///
/// Returns `(turtle, context)` where `context` is the accumulated
/// [`ActiveContext`] built from all `@context` entries in the document.
///
/// Remote `@context` references are not resolved.  Use
/// [`convert_with_loader`] to supply an async context-loading hook.
pub fn convert(root: &Node, base_iri: Option<String>) -> (Turtle, ActiveContext) {
    // NoopContextLoader always resolves immediately (std::future::ready),
    // so polling once is sufficient and safe without a real async runtime.
    use std::task::{Context, Poll, RawWaker, RawWakerVTable, Waker};

    fn noop_clone(p: *const ()) -> RawWaker {
        RawWaker::new(p, &NOOP_VTABLE)
    }
    fn noop(_: *const ()) {}
    static NOOP_VTABLE: RawWakerVTable = RawWakerVTable::new(noop_clone, noop, noop, noop);

    // SAFETY: The waker never actually wakes anything; it is only used to drive
    // the future to completion in a single synchronous poll.  This is safe
    // because NoopContextLoader::load returns std::future::ready(None), which
    // is always Poll::Ready on the first poll.
    let waker = unsafe { Waker::from_raw(RawWaker::new(std::ptr::null(), &NOOP_VTABLE)) };
    let mut cx = Context::from_waker(&waker);
    let mut loader = NoopContextLoader;
    let mut fut = std::pin::pin!(convert_with_loader(root, &mut loader, base_iri));
    match fut.as_mut().poll(&mut cx) {
        Poll::Ready(v) => v,
        Poll::Pending => unreachable!("NoopContextLoader always resolves immediately"),
    }
}

/// Convert a parsed JSON-LD CST to RDF triples, using `loader` to fetch
/// remote `@context` documents asynchronously.
///
/// `base_iri` sets the initial base IRI for resolving relative IRIs.  When the
/// document was fetched from a URL, pass that URL here.  An explicit `@base` in
/// the document's `@context` will override this value.
///
/// Returns `(turtle, context)` where `context` is the accumulated
/// [`ActiveContext`] built from all `@context` entries in the document.
pub async fn convert_with_loader(
    root: &Node,
    loader: &mut dyn ContextLoader,
    base_iri: Option<String>,
) -> (Turtle, ActiveContext) {
    let mut state = ConvertState::new(base_iri.clone());
    let active = ActiveContext {
        base: base_iri,
        ..Default::default()
    };

    // jsonldDoc ::= jsonValue — the JsonValue is a direct child of ROOT.
    if let Some(json_val_node) = root.children().find(|c| c.kind() == SyntaxKind::JsonValue) {
        if let Some(val) = cst_to_value(&json_val_node) {
            process_document(&mut state, &active, loader, &val).await;
        }
    }

    state.into_turtle()
}

// ── Tests ─────────────────────────────────────────────────────────────────────

#[cfg(test)]
mod tests {
    use super::super::parser::{Rule, SyntaxKind as SK};
    use super::*;

    fn parse_jsonld(input: &str) -> Turtle {
        use crate::parse as crate_parse;
        let rule = Rule::new(SK::JsonldDoc);
        let (result, _) = crate_parse(rule, input);
        let root = result.syntax::<Lang>();
        convert(&root, None).0
    }

    fn parse_jsonld_with_context(input: &str) -> (Turtle, ActiveContext) {
        use crate::parse as crate_parse;
        let rule = Rule::new(SK::JsonldDoc);
        let (result, _) = crate_parse(rule, input);
        let root = result.syntax::<Lang>();
        convert(&root, None)
    }

    fn parse_jsonld_with_base(input: &str, base_iri: &str) -> (Turtle, ActiveContext) {
        use crate::parse as crate_parse;
        let rule = Rule::new(SK::JsonldDoc);
        let (result, _) = crate_parse(rule, input);
        let root = result.syntax::<Lang>();
        convert(&root, Some(base_iri.to_string()))
    }

    fn triples_of(t: &Turtle) -> &[Spanned<Triple>] {
        &t.triples
    }

    /// Resolved absolute IRI of a named node: `Full`'s string, or a `Prefixed`
    /// node's context-`computed` IRI (compact JSON-LD IRIs are stored prefixed).
    fn nn_iri(nn: &NamedNode) -> Option<&str> {
        match nn {
            NamedNode::Full(s, _) => Some(s.as_str()),
            NamedNode::Prefixed { computed, .. } => computed.as_deref(),
            _ => None,
        }
    }

    fn term_iri(term: &Term) -> Option<&str> {
        match term {
            Term::NamedNode(nn) => nn_iri(nn),
            _ => None,
        }
    }

    fn subject_iri(triple: &Triple) -> Option<&str> {
        term_iri(&triple.subject.0)
    }

    fn predicate_iri(triple: &Triple) -> Option<&str> {
        triple.po.first().and_then(|po| term_iri(&po.predicate.0))
    }

    fn object_iri(triple: &Triple) -> Option<&str> {
        triple
            .po
            .first()
            .and_then(|po| po.object.first())
            .and_then(|o| term_iri(&o.0))
    }

    fn object_literal(triple: &Triple) -> Option<(&str, Option<&str>, Option<&str>)> {
        triple
            .po
            .first()
            .and_then(|po| po.object.first())
            .and_then(|o| {
                if let Term::Literal(Literal::RDF(lit)) = &o.0 {
                    let lang = lit.lang.as_ref().map(|l| l.as_str());
                    let ty = lit.ty.as_ref().and_then(|sp| nn_iri(sp.value()));
                    Some((lit.value.as_str(), lang, ty))
                } else {
                    None
                }
            })
    }

    // ── 1. Basic node with @id and one property ───────────────────────────────

    #[test]
    fn test_basic_triple() {
        let t = parse_jsonld(
            r#"
            {
              "@id": "http://example.org/s",
              "http://example.org/p": "hello"
            }
        "#,
        );
        let triples = triples_of(&t);
        assert_eq!(triples.len(), 1);
        assert_eq!(subject_iri(&triples[0]), Some("http://example.org/s"));
        assert_eq!(predicate_iri(&triples[0]), Some("http://example.org/p"));
        assert_eq!(
            object_literal(&triples[0]),
            Some(("hello", None, Some(XSD_STRING)))
        );
    }

    // ── 2. Multiple properties ────────────────────────────────────────────────

    #[test]
    fn test_multiple_properties() {
        let t = parse_jsonld(
            r#"
            {
              "@id": "http://example.org/s",
              "http://example.org/p1": "a",
              "http://example.org/p2": "b"
            }
        "#,
        );
        assert_eq!(triples_of(&t).len(), 2);
    }

    // ── 3. Anonymous nested object → blank node ───────────────────────────────

    #[test]
    fn test_nested_blank_node() {
        let t = parse_jsonld(
            r#"
            {
              "@id": "http://example.org/s",
              "http://example.org/p": {
                "http://example.org/q": "inner"
              }
            }
        "#,
        );
        // 2 triples: outer s→blank, inner blank→inner
        assert_eq!(triples_of(&t).len(), 2);
        let outer = &triples_of(&t)[1]; // outer triple
        assert_eq!(subject_iri(outer), Some("http://example.org/s"));
        // Object should be a blank node
        if let Some(po) = outer.po.first() {
            if let Some(obj) = po.object.first() {
                assert!(matches!(obj.0, Term::BlankNode(_)));
            } else {
                panic!("no object");
            }
        }
    }

    // ── 4. Inline @context with term definitions ──────────────────────────────

    #[test]
    fn test_inline_context_term() {
        let t = parse_jsonld(
            r#"
            {
              "@context": { "name": "http://schema.org/name" },
              "@id": "http://example.org/alice",
              "name": "Alice"
            }
        "#,
        );
        let triples = triples_of(&t);
        assert_eq!(triples.len(), 1);
        assert_eq!(predicate_iri(&triples[0]), Some("http://schema.org/name"));
        assert_eq!(
            object_literal(&triples[0]),
            Some(("Alice", None, Some(XSD_STRING)))
        );
    }

    // ── 5. @vocab expansion ───────────────────────────────────────────────────

    #[test]
    fn test_vocab_expansion() {
        let t = parse_jsonld(
            r#"
            {
              "@context": { "@vocab": "http://schema.org/" },
              "@id": "http://example.org/alice",
              "name": "Alice"
            }
        "#,
        );
        let triples = triples_of(&t);
        assert_eq!(triples.len(), 1);
        assert_eq!(predicate_iri(&triples[0]), Some("http://schema.org/name"));
    }

    // ── 6. @type generates rdf:type triple ───────────────────────────────────

    #[test]
    fn test_type_triple() {
        let t = parse_jsonld(
            r#"
            {
              "@id": "http://example.org/alice",
              "@type": "http://schema.org/Person"
            }
        "#,
        );
        let triples = triples_of(&t);
        assert_eq!(triples.len(), 1);
        assert_eq!(predicate_iri(&triples[0]), Some(RDF_TYPE));
        assert_eq!(object_iri(&triples[0]), Some("http://schema.org/Person"));
    }

    // ── 7. @type array ────────────────────────────────────────────────────────

    #[test]
    fn test_type_array() {
        let t = parse_jsonld(
            r#"
            {
              "@id": "http://example.org/x",
              "@type": ["http://example.org/A", "http://example.org/B"]
            }
        "#,
        );
        assert_eq!(triples_of(&t).len(), 2);
    }

    // ── 8. Value object with @language ────────────────────────────────────────

    #[test]
    fn test_value_object_language() {
        let t = parse_jsonld(
            r#"
            {
              "@id": "http://example.org/s",
              "http://example.org/p": { "@value": "hello", "@language": "en" }
            }
        "#,
        );
        let triples = triples_of(&t);
        assert_eq!(triples.len(), 1);
        assert_eq!(
            object_literal(&triples[0]),
            Some(("hello", Some("en"), None))
        );
    }

    #[test]
    fn test_type_array_per_element_spans() {
        let input = r#"{
  "@id": "http://example.org/s",
  "@type": ["http://example.org/A", "http://example.org/B"]
}"#;
        let t = parse_jsonld(input);
        let mut type_spans: Vec<&str> = Vec::new();
        for tr in triples_of(&t) {
            for po in &tr.po {
                let is_type = matches!(
                    &po.predicate.0,
                    Term::NamedNode(NamedNode::Full(s, _)) if s == RDF_TYPE
                );
                if !is_type {
                    continue;
                }
                for o in &po.object {
                    type_spans.push(&input[o.1.clone()]);
                }
            }
        }
        // Each @type entry must cover only its own string token, not the whole array.
        assert_eq!(
            type_spans,
            vec!["\"http://example.org/A\"", "\"http://example.org/B\"",]
        );
    }

    // ── 9. Value object with explicit @type ───────────────────────────────────

    #[test]
    fn test_value_object_typed() {
        let t = parse_jsonld(
            r#"
            {
              "@id": "http://example.org/s",
              "http://example.org/p": { "@value": "42", "@type": "http://www.w3.org/2001/XMLSchema#integer" }
            }
        "#,
        );
        let triples = triples_of(&t);
        assert_eq!(triples.len(), 1);
        assert_eq!(
            object_literal(&triples[0]),
            Some(("42", None, Some(XSD_INTEGER)))
        );
    }

    // ── 10. Native number → xsd:integer / xsd:double ─────────────────────────

    #[test]
    fn test_native_integer() {
        let t = parse_jsonld(
            r#"
            { "@id": "http://example.org/s", "http://example.org/p": 42 }
        "#,
        );
        assert_eq!(
            object_literal(&triples_of(&t)[0]),
            Some(("42", None, Some(XSD_INTEGER)))
        );
    }

    #[test]
    fn test_native_double() {
        let t = parse_jsonld(
            r#"
            { "@id": "http://example.org/s", "http://example.org/p": 3.14 }
        "#,
        );
        assert_eq!(
            object_literal(&triples_of(&t)[0]),
            Some(("3.14", None, Some(XSD_DOUBLE)))
        );
    }

    // ── 11. Boolean → xsd:boolean ────────────────────────────────────────────

    #[test]
    fn test_boolean() {
        let t = parse_jsonld(
            r#"
            { "@id": "http://example.org/s", "http://example.org/p": true }
        "#,
        );
        assert_eq!(
            object_literal(&triples_of(&t)[0]),
            Some(("true", None, Some(XSD_BOOLEAN)))
        );
    }

    // ── 12. Null value is skipped ─────────────────────────────────────────────

    #[test]
    fn test_null_skipped() {
        let t = parse_jsonld(
            r#"
            { "@id": "http://example.org/s", "http://example.org/p": null }
        "#,
        );
        assert_eq!(triples_of(&t).len(), 0);
    }

    // ── 13. @list → rdf:first/rdf:rest chain ─────────────────────────────────

    #[test]
    fn test_list() {
        let t = parse_jsonld(
            r#"
            {
              "@id": "http://example.org/s",
              "http://example.org/p": { "@list": ["a", "b"] }
            }
        "#,
        );
        // 1 triple for the property + 2*2 triples for the two list nodes
        let triples = triples_of(&t);
        assert!(triples.len() >= 3);
        // The property triple's object should be a blank node (list head)
        let prop_triple = triples.last().unwrap();
        if let Some(po) = prop_triple.po.first() {
            if let Some(obj) = po.object.first() {
                assert!(matches!(obj.0, Term::BlankNode(_)));
            }
        }
        // rdf:first and rdf:rest triples should be present
        let has_first = triples.iter().any(|t| predicate_iri(t) == Some(RDF_FIRST));
        let has_rest = triples.iter().any(|t| predicate_iri(t) == Some(RDF_REST));
        assert!(has_first);
        assert!(has_rest);
    }

    // ── 14. Empty @list → rdf:nil ─────────────────────────────────────────────

    #[test]
    fn test_empty_list() {
        let t = parse_jsonld(
            r#"
            {
              "@id": "http://example.org/s",
              "http://example.org/p": { "@list": [] }
            }
        "#,
        );
        let triples = triples_of(&t);
        assert_eq!(triples.len(), 1);
        assert_eq!(object_iri(&triples[0]), Some(RDF_NIL));
    }

    // ── 15. @graph → named graph triples ─────────────────────────────────────

    #[test]
    fn test_named_graph() {
        let t = parse_jsonld(
            r#"
            {
              "@id": "http://example.org/g",
              "@graph": [
                { "@id": "http://example.org/s", "http://example.org/p": "v" }
              ]
            }
        "#,
        );
        let triples = triples_of(&t);
        // One triple inside the named graph
        assert_eq!(triples.len(), 1);
        let triple = &triples[0];
        if let Some(g) = &triple.graph {
            if let Term::NamedNode(NamedNode::Full(g_iri, _)) = &g.0 {
                assert_eq!(g_iri, "http://example.org/g");
            } else {
                panic!("graph should be a named node");
            }
        } else {
            panic!("triple should be in a named graph");
        }
    }

    // ── 16. @reverse property ────────────────────────────────────────────────

    #[test]
    fn test_reverse() {
        let t = parse_jsonld(
            r#"
            {
              "@id": "http://example.org/child",
              "@reverse": {
                "http://example.org/parent": { "@id": "http://example.org/dad" }
              }
            }
        "#,
        );
        // Triple: dad → parent → child
        let triples = triples_of(&t);
        assert_eq!(triples.len(), 1);
        assert_eq!(subject_iri(&triples[0]), Some("http://example.org/dad"));
        assert_eq!(object_iri(&triples[0]), Some("http://example.org/child"));
    }

    // ── 17. Top-level array ───────────────────────────────────────────────────

    #[test]
    fn test_top_level_array() {
        let t = parse_jsonld(
            r#"
            [
              { "@id": "http://example.org/a", "http://example.org/p": "x" },
              { "@id": "http://example.org/b", "http://example.org/p": "y" }
            ]
        "#,
        );
        assert_eq!(triples_of(&t).len(), 2);
    }

    // ── 18. Compact IRI in context ────────────────────────────────────────────

    #[test]
    fn test_compact_iri() {
        let t = parse_jsonld(
            r#"
            {
              "@context": {
                "schema": "http://schema.org/",
                "name": "schema:name"
              },
              "@id": "http://example.org/alice",
              "name": "Alice"
            }
        "#,
        );
        let triples = triples_of(&t);
        assert_eq!(triples.len(), 1);
        assert_eq!(predicate_iri(&triples[0]), Some("http://schema.org/name"));
    }

    #[test]
    fn test_compact_predicate_kept_prefixed_with_computed() {
        // A `prefix:local` predicate keeps its source-faithful prefixed form
        // (consistent with the Turtle parser), while the context-computed
        // absolute IRI is carried in `computed` for downstream consumers.
        let input = r#"{"@context":{"foaf":"http://xmlns.com/foaf/0.1/"},"@id":"http://example.org/alice","foaf:name":"Alice"}"#;
        let t = parse_jsonld(input);
        let triples = triples_of(&t);
        assert_eq!(triples.len(), 1);
        match &triples[0].po[0].predicate.0 {
            Term::NamedNode(NamedNode::Prefixed {
                prefix,
                value,
                computed,
                ..
            }) => {
                assert_eq!(prefix, "foaf");
                assert_eq!(value, "name");
                assert_eq!(
                    computed.as_deref(),
                    Some("http://xmlns.com/foaf/0.1/name"),
                    "computed should hold the context-resolved absolute IRI"
                );
            }
            other => panic!("expected a prefixed predicate, got {:?}", other),
        }
        // Downstream helpers resolve to the full IRI via `computed`.
        assert_eq!(
            predicate_iri(&triples[0]),
            Some("http://xmlns.com/foaf/0.1/name")
        );
    }

    #[test]
    fn test_whole_term_compact_iri_takes_precedence() {
        // When a term literally named `foaf:name` is defined, JSON-LD whole-term
        // precedence resolves it to that term's IRI — not `foaf:` + `name`. The
        // node keeps the whole compact source as the lookup key, and `computed`
        // reflects the term's IRI so a Turtle-style re-expansion can't diverge.
        let input = r#"{"@context":{"foaf":"http://xmlns.com/foaf/0.1/","foaf:name":"http://example.org/fullName"},"@id":"http://example.org/alice","foaf:name":"Alice"}"#;
        let t = parse_jsonld(input);
        let triples = triples_of(&t);
        assert_eq!(triples.len(), 1);
        match &triples[0].po[0].predicate.0 {
            Term::NamedNode(NamedNode::Prefixed {
                prefix,
                value,
                computed,
                ..
            }) => {
                assert_eq!(prefix, "foaf:name");
                assert_eq!(value, "");
                assert_eq!(computed.as_deref(), Some("http://example.org/fullName"));
            }
            other => panic!("expected a prefixed predicate, got {:?}", other),
        }
        assert_eq!(
            predicate_iri(&triples[0]),
            Some("http://example.org/fullName")
        );
        // Display renders the whole-term compact IRI without a spurious colon.
        assert_eq!(format!("{}", triples[0].po[0].predicate.0), "foaf:name");
    }

    // ── 19. @type coercion to @id ─────────────────────────────────────────────

    #[test]
    fn test_type_coercion_id() {
        let t = parse_jsonld(
            r#"
            {
              "@context": {
                "knows": { "@id": "http://schema.org/knows", "@type": "@id" }
              },
              "@id": "http://example.org/alice",
              "knows": "http://example.org/bob"
            }
        "#,
        );
        let triples = triples_of(&t);
        assert_eq!(triples.len(), 1);
        assert_eq!(object_iri(&triples[0]), Some("http://example.org/bob"));
    }

    // ── 20. Default language from context ─────────────────────────────────────

    #[test]
    fn test_default_language() {
        let t = parse_jsonld(
            r#"
            {
              "@context": { "@language": "fr" },
              "@id": "http://example.org/s",
              "http://example.org/p": "Bonjour"
            }
        "#,
        );
        let triples = triples_of(&t);
        assert_eq!(triples.len(), 1);
        assert_eq!(
            object_literal(&triples[0]),
            Some(("Bonjour", Some("fr"), None))
        );
    }

    // ── 21. Error recovery — malformed JSON-LD still produces some triples ────

    #[test]
    fn test_error_recovery() {
        // Missing closing brace — parser should still extract the one valid property
        let t = parse_jsonld(r#"{ "@id": "http://example.org/s", "http://example.org/p": "v" "#);
        // We may or may not get the triple depending on how error recovery works,
        // but the converter should not panic.
        let _ = triples_of(&t);
    }

    // ── Span tests ────────────────────────────────────────────────────────────
    //
    // Each test pinpoints where a token lives in the source string and asserts
    // that the corresponding Spanned range starts at that position.

    /// Byte offset of the first occurrence of `needle` in `haystack`.
    fn offset_of(haystack: &str, needle: &str) -> usize {
        haystack
            .find(needle)
            .unwrap_or_else(|| panic!("needle {:?} not found in {:?}", needle, haystack))
    }

    #[test]
    fn test_subject_span_points_to_id_value() {
        // Compact single-line so byte offsets are easy to calculate.
        let input = r#"{"@id":"http://example.org/s","http://example.org/p":"v"}"#;
        let t = parse_jsonld(input);
        let triples = triples_of(&t);
        assert_eq!(triples.len(), 1);

        let expected_start = offset_of(input, "\"http://example.org/s\"");
        let subject_span = &triples[0].subject.1;
        assert_eq!(
            subject_span.start, expected_start,
            "subject span should start at the @id value, not the whole object"
        );
    }

    #[test]
    fn test_predicate_span_points_to_key_field() {
        let input = r#"{"@id":"http://example.org/s","http://example.org/p":"v"}"#;
        let t = parse_jsonld(input);
        let triples = triples_of(&t);
        assert_eq!(triples.len(), 1);

        let expected_start = offset_of(input, "\"http://example.org/p\"");
        let pred_span = &triples[0].po[0].predicate.1;
        assert_eq!(
            pred_span.start, expected_start,
            "predicate span should start at the key field"
        );
    }

    #[test]
    fn test_predicate_span_points_to_compact_iri_key_not_expanded_iri() {
        // The predicate "foaf:name" expands to the full FOAF URI via context, but
        // the span must point to the compact source key "foaf:name", not to the
        // expanded IRI (which doesn't exist in the source at all).
        let input = r#"{"@context":{"foaf":"http://xmlns.com/foaf/0.1/"},"@id":"http://example.org/alice","foaf:name":"Alice"}"#;
        let t = parse_jsonld(input);
        let triples = triples_of(&t);
        assert_eq!(triples.len(), 1);
        assert_eq!(
            predicate_iri(&triples[0]),
            Some("http://xmlns.com/foaf/0.1/name")
        );

        let expected_start = offset_of(input, "\"foaf:name\"");
        let pred_span = &triples[0].po[0].predicate.1;
        assert_eq!(
            pred_span.start, expected_start,
            "predicate span should point to the compact key in source, not the expanded IRI"
        );
        // The span should cover exactly "foaf:name" (with quotes)
        assert_eq!(
            pred_span.end,
            expected_start + "\"foaf:name\"".len(),
            "predicate span end should be just past the compact key"
        );
    }

    #[test]
    fn test_object_span_points_to_value() {
        let input = r#"{"@id":"http://example.org/s","http://example.org/p":"hello"}"#;
        let t = parse_jsonld(input);
        let triples = triples_of(&t);
        assert_eq!(triples.len(), 1);

        let expected_start = offset_of(input, "\"hello\"");
        let obj_span = &triples[0].po[0].object[0].1;
        assert_eq!(
            obj_span.start, expected_start,
            "object span should start at the value, not the whole object"
        );
    }

    #[test]
    fn test_object_span_for_iri_value() {
        // Object is an IRI (via @type coercion)
        let input = r#"{"@context":{"p":{"@id":"http://example.org/p","@type":"@id"}},"@id":"http://example.org/s","p":"http://example.org/o"}"#;
        let t = parse_jsonld(input);
        let triples = triples_of(&t);
        assert_eq!(triples.len(), 1);

        // The object "http://example.org/o" appears once at the end
        let expected_start = offset_of(input, "\"http://example.org/o\"");
        let obj_span = &triples[0].po[0].object[0].1;
        assert_eq!(
            obj_span.start, expected_start,
            "object IRI span should point to the value string"
        );
    }

    #[test]
    fn test_object_span_for_number() {
        let input = r#"{"@id":"http://example.org/s","http://example.org/p":42}"#;
        let t = parse_jsonld(input);
        let triples = triples_of(&t);
        assert_eq!(triples.len(), 1);

        let expected_start = offset_of(input, "42");
        let obj_span = &triples[0].po[0].object[0].1;
        assert_eq!(
            obj_span.start, expected_start,
            "numeric object span should start at the number token"
        );
    }

    #[test]
    fn test_spans_are_independent_per_property() {
        // Two properties — each should get spans from their own key/value tokens.
        let input = r#"{"@id":"http://example.org/s","http://example.org/p1":"v1","http://example.org/p2":"v2"}"#;
        let t = parse_jsonld(input);
        let triples = triples_of(&t);
        assert_eq!(triples.len(), 2);

        // Subject span is the same @id value for both triples
        let id_start = offset_of(input, "\"http://example.org/s\"");
        for triple in triples {
            assert_eq!(triple.subject.1.start, id_start);
        }

        // Predicate and object spans differ between the two triples
        let p1_start = offset_of(input, "\"http://example.org/p1\"");
        let p2_start = offset_of(input, "\"http://example.org/p2\"");
        let pred_starts: Vec<usize> = triples.iter().map(|t| t.po[0].predicate.1.start).collect();
        assert!(pred_starts.contains(&p1_start), "p1 span missing");
        assert!(pred_starts.contains(&p2_start), "p2 span missing");

        let v1_start = offset_of(input, "\"v1\"");
        let v2_start = offset_of(input, "\"v2\"");
        let obj_starts: Vec<usize> = triples.iter().map(|t| t.po[0].object[0].1.start).collect();
        assert!(obj_starts.contains(&v1_start), "v1 span missing");
        assert!(obj_starts.contains(&v2_start), "v2 span missing");
    }

    // ── 22. Remote @context via a custom ContextLoader ────────────────────────

    /// Drive an async future to completion using a no-op waker.
    ///
    /// Safe as long as the future only awaits immediately-ready sub-futures
    /// (i.e. no real I/O suspension).
    fn block_on_ready<T>(fut: impl std::future::Future<Output = T>) -> T {
        use std::task::{Context, Poll, RawWaker, RawWakerVTable, Waker};
        fn clone(p: *const ()) -> RawWaker {
            RawWaker::new(p, &VTABLE)
        }
        fn noop(_: *const ()) {}
        static VTABLE: RawWakerVTable = RawWakerVTable::new(clone, noop, noop, noop);
        let waker = unsafe { Waker::from_raw(RawWaker::new(std::ptr::null(), &VTABLE)) };
        let mut cx = Context::from_waker(&waker);
        let mut pinned = std::pin::pin!(fut);
        match pinned.as_mut().poll(&mut cx) {
            Poll::Ready(v) => v,
            Poll::Pending => panic!("future did not complete synchronously"),
        }
    }

    #[test]
    fn test_remote_context_loader() {
        // A mock loader that returns a hardcoded context document for one URL.
        struct MockLoader;
        impl ContextLoader for MockLoader {
            fn load<'a>(
                &'a mut self,
                url: &'a str,
            ) -> Pin<Box<dyn Future<Output = Option<String>> + 'a>> {
                let result = if url == "https://example.org/context.jsonld" {
                    Some(
                        r#"{
                          "@context": {
                            "name":   "http://schema.org/name",
                            "email":  "http://schema.org/email",
                            "Person": "http://schema.org/Person"
                          }
                        }"#
                        .to_string(),
                    )
                } else {
                    None
                };
                Box::pin(std::future::ready(result))
            }
        }

        let input = r#"
        {
          "@context": "https://example.org/context.jsonld",
          "@id":   "http://example.org/alice",
          "@type": "Person",
          "name":  "Alice",
          "email": "alice@example.org"
        }"#;

        let rule = Rule::new(SK::JsonldDoc);
        let (result, _) = crate::parse(rule, input);
        let root = result.syntax::<Lang>();

        let (turtle, _ctx) = block_on_ready(convert_with_loader(&root, &mut MockLoader, None));
        let triples = triples_of(&turtle);

        // @type → rdf:type + 2 data properties = 3 triples
        assert_eq!(triples.len(), 3);

        // rdf:type triple
        let type_triple = triples
            .iter()
            .find(|t| predicate_iri(t) == Some(RDF_TYPE))
            .expect("missing rdf:type triple");
        assert_eq!(subject_iri(type_triple), Some("http://example.org/alice"));
        assert_eq!(object_iri(type_triple), Some("http://schema.org/Person"));

        // name triple — expanded via the remote context
        let name_triple = triples
            .iter()
            .find(|t| predicate_iri(t) == Some("http://schema.org/name"))
            .expect("missing schema:name triple");
        assert_eq!(
            object_literal(name_triple),
            Some(("Alice", None, Some(XSD_STRING)))
        );

        // email triple
        assert!(
            triples
                .iter()
                .any(|t| predicate_iri(t) == Some("http://schema.org/email")),
            "missing schema:email triple"
        );
    }

    #[test]
    fn test_prefix_map_populated_from_context() {
        let t = parse_jsonld(
            r#"{
            "@context": {
                "foaf": "http://xmlns.com/foaf/0.1/",
                "schema": "http://schema.org/"
            },
            "@id": "http://example.org/bob",
            "foaf:name": "Bob"
        }"#,
        );

        let prefix_map: std::collections::HashMap<&str, &str> = t
            .prefixes
            .iter()
            .map(|p| {
                (
                    p.value().prefix.value().as_str(),
                    match p.value().value.value() {
                        NamedNode::Full(s, _) => s.as_str(),
                        _ => "",
                    },
                )
            })
            .collect();

        assert_eq!(
            prefix_map.get("foaf"),
            Some(&"http://xmlns.com/foaf/0.1/"),
            "foaf prefix missing"
        );
        assert_eq!(
            prefix_map.get("schema"),
            Some(&"http://schema.org/"),
            "schema prefix missing"
        );
    }

    #[test]
    fn test_prefix_map_object_term_definition() {
        // Terms defined with @id objects should also populate the prefix map
        let t = parse_jsonld(
            r#"{
            "@context": {
                "name": { "@id": "http://xmlns.com/foaf/0.1/name" }
            },
            "@id": "http://example.org/bob",
            "name": "Bob"
        }"#,
        );

        let prefix_map: std::collections::HashMap<&str, &str> = t
            .prefixes
            .iter()
            .map(|p| {
                (
                    p.value().prefix.value().as_str(),
                    match p.value().value.value() {
                        NamedNode::Full(s, _) => s.as_str(),
                        _ => "",
                    },
                )
            })
            .collect();

        assert_eq!(
            prefix_map.get("name"),
            Some(&"http://xmlns.com/foaf/0.1/name"),
            "name term missing"
        );
    }

    #[test]
    fn test_active_context_returned() {
        let (_turtle, ctx) = parse_jsonld_with_context(
            r#"{
            "@context": {
                "@vocab": "http://schema.org/",
                "@base": "http://example.org/",
                "@language": "en",
                "foaf": "http://xmlns.com/foaf/0.1/",
                "name": { "@id": "http://xmlns.com/foaf/0.1/name" }
            },
            "@id": "bob",
            "name": "Bob"
        }"#,
        );

        assert_eq!(ctx.vocab.as_deref(), Some("http://schema.org/"));
        assert_eq!(ctx.base.as_deref(), Some("http://example.org/"));
        assert_eq!(ctx.language.as_deref(), Some("en"));
        assert_eq!(
            ctx.terms["foaf"].iri.as_deref(),
            Some("http://xmlns.com/foaf/0.1/")
        );
        assert_eq!(
            ctx.terms["name"].iri.as_deref(),
            Some("http://xmlns.com/foaf/0.1/name")
        );
    }

    // ── 23. base_iri parameter resolves relative IRIs ─────────────────────────

    fn turtle_base_iri(t: &Turtle) -> Option<&str> {
        t.base.as_ref().and_then(|b| {
            if let NamedNode::Full(s, _) = &b.value().1.value() {
                Some(s.as_str())
            } else {
                None
            }
        })
    }

    #[test]
    fn test_base_iri_resolves_relative_subject() {
        // Without a @base in the document, the base_iri parameter should be used.
        let (t, _) = parse_jsonld_with_base(
            r#"{ "@id": "alice", "http://schema.org/name": "Alice" }"#,
            "http://example.org/",
        );
        let triples = triples_of(&t);
        assert_eq!(triples.len(), 1);
        assert_eq!(subject_iri(&triples[0]), Some("http://example.org/alice"));
        // No @base in the document → Turtle.base is None, set_base carries the URL
        assert_eq!(turtle_base_iri(&t), None);
        assert_eq!(t.set_base.as_deref(), Some("http://example.org/"));
    }

    #[test]
    fn test_base_iri_resolves_relative_object_with_type_id() {
        let (t, _) = parse_jsonld_with_base(
            r#"{
              "@context": { "knows": { "@id": "http://schema.org/knows", "@type": "@id" } },
              "@id": "http://example.org/alice",
              "knows": "bob"
            }"#,
            "http://example.org/",
        );
        let triples = triples_of(&t);
        assert_eq!(triples.len(), 1);
        assert_eq!(object_iri(&triples[0]), Some("http://example.org/bob"));
    }

    #[test]
    fn test_document_base_overrides_base_iri_parameter() {
        // An explicit @base in the document must win over the base_iri parameter.
        let (t, ctx) = parse_jsonld_with_base(
            r#"{
              "@context": { "@base": "http://override.org/" },
              "@id": "carol",
              "http://schema.org/name": "Carol"
            }"#,
            "http://example.org/",
        );
        let triples = triples_of(&t);
        assert_eq!(triples.len(), 1);
        assert_eq!(subject_iri(&triples[0]), Some("http://override.org/carol"));
        assert_eq!(ctx.base.as_deref(), Some("http://override.org/"));
        // @base from the document is reflected in Turtle.base
        assert_eq!(turtle_base_iri(&t), Some("http://override.org/"));
        // The caller-supplied URL is still in set_base
        assert_eq!(t.set_base.as_deref(), Some("http://example.org/"));
    }

    #[test]
    fn test_base_iri_no_effect_on_absolute_iris() {
        // Absolute IRIs must not be altered by the base_iri parameter.
        let (t, _) = parse_jsonld_with_base(
            r#"{ "@id": "http://absolute.example/s", "http://schema.org/name": "S" }"#,
            "http://example.org/",
        );
        let triples = triples_of(&t);
        assert_eq!(triples.len(), 1);
        assert_eq!(subject_iri(&triples[0]), Some("http://absolute.example/s"));
    }

    #[test]
    fn test_document_at_base_without_base_iri_parameter() {
        // @base in the document populates Turtle.base even when no base_iri is passed.
        let (t, ctx) = parse_jsonld_with_context(
            r#"{
            "@context": { "@base": "http://doc.example/" },
            "@id": "thing",
            "http://schema.org/name": "Thing"
        }"#,
        );
        let triples = triples_of(&t);
        assert_eq!(triples.len(), 1);
        assert_eq!(subject_iri(&triples[0]), Some("http://doc.example/thing"));
        assert_eq!(ctx.base.as_deref(), Some("http://doc.example/"));
        assert_eq!(turtle_base_iri(&t), Some("http://doc.example/"));
        assert_eq!(t.set_base, None);
    }

    // ── 24. Local context imports via ContextLoader ───────────────────────────

    /// A loader that serves one or more hardcoded (URL → JSON-LD context) pairs,
    /// simulating local file serving or a simple in-memory registry.
    struct LocalLoader {
        entries: Vec<(&'static str, &'static str)>,
    }

    impl LocalLoader {
        fn new(entries: Vec<(&'static str, &'static str)>) -> Self {
            Self { entries }
        }
    }

    impl ContextLoader for LocalLoader {
        fn load<'a>(
            &'a mut self,
            url: &'a str,
        ) -> Pin<Box<dyn Future<Output = Option<String>> + 'a>> {
            let result = self
                .entries
                .iter()
                .find(|(u, _)| *u == url)
                .map(|(_, body)| body.to_string());
            Box::pin(std::future::ready(result))
        }
    }

    fn parse_with_local_loader(
        input: &str,
        loader: &mut dyn ContextLoader,
    ) -> (Turtle, ActiveContext) {
        let rule = Rule::new(SK::JsonldDoc);
        let (result, _) = crate::parse(rule, input);
        let root = result.syntax::<Lang>();
        block_on_ready(convert_with_loader(&root, loader, None))
    }

    #[test]
    fn test_local_context_terms_expanded() {
        // The document references a local context URL; the loader provides it.
        let mut loader = LocalLoader::new(vec![(
            "file:///contexts/person.jsonld",
            r#"{ "@context": { "name": "http://schema.org/name", "Person": "http://schema.org/Person" } }"#,
        )]);

        let (turtle, _) = parse_with_local_loader(
            r#"{
              "@context": "file:///contexts/person.jsonld",
              "@id": "http://example.org/alice",
              "@type": "Person",
              "name": "Alice"
            }"#,
            &mut loader,
        );
        let triples = triples_of(&turtle);
        assert_eq!(triples.len(), 2);
        assert!(
            triples.iter().any(|t| predicate_iri(t) == Some(RDF_TYPE)
                && object_iri(t) == Some("http://schema.org/Person")),
            "missing rdf:type triple"
        );
        assert!(
            triples
                .iter()
                .any(|t| predicate_iri(t) == Some("http://schema.org/name")),
            "missing schema:name triple"
        );
    }

    #[test]
    fn test_local_context_array_merges_multiple_imports() {
        // A context array that mixes a local import with an inline object.
        let mut loader = LocalLoader::new(vec![(
            "file:///contexts/base.jsonld",
            r#"{ "@context": { "schema": "http://schema.org/" } }"#,
        )]);

        let (turtle, ctx) = parse_with_local_loader(
            r#"{
              "@context": [
                "file:///contexts/base.jsonld",
                { "name": "schema:name" }
              ],
              "@id": "http://example.org/bob",
              "name": "Bob"
            }"#,
            &mut loader,
        );
        let triples = triples_of(&turtle);
        assert_eq!(triples.len(), 1);
        assert_eq!(predicate_iri(&triples[0]), Some("http://schema.org/name"));
        // Both the imported prefix and the inline term should be in the context.
        assert_eq!(
            ctx.terms["schema"].iri.as_deref(),
            Some("http://schema.org/")
        );
        assert_eq!(
            ctx.terms["name"].iri.as_deref(),
            Some("http://schema.org/name")
        );
    }

    #[test]
    fn test_local_context_unknown_url_is_skipped() {
        // If the loader returns None for a URL, processing continues without that
        // context — no panic, no partial expansion.
        let mut loader = LocalLoader::new(vec![]); // serves nothing

        let (turtle, _) = parse_with_local_loader(
            r#"{
              "@context": "file:///contexts/missing.jsonld",
              "@id": "http://example.org/s",
              "http://example.org/p": "v"
            }"#,
            &mut loader,
        );
        // The absolute-IRI property must still be emitted.
        let triples = triples_of(&turtle);
        assert_eq!(triples.len(), 1);
        assert_eq!(predicate_iri(&triples[0]), Some("http://example.org/p"));
    }

    #[test]
    fn test_local_context_chained_imports() {
        // context_a imports context_b; the document imports context_a.
        // This verifies that the loader is called recursively for nested imports.
        let mut loader = LocalLoader::new(vec![
            (
                "file:///ctx_a.jsonld",
                r#"{ "@context": ["file:///ctx_b.jsonld", { "name": "http://schema.org/name" }] }"#,
            ),
            (
                "file:///ctx_b.jsonld",
                r#"{ "@context": { "schema": "http://schema.org/" } }"#,
            ),
        ]);

        let (turtle, ctx) = parse_with_local_loader(
            r#"{
              "@context": "file:///ctx_a.jsonld",
              "@id": "http://example.org/carol",
              "name": "Carol"
            }"#,
            &mut loader,
        );
        let triples = triples_of(&turtle);
        assert_eq!(triples.len(), 1);
        assert_eq!(predicate_iri(&triples[0]), Some("http://schema.org/name"));
        assert_eq!(
            ctx.terms["schema"].iri.as_deref(),
            Some("http://schema.org/")
        );
    }

    #[test]
    fn test_relative_context_url_resolved_against_document_base() {
        // The @context value is a relative URL.  With a base_iri parameter set,
        // the loader should receive the fully-resolved absolute URL.
        let rule = Rule::new(SK::JsonldDoc);
        let input = r#"{
          "@context": "context.jsonld",
          "@id": "http://example.org/s",
          "name": "Alice"
        }"#;
        let (result, _) = crate::parse(rule, input);
        let root = result.syntax::<Lang>();

        let mut loader = LocalLoader::new(vec![(
            "http://example.org/context.jsonld",
            r#"{ "@context": { "name": "http://schema.org/name" } }"#,
        )]);

        let (turtle, _) = block_on_ready(convert_with_loader(
            &root,
            &mut loader,
            Some("http://example.org/".to_string()),
        ));
        let triples = triples_of(&turtle);
        assert_eq!(triples.len(), 1);
        assert_eq!(predicate_iri(&triples[0]), Some("http://schema.org/name"));
    }

    #[test]
    fn test_relative_context_url_resolved_against_at_base() {
        // When the document sets @base before the relative context URL appears
        // (as part of an array context), that @base is used for resolution.
        let rule = Rule::new(SK::JsonldDoc);
        let input = r#"{
          "@context": [
            { "@base": "http://other.example/" },
            "ctx.jsonld"
          ],
          "@id": "http://example.org/s",
          "label": "Hello"
        }"#;
        let (result, _) = crate::parse(rule, input);
        let root = result.syntax::<Lang>();

        let mut loader = LocalLoader::new(vec![(
            "http://other.example/ctx.jsonld",
            r#"{ "@context": { "label": "http://schema.org/name" } }"#,
        )]);

        let (turtle, _) = block_on_ready(convert_with_loader(&root, &mut loader, None));
        let triples = triples_of(&turtle);
        assert_eq!(triples.len(), 1);
        assert_eq!(predicate_iri(&triples[0]), Some("http://schema.org/name"));
    }

    #[test]
    fn test_local_context_with_base_iri_parameter() {
        // Combines a local context import with the base_iri parameter so that
        // relative subject IRIs are resolved correctly.
        let rule = Rule::new(SK::JsonldDoc);
        let input = r#"{
          "@context": "file:///contexts/vocab.jsonld",
          "@id": "dave",
          "name": "Dave"
        }"#;
        let (result, _) = crate::parse(rule, input);
        let root = result.syntax::<Lang>();

        let mut loader = LocalLoader::new(vec![(
            "file:///contexts/vocab.jsonld",
            r#"{ "@context": { "name": "http://schema.org/name" } }"#,
        )]);

        let (turtle, _) = block_on_ready(convert_with_loader(
            &root,
            &mut loader,
            Some("http://example.org/people/".to_string()),
        ));

        let triples = triples_of(&turtle);
        assert_eq!(triples.len(), 1);
        assert_eq!(
            subject_iri(&triples[0]),
            Some("http://example.org/people/dave")
        );
        assert_eq!(predicate_iri(&triples[0]), Some("http://schema.org/name"));
    }

    // ── Formatter tests ──────────────────────────────────────────────────────

    fn format_jsonld(input: &str, width: usize) -> String {
        use super::super::parser::format;
        use crate::parse as crate_parse;
        let rule = Rule::new(SK::JsonldDoc);
        let (result, _) = crate_parse(rule, input);
        let root = result.syntax::<Lang>();
        format::format(&root, width)
    }

    #[test]
    fn format_small_object_fits_on_one_line() {
        // A small object that fits in 80 columns stays flat.
        // Prettier-style: spaces inside braces in flat mode (Line → " ").
        let input = r#"{"a": 1, "b": 2}"#;
        let out = format_jsonld(input, 80);
        assert_eq!(out, "{ \"a\": 1, \"b\": 2 }\n");
    }

    #[test]
    fn format_large_object_breaks() {
        // An object too wide for the column limit expands to one member per line.
        let input = r#"{"key": "value"}"#;
        let out = format_jsonld(input, 10);
        assert_eq!(out, "{\n  \"key\": \"value\"\n}\n");
    }

    #[test]
    fn format_multiple_members_break() {
        let input = r#"{"a":1,"b":2,"c":3}"#;
        let out = format_jsonld(input, 10);
        assert_eq!(out, "{\n  \"a\": 1,\n  \"b\": 2,\n  \"c\": 3\n}\n");
    }

    #[test]
    fn format_nested_objects() {
        // Both inner and outer fit at wide width — both stay flat.
        let input = r#"{"outer":{"inner":1}}"#;
        let out = format_jsonld(input, 80);
        assert_eq!(out, "{ \"outer\": { \"inner\": 1 } }\n");
    }

    #[test]
    fn format_is_idempotent() {
        // Formatting already-formatted output produces the same result.
        let input = r#"{"key": "value", "num": 42}"#;
        let first = format_jsonld(input, 80);
        let second = format_jsonld(&first, 80);
        assert_eq!(first, second);
    }
}