elly_core/

module.rs

use alloc::{boxed::Box, rc::Rc, vec::Vec};

use crate::{Error, Expr, Text};

/// A loaded module containing an immutable, name-sorted table of unevaluated
/// item bodies. Built by [`crate::compile_module`] and stored in an `Rc`.
/// Sibling references are compiled to [`Expr::ModItem`] and resolved via the
/// home module in the environment ([`crate::eval_env::EnvNode::Module`]), ensuring the value
/// heap remains acyclic. See `docs/done/2026-08-07_elly-modules-v0.md`.
///
/// Sibling references use a direct slice index; outside `M.name` accesses use binary search.
#[derive(Debug, PartialEq, Eq)]
pub struct ModuleData {
    items: Box<[(Text, Expr)]>,
    /// Name-sorted private bindings declared with `local`. These are members addressed
    /// in the same index space as items, starting at `items.len()`.
    ///
    /// Privacy is enforced by excluding these from the `index_of` binary search used
    /// for outside `M.name` access. Locals precede iotas so that id-bearing members
    /// (including lambdas) fall within the block reserved by [`instantiate`].
    /// See `docs/done/2026-08-13_elly-modules-local.md`.
    locals: Box<[(Text, Expr)]>,
    /// Name-sorted iotas declared with `const`. They share an address space with
    /// items and locals, starting at [`len`](Self::len).
    ///
    /// Iotas reserve no frame slot or ID; their value is derived on reference based
    /// on the instance and index. Only the name is stored for rendering.
    iotas: Box<[Text]>,
    /// The module's import signature: names of frame slots in index order.
    /// Used for arity checks in [`instantiate`] and host introspection. Empty if no
    /// frame exists. Imports precede any provided frame names.
    frame_names: Box<[Text]>,
    /// Import specifications for the leading frame slots in slot order.
    /// Resolved during the const stage and filled with instances (see [`crate::load_module`]).
    imports: Box<[ImportSpec]>,
    /// The module body, evaluated in the module's environment by the holder.
    /// This may be a [`recur`](Expr::Recur) group's body or a source's `__main`
    /// (evaluated by a runner and skipped during import).
    ///
    /// It is stored separately from the item tables to maintain name-sorting
    /// invariants and ensure the body is unnameable via `M.__main`.
    /// See `docs/done/2026-08-14_elly-run.md`.
    body: Option<Expr>,
    /// The canonical name assigned by the host. This is a property of the code
    /// rather than the instance. `None` for unnamed modules or [`recur`](Expr::Recur) groups.
    name: Option<ModuleName>,
}

impl ModuleData {
    /// Freezes resolved bindings into the item table. Bindings are name-sorted
    /// by [`crate::resolve::resolve_module_bodies`] to maintain `ModItem` index consistency.
    pub(crate) fn from_bindings(
        bindings: alloc::vec::Vec<(Text, Expr)>,
        locals: alloc::vec::Vec<(Text, Expr)>,
        iotas: Box<[Text]>,
        frame_names: Box<[Text]>,
        imports: Box<[ImportSpec]>,
        body: Option<Expr>,
        name: Option<ModuleName>,
    ) -> ModuleData {
        debug_assert!(
            bindings.is_sorted_by(|a, b| a.0.as_str() < b.0.as_str()),
            "module bindings must be sorted by name and distinct"
        );
        debug_assert!(
            locals.is_sorted_by(|a, b| a.0.as_str() < b.0.as_str()),
            "module locals must be sorted by name and distinct"
        );
        debug_assert!(
            iotas.is_sorted_by(|a, b| a.as_str() < b.as_str()),
            "module iotas must be sorted by name and distinct"
        );
        debug_assert!(
            imports.len() <= frame_names.len(),
            "every import is a frame slot"
        );
        ModuleData {
            items: bindings.into_boxed_slice(),
            locals: locals.into_boxed_slice(),
            iotas,
            frame_names,
            imports,
            body,
            name,
        }
    }

    /// Name-sorted item table used for [`recur`](Expr::Recur) rendering and resolution.
    /// Accessed via position ([`item`](Self::item)) or binary search ([`index_of`](Self::index_of)).
    pub(crate) fn items(&self) -> &[(Text, Expr)] {
        &self.items
    }

    /// Item bodies for in-place resolution. For [`recur`](Expr::Recur) groups,
    /// bodies remain mutable after `ModuleData` creation, unlike file modules
    /// which are frozen by [`from_bindings`](Self::from_bindings).
    pub(crate) fn items_mut(&mut self) -> &mut [(Text, Expr)] {
        &mut self.items
    }

    /// Returns the body at `index` (from [`Expr::ModItem`]), covering both items
    /// and [locals](Self::locals). Returns `None` if the index is an iota.
    pub(crate) fn item(&self, index: u32) -> Option<&Expr> {
        let index = index as usize;
        match self.items.get(index) {
            Some((_, body)) => Some(body),
            None => self
                .locals
                .get(index - self.items.len())
                .map(|(_, body)| body),
        }
    }

    /// Finds the index of `name` via binary search. Used by outside `M.name`
    /// accesses before calling [`item`](Self::item).
    pub(crate) fn index_of(&self, name: &str) -> Option<u32> {
        self.items
            .binary_search_by(|(n, _)| n.as_str().cmp(name))
            .ok()
            .map(|i| i as u32)
    }

    /// Total count of ID-bearing members (items and [locals](Self::locals)).
    /// This defines the start of the iota address space and the ID block
    /// size reserved by [`instantiate`].
    pub(crate) fn len(&self) -> usize {
        self.items.len() + self.locals.len()
    }

    /// Returns the iota name at `index` (calculated as `member index - len()`).
    /// Returns `None` if the index is out of bounds, triggering a `.missing_property` error.
    pub(crate) fn iota(&self, index: u32) -> Option<&Text> {
        self.iotas.get(index as usize)
    }

    /// Sorted list of public item names accessible via outside `M.name` access.
    pub fn item_names(&self) -> impl Iterator<Item = &Text> {
        self.items.iter().map(|(n, _)| n)
    }

    /// Sorted list of names declared with `local`. Locals are unreachable
    /// via `M.name` from outside; this method is provided for host
    /// introspection (e.g., debuggers).
    pub fn local_names(&self) -> Vec<&Text> {
        self.locals.iter().map(|(n, _)| n).collect()
    }

    /// Sorted list of names declared with `const`. Private iotas are unreachable
    /// via `M.name` from outside.
    pub fn iota_names(&self) -> &[Text] {
        &self.iotas
    }

    /// Names of frame slots in order. Defines the requirements for
    /// `instantiate`. Empty if no frame exists.
    pub fn frame_names(&self) -> &[Text] {
        &self.frame_names
    }

    /// Import specifications in slot order. Provides a static, auditable record
    /// of reachable modules without requiring execution.
    pub fn imports(&self) -> &[ImportSpec] {
        &self.imports
    }

    /// Returns the module's body (a `recur` group's body or a source's `__main`).
    /// Evaluated by runners in the instance environment (see [`crate::eval_main`]);
    /// remains inert during imports.
    pub fn body(&self) -> Option<&Expr> {
        self.body.as_ref()
    }

    /// Mutable reference to the body for in-place resolution. Required for
    /// [`recur`](Expr::Recur) groups, which are built at parse.
    pub(crate) fn body_mut(&mut self) -> Option<&mut Expr> {
        self.body.as_mut()
    }

    /// The canonical name assigned by the host. Used by `__Mod.name` and the
    /// const stage for instance deduplication. `None` if unnamed.
    pub fn name(&self) -> Option<&ModuleName> {
        self.name.as_ref()
    }
}

/// 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;

/// One `import` declaration: the name the importing module reaches the instance
/// by, and the spec its host resolver is handed.
///
/// The two written forms differ in whether the module also **re-exports** the
/// instance. `import "spec" as Foo` is a private frame slot; `Foo = import "spec"`
/// is the same slot plus an ordinary item `Foo` that forwards it. Both arrive here
/// as one `ImportDecl` — the re-exporting form has additionally pushed its
/// forwarding item into `ModuleSyntax::items` (see
/// `docs/done/2026-08-11_elly-modules-import.md`).
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ImportDecl {
    /// The name the importing module's bodies read the instance by.
    pub name: Text,
    /// What the host resolver is handed.
    pub spec: ImportSpec,
}

/// A module source's top-level declarations: its imports and its `const`
/// declarations, in source order, and its items. The imports are the module's
/// first frame slots — the const stage resolves, compiles and instantiates each
/// one, then instantiates this module against the results (see
/// [`crate::load_module`]). The iotas take no slot at all: an iota's identity is
/// its instance plus its position, derived on reference (see
/// `docs/done/2026-08-13_elly-modules-iotas.md`).
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ModuleSyntax {
    /// The `import` declarations, in source order, which is frame-slot order.
    pub imports: Vec<ImportDecl>,
    /// The names declared by `const`, in source order — the module's **iotas**.
    /// Sorted before they reach [`ModuleData`](crate::ModuleData), where the
    /// order is the address space a member reference counts against.
    pub iotas: Vec<Text>,
    /// The `name = body` items, in source order, bodies unresolved.
    pub items: Vec<(Text, Expr)>,
    /// The `local name = body` declarations, in source order, bodies unresolved
    /// — the module's **private** bindings. They are members like the items, and
    /// differ only in not being searched by name from outside (see
    /// `docs/done/2026-08-13_elly-modules-local.md`).
    pub locals: Vec<(Text, Expr)>,
    /// What the module declared as `__main`, if anything — the **reserved
    /// moditem** a runner evaluates and applies to the root capability.
    ///
    /// It is a slot rather than an entry in [`items`](Self::items), and that is
    /// what makes it unnameable: the member index space it stays out of is the
    /// only thing a body's reference or an outside `M.name` access can address.
    /// See `docs/done/2026-08-14_elly-run.md`.
    pub main: Option<Expr>,
}

/// 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(src: &str, frame: &[Text]) -> Result<Rc<ModuleData>, Error> {
    compile_module_named(src, frame, None)
}

/// Same as [`compile_module_framed`], but records the canonical source name
/// used by `__Mod.name` and for instance deduplication.
pub fn compile_module_named(
    src: &str,
    frame: &[Text],
    name: Option<ModuleName>,
) -> Result<Rc<ModuleData>, Error> {
    let seq = muon::parse(src).map_err(Error::Syntax)?;
    let syntax = crate::parse_module(&seq).map_err(Error::Parse)?;
    let mut bindings = syntax.items;
    let mut locals = syntax.locals;
    let import_names: Vec<Text> = syntax.imports.iter().map(|i| i.name.clone()).collect();
    // The iota table is name-sorted, as the item and local tables are: the three
    // orders concatenated are the member index space a `ModItem` counts against.
    let mut iotas = syntax.iotas;
    iotas.sort_by(|a, b| a.as_str().cmp(b.as_str()));
    // `__main` is resolved with the item bodies and against the same tiers — it
    // is written in the module's own scope, so it reaches every member and every
    // frame slot. It takes no member index of its own (see `ModuleData::body`).
    let mut main = syntax.main;
    crate::resolve_module_bodies(
        &mut bindings,
        &mut locals,
        main.as_mut(),
        &import_names,
        &iotas,
        frame,
    )
    .map_err(Error::Parse)?;
    let mut frame_names = import_names;
    frame_names.extend_from_slice(frame);
    Ok(Rc::new(ModuleData::from_bindings(
        bindings,
        locals,
        iotas.into_boxed_slice(),
        frame_names.into_boxed_slice(),
        syntax
            .imports
            .into_iter()
            .map(|i| i.spec)
            .collect::<Vec<_>>()
            .into_boxed_slice(),
        main,
        name,
    )))
}