zelkova_compiler/canonical/

environment.rs

//! env module

use super::{parser, Pattern, PatternKind};
use super::{ClassSignature, PublishedInstance};
use super::{Infix, Interface, ModuleName, Name, QualName, Type, TypeConstructor, UnionType};
use crate::default_imports;
use crate::scalars;
use crate::utils::{collect_accumulate, suggest};
use crate::{PhaseError, SourceSpan, SpanLabel};
use log::trace;
use std::collections::HashMap;
use zelkova_syntax::position::NodeSpan;

#[derive(Debug)]
pub(crate) enum ValueType {
    Local,
    TopLevel,
    /// A value found through exactly one import, together with where it was
    /// declared in that module — `None` when the interface it came from cannot
    /// say (a hand-built one, or one built before its file was known) — and
    /// whether that import was written or supplied by [the default import
    /// list](ImportOrigin).
    Foreign(ModuleName, Option<SourceSpan>, Type, ImportOrigin),
    /// A value exposed unqualified by more than one import — `AmbiguousVariables`
    /// once looked up — each candidate paired the same way as `Foreign`.
    Foreigns(Vec<(ModuleName, Option<SourceSpan>, ImportOrigin)>),
}

/// Whether a contributor to a module's scope was named by an `import` line the
/// file wrote, or supplied by [the default import
/// list](crate::default_imports) because the file wrote none for that
/// module.
///
/// Carried alongside `ValueType::Foreign`/`Foreigns` purely for diagnostics:
/// [`super::Error::AmbiguousVariables`]'s note calls a `Default` contributor out
/// as implicit, since the collision it causes sits in a module the file never
/// named — [*The default
/// imports*](../../../docs/spec/modules.md#the-default-imports) states the rule
/// that a default entry participates in ambiguity exactly as a written import
/// does; this is what lets the diagnostic say which kind of import it was.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ImportOrigin {
    /// Named by an `import` line in the module under check.
    Written,
    /// Not written by the module under check — supplied because the module
    /// wrote no import for it.
    Default,
}

/// An operator's `infix` declaration as the environment holds it: what it declares,
/// where that declaration was written, and how the function it names resolves.
///
/// The first two are separate because [`Infix::span`] on its own is not enough to
/// underline: an infix reaches this environment either from the module under check
/// or cloned out of an imported module's [`Interface`], and in the second case the
/// span is a byte range in the *exporting* module's file. `declaration` is what
/// records which of the two it was — see [`InfixDeclaration`].
///
/// `function` is the third, and is what makes an operator usable across a module
/// boundary: it is resolved in the module that wrote the `infix` declaration, so
/// whether the importing module also has the backing function in scope never enters
/// into it — see [`InfixFunction`].
#[derive(Debug, Clone)]
pub(crate) struct InfixEntry {
    pub infix: Infix,
    pub declaration: InfixDeclaration,
    pub function: InfixFunction,
}

/// The function an operator's `infix` declaration names, resolved once — when the
/// declaration enters the environment — in the module that wrote it.
///
/// An operator has no qualified spelling, so naming it in an `exposing` list is the
/// only way to use one from another module, and whether that module's *backing*
/// function is also in scope is not something the importer chose or can see. Binding
/// the function to the declaration here is what decouples the two: `resolve_infix_operator`
/// (`canonical/mod.rs`) builds the operator's canonical value out of this variant
/// and never looks the function's name up in the importing module's own scope.
#[derive(Debug, Clone)]
pub(crate) enum InfixFunction {
    /// Declared by the module under check, as a top-level value. `do_infixes`
    /// registers an `infix` only after finding the declaration it names among this
    /// module's functions, so nothing further has to be checked at the use site.
    Local,
    /// Declared by the module that exported the operator, with the type that
    /// module's [`Interface`] carries for it — from
    /// [`Interface::values`] when the header exposes the function by name, and from
    /// [`Interface::infix_functions`] when it exposes only the operator.
    Imported(ModuleName, Type),
    /// Exported by a module whose [`Interface`] carries no type for the backing
    /// function, which happens when that declaration was never annotated. There is
    /// nothing to type a use of the operator against, so `resolve_infix_operator`
    /// reports the function as the unresolved name.
    ImportedUntyped(ModuleName),
}

/// Where an operator's `infix` declaration was written, to the extent
/// canonicalization can say — the three cases a [`SpanLabel`] under it has to
/// distinguish.
///
/// A phase only ever sees one module and never learns which file it was read from,
/// so a label about the module under check leaves `SpanLabel::file` as `None` and
/// the driver fills it in at render time. A label about an *imported* operator
/// cannot do that: its span belongs to
/// the exporting module's file, and rendering it against the importing one
/// underlines unrelated text. That is what [`SourceSpan`] and `SpanLabel::file`
/// were built for (`ERR-5`), and this enum is what picks between them.
#[derive(Debug, Clone, Copy, PartialEq)]
pub enum InfixDeclaration {
    /// Declared by the module under check. Its span is a byte range in the file
    /// the diagnostic is already being rendered against.
    InThisModule(NodeSpan),
    /// Declared by an imported module whose [`Interface`] knew both the span and
    /// the file it was written in.
    InImportedModule(SourceSpan),
    /// Declared by an imported module whose [`Interface`] could not say which file
    /// it came from — a hand-built one, or one built before its file was known
    /// (see [`Interface::source_span`]). There is nothing honest to underline, so
    /// a diagnostic renders no label rather than one against the wrong file.
    Unknown,
}

impl InfixDeclaration {
    /// A secondary label under this declaration, when there is one to point at.
    ///
    /// `None` covers both the unknown case and a [`NodeSpan`] with no position
    /// behind it — a label at byte 0 of the module under check is worse than no
    /// label at all.
    pub fn label(&self, message: String) -> Option<SpanLabel> {
        match self {
            InfixDeclaration::InThisModule(span) => span.span().map(|span| SpanLabel {
                span,
                message,
                primary: false,
                file: None,
            }),
            InfixDeclaration::InImportedModule(source) => Some(SpanLabel {
                span: source.span,
                message,
                primary: false,
                file: Some(source.file),
            }),
            InfixDeclaration::Unknown => None,
        }
    }
}

/// What the environment records for a resolvable type *name*, as opposed to a type
/// expression built from one.
///
/// A `type Maybe a = …` declaration is a type *constructor*: applying it to
/// arguments is what produces a `Type`, and `Maybe` on its own is not one — there is
/// no such thing as the type `Maybe` with `a` left dangling. Storing the fully
/// applied `Type::Type("Maybe.Maybe", [Variable("a")])` and handing it back verbatim on
/// every lookup, which is what this replaced, conflated the two: it made every
/// application of `Maybe` collapse to the same declaration-shaped type regardless of
/// what was actually written, which is the defect `BUG-17` describes in full.
///
/// `name` is the *declaration's* qualified name, which is never the name the
/// lookup used: one union is inserted under every spelling an import makes
/// available for it, so `Lib.Option`, `Option` and an alias' `L.Option` are three
/// keys onto one entry. `Type::from_parser_type` builds the canonical type out of
/// this name rather than the written one, which is what keeps the three spellings
/// unifiable — and what keeps two modules' `Size` apart, since the module is part
/// of the name each records (`AST-4`).
///
/// `variables` is the declaration's own type variables, in the order the `type`
/// line wrote them — its length is the arity a written application is checked
/// against in `Type::from_parser_type`. The names themselves are not needed for
/// that check (a union type has no body to substitute them into — see
/// `TypeConstructor::type_parameters`, which each variant carries directly and
/// already recorded independently), but keeping them rather than a bare count is
/// what the entry would need were a form with a body — a type alias — to reuse this
/// same map.
///
/// Nothing on the entry says whether the module under check declared the type or an
/// import brought it in, because `name` already does: it is the declaration's own, so
/// its module is the module under check for a declaration and another module for an
/// import. A third source of entries is `new_environment`'s seeding of the scalar
/// types in `zelkova-core`, under the qualified names `scalars::SCALARS` holds; each
/// records the module that declares that scalar, so the same reading holds. `do_exports` reads it that way (`declares_type`), as it reads a class's
/// qualified name — where `ValueType` needs variants, a type's entry carries the answer.
#[derive(Debug, Clone, PartialEq)]
pub(crate) struct TypeArity {
    pub name: QualName,
    pub variables: Vec<Name>,
}

impl TypeArity {
    pub(crate) fn arity(&self) -> usize {
        self.variables.len()
    }
}

/// Environment represent the set of values/types available to a compilation unit.
/// It is derived from previous successful units and is provisioned through a
/// module imports.
///
/// As a whole, the aim of the canonical AST is to not have to worry about the
/// Environment in later phases. We still need one to translate the parser AST.
/// The good news being, it can be local to the canonicalization function.
pub(crate) trait Environment<'parent>: std::fmt::Debug {
    fn find_type(&self, name: &Name) -> Option<&TypeArity>;

    fn module_name(&self) -> &ModuleName;

    fn find_value(&self, name: &Name) -> Option<&ValueType>;

    fn find_type_constructor(&self, name: &Name) -> Option<&TypeConstructor>;

    /// The value names resolvable from this scope right now, for building a
    /// "did you mean …?" suggestion once `find_value` has already failed
    /// (`ERR-7`). Not on the lookup path itself: this walks the whole table,
    /// `find_value` a single key.
    ///
    /// A `Vec` and not a set: [`ScopedEnvironment`] appends its own bindings
    /// to whatever the parent returned, so a name a scope shadows appears
    /// twice. That is harmless here — both entries are the same string, and
    /// [`suggest`](crate::utils::suggest) breaks ties by comparing the
    /// candidates themselves rather than by the order they arrive in, so
    /// neither the duplication nor the parent-before-locals order changes
    /// which name comes back.
    ///
    /// One thing this does *not* mirror from `find_value` is the ordering:
    /// `find_value` checks a scope's own bindings before the parent's, this
    /// appends them last.
    fn value_names(&self) -> Vec<Name>;

    /// Same as [`value_names`](Environment::value_names), for type
    /// constructors. A scope never binds its own, so this is always the root
    /// environment's `constructors` and never carries duplicates.
    fn type_constructor_names(&self) -> Vec<Name>;

    fn local_infix_exists(&self, name: &Name) -> bool;

    /// The [`InfixEntry`] an operator resolves to from this scope — its declared
    /// precedence and associativity, which module declared it and where, and the
    /// backing function it names — or `None` when no `infix` declaration for it
    /// is in scope.
    ///
    /// Canonicalization's infix re-association is the only caller
    /// (`resolve_infix_operator` in `canonical/mod.rs`), and this is the whole
    /// of how an operator resolves: the entry decides both how a flat run of
    /// operator applications (`ExpressionKind::InfixChain`) nests into
    /// `Application` nodes, and what each operator position becomes as a value.
    /// So a lookup that fails here is an operator nothing in scope declares, and
    /// `resolve_infix_operator` reports it with the same `VariableNotFound` a
    /// plain unresolvable variable would get.
    fn find_infix(&self, name: &Name) -> Option<&InfixEntry>;

    #[allow(dead_code)]
    fn insert_local_value(&mut self, name: &Name);

    // 'parent must lives at least as long as 'a
    fn new_scope<'a>(&'a self) -> ScopedEnvironment<'parent, 'a>
    where
        'parent: 'a;
}

/// Build a "did you mean …?" suggestion for a name that failed to resolve,
/// from the full set of names available at the point of failure (`ERR-7`).
///
/// Respects the qualified/unqualified distinction called out on
/// [`super::Error::VariableNotFound`]: a qualified `target` (`Widget.map`)
/// only considers candidates qualified with that exact same module prefix,
/// comparing distance on the local part once the prefix is confirmed equal;
/// an unqualified `target` only considers unqualified candidates. Crossing
/// that boundary would let a typo in one module's name get "fixed" by
/// pointing at an entirely different module's value of the same local name,
/// which is the wrong-module case the ticket calls out explicitly as worse
/// than no suggestion at all.
///
/// The `Environment`'s own candidate sets (`RootEnvironment::variables`,
/// `RootEnvironment::constructors`) hold both forms as distinct keys already
/// — `map` and `Maybe.map` are two separate entries once `Maybe` is
/// imported — so this needs no lookup beyond string-splitting on the last
/// `.`. The three `EnvError` sites that use this — `ValueNotFound`,
/// `UnionNotFound`, `InfixNotFound` — draw from a single `Interface`'s own
/// namespace (`interface.values`, `.unions`, `.infixes`), which never holds
/// a qualified name, so they always take the unqualified branch.
///
/// `InterfaceNotFound` deliberately does *not* come through here: its
/// candidates are module names, where a `.` separates two segments of one
/// identifier rather than a module from a value. `process_import` calls
/// [`suggest`](crate::utils::suggest) over the whole string instead.
pub(crate) fn suggest_name(target: &Name, candidates: impl Iterator<Item = Name>) -> Option<Name> {
    match target.as_str().rsplit_once('.') {
        Some((prefix, local)) => {
            let locals: Vec<String> = candidates
                .filter_map(|c| {
                    c.as_str().rsplit_once('.').and_then(|(p, l)| {
                        if p == prefix {
                            Some(l.to_string())
                        } else {
                            None
                        }
                    })
                })
                .collect();
            let refs: Vec<&str> = locals.iter().map(String::as_str).collect();
            suggest(local, refs).map(|l| Name::new(format!("{}.{}", prefix, l)))
        }
        None => {
            let unqualified: Vec<String> = candidates
                .filter(|c| !c.as_str().contains('.'))
                .map(|c| c.to_string())
                .collect();
            let refs: Vec<&str> = unqualified.iter().map(String::as_str).collect();
            suggest(target.as_str(), refs).map(Name::new)
        }
    }
}

/// Build a module's scope out of the imports it wrote and the ones it did not have
/// to.
///
/// What comes back is the scope and the error of every import that did not resolve, in
/// the order the imports were processed. An import that failed does not end the scope:
/// every import that resolved is in it, and so is every entry of a failed import's
/// `exposing` list that did resolve. The scope is [`incomplete`](RootEnvironment::is_incomplete)
/// when any import failed, and when any import resolved to an [`Interface`] whose own
/// [`incomplete`](Interface::incomplete) is set.
///
/// The implicit half comes first, and goes through `process_import` exactly as a
/// written `import` does, so a name arriving through
/// [`default_imports`](crate::default_imports) resolves exactly like one
/// the file named — including for `insert_foreign_value`, which is what makes two
/// imports of one name ambiguous regardless of which half either came from. The
/// only place the two are told apart is [`ImportOrigin`], carried alongside each
/// candidate purely so `AmbiguousVariables`' note can say which contributor the
/// module never wrote (SPEC-32). That is also why a module that *writes* one of
/// the default imports gets only what it wrote:
/// [`implicit_imports`](crate::default_imports::implicit_imports) drops
/// an entry the file already names, rather than registering `Basics` twice over and
/// turning every use of `+` into an `AmbiguousVariables`.
///
/// `is_core` is [`module_name.package().is_core()`](crate::PackageName::is_core)
/// — the same package-level answer `dependencies::add_default_import_edges` uses to
/// decide this package's implicit edges. A module of `zelkova-core` gets none of the
/// eight, whatever it is named — and, in their place, the five scalar type names
/// ([`LANG-58`](../../../docs/tickets/README.md), [`DEC-15` decision
/// 3](../../../docs/decisions/dec-15.md#3--a-module-that-loses-the-basics-default-import-receives-the-scalar-type-names-in-its-place)):
/// `Int`, `Float`, `Char`, `String` and `Bool`, bound to the qualified names
/// [`scalars::SCALARS`] already holds rather than looked up in `Basics`'
/// `Interface`. A facade underneath `Basics` — `Js.Basics`, `Js.Utils` — has no
/// other way to name the types its signatures use, since writing the import
/// out would be [a cycle](../../../docs/spec/modules.md#imports-may-not-form-a-cycle)
/// and the implicit one is exactly what this package does not receive. Only
/// the type names arrive this way: no constructor and no value, so a module
/// reached by this can annotate a `Bool` and cannot write a `True`.
pub(crate) fn new_environment(
    module_name: &ModuleName,
    interfaces: &HashMap<Name, Interface>,
    imports: &[parser::Import],
) -> (RootEnvironment, Vec<EnvError>) {
    let mut env = RootEnvironment {
        module_name: module_name.clone(),
        infixes: HashMap::new(),
        types: HashMap::new(),
        constructors: HashMap::new(),
        variables: HashMap::new(),
        classes: HashMap::new(),
        class_signatures: HashMap::new(),
        unions: HashMap::new(),
        instances: Vec::new(),
        incomplete: false,
    };
    let mut errors = vec![];

    let is_core = module_name.package().is_core();

    // The compiler knows each scalar's qualified name and arity without
    // reading the module that declares it (`scalars::SCALARS`), so seeding
    // them here consults neither `interfaces` nor `Basics`' own declarations —
    // doing either would recreate the dependency `add_default_import_edges`
    // withholds for this package, and turn this into a diagnostic-free way
    // back into the cycle the default imports are dropped to avoid.
    if is_core {
        for scalar in scalars::SCALARS {
            env.types.insert(
                Name::new(scalar.name),
                TypeArity {
                    name: scalar.qual_name(),
                    variables: vec![],
                },
            );
        }
    }

    let implicit = default_imports::implicit_imports(imports, interfaces, is_core);

    let tagged = implicit
        .iter()
        .map(|import| (import, ImportOrigin::Default))
        .chain(imports.iter().map(|import| (import, ImportOrigin::Written)));

    for (
        parser::Import {
            name,
            alias,
            exposing,
            span,
        },
        origin,
    ) in tagged
    {
        match process_import(&mut env, interfaces, name, alias, exposing, *span, origin) {
            Ok(_) => (),
            Err(err) => {
                // A name the import would have brought in may be missing from the
                // scope, and the error just collected is what says so.
                env.incomplete = true;
                errors.push(err);
            }
        }
    }

    (env, errors)
}

fn process_import(
    env: &mut RootEnvironment,
    interfaces: &HashMap<Name, Interface>,
    imported_module_name: &Name,
    alias: &Option<Name>,
    exposing: &parser::Exposing,
    // The `import` line this is resolving. Only `InterfaceNotFound` uses it: the
    // module name itself is not part of any `parser::Exposed`, so the `import` line
    // is the finest span there is for it. Every other error raised further down
    // names one entry of the exposing list and carries that entry's own span
    // instead (`ERR-9`) — `bar` in `import Foo exposing (bar)`, not the line it
    // sits on.
    span: NodeSpan,
    // Whether this import was written by the module under check or supplied by
    // the default import list — carried onto every `ValueType::Foreign` this
    // call produces, purely for `AmbiguousVariables`' diagnostic (SPEC-32).
    origin: ImportOrigin,
) -> Result<(), EnvError> {
    let interface = interfaces.get(imported_module_name).ok_or_else(|| {
        // Module names live in a flat namespace and a dotted one — `Js.Basics` —
        // is a single opaque identifier, not a prefix plus a local part. So this
        // measures the distance over the whole string with `suggest` rather than
        // going through `suggest_name`, whose qualified/unqualified split is
        // about `Name` vs `QualName` for values and constructors. Splitting here
        // would silently drop every typo outside the last segment: `Jz.Basics`
        // and `JsBasics` are both one edit from `Js.Basics`, and neither shares
        // its prefix.
        let suggestion = suggest(
            imported_module_name.as_str(),
            interfaces.keys().map(Name::as_str),
        )
        .map(Name::new);
        EnvError::InterfaceNotFound(imported_module_name.clone(), span, suggestion)
    })?;

    trace!(
        "process_import(imported_module_name={:?}, alias={:?}, exposing: {:?})",
        imported_module_name,
        alias,
        exposing
    );

    // A name this module's importers look for here may be one it declares and could not
    // publish, so nothing missing from the scope can be blamed on this module's
    // importer alone.
    if interface.incomplete {
        env.incomplete = true;
    }

    // Every instance the interface carries is in scope, whatever this import exposes:
    // an instance has no name for an `exposing` list to carry, and coherence needs it
    // wherever its class and its type are
    // ([Type classes](../../../docs/spec/type-classes.md#declaring-an-instance)).
    for published in &interface.instances {
        env.insert_imported_instance(published);
    }

    // Every union the interface carries is known by its declaration, which is how a
    // derived instance finds the constructors of a type however it was spelled.
    for (union_name, union) in &interface.unions {
        env.unions.insert(
            interface.module_name.qualify_name(union_name),
            union.clone(),
        );
    }

    // First we insert all values/types from the module, prefixed with the module name or its alias
    let prefix = alias.as_ref().unwrap_or(imported_module_name);

    // A class and its members are reachable qualified whatever the import exposes, as
    // a value and a type are.
    for (class_name, signature) in &interface.classes {
        insert_foreign_class(env, Some(prefix), interface, class_name, signature, origin);
    }

    for (value_name, signature) in &interface.values {
        insert_foreign_value(
            env,
            value_name.clone().qualify_with(prefix.to_string()),
            signature.tpe.clone(),
            interface.source_span(signature.span),
            &interface.module_name,
            origin,
        );
    }

    for (union_name, union) in &interface.unions {
        insert_foreign_union_type(
            env,
            Some(prefix),
            &interface.module_name,
            union_name,
            &union.variables,
            union.variants.iter(),
        );
    }

    // TODO Infix ?

    // Then we insert unqualified values/types
    match exposing {
        parser::Exposing::Open => {
            // We add everything to the current environment

            for (value_name, signature) in &interface.values {
                insert_foreign_value(
                    env,
                    value_name.clone(),
                    signature.tpe.clone(),
                    interface.source_span(signature.span),
                    &interface.module_name,
                    origin,
                );
            }

            for (op_name, infix) in &interface.infixes {
                env.infixes
                    .insert(op_name.clone(), imported_infix(interface, infix));
            }

            for (class_name, signature) in &interface.classes {
                insert_foreign_class(env, None, interface, class_name, signature, origin);
            }

            // We need to insert the type without any qualifier, including variants
            for (union_name, union) in &interface.unions {
                insert_foreign_union_type(
                    env,
                    None,
                    &interface.module_name,
                    union_name,
                    &union.variables,
                    union.variants.iter(),
                );
            }
        }

        parser::Exposing::Explicit(exposeds) => {
            // We only add the explicitly named types/values/infixes
            let iter = exposeds.iter().map(|exposed| {
                match &exposed.kind {
                    parser::ExposedKind::Lower(value_name) => {
                        let Some(signature) = interface.values.get(value_name) else {
                            // A class member may be named on its own, as any exposed
                            // value may.
                            if let Some(member) = interface
                                .classes
                                .values()
                                .flat_map(|signature| signature.members.iter())
                                .find(|member| &member.name == value_name)
                            {
                                insert_foreign_value(
                                    env,
                                    value_name.clone(),
                                    member.tpe.clone(),
                                    interface.source_span(member.span),
                                    &interface.module_name,
                                    origin,
                                );
                                return Ok(());
                            }

                            // Missing from an interface that is missing names it
                            // could not publish: the entry restates that failure.
                            if interface.incomplete {
                                return Ok(());
                            }
                            let suggestion =
                                suggest_name(value_name, interface.values.keys().cloned());
                            return Err(EnvError::ValueNotFound(
                                value_name.clone(),
                                exposed.span,
                                suggestion,
                            ));
                        };

                        insert_foreign_value(
                            env,
                            value_name.clone(),
                            signature.tpe.clone(),
                            interface.source_span(signature.span),
                            &interface.module_name,
                            origin,
                        );
                    }
                    parser::ExposedKind::Upper(type_name, parser::Privacy::Private) => {
                        // `Size` and `Size(..)` are one entry differing only in
                        // whether the constructors come along, so the name itself is
                        // checked the same way in both and reports the same
                        // `UnionNotFound`. Only the `Public` arm below also asks
                        // whether the module exposed the constructors: this one
                        // never reads `variants`, so a type exposed opaquely is
                        // exactly what it asks for.
                        //
                        // A bare uppercase name may also be a class, which brings its
                        // members along unqualified.
                        let Some(union) = interface.unions.get(type_name) else {
                            if let Some(signature) = interface.classes.get(type_name) {
                                insert_foreign_class(
                                    env, None, interface, type_name, signature, origin,
                                );
                                return Ok(());
                            }
                            if interface.incomplete {
                                return Ok(());
                            }
                            let suggestion =
                                suggest_name(type_name, interface.unions.keys().cloned());
                            return Err(EnvError::UnionNotFound(
                                type_name.clone(),
                                exposed.span,
                                suggestion,
                            ));
                        };

                        // Add the type without qualifier and without constructors
                        // (they are private), but with the declaration's own type
                        // variables: an opaque `Option` is still `Option a`, and
                        // every later application of it is measured against this
                        // arity.
                        env.types.insert(
                            type_name.clone(),
                            TypeArity {
                                name: interface.module_name.qualify_name(type_name),
                                variables: union.variables.clone(),
                            },
                        );
                    }
                    parser::ExposedKind::Upper(type_name, parser::Privacy::Public) => {
                        let Some(union) = interface.unions.get(type_name) else {
                            // A class has no constructors for `(..)` to bring in.
                            if interface.classes.contains_key(type_name) {
                                return Err(EnvError::ClassHasNoConstructors(
                                    type_name.clone(),
                                    exposed.span,
                                ));
                            }
                            if interface.incomplete {
                                return Ok(());
                            }
                            let suggestion =
                                suggest_name(type_name, interface.unions.keys().cloned());
                            return Err(EnvError::UnionNotFound(
                                type_name.clone(),
                                exposed.span,
                                suggestion,
                            ));
                        };

                        // An opaque export's `variants` is empty, as is that of a
                        // type declared with none (which LANG-10 is to reject);
                        // `opaque_unions` is what tells the two apart. Inserting the first would hand over a
                        // constructor-less type in place of what `(..)` asked for.
                        if interface.opaque_unions.contains(type_name) {
                            return Err(EnvError::ConstructorsNotExposed(
                                type_name.clone(),
                                imported_module_name.clone(),
                                exposed.span,
                            ));
                        }

                        insert_foreign_union_type(
                            env,
                            None,
                            &interface.module_name,
                            type_name,
                            &union.variables,
                            union.variants.iter(),
                        );
                    }
                    parser::ExposedKind::Operator(variable_name) => {
                        let Some(infix) = interface.infixes.get(variable_name) else {
                            if interface.incomplete {
                                return Ok(());
                            }
                            let suggestion =
                                suggest_name(variable_name, interface.infixes.keys().cloned());
                            return Err(EnvError::InfixNotFound(
                                variable_name.clone(),
                                exposed.span,
                                suggestion,
                            ));
                        };

                        // The entry is the whole of what the importer gets: it
                        // carries the backing function alongside the precedence
                        // and associativity, so naming the operator here is
                        // enough on its own. Nothing is inserted into
                        // `env.variables` — an operator is not a value name.
                        env.infixes
                            .insert(variable_name.clone(), imported_infix(interface, infix));
                    }
                };

                Ok(())
            });

            collect_accumulate::<_, _, _, ()>(iter).map_err(EnvError::Multiple)?;
        }
    };

    Ok(())
}

/// An [`InfixEntry`] for an operator taken out of an imported module's
/// [`Interface`], carrying the file that interface was read from so a diagnostic
/// about it underlines the *exporting* module's source and not the importing one's.
///
/// `Interface::source_span` declines when either half is missing, and
/// [`InfixDeclaration::Unknown`] is that answer: the label is dropped rather than
/// rendered against the wrong file.
///
/// The backing function is resolved here too, against the exporting interface,
/// which is what lets an `exposing` list name the operator on its own — see
/// [`InfixFunction`]. Two places in that interface can carry its type, and they are
/// disjoint by construction ([`Interface::infix_functions`] holds only what
/// [`Interface::values`] does not), so the order they are consulted in does not
/// matter.
fn imported_infix(interface: &Interface, infix: &Infix) -> InfixEntry {
    let declaration = match interface.source_span(infix.span) {
        Some(source) => InfixDeclaration::InImportedModule(source),
        None => InfixDeclaration::Unknown,
    };

    // A member of a class the module exposes may back an operator too, and its type is
    // its member signature, with the class's constraint in front, which the typer declares
    // for the member and so for a use of the operator.
    let member = || {
        interface
            .classes
            .values()
            .flat_map(|signature| signature.members.iter())
            .find(|member| member.name == infix.function_name)
            .map(|member| &member.tpe)
    };

    let function = match interface
        .values
        .get(&infix.function_name)
        .or_else(|| interface.infix_functions.get(&infix.function_name))
        .map(|signature| &signature.tpe)
        .or_else(member)
    {
        Some(tpe) => InfixFunction::Imported(interface.module_name.clone(), tpe.clone()),
        None => InfixFunction::ImportedUntyped(interface.module_name.clone()),
    };

    InfixEntry {
        infix: infix.clone(),
        declaration,
        function,
    }
}

/// Register an imported union under one spelling — `qualifier` is the prefix the
/// importing module reaches it by (the module's own name, or the alias it wrote),
/// or `None` for the unqualified spelling an `exposing` list adds.
///
/// `declaring_module` is a separate parameter precisely because it is not the
/// qualifier: the key a lookup uses is the spelling, and the [`TypeArity`] it
/// finds records the declaration. `import Widget as W` inserts `W.Size` as a key
/// and `Widget.Size` as the name, so an annotation written `W.Size` canonicalizes
/// to the type `Widget` declared (`AST-4`).
fn insert_foreign_union_type<'a, I: Iterator<Item = &'a TypeConstructor>>(
    env: &mut RootEnvironment,
    qualifier: Option<&Name>,
    declaring_module: &ModuleName,
    union_name: &Name,
    variables: &[Name],
    variants: I,
) {
    // If there is a given qualifier use it, otherwise use the name as is
    let qualify = |n: &Name| match qualifier {
        Some(q) => n.clone().qualify_with(q.to_string()),
        None => n.clone(),
    };

    env.types.insert(
        qualify(union_name),
        TypeArity {
            name: declaring_module.qualify_name(union_name),
            variables: variables.to_vec(),
        },
    );

    for variant in variants {
        // Variant are not qualified, which means we have to alias/qualify them as needed
        env.constructors
            .insert(qualify(&variant.name), variant.clone());
    }
}

/// Register a class `interface` exposes under one spelling, as
/// [`insert_foreign_union_type`] registers a union: `qualifier` is the prefix the
/// importing module reaches it by, or `None` for the unqualified spelling an `exposing`
/// list adds. Every member of the class arrives with it under the same spelling, as a
/// value whose type is its member signature.
///
/// The members are not in [`Interface::values`], so the typer declares them from the class
/// instead: each is its signature with the class's constraint in front.
fn insert_foreign_class(
    env: &mut RootEnvironment,
    qualifier: Option<&Name>,
    interface: &Interface,
    class_name: &Name,
    signature: &ClassSignature,
    origin: ImportOrigin,
) {
    let qualify = |n: &Name| match qualifier {
        Some(q) => n.clone().qualify_with(q.to_string()),
        None => n.clone(),
    };

    let declared = interface.module_name.qualify_name(class_name);
    env.classes.insert(qualify(class_name), declared.clone());
    env.class_signatures.insert(declared, signature.clone());

    for member in &signature.members {
        insert_foreign_value(
            env,
            qualify(&member.name),
            member.tpe.clone(),
            interface.source_span(member.span),
            &interface.module_name,
            origin,
        );
    }
}

fn insert_foreign_value(
    env: &mut RootEnvironment,
    name: Name,
    tpe: Type,
    source: Option<SourceSpan>,
    module_name: &ModuleName,
    origin: ImportOrigin,
) {
    let vt = ValueType::Foreign(module_name.clone(), source, tpe.clone(), origin);

    // Can it be done more efficiently by using get_mut ?
    match env.variables.remove(&name) {
        Some(ValueType::Foreign(module, prev_source, _, prev_origin)) => {
            env.variables.insert(
                name,
                ValueType::Foreigns(vec![
                    (module_name.clone(), source, origin),
                    (module, prev_source, prev_origin),
                ]),
            );
        }
        Some(ValueType::Foreigns(mut vec)) => {
            vec.push((module_name.clone(), source, origin));
            env.variables.insert(name, ValueType::Foreigns(vec));
        }
        None => {
            env.variables.insert(name, vt);
        }
        _ => todo!("find out what to do in those cases"),
    }
}

#[derive(Debug)]
pub enum EnvError {
    /// No module of that name was available to import, where the `import` was
    /// written, and — when one candidate module name is a close enough
    /// typo-distance match (`ERR-7`) — a suggestion for what was meant.
    InterfaceNotFound(Name, NodeSpan, Option<Name>),
    /// A `TypeIdent(..)` in an `exposing` list naming a type the imported module
    /// does not declare, where that name was written (`ERR-9`), and an optional
    /// "did you mean …?" suggestion (`ERR-7`).
    UnionNotFound(Name, NodeSpan, Option<Name>),
    /// A `TypeIdent(..)` in an `exposing` list naming a type the imported module
    /// exposes only opaquely — a bare `TypeIdent` in its own header — so the
    /// constructors it asks for are not there to import. Carries the type's name,
    /// the module name as the `import` wrote it, and where the entry was written.
    ConstructorsNotExposed(Name, Name, NodeSpan),
    /// An `(op)` in an `exposing` list naming an infix the imported module does not
    /// declare, where that name was written (`ERR-9`), and an optional "did you
    /// mean …?" suggestion (`ERR-7`).
    InfixNotFound(Name, NodeSpan, Option<Name>),
    /// A lowercase name in an `exposing` list naming a value the imported module
    /// does not declare, where that name was written (`ERR-9`), and an optional
    /// "did you mean …?" suggestion (`ERR-7`).
    ValueNotFound(Name, NodeSpan, Option<Name>),
    /// `Name(..)` in an `exposing` list naming a class the imported module exposes, and
    /// where the entry was written. A class has no constructors for `(..)` to bring in.
    ClassHasNoConstructors(Name, NodeSpan),
    Multiple(Vec<EnvError>),
}

/// A "did you mean `X`?" suffix for a label message, when a suggestion was
/// found — empty otherwise, so callers can always append the result without
/// checking `is_some()` first (`ERR-7`).
fn suggestion_suffix(suggestion: &Option<Name>) -> String {
    match suggestion {
        Some(name) => format!(" — did you mean `{}`?", name),
        None => String::new(),
    }
}

/// An import that could not be resolved always names the thing it could not find,
/// so the message can quote it back.
impl PhaseError for EnvError {
    fn message(&self) -> String {
        match self {
            EnvError::InterfaceNotFound(name, _, _) => {
                format!("cannot find a module named `{}` to import", name)
            }
            EnvError::UnionNotFound(name, _, _) => {
                format!(
                    "the imported module does not expose a type named `{}`",
                    name
                )
            }
            EnvError::ConstructorsNotExposed(name, module, _) => format!(
                "`{}` exposes the type `{}` but not its constructors",
                module, name
            ),
            EnvError::InfixNotFound(name, _, _) => format!(
                "the imported module does not expose an infix operator named `{}`",
                name
            ),
            EnvError::ValueNotFound(name, _, _) => format!(
                "the imported module does not expose a value named `{}`",
                name
            ),
            EnvError::ClassHasNoConstructors(name, _) => format!(
                "`{}` is a class, and a class has no constructors to import",
                name
            ),
            EnvError::Multiple(errors) => match errors.as_slice() {
                [only] => only.message(),
                many => format!("{} imports could not be resolved", many.len()),
            },
        }
    }

    fn labels(&self) -> Vec<SpanLabel> {
        let primary = |span: &NodeSpan, message: String| match span.span() {
            Some(span) => vec![SpanLabel {
                span,
                message,
                primary: true,
                file: None,
            }],
            None => Vec::new(),
        };

        match self {
            EnvError::InterfaceNotFound(_, span, suggestion) => primary(
                span,
                format!(
                    "no module of this name was found{}",
                    suggestion_suffix(suggestion)
                ),
            ),
            EnvError::UnionNotFound(name, span, suggestion) => primary(
                span,
                format!(
                    "`{}` is not exposed by the imported module{}",
                    name,
                    suggestion_suffix(suggestion)
                ),
            ),
            EnvError::ConstructorsNotExposed(name, module, span) => primary(
                span,
                format!(
                    "`{}(..)` asks for constructors `{}` does not expose",
                    name, module
                ),
            ),
            EnvError::InfixNotFound(name, span, suggestion) => primary(
                span,
                format!(
                    "`{}` is not exposed by the imported module{}",
                    name,
                    suggestion_suffix(suggestion)
                ),
            ),
            EnvError::ValueNotFound(name, span, suggestion) => primary(
                span,
                format!(
                    "`{}` is not exposed by the imported module{}",
                    name,
                    suggestion_suffix(suggestion)
                ),
            ),
            EnvError::ClassHasNoConstructors(name, span) => primary(
                span,
                format!("`{}(..)` asks for constructors a class does not have", name),
            ),
            EnvError::Multiple(errors) => errors.iter().flat_map(|e| e.labels()).collect(),
        }
    }

    fn notes(&self) -> Vec<String> {
        match self {
            EnvError::Multiple(errors) => match errors.as_slice() {
                [only] => only.notes(),
                many => many.iter().flat_map(|e| e.message_and_notes()).collect(),
            },
            EnvError::ConstructorsNotExposed(name, _, _) => vec![format!(
                "write `{}` without `(..)` to import the type alone",
                name
            )],
            EnvError::ClassHasNoConstructors(name, _) => vec![format!(
                "write `{}` without `(..)`: naming a class imports it with every member",
                name
            )],
            _ => Vec::new(),
        }
    }
}

/// RootEnvironment represents the top level module and contains information accessible
/// from the entire module.
///
/// This is opposed to a ScopedEnvironment which contains
/// additional information available only to a scoped expression (eg. local variable)
#[derive(Debug)]
pub(crate) struct RootEnvironment {
    module_name: ModuleName,
    infixes: HashMap<Name, InfixEntry>,
    types: HashMap<Name, TypeArity>,
    constructors: HashMap<Name, TypeConstructor>,
    variables: HashMap<Name, ValueType>,
    /// Every class name in scope, under each spelling that reaches it, to the class's
    /// declaration. A class shares the types namespace and is kept apart from `types`,
    /// because a class name is not a type.
    classes: HashMap<Name, QualName>,
    /// What each class in scope declares, by its declaration's name. A class of this
    /// module is here once its signature canonicalized, and not before.
    class_signatures: HashMap<QualName, ClassSignature>,
    /// Every union in reach, by its declaration's name: this module's own, and each one an
    /// import's interface carries, with no variants when the interface exposes it opaque.
    /// What a derived instance reads its type's constructors off.
    unions: HashMap<QualName, UnionType>,
    /// Every instance an import brought into scope, each once however many routes
    /// reached it.
    instances: Vec<PublishedInstance>,
    /// Whether a name could be missing from this scope for a reason already reported.
    /// See [`is_incomplete`](Self::is_incomplete).
    incomplete: bool,
}

impl RootEnvironment {
    /// Whether a name could be missing from this scope for a reason that has already
    /// been reported: an import that did not resolve, an import of a module whose own
    /// [`Interface::incomplete`] is set, or, once `canonicalize_recovering` says so, a
    /// `type` or `infix` declaration of this module that failed.
    ///
    /// A not-found error raised against an incomplete scope restates one of those
    /// failures, and `canonicalize_recovering` drops it (`without_restated`).
    pub(crate) fn is_incomplete(&self) -> bool {
        self.incomplete
    }

    /// Mark this scope [incomplete](Self::is_incomplete).
    pub(crate) fn set_incomplete(&mut self) {
        self.incomplete = true;
    }

    // TODO Do we need a local/foreign distinction for infixes ? (or in general ?)
    pub(crate) fn insert_local_infix(&mut self, name: Name, infix: Infix) {
        let declaration = InfixDeclaration::InThisModule(infix.span);

        self.infixes.insert(
            name,
            InfixEntry {
                infix,
                declaration,
                function: InfixFunction::Local,
            },
        );
    }

    // TODO Use insert_foreign_value (and rename to remove the foreign part)
    // TODO Return an error if declaration already exists
    pub(crate) fn insert_top_level_value(&mut self, name: Name) {
        self.variables.insert(name, ValueType::TopLevel);
    }

    /// Register a `type` declaration of the module under check by name and
    /// arity alone, before anything has canonicalized its body.
    ///
    /// A declared type name is in scope throughout its own module, so the
    /// bodies being canonicalized may already name it — a declaration naming
    /// itself (`type Never = JustOneMore Never`) or a sibling declared further
    /// down the file. Only the arity is needed for that, and the `type` line
    /// carries it, so the whole set can be registered up front and each entry's
    /// constructors filled in by [`insert_union_type`](Self::insert_union_type)
    /// once the bodies exist.
    pub(crate) fn insert_declared_type(&mut self, name: &Name, variables: Vec<Name>) {
        // The declaration is the module under check's own, so this environment's
        // module name is the one it belongs to (`AST-4`).
        let qualified = self.module_name.qualify_name(name);

        self.types.insert(
            name.clone(),
            TypeArity {
                name: qualified,
                variables,
            },
        );
    }

    /// Register the name of a `class` declaration of the module under check, before
    /// anything has canonicalized it, so that a superclass or an instance can name a
    /// class written further down the file.
    pub(crate) fn insert_declared_class(&mut self, name: &Name) {
        let qualified = self.module_name.qualify_name(name);
        self.classes.insert(name.clone(), qualified);
    }

    /// Record the signature of a `class` declaration of the module under check.
    pub(crate) fn insert_class_signature(&mut self, name: &Name, signature: ClassSignature) {
        let qualified = self.module_name.qualify_name(name);
        self.class_signatures.insert(qualified, signature);
    }

    /// The declaration a class name written in this module resolves to.
    pub(crate) fn find_class(&self, name: &Name) -> Option<&QualName> {
        self.classes.get(name)
    }

    /// What the class `name` declares, when it is in scope and its declaration
    /// canonicalized.
    pub(crate) fn class_signature(&self, name: &QualName) -> Option<&ClassSignature> {
        self.class_signatures.get(name)
    }

    /// The union `name` declares, when it is this module's own or an import's interface
    /// carries it. Its variants are empty when it was imported opaque.
    pub(crate) fn find_union(&self, name: &QualName) -> Option<&UnionType> {
        self.unions.get(name)
    }

    /// Every instance the imports brought into scope.
    pub(crate) fn imported_instances(&self) -> &[PublishedInstance] {
        &self.instances
    }

    /// Bring an imported instance into scope, unless another route already did.
    fn insert_imported_instance(&mut self, published: &PublishedInstance) {
        if !self
            .instances
            .iter()
            .any(|known| known.same_declaration(published))
        {
            self.instances.push(published.clone());
        }
    }

    // TODO Use insert_foreign_union_type (and rename to remove the foreign part)
    pub(crate) fn insert_union_type(&mut self, name: Name, union: UnionType) {
        self.unions
            .insert(self.module_name.qualify_name(&name), union.clone());
        self.insert_declared_type(&name, union.variables);

        for tctor in union.variants {
            self.constructors.insert(tctor.name.clone(), tctor.clone());
        }
    }
}

impl<'p> Environment<'p> for RootEnvironment {
    fn module_name(&self) -> &ModuleName {
        &self.module_name
    }

    fn find_type(&self, name: &Name) -> Option<&TypeArity> {
        self.types.get(name)
    }

    /// Value names only. An operator symbol is never a key here — an `infix`
    /// declaration goes into `infixes`, and no other insertion can produce one,
    /// since a function's own name always comes from `VarIdent`, a distinct token
    /// from `Op`. Operators resolve through [`find_infix`](Environment::find_infix)
    /// and [`InfixFunction`] instead.
    fn find_value(&self, name: &Name) -> Option<&ValueType> {
        self.variables.get(name)
    }

    fn find_type_constructor(&self, name: &Name) -> Option<&TypeConstructor> {
        self.constructors.get(name)
    }

    fn value_names(&self) -> Vec<Name> {
        self.variables.keys().cloned().collect()
    }

    fn type_constructor_names(&self) -> Vec<Name> {
        self.constructors.keys().cloned().collect()
    }

    fn local_infix_exists(&self, name: &Name) -> bool {
        self.infixes.contains_key(name)
    }

    fn find_infix(&self, name: &Name) -> Option<&InfixEntry> {
        self.infixes.get(name)
    }

    // TODO Return error if name already exists
    // Use import_foreign_value ?
    fn insert_local_value(&mut self, name: &Name) {
        self.variables.insert(name.clone(), ValueType::Local);
    }

    fn new_scope<'a>(&'a self) -> ScopedEnvironment<'p, 'a>
    where
        'p: 'a,
    {
        ScopedEnvironment {
            parent: self,
            variables: HashMap::new(),
        }
    }
}

/// An Environment scoped to a module's sub expression (`let`, function, etc…)
#[derive(Debug)]
pub(crate) struct ScopedEnvironment<'root, 'parent> {
    parent: &'parent dyn Environment<'root>,
    variables: HashMap<Name, ValueType>,
}

impl<'root, 'parent> Environment<'parent> for ScopedEnvironment<'root, 'parent> {
    fn find_type(&self, name: &Name) -> Option<&TypeArity> {
        self.parent.find_type(name)
    }

    fn module_name(&self) -> &ModuleName {
        self.parent.module_name()
    }

    /// A plain lookup in this scope's own bindings, falling back to the
    /// parent's `find_value` unchanged — the key handed in is the key looked
    /// up, at both levels, with no redirect or alias in between (audited for
    /// `BUG-27`, closed: the class of bug that ticket described needs a
    /// lookup that lands on a *different* name than the one passed in, and
    /// nothing on this path does that. `self.variables` only ever holds
    /// [`ValueType::Local`] entries a pattern bound directly, under their own
    /// name — see [`ScopedEnvironment::expose_pattern`]).
    fn find_value(&self, name: &Name) -> Option<&ValueType> {
        self.variables.get(name).or(self.parent.find_value(name))
    }

    fn find_type_constructor(&self, name: &Name) -> Option<&TypeConstructor> {
        self.parent.find_type_constructor(name)
    }

    fn value_names(&self) -> Vec<Name> {
        let mut names = self.parent.value_names();
        names.extend(self.variables.keys().cloned());
        names
    }

    fn type_constructor_names(&self) -> Vec<Name> {
        // A scope never binds its own constructors — only patterns bind
        // values (`expose_pattern`) — so this always delegates.
        self.parent.type_constructor_names()
    }

    fn local_infix_exists(&self, name: &Name) -> bool {
        self.parent.local_infix_exists(name)
    }

    fn find_infix(&self, name: &Name) -> Option<&InfixEntry> {
        self.parent.find_infix(name)
    }

    // TODO Return error if name already exists
    // Needs to reuse the logic in import_foreign_value
    fn insert_local_value(&mut self, name: &Name) {
        self.variables.insert(name.clone(), ValueType::Local);
    }

    fn new_scope<'a>(&'a self) -> ScopedEnvironment<'parent, 'a>
    where
        'parent: 'a,
    {
        let parent: &'a dyn Environment<'parent> = self;

        ScopedEnvironment {
            parent,
            variables: HashMap::new(),
        }
    }
}

impl<'root, 'parent> ScopedEnvironment<'root, 'parent> {
    pub(crate) fn expose_pattern(&mut self, pattern: &Pattern) {
        match &pattern.kind {
            PatternKind::Anything => (),
            PatternKind::Int(_) => (),
            PatternKind::Float(_) => (),
            PatternKind::Char(_) => (),
            PatternKind::String(_) => (),
            PatternKind::Unit => (),

            PatternKind::Variable(n) => {
                self.variables.insert(n.clone(), ValueType::Local);
            }
            PatternKind::Tuple(tuple) => {
                for pattern in tuple.iter() {
                    self.expose_pattern(pattern);
                }
            }
            // A constructor that did not resolve still binds what its arguments bind, so
            // a use of one of those names is not reported as a second missing name.
            PatternKind::Constructor { args, .. } | PatternKind::Hole(args) => {
                for arg in args {
                    self.expose_pattern(arg);
                }
            }
            // A record pattern binds what its entries' patterns bind, and nothing for its
            // labels: a label is not a value, and `{ x }` binds `x` only because the
            // grammar made it `x = x`.
            PatternKind::Record(fields) => {
                for field in fields {
                    self.expose_pattern(&field.pattern);
                }
            }
        }
    }
}

// TODO Tests needs some love to make them easier to read. Currently the assert_eq are making it
// hard to grok what is being verified.
#[cfg(test)]
mod tests {
    use super::*;
    use crate::canonical::*;

    /// [`new_environment`], read as all-or-nothing: the scope when every import
    /// resolved, otherwise the errors of the ones that did not.
    fn resolved(
        module_name: &ModuleName,
        interfaces: &HashMap<Name, Interface>,
        imports: &[parser::Import],
    ) -> Result<RootEnvironment, Vec<EnvError>> {
        let (env, errors) = new_environment(module_name, interfaces, imports);
        if errors.is_empty() {
            Ok(env)
        } else {
            Err(errors)
        }
    }

    fn module_name() -> ModuleName {
        ModuleName::new(PackageName::new("author-project").unwrap(), "module".into())
    }

    fn import(name: Name, alias: Option<Name>, exposing: parser::Exposing) -> parser::Import {
        parser::Import {
            name,
            alias,
            exposing,
            // Hand-built, not parsed: there is no source text behind it.
            span: NodeSpan::none(),
        }
    }

    fn exposing_open() -> parser::Exposing {
        parser::Exposing::Open
    }

    fn exposing_explicit(exposeds: Vec<parser::Exposed>) -> parser::Exposing {
        parser::Exposing::Explicit(exposeds)
    }

    // module Maybe exposing (andThen, map, withDefault, Maybe(..))
    fn maybe_interface() -> (Name, Interface) {
        let type_var = |name: &str| Type::Variable(name.into());

        // A type's canonical head names the module that declared it, so the
        // `Maybe` this interface exports is `Maybe.Maybe`.
        let type_hk = |name: &str, params| {
            Type::Type(
                QualName::parse(PackageName::core(), format!("Maybe.{}", name)).unwrap(),
                params,
            )
        };

        let type_fun = |t1, t2| Type::Arrow(Box::new(t1), Box::new(t2));

        let mut values = HashMap::new();
        // andThen : (a -> Maybe b) -> Maybe a -> Maybe b
        values.insert(
            "andThen".into(),
            ValueSignature::unconstrained(
                // Hand-built, not canonicalized from source: no position behind it.
                NodeSpan::none(),
                type_fun(
                    type_fun(type_var("a"), type_hk("Maybe", vec![type_var("b")])),
                    type_fun(
                        type_hk("Maybe", vec![type_var("a")]),
                        type_hk("Maybe", vec![type_var("b")]),
                    ),
                ),
            ),
        );
        // map : (a -> b) -> Maybe a -> Maybe b
        values.insert(
            "map".into(),
            ValueSignature::unconstrained(
                NodeSpan::none(),
                type_fun(
                    type_fun(type_var("a"), type_var("b")),
                    type_fun(
                        type_hk("Maybe", vec![type_var("a")]),
                        type_hk("Maybe", vec![type_var("b")]),
                    ),
                ),
            ),
        );
        // withDefault : a -> Maybe a -> a
        values.insert(
            "withDefault".into(),
            ValueSignature::unconstrained(
                NodeSpan::none(),
                type_fun(
                    type_var("a"),
                    type_fun(type_hk("Maybe", vec![type_var("a")]), type_var("a")),
                ),
            ),
        );

        let mut unions = HashMap::new();
        unions.insert(
            "Maybe".into(),
            UnionType {
                span: NodeSpan::none(),
                variables: vec![],
                variants: vec![
                    TypeConstructor {
                        name: "Just".into(),
                        type_parameters: vec![Type::Variable("a".into())],
                        tpe: QualName::parse(PackageName::core(), "Maybe.Maybe").unwrap(),
                    },
                    TypeConstructor {
                        name: "Nothing".into(),
                        type_parameters: vec![],
                        tpe: QualName::parse(PackageName::core(), "Maybe.Maybe").unwrap(),
                    },
                ],
            },
        );

        let interface = Interface {
            module_name: ModuleName::new(PackageName::new("zelkova-core").unwrap(), "Maybe".into()),
            values,
            unions,
            opaque_unions: Default::default(),
            infixes: HashMap::new(),
            infix_functions: HashMap::new(),
            arities: HashMap::new(),
            classes: HashMap::new(),
            instances: Vec::new(),
            file: None,
            incomplete: false,
        };

        ("Maybe".into(), interface)
    }

    /// A module that writes no imports, in a package that provides nothing to
    /// import, has an empty scope.
    ///
    /// The interfaces map is empty and that is now load-bearing: `Maybe` is on the
    /// [default import list](crate::default_imports), so a package that
    /// *has* a `Maybe` puts it in scope here without a written `import` —
    /// `default_imports_reach_a_module_that_wrote_none` below is that case.
    #[test]
    fn new_no_imports() -> Result<(), Vec<EnvError>> {
        let interfaces = HashMap::new();
        let env = resolved(&module_name(), &interfaces, &[])?;

        assert_eq!(env.infixes.len(), 0, "infixes={:?}", env.infixes);
        assert_eq!(env.types.len(), 0, "types={:?}", env.types); // qual + explicit
        assert_eq!(
            env.constructors.len(),
            0,
            "constructors:{:?}",
            env.constructors
        );
        assert_eq!(env.variables.len(), 0, "variables={:?}", env.variables); // qual + explicit

        Ok(())
    }

    /// `LANG-8`: a module with no `import` line at all still resolves `Maybe`,
    /// `Just` and `Maybe.map`, because `Maybe` is on the default import list and
    /// the package provides it.
    ///
    /// Asserted through the same `find_*` lookups `new_import_type_with_constructors`
    /// uses for a written `import Maybe exposing (Maybe(..))`, because that is the
    /// claim: an implicitly imported name is indistinguishable from one the file
    /// named. `withDefault` is the counter-assertion — the entry exposes the type
    /// and not the module's values, so it is reachable only qualified.
    ///
    /// Mutation-checked by dropping the `implicit` half of `new_environment`'s
    /// import loop: every assertion below goes red.
    #[test]
    fn default_imports_reach_a_module_that_wrote_none() -> Result<(), Vec<EnvError>> {
        let mut interfaces = HashMap::new();
        {
            let (name, iface) = maybe_interface();
            interfaces.insert(name, iface);
        }
        let env = resolved(&module_name(), &interfaces, &[])?;

        assert!(
            env.find_type(&"Maybe".into()).is_some(),
            "type Maybe not found"
        );
        assert!(
            env.find_type_constructor(&"Just".into()).is_some(),
            "type constructor Just not found"
        );
        assert!(
            env.find_value(&"Maybe.withDefault".into()).is_some(),
            "value Maybe.withDefault not found"
        );
        assert!(
            env.find_value(&"withDefault".into()).is_none(),
            "`exposing (Maybe(..))` names the type, not the module's values"
        );

        Ok(())
    }

    /// The `Char` and `String` entries expose their types: a module that wrote no
    /// import resolves `Char` and `String` unqualified, and reaches `String.length`
    /// only qualified.
    ///
    /// Mutation-checked by setting both entries of `DEFAULT_IMPORTS` back to
    /// `Unqualified::Nothing`: `Char` is no longer found.
    #[test]
    fn char_and_string_default_imports_expose_their_types() -> Result<(), Vec<EnvError>> {
        // An opaque `type <module>` declared by `module`, plus a `length` for `String`.
        let scalar_interface = |module: &str| {
            let mut unions = HashMap::new();
            unions.insert(
                Name::new(module),
                UnionType {
                    span: NodeSpan::none(),
                    variables: vec![],
                    variants: vec![],
                },
            );

            let mut values = HashMap::new();
            values.insert(
                "length".into(),
                ValueSignature::unconstrained(
                    NodeSpan::none(),
                    Type::Type(
                        QualName::parse(PackageName::core(), "Basics.Int").unwrap(),
                        vec![],
                    ),
                ),
            );

            (
                Name::new(module),
                Interface {
                    module_name: ModuleName::new(
                        PackageName::new("zelkova-core").unwrap(),
                        Name::new(module),
                    ),
                    values,
                    unions,
                    opaque_unions: Default::default(),
                    infixes: HashMap::new(),
                    infix_functions: HashMap::new(),
                    arities: HashMap::new(),
                    classes: HashMap::new(),
                    instances: Vec::new(),
                    file: None,
                    incomplete: false,
                },
            )
        };
        let interfaces = HashMap::from([scalar_interface("Char"), scalar_interface("String")]);
        let env = resolved(&module_name(), &interfaces, &[])?;

        assert!(
            env.find_type(&"Char".into()).is_some(),
            "type Char not found"
        );
        assert!(
            env.find_type(&"String".into()).is_some(),
            "type String not found"
        );
        assert!(
            env.find_value(&"String.length".into()).is_some(),
            "value String.length not found"
        );
        assert!(
            env.find_value(&"length".into()).is_none(),
            "`exposing (String)` names the type, not the module's values"
        );

        Ok(())
    }

    /// A module of `zelkova-core` receives none of the eight: `Basics` cannot
    /// implicitly import `Basics`, and `Maybe` importing `Result` importing
    /// `Maybe` is the cycle `dependencies` exists to reject. `maybe`'s package is
    /// how `new_environment` learns that — `module_name.package().is_core()` —
    /// rather than `new_environment` inspecting `maybe`'s own name.
    ///
    /// The five scalar names still arrive (`LANG-58`) — seeding them is a
    /// separate question from the eight default imports, and answered `yes`
    /// regardless of which module of the package this is — so `types` is not
    /// empty; it holds exactly the five and none of `Maybe`'s own.
    ///
    /// Mutation-checked by dropping the `is_core` guard in
    /// `default_imports::implicit_imports`, which puts `Maybe` in its own scope
    /// and turns the `variables` assertion red (`andThen`, `map` and
    /// `withDefault` would resolve).
    #[test]
    fn a_default_module_does_not_import_itself() -> Result<(), Vec<EnvError>> {
        let mut interfaces = HashMap::new();
        {
            let (name, iface) = maybe_interface();
            interfaces.insert(name, iface);
        }
        let maybe = ModuleName::new(PackageName::new("zelkova-core").unwrap(), "Maybe".into());
        let env = resolved(&maybe, &interfaces, &[])?;

        let mut scalar_names: Vec<&str> = env.types.keys().map(Name::as_str).collect();
        scalar_names.sort_unstable();
        assert_eq!(
            scalar_names,
            vec!["Bool", "Char", "Float", "Int", "String"],
            "types={:?}",
            env.types
        );
        assert_eq!(env.variables.len(), 0, "variables={:?}", env.variables);

        Ok(())
    }

    /// `LANG-58`: a module of a package exempt from the default imports
    /// resolves `Int`, `Float`, `Char`, `String` and `Bool` as types bound to
    /// the qualified names `scalars::SCALARS` holds, with no interface for
    /// `Basics` (or anything else) available to consult and no `import`
    /// written. Only the type names arrive: no constructor, and no value.
    ///
    /// The empty `interfaces` map is load-bearing — if seeding looked `Basics`
    /// up to resolve these names, there would be nothing here for it to find.
    ///
    /// Mutation-checked by removing the scalar-seeding block from
    /// `new_environment`: every `find_type` below returns `None` instead of
    /// `Some`.
    #[test]
    fn scalar_names_are_seeded_without_reading_any_interface() -> Result<(), Vec<EnvError>> {
        let interfaces = HashMap::new();
        let js_basics = ModuleName::new(
            PackageName::new("zelkova-core").unwrap(),
            "Js.Basics".into(),
        );
        let env = resolved(&js_basics, &interfaces, &[])?;

        let int = env.find_type(&"Int".into()).expect("Int should be seeded");
        assert_eq!(
            int.name,
            QualName::parse(PackageName::core(), "Basics.Int").unwrap()
        );
        assert_eq!(int.arity(), 0);

        let float = env
            .find_type(&"Float".into())
            .expect("Float should be seeded");
        assert_eq!(
            float.name,
            QualName::parse(PackageName::core(), "Basics.Float").unwrap()
        );

        let bool_ = env
            .find_type(&"Bool".into())
            .expect("Bool should be seeded");
        assert_eq!(
            bool_.name,
            QualName::parse(PackageName::core(), "Basics.Bool").unwrap()
        );

        let char_ = env
            .find_type(&"Char".into())
            .expect("Char should be seeded");
        assert_eq!(
            char_.name,
            QualName::parse(PackageName::core(), "Char.Char").unwrap()
        );

        let string = env
            .find_type(&"String".into())
            .expect("String should be seeded");
        assert_eq!(
            string.name,
            QualName::parse(PackageName::core(), "String.String").unwrap()
        );

        // Type names only: no constructor and no value comes with them.
        assert!(
            env.find_type_constructor(&"True".into()).is_none(),
            "no constructor should be seeded for Bool"
        );
        assert!(
            env.find_value(&"True".into()).is_none(),
            "no value should be seeded for Bool"
        );
        assert_eq!(env.variables.len(), 0, "variables={:?}", env.variables);
        assert_eq!(
            env.constructors.len(),
            0,
            "constructors={:?}",
            env.constructors
        );

        Ok(())
    }

    /// A written `import` of a default module replaces the implicit one, rather
    /// than registering every name twice and making each *use* of one ambiguous.
    ///
    /// Mutation-checked by dropping the `written.iter().any(..)` filter in
    /// `default_imports::implicit_imports`: `Maybe.map` becomes
    /// `ValueType::Foreigns` and the assertion below goes red.
    #[test]
    fn a_written_default_import_is_not_registered_twice() -> Result<(), Vec<EnvError>> {
        let mut interfaces = HashMap::new();
        {
            let (name, iface) = maybe_interface();
            interfaces.insert(name, iface);
        }
        let imports = vec![import("Maybe".into(), None, exposing_open())];
        let env = resolved(&module_name(), &interfaces, &imports)?;

        match env.find_value(&"Maybe.map".into()) {
            Some(ValueType::Foreign(..)) => (),
            other => panic!("expected one candidate for `Maybe.map`, got {:?}", other),
        }
        match env.find_value(&"map".into()) {
            Some(ValueType::Foreign(..)) => (),
            other => panic!("expected one candidate for `map`, got {:?}", other),
        }

        Ok(())
    }

    #[test]
    fn new_import_open() -> Result<(), Vec<EnvError>> {
        let imports = vec![import("Maybe".into(), None, exposing_open())];
        let mut interfaces = HashMap::new();
        {
            let (name, iface) = maybe_interface();
            interfaces.insert(name, iface);
        }
        let env = resolved(&module_name(), &interfaces, &imports)?;

        // Assert we have the expected
        assert!(
            env.find_value(&"andThen".into()).is_some(),
            "value andThen not found"
        );
        assert!(
            env.find_value(&"map".into()).is_some(),
            "value map not found"
        );
        assert!(
            env.find_value(&"withDefault".into()).is_some(),
            "value withDefault not found"
        );

        assert!(
            env.find_value(&"Maybe.andThen".into()).is_some(),
            "value Maybe.andThen not found"
        );
        assert!(
            env.find_value(&"Maybe.map".into()).is_some(),
            "value Maybe.map not found"
        );
        assert!(
            env.find_value(&"Maybe.withDefault".into()).is_some(),
            "value Maybe.withDefault not found"
        );

        assert!(
            env.find_type(&"Maybe".into()).is_some(),
            "type Maybe not found"
        );

        assert!(
            env.find_type_constructor(&"Maybe.Just".into()).is_some(),
            "type constructor Maybe.Just not found"
        );
        assert!(
            env.find_type_constructor(&"Maybe.Nothing".into()).is_some(),
            "type constructor Maybe.Nothing not found"
        );
        assert!(
            env.find_type_constructor(&"Just".into()).is_some(),
            "type constructor Just not found"
        );
        assert!(
            env.find_type_constructor(&"Nothing".into()).is_some(),
            "type constructor Nothing not found"
        );

        // Make sure we don't have more than what is expected
        assert_eq!(env.infixes.len(), 0, "infixes={:?}", env.infixes);
        assert_eq!(env.types.len(), 1 + 1, "types={:?}", env.types); // qual + explicit
        assert_eq!(
            env.constructors.len(),
            4,
            "constructors:{:#?}",
            env.constructors
        );
        assert_eq!(env.variables.len(), 3 + 3, "variables={:?}", env.variables); // qual + explicit

        Ok(())
    }

    #[test]
    fn new_import_values() -> Result<(), Vec<EnvError>> {
        let imports = vec![import(
            "Maybe".into(),
            None,
            exposing_explicit(vec![
                parser::Exposed::bare(parser::ExposedKind::Upper(
                    "Maybe".into(),
                    parser::Privacy::Private,
                )),
                parser::Exposed::bare(parser::ExposedKind::Lower("andThen".into())),
            ]),
        )];
        let mut interfaces = HashMap::new();
        {
            let (name, iface) = maybe_interface();
            interfaces.insert(name, iface);
        }
        let env = resolved(&module_name(), &interfaces, &imports)?;

        // Lookup the expected values
        assert!(
            env.find_value(&"andThen".into()).is_some(),
            "value andThen not found"
        );

        assert!(
            env.find_value(&"Maybe.andThen".into()).is_some(),
            "value Maybe.andThen not found"
        );
        assert!(
            env.find_value(&"Maybe.map".into()).is_some(),
            "value Maybe.map not found"
        );
        assert!(
            env.find_value(&"Maybe.withDefault".into()).is_some(),
            "value Maybe.withDefault not found"
        );

        assert!(
            env.find_type(&"Maybe.Maybe".into()).is_some(),
            "type Maybe.Maybe not found"
        );
        assert!(
            env.find_type(&"Maybe".into()).is_some(),
            "type Maybe not found"
        );

        // Make sure we don't have more than what is expected
        assert_eq!(env.infixes.len(), 0, "infixes={:?}", env.infixes);
        assert_eq!(env.types.len(), 1 + 1, "types={:?}", env.types); // qual + explicit
        assert_eq!(
            env.constructors.len(),
            2,
            "constructors:{:?}",
            env.constructors
        );
        assert_eq!(
            env.variables.len(),
            3 + 1, // qual + explicit
            "variables={:?}",
            env.variables.keys()
        );

        Ok(())
    }

    #[test]
    fn new_import_type_with_constructors() -> Result<(), Vec<EnvError>> {
        let imports = vec![import(
            "Maybe".into(),
            None,
            exposing_explicit(vec![parser::Exposed::bare(parser::ExposedKind::Upper(
                "Maybe".into(),
                parser::Privacy::Public,
            ))]),
        )];
        let mut interfaces = HashMap::new();
        {
            let (name, iface) = maybe_interface();
            interfaces.insert(name, iface);
        }
        let env = resolved(&module_name(), &interfaces, &imports)?;

        // Lookup the expected
        assert!(
            env.find_value(&"Maybe.andThen".into()).is_some(),
            "value Maybe.andThen not found"
        );
        assert!(
            env.find_value(&"Maybe.map".into()).is_some(),
            "value Maybe.map not found"
        );
        assert!(
            env.find_value(&"Maybe.withDefault".into()).is_some(),
            "value Maybe.withDefault not found"
        );

        assert!(
            env.find_type(&"Maybe".into()).is_some(),
            "type Maybe not found"
        );
        assert!(
            env.find_type(&"Maybe.Maybe".into()).is_some(),
            "type Maybe.Maybe not found"
        );

        assert!(
            env.find_type_constructor(&"Maybe.Just".into()).is_some(),
            "type constructor Maybe.Just not found"
        );
        assert!(
            env.find_type_constructor(&"Maybe.Nothing".into()).is_some(),
            "type constructor Maybe.Nothing not found"
        );
        assert!(
            env.find_type_constructor(&"Just".into()).is_some(),
            "type constructor Just not found"
        );
        assert!(
            env.find_type_constructor(&"Nothing".into()).is_some(),
            "type constructor Nothing not found"
        );

        // Make sure we don't have more than what is expected
        assert_eq!(env.infixes.len(), 0, "infixes={:?}", env.infixes);
        assert_eq!(env.types.len(), 2, "types={:?}", env.types); // qual + explicit
        assert_eq!(
            env.constructors.len(),
            4,
            "constructors:{:?}",
            env.constructors
        );
        assert_eq!(
            env.variables.len(),
            3,
            "variables={:?}",
            env.variables.keys()
        ); // qual + explicit

        Ok(())
    }

    #[test]
    fn new_import_type_with_constructors_and_aliases() -> Result<(), Vec<EnvError>> {
        let imports = vec![import(
            "Maybe".into(),
            Some("M".into()),
            exposing_explicit(vec![parser::Exposed::bare(parser::ExposedKind::Upper(
                "Maybe".into(),
                parser::Privacy::Public,
            ))]),
        )];
        let mut interfaces = HashMap::new();
        {
            let (name, iface) = maybe_interface();
            interfaces.insert(name, iface);
        }
        let env = resolved(&module_name(), &interfaces, &imports)?;

        // Lookup the expected
        assert!(
            env.find_value(&"M.andThen".into()).is_some(),
            "value M.andThen not found"
        );
        assert!(
            env.find_value(&"M.map".into()).is_some(),
            "value M.map not found"
        );
        assert!(
            env.find_value(&"M.withDefault".into()).is_some(),
            "value M.withDefault not found"
        );

        assert!(
            env.find_type(&"Maybe".into()).is_some(),
            "type Maybe not found"
        );
        assert!(
            env.find_type(&"M.Maybe".into()).is_some(),
            "type M.Maybe not found"
        );

        assert!(
            env.find_type_constructor(&"M.Just".into()).is_some(),
            "type constructor M.Just not found"
        );
        assert!(
            env.find_type_constructor(&"M.Nothing".into()).is_some(),
            "type constructor M.Nothing not found"
        );

        assert!(
            env.find_type_constructor(&"Just".into()).is_some(),
            "type constructor Just not found"
        );
        assert!(
            env.find_type_constructor(&"Nothing".into()).is_some(),
            "type constructor Nothing not found"
        );

        // Make sure we don't have more than what is expected
        assert_eq!(env.infixes.len(), 0, "infixes={:?}", env.infixes);
        assert_eq!(env.types.len(), 2, "types={:?}", env.types);
        assert_eq!(
            env.constructors.len(),
            4,
            "constructors:{:?}",
            env.constructors
        );
        assert_eq!(
            env.variables.len(),
            3,
            "variables={:?}",
            env.variables.keys()
        );

        Ok(())
    }

    // ── ERR-7: "did you mean …?" suggestions ────────────────────────────────
    //
    // These hand-build every `Import`/`Exposed` with `NodeSpan::none()` (see the
    // `import`/`exposing_*` helpers above), so `EnvError::labels` — which needs a
    // real span to attach a caret to — renders nothing for them; that path is
    // covered instead by `crates/zelkova-compiler/tests/canonical.rs`, which goes through the
    // parser and so has real spans. These assert directly on the `Option<Name>`
    // suggestion field each variant now carries.

    /// A minimal interface with one infix, `maybe_interface` has none — needed to
    /// exercise `EnvError::InfixNotFound`'s suggestion.
    fn ops_interface() -> (Name, Interface) {
        let mut infixes = HashMap::new();
        infixes.insert(
            "plus".into(),
            Infix {
                associativity: Associativity::Left,
                precedence: 6,
                function_name: "add".into(),
                span: NodeSpan::none(),
            },
        );

        let interface = Interface {
            module_name: ModuleName::new(PackageName::new("test-project").unwrap(), "Ops".into()),
            values: HashMap::new(),
            unions: HashMap::new(),
            opaque_unions: Default::default(),
            infixes,
            infix_functions: HashMap::new(),
            arities: HashMap::new(),
            classes: HashMap::new(),
            instances: Vec::new(),
            file: None,
            incomplete: false,
        };

        ("Ops".into(), interface)
    }

    /// Neutralising the `suggest` call in the `InterfaceNotFound` arm of
    /// `process_import` (passing `None` instead) turns this red: `suggestion`
    /// becomes `None` where the test expects `Some("Maybe")`.
    #[test]
    fn unknown_module_suggests_a_near_miss() {
        let imports = vec![import("Mabye".into(), None, exposing_open())];
        let mut interfaces = HashMap::new();
        {
            let (name, iface) = maybe_interface();
            interfaces.insert(name, iface);
        }

        let errors = resolved(&module_name(), &interfaces, &imports)
            .expect_err("an unknown module should not resolve");
        assert_eq!(errors.len(), 1, "got {:?}", errors);

        match &errors[0] {
            EnvError::InterfaceNotFound(name, _, suggestion) => {
                assert_eq!(name, &Name::from("Mabye"));
                assert_eq!(suggestion, &Some(Name::from("Maybe")));
            }
            other => panic!("expected InterfaceNotFound, got {:?}", other),
        }
    }

    /// A module name resembling nothing among the known interfaces gets no
    /// suggestion — a bad one would send the reader to check an unrelated import.
    #[test]
    fn unrelated_unknown_module_has_no_suggestion() {
        let imports = vec![import("Zzzzzzzzzzzz".into(), None, exposing_open())];
        let mut interfaces = HashMap::new();
        {
            let (name, iface) = maybe_interface();
            interfaces.insert(name, iface);
        }

        let errors = resolved(&module_name(), &interfaces, &imports)
            .expect_err("an unknown module should not resolve");
        assert_eq!(errors.len(), 1, "got {:?}", errors);

        match &errors[0] {
            EnvError::InterfaceNotFound(_, _, suggestion) => {
                assert_eq!(suggestion, &None);
            }
            other => panic!("expected InterfaceNotFound, got {:?}", other),
        }
    }

    /// A dotted module name — `Js.Basics`, `Js.Utils` and `Js.Bitwise` all exist
    /// in `std/core/src` today — is one identifier, not a module prefix plus a
    /// local part. Routing this through `suggest_name` would compare only the
    /// segment after the last `.` and only against candidates sharing the prefix
    /// exactly, so a typo anywhere else, or a dropped dot, would get nothing.
    /// All three of these are one edit from `Js.Basics`.
    #[test]
    fn unknown_dotted_module_suggests_on_the_whole_name() {
        let mut interfaces = HashMap::new();
        {
            let (_, iface) = maybe_interface();
            interfaces.insert("Js.Basics".into(), iface);
        }

        // `Js.Basicz` shares the prefix, `Jz.Basics` does not, and `JsBasics` has
        // no prefix at all — the last is the likeliest typo of the three.
        for typo in ["Js.Basicz", "Jz.Basics", "JsBasics"] {
            let imports = vec![import(typo.into(), None, exposing_open())];
            let errors = resolved(&module_name(), &interfaces, &imports)
                .expect_err("an unknown module should not resolve");
            assert_eq!(errors.len(), 1, "got {:?}", errors);

            match &errors[0] {
                EnvError::InterfaceNotFound(name, _, suggestion) => {
                    assert_eq!(name, &Name::from(typo));
                    assert_eq!(
                        suggestion,
                        &Some(Name::from("Js.Basics")),
                        "no suggestion for `{}`",
                        typo
                    );
                }
                other => panic!("expected InterfaceNotFound, got {:?}", other),
            }
        }
    }

    /// The `Explicit` exposing arm wraps whatever `collect_accumulate` returns in
    /// `EnvError::Multiple`, even for a single failing entry — see
    /// `process_import`'s last statement — so the `UnionNotFound` this produces is
    /// nested one level deeper than `InterfaceNotFound`'s.
    ///
    /// Neutralising the `suggest_name` call in the `Upper(.., Public)` arm of
    /// `process_import` (passing `None` instead) turns this red.
    #[test]
    fn unknown_exposed_type_suggests_a_near_miss() {
        let imports = vec![import(
            "Maybe".into(),
            None,
            exposing_explicit(vec![parser::Exposed::bare(parser::ExposedKind::Upper(
                "Mayeb".into(),
                parser::Privacy::Public,
            ))]),
        )];
        let mut interfaces = HashMap::new();
        {
            let (name, iface) = maybe_interface();
            interfaces.insert(name, iface);
        }

        let errors = resolved(&module_name(), &interfaces, &imports)
            .expect_err("an unknown exposed type should not resolve");
        assert_eq!(errors.len(), 1, "got {:?}", errors);

        let inner = match &errors[0] {
            EnvError::Multiple(inner) => inner,
            other => panic!("expected Multiple, got {:?}", other),
        };
        assert_eq!(inner.len(), 1, "got {:?}", inner);

        match &inner[0] {
            EnvError::UnionNotFound(name, _, suggestion) => {
                assert_eq!(name, &Name::from("Mayeb"));
                assert_eq!(suggestion, &Some(Name::from("Maybe")));
            }
            other => panic!("expected UnionNotFound, got {:?}", other),
        }
    }

    /// A bare `Mayeb` entry is checked against the interface exactly as `Mayeb(..)`
    /// is: the two differ in whether the constructors come along, not in whether the
    /// type has to exist, so both report the same `UnionNotFound` with the same
    /// suggestion (`BUG-16`).
    ///
    /// Mutation-checked by restoring the arm's old body — reading the variables with
    /// `interface.unions.get(type_name).map(..).unwrap_or_default()` and inserting
    /// unconditionally: the import then succeeds and `expect_err` panics.
    #[test]
    fn unknown_opaque_exposed_type_suggests_a_near_miss() {
        let imports = vec![import(
            "Maybe".into(),
            None,
            exposing_explicit(vec![parser::Exposed::bare(parser::ExposedKind::Upper(
                "Mayeb".into(),
                parser::Privacy::Private,
            ))]),
        )];
        let mut interfaces = HashMap::new();
        {
            let (name, iface) = maybe_interface();
            interfaces.insert(name, iface);
        }

        let errors = resolved(&module_name(), &interfaces, &imports)
            .expect_err("an unknown opaquely exposed type should not resolve");
        assert_eq!(errors.len(), 1, "got {:?}", errors);

        let inner = match &errors[0] {
            EnvError::Multiple(inner) => inner,
            other => panic!("expected Multiple, got {:?}", other),
        };
        assert_eq!(inner.len(), 1, "got {:?}", inner);

        match &inner[0] {
            EnvError::UnionNotFound(name, _, suggestion) => {
                assert_eq!(name, &Name::from("Mayeb"));
                assert_eq!(suggestion, &Some(Name::from("Maybe")));
            }
            other => panic!("expected UnionNotFound, got {:?}", other),
        }
    }

    /// A `Maybe(..)` entry against an interface that lists `Maybe` in
    /// `opaque_unions` is `ConstructorsNotExposed`, nested in `Multiple` like the
    /// other entry errors, and carries the module name as the `import` wrote it.
    ///
    /// Mutation-checked by deleting the `opaque_unions.contains` early return in
    /// the `Upper(.., Public)` arm of `process_import`: the import then succeeds
    /// and `expect_err` panics.
    #[test]
    fn constructor_entry_for_an_opaque_type_is_rejected() {
        use zelkova_syntax::position::BytePos;
        let entry_span = NodeSpan::new(BytePos(20), BytePos(30));
        let imports = vec![import(
            "Maybe".into(),
            None,
            exposing_explicit(vec![parser::Exposed::new(
                entry_span,
                parser::ExposedKind::Upper("Maybe".into(), parser::Privacy::Public),
            )]),
        )];
        let mut interfaces = HashMap::new();
        {
            let (name, mut iface) = maybe_interface();
            if let Some(union) = iface.unions.get_mut(&name) {
                union.variants.clear();
            }
            iface.opaque_unions.insert(name.clone());
            interfaces.insert(name, iface);
        }

        let errors = resolved(&module_name(), &interfaces, &imports)
            .expect_err("constructors the module does not expose should not resolve");
        assert_eq!(errors.len(), 1, "got {:?}", errors);

        let inner = match &errors[0] {
            EnvError::Multiple(inner) => inner,
            other => panic!("expected Multiple, got {:?}", other),
        };
        assert_eq!(inner.len(), 1, "got {:?}", inner);

        match &inner[0] {
            EnvError::ConstructorsNotExposed(name, module, span) => {
                assert_eq!(name, &Name::from("Maybe"));
                assert_eq!(module, &Name::from("Maybe"));
                assert_eq!(span.span(), entry_span.span());
            }
            other => panic!("expected ConstructorsNotExposed, got {:?}", other),
        }
    }

    /// Same nesting as the type case above, for `EnvError::InfixNotFound`.
    ///
    /// Neutralising the `suggest_name` call in the `Operator` arm of
    /// `process_import` (passing `None` instead) turns this red.
    #[test]
    fn unknown_exposed_infix_suggests_a_near_miss() {
        let imports = vec![import(
            "Ops".into(),
            None,
            exposing_explicit(vec![parser::Exposed::bare(parser::ExposedKind::Operator(
                "pluss".into(),
            ))]),
        )];
        let mut interfaces = HashMap::new();
        {
            let (name, iface) = ops_interface();
            interfaces.insert(name, iface);
        }

        let errors = resolved(&module_name(), &interfaces, &imports)
            .expect_err("an unknown exposed infix should not resolve");
        assert_eq!(errors.len(), 1, "got {:?}", errors);

        let inner = match &errors[0] {
            EnvError::Multiple(inner) => inner,
            other => panic!("expected Multiple, got {:?}", other),
        };
        assert_eq!(inner.len(), 1, "got {:?}", inner);

        match &inner[0] {
            EnvError::InfixNotFound(name, _, suggestion) => {
                assert_eq!(name, &Name::from("pluss"));
                assert_eq!(suggestion, &Some(Name::from("plus")));
            }
            other => panic!("expected InfixNotFound, got {:?}", other),
        }
    }
}