Skip to main content

decl_lang/
module.rs

1//! Module loading, linking, and universe evaluation (module.ts, §8.1–8.5,
2//! §8.8): files are modules, the import graph is acyclic, exports are
3//! explicit; packages (§8.6–8.7) plug in through the resolver hook.
4use crate::ast::*;
5use crate::engine::{Engine, RootSrc};
6use crate::package::Resolver;
7use crate::parse::parse_source;
8use crate::semantics::*;
9use std::cell::RefCell;
10use std::collections::HashMap;
11use std::path::{Path, PathBuf};
12use std::rc::Rc;
13
14/// one module of a universe
15pub struct Module {
16    /// the module's absolute path
17    pub path: PathBuf,
18    /// its declarations
19    pub decls: Vec<Decl>,
20    /// its environment, with its imports linked
21    pub env: Rc<Env>,
22    /// what it exports, by name (§8.2)
23    pub exports: Rc<RefCell<HashMap<String, Export>>>,
24}
25
26/// a universe loaded from an entry module
27pub struct LoadResult {
28    /// every module, the entry included, in load order
29    pub modules: Vec<Rc<Module>>,
30    /// the entry module, when it loaded
31    pub entry: Option<Rc<Module>>,
32    /// the loading and linking diagnostics (§8): a missing module, a cycle, a collision, an unexported name
33    pub diags: Vec<Diag>,
34}
35
36struct Loader {
37    modules: HashMap<PathBuf, Rc<Module>>,
38    order: Vec<Rc<Module>>,
39    visiting: Vec<PathBuf>,
40    diags: Vec<Diag>,
41    resolver: Option<Resolver>,
42    overrides: HashMap<PathBuf, String>,
43}
44
45impl Loader {
46    fn report(&mut self, code: &str, message: String) {
47        self.diags
48            .push(Diag::error(message, String::new(), Some(code)));
49    }
50    fn report_at(&mut self, code: &str, message: String, loc: Loc) {
51        let mut d = Diag::error(message, String::new(), Some(code));
52        d.loc = Some(loc);
53        self.diags.push(d);
54    }
55    fn resolve_spec(&mut self, spec: &str, from_dir: &Path) -> Option<PathBuf> {
56        if spec.starts_with("./") || spec.starts_with("../") {
57            return Some(normalize(&from_dir.join(spec)));
58        }
59        let Some(resolver) = self.resolver.clone() else {
60            self.report(
61                "E3010",
62                format!("package import \"{spec}\" outside a package (no manifest)"),
63            );
64            return None;
65        };
66        match resolver(spec, from_dir) {
67            Ok(p) => Some(p),
68            Err((code, message)) => {
69                self.report(&code, message);
70                None
71            }
72        }
73    }
74    fn load(&mut self, path: &Path) -> Option<Rc<Module>> {
75        let abs = normalize(&std::path::absolute(path).unwrap_or_else(|_| path.to_path_buf()));
76        if let Some(m) = self.modules.get(&abs) {
77            return Some(m.clone());
78        }
79        if let Some(ci) = self.visiting.iter().position(|p| *p == abs) {
80            let cycle: Vec<String> = self.visiting[ci..]
81                .iter()
82                .chain(std::iter::once(&abs))
83                .map(|p| p.display().to_string())
84                .collect();
85            self.report(
86                "E3007",
87                format!("module import cycle: {}", cycle.join(" -> ")),
88            );
89            return None;
90        }
91        let src = match self.overrides.get(&abs) {
92            Some(s) => s.clone(),
93            None => match std::fs::read_to_string(&abs) {
94                Ok(s) => s,
95                Err(_) => {
96                    self.report("E3004", format!("module not found: {}", abs.display()));
97                    return None;
98                }
99            },
100        };
101        let parsed = parse_source(&src);
102        if !parsed.errors.is_empty() {
103            let e = &parsed.errors[0];
104            self.report_at(
105                "E2001",
106                format!("{}: {} parse error(s)", abs.display(), parsed.errors.len()),
107                Loc {
108                    sl: e.0,
109                    sc: e.1,
110                    el: e.0,
111                    ec: e.1 + 1,
112                },
113            );
114            return None;
115        }
116        let env = Env::new();
117        env.load(&parsed.decls);
118        for n in env.duplicates.borrow().iter() {
119            self.diags.push(Diag::error(
120                format!("duplicate name {n} in {}", abs.display()),
121                String::new(),
122                Some("E3001"),
123            ));
124        }
125        let m = Rc::new(Module {
126            path: abs.clone(),
127            decls: parsed.decls,
128            env,
129            exports: Rc::new(RefCell::new(HashMap::new())),
130        });
131        self.visiting.push(abs.clone());
132        let mut targets: HashMap<String, Rc<Module>> = HashMap::new();
133        let from_dir = abs.parent().map(|p| p.to_path_buf()).unwrap_or_default();
134        for d in &m.decls {
135            let from = match &d.body {
136                DeclBody::Import { from, .. } | DeclBody::ReExport { from, .. } => from.clone(),
137                _ => continue,
138            };
139            if let Some(t) = self.resolve_spec(&from, &from_dir) {
140                if let Some(tm) = self.load(&t) {
141                    targets.insert(from, tm);
142                }
143            }
144        }
145        self.visiting.pop();
146        self.modules.insert(abs.clone(), m.clone());
147
148        let taken = |n: &str| {
149            let e = &m.env;
150            e.type_asts.borrow().contains_key(n)
151                || e.consts.borrow().contains_key(n)
152                || e.funcs.borrow().contains_key(n)
153                || e.diags.borrow().contains_key(n)
154                || e.inputs.borrow().contains_key(n)
155                || e.outputs.borrow().iter().any(|(o, _, _)| o == n)
156                || e.imports.borrow().contains_key(n)
157                || e.namespaces.borrow().contains_key(n)
158        };
159        for d in &m.decls {
160            match &d.body {
161                DeclBody::Import { from, names, ns } => {
162                    let Some(tm) = targets.get(from) else {
163                        continue;
164                    };
165                    if let Some(ns) = ns {
166                        if taken(ns) {
167                            self.report(
168                                "E3006",
169                                format!(
170                                    "import {ns} collides with an existing binding in {}",
171                                    abs.display()
172                                ),
173                            );
174                            continue;
175                        }
176                        m.env
177                            .namespaces
178                            .borrow_mut()
179                            .insert(ns.clone(), (tm.env.clone(), tm.exports.clone()));
180                        continue;
181                    }
182                    for it in names.iter().flatten() {
183                        let local = it.alias.clone().unwrap_or_else(|| it.name.clone());
184                        let ex = tm.exports.borrow().get(&it.name).cloned();
185                        let Some(ex) = ex else {
186                            self.report(
187                                "E3005",
188                                format!("{} does not export {}", tm.path.display(), it.name),
189                            );
190                            continue;
191                        };
192                        if taken(&local) {
193                            self.report(
194                                "E3006",
195                                format!(
196                                    "import {local} collides with an existing binding in {}",
197                                    abs.display()
198                                ),
199                            );
200                            continue;
201                        }
202                        m.env.imports.borrow_mut().insert(local, ex);
203                    }
204                }
205                DeclBody::ReExport { from, names } => {
206                    let Some(tm) = targets.get(from) else {
207                        continue;
208                    };
209                    for it in names {
210                        let ex = tm.exports.borrow().get(&it.name).cloned();
211                        match ex {
212                            Some(ex) => {
213                                m.exports.borrow_mut().insert(
214                                    it.alias.clone().unwrap_or_else(|| it.name.clone()),
215                                    ex,
216                                );
217                            }
218                            None => self.report(
219                                "E3005",
220                                format!("{} does not export {}", tm.path.display(), it.name),
221                            ),
222                        }
223                    }
224                }
225                _ => {}
226            }
227        }
228        for d in &m.decls {
229            if !d.exported {
230                continue;
231            }
232            if matches!(
233                d.body,
234                DeclBody::Unit { .. }
235                    | DeclBody::Dimension { .. }
236                    | DeclBody::Import { .. }
237                    | DeclBody::ReExport { .. }
238            ) {
239                continue;
240            }
241            if let Some(n) = d.name() {
242                m.exports.borrow_mut().insert(
243                    n.to_string(),
244                    Export {
245                        env: m.env.clone(),
246                        name: n.to_string(),
247                    },
248                );
249            }
250        }
251        self.order.push(m.clone());
252        Some(m)
253    }
254}
255
256fn normalize(p: &Path) -> PathBuf {
257    let mut out = PathBuf::new();
258    for c in p.components() {
259        match c {
260            std::path::Component::ParentDir => {
261                out.pop();
262            }
263            std::path::Component::CurDir => {}
264            other => out.push(other),
265        }
266    }
267    out
268}
269
270/// `resolver` maps package specifiers to paths (packages, §8.6);
271/// `overrides` maps absolute paths to buffer contents (editors)
272pub fn load_modules(
273    entry: &Path,
274    resolver: Option<&Resolver>,
275    overrides: Option<&HashMap<PathBuf, String>>,
276) -> LoadResult {
277    let mut ld = Loader {
278        modules: HashMap::new(),
279        order: vec![],
280        visiting: vec![],
281        diags: vec![],
282        resolver: resolver.cloned(),
283        overrides: overrides.cloned().unwrap_or_default(),
284    };
285    let entry_m = ld.load(entry);
286    if let Some(e) = &entry_m {
287        link_universe(&ld.order, e, &mut ld.diags);
288    }
289    LoadResult {
290        modules: ld.order,
291        entry: entry_m,
292        diags: ld.diags,
293    }
294}
295
296fn link_universe(mods: &[Rc<Module>], entry: &Rc<Module>, diags: &mut Vec<Diag>) {
297    let mut owners: HashMap<String, PathBuf> = HashMap::new();
298    for m in mods {
299        for d in &m.decls {
300            if let DeclBody::Output { name, .. } | DeclBody::Input { name, .. } = &d.body {
301                if let Some(prev) = owners.get(name) {
302                    if *prev != m.path {
303                        diags.push(Diag::error(
304                            format!(
305                                "root {name} declared in both {} and {}",
306                                prev.display(),
307                                m.path.display()
308                            ),
309                            String::new(),
310                            Some("E3018"),
311                        ));
312                    }
313                }
314                owners.insert(name.clone(), m.path.clone());
315            }
316        }
317    }
318    for m in mods {
319        for d in &m.decls {
320            if !d.exported {
321                continue;
322            }
323            match &d.body {
324                DeclBody::Dimension { name, terms } => {
325                    for m2 in mods {
326                        if Rc::ptr_eq(m2, m) {
327                            continue;
328                        }
329                        let own = m2.decls.iter().any(
330                            |x| matches!(&x.body, DeclBody::Dimension { name: n, .. } if n == name),
331                        );
332                        let has = m2.env.dim_decls.borrow().contains_key(name);
333                        if has && !own {
334                            continue;
335                        }
336                        if has {
337                            diags.push(Diag::error(
338                                format!("dimension {name} redeclared across modules"),
339                                String::new(),
340                                Some("E3001"),
341                            ));
342                        } else {
343                            m2.env
344                                .dim_decls
345                                .borrow_mut()
346                                .insert(name.clone(), terms.clone());
347                        }
348                    }
349                }
350                DeclBody::Unit {
351                    name,
352                    dim,
353                    factor,
354                    base,
355                } => {
356                    for m2 in mods {
357                        if Rc::ptr_eq(m2, m) {
358                            continue;
359                        }
360                        let own = m2.decls.iter().any(
361                            |x| matches!(&x.body, DeclBody::Unit { name: n, .. } if n == name),
362                        );
363                        let has = m2.env.unit_decls.borrow().contains_key(name);
364                        if has && !own {
365                            continue;
366                        }
367                        if has {
368                            diags.push(Diag::error(
369                                format!("unit {name} redeclared across modules"),
370                                String::new(),
371                                Some("E4073"),
372                            ));
373                        } else {
374                            m2.env.unit_decls.borrow_mut().insert(
375                                name.clone(),
376                                UnitDecl {
377                                    dim: dim.clone(),
378                                    factor: factor.clone(),
379                                    base: base.clone(),
380                                },
381                            );
382                        }
383                    }
384                }
385                _ => {}
386            }
387        }
388    }
389    for m in mods {
390        if Rc::ptr_eq(m, entry) {
391            continue;
392        }
393        *m.env.registry.borrow_mut() = entry.env.registry.borrow().clone();
394        *m.env.roots.borrow_mut() = entry.env.roots.borrow().clone();
395        *m.env.diagnostics.borrow_mut() = entry.env.diagnostics.borrow().clone();
396    }
397}
398
399/// a document bound to an input (§10): `module` is the one declaring the
400/// input (the entry when unset)
401pub struct Bind {
402    /// the module declaring the input, when one does
403    pub module: Option<Rc<Module>>,
404    /// the input's name
405    pub input: String,
406    /// the document, as the JSON reader gives it
407    pub raw: Value,
408}
409
410/// Evaluate a universe: bind the documents to their inputs, then every root of
411/// every module (§9.2), force, validate; returns the entry's engine and every
412/// diagnostic in canonical order.
413pub fn run_universe(
414    mods: &[Rc<Module>],
415    entry: &Rc<Module>,
416    binds: Vec<Bind>,
417) -> (Rc<Engine>, Vec<Diag>) {
418    // the query engine, when selected, evaluates the universe in place of the
419    // tree walker (qengine/DESIGN.md); an unhandled form falls back, unless
420    // strict mode makes it a hard error
421    if crate::pipeline::use_qengine() {
422        let m_envs: Vec<Rc<Env>> = mods.iter().map(|m| m.env.clone()).collect();
423        let bspecs: Vec<crate::qengine::qeval::BoundSpec> = binds
424            .iter()
425            .map(|b| crate::qengine::qeval::BoundSpec {
426                name: b.input.clone(),
427                raw: b.raw.clone(),
428                menv: b
429                    .module
430                    .clone()
431                    .unwrap_or_else(|| entry.clone())
432                    .env
433                    .clone(),
434            })
435            .collect();
436        match crate::qengine::qeval::run_universe(&m_envs, &entry.env, &bspecs, false) {
437            Ok((report, eng)) => return (eng, report.diagnostics),
438            Err(u) => {
439                if crate::pipeline::strict_qengine() {
440                    panic!("DECL_QENGINE_STRICT: unhandled form: {}", u.0);
441                }
442                // else fall back to the tree walker; a fresh evaluation, so the
443                // partial round's roots/registry/diagnostics are cleared first
444                entry.env.roots_clear();
445                entry.env.registry_clear();
446                entry.env.diag_set(vec![]);
447                // Cached constants may own records from the discarded registry.
448                // Recompute them in the fresh universe so they are validated.
449                for m in mods {
450                    for c in m.env.consts.borrow().values() {
451                        c.state.set(false);
452                        *c.value.borrow_mut() = Value::Undef;
453                    }
454                }
455            }
456        }
457    }
458    let eng = Engine::evaluate(
459        &entry.env,
460        &|eng| {
461            for m in mods {
462                eng.install_hooks(&m.env, true);
463            }
464            // bound documents first: an output may read an input (§5.5), and a
465            // bound input is a root of the universe (§9.2); unbound inputs with a
466            // fallback bind on first demand (§9.4)
467            for b in &binds {
468                let m = b.module.clone().unwrap_or_else(|| entry.clone());
469                let decl = m.env.inputs.borrow().get(&b.input).cloned();
470                let Some((ty_ast, _)) = decl else { continue };
471                let sc = Scope::new(&b.input, Some(m.env.clone()));
472                match m.env.resolve(&ty_ast, None) {
473                    Ok(rt) => eng.bind_root(&b.input, RootSrc::Doc(b.raw.clone()), &rt, &sc),
474                    Err(e) => entry.env.report(Diag::error(e, b.input.clone(), None)),
475                }
476            }
477            for m in mods {
478                let outs = m.env.outputs.borrow().clone();
479                for (name, ty_ast, expr) in outs {
480                    let sc = Scope::new(&name, Some(m.env.clone()));
481                    match m.env.resolve(&ty_ast, None) {
482                        Ok(rt) => eng.bind_root(&name, RootSrc::Expr(&expr), &rt, &sc),
483                        Err(e) => entry.env.report(Diag::error(e, name.clone(), None)),
484                    }
485                }
486            }
487        },
488        false,
489    );
490    eng.validate_all("");
491    // §6.7: evaluation- and validation-time diagnostics in (path, id) order
492    let diags = sort_diags(entry.env.diagnostics_vec());
493    entry.env.diag_set(diags.clone());
494    (eng, diags)
495}