elly_core/

module.rs

//! Modules: compiling module source into a chunk, and resolving and
//! instantiating a module's import graph.
//!
//! Imports are top-level declarations; the reachable module set is fixed by source.
//! The [`ModuleResolver`] provides a module's canonical name and source, which is then
//! compiled and instantiated into the importing module's frame. Instantiated modules
//! contain unevaluated bodies (see [`crate::instantiate`]).
//!
//! ## Loading Process
//!
//! Traversal is post-order depth-first; a module is instantiated only after its imports.
//! This ensures frames contain only finished values and enforces acyclicity.
//! Cycles are detected during traversal and reported as [`LoadError::Cycle`].
//!
//! Modules are deduplicated by canonical name. All specs resolving to the same name
//! share a single instance, ensuring consistent identity across the import graph.
//!
//! [`Instances`] maps names to instances. A [`Ctx`] holds one for its lifetime,
//! together with its resolver, so loads through [`Ctx::load`] share a cache. The
//! free functions [`load_module`] and [`load_module_source`] take both explicitly.

use alloc::string::String;
use alloc::vec::Vec;
use core::cell::Ref;

use crate::code::{ChunkId, Text};
use crate::eval::instantiate;
use crate::source::DocSource;
use crate::{Ctx, Error, Value};

/// What a module's source writes to name an import — a path, a package-qualified
/// name. Its grammar belongs to the host resolver, not to Elly.
pub type ImportSpec = Text;

/// What a resolver answers a spec with: one name per module, however many specs
/// reach it. Module instances are deduplicated by this name, so a resolver that
/// returns the spec unchanged would hand back two instances of one module for
/// `"./foo"` and `"foo"` (see [`crate::load_module`]).
pub type ModuleName = Text;

impl Ctx {
    /// Compile Elly module source into a new chunk, whose top module is the
    /// module (see `docs/done/2026-08-07_elly-modules-v0.md`).
    ///
    /// This is purely syntactic: bodies are resolved against the module's
    /// members and imports are mapped to leading frame slots. No bodies are
    /// evaluated; [`instantiate`](crate::instantiate) makes an instance.
    pub fn compile_module(&self, src: &str) -> Result<ChunkId, Error> {
        self.compile_module_framed(src, &[])
    }

    /// Compile Elly module source against a frame of ordered names.
    ///
    /// References to frame names resolve to de Bruijn locals. Lookup order:
    /// enclosing binders $\to$ imports $\to$ module items $\to$ frame.
    /// Module imports occupy the leading frame slots.
    pub fn compile_module_framed(&self, src: &str, frame: &[Text]) -> Result<ChunkId, Error> {
        self.compile_module_named(src, frame, None)
    }

    /// Same as [`compile_module_framed`](Self::compile_module_framed), but records
    /// the canonical source name used by `__Mod.name` and for instance
    /// deduplication. The chunk takes the name, or `__module_N` if there is none.
    pub fn compile_module_named(
        &self,
        src: &str,
        frame: &[Text],
        name: Option<ModuleName>,
    ) -> Result<ChunkId, Error> {
        self.compile_source(src, frame, name, None)
    }
}

/// A module's canonical name and source.
///
/// The name defines the module's identity; all specs resolving to one module must
/// return the same canonical name.
pub struct Resolved {
    /// Unique name for the module.
    pub name: String,
    /// Module source.
    pub source: String,
    /// The file the source was read from, if any: where an error's location
    /// points (see [`DocSource::Path`]).
    pub path: Option<String>,
}

/// Host-provided module loader. Maps an import spec to its canonical name and source.
///
/// Because `elly-core` is `no_std`, file I/O is handled by the host via this trait.
pub trait ModuleResolver {
    fn resolve(&self, spec: &str) -> Option<Resolved>;
}

/// Map from canonical name to instantiated module.
///
/// Deduplicates the import graph within a single [`load_module`] and acts as the
/// cache a [`Ctx`] keeps across loads. Since a name fixes the frame and imports,
/// cached instances remain valid unless dropped.
#[derive(Debug, Default)]
pub struct Instances {
    entries: Vec<(ModuleName, Value)>,
}

impl Instances {
    /// Create an empty instance map.
    pub fn new() -> Instances {
        Instances {
            entries: Vec::new(),
        }
    }

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

    /// Insert or replace the instance for `name`.
    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)),
        }
    }

    /// Number of modules in the map.
    pub fn len(&self) -> usize {
        self.entries.len()
    }

    /// Whether the map is empty.
    pub fn is_empty(&self) -> bool {
        self.entries.is_empty()
    }

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

/// Compile-time module loading errors.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum LoadError {
    /// Spec could not be resolved.
    NotFound { spec: String },
    /// Import cycle detected; `path` is the closing chain of names.
    Cycle { path: Vec<ModuleName> },
    /// Module failed to compile. `source` is its text, and `path` the file it
    /// was read from, if any: what [`Error::report`] needs to show the error
    /// at its line.
    Compile {
        name: ModuleName,
        error: Error,
        path: Option<String>,
        source: String,
    },
}

impl Ctx {
    /// Loads a module and its import graph through this context's resolver,
    /// returning the instance for `spec`. A module already in the cache is
    /// reused, so two loads that reach one module share its instance.
    ///
    /// Without a resolver, every spec is [`LoadError::NotFound`].
    ///
    /// Loading is not re-entrant: nothing evaluates while a graph is
    /// instantiated, so no host callback can run a nested load.
    pub fn load(&self, spec: &str) -> Result<Value, LoadError> {
        let mut seen = self.instances.borrow_mut();
        load_module(spec, self.resolver(), self, &mut seen)
    }

    /// Loads a module from `src` under `name`, resolving its imports through this
    /// context's resolver. The caller supplied the text, so it replaces whatever
    /// `name` held in the cache — the explicit reload.
    pub fn load_source(&self, name: &str, src: &str) -> Result<Value, LoadError> {
        let mut seen = self.instances.borrow_mut();
        load_module_source(name, src, self.resolver(), self, &mut seen)
    }

    /// The modules loaded so far, by canonical name.
    pub fn instances(&self) -> Ref<'_, Instances> {
        self.instances.borrow()
    }

    fn resolver(&self) -> &dyn ModuleResolver {
        match &self.resolver {
            Some(resolver) => resolver.as_ref(),
            None => &NoResolver,
        }
    }
}

/// The resolver of a [`Ctx`] given none: nothing resolves.
struct NoResolver;

impl ModuleResolver for NoResolver {
    fn resolve(&self, _spec: &str) -> Option<Resolved> {
        None
    }
}

/// Loads a module and its import graph: resolves, compiles, and instantiates
/// modules leaves-first, returning the instance for `spec`.
///
/// `seen` deduplicates instances and may be used as a cache. `ctx` handles
/// item ID allocation.
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)
}

/// Loads a module from provided source under `name`.
///
/// Ignores and replaces any existing instance of `name` in `seen`, allowing
/// explicit reloads.
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();
    let name = ModuleName::from(name);
    instantiate_source(name, src, None, resolver, ctx, seen, &mut path)
}

/// Resolves a spec to an instance, using `seen` for deduplication.
/// Detects cycles via `path`.
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 });
    }
    let doc = resolved
        .path
        .map(|path| DocSource::Path(path.as_str().into()));
    instantiate_source(name, &resolved.source, doc, resolver, ctx, seen, path)
}

/// Compiles source as `name`, from `doc` (`None` for an anonymous source),
/// loads imports, and instantiates the module.
///
/// Traversal is post-order; imports are loaded before the module is instantiated,
/// ensuring frame slots contain finished modules.
fn instantiate_source(
    name: ModuleName,
    src: &str,
    doc: Option<DocSource>,
    resolver: &dyn ModuleResolver,
    ctx: &Ctx,
    seen: &mut Instances,
    path: &mut Vec<ModuleName>,
) -> Result<Value, LoadError> {
    let doc_path = doc.clone();
    let chunk = ctx
        .compile_source(src, &[], Some(name.clone()), doc)
        .map_err(|error| LoadError::Compile {
            name: name.clone(),
            error,
            path: match doc_path {
                Some(DocSource::Path(path)) => Some(String::from(path.as_str())),
                _ => None,
            },
            source: String::from(src),
        })?;
    path.push(name.clone());
    let specs: Vec<ImportSpec> = {
        let code = ctx.chunk(chunk);
        code.imports(code.module(code.top())).to_vec()
    };
    let mut frame: Vec<Value> = Vec::with_capacity(specs.len());
    for spec in &specs {
        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(chunk, &frame, ctx).expect("a module's frame is exactly its own imports");
    seen.insert(name, instance.clone());
    Ok(instance)
}