elly_core/

load.rs

//! The **const stage**: turning a module's written `import`s into instances.
//!
//! A module's imports are declarations at its top level, not calls its bodies
//! make, so the set of modules a program can reach is fixed by its source. This
//! is where that set is walked: each spec is handed to the host
//! [`ModuleResolver`], which answers with the module's canonical name and source;
//! the source is compiled and instantiated; and the instance is written into the
//! importing module's frame. Nothing is evaluated — an instantiated module is
//! still a table of unevaluated bodies (see [`crate::instantiate`]).
//!
//! ## Leaves first, one instance per name
//!
//! The walk is a post-order depth-first traversal, so a module is instantiated
//! only once every module it imports already is: its frame is filled with
//! finished values and never with a placeholder to patch. That ordering is also
//! the acyclicity the whole design rests on — a module frame holds only values
//! older than the frame itself (`docs/done/2026-08-13_elly-modules-env.md`) — read as a
//! schedule rather than checked afterwards. A graph with no such order has a
//! cycle, and the traversal reports it ([`LoadError::Cycle`]) with the path that
//! closes it, at compile time rather than as a surprise mid-run.
//!
//! Instances are deduplicated by **canonical name**, which is why the resolver
//! returns one rather than the caller keying on the spec: `"./foo"` and `"foo"`
//! are two specs for one module, and two instances of it would compare unequal
//! and mint two sets of identities. With the dedup, a diamond — `A` and `B` both
//! importing `Shared` — puts the very same object in both frames.
//!
//! The dedup map is [`Instances`], and it is an argument rather than something
//! this stage allocates for itself: giving it a longer life than one compile is
//! how a host caches loaded modules, which is a change of owner and not of
//! design. See `docs/done/2026-08-11_elly-modules-import.md`.

use alloc::string::String;
use alloc::vec::Vec;

use crate::eval::{instantiate, Ctx, ModuleData, Value};
use crate::parse::ModuleName;
use crate::Error;

/// What a host answers a module spec with: the module's **canonical name** and
/// its source.
///
/// The name is the identity of the module, and the const stage keys instances on
/// it, so a resolver has to canonicalize: every spec that reaches one module must
/// come back with one name. For a path resolver that is the resolved real path —
/// the same thing it compares against its search root.
pub struct Resolved {
    /// One name per module, however many specs reach it.
    pub name: String,
    /// The module's Elly source.
    pub source: String,
}

/// A host-provided module loader, consulted at **compile time** by the const
/// stage. Maps a spec — whatever a source writes in `import "…"` — to the
/// module's canonical name and source, or `None` if it cannot be found.
///
/// The `elly` core is `no_std`, so file I/O lives in the host behind this
/// callback. A host that confines what a program may load (`elly-py`'s
/// `PathResolver` searches a fixed directory list) enforces it here, and because
/// the specs are literals in the source, refusing one is a compile-time refusal
/// rather than a run-time one.
pub trait ModuleResolver {
    fn resolve(&self, spec: &str) -> Option<Resolved>;
}

/// The const stage's map from canonical name to instantiated module: what makes
/// one name yield one instance.
///
/// A caller passes one in and may keep it: within a single [`load_module`] it
/// deduplicates the import graph (a diamond shares its instance), and across
/// calls it becomes a host's module cache, so a module loaded once is not
/// compiled again. Reuse is safe because a name fixes a frame — one name has one
/// set of imports, instantiated leaves-first, so name equality implies frame
/// equality. The cost of keeping it is that a cached name is never recompiled:
/// changed source on disk is not noticed until the entry is dropped.
#[derive(Debug, Default)]
pub struct Instances {
    entries: Vec<(ModuleName, Value)>,
}

impl Instances {
    /// An empty map — one compile's worth of dedup, nothing carried in.
    pub fn new() -> Instances {
        Instances {
            entries: Vec::new(),
        }
    }

    /// The instance recorded for `name`, if any.
    pub fn get(&self, name: &str) -> Option<&Value> {
        self.entries
            .iter()
            .find(|(n, _)| n.as_str() == name)
            .map(|(_, v)| v)
    }

    /// Record `value` as the instance for `name`, replacing any earlier one.
    pub fn insert(&mut self, name: ModuleName, value: Value) {
        match self.entries.iter_mut().find(|(n, _)| *n == name) {
            Some(entry) => entry.1 = value,
            None => self.entries.push((name, value)),
        }
    }

    /// How many modules the map holds.
    pub fn len(&self) -> usize {
        self.entries.len()
    }

    /// Whether the map holds no modules.
    pub fn is_empty(&self) -> bool {
        self.entries.is_empty()
    }

    /// The canonical names the map holds, in insertion order.
    pub fn names(&self) -> impl Iterator<Item = &ModuleName> {
        self.entries.iter().map(|(n, _)| n)
    }
}

/// Why a module graph could not be loaded. Every one of these is a **compile-time**
/// failure: the imports are literals in the source, so they are resolved, compiled
/// and instantiated before anything runs, and none of it can raise mid-evaluation.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum LoadError {
    /// The resolver did not answer this spec. Carries the spec as written, since
    /// the module it names has no canonical name to report.
    NotFound { spec: String },
    /// The imports form a cycle. `path` is the chain of canonical names that
    /// closes it, importer before importee, ending with the name that repeats —
    /// so `[A, B, A]` reads as "`A` imports `B` imports `A`".
    Cycle { path: Vec<ModuleName> },
    /// A module's source did not compile, named by the module it came from.
    Compile { name: ModuleName, error: Error },
}

/// Load the module `spec` names, with its whole import graph: resolve, compile and
/// instantiate every module it reaches, leaves first, one instance per canonical
/// name, and hand back the instance for `spec` itself.
///
/// `seen` deduplicates and may be reused across calls as a cache (see
/// [`Instances`]); pass a fresh one for an independent load. Identities come from
/// `ctx`, which reserves each module's block of item ids as it is instantiated, so
/// a host that hands values out between contexts should seed successors with
/// [`Ctx::ids_used`](crate::Ctx::ids_used).
pub fn load_module(
    spec: &str,
    resolver: &dyn ModuleResolver,
    ctx: &Ctx,
    seen: &mut Instances,
) -> Result<Value, LoadError> {
    let mut path = Vec::new();
    load_spec(spec, resolver, ctx, seen, &mut path)
}

/// [`load_module`] for source the caller already has, compiled under the canonical
/// `name` it should be known by. Its own imports still go through `resolver`.
///
/// Unlike [`load_module`] this **ignores** any instance `seen` already holds for
/// `name` and replaces it: the caller supplied the source, so it means this text
/// rather than whatever was loaded under that name before. That is what makes an
/// explicit reload possible while a plain by-name load stays cached.
pub fn load_module_source(
    name: &str,
    src: &str,
    resolver: &dyn ModuleResolver,
    ctx: &Ctx,
    seen: &mut Instances,
) -> Result<Value, LoadError> {
    let mut path = Vec::new();
    instantiate_source(ModuleName::from(name), src, resolver, ctx, seen, &mut path)
}

/// Resolve one spec and give back its instance: the cached one, or a freshly
/// compiled and instantiated one. Reaching a name that is already being compiled
/// means the graph has a cycle.
fn load_spec(
    spec: &str,
    resolver: &dyn ModuleResolver,
    ctx: &Ctx,
    seen: &mut Instances,
    path: &mut Vec<ModuleName>,
) -> Result<Value, LoadError> {
    let resolved = resolver.resolve(spec).ok_or_else(|| LoadError::NotFound {
        spec: String::from(spec),
    })?;
    let name = ModuleName::from(resolved.name.as_str());
    if let Some(instance) = seen.get(name.as_str()) {
        return Ok(instance.clone());
    }
    if path.contains(&name) {
        let mut cycle = path.clone();
        cycle.push(name);
        return Err(LoadError::Cycle { path: cycle });
    }
    instantiate_source(name, &resolved.source, resolver, ctx, seen, path)
}

/// Compile `src` as `name`, load everything it imports, then instantiate it
/// against those instances and record it.
///
/// The imports are loaded *after* this module is on `path` and *before* it is
/// instantiated, which is what makes the traversal post-order: every frame slot
/// holds a finished module by the time the frame is built.
fn instantiate_source(
    name: ModuleName,
    src: &str,
    resolver: &dyn ModuleResolver,
    ctx: &Ctx,
    seen: &mut Instances,
    path: &mut Vec<ModuleName>,
) -> Result<Value, LoadError> {
    let data: alloc::rc::Rc<ModuleData> = crate::compile_module_named(src, &[], Some(name.clone()))
        .map_err(|error| LoadError::Compile {
            name: name.clone(),
            error,
        })?;
    path.push(name.clone());
    let mut frame: Vec<Value> = Vec::with_capacity(data.imports().len());
    for spec in data.imports() {
        frame.push(load_spec(spec.as_str(), resolver, ctx, seen, path)?);
    }
    path.pop();
    // The module was compiled against no host frame, so its slots are exactly its
    // imports and the arity check cannot fail.
    let instance =
        instantiate(data, &frame, ctx).expect("a module's frame is exactly its own imports");
    seen.insert(name, instance.clone());
    Ok(instance)
}